@adobe/ecs 0.1.0 → 0.2.0

package/src/implementation/compiler/plugin.ts

@@ -1,3 +1,4 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 /// <reference types="node" />
 import { readFileSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
@@ -5,11 +6,16 @@ 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 { identify as identifyModule, moduleIdOf, moduleLabelOf, type PackageOf } 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 { reductionsIn, registeredReductionsIn, registeredSharedIn, sharedIn, type AugmentationHost } from './augmentations.js';
+import type { InputHost } from './input-schemas.js';
+import { inputPass, mayHaveInput } from './passes.js';
+import { copyForImporter, namespaceCopyOf, nodeCopies, packagePathOf, typesFileOf } from './paths.js';
+import type { TypedProgram } from './type-schemas.js';
 import { locateThroughMap } from './source-map.js';
+import { inlineKernels, inlinePlaceholder } from './inline-kernels.js';
 import { transformKernels } from './transform.js';
 
 const scripts = /\.[cm]?[jt]sx?$/;
@@ -29,42 +35,94 @@ const loadFile = async (file: string): Promise<{ readonly code: string; readonly
     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>();
+/** The name and version each directory's package.json gives, read once per directory. */
+const packages = (): PackageOf => {
+    const found = new Map<string, ReturnType<PackageOf>>();
     return directory => {
-        if (names.has(directory)) return names.get(directory);
-        let name: string | null | undefined;
+        if (found.has(directory)) return found.get(directory);
+        let entry: ReturnType<PackageOf>;
         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;
+            const name: unknown = typeof json === "object" && json !== null ? Reflect.get(json, "name") : undefined;
+            const version: unknown = typeof json === "object" && json !== null ? Reflect.get(json, "version") : undefined;
+            entry = typeof name !== "string" || name === "" ? null : typeof version === "string" && version !== "" ? { name, version } : { name };
         }
         catch {
             // No package.json here, or none that parses.
-            name = undefined;
+            entry = undefined;
         }
-        names.set(directory, name);
-        return name;
+        found.set(directory, entry);
+        return entry;
     };
 };
 
+/** Vite's parser of TypeScript, loaded by the first kernel transform, which reads `reduce` traits with it. */
+let parseTypes: typeof import("vite").parseAst | null = null;
+
+const noReductions: ReadonlyMap<string, string> = new Map();
+
+/**
+ * The `reduce` traits a file's declarations give: read from a TypeScript file's source, and from the registrations a
+ * JavaScript file's build gave them, as a library's `dist` ships them.
+ */
+const reductionsOf = (file: string): ReadonlyMap<string, string> => {
+    const extension = file.slice(file.lastIndexOf(".") + 1);
+    const lang = loaders[extension] ?? (extension === "js" || extension === "mjs" ? "js" : undefined);
+    if (parseTypes === null || lang === undefined) return noReductions;
+    let code: string;
+    try {
+        code = readFileSync(file, "utf8");
+    }
+    catch {
+        return noReductions;
+    }
+    if (!code.includes("reduce")) return noReductions;
+    if (lang === "ts" || lang === "tsx") return code.includes("declare module") ? reductionsIn(parseTypes(code, { lang }, file)) : noReductions;
+    // A bundle may have renamed the registrations' import, so any JavaScript giving `reduce` is read.
+    return registeredReductionsIn(parseTypes(code, { lang }, file));
+};
+
+const noShared: ReadonlySet<string> = new Set();
+
+/**
+ * The components a file declares `shared`: read from a TypeScript file's source, and from the registrations a
+ * JavaScript file's build gave them, as a library's `dist` ships them.
+ */
+const sharedOfFile = (file: string): ReadonlySet<string> => {
+    const extension = file.slice(file.lastIndexOf(".") + 1);
+    const lang = loaders[extension] ?? (extension === "js" || extension === "mjs" ? "js" : undefined);
+    if (parseTypes === null || lang === undefined) return noShared;
+    let code: string;
+    try {
+        code = readFileSync(file, "utf8");
+    }
+    catch {
+        return noShared;
+    }
+    if (!code.includes("shared")) return noShared;
+    if (lang === "ts" || lang === "tsx") return code.includes("declare module") ? sharedIn(parseTypes(code, { lang }, file)) : noShared;
+    return registeredSharedIn(parseTypes(code, { lang }, file));
+};
+
 /** Resolves imports through the build, from whichever transform runs. */
 const buildHost = (resolver: () => Rollup.PluginContext): LinkHost => ({
+    reductions: reductionsOf,
+    shared: sharedOfFile,
     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 };
+            return specifier === packageName ? copyForImporter(importer).index : { 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,
+    packages: nodeCopies,
 });
 
 /**
- * Compiles kernel systems (`kernel: "cpu"` or `"gpu"`). Runs after TypeScript is stripped and before minification, so it sees plain JS
+ * Compiles kernel systems (`kernel: true` 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.
  *
@@ -82,23 +140,106 @@ const buildHost = (resolver: () => Rollup.PluginContext): LinkHost => ({
  *
  * 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}`;
+const typed = /\.[cm]?tsx?$/;
 
-/** 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);
+/**
+ * Registers the keys `declare module "@adobe/ecs"` blocks declare (`augmentations.ts`), passes each system's
+ * `create` the schema of its body's input, from the type of the body's parameter after its context
+ * (`input-schemas.ts`), and gives lists of keys declared `as const` their indexes (`archetypes.ts`). It runs before
+ * TypeScript is stripped, which all three read.
+ */
+const inputPlugin = (): Plugin => {
+    let repeated = false;
+    let server: ViteDevServer | undefined;
+    /** Modules whose input types each file declares, and the files each module's input types were read from. */
+    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);
+        }
+    };
+    /** The package's own files' syntax as last parsed, which every module reading the package's types shares. */
+    const parsed = new Map<string, { readonly code: string; readonly program: TypedProgram }>();
+    const instance: Plugin = {
+        name: `${packageName}/input`,
+        enforce: "pre",
+        configResolved: config => {
+            repeated = config.plugins.find(other => other.name === instance.name) !== instance;
+        },
+        configureServer: devServer => {
+            server = devServer;
+        },
+        // A module whose input types come from a changed file is transformed again, for its schemas.
+        watchChange(id) {
+            for (const parent of dependents.get(id) ?? []) {
+                for (const module of server?.moduleGraph.getModulesByFile(parent) ?? []) server?.moduleGraph.invalidateModule(module);
+            }
+        },
+        async transform(code, id) {
+            const file = id.split("?")[0] ?? id;
+            if (repeated || id.includes("\0") || !typed.test(file)) return null;
+            if (!mayHaveInput(code)) return null;
+            const { parseAst } = await import("vite");
+            const resolved = async (specifier: string, importer: string) => await this.resolve(specifier, importer, { skipSelf: true });
+            const host: InputHost & AugmentationHost = {
+                parse: (source, path) => {
+                    const known = parsed.get(path);
+                    if (known !== undefined && known.code === source) return known.program;
+                    const program = parseAst(source, { lang: path.endsWith("x") ? "tsx" : "ts" }, path);
+                    if (packagePathOf(path) !== null) parsed.set(path, { code: source, program });
+                    return program;
+                },
+                resolve: async (specifier, importer) => {
+                    const found = await resolved(specifier, importer);
+                    if (found === null) return null;
+                    // A build that treats the package as external still reads its types, from the importer's copy.
+                    const path = found.external ? (specifier === packageName ? copyForImporter(importer).index : null) : found.id.split("?")[0] ?? found.id;
+                    return path === null || path.includes("\0") || !isAbsolute(path) ? null : typesFileOf(path);
+                },
+                load: file => readFile(file, "utf8"),
+                packagePath: packagePathOf,
+                isSystem: async (specifier, importer) => {
+                    const found = await resolved(specifier, importer);
+                    return found !== null && (found.external ? specifier === packageName : namespaceCopyOf(found.id, "System") !== null);
+                },
+            };
+            const { result, dependencies } = await inputPass(code, file, host);
+            for (const dependency of dependencies) this.addWatchFile(dependency);
+            depend(file, dependencies);
+            return result !== null && "failure" in result ? this.error(describeFailure(result.failure), result.failure.position) : result;
+        },
+    };
+    return instance;
+};
+
+/**
+ * The plugin's two parts: registrations and input schemas, before TypeScript is stripped, and kernels and ids,
+ * after. A library's build takes `{ library: true }`, the first part alone: its build then ships the registrations and
+ * schemas its types give, which an application's build, reading only JavaScript there, can't make, and leaves its
+ * kernels as source and its keys without ids, which the application's plugin compiles and gives.
+ */
+export const plugin = (options: { readonly library?: boolean } = {}): Plugin[] => pluginWith(options);
 
-export const kernelPlugin = (): Plugin => {
+/**
+ * The plugin, for this package's tests: with `automatic: false`, unflagged systems run as written, so suites of the
+ * row path run their bodies that way too.
+ */
+export const pluginWith = ({ library = false, automatic = true }: { readonly library?: boolean; readonly automatic?: boolean }): Plugin[] =>
+    library ? [inputPlugin()] : [inputPlugin(), compilePlugin(automatic)];
+
+const compilePlugin = (automatic: boolean): Plugin => {
     let serve = true;
-    let root = process.cwd();
+    /** Whether this instance builds a worker's bundle. */
+    let worker = false;
     /** Whether an earlier instance of the plugin is in the same bundle. */
     let repeated = false;
     let server: ViteDevServer | undefined;
-    const packageNameOf = packageNames();
+    const packageOf = packages();
     /**
      * A linker per environment, since client and SSR builds resolve imports under different conditions. Each resolves
      * through its environment's latest transform.
@@ -139,19 +280,34 @@ export const kernelPlugin = (): Plugin => {
         chunks.add(referenceId);
         return referenceId;
     };
-    const plugin: Plugin = {
+    const instance: 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()] } }),
+        // Dep pre-bundling breaks the runtime's `new Worker(new URL("./worker.js", import.meta.url))`. Kernels are chunks
+        // of their own, so a worker bundle holding one is a module, unless the configuration says otherwise.
+        config: user => ({
+            optimizeDeps: { exclude: [packageName] },
+            worker: { plugins: () => plugin(), ...user.worker?.format === undefined ? { format: "es" as const } : {} },
+        }),
         configResolved: config => {
             serve = config.command === "serve";
-            root = config.root;
-            repeated = config.plugins.find(other => other.name === plugin.name) !== plugin;
+            worker = config.isWorker;
+            repeated = config.plugins.find(other => other.name === instance.name) !== instance;
         },
         configureServer: devServer => {
             server = devServer;
         },
+        // Vite takes a worker bundle's first chunk as the worker's entry, and the bundler orders entry chunks, a kernel's
+        // among them, by name. In a worker's bundle each kernel's chunk becomes an asset of the same file and code, which
+        // the bundler puts after every chunk, so the worker's own entry comes first.
+        generateBundle(_options, bundle) {
+            if (repeated || !worker) return;
+            for (const [fileName, item] of Object.entries(bundle)) {
+                if (item.type !== "chunk" || item.facadeModuleId === null || parseKernelId(item.facadeModuleId) === undefined) continue;
+                delete bundle[fileName];
+                this.emitFile({ type: "asset", fileName, source: item.code });
+            }
+        },
         // 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: {
@@ -188,23 +344,27 @@ export const kernelPlugin = (): Plugin => {
         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 identify = async (input: string) => {
+                const identified = await identifyModule(input, moduleIdOf(id, packageOf), parse, async (source, namespace) => {
+                    const resolved = await this.resolve(source, id);
+                    return resolved !== null && (resolved.external ? source === packageName : namespaceCopyOf(resolved.id, namespace) !== null);
+                }, nodeCopies);
+                return identified !== null && "failure" in identified ? this.error(identified.failure) : identified;
+            };
             const ssr = options?.ssr === true;
+            parseTypes ??= (await import("vite")).parseAst;
             const linker = linkerFor(ssr, this);
             const hashes: string[] = [];
-            const transformed = await transformKernels(code, id, parse, async source => {
+            const transformed = await transformKernels(code, id, parse, async (source, namespace) => {
                 const resolved = await this.resolve(source, id);
-                return resolved !== null && isSystemModule(resolved.id);
+                return resolved === null ? null : namespaceCopyOf(resolved.id, namespace);
             }, (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);
+            }, linker, automatic, moduleLabelOf(id, packageOf));
             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) {
@@ -215,9 +375,10 @@ export const kernelPlugin = (): Plugin => {
             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);
+            for (const warning of result.warnings) this.warn(warning);
             kernels.set(id, result.kernels.map((source, index) => ({ source, hash: hashes[index] ?? "" })));
             return await identify(result.code) ?? { code: result.code, map: null };
         },
     };
-    return plugin;
+    return instance;
 };

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

@@ -0,0 +1,34 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+/// <reference types="node" />
+import { posix as node } from 'node:path';
+import { expect, test } from 'vitest';
+import * as posix from './posix.js';
+
+const paths = [
+    "", "/", "//", "///", ".", "..", "a", "a/", "a/b", "/a", "/a/", "/a/b", "/a/b/", "//a", "//a/b", "a//b", "/a//b//",
+    "./a", "../a", "a/./b", "a/../b", "/a/../../b", "a/../../b", "../../a/b", "/a/b/../c/./d", "C:", "C:/", "C:/a/b",
+    "file.ts", "/x/file.d.ts", ".hidden", "/x/.hidden", "a.", "a..", "/a/b.c/d", "..b", "a.b.c", "/a/b/.", "/a/b/..",
+    "/node_modules/@adobe/ecs/dist/index.js", "guide/src/01-resources.test.ts", "/a/b?x", "a\\b",
+];
+
+test("dirname, basename, extname and isAbsolute match node's posix ones", () => {
+    for (const path of paths) {
+        expect([path, posix.dirname(path)]).toEqual([path, node.dirname(path)]);
+        expect([path, posix.basename(path)]).toEqual([path, node.basename(path)]);
+        expect([path, posix.extname(path)]).toEqual([path, node.extname(path)]);
+        expect([path, posix.isAbsolute(path)]).toEqual([path, node.isAbsolute(path)]);
+    }
+});
+
+test("resolve and relative match node's posix ones for absolute paths, and for relative ones that stay below the directory they start from", () => {
+    const absolute = paths.filter(path => path.startsWith("/"));
+    for (const from of absolute) {
+        expect([from, posix.resolve(from)]).toEqual([from, node.resolve(from)]);
+        for (const to of paths) {
+            expect([from, to, posix.resolve(from, to)]).toEqual([from, to, node.resolve(from, to)]);
+            if (to.startsWith("/")) expect([from, to, posix.relative(from, to)]).toEqual([from, to, node.relative(from, to)]);
+        }
+    }
+    const relatives = paths.filter(path => !path.startsWith("/") && !path.includes(".."));
+    for (const from of relatives) for (const to of relatives) expect([from, to, posix.relative(from, to)]).toEqual([from, to, node.relative(from, to)]);
+});

package/src/implementation/compiler/posix.ts

@@ -0,0 +1,183 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+/**
+ * The POSIX path functions the compiler uses, as node's `path.posix` gives them, with no node: so the compiler's core
+ * runs in a browser too. `resolve` and `relative` resolve a relative path from `/` where node resolves it from its
+ * working directory, which changes neither's result for relative paths that stay below where they start.
+ */
+
+const slash = 47;
+const dot = 46;
+
+/** A path's segments with `.` and `..` resolved; `..` above the start is kept when `aboveRoot` allows it. */
+const normalized = (path: string, aboveRoot: boolean): string => {
+    let result = "";
+    let lastSegmentLength = 0;
+    let lastSlash = -1;
+    let dots = 0;
+    let code = 0;
+    for (let index = 0; index <= path.length; ++index) {
+        if (index < path.length) code = path.charCodeAt(index);
+        else if (code === slash) break;
+        else code = slash;
+        if (code === slash) {
+            if (lastSlash === index - 1 || dots === 1) {
+                // An empty or `.` segment.
+            } else if (dots === 2) {
+                if (result.length < 2 || lastSegmentLength !== 2 || result.charCodeAt(result.length - 1) !== dot || result.charCodeAt(result.length - 2) !== dot) {
+                    if (result.length > 2) {
+                        const lastSlashIndex = result.lastIndexOf("/");
+                        if (lastSlashIndex === -1) {
+                            result = "";
+                            lastSegmentLength = 0;
+                        } else {
+                            result = result.slice(0, lastSlashIndex);
+                            lastSegmentLength = result.length - 1 - result.lastIndexOf("/");
+                        }
+                        lastSlash = index;
+                        dots = 0;
+                        continue;
+                    } else if (result.length !== 0) {
+                        result = "";
+                        lastSegmentLength = 0;
+                        lastSlash = index;
+                        dots = 0;
+                        continue;
+                    }
+                }
+                if (aboveRoot) {
+                    result += result.length > 0 ? "/.." : "..";
+                    lastSegmentLength = 2;
+                }
+            } else {
+                result += result.length > 0 ? `/${path.slice(lastSlash + 1, index)}` : path.slice(lastSlash + 1, index);
+                lastSegmentLength = index - lastSlash - 1;
+            }
+            lastSlash = index;
+            dots = 0;
+        } else if (code === dot && dots !== -1) {
+            ++dots;
+        } else {
+            dots = -1;
+        }
+    }
+    return result;
+};
+
+export const isAbsolute = (path: string): boolean => path.length > 0 && path.charCodeAt(0) === slash;
+
+/** The absolute path `paths` resolve to, from right to left, from `/` when none of them is absolute. */
+export const resolve = (...paths: readonly string[]): string => {
+    let resolved = "";
+    let absolute = false;
+    for (let index = paths.length - 1; index >= -1 && !absolute; index--) {
+        const path = index >= 0 ? paths[index] ?? "" : "/";
+        if (path.length === 0) continue;
+        resolved = `${path}/${resolved}`;
+        absolute = path.charCodeAt(0) === slash;
+    }
+    resolved = normalized(resolved, !absolute);
+    if (absolute) return `/${resolved}`;
+    return resolved.length > 0 ? resolved : ".";
+};
+
+/** The path from `from` to `to`. */
+export const relative = (from: string, to: string): string => {
+    if (from === to) return "";
+    const source = resolve(from);
+    const target = resolve(to);
+    if (source === target) return "";
+    const sourceLength = source.length - 1;
+    const targetLength = target.length - 1;
+    const length = sourceLength < targetLength ? sourceLength : targetLength;
+    let lastCommonSlash = -1;
+    let index = 0;
+    for (; index < length; index++) {
+        const code = source.charCodeAt(1 + index);
+        if (code !== target.charCodeAt(1 + index)) break;
+        else if (code === slash) lastCommonSlash = index;
+    }
+    if (index === length) {
+        if (targetLength > length) {
+            if (target.charCodeAt(1 + index) === slash) return target.slice(1 + index + 1);
+            if (index === 0) return target.slice(1 + index);
+        } else if (sourceLength > length) {
+            if (source.charCodeAt(1 + index) === slash) lastCommonSlash = index;
+            else if (index === 0) lastCommonSlash = 0;
+        }
+    }
+    let up = "";
+    for (index = 1 + lastCommonSlash + 1; index <= source.length; ++index) {
+        if (index === source.length || source.charCodeAt(index) === slash) up += up.length === 0 ? ".." : "/..";
+    }
+    return `${up}${target.slice(1 + lastCommonSlash)}`;
+};
+
+export const dirname = (path: string): string => {
+    if (path.length === 0) return ".";
+    const rooted = path.charCodeAt(0) === slash;
+    let end = -1;
+    let matchedSlash = true;
+    for (let index = path.length - 1; index >= 1; --index) {
+        if (path.charCodeAt(index) === slash) {
+            if (!matchedSlash) {
+                end = index;
+                break;
+            }
+        } else {
+            matchedSlash = false;
+        }
+    }
+    if (end === -1) return rooted ? "/" : ".";
+    if (rooted && end === 1) return "//";
+    return path.slice(0, end);
+};
+
+export const basename = (path: string): string => {
+    let start = 0;
+    let end = -1;
+    let matchedSlash = true;
+    for (let index = path.length - 1; index >= 0; --index) {
+        if (path.charCodeAt(index) === slash) {
+            if (!matchedSlash) {
+                start = index + 1;
+                break;
+            }
+        } else if (end === -1) {
+            matchedSlash = false;
+            end = index + 1;
+        }
+    }
+    return end === -1 ? "" : path.slice(start, end);
+};
+
+export const extname = (path: string): string => {
+    let startDot = -1;
+    let startPart = 0;
+    let end = -1;
+    let matchedSlash = true;
+    // What comes before the last dot in its segment, read leftward: 0 nothing yet, 1 a dot last, -1 another character last.
+    let beforeDot = 0;
+    for (let index = path.length - 1; index >= 0; --index) {
+        const code = path.charCodeAt(index);
+        if (code === slash) {
+            if (!matchedSlash) {
+                startPart = index + 1;
+                break;
+            }
+            continue;
+        }
+        if (end === -1) {
+            matchedSlash = false;
+            end = index + 1;
+        }
+        if (code === dot) {
+            if (startDot === -1) startDot = index;
+            else if (beforeDot !== 1) beforeDot = 1;
+        } else if (startDot !== -1) {
+            beforeDot = -1;
+        }
+    }
+    if (startDot === -1 || end === -1 || beforeDot === 0 || (beforeDot === 1 && startDot === end - 1 && startDot === startPart + 1)) return "";
+    return path.slice(startDot, end);
+};

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

@@ -0,0 +1,90 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { describe, expect, test } from 'vitest';
+import { parseAst } from 'vite';
+import { transformKernels } from './transform.js';
+import { createLinker } from './link.js';
+import { nodeCopies, ownCopy } from './paths.js';
+import { estreeOf } from './estree.js';
+
+const parse = (code: string) => estreeOf(parseAst(code));
+
+const header = `import { System, Vec2 } from "ecs";
+import { near, drift } from "./helpers.js";
+const cell = Symbol();
+const value = Symbol();
+const camera = Symbol();
+const range = 3;
+`;
+
+/** Modules besides the one transformed. */
+const files: { readonly [file: string]: string } = {
+    "/helpers.js": `const limit = 2;\nexport const near = (x, y) => Math.abs(x - y) <= limit;\nlet offset = 0;\nexport const drift = x => x + offset;\n`,
+};
+
+const transform = (source: string) => transformKernels(`${header}${source}`, "/test.js", parse, async specifier => specifier === "ecs" ? ownCopy : null, index => JSON.stringify(`kernel:${index}`), createLinker({
+    packages: nodeCopies,
+    resolve: async (specifier, importer) => {
+        if (specifier === "ecs") return ownCopy.index;
+        if (specifier === "./helpers.js" && importer === "/test.js") return "/helpers.js";
+        if (!specifier.startsWith(".")) return { error: `${specifier} can't be resolved` };
+        const path = resolve(dirname(importer), specifier);
+        const typescript = path.replace(/\.js$/, ".ts");
+        return existsSync(typescript) ? typescript : path;
+    },
+    load: async file => {
+        const code = files[file] ?? await readFile(file, "utf8");
+        if (!file.endsWith(".ts")) return { code };
+        const { transformWithOxc } = await import("vite");
+        return { code: (await transformWithOxc(code, file, { lang: "ts" })).code };
+    },
+}, parse));
+
+/** What the build gives a system's declaration, or why it fails. */
+const built = async (where: string, wrap = (system: string): string => `export const visible = ${system};`): Promise<string> => {
+    const result = await transform(wrap(`System.create({ kernel: false, components: { with: [value], where: { [cell]: ${where} } } }, row => { void row[value]; })`));
+    if (result === null) return "untransformed";
+    return "failure" in result ? result.failure.message : result.code;
+};
+
+describe("where predicates", () => {
+    test("read their value, resources, literals, module constants and pure functions, which the build infers the resources of", async () => {
+        expect(await built(`(at, { resources }) => near(at[0], resources[camera].x) && Math.abs(at[1]) < range`)).toContain(`where: [camera]`);
+        expect(await built(`([x, y]) => Vec2.length([x, y]) < range`)).toContain(`where: []`);
+        expect(await built(`function (at, context) { const { resources } = context; return at[0] < resources[camera].x; }`)).toContain(`where: [camera]`);
+    });
+    test("fail the build where they read what may change outside the world", async () => {
+        expect(await built(`at => at[0] < limit`, system => `let limit = 2;\nexport const visible = ${system};`)).toContain("a where predicate reads limit, a module variable that may change");
+        expect(await built(`at => at[0] < bounds.x`, system => `const bounds = { x: 2 };\nexport const visible = ${system};`)).toContain("a where predicate reads bounds, which holds values that may change");
+        expect(await built(`at => at[0] < window.innerWidth`)).toContain("a where predicate reads the global window, which may change");
+        expect(await built(`at => at[0] < width`, system => `export const make = (width) => ${system.replace("export const visible = ", "")};`)).toContain("a where predicate reads width, which a function around it declares and may change");
+        expect(await built(`at => drift(at[0]) < range`)).toContain("a where predicate reads offset, a module variable that may change");
+        expect(await built(`(at, { resources }) => { resources[camera] = at; return true; }`)).toContain("a where predicate writes through resources, which it only reads");
+    });
+    const holes: readonly { readonly what: string; readonly where: string; readonly wrap?: (system: string) => string; readonly fails: string }[] = [
+        { what: "Math.random", where: "at => at[0] < Math.random()", fails: "a where predicate reads Math.random, which isn't pure" },
+        { what: "Math.random by another name", where: "at => { const draw = Math.random; return at[0] < draw(); }", fails: "a where predicate reads Math.random, which isn't pure" },
+        { what: "assigning into its value", where: "at => { at[0] = 1; return true; }", fails: "a where predicate writes through at, which it only reads" },
+        { what: "sorting its value", where: "at => { at.sort(); return true; }", fails: "a where predicate calls at.sort, which may change what it reads" },
+        { what: "setting a resource's value", where: "(at, { resources }) => { resources[camera].set(at); return true; }", fails: "a where predicate calls resources[camera].set, which may change what it reads" },
+        { what: "assigning a global's member", where: "at => { Math.PI = 3; return at[0] < 1; }", fails: "a where predicate writes through Math, which it only reads" },
+        { what: "assigning through a global's prototype", where: "at => { Number.prototype.x = 1; return at[0] < 1; }", fails: "a where predicate writes through Number, which it only reads" },
+        { what: "counting on a function object", where: "at => { count.n++; return at[0] < 1; }", wrap: system => `function count() {}\nexport const visible = ${system};`, fails: "a where predicate writes through count, which it only reads" },
+        { what: "importing a module", where: `at => { void import("./helpers.js"); return at[0] < 1; }`, fails: "a where predicate imports a module, which may run anything" },
+        { what: "deleting from its value", where: "at => { delete at.x; return true; }", fails: "a where predicate writes through at, which it only reads" },
+        { what: "a helper assigning into what it's given", where: "at => bump(at)", wrap: system => `const bump = values => { values[0] = 1; return true; };\nexport const visible = ${system};`, fails: "a where predicate writes through values, which it only reads" },
+    ];
+    for (const { what, where, wrap, fails } of holes) {
+        test(`fail the build on ${what}`, async () => {
+            expect(await built(where, wrap)).toContain(fails);
+        });
+    }
+    test("may change what they make of their own, and call the pure members of Math and Number and any other method that doesn't change what it's called on", async () => {
+        expect(await built(`at => { const own = [at[0], at[1]]; own.sort(); own[0] = Math.max(own[0], Number.parseFloat("1")); let n = 0; n++; return own[0] + n < Math.PI; }`)).toContain(`where: []`);
+        expect(await built(`at => at.map(x => x * 2).includes(4)`)).toContain(`where: []`);
+        // A function a resource holds, which the world calls as written.
+        expect(await built(`(at, { resources }) => resources[camera].sees(at)`)).toContain(`where: [camera]`);
+    });
+});