aiecsjs 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -8,12 +8,89 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [Unreleased]
 
-### Planned for 0.3+
+### Planned for 0.4+
 
-- Implement ABA-safe `EntityRef` and graduate `getEntityGeneration` / `packEntity` from experimental → stable.
 - Add `pipeAsync` for async system composition.
 - Doc-test harness so README code blocks are mechanically verified.
 - Promote `aiecsjs/relations` and `aiecsjs/worker` (true SAB-shared columns) to `stable`.
+- 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({ generationBits: 16 })`. See test
+  [tests/ref.test.ts](./tests/ref.test.ts) `generation wrap` describe block.
+
+## [0.3.0] - 2026-05-29
+
+### Added (API)
+
+- **`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.
+
+### 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
 

package/README.md

@@ -1,15 +1,15 @@
 # aiecsjs
 
-[English](README.md) | [繁體中文](README_ZHTW.md)
-
+[![npm version](https://img.shields.io/npm/v/aiecsjs.svg)](https://www.npmjs.com/package/aiecsjs)
+[![CI](https://github.com/yshengliao/aiecsjs/actions/workflows/ci.yml/badge.svg)](https://github.com/yshengliao/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)
-![Status](https://img.shields.io/badge/status-experimental-orange.svg)
-![Version](https://img.shields.io/badge/version-0.1.4-blue.svg)
-![Types](https://img.shields.io/badge/types-TypeScript-3178c6.svg)
+[![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)
 
 > 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/yshengliao) — see also [aifsmjs](https://github.com/yshengliao/aifsmjs) (FSM) and [aibridgejs](https://github.com/yshengliao/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. Entity IDs in 0.x are bare slot indices; internal generation tracks slot reuse but is not encoded in the ID. ABA-safe `EntityRef` is targeted for **0.3+** (deferred from the 0.2 roadmap once the v0.2.0 scope froze on API stability + safety).
 
 ```ts

package/README_ZHTW.md

@@ -1,15 +1,15 @@
 # aiecsjs
 
-[English](README.md) | [繁體中文](README_ZHTW.md)
-
+[![npm version](https://img.shields.io/npm/v/aiecsjs.svg)](https://www.npmjs.com/package/aiecsjs)
+[![CI](https://github.com/yshengliao/aiecsjs/actions/workflows/ci.yml/badge.svg)](https://github.com/yshengliao/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)
-![Status](https://img.shields.io/badge/status-experimental-orange.svg)
-![Version](https://img.shields.io/badge/version-0.1.4-blue.svg)
-![Types](https://img.shields.io/badge/types-TypeScript-3178c6.svg)
+[![AI Generated](https://img.shields.io/badge/AI_Generated-Claude_Code_Opus_4.7_Max-blueviolet.svg)](https://www.anthropic.com/claude-code)
+[![English](https://img.shields.io/badge/lang-English-blue.svg)](README.md)
 
 > 為 TypeScript 而設計的原型式 ECS，支援瀏覽器與 Node，內建 SAB 快照傳輸（snapshot transport）與 AI 可讀文件。
 
+隸屬 [ai\*js micro-runtime 生態系](https://github.com/yshengliao) ─ 另見 [aifsmjs](https://github.com/yshengliao/aifsmjs)（FSM）與 [aibridgejs](https://github.com/yshengliao/aibridgejs)（cross-context RPC）。
+
 aiecsjs 採用 **原型表格搭配 TypedArray 欄位** 與 **位元遮罩查詢**，這正是 piecs 與 wolf-ecs 在公開效能評測中名列前茅所採用的架構。API 為 **函式式且可 tree-shake**，以 `pipe()` 組合。元件（Component）同時支援 SoA（結構陣列）與 AoS（結構物件）兩種佈局。0.x 的實體 ID 為純索引值；世代計數在內部追蹤槽位重用，但不編入 ID。具 ABA 安全的 `EntityRef` 預計 **0.3+** 推出（0.2 為求 API 穩定與安全性收尾而延後）。
 
 ```ts

package/STABILITY.md

@@ -34,8 +34,13 @@ The **root** entry (`aiecsjs`) is the stable core: world, entity, component, que
 | `destroyEntity` | stable | 0.1.0 | |
 | `entityExists` | stable | 0.1.0 | |
 | `getEntityIndex` | stable | 0.1.0 | |
-| `getEntityGeneration` | **experimental** | 0.1.0 | Returns 0 in 0.x (generation tracked internally but not encoded in EntityId). Real values arrive with ABA-safe `EntityRef` in **0.3+**. |
-| `packEntity` | **experimental** | 0.1.0 | Identity helper in 0.x. Returns the index unchanged. Real packing arrives with `EntityRef` in **0.3+**. |
+| `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. |
@@ -130,8 +135,9 @@ Everything under this prefix is **internal**. It exists for the implementation's
 |---|---|---|
 | 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+ | Relations stabilisation + EntityRef + SAB | `aiecsjs/relations` graduates to stable; ABA-safe `EntityRef` lands and `getEntityGeneration` / `packEntity` start returning real values; `aiecsjs/worker` adopts true shared-memory column aliasing. |
-| 0.3.x | Hardening, relations stabilization, multi-threading polish | `aiecsjs/relations` and `aiecsjs/worker` → stable. |
+| 0.3.x | EntityRef + generation packing | ABA-safe; `getEntityGeneration` / `packEntity` → stable. |
+| 0.4+ | Relations stabilisation + true SAB worker | `aiecsjs/relations` and `aiecsjs/worker` → stable. |
+| 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

package/STABILITY_ZHTW.md

@@ -33,8 +33,13 @@ aiecsjs 遵循 [semver](https://semver.org/)。在 **0.x** 系列內：
 | `destroyEntity` | stable | 0.1.0 | |
 | `entityExists` | stable | 0.1.0 | |
 | `getEntityIndex` | stable | 0.1.0 | |
-| `getEntityGeneration` | stable | 0.1.0 | |
-| `packEntity` | 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 共享。 |
@@ -129,7 +134,9 @@ aiecsjs 遵循 [semver](https://semver.org/)。在 **0.x** 系列內：
 |---|---|---|
 | 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+ | Relations 穩定化 + EntityRef + SAB | `aiecsjs/relations` 升為 stable；ABA-safe `EntityRef` 上線，`getEntityGeneration` / `packEntity` 開始回傳真值；`aiecsjs/worker` 採用真正 shared-memory column aliasing。 |
+| 0.3.x | EntityRef + generation packing | ABA-safe；`getEntityGeneration` / `packEntity` → stable。 |
+| 0.4+ | Relations 穩定化 + 真正 SAB worker | `aiecsjs/relations` 與 `aiecsjs/worker` → stable。 |
+| 0.6+ | Multi-World snapshot diff transport（佔位） | experimental — 設計待定。 |
 | 1.0.0 | API 凍結 | 所有 `stable` 匯出於 1.x 系列凍結。 |
 
 ## 在執行時檢查穩定度