lecodes-web-runtime 2.0.0

package/src/gen/wasm.ts

@@ -0,0 +1,156 @@
+// The wasm adapter of the generated web bridges — the runtime/native `js/args.h` of the web target
+// (scripts/gen-bridges.ts, the TS emitter). A generated method turns its JS arguments into what the
+// engine's exported C function takes (numbers as they are, strings and arrays copied into the heap,
+// a fetch buffer id into a heap copy of the bytes) and turns the result back (a heap array into a
+// Float32Array, a C string into a string, a struct into an object). The module is one of the
+// runtime/web/native profiles: every engine shares its heap, so this adapter is the only place that
+// knows about `HEAPF32`, `_malloc` and scratch memory.
+//
+// Scratch: every call runs inside `begin()` / `end(sp)` — a bump allocator over one heap block that
+// is reset when the call returns (an argument copy never outlives the call). A copy that does not
+// fit the block is `_malloc`ed and freed by `end`. Nothing here holds a heap view across a call that
+// can grow the heap: the `HEAP*` getters read the module's CURRENT views every time.
+
+/** The exports a creator-web profile provides (runtime/web/native/CMakeLists.txt). */
+export type WasmModule = {
+  HEAPU8: Uint8Array; HEAPU16: Uint16Array; HEAP32: Int32Array; HEAPU32: Uint32Array; HEAPF32: Float32Array; HEAPF64: Float64Array
+  _malloc(bytes: number): number
+  _free(ptr: number): void
+  UTF8ToString(ptr: number, maxBytes?: number): string
+  stringToUTF8(s: string, ptr: number, maxBytes: number): void
+  lengthBytesUTF8(s: string): number
+  [fn: `_${string}`]: (...args: any[]) => any
+} & Record<string, any>
+
+/** What the host lends the bridges: the fetch store behind the `bytes` alias of the contract. */
+export type WasmHost = {
+  getBuffer(systemId: number): ArrayBuffer | Uint8Array | null | undefined
+}
+
+const SCRATCH_BYTES = 256 * 1024
+
+export class Wasm {
+  readonly M: WasmModule
+  readonly host: WasmHost
+  private readonly base: number
+  private sp: number
+  private readonly heapAllocs: number[] = []
+  private readonly marks: number[] = []
+
+  constructor(module: WasmModule, host: WasmHost) {
+    this.M = module
+    this.host = host
+    this.base = module._malloc(SCRATCH_BYTES)
+    this.sp = this.base
+  }
+
+  // ---- scratch ----------------------------------------------------------------------------------
+  /** Open a call's scratch frame; `end(sp)` releases everything allocated after it. */
+  begin(): number { this.marks.push(this.heapAllocs.length); return this.sp }
+  end(sp: number): void {
+    this.sp = sp
+    const from = this.marks.pop() ?? 0
+    while (this.heapAllocs.length > from) this.M._free(this.heapAllocs.pop()!)
+  }
+  /** `bytes` of scratch, 8-aligned; falls back to the heap when the block is full. */
+  alloc(bytes: number): number {
+    const n = (Math.max(bytes, 1) + 7) & ~7
+    if (this.sp + n <= this.base + SCRATCH_BYTES) { const p = this.sp; this.sp += n; return p }
+    const p = this.M._malloc(n)
+    this.heapAllocs.push(p)
+    return p
+  }
+
+  // ---- arguments in ---------------------------------------------------------------------------------
+  /** A NUL-terminated UTF-8 copy of `s`. */
+  str(s: string): number {
+    const n = this.M.lengthBytesUTF8(s) + 1
+    const p = this.alloc(n)
+    this.M.stringToUTF8(s, p, n)
+    return p
+  }
+  /** A heap copy of a typed array (or a plain number list as floats); `elem` = bytes per element. */
+  array(values: ArrayLike<number>, elem: 1 | 2 | 4 | 8, float = false): number {
+    const length = values.length
+    const p = this.alloc(length * elem)
+    if (length === 0) return p
+    if (ArrayBuffer.isView(values)) {
+      const v = values as unknown as ArrayBufferView
+      this.M.HEAPU8.set(new Uint8Array(v.buffer, v.byteOffset, v.byteLength), p)
+    } else if (float) this.M.HEAPF32.set(values as ArrayLike<number>, p >> 2)
+    else if (elem === 4) this.M.HEAPU32.set(values as ArrayLike<number>, p >> 2)
+    else if (elem === 2) this.M.HEAPU16.set(values as ArrayLike<number>, p >> 1)
+    else this.M.HEAPU8.set(values as ArrayLike<number>, p)
+    return p
+  }
+  f32(values: ArrayLike<number>): number { return this.array(values, 4, true) }
+  u8(values: ArrayLike<number>): number { return this.array(values, 1) }
+  u16(values: ArrayLike<number>): number { return this.array(values, 2) }
+  u32(values: ArrayLike<number>): number { return this.array(values, 4) }
+  i32(values: ArrayLike<number>): number { return this.array(values, 4) }
+  /** The bytes behind a fetch buffer id, copied into the heap; null when the store has nothing. */
+  bytes(systemId: number): { ptr: number, size: number } | null {
+    const buf = this.host.getBuffer(systemId)
+    if (!buf) return null
+    const view = buf instanceof Uint8Array ? buf : new Uint8Array(buf)
+    if (view.byteLength === 0) return null
+    const p = this.alloc(view.byteLength)
+    this.M.HEAPU8.set(view, p)
+    return { ptr: p, size: view.byteLength }
+  }
+
+  // ---- results out ------------------------------------------------------------------------------------
+  /** Copy `n` heap elements at `ptr` into `into` (min(n, into.length) of them) — an engine-written array. */
+  readInto(ptr: number, n: number, into: ArrayBufferView, elem: 1 | 2 | 4): void {
+    const count = Math.min(n, into.byteLength / elem)
+    if (count <= 0) return
+    new Uint8Array(into.buffer, into.byteOffset, count * elem).set(this.M.HEAPU8.subarray(ptr, ptr + count * elem))
+  }
+  /** A NEW Float32Array of `n` floats read at `ptr`. */
+  newF32(ptr: number, n: number): Float32Array {
+    const out = new Float32Array(Math.max(n, 0))
+    if (n > 0) out.set(this.M.HEAPF32.subarray(ptr >> 2, (ptr >> 2) + n))
+    return out
+  }
+  /** A C string (borrowed pointer) as a JS string; 0 → "". */
+  cstr(ptr: number, maxBytes?: number): string { return ptr ? this.M.UTF8ToString(ptr, maxBytes) : "" }
+  /** A malloc'd C string the engine hands over: read, then freed. */
+  cstrFree(ptr: number): string {
+    if (!ptr) return ""
+    const s = this.M.UTF8ToString(ptr)
+    this.M._free(ptr)
+    return s
+  }
+
+  /** Zero `bytes` at `p` (a struct the engine fills, a @pack struct before its fields are written). */
+  zero(p: number, bytes: number): void { this.M.HEAPU8.fill(0, p, p + bytes) }
+  // ---- struct fields (the struct rule's generated readers / the @pack writers) ---------------------------
+  wrU8(p: number, v: number): void { this.M.HEAPU8[p] = v }
+  wrU16(p: number, v: number): void { this.M.HEAPU16[p >> 1] = v }
+  wrI32(p: number, v: number): void { this.M.HEAP32[p >> 2] = v }
+  wrU32(p: number, v: number): void { this.M.HEAPU32[p >> 2] = v }
+  wrF32(p: number, v: number): void { this.M.HEAPF32[p >> 2] = v }
+  wrF64(p: number, v: number): void { this.M.HEAPF64[p >> 3] = v }
+  wrI64(p: number, v: number): void { this.M.HEAPU32[p >> 2] = v >>> 0; this.M.HEAP32[(p >> 2) + 1] = Math.floor(v / 4294967296) }
+  wrU64(p: number, v: number): void { this.M.HEAPU32[p >> 2] = v >>> 0; this.M.HEAPU32[(p >> 2) + 1] = Math.floor(v / 4294967296) }
+  /** `n` structs of `size` bytes starting at `p`, each read by `read`. */
+  rdList<T>(p: number, n: number, size: number, read: (q: number) => T): T[] {
+    const out: T[] = []
+    for (let i = 0; i < n; i++) out.push(read(p + i * size))
+    return out
+  }
+  rdU8(p: number): number { return this.M.HEAPU8[p]! }
+  rdU16(p: number): number { return this.M.HEAPU16[p >> 1]! }
+  rdI32(p: number): number { return this.M.HEAP32[p >> 2]! }
+  rdU32(p: number): number { return this.M.HEAPU32[p >> 2]! }
+  rdF32(p: number): number { return this.M.HEAPF32[p >> 2]! }
+  rdF64(p: number): number { return this.M.HEAPF64[p >> 3]! }
+  rdI64(p: number): number { return this.M.HEAPU32[p >> 2]! + this.M.HEAP32[(p >> 2) + 1]! * 4294967296 }
+  rdU64(p: number): number { return this.M.HEAPU32[p >> 2]! + this.M.HEAPU32[(p >> 2) + 1]! * 4294967296 }
+  /** `n` numbers of `elem` bytes at `p` (a `float pt[3]` field). */
+  rdNumbers(p: number, n: number, rd: (q: number) => number, elem: number): number[] {
+    const out: number[] = []
+    for (let i = 0; i < n; i++) out.push(rd.call(this, p + i * elem))
+    return out
+  }
+}

package/src/jsb.ts

@@ -0,0 +1,494 @@
+// The JS side of runtime/native's wasm arm (runtime/native/src/js/wasm.cpp): the handle table its
+// `jsb::Value`s index, the imports the arm calls (property access, calls, strings, typed arrays,
+// throws), the wrappers that turn an installed handler table into JS functions, and the
+// FinalizationRegistry behind a class finalizer (the owned `Handle`). One instance per module,
+// installed as `Module.jsb` before `creatorWebInit`. Engine-agnostic: a browser or Bun.
+//
+// Values: a number is its IEEE bits (a NaN written canonical — the engine may canonicalize NaNs,
+// so a tagged word never travels as a JS number); anything else is a NaN with the sign bit set, a
+// TAG in bits 16–19 of the high word and the payload in the low word (wasm-support.h). Handles are
+// refcounted: the arm's `dup` / `free` are `dup` / `release` here; objects and functions are deduped
+// through a WeakMap so the arm's `same` holds; at zero references the slot is dropped and the value
+// is the engine's to collect.
+import type { WasmModule } from "./gen/wasm"
+
+const TAG_UNDEFINED = 1, TAG_NULL = 2, TAG_BOOL = 3, TAG_OBJECT = 4, TAG_FUNCTION = 5, TAG_STRING = 6, TAG_ARRAY = 7, TAG_OTHER = 8, TAG_EXCEPTION = 15
+const HI_BASE = 0xFFF00000
+const hiOf = (tag: number) => (HI_BASE | (tag << 16)) >>> 0
+const HI_UNDEFINED = hiOf(TAG_UNDEFINED), HI_NULL = hiOf(TAG_NULL), HI_BOOL = hiOf(TAG_BOOL), HI_EXCEPTION = hiOf(TAG_EXCEPTION)
+const tagOf = (hi: number) => ((hi & 0xFFF00000) >>> 0) === HI_BASE ? (hi >>> 16) & 0xF : 0
+
+/** A world the arm evaluates in: its global object (the bridges are installed on it) + evaluator. */
+export type JsbWorld = {
+  global: object
+  evaluate(code: string, filename: string): unknown
+}
+
+export type JsbOptions = {
+  /** The boot world (context 1). */
+  world: JsbWorld
+  /** A fresh world for `_creatorApp.run` (a vm context headless); absent = the boot world is reused. */
+  newWorld?: () => JsbWorld
+  /** The host tables the generated forwarders call (`Module.jsb.host.<table>.<slot>`). */
+  host: Record<string, unknown>
+}
+
+const ARG_STACK_BYTES = 64 * 1024
+
+/** A settle group: the heap callbacks of one host slot call, released together after the first settle. */
+type Group = { ptrs: number[], done: boolean }
+
+export class Jsb {
+  readonly M: WasmModule
+  readonly host: Record<string, unknown>
+  private out = 0
+  // the table: index → value (0 unused); refs[i] = references the arm holds; free = released slots
+  private table: unknown[] = [undefined]
+  private refs: number[] = [0]
+  private freeSlots: number[] = []
+  private objIndex = new WeakMap<object, number>()
+  private pending: unknown = undefined
+  private hasPending = false
+  private worlds = new Map<number, JsbWorld>()
+  private nextWorld = 2
+  private readonly newWorld?: () => JsbWorld
+  // the argument stack the wrappers write call arguments into (nested calls bump it)
+  private argBase = 0
+  private argSp = 0
+  private readonly scratch = new DataView(new ArrayBuffer(8))
+  private readonly classRegistry: FinalizationRegistry<{ ref: WeakRef<object>, cls: number, opaque: number }>
+  // Every live class instance as a WeakRef: `gc()` sweeps them so a finalizer lands SYNCHRONOUSLY
+  // inside the arm's runGC (QuickJS semantics: `ownedStats` = collect + drain + count), instead of
+  // on the FinalizationRegistry's later task — which still covers the objects a natural collection takes.
+  private readonly tracked = new Map<object, { ref: WeakRef<object>, cls: number, opaque: number }>()
+  private readonly fnRegistry: FinalizationRegistry<number>
+  private readonly opaques = new WeakMap<object, { cls: number, opaque: number }>()
+
+  constructor(M: WasmModule, options: JsbOptions) {
+    this.M = M
+    this.host = options.host
+    this.worlds.set(1, options.world)
+    this.newWorld = options.newWorld
+    this.argBase = M._malloc(ARG_STACK_BYTES)
+    this.argSp = this.argBase
+    this.classRegistry = new FinalizationRegistry((token) => {
+      if (!this.tracked.delete(token)) return   // swept already by gc()
+      this.M._jsbFinalize(token.cls, token.opaque)
+    })
+    this.fnRegistry = new FinalizationRegistry((k) => { this.M._jsbFunctionGone(k) })
+  }
+
+  // ---- the arm's hooks --------------------------------------------------------------------------
+  _init(out: number) { this.out = out }
+
+  // ---- encoding ---------------------------------------------------------------------------------
+  /** Encode `v` at heap address `p` (8 bytes). A handle takes ONE reference (the caller owns it);
+   *  the result is that handle's index, 0 for an immediate (a boolean's payload is NOT an index —
+   *  returning it once released slot 1 under an unrelated function). */
+  private write(p: number, v: unknown): number {
+    const M = this.M
+    if (typeof v === "number") {
+      M.HEAPF64[p >> 3] = v !== v ? NaN : v   // the engine writes a canonical NaN for NaN
+      return 0
+    }
+    let lo = 0, hi: number, idx = 0
+    if (v === undefined) hi = HI_UNDEFINED
+    else if (v === null) hi = HI_NULL
+    else if (typeof v === "boolean") { hi = HI_BOOL; lo = v ? 1 : 0 }
+    else {
+      lo = idx = this.alloc(v)
+      hi = hiOf(typeof v === "function" ? TAG_FUNCTION : typeof v === "string" ? TAG_STRING : Array.isArray(v) ? TAG_ARRAY : typeof v === "object" ? TAG_OBJECT : TAG_OTHER)
+    }
+    M.HEAPU32[p >> 2] = lo
+    M.HEAPU32[(p >> 2) + 1] = hi
+    return idx
+  }
+  private writeOut(v: unknown) { this.write(this.out, v) }
+  private writeOutException() { const M = this.M; M.HEAPU32[this.out >> 2] = 0; M.HEAPU32[(this.out >> 2) + 1] = HI_EXCEPTION }
+  /** Decode a (lo, hi) word pair; a handle's value is BORROWED (the reference stays). */
+  private decode(lo: number, hi: number): unknown {
+    const tag = tagOf(hi)
+    switch (tag) {
+      case 0: { this.scratch.setUint32(0, lo, true); this.scratch.setUint32(4, hi, true); return this.scratch.getFloat64(0, true) }
+      case TAG_UNDEFINED: case TAG_EXCEPTION: return undefined
+      case TAG_NULL: return null
+      case TAG_BOOL: return lo !== 0
+      default: return this.table[lo]
+    }
+  }
+  private readAt(p: number): unknown {
+    const M = this.M
+    return this.decode(M.HEAPU32[p >> 2], M.HEAPU32[(p >> 2) + 1])
+  }
+  /** A `value` parameter of a host slot (the generated forwarders): the JS value whose word is at
+   *  `p` — the app's own value, not a copy; undefined for a null address. */
+  valueAt(p: number): unknown { return p ? this.readAt(p) : undefined }
+  /** Read the result slot and TAKE the reference the arm handed over (an OWNED result). */
+  private takeOut(): { value: unknown, threw: boolean } {
+    const M = this.M
+    const lo = M.HEAPU32[this.out >> 2], hi = M.HEAPU32[(this.out >> 2) + 1]
+    const tag = tagOf(hi)
+    if (tag === TAG_EXCEPTION) return { value: undefined, threw: true }
+    const value = this.decode(lo, hi)
+    if (tag >= TAG_OBJECT && tag <= TAG_OTHER) this.release(lo)
+    return { value, threw: false }
+  }
+  private args(argc: number, argv: number): unknown[] {
+    const out: unknown[] = new Array(argc)
+    for (let i = 0; i < argc; i++) out[i] = this.readAt(argv + i * 8)
+    return out
+  }
+
+  // ---- the table ----------------------------------------------------------------------------------
+  private alloc(v: unknown): number {
+    const isObj = typeof v === "object" || typeof v === "function"
+    if (isObj) {
+      const hit = this.objIndex.get(v as object)
+      if (hit !== undefined) { this.refs[hit]++; return hit }
+    }
+    let i: number
+    if (this.freeSlots.length > 0) { i = this.freeSlots.pop()!; this.table[i] = v; this.refs[i] = 1 }
+    else { i = this.table.length; this.table.push(v); this.refs.push(1) }
+    if (isObj) this.objIndex.set(v as object, i)
+    return i
+  }
+  dup(idx: number) { if (idx > 0) this.refs[idx]++ }
+  release(idx: number) {
+    if (idx <= 0) return
+    if (this.refs[idx] <= 0) { console.warn(`[jsb] release of a dead handle ${idx} (${typeof this.table[idx]})`, new Error().stack?.split("\n").slice(2, 6).join("\n")); return }
+    if (--this.refs[idx] > 0) return
+    const v = this.table[idx]
+    if (typeof v === "object" || typeof v === "function") this.objIndex.delete(v as object)
+    this.table[idx] = undefined
+    this.freeSlots.push(idx)
+  }
+  /** Live handles (for tests). */
+  liveHandles(): number { return this.table.length - 1 - this.freeSlots.length }
+
+  // ---- worlds -------------------------------------------------------------------------------------
+  global(ctx: number) { this.writeOut(this.worlds.get(ctx)?.global ?? this.worlds.get(1)!.global) }
+  newContext(): number {
+    if (!this.newWorld) return 1
+    const id = this.nextWorld++
+    this.worlds.set(id, this.newWorld())
+    return id
+  }
+  freeContext(ctx: number) { if (ctx !== 1) this.worlds.delete(ctx) }
+  eval(ctx: number, code: string, filename: string) {
+    const w = this.worlds.get(ctx) ?? this.worlds.get(1)!
+    try { this.writeOut(w.evaluate(code, filename)) }
+    catch (e) { this.pending = e; this.hasPending = true; this.writeOutException() }
+  }
+
+  // ---- objects ----------------------------------------------------------------------------------
+  get(lo: number, hi: number, key: string) {
+    const o = this.decode(lo, hi) as any
+    if (o === undefined || o === null) { this.writeOut(undefined); return }
+    try { this.writeOut(o[key]) }
+    catch (e) { this.pending = e; this.hasPending = true; this.writeOutException() }
+  }
+  getIndex(lo: number, hi: number, i: number) {
+    const o = this.decode(lo, hi) as any
+    if (o === undefined || o === null) { this.writeOut(undefined); return }
+    try { this.writeOut(o[i]) }
+    catch (e) { this.pending = e; this.hasPending = true; this.writeOutException() }
+  }
+  has(lo: number, hi: number, key: string): boolean {
+    const o = this.decode(lo, hi)
+    return (typeof o === "object" || typeof o === "function") && o !== null && key in (o as object)
+  }
+  set(obj: number, key: string, lo: number, hi: number) {
+    const o = this.table[obj] as any
+    if (o === undefined || o === null) return
+    o[key] = this.decode(lo, hi)
+  }
+  setIndex(obj: number, i: number, lo: number, hi: number) {
+    const o = this.table[obj] as any
+    if (o === undefined || o === null) return
+    o[i] = this.decode(lo, hi)
+  }
+  keys(lo: number, hi: number, countOut: number): number {
+    const M = this.M
+    const o = this.decode(lo, hi)
+    const ks = (typeof o === "object" || typeof o === "function") && o !== null ? Object.keys(o as object) : []
+    let total = 1
+    for (const k of ks) total += M.lengthBytesUTF8(k) + 1
+    const p = M._malloc(total)
+    let off = p
+    for (const k of ks) { const n = M.lengthBytesUTF8(k) + 1; M.stringToUTF8(k, off, n); off += n }
+    M.HEAPU32[countOut >> 2] = ks.length
+    return p
+  }
+  newObject(classId: number, opaque: number) {
+    const o: Record<string, unknown> = {}
+    if (classId > 0) {
+      this.opaques.set(o, { cls: classId, opaque })
+      const token = { ref: new WeakRef(o), cls: classId, opaque }
+      this.tracked.set(token, token)
+      this.classRegistry.register(o, token, token)
+    }
+    this.writeOut(o)
+  }
+  newArray() { this.writeOut([]) }
+  opaqueOf(idx: number, classId: number): number {
+    const o = this.table[idx]
+    if (typeof o !== "object" || o === null) return 0
+    const e = this.opaques.get(o)
+    return e && e.cls === classId ? e.opaque : 0
+  }
+  json(lo: number, hi: number) {
+    let s: unknown
+    try { s = JSON.stringify(this.decode(lo, hi)) } catch { s = undefined }
+    this.writeOut(s)
+  }
+  parseJson(text: string) {
+    try { this.writeOut(JSON.parse(text)) }
+    catch (e) { this.pending = e; this.hasPending = true; this.writeOutException() }
+  }
+
+  // ---- strings + numbers ---------------------------------------------------------------------------
+  newString(s: string) { this.writeOut(s) }
+  str(lo: number, hi: number, lenOut: number): number {
+    const M = this.M
+    const v = this.decode(lo, hi)
+    let s: string
+    try { s = typeof v === "string" ? v : String(v) } catch { return 0 }   // a Symbol
+    const n = M.lengthBytesUTF8(s)
+    const p = M._malloc(n + 1)
+    M.stringToUTF8(s, p, n + 1)
+    M.HEAPU32[lenOut >> 2] = n
+    return p
+  }
+  logString(lo: number, hi: number): number {
+    const M = this.M
+    const v = this.decode(lo, hi)
+    let s: string
+    try { s = String(v) } catch { s = "" }
+    if (v instanceof Error && typeof v.stack === "string" && v.stack.length > 0) {
+      const stack = v.stack.startsWith(s) ? v.stack.slice(s.length).replace(/^\n/, "") : v.stack
+      if (stack.trim().length > 0) s += "\n" + stack.replace(/[\r\n]+$/, "")
+    }
+    const n = M.lengthBytesUTF8(s)
+    const p = M._malloc(n + 1)
+    M.stringToUTF8(s, p, n + 1)
+    return p
+  }
+  toNumber(idx: number): number { try { return Number(this.table[idx]) } catch { return NaN } }
+  truthy(idx: number): boolean { return !!this.table[idx] }
+
+  // ---- errors --------------------------------------------------------------------------------------
+  newError(message: string) { this.writeOut(new Error(message)) }
+  throwNew(kind: number, message: string) {
+    this.pending = kind === 1 ? new TypeError(message) : new Error(message)
+    this.hasPending = true
+  }
+  takeException() {
+    const e = this.hasPending ? this.pending : undefined
+    this.pending = undefined
+    this.hasPending = false
+    this.writeOut(e)
+  }
+  private throwPending(): never {
+    const e = this.hasPending ? this.pending : new Error("native handler failed")
+    this.pending = undefined
+    this.hasPending = false
+    throw e
+  }
+
+  // ---- calls ---------------------------------------------------------------------------------------
+  call(_ctx: number, fn: number, thisLo: number, thisHi: number, argc: number, argv: number) {
+    const f = this.table[fn] as (...a: unknown[]) => unknown
+    const thisv = this.decode(thisLo, thisHi)
+    const args = this.args(argc, argv)
+    try { this.writeOut(f.apply(thisv, args)) }
+    catch (e) { this.pending = e; this.hasPending = true; this.writeOutException() }
+  }
+  construct(ctor: number, argc: number, argv: number) {
+    const c = this.table[ctor] as new (...a: unknown[]) => unknown
+    const args = this.args(argc, argv)
+    try { this.writeOut(Reflect.construct(c, args)) }
+    catch (e) { this.pending = e; this.hasPending = true; this.writeOutException() }
+  }
+
+  // ---- typed arrays ---------------------------------------------------------------------------------
+  typedArray(kind: number, data: number, bytes: number) {
+    const src = this.M.HEAPU8.slice(data, data + bytes)   // a copy: the array owns its buffer
+    const buf = src.buffer as ArrayBuffer
+    const ctors = [null, Uint8Array, Uint16Array, Uint32Array, Int32Array, Float32Array, Float64Array, Int16Array, Int8Array, Uint8ClampedArray] as const
+    if (kind === 0) { this.writeOut(buf); return }
+    const C = ctors[kind]
+    this.writeOut(C ? new C(buf) : undefined)
+  }
+  /** mode 0: a typed array of `elem`-byte elements (size = elements); 1: any typed array's bytes;
+   *  2: an ArrayBuffer. A malloc'd copy the arm frees (a 1-byte block for an empty array), 0 when
+   *  the value is not such an array. */
+  arrayIn(idx: number, elem: number, mode: number, sizeOut: number): number {
+    const M = this.M
+    const v = this.table[idx]
+    let bytes: Uint8Array | null = null
+    let size = 0
+    if (mode === 2) {
+      if (!(v instanceof ArrayBuffer)) return 0
+      bytes = new Uint8Array(v); size = bytes.byteLength
+    } else {
+      if (!ArrayBuffer.isView(v) || v instanceof DataView) return 0
+      const ta = v as Uint8Array
+      const bpe = (ta as unknown as { BYTES_PER_ELEMENT: number }).BYTES_PER_ELEMENT
+      if (mode === 0 && bpe !== elem) return 0
+      bytes = new Uint8Array(ta.buffer, ta.byteOffset, ta.byteLength)
+      size = mode === 0 ? ta.length : ta.byteLength
+    }
+    const p = M._malloc(Math.max(bytes.byteLength, 1))
+    if (bytes.byteLength > 0) M.HEAPU8.set(bytes, p)
+    M.HEAPU32[sizeOut >> 2] = size
+    return p
+  }
+  arrayOut(idx: number, data: number, bytes: number) {
+    const v = this.table[idx]
+    let dst: Uint8Array
+    if (v instanceof ArrayBuffer) dst = new Uint8Array(v)
+    else if (ArrayBuffer.isView(v)) dst = new Uint8Array(v.buffer, v.byteOffset, v.byteLength)
+    else return
+    const n = Math.min(bytes, dst.byteLength)
+    if (n > 0) dst.set(this.M.HEAPU8.subarray(data, data + n))
+  }
+
+  // ---- handler tables + native functions --------------------------------------------------------
+  /** Run an installed handler with `args`: the arguments go onto the arg stack, the result comes
+   *  back through the slot (an exception re-thrown here). */
+  private invoke(call: (argc: number, argv: number) => void, args: unknown[]): unknown {
+    const argc = args.length
+    const sp = this.argSp
+    let argv = sp
+    let heapArgv = 0
+    if (sp + argc * 8 > this.argBase + ARG_STACK_BYTES) { heapArgv = this.M._malloc(Math.max(argc * 8, 8)); argv = heapArgv }
+    else this.argSp = sp + argc * 8
+    const owned: number[] = []
+    for (let i = 0; i < argc; i++) { const idx = this.write(argv + i * 8, args[i]); if (idx) owned.push(idx) }
+    let r: { value: unknown, threw: boolean }
+    try {
+      call(argc, argv)
+      r = this.takeOut()
+    } finally {
+      for (const idx of owned) this.release(idx)
+      this.argSp = sp
+      if (heapArgv) this.M._free(heapArgv)
+    }
+    if (r.threw) this.throwPending()
+    return r.value
+  }
+  defineMethod(ctx: number, obj: number, name: string, fnIndex: number, length: number, getter: number) {
+    const o = this.table[obj] as object
+    if (getter) {
+      Object.defineProperty(o, name, { configurable: true, enumerable: false, get: () => this.invoke(() => this.M._jsbInvokeGetter(fnIndex), []) })
+      return
+    }
+    const M = this.M
+    const f = (...args: unknown[]) => this.invoke((argc, argv) => M._jsbInvoke(ctx, fnIndex, argc, argv), args)
+    Object.defineProperty(f, "name", { value: name })
+    Object.defineProperty(f, "length", { value: length })
+    Object.defineProperty(o, name, { configurable: true, enumerable: false, writable: true, value: f })
+  }
+  makeFunction(ctx: number, k: number, name: string, length: number) {
+    const M = this.M
+    const f = (...args: unknown[]) => this.invoke((argc, argv) => M._jsbInvokeData(ctx, k, argc, argv), args)
+    if (name) Object.defineProperty(f, "name", { value: name })
+    Object.defineProperty(f, "length", { value: length })
+    this.fnRegistry.register(f, k)
+    this.writeOut(f)
+  }
+
+  // ---- host callbacks (the generated forwarders) -----------------------------------------------------
+  /** A JS function for a JSCallback heap pointer a host slot received: calling it posts the call
+   *  through the runtime's dispatch queue (the next tick runs it). `group` = the slot's settle
+   *  group (released after the first settle; a second settle is ignored); null = a long-lived
+   *  listener the runtime frees itself. A zero pointer (an optional callback the app left out) is
+   *  a no-op. */
+  callback(ptr: number, group: Group | null): (...args: unknown[]) => void {
+    if (!ptr) return () => {}
+    return (...args: unknown[]) => {
+      if (group) {
+        if (group.done) { console.warn("[jsb] a settled host callback was called again"); return }
+        group.done = true
+      }
+      const M = this.M
+      const argc = args.length
+      const n = group ? group.ptrs.length : 0
+      const p = M._malloc(Math.max(argc * 8 + n * 4, 8))
+      const owned: number[] = []
+      for (let i = 0; i < argc; i++) { const idx = this.write(p + i * 8, args[i]); if (idx) owned.push(idx) }
+      const gp = p + argc * 8
+      for (let i = 0; i < n; i++) M.HEAPU32[(gp >> 2) + i] = group!.ptrs[i]
+      M._jsbHostCall(ptr, argc, p, gp, n)
+      for (const idx of owned) this.release(idx)
+      M._free(p)
+    }
+  }
+  /** A native view's event, host → app (`channel.emit` of a view a TS host mounted): the payload
+   *  crosses as the value it is — the runtime retains it until its dispatch queue delivers the
+   *  event. No payload = the listener gets none. */
+  viewEvent(viewId: number, event: string, data?: unknown): void {
+    const M = this.M
+    const e = M.stringToNewUTF8(event)
+    if (data === undefined) { M._jsbViewEvent(viewId, e, 0); M._free(e); return }
+    const p = M._malloc(8)
+    const idx = this.write(p, data)
+    M._jsbViewEvent(viewId, e, p)
+    if (idx) this.release(idx)
+    M._free(p)
+    M._free(e)
+  }
+  /** A settle group for the callbacks of one slot call. */
+  group(...ptrs: number[]): Group { return { ptrs: ptrs.filter((x) => x !== 0), done: false } }
+  /** A `const char* const*` + count → strings (the generated forwarders' string[] parameters). */
+  strings(ptr: number, count: number): string[] {
+    const M = this.M
+    const out: string[] = new Array(count)
+    for (let i = 0; i < count; i++) { const p = M.HEAPU32[(ptr >> 2) + i]; out[i] = p ? M.UTF8ToString(p) : "" }
+    return out
+  }
+  /** A host's byte result → a malloc'd, NUL-terminated copy the runtime frees (0 for none); the
+   *  byte count goes to `outSize` when the slot has one. */
+  bytesOut(r: unknown, outSize: number): number {
+    const M = this.M
+    let bytes: Uint8Array | null = null
+    if (r instanceof Uint8Array) bytes = r
+    else if (r instanceof ArrayBuffer) bytes = new Uint8Array(r)
+    else if (ArrayBuffer.isView(r)) bytes = new Uint8Array(r.buffer, r.byteOffset, r.byteLength)
+    if (!bytes || bytes.byteLength === 0) { if (outSize) M.HEAPU32[outSize >> 2] = 0; return 0 }
+    const p = M._malloc(bytes.byteLength + 1)
+    M.HEAPU8.set(bytes, p)
+    M.HEAPU8[p + bytes.byteLength] = 0
+    if (outSize) M.HEAPU32[outSize >> 2] = bytes.byteLength
+    return p
+  }
+
+  gc() {
+    const g = (globalThis as { gc?: () => void }).gc
+    const bun = (globalThis as { Bun?: { gc?: (force: boolean) => void } }).Bun
+    // twice: the first full collection leaves what only became unreachable during it (the weak
+    // processing of the sweep below is one such source); the second takes it
+    for (let i = 0; i < 2; i++) {
+      if (bun?.gc) bun.gc(true)
+      else if (typeof g === "function") g()
+      else return
+      this.sweep()
+    }
+  }
+  /** Collected class instances finalize now, not on the registry's later task. */
+  private sweep() {
+    for (const token of [...this.tracked.keys()] as { ref: WeakRef<object>, cls: number, opaque: number }[]) {
+      if (token.ref.deref() !== undefined) continue
+      this.tracked.delete(token)
+      this.classRegistry.unregister(token)
+      this.M._jsbFinalize(token.cls, token.opaque)
+    }
+  }
+}
+
+/** Create the glue for a loaded runtime module and install it as `Module.jsb`. */
+export const installJsb = (M: WasmModule, options: JsbOptions): Jsb => {
+  const jsb = new Jsb(M, options)
+  ;(M as unknown as { jsb: Jsb }).jsb = jsb
+  return jsb
+}

package/src/native.d.ts

@@ -0,0 +1,23 @@
+// The wasm profiles of runtime/web/native (build-wasm.sh → native/dist): Emscripten ES6 modules whose
+// default export is the module factory. Typed loosely on purpose — the generated bridges type the
+// exports they call through the Wasm adapter (src/gen/wasm.ts).
+declare module "*creator-full.js" {
+  const factory: (args?: Record<string, unknown>) => Promise<any>
+  export default factory
+}
+declare module "*creator-2d.js" {
+  const factory: (args?: Record<string, unknown>) => Promise<any>
+  export default factory
+}
+declare module "*creator-ui.js" {
+  const factory: (args?: Record<string, unknown>) => Promise<any>
+  export default factory
+}
+declare module "*creator-nav.js" {
+  const factory: (args?: Record<string, unknown>) => Promise<any>
+  export default factory
+}
+declare module "*creator-headless.js" {
+  const factory: (args?: Record<string, unknown>) => Promise<any>
+  export default factory
+}