Scan-status seam: camera lifecycle + permission events, delivered by the platform through dispatch() as "scanstatus:". Statuses: "scanning" (camera live), "permission" (a Scanner wants a not-yet-granted camera), "granted"/"denied" (the OS permission prompt's outcome), "error:" (camera failed to start). GLOBAL, not per-path, because permission outcomes arrive from the platform's Activity/shell when no Scanner view need be alive (the app may have swapped the scanner out for a permission pane) — such events carry an empty path.

Width at/below which the UI enters its "Narrow" responsive layout (matches the shipped Vortex web shell's breakpoint). Width-driven and platform- independent — distinct from the @Desktop/@Web/@Mobile platform states.

Upper bound of the "Medium" responsive band: the range above Narrow up to this width (kNarrowBreakpoint < px <= kMediumBreakpoint). In this band the layout keeps its master+detail split but collapses to the detail alone when a row is selected — room for one comfortable pane, not two. Set just above a near-square unfolded foldable (~852dp in either orientation) so it lands in this band, while genuinely wide screens (desktop, large/landscape tablets) stay two-paned. Narrow and Medium are mutually exclusive (a width is in at most one band).

Accumulated scroll distance (px) past which on_scroll() flips the controls' hidden state. Matches the legacy Android 30dp threshold.

Default mobile auto-scale factors (see apply_mobile_scale). Icons get the larger bump (matches the hand-authored "@Mobile" icon sizes the shipped styles used before auto-scale existed, ~1.3–1.7×, clustered near 1.5); text gets a gentler one, since fonts at the icon factor read a touch large. The metric factor (spacing, margins, padding, box sizes, radii, border) matches the font bump so layout geometry scales in step with the text it frames.

Load styles + themes (directories of .json) and activate a theme by id. stylesPath is the framework's library styles root; it must contain widgets/ (loaded under the "Vortex" namespace) and mounts/ (the global Theme node). appStyleDirs are extra (app-owned) style dirs loaded additively ON TOP of the library set — included AFTER it (so app styles can reference/extend library styles with a qualified base, e.g. an app window inheriting Vortex/Main Window) but BEFORE theme activation (so their Theme/... links resolve against the global Theme mount). Order matters: the library set must load first because a base must be in the same set or a set loaded earlier. Returns false if the theme could not be activated.

Structure: apply a top-level Layers style as the root of the UI tree.

Theming: the active theme's id (e.g. "Dark"). Empty until init() succeeds.

Switch the active theme by id. Copies its palette onto the Theme mount so the next build_render_tree() carries it. Returns false if no theme with that id is loaded (active theme unchanged). Reconcilers just re-emit.

Load a theme from a JSON string and add it to the controller at runtime — the same theme JSON the bridges feed at init, now ingestible after launch (a user-loaded custom theme). Returns the new theme's display id ("Name (publisher)"), or "" if the JSON couldn't be parsed into a theme. Re-adding an already-loaded id replaces it. The next build_render_tree() picks it up (e.g. the theme picker shows a new button). The SOURCE of the JSON (a file picker, a persisted handle, a future online network) is a platform-layer concern — the core only ingests the string. [Slice 1]

Remove a loaded theme by display id. If it was the active theme, switches to another loaded theme first so the "Theme" proxy stops reflecting the removed palette. No-op (returns false) if the id isn't loaded or it's the only theme left. [Slice 1]

The loaded themes, keyed by display id — the registry the theme picker (generated buttons) and the static-web emitter read. Theming is a Vortex feature now: theme data lives here, not in the Layers controller.

The active theme's parsed data (nullptr before init() succeeds, or if the active id somehow isn't loaded). Backs the render tree's active-theme binds (Markdown code surfaces, the Theme Bar) and the static-web palette emission.

Register a callback fired whenever the active theme actually changes — on the dispatch-driven switch (a theme-button click), an explicit set_active_theme(), and once during init() (including when init() falls back). The platform layer wires this to its native store (desktop QSettings, web localStorage, Android SharedPreferences) so the selection survives restarts; the core stays storage-agnostic. The argument is the theme's display id, suitable to feed straight back into init() next launch. Set this before init() so an init-time fallback gets persisted too.

Runtime overlay: bind content (text) to a node by its style path.

Read back the bound text overlay ("" when the path has no bind). The programmatic mirror of bind_text — headless tests assert on it (e.g. Docuriser's lint status line) without building a render tree.

Runtime overlay: bind a media Source (Image/Video node) to a node by its style path — the dynamic analog of the static "Source" attribute, parallel to bind_text. App code uses this to point a node at a per-instance media URL (or local path) resolved at runtime, e.g. a profile avatar. An empty url clears the override so the node falls back to its authored Source (its placeholder). The reconcilers re-source the widget when the resolved Source changes (web sets img.src; desktop calls ImageWidget::setSource).

Runtime overlay: bind a Link node's target URL by its style path — the dynamic analog of the static "Href" attribute, parallel to bind_text. Consumed by the static-web emitter (the emitted ); runtime reconcilers ignore hrefs. An empty url clears the override so the node falls back to its authored Href.

Observe a list key: fn fires on every set_list() for that key with the fresh entries. This is how portable shell wiring reacts to PLATFORM-fed list state it cannot compute itself — e.g. the theme-directories dialog swaps its empty-state guidance for the source rows when a platform feeds "themeSources". One observer per key (a re-register replaces); it does not fire on registration — the registrant sets the initial face itself.

Handler for a generated row's action button (Intent "list:"): the click delivers (list key, row id, action) so the platform can act (e.g. remove a theme directory) and re-feed the list with set_list. [Slice 2] This GLOBAL form is the fallback for any list key without a per-key handler (below) — the platform layer installs it to forward every list action to its native code (web/Android bridges) or to handle a platform-owned list (desktop theme directories).

Per-key form: register a handler for ONE list key. Portable app code (build_app) uses this for its own lists (e.g. "nodes", "leftTabs") so a click is handled in the C++ core on every platform, while the global handler the platform installs keeps serving the rest (e.g. "themeSources"). The two no longer clobber each other regardless of install order, since dispatch() consults the per-key map first.

Async HTTP seam. The platform shell injects a transport once at startup; the app core (e.g. sign-in) builds an HttpRequest and calls http(), and the transport delivers the HttpResponse back on the UI thread. The SAME app flow runs on every platform — only the injected handler differs (the networking analog of the per-platform theme-source layer). [Slice A]

Issue an async request via the installed handler. If none is installed (a headless/unit context), the callback fires immediately with a transport error so app code degrades safely instead of hanging on a reply that never comes.

File pick + upload seam (see UploadHandler). The platform opens a native picker filtered by accept, multipart-uploads the chosen file (HTTP verb method) under form field fieldName to url with headers, and delivers the JSON reply. Injected once at startup, like set_http_handler.

Pick a file and upload it via the installed handler. method is the HTTP verb ("POST" for attachments, "PUT" for a profile picture). With no handler installed (a headless/unit context), the callback fires immediately with an error so app code degrades safely instead of hanging on a reply that never comes.

Local path-pick seam (see PickHandler). The platform opens its native file dialog per the request and delivers the chosen path. Injected once at startup, like set_upload_handler. With no handler installed (headless/unit contexts, web/Android shells), the callback fires immediately with "" — the cancel shape — so app code degrades safely.

External-URL seam (see OpenUrlHandler). The platform shell installs the browser-open transport once at startup; app code calls open_url() to hand a URL off-app. With no handler installed (a headless/unit context) the call is a silent no-op, so app code degrades safely instead of faulting.

Same-page navigation seam (reuses OpenUrlHandler's signature): the analog of open_url() for "redirect away and come back" flows — Stripe Checkout, the billing portal — where the URL is opened from an ASYNC callback (after a server round-trip), outside the click's user gesture. On web a new tab there would be popup-blocked, so the web shell installs a handler that navigates the current page instead (location.assign). Desktop/Android have no separate "current tab" — they install no handler, so navigate_url() falls back to open_url() (system browser / ACTION_VIEW). Headless (neither installed) → silent no-op, like open_url().

System-back seam (see BackHandler). The app installs its back chain once in build_app; the platform shell drives it — navigate_back() on the real press, back_captures() as the eager side-effect-free peek. Both report false with no handler installed, so a platform that never wires back (desktop/web today) and an app that never installs a chain both keep the system's default (back leaves the app).

Clipboard seam (see CopyTextHandler). Call from a click handler — the web implementation needs the user gesture. No handler → silent no-op, like open_url().

Save-text seam (see SaveTextHandler). With no handler installed (headless/unit contexts) the callback fires immediately with false — the cancel shape — so app code degrades safely.

Subprocess seam (see RunProcessHandler). With no handler installed (headless/unit contexts, sandboxed shells) on_exit fires immediately with -1 — the failed-to-start shape — so app code degrades safely instead of waiting on an exit that never comes.

In-app purchase seam (see PurchaseHandler). The platform shell installs the store transport at startup; app code calls start_purchase() to launch the native purchase flow. With no handler installed (desktop/web/headless) the callback fires immediately reporting no handler, so app code degrades safely instead of hanging on a reply that never comes.

Purchase-recovery seam (see QueryPurchasesHandler). Lists owned-but- unverified tokens to replay on launch. With no handler installed the callback reports an empty list (nothing to recover), so app code degrades safely.

One-shot timer seam (the time analog of set_http_handler): the platform shell injects a scheduler once at startup. App code calls after() to defer work onto the UI thread.

Run cb after ms milliseconds via the installed timer. If none is installed (a headless/unit context), the callback is dropped rather than run synchronously — deferred work in such a context is a no-op, not a reentrant surprise. Drives the search debounce.

Post-to-UI-thread seam (see PostHandler). Safe to call from a worker thread; the transport queues cb onto the UI thread. With no handler installed (a headless/unit context) the callback is dropped, like after(): running it inline WOULD be a data race — the whole point of the seam is that the calling thread must not touch the app.

Re-render seam. A state change driven by an async completion (account data arriving from an http() reply) lands OUTSIDE the platform's click/resize round-trips, which already repaint inline. The reconciler installs this hook to its patch-apply path so such completions can ask for a repaint; request_render() invokes it (no-op if unset). [Slice A]

Platform -> app config channel. The platform shell sets values BEFORE build_app (e.g. the web shell passes the page origin as "base_url" so the app's API base matches where it's served from); app code reads them via env(). A generic string map — unset keys read as "". [Slice B]

App -> platform persistence channel — the WRITE side, paired with env() as the read side. App code calls store(key, value) to persist a small string (e.g. a session's refresh token); the platform shell writes it to native storage (QSettings / localStorage / SharedPreferences) and feeds it back via set_env() at the next launch, so the app reads it through env(). An empty value clears the key. Generic — the app owns the key + its format. store() also updates the live env() map, so a key written this session reads back without a relaunch (e.g. a self-custody key envelope imported and then unlocked in the same run). [Slice D]

Runtime overlay: show/hide a node (and its subtree). Hidden nodes drop out of the render tree entirely (the diff then emits Remove/Insert).

Whether a node is currently hidden (handy for toggling).

Runtime overlay: bind a click handler to a node by its style path.

Editor read-back: the live value of an Editor node, pushed in by the reconciler as the user types (see set_editor_text) and read by the app when it needs the field's contents (e.g. on a Sign In click). The reconciler owns the on-screen value — the core only retains a copy here, and NEVER feeds it back into the render tree, so a re-render can't clobber what the user typed.

Whether a live value has ever been recorded for an Editor path (typed by the user or seeded via set_editor_text). Lets a reconciler distinguish a field the core knows the value of from one it has never tracked, so a widget rebuilt after its subtree was hidden can be re-seeded with the retained value rather than the clean bound default (which would silently drop unsaved edits). "" is a legitimate value, so presence — not emptiness — is the signal.

Editor value PUSH: app code sets what the Editor at path displays (e.g. clearing a link field after its Add stages the URL). set_editor_text alone can't do this — it only updates the retained read-back copy, and a bind_text rebind only reaches the widget when the BOUND text changes, which a clear-to-empty on a field whose bound default is already empty never does. So the push rides the patch pipeline: the next render_patches() emits an EditorValue patch (after the diff, so it lands on a widget the same render may have just rebuilt) and each reconciler sets the displayed value programmatically — no input handler fires, matching a bind_text seed. The read-back copy is updated here so editor_text() agrees with the screen immediately.

Editor change seam: register a handler fired (with the field's new value) each time the user edits the Editor at path. Pairs with editor_text() — that's the pull (read on a click, e.g. Sign In); this is the push, for search-as-you-type. The reconciler already routes every keystroke through dispatch() as "input:" (web/desktop/Android all share that seam), so no reconciler change is needed. App code typically debounces in the handler via after(). Mirrors bind_click's per-path map.

Scan-result seam: register a handler fired (with the decoded payload) each time the platform's Scanner node at path reads a QR code — the camera analog of set_editor_input_handler. The mobile reconciler routes every decode through dispatch() as "scan:" (the payload is the whole remainder, so it may itself contain ':'), so no extra bridge export is needed. Platforms without a scanning reconciler simply never dispatch it.

Camera-permission request seam (core -> platform, fire-and-forget like open_url): app code — e.g. a "Grant camera access" button — asks the platform to (re-)run its runtime camera permission prompt. The outcome returns asynchronously as a "granted"/"denied" scan-status event. With no handler installed (desktop/web/headless) the call is a silent no-op.

Checkbox read-back: whether the Checkbox node at path is currently checked. A checkbox click auto-toggles the node's "Checked" Layers state (see dispatch), so the checked value IS the presence of that state — read it here (e.g. from a Create button's click, to gate submission). False for a never-touched checkbox or a non-checkbox path.

Set a Checkbox node's checked value explicitly (e.g. clearing a form on open). Adds/removes the "Checked" state to match on — the same state a click toggles — so the box re-styles and checkbox_checked() agrees. A bound click handler is NOT invoked (this is a programmatic set, not a tap).

Combo-box option feed: the choices the ComboBox node at path offers, in display order (each option's id keys the selection; its label is what the user sees). Replaces any prior set — re-render to reflect it: the options ride the render tree (they're app DATA, like a Text node's text), unlike an Editor's live value. If the recorded selection is no longer among the new ids (or none was ever recorded), it resets to the first option's id ("" when options is empty) — so combo_selected() always names a choice the widget actually offers.

Combo-box read-back: the selected option's id — the first option until a pick or an explicit set changes it (see set_combo_options). "" for a path with no options fed.

Set a ComboBox node's selection explicitly (e.g. seeding a form on open). Ignored unless id names one of the node's fed options (feed options first), so the recorded selection can never name a choice the widget doesn't offer. A bound change handler is NOT invoked (a programmatic set, not a pick) — the set_checkbox_checked contract.

Combo change seam: register a handler fired (with the picked option's id) each time the user changes the ComboBox at path — the selection analog of set_editor_input_handler. The reconcilers route every user pick through dispatch() as "select:" (the shared seam; no extra bridge export is needed), so headless tests drive a combo the same way.

Deliver a native event into the core. A click on a generated theme button switches the active theme; otherwise the bound click handler runs.

Toggle a Layers state on a node (cascades to descendants at resolve time).

Report the current viewport width. Toggles the global "Narrow" state when crossing the breakpoint. Returns true only when the responsive state actually changed, so reconcilers re-render only at the crossing.

Report the current viewport height (px, same units the platform reports width in). No responsive bands — this feeds "Size.Height Viewport" fractions, folded into concrete heights at build time (see ResolvedStyle::heightVp). Returns true only when the height changed AND the last build actually placed a viewport-fraction node, so a plain resize with none on screen stays render-free (a desktop drag would otherwise rebuild per tick).

The last reported viewport height (0 = never reported).

Whether the "Narrow" responsive state is currently active.

Whether the "Medium" responsive band (above Narrow, up to kMediumBreakpoint) is currently active. Mutually exclusive with Narrow.

Toggle the "Maximized" global state (desktop window maximize/restore), so styles can drop the window border/corners when maximized. Returns true on an actual change, so the reconciler re-renders only on the transition.

Hide-away-on-scroll. Platforms feed raw vertical scroll deltas from their scroll containers; the core holds the portable accumulate→threshold logic (ported from the legacy Android NestedScrollConnection). dy is the change in scroll position: POSITIVE when scrolling toward the content's end (down), NEGATIVE when scrolling back toward the top. Scrolling down past the threshold hides the controls (the bottom-pinned titlebar slides off via its @ControlsHidden translateY); scrolling up past it shows them again. Engages ONLY while @Narrow (where the bar sits at the bottom) — ignored otherwise. Returns true only when the hidden state actually flipped, so the reconciler re-renders just on the transition (same contract as set_viewport_width / set_maximized).

Force the controls visible (resets the scroll accumulator). The single "show" seam: wired to a tab/content tap, a top-overscroll bounce, and (future) the mouse nearing the bottom edge. Returns true only when the controls were actually hidden and are now shown.

Whether the controls (the bottom-pinned titlebar) are currently hidden.

Declare the host platform once at startup: "Desktop", "Web", or "Mobile" (native Android/iOS). Added as a global state so platform-specific style variants (@Desktop window border/corners, @Mobile larger icons) cascade tree-wide. Orthogonal to width responsiveness (@Narrow), which still toggles dynamically — both can be active at once (a narrow phone).

Whether the host platform is mobile (the "Mobile" band set_platform declared). Lets app code branch on the native billing rail (Play on mobile, Stripe on desktop/web) without a separate platform getter — the style's @Mobile/@Desktop bands cover layout, this covers the rare C++-side platform decision.

The RUNNING BINARY's release version (SemVer, e.g. "2.0.0"), declared once at startup by the platform shell (desktop feeds it from DesktopAppConfig.appVersion, which apps fill from their CMake project(VERSION) via a compile definition). Read by the update channel (vupdate.h) to compare against a release manifest. Empty means "unversioned" (dev/headless builds) and update checks refuse to guess. Distinct from any documented project's version (Docuriser site content) — this names the executable itself.

Multipliers applied on a mobile platform (see apply_mobile_scale): one knob each for icon pixel sizes, font sizes, and the remaining pixel metrics (spacing, margins, padding, box sizes, corner radii, border thickness), instead of a "@Mobile" value on every attribute. An explicit "@Mobile" override in a style still wins for that attribute, so the factors handle the common case and styles only spell out the exceptions. Set before/independent of rendering; takes effect on the next build_render_tree(). Pass 1.0 to disable a factor. Only the "Mobile" platform is affected — Desktop/Web ignore them.

Walk the applied style's hierarchy (+ overlay + state) into a resolved render tree. Desktop consumes this in-process.

Serialized render tree for the web (WASM) and Android (JNI) reconcilers.

Diff the new render tree against the previously-emitted one and return the minimal patch list (the first call yields a single Insert of the whole root). Stateful: advances the retained "previous tree". Desktop consumes these in-process; web/Android use the JSON form.