optimizing-your-rust-projects-for-wasm-in-browsers-and-phones
Made by JeffMake Rust projects extremely fast in browser wasm on desktop and iPhone — zero native regression, proven native↔wasm parity. Use when: wasm, WebAssembly, wasm-pack, wasm-bindgen, browser port, web demo, SIMD128, wasm threads, SharedArrayBuffer, COOP/COEP, iPhone Safari crash, mobile touch/IME for a canvas app, wasm size budget, wasm perf regression, or "why is the browser build slow". Browser/phone wasm only — not for server-side wasmtime/WASI.
From Jeffrey's Skills.md: professionally crafted skills for any AI agent, installed and kept in sync by the jsm CLI. Subscription only, $20/month.
Works With
Quality and Utility come from canonical skill metadata. Community ratings appear separately as stars when subscriber reviews exist.
Subscribe to download
Public previews are available, but downloads, CLI sync, and premium content require an active subscription.
Sign In to Subscribe- Full skill content with deterministic versioning
- CLI sync + local search index
- Access to Jeffrey’s premium library
Save to your account
Saved skills live in your cloud list. Run jsm sync on each machine to pull them locally.
What's New with this Skill
3Updates, enhancements, and release notes for this skill.
Updated: optimizing-your-rust-projects-for-wasm-in-browsers-and-phones, the dual build wasn't enough, and the diet that finally made an iPhone speak
The dual-build doctrine met its limit: growing a shared memory kills iOS tabs near 2 GB, but the serial build still died at a 2.45 GB hydration peak. What produced the first on-device synthesis was a memory diet. Order allocations by lifetime, stop staging bytes the model never reads, fuse derived tables once, and treat dying below a previously survived peak as allocation churn. Committed peak fell from 3.35 GB to 1.61 GB and the phone spoke.
- The tab budget is about 2 GB typical and 3 GB on recent Pros, measured by killing a real iPhone 17 Pro Max rather than by reading documentation: 2.45 GB died, 1.61 GB survived, and iOS Chrome is tighter than Safari on the same phone.
- Order allocations by lifetime on a heap that never shrinks; a freed buffer only helps if a later allocation fits its hole. Reordering alone halved a crash-phase footprint, and fusing weight tables once at hydration made repeated synthesis memory-flat instead of adding 0.56 GB per press.
- Dying below a peak the device previously survived means allocation churn beside the resident set, not totals: a fresh 16 MB ArrayBuffer per chunk crashed at 1.4 GB where 1.86 GB had passed. One reused buffer with subarray views fixed it.
- The section worth removing is rarely the biggest allocation; it is the biggest one barely read. Cold rows were 47% of the artifact and a few hundred 4 KB reads per utterance. Staging only the digest-verified prefix cut the peak from 2.45 to 1.86 GB at zero speed cost.
- frankentts killed int4 at 22x slower because the scalar nibble unpack is where the time goes. franken_ocr then built the in-register SIMD unpack the do-not-retry predicate demanded and took roughly 6x, so the ledger now records that predicate as discharged.
- Same-harness numbers replaced the estimate: codec 13.2x, end-to-end 9.4x, published as 0.31 to 0.43x realtime speed. Re-profile after every lever; the win moved the codec from 92% of frame time to 65% and re-aimed the next one.
- Harnesses lie in new ways. Playwright's default ephemeral WebKit context fails OPFS with a fake out-of-memory error, about:blank is an opaque origin, and safaridriver no longer supports iOS at all. A persistent-profile desktop WebKit run passed the same build the phone killed.
- A hydration crash plus auto-loading of a cached model bricked the page in a permanent crash loop. Models now load on an explicit tap, a crash breadcrumb counts as a refusal to auto-retry, and a standalone reset page that loads no wasm clears OPFS by enumeration.
Two new projects joined the corpus and stress-tested the doctrine: franken_ocr runs a 3-billion-parameter mixture-of-experts OCR model in a browser tab (a 3.0 GB int4 artifact staged in segments under the 2 GiB single-allocation wall), and franken_whisper fits a whole ASR engine in a 597 KB gzip module beside its model. The memory chapter is rewritten around the allocation-order law; two-phase staging is now labeled v1 and superseded. The iPhone crash taxonomy grew to twelve rows, covering crash-loop bricks, compositor-layer kills, and dying below a peak the device previously survived. The neg
Updated: optimizing-your-rust-projects-for-wasm-in-browsers-and-phones, the iOS grow law and the dual-build doctrine
A probe run on a real iPhone 17 Pro Max pinned down why big-heap threaded builds die on iOS: flat allocation to 3.5 GB is fine, growing an unshared memory to 2.75 GB is fine, but growing a shared memory kills the tab near 2 GB. That finding rewrites the threads doctrine into a dual-build rule: one threaded artifact for isolated non-WebKit browsers, and one unshared, growable artifact for WebKit. Six more mined conclusions land with it, each with receipts.
- The iOS grow law, probe-verified on an iPhone 17 Pro Max and now a named glossary term: flat allocation to 3.5 GB is fine shared or unshared, growing an unshared memory to 2.75 GB is fine, growing a shared memory kills the tab near 2 GB
- Corollaries kill the folk remedies: dlmalloc grows on every heap request (pre-reserving is dead), maximum === initial aborts on first allocation (dead), and a shared memory reserves its full declared maximum up front
- Dual-build doctrine replaces single-artifact for big-heap apps: pkg/ threaded for isolated non-WebKit, pkg-serial/ unshared and growable for WebKit (it hydrates the full model at a measured 2.45 GB peak), threads opt-in by allow-list, glue and binary from one PKG_DIR constant
- The module-worker message-loss window: messages posted before onmessage exists are silently discarded, and any top-level await opens the window; one lost init produced both the Chrome hang and the iOS wasm.x undefined; fix is buffer-before-await plus a promise queue with .catch
- The Amdahl verdict is wired into the perf ritual: a threads push covered 7.9% of frame time while the codec held 92%, so whole-pipeline stage split is now step 2 and "threads first" is an anti-pattern row with this receipt
- Packed GEMM microkernel doctrine: no BLAS exists in wasm, so port a plain-scalar MR×NR register-tiled kernel and let LLVM autovectorize; bit-identical ascending-k, team-parallelizable columns, matrixmultiply rejected on parity grounds, NE-004 rescoped to m=1 only
- The testing law: shimmed Node harnesses are a measured-dead proof method; the real-browser harness (real Chromium, shipped headers, real model) lands in PARITY §6 and PROFILING §2, and Proven Results updates to 3.19x slower-than-realtime with the different-harness caveat stated
The grow law comes with corollaries that kill two folk remedies at once: dlmalloc grows on every heap request, so pre-reserving is dead; maximum === initial aborts on the first allocation, so that escape hatch is dead too; and a shared memory reserves its full declared maximum up front, which is exactly why growth hits the wall. Since sharedness is decided at link time, the fix is structural: the dual-build doctrine ships pkg/ (threaded) for isolated non-WebKit browsers and pkg-serial/ (unshared, growable; it hydrates the full model at a measured 2.45 GB peak) for WebKit, threads opt in by all
New skill: optimizing-your-rust-projects-for-wasm-in-browsers-and-phones
Most Rust wasm ports treat the browser as another build target, then wonder why the demo stutters on desktop and dies on iPhone. This skill treats the browser as a different machine: map the architecture onto it first, keep one code path, prove native↔wasm parity on the built artifact, and design the JS boundary as a protocol with flat buffers and coarse calls. SIMD and threads come last, behind a measured ~2x SIMD ceiling and a ledger of levers that already failed.
- The One Rule: same bytes, different machine. One code path serves native and wasm; parity is proven on the BUILT artifact via byte-compare, golden traces, and lockstep checksums; fast paths that drift output get reverted and ledgered
- The JS boundary is a protocol: flat buffers, coarse calls, drain-once. The TTS port's 12.6x came from a profile-pinned hot loop (a wasm-only 8-lane split plus the int8 codec arm); the terminal renderer's 60fps came from architecture with no SIMD or threads
- iPhone survival is its own phase: memory is hard-committed (receipted ~384 MB iOS canvas pool), big payloads are streamed and never held twice, and shipping requires a crash-falsification loop on a real, recent iPhone
- A negative-evidence ledger stops anyone re-spending failed levers: NE-003 records SIMD128 at a measured 1.47-1.71x against the predicted 4-8x
- SIMD and threads are LAST levers: the threads build is solved via the TLS export set while its speedup is still marked unproven
- Depth on demand: 14 reference files (architecture mapping, build cookbook, JS boundary, memory and startup, profiling in browsers, iPhone survival, input and mobile UX, SIMD and threads), 5 subagent roles, and paste-ready templates for size budgets, parity gates, and COOP/COEP headers
- Zero-token validation: scripts/validate-skill.py checks the bundle's own references, terms and stale claims, and SELF-TEST.md checks whether an agent can route the console cold
The doctrine was distilled from five real browser ports. Two of them: a 2 GB neural TTS engine that went from 119.9s to 9.5s for a four-frame synthesis entirely in-browser, after a V8 profile pinned 71% of synthesis in one scalar f32 tail and a wasm-only 8-lane split plus the int8 codec arm fixed it; and a 60fps terminal renderer that needed zero SIMD and zero threads, getting its speed from architecture (host-pumped loop, flat-u32 patch protocol, damage tracking).