aiecsjs 0.5.9 → 0.6.0

package/dist/relations.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/relations.ts"],"names":["nextRelationId","defineRelation","options","ChildOf","getOrCreateStorage","state","rel","storage","linkIncoming","src","tgt","incoming","set","unlinkIncoming","addRelation","world","source","target","data","getWorldState","next","prevTgt","prevInner","list","inner","removeRelation","idx","getRelationTargets","gen","packEid","tIdx","getRelationData","registerRelationsCleanup","eid","e","cur","incomingSet"],"mappings":"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","file":"relations.js","sourcesContent":["// aiecsjs/relations — entity-to-entity relations (experimental in 0.1).\n\nimport { packEid, registerRelationsCleanup } from './internal/entity.js'\nimport type { EntityId, Relation, RelationStorage, World, WorldState } from './internal/types.js'\nimport { getWorldState } from './internal/world.js'\n\nlet nextRelationId = 1\n\nexport function defineRelation<T = void>(options?: { exclusive?: boolean }): Relation<T> {\n  const id = nextRelationId++\n  return {\n    __kind: 'relation',\n    __id: id,\n    __exclusive: options?.exclusive ?? false,\n    __hasData: false,\n  } as Relation<T>\n}\n\nexport const ChildOf: Relation = defineRelation({ exclusive: true })\n\nfunction getOrCreateStorage(state: WorldState, rel: Relation<unknown>): RelationStorage {\n  let storage = state.relationStorage.get(rel.__id)\n  if (storage) return storage\n  storage = {\n    rel,\n    exclusive: rel.__exclusive ? new Int32Array(state.capacity).fill(-1) : null,\n    incoming: rel.__exclusive ? new Map<number, Set<number>>() : null,\n    outgoing: new Map<number, number[]>(),\n    data: new Map<number, Map<number, unknown>>(),\n  }\n  state.relationStorage.set(rel.__id, storage)\n  return storage\n}\n\n// --- Exclusive reverse-index (incoming) helpers ---\n// `incoming` mirrors the `exclusive` array: incoming.get(tgt) is the set of\n// source slots whose exclusive[src] === tgt. Every place that writes a non-`-1`\n// value into `exclusive` must call `linkIncoming`, and every place that clears a\n// slot (sets it back to -1) must call `unlinkIncoming`, so the reverse index\n// never drifts from the forward array.\n\nfunction linkIncoming(storage: RelationStorage, src: number, tgt: number): void {\n  const incoming = storage.incoming\n  if (!incoming) return\n  let set = incoming.get(tgt)\n  if (!set) {\n    set = new Set<number>()\n    incoming.set(tgt, set)\n  }\n  set.add(src)\n}\n\nfunction unlinkIncoming(storage: RelationStorage, src: number, tgt: number): void {\n  const incoming = storage.incoming\n  if (!incoming) return\n  const set = incoming.get(tgt)\n  if (!set) return\n  set.delete(src)\n  if (set.size === 0) incoming.delete(tgt)\n}\n\nexport function addRelation<T>(\n  world: World,\n  source: EntityId,\n  rel: Relation<T>,\n  target: EntityId,\n  data?: T,\n): void {\n  const state = getWorldState(world)\n  if (state.readOnly) throw new Error('aiecsjs: cannot mutate a read-only world')\n  const storage = getOrCreateStorage(state, rel as Relation<unknown>)\n  // Use raw idx as keys in relation storage so slot reuse invalidation is consistent\n  const src = (source as number) & state.options.indexMask\n  const tgt = (target as number) & state.options.indexMask\n\n  if (storage.exclusive) {\n    if (src >= storage.exclusive.length) {\n      const next = new Int32Array(Math.max(src + 1, storage.exclusive.length * 2)).fill(-1)\n      next.set(storage.exclusive)\n      storage.exclusive = next\n    }\n    // Exclusive redirect: if this source already pointed at a different target,\n    // drop that previous target's data entry so getRelationData stays consistent\n    // with getRelationTargets, which reports only the current exclusive target.\n    const prevTgt = storage.exclusive[src] ?? -1\n    if (prevTgt >= 0 && prevTgt !== tgt) {\n      const prevInner = storage.data.get(src)\n      prevInner?.delete(prevTgt)\n      if (prevInner && prevInner.size === 0) storage.data.delete(src)\n      unlinkIncoming(storage, src, prevTgt)\n    }\n    storage.exclusive[src] = tgt\n    if (prevTgt !== tgt) linkIncoming(storage, src, tgt)\n  } else {\n    let list = storage.outgoing.get(src)\n    if (!list) {\n      list = []\n      storage.outgoing.set(src, list)\n    }\n    if (!list.includes(tgt)) list.push(tgt)\n  }\n\n  if (data !== undefined) {\n    let inner = storage.data.get(src)\n    if (!inner) {\n      inner = new Map<number, unknown>()\n      storage.data.set(src, inner)\n    }\n    inner.set(tgt, data)\n  }\n}\n\nexport function removeRelation(\n  world: World,\n  source: EntityId,\n  rel: Relation,\n  target: EntityId,\n): void {\n  const state = getWorldState(world)\n  if (state.readOnly) throw new Error('aiecsjs: cannot mutate a read-only world')\n  const storage = state.relationStorage.get(rel.__id)\n  if (!storage) return\n  const src = (source as number) & state.options.indexMask\n  const tgt = (target as number) & state.options.indexMask\n  if (storage.exclusive) {\n    if (src < storage.exclusive.length && storage.exclusive[src] === tgt) {\n      storage.exclusive[src] = -1\n      unlinkIncoming(storage, src, tgt)\n    }\n  } else {\n    const list = storage.outgoing.get(src)\n    if (list) {\n      const idx = list.indexOf(tgt)\n      if (idx >= 0) list.splice(idx, 1)\n      if (list.length === 0) storage.outgoing.delete(src)\n    }\n  }\n  const inner = storage.data.get(src)\n  if (inner) {\n    inner.delete(tgt)\n    if (inner.size === 0) storage.data.delete(src)\n  }\n}\n\nexport function getRelationTargets(\n  world: World,\n  source: EntityId,\n  rel: Relation,\n): readonly EntityId[] {\n  const state = getWorldState(world)\n  const storage = state.relationStorage.get(rel.__id)\n  if (!storage) return []\n  const src = (source as number) & state.options.indexMask\n  if (storage.exclusive) {\n    if (src < storage.exclusive.length) {\n      const tgt = storage.exclusive[src] ?? -1\n      if (tgt >= 0) {\n        const gen = state.generations[tgt] ?? 0\n        return [packEid(tgt, gen, state.options)]\n      }\n    }\n    return []\n  }\n  const list = storage.outgoing.get(src)\n  if (!list) return []\n  return list.map((tIdx) => {\n    const gen = state.generations[tIdx] ?? 0\n    return packEid(tIdx, gen, state.options)\n  })\n}\n\n/**\n * Read the data payload attached to a relation edge.\n *\n * Returns the `data` value that was supplied to {@link addRelation} for the\n * `(source, rel, target)` triple, or `undefined` when:\n * - the relation has never been stored for this world,\n * - no edge from `source` to `target` via `rel` exists, or\n * - the edge was added without a data argument.\n *\n * **Slot-keying semantic (ABA caveat):** relation storage keys edges by raw\n * entity slot index (`entityId & indexMask`), not by the full packed EntityId\n * that includes the generation counter. This means that if entity A is\n * destroyed and a *different* entity B is later created in the same slot, B\n * will inherit any edges that A had — unless the destroy cleanup hook ran\n * (which it does when `destroyEntity` is called). Callers that cache a\n * source/target EntityId should validate liveness with `entityExists` before\n * calling `getRelationData` if slot recycling is a concern.\n */\nexport function getRelationData<T>(\n  world: World,\n  source: EntityId,\n  rel: Relation<T>,\n  target: EntityId,\n): T | undefined {\n  const state = getWorldState(world)\n  const storage = state.relationStorage.get(rel.__id)\n  if (!storage) return undefined\n  const src = (source as number) & state.options.indexMask\n  const tgt = (target as number) & state.options.indexMask\n  return storage.data.get(src)?.get(tgt) as T | undefined\n}\n\n// Cleanup hook: when an entity is destroyed, remove all relations involving it.\nregisterRelationsCleanup((state: WorldState, eid: EntityId) => {\n  const e = (eid as number) & state.options.indexMask\n  for (const storage of state.relationStorage.values()) {\n    if (storage.exclusive) {\n      // `e` as a SOURCE: clear its own exclusive slot and unlink it from whatever\n      // target it currently points at, so the reverse index stays consistent.\n      if (e < storage.exclusive.length) {\n        const cur = storage.exclusive[e] ?? -1\n        if (cur >= 0) unlinkIncoming(storage, e, cur)\n        storage.exclusive[e] = -1\n      }\n      // `e` as a TARGET: clear every source that points at it. Use the reverse\n      // index to touch only the actual incoming sources (O(incoming)) instead of\n      // scanning the entire `exclusive` capacity (O(capacity)) — the bounded-cost\n      // path for large sparse relation tables. Behaviour is identical to the old\n      // full scan: every src with exclusive[src] === e is reset to -1.\n      const incomingSet = storage.incoming?.get(e)\n      if (incomingSet) {\n        for (const src of incomingSet) {\n          if (src < storage.exclusive.length) storage.exclusive[src] = -1\n        }\n        storage.incoming?.delete(e)\n      }\n    }\n    storage.outgoing.delete(e)\n    for (const [src, list] of storage.outgoing) {\n      const idx = list.indexOf(e)\n      if (idx >= 0) {\n        list.splice(idx, 1)\n        if (list.length === 0) storage.outgoing.delete(src)\n      }\n    }\n    // Clear data entries involving this entity. The outer key is the source\n    // eid; entries whose source IS this entity drop entirely. Entries that\n    // reference this entity as a target are pruned from each inner map.\n    storage.data.delete(e)\n    for (const [src, inner] of storage.data) {\n      inner.delete(e)\n      if (inner.size === 0) storage.data.delete(src)\n    }\n  }\n})\n"]}
+{"version":3,"sources":["../src/relations.ts"],"names":["defineRelation","options","ids","shared","ChildOf","storageOf","state","rel","EcsError","getOrCreateStorage","storage","linkIncoming","src","tgt","incoming","set","unlinkIncoming","addRelation","world","source","target","data","getWritableState","isAliveInternal","next","prevTgt","prevInner","list","inner","removeRelation","idx","getRelationTargets","getWorldState","gen","packEid","tIdx","getRelationData","registerRelationsCleanup","eid","e","cur","incomingSet"],"mappings":"uEAQO,SAASA,EAAyBC,CAAAA,CAAgD,CAEvF,OAAO,CACL,MAAA,CAAQ,WACR,IAAA,CAHSC,CAAAA,CAAI,WAIb,WAAA,CAAaD,CAAAA,EAAS,WAAa,KAAA,CACnC,SAAA,CAAW,KACb,CACF,CAIAE,IAAO,OAAA,GAAYH,CAAAA,CAAe,CAAE,SAAA,CAAW,IAAK,CAAC,CAAA,CAC9C,IAAMI,EAAoBD,GAAAA,CAAO,QAIxC,SAASE,CAAAA,CAAUC,CAAAA,CAAmBC,EAAqD,CACzF,GAAIA,GAAK,MAAA,GAAW,UAAA,CAAY,MAAM,IAAIC,GAAAA,CAAS,iCAAiC,CAAA,CACpF,OAAOF,EAAM,eAAA,CAAgB,GAAA,CAAIC,EAAI,IAAI,CAC3C,CAEA,SAASE,CAAAA,CAAmBH,EAAmBC,CAAAA,CAAyC,CACtF,IAAIG,CAAAA,CAAUL,CAAAA,CAAUC,EAAOC,CAAG,CAAA,CAClC,OAAIG,CAAAA,GACJA,CAAAA,CAAU,CACR,GAAA,CAAAH,CAAAA,CACA,UAAWA,CAAAA,CAAI,WAAA,CAAc,IAAI,UAAA,CAAWD,CAAAA,CAAM,QAAQ,CAAA,CAAE,IAAA,CAAK,EAAE,CAAA,CAAI,IAAA,CACvE,SAAUC,CAAAA,CAAI,WAAA,CAAc,IAAI,GAAA,CAA6B,IAAA,CAC7D,SAAU,IAAI,GAAA,CACd,KAAM,IAAI,GACZ,CAAA,CACAD,CAAAA,CAAM,gBAAgB,GAAA,CAAIC,CAAAA,CAAI,KAAMG,CAAO,CAAA,CACpCA,EACT,CASA,SAASC,EAAaD,CAAAA,CAA0BE,CAAAA,CAAaC,EAAmB,CAC9E,IAAMC,EAAWJ,CAAAA,CAAQ,QAAA,CACzB,GAAI,CAACI,CAAAA,CAAU,OACf,IAAIC,CAAAA,CAAMD,EAAS,GAAA,CAAID,CAAG,EACrBE,CAAAA,GACHA,CAAAA,CAAM,IAAI,GAAA,CACVD,CAAAA,CAAS,IAAID,CAAAA,CAAKE,CAAG,GAEvBA,CAAAA,CAAI,GAAA,CAAIH,CAAG,EACb,CAEA,SAASI,CAAAA,CAAeN,CAAAA,CAA0BE,EAAaC,CAAAA,CAAmB,CAChF,IAAMC,CAAAA,CAAWJ,CAAAA,CAAQ,SACzB,GAAI,CAACI,EAAU,OACf,IAAMC,EAAMD,CAAAA,CAAS,GAAA,CAAID,CAAG,CAAA,CACvBE,CAAAA,GACLA,EAAI,MAAA,CAAOH,CAAG,EACVG,CAAAA,CAAI,IAAA,GAAS,GAAGD,CAAAA,CAAS,MAAA,CAAOD,CAAG,CAAA,EACzC,CAYO,SAASI,CAAAA,CACdC,CAAAA,CACAC,EACAZ,CAAAA,CACAa,CAAAA,CACAC,EACM,CACN,IAAMf,EAAQgB,GAAAA,CAAiBJ,CAAK,EACpC,GAAI,CAACK,EAAgBjB,CAAAA,CAAOa,CAAM,CAAA,CAChC,MAAM,IAAIX,GAAAA,CAAS,CAAA,2CAAA,EAA8CW,CAAM,CAAA,CAAE,CAAA,CAE3E,GAAI,CAACI,CAAAA,CAAgBjB,EAAOc,CAAM,CAAA,CAChC,MAAM,IAAIZ,GAAAA,CAAS,8CAA8CY,CAAM,CAAA,CAAE,EAE3E,IAAMV,CAAAA,CAAUD,EAAmBH,CAAAA,CAAOC,CAAwB,EAE5DK,CAAAA,CAAOO,CAAAA,CAAoBb,EAAM,OAAA,CAAQ,SAAA,CACzCO,EAAOO,CAAAA,CAAoBd,CAAAA,CAAM,QAAQ,SAAA,CAE/C,GAAII,EAAQ,SAAA,CAAW,CACrB,GAAIE,CAAAA,EAAOF,CAAAA,CAAQ,UAAU,MAAA,CAAQ,CACnC,IAAMc,CAAAA,CAAO,IAAI,WAAW,IAAA,CAAK,GAAA,CAAIZ,EAAM,CAAA,CAAGF,CAAAA,CAAQ,UAAU,MAAA,CAAS,CAAC,CAAC,CAAA,CAAE,IAAA,CAAK,EAAE,CAAA,CACpFc,CAAAA,CAAK,IAAId,CAAAA,CAAQ,SAAS,EAC1BA,CAAAA,CAAQ,SAAA,CAAYc,EACtB,CAIA,IAAMC,EAAUf,CAAAA,CAAQ,SAAA,CAAUE,CAAG,CAAA,EAAK,EAAA,CAC1C,GAAIa,CAAAA,EAAW,CAAA,EAAKA,IAAYZ,CAAAA,CAAK,CACnC,IAAMa,CAAAA,CAAYhB,CAAAA,CAAQ,KAAK,GAAA,CAAIE,CAAG,EACtCc,CAAAA,EAAW,MAAA,CAAOD,CAAO,CAAA,CACrBC,CAAAA,EAAaA,EAAU,IAAA,GAAS,CAAA,EAAGhB,EAAQ,IAAA,CAAK,MAAA,CAAOE,CAAG,CAAA,CAC9DI,CAAAA,CAAeN,EAASE,CAAAA,CAAKa,CAAO,EACtC,CACAf,CAAAA,CAAQ,UAAUE,CAAG,CAAA,CAAIC,EACrBY,CAAAA,GAAYZ,CAAAA,EAAKF,EAAaD,CAAAA,CAASE,CAAAA,CAAKC,CAAG,EACrD,CAAA,KAAO,CACL,IAAIc,CAAAA,CAAOjB,EAAQ,QAAA,CAAS,GAAA,CAAIE,CAAG,CAAA,CAC9Be,CAAAA,GACHA,EAAO,EAAC,CACRjB,EAAQ,QAAA,CAAS,GAAA,CAAIE,EAAKe,CAAI,CAAA,CAAA,CAE3BA,EAAK,QAAA,CAASd,CAAG,GAAGc,CAAAA,CAAK,IAAA,CAAKd,CAAG,EACxC,CAEA,GAAIQ,CAAAA,GAAS,MAAA,CAAW,CACtB,IAAIO,CAAAA,CAAQlB,EAAQ,IAAA,CAAK,GAAA,CAAIE,CAAG,CAAA,CAC3BgB,CAAAA,GACHA,EAAQ,IAAI,GAAA,CACZlB,EAAQ,IAAA,CAAK,GAAA,CAAIE,EAAKgB,CAAK,CAAA,CAAA,CAE7BA,EAAM,GAAA,CAAIf,CAAAA,CAAKQ,CAAI,EACrB,CACF,CAEO,SAASQ,CAAAA,CACdX,EACAC,CAAAA,CACAZ,CAAAA,CACAa,EACM,CACN,IAAMd,EAAQgB,GAAAA,CAAiBJ,CAAK,CAAA,CAC9BR,CAAAA,CAAUL,EAAUC,CAAAA,CAAOC,CAAwB,EACzD,GAAI,CAACG,EAAS,OACd,IAAME,EAAOO,CAAAA,CAAoBb,CAAAA,CAAM,QAAQ,SAAA,CACzCO,CAAAA,CAAOO,EAAoBd,CAAAA,CAAM,OAAA,CAAQ,UAC/C,GAAII,CAAAA,CAAQ,UACNE,CAAAA,CAAMF,CAAAA,CAAQ,UAAU,MAAA,EAAUA,CAAAA,CAAQ,UAAUE,CAAG,CAAA,GAAMC,IAC/DH,CAAAA,CAAQ,SAAA,CAAUE,CAAG,CAAA,CAAI,EAAA,CACzBI,EAAeN,CAAAA,CAASE,CAAAA,CAAKC,CAAG,CAAA,CAAA,CAAA,KAE7B,CACL,IAAMc,CAAAA,CAAOjB,CAAAA,CAAQ,SAAS,GAAA,CAAIE,CAAG,EACrC,GAAIe,CAAAA,CAAM,CACR,IAAMG,CAAAA,CAAMH,EAAK,OAAA,CAAQd,CAAG,EACxBiB,CAAAA,EAAO,CAAA,EAAGH,EAAK,MAAA,CAAOG,CAAAA,CAAK,CAAC,CAAA,CAC5BH,CAAAA,CAAK,SAAW,CAAA,EAAGjB,CAAAA,CAAQ,SAAS,MAAA,CAAOE,CAAG,EACpD,CACF,CACA,IAAMgB,CAAAA,CAAQlB,CAAAA,CAAQ,KAAK,GAAA,CAAIE,CAAG,EAC9BgB,CAAAA,GACFA,CAAAA,CAAM,OAAOf,CAAG,CAAA,CACZe,EAAM,IAAA,GAAS,CAAA,EAAGlB,EAAQ,IAAA,CAAK,MAAA,CAAOE,CAAG,CAAA,EAEjD,CAEO,SAASmB,CAAAA,CACdb,CAAAA,CACAC,EACAZ,CAAAA,CACqB,CACrB,IAAMD,CAAAA,CAAQ0B,CAAAA,CAAcd,CAAK,CAAA,CAC3BR,CAAAA,CAAUL,EAAUC,CAAAA,CAAOC,CAAwB,EACzD,GAAI,CAACG,EAAS,OAAO,GACrB,IAAME,CAAAA,CAAOO,EAAoBb,CAAAA,CAAM,OAAA,CAAQ,UAC/C,GAAII,CAAAA,CAAQ,UAAW,CACrB,GAAIE,EAAMF,CAAAA,CAAQ,SAAA,CAAU,OAAQ,CAClC,IAAMG,IAAMH,CAAAA,CAAQ,SAAA,CAAUE,CAAG,CAAA,EAAK,EAAA,CACtC,GAAIC,GAAAA,EAAO,CAAA,CAAG,CACZ,IAAMoB,CAAAA,CAAM3B,EAAM,WAAA,CAAYO,GAAG,GAAK,CAAA,CACtC,OAAO,CAACqB,CAAAA,CAAQrB,GAAAA,CAAKoB,EAAK3B,CAAAA,CAAM,OAAO,CAAC,CAC1C,CACF,CACA,OAAO,EACT,CACA,IAAMqB,IAAOjB,CAAAA,CAAQ,QAAA,CAAS,IAAIE,CAAG,CAAA,CACrC,OAAKe,GAAAA,CACEA,GAAAA,CAAK,IAAKQ,GAAAA,EAAS,CACxB,IAAMF,CAAAA,CAAM3B,CAAAA,CAAM,YAAY6B,GAAI,CAAA,EAAK,EACvC,OAAOD,CAAAA,CAAQC,GAAAA,CAAMF,CAAAA,CAAK3B,EAAM,OAAO,CACzC,CAAC,CAAA,CAJiB,EAKpB,CAmBO,SAAS8B,EACdlB,CAAAA,CACAC,CAAAA,CACAZ,EACAa,CAAAA,CACe,CACf,IAAMd,CAAAA,CAAQ0B,CAAAA,CAAcd,CAAK,CAAA,CAC3BR,CAAAA,CAAUL,EAAUC,CAAAA,CAAOC,CAAwB,EACzD,GAAI,CAACG,EAAS,OACd,IAAME,IAAOO,CAAAA,CAAoBb,CAAAA,CAAM,QAAQ,SAAA,CACzCO,CAAAA,CAAOO,EAAoBd,CAAAA,CAAM,OAAA,CAAQ,UAC/C,OAAOI,CAAAA,CAAQ,KAAK,GAAA,CAAIE,GAAG,GAAG,GAAA,CAAIC,CAAG,CACvC,CAGAwB,CAAAA,CAAyB,CAAC/B,CAAAA,CAAmBgC,CAAAA,GAAkB,CAC7D,IAAMC,CAAAA,CAAKD,EAAiBhC,CAAAA,CAAM,OAAA,CAAQ,UAC1C,IAAA,IAAWI,CAAAA,IAAWJ,EAAM,eAAA,CAAgB,MAAA,GAAU,CACpD,GAAII,EAAQ,SAAA,CAAW,CAGrB,GAAI6B,CAAAA,CAAI7B,CAAAA,CAAQ,UAAU,MAAA,CAAQ,CAChC,IAAM8B,CAAAA,CAAM9B,CAAAA,CAAQ,UAAU6B,CAAC,CAAA,EAAK,GAChCC,CAAAA,EAAO,CAAA,EAAGxB,EAAeN,CAAAA,CAAS6B,CAAAA,CAAGC,CAAG,CAAA,CAC5C9B,CAAAA,CAAQ,UAAU6B,CAAC,CAAA,CAAI,GACzB,CAMA,IAAME,EAAc/B,CAAAA,CAAQ,QAAA,EAAU,IAAI6B,CAAC,CAAA,CAC3C,GAAIE,CAAAA,CAAa,CACf,QAAW7B,CAAAA,IAAO6B,CAAAA,CACZ7B,EAAMF,CAAAA,CAAQ,SAAA,CAAU,SAAQA,CAAAA,CAAQ,SAAA,CAAUE,CAAG,CAAA,CAAI,EAAA,CAAA,CAE/DF,EAAQ,QAAA,EAAU,MAAA,CAAO6B,CAAC,EAC5B,CACF,CACA7B,CAAAA,CAAQ,QAAA,CAAS,OAAO6B,CAAC,CAAA,CACzB,OAAW,CAAC3B,CAAAA,CAAKe,CAAI,CAAA,GAAKjB,CAAAA,CAAQ,SAAU,CAC1C,IAAMoB,EAAMH,CAAAA,CAAK,OAAA,CAAQY,CAAC,CAAA,CACtBT,CAAAA,EAAO,IACTH,CAAAA,CAAK,MAAA,CAAOG,EAAK,CAAC,CAAA,CACdH,EAAK,MAAA,GAAW,CAAA,EAAGjB,EAAQ,QAAA,CAAS,MAAA,CAAOE,CAAG,CAAA,EAEtD,CAIAF,EAAQ,IAAA,CAAK,MAAA,CAAO6B,CAAC,CAAA,CACrB,IAAA,GAAW,CAAC3B,CAAAA,CAAKgB,CAAK,IAAKlB,CAAAA,CAAQ,IAAA,CACjCkB,EAAM,MAAA,CAAOW,CAAC,EACVX,CAAAA,CAAM,IAAA,GAAS,GAAGlB,CAAAA,CAAQ,IAAA,CAAK,OAAOE,CAAG,EAEjD,CACF,CAAC,CAAA","file":"relations.js","sourcesContent":["// aiecsjs/relations — entity-to-entity relations (experimental in 0.1).\n\nimport { isAliveInternal, packEid, registerRelationsCleanup } from './internal/entity.js'\nimport { EcsError } from './internal/errors.js'\nimport { ids, shared } from './internal/registry.js'\nimport type { EntityId, Relation, RelationStorage, World, WorldState } from './internal/types.js'\nimport { getWorldState, getWritableState } from './internal/world.js'\n\nexport function defineRelation<T = void>(options?: { exclusive?: boolean }): Relation<T> {\n  const id = ids.relation++\n  return {\n    __kind: 'relation',\n    __id: id,\n    __exclusive: options?.exclusive ?? false,\n    __hasData: false,\n  } as Relation<T>\n}\n\n// One ChildOf for every loaded copy of the package (see registry.ts), so a\n// hierarchy built through one copy is visible through another.\nshared.childOf ??= defineRelation({ exclusive: true })\nexport const ChildOf: Relation = shared.childOf\n\n// The relation's storage in this world (undefined until its first edge).\n// Rejects a value that is not a `defineRelation` handle.\nfunction storageOf(state: WorldState, rel: Relation<unknown>): RelationStorage | undefined {\n  if (rel?.__kind !== 'relation') throw new EcsError('aiecsjs: rel must be a relation')\n  return state.relationStorage.get(rel.__id)\n}\n\nfunction getOrCreateStorage(state: WorldState, rel: Relation<unknown>): RelationStorage {\n  let storage = storageOf(state, rel)\n  if (storage) return storage\n  storage = {\n    rel,\n    exclusive: rel.__exclusive ? new Int32Array(state.capacity).fill(-1) : null,\n    incoming: rel.__exclusive ? new Map<number, Set<number>>() : null,\n    outgoing: new Map<number, number[]>(),\n    data: new Map<number, Map<number, unknown>>(),\n  }\n  state.relationStorage.set(rel.__id, storage)\n  return storage\n}\n\n// --- Exclusive reverse-index (incoming) helpers ---\n// `incoming` mirrors the `exclusive` array: incoming.get(tgt) is the set of\n// source slots whose exclusive[src] === tgt. Every place that writes a non-`-1`\n// value into `exclusive` must call `linkIncoming`, and every place that clears a\n// slot (sets it back to -1) must call `unlinkIncoming`, so the reverse index\n// never drifts from the forward array.\n\nfunction linkIncoming(storage: RelationStorage, src: number, tgt: number): void {\n  const incoming = storage.incoming\n  if (!incoming) return\n  let set = incoming.get(tgt)\n  if (!set) {\n    set = new Set<number>()\n    incoming.set(tgt, set)\n  }\n  set.add(src)\n}\n\nfunction unlinkIncoming(storage: RelationStorage, src: number, tgt: number): void {\n  const incoming = storage.incoming\n  if (!incoming) return\n  const set = incoming.get(tgt)\n  if (!set) return\n  set.delete(src)\n  if (set.size === 0) incoming.delete(tgt)\n}\n\n/**\n * Add a relation edge from `source` to `target` (replacing `source`'s current\n * target for an exclusive relation such as `ChildOf`), optionally with a data\n * payload read back by {@link getRelationData}.\n *\n * Throws `EcsError` when `source` or `target` is not alive, mirroring\n * `addComponent`: edges are stored by slot, so an edge to a dead entity would\n * otherwise be inherited by whatever entity is later recycled into that slot.\n * Check `entityExists` first when an endpoint may be stale.\n */\nexport function addRelation<T>(\n  world: World,\n  source: EntityId,\n  rel: Relation<T>,\n  target: EntityId,\n  data?: T,\n): void {\n  const state = getWritableState(world)\n  if (!isAliveInternal(state, source)) {\n    throw new EcsError(`aiecsjs: addRelation on dead source entity ${source}`)\n  }\n  if (!isAliveInternal(state, target)) {\n    throw new EcsError(`aiecsjs: addRelation on dead target entity ${target}`)\n  }\n  const storage = getOrCreateStorage(state, rel as Relation<unknown>)\n  // Use raw idx as keys in relation storage so slot reuse invalidation is consistent\n  const src = (source as number) & state.options.indexMask\n  const tgt = (target as number) & state.options.indexMask\n\n  if (storage.exclusive) {\n    if (src >= storage.exclusive.length) {\n      const next = new Int32Array(Math.max(src + 1, storage.exclusive.length * 2)).fill(-1)\n      next.set(storage.exclusive)\n      storage.exclusive = next\n    }\n    // Exclusive redirect: if this source already pointed at a different target,\n    // drop that previous target's data entry so getRelationData stays consistent\n    // with getRelationTargets, which reports only the current exclusive target.\n    const prevTgt = storage.exclusive[src] ?? -1\n    if (prevTgt >= 0 && prevTgt !== tgt) {\n      const prevInner = storage.data.get(src)\n      prevInner?.delete(prevTgt)\n      if (prevInner && prevInner.size === 0) storage.data.delete(src)\n      unlinkIncoming(storage, src, prevTgt)\n    }\n    storage.exclusive[src] = tgt\n    if (prevTgt !== tgt) linkIncoming(storage, src, tgt)\n  } else {\n    let list = storage.outgoing.get(src)\n    if (!list) {\n      list = []\n      storage.outgoing.set(src, list)\n    }\n    if (!list.includes(tgt)) list.push(tgt)\n  }\n\n  if (data !== undefined) {\n    let inner = storage.data.get(src)\n    if (!inner) {\n      inner = new Map<number, unknown>()\n      storage.data.set(src, inner)\n    }\n    inner.set(tgt, data)\n  }\n}\n\nexport function removeRelation(\n  world: World,\n  source: EntityId,\n  rel: Relation,\n  target: EntityId,\n): void {\n  const state = getWritableState(world)\n  const storage = storageOf(state, rel as Relation<unknown>)\n  if (!storage) return\n  const src = (source as number) & state.options.indexMask\n  const tgt = (target as number) & state.options.indexMask\n  if (storage.exclusive) {\n    if (src < storage.exclusive.length && storage.exclusive[src] === tgt) {\n      storage.exclusive[src] = -1\n      unlinkIncoming(storage, src, tgt)\n    }\n  } else {\n    const list = storage.outgoing.get(src)\n    if (list) {\n      const idx = list.indexOf(tgt)\n      if (idx >= 0) list.splice(idx, 1)\n      if (list.length === 0) storage.outgoing.delete(src)\n    }\n  }\n  const inner = storage.data.get(src)\n  if (inner) {\n    inner.delete(tgt)\n    if (inner.size === 0) storage.data.delete(src)\n  }\n}\n\nexport function getRelationTargets(\n  world: World,\n  source: EntityId,\n  rel: Relation,\n): readonly EntityId[] {\n  const state = getWorldState(world)\n  const storage = storageOf(state, rel as Relation<unknown>)\n  if (!storage) return []\n  const src = (source as number) & state.options.indexMask\n  if (storage.exclusive) {\n    if (src < storage.exclusive.length) {\n      const tgt = storage.exclusive[src] ?? -1\n      if (tgt >= 0) {\n        const gen = state.generations[tgt] ?? 0\n        return [packEid(tgt, gen, state.options)]\n      }\n    }\n    return []\n  }\n  const list = storage.outgoing.get(src)\n  if (!list) return []\n  return list.map((tIdx) => {\n    const gen = state.generations[tIdx] ?? 0\n    return packEid(tIdx, gen, state.options)\n  })\n}\n\n/**\n * Read the data payload attached to a relation edge.\n *\n * Returns the `data` value that was supplied to {@link addRelation} for the\n * `(source, rel, target)` triple, or `undefined` when:\n * - the relation has never been stored for this world,\n * - no edge from `source` to `target` via `rel` exists, or\n * - the edge was added without a data argument.\n *\n * **Slot keying:** relation storage keys edges by raw entity slot index\n * (`entityId & indexMask`), not by the full packed EntityId. `addRelation`\n * rejects dead endpoints and `destroyEntity` / `resetWorld` drop every edge of\n * the entities they remove, so storage never holds an edge for a dead entity.\n * A *stale* EntityId whose slot was recycled still addresses the slot's\n * current occupant here, so validate cached ids with `entityExists` (or use\n * `EntityRef`) before reading.\n */\nexport function getRelationData<T>(\n  world: World,\n  source: EntityId,\n  rel: Relation<T>,\n  target: EntityId,\n): T | undefined {\n  const state = getWorldState(world)\n  const storage = storageOf(state, rel as Relation<unknown>)\n  if (!storage) return undefined\n  const src = (source as number) & state.options.indexMask\n  const tgt = (target as number) & state.options.indexMask\n  return storage.data.get(src)?.get(tgt) as T | undefined\n}\n\n// Cleanup hook: when an entity is destroyed, remove all relations involving it.\nregisterRelationsCleanup((state: WorldState, eid: EntityId) => {\n  const e = (eid as number) & state.options.indexMask\n  for (const storage of state.relationStorage.values()) {\n    if (storage.exclusive) {\n      // `e` as a SOURCE: clear its own exclusive slot and unlink it from whatever\n      // target it currently points at, so the reverse index stays consistent.\n      if (e < storage.exclusive.length) {\n        const cur = storage.exclusive[e] ?? -1\n        if (cur >= 0) unlinkIncoming(storage, e, cur)\n        storage.exclusive[e] = -1\n      }\n      // `e` as a TARGET: clear every source that points at it. Use the reverse\n      // index to touch only the actual incoming sources (O(incoming)) instead of\n      // scanning the entire `exclusive` capacity (O(capacity)) — the bounded-cost\n      // path for large sparse relation tables. Behaviour is identical to the old\n      // full scan: every src with exclusive[src] === e is reset to -1.\n      const incomingSet = storage.incoming?.get(e)\n      if (incomingSet) {\n        for (const src of incomingSet) {\n          if (src < storage.exclusive.length) storage.exclusive[src] = -1\n        }\n        storage.incoming?.delete(e)\n      }\n    }\n    storage.outgoing.delete(e)\n    for (const [src, list] of storage.outgoing) {\n      const idx = list.indexOf(e)\n      if (idx >= 0) {\n        list.splice(idx, 1)\n        if (list.length === 0) storage.outgoing.delete(src)\n      }\n    }\n    // Clear data entries involving this entity. The outer key is the source\n    // eid; entries whose source IS this entity drop entirely. Entries that\n    // reference this entity as a target are pruned from each inner map.\n    storage.data.delete(e)\n    for (const [src, inner] of storage.data) {\n      inner.delete(e)\n      if (inner.size === 0) storage.data.delete(src)\n    }\n  }\n})\n"]}

package/dist/serialize.cjs

@@ -1,2 +1,2 @@
-'use strict';var chunkJDV5JZP2_cjs=require('./chunk-JDV5JZP2.cjs');require('./chunk-Q2XLL6YG.cjs');Object.defineProperty(exports,"createDeltaSerializer",{enumerable:true,get:function(){return chunkJDV5JZP2_cjs.e}});Object.defineProperty(exports,"deserializeWorld",{enumerable:true,get:function(){return chunkJDV5JZP2_cjs.b}});Object.defineProperty(exports,"fromJSON",{enumerable:true,get:function(){return chunkJDV5JZP2_cjs.d}});Object.defineProperty(exports,"serializeWorld",{enumerable:true,get:function(){return chunkJDV5JZP2_cjs.a}});Object.defineProperty(exports,"toJSON",{enumerable:true,get:function(){return chunkJDV5JZP2_cjs.c}});//# sourceMappingURL=serialize.cjs.map
+'use strict';var chunkMVBFYRHY_cjs=require('./chunk-MVBFYRHY.cjs');require('./chunk-NPNWRCB5.cjs');Object.defineProperty(exports,"createDeltaSerializer",{enumerable:true,get:function(){return chunkMVBFYRHY_cjs.e}});Object.defineProperty(exports,"deserializeWorld",{enumerable:true,get:function(){return chunkMVBFYRHY_cjs.b}});Object.defineProperty(exports,"fromJSON",{enumerable:true,get:function(){return chunkMVBFYRHY_cjs.d}});Object.defineProperty(exports,"serializeWorld",{enumerable:true,get:function(){return chunkMVBFYRHY_cjs.a}});Object.defineProperty(exports,"toJSON",{enumerable:true,get:function(){return chunkMVBFYRHY_cjs.c}});//# sourceMappingURL=serialize.cjs.map
 //# sourceMappingURL=serialize.cjs.map

package/dist/serialize.d.cts

@@ -1,16 +1,41 @@
-import { W as World, S as SerializeOptions, D as DeltaSerializer, e as DeserializeOptions, p as WorldSnapshot } from './types-BeVLA7xG.cjs';
+import { W as World, S as SerializeOptions, D as DeltaSerializer, e as DeserializeOptions, p as WorldSnapshot } from './types-C6TkQ7HW.cjs';
 
 declare function serializeWorld(world: World, options?: SerializeOptions): Uint8Array;
+/**
+ * Restore a world from `serializeWorld` bytes. Same resolution rules and
+ * options as {@link fromJSON}; the binary header's format version is checked
+ * against `onUnknownVersion` first.
+ */
 declare function deserializeWorld(bytes: Uint8Array, options?: DeserializeOptions): World;
 /**
- * Serialize a world snapshot to a plain JSON-compatible object.
+ * Serialize a world snapshot to a plain JSON-compatible object (format 2).
+ *
+ * `components` lists every component the entities reference with its stable
+ * `key` (from `defineComponent(..., { key })`), kind and SoA fields, so a
+ * loader can match data to components by key rather than by creation order.
+ *
+ * AoS component data is deep-copied (`structuredClone`), so the snapshot never
+ * aliases live component instances; AoS values must therefore be cloneable.
  *
  * Note: `EntityRef` is in-memory only — not preserved across serialize/deserialize.
- * Generation counters reset on world load. Stale refs from before serialization
- * will deref to null after loading the snapshot into a new world.
+ * `fromJSON` / `deserializeWorld` re-create entities in snapshot order with
+ * fresh ids (generation 0, holes in the slot range closed up), so stale refs
+ * deref to null and EntityIds stored inside component data are not remapped.
  */
 declare function toJSON(world: World): WorldSnapshot;
-declare function fromJSON(snapshot: WorldSnapshot): World;
+/**
+ * Restore a world from a `toJSON` snapshot.
+ *
+ * Every component the snapshot references is resolved before the world is
+ * created: by `key` for keyed components, by creation-order id otherwise. A
+ * component this process has not defined throws `EcsError` unless
+ * `onUnknownComponent: 'skip'`; a kind or SoA-field mismatch always throws
+ * `EcsError`. A snapshot without `formatVersion: 2` (every 0.5.x snapshot)
+ * throws `EcsError` unless `onUnknownVersion: 'best-effort'`, which loads it by
+ * id with a kind check only. `options.components` restricts which components
+ * are loaded.
+ */
+declare function fromJSON(snapshot: WorldSnapshot, options?: DeserializeOptions): World;
 declare function createDeltaSerializer(world: World, options?: SerializeOptions): DeltaSerializer;
 
 export { createDeltaSerializer, deserializeWorld, fromJSON, serializeWorld, toJSON };

package/dist/serialize.d.ts

@@ -1,16 +1,41 @@
-import { W as World, S as SerializeOptions, D as DeltaSerializer, e as DeserializeOptions, p as WorldSnapshot } from './types-BeVLA7xG.js';
+import { W as World, S as SerializeOptions, D as DeltaSerializer, e as DeserializeOptions, p as WorldSnapshot } from './types-C6TkQ7HW.js';
 
 declare function serializeWorld(world: World, options?: SerializeOptions): Uint8Array;
+/**
+ * Restore a world from `serializeWorld` bytes. Same resolution rules and
+ * options as {@link fromJSON}; the binary header's format version is checked
+ * against `onUnknownVersion` first.
+ */
 declare function deserializeWorld(bytes: Uint8Array, options?: DeserializeOptions): World;
 /**
- * Serialize a world snapshot to a plain JSON-compatible object.
+ * Serialize a world snapshot to a plain JSON-compatible object (format 2).
+ *
+ * `components` lists every component the entities reference with its stable
+ * `key` (from `defineComponent(..., { key })`), kind and SoA fields, so a
+ * loader can match data to components by key rather than by creation order.
+ *
+ * AoS component data is deep-copied (`structuredClone`), so the snapshot never
+ * aliases live component instances; AoS values must therefore be cloneable.
  *
  * Note: `EntityRef` is in-memory only — not preserved across serialize/deserialize.
- * Generation counters reset on world load. Stale refs from before serialization
- * will deref to null after loading the snapshot into a new world.
+ * `fromJSON` / `deserializeWorld` re-create entities in snapshot order with
+ * fresh ids (generation 0, holes in the slot range closed up), so stale refs
+ * deref to null and EntityIds stored inside component data are not remapped.
  */
 declare function toJSON(world: World): WorldSnapshot;
-declare function fromJSON(snapshot: WorldSnapshot): World;
+/**
+ * Restore a world from a `toJSON` snapshot.
+ *
+ * Every component the snapshot references is resolved before the world is
+ * created: by `key` for keyed components, by creation-order id otherwise. A
+ * component this process has not defined throws `EcsError` unless
+ * `onUnknownComponent: 'skip'`; a kind or SoA-field mismatch always throws
+ * `EcsError`. A snapshot without `formatVersion: 2` (every 0.5.x snapshot)
+ * throws `EcsError` unless `onUnknownVersion: 'best-effort'`, which loads it by
+ * id with a kind check only. `options.components` restricts which components
+ * are loaded.
+ */
+declare function fromJSON(snapshot: WorldSnapshot, options?: DeserializeOptions): World;
 declare function createDeltaSerializer(world: World, options?: SerializeOptions): DeltaSerializer;
 
 export { createDeltaSerializer, deserializeWorld, fromJSON, serializeWorld, toJSON };

package/dist/serialize.js

@@ -1,2 +1,2 @@
-export{e as createDeltaSerializer,b as deserializeWorld,d as fromJSON,a as serializeWorld,c as toJSON}from'./chunk-ZZBNE7C5.js';import'./chunk-OBMQME2P.js';//# sourceMappingURL=serialize.js.map
+export{e as createDeltaSerializer,b as deserializeWorld,d as fromJSON,a as serializeWorld,c as toJSON}from'./chunk-GJ6U2TIU.js';import'./chunk-27JX7WHY.js';//# sourceMappingURL=serialize.js.map
 //# sourceMappingURL=serialize.js.map

package/dist/{types-BeVLA7xG.d.cts → types-C6TkQ7HW.d.cts}

@@ -106,11 +106,44 @@ interface SerializeOptions {
 }
 interface DeserializeOptions {
     components?: ComponentLike[];
+    /**
+     * `'throw'` (default) rejects a snapshot whose format version is not 2 —
+     * including every 0.5.x snapshot — with `EcsError`. `'best-effort'` loads it
+     * anyway; a snapshot without a format 2 component table is then resolved by
+     * creation-order id with a `kind` check only (0.5.x behaviour).
+     */
     onUnknownVersion?: 'throw' | 'best-effort';
+    /**
+     * `'throw'` (default) rejects a snapshot that references a component this
+     * process has not defined with `EcsError`; `'skip'` drops that component's
+     * data and loads the rest.
+     */
+    onUnknownComponent?: 'throw' | 'skip';
 }
 interface WorldSnapshot {
+    /** Snapshot format; 0.6.0 writes 2. 0.5.x snapshots have no `formatVersion`. */
+    formatVersion: 2;
     version: string;
     capacity: number;
+    maxEntities?: number;
+    indexBits?: number;
+    generationBits?: number;
+    /**
+     * One entry per component referenced by `entities`: the source process's
+     * component `id`, its stable `key` (null when keyless), its `kind`, and for
+     * SoA its fields in declaration order. A loader resolves each entry by `key`
+     * (by `id` when keyless) and rejects a kind or field mismatch.
+     */
+    components: Array<{
+        id: number;
+        key: string | null;
+        kind: 'soa' | 'aos' | 'tag';
+        fields: Array<{
+            name: string;
+            type: SoAFieldType;
+            vectorLen: number;
+        }> | null;
+    }>;
     entities: Array<{
         eid: number;
         components: Array<{

package/dist/{types-BeVLA7xG.d.ts → types-C6TkQ7HW.d.ts}

@@ -106,11 +106,44 @@ interface SerializeOptions {
 }
 interface DeserializeOptions {
     components?: ComponentLike[];
+    /**
+     * `'throw'` (default) rejects a snapshot whose format version is not 2 —
+     * including every 0.5.x snapshot — with `EcsError`. `'best-effort'` loads it
+     * anyway; a snapshot without a format 2 component table is then resolved by
+     * creation-order id with a `kind` check only (0.5.x behaviour).
+     */
     onUnknownVersion?: 'throw' | 'best-effort';
+    /**
+     * `'throw'` (default) rejects a snapshot that references a component this
+     * process has not defined with `EcsError`; `'skip'` drops that component's
+     * data and loads the rest.
+     */
+    onUnknownComponent?: 'throw' | 'skip';
 }
 interface WorldSnapshot {
+    /** Snapshot format; 0.6.0 writes 2. 0.5.x snapshots have no `formatVersion`. */
+    formatVersion: 2;
     version: string;
     capacity: number;
+    maxEntities?: number;
+    indexBits?: number;
+    generationBits?: number;
+    /**
+     * One entry per component referenced by `entities`: the source process's
+     * component `id`, its stable `key` (null when keyless), its `kind`, and for
+     * SoA its fields in declaration order. A loader resolves each entry by `key`
+     * (by `id` when keyless) and rejects a kind or field mismatch.
+     */
+    components: Array<{
+        id: number;
+        key: string | null;
+        kind: 'soa' | 'aos' | 'tag';
+        fields: Array<{
+            name: string;
+            type: SoAFieldType;
+            vectorLen: number;
+        }> | null;
+    }>;
     entities: Array<{
         eid: number;
         components: Array<{

package/dist/worker.cjs

@@ -1,2 +1,2 @@
-'use strict';var chunkJDV5JZP2_cjs=require('./chunk-JDV5JZP2.cjs'),chunkQ2XLL6YG_cjs=require('./chunk-Q2XLL6YG.cjs');var l=1095320899;function W(r){let e=chunkQ2XLL6YG_cjs.j(r),o=chunkJDV5JZP2_cjs.a(r);if(typeof SharedArrayBuffer>"u"){let n=new ArrayBuffer(o.byteLength);return new Uint8Array(n).set(o),{buffer:n,meta:p(e)}}let t=new SharedArrayBuffer(o.byteLength);return new Uint8Array(t).set(o),{buffer:t,meta:p(e)}}function b(r){m(r.meta);let e=new Uint8Array(r.buffer);return chunkJDV5JZP2_cjs.b(e)}function S(r,e){let o=new Uint8Array(r),t=chunkJDV5JZP2_cjs.b(o);if(e?.readOnly){let n=chunkQ2XLL6YG_cjs.j(t);n.readOnly=true;}return t}function B(r){chunkQ2XLL6YG_cjs.k(r.id)&&chunkQ2XLL6YG_cjs.m(r);}function p(r){let e=[];for(let o of r.componentInfoByBit)o&&e.push({id:o.id,kind:o.kind,schema:o.schema});return {magic:l,formatVersion:1,aiecsjsVersion:chunkQ2XLL6YG_cjs.a,indexBits:r.options.indexBits,generationBits:r.options.generationBits,maxComponents:r.options.maxComponents,maskWordCount:r.options.maskWordCount,capacity:r.capacity,componentSchemas:e}}function m(r){if(r.magic!==l)throw new Error("aiecsjs: invalid snapshot meta (wrong magic)");if(r.formatVersion!==1)throw new Error(`aiecsjs: unsupported snapshot format version ${r.formatVersion}`)}exports.adoptSnapshot=b;exports.attachWorld=S;exports.detachWorld=B;exports.transferableSnapshot=W;//# sourceMappingURL=worker.cjs.map
+'use strict';var chunkMVBFYRHY_cjs=require('./chunk-MVBFYRHY.cjs'),chunkNPNWRCB5_cjs=require('./chunk-NPNWRCB5.cjs');var c=1095320899;function S(e){let r=chunkNPNWRCB5_cjs.i(e),o=chunkMVBFYRHY_cjs.a(e),a=typeof SharedArrayBuffer>"u"?new ArrayBuffer(o.byteLength):new SharedArrayBuffer(o.byteLength);return new Uint8Array(a).set(o),{buffer:a,meta:p(r)}}function b(e,r){return m(e?.meta,r),chunkMVBFYRHY_cjs.b(new Uint8Array(e.buffer),r)}function B(e,r){let o=chunkMVBFYRHY_cjs.b(new Uint8Array(e),r);return r?.readOnly&&(chunkNPNWRCB5_cjs.i(o).readOnly=true),o}function g(e){chunkNPNWRCB5_cjs.k(e.id)&&chunkNPNWRCB5_cjs.m(e);}function p(e){let r=[];for(let o of e.componentInfoByBit)o&&r.push({id:o.id,kind:o.kind,schema:o.schema});return {magic:c,formatVersion:2,aiecsjsVersion:chunkNPNWRCB5_cjs.a,indexBits:e.options.indexBits,generationBits:e.options.generationBits,maxComponents:e.options.maxComponents,maskWordCount:e.options.maskWordCount,capacity:e.capacity,componentSchemas:r}}function m(e,r){if(e?.magic!==c)throw new chunkNPNWRCB5_cjs.f("aiecsjs: invalid snapshot meta (wrong magic)");if(e.formatVersion!==2&&r?.onUnknownVersion!=="best-effort")throw new chunkNPNWRCB5_cjs.f(`aiecsjs: format version ${e.formatVersion} not supported`)}exports.adoptSnapshot=b;exports.attachWorld=B;exports.detachWorld=g;exports.transferableSnapshot=S;//# sourceMappingURL=worker.cjs.map
 //# sourceMappingURL=worker.cjs.map

package/dist/worker.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/worker.ts"],"names":["MAGIC","transferableSnapshot","world","state","getWorldState","bytes","serializeWorld","ab","buildMeta","sab","adoptSnapshot","snap","validateMeta","deserializeWorld","attachWorld","buffer","options","detachWorld","isWorldRegistered","destroyWorld","componentSchemas","info","VERSION","meta"],"mappings":"qHAkBA,IAAMA,CAAAA,CAAQ,WAEP,SAASC,CAAAA,CAAqBC,EAAoC,CACvE,IAAMC,CAAAA,CAAQC,mBAAAA,CAAcF,CAAK,CAAA,CAC3BG,EAAQC,mBAAAA,CAAeJ,CAAK,EAElC,GAAI,OAAO,kBAAsB,GAAA,CAAa,CAI5C,IAAMK,CAAAA,CAAK,IAAI,WAAA,CAAYF,EAAM,UAAU,CAAA,CAC3C,WAAI,UAAA,CAAWE,CAAE,EAAE,GAAA,CAAIF,CAAK,CAAA,CACrB,CACL,MAAA,CAAQE,CAAAA,CACR,KAAMC,CAAAA,CAAUL,CAAK,CACvB,CACF,CAEA,IAAMM,EAAM,IAAI,iBAAA,CAAkBJ,CAAAA,CAAM,UAAU,CAAA,CAClD,OAAA,IAAI,WAAWI,CAAG,CAAA,CAAE,IAAIJ,CAAK,CAAA,CACtB,CAAE,MAAA,CAAQI,CAAAA,CAAK,IAAA,CAAMD,CAAAA,CAAUL,CAAK,CAAE,CAC/C,CAaO,SAASO,CAAAA,CAAcC,CAAAA,CAAmC,CAC/DC,CAAAA,CAAaD,EAAK,IAAI,CAAA,CACtB,IAAMN,CAAAA,CAAQ,IAAI,UAAA,CAAWM,EAAK,MAAM,CAAA,CACxC,OAAOE,mBAAAA,CAAiBR,CAAK,CAC/B,CAaO,SAASS,CAAAA,CACdC,CAAAA,CACAC,CAAAA,CACO,CACP,IAAMX,CAAAA,CAAQ,IAAI,UAAA,CAAWU,CAAM,CAAA,CAC7Bb,CAAAA,CAAQW,oBAAiBR,CAAK,CAAA,CACpC,GAAIW,CAAAA,EAAS,QAAA,CAAU,CACrB,IAAMb,CAAAA,CAAQC,mBAAAA,CAAcF,CAAK,CAAA,CACjCC,CAAAA,CAAM,SAAW,KACnB,CACA,OAAOD,CACT,CAEO,SAASe,EAAYf,CAAAA,CAAoB,CAC1CgB,mBAAAA,CAAkBhB,CAAAA,CAAM,EAAE,CAAA,EAC5BiB,oBAAajB,CAAK,EAEtB,CAEA,SAASM,CAAAA,CAAUL,CAAAA,CAA8B,CAC/C,IAAMiB,CAAAA,CAAkD,EAAC,CACzD,IAAA,IAAWC,KAAQlB,CAAAA,CAAM,kBAAA,CAClBkB,CAAAA,EACLD,CAAAA,CAAiB,IAAA,CAAK,CAAE,GAAIC,CAAAA,CAAK,EAAA,CAAI,IAAA,CAAMA,CAAAA,CAAK,IAAA,CAAM,MAAA,CAAQA,EAAK,MAAO,CAAC,CAAA,CAE7E,OAAO,CACL,KAAA,CAAOrB,EACP,aAAA,CAAe,CAAA,CACf,eAAgBsB,mBAAAA,CAChB,SAAA,CAAWnB,EAAM,OAAA,CAAQ,SAAA,CACzB,cAAA,CAAgBA,CAAAA,CAAM,OAAA,CAAQ,cAAA,CAC9B,cAAeA,CAAAA,CAAM,OAAA,CAAQ,aAAA,CAC7B,aAAA,CAAeA,CAAAA,CAAM,OAAA,CAAQ,cAC7B,QAAA,CAAUA,CAAAA,CAAM,QAAA,CAChB,gBAAA,CAAAiB,CACF,CACF,CAEA,SAASR,CAAAA,CAAaW,EAAuB,CAC3C,GAAIA,EAAK,KAAA,GAAUvB,CAAAA,CACjB,MAAM,IAAI,KAAA,CAAM,8CAA8C,EAEhE,GAAIuB,CAAAA,CAAK,aAAA,GAAkB,CAAA,CACzB,MAAM,IAAI,MAAM,CAAA,6CAAA,EAAgDA,CAAAA,CAAK,aAAa,CAAA,CAAE,CAExF","file":"worker.cjs","sourcesContent":["// aiecsjs/worker — SharedArrayBuffer helpers (experimental, snapshot-copy).\n//\n// Note: 0.x implements SAB as a transferable snapshot pattern rather than true\n// shared-memory aliasing. The world is serialized into the SAB, and the worker\n// reconstructs a fresh world from those bytes via adoptSnapshot/attachWorld.\n// True shared-column memory is targeted for a future stable release.\n// The API matches the documented contract and survives postMessage cleanly.\n//\n// EntityRef is in-memory only — not preserved across worker boundaries.\n// Generation counters reset on adoptSnapshot/attachWorld. Pass `EntityRef.id`\n// (the packed EntityId) across the worker boundary only if you understand that\n// the generation portion will be stale after a round-trip snapshot.\n\nimport type { TransferableSnapshot, World, WorldMeta, WorldState } from './internal/types.js'\nimport { destroyWorld, getWorldState, isWorldRegistered } from './internal/world.js'\nimport { deserializeWorld, serializeWorld } from './serialize.js'\nimport { VERSION } from './version.js'\n\nconst MAGIC = 0x41494543 // 'AIEC' little-endian as uint32\n\nexport function transferableSnapshot(world: World): TransferableSnapshot {\n  const state = getWorldState(world)\n  const bytes = serializeWorld(world)\n\n  if (typeof SharedArrayBuffer === 'undefined') {\n    // Fallback: a plain ArrayBuffer. TransferableSnapshot.buffer is typed\n    // `SharedArrayBuffer | ArrayBuffer`, so this needs no cast — the type tells\n    // the truth instead of pretending the fallback is a SAB.\n    const ab = new ArrayBuffer(bytes.byteLength)\n    new Uint8Array(ab).set(bytes)\n    return {\n      buffer: ab,\n      meta: buildMeta(state),\n    }\n  }\n\n  const sab = new SharedArrayBuffer(bytes.byteLength)\n  new Uint8Array(sab).set(bytes)\n  return { buffer: sab, meta: buildMeta(state) }\n}\n\n/**\n * Adopt a snapshot previously produced by `transferableSnapshot`.\n *\n * SECURITY: same trust expectation as `attachWorld` — the sender of the\n * `TransferableSnapshot` (typically a Web Worker) must be trusted. The\n * function runs `validateMeta` and `deserializeWorld`, which enforce magic\n * + format version + length bounds on the binary header; but the inner\n * JSON payload, once decoded, is fed to `addComponent` and reaches AoS\n * components. For untrusted senders, use `aibridgejs` + `toJSON(world)` at\n * the application boundary instead.\n */\nexport function adoptSnapshot(snap: TransferableSnapshot): World {\n  validateMeta(snap.meta)\n  const bytes = new Uint8Array(snap.buffer)\n  return deserializeWorld(bytes)\n}\n\n/**\n * Adopt a SharedArrayBuffer-backed snapshot produced by `transferableSnapshot`.\n *\n * SECURITY: the SAB sender must be trusted. `attachWorld` performs the same\n * magic + version + length-bounds checks as `deserializeWorld`, but the JSON\n * payload itself is deserialised into AoS components via `addComponent`. If\n * the sender is untrusted (e.g. a third-party Web Worker that you do not\n * audit), prefer the higher-level `aibridgejs` channel + `toJSON(world)`\n * pattern, which lets you validate the shape at the application boundary\n * before constructing entities.\n */\nexport function attachWorld(\n  buffer: SharedArrayBuffer | ArrayBuffer,\n  options?: { readOnly?: boolean },\n): World {\n  const bytes = new Uint8Array(buffer)\n  const world = deserializeWorld(bytes)\n  if (options?.readOnly) {\n    const state = getWorldState(world)\n    state.readOnly = true\n  }\n  return world\n}\n\nexport function detachWorld(world: World): void {\n  if (isWorldRegistered(world.id)) {\n    destroyWorld(world)\n  }\n}\n\nfunction buildMeta(state: WorldState): WorldMeta {\n  const componentSchemas: WorldMeta['componentSchemas'] = []\n  for (const info of state.componentInfoByBit) {\n    if (!info) continue\n    componentSchemas.push({ id: info.id, kind: info.kind, schema: info.schema })\n  }\n  return {\n    magic: MAGIC,\n    formatVersion: 1,\n    aiecsjsVersion: VERSION,\n    indexBits: state.options.indexBits,\n    generationBits: state.options.generationBits,\n    maxComponents: state.options.maxComponents,\n    maskWordCount: state.options.maskWordCount,\n    capacity: state.capacity,\n    componentSchemas,\n  }\n}\n\nfunction validateMeta(meta: WorldMeta): void {\n  if (meta.magic !== MAGIC) {\n    throw new Error('aiecsjs: invalid snapshot meta (wrong magic)')\n  }\n  if (meta.formatVersion !== 1) {\n    throw new Error(`aiecsjs: unsupported snapshot format version ${meta.formatVersion}`)\n  }\n}\n"]}
+{"version":3,"sources":["../src/worker.ts"],"names":["MAGIC","transferableSnapshot","world","state","getWorldState","bytes","serializeWorld","buffer","buildMeta","adoptSnapshot","snap","options","validateMeta","deserializeWorld","attachWorld","detachWorld","isWorldRegistered","destroyWorld","componentSchemas","info","VERSION","meta","EcsError"],"mappings":"qHAyBA,IAAMA,EAAQ,UAAA,CAEP,SAASC,EAAqBC,CAAAA,CAAoC,CACvE,IAAMC,CAAAA,CAAQC,mBAAAA,CAAcF,CAAK,CAAA,CAC3BG,CAAAA,CAAQC,oBAAeJ,CAAK,CAAA,CAK5BK,EACJ,OAAO,iBAAA,CAAsB,IACzB,IAAI,WAAA,CAAYF,EAAM,UAAU,CAAA,CAChC,IAAI,iBAAA,CAAkBA,CAAAA,CAAM,UAAU,CAAA,CAC5C,OAAA,IAAI,WAAWE,CAAM,CAAA,CAAE,IAAIF,CAAK,CAAA,CACzB,CAAE,MAAA,CAAAE,CAAAA,CAAQ,KAAMC,CAAAA,CAAUL,CAAK,CAAE,CAC1C,CAiBO,SAASM,CAAAA,CAAcC,CAAAA,CAA4BC,EAAqC,CAC7F,OAAAC,EAAaF,CAAAA,EAAM,IAAA,CAAMC,CAAO,CAAA,CACzBE,mBAAAA,CAAiB,IAAI,UAAA,CAAWH,CAAAA,CAAK,MAAM,CAAA,CAAGC,CAAO,CAC9D,CAgBO,SAASG,EACdP,CAAAA,CACAI,CAAAA,CACO,CACP,IAAMT,CAAAA,CAAQW,oBAAiB,IAAI,UAAA,CAAWN,CAAM,CAAA,CAAGI,CAAO,EAC9D,OAAIA,CAAAA,EAAS,WAAUP,mBAAAA,CAAcF,CAAK,EAAE,QAAA,CAAW,IAAA,CAAA,CAChDA,CACT,CAEO,SAASa,EAAYb,CAAAA,CAAoB,CAC1Cc,oBAAkBd,CAAAA,CAAM,EAAE,GAC5Be,mBAAAA,CAAaf,CAAK,EAEtB,CAEA,SAASM,EAAUL,CAAAA,CAA8B,CAC/C,IAAMe,CAAAA,CAAkD,GACxD,IAAA,IAAWC,CAAAA,IAAQhB,EAAM,kBAAA,CAClBgB,CAAAA,EACLD,EAAiB,IAAA,CAAK,CAAE,GAAIC,CAAAA,CAAK,EAAA,CAAI,KAAMA,CAAAA,CAAK,IAAA,CAAM,OAAQA,CAAAA,CAAK,MAAO,CAAC,CAAA,CAE7E,OAAO,CACL,KAAA,CAAOnB,CAAAA,CACP,cAAe,CAAA,CACf,cAAA,CAAgBoB,oBAChB,SAAA,CAAWjB,CAAAA,CAAM,QAAQ,SAAA,CACzB,cAAA,CAAgBA,EAAM,OAAA,CAAQ,cAAA,CAC9B,cAAeA,CAAAA,CAAM,OAAA,CAAQ,cAC7B,aAAA,CAAeA,CAAAA,CAAM,QAAQ,aAAA,CAC7B,QAAA,CAAUA,EAAM,QAAA,CAChB,gBAAA,CAAAe,CACF,CACF,CAEA,SAASN,CAAAA,CAAaS,CAAAA,CAAiBV,EAA+C,CACpF,GAAIU,GAAM,KAAA,GAAUrB,CAAAA,CAClB,MAAM,IAAIsB,mBAAAA,CAAS,8CAA8C,CAAA,CAEnE,GAAID,EAAK,aAAA,GAAkB,CAAA,EAAKV,GAAS,gBAAA,GAAqB,aAAA,CAC5D,MAAM,IAAIW,mBAAAA,CAAS,2BAA2BD,CAAAA,CAAK,aAAa,gBAAgB,CAEpF","file":"worker.cjs","sourcesContent":["// aiecsjs/worker — SharedArrayBuffer helpers (experimental, snapshot-copy).\n//\n// Note: 0.x implements SAB as a transferable snapshot pattern rather than true\n// shared-memory aliasing. The world is serialized into the SAB, and the worker\n// reconstructs a fresh world from those bytes via adoptSnapshot/attachWorld.\n// True shared-column memory is targeted for a future stable release.\n// The API matches the documented contract and survives postMessage cleanly.\n//\n// EntityRef is in-memory only — not preserved across worker boundaries.\n// Generation counters reset on adoptSnapshot/attachWorld. Pass `EntityRef.id`\n// (the packed EntityId) across the worker boundary only if you understand that\n// the generation portion will be stale after a round-trip snapshot.\n\nimport { EcsError } from './internal/errors.js'\nimport type {\n  DeserializeOptions,\n  TransferableSnapshot,\n  World,\n  WorldMeta,\n  WorldState,\n} from './internal/types.js'\nimport { destroyWorld, getWorldState, isWorldRegistered } from './internal/world.js'\nimport { deserializeWorld, serializeWorld } from './serialize.js'\nimport { VERSION } from './version.js'\n\nconst MAGIC = 0x41494543 // 'AIEC' little-endian as uint32\n\nexport function transferableSnapshot(world: World): TransferableSnapshot {\n  const state = getWorldState(world)\n  const bytes = serializeWorld(world)\n  // Fallback: a plain ArrayBuffer where SharedArrayBuffer is unavailable (no\n  // cross-origin isolation). TransferableSnapshot.buffer is typed\n  // `SharedArrayBuffer | ArrayBuffer`, so the type tells the truth instead of\n  // pretending the fallback is a SAB.\n  const buffer =\n    typeof SharedArrayBuffer === 'undefined'\n      ? new ArrayBuffer(bytes.byteLength)\n      : new SharedArrayBuffer(bytes.byteLength)\n  new Uint8Array(buffer).set(bytes)\n  return { buffer, meta: buildMeta(state) }\n}\n\n/**\n * Adopt a snapshot previously produced by `transferableSnapshot`.\n *\n * `options` are the `deserializeWorld` options: component resolution by key,\n * `onUnknownComponent`, and `onUnknownVersion` (which also governs the meta's\n * format version).\n *\n * SECURITY: same trust expectation as `attachWorld` — the sender of the\n * `TransferableSnapshot` (typically a Web Worker) must be trusted. The\n * function runs `validateMeta` and `deserializeWorld`, which enforce magic\n * + format version + length bounds on the binary header; but the inner\n * JSON payload, once decoded, is fed to `addComponent` and reaches AoS\n * components. For untrusted senders, use `aibridgejs` + `toJSON(world)` at\n * the application boundary instead.\n */\nexport function adoptSnapshot(snap: TransferableSnapshot, options?: DeserializeOptions): World {\n  validateMeta(snap?.meta, options)\n  return deserializeWorld(new Uint8Array(snap.buffer), options)\n}\n\n/**\n * Adopt a SharedArrayBuffer-backed snapshot produced by `transferableSnapshot`.\n *\n * `options` takes the `deserializeWorld` options plus `readOnly`, which makes\n * every mutator (including `resetWorld`) throw `EcsError` on the result.\n *\n * SECURITY: the SAB sender must be trusted. `attachWorld` performs the same\n * magic + version + length-bounds checks as `deserializeWorld`, but the JSON\n * payload itself is deserialised into AoS components via `addComponent`. If\n * the sender is untrusted (e.g. a third-party Web Worker that you do not\n * audit), prefer the higher-level `aibridgejs` channel + `toJSON(world)`\n * pattern, which lets you validate the shape at the application boundary\n * before constructing entities.\n */\nexport function attachWorld(\n  buffer: SharedArrayBuffer | ArrayBuffer,\n  options?: DeserializeOptions & { readOnly?: boolean },\n): World {\n  const world = deserializeWorld(new Uint8Array(buffer), options)\n  if (options?.readOnly) getWorldState(world).readOnly = true\n  return world\n}\n\nexport function detachWorld(world: World): void {\n  if (isWorldRegistered(world.id)) {\n    destroyWorld(world)\n  }\n}\n\nfunction buildMeta(state: WorldState): WorldMeta {\n  const componentSchemas: WorldMeta['componentSchemas'] = []\n  for (const info of state.componentInfoByBit) {\n    if (!info) continue\n    componentSchemas.push({ id: info.id, kind: info.kind, schema: info.schema })\n  }\n  return {\n    magic: MAGIC,\n    formatVersion: 2,\n    aiecsjsVersion: VERSION,\n    indexBits: state.options.indexBits,\n    generationBits: state.options.generationBits,\n    maxComponents: state.options.maxComponents,\n    maskWordCount: state.options.maskWordCount,\n    capacity: state.capacity,\n    componentSchemas,\n  }\n}\n\nfunction validateMeta(meta: WorldMeta, options: DeserializeOptions | undefined): void {\n  if (meta?.magic !== MAGIC) {\n    throw new EcsError('aiecsjs: invalid snapshot meta (wrong magic)')\n  }\n  if (meta.formatVersion !== 2 && options?.onUnknownVersion !== 'best-effort') {\n    throw new EcsError(`aiecsjs: format version ${meta.formatVersion} not supported`)\n  }\n}\n"]}

package/dist/worker.d.cts

@@ -1,9 +1,13 @@
-import { m as TransferableSnapshot, W as World } from './types-BeVLA7xG.cjs';
+import { m as TransferableSnapshot, e as DeserializeOptions, W as World } from './types-C6TkQ7HW.cjs';
 
 declare function transferableSnapshot(world: World): TransferableSnapshot;
 /**
  * Adopt a snapshot previously produced by `transferableSnapshot`.
  *
+ * `options` are the `deserializeWorld` options: component resolution by key,
+ * `onUnknownComponent`, and `onUnknownVersion` (which also governs the meta's
+ * format version).
+ *
  * SECURITY: same trust expectation as `attachWorld` — the sender of the
  * `TransferableSnapshot` (typically a Web Worker) must be trusted. The
  * function runs `validateMeta` and `deserializeWorld`, which enforce magic
@@ -12,10 +16,13 @@ declare function transferableSnapshot(world: World): TransferableSnapshot;
  * components. For untrusted senders, use `aibridgejs` + `toJSON(world)` at
  * the application boundary instead.
  */
-declare function adoptSnapshot(snap: TransferableSnapshot): World;
+declare function adoptSnapshot(snap: TransferableSnapshot, options?: DeserializeOptions): World;
 /**
  * Adopt a SharedArrayBuffer-backed snapshot produced by `transferableSnapshot`.
  *
+ * `options` takes the `deserializeWorld` options plus `readOnly`, which makes
+ * every mutator (including `resetWorld`) throw `EcsError` on the result.
+ *
  * SECURITY: the SAB sender must be trusted. `attachWorld` performs the same
  * magic + version + length-bounds checks as `deserializeWorld`, but the JSON
  * payload itself is deserialised into AoS components via `addComponent`. If
@@ -24,7 +31,7 @@ declare function adoptSnapshot(snap: TransferableSnapshot): World;
  * pattern, which lets you validate the shape at the application boundary
  * before constructing entities.
  */
-declare function attachWorld(buffer: SharedArrayBuffer | ArrayBuffer, options?: {
+declare function attachWorld(buffer: SharedArrayBuffer | ArrayBuffer, options?: DeserializeOptions & {
     readOnly?: boolean;
 }): World;
 declare function detachWorld(world: World): void;

package/dist/worker.d.ts

@@ -1,9 +1,13 @@
-import { m as TransferableSnapshot, W as World } from './types-BeVLA7xG.js';
+import { m as TransferableSnapshot, e as DeserializeOptions, W as World } from './types-C6TkQ7HW.js';
 
 declare function transferableSnapshot(world: World): TransferableSnapshot;
 /**
  * Adopt a snapshot previously produced by `transferableSnapshot`.
  *
+ * `options` are the `deserializeWorld` options: component resolution by key,
+ * `onUnknownComponent`, and `onUnknownVersion` (which also governs the meta's
+ * format version).
+ *
  * SECURITY: same trust expectation as `attachWorld` — the sender of the
  * `TransferableSnapshot` (typically a Web Worker) must be trusted. The
  * function runs `validateMeta` and `deserializeWorld`, which enforce magic
@@ -12,10 +16,13 @@ declare function transferableSnapshot(world: World): TransferableSnapshot;
  * components. For untrusted senders, use `aibridgejs` + `toJSON(world)` at
  * the application boundary instead.
  */
-declare function adoptSnapshot(snap: TransferableSnapshot): World;
+declare function adoptSnapshot(snap: TransferableSnapshot, options?: DeserializeOptions): World;
 /**
  * Adopt a SharedArrayBuffer-backed snapshot produced by `transferableSnapshot`.
  *
+ * `options` takes the `deserializeWorld` options plus `readOnly`, which makes
+ * every mutator (including `resetWorld`) throw `EcsError` on the result.
+ *
  * SECURITY: the SAB sender must be trusted. `attachWorld` performs the same
  * magic + version + length-bounds checks as `deserializeWorld`, but the JSON
  * payload itself is deserialised into AoS components via `addComponent`. If
@@ -24,7 +31,7 @@ declare function adoptSnapshot(snap: TransferableSnapshot): World;
  * pattern, which lets you validate the shape at the application boundary
  * before constructing entities.
  */
-declare function attachWorld(buffer: SharedArrayBuffer | ArrayBuffer, options?: {
+declare function attachWorld(buffer: SharedArrayBuffer | ArrayBuffer, options?: DeserializeOptions & {
     readOnly?: boolean;
 }): World;
 declare function detachWorld(world: World): void;

package/dist/worker.js

@@ -1,2 +1,2 @@
-import {a,b as b$1}from'./chunk-ZZBNE7C5.js';import {j,k,m as m$1,a as a$1}from'./chunk-OBMQME2P.js';var l=1095320899;function W(r){let e=j(r),o=a(r);if(typeof SharedArrayBuffer>"u"){let n=new ArrayBuffer(o.byteLength);return new Uint8Array(n).set(o),{buffer:n,meta:p(e)}}let t=new SharedArrayBuffer(o.byteLength);return new Uint8Array(t).set(o),{buffer:t,meta:p(e)}}function b(r){m(r.meta);let e=new Uint8Array(r.buffer);return b$1(e)}function S(r,e){let o=new Uint8Array(r),t=b$1(o);if(e?.readOnly){let n=j(t);n.readOnly=true;}return t}function B(r){k(r.id)&&m$1(r);}function p(r){let e=[];for(let o of r.componentInfoByBit)o&&e.push({id:o.id,kind:o.kind,schema:o.schema});return {magic:l,formatVersion:1,aiecsjsVersion:a$1,indexBits:r.options.indexBits,generationBits:r.options.generationBits,maxComponents:r.options.maxComponents,maskWordCount:r.options.maskWordCount,capacity:r.capacity,componentSchemas:e}}function m(r){if(r.magic!==l)throw new Error("aiecsjs: invalid snapshot meta (wrong magic)");if(r.formatVersion!==1)throw new Error(`aiecsjs: unsupported snapshot format version ${r.formatVersion}`)}export{b as adoptSnapshot,S as attachWorld,B as detachWorld,W as transferableSnapshot};//# sourceMappingURL=worker.js.map
+import {a,b as b$1}from'./chunk-GJ6U2TIU.js';import {i,k,m as m$1,a as a$1,f}from'./chunk-27JX7WHY.js';var c=1095320899;function S(e){let r=i(e),o=a(e),a$1=typeof SharedArrayBuffer>"u"?new ArrayBuffer(o.byteLength):new SharedArrayBuffer(o.byteLength);return new Uint8Array(a$1).set(o),{buffer:a$1,meta:p(r)}}function b(e,r){return m(e?.meta,r),b$1(new Uint8Array(e.buffer),r)}function B(e,r){let o=b$1(new Uint8Array(e),r);return r?.readOnly&&(i(o).readOnly=true),o}function g(e){k(e.id)&&m$1(e);}function p(e){let r=[];for(let o of e.componentInfoByBit)o&&r.push({id:o.id,kind:o.kind,schema:o.schema});return {magic:c,formatVersion:2,aiecsjsVersion:a$1,indexBits:e.options.indexBits,generationBits:e.options.generationBits,maxComponents:e.options.maxComponents,maskWordCount:e.options.maskWordCount,capacity:e.capacity,componentSchemas:r}}function m(e,r){if(e?.magic!==c)throw new f("aiecsjs: invalid snapshot meta (wrong magic)");if(e.formatVersion!==2&&r?.onUnknownVersion!=="best-effort")throw new f(`aiecsjs: format version ${e.formatVersion} not supported`)}export{b as adoptSnapshot,B as attachWorld,g as detachWorld,S as transferableSnapshot};//# sourceMappingURL=worker.js.map
 //# sourceMappingURL=worker.js.map

package/dist/worker.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/worker.ts"],"names":["MAGIC","transferableSnapshot","world","state","getWorldState","bytes","serializeWorld","ab","buildMeta","sab","adoptSnapshot","snap","validateMeta","deserializeWorld","attachWorld","buffer","options","detachWorld","isWorldRegistered","destroyWorld","componentSchemas","info","VERSION","meta"],"mappings":"qGAkBA,IAAMA,CAAAA,CAAQ,WAEP,SAASC,CAAAA,CAAqBC,EAAoC,CACvE,IAAMC,CAAAA,CAAQC,CAAAA,CAAcF,CAAK,CAAA,CAC3BG,EAAQC,CAAAA,CAAeJ,CAAK,EAElC,GAAI,OAAO,kBAAsB,GAAA,CAAa,CAI5C,IAAMK,CAAAA,CAAK,IAAI,WAAA,CAAYF,EAAM,UAAU,CAAA,CAC3C,WAAI,UAAA,CAAWE,CAAE,EAAE,GAAA,CAAIF,CAAK,CAAA,CACrB,CACL,MAAA,CAAQE,CAAAA,CACR,KAAMC,CAAAA,CAAUL,CAAK,CACvB,CACF,CAEA,IAAMM,EAAM,IAAI,iBAAA,CAAkBJ,CAAAA,CAAM,UAAU,CAAA,CAClD,OAAA,IAAI,WAAWI,CAAG,CAAA,CAAE,IAAIJ,CAAK,CAAA,CACtB,CAAE,MAAA,CAAQI,CAAAA,CAAK,IAAA,CAAMD,CAAAA,CAAUL,CAAK,CAAE,CAC/C,CAaO,SAASO,CAAAA,CAAcC,CAAAA,CAAmC,CAC/DC,CAAAA,CAAaD,EAAK,IAAI,CAAA,CACtB,IAAMN,CAAAA,CAAQ,IAAI,UAAA,CAAWM,EAAK,MAAM,CAAA,CACxC,OAAOE,GAAAA,CAAiBR,CAAK,CAC/B,CAaO,SAASS,CAAAA,CACdC,CAAAA,CACAC,CAAAA,CACO,CACP,IAAMX,CAAAA,CAAQ,IAAI,UAAA,CAAWU,CAAM,CAAA,CAC7Bb,CAAAA,CAAQW,IAAiBR,CAAK,CAAA,CACpC,GAAIW,CAAAA,EAAS,QAAA,CAAU,CACrB,IAAMb,CAAAA,CAAQC,CAAAA,CAAcF,CAAK,CAAA,CACjCC,CAAAA,CAAM,SAAW,KACnB,CACA,OAAOD,CACT,CAEO,SAASe,EAAYf,CAAAA,CAAoB,CAC1CgB,CAAAA,CAAkBhB,CAAAA,CAAM,EAAE,CAAA,EAC5BiB,IAAajB,CAAK,EAEtB,CAEA,SAASM,CAAAA,CAAUL,CAAAA,CAA8B,CAC/C,IAAMiB,CAAAA,CAAkD,EAAC,CACzD,IAAA,IAAWC,KAAQlB,CAAAA,CAAM,kBAAA,CAClBkB,CAAAA,EACLD,CAAAA,CAAiB,IAAA,CAAK,CAAE,GAAIC,CAAAA,CAAK,EAAA,CAAI,IAAA,CAAMA,CAAAA,CAAK,IAAA,CAAM,MAAA,CAAQA,EAAK,MAAO,CAAC,CAAA,CAE7E,OAAO,CACL,KAAA,CAAOrB,EACP,aAAA,CAAe,CAAA,CACf,eAAgBsB,GAAAA,CAChB,SAAA,CAAWnB,EAAM,OAAA,CAAQ,SAAA,CACzB,cAAA,CAAgBA,CAAAA,CAAM,OAAA,CAAQ,cAAA,CAC9B,cAAeA,CAAAA,CAAM,OAAA,CAAQ,aAAA,CAC7B,aAAA,CAAeA,CAAAA,CAAM,OAAA,CAAQ,cAC7B,QAAA,CAAUA,CAAAA,CAAM,QAAA,CAChB,gBAAA,CAAAiB,CACF,CACF,CAEA,SAASR,CAAAA,CAAaW,EAAuB,CAC3C,GAAIA,EAAK,KAAA,GAAUvB,CAAAA,CACjB,MAAM,IAAI,KAAA,CAAM,8CAA8C,EAEhE,GAAIuB,CAAAA,CAAK,aAAA,GAAkB,CAAA,CACzB,MAAM,IAAI,MAAM,CAAA,6CAAA,EAAgDA,CAAAA,CAAK,aAAa,CAAA,CAAE,CAExF","file":"worker.js","sourcesContent":["// aiecsjs/worker — SharedArrayBuffer helpers (experimental, snapshot-copy).\n//\n// Note: 0.x implements SAB as a transferable snapshot pattern rather than true\n// shared-memory aliasing. The world is serialized into the SAB, and the worker\n// reconstructs a fresh world from those bytes via adoptSnapshot/attachWorld.\n// True shared-column memory is targeted for a future stable release.\n// The API matches the documented contract and survives postMessage cleanly.\n//\n// EntityRef is in-memory only — not preserved across worker boundaries.\n// Generation counters reset on adoptSnapshot/attachWorld. Pass `EntityRef.id`\n// (the packed EntityId) across the worker boundary only if you understand that\n// the generation portion will be stale after a round-trip snapshot.\n\nimport type { TransferableSnapshot, World, WorldMeta, WorldState } from './internal/types.js'\nimport { destroyWorld, getWorldState, isWorldRegistered } from './internal/world.js'\nimport { deserializeWorld, serializeWorld } from './serialize.js'\nimport { VERSION } from './version.js'\n\nconst MAGIC = 0x41494543 // 'AIEC' little-endian as uint32\n\nexport function transferableSnapshot(world: World): TransferableSnapshot {\n  const state = getWorldState(world)\n  const bytes = serializeWorld(world)\n\n  if (typeof SharedArrayBuffer === 'undefined') {\n    // Fallback: a plain ArrayBuffer. TransferableSnapshot.buffer is typed\n    // `SharedArrayBuffer | ArrayBuffer`, so this needs no cast — the type tells\n    // the truth instead of pretending the fallback is a SAB.\n    const ab = new ArrayBuffer(bytes.byteLength)\n    new Uint8Array(ab).set(bytes)\n    return {\n      buffer: ab,\n      meta: buildMeta(state),\n    }\n  }\n\n  const sab = new SharedArrayBuffer(bytes.byteLength)\n  new Uint8Array(sab).set(bytes)\n  return { buffer: sab, meta: buildMeta(state) }\n}\n\n/**\n * Adopt a snapshot previously produced by `transferableSnapshot`.\n *\n * SECURITY: same trust expectation as `attachWorld` — the sender of the\n * `TransferableSnapshot` (typically a Web Worker) must be trusted. The\n * function runs `validateMeta` and `deserializeWorld`, which enforce magic\n * + format version + length bounds on the binary header; but the inner\n * JSON payload, once decoded, is fed to `addComponent` and reaches AoS\n * components. For untrusted senders, use `aibridgejs` + `toJSON(world)` at\n * the application boundary instead.\n */\nexport function adoptSnapshot(snap: TransferableSnapshot): World {\n  validateMeta(snap.meta)\n  const bytes = new Uint8Array(snap.buffer)\n  return deserializeWorld(bytes)\n}\n\n/**\n * Adopt a SharedArrayBuffer-backed snapshot produced by `transferableSnapshot`.\n *\n * SECURITY: the SAB sender must be trusted. `attachWorld` performs the same\n * magic + version + length-bounds checks as `deserializeWorld`, but the JSON\n * payload itself is deserialised into AoS components via `addComponent`. If\n * the sender is untrusted (e.g. a third-party Web Worker that you do not\n * audit), prefer the higher-level `aibridgejs` channel + `toJSON(world)`\n * pattern, which lets you validate the shape at the application boundary\n * before constructing entities.\n */\nexport function attachWorld(\n  buffer: SharedArrayBuffer | ArrayBuffer,\n  options?: { readOnly?: boolean },\n): World {\n  const bytes = new Uint8Array(buffer)\n  const world = deserializeWorld(bytes)\n  if (options?.readOnly) {\n    const state = getWorldState(world)\n    state.readOnly = true\n  }\n  return world\n}\n\nexport function detachWorld(world: World): void {\n  if (isWorldRegistered(world.id)) {\n    destroyWorld(world)\n  }\n}\n\nfunction buildMeta(state: WorldState): WorldMeta {\n  const componentSchemas: WorldMeta['componentSchemas'] = []\n  for (const info of state.componentInfoByBit) {\n    if (!info) continue\n    componentSchemas.push({ id: info.id, kind: info.kind, schema: info.schema })\n  }\n  return {\n    magic: MAGIC,\n    formatVersion: 1,\n    aiecsjsVersion: VERSION,\n    indexBits: state.options.indexBits,\n    generationBits: state.options.generationBits,\n    maxComponents: state.options.maxComponents,\n    maskWordCount: state.options.maskWordCount,\n    capacity: state.capacity,\n    componentSchemas,\n  }\n}\n\nfunction validateMeta(meta: WorldMeta): void {\n  if (meta.magic !== MAGIC) {\n    throw new Error('aiecsjs: invalid snapshot meta (wrong magic)')\n  }\n  if (meta.formatVersion !== 1) {\n    throw new Error(`aiecsjs: unsupported snapshot format version ${meta.formatVersion}`)\n  }\n}\n"]}
+{"version":3,"sources":["../src/worker.ts"],"names":["MAGIC","transferableSnapshot","world","state","getWorldState","bytes","serializeWorld","buffer","buildMeta","adoptSnapshot","snap","options","validateMeta","deserializeWorld","attachWorld","detachWorld","isWorldRegistered","destroyWorld","componentSchemas","info","VERSION","meta","EcsError"],"mappings":"uGAyBA,IAAMA,EAAQ,UAAA,CAEP,SAASC,EAAqBC,CAAAA,CAAoC,CACvE,IAAMC,CAAAA,CAAQC,CAAAA,CAAcF,CAAK,CAAA,CAC3BG,CAAAA,CAAQC,EAAeJ,CAAK,CAAA,CAK5BK,IACJ,OAAO,iBAAA,CAAsB,IACzB,IAAI,WAAA,CAAYF,EAAM,UAAU,CAAA,CAChC,IAAI,iBAAA,CAAkBA,CAAAA,CAAM,UAAU,CAAA,CAC5C,OAAA,IAAI,WAAWE,GAAM,CAAA,CAAE,IAAIF,CAAK,CAAA,CACzB,CAAE,MAAA,CAAAE,GAAAA,CAAQ,KAAMC,CAAAA,CAAUL,CAAK,CAAE,CAC1C,CAiBO,SAASM,CAAAA,CAAcC,CAAAA,CAA4BC,EAAqC,CAC7F,OAAAC,EAAaF,CAAAA,EAAM,IAAA,CAAMC,CAAO,CAAA,CACzBE,GAAAA,CAAiB,IAAI,UAAA,CAAWH,CAAAA,CAAK,MAAM,CAAA,CAAGC,CAAO,CAC9D,CAgBO,SAASG,EACdP,CAAAA,CACAI,CAAAA,CACO,CACP,IAAMT,CAAAA,CAAQW,IAAiB,IAAI,UAAA,CAAWN,CAAM,CAAA,CAAGI,CAAO,EAC9D,OAAIA,CAAAA,EAAS,WAAUP,CAAAA,CAAcF,CAAK,EAAE,QAAA,CAAW,IAAA,CAAA,CAChDA,CACT,CAEO,SAASa,EAAYb,CAAAA,CAAoB,CAC1Cc,EAAkBd,CAAAA,CAAM,EAAE,GAC5Be,GAAAA,CAAaf,CAAK,EAEtB,CAEA,SAASM,EAAUL,CAAAA,CAA8B,CAC/C,IAAMe,CAAAA,CAAkD,GACxD,IAAA,IAAWC,CAAAA,IAAQhB,EAAM,kBAAA,CAClBgB,CAAAA,EACLD,EAAiB,IAAA,CAAK,CAAE,GAAIC,CAAAA,CAAK,EAAA,CAAI,KAAMA,CAAAA,CAAK,IAAA,CAAM,OAAQA,CAAAA,CAAK,MAAO,CAAC,CAAA,CAE7E,OAAO,CACL,KAAA,CAAOnB,CAAAA,CACP,cAAe,CAAA,CACf,cAAA,CAAgBoB,IAChB,SAAA,CAAWjB,CAAAA,CAAM,QAAQ,SAAA,CACzB,cAAA,CAAgBA,EAAM,OAAA,CAAQ,cAAA,CAC9B,cAAeA,CAAAA,CAAM,OAAA,CAAQ,cAC7B,aAAA,CAAeA,CAAAA,CAAM,QAAQ,aAAA,CAC7B,QAAA,CAAUA,EAAM,QAAA,CAChB,gBAAA,CAAAe,CACF,CACF,CAEA,SAASN,CAAAA,CAAaS,CAAAA,CAAiBV,EAA+C,CACpF,GAAIU,GAAM,KAAA,GAAUrB,CAAAA,CAClB,MAAM,IAAIsB,CAAAA,CAAS,8CAA8C,CAAA,CAEnE,GAAID,EAAK,aAAA,GAAkB,CAAA,EAAKV,GAAS,gBAAA,GAAqB,aAAA,CAC5D,MAAM,IAAIW,CAAAA,CAAS,2BAA2BD,CAAAA,CAAK,aAAa,gBAAgB,CAEpF","file":"worker.js","sourcesContent":["// aiecsjs/worker — SharedArrayBuffer helpers (experimental, snapshot-copy).\n//\n// Note: 0.x implements SAB as a transferable snapshot pattern rather than true\n// shared-memory aliasing. The world is serialized into the SAB, and the worker\n// reconstructs a fresh world from those bytes via adoptSnapshot/attachWorld.\n// True shared-column memory is targeted for a future stable release.\n// The API matches the documented contract and survives postMessage cleanly.\n//\n// EntityRef is in-memory only — not preserved across worker boundaries.\n// Generation counters reset on adoptSnapshot/attachWorld. Pass `EntityRef.id`\n// (the packed EntityId) across the worker boundary only if you understand that\n// the generation portion will be stale after a round-trip snapshot.\n\nimport { EcsError } from './internal/errors.js'\nimport type {\n  DeserializeOptions,\n  TransferableSnapshot,\n  World,\n  WorldMeta,\n  WorldState,\n} from './internal/types.js'\nimport { destroyWorld, getWorldState, isWorldRegistered } from './internal/world.js'\nimport { deserializeWorld, serializeWorld } from './serialize.js'\nimport { VERSION } from './version.js'\n\nconst MAGIC = 0x41494543 // 'AIEC' little-endian as uint32\n\nexport function transferableSnapshot(world: World): TransferableSnapshot {\n  const state = getWorldState(world)\n  const bytes = serializeWorld(world)\n  // Fallback: a plain ArrayBuffer where SharedArrayBuffer is unavailable (no\n  // cross-origin isolation). TransferableSnapshot.buffer is typed\n  // `SharedArrayBuffer | ArrayBuffer`, so the type tells the truth instead of\n  // pretending the fallback is a SAB.\n  const buffer =\n    typeof SharedArrayBuffer === 'undefined'\n      ? new ArrayBuffer(bytes.byteLength)\n      : new SharedArrayBuffer(bytes.byteLength)\n  new Uint8Array(buffer).set(bytes)\n  return { buffer, meta: buildMeta(state) }\n}\n\n/**\n * Adopt a snapshot previously produced by `transferableSnapshot`.\n *\n * `options` are the `deserializeWorld` options: component resolution by key,\n * `onUnknownComponent`, and `onUnknownVersion` (which also governs the meta's\n * format version).\n *\n * SECURITY: same trust expectation as `attachWorld` — the sender of the\n * `TransferableSnapshot` (typically a Web Worker) must be trusted. The\n * function runs `validateMeta` and `deserializeWorld`, which enforce magic\n * + format version + length bounds on the binary header; but the inner\n * JSON payload, once decoded, is fed to `addComponent` and reaches AoS\n * components. For untrusted senders, use `aibridgejs` + `toJSON(world)` at\n * the application boundary instead.\n */\nexport function adoptSnapshot(snap: TransferableSnapshot, options?: DeserializeOptions): World {\n  validateMeta(snap?.meta, options)\n  return deserializeWorld(new Uint8Array(snap.buffer), options)\n}\n\n/**\n * Adopt a SharedArrayBuffer-backed snapshot produced by `transferableSnapshot`.\n *\n * `options` takes the `deserializeWorld` options plus `readOnly`, which makes\n * every mutator (including `resetWorld`) throw `EcsError` on the result.\n *\n * SECURITY: the SAB sender must be trusted. `attachWorld` performs the same\n * magic + version + length-bounds checks as `deserializeWorld`, but the JSON\n * payload itself is deserialised into AoS components via `addComponent`. If\n * the sender is untrusted (e.g. a third-party Web Worker that you do not\n * audit), prefer the higher-level `aibridgejs` channel + `toJSON(world)`\n * pattern, which lets you validate the shape at the application boundary\n * before constructing entities.\n */\nexport function attachWorld(\n  buffer: SharedArrayBuffer | ArrayBuffer,\n  options?: DeserializeOptions & { readOnly?: boolean },\n): World {\n  const world = deserializeWorld(new Uint8Array(buffer), options)\n  if (options?.readOnly) getWorldState(world).readOnly = true\n  return world\n}\n\nexport function detachWorld(world: World): void {\n  if (isWorldRegistered(world.id)) {\n    destroyWorld(world)\n  }\n}\n\nfunction buildMeta(state: WorldState): WorldMeta {\n  const componentSchemas: WorldMeta['componentSchemas'] = []\n  for (const info of state.componentInfoByBit) {\n    if (!info) continue\n    componentSchemas.push({ id: info.id, kind: info.kind, schema: info.schema })\n  }\n  return {\n    magic: MAGIC,\n    formatVersion: 2,\n    aiecsjsVersion: VERSION,\n    indexBits: state.options.indexBits,\n    generationBits: state.options.generationBits,\n    maxComponents: state.options.maxComponents,\n    maskWordCount: state.options.maskWordCount,\n    capacity: state.capacity,\n    componentSchemas,\n  }\n}\n\nfunction validateMeta(meta: WorldMeta, options: DeserializeOptions | undefined): void {\n  if (meta?.magic !== MAGIC) {\n    throw new EcsError('aiecsjs: invalid snapshot meta (wrong magic)')\n  }\n  if (meta.formatVersion !== 2 && options?.onUnknownVersion !== 'best-effort') {\n    throw new EcsError(`aiecsjs: format version ${meta.formatVersion} not supported`)\n  }\n}\n"]}