@rezi-ui/node 0.1.0-alpha.45 → 0.1.0-alpha.48

package/dist/worker/engineWorker.js

@@ -7,6 +7,7 @@
  */
 import { performance } from "node:perf_hooks";
 import { parentPort, workerData } from "node:worker_threads";
+import { FRAME_AUDIT_NATIVE_ENABLED, FRAME_AUDIT_NATIVE_RING_BYTES, ZR_DEBUG_CAT_DRAWLIST, ZR_DEBUG_CAT_FRAME, ZR_DEBUG_CAT_PERF, ZR_DEBUG_CODE_DRAWLIST_CMD, ZR_DEBUG_CODE_DRAWLIST_EXECUTE, ZR_DEBUG_CODE_DRAWLIST_VALIDATE, ZR_DEBUG_CODE_FRAME_BEGIN, ZR_DEBUG_CODE_FRAME_PRESENT, ZR_DEBUG_CODE_FRAME_RESIZE, ZR_DEBUG_CODE_FRAME_SUBMIT, ZR_DEBUG_CODE_PERF_DIFF_PATH, ZR_DEBUG_CODE_PERF_TIMING, createFrameAuditLogger, drawlistFingerprint, } from "../frameAudit.js";
 import { EVENT_POOL_SIZE, 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_IN_USE, FRAME_SAB_SLOT_STATE_READY, FRAME_TRANSPORT_SAB_V1, FRAME_TRANSPORT_TRANSFER_V1, FRAME_TRANSPORT_VERSION, MAX_POLL_DRAIN_ITERS, } from "./protocol.js";
 import { computeNextIdleDelay, computeTickTiming } from "./tickTiming.js";
 /**
@@ -154,12 +155,42 @@ const DEBUG_HEADER_BYTES = 40;
 const DEBUG_QUERY_MIN_HEADERS_CAP = DEBUG_HEADER_BYTES;
 const DEBUG_QUERY_MAX_HEADERS_CAP = 1 << 20; // 1 MiB
 const NO_RECYCLED_DRAWLISTS = Object.freeze([]);
+const DEBUG_DRAWLIST_RECORD_BYTES = 48;
+const DEBUG_FRAME_RECORD_BYTES = 56;
+const DEBUG_PERF_RECORD_BYTES = 24;
+// Must cover sizeof(zr_diff_telemetry_record_t) (includes native trailing pad).
+const DEBUG_DIFF_PATH_RECORD_BYTES = 64;
+const NATIVE_FRAME_AUDIT_CATEGORY_MASK = (1 << ZR_DEBUG_CAT_DRAWLIST) | (1 << ZR_DEBUG_CAT_FRAME) | (1 << ZR_DEBUG_CAT_PERF);
+function nativeFrameCodeName(code) {
+    if (code === ZR_DEBUG_CODE_FRAME_BEGIN)
+        return "frame.begin";
+    if (code === ZR_DEBUG_CODE_FRAME_SUBMIT)
+        return "frame.submit";
+    if (code === ZR_DEBUG_CODE_FRAME_PRESENT)
+        return "frame.present";
+    if (code === ZR_DEBUG_CODE_FRAME_RESIZE)
+        return "frame.resize";
+    return "frame.unknown";
+}
+function nativePerfPhaseName(phase) {
+    if (phase === 0)
+        return "poll";
+    if (phase === 1)
+        return "submit";
+    if (phase === 2)
+        return "present";
+    return "unknown";
+}
 let engineId = null;
 let running = false;
 let haveSubmittedDrawlist = false;
 let pendingFrame = null;
 let lastConsumedSabPublishedSeq = 0;
 let frameTransport = Object.freeze({ kind: FRAME_TRANSPORT_TRANSFER_V1 });
+const frameAudit = createFrameAuditLogger("worker");
+const frameAuditBySeq = new Map();
+let nativeFrameAuditEnabled = false;
+let nativeFrameAuditNextRecordId = 1n;
 let eventPool = [];
 let discardBuffer = null;
 let droppedSinceLast = 0;
@@ -170,6 +201,284 @@ let idleDelayMs = 0;
 let maxIdleDelayMs = 0;
 let sabWakeArmed = false;
 let sabWakeEpoch = 0;
+function u64FromView(v, offset) {
+    const lo = BigInt(v.getUint32(offset, true));
+    const hi = BigInt(v.getUint32(offset + 4, true));
+    return (hi << 32n) | lo;
+}
+function setFrameAuditMeta(frameSeq, patch) {
+    if (!frameAudit.enabled)
+        return;
+    const prev = frameAuditBySeq.get(frameSeq);
+    const next = {
+        frameSeq,
+        enqueuedAtMs: prev?.enqueuedAtMs ?? Date.now(),
+        transport: prev?.transport ?? FRAME_TRANSPORT_TRANSFER_V1,
+        byteLen: prev?.byteLen ?? 0,
+        ...(prev ?? {}),
+        ...patch,
+    };
+    frameAuditBySeq.set(frameSeq, next);
+}
+function emitFrameAudit(stage, frameSeq, fields = {}) {
+    if (!frameAudit.enabled)
+        return;
+    const meta = frameAuditBySeq.get(frameSeq);
+    frameAudit.emit(stage, {
+        frameSeq,
+        ageMs: meta ? Math.max(0, Date.now() - meta.enqueuedAtMs) : null,
+        ...(meta ?? {}),
+        ...fields,
+    });
+}
+function deleteFrameAudit(frameSeq) {
+    if (!frameAudit.enabled)
+        return;
+    frameAuditBySeq.delete(frameSeq);
+}
+function maybeEnableNativeFrameAudit() {
+    if (!frameAudit.enabled)
+        return;
+    if (!FRAME_AUDIT_NATIVE_ENABLED)
+        return;
+    if (engineId === null)
+        return;
+    let rc = -1;
+    try {
+        rc = native.engineDebugEnable(engineId, {
+            enabled: true,
+            ringCapacity: FRAME_AUDIT_NATIVE_RING_BYTES,
+            minSeverity: 0,
+            categoryMask: NATIVE_FRAME_AUDIT_CATEGORY_MASK,
+            captureRawEvents: false,
+            captureDrawlistBytes: true,
+        });
+    }
+    catch (err) {
+        frameAudit.emit("native.debug.enable_error", { detail: safeDetail(err) });
+        nativeFrameAuditEnabled = false;
+        return;
+    }
+    nativeFrameAuditEnabled = rc >= 0;
+    nativeFrameAuditNextRecordId = 1n;
+    frameAudit.emit("native.debug.enable", {
+        rc,
+        enabled: nativeFrameAuditEnabled,
+        ringCapacity: FRAME_AUDIT_NATIVE_RING_BYTES,
+    });
+}
+function drainNativeFrameAudit(reason) {
+    if (!frameAudit.enabled || !nativeFrameAuditEnabled)
+        return;
+    if (engineId === null)
+        return;
+    const headersCap = DEBUG_HEADER_BYTES * 64;
+    const headersBuf = new Uint8Array(headersCap);
+    const tryReadDebugPayload = (recordId, code, expectedBytes, opts = {}) => {
+        if (engineId === null)
+            return null;
+        const payload = new Uint8Array(expectedBytes);
+        let wrote = 0;
+        try {
+            wrote = native.engineDebugGetPayload(engineId, recordId, payload);
+        }
+        catch (err) {
+            frameAudit.emit("native.debug.payload_error", {
+                reason,
+                recordId: recordId.toString(),
+                code,
+                expectedBytes,
+                detail: safeDetail(err),
+            });
+            return null;
+        }
+        if (wrote <= 0) {
+            frameAudit.emit("native.debug.payload_error", {
+                reason,
+                recordId: recordId.toString(),
+                code,
+                expectedBytes,
+                wrote,
+                detail: "payload read returned non-positive length",
+            });
+            return null;
+        }
+        if (wrote < expectedBytes) {
+            frameAudit.emit("native.debug.payload_error", {
+                reason,
+                recordId: recordId.toString(),
+                code,
+                expectedBytes,
+                wrote,
+                detail: "short payload read",
+            });
+            if (opts.allowPartialOnShortRead !== true) {
+                return null;
+            }
+        }
+        return payload.subarray(0, Math.min(wrote, payload.byteLength));
+    };
+    for (let iter = 0; iter < 8; iter++) {
+        let result;
+        try {
+            result = native.engineDebugQuery(engineId, {
+                minRecordId: nativeFrameAuditNextRecordId,
+                categoryMask: NATIVE_FRAME_AUDIT_CATEGORY_MASK,
+                minSeverity: 0,
+                maxRecords: Math.floor(headersCap / DEBUG_HEADER_BYTES),
+            }, headersBuf);
+        }
+        catch (err) {
+            frameAudit.emit("native.debug.query_error", { reason, detail: safeDetail(err) });
+            return;
+        }
+        const recordsReturned = Number.isInteger(result.recordsReturned) && result.recordsReturned > 0
+            ? Math.min(result.recordsReturned, Math.floor(headersCap / DEBUG_HEADER_BYTES))
+            : 0;
+        if (recordsReturned <= 0)
+            return;
+        let advanced = false;
+        for (let i = 0; i < recordsReturned; i++) {
+            const off = i * DEBUG_HEADER_BYTES;
+            const dv = new DataView(headersBuf.buffer, headersBuf.byteOffset + off, DEBUG_HEADER_BYTES);
+            const recordId = u64FromView(dv, 0);
+            const timestampUs = u64FromView(dv, 8);
+            const frameId = u64FromView(dv, 16);
+            const category = dv.getUint32(24, true);
+            const severity = dv.getUint32(28, true);
+            const code = dv.getUint32(32, true);
+            const payloadSize = dv.getUint32(36, true);
+            if (recordId < nativeFrameAuditNextRecordId) {
+                continue;
+            }
+            if (recordId === 0n && frameId === 0n && category === 0 && code === 0 && payloadSize === 0) {
+                continue;
+            }
+            advanced = true;
+            nativeFrameAuditNextRecordId = recordId + 1n;
+            frameAudit.emit("native.debug.header", {
+                reason,
+                recordId: recordId.toString(),
+                frameId: frameId.toString(),
+                timestampUs: timestampUs.toString(),
+                category,
+                severity,
+                code,
+                payloadSize,
+            });
+            if (code === ZR_DEBUG_CODE_DRAWLIST_CMD && payloadSize > 0) {
+                const cap = Math.min(Math.max(payloadSize, 1), 4096);
+                const view = tryReadDebugPayload(recordId, code, cap, {
+                    allowPartialOnShortRead: true,
+                });
+                if (view === null)
+                    continue;
+                const fp = drawlistFingerprint(view);
+                frameAudit.emit("native.drawlist.payload", {
+                    reason,
+                    recordId: recordId.toString(),
+                    frameId: frameId.toString(),
+                    payloadSize: view.byteLength,
+                    hash32: fp.hash32,
+                    prefixHash32: fp.prefixHash32,
+                    head16: fp.head16,
+                    tail16: fp.tail16,
+                });
+                continue;
+            }
+            if ((code === ZR_DEBUG_CODE_DRAWLIST_VALIDATE || code === ZR_DEBUG_CODE_DRAWLIST_EXECUTE) &&
+                payloadSize >= DEBUG_DRAWLIST_RECORD_BYTES) {
+                const payload = tryReadDebugPayload(recordId, code, DEBUG_DRAWLIST_RECORD_BYTES);
+                if (payload === null)
+                    continue;
+                const dvPayload = new DataView(payload.buffer, payload.byteOffset, DEBUG_DRAWLIST_RECORD_BYTES);
+                frameAudit.emit("native.drawlist.summary", {
+                    reason,
+                    recordId: recordId.toString(),
+                    frameId: u64FromView(dvPayload, 0).toString(),
+                    totalBytes: dvPayload.getUint32(8, true),
+                    cmdCount: dvPayload.getUint32(12, true),
+                    version: dvPayload.getUint32(16, true),
+                    validationResult: dvPayload.getInt32(20, true),
+                    executionResult: dvPayload.getInt32(24, true),
+                    clipStackMaxDepth: dvPayload.getUint32(28, true),
+                    textRuns: dvPayload.getUint32(32, true),
+                    fillRects: dvPayload.getUint32(36, true),
+                });
+                continue;
+            }
+            if ((code === ZR_DEBUG_CODE_FRAME_BEGIN ||
+                code === ZR_DEBUG_CODE_FRAME_SUBMIT ||
+                code === ZR_DEBUG_CODE_FRAME_PRESENT ||
+                code === ZR_DEBUG_CODE_FRAME_RESIZE) &&
+                payloadSize >= DEBUG_FRAME_RECORD_BYTES) {
+                const payload = tryReadDebugPayload(recordId, code, DEBUG_FRAME_RECORD_BYTES);
+                if (payload === null)
+                    continue;
+                const dvPayload = new DataView(payload.buffer, payload.byteOffset, DEBUG_FRAME_RECORD_BYTES);
+                frameAudit.emit("native.frame.summary", {
+                    reason,
+                    recordId: recordId.toString(),
+                    frameId: u64FromView(dvPayload, 0).toString(),
+                    code,
+                    codeName: nativeFrameCodeName(code),
+                    cols: dvPayload.getUint32(8, true),
+                    rows: dvPayload.getUint32(12, true),
+                    drawlistBytes: dvPayload.getUint32(16, true),
+                    drawlistCmds: dvPayload.getUint32(20, true),
+                    diffBytesEmitted: dvPayload.getUint32(24, true),
+                    dirtyLines: dvPayload.getUint32(28, true),
+                    dirtyCells: dvPayload.getUint32(32, true),
+                    damageRects: dvPayload.getUint32(36, true),
+                    usDrawlist: dvPayload.getUint32(40, true),
+                    usDiff: dvPayload.getUint32(44, true),
+                    usWrite: dvPayload.getUint32(48, true),
+                });
+                continue;
+            }
+            if (code === ZR_DEBUG_CODE_PERF_TIMING && payloadSize >= DEBUG_PERF_RECORD_BYTES) {
+                const payload = tryReadDebugPayload(recordId, code, DEBUG_PERF_RECORD_BYTES);
+                if (payload === null)
+                    continue;
+                const dvPayload = new DataView(payload.buffer, payload.byteOffset, DEBUG_PERF_RECORD_BYTES);
+                const phase = dvPayload.getUint32(8, true);
+                frameAudit.emit("native.perf.timing", {
+                    reason,
+                    recordId: recordId.toString(),
+                    frameId: u64FromView(dvPayload, 0).toString(),
+                    phase,
+                    phaseName: nativePerfPhaseName(phase),
+                    usElapsed: dvPayload.getUint32(12, true),
+                    bytesProcessed: dvPayload.getUint32(16, true),
+                });
+                continue;
+            }
+            if (code === ZR_DEBUG_CODE_PERF_DIFF_PATH && payloadSize >= DEBUG_DIFF_PATH_RECORD_BYTES) {
+                const payload = tryReadDebugPayload(recordId, code, DEBUG_DIFF_PATH_RECORD_BYTES);
+                if (payload === null)
+                    continue;
+                const dvPayload = new DataView(payload.buffer, payload.byteOffset, DEBUG_DIFF_PATH_RECORD_BYTES);
+                frameAudit.emit("native.perf.diffPath", {
+                    reason,
+                    recordId: recordId.toString(),
+                    frameId: u64FromView(dvPayload, 0).toString(),
+                    sweepFramesTotal: u64FromView(dvPayload, 8).toString(),
+                    damageFramesTotal: u64FromView(dvPayload, 16).toString(),
+                    scrollAttemptsTotal: u64FromView(dvPayload, 24).toString(),
+                    scrollHitsTotal: u64FromView(dvPayload, 32).toString(),
+                    collisionGuardHitsTotal: u64FromView(dvPayload, 40).toString(),
+                    pathSweepUsed: dvPayload.getUint8(48),
+                    pathDamageUsed: dvPayload.getUint8(49),
+                    scrollOptAttempted: dvPayload.getUint8(50),
+                    scrollOptHit: dvPayload.getUint8(51),
+                    collisionGuardHitsLast: dvPayload.getUint32(52, true),
+                });
+            }
+        }
+        if (!advanced)
+            return;
+    }
+}
 function writeResizeBatchV1(buf, cols, rows) {
     // Batch header (24) + RESIZE record (32) = 56 bytes.
     const totalSize = 56;
@@ -314,6 +623,9 @@ function startTickLoop(fpsCap) {
     armSabFrameWake();
 }
 function fatal(where, code, detail) {
+    if (frameAudit.enabled) {
+        frameAudit.emit("fatal", { where, code, detail });
+    }
     postToMain({ type: "fatal", where, code, detail });
 }
 function shutdownComplete() {
@@ -336,6 +648,8 @@ function releasePendingFrame(frame, expectedSabState) {
 function postFrameStatus(frameSeq, completedResult) {
     if (!Number.isInteger(frameSeq) || frameSeq <= 0)
         return;
+    emitFrameAudit("frame.completed", frameSeq, { completedResult });
+    deleteFrameAudit(frameSeq);
     postToMain({
         type: "frameStatus",
         acceptedSeq: frameSeq,
@@ -347,6 +661,7 @@ function postFrameStatus(frameSeq, completedResult) {
 function postFrameAccepted(frameSeq) {
     if (!Number.isInteger(frameSeq) || frameSeq <= 0)
         return;
+    emitFrameAudit("frame.accepted", frameSeq);
     postToMain({
         type: "frameStatus",
         acceptedSeq: frameSeq,
@@ -405,9 +720,22 @@ function syncPendingSabFrameFromMailbox() {
     if (latest === null)
         return;
     if (pendingFrame !== null) {
+        emitFrameAudit("frame.overwritten", pendingFrame.frameSeq, { reason: "mailbox-latest-wins" });
+        deleteFrameAudit(pendingFrame.frameSeq);
         releasePendingFrame(pendingFrame, FRAME_SAB_SLOT_STATE_READY);
     }
     pendingFrame = latest;
+    setFrameAuditMeta(latest.frameSeq, {
+        transport: latest.transport,
+        byteLen: latest.byteLen,
+        slotIndex: latest.slotIndex,
+        slotToken: latest.slotToken,
+    });
+    emitFrameAudit("frame.mailbox.latest", latest.frameSeq, {
+        slotIndex: latest.slotIndex,
+        slotToken: latest.slotToken,
+        byteLen: latest.byteLen,
+    });
 }
 function destroyEngineBestEffort() {
     const id = engineId;
@@ -425,9 +753,17 @@ function shutdownNow() {
     running = false;
     stopTickLoop();
     if (pendingFrame !== null) {
+        emitFrameAudit("frame.dropped", pendingFrame.frameSeq, { reason: "shutdown" });
+        deleteFrameAudit(pendingFrame.frameSeq);
         releasePendingFrame(pendingFrame, FRAME_SAB_SLOT_STATE_READY);
         pendingFrame = null;
     }
+    if (frameAudit.enabled) {
+        for (const [seq] of frameAuditBySeq.entries()) {
+            emitFrameAudit("frame.dropped", seq, { reason: "shutdown_pending" });
+        }
+        frameAuditBySeq.clear();
+    }
     destroyEngineBestEffort();
     shutdownComplete();
     // Let worker thread exit naturally once handles are cleared.
@@ -454,12 +790,32 @@ function tick() {
     if (pendingFrame !== null) {
         const f = pendingFrame;
         pendingFrame = null;
+        emitFrameAudit("frame.submit.begin", f.frameSeq, {
+            transport: f.transport,
+            byteLen: f.byteLen,
+            ...(f.transport === FRAME_TRANSPORT_SAB_V1
+                ? { slotIndex: f.slotIndex, slotToken: f.slotToken }
+                : {}),
+        });
         let res = -1;
         let sabInUse = false;
         let staleSabFrame = false;
         try {
             if (f.transport === FRAME_TRANSPORT_TRANSFER_V1) {
-                res = native.engineSubmitDrawlist(engineId, new Uint8Array(f.buf, 0, f.byteLen));
+                const view = new Uint8Array(f.buf, 0, f.byteLen);
+                if (frameAudit.enabled) {
+                    const fp = drawlistFingerprint(view);
+                    setFrameAuditMeta(f.frameSeq, {
+                        transport: f.transport,
+                        byteLen: f.byteLen,
+                        hash32: fp.hash32,
+                        prefixHash32: fp.prefixHash32,
+                        cmdCount: fp.cmdCount,
+                        totalSize: fp.totalSize,
+                    });
+                    emitFrameAudit("frame.submit.payload", f.frameSeq, fp);
+                }
+                res = native.engineSubmitDrawlist(engineId, view);
             }
             else {
                 if (frameTransport.kind !== FRAME_TRANSPORT_SAB_V1) {
@@ -487,6 +843,20 @@ function tick() {
                         sabInUse = true;
                         const offset = f.slotIndex * frameTransport.slotBytes;
                         const view = frameTransport.data.subarray(offset, offset + f.byteLen);
+                        if (frameAudit.enabled) {
+                            const fp = drawlistFingerprint(view);
+                            setFrameAuditMeta(f.frameSeq, {
+                                transport: f.transport,
+                                byteLen: f.byteLen,
+                                slotIndex: f.slotIndex,
+                                slotToken: f.slotToken,
+                                hash32: fp.hash32,
+                                prefixHash32: fp.prefixHash32,
+                                cmdCount: fp.cmdCount,
+                                totalSize: fp.totalSize,
+                            });
+                            emitFrameAudit("frame.submit.payload", f.frameSeq, fp);
+                        }
                         res = native.engineSubmitDrawlist(engineId, view);
                     }
                 }
@@ -494,7 +864,9 @@ function tick() {
         }
         catch (err) {
             releasePendingFrame(f, sabInUse ? FRAME_SAB_SLOT_STATE_IN_USE : FRAME_SAB_SLOT_STATE_READY);
+            emitFrameAudit("frame.submit.throw", f.frameSeq, { detail: safeDetail(err) });
             postFrameStatus(f.frameSeq, -1);
+            drainNativeFrameAudit("submit-throw");
             fatal("engineSubmitDrawlist", -1, `engine_submit_drawlist threw: ${safeDetail(err)}`);
             running = false;
             return;
@@ -503,6 +875,8 @@ function tick() {
             // This frame was superseded in the shared mailbox before submit.
             // Keep latest-wins behavior without surfacing a fatal protocol error.
             didFrameWork = true;
+            emitFrameAudit("frame.submit.stale", f.frameSeq, { reason: "slot-token-mismatch" });
+            deleteFrameAudit(f.frameSeq);
             syncPendingSabFrameFromMailbox();
             // Continue with present/event processing on this tick.
         }
@@ -511,6 +885,8 @@ function tick() {
             haveSubmittedDrawlist = haveSubmittedDrawlist || didSubmitDrawlistThisTick;
             didFrameWork = true;
             releasePendingFrame(f, FRAME_SAB_SLOT_STATE_IN_USE);
+            emitFrameAudit("frame.submit.result", f.frameSeq, { submitResult: res });
+            drainNativeFrameAudit("post-submit");
             if (res < 0) {
                 postFrameStatus(f.frameSeq, res);
                 fatal("engineSubmitDrawlist", res, "engine_submit_drawlist failed");
@@ -533,22 +909,31 @@ function tick() {
             pres = native.enginePresent(engineId);
         }
         catch (err) {
+            if (submittedFrameSeq !== null)
+                emitFrameAudit("frame.present.throw", submittedFrameSeq, { detail: safeDetail(err) });
             if (submittedFrameSeq !== null)
                 postFrameStatus(submittedFrameSeq, -1);
+            drainNativeFrameAudit("present-throw");
             fatal("enginePresent", -1, `engine_present threw: ${safeDetail(err)}`);
             running = false;
             return;
         }
         if (pres < 0) {
+            if (submittedFrameSeq !== null)
+                emitFrameAudit("frame.present.result", submittedFrameSeq, { presentResult: pres });
             if (submittedFrameSeq !== null)
                 postFrameStatus(submittedFrameSeq, pres);
+            drainNativeFrameAudit("present-failed");
             fatal("enginePresent", pres, "engine_present failed");
             running = false;
             return;
         }
+        if (submittedFrameSeq !== null)
+            emitFrameAudit("frame.present.result", submittedFrameSeq, { presentResult: pres });
     }
     if (submittedFrameSeq !== null) {
         postFrameStatus(submittedFrameSeq, 0);
+        drainNativeFrameAudit("frame-complete");
     }
     // 3) drain events (bounded)
     const discard = discardBuffer;
@@ -668,6 +1053,9 @@ function onMessage(msg) {
             running = true;
             pendingFrame = null;
             lastConsumedSabPublishedSeq = 0;
+            frameAuditBySeq.clear();
+            nativeFrameAuditEnabled = false;
+            nativeFrameAuditNextRecordId = 1n;
             if (frameTransport.kind === FRAME_TRANSPORT_SAB_V1) {
                 Atomics.store(frameTransport.controlHeader, FRAME_SAB_CONTROL_PUBLISHED_SEQ_WORD, 0);
                 Atomics.store(frameTransport.controlHeader, FRAME_SAB_CONTROL_PUBLISHED_SLOT_WORD, 0);
@@ -697,6 +1085,15 @@ function onMessage(msg) {
             if (shim === null || shim.length === 0) {
                 maybeInjectInitialResize(maxEventBytes);
             }
+            if (frameAudit.enabled) {
+                frameAudit.emit("engine.ready", {
+                    engineId: id,
+                    frameTransport: frameTransport.kind,
+                    maxEventBytes,
+                    fpsCap: parsePositiveInt(msg.config.fpsCap) ?? 60,
+                });
+            }
+            maybeEnableNativeFrameAudit();
             postToMain({ type: "ready", engineId: id });
             const fpsCap = parsePositiveInt(msg.config.fpsCap) ?? 60;
             startTickLoop(fpsCap);
@@ -707,6 +1104,10 @@ function onMessage(msg) {
                 return;
             // latest-wins overwrite for transfer-path fallback.
             if (pendingFrame !== null) {
+                emitFrameAudit("frame.overwritten", pendingFrame.frameSeq, {
+                    reason: "message-latest-wins",
+                });
+                deleteFrameAudit(pendingFrame.frameSeq);
                 releasePendingFrame(pendingFrame, FRAME_SAB_SLOT_STATE_READY);
             }
             const frameTransportTag = msg.transport ?? FRAME_TRANSPORT_TRANSFER_V1;
@@ -742,6 +1143,18 @@ function onMessage(msg) {
                     slotToken: msg.slotToken,
                     byteLen: msg.byteLen,
                 };
+                setFrameAuditMeta(msg.frameSeq, {
+                    transport: FRAME_TRANSPORT_SAB_V1,
+                    byteLen: msg.byteLen,
+                    slotIndex: msg.slotIndex,
+                    slotToken: msg.slotToken,
+                });
+                emitFrameAudit("frame.received", msg.frameSeq, {
+                    transport: FRAME_TRANSPORT_SAB_V1,
+                    byteLen: msg.byteLen,
+                    slotIndex: msg.slotIndex,
+                    slotToken: msg.slotToken,
+                });
             }
             else {
                 if (!(msg.drawlist instanceof ArrayBuffer)) {
@@ -762,6 +1175,21 @@ function onMessage(msg) {
                     buf: msg.drawlist,
                     byteLen: msg.byteLen,
                 };
+                if (frameAudit.enabled) {
+                    const fp = drawlistFingerprint(new Uint8Array(msg.drawlist, 0, msg.byteLen));
+                    setFrameAuditMeta(msg.frameSeq, {
+                        transport: FRAME_TRANSPORT_TRANSFER_V1,
+                        byteLen: msg.byteLen,
+                        hash32: fp.hash32,
+                        prefixHash32: fp.prefixHash32,
+                        cmdCount: fp.cmdCount,
+                        totalSize: fp.totalSize,
+                    });
+                    emitFrameAudit("frame.received", msg.frameSeq, {
+                        transport: FRAME_TRANSPORT_TRANSFER_V1,
+                        ...fp,
+                    });
+                }
             }
             idleDelayMs = tickIntervalMs;
             scheduleTickNow();
@@ -870,6 +1298,15 @@ function onMessage(msg) {
                 fatal("engineDebugEnable", -1, `engine_debug_enable threw: ${safeDetail(err)}`);
                 return;
             }
+            if (frameAudit.enabled) {
+                frameAudit.emit("native.debug.enable.user", {
+                    rc,
+                    captureDrawlistBytes: msg.config.captureDrawlistBytes ?? false,
+                });
+            }
+            nativeFrameAuditEnabled = rc >= 0 && frameAudit.enabled;
+            if (nativeFrameAuditEnabled)
+                nativeFrameAuditNextRecordId = 1n;
             postToMain({ type: "debug:enableResult", result: rc });
             return;
         }
@@ -884,6 +1321,10 @@ function onMessage(msg) {
                 fatal("engineDebugDisable", -1, `engine_debug_disable threw: ${safeDetail(err)}`);
                 return;
             }
+            nativeFrameAuditEnabled = false;
+            if (frameAudit.enabled) {
+                frameAudit.emit("native.debug.disable.user", { rc });
+            }
             postToMain({ type: "debug:disableResult", result: rc });
             return;
         }
@@ -1001,6 +1442,10 @@ function onMessage(msg) {
                 fatal("engineDebugReset", -1, `engine_debug_reset threw: ${safeDetail(err)}`);
                 return;
             }
+            if (frameAudit.enabled && rc >= 0) {
+                nativeFrameAuditNextRecordId = 1n;
+                frameAudit.emit("native.debug.reset", { rc });
+            }
             postToMain({ type: "debug:resetResult", result: rc });
             return;
         }