@downdraft/engine 0.1.2-alpha.5 → 0.3.0

package/core/src/sab/sim-channel.ts

@@ -34,7 +34,7 @@ export const SIM_PLAYER_SLOT_SIZE = 256;
 export const SimChannel = defineChannel({
   name: "game-sim",
   magic: 0x53494d42,
-  version: 1,
+  version: 2,
   mode: "slots",
   header: {
     size: 256,
@@ -76,6 +76,12 @@ export const SimChannel = defineChannel({
       physTimingCcdSolver: { type: "f32" },
       physTimingIslandConstruction: { type: "f32" },
       physTimingUserChanges: { type: "f32" },
+      // Presentation-interpolation timing, stamped by incrementTick().
+      // publishTimeMs is wall-clock epoch ms (timeOrigin + now) so it
+      // compares correctly across the worker/renderer thread boundary —
+      // performance.now() epochs differ per thread.
+      publishTimeMs: { type: "f64" },
+      publishDeltaMs: { type: "f32" },
     },
   },
   sections: [
@@ -131,11 +137,33 @@ export const SimChannel = defineChannel({
         // modifying the core SAB schema.
       },
     },
+    // Previous-publish transforms for renderer-side interpolation. The
+    // writer snapshots pos+rot here before overwriting a slot, and fills
+    // the rest from cur at commit — so prev always equals state(t-1)
+    // and cur equals state(t). Same field layout as ENT/PLR transforms.
+    {
+      name: "entitiesPrev",
+      maxSlots: MAX_ENTITIES,
+      slotSize: 32,
+      fields: {
+        pos: { type: "f32", count: 4 },
+        rot: { type: "f32", count: 4 },
+      },
+    },
+    {
+      name: "playersPrev",
+      maxSlots: MAX_PLAYERS,
+      slotSize: 32,
+      fields: {
+        pos: { type: "f32", count: 4 },
+        rot: { type: "f32", count: 4 },
+      },
+    },
   ],
 });
 
 export const SIM_MAGIC = 0x53494d42;
-export const SIM_VERSION = 1;
+export const SIM_VERSION = 2;
 
 export const SIM_HDR = {
   MAGIC: 0,
@@ -178,6 +206,8 @@ export const SIM_HDR = {
   PHYS_TIMING_CCD_SOLVER: 37,
   PHYS_TIMING_ISLAND_CONSTRUCTION: 38,
   PHYS_TIMING_USER_CHANGES: 39,
+  PUBLISH_TIME_MS: 40,   // f64 — occupies u32 words 40–41
+  PUBLISH_DELTA_MS: 42,
 } as const;
 
 export const ENT = {
@@ -227,6 +257,14 @@ export const PLR_FLAG = {
   GROUNDED: 1 << 9,
 } as const;
 
+// Field offsets inside the entitiesPrev/playersPrev sections. pos holds
+// [x, y, z, w] where w is entity scale / player heading; rot is the
+// quaternion. Matches ENT.POS_*/ENT.ROT_* and PLR.POS_*/PLR.ROT_* layout.
+export const PREV = {
+  POS_X: 0, POS_Y: 1, POS_Z: 2, POS_W: 3,
+  ROT_X: 4, ROT_Y: 5, ROT_Z: 6, ROT_W: 7,
+} as const;
+
 export function allocateSimBuffer(): SharedArrayBuffer {
   return SimChannel.allocate();
 }
@@ -241,11 +279,15 @@ export class SimBufferReader {
   private reader: ReturnType<typeof SimChannel.reader>;
   private entitySlots: ReturnType<typeof SimChannel.reader>["sections"]["entities"];
   private playerSlots: ReturnType<typeof SimChannel.reader>["sections"]["players"];
+  private entityPrevSlots: ReturnType<typeof SimChannel.reader>["sections"]["entitiesPrev"];
+  private playerPrevSlots: ReturnType<typeof SimChannel.reader>["sections"]["playersPrev"];
 
   constructor(sab: SharedArrayBuffer) {
     this.reader = SimChannel.reader(sab);
     this.entitySlots = this.reader.sections.entities;
     this.playerSlots = this.reader.sections.players;
+    this.entityPrevSlots = this.reader.sections.entitiesPrev;
+    this.playerPrevSlots = this.reader.sections.playersPrev;
   }
 
   isValid(): boolean {
@@ -258,6 +300,17 @@ export class SimBufferReader {
 
   getTick(): number { return this.reader.header.u32[SimChannel.offsets.header.tick]; }
   getSequence(): number { return this.reader.getSequence(); }
+  /** True while the sim worker is mid-publish (sequence word is odd). */
+  isWriteInProgress(): boolean { return this.reader.isWriteInProgress(); }
+  /**
+   * Run `fn` against a consistent snapshot of the sim state — retries
+   * while the sim worker is mid-publish or publishes during the read
+   * (seqlock). Wrap per-frame read loops (entity iteration, player slot
+   * reads) in this to avoid torn reads across a sim commit.
+   */
+  readConsistent<T>(fn: () => T, maxRetries?: number): T {
+    return this.reader.readConsistent(fn, maxRetries);
+  }
   getEntityCount(): number { return this.reader.header.u32[SimChannel.offsets.header.entityCount]; }
   getPlayerCount(): number { return this.reader.header.u32[SimChannel.offsets.header.playerCount]; }
   getTimeOfDay(): number { return this.reader.header.f32[SimChannel.offsets.header.timeOfDay]; }
@@ -328,6 +381,46 @@ export class SimBufferReader {
       yield { idx: i, f32: sv.f32, u32: sv.u32 };
     }
   }
+
+  // ── Presentation interpolation ──
+  // prev = state(t-1) transform, cur = state(t); the renderer lerps by
+  // getInterpolationAlpha(). Wall-clock epoch ms (timeOrigin + now) —
+  // comparable across the worker/renderer thread boundary.
+
+  getPublishTimeMs(): number {
+    const o = SimChannel.offsets.header;
+    return this.reader.header.f64[o.publishTimeMs >> 1];
+  }
+
+  getPublishDeltaMs(): number {
+    const o = SimChannel.offsets.header;
+    return this.reader.header.f32[o.publishDeltaMs];
+  }
+
+  /**
+   * Interpolation alpha in [0,1] for the current frame. 0 = exactly at
+   * the last publish, 1 = a full publish interval past it (use cur).
+   * Clamped — no extrapolation.
+   */
+  getInterpolationAlpha(nowMs?: number): number {
+    const delta = this.getPublishDeltaMs();
+    if (delta <= 0) return 1;
+    const now = nowMs ?? (performance.timeOrigin ?? 0) + performance.now();
+    const a = (now - this.getPublishTimeMs()) / delta;
+    return a <= 0 ? 0 : a >= 1 ? 1 : a;
+  }
+
+  /** Previous-publish transform for an entity slot (prev pos+rot, PREV.*). */
+  getEntityPrevSlot(idx: number): { f32: Float32Array; u32: Uint32Array } {
+    const sv = this.entityPrevSlots.slot(idx);
+    return { f32: sv.f32, u32: sv.u32 };
+  }
+
+  /** Previous-publish transform for a player slot (prev pos+rot, PREV.*). */
+  getPlayerPrevSlot(idx: number): { f32: Float32Array; u32: Uint32Array } {
+    const sv = this.playerPrevSlots.slot(idx);
+    return { f32: sv.f32, u32: sv.u32 };
+  }
 }
 
 // --- Sim Buffer Writer (sim worker side) ---
@@ -336,52 +429,67 @@ export class SimBufferWriter {
   private writer: ReturnType<typeof SimChannel.writer>;
   private entitySlots: ReturnType<typeof SimChannel.writer>["sections"]["entities"];
   private playerSlots: ReturnType<typeof SimChannel.writer>["sections"]["players"];
+  private entityPrevSlots: ReturnType<typeof SimChannel.writer>["sections"]["entitiesPrev"];
+  private playerPrevSlots: ReturnType<typeof SimChannel.writer>["sections"]["playersPrev"];
   // Dirty flags: 1 = entity/player slot has changed since last writeToBuffer.
   // writeToBuffer skips slots where the flag is 0. Cleared after each writeToBuffer.
   private dirtyEntities: Uint8Array;
   private dirtyPlayers: Uint8Array;
+  // Snapshot flags: 1 = the slot's prev-transform was already captured this
+  // publish (on first write access). Cleared at each incrementTick commit.
+  private snapEntities: Uint8Array;
+  private snapPlayers: Uint8Array;
 
   constructor(sab: SharedArrayBuffer) {
     this.writer = SimChannel.writer(sab);
     this.entitySlots = this.writer.sections.entities;
     this.playerSlots = this.writer.sections.players;
+    this.entityPrevSlots = this.writer.sections.entitiesPrev;
+    this.playerPrevSlots = this.writer.sections.playersPrev;
     this.dirtyEntities = new Uint8Array(MAX_ENTITIES);
     this.dirtyPlayers = new Uint8Array(MAX_PLAYERS);
+    this.snapEntities = new Uint8Array(MAX_ENTITIES);
+    this.snapPlayers = new Uint8Array(MAX_PLAYERS);
   }
 
   init() {
     const w = this.writer;
     const h = SimChannel.offsets.header;
+    w.beginWrite();
     w.header.u32[h.maxEntities] = MAX_ENTITIES;
     w.header.u32[h.maxPlayers] = MAX_PLAYERS;
     w.header.u32[h.entityCount] = 0;
     w.header.u32[h.playerCount] = 0;
     w.header.u32[h.activePlayers] = 0;
+    w.endWrite();
   }
 
-  setEntityCount(n: number) { this.writer.header.u32[SimChannel.offsets.header.entityCount] = n; }
-  setPlayerCount(n: number) { this.writer.header.u32[SimChannel.offsets.header.playerCount] = n; }
-  setTimeOfDay(t: number) { this.writer.header.f32[SimChannel.offsets.header.timeOfDay] = t; }
+  setEntityCount(n: number) { this.writer.beginWrite(); this.writer.header.u32[SimChannel.offsets.header.entityCount] = n; }
+  setPlayerCount(n: number) { this.writer.beginWrite(); this.writer.header.u32[SimChannel.offsets.header.playerCount] = n; }
+  setTimeOfDay(t: number) { this.writer.beginWrite(); this.writer.header.f32[SimChannel.offsets.header.timeOfDay] = t; }
   setWeather(type: number, intensity: number) {
+    this.writer.beginWrite();
     this.writer.header.u32[SimChannel.offsets.header.weatherType] = type;
     this.writer.header.f32[SimChannel.offsets.header.weatherIntensity] = intensity;
   }
   setWind(speed: number, dirX: number, dirZ: number) {
+    this.writer.beginWrite();
     this.writer.header.f32[SimChannel.offsets.header.windSpeed] = speed;
     this.writer.header.f32[SimChannel.offsets.header.windDirX] = dirX;
     this.writer.header.f32[SimChannel.offsets.header.windDirZ] = dirZ;
   }
-  setVisibility(v: number) { this.writer.header.f32[SimChannel.offsets.header.visibility] = v; }
-  setAmbientTemp(t: number) { this.writer.header.f32[SimChannel.offsets.header.ambientTemp] = t; }
-  setActivePlayers(mask: number) { this.writer.header.u32[SimChannel.offsets.header.activePlayers] = mask; }
-  setGamemode(mode: number) { this.writer.header.u32[SimChannel.offsets.header.gamemode] = mode; }
-  setPhysicsInitialized(v: number) { this.writer.header.u32[SimChannel.offsets.header.physicsInitialized] = v; }
-  setPhysicsFailed(v: number) { this.writer.header.u32[SimChannel.offsets.header.physicsFailed] = v; }
-  setPhysicsBodyCount(v: number) { this.writer.header.u32[SimChannel.offsets.header.physicsBodyCount] = v; }
-  setPhysicsTickCount(v: number) { this.writer.header.u32[SimChannel.offsets.header.physicsTickCount] = v; }
-  setChunkCount(v: number) { this.writer.header.u32[SimChannel.offsets.header.chunkCount] = v; }
-  setPhysicsProfilerEnabled(v: number) { this.writer.header.u32[SimChannel.offsets.header.physicsProfilerEnabled] = v; }
+  setVisibility(v: number) { this.writer.beginWrite(); this.writer.header.f32[SimChannel.offsets.header.visibility] = v; }
+  setAmbientTemp(t: number) { this.writer.beginWrite(); this.writer.header.f32[SimChannel.offsets.header.ambientTemp] = t; }
+  setActivePlayers(mask: number) { this.writer.beginWrite(); this.writer.header.u32[SimChannel.offsets.header.activePlayers] = mask; }
+  setGamemode(mode: number) { this.writer.beginWrite(); this.writer.header.u32[SimChannel.offsets.header.gamemode] = mode; }
+  setPhysicsInitialized(v: number) { this.writer.beginWrite(); this.writer.header.u32[SimChannel.offsets.header.physicsInitialized] = v; }
+  setPhysicsFailed(v: number) { this.writer.beginWrite(); this.writer.header.u32[SimChannel.offsets.header.physicsFailed] = v; }
+  setPhysicsBodyCount(v: number) { this.writer.beginWrite(); this.writer.header.u32[SimChannel.offsets.header.physicsBodyCount] = v; }
+  setPhysicsTickCount(v: number) { this.writer.beginWrite(); this.writer.header.u32[SimChannel.offsets.header.physicsTickCount] = v; }
+  setChunkCount(v: number) { this.writer.beginWrite(); this.writer.header.u32[SimChannel.offsets.header.chunkCount] = v; }
+  setPhysicsProfilerEnabled(v: number) { this.writer.beginWrite(); this.writer.header.u32[SimChannel.offsets.header.physicsProfilerEnabled] = v; }
   setPhysicsTiming(data: PhysicsTimingData) {
+    this.writer.beginWrite();
     const h = this.writer.header.f32;
     const o = SimChannel.offsets.header;
     h[o.physTimingStep] = data.step;
@@ -402,10 +510,58 @@ export class SimBufferWriter {
     h[o.physTimingUserChanges] = data.userChanges;
   }
 
+  /**
+   * Copy the slot's current transform (pos+rot, first 8 f32s) into its
+   * prev slot — once per publish, on first write access, so prev always
+   * holds the last committed transform for interpolation.
+   */
+  private snapshotEntityPrev(idx: number): void {
+    if (this.snapEntities[idx]) return;
+    this.snapEntities[idx] = 1;
+    this.entityPrevSlots.slot(idx).f32.set(this.entitySlots.slot(idx).f32.subarray(0, 8));
+  }
+
+  private snapshotPlayerPrev(idx: number): void {
+    if (this.snapPlayers[idx]) return;
+    this.snapPlayers[idx] = 1;
+    this.playerPrevSlots.slot(idx).f32.set(this.playerSlots.slot(idx).f32.subarray(0, 8));
+  }
+
   incrementTick() {
     const h = SimChannel.offsets.header;
-    Atomics.add(this.writer.header.u32, h.tick, 1);
-    this.writer.bumpSequence();
+    const w = this.writer;
+    // Prev-sync: slots not written this publish keep their old cur, so
+    // prev must equal cur (identity lerp). Slots that were written were
+    // already snapshotted on first access. Runs inside the open write
+    // window, before the commit — readers never see a mixed prev/cur.
+    const entCount = Math.min(w.header.u32[h.entityCount], MAX_ENTITIES);
+    for (let i = 0; i < entCount; i++) {
+      if (!this.snapEntities[i]) {
+        this.entityPrevSlots.slot(i).f32.set(this.entitySlots.slot(i).f32.subarray(0, 8));
+      }
+    }
+    this.snapEntities.fill(0);
+    const plrCount = Math.min(w.header.u32[h.playerCount], MAX_PLAYERS);
+    for (let i = 0; i < plrCount; i++) {
+      if (!this.snapPlayers[i]) {
+        this.playerPrevSlots.slot(i).f32.set(this.playerSlots.slot(i).f32.subarray(0, 8));
+      }
+    }
+    this.snapPlayers.fill(0);
+
+    // Wall-clock epoch ms — performance.timeOrigin is defined per thread
+    // and makes the stamp comparable on the renderer side.
+    const now = (performance.timeOrigin ?? 0) + performance.now();
+    const tIdx = h.publishTimeMs >> 1; // u32 index 40 → f64 index 20
+    const last = w.header.f64[tIdx];
+    w.header.f64[tIdx] = now;
+    w.header.f32[h.publishDeltaMs] = last > 0 ? now - last : 0;
+
+    Atomics.add(w.header.u32, h.tick, 1);
+    // Closes the beginWrite() window opened by the first mutation of this
+    // publish (odd→even) — or steps +2 when nothing wrote this tick, so
+    // the sequence still advances once per publish for change detection.
+    w.bumpSequence();
   }
 
   markEntityDirty(slot: number): void {
@@ -436,18 +592,26 @@ export class SimBufferWriter {
   }
 
   getEntityF32(idx: number): Float32Array {
+    this.writer.beginWrite();
+    this.snapshotEntityPrev(idx);
     return this.entitySlots.slot(idx).f32;
   }
 
   getEntityU32(idx: number): Uint32Array {
+    this.writer.beginWrite();
+    this.snapshotEntityPrev(idx);
     return this.entitySlots.slot(idx).u32;
   }
 
   getPlayerF32(idx: number): Float32Array {
+    this.writer.beginWrite();
+    this.snapshotPlayerPrev(idx);
     return this.playerSlots.slot(idx).f32;
   }
 
   getPlayerU32(idx: number): Uint32Array {
+    this.writer.beginWrite();
+    this.snapshotPlayerPrev(idx);
     return this.playerSlots.slot(idx).u32;
   }
 }

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

@@ -117,6 +117,32 @@ export class SlotReader {
     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();
@@ -154,6 +180,8 @@ export class SlotWriter {
   sections: Record<string, SlotAccessor>;
   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;
@@ -180,10 +208,36 @@ export class SlotWriter {
     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: nested/extra calls are free, so
+   * mutating accessors can call it unconditionally on every write path.
+   */
+  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. Legacy callers use this without a beginWrite()
+   * window: it then steps +2 (even→even) so the sequence always lands on
+   * a stable value while still advancing once per publish. Inside a
+   * beginWrite() window it closes the window (+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/types.ts

@@ -126,6 +126,13 @@ export interface ChannelReader {
   validationError(): string | null;
   getSequence(): number;
   hasChanged(lastSeen: number): boolean;
+  /** True while the writer holds an open write window (sequence odd). */
+  isWriteInProgress(): boolean;
+  /**
+   * Run `fn` against a consistent snapshot — retries while the writer is
+   * mid-publish or publishes during the read (seqlock). Bounded retries.
+   */
+  readConsistent<T>(fn: () => T, maxRetries?: number): T;
   header: HeaderViews;
   sections?: Record<string, SlotAccessor>;
   layers?: Record<string, Float32Array | Int32Array | Uint32Array | Float64Array>;
@@ -135,6 +142,10 @@ export interface ChannelReader {
 
 export interface ChannelWriter {
   init(): void;
+  /** Open a write window (sequence → odd). Idempotent. */
+  beginWrite(): void;
+  /** Close the current write window (sequence → even). */
+  endWrite(): void;
   bumpSequence(): void;
   getSequence(): number;
   header: HeaderViews;

package/core/src/telemetry/gpu-resource-tracker.ts

@@ -168,6 +168,26 @@ export class GPUResourceTracker {
    * inform. Enable via constructor for leak-hunting sessions.
    */
   private captureCallsites: boolean;
+  /**
+   * Resources dropped without destroy() are released through the native
+   * FinalizationRegistry (platform-native/gpu/registry.ts) — the wrapped
+   * destroy() never runs, so without this second registry their tracked
+   * entries (and reported VRAM) would grow forever. The held value is the
+   * tracked id; the resource object itself is the unregister token.
+   */
+  private gcRegistry = new FinalizationRegistry<number>((id) => {
+    const r = this.resources.get(id);
+    if (!r) return;
+    this.resources.delete(id);
+    if (r.type === "texture") {
+      this.textureBytes -= r.size;
+      this.textureCount--;
+    } else {
+      this.bufferBytes -= r.size;
+      this.bufferCount--;
+    }
+    this.dirty = true;
+  });
 
   constructor(opts: { captureCallsites?: boolean } = {}) {
     this.captureCallsites = opts.captureCallsites ?? false;
@@ -201,6 +221,7 @@ export class GPUResourceTracker {
       tracker.textureBytes += bytes;
       tracker.textureCount++;
       tracker.dirty = true;
+      tracker.gcRegistry.register(tex, id, tex);
 
       // Wrap destroy to remove from tracking
       const origDestroy = tex.destroy.bind(tex);
@@ -212,6 +233,7 @@ export class GPUResourceTracker {
           tracker.textureCount--;
           tracker.dirty = true;
         }
+        tracker.gcRegistry.unregister(tex);
         origDestroy();
       };
 
@@ -234,6 +256,7 @@ export class GPUResourceTracker {
       tracker.bufferBytes += bytes;
       tracker.bufferCount++;
       tracker.dirty = true;
+      tracker.gcRegistry.register(buf, id, buf);
 
       // Wrap destroy to remove from tracking
       const origDestroy = buf.destroy.bind(buf);
@@ -245,6 +268,7 @@ export class GPUResourceTracker {
           tracker.bufferCount--;
           tracker.dirty = true;
         }
+        tracker.gcRegistry.unregister(buf);
         origDestroy();
       };
 

package/core/src/util/index.ts

@@ -14,4 +14,5 @@ export {
 export type { FeatureLogData } from "./feature-log";
 export { addLogSink, ConsoleLogger, createLogger, getLogTheme, getRecentLogs, setThreadTag } from "./logger";
 export type { Logger, LogSink, LogSinkEntry } from "./logger";
+export { untrackedTimeout } from "./session-timer";
 

package/core/src/util/logger.ts

@@ -272,12 +272,12 @@ function highlightJson(json: string): string {
                 out += jsonColors().string + str + reset;
             }
             i = end + 1;
-        } else if (/[\{\}\[\]]/.test(ch)) {
+        } else if (/[{\}[\]]/.test(ch)) {
             out += jsonColors().brace + ch + reset;
             i++;
         } else if (/\d/.test(ch) || (ch === '-' && /\d/.test(json[i + 1]))) {
             let end = i + 1;
-            while (end < json.length && /[\d.eE+\-]/.test(json[end])) end++;
+            while (end < json.length && /[\d.eE+-]/.test(json[end])) end++;
             out += jsonColors().number + json.slice(i, end) + reset;
             i = end;
         } else if (json.slice(i, i + 4) === 'true') {

package/core/src/util/session-timer.ts

@@ -0,0 +1,23 @@
+// ============================================================================
+// session-timer.ts — scheduling that survives session teardown
+//
+// Under the native dev shell the SessionTracker wraps global setTimeout:
+// callbacks armed while the session is dead (teardown in flight) self-disarm
+// via WeakRef and never run — correct for session-owned work, fatal for
+// bound/grace-period timers whose whole job is to fire DURING teardown
+// (shutdown-RPC bounds, retire fallbacks, response timeouts). Those must
+// route through the tracker's untrackedTimeout. Outside the dev shell
+// __ddSession is absent and this is a plain setTimeout.
+// ============================================================================
+
+/**
+ * setTimeout that is exempt from dev-session tracking. The returned id pairs
+ * with plain clearTimeout (the wrapped clear delegates to the platform clear).
+ */
+export function untrackedTimeout(fn: () => void, ms: number): ReturnType<typeof setTimeout> {
+  const tracker = (globalThis as any).__ddSession;
+  if (typeof tracker?.untrackedTimeout === "function") {
+    return tracker.untrackedTimeout(fn, ms);
+  }
+  return setTimeout(fn, ms);
+}

package/core/src/worker/base-worker-host.ts

@@ -24,6 +24,7 @@
 
 import { usingRealSAB } from "../sab/sab-polyfill";
 import { createLogger } from "../util/logger";
+import { untrackedTimeout } from "../util/session-timer";
 import type { BufferSyncConfig, BufferSyncHost } from "./buffer-sync";
 import { wrap, type WorkerApi, type WorkerProxy } from "./rpc";
 
@@ -171,7 +172,7 @@ export abstract class BaseWorkerHost<TApi extends WorkerApi> {
           await Promise.race([
             this.proxy.proxy.shutdown(),
             new Promise((_, rej) => {
-              timer = setTimeout(() => rej(new Error("shutdown RPC timed out")), 2_000);
+              timer = untrackedTimeout(() => rej(new Error("shutdown RPC timed out")), 2_000);
             }),
           ]);
         } finally {

package/core/src/worker/buffer-sync.ts

@@ -113,10 +113,10 @@ export interface BufferSyncMessage {
   regions: Record<string, RegionCopy[]>;
   /**
    * Multi-message transfer metadata. Large transfers are split into one
-   * region-copy per message with a 16ms gap so the main thread can render
-   * between chunks; the receiver buffers the parts and applies them
-   * ATOMICALLY once all arrive — otherwise the buffer visibly tears for
-   * `total × 16ms` while partially-updated regions are rendered.
+   * region-copy per message (each its own macrotask, so the main thread
+   * can render between deliveries); the receiver buffers the parts and
+   * applies them ATOMICALLY once all arrive — otherwise the buffer would
+   * visibly tear while partially-updated regions are rendered.
    */
   batch?: { id: number; index: number; total: number };
 }
@@ -457,10 +457,11 @@ export class BufferSyncWorker {
           len = Math.min(r.length, count * r.lengthMultiplier);
         }
         // Chunked transfer: if the region is large, split into chunks
-        // and send with setTimeout between them so the main thread
-        // can process rAF/render between chunks. This prevents 100-900ms
-        // main-thread blocks where SAB is unavailable
-        // and postMessage structured clone is ~10MB/s).
+        // sent as separate postMessages so the main thread interleaves
+        // receive+apply tasks with rAF/render instead of blocking on one
+        // giant structured clone. This prevents 100-900ms main-thread
+        // blocks where SAB is unavailable (and postMessage structured
+        // clone is ~10MB/s).
         const CHUNK_SIZE = 64 * 1024; // 64KB per chunk — small enough to avoid >50ms blocks
         if (len > CHUNK_SIZE) {
           const numChunks = Math.ceil(len / CHUNK_SIZE);
@@ -497,10 +498,16 @@ export class BufferSyncWorker {
       // main thread to render between them.
       const allCopies = Object.values(regions).flat();
       if (allCopies.length > 1 && totalBytes > 256 * 1024) {
-        // Large transfer: send chunks with setTimeout between them so the
-        // main thread can render between chunks. Each message carries batch
-        // metadata — the receiver buffers parts and applies them atomically
-        // once all arrive, so the buffer never renders partially-updated.
+        // Large transfer: send chunks as separate postMessages so the main
+        // thread interleaves receive+apply tasks with rAF/render. Each
+        // message carries batch metadata — the receiver buffers parts and
+        // applies them atomically once all arrive, so the buffer never
+        // renders partially-updated. A setTimeout(0) between posts yields
+        // the worker's macrotask queue once per chunk — letting urgent
+        // worker-side messages (RPC responses, other sync traffic) insert
+        // between chunks rather than queueing behind the whole batch — but
+        // adds no fixed delay: measured delivery was ~16ms/chunk with a
+        // 16ms gap (~1s for a 4MB region) vs sub-ms/chunk now.
         // Precompute chunk→buffer ownership once (was O(chunks×regions) before).
         const chunkOwner: string[] = [];
         for (const [name, regionList] of Object.entries(regions)) {
@@ -520,7 +527,7 @@ export class BufferSyncWorker {
             [copy.data],
           );
           if (chunkIdx < total) {
-            setTimeout(sendNextChunk, 16); // 16ms delay lets main thread render between chunks
+            setTimeout(sendNextChunk, 0); // yield the macrotask queue between chunk posts
           }
         };
         sendNextChunk();