domqueue-host 0.1.0-beta.1

package/README.md

@@ -0,0 +1,95 @@
+# SikioDQ
+
+![NPM Version](https://img.shields.io/npm/v/@domqueue/host?style=flat-square&color=blue) ![License](https://img.shields.io/badge/license-UNLICENSED-lightgrey?style=flat-square) ![Rust](https://img.shields.io/badge/built_with-Rust-orange?style=flat-square) ![WASM](https://img.shields.io/badge/target-WASM-purple?style=flat-square) ![Size](https://img.shields.io/bundlephobia/minzip/@domqueue/host?style=flat-square&label=minzipped)
+
+A command-buffered Wasm -> DOM runtime (DOMQueue / DQ). Wasm writes UI commands into linear memory; a tiny JS host applies them in one tight loop per frame.
+
+## Performance
+
+The perf harness compares naive DOM text updates vs the DOMQueue command buffer path.
+
+| Scenario | Naive DOM | DOMQueue cmd buffer | Speedup |
+|---------|-----------|---------------------|---------|
+| NODES=200, ITER=100 | TBD | TBD | TBD |
+
+Run the harness:
+
+```bash
+npm --prefix packages/domqueue-host run build
+npm run serve
+# open http://127.0.0.1:4173/examples/perf/index.html
+```
+
+Tune parameters in `examples/perf/bench-config.js`.
+
+## Features
+
+- Command buffer protocol (u32 opcodes) with a versioned shared header (v0.2)
+- String and atom interning to avoid per-frame UTF-8 decode
+- Event ring with coalescing for high-rate events
+- List reordering using LIS (`LIST_BEGIN/ITEM/END`)
+- Blueprints + slot commits for fast text updates
+- Worker + shared memory mode (CAP_WORKER_SHARED)
+- Tools for inspecting buffers and traces (`dq-dump`, `dq-trace-viewer`)
+
+## Installation
+
+```bash
+npm i @domqueue/host
+```
+
+## Quick Start
+
+```js
+import { createHost } from "@domqueue/host";
+
+const mount = document.getElementById("app");
+const host = await createHost({ wasmUrl: "/app.wasm", mount });
+host.start();
+```
+
+Your Wasm module must export:
+
+- `dq_get_shared_ptr() -> u32`
+- `dq_frame(now_ms: f64)`
+
+## Examples
+
+- Counter: `examples/counter/index.html`
+- TodoMVC: `examples/todomvc/index.html`
+- Perf: `examples/perf/index.html`
+
+Serve examples:
+
+```bash
+npm --prefix packages/domqueue-host run build
+npm run serve
+```
+
+## Protocol
+
+See the protocol spec in `packages/domqueue-protocol/SPEC.md`.
+
+## Project Layout
+
+- `packages/domqueue-host` - JS host runtime (`createHost`, `startWorker`, DOM backend)
+- `packages/domqueue-rust` - Rust ABI + command writer + example Wasm apps
+- `examples` - Counter, TodoMVC, perf harness
+- `tools/dq-dump` - Command buffer decoder
+- `tools/dq-trace-viewer` - Trace viewer HTML
+
+## Worker Mode
+
+Worker mode requires shared memory and cross-origin isolation. See `packages/domqueue-host/WORKER.md`.
+
+## Building From Source
+
+```bash
+rustup target add wasm32-unknown-unknown
+npm --prefix packages/domqueue-host run build
+npm --prefix packages/domqueue-host run build:wasm
+```
+
+## License
+
+This project is licensed under AGPLv3 (`AGPL-3.0-only`)

package/dist/backend.d.ts

@@ -0,0 +1,10 @@
+export type DomBackend<TNode> = {
+    createElem: (tag: string) => TNode;
+    createText: (text: string) => TNode;
+    setText: (node: TNode, text: string) => void;
+    setAttr: (node: TNode, name: string, value: string) => void;
+    append: (parent: TNode, child: TNode) => void;
+    insertBefore: (parent: TNode, child: TNode, before: TNode | null) => void;
+    remove: (node: TNode) => void;
+};
+export declare const createDomBackend: (doc: Document) => DomBackend<Node>;

package/dist/backend.js

@@ -0,0 +1,23 @@
+export const createDomBackend = (doc) => ({
+    createElem: (tag) => doc.createElement(tag),
+    createText: (text) => doc.createTextNode(text),
+    setText: (node, text) => {
+        node.textContent = text;
+    },
+    setAttr: (node, name, value) => {
+        if (node instanceof Element) {
+            node.setAttribute(name, value);
+        }
+    },
+    append: (parent, child) => {
+        parent.appendChild(child);
+    },
+    insertBefore: (parent, child, before) => {
+        parent.insertBefore(child, before);
+    },
+    remove: (node) => {
+        if (node.parentNode) {
+            node.parentNode.removeChild(node);
+        }
+    }
+});

package/dist/core.d.ts

@@ -0,0 +1,64 @@
+import type { DomBackend } from "./backend.js";
+type BlueprintNode = {
+    handle: number;
+    kind: number;
+    parent: number;
+    tagOrSlot: number;
+};
+type Blueprint<TNode> = {
+    nodes: BlueprintNode[];
+    slotIds: number[];
+};
+type PendingEvent = {
+    typeId: number;
+    targetHandle: number;
+    time: number;
+    data0: number;
+    data1: number;
+    data2: number;
+};
+export type Core<TNode> = {
+    memory: WebAssembly.Memory;
+    sharedPtr: number;
+    sharedIndex: number;
+    backend: DomBackend<TNode>;
+    buffer: ArrayBuffer;
+    u8: Uint8Array;
+    u32: Uint32Array;
+    i32: Int32Array;
+    isShared: boolean;
+    caps: number;
+    nodes: Array<TNode | null>;
+    gens: number[];
+    decoder: TextDecoder;
+    atomTable: string[];
+    stringTable: string[];
+    eventBindings: Set<string>;
+    pendingEvents: Map<string, PendingEvent>;
+    listParentHandle: number;
+    listParent: TNode | null;
+    listItems: Array<{
+        key: number;
+        node: TNode;
+    }>;
+    listStates: Map<number, number[]>;
+    blueprints: Map<number, Blueprint<TNode>>;
+    slotNodes: Map<number, TNode>;
+};
+export type CoreInit<TNode> = {
+    memory: WebAssembly.Memory;
+    sharedPtr: number;
+    backend: DomBackend<TNode>;
+    mountHandle: number;
+    mountNode: TNode;
+};
+export declare const flushPendingEvents: <TNode>(core: Core<TNode>) => void;
+export declare const createCore: <TNode>(init: CoreInit<TNode>) => Core<TNode>;
+export declare const refreshViewsIfNeeded: <TNode>(core: Core<TNode>) => void;
+export declare const validateHeader: <TNode>(core: Core<TNode>) => void;
+export declare const applyCmdBuffer: <TNode>(core: Core<TNode>) => void;
+export declare const decodeHandleParts: (handle: number) => {
+    index: number;
+    gen: number;
+};
+export {};

package/dist/core.js

@@ -0,0 +1,601 @@
+import { CAP_EVENTS, DQ_MAGIC, DQ_VERSION, EVENT_RECORD_WORDS, HDR_CAPS, HDR_CMD_ACTIVE, HDR_CMD_CAP_WORDS, HDR_CMD_LEN_WORDS, HDR_CMD_LEN_WORDS_B, HDR_CMD_PTR, HDR_CMD_PTR_B, HDR_EV_CAP_WORDS, HDR_EV_HEAD, HDR_EV_PTR, HDR_EV_TAIL, HDR_MAGIC, HDR_SYNC_STATE, HDR_VERSION, HANDLE_GEN_SHIFT, HANDLE_INDEX_MASK, OP_APPEND, OP_BLUEPRINT_DEFINE, OP_BLUEPRINT_INSTANTIATE, OP_CREATE_ELEM, OP_CREATE_ELEM_ATOM, OP_CREATE_TEXT, OP_EVENT_ON, OP_INSERT_BEFORE, OP_INTERN_ATOM, OP_INTERN_STRING, OP_LIST_BEGIN, OP_LIST_END, OP_LIST_ITEM, OP_REMOVE, OP_SET_ATTR, OP_SET_ATTR_ATOM, OP_SET_TEXT, OP_SET_TEXT_ID, OP_SLOT_COMMIT, CAP_WORKER_SHARED, handleGen, handleIndex } from "./protocol.js";
+const isSharedBuffer = (buffer) => typeof SharedArrayBuffer !== "undefined" && buffer instanceof SharedArrayBuffer;
+const ensureSlot = (core, index, gen) => {
+    while (core.nodes.length <= index) {
+        core.nodes.push(null);
+        core.gens.push(0);
+    }
+    if (core.gens[index] === 0) {
+        core.gens[index] = gen;
+    }
+};
+const setHandle = (core, handle, node) => {
+    const index = handleIndex(handle);
+    const gen = handleGen(handle);
+    if (index === 0) {
+        return;
+    }
+    ensureSlot(core, index, gen);
+    core.nodes[index] = node;
+    core.gens[index] = gen;
+};
+const getNode = (core, handle) => {
+    if (handle === 0) {
+        return null;
+    }
+    const index = handleIndex(handle);
+    const gen = handleGen(handle);
+    if (index >= core.nodes.length) {
+        return null;
+    }
+    if (core.gens[index] !== gen) {
+        return null;
+    }
+    return core.nodes[index];
+};
+const dropHandle = (core, handle) => {
+    if (handle === 0) {
+        return;
+    }
+    const index = handleIndex(handle);
+    const gen = handleGen(handle);
+    if (index >= core.nodes.length) {
+        return;
+    }
+    if (core.gens[index] !== gen) {
+        return;
+    }
+    core.nodes[index] = null;
+    const nextGen = (gen + 1) & 0xff;
+    core.gens[index] = nextGen === 0 ? 1 : nextGen;
+};
+const readString = (core, ptr, len) => {
+    if (len === 0) {
+        return "";
+    }
+    const end = ptr + len;
+    if (end > core.u8.length) {
+        return "";
+    }
+    return core.decoder.decode(core.u8.subarray(ptr, end));
+};
+const ensureStringSlot = (table, id) => {
+    while (table.length <= id) {
+        table.push("");
+    }
+};
+const internToTable = (core, table, id, ptr, len) => {
+    ensureStringSlot(table, id);
+    table[id] = readString(core, ptr, len);
+};
+const lookupString = (table, id) => {
+    if (id < 0 || id >= table.length) {
+        return "";
+    }
+    return table[id] ?? "";
+};
+const loadIndex = (core, offset) => {
+    const idx = core.sharedIndex + offset;
+    if (core.isShared) {
+        return Atomics.load(core.i32, idx) >>> 0;
+    }
+    return core.u32[idx];
+};
+const storeIndex = (core, offset, value) => {
+    const idx = core.sharedIndex + offset;
+    if (core.isShared) {
+        Atomics.store(core.i32, idx, value);
+        return;
+    }
+    core.u32[idx] = value;
+};
+const pushEvent = (core, ev) => {
+    const evPtr = core.u32[core.sharedIndex + HDR_EV_PTR];
+    const evCapWords = core.u32[core.sharedIndex + HDR_EV_CAP_WORDS];
+    if (evPtr === 0 || evCapWords === 0) {
+        return;
+    }
+    const head = loadIndex(core, HDR_EV_HEAD);
+    const tail = loadIndex(core, HDR_EV_TAIL);
+    const next = head + EVENT_RECORD_WORDS >= evCapWords ? 0 : head + EVENT_RECORD_WORDS;
+    if (next === tail) {
+        const drop = tail + EVENT_RECORD_WORDS >= evCapWords ? 0 : tail + EVENT_RECORD_WORDS;
+        storeIndex(core, HDR_EV_TAIL, drop);
+    }
+    const base = (evPtr >>> 2) + head;
+    core.u32[base] = ev.typeId;
+    core.u32[base + 1] = ev.targetHandle;
+    core.u32[base + 2] = ev.time >>> 0;
+    core.u32[base + 3] = ev.data0 >>> 0;
+    core.u32[base + 4] = ev.data1 >>> 0;
+    core.u32[base + 5] = ev.data2 >>> 0;
+    storeIndex(core, HDR_EV_HEAD, next);
+};
+const COALESCE_EVENTS = new Set(["pointermove", "mousemove", "scroll", "wheel"]);
+const enqueueEvent = (core, ev, eventName) => {
+    if (COALESCE_EVENTS.has(eventName)) {
+        const key = `${eventName}:${ev.targetHandle}`;
+        core.pendingEvents.set(key, ev);
+        return;
+    }
+    pushEvent(core, ev);
+};
+export const flushPendingEvents = (core) => {
+    if (core.pendingEvents.size === 0) {
+        return;
+    }
+    for (const ev of core.pendingEvents.values()) {
+        pushEvent(core, ev);
+    }
+    core.pendingEvents.clear();
+};
+const eventPayload = (event) => {
+    if (event instanceof MouseEvent) {
+        return {
+            data0: event.clientX >>> 0,
+            data1: event.clientY >>> 0,
+            data2: event.buttons >>> 0
+        };
+    }
+    if (event instanceof KeyboardEvent) {
+        const mod = (event.shiftKey ? 1 : 0) | (event.ctrlKey ? 2 : 0) | (event.altKey ? 4 : 0) | (event.metaKey ? 8 : 0);
+        return {
+            data0: event.keyCode >>> 0,
+            data1: mod >>> 0,
+            data2: 0
+        };
+    }
+    return { data0: 0, data1: 0, data2: 0 };
+};
+export const createCore = (init) => {
+    const buffer = init.memory.buffer;
+    const u8 = new Uint8Array(buffer);
+    const u32 = new Uint32Array(buffer);
+    const i32 = new Int32Array(buffer);
+    const sharedIndex = init.sharedPtr >>> 2;
+    const core = {
+        memory: init.memory,
+        sharedPtr: init.sharedPtr,
+        sharedIndex,
+        backend: init.backend,
+        buffer,
+        u8,
+        u32,
+        i32,
+        isShared: isSharedBuffer(buffer),
+        caps: 0,
+        nodes: [],
+        gens: [],
+        decoder: new TextDecoder(),
+        atomTable: [],
+        stringTable: [],
+        eventBindings: new Set(),
+        pendingEvents: new Map(),
+        listParentHandle: 0,
+        listParent: null,
+        listItems: [],
+        listStates: new Map(),
+        blueprints: new Map(),
+        slotNodes: new Map()
+    };
+    setHandle(core, init.mountHandle, init.mountNode);
+    return core;
+};
+export const refreshViewsIfNeeded = (core) => {
+    if (core.memory.buffer === core.buffer) {
+        return;
+    }
+    core.buffer = core.memory.buffer;
+    core.u8 = new Uint8Array(core.buffer);
+    core.u32 = new Uint32Array(core.buffer);
+    core.i32 = new Int32Array(core.buffer);
+    core.isShared = isSharedBuffer(core.buffer);
+};
+export const validateHeader = (core) => {
+    const magic = core.u32[core.sharedIndex + HDR_MAGIC];
+    const version = core.u32[core.sharedIndex + HDR_VERSION];
+    if (magic !== DQ_MAGIC) {
+        throw new Error("DQ magic mismatch");
+    }
+    if (version !== DQ_VERSION) {
+        throw new Error("DQ version mismatch");
+    }
+    core.caps = core.u32[core.sharedIndex + HDR_CAPS];
+};
+const computeLis = (seq) => {
+    const n = seq.length;
+    const prev = new Array(n).fill(-1);
+    const tails = [];
+    const tailsIndex = [];
+    let i = 0;
+    while (i < n) {
+        const v = seq[i];
+        if (v >= 0) {
+            let lo = 0;
+            let hi = tails.length;
+            while (lo < hi) {
+                const mid = (lo + hi) >> 1;
+                if (tails[mid] < v) {
+                    lo = mid + 1;
+                }
+                else {
+                    hi = mid;
+                }
+            }
+            if (lo > 0) {
+                prev[i] = tailsIndex[lo - 1];
+            }
+            if (lo === tails.length) {
+                tails.push(v);
+                tailsIndex.push(i);
+            }
+            else {
+                tails[lo] = v;
+                tailsIndex[lo] = i;
+            }
+        }
+        i += 1;
+    }
+    const keep = new Array(n).fill(false);
+    if (tailsIndex.length === 0) {
+        return keep;
+    }
+    let k = tailsIndex[tailsIndex.length - 1];
+    while (k >= 0) {
+        keep[k] = true;
+        k = prev[k];
+    }
+    return keep;
+};
+const applyList = (core) => {
+    const parent = core.listParent;
+    const parentHandle = core.listParentHandle;
+    if (!parent || parentHandle === 0) {
+        core.listItems = [];
+        core.listParent = null;
+        core.listParentHandle = 0;
+        return;
+    }
+    const newKeys = core.listItems.map((item) => item.key);
+    const prevKeys = core.listStates.get(parentHandle) ?? [];
+    const indexMap = new Map();
+    let p = 0;
+    while (p < prevKeys.length) {
+        indexMap.set(prevKeys[p], p);
+        p += 1;
+    }
+    const seq = newKeys.map((key) => {
+        const idx = indexMap.get(key);
+        return idx === undefined ? -1 : idx;
+    });
+    const keep = computeLis(seq);
+    let anchor = null;
+    let i = core.listItems.length - 1;
+    while (i >= 0) {
+        const item = core.listItems[i];
+        if (keep[i]) {
+            anchor = item.node;
+        }
+        else {
+            core.backend.insertBefore(parent, item.node, anchor);
+            anchor = item.node;
+        }
+        i -= 1;
+    }
+    core.listStates.set(parentHandle, newKeys);
+    core.listItems = [];
+    core.listParent = null;
+    core.listParentHandle = 0;
+};
+const parseBlueprint = (core, ptr, lenWords) => {
+    const base = ptr >>> 2;
+    if (base + lenWords > core.u32.length || lenWords < 2) {
+        return null;
+    }
+    const version = core.u32[base];
+    const count = core.u32[base + 1];
+    if (version !== 1) {
+        return null;
+    }
+    const nodes = [];
+    const slotIds = [];
+    let offset = base + 2;
+    let i = 0;
+    while (i < count) {
+        if (offset + 4 > base + lenWords) {
+            break;
+        }
+        const handle = core.u32[offset];
+        const kind = core.u32[offset + 1];
+        const parent = core.u32[offset + 2];
+        const tagOrSlot = core.u32[offset + 3];
+        nodes.push({ handle, kind, parent, tagOrSlot });
+        if (kind === 2) {
+            slotIds.push(tagOrSlot);
+        }
+        offset += 4;
+        i += 1;
+    }
+    return { nodes, slotIds };
+};
+const instantiateBlueprint = (core, blueprint) => {
+    for (const node of blueprint.nodes) {
+        if (node.kind === 1) {
+            const tag = lookupString(core.atomTable, node.tagOrSlot);
+            const elem = core.backend.createElem(tag);
+            setHandle(core, node.handle, elem);
+            const parent = node.parent === 0 ? null : getNode(core, node.parent);
+            if (parent) {
+                core.backend.append(parent, elem);
+            }
+        }
+        else if (node.kind === 2) {
+            const text = core.backend.createText("");
+            setHandle(core, node.handle, text);
+            core.slotNodes.set(node.tagOrSlot, text);
+            const parent = node.parent === 0 ? null : getNode(core, node.parent);
+            if (parent) {
+                core.backend.append(parent, text);
+            }
+        }
+    }
+};
+const applySlotCommit = (core, valuesPtr, valuesLenWords, dirtyPtr, dirtyLenWords) => {
+    const valuesIndex = valuesPtr >>> 2;
+    const dirtyIndex = dirtyPtr >>> 2;
+    if (valuesIndex + valuesLenWords > core.u32.length) {
+        return;
+    }
+    if (dirtyIndex + dirtyLenWords > core.u32.length) {
+        return;
+    }
+    let wordIndex = 0;
+    while (wordIndex < dirtyLenWords) {
+        const bits = core.u32[dirtyIndex + wordIndex];
+        if (bits !== 0) {
+            let bit = 0;
+            while (bit < 32) {
+                if ((bits & (1 << bit)) !== 0) {
+                    const slotId = wordIndex * 32 + bit;
+                    if (slotId < valuesLenWords) {
+                        const valueId = core.u32[valuesIndex + slotId];
+                        const node = core.slotNodes.get(slotId);
+                        if (node) {
+                            const text = lookupString(core.stringTable, valueId);
+                            core.backend.setText(node, text);
+                        }
+                    }
+                }
+                bit += 1;
+            }
+        }
+        wordIndex += 1;
+    }
+};
+export const applyCmdBuffer = (core) => {
+    if ((core.caps & CAP_WORKER_SHARED) !== 0) {
+        const state = core.u32[core.sharedIndex + HDR_SYNC_STATE];
+        if (state !== 2) {
+            return;
+        }
+    }
+    const active = core.u32[core.sharedIndex + HDR_CMD_ACTIVE];
+    const cmdPtr = active === 1 ? core.u32[core.sharedIndex + HDR_CMD_PTR_B] : core.u32[core.sharedIndex + HDR_CMD_PTR];
+    const cmdLenWords = active === 1 ? core.u32[core.sharedIndex + HDR_CMD_LEN_WORDS_B] : core.u32[core.sharedIndex + HDR_CMD_LEN_WORDS];
+    const cmdCapWords = core.u32[core.sharedIndex + HDR_CMD_CAP_WORDS];
+    if (cmdPtr === 0 || cmdLenWords === 0) {
+        return;
+    }
+    if (cmdLenWords > cmdCapWords) {
+        if (active === 1) {
+            core.u32[core.sharedIndex + HDR_CMD_LEN_WORDS_B] = 0;
+        }
+        else {
+            core.u32[core.sharedIndex + HDR_CMD_LEN_WORDS] = 0;
+        }
+        return;
+    }
+    const baseIndex = cmdPtr >>> 2;
+    let i = 0;
+    while (i < cmdLenWords) {
+        const header = core.u32[baseIndex + i];
+        const opcode = header & 0xff;
+        const len = header >>> 16;
+        const next = i + 1 + len;
+        if (next > cmdLenWords) {
+            break;
+        }
+        const args = baseIndex + i + 1;
+        if (opcode === OP_CREATE_ELEM) {
+            const handle = core.u32[args];
+            const tagPtr = core.u32[args + 1];
+            const tagLen = core.u32[args + 2];
+            const tag = readString(core, tagPtr, tagLen);
+            const node = core.backend.createElem(tag);
+            setHandle(core, handle, node);
+        }
+        else if (opcode === OP_CREATE_TEXT) {
+            const handle = core.u32[args];
+            const textPtr = core.u32[args + 1];
+            const textLen = core.u32[args + 2];
+            const text = readString(core, textPtr, textLen);
+            const node = core.backend.createText(text);
+            setHandle(core, handle, node);
+        }
+        else if (opcode === OP_SET_TEXT) {
+            const handle = core.u32[args];
+            const textPtr = core.u32[args + 1];
+            const textLen = core.u32[args + 2];
+            const node = getNode(core, handle);
+            if (node) {
+                const text = readString(core, textPtr, textLen);
+                core.backend.setText(node, text);
+            }
+        }
+        else if (opcode === OP_SET_ATTR) {
+            const handle = core.u32[args];
+            const namePtr = core.u32[args + 1];
+            const nameLen = core.u32[args + 2];
+            const valuePtr = core.u32[args + 3];
+            const valueLen = core.u32[args + 4];
+            const node = getNode(core, handle);
+            if (node) {
+                const name = readString(core, namePtr, nameLen);
+                const value = readString(core, valuePtr, valueLen);
+                core.backend.setAttr(node, name, value);
+            }
+        }
+        else if (opcode === OP_APPEND) {
+            const parentHandle = core.u32[args];
+            const childHandle = core.u32[args + 1];
+            const parent = getNode(core, parentHandle);
+            const child = getNode(core, childHandle);
+            if (parent && child) {
+                core.backend.append(parent, child);
+            }
+        }
+        else if (opcode === OP_INSERT_BEFORE) {
+            const parentHandle = core.u32[args];
+            const childHandle = core.u32[args + 1];
+            const beforeHandle = core.u32[args + 2];
+            const parent = getNode(core, parentHandle);
+            const child = getNode(core, childHandle);
+            const before = beforeHandle === 0 ? null : getNode(core, beforeHandle);
+            if (parent && child) {
+                core.backend.insertBefore(parent, child, before);
+            }
+        }
+        else if (opcode === OP_REMOVE) {
+            const handle = core.u32[args];
+            const node = getNode(core, handle);
+            if (node) {
+                core.backend.remove(node);
+            }
+            dropHandle(core, handle);
+        }
+        else if (opcode === OP_INTERN_STRING) {
+            const id = core.u32[args];
+            const ptr = core.u32[args + 1];
+            const lenStr = core.u32[args + 2];
+            internToTable(core, core.stringTable, id, ptr, lenStr);
+        }
+        else if (opcode === OP_INTERN_ATOM) {
+            const id = core.u32[args];
+            const ptr = core.u32[args + 1];
+            const lenStr = core.u32[args + 2];
+            internToTable(core, core.atomTable, id, ptr, lenStr);
+        }
+        else if (opcode === OP_CREATE_ELEM_ATOM) {
+            const handle = core.u32[args];
+            const tagId = core.u32[args + 1];
+            const tag = lookupString(core.atomTable, tagId);
+            const node = core.backend.createElem(tag);
+            setHandle(core, handle, node);
+        }
+        else if (opcode === OP_SET_ATTR_ATOM) {
+            const handle = core.u32[args];
+            const nameId = core.u32[args + 1];
+            const valueId = core.u32[args + 2];
+            const node = getNode(core, handle);
+            if (node) {
+                const name = lookupString(core.atomTable, nameId);
+                const value = lookupString(core.stringTable, valueId);
+                core.backend.setAttr(node, name, value);
+            }
+        }
+        else if (opcode === OP_SET_TEXT_ID) {
+            const handle = core.u32[args];
+            const textId = core.u32[args + 1];
+            const node = getNode(core, handle);
+            if (node) {
+                const text = lookupString(core.stringTable, textId);
+                core.backend.setText(node, text);
+            }
+        }
+        else if (opcode === OP_EVENT_ON) {
+            const handle = core.u32[args];
+            const eventId = core.u32[args + 1];
+            const flags = core.u32[args + 2];
+            const node = getNode(core, handle);
+            if (node && (core.caps & CAP_EVENTS) !== 0) {
+                const eventName = lookupString(core.atomTable, eventId);
+                if (!eventName) {
+                    i = next;
+                    continue;
+                }
+                const key = `${handle}:${eventId}`;
+                if (!core.eventBindings.has(key)) {
+                    core.eventBindings.add(key);
+                    const listener = (event) => {
+                        const { data0, data1, data2 } = eventPayload(event);
+                        const ev = {
+                            typeId: eventId,
+                            targetHandle: handle,
+                            time: Math.floor(event.timeStamp || 0),
+                            data0,
+                            data1,
+                            data2
+                        };
+                        enqueueEvent(core, ev, eventName);
+                    };
+                    node.addEventListener(eventName, listener, { passive: (flags & 1) !== 0 });
+                }
+            }
+        }
+        else if (opcode === OP_LIST_BEGIN) {
+            const parentHandle = core.u32[args];
+            const parent = getNode(core, parentHandle);
+            core.listParentHandle = parentHandle;
+            core.listParent = parent;
+            core.listItems = [];
+        }
+        else if (opcode === OP_LIST_ITEM) {
+            const key = core.u32[args];
+            const childHandle = core.u32[args + 1];
+            const child = getNode(core, childHandle);
+            if (child) {
+                core.listItems.push({ key, node: child });
+            }
+        }
+        else if (opcode === OP_LIST_END) {
+            applyList(core);
+        }
+        else if (opcode === OP_BLUEPRINT_DEFINE) {
+            const id = core.u32[args];
+            const ptr = core.u32[args + 1];
+            const lenWords = core.u32[args + 2];
+            const blueprint = parseBlueprint(core, ptr, lenWords);
+            if (blueprint) {
+                core.blueprints.set(id, blueprint);
+            }
+        }
+        else if (opcode === OP_BLUEPRINT_INSTANTIATE) {
+            const id = core.u32[args];
+            const blueprint = core.blueprints.get(id);
+            if (blueprint) {
+                instantiateBlueprint(core, blueprint);
+            }
+        }
+        else if (opcode === OP_SLOT_COMMIT) {
+            const valuesPtr = core.u32[args];
+            const valuesLen = core.u32[args + 1];
+            const dirtyPtr = core.u32[args + 2];
+            const dirtyLen = core.u32[args + 3];
+            applySlotCommit(core, valuesPtr, valuesLen, dirtyPtr, dirtyLen);
+        }
+        i = next;
+    }
+    if (active === 1) {
+        core.u32[core.sharedIndex + HDR_CMD_LEN_WORDS_B] = 0;
+    }
+    else {
+        core.u32[core.sharedIndex + HDR_CMD_LEN_WORDS] = 0;
+    }
+    if ((core.caps & CAP_WORKER_SHARED) !== 0) {
+        core.u32[core.sharedIndex + HDR_SYNC_STATE] = 0;
+    }
+};
+export const decodeHandleParts = (handle) => ({
+    index: handle & HANDLE_INDEX_MASK,
+    gen: handle >>> HANDLE_GEN_SHIFT
+});

package/dist/host.d.ts

@@ -0,0 +1,15 @@
+import { type DomBackend } from "./backend.js";
+export type HostOptions = {
+    wasmUrl: string;
+    mount: Node;
+    backend?: DomBackend<Node>;
+    importObject?: WebAssembly.Imports;
+    rootHandle?: number;
+};
+export type Host = {
+    start: () => void;
+    stop: () => void;
+    step: (now?: number) => void;
+    instance: WebAssembly.Instance;
+};
+export declare const createHost: (options: HostOptions) => Promise<Host>;

package/dist/host.js

@@ -0,0 +1,81 @@
+import { createDomBackend } from "./backend.js";
+import { applyCmdBuffer, createCore, flushPendingEvents, refreshViewsIfNeeded, validateHeader } from "./core.js";
+import { HDR_ROOT_HANDLE, makeHandle } from "./protocol.js";
+const getNow = () => {
+    const perf = globalThis.performance;
+    if (perf && typeof perf.now === "function") {
+        return perf.now();
+    }
+    return Date.now();
+};
+const scheduleFrame = (cb) => {
+    if (typeof requestAnimationFrame === "function") {
+        return requestAnimationFrame(cb);
+    }
+    return setTimeout(() => cb(getNow()), 16);
+};
+const cancelFrame = (id) => {
+    if (typeof cancelAnimationFrame === "function") {
+        cancelAnimationFrame(id);
+    }
+    else {
+        clearTimeout(id);
+    }
+};
+export const createHost = async (options) => {
+    const backend = options.backend ?? (typeof document !== "undefined" ? createDomBackend(document) : undefined);
+    if (!backend) {
+        throw new Error("Dom backend required");
+    }
+    const response = await fetch(options.wasmUrl);
+    const result = await WebAssembly.instantiateStreaming(response, options.importObject ?? {});
+    const instance = result.instance;
+    const exports = instance.exports;
+    if (!exports.memory || typeof exports.dq_get_shared_ptr !== "function" || typeof exports.dq_frame !== "function") {
+        throw new Error("Missing DQ exports");
+    }
+    const sharedPtr = exports.dq_get_shared_ptr();
+    const rootHandle = options.rootHandle ?? makeHandle(1, 1);
+    const core = createCore({
+        memory: exports.memory,
+        sharedPtr,
+        backend,
+        mountHandle: rootHandle,
+        mountNode: options.mount
+    });
+    refreshViewsIfNeeded(core);
+    validateHeader(core);
+    core.u32[core.sharedIndex + HDR_ROOT_HANDLE] = rootHandle;
+    const step = (now) => {
+        const t = now ?? getNow();
+        refreshViewsIfNeeded(core);
+        flushPendingEvents(core);
+        exports.dq_frame(t);
+        refreshViewsIfNeeded(core);
+        applyCmdBuffer(core);
+    };
+    let running = false;
+    let frameId = 0;
+    const loop = (t) => {
+        if (!running) {
+            return;
+        }
+        step(t);
+        frameId = scheduleFrame(loop);
+    };
+    const start = () => {
+        if (running) {
+            return;
+        }
+        running = true;
+        frameId = scheduleFrame(loop);
+    };
+    const stop = () => {
+        if (!running) {
+            return;
+        }
+        running = false;
+        cancelFrame(frameId);
+    };
+    return { start, stop, step, instance };
+};

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export { createHost } from "./host.js";
+export { startWorker } from "./worker.js";
+export { createDomBackend } from "./backend.js";
+export { applyCmdBuffer, createCore, flushPendingEvents, refreshViewsIfNeeded, validateHeader } from "./core.js";
+export * from "./protocol.js";
+export type { DomBackend } from "./backend.js";
+export declare const wasmUrls: {
+    counter: string;
+    todomvc: string;
+};

package/dist/index.js

@@ -0,0 +1,9 @@
+export { createHost } from "./host.js";
+export { startWorker } from "./worker.js";
+export { createDomBackend } from "./backend.js";
+export { applyCmdBuffer, createCore, flushPendingEvents, refreshViewsIfNeeded, validateHeader } from "./core.js";
+export * from "./protocol.js";
+export const wasmUrls = {
+    counter: new URL("./wasm/domqueue_example_app.wasm", import.meta.url).toString(),
+    todomvc: new URL("./wasm/domqueue_todomvc_app.wasm", import.meta.url).toString()
+};

package/dist/protocol.d.ts

@@ -0,0 +1,50 @@
+export declare const DQ_MAGIC = 1146171441;
+export declare const DQ_VERSION = 2;
+export declare const HDR_MAGIC = 0;
+export declare const HDR_VERSION = 1;
+export declare const HDR_CAPS = 2;
+export declare const HDR_CMD_PTR = 3;
+export declare const HDR_CMD_CAP_WORDS = 4;
+export declare const HDR_CMD_LEN_WORDS = 5;
+export declare const HDR_HEAP_BASE_PTR = 6;
+export declare const HDR_ROOT_HANDLE = 7;
+export declare const HDR_EV_PTR = 8;
+export declare const HDR_EV_CAP_WORDS = 9;
+export declare const HDR_EV_HEAD = 10;
+export declare const HDR_EV_TAIL = 11;
+export declare const HDR_CMD_PTR_B = 12;
+export declare const HDR_CMD_LEN_WORDS_B = 13;
+export declare const HDR_CMD_ACTIVE = 14;
+export declare const HDR_SYNC_STATE = 15;
+export declare const HDR_FRAME_ID = 16;
+export declare const HDR_WORDS = 17;
+export declare const CAP_INTERN = 1;
+export declare const CAP_EVENTS = 2;
+export declare const CAP_LIST = 4;
+export declare const CAP_BLUEPRINT = 8;
+export declare const CAP_WORKER_SHARED = 16;
+export declare const HANDLE_GEN_SHIFT = 24;
+export declare const HANDLE_INDEX_MASK = 16777215;
+export declare const EVENT_RECORD_WORDS = 6;
+export declare const makeHandle: (index: number, gen: number) => number;
+export declare const handleIndex: (handle: number) => number;
+export declare const handleGen: (handle: number) => number;
+export declare const OP_CREATE_ELEM = 1;
+export declare const OP_CREATE_TEXT = 2;
+export declare const OP_SET_TEXT = 3;
+export declare const OP_SET_ATTR = 4;
+export declare const OP_APPEND = 5;
+export declare const OP_INSERT_BEFORE = 6;
+export declare const OP_REMOVE = 7;
+export declare const OP_INTERN_STRING = 8;
+export declare const OP_INTERN_ATOM = 9;
+export declare const OP_CREATE_ELEM_ATOM = 10;
+export declare const OP_SET_ATTR_ATOM = 11;
+export declare const OP_SET_TEXT_ID = 12;
+export declare const OP_EVENT_ON = 13;
+export declare const OP_LIST_BEGIN = 14;
+export declare const OP_LIST_ITEM = 15;
+export declare const OP_LIST_END = 16;
+export declare const OP_BLUEPRINT_DEFINE = 17;
+export declare const OP_BLUEPRINT_INSTANTIATE = 18;
+export declare const OP_SLOT_COMMIT = 19;

package/dist/protocol.js

@@ -0,0 +1,50 @@
+export const DQ_MAGIC = 0x44513031;
+export const DQ_VERSION = 2;
+export const HDR_MAGIC = 0;
+export const HDR_VERSION = 1;
+export const HDR_CAPS = 2;
+export const HDR_CMD_PTR = 3;
+export const HDR_CMD_CAP_WORDS = 4;
+export const HDR_CMD_LEN_WORDS = 5;
+export const HDR_HEAP_BASE_PTR = 6;
+export const HDR_ROOT_HANDLE = 7;
+export const HDR_EV_PTR = 8;
+export const HDR_EV_CAP_WORDS = 9;
+export const HDR_EV_HEAD = 10;
+export const HDR_EV_TAIL = 11;
+export const HDR_CMD_PTR_B = 12;
+export const HDR_CMD_LEN_WORDS_B = 13;
+export const HDR_CMD_ACTIVE = 14;
+export const HDR_SYNC_STATE = 15;
+export const HDR_FRAME_ID = 16;
+export const HDR_WORDS = 17;
+export const CAP_INTERN = 1;
+export const CAP_EVENTS = 2;
+export const CAP_LIST = 4;
+export const CAP_BLUEPRINT = 8;
+export const CAP_WORKER_SHARED = 16;
+export const HANDLE_GEN_SHIFT = 24;
+export const HANDLE_INDEX_MASK = 0x00ffffff;
+export const EVENT_RECORD_WORDS = 6;
+export const makeHandle = (index, gen) => (gen << HANDLE_GEN_SHIFT) | index;
+export const handleIndex = (handle) => handle & HANDLE_INDEX_MASK;
+export const handleGen = (handle) => handle >>> HANDLE_GEN_SHIFT;
+export const OP_CREATE_ELEM = 1;
+export const OP_CREATE_TEXT = 2;
+export const OP_SET_TEXT = 3;
+export const OP_SET_ATTR = 4;
+export const OP_APPEND = 5;
+export const OP_INSERT_BEFORE = 6;
+export const OP_REMOVE = 7;
+export const OP_INTERN_STRING = 8;
+export const OP_INTERN_ATOM = 9;
+export const OP_CREATE_ELEM_ATOM = 10;
+export const OP_SET_ATTR_ATOM = 11;
+export const OP_SET_TEXT_ID = 12;
+export const OP_EVENT_ON = 13;
+export const OP_LIST_BEGIN = 14;
+export const OP_LIST_ITEM = 15;
+export const OP_LIST_END = 16;
+export const OP_BLUEPRINT_DEFINE = 17;
+export const OP_BLUEPRINT_INSTANTIATE = 18;
+export const OP_SLOT_COMMIT = 19;

package/dist/worker.d.ts

@@ -0,0 +1,12 @@
+export type WorkerOptions = {
+    wasmUrl: string;
+    importObject?: WebAssembly.Imports;
+    tickMs?: number;
+    onReady?: (sharedPtr: number, instance: WebAssembly.Instance) => void;
+};
+export type WorkerRuntime = {
+    stop: () => void;
+    instance: WebAssembly.Instance;
+    sharedPtr: number;
+};
+export declare const startWorker: (options: WorkerOptions) => Promise<WorkerRuntime>;

package/dist/worker.js

@@ -0,0 +1,46 @@
+import { HDR_SYNC_STATE } from "./protocol.js";
+const nowMs = () => {
+    const perf = globalThis.performance;
+    if (perf && typeof perf.now === "function") {
+        return perf.now();
+    }
+    return Date.now();
+};
+export const startWorker = async (options) => {
+    const response = await fetch(options.wasmUrl);
+    const result = await WebAssembly.instantiateStreaming(response, options.importObject ?? {});
+    const instance = result.instance;
+    const exports = instance.exports;
+    if (!exports.memory || typeof exports.dq_get_shared_ptr !== "function" || typeof exports.dq_frame !== "function") {
+        throw new Error("Missing DQ exports");
+    }
+    const sharedPtr = exports.dq_get_shared_ptr();
+    const tickMs = options.tickMs ?? 16;
+    options.onReady?.(sharedPtr, instance);
+    let buffer = exports.memory.buffer;
+    let u32 = new Uint32Array(buffer);
+    const headerIndex = sharedPtr >>> 2;
+    const refresh = () => {
+        if (exports.memory.buffer !== buffer) {
+            buffer = exports.memory.buffer;
+            u32 = new Uint32Array(buffer);
+        }
+    };
+    let running = true;
+    const loop = () => {
+        if (!running) {
+            return;
+        }
+        refresh();
+        u32[headerIndex + HDR_SYNC_STATE] = 1;
+        exports.dq_frame(nowMs());
+        refresh();
+        u32[headerIndex + HDR_SYNC_STATE] = 2;
+        setTimeout(loop, tickMs);
+    };
+    loop();
+    const stop = () => {
+        running = false;
+    };
+    return { stop, instance, sharedPtr };
+};

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "domqueue-host",
+  "version": "0.1.0-beta.1",
+  "license": "AGPL-3.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "WORKER.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "build:wasm": "node scripts/build-wasm.mjs",
+    "prepublishOnly": "npm run build && npm run build:wasm",
+    "test": "node --test"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.2"
+  }
+}