@rezi-ui/node 0.1.0-alpha.1

package/dist/backend/nodeBackend.js

@@ -0,0 +1,942 @@
+/**
+ * Node RuntimeBackend implementation (LOCKED behavior).
+ * @see docs/backend/worker-model.md
+ * @see docs/guide/lifecycle-and-updates.md
+ * @see docs/backend/node.md
+ * @see docs/dev/style-guide.md
+ * @see docs/backend/native.md
+ */
+import { Worker } from "node:worker_threads";
+import { DEFAULT_TERMINAL_CAPS, FRAME_ACCEPTED_ACK_MARKER } from "@rezi-ui/core";
+import { ZR_DRAWLIST_VERSION_V1, ZR_DRAWLIST_VERSION_V2, ZR_ENGINE_ABI_MAJOR, ZR_ENGINE_ABI_MINOR, ZR_ENGINE_ABI_PATCH, ZR_EVENT_BATCH_VERSION_V1, ZrUiError, severityToNum, } from "@rezi-ui/core";
+import { FRAME_SAB_CONTROL_CONSUMED_SEQ_WORD, FRAME_SAB_CONTROL_HEADER_WORDS, FRAME_SAB_CONTROL_PUBLISHED_BYTES_WORD, FRAME_SAB_CONTROL_PUBLISHED_SEQ_WORD, FRAME_SAB_CONTROL_PUBLISHED_SLOT_WORD, FRAME_SAB_CONTROL_PUBLISHED_TOKEN_WORD, FRAME_SAB_CONTROL_WORDS_PER_SLOT, FRAME_SAB_SLOT_STATE_FREE, FRAME_SAB_SLOT_STATE_READY, FRAME_SAB_SLOT_STATE_WRITING, FRAME_TRANSPORT_SAB_V1, FRAME_TRANSPORT_TRANSFER_V1, FRAME_TRANSPORT_VERSION, } from "../worker/protocol.js";
+import { createNodeBackendInlineInternal } from "./nodeBackendInline.js";
+function deferred() {
+    let resolve;
+    let reject;
+    const promise = new Promise((res, rej) => {
+        resolve = res;
+        reject = (err) => rej(err instanceof Error ? err : new Error(String(err)));
+    });
+    return { promise, resolve, reject };
+}
+function parsePositiveIntOr(n, fallback) {
+    if (typeof n !== "number")
+        return fallback;
+    if (!Number.isFinite(n))
+        return fallback;
+    if (!Number.isInteger(n))
+        return fallback;
+    if (n <= 0)
+        return fallback;
+    return n;
+}
+function parsePositiveInt(n) {
+    if (typeof n !== "number")
+        return null;
+    if (!Number.isFinite(n))
+        return null;
+    if (!Number.isInteger(n))
+        return null;
+    if (n <= 0)
+        return null;
+    return n;
+}
+function readNativeTargetFps(cfg) {
+    const targetFpsCfg = cfg;
+    return parsePositiveInt(targetFpsCfg.targetFps) ?? parsePositiveInt(targetFpsCfg.target_fps);
+}
+function safeErr(err) {
+    return err instanceof Error ? err : new Error(String(err));
+}
+const DEBUG_QUERY_DEFAULT_RECORDS = 4096;
+const DEBUG_QUERY_MAX_RECORDS = 16384;
+const FRAME_SAB_SLOT_COUNT_DEFAULT = 8;
+const FRAME_SAB_SLOT_BYTES_DEFAULT = 1 << 20;
+function copyInto(buf, bytes) {
+    new Uint8Array(buf, 0, bytes.byteLength).set(bytes);
+}
+function frameSeqToSlotToken(frameSeq) {
+    const token = frameSeq & 0x7fff_ffff;
+    return token === 0 ? 1 : token;
+}
+function createSabFrameTransport(slotCount, slotBytes) {
+    if (typeof SharedArrayBuffer !== "function")
+        return null;
+    const control = new SharedArrayBuffer((FRAME_SAB_CONTROL_HEADER_WORDS + slotCount * FRAME_SAB_CONTROL_WORDS_PER_SLOT) *
+        Int32Array.BYTES_PER_ELEMENT);
+    const controlHeader = new Int32Array(control, 0, FRAME_SAB_CONTROL_HEADER_WORDS);
+    const states = new Int32Array(control, FRAME_SAB_CONTROL_HEADER_WORDS * Int32Array.BYTES_PER_ELEMENT, slotCount);
+    const tokens = new Int32Array(control, (FRAME_SAB_CONTROL_HEADER_WORDS + slotCount) * Int32Array.BYTES_PER_ELEMENT, slotCount);
+    Atomics.store(controlHeader, FRAME_SAB_CONTROL_PUBLISHED_SEQ_WORD, 0);
+    Atomics.store(controlHeader, FRAME_SAB_CONTROL_PUBLISHED_SLOT_WORD, 0);
+    Atomics.store(controlHeader, FRAME_SAB_CONTROL_PUBLISHED_BYTES_WORD, 0);
+    Atomics.store(controlHeader, FRAME_SAB_CONTROL_PUBLISHED_TOKEN_WORD, 0);
+    Atomics.store(controlHeader, FRAME_SAB_CONTROL_CONSUMED_SEQ_WORD, 0);
+    for (let i = 0; i < slotCount; i++) {
+        Atomics.store(states, i, FRAME_SAB_SLOT_STATE_FREE);
+        Atomics.store(tokens, i, 0);
+    }
+    const data = new SharedArrayBuffer(slotCount * slotBytes);
+    return {
+        control,
+        data,
+        slotCount,
+        slotBytes,
+        controlHeader,
+        states,
+        tokens,
+        dataBytes: new Uint8Array(data),
+        nextSlot: { value: 0 },
+    };
+}
+function resetSabFrameTransport(t) {
+    Atomics.store(t.controlHeader, FRAME_SAB_CONTROL_PUBLISHED_SEQ_WORD, 0);
+    Atomics.store(t.controlHeader, FRAME_SAB_CONTROL_PUBLISHED_SLOT_WORD, 0);
+    Atomics.store(t.controlHeader, FRAME_SAB_CONTROL_PUBLISHED_BYTES_WORD, 0);
+    Atomics.store(t.controlHeader, FRAME_SAB_CONTROL_PUBLISHED_TOKEN_WORD, 0);
+    Atomics.store(t.controlHeader, FRAME_SAB_CONTROL_CONSUMED_SEQ_WORD, 0);
+    for (let i = 0; i < t.slotCount; i++) {
+        Atomics.store(t.states, i, FRAME_SAB_SLOT_STATE_FREE);
+        Atomics.store(t.tokens, i, 0);
+    }
+    t.nextSlot.value = 0;
+}
+function acquireSabSlot(t) {
+    const start = t.nextSlot.value % t.slotCount;
+    for (let i = 0; i < t.slotCount; i++) {
+        const slot = (start + i) % t.slotCount;
+        const prev = Atomics.compareExchange(t.states, slot, FRAME_SAB_SLOT_STATE_FREE, FRAME_SAB_SLOT_STATE_WRITING);
+        if (prev === FRAME_SAB_SLOT_STATE_FREE) {
+            t.nextSlot.value = (slot + 1) % t.slotCount;
+            return slot;
+        }
+    }
+    // Latest-wins semantics allow reclaiming stale READY slots instead of
+    // falling back to transfer under pressure.
+    for (let i = 0; i < t.slotCount; i++) {
+        const slot = (start + i) % t.slotCount;
+        const prev = Atomics.compareExchange(t.states, slot, FRAME_SAB_SLOT_STATE_READY, FRAME_SAB_SLOT_STATE_WRITING);
+        if (prev === FRAME_SAB_SLOT_STATE_READY) {
+            t.nextSlot.value = (slot + 1) % t.slotCount;
+            return slot;
+        }
+    }
+    return -1;
+}
+function publishSabFrame(t, frameSeq, slotIndex, slotToken, byteLen) {
+    Atomics.store(t.controlHeader, FRAME_SAB_CONTROL_PUBLISHED_SLOT_WORD, slotIndex);
+    Atomics.store(t.controlHeader, FRAME_SAB_CONTROL_PUBLISHED_BYTES_WORD, byteLen);
+    Atomics.store(t.controlHeader, FRAME_SAB_CONTROL_PUBLISHED_TOKEN_WORD, slotToken);
+    Atomics.store(t.controlHeader, FRAME_SAB_CONTROL_PUBLISHED_SEQ_WORD, frameSeq);
+}
+export function createNodeBackendInternal(opts = {}) {
+    const cfg = opts.config ?? {};
+    const fpsCap = parsePositiveIntOr(cfg.fpsCap, 60);
+    const requestedExecutionMode = cfg.executionMode ?? "auto";
+    const executionMode = requestedExecutionMode === "inline"
+        ? "inline"
+        : requestedExecutionMode === "worker"
+            ? "worker"
+            : fpsCap <= 30
+                ? "inline"
+                : "worker";
+    if (executionMode === "inline") {
+        return createNodeBackendInlineInternal(opts);
+    }
+    const maxEventBytes = parsePositiveIntOr(cfg.maxEventBytes, 1 << 20);
+    const useDrawlistV2 = cfg.useDrawlistV2 === true;
+    const frameTransportMode = cfg.frameTransport === "transfer" || cfg.frameTransport === "sab" ? cfg.frameTransport : "auto";
+    const frameSabSlotCount = parsePositiveIntOr(cfg.frameSabSlotCount, FRAME_SAB_SLOT_COUNT_DEFAULT);
+    const frameSabSlotBytes = parsePositiveIntOr(cfg.frameSabSlotBytes, FRAME_SAB_SLOT_BYTES_DEFAULT);
+    const sabFrameTransport = frameTransportMode === "transfer"
+        ? null
+        : createSabFrameTransport(frameSabSlotCount, frameSabSlotBytes);
+    const frameTransportWire = sabFrameTransport !== null
+        ? {
+            kind: FRAME_TRANSPORT_SAB_V1,
+            version: FRAME_TRANSPORT_VERSION,
+            slotCount: sabFrameTransport.slotCount,
+            slotBytes: sabFrameTransport.slotBytes,
+            control: sabFrameTransport.control,
+            data: sabFrameTransport.data,
+        }
+        : {
+            kind: FRAME_TRANSPORT_TRANSFER_V1,
+            version: FRAME_TRANSPORT_VERSION,
+        };
+    const nativeConfig = typeof cfg.nativeConfig === "object" &&
+        cfg.nativeConfig !== null &&
+        !Array.isArray(cfg.nativeConfig)
+        ? cfg.nativeConfig
+        : Object.freeze({});
+    const nativeTargetFps = readNativeTargetFps(nativeConfig) ?? fpsCap;
+    const initConfig = {
+        ...nativeConfig,
+        // Keep native tick generation aligned with app/backend fpsCap unless
+        // explicitly overridden in nativeConfig.
+        targetFps: nativeTargetFps,
+        // Negotiation pins (docs/16 + docs/01)
+        requestedEngineAbiMajor: ZR_ENGINE_ABI_MAJOR,
+        requestedEngineAbiMinor: ZR_ENGINE_ABI_MINOR,
+        requestedEngineAbiPatch: ZR_ENGINE_ABI_PATCH,
+        requestedDrawlistVersion: useDrawlistV2 ? ZR_DRAWLIST_VERSION_V2 : ZR_DRAWLIST_VERSION_V1,
+        requestedEventBatchVersion: ZR_EVENT_BATCH_VERSION_V1,
+        // Node worker runtime caps
+        fpsCap,
+        maxEventBytes,
+        frameTransport: frameTransportWire,
+    };
+    let worker = null;
+    let disposed = false;
+    let started = false;
+    let fatal = null;
+    let startDef = null;
+    let startSettled = false;
+    let stopDef = null;
+    let stopSettled = false;
+    let exitDef = null;
+    let nextFrameSeq = 1;
+    const frameAcceptedWaiters = new Map();
+    const frameCompletionWaiters = new Map();
+    const eventQueue = [];
+    const eventWaiters = [];
+    const capsWaiters = [];
+    let cachedCaps = null;
+    let stopRequested = false;
+    // =============================================================================
+    // Debug request serialization (no request IDs in protocol)
+    // =============================================================================
+    let debugChain = Promise.resolve();
+    let debugEnableDef = null;
+    let debugDisableDef = null;
+    let debugQueryDef = null;
+    let debugGetPayloadDef = null;
+    let debugGetStatsDef = null;
+    let debugExportDef = null;
+    let debugResetDef = null;
+    let perfSnapshotDef = null;
+    function rejectDebugWaiters(err) {
+        debugEnableDef?.reject(err);
+        debugEnableDef = null;
+        debugDisableDef?.reject(err);
+        debugDisableDef = null;
+        debugQueryDef?.reject(err);
+        debugQueryDef = null;
+        debugGetPayloadDef?.reject(err);
+        debugGetPayloadDef = null;
+        debugGetStatsDef?.reject(err);
+        debugGetStatsDef = null;
+        debugExportDef?.reject(err);
+        debugExportDef = null;
+        debugResetDef?.reject(err);
+        debugResetDef = null;
+        perfSnapshotDef?.reject(err);
+        perfSnapshotDef = null;
+    }
+    function enqueueDebug(fn) {
+        const p = debugChain.then(fn, fn);
+        debugChain = p.then(() => undefined, () => undefined);
+        return p;
+    }
+    function rejectFrameWaiters(err) {
+        for (const waiter of frameAcceptedWaiters.values()) {
+            waiter.reject(err);
+        }
+        frameAcceptedWaiters.clear();
+        for (const waiter of frameCompletionWaiters.values()) {
+            waiter.reject(err);
+        }
+        frameCompletionWaiters.clear();
+    }
+    function resolveAcceptedFramesUpTo(acceptedSeq) {
+        if (!Number.isInteger(acceptedSeq) || acceptedSeq <= 0)
+            return;
+        for (const [seq, waiter] of frameAcceptedWaiters.entries()) {
+            if (seq > acceptedSeq)
+                continue;
+            frameAcceptedWaiters.delete(seq);
+            waiter.resolve(undefined);
+        }
+    }
+    function resolveCoalescedCompletionFramesUpTo(acceptedSeq) {
+        if (!Number.isInteger(acceptedSeq) || acceptedSeq <= 0)
+            return;
+        for (const [seq, waiter] of frameCompletionWaiters.entries()) {
+            if (seq >= acceptedSeq)
+                continue;
+            frameCompletionWaiters.delete(seq);
+            waiter.resolve(undefined);
+        }
+    }
+    function settleCompletedFrame(frameSeq, completedResult) {
+        const waiter = frameCompletionWaiters.get(frameSeq);
+        if (waiter === undefined)
+            return;
+        frameCompletionWaiters.delete(frameSeq);
+        if (completedResult < 0) {
+            waiter.reject(new ZrUiError("ZRUI_BACKEND_ERROR", `engine frame completion failed: seq=${String(frameSeq)} code=${String(completedResult)}`));
+            return;
+        }
+        waiter.resolve(undefined);
+    }
+    function failAll(err) {
+        while (eventWaiters.length > 0)
+            eventWaiters.shift()?.reject(err);
+        while (capsWaiters.length > 0)
+            capsWaiters.shift()?.reject(err);
+        eventQueue.length = 0;
+        rejectFrameWaiters(err);
+        rejectDebugWaiters(err);
+        if (startDef !== null && !startSettled) {
+            startSettled = true;
+            startDef.reject(err);
+        }
+        if (stopDef !== null && !stopSettled) {
+            stopSettled = true;
+            stopDef.reject(err);
+        }
+    }
+    function rejectPending(err) {
+        while (eventWaiters.length > 0)
+            eventWaiters.shift()?.reject(err);
+        while (capsWaiters.length > 0)
+            capsWaiters.shift()?.reject(err);
+        eventQueue.length = 0;
+        rejectFrameWaiters(err);
+        rejectDebugWaiters(err);
+        if (startDef !== null && !startSettled) {
+            startSettled = true;
+            startDef.reject(err);
+        }
+    }
+    function send(msg, transfer) {
+        if (worker === null)
+            return;
+        if (transfer !== undefined) {
+            worker.postMessage(msg, transfer);
+            return;
+        }
+        worker.postMessage(msg);
+    }
+    function handleWorkerMessage(m) {
+        if (fatal !== null)
+            return;
+        if (typeof m !== "object" || m === null)
+            return;
+        const type = m.type;
+        if (typeof type !== "string")
+            return;
+        const msg = m;
+        switch (msg.type) {
+            case "ready": {
+                started = true;
+                stopRequested = false;
+                if (startDef !== null && !startSettled) {
+                    startSettled = true;
+                    startDef.resolve();
+                }
+                return;
+            }
+            case "frameStatus": {
+                if (!Number.isInteger(msg.acceptedSeq) || msg.acceptedSeq <= 0) {
+                    fatal = new ZrUiError("ZRUI_BACKEND_ERROR", `invalid frameStatus.acceptedSeq: ${String(msg.acceptedSeq)}`);
+                    failAll(fatal);
+                    return;
+                }
+                resolveAcceptedFramesUpTo(msg.acceptedSeq);
+                resolveCoalescedCompletionFramesUpTo(msg.acceptedSeq);
+                if (msg.completedSeq !== undefined) {
+                    if (!Number.isInteger(msg.completedSeq) || msg.completedSeq <= 0) {
+                        fatal = new ZrUiError("ZRUI_BACKEND_ERROR", `invalid frameStatus.completedSeq: ${String(msg.completedSeq)}`);
+                        failAll(fatal);
+                        return;
+                    }
+                    const completedResult = msg.completedResult ?? 0;
+                    if (!Number.isInteger(completedResult)) {
+                        fatal = new ZrUiError("ZRUI_BACKEND_ERROR", `invalid frameStatus.completedResult: ${String(msg.completedResult)}`);
+                        failAll(fatal);
+                        return;
+                    }
+                    settleCompletedFrame(msg.completedSeq, completedResult);
+                    if (completedResult < 0) {
+                        fatal = new ZrUiError("ZRUI_BACKEND_ERROR", `engine frame failed: seq=${String(msg.completedSeq)} code=${String(completedResult)}`);
+                        failAll(fatal);
+                        return;
+                    }
+                    return;
+                }
+                return;
+            }
+            case "events": {
+                const waiter = eventWaiters.shift();
+                if (waiter !== undefined) {
+                    const buf = msg.batch;
+                    const bytes = new Uint8Array(buf, 0, msg.byteLen);
+                    let released = false;
+                    waiter.resolve({
+                        bytes,
+                        droppedBatches: msg.droppedSinceLast,
+                        release: () => {
+                            if (released)
+                                return;
+                            released = true;
+                            if (disposed)
+                                return;
+                            send({ type: "eventsAck", buffer: buf }, [buf]);
+                        },
+                    });
+                    return;
+                }
+                eventQueue.push({
+                    batch: msg.batch,
+                    byteLen: msg.byteLen,
+                    droppedSinceLast: msg.droppedSinceLast,
+                });
+                return;
+            }
+            case "fatal": {
+                fatal = new ZrUiError("ZRUI_BACKEND_ERROR", `worker fatal: ${msg.where} (${msg.code}): ${msg.detail}`);
+                failAll(fatal);
+                return;
+            }
+            case "debug:enableResult": {
+                debugEnableDef?.resolve(msg.result);
+                debugEnableDef = null;
+                return;
+            }
+            case "debug:disableResult": {
+                debugDisableDef?.resolve(msg.result);
+                debugDisableDef = null;
+                return;
+            }
+            case "debug:queryResult": {
+                try {
+                    if (!Number.isInteger(msg.headersByteLen) || msg.headersByteLen < 0) {
+                        throw new Error(`debug:queryResult: invalid headersByteLen=${String(msg.headersByteLen)}`);
+                    }
+                    if (msg.headersByteLen > msg.headers.byteLength) {
+                        throw new Error(`debug:queryResult: headersByteLen=${String(msg.headersByteLen)} exceeds buffer=${String(msg.headers.byteLength)}`);
+                    }
+                    const headers = new Uint8Array(msg.headers, 0, msg.headersByteLen);
+                    const result = {
+                        recordsReturned: msg.result.recordsReturned,
+                        recordsAvailable: msg.result.recordsAvailable,
+                        oldestRecordId: BigInt(msg.result.oldestRecordId),
+                        newestRecordId: BigInt(msg.result.newestRecordId),
+                        recordsDropped: msg.result.recordsDropped,
+                    };
+                    debugQueryDef?.resolve({ headers, result });
+                    debugQueryDef = null;
+                    return;
+                }
+                catch (err) {
+                    fatal = new ZrUiError("ZRUI_BACKEND_ERROR", safeErr(err).message);
+                    failAll(fatal);
+                    return;
+                }
+            }
+            case "debug:getPayloadResult": {
+                if (msg.result <= 0 || msg.payloadByteLen <= 0) {
+                    debugGetPayloadDef?.resolve(null);
+                    debugGetPayloadDef = null;
+                    return;
+                }
+                try {
+                    if (!Number.isInteger(msg.payloadByteLen) || msg.payloadByteLen < 0) {
+                        throw new Error(`debug:getPayloadResult: invalid payloadByteLen=${String(msg.payloadByteLen)}`);
+                    }
+                    if (msg.payloadByteLen > msg.payload.byteLength) {
+                        throw new Error(`debug:getPayloadResult: payloadByteLen=${String(msg.payloadByteLen)} exceeds buffer=${String(msg.payload.byteLength)}`);
+                    }
+                    debugGetPayloadDef?.resolve(new Uint8Array(msg.payload, 0, msg.payloadByteLen));
+                    debugGetPayloadDef = null;
+                    return;
+                }
+                catch (err) {
+                    fatal = new ZrUiError("ZRUI_BACKEND_ERROR", safeErr(err).message);
+                    failAll(fatal);
+                    return;
+                }
+            }
+            case "debug:getStatsResult": {
+                try {
+                    const stats = {
+                        totalRecords: BigInt(msg.stats.totalRecords),
+                        totalDropped: BigInt(msg.stats.totalDropped),
+                        errorCount: msg.stats.errorCount,
+                        warnCount: msg.stats.warnCount,
+                        currentRingUsage: msg.stats.currentRingUsage,
+                        ringCapacity: msg.stats.ringCapacity,
+                    };
+                    debugGetStatsDef?.resolve(stats);
+                    debugGetStatsDef = null;
+                    return;
+                }
+                catch (err) {
+                    fatal = new ZrUiError("ZRUI_BACKEND_ERROR", safeErr(err).message);
+                    failAll(fatal);
+                    return;
+                }
+            }
+            case "debug:exportResult": {
+                try {
+                    if (!Number.isInteger(msg.bufferByteLen) || msg.bufferByteLen < 0) {
+                        throw new Error(`debug:exportResult: invalid bufferByteLen=${String(msg.bufferByteLen)}`);
+                    }
+                    if (msg.bufferByteLen > msg.buffer.byteLength) {
+                        throw new Error(`debug:exportResult: bufferByteLen=${String(msg.bufferByteLen)} exceeds buffer=${String(msg.buffer.byteLength)}`);
+                    }
+                    debugExportDef?.resolve(new Uint8Array(msg.buffer, 0, msg.bufferByteLen));
+                    debugExportDef = null;
+                    return;
+                }
+                catch (err) {
+                    fatal = new ZrUiError("ZRUI_BACKEND_ERROR", safeErr(err).message);
+                    failAll(fatal);
+                    return;
+                }
+            }
+            case "debug:resetResult": {
+                debugResetDef?.resolve(msg.result);
+                debugResetDef = null;
+                return;
+            }
+            case "perf:snapshotResult": {
+                perfSnapshotDef?.resolve(msg.snapshot);
+                perfSnapshotDef = null;
+                return;
+            }
+            case "shutdownComplete": {
+                rejectPending(new Error("NodeBackend: stopped"));
+                if (stopDef !== null && !stopSettled) {
+                    stopSettled = true;
+                    stopDef.resolve();
+                }
+                return;
+            }
+            case "caps": {
+                const caps = {
+                    colorMode: msg.colorMode,
+                    supportsMouse: msg.supportsMouse,
+                    supportsBracketedPaste: msg.supportsBracketedPaste,
+                    supportsFocusEvents: msg.supportsFocusEvents,
+                    supportsOsc52: msg.supportsOsc52,
+                    supportsSyncUpdate: msg.supportsSyncUpdate,
+                    supportsScrollRegion: msg.supportsScrollRegion,
+                    supportsCursorShape: msg.supportsCursorShape,
+                    supportsOutputWaitWritable: msg.supportsOutputWaitWritable,
+                    sgrAttrsSupported: msg.sgrAttrsSupported,
+                };
+                cachedCaps = caps;
+                const waiter = capsWaiters.shift();
+                if (waiter !== undefined) {
+                    waiter.resolve(caps);
+                }
+                return;
+            }
+        }
+    }
+    function handleWorkerExit(code) {
+        if (disposed)
+            return;
+        if (stopRequested) {
+            rejectPending(new Error("NodeBackend: stopped"));
+        }
+        if (code !== 0 && fatal === null) {
+            fatal = new ZrUiError("ZRUI_BACKEND_ERROR", `worker exited unexpectedly: code=${String(code)}`);
+            failAll(fatal);
+        }
+        if (code === 0 && !started && fatal === null && startDef !== null && !startSettled) {
+            fatal = new ZrUiError("ZRUI_BACKEND_ERROR", "worker exited before ready handshake");
+            failAll(fatal);
+        }
+        if (stopDef !== null && !stopSettled) {
+            stopSettled = true;
+            stopDef.resolve();
+        }
+        if (exitDef !== null)
+            exitDef.resolve();
+        worker = null;
+        started = false;
+    }
+    const backend = {
+        async start() {
+            if (disposed)
+                throw new Error("NodeBackend: disposed");
+            if (fatal !== null)
+                throw fatal;
+            if (started)
+                return;
+            if (worker === null) {
+                startDef = deferred();
+                startSettled = false;
+                stopDef = null;
+                stopSettled = false;
+                stopRequested = false;
+                if (sabFrameTransport !== null)
+                    resetSabFrameTransport(sabFrameTransport);
+                const entry = new URL("../worker/engineWorker.js", import.meta.url);
+                const workerData = opts.nativeShimModule === undefined
+                    ? undefined
+                    : { nativeShimModule: opts.nativeShimModule };
+                worker = new Worker(entry, { workerData });
+                exitDef = deferred();
+                worker.on("message", handleWorkerMessage);
+                worker.on("error", (err) => {
+                    if (fatal !== null)
+                        return;
+                    fatal = new ZrUiError("ZRUI_BACKEND_ERROR", safeErr(err).message);
+                    failAll(fatal);
+                });
+                worker.on("exit", (code) => {
+                    handleWorkerExit(code);
+                });
+                send({ type: "init", config: initConfig });
+            }
+            if (startDef === null)
+                throw new Error("NodeBackend: invariant violated (startDef is null)");
+            await startDef.promise;
+        },
+        async stop() {
+            if (disposed)
+                return;
+            if (fatal !== null)
+                throw fatal;
+            if (worker === null)
+                return;
+            if (stopDef !== null) {
+                await stopDef.promise;
+                return;
+            }
+            stopDef = deferred();
+            stopSettled = false;
+            stopRequested = true;
+            send({ type: "shutdown" });
+            await stopDef.promise;
+            if (exitDef !== null)
+                await exitDef.promise;
+        },
+        dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            if (worker !== null) {
+                worker.terminate().catch(() => { });
+                worker = null;
+            }
+            const err = new Error("NodeBackend: disposed");
+            while (eventWaiters.length > 0)
+                eventWaiters.shift()?.reject(err);
+            while (capsWaiters.length > 0)
+                capsWaiters.shift()?.reject(err);
+            eventQueue.length = 0;
+            rejectFrameWaiters(err);
+            rejectDebugWaiters(err);
+            if (startDef !== null && !startSettled) {
+                startSettled = true;
+                startDef.reject(err);
+            }
+            if (stopDef !== null && !stopSettled) {
+                stopSettled = true;
+                stopDef.reject(err);
+            }
+        },
+        requestFrame(drawlist) {
+            if (disposed)
+                return Promise.reject(new Error("NodeBackend: disposed"));
+            if (fatal !== null)
+                return Promise.reject(fatal);
+            if (stopRequested)
+                return Promise.reject(new Error("NodeBackend: stopped"));
+            if (!started) {
+                return backend.start().then(() => backend.requestFrame(drawlist));
+            }
+            if (worker === null)
+                return Promise.reject(new Error("NodeBackend: worker not available"));
+            const frameSeq = nextFrameSeq++;
+            const frameAcceptedDef = deferred();
+            frameAcceptedWaiters.set(frameSeq, frameAcceptedDef);
+            const frameCompletionDef = deferred();
+            frameCompletionWaiters.set(frameSeq, frameCompletionDef);
+            const framePromise = frameCompletionDef.promise;
+            Object.defineProperty(framePromise, FRAME_ACCEPTED_ACK_MARKER, {
+                value: frameAcceptedDef.promise,
+                configurable: false,
+                enumerable: false,
+                writable: false,
+            });
+            if (sabFrameTransport !== null && drawlist.byteLength <= sabFrameTransport.slotBytes) {
+                const slotIndex = acquireSabSlot(sabFrameTransport);
+                if (slotIndex >= 0) {
+                    const slotToken = frameSeqToSlotToken(frameSeq);
+                    const slotOffset = slotIndex * sabFrameTransport.slotBytes;
+                    sabFrameTransport.dataBytes.set(drawlist, slotOffset);
+                    Atomics.store(sabFrameTransport.tokens, slotIndex, slotToken);
+                    Atomics.store(sabFrameTransport.states, slotIndex, FRAME_SAB_SLOT_STATE_READY);
+                    publishSabFrame(sabFrameTransport, frameSeq, slotIndex, slotToken, drawlist.byteLength);
+                    // SAB consumers wake on futex notify instead of per-frame
+                    // MessagePort frameKick round-trips.
+                    Atomics.notify(sabFrameTransport.controlHeader, FRAME_SAB_CONTROL_PUBLISHED_SEQ_WORD, 1);
+                    return framePromise;
+                }
+            }
+            // Transfer fallback participates in the same ACK model:
+            // - accepted ACK (hidden marker) can unblock app scheduling early
+            // - completion promise settles on worker completion/coalescing status
+            const buf = new ArrayBuffer(drawlist.byteLength);
+            copyInto(buf, drawlist);
+            try {
+                send({
+                    type: "frame",
+                    frameSeq,
+                    byteLen: drawlist.byteLength,
+                    transport: FRAME_TRANSPORT_TRANSFER_V1,
+                    drawlist: buf,
+                }, [buf]);
+            }
+            catch (err) {
+                frameAcceptedWaiters.delete(frameSeq);
+                frameCompletionWaiters.delete(frameSeq);
+                return Promise.reject(safeErr(err));
+            }
+            return framePromise;
+        },
+        pollEvents() {
+            if (disposed)
+                return Promise.reject(new Error("NodeBackend: disposed"));
+            if (fatal !== null)
+                return Promise.reject(fatal);
+            if (stopRequested)
+                return Promise.reject(new Error("NodeBackend: stopped"));
+            const queued = eventQueue.shift();
+            if (queued !== undefined) {
+                const buf = queued.batch;
+                const bytes = new Uint8Array(buf, 0, queued.byteLen);
+                let released = false;
+                return Promise.resolve({
+                    bytes,
+                    droppedBatches: queued.droppedSinceLast,
+                    release: () => {
+                        if (released)
+                            return;
+                        released = true;
+                        if (disposed)
+                            return;
+                        send({ type: "eventsAck", buffer: buf }, [buf]);
+                    },
+                });
+            }
+            const d = deferred();
+            eventWaiters.push(d);
+            return d.promise;
+        },
+        postUserEvent(tag, payload) {
+            if (disposed)
+                throw new Error("NodeBackend: disposed");
+            if (fatal !== null)
+                throw fatal;
+            if (worker === null)
+                throw new Error("NodeBackend: not started");
+            if (stopRequested)
+                throw new Error("NodeBackend: stopped");
+            const buf = new ArrayBuffer(payload.byteLength);
+            copyInto(buf, payload);
+            send({ type: "postUserEvent", tag, payload: buf, byteLen: payload.byteLength }, [buf]);
+        },
+        async getCaps() {
+            if (disposed)
+                throw new Error("NodeBackend: disposed");
+            if (fatal !== null)
+                throw fatal;
+            // Return cached caps if available
+            if (cachedCaps !== null) {
+                return cachedCaps;
+            }
+            // If not started, return default caps
+            if (!started || worker === null) {
+                return DEFAULT_TERMINAL_CAPS;
+            }
+            // Request caps from worker
+            const d = deferred();
+            capsWaiters.push(d);
+            send({ type: "getCaps" });
+            return d.promise;
+        },
+    };
+    const debug = {
+        debugEnable: (config) => enqueueDebug(async () => {
+            if (disposed)
+                throw new Error("NodeBackend: disposed");
+            if (fatal !== null)
+                throw fatal;
+            await backend.start();
+            if (worker === null)
+                throw new Error("NodeBackend: worker not available");
+            if (debugEnableDef !== null)
+                throw new Error("NodeBackend: debugEnable already in-flight");
+            debugEnableDef = deferred();
+            const minSeverity = config.minSeverity !== undefined ? severityToNum(config.minSeverity) : null;
+            const configWire = {
+                enabled: true,
+                ...(config.ringCapacity !== undefined ? { ringCapacity: config.ringCapacity } : {}),
+                ...(minSeverity !== null ? { minSeverity } : {}),
+                ...(config.categoryMask !== undefined ? { categoryMask: config.categoryMask } : {}),
+                ...(config.captureRawEvents !== undefined
+                    ? { captureRawEvents: config.captureRawEvents }
+                    : {}),
+                ...(config.captureDrawlistBytes !== undefined
+                    ? { captureDrawlistBytes: config.captureDrawlistBytes }
+                    : {}),
+            };
+            send({ type: "debug:enable", config: configWire });
+            const rc = await debugEnableDef.promise;
+            debugEnableDef = null;
+            if (rc < 0) {
+                throw new ZrUiError("ZRUI_BACKEND_ERROR", `engineDebugEnable failed: code=${String(rc)}`);
+            }
+        }),
+        debugDisable: () => enqueueDebug(async () => {
+            if (disposed)
+                throw new Error("NodeBackend: disposed");
+            if (fatal !== null)
+                throw fatal;
+            await backend.start();
+            if (worker === null)
+                throw new Error("NodeBackend: worker not available");
+            if (debugDisableDef !== null)
+                throw new Error("NodeBackend: debugDisable already in-flight");
+            debugDisableDef = deferred();
+            send({ type: "debug:disable" });
+            const rc = await debugDisableDef.promise;
+            debugDisableDef = null;
+            if (rc < 0) {
+                throw new ZrUiError("ZRUI_BACKEND_ERROR", `engineDebugDisable failed: code=${String(rc)}`);
+            }
+        }),
+        debugQuery: (query) => enqueueDebug(async () => {
+            if (disposed)
+                throw new Error("NodeBackend: disposed");
+            if (fatal !== null)
+                throw fatal;
+            await backend.start();
+            if (worker === null)
+                throw new Error("NodeBackend: worker not available");
+            if (debugQueryDef !== null)
+                throw new Error("NodeBackend: debugQuery already in-flight");
+            debugQueryDef = deferred();
+            const minSeverity = query.minSeverity !== undefined ? severityToNum(query.minSeverity) : null;
+            const maxRecords = parsePositiveInt(query.maxRecords);
+            const recordsCap = maxRecords !== null
+                ? Math.min(maxRecords, DEBUG_QUERY_MAX_RECORDS)
+                : DEBUG_QUERY_DEFAULT_RECORDS;
+            const headersCap = Math.max(40, recordsCap * 40);
+            const queryWire = {
+                ...(query.minRecordId !== undefined ? { minRecordId: String(query.minRecordId) } : {}),
+                ...(query.maxRecordId !== undefined ? { maxRecordId: String(query.maxRecordId) } : {}),
+                ...(query.minFrameId !== undefined ? { minFrameId: String(query.minFrameId) } : {}),
+                ...(query.maxFrameId !== undefined ? { maxFrameId: String(query.maxFrameId) } : {}),
+                ...(query.categoryMask !== undefined ? { categoryMask: query.categoryMask } : {}),
+                ...(minSeverity !== null ? { minSeverity } : {}),
+                ...(maxRecords !== null ? { maxRecords: recordsCap } : {}),
+            };
+            send({ type: "debug:query", query: queryWire, headersCap });
+            const out = await debugQueryDef.promise;
+            debugQueryDef = null;
+            return out;
+        }),
+        debugGetPayload: (recordId) => enqueueDebug(async () => {
+            if (disposed)
+                throw new Error("NodeBackend: disposed");
+            if (fatal !== null)
+                throw fatal;
+            await backend.start();
+            if (worker === null)
+                throw new Error("NodeBackend: worker not available");
+            if (debugGetPayloadDef !== null) {
+                throw new Error("NodeBackend: debugGetPayload already in-flight");
+            }
+            debugGetPayloadDef = deferred();
+            // Payloads can include raw drawlist bytes. Default to 4 MiB.
+            const payloadCap = 1 << 22;
+            send({
+                type: "debug:getPayload",
+                recordId: String(recordId),
+                payloadCap,
+            });
+            const bytes = await debugGetPayloadDef.promise;
+            debugGetPayloadDef = null;
+            return bytes;
+        }),
+        debugGetStats: () => enqueueDebug(async () => {
+            if (disposed)
+                throw new Error("NodeBackend: disposed");
+            if (fatal !== null)
+                throw fatal;
+            await backend.start();
+            if (worker === null)
+                throw new Error("NodeBackend: worker not available");
+            if (debugGetStatsDef !== null)
+                throw new Error("NodeBackend: debugGetStats already in-flight");
+            debugGetStatsDef = deferred();
+            send({ type: "debug:getStats" });
+            const stats = await debugGetStatsDef.promise;
+            debugGetStatsDef = null;
+            return stats;
+        }),
+        debugExport: () => enqueueDebug(async () => {
+            if (disposed)
+                throw new Error("NodeBackend: disposed");
+            if (fatal !== null)
+                throw fatal;
+            await backend.start();
+            if (worker === null)
+                throw new Error("NodeBackend: worker not available");
+            if (debugExportDef !== null)
+                throw new Error("NodeBackend: debugExport already in-flight");
+            debugExportDef = deferred();
+            send({ type: "debug:export", bufferCap: 1 << 23 }); // 8 MiB
+            const bytes = await debugExportDef.promise;
+            debugExportDef = null;
+            return bytes;
+        }),
+        debugReset: () => enqueueDebug(async () => {
+            if (disposed)
+                throw new Error("NodeBackend: disposed");
+            if (fatal !== null)
+                throw fatal;
+            await backend.start();
+            if (worker === null)
+                throw new Error("NodeBackend: worker not available");
+            if (debugResetDef !== null)
+                throw new Error("NodeBackend: debugReset already in-flight");
+            debugResetDef = deferred();
+            send({ type: "debug:reset" });
+            const rc = await debugResetDef.promise;
+            debugResetDef = null;
+            if (rc < 0) {
+                throw new ZrUiError("ZRUI_BACKEND_ERROR", `engineDebugReset failed: code=${String(rc)}`);
+            }
+        }),
+    };
+    const perf = {
+        perfSnapshot: () => enqueueDebug(async () => {
+            if (disposed)
+                throw new Error("NodeBackend: disposed");
+            if (fatal !== null)
+                throw fatal;
+            await backend.start();
+            if (worker === null)
+                throw new Error("NodeBackend: worker not available");
+            if (perfSnapshotDef !== null)
+                throw new Error("NodeBackend: perfSnapshot already in-flight");
+            perfSnapshotDef = deferred();
+            send({ type: "perf:snapshot" });
+            const snapshot = await perfSnapshotDef.promise;
+            perfSnapshotDef = null;
+            return snapshot;
+        }),
+    };
+    return Object.assign(backend, { debug, perf });
+}
+//# sourceMappingURL=nodeBackend.js.map