@akanjs/devkit 3.0.0-beta.26 → 3.0.0-beta.28

package/csrE2e/csrRootLayout.e2e.test.ts

@@ -0,0 +1,134 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { CsrE2eHarness } from "./csrE2eHarness.fixture";
+
+//* Where a CSR page lands, not only what its console says. CSR's root layout renders the pages in a frame of its own
+//* and hides what it wraps, so a layout the route table puts at the root wraps no page: an app with its root layout
+//* in a route group once rendered nothing, then rendered its dashboard outside the lock screen that wraps it.
+const EXPLORE = "/explore";
+const TAB_A = "/e2e/stack/tab-a";
+//? The web layout draws no bottom chrome, so the `(tab)` layout shows in the route table, not in the text.
+const exploreText = ["Where are you headed today?", "Popular stays right now"];
+
+interface RouteTableWindow {
+  __akan?: { inspect(): { executed: string[] }; require(id: string): unknown };
+}
+
+//? A page's element is inside its layout's marker, outside the hidden provider container, and on screen.
+const placement = async (harness: CsrE2eHarness, page: string) =>
+  await harness.evaluate((selector: string) => {
+    const element = document.querySelector(selector);
+    return {
+      rendered: element !== null,
+      inLayout: element?.closest('[data-e2e="public-layout"]') != null,
+      hidden: element?.closest("#csr-provider-children") != null,
+      visible: element?.checkVisibility() ?? false,
+    };
+  }, `[data-e2e="${page}"]`);
+
+describe.skipIf(!CsrE2eHarness.enabled)("CSR layouts under a root layout (minimal, (tab))", () => {
+  let csr: CsrE2eHarness;
+
+  beforeAll(async () => {
+    csr = await CsrE2eHarness.start({
+      app: "minimal",
+      port: Number(process.env.AKAN_CSR_E2E_ROOT_LAYOUT_PORT ?? 8497),
+    });
+  }, 240_000);
+
+  afterAll(async () => {
+    // biome-ignore lint/suspicious/noUnnecessaryConditions: unassigned when beforeAll threw before the harness started
+    await csr?.close();
+  }, 60_000);
+
+  const rendered = async (texts: string[]) =>
+    await csr.waitFor(
+      (want: string[]) => want.every((text) => (document.getElementById("root")?.innerText ?? "").includes(text)),
+      { args: [texts], timeout: 30_000 },
+    );
+  //? The table the running bundle built, read through the dev registry: what the router renders from.
+  const layerCounts = async () =>
+    await csr.evaluate(() => {
+      const akan = (window as unknown as RouteTableWindow).__akan;
+      const id = akan?.inspect().executed.find((executed) => executed.endsWith("webkit/CsrRouteTable.ts"));
+      const table = id
+        ? (akan?.require(id) as {
+            CsrRouteTable: {
+              active: {
+                snapshot(): { pathRoutes: { path: string; renderRootLayouts: unknown[]; renderLayouts: unknown[] }[] };
+              };
+            };
+          })
+        : null;
+      return Object.fromEntries(
+        (table?.CsrRouteTable.active.snapshot().pathRoutes ?? []).map((route) => [
+          route.path,
+          { root: route.renderRootLayouts.length, layouts: route.renderLayouts.length },
+        ]),
+      );
+    });
+
+  test("a nested root boundary renders with its pages, not at the root", async () => {
+    await csr.open(EXPLORE);
+    await rendered(exploreText);
+    const counts = await layerCounts();
+    expect(counts["/:lang/explore"]?.root).toBe(counts["/:lang/e2e/stack/tab-a"]?.root);
+    expect(counts["/:lang/explore"]?.layouts).toBe(1);
+    expect(csr.consoleMessages().filter((message) => /no root layout|error occurred/.test(message))).toEqual([]);
+  }, 60_000);
+
+  test("leaving the group and coming back renders each side", async () => {
+    await csr.open(EXPLORE);
+    await rendered(exploreText);
+    await csr.navigate(TAB_A);
+    await csr.waitFor(() => document.querySelector('[data-e2e-probe="tab-a"]') !== null, { timeout: 30_000 });
+    await csr.back();
+    await rendered(exploreText);
+  }, 90_000);
+});
+
+describe.skipIf(!CsrE2eHarness.enabled)("a root layout in a route group (groupedroot, page/(app)/_layout)", () => {
+  let harness: CsrE2eHarness;
+
+  beforeAll(async () => {
+    harness = await CsrE2eHarness.start({
+      app: "groupedroot",
+      port: Number(process.env.AKAN_CSR_E2E_GROUPED_ROOT_PORT ?? 8498),
+    });
+  }, 240_000);
+
+  afterAll(async () => {
+    // biome-ignore lint/suspicious/noUnnecessaryConditions: unassigned when beforeAll threw before the harness started
+    await harness?.close();
+  }, 60_000);
+
+  const open = async (path: string, page: string, csr: boolean) => {
+    await harness.open(path, { csr });
+    await harness.waitFor((selector: string) => document.querySelector(selector) !== null, {
+      args: [`[data-e2e="${page}"]`],
+      timeout: 30_000,
+    });
+  };
+
+  test.each([
+    ["SSR", false],
+    ["CSR", true],
+  ] as const)(
+    "%s: a page renders inside the (public) layout that wraps it",
+    async (_mode, csr) => {
+      for (const [path, page] of [
+        ["/dashboard", "dashboard"],
+        ["/", "index"],
+      ] as const) {
+        await open(path, page, csr);
+        expect(await placement(harness, page)).toEqual({
+          rendered: true,
+          inLayout: true,
+          hidden: false,
+          visible: true,
+        });
+      }
+      expect(harness.consoleMessages().filter((message) => /no root layout|error occurred/.test(message))).toEqual([]);
+    },
+    90_000,
+  );
+});

package/csrE2e/registryVendor.e2e.test.ts

@@ -0,0 +1,221 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { rm } from "node:fs/promises";
+import path from "node:path";
+import { CsrE2eHarness } from "./csrE2eHarness.fixture";
+
+//* Package shapes that once turned a whole dev vendor file into a SyntaxError or a startup throw, each followed by
+//* nothing but distant MissingModuleErrors. Written in for the run only: no app of the repo depends on them.
+const workspaceRoot = path.resolve(import.meta.dir, "../../../..");
+const vendorRoot = path.join(workspaceRoot, "node_modules/@akan-e2e");
+const probeFile = path.join(workspaceRoot, "apps/minimal/ui/RegistryVendor.tsx");
+const pageFile = path.join(workspaceRoot, "apps/minimal/page/(home)/e2e/vendor.tsx");
+const cliFile = path.join(workspaceRoot, "dist/pkgs/@akanjs/cli/index.js");
+const VENDOR = "/e2e/vendor";
+const expected = { prebundled: 3, metaDev: true, metaUrl: "http:", used: "used", inspectish: "yes" };
+const broken =
+  /SyntaxError|MissingModuleError|no module registered|Node built-in|left out of the dev registry|error occurred in one of your React components/;
+
+const packages: Record<string, string> = {
+  //? esbuild's own interop helpers, as the @mermaid-js/parser chunks ship them.
+  "prebundled/package.json": JSON.stringify({ name: "@akan-e2e/prebundled", type: "module", main: "chunk.mjs" }),
+  "prebundled/chunk.mjs": `var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __reExport = (target, mod, secondTarget) => (__copyProps(target, mod, "default"), secondTarget && __copyProps(secondTarget, mod, "default"));
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target, mod));
+var parts = {};
+__reExport(parts, { a: 1 });
+var wrapped = __toESM({ b: 2 });
+export const prebundled = parts.a + wrapped.b;
+`,
+  //? jotai's and zustand's ESM development check.
+  "meta-env/package.json": JSON.stringify({
+    name: "@akan-e2e/meta-env",
+    type: "module",
+    exports: { ".": "./esm/index.mjs" },
+  }),
+  "meta-env/esm/index.mjs": `export const metaDev = (import.meta.env ? import.meta.env.MODE : void 0) !== "production";
+export const metaUrl = new URL(import.meta.url).protocol;
+`,
+  //? vfile behind unified: a side-effect-free barrel whose unused re-exports reach Node-only files through `#imports`.
+  "barrel/package.json": JSON.stringify({
+    name: "@akan-e2e/barrel",
+    type: "module",
+    main: "index.js",
+    sideEffects: false,
+    imports: {
+      "#where": { node: "./where.node.js", default: "./where.browser.js" },
+      "#other": { node: "./other.node.js", default: "./other.browser.js" },
+    },
+  }),
+  "barrel/index.js": `export { used } from "./used.js";
+export { unused } from "./unused.js";
+export { other } from "#other";
+`,
+  "barrel/used.js": `export const used = "used";\n`,
+  "barrel/unused.js": `import { where } from "#where";\nexport const unused = where;\n`,
+  "barrel/where.node.js": `import path from "node:path";\nexport const where = path.sep;\n`,
+  "barrel/where.browser.js": `export const where = "browser";\n`,
+  "barrel/other.node.js": `import path from "node:path";\nexport const other = path.sep;\n`,
+  "barrel/other.browser.js": `export const other = "browser";\n`,
+  //? object-inspect: a `browser` map that turns a Node-only file off.
+  "inspectish/package.json": JSON.stringify({
+    name: "@akan-e2e/inspectish",
+    main: "index.js",
+    browser: { "./util.inspect.js": false },
+  }),
+  //? Bun's own bundle gives the require `() => ({})` where the registry gives `{}`; either way it must not throw.
+  "inspectish/index.js": `var inspect = require("./util.inspect");\nmodule.exports = { loaded: inspect ? "yes" : "no" };\n`,
+  "inspectish/util.inspect.js": `module.exports = require("util").inspect;\n`,
+};
+
+const probeSource = `"use client";
+import { used } from "@akan-e2e/barrel";
+import inspectish from "@akan-e2e/inspectish";
+import { metaDev, metaUrl } from "@akan-e2e/meta-env";
+import { prebundled } from "@akan-e2e/prebundled";
+import { useEffect, useState } from "react";
+
+export const RegistryVendor = () => {
+  const [hydrated, setHydrated] = useState(false);
+  useEffect(() => setHydrated(true), []);
+  return (
+    <div data-e2e="vendor" data-e2e-hydrated={hydrated ? "1" : "0"} data-e2e-hot="0">
+      {JSON.stringify({ prebundled, metaDev, metaUrl, used, inspectish: inspectish.loaded })}
+    </div>
+  );
+};
+`;
+
+const pageSource = `import { page } from "akanjs/client";
+import { RegistryVendor } from "../../../ui/RegistryVendor";
+
+export default page()
+  .config({ transition: "none", gesture: false })
+  .render(() => (
+    <main>
+      <RegistryVendor />
+    </main>
+  ));
+`;
+
+interface VendorWindow {
+  __akan?: { has(id: string): boolean; inspect(): { started: boolean; failed: boolean; executed: string[] } };
+}
+
+describe.skipIf(!CsrE2eHarness.enabled)("dev registries with the package shapes that broke them (minimal)", () => {
+  //? Run first too, and safe to run twice: a run killed mid-way (a timeout, SIGKILL, a Jenkins abort on a reused
+  //? workspace) leaves the packages, the probe and the page behind, and `akan sync` rebuilds the barrel it joined.
+  const cleanup = async () => {
+    await Promise.all([
+      rm(vendorRoot, { recursive: true, force: true }),
+      rm(probeFile, { force: true }),
+      rm(pageFile, { force: true }),
+    ]);
+    for (const command of [
+      ["bun", path.join(workspaceRoot, "pkgs/@akanjs/cli/build.ts")],
+      ["bun", cliFile, "sync", "minimal"],
+    ]) {
+      const done = Bun.spawnSync(command, { cwd: workspaceRoot, stdout: "ignore" });
+      if (done.exitCode !== 0)
+        throw new Error(`[csr-e2e] ${command.slice(1).join(" ")} failed: ${done.stderr.toString()}`);
+    }
+  };
+
+  beforeAll(async () => {
+    await cleanup();
+    for (const [file, text] of Object.entries(packages)) await Bun.write(path.join(vendorRoot, file), text);
+    await Bun.write(probeFile, probeSource);
+    await Bun.write(pageFile, pageSource);
+  }, 120_000);
+
+  afterAll(cleanup, 120_000);
+
+  describe.each([
+    ["registry", 8495],
+    ["artifact", 8496],
+  ] as const)("AKAN_DEV_CSR=%s", (mode, port) => {
+    let harness: CsrE2eHarness;
+
+    beforeAll(async () => {
+      harness = await CsrE2eHarness.start({ app: "minimal", port, env: { AKAN_DEV_CSR: mode } });
+    }, 240_000);
+
+    afterAll(async () => {
+      // biome-ignore lint/suspicious/noUnnecessaryConditions: unassigned when beforeAll threw before the harness started
+      await harness?.close();
+    }, 60_000);
+
+    const probeValues = async () =>
+      JSON.parse((await harness.text('[data-e2e="vendor"]', { mounted: true }))[0] ?? "null") as typeof expected | null;
+    const openVendor = async (csr: boolean) => {
+      await harness.open(VENDOR, { csr });
+      await harness.waitFor(
+        () => document.querySelector('[data-e2e="vendor"]')?.getAttribute("data-e2e-hydrated") === "1",
+        { timeout: 60_000 },
+      );
+    };
+    const registryState = async () =>
+      await harness.evaluate(() => {
+        const akan = (window as unknown as VendorWindow).__akan;
+        if (!akan) return null;
+        const { started, failed, executed } = akan.inspect();
+        return {
+          started,
+          failed,
+          refresh: executed.some((id) => id.includes("react-refresh/")),
+          vendors: [
+            "node_modules/@akan-e2e/prebundled/chunk.mjs",
+            "node_modules/@akan-e2e/meta-env/esm/index.mjs",
+            "node_modules/@akan-e2e/barrel/unused.js",
+            "node_modules/@akan-e2e/inspectish/index.js",
+          ].filter((id) => akan.has(id)),
+        };
+      });
+
+    test("an SSR page hydrates its client code with every package shape in it", async () => {
+      await openVendor(false);
+      expect(await probeValues()).toEqual(expected);
+      expect(await registryState()).toMatchObject({ started: true, failed: false });
+      expect((await registryState())?.vendors).toHaveLength(4);
+      expect(harness.consoleMessages().filter((message) => broken.test(message))).toEqual([]);
+    }, 120_000);
+
+    test("a CSR page boots and renders with every package shape in it", async () => {
+      await openVendor(true);
+      expect(await probeValues()).toEqual(expected);
+      const state = await registryState();
+      if (mode === "registry") expect(state).toMatchObject({ started: true, failed: false, refresh: true });
+      if (mode === "registry") expect(state?.vendors).toHaveLength(4);
+      expect(harness.consoleMessages().filter((message) => broken.test(message))).toEqual([]);
+    }, 120_000);
+
+    test("a save to the page's client code shows on the CSR page", async () => {
+      await openVendor(true);
+      await harness.editSource(
+        probeFile,
+        (source) => source.replace('data-e2e-hot="0"', 'data-e2e-hot="1"'),
+        async () => {
+          await harness.waitFor(
+            () => document.querySelector('[data-e2e="vendor"]')?.getAttribute("data-e2e-hot") === "1",
+            { timeout: 60_000 },
+          );
+        },
+      );
+      //? The registry patches in place; the single-file artifact reloads on every save, which is its contract.
+      expect(await harness.reloaded()).toBe(mode === "artifact");
+      expect(await probeValues()).toEqual(expected);
+    }, 120_000);
+  });
+});

package/executors.test.ts

@@ -1,4 +1,5 @@
 import { describe, expect, test } from "bun:test";
+import { existsSync } from "node:fs";
 import { lstat, mkdir, readFile, readlink, rm, stat, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { AkanAppConfig } from "./akanConfig";
@@ -326,6 +327,37 @@ describe("Workspace and app executor environment contracts", () => {
     expect((await stat(path.join(root, "dist/apps/demo/public"))).isDirectory()).toBe(true);
   });
 
+  test("akan start clears the dev output and keeps native builds, update releases and the bin downloads", async () => {
+    const root = await makeTempRoot();
+    process.env.AKAN_PUBLIC_REPO_NAME = "repo";
+    process.env.AKAN_PUBLIC_SERVE_DOMAIN = "example.com";
+    process.env.AKAN_PUBLIC_ENV = "local";
+    process.env.PORT_OFFSET = "0";
+    await writeJson(path.join(root, "package.json"), rootPackageJson());
+    await mkdir(path.join(root, "apps/startclean/page"), { recursive: true });
+    await writeFile(path.join(root, "apps/startclean/akan.config.ts"), "export default {};\n");
+    const akan = path.join(root, "apps/startclean/.akan");
+    const kept = [
+      "mobile/desktop/updates/macos-arm64/main.json",
+      "mobile/desktop/native/macos/App.app",
+      "cache/bin/ffmpeg",
+    ];
+    const removed = [
+      "artifact/client/app.js",
+      "generated/dict/index.ts",
+      "cache/cssCandidates.json",
+      "desktop/server/main.js",
+    ];
+    for (const file of [...kept, ...removed]) await writeText(path.join(akan, file), "x");
+
+    const app = AppExecutor.from(new WorkspaceExecutor({ workspaceRoot: root, repoName: "repo" }), "startclean");
+    await app.prepareCommand("start");
+
+    for (const file of kept) expect(existsSync(path.join(akan, file))).toBe(true);
+    for (const file of [...removed, "artifact", "generated", "desktop"])
+      expect(existsSync(path.join(akan, file))).toBe(false);
+  });
+
   describe("syncPages", () => {
     // `AppExecutor.from` memoises by name, so each test needs a name no other test has used.
     const makeAppWithLibPages = async (
@@ -963,6 +995,17 @@ describe("WorkspaceExecutor listing", () => {
       ["@sample/tool", "akanjs", "zeta-tool"],
     ]);
   });
+
+  test("never takes a scratch workspace under a local/ folder for a package, app or lib", async () => {
+    const root = await makeTempRoot();
+    await writeJson(path.join(root, "pkgs/@akanjs/devkit/package.json"), { name: "@akanjs/devkit" });
+    await writeJson(path.join(root, "pkgs/@akanjs/devkit/local/akan-cli-x/package.json"), { name: "repo" });
+    await writeText(path.join(root, "apps/portal/akan.config.ts"), "");
+    await writeText(path.join(root, "libs/util/local/akan-cli-y/akan.config.ts"), "");
+
+    const workspace = new WorkspaceExecutor({ workspaceRoot: root, repoName: "repo" });
+    expect(await workspace.getExecs()).toEqual([["portal"], [], ["@akanjs/devkit"]]);
+  });
 });
 
 describe("SysExecutor module listing", () => {

package/executors.ts

@@ -790,7 +790,8 @@ export class WorkspaceExecutor extends Executor {
   }
   async #getDirHasFile(basePath: string, targetFilename: string) {
     if (!(await FileSys.dirExists(basePath))) return [];
-    const AVOID_DIRS = ["node_modules", "dist", "public", "webkit"];
+    //? `local/` is gitignored scratch: a test's temporary workspace there has a package.json of its own.
+    const AVOID_DIRS = ["node_modules", "dist", "public", "webkit", "local"];
     const getDirs = async (dirname: string, maxDepth = 3, results: string[] = [], prefix = "") => {
       const dirs = await this.readdir(dirname);
       await Promise.all(
@@ -1118,6 +1119,20 @@ export class AppExecutor extends SysExecutor {
   static from(executor: SysExecutor | WorkspaceExecutor, name: string) {
     return new AppExecutor({ workspace: executor instanceof WorkspaceExecutor ? executor : executor.workspace, name });
   }
+  //* Not dev output: native builds and the update releases waiting to be uploaded, and the downloaded `bin` sources.
+  static readonly #keptOnStart = [path.join(".akan", "mobile"), path.join(".akan", "cache", "bin")];
+  async #removeDevOutput(dir = ".akan") {
+    const entries = await readDirEntries(this.getPath(dir)).catch(() => [] as string[]);
+    await Promise.all(
+      entries.map(async (name) => {
+        const entry = path.join(dir, name);
+        if (AppExecutor.#keptOnStart.includes(entry)) return;
+        if (AppExecutor.#keptOnStart.some((kept) => kept.startsWith(`${entry}${path.sep}`)))
+          return await this.#removeDevOutput(entry);
+        await this.removeDir(entry);
+      }),
+    );
+  }
   getEnv() {
     return WorkspaceExecutor.getBaseDevEnv().env;
   }
@@ -1174,7 +1189,7 @@ export class AppExecutor extends SysExecutor {
         ...(akanConfig.web.ssr ? [this.cp("public", `${this.dist.cwdPath}/public`, { dereference: true })] : []),
       ]);
     } else {
-      await this.removeDir(".akan");
+      await this.#removeDevOutput();
       //? `akan start` keeps the full dev surface: the incremental builder is also the file watcher.
       if (!akanConfig.web.ssr || !akanConfig.web.csr)
         this.logger.verbose(

package/frontendBuild/csrDevArtifactWriter.test.ts

@@ -76,6 +76,14 @@ describe("CsrDevArtifactWriter", () => {
     expect(existsSync(path.join(dir, "graph.json"))).toBe(true);
   });
 
+  test("a module a package's browser field turns off is written empty, and a Node built-in still throws", async () => {
+    const { writer, graph, dir } = await makeWriter();
+    graph.modules["a.ts"] = { vendor: false, mtimeMs: 0, hash: "", deps: ["stub:empty:fs", "stub:path"] };
+    const vendor = readFileSync(path.join(dir, await writer.writeVendor(graph)), "utf8");
+    expect(vendor).toContain('__akan.define("stub:empty:fs", function () {});');
+    expect(vendor).toContain("[akan-csr] path is a Node built-in the browser does not have");
+  });
+
   test("rewrites an app.js a crash left behind the manifest's generation", async () => {
     const { writer, graph, read } = await makeWriter();
     await writer.writeApp(graph, { generation: 5, vendorFile: "v.js" });

package/frontendBuild/csrDevArtifactWriter.ts

@@ -114,6 +114,10 @@ export class CsrDevArtifactWriter {
     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`,

package/frontendBuild/csrDevBundler.ts

@@ -13,7 +13,7 @@ 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 = 3;
+  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> }>();

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);
+    }
+  }
+}