@oasys/oecs 0.5.3 → 0.6.0

package/dist/plugins/snapshots.js

@@ -0,0 +1,737 @@
+import { M as L, s as W, r as z, c as q } from "./relation_store-BsoegrZh.js";
+import { StoreRestoreError as $, SparseRestoreError as _, ECSRestoreError as y } from "../index.js";
+import { S as d, A, a as S, C as B, b as M, c as b, d as R, e as T, f as I, L as C, g as v } from "./abi-NP8pNxpd.js";
+import { pluginMissingError as j } from "../internal.js";
+function Y(t) {
+  return {
+    magic: t.getUint32(d.magic, !0),
+    simAbiVersion: t.getUint32(d.sim_abi_version, !0),
+    viewStamp: t.getUint32(d.view_stamp, !0),
+    capacity: t.getUint32(d.capacity, !0),
+    archetypeCount: t.getUint32(d.archetype_count, !0),
+    layoutDescriptorOff: t.getUint32(d.layout_descriptor_off, !0),
+    commandRingOff: t.getUint32(d.command_ring_off, !0),
+    actionRingOff: t.getUint32(d.action_ring_off, !0),
+    entityIndexOff: t.getUint32(d.entity_index_off, !0),
+    eventRingOff: t.getUint32(d.event_ring_off, !0),
+    regionTableOff: t.getUint32(d.region_table_off, !0),
+    regionTableCount: t.getUint32(d.region_table_count, !0),
+    bindingsOff: t.getUint32(d.bindings_off, !0)
+  };
+}
+const w = {
+  u8: 0,
+  i8: 1,
+  u16: 2,
+  i16: 3,
+  u32: 4,
+  i32: 5,
+  f32: 6,
+  f64: 7
+}, K = Object.freeze({
+  [w.u8]: 1,
+  [w.i8]: 1,
+  [w.u16]: 2,
+  [w.i16]: 2,
+  [w.u32]: 4,
+  [w.i32]: 4,
+  [w.f32]: 4,
+  [w.f64]: 8
+});
+function J(t, e, r) {
+  t.setUint16(e + b.component_id, r.componentId, !0), t.setUint16(e + b.field_id, r.fieldId, !0), t.setUint8(e + b.type_tag, r.typeTag), t.setUint32(e + b.byte_off, r.byteOff, !0), t.setUint16(e + b.stride, r.stride, !0);
+}
+function Q(t, e) {
+  return {
+    componentId: t.getUint16(e + b.component_id, !0),
+    fieldId: t.getUint16(e + b.field_id, !0),
+    typeTag: t.getUint8(e + b.type_tag),
+    byteOff: t.getUint32(e + b.byte_off, !0),
+    stride: t.getUint16(e + b.stride, !0)
+  };
+}
+function Z(t, e = A) {
+  return e + t * M;
+}
+function tt(t, e, r) {
+  t.setUint32(e + S.archetype_id, r.archetypeId, !0);
+  for (let n = 0; n < B; n++)
+    t.setUint32(
+      e + S.component_mask + n * 4,
+      r.componentMask[n] ?? 0,
+      !0
+    );
+  t.setUint32(e + S.row_count, r.rowCount, !0), t.setUint32(e + S.row_capacity, r.rowCapacity, !0), t.setUint32(e + S.column_count, r.columns.length, !0), t.setUint32(e + S.enabled_count, r.enabledCount, !0), t.setUint32(e + S.entity_ids_off, 0, !0);
+  let s = e + A;
+  for (let n = 0; n < r.columns.length; n++)
+    J(t, s, r.columns[n]), s += M;
+  return s;
+}
+function et(t, e, r = A) {
+  const s = t.getUint32(e + S.column_count, !0), n = new Array(s);
+  let o = e + r;
+  for (let a = 0; a < s; a++)
+    n[a] = Q(t, o), o += M;
+  const i = new Array(B);
+  for (let a = 0; a < B; a++)
+    i[a] = t.getUint32(
+      e + S.component_mask + a * 4,
+      !0
+    );
+  return {
+    archetypeId: t.getUint32(e + S.archetype_id, !0),
+    componentMask: i,
+    rowCount: t.getUint32(e + S.row_count, !0),
+    rowCapacity: t.getUint32(e + S.row_capacity, !0),
+    enabledCount: t.getUint32(e + S.enabled_count, !0),
+    columns: n
+  };
+}
+function nt(t, e, r) {
+  let s = e;
+  for (let n = 0; n < r.length; n++)
+    s = tt(t, s, r[n]);
+  return s;
+}
+function H(t, e, r, s = A) {
+  const n = new Array(r);
+  let o = e;
+  for (let i = 0; i < r; i++) {
+    const a = et(t, o, s);
+    n[i] = a, o += Z(a.columns.length, s);
+  }
+  return n;
+}
+class rt extends Error {
+  constructor() {
+    super(
+      'SharedArrayBuffer is not available in this runtime. The chosen world backing is SAB-based and cannot start without it. In browsers this requires cross-origin isolation: serve the page with `Cross-Origin-Opener-Policy: same-origin` and `Cross-Origin-Embedder-Policy: require-corp` (or `credentialless`). Alternatively choose the pure-TS heap profile (`memory: { backing: "heap" }`), which is backed by a plain ArrayBuffer and needs no SAB and no COOP+COEP. In Bun or Node SAB is available unconditionally. If you see this there, the runtime is older than expected, or the global was shadowed.'
+    ), this.name = "SabUnavailableError";
+  }
+}
+const st = (t) => {
+  if (typeof SharedArrayBuffer > "u") throw new rt();
+  return new SharedArrayBuffer(t);
+}, ot = 16, at = {
+  capacity: 4
+  // 8..16: pad to 16-byte alignment so the i32 arrays start aligned.
+};
+function it(t, e) {
+  return t << 16 | e;
+}
+const X = 2 ** 31;
+class ct extends Error {
+  constructor(e) {
+    super(
+      `SAB column layout offset ${e} reaches or exceeds the 2³¹ (${X}-byte) ceiling. Past 2 GiB the signed-32-bit bitwise alignment math wraps to a negative or misaligned offset. This is a structural limit independent of the allocator cap, so a single store cannot back more than 2 GiB of column data.`
+    ), this.name = "StoreLayoutOverflowError";
+  }
+}
+function ht(t, e) {
+  if (t + e > X)
+    throw new ct(t);
+  return t + (e - 1) & ~(e - 1);
+}
+function ut(t, e, r, s, n) {
+  const o = e + s;
+  switch (r) {
+    case w.u8:
+      return new Uint8Array(t, o, n);
+    case w.i8:
+      return new Int8Array(t, o, n);
+    case w.u16:
+      return new Uint16Array(t, o, n);
+    case w.i16:
+      return new Int16Array(t, o, n);
+    case w.u32:
+      return new Uint32Array(t, o, n);
+    case w.i32:
+      return new Int32Array(t, o, n);
+    case w.f32:
+      return new Float32Array(t, o, n);
+    case w.f64:
+      return new Float64Array(t, o, n);
+  }
+}
+const P = 16;
+function lt(t) {
+  if (!Number.isInteger(t) || t < 0)
+    throw new RangeError(`createColumnStore: storeBase must be an integer >= 0, got ${t}`);
+  if (t % P !== 0)
+    throw new RangeError(
+      `createColumnStore: storeBase must be a multiple of ${P}, got ${t}`
+    );
+}
+function ft(t, e, r) {
+  const s = /* @__PURE__ */ new Map();
+  for (let n = 0; n < r.length; n++) {
+    const o = r[n], i = new Array(o.columns.length), a = /* @__PURE__ */ new Map();
+    for (let c = 0; c < o.columns.length; c++) {
+      const h = o.columns[c], l = {
+        componentId: h.componentId,
+        fieldId: h.fieldId,
+        typeTag: h.typeTag,
+        byteOff: h.byteOff,
+        stride: h.stride,
+        view: ut(t, e, h.typeTag, h.byteOff, o.rowCapacity)
+      };
+      i[c] = l, a.set(it(h.componentId, h.fieldId), l);
+    }
+    s.set(o.archetypeId, {
+      archetypeId: o.archetypeId,
+      componentMask: o.componentMask,
+      rowCapacity: o.rowCapacity,
+      columns: a,
+      columnsInOrder: i
+    });
+  }
+  return s;
+}
+function pt(t) {
+  const e = t.view.getUint32(d.capacity, !0);
+  return new Uint8Array(t.buffer, t.storeBase, e);
+}
+const dt = Math.max(...Object.values(K));
+function gt(t) {
+  const e = A - v;
+  return ht(t * e, dt);
+}
+function yt(t) {
+  const e = new DataView(t.buffer, t.byteOffset, t.byteLength), r = e.getUint32(d.layout_descriptor_off, !0), s = e.getUint32(d.archetype_count, !0), n = gt(s);
+  if (n === 0) return t;
+  const o = H(
+    e,
+    r,
+    s,
+    v
+  ), i = new Uint8Array(t.byteLength + n);
+  i.set(t.subarray(0, r), 0), i.set(t.subarray(r), r + n);
+  const a = new DataView(i.buffer), c = o.map((l) => ({
+    ...l,
+    columns: l.columns.map((f) => ({ ...f, byteOff: f.byteOff + n }))
+  }));
+  nt(a, r, c);
+  const h = e.getUint32(d.capacity, !0);
+  return a.setUint32(d.capacity, h + n, !0), i;
+}
+function mt(t, e = st, r = {}) {
+  const s = r.storeBase ?? 0;
+  lt(s);
+  const n = new DataView(t.buffer, t.byteOffset, t.byteLength);
+  if (t.byteLength < R)
+    throw new $(
+      `snapshot too small: ${t.byteLength} bytes (header alone needs ${R})`
+    );
+  const o = n.getUint32(d.magic, !0);
+  if (o !== T)
+    throw new $(
+      `bad magic: 0x${o.toString(16).padStart(8, "0")} (expected 0x${T.toString(16).padStart(8, "0")})`
+    );
+  const i = n.getUint32(d.sim_abi_version, !0);
+  if (i !== I && i !== C)
+    throw new $(
+      `incompatible sim_abi_version: snapshot=${i}, build=${I}`
+    );
+  const a = n.getUint32(d.layout_descriptor_off, !0);
+  if (a > t.byteLength)
+    throw new $(
+      `layout_descriptor_off ${a} is outside the snapshot (${t.byteLength} bytes)`
+    );
+  let c = t;
+  if (i === C)
+    try {
+      c = yt(t);
+    } catch (p) {
+      throw p instanceof RangeError ? new $(
+        `snapshot layout is corrupt or truncated: a version 0 descriptor reads past the ${t.byteLength}-byte span (${p.message})`
+      ) : p;
+    }
+  const h = e(s + c.byteLength);
+  new Uint8Array(h, s, c.byteLength).set(c);
+  const l = new DataView(h, s);
+  l.setUint32(d.sim_abi_version, I, !0);
+  const f = Y(l);
+  if (f.layoutDescriptorOff < 0 || f.layoutDescriptorOff > c.byteLength)
+    throw new $(
+      `layout_descriptor_off ${f.layoutDescriptorOff} is outside the snapshot (${c.byteLength} bytes)`
+    );
+  try {
+    const p = H(
+      l,
+      f.layoutDescriptorOff,
+      f.archetypeCount
+    ), u = ft(h, s, p);
+    return { buffer: h, view: l, header: f, storeBase: s, archetypes: u };
+  } catch (p) {
+    throw p instanceof RangeError ? new $(
+      `snapshot layout is corrupt or truncated: a descriptor offset or column extent reads past the ${c.byteLength}-byte span (${p.message})`
+    ) : p;
+  }
+}
+const wt = 2166136261, _t = 16777619;
+function D(t, e) {
+  return t = (t ^ e & 255) >>> 0, Math.imul(t, _t) >>> 0;
+}
+const V = 12, k = 4, U = 8;
+function F(t, e) {
+  let r = wt;
+  const s = (n) => {
+    for (let o = 0; o < n.length; o++) r = D(r, n.charCodeAt(o));
+  };
+  for (let n = 0; n < t.length; n++)
+    s(t[n]), r = D(r, 31), s(e[n]), r = D(r, 30);
+  return r >>> 0;
+}
+function St(t) {
+  let e = 4;
+  for (let o = 0; o < t.length; o++) {
+    const i = t[o], a = i.fieldNames.length;
+    e += V + i.size * (k + a * U);
+  }
+  const r = new Uint8Array(e), s = new DataView(r.buffer);
+  let n = 0;
+  s.setUint32(n, t.length, !0), n += 4;
+  for (let o = 0; o < t.length; o++) {
+    const i = t[o], a = i.fieldNames.length, c = i.canonicalIndices();
+    s.setUint32(n, a, !0), n += 4, s.setUint32(n, F(i.fieldNames, i.fieldTypes), !0), n += 4, s.setUint32(n, c.length, !0), n += 4;
+    for (let h = 0; h < c.length; h++) {
+      const l = c[h];
+      s.setUint32(n, l, !0), n += 4;
+      const f = i.getRow(l);
+      for (let p = 0; p < a; p++)
+        s.setFloat64(n, f[p], !0), n += U;
+    }
+  }
+  return r;
+}
+function bt(t, e) {
+  const r = new DataView(e.buffer, e.byteOffset, e.byteLength), s = e.byteLength;
+  let n = 0;
+  const o = (a) => {
+    if (n + a > s)
+      throw new _(
+        `sparse snapshot truncated: need ${a} more bytes at offset ${n}, have ${s - n}`
+      );
+  };
+  o(4);
+  const i = r.getUint32(n, !0);
+  if (n += 4, i !== t.length)
+    throw new _(
+      `sparse store count mismatch: snapshot=${i}, registered=${t.length}`
+    );
+  for (let a = 0; a < t.length; a++) {
+    const c = t[a];
+    o(V);
+    const h = r.getUint32(n, !0);
+    n += 4;
+    const l = r.getUint32(n, !0);
+    n += 4;
+    const f = r.getUint32(n, !0);
+    if (n += 4, h !== c.fieldNames.length)
+      throw new _(
+        `sparse store ${a} field-count mismatch: snapshot=${h}, registered=${c.fieldNames.length}`
+      );
+    const p = F(c.fieldNames, c.fieldTypes);
+    if (l !== p)
+      throw new _(
+        `sparse store ${a} schema identity mismatch: snapshot hash=${l}, registered=${p} (same field count, different field names or types, likely a registration-order divergence between the snapshot and restore worlds)`
+      );
+    c.clear();
+    for (let u = 0; u < f; u++) {
+      o(k + h * U);
+      const m = r.getUint32(n, !0);
+      if (n += 4, m > L)
+        throw new _(
+          `sparse store ${a} member ${u} entity index ${m} exceeds MAX_INDEX (${L})`
+        );
+      const g = new Array(h);
+      for (let O = 0; O < h; O++)
+        g[O] = r.getFloat64(n, !0), n += U;
+      c.setRawRow(m, g);
+    }
+  }
+  if (n !== s)
+    throw new _(
+      `sparse snapshot has ${s - n} trailing bytes after the last store (not a canonical encoding)`
+    );
+}
+function $t(t, e) {
+  const r = new DataView(e.buffer, e.byteOffset, e.byteLength), s = e.byteLength;
+  let n = 0;
+  const o = (a) => {
+    if (n + a > s)
+      throw new _(
+        `sparse snapshot truncated: need ${a} more bytes at offset ${n}, have ${s - n}`
+      );
+  };
+  o(4);
+  const i = r.getUint32(n, !0);
+  if (n += 4, i !== t.length)
+    throw new _(
+      `sparse store count mismatch: snapshot=${i}, registered=${t.length}`
+    );
+  for (let a = 0; a < t.length; a++) {
+    const c = t[a];
+    o(V);
+    const h = r.getUint32(n, !0);
+    n += 4;
+    const l = r.getUint32(n, !0);
+    n += 4;
+    const f = r.getUint32(n, !0);
+    if (n += 4, h !== c.fieldNames.length)
+      throw new _(
+        `sparse store ${a} field-count mismatch: snapshot=${h}, registered=${c.fieldNames.length}`
+      );
+    const p = F(c.fieldNames, c.fieldTypes);
+    if (l !== p)
+      throw new _(
+        `sparse store ${a} schema identity mismatch: snapshot hash=${l}, registered=${p} (same field count, different field names or types, likely a registration-order divergence between the snapshot and restore worlds)`
+      );
+    for (let u = 0; u < f; u++) {
+      o(k + h * U);
+      const m = r.getUint32(n, !0);
+      if (n += 4, m > L)
+        throw new _(
+          `sparse store ${a} member ${u} entity index ${m} exceeds MAX_INDEX (${L})`
+        );
+      n += h * U;
+    }
+  }
+  if (n !== s)
+    throw new _(
+      `sparse snapshot has ${s - n} trailing bytes after the last store (not a canonical encoding)`
+    );
+}
+const N = 1, x = 810766935, E = 4;
+function Ut(t) {
+  const e = t.freeIndices.length, r = t.archetypeRows.length, s = E * (4 + e + 1 + r * 3), n = new Uint8Array(s), o = new DataView(n.buffer);
+  let i = 0;
+  const a = (c) => {
+    o.setUint32(i, c, !0), i += E;
+  };
+  a(t.tick), a(t.entityHighWater), a(t.entityAliveCount), a(e);
+  for (let c = 0; c < e; c++) a(t.freeIndices[c]);
+  a(r);
+  for (let c = 0; c < r; c++) {
+    const h = t.archetypeRows[c];
+    a(h.archetypeId), a(h.length), a(h.enabledCount);
+  }
+  return n;
+}
+function Et(t) {
+  const e = new DataView(t.buffer, t.byteOffset, t.byteLength), r = t.byteLength;
+  let s = 0;
+  const n = (u) => {
+    if (s + u > r)
+      throw new y(
+        `host-state truncated: need ${u} more bytes at offset ${s}, have ${r - s}`
+      );
+  }, o = () => {
+    n(E);
+    const u = e.getUint32(s, !0);
+    return s += E, u;
+  }, i = o(), a = o(), c = o(), h = o(), l = new Array(h);
+  for (let u = 0; u < h; u++) l[u] = o();
+  const f = o(), p = new Array(f);
+  for (let u = 0; u < f; u++) {
+    const m = o(), g = o(), O = o();
+    p[u] = { archetypeId: m, length: g, enabledCount: O };
+  }
+  if (s !== r)
+    throw new y(
+      `host-state has ${r - s} trailing bytes after the last archetype (not a canonical encoding)`
+    );
+  return { tick: i, entityHighWater: a, entityAliveCount: c, freeIndices: l, archetypeRows: p };
+}
+function At(t, e, r) {
+  const s = E * 5, n = new Uint8Array(s + t.length + e.length + r.length), o = new DataView(n.buffer);
+  return o.setUint32(0, x, !0), o.setUint32(4, N, !0), o.setUint32(8, t.length, !0), o.setUint32(12, e.length, !0), o.setUint32(16, r.length, !0), n.set(t, s), n.set(e, s + t.length), n.set(r, s + t.length + e.length), n;
+}
+function Ot(t) {
+  const e = E * 5;
+  if (t.byteLength < e)
+    throw new y(
+      `world snapshot too small: ${t.byteLength} bytes (frame header needs ${e})`
+    );
+  const r = new DataView(t.buffer, t.byteOffset, t.byteLength), s = r.getUint32(0, !0);
+  if (s !== x)
+    throw new y(
+      `bad world-snapshot magic: 0x${s.toString(16).padStart(8, "0")} (expected 0x${x.toString(16).padStart(8, "0")}). A bare dense (SAB) snapshot is not a combined world snapshot, pass the bytes from ECS.snapshot(), not columnStoreBytesView().`
+    );
+  const n = r.getUint32(4, !0);
+  if (n !== N)
+    throw new y(
+      `incompatible world-snapshot version: snapshot=${n}, build=${N}`
+    );
+  const o = r.getUint32(8, !0), i = r.getUint32(12, !0), a = r.getUint32(16, !0);
+  if (e + o + i + a !== t.byteLength)
+    throw new y(
+      `world-snapshot frame mismatch: header declares ${e}+${o}+${i}+${a}=${e + o + i + a} bytes, buffer is ${t.byteLength}`
+    );
+  const c = t.byteOffset, h = t.buffer;
+  return {
+    dense: new Uint8Array(h, c + e, o),
+    sparse: new Uint8Array(h, c + e + o, i),
+    host: new Uint8Array(h, c + e + o + i, a)
+  };
+}
+function It(t, e, r) {
+  if (t.byteLength < R)
+    throw new y(
+      `dense section too small: ${t.byteLength} bytes (SAB header needs ${R})`
+    );
+  const s = new DataView(t.buffer, t.byteOffset, t.byteLength), n = s.getUint32(d.magic, !0);
+  if (n !== T)
+    throw new y(
+      `dense section bad magic: 0x${n.toString(16).padStart(8, "0")} (expected SAB magic 0x${T.toString(16).padStart(8, "0")})`
+    );
+  const o = s.getUint32(d.sim_abi_version, !0);
+  if (o !== I && o !== C)
+    throw new y(
+      `dense section incompatible sim_abi_version: snapshot=${o}, build=${I}`
+    );
+  const i = Y(s);
+  if (i.layoutDescriptorOff < 0 || i.layoutDescriptorOff > t.byteLength)
+    throw new y(
+      `dense layoutDescriptorOff ${i.layoutDescriptorOff} is outside the section (${t.byteLength} bytes)`
+    );
+  const a = i.entityIndexOff;
+  if (a < 0 || a + ot > t.byteLength)
+    throw new y(
+      `dense entityIndexOff ${a} is outside the section (${t.byteLength} bytes)`
+    );
+  const c = s.getUint32(a + at.capacity, !0);
+  if (c !== r)
+    throw new y(
+      `entity-index capacity mismatch: live=${r}, snapshot=${c}`
+    );
+  let h;
+  try {
+    h = H(
+      s,
+      i.layoutDescriptorOff,
+      i.archetypeCount,
+      o === C ? v : A
+    );
+  } catch (l) {
+    throw l instanceof RangeError ? new y(
+      `dense section layout is corrupt or truncated: a descriptor reads past the ${t.byteLength}-byte section (${l.message})`
+    ) : l;
+  }
+  if (e.size !== h.length)
+    throw new y(
+      `archetype-set mismatch: the live world has ${e.size} SAB archetypes, the snapshot has ${h.length}. restore requires an identical archetype set. Prewarm the world so its archetype set is stable.`
+    );
+  for (let l = 0; l < h.length; l++) {
+    const f = h[l], p = e.get(f.archetypeId);
+    if (p === void 0)
+      throw new y(
+        `archetype-set mismatch: snapshot archetype ${f.archetypeId} is absent from the live world`
+      );
+    if (!Lt(p.componentMask, f.componentMask))
+      throw new y(
+        `archetype ${f.archetypeId} component-mask mismatch between the live world and the snapshot (different component registration)`
+      );
+    const u = p.columnsInOrder, m = f.columns;
+    if (u.length !== m.length)
+      throw new y(
+        `archetype ${f.archetypeId} column-count mismatch: live=${u.length}, snapshot=${m.length}`
+      );
+    for (let g = 0; g < u.length; g++)
+      if (u[g].componentId !== m[g].componentId || u[g].fieldId !== m[g].fieldId || u[g].typeTag !== m[g].typeTag)
+        throw new y(
+          `archetype ${f.archetypeId} column ${g} layout mismatch: live=(c${u[g].componentId},f${u[g].fieldId},t${u[g].typeTag}), snapshot=(c${m[g].componentId},f${m[g].fieldId},t${m[g].typeTag})`
+        );
+  }
+}
+function Lt(t, e) {
+  if (t.length !== e.length) return !1;
+  for (let r = 0; r < t.length; r++) if (t[r] !== e[r]) return !1;
+  return !0;
+}
+class Rt {
+  _host;
+  /** The allocator is its own snapshot seam: a free-list copy on
+   * capture, `setHighWater` and `restoreHostState` on mount. */
+  _allocator;
+  constructor(e, r) {
+    this._host = e, this._allocator = r;
+  }
+  /** Serialize the sparse stores **and** relation side data to a self-contained
+   * byte buffer, the sparse half of a world snapshot (the dense half is the
+   * SAB snapshot). Two framed sections: the sparse stores (`snapshotSparseStores`,
+   * where the exclusive relation targets and the multi membership ride) followed
+   * by the relation side data (`snapshotRelations`, multi forward target
+   * sets, which live outside the sparse store). Both are written in canonical
+   * entity-index order, so two worlds with identical contents inserted in
+   * different orders snapshot byte-for-byte the same. The reverse index
+   * is derived and never serialized, `restoreSparse` rebuilds it. */
+  snapshotSparse() {
+    const e = St(this._host.sparseStores()), r = W(this._host.relationStores()), s = new Uint8Array(8 + e.length + r.length), n = new DataView(s.buffer);
+    return n.setUint32(0, e.length, !0), n.setUint32(4, r.length, !0), s.set(e, 8), s.set(r, 8 + e.length), s;
+  }
+  /** Repopulate the sparse stores from `snapshotSparse` bytes, replacing all
+   * current sparse data (full-equality round-trip of membership and data), then
+   * rebuild every relation's derived side indices: multi forward sets from the
+   * relation section, and the reverse index for both cardinalities (exclusive
+   * from the newly restored sparse target field, multi from the rebuilt forward
+   * sets). The sparse components and relations must already be registered in
+   * the same order, restore carries data, not the registration (which is
+   * code). Throws `SparseRestoreError` if the snapshot's shape, field identity,
+   * entity-index bounds, or frame length don't validate. */
+  restoreSparse(e) {
+    const r = new DataView(e.buffer, e.byteOffset, e.byteLength);
+    if (e.byteLength < 8)
+      throw new _(
+        `sparse snapshot truncated: need 8 header bytes, have ${e.byteLength}`
+      );
+    const s = r.getUint32(0, !0), n = r.getUint32(4, !0);
+    if (8 + s + n !== e.byteLength)
+      throw new _(
+        `sparse snapshot frame mismatch: header declares 8+${s}+${n}=${8 + s + n} bytes, buffer is ${e.byteLength}`
+      );
+    bt(this._host.sparseStores(), e.subarray(8, 8 + s)), this._rebuildRelationIndices(e.subarray(8 + s, 8 + s + n));
+  }
+  /** Rebuild every relation's derived side indices after the sparse stores have
+   * been restored. `restoreRelations` resets all relations, rebuilds the multi
+   * forward sets and their reverse edges from `relBytes`, and validates shape.
+   * The exclusive reverse index can't be carried in the bytes (it's derivable),
+   * so it's rebuilt here from the backing sparse store: every member row holds
+   * `(source index → target EntityID)`, which is exactly one reverse edge. */
+  _rebuildRelationIndices(e) {
+    const r = this._host.generations(), s = (o) => q(o, r[o]), n = this._host.relationStores();
+    z(n, e, s);
+    for (let o = 0; o < n.length; o++) n[o].rebuildReverse(s);
+  }
+  /** Capture the full live world to one self-contained byte buffer that
+   * `restore` can mount back onto a live, ticking world. Three
+   * sections (see `resume.ts`): the dense SAB column bytes, the sparse and
+   * relation bytes, and the host-side bookkeeping the SAB omits. */
+  snapshot() {
+    this._host.publishRowCounts();
+    const e = new Uint8Array(pt(this._host.columnStore())), r = this.snapshotSparse(), s = Ut(this._collectHostState());
+    return At(e, r, s);
+  }
+  /** Gather the host-side state a snapshot carries alongside the dense and
+   * sparse bytes, see `snapshot()`. The free-list is copied, because it is a
+   * live mutable. */
+  _collectHostState() {
+    const e = [], r = this._host.archetypes();
+    for (let s = 0; s < r.length; s++) {
+      const n = r[s];
+      n.isBufferBacked && e.push({
+        archetypeId: n.id,
+        length: n.length,
+        enabledCount: n.enabledCount
+      });
+    }
+    return {
+      tick: this._host.tick(),
+      entityHighWater: this._allocator.highWater,
+      entityAliveCount: this._allocator.aliveCount,
+      freeIndices: this._allocator.snapshotFreeIndices(),
+      archetypeRows: e
+    };
+  }
+  /** Mount a `snapshot()` buffer onto the live world and leave it ready to keep
+   * ticking. Fails closed on a malformed frame or a registration mismatch
+   * before any live state is touched. */
+  restore(e) {
+    const r = Ot(e), s = Et(r.host);
+    It(
+      r.dense,
+      this._host.columnStore().archetypes,
+      this._host.entityIndexCapacity()
+    ), this._assertSparseMatchesLive(r.sparse);
+    const n = mt(r.dense, this._host.bufferAllocator(), {
+      storeBase: this._host.columnStore().storeBase
+    });
+    this._host.mountRestoredDense(n), this._host.reconstructHostRows(s), this._allocator.restoreHostState(s.freeIndices, s.entityAliveCount), this._host.setTick(s.tick), this._host.invalidateCaches(), this.restoreSparse(r.sparse);
+  }
+  /** Read-only validation of a `snapshotSparse` Section (the framed
+   * `[sparseLen][relLen][sparse][rel]` buffer) against the live registry, used
+   * by `restore` to fail closed on a sparse-registration mismatch before the
+   * dense mount commits. Mirrors `restoreSparse`'s frame check, then validates the
+   * sparse-stores sub-section without mutating. A relation-registration difference
+   * surfaces here too: every `registerRelation` adds a backing sparse store, so a
+   * differing relation set changes the sparse store count or its schema. Throws
+   * `SparseRestoreError` on a mismatch. */
+  _assertSparseMatchesLive(e) {
+    const r = new DataView(e.buffer, e.byteOffset, e.byteLength);
+    if (e.byteLength < 8)
+      throw new _(
+        `sparse snapshot truncated: need 8 header bytes, have ${e.byteLength}`
+      );
+    const s = r.getUint32(0, !0), n = r.getUint32(4, !0);
+    if (8 + s + n !== e.byteLength)
+      throw new _(
+        `sparse snapshot frame mismatch: header declares 8+${s}+${n}=${8 + s + n} bytes, buffer is ${e.byteLength}`
+      );
+    $t(this._host.sparseStores(), e.subarray(8, 8 + s));
+  }
+}
+class G {
+  // Protected, not private: the snapshot plugin subclasses this to add
+  // `capture` and `restore`, and reaches the store the same way.
+  _store;
+  /** @internal constructed by `ECS`. */
+  constructor(e) {
+    this._store = e;
+  }
+  /** Whether the determinism surface is enabled. */
+  get deterministic() {
+    return this._store.deterministic;
+  }
+  /** FNV-1a 32 digest over every archetype's live rows in id order, the
+   * canonical "live ECS state digest". Per-call cost scales with live
+   * entity count, not SAB capacity. */
+  stateHash() {
+    return this._store.stateHash();
+  }
+}
+for (const t of ["capture", "restore", "captureSparse", "restoreSparse"])
+  G.prototype[t] = function() {
+    throw j("snapshots", `ecs.snapshots.${t}`);
+  };
+class Tt extends G {
+  /** Capture the full live world (the dense bytes, the sparse stores and
+   * relations, and the host-side bookkeeping) to one self-contained byte
+   * buffer that `restore` can mount back onto a live, ticking world. Version 1
+   * captures no resource, no event and no change-detection baseline. */
+  capture() {
+    return this._store.snapshot();
+  }
+  /** Mount a `capture()` buffer onto this live world and keep ticking.
+   * Fails closed on a malformed frame or registration mismatch before
+   * mutating any live state. Requires a matching archetype set and column
+   * layout (prewarm so the set is stable). */
+  restore(e) {
+    this._store.restore(e);
+  }
+  /** Serialize the sparse stores and the relations to a self-contained buffer,
+   * the sparse half of a world snapshot, canonical entity-index order.
+   * Pairs with `restoreSparse`. */
+  captureSparse() {
+    return this._store.snapshotSparse();
+  }
+  /** Repopulate the sparse stores and the relation indices from
+   * `captureSparse` bytes. Sparse components must already be registered in the
+   * same order. Throws `SparseRestoreError` on a shape or identity
+   * mismatch. */
+  restoreSparse(e) {
+    this._store.restoreSparse(e);
+  }
+}
+function xt() {
+  return {
+    name: "snapshots",
+    install(t) {
+      const e = t.store;
+      return e.installSnapshots(new Rt(e.snapshotHost(), e.entityAllocator)), { snapshots: new Tt(e) };
+    }
+  };
+}
+export {
+  Tt as ECSSnapshotsFull,
+  xt as snapshots
+};