@akanjs/devkit 3.1.2-rc.4 → 3.2.0-rc.0

package/frontendBuild/buildRouteClient.test.ts

@@ -1,4 +1,5 @@
 import { describe, expect, test } from "bun:test";
+import { realpath } from "node:fs/promises";
 import path from "node:path";
 import { tempDirs, writeText as write } from "../testHelpers";
 import { createTsconfigPackageResolver } from "../transforms/barrelImportsPlugin";
@@ -9,8 +10,86 @@ import { RouteClientBuilder } from "./routeClientBuilder";
 
 const makeTempRoot = tempDirs("akan-client-entry-");
 
+const fixtureBarrels = ["@apps/demo/client", "@libs/kit/client"];
+
+const writeBarrelFixture = async () => {
+  const root = await makeTempRoot();
+  const appDir = path.join(root, "apps/demo");
+  const libDir = path.join(root, "libs/kit");
+  const paths = { "@apps/*": ["./apps/*"], "@libs/*": ["./libs/*"] };
+  await write(path.join(root, "tsconfig.json"), JSON.stringify({ compilerOptions: { baseUrl: ".", paths } }));
+  const writeSys = async (dir: string, prefix: string, modules: string[]) => {
+    await write(
+      path.join(dir, "client.ts"),
+      [
+        'export * as cnst from "./lib/cnst";',
+        'export { msg, Err, usePage, fetch, sig } from "./lib/useClient";',
+        'export { st, RootStore } from "./lib/st";',
+        'export * as store from "./lib/st";',
+        ...modules.map((name) => `export { ${name} } from "./lib/${name.toLowerCase()}";`),
+        "",
+      ].join("\n"),
+    );
+    await write(
+      path.join(dir, "lib/useClient.ts"),
+      `const runtime = Object.freeze({ mark: "${prefix}runtime-marker", msg: 1, Err: 2, usePage: 3, fetch: 4, sig: 5 });\nexport const { msg, Err, usePage, fetch, sig } = runtime;\n`,
+    );
+    await write(
+      path.join(dir, "lib/cnst.ts"),
+      `export const Sample = Object.freeze({ mark: "${prefix}cnst-marker" });\n`,
+    );
+    for (const name of modules)
+      await write(
+        path.join(dir, `lib/${name.toLowerCase()}/index.ts`),
+        `import * as Zone from "./${name}.Zone";\nexport const ${name} = { Zone };\n`,
+      );
+  };
+  await writeSys(libDir, "lib-", ["Widget"]);
+  await write(
+    path.join(libDir, "lib/st.ts"),
+    'export class RootStore {}\nexport const st = Object.freeze({ mark: "lib-store-marker" });\n',
+  );
+  await write(
+    path.join(libDir, "lib/widget/Widget.Zone.tsx"),
+    '"use client";\nexport const Card = Object.freeze({ mark: "lib-ui-marker" });\n',
+  );
+  await write(
+    path.join(libDir, "ui/Field.tsx"),
+    '"use client";\nimport { cnst as kitCnst } from "@libs/kit/client";\nexport const Field = () => [kitCnst.Sample, "field-marker"];\n',
+  );
+  await writeSys(appDir, "", ["Memo", "Other"]);
+  await write(
+    path.join(appDir, "lib/st.ts"),
+    'import { RootStore as kit } from "@libs/kit/client";\nexport class RootStore {}\nexport const st = Object.freeze({ mark: "store-marker", kit });\n',
+  );
+  await write(
+    path.join(appDir, "lib/memo/Memo.Zone.tsx"),
+    '"use client";\nimport { type cnst, Memo, st } from "@apps/demo/client";\nexport const Card = (props: { sample?: typeof cnst.Sample }) => [st, Memo, props, "memo-ui-marker"];\n',
+  );
+  await write(
+    path.join(appDir, "lib/other/Other.Zone.tsx"),
+    '"use client";\nexport const Card = Object.freeze({ mark: "other-ui-marker" });\n',
+  );
+  await write(path.join(appDir, "ui/A.tsx"), '"use client";\nexport const A = () => "a";\n');
+  const app = {
+    name: "demo",
+    cwdPath: appDir,
+    dist: { cwdPath: path.join(root, "dist/apps/demo") },
+    workspace: { workspaceRoot: root },
+    getConfig: async () => ({ barrelImports: fixtureBarrels, optimizeImports: [] }),
+    getTsConfig: async () => ({ compilerOptions: { paths } }),
+    getPublicEnv: () => ({}),
+  } as never;
+  return { root, appDir, app };
+};
+
+const bundledText = async (dir: string) =>
+  (
+    await Promise.all([...new Bun.Glob("**/*.js").scanSync(dir)].map((file) => Bun.file(path.join(dir, file)).text()))
+  ).join("\n");
+
 describe("route client store bootstrap", () => {
-  test("wraps client entries with app client bootstrap before re-exporting components", () => {
+  test("wraps client entries with the client runtime and store bootstrap before re-exporting components", () => {
     const original = path.resolve("/repo/pkgs/akanjs/ui/Model/NewWrapper_Client.tsx");
     const source = RouteClientBuilder.createStoreBootstrapEntrySource({
       appName: "akan",
@@ -20,7 +99,8 @@ describe("route client store bootstrap", () => {
 
     expect(source).toBe(
       [
-        'import "@apps/akan/client";',
+        'import "@apps/akan/lib/useClient";',
+        'import "@apps/akan/lib/st";',
         `export { NewWrapper_Client } from ${JSON.stringify(original)};`,
         `export { default } from ${JSON.stringify(original)};`,
         "",
@@ -183,6 +263,116 @@ describe("route client store bootstrap", () => {
     expect(carriers.filter(Boolean)).toHaveLength(1);
   });
 
+  test("names each entry's static chunks and the importmap specifiers every chunk imports", async () => {
+    const root = await realpath(await makeTempRoot());
+    const appDir = path.join(root, "apps/demo");
+    const entryA = path.join(appDir, "ui/A.tsx");
+    const entryB = path.join(appDir, "ui/B.tsx");
+    await write(
+      entryA,
+      '"use client";\nimport { useState } from "react";\nimport { mark } from "../common/shared";\nexport const A = () => [useState, mark];\n',
+    );
+    await write(
+      entryB,
+      '"use client";\nimport { mark } from "../common/shared";\nexport const B = () => import("../common/lazy").then(() => mark);\n',
+    );
+    await write(
+      path.join(appDir, "common/shared.ts"),
+      'import { tag } from "akanjs/base";\nexport const mark = tag;\n',
+    );
+    await write(path.join(appDir, "common/lazy.ts"), 'import "tailwind-merge";\nexport const lazy = 1;\n');
+    const app = {
+      name: "demo",
+      cwdPath: appDir,
+      dist: { cwdPath: path.join(root, "dist/apps/demo") },
+      workspace: { workspaceRoot: root },
+      getConfig: async () => ({ barrelImports: [], optimizeImports: [] }),
+      getPublicEnv: () => ({}),
+    } as never;
+
+    const bundle = await new ClientEntriesBundler({
+      app,
+      entries: [entryA, entryB],
+      external: ["react", "akanjs/base", "tailwind-merge"],
+      command: "build",
+    }).bundle();
+
+    const [urlA, sharedA] = bundle.entryChunkUrlsByAbsPath.get(entryA) ?? [];
+    const [urlB, sharedB] = bundle.entryChunkUrlsByAbsPath.get(entryB) ?? [];
+    expect(bundle.entryChunkUrlsByAbsPath.get(entryA)).toHaveLength(2);
+    expect(bundle.entryChunkUrlsByAbsPath.get(entryB)).toHaveLength(2);
+    expect(sharedA).toBe(sharedB);
+    expect(bundle.externalsByChunkUrl.get(urlA ?? "")).toEqual(["react"]);
+    expect(bundle.externalsByChunkUrl.get(urlB ?? "")).toEqual([]);
+    expect(bundle.externalsByChunkUrl.get(sharedA ?? "")).toEqual(["akanjs/base"]);
+    expect([...bundle.externalsByChunkUrl.values()].flat()).toContain("tailwind-merge");
+  });
+
+  test("a route carries the client runtime and stores, but no module UI it never imports", async () => {
+    const { appDir, app } = await writeBarrelFixture();
+
+    await new RouteClientBuilder({
+      app,
+      seeds: [],
+      entries: [path.join(appDir, "ui/A.tsx")],
+      artifact: {} as never,
+      browser: "chunks",
+    }).build();
+
+    const bundled = await bundledText(path.join(appDir, ".akan/artifact/client"));
+    for (const marker of ["runtime-marker", "store-marker", "lib-runtime-marker", "lib-store-marker"])
+      expect(bundled).toContain(marker);
+    for (const marker of ["memo-ui-marker", "other-ui-marker", "lib-ui-marker"]) expect(bundled).not.toContain(marker);
+  });
+
+  test("a route rendering one module's UI carries no other module's or lib's UI", async () => {
+    const { appDir, app } = await writeBarrelFixture();
+
+    await new RouteClientBuilder({
+      app,
+      seeds: [],
+      entries: [path.join(appDir, "lib/memo/Memo.Zone.tsx")],
+      artifact: {} as never,
+      browser: "chunks",
+    }).build();
+
+    const bundled = await bundledText(path.join(appDir, ".akan/artifact/client"));
+    expect(bundled).toContain("memo-ui-marker");
+    expect(bundled).toContain("store-marker");
+    expect(bundled).not.toContain("other-ui-marker");
+    expect(bundled).not.toContain("lib-ui-marker");
+  });
+
+  test("a route reaching a lib's cnst through its client barrel carries no module UI", async () => {
+    const { root, appDir, app } = await writeBarrelFixture();
+
+    await new RouteClientBuilder({
+      app,
+      seeds: [],
+      entries: [path.join(root, "libs/kit/ui/Field.tsx")],
+      artifact: {} as never,
+      browser: "chunks",
+    }).build();
+
+    const bundled = await bundledText(path.join(appDir, ".akan/artifact/client"));
+    expect(bundled).toContain("field-marker");
+    expect(bundled).toContain("lib-cnst-marker");
+    for (const marker of ["memo-ui-marker", "other-ui-marker", "lib-ui-marker"]) expect(bundled).not.toContain(marker);
+  });
+
+  test("an import of the store through a client barrel discovers no module UI as a client entry", async () => {
+    const { appDir, app } = await writeBarrelFixture();
+    const seed = path.join(appDir, "page/_index.tsx");
+    await write(seed, 'import { st } from "@apps/demo/client";\nexport default function Page() { return st; }\n');
+
+    const discovery = new GraphClientEntryDiscovery(
+      { barrelImports: fixtureBarrels },
+      await createTsconfigPackageResolver(app),
+    );
+
+    expect(await discovery.discover([seed])).toEqual([]);
+  });
+
   test("discovers client entries from installed akanjs package sources", async () => {
     const root = await makeTempRoot();
     const seed = path.join(root, "apps/demo/page/_index.tsx");

package/frontendBuild/bundleDefine.ts

@@ -1,5 +1,9 @@
 import type { App } from "../commandDecorators";
 
+//? A package's `default` export can pick its build by NODE_ENV at run time (Lexical), which keeps every export of that
+//? build; its `production` export is the build itself, so what a page leaves unused is dropped.
+export const bundleConditions = (command: "build" | "start") => (command === "build" ? ["production"] : []);
+
 export const bundleDefine = (app: App, command: "build" | "start", renderEnv: "ssr" | "csr") => {
   const nodeEnv = command === "build" ? "production" : (process.env.NODE_ENV ?? "development");
   return {

package/frontendBuild/clientBuildTypes.ts

@@ -59,6 +59,8 @@ export interface BundleClientEntriesInternalOptions extends BundleClientEntriesO
   externalSubpaths?: readonly string[];
   externalAliases?: Partial<Record<string, string>>;
   command?: "build" | "start";
+  /** Per absolute entry, the only names its alias re-exports, in place of every name the entry declares. */
+  entryExports?: Partial<Record<string, readonly string[]>>;
 }
 
 export interface BundleClientEntriesResult {
@@ -67,12 +69,16 @@ export interface BundleClientEntriesResult {
   entryUrlsByAbsPath: Map<string, string>;
   entryOutputAbsByAbsPath: Map<string, string>;
   entryDepsByAbsPath: Map<string, string[]>;
+  /** Each entry's served URL and the chunks it imports statically, the entry first. */
+  entryChunkUrlsByAbsPath: Map<string, string[]>;
+  externalsByChunkUrl: Map<string, string[]>;
   /** Workspace-relative client reference id per absolute source entry. */
   clientReferenceIdByAbsPath: Map<string, string>;
 }
 
 export type AkanConfig = Awaited<ReturnType<App["getConfig"]>>;
-export type ScannedImport = { path: string; kind?: string };
+export type ScannedImport = { path: string; kind?: string; external?: boolean };
+export type MetafileInput = { imports?: ScannedImport[] };
 export type MetafileOutput = {
   imports: ScannedImport[];
   entryPoint?: string;

package/frontendBuild/clientEntriesBundler.test.ts

@@ -0,0 +1,82 @@
+import { describe, expect, test } from "bun:test";
+import fs from "node:fs";
+import { realpath } from "node:fs/promises";
+import path from "node:path";
+import { tempDirs, writeText } from "../testHelpers";
+import { ClientEntriesBundler } from "./clientEntriesBundler";
+
+const makeTempRoot = tempDirs("akan-client-entries-");
+//? Bun's metafile names real paths, and macOS's temp dir sits behind the /var symlink.
+const realTempRoot = async () => fs.realpathSync(await makeTempRoot());
+
+const vendorApp = async () => {
+  const root = await realTempRoot();
+  const appDir = path.join(root, "apps/demo");
+  const vendor = path.join(root, "vendor/facet.ts");
+  await writeText(path.join(root, "vendor/lib.ts"), "export const real = 1;\nexport const other = 2;\n");
+  await writeText(vendor, 'export * from "./lib";\n');
+  const app = {
+    name: "demo",
+    cwdPath: appDir,
+    dist: { cwdPath: path.join(root, "dist/apps/demo") },
+    workspace: { workspaceRoot: root },
+    getConfig: async () => ({ optimizeImports: [] }),
+    getPublicEnv: () => ({}),
+  } as never;
+  const bundle = (command: "build" | "start", entryExports?: Record<string, string[]>) =>
+    new ClientEntriesBundler({ app, entries: [vendor], command, entryExports }).bundle();
+  return { appDir, vendor, bundle };
+};
+
+describe("ClientEntriesBundler narrowed entries", () => {
+  test("fails the build, naming each name a route imports that its vendor does not export", async () => {
+    const { vendor, bundle } = await vendorApp();
+
+    await expect(bundle("build", { [vendor]: ["real", "notThere"] })).rejects.toThrow("facet.ts: notThere");
+    await expect(bundle("build", { [vendor]: ["real"] })).resolves.toBeDefined();
+  }, 30_000);
+
+  test("writes a narrowed alias apart from the whole one `akan start` keeps for the same entry", async () => {
+    const { appDir, vendor, bundle } = await vendorApp();
+    await bundle("start");
+    await bundle("build", { [vendor]: ["real"] });
+
+    const aliasDir = path.join(appDir, ".akan/generated/client-entry-alias/client");
+    const aliases = await Promise.all(
+      [...new Bun.Glob("*.tsx").scanSync(aliasDir)].map((file) => Bun.file(path.join(aliasDir, file)).text()),
+    );
+
+    expect(aliases).toHaveLength(2);
+    expect(aliases).toContain(ClientEntriesBundler.narrowedAliasSource(vendor, ["real"]));
+  }, 30_000);
+});
+
+describe("ClientEntriesBundler", () => {
+  test("takes a package's production build in a build and its default one under start", async () => {
+    const root = await realpath(await makeTempRoot());
+    await writeText(
+      path.join(root, "node_modules/twobuild/package.json"),
+      '{ "name": "twobuild", "exports": { ".": { "production": "./prod.js", "default": "./switch.js" } } }\n',
+    );
+    await writeText(path.join(root, "node_modules/twobuild/prod.js"), 'export const mark = "prod-build";\n');
+    await writeText(path.join(root, "node_modules/twobuild/switch.js"), 'export const mark = "switch-build";\n');
+    const entry = path.join(root, "Mark.tsx");
+    await writeText(entry, '"use client";\nimport { mark } from "twobuild";\nexport const Mark = () => mark;\n');
+    const app = {
+      name: "probe",
+      cwdPath: path.join(root, "app"),
+      dist: { cwdPath: path.join(root, "dist") },
+      workspace: { workspaceRoot: root },
+      getConfig: async () => ({ optimizeImports: [] }),
+      getPublicEnv: () => ({}),
+    };
+    const bundle = async (command: "build" | "start") => {
+      const result = await new ClientEntriesBundler({ app: app as never, entries: [entry], command }).bundle();
+      const output = result.entryOutputAbsByAbsPath.get(entry);
+      return output ? await Bun.file(output).text() : "";
+    };
+
+    expect(await bundle("build")).toContain("prod-build");
+    expect(await bundle("start")).toContain("switch-build");
+  });
+});

package/frontendBuild/clientEntriesBundler.ts

@@ -3,13 +3,14 @@ import path from "node:path";
 import type { SsrManifest, SsrManifestEntry } from "akanjs/server";
 import type { BunPlugin } from "bun";
 import { scanUseClientExports, toClientReferencePath } from "../transforms/rscUseClientTransform";
-import { bundleDefine } from "./bundleDefine";
+import { bundleConditions, bundleDefine } from "./bundleDefine";
 import {
   type BundleClientEntriesInternalOptions,
   type BundleClientEntriesResult,
   CLIENT_BUNDLE_NAMING,
   type ClientBundleTarget,
   type ClientManifest,
+  type MetafileInput,
   type MetafileOutput,
   type OpaqueEntryAliases,
 } from "./clientBuildTypes";
@@ -21,6 +22,7 @@ export class ClientEntriesBundler {
   #external: readonly string[];
   #externalSubpaths: readonly string[];
   #externalAliases: Partial<Record<string, string>>;
+  #entryExports: Partial<Record<string, readonly string[]>>;
   #command: "build" | "start";
   #target: ClientBundleTarget;
   #outputSubdir: string;
@@ -32,9 +34,11 @@ export class ClientEntriesBundler {
   #entryUrlsByAbsPath = new Map<string, string>();
   #entryOutputAbsByAbsPath = new Map<string, string>();
   #entryDepsByAbsPath = new Map<string, string[]>();
+  #entryChunkUrlsByAbsPath = new Map<string, string[]>();
   #clientReferenceIdByAbsPath = new Map<string, string>();
   #opaqueEntries: OpaqueEntryAliases | null = null;
   #metafileOutputsByAbs = new Map<string, MetafileOutput>();
+  #metafileInputs: Record<string, MetafileInput> = {};
 
   constructor(options: BundleClientEntriesInternalOptions) {
     this.#app = options.app;
@@ -43,6 +47,7 @@ export class ClientEntriesBundler {
     this.#external = options.external ?? [];
     this.#externalSubpaths = options.externalSubpaths ?? [];
     this.#externalAliases = options.externalAliases ?? {};
+    this.#entryExports = options.entryExports ?? {};
     this.#command = options.command ?? "start";
     this.#target = options.target ?? "browser";
     this.#outputSubdir = options.outputSubdir ?? "client";
@@ -64,6 +69,7 @@ export class ClientEntriesBundler {
       naming: CLIENT_BUNDLE_NAMING,
       metafile: true,
       define: bundleDefine(this.#app, this.#command, "ssr"),
+      conditions: bundleConditions(this.#command),
       minify: this.#command === "build",
       optimizeImports: akanConfig.optimizeImports,
       reactFastRefresh: this.#command === "start" && this.#outputSubdir === "client" && this.#reactFastRefresh,
@@ -81,9 +87,11 @@ export class ClientEntriesBundler {
     this.#metafileOutputsByAbs = new Map<string, MetafileOutput>(
       Object.entries(metafile.outputs).map(([k, v]) => [this.#absFromOutdir(k), v as MetafileOutput]),
     );
+    this.#metafileInputs = metafile.inputs as Record<string, MetafileInput>;
 
     for (const artifact of result.outputs.filter((a) => a.kind === "entry-point"))
       this.#addEntryArtifact(artifact.path);
+    this.#assertNarrowedExports();
 
     return {
       manifest: this.#manifest,
@@ -91,6 +99,8 @@ export class ClientEntriesBundler {
       entryUrlsByAbsPath: this.#entryUrlsByAbsPath,
       entryOutputAbsByAbsPath: this.#entryOutputAbsByAbsPath,
       entryDepsByAbsPath: this.#entryDepsByAbsPath,
+      entryChunkUrlsByAbsPath: this.#entryChunkUrlsByAbsPath,
+      externalsByChunkUrl: this.#collectExternalsByChunkUrl(),
       clientReferenceIdByAbsPath: this.#clientReferenceIdByAbsPath,
     };
   }
@@ -102,11 +112,15 @@ export class ClientEntriesBundler {
     const aliasedEntries = await Promise.all(
       this.#entries.map(async (entry) => {
         const absEntry = path.resolve(entry);
-        const hash = Bun.hash(`${this.#app.name}\n${this.#outputSubdir}\n${absEntry}`).toString(36);
-        const aliasPath = path.join(aliasDir, `${hash}.tsx`);
+        const narrowed = this.#entryExports[absEntry];
+        //? `akan build` and `akan start` share this directory, so a narrowed alias never takes the whole one's file.
+        const key = `${this.#app.name}\n${this.#outputSubdir}\n${absEntry}${narrowed ? "\nnarrowed" : ""}`;
+        const aliasPath = path.join(aliasDir, `${Bun.hash(key).toString(36)}.tsx`);
         await Bun.write(
           aliasPath,
-          this.#createOpaqueEntryAliasSource(absEntry, await this.#scanEntryExportNames(absEntry)),
+          narrowed
+            ? ClientEntriesBundler.narrowedAliasSource(absEntry, narrowed)
+            : this.#createOpaqueEntryAliasSource(absEntry, await this.#scanEntryExportNames(absEntry)),
         );
         originalByAlias.set(path.resolve(aliasPath), absEntry);
         return aliasPath;
@@ -124,6 +138,27 @@ export class ClientEntriesBundler {
     return `${lines.join("\n")}\n`;
   }
 
+  //? `export {} from` still loads the entry, so a module only ever imported for its side effects keeps them.
+  static narrowedAliasSource(absEntry: string, names: readonly string[]): string {
+    const list = names.length > 0 ? `{ ${names.join(", ")} }` : "{}";
+    return `export ${list} from ${JSON.stringify(path.resolve(absEntry))};\n`;
+  }
+
+  //? Bun silently drops a name `export { … } from` cannot find behind an `export *`.
+  #assertNarrowedExports(): void {
+    const missing = Object.entries(this.#entryExports).flatMap(([absEntry, names = []]) => {
+      const absOut = this.#entryOutputAbsByAbsPath.get(absEntry);
+      if (!absOut) return [`${path.basename(absEntry)}: no output`];
+      const exported = new Set(this.#metafileOutputsByAbs.get(absOut)?.exports);
+      const absent = names.filter((name) => !exported.has(name));
+      return absent.length > 0 ? [`${path.basename(absEntry)}: ${absent.join(", ")}`] : [];
+    });
+    if (missing.length > 0)
+      throw new Error(
+        `[ClientEntriesBundler] client code imports names its vendor does not export (${missing.join("; ")})`,
+      );
+  }
+
   async #scanEntryExportNames(absEntry: string): Promise<string[]> {
     return scanUseClientExports(await Bun.file(absEntry).text(), absEntry, this.#app.workspace.workspaceRoot);
   }
@@ -220,6 +255,21 @@ export class ClientEntriesBundler {
     return urls;
   }
 
+  //? Bun's metafile lists an external import on the input that wrote it, never on the output chunk.
+  #collectExternalsByChunkUrl(): Map<string, string[]> {
+    const externalsByChunkUrl = new Map<string, string[]>();
+    if (this.#command !== "build" || this.#target !== "browser") return externalsByChunkUrl;
+    for (const [absOut, info] of this.#metafileOutputsByAbs) {
+      if (!absOut.endsWith(".js")) continue;
+      const externals = new Set<string>();
+      for (const input of Object.keys(info.inputs ?? {}))
+        for (const imp of this.#metafileInputs[input]?.imports ?? [])
+          if (imp.external && imp.kind !== "dynamic-import" && !/^[./]/.test(imp.path)) externals.add(imp.path);
+      externalsByChunkUrl.set(this.#toServeUrl(absOut), [...externals].sort());
+    }
+    return externalsByChunkUrl;
+  }
+
   #collectClientDeps(absOutPath: string, visited = new Set<string>()): Set<string> {
     if (visited.has(absOutPath)) return new Set();
     visited.add(absOutPath);
@@ -256,6 +306,7 @@ export class ClientEntriesBundler {
     this.#entryUrlsByAbsPath.set(entryPointAbs, entryUrl);
     this.#entryOutputAbsByAbsPath.set(entryPointAbs, absOut);
     this.#entryDepsByAbsPath.set(entryPointAbs, [...this.#collectClientDeps(absOut)].sort());
+    this.#entryChunkUrlsByAbsPath.set(entryPointAbs, chunkUrls);
     const clientReferenceId = toClientReferencePath(entryPointAbs, this.#app.workspace.workspaceRoot);
     this.#clientReferenceIdByAbsPath.set(entryPointAbs, clientReferenceId);
 

package/frontendBuild/csrArtifactBuilder.test.ts

@@ -62,6 +62,29 @@ console.info(await result.outputs[0].text());
     expect(firstOutput).not.toContain(path.basename(first));
   });
 
+  test("takes a package's production build in a build and its default one under start", async () => {
+    const root = await makeTempRoot();
+    const app = { getPublicEnv: () => ({ AKAN_PUBLIC_ENV: "main" }) };
+    await writeText(
+      path.join(root, "node_modules/twobuild/package.json"),
+      '{ "name": "twobuild", "exports": { ".": { "production": "./prod.js", "default": "./switch.js" } } }\n',
+    );
+    await writeText(path.join(root, "node_modules/twobuild/prod.js"), 'export const mark = "prod-build";\n');
+    await writeText(path.join(root, "node_modules/twobuild/switch.js"), 'export const mark = "switch-build";\n');
+    await writeText(path.join(root, "entry.ts"), 'import { mark } from "twobuild";\nconsole.info(mark);\n');
+    const bundle = async (command: "build" | "start") => {
+      const result = await Bun.build({
+        ...CsrArtifactBuilder.bundleOptions(app as never, command),
+        entrypoints: [path.join(root, "entry.ts")],
+      });
+      expect(result.success).toBe(true);
+      return (await result.outputs[0]?.text()) ?? "";
+    };
+
+    expect(await bundle("build")).toContain("prod-build");
+    expect(await bundle("start")).toContain("switch-build");
+  });
+
   //? The shape of `@lexical/code-prism` under a `lazy()` editor, which threw in every view and CSR shell carrying it.
   test("runs a lazily imported module's CommonJS side-effect import before the imports after it", async () => {
     const root = await makeTempRoot();

package/frontendBuild/csrArtifactBuilder.ts

@@ -6,7 +6,7 @@ import type { App } from "../commandDecorators";
 import { type BarrelImportsPluginOptions, createBarrelImportsPlugin } from "../transforms/barrelImportsPlugin";
 import { createBrowserDirnamePlugin } from "../transforms/browserDirnamePlugin";
 import { SideEffectImportOrder } from "../transforms/sideEffectImportOrder";
-import { bundleDefine } from "./bundleDefine";
+import { bundleConditions, bundleDefine } from "./bundleDefine";
 import { CsrEntryFiles } from "./csrEntryFiles";
 import { type McpAppView, McpAppViewBuilder } from "./mcpAppViewBuilder";
 import { PagesBundleBuilder } from "./pagesBundleBuilder";
@@ -114,6 +114,7 @@ export class CsrArtifactBuilder {
       splitting: false,
       minify: true,
       define: bundleDefine(app, command, "csr"),
+      conditions: bundleConditions(command),
       optimizeImports,
       // A raw `.css` in the route graph is Tailwind source; the base artifact's compiled sheet is the only stylesheet.
       plugins: [PagesBundleBuilder.createCssStubPlugin(), createBrowserDirnamePlugin(), SideEffectImportOrder.plugin()],

package/frontendBuild/fontOptimizer.test.ts

@@ -58,6 +58,18 @@ const chainFontList = (extra = "") => `[\n    ${chainFontEntry(extra)},\n  ]`;
 
 const optimize = (app: App) => new FontOptimizer(app, "start").optimize();
 
+const sizeAdjusts = (css: string) => [...css.matchAll(/size-adjust: ([^;]+);/g)].map((match) => match[1]);
+
+const renameSfntTable = (bytes: Uint8Array, from: string, to: string) => {
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  for (let index = 0; index < view.getUint16(4); index++) {
+    const offset = 12 + index * 16;
+    if (new TextDecoder().decode(bytes.subarray(offset, offset + 4)) === from)
+      bytes.set(new TextEncoder().encode(to), offset);
+  }
+  return bytes;
+};
+
 describe("FontOptimizer cache", () => {
   test("reuses subset output instead of resubsetting an unchanged font", async () => {
     const { app } = await makeApp(layoutWith());
@@ -121,6 +133,48 @@ describe("FontOptimizer cache", () => {
   });
 });
 
+describe("FontOptimizer fallback", () => {
+  test("writes a metric-adjusted fallback face next to the optimized face", async () => {
+    const { app } = await makeApp(layoutWith());
+
+    const { css } = await optimize(app);
+
+    expect(css).toContain('font-family: "Assistant fallback"');
+    expect(sizeAdjusts(css).length).toBeGreaterThan(0);
+    expect(css).toMatch(/ascent-override: [\d.]+%/);
+    expect(css).toMatch(/descent-override: [\d.]+%/);
+  });
+
+  test("sizes the fallback from the source font, so a subset without Latin letters keeps the same size", async () => {
+    const { app: latinApp } = await makeApp(layoutWith());
+    const { app: digitsApp } = await makeApp(layoutWith(`\n    subsets: [],\n    subsetText: "0123456789",`));
+
+    const latin = sizeAdjusts((await optimize(latinApp)).css);
+    const digits = sizeAdjusts((await optimize(digitsApp)).css);
+
+    expect(latin.length).toBeGreaterThan(0);
+    expect(digits).toEqual(latin);
+  });
+
+  test("still writes the face, with no fallback, when the source font's metrics cannot be read", async () => {
+    const { app, cwdPath } = await makeApp(`
+export const fonts = [{ name: "Gilda", paths: [{ src: "/fonts/Gilda.ttf", weight: 400 }] }];
+export default function Layout() {
+  return null;
+}
+`);
+    const source = await Bun.file(path.resolve(path.dirname(SOURCE_FONT), "GildaDisplay-Regular.ttf")).bytes();
+    // capsize reads the average width from the OS/2 table, so without one the metrics read throws.
+    await Bun.write(path.join(cwdPath, "public/fonts/Gilda.ttf"), renameSfntTable(source, "OS/2", "XS/2"));
+
+    const result = await optimize(app);
+
+    expect(result.files).toHaveLength(1);
+    expect(result.css).toContain('font-family: "Gilda"');
+    expect(result.css).not.toContain('font-family: "Gilda fallback"');
+  });
+});
+
 describe("FontOptimizer discovery", () => {
   test("reads the .fonts() stage of a rootLayout() chain", async () => {
     const { app, warnings } = await makeApp(chainLayoutWith(chainFontList()));

package/frontendBuild/fontOptimizer.ts

@@ -39,7 +39,7 @@ export class FontOptimizer {
   #woff2Ready: Promise<void> | null = null;
 
   static #ksX1001Text: string | null = null;
-  static readonly #cacheVersion = 2;
+  static readonly #cacheVersion = 3;
 
   constructor(app: App, command: FontOptimizerCommand = "start") {
     this.#app = app;
@@ -163,7 +163,7 @@ export class FontOptimizer {
       this.#files.push(outputPath);
 
       faceCss.push(this.#buildOptimizedFontFaceRule(font, face));
-      const fallbackCss = await this.#buildFontaineFallbackCss(font, face, outputPath);
+      const fallbackCss = await this.#buildFontaineFallbackCss(font, face, sourcePath);
       if (fallbackCss) faceCss.push(fallbackCss);
     }
 
@@ -468,10 +468,11 @@ export class FontOptimizer {
     return `@font-face {\n${declarations.map(([prop, value]) => `  ${prop}: ${value};`).join("\n")}\n}`;
   }
 
-  async #buildFontaineFallbackCss(font: ReactFont, face: ReactFontFace, outputPath: string) {
+  async #buildFontaineFallbackCss(font: ReactFont, face: ReactFontFace, sourcePath: string) {
     if (font.adjustFontFallback === false) return "";
     const { generateFontFace, getMetricsForFamily, readMetrics, resolveCategoryFallbacks } = await import("fontaine");
-    const metrics = await readMetrics(outputPath).catch(() => null);
+    // The source, not the subset: without Latin glyphs a subset measures .notdef, so xWidthAvg reads as a full em.
+    const metrics = await readMetrics(Bun.pathToFileURL(sourcePath)).catch(() => null);
     if (!metrics) return "";
     const fallbacks = resolveCategoryFallbacks({
       fontFamily: font.name,

package/frontendBuild/index.ts

@@ -18,6 +18,7 @@ export * from "./pagesBundleBuilder";
 export * from "./pagesEntrySourceGenerator";
 export * from "./precompressArtifacts";
 export * from "./routeClientBuilder";
+export * from "./routeModulePreloads";
 export * from "./routesManifestArtifactSerializer";
 export * from "./serverGraphFile";
 export * from "./sourceMtimeIndex";
@@ -25,5 +26,7 @@ export * from "./ssrBaseArtifactBuilder";
 export * from "./ssrDevBundler";
 export * from "./styleContract";
 export * from "./themeValidator";
+export * from "./vendorImportScanner";
+export * from "./vendorNarrowing";
 export * from "./vendorSpecifiers";
 export * from "./watchRootResolver";