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

package/csrE2e/csrE2eHarness.fixture.ts

@@ -54,6 +54,7 @@ export class CsrE2eHarness {
   readonly #lang: string;
   readonly #mobileTarget: string;
   readonly #edited = new Map<string, string>();
+  readonly #console: string[];
   #marker = "";
   #csr: boolean = true;
 
@@ -63,14 +64,39 @@ export class CsrE2eHarness {
     server: CsrE2eServer | null;
     lang: string;
     mobileTarget: string;
+    console: string[];
   }) {
     this.origin = options.origin;
     this.#view = options.view;
+    this.#console = options.console;
     this.#server = options.server;
     this.#lang = options.lang;
     this.#mobileTarget = options.mobileTarget;
   }
 
+  /** What keeps this host from driving a page, or null when a `Bun.WebView` opens one and answers. */
+  static async preflight(backend = CsrE2eHarness.#defaultBackend()): Promise<string | null> {
+    if (typeof (Bun as { WebView?: unknown }).WebView !== "function") return `Bun ${Bun.version} has no Bun.WebView`;
+    let view: Bun.WebView | null = null;
+    try {
+      const opened = new Bun.WebView({
+        width: 320,
+        height: 240,
+        backend: backend === "chrome" ? { type: "chrome", url: false } : backend,
+      });
+      view = opened;
+      const answer = await Promise.race([
+        opened.navigate("about:blank").then(async () => await opened.evaluate<number>("1 + 1")),
+        Bun.sleep(30_000).then(() => null),
+      ]);
+      return answer === 2 ? null : `a ${backend} Bun.WebView did not answer within 30s`;
+    } catch (error) {
+      return `a ${backend} Bun.WebView cannot start: ${error instanceof Error ? error.message : String(error)}`;
+    } finally {
+      view?.close();
+    }
+  }
+
   /** E2E suites run only with `AKAN_CSR_E2E=1`: they boot a dev server and a browser. */
   static get enabled() {
     return process.env.AKAN_CSR_E2E === "1";
@@ -91,13 +117,19 @@ export class CsrE2eHarness {
       await CsrE2eHarness.#waitForHealth(origin, server, options.startTimeoutMs ?? 180_000);
       const { width, height } = { width: 390, height: 844, ...options.viewport };
       const backend = options.backend ?? CsrE2eHarness.#defaultBackend();
+      const messages: string[] = [];
+      const print = process.env.AKAN_CSR_E2E_CONSOLE === "1";
       //? `url: false` spawns a fresh Chrome instead of attaching to one the developer runs with remote debugging on.
       const view = new Bun.WebView({
         width,
         height,
         backend: backend === "chrome" ? { type: "chrome", url: false } : backend,
-        //? AKAN_CSR_E2E_CONSOLE=1 prints the page's console: the only view of a hydration warning or a failed patch.
-        ...(process.env.AKAN_CSR_E2E_CONSOLE === "1" ? { console: globalThis.console } : {}),
+        //? Kept for `consoleMessages()`; AKAN_CSR_E2E_CONSOLE=1 also prints it, the only view of a hydration warning or
+        //? a failed patch. An uncaught error is not a console call and never arrives here.
+        console: (type: string, ...args: unknown[]) => {
+          messages.push(`[${type}] ${args.map(CsrE2eHarness.#formatArg).join(" ")}`);
+          if (print) globalThis.console.info(`[page ${type}]`, ...args);
+        },
       });
       return new CsrE2eHarness({
         origin,
@@ -105,6 +137,7 @@ export class CsrE2eHarness {
         server,
         lang: options.lang ?? "en",
         mobileTarget: options.mobileTarget ?? "e2e",
+        console: messages,
       });
     } catch (error) {
       await CsrE2eHarness.#stopServer(server);
@@ -120,6 +153,7 @@ export class CsrE2eHarness {
       url.searchParams.set("akanMobileTarget", this.#mobileTarget);
     }
     this.#csr = csr;
+    this.#console.length = 0;
     await this.#view.navigate(url.toString());
     await this.#markBoot();
   }
@@ -346,6 +380,11 @@ export class CsrE2eHarness {
     return [await read(logPath), await read(logPath.replace(/\.log$/, ".err.log"))];
   }
 
+  /** The page's console calls since `open()`, as `[type] text`. */
+  consoleMessages(): string[] {
+    return [...this.#console];
+  }
+
   /** Whether the page reloaded since `open()`: the boot marker lives only in the page `open()` loaded. */
   async reloaded() {
     const marker = await this.evaluate(
@@ -378,7 +417,17 @@ export class CsrE2eHarness {
     await CsrE2eHarness.#stopServer(this.#server);
   }
 
-  static #defaultBackend() {
+  static #formatArg(arg: unknown): string {
+    if (typeof arg === "string") return arg;
+    try {
+      return JSON.stringify(arg) ?? String(arg);
+    } catch {
+      // A circular descriptor still names itself.
+      return String(arg);
+    }
+  }
+
+  static #defaultBackend(): "webkit" | "chrome" {
     const requested = process.env.AKAN_CSR_E2E_BACKEND;
     if (requested === "webkit" || requested === "chrome") return requested;
     return process.platform === "darwin" ? "webkit" : "chrome";
@@ -411,8 +460,9 @@ export class CsrE2eHarness {
     const errPath = logPath.replace(/\.log$/, ".err.log");
     //? A `Bun.file` sink writes from offset 0 without truncating, so the last run's tail would outlive this one's start.
     await Promise.all([Bun.write(logPath, ""), Bun.write(errPath, "")]);
-    //? Its own process group, so stopping it reaches the gateway, the builder and every replica it spawned.
-    const proc = Bun.spawn(["bun", cli, "start", app, "--plain"], {
+    //? Its own process group, so stopping it reaches the gateway, the builder and every replica it spawned. That group
+    //? outlives a run killed before it could stop it, so `--kill` takes the suite's own port back from it first.
+    const proc = Bun.spawn(["bun", cli, "start", app, "--plain", "--kill"], {
       cwd: workspaceRoot,
       env: { ...process.env, AKAN_DEV_PORT: String(port), ...env },
       stdout: Bun.file(logPath),

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