@oasys/oecs 0.5.2 → 0.5.4

package/README.md

@@ -1,22 +1,34 @@
 # oecs
 
-**A full-featured, archetype-based Entity Component System for TypeScript.**
-
-`@oasys/oecs` is a complete ECS — not just storage-and-queries, but the whole toolkit you expect from a
-mature engine: observers, relations with wildcards, sparse storage, system sets and run conditions,
-entity enable/disable, templates, deterministic hashing with snapshot/restore, a typed host→ECS write
-seam, and an optional reactive UI bridge. It is **pure TypeScript and zero-dependency by default** — it
-runs over a plain resizable `ArrayBuffer`, so it needs no `SharedArrayBuffer` and no cross-origin
-isolation (COOP/COEP). An opt-in shared-memory profile swaps in a `SharedArrayBuffer` for worker offload
-or a WASM compute backend; both profiles share one core and agree, byte-for-byte, on `stateHash`.
-
-- **Fast** — struct-of-arrays column storage grouped by archetype; iteration is a tight loop over typed
-  arrays with no per-entity object allocation.
-- **Type-safe** — component handles are callable defs with stable numeric ids at runtime and fully-typed schemas at compile time;
-  misspelled fields are compile errors.
-- **Deterministic** — an opt-in mode gives a backing-agnostic `stateHash` plus snapshot/restore and
-  command-log replay.
-- **Complete** — the feature surface below is the whole engine, not a starting point.
+**A complete, archetype-based Entity Component System for TypeScript.**
+
+`@oasys/oecs` gives you more than storage and queries. It gives you the tools that a mature engine
+has:
+
+- observers;
+- relations with wildcards;
+- sparse storage;
+- system sets and run conditions;
+- enable and disable for an entity;
+- templates;
+- deterministic hashing, with snapshot and restore;
+- a typed write path from the host into the ECS;
+- an optional reactive UI bridge.
+
+The package is **pure TypeScript, and it has no dependencies by default**. It runs over one plain
+`ArrayBuffer`. So it does not need a `SharedArrayBuffer`, and it does not need cross-origin
+isolation (COOP/COEP). An optional shared-memory profile uses a `SharedArrayBuffer` instead. Use
+that profile for worker offload, or for a WASM compute backend. The two profiles use one core, and
+they agree byte-for-byte on `stateHash`.
+
+- **Data-oriented** — Columns use struct-of-arrays storage, grouped by archetype. Iteration is a
+  small loop over typed arrays. The loop allocates no object for each entity.
+- **Type-safe** — A component handle is a callable definition. It has a stable numeric id at run
+  time and a full schema type at compile time. A field name with a spelling error is a compile
+  error.
+- **Deterministic** — An optional mode gives you a `stateHash` that is independent of the storage
+  type. It also gives you snapshot, restore, and replay of a command log.
+- **Complete** — The features below are the full engine. They are not only a start.
 
 ## Installation
 
@@ -28,8 +40,10 @@ deno add jsr:@oasys/oecs    # JSR (Deno)
 npx jsr add @oasys/oecs     # JSR (npm-compatible)
 ```
 
-Requires a runtime with resizable `ArrayBuffer` (the default heap profile grows in place):
-Node ≥ 20, Deno ≥ 1.38, Chrome 111+, Firefox 128+, Safari 16.4+.
+Supported runtimes: Node 20 or later, Deno 1.38 or later, Chrome 111 or later, Firefox 128 or
+later, and Safari 16.4 or later. The default heap profile uses a plain, fixed `ArrayBuffer`. The
+optional shared and WASM profiles need a growable `SharedArrayBuffer` or `WebAssembly.Memory`, and
+those requirements set the version limits.
 
 ## Quick start
 
@@ -42,17 +56,17 @@ const ecs = new ECS(); // pure-TS heap profile — no SharedArrayBuffer needed
 const Pos = ecs.registerComponent({ x: "f64", y: "f64" });
 const Vel = ecs.registerComponent(["vx", "vy"] as const);
 
-// A query is a live, cached view over matching archetypes — build it once, reuse it.
+// A query is a live, cached view of the matching archetypes. Build it once, then use it again.
 const movers = ecs.query(Pos, Vel);
 
-// Systems declare the components they read/write (checked in dev builds).
+// Systems declare the components that they read and write (checked in development builds).
 const move = ecs.registerSystem({
   reads: [Vel],
-  writes: [Pos], // a declared write implies read of the same component
+  writes: [Pos], // a declared write also gives read access to the same component
   fn: (ctx, dt) => {
     movers.eachChunk((cols, count) => {
-      const { x, y } = cols.mut(Pos);    // whole group; stamps Pos's change tick once
-      const { vx, vy } = cols.read(Vel); // read-only group
+      const { x, y } = cols.mut(Pos);    // the full group; sets the change tick of Pos one time
+      const { vx, vy } = cols.read(Vel); // a read-only group
       for (let i = 0; i < count; i++) {
         x[i] += vx[i] * dt;
         y[i] += vy[i] * dt;
@@ -69,141 +83,180 @@ ecs.addComponent(e, Pos, { x: 0, y: 0 });
 ecs.addComponent(e, Vel, { vx: 100, vy: 50 });
 
 ecs.update(1 / 60);
-ecs.getField(e, Pos, "x"); // ≈ 1.667
+ecs.getField(e, Pos, "x"); // about 1.667
 ```
 
 ## Features
 
-**Storage & data model**
-
-- **Archetype SoA storage** over a backing-neutral `ColumnStore` — entities with the same component set
-  share contiguous typed-array columns; cache-friendly loops, no per-entity object allocation.
-- **Phantom-typed components** — `registerComponent({ x: "f64", y: "f64" })` returns a callable
-  `ComponentDef` with a stable numeric `.id` at runtime and a fully-typed schema at compile time.
-  Record syntax for per-field types, array shorthand for uniform `f64`, and `registerTag()` for
-  data-free markers. Field types: `f32 f64 i8 i16 i32 u8 u16 u32`.
-- **Two storage profiles, one core** — pure-TS heap (`ArrayBuffer`) by default; opt-in
-  `SharedArrayBuffer` for workers / WASM. Same code path, same `stateHash`, sized through a single
-  `memory` surface (entity budget, byte cap, or pinned capacity).
+**Storage and the data model**
+
+- **Archetype storage in struct-of-arrays form**, above a storage-neutral `ColumnStore`. Entities
+  with the same set of components share adjacent typed-array columns. Loops use the cache well, and
+  they allocate no object for each entity.
+- **Components with phantom types** — `registerComponent({ x: "f64", y: "f64" })` gives you a
+  callable `ComponentDef`. The definition has a stable numeric `.id` at run time and a full schema
+  type at compile time. Use the record syntax for different types in each field. Use the array
+  shorthand when all fields are `f64`. Use `registerTag()` for markers that hold no data. The field
+  types are `f32 f64 i8 i16 i32 u8 u16 u32`.
+- **Two storage profiles, one core** — The default is a pure-TS heap (`ArrayBuffer`). A
+  `SharedArrayBuffer` for workers or WASM is optional. The code path is the same, the `stateHash`
+  is the same, and one `memory` option sets the size (an entity budget, a byte limit, or a fixed
+  capacity).
 
 **Queries**
 
-- **Live, cached queries** — `ecs.query(Pos, Vel)` refined with `.and()` / `.without()` / `.anyOf()`;
-  new matching archetypes are pushed in automatically.
-- **Two iteration verbs** — `forEach(arch => …)` for read-only archetype iteration, `eachChunk((cols, count) => …)`
-  for the mutable hot path (`cols.mut` / `cols.read` resolve a whole component's columns at once).
-- **Change detection** — per-`(archetype, component)` change ticks; `query.changed(Pos)` visits only
-  archetypes written since the system's threshold tick.
-- **Relation & hierarchy queries** — `(R, *)` / `(*, T)` wildcards, `forEachRelatedTo`, and
-  `query.hierarchy(rel, depth)`. **Sparse queries** via `query.withSparse(...)`; disabled entities are
-  skipped unless you opt in with `query.includeDisabled()`.
-
-**Systems & scheduling**
-
-- **Declarative systems** — plain functions in a `SystemConfig` declaring `reads` / `writes`, enforced by
-  a dev-mode access checker (tree-shaken in production). Bare `(ctx, dt)` and `(q, ctx, dt)` +
-  query-builder overloads exist for no-access glue; lifecycle hooks `onAdded` / `onRemoved` / `dispose`;
-  `exclusive: true` for full-world setup/teardown.
-- **Topological scheduler** — seven phases (`PRE_STARTUP` → `STARTUP` → `POST_STARTUP`, `FIXED_UPDATE`,
-  `PRE_UPDATE` → `UPDATE` → `POST_UPDATE`); per-phase Kahn sort by `before` / `after`, with insertion
-  order as a deterministic tiebreaker. Always-on cycle detection.
-- **Fixed timestep** — accumulator loop with configurable `fixedTimestep` and spiral-of-death protection.
-- **System sets & run conditions** — `systemSet(...)` + `configureSet(...)`; `runIfResourceEq`,
-  `runEveryNTicks`, `runIfAnyMatch`, and custom `RunCondition`s.
+- **Live, cached queries** — Write `ecs.query(Pos, Vel)`, then make it more exact with `.and()`,
+  `.without()`, or `.anyOf()`. The store adds new matching archetypes to the query automatically.
+- **Two iteration verbs** — Use `forEach(arch => …)` to read archetypes. Use
+  `eachChunk((cols, count) => …)` for the high-frequency loop that writes. In that loop, `cols.mut`
+  and `cols.read` give you all the columns of one component at the same time.
+- **Change detection** — Each `(archetype, component)` pair has a change tick.
+  `query.changed(Pos)` visits only the archetypes that changed at or after the threshold tick of
+  the system.
+- **Queries for relations and hierarchies** — Use the wildcards `(R, *)` and `(*, T)`, plus
+  `forEachRelatedTo` and `query.hierarchy(rel, depth)`. For **sparse queries**, use
+  `query.withSparse(...)`. Queries skip disabled entities. To include them, use
+  `query.includeDisabled()`.
+
+**Systems and the schedule**
+
+- **Systems that declare their access** — A system is a plain function in a `SystemConfig` that
+  declares `reads` and `writes`. A development-mode access checker holds you to that declaration,
+  and the build tool removes that checker from a production build. There are also `(ctx, dt)` and
+  `(q, ctx, dt)`
+  forms with a query builder, for connection code that touches no data. The lifecycle hooks are
+  `onAdded`, `onRemoved`, and `dispose`. Set `exclusive: true` for full-world setup or teardown.
+- **A topological scheduler** — There are seven phases: `PRE_STARTUP`, `STARTUP`, `POST_STARTUP`,
+  `FIXED_UPDATE`, `PRE_UPDATE`, `UPDATE`, and `POST_UPDATE`. Each phase does a Kahn sort on the
+  `before` and `after` constraints. Insertion order breaks a tie, which keeps the result
+  deterministic. Cycle detection is always active.
+- **A fixed timestep** — An accumulator loop uses the `fixedTimestep` value that you set. A limit
+  protects against the spiral of death.
+- **System sets and run conditions** — Use `systemSet(...)` with `configureSet(...)`. The supplied
+  conditions are `runIfResourceEq`, `runEveryNTicks`, and `runIfAnyMatch`. You can also write your
+  own `RunCondition`.
 
 **Structural changes**
 
-- **Deferred inside systems, immediate on the host** — `ctx.commands` (a Bevy-`Commands`-style
-  facade) buffers add / remove / despawn / enable / disable until the phase flush, so iterators
-  stay valid (`commands.spawn` returns the id immediately; its component attaches are deferred). Every host-side mutation (`ecs.addComponent` / `removeComponent` /
-  `despawn` / `disable` / `enable`) applies immediately.
-- **Entity enable/disable** — `disable` / `enable` / `isDisabled`; disabled rows sit in a partitioned
-  tail and are skipped by default queries.
-- **Templates & bundles** — `ecs.template(Pos({ x, y }), …)` blueprints consumed by `spawn` /
-  `spawnMany` for zero-transition spawns; the same callable-bundle varargs drive `spawnBundle(...)`
-  and `addComponents(...)`.
-
-**Reactivity & relationships**
-
-- **Observers** — `ecs.observe(...)` for `onAdd` / `onRemove` / `onSet` / `onEnable` / `onDisable`,
-  structural or per-entity.
-- **Relations** — `(relation, target)` pairs with `ChildOf` / `IsA` presets, exclusive / multi arities,
-  bidirectional queries (`targetOf` / `sourcesOf` / `ancestorsOf` / `rootOf` / `cascadeOf`), and
-  configurable on-delete cleanup (`delete` / `clear` / `orphan`). Stored sparsely — no archetype
-  transition, no identity bit.
-- **Sparse storage** — `registerSparseComponent` / `registerSparseTag`, `addSparse` / `removeSparse` for
-  churny or rare data that shouldn't cause archetype transitions.
-- **Resources** — typed global singletons via `resourceKey<T>`. **Events** — fire-and-forget SoA channels
-  via `eventKey<F>` / `signalKey`, cleared at the end of each `update`.
-- **Cached refs** — `ctx.ref(def, e)` (mutable, bumps the change tick) / `ctx.refRead(def, e)`
-  (read-only): resolve archetype + row + column once, then `pos.x += vel.vx * dt`.
-
-**Determinism, persistence & integration**
-
-- **Determinism** (opt-in) — `new ECS({ deterministic: true })`, then `ecs.snapshots.stateHash()` (an FNV-1a-style
-  32-bit digest over live dense bytes, sparse stores, and multi-relation target sets), `ecs.snapshots.capture()` /
-  `ecs.snapshots.restore(...)`, plus sparse variants. Backing-agnostic: a heap world and a shared world with identical history produce
-  identical hashes.
-- **Host → ECS write seam** — `installHostCommandSeam(ecs)` applies typed `HostCommand`s off-schedule
-  via a blessed `exclusive` system, with record/replay (`HostCommandRecorder`, `replayCommandLog`) and a
-  cross-thread ring transport.
-- **Reactive UI seam** (optional) — a zero-dep signals kernel (`@oasys/oecs/reactive`), an ECS→reactive
-  bridge that publishes only dirty entities/columns (`@oasys/oecs/reactive-sync`), and a SolidJS adapter
-  (`@oasys/oecs/solid`).
-- **Editor layer** — undo/redo + field handles over the write seam (`@oasys/oecs/editor`).
-- **Frame tracing** — `ecs.setTrace(sink)` + `FrameTraceRecorder` for a structured per-frame event
-  stream (dev-gated).
-- **Compute backend seam** — `ecs.attachBackend(...)` to run a system body on a compiled backend (WASM,
-  …) instead of its TS closure.
+- **Deferred in a system, immediate on the host** — `ctx.commands` is a facade in the style of the
+  Bevy `Commands` type. It holds add, remove, despawn, enable, and disable operations until the
+  flush at the end of the phase, so that iterators stay correct. `commands.spawn` gives you the id
+  immediately, but it attaches the components later. Each mutation on the host
+  (`ecs.addComponent`, `ecs.removeComponent`, `ecs.despawn`, `ecs.disable`, and `ecs.enable`)
+  applies immediately.
+- **Enable and disable for an entity** — Use `disable`, `enable`, and `isDisabled`. Disabled rows
+  stay in a partition at the end of the archetype, and queries skip them by default.
+- **Templates and bundles** — `ecs.template(Pos({ x, y }), …)` makes a blueprint. `spawn` and
+  `spawnMany` use that blueprint to create entities with no archetype transition. The same callable
+  bundles are the arguments to `spawnBundle(...)` and `addComponents(...)`.
+
+**Reactions and relationships**
+
+- **Observers** — `ecs.observe(...)` registers `onAdd`, `onRemove`, `onSet`, `onEnable`, and
+  `onDisable` callbacks, for a structure or for one entity.
+- **Relations** — A relation is a `(relation, target)` pair. The presets are `ChildOf` and `IsA`.
+  A relation is exclusive or multi. Queries go in both directions (`targetOf`, `sourcesOf`,
+  `ancestorsOf`, `rootOf`, and `cascadeOf`). The cleanup policy for a deleted target is
+  `delete`, `clear`, or `orphan`. Relations use sparse storage. So they cause no archetype
+  transition, and they use no identity bit.
+- **Sparse storage** — Use `registerSparseComponent` and `registerSparseTag`, then `addSparse` and
+  `removeSparse`. Sparse storage is correct for data that changes frequently or is rare, because it
+  causes no archetype transition.
+- **Resources** — A resource is a typed global value, keyed with `resourceKey<T>`. **Events** are
+  send-and-forget channels in struct-of-arrays form, keyed with `eventKey<F>` or `signalKey`. The
+  ECS clears the events at the end of each `update`.
+- **Cached refs** — `ctx.ref(def, e)` gives you a writable ref, and it sets the change tick.
+  `ctx.refRead(def, e)` gives you a read-only ref. A ref finds the archetype, the row, and the
+  columns one time. Then you can write `pos.x += vel.vx * dt`.
+- **Cursors** — `ctx.cursor(def)` gives you an accessor that you can use again for a different
+  entity. `ctx.cursorRead(def)` gives you the read-only form. The same two functions are on `ecs`.
+  You make a cursor one time. Then each `at(entity)` call moves it to a different entity. Use a
+  cursor when you read or write many entities from a list of ids. The loop then makes no ref for
+  each entity, and the cursor finds the position of each field one time. Each `at` call finds the
+  archetype and the row again. Thus a structural change between two `at` calls cannot make a
+  cursor read a different entity.
+
+**Determinism, storage of state, and integration**
+
+- **Determinism** (optional) — Construct the ECS with `new ECS({ deterministic: true })`. Then use
+  `ecs.snapshots.stateHash()`, which gives a 32-bit digest in FNV-1a style over the live dense
+  bytes, the sparse stores, and the target sets of multi relations. Also use
+  `ecs.snapshots.capture()`, `ecs.snapshots.restore(...)`, and the equivalent functions for sparse
+  data. The hash is independent of the storage type: a heap ECS and a shared ECS with the same
+  history give the same hash.
+- **A write path from the host into the ECS** — `installHostCommandSeam(ecs)` applies typed
+  `HostCommand` values from outside the schedule, through one approved `exclusive` system. It
+  supports record and replay (`HostCommandRecorder` and `replayCommandLog`), and a ring transport
+  between threads.
+- **A reactive UI connection** (optional) — There are three parts. `@oasys/oecs/reactive` is a
+  signals kernel with no dependencies. `@oasys/oecs/reactive-sync` is a bridge from the ECS to that
+  kernel, and it publishes only the changed entities and columns. `@oasys/oecs/solid` is a SolidJS
+  adapter.
+- **An editor layer** — It adds undo, redo, and field handles above the host write path
+  (`@oasys/oecs/editor`).
+- **Frame traces** — `ecs.setTrace(sink)` with `FrameTraceRecorder` gives you a structured stream
+  of the events in each frame. It is available in development builds only.
+- **A compute backend connection** — `ecs.attachBackend(...)` runs the body of a system on a
+  compiled backend, such as WASM, instead of its TypeScript closure.
 
 **Reference**
 
-- **Typed errors** — an `ECSError` taxonomy with a `category` enum and an `isEcsError` guard, all exported.
-- **Reusable primitives** (`@oasys/oecs/primitives`) — `BitSet`, `SparseSet`, `SparseMap`,
-  `GrowableTypedArray`, `BinaryHeap`, and `topologicalSort`, usable standalone.
+- **Typed errors** — There is an `ECSError` taxonomy with a `category` enum and an `isEcsError`
+  guard. The package exports all of them.
+- **Primitives that you can use again** (`@oasys/oecs/primitives`) — `BitSet`, `SparseSet`,
+  `SparseMap`, `GrowableTypedArray`, `BinaryHeap`, and `topologicalSort` also operate alone.
 
 ## Entry points
 
-The core is `@oasys/oecs`; everything else is opt-in and costs nothing until imported.
+The core is `@oasys/oecs`. Each other entry point is optional, and it costs nothing until you
+import it.
 
 | Import | What it is |
 | --- | --- |
-| `@oasys/oecs` | the ECS — pure-TS heap profile by default (production build; dev guards stripped) |
-| `@oasys/oecs/dev` | the same ECS with the dev guards **on** — for a direct guards-on import; see [Dev vs prod](#dev-vs-prod) |
-| `@oasys/oecs/shared` | opt-in `SharedArrayBuffer` allocators for worker offload / a WASM backend (needs COOP/COEP) |
-| `@oasys/oecs/reactive` | zero-dependency reactive kernel (`signal`/`computed`/`effect`, reactive collections) |
-| `@oasys/oecs/reactive-sync` | ECS→reactive bridge — publishes only dirty entities/columns |
-| `@oasys/oecs/editor` | undo/redo + field-handle layer over the host-write seam |
-| `@oasys/oecs/solid` | SolidJS adapter (`solid-js` is an **optional** peer dependency) |
-| `@oasys/oecs/primitives` | the standalone data structures oecs is built on |
-| `@oasys/oecs/internal` | unstable internals (codecs, ABI constants, access checker) — **no semver guarantees** |
-
-## Dev vs prod
-
-A compile-time `__DEV__` flag gates every runtime check — bounds and liveness checks, duplicate-system
-detection, registration validation, and the system access checker (`reads`/`writes`). These are
-**tree-shaken out of production builds**, so treat "throws in dev" as a development tripwire, not a
-production guarantee. The scheduler's cycle detection and constructor-option validation (timestep,
-memory options, relation cardinality) are always active.
-
-**Production is the default on both channels; you opt *into* the guards.** On **npm**, `@oasys/oecs`
-is the stripped production build — dev-mode bundlers (`vite dev`, `webpack --mode development`) pick
-the guards-on build automatically via the `development` export condition, or import `@oasys/oecs/dev`
-for it directly. On **JSR/Deno** (raw source, no bundler) the default is also production
-(`__DEV__ = false`); set `globalThis.__DEV__ = true` before the first import to turn the guards on
-while developing. Full details — including the browser/CDN and manual-override paths — are in the
-[**Development guards & production builds**](docs/PRODUCTION.md) guide.
+| `@oasys/oecs` | the ECS — the pure-TS heap profile by default (a production build, with the development guards removed) |
+| `@oasys/oecs/dev` | the same ECS with the development guards **on** — import this to get the guards directly; see [Development and production](#dev-vs-prod) |
+| `@oasys/oecs/shared` | the optional `SharedArrayBuffer` allocators, for worker offload or a WASM backend (this needs COOP/COEP) |
+| `@oasys/oecs/reactive` | the reactive kernel, which has no dependencies (`signal`, `computed`, `effect`, and reactive collections) |
+| `@oasys/oecs/reactive-sync` | the bridge from the ECS to the kernel — it publishes only the changed entities and columns |
+| `@oasys/oecs/editor` | undo, redo, and field handles above the host write path |
+| `@oasys/oecs/solid` | the SolidJS adapter (`solid-js` is an **optional** peer dependency) |
+| `@oasys/oecs/primitives` | the data structures that oecs is built from, which also operate alone |
+| `@oasys/oecs/internal` | unstable internal parts (codecs, ABI constants, the access checker) — **there are no semver guarantees** |
+
+<a id="dev-vs-prod"></a>
+
+## Development and production
+
+A compile-time flag, `__DEV__`, controls each run-time check. The checks include bounds and
+liveness checks, detection of a system that you added two times, validation at registration, and
+the system access checker for `reads` and `writes`. The build tool **removes these checks from a
+production build**. So, when the documentation says that an operation "throws in development",
+that behavior is a development aid. It is not a production guarantee. Two checks stay active in
+each build: cycle detection in the scheduler, and validation of the constructor options (the
+timestep, the memory options, and the cardinality of a relation).
+
+**Production is the default on both channels. You must turn the guards on.** On **npm**,
+`@oasys/oecs` is the production build, with the guards removed. A bundler in development mode
+(`vite dev` or `webpack --mode development`) selects the build with the guards automatically,
+through the `development` export condition. As an alternative, import `@oasys/oecs/dev` directly.
+On **JSR and Deno** there is no bundler, because the package is raw source. The default is also
+production (`__DEV__ = false`). To turn the guards on while you develop, set
+`globalThis.__DEV__ = true` before the first import. For the full details, which include the
+browser, CDN, and manual paths, read the
+[**Development guards and production builds**](docs/PRODUCTION.md) guide.
 
 ## Documentation
 
-- **New to oecs?** Start with the [Getting Started](docs/GETTING_STARTED.md) tutorial, then
-  [Best Practices](docs/BEST_PRACTICES.md) and the [Architecture](docs/ARCHITECTURE.md) overview.
-- **Using optional extensions?** See the [Extensions guide](docs/EXTENSIONS.md) for reactive UI,
-  editor, Solid, shared-memory, and primitives usage.
-- **Upgrading from 0.4?** See the [Migration guide (0.4 → 0.5)](docs/MIGRATION-0.4-to-0.5.md) and the
-  [CHANGELOG](CHANGELOG.md).
-- **Upgrading from 0.3?** See the [Migration guide (0.3 → 0.4)](docs/MIGRATION-0.3-to-0.4.md).
-- **Full API reference** — start at the [reference index](docs/api/index.md):
+- **If oecs is new to you**, start with the [Getting started](docs/GETTING_STARTED.md) tutorial.
+  Then read [Best practices](docs/BEST_PRACTICES.md) and the
+  [Architecture](docs/ARCHITECTURE.md) overview.
+- **If you use the optional extensions**, read the [Extensions guide](docs/EXTENSIONS.md) for the
+  reactive UI, the editor, Solid, shared memory, and the primitives.
+- **If you upgrade from 0.4**, read the
+  [Migration guide (0.4 to 0.5)](docs/MIGRATION-0.4-to-0.5.md) and the [CHANGELOG](CHANGELOG.md).
+- **If you upgrade from 0.3**, read the
+  [Migration guide (0.3 to 0.4)](docs/MIGRATION-0.3-to-0.4.md).
+- **The full API reference** — Start at the [reference index](docs/api/index.md):
   [components](docs/api/components.md) ·
   [entities](docs/api/entities.md) ·
   [queries](docs/api/queries.md) ·
@@ -219,11 +272,11 @@ while developing. Full details — including the browser/CDN and manual-override
   [determinism](docs/api/determinism.md) ·
   [memory](docs/api/memory.md) ·
   [WASM backends](docs/api/wasm.md) ·
-  [parallelism](docs/api/parallel.md) ·
-  [host-write seam](docs/api/host-write-seam.md) ·
+  [parallel execution](docs/api/parallel.md) ·
+  [the host write path](docs/api/host-write-seam.md) ·
   [reactive](docs/api/reactive.md) ·
   [editor](docs/api/editor.md) ·
-  [tracing](docs/api/tracing.md) ·
+  [traces](docs/api/tracing.md) ·
   [primitives](docs/api/primitives.md) ·
   [errors](docs/api/errors.md)
 
@@ -239,13 +292,13 @@ pnpm exec tsc --noEmit # type check
 
 ## Acknowledgements
 
-oecs stands on the shoulders of the ECS community. Special thanks to:
+oecs is built on the work of the ECS community. We thank:
 
 - **[Bevy](https://bevyengine.org)**, **[Flecs](https://github.com/SanderMertens/flecs)**, and
-  **[bitECS](https://github.com/NateTheGreatt/bitECS)** — a constant source of inspiration; their
-  designs shaped how oecs approaches archetypes, relations, scheduling, and change detection.
-- **[@clinuxrulz](https://github.com/clinuxrulz)** — for his amazing showcase and invaluable input on
-  the ECS.
+  **[bitECS](https://github.com/NateTheGreatt/bitECS)** — a continuous source of ideas. Their
+  designs gave shape to the archetypes, relations, schedule, and change detection in oecs.
+- **[@clinuxrulz](https://github.com/clinuxrulz)** — for an excellent demonstration and for very
+  valuable comments on the ECS.
 
 ## License
 

package/dist/core/ecs/access_check.d.cts

@@ -17,7 +17,7 @@ interface AccessSets {
     relationWrites: Set<number>;
 }
 declare function setsFor(desc: SystemDescriptor): AccessSets;
-/** The reads-only access surface a run condition declares (#576). A condition
+/** The reads-only access surface a run condition declares. A condition
  * can only `reads` components (via a captured query) and `resourceReads`; every
  * mutation set is empty by construction, so the same `check_*` machinery rejects
  * any write/structural/resource-write a misbehaving predicate attempts. */
@@ -32,7 +32,7 @@ declare class AccessCheck {
     private activeName;
     private exclusive;
     enter(desc: SystemDescriptor): void;
-    /** Open a reads-only span for a run condition (#576). No descriptor — a
+    /** Open a reads-only span for a run condition. No descriptor — a
      * condition can gate a whole SystemSet, so it isn't attributable to one
      * system — just its declared reads/resource_reads and a name for diagnostics.
      * Paired with `leave()`. */
@@ -52,7 +52,7 @@ declare class AccessCheck {
     checkSparseWrite(def: SparseComponentDef): void;
     checkRelationRead(def: RelationDef): void;
     checkRelationWrite(def: RelationDef): void;
-    /** A `(*, T)` wildcard (`Query.forEachRelatedTo`, #579) reads every
+    /** A `(*, T)` wildcard (`Query.forEachRelatedTo`) reads every
      * relation's reverse index, so it can't name a specific relation — it is
      * authorised by the `ANY_RELATION` sentinel in `relationReads`. Honoured here
      * exactly like a per-relation read, just keyed on the reserved sentinel id

package/dist/core/ecs/access_check.d.ts

@@ -17,7 +17,7 @@ interface AccessSets {
     relationWrites: Set<number>;
 }
 declare function setsFor(desc: SystemDescriptor): AccessSets;
-/** The reads-only access surface a run condition declares (#576). A condition
+/** The reads-only access surface a run condition declares. A condition
  * can only `reads` components (via a captured query) and `resourceReads`; every
  * mutation set is empty by construction, so the same `check_*` machinery rejects
  * any write/structural/resource-write a misbehaving predicate attempts. */
@@ -32,7 +32,7 @@ declare class AccessCheck {
     private activeName;
     private exclusive;
     enter(desc: SystemDescriptor): void;
-    /** Open a reads-only span for a run condition (#576). No descriptor — a
+    /** Open a reads-only span for a run condition. No descriptor — a
      * condition can gate a whole SystemSet, so it isn't attributable to one
      * system — just its declared reads/resource_reads and a name for diagnostics.
      * Paired with `leave()`. */
@@ -52,7 +52,7 @@ declare class AccessCheck {
     checkSparseWrite(def: SparseComponentDef): void;
     checkRelationRead(def: RelationDef): void;
     checkRelationWrite(def: RelationDef): void;
-    /** A `(*, T)` wildcard (`Query.forEachRelatedTo`, #579) reads every
+    /** A `(*, T)` wildcard (`Query.forEachRelatedTo`) reads every
      * relation's reverse index, so it can't name a specific relation — it is
      * authorised by the `ANY_RELATION` sentinel in `relationReads`. Honoured here
      * exactly like a per-relation read, just keyed on the reserved sentinel id