@adobe/ecs 0.0.0-stage → 0.1.0

package/src/implementation/compiler/paths.ts

@@ -0,0 +1,43 @@
+/// <reference types="node" />
+import { extname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const here = fileURLToPath(import.meta.url);
+const extension = extname(here);
+const posix = (path: string): string => path.replace(/\\/g, "/");
+const packageRoot = posix(fileURLToPath(new URL("../../..", import.meta.url))).replace(/\/$/, "");
+
+/** The runtime hook emitted code imports: the source file when running from `src`, the built one from `dist`. */
+export const attachKernelPath = posix(fileURLToPath(new URL(`../world/attach-kernel${extension}`, import.meta.url)));
+
+/** The runtime hook for spawns whose values pass positionally. */
+export const prepareSpawnPath = posix(fileURLToPath(new URL(`../world/prepared-spawn${extension}`, import.meta.url)));
+
+/** The runtime hook for index lookups whose keys pass positionally. */
+export const prepareLookupPath = posix(fileURLToPath(new URL(`../world/prepared-lookup${extension}`, import.meta.url)));
+
+const intrinsicModules: ReadonlySet<string> = new Set(["src/interface/math/intrinsic.ts", "src/interface/math/intrinsic.js", "dist/interface/math/intrinsic.js"].map(path => `${packageRoot}/${path}`));
+
+/** Whether a file is the module math functions declare their WGSL builtins with. */
+export const isIntrinsicModule = (file: string): boolean => intrinsicModules.has(posix(file));
+
+/** The package root's module, for kernels that import the package when a build treats it as external. */
+export const packageIndex = posix(fileURLToPath(new URL(`../../index${extension}`, import.meta.url)));
+
+const systemModules: ReadonlySet<string> = new Set([
+    "src/interface/system/system.ts", "src/interface/system/system.js", "dist/interface/system/system.js",
+    "src/interface/index.ts", "src/interface/index.js", "dist/interface/index.js", "src/index.ts", "src/index.js", "dist/index.js",
+].map(path => `${packageRoot}/${path}`));
+
+/** Whether a resolved module id is this package's `System` namespace, directly or through the package root. */
+export const isSystemModule = (id: string): boolean => systemModules.has(posix(id.split("?")[0] ?? id));
+
+const roots = ["src/interface/index.ts", "src/interface/index.js", "dist/interface/index.js", "src/index.ts", "src/index.js", "dist/index.js"];
+const namespaceModules: { readonly [namespace: string]: ReadonlySet<string> } = Object.fromEntries(
+    [["System", "system/system"], ["Rule", "rule/rule"], ["Finalizer", "finalizer/finalizer"], ["Index", "indexes/index-type"]].map(([namespace, module]) => [namespace, new Set(
+        [`src/interface/${module}.ts`, `src/interface/${module}.js`, `dist/interface/${module}.js`, ...roots].map(path => `${packageRoot}/${path}`),
+    )]),
+);
+
+/** Whether a resolved module id is the module of this package's `namespace`, directly or through the package root. */
+export const isNamespaceModule = (id: string, namespace: string): boolean => namespaceModules[namespace]?.has(posix(id.split("?")[0] ?? id)) ?? false;

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

@@ -0,0 +1,375 @@
+/// <reference types="node" />
+import { mkdirSync, mkdtempSync, realpathSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { afterAll, expect, test } from 'vitest';
+import { build, createServer, type Rollup, type ViteDevServer } from 'vite';
+import type { KernelDescription, KernelModule } from '../world/kernel.js';
+import { kernelPlugin } from './plugin.js';
+
+const source = (path: string) => JSON.stringify(fileURLToPath(new URL(path, import.meta.url)));
+const directory = realpathSync(mkdtempSync(join(tmpdir(), "ecs-kernel-")));
+// The application's package, which names its modules' ids.
+writeFileSync(join(directory, "package.json"), JSON.stringify({ name: "fixture-app", type: "module" }));
+const fixture = join(directory, "fixture.js");
+writeFileSync(fixture, `import { System } from ${source("../../interface/system/system.ts")};
+import { Component } from ${source("../../interface/component/component.ts")};
+import { kernelOf } from ${source("../world/attach-kernel.ts")};
+const score = Symbol("score");
+Component.register(score, { type: { type: "number" } });
+const kernel = System.create({ name: "fixture", kernel: "cpu", components: { write: [score] } }, (row) => { row[score] = row.entity * 2; });
+export const description = kernelOf(kernel);
+`);
+/** A kernel inlining a TypeScript helper and a function from a package's `dist`. */
+const linked = join(directory, "linked.js");
+const helper = join(directory, "helper.ts");
+const writeHelper = (factor: number) => writeFileSync(helper, `type Factor = number;\nconst factor: Factor = ${factor};\nexport const scaled = (x: number): number => x * factor;\n`);
+writeHelper(2);
+mkdirSync(join(directory, "node_modules/fake-math/dist"), { recursive: true });
+writeFileSync(join(directory, "node_modules/fake-math/package.json"), JSON.stringify({ name: "fake-math", type: "module", exports: "./dist/index.js" }));
+writeFileSync(join(directory, "node_modules/fake-math/dist/index.js"), "export const increment = (x) => x + 1;\n");
+/** The linked kernel's keys, in a module of their own that the edit doesn't evaluate again. */
+writeFileSync(join(directory, "linked-keys.js"), `import { Component } from ${source("../../interface/component/component.ts")};
+export const score = Symbol("score");
+Component.register(score, { type: { type: "number" } });
+`);
+writeFileSync(linked, `import { System } from ${source("../../interface/system/system.ts")};
+import { kernelOf } from ${source("../world/attach-kernel.ts")};
+import { scaled } from "./helper.ts";
+import { increment } from "fake-math";
+import { score } from "./linked-keys.js";
+// Serving evaluates this module again after an edit, declaring the same system again with the same keys.
+const kernel = System.create({ name: "linked", kernel: "cpu", components: { write: [score] } }, (row) => { row[score] = increment(scaled(row.entity)); });
+export const description = kernelOf(kernel);
+`);
+/** A kernel spawning through a list another module declares, which the test edits. */
+const listing = join(directory, "listing.js");
+const listed = join(directory, "listed.js");
+const writeListed = (keys: string) => writeFileSync(listed, `import { Component } from ${source("../../interface/component/component.ts")};
+import { score } from "./linked-keys.js";
+export const extra = Symbol("extra");
+Component.register(extra, { type: { const: true } });
+export const Listed = [${keys}];
+`);
+writeListed("score");
+writeFileSync(listing, `import { System } from ${source("../../interface/system/system.ts")};
+import { kernelOf } from ${source("../world/attach-kernel.ts")};
+import { score } from "./linked-keys.js";
+import { Listed } from "./listed.js";
+const kernel = System.create({ name: "listing", kernel: "cpu", components: { read: [score] } }, (row, { commands }) => { commands.spawn(Listed)({ [score]: row[score] }); });
+export const description = kernelOf(kernel);
+`);
+/** An application importing a kernel a library ships uncompiled, from its `dist`. */
+const application = join(directory, "application.js");
+mkdirSync(join(directory, "node_modules/@adobe"), { recursive: true });
+symlinkSync(fileURLToPath(new URL("../../..", import.meta.url)), join(directory, "node_modules/@adobe/ecs"));
+mkdirSync(join(directory, "node_modules/kernel-library/dist"), { recursive: true });
+writeFileSync(join(directory, "node_modules/kernel-library/package.json"), JSON.stringify({ name: "kernel-library", type: "module", exports: "./dist/index.js" }));
+writeFileSync(join(directory, "node_modules/kernel-library/dist/index.js"), `import { Component, System } from "@adobe/ecs";
+const score = Symbol("score");
+Component.register(score, { type: { type: "number" } });
+export const kernel = System.create({ name: "library", kernel: "cpu", components: { write: [score] } }, (row) => { row[score] = row.entity * 2; });
+`);
+writeFileSync(application, `import { kernelOf } from ${source("../world/attach-kernel.ts")};
+import { kernel } from "kernel-library";
+export const description = kernelOf(kernel);
+`);
+/** Two kernels in one module, writing different functions of the entity. */
+const pair = join(directory, "pair.js");
+writeFileSync(pair, `import { System } from ${source("../../interface/system/system.ts")};
+import { Component } from ${source("../../interface/component/component.ts")};
+import { kernelOf } from ${source("../world/attach-kernel.ts")};
+const score = Symbol("score");
+Component.register(score, { type: { type: "number" } });
+const doubled = System.create({ name: "doubled", kernel: "cpu", components: { write: [score] } }, (row) => { row[score] = row.entity * 2; });
+const tripled = System.create({ name: "tripled", kernel: "cpu", components: { write: [score] } }, (row) => { row[score] = row.entity * 3; });
+export const descriptions = [kernelOf(doubled), kernelOf(tripled)];
+`);
+/** A module of keys and what it declares with them, which serving evaluates again under another query. */
+const keys = (declaration: string, released = "score") => `import { System as Systems } from ${source("../../interface/system/system.ts")};
+import { Component } from ${source("../../interface/component/component.ts")};
+import { Finalizer } from ${source("../../interface/finalizer/finalizer.ts")};
+import { Rule } from ${source("../../interface/rule/rule.ts")};
+import { labelOf } from ${source("../../interface/registry/names.ts")};
+export const score = Symbol("score");
+const shown = Symbol("shown");
+Component.register(score, ${declaration});
+Component.register(shown, { type: { const: true }, derived: true });
+export const rule = Rule.create({ name: "keys/shown", components: { has: [score] }, derive: [shown] });
+export const release = Finalizer.create({ name: "keys/release", components: { read: [${released}] } }, () => {});
+export const system = Systems.create({ name: "keys/write", components: { write: [score] } }, (row) => { row[score] = 1; });
+export const kernel = Systems.create({ name: "keys/write", kernel: "cpu", components: { write: [score] } }, (row) => { row[score] = 2; });
+export const label = labelOf(score);
+`;
+const evaluated = join(directory, "evaluated.js");
+writeFileSync(evaluated, keys(`{ type: { type: "number" } }`));
+const changed = join(directory, "changed.js");
+writeFileSync(changed, keys(`{ type: { type: "number" } }`));
+const changedItems = join(directory, "changed-items.js");
+writeFileSync(changedItems, keys(`{ type: { type: "number" } }`));
+/** An application whose keys are its own and a dependency's, and a worker's. */
+const identified = join(directory, "identified.js");
+mkdirSync(join(directory, "node_modules/key-library/dist"), { recursive: true });
+writeFileSync(join(directory, "node_modules/key-library/package.json"), JSON.stringify({ name: "key-library", type: "module", exports: "./dist/index.js" }));
+writeFileSync(join(directory, "node_modules/key-library/dist/index.js"), `export const marker = Symbol("marker");\n`);
+writeFileSync(join(directory, "worker-keys.js"), `export const message = Symbol("message");\nself.postMessage(String(message.description));\n`);
+writeFileSync(identified, `import { labelOf } from ${source("../../interface/registry/names.ts")};
+import { Component } from ${source("../../interface/component/component.ts")};
+import { marker } from "key-library";
+export const score = Symbol("score");
+const twin = Symbol("score");
+export default Symbol();
+Component.register(score, { type: { type: "number" } });
+Component.register(twin, { type: { type: "number" } });
+export const labels = [labelOf(score), labelOf(twin), labelOf(marker)];
+export const worker = () => new Worker(new URL("./worker-keys.js", import.meta.url), { type: "module" });
+`);
+/** Kernels adding a key and a list a package external to the build declares, so the build can't read them. */
+mkdirSync(join(directory, "node_modules/external-keys"), { recursive: true });
+writeFileSync(join(directory, "node_modules/external-keys/package.json"), JSON.stringify({ name: "external-keys", type: "module", exports: "./index.js" }));
+writeFileSync(join(directory, "node_modules/external-keys/index.js"), `export const heat = Symbol("heat");\nexport const Pair = [Symbol("left"), Symbol("right")];\n`);
+const externalKernel = (name: string, added: string) => `import { System } from ${source("../../interface/system/system.ts")};
+import { Component } from ${source("../../interface/component/component.ts")};
+import { kernelOf } from ${source("../world/attach-kernel.ts")};
+import { ${added} } from "external-keys";
+const score = Symbol("score");
+Component.register(score, { type: { type: "number" } });
+const kernel = System.create({ name: "${name}", kernel: "cpu", components: { read: [score] } }, (row, { commands }) => { commands.add(row.entity, ${added}, row[score]); });
+export const description = kernelOf(kernel);
+`;
+const externalKey = join(directory, "external-key.js");
+writeFileSync(externalKey, externalKernel("externalKey", "heat"));
+const externalList = join(directory, "external-list.js");
+writeFileSync(externalList, externalKernel("externalList", "Pair"));
+afterAll(() => rmSync(directory, { recursive: true, force: true }));
+
+/** Runs a one-column kernel writing a function of the entity, for entities 3 and 4. */
+const runs = (module: KernelModule, description: KernelDescription): readonly number[] => {
+    const entities = Float64Array.from([3, 4]);
+    const columns = description.columns.map(column => column.kind === "entity" ? entities : column.kind === "changed" ? new Uint32Array(2) : new Float64Array(2));
+    const commands = { spawners: [], begin: () => {}, value: () => {}, component: () => {} };
+    module.create(columns.map(() => false), columns.map(() => 1), columns.map(() => 0))(columns, 0, 2, [], [], description.keys, undefined, commands, 1, new Float64Array(0), 0);
+    return [...columns[description.columns.findIndex(column => column.kind === "field")] ?? []];
+};
+
+test("a build emits each kernel as its own chunk, referenced by the description's url", async () => {
+    const outDir = join(directory, "dist");
+    const output = await build({
+        configFile: false, logLevel: "silent", root: directory, plugins: [kernelPlugin()],
+        build: { outDir, minify: false, lib: { entry: fixture, formats: ["es"], fileName: "main" } },
+    });
+    const chunks = (Array.isArray(output) ? output : [output]).flatMap((result: Rollup.RollupOutput | Rollup.RollupWatcher) => "output" in result ? result.output : [])
+        .filter((item): item is Rollup.OutputChunk => item.type === "chunk");
+    const kernel = chunks.find(chunk => chunk.name.startsWith("kernel-"));
+    const main = chunks.find(chunk => chunk.facadeModuleId === fixture);
+    expect(kernel).toBeDefined();
+    expect(main?.code).not.toContain("columns, start, end");
+    const { description }: { description: KernelDescription } = await import(/* @vite-ignore */ pathToFileURL(join(outDir, main?.fileName ?? "")).href);
+    expect(description.url).toBe(pathToFileURL(join(outDir, kernel?.fileName ?? "")).href);
+    const module: KernelModule = await import(/* @vite-ignore */ description.url);
+    expect(runs(module, description)).toEqual([6, 8]);
+});
+
+const serve = async <T>(use: (server: ViteDevServer) => Promise<T>): Promise<T> => {
+    const server = await createServer({
+        configFile: false, logLevel: "silent", root: directory, plugins: [kernelPlugin()],
+        appType: "custom", server: { middlewareMode: true, hmr: false, watch: null }, optimizeDeps: { noDiscovery: true },
+    });
+    try {
+        return await use(server);
+    } finally {
+        await server.close();
+    }
+};
+
+test("a build gives each kernel the url of its own chunk", async () => {
+    const outDir = join(directory, "dist-pair");
+    const output = await build({
+        configFile: false, logLevel: "silent", root: directory, plugins: [kernelPlugin()],
+        build: { outDir, minify: false, lib: { entry: pair, formats: ["es"], fileName: "main" } },
+    });
+    const main = (Array.isArray(output) ? output : [output]).flatMap((result: Rollup.RollupOutput | Rollup.RollupWatcher) => "output" in result ? result.output : [])
+        .find((item): item is Rollup.OutputChunk => item.type === "chunk" && item.facadeModuleId === pair);
+    const { descriptions }: { descriptions: readonly KernelDescription[] } = await import(/* @vite-ignore */ pathToFileURL(join(outDir, main?.fileName ?? "")).href);
+    expect(new Set(descriptions.map(description => description.url)).size).toBe(2);
+    const results = await Promise.all(descriptions.map(async description => runs(await import(/* @vite-ignore */ description.url), description)));
+    expect(results).toEqual([[6, 8], [9, 12]]);
+});
+
+/** The url a page's code gives a module's first kernel, as the dev server serves it to a browser and its workers. */
+const servedUrl = async (server: ViteDevServer, module: string): Promise<string> => {
+    const code = (await server.transformRequest(module))?.code ?? "";
+    return /"(\/@ecs-kernel\/[^"]+)"/.exec(code)?.[1] ?? "";
+};
+
+test("serve loads a kernel module by url, also before its parent was transformed", async () => {
+    // Modules are untyped here; their shapes are what the plugin emits.
+    const description: KernelDescription = await serve(async server => {
+        const parent = await server.ssrLoadModule(fixture);
+        expect(server.config.optimizeDeps.exclude).toContain("@adobe/ecs");
+        return parent.description;
+    });
+    const url = await serve(server => servedUrl(server, fixture));
+    expect(url).toMatch(/^\/@ecs-kernel\/.+\?h=/);
+    const module = await serve(server => server.ssrLoadModule(url));
+    expect(runs({ create: module.create }, description)).toEqual([6, 8]);
+});
+
+test("serve in node gives each kernel a url a node worker imports, as a pool's do outside the dev server", async () => {
+    const description: KernelDescription = await serve(async server => (await server.ssrLoadModule(fixture)).description);
+    expect(description.url).toMatch(/^data:text\/javascript;base64,/);
+    const { Worker } = await import("node:worker_threads");
+    const worker = new Worker(`const { parentPort } = require("node:worker_threads");
+import(${JSON.stringify(description.url)}).then(module => parentPort.postMessage(typeof module.create), error => parentPort.postMessage(String(error)));`, { eval: true });
+    const reply = await new Promise<unknown>(resolve => worker.once("message", resolve));
+    await worker.terminate();
+    expect(reply).toBe("function");
+});
+
+test("serve rejects a url for a different version of the kernel", async () => {
+    const stale = (await serve(server => servedUrl(server, fixture))).replace(/\?h=.*/, "?h=stale");
+    await expect(serve(server => server.ssrLoadModule(stale))).rejects.toThrow(/changed since its description was compiled/);
+});
+
+test("a build inlines functions from TypeScript modules and packages", async () => {
+    const outDir = join(directory, "dist-linked");
+    const output = await build({
+        configFile: false, logLevel: "silent", root: directory, plugins: [kernelPlugin()],
+        build: { outDir, minify: false, lib: { entry: linked, formats: ["es"], fileName: "main" } },
+    });
+    const chunks = (Array.isArray(output) ? output : [output]).flatMap((result: Rollup.RollupOutput | Rollup.RollupWatcher) => "output" in result ? result.output : [])
+        .filter((item): item is Rollup.OutputChunk => item.type === "chunk");
+    const main = chunks.find(chunk => chunk.facadeModuleId === linked);
+    const { description }: { description: KernelDescription } = await import(/* @vite-ignore */ pathToFileURL(join(outDir, main?.fileName ?? "")).href);
+    const module: KernelModule = await import(/* @vite-ignore */ description.url);
+    expect(runs(module, description)).toEqual([7, 9]);
+});
+
+test("serve compiles kernels again when a file they inline from changes", async () => {
+    try {
+        await serve(async server => {
+            const before: KernelDescription = (await server.ssrLoadModule(linked)).description;
+            expect(runs({ create: (await server.ssrLoadModule(before.url)).create }, before)).toEqual([7, 9]);
+            writeHelper(3);
+            server.watcher.emit("change", helper);
+            const after: KernelDescription = (await server.ssrLoadModule(linked)).description;
+            expect(after.url).not.toBe(before.url);
+            expect(runs({ create: (await server.ssrLoadModule(after.url)).create }, after)).toEqual([10, 13]);
+        });
+    } finally {
+        writeHelper(2);
+    }
+});
+
+test("serve compiles kernels again when a list they import changes", async () => {
+    try {
+        await serve(async server => {
+            const before: KernelDescription = (await server.ssrLoadModule(listing)).description;
+            expect(before.keys.map(String)).toEqual(["Symbol(score)"]);
+            writeListed("score, extra");
+            server.watcher.emit("change", listed);
+            const after: KernelDescription = (await server.ssrLoadModule(listing)).description;
+            expect(after.url).not.toBe(before.url);
+            expect(after.keys.map(String)).toEqual(["Symbol(score)", "Symbol(extra)"]);
+        });
+    } finally {
+        writeListed("score");
+    }
+});
+
+test("an application's build compiles the kernels a library ships uncompiled", async () => {
+    const outDir = join(directory, "dist-application");
+    const output = await build({
+        configFile: false, logLevel: "silent", root: directory, plugins: [kernelPlugin()],
+        build: { outDir, minify: false, lib: { entry: application, formats: ["es"], fileName: "main" } },
+    });
+    const main = (Array.isArray(output) ? output : [output]).flatMap((result: Rollup.RollupOutput | Rollup.RollupWatcher) => "output" in result ? result.output : [])
+        .find((item): item is Rollup.OutputChunk => item.type === "chunk" && item.facadeModuleId === application);
+    const { description }: { description: KernelDescription | undefined } = await import(/* @vite-ignore */ pathToFileURL(join(outDir, main?.fileName ?? "")).href);
+    expect(description).toBeDefined();
+    const module: KernelModule = await import(/* @vite-ignore */ description?.url ?? "");
+    expect(description === undefined ? [] : runs(module, description)).toEqual([6, 8]);
+});
+
+test("serve accepts a module of keys evaluated again, which makes the same keys, systems, rules and finalizers by their ids", async () => {
+    await serve(async server => {
+        const first = await server.ssrLoadModule(evaluated);
+        const again = await server.ssrLoadModule(`${evaluated}?evaluated=again`);
+        const { labelOfItem, sameItem } = await server.ssrLoadModule(JSON.parse(source("../../interface/registry/items.ts")));
+        expect(again.score).not.toBe(first.score);
+        expect([first.label, again.label]).toEqual(["score", "score"]);
+        expect(again.system).not.toBe(first.system);
+        expect([sameItem(again.system, first.system), sameItem(again.kernel, first.kernel), sameItem(again.kernel, again.system)]).toEqual([true, true, false]);
+        expect(again.rule).toBe(first.rule);
+        expect(again.release).toBe(first.release);
+        // The two systems share a name, so each is labeled with its id.
+        expect([labelOfItem(again.system), labelOfItem(first.kernel)]).toEqual(["keys/write (fixture-app/evaluated.js#system)", "keys/write (fixture-app/evaluated.js#kernel)"]);
+    });
+});
+
+test("serve reports a finalizer evaluated again under its id with another declaration", async () => {
+    await serve(async server => {
+        await server.ssrLoadModule(changedItems);
+        writeFileSync(changedItems, keys(`{ type: { type: "number" } }`, "shown"));
+        await expect(server.ssrLoadModule(`${changedItems}?evaluated=changed`)).rejects.toThrow(`Cannot declare "keys/release" (fixture-app/changed-items.js#release): its id is another item's, with another declaration; if a module was evaluated again with a changed declaration, reload the page.`);
+    });
+});
+
+test("serve reports a key evaluated again with another declaration", async () => {
+    await serve(async server => {
+        await server.ssrLoadModule(changed);
+        writeFileSync(changed, keys(`{ type: { type: "string" } }`));
+        await expect(server.ssrLoadModule(`${changed}?evaluated=changed`)).rejects.toThrow(`Cannot register component "fixture-app/changed.js#score": its id is another key's, with another declaration`);
+    });
+});
+
+/** Every id a build's code gives a symbol. */
+const idsIn = (code: string): readonly string[] => [...code.matchAll(/identify\$[$\d]*\(Symbol\([^)]*\), "([^"]*)"\)/g)].map(match => match[1] ?? "");
+
+test("a build gives top-level symbols ids naming no absolute path, also in workers", async () => {
+    const outDir = join(directory, "dist-identified");
+    const output = await build({
+        configFile: false, logLevel: "silent", root: directory, plugins: [kernelPlugin()],
+        build: { outDir, minify: false, rolldownOptions: { input: identified, preserveEntrySignatures: "strict" } },
+    });
+    const items = (Array.isArray(output) ? output : [output]).flatMap((result: Rollup.RollupOutput | Rollup.RollupWatcher) => "output" in result ? result.output : []);
+    const main = items.find((item): item is Rollup.OutputChunk => item.type === "chunk" && item.facadeModuleId === identified);
+    expect(new Set(idsIn(main?.code ?? "").filter(id => !id.startsWith("@adobe/ecs/")))).toEqual(new Set(["fixture-app/identified.js#score", "fixture-app/identified.js#twin", "fixture-app/identified.js#default", "key-library/dist/index.js#marker"]));
+    const worker = items.find(item => item.fileName.includes("worker-keys"));
+    expect(idsIn(worker === undefined ? "" : worker.type === "chunk" ? worker.code : String(worker.source))).toEqual(["fixture-app/worker-keys.js#message"]);
+    const ids = items.flatMap(item => idsIn(item.type === "chunk" ? item.code : String(item.source)));
+    expect(ids.filter(id => id.startsWith("/") || id.includes(directory) || id.includes(tmpdir()))).toEqual([]);
+    const { labels }: { labels: readonly string[] } = await import(/* @vite-ignore */ pathToFileURL(join(outDir, main?.fileName ?? "")).href);
+    // Keys sharing a description are labeled by their ids; a key whose description is its own, by its description.
+    expect(labels).toEqual(["fixture-app/identified.js#score", "fixture-app/identified.js#twin", "marker"]);
+});
+
+test("a second instance of the plugin in one bundle does nothing, as when an application also lists it for workers", async () => {
+    const outDir = join(directory, "dist-twice");
+    const output = await build({
+        configFile: false, logLevel: "silent", root: directory, plugins: [kernelPlugin(), kernelPlugin()],
+        build: { outDir, minify: false, lib: { entry: fixture, formats: ["es"], fileName: "main" } },
+    });
+    const chunks = (Array.isArray(output) ? output : [output]).flatMap((result: Rollup.RollupOutput | Rollup.RollupWatcher) => "output" in result ? result.output : [])
+        .filter((item): item is Rollup.OutputChunk => item.type === "chunk");
+    expect(chunks.filter(chunk => chunk.name.startsWith("kernel-"))).toHaveLength(1);
+    const main = chunks.find(chunk => chunk.facadeModuleId === fixture);
+    expect(idsIn(main?.code ?? "").filter(id => id.startsWith("fixture-app/"))).toEqual(["fixture-app/fixture.js#score"]);
+    const { description }: { description: KernelDescription } = await import(/* @vite-ignore */ pathToFileURL(join(outDir, main?.fileName ?? "")).href);
+    expect(runs(await import(/* @vite-ignore */ description.url), description)).toEqual([6, 8]);
+});
+
+test("a build takes a name from a package external to it as one key, and registration rejects a list there", async () => {
+    const outDir = join(directory, "dist-external");
+    const output = await build({
+        configFile: false, logLevel: "silent", root: directory, plugins: [kernelPlugin()],
+        build: { outDir, minify: false, rolldownOptions: { input: [externalKey, externalList], external: ["external-keys"], preserveEntrySignatures: "strict" } },
+    });
+    const chunks = (Array.isArray(output) ? output : [output]).flatMap((result: Rollup.RollupOutput | Rollup.RollupWatcher) => "output" in result ? result.output : [])
+        .filter((item): item is Rollup.OutputChunk => item.type === "chunk");
+    const url = (entry: string) => pathToFileURL(join(outDir, chunks.find(chunk => chunk.facadeModuleId === entry)?.fileName ?? "")).href;
+    const { description }: { description: KernelDescription } = await import(/* @vite-ignore */ url(externalKey));
+    expect(description.keys.map(String)).toEqual(["Symbol(heat)"]);
+    await expect(import(/* @vite-ignore */ url(externalList))).rejects.toThrow(`System "externalList" names a list of components where a command takes one component; its kernel's build couldn't read the list, so name it from a module the build reads, or as an array literal.`);
+});

package/src/implementation/compiler/plugin.ts

@@ -0,0 +1,223 @@
+/// <reference types="node" />
+import { readFileSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { isAbsolute } from 'node:path';
+import type { Plugin, Rollup, ViteDevServer } from 'vite';
+import { estreeOf } from './estree.js';
+import { describeFailure } from './failure.js';
+import { identify as identifyModule, moduleIdOf, type PackageNameOf } from './identify.js';
+import { buildId, kernelHash, parseKernelId, serveUrl } from './kernel-id.js';
+import { createLinker, type LinkHost, type Linker } from './link.js';
+import { isNamespaceModule, isSystemModule, packageIndex } from './paths.js';
+import { locateThroughMap } from './source-map.js';
+import { transformKernels } from './transform.js';
+
+const scripts = /\.[cm]?[jt]sx?$/;
+const packageName = "@adobe/ecs";
+
+type CachedKernel = { readonly source: string; readonly hash: string };
+
+const loaders: { readonly [extension: string]: "ts" | "tsx" | "jsx" } = { ts: "ts", mts: "ts", cts: "ts", tsx: "tsx", jsx: "jsx" };
+
+/** A file's code as JavaScript, with types stripped and lines mapped back to the source. */
+const loadFile = async (file: string): Promise<{ readonly code: string; readonly locate?: ReturnType<typeof locateThroughMap> }> => {
+    const code = await readFile(file, "utf8");
+    const loader = loaders[file.slice(file.lastIndexOf(".") + 1)];
+    if (loader === undefined) return { code };
+    const { transformWithOxc } = await import("vite");
+    const result = await transformWithOxc(code, file, { lang: loader, sourcemap: true });
+    return { code: result.code, locate: result.map === undefined ? undefined : locateThroughMap(result.code, result.map.mappings) };
+};
+
+/** The name each directory's package.json gives, read once per directory. */
+const packageNames = (): PackageNameOf => {
+    const names = new Map<string, string | null | undefined>();
+    return directory => {
+        if (names.has(directory)) return names.get(directory);
+        let name: string | null | undefined;
+        try {
+            const json: unknown = JSON.parse(readFileSync(`${directory}/package.json`, "utf8"));
+            const named: unknown = typeof json === "object" && json !== null ? Reflect.get(json, "name") : undefined;
+            name = typeof named === "string" && named !== "" ? named : null;
+        }
+        catch {
+            // No package.json here, or none that parses.
+            name = undefined;
+        }
+        names.set(directory, name);
+        return name;
+    };
+};
+
+/** Resolves imports through the build, from whichever transform runs. */
+const buildHost = (resolver: () => Rollup.PluginContext): LinkHost => ({
+    resolve: async (specifier, importer) => {
+        const resolved = await resolver().resolve(specifier, importer, { skipSelf: true });
+        if (resolved === null) return { error: `${specifier} can't be resolved from ${importer}` };
+        if (resolved.external) {
+            return specifier === packageName ? packageIndex : { error: `${specifier} is external to the build, so kernels can't inline from it`, unreadable: true };
+        }
+        const id = resolved.id.split("?")[0] ?? resolved.id;
+        return id.includes("\0") || !isAbsolute(id) ? { error: `${specifier} isn't a file` } : id;
+    },
+    load: loadFile,
+});
+
+/**
+ * Compiles kernel systems (`kernel: "cpu"` or `"gpu"`). Runs after TypeScript is stripped and before minification, so it sees plain JS
+ * with source names. Each kernel's `create` becomes its own module at `description.url`: served from a
+ * root-absolute url in dev, and emitted as a chunk in a build.
+ *
+ * Functions and constants kernels import are read from their files, with types stripped, and inlined (`link.ts`).
+ * The application's build compiles every kernel, its dependencies' too: a library ships its kernels uncompiled.
+ *
+ * Also gives each top-level `Symbol(...)` declaration an id, its package's name, its module's path in the package and
+ * its binding, by which the registry knows the symbol a module evaluated again makes as the same key, and in the same
+ * way the declaration of each top-level binding's system, rule or finalizer, as the same item (`identify.ts`).
+ *
+ * Dev dep pre-bundling bypasses plugins and breaks the runtime's worker url, so `@adobe/ecs` is excluded from it.
+ * Consumers must also add to `optimizeDeps.exclude` any dependency that defines kernels or keys, imports
+ * `@adobe/ecs`, or has functions kernels import; otherwise its kernels reach the runtime uncompiled, which fails
+ * at registration, its keys have no ids, or its functions can't be read.
+ *
+ * The plugin adds itself to worker bundles; an instance after the first in one bundle does nothing.
+ */
+/** Where a served kernel's url goes in node's code, until its module is compiled. */
+const inlinePlaceholder = (index: number, hash: string): string => `@ecs-kernel-inline/${index}/${hash}`;
+
+/** Code with each kernel's placeholder replaced by its module as a `data:` url, which node imports on any thread. */
+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,${Buffer.from(source).toString("base64")}`),
+    ), code);
+
+export const kernelPlugin = (): Plugin => {
+    let serve = true;
+    let root = process.cwd();
+    /** Whether an earlier instance of the plugin is in the same bundle. */
+    let repeated = false;
+    let server: ViteDevServer | undefined;
+    const packageNameOf = packageNames();
+    /**
+     * A linker per environment, since client and SSR builds resolve imports under different conditions. Each resolves
+     * through its environment's latest transform.
+     */
+    const contexts = new Map<boolean, Rollup.PluginContext>();
+    const linkers = new Map<boolean, Linker>();
+    const linkerFor = (ssr: boolean, context: Rollup.PluginContext): Linker => {
+        contexts.set(ssr, context);
+        const existing = linkers.get(ssr);
+        if (existing !== undefined) return existing;
+        const linker = createLinker(buildHost(() => contexts.get(ssr) ?? context), input => estreeOf((contexts.get(ssr) ?? context).parse(input)));
+        linkers.set(ssr, linker);
+        return linker;
+    };
+    /** Modules whose kernels inline each file, and the files each module's kernels inline. */
+    const dependents = new Map<string, Set<string>>();
+    const dependencies = new Map<string, readonly string[]>();
+    const depend = (parent: string, files: readonly string[]): void => {
+        for (const file of dependencies.get(parent) ?? []) dependents.get(file)?.delete(parent);
+        dependencies.set(parent, files);
+        for (const file of files) {
+            const parents = dependents.get(file) ?? new Set<string>();
+            parents.add(parent);
+            dependents.set(file, parents);
+        }
+    };
+    /** Kernel modules by parent module id, kept current as parents are transformed. */
+    const kernels = new Map<string, readonly CachedKernel[]>();
+    /** Reference ids of the kernel chunks a build emitted. */
+    const chunks = new Set<string>();
+    /**
+     * The bundler gives chunks emitted under one name one reference, so each kernel's name carries its hash. Its
+     * `create` is imported at run time, which the bundle can't see, so the chunk keeps its exports even where the
+     * build drops entries' signatures, as an application's does.
+     */
+    const emitChunk = (context: Rollup.PluginContext, id: string, hash: string): string => {
+        const referenceId = context.emitFile({ type: "chunk", id, name: `kernel-${hash}`, preserveSignature: "exports-only" });
+        chunks.add(referenceId);
+        return referenceId;
+    };
+    const plugin: Plugin = {
+        name: `${packageName}/kernel`,
+        enforce: "post",
+        // Dep pre-bundling breaks the runtime's `new Worker(new URL("./worker.js", import.meta.url))`.
+        config: () => ({ optimizeDeps: { exclude: [packageName] }, worker: { plugins: () => [kernelPlugin()] } }),
+        configResolved: config => {
+            serve = config.command === "serve";
+            root = config.root;
+            repeated = config.plugins.find(other => other.name === plugin.name) !== plugin;
+        },
+        configureServer: devServer => {
+            server = devServer;
+        },
+        // A kernel chunk's url is relative to the chunk that references it, as Rollup resolves it, rather than to `base`
+        // as Vite resolves other files, so a build's kernels load wherever it's served from or run.
+        resolveFileUrl: {
+            order: "pre",
+            handler: ({ referenceId, relativePath }) => chunks.has(referenceId) ? `new URL(${JSON.stringify(relativePath)}, import.meta.url).href` : null,
+        },
+        resolveId: id => repeated || parseKernelId(id) === undefined ? null : id,
+        async load(id) {
+            if (repeated) return null;
+            const kernel = parseKernelId(id);
+            if (kernel === undefined) return null;
+            // Transforming the parent fills the cache: for a kernel requested first, or after a restart.
+            // In dev, `this.load` doesn't read files from disk, so the server's own pipeline does it.
+            if (!kernels.has(kernel.parent)) {
+                if (server) await server.transformRequest(kernel.parent);
+                else await this.load({ id: kernel.parent });
+            }
+            const cached = kernels.get(kernel.parent)?.[kernel.index];
+            if (cached === undefined) return this.error(`no kernel ${kernel.index} in ${kernel.parent}`);
+            // A different version would pair the description's columns with another kernel's code.
+            if (kernel.hash !== undefined && kernel.hash !== cached.hash) {
+                return this.error(`kernel ${kernel.index} in ${kernel.parent} changed since its description was compiled; reload`);
+            }
+            return cached.source;
+        },
+        // Vite only soft-invalidates importers of a changed file, which doesn't transform them again, so kernels that
+        // inline from it are invalidated here.
+        watchChange(id, change) {
+            for (const linker of linkers.values()) linker.forget(id, change.event !== "update");
+            for (const parent of dependents.get(id) ?? []) {
+                for (const module of server?.moduleGraph.getModulesByFile(parent) ?? []) server?.moduleGraph.invalidateModule(module);
+            }
+        },
+        async transform(code, id, options) {
+            if (repeated || id.includes("\0") || !scripts.test(id.split("?")[0] ?? id)) return null;
+            const parse = (input: string) => estreeOf(this.parse(input));
+            const identify = (input: string) => identifyModule(input, moduleIdOf(id, root, packageNameOf), parse, async (source, namespace) => {
+                const resolved = await this.resolve(source, id);
+                return resolved !== null && (resolved.external ? source === packageName : isNamespaceModule(resolved.id, namespace));
+            });
+            const ssr = options?.ssr === true;
+            const linker = linkerFor(ssr, this);
+            const hashes: string[] = [];
+            const transformed = await transformKernels(code, id, parse, async source => {
+                const resolved = await this.resolve(source, id);
+                return resolved !== null && isSystemModule(resolved.id);
+            }, (index, identity) => {
+                const hash = kernelHash(identity);
+                hashes[index] = hash;
+                if (!serve) return `import.meta.ROLLUP_FILE_URL_${emitChunk(this, buildId(id, index), hash)}`;
+                // Served to node, a kernel's module is its url, so a pool's workers, which import it outside the server, read it too.
+                return JSON.stringify(ssr ? inlinePlaceholder(index, hash) : serveUrl(id, index, hash));
+            }, linker);
+            const result = ssr && transformed !== null && !("failure" in transformed) ? { ...transformed, code: inlineKernels(transformed.code, transformed.kernels, hashes) } : transformed;
+            const parent = id.split("?")[0] ?? id;
+            if (result === null) {
+                kernels.delete(id);
+                depend(parent, []);
+                return await identify(code);
+            }
+            for (const dependency of result.dependencies) this.addWatchFile(dependency);
+            depend(parent, result.dependencies);
+            if ("failure" in result) return this.error(describeFailure(result.failure), result.failure.position);
+            kernels.set(id, result.kernels.map((source, index) => ({ source, hash: hashes[index] ?? "" })));
+            return await identify(result.code) ?? { code: result.code, map: null };
+        },
+    };
+    return plugin;
+};