App execution model: no app JS - components drive a curated DOM surface, the UI frame runs only framework code

[lannbot]

Provisional plan — recorded 2026-08-16 from the founding sandbox discussion. Adopted as the working app-execution model; converted to a ruling only by the checkpoints at the end. This amends the sketch in NOTES.md — App-frame sandboxing: the UI frame no longer executes an app-supplied HTML/JS bundle — it executes only framework shim code. Related: #5, #6, #7, #13; shape rules for the surface in #15.

The decision

Applications ship no JS, HTML, or CSS that executes or parses as page content anywhere in the system. The component is the entire app:

• App logic runs as a wasm component (deltic, framework side), per the existing components bet.
• App UI is expressed through a typed, DOM-shaped host surface (WIT): element creation from validated vocabulary, attributes checked per (tag, attribute), URL-typed values only as resource asset handles resolved from the manifest, events delivered as records (stream<event>), styling via parsed-and-laundered stylesheet assets or property-level calls.
• The UI frame (sandboxed, dedicated origin, header CSP per NOTES) runs only trusted framework shim code, applying validated operations to real DOM. App-authored strings are never parsed as HTML there; app-authored script never executes there.
• JS is userland, not platform: apps wanting JS compile it into their component (componentize-js / StarlingMonkey; QuickJS), optionally against a guest-side DOM shim so DOM-expecting frameworks (React-class) largely work. The sandbox is indifferent — the interpreter sits inside the capability boundary.

Why

1. Any realm executing app JS keeps a residual-channel long tail. The App-frame sandboxing: a ruling table per sandbox flag and CSP directive; residual channels; anti-spoofing chrome #5 ruling table (WebRTC data channels with webrtc 'block' support caveats, speculation rules, fresh same-origin realms resurrecting censored globals, UA-initiated fetches…) is load-bearing forever if app script runs in the frame, and it degrades on exactly our worst browser (Safari). With no app JS, that table demotes to defense-in-depth backstop; the primary boundary becomes the component import set — enumerable, diffable in CI, fuzzable per-function. There is no realm to escape and no global to censor.
2. String-HTML never crosses a trust boundary, killing the mutation-XSS / parser-differential class outright rather than sanitizing at it. CSS is treated as code (it is one): parsed with the engine's own parser (constructable stylesheets), URL-bearing properties rewritten to asset handles, @import inlined at install.
3. No live platform objects are reachable from app code. Handles are opaque component resources; traversal escapes (ownerDocument → window → network) exist only if the surface exports them. Validator TCB shrinks from "HTML/CSS/JS sanitizer" to typed per-op checks.
4. Capability story becomes uniform. The UI surface is just another set of imports under the Permission model: linking as enforcement - deny-by-unlink, prompt-on-first-use, revocation semantics, durable grants #6 linker model — same deny/prompt/revoke semantics as network and data, one consent vocabulary. The honest exfil claim from Network capabilities: per-destination grants, the app manifest, proxied fetch and the audit log, exfiltration stance #7 is unchanged: this bounds unconsented channels and shrinks the enforcement surface; it does not make granted-channel encoding impossible.

What it costs (stated plainly — the Sandstorm lesson)

• No as-is porting of existing web apps. UI must target the surface (directly or via the SDK shim). This is the existential DX risk; Developer experience: the componentize-js app SDK, fetch/storage shims, the porting story #13 carries it.
• Sync layout reads become async or shim-cached (getBoundingClientRect-shaped code changes form). Two-hop RPC latency budget per NOTES stands.
• Accessibility must be first-class in the surface vocabulary from day one — semantic elements and ARIA in v1, not retrofitted. (This is also why canvas-only rendering was rejected despite its smaller surface.)
• Text input, IME, focus, selection are the classically thorny parts of mediated DOM; they need explicit design, not emergence.

Alternatives considered

• App HTML/JS bundle in the sandboxed+CSP frame (the prior NOTES sketch): rejected as primary — keeps the ruling table as the real boundary forever, plus sanitizer burden, plus realm problems. Any future "legacy tier" running such bundles is a separate decision with its own threat entry, not a default.
• Hardened JS (SES/Compartment) in a worker: viable but adds lockdown/engine-compat risk and keeps JS-realm reasoning; NOTES prior-art already names SES/Endo the road not taken — this extends that choice to the UI layer.
• Platform-imposed interpreter-in-wasm: unnecessary given components; apps may do it themselves (see JS-as-userland above).
• Canvas-only UI: total mediation, unacceptable a11y/text/i18n.

Performance posture

App logic runs at native wasm speed. The DOM surface is per-call and chatty by design (future-compatible per #15); the shim batches host-side per animation frame, and the postMessage hop — not the component boundary — dominates the UI path. Mozilla's Dodrio experiment (45% of DOM-change application time was glue overhead) both motivates host-side batching now and prices the native-binding upside later.

Conversion checkpoints (provisional → ruling)

• Walking-skeleton app: a real (small) app built end-to-end on the surface under deltic — validates the vocabulary, measures two-hop latency and batching against interaction budgets.
• Porting spike (Developer experience: the componentize-js app SDK, fetch/storage shims, the porting story #13): one existing small web app brought over via componentize-js + guest DOM shim; porting cost assessed explicitly against the Sandstorm bar.
• A11y review of the v1 surface vocabulary by someone who does this for a living.
• App-frame sandboxing: a ruling table per sandbox flag and CSP directive; residual channels; anti-spoofing chrome #5 re-scoped, not shrunk: the ruling table and canary checks are re-labeled backstop and still fully enumerated — demotion is not deletion.

Open sub-questions

• Surface vocabulary ownership: WebIDL-mirror subset (WIT surface shapes: the web-embedding fast-path bet - mirror WebIDL on pass-through surfaces, resources not indices, streams not callbacks #15 rules) vs framework-shaped ops — likely both, layered; where is the line?
• Text input/IME/selection/focus model.
• Clipboard, drag-and-drop, file pickers as consent-gated capabilities on the UI surface (powerbox-shaped, per Permission model: linking as enforcement - deny-by-unlink, prompt-on-first-use, revocation semantics, durable grants #6).
• Whether the future in-frame placement (WIT surface shapes: the web-embedding fast-path bet - mirror WebIDL on pass-through surfaces, resources not indices, streams not callbacks #15) changes the shim's validation duties enough to warrant a separate ruling.

[lannbot]

First conversion-checkpoint artifact: spikes/todomvc — TodoMVC as a wasm component driving the curated DOM surface, no app JS/HTML, on deltic (0.1.0-pre.gc4043e6, build-time envelope, no translator shipped).

Live demo (mobile-friendly): https://polymorph-components.github.io/polymorph-apps/spike-todomvc/

Scope: wasm→DOM plumbing only; the worker/frame split, permission linker, and asset pipeline are left as seams (ops and events already cross as structured-clone-checked data; handles allocated surface-side so no sync read-backs block a future hop).

Findings recorded in the README; headlines:

• All-sync imports → no JSPI/COOP/COEP/SAB anywhere: nothing that excludes iOS WebKit. Symbol.dispose polyfill needed on older engines.
• ~68 KB gzip total (runtime 52 / component 14 / envelope 1.5).
• The artifact demonstrates import-set-as-boundary directly: methods the guest never calls (remove-attribute, remove) are pruned from the component's imported world — wasm-tools component wit on the binary IS the reachable surface.
• One real ordering find: focus() no-ops on not-yet-connected elements — the guest must focus after appending. Exactly the DOM-semantics class the record protocol has to keep explicit.
• deltic embedder notes: interface import keys are versioned verbatim (polymorph:todomvc-spike/dom@0.0.1); host resource class + free functions returning instances worked as contracted; guest handle drops surface as [Symbol.dispose] → clean applier-table lifecycle.

(Originally spiked in a standalone repo; moved into this repo at spikes/todomvc per convention, demo now under Pages at /docs.)

[lannbot]

Framework support validated: the spike now runs a real framework — dioxus 0.7 — as a second guest implementing the same todomvc world, its in-guest VDOM diffing applied through the curated surface.

Live: https://polymorph-components.github.io/polymorph-apps/spike-todomvc/?guest=dioxus (all three backends work: &backend=queued|direct|channel)

Research + decision (Leptos vs Dioxus, details in the spike README):

• Dioxus: dioxus-core's WriteMutations is a real maintained renderer seam (Blitz ships on it), the crate graph is wasm-bindgen-free, and the VirtualDom drives synchronously — the glue is ~450 lines (stack-machine mutation writer with guest-side shadow children for template paths, an HtmlEventConverter over surface event records, listener tokens = ElementIds).
• Leptos 0.8: tachys hardcodes Rndr = Dom (web-sys) — the generic renderer was monomorphized away for compile times; support would mean forking the view layer. Its standalone reactive_graph stays interesting for a future hand-rolled fine-grained renderer.
• No host-side VDOM diffing was needed or added — the framework brings the diff; the surface stayed a validated patch target, confirming the analysis that the dependency points that way.

Surface additions the framework forced — exactly the predicted prerequisite list: create-text-node (mixed content) and before/after (ChildNode mirrors, positional insertion for keyed diffs). All structural, all validated; two new probe cases pin text-node restrictions; harness still PASS (10 cases × 3 backends).

Findings worth keeping:

• "wasm32 implies browser" is the ecosystem's big lie: dioxus-core's mandatory subsecond (hot-patch runtime) links js-sys/wasm-bindgen on all wasm32 targets and poisons componentization. Fixed with an API-identical inert stub via [patch.crates-io] (spikes/todomvc/vendor/subsecond). Expect this pattern to recur across the Rust ecosystem; the SDK story (Developer experience: the componentize-js app SDK, fetch/storage shims, the porting story #13) should own a catalogue of such stubs.
• Framework tax: 366 KB raw / 130 KB gz for the dioxus guest vs 37/14 hand-written.
• Known gaps documented: no onmounted/focus bridging yet (edit field doesn't auto-focus in the dioxus guest — needs a mounted-data story over the surface), handler-side preventDefault/stopPropagation don't cross the record boundary (real-DOM bubbling + bubbles=false into dioxus), six event families converted so far.

[lannbot]

JS-as-userland, proven end to end: the spike's third guest is unmodified Preact 10.27 running inside a StarlingMonkey component (componentize-js, --disable all), driving the same todomvc world through a ~230-line guest-side DOM shim.

Live: https://polymorph-components.github.io/polymorph-apps/spike-todomvc/?guest=preact (all three backends; verified at mobile viewport)

The load-bearing facts:

• With all WASI features disabled, the emitted world imports only the three surface interfaces — a 12.7 MB (4.1 MB gz) component with zero ambient authority. deltic translates it in ~200 ms; the SpiderMonkey tax is real but the confinement story is unchanged: the interpreter lives inside the app's own capability boundary, exactly as App execution model: no app JS - components drive a curated DOM surface, the UI frame runs only framework code #16 claimed.
• The shim is the predicted shape: structure reads (parentNode/childNodes/nextSibling) answered from guest-side shadow bookkeeping, mutations written through to surface handles, and input value/checked mirrored from event records before dispatch so e.target.value works with no host reads. This artifact is the seed of the Developer experience: the componentize-js app SDK, fetch/storage shims, the porting story #13 SDK's DOM shim.
• Frameworks probe the DOM's shape: Preact renders exclusively via createElementNS(parent.namespaceURI, …), and lowercases onKeyDown only if 'onkeydown' in dom — keying its internal handler map with whatever survives. Both found by test; both now documented shim obligations.
• Deterministic edit focus works (useLayoutEffect + ref → focus() synchronously in the commit) — validating the focus-as-explicit-op ruling from the framework side, and closing the gap the dioxus guest still has (no onmounted bridge yet).
• Preact's diff emits targeted ops (["text", id, "1"] on the counter's text node) — fine-grained updates straight through the seam, no host-side diffing anywhere.
• Debugging without stderr: uncaught guest exceptions become opaque traps under --disable all, so the exports smuggle error.stack out through a surface op before rethrowing (guest-error: class beacon), plus tools/diag-preact.ts drives any guest headlessly under Deno. A real diagnostics channel is now an evidenced framework need.

Framework-validation status per the earlier survey: imperative ✓, template-VDOM (dioxus) ✓, DOM-API-on-shim (preact) ✓ — three architectures, one WIT surface, no host changes needed for the third. Next surface pressure should come from a second real app (style/aria/pointer), not a fourth renderer.