Developer experience: the componentize-js app SDK, fetch/storage shims, the porting story

[lannbot]

Make porting a normal web app mechanical — Sandstorm's postmortem lesson is that porting friction kills the ecosystem, and this design asks more of app authors than Sandstorm did. See NOTES.md — Developer experience.

Directions:

• A componentize-js SDK: fetch shim → capability-checked host fetch; storage shim (IndexedDB/KV-shaped) → framework data services; templates (polymorph create-app). In-family precedent: webcrypto-componentize (crypto.subtle over WIT imports).
• A WIT-first surface for component-native developers (Rust, …) in parallel.
• The embedded-UI story: asset pipeline (bundle → srcdoc/blob injection), and a dev loop (local shell, hot reload, capability mocks).

Open sub-questions:

• Target persona and budget split: JS devs porting web apps vs component-native devs — this decides where SDK effort goes first.
• How much of the web platform the shims must cover before "just port it" is honest (routing? workers? WebSocket?).
• App packaging/manifest format (interacts with the network-capabilities manifest) and signing/distribution (app stores? URLs? content-addressed?).
• Testing story for apps: what of the polymorph:test stack is reusable for app authors.

[lannbot]

Ruling: the wasm-bindgen trapping root-stub (SDK substrate)

From the 2026-08-16 framework-support work (context: #16 dioxus comment — dioxus-core's mandatory subsecond links wasm-bindgen on all wasm32 targets and poisons componentization; fixed there with a bespoke inert stub).

The generalization: js-sys and web-sys are almost entirely #[wasm_bindgen] extern declarations expanded by the macro. So stub the roots, not the frameworks: a forked wasm-bindgen (runtime types) + macro whose codegen turns every JS import in the entire dependency universe into a trapping Rust function — no __wbindgen_* imports, no custom sections, componentizes by construction. One patch entry covers every crate that links the JS boundary.

Stub grades (ruling-table discipline, per item):

1. Trapping (default): "never reached" becomes a runtime-enforced invariant with surface-violation semantics; trap messages double as an empirical reachability audit (linkage ≠ reachability — cargo tree can't tell you which APIs actually fire).
2. No-op (recorded justification required): reached but inert by contract.
3. Capability-routed (not a stub): time/randomness/logging route to WIT imports (getrandom custom backend, web-time replacement) — the honest version of the dependency.

What it does not change: web-sys-welded render paths (leptos/sycamore) trap on frame one — loudly dead is better than silently broken, but still not support. Renderer seams remain the integration rule.

Placement ruling: NOT deltic (host runtime vs guest authoring; wrong publishing cadence — JSR-per-commit vs crates.io tracking wasm-bindgen 0.2.x). Incubate in polymorph-apps (spikes/no-js-bindgen) where the acceptance test lives; graduate to a standalone repo (personal-account infra, same pattern as deltic) once proven — it has its own audience (any Rust-component author, wasmtime/jco included) and a maintenance treadmill (wasm-bindgen versions) that wants outside contributors. The SDK depends on it and owns the polymorph pins + capability-routed replacements + CI gate; deltic may consume it as a contaminated-graph guest fixture. Upstream endgame: a cleanly-scoped repo is what a wasm-bindgen upstream issue can point at (filing is a human decision, as usual).

CI-gate evolution: pure guests keep cargo tree -i wasm-bindgen = empty; framework guests pin the root-stub, and traps are the tripwire for reachability drift on framework upgrades.

Acceptance test (in flight): rebuild spikes/todomvc/guest-dioxus against real js-sys/web-sys/subsecond with only the root-stub patched in, delete vendor/subsecond, equivalence harness stays green.

[lannbot]

Executed, with one design upgrade over the ruling above: the incubated artifact is a composition-time severer, not a macro fork — spikes/no-js-bindgen (commit d67b438).

wbg-sever (walrus, ~120 lines) post-processes the compiled core module: every function import from __wbindgen*/snippet modules is replaced in place by an unreachable body (call sites keep indices; shim names — which encode the JS API — survive in the name section for trap diagnosis), describe exports and wasm-bindgen custom sections are stripped, and non-function JS-boundary imports are a hard error (that graph genuinely needs JS glue). Sound because describe exports only execute inside the wasm-bindgen CLI, which never runs, and pre-CLI externref-xform imports are plain functions.

Why this beats the macro fork: zero source patching, no per-version parser maintenance (operates on the stable-ish import-module naming layer), and it covers any wasm-bindgen version in one tool. The macro fork stays on the shelf as the fallback if richer trap messages or partial linking ever justify it.

Acceptance test passed: guest-dioxus rebuilt against real subsecond/js-sys/web-sys, vendor/subsecond deleted — 4 imports severed, 1930 describe exports stripped, artifact smaller (352 KB vs 366 KB with the bespoke stub), full behavior battery + equivalence harness green, live on Pages.

Pipeline shape (the CI-gate pattern from the ruling, now concrete): pure guests keep cargo tree -i wasm-bindgen empty; framework guests go build → wbg-sever → component new, with the behavior suite as the reachability tripwire on dependency upgrades. Graduation to a standalone repo per the placement ruling once it survives a second consumer.

[lannbot]

Groundwork update for the SDK's dependency story: the whole family now publishes to JSR under caret-honest 0.x versioning — @polymorph/test, @polymorph/webcrypto, @polymorph/websocket, @polymorph/webrtc-datachannels, and @polymorph/iroh (the last shipping the built endpoint component inside the package: import, newEndpointInstance(), done). An app SDK can consume the substrate by caret constraint from a registry rather than by rev-pinned checkouts — and @polymorph/iroh's embedded-wasm pattern is the precedent for the SDK shipping framework components the same way. The "what of polymorph:test is reusable for app authors" sub-question also gets simpler: jsr:@polymorph/test is directly importable in app repos.