aiecsjs 0.5.6 → 0.5.8

package/llms-full.txt

@@ -12,959 +12,83 @@ The short index lives at `llms.txt` (see https://llmstxt.org/).
 
 # aiecsjs
 
-[![npm version](https://img.shields.io/npm/v/aiecsjs.svg)](https://www.npmjs.com/package/aiecsjs)
-[![CI](https://github.com/islumina/aiecsjs/actions/workflows/ci.yml/badge.svg)](https://github.com/islumina/aiecsjs/actions/workflows/ci.yml)
-[![License](https://img.shields.io/badge/license-MIT-brightgreen.svg)](LICENSE)
-[![AI Generated](https://img.shields.io/badge/AI_Generated-Claude_Code_Opus_4.7_Max-blueviolet.svg)](https://www.anthropic.com/claude-code)
-[![繁體中文](https://img.shields.io/badge/lang-繁體中文-red.svg)](README_ZHTW.md)
+TypeScript-first archetype ECS with TypedArray SoA components, command buffers, relations, serialization, and SAB-ready snapshot transport.
 
-> A TypeScript-first archetype ECS for browser and Node, with SAB-ready snapshot transport and AI-readable documentation.
-
-Part of the [ai\*js micro-runtime ecosystem](https://github.com/islumina) — see also [aifsmjs](https://github.com/islumina/aifsmjs) (FSM) and [aibridgejs](https://github.com/islumina/aibridgejs) (cross-context RPC).
-
-aiecsjs uses **archetype tables with TypedArray columns** and **bitmask queries** — the same architecture that powers piecs and wolf-ecs at the top of public benchmarks. Its API is **functional and tree-shakable**, composed with `pipe()`. Components support both Structure-of-Arrays (SoA) and Array-of-Structures (AoS) layouts. Since 0.3, `EntityId` packs index + generation into a single 32-bit number; the ABA-safe `EntityRef` API shipped in 0.3.0.
-
-```ts
-import { createWorld, createEntity, addComponent, defineComponent, defineQuery, pipe, forEachEntityIndexed, Types } from 'aiecsjs'
-
-const Position = defineComponent({ x: Types.f32, y: Types.f32 })
-const Velocity = defineComponent({ x: Types.f32, y: Types.f32 })
-
-const world = createWorld()
-const eid = createEntity(world)
-addComponent(world, eid, Position, { x: 0, y: 0 })
-addComponent(world, eid, Velocity, { x: 1, y: 2 })
-
-const movers = defineQuery([Position, Velocity])
-const movement = (w, dt) => { forEachEntityIndexed(w, movers, (e, i, pos, vel) => { pos.x[i] += vel.x[i] * dt; pos.y[i] += vel.y[i] * dt }); return w }
-
-pipe(movement)(world, 1/60)
-```
-
-> **Use `forEachEntityIndexed` for column iteration.** Its callback is `(e, i, ...cols)`: `e` is the packed `EntityId` (use it directly for `destroyEntity`, `hasComponent`, `getComponent`, command buffers), and `i` is the **safe column subscript** — index every SoA column with it (`pos.x[i]`). The packed `e` is **not** a column index: it only equals the index until a slot is recycled (generation 0); after any `destroyEntity` recycles a slot, `e !== i` and indexing a column with `e` reads the wrong slot (out of bounds → `undefined`/`NaN`). `forEachEntityIndexed` hands you the correct `i` so this footgun is closed in code. Use `forEachEntity` when you only need the `EntityId` (and index columns via `getEntityIndex(e)` if you must).
-
-> **Status: experimental (v0.5.x).** The API surface in `STABILITY.md` is committed for the 0.x line, but expect adjustments. A stable 1.0 freeze is targeted after community feedback.
-
-## Table of contents
-
-- [Why aiecsjs?](#why-aiecsjs)
-- [Install](#install)
-- [Quick Start](#quick-start)
-- [Core Concepts](#core-concepts)
-- [Guide](#guide)
-- [API Reference](#api-reference)
-- [Performance](#performance)
-- [Multi-threading Guide](#multi-threading-guide)
-- [WebGPU Interop](#webgpu-interop)
-- [Serialization Guide](#serialization-guide)
-- [Migration Guides](#migration-guides)
-- [For AI Agents](#for-ai-agents)
-- [FAQ](#faq)
-- [Caveats and Known Limitations](#caveats-and-known-limitations)
-- [Contributing](#contributing)
-- [Changelog](#changelog)
-- [License](#license)
-
-## Why aiecsjs?
-
-- **Archetype-first storage** — entities sharing the same component set live in one contiguous table; queries walk straight `for` loops over parallel TypedArrays. Iteration is cache-friendly by construction.
-- **Zero-config TypeScript inference** — `defineQuery([Position, Velocity])` returns an iterator that yields `(eid, posCols, velCols)` with the correct TypedArray types. No manual generics.
-- **AI-first documentation contract** — every public export has a stability tag and a `since` version. Ships `llms.txt`, `llms-full.txt`, and `api.json` so LLM tools can read the API surface directly.
-
-### Comparison
-
-| | aiecsjs 0.1 | bitECS 0.4 | miniplex 2.0 | becsy 0.15 |
-|---|---|---|---|---|
-| Storage | Archetype + SoA columns | SparseSet + bitmask + SoA/AoS | Archetype + JS objects | Configurable (packed/sparse/compact) + ArrayBuffer |
-| API style | Functional + `pipe` | Functional + `pipe` | Chainable OO | Decorator classes |
-| TS inference on query | Tuple-aware columns | Manual | Predicate inference | Class-based |
-| Multi-thread | SAB snapshot transport (0.x); true shared cols planned 0.3+ | SAB-ready, scheduling DIY | Single-thread | Roadmap (not shipped) |
-| AI docs | `llms.txt` + `llms-full.txt` + `api.json` | No | No | No |
-| Maintenance | Active (new) | Active | Slowed (~3y since npm release) | Active |
-
-### When NOT to use aiecsjs
-
-- **You need the tiniest possible bundle (≤ 3 kB).** Use [bitECS 0.4](https://github.com/NateTheGreatt/bitECS) — its SparseSet model is leaner and tree-shakes aggressively.
-- **You want plain JS objects as entities with full DX freedom.** Use [miniplex](https://github.com/hmans/miniplex). It's the DX champion at the cost of a 2–4× iteration penalty.
-- **You need automatic system scheduling with declared read/write entitlements.** Use [@lastolivegames/becsy](https://github.com/LastOliveGames/becsy). aiecsjs systems are just functions in `pipe()` order.
-- **Your workload is entity-churn dominated (>50% of entities change shape per frame).** A sparse-set ECS will beat an archetype ECS here. Use bitECS or goodluck.
-
-### What aiecsjs does NOT do
-
-The core stays narrow on purpose. The following are explicit non-goals; reach for a dedicated tool or write app-layer code:
-
-- **System scheduler with declared read/write entitlements.** `pipe()` runs systems in declared order. Use `@lastolivegames/becsy` if you need parallel scheduling.
-- **Render component / scene-graph sync.** ECS holds data only. Pair with PixiJS, Three.js, or your renderer of choice.
-- **Physics / spatial partition.** No broad-phase, no collision. Use Rapier, Matter, or a dedicated quadtree.
-- **Network replication.** `aiecsjs/serialize` produces snapshot bytes; how they cross the wire is your app's choice.
-- **Reactive value-predicate queries.** `enterQuery` / `exitQuery` fire on component-set membership change only. Component value mutations are not tracked.
-- **Prefab / entity inheritance / hierarchy.** `aiecsjs/relations` provides plain entity-to-entity references, not inheritance.
-
-## Integration with aibridgejs
-
-If you stream world state across an [aibridgejs](https://www.npmjs.com/package/aibridgejs) bridge (iframe / Flutter InAppWebView), the bridge enforces a strict JSON envelope and silently drops `Date`, `Map`, `Set`, and class instances. AoS components from `defineObjectComponent(...)` can legally hold any of these; sending them as-is corrupts the payload on the host side.
-
-Correct shape — serialise first, emit a plain object or byte array:
-
-```ts
-import { toJSON } from 'aiecsjs/serialize'
-
-const snap = toJSON(world)
-await bridge.emit('world.snapshot', snap)
-```
-
-Do NOT do — `getComponent` returns the live column view or the AoS instance with its prototype intact, which the bridge cannot transport:
-
-```ts
-await bridge.emit('inv', getComponent(world, eid, Inventory))
-```
-
-`serializeWorld(world)` (binary, `Uint8Array`) is also bridge-safe; wrap the bytes in a JSON envelope like `{ kind: 'binary', bytes: Array.from(snap) }`, or use a transferable channel when the host supports it.
+> **Status: 0.5.8 - stable 1.0-track core.** Root ECS APIs are stable; worker transport remains adapter-shaped and environment-dependent.
 
 ## Install
 
 ```bash
-npm install aiecsjs
 pnpm add aiecsjs
-yarn add aiecsjs
-bun add aiecsjs
-```
-
-CDN (ESM):
-
-```html
-<script type="module">
-  import { createWorld } from 'https://unpkg.com/aiecsjs?module'
-</script>
 ```
 
-Peer requirements: **Node 18+** (for ESM and structured-clone WebStreams), **TypeScript 5.0+** (optional but recommended for the inference goodies).
-
-## Quick Start
-
 ```ts
 import {
-  createWorld, createEntity, destroyEntity,
-  defineComponent, addComponent, removeComponent,
-  defineQuery, forEachEntityIndexed, pipe, Types,
-} from 'aiecsjs'
-import { createLoop } from 'aiecsjs/loop'
-
-const Position = defineComponent({ x: Types.f32, y: Types.f32 })
-const Velocity = defineComponent({ x: Types.f32, y: Types.f32 })
-const Lifetime = defineComponent({ remaining: Types.f32 })
-
-const world = createWorld({ initialCapacity: 1024 })
-
-for (let i = 0; i < 100; i++) {
-  const e = createEntity(world)
-  addComponent(world, e, Position, { x: Math.random() * 100, y: Math.random() * 100 })
-  addComponent(world, e, Velocity, { x: Math.random() * 2 - 1, y: Math.random() * 2 - 1 })
-  addComponent(world, e, Lifetime, { remaining: 5 })
-}
-
-const movers = defineQuery([Position, Velocity])
-const decaying = defineQuery([Lifetime])
-
-const movementSystem = (w, dt) => {
-  forEachEntityIndexed(w, movers, (e, i, pos, vel) => {
-    pos.x[i] += vel.x[i] * dt   // `i` is the safe column subscript
-    pos.y[i] += vel.y[i] * dt
-  })
-  return w
-}
-
-const lifetimeSystem = (w, dt) => {
-  forEachEntityIndexed(w, decaying, (e, i, life) => {
-    life.remaining[i] -= dt
-    if (life.remaining[i] <= 0) destroyEntity(w, e)   // destroyEntity takes the packed `e`
-  })
-  return w
-}
-
-const tick = pipe(movementSystem, lifetimeSystem)
-const loop = createLoop({ fixed: 1 / 60, onUpdate: (dt) => tick(world, dt) })
-loop.start()
-```
-
-That's a complete simulation: 100 particles drifting until each one's lifetime expires.
-
-## Core Concepts
-
-**Entity.** A versioned 32-bit ID. The low bits are the entity index; the high bits are a generation counter that bumps when the ID is recycled. This prevents the "I cached a reference to entity 42 but now entity 42 is something else" class of bug. Default split is 24 index bits + 8 generation bits (≈ 16M entities × 256 recycles each). Because the packed ID is **not** the column index once a slot is recycled, prefer **`forEachEntityIndexed((e, i, ...cols) => …)`** for column iteration — it hands you the masked index `i` (the safe SoA subscript, `pos.x[i]`) alongside the packed `e`. For the raw `forEachEntity` form, derive the index with `getEntityIndex(e)`.
-
-**Component.** A data type attached to entities. Two flavours:
-- **SoA (Structure of Arrays)** — declared with `defineComponent({ x: Types.f32, y: Types.f32 })`. Each field becomes a TypedArray column indexed by entity ID. Best for hot, numeric data.
-- **AoS (Array of Structures)** — declared with `defineObjectComponent(() => ({ ref: null }))`. Each entity gets its own JS object. Best for heterogeneous data or external references (e.g. a `three.js` Mesh).
-
-**System.** Just a function: `(world, ctx) => world`. No base class, no decorators. Compose multiple systems with `pipe()`. The returned world is the same world reference — `pipe` is associative and the world is mutated in place.
-
-**Query.** A persistent descriptor over component sets: `defineQuery({ all: [Position], any: [Active, Visible], none: [Hidden] })`. Queries are pre-compiled to a bitmask pair and cached in the world; iteration is O(matching archetypes), not O(entities).
-
-**World.** Owns all entities, components, archetypes, and query indices. Multiple worlds are supported; they do not share entity IDs unless you opt-in by sharing a `SharedArrayBuffer`.
-
-**Archetype.** An internal table — one per unique component combination present in the world. When an entity gains or loses a component, it migrates from one archetype to another. Migration cost scales with the number of component columns the entity has; iteration cost does not.
-
-## Guide
-
-### Defining components
-
-```ts
-// SoA: TypedArray-backed, max performance, SAB-safe
-const Position = defineComponent({ x: Types.f32, y: Types.f32 })
-
-// SoA with a fixed-size vector field
-const Transform = defineComponent({
-  position: [Types.f32, 3],   // Float32Array per entity, length 3
-  scale: Types.f32,
-})
-
-// Tag: zero-byte marker, no data
-const Player = defineTag()
-const Dead = defineTag()
-
-// AoS: arbitrary JS objects, main-thread only
-const MeshRef = defineObjectComponent<{ mesh: THREE.Mesh | null }>(() => ({ mesh: null }))
-```
-
-### Spawning and destroying entities
-
-```ts
-const eid = createEntity(world)
-addComponent(world, eid, Position, { x: 10, y: 20 })
-addComponent(world, eid, Player)
-
-if (entityExists(world, eid)) {
-  destroyEntity(world, eid)
-}
-```
-
-`destroyEntity` increments the entity's generation immediately, so any cached `EntityId` becomes invalid on the next `entityExists` check.
-
-### Writing systems
-
-```ts
-const moveSystem = (world: World, dt: number) => {
-  forEachEntityIndexed(world, defineQuery([Position, Velocity]), (e, i, pos, vel) => {
-    pos.x[i] += vel.x[i] * dt   // `i` is the safe column subscript
-    pos.y[i] += vel.y[i] * dt
-  })
-  return world
-}
-```
-
-**Prefer `forEachEntityIndexed` for column iteration.** Its callback is `(e, i, ...cols)`: index every SoA column with `i` (the masked slot index), and pass the packed `e` to entity operations (`destroyEntity`, `hasComponent`, command buffers). The yielded `i` is always the correct subscript, even after a slot is recycled — so you never hand-mask or call `getEntityIndex` in the loop. Use **`forEachEntity`** when you only need the `EntityId` (its first argument is a packed `EntityId`, not a column index; derive the subscript with `getEntityIndex(e)` if you must index columns). See [Core Concepts → Entity](#core-concepts) for why `e !== i` once a slot is recycled.
-
-Hoist `defineQuery(...)` calls out of the hot loop — the same query object is returned for the same component set, but the lookup still costs a hash.
-
-### Tags in mixed queries
-
-Every component named in `defineQuery([...])` — **including tags** — occupies one callback slot, in declaration order. A tag has no storage, so its slot is passed as the literal `true`:
-
-```ts
-const Frozen = defineTag()
-const q = defineQuery([Frozen, Position])   // tag first
-
-// ❌ Wrong: `pos` binds to the tag slot (`true`); `pos.x` throws.
-forEachEntityIndexed(world, q, (e, i, pos) => { /* pos === true */ })
-
-// ✅ Correct: account for every slot. Tag arrives as `true`.
-forEachEntityIndexed(world, q, (e, i, _frozen, pos) => {
-  pos.x[i] += 1
-})
-```
-
-**Recommendation: put tags last** so data columns come first and the trailing `true` slots are easy to ignore:
-
-```ts
-const q = defineQuery([Position, Velocity, Frozen])   // tags last
-forEachEntityIndexed(world, q, (e, i, pos, vel /* , _frozen */) => {
-  pos.x[i] += vel.x[i]
-})
-```
-
-(Tags still filter membership either way — ordering only affects the callback's argument layout. The column-argument list is `any`-typed, so a mismatched binding is a runtime error, not a compile error.)
-
-### Composing with pipe and createLoop
-
-```ts
-import { createLoop } from 'aiecsjs/loop'
-
-const tick = pipe(inputSystem, physicsSystem, movementSystem, renderSystem)
-
-const loop = createLoop({
-  fixed: 1 / 60,
-  maxSubSteps: 5,
-  onUpdate: (dt) => tick(world, dt),
-  onRender: (alpha) => renderInterpolated(world, alpha),
-})
-
-loop.start()
-// later: loop.stop()
+  Types,
+  addComponent,
+  createEntity,
+  createWorld,
+  defineComponent,
+  forEachEntity,
+  getComponent,
+} from "aiecsjs";
 ```
 
-The accumulator pattern in `createLoop` is the canonical fixed-timestep model from `gafferongames.com` — physics is deterministic and decoupled from variable frame rate.
-
-### Reactive queries (enter/exit)
-
-```ts
-const newlyDead = enterQuery(defineQuery([Dead]))
-const noLongerDead = exitQuery(defineQuery([Dead]))
-
-const reapSystem = (world) => {
-  forEachEntity(world, newlyDead, (e) => playDeathAnimation(e))
-  forEachEntity(world, noLongerDead, (e) => stopDeathAnimation(e))
-  return world
-}
-```
-
-`enterQuery` yields only entities that newly match this frame; `exitQuery` yields only entities that left. Both are computed incrementally during structural changes — there's no per-frame scan.
-
-> **Define reactive queries at module scope** (as above), before any update runs. A reactive query's enter/exit buffer is **armed lazily** — the world starts tracking a query's transitions the first time that query (or its `enterQuery`/`exitQuery` view) participates in a structural change or is read. Create/destroy events that happen *before* the first registration are not retroactively captured. Module-scope definitions register the query at import time, so the very first `tick` already observes transitions; queries created lazily inside a system may miss the events from the frame they were introduced.
-
-### Observers
-
-```ts
-import { onAdd, onRemove, onSet } from 'aiecsjs/observers'
-
-const stopAdd = onAdd(world, Position, (e) => console.log('positioned', e))
-const stopRemove = onRemove(world, Player, (e) => console.log('un-playered', e))
-const stopSet = onSet(world, Health, (e, val) => console.log('health set', e, val))
-
-// Auto-unsubscribe via AbortSignal (since 0.2.0):
-const ac = new AbortController()
-onAdd(world, Position, (e) => trackEntity(e), { signal: ac.signal })
-// later, abort once and all observers attached to this signal are removed
-ac.abort()
-
-// Or the returned unsubscribe — both are idempotent and may be combined:
-stopAdd()
-stopRemove()
-stopSet()
-```
-
-Observers fire synchronously inside the mutation call. Use them for side effects that must happen at the exact moment of the change (debugging, replication). For batched UI updates, prefer reactive queries.
-
-**`onSet` is a low-level mutation hook**, not a reactive value-predicate query. It fires after `setComponent(world, eid, comp, value)` when the component is already present on the entity — `addComponent` does NOT trigger `onSet` (use `onAdd` for that path; an `addComponent` followed by `setComponent` fires both, in that order). `enterQuery` / `exitQuery` respond to structural component-set changes only; if you need a reactive "value crossed threshold" view, layer that in app code on top of `onSet`.
-
-### Command buffers — when and why
-
-The golden rule: **do not add or remove components on entities you're currently iterating over.** Doing so can skip or double-process entities because the archetype membership changes mid-walk. Use a command buffer to defer:
-
-```ts
-import { withCommandBuffer } from 'aiecsjs/commands'
-
-const damageSystem = (world) => {
-  const dying = defineQuery([Health])
-  withCommandBuffer(world, (cb) => {
-    forEachEntityIndexed(world, dying, (e, i, health) => {
-      if (health.hp[i] <= 0) cb.destroy(e)   // index the column with `i`, queue the packed `e`
-    })
-  })  // auto-flushes here
-  return world
-}
-```
-
-Or manually:
-
-```ts
-import { createCommandBuffer, flush } from 'aiecsjs/commands'
-
-const cb = createCommandBuffer(world)
-forEachEntity(world, q, (e) => { cb.remove(e, SomeTag) })
-flush(cb)
-```
-
-### Relations and hierarchies
-
-> The Relations API is **stable since 0.4.0**. The graph API (`defineRelation` / `addRelation` / `removeRelation` / `getRelationTargets` / `getRelationData`) and the built-in `ChildOf` relation are frozen for the 1.x track.
-
-```ts
-import { defineRelation, addRelation, ChildOf, getRelationTargets, getRelationData } from 'aiecsjs/relations'
-
-const Likes = defineRelation<{ since: number }>()
-addRelation(world, alice, Likes, bob, { since: 2020 })
-addRelation(world, alice, ChildOf, parent)
-
-const parentOfAlice = getRelationTargets(world, alice, ChildOf)
-const likedSince = getRelationData(world, alice, Likes, bob) // { since: 2020 }
-```
-
-Exclusive relations (one target only) and the `getRelationData` reader are stable as of 0.4.0. Wildcard relation queries and serialisation of relation graphs remain future work and are not part of the frozen surface.
-
-## API Reference
-
-Full machine-readable surface in [`api.json`](./api.json). Stability flags in [`STABILITY.md`](./STABILITY.md).
-
-### World — `aiecsjs`
-
-| Function | Signature | Stability |
-|---|---|---|
-| `createWorld` | `(options?: WorldOptions) => World` | stable |
-| `disposeWorld` | `(world: World) => void` | stable (since 0.2.0) |
-| `destroyWorld` | `(world: World) => void` | **deprecated** since 0.2.0 — alias of `disposeWorld`; scheduled for removal in 1.0 |
-| `resetWorld` | `(world: World) => void` | stable |
-| `getWorldSize` | `(world: World) => number` (alive count) | stable |
-| `getWorldCapacity` | `(world: World) => number` | stable |
-
-`WorldOptions`:
-```ts
-type WorldOptions = {
-  initialCapacity?: number       // default 1024
-  maxEntities?: number           // default 1_000_000
-  indexBits?: 20 | 24            // default 24 → 16M entities
-  generationBits?: 8 | 12 | 16   // default 8 → 256 recycles
-  buffer?: SharedArrayBuffer     // opt-in SAB backing
-  bufferByteOffset?: number      // when sharing one SAB across worlds
-}
-```
-
-### Entity — `aiecsjs`
-
-| Function | Signature | Stability |
-|---|---|---|
-| `createEntity` | `(world: World) => EntityId` | stable |
-| `destroyEntity` | `(world: World, eid: EntityId) => void` | stable |
-| `entityExists` | `(world: World, eid: EntityId) => boolean` | stable |
-| `getEntityIndex` | `(eid: EntityId) => number` | stable |
-| `getEntityGeneration` | `(eid: EntityId) => number` | stable (since 0.3.0) — returns the 8-bit generation field; uses default 24/8 layout |
-| `packEntity` | `(index: number, generation: number) => EntityId` | stable (since 0.3.0) — packs index + generation using default 24/8 layout |
-| `refOf` | `<T>(world: World, eid: EntityId) => EntityRef<T>` | stable (since 0.3.0) — creates ABA-safe ref; throws `EntityNotAliveError` if entity is dead |
-| `deref` | `<T>(world: World, ref: EntityRef<T>) => EntityId \| null` | stable (since 0.3.0) — returns live `EntityId` or `null` if stale/cross-world; never throws |
-| `aliveRef` | `<T>(world: World, ref: EntityRef<T>) => boolean` | stable (since 0.3.0) — boolean guard form of `deref`; never throws |
-| `EntityRef` | `interface EntityRef<T> { id: EntityId; worldId: number }` | stable (since 0.3.0) — opaque ABA-safe reference; in-memory only |
-| `EntityNotAliveError` | `class EntityNotAliveError extends Error { eid: number }` | stable (since 0.3.0) — thrown by `refOf` when entity is not alive |
-
-### Component — `aiecsjs`
-
-| Function | Signature | Stability |
-|---|---|---|
-| `defineComponent` | `<S extends SoASchema>(schema: S) => SoAComponent<S>` | stable |
-| `defineTag` | `() => TagComponent` | stable |
-| `defineObjectComponent` | `<T>(factory?: () => T) => AoSComponent<T>` | stable |
-| `addComponent` | `<C>(world, eid, c: C, init?) => void` | stable |
-| `removeComponent` | `<C>(world, eid, c: C) => void` | stable |
-| `hasComponent` | `<C>(world, eid, c: C) => boolean` | stable |
-| `getComponent` | `<C>(world, eid, c: C) => ComponentView<C>` | stable |
-| `setComponent` | `<C, V>(world, eid, c: C, v: V) => void` | stable |
-
-`Types`:
-```ts
-const Types = { i8, u8, i16, u16, i32, u32, f32, f64, eid, bool } as const
-```
-
-### Query — `aiecsjs`
-
-| Function | Signature | Stability |
-|---|---|---|
-| `defineQuery` | `(components: ComponentLike[] \| QueryDescriptor) => Query` | stable |
-| `runQuery` | `(world: World, q: Query) => readonly EntityId[]` | stable |
-| `forEachEntity` | `<Q>(world, q: Q, fn: (eid, ...cols) => void) => void` | stable |
-| `forEachEntityIndexed` | `<Q>(world, q: Q, fn: (eid, i, ...cols) => void) => void` | stable |
-| `iterQuery` | `(world, q) => IterableIterator<EntityId>` | stable |
-| `enterQuery` | `(q: Query) => Query` | stable |
-| `exitQuery` | `(q: Query) => Query` | stable |
-| `queryArchetypes` | `(world, q) => readonly Archetype[]` | experimental |
-
-### System — `aiecsjs`
-
-| Function | Signature | Stability |
-|---|---|---|
-| `pipe` | `<W, Ctx>(...systems) => System<W, Ctx>` | stable |
-| `System` (type) | `(world, ctx) => world` | stable |
-
-### Loop — `aiecsjs/loop`
-
-| Function | Signature | Stability |
-|---|---|---|
-| `createLoop` | `(opts) => { start(), stop() }` | stable |
-
-### Command Buffer — `aiecsjs/commands`
-
-| Function | Signature | Stability |
-|---|---|---|
-| `createCommandBuffer` | `(world) => CommandBuffer` | stable |
-| `flush` | `(cb: CommandBuffer) => void` | stable |
-| `withCommandBuffer` | `<R>(world, fn: (cb) => R) => R` | stable |
-
-### Observers — `aiecsjs/observers`
-
-| Function | Signature | Stability |
-|---|---|---|
-| `observe` | `(world, q, event, handler, opts?: { signal? }) => () => void` | stable |
-| `onAdd` | `(world, comp, handler, opts?: { signal? }) => () => void` | stable |
-| `onRemove` | `(world, comp, handler, opts?: { signal? }) => () => void` | stable |
-| `onSet` | `(world, comp, handler, opts?: { signal? }) => () => void` | stable; low-level mutation hook, not reactive |
-
-### Serialization — `aiecsjs/serialize`
-
-| Function | Signature | Stability |
-|---|---|---|
-| `serializeWorld` | `(world, opts?) => Uint8Array` | stable |
-| `deserializeWorld` | `(bytes, opts?) => World` | stable |
-| `toJSON` | `(world) => WorldSnapshot` | stable |
-| `fromJSON` | `(snap) => World` | stable |
-| `createDeltaSerializer` | `(world, opts?) => DeltaSerializer` | experimental |
-
-### Worker / SAB — `aiecsjs/worker`
-
-| Function | Signature | Stability |
-|---|---|---|
-| `transferableSnapshot` | `(world) => { buffer, meta }` | experimental |
-| `adoptSnapshot` | `(snap) => World` | experimental |
-| `attachWorld` | `(buffer, opts?) => World` | experimental |
-| `detachWorld` | `(world) => void` | experimental |
-
-### Relations — `aiecsjs/relations`
-
-| Function | Signature | Stability |
-|---|---|---|
-| `defineRelation` | `<T>(opts?) => Relation<T>` | stable |
-| `addRelation` | `(world, src, rel, tgt, data?) => void` | stable |
-| `removeRelation` | `(world, src, rel, tgt) => void` | stable |
-| `getRelationTargets` | `(world, src, rel) => readonly EntityId[]` | stable |
-| `getRelationData` | `<T>(world, src, rel, tgt) => T \| undefined` | stable (since 0.4.0) |
-| `ChildOf` (constant) | `Relation` | stable |
-
-### Utility — `aiecsjs`
-
-| Export | Type | Stability |
-|---|---|---|
-| `VERSION` | `string` | stable |
-| `IS_SAB_SUPPORTED` | `boolean` | stable |
-| `isWorld` | `(x: unknown) => x is World` | stable |
-| `isEntity` | `(world, x) => x is EntityId` | stable |
-
-## Performance
-
-### Storage model
-
-```
-World
-├── Archetype 0: [] (empty entities)
-├── Archetype 1: [Position]
-│   ├── entities:   Uint32Array  [e1, e2, e3, ...]
-│   └── columns:    Position.x: Float32Array, Position.y: Float32Array
-├── Archetype 2: [Position, Velocity]
-│   ├── entities:   Uint32Array  [e4, e5, ...]
-│   ├── columns:    Position.x, Position.y, Velocity.x, Velocity.y
-└── Archetype 3: [Position, Velocity, Health]
-    └── ...
-```
-
-A query for `(Position, Velocity)` matches archetypes 2 and 3 and walks each linearly. Each archetype's columns are contiguous `Float32Array`s — the JIT can vectorise the inner loop and the L1 cache hit rate is near 100%.
-
-### Cost model
-
-- **Iteration**: `O(matching archetypes × entities per archetype)` with effectively zero per-entity overhead after the archetype list is resolved. Resolution is amortised by query caching.
-- **Add / remove component**: `O(component count on entity)`. The entity row is copied from its source archetype's columns into the destination's. If you flicker a tag every frame on N entities, this is N × (column count) memory moves per frame.
-- **Query setup**: `O(component count)` at `defineQuery` time. Re-using the same component set returns the cached query.
-
-### Tips
-
-- Hoist `defineQuery` out of the hot loop. Same component set returns the same query object, but the lookup still costs a hash.
-- Prefer **bulk operations**: spawn 1000 entities by calling `createEntity` + `addComponent` in a tight loop; the archetype migration runs once per shape.
-- Group **frequently-toggled tags** into one stable component with a boolean field, instead of constantly adding/removing a tag — the latter triggers archetype migration.
-- For very hot inner loops, fetch each column once at the top of the system: `const px = Position.x; const vx = Velocity.x;` then index directly.
-
-### Reproducible micro-benchmark
-
-```ts
-import { createWorld, createEntity, addComponent, defineComponent, defineQuery, forEachEntityIndexed, Types } from 'aiecsjs'
-
-const Position = defineComponent({ x: Types.f32, y: Types.f32 })
-const Velocity = defineComponent({ x: Types.f32, y: Types.f32 })
-
-const world = createWorld({ initialCapacity: 100_000 })
-for (let i = 0; i < 100_000; i++) {
-  const e = createEntity(world)
-  addComponent(world, e, Position, { x: 0, y: 0 })
-  addComponent(world, e, Velocity, { x: 1, y: 1 })
-}
-
-const movers = defineQuery([Position, Velocity])
-const start = performance.now()
-for (let frame = 0; frame < 1000; frame++) {
-  forEachEntityIndexed(world, movers, (e, i, pos, vel) => {
-    pos.x[i] += vel.x[i]; pos.y[i] += vel.y[i]
-  })
-}
-console.log('ms per frame:', (performance.now() - start) / 1000)
-```
-
-### Disclaimer
-
-These tips are derived from public ECS benchmarks (noctjs/ecs-benchmark, ddmills/js-ecs-benchmarks) and the peer-reviewed C++ comparison by Cox, Williams, Vickers, Ward, and Headleand (CGVC 2025, [DOI 10.2312/cgvc.20251224](https://doi.org/10.2312/cgvc.20251224)). In renderer-heavy applications, ECS overhead is typically 1–2% of frame time (as observed by Felix Z on Meta's Project Flowerbed) — so the practical win from picking aiecsjs over a slower ECS is small unless your simulation is the bottleneck. Pick the library whose DX matches your workload.
-
-## Multi-threading Guide
-
-aiecsjs is **SharedArrayBuffer-ready**: a world's archetype columns can live in shared memory and a Worker can iterate them in parallel.
-
-### Capability detection
-
-```ts
-import { IS_SAB_SUPPORTED } from 'aiecsjs'
-if (!IS_SAB_SUPPORTED) {
-  console.warn('SAB unavailable; check COOP/COEP headers')
-}
-```
-
-In browsers, `SharedArrayBuffer` requires the page to be **cross-origin isolated**: serve with `Cross-Origin-Opener-Policy: same-origin` and `Cross-Origin-Embedder-Policy: require-corp`.
-
-### Main thread
-
-```ts
-const buffer = new SharedArrayBuffer(64 * 1024 * 1024)  // 64 MB
-const world = createWorld({ buffer })
-
-// populate world...
-
-const worker = new Worker(new URL('./sim-worker.ts', import.meta.url), { type: 'module' })
-worker.postMessage({ buffer, meta: transferableSnapshot(world).meta })
-```
-
-### Worker thread
-
-```ts
-// sim-worker.ts
-import { adoptSnapshot, defineComponent, defineQuery, forEachEntityIndexed, Types } from 'aiecsjs'
-
-const Position = defineComponent({ x: Types.f32, y: Types.f32 })
-const Velocity = defineComponent({ x: Types.f32, y: Types.f32 })
-
-self.onmessage = (msg) => {
-  const world = adoptSnapshot(msg.data)
-  const movers = defineQuery([Position, Velocity])
-  setInterval(() => {
-    forEachEntityIndexed(world, movers, (e, i, pos, vel) => {
-      pos.x[i] += vel.x[i]
-      pos.y[i] += vel.y[i]
-    })
-  }, 16)
-}
-```
-
-### Atomics and synchronisation
-
-Reads and writes to TypedArray columns inside a SAB are **not atomic by default**. For most game-loop work, the convention is: one writer thread per column (e.g. physics worker owns positions), readers see eventually-consistent data. If you need strict ordering, use `Atomics.load` / `Atomics.store`; you give up vectorisation in exchange.
-
-### Pitfalls
-
-- **AoS components are NOT SAB-shareable.** Workers see only SoA columns. Either keep AoS data on the main thread or replace with SoA equivalents.
-- **`createEntity` / `destroyEntity` from a Worker requires the worker to own the entity index.** Currently, attach worlds with `{ readOnly: true }` when the Worker should only mutate columns.
-- **No synchronisation primitives are baked into aiecsjs.** Use `Atomics.wait` / `Atomics.notify` yourself if you need barriers.
-
-## WebGPU Interop
-
-A SoA component's columns are TypedArrays — exactly the format `GPUQueue.writeBuffer` accepts. There is no "ECS on GPU" mode; the integration is one-directional (CPU writes, GPU reads).
-
-```ts
-const Position = defineComponent({ x: Types.f32, y: Types.f32 })
-// after populating the world ...
-
-const gpuBuffer = device.createBuffer({
-  size: Position.x.byteLength,
-  usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
-})
-
-// upload every frame, or only when archetypes change
-device.queue.writeBuffer(gpuBuffer, 0, Position.x)
-```
-
-### Caveats
-
-- **Archetype migration invalidates column references.** If an entity moves to a new archetype, `Position.x` now points to a different `Float32Array` for that entity. For stable GPU buffers, dedicate a single archetype to entities you upload (e.g. tag them with a `Renderable` component that never gets removed) or upload per-archetype.
-- **Write-back from GPU to ECS is not supported.** Read-only on the GPU side. If you need GPU-computed values back in CPU columns, map the buffer manually and write into the column.
-- **Non-goal: running ECS systems on the GPU.** aiecsjs does not generate compute shaders from systems. Use a dedicated GPU compute framework for that.
-
-## Serialization Guide
-
-### Binary save/load
-
-```ts
-import { serializeWorld, deserializeWorld } from 'aiecsjs/serialize'
-
-const bytes = serializeWorld(world)
-localStorage.setItem('save', btoa(String.fromCharCode(...bytes)))
-
-const restored = deserializeWorld(Uint8Array.from(atob(localStorage.getItem('save')!), c => c.charCodeAt(0)))
-```
-
-The binary format is **version-stamped**. Loading bytes from an older `aiecsjs` version returns a world if migration succeeds, throws otherwise. AoS components are stored as JSON inside the binary blob.
-
-### JSON save/load
-
-```ts
-import { toJSON, fromJSON } from 'aiecsjs/serialize'
-
-const snap = toJSON(world)            // human-readable
-const restored = fromJSON(snap)
-```
-
-Slower and larger than binary, but inspectable in DevTools.
-
-### Network delta
-
-For multiplayer, you want to send only what changed since last tick:
-
-```ts
-import { createDeltaSerializer } from 'aiecsjs/serialize'
-
-const delta = createDeltaSerializer(world, { components: [Position, Velocity, Health] })
-setInterval(() => {
-  const bytes = delta.capture()
-  ws.send(bytes)
-}, 50)
-
-// on the other side:
-const remoteDelta = createDeltaSerializer(remoteWorld)
-ws.onmessage = (e) => remoteDelta.apply(remoteWorld, new Uint8Array(e.data))
-```
-
-> ⚠️ `createDeltaSerializer` is `experimental` in 0.1; the wire format may change before 1.0.
-
-## Migration Guides
-
-Full tables in [`docs/MIGRATION.md`](https://github.com/islumina/aiecsjs/blob/main/docs/MIGRATION.md).
-
-### From bitECS 0.4
-
-| bitECS | aiecsjs |
-|---|---|
-| `createWorld()` | `createWorld()` |
-| `defineComponent({ x: Types.f32 })` | `defineComponent({ x: Types.f32 })` |
-| `addComponent(world, Comp, eid)` | `addComponent(world, eid, Comp, init?)` (arg order!) |
-| `removeComponent(world, Comp, eid)` | `removeComponent(world, eid, Comp)` |
-| `defineQuery([Comp])(world)` | `forEachEntity(world, defineQuery([Comp]), fn)` |
-| `enterQuery(query)` | `enterQuery(defineQuery([...]))` (no `world` arg) |
-| `pipe(s1, s2)(world)` | `pipe(s1, s2)(world, ctx)` (ctx threaded through) |
-
-Key mental shift: aiecsjs is **archetype-first**. Tag flicker (adding/removing a tag every frame) is more expensive than in bitECS. Group toggleable state into boolean fields instead.
-
-### From miniplex
-
-| miniplex | aiecsjs |
-|---|---|
-| `world.add({ position: {x, y}, velocity: {x, y} })` | `createEntity` + `addComponent` (per component) |
-| `world.with('position', 'velocity')` | `defineQuery([Position, Velocity])` |
-| `for (const e of query)` | `forEachEntity(world, query, fn)` |
-| `world.remove(entity)` | `destroyEntity(world, eid)` |
-| `world.queue.add(...)` | `withCommandBuffer(world, cb => cb.create() ...)` |
-
-Mental shift: components are **declared up front** in aiecsjs, not anonymous object shapes. The win is TypedArray performance + multi-thread compatibility.
-
-### From ECSY
-
-ECSY is [archived](https://github.com/ecsyjs/ecsy) as of April 2025. Migration is straightforward because both are archetype-style.
-
-| ECSY | aiecsjs |
-|---|---|
-| `class C extends Component { static schema = { x: Types.Number } }` | `defineComponent({ x: Types.f32 })` |
-| `class S extends System { execute(dt) { this.queries.foo.results.forEach(...) } }` | `const S = (world, dt) => { forEachEntity(world, foo, fn); return world }` |
-| `world.registerComponent(C)` | (implicit on `defineComponent`) |
-| `world.registerSystem(S)` then `world.execute(dt)` | `const tick = pipe(S1, S2); tick(world, dt)` |
-
-## For AI Agents
-
-This section is designed to be loaded as context by AI coding assistants. The same information is available in machine-readable form in [`llms.txt`](./llms.txt), [`llms-full.txt`](./llms-full.txt), and [`api.json`](./api.json).
-
-### Decision matrix
-
-| If you need...                                  | Use aiecsjs        | Use this instead         |
-|-------------------------------------------------|------------------|--------------------------|
-| Fastest iteration over 10k+ entities            | ✅                | —                        |
-| Plain JS object entities, no typed schema       | ❌                | miniplex                 |
-| Automatic system scheduling / parallelism       | ❌ (v0.1)        | becsy                    |
-| SAB-based main+worker setup                     | ✅                | —                        |
-| Hot reload, frequent entity churn (>50%/frame)  | works but slower | bitECS 0.4 (SparseSet)   |
-| Tiny bundle (< 3 kB)                            | ❌                | bitECS 0.4               |
-| TypeScript-first inference                      | ✅                | —                        |
-
-### Common patterns (copy-paste)
-
-**1. Spawn-and-move**
-
-```ts
-import { createWorld, createEntity, addComponent, defineComponent, defineQuery, forEachEntityIndexed, pipe, Types } from 'aiecsjs'
-
-const Position = defineComponent({ x: Types.f32, y: Types.f32 })
-const Velocity = defineComponent({ x: Types.f32, y: Types.f32 })
-
-const world = createWorld()
-for (let i = 0; i < 1000; i++) {
-  const e = createEntity(world)
-  addComponent(world, e, Position, { x: i, y: 0 })
-  addComponent(world, e, Velocity, { x: 0, y: 1 })
-}
-
-const movers = defineQuery([Position, Velocity])
-const move = (w, dt) => {
-  forEachEntityIndexed(w, movers, (e, i, p, v) => { p.x[i] += v.x[i] * dt; p.y[i] += v.y[i] * dt })
-  return w
-}
-pipe(move)(world, 0.016)
-```
-
-**2. Reactive UI via enter/exit query**
-
-```ts
-const visible = defineQuery([Renderable])
-const becameVisible = enterQuery(visible)
-const becameHidden = exitQuery(visible)
-
-const renderSync = (world) => {
-  forEachEntity(world, becameVisible, (e) => domLayer.mount(e))
-  forEachEntity(world, becameHidden, (e) => domLayer.unmount(e))
-  return world
-}
-```
-
-**3. Command buffer for safe deferred ops**
-
-```ts
-import { withCommandBuffer } from 'aiecsjs/commands'
-
-const reapDead = (world) => {
-  withCommandBuffer(world, (cb) => {
-    forEachEntity(world, deadQ, (e) => cb.destroy(e))
-  })
-  return world
-}
-```
-
-**4. SAB worker handoff**
-
-```ts
-// main.ts
-const buffer = new SharedArrayBuffer(16 * 1024 * 1024)
-const world = createWorld({ buffer })
-const worker = new Worker(new URL('./physics.ts', import.meta.url), { type: 'module' })
-worker.postMessage(transferableSnapshot(world))
-
-// physics.ts
-import { adoptSnapshot } from 'aiecsjs/worker'
-self.onmessage = (e) => {
-  const world = adoptSnapshot(e.data)
-  // ... iterate columns
-}
-```
-
-**5. Networked delta replay**
+## Quick Start
 
 ```ts
-import { createDeltaSerializer } from 'aiecsjs/serialize'
+const Position = defineComponent({ x: Types.f32, y: Types.f32 });
+const Velocity = defineComponent({ x: Types.f32, y: Types.f32 });
 
-const tx = createDeltaSerializer(world, { components: [Position, Velocity] })
-setInterval(() => ws.send(tx.capture()), 50)
+const world = createWorld({ initialCapacity: 1024 });
+const e = createEntity(world);
+addComponent(world, e, Position, { x: 0, y: 0 });
+addComponent(world, e, Velocity, { x: 1, y: 0 });
 
-// remote
-const rx = createDeltaSerializer(remoteWorld)
-ws.onmessage = (e) => rx.apply(remoteWorld, new Uint8Array(e.data))
+forEachEntity(world, [Position, Velocity], (entity) => {
+  const pos = getComponent(world, entity, Position);
+  const vel = getComponent(world, entity, Velocity);
+  pos.x += vel.x;
+  pos.y += vel.y;
+});
 ```
 
-### Anti-patterns
-
-1. **Mutating a `getComponent()` return value after the entity changes archetype.** The returned view points into the old archetype's TypedArray; it no longer represents this entity. Always re-fetch.
-2. **Adding or removing components during `forEachEntity` without a command buffer.** May skip or double-process entities. Use `withCommandBuffer`.
-3. **Holding `EntityId` across `destroyEntity`.** The ID may be recycled with a new generation. Always `entityExists(world, eid)` first.
-4. **Using AoS components inside a SAB-backed Worker world.** AoS storage is main-thread only. Replace with SoA.
-5. **Storing column references in closures longer than one frame.** Archetype migration replaces the TypedArray reference for an entity. Re-fetch each frame.
-6. **Calling `addComponent(world, Comp, eid)` (bitECS order).** aiecsjs is `(world, eid, Comp, init?)`. Different positional args.
+Use `defineTag()` for marker components and `defineObjectComponent()` when you need object references instead of TypedArray storage.
 
-### Stable invariants
+## Public Surface
 
-- `pipe(a, b, c)(world, ctx) === c(b(a(world, ctx), ctx), ctx)` — pipe is associative.
-- `pipe(...)` always returns the same `World` reference (mutations in place).
-- `defineQuery(X)` returns the same `Query` object for the same component set in the same module.
-- Entity ID `0` is reserved. `createEntity` never returns `0`.
-- `VERSION` exported from `'aiecsjs'` equals the published npm version.
-- SoA columns are TypedArrays indexed by the entity **index** (always in `[0, getWorldCapacity(world))`), never by the packed `eid` — the two differ once a slot is recycled. `forEachEntityIndexed` yields this index as its `i` argument (correct for any world layout). For the raw `forEachEntity` form on the default world layout (`indexBits: 24`) the index is `getEntityIndex(eid)`; for a world created with a non-default `indexBits`, `getEntityIndex` uses the default 24-bit mask and is **not** the column index — prefer `forEachEntityIndexed` (or `EntityRef` + `deref`) instead.
-- Component identity is **global** (created by `defineComponent`), but each component's storage is **per-world**.
+| Import | Purpose |
+| --- | --- |
+| `aiecsjs` | World/entity/component/query/system helpers, `Types`, refs, errors, `VERSION`. |
+| `aiecsjs/loop` | `createLoop()` for fixed-step style loops. |
+| `aiecsjs/commands` | `createCommandBuffer()`, `flush()`, `withCommandBuffer()` for deferred structural changes. |
+| `aiecsjs/observers` | `onAdd`, `onRemove`, `onSet`, `observe`. |
+| `aiecsjs/serialize` | Binary/JSON world snapshots and delta serializer. |
+| `aiecsjs/worker` | Transfer/adopt/attach helpers for worker snapshots. |
+| `aiecsjs/relations` | `defineRelation`, `ChildOf`, relation add/remove/read helpers. |
 
-### Glossary
-
-- **Archetype** — a unique combination of components; entities sharing components live in the same archetype table.
-- **SoA (Structure of Arrays)** — each component field is a separate TypedArray column. Default and preferred for hot data.
-- **AoS (Array of Structures)** — each component instance is a plain JS object. For heterogeneous or rarely-touched data.
-- **Bitmask** — a `Uint32Array` where each bit position represents one component; queries match by bitwise AND.
-- **Command buffer** — a queue of pending structural mutations applied at a defined sync point.
-- **Generation** — a counter incremented when an entity ID is recycled; prevents dangling references.
-
-### Runtime version detection
-
-```ts
-import { VERSION } from 'aiecsjs'
-if (VERSION.startsWith('0.')) {
-  // running an experimental version; expect API drift in 0.x
-}
-```
-
-### Stability contract
-
-See [`STABILITY.md`](./STABILITY.md). In short: imports from `aiecsjs` (root) are **stable** within 0.x minors. `aiecsjs/relations` is **stable** since 0.4.0; `aiecsjs/worker` is **experimental**. Anything in `aiecsjs/internal` is **internal** — do not import.
-
-### Telemetry / privacy
-
-aiecsjs ships **no telemetry**, **no network calls**, **no postinstall scripts**. Verify with `npm pack --dry-run` and inspect the tarball.
-
-### Citation for AI-generated code
-
-When you generate code that uses aiecsjs, include this comment at the top of the file:
-
-```ts
-// generated with aiecsjs@0.1.0 — https://github.com/islumina/aiecsjs
-```
+## Sharp Edges
 
-### Known LLM gotchas
+- Structural mutation during a query loop is allowed by the library, but app systems should prefer `withCommandBuffer()` when adding/removing/destroying entities from inside iteration.
+- Reactive query buffers are unbounded until drained. Poll and clear them every frame or event tick.
+- Query registration currently uses a global module cache; many worlds/components can make structural changes scan more query metadata than expected.
+- Exclusive relation cleanup scans relation capacity on destroy. Large sparse relation tables can make destroy cost visible.
+- Serialization restores capacity with safety clamps, but snapshots from untrusted sources should still be treated as hostile input.
+- Worker/SAB helpers depend on the runtime environment. Feature-detect `SharedArrayBuffer` and cross-origin isolation in browsers.
+- `pnpm lint` currently reports many `noExplicitAny` warnings. They are not release-blocking, but they add AI-review noise.
 
-- **aiecsjs is NOT bitECS.** Argument order for `addComponent` differs: aiecsjs uses `(world, eid, Component, init?)`; bitECS uses `(world, Component, eid)`.
-- **Index SoA columns with the masked index, NOT the packed `EntityId`.** The footgun is closed in code: prefer **`forEachEntityIndexed(w, q, (e, i, ...cols) => …)`**, which yields the masked slot index `i` (the correct subscript: `pos.x[i]`) alongside the packed `e`. The packed `e` is **not** a column index — it only equals the index while no slot has been recycled (generation 0); after any `destroyEntity` it reads the wrong/out-of-bounds slot. With the raw `forEachEntity` form, derive the index yourself: hoist `const i = getEntityIndex(e)` once per callback. Either way, use `e` for entity operations (`destroyEntity(w, e)`, `hasComponent`, `getComponent`, command buffers).
-- **A tag occupies a callback slot too.** `defineQuery([Tag, Position])` calls the callback as `(e, i, true, posCols)` under `forEachEntityIndexed` (`(e, true, posCols)` under `forEachEntity`) — the tag is passed as the literal `true`. Put tags **last** in the array (`defineQuery([Position, Tag])`) so data columns come first; or accept and ignore the trailing `true`. Binding `pos` to a tag slot makes `pos === true`, and `pos.x` throws.
-- **`forEachEntity` / `forEachEntityIndexed` are the fast path.** `runQuery` allocates an array; `for...of iterQuery(...)` allocates an iterator. In hot loops, use `forEachEntityIndexed` (or `forEachEntity` when you only need the `EntityId`).
-- **`defineObjectComponent` factory runs ONCE at definition**, not per entity. Mutate the entity's instance via `setComponent` / `getComponent`.
-- **The component reference is the storage handle.** `Position` is not a constructor — it's a value object that aiecsjs uses to address the right archetype columns.
+## AI Context
 
-## FAQ
-
-**Q: Is aiecsjs production-ready?**
-A: Not yet. 0.x is experimental. The API surface in `STABILITY.md` is the working contract; expect bug fixes. Target 1.0 is post-implementation hardening.
-
-**Q: Can I use class instances as components?**
-A: Yes, with `defineObjectComponent`. But AoS components are main-thread only and slower than SoA in iteration.
-
-**Q: How many components can I have?**
-A: aiecsjs uses multi-word bitmasks; the practical limit is set by `WorldOptions.maxComponents` (default 256). Raise it if needed.
-
-**Q: Does aiecsjs support hot reload?**
-A: Component identities are module-scoped. If you re-import a module under HMR, the component identity changes; the safe path is to call `resetWorld(world)` and re-spawn.
-
-**Q: Why not a class-based API?**
-A: Functional API tree-shakes better, has lower overhead, and is what LLMs reliably generate. The trade-off (no automatic scheduling) is acceptable for the target audience.
-
-**Q: Why isn't `aiecsjs` available on npm yet?**
-A: It will be on first stable publish. Until then, the docs are the contract.
-
-## Caveats and Known Limitations
-
-- **Max entity count** is capped by `indexBits` × `generationBits`. Default 24 + 8 = 16M entities × 256 recycles.
-- **No automatic system scheduler / parallel execution** in 0.1. Systems run in `pipe()` order on one thread (you can launch additional workers manually).
-- **Relations API (`aiecsjs/relations`) is stable since 0.4.0.** Wildcard relation queries and relation-graph serialisation remain future work.
-- **AoS components** not SAB-shareable across workers.
-- **Network delta serializer** wire format is experimental in 0.1; may change.
-- **WebGPU integration is one-way** (CPU → GPU). No compute-shader system generation.
-- **Limited dev-mode validation.** Production builds skip invariant checks for speed; dev builds (`process.env.NODE_ENV !== 'production'`) include argument-order and entity-existence checks.
-
-## Contributing
-
-aiecsjs is primarily AI-generated and maintained by a single author. Issue reports and small PRs welcome at [github.com/islumina/aiecsjs](https://github.com/islumina/aiecsjs). Large architectural changes — please open an issue first.
-
-## Changelog
-
-See [`CHANGELOG.md`](./CHANGELOG.md).
+- Short index: [`llms.txt`](llms.txt)
+- Full generated context: [`llms-full.txt`](llms-full.txt)
+- Stability contract: [`STABILITY.md`](STABILITY.md)
+- Current review backlog: [`REVIEW.md`](REVIEW.md)
+- Machine-readable API: [`api.json`](api.json)
+- Release history: [`CHANGELOG.md`](CHANGELOG.md)
 
 ## License
 
-[MIT](./LICENSE) © yshengliao
+MIT
 
 ---
 
@@ -972,359 +96,31 @@ See [`CHANGELOG.md`](./CHANGELOG.md).
 
 # Changelog
 
-All notable changes to `aiecsjs` are recorded in this file.
-
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+All notable changes to aiecsjs are summarized here. Detailed historical review notes live in Git history; this file keeps current release context compact.
 
 ## [Unreleased]
 
-### Planned
-
-- Add `pipeAsync` for async system composition.
-- Doc-test harness so README code blocks are mechanically verified.
-- Promote `aiecsjs/worker` to `stable` once true SAB shared-memory column aliasing is implemented.
-- Document the 8-bit generation wrap caveat in [STABILITY.md](./STABILITY.md): with the
-  default `generationBits=8`, a single slot recycled 256 times wraps back to its
-  starting generation, briefly re-opening the ABA window. Safe for v0.5 shmup
-  workloads (~5000 frame to wrap a single slot at 60 fps × ~1k destroys); high-churn
-  pools should set `createWorld({ indexBits: 16, generationBits: 16 })` (16 + 16 = 32 bits;
-  65 536 entities × 65 536 generations). See test
-  [tests/ref.test.ts](./tests/ref.test.ts) `generation wrap` describe block.
-
-## [0.5.6] - 2026-06-09
-
-### Changed
-
-- Docs: document `forEachEntity`'s packed-EntityId footgun and cross-link `forEachEntityIndexed` / `getEntityIndex` (closes downstream issue #3). No runtime change — the JSDoc reaches consumers through the generated `.d.ts` / `.d.cts`.
-
-## [0.5.5] - 2026-06-08
-
-### Changed
-
-- Project home migrated to the [`islumina`](https://github.com/islumina) GitHub org; published from there via npm trusted publisher (OIDC + SLSA provenance). Family-wide version alignment at `0.5.5`.
-
-### Internal
-
-- Test version assertions now derive from `package.json` instead of a hard-coded string, shrinking the release version-sync surface.
-
-## [0.5.3] - 2026-06-05
-
-### Added
-
-- Add `forEachEntityIndexed` yielding the masked index alongside the EntityId; closes the A1 packed-EntityId footgun in code (safe column iteration is now the default; `forEachEntity` unchanged).
-
-### Docs
-
-- **Correctness clarification — `forEachEntity`'s `e` is a packed `EntityId`, not a column index.** The column-iteration docs/examples now lead with `forEachEntityIndexed((e, i, ...cols) => …)`, indexing SoA columns with the yielded safe index `i` (`pos.x[i]`) — no manual masking (`README.md`, `README_ZHTW.md`, `docs/MIGRATION.md`, `docs/MIGRATION_ZHTW.md`, regenerated `llms-full.txt`). `forEachEntity` is documented as the form to use when you only need the `EntityId`; for that raw form, derive the subscript with `getEntityIndex(e)`. The old `pos.x[e]` pattern only worked while generation 0 (`e === getEntityIndex(e)`); after any `destroyEntity` recycles a slot it read an out-of-bounds column slot. Added a recycle regression test proving both the bug and the fix; `e`'s packed semantics are intentionally unchanged (it is still what you pass to `destroyEntity`/`hasComponent`/command buffers). Corrected the 0.1.0 storage note that implied `Position.x[eid]` indexes by the packed id.
-- **A2 (tag slot footgun).** Documented that each tag in `defineQuery([...])` occupies a callback slot passed as `true`, with a correct mixed-query example; recommend placing tags last so data columns come first. Docs-only — the callback arity is intentionally unchanged (changing it would shift data params for code that correctly writes `(e, _tag, pos)`; deferred to a future major). Column arguments remain `any`-typed.
-- **A3 (reactive-query lazy arm).** Documented that enter/exit buffers are armed lazily on first registration/read, and recommend defining reactive queries at module scope so the first `tick` already observes transitions.
-
-### Fixed
-
-- Synced the embedded `VERSION` constant (`src/version.ts`) to `0.5.2` to match `package.json` — the release gate asserts they are equal (`tests/utils.test.ts`). No API change; `dist` differs from 0.5.1 only by this version stamp.
-
-## [0.5.1] - 2026-06-02
-
-### Fixed
-
-- **`destroyEntity` now fires the reactive `enterQuery`/`exitQuery` surface.** Previously `destroyEntity` cleared the entity mask wholesale without notifying `recordEntityMaskChange`, so `exitQuery(...)` buffers stayed empty on destroy — asymmetric with both `removeComponent` (which notifies) and the query-targeted `observe(q, 'remove')` observer (which already fired on destroy). A destroyed entity now records an exit for every query it was matching. The pre-destroy mask is snapshotted at destroy entry so reentrant teardown handlers cannot suppress the exit. No public API change.
-- **`disposeWorld` / `destroyWorld` now release the large per-entity arrays.** The dispose path cleared archetypes/storages/queries but left `entityMask`, `entityArchetype`, `generations`, `freeList`, `componentBitFor`, `bitToQueries`, `queryArchetypeStamp`, and `sab` allocated. Because the public world handle's `capacity` getter closes over the internal state object, those arrays survived for the lifetime of the (typically retained) handle, defeating the "clear large buffers to help GC" intent. They are now released (typed arrays swapped to length-0 instances, Maps/arrays cleared, `sab` nulled). Post-dispose operations still throw as before — this is internal state, not public API.
-- **`unpackBinary` best-effort mode no longer leaks a raw `SyntaxError`.** Under `onUnknownVersion: 'best-effort'`, a malformed/garbled snapshot body reaching `JSON.parse` now surfaces a namespaced `aiecsjs:` error (with the original parse error attached as `cause`), consistent with the rest of the serializer. All existing length/bounds checks are unchanged.
-- **`DeltaSerializer.apply()` is now sound on a non-pristine / churned replica.** It previously treated the wire `eid` (a raw slot index, generation 0) as a packed id — throwing `addComponent on dead entity` once a replica slot's generation had advanced — and padded with `while (targetState.size < e.eid) createEntity()`, conflating the live count with a slot index and spawning phantom entities for holes in the source id space. `apply()` now materialises each entity at the source's slot via a new internal `ensureEntityAtSlot` primitive (reuse a live slot, reclaim a freed one, or advance the frontier), using the slot's current generation. No public API or wire-format change. Caveat: deltas carry only added/changed entities — entity/component removals are not propagated, so `apply()` remains additive.
-
-## [0.5.0] - 2026-05-30
-
-ai\*js family version-unify milestone — the seven packages align on a common `0.5.0`. **No runtime API change; `dist/` is byte-identical to 0.4.1 apart from the bumped `VERSION` string.**
-
-### Changed
-
-- **Migration-guide links repointed to GitHub blob URLs.** `docs/` became repository-only in 0.4.1 (dropped from the npm `files[]`), so the relative `./docs/MIGRATION*.md` links in `README.md` / `README_ZHTW.md` no longer resolved from the npm package page or the installed tarball. They now point at `https://github.com/islumina/aiecsjs/blob/main/docs/…` so consumers can follow them.
-- **Version aligned to the ai\*js family `0.5.0` unify milestone.** A coordinated family-wide minor bump; aiecsjs carries no source / public-API / relations change in this release.
-
-## [0.4.1] - 2026-05-29
-
-Consistency patch — packaging and documentation surface aligned to the ai*js family. **No runtime API change; `dist/` is byte-identical to 0.4.0 apart from the bumped `VERSION` string.**
-
-### Changed
-
-- **`package.json` packaging metadata aligned to family conventions**: `engines.node` `">=18"` → `">=18.0.0"`; `repository.url` gains the `git+` prefix (`git+https://github.com/islumina/aiecsjs.git`). Both are semantically equivalent — registry/tooling hygiene only.
-- **`files[]` trimmed to the family-minimal set plus `api.json`**: the npm tarball now ships `dist`, `README.md`, `README_ZHTW.md`, `LICENSE`, `llms.txt`, `llms-full.txt`, and `api.json`. `LICENSE` is now listed explicitly (it was already published via npm's automatic root-LICENSE inclusion). `STABILITY.md`, `CHANGELOG.md`, and `docs/` are no longer bundled — they remain in the repository and stay reachable from the README/`llms.txt` links on GitHub. `api.json` is **deliberately retained**: it is the machine-readable export manifest (stability + `since` per entry) that this package's "AI-readable docs" contract advertises, so it remains the tarball's stability surface for tooling.
-
-### Removed
-
-- **Redundant Traditional-Chinese doc duplicates**: `STABILITY_ZHTW.md` and `CHANGELOG_ZHTW.md` removed. The family keeps `README_ZHTW.md` as the single Traditional-Chinese entry point; per-export stability and the changelog are English-canonical (with `api.json` carrying the machine-readable stability surface). The plain-pipe language-switcher line atop `STABILITY.md` / `CHANGELOG.md` and the now-dangling `_ZHTW` references inside `README_ZHTW.md` were removed accordingly.
-
-## [0.4.0] - 2026-05-29
-
-### Added
-
-- **`getRelationData(world, source, rel, target)`**: new stable export on `aiecsjs/relations`. Returns the `data` payload attached via `addRelation`, or `undefined` when no such edge exists or no data was stored. Closes the write-only-data asymmetry present since 0.1: `addRelation` accepted a data argument but there was no corresponding public read path.
-
-### Changed
-
-- **`aiecsjs/relations` graduated from experimental to stable.** The graph API (`defineRelation`, `addRelation`, `removeRelation`, `getRelationTargets`, `getRelationData`) and the built-in `ChildOf` relation are now frozen for the 1.x track. See [`STABILITY.md`](./STABILITY.md) for the full stability contract, including the raw slot-keying ABA semantic.
-- **`aiecsjs/worker` remains experimental.** True SAB shared-memory column aliasing is deferred; the worker sub-path continues on snapshot-copy semantics.
-
-### Build & Tooling
-
-- **size-limit → `scripts/check-size.mjs`**: replaced the `size-limit` + `@size-limit/file` dev dependencies with a zero-dependency script that measures transitive chunk-closure gzip size per ESM entry. Required because `tsup splitting: true` (introduced in 0.3.1) makes each entry a thin re-export shell; the vanilla single-file measurement reported ~899 B for index when the true closure is ~7295 B. The new script resolves chunk imports recursively via BFS, sums per-file gzip, and enforces per-entry budgets.
-- **npm → pnpm**: migrated from `package-lock.json` to `pnpm-lock.yaml`. Added `"packageManager": "pnpm@9.12.3"` and `"publishConfig": { "access": "public" }`. CI and publish workflows updated to use `pnpm/action-setup@v6` + `pnpm install --frozen-lockfile`. `npm publish --provenance --access public` in the publish workflow is intentionally preserved (OIDC trusted publishing requires npm CLI, not pnpm publish).
-- **Coverage tests added + unreachable gaps documented**: new tests cover previously-unreachable paths in `serialize.ts`, `component.ts`, `query.ts`, and `loop.ts`. Thresholds updated to the honestly-achieved floor (statements 95 / branches 81 / functions 98 / lines 99). Unreachable-by-design gaps are now documented in `vitest.config.ts` with Chesterton rationale.
-
-## [0.3.1] - 2026-05-29
-
-### Fixed
-
-- **Packed EntityId signed-overflow for generation ≥ 128**: `createEntity` returned a negative number diverging from the unsigned value stored in archetype row arrays (`Uint32Array`), so query iteration (`runQuery`/`iterQuery`/`forEachEntity`) yielded an eid that failed `entityRow` lookups; `refOf`/`entityExists`/`deref` on a query-iterated high-generation entity misbehaved (`refOf` threw on a live entity). `packEid`/`packEntity` now normalise with `>>> 0`. No public-bundle behaviour change beyond the corrected eid representation (EntityId is opaque + in-memory-only).
-- **`toJSON` silently dropped high-generation entities** (gen ≥ 128 with default 8-bit generation): `toJSON` contained its own inline pack expression that produced a signed (negative) result, diverging from the unsigned key stored in `arch.entityRow`. The affected entity passed the archetype check but failed `entityRow.has()`, so it was omitted from every snapshot and `serializeWorld` call. Fixed by replacing the inline expression with the canonical `packEid` (which applies `>>> 0`). SPOT principle: one pack source of truth.
-- **Cross-subpath registry isolation** (`tsup splitting: false` → `splitting: true`): each compiled entry point (`dist/index.js`, `dist/serialize.js`, etc.) previously bundled its own private copy of `internal/world.ts`, including the module-scope `worldRegistry`. A world created via the core subpath was invisible to `serializeWorld`/`getRelationTargets`/`transferableSnapshot` imported from their respective subpaths, causing `world N is destroyed or unknown` at runtime. With `splitting: true`, esbuild extracts a shared chunk used by all entries; ESM and CJS are both verified by the new `scripts/check-dist-subpaths.mjs` smoke script.
-- **`getRelationTargets` returned raw index as `EntityId`** (gen always 0): `addRelation` stores the target as a raw slot index (`& indexMask`). The previous return path cast this raw index directly to `EntityId`, which is equivalent to a packed id with generation 0. For any target that had been recycled (gen > 0), callers received a stale id that failed `entityExists`, `entityRow` lookups, and component access. Fixed by re-packing each raw index against the current generation via `packEid` before returning.
-- **`resolveOptions` did not validate `indexBits + generationBits ≤ 32`**: the individual range checks (`indexBits ∈ [1, 24]`, `generationBits ∈ [0, 16]`) allowed combinations such as `indexBits=24, generationBits=16` (40 bits), where `gen << 24` silently overflowed and high-generation bits were lost. A sum check is now enforced with a clear error message. The `[Unreleased]` example corrected accordingly (`indexBits: 16, generationBits: 16` = 32 bits).
-
-### Known Limitations
-
-- **`createDeltaSerializer.apply` with a recycled target world**: `apply` uses the raw entity index from the delta snapshot as the `EntityId` directly. When the target world has already recycled any of those slots (generation > 0), component operations silently act on the wrong packed id. This is a known limitation of the experimental delta API; the common usage (delta → a fresh gen-0 render-mirror world) is unaffected. A proper raw-index-to-packed-id mapping is planned for 0.4. Avoid `apply` against a world that has previously destroyed entities.
-
-### Documentation
-
-- README / README_ZHTW updated to reflect the shipped 0.3.0 `EntityRef` API: the previous README still described EntityRef as "targeted for 0.3+" and `getEntityGeneration`/`packEntity` as experimental. Both files now correctly state EntityId has been packed since 0.3, and `EntityRef` / `refOf` / `deref` / `aliveRef` / `EntityNotAliveError` are all stable since 0.3.0. API table entries for these symbols added.
-
-### Build & Tooling
+## [0.5.8] - 2026-06-14
 
-- Coverage gate: `@vitest/coverage-v8` installed and wired into `prepublishOnly` (replaces `npm run test`) and CI. Thresholds: statements 95 / branches 80 / functions 97 / lines 98 — the achievable bar on pristine source. The branch figure honours the `?? 0` / `noUncheckedIndexedAccess` idiom on TypedArray reads (nullish-fallback branches unreachable by design); thresholds are raised only by adding tests, never by stripping defensive guards or scattering `/* v8 ignore */`.
-- `fast-check` property tests (`tests/properties.test.ts`): pack/unpack round-trip invariant (asserts `e >= 0` to guard the P0 regression) and ABA-deref always-null invariant.
-- Dispose three-cycle tests, error-path tests, and observer handler-throw behaviour documented in `tests/world.test.ts` / `tests/observers.test.ts`.
-- `scripts/check-dist-subpaths.mjs` (`npm run verify:dist`): post-build smoke test that imports `createWorld`+`createEntity` from the core subpath and calls `serializeWorld`, `addRelation`/`getRelationTargets`, and `transferableSnapshot` from their respective subpaths for both ESM (`dist/*.js`) and CJS (`dist/*.cjs`). Wired into `prepublishOnly` (after `build`) and CI.
+- Changed: exclusive-relation destroy cleanup now clears incoming edges in O(incoming) via a reverse index instead of scanning the full relation capacity per destroy. Behaviour is unchanged; large sparse relation tables no longer pay a per-destroy capacity scan.
+- Changed: reduced `noExplicitAny` lint warnings in source (154 to 140) with no behaviour change.
+- Documentation-only slimming pass across README, stability notes, review backlog, and LLM context. Reactive query world-local indexing remains a deferred follow-up (design note in the review backlog).
 
-## [0.3.0] - 2026-05-29
+## [0.5.7] - 2026-06-10
 
-### Added (API)
+- Hardened serialization restore capacity and hostile snapshot handling.
+- Fixed query iteration safety around archetype size changes.
+- Clarified worker snapshot buffer types and runtime validation boundaries.
+- Regenerated LLM context from the canonical docs.
 
-- **`EntityRef<T>`** — ABA-safe entity reference. `refOf(world, eid)` builds one;
-  `deref(world, ref)` returns the entity id when still alive (generation match)
-  or `null` otherwise; `aliveRef(world, ref)` is the boolean guard form. Phantom
-  type `T` lets callers distinguish ref kinds (e.g. `EntityRef<'bullet'>`) without
-  runtime cost. Refs are in-memory only — not serializable across worker / disk.
-- **`EntityNotAliveError`** — thrown by `refOf` when the entity is dead or invalid.
-  `deref` / `aliveRef` never throw.
+## Older releases
 
-### Changed
-
-- **`EntityId` now packs index + generation** into a single 32-bit number
-  `(generation << indexBits) | index` (default `indexBits=24, generationBits=8`).
-  `EntityId` remains opaque per STABILITY contract; the layout is implementation
-  detail. **Migration note**: do not compare `EntityId` numbers directly
-  (`eid === 42` will break across slot recycles); use
-  `getEntityIndex(eid)` for index comparison or `refOf(world, eid).id` for
-  identity matching that survives slot reuse.
-- **`getEntityGeneration` / `packEntity` graduate to `stable`** (were `experimental`
-  since 0.2.0). Both now return real values. These functions use default 24/8 bit
-  layout; for non-default `createWorld({ indexBits, generationBits })`, use
-  `EntityRef` and `deref` instead of manual unpacking.
-
-### Fixed
-
-- **ABA bug on entity slot recycle**: previously `entityExists` and `isAliveInternal`
-  only checked archetype membership; a stale `EntityId` pointing at a recycled slot
-  would silently report alive. With packed generation + `deref` generation match,
-  stale refs now correctly invalidate.
-- **`destroyEntity` generation wrap mask aligned with `options.generationBits`**
-  (was hard-coded `& 0xffff`). The mask now correctly uses
-  `state.options.generationMask`, fixing inconsistency for non-default
-  `generationBits` values.
-
-### Documentation
-
-- `onSet` JSDoc clarifies that `addComponent` does NOT trigger `onSet`, and
-  direct writes to column views returned by `getComponent` (e.g. `col.x[idx] = 5`)
-  also do NOT trigger `onSet`. Only `setComponent` on an already-present
-  component fires the callback. Anti-pattern example included.
-
-### Compatibility
-
-- `EntityId` layout change is **not** breaking at the type system level (opaque
-  branded number), but consumers who relied on `eid === N` direct comparison
-  will need to migrate (see Migration note above).
-- All existing `stable` exports unchanged.
-- `aiecsjs/worker` snapshot wire format unchanged (still uses raw indices).
-- `aiecsjs/serialize` wire format unchanged.
-
-### Build & tooling
-
-- `VERSION` constant bumped to `0.3.0`.
-
-## [0.2.1] - 2026-05-28
-
-### Security
-
-- **Resolve two Dependabot moderate advisories** on the transitive dev-only graph by upgrading `vitest` 1.6.0 → 4.1.7. Adds `vite` 8.0.14 as a direct devDependency to satisfy vitest 4's peer range (`^6 || ^7 || ^8`). These are dev-only — runtime surface unchanged.
-  - [GHSA-67mh-4wv8-2f99](https://github.com/advisories/GHSA-67mh-4wv8-2f99) `esbuild <=0.24.2` CORS development server data leak (fixed in 0.25.0).
-  - [GHSA-4w7w-66w2-5vf9](https://github.com/advisories/GHSA-4w7w-66w2-5vf9) `vite <=6.4.1` path traversal in optimized deps `.map` handling (fixed in 6.4.2 / 7.3.2 / 8.0.5).
-
-### Changed
-
-- **README opening unified across the ai*js family**: five-badge shields row (npm + CI + License + AI Generated + 繁體中文/English), one-line tagline as blockquote, ecosystem footer linking to the other two packages. Replaces the previous mixed style (text language switcher + 5 ad-hoc badges).
-- **`VERSION` constant bumped to 0.2.1** ([src/version.ts](src/version.ts)) so `world.version` and snapshot meta reflect this release.
-
-Runtime surface unchanged. Production bundles are byte-identical to 0.2.0.
-
-## [0.2.0] - 2026-05-28
-
-### Fixed (correctness + security)
-
-- **Prototype-pollution hardening in AoS `writeInitial`** ([src/internal/component.ts](src/internal/component.ts)): replaced `Object.assign(inst, initial)` with an explicit own-key copy that filters `__proto__` / `constructor` / `prototype`. Closes a path where a malicious `JSON.parse` payload reaching `addComponent` / `setComponent` / `fromJSON` / `deserializeWorld` could clobber the per-instance prototype.
-- **Observer dispatch is now safe against unsubscribe-during-iteration** ([src/observers.ts](src/observers.ts)): every `fire*` walks a snapshot of `state.observers` (`Array.from(...)` + `includes` guard) so a handler that calls its own returned disposer no longer skips sibling observers in the same fire round.
-- **`removeComponent` writes the new entity mask BEFORE firing observers** ([src/internal/component.ts](src/internal/component.ts)): query-targeted `remove` observers read `state.entityMask` to decide if the entity left the matching set; with the previous ordering the bit was still set during dispatch and the remove never fired. Brings `removeComponent` in line with `addComponent`'s "mutate then fire" order.
-- **`destroyEntity` now emits query-targeted `remove` events** ([src/observers.ts](src/observers.ts) `dispatchDestroyObservers`): in addition to per-component `onRemove`, the destroy hook now walks query observers and fires `remove` for any query the entity was matching pre-destroy. `wasMatch` is computed against a **snapshot of the pre-destroy mask** (not live `state.entityMask`) so a Phase 1 reentrant handler that mutates the entity's mask cannot suppress query removes in Phase 2 (regression caught by the round-2 review).
-- **`deserializeWorld` / `attachWorld` / `adoptSnapshot` binary length fields are bounds-checked** ([src/serialize.ts](src/serialize.ts)): `verLen` and `jsonLen` carry explicit `off + len <= bytes.length` assertions and a 64 MiB cap. `attachWorld` and `adoptSnapshot` ([src/worker.ts](src/worker.ts)) both carry SECURITY JSDocs that document the trust boundary expectation for SAB / TransferableSnapshot transports.
-
-### Added (API)
-
-- **`disposeWorld(world)`** — new export that aliases `destroyWorld`. Aligns with the ai*js ecosystem `dispose()` convention (`aifsmjs.Runtime.dispose`, `aibridgejs.Bridge.dispose`). Prefer this name in new code; `destroyWorld` is retained as a deprecated alias and is scheduled for removal in 1.0.
-- **`{ signal?: AbortSignal }` on every observer**: `onAdd`, `onRemove`, `onSet`, and `observe` now accept an options object. When the signal aborts, the observer auto-unsubscribes. The returned unsubscribe function remains valid and idempotent. New exported type `ObserverOptions` documents the shape. This closes a long-running gap noted in the AI ecosystem audit — long-lived observers on user-controlled lifecycles (UI components, async pipelines) no longer require manual cleanup wiring.
-
-### Changed (stability)
-
-- `getEntityGeneration` and `packEntity` re-classified from `stable` → `experimental` in `STABILITY.md` and `api.json`. In 0.1 these returned `0` / identity and that has not changed — the relabel honestly admits the deferred encoding work. Real values arrive when ABA-safe `EntityRef` lands.
-- `destroyWorld` re-classified from `stable` → `deprecated`. Behaviour unchanged; the deprecation is the API-naming alignment described above. Use `disposeWorld` instead.
-
-### Documentation
-
-- `onSet` now carries a JSDoc and README paragraph clarifying that it is a **low-level mutation hook**, not a reactive value-predicate query. `enterQuery` / `exitQuery` continue to be the structural-change surface; reactive value tracking remains an explicit non-goal of the core.
-- README observer section gains an `AbortController`-based unsubscribe example.
-
-### Build & tooling
-
-- Added [Biome](https://biomejs.dev/) lint + format (`biome.json`, `npm run lint`, `npm run format`). Brings parity with `aifsmjs` and `aibridgejs` and surfaces `noExplicitAny` warnings in legacy `src/internal/*` for follow-up cleanup.
-- Added `scripts/verify-exports.mjs` and the `npm run verify:exports` script; gates that every `package.json#exports` entry has a real file in `dist/`. Wired into `prepublishOnly`.
-- New `CONTRIBUTING.md` with the same shape used by `aifsmjs` (quick start, scope policy, release flow).
-
-### Compatibility
-
-This release is **non-breaking at runtime**. All existing code that called `destroyWorld(world)`, registered observers without options, or read `getEntityGeneration` continues to work. The stability label change is documentation-only.
-
-## [0.1.4] - 2026-05-28
-
-Docs-only release. Adds a cross-package integration section pointing at the `aibridgejs` JSON envelope contract; no source code changes.
-
-### Documentation
-
-- README and README_ZHTW gained an "Integration with aibridgejs" section explaining that `bridge.call` / `bridge.emit` enforce JSON-safe payloads and silently drop `Date`, `Map`, `Set`, and class instances. The correct shape for streaming world state across the bridge is `toJSON(world)` (or `serializeWorld(world)` wrapped in a JSON envelope) before emitting, not `getComponent(...)` direct. See [aiecsjs README · Integration with aibridgejs](README.md#integration-with-aibridgejs).
-- Verified via the `aijs-integration-smoke` companion project: every named export from `aifsmjs@0.1.2`, `aibridgejs@0.1.3`, and `aiecsjs@0.1.3` can coexist in a single TypeScript module with zero identifier collisions under `tsc --noEmit --strict`.
-
-## [0.1.3] - 2026-05-28
-
-A "no known silent bugs" release. Two correctness fixes, one hot-path allocation removal, and a small batch of style cleanups. No public API behaviour changes; `_getWorldState` is removed from the root export (was undocumented, unused by every sub-path, leading underscore signalled internal).
-
-### Fixed
-
-- `aiecsjs/relations` relation data store no longer keys edges by `srcEid * worldCapacity + tgtEid`. After the world grew, the same `(src, tgt)` pair computed a different key and earlier entries became orphaned. Storage is now a nested `Map<srcEid, Map<tgtEid, data>>`, independent of capacity. The cleanup hook on `destroyEntity` was updated to match. v0.1 has no public retrieve API so the bug was user-invisible, but it would have surfaced the moment a retrieve surface landed in 0.2.
-- Per-world resolved query bitmasks no longer live on the module-global `QueryInternal`. When the same `defineQuery(...)` handle was used by two worlds whose component registration orders differed, the second world's per-world mask overwrote the first world's, and `runQuery` silently returned wrong rows in world A. Masks now live in `WorldState.queryMasks: Map<queryId, QueryMaskBundle>`, isolated per world. Regression test in `tests/multi-world.test.ts` exercises the cross-order scenario.
-
-### Changed (internal)
-
-- Observer dispatch (`dispatchQueryObservers`) no longer allocates a temporary `Uint32Array` on every mutation event. Added `matchesEntityMask` helper in `bitmask.ts` that reads directly from `state.entityMask` at a base offset.
-- Shared bit-iteration extracted as `forEachSetBit(mask, base, words, fn)` in `bitmask.ts`. `clearAllEntityStorages` (`component.ts`) and `dispatchDestroyObservers` (`observers.ts`) now share that single implementation instead of inlining the same `word & -word` / `Math.clz32` pattern three times.
-- `state.generations[idx]` is written without an `as any` cast. `Uint8Array | Uint16Array` already supports indexed read/write.
-- Removed the `void oldCap` no-op from `growEntityArrays`.
-- Removed `_getWorldState` from the root `aiecsjs` export. Sub-paths (`aiecsjs/serialize`, `aiecsjs/worker`) already import `getWorldState` directly from the internal module; the leading-underscore root re-export had no consumer.
-
-### Planned for 0.3
-
-- Promote `aiecsjs/relations` and `aiecsjs/worker` to `stable`.
-- Stabilize the network delta wire format.
-- Add automated benchmark suite committed to repo.
-
-### Planned for 1.0
-
-- API freeze for the 1.x line.
-- Drop the experimental status label.
-
-## [0.1.2] - 2026-05-28
-
-CI/CD smoke-test release. No user-facing source or behavioural changes since 0.1.1; this bump exists solely to validate the tag-triggered publish workflow (see `.github/workflows/publish.yml`) end-to-end against the npm registry with provenance attestation.
-
-### Build & tooling
-
-- Confirmed that pushing a `v*.*.*` tag triggers `.github/workflows/publish.yml`, runs `prepublishOnly` (typecheck + tests + build + size budget), and publishes to npm with sigstore provenance.
-
-## [0.1.1] - 2026-05-28
-
-The "documentation honesty + test backstop" release. No new public APIs; this is the version of 0.1.0 that ships with the public surface, the documentation, and the test coverage in agreement.
-
-### Fixed
-
-- `destroyEntity` now clears the SoA columns and undefines the AoS slots that the destroyed entity owned. Previously only the entity mask was cleared, leaving stale data at the slot visible to debug snapshots and the serialisation path. Public `hasComponent` / query behaviour was already correct, so user-visible behaviour is unchanged; this closes the gap surfaced by the new `destroyEntity zeroes the destroyed entity’s SoA slot` test.
-
-### Changed (docs hygiene)
-
-- README and STABILITY now describe `aiecsjs/worker` honestly as a snapshot-copy transport for 0.1; true shared columns remain a 0.2 target. README description and `package.json` description updated accordingly.
-- README clarifies that 0.1 `EntityId` is a bare slot index; internal generation is tracked for slot reuse but not encoded in the ID. ABA-safe `EntityRef` is on the 0.2 roadmap.
-- Sub-paths (`loop` / `commands` / `observers` / `serialize` / `worker` / `relations`) re-positioned in STABILITY as utility / adapter sub-paths; the root `aiecsjs` is the stable core surface. Tree-shakers should drop any sub-path the app does not import.
-- README adds a "What aiecsjs does NOT do" section listing explicit non-goals (system scheduler, render binding, physics, network replication, value-predicate reactive queries, prefab/inheritance).
-- Language version filenames renamed from `*.zh-TW.md` to `*_ZHTW.md`. Cross-links, `llms.txt`, and `package.json` `files` updated. Future language variants follow the same uppercase ISO 639-1 pattern.
-- Removed emoji from documentation prose (language switchers, status banners).
-
-### Build & tooling
-
-- tsup build now runs with `minify: true`.
-- `size-limit` added as a dev dependency; per-export gzip budgets enforced via `npm run size`. Current measurements: core 5.49 kB, all sub-paths combined 12.6 kB gzip.
-- GitHub Actions CI workflow added: typecheck → test → build → size check on push and PR to `main`.
-- `prepublishOnly` now runs typecheck, tests, build, and the size budget gate before allowing publish.
-
-### Tests
-
-- Test count increased from 84 to 140. New file `tests/internal/bitmask.test.ts` covers the multi-word bitmask helpers in isolation (27 cases including `matches` truth table). New file `tests/multi-world.test.ts` covers per-world isolation when the same component is reused. Existing files gained: naive linear-filter cross-check against `runQuery` for all clause combinations, archetype migration boundary path, query mid-traversal stability and lazy cache behaviour, SoA field clear assertions on both `removeComponent` and `destroyEntity`, SoA vector-length round trip, `maxEntities` / `maxComponents` boundary throws, observer fan-out for destroy across multiple components, `onSet` value content, query observer ignores unrelated mutation, relation source-side destroy cleanup, exclusive relation storage resize, worker `readOnly` rejects add / remove / destroy, serialize `options.components` filter, `onUnknownVersion: throw | best-effort` paths, command buffer placeholder resolves into a queryable entity, slot-reuse limitation made explicit. Loop tests rewritten on top of `vi.useFakeTimers({ toFake: ['performance', ...] })` for deterministic dt validation.
-
-## [0.1.0] - 2026-05-27
-
-**Initial release.** All 50 documented exports across 7 modules are implemented and covered by 84 passing Vitest behaviour tests. Built with tsup to dual ESM + CJS, ships `.d.ts` declarations and source maps.
-
-### Implementation notes
-
-- **Storage**: world-level TypedArray columns per SoA component field, sized to world capacity. Archetypes track entity membership (a `Uint32Array entities[]`) but do not own column data. This makes archetype migration O(1) and lets columns be indexed by the entity **index** (`getEntityIndex(eid)`) directly, without per-archetype indirection. (In 0.1 `EntityId` *was* the index, so `Position.x[eid]` worked literally; since 0.3 packs a generation into the id, hot-loop code must index with `Position.x[getEntityIndex(eid)]` — the raw packed id is no longer the column offset.) Trade-off: iteration over archetypes reads columns at potentially non-contiguous offsets; for hot data this stays in L1.
-- **EntityId is unversioned in 0.1**: `EntityId` is the entity index. Generation is tracked internally for slot reuse but not encoded in the ID. `getEntityIndex` / `getEntityGeneration` / `packEntity` are identity helpers. ABA-safe references via a separate `EntityRef` type are planned for 0.2.
-- **Bitmask queries**: multi-word Uint32 masks, default 8 words (256 components). Per-world bit allocation, global component identity.
-- **Worker / SAB**: 0.1 implements snapshot-copy semantics (serialize-into-SAB on send, deserialize-on-adopt) rather than true shared-memory column aliasing. The API surface matches the documented contract; true shared columns ship in 0.2.
-- **Binary serialization**: a JSON payload wrapped in a 4-byte magic + version header. Compact binary column encoding is planned for 0.2.
-
-### Added
-
-- `README.md` (English) and `README_ZHTW.md` (Traditional Chinese) with quick start, guide, API reference, performance notes, multi-threading guide, WebGPU interop section, serialization guide, migration guides, and "For AI Agents" section.
-- `llms.txt` — Jeremy Howard format AI-discovery file.
-- `llms-full.txt` — Single-file complete reference for LLM consumption.
-- `api.json` — Machine-readable export manifest with stability and `since` fields on every entry.
-- `STABILITY.md` and `STABILITY_ZHTW.md` — Per-export stability contract.
-- `docs/MIGRATION.md` and `docs/MIGRATION_ZHTW.md` — Migration guides from bitECS 0.4, miniplex 2.0, and ECSY.
-
-### API surface declared
-
-- Core: `createWorld`, `destroyWorld`, `resetWorld`, `getWorldSize`, `getWorldCapacity`.
-- Entity: `createEntity`, `destroyEntity`, `entityExists`, `getEntityIndex`, `getEntityGeneration`, `packEntity`.
-- Component: `defineComponent`, `defineTag`, `defineObjectComponent`, `addComponent`, `removeComponent`, `hasComponent`, `getComponent`, `setComponent`, `Types`.
-- Query: `defineQuery`, `runQuery`, `forEachEntity`, `iterQuery`, `enterQuery`, `exitQuery`, `queryArchetypes` (experimental).
-- System: `pipe`.
-- Subpath `aiecsjs/loop`: `createLoop`.
-- Subpath `aiecsjs/commands`: `createCommandBuffer`, `flush`, `withCommandBuffer`.
-- Subpath `aiecsjs/observers`: `observe`, `onAdd`, `onRemove`, `onSet`.
-- Subpath `aiecsjs/serialize`: `serializeWorld`, `deserializeWorld`, `toJSON`, `fromJSON`, `createDeltaSerializer` (experimental).
-- Subpath `aiecsjs/worker` (experimental): `transferableSnapshot`, `adoptSnapshot`, `attachWorld`, `detachWorld`.
-- Subpath `aiecsjs/relations` (experimental, not implemented): `defineRelation`, `addRelation`, `removeRelation`, `getRelationTargets`, `ChildOf`.
-- Utility: `VERSION`, `IS_SAB_SUPPORTED`, `isWorld`, `isEntity`.
-
-### Known limitations in 0.1
-
-- `aiecsjs/relations` and `aiecsjs/worker` are implemented but tagged experimental; API may shift.
-- Network delta wire format is JSON-based; binary patch format is planned for 0.2.
-- AoS components are main-thread only; cannot be shared via SharedArrayBuffer.
-- No automatic system scheduler / parallel execution.
-- Worker/SAB uses snapshot-copy in 0.1 rather than true shared-memory aliasing.
-- EntityId is unversioned; ABA-safe references arrive with `EntityRef` in 0.2.
-
-[Unreleased]: https://github.com/islumina/aiecsjs/compare/v0.5.6...HEAD
-[0.5.6]: https://github.com/islumina/aiecsjs/compare/v0.5.5...v0.5.6
-[0.5.1]: https://github.com/islumina/aiecsjs/compare/v0.5.0...v0.5.1
-[0.1.0]: https://github.com/islumina/aiecsjs/releases/tag/v0.1.0
+- `0.5.6` through `0.5.1` focused on release hygiene, docs accuracy, ECS safety fixes, and family SLSA/provenance metadata.
+- `0.5.0` aligned the package with the broader ai*js family release line.
+- `0.4.x` added relations and declared the 1.0-track stability policy.
+- `0.3.x` expanded serialization, worker/SAB helpers, command buffers, observers, and docs.
+- `0.2.x` hardened entity/component correctness and security-sensitive registry behavior.
+- `0.1.x` introduced the root world/entity/component/query API and TypedArray SoA storage.
 
 ---
 
@@ -1332,158 +128,35 @@ The "documentation honesty + test backstop" release. No new public APIs; this is
 
 # Stability Contract
 
-This document is the per-export stability promise for `aiecsjs`. It is the contract AI tools and human users can rely on when pinning versions and writing import paths.
-
-## Policy
-
-aiecsjs follows [semver](https://semver.org/). Within the **0.x** series:
-- **`stable`** exports do not change in breaking ways across minor versions (e.g. 0.1 → 0.2).
-- **`experimental`** exports may change shape, name, or behaviour in any minor release. Pin the exact version if you depend on them.
-- **`internal`** is not part of the API. May change in any patch release. Do not import.
-- **`deprecated`** still works as documented but is scheduled for removal. The deprecation notice states the target version.
-
-At **1.0**, the `stable` surface freezes for the entire 1.x series.
-
-The full machine-readable export list lives in [`api.json`](./api.json), with the `stability` and `since` fields on every entry.
-
-## By module
-
-The **root** entry (`aiecsjs`) is the stable core: world, entity, component, query, system. Everything under a sub-path (`aiecsjs/<name>`) is a **utility or adapter sub-path** — useful but non-essential, decoupled from the core, and importable a la carte. Tree-shakers should be able to drop any sub-path the application does not import.
-
-### `aiecsjs` (root core)
-
-| Export | Stability | Since | Notes |
-|---|---|---|---|
-| `createWorld` | stable | 0.1.0 | |
-| `disposeWorld` | stable | 0.2.0 | Alias for `destroyWorld`; aligns with the ai*js ecosystem `dispose()` convention. Prefer this name in new code. |
-| `destroyWorld` | **deprecated** | 0.1.0 | Use `disposeWorld` instead. Scheduled for removal in 1.0. |
-| `resetWorld` | stable | 0.1.0 | |
-| `getWorldSize` | stable | 0.1.0 | |
-| `getWorldCapacity` | stable | 0.1.0 | |
-| `createEntity` | stable | 0.1.0 | |
-| `destroyEntity` | stable | 0.1.0 | |
-| `entityExists` | stable | 0.1.0 | |
-| `getEntityIndex` | stable | 0.1.0 | |
-| `getEntityGeneration` | stable | 0.3.0 | Returns real generation value packed into EntityId (default 24-bit index, 8-bit generation). For non-default `createWorld({ indexBits, generationBits })`, use `EntityRef` + `deref` instead. |
-| `packEntity` | stable | 0.3.0 | Packs index + generation into an EntityId using default 24/8 bit layout. For non-default bit sizes, use `EntityRef` + `deref` instead. |
-| `refOf` | stable | 0.3.0 | Throws `EntityNotAliveError` for dead entity. |
-| `deref` | stable | 0.3.0 | Returns null for stale / cross-world refs; never throws. |
-| `aliveRef` | stable | 0.3.0 | Boolean guard form of `deref`; never throws. |
-| `EntityRef` (type) | stable | 0.3.0 | In-memory only; not serializable. |
-| `EntityNotAliveError` | stable | 0.3.0 | Thrown only by `refOf`. |
-| `defineComponent` | stable | 0.1.0 | |
-| `defineTag` | stable | 0.1.0 | |
-| `defineObjectComponent` | stable | 0.1.0 | AoS components are main-thread only; not SAB-shareable. |
-| `addComponent` | stable | 0.1.0 | Argument order `(world, eid, component, init?)` is final. |
-| `removeComponent` | stable | 0.1.0 | |
-| `hasComponent` | stable | 0.1.0 | |
-| `getComponent` | stable | 0.1.0 | |
-| `setComponent` | stable | 0.1.0 | |
-| `Types` | stable | 0.1.0 | Constant map; field names are part of the contract. |
-| `defineQuery` | stable | 0.1.0 | |
-| `runQuery` | stable | 0.1.0 | |
-| `forEachEntity` | stable | 0.1.0 | |
-| `iterQuery` | stable | 0.1.0 | |
-| `enterQuery` | stable | 0.1.0 | |
-| `exitQuery` | stable | 0.1.0 | |
-| `queryArchetypes` | **experimental** | 0.1.0 | `Archetype.id` is opaque-internal; the shape of `Archetype` may grow. |
-| `pipe` | stable | 0.1.0 | |
-| `VERSION` | stable | 0.1.0 | |
-| `IS_SAB_SUPPORTED` | stable | 0.1.0 | |
-| `isWorld` | stable | 0.1.0 | |
-| `isEntity` | stable | 0.1.0 | |
-
-### `aiecsjs/loop` (utility sub-path)
-
-Fixed-timestep accumulator loop. Drop this sub-path if you already drive frame updates yourself (PixiJS `Ticker`, requestAnimationFrame, server-side simulation).
-
-| Export | Stability | Since | Notes |
-|---|---|---|---|
-| `createLoop` | stable | 0.1.0 | |
-
-### `aiecsjs/commands` (utility sub-path)
-
-Deferred structural mutations so systems can mutate world structure mid-iteration without invalidating queries.
-
-| Export | Stability | Since | Notes |
-|---|---|---|---|
-| `createCommandBuffer` | stable | 0.1.0 | |
-| `flush` | stable | 0.1.0 | |
-| `withCommandBuffer` | stable | 0.1.0 | |
-
-### `aiecsjs/observers` (utility sub-path)
-
-Component lifecycle hooks. The core does not require observers; install this sub-path only if a system needs add/remove/set callbacks.
-
-| Export | Stability | Since | Notes |
-|---|---|---|---|
-| `observe` | stable | 0.1.0 | Accepts `{ signal?: AbortSignal }` since 0.2.0. |
-| `onAdd` | stable | 0.1.0 | Accepts `{ signal?: AbortSignal }` since 0.2.0. |
-| `onRemove` | stable | 0.1.0 | Accepts `{ signal?: AbortSignal }` since 0.2.0. |
-| `onSet` | stable | 0.1.0 | Low-level mutation hook; NOT a reactive value-predicate query. Accepts `{ signal?: AbortSignal }` since 0.2.0. |
-
-### `aiecsjs/serialize` (utility sub-path)
-
-| Export | Stability | Since | Notes |
-|---|---|---|---|
-| `serializeWorld` | stable | 0.1.0 | Binary format includes a version stamp. |
-| `deserializeWorld` | stable | 0.1.0 | |
-| `toJSON` | stable | 0.1.0 | |
-| `fromJSON` | stable | 0.1.0 | |
-| `createDeltaSerializer` | **experimental** | 0.1.0 | Wire format may change before 1.0. |
-
-### `aiecsjs/worker` (experimental adapter sub-path)
+aiecsjs keeps the root ECS surface stable and treats subpaths as explicit public modules.
 
-The entire subpath is **experimental** in 0.x. **In 0.x the implementation is a snapshot-copy transport** — serialize the world into the SAB on send, deserialize into a fresh world on adopt. It is not true shared-memory column aliasing. The API surface matches the documented contract; true shared columns are targeted for **0.3+**. Snapshot layout and capability flags may change.
+## Stable Surface
 
-| Export | Stability | Since | Notes |
-|---|---|---|---|
-| `transferableSnapshot` | experimental | 0.1.0 | |
-| `adoptSnapshot` | experimental | 0.1.0 | |
-| `attachWorld` | experimental | 0.1.0 | |
-| `detachWorld` | experimental | 0.1.0 | |
+| Surface | Status | Notes |
+| --- | --- | --- |
+| `aiecsjs` root | Stable | World/entity/component/query/system helpers, `Types`, refs, `VERSION`, `EcsError`. |
+| `aiecsjs/loop` | Stable utility | Loop helper only; scheduler policy remains app-owned. |
+| `aiecsjs/commands` | Stable utility | Command buffers for deferred structural mutations. |
+| `aiecsjs/observers` | Stable utility | Add/remove/set observer helpers. |
+| `aiecsjs/serialize` | Stable utility | Binary and JSON snapshots with capacity clamps. |
+| `aiecsjs/worker` | Experimental adapter | Environment-dependent SAB/transfer helpers. |
+| `aiecsjs/relations` | Stable | Relations and `ChildOf`; destroy cleanup cost remains documented. |
+| `aiecsjs/internal/*` | Private | No compatibility guarantee. |
 
-### `aiecsjs/relations` (stable sub-path since 0.4.0)
+## Behavioral Boundaries
 
-The relations sub-path is **stable** as of 0.4.0. The graph API (`defineRelation`, `addRelation`, `removeRelation`, `getRelationTargets`, `getRelationData`) and the built-in `ChildOf` relation are frozen for the 1.x track.
+- Entity ids are generational numeric ids. Use refs (`refOf`, `deref`, `aliveRef`) when storing ids across time.
+- Query iteration is synchronous and direct. Use command buffers for structural changes inside systems.
+- Reactive query buffers must be drained by the caller.
+- Serialization accepts trusted snapshots; hostile input is bounded but not a sandbox.
+- No build-mode-gated runtime validation policy is promised.
+- Worker support depends on `SharedArrayBuffer`, transfer support, and browser isolation policy.
 
-**Raw slot-keying ABA semantic:** relation storage keys edges by raw entity slot index (`entityId & indexMask`), not by the full packed EntityId (which includes a generation counter). If entity A is destroyed and a different entity B is later created occupying the same slot, B will inherit A's outgoing and incoming edges unless the destroy cleanup hook ran. The cleanup hook fires automatically when `destroyEntity` is called, so normal usage is safe. Callers holding cached EntityId values across destroy/recreate cycles should validate liveness with `entityExists` before reading relation data if ABA is a concern.
+## Current Caveats
 
-| Export | Stability | Since | Notes |
-|---|---|---|---|
-| `defineRelation` | stable | 0.1.0 | |
-| `addRelation` | stable | 0.1.0 | |
-| `removeRelation` | stable | 0.1.0 | |
-| `getRelationTargets` | stable | 0.1.0 | |
-| `ChildOf` (constant) | stable | 0.1.0 | Built-in exclusive relation. |
-| `getRelationData` | stable | 0.4.0 | Returns the data payload attached via `addRelation`, or `undefined` if no such edge or no data was stored. Subject to the raw slot-keying ABA semantic described above. |
-
-### `aiecsjs/internal/*`
-
-Everything under this prefix is **internal**. It exists for the implementation's own use and may break in any release. Do not import.
-
-## Roadmap
-
-| Version | Focus | Stability shift |
-|---|---|---|
-| 0.1.x | Core surface (world, entity, component, query, system, loop, commands, observers, serialize) | Initial publish; all marked experimental at the package level but per-export stable where listed. |
-| 0.2.0 | Safety + alignment | Prototype-pollution hardening, observer `{ signal? }`, `disposeWorld` alias, `getEntityGeneration` / `packEntity` re-labelled experimental, `verify:llms` gate. See [CHANGELOG.md](./CHANGELOG.md#020---2026-05-28). |
-| 0.3.x | EntityRef + generation packing | ABA-safe; `getEntityGeneration` / `packEntity` → stable. |
-| 0.4.0 | Relations stabilisation | `aiecsjs/relations` graduated to stable; `getRelationData` added. `aiecsjs/worker` remains experimental (true SAB shared-memory columns deferred). |
-| 0.6+ | Multi-World snapshot diff transport (placeholder) | experimental — design TBD. |
-| 1.0.0 | API freeze | All `stable` exports frozen for 1.x. |
-
-## How to check stability at runtime
-
-```ts
-import { VERSION } from 'aiecsjs'
-
-if (VERSION.startsWith('0.')) {
-  console.warn('aiecsjs is in pre-1.0; API surface may shift')
-}
-```
-
-For programmatic introspection, parse [`api.json`](./api.json) — each entry has `stability` and `since` fields.
+- Reactive query registration scans a module-level query cache on structural changes.
+- Exclusive relation cleanup scans relation capacity when an entity is destroyed.
+- Lint has many `noExplicitAny` warnings pending cleanup.
 
 ---
 
@@ -1491,98 +164,34 @@ For programmatic introspection, parse [`api.json`](./api.json) — each entry ha
 
 # Contributing to aiecsjs
 
-Thanks for taking the time to look. aiecsjs is a deliberately small ECS core;
-contributions that keep the surface narrow and the iteration path hot are
-easier to accept than ones that expand it.
-
-## Quick start
-
-```bash
-npm install
-npm run test            # vitest, ~150 behaviour tests + multi-world isolation
-npm run typecheck       # tsc --noEmit on strict mode
-npm run lint            # biome check (added in 0.2.0)
-npm run build           # tsup; dual ESM/CJS + .d.ts
-npm run verify:exports  # ensures package.json#exports matches dist/ (added in 0.2.0)
-npm run size            # size-limit per-subpath gzip budget
-```
-
-The full pre-publish gate is `npm run prepublishOnly`, which runs typecheck,
-tests, build, and the size budget check — in that order. Once 0.2.0 lands,
-`lint` and `verify:exports` should also be wired into the gate (see
-`package.json`).
-
-## What gets in easily
-
-- Bug fixes with a failing test added first.
-- README / typing corrections — especially in `STABILITY.md` or `api.json`
-  when an export's stability label drifts from reality.
-- Tests that lock down existing behaviour (multi-world isolation, archetype
-  migration boundaries, observer fan-out on destroy, etc).
-- New `aiecsjs/<subpath>` opt-in modules that follow the same shape as
-  `loop`, `commands`, `observers`, `serialize`, `worker`, `relations`:
-  independent, named exports only, no side effects, single responsibility,
-  tree-shakable.
-
-## What needs discussion first
-
-- Anything that changes the storage layout (archetype tables, TypedArray
-  columns, bitmask layout). The Caesar-III-style growth invariants matter.
-- New required fields on `World`, `Component`, or `Snapshot`.
-- A change that would push any subpath past its `size-limit` budget.
-- Reactive value-predicate queries (see "What aiecsjs does NOT do" in the
-  README — open an issue with the use case first).
-
-## Design principles
-
-aiecsjs follows the core priority order:
-
-> Security > Correctness > Simplicity > YAGNI > Performance
-
-In particular, the public API stays **functional and tree-shakable** — no
-class constructors on the public surface, factory functions only.
-`destroyWorld` is the original 0.1.x export and is now **deprecated** since
-0.2.0 — see `STABILITY.md`. New code should use `disposeWorld`, which is the
-same function under the ai*js ecosystem `dispose()` convention.
-`destroyWorld` is scheduled for removal in 1.0.
-
-## Commit & PR style
-
-- Commit messages: imperative subject under 70 chars; body explains *why*.
-- PRs: keep scope to one topic. Link the issue if any.
-- Tests required for any behaviour change. Property-based tests welcome for
-  invariants (`tests/multi-world.test.ts` is the reference shape).
-
-## Reporting issues
-
-- Minimal reproduction welcome: paste the smallest
-  `createWorld + addComponent + runQuery` triple that shows the bug.
-- For security issues (e.g. snapshot/SAB validation bypass), please email
-  the maintainer rather than filing publicly.
-
-## Release flow
+Keep ECS changes explicit, benchmarkable, and compatible with the public subpath contracts.
 
-Releases are tag-triggered via the GitHub Actions workflow
-(`.github/workflows/publish.yml`). From a clean tree on `main`:
+## Local workflow
 
 ```bash
-npm version patch       # or `minor` / `major`
-git push --follow-tags
+pnpm install
+pnpm typecheck
+pnpm test
+pnpm verify:docs
+pnpm build:llms
+pnpm verify:llms
+pnpm verify:exports
+pnpm verify:dist
+pnpm check:size
 ```
 
-The workflow triggers on `v*` tag push and runs the full gate before
-publishing:
+Run `pnpm lint` before PRs; existing `noExplicitAny` warnings are known backlog, not an excuse to add more.
 
-1. typecheck / tests / build
-2. size budget gate
-3. `npm publish --provenance --access public`
+## Rules
 
-A failed gate stops the publish; the tag stays on the repo but nothing
-ships.
+- Do not expose `internal/*` as public API.
+- Use command buffers in examples that mutate structure during iteration.
+- Add regression tests for entity lifetime, archetype moves, relation cleanup, serialization, and worker transport changes.
+- Keep docs short and update `llms-full.txt` after docs edits.
+- Discuss storage layout or entity id compatibility changes before implementation.
 
 ## License
 
-By contributing, you agree your changes will be licensed under the MIT
-license that covers this project.
+MIT
 
 ---