@downdraft/engine 0.1.1 → 0.2.0

package/dist/core/src/sab/sab-polyfill.js

@@ -0,0 +1,47 @@
+// ============================================================================
+// sab-polyfill — SharedArrayBuffer polyfill for hosts without real SAB
+// ============================================================================
+//
+// Some JS hosts do not support SharedArrayBuffer. This polyfill replaces it
+// with an ArrayBuffer subclass so that all existing channel code (typed array
+// views, Atomics.load/add/store) works unchanged.
+//
+// The "sharing" is implemented separately by the BufferSyncManager
+// (packages/engine/core/src/worker/buffer-sync.ts), which copies buffer regions
+// between the main thread and worker via postMessage at tick/frame boundaries.
+//
+// Why this works:
+//   - `class FakeSAB extends ArrayBuffer` passes V8's IS_ARRAYBUFFER check,
+//     so `new Int32Array(fakeSAB, offset, length)` creates working views.
+//   - `Atomics.load/add/store` work on ArrayBuffer-backed typed arrays (V8
+//     doesn't enforce the SAB requirement for these — verified). They perform
+//     non-atomic reads/writes, which is correct for the copy-based protocol
+//     (each side has its own buffer copy — no concurrent access).
+//   - Only `Atomics.wait` throws on non-SAB arrays. We shim it to return
+//     "timed-out" as a safety net.
+//
+// This file must be imported BEFORE any code that references SharedArrayBuffer.
+// It is a no-op when real SharedArrayBuffer is available.
+//
+import { createLogger } from "../util/logger.js";
+const log = createLogger();
+/** True if the real SharedArrayBuffer is available. False if polyfilled. */
+export const usingRealSAB = typeof SharedArrayBuffer !== "undefined";
+if (!usingRealSAB) {
+    // Polyfill SharedArrayBuffer as an ArrayBuffer subclass.
+    // Typed array views (Int32Array, Float32Array, etc.) work on it because
+    // V8's IS_ARRAYBUFFER check passes for ArrayBuffer subclasses.
+    globalThis.SharedArrayBuffer = class SharedArrayBuffer extends ArrayBuffer {
+        constructor(size) {
+            super(size);
+        }
+    };
+    // Shim Atomics.wait — only wait throws on non-SAB arrays.
+    // load/add/store/store/notify all work without throwing on ArrayBuffer.
+    Atomics.wait = () => "timed-out";
+    // Debug identifier — detectable from console/devtools.
+    globalThis.__DOWNDRAFT_SAB_POLYFILL = true;
+    log.warn("sab-polyfill", "SharedArrayBuffer is not available — using copy-based buffer sync protocol.\n" +
+        "If you see this on a runtime that should have real SABs, COOP/COEP\n" +
+        "headers may be missing.");
+}

package/dist/core/src/sab/sim-channel.js

@@ -0,0 +1,397 @@
+// ============================================================================
+// Sim SAB Channel — SharedArrayBuffer for zero-copy sim→renderer state transfer
+// Entity and player slot-based data channel with weather, physics, and world state.
+// ============================================================================
+import { defineChannel } from "./define.js";
+import { InputChannel } from "./game-input.js";
+export const MAX_ENTITIES = 8192;
+export const MAX_PLAYERS = 8;
+export const SIM_ENTITY_SLOT_SIZE = 128;
+export const SIM_PLAYER_SLOT_SIZE = 256;
+export const SimChannel = defineChannel({
+    name: "game-sim",
+    magic: 0x53494d42,
+    version: 1,
+    mode: "slots",
+    header: {
+        size: 256,
+        fields: {
+            entityCount: { type: "u32" },
+            maxEntities: { type: "u32" },
+            playerCount: { type: "u32" },
+            maxPlayers: { type: "u32" },
+            tick: { type: "u32", atomic: true },
+            timeOfDay: { type: "f32" },
+            weatherType: { type: "u32" },
+            weatherIntensity: { type: "f32" },
+            windSpeed: { type: "f32" },
+            windDirX: { type: "f32" },
+            windDirZ: { type: "f32" },
+            visibility: { type: "f32" },
+            ambientTemp: { type: "f32" },
+            activePlayers: { type: "u32" },
+            gamemode: { type: "u32" },
+            physicsInitialized: { type: "u32" },
+            physicsFailed: { type: "u32" },
+            physicsBodyCount: { type: "u32" },
+            physicsTickCount: { type: "u32" },
+            chunkCount: { type: "u32" },
+            physicsProfilerEnabled: { type: "u32" },
+            physTimingStep: { type: "f32" },
+            physTimingCollisionDetection: { type: "f32" },
+            physTimingBroadPhase: { type: "f32" },
+            physTimingNarrowPhase: { type: "f32" },
+            physTimingSolver: { type: "f32" },
+            physTimingVelocityAssembly: { type: "f32" },
+            physTimingVelocityResolution: { type: "f32" },
+            physTimingVelocityUpdate: { type: "f32" },
+            physTimingVelocityWriteback: { type: "f32" },
+            physTimingCcd: { type: "f32" },
+            physTimingCcdToiComputation: { type: "f32" },
+            physTimingCcdBroadPhase: { type: "f32" },
+            physTimingCcdNarrowPhase: { type: "f32" },
+            physTimingCcdSolver: { type: "f32" },
+            physTimingIslandConstruction: { type: "f32" },
+            physTimingUserChanges: { type: "f32" },
+        },
+    },
+    sections: [
+        {
+            name: "entities",
+            maxSlots: MAX_ENTITIES,
+            slotSize: SIM_ENTITY_SLOT_SIZE,
+            fields: {
+                pos: { type: "f32", count: 4 },
+                rot: { type: "f32", count: 4 },
+                vel: { type: "f32", count: 3 },
+                angVel: { type: "f32", count: 3 },
+                health: { type: "f32" },
+                maxHealth: { type: "f32" },
+                type: { type: "u32" },
+                flags: { type: "u32" },
+                id: { type: "u32" },
+                parentId: { type: "u32" },
+                chunkX: { type: "i32" },
+                chunkZ: { type: "i32" },
+                data: { type: "f32", count: 8 },
+                anchorX: { type: "f32" },
+                anchorZ: { type: "f32" },
+            },
+        },
+        {
+            name: "players",
+            maxSlots: MAX_PLAYERS,
+            slotSize: SIM_PLAYER_SLOT_SIZE,
+            fields: {
+                pos: { type: "f32", count: 4 },
+                rot: { type: "f32", count: 4 },
+                health: { type: "f32" },
+                maxHealth: { type: "f32" },
+                hunger: { type: "f32" },
+                thirst: { type: "f32" },
+                oxygen: { type: "f32" },
+                maxOxygen: { type: "f32" },
+                temperature: { type: "f32" },
+                cameraMode: { type: "u32" },
+                activeSlot: { type: "u32" },
+                flags: { type: "u32" },
+                entityId: { type: "u32" },
+                playerId: { type: "u32" },
+                viewport: { type: "f32", count: 4 },
+                pitch: { type: "f32" },
+                freecam: { type: "f32", count: 5 },
+                thirdPersonDistance: { type: "f32" },
+                // NOTE: The player slot is 256 bytes (64 f32s). Core fields use
+                // indices 0–30. Indices 31–63 are reserved padding — games can
+                // define their own extension constants (e.g. GAME_PLR.GOLD = 31)
+                // to store game-specific player state in this padding area without
+                // modifying the core SAB schema.
+            },
+        },
+    ],
+});
+export const SIM_MAGIC = 0x53494d42;
+export const SIM_VERSION = 1;
+export const SIM_HDR = {
+    MAGIC: 0,
+    VERSION: 1,
+    ENTITY_COUNT: 3,
+    MAX_ENTITIES: 4,
+    PLAYER_COUNT: 5,
+    MAX_PLAYERS: 6,
+    TICK: 7,
+    SEQUENCE: 2,
+    TIME_OF_DAY: 8,
+    WEATHER_TYPE: 9,
+    WEATHER_INTENSITY: 10,
+    WIND_SPEED: 11,
+    WIND_DIR_X: 12,
+    WIND_DIR_Z: 13,
+    VISIBILITY: 14,
+    AMBIENT_TEMP: 15,
+    ACTIVE_PLAYERS: 16,
+    GAMEMODE: 17,
+    PHYSICS_INITIALIZED: 18,
+    PHYSICS_FAILED: 19,
+    PHYSICS_BODY_COUNT: 20,
+    PHYSICS_TICK_COUNT: 21,
+    CHUNK_COUNT: 22,
+    PHYSICS_PROFILER_ENABLED: 23,
+    PHYS_TIMING_STEP: 24,
+    PHYS_TIMING_COLLISION_DETECTION: 25,
+    PHYS_TIMING_BROAD_PHASE: 26,
+    PHYS_TIMING_NARROW_PHASE: 27,
+    PHYS_TIMING_SOLVER: 28,
+    PHYS_TIMING_VELOCITY_ASSEMBLY: 29,
+    PHYS_TIMING_VELOCITY_RESOLUTION: 30,
+    PHYS_TIMING_VELOCITY_UPDATE: 31,
+    PHYS_TIMING_VELOCITY_WRITEBACK: 32,
+    PHYS_TIMING_CCD: 33,
+    PHYS_TIMING_CCD_TOI_COMPUTATION: 34,
+    PHYS_TIMING_CCD_BROAD_PHASE: 35,
+    PHYS_TIMING_CCD_NARROW_PHASE: 36,
+    PHYS_TIMING_CCD_SOLVER: 37,
+    PHYS_TIMING_ISLAND_CONSTRUCTION: 38,
+    PHYS_TIMING_USER_CHANGES: 39,
+};
+export const ENT = {
+    POS_X: 0, POS_Y: 1, POS_Z: 2, SCALE: 3,
+    ROT_X: 4, ROT_Y: 5, ROT_Z: 6, ROT_W: 7,
+    VEL_X: 8, VEL_Y: 9, VEL_Z: 10,
+    ANGVEL_X: 11, ANGVEL_Y: 12, ANGVEL_Z: 13,
+    HEALTH: 14, MAX_HEALTH: 15,
+    TYPE: 16, FLAGS: 17, ID: 18, PARENT_ID: 19,
+    CHUNK_X: 20, CHUNK_Z: 21,
+    DATA: 22,
+    ANCHOR_X: 30, ANCHOR_Z: 31,
+};
+export const PLR = {
+    POS_X: 0, POS_Y: 1, POS_Z: 2, HEADING: 3,
+    ROT_X: 4, ROT_Y: 5, ROT_Z: 6, ROT_W: 7,
+    HEALTH: 8, MAX_HEALTH: 9,
+    HUNGER: 10, THIRST: 11,
+    OXYGEN: 12, MAX_OXYGEN: 13,
+    TEMPERATURE: 14,
+    CAMERA_MODE: 15,
+    ACTIVE_SLOT: 16,
+    FLAGS: 17,
+    ENTITY_ID: 18,
+    PLAYER_ID: 19,
+    VIEWPORT_X: 20, VIEWPORT_Y: 21,
+    VIEWPORT_W: 22, VIEWPORT_H: 23,
+    PITCH: 24,
+    FREECAM_X: 25, FREECAM_Y: 26, FREECAM_Z: 27,
+    FREECAM_PITCH: 28, FREECAM_YAW: 29,
+    THIRD_PERSON_DISTANCE: 30,
+    // Indices 31–63 are reserved for game-specific player state.
+    // Games define their own extension constants (e.g. GAME_PLR.GOLD = 31).
+};
+export const PLR_FLAG = {
+    SLEEPING: 1 << 0,
+    DEAD: 1 << 1,
+    UNDERWATER: 1 << 2,
+    ONBOARD: 1 << 3,
+    SWIMMING: 1 << 4,
+    FISHING: 1 << 5,
+    PILOTING: 1 << 6,
+    CLIMBING: 1 << 7,
+    NOCLIP: 1 << 8,
+    GROUNDED: 1 << 9,
+};
+export function allocateSimBuffer() {
+    return SimChannel.allocate();
+}
+export function allocateInputBuffer() {
+    return InputChannel.allocate();
+}
+// --- Sim Buffer Reader (renderer side) ---
+export class SimBufferReader {
+    reader;
+    entitySlots;
+    playerSlots;
+    constructor(sab) {
+        this.reader = SimChannel.reader(sab);
+        this.entitySlots = this.reader.sections.entities;
+        this.playerSlots = this.reader.sections.players;
+    }
+    isValid() {
+        return this.reader.isValid();
+    }
+    validationError() {
+        return this.reader.validationError();
+    }
+    getTick() { return this.reader.header.u32[SimChannel.offsets.header.tick]; }
+    getSequence() { return this.reader.getSequence(); }
+    getEntityCount() { return this.reader.header.u32[SimChannel.offsets.header.entityCount]; }
+    getPlayerCount() { return this.reader.header.u32[SimChannel.offsets.header.playerCount]; }
+    getTimeOfDay() { return this.reader.header.f32[SimChannel.offsets.header.timeOfDay]; }
+    getWeatherType() { return this.reader.header.u32[SimChannel.offsets.header.weatherType]; }
+    getWeatherIntensity() { return this.reader.header.f32[SimChannel.offsets.header.weatherIntensity]; }
+    getWindSpeed() { return this.reader.header.f32[SimChannel.offsets.header.windSpeed]; }
+    pooledWindDir = { x: 0, z: 0 };
+    getWindDir() {
+        const dir = this.pooledWindDir;
+        dir.x = this.reader.header.f32[SimChannel.offsets.header.windDirX];
+        dir.z = this.reader.header.f32[SimChannel.offsets.header.windDirZ];
+        return dir;
+    }
+    getVisibility() { return this.reader.header.f32[SimChannel.offsets.header.visibility]; }
+    getAmbientTemp() { return this.reader.header.f32[SimChannel.offsets.header.ambientTemp]; }
+    getActivePlayers() { return this.reader.header.u32[SimChannel.offsets.header.activePlayers]; }
+    getGamemode() { return this.reader.header.u32[SimChannel.offsets.header.gamemode]; }
+    getPhysicsInitialized() { return this.reader.header.u32[SimChannel.offsets.header.physicsInitialized]; }
+    getPhysicsFailed() { return this.reader.header.u32[SimChannel.offsets.header.physicsFailed]; }
+    getPhysicsBodyCount() { return this.reader.header.u32[SimChannel.offsets.header.physicsBodyCount]; }
+    getPhysicsTickCount() { return this.reader.header.u32[SimChannel.offsets.header.physicsTickCount]; }
+    getChunkCount() { return this.reader.header.u32[SimChannel.offsets.header.chunkCount]; }
+    getPhysicsProfilerEnabled() { return this.reader.header.u32[SimChannel.offsets.header.physicsProfilerEnabled] === 1; }
+    getPhysicsTiming() {
+        if (!this.getPhysicsProfilerEnabled())
+            return null;
+        const h = this.reader.header.f32;
+        const o = SimChannel.offsets.header;
+        return {
+            step: h[o.physTimingStep],
+            collisionDetection: h[o.physTimingCollisionDetection],
+            broadPhase: h[o.physTimingBroadPhase],
+            narrowPhase: h[o.physTimingNarrowPhase],
+            solver: h[o.physTimingSolver],
+            velocityAssembly: h[o.physTimingVelocityAssembly],
+            velocityResolution: h[o.physTimingVelocityResolution],
+            velocityUpdate: h[o.physTimingVelocityUpdate],
+            velocityWriteback: h[o.physTimingVelocityWriteback],
+            ccd: h[o.physTimingCcd],
+            ccdToiComputation: h[o.physTimingCcdToiComputation],
+            ccdBroadPhase: h[o.physTimingCcdBroadPhase],
+            ccdNarrowPhase: h[o.physTimingCcdNarrowPhase],
+            ccdSolver: h[o.physTimingCcdSolver],
+            islandConstruction: h[o.physTimingIslandConstruction],
+            userChanges: h[o.physTimingUserChanges],
+        };
+    }
+    getEntitySlot(idx) {
+        const sv = this.entitySlots.slot(idx);
+        return { f32: sv.f32, u32: sv.u32 };
+    }
+    /** Direct slot access — returns cached SlotViews without allocating a wrapper object. */
+    getEntitySlotDirect(idx) {
+        return this.entitySlots.slot(idx);
+    }
+    getPlayerSlot(idx) {
+        const sv = this.playerSlots.slot(idx);
+        return { f32: sv.f32, u32: sv.u32 };
+    }
+    *iterEntities() {
+        const count = this.getEntityCount();
+        for (let i = 0; i < count; i++) {
+            const sv = this.entitySlots.slot(i);
+            yield { idx: i, f32: sv.f32, u32: sv.u32 };
+        }
+    }
+}
+// --- Sim Buffer Writer (sim worker side) ---
+export class SimBufferWriter {
+    writer;
+    entitySlots;
+    playerSlots;
+    // Dirty flags: 1 = entity/player slot has changed since last writeToBuffer.
+    // writeToBuffer skips slots where the flag is 0. Cleared after each writeToBuffer.
+    dirtyEntities;
+    dirtyPlayers;
+    constructor(sab) {
+        this.writer = SimChannel.writer(sab);
+        this.entitySlots = this.writer.sections.entities;
+        this.playerSlots = this.writer.sections.players;
+        this.dirtyEntities = new Uint8Array(MAX_ENTITIES);
+        this.dirtyPlayers = new Uint8Array(MAX_PLAYERS);
+    }
+    init() {
+        const w = this.writer;
+        const h = SimChannel.offsets.header;
+        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;
+    }
+    setEntityCount(n) { this.writer.header.u32[SimChannel.offsets.header.entityCount] = n; }
+    setPlayerCount(n) { this.writer.header.u32[SimChannel.offsets.header.playerCount] = n; }
+    setTimeOfDay(t) { this.writer.header.f32[SimChannel.offsets.header.timeOfDay] = t; }
+    setWeather(type, intensity) {
+        this.writer.header.u32[SimChannel.offsets.header.weatherType] = type;
+        this.writer.header.f32[SimChannel.offsets.header.weatherIntensity] = intensity;
+    }
+    setWind(speed, dirX, dirZ) {
+        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) { this.writer.header.f32[SimChannel.offsets.header.visibility] = v; }
+    setAmbientTemp(t) { this.writer.header.f32[SimChannel.offsets.header.ambientTemp] = t; }
+    setActivePlayers(mask) { this.writer.header.u32[SimChannel.offsets.header.activePlayers] = mask; }
+    setGamemode(mode) { this.writer.header.u32[SimChannel.offsets.header.gamemode] = mode; }
+    setPhysicsInitialized(v) { this.writer.header.u32[SimChannel.offsets.header.physicsInitialized] = v; }
+    setPhysicsFailed(v) { this.writer.header.u32[SimChannel.offsets.header.physicsFailed] = v; }
+    setPhysicsBodyCount(v) { this.writer.header.u32[SimChannel.offsets.header.physicsBodyCount] = v; }
+    setPhysicsTickCount(v) { this.writer.header.u32[SimChannel.offsets.header.physicsTickCount] = v; }
+    setChunkCount(v) { this.writer.header.u32[SimChannel.offsets.header.chunkCount] = v; }
+    setPhysicsProfilerEnabled(v) { this.writer.header.u32[SimChannel.offsets.header.physicsProfilerEnabled] = v; }
+    setPhysicsTiming(data) {
+        const h = this.writer.header.f32;
+        const o = SimChannel.offsets.header;
+        h[o.physTimingStep] = data.step;
+        h[o.physTimingCollisionDetection] = data.collisionDetection;
+        h[o.physTimingBroadPhase] = data.broadPhase;
+        h[o.physTimingNarrowPhase] = data.narrowPhase;
+        h[o.physTimingSolver] = data.solver;
+        h[o.physTimingVelocityAssembly] = data.velocityAssembly;
+        h[o.physTimingVelocityResolution] = data.velocityResolution;
+        h[o.physTimingVelocityUpdate] = data.velocityUpdate;
+        h[o.physTimingVelocityWriteback] = data.velocityWriteback;
+        h[o.physTimingCcd] = data.ccd;
+        h[o.physTimingCcdToiComputation] = data.ccdToiComputation;
+        h[o.physTimingCcdBroadPhase] = data.ccdBroadPhase;
+        h[o.physTimingCcdNarrowPhase] = data.ccdNarrowPhase;
+        h[o.physTimingCcdSolver] = data.ccdSolver;
+        h[o.physTimingIslandConstruction] = data.islandConstruction;
+        h[o.physTimingUserChanges] = data.userChanges;
+    }
+    incrementTick() {
+        const h = SimChannel.offsets.header;
+        Atomics.add(this.writer.header.u32, h.tick, 1);
+        this.writer.bumpSequence();
+    }
+    markEntityDirty(slot) {
+        this.dirtyEntities[slot] = 1;
+    }
+    markPlayerDirty(slot) {
+        this.dirtyPlayers[slot] = 1;
+    }
+    isEntityDirty(slot) {
+        return this.dirtyEntities[slot] !== 0;
+    }
+    isPlayerDirty(slot) {
+        return this.dirtyPlayers[slot] !== 0;
+    }
+    clearDirty() {
+        this.dirtyEntities.fill(0);
+        this.dirtyPlayers.fill(0);
+    }
+    // Mark all entities and players dirty (used on initial write or full re-sync).
+    markAllDirty() {
+        this.dirtyEntities.fill(1);
+        this.dirtyPlayers.fill(1);
+    }
+    getEntityF32(idx) {
+        return this.entitySlots.slot(idx).f32;
+    }
+    getEntityU32(idx) {
+        return this.entitySlots.slot(idx).u32;
+    }
+    getPlayerF32(idx) {
+        return this.playerSlots.slot(idx).f32;
+    }
+    getPlayerU32(idx) {
+        return this.playerSlots.slot(idx).u32;
+    }
+}

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

@@ -0,0 +1,140 @@
+import { describeHeaderValidation, isDebug, warnOnce } from "./errors.js";
+function createHeaderViews(sab, headerSize) {
+    const u32Length = headerSize / 4;
+    return {
+        u32: new Uint32Array(sab, 0, u32Length),
+        i32: new Int32Array(sab, 0, u32Length),
+        f32: new Float32Array(sab, 0, u32Length),
+        f64: new Float64Array(sab, 0, Math.floor(headerSize / 8)),
+    };
+}
+class SlotAccessorImpl {
+    sab;
+    cache;
+    _maxSlots;
+    _slotSize;
+    _slotStride;
+    _byteOffset;
+    sectionName;
+    constructor(sab, byteOffset, maxSlots, slotSize, slotStride, sectionName) {
+        this.sab = sab;
+        this._byteOffset = byteOffset;
+        this._maxSlots = maxSlots;
+        this._slotSize = slotSize;
+        this._slotStride = slotStride;
+        this.sectionName = sectionName;
+        this.cache = new Array(maxSlots).fill(null);
+    }
+    get maxSlots() { return this._maxSlots; }
+    get slotSize() { return this._slotSize; }
+    get slotStride() { return this._slotStride; }
+    get byteOffset() { return this._byteOffset; }
+    slot(index) {
+        if (index < 0 || index >= this._maxSlots) {
+            if (isDebug()) {
+                warnOnce(`slot-oob-${this.sectionName}-${index}`, `Slot index ${index} out of range [0, ${this._maxSlots}) for section "${this.sectionName}"`);
+            }
+            throw new RangeError(`Slot index ${index} out of range [0, ${this._maxSlots}) for section "${this.sectionName}"`);
+        }
+        let views = this.cache[index];
+        if (views)
+            return views;
+        const base = this._byteOffset + index * this._slotSize;
+        const f32Len = this._slotSize / 4;
+        views = {
+            f32: new Float32Array(this.sab, base, f32Len),
+            u32: new Uint32Array(this.sab, base, f32Len),
+            i32: new Int32Array(this.sab, base, f32Len),
+            f64: new Float64Array(this.sab, base, Math.floor(this._slotSize / 8)),
+        };
+        this.cache[index] = views;
+        return views;
+    }
+}
+export class SlotReader {
+    header;
+    sections;
+    seqArr;
+    layout;
+    constructor(sab, layout) {
+        this.layout = layout;
+        this.header = createHeaderViews(sab, layout.header.size);
+        this.seqArr = new Int32Array(sab, layout.header.sequenceIndex * 4, 1);
+        this.sections = {};
+        if (layout.sections) {
+            layout.sections.forEach((section) => {
+                this.sections[section.name] = new SlotAccessorImpl(sab, section.byteOffset, section.maxSlots, section.slotSize, section.slotStride, section.name);
+            });
+        }
+    }
+    isValid() {
+        return this.validationError() === null;
+    }
+    validationError() {
+        return describeHeaderValidation(this.header.u32, this.layout.header.magicIndex, this.layout.header.versionIndex, this.layout.magic, this.layout.version);
+    }
+    getSequence() {
+        return Atomics.load(this.seqArr, 0);
+    }
+    hasChanged(lastSeen) {
+        return this.getSequence() !== lastSeen;
+    }
+    snapshot() {
+        const data = {};
+        data["sequence"] = this.getSequence();
+        if (this.layout.sections) {
+            this.layout.sections.forEach((section) => {
+                const accessor = this.sections[section.name];
+                const slots = [];
+                const count = this.header.u32[0 + 4];
+                for (let i = 0; i < Math.min(count, section.maxSlots); i++) {
+                    const slot = accessor.slot(i);
+                    const slotData = {};
+                    for (const [fname, flayout] of Object.entries(section.fields)) {
+                        const view = flayout.type === "f32" || flayout.type === "f64" ? slot.f32 : slot.u32;
+                        if (flayout.count === 1) {
+                            slotData[fname] = view[flayout.index];
+                        }
+                        else {
+                            const arr = [];
+                            for (let j = 0; j < flayout.count; j++) {
+                                arr.push(view[flayout.index + j]);
+                            }
+                            slotData[fname] = arr;
+                        }
+                    }
+                    slots.push(slotData);
+                }
+                data[section.name] = slots;
+            });
+        }
+        return data;
+    }
+}
+export class SlotWriter {
+    header;
+    sections;
+    seqArr;
+    layout;
+    constructor(sab, layout) {
+        this.layout = layout;
+        this.header = createHeaderViews(sab, layout.header.size);
+        this.seqArr = new Int32Array(sab, layout.header.sequenceIndex * 4, 1);
+        this.sections = {};
+        if (layout.sections) {
+            layout.sections.forEach((section) => {
+                this.sections[section.name] = new SlotAccessorImpl(sab, section.byteOffset, section.maxSlots, section.slotSize, section.slotStride, section.name);
+            });
+        }
+    }
+    init() {
+        this.header.u32[this.layout.header.magicIndex] = this.layout.magic;
+        this.header.u32[this.layout.header.versionIndex] = this.layout.version;
+    }
+    bumpSequence() {
+        Atomics.add(this.seqArr, 0, 1);
+    }
+    getSequence() {
+        return Atomics.load(this.seqArr, 0);
+    }
+}

package/dist/core/src/sab/types.js

@@ -0,0 +1 @@
+export {};

package/dist/core/src/safety/bounds.js

@@ -0,0 +1,71 @@
+/**
+ * Safety bounds for asset parser validation.
+ * These limits prevent decompression bombs, OOM, and integer overflow from
+ * malformed or malicious files.
+ */
+export const MAX_VERTEX_COUNT = 50_000_000;
+export const MAX_FACE_COUNT = 100_000_000;
+export const MAX_TEXTURE_DIM = 16384;
+export const MAX_MIP_LEVELS = 16;
+export const MAX_DECOMPRESS_SIZE = 512 * 1024 * 1024; // 512 MB
+export const MAX_FETCH_SIZE = 256 * 1024 * 1024; // 256 MB
+export const MAX_NODE_DEPTH = 64;
+export const MAX_ARRAY_LENGTH = 100_000_000;
+/**
+ * Asserts that `offset + length` does not exceed `max`.
+ * Throws a `RangeError` with a descriptive message if violated.
+ */
+export function assertBounds(name, offset, length, max) {
+    if (offset < 0 || length < 0) {
+        throw new RangeError(`${name}: negative offset (${offset}) or length (${length})`);
+    }
+    if (offset + length > max) {
+        throw new RangeError(`${name}: offset ${offset} + length ${length} exceeds max ${max}`);
+    }
+}
+/**
+ * Asserts that `count` is a non-negative integer not exceeding `max`.
+ * Throws a `RangeError` if violated.
+ */
+export function assertCount(name, count, max) {
+    if (!Number.isInteger(count) || count < 0) {
+        throw new RangeError(`${name}: count ${count} is not a non-negative integer`);
+    }
+    if (count > max) {
+        throw new RangeError(`${name}: count ${count} exceeds max ${max}`);
+    }
+}
+/**
+ * Asserts that `value` is a finite number (not NaN, not Infinity).
+ * Throws a `RangeError` if violated.
+ */
+export function assertFinite(name, value) {
+    if (!Number.isFinite(value)) {
+        throw new RangeError(`${name}: value ${value} is not finite`);
+    }
+}
+/**
+ * Asserts that `value` is a positive finite number.
+ * Throws a `RangeError` if violated.
+ */
+export function assertPositive(name, value) {
+    assertFinite(name, value);
+    if (value <= 0) {
+        throw new RangeError(`${name}: value ${value} is not positive`);
+    }
+}
+/**
+ * Clamps a value to `[min, max]`.
+ */
+export function clamp(value, min, max) {
+    return Math.max(min, Math.min(max, value));
+}
+/**
+ * Clamps a value to `[0, Number.MAX_SAFE_INTEGER]`.
+ * Useful for gold/currency/quantity values.
+ */
+export function clampSafeInt(value) {
+    if (!Number.isFinite(value))
+        return 0;
+    return Math.max(0, Math.min(value, Number.MAX_SAFE_INTEGER));
+}