@adobe/ecs 0.1.0 → 0.2.0

package/src/guide/09-rules.md

@@ -0,0 +1,12 @@
+# Rules
+
+A *rule* derives components from others: entities matching it have what it derives, only while they match.
+`Rule.create` declares one at module scope, with a match like a system's and the components it derives.
+
+- A derived component is [declared](09-rules.ts#L15-L16) with `derived: true`. Only rules add and remove it; it
+  starts at its default.
+- [Several rules](09-rules.ts#L20-L21) may derive one component, which an entity has while any of them matches.
+- Rules build on what others derive: [`layer`](09-rules.ts#L22) follows from `drawn`.
+
+Rules apply at each sync point. When [`hide`](09-rules.ts#L29-L31) adds `hidden` to the sprite, it stops matching,
+so it loses `drawn`, and with it `layer`.

package/src/guide/09-rules.out

@@ -0,0 +1,2 @@
+drawn: mesh 1 on layer 1, sprite 2 on layer 1
+drawn: mesh 1 on layer 1

package/src/guide/09-rules.ts

@@ -0,0 +1,50 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { Rule, System, World } from "../index.js";
+
+const mesh = Symbol();
+const sprite = Symbol();
+const hidden = Symbol();
+const drawn = Symbol();
+const layer = Symbol();
+
+declare module "@adobe/ecs" {
+    interface Components {
+        [mesh]: { type: number };
+        [sprite]: { type: number };
+        [hidden]: { type: true };
+        [drawn]: { type: true; derived: true };
+        [layer]: { type: number; derived: true; default: 1 };
+    }
+}
+
+Rule.create({ components: { with: [mesh], not: [hidden] }, derive: [drawn] });
+Rule.create({ components: { with: [sprite], not: [hidden] }, derive: [drawn] });
+Rule.create({ components: { with: [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: { with: [sprite] } }, (row, { commands }) => {
+    commands.add(row.entity, hidden);
+});
+
+const drawing: string[] = [];
+const read = System.create({ observer: 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. */
+const logDrawn = async (world: World): Promise<void> => {
+    drawing.length = 0;
+    await world.run(read);
+    console.log("drawn:", drawing.sort().join(", "));
+};
+
+export const main = async (): Promise<void> => {
+    await using world = World.create();
+    await world.run(spawn);
+    await logDrawn(world);
+    await world.run(hide);
+    await logDrawn(world);
+};

package/src/guide/10-finalizers.md

@@ -0,0 +1,13 @@
+# Finalizers and change sets
+
+A *finalizer* runs for each entity that stops matching it, whatever the cause: a despawn, a removed component, an
+owner's despawn or the world's disposal. It reads the entity's values from before, so it can release what they name
+outside the world, such as GPU buffers and DOM nodes. [This one](10-finalizers.ts#L15-L17) closes handles: the
+despawned entity's and the one whose `handle` was removed.
+
+`world.dispose()` runs every finalizer for the entities it still matches, so [the last handle](10-finalizers.ts#L46-L47)
+closes too.
+
+A *change set* is each sync point's structural changes to the components a `Finalizer.changes` watches, grouped by how
+entities changed. [`changes.previous` and `changes.next`](10-finalizers.ts#L32-L36) give a component's value before
+and after, `null` where the entity didn't have it: what saving and undo need.

package/src/guide/10-finalizers.out

@@ -0,0 +1,4 @@
+changed: null → 7, null → 8, null → 9
+changed: 7 → null, 8 → null
+open [ 9 ]
+open []

package/src/guide/10-finalizers.ts

@@ -0,0 +1,48 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { Finalizer, System, World } from "../index.js";
+
+const handle = Symbol();
+
+declare module "@adobe/ecs" {
+    interface Components {
+        [handle]: { type: number };
+    }
+}
+
+/** What handles name outside the world, as GPU buffers and DOM nodes are. */
+const open = new Set<number>();
+
+Finalizer.create({ components: { with: [handle] } }, row => {
+    open.delete(row[handle]);
+});
+
+const spawn = System.create(({ commands }) => {
+    for (const id of [7, 8, 9]) {
+        open.add(id);
+        commands.spawn([handle])({ [handle]: id });
+    }
+});
+const destroy = System.create({ components: { with: [handle] } }, (row, { commands }) => {
+    if (row[handle] === 7) commands.despawn(row.entity);
+    else if (row[handle] === 8) commands.remove(row.entity, handle);
+});
+
+const saved: string[] = [];
+
+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)}`);
+    }
+});
+
+export const main = async (): Promise<void> => {
+    const world = World.create();
+    await world.run(spawn);
+    console.log("changed:", saved.sort().join(", "));
+    saved.length = 0;
+    await world.run(destroy);
+    console.log("changed:", saved.sort().join(", "));
+    console.log("open", [...open]);
+    await world.dispose();
+    console.log("open", [...open]);
+};

package/src/guide/11-traits.md

@@ -0,0 +1,16 @@
+# Traits, within and references
+
+A declaration's fields are its *traits*. Besides `type` and `default`, these change what the world does with a
+component:
+
+- `reference: "owner"`: an `Entity` the holder belongs to. The holder is despawned with it.
+- `reference: "weak"`: an `Entity` the holder points at. The component is removed when that entity despawns.
+- `within: typeof selected`: the component is removed with `selected`.
+
+[Here](11-traits.ts#L10-L21), deselecting the mothership removes its outline; destroying it despawns the entity it
+owns and leaves the one targeting it without `target`. A row can't assign a reference; `commands.add` replaces it.
+
+**Traits of your own** are members of `interface Traits<N>`, typed as the value each allows on key `N`, or `never`
+where it doesn't apply. [`instanced`](11-traits.type-test.ts#L5-L10) applies only to components whose values are
+lists of numbers. `Component.With<typeof instanced>` is the type of every key declared with it, so
+[passing another](11-traits.type-test.ts#L21-L25) is a type error.

package/src/guide/11-traits.out

@@ -0,0 +1,2 @@
+{ outlined: 0, targeting: 1, entities: 3 }
+{ outlined: 0, targeting: 0, entities: 1 }

package/src/guide/11-traits.ts

@@ -0,0 +1,51 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { Entity, System, World } from "../index.js";
+
+const ship = Symbol();
+const parent = Symbol();
+const target = Symbol();
+const selected = Symbol();
+const outline = Symbol();
+
+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 };
+    }
+}
+
+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: { with: [selected] } }, (row, { commands }) => {
+    commands.remove(row.entity, selected);
+});
+const destroy = System.create({ components: { with: [ship] } }, (row, { commands }) => {
+    commands.despawn(row.entity);
+});
+
+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 count = System.create([countOutlined, countTargeting, countAll]);
+
+export const main = async (): Promise<void> => {
+    await using world = World.create();
+    await world.run(spawn);
+    await world.run(deselect);
+    await world.run(count);
+    console.log(counts);
+    counts.outlined = counts.targeting = counts.entities = 0;
+    await world.run(destroy);
+    await world.run(count);
+    console.log(counts);
+};

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

@@ -1,27 +1,25 @@
-import { Component, Trait } from "../index.js";
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { Component } 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");
+// A trait of your own: true for components whose values are lists of numbers, never for others.
+export const instanced = Symbol();
 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");
+const transform = Symbol();
+const name = Symbol();
 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>>();
+const instance = (key: Component.With<typeof instanced>): Component.Key => key;
+instance(transform);
+// @ts-expect-error: name isn't instanced. Without this line, TypeScript reports:
+// Argument of type 'typeof name' is not assignable to parameter of type 'typeof transform'.
+instance(name);

package/src/guide/12-lookups.md

@@ -0,0 +1,14 @@
+# Lookups
+
+A *lookup* reads another entity from a system. It's named in the declaration, `lookup: { enemy: { with, not } }`, and
+called from the body, `lookup.enemy(entity)`. It's read-only, and it doesn't change which entities the system runs on.
+
+- [The call](12-lookups.ts#L18-L24) gives the entity's row, or `null` when the entity lacks a component in `with` or
+  has one in `not`. So the tracker of the frozen statue aims at 0.
+- The row holds only what `with` lists.
+- With `changed: [health]`, the row's `changed` says whether those components may have changed since the system last
+  ran: [`watch`](12-lookups.ts#L26-L34) sees `true` on its first run and `false` on the next.
+
+A system can't look up components it writes, since a lookup reads other rows while the run writes them.
+
+To find entities by value rather than by id, look up through an [index](13-indexes.md).

package/src/guide/12-lookups.out

@@ -0,0 +1,3 @@
+aims [ 0, 40 ]
+changed [ true, true ]
+changed [ false, false ]

package/src/guide/12-lookups.ts

@@ -0,0 +1,59 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { Entity, System, World } from "../index.js";
+
+const health = Symbol();
+const target = Symbol();
+const frozen = Symbol();
+const aim = Symbol();
+
+declare module "@adobe/ecs" {
+    interface Components {
+        [health]: { type: number };
+        [target]: { type: Entity; reference: "weak" };
+        [frozen]: { type: true };
+        [aim]: { type: number };
+    }
+}
+
+const track = System.create({
+    components: { with: [target, aim] },
+    lookup: { enemy: { with: [health], not: [frozen] } },
+}, (row, { lookup }) => {
+    const enemy = lookup.enemy(row[target]);
+    row[aim] = enemy === null ? 0 : enemy[health];
+});
+
+const refreshed: boolean[] = [];
+const watch = System.create({
+    observer: true,
+    components: { with: [target] },
+    lookup: { enemy: { with: [health], changed: [health] } },
+}, (row, { lookup }) => {
+    const enemy = lookup.enemy(row[target]);
+    if (enemy !== null) refreshed.push(enemy.changed);
+});
+
+const aims: number[] = [];
+const readAims = System.create({ observer: true, components: { with: [aim] } }, row => {
+    aims.push(row[aim]);
+});
+
+const spawn = System.create(({ commands }) => {
+    const ogre = commands.spawn([health])({ [health]: 40 });
+    const statue = commands.spawn([health, frozen])({ [health]: 90 });
+    commands.spawn([target, aim])({ [target]: ogre, [aim]: -1 });
+    commands.spawn([target, aim])({ [target]: statue, [aim]: -1 });
+});
+
+export const main = async (): Promise<void> => {
+    await using world = World.create();
+    await world.run(spawn);
+    await world.run(track);
+    await world.run(readAims);
+    console.log("aims", aims.sort((a, b) => a - b));
+    await world.run(watch);
+    console.log("changed", refreshed);
+    refreshed.length = 0;
+    await world.run(watch);
+    console.log("changed", refreshed);
+};

package/src/guide/13-indexes.md

@@ -0,0 +1,21 @@
+# Indexes
+
+An *index* maps component values to the entities holding them, and every world keeps it current. `Index.create`
+declares it with a `key` and the components an entity needs to be in it; a lookup through it,
+`lookup: { at: { index: grid } }`, finds entities by value.
+
+- **Hash**, the default: [`lookup.at(key)`](13-indexes.ts#L20-L25) gives the rows with that key, in entity order.
+- **`sorted: true`**: also takes ranges, such as [`{ ">=": 90 }`](13-indexes.ts#L27-L34), and `order: byScore` runs a
+  system's rows [in the key's order](13-indexes.ts#L36-L38).
+- **`unique: true`**: [one row, or `null`](13-indexes.ts#L40-L42).
+- **`key: []`**: every entity with its components, in entity order.
+
+A lookup gives a list: its `length`, `at(i)`, and `changed`, whether an entity entered, left or moved in it since the
+system last ran. The list is reused, valid until its call site runs again, and costs only what the body reads. Its rows
+hold the index's key and `with`.
+
+With `changed: true` on the lookup, a system runs only when an entity entered or left the index anywhere. Added,
+[`countPlayers`](13-indexes.ts#L44-L47) logs once as the players arrive.
+
+A system can't look up through an index keyed by what it writes, nor order its rows by an index that isn't sorted or
+is keyed by what it writes.

package/src/guide/13-indexes.out

@@ -0,0 +1,8 @@
+players 3
+crowds [ 1, 2, 2 ]
+90 and up [ 'cy', 'ada' ]
+bo 80
+cy 91
+ada 95
+server 8 bo
+server 1 null

package/src/guide/13-indexes.ts

@@ -0,0 +1,73 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { type I32, Index, System, type Vec2, World } from "../index.js";
+
+const cell = Symbol();
+const crowded = Symbol();
+const score = Symbol();
+const player = Symbol();
+const serverId = Symbol();
+
+declare module "@adobe/ecs" {
+    interface Components {
+        [cell]: { type: Vec2.I32 };
+        [crowded]: { type: number };
+        [score]: { type: number };
+        [player]: { type: string };
+        [serverId]: { type: I32 };
+    }
+}
+
+const grid = Index.create({ key: [cell], components: { with: [crowded] } });
+
+const count = System.create({ components: { with: [cell, crowded] }, lookup: { at: { index: grid } } }, (row, { lookup }) => {
+    const [x, y] = row[cell];
+    row[crowded] = lookup.at([x, y]).length;
+});
+
+const byScore = Index.create({ key: [score], sorted: true, components: { with: [player] } });
+
+const leaders = System.create({ observer: 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 => {
+    console.log(row[player], row[score]);
+});
+
+const byServerId = Index.create({ key: [serverId], unique: true, components: { with: [player] } });
+const find = System.create({ lookup: { byId: { index: byServerId } } }, ({ lookup }, input: { readonly id: number }) =>
+    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 }) => {
+    console.log("players", lookup.players().length);
+});
+
+const crowds: number[] = [];
+const readCrowds = System.create({ observer: true, components: { with: [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 });
+});
+
+export const main = async (): Promise<void> => {
+    await using world = World.create();
+    world.add(countPlayers);
+    await world.run(spawn);
+    await world.run(count);
+    await world.run(readCrowds);
+    console.log("crowds", crowds.sort((a, b) => a - b));
+    console.log("90 and up", await world.run(leaders));
+    await world.run(list);
+    console.log("server 8", await world.run(find, { id: 8 }));
+    console.log("server 1", await world.run(find, { id: 1 }));
+};

package/src/guide/14-kernels.md

@@ -0,0 +1,15 @@
+# Kernels
+
+A *kernel* is a body the build compiles to run once per row, each row on its own, so the world can split the rows
+across workers and run them as WASM, with results the same as the body as written.
+
+The build makes a kernel of any row system whose body reads and writes only data, calls math, and touches no module
+state, without being asked: [`move`](14-kernels.ts#L18-L21) is one. Two flags change that:
+
+- `kernel: true` asserts it. The build fails, saying why, if [the body](14-kernels.ts#L23-L25) can't be one. It also
+  computes `F32` values at 32 bits, which is faster on dense rows.
+- `kernel: false` runs [the body as written](14-kernels.ts#L27-L29), on its thread: to step through it in a
+  debugger, say.
+
+In the guide, the lens above each system says what it compiles to: JS, WASM and WGSL, or as written. Its Compiled tab
+shows the code.

package/src/guide/14-kernels.out

@@ -0,0 +1 @@
+at 3, moving at 1; at 4, moving at 1; at 5, moving at 1

package/src/guide/14-kernels.ts

@@ -0,0 +1,48 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { type F32, System, Vec3, World } from "../index.js";
+
+const position = Symbol();
+const velocity = Symbol();
+const delta = Symbol();
+
+declare module "@adobe/ecs" {
+    interface Components {
+        [position]: { type: Vec3 };
+        [velocity]: { type: Vec3 };
+    }
+    interface Resources {
+        [delta]: { type: F32; default: 0.5 };
+    }
+}
+
+// A kernel without asking: the build compiles it.
+const move = System.create({ components: { with: [velocity, position] } }, (row, { resources }) => {
+    row[position] = Vec3.add(row[position], Vec3.scale(row[velocity], resources[delta]));
+});
+
+const drift = System.create({ kernel: true, components: { with: [velocity, position] } }, row => {
+    row[position] = Vec3.add(row[position], row[velocity]);
+});
+
+const slow = System.create({ kernel: false, components: { with: [velocity] } }, row => {
+    row[velocity] = Vec3.scale(row[velocity], 0.5);
+});
+
+const moved: string[] = [];
+const read = System.create({ observer: true, components: { with: [position, velocity] } }, row => {
+    moved.push(`at ${row[position][0]}, moving at ${row[velocity][0]}`);
+});
+
+const spawn = System.create(({ commands }) => {
+    for (let i = 0; i < 3; i++) commands.spawn([position, velocity])({ [position]: [i, 0, 0], [velocity]: [2, 0, 0] });
+});
+
+export const main = async (): Promise<void> => {
+    await using world = World.create();
+    await world.run(spawn);
+    await world.run(move);
+    await world.run(drift);
+    await world.run(slow);
+    await world.run(read);
+    console.log(moved.sort().join("; "));
+};

package/src/guide/15-reductions.md

@@ -0,0 +1,12 @@
+# Reductions
+
+A *reduction* folds what many rows contribute into one resource, however the rows are split across workers. Its
+[declaration](15-reductions.ts#L13-L17) names the operator: `reduce: "+"`, `"*"`, `"min"`, `"max"`, or bitwise `"&"`,
+`"|"`, `"^"`.
+
+- A body contributes with [`reduce[total](value)`](15-reductions.ts#L20-L24), as often as it likes.
+- Each run that reduces into a resource starts it at its operator's identity and leaves it holding the fold of every
+  contribution.
+- Systems can't write a reduced resource; only the fold sets it. Read it after the run, as any resource.
+
+The clock's `wake`, from [Ticks and cadence](04-ticks.md), is a reduction: the earliest time asked for wins.

package/src/guide/15-reductions.out

@@ -0,0 +1 @@
+3 weigh 10, at most 5

package/src/guide/15-reductions.ts

@@ -0,0 +1,38 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { type F32, System, World } from "../index.js";
+
+const mass = Symbol();
+const total = Symbol();
+const heaviest = Symbol();
+const count = Symbol();
+
+declare module "@adobe/ecs" {
+    interface Components {
+        [mass]: { type: F32 };
+    }
+    interface Resources {
+        [total]: { type: number; reduce: "+" };
+        [heaviest]: { type: F32; reduce: "max" };
+        [count]: { type: number; reduce: "+" };
+    }
+}
+
+const weigh = System.create({ components: { with: [mass] } }, (row, { reduce }) => {
+    reduce[total](row[mass]);
+    reduce[heaviest](row[mass]);
+    reduce[count](1);
+});
+
+const report = System.create({ observer: true }, ({ resources }) =>
+    `${resources[count]} weigh ${resources[total]}, at most ${resources[heaviest]}`);
+
+const spawn = System.create(({ commands }) => {
+    for (const value of [2, 5, 3]) commands.spawn([mass])({ [mass]: value });
+});
+
+export const main = async (): Promise<void> => {
+    await using world = World.create();
+    await world.run(spawn);
+    await world.run(weigh);
+    console.log(await world.run(report));
+};

package/src/guide/16-gpu.md

@@ -0,0 +1,18 @@
+# GPU kernels and render systems
+
+A world given a WebGPU device, `World.create({ [gpuDevice]: device })`, keeps a GPU copy of the components its GPU
+systems use.
+
+**GPU kernels.** `kernel: "gpu"` runs [the body](16-gpu.ts#L16-L18) as a compute shader over that copy, and as a kernel
+on the CPU in a world without a device, as here. Its rows hold 32-bit numbers and vectors of them, and it has no
+lookups, change filters or commands.
+
+**Render systems.** `System.render` records draws over the GPU copy of the components its `accessors` name, in a world
+with a device; without one it's skipped. [Its body](16-gpu.ts#L23-L32) gets an encoder and `tables`, each a group of
+matching rows to draw: `table.bind(pass)` binds its rows, and `table.count` says how many there are.
+
+- `Gpu.wgsl(draw)` gives the WGSL functions its shaders call, one per accessor, such as
+  `fn dotPosition(row: u32) -> vec2<f32>`.
+- `Gpu.layout(device)` gives the bind group layout its pipeline takes.
+
+The guide says whether this browser has WebGPU.

package/src/guide/16-gpu.out

@@ -0,0 +1,3 @@
+at [ 1, 2 ]
+fn dotPosition(row: u32) -> vec2<f32>
+fn dotSize(row: u32) -> f32

package/src/guide/16-gpu.ts

@@ -0,0 +1,51 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { type F32, Gpu, System, Vec2, World } from "../index.js";
+
+const position = Symbol();
+const velocity = Symbol();
+const size = Symbol();
+
+declare module "@adobe/ecs" {
+    interface Components {
+        [position]: { type: Vec2 };
+        [velocity]: { type: Vec2 };
+        [size]: { type: F32 };
+    }
+}
+
+const move = System.create({ kernel: "gpu", components: { with: [velocity, position] } }, row => {
+    row[position] = Vec2.add(row[position], row[velocity]);
+});
+
+// Made with the app's shaders, using shaderCode, and its canvas.
+let pipeline: GPURenderPipeline | null = null;
+let target: GPUTextureView | null = null;
+const draw = System.render({ shader: { accessors: { dotPosition: position, dotSize: size } } }, ({ encoder, tables }) => {
+    if (pipeline === null || target === null) return;
+    const pass = encoder.beginRenderPass({ colorAttachments: [{ view: target, loadOp: "clear", storeOp: "store" }] });
+    pass.setPipeline(pipeline);
+    for (const table of tables) {
+        table.bind(pass);
+        pass.draw(6, table.count);
+    }
+    pass.end();
+});
+const shaderCode = Gpu.wgsl(draw);
+
+const read = System.create({ observer: true, components: { with: [position] } }, row => {
+    console.log("at", row[position]);
+});
+
+const spawn = System.create(({ commands }) => {
+    commands.spawn([position, velocity, size])({ [position]: [0, 0], [velocity]: [1, 2], [size]: 4 });
+});
+
+export const main = async (): Promise<void> => {
+    // Without a device, move runs on the CPU and draw is skipped.
+    await using world = World.create();
+    await world.run(spawn);
+    await world.run(move);
+    await world.run(draw);
+    await world.run(read);
+    for (const accessor of shaderCode.match(/fn dot\w+\(.*?\) -> [\w<>]+/g) ?? []) console.log(accessor);
+};

package/src/guide/17-hierarchies.md

@@ -0,0 +1,11 @@
+# Hierarchies
+
+A hierarchy is entities pointing at their parent through a reference, here `reference: "owner"`, so a child is
+despawned with its parent.
+
+`up: { through: parent }` runs a system's rows parent first, so each row reads its parent's values as the same run
+left them. The body's `up` holds what it reads of the parent, or `null` for a row without one.
+[`place`](17-hierarchies.ts#L19-L21) adds each offset to its parent's place, so the cup, on the tray, on the table, is
+at 13 after one run.
+
+A system with `up` can't also have `order`: both decide the order of its rows.

package/src/guide/17-hierarchies.out

@@ -0,0 +1 @@
+cup at 13, table at 10, tray at 12