@downdraft/engine 0.0.0 → 0.1.0

package/core/src/sab/game-input.ts

@@ -0,0 +1,343 @@
+// ============================================================================
+// Game Input Buffer — SharedArrayBuffer for per-player input state
+// Multi-player slot-based input channel with keys, mouse, gamepad, and builder state.
+// ============================================================================
+
+import { defineChannel } from "./define";
+
+export const MAX_INPUT_PLAYERS = 4;
+
+export const InputChannel = defineChannel({
+  name: "game-input",
+  magic: 0x494e5054,
+  version: 1,
+  mode: "slots",
+  header: {
+    size: 64,
+    fields: {
+      playerCount: { type: "u32" },
+    },
+  },
+  sections: [
+    {
+      name: "players",
+      maxSlots: MAX_INPUT_PLAYERS,
+      slotSize: 128,
+      fields: {
+        keys: { type: "u32", count: 8 },
+        mouseX: { type: "f32" },
+        mouseY: { type: "f32" },
+        mouseBtn: { type: "u32" },
+        wheel: { type: "f32" },
+        gpAxes: { type: "f32", count: 8 },
+        gpBtn: { type: "u32" },
+        flags: { type: "u32" },
+        mouseDx: { type: "f32" },
+        mouseDy: { type: "f32" },
+        cameraZoom: { type: "f32" },
+        lookHeading: { type: "f32" },
+        lookPitch: { type: "f32" },
+        builderCellType: { type: "u32" },
+        builderRotation: { type: "u32" },
+      },
+    },
+  ],
+});
+
+export const INPUT_MAGIC = 0x494e5054;
+export const INPUT_VERSION = 1;
+
+export const INP_HDR = {
+  MAGIC: 0,
+  VERSION: 1,
+  PLAYER_COUNT: 3,
+  SEQUENCE: 2,
+} as const;
+
+export const INP = {
+  KEYS: 0,
+  MOUSE_X: 8,
+  MOUSE_Y: 9,
+  MOUSE_BTN: 10,
+  WHEEL: 11,
+  GP_AXES: 12,
+  GP_BTN: 20,
+  FLAGS: 21,
+  MOUSE_DX: 22,
+  MOUSE_DY: 23,
+  CAMERA_ZOOM: 24,
+  LOOK_HEADING: 25,
+  LOOK_PITCH: 26,
+  BUILDER_CELL_TYPE: 27,
+  BUILDER_ROTATION: 28,
+} as const;
+
+export const INP_FLAG = {
+  CONNECTED: 1 << 0,
+  HAS_GAMEPAD: 1 << 1,
+} as const;
+
+export const KEY = {
+  W: 87, A: 65, S: 83, D: 68,
+  Q: 81, E: 69, R: 82, F: 70,
+  SHIFT: 16, CTRL: 17, ALT: 18, TAB: 9,
+  SPACE: 32, ENTER: 13, ESC: 27,
+  ONE: 49, TWO: 50, THREE: 51, FOUR: 52,
+  FIVE: 53, SIX: 54, SEVEN: 55, EIGHT: 56,
+  NINE: 57, ZERO: 48,
+  I: 73, B: 66, C: 67, M: 77, P: 80,
+  T: 84, V: 86, Z: 90, X: 88,
+  UP: 38, DOWN: 40, LEFT: 37, RIGHT: 39,
+  F1: 112, F2: 113, F3: 114, F4: 115, F5: 116, F6: 117,
+  F7: 118, F8: 119, F9: 120, F10: 121, F11: 122, F12: 123,
+  BRACKET_LEFT: 219,
+  BRACKET_RIGHT: 221,
+} as const;
+
+export class InputBufferWriter {
+  private writer: ReturnType<typeof InputChannel.writer>;
+  private slots: ReturnType<typeof InputChannel.writer>["sections"]["players"];
+
+  constructor(sab: SharedArrayBuffer) {
+    this.writer = InputChannel.writer(sab);
+    this.slots = this.writer.sections.players;
+  }
+
+  init() {
+    this.writer.header.u32[InputChannel.offsets.header.playerCount] = 0;
+  }
+
+  setPlayerCount(n: number) { this.writer.header.u32[InputChannel.offsets.header.playerCount] = n; }
+
+  incrementSequence() { this.writer.bumpSequence(); }
+
+  private slot(playerIdx: number) {
+    return this.slots.slot(playerIdx);
+  }
+
+  setKey(playerIdx: number, keyCode: number, pressed: boolean) {
+    const sv = this.slot(playerIdx);
+    const f = InputChannel.offsets.sections.players.fields;
+    const wordIdx = Math.floor(keyCode / 32);
+    const bitIdx = keyCode % 32;
+    if (pressed) {
+      sv.u32[f.keys + wordIdx] |= (1 << bitIdx);
+    } else {
+      sv.u32[f.keys + wordIdx] &= ~(1 << bitIdx);
+    }
+  }
+
+  setMousePos(playerIdx: number, x: number, y: number) {
+    const sv = this.slot(playerIdx);
+    const f = InputChannel.offsets.sections.players.fields;
+    sv.f32[f.mouseX] = x;
+    sv.f32[f.mouseY] = y;
+  }
+
+  setMouseButton(playerIdx: number, button: number, pressed: boolean) {
+    const sv = this.slot(playerIdx);
+    const f = InputChannel.offsets.sections.players.fields;
+    if (pressed) {
+      sv.u32[f.mouseBtn] |= (1 << button);
+    } else {
+      sv.u32[f.mouseBtn] &= ~(1 << button);
+    }
+  }
+
+  setWheel(playerIdx: number, delta: number) {
+    const sv = this.slot(playerIdx);
+    const f = InputChannel.offsets.sections.players.fields;
+    // Absolute per-flush value, not an accumulation — the reader never
+    // clears this field (single-writer rule); the writer owns it outright.
+    sv.f32[f.wheel] = delta;
+  }
+
+  setMouseDelta(playerIdx: number, dx: number, dy: number) {
+    const sv = this.slot(playerIdx);
+    const f = InputChannel.offsets.sections.players.fields;
+    sv.f32[f.mouseDx] = dx;
+    sv.f32[f.mouseDy] = dy;
+  }
+
+  setGamepadAxis(playerIdx: number, axis: number, value: number) {
+    const sv = this.slot(playerIdx);
+    const f = InputChannel.offsets.sections.players.fields;
+    sv.f32[f.gpAxes + axis] = value;
+  }
+
+  setGamepadButton(playerIdx: number, button: number, pressed: boolean) {
+    const sv = this.slot(playerIdx);
+    const f = InputChannel.offsets.sections.players.fields;
+    if (pressed) {
+      sv.u32[f.gpBtn] |= (1 << button);
+    } else {
+      sv.u32[f.gpBtn] &= ~(1 << button);
+    }
+  }
+
+  setFlags(playerIdx: number, flags: number) {
+    const sv = this.slot(playerIdx);
+    const f = InputChannel.offsets.sections.players.fields;
+    sv.u32[f.flags] = flags;
+  }
+
+  setCameraZoom(playerIdx: number, zoom: number) {
+    const sv = this.slot(playerIdx);
+    const f = InputChannel.offsets.sections.players.fields;
+    sv.f32[f.cameraZoom] = zoom;
+  }
+
+  setLookHeading(playerIdx: number, heading: number) {
+    const sv = this.slot(playerIdx);
+    const f = InputChannel.offsets.sections.players.fields;
+    sv.f32[f.lookHeading] = heading;
+  }
+
+  setLookPitch(playerIdx: number, pitch: number) {
+    const sv = this.slot(playerIdx);
+    const f = InputChannel.offsets.sections.players.fields;
+    sv.f32[f.lookPitch] = pitch;
+  }
+
+  setBuilderCellType(playerIdx: number, cellTypeIdx: number) {
+    const sv = this.slot(playerIdx);
+    const f = InputChannel.offsets.sections.players.fields;
+    sv.u32[f.builderCellType] = cellTypeIdx;
+  }
+
+  setBuilderRotation(playerIdx: number, rotation: number) {
+    const sv = this.slot(playerIdx);
+    const f = InputChannel.offsets.sections.players.fields;
+    sv.u32[f.builderRotation] = rotation;
+  }
+}
+
+export class InputBufferReader {
+  private reader: ReturnType<typeof InputChannel.reader>;
+  private slots: ReturnType<typeof InputChannel.reader>["sections"]["players"];
+
+  constructor(sab: SharedArrayBuffer) {
+    this.reader = InputChannel.reader(sab);
+    this.slots = this.reader.sections.players;
+  }
+
+  isValid(): boolean {
+    return this.reader.isValid();
+  }
+
+  validationError(): string | null {
+    return this.reader.validationError();
+  }
+
+  getSequence(): number { return this.reader.getSequence(); }
+  getPlayerCount(): number { return this.reader.header.u32[InputChannel.offsets.header.playerCount]; }
+
+  private slot(playerIdx: number) {
+    return this.slots.slot(playerIdx);
+  }
+
+  isKeyDown(playerIdx: number, keyCode: number): boolean {
+    const sv = this.slot(playerIdx);
+    const f = InputChannel.offsets.sections.players.fields;
+    const wordIdx = Math.floor(keyCode / 32);
+    const bitIdx = keyCode % 32;
+    return (sv.u32[f.keys + wordIdx] & (1 << bitIdx)) !== 0;
+  }
+
+  getMousePos(playerIdx: number): { x: number; y: number } {
+    const sv = this.slot(playerIdx);
+    const f = InputChannel.offsets.sections.players.fields;
+    return { x: sv.f32[f.mouseX], y: sv.f32[f.mouseY] };
+  }
+
+  isMouseDown(playerIdx: number, button: number): boolean {
+    const sv = this.slot(playerIdx);
+    const f = InputChannel.offsets.sections.players.fields;
+    return (sv.u32[f.mouseBtn] & (1 << button)) !== 0;
+  }
+
+  getWheel(playerIdx: number): number {
+    const sv = this.slot(playerIdx);
+    const f = InputChannel.offsets.sections.players.fields;
+    return sv.f32[f.wheel];
+  }
+
+  // Sequence-gated consumption state. Transient fields (wheel, mouseDelta)
+  // are writer-owned: the reader must NEVER write into a slot (that would
+  // make the region two-writer — a lost-update race on real SAB and a
+  // protocol violation under the polyfill's whole-region sync). Instead the
+  // reader yields each written value exactly once per writer sequence bump.
+  private lastWheelSeq = new Uint32Array(MAX_INPUT_PLAYERS).fill(0xffffffff);
+  private lastMouseDeltaSeq = new Uint32Array(MAX_INPUT_PLAYERS).fill(0xffffffff);
+
+  consumeWheel(playerIdx: number): number {
+    const seq = this.reader.getSequence();
+    if (seq === this.lastWheelSeq[playerIdx]) return 0;
+    this.lastWheelSeq[playerIdx] = seq;
+    const sv = this.slot(playerIdx);
+    return sv.f32[InputChannel.offsets.sections.players.fields.wheel];
+  }
+
+  getMouseDelta(playerIdx: number): { dx: number; dy: number } {
+    const sv = this.slot(playerIdx);
+    const f = InputChannel.offsets.sections.players.fields;
+    return { dx: sv.f32[f.mouseDx], dy: sv.f32[f.mouseDy] };
+  }
+
+  consumeMouseDelta(playerIdx: number): { dx: number; dy: number } {
+    const seq = this.reader.getSequence();
+    if (seq === this.lastMouseDeltaSeq[playerIdx]) return { dx: 0, dy: 0 };
+    this.lastMouseDeltaSeq[playerIdx] = seq;
+    const sv = this.slot(playerIdx);
+    const f = InputChannel.offsets.sections.players.fields;
+    return { dx: sv.f32[f.mouseDx], dy: sv.f32[f.mouseDy] };
+  }
+
+  getGamepadAxis(playerIdx: number, axis: number): number {
+    const sv = this.slot(playerIdx);
+    const f = InputChannel.offsets.sections.players.fields;
+    return sv.f32[f.gpAxes + axis];
+  }
+
+  isGamepadButtonDown(playerIdx: number, button: number): boolean {
+    const sv = this.slot(playerIdx);
+    const f = InputChannel.offsets.sections.players.fields;
+    return (sv.u32[f.gpBtn] & (1 << button)) !== 0;
+  }
+
+  getFlags(playerIdx: number): number {
+    const sv = this.slot(playerIdx);
+    const f = InputChannel.offsets.sections.players.fields;
+    return sv.u32[f.flags];
+  }
+
+  getCameraZoom(playerIdx: number): number {
+    const sv = this.slot(playerIdx);
+    const f = InputChannel.offsets.sections.players.fields;
+    return sv.f32[f.cameraZoom];
+  }
+
+  getLookHeading(playerIdx: number): number {
+    const sv = this.slot(playerIdx);
+    const f = InputChannel.offsets.sections.players.fields;
+    return sv.f32[f.lookHeading];
+  }
+
+  getLookPitch(playerIdx: number): number {
+    const sv = this.slot(playerIdx);
+    const f = InputChannel.offsets.sections.players.fields;
+    return sv.f32[f.lookPitch];
+  }
+
+  getBuilderCellType(playerIdx: number): number {
+    const sv = this.slot(playerIdx);
+    const f = InputChannel.offsets.sections.players.fields;
+    return sv.u32[f.builderCellType];
+  }
+
+  getBuilderRotation(playerIdx: number): number {
+    const sv = this.slot(playerIdx);
+    const f = InputChannel.offsets.sections.players.fields;
+    return sv.u32[f.builderRotation];
+  }
+}

package/core/src/sab/gamepad-devices.ts

@@ -0,0 +1,259 @@
+// ============================================================================
+// Gamepad Devices Buffer — per-device gamepad metadata + state
+// Writer: the native downdraft_gamepad cdylib worker thread (Rust) writes every
+//   field EXCEPT `hostMeta`, which is owned by JS sysfs/enrichment code.
+// Readers: renderer/main thread (device discovery, nav, enrichment output).
+//
+// This channel is a *device table* — identity, connection, battery, name — and
+// a raw-state mirror. Per-player routed input lives in MultiInputChannel.
+// ============================================================================
+
+import { defineChannel } from "./define";
+
+export const GAMEPAD_DEVICES_MAGIC = 0x50474444; // "DDGP"
+export const GAMEPAD_DEVICES_VERSION = 1;
+export const GAMEPAD_MAX_SLOTS = 16;
+
+/** Pad classification written by the native backend (mirrors Rust pad_type). */
+export const PadType = {
+  UNKNOWN: 0,
+  XBOX: 1,
+  PS3: 2,
+  PS4: 3,
+  PS5: 4,
+  SWITCH: 5,
+  GAMECUBE: 6,
+  N64: 7,
+  WIIMOTE: 8,
+  STEAM: 9,
+  GENERIC: 10,
+} as const;
+export type PadTypeValue = (typeof PadType)[keyof typeof PadType];
+
+/** Connection classification (mirrors Rust conn_type). */
+export const PadConnType = {
+  UNKNOWN: 0,
+  WIRED: 1,
+  BLUETOOTH: 2,
+  DONGLE: 3,
+} as const;
+export type PadConnTypeValue = (typeof PadConnType)[keyof typeof PadConnType];
+
+/** meta1 flag bits. */
+export const PAD_FLAG = {
+  FF_SUPPORTED: 1 << 0,
+  CHARGING: 1 << 1,
+  AUX_DEVICE: 1 << 2,
+} as const;
+
+/** Battery sentinels (meta0 >> 24). */
+export const PAD_BATTERY_UNKNOWN = 255;
+export const PAD_BATTERY_WIRED = 254;
+
+/** Standard-layout button bitmask (buttonsLo; buttonsHi is reserved for
+ *  touchpad/paddle/misc). Bit indices match W3C standard mapping order. */
+export const GP_BTN = {
+  SOUTH: 0,
+  EAST: 1,
+  WEST: 2,
+  NORTH: 3,
+  LEFT_SHOULDER: 4,
+  RIGHT_SHOULDER: 5,
+  LEFT_TRIGGER_BTN: 6,
+  RIGHT_TRIGGER_BTN: 7,
+  SELECT: 8,
+  START: 9,
+  HOME: 10,
+  LEFT_STICK: 11,
+  RIGHT_STICK: 12,
+  DPAD_UP: 13,
+  DPAD_DOWN: 14,
+  DPAD_LEFT: 15,
+  DPAD_RIGHT: 16,
+  C: 17,
+  Z: 18,
+  CAPTURE: 19,
+} as const;
+
+/** Axis indices in axes[8]. */
+export const GP_AXIS = {
+  LEFT_X: 0,
+  LEFT_Y: 1,
+  RIGHT_X: 2,
+  RIGHT_Y: 3,
+  LEFT_TRIGGER: 4,
+  RIGHT_TRIGGER: 5,
+  DPAD_X: 6,
+  DPAD_Y: 7,
+} as const;
+
+export const GamepadDevicesChannel = defineChannel({
+  name: "gamepad-devices",
+  magic: GAMEPAD_DEVICES_MAGIC,
+  version: GAMEPAD_DEVICES_VERSION,
+  mode: "slots",
+  header: {
+    size: 64,
+    fields: {
+      connectedMask: { type: "u32" },
+    },
+  },
+  sections: [
+    {
+      name: "pads",
+      maxSlots: GAMEPAD_MAX_SLOTS,
+      slotSize: 128,
+      // Field order is the ABI — must stay in sync with
+      // packages/platform-native/native-gamepad/src/lib.rs SLOT_* offsets.
+      fields: {
+        meta0: { type: "u32" }, // connected | padType<<8 | connType<<16 | battery<<24
+        meta1: { type: "u32" }, // PAD_FLAG_*
+        hostMeta: { type: "u32" }, // rssi | jsFlags<<8 | reserved — JS writes this
+        buttonsLo: { type: "u32" },
+        buttonsHi: { type: "u32" },
+        axes: { type: "f32", count: 8 },
+        lastEventMs: { type: "u32" },
+        slotSeq: { type: "u32" },
+        vendorId: { type: "u32" },
+        productId: { type: "u32" },
+        name: { type: "u32", count: 14 }, // 56 B NUL-padded UTF-8
+        aux: { type: "u32" }, // Linux: /dev/input/eventN index; 0xFFFF unknown
+      },
+    },
+  ],
+});
+
+export type GamepadDevicesChannelInstance = typeof GamepadDevicesChannel;
+
+/** Decoded view of one pad slot. */
+export interface GamepadDeviceSlot {
+  slot: number;
+  connected: boolean;
+  padType: PadTypeValue;
+  connType: PadConnTypeValue;
+  /** 0..100, or PAD_BATTERY_UNKNOWN / PAD_BATTERY_WIRED. */
+  battery: number;
+  rssi: number; // 0..100, 255 = unknown
+  flags: number;
+  buttonsLo: number;
+  buttonsHi: number;
+  axes: Float32Array;
+  lastEventMs: number;
+  slotSeq: number;
+  vendorId: number;
+  productId: number;
+  name: string;
+  /** Linux /dev/input/eventN index for sysfs correlation; -1 when unknown. */
+  eventNode: number;
+}
+
+const textDecoder = new TextDecoder();
+
+/**
+ * Reader for the device table. Construct per-thread over the shared buffer;
+ * call `readSlot`/`readConnected` from the consuming side only.
+ */
+export class GamepadDevicesReader {
+  private reader: ReturnType<typeof GamepadDevicesChannel.reader>;
+  private pads: ReturnType<typeof GamepadDevicesChannel.reader>["sections"]["pads"];
+
+  constructor(sab: SharedArrayBuffer) {
+    this.reader = GamepadDevicesChannel.reader(sab);
+    this.pads = this.reader.sections.pads;
+  }
+
+  isValid(): boolean {
+    return this.reader.isValid();
+  }
+
+  validationError(): string | null {
+    return this.reader.validationError();
+  }
+
+  getSequence(): number {
+    return this.reader.getSequence();
+  }
+
+  hasChanged(lastSeen: number): boolean {
+    return this.reader.hasChanged(lastSeen);
+  }
+
+  getConnectedMask(): number {
+    return this.reader.header.u32[GamepadDevicesChannel.offsets.header.connectedMask];
+  }
+
+  private slotViews(slot: number) {
+    return this.pads.slot(slot);
+  }
+
+  readSlot(slot: number, out?: Partial<GamepadDeviceSlot>): GamepadDeviceSlot | null {
+    const f = GamepadDevicesChannel.offsets.sections.pads.fields;
+    const sv = this.slotViews(slot);
+    const meta0 = sv.u32[f.meta0];
+    if ((meta0 & 0xff) === 0) return null;
+
+    const axes =
+      (out?.axes as Float32Array | undefined) ?? new Float32Array(8);
+    axes.set(sv.f32.subarray(f.axes, f.axes + 8));
+
+    // Decode the 56-byte NUL-padded name. Reinterpret the slot u32 region.
+    const nameBytes = new Uint8Array(
+      sv.u32.buffer,
+      sv.u32.byteOffset + f.name * 4,
+      56,
+    );
+    let nameLen = nameBytes.indexOf(0);
+    if (nameLen < 0) nameLen = 56;
+
+    return {
+      slot,
+      connected: true,
+      padType: ((meta0 >>> 8) & 0xff) as PadTypeValue,
+      connType: ((meta0 >>> 16) & 0xff) as PadConnTypeValue,
+      battery: (meta0 >>> 24) & 0xff,
+      rssi: sv.u32[f.hostMeta] & 0xff,
+      flags: sv.u32[f.meta1],
+      buttonsLo: sv.u32[f.buttonsLo],
+      buttonsHi: sv.u32[f.buttonsHi],
+      axes,
+      lastEventMs: sv.u32[f.lastEventMs],
+      slotSeq: sv.u32[f.slotSeq],
+      vendorId: sv.u32[f.vendorId],
+      productId: sv.u32[f.productId],
+      name: textDecoder.decode(nameBytes.subarray(0, nameLen)),
+      eventNode: (sv.u32[f.aux] & 0xffff) === 0xffff ? -1 : sv.u32[f.aux] & 0xffff,
+    };
+  }
+
+  /** Iterate all currently-connected slots. Allocates one object per pad —
+   *  fine for UI/discovery at event cadence; for per-frame input read
+   *  axes/buttons directly via `rawSlot`. */
+  *readConnected(): Generator<GamepadDeviceSlot> {
+    const mask = this.getConnectedMask();
+    for (let i = 0; i < GAMEPAD_MAX_SLOTS; i++) {
+      if (mask & (1 << i)) {
+        const d = this.readSlot(i);
+        if (d) yield d;
+      }
+    }
+  }
+}
+
+/**
+ * Writer for the JS-owned enrichment field (`hostMeta`). Only JS sysfs
+ * enrichment should construct this — the native worker owns everything else.
+ */
+export class GamepadDevicesHostMetaWriter {
+  private pads: ReturnType<typeof GamepadDevicesChannel.writer>["sections"]["pads"];
+
+  constructor(sab: SharedArrayBuffer) {
+    this.pads = GamepadDevicesChannel.writer(sab).sections.pads;
+  }
+
+  /** Write RSSI (0..100, 255 unknown) + JS flag byte for a slot. */
+  setHostMeta(slot: number, rssi: number, jsFlags = 0) {
+    const f = GamepadDevicesChannel.offsets.sections.pads.fields;
+    const sv = this.pads.slot(slot);
+    sv.u32[f.hostMeta] = ((rssi & 0xff) | ((jsFlags & 0xff) << 8)) >>> 0;
+  }
+}

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

@@ -0,0 +1,117 @@
+import type { ChannelLayout, GridLayerLayout, HeaderViews } from "./types";
+import { describeHeaderValidation } from "./errors";
+
+function createHeaderViews(sab: SharedArrayBuffer, headerSize: number): HeaderViews {
+  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)),
+  };
+}
+
+function createLayerView(
+  sab: SharedArrayBuffer,
+  layer: GridLayerLayout,
+): Float32Array | Int32Array | Uint32Array | Float64Array {
+  switch (layer.type) {
+    case "f32": return new Float32Array(sab, layer.byteOffset, layer.length);
+    case "i32": return new Int32Array(sab, layer.byteOffset, layer.length);
+    case "u32": return new Uint32Array(sab, layer.byteOffset, layer.length);
+    case "bool": return new Uint32Array(sab, layer.byteOffset, layer.length);
+    case "f64": return new Float64Array(sab, layer.byteOffset, layer.length);
+    default: return new Float32Array(sab, layer.byteOffset, layer.length);
+  }
+}
+
+export class GridReader {
+  header: HeaderViews;
+  layers: Record<string, Float32Array | Int32Array | Uint32Array | Float64Array>;
+  private seqArr: Int32Array;
+  private layout: ChannelLayout;
+
+  constructor(sab: SharedArrayBuffer, layout: ChannelLayout) {
+    this.layout = layout;
+    this.header = createHeaderViews(sab, layout.header.size);
+    this.seqArr = new Int32Array(sab, layout.header.sequenceIndex * 4, 1);
+
+    this.layers = {};
+    if (layout.grid) {
+      for (const [name, layer] of Object.entries(layout.grid.layers)) {
+        this.layers[name] = createLayerView(sab, layer);
+      }
+    }
+  }
+
+  isValid(): boolean {
+    return this.validationError() === null;
+  }
+
+  validationError(): string | null {
+    return describeHeaderValidation(
+      this.header.u32,
+      this.layout.header.magicIndex,
+      this.layout.header.versionIndex,
+      this.layout.magic,
+      this.layout.version,
+    );
+  }
+
+  getSequence(): number {
+    return Atomics.load(this.seqArr, 0);
+  }
+
+  hasChanged(lastSeen: number): boolean {
+    return this.getSequence() !== lastSeen;
+  }
+
+  snapshot(): Record<string, unknown> {
+    const data: Record<string, unknown> = {};
+    data["sequence"] = this.getSequence();
+    if (this.layout.grid) {
+      for (const [name, layer] of Object.entries(this.layout.grid.layers)) {
+        const view = this.layers[name];
+        const copy: number[] = [];
+        for (let i = 0; i < layer.length; i++) {
+          copy.push((view as Float32Array)[i]);
+        }
+        data[name] = copy;
+      }
+    }
+    return data;
+  }
+}
+
+export class GridWriter {
+  header: HeaderViews;
+  layers: Record<string, Float32Array | Int32Array | Uint32Array | Float64Array>;
+  private seqArr: Int32Array;
+  private layout: ChannelLayout;
+
+  constructor(sab: SharedArrayBuffer, layout: ChannelLayout) {
+    this.layout = layout;
+    this.header = createHeaderViews(sab, layout.header.size);
+    this.seqArr = new Int32Array(sab, layout.header.sequenceIndex * 4, 1);
+
+    this.layers = {};
+    if (layout.grid) {
+      for (const [name, layer] of Object.entries(layout.grid.layers)) {
+        this.layers[name] = createLayerView(sab, layer);
+      }
+    }
+  }
+
+  init(): void {
+    this.header.u32[this.layout.header.magicIndex] = this.layout.magic;
+    this.header.u32[this.layout.header.versionIndex] = this.layout.version;
+  }
+
+  bumpSequence(): void {
+    Atomics.add(this.seqArr, 0, 1);
+  }
+
+  getSequence(): number {
+    return Atomics.load(this.seqArr, 0);
+  }
+}