@adobe/ecs 0.2.1 → 0.2.3

package/dist/world.d.ts

@@ -0,0 +1,27 @@
+import type { Create } from './interface/world/create.js';
+import type { Join } from './interface/world/join.js';
+export type { Table } from './interface/world/table/table.js';
+/**
+ * Creates a world on this thread, synchronously, with resources starting at the given values in place of their
+ * defaults. This thread is its `"world"` thread for the world's life: it runs the sync points, the ticks and the GPU
+ * device, and fills every logical thread no joined thread claims. Keys are the resources' symbols, built-in ones
+ * included (`{ [workers]: 0 }`); string keys are never a resource's, so they're ignored. Throws for a symbol that isn't
+ * a resource, or is one only the world writes. While a declaration's trait or default doesn't hold, each call fails to
+ * compile, once, naming each such key, its members and what's wrong with them.
+ * @function
+ */
+export declare const create: Create;
+/**
+ * Joins, from another thread, a world that `share` let join through the other end of `port`, claiming the logical
+ * `threads` this thread fills: their objects live here, and the systems and finalizers reading them run here. Resolves,
+ * once the world accepted the claim, to the same world: its `run` runs systems there, and its `add` and `remove` take
+ * readonly systems, which run here after the world's sync points. Add them before awaiting anything else, so the
+ * world's `share` resolves with them in place. Its `dispose` disconnects this thread. Rejects with an `Error` saying
+ * why it didn't join: the world refused the claim, was disposed, or its thread ended first, as the platform reports it:
+ * the world's `Worker` failing to start or throwing first, a port closed, as in node, or, in a browser, the world's
+ * thread ending once it was shared through a port this thread listened on. A browser world's worker that the page ended
+ * before this thread heard from it isn't reported, so the join stays pending. Rejects too where memory can't be shared,
+ * as without cross-origin isolation.
+ * @function
+ */
+export declare const join: Join;

package/dist/world.js

@@ -0,0 +1,27 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { create as createWorld, join as joinWorld } from './implementation/index.js';
+/**
+ * Creates a world on this thread, synchronously, with resources starting at the given values in place of their
+ * defaults. This thread is its `"world"` thread for the world's life: it runs the sync points, the ticks and the GPU
+ * device, and fills every logical thread no joined thread claims. Keys are the resources' symbols, built-in ones
+ * included (`{ [workers]: 0 }`); string keys are never a resource's, so they're ignored. Throws for a symbol that isn't
+ * a resource, or is one only the world writes. While a declaration's trait or default doesn't hold, each call fails to
+ * compile, once, naming each such key, its members and what's wrong with them.
+ * @function
+ */
+export const create = createWorld;
+/**
+ * Joins, from another thread, a world that `share` let join through the other end of `port`, claiming the logical
+ * `threads` this thread fills: their objects live here, and the systems and finalizers reading them run here. Resolves,
+ * once the world accepted the claim, to the same world: its `run` runs systems there, and its `add` and `remove` take
+ * readonly systems, which run here after the world's sync points. Add them before awaiting anything else, so the
+ * world's `share` resolves with them in place. Its `dispose` disconnects this thread. Rejects with an `Error` saying
+ * why it didn't join: the world refused the claim, was disposed, or its thread ended first, as the platform reports it:
+ * the world's `Worker` failing to start or throwing first, a port closed, as in node, or, in a browser, the world's
+ * thread ending once it was shared through a port this thread listened on. A browser world's worker that the page ended
+ * before this thread heard from it isn't reported, so the join stays pending. Rejects too where memory can't be shared,
+ * as without cross-origin isolation.
+ * @function
+ */
+export const join = joinWorld;
+//# sourceMappingURL=world.js.map

package/dist/world.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"world.js","sourceRoot":"","sources":["../src/world.ts"],"names":[],"mappings":"AAAA,uDAAuD;AACvD,OAAO,EAAE,MAAM,IAAI,WAAW,EAAE,IAAI,IAAI,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAMrF;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,MAAM,GAAW,WAAW,CAAC;AAE1C;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,IAAI,GAAS,SAAS,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/ecs",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "Adobe ECS",
   "license": "MIT",
   "type": "module",

package/src/exports.test.ts

@@ -50,7 +50,7 @@ export const world: World = World.create({ [workers]: 0 });
 // Another thread joins it through the other end of a channel the world shares.
 declare const port: MessagePort;
 export const joined: Promise<World> = World.join(port, { threads: ["main"] });
-export const read = System.create({ observer: true, components: { with: [position] }, lookup: { at: { with: [position] } } }, () => {});
+export const read = System.create({ readonly: true, components: { with: [position] }, lookup: { at: { with: [position] } } }, () => {});
 export const added = world.add(read);
 `;
 

package/src/guide/00-keys.ts

@@ -23,7 +23,7 @@ const award = System.create({ components: { with: [score] } }, (row, { resources
     row[score] += resources[bonus];
 });
 
-const read = System.create({ observer: true, components: { with: [score] } }, row => {
+const read = System.create({ readonly: true, components: { with: [score] } }, row => {
     console.log("score", row[score]);
 });
 

package/src/guide/01-resources.md

@@ -17,6 +17,6 @@ that isn't data, such as an `AudioContext`, is stored as it is; a change inside
 written back. An `Entity` resource with no entity holds `Entity.none`, which is `0` rather than `null`, so it stays data
 every thread can read.
 
-A system reads resources by key. With `observer: true` it only reads, and runs after the world's changes apply.
+A system reads resources by key. With `readonly: true` it only reads, and runs after the world's changes apply.
 [`run`](01-resources.ts#L31-L32) runs a system once, and resolves to what the body returns, for a system without
 components.

package/src/guide/01-resources.ts

@@ -22,7 +22,7 @@ declare module "@adobe/ecs" {
     }
 }
 
-const read = System.create({ observer: true }, ({ resources }) =>
+const read = System.create({ readonly: true }, ({ resources }) =>
     [resources[gravity], resources[floor], resources[names], resources[audio], resources[focused]]);
 
 export const main = async (): Promise<void> => {

package/src/guide/02-entities.ts

@@ -25,10 +25,10 @@ export const defeat = System.create({ components: { with: [enemy] } }, (row, { c
     commands.remove(row.entity, enemy);
 });
 
-const readFoes = System.create({ observer: true, components: { with: [position, enemy] } }, row => {
+const readFoes = System.create({ readonly: true, components: { with: [position, enemy] } }, row => {
     console.log("a foe at", row[position]);
 });
-const readParticles = System.create({ observer: true, components: { with: [...Particle] } }, row => {
+const readParticles = System.create({ readonly: true, components: { with: [...Particle] } }, row => {
     console.log("a particle moving at", row[velocity]);
 });
 

package/src/guide/03-systems.md

@@ -8,8 +8,8 @@ it in parallel.
   component in `with` and none in `not`, so the `frozen` one stays put. Values are replaced whole, never edited in
   place.
 - **Systems without components**, such as [`count`](03-systems.ts#L35-L37), run once per run.
-- **Observer systems**, `observer: true`, only read. They see what the runs before them left. Run one to read the
-  world, or add one to react to it.
+- **Readonly systems**, `readonly: true`, only read. Run one to read the world, as [`read`](03-systems.ts#L40-L42)
+  does, or add one to react to it. [Sync points](06-sync-points.md) says when and where they run.
 - **Optional components**, `optional: [velocity]`, are in the row where the entity has them and `undefined` where it
   doesn't. They never narrow which entities a system runs on; [`readSpeeds`](03-systems.ts#L44-L47) still reads the
   entity without a velocity. Only commands add and remove them.

package/src/guide/03-systems.out

@@ -1,5 +1,5 @@
 at [ 0, 1, 5 ]
 moving [ 'at 2', 'at 2', 'still' ]
 frames 1
-Error: System "fail" (@adobe/ecs@0.2.1/src/guide/03-systems.ts#fail) failed: broken
+Error: System "fail" (@adobe/ecs@0.2.3/src/guide/03-systems.ts#fail) failed: broken
 frames 2

package/src/guide/03-systems.ts

@@ -37,16 +37,16 @@ const count = System.create({}, ({ resources }) => {
 });
 
 const places: number[] = [];
-const read = System.create({ observer: true, components: { with: [position] } }, row => {
+const read = System.create({ readonly: true, components: { with: [position] } }, row => {
     places.push(row[position][0]);
 });
 
 const speeds: string[] = [];
-const readSpeeds = System.create({ observer: true, components: { with: [position], optional: [velocity] } }, row => {
+const readSpeeds = System.create({ readonly: true, components: { with: [position], optional: [velocity] } }, row => {
     speeds.push(row[velocity] === undefined ? "still" : `at ${row[velocity][0]}`);
 });
 
-const frameCount = System.create({ observer: true }, ({ resources }) => resources[frames]);
+const frameCount = System.create({ readonly: true }, ({ resources }) => resources[frames]);
 
 const fail = System.create(() => {
     throw new Error("broken");

package/src/guide/04-ticks.md

@@ -9,7 +9,7 @@ every tick from then on, and [`world.remove`](04-ticks.ts#L41) takes it off.
   `step` milliseconds, each with that `delta`.
 - A world ticks only after a run arrives, unless `always` is set, as for [the first world](04-ticks.ts#L36).
 
-An observer with `resources: { changed: [elapsed] }` runs after each tick that changed `elapsed`:
+A readonly system with `resources: { changed: [elapsed] }` runs after each tick that changed `elapsed`:
 [`watch`](04-ticks.ts#L18-L21) resolves once 30 ms have passed. Once `advance` is removed, `elapsed` stays put.
 
 **Asking for a tick.** A system that needs another tick contributes a time to the `wake` reduction:

package/src/guide/04-ticks.ts

@@ -16,11 +16,11 @@ const advance = System.create({}, ({ resources }) => {
 });
 
 let reached: (elapsed: number) => void = () => {};
-const watch = System.create({ observer: true, resources: { changed: [elapsed] } }, ({ resources }) => {
+const watch = System.create({ readonly: true, resources: { changed: [elapsed] } }, ({ resources }) => {
     if (resources[elapsed] >= 30) reached(resources[elapsed]);
 });
 
-const readTime = System.create({ observer: true }, ({ resources }) => ({ elapsed: resources[elapsed], delta: resources[clock].delta }));
+const readTime = System.create({ readonly: true }, ({ resources }) => ({ elapsed: resources[elapsed], delta: resources[clock].delta }));
 
 const step = System.create({}, ({ resources, reduce }) => {
     resources[steps] += 1;
@@ -28,7 +28,7 @@ const step = System.create({}, ({ resources, reduce }) => {
 });
 
 let finished: (steps: number) => void = () => {};
-const watchSteps = System.create({ observer: true, resources: { changed: [steps] } }, ({ resources }) => {
+const watchSteps = System.create({ readonly: true, resources: { changed: [steps] } }, ({ resources }) => {
     if (resources[steps] === 3) finished(resources[steps]);
 });
 

package/src/guide/05-scheduling.ts

@@ -20,7 +20,7 @@ const heal = System.create({ components: { with: [health] }, after: [hit] }, row
 });
 const frame = System.create([heal, hit]);
 
-const read = System.create({ observer: true, components: { with: [health] } }, row => {
+const read = System.create({ readonly: true, components: { with: [health] } }, row => {
     console.log("health", row[health]);
 });
 

package/src/guide/06-sync-points.md

@@ -10,5 +10,12 @@ A run ends at a *sync point*, where its commands apply.
 A composite is one run with one sync point. In [`frame`](06-sync-points.ts#L25), `count` runs `after: [spawn]` but
 before the spawned entities exist, so it counts none; run alone, after the sync point, it counts the hero.
 
-An observer added to a world runs after the sync point of every run and tick, reading what it left:
-[`watch`](06-sync-points.ts#L39-L41) logs the hero after the run that spawned it.
+**Readonly systems.** `readonly: true` places a system after the sync point, so it reads what the commands did. Added
+to a world, [`watch`](06-sync-points.ts#L27-L29) runs after the sync point of every run and tick, and logs the hero
+after the run that spawned it; `count`, which isn't readonly, runs before the sync point, in its tier.
+
+- **Where:** a readonly system runs on the thread that added or ran it, so a [joined thread](19-threads.md) adds only
+  readonly systems.
+- **Order:** none. It can't declare `before`, `after` or `during`.
+- **Limits:** it can't write, use `commands` or `reduce`, or take input. Its row and resources are read-only, so each
+  is a type error.

package/src/guide/06-sync-points.ts

@@ -24,10 +24,10 @@ const count = System.create({ components: { with: [health] }, after: [spawn] },
 });
 const frame = System.create([spawn, count]);
 
-const watch = System.create({ observer: true, components: { with: [health] } }, row => {
+const watch = System.create({ readonly: true, components: { with: [health] } }, row => {
     console.log("health", row[health]);
 });
-const readSeen = System.create({ observer: true }, ({ resources }) => resources[seen]);
+const readSeen = System.create({ readonly: true }, ({ resources }) => resources[seen]);
 
 export const main = async (): Promise<void> => {
     await using world = World.create();

package/src/guide/07-change-filters.ts

@@ -36,7 +36,7 @@ const bump = System.create({ components: { with: [score, boss] } }, row => {
 });
 
 let loaded = 0;
-const countLoaded = System.create({ observer: true, components: { with: [shown] } }, () => {
+const countLoaded = System.create({ readonly: true, components: { with: [shown] } }, () => {
     loaded += 1;
 });
 
@@ -45,7 +45,7 @@ const step = System.create({ resources: { is: [map], not: [paused] } }, ({ resou
 });
 const pause = System.create({}, ({ resources }) => { resources[paused] = true; });
 const open = System.create({}, ({ resources }) => { resources[map] = { width: 4 }; });
-const readSteps = System.create({ observer: true }, ({ resources }) => resources[steps]);
+const readSteps = System.create({ readonly: true }, ({ resources }) => resources[steps]);
 
 export const main = async (): Promise<void> => {
     await using world = World.create();

package/src/guide/08-input.ts

@@ -30,7 +30,7 @@ const heal = System.create({
 });
 
 const healths: number[] = [];
-const read = System.create({ observer: true, components: { with: [health] } }, row => {
+const read = System.create({ readonly: true, components: { with: [health] } }, row => {
     healths.push(row[health]);
 });
 

package/src/guide/09-rules.ts

@@ -31,7 +31,7 @@ const hide = System.create({ components: { with: [sprite] } }, (row, { commands
 });
 
 const drawing: string[] = [];
-const read = System.create({ observer: true, components: { with: [layer, drawn], optional: [mesh, sprite] } }, row => {
+const read = System.create({ readonly: true, components: { with: [layer, drawn], optional: [mesh, sprite] } }, row => {
     drawing.push(`${row[mesh] === undefined ? `sprite ${row[sprite]}` : `mesh ${row[mesh]}`} on layer ${row[layer]}`);
 });
 /** Logs what's drawn, in order. */

package/src/guide/11-traits.ts

@@ -33,9 +33,9 @@ const destroy = System.create({ components: { with: [ship] } }, (row, { commands
 });
 
 const counts = { outlined: 0, targeting: 0, entities: 0 };
-const countOutlined = System.create({ observer: true, components: { with: [outline] } }, () => { counts.outlined += 1; });
-const countTargeting = System.create({ observer: true, components: { with: [target] } }, () => { counts.targeting += 1; });
-const countAll = System.create({ observer: true, components: {} }, () => { counts.entities += 1; });
+const countOutlined = System.create({ readonly: true, components: { with: [outline] } }, () => { counts.outlined += 1; });
+const countTargeting = System.create({ readonly: true, components: { with: [target] } }, () => { counts.targeting += 1; });
+const countAll = System.create({ readonly: true, components: {} }, () => { counts.entities += 1; });
 const count = System.create([countOutlined, countTargeting, countAll]);
 
 export const main = async (): Promise<void> => {

package/src/guide/12-lookups.ts

@@ -25,7 +25,7 @@ const track = System.create({
 
 const refreshed: boolean[] = [];
 const watch = System.create({
-    observer: true,
+    readonly: true,
     components: { with: [target] },
     lookup: { enemy: { with: [health], changed: [health] } },
 }, (row, { lookup }) => {
@@ -34,7 +34,7 @@ const watch = System.create({
 });
 
 const aims: number[] = [];
-const readAims = System.create({ observer: true, components: { with: [aim] } }, row => {
+const readAims = System.create({ readonly: true, components: { with: [aim] } }, row => {
     aims.push(row[aim]);
 });
 

package/src/guide/13-indexes.ts

@@ -26,14 +26,14 @@ const count = System.create({ components: { with: [cell, crowded] }, lookup: { a
 
 const byScore = Index.create({ key: [score], sorted: true, components: { with: [player] } });
 
-const leaders = System.create({ observer: true, lookup: { scores: { index: byScore } } }, ({ lookup }) => {
+const leaders = System.create({ readonly: true, lookup: { scores: { index: byScore } } }, ({ lookup }) => {
     const winners: string[] = [];
     const high = lookup.scores({ ">=": 90 });
     for (let i = 0; i < high.length; i++) winners.push(high.at(i)[player]);
     return winners;
 });
 
-const list = System.create({ observer: true, components: { with: [player, score] }, order: byScore }, row => {
+const list = System.create({ readonly: true, components: { with: [player, score] }, order: byScore }, row => {
     console.log(row[player], row[score]);
 });
 
@@ -42,12 +42,12 @@ const find = System.create({ lookup: { byId: { index: byServerId } } }, ({ looku
     lookup.byId(input.id)?.[player] ?? null);
 
 const players = Index.create({ key: [], components: { with: [player] } });
-const countPlayers = System.create({ observer: true, lookup: { players: { index: players, changed: true } } }, ({ lookup }) => {
+const countPlayers = System.create({ readonly: true, lookup: { players: { index: players, changed: true } } }, ({ lookup }) => {
     console.log("players", lookup.players().length);
 });
 
 const crowds: number[] = [];
-const readCrowds = System.create({ observer: true, components: { with: [crowded] } }, row => {
+const readCrowds = System.create({ readonly: true, components: { with: [crowded] } }, row => {
     crowds.push(row[crowded]);
 });
 

package/src/guide/14-kernels.ts

@@ -29,7 +29,7 @@ const slow = System.create({ kernel: false, components: { with: [velocity] } },
 });
 
 const moved: string[] = [];
-const read = System.create({ observer: true, components: { with: [position, velocity] } }, row => {
+const read = System.create({ readonly: true, components: { with: [position, velocity] } }, row => {
     moved.push(`at ${row[position][0]}, moving at ${row[velocity][0]}`);
 });
 

package/src/guide/15-reductions.ts

@@ -23,7 +23,7 @@ const weigh = System.create({ components: { with: [mass] } }, (row, { reduce })
     reduce[count](1);
 });
 
-const report = System.create({ observer: true }, ({ resources }) =>
+const report = System.create({ readonly: true }, ({ resources }) =>
     `${resources[count]} weigh ${resources[total]}, at most ${resources[heaviest]}`);
 
 const spawn = System.create(({ commands }) => {

package/src/guide/16-gpu.ts

@@ -32,7 +32,7 @@ const draw = System.render({ shader: { accessors: { dotPosition: position, dotSi
 });
 const shaderCode = Gpu.wgsl(draw);
 
-const read = System.create({ observer: true, components: { with: [position] } }, row => {
+const read = System.create({ readonly: true, components: { with: [position] } }, row => {
     console.log("at", row[position]);
 });
 

package/src/guide/17-hierarchies.ts

@@ -21,7 +21,7 @@ const place = System.create({ components: { with: [offset, placed] }, up: { thro
 });
 
 const where: string[] = [];
-const read = System.create({ observer: true, components: { with: [label, placed] } }, row => {
+const read = System.create({ readonly: true, components: { with: [label, placed] } }, row => {
     where.push(`${row[label]} at ${row[placed]}`);
 });
 

package/src/guide/18-identity.out

@@ -1 +1 @@
-Error: System "explode" (@adobe/ecs@0.2.1/src/guide/18-identity.ts#explode) failed: boom
+Error: System "explode" (@adobe/ecs@0.2.3/src/guide/18-identity.ts#explode) failed: boom

package/src/guide/19-threads.md

@@ -11,6 +11,8 @@ A *logical thread* is where objects live and the code touching them runs: the pa
 `World.join(port, { threads: ["audio"] })`, claiming the threads it fills. Usually the other end of the channel goes
 to a worker; [here both ends](19-threads.ts#L44-L54) are on one thread.
 
-- `share` resolves once the thread joined, with the observer systems it added as `join` resolved, before awaiting
-  anything else. Those observers run there after the world's sync points: `listen` hears what `mix` wrote.
+- `share` resolves once the thread joined, with the readonly systems it added as `join` resolved, before awaiting
+  anything else. Those readonly systems run there after the world's sync points: `listen` hears what `mix` wrote.
+- A joined thread adds only [readonly systems](03-systems.md), which run on it; a system that writes is added on the
+  world's thread.
 - A joined world runs systems as the world does: [`audio.run`](19-threads.ts#L60-L61) spawns and mixes too.

package/src/guide/19-threads.ts

@@ -22,7 +22,7 @@ const mix = System.create({ components: { with: [volume] } }, (row, { resources
 });
 
 let heard = 0;
-const listen = System.create({ observer: true }, ({ resources }) => {
+const listen = System.create({ readonly: true }, ({ resources }) => {
     heard = resources[levels].size;
 });
 
@@ -31,7 +31,7 @@ const spawn = System.create(({ commands }) => {
     commands.spawn([volume])({ [volume]: 0.3 });
 });
 
-const countVoices = System.create({ observer: true }, ({ resources }) => resources[levels].size);
+const countVoices = System.create({ readonly: true }, ({ resources }) => resources[levels].size);
 
 /** Waits a turn of the event loop at a time until `done`, for two seconds at most. */
 const until = async (done: () => boolean): Promise<void> => {

package/src/guide/20-shared.ts

@@ -56,7 +56,7 @@ let drawn = 0;
 let left = Infinity;
 let right = -Infinity;
 const draw = System.create({
-    observer: true,
+    readonly: true,
     components: { with: [position], where: { [cell]: (at, { resources }) => resources[camera]?.sees(at) === true } },
 }, row => {
     drawn += 1;
@@ -66,7 +66,7 @@ const draw = System.create({
 
 let refreshed = 0;
 const refresh = System.create({
-    observer: true,
+    readonly: true,
     components: { with: [position], changed: [position], where: { [cell]: (at, { resources }) => resources[camera]?.sees(at) === true } },
 }, () => {
     refreshed += 1;
@@ -74,7 +74,7 @@ const refresh = System.create({
 
 // Only chunk [4, 0], which no unit is in until one crosses into it.
 let east = 0;
-const countEast = System.create({ observer: true, components: { with: [position], where: { [cell]: [4, 0] } } }, () => {
+const countEast = System.create({ readonly: true, components: { with: [position], where: { [cell]: [4, 0] } } }, () => {
     east += 1;
 });
 

package/src/guide/21-dom.md

@@ -13,9 +13,9 @@ same.
 Each tick runs one composite:
 
 1. [`move`](21-dom.ts#L38-L44) moves every particle and turns it back from the walls.
-2. [`create`](21-dom.ts#L46-L51) gives each particle without a dot an element, with `commands.add`. Observers can't
+2. [`create`](21-dom.ts#L46-L51) gives each particle without a dot an element, with `commands.add`. Readonly systems can't
    issue commands, so it ticks, and its condition `is: [stage]` waits for a stage.
-3. [`draw`](21-dom.ts#L52-L60), an observer, sets each moved dot's `style.translate`, a transform, which the page
+3. [`draw`](21-dom.ts#L52-L60), a readonly system, sets each moved dot's `style.translate`, a transform, which the page
    doesn't lay out again. `changed: [position]` skips the dots that didn't move.
 
 [A finalizer](21-dom.ts#L61-L63) removes a particle's element when the particle goes, and every element when the

package/src/guide/21-dom.ts

@@ -51,7 +51,7 @@ const create = System.create({ components: { with: [position], not: [dot] }, res
 });
 // Moves each dot whose particle moved, by a transform, which the page doesn't lay out again.
 const draw = System.create({
-    observer: true,
+    readonly: true,
     components: { with: [position, dot], optional: [traced], changed: [position] },
 }, (row, { resources }) => {
     const [x, y] = row[position];

package/src/guide/22-canvas.md

@@ -2,7 +2,7 @@
 
 The same particles, drawn in immediate mode: each frame, the canvas is cleared and drawn again whole.
 
-[`draw`](22-canvas.ts#L52-L80) is one observer without components, so it runs once per tick, not per particle.
+[`draw`](22-canvas.ts#L52-L80) is one readonly system without components, so it runs once per tick, not per particle.
 
 - `changed: [clock]` runs it after every tick, and `is: [pen]` waits for a 2D context.
 - It reads every particle through [an index without a key](22-canvas.ts#L50-L51), `key: []`, and the traced one

package/src/guide/22-canvas.ts

@@ -51,7 +51,7 @@ const particles = Index.create({ key: [], components: { with: [position] } });
 const tracedOnes = Index.create({ key: [], components: { with: [position, traced] } });
 // Clears the canvas and draws every particle, after each tick.
 const draw = System.create({
-    observer: true,
+    readonly: true,
     resources: { is: [pen], changed: [clock] },
     lookup: { particles: { index: particles }, traced: { index: tracedOnes } },
 }, ({ resources, lookup }) => {

package/src/guide/CLAUDE.md

@@ -45,5 +45,5 @@ it in `NN-name.type-test.ts`, under a `// @ts-expect-error` that the package's b
   before they're printed.
 - Keys are `Symbol()` with no description: the build's id names each by its binding.
 - Archetypes are types, so their names are PascalCase: `const Particle = [position, velocity] as const`.
-- Use the public API only, as a consumer imports it, not internal modules. Read a world through observer systems.
+- Use the public API only, as a consumer imports it, not internal modules. Read a world through readonly systems.
 - Lines change as code does: the test of links fails on any that no longer covers whole code, so move them with it.

package/src/guide/guide.test.ts

@@ -69,12 +69,12 @@ const listed = [...read("README.md").matchAll(/^(?:- |(\d+)\. )\[([^\]]+)\]\(([^
 /** What each chapter teaches, which its prose names as code and its program does; 0 is the unnumbered keys chapter's. */
 const teaches: { readonly [chapter: number]: readonly string[] } = {
     0: ["Symbol()", "declare module \"@adobe/ecs\"", "Components", "Resources", "row[score]", "resources[bonus]", "default"],
-    1: ["Resources", "default", "World.create", "observer: true", "run", "ReadonlyMap", "Entity"],
+    1: ["Resources", "default", "World.create", "readonly: true", "run", "ReadonlyMap", "Entity"],
     2: ["Components", "type: true", "as const", "commands.spawn", "commands.remove", "with: [...Particle]"],
-    3: ["System.create", "with", "not", "observer: true", "optional: [velocity]"],
+    3: ["System.create", "with", "not", "readonly: true", "optional: [velocity]"],
     4: ["clock", "delta", "cadence", "always", "resources: { changed: [elapsed] }", "wake", "reduce[wake]", "world.add", "world.remove"],
     5: ["after", "during", "System.create([heal, hit])", "during: [update]"],
-    6: ["commands.spawn", "commands.add", "commands.despawn", "after: [spawn]"],
+    6: ["commands.spawn", "commands.add", "commands.despawn", "after: [spawn]", "readonly: true"],
     7: ["resources: { changed: [level] }", "changed: [score]", "resources: { is: [map], not: [paused] }", "resources[map]"],
     8: ["world.run(hit, { amount: 3 })", "target: \"entity\""],
     9: ["Rule.create", "derived: true"],
@@ -106,10 +106,12 @@ const mutations: { readonly [chapter: number]: readonly (readonly [string, strin
     ],
     1: [["World.create({ [gravity]: -1.6 })", "World.create()"], ["default: -9.8 ", ""], ["{ default: -Infinity }", "{}"]],
     2: [["commands.remove(row.entity, enemy);", ""], ["{ [position]: [0, 10, 0] }", "{}"]],
-    3: [["not: [frozen]", "not: []"], ["System.create([count, fail])", "System.create([fail])"]],
+    3: [
+        ["not: [frozen]", "not: []"], ["System.create([count, fail])", "System.create([fail])"],
+    ],
     4: [["world.remove(advance);", ""]],
     5: [["after: [hit] ", ""], ["during: [update] ", ""]],
-    6: [["commands.add(hero, health, 5);", ""], ["commands.despawn(commands.spawn([health])({ [health]: 1 }));", "commands.spawn([health])({ [health]: 1 });"], ["watched.add(watch);", ""]],
+    6: [["commands.add(hero, health, 5);", ""], ["commands.despawn(commands.spawn([health])({ [health]: 1 }));", "commands.spawn([health])({ [health]: 1 });"], ["watched.add(watch);", ""], ["const watch = System.create({ readonly: true, ", "const watch = System.create({ "]],
     7: [["resources: { changed: [level] } ", ""], [", changed: [score]", ""], [", not: [paused]", ""], ["is: [map], ", ""]],
     8: [["target: \"entity\",", ""]],
     9: [["with: [mesh], not: [hidden]", "with: [mesh]"], ["Rule.create({ components: { with: [sprite], not: [hidden] }, derive: [drawn] });", ""], ["Rule.create({ components: { with: [drawn] }, derive: [layer] });", ""]],

package/src/implementation/compiler/describe.test-helper.ts

@@ -51,7 +51,7 @@ export const spawn = System.create(({ commands }) => {
     commands.spawn([position, velocity])({ [position]: [0, 0, 0], [velocity]: [1, 0, 0] });
 });
 
-export const observe = System.create({ observer: true, components: { with: [position] } }, row => {
+export const observe = System.create({ readonly: true, components: { with: [position] } }, row => {
     console.log(row[position]);
 });
 

package/src/implementation/compiler/describe.test.ts

@@ -109,7 +109,7 @@ describe("a module's systems described", () => {
     it("says why systems that run as written have no code: per-run systems, observers, render systems, kernel: false and one declared in a function", () => {
         expect(described("spawn")).toMatchObject({ kind: "per-run", runs: `Its body as written, on the "world" thread` });
         for (const backend of ["js", "wasm", "wgsl"] as const) expect(reasonOf(described("spawn")[backend])).toBe("per-run systems run as written; only row systems compile");
-        expect(described("observe")).toMatchObject({ kind: "observer", js: { kind: "none", reason: expect.stringMatching(/^an observer runs as written/) } });
+        expect(described("observe")).toMatchObject({ kind: "readonly", js: { kind: "none", reason: expect.stringMatching(/^a readonly system runs as written/) } });
         expect(described("draw")).toMatchObject({ kind: "render", runs: expect.stringContaining("while the world has a GPU device"), wgsl: { kind: "none", reason: expect.stringMatching(/^a render system runs as written/) } });
         const unflagged = described("unflagged");
         expect(unflagged).toMatchObject({ kernel: false, js: { kind: "none", reason: "as written, because `kernel: false`" }, wasm: { kind: "none", reason: "as written, because `kernel: false`" }, wgsl: { kind: "eligible" } });

package/src/implementation/compiler/describe.ts

@@ -30,7 +30,7 @@ export type Backend =
  * What runs a system: over every matched row, once per run, as an observer, on one entity its input names (`target`),
  * or as a render system.
  */
-export type SystemKind = "row" | "per-run" | "observer" | "target" | "render";
+export type SystemKind = "row" | "per-run" | "readonly" | "target" | "render";
 
 /**
  * A system of a module as the build compiles it: its call's offsets in the code transformed, the binding it's
@@ -427,7 +427,7 @@ export const describeSystems = async (sites: TransformedSites, format: (code: st
         const kernel: boolean | "gpu" | null = literal === true || literal === false ? literal : literal === "gpu" ? "gpu" : null;
         const kind: SystemKind = created === "render" ? "render"
             : declaration === undefined ? "per-run"
-            : propertyOf(declaration, "observer") !== null ? "observer"
+            : propertyOf(declaration, "readonly") !== null ? "readonly"
             : propertyOf(declaration, "target") !== null ? "target"
             : propertyOf(declaration, "components") !== null ? "row" : "per-run";
         const base = { start: node.start, end: node.end, binding: bindings.get(node) ?? null, kind, kernel };
@@ -442,7 +442,7 @@ export const describeSystems = async (sites: TransformedSites, format: (code: st
             ? threadOf(declaration, body, kind === "render" ? positionsOf("render", declaration) : positionsOf("system", declaration)) : "world";
         if (kind === "render") return asWritten("a render system runs as written, recording GPU work with shaders of your own; `Gpu.wgsl` gives them their accessors", "world");
         if (kind === "per-run") return asWritten("per-run systems run as written; only row systems compile", written());
-        if (kind === "observer") return asWritten("an observer runs as written, reading the settled state after the run's last sync point; only row systems that aren't observers compile", written());
+        if (kind === "readonly") return asWritten("a readonly system runs as written, reading the settled state after the run's last sync point; only row systems that aren't readonly compile", written());
         if (kind === "target") return asWritten("a system with `target` runs as written, once, on the entity its input names; only systems over every matched row compile", written());
         if (declaration === undefined || body === undefined || body.type === "SpreadElement" || !isFunction(body)) {
             return asWritten(declaration === undefined ? "its declaration isn't written in its call, so the build can't read whether it's a kernel" : "its body isn't a function written in place or bound at module scope, so the build can't read it", "world");

package/src/implementation/compiler/hygiene.test.ts

@@ -34,7 +34,7 @@ const spawn = System.create(({ commands }) => {
 });
 
 const read: number[][] = [];
-const readAll = System.create({ observer: true, components: { with: [p, c, l, s, e, v0, v1] } }, row => {
+const readAll = System.create({ readonly: true, components: { with: [p, c, l, s, e, v0, v1] } }, row => {
     read.push([row[p], row[c], row[l], row[s], row[e], row[v0], row[v1]]);
 });