Engines, AOT/JIT, WebGL, Studio: research synthesis (2026-09-30)

Status: research only. Nothing here is implemented. Speedups and effort figures are estimates unless marked measured. Details, sources and verified/inferred tags are in the five reports next to this file.

Conclusions

1. Zinc VM AOT: ZBC4 -> C++ -> clang -O2 (--emit-aot in the runner, interpreter as fallback and oracle). Scalar prototype (measured): fib(32) 130 ms interp / 66 JIT / 31 AOT / 10 native; mandelbrot 350 / 80 / 21.8 / 22. Upper bound for numeric code only. Do the compiler/interpreter quick wins first (no register allocation or copy coalescing in emit-bc.ts; 32-byte Ins; heavy CALL; std::find per field access). Unify the recursion limit (JIT 1024 vs interpreter 16383). ~17-24 weeks for P0-P4 including iOS/OTA mixed mode.
2. QuickJS: port qjsc -A (ivankra/quickjs-aot) onto quickjs-ng 0.17 (what Zinc vendors). Measured here: -A gives 1.4x fib, 2.2x mandelbrot, 1.14x objects vs its own interpreter; tail dispatch alone was neutral. First do the cheap wins: precompiled bytecode (the runner re-parses source at each start), -O3/LTO/PGO, and fix Math.fround emission for f32 (measured 2x on a loop). A real JIT (60-100 days, high risk, not iOS-legal) only after profiling a real Zinc UI app, which has not been done.
3. mquickjs is a different language (strict ES5), not a lighter QuickJS. Worth it for ESP32-class targets, not for Pi, rM or iOS. MVP 12-15 days, parity 32-45 days. Cheaper first step: an engine: 'mquickjs' option for zinc:script (~6-8 days). Not suitable for upstream Three.js.
4. Three.js / WebGL2: Zinc has no WebGL today. Needs a native WebGL2 core over GLES3 (ANGLE on macOS), QuickJS bindings generated from one IDL, a browser-host JS bundle, and zinc:webgl. WebGLRenderer needs 142 WebGL methods (r186.1). Three under QuickJS is ~14-30x slower than V8 on JS-side work (mock GL, order of magnitude), so QuickJS speed is the bottleneck, not the GL crossing. ~25-35 weeks. three-native is WebGL1-only and is reference reading, not a base.
5. Docker-free: zig c++ cross-compiled runtime/zrt.cpp for aarch64/armhf/x86_64 linux, windows and aarch64 macOS in ~1 s each (full link and SDL3 not tested). So linux/rpi/rmpp can drop Docker via zig c++ + pinned sysroots. ESP-IDF stays a managed SDK; PS1/PS2 on mac/Windows and Apple targets off-Mac still need Docker/VM/Mac.
6. Studio + browser: Tauri shell over the Node CLI, zinc toolchain install, and bytecode upload to a pre-flashed VM core as the Arduino-like learner path. Browser tiers: A (compile to ZBC4 + Wasm VM, no install), B (Web Serial upload), C (cloud compile). ~30-40 person-weeks for Studio + Tier A, +12-20 for Tier B. “ZincStudio” already names the macOS box editor in docs/studio.md: pick another product name.

Suggested order

1. Cheap wins (days): QuickJS bytecode precompile + fround fix + -O3/LTO; VM compiler quick wins; recursion-limit parity.
2. Profile a real Zinc UI app under --engine quickjs to decide JIT vs AOT vs typed AOT.
3. Zinc VM AOT (P1-P2) and QuickJS AOT on ng, in parallel with a 2-day mquickjs spike.
4. zinc toolchain (zig c++ first) and universal VM cores, which unlock Studio and browser Tier A/B.
5. WebGL2 core last: largest effort and it depends on QuickJS speed.

Caveats

• No Zinc app was run under any AOT prototype; the VM AOT prototype is scalar-only.
• Interpreter/JIT numbers come from binaries built 2026-09-29, before the current dirty edits.
• Web-sourced claims (weval, LuaAOT, longbridge/quickjs-jit, gkurt) were not reproduced.
• Estimates are one strong developer, unvalidated.

Addendum: JS engines, editor, Studio as a Zinc app, Carnet (same day)

7. JS engines: extract a zinc-js-engine interface from runtime/vm/quickjs.cpp; support QuickJS-ng (baseline, iOS, Pi 3B+, rM) and JavaScriptCore on macOS (JSCOnly for aarch64 Linux experimental); V8 only if Windows needs it; LibJS not viable now. Measured (single runs, JS-side only): Three r186 mock GL 500 cubes 13.2 ms/frame QuickJS-ng, 0.54 JSC, 0.81 V8; no-JIT JSC/V8 still ~2x faster than QuickJS. This revises item 4: JSC removes the QuickJS speed bottleneck on macOS. Highest-value independent change: ABI v5 with borrowed typed-array views (4-6 days).
8. Code editor: today it is the engine <TextArea> in code mode plus an extension API (single caret, whole-string undo snapshots, commit-only IME, no shaping). Plan: rope + range-set selection + ChangeSet transactions written in Zinc TS (zinc:editor), tree-sitter as a vendored native plugin, LSP client in Zinc TS over zinc:process, zinc lsp reusing frontend.ts. M1-M6 ~32-44 engineer-weeks. Several ABI gaps (non-blocking write, byte-safe I/O, PTY) unverified.
9. Studio as a Zinc app: yes (macOS/Linux first). apps/studio and examples/zed-editor already cover much of it; v0 ~8-10 pw, credible cross-platform IDE ~40-60 pw. Gates: Windows, accessibility, editor quality. Keep the Node CLI as a JSON-RPC child; self-hosting the compiler in QuickJS is optional and late. Rename to avoid the “ZincStudio” clash.
10. Carnet (notion-block-editor): its model is already headless and DOM-free (~3.5k lines, MIT, already ported to Swift and Rust/GPUI). Recommended: compile the core with Zinc, rewrite the view in Zinc JSX on a text engine shared with the code editor. Do not run its browser bundle on QuickJS. MVP ~20-28 weeks solo. Needs rich-text spans, shaping/segmentation, text geometry, IME preedit, rich clipboard first.

Shared critical path for 8, 9, 10: a native text engine (spans, shaping, segmentation, geometry, IME preedit). Caveats: effort numbers are unvalidated; JSCOnly, V8 and LibJS were not built; zinc check was not run on Carnet’s core.

Addendum 2: platform management, tool belt, OS integration (same day)

11. Platform management: platformVariant() (frontend.ts:197-208) and zinc:platform already exist, but constants are NOT compile-time today (verified: both branches type-checked and emitted; docs/targets/capabilities.md is wrong). Recommended: prune untaken branches in the frontend getSourceFile hook before TS type-check (whitespace blanking keeps positions), closed tag chain board > chip > target > family > native > default, Platform.{is,has,select,...}, --portable bytecode mode, zinc check --all-targets, @requires capability lint. ~28-38 days.
12. Tool belt: no Metro-style pipeline exists (bundleJs is a file copy). PocketJS = Babel + Bun.build IIFE with define, no ES5 lowering. Measured: minify cuts bytes 45% but QuickJS parse time barely changes (8.8 vs 8.1 ms), so bytecode precompile matters more than minify. ES5 lowering by generic tools fails on mquickjs (12/30 SWC, 9/30 Babel, 14/30 TS semantic cases); mquickjs needs lowering inside emit-js.ts for Zinc code plus SWC + fix-up + polyfills for foreign JS. Suggested: esbuild (bundle/define), oxlint + Zinc rules, oxc-parser, tsgo as fast gate. M0-M5 ~25-34 days.
13. OS integration: none exists; SDL3 3.4 headers expose tray/menus/dialogs/drop/clipboard mime/theme/power/displays but not notifications, global shortcuts, deep links, keychain, native macOS menu. Proposed zinc:desktop/* (not zinc:os, taken) with capability names, .sim.ts twins, zinc.json permission manifest. Items 1-9 ~14-17 weeks (mac/Linux). OS widgets cannot be authored from Zinc; honest option is a data/layout descriptor rendered by generated native shells.

Zinc VM: a real AOT mode, plus interpreter/JIT upgrades (research report)

Date 2026-09-30. Read-only on /Users/mowmow/Lab/zinc (dirty tree; nothing modified, nothing committed). Everything I ran lives in the scratchpad (aotproto/). Tags: [V] verified by reading code or by a measurement I ran; [D] stated by the repo’s own docs (not re-measured); [W] from web sources; [I] my inference or estimate.

Paths are relative to /Users/mowmow/Lab/zinc. Line refs are to the working tree as it was today (the files are dirty).

0. Executive summary

1. Recommended AOT: ZBC4 -> C++ generated by the VM runner itself (zinc-vm --emit-aot app.zbc), compiled by clang -O2 and linked into the core, with every non-trivial op delegated to the same single-sourced step<O,T> semantics. Scalar ops become C locals and clang does register allocation, inlining and loop optimisation. This is options (b) + Futamura-by-templates (f). It is the only option that (1) keeps the interpreter as the semantic oracle by construction, (2) is legal on iOS (native code is in the signed binary; downloaded bytecode is only ever interpreted), (3) works on x86-64/armv7/aarch64 unchanged, and (4) gets near-native scalar speed.

2. Measured evidence that this is worth it [V] (my throwaway generator turns the real fib and mandelbrot .zbc files into C, faithful to the VM’s frame/poll/depth protocol; outputs verified 2178309 and 6095446; 9 runs, median, spawn-to-exit, load ~6, ran 3 times, stable):

   Kernel	native	interpreter	JIT (--jit)	AOT prototype (clang -O2 from ZBC4)
   fib(32)	10 ms	130 ms	66 ms	31 ms (4.2x interp, 2.1x JIT, 3x native)
   mandelbrot	22 ms	350 ms	80 ms	21.8 ms (16x interp, 3.7x JIT, ~1.0x native)

   The prototype is scalar-only (no refs/heap/GC/exceptions), so it is an upper bound for the numeric part, not a claim for whole applications. It does keep the VM’s real call protocol (16-byte frame push, params through the frame, poll counter, depth check).

3. The current interpreter/JIT are far from the design report’s prototype [V]: design report: tail-acc 43/78 ms (fib/mandelbrot); integrated interpreter: 130/350 ms (3-4.5x slower). The causes are visible in the code (section 4): 32-byte Ins, heavy CALL handler, no register allocation or copy coalescing in emit-bc.ts, constants re-loaded from memory, every field/array access re-validates layout and type. Do the cheap wins first (Phase 0), they benefit every tier and the AOT input.

4. Two semantic divergences already exist between tiers [V]: the JIT limits recursion to 1024 frames (runtime/vm/jit.h:21), the interpreter to 16383 (runtime/vm/main.cpp:422). A “no compromise” AOT must first define one limit and give every tier the same. Native recursion also needs a big C stack (iOS threads default to 512 KB-1 MB [I]), so the VM must run on its own large-stack thread.

5. Rejected as the primary path: offline emission with the existing AArch64 JIT emitter (a: aarch64-only, a helper round trip per call, absolute addresses everywhere), MIR->C++ reuse of emit-cpp (c: emit-cpp is AST->C++ with RC and zrt::Ref, not MIR-driven; a second semantic implementation), Wasm intermediates (e: the semantics that matter are in the heap/GC/ABI, not the ISA). LLVM IR/QBE/MIR-project (d) are refinements of (b), not alternatives, and are worth revisiting only for precise GC (statepoints) or when clang is unavailable on the build host.

6. Effort: Phase 0 quick wins 2-3 weeks; refactor to single-sourced semantics 3-4 weeks; AOT emitter + parity 5-7 weeks; performance/GC precision 3-4 weeks; OTA mixed mode + iOS packaging 4-6 weeks. About 4-5 months for one experienced engineer end to end; a usable release-mode AOT (without OTA mixed mode) at about 2.5-3 months. [I]

1. What the VM actually is (verified reading)

1.1 Data model

• Register file / frames. union Reg {double f; int32_t i; uint32_t u; Heap* h;} (runtime/vm/main.cpp:29). One flat stack of Reg (1M registers default, :95). A callee frame starts at fp + caller.types.size() (:423), so every SSA value of a function has its own slot (no reuse). Frame{ip, fp, dst, fn} records live in frames[16384] (:83, :188).
• Instructions. On disk 16 bytes (compiler/src/emit-bc.ts:503-506); in memory struct Ins{Handler h; a,b,c; op,t; catchPc} = 32 bytes [V: compiled sizeof] (:81), not the 16 bytes the design doc assumes (docs/reports/zinc-vm.md:75-77). Handlers are handle<O,T> specialised on opcode x type, chained by [[clang::musttail]] return ip->h(...) (:838-848).
• Semantics live in one template. step<O,T>(vm, ip&, fp&) (:378-836) is used by the interpreter and by the JIT helpers (jit.h:12-33, step<O,T> at :31). This is the key asset for AOT.
• Heap. Non-moving, malloc-per-object, singly linked, mark/sweep (:43-60, :107-148). Heap is a fat struct (unique_ptr trace, ~7 Heap* links, flags, zrt::String, std::vector<Reg> slots, unique_ptr<Collection>) - every object is two mallocs. Budget enforced via heapBytes, reserveHeap (:149-152); string creation = one Heap per string (:162).
• GC roots. Constants, globals, every live frame’s ref slots (fns[id].refs, :112-113), result/exception, callback roots, function values, tasks/jobs/timers/rejections. The frames[] array is the stack map source: for j<depth: frame(frames[j].fn, frames[j].fp). Ref slots are zeroed on every call (:426) so the scan is safe; dead refs stay live until overwritten (documented, docs/engines.md:146-147).
• Exceptions. GuestThrow C++ exception thrown by step; each handle<> wraps step in try/catch and calls routeException (:362-369, :841) which walks frames[] using the per-instruction catchPc. JIT: helpers catch and return status 0/1(fatal, message in vm->jitError)/2(guest throw)/3(suspended) (jit.h:33, :141-153).
• Async/generators. AWAIT/YIELD copy the whole frame (std::copy(fp, fp+task->slots.size(), ...)) into the heap task with the resume pc (:223-233, :513-517); resume = execute(vm, fn, fp, pc) (:1067-1083); the JIT has a checked pc->label table for async/gen functions (jit.h:146-153).
• Limits/polling. poll() every 4096 ticks on CALL/JMP/BR/THROW, checks interrupted and deadline (:242-247); JIT polls at backward edges with jitBudget (jit.h:160-165) and in call helpers.
• Bundle/verifier. load() (:863-1029) verifies every operand type and register, branch targets, call signatures, exports; converts branch targets to relative offsets. Guest bytes never contain pointers (:837 comment). Debug map is a sidecar .debug (:1031-1053), fingerprinted by FNV-1a of the bundle.
• Embedding. runtime/vm/embedded.cpp includes main.cpp (one implementation of validation/GC/dispatch/JIT, :1-3).

1.2 The compiler side (compiler/src/emit-bc.ts)

• Every MIR value gets its own register (:127-132); every call/closure/method call copies all args into fresh registers with mov (:311-313, :283-285, etc.); phi edges emit 2 movs per phi (temp then destination) plus a jump (:156-165); constants are not deduplicated (constants.push per use, :180) and are re-loaded from memory each time by K.
• All reference-typed registers are the single tag VM_REF=7 (:13): objects, arrays, closures, promises, generators, maps, dyn. Field access is therefore resolved dynamically per object: vm->field(reg,key,type) does object() checks + std::find over layout.keys + type compare on every FIELDGET/FIELDSET (main.cpp:172-181). Field ids are assigned in first-use order (emit-bc.ts:85-86), so ZBC4 carries no field names, only numeric keys (:498).
• MIR (compiler/src/mir.ts) is an “inspection stage, not the input of the C++ emitter” (mir.ts:3-5); missing passes: inlining, devirtualisation, ranges, bounds, escape, RC optimisation (:5). emit-cpp.ts is direct AST->C++ (decision 0004), with zrt::Ref RC, AsyncFrame/GenFrame state machines (emit-cpp.ts:115, :519) and zrt::g_err status-code exceptions (:3, :733-745).
• Bytecode shape evidence [V, dumped from the built .zbc]: fib = 16 instrs for a 5-line function (3 K, 2 MOV, 2 JMP, 2 CALL); mandelbrot main = 107 instrs / 79 registers with 24 MOV, 19 K, 16 JMP, 7 LOAD + 5 STORE of globals.

1.3 The JIT (runtime/vm/jit.h)

• Direct AArch64 word emission (emit(0x...)), macOS MAP_JIT + pthread_jit_write_protect_np, Linux mprotect (:58-85). Inlines only int/f64 arith/compare/branch/K/MOV/LOAD/STORE; everything else, including every CALL/RET, goes through jitHelper<O,T> = the same step (:12-33, :195).
• Pinning. Only leaf functions pin slots: up to 8 int regs (x21-x28) and 8 f64 regs (d8-d15) chosen by static loop-depth weight (:91-121); non-leaf functions pin nothing. Before every helper, sync(false) stores all pinned slots to the frame, after it sync(true) reloads them all (:131, :154-159). Refs are never pinned, so GC sees everything in the frame. Prologue/epilogue always save 5 x-pairs + 4 d-pairs (:133-135).
• Relocation/absolute address problems for offline use [V]: helper function addresses imm(16,(uintptr_t)fn) (:155), const Ins* of the instruction passed to the helper (:155), address of vm.jitBudget (:161), addresses of vm.constants[b] / vm.globals[b] (:173), and vm->jit[target] indirect call inside the helper (:28). All are 4-instruction movz/movk immediates: none is position-independent.
• Call cost [V by arithmetic]: fib(32) = 7.05M calls; JIT 66 ms = 9.4 ns/call (~30 cycles), interpreter 130 ms = 18 ns, native 1.4 ns, my AOT prototype 4.4 ns.

2. Native vs VM-AOT: what actually differs (option c, explained)

Option (c) (feed MIR straight to C++ with the VM heap ABI) means a second implementation of the VM’s semantics (field key lookups, dyn boxing, promise/generator protocol, collection ops, heap accounting) in the emitter. Every difference shows up as a parity bug against the interpreter; and OTA fallback then needs MIR->bytecode equivalence proofs. It has the highest ceiling (static knowledge of layouts, no dynamic field()), but that ceiling is reachable inside (b) with inline caches and, later, static layout typing in the bytecode. Verdict: no.

3. AOT options, evaluated

Scores: fidelity F, iOS legality I, OTA fallback O, build time B, code size S, speedup P (vs current interpreter unless noted).

(a) AArch64/x86-64 machine code offline from ZBC4 with the existing JIT emitter into .o/.S

• F: high (same helpers/step, already in the 4-mode matrix). I: legal (object linked into app). O: fine (fallback interpreter).
• Effort: every absolute address in jit.h (section 1.3) must become a relocation or a VM-relative offset (x19 already holds VM*); write a Mach-O/ELF object writer or emit .S text with .word; the emitter is aarch64-only, so no x86-64 Linux/Simulator-on-Intel/armv7 (Raspberry Pi 3B+ in 32-bit); a second emitter would be a second bug surface. [V: jit.h:4 only __aarch64__.]
• P: modest. Today’s JIT is 2-4x over the interpreter (66 vs 130 ms fib; 80 vs 350 mandelbrot), limited by helper-per-call and 8+8 pinned leaf-only registers. Fixing that is exactly re-implementing a register allocator and inliner by hand. Verdict: keep the JIT for desktop tier-up (improve it, section 4.3), do not build AOT on it.

(b) ZBC4 -> C/C++ with clang -O2 as the backend (chosen)

• Each ZBC function becomes one C function int fnN(VM*, Reg* fp, uint32_t entry_pc); each register of a scalar type becomes a C local; ref registers stay in fp[] (precise roots, section 5); labels + goto for control flow; direct calls between AOT functions; helper calls (out-of-line noinline noexcept wrappers around step) for everything with heap/GC/throw/suspend semantics.
• F: exact if scalar ops are single-sourced (7.1) and slow ops literally call the same code. I: legal; native code ships in the signed binary. O: see section 6. B: clang -O2 on generated C: my prototype for mandelbrot (107 instrs) compiles in well under a second [I: not timed precisely]; large apps need per-unit TU splitting, -O1/-Os for cold functions and a content-hash cache (risk R2). S: [I] 20-60 bytes of AArch64 per bytecode instruction for scalar-dense code (an inlined helper call is ~5 instrs); the 16-byte-per-instruction bytecode stays in the bundle for fallback/debug, so the AOT build is roughly 2-4x the bytecode size.
• P: measured 4.2x (fib) to 16x (mandelbrot) over the current interpreter on scalar kernels (section 0).

(c) MIR -> C++ reusing emit-cpp with the VM ABI: rejected (section 2). emit-cpp.ts is AST-driven; MIR is not its input.

(d) Other backends from MIR/ZBC

(e) Wasm as intermediate

• wasm2c / w2c2 / WAMR AOT / wasmtime AOT: turns the problem into “port the VM’s heap, GC and ABI to linear memory”: objects are structs in linear memory with a hand-written collector, and roots must live on a shadow stack (wasm cannot scan its own stack) - i.e. the same design as (b) plus an ISA layer, plus lost source-level traces and a marshalling boundary to native zrt/UI. wasm2c output compiled by clang is near-native for numeric code, but everything the VM does differently (dyn boxing, promises, generators, ZincValue ABI) still has to be written in wasm or imported.
• Interpreters: wasm3 is 16-20x slower than native on fib(40) and ~11.8x on CoreMark, wasmtime about 4x faster than wasm3 (older 2019-20 numbers) [W: wasm3 docs/Performance.md, dated by the doc itself]. Our interpreter already sits in that class (13-16x native), so Wasm-interpreted on iOS would not help. Wasmtime’s Pulley portable interpreter and WAMR’s AOT .aot files are native code or JIT-adjacent; a downloaded .aot is executable code (illegal on iOS OTA).
• Wasm GC backend: would hand allocation/GC to a host engine (V8, wasmtime), giving struct/array typing for free and exceptions/tail-calls as instructions. But there is no wasm host on iOS without JIT except interpreters, engines must be embedded, native interop is via imports (marshalling), and Zinc’s non-trivial semantics (promise/generator protocol, budgets, deadline polling, debug traces) would still be reimplemented. It is a whole-runtime replacement, not an AOT mode. Verdict: only as an isolation tier for untrusted plugins (already the position of ios-core-runtime.md).

(f) Futamura projection / specialising the handlers per function (the technique inside (b))

• ivankra/quickjs-aot: qjsc -A “unrolls the interpreter main loop” over a static const bytecode array so clang folds operands; +36% (v8-v7) and +43% (v8-v9) geomean, “-B” baseline half that [W]. LuaAOT (Gualandi/Ierusalimschy): a partial evaluation of the reference interpreter, <500 new lines; “reduced running time 20% to 60%”, up to 2x on numeric code, “not as fast as LuaJIT or Pallene” [W]. weval: Futamura on wasm snapshots with update_context on pc; 2.19x with weval alone, 2.77x geomean with intrinsics, up to 4.39x on SpiderMonkey PBL; AOT-only, cannot register-promote interpreter-visible state such as GC-visible values [W: cfallin.org 2024/08/28].
• Why Zinc should beat those numbers: in dynamic VMs the per-op work (tag checks, ICs, refcounts) is untouched by removing dispatch. In a typed VM the ops are 1-2 machine instructions, so dispatch, frame loads/stores and calls are the cost. The design doc’s own JIT experiment shows 2.2x for register pinning on mandelbrot [D] and my prototype shows 16x over the integrated interpreter.
• How to do it in C++ here: the VM already has step<O,T> specialised on opcode and type; make operands constexpr template args (or an Ops{a,b,c} struct passed by value that folds after inlining). Generated code then literally is the interpreter body with constants folded (the Futamura projection), while the hot scalar ops are also emitted as plain C expressions from the same header of inline functions (7.1).

4. Quick performance wins for the current interpreter/JIT (before any AOT)

Ranked by (impact x confidence) / effort. Attribution of the 3-4.5x gap to prototype numbers is [I]; I did not profile (see 8).

4.1 Compiler (compiler/src/emit-bc.ts, benefits all tiers and the AOT input)

1. Copy coalescing and arg windows: compute call arguments directly into the outgoing window; drop the temp-then-dest phi copies when the interval does not conflict. mandelbrot: 24 of 107 instrs are MOV, 16 are JMP [V]. (:156-165, :283-313)
2. Constant handling: dedupe constants (:180 pushes a new pool entry per use), and add K-forms or immediates; hoist loop-invariant constants; emit scalar K as mov/fmov in JIT/AOT. 19 K in mandelbrot [V].
3. Slot allocation (linear scan on MIR intervals): shrink frames from 79 registers to a few dozen; less ref zeroing per call (main.cpp:426), smaller async save/restore copies (:227, :516), better cache behaviour, tighter GC scan.
4. Compare-and-branch fusion (LT+BR) and jump threading; the prototype found FORLOOP fusion within noise for the interpreter [D], but the JIT/AOT get it for free (no bool materialisation).
5. MIR inlining of small leaf functions: -42% on spectralnorm in the prototype [D]; also needed for AOT since clang cannot inline across the VM’s call protocol unless calls are direct C calls (they will be).
6. Ranges (number -> i32 loop counters) and bounds-check hoisting: listed as missing in mir.ts:5.

4.2 Interpreter (runtime/vm/main.cpp)

1. CALL fast path (:416-429): each call does vm->fns[target], vm->fns[vm->fn].types.size(), a range check against the stack, a loop over fn.refs and a loop over fn.params with vector indexing, plus poll(). Precompute per-callee {frameSize, refs*, params*} in a POD table and embed next = fp + frameSize in the Ins. Expected 1.5-2x on call-heavy code. [I]
2. Inline caches for objects/arrays (:172-181, :632-652): cache {layoutId -> slot} per instruction (32-byte Ins has 4 spare bytes; or shrink Ins to 16 bytes as designed and use a side table), quicken FIELDGET to FIELDGET_CACHED by rewriting ip->h (data mutation only, legal on iOS as the design doc states). Removes std::find + 5 checks per access. Array std::vector<Reg> -> raw pointer+length for INDEXGET/SET.
3. Integer div/mod through doubles (:402-405): replace with integer ops preserving results (INT_MIN / -1 and % -1 need explicit cases, since C++ is UB there while the double path wraps).
4. Accumulator registers carried as handler arguments: -20/-22/-27% on the prototype’s float kernels [D]; needs new bytecode forms.
5. Drop try/catch from hot handlers by making throwing paths noinline cold functions returning status (as JIT helpers already do) [I: EH is table-based, cost is mostly code-shape].
6. Heap: flatten Heap (slots inline or one malloc), size-class free lists, avoid h->bytes() recomputation per allocation (:159-160), avoid one Heap per string temporary.
7. preserve_none and super-instructions: the prototype found them within noise [D] - skip.

4.3 JIT (runtime/vm/jit.h)

1. Direct calls: static targets (CALL, known gen/async flags) can be emitted inline: bump fp by an immediate, store params from registers, push the Frame, bl the callee’s entry. The current path is a C++ helper round trip with try/catch (:12-33), ~9.4 ns per call [V by arithmetic]. Expected 3-5x on fib. [I]
2. Operand-level sync instead of full sync: sync(false)/sync(true) store/reload all pinned slots around every helper (:131, :154-159). A per-opcode table of which operands a helper reads/writes turns that into 1-3 memory ops; pinned callee-saved registers can then live across calls, so non-leaf functions can be pinned too (today leaf gate at :92).
3. Save only used callee-saved registers in prologue/epilogue (:133-135, :202-204).
4. Scalar K as immediates (no address materialisation + load, :172-180).
5. Poll: replace the load/decrement/store counter through an absolute address (:161) by a check of one byte flag set from a watchdog or by ldr relative to x19.
6. Fix the 1024 recursion cap (:21) to match the interpreter (semantic divergence, see 7.3).
7. x86-64 JIT is not planned; AOT-through-clang is the cross-architecture story.

4.4 GC frame precision

Conservative “all ref slots of every live frame, zeroed on entry” (:112-113, :426) costs zeroing and retains dead values. Per-call-site liveness bitmaps (stack maps) at safepoints (allocation, call, await) remove the zeroing and reduce retention. It changes when objects die, which is unobservable today (no finalizers/weak refs in the VM); keep an exact-equal heap-accounting oracle (7.5). [I]

Expected combined effect of 4.1-4.3: interpreter 2-3x (toward the prototype’s 43/78 ms), JIT 2-4x on call-heavy code. [I]

5. Recommended architecture: “ZBC -> C++ AOT, single-sourced semantics”

5.1 Pipeline

TS -> HIR -> MIR -> emit-bc.ts -> app.zbc (+ app.zbc.debug)       [unchanged; improved in Phase 0]
                                       |
                   zinc-vm --emit-aot app.zbc -o aot/          [new mode of the C++ runner: reuses load()+verifier and the opcode table]
                                       |
                    aot/unit_*.cpp  (one TU per module/unit, clang -O2 -ffp-contract=off)
                                       |
              link into the core with libzinc-vm (interpreter stays linked for fallback)

Generator in C++ (inside runtime/vm) so it shares the verifier, Fn/Layout structs and the opcode metadata; emit-bc.ts keeps its own OPS list (“Kept in the same order as runtime/vm/main.cpp”, emit-bc.ts:10) and should not become a second semantics table. Build hookup: zinc build --engine zinc-vm --vm-tier=aot; the CLI already drives CMake for cores (docs/precompiled-core.md).

5.2 Generated function shape

// int status: 0 ok, 1 fatal (message in vm->jitError), 2 guest throw (vm->exception set), 3 suspended
int aot_f17(VM* vm, Reg* fp, uint32_t pc) {          // pc!=0 only for async/gen resume
  if (async_or_gen) switch (pc) { case 0: break; case 23: goto R23; ... default: return fatal(); }
  int32_t r5 = fp[5].i; double r9;                    // scalar regs -> C locals (params loaded from fp)
  ...
  L12: r9 = f64_mul(r7, r8);                         // single-sourced scalar semantics (7.1)
  L13: if (poll_tick(vm)) return poll_slow(vm);      // same tick accounting as interpreter
  L14: { st = aot_f21(vm, next_fp, 0); if (st) { if (handler) goto H14; return st; } r10 = vm->result.i; }
  L15: st = slow<STRING,ZINC_STRING>(vm, fp, /*a,b,c*/ 9, 8, 0x1101, code_ptr(17,15)); ...

• Scalar registers in C locals; before a slow<> op that reads scalar operands from fp[], store just those operands, after it reload just the scalar result (operand-level sync, the fix in 4.3-2).
• Ref registers live in fp[] (the VM stack). This is the shadow stack: exact roots via the existing frames[] + fns[].refs scan, unchanged GC. Conservative C-stack scanning is not recommended: non-moving heap, but object storage is a separate std::vector allocation, so interior pointers would need a second registry [I].
• Frame protocol identical to the interpreter: vm->frames[vm->depth++]={call_site_ip,fp,dst,fn}, vm->fn=callee, depth check at the same limit and message. Needed for GC roots, captureTrace (:320-336) and execute() re-entry.
• Exceptions: callee status 2 -> goto the same-function catch label (scalar locals survive, as the catch target is in the same C function) or return 2. No C++ EH across generated code; slow<> wrappers are noexcept and convert GuestThrow/std::exception to status, exactly like jitHelper (jit.h:33).
• Async/generators: keep all slots in fp[] for such functions (no local promotion) at first; a resume switch on pc as in the JIT (jit.h:146-153); spill-at-suspend promotion can come later.
• Timeout/interrupt polling: ++vm->ticks&4095 on the same instruction classes as the interpreter (JMP/BR/CALL/THROW), so tick counts are equal.
• Source traces: captureTrace needs const Ins* inside fns[f].code; AOT passes &code[pc] to slow paths only (no cost on fast paths). .debug sidecar unchanged.
• Fast scalar entry (optional, Phase 3): for scalar-only signatures without refs, a int32_t f_fast(VM*, int32_t) C-ABI entry avoids the frame round trip; the frame push remains needed only for traces. My prototype (31 ms fib) leaves this on the table (3x native -> ~1.5x). [I]

5.3 Single-sourcing the semantics (the “no compromise” enabler)

1. Split main.cpp into vm_core.h (Reg/Heap/VM/step) + vm_interp.cpp + vm_load.cpp. Change step<O,T>(vm, ip, fp) to step<O,T>(vm, Ops{a,b,c}, ip_for_diagnostics, fp) so that AOT passes compile-time constants and the interpreter passes runtime ones.
2. Move scalar semantics (typedNumber, uint32(), value(), integer/float arith, compare, shifts, CONV, NEG, BITNOT, SQRT..TRUNC) into inline functions sem::add<T>()... used by both step and the generator’s C. A unit test compares every (op, type) pair over random and edge inputs between the interpreter handler and the generated C function (incl. NaN, -0, INT_MIN, f32 rounding). Floating point must be compiled -ffp-contract=off -fno-fast-math, or the generated code can fuse a*b+c differently from separate handlers (my prototype uses -ffp-contract=off).
3. An X-macro opcode metadata table (operand roles read/write/scalar/ref, can-throw, can-GC, can-suspend, can-reenter) drives: the verifier, the JIT’s operand-level sync, the AOT emitter and the GC-stress instrumentation. Today the same knowledge is spread over step, load() verification (:931-1027) and jit.h (:105-113).
4. Slow ops are non-template out-of-line functions per (op, type) (already instantiated by handler()/jitHelperFor()), so generated TUs stay small and compile fast.

5.4 Runtime prerequisites

• One recursion limit in all tiers (16383 is the interpreter’s; JIT’s 1024 at jit.h:21, async/gen/callback cap 1024 at main.cpp:1097, :1176, :1200 - decide and unify).
• Large C stack: AOT recursion uses the C stack. Run execute() on a dedicated thread with an explicit stack (e.g. 64 MB reserve), or check __builtin_frame_address against a limit and raise the same VM error at the same logical depth (a smaller-stack platform must not fail earlier than the interpreter would). [I: iOS secondary thread default 512 KB is from memory of Apple docs, not re-verified]
• Interop: invokeCallback/runTask/generatorStep call execute(); execute() gains if (fn has aot) status = aot[fn](...) beside the JIT branch (:1070-1076).

6. iOS legality and the OTA story

• Rule [W + D]: App Store guideline 2.5.2 forbids downloading code that changes features; DPLA 3.3.1(B) allows code “interpreted and run by an interpreter engine embedded in Your Application” within the reviewed purpose (docs/reports/ios-core-runtime.md:26-31). Native code compiled ahead of time into the shipped, signed binary is fine; downloaded dylibs/machine code/wasm AOT artifacts are not (:47-51). JIT (MAP_JIT) is not available to third parties on iOS (:41). Hence: --vm-tier=jit is desktop/Android/Pi only; AOT is a build-time compile of bytecode that the developer ships.
• Binding rule (recommended): the loader binds vm.aot[fn] only when a content hash of the function’s canonical form equals the hash recorded in the AOT object. Otherwise vm.aot[fn]==nullptr and the interpreter runs the (verified) bytecode. Downloaded bytecode can therefore only (a) select code that was already in the reviewed binary, byte-identical, or (b) be interpreted. This is exactly decision 2 of ios-core-runtime.md:14.
• Granularity problem [V from code]: ZBC4 links the whole program into one function table, one layout table, one constant pool, one global table (emit-bc.ts:54-55, deduped layouts :112-115, first-use field ids :85-86). Any OTA edit shifts indices; a whole-bundle hash would make every OTA edit fall back to the interpreter for the whole app.
• Fix, staged:
  1. Phase A (release builds, no OTA): whole-bundle hash. AOT unit = whole program. Ship this first.
  2. Phase B (mixed mode): ZBC5 adds a symbol section (field names, function names/module id, layout structural descriptors) and a per-module canonical hash (bodies with local indices replaced by symbolic ids). AOT unit = module: direct calls and inlining inside a unit, indirect through a loader-filled table across units (vm->got.fn[k], layout and constant remap tables). An OTA edit to one module makes only that module interpreted; the rest stay native. Cross-unit direct calls (Merkle hash over callees) are not recommended: a changed leaf would demote all transitive callers.
  3. Signed manifest (Ed25519) covers bytecode + AOT hash list; capabilities cannot grow via OTA (ios-core-runtime.md:96-99).
• Cost of the fallback: modified modules run at interpreter speed (10-16x slower on scalar loops today, closer to 4-8x after Phase 0). The UI/runtime services stay native, so app-level impact is smaller (ios-core-runtime.md:16-22).
• Android: same rule in practice (bytecode interpreted OK, downloaded native code not) [W: OTA policy posts]; AOT is arch-neutral because clang targets any of them.

7. What “no compromise” means (proposed definition) and how each item is enforced

Reference oracle = the interpreter (Tier 0) on the same verified bundle, itself parity-checked with native/QuickJS by the existing matrix.

1. Bit-identical observable behaviour: stdout bytes, exit status, error text, uncaught-error stack (function name + file:line:col from .debug), pixel captures, event/timer/microtask ordering, ZINC_VM_STATS counters.
2. Identical limits: recursion depth (16383) and messages, register stack, heap budget failure at the same allocation, timeout/interrupt (same tick classes; timing non-determinism excluded).
3. Identical resource semantics: heap accounting (heapBytes, peakHeapBytes, collections) equal at exit. AOT performs the same allocations in the same order, so equality is a strong oracle. GC triggers are a pure function of heapBytes.
4. Documented, not solved, gap vs native: destruction timing (RC vs tracing GC, docs/engines.md:154-155) and custom Error subclasses/stack info (:190-191). AOT inherits VM semantics; closing this is the separate RC-pass project in zinc-vm.md section 5.
5. Safety: AOT code is only entered for functions whose hash matches; interpreter verifier always runs on the loaded bundle; AOT code contains no guest-supplied pointers, indexes are compile-time constants from verified bytecode; all dynamic checks the interpreter performs (null/object/layout/type/bounds/closure signature) are kept (fast-path guards + slow fallback), never dropped because “the verifier already checked” (the verifier cannot check them: refs are untyped VM_REF).
6. No FP divergence: -ffp-contract=off, no fast-math, same helper for fmod/trunc; FMA fusion is the classic AOT-vs-interpreter mismatch.
7. No un-tiered semantics: every new op lands first in the interpreter step, and AOT/JIT delegate to it until an explicit, tested fast path exists.

7.x Fidelity per option (summary)

8. Measurements (what I ran, what I did not)

• Ran (safe, read-only): the already built binaries under tests/bench/kernels/build/* (gitignored build/; built 2026-09-29, so they predate today’s dirty runtime edits and are stale relative to the working tree) for native, VM --jit and interpreter, plus my scalar ZBC4->C prototype in the scratchpad. Results agree with docs/engines.md’s table (fib 128/67 ms, mandelbrot 349/80 ms): three consecutive runs gave fib native 9.8-10.8, VM 130-133, JIT 66-68, AOT proto 30.8-31.4; mandelbrot 22.2-22.5, 348-354, 80-82, 21.8 ms. One noisier run (load 6) inflated native fib to 24.6 ms; ignore it.
• Not run: node tests/engines/run.mjs --bench-only because it rebuilds via zinc build into tests/engines/build/ and rewrites benchmark.json inside a dirty tree. I did not build the current dirty runtime/vm/main.cpp. No profile (sample/Instruments) of the interpreter; the attribution in section 4 is reading-based [I].
• Prototype scope: aotproto/gen.mjs reads app.zbc, emits C for K/MOV/LOAD/STORE/arith/compare/CONV/JMP/BR/CALL/RET/PRINT/NEWLINE only. Types: I32/U32/F64 (no F32, no refs, no throw, no GC, no polling slow path - vm_poll returns 0). It keeps: Frame push/pop (16 bytes), args stored in the callee frame, depth check at 16383, ++ticks&4095 on JMP/BR/CALL, result via vm->result. It removes: ref zeroing, GC, exceptions, vm->fn maintenance, catchPc. Expect fib to grow by some 10-30% once vm->fn maintenance and exception plumbing are added. [I]
• Per-kernel expectations for a full AOT [I, calibrated by the above and by zinc-vm.md section 3 mixes]:

Comparable systems: QuickJS-AOT +36-43% geomean [W], LuaAOT +20-60% (2x numeric) [W], weval 2.2-2.8x (4.4x max) [W], CPython copy-and-patch ~parity [W], Static Hermes typed AOT emits C for typed code (no JIT) [W: web summaries, not verified in primary docs]. A typed VM has larger headroom than these because per-op work is tiny, which is what the prototype shows.

9. Roadmap, effort, risks, tests

9.1 Phases (one experienced engineer, weeks)

Total P0-P4: about 17-24 weeks. [I]; the design doc’s comparable V6+V7 (Tier 1 c&p + Tier 2 MIR) is 14-18 weeks for desktop-only gains and does nothing for iOS.

9.2 Risks

9.3 Test plan (reuse the four-mode parity matrix)

1. Add zinc-vm-aot to engines in tests/engines/run.mjs:10-11 (--vm-tier=aot). The existing ~62 fixtures (:29), graphics capture matrix (:41), core-cli, and limit tests (array-limits, string-*-limits, heap-64KB loop :183-188) run in five modes.
2. Heap-stat equality: ZINC_VM_STATS JSON must be equal in interpreter, JIT and AOT (collections, heapBytes, peakHeapBytes).
3. GC-stress mode for interpreter/JIT/AOT on every fixture; ASan/UBSan AOT builds (--debug).
4. Mixed mode: for each fixture, AOT a random subset of functions (or modules) and interpret the rest; check exceptions, async resume and generators cross the boundary in both directions.
5. Limits: recursion at 16382/16383/16384 (same result and message in all tiers), timeout and interrupt on an AOT loop (:174-182 analogue), callback re-entrancy (callback-bench).
6. Stack traces: identical guestDiagnostic text (uncaught guest exception with .debug) across tiers.
7. Numeric micro-tests: every (op,type) over edge inputs, interpreter vs generated C.
8. Bench: extend --bench list with nbody, spectralnorm, binarytrees, mapset, sort (they exist in tests/bench/kernels), and add an AOT column. Continue to keep raw samples.
9. Verifier fuzz stays interpreter-side (run.mjs:119-147); add a test that mutated bytecode never binds AOT code (hash mismatch -> interpreter).

10. Sources

Repository (all read):

• runtime/vm/main.cpp (interpreter, GC, loader/verifier, async/generators, callbacks), runtime/vm/jit.h, runtime/vm/abi.h, runtime/vm/embedded.cpp
• compiler/src/emit-bc.ts, compiler/src/mir.ts, compiler/src/hir.ts (skimmed), compiler/src/emit-cpp.ts (structure and async/error handling)
• docs/engines.md, docs/engine-progress.md, docs/precompiled-core.md, docs/reports/zinc-vm.md, docs/reports/PERF.md, docs/reports/ios-core-runtime.md, tests/engines/run.mjs

Web (WebSearch/WebFetch, summaries by a small model; treat numbers as [W], not independently reproduced):

• ivankra/quickjs-aot: https://github.com/ivankra/quickjs-aot
• weval (Fallin): https://cfallin.org/blog/2024/08/28/weval/ , paper https://cfallin.org/pubs/pldi2025_weval.pdf
• LuaAOT: https://github.com/hugomg/lua-aot-5.4 , paper https://dl.acm.org/doi/10.1145/3475061.3475077
• Copy-and-patch: https://arxiv.org/abs/2011.13127 ; CPython PEP 744: https://peps.python.org/pep-0744/
• wasm3 performance: https://github.com/wasm3/wasm3/blob/main/docs/Performance.md
• MIR project: https://github.com/vnmakarov/mir
• musttail / preserve_none: https://blog.reverberate.org/2025/02/10/tail-call-updates.html , https://discourse.llvm.org/t/rfc-exposing-ghccc-calling-convention-as-preserve-none-to-clang/74233
• Static Hermes overview (secondary): https://medium.com/@elves.silva.vieira/javascript-achieves-breakthrough-performance-with-static-hermes-6286b0ac8ef7
• OTA/App Store 2.5.2: https://saagarjha.com/blog/2020/11/08/fixing-section-2-5-2/ , https://www.otakit.app/blog/app-store-compliant-ota-updates
• Wasm runtime perf context: https://00f.net/2023/01/04/webassembly-benchmark-2023/

Scratchpad artefacts (not in the repo): aotproto/gen.mjs (ZBC4 -> C, scalar subset), aotproto/rt.h, aotproto/main.c, aotproto/bench.mjs, dump.mjs (bytecode histogram).

QuickJS JIT tier and real AOT mode for Zinc: research and roadmap

Date: 2026-09-30. Host: Apple M1 Pro (arm64), macOS 24.6, Apple clang 21, load average 5-7 during timings. The Zinc tree was dirty and was not modified. Clones live in the scratchpad: quickjs-aot/, quickjit/, quickjs/ (quickjs-ng master).

Legend: [V] verified here by running or reading code. [W] from a web source, not reproduced. [I] my inference.

Paths below are relative to /Users/mowmow/Lab/zinc unless prefixed SP/ (the scratchpad).

0. Verdict

1. Zinc embeds quickjs-ng 0.17.0 (amalgam), not Bellard’s tree [V]. plugins/script/vendor/quickjs/quickjs.h:1458-1461 gives QJS_VERSION_MAJOR 0 / MINOR 17. docs/licenses.md:17 says the same. The build is plain -O2 on the amalgam (compiler/src/engines.ts:54-55).
2. Zinc’s QuickJS runner parses ES source at every start. runtime/vm/quickjs.cpp:226 calls JS_Eval(... JS_EVAL_TYPE_MODULE|JS_EVAL_FLAG_COMPILE_ONLY) on the source text. compiler/src/engines.ts:130-170 (bundleJs) copies .mjs files. There is no bytecode path, no JS_WriteObject and no AOT. Phase 0 is therefore real and cheap.
3. The only existing AOT that keeps full QuickJS semantics is ivankra/quickjs-aot (MIT, Futamura projection). I built it and reproduced the effect: qjsc -A is 1.4x on fib and 2.2x on mandelbrot against its own tail-dispatch interpreter, and only 1.14x on an object/alloc kernel. It is based on Bellard’s 2025-09-13 tree, not quickjs-ng.
4. Against quickjs-ng 0.17 the AOT advantage on object code disappears. ng’s interpreter is already about 20-25% faster than that Bellard base on mandelbrot and objects [V]. quickjs-aot on the object kernel was 0.71 s against 0.61 s for stock ng. Any AOT for Zinc must therefore be ported onto ng, or ng’s improvements ported to it.
5. Tail-call dispatch alone buys about 0-6% on this M1 Pro with clang 21 [V]. The published “+25%” (Mac M4, Debian VM) is not reproduced here. Do not budget it as a headline win.
6. The biggest realistic gains, in order of certainty:
   • (a) Emitter hygiene. Math.fround for f32 costs about 2x on a float loop [V, Section 4.3]. Zero engine work.
   • (b) Bytecode precompile plus PGO/LTO build. Startup and about 10-20% [I].
   • (c) AOT -A ported to ng. 1.5-2.2x on numeric loops, 1.1-1.2x on object code.
   • (d) Interpreter inline caches for get/put field. Published +22% Octane geomean on a QuickJS fork [W]. Stock ng 0.17 has none [V].
   • (e) A baseline JIT. Expensive, and it does not fix refcounting or the tag/16-byte JSValue costs. The evidence for it on QuickJS is a single MIT third-party project whose own docs contradict each other on wins.
   • (f) Typed specialization from Zinc types. The only route to Zinc-VM-class numbers (5-10x over the interpreter on numeric kernels) [I, anchored on docs/reports/zinc-vm.md:228-241].
7. iOS: Phases 0, 1 and the IC work are legal there. Phases 2 and 3 as a runtime JIT are not (docs/reports/ios-core-runtime.md:40). Phase 3 can still be emitted as AOT.

1. Zinc’s current QuickJS integration [V, read]

Two observations that shape the whole plan:

• The kernels in PERF.md are numeric. Zinc UI apps (examples/hero, remarkable/notes) are closure, object, string and array heavy. Numeric AOT wins will not translate 1:1. I did not profile a real Zinc UI app under QuickJS; that is the first thing to do (Section 6, Phase 0).
• The QuickJS engine’s job in Zinc is parity and dev tooling (docs/engines.md intro), not shipping performance. Investment in it competes with the Zinc VM’s own Tier 1/Tier 2 plan (docs/reports/zinc-vm.md:247+), which already targets the same use cases with typed semantics. A QuickJS JIT is justified mainly where arbitrary untyped JS must run (zinc:script, npm code in the “Zinc Core for iOS” bridge, docs/reports/ios-core-runtime.md:59).

2. Existing work

2.1 ivankra/quickjs-aot (SP/quickjs-aot, cloned at cee72b9, “QuickJS-AOT 20251209”) [V]

• License: MIT (Bellard’s QuickJS license file).
• Base: Bellard QuickJS, VERSION 2025-09-13. It is not quickjs-ng.
• Mechanism (first Futamura projection):
  1. The interpreter is first rewritten to tail-call dispatch. Every opcode is a separate js_OP_xxx() function ending in __attribute__((musttail)) return js_tail_dispatch_table[*pc](...). Uses preserve_none when available (quickjs.c:53-61).
  2. aot-parse.py (90 lines) parses the preprocessed quickjs.c, extracts each js_OP_* body into aot-table.h (Makefile:346-349), and rewrites the local labels.
  3. qjsc -A (qjsc.c:371-400) calls aot_compile() (quickjs.c:59798-59945). For each function it emits one C function with a labeled block per bytecode offset (pcN:), the opcode body pasted in, operands constant-folded against a static const uint8_t aotN_bytecode[], and a computed-goto pc_table for generator/async re-entry (quickjs.c:59888-59889).
  4. -B emits a label at every opcode. It is a proxy for a template JIT: it stops the C compiler optimizing across opcodes.
• Integration and safety model. This is the key design point for “no compromise”:
  • The AOT function has the same signature as an interpreter handler and is entered from JS_CallInternal (quickjs.c:17584-17585) with the same JSStackFrame, sp, arg_buf/var_buf. Refcounting, the cycle collector’s frame scan, exception unwinding, generators, cur_pc/backtraces and interrupts all use the interpreter’s own code because the handler bodies are the interpreter’s.
  • Serialized bytecode carries an aot_id (quickjs.c:37498, 38433). On load, memcmp against the compiled-in bytecode decides whether to bind aot_funcs[id] (quickjs.c:38537-38546). A mismatch silently falls back to the interpreter (it prints to stderr). The bytecode stays authoritative, so Function.prototype.toString, line numbers and the debugger keep working.
  • Prototype quality: prints “aot enabled” to stderr, no versioning of the handler table, needs a Python step and clang (musttail + preserve_none).
• Author’s numbers [W, README] (Mac M4, Debian 13 VM, median of 20): geomean v8-v7 base 2582, tail 2800 (+8%), -A 3518 (+36% over base). v8-v9 base 5425, tail 6146, -A 7784. Per benchmark: Crypto +78% (tail vs base), NavierStokes +52%, Mandreel +68% (-A over base +103%); Richards +25%, DeltaBlue +25%. -B gives about half the -A gain.
• Author’s own future idea: JIT by compiling hot functions to .so and dlopen, blocked by QuickJS’s many static functions.

My reproduction [V], min of 7 wall-clock runs, -O2, same machine, one shared build of the runtime library:

Sources: SP/quickjs-aot/bench/{fib,mandel,objs}.js, t2.sh, t3.sh. Checksums matched across all binaries.

Reading it honestly:

• -A is real and reproducible: 1.4x / 2.2x / 1.14x over its own tail interpreter.
• Tail dispatch itself was neutral on this CPU/compiler (fib +1%, mandel -6%, objs 0%). The author’s +25% is not reproduced on M1 Pro / clang 21. Consistent with the wider finding that clang’s computed-goto code is already good on arm64. See also Reverberate’s follow-up on tail-call interpreters and a compiler regression that inflated CPython’s early numbers [W: blog.reverberate.org/2025/02/10/tail-call-updates.html].
• The quickjs-aot base is older than ng. Stock ng 0.17 beats the Bellard base on mandelbrot (0.80 vs 0.98) and objects (0.61 vs 0.82), and is slower on fib (0.173 vs 0.152). Result: -A on Bellard base loses to plain ng on the object kernel and wins about 1.9x on mandelbrot, 1.6x on fib. Porting -A to ng is a precondition.
• Size [V]: microbench.js (1584 lines) generates a 2.3 MB .c file. Embedded-binary size 1.46 MB with -A vs 1.23 MB for plain qjsc bytecode-in-binary (both include the engine). Code growth is roughly 20% on this input; the C is large because each opcode body is inlined per instance.
• Compile time of the emitted C was not measured cleanly (my time output was swallowed by warnings). The cost is dominated by clang on a multi-MB file: [I] tens of seconds for a large app at -O2.

2.2 bnoordhuis/quickjit (SP/quickjit, HEAD d5a3e72) [V]

• QuickJS fork, JIT = bytecode -> C -> embedded tcc (libtcc.c, tccgen.c … in the tree). README: “same license as QuickJS. tcc is LGPL”.
• Backend files present: x86_64-gen.c, x86_64-link.c, i386-asm.c. There is no arm64-gen.c. So no Apple Silicon, no Pi, no rMPP. Not an option for Zinc’s targets.
• Unfinished (“support put_arg opcode” is the last commit) and hand-translates each opcode (as quickjs-aot’s README notes). LGPL in a statically linked app is a problem for Zinc’s licensing (docs/licenses.md is MIT-only for engines). It also needs a compiler at runtime, which is why it cannot reach iOS.

2.3 longbridge/quickjs-jit [W: github.com/longbridge/quickjs-jit, PRs #21 and #30]

• MIT. “A high level binding” (Rust, rquickjs-compatible) of QuickJS-NG with JIT patches. ABI is tightly coupled to a patch version.
• Design from PR #30: Tier 1 baseline emitting machine code directly (x86-64 primary), Tier 2 lowering to Cranelift IR. Inline refcount DUP/FREE in generated code, closures, exception regions, direct native-to-native calls, later polymorphic property ICs (up to 4 shapes), guard elimination, bounds-check elimination. Frame materialization on deopt or exception.
• Claims: 28 of 35 x86-64 Linux scenarios significantly faster than the QuickJS interpreter, 5 tied, 2 slower. A fibonacci scenario “26.97x faster than QuickJS”, still 0.72x of Bun’s speed. But an earlier doc-PR (#21) reported only “8 faster, 1 tied, 13 slower”, so the project is fast-moving and the numbers are self-reported and not reproduced. macOS aarch64 marked untested.
• Value to Zinc: reference architecture, an existence proof of a QuickJS-ng JIT with refcounting and exceptions handled, and a codebase to read. Adopting it as a dependency is risky (patch-version ABI lock, x86-64 first, Rust-centric packaging, moving target).

2.4 quickjs-ng and Bellard [V + W]

• ng 0.17.0 has opcode fusion (quickjs.c:18941 region comment; docs diff.md:43) and a faster allocator, but no inline caches in the code I inspected: OP_get_field does find_own_property + prototype walk on every execution (quickjs-amalgam.c:31580-31627, find_own_property1 at :17685-17700 is a hash-chain walk). ng’s docs page lists “polymorphic inline caching” [W: quickjs-ng.github.io/quickjs/diff/]. I found no such code in the vendored 0.17.0 amalgam or in the ng master clone (SP/quickjs, HEAD 2f0aa72); treat the doc line as unverified or as unreleased.
• ng dispatch: computed goto on non-MSVC/Emscripten (quickjs-amalgam.c:9222-9233). No tail-call dispatch.
• ng serialization: JS_WriteObject/JS_ReadObject and qjsc exist (quickjs.h:1267-1287), i.e. Phase 0’s precompile is supported API. No heap snapshot facility in QuickJS/ng.
• gkurt/quickjs PR #9 [W]: 15 optimizations, +22.1% Octane geomean (RayTrace +51%, Crypto +49%, Gameboy +60%, zlib +41%), driven by callgrind. Property caches enlarged, dictionary-mode shapes, dense-array revert, a 256-entry per-context global-variable cache with self-validation, OP_to_int32, fast apply. Semantics preserved by self-validating cache entries and cache invalidation on descriptor conversion. Peak memory +1.6%. This is the best public evidence for what interpreter-level work gives on QuickJS.
• Bellard’s MicroQuickJS is a different language subset; see SP/mquickjs.md from the earlier assessment. Not relevant to a JIT/AOT for full ES.

2.5 weval, LuaAOT, Deegen, copy-and-patch [W]

• weval (bytecodealliance): partial evaluator over WebAssembly snapshots; the interpreter needs about 100-200 lines of intrinsics (context updates on pc change, specialization requests, virtual locals/stack ops). Results: SpiderMonkey PBL + weval 2.17-2.19x over the same interpreter (PLDI’25, geomean 2.77x vs the generic interpreter including the PBL gain; up to 4.39x), PUC-Lua 1.84x [W: cfallin.org/blog/2024/08/28/weval/, arxiv.org/abs/2411.10559]. It is Wasm-only, so it applies to QuickJS only if QuickJS is run as Wasm. Not native arm64. Conceptually identical to quickjs-aot’s -A; the gains are also consistent (about 2x on numeric).
• LuaAOT (Gualandi and Ierusalimschy, SBLP 2021): about 500 lines, run-time reduction 20-60%, biggest on Mandelbrot (about 60%), smallest on K-Nucleotide (20%). Gain comes from removing decode/dispatch, so it depends on instruction mix [W: inf.puc-rio.br/~roberto/docs/paper-aot-preprint.pdf]. This matches quickjs-aot: 2.2x (54% less time) on mandelbrot, 1.14x on object code.
• Copy-and-patch (Xu and Kjolstad, OOPSLA’21) and CPython 3.13 JIT: stencils are compiled by LLVM from C templates with relocation holes, then memcpy’d and patched at run time. Code quality approaches LLVM -O0/-O1 quality with compile times orders of magnitude lower [W]. CPython’s 3.13 result was modest (single-digit % on pyperformance) because its bytecode is not typed [W, tonybaloney.github.io/posts/python-gets-a-jit.html], which is the point: a stencil JIT removes dispatch, not the semantics cost of generic operations. Requires clang at build time only. This is the design already sketched for Zinc VM Tier 1 (docs/reports/zinc-vm.md:247-282).
• Deegen (LuaJIT Remake, arXiv 2411.11469): generates an interpreter and baseline JIT from one description; x86-64 focused in the paper. Too invasive for QuickJS.
• Static Hermes / Hermes [W]: typed AOT, 2-5x faster than Hermes interpreter on typed code; even the Hermes team says untyped AOT is not a win over a high-tier JIT. Porffor: AOT JS to Wasm/C, incomplete ES coverage, so it violates “no compromise”. Kiesel, Boa: not investigated in depth (I did not read their code; I list them only as further interpreters without a JIT).

3. Why QuickJS is slow (and what each technique can fix)

All code refs are the vendored amalgam plugins/script/vendor/quickjs/quickjs-amalgam.c unless noted.

3.1 The real costs [V read, I estimate]

1. JSValue is a 16-byte {union, int64 tag} struct on 64-bit (quickjs.h:315-335; NaN-boxing only on 32-bit, quickjs.h:173-175, 251). Every operand-stack slot, argument and local is 16 bytes, so twice the memory traffic of a NaN-boxed engine. The tag is checked on every arithmetic op (OP_add, :32138-32165: int+int with overflow to double, double+double, mixed, else slow path).
2. Reference counting on every stack move. js_dup(pr->u.value) on every property read and JS_FreeValue(sp[-1]) after (OP_get_field, :31580-31627). Every get_loc/put_loc of a heap value is a dup/free pair. A cycle collector (gc_decref) runs on top.
3. Property lookup is hash chain by atom per access with prototype walk: find_own_property into a per-shape hash table, then p->shape->proto on miss. No inline caches at the bytecode site. Method calls do it twice (own property miss then prototype hit). Exotic objects (arrays, typed arrays) take a slow path (:31607-31612).
4. Calls are heavy. JS_CallInternal sets up a JSStackFrame, allocates arg/var buffers, checks stack depth and links the frame list. Recursion cost dominates fib.
5. Dispatch and decode. Variable-length opcode encoding (SHORT_OPCODES), decode of operands on every execution, indirect branch per opcode. This is what tail dispatch and AOT remove; it is a smaller share on modern cores than people expect (my tail-vs-goto result).
6. No type feedback. Nothing records “this add always sees int32” or “this site always sees shape S”.

3.2 What each technique realistically gives

Hard ceiling of any bytecode-level speedup that keeps QuickJS’s object model: refcounting and 16-byte values remain. Even quickjs-jit, with inline refcounts and Cranelift, describes itself as slower than Bun on all 35 scenarios [W]. Do not promise V8-class results.

3.3 What “no compromise” must mean here

Concrete acceptance rules; each is testable:

1. Semantics. Every ES behaviour QuickJS-ng 0.17 produces (including error messages, Error.stack line numbers, property enumeration order, getters/setters, Proxy, generators, async, TDZ, eval, with) is unchanged. Gate: quickjs-ng tests/ and test262 as run by SP/quickjs/run-test262.c, with results equal to the interpreter, plus tests/engines/run.mjs byte-exact parity in all four modes.
2. Bytecode stays authoritative. Generated code is a specialization of the same handlers keyed by a bytecode hash (as quickjs-aot’s memcmp, quickjs.c:38537-38546). If the hash, engine version or ABI does not match, run the interpreter. No silent divergence.
3. Deopt/fallback. For JIT and typed paths: every fast path has a guard and a slow path that is the interpreter handler. Frame state must be exactly reconstructible at every guard, exception and call.
4. Refcount/GC safety. At every point where QuickJS can run the cycle collector or call out (any JS_Call, allocation, property get on exotic/getter, JS_FreeValue with finalizers), the operand stack sp[], arg_buf and var_buf in the JSStackFrame must hold owned values exactly as the interpreter would. AOT via handler pasting gets this for free. A register-allocating JIT must spill before every such point. Reference counts must balance on every exit path, including exceptions.
5. Exceptions. Throw goes to the same catch/finally offsets, with sf->cur_pc = pc set before anything that can throw (as OP_get_field does, :31615). Host errors (memory limit, interrupt) produce the same uncatchable behaviour Zinc relies on (runtime/vm/quickjs.cpp:267).
6. Limits. The interrupt counter and stack-depth checks (js_poll_interrupts, JS_INTERRUPT_COUNTER_INIT 10000, :9733, :19534) must fire on back-edges and calls in compiled code. Zinc’s 60 s deadline and zinc:script time limits depend on this.
7. Generators/async resume into compiled code at any yield/await point (quickjs-aot does it with a per-function pc_table, quickjs.c:59888-59889).
8. Reproducible builds. Output is deterministic and content-addressed; the engine version is part of the fingerprint (engine.json already carries a fingerprint, compiler/src/engines.ts around fingerprint: hash(...)).

4. Additional measurements I ran

4.1 Setup

All on SP/quickjs-aot/bench/, M1 Pro, Apple clang 21, -O2, load average 5-7 (noisy; I report min of 5-7 runs and only trust differences above about 10%).

4.2 Table

See Section 2.1.

4.3 What Zinc’s emitter costs QuickJS (ng 0.17.0, 10M iterations, SP/quickjs-aot/bench/fr.js) [V]

Math.fround is a native C function call through the generic call path, about 16 ns each; it doubles the float loop. compiler/src/emit-js.ts:40, 185, 202 inserts it after every f32 op. Options that need no engine change: (i) keep f32 math in f64 and fround only at stores/escapes when the frontend can prove no observable difference (needs care to keep bit-exact parity with native f32; the parity tests will catch violations), (ii) a QuickJS-specific OP_fround opcode (Phase 1 extension: a few lines in ng), (iii) Float32Array store/load round trip is worse.

5. Constraints specific to Zinc targets

• iOS: no JIT for third parties (docs/reports/ios-core-runtime.md:40). AOT must be linked at build time and shipped in the signed app. OTA-updated JS keeps the interpreter. dlopen of downloaded code is out.
• Targets in tree: macOS, Linux, rpi1, rmpp (plugins/script/plugin.json:8-13). The Pi 3B+ (aarch64) and rMPP (aarch64 Linux) can run arm64 JIT; rpi1 is ARMv6 32-bit and can only run the interpreter [I]. musttail+preserve_none need clang >= 19 on x86-64/AArch64 [W: reverberate blog]; on 32-bit ARM or GCC there must be a fallback (quickjs-aot’s #else DIRECT_DISPATCH branch, quickjs.c:63-65).
• Hardened runtime on macOS: JIT needs MAP_JIT + the JIT entitlement when signed; already handled by Zinc VM Tier 1 (runtime/vm/jit.h:65-80, docs/engines.md JIT section). Reuse that executable-memory code.
• Existing Zinc JIT code is not reusable as a QuickJS JIT: runtime/vm/jit.h compiles Zinc’s typed 16-byte-instruction bytecode with typed unboxed registers (jit.h:1-40, helper jitHelper<O,T>); QuickJS bytecode is a stack machine with boxed tagged values. What is reusable: MAP_JIT handling, icache flush, the helper-call/status-code protocol (“no C++ exception through JIT frames”), the poll-on-back-edge idea, and test scaffolding.

6. Roadmap

Effort is engineer-days for one experienced person working in the tree, including tests, not calendar time. Speedups are vs current stock ng 0.17 -O2 unless stated.

Phase 0: cheap wins and the measurement harness (4-7 days)

Contents:

1. Profile a real Zinc UI app under --engine quickjs (hero, notes): cycle count per opcode class, perf/Instruments. Decide priorities from data. Add examples/*-derived kernels to tests/engines/run.mjs --bench (object, closure, string, array). (1-2 d)
2. Bytecode precompile in buildEngine (compiler/src/engines.ts:34): compile the bundle to bytecode at build time (a small host tool linking the vendored amalgam using JS_WriteObject; keep the .mjs next to it for debug/source maps), and change loader (runtime/vm/quickjs.cpp:226) to JS_ReadObject + JS_ResolveModule/js_module_set_import_meta handling, falling back to source when the fingerprint (engine version + flags) mismatches. Bytecode is version-specific and unverified, so treat it as trusted build output only, never from zinc:script input. (2 d)
3. Build flags: -O3, LTO, -fno-semantic-interposition, and a PGO profile from the bench kernels (compiler/src/engines.ts:54-55). (1 d; expect 10-20% [I])
4. Emitter hygiene for f32 (emit-js.ts:40, 185, 202); measure with the parity matrix. (1-2 d; up to 2x on f32 loops [V])
5. Optional: port tail-call dispatch to ng only as the prerequisite for Phase 1 (item is in Phase 1’s cost, not here). Do not ship it as a standalone speedup.

Expected: startup improvement proportional to the bundle; steady state +10-25% from PGO/LTO/emitter. Risk: low. Test plan: node tests/engines/run.mjs full matrix (all four modes agree byte-exact) and --bench before/after; add a test that a stale bytecode fingerprint falls back to source. License: no change (MIT).

Phase 1: real AOT mode, zinc build --engine quickjs --aot (20-30 days)

Goal: the qjsc -A mechanism on quickjs-ng 0.17 (not the Bellard base), iOS-safe (static, no run-time code generation).

Work items:

1. Port tail-call dispatch to ng’s interpreter (ng has diverged: opcode fusion, different CASE macros). This is the prerequisite because aot-parse.py extracts js_OP_* bodies from the tail-dispatch form. Alternative to avoid diverging from ng: keep the interpreter unchanged and add a generation-time extraction (like aot-parse.py but from the computed-goto form). More fragile; prefer the tail form on Clang and keep the goto path for GCC/MSVC. (6-9 d)
2. Port AOT emission (aot_compile, aot_emit_table, bytecode aot_id serialization, load-time memcmp binding) to ng and clean up: drop the stderr prints, add a hash of (engine version, handler table, bytecode) so a mismatched interpreter falls back, add JS_ATOM remapping check (bytecode atom indices are per-runtime tables; quickjs-aot relies on the deserialized bytecode being the same as compiled-in, which memcmp validates only after load). (5-8 d)
3. Zinc integration: a zinc-qjsc build tool (from the vendored amalgam + a small generator) invoked by buildEngine when --aot is passed; generated .c compiled with clang into the runner via the CMake in engines.ts:41-70; engine.json fingerprint includes the AOT table hash; zinc export ships the binary only. Add --aot to zinc run/build/export/capture. (4-6 d)
4. Hardening: run ng’s tests and test262 on the AOT build; async generators, class fields, module top-level await, eval/new Function (these are not AOT’d and must interpret), stack-overflow and interrupt parity, backtrace line numbers. Compile-time budget: large apps produce multi-MB C (2.3 MB for 1.6k JS lines [V]); add a function-level filter (skip cold startup functions) and a size cap. (5-7 d)

Expected speedup [V/W]: numeric loops 1.5-2.2x (fib 1.6x, mandelbrot 1.9x vs stock ng [V]; because ng is already faster than the Bellard base on the object case, the port gets about 1.1-1.2x there [V/I]); v8-v7 geomean +25-36% over the interpreter [W]. String/regexp/JSON-bound code about 1.0x [V microbench -6% total]. Binary +~20% [V].

Risks: (a) ng 0.17’s handler bodies use more gotos and macros than Bellard’s; the Python extractor breaks on them. (b) compile time and code size on real apps. (c) musttail+preserve_none availability (clang >= 19; need CI on Linux/Pi; rpi1 gets interpreter only). (d) Maintenance: every ng bump regenerates the table (add a CI job that rebuilds and diffs). (e) The -A win is per-function; zinc:script code loaded at runtime cannot use it, only the build-time-known app.

Test plan: full tests/engines/run.mjs with --engine quickjs --aot as a fifth mode (“quickjs-aot”) so every fixture is byte-compared with native/VM/JIT/QuickJS; the quickjs-ng test suite and test262 under the AOT build (must equal interpreter pass/fail set); --bench including new object/closure kernels; a “mismatch falls back” test.

Licensing: quickjs-aot (MIT), quickjs-ng (MIT), Bellard QuickJS (MIT). Generated C inherits the MIT notice of the engine code it embeds; ship the notice as docs/licenses.md already does for the engine.

Phase 1b: interpreter inline caches for get/put field (10-15 days, independent, do in parallel)

• Per-site cache {shape*, slot index, proto holder?} in a side table in JSFunctionBytecode (operand is a u32 atom, OP_get_field at :31580), consulted before find_own_property. Follow gkurt’s self-validating and descriptor-conversion invalidation approach [W]. Must hold a shape reference (or epoch) to avoid ABA on freed/reused shapes; invalidate when a shape is mutated in place (dictionary mode); do not cache exotic or accessor properties.
• Expected 10-25% on property-heavy code [W: +22% Octane geomean, RayTrace +51%]; quantify on Zinc UI kernels.
• Risk: moderate (shape lifetime, Object.defineProperty, Proxy, TypedArray receivers). Test: quickjs-ng + test262 + parity matrix + a fuzz test mutating prototypes between calls.
• Note it composes with Phase 1: AOT bodies can constant-fold the cache-slot address.

Phase 2: baseline JIT with ICs on macOS/Linux/Pi/rMPP (60-100 days, high risk; recommend gating on Phase 0-1 data)

Design options:

• 2A. Copy-and-patch from the tail-dispatch handlers (recommended if a JIT is needed). Compile each js_OP_xxx as a stencil with clang, extract with relocations (Xu and Kjolstad; CPython’s Tools/jit), emit sequences by memcpy + patch immediates (operands, pc, jump targets, cache slots). Same source, so AArch64 and x86-64 come from one handler set, matching the stencil approach already planned for the Zinc VM (docs/reports/zinc-vm.md:249-282). Because the interpreter frame is the JIT frame, GC/exception/generator semantics are inherited (like AOT). Add stencils with ICs and int fast paths for get/put field, get_array_el, call, add/sub/lt with int32 specialization. Gain over Phase 1 arises only from the specialization, not from JIT itself, since -A already removes dispatch. So its real advantage over Phase 1 is coverage of code unknown at build time (zinc:script, OTA JS).
• 2B. Register-allocating method JIT (like quickjs-jit’s Tier 1 + Cranelift Tier 2) with frame materialization on deopt. Much larger; refcount elision and spill at every safepoint are subtle. Only pursue if 2A + ICs is insufficient. Adopting or forking longbridge/quickjs-jit (MIT) is a possibility for reading and borrowing, not for direct adoption (patch-version ABI lock, x86-64 first, macOS aarch64 untested [W]).
• Reject: bytecode->C->tcc (quickjit): x86-64 only [V], LGPL [V], needs a compiler at run time, no arm64.

Work for 2A: stencil generator (15-20 d), arm64 emitter/patcher (10-15 d), x86-64 (10-15 d), executable memory manager reusing runtime/vm/jit.h:65-80 (3 d), tier-up counters + code cache invalidation on JS_FreeRuntime (5 d), ICs (Phase 1b), hardening (15-20 d).

Expected speedup: on top of Phase 1b, another 1.3-2x on numeric loops if int-specialized stencils are added, otherwise about Phase 1 level [I; weval/LuaAOT/-B evidence [W] says the dispatch-removal share is about 1.2-2x and the rest needs typing].

Risks: highest of all phases: GC safety at safepoints, generator/async frames, debugger/stack traces, W^X on macOS (MAP_JIT, entitlement) and iOS impossibility (interpreter/AOT only there), Linux SELinux/W^X policies on some distros, maintenance against every ng bump. Test: Phase 1 matrix plus a JIT-forced mode (threshold 1) that JITs everything, plus test262 under forced JIT, plus ASan/UBSan (--debug path exists in engines.ts:44).

Licensing: MIT engine + Zinc code; stencil approach needs clang at build time only. I did not investigate patents on copy-and-patch; CPython (PSF) ships it, and the paper is public, but check before shipping.

Phase 3: typed specialization using Zinc type info (35-60 days; largest upside on numeric code, works as AOT so it is iOS-safe)

What Zinc knows and QuickJS cannot: Sema has numberKind, ZT types (i32/u32/f32/f64/bool, classes with known layouts) (compiler/src/sema.ts, used in emit-js.ts:9, 99-100, 195-202), which emit-js currently erases. Emit type facts as a side channel next to the JS (per function: parameter/local/return kinds, class layouts), and let the AOT generator (Phase 1) consume them:

1. Numeric locals: unboxed int32_t/double C locals for provably-typed slots. Entry guards on argument tags (int32 or number) with jump to the generic AOT’d body on mismatch (deopt = “run the generic version from the function start”, legal because the typed version has no side effects before its guards, or from a safepoint map otherwise). |0 and fround emitted by Zinc become native truncate/(float) operations.
2. Known classes: guard shape == S once per function entry or loop preheader, then direct slot loads and stores; deopt if a prototype or shape changes (shape epoch counter).
3. Refcounts: keep a plain boxed slot for anything that escapes; unboxed ints/doubles need no refcounting, which is where the largest savings on numeric code come from.
4. Soundness: TypeScript types are not sound. Only Zinc’s checked subset, where the emitter already inserts runtime coercions (|0, Math.fround, $z.idiv), can be trusted, and every entry guard revalidates at run time. any, casts through unknown and native ABI boundaries stay generic. This is exactly what “no compromise” requires: the typed body is a proven specialization of the emitted JS, not a different language.

Expected speedup [I, anchored on zinc-vm.md:228-241 and PERF.md]: nbody/spectralnorm-class kernels 5-10x over the interpreter (the Zinc VM’s est. 8-9x is with typed registers and MIR inlining; a C-compiled typed body with a boxed calling convention should be in the same range), fib/mandelbrot 3-6x; object/string/UI code 1.2-2x. Honest caveat: this converges on the Zinc VM design already in the tree; the incremental value of doing it inside QuickJS is that arbitrary untyped JS and zinc:script still run on the same engine and the parity story stays “same JS on QuickJS”.

Risks: overflow semantics for i32 (must match |0), f32 rounding parity (byte-exact outputs), deopt correctness, effort for class-layout guards. Test: engine parity matrix plus a differential fuzz of typed vs generic on random typed programs.

7. Recommended order and what not to do

1. Phase 0 now (including profiling a real UI app). It gives evidence and low-risk wins.
2. Phase 1b (ICs) and Phase 1 (AOT) next, on ng. Prefer ICs first if the profile shows property access dominates UI apps.
3. Phase 3 typed AOT only if numeric-heavy Zinc apps must run on QuickJS at speed; otherwise steer such apps to zinc-vm --jit or native (they already have those).
4. Phase 2 JIT last, and only if OTA/zinc:script code performance justifies 60-100 days plus perpetual ng-bump maintenance.
5. Do not: adopt tcc/quickjit (x86-64 only, LGPL); adopt Porffor (incomplete semantics); count on tail dispatch alone; promise V8-class performance (refcounting and 16-byte values remain).

8. Gaps and unverified items

• I did not run quickjs-aot with a Zinc-emitted app or profile a Zinc UI app under QuickJS. All Zinc-app expectations are inference.
• Compile time of qjsc -A output was not captured cleanly.
• quickjs-aot’s published numbers (Mac M4) and quickjs-jit’s numbers are not reproduced; only the three kernels above were.
• I did not read Kiesel, Boa, Deegen or Static Hermes source; those rows are from web summaries.
• ng’s docs claim polymorphic inline caches; I found none in 0.17.0 or the clone (grep for cache/IC structures, and reading OP_get_field). Re-check a newer ng before building ICs, to avoid duplicating upstream work.
• preserve_none/musttail support on the Pi and rMPP toolchains is inferred from LLVM support for AArch64, not tested there.
• Patent/licensing review for copy-and-patch not done.

Sources

• quickjs-aot: https://github.com/ivankra/quickjs-aot (README, qjsc.c, quickjs.c, aot-parse.py); tail branch https://github.com/ivankra/quickjs/tree/tail
• quickjit: https://github.com/bnoordhuis/quickjit
• quickjs-ng: https://github.com/quickjs-ng/quickjs ; differences page https://quickjs-ng.github.io/quickjs/diff/
• longbridge/quickjs-jit: https://github.com/longbridge/quickjs-jit (PR #21, PR #30)
• gkurt/quickjs PR #9: https://github.com/gkurt/quickjs/pull/9
• weval: https://github.com/bytecodealliance/weval ; https://cfallin.org/blog/2024/08/28/weval/ ; https://arxiv.org/abs/2411.10559
• LuaAOT: https://www.inf.puc-rio.br/~roberto/docs/paper-aot-preprint.pdf ; https://github.com/hugomg/lua-aot-5.4
• Copy-and-patch: https://fredrikbk.com/publications/copy-and-patch.pdf ; CPython JIT https://tonybaloney.github.io/posts/python-gets-a-jit.html ; PEP 774 https://peps.python.org/pep-0774/
• Tail-call interpreters: https://blog.reverberate.org/2021/04/21/musttail-efficient-interpreters.html ; https://blog.reverberate.org/2025/02/10/tail-call-updates.html
• Deegen: https://arxiv.org/pdf/2411.11469
• Static Hermes / Porffor: https://github.com/facebook/hermes/discussions/1137 ; https://github.com/CanadaHonk/porffor

mquickjs as a fourth Zinc engine: assessment and design

Date: 2026-09-30. Host: Apple M1 Pro, macOS 24.6, Apple clang. mquickjs checkout: bellard/mquickjs HEAD 6d4d7eb (2026-09-26; 477 commits), cloned to scratchpad/mquickjs. Zinc tree was dirty and was not modified.

Legend: [V] verified by running or reading code here, [W] from web sources, [I] inferred.

0. Verdict

Feasible, but it is not “QuickJS with a smaller footprint”. It is a different language (ES5 plus a few extensions, stricter mode). Zinc’s current JS path (emit-js.ts output as ES2022 modules, run through sim/zinc.mjs) cannot run on it. The work is a downlevel + bundle pipeline, an ES5 rewrite of the sim shim, a Promise/timer polyfill, and a new C adapter that respects a moving GC. Estimated 12-15 days for an MVP that runs the scalar/native fixtures, and 35-50 days for four-mode parity including UI demos. The payoff is real for ESP32-class targets. For Pi 3B+, rM Paper Pro and iOS, QuickJS is the better engine (Section 6).

1. mquickjs facts

1.1 Language subset

Sources: README.md lines 67-190, and my probes with ./mqjs [V].

The README describes ES5 in a mandatory “stricter mode”: strict-only, no holes in arrays (a[10]=x past the end is a TypeError [V “invalid array subscript”]), only global eval, no value boxing, for-in covers own properties only, and Date is only Date.now(). Extensions: for-of over arrays only, typed arrays, **, some Math functions, regexp s/y/u flags, codePointAt, replaceAll, trimStart/trimEnd, globalThis.

Probe results (each one-liner run in mqjs). “no” means SyntaxError or ReferenceError:

Missing standard-library members the emitted code commonly needs (all [V] via typeof loop over the example stdlib):

• Array: includes, find, findIndex, flat, flatMap, fill, at, Array.from, Array.of.
• String: padStart, includes, startsWith, at, localeCompare.
• Object: entries, values, assign, freeze, fromEntries, getOwnPropertyNames.
• Number and Math: Number.isInteger, Math.hypot.
• Globals: encodeURIComponent, structuredClone, TextEncoder, queueMicrotask, DataView.
• Present: slice, splice, indexOf, sort, reduce, map, filter, some, every, push/pop/shift/unshift, concat, reverse, Object.keys/create/defineProperty/getPrototypeOf, Math.fround/imul/trunc/sign/log2.

The stdlib is a compile-time C table (Section 1.3), so Zinc can add native members, or polyfill in JS at the cost of RAM.

Error subclassing is broken for ES5 patterns. Both Error.call(this,m) with E.prototype=Object.create(Error.prototype), and just this.message=m on such an object, threw TypeError: not a function [V]. Zinc’s class ScriptError extends Error pattern (plugins/script/index.ts:37) needs a custom Error construction path [I].

Other behaviors [V]: strings are WTF-8 ("héllo€".length=6, "😀".length=2, so UTF-16 semantics are preserved). Deep recursion of 20000 frames works. Runaway recursion throws InternalError (catchable), not a crash.

1.2 Memory model

• No malloc. JS_NewContext(mem_buf, size, &js_stdlib) (mquickjs.h:263) allocates everything inside the given buffer. JS_FreeContext only runs finalizers.
• Tracing, compacting GC. Any allocation can move objects. C code must not hold JSValue across API calls except through JSGCRef (JS_PushGCRef/JS_PopGCRef, LIFO stack, mquickjs.h:143-152) or JS_AddGCRef/JS_DeleteGCRef (context roots, non-LIFO). No JS_FreeValue. DEBUG_GC forces a move on every allocation (good for testing the adapter).
• Value = one CPU word (32-bit on 32-bit CPUs; on 64-bit, “short floats” with small exponent are inline, others boxed) (mquickjs.h:44-51, README 296-330). 31-bit ints. Objects >= 3 words.
• Retaining JS values from native objects: known gap in issue #80. The fix, commit 6d4d7eb, added JS_NewObjectClassUser(ctx, class_id, n_values) plus JS_SetUserValue/JS_GetUserValue, which are GC-traced slots inside the object [V, mquickjs.h:216,289]. This is how a resource wrapper can hold a callback closure without a root cycle.
• Finalizers (JSCFinalizer(ctx, opaque)) cannot call into JS (mquickjs.h:220).
• JS_StackCheck/JS_PushArg/JS_Call(ctx, argc|flags) is the call sequence (example.c:250-253, mqjs.c:215-221). Errors longjmp only inside the parser (mquickjs.c:7655,11762); C callbacks report failure by returning JS_EXCEPTION. C++ exceptions must never unwind through the engine, the same rule Zinc’s quickjs.cpp:200-202 already follows.

Numbers [V, mqjs --memory-limit]: hello world runs in a 10 KB buffer; tests/mandelbrot.js runs in 64 KB. My alloc-heavy objs.js (string growth) used 775 KB of a 1 MB heap at exit.

1.3 C API and stdlib generation

• mquickjs_build.c is a host tool that compiles a C description (mqjs_stdlib.c) into mqjs_stdlib.h: JSSTDLibraryDef with ROM-able property tables, a C function table, a finalizer table, and the class count. Function identity is a table index (JS_CFUNCTION_*), fixed at build time.
• Consequence for Zinc: per-export JS_NewCFunctionData (used by quickjs.cpp:212) does not exist. The equivalent is JS_NewCFunctionParams(ctx, JS_CFUNCTION_zn_call, JS_NewInt32(id)) (example.c:241), one fixed stdlib entry with the export id as a param, created at runtime [V that the API exists, I for the design]. Therefore the stdlib table is generated once per Zinc runner, not per app.
• Bytecode: mqjs -o out.bin src.js, mqjs -b out.bin, -m32 for 32-bit output on a 64-bit host, --no-column. JS_RelocateBytecode, JS_LoadBytecode, JS_Run (mquickjs.h:342-372). Bytecode is unverified; trusted sources only (README 273-275). Version is checked (JS_BYTECODE_MAGIC and a version field), but there is no compatibility promise. Measured [V]: fib.js gives 736 B (64-bit) and 452 B (-m32).
• Interrupt: JS_SetInterruptHandler(ctx, fn(ctx, opaque)), polled every 10000 ops (mquickjs.c:187,5096); non-zero raises InternalError: interrupted. Regexps are also interruptible [W].
• Memory limit is simply the size of the buffer.
• License: MIT (Fabrice Bellard, Charlie Gordon). Compatible with the vendored QuickJS licensing [V].
• Build: plain make (gcc/clang, C99-ish; -D_GNU_SOURCE); CMake wrapping is trivial: mquickjs.c, cutils.c, dtoa.c, libm.c plus a generated stdlib header. I built it on macOS arm64 without changes [V]; mqjs is 271 KB (-Os -g, includes readline). Options for ARM32 (-mthumb), softfloat, X86_32 and Win32 in the Makefile [V].
• Portability: built for both 32- and 64-bit words (JSW 4 or 8). Own libm and soft-float; ROM about 100 KB Thumb-2 per Bellard [W/README].

1.4 Performance

Bellard’s claim: “speed comparable to QuickJS” (README:9-10); ships make microbench and an Octane target with a strict-mode-patched Octane in a tarball (I did not download it). Nobody I found published reliable Octane numbers; one blog post has only placeholders (X/Y/Z) and I discount it [W].

My own micro-measurements, ES5 code so both engines run identical source. Zinc’s vendored QuickJS-ng 0.17 built at -O2 through a 20-line runner; mqjs at -Os (default) and -O2. Single machine, 2 runs each, wall clock in ms, no statistics: treat as ordering only [V].

Reading: mqjs is faster on call-heavy code (~20-25%), slower on float-heavy code (~10-15%, boxed doubles) and allocation-heavy code. This matches “comparable”.

Zinc’s own baselines (docs/engines.md:226-243): QuickJS fib 322-341 ms, mandelbrot 715-745 ms (different, larger kernels, spawn-to-exit). So mquickjs would sit close to the QuickJS column and far from the VM/JIT column.

1.5 Ecosystem [W unless noted]

• ESP32: conoro/mquickjs (ESP32 fork), makgordon/esp-mquickjs (ESP-IDF component, registry), 99percentpeople/esp32qjs (ESP-IDF framework for trusted JS on mquickjs), an Adafruit write-up (page returned 403, title only).
• Bindings: mitchellh/zig-mquickjs (Zig; pinned to one Zig release; stdlib ROM compile step needed), mquickjs-kmp (Kotlin), Simon Willison’s Python/Node/Deno/Pyodide/WASM bindings (WASM was harder because of setjmp/longjmp; 303 KB wasm).
• Users: mattneel/three-native README states mquickjs as the JS engine (“10KB RAM, 100KB ROM … JS is not the hot path; GPU calls are. Can swap to V8/JSC later”). A search-engine summary claimed it was on QuickJS-NG; I trust the README fetch, but this is a mild conflict [W].
• Repo state: 6.2k stars, 245 forks, 4 open issues, 15 PRs (fetch of GitHub Issues page). Open issues: no version tags (#18, #69), PIC bytecode (#53), catch variable already exists SyntaxError (#40); #80 (retained values) was addressed by 6d4d7eb. There are no releases or tags, so pin by commit [W].
• Lobsters discussion: the fixed static buffer is seen as a weakness for multi-VM designs; no-hole arrays praised. No independent benchmark data.

2. Zinc’s current QuickJS integration

Files read: runtime/vm/quickjs.cpp (333 lines), runtime/vm/abi.h, runtime/include/zinc_abi.h (94), compiler/src/{emit-js,engines,abi}.ts, docs/engines.md, docs/engine-progress.md, tests/engines/run.mjs, plugins/script/**.

2.1 Pipeline today

1. buildEngine (engines.ts:14) calls emitAbi (engines.ts:19, abi.ts:25) to produce zinc_abi_generated.h (per-export C adapters over zinc_abi.h) plus core.abi.json.
2. For quickjs: emitJs(..., abi.imports) (engines.ts:33; emit-js.ts:13) uses program.emit with a TS transformer (emit-js.ts:22-363), then bundleJs (engines.ts:130) copies the module graph as .mjs files with rewritten relative specifiers; no concatenation, the QuickJS module loader (quickjs.cpp:217-230) reads them from disk.
3. run.mjs for the engine (emit-js.ts:388-389) uses top-level await runMain(() => import(entry)) and imports sim/zinc.mjs (766 lines across sim/*.mjs).
4. CMake is generated in engines.ts:44-64; the QuickJS target adds plugins/script/vendor/quickjs/quickjs-amalgam.c as a static library (engines.ts:54-56). The runner is runtime/vm/quickjs.cpp for quickjs, main.cpp for the VM (engines.ts:47).
5. CLI: --engine validated at cli.ts:62, help text cli.ts:991, engine name in build directory cli.ts:234, dispatch at cli.ts:470-479, hardcoded host-only rule engines.ts:16 and cli.ts:127-128. Type Engine is engines.ts:12. Exports: exportEngine (engines.ts:163), which special-cases quickjs at :171-177.
6. Tests: tests/engines/run.mjs:10 builds the engine list (native, zinc-vm, zinc-vm-jit on arm64, quickjs); flags() at :11; ~62 fixture programs are compared byte-for-byte across modes (:29), plus graphics capture, dynamic-library loading, invalid resource/unknown-module/timeout checks (:206-224).

2.2 What the emitted JS uses that mquickjs lacks

The TS program is created with ts.ScriptTarget.ES2022 (frontend.ts:60, 86), so emit-js output is modern JS. Everything in the left column is emitted as-is:

The 32-bit |0, >>>0, Math.imul, Math.fround narrowing that emit-js.ts:32-45 produces is all ES5-safe (Math.fround and imul are present) [V].

2.3 Downlevel options

TypeScript is used as @typescript/typescript6 6.0.x by the frontend (frontend.ts:3, package.json:8); typescript 7.0.2 is only a devDependency.

• Verified: ts.transpileModule(src, {target: ES5, module: CommonJS, downlevelIteration: true, ignoreDeprecations: '6.0'}) works in TS 6.0.3 here (scratchpad bench/es5.cjs, bench/s1.js). TS 6 deprecates target: ES5 (needs ignoreDeprecations), and it is removed in TS 7 [I from the 6.0 deprecation message, not verified against release notes]. That makes ES5 emit a dependency on staying on @typescript/typescript6.
• Recommended: emit-js stays untouched (still ES2022 output, still the single semantic transformer). A new pass takes each emitted .js file and does ts.transpileModule to ES5 CommonJS, then wraps each in a module function and concatenates into one bundle.js, with a ~30-line __zn_require registry and the zinc:* builtin modules pre-registered. This adds the pass in engines.ts (a bundleEs5 next to bundleJs), about 150 lines.
• Alternative: a hand lowering in emit-js. Higher risk. Rejected.
• Verified pitfall (scratchpad bench/s1.js): class B extends A with super.y on a getter gave NaN in TS’s ES5 output. It needs either a Zinc-specific rewrite or a lint error. extends Error needs a helper.
• sim/zinc.mjs (~90 lines of helpers such as idiv/imod/dto/get/set/c_log/dynfn) must be re-authored as ES5 sim/zinc.es5.js, without Symbol, BigInt, class fields, async timers, node:*. About 1 day for the integer/float profile; more for fx.

3. ABI mapping onto the mquickjs C API

ZincValue/ZincExport/ZincHost (zinc_abi.h) are engine-neutral. The generated adapters (abi.ts) only touch ZincValue. So the adapter work is confined to a new runner runtime/vm/mquickjs.cpp (about the same 330 lines as quickjs.cpp, plus changes); abi.ts needs no change [I].

Not verified: I did not compile the adapter.

4. Design: --engine mquickjs

4.1 CLI and build

• compiler/src/cli.ts:62 add 'mquickjs' to the accepted list; :991 and :1061 help; :113 --native-library accepts it; :470 unchanged (already !== 'native').
• engines.ts:12: type Engine = 'native'|'zinc-vm'|'quickjs'|'mquickjs'. Build directory falls out of cli.ts:234 as mquickjs-<name>-<target>.
• Vendor mquickjs at plugins/script/vendor/mquickjs/ (or runtime/vendor/mquickjs/): mquickjs.c, mquickjs.h, mquickjs_priv.h, mquickjs_opcode.h, cutils.[ch], dtoa.[ch], libm.[ch], list.h, softfp_template*.h, mquickjs_build.[ch], LICENSE; pin commit 6d4d7eb. About 600 KB of source.
• Generated stdlib: CMake builds the host tool mquickjs_build from zinc_stdlib.c (a trimmed copy of mqjs_stdlib.c with Zinc additions: __zn_call param function, print, host timers, performance/Date shims, extra Array/String/Object natives) and emits zinc_stdlib.h. Two-stage CMake (add_executable host tool, add_custom_command). About 1 day of CMake in engines.ts:44-64, which currently hardcodes text templates.
• Runner: runtime/vm/mquickjs.cpp selected at engines.ts:47 (engine === 'mquickjs' ? 'mquickjs.cpp'); flags -O2 -fno-strict-aliasing? (not checked).
• Native link: add_library(mqjs STATIC ...) mirroring engines.ts:54-56.

4.2 Program pipeline

sema -> emitJs (unchanged, ES2022 modules, nativeImports map)
     -> bundleEs5: per-module ts.transpileModule(ES5, CommonJS, downlevelIteration, ignoreDeprecations)
                   + registry runtime + sim/zinc.es5.js + polyfills.js (Promise, Map, Set, Array/String/Object gaps)
                   + entry: runMain(function(){ __zn_require(entry) })
     -> bundle.js (one strict ES5 script)
     -> (optional) mqjs-compile: JS_Parse + JS_PrepareBytecode -> app.mqbc  (`-m32` when target word size is 32)

Reuse of emit-js’s nativeImports mapping is intact: the bundler resolves zinc:native/X to registry names the runner pre-populates.

Entry differs from emit-js.ts:388-389 (top-level await); add an emit-js option or write the entry in the bundler.

4.3 Precompiled bytecode

mquickjs.cpp accepts program.js or program.mqbc (JS_IsBytecode, JS_RelocateBytecode, JS_LoadBytecode, JS_Run). The compile step is done with the same runner (--compile out.mqbc) so the version matches; store the mquickjs commit and word size in engine.json (as engines.ts:77 does for the core). Bytecode is not verified, so treat it like the VM’s --core scripts: trusted only, hash-checked; document this next to docs/engines.md:57-59.

4.4 Flags and limits

• ZINC_MQJS_HEAP_BYTES (default 8 MiB desktop; the runner mallocs the buffer once); --mq-heap=<n>[k|m] CLI option maps to it.
• ZINC_EXECUTION_TIMEOUT_MS reused via zinc::deadline() and JS_SetInterruptHandler.
• ZINC_MQJS_STATS=1 prints JS_DumpMemory JSON-ish, parallel to ZINC_VM_STATS.
• A --gc-stress debug flag builds with -DDEBUG_GC (README:251), which runs the whole fixture set under move-every-allocation.

4.5 Test matrix changes (tests/engines/run.mjs)

• :10 add mquickjs to the list; :11 flags; command() :20-27 already generic via engine.json entry.
• Introduce a per-fixture skip[engine] allowlist with reasons, so parity gaps are explicit rather than silent.
• :206-224 (QuickJS-only import probes) need an mquickjs variant; module syntax tests would use ES5 require-style snippets or be skipped.
• Add --gc-stress runs of the bytes/records/callbacks/resources fixtures.

4.6 Parity gaps versus the current four-mode matrix

Predicted, not run.

1. resources.ts object identity ("identity true"): no WeakMap. Needs a design decision (Section 3).
2. Promise/async ordering fixtures (async, async-control, promise-order, suspend-order, promise-timers, promise-chains, promise-all): depends on a polyfill matching native microtask order exactly; tractable, but 7+ fixtures.
3. Generators family (generator-*, 7 fixtures): TS __generator works without Symbols if __values is patched; for-of over user iterators is not possible natively, so the ES5 output must use array paths.
4. classes, accessors, bind, instanceof, static-fields, generic-inheritance: super accessors and custom Errors need work (Section 2.3).
5. collections, map-undefined: Map/Set polyfill semantics (ordering under mutation, undefined keys, NaN keys).
6. strings, string-*, replace-all, stdlib-path, string-format: UTF-16 semantics verified [V]; case conversion only ASCII (toLowerCase/UpperCase), regexp case folding ASCII only (README:161-168). Unicode fixtures will diverge. Missing localeCompare, padStart, includes.
7. native-library, dynamic-lib tests (run.mjs:71-111): should pass, engine-neutral.
8. bytes, records: fine after copy loops; watch for compaction bugs (use --gc-stress).
9. events, services, graphics: depend on host loop plus timers (quickjs.cpp:298-321 logic ported).
10. Proxy probe (run.mjs:96) and import() probes (:209): irrelevant/skip.
11. Typed number fx profiles (sim/zinc.mjs:139-169) use BigInt: rewrite or skip fx profile for mquickjs.
12. Error stacks and messages: text differs (like docs/plugins/script.md:118-120).
13. Runtime limits: heap-limit style test differs (buffer exhaustion throws InternalError: out of memory; message text must be normalised) [I].
14. zinc:script inside the app (nested Script instances): not applicable; nested contexts would need a second buffer.
15. Timing kernels: fib/mandelbrot would run (ES5 code path is trivial); the 100000 native calls and callback kernels exercise the ABI adapter heavily.

5. Effort (working days; one developer; assumes the spike works as tested)

The largest uncertainty is M5: whether the UI framework code (lib/std/react.ts, solid.ts, ui.ts, kit/*) survives ES5 downlevel plus the 31-bit-int/boxed-double performance profile. I did not test it. The examples/hero tree, docs/engines.md:274-276 reports QuickJS building only 16/58 demos even today, so mquickjs would start behind that.

6. Where mquickjs helps and hurts, per target

Other observations:

• mquickjs’s compacting GC and no-malloc model actually gives Zinc a stricter memory budget test than QuickJS: heap-limit fixtures become deterministic.
• Strict-mode restrictions are a subset of JS, which is aligned with Zinc’s typed-array semantics (no holes, pop on empty gives undefined still, needs ?? default from emit-js:167-172).
• The runtime has a single context per buffer and no threads; the zinc:script plugin’s “many Script instances with independent limits” is achievable with one buffer each but at a fixed cost per instance.
• Maintenance risk: no releases or tags; single-author; pin by commit. TS ES5 deprecation adds a second pin.

7. Recommendation

1. Do M0 (2 days) as a spike, in a branch, to prove the vendoring, generated stdlib and one JS_NewCFunctionParams-based native call.
2. Decide the first product use case before investing beyond M2. If it is “run Zinc apps on ESP32-class hardware”, M1-M2 plus M7 is the right path and mquickjs is the only candidate besides the Zinc VM. If it is “a fourth desktop engine for parity”, the value is mostly differential testing, and the 35+ day parity cost is hard to justify.
3. The zinc:script embedding (ScriptEngine interface at plugins/script/index.ts:56) is a much smaller first integration (an engine: 'mquickjs' option: sandboxed ES5, fixed memory budget, interrupt). It also avoids the entire downlevel/bundle problem because scripts are ES5 authored. Estimated 6-8 days [I].
4. Do not attempt --engine mquickjs for Pi/rM/iOS UI apps unless memory or binary-size numbers show a need.

Reproduction

Everything under scratchpad/: mquickjs/ (built, mqjs binary), mq_o2/ (-O2 build), bench/{fib,mandel,objs}.js, bench/qmain.c (QuickJS-ng runner), bench/es5.cjs (TS 6 ES5 transpile), bench/s1.js (downlevel test). Commands: ./qjs_ng fib.js versus ../mquickjs/mqjs fib.js; mqjs --memory-limit 10k -e 'print(1)'; mqjs -o x.bin x.js; mqjs -m32 -o x32.bin x.js; mqjs -b x.bin.

Sources

• https://github.com/bellard/mquickjs (README, mquickjs.h, mquickjs.c, example.c, mqjs.c, mqjs_stdlib.c, issue #80, commit 6d4d7eb)
• https://simonwillison.net/2025/Dec/23/microquickjs/
• https://lobste.rs/s/60fjs1/mquickjs_micro_quickjs_javascript
• https://github.com/mitchellh/zig-mquickjs
• https://components.espressif.com/components/makgordon/esp-mquickjs/versions/0.1.0-beta/readme?language=en
• https://github.com/conoro/mquickjs, https://github.com/99percentpeople/esp32qjs
• https://blog.adafruit.com/2026/01/05/vibe-coding-an-esp32-version-of-micro-quickjs/ (403 on fetch, title only)
• https://github.com/mattneel/three-native
• https://github.com/HarlonWang/mquickjs-kmp
• https://www.phoronix.com/news/Micro-QuickJS
• https://tisankan.dev/embedded-javascript-engine/ (discounted: placeholder benchmark values)

Running the complete Three.js + WebGL/WebGL2 API on the Zinc toolchain

Research only. Repo /Users/mowmow/Lab/zinc was read, not modified (working tree dirty; I read the working-tree files). Date 2026-09-30. “V” = verified by reading code/docs or running something. “I” = inferred / recalled, not verified.

0. Executive summary

1. Nothing WebGL-shaped exists in Zinc today (V). grep -i webgl hits only reports/docs. The GL code (plugins/display-gl, 1075 lines in 4 files) is an internal 2D compositor in a GLSL ES 1.00 dialect (zgl.h:2-3, display_gl.cpp:43-47), on GL 3.2 core (macOS, SDL3, sdl.cpp:17-20) and GLES 2.0 (Linux/Pi, EGL+GBM+KMS, kms.cpp:193 EGL_CONTEXT_CLIENT_VERSION, 2). Three.js >= r163 needs WebGL2 (GLES 3.0), so neither existing context is enough.
2. Zinc has no ArrayBuffer/typed arrays in the language (V, docs/guide/09-web-apis.md:87) and the native ABI only moves copied, read-only byte/number snapshots (docs/engines.md:93-95, zinc_abi.h:25-28). Upstream Three.js is dynamic JS that lives on typed arrays (three r186 src: 84 Float32Array, 47 Uint32Array, 38 Uint16Array, 33 Uint8Array, 33 ArrayBuffer refs, V by grep). So the only credible host for upstream Three.js is a real JS engine. That is QuickJS(-ng), already vendored (plugins/script/vendor/quickjs, v0.17.0) and already a Zinc engine (--engine quickjs, runtime/vm/quickjs.cpp).
3. zinc-vm cannot run upstream Three.js, honestly: it is a typed-language VM (docs/engines.md:29-41), Dyn shapes/ICs are still a plan (docs/reports/zinc-vm.md:105-121, 421 “V4”), zinc:script is “still unavailable” in the VM (engines.md:39), and there are no typed arrays. What zinc-vm (and native) can do: run a typed Zinc program that owns a QuickJS instance (the zinc:script plugin pattern, ~1 MB) and/or call a typed WebGL2 API, once the ABI gets shared mutable buffers.
4. Best architecture (recommendation): one native “WebGL2 context” library (C++, ~224 methods, ~550 constants, ~25 extensions) on a GLES3-native backend (system GLES 3.x on Linux/Pi 4/5, ANGLE on macOS), bound directly to QuickJS-ng through its C API (zero-copy typed arrays, no Zinc ABI in the hot path), plus a small JS “browser host” bundle (canvas, Image, fetch, events, rAF, TextDecoder, URL/Blob, WebAssembly, Worker). Do not copy three-native’s design (sokol_gfx + textual GLSL rewriting); it fights the WebGL state machine.
5. Measured today (V, this machine, M-series Mac; scripts in scratchpad): with a mock GL (no-op Proxy, so JS-side cost only), Three r186 renderer.render() for 500 MeshStandardMaterial cubes costs 0.81 ms in node/V8 vs 11.4 ms in QuickJS (14x), and 1000 cubes 1.9 vs 25.7 ms. A scene-graph-only benchmark (1000 animated objects, updateMatrixWorld + frustum cull) is 0.19 ms vs 5.7 ms (30x). GL calls per frame: ~6 per draw (about 2100 calls for 351 draws). The JS<->native crossing is not the bottleneck; Three.js’s own JS running on an interpreter is. Expect a budget of a few hundred draw calls at 60 fps on desktop, far fewer on a Pi. A JIT engine (JSC/V8) or Three’s own batching (InstancedMesh/BatchedMesh, static matrices) is the lever, not a fancier command buffer.
6. Effort (one strong dev): ~25-35 person-weeks to “Three r18x WebGLRenderer runs glTF/PBR/shadows/post-processing at real perf in QuickJS on macOS + Linux/Pi4-5 through native and quickjs engines”; +8-12 weeks for Khronos WebGL2 conformance-grade; +4-6 for a WebGL1/GLES2 (Pi 1-3, Three <= r162) profile. zinc-vm parity for typed WebGL use adds ~4-6 (ABI buffers).

1. What already exists in the repo (all V unless marked)

1.1 GL / canvas / audio surface

Backend summary: the current GL backend is desktop GL 3.2 core (mac) / GLES 2 (Pi, Linux), i.e. one GLES2 and one GL3.2 code path, no GLES3. Pi 4/5 (Mesa V3D, GLES 3.1 conformant, I from Mesa docs/Phoronix) would run GLES3 through the same KMS code with EGL_CONTEXT_CLIENT_VERSION 3; Pi 1-3 (VC4) are GLES 2.0 only (V for Pi 3B+: docs/plugins/display-gl.md capability table; reports also say ANGLE is not a hardware upgrade for VC4).

Measured VC4 facts useful for a WebGL layer (V, display-gl.md): 2048 max texture, 16 units, NPOT ok, VAO/uint32 indices via extensions, no GL_OES_standard_derivatives, no EXT_shader_texture_lod, MSAA 4x on window configs only; tile-based GPU (mid-frame FBO switches cost a flush); one unexplained VC4 GPU hang on partially changing screens; DRM master needed (console only).

1.2 Engines (docs/engines.md, runtime/vm/quickjs.cpp, plugins/script)

• Three modes: native (AOT C++), zinc-vm (typed bytecode, Tier-0 interpreter + AArch64 baseline JIT), quickjs (application runner) — engines.md:29-41.
• QuickJS runner: registers modules through the shared C ABI, ES-module loader from the filesystem, bootstrap installs process, performance.now, setTimeout/Interval/Immediate, queueMicrotask, console only — quickjs.cpp:143-177. No window/document/canvas/fetch/Image/TextDecoder/URL/WebAssembly/rAF today.
• Emitted JS target is ES2022 (compiler/src/emit-js.ts:367,377); QuickJS-ng handles it natively, so no ES5 down-levelling.
• Speed (V, engines.md:226-243, M1 Pro): fib native 10 ms / VM 130 / VM-JIT 62 / QuickJS 341; mandelbrot 22 / 385 / 85 / 745. 100k scalar native calls: 3.0 / 6.4 / 5.1 / 10.8 ms (spawn-to-exit; so per-call ABI cost is under ~100 ns in every mode). These are typed numeric kernels, not UI.
• Native ABI (zinc_abi.h): types VOID BOOL I32 U32 F32 F64 STRING RESOURCE CALLBACK BYTES RECORD NUMBERS ARRAY. Bytes/numbers are borrowed for the call or copied snapshots; “mutable user specs remain rejected” (engines.md:93-95). Callbacks take scalars only (engines.md:107). No shared mutable buffers, no async completion.
• zinc:script (QuickJS-ng 0.17.0 vendored, ~1 MB overhead, macos/linux/rpi1/rmpp; sim uses node:vm) sandboxes JS with typed expose() host fns; values cross as Dyn copies (docs/plugins/script.md, plugins/script/native/quickjs.host.cpp, 667 lines: no quickjs-libc, memory + interrupt limits). Right pattern for embedding, wrong for GL (no zero-copy typed arrays, Dyn conversion per call). It has no timers/fetch.
• mquickjs (Bellard’s MicroQuickJS) is not in the repo (grep). QuickJS-ng is.

1.3 Gaps for “complete WebGL + Three.js”

1. GLES3/WebGL2-capable context (ES 3.00 shaders, UBOs, VAOs, instancing, MRT, 3D/array textures, transform feedback, sync, queries, sRGB/half-float/RGB9E5 formats, renderbuffer multisample, blitFramebuffer).
2. WebGL semantics layer (validation, getError, object lifetime, default drawing buffer, context loss, limits, extensions).
3. Shared mutable typed-array bridge (QuickJS: available via its C API; Zinc ABI: missing).
4. Browser host (canvas/DOM stubs, Image decode, fetch, events, rAF, TextDecoder, URL/Blob, Worker, WebAssembly).
5. Compositing a GL surface with the Zinc UI without CPU readback (needs an “external texture” command kind or a shared-context pass in display-gl).
6. Audio (Three’s AudioContext use is only in src/audio, optional).
7. A test suite: Khronos WebGL2 conformance (not runnable without a DOM-ish harness).

2. Reference project: mattneel/three-native (read via gh api)

Repo facts (V): MIT, 18 stars, last push 2026-01-21, ~30 commits, Zig 0.15 + mquickjs (vendored) + sokol-zig (sokol_gfx/app/audio/fetch). Three.js is a git submodule. Sources: README, KICKSTART.md, docs/design/src, src/shim.

Architecture (V, docs/design/src/{architecture,shim,runtime}.md): Zig host -> one mquickjs runtime/context -> browser shim (WebGL, canvas, rAF, Image, fetch, input events) -> sokol_gfx backend (Metal/D3D11/GL). Single-threaded frame loop (poll events, dispatch, one rAF tick, translate GL to sokol, present). JS wrapper objects hold small numeric handles; host owns fixed-size handle tables (buffers 4096, textures 2048, programs 1024, FBOs 512, …; shaders 128, max 64 KB source: webgl_shader.zig). fetch is local-file only, images PNG/JPEG decode.

Shim (V): webgl.zig 21 KB, webgl_program.zig 86 KB, webgl_draw.zig 47 KB, webgl_texture.zig 31 KB, webgl_state.zig 17 KB, gl_uniforms.zig 7 KB, image_loader.zig 7 KB, runtime/js.zig 179 KB (bindings). WebGL state is re-assembled into sokol pipelines at draw time; the GLSL is rewritten line by line (webgl_program.zig:~1380-1470): drops #version/precision, replaces texture2D->texture, attribute->in, varying->out/in, gl_FragColor->fragColor, prepends #version 330, extracts loose uniforms, re-declares them, filters unused ones. sokol needs SG_MAX_UNIFORMBLOCK_MEMBERS patched to 64 for Three’s shaders (README).

Build (V, build-three-es5.mjs): esbuild (es2017 IIFE) -> Babel preset-env targets IE11 -> a hand-written es5-shim.js (Symbol stub, Object.assign, getOwnPropertyDescriptor(s)…) -> string patches (e.g. generateDefines null guard, no-op _classCallCheck, ASCII-escape). mquickjs is ES5-strict: no holes in arrays, arrays-only for..of, no boxing, no direct eval, only Date.now(), ASCII-only case mapping (README of deps/mquickjs, V); typed arrays and globalThis are supported. Three uses WeakMap heavily in renderers/webgl/* (V, grep) — mquickjs’s README does not list Map/Set/WeakMap (I: so more shims).

Coverage (V/I): webgl-api-coverage.csv has 315 rows (unique gl.* identifiers found in the Three checkout; methods and constants). Counts: webgl1 methods 31 implemented / 33 partial / 41 missing; webgl2 methods 31 missing (0 implemented); constants ~71 of 121 (webgl1) done/partial, 57 of 58 webgl2 missing. Partial notes are telling: “always NO_ERROR”, “LINK_STATUS only”, “COMPILE_STATUS only”, “returns empty list”, “always null”, “sampler units tracked only”. The CSV is stale vs the git log (bindTexture/createTexture marked missing while the commit log says textured cube and fetch() work), so treat it as a lower bound. Roadmap state (V): M0-M1 done, M2 partly, M3 “Three loads” mostly unchecked in the roadmap doc while commits show “M3: input events”, “M4: fetch() API”, textured-cube and interactive-cube examples exist. No glTF/PBR/shadows evidence. No WebGL2 (#version 300 es not handled anywhere in src/shim: grep = 0 hits), so it is effectively a WebGL1 shim, i.e. Three <= r162 (I: submodule commit not pinned in what I read).

What it proves: a small team can get Three’s scene setup and a cube through a hand-written shim in mquickjs in weeks. What it does not: WebGL2, conformance, performance numbers (its perf doc is “napkin math” placeholders: 2-5k GL calls, 200-500 draws/frame budget; no measurements).

Takeaways for Zinc: (a) their surface list (canvas, rAF, performance.now, Image/createImageBitmap, fetch, FileReader, URL.createObjectURL, events, TextDecoder) matches my grep of Three (section 6); (b) the sokol layer is the wrong abstraction for WebGL (PSO-based, forces GLSL rewriting, fixed caps) — GLES3 passthrough is simpler and more faithful; (c) mquickjs+ES5 is a tax we should not pay.

3. Other approaches (web; sources inline)

Shader translation options (GLSL ES 3.00 -> platform):

• Passthrough (recommended): WebGL2 GLSL is GLES3 GLSL; on GLES3 drivers and ANGLE no translation by us.
• ANGLE translator standalone: WebGL-spec validation (SH_WEBGL2_SPEC), error logs, limits; can also emit GLSL 330/410 for desktop core on macOS if we refuse ANGLE’s GL layer.
• glslang (ES 3.00 -> SPIR-V, Vulkan semantics: loose uniforms need UBO/push mapping) + SPIRV-Cross (SPIR-V -> GLSL/MSL/HLSL): heavy-ish pipeline, needed only for a non-GL backend.
• naga GLSL frontend: faster but subset; discussions mention WebGL2-specific tweaks (I). Rust dependency. Not recommended.

4. Size of the WebGL2 surface and what Three actually calls

Full surface (V, computed from lib.dom.d.ts TypeScript 6.0.3 in the repo’s node_modules): WebGL1 context = 136 unique methods, WebGL2 adds 88 (=> 224 unique methods), ~550 constants (297 + 256 in the interface bodies), plus ~25-30 extensions and ~35 object types (Buffer, Texture, Program, Shader, Framebuffer, Renderbuffer, VAO, Query, Sampler, Sync, TransformFeedback, UniformLocation, ActiveInfo, ShaderPrecisionFormat, …).

Three.js r186.1 (npm i three, V) WebGLRenderer path (src/renderers/webgl/*.js + WebGLRenderer.js): 142 distinct gl methods, ~200 distinct constants. Extraction by regex, so a few items are noise (canvas, rAF, drawImage). WebGPURenderer’s WebGL2 backend (webgl-fallback/) adds: beginQuery, endQuery, createQuery, deleteQuery, getQueryParameter, beginTransformFeedback, endTransformFeedback, createTransformFeedback, bindTransformFeedback, transformFeedbackVaryings, clearBufferfv, clearBufferfi, clientWaitSync, getSupportedExtensions.

4.1 Methods Three’s WebGLRenderer calls (checklist; V by grep)

activeTexture attachShader bindAttribLocation bindBuffer bindBufferBase bindFramebuffer bindRenderbuffer
bindTexture bindVertexArray blendColor blendEquation blendEquationSeparate blendFunc blendFuncSeparate
blitFramebuffer bufferData bufferSubData clear clearBufferiv clearBufferuiv clearColor clearDepth
clearStencil colorMask compileShader compressedTexImage2D compressedTexImage3D compressedTexSubImage2D
compressedTexSubImage3D copyTexSubImage2D copyTexSubImage3D createBuffer createFramebuffer createProgram
createRenderbuffer createShader createTexture createVertexArray cullFace deleteBuffer deleteFramebuffer
deleteProgram deleteRenderbuffer deleteShader deleteSync deleteTexture deleteVertexArray depthFunc depthMask
detachShader disable disableVertexAttribArray drawArrays drawArraysInstanced drawBuffers drawElements
drawElementsInstanced enable enableVertexAttribArray fenceSync finish flush framebufferRenderbuffer
framebufferTexture2D framebufferTextureLayer frontFace generateMipmap getActiveAttrib getActiveUniform
getAttribLocation getBufferSubData getContextAttributes getError getExtension getParameter getProgramInfoLog
getProgramParameter getShaderInfoLog getShaderParameter getShaderPrecisionFormat getShaderSource
getUniformBlockIndex getUniformLocation invalidateFramebuffer lineWidth linkProgram pixelStorei polygonOffset
readBuffer readPixels renderbufferStorage renderbufferStorageMultisample scissor shaderSource stencilFunc
stencilMask stencilOp texElementImage2D texImage2D texImage3D texParameterf texParameteri texStorage2D
texStorage3D texSubImage2D texSubImage3D uniform1f uniform1fv uniform1i uniform1iv uniform1ui uniform1uiv
uniform2f uniform2fv uniform2i uniform2iv uniform2ui uniform2uiv uniform3f uniform3fv uniform3i uniform3iv
uniform3ui uniform3uiv uniform4f uniform4fv uniform4i uniform4iv uniform4ui uniform4uiv uniformBlockBinding
uniformMatrix2fv uniformMatrix3fv uniformMatrix4fv useProgram vertexAttrib1fv vertexAttrib2fv vertexAttrib3fv
vertexAttrib4fv vertexAttribDivisor vertexAttribIPointer vertexAttribPointer viewport

Notes: texElementImage2D is a new optional path (WebGLTextures.js:1259, guarded by 'texElementImage2D' in _gl). getBufferSubData (async readback), fenceSync/deleteSync, blitFramebuffer, renderbufferStorageMultisample, texStorage2D/3D, framebufferTextureLayer, readBuffer, drawBuffers, invalidateFramebuffer, clearBufferiv/uiv, uniformBlockBinding/getUniformBlockIndex/bindBufferBase (UBOs), drawArrays/ElementsInstanced, vertexAttribDivisor, vertexAttribIPointer are the WebGL2-only items Three requires; all are plain GLES 3.0.

4.2 Extensions Three probes (V)

Requested at init in WebGLExtensions.js: EXT_color_buffer_float, WEBGL_clip_cull_distance, OES_texture_float_linear, EXT_color_buffer_half_float, WEBGL_multisampled_render_to_texture, WEBGL_render_shared_exponent. Queried elsewhere: EXT_texture_filter_anisotropic, WEBGL_compressed_texture_{s3tc,s3tc_srgb,etc,astc,pvrtc}, EXT_texture_compression_{bptc,rgtc}, EXT_texture_norm16, KHR_parallel_shader_compile, WEBGL_multi_draw, WEBGL_lose_context, EXT_clip_control, OVR_multiview2 (8 mentions), EXT_disjoint_timer_query(_webgl2), WEBGL_debug_shaders. All optional: returning null for unsupported ones is legal and Three degrades. A first milestone set: EXT_color_buffer_float, EXT_color_buffer_half_float, OES_texture_float_linear, EXT_texture_filter_anisotropic, KHR_parallel_shader_compile, WEBGL_lose_context, WEBGL_multi_draw; BC/ETC/ASTC follow GPU support (Apple: BC no, ASTC yes; VC4/V3D: ETC2 yes).

Shader side (V, renderers/shaders, WebGLProgram.js): Three emits #version 300 es and uses gl_FragColor via macro to a layout(location=0) out, gl_Position, gl_FragCoord, gl_FragDepth, gl_PointSize, gl_PointCoord, gl_InstanceID, gl_VertexID, gl_DrawID (multi-draw), gl_FrontFacing, ANGLE-specific hints. No compute, no geometry/tessellation: plain GLES 3.0.

4.3 Context/host surfaces Three touches (V by grep of src and examples/jsm, files matched)

Bundle (V, esbuild 0.2x, minified, target es2020): full import * as THREE 743 KB (190 KB gzip); tree-shaken small scene (WebGLRenderer, Scene, Mesh, BoxGeometry, MeshStandardMaterial, DirectionalLight, PerspectiveCamera) 521 KB. esbuild cannot target ES5 at all (errors on let/const), Babel would be needed as in three-native.

5. Design

5.1 Layering

 App (upstream Three.js r18x ESM, user JS, or typed Zinc)
 -------------------------------------------------------------------------
 L4 Zinc integration      zinc:webgl plugin (typed API for Zinc programs), quickjs/native/vm registration,
                          zinc.json "renderer/webgl": "webgl2" | "webgl1" | "off", capability check at startup
 L3 Browser host (JS)     window/document/canvas/Image/createImageBitmap/OffscreenCanvas/fetch/URL/Blob/
                          TextDecoder/rAF/perf/events/Worker/WebAssembly; small (~2-3k lines JS) + native helpers
 L2 Engine glue           QuickJS-ng C-API binding generated from one IDL table (like compiler/src/abi.ts does
                          for Zinc specs); zero-copy typed arrays; object handles = small ints in JS wrappers
 L1 WebGL2 core (C++)     ~224 methods, object tables + generations, state mirror, validation, getError queue,
                          limits/caps clamps, extension table, drawing buffer + context loss; engine-agnostic
 L0 GLES3 backend         Linux/Pi4-5: system GLES 3.x over EGL/GBM (kms.cpp, ctx version 3);
                          macOS: ANGLE (Metal) via EGL; optional Windows: ANGLE(D3D11);
                          Pi 1-3: GLES2 => WebGL1 profile only (Three <= r162)
 Present                  display-gl extended: WebGL canvas = FBO texture composited in the present pass
                          (existing key-colour/texture pass, display_gl.cpp) or an EXTERNAL_TEXTURE cmd kind

Why passthrough on GLES3: WebGL2 ~ GLES 3.0 with extra rules. The L1 layer only validates and forwards; no PSO reconstruction, no GLSL rewriting, uniforms/UBOs/samplers map 1:1. WebGL semantics that need real code: (a) default framebuffer emulation (render to an RGBA8 + depth/stencil FBO, MSAA renderbuffer when antialias, resolve at composite; preserveDrawingBuffer/premultipliedAlpha), (b) strict GLSL validation (ANGLE translator in WebGL spec mode; browsers do this), (c) error semantics (INVALID_ENUM/VALUE/OPERATION, no undefined behaviour reaching the driver, e.g. buffer bounds on draw), (d) uninitialised resource zeroing, (e) context loss/restore, (f) limits (clamp MAX_* to spec-friendly values), (g) readPixels/format rules, (h) getUniformLocation array names, getActiveUniform info, (i) sRGB/colorspace unpack flags, (j) UNPACK_FLIP_Y_WEBGL, UNPACK_PREMULTIPLY_ALPHA_WEBGL, UNPACK_COLORSPACE_CONVERSION_WEBGL done on the CPU for image sources.

Context sharing with existing display-gl: use a separate EGL/GL share-group context for WebGL rather than the single display-gl context, else the 2D uber renderer and WebGL trample each other’s state (gl_renderer.cpp assumes ownership). On tile-based VC4/V3D, extra FBO passes cost (design report §11). Compositing: the WebGL drawing buffer texture goes to the present pass (already a texture pass with key colour and zgl_layers underneath, display_gl.cpp), or a new GPU-texture command kind inside the retained frame list (the report’s IMAGE kind with dyn images and a version counter is the seam; gpu-renderer-design.md §2). CPU renderer / sim: show a placeholder or a readback (explicit cost).

5.2 Which engine hosts the JS

Verified interpreter gap (numbers on this M-series Mac; qjs = Homebrew QuickJS 2026-06-04; Zinc vendors quickjs-ng 0.17.0, expected similar (I)). Scripts: mock-render-bench.mjs, scenegraph-bench.mjs in the scratchpad dir.

Caveats: GL is a JS Proxy stub (its cost is included on both engines and is probably heavier under qjs, so real binding numbers should be a bit lower); no textures, shadows, real uniform locations, or post-processing; only ~10 uniform uploads per draw here; a single machine; frustum culling dropped ~30% of cubes. Order-of-magnitude only. Extrapolation to a Pi 4 (A72) at ~3-4x slower than M1 (I): ~35-45 ms for 500 cubes => 20-30 fps; Pi 3B+ worse. This is why the perf plan attacks Three’s JS (below), not crossing cost.

5.3 JS <-> native crossing and command buffer

Facts: ~6 GL calls per draw in Three (enable/disable culling, 2-3 matrix uniforms, drawElements; more with textures, shadows, morphs); 2-5k calls/frame at a few hundred draws. QuickJS C-function call from JS costs on the order of 50-200 ns (I: from bridge-bench ~100k calls in 5-11 ms including process time, engines.md:242). 5000 calls = 0.25-1 ms. So:

• Phase 1: direct calls into L1 on the JS thread; GL executed synchronously. Typed arrays passed by pointer (JS_GetArrayBuffer): zero copy for bufferData/uniform*fv/texImage2D. Simplest, sync semantics (getError, readPixels, getUniformLocation, compile status) trivially correct. Also identical semantics for Zinc typed callers.
• Phase 2 (only if measured): a command stream for render-thread offload (design report phase 3 wants a render thread anyway, gpu-renderer-design.md §6). expo-gl’s batch queue is the template (V). JS wrappers own handle ids allocated JS-side (create* returns immediately; no round trip), state mirror JS-side so that redundant calls are dropped (Three’s own WebGLState already deduplicates); commands encoded into a preallocated Int32Array/Float32Array ring (opcode + args), data uploads copied into a byte arena (bufferSubData/texSubImage are the only bulk copies, memcpy speed); flush at endFrame/rAF end and before any sync-return call (getError/readPixels/getParameter of dynamic state/getBufferSubData/clientWaitSync/getShaderParameter(COMPILE_STATUS) unless KHR_parallel_shader_compile semantic used, getProgramParameter(LINK_STATUS)). Shader compile/link stays sync unless parallel-compile is exposed (Three probes it).
• Do not do Zinc-ABI marshalling per GL call: ABI has no mutable buffers and scalars-only callbacks; add an ABI type for borrowed mutable buffer + length if typed Zinc code (native/vm) must call WebGL, or expose L1 through the plugin’s own C++ with typed arrays living in native memory.

5.4 ES5 vs ES2020

• QuickJS-ng: ship ESM/IIFE ES2020-2022, minified + tree-shaken (521-743 KB, 190 KB gzip), optionally precompiled to bytecode with qjsc (skip parse/compile on start; I: parse of 700 KB is on the order of 100+ ms on a Pi 3, needs measuring). Zinc’s own emitter is already ES2022 (emit-js.ts:367).
• ES5 (mquickjs-style) requires Babel preset-env + shims + hand patches as three-native/build-three-es5.mjs shows, larger/slower output (helpers for classes, spread, generators), no WeakMap/Symbol, engine strictness bugs. Decision: no ES5 target. Keep Three unmodified.
• Keep an option to pre-bundle user code + Three once at build time (zinc build) so devices never ship Node/esbuild.

5.5 Browser host layer (what to build, ordered by need)

1. Must (M1-M3): window/self/globalThis, devicePixelRatio, innerWidth/Height, requestAnimationFrame bound to the HAL frame callback, performance.now, document.createElement('canvas'|'img'), HTMLCanvasElement.getContext('webgl2'|'2d') (2D via existing zinc:canvas or a small native 2D surface with drawImage/getImageData, because Three’s CanvasTexture/PMREM/font code uses it), Image + createImageBitmap (decode PNG/JPEG/WebP through a native decoder, stb_image is what expo-gl and sokol use), fetch (file/asset root + HTTP(S) via existing lib/std/fetch.ts runtime), TextDecoder/TextEncoder, URL/Blob/createObjectURL, event targets (mouse/pointer/keyboard/wheel/resize from the HAL, pointer capture no-op), console, timers (exist).
2. Should (M4): OffscreenCanvas, ImageBitmap upload path (skip CPU round trip), WebAssembly global for QuickJS (zinc:wasm wasm3 exists: interpreter, so Draco/Basis/meshopt decode is slow but works; I), Worker (a second QuickJS runtime on a thread + structured clone of ArrayBuffers; DRACOLoader/KTX2Loader need it; or run decoders inline by patching the loader to call the wasm on the main runtime), FileReader, AbortController (zinc:web has it typed).
3. Later: AudioContext (Zinc audio plugin, Three Audio is optional), HTMLVideoElement (zinc:video exists), Gamepad, pointer lock, WebXR (out of scope). Reuse: lib/std/web.ts and fetch.ts are typed Zinc, not JS globals for QuickJS; the JS-visible versions must be small JS/C++ bindings over the same native helpers (utf8, sockets/HTTP, hashing) rather than a second implementation.

5.6 Performance plan (targets are engineering guesses, to be measured)

1. Pin the workload (Three’s webgl_* examples subset) and profile split: JS scene update / renderer JS / L2 crossing / L1 validation / driver / GPU. Zinc has stage profiling infra to extend (engines.md PocketJS lessons 3-4).
2. Cut Three’s JS cost: static scenes (matrixAutoUpdate=false, matrixWorldAutoUpdate), InstancedMesh/BatchedMesh, merged geometry, fewer materials/programs, frustum culling off for known-visible, reuse render lists, no per-frame allocation (matters for QuickJS RC/GC). This is documentation + presets, not engine work.
3. L1: skip driver calls already in the right state; UBO/uniform caches; lazy validation with hot-path fast checks; precomputed caps.
4. Command stream + render thread (section 5.3 phase 2) only if the crossing shows >15% of frame time; otherwise skip.
5. Startup: bytecode-precompiled bundle, lazy shader compile with a program-binary cache (glGetProgramBinary GLES3, not on VC4) and KHR_parallel_shader_compile.
6. If QuickJS still misses budgets: swap engine behind L2 (JSC on macOS first), keeping L1 unchanged.
7. Report per-engine in the existing benchmark protocol (raw samples, p50/p99, RSS, bundle size), as engines.md already prescribes.

5.7 Engine modes: what “runs Three.js” means per mode

6. Coverage checklist (what “complete” decomposes into)

• Context: getContext attributes (alpha, depth, stencil, antialias, premultipliedAlpha, preserveDrawingBuffer, powerPreference, failIfMajorPerformanceCaveat, desynchronized, xrCompatible), drawingBuffer{Width,Height,ColorSpace}, unpackColorSpace, isContextLost, WEBGL_lose_context, contextlost/contextrestored events, getContextAttributes.
• State: enable/disable, blend*, depth*, stencil*, cull/front face, scissor, viewport, polygonOffset, colorMask, sampleCoverage, lineWidth, pixelStorei (incl. UNPACK_* extras), hint, clear*, all with getParameter for every pname (Three reads ~30 of ~120).
• Objects: buffer, VAO, texture (2D, cube, 3D, 2D_ARRAY), sampler, framebuffer/renderbuffer (MRT, multisample, blit), program/shader (getActiveUniform/Attrib, UBOs, getUniformBlockIndex, transformFeedbackVaryings), query, sync, transform feedback.
• Data paths: bufferData/SubData/getBufferSubData/copyBufferSubData (ArrayBufferView + offset/length overloads), texImage2D/3D (ImageBitmap, HTMLImageElement, HTMLCanvasElement, OffscreenCanvas, VideoFrame, ImageData, ArrayBufferView, PBO offset), compressedTex*, texStorage*, readPixels (+PBO), uniform* incl. *ui, uniformMatrix*, vertexAttrib*, vertexAttribIPointer.
• Drawing: drawArrays/Elements(+Instanced, RangeElements), WEBGL_multi_draw, gl_DrawID, OVR_multiview2.
• Shaders: ES 3.00 and ES 1.00 (WebGL1 profile) pass-through with WebGL-strict validation, getShaderPrecisionFormat, getShaderInfoLog, getShaderSource, WEBGL_debug_shaders, KHR_parallel_shader_compile.
• Extensions (mandatory-for-Three first): EXT_color_buffer_float, EXT_color_buffer_half_float, OES_texture_float_linear, EXT_texture_filter_anisotropic, KHR_parallel_shader_compile, WEBGL_multi_draw, WEBGL_lose_context; then compressed textures (s3tc/etc/astc/bptc/rgtc/pvrtc as the GPU supports), EXT_disjoint_timer_query_webgl2, EXT_texture_norm16, WEBGL_clip_cull_distance, EXT_clip_control, WEBGL_render_shared_exponent, WEBGL_multisampled_render_to_texture, OVR_multiview2.
• Conformance: pin a Khronos WebGL conformance2 revision; run in QuickJS with a tiny DOM harness; publish pass/fail/skipped matrix (the creative report requires this, §2, §6.2).
• Three targets: webgl_geometries, webgl_materials_* (PBR, transmission), webgl_shadowmap*, webgl_loader_gltf (+ Draco/KTX2/meshopt), webgl_postprocessing_*, webgl_instancing_*, webgl_multiple_render_targets, webgl_buffergeometry_*, webgpu_* with WebGL2 fallback (TSL). Compare pixels against a reference browser (scripts/pixel-diff.mjs exists, tolerance-based).

7. Milestones and effort (one experienced dev; estimates, not measurements)

Total M0-M6 ~ 23-32 weeks (the “Three works well on modern targets” number quoted in the summary as 25-35 with slack); M7 to conformance-grade +8-12; M8 optional +4-6. Parallelisable: M3 (host) with M2 (L1); M4 with M3.

8. Risks and open questions

1. Interpreter speed (measured 14-30x behind V8 on Three’s code). Mitigation: Three presets, batching, engine swap seam. Might cap Pi 3 to “small scenes”. This is the biggest risk to “real performance”.
2. macOS backend choice: SDL3 GL 3.2 core (sdl.cpp:17-20) cannot run ES 3.00 shaders unmodified; Apple GL tops at 4.1 and is deprecated. ANGLE brings a large build (gn/depot_tools), BSD-3 license and a binary in tens of MB range (I: not measured); alternatives are ANGLE’s translator + GL 4.1 (drift risk) or a Metal backend (huge). Decide in M0. SDL3 can load an ES/EGL driver (I: hint-based), to verify.
3. VC4 (Pi 1-3) = WebGL1 only. Three >= r163 impossible; light profile needs older Three or Zinc-side renderer (already documented in the creative report). Pi 3B+ also had an unexplained VC4 GPU hang (gpu-renderer-design.md phase 1b).
4. Tile-based GPUs: Three’s frequent FBO switches (shadow maps, post-processing) cost flushes on VC4/V3D; MSAA render-to-texture unavailable on VC4.
5. Conformance vs “Three works”: the coverage list Three uses is 142 of 224 methods; the remaining ~80 exist for other libraries. “Complete WebGL2” is a separate, larger goal (M7).
6. Zinc ABI: no shared mutable buffers, scalar-only callbacks, no async completion (engines.md:103-108, 292). Typed-Zinc users of WebGL depend on that work; upstream-JS users do not.
7. Threading: ABI callbacks only on the engine thread (creative report §1); command-stream/render-thread needs care with the single-thread engine assumptions and the existing 3-slot plan.
8. Security: WebGL content is web-like untrusted input; zinc:script has memory/time limits and no I/O by design, the app runners do not (engines.md:57-59). A WebGL host must keep the same trust model (asset root, no arbitrary file reads, buffer-bounds validation before the driver).
9. Maintenance: Three r186 is moving (new texElementImage2D path, WebGPU-first roadmap; WebGLRenderer “maintained, no big new features”). Pin a version, publish the matrix.
10. Unverified here: quickjs-ng vs Homebrew qjs speed parity; Pi timings; ANGLE-on-SDL3 path; expo-gl performance; three-native’s actual Three revision and current working state; Mesa V3D GLES level on a real Pi 4/5 in this stack; how many Khronos WebGL2 tests need a browser-only feature.

9. Key file references

• Repo: docs/reports/gpu-renderer-design.md, docs/reports/render-perf-options.md, docs/plugins/display-gl.md, plugins/display-gl/{plugin.json,zgl.h,src/*.cpp}, runtime/vm/quickjs.cpp, docs/engines.md, runtime/include/zinc_abi.h, compiler/src/emit-js.ts:367, plugins/script/, docs/plugins/{script,three,canvas2d,wasm}.md, lib/std/{web,fetch}.ts, docs/guide/09-web-apis.md, docs/reports/creative-runtime-webgl-audio-2026-09-29.md, docs/reports/creative-studio-compatibility-demo-2026-09-29.md.
• Scratchpad (not in repo): mock-render-bench.mjs, scenegraph-bench.mjs (benchmarks), thr/ (three@0.186.1 install, gl-idents.txt), tn/ (three-native docs and shim files pulled with gh api).
• External: three-native, mquickjs README as vendored, expo-gl common/, ANGLE, headless-gl, Babylon Native, Three WebGLRenderer docs, Three WebGPURenderer manual, Mesa V3D, Mesa VC4, WebGL2 spec, Khronos tests, SPIRV-Cross, naga.

Zinc without Docker, a desktop “Studio” and a browser mode: findings and roadmap

Date 2026-09-30. Read-only study of /Users/mowmow/Lab/zinc (dirty tree, nothing modified) plus web research. Legend: [V] verified by reading the repo or running something locally, [W] from a web source (linked), [I] my inference / judgement, unverified.

0. Executive summary

1. Docker is used for every non-host target, and only there. Host builds (macos, and linux-on-Linux) use the host’s cmake + c++ + SDL3. Cross builds spawn docker run from compiler/src/cli.ts (table DOCKER, l.541-557; dockerBuild l.563; ESP-IDF l.605-680). Nothing in the compiler needs Docker conceptually: Docker is a way to pin a compiler + sysroot and, for rpi1/ps1/esp32, an emulator. [V]
2. The C++ the compiler emits and the runtime cross-compile cleanly with zig c++ already installed on this Mac (zig 0.15.2): runtime/zrt.cpp compiled OK for aarch64-linux-gnu.2.36, arm-linux-gnueabihf.2.31, arm-linux-musleabihf, x86_64-windows-gnu, x86_64-linux-musl, aarch64-macos, in about 1 s each; gfx/raster/ttf/host.cpp and hal_posix.cpp also OK on aarch64 and armhf. [V] Failures: wasm32-wasi (setjmp needs EH, irrelevant, wasm target uses Emscripten) and hal_posix.cpp on Windows (SIGBUS undeclared: no Windows HAL exists). [V] Not tested: a full link, SDL3, libcurl, FFmpeg, the ESP32, PS1, PS2 targets.
3. Realistic Docker replacement per target: linux/rpi(arm64/armhf)/rmpp/Windows/macos hosts: zig c++ + a downloaded, pinned sysroot for the few plugins needing system libs (SDL3, libcurl, FFmpeg, libgpiod) => Zinc-owned “toolchain manager”. ESP32: Espressif’s prebuilt xtensa-esp-elf / riscv32-esp-elf + ESP-IDF itself (git + Python + idf_tools.py), no Docker but a ~1.5-2 GB heavy SDK. PS1: PSn00bSDK release zip is already a prebuilt x86_64 Linux GCC (Docker only supplies the OS), so it is a download but x86_64 Linux hosts only (Windows/Mac need a VM/emulation or a rebuilt toolchain). PS2: ps2dev toolchain needs building or a Docker/WSL image. Emscripten: emsdk download.
4. Biggest strategic finding: the “no toolchain” path is half built. --engine zinc-vm + --core (docs/precompiled-core.md) already compile an app to ZBC4 bytecode in ~100s of ms with no C++ compiler, running on a precompiled core. Generalizing this to “pre-flashed Zinc VM firmware per board + bytecode upload” is the Arduino/MicroPython/Espruino-style loop and would remove the heavy SDK from the everyday path on ESP32 and Pi. It costs 3-10x on compute (docs/reports/zinc-vm.md), is not yet portable (VM is host macOS/Linux only today, docs/engines.md), and needs a “universal core” that the docs explicitly list as separate, unstarted work.
5. Browser mode is feasible in tiers, and the compiler front end is nearly browser-ready ([I]: 10k LOC TS on the pure-JS @typescript/typescript6, node:fs/path used in a handful of places, a virtual file map already exists in frontend.ts:145), but the current sim has no renderer (sim/gfx.mjs is all no-ops), so a preview needs the C++ rasterizer compiled to Wasm (an Emscripten wasm target with targets/wasm/hal_web.cpp canvas HAL exists).
6. Shell recommendation: Tauri 2 (or Electron if the Node engine is kept unbundled) around the existing Node CLI as engine, with a Rust/JS “toolchain manager” that downloads pinned, sha256+minisign-verified archives into a content-addressed cache. Ship the same UI as a PWA for browser mode.

1. What is in the repo today (verified)

1.1 Where Docker is used

Other facts:

• docker/versions.lock is referenced in docker/sdk-ps2/Dockerfile but does not exist in the tree listing (ls docker shows only the six dirs). [V]
• Docker also runs the tests (conformance byte-compare against the sim oracle, zinc test --target rpi1|ps1|esp32), so replacing Docker for builds does not remove emulators (QEMU user for armv6, PCSX-Redux, Espressif QEMU) from the test story. [V/I]
• Plugin system packages (packages in plugin.json: apk/apt) are installed by building a derived Docker image per package set (cli.ts:571-583). That is the one place where Docker acts as a package manager; a Docker-free design needs a sysroot store instead (section 4.2). [V]
• docs/decisions/0009-cross-targets.md, 0012-playstation-sdk-emulator.md, docs/security/third-party.md justify digests/sha256 pinning (existing supply-chain posture to reuse). [V]
• Host prereqs today: Node >= 23.6 (type stripping; compiler/bin/zinc.mjs), CMake, a C++17 compiler, SDL3, optional Ninja, Docker; esptool + Python for flashing; emcc for wasm; FFmpeg for studio previews. zinc doctor (cli.ts:928) checks node, cmake, c++, ninja, SDL3, docker only. [V]
• No Windows target exists: HOSTS = ['macos','linux','rpi1','sim','rmpp'] (native.ts:15), README mentions “Windows” only as UI windows. A Windows host can run the sim (Node) and, via Docker/WSL, cross targets; native Windows apps and a Windows HAL are new work (hal_posix.cpp:48 needs SIGBUS, plus SDL3 HAL is cross-platform so it is likely the small part). [V/I]
• Local machine: zig 0.15.2 at /opt/homebrew/bin/zig, Docker 29.4 (OrbStack), Node 24.14, Bun present. [V]

1.2 Pipeline shape (what a toolchain manager must feed)

zinc build = TS front end (frontend.ts, TS 6 JS API) -> sema/HIR/MIR -> one of: emit-cpp.ts (2088 lines) => zinc_main.cpp + generated CMakeLists.txt (cli.ts cmakeLists, l.~250-340) + runtime sources (runtime/*.cpp, runtime/mod/*.cpp) + plugin sources; emit-js.ts => run.mjs for the Node sim; emit-bc.ts => app.zbc for the VM (engines.ts). The build system contract is CMake + Ninja/Make + a C++17 compiler for hosted targets, CMake via emcmake for wasm, idf.py for esp32, and a CMake toolchain file for ps1/ps2 (targets/ps1/ps1.cmake, targets/ps2/ps2.cmake, HALs targets/*/hal_*.cpp). So a Docker replacement must supply: compiler(+sysroot) and CMake/Ninja (or replace CMake by direct zig c++ invocation, section 4.3). [V]

1.3 Existing “studio”, “sim”, web and wasm pieces

• apps/studio (docs/studio.md): ZincStudio, a Choregraphe-style node/box editor, itself a Zinc app on zinc:ui + SDL3 (macOS only, “Requirements: macOS with SDL3 …, Node.js, FFmpeg; docker for the Pi (QEMU) target”). It generates main.ts, runs targets sim / macOS window / remote-display preview (port 7711) / Pi QEMU / ssh device (zinc deploy --device). It has a Devices dialog listing apps announcing a remote display and manual ssh devices. It is not an IDE/board manager and not cross-platform. Name collision: the product proposed here should not be called “ZincStudio” unless the node editor is folded in as one view. [V]
• zinc:webview (macOS) hosts a “Tauri-like bridge” (zinc.invoke(...)) for the docs page. [V] (docs/studio.md, Docs section)
• site/ = Astro 7 static docs/marketing site (pages: index, features, limitations, performance, showcase, targets, docs). No playground, no wasm compile UI. [V]
• sim/ = 766 lines JS: the Node “oracle” runtime for --target sim; sim/gfx.mjs is a headless no-op (comment line 1: “headless (draw calls are no-ops)”); only text metrics come from baked resources.json. Nine sim modules import node: (fs, os, net, mqtt, osc, telemetry, sys, storage, assets), sim/zinc.mjs uses process.* (stdout, exit, getActiveResourcesInfo). So the sim is not a display preview and not browser-portable as is, but is small. [V]
• targets/wasm/hal_web.cpp (133 lines) + shell.html: an Emscripten canvas-2D HAL with keyboard/mouse/text/clipboard/RAF; the whole app (zrt + rasterizer + generated C++) compiles to app.wasm; zinc dev --target wasm reloads by page reload (docs/dev-mode.md). This is the existing in-browser runtime, but it needs emcc at build time (no compiler in the browser). [V]
• plugins/wasm = wasm3 0.5.0 interpreter linked into apps (running Wasm inside Zinc, opposite direction). [V]
• VM/engines: runtime/vm/main.cpp (1283 lines; uses <thread>, <fstream>, <atomic>; [[clang::musttail]] dispatch with “a bounded loop elsewhere”, l.377/843) + jit.h (AArch64 macOS/Linux only) + QuickJS runner. “Host targets: Host macOS/Linux” only (docs/engines.md). ZBC4 = 16-byte instructions, verifier bounds file sizes/counts and types (docs/engines.md, “VM and JIT”). Prototype numbers: 6.6-10.7x faster than QuickJS, 2-5x than Hermes, 2.8-15x slower than native (docs/reports/zinc-vm.md summary, measured on the prototype, the integrated backend “not described” by those numbers). [V]
• docs/precompiled-core.md: --core <dir> runs script builds with no CMake; “a script must use a subset of its native exports with matching ABI descriptors; graphics config, number profile, baked fonts/images, target, arch, debug must match”; “Core directories currently depend on their recorded source/library paths; this is a local development workflow, not a portable core package. Universal cores and external asset packs are separate work.” [V] This sentence is the technical gate for “bytecode upload to a preflashed firmware”.
• docs/reports/ios-core-runtime.md: the “Zinc Core for iOS” design (AOT core + .zbc OTA, Apple 2.5.2/DPLA 3.3.1(B)); the same architecture as what section 6 proposes for ESP32/Pi/browser. [V]
• Flash/monitor today: compiler/src/flash.ts (70 lines): host esptool/python3 -m esptool write merged-binary.bin at 0x0, 460800 baud; port discovery by regex on /dev/cu.usbmodem*|ttyACM*|ttyUSB* (Unix only); monitor is stty raw + read (Unix only). zinc deploy = export + generated deploy.sh over ssh (cli.ts:1110-1125; rmpp default root@10.11.99.1). [V]
• Boards: boards/*.json presets (waveshare-esp32-s3-matrix, esp32-2432s022, pimoroni-scroll-phat) merged into zinc.json (docs/boards.md); 3 boards, no index/registry, no USB VID/PID matching. [V]
• Pi rig (memory note + docs/reports/raspberry-pi.md): Pi 3B+ aarch64 trixie; recommended target is linux (arm64, Debian trixie, glibc, dynamic FFmpeg) not rpi1; deploy = zinc export --target linux + scp + detached start; must stop lightdm; fbdev display plugin. [V]

2. Toolchain research (web)

2.1 zig cc / zig c++ as a hermetic cross compiler

• glibc targeting: Zig ships tiny text files with glibc symbol versioning (27 KB gz) and can target any listed glibc version per arch (-target aarch64-linux-gnu.2.36), generating stub .so and letting the target’s loader resolve; default for cross was 2.17 in 2020 [W: Kelley, https://andrewkelley.me/post/zig-cc-powerful-drop-in-replacement-gcc-clang.html]. Zig builds musl/glibc-subset/mingw-w64 from bundled source on demand and caches the result [W same]. Overview says headers for 97 libcs in ~50 MiB [W: https://ziglang.org/learn/overview/]. 0.16.0 (2026-04-13, current stable per https://ziglang.org/download/) bundles LLVM 21, musl 1.2.5, glibc 2.43, Linux 6.19 headers, macOS 26.4 headers, and adds maccatalyst targets “free” because the vendored libSystem.tbd covers them [W: https://ziglang.org/download/0.16.0/release-notes.html]. Also: libc++ (LLVM 19 headers in 0.15+) is bundled [W: search result on Zig 0.15+; unverified detail]. Locally installed zig is 0.15.2, one minor behind. [V]
• Downloads & verification: tarballs 41-98 MiB for all hosts (Windows x86_64/aarch64, macOS x86_64/aarch64, many Linux), every download minisign-signed, public key published, JSON index for tooling, community mirrors [W: https://ziglang.org/download/]. This makes Zig itself an ideal first pinned package.
• Windows: mingw-w64 headers/import-lib generation bundled; MSVC ABI needs a Windows SDK found at build time [W: Kelley; issue #20781 in search]. Recommend x86_64-windows-gnu.
• macOS: Zig vendors libSystem.tbd + headers so pure-libc C/C++ links without an SDK; frameworks (Cocoa/Metal/CoreFoundation, needed by SDL3-static or any Apple UI) require a real SDK via -isysroot/SDKROOT [W: results for issues #10485, wails discussion #4267, macroquad zigbuild-osx article, https://ziglang.org/download/0.16.0/release-notes.html]. Some zig cc macOS cross segfault reports exist (https://codeberg.org/ziglang/zig/issues/31189) [W, single search snippet]. Apple’s license: Xcode and Apple SDKs Agreement says you agree “not to install, use or run the Apple SDKs on any non-Apple-branded computer” [W: https://www.apple.com/legal/sla/docs/xcode.pdf; https://developer.apple.com/forums/thread/114179]. So redistributing/downloading the SDK from Zinc to Linux/Windows hosts to build macOS/iOS apps is not legally clean; building macOS apps on a Mac only. Note Zinc’s macOS target uses SDL3 (a framework-light build) but macBundle, ObjC/Metal HALs and VideoToolbox plugin need the SDK. [I]
• Zinc-specific verified probe (this Mac, zig 0.15.2, zig c++ -std=c++17 -O2 -fno-exceptions -fno-rtti -Iruntime -Iruntime/include -c runtime/zrt.cpp): all six triples above compile. Not compiled: full app link, SDL3, plugins, ESP32/PS. [V]
• Caveats [I]: zig c++ uses its own libc++ (LLVM) not libstdc++: ABI-incompatible with prebuilt libstdc++ system libs (FFmpeg C API is fine, C++ system libs are not); mixed with CMake works via CMAKE_C_COMPILER="zig cc -target ..." wrappers (cargo-zigbuild, https://crates.io/crates/cargo-zigbuild, is the precedent); -march=armv6kz+fp -mfloat-abi=hard for Pi 1 should map to -target arm-linux-gnueabihf -mcpu=arm1176jzf_s; must test.
• Licensing: Zig MIT; bundled musl MIT, glibc LGPL (dynamic linking stubs only), mingw-w64 ZPL/public domain, LLVM Apache-2.0 w/ exceptions [I, standard knowledge].

2.2 Other prebuilt cross toolchains

2.3 Espressif toolchain and package managers

• ESP-IDF’s tools.json describes 15 tools (xtensa-esp-elf, riscv32-esp-elf, esp-clang, openocd-esp32, cmake, ninja, ccache, dfu-util, esp-rom-elfs, qemu, …), each with per-host {url, sha256, size} for linux-amd64/arm64/armhf/armel/i686, macos, macos-arm64, win32/win64/win-arm64 [W: tools.json]. install.sh/idf_tools.py implements install by that manifest, i.e. the design Zinc should copy (and can literally call). But ESP-IDF v6 itself (git clone + submodules, Python venv, component manager) is the heavy part; no way to build ESP-IDF projects with GCC alone. Docker today hides ~2+ GB. [I on size]
• Component Manager: idf_component.yml dependencies resolved during cmake from components.espressif.com or git (https://docs.espressif.com/projects/idf-component-manager/); Zinc already writes idf_component.yml from plugins (cli.ts:~650). Needs network at first build. [V/W]
• Espressif LLVM/Clang fork with Xtensa (esp-clang in tools.json; esp-rs/espup installs an LLVM fork + Xtensa Rust + GCC as linker [W: https://github.com/esp-rs/espup]): Xtensa (ESP32/S2/S3) is not in mainline LLVM; RISC-V ESP32-C3/C6/H2/P4 are, so zig c++ can target RISC-V ESP32 chips only as freestanding, and would still need ESP-IDF’s libs/headers. Zig cannot replace ESP-IDF; even a “zig for RISC-V ESP32” build needs IDF. [I]
• PlatformIO: Python core with SCons build, unified package manager (pio pkg), platforms/frameworks/toolchains are versioned registry packages cached in ~/.platformio, works on Win/mac/Linux/ARM [W: https://docs.platformio.org/en/latest/core/index.html, limited detail; SCons/~/.platformio layout from general knowledge, [I]]. Pattern: platform.json + packages with semver + registry; offline after first install.
• Arduino: arduino-cli (Go) + package_index.json spec: platforms[] with url, archiveFileName, checksum (SHA-256:...), size, toolsDependencies, tools[] with per-host (aarch64-apple-darwin, x86_64-mingw32, …) systems [W: https://docs.arduino.cc/arduino-cli/package_index_json-specification]. Arduino IDE 2 = Electron + Theia front end, arduino-cli daemon (gRPC) as backend for compile/upload, AGPLv3 [W: https://github.com/arduino/arduino-ide]. Boards Manager = third-party index URLs, i.e. an open ecosystem for boards.

2.4 Pi sysroot options

1. Rsync of /lib /usr/include /usr/lib from a real Pi (+ symlink fix): exact, but needs the device [W: search results incl. abhiTronix wiki, deardevices.com, earthly blog].
2. Debian multiarch/debootstrap --foreign sysroot per suite (bookworm/trixie) built once on Linux (needs root/qemu-user for —second-stage; mmdebstrap --variant=custom or a pure apt-get download + dpkg -x avoids root) and published as a Zinc-owned, sha256-pinned tarball (e.g. sysroot-debian-trixie-arm64-{sdl3,curl,ffmpeg,gpiod}.tar.zst, ~50-300 MB) [I]. This is the Docker-free equivalent of sdk-linux + the plugin packages derived images.
3. Static musl (as done for rmpp/rpi1 exports): no sysroot, works with zig c++ -target aarch64-linux-musl; no dynamic libs (FFmpeg, libcurl static builds required) [V for rmpp design; I for zig].
4. Raspberry Pi OS sysroot images: use the official image + losetup/mount: Linux-only, heavy [I].

• Recommendation: option 3 as default for “simple” apps, option 2 for plugin-heavy ones, glibc floor 2.36 (bookworm) so binaries run on bookworm and trixie and reMarkable 3.20+ (glibc 2.39 there; 3.14-3.18 have 2.35 so static remains right for rmpp). [I]

3. Shell, distribution, update, supply chain (web + judgement)

• Tauri 2: ~3-10 MB shell vs Electron 85-200 MB [W: rustify.rs / pkgpulse results]; bundles: AppImage/deb/rpm (Linux), DMG (macOS, needs signing + notarization for non-App-Store), MSI/NSIS (Windows) [W: https://v2.tauri.app/distribute/]. Updater plugin verifies Minisign/Ed25519 signatures with a configured pubkey [W: https://v2.tauri.app/plugin/updater/]. Sidecars: only self-contained binaries via bundle.externalBin, Node must be packaged first [W: https://v2.tauri.app/develop/sidecar/, https://v2.tauri.app/learn/sidecar-nodejs/]. Uses the OS WebView: WebKitGTK on Linux is the weak spot (WebSerial/WebUSB not there; irrelevant because the desktop shell uses native serial through Rust) [I].
• Electron: bundles Chromium+Node (WebSerial/WebUSB available in renderer; Node native in main). Arduino IDE 2 and Wokwi-free tools chose it; +100-150 MB. Reuses Node CLI as is with zero sidecar engineering [I].
• Neutralino: tiny, weaker updater/signing ecosystem [I].
• Engine packaging: (a) require/ship Node: Node SEA can embed a script and cross-generate for other platforms but binaries are ~100 MB [W: https://nodejs.org/api/single-executable-applications.html, dev.to results]; (b) bun build --compile cross-targets linux/macos/windows x64/arm64, ~50-100 MB [W: https://bun.com/docs/bundler/executables]; note the repo runs TS via Node type stripping and needs TS 6 JS API (@typescript/typescript6); the pnpm devDependency typescript@7.0.2 (native Go port) is present too [V package.json] and its JS API story differs (frontend.ts states “a swap to the TS 7.1 API touches this file only”, l.1-2). [V]
• Toolchain download design (all [I], modelled on cited practice: idf tools.json, Arduino package_index, Zig minisign JSON, Cargo/rustup):
  • toolchains.lock in each project or Zinc release: {id, version, host, url[], sha256, size, minisign sig, license}; content-addressed cache ~/.zinc/store/sha256-<hash>/ (immutable, hardlink/reflink into versioned symlinks); verify sha256 then unpack (tar.xz/zst/zip) into a temp dir and atomic rename; never execute before verification.
  • Signed index (minisign over the manifest, Zinc’s key pinned in the app; the Tauri updater key can be reused or a separate one) so a compromised mirror cannot swap URLs; vendor sha256 remains the leaf check.
  • Offline mode: zinc toolchain fetch --all-for <project> / --bundle offline.tar for classrooms; ZINC_OFFLINE=1 fails with the list of missing hashes; mirror support (ZINC_TOOLCHAIN_MIRROR).
  • Mirroring upstream binaries into a Zinc-controlled release bucket avoids link rot (Docker layers currently pin some URLs like the distrib.app PCSX-Redux build, docker/sdk-psx/Dockerfile), but check redistribution licenses (GPL toolchains: must offer sources).

4. Design (i): hermetic toolchain manager replacing Docker

4.1 CLI surface

zinc toolchain list [--installed]             # from signed index + toolchains.lock
zinc toolchain install <target|tool> [--host <triple>] [--offline-bundle f]
zinc toolchain doctor                          # what is missing, per target, with sizes
zinc toolchain gc | which <tool> | env <target> # print PATH/env for use in a shell
zinc build --target rpi1   # transparently ensures toolchain (prompt with size), then builds

Keep Docker as a fallback backend (--toolchain docker) during migration; add a Toolchain interface in cli.ts (prepare(target) -> {cc, cxx, sysroot, cmakeToolchainFile, runWrapper}) and turn DOCKER entries into two implementations. Today run output is ['docker', ...args] (exe as argv, cli.ts:590), which the interface must keep. [I, based on Built.exe usage]

4.2 Matrix: what replaces Docker, per target x host

Host columns: mac-arm (Apple Silicon), mac-x64, lin-x64, lin-arm64, win-x64. Cell = replacement; “H” = heavy SDK; “X” = blocked/needs VM.

What would still need Docker/VM/heavy SDK even after this work [I, honest list]: (1) ps1/ps2 on macOS/Windows and ps2 anywhere except via prebuilt-source builds; (2) ESP32 (ESP-IDF is a 2 GB SDK, not eliminable, only managed); (3) Apple targets from non-Mac hosts (license) and any iOS build (Xcode); (4) QEMU-based conformance tests for armv6/ESP32 on Mac/Windows (no qemu-user there); (5) the pcsx-redux headless runner on macOS; (6) exact-glibc reproducibility for release artifacts (keep the Docker/Nix image as the CI oracle that reproduces the zig build).

4.3 Removing CMake from the loop (optional)

For non-ESP hosted targets the generated CMakeLists.txt is ~90 lines; the compile is a flat list of .cpp + link flags. Because zig caches per-object, zig c++ *.cpp -o app is enough and removes CMake+Ninja as prerequisites (saves ~100 MB and a Python/CMake install on Windows). Risk: plugins with pkg_check_modules, find_package(SDL3). Keep CMake as the compat path, ship a pinned cmake+ninja (Kitware releases, and both are already in idf tools.json) in the manager. [I]

5. Design (ii): “Zinc Studio” desktop app

5.1 Reference architectures

5.2 Proposal

• Shell: Tauri 2 (small, signed updater, native serial via Rust serialport, mDNS via mdns-sd) hosting the web UI (which is also the browser-mode UI, section 6). Fallback Electron if WebKitGTK/WebView2 quirks bite. Editor: Monaco with the Zinc TS language service (the compiler already exposes zinc check --json LSP-style diagnostics, cli.ts help text l.~975; TS 6 language service can run in a worker). [I]
• Engine: keep the Node CLI as the engine, exposed as a long-lived daemon over JSON-RPC/stdio (like arduino-cli’s gRPC) so the compiler stays warm (the dev-mode doc notes compile-in-process keeps it warm, docs/dev-mode.md Hot reload). Package the engine either as (a) a private Node runtime + the TS sources (~50 MB, simplest, keeps import.meta layout for ZINC_ROOT), or (b) bun build --compile/Node SEA (~50-100 MB but must solve ZINC_ROOT-relative reads of runtime/, lib/, plugins/: ship them as a resource dir, frontend.ts:14). Recommended: (a) for v1. [I]
• Panels: Project & examples browser (from examples/, boards/); Board manager (index JSON of boards + presets + toolchain requirements, Arduino-style, third-party indexes allowed); Device manager (USB VID/PID matcher for ESP32 boards - Espressif 0x303A, CP210x 0x10C4:0xEA60, CH340 0x1A86:0x7523/0x55D4; ssh/mDNS _zinc._tcp for Pi/rmpp, reuse the existing remote-display announcement in plugins/display-remote); Build/Flash/Monitor panels (structured JSON progress from the CLI; today it only prints text, --json exists for check); Simulator preview (native SDL window embedded via remote display port 7711, exactly what apps/studio “Preview” does, or the web preview from section 6); Toolchain panel (progress, sizes, verify, offline bundle).
• Flashing/discovery details [I with cited tools]: ESP32: bundle esptool (PyInstaller-frozen or Rust espflash 3.x; esp-rs) instead of “pip install esptool” (flash.ts:31-38 today); native USB-Serial/JTAG boards (0x303A:0x1001) enter download mode by DTR/RTS or 1200-baud touch. Pi Zero/CM (RP1/BCM rpiboot), RP2040 picotool/UF2 drag-drop, STM dfu-util (also in idf tools.json [W]), OpenOCD (esp fork in tools.json [W]). Pi/rmpp: ssh + rsync/scp (native ssh exists on Win10+/mac/Linux; or a Rust russh), start detached and stream logs (pi-test-rig rules: detach, ConnectTimeout, never leave ssh attached). OTA for ESP32: esp_https_ota or a Zinc OTA endpoint (only meaningful once Wi-Fi bring-up exists: cli.ts:~640 says “no esp_wifi station bring-up yet”). [V for the note]
• Signing/notarization: macOS Developer ID + notarytool (Tauri docs [W]); Windows Authenticode/EV or Azure Trusted Signing to avoid SmartScreen [I]; Linux AppImage + deb/rpm/flatpak. Auto-update via Tauri updater with minisign key stored in CI secrets/HSM [W].
• Size budget [I]: shell 5-15 MB (Tauri) + engine 50 MB + Zig 45-98 MB on first target install + sysroots 50-300 MB + optional ESP-IDF 2 GB + emsdk 1 GB. Installer < 100 MB, everything else lazily fetched.

6. Design (iii): browser mode

6.1 What can run in a browser today (facts)

• Wasm clang/lld exists: binji/wasm-clang (clang+lld as wasm/WASI, in-memory FS, demo at binji.github.io/wasm-clang), Wasmer’s Clang-in-browser (Wasmer JS SDK 0.8), browsercc, llvm-wasm (wasi-sdk 33 / clang 22.1, updated 2026-08-10) [W: https://github.com/binji/wasm-clang, https://wasmer.io/posts/clang-in-browser, https://github.com/LuvHakii/llvm-wasm]. Zig also runs in browsers via zigtools/playground [W: https://github.com/zigtools/playground]. Cost: tens of MB of wasm (clang is ~30-60 MB unpacked [I]), several seconds per TU, C++ compile of a 50k-LOC runtime on every build is impractical unless the runtime is precompiled to .o/archive and only zinc_main.cpp is compiled (then link with wasm-ld, like the hot-reload path where only zinc_main.cpp recompiles, docs/dev-mode.md). Emscripten’s own libc/sysroot (SDL/GL glue) does not run in-browser; a wasi-sdk build would need its own HAL. Verdict: possible for a research demo, not the product path. [I]
• WebContainers: Node in the browser, but cannot execute native binaries, only WASM/JS; native addons off [W: https://blog.stackblitz.com/posts/bringing-sharp-to-wasm-and-webcontainers/, WebContainers troubleshooting]. No C++ toolchain, so irrelevant for emit-cpp, useful only for running the Node CLI unchanged (proprietary licence, COOP/COEP needed) [I].
• The Zinc compiler in the browser [grep-verified surface, feasibility inferred]: it uses @typescript/typescript6 (pure JS TS 6.0.2, works in browsers as the TS Playground shows [I]); Node-only touch points: frontend.ts (node:fs, path, fileURLToPath, ts.createCompilerHost l.133 and ts.sys.readFile l.145/150, process.cwd() l.162/182, ZINC_ROOT via import.meta.url), plugins.ts (plugin discovery reads the dir tree), jsx.ts, capabilities.ts, emit-js.ts (writes files + imports sim/zinc.mjs by path), hir/sema/infer/emit-bc only import node:path (pure, polyfillable). emit-bc.ts returns bytes (engines.ts writes app.zbc from emitBytecode(...)). Work: implement a virtual CompilerHost (a virtual map already exists in frontend.ts:145), embed lib/ (1.6 MB) + lib/std + plugin index.ts as a virtual FS, replace import.meta.url root, esbuild-bundle with .ts extension imports. emit-cpp also runs there (pure string generation, only ~3 node: imports) so the browser can show C++ or send it to a server. Not run-tested (I only grepped; the task asked to grep). Bundle size estimate 3-4 MB gz (TS lib + compiler) [I]. Compile speed of TS in browser: seconds for cold start, sub-second incremental [I].
• Running the emitted JS in the browser: emit-js output targets sim/zinc.mjs + node modules. Sim gfx is a no-op, so there is no pixel preview; a browser backend needs a canvas renderer or the C++ rasterizer in wasm (below). Non-gfx sim modules (fs/net/os/...) are Node-specific but tiny (766 LOC total). [V]
• zinc-vm in Wasm: runtime/vm/main.cpp is portable-ish C++17 (std::thread, std::fstream, [[clang::musttail]] with a loop fallback); Emscripten supports these (pthreads need COOP/COEP+SAB; can be built single-threaded if timers/fs threads are guarded, [I]); wasm has tail calls (-mtail-call) in Chrome/Firefox/Safari, musttail compiles under -mtail-call [I: unverified]. Graphics: gfx.cpp/raster.cpp/ttf.cpp + hal_web.cpp already exist and compile to canvas via Emscripten in the wasm target [V]. The verifier and ZBC4 bundle (bounded, “guest bytes cannot supply code or object pointers”, docs/engines.md) makes browser-side bytecode loading a good security fit [V]. This is the natural Tier A: ship one prebuilt “web core” zinc-vm.wasm (universal core with rasterizer + all wasm-capable modules, i.e. exactly the “universal core” item the docs mark unstarted) + JS glue; the in-browser compiler emits ZBC4 and hands it to the core. JIT irrelevant. Cost: 3-10x slower than native compute; zinc:ui frame cost +5-25% (ios-core doc estimates) [V doc claims].
• Web Serial/WebUSB flashing: esptool-js (Apache-2.0, Chrome/Edge 89+, can flash prebuilt bins at offsets; does not create images from ELF) [W: https://github.com/espressif/esptool-js]; used by MicroPython/CircuitPython web installers and ESP Web Tools [W: adafruit/Adafruit_WebSerial_ESPTool, micropython discussion #13222]. Espruino Web IDE sends JS to the device by Web Serial/Bluetooth [W: https://www.espruino.com/Web+IDE]. MakeCode micro:bit flashes hex via WebUSB, compiles in the browser to ARM Thumb machine code, offline after first load [W: https://makecode.microbit.org/device/usb/webusb, MSR blog https://www.microsoft.com/en-us/research/blog/rocket-fast-embedded-typescript-for-makecode-arcade/; PXT also has a bytecode VM for platforms that forbid codegen, ~5x slower]. Wokwi simulates ESP32 in the browser and via VS Code with your own ELF [W: https://docs.wokwi.com/].
• Availability: Web Serial: Chrome/Edge 89+, Opera 76+, Chrome Android 154+, Firefox desktop 151+ (since 2026-05, behind a site-permission add-on prompt), no Safari/iOS [W: https://caniuse.com/web-serial, https://hacks.mozilla.org/2026/05/web-serial-support-in-firefox/ (search result), MDN]. Secure context + user gesture; usable in dedicated workers [W: MDN]. WebUSB: Chromium only [I].
• COOP/COEP: SharedArrayBuffer (needed for threaded Emscripten builds, Wasmer, some WebContainers) requires Cross-Origin-Opener-Policy: same-origin + Cross-Origin-Embedder-Policy: require-corp|credentialless; on static hosts without header control, coi-serviceworker emulates them but must be same-origin, not from a CDN, and reloads the page once [W: https://web.dev/articles/coop-coep, https://github.com/gzuidhof/coi-serviceworker]. The Astro site can set headers on Netlify/Cloudflare; design the VM core single-threaded to avoid needing SAB [I].
• Storage/offline: OPFS + IndexedDB for projects, Service Worker + Cache API for the compiler/core wasm (MakeCode is the precedent for fully offline after first load [W]); File System Access API (Chromium) for opening real folders [I].

6.2 Tiers

Tier A: no-install simulator (weeks). Browser compiler (TS + HIR + emit-bc) -> ZBC4 -> zinc-vm.wasm web core with canvas HAL -> live preview, hot reload by re-loading bytecode (no page reload; better than today’s wasm target which reloads the page). Also deterministic replay (ZINC_RECORD/REPLAY concepts) for shareable sessions and a docs “run this snippet” widget on site/. Needs: browser-ported compiler, universal wasm core (Emscripten build of runtime/vm/main.cpp with the gfx modules; a zinc:* subset per capabilities.json “wasm” profile: no net/fs/threads), zinc.storage mapping to IndexedDB. Limitation: modules not in the core (user .spec.ts native modules, plugins with C++ such as sqlite/three/video) are unavailable in Tier A (native C++ cannot be compiled in-browser); pure-Zinc plugins fine.

Tier B: compile in the browser to ZBC4, then upload bytecode to a device running the Zinc VM firmware (the Arduino-like key insight; months). Flow: user picks “ESP32-S3 Matrix” -> Studio flashes once a board core firmware (prebuilt by CI per board preset from boards/*.json: display drivers, IMU plugin, pools/heap already in the preset) with esptool-js/esptool -> subsequent “Upload” only sends app.zbc (KB, not a 1.6 MB image) over serial (framed protocol, CRC, to a zbc flash partition, or RAM for “Run” like MicroPython raw REPL) or OTA/ssh to Pi (scp app.zbc + zinc-core service). Benefits: no toolchain at all for daily use (removes ESP-IDF, Docker, sysroots from the student path), 1-2 s upload, works from a Chromebook. Costs/risks: (1) VM is host-only today: needs a bare-metal/ESP-IDF port of runtime/vm/main.cpp (uses <thread>, <fstream>, std::deque/map; ESP32 heap default 160 KiB, no PSRAM on CYD board, docs/boards.md), an ESP-IDF build of the core is still needed but by CI; (2) VM is 3-10x slower than native and ESP32 has no JIT (fine); (3) every native module a script may call must be linked into the core (“script must use a subset of its native exports”, docs/precompiled-core.md), so a board core = superset of plugins for that board (size!); (4) ABI/versioning: ZBC4 is “experimental”, bundles “must be rebuilt” on change (docs/engines.md), so define a stable ZBC + core ABI version handshake with a semver’d core; (5) memory: ZBC4 16-byte instrs are wasteful for 4 MB flash boards (the design doc’s compact 32-bit encoding is not implemented) [V]. Also fits Pi 1-5, rmpp (ship core as an AppLoad app), and even PS1/PS2 (bytecode in the disc image) [I]. Recommendation: make Tier B the default path for education, keep full native firmware (zinc build --target esp32) for “production” and performance.

Tier C: cloud compile service (weeks after toolchains are Docker-free; infra + ops). API: POST project -> containerized zinc build with the same pinned toolchains -> returns firmware .bin (esp32), ELF, or wasm. Needed for: native builds from the browser (esp32 full firmware, rpi/linux arm binaries, PS1). Arduino Cloud, PlatformIO, Wokwi-style. Must sandbox (untrusted C++ via native .spec modules and plugin sources = arbitrary code; gVisor/Firecracker, no network, cpu/mem limits), and rate-limit; the browser then flashes the returned image with esptool-js. Data privacy: source leaves the machine (opt-in). Costs: ESP-IDF build ~1-3 min cold on a small instance [I]. Reuse the existing conformance corpus to smoke-test. This is where Docker legitimately remains (server side).

Tier A+ (optional): in-browser C++ compile of only the app TU with wasm clang against a prebuilt runtime archive to build wasm apps (Tier A of native fidelity). Research-grade, skip in v1.

7. Roadmap, effort and risks

Effort in person-weeks (pw) for one engineer familiar with the codebase; [I] = estimates, not measured.

Suggested order: P0 -> P1 -> P2 -> P4 -> P5 (Linux/mac first) in parallel with P6 -> P7 (public wow: “try Zinc in your browser”) -> P3 -> P8 -> P9. Total to “Studio + Docker-free + Tier A” is ~30-40 pw; Tier B adds another ~12-20 pw and is the highest-risk/highest-value item. [I]

Security and supply chain

• Everything downloaded is pinned by sha256 and the index is signed (minisign) with an offline root key; reproducible provenance table in docs/security/third-party.md extended per toolchain (already done for Docker digests). Consider Sigstore/SLSA attestations on Zinc-built sysroot tarballs.
• Untrusted-project risk: projects contain .spec.ts native modules, plugin sources, sdkconfig, idf_component.yml git deps => building a downloaded project is arbitrary code execution (same as any repo; docs/studio.md already says “Open projects you trust”). Studio needs a trust prompt (VS Code Workspace Trust model) [I].
• Browser: run compiler in a Worker, CSP, VM core sandbox = wasm; bytecode verifier is the trust boundary (docs/engines.md). WebSerial only from user gesture; never auto-flash.
• Code signing: Apple Developer ID + notarization; Windows Authenticode; Tauri update signatures; pin the updater public key; the toolchain-index key must be different from the app key.
• ESP32 flash contains Wi-Fi credentials when targets.esp32.wifi is used (cli.ts ~ l.650) => keep out of committed zinc.json/ZINC_WIFI_PASSWORD (already supported) and out of cloud builds.

8. Comparison

9. Verified locally (commands run)

• which zig docker node bun -> zig 0.15.2 (Homebrew), Docker 29.4.0 (context OrbStack), Node v24.14.0, bun present.
• zig c++ -target <T> -std=c++17 -O2 -fno-exceptions -fno-rtti -Iruntime -Iruntime/include -c runtime/zrt.cpp for T in aarch64-linux-gnu.2.36, arm-linux-gnueabihf.2.31, arm-linux-musleabihf, x86_64-windows-gnu, x86_64-linux-musl, aarch64-macos: all OK (~0-1 s each); wasm32-wasi: fails (setjmp needs EH, expected). Outputs written only to the session scratchpad zt/.
• Same flags for runtime/{gfx,raster,ttf,host}.cpp and targets/common/hal_posix.cpp: OK on aarch64-linux-gnu.2.36 and arm-linux-gnueabihf.2.31; on x86_64-windows-gnu all OK except hal_posix.cpp (SIGBUS undeclared).
• Greps for node-only APIs across compiler/src (node: import counts per file, ts.sys, createCompilerHost, process.) and sim/*.mjs. Not run: the compiler in a browser-like environment, a full zig link of an app, SDL3/FFmpeg under zig, any Wasm build of the VM, any ESP32/PS build.
• Not verified (web): Bootlin host restriction, ARM GNU host list, PSn00bSDK Windows zips, PCSX-Redux macOS availability, Espressif archive sizes, wasm -mtail-call with musttail, all effort numbers.

10. Sources (web)

• Zig: https://ziglang.org/download/ , https://ziglang.org/download/0.16.0/release-notes.html , https://ziglang.org/learn/overview/ , https://andrewkelley.me/post/zig-cc-powerful-drop-in-replacement-gcc-clang.html , https://github.com/ziglang/zig/issues/10485 , https://codeberg.org/ziglang/zig/issues/31189 , https://crates.io/crates/cargo-zigbuild
• Apple license: https://www.apple.com/legal/sla/docs/xcode.pdf , https://developer.apple.com/forums/thread/114179
• Toolchains: https://github.com/mstorsjo/llvm-mingw , https://toolchains.bootlin.com/ , https://bootlin.com/blog/bootlin-toolchains-2026-08-released/ , https://gitlab.arm.com/tooling/gnu-toolchains-for-arm , https://github.com/espressif/crosstool-NG/releases/ , https://github.com/espressif/esp-idf/blob/master/tools/tools.json , https://docs.espressif.com/projects/idf-component-manager/ , https://github.com/esp-rs/espup
• Arduino/PlatformIO: https://docs.arduino.cc/arduino-cli/package_index_json-specification , https://github.com/arduino/arduino-ide , https://docs.platformio.org/en/latest/core/index.html
• Shell/distribution: https://v2.tauri.app/distribute/ , https://v2.tauri.app/plugin/updater/ , https://v2.tauri.app/develop/sidecar/ , https://v2.tauri.app/learn/sidecar-nodejs/ , https://nodejs.org/api/single-executable-applications.html , https://bun.com/docs/bundler/executables
• Browser: https://github.com/binji/wasm-clang , https://wasmer.io/posts/clang-in-browser , https://github.com/LuvHakii/llvm-wasm , https://github.com/zigtools/playground , https://blog.stackblitz.com/posts/bringing-sharp-to-wasm-and-webcontainers/ , https://github.com/espressif/esptool-js , https://developer.mozilla.org/en-US/docs/Web/API/Web_Serial_API , https://caniuse.com/web-serial , https://hacks.mozilla.org/2026/05/web-serial-support-in-firefox/ , https://web.dev/articles/coop-coep , https://github.com/gzuidhof/coi-serviceworker , https://www.espruino.com/Web+IDE , https://makecode.microbit.org/device/usb/webusb , https://www.microsoft.com/en-us/research/blog/rocket-fast-embedded-typescript-for-makecode-arcade/ , https://docs.wokwi.com/ , https://github.com/adafruit/Adafruit_WebSerial_ESPTool
• Pi sysroot: https://github.com/abhiTronix/raspberry-pi-cross-compilers/wiki/Cross-Compiler-CMake-Usage-Guide-with-rsynced-Raspberry-Pi-32-bit-OS , https://deardevices.com/2019/12/25/raspberry-pi-sysroot/ , https://earthly.dev/blog/cross-compiling-raspberry-pi/

11. Repo file references (main)

compiler/src/cli.ts (DOCKER l.541-557, dockerArgs l.559, dockerBuild l.563, IDF_IMAGE l.605, espBuild l.618, emEnv l.688, wasmBuild l.699, doctor l.928, deploy/flash l.1110-1131), compiler/src/flash.ts, compiler/src/frontend.ts (l.1-14, 133-150), compiler/src/native.ts:15, compiler/src/engines.ts, compiler/src/emit-bc.ts, compiler/src/emit-js.ts:387, docker/*/Dockerfile, targets/capabilities.json, targets/wasm/hal_web.cpp, targets/common/hal_posix.cpp:48, runtime/vm/main.cpp:377,843, sim/gfx.mjs:1, docs/precompiled-core.md, docs/engines.md, docs/studio.md, docs/boards.md, docs/dev-mode.md, docs/reports/{raspberry-pi,zinc-vm,ios-core-runtime}.md, docs/targets/{remarkable-paper-pro,playstation}.md, docs/decisions/0012-playstation-sdk-emulator.md, apps/studio/README.md, memory pi-test-rig.md.

Other JS engines for Zinc: JavaScriptCore, V8, LibJS (and the rest)

Status: research only, nothing implemented. Date 2026-09-30. Tags: [V] verified here (read code or ran it), [W] from a web source (linked), [I] inference or estimate. Effort figures are one strong developer, unvalidated. Prior context: README.md, quickjs-jit-aot.md, threejs-webgl.md.

0. Verdict

1. Build a small zinc-js-engine C++ interface, then support exactly two engines: QuickJS-ng (default, everywhere, the only one that works on iOS/ESP32-adjacent/rpi1) and JavaScriptCore (macOS/iOS system framework, plus JSCOnly on Linux arm64/x64 as an experiment). V8 is the third, opt-in, desktop/server-only engine and only if JSC-on-Linux fails. LibJS is not viable today.
2. The speed gap is real and JSC closes it. Measured here (M-series Mac, same kernels as the earlier reports): Three r186 mock-GL render of 500 cubes is 13.2 ms in quickjs-ng, 0.54 ms in JSC (JIT), 0.81 ms in V8/node, 6.8 ms in JSC with JIT off, 5.8 ms in V8 --jitless. Even the no-JIT modes of JSC and V8 are ~2x faster than QuickJS on Three’s code. That matters for iOS, where no engine gets a JIT.
3. iOS: JIT is not available to any in-process engine, JSC included. In-process JSContext runs without JIT [W: Apple DTS reply, forums 746159]; WKWebView has JIT but is out of process; BrowserEngineKit’s JIT protection is EU browsers only. So on iOS the choice is between interpreters: JSC LLInt (free, system-provided, 0 bytes), QuickJS (+AOT from the earlier report), or V8 jitless (~+20 MB [I]).
4. The current ABI cannot do zero-copy. zinc_abi.h v4 says BYTES are readonly snapshots and adapters copy. WebGL/Three needs typed-array views onto native memory. That needs an ABI v5 addition (section 4), independent of the engine choice.

1. Measurements run for this report [V]

Machine: Apple M-series Mac, macOS 24.6, node v24.14 (V8 13.6.233.17-node.41), quickjs-ng build in the scratchpad (bench/qjs_ng, 1.09 MB), Apple jsc at /System/Library/Frameworks/JavaScriptCore.framework/Versions/A/Helpers/jsc. Kernels: scratchpad/bench/{fib,mandel,objs}.js (fib(32); 300x300 mandelbrot; 200k new P plus string/object churn). Single run each, warm machine, differences under about 15% are noise.

Three r186 (esbuild bundle, mock GL Proxy, scratchpad/thr/r.js), ms per frame:

Process footprint for print(1): JSC 7.2 MB RSS, node 44.8 MB, quickjs-ng 2.1 MB; wall startup: JSC and QuickJS under 10 ms, node ~30 ms [V]. JSC on macOS costs 0 bytes of app size (system framework) [V: du reports 0B because it is in the dyld shared cache]. node is 119 MB, bun (JSC based, also with its own runtime) 61 MB [V, file sizes]. Caveats: jsc shell has no Zinc bindings; the mock GL crossing is a JS function, so native-crossing cost per engine is not measured; the JSC-no-JIT run still uses LLInt with its own assembly fast paths, so it is stronger than a naive interpreter; V8 --jitless on node still has embedded builtins compiled natively.

Published numbers [W]: V8 jitless is about 40% slower on Speedometer 2.0, 80% on Web Tooling, 6% on a real YouTube app, heap -1.7% (v8.dev/blog/jitless). LibJS moved Speedometer 3 from 4.11 to 4.22 in one April 2026 optimisation (newsletter), i.e. it is far behind V8/JSC. Hermes reports vs QuickJS only as charts, no numbers extractable (Static Hermes report). weval on SpiderMonkey/Octane: 2.17x geomean vs its interpreter (Fallin, PLDI 2025).

2. Comparison matrix

Other engines, briefly:

3. What each engine means for Zinc’s QuickJS runner [V read of runtime/vm/quickjs.cpp]

The runner (333 lines) does the following engine-specific work, which is what a zinc-js-engine interface has to cover:

Conclusion: the ABI side (zinc_abi.h) is engine-neutral and reusable unchanged, since no engine value crosses it [V]. What must be abstracted is a “JS host” trait of about 15 operations (section 5), not the ABI.

4. Zero-copy and the ABI (crucial for WebGL/Three.js)

zinc_abi.h v4 comment: “BYTES are readonly value snapshots: adapters copy inputs and outputs; no alias identity or native mutation is exposed”, and NUMBERS are read-only double[] arguments only [V]. In quickjs.cpp a u8[]/number[] argument is rebuilt by walking a JS Array element by element and pushing into a std::vector (lines about 140-165) [V]. That is O(n) with per-element JS_GetPropertyUint32, a typed array would not even be accepted (JS_IsArray). So today even bufferData with a Float32Array is impossible.

Needed (engine-neutral) ABI v5 addition, prototype:

• ZINC_TYPED_VIEW argument type: { void* data; uint32_t byte_length; uint8_t elem_kind; uint8_t writable; }, borrowed for the duration of invoke; same borrowing rule as strings. All three engines can give a pointer to an ArrayBuffer backing store:
  • QuickJS: JS_GetArrayBuffer / JS_GetTypedArrayBuffer [V: earlier report].
  • JSC: JSObjectGetTypedArrayBytesPtr + JSObjectGetTypedArrayByteOffset/Length (JSTypedArray.h) [V].
  • V8: ArrayBufferView::Buffer()->GetBackingStore()->Data() plus ByteOffset().
• ZINC_NATIVE_BUFFER result: native-owned memory exposed as an ArrayBuffer without copy (JS_NewArrayBuffer with free func; JSC JSObjectMakeArrayBufferWithBytesNoCopy with JSTypedArrayBytesDeallocator; V8 ArrayBuffer::NewBackingStore(data, len, deleter)). Needed for mapBufferRange/readPixels-style APIs and for shared Float32Array staging arenas.
• Rule: native code must not retain the pointer after invoke returns (GC and detach), matching the current “borrowed for the duration of invoke” contract.

Effort: 4-6 days for ABI, abi.ts and the QuickJS adapter plus tests; +2-3 days per further engine. This is the highest-value change in this whole report and it helps QuickJS as well.

5. Proposed abstraction: zinc-js-engine

Keep it a compile-time (template or link-time) interface, not a virtual hierarchy per value; runner main loop (timers, poll_host, deadline, exit code, zinc::RunnerHost, module registry, resources) is engine-neutral and extracted once from quickjs.cpp (about 120 of the 333 lines).

struct JsEngine {                      // one implementation per engine, chosen at build time
  bool init(const Limits&);            // memory, stack size
  bool defineHostObject(name, table);  // __zincHost: write, timer, now, exit, env ...
  bool registerNativeModule(name, const ZincModule*);   // synthetic module or global fallback
  bool evalMain(path, source);         // ESM main (or IIFE bundle on JSC without modules)
  int  runMicrotasks();                // >0 progress, 0 none, <0 exception
  bool call(Fn, args...);              // for timers and ZincCallback
  ZincHandle makeCallback(Fn);         // ref-hold; released via resource_release
  void  setInterrupt(deadline);
  void  reportError(ex);               // uniform stderr format so tests stay byte-exact
  void  setRejectionHook(cb);
};

Marshalling code (args to ZincValue, results back) is generated per engine from the same descriptor table (ZincExport), so the ~120 lines of conversion in nativeCall get one implementation per engine but no logic change. New files: runtime/vm/jsengine.h, runtime/vm/js_quickjs.cpp (moved code), js_jsc.cpp, later js_v8.cpp. CLI: --engine quickjs|jsc|v8 reuses the existing engines.ts per-engine build directories and engine.json fingerprint. Parity harness tests/engines/run.mjs adds modes jsc and v8 (byte-exact stdout vs native/VM/QuickJS), which is the correctness gate.

Module loader: keep emit-js as ES2022 modules for QuickJS/V8; for JSC add a --js-format iife bundler step (one-file, zinc:* imports rewritten to __zincModules["zinc:x"]), which also removes file I/O from the runner and suits iOS bundles. Event loop: unchanged (Zinc-owned). Timeouts: interrupt/terminate per table in section 3. Memory limit: enforced in Zinc’s ABI allocations (already 64 MiB composite cap) plus process rlimit for JSC.

6. Fit for Three.js / WebGL per platform

Cost model to remember: the earlier report found the crossing is not the bottleneck and this report confirms that Three’s own JS is. So a JIT engine on desktop/Pi-class targets is the lever; on iOS the lever is Three’s own batching (InstancedMesh/BatchedMesh) plus JSC LLInt.

7. Phased plan (one developer)

Total for JSC macOS + Pi: about 35-55 days, V8 as extra: +20-30 days. LibJS: no phase; revisit in 12+ months.

8. Risks

• JSC portability (highest): JSCOnly is real and builds on ARM64/ARMv7 [W], but WebKit build time, size and toolchain (ICU, Ruby/Perl/Python, compilers new enough) are uncertain for cross-builds to Pi; JIT on ARMv6 (rpi1) is impossible, so rpi1 stays QuickJS. Not built in this session.
• JSC API gaps: no C-level modules, microtask control, rejection tracker or supported execution time limit; each needs a workaround and may cause parity differences from QuickJS.
• iOS policy: rules can change; today, in-process JSC has no JIT [W] and BrowserEngineKit JIT is EU-browser only. JSC as an only engine for iOS Zinc apps would need a fallback to QuickJS.
• V8: 20-30 MB, gn/depot_tools or third-party prebuilts (rusty_v8 static libs are large and versioned per Rust crate), C++ API churn every release; not viable on Pi 3B+, on iOS only as jitless.
• LibJS: test262 97.8% is good, but no JIT by design, no stable embedding API, C++/Rust mix with Rust mandatory since April 2026, tightly coupled to Ladybird build, slower than V8/JSC (Speedometer 3 about 4.2 [W] vs. browsers in the 20-40 range [I]). Only useful as a curiosity.
• Parity drift: microtask timing, error message text, property enumeration order, float formatting differences between engines can break byte-exact tests; add a normalisation layer only where the ECMAScript spec allows variation.
• Licences: JSC is LGPL/BSD mixed [I: verify per-file]; dynamic linking on Apple is fine, static linking on Linux needs a license review against docs/licenses.md (MIT-only for engines).

9. AOT-friendly for iOS (what remains)

• Zinc VM (typed bytecode, tail-call threaded interpreter) and Zinc->C++ AOT stay the primary iOS path; both are engine-free.
• QuickJS: precompiled bytecode (JS_WriteObject) and qjsc -A AOT ported to ng are iOS-legal because they are linked at build time [V: earlier report]; JSC and V8 give no such AOT (JSC bytecode cache is private; V8 code cache needs a matching build and jitless still interprets).
• JSC in-process (LLInt) is legal on iOS and is the fastest no-JIT engine tested here [V], but ships JS as source; V8 jitless is legal, larger.
• Rule from docs/reports/ios-core-runtime.md: no downloaded dylibs/machine code/wasm AOT artefacts; OTA is interpreted bytecode or source only.

10. Not verified

Not built: JSCOnly, V8 monolith, LibJS, Hermes, mozjs, quickjs-in-wasm+weval. All sizes for those are estimates. JSContextGroupSetExecutionTimeLimit availability on public headers was only partially checked (grep found the context-group API but not the time-limit declaration in public headers). BrowserEngineKit details come from an Apple DTS forum reply, not the App Store guidelines text; re-read App Review Guideline 2.5.2 and the JIT entitlement docs before committing to a strategy. LibJS embedding conclusions are inferred from the newsletter and repository structure, not from building it. The Three mock bench measures JS-side cost only.

Sources

• Apple DTS thread: https://developer.apple.com/forums/thread/746159
• V8 jitless: https://v8.dev/blog/jitless ; V8 iOS cross-compile: https://v8.dev/docs/cross-compile-ios
• Ladybird April 2026 newsletter (LibJS 97.8% test262, Rust mandatory, no-JIT stance): https://ladybird.org/newsletter/2026-04-30/ ; results: https://ladybirdbrowser.github.io/libjs-website/test262/
• JSCOnly: https://trac.webkit.org/wiki/JSCOnly ; https://github.com/WebKit/webkit/blob/main/Source/cmake/OptionsJSCOnly.cmake ; cross-build https://trac.webkit.org/wiki/JSCOnly/CrossBuildAndRemoteTestJSCLinux
• Hermes: https://github.com/facebook/hermes/blob/static_h/doc/blog/2025-07-15-static-h-performance-june-2025.md
• Boa: https://github.com/boa-dev/boa ; https://lobste.rs/s/upi3xa/boa_release_v0_21_new_release_boa
• Kiesel: https://kiesel.dev/ ; Duktape/mujs sizes: https://www.x-cmd.com/install/duktape/
• weval: https://cfallin.org/blog/2024/08/28/weval/ ; https://cfallin.org/pubs/pldi2025_weval.pdf
• Local: runtime/include/zinc_abi.h, runtime/vm/quickjs.cpp, docs/reports/ios-core-runtime.md, macOS SDK JavaScriptCore.framework/Headers/JSTypedArray.h; bench inputs in the session scratchpad (bench/, thr/r.js).

From a textarea to a real code editor: editing core, tree-sitter, LSP, Zinc language server (2026-09-30)

Status: research only, nothing here is implemented. Tags: [verified] read in this repo, [web] fetched or searched during this study (sources at the end), [bg] background knowledge not re-checked online, [inferred] my reasoning or estimate. Effort figures are estimates in engineer-weeks (ew) for one person who knows the codebase. Repo state: the working tree was dirty (many modified files); line numbers below are from the tree as read.

1. What exists today

1.1 The editor is the engine’s <TextArea>, not a component

There is no separate editor widget. A “code editor” is a <TextArea> in code mode plus a small extension API. [verified]

• lib/std/ui.ts:17-18: INPUT/TEXTAREA node tags. ui.ts:233: n.ed = new Edit(tag === TEXTAREA).
• codeMode() (ui.ts:1151): a multi-line field with lineNumbers or a mono font. In code mode Tab inserts 2 spaces and Enter keeps indentation (ui.ts:1426, docs/ui.md:28).
• Extensions for editors (ui.ts:1556-1640, docs/ui.md:49-63): setMarks (line/fill/box/squiggle/gutter marks), setEditColors, setHighlightAt(h, f(line, start)), editView, scrollEditTo, editRowOf, repaint.
• examples/zed-editor (2.5k lines of Zinc, examples/zed-editor/README.md) is a Zed-style app on top of it: project tree, tabs with preview semantics, find bar, palette/finder, minimap, terminal panel via zinc:process, zinc check --json diagnostics as squiggles. “One textarea per buffer” (README, “What it shows”). Scenes and a scroll benchmark are scripted through the input test hooks (ZINC_DEMO=...).
• Conformance test: tests/conformance/code_editor.tsx drives the extension API headlessly and records .out files per resolution and number profile. [verified]

1.2 Text model

class Edit (ui.ts:80-108): the whole document is one string value; caret/anchor are UTF-16 offsets; undo/redo are whole-string snapshots in string[] stacks capped at 100 (ui.ts:1318-1324 snapshot()); an edit is value.slice(0,a) + s + value.slice(b) (ui.ts:1333). One selection only. Typing coalesces into one undo step (e.typing). There is no tree/branching undo. [verified]

Zinc strings are UTF-8, so indexing a non-ASCII string costs O(offset); docs/ui.md:66-68 says fields work “line by line” and code walking the value should split('\n'). Consequences [verified/inferred]:

• Every edit is O(document size): string rebuild, then ensureRows (ui.ts:1153-1181) re-splits the whole value and re-wraps every line whenever value or width changed (rowsFor === value check at ui.ts:1153).
• rowOf is a linear scan over rows (ui.ts:1185-1188); offAtX and xIn measure per character by calling textWidth on 1-char slices (ui.ts:1190-1201); hit-testing and caret x are O(row length) text measurements.
• zed-editor keeps its own second copy of the text: Doc (examples/zed-editor/src/app/document.ts:29-61) re-splits into lines/starts after each edit and re-tokenizes from line 0 (ponytail: comment at line 52). Measured by the authors: keystroke in a 5006-line file 4-5 ms; 5000-line scroll at 111-119 fps (README “Scenes and measurements”). That is fine for thousands of lines and hopeless for tens of MB.

1.3 Input, IME, clipboard, layout, rendering

• Keys/typed text arrive in order from the HAL (docs/ui.md:260-271). Movement/deletion handling is in ui.ts:1379-1430 (word/line/char, goal column goalX). Pointer: click, word/line selection, drag select (ui.ts:1941).
• IME: startTextInput(x,y,w,h) follows the focused field so the OS candidate window is placed next to it (ui.ts:2178-2182, runtime/gfx.cpp:912-913, targets/macos/hal_sdl.cpp:415). Only committed text works: docs/ui.md:270 “Not done yet: IME composition preview … multiple carets, word-wise drag selection after a double click”. No preedit string, no marked-text range, no TEXT_EDITING handling. [verified]
• Clipboard: hal_clipboard_get/set (weak default process-local; SDL3 HAL implements it, hal_sdl.cpp:430-437), clipboardText/setClipboardText exposed by zinc:gfx. Text only. [verified]
• Bidi / shaping: none. runtime/ttf.cpp (332 lines) is a from-scratch TrueType rasterizer: cmap lookup (format 4/12, ttf.cpp:62), glyf outlines, hmtx advances; no GSUB/GPOS/kern tables found (grep “kern|GPOS” empty), glyph cache per (font, size), fixed table of 32 fonts (ttf.cpp:228). textWidth (gfx.cpp:796) sums advances. Consequently: no ligatures, no combining marks positioning, no Arabic/Indic shaping, no bidi reordering, no color emoji, no font fallback chain. [verified for what is present, inferred for “no fallback” from absence of any code]
• Rendering: software rasterizer in bands, on the CPU (runtime/raster.cpp); an optional GPU/GLES path is designed and Phase 1 implemented (docs/reports/gpu-renderer-design.md). The editor paints only visible rows: paintEdit slices the visible rows once per frame (docs/ui.md:66-68). Wheel/trackpad physics are engine-level.
• Accessibility: nothing for text fields (no AccessKit or platform tree found). [inferred from grep: no matches]

1.4 What zed-editor already covers (so it is not on the roadmap)

Tabs and preview tabs, find in file (plain text, not regex; src/app/search.ts, 74 lines), fuzzy finder and palette, bracket matching marks, indent guides, soft wrap, zoom, minimap (canvas, token-coloured), lexical highlighting for TS/TSX/JSON/Markdown/CSS with carried per-line state (src/app/syntax.ts, 234 lines), file tree, terminal output only (no stdin/PTY), diagnostics from zinc check --json on the saved file (src/app/tools.ts:70-79). Its own “Limits” section: one caret, no split panes, no go-to-definition, tokens recomputed from line 0, no unsaved-buffer prompt on window close. [verified]

1.5 Platform facilities the roadmap can lean on

• Process spawn already exists: zinc:process (plugins/process/, docs/plugins/process.md): spawn(cmd, args, {cwd, env}), onStdout(line), onStderr, onData(chunk, isStderr) raw chunks with UTF-8 never split, write(s), closeStdin(), kill, exit code, up to 32 children, posix_spawnp with three pipes and a zrt::Poller on the event loop; targets macos/linux/rpi1. Callbacks are only delivered from the event loop. [verified] Gaps for LSP: write blocks when the child stops reading and the 64 KiB pipe is full (docs/plugins/process.md:54-55); no PTY; string-only I/O (no binary-safe Content-Length counting: LSP counts bytes, JS/Zinc string lengths are UTF-16/UTF-8-ambiguous, see 5.2).
• TCP/Unix sockets/WebSocket exist: zinc:socket (docs/plugins/socket.md), non-blocking, poller-driven, requires net + process. So LSP over TCP is possible today. [verified]
• Plugin system: plugins/<name>/plugin.json; kind: module = Zinc index.ts + optional native C++ (native/<name>.spec.ts, <name>.<target>.cpp, .sim.ts), vendored .c sources compile into a separate static lib (docs/plugins.md “plugin.json”, sources/pkg/libs); availability per target (Z5003). [verified] That is exactly the shape a vendored tree-sitter needs.
• Engines: the same app should run native / Zinc VM / QuickJS, with sim on node; “full UI pending” for VM and QuickJS (docs/engines.md). Any editor core in lib/std written in Zinc TS inherits all engines; a native-only core does not. [verified/inferred]
• Testing: deterministic headless replay (virtual clock, recorded HalInput tapes with keys/text/pointer, ZINC_RECORD/ZINC_REPLAY, docs/guide/06-testing.md:103-132), .out conformance per resolution and number profile, pixel tests (zinc test --pixels), test hooks (ui.pointerAt, typed text injection at ui.ts:2323). Tapes do not carry IME composition (no such HAL field) or pen samples. [verified]

1.6 The compiler frontend (for section 6)

• compiler/src/frontend.ts:128 loadProgram(entry, extra, virtual) builds a real ts.Program with a custom CompilerHost, virtual files supported (virtual map, lines 131-136) and module path mapping for zinc:* (STD_MODULES, line 32+, plus plugin modules). It exposes program, checker, sources, tsDiagnostics. The type system is TypeScript’s own checker (package.json: @typescript/typescript6 6.0.2 dependency, typescript 7.0.2 dev).
• Sema (compiler/src/sema.ts, 1244 lines) and HIR (hir.ts, 1028) are lowerings on top of the TS checker; their locations are per-node {file, line, column} (hir.ts:173 location()), not ranges. ZincError carries one Diag and guard() (cli.ts:225-230) aborts on the first Zinc error (Z-codes); zinc check prints [] on success (cli.ts:1102-1108). So today: TS diagnostics as a list, Zinc-specific diagnostics one at a time, no ranges (start only), no incremental program. [verified]

2. Lessons from real editors [web unless marked]

Text-shaping [bg]: CoreText (macOS), HarfBuzz+FreeType (Linux, portable, MIT-licensed HarfBuzz), Pango on top of HarfBuzz. AccessKit [web]: Rust with C bindings, adapters for Windows UIA, macOS NSAccessibility, Linux AT-SPI, Android; supports single and multi-line text edit controls. Only relevant later (see 4.6).

Tree-sitter [web]: MIT, runtime is pure C and dependency-free, designed to be embedded, incremental parsing (ts_parser_parse with the old edited tree), robust to syntax errors, “fast enough to parse on every keystroke”. Grammars are C (parser.c [+ scanner.c]) files generated per language [bg]; each grammar is 100 KB to several MB of C source; queries (highlights.scm) are s-expression files [bg].

LSP 3.17 [web]: JSON-RPC 2.0 with Content-Length header (bytes, UTF-8); initialize handshake gates all other requests; incremental textDocument/didChange; positions are UTF-16 code units by default and 3.17 adds positionEncoding negotiation (UTF-8, UTF-16 mandatory, UTF-32); semantic tokens, inlay hints, workspace folders as capabilities. Servers: typescript-language-server and pyright need --stdio, rust-analyzer must not get --stdio (exits with code 2), clangd takes no flag [web, one issue-tracker source; confirm before hard-coding].

3. Design for Zinc

3.1 Where does the editor live? Native vs Zinc TS

Recommendation [inferred]: write the editing core in Zinc TypeScript as a new std module (lib/std/editor/ exposing zinc:editor), not in C++.

• Zinc compiles to C++ AOT, so on the native engine there is no boundary and the code is compiled; VM and QuickJS engines run the same source. A C++ core would fork the engines (VS Code’s lesson on boundary cost applies to the VM and QuickJS engines) and would need .sim.ts twins for the node sim (ADR 0010 module rule, docs/plugins.md).
• Native is needed only where Zinc cannot: tree-sitter (vendored C), text shaping (later), process/socket I/O (already there), OS IME/clipboard (already in HAL, needs preedit fields).
• Performance risk: PERF.md says Zinc is ~13x QuickJS geomean but string/Map-heavy kernels benefit least (2.1x on strings, docs/reports/PERF.md:101-119). The core therefore must not be string-slice based: use typed arrays/chunks and integer offsets, never concatenate the document.

The existing <TextArea> stays as the small-form field. The new component is a distinct node kind or a canvas-backed widget. Two options:

• (A) New engine node EDITOR painted by new paintEditor in ui.ts, reusing scroll physics, focus, key routing, IME hook and marks painting. Pro: input/IME/scroll/focus for free. Con: ui.ts is already 2843 lines.
• (B) A widget drawn with gfx inside a <Canvas onDraw> plus key/pointer handlers in a std module. Pro: isolated, no ui.ts growth. Con: must re-implement focus/IME/clipboard glue and scroll physics.

Recommend (A) with the model in lib/std/editor/* and only the painter/input glue in ui.ts (or a sibling lib/std/ui-editor.ts imported by ui.ts). [inferred]

3.2 Data model: piece table vs rope

Choose a B-tree rope with summaries (Zed/Ropey style), not a plain piece table [inferred, informed by 2 above]:

• Leaves ~1 KiB UTF-8 chunks; node summary = {bytes, utf16, lines, maxLineUtf16?}. Conversions offset <-> (line, col) <-> utf16 are O(log n). This one structure serves editor coordinates, LSP UTF-16 positions, and tree-sitter byte offsets (tree-sitter wants byte offset + (row, column-in-bytes) in TSInputEdit).
• Snapshots are cheap (persistent nodes): tree-sitter reparse, LSP didChange diffing, search and highlighting can run on a snapshot, and undo restores by structure sharing (no more 100 full-string snapshots).
• Piece table (VS Code) is comparable for editing but its line/offset queries need the RB-tree anyway; the rope gives the same complexity with simpler snapshots. Gap buffer is best for a single caret and worst for multi-cursor and snapshots, so rejected.
• Since Zinc strings are UTF-8 with O(offset) non-ASCII indexing (docs/ui.md:66), the rope must operate on bytes with explicit counters and never call charCodeAt on a big string. Needs byte-level string API in zinc (check zinc:web/string ABI; an Uint8Array chunk with a utf8 decoder is fine). [inferred]
• ~1500 lines of Zinc; 2-3 ew including property/fuzz tests against a naive string model (fuzz infra exists: tests/fuzz).

3.3 Selection model, transactions, undo

Copy CodeMirror 6 + Helix [web]:

• Range {anchor, head, goalColumn}; Selection = sorted, non-overlapping array + primary index; normalize merges overlapping ranges (same as CM6 and Kakoune). All commands are (state, range) -> change, applied to every range. [inferred]
• ChangeSet = sequence of retain/insert/delete over the old document, composable, invertible, and able to map positions (selections, marks, diagnostics, LSP ranges, tree-sitter edits). One Transaction = ChangeSet + new selection
  • metadata (user event, “typing” coalescing key, addToHistory).
• Undo: history tree (Vim/Helix style) rather than linear stacks. Store inverted ChangeSets + selection before/after; linear undo/redo is a walk; “earlier/later” and branch navigation are cheap extras. Group by time (~500 ms) and event kind like CM6. A tree costs little more than two stacks.
• Marks/decorations: RangeSet of anchored ranges mapped through ChangeSets (extmark-like). The current setMarks(h, flat i32[]) is replaced by setDecorations(layer, rangeSet), layers for search, diagnostics, brackets, semantic tokens, LSP document highlights, inline hints.
• Code folding = a decoration kind that hides line ranges (fold ranges from tree-sitter folds.scm or indentation); handled in the layout layer (3.4). Bracket matching = tree-sitter node pairs when a tree exists, else the current scan. Comment toggle, auto-indent, snippets ($1, ${1:placeholder}, mirrored tabstops as multi-selection sets), and find/replace are all transaction producers.
• Find/replace with regex: Zinc has no regex engine documented. Check zinc:web (docs/guide/09-web-apis.md) before choosing; otherwise embed a small non-backtracking regex (RE2-style Pike VM ~600 lines) run chunkwise over the rope, or vendor tiny-regex/SLRE-class C (needs UTF-8 and lookaround limits documented). [inferred; regex support not verified in this repo]

3.4 View model, layout and rendering

Today ensureRows re-lays out everything on any change (ui.ts:1153). Replace with:

• A height map / line-layout cache keyed by line index and mapped through ChangeSets: wrapped-row count per line, x-advance cache per line (or per chunk), invalidated only for touched lines and on width change. Row lookup by binary search over a Fenwick/sum tree instead of rowOf linear scan (ui.ts:1185). Folded ranges are 0-height entries.
• Display map pipeline (Zed): buffer coords -> fold map -> tab map -> wrap map -> inlay map -> display rows. Inlay hints and folds are just transforms in this chain. Start with fold + wrap only. [web/inferred]
• Only visible rows are shaped and painted (as now). Keep the per-frame slicing but slice rope leaves, not a string.
• Glyph cost: textWidth per character is the bottleneck for hit testing. Add a per-font monospace fast path (advance = constant; detect from hmtx) so column<->x is arithmetic; keep the measured path for proportional fonts. This alone covers >95% of code editing use. [inferred]
• Minimap: keep the lazy canvas but feed it line token summaries from the tree-sitter highlight cache instead of re-lexing.
• Split panes: view state (scroll, selection set, folds) is per view, document state (rope, history, tree, diagnostics) is per buffer; two views on one buffer share one history. Tabs/panes are plain Zinc UI (already demonstrated by zed-editor Tabs.tsx, workspace.ts), so a pane tree component is app-level (1-2 ew), not engine work.
• Minimal display of large files: rope + line index means opening 100 MB is a read into chunks plus a newline scan; render never touches non-visible text. Memory ~1x file size. Mark read-only huge-file mode (no tree-sitter above a size limit, e.g. 5 MB, as Helix/Zed do [bg]).

3.5 IME/composition, bidi, shaping, clipboard, a11y

• IME: needs HAL work. SDL3 delivers SDL_EVENT_TEXT_EDITING (preedit text + selection start/length) [bg]; add HalInput.preedit and hal_text_input rect updates per caret move (already partly there, hal_sdl.cpp:415). The editor holds a “composition range” not committed to the rope, drawn underlined; commit replaces it via one transaction. On the wasm HAL: compositionstart/update/end on a hidden textarea [bg]. Tapes must gain a preedit field to stay replayable (docs/guide/06-testing.md:132 lists gaps). ~1.5-2 ew.
• Shaping and bidi: the rasterizer has no GSUB/GPOS/bidi (see 1.3). Options ranked: (1) monospace Latin/code editing only, document the limit (MVP); (2) add kerning-free fallback fonts + grapheme clustering + double-width CJK (wcwidth-style tables, ~1 ew); (3) vendor HarfBuzz (MIT, C++, ~1.5 MB source; add to a zinc:text plugin, sources) plus a UBA implementation (fribidi is LGPL, so prefer ICU-less small implementation or SheenBidi, Apache-2.0 [bg]) for real bidi/Indic/Arabic; needs the rasterizer to draw by glyph id instead of codepoint (ttf.cpp:236 slot(cp)). 6-10 ew and is the biggest single unknown; do not put it on the critical path for a code editor.
• Clipboard: text works; add multi-cursor clipboard (one entry per cursor pasted round-robin, VS Code/Helix behaviour), line-wise cut/copy when selection empty, and paste-and-indent. Rich types unnecessary. 0.5 ew.
• Accessibility: AccessKit C API [web] would give AT-SPI/UIA/NSAccessibility; needs a semantic tree from ui.ts nodes, which does not exist. Post-1.0 milestone; state as a known gap.

4. Syntax highlighting

4.1 Recommendation: tree-sitter as a vendored native plugin zinc:treesitter, lexer fallback stays

• plugins/treesitter/plugin.json kind: module, sources: ["vendor/lib/src/lib.c", ...] (tree-sitter’s runtime compiles as one C file, lib/src/lib.c [bg]) plus per-language grammar folders compiled only if imported/configured (plugins.treesitter.languages: ["typescript","json","css","cpp","rust","markdown"] via plugin options, which C++ sees as ZP_TREESITTER_* defines, docs/plugins.md table). C sources go in the separate C static library (documented for .c).
• Native spec (native/treesitter.spec.ts + treesitter.<target>.cpp): createParser(lang), parse(handle, chunks), edit(handle, startByte, oldEndByte, newEndByte, points...), reparse(handle), query(handle, name, byteRange) returning a flat i32[] of [captureId, startByte, endByte] for a byte range (visible rows only) so the boundary is crossed once per frame; tree lifetime as an opaque resource (spec ABI supports resources, docs/engines.md).
• Fit with existing constraints: MIT license (compatible; add to docs/licenses.md); C only, no allocator surprises (tree-sitter lets you override ts_set_allocator; hook to zrt heap); no exceptions/RTTI issue since C. Excluded targets: esp32/ps1/ps2 (like zinc:socket requires), sim via web-tree-sitter (wasm) or node tree-sitter in a .sim.ts twin. [inferred]
• Highlighting pipeline: on transaction, translate ChangeSet to TSInputEdits, ts_tree_edit, schedule reparse (timer, ~1-5 ms budgets; parse with TSParseOptions progress callback for cancellation [bg]), then run the highlight query over the visible byte range plus margin; cache capture runs per line, invalidate through ts_tree_get_changed_ranges. Injections (markdown fences, TSX-in-HTML, CSS-in-JS) as in Zed SyntaxMap [web]; do in a second pass.
• Same tree drives: fold ranges, bracket matching, indent (indents.scm), “select parent node”, comment markers by language config, sticky scroll, outline.
• Grammar distribution: each parser.c is large; committing generated parsers for ~8 languages adds tens of MB to the repo [bg, estimate]; alternative: build them lazily on zinc plugins install into a cache. Zinc grammar itself: TypeScript grammar covers .ts/.tsx (Zinc source is TypeScript), so no new grammar for the Zinc language. [inferred]

4.2 Alternatives

Effort: plugin + TS/JSON/CSS/C++/Rust/Markdown highlighting, folds, brackets: 4-6 ew. Injections + indent queries: +2 ew.

5. LSP client

5.1 Placement: zinc:lsp as pure Zinc TS on top of zinc:process and zinc:socket

No new native code is required for stdio transport [verified from 1.5], only hardening (5.5). Layers:

1. Transport: StdioTransport(cmd, args, {cwd, env}) using proc.spawn + onData; TcpTransport(host, port) using zinc:socket connect. Interface {send(bytes), onBytes(cb), close()}.
2. Framing: parse Content-Length: N\r\n\r\n + N bytes. onData delivers chunks of UTF-8 without splitting sequences (docs/plugins/process.md:30) but as strings, so length must be computed in UTF-8 bytes (String.bytes() exists in the runtime, gfx.cpp:796 uses s.bytes(); expose it or add a byte-level API). Robust rule: keep an accumulation buffer of bytes, never trust string.length. Add p.onBytes(cb: (Uint8Array)=>void) to zinc:process if strings prove lossy.
3. JSON-RPC: request ids, pending map id -> Promise, notifications, server-to-client requests (workspace/configuration, client/registerCapability, window/workDoneProgress/create, workspace/applyEdit) with mandatory replies, $/cancelRequest, $/progress. Requires a JSON parser/serializer: JSON.parse/stringify availability in Zinc for dynamic shapes must be confirmed (docs/guide/09-web-apis.md; DYN types exist in hir.ts:30). [inferred; not verified]
4. Session: capability negotiation, initialize/initialized, shutdown/exit, restart with backoff, one server per (language, workspace root), multi-root via workspaceFolders and didChangeWorkspaceFolders.
5. Document sync: ChangeSet -> contentChanges incremental ranges (needs the rope’s utf16 line/col summaries), version counters, debounce for diagnostics-relevant flushes; request positionEncoding: utf-8 when the server supports it (clangd, rust-analyzer do [bg]) and fall back to utf-16.
6. Feature adapters (each maps a response into editor concepts):

5.2 Spawning servers

• typescript-language-server: npx typescript-language-server --stdio (or a resolved node_modules/.bin), TS needs a tsserver.path (initializationOptions); clangd: clangd (uses compile_commands.json; Zinc’s build dir may need to emit one for Zinc C++ output), rust-analyzer: rust-analyzer with no args; pyright pyright-langserver --stdio [web].
• Server table in a JSON config (languages.json): {id, extensions, command, args, rootMarkers, initializationOptions}.
• Environment: the app runs sandbox-free on host targets (docs/guide/08-security.md threat model: process plugin is program-trusted). Editor should spawn servers with cwd = workspace root, stderr routed to an output panel.
• Requirement: PATH resolution of node/npx for GUI-launched apps on macOS, where PATH is minimal; add an explicit login-shell PATH probe (sh -lc 'echo $PATH'). [bg/inferred]

5.3 Async I/O integration with the event loop

Events are delivered from the loop by zrt::Poller (docs/plugins/process.md; docs/plugins.md “Core services”) so LSP callbacks run on the UI thread between frames. Rules: parse large JSON responses (completion lists, semantic tokens can be MBs) in slices or on a worker if Zinc offers threads (not documented; else chunk with queueMicrotask/timers so a 5 MB reply does not drop frames); cap message size; never block the frame on a response, use debounced requests with cancellation (generation counters, as zed-editor/src/app/tools.ts already does for check). [verified pattern]

5.4 ABI additions and hardening needed (list)

1. zinc:process: non-blocking write with a queue and a onDrain/writable event (today it blocks at 64 KiB, docs/plugins/process.md:54); LSP didOpen of a large file can exceed 64 KiB while the server is busy (deadlock with a server that writes while we write, a classic).
2. Binary-safe I/O: onBytes/writeBytes (or expose UTF-8 byte length and byte slicing).
3. Optional PTY for the terminal panel: spawnPty(cmd, args, {cols, rows}) with openpty/forkpty, resize (TIOCSWINSZ), plus a VT100/xterm parser (the panel today only strips SGR, tools.ts:parseAnsi). 3-4 ew (parser is the bulk; no PTY code found: grep -rn "pty|forkpty|openpty" runtime plugins empty).
4. Process exit/kill(SIGTERM) semantics and process group kill (language servers spawn children; kill must reach them).
5. A file watcher (FSEvents/inotify) for didChangeWatchedFiles, and a zinc:fs recursive glob/ignore-aware walk for workspace symbols. [inferred; unverified whether zinc:fs has these]
6. Environment/PATH inheritance as above.
7. String.bytes()/byteAt/sliceBytes in the string API used by the rope and by framing.

5.5 Effort

MVP client (stdio, framing, sync, diagnostics, hover, definition, completion popup, formatting): 4-5 ew; the rest (references, rename, code actions, signature help, semantic tokens, inlay hints, folding/selection ranges, workspace folders, progress UI): +5-6 ew; ABI hardening: +1.5 ew. Test with a scripted fake server (Zinc program that speaks LSP on stdio) plus a real typescript-language-server in CI-optional tests.

6. A Zinc language server (zinc lsp)

6.1 Feasibility

Because Zinc source is TypeScript and Zinc’s semantic model is the TS checker plus Zinc lowering (1.6), the cheapest correct design is layered [inferred]:

1. Base layer = the TypeScript language service (not tsserver as a process): construct ts.createLanguageService with a LanguageServiceHost reusing the options and module resolution from frontend.ts (STD_MODULES, plugin paths, PLATFORM_FILE virtual file, webGlobals, platformVariant, frontend.ts:128-208). That yields hover with inferred types, definitions (including through zinc:* modules to lib/std/*.ts and plugins/*/index.ts), references, rename, completion, signature help, quick info, organize imports, semantic classification, inlay hints, for free and incrementally. This is more capable than building a checker from sema.ts; the frontend exports only the whole-program loadProgram today, so refactor it to expose the compiler options/host builder (small, ~0.5 ew).
2. Zinc overlay diagnostics: run Sema (Z-codes: unsupported types/ops for the selected profile, integer/float profile warnings, Z5003/Z5004/Z5005 plugin/target availability) on demand for the entry graph and merge with TS diagnostics. Needs: (a) Sema collecting all ZincErrors instead of throwing on the first (guard, cli.ts:225; HIR already converts errors inside statements/expressions to opaque nodes with the code text, hir.ts:177,329, so partial recovery exists) (b) diagnostics with ranges (SourceLocation has only start; hir.location() uses getStart; add end). (c) Per-target profile choice: zinc.json targets / initializationOptions target, profile, noFloat.
3. Zinc-specific intelligence: hover shows the lowered type (numeric kind: f64/i32/fx12, from NumKind sema.ts/hir.ts:6, infer.ts zinc infer --write proposes numeric annotations); code actions “apply inferred numeric types”; go-to-definition through declaration identities (used by the VM linker, docs/engines.md “Declaration identities”) for re-exports and aliases; virtual JSX/CSS class diagnostics (css.ts, styles.ts, ui-style.ts: unknown utility classes such as w-[300]), plugin-aware completion of zinc:* module imports, zinc.json schema validation.
4. Transport: implement in Node (the compiler is Node TS: compiler/bin/zinc.mjs), using vscode-languageserver (MIT) or a 200-line hand-rolled JSON-RPC over stdio; entry zinc lsp --stdio added next to cmd === 'ui' in cli.ts:1073. Incremental document sync with the language service host getScriptSnapshot on unsaved buffers (virtual files).
5. Performance: TS language service holds one program per project; Zinc’s std ui.ts is 2843 lines and the kit is large, so the first check is seconds, later ones incremental. @typescript/typescript6 is what the compiler uses (package.json); the dev dependency is TS 7 (native port). Pick one version and keep the LS on the same one the compiler uses so hover and diagnostics agree with zinc check. [verified from package.json / inferred for the risk]

Alternative: forward to typescript-language-server and add only the overlay (Z-code diagnostics + hover addendum) as a second server (LSP allows several servers per language; the editor merges). Simpler and immediately usable in the editor, but loses Zinc target awareness in module resolution. Suggested as step 0 of the LSP milestone: it proves the client with a real server while zinc lsp is written.

6.2 Effort

zinc lsp with TS language service base + target-aware diagnostics (first error only): 2-3 ew; collect-all Sema diagnostics with ranges: +2 ew; Zinc-specific hover/actions/CSS-class intelligence: +2 ew. Written in Node, works in VS Code and Zed too, which is a distribution win independent of the Zinc editor.

7. DAP and terminal

• Terminal panel: exists for output (Terminal.tsx, 47 lines). A real terminal needs PTY + VT parser + cell grid renderer (fixed-width cell canvas, scrollback ring, selection, bracketed paste, alt screen). 4-6 ew total. Recommend deferring behind LSP: run tasks still work with today’s panel.
• DAP [bg]: JSON-RPC-like protocol with the same Content-Length framing, so the LSP transport/framing layer is reused as is; adapters (codelldb, lldb-dap, node --inspect bridges). UI needs breakpoints gutter (a MARK_GUTTER kind exists, ui.ts:1558), variables/callstack panels. Zinc VM/QuickJS engines have no debug protocol; the native engine could be debugged through lldb/dap. 4-6 ew after the LSP is stable; low priority. Do not design it now beyond keeping the transport generic.

8. Test strategy

Assets that already exist [verified]: headless deterministic replay with virtual clock, .out goldens per resolution/number profile, pixel tests, test hooks for pointer/keys/typed text, conformance for code_editor.tsx, fuzz directory, and the engines matrix (tests/engines/run.mjs) to check the same app on native/VM/QuickJS.

Add:

1. Model tests without UI: rope vs naive string differential fuzz (random edits, offsets, utf16 counts, non-ASCII), ChangeSet compose/invert/map properties, undo tree walk = original, multi-range command results (tests/editor/*.ts). Run on sim + native + VM to catch engine drift.
2. Scripted key tapes for behaviours: multi-cursor typing, paste round-robin, auto-indent, comment toggle, snippet tabstops, fold/unfold, find/replace, undo-redo across cursors; assert on getValue/selections dumps in .out.
3. Pixel tests for caret/selection/gutter/squiggle rendering at 1x and 2x (existing --pixels).
4. IME: extend HalInput with preedit so tapes can replay composition; until then unit-test the composition state machine.
5. LSP: a fake server (Zinc or node) with recorded transcripts (request/response fixtures) to verify framing, id correlation, cancellation, position mapping through concurrent edits; contract tests against real typescript-language-server opt-in; golden tests for zinc lsp responses (hover/definition/diagnostics JSON) run in zinc test.
6. Perf gates: extend ZINC_DEMO=scroll to a 100 MB file, 10k-line files, and multi-cursor (1000 cursors) typing; record in docs/reports next to existing engine JSON reports; budgets: keystroke <= 2 ms at 100k lines, open 100 MB <= 1 s, scroll >= display rate.
7. Tree-sitter: golden highlight dumps per language for fixtures; incremental vs full reparse equivalence fuzz.

9. Roadmap and estimates [inferred]

Total for a solid, LSP-capable code editor (M1-M5 + M6): about 32-44 ew, roughly 8-10 months for one engineer, 4-5 months for two after M1. Milestones M2 and M3 can run in parallel after M1; M4 needs M1’s utf16 position mapping; M5 is independent of the editor (Node only) and can start on day one as a standalone tool for VS Code/Zed, which de-risks the demand side.

Minimal “real editor” bar (my proposal)

Not a real editor until all of these hold: multiple cursors/selections and every command applies to all; undo tree with selection restore; open and scroll a 50 MB file without stalls; regex find/replace; auto-indent, comment toggle, bracket match/auto-close; incremental structural highlighting; at least one language server giving diagnostics, completion, hover and go-to-definition; keyboard-only operation; correct IME commit and composition display; unsaved-changes safety. Everything else (bidi shaping, DAP, PTY terminal, a11y tree, minimap) is v2.

10. Risks

1. Zinc string/UTF-8 cost model: any accidental charCodeAt on large strings is O(n) (docs/ui.md:66). Mitigation: byte-oriented rope API, lint rule/test that fails when the core imports string index helpers on documents.
2. Text shaping absence (ttf.cpp) limits i18n; monospace Latin/CJK-width is fine for code, but users editing Arabic/Hebrew comments will see wrong output. Document; plan M8.
3. Native plugin size and portability: grammar C sources are large; build times on rpi1; excluded targets need graceful errors (Z5003).
4. Engine parity: VM/QuickJS UI is “pending” (docs/engines.md), so the editor only targets the native engine + sim at first; running the core-model tests on all engines keeps the door open.
5. zinc:process write blocking can freeze the UI during large didOpen to a busy server; must be fixed before LSP ships.
6. LSP position encoding mismatches (UTF-16 vs bytes) are the number one source of bugs; keep utf16/byte/line summaries in the rope and fuzz conversions.
7. Scope creep in a ui.ts of 2.8k lines: keep the new editor in separate files (lib/std/editor/*) and a narrow glue API.
8. Zinc LSP depends on Sema recovery (first-error-only today) and on TS version alignment (@typescript/typescript6 vs TS 7).
9. Terminal/DAP are large, separable projects; do not let them block editing/LSP.
10. Unverified in this study: whether Zinc has a regex engine, JSON.parse into dynamic values with acceptable speed, threads/workers, an fs watcher, byte-level string APIs. Each needs a 1-day spike before M1/M4 estimates are firm.

Sources

Repo files (all under /Users/mowmow/Lab/zinc): lib/std/ui.ts, docs/ui.md, examples/zed-editor/README.md and src/**, tests/conformance/code_editor.tsx, runtime/ttf.cpp, runtime/gfx.cpp, targets/macos/hal_sdl.cpp, docs/plugins.md, docs/plugins/process.md, docs/plugins/socket.md, docs/engines.md, docs/guide/06-testing.md, docs/reports/PERF.md, docs/reports/gpu-renderer-design.md, compiler/src/{frontend,sema,hir,cli}.ts, package.json.

Web (fetched or searched 2026-09-30):

• Zed Decoded: rope and SumTree: https://zed.dev/blog/zed-decoded-rope-sumtree
• Zed architecture summaries: https://deepwiki.com/zed-industries/zed/4.3-buffer-architecture , https://deepwiki.com/zed-industries/zed/13.2-crdt-and-buffer-synchronization
• VS Code text buffer reimplementation (piece tree): https://code.visualstudio.com/blogs/2018/03/23/text-buffer-reimplementation
• CodeMirror 6 system guide: https://codemirror.net/docs/guide/
• xi-editor retrospective: https://raphlinus.github.io/xi/2020/06/27/xi-retrospective.html
• Xi rope science / CRDT: https://xi-editor.io/docs/rope_science_08.html
• Helix architecture: https://github.com/helix-editor/helix/blob/master/docs/architecture.md ; tree-house: https://github.com/helix-editor/tree-house
• Kakoune/Helix selection model: https://phaazon.net/blog/more-hindsight-vim-helix-kakoune
• Lapce architecture: https://docs.lapce.dev/development/architecture
• Tree-sitter: https://github.com/tree-sitter/tree-sitter
• LSP 3.17 specification: https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/
• Server flags (rust-analyzer vs —stdio): https://github.com/hyperion2144/dsh-hashline-edittool/issues/135 (single issue source, confirm)
• AccessKit: https://accesskit.dev/how-it-works/ , https://crates.io/crates/accesskit

Should the desktop IDE (“Studio”) itself be a Zinc app? Coherence, gaps, plan

Date 2026-09-30. Read-only study of /Users/mowmow/Lab/zinc (dirty tree, nothing modified). Follows README.md and docker-free-studio.md, which proposed a Tauri 2 shell around the Node CLI. Legend: [V] verified by reading the repo (file:line), [W] web / general knowledge of a third-party API, [I] my inference or estimate. Effort in person-weeks (pw), one engineer who knows the codebase, unvalidated. Parallel studies cover the editor component and JS engines; this report only takes their questions as interfaces.

0. Verdict

Yes, it is coherent, and it is already half-done: build the IDE as a Zinc app (dogfooding), and drop Tauri. [I, based on the [V] findings below]

1. Two Zinc apps of this exact shape exist today: apps/studio (2.9k LOC, zinc:ui + zinc:process + zinc:remote + zinc:webview, drives compiler/bin/zinc.mjs, streams build logs, previews a running app through the remote display, deploys over ssh; docs/studio.md:6-7, apps/studio/src/runner.ts:1-8) and examples/zed-editor (2.6k LOC: project tree, tabs, textarea-based editor with highlighting, fuzzy finder, command palette, zinc check --json diagnostics, terminal panel via zinc:process; examples/zed-editor/README.md:1-8). [V]
2. What the Tauri plan would give and Zinc does not is mostly the web stack (Monaco, an HTML docs renderer, WebSerial in the browser). What Zinc gives and Tauri does not: one runtime and one language for app, examples and IDE, ~1 MB-class binaries (hello 53-70 KiB, docs/reports/qt-comparison.md:34), pixel-identical rendering with golden tests, zinc dev hot reload of the IDE itself (docs/dev-mode.md:8-9), and the strongest possible proof of the platform. [V]
3. But not for all phases and not for the browser tier. Zinc has no Windows target, no accessibility, no IME preedit, no PTY, no serial, single window only. The honest position: Studio v0 as a Zinc app now (macOS + Linux), Windows/a11y are the gating risks for a wide “Arduino IDE replacement” audience. A web/PWA tier (browser mode, Tier A/B from the previous report) is a separate product surface that Zinc-native cannot serve, except by shipping the same UI as a Zinc wasm target (targets/wasm/hal_web.cpp, exists [V]) which is a research item.
4. Self-hosting the compiler inside the app (v2) is not worth it as a goal by itself. Keep the compiler as a child process (Node today; a bundled runtime, or later a native TS 7 tsgo-style binary) behind JSON-RPC. Running the TS 6 JS compiler inside QuickJS is possible in principle but is 10-30x slower and needs a virtual host; do it only if “no Node install” becomes a hard requirement and only after the QuickJS bytecode/AOT work. [I]
5. Name: ZincStudio is the box editor (docs/studio.md:1, apps/studio/README.md:1). Recommendation: keep apps/studio as “ZincStudio Flow” (or fold it in as a view) and call the IDE something else (“Zinc IDE”, “Zinc Bench”…). [I]

When: v0 in 8-10 pw from today because both codebases exist; the platform work that makes it good (multi-window, dialogs, PTY, serial, a11y, Windows) is 30-55 pw and is worth doing anyway for every desktop Zinc app.

1. What a Zinc app can do on the desktop today (verified inventory)

Existing Studio-like code (assets to reuse, not just references):

• apps/studio/src/runner.ts already calls node zinc.mjs plugins, build, run, deploy through zinc:process and streams logs with levels (ZINC_LOG_FORMAT=json). src/devices.ts does zinc:remote discovery + ssh device list. docs.ts + zinc:webview renders docs. [V]
• examples/zed-editor/src/app/tools.ts (159 lines) does zinc check --json diagnostics and the zinc run terminal. [V]
• examples/hero is the UI-kit showcase (10 screens, router, prefs, commands, overlays) proving the kit scales to app-size UI; docs/ui-kit.md lists Card, Dialog, Tabs, Switch, Slider, Progress, Alert… [V]

2. Comparison with alternatives

Verdict of the comparison [I]: Zinc loses on the boring OS-integration checklist (a11y, IME, menus, multi-window, Windows, terminal) and on editor depth; it wins on size, determinism, and coherence. Zed/GPUI and Lapce/Floem are the closest philosophy (GPU-drawn native editor) and both had to build the same missing pieces; that is the price list for the gap table below.

Dogfooding buys: one runtime and one language (any Studio feature is a reusable kit component for users), tiny binary and instant startup (3.8 ms hello), uniform pixels across mac/linux (goldens, replay tapes catch IDE regressions), zinc dev hot reload of the IDE, and every platform bug the IDE hits gets fixed for every app. Studio is the best possible “real app” for the never-done profiling step (README.md caveat 2: “profile a real Zinc UI app”). Dogfooding costs: a11y (legal risk in EU for a product, qt-comparison.md:85), IME preedit and non-Latin text (Chinese/Japanese comments in source), no native menu bar, no Windows (the Arduino audience is heavily Windows and Chromebook), self-built terminal and richer editor, no webview outside macOS (docs/markdown), and a single-window HAL.

2.1 Hybrid: Zinc UI + Node CLI as engine, vs compiler inside the Zinc JS engine

Node-only surface of the compiler (compiler/src, 10,273 lines, 27 files): [V]

• node:fs + node:path imports in abi, capabilities, emit-cpp, frontend, jsx, plugins, resources, emit-js, native, tools, cli, engines (grep -c "from 'node:'"); node:zlib in resources.ts:6; node:url in frontend.ts:6; hir, sema, infer, emit-bc import only node:path (polyfillable). [V]
• Process side effects concentrated in cli.ts (107 process./readFileSync… hits), tools.ts (28, includes spawnSync('codesign'), tools.ts:197), engines.ts (29), emit-js.ts (11), resources.ts (7): this is the driver layer (cmake, docker, esptool, codesign), not the compiler core. [V]
• frontend.ts:133-150 builds a ts.createCompilerHost over ts.sys and already has a virtual file map (:145); ZINC_ROOT via import.meta.url (:14). emit-bc.ts returns bytes; emit-cpp.ts returns strings. [V, from prior report; unchanged]
• TS 6 is the @typescript/typescript6 JS package (node_modules/@typescript/typescript6/lib/typescript.js is a shim require("@typescript/old")); the dev dependency typescript@7.0.2 is the native (Go) port and frontend.ts:1-2 says a switch to the TS 7.1 API touches that file only. [V]

So the compiler core is portable JS (frontend/jsx/sema/hir/infer/emit-*) behind ~10 file-touching functions; a Node-free host needs: a virtual FS (embed lib/, plugins index), zlib (only resources.ts, font/image baking), and replacing process. But three showstoppers for “run it in the Zinc app’s own QuickJS”: (a) it is not Zinc-subset TS (it uses the full TS compiler API, regexes, dynamic objects) so Zinc cannot AOT-compile it; it must run on a JS engine; (b) the TS JS library is ~10 MB of JS and the compile of a UI app takes ~400 ms warm in V8 (docs/dev-mode.md:47); the prior report measured QuickJS about 14-30x slower than V8 on Three.js’s JS-side work (README.md conclusion 4) so a UI app compile would be ~6-12 s, plus a multi-hundred-ms cold load unless the bytecode is precompiled (the runner still re-parses source at each start, README.md conclusion 2) [I]; (c) zinc:script is a sandbox with a 16 MiB default memory limit, no files, no timers (docs/plugins/script.md:5-8,50), so the host would have to expose a whole file API and raise limits. Then C++/CMake/docker/esptool still have to be spawned anyway, so Node is not eliminated from any native build path: it only disappears from the ZBC4/sim path.

Recommendation: A then B; C only as a by-product of the browser port. [I]

2.2 Bootstrap / self-hosting story

Studio is built by the Zinc compiler (zinc build apps/ide) and drives the same compiler as a child process: this is normal dogfooding, not self-hosting. True self-hosting (the compiler compiled by itself) is out of scope: the compiler needs the full TS API and Node. What is real: (1) a released Studio bundles the compiler + runtime sources + Node/engine, and builds user apps by spawning it; (2) Studio can rebuild itself with zinc dev (edit Studio in Studio, hot reload keeps the window: docs/dev-mode.md:31-40); (3) CI builds Studio with a pinned previous Zinc release so a compiler regression cannot brick the release pipeline [I]. Chicken-and-egg risk: a compiler bug that breaks Studio’s own build also blocks the tool used to fix it; mitigation is that the CLI stays usable without Studio (it always is) and Studio is built by the pinned release. [I]

3. Gap list (ranked)

Ranked by “blocks a credible v1 IDE” first, then by reuse value for all Zinc apps. Effort: pw. Numbers are [I]; SDL3 API availability [W] from general knowledge of SDL 3.2 (SDL_ShowOpenFileDialog, SDL_ShowOpenFolderDialog, SDL_ShowSaveFileDialog, SDL_CreateTray, SDL_EVENT_DROP_FILE, SDL_EVENT_TEXT_EDITING) that should be confirmed against the vendored SDL3 version before scheduling.

Windows (#7) and a11y (#8) are the two items that decide whether Studio can be the public default IDE; #1, #3, #4 and #11 decide whether it is a good IDE; #5 and #6 are polish.

4. Phased plan

Phases share code with the prior report’s toolchain manager (P1) and with the engine/AOT items; only Studio-specific work is counted.

Phase 0: spike, 1 pw. Fork examples/zed-editor + apps/studio panes into one app skeleton apps/ide (not in this report’s scope to create). Decide name. Run zinc dev on it. Measure with the real app: this is also the first profile of a real Zinc UI app under --engine quickjs (README.md order item 2).

Studio v0: “Zinc app that shells out to the Node CLI and shows the sim preview”, 8-10 pw (macOS + Linux).

• Project open/recent (dialog #1 fallback = in-app picker), tree, tabs, existing editor, diagnostics via zinc check --json (all reuse zed-editor).
• Build / Run / Stop / Deploy / Monitor panels via zinc:process (reuse apps/studio/src/runner.ts); structured progress (--json) added to the CLI (+1 pw).
• Preview: reuse the remote-display preview (zinc:remote, port 7711) for native, and Node sim for headless logs (apps/studio Robot view; note the sim has no renderer, docker-free-studio.md §1.3, so pixel preview = native build with remote display).
• Toolchain panel and zinc doctor UI on top of the future zinc toolchain (prior report P1).
• Flash/monitor by spawning zinc flash/monitor (no #4 yet); docs via Markdown component (#10).
• Packaging: macOS signed .app + DMG, Linux AppImage/deb; no Windows.
• Exit criterion: open an example, edit, build, preview, deploy to the Pi 3B+, flash an ESP32-S3 Matrix, all without leaving the app.

v1: editor + LSP + serial + PTY, +18-26 pw (parallel study on editor and JS engines feeds #2 and the engine choice).

• #2 editor depth, #3 LSP, #11 panes/dock, #12 settings/keymaps, #4 zinc:serial (+ esptool/espflash bundled), #5 terminal (PTY first, VT emulator second), #13 auto-update, #14 packaging with notarize CI.
• Board/device manager UI (USB VID/PID, ssh/mDNS #17), project templates from boards/*.json.
• Windows decision gate: start #7 in parallel (10-14 pw); Studio for Windows ships when the runtime port and packaging pass conformance.
• a11y macOS bridge (#8) in the same window if a public/EU release is planned.

v2: self-hosted compiler (optional), +8-12 pw. Only after the browser port of the compiler front end (prior report P6) exists: run frontend + emit-bc/emit-js in QuickJS inside Studio for the Node-free ZBC4/sim loop; native builds still spawn the toolchain. Also state-preserving hot reload (#19) and multi-window (#6) here. Precondition: QuickJS bytecode precompile and AOT work landed (quickjs-jit-aot.md), otherwise the compile latency is a UX regression. [I]

Total to a credible cross-platform IDE: roughly 40-60 pw including Windows and a11y; 8-10 pw to the macOS/Linux v0 that already reads as an Arduino-IDE-like tool. Compare with the prior Tauri plan (Studio v0 8-12 pw, docker-free-studio.md §7 P5): same v0 cost, but the Zinc plan’s v1 investments are reusable by every Zinc app while Tauri’s are not, and its size stays an order of magnitude smaller. [I]

Packaging, signing, updates per OS