Module runtime_options

Expand description

Runtime option and theming mutation API with atomic validation (bd-2vr05.13.5).

§Why this exists

Production embedders of the FrankenTermJS web surface need to reconfigure a live terminal without re-instantiating it — exactly the term.options mutation surface that real xterm.js integrators depend on (cursor style, scrollback depth, screen-reader mode, renderer backend, theme palette, …).

This module is the single host-agnostic source of truth for that option schema and its mutation semantics. It is pure and deterministic: identical (current options, patch, capability profile) inputs always produce an identical RuntimeOptionUpdate outcome and an identical structured-log serialisation, so a fixed capability profile yields reproducible behaviour across the rendering backends introduced by bd-2vr05.8.1.

 JSON patch ──parse──> RuntimeOptionPatch ─┐
 (or typed builder) ───────────────────────┤
                                           ├─ apply_patch(caps) ─┬─ Applied  ─> field diffs + repaint/reinit flags
 OptionCapabilityProfile ──────────────────┘  (atomic: all or    └─ Rejected ─> per-field errors, options UNCHANGED
                                                nothing commits)

§Atomicity & rollback

RuntimeOptions::apply_patch validates the entire candidate state (schema range checks + capability gating) before committing anything. If any field is invalid it returns a RuntimeOptionUpdate carrying every offending field’s error and leaves self byte-for-byte unchanged — there is no partial application. On success it commits atomically and reports the exact set of changed fields plus the renderer/engine synchronisation that the host must perform (RuntimeOptionUpdate::requires_repaint / RuntimeOptionUpdate::requires_renderer_reinit).

§Capability / profile gating

A value can be schema-valid yet unsupported by the active engine: e.g. a WebGpu renderer request when the host only advertises Canvas, or a scrollback depth beyond the host’s memory budget. Those are reported as gating errors distinct from out-of-range schema errors, so a host can tell “you asked for something impossible here” apart from “you asked for nonsense”.

The colour swaps themselves stay host-side (browser CSS / canvas), keeping this module free of any dependency on ftui-style — the same layering rule the accessibility preference policies follow.

Structs§

OptionCapabilityProfile: What the active rendering engine / host advertises as supported. A schema-valid option can still be gated against this profile.
OptionFieldChange: A single field that changed in a committed update.
RuntimeOptionPatch: A sparse patch: every field is independently Some(_) to mutate or None to leave untouched. Mirrors assigning to a subset of xterm.js term.options.
RuntimeOptionUpdate: The outcome of an RuntimeOptions::apply_patch call.
RuntimeOptions: The complete, validated runtime option state.
ThemeColor: A packed 0xRRGGBBAA theme colour. Host-agnostic: the actual swap is applied by the browser/canvas, this is pure intent.
ThemePalette: The full theme palette: anchor colours plus the 16 ANSI entries.

Enums§

CursorStyle: Terminal cursor presentation style (parity with xterm.js cursorStyle).
GatingDetail: Detail for a capability-gating rejection.
RendererType: Rendering backend selection (parity with xterm.js renderer addons, plus the WebGPU-primary backend introduced by bd-2vr05.8.1).
RuntimeOptionError: A single, explicit option validation/gating failure.

Constants§

MAX_CONTRAST_RATIO_X100: Maximum WCAG contrast ratio expressible by the option, ×100 (21:1, the largest ratio achievable between sRGB black and white).
MAX_TAB_WIDTH: Maximum supported tab stop width, in columns.
MIN_CONTRAST_RATIO_X100: Minimum WCAG contrast ratio expressible by the option, ×100 (1.0:1).
MIN_TAB_WIDTH: Minimum supported tab stop width, in columns.
SCROLLBACK_HARD_MAX: Hard ceiling on scrollback retention, independent of the host’s advertised budget. Guards against absurd payloads even when a host reports a very large max_scrollback_lines.