@adobe/ecs 0.1.0 → 0.2.1

package/src/exports.test.ts

@@ -1,3 +1,4 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 import { cpSync, mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { dirname, join, relative } from "node:path";
@@ -28,31 +29,28 @@ const install = (): void => {
 };
 
 const consumer = `
-import { Archetype, Component, Index, Rule, System, World, gpuDevice, workers } from "@adobe/ecs";
+import { Index, Rule, System, World, gpuDevice, workers } from "@adobe/ecs";
 export const position = Symbol("exportsTest/position");
 export const element = Symbol("exportsTest/element");
 export const shown = Symbol("exportsTest/shown");
 declare module "@adobe/ecs" {
     interface Components { [position]: { type: number }; [element]: { type: HTMLElement; thread: "main" }; [shown]: { type: true; derived: true } }
 }
-Component.register(position, { type: { type: "number" } });
-Component.register(element, { thread: "main" });
-Component.register(shown, { type: { const: true }, derived: true });
-export const Placed = Archetype.create([position, element]);
-export const showing = Rule.create({ components: { has: [element] }, derive: [shown] });
-export const move = System.create({ name: "exportsTest/move", components: { write: [position] } }, row => { row[position] += 1; });
-export const all = System.create({ name: "exportsTest/all", systems: [move] });
-export const draw = System.render({ name: "exportsTest/draw", shader: { accessors: {} } }, () => {});
-export const placed = Index.create({ name: "exportsTest/placed", key: [position], components: { has: [element] } });
+export const Placed = [position, element] as const;
+export const showing = Rule.create({ components: { with: [element] }, derive: [shown] });
+export const move = System.create({ components: { with: [position] } }, row => { row[position] += 1; });
+export const all = System.create({ systems: [move] });
+export const draw = System.render({ shader: { accessors: {} } }, () => {});
+export const placed = Index.create({ key: [position], components: { with: [element] } });
 export const ranked = Index.create({ key: [position], sorted: true });
-export const after = System.create({ components: { read: [position] }, lookup: { next: { index: ranked, read: [position] } } }, (row, { lookup }) => { void lookup.next({ ">": row[position] }).length; });
+export const after = System.create({ components: { with: [position] }, lookup: { next: { index: ranked } } }, (row, { lookup }) => { void lookup.next({ ">": row[position] }).length; });
 export const sortedName = (index: Index<{ readonly sorted: true }>): string => index.name;
 // A world comes from the one import every other value does.
 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: World = World.join(port, { threads: ["main"] });
-export const read = System.create({ observer: true, components: { read: [position] }, resources: { read: [gpuDevice] }, lookup: { at: { read: [position] } } }, () => {});
+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 added = world.add(read);
 `;
 
@@ -77,7 +75,7 @@ const internal = (path: string): boolean =>
     || path.startsWith("interface/gpu/record");
 
 /** Compiles a consumer's `index.ts` against the installed package, emitting its declarations. */
-const compile = (source: string): { readonly messages: string[] } => {
+const compile = (source: string): { readonly messages: string[]; readonly lines: number[] } => {
     writeFileSync(join(temporary, "index.ts"), source);
     const program = ts.createProgram([join(temporary, "index.ts")], {
         target: ts.ScriptTarget.ESNext,
@@ -91,36 +89,110 @@ const compile = (source: string): { readonly messages: string[] } => {
         outDir: join(temporary, "out"),
     });
     const result = program.emit();
-    return { messages: messages([...ts.getPreEmitDiagnostics(program), ...result.diagnostics]) };
+    const diagnostics = [...ts.getPreEmitDiagnostics(program), ...result.diagnostics];
+    // Each diagnostic's line in the consumer, 1-based; 0 for one outside it.
+    const lines = diagnostics.map(diagnostic => diagnostic.file === undefined || diagnostic.start === undefined || !diagnostic.file.fileName.endsWith("index.ts")
+        ? 0
+        : diagnostic.file.getLineAndCharacterOfPosition(diagnostic.start).line + 1);
+    return { messages: messages(diagnostics), lines };
 };
 
-/** A consumer that registers a symbol-keyed component beside the augmentation given. */
-const stringKeyed = (augmentation: string, registration = ""): string => `
-import { Component, Trait } from "@adobe/ecs";
-export const keyed = Symbol("exportsTest/keyed");
-declare module "@adobe/ecs" {
-    interface Components { [keyed]: { type: number } }
-    ${augmentation}
-}
-Component.register(keyed, { type: { type: "number" } });
-${registration}
-`;
+/** The 1-based lines of `source` holding `text`. */
+const linesWith = (source: string, text: string): number[] =>
+    source.split("\n").flatMap((line, index) => line.includes(text) ? [index + 1] : []);
 
 /** A consumer with a system whose declaration lists a key in both read and write, and composites of conflicting inputs. */
 const misdeclared = `
-import { Component, System } from "@adobe/ecs";
+import { System } from "@adobe/ecs";
 export const health = Symbol("exportsTest/health");
 declare module "@adobe/ecs" {
     interface Components { [health]: { type: number } }
 }
-Component.register(health, { type: { type: "number" } });
-export const both = System.create({ components: { read: [health], write: [health] } }, () => {});
-const near = System.create({ input: { type: "object", properties: { distance: { type: "number" } } } }, () => {});
-const far = System.create({ input: { type: "object", properties: { distance: { type: "string" } } } }, () => {});
+// What a body reads is inferred, never declared.
+export const both = System.create({ components: { read: [health] } }, () => {});
+const near = System.create({}, (_context, input: { readonly distance: number }) => { void input; });
+const far = System.create({}, (_context, input: { readonly distance: string }) => { void input; });
 export const listed = System.create([near, far]);
 export const declared = System.create({ systems: [near, far], after: [both] });
 `;
 
+/** A consumer spawning with a shared component's value missing, a constant outside its list, and a value given twice. */
+const misspawned = `
+import { System } from "@adobe/ecs";
+export const team = Symbol("exportsTest/team");
+export const health = Symbol("exportsTest/health");
+export const armor = Symbol("exportsTest/armor");
+declare module "@adobe/ecs" {
+    interface Components { [team]: { type: "red" | "blue"; shared: true }; [health]: { type: number }; [armor]: { type: number } }
+}
+export const spawning = System.create(({ commands }) => {
+    commands.spawn([team, health]);
+    commands.spawn([team], { [team]: "red", [health]: 1 });
+    const whole = commands.spawn([team, health], { [team]: "red", [health]: 1 });
+    whole();
+    whole({});
+    whole({ [health]: 2 });
+    whole({ [armor]: 2 });
+    commands.spawn([team, health, armor], { [team]: "red", [health]: 1 })({ [armor]: 1, [health]: 2 });
+});
+`;
+
+/** A consumer creating two worlds and using them, with `declarations` augmenting the package. */
+const creating = (declarations: string): string => `
+import { World, workers, type Component } from "@adobe/ecs";
+${declarations}
+export const world: World = World.create();
+export const other: World = World.create({ [workers]: 0 });
+export const typed: World = world;
+export const disposed = other.dispose();
+`;
+
+/** A trait of your own on a key its type doesn't allow. */
+const customTrait = creating(`
+export const instanced = Symbol();
+export const foo = Symbol();
+declare module "@adobe/ecs" {
+    interface Traits<N> { readonly [instanced]: N extends Component.Key ? ([Component<N>] extends [readonly number[]] ? true : never) : never }
+    interface Components { [foo]: { type: string; [instanced]: true } }
+}`);
+
+/** A built-in trait on a key its type doesn't allow: a thread on a struct. */
+const builtInTrait = creating(`
+export const spot = Symbol();
+declare module "@adobe/ecs" {
+    interface Components { [spot]: { type: number; thread: "main" } }
+}`);
+
+/** A shared component of a value that isn't comparable data: a map. */
+const sharedMap = creating(`
+export const scores = Symbol();
+declare module "@adobe/ecs" {
+    interface Components { [scores]: { type: ReadonlyMap<string, number>; shared: true } }
+}`);
+
+/** A default that isn't of the declared type. */
+const wrongDefault = creating(`
+export const label = Symbol();
+declare module "@adobe/ecs" {
+    interface Resources { [label]: { type: string; default: 1 } }
+}`);
+
+/** One key with several members that don't hold: a custom trait and a thread on a string. */
+const severalTraits = creating(`
+export const instanced = Symbol();
+export const name = Symbol();
+declare module "@adobe/ecs" {
+    interface Traits<N> { readonly [instanced]: N extends Component.Key ? ([Component<N>] extends [readonly number[]] ? true : never) : never }
+    interface Components { [name]: { type: string; [instanced]: true; thread: "main" } }
+}`);
+
+/** One key whose default is of another type and which can't be transferred. */
+const defaultAndTransfer = creating(`
+export const canvas = Symbol();
+declare module "@adobe/ecs" {
+    interface Resources { [canvas]: { type: string; default: 1; transfer: true } }
+}`);
+
 describe("package exports", () => {
     beforeAll(() => {
         install();
@@ -132,10 +204,9 @@ describe("package exports", () => {
         // An index's type reads as it was declared, naming only the package root.
         const emitted = readFileSync(join(temporary, "out", "index.d.ts"), "utf8");
         expect(emitted).toContain(`export declare const placed: Index<{
-    readonly name: "exportsTest/placed";
     readonly key: readonly [typeof position];
     readonly components: {
-        readonly has: readonly [typeof element];
+        readonly with: readonly [typeof element];
     };
 }>;`);
         expect(emitted).toContain(`export declare const ranked: Index<{
@@ -144,21 +215,55 @@ describe("package exports", () => {
 }>;`);
         expect([...emitted.matchAll(/import\("([^"]+)"\)/g)].map(match => match[1]).filter(path => path !== "@adobe/ecs")).toEqual([]);
     }, 60_000);
+    it("report a declaration that doesn't hold once at each World.create call, naming the key, the member and the problem", () => {
+        const cases = [
+            { source: customTrait, named: `readonly [foo]: { readonly [instanced]: "isn't allowed on this key"; }` },
+            { source: builtInTrait, named: `readonly [spot]: { readonly thread: "isn't allowed on this key"; }` },
+            { source: sharedMap, named: `readonly [scores]: { readonly shared: "isn't allowed on this key"; }` },
+            { source: wrongDefault, named: `readonly [label]: { readonly default: "isn't of the declared type"; }` },
+        ];
+        for (const { source, named } of cases) {
+            const { messages: reported, lines } = compile(source);
+            // One error per call, on the call; uses of the worlds type-check.
+            expect(lines).toEqual(linesWith(source, "World.create("));
+            for (const message of reported) {
+                expect(message).toContain("declarations don't hold");
+                expect(message).toContain(named);
+            }
+        }
+        expect(compile(creating("")).messages).toEqual([]);
+    }, 60_000);
+    it("name every member of a key that doesn't hold", () => {
+        const cases = [
+            { source: severalTraits, named: [`readonly [instanced]: "isn't allowed on this key"`, `readonly thread: "isn't allowed on this key"`] },
+            { source: defaultAndTransfer, named: [`readonly default: "isn't of the declared type"`, `readonly transfer: "isn't allowed on this key"`] },
+        ];
+        for (const { source, named } of cases) {
+            const { messages: reported, lines } = compile(source);
+            expect(lines).toEqual(linesWith(source, "World.create("));
+            for (const message of reported) for (const member of named) expect(message).toContain(member);
+        }
+    }, 60_000);
+    it("report a spawn's missing shared value, a constant outside its list and a value given in both calls by the key", () => {
+        const { messages: reported, lines } = compile(misspawned);
+        const at = (text: string): number => linesWith(misspawned, text)[0];
+        const on = (line: number): string => reported.filter((_, k) => lines[k] === line).join("\n");
+        expect(on(at("commands.spawn([team, health]);"))).toContain(`"error: a spawn of a shared component takes its value first, in its constants"`);
+        expect(on(at("commands.spawn([team, health]);"))).toContain(`{ readonly [team]: "red" | "blue"; }`);
+        expect(on(at(`commands.spawn([team], {`))).toContain(`"error: a constant names a component of the spawn's list"`);
+        expect(on(at(`commands.spawn([team], {`))).toContain(`{ readonly [health]: "isn't one"; }`);
+        expect(on(at("whole();"))).toBe("");
+        expect(on(at("whole({});"))).toBe("");
+        expect(on(at("whole({ [health]: 2 });"))).toContain(`"error: a spawn gives each component's value in one of its calls, this one in its constants": { readonly [health]: "given"; }`);
+        expect(on(at("whole({ [armor]: 2 });"))).not.toBe("");
+        expect(on(at("({ [armor]: 1, [health]: 2 });"))).toContain(`"error: a spawn gives each component's value in one of its calls, this one in its constants"`);
+        expect(lines.filter(line => line === 0)).toEqual([]);
+    }, 60_000);
     it("report a misdeclared system, and a composite of conflicting members, at the mistake rather than as no overload matching", () => {
         const reported = compile(misdeclared).messages;
         expect(reported.some(message => message.includes("No overload matches"))).toBe(false);
         expect(reported.filter(message => message.includes(`has a different type in another member of this composite.`))).toHaveLength(4);
-        expect(reported.some(message => message.startsWith("Type '[unique symbol]' is not assignable"))).toBe(true);
-    }, 60_000);
-    it("fail every registration to compile while a component, resource or trait is keyed by a string, naming the keys", () => {
-        expect(compile(stringKeyed(`interface Components { "exportsTest/named": { type: number } }`)).messages.join("\n"))
-            .toContain(`'{ readonly "component keys must be symbols": "exportsTest/named"; }'`);
-        expect(compile(stringKeyed(`interface Resources { "exportsTest/time": { type: number } }`)).messages.join("\n"))
-            .toContain(`'{ readonly "resource keys must be symbols": "exportsTest/time"; }'`);
-        const trait = compile(stringKeyed(`interface Traits<N> { readonly persisted: true }`, `Trait.register("persisted");`)).messages.join("\n");
-        expect(trait).toContain(`'{ readonly "trait keys must be symbols": "persisted"; }'`);
-        // Registration takes only symbol keys, so a string-keyed trait can't be registered either.
-        expect(trait).toContain(`Argument of type '"persisted"' is not assignable`);
+        expect(reported.some(message => message.startsWith("Type 'symbol[]' is not assignable to type 'undefined'"))).toBe(true);
     }, 60_000);
 });
 

package/src/guide/00-keys.md

@@ -0,0 +1,34 @@
+# Keys and declarations
+
+Every component and resource is a *key*: a `Symbol()` [bound at a module's top level](00-keys.ts#L5-L6).
+
+- A symbol is unique, so keys from different libraries can't collide as strings can, and a minifier can't rename two
+  into one.
+- TypeScript types each `const` symbol as its own `unique symbol`, so the key itself can carry its value's type.
+
+A *declaration* gives a key its type. [`declare module "@adobe/ecs"`](00-keys.ts#L8-L15) is TypeScript's module
+augmentation: it merges your entries into the package's `Components`, `Resources` and `Traits` interfaces. That's what
+types [`row[score]` and `resources[bonus]`](00-keys.ts#L22-L24) as numbers, with no generics anywhere.
+
+A declaration's fields are its *traits*: `type`, `default`, and others that later chapters introduce, such as `reduce`
+([Reductions](15-reductions.md)), `reference` and `within` ([Traits](11-traits.md)), `thread` ([Threads](19-threads.md))
+and `shared` ([Shared components](20-shared.md)). A type named by `Schema.Type`, such as `F32` or `U32`, sets the stored
+precision or width.
+
+**What the build does.** `Compiler.plugin()` reads each declaration: it records the key with its schema, which the
+package registers the first time it's needed, and gives the key an *id* from its package's name and version, its
+module's path and its binding, such as `my-game@1.0.0/src/score.ts#score`. Threads, and a module evaluated again by hot
+reload, agree on a key by its id ([Identity and ids](18-identity.md)).
+
+**The rules**, and what breaking each gives:
+
+- A key is a `Symbol()` constant at the top level of the module that declares it. A `Symbol.for` key, which the
+  whole program shares, a well-known symbol, or a key made any other way fails the build: *a component's key score is
+  a top-level `Symbol()` constant of this module*. So does declaring an imported key: *a component's key score is
+  imported from "./keys.js": declare it in the module that declares the key*.
+- A key used but not declared is TypeScript's error at each use, such as *Type 'symbol' is not assignable to type
+  'never'* where a list names it, and the system naming it fails as its module loads:
+  *System "award" uses component "score", which isn't a registered component: declare it beside its key, in interface
+  Components or Resources.*
+- A trait or default that doesn't hold makes every `World.create` call fail to type-check, naming the key and what's
+  wrong.

package/src/guide/00-keys.out

@@ -0,0 +1 @@
+score 15

package/src/guide/00-keys.ts

@@ -0,0 +1,35 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { System, World } from "../index.js";
+
+// Each key a Symbol() bound at the module's top level.
+export const score = Symbol();
+export const bonus = Symbol();
+
+declare module "@adobe/ecs" {
+    interface Components {
+        [score]: { type: number };
+    }
+    interface Resources {
+        [bonus]: { type: number; default: 5 };
+    }
+}
+
+const spawn = System.create(({ commands }) => {
+    commands.spawn([score])({ [score]: 10 });
+});
+
+// No generics: the declarations type row[score] and resources[bonus] as numbers.
+const award = System.create({ components: { with: [score] } }, (row, { resources }) => {
+    row[score] += resources[bonus];
+});
+
+const read = System.create({ observer: true, components: { with: [score] } }, row => {
+    console.log("score", row[score]);
+});
+
+export const main = async (): Promise<void> => {
+    await using world = World.create();
+    await world.run(spawn);
+    await world.run(award);
+    await world.run(read);
+};

package/src/guide/00-setup.md

@@ -0,0 +1,24 @@
+# Setup
+
+Install `@adobe/ecs` and add its build plugin to Vite:
+
+```ts
+import { Compiler } from "@adobe/ecs/compiler";
+export default defineConfig({ plugins: [Compiler.plugin()] });
+```
+
+The plugin is part of the API, not an optimization. It reads each system's body to infer what the body reads and
+writes, compiles kernels, reads the schema of each value from its declared type, and gives every key and system an id.
+
+- A library builds with `Compiler.plugin({ library: true })`, so its build ships the registrations its declarations
+  give.
+- Kernels run on workers loaded as separate chunks, so the plugin sets Vite's `worker.format` to `"es"` unless the
+  config sets it.
+
+Components and resources are keys, each declared once with its type: [Keys and declarations](00-keys.md).
+
+**Systems** declare only what their body can't show: the entities they run over, their change filters and
+conditions, and their order. Write the body inline in `System.create`, indexing rows and resources by key, so the
+plugin can read it.
+
+Each chapter's example is a program whose `main` creates worlds, runs systems on them and logs what they did.

package/src/guide/01-resources.md

@@ -0,0 +1,22 @@
+# Resources
+
+A *resource* is a value a world holds once: a setting, a clock, a handle to an audio context, [declared](01-resources.ts#L14-L23)
+in `Resources`.
+
+A world starts each resource at the first of these that applies:
+
+1. the value given to `World.create`, as [the moon](01-resources.ts#L30) gives `gravity`;
+2. its `default` trait, a literal;
+3. its type's namespace's `default`, as [`Height`](01-resources.ts#L11-L12) gives; every world shares that value, so
+   it's read-only;
+4. a reduction's identity ([Reductions](15-reductions.md)), `null` for a nullable type, the zero value (`0`, `false`,
+   `""`, item by item), or an empty `ReadonlyMap` or `ReadonlySet` of each world's own.
+
+Data, such as numbers, strings, tuples, structs, maps and sets, is held as a value: a system replaces it whole. A value
+that isn't data, such as an `AudioContext`, is stored as it is; a change inside it is seen only once the resource is
+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.
+[`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.out

@@ -0,0 +1,2 @@
+[ -9.8, -Infinity, Map(0) {}, null, 0 ]
+[ -1.6, -Infinity, Map(0) {}, null, 0 ]

package/src/guide/01-resources.ts

@@ -0,0 +1,33 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { Entity, System, World, type F32 } from "../index.js";
+
+export const gravity = Symbol();
+export const floor = Symbol();
+export const names = Symbol();
+export const audio = Symbol();
+export const focused = Symbol();
+
+// A type whose namespace gives the value it starts at.
+export type Height = F32;
+export const Height = { default: -Infinity } as const;
+
+declare module "@adobe/ecs" {
+    interface Resources {
+        [gravity]: { type: number; default: -9.8 };
+        [floor]: { type: Height };
+        [names]: { type: ReadonlyMap<string, number> };
+        // Not data: stored as it is.
+        [audio]: { type: AudioContext | null };
+        [focused]: { type: Entity };
+    }
+}
+
+const read = System.create({ observer: true }, ({ resources }) =>
+    [resources[gravity], resources[floor], resources[names], resources[audio], resources[focused]]);
+
+export const main = async (): Promise<void> => {
+    await using earth = World.create();
+    await using moon = World.create({ [gravity]: -1.6 });
+    console.log(await earth.run(read));
+    console.log(await moon.run(read));
+};

package/src/guide/02-entities.md

@@ -0,0 +1,19 @@
+# Entities, components and archetypes
+
+An *entity* is an id. A *component* is a key whose values entities hold, [declared](02-entities.ts#L8-L15) in
+`Components` as a resource is. A component of `type: true` is a *tag*: an entity has it or doesn't, with no value.
+
+An *archetype* is a list of components declared `as const` at module scope, such as
+[`Particle`](02-entities.ts#L17). The build indexes it, and it goes wherever a list of components does. The world
+stores entities with the same set of components together.
+
+Systems change which entities exist through `commands`:
+
+- `commands.spawn(components)(values)` [spawns an entity](02-entities.ts#L19-L22) with those components. A
+  component left out of the values, such as the tag, starts at its default.
+- `commands.add` and `commands.remove` add and remove components; `commands.despawn` removes the entity. Here
+  [`defeat`](02-entities.ts#L24-L26) removes the tag, so the entity stops being a foe.
+
+A system with `components: { with: [...] }` runs once per entity that has every listed component, its *row*, which
+holds those values. `with: [...Particle]` spreads an archetype into a list. Since `defeat` removed the tag,
+[the last read](02-entities.ts#L42) finds no foe and logs nothing.

package/src/guide/02-entities.out

@@ -0,0 +1,2 @@
+a foe at [ 0, 10, 0 ]
+a particle moving at [ 1, 0, 0 ]

package/src/guide/02-entities.ts

@@ -0,0 +1,43 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { System, Vec3, World } from "../index.js";
+
+export const position = Symbol();
+export const velocity = Symbol();
+export const enemy = Symbol();
+
+declare module "@adobe/ecs" {
+    interface Components {
+        [position]: { type: Vec3 };
+        [velocity]: { type: Vec3 };
+        // A tag: present or not.
+        [enemy]: { type: true };
+    }
+}
+
+export const Particle = [position, velocity] as const;
+
+export const spawn = System.create(({ commands }) => {
+    commands.spawn([position, enemy])({ [position]: [0, 10, 0] });
+    commands.spawn(Particle)({ [position]: [0, 0, 0], [velocity]: [1, 0, 0] });
+});
+
+export const defeat = System.create({ components: { with: [enemy] } }, (row, { commands }) => {
+    commands.remove(row.entity, enemy);
+});
+
+const readFoes = System.create({ observer: true, components: { with: [position, enemy] } }, row => {
+    console.log("a foe at", row[position]);
+});
+const readParticles = System.create({ observer: true, components: { with: [...Particle] } }, row => {
+    console.log("a particle moving at", row[velocity]);
+});
+
+export const main = async (): Promise<void> => {
+    await using world = World.create();
+    await world.run(spawn);
+    await world.run(readFoes);
+    await world.run(readParticles);
+    await world.run(defeat);
+    // No foe is left: logs nothing.
+    await world.run(readFoes);
+};

package/src/guide/03-systems.md

@@ -0,0 +1,22 @@
+# Systems
+
+A *system* is a declaration and a body, made by `System.create`. The declaration says which entities it runs over;
+the build infers from the body what it reads and writes, which orders it against other systems and lets the world run
+it in parallel.
+
+- **Row systems** run once per matching entity. [`move`](03-systems.ts#L28-L33) runs over entities with every
+  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.
+- **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.
+
+A run resolves to what a system without components returns, so [`frameCount`](03-systems.ts#L49) reads a resource
+back.
+
+**Failure.** A system whose body throws fails, and its run rejects with an `Error` naming each failed system by its
+binding and id. The others' work still applies: [`countThenFail`](03-systems.ts#L54) still counts a frame, as the last
+line shows.

package/src/guide/03-systems.out

@@ -0,0 +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
+frames 2

package/src/guide/03-systems.ts

@@ -0,0 +1,68 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { System, Vec3, World } from "../index.js";
+
+const position = Symbol();
+const velocity = Symbol();
+const frozen = Symbol();
+const delta = Symbol();
+const frames = Symbol();
+
+declare module "@adobe/ecs" {
+    interface Components {
+        [position]: { type: Vec3 };
+        [velocity]: { type: Vec3 };
+        [frozen]: { type: true };
+    }
+    interface Resources {
+        [delta]: { type: number; default: 0.5 };
+        [frames]: { type: number };
+    }
+}
+
+const spawn = System.create(({ commands }) => {
+    commands.spawn([position, velocity])({ [position]: [0, 0, 0], [velocity]: [2, 0, 0] });
+    commands.spawn([position, velocity, frozen])({ [position]: [0, 0, 0], [velocity]: [2, 0, 0] });
+    commands.spawn([position])({ [position]: [5, 0, 0] });
+});
+
+const move = System.create({
+    components: { with: [velocity, position], not: [frozen] },
+}, (row, { resources }) => {
+    // Values are replaced whole, never edited in place.
+    row[position] = Vec3.add(row[position], Vec3.scale(row[velocity], resources[delta]));
+});
+
+const count = System.create({}, ({ resources }) => {
+    resources[frames] += 1;
+});
+
+const places: number[] = [];
+const read = System.create({ observer: 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 => {
+    speeds.push(row[velocity] === undefined ? "still" : `at ${row[velocity][0]}`);
+});
+
+const frameCount = System.create({ observer: true }, ({ resources }) => resources[frames]);
+
+const fail = System.create(() => {
+    throw new Error("broken");
+});
+const countThenFail = System.create([count, fail]);
+
+export const main = async (): Promise<void> => {
+    await using world = World.create();
+    await world.run(spawn);
+    await world.run(move);
+    await world.run(read);
+    console.log("at", places.sort((a, b) => a - b));
+    await world.run(readSpeeds);
+    console.log("moving", speeds.sort());
+    await world.run(count);
+    console.log("frames", await world.run(frameCount));
+    await world.run(countThenFail).catch((error: unknown) => console.log(String(error)));
+    console.log("frames", await world.run(frameCount));
+};

package/src/guide/04-ticks.md

@@ -0,0 +1,18 @@
+# Ticks and cadence
+
+A *tick* is one beat of a world's loop, which runs every system added to it. `world.add(system)` runs a system on
+every tick from then on, and [`world.remove`](04-ticks.ts#L41) takes it off.
+
+- `clock` is a resource the world writes on each tick: `delta` is the milliseconds since the last one, `now` the time
+  and `tick` the count. [`advance`](04-ticks.ts#L14-L16) accumulates `delta`.
+- `cadence` says when ticks happen: once per animation frame by default, or, with `{ kind: "fixed", step }`, every
+  `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`:
+[`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:
+`reduce[wake](time)` makes the first tick at or after that time run. [`step`](04-ticks.ts#L25-L28) does it twice, so
+the second world, without `always`, ticks three times for one run. Work that one tick's commands start and a later
+tick finishes asks for its next tick this way.

package/src/guide/04-ticks.out

@@ -0,0 +1,3 @@
+elapsed 30 ms, each tick 10
+stopped true
+steps 3