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

package/frontendBuild/csrDevModuleCompiler.test.ts

@@ -6,7 +6,7 @@ import type { App } from "../commandDecorators";
 import { CsrDevModuleCompiler } from "./csrDevModuleCompiler";
 import { CsrDevPaths } from "./csrDevPaths";
 import { CsrDevResolver } from "./csrDevResolver";
-import type { CsrDevContext } from "./csrDevTypes";
+import type { CsrDevCompiledModule, CsrDevContext } from "./csrDevTypes";
 
 const context: CsrDevContext = {
   pageEntries: [],
@@ -41,20 +41,63 @@ var wrapped = __toESM({ b: 2 });
 export { parts, wrapped };
 `;
 
+//? The development checks jotai's and zustand's ESM builds ship, as written in jotai/esm/vanilla.mjs.
+const jotai = `let keyCount = 0;
+export function atom(read) {
+  const key = \`atom\${++keyCount}\`;
+  return {
+    read,
+    toString() {
+      return (import.meta.env ? import.meta.env.MODE : void 0) !== "production" && this.debugLabel ? key + ":" + this.debugLabel : key;
+    },
+  };
+}
+`;
+const zustand = `export const devtools = (fn) => (import.meta.env ? import.meta.env.MODE : void 0) !== "production" ? "dev" : fn;
+`;
+
 describe("CsrDevModuleCompiler", () => {
   let root: string;
+  const origin = "http://localhost:8283";
   const file = (relative: string) => path.join(root, relative);
-  const compile = async (relative: string) => {
+  const logged: string[] = [];
+  const compile = async (relative: string | string[], { prepass = false }: { prepass?: boolean } = {}) => {
+    const files = (Array.isArray(relative) ? relative : [relative]).map(file);
     const paths = new CsrDevPaths(root);
+    const resolver = new CsrDevResolver({ paths, context, entryFiles: prepass ? files : [] });
+    if (prepass) await resolver.prepass();
     const compiler = new CsrDevModuleCompiler({
-      app: { verbose: () => undefined } as unknown as App,
+      app: { verbose: () => undefined, logger: { error: (message: string) => logged.push(message) } } as unknown as App,
       paths,
-      resolver: new CsrDevResolver({ paths, context, entryFiles: [] }),
+      resolver,
       context,
       outDir: file("out"),
       routePrefix: "/_akan/registry/",
     });
-    return await compiler.compile([file(relative)], new Set());
+    return { resolver, ...(await compiler.compile(files, new Set())) };
+  };
+  //? As the page runs a factory: a classic script whose only globals are the runtime and the window.
+  const run = (module: CsrDevCompiledModule | undefined) => {
+    const helpers = new Map<string, Record<string, unknown>>();
+    const akan = {
+      defineHelpers: (hash: string, define: () => Record<string, unknown>) => helpers.set(hash, define()),
+      helpers: (hash: string) => helpers.get(hash),
+    };
+    if (module?.helpers) new Function("__akan", module.helpers.definition)(akan);
+    const factory = new Function("__akan", "self", `return (${module?.factory});`)(akan, {
+      location: { href: `${origin}/en/dashboard` },
+    });
+    const record = { exports: {} as Record<string, unknown> };
+    factory.call(
+      record.exports,
+      () => ({}),
+      record,
+      record.exports,
+      () => undefined,
+      () => (type: unknown) => type,
+      async () => ({}),
+    );
+    return record.exports;
   };
 
   beforeAll(async () => {
@@ -62,6 +105,84 @@ describe("CsrDevModuleCompiler", () => {
     await Bun.write(file("node_modules/prebundled/chunk.mjs"), prebundled);
     await Bun.write(file("node_modules/bare-reexport/index.mjs"), "export const parts = __reExport({}, { a: 1 });\n");
     await Bun.write(file("node_modules/bare-toesm/index.mjs"), "export const wrapped = __toESM({ b: 2 });\n");
+    await Bun.write(file("node_modules/jotai/esm/vanilla.mjs"), jotai);
+    await Bun.write(file("node_modules/zustand/esm/middleware.mjs"), zustand);
+    await Bun.write(
+      file("apps/demo/ui/meta.ts"),
+      [
+        "export const url = import.meta.url;",
+        "export const env = import.meta.env;",
+        'export const asset = new URL("./x.wasm", import.meta.url).href;',
+        'export const label = "import.meta.env";',
+        "",
+      ].join("\n"),
+    );
+    //? The shape of an app's useClient.ts: a macro whose module graph reaches server code that reads import.meta.
+    await Bun.write(
+      file("apps/demo/lib/macroDep.ts"),
+      'import { createRequire } from "node:module";\nconst req = createRequire(import.meta.url);\nexport const depUrl = import.meta.url;\nexport const hasRequire = typeof req;\n',
+    );
+    await Bun.write(
+      file("apps/demo/lib/macro.ts"),
+      'import { depUrl, hasRequire } from "./macroDep";\nexport const serialized = () => ({ depUrl, hasRequire });\n',
+    );
+    await Bun.write(
+      file("apps/demo/lib/useClient.ts"),
+      [
+        'import { used } from "barrel";',
+        'import { serialized } from "./macro" with { type: "macro" };',
+        "export const signal = serialized();",
+        "export const own = import.meta.url;",
+        'export const label = "import.meta.url";',
+        "export const barrel = used;",
+        "",
+      ].join("\n"),
+    );
+    await Bun.write(file("node_modules/with-bin/index.mjs"), "#!/usr/bin/env node\nexport const a = 1;\n");
+    await Bun.write(file("node_modules/awaits/index.mjs"), "export const a = await Promise.resolve(1);\n");
+    await Bun.write(file("apps/demo/ui/awaits.ts"), "export const a = await Promise.resolve(1);\n");
+    await Bun.write(
+      file("node_modules/barrel/package.json"),
+      JSON.stringify({
+        name: "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" },
+        },
+      }),
+    );
+    await Bun.write(
+      file("node_modules/barrel/index.js"),
+      'export { used } from "./used.js";\nexport { unused } from "./unused.js";\nexport { other } from "#other";\n',
+    );
+    await Bun.write(file("node_modules/barrel/used.js"), "export const used = 1;\n");
+    await Bun.write(
+      file("node_modules/barrel/unused.js"),
+      'import { where } from "#where";\nexport const unused = where;\n',
+    );
+    await Bun.write(
+      file("node_modules/barrel/where.node.js"),
+      'import path from "node:path";\nexport const where = path.sep;\n',
+    );
+    await Bun.write(file("node_modules/barrel/where.browser.js"), 'export const where = "browser";\n');
+    await Bun.write(
+      file("node_modules/barrel/other.node.js"),
+      'import path from "node:path";\nexport const other = path.sep;\n',
+    );
+    await Bun.write(file("node_modules/barrel/other.browser.js"), 'export const other = "browser";\n');
+    await Bun.write(file("apps/demo/entry.ts"), 'import { used } from "barrel";\nexport const run = used;\n');
+    await Bun.write(
+      file("node_modules/inspectish/package.json"),
+      JSON.stringify({ name: "inspectish", main: "index.js", browser: { "./util.inspect.js": false, fs: false } }),
+    );
+    await Bun.write(
+      file("node_modules/inspectish/index.js"),
+      'var inspect = require("./util.inspect");\nvar fs = require("fs");\nmodule.exports = { inspect, fs };\n',
+    );
+    await Bun.write(file("node_modules/inspectish/util.inspect.js"), 'module.exports = require("util").inspect;\n');
   });
 
   afterAll(async () => {
@@ -77,7 +198,8 @@ describe("CsrDevModuleCompiler", () => {
     expect(factory).toContain("var __toESM = (mod, isNodeMode, target) => (");
     expect(factory).not.toContain("__akan.reExport");
     expect(factory).not.toContain("__akan.toESM");
-    expect(() => new Function(`return (${factory});`)).not.toThrow();
+    expect(factory).not.toContain("__akanMeta");
+    expect(run(module)).toMatchObject({ parts: { a: 1 }, wrapped: { b: 2 } });
   });
 
   test.each([
@@ -86,4 +208,86 @@ describe("CsrDevModuleCompiler", () => {
   ])("a %s call with no definition anywhere still stops the build", async (name, relative) => {
     await expect(compile(relative)).rejects.toThrow(`Bun's ${name} helper no longer reads`);
   });
+
+  test("jotai's and zustand's import.meta.env checks run as a classic script and take the ESM bundle's branch", async () => {
+    const [{ modules: jotaiModules }, { modules: zustandModules }] = await Promise.all([
+      compile("node_modules/jotai/esm/vanilla.mjs"),
+      compile("node_modules/zustand/esm/middleware.mjs"),
+    ]);
+    const [jotaiModule] = jotaiModules;
+    const [zustandModule] = zustandModules;
+    expect(jotaiModule?.factory).not.toContain("import.meta");
+    expect(zustandModule?.factory).not.toContain("import.meta");
+    const labeled = Object.assign((run(jotaiModule).atom as (read: unknown) => object)(null), { debugLabel: "count" });
+    expect(String(labeled)).toBe("atom1:count");
+    expect((run(zustandModule).devtools as (fn: unknown) => unknown)("prod")).toBe("dev");
+  });
+
+  test("an app module reads import.meta as a browser module does, on its own path and with no env", async () => {
+    const [module] = (await compile("apps/demo/ui/meta.ts")).modules;
+    expect(module?.factory).not.toContain("file://");
+    expect(run(module)).toEqual({
+      url: `${origin}/apps/demo/ui/meta.ts`,
+      env: undefined,
+      asset: `${origin}/apps/demo/ui/x.wasm`,
+      label: "import.meta.env",
+    });
+  });
+
+  test("a macro runs with its modules' own import.meta, and the file importing it still reads the browser's", async () => {
+    const { modules } = await compile("apps/demo/lib/useClient.ts", { prepass: true });
+    const module = modules.find((compiled) => compiled.id === "apps/demo/lib/useClient.ts");
+    expect(module?.deps.some((dep) => dep.includes(`${path.join("node_modules", "barrel")}${path.sep}`))).toBe(true);
+    expect(run(module)).toMatchObject({
+      signal: { depUrl: Bun.pathToFileURL(file("apps/demo/lib/macroDep.ts")).href, hasRequire: "function" },
+      own: `${origin}/apps/demo/lib/useClient.ts`,
+      label: "import.meta.url",
+    });
+  });
+
+  test("a file or re-export the browser build tree-shook away resolves with the browser condition", async () => {
+    const { modules, resolver } = await compile("apps/demo/entry.ts", { prepass: true });
+    const ids = modules.map((module) => module.id);
+    expect(ids).toContain("node_modules/barrel/unused.js");
+    expect(ids).toContain("node_modules/barrel/where.browser.js");
+    expect(ids).not.toContain("node_modules/barrel/where.node.js");
+    expect(ids).toContain("node_modules/barrel/other.browser.js");
+    expect(ids).not.toContain("node_modules/barrel/other.node.js");
+    expect([...resolver.fallbacks]).toEqual([]);
+  });
+
+  test("what a package's browser field maps to false is an empty stub, not the file or the Node built-in", async () => {
+    const { modules } = await compile("node_modules/inspectish/index.js");
+    expect(modules.map((module) => module.id)).toEqual(["node_modules/inspectish/index.js"]);
+    expect(modules[0]?.deps.sort()).toEqual(["stub:empty:fs", "stub:empty:node_modules/inspectish/util.inspect.js"]);
+  });
+
+  test("a package's #! line is a comment in its factory, so the package loads", async () => {
+    const [module] = (await compile("node_modules/with-bin/index.mjs")).modules;
+    expect(module?.factory).not.toContain("#!");
+    expect(run(module)).toEqual({ a: 1 });
+  });
+
+  test("a package file Bun cannot build as CommonJS is left out, named in the log, and the rest still builds", async () => {
+    logged.length = 0;
+    const { modules } = await compile(["node_modules/awaits/index.mjs", "node_modules/zustand/esm/middleware.mjs"]);
+    const left = modules.find((module) => module.id === "node_modules/awaits/index.mjs");
+    expect(modules.map((module) => module.id)).toContain("node_modules/zustand/esm/middleware.mjs");
+    expect(left?.deps).toEqual([]);
+    expect(() => run(left)).toThrow(
+      "[akan-csr] node_modules/awaits/index.mjs was left out of the dev registry: a top-level await",
+    );
+    expect(logged).toEqual([
+      expect.stringContaining(
+        "[csr-dev] node_modules/awaits/index.mjs is left out of the dev registry: a top-level await",
+      ),
+    ]);
+    expect(logged[0]).toContain("(node_modules/awaits/index.mjs:1)");
+  });
+
+  test("app code Bun cannot build as CommonJS still fails the build with Bun's messages", async () => {
+    const failure = await compile("apps/demo/ui/awaits.ts").catch((error: unknown) => error);
+    expect(failure).toBeInstanceOf(AggregateError);
+    expect(String((failure as AggregateError).errors[0])).toContain('"await" can only be used');
+  });
 });

package/frontendBuild/csrDevModuleCompiler.ts

@@ -1,6 +1,7 @@
 import path from "node:path";
 import type { BunPlugin } from "bun";
 import type { App } from "../commandDecorators";
+import { CsrDevFactoryCheck } from "./csrDevFactoryCheck";
 import { CsrDevPaths } from "./csrDevPaths";
 import { CsrDevResolver } from "./csrDevResolver";
 import type { CsrDevCompiledModule, CsrDevContext, CsrDevSharedHelpers } from "./csrDevTypes";
@@ -43,6 +44,7 @@ export interface CsrDevCompileResult {
 //* modules it changed instead of reloading one scope-hoisted file.
 export class CsrDevModuleCompiler {
   static readonly #storeRoot = /(?:^|\/)lib\/st\.ts$/;
+  static readonly #macroImport = /\b(?:with|assert)\s*\{\s*type\s*:\s*["']macro["']/;
   static readonly #factoryArgument =
     /(?<![\w$.])(?:require|module|exports|__akanImport|\$RefreshReg\$|\$RefreshSig\$)(?![\w$]|\s*:)/;
   static readonly #helperPatches = [
@@ -82,6 +84,7 @@ export class CsrDevModuleCompiler {
     while (frontier.length > 0) {
       const refusedVendors = refuseNewVendor ? frontier.filter((file) => CsrDevPaths.isVendorFile(file)) : [];
       if (refusedVendors.length > 0) return { modules: [...compiled.values()], refusedVendors, unresolved: [] };
+      await this.#resolver.cover(frontier);
       const round = await this.#compileRound(frontier);
       if (round.misses.length > 0 && !this.#resolver.prepassDone && refusePrepass)
         return { modules: [...compiled.values()], refusedVendors: [], unresolved: round.misses };
@@ -138,21 +141,30 @@ export class CsrDevModuleCompiler {
       ),
     );
     const misses: string[] = [];
-    const result = await Bun.build({
-      entrypoints: files,
-      root: this.#paths.root,
-      target: "browser",
-      format: "cjs",
-      reactFastRefresh: !vendor,
-      sourcemap: vendor ? "none" : "external",
-      naming: { entry: "[dir]/[name].[ext]", asset: "assets/[name]-[hash].[ext]" },
-      publicPath: this.#routePrefix,
-      metafile: true,
-      env: "AKAN_PUBLIC_*",
-      define: this.#context.define,
-      optimizeImports: this.#context.optimizeImports,
-      plugins: [this.#registryPlugin(vendor, misses)],
-    });
+    const macroOutputs = vendor ? new Map<string, string>() : await this.#evaluateMacros(files);
+    let result: Awaited<ReturnType<typeof Bun.build>>;
+    try {
+      result = await Bun.build({
+        entrypoints: files,
+        root: this.#paths.root,
+        target: "browser",
+        format: "cjs",
+        reactFastRefresh: !vendor,
+        sourcemap: vendor ? "none" : "external",
+        naming: { entry: "[dir]/[name].[ext]", asset: "assets/[name]-[hash].[ext]" },
+        publicPath: this.#routePrefix,
+        metafile: true,
+        env: "AKAN_PUBLIC_*",
+        //? A factory runs as a classic script, where `import.meta` is a SyntaxError that takes the whole vendor file
+        //? down, and Bun's cjs output keeps `import.meta.env` and spells `import.meta.url` as this disk's `file://` path.
+        define: { ...this.#context.define, "import.meta": "__akanMeta" },
+        optimizeImports: this.#context.optimizeImports,
+        plugins: [this.#registryPlugin(vendor, misses, macroOutputs)],
+      });
+    } catch (error) {
+      if (vendor && error instanceof AggregateError) return await this.#withoutFailed(files, error);
+      throw error;
+    }
     const { outputs } = result.metafile as unknown as OutputMetafile;
     const sourceMaps = new Map(
       result.outputs.filter((artifact) => artifact.kind === "sourcemap").map((artifact) => [artifact.path, artifact]),
@@ -177,12 +189,20 @@ export class CsrDevModuleCompiler {
       }
       const code = await artifact.text();
       const id = this.#paths.idOf(file);
+      const built = CsrDevModuleCompiler.#factory(id, code);
+      const problem = CsrDevFactoryCheck.problemOf(built.factory, built.helpers?.definition);
+      if (problem && !vendor)
+        throw new Error(`[csr-dev] ${id}: its factory does not parse as a classic script: ${problem}`);
+      if (problem) {
+        modules.push(this.#leftOut(file, problem));
+        continue;
+      }
       const sourceMap = sourceMaps.get(`${artifact.path}.map`);
       modules.push({
         id,
         file,
         vendor,
-        ...CsrDevModuleCompiler.#factory(id, code),
+        ...built,
         sourceMap: sourceMap ? this.#rebaseSourceMap(await sourceMap.text()) : undefined,
         deps: this.#emittedDeps(code),
         mtimeMs: mtimes.get(file) ?? CsrDevPaths.mtimeOf(file),
@@ -192,11 +212,96 @@ export class CsrDevModuleCompiler {
     return { modules, misses, tangled };
   }
 
-  #registryPlugin(vendor: boolean, misses: string[]): BunPlugin {
+  //? A package file that cannot be a CommonJS factory would fail every module built beside it, and no save fixes a
+  //? package: it is left out and named in the log, and the module requiring it gets the reason. App code still fails.
+  async #withoutFailed(files: string[], error: AggregateError): Promise<BuildRound> {
+    const reasons = new Map<string, string[]>();
+    for (const message of error.errors as {
+      message?: unknown;
+      position?: { file?: unknown; line?: number } | null;
+    }[]) {
+      const file = message.position?.file;
+      if (typeof file !== "string" || !path.isAbsolute(file)) continue;
+      const real = CsrDevPaths.realpath(file);
+      const at = message.position?.line ? `:${message.position.line}` : "";
+      reasons.set(real, [...(reasons.get(real) ?? []), `${String(message.message)} (${this.#paths.idOf(real)}${at})`]);
+    }
+    const failed = new Set(files.filter((file) => reasons.has(CsrDevPaths.realpath(file))));
+    if (failed.size === 0) throw error;
+    const rest = files.filter((file) => !failed.has(file));
+    const round = rest.length > 0 ? await this.#bunBuild(rest, true) : { modules: [], misses: [], tangled: [] };
+    for (const file of failed) {
+      const text = (reasons.get(CsrDevPaths.realpath(file)) ?? []).join("; ");
+      const awaits = text.includes('"await" can only be used');
+      round.modules.push(
+        this.#leftOut(file, awaits ? `a top-level await, which a CommonJS factory cannot wait on: ${text}` : text),
+      );
+    }
+    return round;
+  }
+
+  #leftOut(file: string, problem: string): CsrDevCompiledModule {
+    const real = CsrDevPaths.realpath(file);
+    const id = this.#paths.idOf(real);
+    this.#app.logger.error(`[csr-dev] ${id} is left out of the dev registry: ${problem}`);
+    return {
+      id,
+      file: real,
+      vendor: true,
+      factory: CsrDevFactoryCheck.thrower(id, problem),
+      helpers: null,
+      deps: [],
+      mtimeMs: CsrDevPaths.mtimeOf(real),
+      hash: "",
+    };
+  }
+
+  //? Bun applies `define` to the modules a macro imports too, and runs them in this process, where the `import.meta`
+  //? rewrite leaves a free `__akanMeta` that no factory header declares. So a file importing a macro has its macros run
+  //? first by a build of its own, with every other import left as written, and the module build reads that output.
+  async #evaluateMacros(files: string[]): Promise<Map<string, string>> {
+    const sources = await Promise.all(files.map(async (file) => [file, await Bun.file(file).text()] as const));
+    const importers = sources.filter(([, source]) => CsrDevModuleCompiler.#macroImport.test(source));
+    const outputs = await Promise.all(
+      importers.map(async ([file]) => {
+        const result = await Bun.build({
+          entrypoints: [file],
+          target: "browser",
+          format: "esm",
+          plugins: [
+            {
+              name: "akan-csr-macro-pass",
+              setup: (build) =>
+                void build.onResolve({ filter: /.*/ }, (args) =>
+                  args.importer ? { path: args.path, external: true } : undefined,
+                ),
+            },
+          ],
+        });
+        const [output] = result.outputs;
+        if (!output) throw new Error(`[csr-dev] ${this.#paths.idOf(file)}: its macro pass wrote no output`);
+        const text = await output.text();
+        return [
+          [file, text],
+          [CsrDevPaths.realpath(file), text],
+        ] as const;
+      }),
+    );
+    return new Map(outputs.flat());
+  }
+
+  #registryPlugin(vendor: boolean, misses: string[], macroOutputs: Map<string, string>): BunPlugin {
     return {
       name: "akan-csr-registry",
       setup: (build) => {
         build.onLoad({ filter: /\.css$/ }, () => ({ contents: "", loader: "js" }));
+        if (macroOutputs.size > 0) {
+          const exact = [...macroOutputs.keys()].map((file) => file.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"));
+          build.onLoad({ filter: new RegExp(`^(?:${exact.join("|")})$`) }, (args) => {
+            const contents = macroOutputs.get(args.path);
+            return contents === undefined ? undefined : { contents, loader: "js" };
+          });
+        }
         if (!vendor)
           build.onLoad({ filter: /\.tsx$/ }, async (args) => {
             if (CsrDevPaths.isVendorFile(args.path)) return undefined;
@@ -261,7 +366,11 @@ export class CsrDevModuleCompiler {
   // Every rewrite keeps the line count, so a module's source map still lines up inside the factory.
   static #factory(id: string, code: string): { factory: string; helpers: CsrDevSharedHelpers | null } {
     const prefix = CsrDevPaths.modulePrefix;
-    let patched = code.replaceAll(`import("${prefix}`, `__akanImport("${prefix}`).replace(/^\/\/# debugId=.*$/m, "");
+    //? Bun keeps a package's `#!` line atop its output, where a script inside a function cannot have one.
+    let patched = code
+      .replace(/^#!/, "//")
+      .replaceAll(`import("${prefix}`, `__akanImport("${prefix}`)
+      .replace(/^\/\/# debugId=.*$/m, "");
     //? A file esbuild already bundled (mermaid's parser chunks) defines its own helper under the same name, below Bun's
     //? preamble, and Bun then emits none. Only a copy there is exempt: one in the preamble is Bun's own, changed.
     const marker = patched.search(/^\/\/ /m);
@@ -279,8 +388,13 @@ export class CsrDevModuleCompiler {
     // re-running the store root is the whole update, and bubbling past it would only reach the page modules.
     if (CsrDevModuleCompiler.#storeRoot.test(id)) patched += "\nmodule.hot.accept();";
     const shared = CsrDevModuleCompiler.#shareHelpers(patched);
+    //? What `import.meta` is in a browser module: a `url` and no `env`, so `import.meta.env` checks (jotai, zustand)
+    //? branch as they do in the ESM bundle. On the header line, outside the preamble that modules share.
+    const meta = /(?<![\w$.])__akanMeta(?![\w$])/.test(patched)
+      ? ` var __akanMeta = { url: new URL(${JSON.stringify(id.startsWith("/") ? id : `/${id}`)}, self.location.href).href };`
+      : "";
     return {
-      factory: `function (require, module, exports, $RefreshReg$, $RefreshSig$, __akanImport) {\n${shared?.code ?? patched}\n}`,
+      factory: `function (require, module, exports, $RefreshReg$, $RefreshSig$, __akanImport) {${meta}\n${shared?.code ?? patched}\n}`,
       helpers: shared?.helpers ?? null,
     };
   }

package/frontendBuild/csrDevPaths.ts

@@ -4,6 +4,7 @@ import path from "node:path";
 export class CsrDevPaths {
   static readonly modulePrefix = "akan-module:";
   static readonly stubPrefix = "stub:";
+  static readonly emptyStubPrefix = "stub:empty:";
   static readonly vendorPrefix = "vendor:";
   readonly root: string;
 

package/frontendBuild/csrDevResolver.ts

@@ -15,6 +15,12 @@ interface PrepassMetafile {
   inputs: Record<string, { imports: MetafileImport[] }>;
 }
 
+interface BrowserMap {
+  /** What the `browser` object maps to `false`: an empty module in a browser build. */
+  offFiles: Set<string>;
+  offNames: Set<string>;
+}
+
 export interface CsrDevResolverOptions {
   paths: CsrDevPaths;
   context: CsrDevContext;
@@ -36,7 +42,9 @@ export class CsrDevResolver {
   readonly #resolution = new Map<string, Map<string, string>>();
   readonly #fallbacks = new Set<string>();
   readonly #runtimeResolved = new Map<string, Set<string>>();
-  readonly #browserMaps = new Map<string, boolean>();
+  readonly #browserMaps = new Map<string, BrowserMap | null>();
+  /** Files a browser build loaded, so every import they make has its browser resolution recorded. */
+  readonly #loaded = new Set<string>();
   readonly #startedAt: number;
   #prepassDone = false;
 
@@ -85,9 +93,52 @@ export class CsrDevResolver {
       optimizeImports: this.#context.optimizeImports,
       plugins: [PagesBundleBuilder.createCssStubPlugin()],
     });
-    const { inputs } = result.metafile as unknown as PrepassMetafile;
+    this.#record((result.metafile as unknown as PrepassMetafile).inputs);
+    this.#prepassDone = true;
+  }
+
+  //? The browser build drops a side-effect-free barrel's unused re-exports without loading them, yet the registry
+  //? compiles every file an import names. Such a file's own imports are resolved by a browser build of its own, one
+  //? level deep, not by the runtime resolver's Node conditions (vfile's `#minpath` would reach `node:path`).
+  async cover(files: string[]): Promise<void> {
+    if (!this.#prepassDone) return;
+    const pending = files.filter((file) => CsrDevPaths.isScript(file) && !this.#loaded.has(file));
+    if (pending.length === 0) return;
+    for (const file of pending) this.#loaded.add(file);
+    const entries = new Set(pending);
+    const result = await Bun.build({
+      entrypoints: pending,
+      target: "browser",
+      metafile: true,
+      throw: false,
+      external: [...(this.#context.externals ?? [])],
+      env: "AKAN_PUBLIC_*",
+      define: this.#context.define,
+      plugins: [
+        {
+          name: "akan-csr-cover",
+          //? What an entry imports is resolved, never parsed: a CommonJS stub, since an empty ESM module fails a named
+          //? import ("No matching export") and a failed build hands back no metafile at all.
+          setup: (build) => {
+            build.onLoad({ filter: /.*/ }, (args) =>
+              entries.has(CsrDevPaths.realpath(args.path))
+                ? undefined
+                : { contents: "module.exports = {};", loader: "js" },
+            );
+          },
+        },
+      ],
+    });
+    //? Left unrecorded when the build fails: those imports keep the runtime resolver's answer, as before.
+    if (result.metafile) this.#record((result.metafile as unknown as PrepassMetafile).inputs, entries);
+  }
+
+  #record(inputs: PrepassMetafile["inputs"], only?: Set<string>): void {
     for (const [input, { imports }] of Object.entries(inputs)) {
       const importer = CsrDevPaths.realpath(path.resolve(input));
+      if (only && !only.has(importer)) continue;
+      //? A re-export the build tree-shook keeps no specifier, so its file is resolved again as an entry of its own.
+      if (imports.every((record) => record.original)) this.#loaded.add(importer);
       for (const record of imports) {
         if (!record.original) continue;
         if (record.external) {
@@ -101,11 +152,12 @@ export class CsrDevResolver {
         this.#runtimeResolved.get(importer)?.delete(record.original);
       }
     }
-    this.#prepassDone = true;
   }
 
   resolve(importer: string, specifier: string, kind: "import" | "require" = "import"): string | null {
     if (this.#isInlineSpecifier(specifier)) return CsrDevResolver.inline;
+    const disabled = this.#disabledInBrowser(importer, specifier, kind);
+    if (disabled) return disabled;
     const known = this.#resolution.get(importer)?.get(specifier);
     const usable = known && this.#stillAnswers(importer, specifier, known, kind) ? known : null;
     const target = usable ?? this.#resolveUnknown(importer, specifier, kind);
@@ -139,23 +191,51 @@ export class CsrDevResolver {
     });
   }
 
+  //? `false` in a package's `browser` object is an empty module to a browser build (object-inspect's
+  //? `./util.inspect.js`, which requires `util`). Its record carries no specifier, so the field is read here.
+  #disabledInBrowser(importer: string, specifier: string, kind: "import" | "require"): string | null {
+    const map = this.#browserMapOf(path.dirname(importer));
+    if (!map || (map.offFiles.size === 0 && map.offNames.size === 0)) return null;
+    if (!specifier.startsWith(".") && !path.isAbsolute(specifier))
+      return map.offNames.has(specifier) ? `${CsrDevPaths.emptyStubPrefix}${specifier}` : null;
+    const target = CsrDevPaths.resolveRelative(path.dirname(importer), specifier, kind);
+    return target && map.offFiles.has(CsrDevPaths.realpath(target))
+      ? `${CsrDevPaths.emptyStubPrefix}${this.#paths.idOf(target)}`
+      : null;
+  }
+
   #hasBrowserMap(dir: string): boolean {
+    return this.#browserMapOf(dir) !== null;
+  }
+
+  #browserMapOf(dir: string): BrowserMap | null {
     const cached = this.#browserMaps.get(dir);
     if (cached !== undefined) return cached;
     const pkgFile = path.join(dir, "package.json");
     const parent = path.dirname(dir);
-    let mapped: boolean;
+    let map: BrowserMap | null = null;
     if (fs.existsSync(pkgFile)) {
       try {
         const browser = (JSON.parse(fs.readFileSync(pkgFile, "utf8")) as { browser?: unknown }).browser;
-        mapped = typeof browser === "object" && browser !== null;
+        if (typeof browser === "object" && browser !== null) {
+          const off = Object.entries(browser)
+            .filter(([, target]) => target === false)
+            .map(([key]) => key);
+          const files = off
+            .filter((key) => key.startsWith("."))
+            .map((key) => CsrDevPaths.resolveRelative(dir, key))
+            .filter((file): file is string => !!file);
+          map = {
+            offFiles: new Set(files.map((file) => CsrDevPaths.realpath(file))),
+            offNames: new Set(off.filter((key) => !key.startsWith("."))),
+          };
+        }
       } catch {
         // An unreadable package.json maps nothing; Bun's build fails on it anyway.
-        mapped = false;
       }
-    } else mapped = parent !== dir && this.#hasBrowserMap(parent);
-    this.#browserMaps.set(dir, mapped);
-    return mapped;
+    } else if (parent !== dir) map = this.#browserMapOf(parent);
+    this.#browserMaps.set(dir, map);
+    return map;
   }
 
   /** A module that left the graph takes its records with it. */

package/frontendBuild/ssrBaseArtifactBuilder.ts

@@ -1,6 +1,6 @@
 import path from "node:path";
 import { optimize } from "@tailwindcss/node";
-import type { AkanWebConfig } from "akanjs";
+import type { AkanMobileAppId, AkanWebConfig } from "akanjs";
 import type { BaseBuildArtifact } from "akanjs/server";
 import { resolveSsrPageEntriesForApp } from "../artifact/implicitRootLayout";
 import { computeRouteSeedIndex, type RouteSeedIndex, saveRouteSeedIndex } from "../artifact/routeSeedIndex";
@@ -89,7 +89,8 @@ export class SsrBaseArtifactBuilder {
         .filter((target) => (target.deepLinks?.domains?.length ?? 0) > 0)
         .map((target) => ({
           targetName: target.name,
-          appId: target.appId,
+          iosAppId: SsrBaseArtifactBuilder.#appIdOn(target.appId, "ios"),
+          androidAppId: SsrBaseArtifactBuilder.#appIdOn(target.appId, "android"),
           domains: target.deepLinks?.domains ?? [],
           iosTeamId: target.deepLinks?.ios?.teamId,
           androidSha256CertFingerprints: target.deepLinks?.android?.sha256CertFingerprints,
@@ -223,6 +224,10 @@ export class SsrBaseArtifactBuilder {
   }
 
   // Checked against the written asset, not the compiled text: it is the only stylesheet an SSR render serves.
+  static #appIdOn(appId: AkanMobileAppId, platform: "ios" | "android"): string | null {
+    return typeof appId === "string" ? appId : (appId[platform] ?? appId.default ?? null);
+  }
+
   static #warnDroppedImports(app: App, cssRelPath: string, css: string, imported: ImportedStylesheet[]) {
     for (const { cssPath, declaredNames } of imported) {
       if (declaredNames.length === 0 || declaredNames.some((name) => css.includes(`${name}:`))) continue;