@adobe/ecs 0.1.0 → 0.2.0

package/dist/interface/thread/of.d.ts

@@ -1,9 +1,11 @@
 import type { IsShared } from '../schema/is-struct.js';
 import type { Thread } from './thread.js';
 /**
- * The thread a value of type `T` declared with traits `Entry` lives on: none for a struct or a string, else its `thread`
- * or `"world"`.
+ * The thread a value of type `T` declared with traits `Entry` lives on: none for a struct, a string or a shared
+ * component's value, which every thread reads, else its `thread` or `"world"`.
  */
 export type ThreadOf<Entry, T> = IsShared<T> extends true ? never : Entry extends {
+    readonly shared: true;
+} ? never : Entry extends {
     readonly thread: infer H extends Thread;
 } ? H : "world";

package/dist/interface/trait/key.d.ts

@@ -1,4 +1,4 @@
 import type { Traits } from './types.js';
 export type Key = keyof Traits<never>;
 /** The core's traits, the only ones named by strings. */
-export type BuiltIn = "type" | "derived" | "within" | "reference" | "reduce" | "thread" | "transfer";
+export type BuiltIn = "type" | "derived" | "within" | "reference" | "reduce" | "thread" | "transfer" | "shared";

package/dist/interface/trait/types.d.ts

@@ -4,7 +4,7 @@ import type { Entity } from '../entity/entity.js';
 import type { IsNode, IsTransferable } from '../platform/platform.js';
 import type { Resource } from '../resource/resource.js';
 import type { Reduction } from '../resource/reduction.js';
-import type { IsString, IsStruct } from '../schema/is-struct.js';
+import type { IsComparable, IsString, IsStruct } from '../schema/is-struct.js';
 import type { Thread } from '../thread/thread.js';
 /** The value type of the component or resource `N`. */
 type ValueOf<N> = N extends Component.Key ? Component.Value<N> : N extends Resource.Key ? Resource.Value<N> : never;
@@ -18,15 +18,18 @@ type Structs = {
 };
 /**
  * The value each trait allows on the component or resource `N`. Augment it, with this exact type parameter, to
- * define a trait, and register its name with `Trait.register`. A trait that doesn't apply to `N` resolves to `never`.
+ * define a trait, keyed by a `Symbol()` constant of the same module, which the build registers. A trait that doesn't
+ * apply to `N` resolves to `never`.
  * An allowed value may look at `N`'s own traits and at the one component a declared value names, never map over
  * every component, or checking grows with the square of the component count.
  */
 export interface Traits<N extends Component.Key | Resource.Key> {
     /** The value type: declared as a TypeScript type, registered as a schema for it when it's data. */
     readonly type: unknown;
-    /** Present only while a rule deriving it matches, so commands never add or remove it. */
-    readonly derived: N extends Component.Key ? true : never;
+    /** Present only while a rule deriving it matches, so commands never add or remove it. Not on a shared component. */
+    readonly derived: N extends Component.Key ? Components[N] extends {
+        readonly shared: true;
+    } ? never : true : never;
     /** Exists only while its host component does, and is removed with it. Not on a derived component, which its rule covers. */
     readonly within: N extends Component.Key ? Components[N] extends {
         readonly derived: true;
@@ -39,6 +42,8 @@ export interface Traits<N extends Component.Key | Resource.Key> {
      */
     readonly reference: N extends Component.Key ? Components[N] extends {
         readonly derived: true;
+    } | {
+        readonly shared: true;
     } ? never : [Component.Value<N>] extends [Entity] ? "owner" | "weak" : never : never;
     /**
      * On a resource, the operator systems reduce into it with: each run that a contributor runs in starts it at the
@@ -49,8 +54,21 @@ export interface Traits<N extends Component.Key | Resource.Key> {
      * The logical thread an object lives on, `"world"` without it. Not on a struct or a string, which live in shared
      * memory. A DOM `Node` lives on `"main"`, and says so.
      */
-    readonly thread: Structs[N] extends true | "string" ? never : IsNode<ValueOf<N>> extends true ? "main" : Thread;
+    readonly thread: Structs[N] extends true | "string" ? never : N extends Component.Key ? Components[N] extends {
+        readonly shared: true;
+    } ? never : IsNode<ValueOf<N>> extends true ? "main" : Thread : IsNode<ValueOf<N>> extends true ? "main" : Thread;
     /** The value may be moved, never copied, to its thread: only a Transferable value. */
     readonly transfer: IsTransferable<ValueOf<N>> extends true ? true : never;
+    /**
+     * On a component of comparable data (numbers, booleans, strings, arrays and plain objects of those): each archetype
+     * holds one value of it for every entity it holds, so entities of equal values share an archetype. Rows read it as
+     * their archetype's value; `commands.add` with another value moves the entity. Not on a derived component or a
+     * reference, and it has no thread: every thread reads it.
+     */
+    readonly shared: N extends Component.Key ? Components[N] extends {
+        readonly derived: true;
+    } | {
+        readonly reference: unknown;
+    } ? never : IsComparable<Component.Value<N>> extends true ? true : never : never;
 }
 export {};

package/dist/interface/world/create.d.ts

@@ -1,5 +1,6 @@
 import type { Resource } from '../resource/resource.js';
 import type { WorldWritten } from '../resource/written.js';
+import type { InvalidDeclarations } from './declarations.js';
 import type { World } from './world.js';
 /** Values resources start at in place of their defaults: any but those only the world writes. */
 export type InitialResources = {
@@ -10,6 +11,11 @@ export type InitialResources = {
  * defaults. This thread is its `"world"` thread for the world's life: it runs the sync points, the ticks and the GPU
  * device, and fills every logical thread no joined thread claims. Keys are the resources' symbols, built-in ones
  * included (`{ [workers]: 0 }`); string keys are never a resource's, so they're ignored. Throws for a symbol that isn't
- * a resource, or is one only the world writes.
+ * a resource, or is one only the world writes. While a declaration's trait or default doesn't hold, each call fails to
+ * compile, once, naming each such key, its members and what's wrong with them.
  */
-export type Create = (resources?: InitialResources) => World;
+export type Create = (this: [InvalidDeclarations] extends [never] ? unknown : {
+    readonly "declarations don't hold": {
+        readonly [D in InvalidDeclarations as D["key"]]: D["members"];
+    };
+}, resources?: InitialResources) => World;

package/dist/interface/world/declarations.d.ts

@@ -0,0 +1,37 @@
+import type { Component } from '../component/component.js';
+import type { Components } from '../component/types.js';
+import type { Resource } from '../resource/resource.js';
+import type { Resources } from '../resource/types.js';
+import type { Key as TraitKey } from '../trait/key.js';
+import type { Traits } from '../trait/types.js';
+/**
+ * The members of key `K`'s declaration `Entry` that don't hold: a trait whose value `Traits<K>` doesn't allow, a name
+ * that isn't a trait, and a `default` that isn't of the declared type. Checks only `K`'s own traits, so the whole check
+ * is linear in the declarations.
+ */
+type Invalid<K extends Component.Key | Resource.Key, Entry, Value> = {
+    readonly [T in Exclude<keyof Entry, "type" | "default">]-?: T extends TraitKey ? ([Entry[T]] extends [Traits<K>[T]] ? never : T) : T;
+}[Exclude<keyof Entry, "type" | "default">] | (Entry extends {
+    readonly default: infer D;
+} ? ([D] extends [Value] ? never : "default") : never);
+/**
+ * Key `K` with what's wrong with each member that doesn't hold, keyed by member so an error prints a trait by its
+ * key's binding; written in place, as an alias would print by its name.
+ */
+type Reported<K, Members extends PropertyKey> = [Members] extends [never] ? never : {
+    readonly key: K;
+    readonly members: {
+        readonly [M in Members]: M extends "default" ? "isn't of the declared type" : M extends TraitKey ? "isn't allowed on this key" : "isn't a trait";
+    };
+};
+/**
+ * Every declaration in `Components` and `Resources` with members that don't hold, each as its key and what's wrong
+ * with those members; `never` when all hold. The build registers declarations without a type checker, so
+ * `World.create` reports these.
+ */
+export type InvalidDeclarations = {
+    readonly [K in Component.Key]: Reported<K, Invalid<K, Components[K], Component.Value<K>>>;
+}[Component.Key] | {
+    readonly [K in Resource.Key]: Reported<K, Invalid<K, Resources[K], Resource.Value<K>>>;
+}[Resource.Key];
+export {};

package/dist/interface/world/declarations.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=declarations.js.map

package/dist/interface/world/declarations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"declarations.js","sourceRoot":"","sources":["../../../src/interface/world/declarations.ts"],"names":[],"mappings":""}

package/dist/interface/world/filter.js

@@ -1,2 +1,3 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 export {};
 //# sourceMappingURL=filter.js.map

package/dist/interface/world/filter.js.map

@@ -1 +1 @@
-{"version":3,"file":"filter.js","sourceRoot":"","sources":["../../../src/interface/world/filter.ts"],"names":[],"mappings":""}
+{"version":3,"file":"filter.js","sourceRoot":"","sources":["../../../src/interface/world/filter.ts"],"names":[],"mappings":"AAAA,uDAAuD"}

package/dist/interface/world/join.d.ts

@@ -2,10 +2,16 @@ import type { Thread } from '../thread/thread.js';
 import type { World } from './world.js';
 /**
  * Joins, from another thread, a world that `share` let join through the other end of `port`, claiming the logical
- * `threads` this thread fills: their objects live here, and the systems and finalizers reading them run here. The world
- * it returns is the same one: its `run` runs systems there, and its `add` and `remove` take observer systems, which run
- * here after the world's sync points. Its `dispose` disconnects this thread.
+ * `threads` this thread fills: their objects live here, and the systems and finalizers reading them run here. Resolves,
+ * once the world accepted the claim, to the same world: its `run` runs systems there, and its `add` and `remove` take
+ * observer systems, which run here after the world's sync points. Add them before awaiting anything else, so the
+ * world's `share` resolves with them in place. Its `dispose` disconnects this thread. Rejects with an `Error` saying
+ * why it didn't join: the world refused the claim, was disposed, or its thread ended first, as the platform reports it:
+ * the world's `Worker` failing to start or throwing first, a port closed, as in node, or, in a browser, the world's
+ * thread ending once it was shared through a port this thread listened on. A browser world's worker that the page ended
+ * before this thread heard from it isn't reported, so the join stays pending. Rejects too where memory can't be shared,
+ * as without cross-origin isolation.
  */
 export type Join = (port: Parameters<World["share"]>[0], options?: {
     readonly threads?: readonly Exclude<Thread, "world">[];
-}) => World;
+}) => Promise<World>;

package/dist/interface/world/world.d.ts

@@ -7,25 +7,33 @@ import type { System } from '../system/system.js';
 export type World = {
     /**
      * The one way to change state. Runs are sequential in call order; physically, any that don't conflict overlap. Each
-     * runs a system or composite, ending in a sync point, and resolves to its number: every run and tick takes the
-     * next, in the order they run. What went wrong, if anything, is a report the world spawns for that number (see
-     * `Report`): systems, finalizers and GPU work that failed, systems skipped after a failed tier, commands that did
-     * nothing, and warnings. Rejects only when the run can't happen or finish: registration fails, the world is
-     * disposed, its GPU device is lost, or its sync point can't apply a command's value. Observer systems, the run's and
-     * those added, run after its sync point and its report, before it resolves; their throws are `"system"` failures
-     * in the next run's report, since each report's errors are written once. A run of observer systems alone runs them
-     * once after an empty sync point, and doesn't wake the loop.
+     * runs a system or composite, ending in a sync point, then observer systems, the run's and those added, and
+     * resolves to what a per-run body returns: a system without components resolves to its body's value, or
+     * `undefined` when its body was skipped, and any other system or composite to nothing. So a one-off read is a run
+     * of an observer system returning what it read; one that runs on a joined thread, as it reads objects there, runs
+     * there before the run resolves, to its value as structured clone. A run of observer systems alone runs them once
+     * after an empty sync point, and doesn't wake the loop.
+     *
+     * When a system or finalizer of the run fails, later tiers are skipped, the sync point still applies what was done,
+     * and once its observer systems ran the run rejects with an `Error` naming each failure, its system's label and id,
+     * message and cause. It rejects too when the run can't happen or finish: registration fails, the world is disposed,
+     * its GPU device is lost, or its sync point can't apply a command's value. What fails after it, an observer system
+     * added or GPU work, is reported out of band, as ticks' failures are (see `add`).
      */
-    run<I>(system: System<I>, ...input: Input<NoInfer<I>>): Promise<number>;
+    run<I, R>(system: System<I, R>, ...input: Input<NoInfer<I>>): Promise<R>;
     /**
      * Adds a system to every tick, from the next one on, ordered with those already added by its constraints, as a
      * composite's members are. A tick runs on a beat of the `cadence` resource where `always` is set, `wake` is due or
      * a run arrived since the last tick, and only while some system is added. Throws for a system with no ordering path
-     * to one already added that conflicts with it; failures are in the tick's report. An observer system runs after
-     * every run's and tick's sync point instead. It never conflicts and doesn't count as an added system for ticking.
-     * On a joined thread `add` takes only observer systems, whose keys need ids: each runs on that thread after the
-     * world's sync points, once for the newest when the thread fell behind, reading structs and the objects of the
-     * threads it fills as of one sync point; its failures are in a later run's report.
+     * to one already added that conflicts with it. An observer system runs after every run's and tick's sync point
+     * instead. It never conflicts and doesn't count as an added system for ticking. On a joined thread `add` takes only
+     * observer systems, whose keys need ids: each runs on that thread after the world's sync points, once for the
+     * newest when the thread fell behind, reading structs and the objects of the threads it fills as of one sync point.
+     *
+     * What added systems throw, and what fails in ticks, is reported out of band on the world's thread, as an `Error`
+     * naming what failed with what it threw as its cause: through `reportError` where the platform has it, as browsers
+     * and their workers do, and otherwise thrown from a task of its own, an uncaught exception, as in node. A system is
+     * reported once while it keeps failing, and again once it has run without failing since.
      */
     add(system: System<void>): void;
     /**
@@ -39,8 +47,14 @@ export type World = {
     /**
      * Lets another thread join this world through `port`, one end of a channel to it, of the browser or node: a
      * `MessagePort`, a `Worker`, or a worker's own scope, `self` or node's `parentPort`. That thread joins through the
-     * other end, claiming the logical threads it fills; a thread claimed twice can't join. Throws on a joined thread,
-     * and where memory can't be shared, as without cross-origin isolation.
+     * other end, claiming the logical threads it fills. Resolves once it has joined: the threads it claims are its own,
+     * and the observer systems it added as its join resolved, before awaiting anything else, are added, so a run
+     * started afterwards runs on it and reaches them; one it adds later reaches the runs after its add arrived.
+     * Rejects with an `Error` saying why it didn't join: the world refused its claim, as of a thread claimed twice, the
+     * world was disposed, the port is shared already, or that thread ended first, as the platform reports it: a
+     * `Worker` failing to start or throwing first, a node worker exiting, a port closed, or, once that thread asked to
+     * join, its end however it came. A browser worker ended before it asked to join isn't reported, so its share stays
+     * pending. Rejects too on a joined thread, and where memory can't be shared, as without cross-origin isolation.
      */
     share(port: {
         readonly postMessage: (message: never, transfer: never) => void;
@@ -48,7 +62,7 @@ export type World = {
         readonly addEventListener: (type: "message", listener: (event: unknown) => void) => void;
     } | {
         readonly on: (event: "message", listener: (value: unknown) => void) => unknown;
-    })): void;
+    })): Promise<void>;
     /**
      * Waits for pending runs, then stops ticking and releases memory, and joined threads' runs reject; the world is
      * unusable afterwards. On a joined thread, it disconnects this thread.

package/package.json

@@ -1,10 +1,17 @@
 {
   "name": "@adobe/ecs",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Adobe ECS",
+  "license": "MIT",
   "type": "module",
   "sideEffects": false,
   "private": false,
+  "pages": [
+    {
+      "from": "docs",
+      "to": "ecs"
+    }
+  ],
   "independentVersion": true,
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
@@ -21,21 +28,25 @@
     "!dist/guide",
     "!dist/perf",
     "!dist/perftest",
-    "!dist/samples",
     "!dist/observe",
     "!dist/**/*.tsbuildinfo",
     "src",
     "LICENSE"
   ],
   "devDependencies": {
-    "@types/estree": "^1.0.5",
+    "@oxc-parser/binding-wasm32-wasip1": "0.155.0",
+    "@oxc-transform/binding-wasm32-wasip1": "0.155.0",
+    "@types/estree": "^1.0.9",
     "@types/node": "^25.6.0",
     "@vitest/browser-playwright": "^5.0.5",
+    "@vitest/coverage-v8": "^5.0.5",
     "@webgpu/types": "^0.1.61",
     "playwright": "^1.64.1",
+    "typedoc": "^0.28.9",
     "typescript": "^5.8.3",
     "vite": "^8.3.4",
-    "vitest": "^5.0.5"
+    "vitest": "^5.0.5",
+    "wabt": "1.0.39"
   },
   "peerDependencies": {
     "vite": "^8.0.0"
@@ -60,10 +71,12 @@
     "dev": "tsc -b -w --preserveWatchOutput",
     "typecheck": "tsc -b",
     "test": "pnpm exec playwright install chromium && vitest --run",
+    "test:coverage": "pnpm exec playwright install chromium && vitest --run --coverage",
+    "test:coverage:without-guide": "pnpm exec playwright install chromium && ECS_WITHOUT_GUIDE=1 vitest --run --coverage",
     "test:perf": "pnpm exec playwright install chromium && vitest --run --config vitest.perf.config.ts",
     "perf": "node scripts/perf.mjs",
     "perf:browser": "node scripts/perf.mjs --browser",
     "perf:report": "node scripts/perf.mjs --report",
-    "sample": "vite --config vite.sample.config.ts"
+    "docs": "typedoc"
   }
 }

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.Value<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.Value<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