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

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() {

package/frontendBuild/ssrDevBundler.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, test } from "bun:test";
+import path from "node:path";
+import { tempDirs, writeText as write } from "../testHelpers";
+import { SsrDevBundler } from "./ssrDevBundler";
+
+const makeTempRoot = tempDirs("akan-ssr-dev-bundler-");
+
+describe("SsrDevBundler bootstrap", () => {
+  const bootstrapOf = async (root: string) => {
+    const appDir = path.join(root, "apps/demo");
+    const app = { name: "demo", cwdPath: appDir, workspace: { workspaceRoot: root } } as never;
+    const { files } = await new SsrDevBundler(app).writeEntries();
+    return await Bun.file(files[SsrDevBundler.bootstrapKey] ?? "").text();
+  };
+
+  test("runs the client runtime and the store, not the client barrel", async () => {
+    const root = await makeTempRoot();
+    await write(path.join(root, "apps/demo/lib/st.ts"), "export const st = {};\n");
+
+    expect(await bootstrapOf(root)).toBe('import "@apps/demo/lib/useClient";\nimport "@apps/demo/lib/st";\n');
+  });
+
+  test("runs nothing for an app without a store", async () => {
+    expect(await bootstrapOf(await makeTempRoot())).toBe("export {};\n");
+  });
+});

package/frontendBuild/ssrDevBundler.ts

@@ -3,6 +3,7 @@ import path from "node:path";
 import { SSR_DEV_DIRNAME, SSR_DEV_ROUTE_PREFIX } from "akanjs/server/hmr/csrDevManifest";
 import { resolveSsrPageEntriesForApp } from "../artifact/implicitRootLayout";
 import { computeRouteSeedIndex } from "../artifact/routeSeedIndex";
+import { StoreBootstrap } from "../artifact/storeBootstrap";
 import type { App } from "../commandDecorators";
 import { bundleDefine } from "./bundleDefine";
 import type { ClientEntryDiscovery } from "./clientBuildTypes";
@@ -58,7 +59,7 @@ export class SsrDevBundler extends DevRegistryBundler {
     await mkdir(this.entryDir, { recursive: true });
     const file = path.join(this.entryDir, "bootstrap.ts");
     const hasStore = await Bun.file(path.join(this.app.cwdPath, "lib", "st.ts")).exists();
-    const source = hasStore ? `import ${JSON.stringify(`@apps/${this.app.name}/client`)};\n` : "export {};\n";
+    const source = hasStore ? StoreBootstrap.source(this.app.name) : "export {};\n";
     const unchanged = (await Bun.file(file).exists()) && (await Bun.file(file).text()) === source;
     if (!unchanged) await Bun.write(file, source);
     const entryFile = CsrDevPaths.realpath(file);

package/frontendBuild/vendorImportScanner.test.ts

@@ -0,0 +1,71 @@
+import { describe, expect, test } from "bun:test";
+import path from "node:path";
+import { tempDirs, writeText as write } from "../testHelpers";
+import { VendorImportScanner } from "./vendorImportScanner";
+
+const makeTempRoot = tempDirs("akan-vendor-imports-");
+const specifiers = ["akanjs/store", "akanjs/common", "akanjs/fetch", "tailwind-merge"];
+const scan = (...sources: string[]) => {
+  const scanner = new VendorImportScanner(specifiers);
+  for (const source of sources) scanner.scan(source);
+  return scanner.usedExports();
+};
+
+describe("VendorImportScanner", () => {
+  test("reads the imported names, not the local aliases, of minified and plain imports", () => {
+    const used = scan(
+      'import{capitalize as He,Logger as K}from"akanjs/common";import{st}from"akanjs/store";',
+      'import { formSetterNames, Logger } from "akanjs/common";\nimport "akanjs/fetch";\n',
+    );
+
+    expect(used).toEqual({
+      "akanjs/store": ["st"],
+      "akanjs/common": ["Logger", "capitalize", "formSetterNames"],
+      "akanjs/fetch": [],
+      "tailwind-merge": [],
+    });
+  });
+
+  test("leaves out a specifier read whole: a namespace import, an export star or a dynamic import", () => {
+    expect(scan('import*as s from"akanjs/store";import{isEmail}from"akanjs/common";')).not.toHaveProperty(
+      "akanjs/store",
+    );
+    expect(scan('export*from"akanjs/store";')).not.toHaveProperty("akanjs/store");
+    expect(scan('export*as s from"akanjs/store";')).not.toHaveProperty("akanjs/store");
+    expect(scan('const load=()=>import("akanjs/store");')).not.toHaveProperty("akanjs/store");
+    expect(scan('export{twMerge as m}from"tailwind-merge";')["tailwind-merge"]).toEqual(["twMerge"]);
+  });
+
+  test("reads nothing from a require, which a browser chunk carries as Bun's shim and never resolves", () => {
+    const used = scan('function C9(){let{untrackedHeaders:n,untrackedRequest:d}=ii("akanjs/fetch");return d}');
+
+    expect(used["akanjs/fetch"]).toEqual([]);
+  });
+
+  test("ignores a specifier quoted in a string, as a docs page shows code", () => {
+    const used = scan(
+      'const sample="import { st } from \\"akanjs/store\\"";const tpl=`export * from "akanjs/store"`;console.info("akanjs/store");',
+    );
+
+    expect(used["akanjs/store"]).toEqual([]);
+  });
+
+  test("collects across every .js file of a directory", async () => {
+    const dir = await makeTempRoot();
+    await write(path.join(dir, "entry-a.js"), 'import{st}from"akanjs/store";');
+    await write(path.join(dir, "chunks/lazy.js"), 'import{RootStore}from"akanjs/store";');
+    await write(path.join(dir, "chunks/lazy.js.map"), 'import{ignored}from"akanjs/store";');
+
+    const used = await VendorImportScanner.exportsUsedIn(dir, ["akanjs/store"]);
+
+    expect(used).toEqual({ "akanjs/store": ["RootStore", "st"] });
+  });
+
+  test("reads a client output directory a build never wrote as importing nothing", async () => {
+    const dir = await makeTempRoot();
+
+    expect(await VendorImportScanner.exportsUsedIn(path.join(dir, "client"), ["akanjs/store"])).toEqual({
+      "akanjs/store": [],
+    });
+  });
+});

package/frontendBuild/vendorImportScanner.ts

@@ -0,0 +1,80 @@
+import fs from "node:fs";
+import path from "node:path";
+import ts from "typescript";
+
+export class VendorImportScanner {
+  readonly #specifiers: Set<string>;
+  readonly #names = new Map<string, Set<string>>();
+  readonly #whole = new Set<string>();
+
+  constructor(specifiers: readonly string[]) {
+    this.#specifiers = new Set(specifiers);
+    for (const specifier of specifiers) this.#names.set(specifier, new Set());
+  }
+
+  /** The names each specifier's importers read across a directory's `.js` files; a specifier read whole is left out. */
+  static async exportsUsedIn(dir: string, specifiers: readonly string[]): Promise<Record<string, string[]>> {
+    const scanner = new VendorImportScanner(specifiers);
+    if (!fs.existsSync(dir)) return scanner.usedExports();
+    for await (const relative of new Bun.Glob("**/*.js").scan({ cwd: dir }))
+      scanner.scan(await Bun.file(path.join(dir, relative)).text(), relative);
+    return scanner.usedExports();
+  }
+
+  scan(source: string, fileName = "chunk.js"): this {
+    if (![...this.#specifiers].some((specifier) => source.includes(specifier))) return this;
+    const file = ts.createSourceFile(fileName, source, ts.ScriptTarget.Latest, false, ts.ScriptKind.JS);
+    const visit = (node: ts.Node): void => {
+      if (ts.isImportDeclaration(node)) this.#readImport(node);
+      else if (ts.isExportDeclaration(node)) this.#readExport(node);
+      else if (ts.isCallExpression(node)) this.#readCall(node);
+      ts.forEachChild(node, visit);
+    };
+    visit(file);
+    return this;
+  }
+
+  usedExports(): Record<string, string[]> {
+    return Object.fromEntries(
+      [...this.#names]
+        .filter(([specifier]) => !this.#whole.has(specifier))
+        .map(([specifier, names]) => [specifier, [...names].sort()]),
+    );
+  }
+
+  #specifierOf(node: ts.Expression | undefined): string | null {
+    if (!node || !ts.isStringLiteralLike(node)) return null;
+    return this.#specifiers.has(node.text) ? node.text : null;
+  }
+
+  #readImport(node: ts.ImportDeclaration): void {
+    const specifier = this.#specifierOf(node.moduleSpecifier);
+    const clause = node.importClause;
+    if (!specifier || !clause) return;
+    if (clause.name) this.#add(specifier, "default");
+    const bindings = clause.namedBindings;
+    if (!bindings) return;
+    if (ts.isNamespaceImport(bindings)) this.#whole.add(specifier);
+    else for (const element of bindings.elements) this.#add(specifier, (element.propertyName ?? element.name).text);
+  }
+
+  #readExport(node: ts.ExportDeclaration): void {
+    const specifier = this.#specifierOf(node.moduleSpecifier);
+    if (!specifier) return;
+    const clause = node.exportClause;
+    if (!clause || ts.isNamespaceExport(clause)) this.#whole.add(specifier);
+    else for (const element of clause.elements) this.#add(specifier, (element.propertyName ?? element.name).text);
+  }
+
+  //? Only `import()` reaches the import map: a `require` left in a browser chunk is Bun's shim, which throws there.
+  #readCall(node: ts.CallExpression): void {
+    if (node.expression.kind !== ts.SyntaxKind.ImportKeyword) return;
+    const specifier = this.#specifierOf(node.arguments[0]);
+    if (specifier) this.#whole.add(specifier);
+  }
+
+  #add(specifier: string, name: string): void {
+    if (!/^[A-Za-z_$][\w$]*$/.test(name)) this.#whole.add(specifier);
+    else this.#names.get(specifier)?.add(name);
+  }
+}

package/frontendBuild/vendorNarrowing.test.ts

@@ -0,0 +1,103 @@
+import { describe, expect, test } from "bun:test";
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { tempDirs, writeText as write } from "../testHelpers";
+import { ClientEntriesBundler } from "./clientEntriesBundler";
+import { VendorNarrowing } from "./vendorNarrowing";
+
+const makeTempRoot = tempDirs("akan-vendor-narrowing-");
+const akanjsRoot = path.resolve(import.meta.dir, "../../../akanjs");
+const vendorFile = (name: string) => path.join(akanjsRoot, "server/vendor", `${name}.ts`);
+const agentOnlyText = "path must be an internal path starting with /.";
+
+const staticClosure = (absPath: string, seen = new Set<string>()): Set<string> => {
+  if (seen.has(absPath)) return seen;
+  seen.add(absPath);
+  const transpiler = new Bun.Transpiler({ loader: "js" });
+  for (const { path: imported, kind } of transpiler.scanImports(readFileSync(absPath, "utf8")))
+    if (kind !== "dynamic-import" && imported.startsWith("."))
+      staticClosure(path.resolve(path.dirname(absPath), imported), seen);
+  return seen;
+};
+const closureText = (absPath: string) =>
+  [...staticClosure(absPath)].map((file) => readFileSync(file, "utf8")).join("\n");
+
+const buildVendors = async (storeNames: string[], plugins: Awaited<ReturnType<VendorNarrowing["plugins"]>>) => {
+  const root = await makeTempRoot();
+  const storeAlias = path.join(root, "store.ts");
+  const agentAlias = path.join(root, "agent.ts");
+  await write(storeAlias, ClientEntriesBundler.narrowedAliasSource(vendorFile("akanjs-store"), storeNames));
+  await write(agentAlias, `export * from ${JSON.stringify(vendorFile("akanjs-store-agent"))};\n`);
+  const result = await Bun.build({
+    entrypoints: [storeAlias, agentAlias],
+    outdir: path.join(root, "out"),
+    splitting: true,
+    target: "browser",
+    format: "esm",
+    plugins,
+  });
+  expect(result.logs.map((log) => log.message)).toEqual([]);
+  const outputOf = (name: string) => {
+    const output = result.outputs.find((o) => o.kind === "entry-point" && path.basename(o.path) === `${name}.js`);
+    if (!output) throw new Error(`no ${name}.js output`);
+    return output.path;
+  };
+  return { store: closureText(outputOf("store")), agent: closureText(outputOf("agent")) };
+};
+
+describe("VendorNarrowing", () => {
+  test("maps each narrowed specifier's vendor entry to its names and leaves the rest whole", () => {
+    const narrowing = new VendorNarrowing(akanjsRoot, { "akanjs/store": ["st"], "akanjs/base": [] });
+
+    expect(
+      narrowing.entryExports([
+        { specifier: "akanjs/store", absPath: "/v/akanjs-store.ts" },
+        { specifier: "akanjs/base", absPath: "/v/akanjs-base.ts" },
+        { specifier: "akanjs/common", absPath: "/v/akanjs-common.ts" },
+      ]),
+    ).toEqual({ "/v/akanjs-store.ts": ["st"], "/v/akanjs-base.ts": [] });
+  });
+
+  test("keeps the deprecated agent re-export when a route imports one of its names, or reads the store whole", async () => {
+    expect(await new VendorNarrowing(akanjsRoot, { "akanjs/store": ["AgentContext", "st"] }).plugins()).toEqual([]);
+    expect(await new VendorNarrowing(akanjsRoot, {}).plugins()).toEqual([]);
+  });
+
+  test("a store vendor no route reads an agent name from loads no agent runtime; the agent vendor does", async () => {
+    const narrowing = new VendorNarrowing(akanjsRoot, { "akanjs/store": ["StoreRegistry", "store"] });
+    const plugins = await narrowing.plugins();
+    expect(plugins).toHaveLength(1);
+
+    const { store, agent } = await buildVendors(["StoreRegistry", "store"], plugins);
+
+    expect(store).not.toContain(agentOnlyText);
+    expect(agent).toContain(agentOnlyText);
+  }, 60_000);
+
+  test("without the blanking, the deprecated re-export drags the agent runtime into the store vendor", async () => {
+    const { store } = await buildVendors(["StoreRegistry", "store"], []);
+
+    expect(store).toContain(agentOnlyText);
+  }, 60_000);
+
+  test("an akanjs older than the agent split keeps whole vendors and gets no agent entry", async () => {
+    const root = await makeTempRoot();
+    for (const name of ["akanjs-store", "akanjs-base"])
+      await write(path.join(root, "server/vendor", `${name}.ts`), `export * from "${name}";\n`);
+    const entries = VendorNarrowing.entriesIn(path.join(root, "server"));
+    const narrowing = new VendorNarrowing(root, { "akanjs/store": ["st"], "akanjs/base": [] });
+
+    expect(entries.map(({ specifier }) => specifier)).toEqual(["akanjs/store", "akanjs/base"]);
+    expect(narrowing.entryExports(entries)).toEqual({});
+    expect(await narrowing.plugins()).toEqual([]);
+    expect(VendorNarrowing.entriesIn(path.join(akanjsRoot, "server")).map(({ specifier }) => specifier)).toContain(
+      "akanjs/store/agent",
+    );
+  });
+
+  test("an alias narrowed to no names still loads its entry, so the entry's side effects run", () => {
+    expect(ClientEntriesBundler.narrowedAliasSource("/v/akanjs-fetch.ts", [])).toBe(
+      `export {} from ${JSON.stringify(path.resolve("/v/akanjs-fetch.ts"))};\n`,
+    );
+  });
+});

package/frontendBuild/vendorNarrowing.ts

@@ -0,0 +1,64 @@
+import fs from "node:fs";
+import path from "node:path";
+import type { BunPlugin } from "bun";
+import { VENDOR_SPECIFIERS, type VendorSpecifier } from "./vendorSpecifiers";
+
+//? Bun puts a module in the chunk of every entry that reaches it, read or not, so a deprecated re-export would keep
+//? its target in a vendor every page loads; a narrowed build blanks it unless a route imports one of its names.
+const deprecatedReexports: Partial<Record<VendorSpecifier, string>> = { "akanjs/store": "store/deprecatedAgent.ts" };
+
+export interface VendorEntry {
+  specifier: VendorSpecifier;
+  absPath: string;
+}
+
+export class VendorNarrowing {
+  readonly #akanjsRoot: string;
+  readonly #vendorExports: Partial<Record<VendorSpecifier, readonly string[]>>;
+
+  //? A devkit newer than the installed akanjs finds no agent vendor or deprecated re-export there, and builds that
+  //? akanjs's vendors whole, as the devkit it shipped with did.
+  static entriesIn(akanServerPath: string): VendorEntry[] {
+    return VENDOR_SPECIFIERS.map((specifier) => ({
+      specifier,
+      absPath: path.resolve(akanServerPath, "vendor", `${specifier.replaceAll("/", "-").replaceAll(".", "-")}.ts`),
+    })).filter(({ absPath }) => fs.existsSync(absPath));
+  }
+
+  constructor(akanjsRoot: string, vendorExports: Partial<Record<VendorSpecifier, readonly string[]>>) {
+    this.#akanjsRoot = akanjsRoot;
+    const current = Object.values(deprecatedReexports).every((file) => fs.existsSync(path.join(akanjsRoot, file)));
+    this.#vendorExports = current ? vendorExports : {};
+  }
+
+  entryExports(vendorEntries: VendorEntry[]): Record<string, readonly string[]> {
+    return Object.fromEntries(
+      vendorEntries.flatMap(({ specifier, absPath }) => {
+        const names = this.#vendorExports[specifier];
+        return names ? [[absPath, names]] : [];
+      }),
+    );
+  }
+
+  async plugins(): Promise<BunPlugin[]> {
+    const blanked: string[] = [];
+    for (const [specifier, file] of Object.entries(deprecatedReexports) as [VendorSpecifier, string][]) {
+      const used = this.#vendorExports[specifier];
+      if (!used) continue;
+      const source = await Bun.file(path.join(this.#akanjsRoot, file)).text();
+      const names = new Bun.Transpiler({ loader: "ts" }).scan(source).exports;
+      if (!names.some((name) => used.includes(name))) blanked.push(`akanjs/${file}`);
+    }
+    if (blanked.length === 0) return [];
+    const escaped = blanked.map((file) => file.replace(/[.*+?^${}()|[\]\\]/g, "\\$&").replaceAll("/", "[\\\\/]"));
+    const filter = new RegExp(`[\\\\/](?:${escaped.join("|")})$`);
+    return [
+      {
+        name: "akan-blank-deprecated-reexports",
+        setup(build) {
+          build.onLoad({ filter }, () => ({ contents: "export {};\n", loader: "ts" }));
+        },
+      },
+    ];
+  }
+}

package/frontendBuild/vendorSpecifiers.ts

@@ -8,6 +8,7 @@ export const VENDOR_SPECIFIERS = [
   "scheduler",
   "react-server-dom-webpack/client.browser",
   "akanjs/store",
+  "akanjs/store/agent",
   "akanjs/base",
   "akanjs/common",
   "akanjs/constant",
@@ -16,3 +17,15 @@ export const VENDOR_SPECIFIERS = [
 ] as const;
 
 export type VendorSpecifier = (typeof VENDOR_SPECIFIERS)[number];
+
+//? The vendor entries a build narrows to the names its client code imports: each is an ESM `export *`, while React's
+//? entries list a CommonJS module's names by hand.
+export const NARROWABLE_VENDOR_SPECIFIERS = [
+  "akanjs/store",
+  "akanjs/store/agent",
+  "akanjs/base",
+  "akanjs/common",
+  "akanjs/constant",
+  "akanjs/fetch",
+  "tailwind-merge",
+] as const satisfies readonly VendorSpecifier[];