@akanjs/devkit 3.0.0-beta.9 → 3.0.0

package/frontendBuild/csrDevArtifactWriter.ts

@@ -0,0 +1,307 @@
+import fs from "node:fs";
+import { mkdir, readdir, rm } from "node:fs/promises";
+import path from "node:path";
+import {
+  appGenerationOf,
+  CSR_DEV_APP_FILE,
+  CSR_DEV_KEPT_PATCHES,
+  CSR_DEV_MANIFEST_FILE,
+  CSR_DEV_PATCHING_MARKER,
+  type CsrDevLayout,
+  type CsrDevManifest,
+  csrDevModuleFile,
+} from "akanjs/server/hmr/csrDevManifest";
+import { FileSys } from "../fileSys";
+import { CsrDevPaths } from "./csrDevPaths";
+import type { CsrDevCode, CsrDevCompiledModule, CsrDevGraph } from "./csrDevTypes";
+
+export interface CsrDevArtifactWriterOptions {
+  /** Where the dev server serves `outDir`; a patch is announced by its URL. */
+  routePrefix: string;
+  /** `app.js` starts no entry: an SSR page requires the modules its RSC payload names, one at a time. */
+  library?: boolean;
+}
+
+export class CsrDevArtifactWriter {
+  static readonly #keptVendors = 3;
+  static readonly #buildingMarker = ".building";
+  readonly #outDir: string;
+  readonly #routePrefix: string;
+  readonly #library: boolean;
+
+  constructor(outDir: string, { routePrefix, library = false }: CsrDevArtifactWriterOptions) {
+    this.#outDir = outDir;
+    this.#routePrefix = routePrefix;
+    this.#library = library;
+  }
+
+  //? Set between a whole build's first write and its last: module files are named by id and overwritten in place, so a
+  //? build cut short there leaves new modules under the previous graph and app.js, which no patch may read.
+  async markBuilding(): Promise<void> {
+    await Bun.write(path.join(this.#outDir, CsrDevArtifactWriter.#buildingMarker), String(process.pid));
+  }
+
+  async clearBuilding(): Promise<void> {
+    await CsrDevArtifactWriter.#remove(path.join(this.#outDir, CsrDevArtifactWriter.#buildingMarker));
+  }
+
+  async isBuilding(): Promise<boolean> {
+    return await Bun.file(path.join(this.#outDir, CsrDevArtifactWriter.#buildingMarker)).exists();
+  }
+
+  //? A reload's generation has no patch: one an attempt cut short left under that number would be applied by a tab
+  //? catching up (catchUp reloads only when the file is missing).
+  async forgetPatch(generation: number): Promise<void> {
+    await Promise.all(
+      [`patch-${generation}.js`, `patch-${generation}.js.layout.json`].map((name) =>
+        CsrDevArtifactWriter.#remove(path.join(this.#outDir, name)),
+      ),
+    );
+  }
+
+  async readJson<T>(name: string): Promise<T | null> {
+    const file = Bun.file(path.join(this.#outDir, name));
+    if (!(await file.exists())) return null;
+    return (await file.json().catch(() => null)) as T | null;
+  }
+
+  async writeJson(name: string, value: unknown): Promise<void> {
+    await this.#writeAtomic(name, JSON.stringify(value));
+  }
+
+  async writeModules(compiled: CsrDevCompiledModule[]): Promise<void> {
+    await mkdir(path.join(this.#outDir, "modules"), { recursive: true });
+    const helpers = new Map(
+      compiled.flatMap((module) => (module.helpers ? [[module.helpers.hash, module.helpers]] : [])),
+    );
+    await Promise.all([
+      ...compiled.flatMap((module) => [
+        Bun.write(this.#modulePath(module.id, ".js"), module.factory),
+        ...(module.sourceMap ? [Bun.write(this.#modulePath(module.id, ".js.map"), module.sourceMap)] : []),
+      ]),
+      ...[...helpers.values()].map((shared) => Bun.write(this.#helpersPath(shared.hash), shared.definition)),
+    ]);
+  }
+
+  //? A module whose file is missing is left out rather than failing the read: the patcher compiles it again.
+  async readCode(graph: CsrDevGraph): Promise<CsrDevCode> {
+    const ids = Object.keys(graph.modules).filter((id) => !graph.modules[id]?.vendor && this.hasModule(id));
+    const hashes = [...new Set(ids.flatMap((id) => graph.modules[id]?.helpers ?? []))];
+    const [modules, helpers] = await Promise.all([
+      Promise.all(ids.map(async (id) => [id, await Bun.file(this.#modulePath(id, ".js")).text()] as const)),
+      Promise.all(hashes.map(async (hash) => [hash, await Bun.file(this.#helpersPath(hash)).text()] as const)),
+    ]);
+    return { modules: new Map(modules), helpers: new Map(helpers) };
+  }
+
+  hasModule(id: string): boolean {
+    return fs.existsSync(this.#modulePath(id, ".js"));
+  }
+
+  async forgetModules(ids: string[]): Promise<void> {
+    await Promise.all(
+      ids.flatMap((id) => [
+        CsrDevArtifactWriter.#remove(this.#modulePath(id, ".js")),
+        CsrDevArtifactWriter.#remove(this.#modulePath(id, ".js.map")),
+      ]),
+    );
+  }
+
+  async writeVendor(graph: CsrDevGraph): Promise<string> {
+    const ids = Object.keys(graph.modules)
+      .filter((id) => graph.modules[id]?.vendor)
+      .sort();
+    const stubs = new Set(Object.values(graph.modules).flatMap((module) => module.deps.filter(CsrDevPaths.isStub)));
+    const lines = [await this.#helperDefinitions(graph, ids), ...(await this.#defineLines(ids))];
+    for (const stub of [...stubs].sort()) {
+      if (stub.startsWith(CsrDevPaths.emptyStubPrefix)) {
+        lines.push(`__akan.define(${JSON.stringify(stub)}, function () {});\n`);
+        continue;
+      }
+      const message = `[akan-csr] ${stub.slice(CsrDevPaths.stubPrefix.length)} is a Node built-in the browser does not have`;
+      lines.push(
+        `__akan.define(${JSON.stringify(stub)}, function () {\n  throw new Error(${JSON.stringify(message)});\n});\n`,
+      );
+    }
+    const code = lines.join("");
+    const vendorFile = `vendor-${Bun.hash(code).toString(36)}.js`;
+    await this.#writeAtomic(vendorFile, code);
+    return vendorFile;
+  }
+
+  //? A library app.js names the vendor file and epoch it was built with: a tab that booted it beside another build's
+  //? vendor file (a whole build landing between its render and its load) tells, and keeps the right epoch for hello.
+  async writeApp(
+    graph: CsrDevGraph,
+    { generation, vendorFile, epoch }: Pick<CsrDevManifest, "generation" | "vendorFile" | "epoch">,
+    code?: CsrDevCode,
+  ): Promise<void> {
+    const ids = Object.keys(graph.modules)
+      .filter((id) => !graph.modules[id]?.vendor)
+      .sort();
+    const lines = await this.#defineLines(ids, code);
+    const blocks = ids.map((id, index) => [id, lines[index] ?? ""] as [string, string]);
+    const start = this.#library
+      ? `__akan.startLibrary(${JSON.stringify({ generation, refresh: graph.refresh, bootstrap: graph.entries[""], vendorFile, epoch })});\n`
+      : `__akan.start(${JSON.stringify({ generation, refresh: graph.refresh })});\n`;
+    await this.#writeWithSourceMap(CSR_DEV_APP_FILE, await this.#helperDefinitions(graph, ids, code), blocks, start);
+  }
+
+  async writePatch(generation: number, modules: CsrDevCompiledModule[]): Promise<string> {
+    const patchFile = `patch-${generation}.js`;
+    const blocks = modules.map(
+      (module, index) =>
+        [module.id, `${JSON.stringify(module.id)}: ${module.factory}${index < modules.length - 1 ? ",\n" : "\n"}`] as [
+          string,
+          string,
+        ],
+    );
+    const helpers = new Map(
+      modules.flatMap((module) => (module.helpers ? [[module.helpers.hash, module.helpers]] : [])),
+    );
+    const header = `${[...helpers.values()].map((shared) => shared.definition).join("")}__akan.update(${generation}, {\n`;
+    await this.#writeWithSourceMap(patchFile, header, blocks, "});\n");
+    return `${this.#routePrefix}${patchFile}`;
+  }
+
+  // The manifest goes last: the server renders shells from it, so it must never name a file not yet written.
+  async writeState(graph: CsrDevGraph, manifest: CsrDevManifest): Promise<void> {
+    await this.writeJson("graph.json", graph);
+    await this.writeJson(CSR_DEV_MANIFEST_FILE, manifest);
+  }
+
+  //? The open tabs need only the patch file and the manifest naming it, so they hear of a patch before the rest lands:
+  //? the module files and graph.json (read only by the next build), then app.js (a full rewrite). The manifest says
+  //? which generation app.js holds, and the shell holds a tab booting in that gap until it does. A crash in the gap is
+  //? recovered by the next build, which sees the edited files' mtimes differ from graph.json and compiles them again.
+  async commitPatch(
+    graph: CsrDevGraph,
+    manifest: CsrDevManifest,
+    announce: () => void,
+    { modules, code }: { modules: CsrDevCompiledModule[]; code?: CsrDevCode },
+  ): Promise<void> {
+    await this.writeJson(CSR_DEV_MANIFEST_FILE, manifest);
+    announce();
+    await CsrDevArtifactWriter.#appWriteDelay();
+    await this.writeModules(modules);
+    await this.writeJson("graph.json", graph);
+    await this.writeApp(graph, manifest, code);
+    await this.writeJson(CSR_DEV_MANIFEST_FILE, { ...manifest, appGeneration: manifest.generation });
+  }
+
+  // A process that died between announcing a patch and rewriting app.js left every booting tab one generation behind.
+  async healApp(graph: CsrDevGraph, manifest: CsrDevManifest, code?: CsrDevCode): Promise<CsrDevManifest> {
+    if (appGenerationOf(manifest) >= manifest.generation) return manifest;
+    await this.writeApp(graph, manifest, code);
+    const healed = { ...manifest, appGeneration: manifest.generation };
+    await this.writeJson(CSR_DEV_MANIFEST_FILE, healed);
+    return healed;
+  }
+
+  async prune(vendorFile: string, generation: number): Promise<void> {
+    const names = await readdir(this.#outDir);
+    const stale = names.filter((name) => {
+      const patch = /^patch-(\d+)\.js(?:\.layout\.json)?$/.exec(name);
+      return patch ? Number(patch[1]) <= generation - CSR_DEV_KEPT_PATCHES : false;
+    });
+    const vendors = names
+      .filter((name) => /^vendor-[\w-]+\.js$/.test(name) && name !== vendorFile)
+      .map((name) => ({ name, mtimeMs: CsrDevPaths.mtimeOf(path.join(this.#outDir, name)) }))
+      .sort((a, b) => b.mtimeMs - a.mtimeMs)
+      .slice(CsrDevArtifactWriter.#keptVendors - 1)
+      .map(({ name }) => name);
+    await Promise.all(
+      [...stale, ...vendors].map((name) => CsrDevArtifactWriter.#remove(path.join(this.#outDir, name))),
+    );
+  }
+
+  //? A whole build writes over the registry before it instead of clearing it first, so it clears what that one left:
+  //? the modules and helpers it no longer holds, every patch (each was made against the previous registry), the assets
+  //? this build did not write (by path: a file's mtime and this process's clock need not agree on a mounted volume),
+  //? temp files of a write cut short, and the marker of a builder that died mid-patch.
+  async pruneAfterFullBuild(
+    graph: CsrDevGraph,
+    vendorFile: string,
+    { generation, assets }: { generation: number; assets: string[] },
+  ): Promise<void> {
+    const kept = new Set(
+      Object.keys(graph.modules).flatMap((id) => [this.#modulePath(id, ".js"), this.#modulePath(id, ".js.map")]),
+    );
+    for (const module of Object.values(graph.modules)) if (module.helpers) kept.add(this.#helpersPath(module.helpers));
+    for (const asset of assets) kept.add(path.resolve(asset));
+    const listed = async (dir: string) =>
+      (await readdir(path.join(this.#outDir, dir)).catch(() => [] as string[])).map((name) =>
+        path.join(this.#outDir, dir, name),
+      );
+    const stale = [
+      ...(await listed("modules")).filter((file) => !kept.has(file)),
+      ...(await listed("assets")).filter((file) => !kept.has(file)),
+      ...(await listed(".")).filter((file) => {
+        const name = path.basename(file);
+        return /^patch-\d+\.js(?:\.layout\.json)?$/.test(name) || name.endsWith(".tmp");
+      }),
+      path.join(this.#outDir, CSR_DEV_PATCHING_MARKER),
+    ];
+    await Promise.all(stale.map((file) => CsrDevArtifactWriter.#remove(file)));
+    await this.prune(vendorFile, generation);
+  }
+
+  async #helperDefinitions(graph: CsrDevGraph, ids: string[], code?: CsrDevCode): Promise<string> {
+    const hashes = [...new Set(ids.flatMap((id) => graph.modules[id]?.helpers ?? []))].sort();
+    return (
+      await Promise.all(hashes.map(async (hash) => code?.helpers.get(hash) ?? Bun.file(this.#helpersPath(hash)).text()))
+    ).join("");
+  }
+
+  async #defineLines(ids: string[], code?: CsrDevCode): Promise<string[]> {
+    return await Promise.all(
+      ids.map(async (id) => {
+        const factory = code?.modules.get(id) ?? (await Bun.file(this.#modulePath(id, ".js")).text());
+        return `__akan.define(${JSON.stringify(id)}, ${factory});\n`;
+      }),
+    );
+  }
+
+  //? A factory's code starts on the line after its header, so each module's map is placed one line below it.
+  async #writeWithSourceMap(name: string, header: string, blocks: [id: string, text: string][], footer: string) {
+    const layout: CsrDevLayout = { lineCount: 0, modules: [] };
+    let line = CsrDevPaths.lineCount(header);
+    for (const [id, text] of blocks) {
+      layout.modules.push([id, line + 1]);
+      line += CsrDevPaths.lineCount(text);
+    }
+    const code = `${header}${blocks.map(([, text]) => text).join("")}${footer}//# sourceMappingURL=${name}.map\n`;
+    layout.lineCount = CsrDevPaths.lineCount(code);
+    await this.writeJson(`${name}.layout.json`, layout);
+    await this.#writeAtomic(name, code);
+  }
+
+  // A rename is atomic: the dev server may be streaming the previous app.js to a reloading page right now.
+  async #writeAtomic(name: string, content: string): Promise<void> {
+    const target = path.join(this.#outDir, name);
+    const temp = `${target}.${process.pid}.tmp`;
+    await Bun.write(temp, content);
+    await FileSys.replace(temp, target);
+  }
+
+  //? Best effort, after the tabs already have the update: Windows refuses to delete a file a reader holds open (the
+  //? server streaming it to a tab), and throwing here would send a patch that already went out to a build worker.
+  //? A file that stays is removed by a later prune.
+  static async #remove(file: string): Promise<void> {
+    await rm(file, { force: true }).catch(() => undefined);
+  }
+
+  //? A test-only hook that widens the gap between the patch and app.js, so an E2E can boot a tab inside it.
+  static async #appWriteDelay(): Promise<void> {
+    const ms = Number(process.env.AKAN_CSR_DEV_APP_WRITE_DELAY_MS);
+    if (Number.isInteger(ms) && ms > 0) await Bun.sleep(ms);
+  }
+
+  #modulePath(id: string, extension: ".js" | ".js.map"): string {
+    return path.join(this.#outDir, csrDevModuleFile(id, extension));
+  }
+
+  #helpersPath(hash: string): string {
+    return path.join(this.#outDir, "modules", `helpers-${hash}.js`);
+  }
+}

package/frontendBuild/csrDevBundler.test.ts

@@ -0,0 +1,66 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { mkdtemp, rm } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+//* Pins the Bun behaviour CsrDevBundler is built on, so a Bun upgrade that changes it fails here, not in a browser.
+describe("Bun output the CSR registry bundle relies on", () => {
+  let dir: string;
+  const externalizeAll = {
+    name: "externalize-all",
+    setup(build: Bun.PluginBuilder) {
+      build.onResolve({ filter: /.*/ }, (args) =>
+        args.kind === "entry-point-build" ? undefined : { path: `akan-module:${args.path}`, external: true },
+      );
+    },
+  };
+
+  beforeAll(async () => {
+    dir = await mkdtemp(path.join(os.tmpdir(), "akan-csr-dev-bundler-"));
+    await Bun.write(path.join(dir, "a.ts"), "export const a = 1;\n");
+    await Bun.write(
+      path.join(dir, "entry.ts"),
+      'import value from "./a";\nexport * from "./a";\nexport const lazy = () => import("./a");\nconsole.log(value);\n',
+    );
+  });
+
+  afterAll(async () => {
+    await rm(dir, { recursive: true, force: true });
+  });
+
+  const build = async (entrypoints: string[]) =>
+    await Bun.build({
+      entrypoints: entrypoints.map((file) => path.join(dir, file)),
+      root: dir,
+      target: "browser",
+      format: "cjs",
+      naming: { entry: "[dir]/[name].[ext]" },
+      plugins: [externalizeAll],
+    });
+
+  test("the CJS helpers keep the shapes CsrDevBundler rewrites", async () => {
+    const [output] = (await build(["entry.ts"])).outputs;
+    const code = (await output?.text()) ?? "";
+    expect(code).toContain("var __toESM = (mod, isNodeMode, target) => {");
+    expect(code).toContain("var __reExport = (target, mod, secondTarget) => {");
+    expect(code).toContain('require("akan-module:./a")');
+    expect(code).toContain('import("akan-module:./a")');
+  });
+
+  test("the helper preamble ends at the first path comment and names no factory argument", async () => {
+    const [output] = (await build(["entry.ts"])).outputs;
+    const code = (await output?.text()) ?? "";
+    const marker = code.search(/^\/\/ /m);
+    expect(marker).toBeGreaterThan(0);
+    const preamble = code.slice(0, marker);
+    expect(preamble).toMatch(/^var __toESM = /m);
+    expect(preamble).not.toMatch(/(?<![\w$.])(?:require|module|exports)(?![\w$]|\s*:)/);
+  });
+
+  test("a relative import of another entrypoint in the same build stays external", async () => {
+    const outputs = (await build(["entry.ts", "a.ts"])).outputs;
+    const entry = await outputs.find((output) => output.path.includes("entry"))?.text();
+    expect(entry).toContain('require("akan-module:./a")');
+    expect(entry).not.toContain("var a = 1");
+  });
+});

package/frontendBuild/csrDevBundler.ts

@@ -0,0 +1,95 @@
+import { mkdir } from "node:fs/promises";
+import path from "node:path";
+import { CSR_DEV_DIRNAME, CSR_DEV_ROUTE_PREFIX } from "akanjs/server/hmr/csrDevManifest";
+import { resolveSsrPageEntriesForApp } from "../artifact/implicitRootLayout";
+import type { App } from "../commandDecorators";
+import { AsyncDefaultExportDetector } from "../transforms/asyncDefaultExportDetector";
+import { bundleDefine } from "./bundleDefine";
+import { CsrDevPaths } from "./csrDevPaths";
+import type { CsrDevContext } from "./csrDevTypes";
+import { CsrEntryFiles } from "./csrEntryFiles";
+import { DevRegistryBundler } from "./devRegistryBundler";
+import { PagesEntrySourceGenerator } from "./pagesEntrySourceGenerator";
+
+//* Dev-only CSR as a module registry, under `.akan/artifact/csr-dev`: one entry per basePath boots every page.
+export class CsrDevBundler extends DevRegistryBundler {
+  static readonly #formatVersion = 4;
+  readonly reloadsOnEntryChange = true;
+  //? Detecting a page's async default parses it with TypeScript: on apps/akan every page each save cost ~100ms.
+  readonly #asyncDefaults = new Map<string, { mtimeMs: number; detected: Promise<boolean> }>();
+
+  constructor(app: App) {
+    super(app, { dirName: CSR_DEV_DIRNAME, routePrefix: CSR_DEV_ROUTE_PREFIX, library: false });
+  }
+
+  async context(): Promise<CsrDevContext | null> {
+    const akanConfig = await this.app.getConfig();
+    const pageEntries = await resolveSsrPageEntriesForApp(this.app, await this.app.getPageKeys());
+    if (pageEntries.length === 0) return null;
+    const basePaths = [...akanConfig.basePaths];
+    const htmlBasePaths = basePaths.length > 0 ? basePaths : [""];
+    const define = bundleDefine(this.app, "start", "csr");
+    const optimizeImports = [...akanConfig.optimizeImports];
+    const configKey = Bun.hash(
+      JSON.stringify([CsrDevBundler.#formatVersion, Bun.version, define, optimizeImports, htmlBasePaths]),
+    ).toString(36);
+    return {
+      pageEntries,
+      basePaths,
+      htmlBasePaths,
+      define,
+      optimizeImports,
+      configKey,
+      refreshFile: this.#resolveRefreshRuntime(),
+    };
+  }
+
+  async writeEntries(context: CsrDevContext): Promise<{ files: Record<string, string>; changed: string[] }> {
+    await mkdir(this.entryDir, { recursive: true });
+    const files: Record<string, string> = {};
+    const changed: string[] = [];
+    for (const basePath of context.htmlBasePaths) {
+      const file = path.join(this.entryDir, CsrEntryFiles.entryFilename(basePath));
+      const entryPages = CsrEntryFiles.pageEntriesForBasePath(context.pageEntries, basePath, context.basePaths);
+      const generator = new PagesEntrySourceGenerator(entryPages, {
+        isAsyncDefault: (moduleAbsPath) => this.#isAsyncDefault(moduleAbsPath),
+      });
+      const pages = await generator.generateStatic({ fromDir: this.entryDir });
+      const hot = await generator.generateHotReplace({
+        fromDir: this.entryDir,
+        ownerId: this.paths.idOf(file),
+        moduleIds: entryPages.map(({ moduleAbsPath }) => this.paths.idOf(moduleAbsPath)),
+      });
+      const source = `import * as akanWebkit from "akanjs/webkit";\n${pages}\nvoid akanWebkit.bootCsr(pages);\n${hot}`;
+      const unchanged = (await Bun.file(file).exists()) && (await Bun.file(file).text()) === source;
+      if (!unchanged) await Bun.write(file, source);
+      const entryFile = CsrDevPaths.realpath(file);
+      files[basePath] = entryFile;
+      if (!unchanged) changed.push(entryFile);
+    }
+    return { files, changed };
+  }
+
+  protected async rootFiles(entryFiles: string[]): Promise<string[]> {
+    return entryFiles;
+  }
+
+  #isAsyncDefault(moduleAbsPath: string): Promise<boolean> {
+    const mtimeMs = CsrDevPaths.mtimeOf(moduleAbsPath);
+    const cached = this.#asyncDefaults.get(moduleAbsPath);
+    if (cached?.mtimeMs === mtimeMs) return cached.detected;
+    const detected = AsyncDefaultExportDetector.detect(moduleAbsPath);
+    this.#asyncDefaults.set(moduleAbsPath, { mtimeMs, detected });
+    return detected;
+  }
+
+  #resolveRefreshRuntime(): string {
+    const akanWebkit = CsrDevPaths.tryResolve("akanjs/webkit", this.app.cwdPath);
+    const bases = [this.app.cwdPath, this.paths.root, ...(akanWebkit ? [path.dirname(path.dirname(akanWebkit))] : [])];
+    for (const base of bases) {
+      const resolved = CsrDevPaths.tryResolve("react-refresh/runtime", base);
+      if (resolved) return CsrDevPaths.realpath(resolved);
+    }
+    throw new Error(`[csr-dev] react-refresh/runtime is not resolvable from ${bases.join(", ")}`);
+  }
+}

package/frontendBuild/csrDevFactoryCheck.test.ts

@@ -0,0 +1,33 @@
+import { describe, expect, test } from "bun:test";
+import { CsrDevFactoryCheck } from "./csrDevFactoryCheck";
+
+const factoryOf = (body: string) =>
+  `function (require, module, exports, $RefreshReg$, $RefreshSig$, __akanImport) {\n${body}\n}`;
+
+describe("CsrDevFactoryCheck", () => {
+  test("a factory that parses as a classic script has no problem, twice over", () => {
+    const factory = factoryOf('var a = require("akan-module:x");\nmodule.exports = { a, label: "import.meta" };');
+    expect(CsrDevFactoryCheck.problemOf(factory)).toBeNull();
+    expect(CsrDevFactoryCheck.problemOf(factory)).toBeNull();
+  });
+
+  test("an import.meta left in a factory is named with its compiled line", () => {
+    const problem = CsrDevFactoryCheck.problemOf(factoryOf("var a = 1;\nvar url = import.meta.url;"));
+    expect(problem).toStartWith("import.meta is left in it (compiled line 2), which a classic script cannot hold");
+  });
+
+  test("a top-level await left in a factory is named as one", () => {
+    const problem = CsrDevFactoryCheck.problemOf(factoryOf("var a = await Promise.resolve(1);"));
+    expect(problem).toStartWith("a top-level await is left in it, which a CommonJS factory cannot wait on");
+  });
+
+  test("any other syntax error answers the parser's message, and a broken helper preamble counts too", () => {
+    expect(CsrDevFactoryCheck.problemOf(factoryOf("var = ;"))).toBeString();
+    expect(CsrDevFactoryCheck.problemOf(factoryOf("module.exports = 1;"), "var { a } = ;\n")).toBeString();
+  });
+
+  test("the stand-in for a module left out throws its id and the reason", () => {
+    const thrower = new Function(`return (${CsrDevFactoryCheck.thrower("node_modules/x/index.js", "why")});`)();
+    expect(() => thrower()).toThrow("[akan-csr] node_modules/x/index.js was left out of the dev registry: why");
+  });
+});

package/frontendBuild/csrDevFactoryCheck.ts

@@ -0,0 +1,39 @@
+//* A module factory runs inside one classic script with every module written beside it, so a factory that does not
+//* parse as a script drops them all, far from the cause. Each is parsed once, as the page will, before it is written.
+export class CsrDevFactoryCheck {
+  static readonly #parsed = new Set<number | bigint>();
+
+  /** Why the page could not parse `factory` after `helperDefinition`, or null when it can. */
+  static problemOf(factory: string, helperDefinition = ""): string | null {
+    const key = Bun.hash(`${helperDefinition}\0${factory}`);
+    if (CsrDevFactoryCheck.#parsed.has(key)) return null;
+    const problem = CsrDevFactoryCheck.#syntaxError(`${helperDefinition}return (${factory});`);
+    if (problem === null) {
+      CsrDevFactoryCheck.#parsed.add(key);
+      return null;
+    }
+    if (problem.includes("import.meta")) {
+      //? JSC's own line is the caller's, not the factory's; the factory's line N is line N of Bun's output.
+      const line = factory.split("\n").findIndex((text) => /(?<![\w$.])import\.meta\b/.test(text));
+      return `import.meta is left in it${line > 0 ? ` (compiled line ${line})` : ""}, which a classic script cannot hold: ${problem}`;
+    }
+    if (CsrDevFactoryCheck.#syntaxError(`${helperDefinition}return (async ${factory});`) === null)
+      return `a top-level await is left in it, which a CommonJS factory cannot wait on: ${problem}`;
+    return problem;
+  }
+
+  /** Stands in for a module left out of the registry: the page runs, and requiring the module says why. */
+  static thrower(id: string, problem: string): string {
+    const message = `[akan-csr] ${id} was left out of the dev registry: ${problem}`;
+    return `function () {\n  throw new Error(${JSON.stringify(message)});\n}`;
+  }
+
+  static #syntaxError(source: string): string | null {
+    try {
+      new Function(source);
+      return null;
+    } catch (error) {
+      return error instanceof Error ? error.message : String(error);
+    }
+  }
+}