@downdraft/engine 0.1.0 → 0.1.2-alpha.5

package/dist/core/src/worker/base-worker-host.js

@@ -0,0 +1,212 @@
+// ============================================================================
+// BaseWorkerHost — shared boilerplate for main-thread worker host classes.
+//
+// Each game's XxxWorkerHost re-implemented the same ~80 lines: SAB allocation,
+// wrap(), onerror, onEvents("ready"), stop(), ready tracking, proxy management.
+// This base class centralizes that boilerplate. Subclasses provide:
+//   - createWorker(): MUST return `new Worker(new URL("./xxx-worker.ts", import.meta.url), { type: "module" })`
+//   - onInit(): call the worker's init RPC with the SAB + game-specific args
+//   - onEvent(): override for game-specific events (defaults to ready tracking)
+//   - getSyncConfig(): optional — buffer sync regions for SAB polyfill (mobile)
+//
+// CRITICAL: Vite's static analysis requires `new Worker(new URL(..., import.meta.url))`
+// to appear literally in the source at the call site. It CANNOT be moved into
+// this base class. Subclasses MUST implement createWorker() with the inline
+// pattern. Assigning the URL to a variable first breaks production builds
+// (Vite emits the worker as a raw unbundled asset with unresolved bare imports).
+//
+// SAB polyfill: when SharedArrayBuffer is unavailable, the
+// base class creates a BufferSyncHost that syncs input regions to the worker
+// via requestAnimationFrame + postMessage (transfer). The worker side syncs
+// sim data back after each tick batch. See buffer-sync.ts + sab-polyfill.ts.
+// Subclasses override getSyncConfig() to declare which regions each side writes.
+// ============================================================================
+import { usingRealSAB } from "../sab/sab-polyfill.js";
+import { createLogger } from "../util/logger.js";
+import { wrap } from "./rpc.js";
+const log = createLogger();
+export class BaseWorkerHost {
+    sab;
+    proxy = null;
+    worker = null;
+    ready = false;
+    unsubEvents = null;
+    syncHost = null;
+    lifecycleLock = null;
+    constructor(sab) {
+        this.sab = sab;
+    }
+    /** The SharedArrayBuffer shared with the worker. */
+    getSimBuffer() {
+        return this.sab;
+    }
+    /** True after the worker has reported the "ready" event. */
+    isReady() {
+        return this.ready;
+    }
+    /** The typed RPC proxy. Returns null before start() or after stop(). */
+    getProxy() {
+        return this.proxy;
+    }
+    /**
+     * Serialize start()/stop() — a hot-reload save→stop→start cycle racing a
+     * second caller (overlapping swap events, session teardown) must not
+     * interleave worker/proxy swaps, or workers get orphaned mid-flight.
+     * FIFO mutex; uncontended calls invoke fn synchronously so start() wires
+     * the worker in the caller's own tick (post-await subscribers rely on it).
+     */
+    serialized(fn) {
+        let release;
+        const mine = new Promise((r) => (release = r));
+        const prev = this.lifecycleLock;
+        this.lifecycleLock = mine;
+        const settle = () => {
+            if (this.lifecycleLock === mine)
+                this.lifecycleLock = null;
+            release();
+        };
+        if (!prev) {
+            const result = Promise.resolve(fn());
+            void result.finally(settle);
+            return result;
+        }
+        return prev.then(async () => {
+            try {
+                return await fn();
+            }
+            finally {
+                settle();
+            }
+        });
+    }
+    /**
+     * Spawn the worker and call its init RPC.
+     *
+     * Subclasses MUST implement createWorker() with the inline
+     * `new Worker(new URL("./xxx-worker.ts", import.meta.url), { type: "module" })`
+     * pattern. See the file-level comment for why.
+     *
+     * When SAB is unavailable, a BufferSyncHost is created
+     * to sync input regions to the worker via rAF + postMessage. Subclasses
+     * override getSyncConfig() to declare the region layout.
+     */
+    async start() {
+        return this.serialized(async () => {
+            // Re-entrant start while a worker is live (overlapping hot reloads,
+            // teardown racing a respawn) must not orphan the old worker.
+            if (this.worker || this.proxy)
+                await this.stopInner();
+            this.worker = this.createWorker();
+            // A live worker must never be the only handle pinning the process —
+            // window-close teardown stops it explicitly (sim.stop()), but a worker
+            // that slips through (error path, missing stop impl) shouldn't hold
+            // the runtime open forever. No-op where unref doesn't exist (Deno).
+            this.worker.unref?.();
+            // 120s rather than the 30s default: in dev, vite's cold transform of a
+            // large worker module can exceed 30s, killing init with a spurious
+            // timeout while the worker is still legitimately loading.
+            this.proxy = wrap(this.worker, { timeoutMs: 120_000 });
+            // Tag the Worker with its RPC proxy so external force-terminates (dev
+            // session teardown) reject pending calls instead of leaving them to
+            // hang until their timeout — a hanging caller pins the dying session.
+            this.worker.__ddWorkerProxy = this.proxy;
+            this.worker.onerror = (e) => {
+                this.onError(e);
+            };
+            this.unsubEvents = this.proxy.onEvents((kind, data) => {
+                this.onEvent(kind, data);
+            });
+            // SAB polyfill: start buffer sync host before onInit so input sync begins
+            // as soon as the worker is ready. The host uses rAF to sync input regions.
+            if (!usingRealSAB && this.getSyncConfig()) {
+                const { BufferSyncHost: BSH } = await import("./buffer-sync.js");
+                this.syncHost = new BSH(this.worker, this.getSyncConfig());
+                this.syncHost.start();
+            }
+            // Hook for subclasses to run setup before onInit (e.g. attaching profiling SAB).
+            await this.beforeInit();
+            await this.onInit();
+        });
+    }
+    /**
+     * Shut down the worker: call shutdown() RPC, terminate, clean up.
+     * Safe to call multiple times.
+     * Alias for stop() — some games call shutdown(), others stop().
+     */
+    async shutdown() {
+        return this.stop();
+    }
+    /**
+     * Shut down the worker: call shutdown() RPC, terminate, clean up.
+     * Safe to call multiple times.
+     */
+    async stop() {
+        return this.serialized(() => this.stopInner());
+    }
+    async stopInner() {
+        this.syncHost?.stop();
+        this.syncHost = null;
+        if (this.proxy) {
+            try {
+                // Bounded graceful shutdown — a wedged worker must not hang stop()
+                // (and through it, hot-reload pipelines and session teardown).
+                let timer;
+                try {
+                    await Promise.race([
+                        this.proxy.proxy.shutdown(),
+                        new Promise((_, rej) => {
+                            timer = setTimeout(() => rej(new Error("shutdown RPC timed out")), 2_000);
+                        }),
+                    ]);
+                }
+                finally {
+                    clearTimeout(timer);
+                }
+            }
+            catch {
+                // Worker may already be dead
+            }
+            this.proxy.terminate();
+        }
+        this.unsubEvents?.();
+        this.unsubEvents = null;
+        this.proxy = null;
+        this.worker = null;
+        this.ready = false;
+    }
+    /**
+     * Override to run setup before onInit(). Called after the worker is spawned
+     * and the proxy is set up, but before onInit(). InstrumentedWorkerHost uses
+     * this to attach the ProfilingSAB + patch prototypes before user code runs.
+     * Default: no-op.
+     */
+    beforeInit() {
+        return Promise.resolve();
+    }
+    /**
+     * Override to declare buffer sync regions for the SAB polyfill (mobile).
+     * Return null/undefined to skip sync (e.g. if the host doesn't use SAB).
+     * The config should declare which regions the MAIN thread writes (input)
+     * vs which the WORKER writes (sim data, stats, board). See buffer-sync.ts.
+     * Default: null (no sync — used when SAB is available or host doesn't need sync).
+     */
+    getSyncConfig() {
+        return null;
+    }
+    /**
+     * Override for game-specific event handling.
+     * Default: sets ready=true on "ready" event.
+     */
+    onEvent(kind, _data) {
+        if (kind === "ready") {
+            this.ready = true;
+        }
+    }
+    /**
+     * Override for custom error handling.
+     * Default: logs to console with the class name.
+     */
+    onError(e) {
+        log.error(this.constructor.name, `Worker error: ${e.message}`);
+    }
+}

package/dist/core/src/worker/buffer-sync.js

@@ -0,0 +1,454 @@
+// ============================================================================
+// buffer-sync — copy-based buffer synchronization for the SAB polyfill
+// ============================================================================
+//
+// When SharedArrayBuffer is polyfilled, each thread has its
+// own ArrayBuffer instance. This module synchronizes them via postMessage at
+// tick/frame boundaries:
+//
+//   Main → Worker (input):  driven by requestAnimationFrame, copies only the
+//     input region(s) the main thread writes, transfers the ArrayBuffer.
+//   Worker → Main (sim):    event-driven (after each tick batch), copies only
+//     the regions the worker writes, transfers the ArrayBuffer.
+//
+// Optimizations:
+//   - Region-aware: only the declared write regions are copied, not the full
+//     buffer. For sandjongg's embedded input (64 bytes), main→worker copies
+//     64 bytes, not the full 1.3MB.
+//   - Sequence-number gating: if a buffer has a sequence field, the sync is
+//     skipped when the sequence hasn't changed since the last sync. Eliminates
+//     all copy overhead when the sim is paused.
+//   - Transferable ArrayBuffers: postMessage with a transfer list avoids the
+//     structured-clone copy (transfer is zero-copy). Net: 1 copy (slice)
+//     instead of 2 (slice + structured clone).
+//
+// Single-writer constraint:
+//   Each buffer region must have exactly one writer. If both sides write to
+//   the same region, the sync will overwrite one side's writes with stale data
+//   from the other. The region declarations (writeRegions/readRegions) enforce
+//   this — the sync manager only copies declared write regions.
+//
+import { createLogger } from "../util/logger.js";
+const log = createLogger();
+/** Check if a message is a buffer-sync message. */
+export function isBufferSyncMessage(msg) {
+    return typeof msg === "object" && msg !== null && "__bufferSync" in msg;
+}
+// ---------------------------------------------------------------------------
+// Main-thread side
+// ---------------------------------------------------------------------------
+// ---------------------------------------------------------------------------
+// Profiling support (lightweight, no deps)
+// ---------------------------------------------------------------------------
+/** Sync profiling is opt-in: `__DOWNDRAFT_PROFILE_SYNC__` global or
+ *  `DOWNDRAFT_PROFILE_SYNC=1` env. When off, no samples are recorded and no
+ *  console output is produced (previously it logged every 5s in production). */
+function syncProfilingEnabled() {
+    const g = globalThis;
+    if (g.__DOWNDRAFT_PROFILE_SYNC__ === true)
+        return true;
+    try {
+        return g.process?.env
+            ?.DOWNDRAFT_PROFILE_SYNC === "1";
+    }
+    catch {
+        return false;
+    }
+}
+/** Accumulates timing samples and logs a summary every N calls. */
+class SyncProfiler {
+    samples = [];
+    logTimer = 0;
+    logInterval;
+    enabled = syncProfilingEnabled();
+    constructor(logIntervalMs = 5000) {
+        this.logInterval = logIntervalMs;
+    }
+    /** Record a timed operation. Call begin() before, end() after. */
+    begin() { return this.enabled ? performance.now() : 0; }
+    end(label, start, bytes) {
+        if (!this.enabled)
+            return;
+        const ms = performance.now() - start;
+        this.samples.push({ label, ms, bytes });
+        const now = performance.now();
+        if (now - this.logTimer >= this.logInterval) {
+            this.logTimer = now;
+            this.flush();
+        }
+    }
+    flush() {
+        if (this.samples.length === 0)
+            return;
+        const byLabel = {};
+        this.samples.forEach((s) => {
+            const e = byLabel[s.label] ?? (byLabel[s.label] = { count: 0, totalMs: 0, totalBytes: 0, maxMs: 0 });
+            e.count++;
+            e.totalMs += s.ms;
+            e.totalBytes += s.bytes;
+            if (s.ms > e.maxMs)
+                e.maxMs = s.ms;
+        });
+        const lines = [];
+        for (const [label, e] of Object.entries(byLabel)) {
+            const avgMs = (e.totalMs / e.count).toFixed(2);
+            const maxMs = e.maxMs.toFixed(2);
+            const totalKB = (e.totalBytes / 1024).toFixed(0);
+            const avgKB = (e.totalBytes / e.count / 1024).toFixed(1);
+            lines.push(`  ${label}: ${e.count}x avg=${avgMs}ms max=${maxMs}ms avgSize=${avgKB}KB total=${totalKB}KB`);
+        }
+        log.warn("buffer-sync", `Profiling: ${this.samples.length} samples over last ${this.logInterval}ms:\n${lines.join("\n")}`);
+        this.samples = [];
+    }
+}
+/**
+ * Main-thread buffer sync manager.
+ *
+ * Sends input regions to the worker on requestAnimationFrame, and receives
+ * sim data regions from the worker via onMessage. Uses rAF (not setInterval)
+ * to adapt to the display refresh rate and pause when the tab is hidden.
+ */
+export class BufferSyncHost {
+    worker;
+    config;
+    rafId = 0;
+    /** Per-region last-synced sequence: buffer name → region name → seq.
+     *  Tracked per region (not per buffer) so throttled regions aren't starved
+     *  when another region's sync consumes the buffer-level seq. */
+    lastRegionSeqs = {};
+    frameCount = 0;
+    profiler = new SyncProfiler(5000);
+    messageHandler = null;
+    constructor(worker, config) {
+        this.worker = worker;
+        this.config = config;
+    }
+    start() {
+        if (!this.messageHandler) {
+            this.messageHandler = (e) => this.onMessage(e.data);
+            this.worker.addEventListener("message", this.messageHandler);
+        }
+        cancelAnimationFrame(this.rafId); // guard against double-start
+        this.syncInput(); // start rAF loop
+    }
+    stop() {
+        cancelAnimationFrame(this.rafId);
+        if (this.messageHandler) {
+            this.worker.removeEventListener("message", this.messageHandler);
+            this.messageHandler = null;
+        }
+    }
+    /**
+     * Sync input regions to the worker. Called on each rAF frame.
+     * Copies only the writeRegions of each buffer, transfers the ArrayBuffers.
+     * Regions with syncInterval > 1 are only synced every N frames (throttled).
+     */
+    syncInput = () => {
+        const transfers = [];
+        const regions = {};
+        this.frameCount++;
+        let totalBytes = 0;
+        const pStart = this.profiler.begin();
+        for (const [name, buf] of Object.entries(this.config.buffers)) {
+            const regionDef = this.config.regions[name];
+            if (!regionDef || regionDef.writeRegions.length === 0)
+                continue;
+            // Sequence gating is per-region (see below) — read the current seq once.
+            const seqField = this.config.seqFields?.[name];
+            const seq = seqField ? new Int32Array(buf, seqField.offset, 1)[0] : 0;
+            const copies = [];
+            for (let _i = 0, _it = regionDef.writeRegions, _n = _it.length; _i < _n; _i++) {
+                const r = _it[_i];
+                // Throttle: skip regions with syncInterval > 1 on most frames.
+                // Only sync them every syncInterval frames.
+                if (r.syncInterval && r.syncInterval > 1) {
+                    if (this.frameCount % r.syncInterval !== 0)
+                        continue;
+                }
+                // Per-region sequence gating: skip this region if its last-synced
+                // seq matches the buffer's current seq. Per-region tracking (rather
+                // than per-buffer) is required because interval-throttled regions
+                // would otherwise never sync — a seq change consumed by a non-
+                // throttled region would gate the throttled one out forever.
+                if (seqField) {
+                    const lastSeqs = (this.lastRegionSeqs[name] ??= {});
+                    if (lastSeqs[r.name] === seq)
+                        continue;
+                }
+                const src = new Uint8Array(buf, r.offset, r.length);
+                // skipIfAllZero: don't send zero-filled regions (e.g. input with
+                // ACTION=0 after clearAfterSend). This prevents overwriting the
+                // worker's pending input with zeros before it processes the input.
+                if (r.skipIfAllZero) {
+                    let allZero = true;
+                    for (let i = 0; i < src.length; i++) {
+                        if (src[i] !== 0) {
+                            allZero = false;
+                            break;
+                        }
+                    }
+                    if (allZero)
+                        continue;
+                }
+                const copy = new ArrayBuffer(r.length);
+                new Uint8Array(copy).set(src);
+                copies.push({ offset: r.offset, data: copy });
+                transfers.push(copy);
+                totalBytes += r.length;
+                // Clear-after-send: zero the local region so we don't re-send stale
+                // data on the next frame. Used for input regions (hand-off pattern).
+                if (r.clearAfterSend) {
+                    new Uint8Array(buf, r.offset, r.length).fill(0);
+                }
+                if (seqField) {
+                    this.lastRegionSeqs[name][r.name] = seq;
+                }
+            }
+            if (copies.length > 0)
+                regions[name] = copies;
+        }
+        if (Object.keys(regions).length > 0) {
+            const postStart = performance.now();
+            this.worker.postMessage({ __bufferSync: true, regions }, transfers);
+            this.profiler.end("host→worker postMessage", postStart, totalBytes);
+        }
+        this.profiler.end("host→worker total", pStart, totalBytes);
+        this.rafId = requestAnimationFrame(this.syncInput);
+    };
+    /** In-flight chunked transfers, keyed by batch id. Parts are applied
+     *  atomically once the batch completes — see BufferSyncMessage.batch. */
+    pendingBatches = new Map();
+    lastBatchSeen = -1;
+    applyRegions(regions) {
+        let totalBytes = 0;
+        for (const [name, regionList] of Object.entries(regions)) {
+            const local = this.config.buffers[name];
+            if (!local)
+                continue;
+            regionList.forEach(({ offset, data }) => {
+                new Uint8Array(local, offset, data.byteLength).set(new Uint8Array(data));
+                totalBytes += data.byteLength;
+            });
+        }
+        return totalBytes;
+    }
+    /**
+     * Receive sim data regions from the worker. Copies only the readRegions
+     * (regions the other side writes) into the local buffer.
+     */
+    onMessage(msg) {
+        if (!isBufferSyncMessage(msg))
+            return;
+        const pStart = this.profiler.begin();
+        let totalBytes = 0;
+        if (msg.batch) {
+            const { id, index, total } = msg.batch;
+            // Part of a batch already completed (or evicted) — a duplicate or a
+            // straggler from before a worker restart; applying it would tear.
+            if (id <= this.lastBatchSeen && !this.pendingBatches.has(id))
+                return;
+            let b = this.pendingBatches.get(id);
+            if (!b) {
+                b = { parts: new Array(total), received: 0 };
+                this.pendingBatches.set(id, b);
+                // Bound the map: a batch that never completes (worker died
+                // mid-transfer) must not leak entries forever.
+                if (this.pendingBatches.size > 8) {
+                    const oldest = this.pendingBatches.keys().next().value;
+                    this.pendingBatches.delete(oldest);
+                }
+            }
+            b.parts[index] = msg.regions;
+            b.received++;
+            if (b.received < total)
+                return; // wait for the rest — no tearing
+            this.pendingBatches.delete(id);
+            this.lastBatchSeen = id;
+            b.parts.forEach((part) => {
+                if (part)
+                    totalBytes += this.applyRegions(part);
+            });
+            this.profiler.end("worker→host onMessage", pStart, totalBytes);
+            return;
+        }
+        totalBytes = this.applyRegions(msg.regions);
+        this.profiler.end("worker→host onMessage", pStart, totalBytes);
+    }
+}
+// ---------------------------------------------------------------------------
+// Worker-thread side
+// ---------------------------------------------------------------------------
+/**
+ * Worker-thread buffer sync manager.
+ *
+ * Sends sim data regions to the main thread after each tick batch (event-
+ * driven, no polling), and receives input regions from the main thread via
+ * onMessage.
+ */
+export class BufferSyncWorker {
+    config;
+    /** Per-region last-synced sequence: buffer name → region name → seq.
+     *  Tracked per region (not per buffer) so a filtered syncToMain() call
+     *  can't consume the buffer seq and starve regions it filtered out —
+     *  e.g. the fast/slow region pattern in sim-worker-base, where a
+     *  fast-region sync followed by a full sync must still send slow regions. */
+    lastRegionSeqs = {};
+    profiler = new SyncProfiler(5000);
+    onAfterReceive = null;
+    /** Monotonic id for chunked (multi-message) transfers — the host applies
+     *  a batch atomically once all parts arrive. */
+    batchCounter = 0;
+    constructor(config) {
+        this.config = config;
+    }
+    /**
+     * Start listening for sync messages from the main thread.
+     * @param onAfterReceive - Optional callback fired after each received
+     *   message is processed. Use this to trigger event-driven work (e.g.
+     *   the grid builder calls build() here instead of polling on a timer,
+     *   which avoids timer throttling in workers on some hosts).
+     */
+    start(onAfterReceive) {
+        this.onAfterReceive = onAfterReceive ?? null;
+        self.addEventListener("message", (e) => {
+            this.onMessage(e.data);
+            this.onAfterReceive?.();
+        });
+    }
+    /**
+     * Post written regions to the main thread. Called after each tick batch.
+     * Copies only the writeRegions of each buffer, transfers the ArrayBuffers.
+     * Skips buffers whose sequence hasn't changed (if seqFields declared).
+     *
+     * @param regionNames - If provided, only sync write regions whose `name`
+     *   matches one of the given names. This enables throttled sync: sync small
+     *   "fast" regions (header, entities) every tick, and large "slow" regions
+     *   (grid data, render buffers) every N ticks. If omitted, sync all regions.
+     */
+    syncToMain(regionNames) {
+        const transfers = [];
+        const regions = {};
+        const filter = regionNames ? new Set(regionNames) : null;
+        const pStart = this.profiler.begin();
+        let totalBytes = 0;
+        for (const [name, buf] of Object.entries(this.config.buffers)) {
+            const regionDef = this.config.regions[name];
+            if (!regionDef || regionDef.writeRegions.length === 0)
+                continue;
+            // Sequence gating is per-region (see below) — read the current seq once.
+            const seqField = this.config.seqFields?.[name];
+            const seq = seqField ? new Int32Array(buf, seqField.offset, 1)[0] : 0;
+            const copies = [];
+            for (let _i = 0, _it = regionDef.writeRegions, _n = _it.length; _i < _n; _i++) {
+                const r = _it[_i];
+                // Region name filter: skip regions not in the filter set.
+                if (filter && !filter.has(r.name))
+                    continue;
+                // Per-region sequence gating: skip if this region's last-synced seq
+                // matches the current buffer seq. Regions excluded by `filter` are
+                // checked before this point, so a filtered call never consumes seq
+                // for regions it didn't send.
+                if (seqField) {
+                    const lastSeqs = (this.lastRegionSeqs[name] ??= {});
+                    if (lastSeqs[r.name] === seq)
+                        continue;
+                }
+                // Dynamic length: read actual length from a field in the buffer.
+                let len = r.length;
+                if (r.lengthFieldOffset !== undefined && r.lengthMultiplier) {
+                    const count = new Uint32Array(buf, r.lengthFieldOffset, 1)[0];
+                    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).
+                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);
+                    for (let i = 0; i < numChunks; i++) {
+                        const chunkStart = i * CHUNK_SIZE;
+                        const chunkLen = Math.min(CHUNK_SIZE, len - chunkStart);
+                        const chunkCopy = new ArrayBuffer(chunkLen);
+                        new Uint8Array(chunkCopy).set(new Uint8Array(buf, r.offset + chunkStart, chunkLen));
+                        copies.push({ offset: r.offset + chunkStart, data: chunkCopy });
+                        transfers.push(chunkCopy);
+                        totalBytes += chunkLen;
+                    }
+                }
+                else {
+                    const copy = new ArrayBuffer(len);
+                    new Uint8Array(copy).set(new Uint8Array(buf, r.offset, len));
+                    copies.push({ offset: r.offset, data: copy });
+                    transfers.push(copy);
+                    totalBytes += len;
+                }
+                if (seqField) {
+                    this.lastRegionSeqs[name][r.name] = seq;
+                }
+            }
+            if (copies.length > 0)
+                regions[name] = copies;
+        }
+        if (Object.keys(regions).length > 0) {
+            const label = regionNames ? `worker→host syncToMain(${regionNames.join(",")})` : "worker→host syncToMain(all)";
+            // Send all chunks in a single postMessage. The host's onMessage
+            // handler copies each chunk to the correct offset in the local buffer.
+            // We don't use setTimeout between chunks because the postMessage
+            // itself is the blocking operation on the main thread — splitting
+            // into multiple postMessage calls with setTimeout would allow the
+            // 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.
+                // Precompute chunk→buffer ownership once (was O(chunks×regions) before).
+                const chunkOwner = [];
+                for (const [name, regionList] of Object.entries(regions)) {
+                    for (let i = 0; i < regionList.length; i++)
+                        chunkOwner.push(name);
+                }
+                const batchId = ++this.batchCounter;
+                const total = allCopies.length;
+                let chunkIdx = 0;
+                const sendNextChunk = () => {
+                    if (chunkIdx >= total)
+                        return;
+                    const copy = allCopies[chunkIdx];
+                    const batchRegions = {};
+                    batchRegions[chunkOwner[chunkIdx]] = [copy];
+                    chunkIdx++;
+                    self.postMessage({ __bufferSync: true, regions: batchRegions, batch: { id: batchId, index: chunkIdx - 1, total } }, [copy.data]);
+                    if (chunkIdx < total) {
+                        setTimeout(sendNextChunk, 16); // 16ms delay lets main thread render between chunks
+                    }
+                };
+                sendNextChunk();
+                this.profiler.end(label, pStart, totalBytes);
+            }
+            else {
+                self.postMessage({ __bufferSync: true, regions }, transfers);
+                this.profiler.end(label, pStart, totalBytes);
+            }
+        }
+    }
+    /**
+     * Receive input regions from the main thread. Copies only the readRegions
+     * (regions the other side writes) into the local buffer.
+     */
+    onMessage(msg) {
+        if (!isBufferSyncMessage(msg))
+            return;
+        for (const [name, regionList] of Object.entries(msg.regions)) {
+            const local = this.config.buffers[name];
+            if (!local)
+                continue;
+            regionList.forEach(({ offset, data }) => {
+                new Uint8Array(local, offset, data.byteLength).set(new Uint8Array(data));
+            });
+        }
+    }
+}