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

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";

package/frontendBuild/routeClientBuilder.ts

@@ -2,6 +2,7 @@ import { mkdir } from "node:fs/promises";
 import path from "node:path";
 import type { BaseBuildArtifact, ClientManifest, ClientManifestEntry, SsrManifest } from "akanjs/server";
 import { SSR_DEV_CHUNK, SSR_DEV_ID_PREFIX } from "akanjs/server/hmr/csrDevManifest";
+import { StoreBootstrap } from "../artifact/storeBootstrap";
 import type { App } from "../commandDecorators";
 import { createBarrelImportsPlugin } from "../transforms/barrelImportsPlugin";
 import { loaderFor } from "../transforms/moduleSyntax";
@@ -26,7 +27,7 @@ export interface BuildRouteClientOptions {
   seeds: string[];
   /** Every route's seeds: a build that runs at all bundles the whole app, since two builds each copy shared modules. */
   graphSeeds?: string[];
-  artifact: BaseBuildArtifact;
+  artifact?: BaseBuildArtifact;
   knownEntries?: Set<string>;
   routeId?: string;
   command?: "build" | "start";
@@ -46,6 +47,8 @@ export interface BuildRouteClientResult {
   clientDepsByEntry?: Record<string, string[]>;
   /** Registry mode: the entries the manifest rows name, which the SSR dev registry must hold before they are served. */
   registryEntries?: string[];
+  /** Chunks mode: the importmap specifiers each browser chunk imports statically. */
+  externalsByChunkUrl?: Record<string, string[]>;
 }
 
 interface BootstrapEntries {
@@ -133,6 +136,7 @@ export class RouteClientBuilder {
       clientDeps: [...clientDeps].sort(),
       clientDepsByEntry,
       ...(registry ? { registryEntries: [...acceptedEntries].sort() } : {}),
+      ...(browserBundle ? { externalsByChunkUrl: Object.fromEntries(browserBundle.externalsByChunkUrl) } : {}),
     };
   }
 
@@ -317,7 +321,7 @@ export class RouteClientBuilder {
     const originalEntry = JSON.stringify(path.resolve(args.originalEntry));
     const namedExports = args.exportNames.filter((name) => name !== "default");
     const lines = [
-      `import ${JSON.stringify(`@apps/${args.appName}/client`)};`,
+      ...StoreBootstrap.importLines(args.appName),
       ...(namedExports.length > 0 ? [`export { ${namedExports.join(", ")} } from ${originalEntry};`] : []),
     ];
     if (args.exportNames.includes("default")) lines.push(`export { default } from ${originalEntry};`);

package/frontendBuild/routeModulePreloads.test.ts

@@ -0,0 +1,59 @@
+import { describe, expect, test } from "bun:test";
+import path from "node:path";
+import { RouteModulePreloads } from "./routeModulePreloads";
+
+describe("RouteModulePreloads", () => {
+  const root = "/repo";
+  const entry = (name: string) => path.join(root, `apps/demo/ui/${name}.tsx`);
+  const row = (...chunks: string[]) => ({
+    id: chunks[0] ?? "",
+    chunks: chunks.flatMap((chunk) => [chunk, chunk]),
+    name: "default",
+  });
+  const preloads = new RouteModulePreloads({
+    runtimeChunks: {
+      runtime: ["/_akan/client/rsc.js"],
+      vendors: { react: ["/_akan/client/react.js"], "akanjs/store": ["/_akan/client/store.js"] },
+    },
+    entriesByRoute: new Map([
+      ["/:lang", [entry("Home")]],
+      ["/:lang/memo", [entry("Home"), entry("Memo")]],
+    ]),
+    clientManifest: {
+      "apps/demo/ui/Home.tsx#default": row("/_akan/client/home.js", "/_akan/client/chunks/s.js"),
+      "apps/demo/ui/Memo.tsx#default": row("/_akan/client/memo.js", "/_akan/client/chunks/s.js"),
+    },
+    externalsByChunkUrl: {
+      "/_akan/client/home.js": ["react"],
+      "/_akan/client/memo.js": ["akanjs/store", "node:fs"],
+      "/_akan/client/chunks/s.js": [],
+    },
+    workspaceRoot: root,
+  });
+
+  test("keeps only importmap specifiers, and only for chunks that import one", () => {
+    expect(preloads.table.chunkVendors).toEqual({
+      "/_akan/client/home.js": ["react"],
+      "/_akan/client/memo.js": ["akanjs/store"],
+    });
+  });
+
+  test("lists what each route can load: the runtime, its vendors, then its chunks", () => {
+    expect(preloads.modulesByRoute()).toEqual({
+      "/:lang": [
+        "/_akan/client/rsc.js",
+        "/_akan/client/react.js",
+        "/_akan/client/home.js",
+        "/_akan/client/chunks/s.js",
+      ],
+      "/:lang/memo": [
+        "/_akan/client/rsc.js",
+        "/_akan/client/react.js",
+        "/_akan/client/store.js",
+        "/_akan/client/home.js",
+        "/_akan/client/chunks/s.js",
+        "/_akan/client/memo.js",
+      ],
+    });
+  });
+});

package/frontendBuild/routeModulePreloads.ts

@@ -0,0 +1,52 @@
+import type { ClientManifest } from "akanjs/server";
+import { ModulePreloadPlan, type ModulePreloadTable } from "akanjs/server/artifact/modulePreloadPlan";
+import { toClientReferencePath } from "../transforms/rscUseClientTransform";
+
+export type RuntimeChunks = Pick<ModulePreloadTable, "runtime" | "vendors">;
+
+export interface RouteModulePreloadsInput {
+  runtimeChunks: RuntimeChunks;
+  entriesByRoute: Map<string, string[]>;
+  clientManifest: ClientManifest;
+  externalsByChunkUrl: Record<string, string[]>;
+  workspaceRoot: string;
+}
+
+export class RouteModulePreloads {
+  readonly table: ModulePreloadTable;
+  #input: RouteModulePreloadsInput;
+  #chunksByReferenceId = new Map<string, Set<string>>();
+
+  constructor(input: RouteModulePreloadsInput) {
+    this.#input = input;
+    for (const [key, row] of Object.entries(input.clientManifest)) {
+      const chunks = this.#chunksByReferenceId.getOrInsert(key.slice(0, key.lastIndexOf("#")), new Set());
+      for (const url of row.chunks) chunks.add(url);
+    }
+    this.table = {
+      ...input.runtimeChunks,
+      chunkVendors: Object.fromEntries(
+        Object.entries(input.externalsByChunkUrl)
+          .map(([url, specifiers]): [string, string[]] => [
+            url,
+            specifiers.filter((specifier) => specifier in input.runtimeChunks.vendors),
+          ])
+          .filter(([, specifiers]) => specifiers.length > 0),
+      ),
+    };
+  }
+
+  modulesByRoute(): Record<string, string[]> {
+    const plan = new ModulePreloadPlan(this.table);
+    return Object.fromEntries(
+      [...this.#input.entriesByRoute].map(([routeId, entries]) => [
+        routeId,
+        plan.urlsOf(
+          entries.flatMap((entry) => [
+            ...(this.#chunksByReferenceId.get(toClientReferencePath(entry, this.#input.workspaceRoot)) ?? []),
+          ]),
+        ),
+      ]),
+    );
+  }
+}

package/frontendBuild/ssrBaseArtifactBuilder.ts

@@ -12,13 +12,16 @@ import { DictionaryAssetBuilder } from "./dictionaryAssetBuilder";
 import { FontOptimizer } from "./fontOptimizer";
 import { PagesBundleBuilder } from "./pagesBundleBuilder";
 import { RouteClientBuilder } from "./routeClientBuilder";
-import { VENDOR_SPECIFIERS, type VendorSpecifier } from "./vendorSpecifiers";
+import type { RuntimeChunks } from "./routeModulePreloads";
+import { VendorNarrowing } from "./vendorNarrowing";
+import type { VendorSpecifier } from "./vendorSpecifiers";
 
 export interface BuildSsrBaseArtifactResult {
   artifact: BaseBuildArtifact;
   seedIndex: RouteSeedIndex;
   cssCompiler: CssCompiler;
   optimizedFonts: Awaited<ReturnType<FontOptimizer["optimize"]>>;
+  runtimeChunks: RuntimeChunks;
 }
 
 export function prepareCssAsset(command: "build" | "start", basePath: string, cssText: string): string {
@@ -32,12 +35,24 @@ export class SsrBaseArtifactBuilder {
   #absArtifactDir: string;
   #started = Date.now();
   #serverEnv: BunPlugin | undefined;
+  #vendorExports: Partial<Record<VendorSpecifier, readonly string[]>>;
 
-  /** `serverEnv`: the build's server env plugin, so the route bundle carries the env files the backend does and no more. */
-  constructor(app: App, command: "build" | "start" = "start", { serverEnv }: { serverEnv?: BunPlugin } = {}) {
+  /**
+   * `serverEnv`: the build's server env plugin, so the route bundle carries the env files the backend does and no more.
+   * `vendorExports`: the only names a vendor entry exports, for a build whose every client module is already bundled.
+   */
+  constructor(
+    app: App,
+    command: "build" | "start" = "start",
+    {
+      serverEnv,
+      vendorExports = {},
+    }: { serverEnv?: BunPlugin; vendorExports?: Partial<Record<VendorSpecifier, readonly string[]>> } = {},
+  ) {
     this.#app = app;
     this.#command = command;
     this.#serverEnv = serverEnv;
+    this.#vendorExports = vendorExports;
     this.#artifactDir = `${command === "build" ? app.dist.cwdPath : app.cwdPath}/.akan/artifact`;
     this.#absArtifactDir = path.resolve(this.#artifactDir);
   }
@@ -50,7 +65,7 @@ export class SsrBaseArtifactBuilder {
 
   async build(): Promise<BuildSsrBaseArtifactResult> {
     const akanConfig = await this.#app.getConfig();
-    const { rscClientUrl, rscRuntimeClientManifest, rscRuntimeSsrManifest, vendorMap } =
+    const { rscClientUrl, rscRuntimeClientManifest, rscRuntimeSsrManifest, vendorMap, runtimeChunks } =
       await this.#buildRuntimeClientEntries();
     const pageKeys = await this.#app.getPageKeys();
     this.#app.verbose(`[base-artifact] discovered ${pageKeys.length} route files under ${this.#app.cwdPath}/page`);
@@ -106,23 +121,28 @@ export class SsrBaseArtifactBuilder {
     await Bun.write(path.join(this.#absArtifactDir, "base-artifact.json"), `${JSON.stringify(artifact, null, 2)}\n`);
     this.#app.verbose(`[base-artifact] complete in ${Date.now() - this.#started}ms`);
 
-    return { artifact, seedIndex, cssCompiler, optimizedFonts };
+    return { artifact, seedIndex, cssCompiler, optimizedFonts, runtimeChunks };
   }
 
   async #buildRuntimeClientEntries(): Promise<
     Pick<BaseBuildArtifact, "rscClientUrl" | "rscRuntimeClientManifest" | "rscRuntimeSsrManifest"> & {
       vendorMap: Record<VendorSpecifier, string>;
+      runtimeChunks: RuntimeChunks;
     }
   > {
     const akanServerPath = await this.#resolveAkanServerPath();
     const rscClientEntry = path.resolve(akanServerPath, "rscClient.tsx");
     const rscSegmentOutletEntry = path.resolve(akanServerPath, "rscSegmentOutlet.tsx");
-    const vendorEntries = VENDOR_SPECIFIERS.map((specifier) => ({
-      specifier,
-      absPath: path.resolve(akanServerPath, "vendor", `${specifier.replaceAll("/", "-").replaceAll(".", "-")}.ts`),
-    }));
+    const vendorEntries = VendorNarrowing.entriesIn(akanServerPath);
     const entries = [rscClientEntry, rscSegmentOutletEntry, ...vendorEntries.map((v) => v.absPath)];
-    const clientBundle = await new ClientEntriesBundler({ app: this.#app, entries, command: this.#command }).bundle();
+    const narrowing = new VendorNarrowing(path.dirname(akanServerPath), this.#vendorExports);
+    const clientBundle = await new ClientEntriesBundler({
+      app: this.#app,
+      entries,
+      command: this.#command,
+      entryExports: narrowing.entryExports(vendorEntries),
+      plugins: await narrowing.plugins(),
+    }).bundle();
     const ssrBundle = await new ClientEntriesBundler({
       app: this.#app,
       entries: [rscSegmentOutletEntry],
@@ -158,11 +178,16 @@ export class SsrBaseArtifactBuilder {
       vendorEntries.map(({ specifier, absPath }) => [specifier, clientBundle.entryUrlsByAbsPath.get(absPath) ?? ""]),
     ) as Record<VendorSpecifier, string>;
     this.#app.verbose(`[base-artifact] rscClientUrl=${rscClientUrl} vendors=${Object.keys(vendorMap).length}`);
+    const chunksOf = (absPath: string) => clientBundle.entryChunkUrlsByAbsPath.get(absPath) ?? [];
     return {
       rscClientUrl,
       rscRuntimeClientManifest: clientBundle.manifest,
       rscRuntimeSsrManifest,
       vendorMap,
+      runtimeChunks: {
+        runtime: [...new Set([...chunksOf(rscClientEntry), ...chunksOf(rscSegmentOutletEntry)])],
+        vendors: Object.fromEntries(vendorEntries.map(({ specifier, absPath }) => [specifier, chunksOf(absPath)])),
+      },
     };
   }
   async #resolveAkanServerPath() {