Module resolve 

Shared resolution step — style packs, fonts, and contrast math.

This module is the single owner of token semantics for BOTH render targets: render_html (websites) consumes these functions for its CSS emission, and render_native projects the same resolved values across the FFI as a NativeTheme. The 0025 style-pack property — “preview cannot drift from the pack” — holds only because resolution happens exactly once, here, in Rust. Never reimplement pack→value mapping in Swift/Kotlin/JS.

The --ws-* token contract (style-pack rendering annex v0): packs re-set ONLY these tokens; packs change visuals, never layout. Defaults are the “Surf Simple” pack and must stay in lockstep with assets/surfdoc.css :root (drift-tested in render_html).

The pack registry here mirrors the production injection tables in repos/surf frontend/src/sites/container.rs (STYLE_PACKS). The container remains the web injection point; this module is the canonical semantic owner for native targets and any future consolidation.

Structs

ResolvedTheme

A document’s fully resolved presentation: pack tokens with the pack applied, accent + derived WCAG colors, and font stacks. Computed once; render_html emits it as CSS variables, render_native ships it across the FFI as NativeTheme.

WsTokens

The resolved --ws-* token values for one style pack. Values are the exact CSS strings the web renderer emits; native targets parse the px fields into numeric form via NativeTheme.

Constants

COMIC_TOKENS

Comic — the dramatic second voice that proves the contract: tight radii, comic-thick borders, hard-offset panel shadows, flat hero ink, a light diagonal hatch texture. Values mirror the comic pack in the surf container’s STYLE_PACKS.

DEFAULT_ACCENT

Platform default accent (--accent in assets/surfdoc.css :root).

DEFAULT_STYLE_PACK

Default style-pack key. Mirrors DEFAULT_STYLE_PACK in the surf container (0025 DEFAULT).

SURF_SIMPLE_TOKENS

Surf Simple — the zero-pack default. MUST stay byte-equal to the :root declarations in assets/surfdoc.css (drift-tested below and in render_html); injecting nothing on web yields exactly these values.

Functions

accent_ink_color

Derive an accent ink — the accent adjusted until it reads as normal TEXT at WCAG AA (≥ 4.5:1) against the theme’s surfaces (BR-SITE-A11Y).

contrast_ratio

WCAG 2.x contrast ratio between two hex colors (1.0..=21.0). Unparseable input yields 0.0 (so “is this AA?” checks fail loudly).

resolve_style_pack

Resolve a style-pack key to its token set. Unknown keys (DB drift, forward-compat) fall back to Surf Simple — a stale pack value can never break a render.

resolve_theme

Resolve a theme from site-level inputs. All inputs optional; None yields the platform defaults (Surf Simple pack, #2563eb accent, system fonts).