@adobe/ecs 0.1.0 → 0.2.0

package/src/implementation/compiler/inferred.ts

@@ -0,0 +1,197 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import type { ArrayExpression, Expression, Identifier, MemberExpression, ObjectExpression, Pattern, Property } from 'estree';
+import type { Used } from './body-access.js';
+
+/** An object literal's plain-named properties; none for anything else. */
+const fields = (node: Expression | Pattern | undefined): ReadonlyMap<string, Property> => new Map(node?.type !== "ObjectExpression" ? [] :
+    node.properties.flatMap((property): (readonly [string, Property])[] =>
+        property.type === "Property" && !property.computed && property.key.type === "Identifier" ? [[property.key.name, property]] : []));
+
+/**
+ * Whether the build saw every use the body makes of its row, resources and parent, and of its lookups through an
+ * index: a kernel compiles from them. A lookup by entity whose rows it didn't follow reads all of its `with`.
+ */
+export const followsAll = (used: Used, declaration: ObjectExpression): boolean => {
+    if (used.query === null || used.resources === null || used.up === null) return false;
+    const lookups = fields(valueOf(fields(declaration).get("lookup")));
+    if (used.lookups === null) return lookups.size === 0;
+    return [...used.lookups].every(([name, read]) => read !== null || !fields(valueOf(lookups.get(name))).has("index"));
+};
+
+/** `names` in the order `first` lists them, then the rest in the order the body first used them. */
+const ordered = (names: ReadonlySet<string>, first: readonly string[]): ReadonlySet<string> =>
+    new Set([...first.filter(name => names.has(name)), ...names]);
+
+/**
+ * What a body uses, its row's and each lookup's keys in the order their `with` lists them, so the lists the world
+ * takes follow the declaration as written.
+ */
+export const inOrder = (used: Used, declaration: ObjectExpression): Used => {
+    const declared = fields(declaration);
+    const components = fields(valueOf(declared.get("components")));
+    const members = [...namesIn(valueOf(components.get("with"))), ...namesIn(valueOf(components.get("optional")))];
+    const lookups = fields(valueOf(declared.get("lookup")));
+    return {
+        ...used,
+        query: used.query === null ? null : { read: ordered(used.query.read, members), write: ordered(used.query.write, members), mutate: ordered(used.query.mutate, members) },
+        lookups: used.lookups === null ? null : new Map([...used.lookups].map(([name, read]) =>
+            [name, read === null ? null : ordered(read, namesIn(valueOf(fields(valueOf(lookups.get(name))).get("with"))))])),
+    };
+};
+
+/**
+ * The first key a body uses of its row, or of a lookup's rows by entity, that its declaration doesn't require, and
+ * where it's required: types reject it too, but a body the build reads may have none. Null when every one is
+ * required, or a list isn't an array literal the build can read.
+ */
+export const unrequired = (used: Used, declaration: ObjectExpression): { readonly key: string; readonly list: string } | null => {
+    const declared = fields(declaration);
+    const components = fields(valueOf(declared.get("components")));
+    const literal = (names: readonly (Expression | undefined)[]): readonly string[] | null => {
+        const lists = names.filter(node => node !== undefined);
+        return lists.every(node => node.type === "ArrayExpression" && node.elements.every(element => element?.type === "Identifier" || element?.type === "MemberExpression"))
+            ? lists.flatMap(node => namesIn(node)) : null;
+    };
+    const members = literal(["with", "optional", "added", "changed"].map(name => valueOf(components.get(name))));
+    if (used.query !== null && members !== null) {
+        const key = [...used.query.read, ...used.query.write].find(name => !members.includes(name));
+        if (key !== undefined) return { key, list: "components with or optional" };
+    }
+    if (used.lookups !== null) {
+        for (const [name, lookup] of fields(valueOf(declared.get("lookup")))) {
+            const parts = fields(valueOf(lookup));
+            const read = used.lookups.get(name);
+            if (parts.has("index") || read === null || read === undefined) continue;
+            const required = literal([valueOf(parts.get("with")), valueOf(parts.get("optional")), valueOf(parts.get("changed"))]);
+            const key = required === null ? undefined : [...read].find(key => !required.includes(key));
+            if (key !== undefined) return { key, list: `lookup.${name}.with or optional` };
+        }
+    }
+    return null;
+};
+
+const list = (names: Iterable<string>): string => `[${[...names].join(", ")}]`;
+
+/**
+ * The source of what the build inferred a body uses, `Access` in `interface/system/resolve.ts`: its keys as the
+ * module-scope bindings the body indexes by, null for a group it couldn't follow, and `at` where the body is.
+ */
+export const accessText = (used: Used, at: string, where?: ReadonlySet<string> | null): string => {
+    const { query, resources, lookups, up } = used;
+    // Keys changed inside their values are listed only when there are some, for registration to judge by kind.
+    const mutate = (keys: ReadonlySet<string>): string => keys.size === 0 ? "" : `, mutate: ${list(keys)}`;
+    const components = query === null ? "null" : `{ read: ${list([...query.read].filter(key => !query.write.has(key)))}, write: ${list(query.write)}${mutate(query.mutate)} }`;
+    const resourceText = resources === null ? "null" : `{ read: ${list(resources.read)}, write: ${list(resources.write)}, reduce: ${list(resources.reduce)}${mutate(resources.mutate)} }`;
+    const lookupText = lookups === null ? "null" : `{ ${[...lookups].map(([name, read]) => `${JSON.stringify(name)}: ${read === null ? "null" : list(read)}`).join(", ")} }`;
+    // The resources `where`'s predicates read, only with predicates.
+    const whereText = where === undefined ? "" : `, where: ${where === null ? "null" : list(where)}`;
+    return `{ components: ${components}, resources: ${resourceText}, lookup: ${lookupText}, up: ${up === null ? "null" : list(up)}${whereText}, at: ${JSON.stringify(at)} }`;
+};
+
+/** A declaration's parts the build makes, located at `at`, so a failure in them points at the declaration. */
+const made = (at: { readonly start: number; readonly end: number }) => {
+    const identifier = (name: string): Identifier => ({ type: "Identifier", name, start: at.start, end: at.end });
+    /** A key as the body named it: a binding, or a namespace's member. */
+    const key = (name: string): Identifier | MemberExpression => {
+        const [object, member] = name.split(".");
+        return member === undefined || object === undefined ? identifier(name) : {
+            type: "MemberExpression", object: identifier(object), property: identifier(member), computed: false, optional: false, start: at.start, end: at.end,
+        };
+    };
+    const array = (names: Iterable<string>): ArrayExpression => ({ type: "ArrayExpression", elements: [...names].map(key), start: at.start, end: at.end });
+    const property = (name: string, value: Expression): Property => ({
+        type: "Property", key: identifier(name), value, kind: "init", computed: false, method: false, shorthand: false, start: at.start, end: at.end,
+    });
+    const object = (properties: readonly Property[]): ObjectExpression => ({ type: "ObjectExpression", properties: [...properties], start: at.start, end: at.end });
+    return { identifier, array, property, object };
+};
+
+/** `node`'s value when it's a property whose value is an expression. */
+const valueOf = (property: Property | undefined): Expression | undefined =>
+    property !== undefined && property.value.type !== "ObjectPattern" && property.value.type !== "ArrayPattern" && property.value.type !== "RestElement" && property.value.type !== "AssignmentPattern"
+        ? property.value : undefined;
+
+/** The names an array literal of keys lists: bindings, or namespaces' members (`Shapes.circle`). */
+const namesIn = (node: Expression | undefined): readonly string[] => node?.type !== "ArrayExpression" ? [] :
+    node.elements.flatMap(element => element?.type === "Identifier" ? [element.name]
+        : element?.type === "MemberExpression" && !element.computed && element.object.type === "Identifier" && element.property.type === "Identifier" ? [`${element.object.name}.${element.property.name}`]
+        : []);
+
+/**
+ * A kernel's declaration as the compiler reads it, from the declaration written and what the build inferred its body
+ * uses: `components` with `read` and `write` from the body beside its `with`, `resources` with `read` and `reduce`,
+ * each lookup with `read`, and `up` with `read`. `used` follows every use (`followsAll`).
+ */
+export const resolvedDeclaration = (declaration: ObjectExpression, used: Used): ObjectExpression => {
+    const { array, property, object } = made(declaration);
+    const keep = (from: ReadonlyMap<string, Property>, names: readonly string[]): Property[] =>
+        names.flatMap(name => from.get(name) ?? []);
+    const properties: Property[] = [];
+    let resourcesDeclared = false;
+    for (const original of declaration.properties) {
+        if (original.type !== "Property" || original.computed || original.key.type !== "Identifier") {
+            properties.push(...original.type === "Property" ? [original] : []);
+            continue;
+        }
+        const value = valueOf(original);
+        const parts = fields(value);
+        switch (original.key.name) {
+            case "components": {
+                if (value?.type !== "ObjectExpression" || used.query === null) break;
+                const { read, write, mutate } = used.query;
+                // A change inside a value is a write to the compiler, which rejects it for values written whole.
+                const written = new Set([...write, ...mutate]);
+                properties.push(property("components", object([
+                    property("read", array([...read].filter(key => !written.has(key)))),
+                    property("write", array(written)),
+                    ...keep(parts, ["with", "optional", "not", "added", "changed"]),
+                ])));
+                continue;
+            }
+            case "resources": {
+                if (value?.type !== "ObjectExpression" || used.resources === null) break;
+                resourcesDeclared = true;
+                properties.push(property("resources", resourcesOf(used.resources, keep(parts, ["is", "not", "changed"]), namesIn(valueOf(parts.get("is"))), array, property, object)));
+                continue;
+            }
+            case "lookup": {
+                if (value?.type !== "ObjectExpression" || used.lookups === null) break;
+                properties.push(property("lookup", object([...parts].map(([name, lookup]) => {
+                    const lookupParts = fields(valueOf(lookup));
+                    // A lookup the body never uses reads nothing; null, one whose rows it didn't follow.
+                    const found = used.lookups?.get(name);
+                    const reads = found === undefined ? [] : found;
+                    if (lookupParts.has("index")) {
+                        // Rows the build didn't follow read everything the index holds, as the world resolves it.
+                        const read = reads === null ? [] : [property("read", array(reads))];
+                        return property(name, object([...read, ...keep(lookupParts, ["index", "changed"])]));
+                    }
+                    const withList = valueOf(lookupParts.get("with"));
+                    // Rows the build didn't follow read everything the lookup requires.
+                    const read = reads === null ? withList ?? array([]) : array(reads);
+                    return property(name, object([property("read", read), ...keep(lookupParts, ["with", "optional", "not", "changed"])]));
+                }))));
+                continue;
+            }
+            case "up": {
+                if (value?.type !== "ObjectExpression" || used.up === null) break;
+                properties.push(property("up", object([...keep(parts, ["through"]), property("read", array(used.up))])));
+                continue;
+            }
+        }
+        properties.push(original);
+    }
+    if (!resourcesDeclared && used.resources !== null) properties.push(property("resources", resourcesOf(used.resources, [], [], array, property, object)));
+    return object(properties);
+};
+
+/** A kernel's `resources`: what its body reads, but conditions it reads already, and reduces into; a write is refused by the compiler. */
+const resourcesOf = (
+    resources: NonNullable<Used["resources"]>, declared: readonly Property[], is: readonly string[],
+    array: (names: Iterable<string>) => ArrayExpression, property: (name: string, value: Expression) => Property, object: (properties: readonly Property[]) => ObjectExpression,
+): ObjectExpression => object([
+    property("read", array([...resources.read].filter(key => !resources.write.has(key) && !is.includes(key)))),
+    ...resources.write.size === 0 ? [] : [property("write", array(resources.write))],
+    ...resources.reduce.size === 0 ? [] : [property("reduce", array(resources.reduce))],
+    ...declared,
+]);

package/src/implementation/compiler/inline-kernels.test.ts

@@ -0,0 +1,10 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+/// <reference types="node" />
+import { expect, test } from 'vitest';
+import { inlineKernels, inlinePlaceholder } from './inline-kernels.js';
+
+test("inlines each kernel's module as a data: url of its UTF-8 bytes, as node's Buffer encodes them", () => {
+    const kernels = ["export const create = () => 'ü😀';\n", "export const create = () => 2;\n"];
+    const code = `a(${JSON.stringify(inlinePlaceholder(0, "h0"))}, ${JSON.stringify(inlinePlaceholder(1, "h1"))});`;
+    expect(inlineKernels(code, kernels, ["h0", "h1"])).toBe(`a(${kernels.map(source => JSON.stringify(`data:text/javascript;base64,${Buffer.from(source).toString("base64")}`)).join(", ")});`);
+});

package/src/implementation/compiler/inline-kernels.ts

@@ -0,0 +1,21 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+/** Where a kernel's url goes in compiled code, until its module is compiled: the plugin's for node, the guide's. */
+export const inlinePlaceholder = (index: number, hash: string): string => `@ecs-kernel-inline/${index}/${hash}`;
+
+/** A module's source as base64, from its UTF-8 bytes. */
+const base64 = (source: string): string => {
+    let binary = "";
+    for (const byte of new TextEncoder().encode(source)) binary += String.fromCharCode(byte);
+    return btoa(binary);
+};
+
+/**
+ * Code with each kernel's placeholder replaced by its module as a `data:` url, which imports on any thread, wherever
+ * it's served from: in node, and in a browser's workers.
+ */
+export const inlineKernels = (code: string, kernels: readonly string[], hashes: readonly string[]): string =>
+    kernels.reduce((inlined, source, index) => inlined.replaceAll(
+        JSON.stringify(inlinePlaceholder(index, hashes[index] ?? "")),
+        JSON.stringify(`data:text/javascript;base64,${base64(source)}`),
+    ), code);

package/src/implementation/compiler/input-schemas.test.ts

@@ -0,0 +1,182 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { describe, expect, test } from 'vitest';
+import { inputInsertions, type InputHost } from './input-schemas.js';
+import { insertInto } from './source-map.js';
+import { hostOf } from './type-host.test-helper.js';
+import { moduleOf } from './type-schemas.js';
+
+/** The module as the pass leaves it, with the files whose types it read, or its failure; null when it inserts nothing. */
+const passInputSchemas = async (code: string, file: string, host: InputHost) => {
+    const result = await inputInsertions(moduleOf(file, code, host.parse(code, file)), host);
+    if (result === null || "failure" in result) return result;
+    return { ...insertInto(code, result.insertions, file), dependencies: result.dependencies };
+};
+
+const header = `import { System, type Entity, type Vec2, type F32, type I32 } from "@adobe/ecs";\n`;
+
+/** The schemas the pass gives each system of `body`, in order. */
+const schemasOf = async (body: string, files: { readonly [path: string]: string } = {}): Promise<unknown> => {
+    const code = header + body;
+    const result = await passInputSchemas(code, "/src/main.ts", hostOf(files));
+    if (result === null) return null;
+    if ("failure" in result) return { failure: result.failure.message };
+    return [...result.code.matchAll(/, (\{.*\})\);?$/gm)].map(match => JSON.parse(match[1] ?? "null"));
+};
+
+describe("passInputSchemas", () => {
+    test("gives a system the schema of its body's parameter after its context", async () => {
+        expect(await schemasOf(`System.create({}, (_context, input: { readonly count: number; label: string; on: boolean; none: null }) => {});`)).toEqual([
+            { type: "object", properties: { count: { type: "number" }, label: { type: "string" }, on: { type: "boolean" }, none: { type: "null" } } },
+        ]);
+    });
+    test("finds the input after the row when the declaration has components", async () => {
+        expect(await schemasOf(`System.create({ components: { with: [a] } }, (row, context, input: { dx: number }) => {});`)).toEqual([
+            { type: "object", properties: { dx: { type: "number" } } },
+        ]);
+        expect(await schemasOf(`System.create({ components: { with: [a] } }, (row, context) => {});`)).toBe(null);
+    });
+    test("takes a declaration not written in place's input from a third parameter, or a second with a type", async () => {
+        expect(await schemasOf([
+            `System.create(declaration, (row, context, input: { a: number }) => {});`,
+            `System.create(declaration, (context, input: { b: number }) => {});`,
+            `System.create(declaration, (row, context) => {});`,
+        ].join("\n"))).toEqual([{ type: "object", properties: { a: { type: "number" } } }, { type: "object", properties: { b: { type: "number" } } }]);
+    });
+    test("passes nothing for a body without input", async () => {
+        expect(await schemasOf(`System.create({ resources: {} }, ({ resources }) => {});\nSystem.create(context => {});`)).toBe(null);
+    });
+    test("reads optional fields, literals, unions, arrays, tuples, sets and maps", async () => {
+        expect(await schemasOf(`System.create({}, (_c, input: {
+            mode?: "add" | "remove";
+            level: 1 | -1;
+            tags: readonly string[];
+            ids: ReadonlyArray<Entity>;
+            pair: [number, number];
+            seen: ReadonlySet<string>;
+            names: ReadonlyMap<Entity, string>;
+            maybe: string | null;
+        }) => {});`)).toEqual([{
+            type: "object",
+            properties: {
+                mode: { anyOf: [{ const: "add" }, { const: "remove" }] },
+                level: { anyOf: [{ const: 1 }, { const: -1 }] },
+                tags: { type: "array", items: { type: "string" } },
+                ids: { type: "array", items: { type: "integer", format: "entity" } },
+                pair: { type: "array", items: { type: "number" }, minItems: 2, maxItems: 2 },
+                seen: { type: "set", items: { type: "string" } },
+                names: { type: "map", keys: { type: "integer", format: "entity" }, values: { type: "string" } },
+                maybe: { anyOf: [{ type: "string" }, { type: "null" }] },
+            },
+            required: ["level", "tags", "ids", "pair", "seen", "names", "maybe"],
+        }]);
+    });
+    test("gives the package's types their schemas", async () => {
+        expect(await schemasOf(`System.create({}, (_c, input: { entity: Entity; at: Vec2; cell: Vec2.I32; dt: F32; steps: I32 }) => {});`)).toEqual([{
+            type: "object",
+            properties: {
+                entity: { type: "integer", format: "entity" },
+                at: { type: "array", items: { type: "number", precision: 1 }, minItems: 2, maxItems: 2 },
+                cell: { type: "array", items: { type: "integer", minimum: -2147483648, maximum: 2147483647 }, minItems: 2, maxItems: 2 },
+                dt: { type: "number", precision: 1 },
+                steps: { type: "integer", minimum: -2147483648, maximum: 2147483647 },
+            },
+        }]);
+    });
+    test("follows a type named by Schema.Type to its schema, written as a literal type or `typeof` a constant", async () => {
+        const files = { "/src/units.ts": `import type { Schema } from "@adobe/ecs";\nexport type Level = Schema.Type<{ type: "integer"; minimum: 0; maximum: 9 }>;\nconst title = { type: "string", maxLength: 64 } as const;\nexport type Title = Schema.Type<typeof title>;` };
+        expect(await schemasOf([
+            `import type { Level, Title } from "./units.js";`,
+            `type Cell = readonly [Level, Level];`,
+            `System.create({}, (_c, input: { level: Level; title: Title; cell: Cell }) => {});`,
+        ].join("\n"), files)).toEqual([{
+            type: "object",
+            properties: {
+                level: { type: "integer", minimum: 0, maximum: 9 },
+                title: { type: "string", maxLength: 64 },
+                cell: { type: "array", items: { type: "integer", minimum: 0, maximum: 9 }, minItems: 2, maxItems: 2 },
+            },
+        }]);
+    });
+    test("reads the package's types through any namespace", async () => {
+        expect(await schemasOf(`import * as ecs from "@adobe/ecs";\nSystem.create({}, (_c, input: { at: ecs.Vec3; cell: ecs.Vec2.U32 }) => {});`)).toEqual([{
+            type: "object",
+            properties: {
+                at: { type: "array", items: { type: "number", precision: 1 }, minItems: 3, maxItems: 3 },
+                cell: { type: "array", items: { type: "integer", minimum: 0, maximum: 0xFFFFFFFF }, minItems: 2, maxItems: 2 },
+            },
+        }]);
+    });
+    test("takes any value for a class a module exports", async () => {
+        const files = { "/src/row.ts": `export class Row extends HTMLElement {}` };
+        expect(await schemasOf(`import { Row } from "./row.js";\nSystem.create({}, (_c, input: { row: Row }) => {});`, files)).toEqual([{ type: "object", properties: { row: { allOf: [] } } }]);
+    });
+    test("takes any value for a global class or unknown", async () => {
+        expect(await schemasOf(`System.create({}, (_c, input: { canvas: OffscreenCanvas; bitmap: ImageBitmap; element: HTMLCanvasElement; anything: unknown }) => {});`)).toEqual([
+            { type: "object", properties: { canvas: { allOf: [] }, bitmap: { allOf: [] }, element: { allOf: [] }, anything: { allOf: [] } } },
+        ]);
+    });
+    test("reads the values of an `as const` object, here or imported, as a union of their literals", async () => {
+        const files = { "/src/align.ts": `export const Align = { start: "start", end: "end", again: "start" } as const;\nexport type Align = (typeof Align)[keyof typeof Align];` };
+        expect(await schemasOf([
+            `import { Align } from "./align.js";`,
+            `const Level = { low: 1, high: -1, on: true } as const satisfies Record<string, number | boolean>;`,
+            `type Level = (typeof Level)[keyof typeof Level];`,
+            `System.create({}, (_c, input: { align: Align; level: Level; inline: (typeof Level)[keyof typeof Level] }) => {});`,
+        ].join("\n"), files)).toEqual([{
+            type: "object",
+            properties: {
+                align: { anyOf: [{ const: "start" }, { const: "end" }] },
+                level: { anyOf: [{ const: 1 }, { const: -1 }, { const: true }] },
+                inline: { anyOf: [{ const: 1 }, { const: -1 }, { const: true }] },
+            },
+        }]);
+    });
+    test("follows aliases and interfaces, here and in modules imported", async () => {
+        const files = {
+            "/src/types.ts": `export type Move = { readonly by: number };\nexport interface Named { readonly name: string }\nexport { type Tagged } from "./more.js";\nexport * from "./all.js";`,
+            "/src/more.ts": `export interface Tagged extends Base { readonly tag: string }\ninterface Base { readonly base: boolean }`,
+            "/src/all.ts": `export type Spread = { readonly spread: number };`,
+        };
+        expect(await schemasOf([
+            `import type { Move, Named, Tagged, Spread } from "./types.js";`,
+            `type Local = Move & Named;`,
+            `System.create({}, (_c, input: Local) => {});`,
+            `System.create({}, (_c, input: Tagged) => {});`,
+            `System.create({}, (_c, input: Spread) => {});`,
+        ].join("\n"), files)).toEqual([
+            { type: "object", properties: { by: { type: "number" }, name: { type: "string" } } },
+            { type: "object", properties: { base: { type: "boolean" }, tag: { type: "string" } } },
+            { type: "object", properties: { spread: { type: "number" } } },
+        ]);
+    });
+    test("names the module of a type it can't read", async () => {
+        const failed = await passInputSchemas(`${header}import type { Bad } from "./bad.js";\nSystem.create({}, (_c, input: Bad) => {});`, "/src/main.ts", hostOf({ "/src/bad.ts": `export type Bad = Pick<Big, "x">;` }));
+        expect(failed !== null && "failure" in failed ? failed.failure.frames.map(frame => [frame.file, frame.line]) : failed).toEqual([["/src/bad.ts", 1]]);
+        expect(failed !== null && "failure" in failed ? failed.dependencies : failed).toEqual(["/src/bad.ts"]);
+    });
+    test("fails, saying why, for what an input type can't be", async () => {
+        const failure = async (body: string) => {
+            const schemas = await schemasOf(body);
+            return typeof schemas === "object" && schemas !== null && "failure" in schemas ? schemas.failure : schemas;
+        };
+        expect(await failure(`System.create({}, (_c, input) => {});`)).toContain("has a type");
+        expect(await failure(`System.create({}, (_c, input: { a?: number | undefined }) => {});`)).toContain("optional");
+        expect(await failure(`System.create({}, (_c, input: Pick<Big, "x">) => {});`)).toContain("type arguments");
+        expect(await failure(`type Tree = { readonly child: Tree };\nSystem.create({}, (_c, input: Tree) => {});`)).toContain("refers to itself");
+        expect(await failure(`type Box<T> = { readonly value: T };\nSystem.create({}, (_c, input: Box) => {});`)).toContain("generic");
+        expect(await failure(`System.create({}, (_c, input: [number, string]) => {});`)).toContain("one type");
+        expect(await failure(`System.create({}, (_c, input: number) => {});`)).toContain("object of named fields");
+        expect(await failure(`const Loose = { a: "a" };\nSystem.create({}, (_c, input: { a: (typeof Loose)[keyof typeof Loose] }) => {});`)).toContain("as const");
+        expect(await failure(`const Nested = { a: { b: 1 } } as const;\nSystem.create({}, (_c, input: { a: (typeof Nested)[keyof typeof Nested] }) => {});`)).toContain("literals");
+        expect(await failure(`System.create({}, (_c, input: { a: Big["x"] }) => {});`)).toContain("keyof typeof");
+        expect(await failure(`System.create({}, (_c, ...rest: [{ a: number }]) => {});`)).toContain("rest parameter");
+    });
+    test("inserts each schema after the body, mapping the rest of the line back", async () => {
+        const result = await passInputSchemas(`${header}System.create({}, (_c, input: { a: number }) => {}); const after = 1;`, "/src/main.ts", hostOf({}));
+        expect(result !== null && "code" in result ? result.code.split("\n")[1] : result).toBe(`System.create({}, (_c, input: { a: number }) => {}, {"type":"object","properties":{"a":{"type":"number"}}}); const after = 1;`);
+        expect(result !== null && "map" in result ? result.map.mappings.length > 0 : result).toBe(true);
+    });
+    test("leaves calls of another System", async () => {
+        expect(await passInputSchemas(`import { System } from "elsewhere";\nSystem.create({}, (_c, input: { a: number }) => {});`, "/src/main.ts", hostOf({}))).toBe(null);
+    });
+});

package/src/implementation/compiler/input-schemas.ts

@@ -0,0 +1,107 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import type { Failure } from './failure.js';
+import type { Insertion } from './source-map.js';
+import { createConverter, isThrown, type Module, type Node, type Statement, type TypeHost, type TypeNode } from './type-schemas.js';
+
+/** Whether an import specifier, resolved from `importer`, is a module of the package exporting `System`. */
+export type IsSystem = (specifier: string, importer: string) => Promise<boolean>;
+
+export type InputHost = TypeHost & { readonly isSystem: IsSystem };
+
+/** What a pass inserts into a module, and the files whose types it read; or why it failed. */
+export type PassResult =
+    | { readonly insertions: readonly Insertion[]; readonly dependencies: readonly string[] }
+    | { readonly failure: Failure; readonly dependencies: readonly string[] };
+
+type Expression = Extract<Statement, { readonly type: "ExpressionStatement" }>["expression"];
+type Call = Extract<Expression, { readonly type: "CallExpression" }>;
+type FunctionNode = Extract<Expression, { readonly type: "ArrowFunctionExpression" | "FunctionExpression" }>;
+
+/** Every node under `node`, in source order. */
+const each = (node: unknown, visit: (node: Node) => void): void => {
+    if (Array.isArray(node)) {
+        for (const item of node) each(item, visit);
+        return;
+    }
+    if (typeof node !== "object" || node === null || typeof Reflect.get(node, "type") !== "string") return;
+    if (isNode(node)) visit(node);
+    for (const key of Object.keys(node)) if (key !== "parent") each(Reflect.get(node, key), visit);
+};
+
+const isNode = (value: object): value is Node => typeof Reflect.get(value, "start") === "number" && typeof Reflect.get(value, "end") === "number";
+
+// Each call's arguments are its own expressions.
+const isCall = (node: Node): node is Call => node.type === "CallExpression";
+
+const unwrapped = (node: Call["arguments"][number]): Call["arguments"][number] =>
+    node.type === "ParenthesizedExpression" ? unwrapped(node.expression) : node;
+
+const isFunction = (node: Call["arguments"][number]): node is FunctionNode => node.type === "ArrowFunctionExpression" || node.type === "FunctionExpression";
+
+/** Whether a declaration written in place declares `components`; null when it isn't written in place. */
+const declaresComponents = (declaration: Call["arguments"][number]): boolean | null => {
+    if (declaration.type !== "ObjectExpression") return null;
+    return declaration.properties.some(property => property.type === "Property" && !property.computed
+        && ((property.key.type === "Identifier" && property.key.name === "components") || (property.key.type === "Literal" && property.key.value === "components")));
+};
+
+/**
+ * Passes each `System.create(declaration, body)` the schema of its body's input, the type of its parameter after its
+ * context, as a third argument: `create` takes the schema from there. The type is read from its syntax, through aliases
+ * and interfaces of the module and those it imports, so it needs no type checker. Returns null when no system here
+ * takes input.
+ */
+export const inputInsertions = async (module: Module, host: InputHost): Promise<PassResult | null> => {
+    const { code, file, program } = module;
+    if (!code.includes("System") || !code.includes(".create(")) return null;
+    const converter = createConverter(host, file);
+    const { fail } = converter;
+    const systems = new Set<string>();
+    for (const [local, entry] of module.imports) {
+        if (entry.imported === "System" && await host.isSystem(entry.source, file)) systems.add(local);
+    }
+    if (systems.size === 0) return null;
+    const calls: Call[] = [];
+    each(program.body, node => {
+        if (!isCall(node)) return;
+        const { callee } = node;
+        if (callee.type === "MemberExpression" && !callee.computed && callee.object.type === "Identifier" && systems.has(callee.object.name)
+            && callee.property.type === "Identifier" && callee.property.name === "create" && node.arguments.length === 2) calls.push(node);
+    });
+    const insertions: Insertion[] = [];
+    try {
+        for (const call of calls) {
+            const [declaration, second] = call.arguments;
+            if (declaration === undefined || second === undefined) continue;
+            const body = unwrapped(second);
+            if (!isFunction(body)) continue;
+            const components = declaresComponents(declaration);
+            // For a declaration not written in place, a third parameter is the input, as is a second one with a type: a
+            // context is rarely given one.
+            const before = components === null ? (body.params.length > 2 || annotationOf(body.params[1]) === null ? 2 : 1) : components ? 2 : 1;
+            const parameter = body.params[before];
+            if (parameter === undefined) continue;
+            if (parameter.type === "RestElement") fail(module, parameter, "a body's input is one parameter, not a rest parameter");
+            if (parameter.type === "AssignmentPattern") fail(module, parameter, "a body's input has no default");
+            const annotation = annotationOf(parameter);
+            if (annotation === null) return fail(module, parameter, "a body's input parameter has a type, which its schema is made from");
+            converter.site.at = parameter.start;
+            const schema = await converter.convert(annotation, module, new Set(), "input");
+            if (!("type" in schema) || schema.type !== "object") fail(module, parameter, "a body's input is an object of named fields");
+            insertions.push({ at: second.end, text: `, ${JSON.stringify(schema)}` });
+        }
+    } catch (error) {
+        if (isThrown(error)) return { failure: error.typeFailure, dependencies: [...converter.read] };
+        throw error;
+    }
+    if (insertions.length === 0) return null;
+    return { insertions, dependencies: [...converter.read] };
+};
+
+type Parameter = FunctionNode["params"][number];
+
+const annotationOf = (parameter: Parameter | undefined): TypeNode | null => {
+    if (parameter === undefined || parameter.type === "TSParameterProperty") return null;
+    const annotation = parameter.type === "RestElement" ? parameter.typeAnnotation : parameter.typeAnnotation;
+    return annotation === null || annotation === undefined ? null : annotation.typeAnnotation;
+};

package/src/implementation/compiler/ir.ts

@@ -1,3 +1,4 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 import type { BinaryOperator } from 'estree';
 import type { Path, Program } from '../world/kernel.js';
 import type { Out } from './out.js';
@@ -22,10 +23,14 @@ export type Expression =
     | { readonly kind: "number"; readonly value: number }
     | { readonly kind: "boolean"; readonly value: boolean }
     | { readonly kind: "column"; readonly column: number }
+    /** Whether this call's archetype has an optional component, by its presence column: the same for every row. */
+    | { readonly kind: "present"; readonly column: number }
     /** A column of the row's parent, at the parent's row: `Unit.upColumns`. */
     | { readonly kind: "upColumn"; readonly column: number }
     | { readonly kind: "resource"; readonly index: number; readonly path: Path }
     | { readonly kind: "args"; readonly path: Path }
+    /** A leaf of the call's archetype's value of shared component `index`, in `Signature.shared` order: a parameter of the call. */
+    | { readonly kind: "shared"; readonly index: number; readonly path: Path }
     | { readonly kind: "local"; readonly local: number }
     | { readonly kind: "unary"; readonly operator: Unary; readonly operand: Expression }
     | { readonly kind: "binary"; readonly operator: Binary; readonly left: Expression; readonly right: Expression }
@@ -54,8 +59,8 @@ export type Statement =
     /** Declares `let` locals that every path assigns before reading. */
     | { readonly kind: "declare"; readonly locals: readonly number[] }
     | { readonly kind: "store"; readonly column: number; readonly value: Expression }
-    /** Stamps a changed column at the row and its chunk column at the row's chunk. */
-    | { readonly kind: "stamp"; readonly column: number; readonly chunks: number }
+    /** Stamps a changed column at the row, and its chunk and block columns at the row's chunk and block. */
+    | { readonly kind: "stamp"; readonly column: number; readonly chunks: number; readonly blocks: number }
     | { readonly kind: "if"; readonly test: Expression; readonly consequent: Out; readonly alternate: Out }
     | { readonly kind: "block"; readonly label: number; readonly body: Out }
     | { readonly kind: "loop"; readonly label: number; readonly body: Out }

package/src/implementation/compiler/kernel-id.ts

@@ -1,3 +1,4 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 /// <reference types="node" />
 import { createHash } from 'node:crypto';
 

package/src/implementation/compiler/key.ts

@@ -1,3 +1,4 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 import type { AssignmentProperty, MemberExpression, Node, Property } from 'estree';
 import { fail } from './failure.js';
 import type { Out } from './out.js';

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

@@ -1,12 +1,15 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 import { describe, expect, test } from 'vitest';
 import { parseAst } from 'vite';
 import { createLinker, isPending, resolveExport, type Link, type LinkHost } from './link.js';
 import { estreeOf } from './estree.js';
+import { nodeCopies } from './paths.js';
 
 const parse = (code: string) => estreeOf(parseAst(code));
 
 /** Resolves `./name.js` to `/name.js`, and loads from `files`, which tests may change. */
 const host = (files: Map<string, string>, gate: Promise<void> = Promise.resolve()): LinkHost => ({
+    packages: nodeCopies,
     resolve: async specifier => `/${specifier.replace(/^\.\//, "")}`,
     load: async file => {
         const code = files.get(file);