feat(framework): add Octane as the third first-class framework

[doodlewind]

Octane (https://github.com/octanejs/octane — React's programming model, compiled; by Dominic Gannaway) joins Solid and Vue Vapor as a first-class PocketJS framework. This is the React-model path PR #6 concluded was impossible with original React: Octane's universal client target compiles JSX + hooks into static host plans + dynamic slot batches executed by a UniversalHostDriver — no DOM, no VDOM — which maps directly onto the native ui.* tree.

What's in here

Adapter (framework/src/*octane*)

• renderer-octane.ts — the "pocket" universal driver: host command batches (create/update/insert/move/remove/destroy) applied to the shared NodeMirror arena via applyProps; #text hosts through createTextNode/replaceText; portals as a driver capability minting overlay hosts transactionally. Re-exports the host-neutral universal ABI (octane/universal/native — QuickJS-safe).
• components-octane.tsx — the full 15-component surface (View/Text/Image/Sprite as hand-lowered universal plans; Screen/Focusable/FocusScope/FocusGrid/ActionHandler/Portal/Modal/ActionBar/Grid/Lazy/Gallery as Octane function components).
• frame-octane.tsx / lifecycle-octane.ts — useFrame, useButtonPress, useSpriteAnimation (use-prefixed: the Octane compiler slot-keys custom hooks by the use[A-Z] call-site convention; non-hook names silently collide their internal slots).
• index-octane.ts — render/mount; the frame handler drains Octane's microtask renders inside the frame via flushUniversalSync, so state commits land in the same tick as their input.

Compiler/build

• jsx-plugin.ts: third FRAMEWORKS entry, OCTANE_RENDERER_DESCRIPTOR, octane compile branch (collector pass on pristine source → octane/compiler universal lowering), generalized frameworkVariantPath (app.octane.tsx siblings), cache-key includes the octane version.
• pocket.json schema ("framework": "octane"), package exports ./octane/*, tsconfig paths.

The memory hunt (the fun part) — octane demos initially died mid-run on PPSSPP (InternalError: out of memory with megabytes of arena free, opaque null exceptions, wedged frame loops). A scratch cargo probe pinned to the exact libquickjs-sys revision (eval the real bundle + stub ui + frame loop + heap histograms + a gc_decref root dump) unpicked a three-layer cause:

1. Octane's profiler is on by default, and its trackedComponents WeakMap is written even after profiler.stop() — with per-render closures as values.
2. The pinned QuickJS (2026-06, new GC) marks WeakMap record values strongly — not ephemeron-aware — so those records pinned every render's owner graph (ten-line upstream repro: wm.set(key, {back: key}) never collects; bellard master has the same code).
3. Even after unpinning, the engine's internal slab allocator (JSMallocArena) amplifies any residual retention 10-20× on a fixed arena: a few live objects pin whole chunks, and the auto-GC threshold (live × 1.5) is far too lazy for a 14.4 MiB heap.

Fixes, in order: framework=octane builds alias octane/profiling to a no-op stub (framework/src/octane-profiling-stub.ts — also removes per-render profiler work from the frame budget); the PSP frame loop gained an arena-pressure GC (JS_RunGC when a frame leaves the bump pointer >256 KiB past the last collection — steady-state Solid/Vapor guests never trigger it); and the Octane ports keep always-animating state in leaf components, committing state on visible steps (music's Equalizer/ProgressLine split, stats' StatTiles). Along the way the PSP host's exception logger learned to print tag + message + stack (a null exception is QuickJS's no-room-for-the-Error-object throw), and one solid golden (hero.boot, a single background pixel ±2) was re-baselined — it predates this branch; this is the first full solid e2e since the #149-era goldens.

Result: all three frameworks pass byte-exact PPSSPP e2e. A real-hardware test then exposed the second act (commits 4e097c0, f0b8d12): hero-octane ran under 1 fps on a physical PSP. Two more root causes fell out — every PSP QuickJS build since 2021 had silently been -O0 (CRATE_CC_NO_DEFAULTS=1 drops the cc crate's opt_level; -O2 now lives in TARGET_CFLAGS, and libquickjs-sys is repinned registry-wide), and an Octane state commit replays the whole root at scope-independent cost, so per-frame state is unaffordable regardless of leaf placement. Continuous motion now rides the native channels (<Sprite> atlases, baked keyframe timelines, animate()/jump(), ref-based phase timers, and a new setTextContent() escape hatch for per-frame text). Per-replay engine residue remains a tracked quickjs-rs follow-up, but replays are now interaction-rate, not frame-rate.

Demos — all 8 Vue Vapor demos got app.octane.tsx twins (hero, cards, stats, library, settings, notifications, music, gallery), sim-verified text/pixel parity against the vapor variants, PPSSPP byte-exact goldens in tests/goldens/psp-octane/ (7 bench-table demos), plus new tests/goldens/psp-vue-vapor/ coverage.

Playground + docs — third framework toggle with in-browser octane compilation (pure-JS compiler, no WASM shim needed), pg/runtime-octane.js bundle, import-map entries; frameworks.md reworked for three frameworks, octane fences added to all 29 :::framework-code blocks, README/DESIGN/RUNTIMES/home/INTEGRATION updated.

Benchmark — tools/bench-ppsspp.ts regained the PR #6 cross-engine axis: --frameworks=solid,vue-vapor,octane, per-(app, framework) grouping, geomean-vs-baseline ratios with optional --bootstrap CIs; tools/bench-chart.ts renders the matrix SVG. Full three-framework results below.

Benchmark (PPSSPP software renderer, per PR #6 methodology)

7 samples per (app, framework) cell across the 7 bench demos, deterministic PPSSPP headless (PPSSPP 676724ee5e, base 4e097c0), geomean-vs-Solid ratios with mulberry32-seeded 5000-resample bootstrap 95% CIs. Full report + chart in docs/bench/ (three-frameworks-ppsspp-2026-07-30.{md,json,svg,png}; the pre-fix 07-29 dataset is archived beside it); raw samples reproducible via the specs table in tools/bench-ppsspp.ts, and the report is rebuildable from a raw dump with the new --from-raw=<raw.jsonl> mode.

metric (geomean vs Solid, lower is better)	Vue Vapor	Octane
bundle eval	2.91×	2.88×
boot → first frame	2.02×	2.00×
avg frame work	1.11×	1.66× (was 15.58× pre-fix)
host wall clock	1.25× [1.24, 1.25]	1.27× [1.26, 1.28]
bundle size	2.41×	2.96×

Average frame work by app:

app	Solid	Vue Vapor	Octane	Octane pre-fix
hero	3.66 ms	3.61 ms	6.53 ms	387.82 ms
cards	4.82 ms	5.14 ms	6.56 ms	9.66 ms
stats	6.84 ms	8.04 ms	9.25 ms	279.91 ms
library	3.68 ms	4.39 ms	4.94 ms	50.76 ms
settings	6.84 ms	7.37 ms	14.53 ms	27.44 ms
notifications	4.52 ms	6.10 ms	13.84 ms	271.21 ms
music	10.44 ms	10.39 ms	12.92 ms	282.71 ms

Every cell of all three frameworks is inside the 16.7 ms 60 fps budget (the -O2 fix also roughly halved Solid's and Vue Vapor's own numbers). The honest remaining gaps: Octane runs 1.2–3.1× Solid per app, and a button press is one root replay ≈ 150–250 ms on the PSP — the replay walk's identity-path re-resolution (13k calls/replay) is the upstream Octane follow-up, alongside the quickjs-rs ephemeron repair.

React status: unchanged from PR #6 — original React still has no viable PSP path; Octane is the React programming model that does run, measured above.

Authoring notes (also in docs/frameworks.md)

• Mixed static+dynamic text → one template literal (universal lowering trims the static segment's trailing space).
• Frame-loop counters → functional setState (a same-frame handler write would be clobbered by a stale read).
• Don't put natively-animated props in a style whose value changes across renders (unchanged values diff away and are safe).
• Octane entries call mount(App) — JSX in a call-argument arrow is a fail-closed universal-target error.

Validation

• bunx tsc --noEmit clean
• bun run test green end-to-end (includes the new tests/octane-smoke.test.ts + hero --framework=octane build in the chain)
• PPSSPP e2e byte-exact goldens for all three frameworks: tests/goldens/psp/, tests/goldens/psp-vue-vapor/ (new), tests/goldens/psp-octane/ (new); hero.boot re-baselined (single background pixel ±2, pre-dates this branch)
• Three-framework benchmark: 147 samples (7 per cell × 7 apps × 3 frameworks), deterministic — repeated runs are byte-identical; pre-fix and post-fix reports/charts archived in docs/bench/
• XMB cover art (ICON0/PIC1/title) for all eight demos via tools/gen-demo-covers.ts
• bun site/build.ts green — playground ships current pg/runtime.js / pg/runtime-vue-vapor.js / pg/runtime-octane.js
• Real-hardware PSP first run — caught hero-octane at <1 fps and triggered the performance work in 4e097c0
• Real-hardware PSP re-test of the post-fix EBOOTs — confirmed smooth on device; it also caught the blank sprite-atlas bug (<g transform> silently dropped by bake-svg) fixed in 569d626

🤖 Generated with Claude Code