aiecsjs 0.5.9 → 0.6.0

package/api.json

@@ -1,8 +1,8 @@
 {
   "$schema": "https://islumina.github.io/aiecsjs/api-schema.json",
   "name": "aiecsjs",
-  "version": "0.5.0",
-  "generated": "2026-05-29",
+  "version": "0.6.0",
+  "generated": "2026-09-29",
   "stability": "experimental",
   "license": "MIT",
   "repository": "https://github.com/islumina/aiecsjs",
@@ -119,6 +119,12 @@
         "type": "World",
         "description": "Opaque world handle passed to all other API calls."
       },
+      "throws": [
+        {
+          "type": "EcsError",
+          "when": "initialCapacity, maxEntities, indexBits or generationBits is not an integer (checked first), indexBits is outside [1, 24], generationBits is outside [0, 16], or their sum exceeds 32."
+        }
+      ],
       "examples": [
         { "title": "Minimal world", "code": "const world = createWorld()" },
         {
@@ -179,11 +185,12 @@
       "stability": "stable",
       "deprecated": false,
       "signature": "function resetWorld(world: World): void",
-      "summary": "Wipe entities and components but keep the world allocated. Useful for hot module reload.",
+      "summary": "Wipe entities, components and relation edges but keep the world allocated (capacity and registered components). Useful for hot module reload.",
       "params": [
         { "name": "world", "type": "World", "optional": false, "description": "World to reset." }
       ],
       "returns": { "type": "void", "description": "" },
+      "throws": [{ "type": "EcsError", "when": "world is read-only (worker-attached, since 0.6.0)." }],
       "examples": [
         {
           "title": "Reset for HMR",
@@ -242,7 +249,9 @@
         "type": "EntityId",
         "description": "Branded number containing index + generation."
       },
-      "throws": [{ "type": "Error", "when": "world has reached maxEntities cap." }],
+      "throws": [
+        { "type": "EcsError", "when": "world has reached its maxEntities cap, or is read-only." }
+      ],
       "examples": [{ "title": "Spawn one entity", "code": "const e = createEntity(world)" }],
       "seeAlso": ["destroyEntity", "entityExists", "packEntity"]
     },
@@ -254,7 +263,7 @@
       "stability": "stable",
       "deprecated": false,
       "signature": "function destroyEntity(world: World, eid: EntityId): void",
-      "summary": "Remove all components, bump generation, free slot.",
+      "summary": "Remove all components and relation edges, bump generation, free slot. No-op for a dead entity.",
       "params": [
         { "name": "world", "type": "World", "optional": false, "description": "Target world." },
         {
@@ -265,6 +274,7 @@
         }
       ],
       "returns": { "type": "void", "description": "" },
+      "throws": [{ "type": "EcsError", "when": "world is read-only." }],
       "examples": [
         {
           "title": "Cleanup dead entity",
@@ -364,20 +374,30 @@
       "since": "0.1.0",
       "stability": "stable",
       "deprecated": false,
-      "signature": "function defineComponent<S extends SoASchema>(schema: S): SoAComponent<S>",
-      "summary": "Declare a Structure-of-Arrays component. Each field becomes a TypedArray column indexed by entity ID.",
+      "signature": "function defineComponent<S extends SoASchema>(schema: S, options?: { key?: string }): SoAComponent<S>",
+      "summary": "Declare a Structure-of-Arrays component. Each field becomes a TypedArray column indexed by entity slot index. `options.key` (since 0.6.0) is the stable identity snapshots use to match data to this component.",
       "params": [
         {
           "name": "schema",
           "type": "SoASchema",
           "optional": false,
           "description": "Map of field name → field type. Field type is a member of Types, or [type, vectorLength] for fixed-size vectors."
+        },
+        {
+          "name": "options",
+          "type": "{ key?: string }",
+          "optional": true,
+          "description": "Stable serialization key: a non-empty string, unique in the process. Snapshot loaders resolve keyed components by key, keyless ones by creation-order id."
         }
       ],
       "returns": {
         "type": "SoAComponent<S>",
         "description": "Component handle used in addComponent/getComponent/etc."
       },
+      "throws": [
+        { "type": "TypeError", "when": "a field declaration or field type is invalid." },
+        { "type": "EcsError", "when": "options.key is empty, not a string, or already defined." }
+      ],
       "examples": [
         {
           "title": "Position with two scalars",
@@ -386,6 +406,10 @@
         {
           "title": "Transform with vector field",
           "code": "const Transform = defineComponent({ pos: [Types.f32, 3], scale: Types.f32 })"
+        },
+        {
+          "title": "Keyed for snapshots",
+          "code": "const Position = defineComponent({ x: Types.f32, y: Types.f32 }, { key: 'position' })"
         }
       ],
       "seeAlso": ["defineTag", "defineObjectComponent", "Types", "addComponent"]
@@ -397,9 +421,16 @@
       "since": "0.1.0",
       "stability": "stable",
       "deprecated": false,
-      "signature": "function defineTag(): TagComponent",
-      "summary": "Declare a zero-byte tag component. No fields.",
-      "params": [],
+      "signature": "function defineTag(options?: { key?: string }): TagComponent",
+      "summary": "Declare a zero-byte tag component. No fields. `options.key` (since 0.6.0): see defineComponent.",
+      "params": [
+        {
+          "name": "options",
+          "type": "{ key?: string }",
+          "optional": true,
+          "description": "Stable serialization key; see defineComponent."
+        }
+      ],
       "returns": { "type": "TagComponent", "description": "Tag component handle." },
       "examples": [{ "title": "Player tag", "code": "const Player = defineTag()" }],
       "seeAlso": ["defineComponent"]
@@ -411,17 +442,29 @@
       "since": "0.1.0",
       "stability": "stable",
       "deprecated": false,
-      "signature": "function defineObjectComponent<T>(factory?: () => T): AoSComponent<T>",
+      "signature": "function defineObjectComponent<T>(factory?: () => T, options?: { key?: string }): AoSComponent<T>",
       "summary": "Declare an Array-of-Structures component. Each entity stores a separate JS object. Main-thread only.",
       "params": [
         {
           "name": "factory",
           "type": "() => T",
           "optional": true,
-          "description": "Default value factory invoked ONCE at definition time. Mutate per-entity instances via setComponent/getComponent."
+          "description": "Called once per entity, when the component is first added, to create that entity's instance (default `() => ({})`). Must return a value other than null or undefined. Initial data is copied onto the instance."
+        },
+        {
+          "name": "options",
+          "type": "{ key?: string }",
+          "optional": true,
+          "description": "Stable serialization key; see defineComponent."
         }
       ],
       "returns": { "type": "AoSComponent<T>", "description": "AoS component handle." },
+      "throws": [
+        {
+          "type": "EcsError",
+          "when": "factory is given but not a function, or options.key is invalid or already defined."
+        }
+      ],
       "examples": [
         {
           "title": "Reference to a Three.js mesh",
@@ -462,8 +505,10 @@
       ],
       "returns": { "type": "void", "description": "" },
       "throws": [
-        { "type": "TypeError", "when": "component is not a ComponentLike." },
-        { "type": "Error", "when": "eid does not exist (dev mode only)." }
+        {
+          "type": "EcsError",
+          "when": "eid is not alive, the component is not registered, the world is read-only, or an AoS factory returns null/undefined (before the entity changes)."
+        }
       ],
       "examples": [
         {
@@ -577,6 +622,12 @@
         { "name": "value", "type": "V", "optional": false, "description": "New values." }
       ],
       "returns": { "type": "void", "description": "" },
+      "throws": [
+        {
+          "type": "EcsError",
+          "when": "eid is not alive, the component is not registered, or the world is read-only."
+        }
+      ],
       "examples": [
         { "title": "Set SoA", "code": "setComponent(world, e, Position, { x: 5, y: 10 })" }
       ],
@@ -623,7 +674,8 @@
         { "name": "world", "type": "World", "optional": false, "description": "Target world." },
         { "name": "query", "type": "Query", "optional": false, "description": "Query handle." }
       ],
-      "returns": { "type": "readonly EntityId[]", "description": "Frozen array of entity IDs." },
+      "returns": { "type": "Query", "description": "Cached query handle." },
+      "throws": [{ "type": "TypeError", "when": "a member is not a component handle." }],
       "examples": [],
       "seeAlso": ["forEachEntity", "iterQuery"]
     },
@@ -653,6 +705,10 @@
           "code": "forEachEntity(world, movers, (e, pos, vel) => { const i = getEntityIndex(e); pos.x[i] += vel.x[i]; pos.y[i] += vel.y[i] })"
         }
       ],
+      "throws": [
+        { "type": "TypeError", "when": "query is neither a Query nor a component array." },
+        { "type": "EcsError", "when": "fn is not a function (checked before a reactive buffer is drained)." }
+      ],
       "seeAlso": ["defineQuery", "runQuery", "forEachEntityIndexed", "iterQuery"]
     },
     {
@@ -681,6 +737,10 @@
           "code": "forEachEntityIndexed(world, movers, (e, i, pos, vel) => { pos.x[i] += vel.x[i]; pos.y[i] += vel.y[i] })"
         }
       ],
+      "throws": [
+        { "type": "TypeError", "when": "query is neither a Query nor a component array." },
+        { "type": "EcsError", "when": "fn is not a function (checked before a reactive buffer is drained)." }
+      ],
       "seeAlso": ["forEachEntity", "defineQuery", "runQuery", "iterQuery"]
     },
     {
@@ -710,11 +770,17 @@
       "stability": "stable",
       "deprecated": false,
       "signature": "function enterQuery(query: Query): Query",
-      "summary": "Reactive query that yields only entities newly matching this frame.",
+      "summary": "Reactive query that yields only entities newly matching since the last read. The buffer is unbounded until drained.",
       "params": [
-        { "name": "query", "type": "Query", "optional": false, "description": "Source query." }
+        {
+          "name": "query",
+          "type": "Query",
+          "optional": false,
+          "description": "Source query (a raw component array is accepted, as for runQuery)."
+        }
       ],
       "returns": { "type": "Query", "description": "Reactive query handle." },
+      "throws": [{ "type": "TypeError", "when": "query is neither a Query nor a component array." }],
       "examples": [
         { "title": "Mount-on-enter", "code": "const becameVisible = enterQuery(visibleQ)" }
       ],
@@ -728,11 +794,17 @@
       "stability": "stable",
       "deprecated": false,
       "signature": "function exitQuery(query: Query): Query",
-      "summary": "Reactive query that yields only entities that left the match this frame.",
+      "summary": "Reactive query that yields only entities that left the match since the last read. The buffer is unbounded until drained.",
       "params": [
-        { "name": "query", "type": "Query", "optional": false, "description": "Source query." }
+        {
+          "name": "query",
+          "type": "Query",
+          "optional": false,
+          "description": "Source query (a raw component array is accepted, as for runQuery)."
+        }
       ],
       "returns": { "type": "Query", "description": "Reactive query handle." },
+      "throws": [{ "type": "TypeError", "when": "query is neither a Query nor a component array." }],
       "examples": [],
       "seeAlso": ["enterQuery", "defineQuery"]
     },
@@ -776,6 +848,7 @@
         }
       ],
       "returns": { "type": "System<W, Ctx>", "description": "Composed system." },
+      "throws": [{ "type": "EcsError", "when": "a system is not a function (checked at composition)." }],
       "examples": [
         {
           "title": "Frame tick",
@@ -802,6 +875,16 @@
         }
       ],
       "returns": { "type": "{ start(), stop() }", "description": "Loop control handle." },
+      "throws": [
+        {
+          "type": "TypeError",
+          "when": "options is not an object, onUpdate is not a function, or onRender is set but not a function."
+        },
+        {
+          "type": "RangeError",
+          "when": "fixed is not a finite number > 0, or maxSubSteps is not a finite number >= 1."
+        }
+      ],
       "examples": [
         {
           "title": "60Hz loop",
@@ -869,6 +952,7 @@
         }
       ],
       "returns": { "type": "R", "description": "Whatever the callback returned." },
+      "throws": [{ "type": "EcsError", "when": "fn is not a function." }],
       "examples": [
         {
           "title": "Safe destroy in iter",
@@ -885,7 +969,7 @@
       "stability": "stable",
       "deprecated": false,
       "signature": "function observe(world: World, query: Query, event: 'add' | 'remove' | 'set', handler: (eid: EntityId) => void, opts?: ObserverOptions): () => void",
-      "summary": "General-purpose query observer. Returns a disposer. `opts.signal` (since 0.2.0) auto-unsubscribes when aborted.",
+      "summary": "General-purpose query observer: 'add' when an entity starts matching, 'remove' when it stops (including destroy), 'set' after setComponent writes an all/any component of a matching entity. Accepts a raw component array. Returns a disposer. `opts.signal` (since 0.2.0) auto-unsubscribes when aborted.",
       "params": [
         { "name": "world", "type": "World", "optional": false, "description": "Target world." },
         { "name": "query", "type": "Query", "optional": false, "description": "Query handle." },
@@ -909,6 +993,7 @@
         }
       ],
       "returns": { "type": "() => void", "description": "Disposer." },
+      "throws": [{ "type": "EcsError", "when": "handler is not a function." }],
       "examples": [],
       "seeAlso": ["onAdd", "onRemove", "onSet"]
     },
@@ -943,6 +1028,7 @@
         }
       ],
       "returns": { "type": "() => void", "description": "Disposer." },
+      "throws": [{ "type": "EcsError", "when": "handler is not a function." }],
       "examples": [],
       "seeAlso": ["onRemove", "onSet", "observe"]
     },
@@ -977,6 +1063,7 @@
         }
       ],
       "returns": { "type": "() => void", "description": "Disposer." },
+      "throws": [{ "type": "EcsError", "when": "handler is not a function." }],
       "examples": [],
       "seeAlso": ["onAdd", "onSet"]
     },
@@ -1006,6 +1093,7 @@
         }
       ],
       "returns": { "type": "() => void", "description": "Disposer." },
+      "throws": [{ "type": "EcsError", "when": "handler is not a function." }],
       "examples": [],
       "seeAlso": ["onAdd", "onRemove"]
     },
@@ -1017,7 +1105,7 @@
       "stability": "stable",
       "deprecated": false,
       "signature": "function serializeWorld(world: World, options?: SerializeOptions): Uint8Array",
-      "summary": "Produce a versioned binary snapshot of the world.",
+      "summary": "Produce a versioned binary snapshot of the world (format 2: magic, format version, VERSION, JSON body with the component table).",
       "params": [
         { "name": "world", "type": "World", "optional": false, "description": "Target world." },
         {
@@ -1051,11 +1139,16 @@
           "name": "options",
           "type": "DeserializeOptions",
           "optional": true,
-          "description": "Migration behaviour for unknown versions."
+          "description": "Same as fromJSON: components allowlist, onUnknownVersion (also checked against the binary header), onUnknownComponent."
         }
       ],
       "returns": { "type": "World", "description": "Restored world." },
-      "throws": [{ "type": "Error", "when": "version mismatch and onUnknownVersion is 'throw'." }],
+      "throws": [
+        {
+          "type": "EcsError",
+          "when": "the bytes are malformed, the format version is not 2 and onUnknownVersion is not 'best-effort', a component is undefined here and onUnknownComponent is not 'skip', or a component kind/SoA fields mismatch."
+        }
+      ],
       "examples": [],
       "seeAlso": ["serializeWorld"]
     },
@@ -1067,7 +1160,7 @@
       "stability": "stable",
       "deprecated": false,
       "signature": "function toJSON(world: World): WorldSnapshot",
-      "summary": "Produce a human-readable JSON snapshot. Slower than serializeWorld; inspectable in DevTools.",
+      "summary": "Produce a human-readable JSON snapshot (format 2: `formatVersion: 2`, a `components` table with id/key/kind/fields, and per-entity data). AoS data is deep-copied. Slower than serializeWorld; inspectable in DevTools.",
       "params": [
         { "name": "world", "type": "World", "optional": false, "description": "Target world." }
       ],
@@ -1082,17 +1175,29 @@
       "since": "0.1.0",
       "stability": "stable",
       "deprecated": false,
-      "signature": "function fromJSON(snapshot: WorldSnapshot): World",
-      "summary": "Restore from a JSON snapshot.",
+      "signature": "function fromJSON(snapshot: WorldSnapshot, options?: DeserializeOptions): World",
+      "summary": "Restore from a JSON snapshot. Every component is resolved (by key, by creation-order id when keyless) and checked for kind/SoA fields before the world is created. Entities get fresh ids in snapshot order.",
       "params": [
         {
           "name": "snapshot",
           "type": "WorldSnapshot",
           "optional": false,
           "description": "Snapshot from toJSON."
+        },
+        {
+          "name": "options",
+          "type": "DeserializeOptions",
+          "optional": true,
+          "description": "components allowlist, onUnknownVersion ('throw' | 'best-effort'), onUnknownComponent ('throw' | 'skip'). Since 0.6.0."
         }
       ],
       "returns": { "type": "World", "description": "Restored world." },
+      "throws": [
+        {
+          "type": "EcsError",
+          "when": "snapshot is not an object with an entities array, formatVersion is not 2 and onUnknownVersion is not 'best-effort', a component is undefined here and onUnknownComponent is not 'skip', or a component kind/SoA fields mismatch."
+        }
+      ],
       "examples": [],
       "seeAlso": ["toJSON"]
     },
@@ -1104,7 +1209,7 @@
       "stability": "experimental",
       "deprecated": false,
       "signature": "function createDeltaSerializer(world: World, options?: SerializeOptions): DeltaSerializer",
-      "summary": "Capture only changes since the previous capture. For network replication. Wire format may change before 1.0.",
+      "summary": "Capture only changes since the previous capture. For network replication. Each capture carries formatVersion 2 and the component table; apply() resolves it like fromJSON (unknown components throw) before touching the target, and keeps slot indices. Wire format may change before 1.0.",
       "params": [
         { "name": "world", "type": "World", "optional": false, "description": "Target world." },
         {
@@ -1151,14 +1256,20 @@
       "since": "0.1.0",
       "stability": "experimental",
       "deprecated": false,
-      "signature": "function adoptSnapshot(snap: { buffer: SharedArrayBuffer; meta: WorldMeta }): World",
-      "summary": "On the Worker side, materialise a world from a snapshot sent over postMessage.",
+      "signature": "function adoptSnapshot(snap: TransferableSnapshot, options?: DeserializeOptions): World",
+      "summary": "On the Worker side, materialise a world from a snapshot sent over postMessage. Validates the meta (magic, format version 2 unless onUnknownVersion is 'best-effort') and resolves components like deserializeWorld.",
       "params": [
         {
           "name": "snap",
           "type": "TransferableSnapshot",
           "optional": false,
           "description": "Snapshot received via onmessage."
+        },
+        {
+          "name": "options",
+          "type": "DeserializeOptions",
+          "optional": true,
+          "description": "Same as deserializeWorld. Since 0.6.0."
         }
       ],
       "returns": {
@@ -1175,8 +1286,8 @@
       "since": "0.1.0",
       "stability": "experimental",
       "deprecated": false,
-      "signature": "function attachWorld(buffer: SharedArrayBuffer, options?: { readOnly?: boolean }): World",
-      "summary": "Attach to a SAB that was set up by another thread. Use readOnly when this thread should only read.",
+      "signature": "function attachWorld(buffer: SharedArrayBuffer | ArrayBuffer, options?: DeserializeOptions & { readOnly?: boolean }): World",
+      "summary": "Attach to a SAB that was set up by another thread. Use readOnly when this thread should only read: every mutator, resetWorld included, then throws EcsError.",
       "params": [
         {
           "name": "buffer",
@@ -1186,9 +1297,9 @@
         },
         {
           "name": "options",
-          "type": "{ readOnly?: boolean }",
+          "type": "DeserializeOptions & { readOnly?: boolean }",
           "optional": true,
-          "description": "Attach flags."
+          "description": "readOnly flag plus the deserializeWorld options (onUnknownVersion, onUnknownComponent, components)."
         }
       ],
       "returns": { "type": "World", "description": "Attached world view." },
@@ -1245,9 +1356,21 @@
       "stability": "stable",
       "deprecated": false,
       "signature": "function addRelation<T>(world: World, source: EntityId, rel: Relation<T>, target: EntityId, data?: T): void",
-      "summary": "Add a relation edge from source to target.",
-      "params": [],
+      "summary": "Add a relation edge from source to target (replacing the current target of an exclusive relation), optionally with a data payload.",
+      "params": [
+        { "name": "world", "type": "World", "optional": false, "description": "Target world." },
+        { "name": "source", "type": "EntityId", "optional": false, "description": "Live source entity." },
+        { "name": "rel", "type": "Relation<T>", "optional": false, "description": "Relation handle." },
+        { "name": "target", "type": "EntityId", "optional": false, "description": "Live target entity." },
+        { "name": "data", "type": "T", "optional": true, "description": "Edge payload for getRelationData." }
+      ],
       "returns": { "type": "void", "description": "" },
+      "throws": [
+        {
+          "type": "EcsError",
+          "when": "source or target is not alive (since 0.6.0), rel is not a relation handle, or the world is read-only."
+        }
+      ],
       "examples": [
         {
           "title": "Mark Alice as child of Parent",
@@ -1292,7 +1415,7 @@
       "stability": "stable",
       "deprecated": false,
       "signature": "function getRelationData<T>(world: World, source: EntityId, rel: Relation<T>, target: EntityId): T | undefined",
-      "summary": "Read the data payload attached to a relation edge. Returns the value passed as `data` to `addRelation`, or `undefined` if no such edge exists or no data was stored. Subject to raw slot-keying: edges are keyed by slot index, not generation; validate liveness with `entityExists` if slot recycling is a concern.",
+      "summary": "Read the data payload attached to a relation edge. Returns the value passed as `data` to `addRelation`, or `undefined` if no such edge exists or no data was stored. Edges are keyed by slot index; storage never holds an edge for a dead entity, but a stale EntityId addresses its slot's current occupant, so validate cached ids with `entityExists`.",
       "params": [
         { "name": "world", "type": "World", "optional": false, "description": "Target world." },
         { "name": "source", "type": "EntityId", "optional": false, "description": "Source entity." },
@@ -1374,7 +1497,7 @@
       "stability": "stable",
       "deprecated": false,
       "signature": "function deref<T = unknown>(world: World, ref: EntityRef<T>): EntityId | null",
-      "summary": "Resolve a ref to its live EntityId, or null if stale / cross-world / OOB. Never throws.",
+      "summary": "Resolve a ref to its live EntityId, or null if stale / cross-world / OOB. Never throws for a live world; throws EcsError if world was already disposed.",
       "params": [
         { "name": "world", "type": "World", "optional": false, "description": "Target world." },
         {
@@ -1401,7 +1524,7 @@
       "stability": "stable",
       "deprecated": false,
       "signature": "function aliveRef<T = unknown>(world: World, ref: EntityRef<T>): boolean",
-      "summary": "Boolean guard form of deref. Returns true if ref is alive, false otherwise. Never throws.",
+      "summary": "Boolean guard form of deref. Returns true if ref is alive, false otherwise. Never throws for a live world; see deref for the disposed-world case.",
       "params": [
         { "name": "world", "type": "World", "optional": false, "description": "Target world." },
         { "name": "ref", "type": "EntityRef<T>", "optional": false, "description": "Ref to check." }
@@ -1419,8 +1542,8 @@
       "since": "0.5.6",
       "stability": "stable",
       "deprecated": false,
-      "signature": "class EcsError extends Error {}",
-      "summary": "Thrown by core world/entity/component operations for invariant violations and misuse (bad world options, a destroyed or unknown world, exhausted component slots, capacity overflow). Carries the aiecsjs:-prefixed message.",
+      "signature": "class EcsError extends Error { constructor(message: string, options?: { cause?: unknown }) }",
+      "summary": "Thrown by aiecsjs for invariant violations and misuse, before any change is made: bad or non-integer world options, a destroyed/unknown world, dead entities, unregistered components, invalid component keys, non-function callbacks or factories, dead relation endpoints, read-only world mutations, command-buffer errors and snapshot errors (malformed bytes, unsupported format version, unknown or mismatched components). Carries the aiecsjs:-prefixed message.",
       "params": [],
       "returns": {
         "type": "EcsError",
@@ -1442,7 +1565,7 @@
       "stability": "stable",
       "deprecated": false,
       "signature": "class EntityNotAliveError extends Error { readonly eid: number }",
-      "summary": "Thrown by refOf when the entity is not alive. deref and aliveRef never throw.",
+      "summary": "Thrown by refOf when the entity is not alive. deref and aliveRef never throw for a live world (they throw EcsError only if world was already disposed).",
       "params": [],
       "returns": {
         "type": "EntityNotAliveError",
@@ -1472,7 +1595,7 @@
       "module": "aiecsjs",
       "since": "0.1.0",
       "stability": "stable",
-      "definition": "type WorldOptions = { initialCapacity?: number; maxEntities?: number; indexBits?: 20 | 24; generationBits?: 8 | 12 | 16; buffer?: SharedArrayBuffer; bufferByteOffset?: number }"
+      "definition": "type WorldOptions = { initialCapacity?: number; maxEntities?: number; indexBits?: number; generationBits?: number; buffer?: SharedArrayBuffer; bufferByteOffset?: number } // numeric options must be integers; indexBits 1-24, generationBits 0-16, sum <= 32; buffer/bufferByteOffset reserved (no effect)"
     },
     {
       "name": "World",
@@ -1504,7 +1627,7 @@
       "module": "aiecsjs",
       "since": "0.1.0",
       "stability": "stable",
-      "definition": "interface SoAComponent<S extends SoASchema> { readonly __schema: S; readonly __soa: true }"
+      "definition": "interface SoAComponent<S extends SoASchema = SoASchema> { readonly __kind: 'soa'; readonly __id: number; readonly __schema: S }"
     },
     {
       "name": "AoSComponent",
@@ -1512,7 +1635,7 @@
       "module": "aiecsjs",
       "since": "0.1.0",
       "stability": "stable",
-      "definition": "interface AoSComponent<T> { readonly __aos: true }"
+      "definition": "interface AoSComponent<T = unknown> { readonly __kind: 'aos'; readonly __id: number; readonly __factory: () => T }"
     },
     {
       "name": "TagComponent",
@@ -1520,7 +1643,7 @@
       "module": "aiecsjs",
       "since": "0.1.0",
       "stability": "stable",
-      "definition": "interface TagComponent { readonly __tag: true }"
+      "definition": "interface TagComponent { readonly __kind: 'tag'; readonly __id: number }"
     },
     {
       "name": "ComponentLike",
@@ -1584,7 +1707,7 @@
       "module": "aiecsjs/serialize",
       "since": "0.1.0",
       "stability": "stable",
-      "definition": "type DeserializeOptions = { onUnknownVersion?: 'throw' | 'best-effort' }"
+      "definition": "type DeserializeOptions = { components?: ComponentLike[]; onUnknownVersion?: 'throw' | 'best-effort'; onUnknownComponent?: 'throw' | 'skip' }"
     },
     {
       "name": "WorldSnapshot",
@@ -1592,7 +1715,7 @@
       "module": "aiecsjs/serialize",
       "since": "0.1.0",
       "stability": "stable",
-      "definition": "interface WorldSnapshot { /* opaque, JSON-serializable */ }"
+      "definition": "interface WorldSnapshot { formatVersion: 2; version: string; capacity: number; maxEntities?: number; indexBits?: number; generationBits?: number; 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<{ kind: 'soa' | 'aos' | 'tag'; id: number; data: unknown }> }> }"
     },
     {
       "name": "DeltaSerializer",
@@ -1616,7 +1739,7 @@
       "module": "aiecsjs/relations",
       "since": "0.2.0",
       "stability": "experimental",
-      "definition": "interface Relation<T = void> { readonly __relation: true }"
+      "definition": "interface Relation<T = void> { readonly __kind: 'relation'; readonly __id: number; readonly __exclusive: boolean; readonly __hasData: boolean }"
     }
   ],
   "constants": [

package/dist/chunk-27JX7WHY.js

@@ -0,0 +1,2 @@
+var C="0.6.0";function D(e){return new Uint32Array(e)}function q(e,n){let t=n>>>5;e[t]=(e[t]??0)|1<<(n&31);}function S(e,n){let t=n>>>5;e[t]=(e[t]??0)&~(1<<(n&31));}function h(e,n){let t=n>>>5;return ((e[t]??0)&1<<(n&31))!==0}function b(e){let n=new Uint32Array(e.length);for(let t=0;t<e.length;t++)n[t]=e[t]??0;return n}function N(e){let n=[];for(let t=0;t<e.length;t++)n.push((e[t]??0).toString(16));return n.join(",")}function U(e,n,t,o){for(let r=0;r<t;r++){let i=e[n+r]??0;for(;i!==0;){let s=(r<<5)+tn(i);o(s),i&=i-1;}}}function bn(e,n,t,o,r,i,s){let a=!s;for(let c=0;c<t;c++){let u=e[n+c]??0,p=o[c]??0,M=r[c]??0,g=i[c]??0;if((u&p)!==p||(u&g)!==0)return  false;!a&&(u&M)!==0&&(a=true);}return a}function tn(e){return 31-Math.clz32(e&-e)}var d=class extends Error{constructor(n,t){super(n,t),this.name="EcsError";}};var v=globalThis,$=Symbol.for("aiecsjs.ids");v[$]??={component:1,query:1,world:1,relation:1};var E=v[$],z=Symbol.for(`aiecsjs.registry@${C}`);v[z]??={componentInfoById:new Map,componentInfoByKey:new Map,queryCache:new Map,reactiveBySource:new Map,reactiveSourcesByComponent:new Map,worlds:new Map,childOf:null,hooks:{observerDispatch:null,maskChange:null,destroyObservers:null,relationsCleanup:null}};var f=v[z];var w={initialCapacity:1024,maxEntities:1e6,indexBits:24,generationBits:8},on=256,k=f.worlds;function l(e){let n=e?.id,t=k.get(n);if(!t)throw new d(`aiecsjs: world ${n} is destroyed or unknown`);return t}function x(e){let n=l(e);if(n.readOnly)throw new d("aiecsjs: cannot mutate a read-only world");return n}function rn(e){k.set(e.id,e);}function sn(e){k.delete(e);}function vn(e){return k.has(e)}function an(e){let n=e??{};for(let c of Object.keys(w)){let u=n[c];if(u!==void 0&&!Number.isInteger(u))throw new d(`aiecsjs: ${c} must be an integer`)}let t=n.indexBits??w.indexBits,o=n.generationBits??w.generationBits,r=on;if(t<1||t>24)throw new d("aiecsjs: indexBits must be in [1, 24]");if(o<0||o>16)throw new d("aiecsjs: generationBits must be in [0, 16]");if(t+o>32)throw new d(`aiecsjs: indexBits (${t}) + generationBits (${o}) must be <= 32`);let i=1<<t,s=Math.max(1,Math.min(n.initialCapacity??w.initialCapacity,i)),a=Math.max(s,Math.min(n.maxEntities??w.maxEntities,i));return {initialCapacity:s,maxEntities:a,indexBits:t,generationBits:o,indexMask:(1<<t)-1,generationMask:o===0?0:(1<<o)-1,maxComponents:r,maskWordCount:Math.ceil(r/32),buffer:n.buffer??null,bufferByteOffset:n.bufferByteOffset??0}}function En(e){let n=an(e),t=E.world++,o=n.generationBits>8?Uint16Array:Uint8Array,r=new o(n.initialCapacity),i={id:t,capacity:n.initialCapacity,version:C,options:n,size:0,nextFreshIndex:1,freeList:[],generations:r,destroyed:false,destroying:new Set,removing:new Set,visitStamp:new Uint32Array(0),visitEpoch:0,componentBitFor:new Map,componentInfoByBit:new Array(n.maxComponents).fill(null),componentStorageByBit:new Array(n.maxComponents).fill(null),nextComponentBit:0,entityArchetype:new Uint32Array(n.initialCapacity),entityMask:new Uint32Array(n.initialCapacity*n.maskWordCount),archetypes:[],archetypeByMaskHash:new Map,queryVersion:0,queries:[],queryMasks:new Map,queryArchetypeCache:[],queryArchetypeStamp:[],bitToQueries:new Map,reactiveBuffers:new Map,observers:[],relationStorage:new Map,sab:n.buffer,readOnly:false};return R(i,D(n.maskWordCount)),rn(i),cn(i)}function cn(e){return {id:e.id,get capacity(){return e.capacity},version:e.version}}function Wn(e){let n=k.get(e?.id);!n||n.destroyed||(n.destroyed=true,n.archetypes=[],n.archetypeByMaskHash.clear(),n.componentInfoByBit=[],n.componentStorageByBit=[],n.queries=[],n.queryMasks.clear(),n.queryArchetypeCache=[],n.observers=[],n.relationStorage.clear(),n.reactiveBuffers.clear(),n.entityMask=new Uint32Array(0),n.entityArchetype=new Uint32Array(0),n.visitStamp=new Uint32Array(0),n.generations=new Uint8Array(0),n.freeList=[],n.destroying.clear(),n.componentBitFor.clear(),n.bitToQueries.clear(),n.queryArchetypeStamp=[],n.sab=null,sn(n.id));}function Bn(e){let n=x(e);n.size=0,n.nextFreshIndex=1,n.freeList=[],n.destroying.clear(),n.generations.fill(0),n.entityArchetype.fill(0),n.entityMask.fill(0);for(let t of n.archetypes)t.size=0,t.entityRow.clear();for(let t of n.componentStorageByBit)if(t)if(t.kind==="soa"&&t.soa)for(let o of Object.keys(t.soa))t.soa[o]?.fill(0);else t.kind==="aos"&&t.aos&&t.aos.fill(void 0);n.relationStorage.clear(),n.queryVersion++;for(let t of n.reactiveBuffers.values())t.entered.length=0,t.exited.length=0;}function Mn(e){return l(e).size}function Un(e){return l(e).capacity}function O(e,n){if(n<=e.capacity)return;if(n>e.options.maxEntities)throw new d(`aiecsjs: requested capacity ${n} exceeds maxEntities ${e.options.maxEntities}`);let t=e.capacity;for(;t<n;)t=Math.min(t*2,e.options.maxEntities);un(e,t);}function un(e,n){let t=e.generations.constructor,o=new t(n);o.set(e.generations),e.generations=o;let r=new Uint32Array(n);r.set(e.entityArchetype),e.entityArchetype=r;let i=e.options.maskWordCount,s=new Uint32Array(n*i);if(s.set(e.entityMask),e.entityMask=s,e.visitStamp.length>0){let a=new Uint32Array(n);a.set(e.visitStamp),e.visitStamp=a;}for(let a of e.componentStorageByBit)if(a)if(a.kind==="soa"&&a.soa){let c=e.componentInfoByBit[a.bit];c&&dn(a.soa,c.fields,n);}else a.kind==="aos"&&a.aos&&(a.aos.length=n);e.capacity=n;}function dn(e,n,t){for(let o of n){let r=e[o.name];if(!r)continue;let i=t*o.vectorLen;if(r.length>=i)continue;let s=new o.ctor(i);s.set(r),e[o.name]=s;}}function R(e,n){let t=N(n),o=e.archetypeByMaskHash.get(t);if(o!==void 0)return {archId:o,created:false};let r=e.archetypes.length,i={id:r,mask:b(n),size:0,capacity:16,entities:new Uint32Array(16),entityRow:new Map};return e.archetypes.push(i),e.archetypeByMaskHash.set(t,r),e.queryVersion++,{archId:r,created:true}}function W(e,n){if(e.size===e.capacity){e.capacity*=2;let t=new Uint32Array(e.capacity);t.set(e.entities),e.entities=t;}e.entities[e.size]=n,e.entityRow.set(n,e.size++);}function B(e,n){let t=e.entityRow.get(n);if(t===void 0)return;let o=--e.size,r=e.entities[o]??0;e.entities[t]=r,e.entityRow.set(r,t),e.entities[o]=0,e.entityRow.delete(n);}function P(e,n){let t=e.componentBitFor.get(n.id);if(t!==void 0)return t;if(e.nextComponentBit>=e.options.maxComponents)throw new d(`aiecsjs: world reached maxComponents=${e.options.maxComponents}`);let o=e.nextComponentBit++;e.componentBitFor.set(n.id,o),e.componentInfoByBit[o]=n;let r;if(n.kind==="soa"){let i={};for(let s of n.fields)i[s.name]=new s.ctor(e.capacity*s.vectorLen);r={kind:"soa",componentId:n.id,bit:o,soa:i};}else n.kind==="aos"?r={kind:"aos",componentId:n.id,bit:o,aos:new Array(e.capacity)}:r={kind:"tag",componentId:n.id,bit:o};return e.componentStorageByBit[o]=r,o}function m(e,n){let t=e.options.maskWordCount,o=new Uint32Array(t),i=(n&e.options.indexMask)*t;for(let s=0;s<t;s++)o[s]=e.entityMask[i+s]??0;return o}function G(e,n,t){let o=e.options.maskWordCount,i=(n&e.options.indexMask)*o;for(let s=0;s<o;s++)e.entityMask[i+s]=t[s]??0;}function A(e,n){return e.componentBitFor.get(n.id)}function On(e){if(!e||typeof e!="object")return  false;let n=e;return typeof n.id!="number"||typeof n.version!="string"?false:k.has(n.id)}var fn={i8:Int8Array,u8:Uint8Array,i16:Int16Array,u16:Uint16Array,i32:Int32Array,u32:Uint32Array,f32:Float32Array,f64:Float64Array,eid:Uint32Array,bool:Uint8Array},j=f.componentInfoById,V=f.componentInfoByKey;function L(e,n,t=null,o=[],r=null){let i=e?.key;if(i!==void 0){if(typeof i!="string"||i==="")throw new d("aiecsjs: component key must be a non-empty string");let c=V.get(i);if(c){if(c.kind!==n||c.fields.length!==o.length||c.fields.some((u,p)=>u.name!==o[p].name||u.type!==o[p].type||u.vectorLen!==o[p].vectorLen))throw new d(`aiecsjs: component key "${i}" is already defined with a different layout`);return r&&(c.factory=r),c.id}}let s=E.component++,a={id:s,key:i??null,kind:n,schema:t,fields:o,factory:r};return j.set(s,a),i!==void 0&&V.set(i,a),s}function Dn(e,n){let t=[];for(let[o,r]of Object.entries(e)){let i,s=1;if(typeof r=="string")i=r;else if(Array.isArray(r)){let[c,u]=r;i=c,s=u;}else throw new TypeError(`aiecsjs: invalid field declaration for "${o}"`);let a=fn[i];if(!a)throw new TypeError(`aiecsjs: unknown field type "${i}" for field "${o}"`);t.push({name:o,type:i,vectorLen:s,ctor:a});}return {__kind:"soa",__id:L(n,"soa",e,t),__schema:e}}function qn(e){return {__kind:"tag",__id:L(e,"tag")}}function Nn(e,n){if(e!==void 0&&typeof e!="function")throw new d("aiecsjs: factory must be a function");let t=e??(()=>({}));return {__kind:"aos",__id:L(n,"aos",null,[],t),__factory:t}}function I(e){let n=j.get(e?.__id);if(!n)throw new d("aiecsjs: component is not registered (call defineComponent/defineTag/defineObjectComponent)");return n}function pn(e,n,t,o){let r=x(e);if(!y(r,n))throw new d(`aiecsjs: addComponent on dead entity ${n}`);let i=I(t),s=P(r,i),a=n&r.options.indexMask,c=m(r,n);if(h(c,s)){o!==void 0&&_(r,a,i,s,o);return}let u=b(c);q(u,s),i.kind==="aos"&&H(r,a,i,s),Y(r,n,u),_(r,a,i,s,o),f.hooks.observerDispatch?.fireAdd(r,n,s,c,u),F(r,n,s,c,u);}function $n(e,n,t){let o=x(e);if(!y(o,n))return;let r=I(t),i=A(o,r);if(i===void 0||!h(m(o,n),i))return;let s=(n&o.options.indexMask)*o.options.maxComponents+i;if(o.removing.has(s))return;o.removing.add(s);try{f.hooks.observerDispatch?.fireRemove(o,n,i);}finally{o.removing.delete(s);}if(!y(o,n))return;let a=m(o,n);if(!h(a,i))return;let c=b(a);S(c,i),Y(o,n,c),f.hooks.observerDispatch?.fireRemoveQuery(o,n,a,c);let u=n&o.options.indexMask,p=o.componentStorageByBit[i];p?.kind==="soa"&&p.soa?K(p.soa,r.fields,u):p?.kind==="aos"&&p.aos&&(p.aos[u]=void 0),F(o,n,i,a,c);}function zn(e,n,t){let o=l(e);if(!y(o,n))return  false;let r=I(t),i=A(o,r);if(i===void 0)return  false;let s=m(o,n);return h(s,i)}function Pn(e,n,t){let o=l(e);if(!y(o,n))return;let r=I(t),i=A(o,r);if(i===void 0)return;let s=m(o,n);if(!h(s,i))return;let a=o.componentStorageByBit[i];if(a){if(a.kind==="soa")return a.soa;if(a.kind==="aos"){let c=n&o.options.indexMask;return a.aos?.[c]}return  true}}function Gn(e,n,t,o){let r=x(e);if(!y(r,n))throw new d(`aiecsjs: setComponent on dead entity ${n}`);let i=I(t),s=A(r,i);if(s===void 0||!h(m(r,n),s)){pn(e,n,t,o);return}_(r,n&r.options.indexMask,i,s,o),f.hooks.observerDispatch?.fireSet(r,n,s,o);}function _(e,n,t,o,r){let i=e.componentStorageByBit[o];if(t.kind==="soa"&&i?.soa){if(r==null)return;let s=r;for(let a of t.fields){if(!(a.name in s))continue;let c=i.soa[a.name];if(!c)continue;let u=s[a.name];if(a.vectorLen===1)c[n]=typeof u=="boolean"?u?1:0:Number(u);else if(Array.isArray(u)||ArrayBuffer.isView(u)){let p=n*a.vectorLen,M=u;for(let g=0;g<a.vectorLen;g++)c[p+g]=Number(M[g]??0);}}}else if(t.kind==="aos"){let s=H(e,n,t,o);if(r&&typeof r=="object"){let a=r,c=s;for(let u of Object.keys(a))u==="__proto__"||u==="constructor"||u==="prototype"||(c[u]=a[u]);}}}function H(e,n,t,o){let r=e.componentStorageByBit[o].aos;if(r[n]===void 0){let i=t.factory();if(i==null)throw new d("aiecsjs: factory result must not be null or undefined");r[n]=i;}return r[n]}function K(e,n,t){for(let o of n){let r=e[o.name];if(r)if(o.vectorLen===1)r[t]=0;else {let i=t*o.vectorLen;for(let s=0;s<o.vectorLen;s++)r[i+s]=0;}}}function Q(e,n){let t=e.options.maskWordCount,o=n&e.options.indexMask,r=o*t;U(e.entityMask,r,t,i=>{let s=e.componentStorageByBit[i],a=e.componentInfoByBit[i];s?.kind==="soa"&&s.soa&&a?K(s.soa,a.fields,o):s?.kind==="aos"&&s.aos&&(s.aos[o]=void 0);});}function Y(e,n,t){let o=n&e.options.indexMask,r=e.entityArchetype[o]??0,i=e.archetypes[r];if(!i)return;let a=R(e,t).archId,c=e.archetypes[a];c&&(a!==r&&(B(i,n),W(c,n),e.entityArchetype[o]=a),G(e,n,t));}function Vn(e){f.hooks.maskChange=e;}function F(e,n,t,o,r){f.hooks.maskChange?.(e,n,t,o,r);}function X(e,n,t){let o=e.options.maskWordCount,r=b(t),i=b(t);U(t,0,o,s=>{S(i,s),F(e,n,s,r,i),S(r,s);});}function Hn(e){f.hooks.observerDispatch=e;}function Kn(e){return j.get(e)}var T=24,yn=8,Z=(1<<T)-1,J=(1<<yn)-1;function nn(e,n,t){return ((n&t.generationMask)<<t.indexBits|e&t.indexMask)>>>0}function ne(e,n){return e&n.indexMask}function ee(e,n){return e>>>n.indexBits&n.generationMask}function te(e){let n=l(e);if(n.readOnly)throw new d("aiecsjs: cannot createEntity on a read-only world (worker-attached)");let t;if(n.freeList.length>0)t=n.freeList.pop();else {if(n.nextFreshIndex>=n.options.maxEntities)throw new d(`aiecsjs: reached maxEntities ${n.options.maxEntities}`);n.nextFreshIndex>=n.capacity&&O(n,n.nextFreshIndex+1),t=n.nextFreshIndex++;}return en(n,t)}function en(e,n){let t=nn(n,e.generations[n]??0,e.options),o=e.archetypes[0];if(!o)throw new d("aiecsjs: missing empty archetype");return W(o,t),e.entityArchetype[n]=0,e.entityMask.fill(0,n*e.options.maskWordCount,(n+1)*e.options.maskWordCount),e.size++,t}function oe(e,n){if(e.readOnly)throw new d("aiecsjs: cannot create entities on a read-only world (worker-attached)");if(n<=0||n>=e.options.maxEntities)throw new d(`aiecsjs: slot index ${n} out of range`);n>=e.capacity&&O(e,n+1);let t=e.generations[n]??0,o=nn(n,t,e.options);if(y(e,o))return o;if(n>=e.nextFreshIndex){for(let r=e.nextFreshIndex;r<n;r++)e.freeList.push(r);e.nextFreshIndex=n+1;}else {let r=e.freeList.lastIndexOf(n);if(r!==-1){let i=e.freeList.length-1;e.freeList[r]=e.freeList[i],e.freeList.pop();}}return en(e,n)}function re(e,n){let t=l(e);if(t.readOnly)throw new d("aiecsjs: cannot destroyEntity on a read-only world");if(!y(t,n)||t.destroying.has(n))return;let o=n&t.options.indexMask;t.destroying.add(n);let r;try{f.hooks.destroyObservers?.dispatchDestroyObservers(t,n),mn(t,n);}finally{r=t.destroying.delete(n);}if(!r||t.destroyed||!y(t,n))return;let i=m(t,n);Q(t,n),B(t.archetypes[t.entityArchetype[o]??0],n),X(t,n,i),t.entityArchetype[o]=0,t.entityMask.fill(0,o*t.options.maskWordCount,(o+1)*t.options.maskWordCount),t.generations[o]=(t.generations[o]??0)+1&t.options.generationMask,t.freeList.push(o),t.size--;}function ln(e,n){let t=l(e);return y(t,n)}function y(e,n){let t=n&e.options.indexMask;if(t<=0||t>=e.capacity)return  false;let o=e.entityArchetype[t]??0,r=e.archetypes[o];if(!r||!r.entityRow.has(n))return  false;let i=e.generations[t]??0,s=n>>>e.options.indexBits&e.options.generationMask;return i===s}function ie(e){return e&Z}function se(e){return e>>>T&J}function ae(e,n){return ((n&J)<<T|e&Z)>>>0}function ce(e,n){return typeof n!="number"?false:ln(e,n)}function ue(e){f.hooks.destroyObservers=e;}function de(e){f.hooks.relationsCleanup=e;}function mn(e,n){f.hooks.relationsCleanup?.(e,n);}export{ie as A,se as B,ae as C,ce as D,ue as E,de as F,Dn as G,qn as H,Nn as I,I as J,pn as K,$n as L,zn as M,Pn as N,Gn as O,Vn as P,Hn as Q,Kn as R,C as a,D as b,q as c,U as d,bn as e,d as f,E as g,f as h,l as i,x as j,vn as k,En as l,Wn as m,Bn as n,Mn as o,Un as p,P as q,On as r,nn as s,ne as t,ee as u,te as v,oe as w,re as x,ln as y,y as z};//# sourceMappingURL=chunk-27JX7WHY.js.map
+//# sourceMappingURL=chunk-27JX7WHY.js.map