@adobe/ecs 0.0.0-stage → 0.2.0

package/src/guide/17-hierarchies.ts

@@ -0,0 +1,40 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { Entity, System, World } from "../index.js";
+
+const parent = Symbol();
+const offset = Symbol();
+const placed = Symbol();
+const label = Symbol();
+
+declare module "@adobe/ecs" {
+    interface Components {
+        // Despawned with its parent.
+        [parent]: { type: Entity; reference: "owner" };
+        [offset]: { type: number };
+        [placed]: { type: number };
+        [label]: { type: string };
+    }
+}
+
+const place = System.create({ components: { with: [offset, placed] }, up: { through: parent } }, (row, { up }) => {
+    row[placed] = (up === null ? 0 : up[placed]) + row[offset];
+});
+
+const where: string[] = [];
+const read = System.create({ observer: true, components: { with: [label, placed] } }, row => {
+    where.push(`${row[label]} at ${row[placed]}`);
+});
+
+const spawn = System.create(({ commands }) => {
+    const table = commands.spawn([label, offset, placed])({ [label]: "table", [offset]: 10, [placed]: 0 });
+    const tray = commands.spawn([label, offset, placed, parent])({ [label]: "tray", [offset]: 2, [placed]: 0, [parent]: table });
+    commands.spawn([label, offset, placed, parent])({ [label]: "cup", [offset]: 1, [placed]: 0, [parent]: tray });
+});
+
+export const main = async (): Promise<void> => {
+    await using world = World.create();
+    await world.run(spawn);
+    await world.run(place);
+    await world.run(read);
+    console.log(where.sort().join(", "));
+};

package/src/guide/18-identity.md

@@ -0,0 +1,10 @@
+# Identity and ids
+
+A key, system, index, rule or finalizer is the value its constructor returns. Two written alike are two, and code
+written apart can't collide.
+
+The build gives each one bound at a module's top level an *id*: its package's name and version, its module's path,
+and its binding. Other threads, and a module evaluated again by hot reload, name the same one by it.
+
+What fails is named by its binding, with its id beside it to tell two of one name apart, as
+[`explode`](18-identity.ts#L4-L6)'s error shows.

package/src/guide/18-identity.out

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

package/src/guide/18-identity.ts

@@ -0,0 +1,11 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { System, World } from "../index.js";
+
+const explode = System.create(() => {
+    throw new Error("boom");
+});
+
+export const main = async (): Promise<void> => {
+    await using world = World.create();
+    await world.run(explode).catch((error: unknown) => console.log(String(error)));
+};

package/src/guide/19-threads.md

@@ -0,0 +1,16 @@
+# Threads
+
+A *logical thread* is where objects live and the code touching them runs: the page's `"main"`, or one you declare in
+[`interface Threads`](19-threads.ts#L7-L17). `thread: "audio"` places a component or resource on it.
+
+- A system runs on the thread its objects live on: [`mix`](19-threads.ts#L19-L22) writes `levels`, so it runs on
+  `audio`.
+- A run reading objects on another thread runs there, and resolves to a copy of what it returns.
+
+**Joining.** A world shares itself over a message port, `world.share(port)`, and another thread joins it with
+`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.
+- 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.out

@@ -0,0 +1,2 @@
+mixed 2 voices; listening hears 2
+mixed 4 voices; listening hears 4

package/src/guide/19-threads.ts

@@ -0,0 +1,65 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { System, World } from "../index.js";
+
+const volume = Symbol();
+const levels = Symbol();
+
+declare module "@adobe/ecs" {
+    interface Threads {
+        audio: true;
+    }
+    interface Components {
+        [volume]: { type: number };
+    }
+    interface Resources {
+        [levels]: { type: ReadonlyMap<string, number>; thread: "audio" };
+    }
+}
+
+// Runs on audio, where levels lives.
+const mix = System.create({ components: { with: [volume] } }, (row, { resources }) => {
+    resources[levels] = new Map([...resources[levels], [`voice ${row.entity}`, row[volume]]]);
+});
+
+let heard = 0;
+const listen = System.create({ observer: true }, ({ resources }) => {
+    heard = resources[levels].size;
+});
+
+const spawn = System.create(({ commands }) => {
+    commands.spawn([volume])({ [volume]: 0.8 });
+    commands.spawn([volume])({ [volume]: 0.3 });
+});
+
+const countVoices = System.create({ observer: 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> => {
+    const end = performance.now() + 2000;
+    while (!done() && performance.now() < end) await new Promise(resolve => setTimeout(resolve, 1));
+};
+
+export const main = async (): Promise<void> => {
+    // Usually one end of the channel goes to a worker, `new Worker(...)`, which joins with the other.
+    const channel = new MessageChannel();
+    await using world = World.create();
+    // Each side awaits its own end, here both on one thread.
+    const [joined] = await Promise.all([
+        World.join(channel.port2, { threads: ["audio"] }).then(audio => {
+            audio.add(listen);
+            return audio;
+        }),
+        world.share(channel.port1),
+    ]);
+    await using audio = joined;
+    await world.run(spawn);
+    await world.run(mix);
+    const mixed = await world.run(countVoices);
+    await until(() => heard === mixed);
+    console.log("mixed", mixed, "voices; listening hears", heard);
+    await audio.run(spawn);
+    await audio.run(mix);
+    const more = await world.run(countVoices);
+    await until(() => heard === more);
+    console.log("mixed", more, "voices; listening hears", heard);
+};

package/src/guide/20-shared.md

@@ -0,0 +1,29 @@
+# Shared components and where
+
+A *shared* component's value belongs to its archetype: entities with equal values share one archetype, which holds the
+value once. [`cell`](20-shared.ts#L16), declared `shared: true`, is the chunk of the world a unit is in, so each
+chunk's units share an archetype.
+
+- A spawner's first call takes *constants*, values every entity it spawns starts with:
+  [`commands.spawn(Unit, { [cell]: [x, y], ... })`](20-shared.ts#L31-L39). The shared ones choose the archetype; the
+  others, here every unit's velocity, start each entity's own value. The spawner's call takes the rest.
+- A row reads `row[cell]` as its archetype's value, read-only: [`place`](20-shared.ts#L41-L43) reads it, and as a
+  kernel takes it as a parameter of each call over an archetype, not as a column.
+- Assigning a shared component is a type error. `commands.add` with another value
+  [moves the entity](20-shared.ts#L49-L53) to that value's archetype, creating it if needed.
+
+**`where`** keeps a system to the archetypes whose shared values pass:
+
+- A value passes the archetypes holding an equal one: [`where: { [cell]: [4, 0] }`](20-shared.ts#L77-L79) counts only
+  the chunk the step's crossing units move into.
+- A predicate of the value and the resources passes those it returns `true` for: [`draw`](20-shared.ts#L58-L65) visits
+  only the chunks the camera sees.
+
+A predicate runs once per archetype as the archetype appears, and again for every archetype only after a resource it
+reads changed, never per row or per run. The camera counts what it's asked: every chunk for each of the two systems at
+first, only the new chunks after the step, nothing while nothing changed, and every chunk again once
+[`look`](20-shared.ts#L92-L94) writes a new camera. Since the world caches the results, the build rejects a predicate
+that reads anything but its value, the resources and module constants.
+
+With a change filter, a chunk out of view keeps its rows unseen: [`refresh`](20-shared.ts#L67-L73) counts, when the
+camera moves, the rows that changed while their chunk was out of view, through `changed: [position]`.

package/src/guide/20-shared.out

@@ -0,0 +1,4 @@
+start: drew 18 from x -8 to 17 refreshed 18 east 0 asked 98
+after a step: drew 18 from x -9 to 16 refreshed 18 east 1 asked 14
+unchanged: drew 18 from x -9 to 16 refreshed 0 east 1 asked 0
+camera moved: drew 18 from x 11 to 36 refreshed 16 east 1 asked 112

package/src/guide/20-shared.ts

@@ -0,0 +1,118 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { System, Vec2, World } from "../index.js";
+
+const cell = Symbol();
+const offset = Symbol();
+const velocity = Symbol();
+const position = Symbol();
+const camera = Symbol();
+
+/** A camera, as a renderer would give one: which chunks of the world it sees. */
+type Camera = { readonly sees: (chunk: Vec2.I32) => boolean };
+
+declare module "@adobe/ecs" {
+    interface Components {
+        // The chunk of the world an entity is in: each chunk's entities share an archetype.
+        [cell]: { type: Vec2.I32; shared: true };
+        // Where an entity is within its chunk, and in the world.
+        [offset]: { type: Vec2 };
+        [velocity]: { type: Vec2 };
+        [position]: { type: Vec2 };
+    }
+    interface Resources {
+        [camera]: { type: Camera | null };
+    }
+}
+
+const size = 10;
+const Unit = [cell, offset, velocity, position] as const;
+
+// Two units in each of 7 × 7 chunks, all moving east.
+const populate = System.create(({ commands }) => {
+    for (let x = -3; x <= 3; x++) {
+        for (let y = -3; y <= 3; y++) {
+            const spawn = commands.spawn(Unit, { [cell]: [x, y], [velocity]: [4, 0], [position]: [0, 0] });
+            spawn({ [offset]: [2, 3] });
+            spawn({ [offset]: [7, 8] });
+        }
+    }
+});
+
+const place = System.create({ components: { with: [cell, offset, position] } }, row => {
+    row[position] = Vec2.add(Vec2.scale([row[cell][0], row[cell][1]], size), row[offset]);
+});
+
+const drift = System.create({ components: { with: [offset, velocity] } }, row => {
+    row[offset] = Vec2.add(row[offset], row[velocity]);
+});
+
+// A unit past its chunk's edge moves into the next chunk.
+const cross = System.create({ components: { with: [cell, offset] } }, (row, { commands }) => {
+    const [x, y] = row[offset];
+    if (x >= size) commands.add(row.entity, [cell, offset], { [cell]: [row[cell][0] + 1, row[cell][1]], [offset]: [x - size, y] });
+});
+
+let drawn = 0;
+let left = Infinity;
+let right = -Infinity;
+const draw = System.create({
+    observer: true,
+    components: { with: [position], where: { [cell]: (at, { resources }) => resources[camera]?.sees(at) === true } },
+}, row => {
+    drawn += 1;
+    left = Math.min(left, row[position][0]);
+    right = Math.max(right, row[position][0]);
+});
+
+let refreshed = 0;
+const refresh = System.create({
+    observer: true,
+    components: { with: [position], changed: [position], where: { [cell]: (at, { resources }) => resources[camera]?.sees(at) === true } },
+}, () => {
+    refreshed += 1;
+});
+
+// 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] } } }, () => {
+    east += 1;
+});
+
+/** How many chunks cameras were asked about. */
+let asked = 0;
+
+/** A camera over a chunk, seeing the chunks within `radius` of it. */
+const cameraOver = ([overX, overY]: readonly [number, number], radius: number): Camera => ({
+    sees: ([x, y]) => {
+        asked += 1;
+        return Math.max(Math.abs(x - overX), Math.abs(y - overY)) <= radius;
+    },
+});
+
+const look = System.create({}, ({ resources }, input: { readonly x: number; readonly y: number }) => {
+    resources[camera] = cameraOver([input.x, input.y], 1);
+});
+
+const report = async (world: World, what: string): Promise<void> => {
+    drawn = refreshed = east = asked = 0;
+    left = Infinity;
+    right = -Infinity;
+    await world.run(draw);
+    await world.run(refresh);
+    await world.run(countEast);
+    console.log(what, "drew", drawn, "from x", left, "to", right, "refreshed", refreshed, "east", east, "asked", asked);
+};
+
+export const main = async (): Promise<void> => {
+    await using world = World.create({ [camera]: cameraOver([0, 0], 1) });
+    await world.run(populate);
+    await world.run(place);
+    await report(world, "start:");
+    await world.run(drift);
+    await world.run(cross);
+    await world.run(place);
+    await report(world, "after a step:");
+    await report(world, "unchanged:");
+    await world.run(look, { x: 2, y: 2 });
+    await report(world, "camera moved:");
+};

package/src/guide/21-dom.md

@@ -0,0 +1,22 @@
+# Animating elements
+
+Systems can drive the page: the world holds what it shows, and systems write it to elements after each tick. Both UI
+chapters animate particles bouncing inside `#output`, the element the guide's Output tab gives, which a resource
+holds. Without a page, as in node, a stand-in takes its place, so the systems run the same and the program prints the
+same.
+
+- Objects live on the thread that shows them: [the dot and the stage](21-dom.ts#L22-L27) are `thread: "main"`, so the
+  systems touching them run on the page's thread.
+- A fixed `cadence` of 60 ticks a second, with `always`, makes [a velocity per tick a speed](21-dom.ts#L107),
+  whatever the display's rate.
+
+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
+   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
+   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
+world is disposed, so one fewer dot is left once the traced particle is despawned.

package/src/guide/21-dom.out

@@ -0,0 +1,5 @@
+frame 1: 99.5cqw 49.25cqh
+frame 2: 100cqw 48.5cqh
+frame 3: 98.5cqw 47.75cqh
+60 dots drawn
+59 dots once the traced particle is gone

package/src/guide/21-dom.ts

@@ -0,0 +1,117 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { always, cadence, clock, Finalizer, System, Vec2, World } from "../index.js";
+
+const position = Symbol();
+const velocity = Symbol();
+const traced = Symbol();
+const dot = Symbol();
+const stage = Symbol();
+const tracing = Symbol();
+
+/** An element showing a particle, as the systems drawing use it. */
+type Dot = { readonly style: { translate: string; background: string }; readonly remove: () => void };
+/** Where particles are drawn: an element of the page, or a stand-in where there's no page. */
+type Stage = { readonly add: () => Dot; readonly count: () => number };
+
+declare module "@adobe/ecs" {
+    interface Components {
+        // Percents of the stage's width and height.
+        [position]: { type: Vec2 };
+        [velocity]: { type: Vec2 };
+        [traced]: { type: true };
+        [dot]: { type: Dot; thread: "main" };
+    }
+    interface Resources {
+        [stage]: { type: Stage | null; thread: "main" };
+        // Called with each frame of the traced particle's dot.
+        [tracing]: { type: ((frame: number, dot: Dot) => void) | null; thread: "main" };
+    }
+}
+
+const spawn = System.create(({ commands }) => {
+    commands.spawn([position, velocity, traced])({ [position]: [98, 50], [velocity]: [1.5, -0.75] });
+    for (let i = 1; i < 60; i++) {
+        commands.spawn([position, velocity])({ [position]: [(i * 37) % 100, (i * 61) % 100], [velocity]: [Math.cos(i * 2.4) * 0.6, Math.sin(i * 2.4) * 0.6] });
+    }
+});
+
+// Each tick moves every particle by its velocity, turning it back from the walls.
+const move = System.create({ components: { with: [position, velocity] } }, row => {
+    const [x, y] = Vec2.add(row[position], row[velocity]);
+    const [vx, vy] = row[velocity];
+    row[velocity] = [x < 0 || x > 100 ? -vx : vx, y < 0 || y > 100 ? -vy : vy];
+    row[position] = [Math.min(Math.max(x, 0), 100), Math.min(Math.max(y, 0), 100)];
+});
+
+// Gives each particle a dot: not an observer, since it issues commands.
+const create = System.create({ components: { with: [position], not: [dot] }, resources: { is: [stage] } }, (row, { resources, commands }) => {
+    const element = resources[stage].add();
+    element.style.background = `hsl(${row.entity * 47 % 360} 80% 60%)`;
+    commands.add(row.entity, dot, element);
+});
+// Moves each dot whose particle moved, by a transform, which the page doesn't lay out again.
+const draw = System.create({
+    observer: true,
+    components: { with: [position, dot], optional: [traced], changed: [position] },
+}, (row, { resources }) => {
+    const [x, y] = row[position];
+    row[dot].style.translate = `${x}cqw ${y}cqh`;
+    if (row[traced] !== undefined) resources[tracing]?.(resources[clock].tick + 1, row[dot]);
+});
+Finalizer.create({ components: { with: [dot] } }, row => {
+    row[dot].remove();
+});
+
+const despawnTraced = System.create({ components: { with: [traced] } }, (row, { commands }) => {
+    commands.despawn(row.entity);
+});
+
+/** The page's `#output`: dots move inside a field a dot's radius in from its edges, by percents of it. */
+const pageStage = (output: HTMLElement): Stage => {
+    const field = output.appendChild(document.createElement("div"));
+    field.style.cssText = "position: absolute; inset: 6px; container-type: size";
+    return {
+        add: () => {
+            const element = field.appendChild(document.createElement("div"));
+            element.style.cssText = "position: absolute; width: 12px; height: 12px; margin: -6px; border-radius: 50%";
+            return element;
+        },
+        count: () => field.childElementCount,
+    };
+};
+
+/** Where there's no page, as in node: dots that keep what's written to them. */
+const standIn = (): Stage => {
+    const dots = new Set<Dot>();
+    return {
+        add: () => {
+            const added: Dot = { style: { translate: "", background: "" }, remove: () => void dots.delete(added) };
+            dots.add(added);
+            return added;
+        },
+        count: () => dots.size,
+    };
+};
+
+export const main = async (): Promise<void> => {
+    // The guide's Output tab has an element #output; elsewhere, as in node, there's none.
+    const output = globalThis.document?.querySelector<HTMLElement>("#output") ?? null;
+    const shown = output === null ? standIn() : pageStage(output);
+    const traceDone = Promise.withResolvers<void>();
+    const logFrame = (frame: number, traced: Dot): void => {
+        if (frame > 3) return;
+        console.log(`frame ${frame}: ${traced.style.translate}`);
+        if (frame === 3) traceDone.resolve();
+    };
+    // 60 ticks a second, whatever the display's rate.
+    await using world = World.create({ [cadence]: { kind: "fixed", step: 1000 / 60 }, [always]: true, [stage]: shown, [tracing]: logFrame });
+    await world.run(spawn);
+    world.add(System.create([move, create, draw]));
+    // The first three frames, or two seconds should they never be drawn.
+    await Promise.race([traceDone.promise, new Promise(resolve => setTimeout(resolve, 2000))]);
+    console.log(shown.count(), "dots drawn");
+    await world.run(despawnTraced);
+    console.log(shown.count(), "dots once the traced particle is gone");
+    // In a page it animates until the page goes; elsewhere it ends, its world disposed.
+    if (output !== null) await new Promise(resolve => addEventListener("pagehide", resolve));
+};

package/src/guide/22-canvas.md

@@ -0,0 +1,15 @@
+# Drawing on a canvas
+
+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.
+
+- `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
+  through a second.
+- It sizes the canvas's pixels to its size on the page, then calls `clearRect(`, and `arc(` and `fill()` for each
+  particle.
+
+Without a page, the stand-in keeps the circles filled since it was last cleared, and its `getImageData(` answers
+whether a pixel is covered, as a canvas does. So the program checks that the traced particle is drawn, frame by
+frame, the same in node and on the page.

package/src/guide/22-canvas.out

@@ -0,0 +1,3 @@
+frame 1: the traced particle is drawn
+frame 2: the traced particle is drawn
+frame 3: the traced particle is drawn

package/src/guide/22-canvas.ts

@@ -0,0 +1,119 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { always, cadence, clock, Index, System, Vec2, World } from "../index.js";
+
+const position = Symbol();
+const velocity = Symbol();
+const traced = Symbol();
+const pen = Symbol();
+const tracing = Symbol();
+
+/** What the drawing system uses of a canvas's 2D context, which a stand-in gives where there's no page. */
+type Pen = {
+    readonly canvas: { width: number; height: number; readonly clientWidth: number; readonly clientHeight: number };
+    fillStyle: string | CanvasGradient | CanvasPattern;
+    clearRect(x: number, y: number, width: number, height: number): void;
+    beginPath(): void;
+    arc(x: number, y: number, radius: number, start: number, end: number): void;
+    fill(): void;
+    getImageData(x: number, y: number, width: number, height: number): { readonly data: ArrayLike<number> };
+};
+
+declare module "@adobe/ecs" {
+    interface Components {
+        // Percents of the canvas's width and height.
+        [position]: { type: Vec2 };
+        [velocity]: { type: Vec2 };
+        [traced]: { type: true };
+    }
+    interface Resources {
+        [pen]: { type: Pen | null; thread: "main" };
+        // Called with each frame drawn, and where the traced particle was drawn, in the canvas's pixels.
+        [tracing]: { type: ((frame: number, at: Vec2) => void) | null; thread: "main" };
+    }
+}
+
+const spawn = System.create(({ commands }) => {
+    commands.spawn([position, velocity, traced])({ [position]: [98, 50], [velocity]: [1.5, -0.75] });
+    for (let i = 1; i < 400; i++) {
+        commands.spawn([position, velocity])({ [position]: [(i * 37) % 100, (i * 61) % 100], [velocity]: [Math.cos(i * 2.4) * 0.6, Math.sin(i * 2.4) * 0.6] });
+    }
+});
+
+// Each tick moves every particle by its velocity, turning it back from the walls.
+const move = System.create({ components: { with: [position, velocity] } }, row => {
+    const [x, y] = Vec2.add(row[position], row[velocity]);
+    const [vx, vy] = row[velocity];
+    row[velocity] = [x < 0 || x > 100 ? -vx : vx, y < 0 || y > 100 ? -vy : vy];
+    row[position] = [Math.min(Math.max(x, 0), 100), Math.min(Math.max(y, 0), 100)];
+});
+
+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,
+    resources: { is: [pen], changed: [clock] },
+    lookup: { particles: { index: particles }, traced: { index: tracedOnes } },
+}, ({ resources, lookup }) => {
+    const context = resources[pen];
+    const { canvas } = context;
+    // The canvas's pixels follow its size on the page.
+    const scale = globalThis.devicePixelRatio ?? 1;
+    const width = Math.round(canvas.clientWidth * scale);
+    const height = Math.round(canvas.clientHeight * scale);
+    if (canvas.width !== width) canvas.width = width;
+    if (canvas.height !== height) canvas.height = height;
+    const radius = 4 * scale;
+    const at = ([x, y]: Vec2): Vec2 => [radius + x / 100 * (width - 2 * radius), radius + y / 100 * (height - 2 * radius)];
+    context.clearRect(0, 0, width, height);
+    const list = lookup.particles();
+    for (let i = 0; i < list.length; i++) {
+        const particle = list.at(i);
+        const [x, y] = at(particle[position]);
+        context.fillStyle = `hsl(${particle.entity * 47 % 360} 80% 60%)`;
+        context.beginPath();
+        context.arc(x, y, radius, 0, 2 * Math.PI);
+        context.fill();
+    }
+    const followed = lookup.traced();
+    if (followed.length > 0) resources[tracing]?.(resources[clock].tick + 1, at(followed.at(0)[position]));
+});
+
+/** Where there's no page, as in node: a canvas of a fixed size that keeps the circles filled since it was last cleared. */
+const standIn = (): Pen => {
+    const filled: { readonly x: number; readonly y: number; readonly radius: number }[] = [];
+    let path = { x: 0, y: 0, radius: 0 };
+    return {
+        canvas: { width: 0, height: 0, clientWidth: 400, clientHeight: 300 },
+        fillStyle: "",
+        clearRect: () => void filled.splice(0),
+        beginPath: () => void (path = { x: 0, y: 0, radius: 0 }),
+        arc: (x, y, radius) => void (path = { x, y, radius }),
+        fill: () => void filled.push(path),
+        getImageData: (x, y) => ({ data: [0, 0, 0, filled.some(circle => Math.hypot(circle.x - x, circle.y - y) < circle.radius) ? 255 : 0] }),
+    };
+};
+
+export const main = async (): Promise<void> => {
+    // The guide's Output tab has an element #output; elsewhere, as in node, there's none.
+    const output = globalThis.document?.querySelector<HTMLElement>("#output") ?? null;
+    const canvas = output?.appendChild(document.createElement("canvas")) ?? null;
+    canvas?.setAttribute("style", "display: block; width: 100%; height: 100%");
+    const context = canvas === null ? standIn() : canvas.getContext("2d");
+    const traceDone = Promise.withResolvers<void>();
+    const logFrame = (frame: number, [x, y]: Vec2): void => {
+        if (frame > 3 || context === null) return;
+        // Whether the traced particle's place is drawn on: its pixel's opacity.
+        const covered = context.getImageData(Math.floor(x), Math.floor(y), 1, 1).data[3] === 255;
+        console.log(`frame ${frame}: the traced particle is ${covered ? "drawn" : "missing"}`);
+        if (frame === 3) traceDone.resolve();
+    };
+    // 60 ticks a second, whatever the display's rate.
+    await using world = World.create({ [cadence]: { kind: "fixed", step: 1000 / 60 }, [always]: true, [pen]: context, [tracing]: logFrame });
+    await world.run(spawn);
+    world.add(System.create([move, draw]));
+    // The first three frames, or two seconds should they never be drawn.
+    await Promise.race([traceDone.promise, new Promise(resolve => setTimeout(resolve, 2000))]);
+    // In a page it animates until the page goes; elsewhere it ends, its world disposed.
+    if (canvas !== null) await new Promise(resolve => addEventListener("pagehide", resolve));
+};

package/src/guide/CLAUDE.md

@@ -0,0 +1,49 @@
+# The guide
+
+This folder teaches the ECS to someone who has just started using it, in chapters. `README.md` is its index: the
+chapters by part, in order, the unnumbered `Setup` and `Keys and declarations` first, numbered `00-`. Each chapter is
+its prose, `NN-name.md`, under a `# Title` that the index gives too, and a program, `NN-name.ts`, whose exported `main`
+runs it, and what it prints is in `NN-name.out` beside it. `Setup` has prose alone. The interactive guide, `packages/ecs-guide`, shows each chapter's prose beside its program
+in an editor, and runs it.
+
+`guide.test.ts` runs every program and compares what it logged with its `.out`, which mustn't be empty. It checks
+that every program has prose and the index lists every chapter by its title; that each chapter's prose names, as code,
+what the chapter teaches, its list in `teaches`, and its program does it, outside comments; that each link to a
+program's lines points at whole code of the chapter's own files; that code in the prose stays a line or two; and, by
+`mutations`, that taking a point a program teaches away changes what it prints, or prints the failure a broken rule
+gives. A chapter that shows a type error does
+it in `NN-name.type-test.ts`, under a `// @ts-expect-error` that the package's build checks.
+
+## Writing the prose
+
+- The readers are experienced engineers. Keep it concise: short paragraphs and lists, no padding, no marketing, and
+  no repeating what the code shows.
+- Introduce the chapter's concept, define each term in italics where it first appears, and say how it behaves: what
+  runs when, what's kept, and what's rejected and why.
+- Code in the prose only where a sentence needs a shape: inline, or a block of a line or two. The program in the
+  editor is the demonstration.
+- Link the program's lines a sentence speaks of: `[spawns an entity](02-entities.ts#L19-L22)`, or `#L17` for one line.
+  On GitHub the link opens the file at those lines; in the interactive guide it selects them in the editor. A link
+  covers whole statements or whole members of a declaration. Link another chapter by its prose, `[Reductions](15-reductions.md)`.
+- Don't repeat the output, which the run window shows; mention a line of it only where a sentence points at it.
+- Never mention `@adobe/data` or any other package that isn't this one. Describe only the current API, with no history.
+
+## Code conventions
+
+- An example imports only the package, as `../index.js`, declares what it uses, and exports `main`, an async function
+  that creates its worlds with `World.create()`, runs systems, logs what they did with `console.log`, and disposes its
+  worlds before it resolves. Never top-level await.
+- Comments are reading aids, short, for what the code doesn't say; the prose carries the explanation.
+- What it prints shows the effect of each point it teaches, so leaving one out changes the output: enough entities
+  that a filter or a target matters, the values a system wrote read back, what a finalizer did. Add each to
+  `mutations`.
+- An example that draws finds the element to draw in as `#output`, which the interactive guide's Output tab gives, and
+  holds what it draws with in a resource; where there's no page, as in node, a small stand-in takes its place and
+  keeps what's drawn, so the systems run the same and the program prints the same. It logs a few deterministic frames,
+  ticking at a fixed cadence, then animates until its page goes, or, without one, ends.
+- What it prints is deterministic: no timings or random values, and rows in an order the API doesn't define are sorted
+  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.
+- Lines change as code does: the test of links fails on any that no longer covers whole code, so move them with it.