@adobe/ecs 0.0.0-stage → 0.2.0

package/src/guide/README.md

@@ -0,0 +1,42 @@
+# Guide
+
+How to use the ECS, in chapters. Each chapter is its prose, `NN-name.md`, and a program, `NN-name.ts`, whose output is
+`NN-name.out`. The [interactive guide](../../../ecs-guide) shows each chapter's prose beside its program, which you edit
+and run in the browser.
+
+- [Setup](00-setup.md)
+- [Keys and declarations](00-keys.md)
+
+## Basics
+
+1. [Resources](01-resources.md)
+2. [Entities, components and archetypes](02-entities.md)
+3. [Systems](03-systems.md)
+4. [Ticks and cadence](04-ticks.md)
+
+## Intermediate
+
+5. [Scheduling and composites](05-scheduling.md)
+6. [Sync points](06-sync-points.md)
+7. [Change filters and conditions](07-change-filters.md)
+8. [Input](08-input.md)
+9. [Rules](09-rules.md)
+10. [Finalizers and change sets](10-finalizers.md)
+11. [Traits, within and references](11-traits.md)
+
+## Advanced
+
+12. [Lookups](12-lookups.md)
+13. [Indexes](13-indexes.md)
+14. [Kernels](14-kernels.md)
+15. [Reductions](15-reductions.md)
+16. [GPU kernels and render systems](16-gpu.md)
+17. [Hierarchies](17-hierarchies.md)
+18. [Identity and ids](18-identity.md)
+19. [Threads](19-threads.md)
+20. [Shared components and where](20-shared.md)
+
+## UI
+
+21. [Animating elements](21-dom.md)
+22. [Drawing on a canvas](22-canvas.md)

package/src/guide/guide.test.ts

@@ -0,0 +1,215 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { formatWithOptions } from "node:util";
+import ts from "typescript";
+import { afterAll, expect, it, vi } from "vitest";
+
+/**
+ * Each chapter here is its prose, `NN-name.md`, and a program, which its `main` runs. Run, it prints what the `.out`
+ * file beside it says: a line per console call, as node writes its values, on one line each. Ids name the package's
+ * version, which is left out of the comparison, so a new version changes no example. The folder is read as the test
+ * runs, not through `import.meta.glob`, which vitest's cache of transformed modules would keep as of the test's first
+ * run, missing a chapter added since.
+ */
+const folder = new URL(".", import.meta.url);
+const files = readdirSync(folder);
+const read = (file: string): string => readFileSync(new URL(file, folder), "utf8");
+const names = files.filter(file => /^\d+-[\w-]+\.ts$/.test(file) && !file.endsWith(".type-test.ts")).map(file => file.slice(0, -".ts".length)).sort();
+const proseFiles = files.filter(file => /^\d+-[\w-]+\.md$/.test(file)).sort();
+/** Where the mutation tests write each program changed: `.mutants` in the package. */
+const mutants = new URL("../../.mutants/", import.meta.url);
+afterAll(() => rmSync(mutants, { recursive: true, force: true }));
+
+const levels = ["log", "info", "warn", "error", "debug"] as const;
+const unversioned = (text: string): string => text.replace(/@adobe\/ecs@[^/\s]+\//g, "@adobe/ecs/");
+const chapterOf = (file: string): number => Number(/^(\d+)-/.exec(file)?.[1]);
+
+/** What `main` prints, a line per console call, and how it failed, if it did. */
+const printed = async (main: () => Promise<void>): Promise<string> => {
+    const lines: string[] = [];
+    const spies = levels.map(level => vi.spyOn(console, level).mockImplementation((...values: unknown[]) => {
+        lines.push(formatWithOptions({ breakLength: Infinity, compact: true }, ...values));
+    }));
+    try {
+        await main();
+    } catch (error) {
+        lines.push(`main failed: ${String(error)}`);
+    } finally {
+        for (const spy of spies) spy.mockRestore();
+    }
+    return lines.map(line => `${line}\n`).join("");
+};
+
+/** What a program prints, run from its file, or how it failed, as a declaration the world rejects fails its import. */
+const run = (file: URL): Promise<string> => printed(async () => {
+    const program: unknown = await import(/* @vite-ignore */ file.href);
+    const main: unknown = Reflect.get(Object(program), "main");
+    if (typeof main !== "function") throw new Error(`${file.pathname} exports no main`);
+    await Reflect.apply(main, undefined, []);
+});
+
+/** Code without its comments, as TypeScript prints it. */
+const withoutComments = (source: string): string =>
+    ts.createPrinter({ removeComments: true }).printFile(ts.createSourceFile("program.ts", source, ts.ScriptTarget.ESNext, false));
+
+/** Each chapter's code: its files', without comments. */
+const codeOf = (chapter: number): string =>
+    files.filter(file => file.endsWith(".ts") && !file.endsWith(".test.ts") && chapterOf(file) === chapter).map(file => withoutComments(read(file))).join("\n");
+
+/** What prose shows as code: its inline code and its blocks. */
+const shownIn = (prose: string): readonly string[] => [...prose.matchAll(/```\w*\n([\s\S]*?)```|`([^`\n]+)`/g)].map(([, block, inline]) => block ?? inline ?? "");
+
+/** Each link of the prose to lines of a program, which the interactive guide shows in its editor: `NN-name.ts#L4-L9`. */
+const editorLinks = proseFiles.flatMap(prose => [...read(prose).matchAll(/\]\(([^)#\s]*)#L(\d+)(?:-L(\d+))?\)/g)].map(([, file = "", from = "", to]) =>
+    ({ prose, file, from: Number(from), to: Number(to ?? from) })));
+
+/** The chapters the guide's index lists, in order: each its number, title and prose. */
+const listed = [...read("README.md").matchAll(/^(?:- |(\d+)\. )\[([^\]]+)\]\(([^)]+)\)$/gm)].map(([, number = "0", title = "", file = ""]) => ({ number: Number(number), title, file }));
+
+/** What each chapter teaches, which its prose names as code and its program does; 0 is the unnumbered keys chapter's. */
+const teaches: { readonly [chapter: number]: readonly string[] } = {
+    0: ["Symbol()", "declare module \"@adobe/ecs\"", "Components", "Resources", "row[score]", "resources[bonus]", "default"],
+    1: ["Resources", "default", "World.create", "observer: true", "run", "ReadonlyMap", "Entity"],
+    2: ["Components", "type: true", "as const", "commands.spawn", "commands.remove", "with: [...Particle]"],
+    3: ["System.create", "with", "not", "observer: true", "optional: [velocity]"],
+    4: ["clock", "delta", "cadence", "always", "resources: { changed: [elapsed] }", "wake", "reduce[wake]", "world.add", "world.remove"],
+    5: ["after", "during", "System.create([heal, hit])", "during: [update]"],
+    6: ["commands.spawn", "commands.add", "commands.despawn", "after: [spawn]"],
+    7: ["resources: { changed: [level] }", "changed: [score]", "resources: { is: [map], not: [paused] }", "resources[map]"],
+    8: ["world.run(hit, { amount: 3 })", "target: \"entity\""],
+    9: ["Rule.create", "derived: true"],
+    10: ["world.dispose()", "Finalizer.changes", "changes.previous", "changes.next"],
+    11: ["reference: \"owner\"", "reference: \"weak\"", "within: typeof selected", "interface Traits<N>", "Component.With<typeof instanced>"],
+    12: ["lookup: { enemy: { with", "lookup.enemy(", "changed: [health]", "changed"],
+    13: ["Index.create", "key", "lookup: { at: { index: grid } }", "sorted: true", "{ \">=\": 90 }", "order: byScore", "unique: true", "key: []", "length", "at(i)", "changed: true"],
+    14: ["kernel: true", "kernel: false", "F32"],
+    15: ["reduce: \"+\"", "\"max\"", "reduce[total]("],
+    16: ["kernel: \"gpu\"", "System.render", "accessors", "tables", "table.bind(pass)", "table.count", "Gpu.wgsl(draw)"],
+    17: ["reference: \"owner\"", "up: { through: parent }", "up", "null"],
+    18: ["explode"],
+    19: ["interface Threads", "thread: \"audio\"", "world.share(", "World.join(", "{ threads: [\"audio\"] }", "audio.run"],
+    20: ["shared: true", "commands.spawn(Unit, {", "row[cell]", "commands.add", "where: { [cell]: [4, 0] }", "where", "changed: [position]"],
+    21: ["thread: \"main\"", "cadence", "always", "commands.add", "is: [stage]", "style.translate", "changed: [position]"],
+    22: ["changed: [clock]", "is: [pen]", "key: []", "clearRect(", "arc(", "fill()", "getImageData("],
+};
+
+/**
+ * Changes to each chapter's program, each taking away a point it teaches, which its output catches: each its code as
+ * written, once in the program, what takes its place, and the failure it then prints, where it's one.
+ */
+const mutations: { readonly [chapter: number]: readonly (readonly [string, string, string?])[] } = {
+    0: [
+        ["default: 5 ", ""],
+        ["export const score = Symbol();", "export const score = Symbol.for(\"score\");", "a component's key score is a top-level `Symbol()` constant of this module"],
+        ["export const score = Symbol();", "export const score = [Symbol()][0];", "a component's key score is a top-level `Symbol()` constant of this module"],
+        ["        [score]: { type: number };\n", "", "System \"award\" uses component \"score\", which isn't a registered component: declare it beside its key, in interface Components or Resources."],
+    ],
+    1: [["World.create({ [gravity]: -1.6 })", "World.create()"], ["default: -9.8 ", ""], ["{ default: -Infinity }", "{}"]],
+    2: [["commands.remove(row.entity, enemy);", ""], ["{ [position]: [0, 10, 0] }", "{}"]],
+    3: [["not: [frozen]", "not: []"], ["System.create([count, fail])", "System.create([fail])"]],
+    4: [["world.remove(advance);", ""]],
+    5: [["after: [hit] ", ""], ["during: [update] ", ""]],
+    6: [["commands.add(hero, health, 5);", ""], ["commands.despawn(commands.spawn([health])({ [health]: 1 }));", "commands.spawn([health])({ [health]: 1 });"], ["watched.add(watch);", ""]],
+    7: [["resources: { changed: [level] } ", ""], [", changed: [score]", ""], [", not: [paused]", ""], ["is: [map], ", ""]],
+    8: [["target: \"entity\",", ""]],
+    9: [["with: [mesh], not: [hidden]", "with: [mesh]"], ["Rule.create({ components: { with: [sprite], not: [hidden] }, derive: [drawn] });", ""], ["Rule.create({ components: { with: [drawn] }, derive: [layer] });", ""]],
+    10: [["open.delete(row[handle]);", ""], ["await world.dispose();", ""], ["changes.previous(entity, handle)", "null"]],
+    11: [["; reference: \"owner\"", ""], ["; reference: \"weak\"", ""], ["; within: typeof selected", ""]],
+    12: [["with: [health], not: [frozen]", "with: [health]"], ["with: [health], changed: [health]", "with: [health]"]],
+    13: [["sorted: true, ", ""], ["unique: true, ", ""], [", changed: true", ""], ["key: [cell]", "key: [crowded]"]],
+    15: [["reduce[count](1);", ""], ["reduce: \"max\"", "reduce: \"+\""]],
+    16: [[", dotSize: size", ""]],
+    17: [[", up: { through: parent }", ""]],
+    19: [["audio.add(listen);", ""], ["await audio.run(mix);", ""]],
+    20: [
+        [", [velocity]: [4, 0]", ""], ["with: [position], where: { [cell]: [4, 0] }", "with: [position]"],
+        ["with: [position], where: { [cell]: (at, { resources }) => resources[camera]?.sees(at) === true } }", "with: [position] }"],
+        ["changed: [position], ", ""], ["await world.run(cross);", ""], ["await world.run(look, { x: 2, y: 2 });", ""],
+    ],
+    21: [["row[dot].remove();", ""], ["commands.add(row.entity, dot, element);", ""]],
+    22: [["context.fill();", ""]],
+};
+
+it("has prose and an expected output beside each program, and none without one, and Setup's prose", () => {
+    expect(files.filter(file => file.endsWith(".out")).map(file => file.slice(0, -".out".length)).sort()).toEqual(names);
+    expect(proseFiles).toEqual(["00-setup.md", ...names.map(name => `${name}.md`)].sort());
+});
+
+it("lists every chapter in its index, the unnumbered first, numbered as its files are and by the title its prose gives", () => {
+    expect(listed.map(chapter => chapter.file).sort()).toEqual(proseFiles);
+    expect(listed.map(chapter => chapter.number)).toEqual(listed.map(chapter => chapter.number).sort((a, b) => a - b));
+    for (const { number, title, file } of listed) {
+        expect(number).toBe(chapterOf(file));
+        const [heading, ...rest] = read(file).split("\n");
+        expect(heading).toBe(`# ${title}`);
+        expect(rest.join("\n").trim()).not.toBe("");
+    }
+});
+
+it.each(names)("%s prints what its .out says", async name => {
+    const expected = read(`${name}.out`);
+    expect(expected.trim()).not.toBe("");
+    expect(unversioned(await run(new URL(`${name}.ts`, folder)))).toBe(unversioned(expected));
+});
+
+it.each(Object.entries(teaches))("chapter %s's prose names what it teaches, as code, and its program does it", (chapter, taught) => {
+    const prose = `${names.find(name => chapterOf(name) === Number(chapter)) ?? ""}.md`;
+    const shown = shownIn(read(prose)).join("\n");
+    const code = codeOf(Number(chapter));
+    expect(taught.filter(name => !shown.includes(name))).toEqual([]);
+    expect(taught.filter(name => !code.includes(name))).toEqual([]);
+});
+
+it("teaches something in every chapter", () => {
+    expect(Object.keys(teaches).map(Number)).toEqual(names.map(chapterOf));
+});
+
+it("keeps code in the prose to a line or two, the program in the editor showing the rest", () => {
+    const long = proseFiles.flatMap(file => [...read(file).matchAll(/```\w*\n([\s\S]*?)```/g)].filter(([, block = ""]) => block.split("\n").length > 3).map(() => file));
+    expect(long).toEqual([]);
+});
+
+it("links chapters only to chapters there are", () => {
+    const chapterLinks = proseFiles.flatMap(file => [...read(file).matchAll(/\]\(([^)#\s]+\.md)\)/g)].map(([, target = ""]) => target));
+    expect(chapterLinks.length).toBeGreaterThan(0);
+    expect(chapterLinks.filter(target => !proseFiles.includes(target))).toEqual([]);
+});
+
+/** The messages of TypeScript's syntax errors in code. */
+const syntaxErrors = (code: string): readonly string[] => {
+    const { diagnostics = [] } = ts.transpileModule(code, { reportDiagnostics: true, compilerOptions: { target: ts.ScriptTarget.ESNext, module: ts.ModuleKind.ESNext } });
+    return diagnostics.map(diagnostic => ts.flattenDiagnosticMessageText(diagnostic.messageText, "\n"));
+};
+
+it.each(editorLinks.map(link => [`${link.prose} to ${link.file}#L${link.from}-L${link.to}`, link] as const))("links %s, lines of its own program that are whole code", (_place, { prose, file, from, to }) => {
+    expect(file.startsWith(prose.replace(/\.md$/, "."))).toBe(true);
+    const lines = read(file).split("\n");
+    expect(from).toBeGreaterThanOrEqual(1);
+    expect(to).toBeGreaterThanOrEqual(from);
+    expect(to).toBeLessThanOrEqual(lines.length);
+    const code = lines.slice(from - 1, to).join("\n");
+    expect(withoutComments(code).trim()).not.toBe("");
+    expect(lines[from - 1]?.trim()).not.toBe("");
+    expect(lines[to - 1]?.trim()).not.toBe("");
+    // Lines cut short leave a brace or a call open, which parses neither as statements nor as a declaration's members.
+    expect(syntaxErrors(code).length === 0 || syntaxErrors(`interface Members {\n${code}\n}`).length === 0 ? [] : syntaxErrors(code)).toEqual([]);
+});
+
+it.each(Object.entries(mutations).flatMap(([chapter, changes]) => changes.map(([from, to, failure], index) => [Number(chapter), from, to, failure, index] as const)))(
+    "catches chapter %s's point taken away, %j, in its output", async (chapter, from, to, failure, index) => {
+        const name = names.find(item => chapterOf(item) === chapter) ?? "";
+        const source = read(`${name}.ts`);
+        expect(source.split(from).length).toBe(2);
+        // A file of the package's own, compiled as the program is, outside its sources, which other tests read.
+        const mutant = `${name}-${index}.ts`;
+        mkdirSync(mutants, { recursive: true });
+        const file = new URL(mutant, mutants);
+        writeFileSync(file, source.replace(from, to).replace(` from "../index.js";`, ` from "../src/index.js";`));
+        try {
+            const output = (await run(file)).replaceAll(`.mutants/${mutant}`, `src/guide/${name}.ts`);
+            expect(unversioned(output)).not.toBe(unversioned(read(`${name}.out`)));
+            if (failure !== undefined) expect(output).toContain(failure);
+        } finally {
+            rmSync(file, { force: true });
+        }
+    });

package/src/implementation/compiler/access.ts

@@ -0,0 +1,149 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import type { Node } from 'estree';
+import { entityRead } from './columns.js';
+import { fail } from './failure.js';
+import type { Key } from './key.js';
+import { local, number, type Expression } from './ir.js';
+import { mathConstants, mathFunctions } from './math.js';
+import { scalar } from './scalar.js';
+import type { Scope } from './scope.js';
+import { resolveExport } from './link.js';
+import { resolvedValue } from './module-value.js';
+import type { Out } from './out.js';
+import { describeValue, scalarValue, type Value } from './value.js';
+
+const commandNames: ReadonlySet<string> = new Set(["spawn", "despawn", "add", "remove"]);
+
+const literal = (key: Key): number | string | undefined => key.kind === "static" ? key.name : undefined;
+
+/** Indexes a plain JS value. A static index into a resource or the input extends its path. */
+const element = (node: Node, scope: Scope, object: Expression, key: Key, optional: boolean): Expression => {
+    if (key.kind === "static" && !optional && (object.kind === "resource" || object.kind === "args" || object.kind === "shared")) {
+        return { ...object, path: [...object.path, key.name] };
+    }
+    const index: Expression = key.kind === "static"
+        ? typeof key.name === "number" ? number(key.name) : { kind: "string", value: key.name }
+        : key.kind === "value" ? scalar(key.value, node, scope)
+        : fail(node, `${key.name} is not an index here`);
+    return { kind: "element", object, index, optional };
+};
+
+const mathConstant = (name: string): Expression => {
+    const value: unknown = Reflect.get(Math, name);
+    return number(typeof value === "number" ? value : NaN);
+};
+
+/** `value[key]`, resolved at compile time where the kernel subset allows. */
+export const access = (value: Value, key: Key, node: Node, scope: Scope, optional: boolean): Value => {
+    const signature = scope.unit.signature;
+    const name = literal(key);
+    switch (value.kind) {
+        case "row":
+            if (key.kind === "binding") {
+                if (!signature.read.has(key.name) && !signature.write.has(key.name)) fail(node, `${key.name} is not in components read or write`);
+                // A shared component is the call's archetype's value, which each call takes as a parameter.
+                const shared = signature.shared.indexOf(key.name);
+                if (shared >= 0) {
+                    scope.unit.used.read.add(key.name);
+                    return { kind: "dynamic", expression: { kind: "shared", index: shared, path: [] } };
+                }
+                return { kind: "component", component: key.name, path: [] };
+            }
+            if (name === "entity") return scalarValue(entityRead(scope.unit));
+            return fail(node, "row is indexed by a component in components read or write, or .entity");
+        case "context":
+            if (name === "resources") return { kind: "resources" };
+            if (name === "lookup") return { kind: "lookups" };
+            if (name === "reduce") return { kind: "reducers" };
+            if (name === "commands") return { kind: "commands" };
+            if (name === "up" && scope.unit.up !== null) return { kind: "found", lookup: signature.lookups.length, expression: local(scope.unit.up) };
+            return fail(node, "the context holds the declared resources, lookup, reduce and up, and commands");
+        case "resources": {
+            const index = key.kind === "binding" ? signature.resources.indexOf(key.name) : -1;
+            if (key.kind !== "binding" || index < 0) return fail(node, `${key.kind === "binding" ? key.name : "resources"} is not in resources read`);
+            scope.unit.used.resources.add(key.name);
+            return { kind: "dynamic", expression: { kind: "resource", index, path: [] } };
+        }
+        case "reducers": {
+            const reduced = key.kind === "binding" ? signature.reduced.findIndex(entry => entry.resource === key.name) : -1;
+            return reduced >= 0 ? { kind: "reducer", reduced } : fail(node, "reduce is indexed by a resource in the declaration's resources.reduce");
+        }
+        case "lookups": {
+            const lookup = signature.lookups.findIndex(entry => entry.name === name);
+            return lookup >= 0 ? { kind: "lookup", lookup } : fail(node, "lookup holds the declaration's lookups, by name");
+        }
+        case "found": {
+            // The lookup after the declaration's is `up`'s.
+            const up = value.lookup === signature.lookups.length ? signature.up : null;
+            const lookup = up ?? signature.lookups[value.lookup];
+            // A lookup by entity with `changed` gives it after what it reads.
+            if (up === null && lookup !== undefined && "watches" in lookup && lookup.watches && name === "changed") {
+                return { kind: "dynamic", expression: { kind: "element", object: value.expression, index: number(lookup.read.length), optional } };
+            }
+            const index = key.kind === "binding" ? (lookup?.read ?? []).indexOf(key.name) : -1;
+            if (lookup === undefined || key.kind !== "binding" || index < 0) return fail(node, up === null ? "a lookup result is indexed by a component in that lookup's read, or by changed with changed declared" : "up is indexed by a component in up.read");
+            if (up !== null) {
+                // Read straight from the parent's columns, at the parent's row.
+                if (optional) return fail(node, "up is read only where it isn't null: test up === null first");
+                scope.unit.used.up.add(key.name);
+                return { kind: "component", component: key.name, path: [], up: true };
+            }
+            else {
+                const used = scope.unit.used.lookups;
+                const name = signature.lookups[value.lookup]?.name ?? "";
+                used.set(name, (used.get(name) ?? new Set()).add(key.name));
+            }
+            return { kind: "dynamic", expression: { kind: "element", object: value.expression, index: number(index), optional } };
+        }
+        case "indexed":
+            // A unique index's result is its first row.
+            if (name === "length") return scalarValue({ kind: "listLength", list: value.list, lookup: value.lookup });
+            if (name === "changed") return scalarValue({ kind: "listChanged", list: value.list, lookup: value.lookup });
+            if (name === "at") return { kind: "listAt", lookup: value.lookup, list: value.list };
+            return access({ kind: "indexRow", lookup: value.lookup, row: value.first }, key, node, scope, optional);
+        case "indexRow": {
+            if (name === "entity") return scalarValue({ kind: "rowEntity", row: value.row, lookup: value.lookup });
+            const lookup = signature.lookups[value.lookup];
+            const read = key.kind === "binding" ? (lookup?.read ?? []).indexOf(key.name) : -1;
+            if (lookup === undefined || key.kind !== "binding" || read < 0) return fail(node, "a lookup's row is indexed by a component in that lookup's read, or .entity");
+            const used = scope.unit.used.lookups;
+            used.set(lookup.name, (used.get(lookup.name) ?? new Set()).add(key.name));
+            return { kind: "rowRead", lookup: value.lookup, row: value.row, read, path: [] };
+        }
+        case "rowRead":
+            return name === undefined
+                ? fail(node, "component values are indexed by literal elements or field names")
+                : { ...value, path: [...value.path, name] };
+        case "dynamic":
+            return { kind: "dynamic", expression: element(node, scope, value.expression, key, optional) };
+        case "tuple":
+            return typeof name === "number" && value.items[name] !== undefined
+                ? value.items[name]
+                : fail(node, "tuple elements are indexed by an in-range literal");
+        case "struct": {
+            const field = value.fields.find(([fieldName]) => fieldName === name);
+            return field ? field[1] : fail(node, `no field ${String(name)}`);
+        }
+        case "component":
+        case "snapshot":
+            return name === undefined
+                ? fail(node, "component values are indexed by literal elements or field names")
+                : { ...value, path: [...value.path, name] };
+        case "math":
+            if (typeof name === "string" && mathConstants.has(name)) return scalarValue(mathConstant(name));
+            if (typeof name === "string" && mathFunctions.has(name)) return { kind: "method", owner: "math", name };
+            return fail(node, `Math.${String(name)} is not in the kernel subset`);
+        case "namespace": {
+            const link = scope.unit.link;
+            if (typeof name !== "string" || link === null) return fail(node, "namespaces are indexed by an export name");
+            const out: Out = [];
+            const member = resolvedValue(node, resolveExport(link, value.file, name), scope, out);
+            return out.length === 0 ? member : fail(node, `${name} must be a function or a literal constant`);
+        }
+        case "commands":
+            if (typeof name === "string" && commandNames.has(name)) return { kind: "method", owner: "commands", name };
+            return fail(node, "commands has spawn, despawn, add and remove");
+        default:
+            return fail(node, `${describeValue(value)} can't be indexed`);
+    }
+};

package/src/implementation/compiler/archetypes.test.ts

@@ -0,0 +1,64 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { describe, expect, test } from 'vitest';
+import { parseAst } from 'vite';
+import { archetypeFunction, archetypeInsertions } from './archetypes.js';
+import { archetypeIndexKey } from '../../interface/registry/archetypes.js';
+import { insertInto } from './source-map.js';
+import { moduleOf } from './type-schemas.js';
+
+/** The module as the pass leaves it without the function it appends, its failure's message, or null. */
+const passed = (code: string): string | null => {
+    const result = archetypeInsertions(moduleOf("/src/lists.ts", code, parseAst(code, { lang: "ts" }, "/src/lists.ts")));
+    if (result === null) return null;
+    if ("failure" in result) return `failure: ${result.failure.message}`;
+    return insertInto(code, result.insertions, "/src/lists.ts").code.replace(/\nfunction archetype\$\d*\(list\) \{.*\}\n$/, "");
+};
+
+const keys = `import { label, type Other } from "./keys.js";\nconst todo = Symbol();\nconst done = Symbol();\n`;
+
+describe("archetypeInsertions", () => {
+    test("gives a top-level list of keys declared as const an index, its own keys or imported", () => {
+        expect(passed(`${keys}export const Todo = [todo, label, done] as const;`)).toBe(`${keys}export const Todo = archetype$([todo, label, done] as const);`);
+    });
+    test("gives an index to lists spreading lists of keys, and to lists in what the module makes as it loads", () => {
+        expect(passed(`${keys}const Node = [todo, done] as const;\nconst Kinds = [[...Node, label] as const, { list: [label] as const }];`))
+            .toBe(`${keys}const Node = archetype$([todo, done] as const);\nconst Kinds = [archetype$([...Node, label] as const), { list: archetype$([label] as const) }];`);
+    });
+    test("leaves a list spreading what isn't a list of keys", () => {
+        expect(passed(`${keys}const named = [todo];\nconst Node = [...named, done] as const;`)).toBe(null);
+    });
+    test("leaves lists it can't tell are only keys, or that aren't declared as const", () => {
+        expect(passed(`${keys}const loose = [todo, done];\nconst mixed = [todo, 1] as const;\nconst named = [todo, other] as const;\nconst empty = [] as const;`)).toBe(null);
+    });
+    test("leaves a list in a function, which isn't made once", () => {
+        expect(passed(`${keys}const make = () => [todo, done] as const;`)).toBe(null);
+    });
+    test("fails for a list naming one of its module's keys twice, and leaves one naming an import twice", () => {
+        expect(passed(`${keys}const Todo = [todo, done, todo] as const;`)).toBe("failure: this list names todo twice; a list of components names each once");
+        expect(passed(`${keys}const Labels = [label, label] as const;`)).toBe(null);
+    });
+    test("leaves a module binding a global the appended function uses", () => {
+        expect(passed(`${keys}const Object = 1;\nconst Todo = [todo, done] as const;`)).toBe(null);
+    });
+    test("gives an index to a list of a namespace's keys", () => {
+        expect(passed(`import { Shapes } from "./shapes.js";\nconst Round = [Shapes.circle, Shapes.radius] as const;`))
+            .toBe(`import { Shapes } from "./shapes.js";\nconst Round = archetype$([Shapes.circle, Shapes.radius] as const);`);
+    });
+    test("appends a function indexing a list of symbols each listed once, whether or not their declarations registered yet", () => {
+        const made: unknown = new Function(`${archetypeFunction("index")}\nreturn index;`)();
+        const index = (list: readonly unknown[]): unknown => typeof made === "function" ? Reflect.apply(made, undefined, [list]) : null;
+        const [first, second] = [Symbol(), Symbol()];
+        const list = [first, second];
+        expect(index(list)).toBe(list);
+        expect(typeof Reflect.get(list, archetypeIndexKey)).toBe("number");
+        const twice = [first, first];
+        index(twice);
+        expect(Reflect.get(twice, archetypeIndexKey)).toBe(undefined);
+    });
+    test("appends a function giving each list its index once", () => {
+        const code = `${keys}const Todo = [todo, done] as const;`;
+        const result = archetypeInsertions(moduleOf("/src/lists.ts", code, parseAst(code, { lang: "ts" }, "/src/lists.ts")));
+        const whole = result !== null && "insertions" in result ? insertInto(code, result.insertions, "/src/lists.ts").code : "";
+        expect(whole.match(/function archetype\$\(list\)/g)?.length).toBe(1);
+    });
+});

package/src/implementation/compiler/archetypes.ts

@@ -0,0 +1,134 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { archetypeCountName, archetypeIndexName } from '../../interface/registry/archetypes.js';
+import type { PassResult } from './input-schemas.js';
+import type { Insertion } from './source-map.js';
+import type { Module, Node, Statement } from './type-schemas.js';
+
+/**
+ * The function the plugin appends, as `name`, to a module with lists of keys it can read: it gives a list a
+ * program-wide index, by which worlds find what they resolved for it without comparing components, when every member is
+ * a symbol, each once, and returns the list. It runs where the list is made, before any key's declaration may be
+ * registered, so whether they're components is checked where the list is used. Generated code imports nothing, so it
+ * shares the count through a global, as every copy of the package does (`registry/archetypes.ts`).
+ */
+export const archetypeFunction = (name: string): string => [
+    `function ${name}(list) {`,
+    ` const index = Symbol.for(${JSON.stringify(archetypeIndexName)}), count = Symbol.for(${JSON.stringify(archetypeCountName)});`,
+    ` if (Object.prototype.hasOwnProperty.call(list, index) || !Object.isExtensible(list)) return list;`,
+    ` for (let k = 0; k < list.length; k++) if (typeof list[k] !== "symbol" || list.indexOf(list[k]) < k) return list;`,
+    ` const next = globalThis[count] || 0; globalThis[count] = next + 1; Object.defineProperty(list, index, { value: next });`,
+    ` return list;`,
+    `}`,
+].join("");
+
+const uniqueName = (code: string, base: string): string => {
+    let name = base;
+    for (let n = 1; code.includes(name); n++) name = `${base}${n}`;
+    return name;
+};
+
+type Declarations = Extract<Statement, { readonly type: "VariableDeclaration" }>;
+type Expression = NonNullable<Declarations["declarations"][number]["init"]>;
+/** `[...] as const`. */
+type ConstList = Extract<Expression, { readonly type: "TSAsExpression" }> & { readonly expression: Extract<Expression, { readonly type: "ArrayExpression" }> };
+
+const isNode = (value: object): value is Node => typeof Reflect.get(value, "start") === "number" && typeof Reflect.get(value, "type") === "string";
+
+const isConstList = (node: Node): node is ConstList => {
+    if (node.type !== "TSAsExpression") return false;
+    const expression: unknown = Reflect.get(node, "expression");
+    const annotation: unknown = Reflect.get(node, "typeAnnotation");
+    const typeName: unknown = typeof annotation === "object" && annotation !== null ? Reflect.get(annotation, "typeName") : undefined;
+    return typeof expression === "object" && expression !== null && Reflect.get(expression, "type") === "ArrayExpression"
+        && typeof typeName === "object" && typeName !== null && Reflect.get(typeName, "type") === "Identifier" && Reflect.get(typeName, "name") === "const";
+};
+
+/** Nodes whose code runs when called, not when the module loads. */
+const functions: ReadonlySet<string> = new Set(["ArrowFunctionExpression", "FunctionExpression", "FunctionDeclaration", "ClassDeclaration", "ClassExpression"]);
+
+/** A top-level statement's variable declaration, exported or not. */
+const variablesOf = (statement: Statement): Declarations | null => {
+    const declared = statement.type === "ExportNamedDeclaration" ? statement.declaration : statement;
+    return declared?.type === "VariableDeclaration" ? declared : null;
+};
+
+/** Whether a module binds at top level a global the appended function uses. */
+const bindsGlobals = (module: Module): boolean => module.program.body.some(statement => {
+    const declared = statement.type === "ExportNamedDeclaration" ? statement.declaration : statement;
+    const names = declared?.type === "VariableDeclaration" ? declared.declarations.map(declarator => declarator.id.type === "Identifier" ? declarator.id.name : "")
+        : (declared?.type === "FunctionDeclaration" || declared?.type === "ClassDeclaration") ? [declared.id?.name ?? ""]
+        : statement.type === "ImportDeclaration" ? statement.specifiers.map(specifier => specifier.local.name)
+        : [];
+    return names.some(name => name === "Symbol" || name === "globalThis" || name === "Object");
+});
+
+/**
+ * Gives each top-level list of keys declared `as const`, `const List = [a, b] as const`, a program-wide index: its
+ * members are the module's `Symbol()` constants or value imports, and the appended function indexes it once they're
+ * all declared components. `as const` makes it a readonly tuple, which nothing changes, as an indexed list must not.
+ * A list naming one of the module's keys twice fails; one naming an import twice is left without an index.
+ */
+export const archetypeInsertions = (module: Module): PassResult | null => {
+    const { code, program } = module;
+    if (!code.includes("as const") || bindsGlobals(module)) return null;
+    const keys = new Set<string>();
+    const local = new Set<string>();
+    for (const [name, imported] of module.imports) if (imported.value && imported.imported !== null) keys.add(name);
+    for (const statement of program.body) {
+        const variables = variablesOf(statement);
+        if (variables?.kind !== "const") continue;
+        for (const { id, init } of variables.declarations) {
+            if (id.type === "Identifier" && init?.type === "CallExpression" && init.callee.type === "Identifier" && init.callee.name === "Symbol") {
+                keys.add(id.name);
+                local.add(id.name);
+            }
+        }
+    }
+    if (keys.size === 0 && module.imports.size === 0) return null;
+    /** The module's top-level constants holding lists it indexes, which other lists may spread. */
+    const lists = new Set<string>();
+    const insertions: Insertion[] = [];
+    const name = uniqueName(code, "archetype$");
+    /** Lists naming one of the module's keys twice, which fail the build. */
+    const repeated: { readonly name: string; readonly at: number }[] = [];
+    /** Whether a list declared `as const` names only keys: the module's or imported, or spreads lists of them. */
+    const indexes = (list: ConstList): boolean => {
+        const named: string[] = [];
+        for (const element of list.expression.elements) {
+            if (element?.type === "Identifier" && keys.has(element.name)) named.push(element.name);
+            // A namespace's member, `Shapes.circle`, is a key of the package or a module imported.
+            else if (element?.type === "MemberExpression" && !element.computed && element.object.type === "Identifier" && element.property.type === "Identifier"
+                && module.imports.get(element.object.name)?.value === true) named.push(`${element.object.name}.${element.property.name}`);
+            else if (element?.type !== "SpreadElement" || element.argument.type !== "Identifier" || !(lists.has(element.argument.name) || module.imports.get(element.argument.name)?.value === true)) return false;
+        }
+        const twice = named.find((member, k) => named.indexOf(member) < k);
+        if (twice === undefined) return true;
+        if (local.has(twice)) repeated.push({ name: twice, at: list.start });
+        return false;
+    };
+    // Lists made when the module loads: those in functions are made on every call, so they aren't indexed.
+    const visit = (node: unknown, binding: string | null): void => {
+        if (Array.isArray(node)) {
+            for (const item of node) visit(item, null);
+            return;
+        }
+        if (typeof node !== "object" || node === null || !isNode(node) || functions.has(node.type)) return;
+        if (isConstList(node) && node.expression.elements.length > 0 && indexes(node)) {
+            insertions.push({ at: node.start, text: `${name}(` }, { at: node.end, text: ")" });
+            if (binding !== null) lists.add(binding);
+            return;
+        }
+        for (const key of Object.keys(node)) if (key !== "parent") visit(Reflect.get(node, key), null);
+    };
+    for (const statement of program.body) {
+        const variables = variablesOf(statement);
+        // A list a top-level `const` holds may be spread by those after it.
+        if (variables?.kind === "const") for (const { id, init } of variables.declarations) visit(init, id.type === "Identifier" ? id.name : null);
+        else visit(statement, null);
+    }
+    const [twice] = repeated;
+    if (twice !== undefined) return { failure: { message: `this list names ${twice.name} twice; a list of components names each once`, position: twice.at, frames: [] }, dependencies: [] };
+    if (insertions.length === 0) return null;
+    insertions.push({ at: code.length, text: `\n${archetypeFunction(name)}\n` });
+    return { insertions, dependencies: [] };
+};