@downdraft/engine 0.2.0 → 0.3.1

package/dist/core/src/render/game-renderer.js

@@ -6,7 +6,7 @@
 // logic through callback hooks.
 // ============================================================================
 import { UIInputRouter } from "../input/ui-router.js";
-import { getHostCapabilities, getNativeHost } from "../platform/runtime.js";
+import { getNativeHost } from "../platform/runtime.js";
 import { TelemetryCollector } from "../telemetry/collector.js";
 import { GPUProfiler } from "../telemetry/gpu-profiler.js";
 import { GPUResourceTracker } from "../telemetry/gpu-resource-tracker.js";
@@ -42,6 +42,9 @@ export class GameRenderer {
     uiInputRouter = null;
     /** Screen-space compositors (html-ui panels etc.) drawn in the UI pass. */
     uiCompositors = new Set();
+    /** uiCompositors as a pre-sorted array — rebuilt on add/remove so the
+     *  frame loop doesn't spread+sort the set every frame. */
+    uiCompositorOrder = [];
     // Render loop state
     running = false;
     deviceLost = false;
@@ -75,11 +78,22 @@ export class GameRenderer {
     frameCtx = null;
     // Depth texture cache (used when the graph does not own depth)
     // LRU: Map insertion order = access order (delete + re-set on access).
+    // Numeric key packs (w,h) — a `${w}x${h}` string key allocated a fresh
+    // string per lookup per viewport per frame.
     depthTextures = new Map();
     depthTextureCacheSize;
     // Frame stats
     frameDrawCalls = 0;
     frameTriangles = 0;
+    // Per-frame submit interception: while non-null, queue.submit() calls
+    // (game callbacks, render-target providers, helpers) append their buffers
+    // here in call order instead of crossing into wgpu — the whole frame then
+    // lands in ONE queue.submit at end-of-frame. Games legitimately submit
+    // inside afterFrame callbacks (2D renderers, overlays), so folding the UI
+    // composite into the main batch requires capturing those submits rather
+    // than submitting early or reordering.
+    frameSubmitSink = null;
+    submitInterceptorDevice = null;
     // Callbacks
     callbacks = {};
     // Offscreen mode (set by game for postprocessing)
@@ -150,6 +164,7 @@ export class GameRenderer {
                 return false;
             }
             this.device = borrowedDevice ?? await this.requestDeviceFromAdapter(adapter);
+            this.installQueueSubmitInterceptor(this.device);
             this.adapter = adapter;
             // The host configured the surface with its own usage set at creation —
             // reconfiguring here would tear down the swapchain and race the host's
@@ -214,8 +229,16 @@ export class GameRenderer {
                 setViewportCount: (count) => this.setViewportCount(count),
                 getUIInputRouter: () => this.uiInputRouter,
                 registerUiCompositor: (c) => {
+                    const isNew = !this.uiCompositors.has(c);
                     this.uiCompositors.add(c);
-                    return () => this.uiCompositors.delete(c);
+                    if (isNew) {
+                        this.uiCompositorOrder = [...this.uiCompositors].sort((a, b) => (a.order ?? 0) - (b.order ?? 0));
+                    }
+                    return () => {
+                        if (this.uiCompositors.delete(c)) {
+                            this.uiCompositorOrder = [...this.uiCompositors].sort((a, b) => (a.order ?? 0) - (b.order ?? 0));
+                        }
+                    };
                 },
             });
             // Initial viewport layout
@@ -328,6 +351,7 @@ export class GameRenderer {
             const device = await this.requestDeviceFromAdapter(adapter);
             device.lost.then((info) => this.handleDeviceLost(info));
             this.device = device;
+            this.installQueueSubmitInterceptor(device);
             this.adapter = adapter;
             installShaderValidationGuard(device);
             this.gpuResourceTracker = new GPUResourceTracker();
@@ -381,17 +405,15 @@ export class GameRenderer {
      */
     setResolutionScale(scale) {
         this.resolutionScale = Math.max(0.25, Math.min(1, scale));
-        if (!getHostCapabilities().hasDom) {
-            // On the native host the swapchain extent must equal the window's
-            // real size — wgpu compares the configured size against the surface's
-            // currentExtent at acquire time and returns Outdated forever when
-            // they differ. Shrinking canvas.width/height would also corrupt
-            // clientWidth (UI layout + input coords). Resolution scaling needs
-            // an offscreen-render + upscale path to work here; for now it is a
-            // no-op rather than a brick.
-            if (this.resolutionScale < 1) {
-                log.warn("game-renderer", "resolutionScale is not supported on the native surface (swapchain must match the window size) — ignoring");
-            }
+        // On the native host the swapchain extent must equal the window's
+        // real size — wgpu compares the configured size against the surface's
+        // currentExtent at acquire time and returns Outdated forever when
+        // they differ. Shrinking canvas.width/height would also corrupt
+        // clientWidth (UI layout + input coords). Resolution scaling needs
+        // an offscreen-render + upscale path to work here; for now it is a
+        // no-op rather than a brick.
+        if (this.resolutionScale < 1) {
+            log.warn("game-renderer", "resolutionScale is not supported on the native surface (swapchain must match the window size) — ignoring");
         }
         if (this.lastCssW > 0)
             this.onResize(this.lastCssW, this.lastCssH, this.lastRawDpr);
@@ -407,7 +429,7 @@ export class GameRenderer {
         // performance knob when fill rate is a concern. On native the
         // swapchain is window-sized (see setResolutionScale) so the scale is
         // never applied to the backing store.
-        const cappedDpr = dpr * (getHostCapabilities().hasDom ? this.resolutionScale : 1);
+        const cappedDpr = dpr;
         this.dpr = cappedDpr;
         const w = Math.round(cssWidth * cappedDpr);
         const h = Math.round(cssHeight * cappedDpr);
@@ -563,14 +585,40 @@ export class GameRenderer {
         }
         catch (err) {
             log.error("game-renderer", `Render loop error: ${err.message}\n${err.stack}`);
-            if (this.device?.lost) {
-                this.device.lost.then((info) => {
-                    this.handleDeviceLost(info);
-                });
-            }
+            // No per-error device.lost.then here: the device already has exactly
+            // one lost subscription (init + reinit paths), and on native each
+            // .lost access mints a fresh promise — per-error attaches accumulated
+            // duplicate watchers during an error storm.
         }
         this.scheduleRender();
     };
+    /**
+     * Redirect queue.submit() into frameSubmitSink while a frame is in
+     * flight. Submission order is preserved — buffers land in the sink in
+     * the order submit() was called — so mid-frame submits (uploads in
+     * beforeFrame, a game's afterFrame pass, endFrame hooks) still execute
+     * ahead of work recorded later, just inside the single end-of-frame
+     * queue.submit rather than as extra queue-lock + driver calls.
+     */
+    installQueueSubmitInterceptor(device) {
+        if (this.submitInterceptorDevice === device)
+            return;
+        this.submitInterceptorDevice = device;
+        const queue = device.queue;
+        if (queue.__ddSubmitIntercepted)
+            return;
+        queue.__ddSubmitIntercepted = true;
+        const origSubmit = queue.submit.bind(queue);
+        queue.submit = (commandBuffers) => {
+            const sink = this.frameSubmitSink;
+            if (!sink) {
+                origSubmit(commandBuffers);
+                return;
+            }
+            for (const cb of commandBuffers)
+                sink.push(cb);
+        };
+    }
     renderFrame() {
         const now = performance.now();
         // Frame rate limiter: phase accumulator (skip during XR — XR drives its own cadence)
@@ -615,6 +663,14 @@ export class GameRenderer {
         // simulation stays responsive. The flag is cleared by recovery code that
         // recreates the invalid resources.
         const gpuError = this.gpuProfiler?.hasUncapturedError() ?? false;
+        // Collect command buffers from all phases and submit once at the end
+        // of the frame — one queue.submit per frame instead of 2-4. The sink
+        // is armed BEFORE beginFrame so submit() calls from hooks and game
+        // callbacks (beforeFrame uploads, afterFrame render passes, the XR
+        // endFrame encoder) are captured in call order into the same batch
+        // rather than crossing into wgpu individually.
+        const frameCommandBuffers = [];
+        this.frameSubmitSink = frameCommandBuffers;
         // XR render target provider beginFrame hook
         if (this.renderTargetProvider && !gpuError) {
             this.renderTargetProvider.beginFrame();
@@ -625,9 +681,6 @@ export class GameRenderer {
         if (offscreen && useOffscreen && offscreen.ensureTargets && !gpuError) {
             offscreen.ensureTargets(this.canvas.width, this.canvas.height);
         }
-        // Collect command buffers from all phases and submit once at the end
-        // (reduces CPU→GPU sync points from 3+ per frame to 1).
-        const frameCommandBuffers = [];
         if (!gpuError) {
             // 2D mode with viewportCount=0: clear the canvas if a clearColor is
             // configured, then let the afterFrame callback do custom rendering.
@@ -674,19 +727,6 @@ export class GameRenderer {
         if (passMailbox) {
             frameCommandBuffers.push(...passMailbox.drain("preSubmit"));
         }
-        // Submit all command buffers for this frame in a single queue.submit() call
-        if (frameCommandBuffers.length > 0) {
-            this.device.queue.submit(frameCommandBuffers);
-        }
-        // Read GPU timer results asynchronously (1-frame latency).
-        // Must be called AFTER queue.submit() — readGpuTimers() calls mapAsync on
-        // the read buffer, and a mapped/mapping-pending buffer cannot be used in a
-        // submitted command buffer (the copy-to-readBuffer was encoded above).
-        if (this.gpuProfiler) {
-            this.gpuProfiler.readGpuTimers().then(() => {
-                // Results available for next frame
-            }).catch(() => { });
-        }
         // Record telemetry
         if (this.telemetryCollector) {
             this.telemetryCollector.recordFrame(dt * 1000);
@@ -721,42 +761,72 @@ export class GameRenderer {
             this.frameDrawCalls = 0;
             this.frameTriangles = 0;
         }
-        // XR render target provider endFrame hook (skip on GPU error)
-        if (!gpuError && this.renderTargetProvider && this.device) {
-            this.renderTargetProvider.endFrame(this.device.createCommandEncoder());
+        try {
+            // XR render target provider endFrame hook (skip on GPU error). Its
+            // submits are captured by frameSubmitSink and join the batch.
+            if (!gpuError && this.renderTargetProvider && this.device) {
+                this.renderTargetProvider.endFrame(this.device.createCommandEncoder());
+            }
+            // After frame callback — game submits here append to the batch in
+            // order, still ahead of the UI composite below.
+            this.callbacks.afterFrame?.(dt, this.elapsedTime);
+            this.rendererModuleHost?.dispatchFrame("afterFrame", dt, this.elapsedTime);
+            // Composite registered screen-space UI (html-ui panels) on top of the
+            // final image (skip on GPU error to avoid cascade). This must run AFTER
+            // afterFrame — 2D games (viewportCount=0) do their custom rendering in
+            // the afterFrame callback, so drawing UI earlier would put it underneath
+            // their clear pass. The texture comes from peek: a frame the game
+            // skipped must not be started just to draw UI on a blank swapchain.
+            if (!gpuError && this.device && this.context) {
+                const compositors = this.uiCompositorOrder.filter((c) => c.hasContent());
+                const uiCanvasView = compositors.length > 0
+                    ? this.getFrameSurfaceTexture()?.createView()
+                    : undefined;
+                if (uiCanvasView) {
+                    const uiEncoder = this.device.createCommandEncoder();
+                    const uiPass = uiEncoder.beginRenderPass({
+                        colorAttachments: [{
+                                view: uiCanvasView,
+                                clearValue: { r: 0, g: 0, b: 0, a: 0 },
+                                loadOp: "load",
+                                storeOp: "store",
+                            }],
+                    });
+                    // Panel rects are CSS px — pass the CSS surface size so
+                    // rect/surface maps correctly on HiDPI displays (canvas.width is
+                    // physical px; identical where scaleFactor=1).
+                    compositors.forEach((c) => { c.render(uiPass, this.canvas.clientWidth, this.canvas.clientHeight); });
+                    uiPass.end();
+                    // "preUi" slot — worker passes ordered ahead of the UI-composite
+                    // buffer inside the end-of-frame submit.
+                    frameCommandBuffers.push(...(passMailbox?.drain("preUi") ?? []), uiEncoder.finish());
+                }
+            }
         }
-        // After frame callback
-        this.callbacks.afterFrame?.(dt, this.elapsedTime);
-        this.rendererModuleHost?.dispatchFrame("afterFrame", dt, this.elapsedTime);
-        // Composite registered screen-space UI (html-ui panels) on top of the
-        // final image (skip on GPU error to avoid cascade). This must run AFTER
-        // afterFrame — 2D games (viewportCount=0) do their custom rendering in
-        // the afterFrame callback, so drawing UI earlier would put it underneath
-        // their clear pass.
-        if (!gpuError && this.device && this.context) {
-            const compositors = [...this.uiCompositors]
-                .filter((c) => c.hasContent())
-                .sort((a, b) => (a.order ?? 0) - (b.order ?? 0));
-            const uiCanvasView = compositors.length > 0
-                ? this.getSurfaceTexture()?.createView()
-                : undefined;
-            if (uiCanvasView) {
-                const uiEncoder = this.device.createCommandEncoder();
-                const uiPass = uiEncoder.beginRenderPass({
-                    colorAttachments: [{
-                            view: uiCanvasView,
-                            clearValue: { r: 0, g: 0, b: 0, a: 0 },
-                            loadOp: "load",
-                            storeOp: "store",
-                        }],
-                });
-                compositors.forEach((c) => { c.render(uiPass, this.canvas.width, this.canvas.height); });
-                uiPass.end();
-                // "preUi" slot — worker passes ordered ahead of the UI-composite
-                // submit so their output is visible to the compositor this frame.
-                this.device.queue.submit([...(passMailbox?.drain("preUi") ?? []), uiEncoder.finish()]);
+        finally {
+            // End of frame: disarm the submit sink and flush everything recorded
+            // this frame — engine passes, captured callback submits, mailbox
+            // passes, the UI composite — in a single queue.submit(). Runs even on
+            // a callback throw so already-recorded work still lands.
+            this.frameSubmitSink = null;
+            if (frameCommandBuffers.length > 0 && this.device) {
+                try {
+                    this.device.queue.submit(frameCommandBuffers);
+                }
+                catch (err) {
+                    log.error("game-renderer", `queue.submit failed: ${err.message ?? err}`);
+                }
             }
         }
+        // Read GPU timer results asynchronously (1-frame latency).
+        // Must be called AFTER queue.submit() — readGpuTimers() calls mapAsync on
+        // the read buffer, and a mapped/mapping-pending buffer cannot be used in a
+        // submitted command buffer (the copy-to-readBuffer was encoded above).
+        if (this.gpuProfiler) {
+            this.gpuProfiler.readGpuTimers().then(() => {
+                // Results available for next frame
+            }).catch(() => { });
+        }
         // Present the surface (native wgpu requires explicit presentation;
         // in browsers this is automatic at the end of the frame). Must be last —
         // all submissions targeting the surface texture happen above.
@@ -785,6 +855,29 @@ export class GameRenderer {
             return null;
         }
     }
+    /**
+     * The surface texture already acquired for the in-flight frame, or null
+     * when nothing has acquired one yet. End-of-frame overlays (the UI
+     * composite) use this so they join a frame rather than start one: on
+     * hosts with frame retention (native), acquiring here would fabricate a
+     * frame the game deliberately skipped (dirty-tracking) and present the
+     * overlay over a blank swapchain image — a full-screen flash. Falls
+     * back to acquiring on contexts without peek (DOM semantics:
+     * getCurrentTexture is idempotent within a frame and present is
+     * implicit, so there is nothing to defeat).
+     */
+    getFrameSurfaceTexture() {
+        const peek = this.context?.peekCurrentTexture;
+        if (typeof peek === "function") {
+            try {
+                return peek.call(this.context) ?? null;
+            }
+            catch {
+                return null;
+            }
+        }
+        return this.getSurfaceTexture();
+    }
     renderViewport(viewportIdx, dt, offscreen) {
         if (!this.device || !this.context)
             return null;
@@ -951,7 +1044,7 @@ export class GameRenderer {
     createDepthTexture(w, h) {
         if (!this.device)
             throw new Error("No device");
-        const key = `${w}x${h}`;
+        const key = w * 65536 + h;
         let tex = this.depthTextures.get(key);
         if (tex) {
             // LRU: move to most-recently-used by re-inserting.
@@ -1030,12 +1123,10 @@ export class GameRenderer {
      * this helper only runs the compositors.
      */
     renderScreenUiCompositors() {
-        const compositors = [...this.uiCompositors]
-            .filter((c) => c.hasContent())
-            .sort((a, b) => (a.order ?? 0) - (b.order ?? 0));
+        const compositors = this.uiCompositorOrder.filter((c) => c.hasContent());
         if (compositors.length === 0 || !this.device || !this.context)
             return;
-        const canvasView = this.getSurfaceTexture()?.createView();
+        const canvasView = this.getFrameSurfaceTexture()?.createView();
         if (!canvasView)
             return;
         const uiEncoder = this.device.createCommandEncoder();
@@ -1047,7 +1138,8 @@ export class GameRenderer {
                     storeOp: "store",
                 }],
         });
-        compositors.forEach((c) => { c.render(uiPass, this.canvas.width, this.canvas.height); });
+        // Panel rects are CSS px — see the main UI composite block above.
+        compositors.forEach((c) => { c.render(uiPass, this.canvas.clientWidth, this.canvas.clientHeight); });
         uiPass.end();
         this.device.queue.submit([uiEncoder.finish()]);
     }

package/dist/core/src/render/index.js

@@ -57,7 +57,6 @@ export { PipelineCache } from "./pipeline.js";
 export { RenderPass } from "./render-pass.js";
 export { RendererInputBusImpl } from "./renderer-input-bus.js";
 export { RendererModuleHost } from "./renderer-module-host.js";
-export { SabCanvasOverlay } from "./sab-canvas-overlay.js";
 export { clearShaderValidationDedup, createValidatedShaderModule, createValidatedShaderModuleAsync, installShaderValidationGuard } from "./shader-validator.js";
 export { CSM_SHADER_CHUNK, POINT_SHADOW_SHADER_CHUNK, SPOT_SHADOW_SHADER_CHUNK } from "./shaders/shadow-chunks.js";
 export { SkyboxRenderer } from "./skybox.js";

package/dist/core/src/render/input-manager.js

@@ -58,9 +58,9 @@ export class InputManager {
                     this.tryLockPointer();
                 }
             }));
-            add(document, "pointerlockchange", (() => {
+            add(this.canvas, "pointerlockchange", (() => {
                 const wasLocked = this.pointerLocked;
-                this.pointerLocked = document.pointerLockElement === this.canvas;
+                this.pointerLocked = this.canvas.pointerLocked === true;
                 if (this.pointerLocked) {
                     this.pointerLockRetryCount = 0;
                     if (this.pointerLockRetryTimer) {
@@ -76,7 +76,7 @@ export class InputManager {
                     this.mouseDelta.dy = 0;
                 }
             }));
-            add(document, "pointerlockerror", (() => {
+            add(this.canvas, "pointerlockerror", (() => {
                 // No action needed — tryLockPointer's fallback timer will retry.
             }));
         }
@@ -150,10 +150,10 @@ export class InputManager {
                 e.preventDefault();
             }
         }), { passive: false });
-        // Use document-level mouseleave: a sibling canvas stacked above (e.g.
-        // sandjongg's tile canvas) would otherwise trigger the canvas's own
-        // mouseleave and break UI hover/pressed state.
-        add(document, "mouseleave", (() => {
+        // Window-level mouseleave: a second interactive canvas stacked above
+        // (e.g. sandjongg's tile canvas) would otherwise trigger the canvas's
+        // own mouseleave and break UI hover/pressed state.
+        add(window, "mouseleave", (() => {
             this.uiInputRouter?.handlePointerLeave();
         }));
         add(this.canvas, "contextmenu", ((e) => {

package/dist/core/src/render/renderer-module-host.js

@@ -50,8 +50,8 @@ export class RendererModuleHost {
         this.inputBus = new RendererInputBusImpl(canvas);
     }
     /**
-     * Inject the DevTools API so renderer plugins can self-register debug
-     * panels via `ctx.devtools.registerPanel(...)` during their `register()`.
+     * Inject the DevTools API so renderer plugins can self-register data
+     * feeds via `ctx.devtools.registerDataFeed(...)` during their `register()`.
      */
     setDevToolsAPI(api) {
         this._devtools = api;
@@ -531,8 +531,6 @@ export class RendererModuleHost {
 }
 // No-op DevTools API stub — used when setDevToolsAPI() hasn't been called.
 const NoopRendererDevToolsAPI = {
-    registerPanel: () => { },
-    registerOverlayToggle: () => { },
     registerDataFeed: () => { },
     registerCommand: () => { },
     registerSABStat: () => { },

package/dist/core/src/sab/grid-buffer.js

@@ -46,6 +46,31 @@ export class GridReader {
     hasChanged(lastSeen) {
         return this.getSequence() !== lastSeen;
     }
+    /**
+     * True while the writer holds an open write window (sequence is odd).
+     * Readers can use this to cheaply defer sync work past a publish.
+     */
+    isWriteInProgress() {
+        return (Atomics.load(this.seqArr, 0) & 1) !== 0;
+    }
+    /**
+     * Run `fn` against a consistent snapshot of the channel. The sequence
+     * word is a seqlock: odd while the writer is publishing, even when the
+     * data is stable. The read is retried while the word is odd or changes
+     * mid-read; after maxRetries it returns whatever the last attempt read
+     * rather than starving the reader (writers publish every tick).
+     */
+    readConsistent(fn, maxRetries = 64) {
+        for (let i = 0; i < maxRetries; i++) {
+            const s1 = Atomics.load(this.seqArr, 0);
+            if ((s1 & 1) === 0) {
+                const out = fn();
+                if (Atomics.load(this.seqArr, 0) === s1)
+                    return out;
+            }
+        }
+        return fn();
+    }
     snapshot() {
         const data = {};
         data["sequence"] = this.getSequence();
@@ -67,6 +92,8 @@ export class GridWriter {
     layers;
     seqArr;
     layout;
+    /** True while a beginWrite() window is open (sequence is odd). */
+    writeOpen = false;
     constructor(sab, layout) {
         this.layout = layout;
         this.header = createHeaderViews(sab, layout.header.size);
@@ -82,9 +109,34 @@ export class GridWriter {
         this.header.u32[this.layout.header.magicIndex] = this.layout.magic;
         this.header.u32[this.layout.header.versionIndex] = this.layout.version;
     }
-    bumpSequence() {
+    /**
+     * Open a write window — marks the sequence word odd so readers know a
+     * publish is in progress. Idempotent so mutating paths can call it
+     * unconditionally.
+     */
+    beginWrite() {
+        if (this.writeOpen)
+            return;
+        this.writeOpen = true;
         Atomics.add(this.seqArr, 0, 1);
     }
+    /** Close the write window opened by beginWrite() — sequence back to even. */
+    endWrite() {
+        if (!this.writeOpen)
+            return;
+        this.writeOpen = false;
+        Atomics.add(this.seqArr, 0, 1);
+    }
+    /**
+     * Publish a commit. Without an open write window it steps +2 (even→even)
+     * so the sequence always lands on a stable value while still advancing
+     * once per publish; inside a window it closes it (+1, odd→even).
+     */
+    bumpSequence() {
+        const step = this.writeOpen ? 1 : 2;
+        this.writeOpen = false;
+        Atomics.add(this.seqArr, 0, step);
+    }
     getSequence() {
         return Atomics.load(this.seqArr, 0);
     }

package/dist/core/src/sab/record-buffer.js

@@ -47,6 +47,31 @@ export class RecordReader {
     hasChanged(lastSeen) {
         return this.getSequence() !== lastSeen;
     }
+    /**
+     * True while the writer holds an open write window (sequence is odd).
+     * Readers can use this to cheaply defer sync work past a publish.
+     */
+    isWriteInProgress() {
+        return (Atomics.load(this.seqArr, 0) & 1) !== 0;
+    }
+    /**
+     * Run `fn` against a consistent snapshot of the channel. The sequence
+     * word is a seqlock: odd while the writer is publishing, even when the
+     * data is stable. The read is retried while the word is odd or changes
+     * mid-read; after maxRetries it returns whatever the last attempt read
+     * rather than starving the reader (writers publish every tick).
+     */
+    readConsistent(fn, maxRetries = 64) {
+        for (let i = 0; i < maxRetries; i++) {
+            const s1 = Atomics.load(this.seqArr, 0);
+            if ((s1 & 1) === 0) {
+                const out = fn();
+                if (Atomics.load(this.seqArr, 0) === s1)
+                    return out;
+            }
+        }
+        return fn();
+    }
     snapshot() {
         const data = {};
         if (this.layout.fields) {
@@ -73,6 +98,8 @@ export class RecordWriter {
     fields;
     seqArr;
     layout;
+    /** True while a beginWrite() window is open (sequence is odd). */
+    writeOpen = false;
     constructor(sab, layout) {
         this.layout = layout;
         this.header = createHeaderViews(sab, layout.header.size);
@@ -88,16 +115,33 @@ export class RecordWriter {
         this.header.u32[this.layout.header.magicIndex] = this.layout.magic;
         this.header.u32[this.layout.header.versionIndex] = this.layout.version;
     }
+    /**
+     * Open a write window — marks the sequence word odd so readers know a
+     * publish is in progress. Idempotent so mutating paths can call it
+     * unconditionally.
+     */
     beginWrite() {
-        const seq = Atomics.load(this.seqArr, 0);
-        Atomics.store(this.seqArr, 0, seq + 1);
+        if (this.writeOpen)
+            return;
+        this.writeOpen = true;
+        Atomics.add(this.seqArr, 0, 1);
     }
+    /** Close the write window opened by beginWrite() — sequence back to even. */
     endWrite() {
-        // Sequence is incremented in beginWrite() — endWrite() is a no-op
-        // to avoid double incrementing.
+        if (!this.writeOpen)
+            return;
+        this.writeOpen = false;
+        Atomics.add(this.seqArr, 0, 1);
     }
+    /**
+     * Publish a commit. Without an open write window it steps +2 (even→even)
+     * so the sequence always lands on a stable value while still advancing
+     * once per publish; inside a window it closes it (+1, odd→even).
+     */
     bumpSequence() {
-        Atomics.add(this.seqArr, 0, 1);
+        const step = this.writeOpen ? 1 : 2;
+        this.writeOpen = false;
+        Atomics.add(this.seqArr, 0, step);
     }
     getSequence() {
         return Atomics.load(this.seqArr, 0);