aiecsjs 0.4.0 → 0.5.0

package/STABILITY.md

@@ -1,156 +0,0 @@
-# Stability Contract
-
-[English](STABILITY.md) | [繁體中文](STABILITY_ZHTW.md)
-
-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)
-
-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.
-
-| Export | Stability | Since | Notes |
-|---|---|---|---|
-| `transferableSnapshot` | experimental | 0.1.0 | |
-| `adoptSnapshot` | experimental | 0.1.0 | |
-| `attachWorld` | experimental | 0.1.0 | |
-| `detachWorld` | experimental | 0.1.0 | |
-
-### `aiecsjs/relations` (stable sub-path since 0.4.0)
-
-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.
-
-**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.
-
-| 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.

package/STABILITY_ZHTW.md

@@ -1,155 +0,0 @@
-# 穩定度契約
-
-[English](STABILITY.md) | [繁體中文](STABILITY_ZHTW.md)
-
-本文件為 `aiecsjs` 中各匯出的穩定度承諾。AI 工具與人類使用者可依此契約來鎖定版本與書寫 import 路徑。
-
-## 規範
-
-aiecsjs 遵循 [semver](https://semver.org/)。在 **0.x** 系列內：
-- **`stable`** 匯出於 minor 版本之間（例如 0.1 → 0.2）不會破壞性變更。
-- **`experimental`** 匯出可能在任何 minor 釋出時改變形狀、命名或行為。若有依賴請鎖定明確版本。
-- **`internal`** 不屬於 API 表面，可能在任何 patch 釋出時改變。請勿匯入。
-- **`deprecated`** 仍可正常運作但已排入移除計畫。棄用通知中會載明目標版本。
-
-至 **1.0** 時，`stable` 表面為整個 1.x 系列凍結。
-
-完整機器可讀的匯出清單位於 [`api.json`](./api.json)，每筆都有 `stability` 與 `since` 欄位。
-
-## 依模組分類
-
-**根目錄** entry（`aiecsjs`）為穩定核心：world、entity、component、query、system。任何 sub-path（`aiecsjs/<名稱>`）為 **utility 或 adapter sub-path** — 實用但非核心，與 core 解耦，可單獨 a la carte import。Tree-shaker 應能丟掉未引用的任何 sub-path。
-
-### `aiecsjs`（根核心）
-
-| 匯出 | 穩定度 | 起始版本 | 備註 |
-|---|---|---|---|
-| `createWorld` | stable | 0.1.0 | |
-| `destroyWorld` | **deprecated** | 0.1.0 | 請改用 `disposeWorld`。預計於 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 | 回傳 EntityId 中實際打包的 generation 值（預設 24-bit index、8-bit generation）。若使用非預設 `createWorld({ indexBits, generationBits })`，請改用 `EntityRef` + `deref`。 |
-| `packEntity` | stable | 0.3.0 | 使用預設 24/8 bit 佈局將 index + generation 打包為 EntityId。若使用非預設 bit 大小，請改用 `EntityRef` + `deref`。 |
-| `refOf` | stable | 0.3.0 | entity 不存活時拋出 `EntityNotAliveError`。 |
-| `deref` | stable | 0.3.0 | 對過期或跨 world 的 ref 回傳 null；絕不拋出錯誤。 |
-| `aliveRef` | stable | 0.3.0 | `deref` 的布林 guard 形式；絕不拋出錯誤。 |
-| `EntityRef`（type） | stable | 0.3.0 | 僅限記憶體內使用；不可序列化。 |
-| `EntityNotAliveError` | stable | 0.3.0 | 僅由 `refOf` 拋出。 |
-| `defineComponent` | stable | 0.1.0 | |
-| `defineTag` | stable | 0.1.0 | |
-| `defineObjectComponent` | stable | 0.1.0 | AoS 元件僅限主執行緒；不可跨 SAB 共享。 |
-| `addComponent` | stable | 0.1.0 | 參數順序 `(world, eid, component, init?)` 為最終定義。 |
-| `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 | 常數對應表；欄位名稱屬於契約。 |
-| `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` 為 opaque 內部值；`Archetype` 的形狀可能增加欄位。 |
-| `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）
-
-定步長累加迴圈。若應用層已自有 frame 更新驅動（PixiJS `Ticker`、requestAnimationFrame、伺服端模擬），可直接略過本 sub-path。
-
-| 匯出 | 穩定度 | 起始版本 | 備註 |
-|---|---|---|---|
-| `createLoop` | stable | 0.1.0 | |
-
-### `aiecsjs/commands`（utility sub-path）
-
-延後的結構性變更，讓系統可在迭代中安全改動 world 結構而不會讓查詢失效。
-
-| 匯出 | 穩定度 | 起始版本 | 備註 |
-|---|---|---|---|
-| `createCommandBuffer` | stable | 0.1.0 | |
-| `flush` | stable | 0.1.0 | |
-| `withCommandBuffer` | stable | 0.1.0 | |
-
-### `aiecsjs/observers`（utility sub-path）
-
-元件生命週期 hook。Core 不依賴 observers；只在系統需要 add/remove/set callback 時才安裝本 sub-path。
-
-| 匯出 | 穩定度 | 起始版本 | 備註 |
-|---|---|---|---|
-| `observe` | stable | 0.1.0 | |
-| `onAdd` | stable | 0.1.0 | |
-| `onRemove` | stable | 0.1.0 | |
-| `onSet` | stable | 0.1.0 | |
-
-### `aiecsjs/serialize`（utility sub-path）
-
-| 匯出 | 穩定度 | 起始版本 | 備註 |
-|---|---|---|---|
-| `serializeWorld` | stable | 0.1.0 | 二進位格式包含版本戳記。 |
-| `deserializeWorld` | stable | 0.1.0 | |
-| `toJSON` | stable | 0.1.0 | |
-| `fromJSON` | stable | 0.1.0 | |
-| `createDeltaSerializer` | **experimental** | 0.1.0 | Wire format 在 1.0 之前可能改變。 |
-
-### `aiecsjs/worker`（experimental adapter sub-path）
-
-整個 subpath 在 0.x 為 **experimental**。**0.x 的實作為 snapshot-copy 傳輸**——傳送時將 world 序列化進 SAB，接收端反序列化成全新 world，並非真正的共享記憶體欄位 aliasing。API 表面符合文件契約；真正的共享欄位預計 **0.3+** 推出。Snapshot 佈局與能力旗標可能改變。
-
-| 匯出 | 穩定度 | 起始版本 | 備註 |
-|---|---|---|---|
-| `transferableSnapshot` | experimental | 0.1.0 | |
-| `adoptSnapshot` | experimental | 0.1.0 | |
-| `attachWorld` | experimental | 0.1.0 | |
-| `detachWorld` | experimental | 0.1.0 | |
-
-### `aiecsjs/relations`（stable sub-path，自 0.4.0 起）
-
-relations sub-path 自 **0.4.0** 起為 **stable**。圖形 API（`defineRelation`、`addRelation`、`removeRelation`、`getRelationTargets`、`getRelationData`）以及內建 `ChildOf` 關係已為 1.x 凍結。
-
-**原始 slot 鍵值的 ABA 語意：** relation storage 以原始 entity slot index（`entityId & indexMask`）作為 edge 的鍵，而非包含 generation counter 的完整 packed EntityId。若 entity A 被銷毀後，另一個 entity B 在同一個 slot 被建立，B 將繼承 A 的所有進出 edge——除非 destroy cleanup hook 已執行（呼叫 `destroyEntity` 時會自動執行）。一般使用下是安全的；若在 destroy/recreate 循環中持有快取的 EntityId，讀取 relation data 前應以 `entityExists` 確認活躍狀態。
-
-| 匯出 | 穩定度 | 起始版本 | 備註 |
-|---|---|---|---|
-| `defineRelation` | stable | 0.1.0 | |
-| `addRelation` | stable | 0.1.0 | |
-| `removeRelation` | stable | 0.1.0 | |
-| `getRelationTargets` | stable | 0.1.0 | |
-| `ChildOf`（常數） | stable | 0.1.0 | 內建獨佔關係。 |
-| `getRelationData` | stable | 0.4.0 | 回傳透過 `addRelation` 附加的 data payload，或在 edge 不存在 / 未儲存 data 時回傳 `undefined`。受上述原始 slot 鍵值 ABA 語意影響。 |
-
-### `aiecsjs/internal/*`
-
-此前綴底下的所有內容皆為 **internal**。它存在於實作自用，可能在任何 release 變更。請勿匯入。
-
-## Roadmap
-
-| 版本 | 焦點 | 穩定度變動 |
-|---|---|---|
-| 0.1.x | 核心表面（world、entity、component、query、system、loop、commands、observers、serialize） | 初次發佈；package 整體標 experimental，但各 export 表中列為 stable 者皆穩定。 |
-| 0.2.0 | 安全與生態對齊 | 原型污染強化、observer `{ signal? }`、`disposeWorld` 別名、`getEntityGeneration` / `packEntity` 改 experimental、`verify:llms` gate。詳見 [CHANGELOG.md](./CHANGELOG.md#020---2026-05-28)。 |
-| 0.3.x | EntityRef + generation packing | ABA-safe；`getEntityGeneration` / `packEntity` → stable。 |
-| 0.4.0 | Relations 穩定化 | `aiecsjs/relations` 升為 stable；新增 `getRelationData`。`aiecsjs/worker` 維持 experimental（真正 SAB 共享記憶體欄位延後）。 |
-| 0.6+ | Multi-World snapshot diff transport（佔位） | experimental — 設計待定。 |
-| 1.0.0 | API 凍結 | 所有 `stable` 匯出於 1.x 系列凍結。 |
-
-## 在執行時檢查穩定度
-
-```ts
-import { VERSION } from 'aiecsjs'
-
-if (VERSION.startsWith('0.')) {
-  console.warn('aiecsjs 處於 1.0 前；API 表面可能調整')
-}
-```
-
-如需程式化檢視，請解析 [`api.json`](./api.json) — 每筆都有 `stability` 與 `since` 欄位。

package/docs/MIGRATION.md

@@ -1,252 +0,0 @@
-# Migration Guide
-
-[English](MIGRATION.md) | [繁體中文](MIGRATION_ZHTW.md)
-
-Concrete name-mapping tables and mental-model notes for switching to `aiecsjs` from other JavaScript ECS libraries.
-
-## From bitECS 0.4
-
-bitECS and aiecsjs share the most DNA: both are functional, both use TypedArray columns, both compose systems with `pipe`. The differences are real but small.
-
-### Name mappings
-
-| bitECS 0.4 | aiecsjs 0.1 |
-|---|---|
-| `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)` |
-| `hasComponent(world, Comp, eid)` | `hasComponent(world, eid, Comp)` |
-| `addEntity(world)` | `createEntity(world)` |
-| `removeEntity(world, eid)` | `destroyEntity(world, eid)` |
-| `defineQuery([Comp])(world)` | `forEachEntity(world, defineQuery([Comp]), fn)` |
-| `enterQuery(query)` | `enterQuery(defineQuery([...]))` (no `world` arg) |
-| `exitQuery(query)` | `exitQuery(defineQuery([...]))` |
-| `Not(Comp)` | `defineQuery({ all: [...], none: [Comp] })` |
-| `pipe(s1, s2)(world)` | `pipe(s1, s2)(world, ctx)` (ctx threaded through) |
-| `defineSerializer(...)` | `createDeltaSerializer(world, { components })` |
-| `createRelation(...)` | `defineRelation(...)` (target 0.2) |
-| `withVersioning(bits)` | `createWorld({ indexBits, generationBits })` |
-| `observe(world, query, ...)` | `observe(world, query, event, handler)` |
-
-### Mental shifts
-
-**Storage model.** bitECS uses per-component SparseSet + bitmask. aiecsjs uses archetype tables. The performance characteristics differ:
-
-- Adding/removing a tag every frame is **cheaper in bitECS** (sparse set has O(1) toggle).
-- Iterating a hot query over 10k entities is **cheaper in aiecsjs** (contiguous archetype columns).
-- For tags you toggle often, store a `boolean` field in a stable component instead of `add`/`removeComponent`.
-
-**Argument order.** This is the #1 source of bugs when porting:
-
-```ts
-// bitECS:
-addComponent(world, Position, eid)
-
-// aiecsjs:
-addComponent(world, eid, Position, { x: 0, y: 0 })
-```
-
-The aiecsjs order is `(world, eid, component, init)` — entity first because it's the subject of the operation.
-
-**Query iteration.** bitECS returns the entity array from the query function call. aiecsjs separates query definition from execution:
-
-```ts
-// bitECS:
-const movers = defineQuery([Position, Velocity])
-const eids = movers(world)
-for (let i = 0; i < eids.length; i++) {
-  const e = eids[i]
-  Position.x[e] += Velocity.x[e]
-}
-
-// aiecsjs:
-const movers = defineQuery([Position, Velocity])
-forEachEntity(world, movers, (e, pos, vel) => {
-  pos.x[e] += vel.x[e]
-})
-```
-
-The aiecsjs version is shorter and gets typed column views as callback arguments.
-
-**Entity versioning.** Both support it. bitECS exposes `withVersioning(bits)`; aiecsjs takes `indexBits` and `generationBits` directly in `WorldOptions`.
-
-```ts
-// bitECS:
-const world = createWorld(withVersioning(8))
-
-// aiecsjs:
-const world = createWorld({ indexBits: 24, generationBits: 8 })
-```
-
-### Porting a system
-
-bitECS:
-```ts
-const movementSystem = (world) => {
-  const ents = movers(world)
-  for (let i = 0; i < ents.length; i++) {
-    const eid = ents[i]
-    Position.x[eid] += Velocity.x[eid]
-    Position.y[eid] += Velocity.y[eid]
-  }
-  return world
-}
-```
-
-aiecsjs:
-```ts
-const movementSystem = (world, dt = 1) => {
-  forEachEntity(world, movers, (e, pos, vel) => {
-    pos.x[e] += vel.x[e] * dt
-    pos.y[e] += vel.y[e] * dt
-  })
-  return world
-}
-```
-
-## From miniplex
-
-miniplex is object-oriented and entity-shape-driven; aiecsjs is functional and component-declaration-driven. The port is a small mental adjustment but worthwhile if you need TypedArray performance or multi-thread support.
-
-### Name mappings
-
-| miniplex 2.0 | aiecsjs 0.1 |
-|---|---|
-| `const world = new World<Entity>()` | `const world = createWorld()` |
-| `world.add({ position: {x, y}, velocity: {x, y} })` | `createEntity` + multiple `addComponent` calls |
-| `world.with('position', 'velocity')` | `defineQuery([Position, Velocity])` |
-| `world.archetype('position', 'velocity')` | `defineQuery([Position, Velocity])` |
-| `query.entities` | `runQuery(world, query)` |
-| `for (const e of query)` | `forEachEntity(world, query, fn)` |
-| `query.onEntityAdded.add(fn)` | `enterQuery(query)` + observe in a system |
-| `query.onEntityRemoved.add(fn)` | `exitQuery(query)` |
-| `world.remove(entity)` | `destroyEntity(world, eid)` |
-| `world.queue.add(...)`, `world.queue.flush()` | `withCommandBuffer(world, cb => cb.create() ...)` |
-| `world.where(predicate)` | (filter inside `forEachEntity` callback) |
-| `<Entities of={query}>` (miniplex-react) | (not yet — see roadmap) |
-
-### Mental shifts
-
-**Component declaration up front.** In miniplex, components are object property names that exist if you assign them. In aiecsjs, components must be declared:
-
-```ts
-// miniplex:
-const e = world.add({ position: { x: 0, y: 0 }, velocity: { x: 1, y: 0 } })
-
-// aiecsjs:
-const Position = defineComponent({ x: Types.f32, y: Types.f32 })
-const Velocity = defineComponent({ x: Types.f32, y: Types.f32 })
-const e = createEntity(world)
-addComponent(world, e, Position, { x: 0, y: 0 })
-addComponent(world, e, Velocity, { x: 1, y: 0 })
-```
-
-The win is TypedArray-backed columns (fast iteration) and SAB-safe storage. The cost is the upfront component declarations.
-
-**Heterogeneous references.** If your miniplex entities have `mesh: THREE.Mesh` properties, use `defineObjectComponent` in aiecsjs:
-
-```ts
-const MeshRef = defineObjectComponent<{ mesh: THREE.Mesh | null }>(() => ({ mesh: null }))
-addComponent(world, e, MeshRef, { mesh: someMesh })
-```
-
-But remember: AoS components are main-thread only.
-
-**Iteration callbacks vs. iterators.** miniplex's `for (const e of query)` is convenient but allocates the iterator each frame. `forEachEntity(world, query, fn)` is the hot path; reach for `iterQuery` only when you need `for...of` semantics.
-
-### Porting a system
-
-miniplex:
-```ts
-const movement = (dt: number) => {
-  for (const e of world.with('position', 'velocity')) {
-    e.position.x += e.velocity.x * dt
-    e.position.y += e.velocity.y * dt
-  }
-}
-```
-
-aiecsjs:
-```ts
-const movers = defineQuery([Position, Velocity])
-const movement = (world, dt) => {
-  forEachEntity(world, movers, (e, pos, vel) => {
-    pos.x[e] += vel.x[e] * dt
-    pos.y[e] += vel.y[e] * dt
-  })
-  return world
-}
-```
-
-## From ECSY
-
-ECSY is [archived](https://github.com/ecsyjs/ecsy) (April 2025). Migration to aiecsjs is straightforward because both are archetype-style ECS. ECSY's OO ergonomics map cleanly to aiecsjs's functional API.
-
-### Name mappings
-
-| ECSY | aiecsjs 0.1 |
-|---|---|
-| `class C extends Component { static schema = { x: { type: Types.Number } } }` | `defineComponent({ x: Types.f64 })` |
-| `class Tag extends TagComponent {}` | `defineTag()` |
-| `class S extends System { static queries = { foo: { components: [...] } }; execute(dt) { this.queries.foo.results.forEach(...) } }` | `const fooQ = defineQuery([...])`; `const S = (world, dt) => { forEachEntity(world, fooQ, fn); return world }` |
-| `world.registerComponent(C)` | (implicit on `defineComponent`) |
-| `world.registerSystem(S)` | (none — `pipe` orders systems) |
-| `world.execute(dt, time)` | `tick(world, dt)` where `tick = pipe(S1, S2, ...)` |
-| `world.createEntity()` | `createEntity(world)` |
-| `entity.addComponent(C, data)` | `addComponent(world, eid, C, data)` |
-| `entity.removeComponent(C)` | `removeComponent(world, eid, C)` |
-| `entity.getComponent(C)` | `getComponent(world, eid, C)` |
-| `entity.getMutableComponent(C)` | `getComponent(world, eid, C)` (always mutable in aiecsjs) |
-| `queries.foo.added` | `enterQuery(fooQ)` |
-| `queries.foo.removed` | `exitQuery(fooQ)` |
-| `queries.foo.changed` | (use `onSet` observer or own change tracking) |
-
-### Mental shifts
-
-**No `class System`.** Systems are functions, not classes. Drop `extends System`, `execute`, and `static queries` — define a query at module top-level and pass it to `forEachEntity`.
-
-```ts
-// ECSY:
-class MovementSystem extends System {
-  static queries = { movers: { components: [Position, Velocity] } }
-  execute(dt: number) {
-    this.queries.movers.results.forEach((e) => {
-      const pos = e.getMutableComponent(Position)
-      const vel = e.getComponent(Velocity)
-      pos.x += vel.x * dt
-      pos.y += vel.y * dt
-    })
-  }
-}
-world.registerSystem(MovementSystem)
-world.execute(1/60)
-```
-
-```ts
-// aiecsjs:
-const movers = defineQuery([Position, Velocity])
-const movement = (world, dt) => {
-  forEachEntity(world, movers, (e, pos, vel) => {
-    pos.x[e] += vel.x[e] * dt
-    pos.y[e] += vel.y[e] * dt
-  })
-  return world
-}
-const tick = pipe(movement)
-tick(world, 1/60)
-```
-
-**SoA columns vs. component instances.** ECSY components are class instances with fields like `pos.x`. aiecsjs SoA components are column maps; you index by entity ID: `pos.x[e]`.
-
-**No `priority` or scheduling DSL.** aiecsjs systems run in `pipe()` order. If you depended on ECSY's `priority` for ordering, just write the pipe in the right order.
-
-**`Types.Number` → `Types.f64` (or `f32`).** ECSY's numeric type is double-precision; aiecsjs lets you pick the width. Use `f32` for game data, `f64` only if you genuinely need it.
-
-## Common pitfalls when migrating (from any library)
-
-1. **Forgetting to `pipe(...)` system function** — calling each system manually and forgetting to thread the world reference. Compose with `pipe` once and call `tick(world, ctx)`.
-2. **Calling `defineComponent` inside a system** — components are identity-based and must be module-level constants.
-3. **Caching `getComponent()` return value** — after an entity's archetype changes, the view is stale. Re-fetch each frame.
-4. **Iterating with `for...of` on `runQuery` result** — `runQuery` allocates an array each call. Use `forEachEntity` in hot paths.
-5. **Trying to share AoS components across Workers** — only SoA components live in SharedArrayBuffer. Replace AoS with SoA before going multi-thread.