@rezi-ui/node 0.1.0-alpha.44 → 0.1.0-alpha.47

package/dist/backend/nodeBackend.d.ts

@@ -25,13 +25,6 @@ export type NodeBackendConfig = Readonly<{
      * remain aligned by construction.
      */
     maxEventBytes?: number;
-    /**
-     * Explicit drawlist version request.
-     *
-     * Defaults to `5` (enables v3 style extensions + v4 canvas + v5 image commands).
-     * Supported versions are `2`-`5`.
-     */
-    drawlistVersion?: 2 | 3 | 4 | 5;
     /**
      * Frame transport mode:
      * - "auto": prefer SAB mailbox transport when available, fallback to transfer.

package/dist/backend/nodeBackend.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"nodeBackend.d.ts","sourceRoot":"","sources":["../../src/backend/nodeBackend.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAGV,YAAY,EAKZ,cAAc,EAGf,MAAM,eAAe,CAAC;AA2CvB,MAAM,MAAM,iBAAiB,GAAG,QAAQ,CAAC;IACvC;;;;;OAKG;IACH,aAAa,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,QAAQ,CAAC;IAC7C;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;OAKG;IACH,eAAe,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAChC;;;;;OAKG;IACH,cAAc,CAAC,EAAE,MAAM,GAAG,UAAU,GAAG,KAAK,CAAC;IAC7C,2CAA2C;IAC3C,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,mDAAmD;IACnD,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B;;;OAGG;IACH,YAAY,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACjD;;;;;;;;OAQG;IACH,gBAAgB,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,QAAQ,CAAC;CAC/C,CAAC,CAAC;AAEH,MAAM,MAAM,uBAAuB,GAAG,QAAQ,CAAC;IAC7C,MAAM,CAAC,EAAE,iBAAiB,CAAC;IAC3B,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B,CAAC,CAAC;AAEH,MAAM,MAAM,uBAAuB,GAAG,QAAQ,CAAC;IAC7C,MAAM,EAAE,QAAQ,CACd,MAAM,CACJ,MAAM,EACN;QACE,KAAK,EAAE,MAAM,CAAC;QACd,GAAG,EAAE,MAAM,CAAC;QACZ,GAAG,EAAE,MAAM,CAAC;QACZ,GAAG,EAAE,MAAM,CAAC;QACZ,GAAG,EAAE,MAAM,CAAC;QACZ,GAAG,EAAE,MAAM,CAAC;QACZ,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;KAC5B,CACF,CACF,CAAC;CACH,CAAC,CAAC;AAEH,MAAM,MAAM,eAAe,GAAG,QAAQ,CAAC;IACrC,YAAY,EAAE,MAAM,OAAO,CAAC,uBAAuB,CAAC,CAAC;CACtD,CAAC,CAAC;AAEH,MAAM,MAAM,WAAW,GAAG,cAAc,GAAG,QAAQ,CAAC;IAAE,KAAK,EAAE,YAAY,CAAC;IAAC,IAAI,EAAE,eAAe,CAAA;CAAE,CAAC,CAAC;AAiRpG,wBAAgB,yBAAyB,CAAC,IAAI,GAAE,uBAA4B,GAAG,WAAW,CAk+BzF"}
+{"version":3,"file":"nodeBackend.d.ts","sourceRoot":"","sources":["../../src/backend/nodeBackend.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAGV,YAAY,EAKZ,cAAc,EAGf,MAAM,eAAe,CAAC;AAkDvB,MAAM,MAAM,iBAAiB,GAAG,QAAQ,CAAC;IACvC;;;;;OAKG;IACH,aAAa,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,QAAQ,CAAC;IAC7C;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;OAKG;IACH,cAAc,CAAC,EAAE,MAAM,GAAG,UAAU,GAAG,KAAK,CAAC;IAC7C,2CAA2C;IAC3C,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,mDAAmD;IACnD,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B;;;OAGG;IACH,YAAY,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACjD;;;;;;;;OAQG;IACH,gBAAgB,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,QAAQ,CAAC;CAC/C,CAAC,CAAC;AAEH,MAAM,MAAM,uBAAuB,GAAG,QAAQ,CAAC;IAC7C,MAAM,CAAC,EAAE,iBAAiB,CAAC;IAC3B,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B,CAAC,CAAC;AAEH,MAAM,MAAM,uBAAuB,GAAG,QAAQ,CAAC;IAC7C,MAAM,EAAE,QAAQ,CACd,MAAM,CACJ,MAAM,EACN;QACE,KAAK,EAAE,MAAM,CAAC;QACd,GAAG,EAAE,MAAM,CAAC;QACZ,GAAG,EAAE,MAAM,CAAC;QACZ,GAAG,EAAE,MAAM,CAAC;QACZ,GAAG,EAAE,MAAM,CAAC;QACZ,GAAG,EAAE,MAAM,CAAC;QACZ,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;KAC5B,CACF,CACF,CAAC;CACH,CAAC,CAAC;AAEH,MAAM,MAAM,eAAe,GAAG,QAAQ,CAAC;IACrC,YAAY,EAAE,MAAM,OAAO,CAAC,uBAAuB,CAAC,CAAC;CACtD,CAAC,CAAC;AAEH,MAAM,MAAM,WAAW,GAAG,cAAc,GAAG,QAAQ,CAAC;IAAE,KAAK,EAAE,YAAY,CAAC;IAAC,IAAI,EAAE,eAAe,CAAA;CAAE,CAAC,CAAC;AA+UpG,wBAAgB,yBAAyB,CAAC,IAAI,GAAE,uBAA4B,GAAG,WAAW,CAwvCzF"}

package/dist/backend/nodeBackend.js

@@ -7,8 +7,9 @@
  * @see docs/backend/native.md
  */
 import { Worker } from "node:worker_threads";
-import { BACKEND_DRAWLIST_VERSION_MARKER, BACKEND_FPS_CAP_MARKER, BACKEND_MAX_EVENT_BYTES_MARKER, BACKEND_RAW_WRITE_MARKER, DEFAULT_TERMINAL_CAPS, FRAME_ACCEPTED_ACK_MARKER, } from "@rezi-ui/core";
-import { ZR_DRAWLIST_VERSION_V5, 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 { BACKEND_BEGIN_FRAME_MARKER, BACKEND_DRAWLIST_VERSION_MARKER, BACKEND_FPS_CAP_MARKER, BACKEND_MAX_EVENT_BYTES_MARKER, BACKEND_RAW_WRITE_MARKER, DEFAULT_TERMINAL_CAPS, FRAME_ACCEPTED_ACK_MARKER, } 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 { applyEmojiWidthPolicy, resolveBackendEmojiWidthPolicy } from "./emojiWidthPolicy.js";
 import { createNodeBackendInlineInternal } from "./nodeBackendInline.js";
@@ -80,19 +81,6 @@ function parsePositiveInt(n) {
         return null;
     return n;
 }
-function parseDrawlistVersion(v) {
-    if (v === undefined)
-        return null;
-    if (v === 2 || v === 3 || v === 4 || v === 5)
-        return v;
-    throw new ZrUiError("ZRUI_INVALID_PROPS", `createNodeBackend config mismatch: drawlistVersion must be one of 2, 3, 4, 5 (got ${String(v)}).`);
-}
-function resolveRequestedDrawlistVersion(config) {
-    const explicitDrawlistVersion = parseDrawlistVersion(config.drawlistVersion);
-    if (explicitDrawlistVersion !== null)
-        return explicitDrawlistVersion;
-    return ZR_DRAWLIST_VERSION_V5;
-}
 function parseBoundedPositiveIntOrThrow(name, value, fallback, max) {
     if (value === undefined)
         return fallback;
@@ -205,6 +193,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);
@@ -212,6 +232,7 @@ 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 = parseBoundedPositiveIntOrThrow("fpsCap", cfg.fpsCap, DEFAULT_FPS_CAP, MAX_SAFE_FPS_CAP);
     const requestedExecutionMode = cfg.executionMode ?? "auto";
@@ -225,7 +246,7 @@ export function createNodeBackendInternal(opts = {}) {
     if (executionMode === "inline") {
         return createNodeBackendInlineInternal(opts);
     }
-    const requestedDrawlistVersion = resolveRequestedDrawlistVersion(cfg);
+    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);
@@ -280,6 +301,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 = [];
@@ -329,10 +351,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;
@@ -343,6 +440,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;
@@ -351,6 +449,7 @@ export function createNodeBackendInternal(opts = {}) {
         }
     }
     function settleCompletedFrame(frameSeq, completedResult) {
+        markCompletedFrame(frameSeq, completedResult);
         const waiter = frameCompletionWaiters.get(frameSeq);
         if (waiter === undefined)
             return;
@@ -361,6 +460,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);
@@ -420,6 +539,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);
@@ -700,6 +826,13 @@ export function createNodeBackendInternal(opts = {}) {
                     ? undefined
                     : { nativeShimModule: opts.nativeShimModule };
                 worker = new Worker(entry, { workerData });
+                if (frameAudit.enabled) {
+                    frameAudit.emit("worker.spawn", {
+                        frameTransport: frameTransportWire.kind,
+                        frameSabSlotCount: frameSabSlotCount,
+                        frameSabSlotBytes: frameSabSlotBytes,
+                    });
+                }
                 exitDef = deferred();
                 worker.on("message", handleWorkerMessage);
                 worker.on("error", (err) => {
@@ -774,37 +907,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",
@@ -815,10 +955,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() {
@@ -1060,6 +1211,107 @@ export function createNodeBackendInternal(opts = {}) {
             return snapshot;
         }),
     };
+    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);
+                },
+            };
+        };
     const out = Object.assign(backend, { debug, perf });
     Object.defineProperties(out, {
         [BACKEND_DRAWLIST_VERSION_MARKER]: {
@@ -1096,6 +1348,14 @@ export function createNodeBackendInternal(opts = {}) {
             configurable: false,
         },
     });
+    if (beginFrame !== null) {
+        Object.defineProperty(out, BACKEND_BEGIN_FRAME_MARKER, {
+            value: beginFrame,
+            writable: false,
+            enumerable: false,
+            configurable: false,
+        });
+    }
     return out;
 }
 //# sourceMappingURL=nodeBackend.js.map