@rezi-ui/node 0.1.0-alpha.6 → 0.1.0-alpha.60

package/dist/backend/nodeBackend.js

@@ -6,11 +6,19 @@
  * @see docs/dev/style-guide.md
  * @see docs/backend/native.md
  */
+import { existsSync } from "node:fs";
 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 { ZR_DRAWLIST_VERSION_V1, ZR_ENGINE_ABI_MAJOR, ZR_ENGINE_ABI_MINOR, ZR_ENGINE_ABI_PATCH, ZR_EVENT_BATCH_VERSION_V1, ZrUiError, setTextMeasureEmojiPolicy, severityToNum, } from "@rezi-ui/core";
+import { createFrameAuditLogger, drawlistFingerprint, maybeDumpDrawlistBytes, } from "../frameAudit.js";
 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 { DEFAULT_FPS_CAP, DEFAULT_MAX_EVENT_BYTES, MAX_SAFE_EVENT_BYTES, MAX_SAFE_FPS_CAP, normalizeBackendNativeConfig, parseBoundedPositiveIntOrThrow, parsePositiveInt, parsePositiveIntOr, resolveTargetFps, } from "./backendSharedConfig.js";
+import { DEBUG_QUERY_DEFAULT_RECORDS, DEBUG_QUERY_MAX_RECORDS } from "./backendSharedDebug.js";
+import { attachBackendMarkers } from "./backendSharedMarkers.js";
+import { applyEmojiWidthPolicy, resolveBackendEmojiWidthPolicy } from "./emojiWidthPolicy.js";
 import { createNodeBackendInlineInternal } from "./nodeBackendInline.js";
+import { terminalProfileFromNodeEnv } from "./terminalProfile.js";
+const WIDTH_POLICY_KEY = "widthPolicy";
 function deferred() {
     let resolve;
     let reject;
@@ -20,37 +28,48 @@ function deferred() {
     });
     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 safeErr(err) {
+    return err instanceof Error ? err : new Error(String(err));
 }
-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 resolveWorkerEntry(workerData) {
+    const options = { workerData };
+    const workerEntryJs = new URL("../worker/engineWorker.js", import.meta.url);
+    if (existsSync(workerEntryJs)) {
+        return { entry: workerEntryJs, options };
+    }
+    // Source-mode worktrees do not emit sibling .js worker files under src.
+    // Use a JS bootstrap that registers tsx and then imports engineWorker.ts.
+    const workerEntryBootstrapJs = new URL("../worker/engineWorker.bootstrap.js", import.meta.url);
+    if (existsSync(workerEntryBootstrapJs)) {
+        return { entry: workerEntryBootstrapJs, options };
+    }
+    throw new ZrUiError("ZRUI_BACKEND_ERROR", "Unable to locate worker entry (expected engineWorker.js or engineWorker.bootstrap.js)");
 }
-function readNativeTargetFps(cfg) {
-    const targetFpsCfg = cfg;
-    return parsePositiveInt(targetFpsCfg.targetFps) ?? parsePositiveInt(targetFpsCfg.target_fps);
+function hasInteractiveTty() {
+    return (process.stdin.isTTY === true || process.stdout.isTTY === true || process.stderr.isTTY === true);
 }
-function safeErr(err) {
-    return err instanceof Error ? err : new Error(String(err));
+export function selectNodeBackendExecutionMode(input) {
+    const { requestedExecutionMode, fpsCap } = input;
+    const resolvedExecutionMode = requestedExecutionMode === "inline"
+        ? "inline"
+        : requestedExecutionMode === "worker"
+            ? "worker"
+            : fpsCap <= 30
+                ? "inline"
+                : "worker";
+    return {
+        resolvedExecutionMode,
+        selectedExecutionMode: resolvedExecutionMode,
+        fallbackReason: null,
+    };
+}
+function assertWorkerEnvironmentSupported(nativeShimModule) {
+    if (nativeShimModule !== undefined)
+        return;
+    if (hasInteractiveTty())
+        return;
+    throw new ZrUiError("ZRUI_BACKEND_ERROR", 'Worker backend requires a TTY when using @rezi-ui/native. Use `executionMode: "inline"` for headless runs or pass `nativeShimModule` in test harnesses.');
 }
-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) {
@@ -124,6 +143,38 @@ function acquireSabSlot(t) {
     }
     return -1;
 }
+function acquireSabSlotTracked(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 { slotIndex: slot, reclaimedReady: false };
+        }
+    }
+    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 { slotIndex: slot, reclaimedReady: true };
+        }
+    }
+    return { slotIndex: -1, reclaimedReady: false };
+}
+function acquireSabFreeSlot(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;
+        }
+    }
+    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);
@@ -131,21 +182,30 @@ function publishSabFrame(t, frameSeq, slotIndex, slotToken, byteLen) {
     Atomics.store(t.controlHeader, FRAME_SAB_CONTROL_PUBLISHED_SEQ_WORD, frameSeq);
 }
 export function createNodeBackendInternal(opts = {}) {
+    const frameAudit = createFrameAuditLogger("backend");
     const cfg = opts.config ?? {};
-    const fpsCap = parsePositiveIntOr(cfg.fpsCap, 60);
+    const fpsCap = parseBoundedPositiveIntOrThrow("fpsCap", cfg.fpsCap, DEFAULT_FPS_CAP, MAX_SAFE_FPS_CAP);
     const requestedExecutionMode = cfg.executionMode ?? "auto";
-    const executionMode = requestedExecutionMode === "inline"
-        ? "inline"
-        : requestedExecutionMode === "worker"
-            ? "worker"
-            : fpsCap <= 30
-                ? "inline"
-                : "worker";
+    const executionModeSelection = selectNodeBackendExecutionMode({
+        requestedExecutionMode,
+        fpsCap,
+        hasAnyTty: hasInteractiveTty(),
+        ...(opts.nativeShimModule === undefined ? {} : { nativeShimModule: opts.nativeShimModule }),
+    });
+    const executionMode = executionModeSelection.selectedExecutionMode;
+    if (executionModeSelection.fallbackReason !== null && frameAudit.enabled) {
+        frameAudit.emit("backend.executionModeFallback", {
+            requestedExecutionMode,
+            resolvedExecutionMode: executionModeSelection.resolvedExecutionMode,
+            selectedExecutionMode: executionMode,
+            reason: executionModeSelection.fallbackReason,
+        });
+    }
     if (executionMode === "inline") {
         return createNodeBackendInlineInternal(opts);
     }
-    const maxEventBytes = parsePositiveIntOr(cfg.maxEventBytes, 1 << 20);
-    const useDrawlistV2 = cfg.useDrawlistV2 === true;
+    const requestedDrawlistVersion = ZR_DRAWLIST_VERSION_V1;
+    const maxEventBytes = parseBoundedPositiveIntOrThrow("maxEventBytes", cfg.maxEventBytes, DEFAULT_MAX_EVENT_BYTES, MAX_SAFE_EVENT_BYTES);
     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);
@@ -165,28 +225,24 @@ export function createNodeBackendInternal(opts = {}) {
             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 = {
+    const nativeConfig = normalizeBackendNativeConfig(cfg.nativeConfig);
+    const nativeTargetFps = resolveTargetFps(fpsCap, nativeConfig);
+    const initConfigBase = {
         ...nativeConfig,
-        // Keep native tick generation aligned with app/backend fpsCap unless
-        // explicitly overridden in nativeConfig.
+        // fpsCap is the single frame-scheduling knob; native target fps must align.
         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,
+        requestedDrawlistVersion: requestedDrawlistVersion,
         requestedEventBatchVersion: ZR_EVENT_BATCH_VERSION_V1,
         // Node worker runtime caps
         fpsCap,
         maxEventBytes,
         frameTransport: frameTransportWire,
     };
+    let initConfigResolved = null;
     let worker = null;
     let disposed = false;
     let started = false;
@@ -199,6 +255,7 @@ export function createNodeBackendInternal(opts = {}) {
     let nextFrameSeq = 1;
     const frameAcceptedWaiters = new Map();
     const frameCompletionWaiters = new Map();
+    const frameAuditBySeq = new Map();
     const eventQueue = [];
     const eventWaiters = [];
     const capsWaiters = [];
@@ -248,10 +305,85 @@ export function createNodeBackendInternal(opts = {}) {
             waiter.reject(err);
         }
         frameCompletionWaiters.clear();
+        if (frameAudit.enabled) {
+            for (const [seq, meta] of frameAuditBySeq.entries()) {
+                frameAudit.emit("frame.aborted", {
+                    reason: err.message,
+                    ageMs: Math.max(0, Date.now() - meta.submitAtMs),
+                    ...meta,
+                });
+            }
+            frameAuditBySeq.clear();
+        }
+    }
+    function registerFrameAudit(frameSeq, submitPath, transport, bytes, slotIndex, slotToken) {
+        if (!frameAudit.enabled)
+            return;
+        const fp = drawlistFingerprint(bytes);
+        const meta = {
+            frameSeq,
+            submitAtMs: Date.now(),
+            submitPath,
+            transport,
+            byteLen: fp.byteLen,
+            hash32: fp.hash32,
+            prefixHash32: fp.prefixHash32,
+            cmdCount: fp.cmdCount,
+            totalSize: fp.totalSize,
+            head16: fp.head16,
+            tail16: fp.tail16,
+            ...(slotIndex === undefined ? {} : { slotIndex }),
+            ...(slotToken === undefined ? {} : { slotToken }),
+        };
+        frameAuditBySeq.set(frameSeq, meta);
+        maybeDumpDrawlistBytes("backend", submitPath, frameSeq, bytes);
+        frameAudit.emit("frame.submitted", meta);
+    }
+    function markAcceptedFramesUpTo(acceptedSeq) {
+        if (!frameAudit.enabled)
+            return;
+        for (const [seq, meta] of frameAuditBySeq.entries()) {
+            if (seq > acceptedSeq)
+                continue;
+            if (meta.acceptedLogged === true)
+                continue;
+            frameAudit.emit("frame.accepted", {
+                acceptedSeq,
+                ageMs: Math.max(0, Date.now() - meta.submitAtMs),
+                ...meta,
+            });
+            meta.acceptedLogged = true;
+        }
+    }
+    function markCoalescedFramesBefore(acceptedSeq) {
+        if (!frameAudit.enabled)
+            return;
+        for (const [seq, meta] of frameAuditBySeq.entries()) {
+            if (seq >= acceptedSeq)
+                continue;
+            frameAudit.emit("frame.coalesced", {
+                acceptedSeq,
+                ageMs: Math.max(0, Date.now() - meta.submitAtMs),
+                ...meta,
+            });
+            frameAuditBySeq.delete(seq);
+        }
+    }
+    function markCompletedFrame(frameSeq, completedResult) {
+        if (!frameAudit.enabled)
+            return;
+        const meta = frameAuditBySeq.get(frameSeq);
+        frameAudit.emit("frame.completed", {
+            completedResult,
+            ageMs: meta ? Math.max(0, Date.now() - meta.submitAtMs) : null,
+            ...(meta ?? {}),
+        });
+        frameAuditBySeq.delete(frameSeq);
     }
     function resolveAcceptedFramesUpTo(acceptedSeq) {
         if (!Number.isInteger(acceptedSeq) || acceptedSeq <= 0)
             return;
+        markAcceptedFramesUpTo(acceptedSeq);
         for (const [seq, waiter] of frameAcceptedWaiters.entries()) {
             if (seq > acceptedSeq)
                 continue;
@@ -262,6 +394,7 @@ export function createNodeBackendInternal(opts = {}) {
     function resolveCoalescedCompletionFramesUpTo(acceptedSeq) {
         if (!Number.isInteger(acceptedSeq) || acceptedSeq <= 0)
             return;
+        markCoalescedFramesBefore(acceptedSeq);
         for (const [seq, waiter] of frameCompletionWaiters.entries()) {
             if (seq >= acceptedSeq)
                 continue;
@@ -270,6 +403,7 @@ export function createNodeBackendInternal(opts = {}) {
         }
     }
     function settleCompletedFrame(frameSeq, completedResult) {
+        markCompletedFrame(frameSeq, completedResult);
         const waiter = frameCompletionWaiters.get(frameSeq);
         if (waiter === undefined)
             return;
@@ -280,6 +414,26 @@ export function createNodeBackendInternal(opts = {}) {
         }
         waiter.resolve(undefined);
     }
+    function reserveFramePromise(frameSeq) {
+        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,
+        });
+        return framePromise;
+    }
+    function releaseFrameReservation(frameSeq) {
+        frameAcceptedWaiters.delete(frameSeq);
+        frameCompletionWaiters.delete(frameSeq);
+        if (frameAudit.enabled)
+            frameAuditBySeq.delete(frameSeq);
+    }
     function failAll(err) {
         while (eventWaiters.length > 0)
             eventWaiters.shift()?.reject(err);
@@ -339,6 +493,13 @@ export function createNodeBackendInternal(opts = {}) {
                 return;
             }
             case "frameStatus": {
+                if (frameAudit.enabled) {
+                    frameAudit.emit("worker.frameStatus", {
+                        acceptedSeq: msg.acceptedSeq,
+                        completedSeq: msg.completedSeq ?? null,
+                        completedResult: msg.completedResult ?? null,
+                    });
+                }
                 if (!Number.isInteger(msg.acceptedSeq) || msg.acceptedSeq <= 0) {
                     fatal = new ZrUiError("ZRUI_BACKEND_ERROR", `invalid frameStatus.acceptedSeq: ${String(msg.acceptedSeq)}`);
                     failAll(fatal);
@@ -369,6 +530,26 @@ export function createNodeBackendInternal(opts = {}) {
                 return;
             }
             case "events": {
+                if (!Number.isInteger(msg.byteLen) || msg.byteLen < 0) {
+                    fatal = new ZrUiError("ZRUI_BACKEND_ERROR", `events: invalid byteLen=${String(msg.byteLen)}`);
+                    failAll(fatal);
+                    return;
+                }
+                if (msg.byteLen > msg.batch.byteLength) {
+                    fatal = new ZrUiError("ZRUI_BACKEND_ERROR", `events: byteLen=${String(msg.byteLen)} exceeds batch.byteLength=${String(msg.batch.byteLength)}`);
+                    failAll(fatal);
+                    return;
+                }
+                if (msg.byteLen > maxEventBytes) {
+                    fatal = new ZrUiError("ZRUI_BACKEND_ERROR", `events: byteLen=${String(msg.byteLen)} exceeds maxEventBytes=${String(maxEventBytes)}`);
+                    failAll(fatal);
+                    return;
+                }
+                if (!Number.isInteger(msg.droppedSinceLast) || msg.droppedSinceLast < 0) {
+                    fatal = new ZrUiError("ZRUI_BACKEND_ERROR", `events: invalid droppedSinceLast=${String(msg.droppedSinceLast)}`);
+                    failAll(fatal);
+                    return;
+                }
                 const waiter = eventWaiters.shift();
                 if (waiter !== undefined) {
                     const buf = msg.batch;
@@ -526,6 +707,9 @@ export function createNodeBackendInternal(opts = {}) {
                     supportsScrollRegion: msg.supportsScrollRegion,
                     supportsCursorShape: msg.supportsCursorShape,
                     supportsOutputWaitWritable: msg.supportsOutputWaitWritable,
+                    supportsUnderlineStyles: msg.supportsUnderlineStyles,
+                    supportsColoredUnderlines: msg.supportsColoredUnderlines,
+                    supportsHyperlinks: msg.supportsHyperlinks,
                     sgrAttrsSupported: msg.sgrAttrsSupported,
                 };
                 cachedCaps = caps;
@@ -568,7 +752,23 @@ export function createNodeBackendInternal(opts = {}) {
                 throw fatal;
             if (started)
                 return;
+            assertWorkerEnvironmentSupported(opts.nativeShimModule);
             if (worker === null) {
+                if (initConfigResolved === null) {
+                    const resolvedEmojiWidthPolicy = await resolveBackendEmojiWidthPolicy(cfg.emojiWidthPolicy, nativeConfig);
+                    const nativeWidthPolicy = applyEmojiWidthPolicy(resolvedEmojiWidthPolicy);
+                    initConfigResolved = {
+                        ...initConfigBase,
+                        widthPolicy: nativeWidthPolicy,
+                    };
+                }
+                else {
+                    // Keep core measurement policy deterministic across stop/start cycles.
+                    const widthPolicy = initConfigResolved[WIDTH_POLICY_KEY];
+                    if (typeof widthPolicy === "number") {
+                        setTextMeasureEmojiPolicy(widthPolicy === 0 ? "narrow" : "wide");
+                    }
+                }
                 startDef = deferred();
                 startSettled = false;
                 stopDef = null;
@@ -576,11 +776,19 @@ export function createNodeBackendInternal(opts = {}) {
                 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 });
+                const workerEntry = resolveWorkerEntry(workerData);
+                worker = new Worker(workerEntry.entry, workerEntry.options);
+                if (frameAudit.enabled) {
+                    frameAudit.emit("worker.spawn", {
+                        frameTransport: frameTransportWire.kind,
+                        frameSabSlotCount: frameSabSlotCount,
+                        frameSabSlotBytes: frameSabSlotBytes,
+                        workerEntry: workerEntry.entry.href,
+                    });
+                }
                 exitDef = deferred();
                 worker.on("message", handleWorkerMessage);
                 worker.on("error", (err) => {
@@ -592,11 +800,27 @@ export function createNodeBackendInternal(opts = {}) {
                 worker.on("exit", (code) => {
                     handleWorkerExit(code);
                 });
-                send({ type: "init", config: initConfig });
+                send({ type: "init", config: initConfigResolved });
             }
             if (startDef === null)
                 throw new Error("NodeBackend: invariant violated (startDef is null)");
-            await startDef.promise;
+            try {
+                await startDef.promise;
+            }
+            catch (err) {
+                // Startup fatals can race with worker teardown. Waiting for exit keeps
+                // caller shutdown paths deterministic and avoids process-level teardown
+                // races when user code exits immediately after a start() rejection.
+                if (exitDef !== null) {
+                    try {
+                        await exitDef.promise;
+                    }
+                    catch {
+                        // ignore teardown wait failures
+                    }
+                }
+                throw err;
+            }
         },
         async stop() {
             if (disposed)
@@ -655,37 +879,44 @@ export function createNodeBackendInternal(opts = {}) {
             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,
-            });
+            const framePromise = reserveFramePromise(frameSeq);
             if (sabFrameTransport !== null && drawlist.byteLength <= sabFrameTransport.slotBytes) {
                 const slotIndex = acquireSabSlot(sabFrameTransport);
                 if (slotIndex >= 0) {
                     const slotToken = frameSeqToSlotToken(frameSeq);
+                    registerFrameAudit(frameSeq, "requestFrame", FRAME_TRANSPORT_SAB_V1, drawlist, slotIndex, slotToken);
                     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);
+                    if (frameAudit.enabled) {
+                        frameAudit.emit("frame.sab.publish", {
+                            frameSeq,
+                            slotIndex,
+                            slotToken,
+                            byteLen: 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;
                 }
+                if (frameAudit.enabled) {
+                    frameAudit.emit("frame.sab.fallback_transfer", {
+                        frameSeq,
+                        byteLen: drawlist.byteLength,
+                        reason: "no-slot-available",
+                    });
+                }
             }
             // 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);
+            registerFrameAudit(frameSeq, "requestFrame", FRAME_TRANSPORT_TRANSFER_V1, drawlist);
             try {
                 send({
                     type: "frame",
@@ -696,10 +927,21 @@ export function createNodeBackendInternal(opts = {}) {
                 }, [buf]);
             }
             catch (err) {
-                frameAcceptedWaiters.delete(frameSeq);
-                frameCompletionWaiters.delete(frameSeq);
+                releaseFrameReservation(frameSeq);
+                if (frameAudit.enabled) {
+                    frameAudit.emit("frame.transfer.publish_error", {
+                        frameSeq,
+                        detail: safeErr(err).message,
+                    });
+                }
                 return Promise.reject(safeErr(err));
             }
+            if (frameAudit.enabled) {
+                frameAudit.emit("frame.transfer.publish", {
+                    frameSeq,
+                    byteLen: drawlist.byteLength,
+                });
+            }
             return framePromise;
         },
         pollEvents() {
@@ -763,6 +1005,10 @@ export function createNodeBackendInternal(opts = {}) {
             send({ type: "getCaps" });
             return d.promise;
         },
+        async getTerminalProfile() {
+            const caps = await backend.getCaps();
+            return terminalProfileFromNodeEnv(caps);
+        },
     };
     const debug = {
         debugEnable: (config) => enqueueDebug(async () => {
@@ -937,6 +1183,112 @@ export function createNodeBackendInternal(opts = {}) {
             return snapshot;
         }),
     };
-    return Object.assign(backend, { debug, perf });
+    const beginFrameMetrics = {
+        success: 0,
+        fallbackToRequestFrame: 0,
+        readyReclaims: 0,
+    };
+    const beginFrame = sabFrameTransport === null
+        ? null
+        : (minCapacity) => {
+            if (disposed)
+                return null;
+            if (fatal !== null)
+                return null;
+            if (stopRequested || !started || worker === null)
+                return null;
+            const required = typeof minCapacity === "number" && Number.isInteger(minCapacity) && minCapacity > 0
+                ? minCapacity
+                : 0;
+            if (required > sabFrameTransport.slotBytes)
+                return null;
+            const result = acquireSabSlotTracked(sabFrameTransport);
+            if (result.slotIndex < 0) {
+                beginFrameMetrics.fallbackToRequestFrame++;
+                if (frameAudit.enabled) {
+                    frameAudit.emit("frame.beginFrame.fallback", {
+                        reason: "no-slot-available",
+                        metrics: { ...beginFrameMetrics },
+                    });
+                }
+                return null;
+            }
+            if (result.reclaimedReady) {
+                beginFrameMetrics.readyReclaims++;
+            }
+            beginFrameMetrics.success++;
+            const slotIndex = result.slotIndex;
+            const slotOffset = slotIndex * sabFrameTransport.slotBytes;
+            const buf = sabFrameTransport.dataBytes.subarray(slotOffset, slotOffset + sabFrameTransport.slotBytes);
+            let finalized = false;
+            return {
+                buf,
+                commit: (byteLen) => {
+                    if (finalized) {
+                        return Promise.reject(new Error("NodeBackend: beginFrame writer already finalized"));
+                    }
+                    finalized = true;
+                    if (disposed) {
+                        Atomics.store(sabFrameTransport.tokens, slotIndex, 0);
+                        Atomics.store(sabFrameTransport.states, slotIndex, FRAME_SAB_SLOT_STATE_FREE);
+                        return Promise.reject(new Error("NodeBackend: disposed"));
+                    }
+                    if (fatal !== null) {
+                        Atomics.store(sabFrameTransport.tokens, slotIndex, 0);
+                        Atomics.store(sabFrameTransport.states, slotIndex, FRAME_SAB_SLOT_STATE_FREE);
+                        return Promise.reject(fatal);
+                    }
+                    if (stopRequested || !started || worker === null) {
+                        Atomics.store(sabFrameTransport.tokens, slotIndex, 0);
+                        Atomics.store(sabFrameTransport.states, slotIndex, FRAME_SAB_SLOT_STATE_FREE);
+                        return Promise.reject(new Error("NodeBackend: stopped"));
+                    }
+                    if (!Number.isInteger(byteLen) ||
+                        byteLen < 0 ||
+                        byteLen > sabFrameTransport.slotBytes) {
+                        Atomics.store(sabFrameTransport.tokens, slotIndex, 0);
+                        Atomics.store(sabFrameTransport.states, slotIndex, FRAME_SAB_SLOT_STATE_FREE);
+                        return Promise.reject(new Error("NodeBackend: beginFrame commit byteLen out of range"));
+                    }
+                    const frameSeq = nextFrameSeq++;
+                    const framePromise = reserveFramePromise(frameSeq);
+                    const slotToken = frameSeqToSlotToken(frameSeq);
+                    registerFrameAudit(frameSeq, "beginFrame", FRAME_TRANSPORT_SAB_V1, buf.subarray(0, byteLen), slotIndex, slotToken);
+                    Atomics.store(sabFrameTransport.tokens, slotIndex, slotToken);
+                    Atomics.store(sabFrameTransport.states, slotIndex, FRAME_SAB_SLOT_STATE_READY);
+                    publishSabFrame(sabFrameTransport, frameSeq, slotIndex, slotToken, byteLen);
+                    if (frameAudit.enabled) {
+                        frameAudit.emit("frame.beginFrame.publish", {
+                            frameSeq,
+                            slotIndex,
+                            slotToken,
+                            byteLen,
+                            reclaimedReady: result.reclaimedReady,
+                            metrics: { ...beginFrameMetrics },
+                        });
+                    }
+                    Atomics.notify(sabFrameTransport.controlHeader, FRAME_SAB_CONTROL_PUBLISHED_SEQ_WORD, 1);
+                    return framePromise;
+                },
+                abort: () => {
+                    if (finalized)
+                        return;
+                    finalized = true;
+                    if (frameAudit.enabled) {
+                        frameAudit.emit("frame.beginFrame.abort", {
+                            slotIndex,
+                        });
+                    }
+                    Atomics.store(sabFrameTransport.tokens, slotIndex, 0);
+                    Atomics.store(sabFrameTransport.states, slotIndex, FRAME_SAB_SLOT_STATE_FREE);
+                },
+            };
+        };
+    return attachBackendMarkers(Object.assign(backend, { debug, perf }), {
+        requestedDrawlistVersion,
+        maxEventBytes,
+        fpsCap,
+        beginFrame,
+    });
 }
 //# sourceMappingURL=nodeBackend.js.map