@downdraft/engine 0.2.0 → 0.3.1

package/core/src/render/game-renderer.ts

@@ -9,7 +9,7 @@
 import { UIInputRouter } from "../input/ui-router";
 import type { RendererModule } from "../module/renderer-module";
 import type { RenderSurface, RenderSurfaceContext } from "../platform/render-surface";
-import { getHostCapabilities, getNativeHost } from "../platform/runtime";
+import { getNativeHost } from "../platform/runtime";
 import { TelemetryCollector } from "../telemetry/collector";
 import type { GPUAdapterInfo as GPUAdapterInfoData } from "../telemetry/gpu-profiler";
 import { GPUProfiler, type FrameGraphData, type GPUInfo } from "../telemetry/gpu-profiler";
@@ -233,6 +233,9 @@ export class GameRenderer implements CanvasResizeHandler {
   uiInputRouter: UIInputRouter | null = null;
   /** Screen-space compositors (html-ui panels etc.) drawn in the UI pass. */
   private uiCompositors = new Set<import("../module/renderer-module").ScreenUiCompositor>();
+  /** uiCompositors as a pre-sorted array — rebuilt on add/remove so the
+   *  frame loop doesn't spread+sort the set every frame. */
+  private uiCompositorOrder: import("../module/renderer-module").ScreenUiCompositor[] = [];
 
   // Render loop state
   private running = false;
@@ -272,13 +275,25 @@ export class GameRenderer implements CanvasResizeHandler {
 
   // Depth texture cache (used when the graph does not own depth)
   // LRU: Map insertion order = access order (delete + re-set on access).
-  private depthTextures = new Map<string, GPUTexture>();
+  // Numeric key packs (w,h) — a `${w}x${h}` string key allocated a fresh
+  // string per lookup per viewport per frame.
+  private depthTextures = new Map<number, GPUTexture>();
   private depthTextureCacheSize: number;
 
   // Frame stats
   private frameDrawCalls = 0;
   private 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.
+  private frameSubmitSink: GPUCommandBuffer[] | null = null;
+  private submitInterceptorDevice: GPUDevice | null = null;
+
   // Callbacks
   private callbacks: FrameCallbacks = {};
 
@@ -354,6 +369,7 @@ export class GameRenderer implements CanvasResizeHandler {
         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
@@ -426,8 +442,16 @@ export class GameRenderer implements CanvasResizeHandler {
         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));
+            }
+          };
         },
       });
 
@@ -543,6 +567,7 @@ export class GameRenderer implements CanvasResizeHandler {
       const device = await this.requestDeviceFromAdapter(adapter);
       device.lost.then((info) => this.handleDeviceLost(info));
       this.device = device;
+      this.installQueueSubmitInterceptor(device);
       this.adapter = adapter;
 
       installShaderValidationGuard(device);
@@ -605,17 +630,15 @@ export class GameRenderer implements CanvasResizeHandler {
    */
   setResolutionScale(scale: number): void {
     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);
   }
@@ -632,7 +655,7 @@ export class GameRenderer implements CanvasResizeHandler {
     // 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);
@@ -798,15 +821,39 @@ export class GameRenderer implements CanvasResizeHandler {
       this.renderFrame();
     } catch (err) {
       log.error("game-renderer", `Render loop error: ${(err as Error).message}\n${(err as Error).stack}`);
-      if (this.device?.lost) {
-        this.device.lost.then((info: GPUDeviceLostInfo) => {
-          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.
+   */
+  private installQueueSubmitInterceptor(device: GPUDevice): void {
+    if (this.submitInterceptorDevice === device) return;
+    this.submitInterceptorDevice = device;
+    const queue = device.queue as any;
+    if (queue.__ddSubmitIntercepted) return;
+    queue.__ddSubmitIntercepted = true;
+    const origSubmit: GPUQueue["submit"] = queue.submit.bind(queue);
+    queue.submit = (commandBuffers: Iterable<GPUCommandBuffer>) => {
+      const sink = this.frameSubmitSink;
+      if (!sink) {
+        origSubmit(commandBuffers);
+        return;
+      }
+      for (const cb of commandBuffers) sink.push(cb);
+    };
+  }
+
   private renderFrame(): void {
     const now = performance.now();
 
@@ -856,6 +903,15 @@ export class GameRenderer implements CanvasResizeHandler {
     // 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: GPUCommandBuffer[] = [];
+    this.frameSubmitSink = frameCommandBuffers;
+
     // XR render target provider beginFrame hook
     if (this.renderTargetProvider && !gpuError) {
       this.renderTargetProvider.beginFrame();
@@ -869,9 +925,6 @@ export class GameRenderer implements CanvasResizeHandler {
       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: GPUCommandBuffer[] = [];
     if (!gpuError) {
       // 2D mode with viewportCount=0: clear the canvas if a clearColor is
       // configured, then let the afterFrame callback do custom rendering.
@@ -922,21 +975,6 @@ export class GameRenderer implements CanvasResizeHandler {
       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);
@@ -975,43 +1013,72 @@ export class GameRenderer implements CanvasResizeHandler {
       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
-    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" as GPULoadOp,
-            storeOp: "store" as GPUStoreOp,
-          }],
-        });
-        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()]);
+      // 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" as GPULoadOp,
+              storeOp: "store" as GPUStoreOp,
+            }],
+          });
+          // 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());
+        }
       }
+    } 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 as Error).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;
@@ -1043,6 +1110,25 @@ export class GameRenderer implements CanvasResizeHandler {
     }
   }
 
+  /**
+   * 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).
+   */
+  private getFrameSurfaceTexture(): GPUTexture | null {
+    const peek = (this.context as { peekCurrentTexture?: () => GPUTexture | null } | null)?.peekCurrentTexture;
+    if (typeof peek === "function") {
+      try { return peek.call(this.context) ?? null; } catch { return null; }
+    }
+    return this.getSurfaceTexture();
+  }
+
   private renderViewport(viewportIdx: number, dt: number, offscreen: OffscreenMode | null): GPUCommandBuffer | null {
     if (!this.device || !this.context) return null;
 
@@ -1220,7 +1306,7 @@ export class GameRenderer implements CanvasResizeHandler {
 
   private createDepthTexture(w: number, h: number): GPUTextureView {
     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.
@@ -1314,11 +1400,9 @@ export class GameRenderer implements CanvasResizeHandler {
    * this helper only runs the compositors.
    */
   protected renderScreenUiCompositors(): void {
-    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();
     const uiPass = uiEncoder.beginRenderPass({
@@ -1329,7 +1413,8 @@ export class GameRenderer implements CanvasResizeHandler {
         storeOp: "store" as GPUStoreOp,
       }],
     });
-    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/core/src/render/index.ts

@@ -111,8 +111,6 @@ export type { FrameGraphBuilder } from "./render-pass";
 export { RendererInputBusImpl } from "./renderer-input-bus";
 export { RendererModuleHost } from "./renderer-module-host";
 export type { RendererModuleHostCallbacks } from "./renderer-module-host";
-export { SabCanvasOverlay } from "./sab-canvas-overlay";
-export type { SabCanvasOverlayOptions } from "./sab-canvas-overlay";
 export { clearShaderValidationDedup, createValidatedShaderModule, createValidatedShaderModuleAsync, installShaderValidationGuard } from "./shader-validator";
 export { CSM_SHADER_CHUNK, POINT_SHADOW_SHADER_CHUNK, SPOT_SHADOW_SHADER_CHUNK } from "./shaders/shadow-chunks";
 export { SkyboxRenderer } from "./skybox";

package/core/src/render/input-manager.ts

@@ -79,9 +79,9 @@ export class InputManager {
         }
       }) as EventListener);
 
-      add(document, "pointerlockchange", (() => {
+      add(this.canvas, "pointerlockchange", (() => {
         const wasLocked = this.pointerLocked;
-        this.pointerLocked = (document.pointerLockElement as unknown) === this.canvas;
+        this.pointerLocked = this.canvas.pointerLocked === true;
         if (this.pointerLocked) {
           this.pointerLockRetryCount = 0;
           if (this.pointerLockRetryTimer) {
@@ -97,7 +97,7 @@ export class InputManager {
         }
       }) as EventListener);
 
-      add(document, "pointerlockerror", (() => {
+      add(this.canvas, "pointerlockerror", (() => {
         // No action needed — tryLockPointer's fallback timer will retry.
       }) as EventListener);
     }
@@ -180,10 +180,10 @@ export class InputManager {
       }
     }) as EventListener, { 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();
     }) as EventListener);
 

package/core/src/render/renderer-module-host.ts

@@ -116,8 +116,8 @@ export class RendererModuleHost {
   }
 
   /**
-   * 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: ModuleDevToolsAPI): void {
     this._devtools = api;
@@ -635,8 +635,6 @@ export class RendererModuleHost {
 
 // No-op DevTools API stub — used when setDevToolsAPI() hasn't been called.
 const NoopRendererDevToolsAPI: ModuleDevToolsAPI = {
-  registerPanel: () => {},
-  registerOverlayToggle: () => {},
   registerDataFeed: () => {},
   registerCommand: () => {},
   registerSABStat: () => {},

package/core/src/sab/grid-buffer.ts

@@ -1,5 +1,5 @@
-import type { ChannelLayout, GridLayerLayout, HeaderViews } from "./types";
 import { describeHeaderValidation } from "./errors";
+import type { ChannelLayout, GridLayerLayout, HeaderViews } from "./types";
 
 function createHeaderViews(sab: SharedArrayBuffer, headerSize: number): HeaderViews {
   const u32Length = headerSize / 4;
@@ -66,6 +66,32 @@ export class GridReader {
     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(): boolean {
+    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<T>(fn: () => T, maxRetries = 64): T {
+    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(): Record<string, unknown> {
     const data: Record<string, unknown> = {};
     data["sequence"] = this.getSequence();
@@ -88,6 +114,8 @@ export class GridWriter {
   layers: Record<string, Float32Array | Int32Array | Uint32Array | Float64Array>;
   private seqArr: Int32Array;
   private layout: ChannelLayout;
+  /** True while a beginWrite() window is open (sequence is odd). */
+  private writeOpen = false;
 
   constructor(sab: SharedArrayBuffer, layout: ChannelLayout) {
     this.layout = layout;
@@ -107,10 +135,35 @@ export class GridWriter {
     this.header.u32[this.layout.header.versionIndex] = this.layout.version;
   }
 
-  bumpSequence(): void {
+  /**
+   * 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(): void {
+    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(): void {
+    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(): void {
+    const step = this.writeOpen ? 1 : 2;
+    this.writeOpen = false;
+    Atomics.add(this.seqArr, 0, step);
+  }
+
   getSequence(): number {
     return Atomics.load(this.seqArr, 0);
   }

package/core/src/sab/record-buffer.ts

@@ -67,6 +67,32 @@ export class RecordReader {
     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(): boolean {
+    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<T>(fn: () => T, maxRetries = 64): T {
+    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(): Record<string, unknown> {
     const data: Record<string, unknown> = {};
     if (this.layout.fields) {
@@ -93,6 +119,8 @@ export class RecordWriter {
   fields: Record<string, Float32Array | Int32Array | Uint32Array | Float64Array>;
   private seqArr: Int32Array;
   private layout: ChannelLayout;
+  /** True while a beginWrite() window is open (sequence is odd). */
+  private writeOpen = false;
 
   constructor(sab: SharedArrayBuffer, layout: ChannelLayout) {
     this.layout = layout;
@@ -112,18 +140,33 @@ export class RecordWriter {
     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(): void {
-    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(): void {
-    // 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(): void {
-    Atomics.add(this.seqArr, 0, 1);
+    const step = this.writeOpen ? 1 : 2;
+    this.writeOpen = false;
+    Atomics.add(this.seqArr, 0, step);
   }
 
   getSequence(): number {