@adobe/ecs 0.0.0-stage → 0.1.0

package/src/guide/04-ticks.test.ts

@@ -0,0 +1,73 @@
+import { expect, it } from "vitest";
+import { always, cadence, clock, Resource, System, wake, World } from "../index.js";
+
+const elapsed = Symbol("elapsed");
+const steps = Symbol("steps");
+
+declare module "@adobe/ecs" {
+    interface Resources {
+        [elapsed]: { type: number };
+        [steps]: { type: number };
+    }
+}
+
+Resource.register(elapsed, { type: { type: "number", default: 0 } });
+Resource.register(steps, { type: { type: "number", default: 0 } });
+
+// clock is the current tick's: delta is the milliseconds since the last one.
+const advance = System.create({ resources: { read: [clock], write: [elapsed] } }, ({ resources }) => {
+    resources[elapsed] += resources[clock].delta;
+});
+
+// Added, an observer system reacts to changes: with elapsed in changed, it runs after each tick that changed it.
+let reached: (value: number) => void = () => {};
+const watch = System.create({ observer: true, resources: { read: [elapsed], changed: [elapsed] } }, ({ resources }) => {
+    if (resources[elapsed] >= 30) reached(resources[elapsed]);
+});
+
+let read = { elapsed: 0, delta: 0 };
+const readTime = System.create({ observer: true, resources: { read: [elapsed, clock] } }, ({ resources }) => {
+    read = { elapsed: resources[elapsed], delta: resources[clock].delta };
+});
+
+it("runs added systems on every tick", async () => {
+    // cadence ticks once per animation frame by default; fixed ticks every step milliseconds, each with that delta.
+    // A tick runs only after a run arrives, unless always is set.
+    await using world = World.create({ [cadence]: { kind: "fixed", step: 10 }, [always]: true });
+    const ticked = new Promise<number>(resolve => { reached = resolve; });
+    // add: runs a system on every tick.
+    world.add(advance);
+    world.add(watch);
+    expect(await ticked).toBeGreaterThanOrEqual(30);
+    await world.run(readTime);
+    expect(read.delta).toBe(10);
+    // remove: takes a system added off every tick again.
+    world.remove(advance);
+    await world.run(readTime);
+    const stopped = read.elapsed;
+    await new Promise(resolve => setTimeout(resolve, 50));
+    await world.run(readTime);
+    expect(read.elapsed).toBe(stopped);
+});
+
+// A system asks for another tick by contributing a time to wake: the first tick at or after it runs. Work that a tick's
+// commands start and a later tick finishes asks for the next one this way.
+const step = System.create({ resources: { read: [clock], write: [steps] }, reduce: { [wake]: "min" } }, ({ resources, reduce }) => {
+    resources[steps] += 1;
+    if (resources[steps] < 3) reduce[wake](resources[clock].now);
+});
+
+let finished: (value: number) => void = () => {};
+const watchSteps = System.create({ observer: true, resources: { read: [steps], changed: [steps] } }, ({ resources }) => {
+    if (resources[steps] === 3) finished(resources[steps]);
+});
+
+it("ticks again when a system asks", async () => {
+    await using world = World.create({ [cadence]: { kind: "fixed", step: 10 } });
+    const done = new Promise<number>(resolve => { finished = resolve; });
+    world.add(step);
+    world.add(watchSteps);
+    // One run arriving ticks once; step's wakes tick twice more.
+    await world.run(System.create(() => {}));
+    expect(await done).toBe(3);
+});

package/src/guide/05-scheduling.test.ts

@@ -0,0 +1,60 @@
+import { expect, it } from "vitest";
+import { Component, System, World } from "../index.js";
+
+const health = Symbol("health");
+const damage = Symbol("damage");
+
+declare module "@adobe/ecs" {
+    interface Components {
+        [health]: { type: number };
+        [damage]: { type: number };
+    }
+}
+
+Component.register(health, { type: { type: "number" } });
+Component.register(damage, { type: { type: "number" } });
+
+const spawn = System.create(({ commands }) => { commands.spawn([health, damage])({ [health]: 10, [damage]: 4 }); });
+const hit = System.create({ components: { read: [damage], write: [health] } }, row => {
+    row[health] -= row[damage];
+});
+// before, after and during list the systems themselves.
+const heal = System.create({ components: { write: [health] }, after: [hit] }, row => {
+    row[health] = Math.min(row[health] * 2, 10);
+});
+// A list of systems is a composite: it runs its members as one system, in their order; members without an order
+// between them may run in parallel. { systems, after, ... } declares one with a name or constraints.
+const frame = System.create([heal, hit]);
+
+const healths: number[] = [];
+const read = System.create({ observer: true, components: { read: [health] } }, row => {
+    healths.push(row[health]);
+});
+
+it("orders a composite's members by their constraints", async () => {
+    await using world = World.create();
+    await world.run(spawn);
+    await world.run(frame);
+    await world.run(read);
+    // hit, 10 - 4 = 6, then heal, min(12, 10).
+    expect(healths).toEqual([10]);
+});
+
+// Phases are systems that do nothing; a system during one runs after what the phase follows and before what follows it.
+const update = System.create(() => {});
+const render = System.create({ after: [update] }, () => {});
+const poison = System.create({ components: { write: [health] }, during: [update] }, row => {
+    row[health] -= 1;
+});
+const seen: number[] = [];
+const report = System.create({ components: { read: [health] }, during: [render] }, row => {
+    seen.push(row[health]);
+});
+const phased = System.create([report, poison, update, render]);
+
+it("orders systems during phases by the order of the phases", async () => {
+    await using world = World.create();
+    await world.run(spawn);
+    await world.run(phased);
+    expect(seen).toEqual([9]);
+});

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

@@ -0,0 +1,59 @@
+import { expect, it } from "vitest";
+import { Component, Resource, System, World } from "../index.js";
+
+const health = Symbol("health");
+const seen = Symbol("seen");
+
+declare module "@adobe/ecs" {
+    interface Components {
+        [health]: { type: number };
+    }
+    interface Resources {
+        [seen]: { type: number };
+    }
+}
+
+Component.register(health, { type: { type: "number" } });
+Resource.register(seen, { type: { type: "number", default: 0 } });
+
+// Value writes apply at once; commands wait for the sync point that ends each run, then apply in the order issued.
+const spawn = System.create(({ commands }) => {
+    // spawn gives the entity at once, so later commands can name it.
+    const hero = commands.spawn([health])({ [health]: 3 });
+    commands.add(hero, health, 5);
+    // Spawned and despawned before the sync point, it never exists.
+    commands.despawn(commands.spawn([health])({ [health]: 1 }));
+});
+// A composite is one run with one sync point: count runs after spawn, before its entities exist.
+const count = System.create({ components: { has: [health] }, resources: { write: [seen] }, after: [spawn] }, (row, { resources }) => {
+    resources[seen] += 1;
+});
+const frame = System.create([spawn, count]);
+
+const healths: number[] = [];
+// An observer runs after the sync point of every run and tick it's added to, reading what it left; it writes nothing.
+const watch = System.create({ observer: true, components: { read: [health] } }, row => {
+    healths.push(row[health]);
+});
+let counted = 0;
+const readSeen = System.create({ observer: true, resources: { read: [seen] } }, ({ resources }) => {
+    counted = resources[seen];
+});
+
+it("applies commands at the sync point that ends each run", async () => {
+    await using world = World.create();
+    await world.run(frame);
+    await world.run(readSeen);
+    expect(counted).toBe(0);
+    await world.run(count);
+    await world.run(readSeen);
+    expect(counted).toBe(1);
+});
+
+it("runs observer systems after each sync point", async () => {
+    healths.length = 0;
+    await using world = World.create();
+    world.add(watch);
+    await world.run(spawn);
+    expect(healths).toEqual([5]);
+});

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

@@ -0,0 +1,87 @@
+import { expect, it } from "vitest";
+import { Component, Resource, System, World } from "../index.js";
+
+const score = Symbol("score");
+const shown = Symbol("shown");
+const boss = Symbol("boss");
+const level = Symbol("level");
+const paused = Symbol("paused");
+const map = Symbol("map");
+const steps = Symbol("steps");
+
+declare module "@adobe/ecs" {
+    interface Components {
+        [score]: { type: number };
+        [shown]: { type: number };
+        [boss]: { type: true };
+    }
+    interface Resources {
+        [level]: { type: number };
+        [paused]: { type: boolean };
+        [map]: { type: { readonly width: number } | null };
+        [steps]: { type: number };
+    }
+}
+
+Component.register(score, { type: { type: "number" } });
+Component.register(shown, { type: { type: "number" } });
+Component.register(boss, { type: { const: true } });
+Resource.register(level, { type: { type: "number", default: 1 } });
+Resource.register(paused, { type: { type: "boolean", default: false } });
+Resource.register(map, { type: { anyOf: [{ type: "object", properties: { width: { type: "number" } } }, { type: "null" }] } });
+Resource.register(steps, { type: { type: "number", default: 0 } });
+
+// A resource in changed passes the first run and each run after it changes: no run-once flag needed.
+const load = System.create({ resources: { read: [level], changed: [level] } }, ({ resources, commands }) => {
+    commands.spawn([score, shown, boss])({ [score]: 0, [shown]: -1 });
+    for (let i = 0; i < resources[level]; i++) commands.spawn([score, shown])({ [score]: 0, [shown]: -1 });
+});
+// A component in changed passes only rows written since this system last ran.
+const show = System.create({ components: { read: [score], write: [shown], changed: [score] } }, row => {
+    row[shown] = row[score];
+});
+const bump = System.create({ components: { write: [score], has: [boss] } }, row => {
+    row[score] += 10;
+});
+
+const shownValues: number[] = [];
+const readShown = System.create({ observer: true, components: { read: [shown] } }, row => {
+    shownValues.push(row[shown]);
+});
+
+it("runs systems only for what changed since they last ran", async () => {
+    await using world = World.create();
+    await world.run(load);
+    await world.run(load);
+    await world.run(readShown);
+    expect(shownValues).toEqual([-1, -1]);
+    await world.run(show);
+    await world.run(bump);
+    await world.run(show);
+    shownValues.length = 0;
+    await world.run(readShown);
+    expect(shownValues.sort((a, b) => a - b)).toEqual([0, 10]);
+});
+
+// Runs only while each resource in is is neither null nor false, and each in not is; is reads it narrowed.
+const step = System.create({ resources: { is: [map], not: [paused], write: [steps] } }, ({ resources }) => {
+    resources[steps] += resources[map].width;
+});
+const pause = System.create({ resources: { write: [paused] } }, ({ resources }) => { resources[paused] = true; });
+const open = System.create({ resources: { write: [map] } }, ({ resources }) => { resources[map] = { width: 4 }; });
+
+let stepped = 0;
+const readSteps = System.create({ observer: true, resources: { read: [steps] } }, ({ resources }) => {
+    stepped = resources[steps];
+});
+
+it("runs systems only while their conditions hold", async () => {
+    await using world = World.create();
+    await world.run(step);
+    await world.run(open);
+    await world.run(step);
+    await world.run(pause);
+    await world.run(step);
+    await world.run(readSteps);
+    expect(stepped).toBe(4);
+});

package/src/guide/08-input.test.ts

@@ -0,0 +1,47 @@
+import { expect, it } from "vitest";
+import { Component, Entity, System, World } from "../index.js";
+
+const health = Symbol("health");
+
+declare module "@adobe/ecs" {
+    interface Components {
+        [health]: { type: number };
+    }
+}
+
+Component.register(health, { type: { type: "number" } });
+
+let player = Entity.none;
+const spawn = System.create(({ commands }) => { player = commands.spawn([health])({ [health]: 10 }); });
+
+// input is an object schema of named fields; each run passes a value of it.
+const hit = System.create({
+    components: { write: [health] },
+    input: { type: "object", properties: { amount: { type: "number" } } },
+}, (row, { input }) => {
+    row[health] -= input.amount;
+});
+
+// target names an input field holding an entity: the system runs on that entity's row alone, or on none once it's gone.
+const heal = System.create({
+    components: { write: [health] },
+    input: { type: "object", properties: { entity: Entity.schema, amount: { type: "number" } } },
+    target: "entity",
+}, (row, { input }) => {
+    row[health] += input.amount;
+});
+
+const healths: number[] = [];
+const read = System.create({ observer: true, components: { read: [health] } }, row => {
+    healths.push(row[health]);
+});
+
+it("runs a system with a value", async () => {
+    await using world = World.create();
+    await world.run(spawn);
+    // Systems with input are run, not added; a composite's input has every field its members declare.
+    await world.run(hit, { amount: 3 });
+    await world.run(heal, { entity: player, amount: 1 });
+    await world.run(read);
+    expect(healths).toEqual([8]);
+});

package/src/guide/09-rules.test.ts

@@ -0,0 +1,57 @@
+import { expect, it } from "vitest";
+import { Component, Rule, System, World } from "../index.js";
+
+const mesh = Symbol("mesh");
+const sprite = Symbol("sprite");
+const hidden = Symbol("hidden");
+const drawn = Symbol("drawn");
+const layer = Symbol("layer");
+
+declare module "@adobe/ecs" {
+    interface Components {
+        [mesh]: { type: number };
+        [sprite]: { type: number };
+        [hidden]: { type: true };
+        // Only rules add derived components, starting at their schema's default.
+        [drawn]: { type: true; derived: true };
+        [layer]: { type: number; derived: true };
+    }
+}
+
+Component.register(mesh, { type: { type: "number" } });
+Component.register(sprite, { type: { type: "number" } });
+Component.register(hidden, { type: { const: true } });
+Component.register(drawn, { type: { const: true }, derived: true });
+Component.register(layer, { type: { type: "number", default: 1 }, derived: true });
+
+// Entities matching a rule have what it derives, only while they match.
+Rule.create({ components: { has: [mesh], not: [hidden] }, derive: [drawn] });
+// Several rules may derive one component, present while any matches.
+Rule.create({ components: { has: [sprite], not: [hidden] }, derive: [drawn] });
+// Rules build on what others derive.
+Rule.create({ components: { has: [drawn] }, derive: [layer] });
+
+const spawn = System.create(({ commands }) => {
+    commands.spawn([mesh])({ [mesh]: 1 });
+    commands.spawn([sprite])({ [sprite]: 2 });
+    commands.spawn([mesh, hidden])({ [mesh]: 3 });
+});
+const hide = System.create({ components: { has: [sprite] } }, (row, { commands }) => {
+    commands.add(row.entity, hidden);
+});
+
+const layers: number[] = [];
+const read = System.create({ observer: true, components: { read: [layer], has: [drawn] } }, row => {
+    layers.push(row[layer]);
+});
+
+it("derives components from the components an entity has", async () => {
+    await using world = World.create();
+    await world.run(spawn);
+    await world.run(read);
+    expect(layers).toEqual([1, 1]);
+    await world.run(hide);
+    layers.length = 0;
+    await world.run(read);
+    expect(layers).toEqual([1]);
+});

package/src/guide/10-finalizers.test.ts

@@ -0,0 +1,64 @@
+import { expect, it } from "vitest";
+import { Component, Finalizer, System, World } from "../index.js";
+
+const handle = Symbol("handle");
+
+declare module "@adobe/ecs" {
+    interface Components {
+        [handle]: { type: number };
+    }
+}
+
+Component.register(handle, { type: { type: "number" } });
+
+/** What handles name outside the world, as GPU buffers and DOM nodes are. */
+const open = new Set<number>();
+
+// Runs for each entity that stops matching, whatever the cause, reading its values from before.
+Finalizer.create({ components: { read: [handle] } }, row => {
+    open.delete(row[handle]);
+});
+
+const spawn = System.create(({ commands }) => {
+    for (const id of [7, 8]) {
+        open.add(id);
+        commands.spawn([handle])({ [handle]: id });
+    }
+});
+const destroy = System.create({ components: { read: [handle] } }, (row, { commands }) => {
+    if (row[handle] === 7) commands.despawn(row.entity);
+    else commands.remove(row.entity, handle);
+});
+
+it("releases what entities held when they stop matching", async () => {
+    await using world = World.create();
+    await world.run(spawn);
+    await world.run(destroy);
+    expect([...open]).toEqual([]);
+});
+
+it("releases what every entity holds when the world is disposed", async () => {
+    const world = World.create();
+    await world.run(spawn);
+    // dispose runs every finalizer for the entities it still matches.
+    await world.dispose();
+    expect(open.size).toBe(0);
+});
+
+const saved: string[] = [];
+
+// Sees each sync point's structural changes to the components it watches, grouped by how entities changed, with
+// values before and after: for saving and undo.
+Finalizer.changes({ watch: [handle] }, changes => {
+    for (const group of changes.groups) {
+        for (const entity of group.entities) saved.push(`${changes.previous(entity, handle)} → ${changes.next(entity, handle)}`);
+    }
+});
+
+it("records each sync point's structural changes", async () => {
+    saved.length = 0;
+    await using world = World.create();
+    await world.run(spawn);
+    await world.run(destroy);
+    expect(saved.sort()).toEqual(["7 → null", "8 → null", "null → 7", "null → 8"]);
+});

package/src/guide/11-traits.test.ts

@@ -0,0 +1,58 @@
+import { expect, it } from "vitest";
+import { Component, Entity, System, World } from "../index.js";
+
+const ship = Symbol("ship");
+const parent = Symbol("parent");
+const target = Symbol("target");
+const selected = Symbol("selected");
+const outline = Symbol("outline");
+
+// Traits are the fields of a key's declaration; type is one. Registration repeats them.
+declare module "@adobe/ecs" {
+    interface Components {
+        [ship]: { type: true };
+        // Despawned with the entity it points to.
+        [parent]: { type: Entity; reference: "owner" };
+        // Removed when the entity it points to despawns.
+        [target]: { type: Entity; reference: "weak" };
+        [selected]: { type: true };
+        // Removed with selected.
+        [outline]: { type: number; within: typeof selected };
+    }
+}
+
+Component.register(ship, { type: { const: true } });
+Component.register(parent, { type: Entity.schema, reference: "owner" });
+Component.register(target, { type: Entity.schema, reference: "weak" });
+Component.register(selected, { type: { const: true } });
+Component.register(outline, { type: { type: "number" }, within: selected });
+
+const spawn = System.create(({ commands }) => {
+    const mothership = commands.spawn([ship, selected, outline])({ [outline]: 2 });
+    commands.spawn([parent])({ [parent]: mothership });
+    commands.spawn([target])({ [target]: mothership });
+});
+const deselect = System.create({ components: { has: [selected] } }, (row, { commands }) => {
+    commands.remove(row.entity, selected);
+});
+const destroy = System.create({ components: { has: [ship] } }, (row, { commands }) => {
+    commands.despawn(row.entity);
+});
+
+const counts = { outlined: 0, targeting: 0, all: 0 };
+const countOutlined = System.create({ observer: true, components: { has: [outline] } }, () => { counts.outlined += 1; });
+const countTargeting = System.create({ observer: true, components: { has: [target] } }, () => { counts.targeting += 1; });
+const countAll = System.create({ observer: true, components: {} }, () => { counts.all += 1; });
+
+it("removes components with their host, and follows references", async () => {
+    await using world = World.create();
+    await world.run(spawn);
+    await world.run(deselect);
+    await world.run(countOutlined);
+    expect(counts.outlined).toBe(0);
+    await world.run(destroy);
+    await world.run(countTargeting);
+    await world.run(countAll);
+    // The owned entity is gone; the weak holder lives on without target.
+    expect(counts).toEqual({ outlined: 0, targeting: 0, all: 1 });
+});

package/src/guide/11-traits.type-test.ts

@@ -0,0 +1,27 @@
+import { Component, Trait } from "../index.js";
+
+type Equal<X, Y> = (<T>() => T extends X ? 1 : 2) extends (<T>() => T extends Y ? 1 : 2) ? true : false;
+const check = <_T extends true>() => { };
+
+// A trait of your own is a member of Traits<N>: the value it allows on key N, or never where it doesn't apply.
+export const instanced = Symbol("instanced");
+declare module "@adobe/ecs" {
+    interface Traits<N> {
+        readonly [instanced]: N extends Component.Key ? ([Component.Value<N>] extends [readonly number[]] ? true : never) : never;
+    }
+}
+Trait.register(instanced);
+
+const transform = Symbol("transform");
+const name = Symbol("name");
+declare module "@adobe/ecs" {
+    interface Components {
+        [transform]: { type: readonly [number, number, number]; [instanced]: true };
+        [name]: { type: string };
+    }
+}
+Component.register(transform, { type: { type: "array", items: { type: "number" }, minItems: 3, maxItems: 3 }, [instanced]: true });
+Component.register(name, { type: { type: "string" } });
+
+// Types select components by trait.
+check<Equal<Extract<Component.With<typeof instanced>, typeof transform | typeof name>, typeof transform>>();

package/src/guide/13-indexes.test.ts

@@ -0,0 +1,95 @@
+import { expect, it } from "vitest";
+import { Component, Index, System, World } from "../index.js";
+
+const cell = Symbol("cell");
+const crowded = Symbol("crowded");
+const score = Symbol("score");
+const player = Symbol("player");
+const serverId = Symbol("serverId");
+
+declare module "@adobe/ecs" {
+    interface Components {
+        [cell]: { type: readonly [number, number] };
+        [crowded]: { type: number };
+        [score]: { type: number };
+        [player]: { type: string };
+        [serverId]: { type: number };
+    }
+}
+
+Component.register(cell, { type: { type: "array", items: { type: "integer" }, minItems: 2, maxItems: 2 } });
+Component.register(crowded, { type: { type: "number" } });
+Component.register(score, { type: { type: "number" } });
+Component.register(player, { type: { type: "string" } });
+Component.register(serverId, { type: { type: "integer" } });
+
+// An index finds entities by their components' values: here, those with a crowded count, by their cell.
+const grid = Index.create({ key: [cell], components: { has: [crowded] } });
+
+// A lookup through it gives the rows with a key, in entity order.
+const count = System.create({ components: { read: [cell], write: [crowded] }, lookup: { at: { index: grid } } }, (row, { lookup }) => {
+    const [x, y] = row[cell];
+    row[crowded] = lookup.at([x, y]).length;
+});
+
+// A sorted index keeps its key's order: lookups take a range, and `order` runs a system's rows in it.
+const byScore = Index.create({ key: [score], sorted: true, components: { has: [player] } });
+
+const winners: string[] = [];
+const leaders = System.create({ observer: true, lookup: { scores: { index: byScore, read: [player] } } }, ({ lookup }) => {
+    winners.length = 0;
+    const high = lookup.scores({ ">=": 90 });
+    for (let i = 0; i < high.length; i++) winners.push(high.at(i)[player]);
+});
+
+const board: string[] = [];
+const list = System.create({ observer: true, components: { read: [player] }, order: byScore }, row => {
+    board.push(row[player]);
+});
+
+// A unique index gives one row, or null.
+const byServerId = Index.create({ key: [serverId], unique: true });
+let found: number | null = null;
+const find = System.create({ input: { type: "object", properties: { id: { type: "integer" } } }, lookup: { byId: { index: byServerId } } }, ({ input, lookup }) => {
+    found = lookup.byId(input.id)?.entity ?? null;
+});
+
+// An index without a key holds every entity with its components, in entity order. With changed: true, this observer
+// system runs only when an entity entered or left the index, so added, it keeps a count as players come and go.
+const players = Index.create({ key: [], components: { has: [player] } });
+let playerCount = 0;
+const countPlayers = System.create({ observer: true, lookup: { players: { index: players, changed: true } } }, ({ lookup }) => {
+    playerCount = lookup.players().length;
+});
+
+const crowds: number[] = [];
+const readCrowds = System.create({ observer: true, components: { read: [crowded] } }, row => {
+    crowds.push(row[crowded]);
+});
+
+const places: readonly (readonly [number, number])[] = [[0, 0], [0, 0], [1, 0]];
+const spawn = System.create(({ commands }) => {
+    for (const place of places) commands.spawn([cell, crowded])({ [cell]: place, [crowded]: 0 });
+    commands.spawn([player, score, serverId])({ [player]: "ada", [score]: 95, [serverId]: 7 });
+    commands.spawn([player, score, serverId])({ [player]: "bo", [score]: 80, [serverId]: 8 });
+    commands.spawn([player, score, serverId])({ [player]: "cy", [score]: 91, [serverId]: 9 });
+});
+
+it("finds rows by key, by range and in order", async () => {
+    await using world = World.create();
+    world.add(countPlayers);
+    await world.run(spawn);
+    expect(playerCount).toBe(3);
+    await world.run(count);
+    await world.run(readCrowds);
+    expect(crowds.sort()).toEqual([1, 2, 2]);
+    await world.run(leaders);
+    expect(winners).toEqual(["cy", "ada"]);
+    board.length = 0;
+    await world.run(list);
+    expect(board).toEqual(["bo", "cy", "ada"]);
+    await world.run(find, { id: 8 });
+    expect(found).not.toBeNull();
+    await world.run(find, { id: 1 });
+    expect(found).toBeNull();
+});

package/src/guide/CLAUDE.md

@@ -0,0 +1,34 @@
+# The guide
+
+`guide.md` in this folder teaches the ECS to someone who has just started using it. The files beside it are the
+code it shows: every excerpt comes from a file here that runs as a test, so the guide can't drift from the API.
+
+## Writing the guide
+
+- Teach how to use the API, concisely. A reader is learning, so show the common case and stop.
+- Prefer concise TypeScript with a few comments for what isn't obvious over prose that explains the code.
+- Explain behaviour only as far as using it needs: "you're notified when values change, at most once per frame", not
+  the exact timing rules. Detailed rules belong in a glossary or appendix, not in a lesson.
+- Don't document what throws. Throws aren't part of the documented contract; readers meet them when they happen, and
+  compile-time checks prevent most mistakes.
+- Never mention `@adobe/data` or any other package that isn't this one. It means nothing to a consumer.
+- Describe only the current API, with no history.
+- Keep it small. Write sections for the basics and intermediate topics; advanced topics are placeholders until the
+  API settles.
+
+## Structure
+
+- **Setup:** its own short section before the basics: the build plugin and how keys are registered and declared.
+- **Basics:** resources, then entities, components and archetypes, which together are the whole data model, then
+  systems, and ticks and cadence: everything needed to build and run a world and its loop. Topics that belong together
+  share a section; entities are taught with components, and archetypes, named lists of components, with them.
+- **Intermediate:** scheduling and composites, sync points, change filters and conditions, input, rules, finalizers
+  and change sets, and traits with within and references.
+- **Advanced:** placeholders only.
+
+## Code conventions
+
+- Keys are short: `Symbol("position")`, never a path like `"guide/components/position"`. A resource's description says
+  nothing about components.
+- Archetypes are types, so their names are PascalCase: `const Particle = Archetype.create([position, velocity])`.
+- Use the public API only, as a consumer imports it, not internal modules. Read a world through observer systems.