@adobe/ecs 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,21 @@
+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 = {
+    readonly [K in Exclude<Resource.Key, WorldWritten>]?: Resource.Value<K>;
+};
+/**
+ * Creates a world on this thread, synchronously, with resources starting at the given values in place of their
+ * 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. 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 = (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/create.js

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

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

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

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.d.ts

@@ -0,0 +1,8 @@
+export type Comparison<T> = {
+    readonly "=="?: T;
+    readonly "!="?: T;
+    readonly "<"?: T;
+    readonly ">"?: T;
+    readonly "<="?: T;
+    readonly ">="?: T;
+};

package/dist/interface/world/filter.js

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

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

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

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

@@ -0,0 +1 @@
+export {};

package/dist/interface/world/index.js

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

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

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

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

@@ -0,0 +1,17 @@
+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. 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">[];
+}) => Promise<World>;

package/dist/interface/world/join.js

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

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

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

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

@@ -0,0 +1,73 @@
+import type { Input } from '../system/input.js';
+import type { System } from '../system/system.js';
+/**
+ * A world. Systems read and change it; observer systems read it after each run's and tick's sync point. Every member's
+ * type is named from the package root, so declarations a consumer emits for its results name no internal module.
+ */
+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, 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, 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. 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;
+    /**
+     * Takes a value passed to `add`. Once it returns, that system's body is never called again, and its memory is
+     * released. A system added both alone and within an added composite stays until both are removed; constraints
+     * naming a removed system are ignored. Removing a value that isn't added does nothing. Throws, removing nothing,
+     * when the systems left would conflict with no ordering path between them, as `add` does. On a joined thread it
+     * takes only observer systems.
+     */
+    remove(system: System<void>): void;
+    /**
+     * 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. 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;
+    } & ({
+        readonly addEventListener: (type: "message", listener: (event: unknown) => void) => void;
+    } | {
+        readonly on: (event: "message", listener: (value: unknown) => void) => unknown;
+    })): 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.
+     */
+    dispose(): Promise<void>;
+    [Symbol.asyncDispose](): Promise<void>;
+};
+export type * as World from './index.js';

package/dist/interface/world/world.js

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

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

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

package/package.json

@@ -1,6 +1,82 @@
 {
   "name": "@adobe/ecs",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "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/",
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.test.*",
+    "!dist/**/*.type-test.*",
+    "!dist/**/*.test-helper.*",
+    "!dist/**/*.cases.*",
+    "!dist/**/*.fixture.*",
+    "!dist/fixtures",
+    "!dist/guide",
+    "!dist/perf",
+    "!dist/perftest",
+    "!dist/observe",
+    "!dist/**/*.tsbuildinfo",
+    "src",
+    "LICENSE"
+  ],
+  "devDependencies": {
+    "@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",
+    "wabt": "1.0.39"
+  },
+  "peerDependencies": {
+    "vite": "^8.0.0"
+  },
+  "peerDependenciesMeta": {
+    "vite": {
+      "optional": true
+    }
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./compiler": {
+      "import": "./dist/implementation/compiler/index.js",
+      "types": "./dist/implementation/compiler/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "cp ../../LICENSE . && tsc -b",
+    "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",
+    "docs": "typedoc"
+  }
 }

package/src/exports.test.ts

@@ -0,0 +1,276 @@
+// © 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";
+import { fileURLToPath } from "node:url";
+import ts from "typescript";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+
+const packageRoot = join(dirname(fileURLToPath(import.meta.url)), "..");
+const temporary = mkdtempSync(join(tmpdir(), "ecs-exports-"));
+afterAll(() => rmSync(temporary, { recursive: true, force: true }));
+
+const messages = (diagnostics: readonly ts.Diagnostic[]): string[] =>
+    diagnostics.map(diagnostic => ts.flattenDiagnosticMessageText(diagnostic.messageText, "\n"));
+
+const installed = join(temporary, "node_modules", "@adobe", "ecs");
+
+/** Emits the package's declarations into node_modules, as a consumer installs it. */
+const install = (): void => {
+    mkdirSync(installed, { recursive: true });
+    writeFileSync(join(installed, "package.json"), readFileSync(join(packageRoot, "package.json")));
+    const config = ts.getParsedCommandLineOfConfigFile(join(packageRoot, "tsconfig.json"), { outDir: join(installed, "dist"), emitDeclarationOnly: true, composite: false, incremental: false, sourceMap: false }, { ...ts.sys, onUnRecoverableConfigFileDiagnostic: () => {} });
+    if (config === undefined) throw new Error("No tsconfig.json.");
+    const program = ts.createProgram([join(packageRoot, "src", "index.ts")], config.options);
+    // Its own sources check without the test runner's Node types, as a consumer's build sees them.
+    expect(messages([...ts.getPreEmitDiagnostics(program), ...program.emit().diagnostics])).toEqual([]);
+    mkdirSync(join(temporary, "node_modules", "@webgpu"), { recursive: true });
+    cpSync(join(packageRoot, "node_modules", "@webgpu", "types"), join(temporary, "node_modules", "@webgpu", "types"), { recursive: true, dereference: true });
+};
+
+const consumer = `
+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 } }
+}
+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: { 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: 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);
+`;
+
+/** Every declaration file reachable from `file` by relative imports, relative to `directory`. */
+const reachable = (directory: string, file: string): string[] => {
+    const seen = new Set<string>();
+    const pending = [join(directory, file)];
+    for (let next = pending.pop(); next !== undefined; next = pending.pop()) {
+        if (seen.has(next)) continue;
+        seen.add(next);
+        for (const [, specifier] of readFileSync(next, "utf8").matchAll(/(?:from|import)\s*\(?\s*["'](\.[^"']+)["']/g)) {
+            pending.push(join(dirname(next), specifier.replace(/\.js$/, ".d.ts")));
+        }
+    }
+    return [...seen].map(path => relative(directory, path)).sort();
+};
+
+/** Modules only the implementation reads: the registry's read side and the forms of systems it holds. */
+const internal = (path: string): boolean =>
+    path.startsWith("interface/registry/")
+    || path === "interface/system/composite.d.ts" || path === "interface/system/leaf.d.ts" || path === "interface/system/definition.d.ts"
+    || 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[]; readonly lines: number[] } => {
+    writeFileSync(join(temporary, "index.ts"), source);
+    const program = ts.createProgram([join(temporary, "index.ts")], {
+        target: ts.ScriptTarget.ESNext,
+        module: ts.ModuleKind.NodeNext,
+        moduleResolution: ts.ModuleResolutionKind.NodeNext,
+        lib: ["lib.esnext.d.ts", "lib.dom.d.ts"],
+        types: ["@webgpu/types"],
+        strict: true,
+        declaration: true,
+        emitDeclarationOnly: true,
+        outDir: join(temporary, "out"),
+    });
+    const result = program.emit();
+    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 };
+};
+
+/** 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 { System } from "@adobe/ecs";
+export const health = Symbol("exportsTest/health");
+declare module "@adobe/ecs" {
+    interface Components { [health]: { type: number } }
+}
+// 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();
+        writeFileSync(join(temporary, "package.json"), JSON.stringify({ name: "consumer", type: "module", private: true }));
+    }, 60_000);
+    it("let a consumer emit declarations for the values it makes from the public API", () => {
+        expect(compile(consumer).messages).toEqual([]);
+        expect(reachable(join(installed, "dist"), "index.d.ts").filter(internal)).toEqual([]);
+        // 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 key: readonly [typeof position];
+    readonly components: {
+        readonly with: readonly [typeof element];
+    };
+}>;`);
+        expect(emitted).toContain(`export declare const ranked: Index<{
+    readonly key: readonly [typeof position];
+    readonly sorted: true;
+}>;`);
+        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 'symbol[]' is not assignable to type 'undefined'"))).toBe(true);
+    }, 60_000);
+});
+
+describe("the package's dependencies", () => {
+    it("are none at run time: consumers install nothing with it", () => {
+        const manifest: unknown = JSON.parse(readFileSync(join(packageRoot, "package.json"), "utf8"));
+        const listed = typeof manifest === "object" && manifest !== null ? ["dependencies", "optionalDependencies", "bundledDependencies"].filter(field => field in manifest) : [];
+        expect(listed).toEqual([]);
+    });
+});

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