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

package/frameworkGraph.ts

@@ -0,0 +1,165 @@
+import { readdir, readFile, realpath, stat } from "node:fs/promises";
+import path from "node:path";
+import {
+  type FrameworkChannelSpec,
+  FrameworkMapBuilder,
+  FrameworkMapDoc,
+  type FrameworkSourcePackage,
+} from "@akanjs/language";
+import type { FrameworkMap } from "akanjs/common";
+import ts from "typescript";
+
+const packageSpecs: Omit<FrameworkSourcePackage, "root">[] = [
+  { name: "akanjs", split: true },
+  { name: "@akanjs/devkit", split: false },
+];
+const channelSpecs: FrameworkChannelSpec[] = [
+  { file: "service/ipcTypes.ts", union: "AkanIpcMessage", label: "gateway ⇄ child" },
+  { file: "server/artifact/ipcTypes.ts", union: "BuilderMessage", label: "dev host ⇄ builder, relayed to the child" },
+  { file: "server/rscWorker.tsx", union: "InMsg", label: "server → RSC worker" },
+  { file: "server/rscWorkerHost.ts", union: "RscInMsg", label: "RSC worker → server" },
+  { file: "server/hmr/wsHub.ts", union: "HmrMessage", label: "dev server → browser tab", relays: ["HmrWsHub"] },
+];
+//? A published akanjs bundles use-agentic and @akanjs/native under `vendor/` and its declarations under `types/`;
+//? devkit's `integration`, `csrE2e` and `platformTest` are test harnesses that run in no framework process.
+const skippedDirs = new Set(["node_modules", "vendor", "types", "integration", "csrE2e", "platformTest"]);
+
+export interface FrameworkArchitecture {
+  file: string;
+  current: string;
+  next: string;
+  unknownClasses: string[];
+  map: FrameworkMap;
+}
+
+export class FrameworkGraph {
+  static readonly architectureFile = "pkgs/akanjs/ARCHITECTURE.md";
+  static readonly #cache = new Map<string, Promise<FrameworkMap | null>>();
+  static readonly #edits = new Map<string, number>();
+
+  static async packagesOf(workspaceRoot: string): Promise<FrameworkSourcePackage[]> {
+    const found = await Promise.all(
+      packageSpecs.map(async ({ name, split }) => {
+        const root = (await FrameworkGraph.#isDir(path.join(workspaceRoot, "pkgs", name)))
+          ? `pkgs/${name}`
+          : await FrameworkGraph.#installedRoot(workspaceRoot, name);
+        return root ? [{ name, root, split }] : [];
+      }),
+    );
+    return found.flat();
+  }
+
+  static async build(workspaceRoot: string): Promise<FrameworkMap | null> {
+    const packages = await FrameworkGraph.packagesOf(workspaceRoot);
+    const akanjs = packages.find(({ name }) => name === "akanjs");
+    if (!akanjs) return null;
+    const files = (
+      await Promise.all(packages.map(({ root }) => FrameworkGraph.#filesUnder(workspaceRoot, root)))
+    ).flat();
+    const texts = await Promise.all(
+      files.map(async (file) => [file, await readFile(path.join(workspaceRoot, file), "utf8")] as [string, string]),
+    );
+    return new FrameworkMapBuilder({
+      ts,
+      packages,
+      files: texts,
+      channels: channelSpecs.map((spec) => ({ ...spec, file: `${akanjs.root}/${spec.file}` })),
+    }).build();
+  }
+
+  //? Only the framework's own repository holds the document; a consumer's `node_modules/akanjs` is never rewritten.
+  static async architecture(workspaceRoot: string): Promise<FrameworkArchitecture | null> {
+    const file = path.join(workspaceRoot, FrameworkGraph.architectureFile);
+    const current = await readFile(file, "utf8")
+      .then((text) => text.replace(/\r\n/g, "\n"))
+      .catch(() => null);
+    const map = current === null ? null : await FrameworkGraph.build(workspaceRoot);
+    if (current === null || !map || map.packages.find(({ name }) => name === "akanjs")?.root !== "pkgs/akanjs")
+      return null;
+    const next = FrameworkMapDoc.splice(
+      current,
+      FrameworkMapDoc.render(map, path.posix.dirname(FrameworkGraph.architectureFile)),
+    );
+    return {
+      file,
+      current,
+      next,
+      unknownClasses: FrameworkMapDoc.unknownClasses(next, map),
+      map,
+    };
+  }
+
+  static touched(workspaceRoot: string, files: string[]) {
+    const roots = packageSpecs.map(({ name }) => path.join(workspaceRoot, "pkgs", name) + path.sep);
+    if (files.some((file) => roots.some((root) => path.resolve(workspaceRoot, file).startsWith(root))))
+      FrameworkGraph.#edits.set(workspaceRoot, (FrameworkGraph.#edits.get(workspaceRoot) ?? 0) + 1);
+  }
+
+  //? Only an install rewrites `node_modules/akanjs`, and an install changes its version.
+  static async cached(workspaceRoot: string): Promise<FrameworkMap | null> {
+    const packages = await FrameworkGraph.packagesOf(workspaceRoot);
+    const stamps = await Promise.all(
+      packages.map(async ({ name, root }) =>
+        root.startsWith("pkgs/")
+          ? `${name}#${FrameworkGraph.#edits.get(workspaceRoot) ?? 0}`
+          : `${name}@${await FrameworkGraph.#versionOf(path.join(workspaceRoot, root))}`,
+      ),
+    );
+    const cacheKey = [workspaceRoot, ...stamps].join("\n");
+    const existing = FrameworkGraph.#cache.get(cacheKey);
+    if (existing) return await existing;
+    const built = FrameworkGraph.build(workspaceRoot);
+    built.catch(() => FrameworkGraph.#cache.delete(cacheKey));
+    FrameworkGraph.#cache.clear();
+    FrameworkGraph.#cache.set(cacheKey, built);
+    return await built;
+  }
+
+  //? Bun resolves a bare name from its global cache when no `node_modules` exists, so one must; an install linked from
+  //? outside the workspace is skipped, as its files have no workspace-relative path.
+  static async #installedRoot(workspaceRoot: string, name: string): Promise<string | null> {
+    if (!(await FrameworkGraph.#isDir(path.join(workspaceRoot, "node_modules")))) return null;
+    const resolved = await (async () => {
+      try {
+        return path.dirname(await realpath(Bun.resolveSync(`${name}/package.json`, workspaceRoot)));
+      } catch {
+        const dir = path.join(workspaceRoot, "node_modules", name);
+        return (await FrameworkGraph.#isDir(dir)) ? await realpath(dir) : null;
+      }
+    })();
+    if (!resolved) return null;
+    const root = path
+      .relative(await realpath(workspaceRoot), resolved)
+      .split(path.sep)
+      .join("/");
+    return root && !root.startsWith("..") && !path.isAbsolute(root) ? root : null;
+  }
+
+  static async #versionOf(dir: string) {
+    return await readFile(path.join(dir, "package.json"), "utf8")
+      .then((text) => (JSON.parse(text) as { version?: string }).version ?? "")
+      .catch(() => "");
+  }
+
+  static async #isDir(dir: string) {
+    return await stat(dir)
+      .then((info) => info.isDirectory())
+      .catch(() => false);
+  }
+
+  static async #filesUnder(workspaceRoot: string, root: string): Promise<string[]> {
+    const entries = await readdir(path.join(workspaceRoot, root), { withFileTypes: true });
+    const files: string[] = [];
+    for (const entry of entries) {
+      if (entry.name.startsWith(".") || skippedDirs.has(entry.name)) continue;
+      if (entry.isFile()) files.push(`${root}/${entry.name}`);
+      else if (entry.isDirectory())
+        for await (const file of new Bun.Glob("**/*.{ts,tsx}").scan({
+          cwd: path.join(workspaceRoot, root, entry.name),
+        }))
+          if (!file.split(path.sep).includes("node_modules"))
+            files.push(`${root}/${entry.name}/${file.split(path.sep).join("/")}`);
+    }
+    return files.filter((file) => FrameworkMapBuilder.isSourcePath(file)).sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+  }
+}

package/frontendBuild/allRoutesBuilder.test.ts

@@ -0,0 +1,84 @@
+import { describe, expect, test } from "bun:test";
+import { mkdir, realpath, symlink } from "node:fs/promises";
+import path from "node:path";
+import { tempDirs, writeText as write } from "../testHelpers";
+import { AllRoutesBuilder } from "./allRoutesBuilder";
+
+const makeTempRoot = tempDirs("akan-all-routes-");
+const akanjsRoot = path.resolve(import.meta.dir, "../../../akanjs");
+
+const linkPackage = async (root: string, name: string, dir: string) => {
+  await mkdir(path.join(root, "node_modules"), { recursive: true });
+  await symlink(dir, path.join(root, "node_modules", name));
+};
+
+//? As this monorepo maps it, so the generated root layout's `akanjs/ui/System/index.tsx` resolves through a wildcard.
+const paths = { "@apps/*": ["./apps/*"], "akanjs/*": ["./node_modules/akanjs/*"] };
+
+const writeApp = async () => {
+  const root = await realpath(await makeTempRoot());
+  const appDir = path.join(root, "apps/demo");
+  await linkPackage(root, "akanjs", akanjsRoot);
+  await linkPackage(root, "react", path.dirname(Bun.resolveSync("react/package.json", akanjsRoot)));
+  await write(path.join(root, "tsconfig.json"), JSON.stringify({ compilerOptions: { paths } }));
+  await write(path.join(appDir, "client.ts"), "export {};\n");
+  await write(path.join(appDir, "env/env.client.ts"), "export const env = {};\n");
+  await write(path.join(appDir, "lib/dict.ts"), "export const getAllDictionary = () => ({});\n");
+  await write(path.join(appDir, "ui/Home.tsx"), '"use client";\nexport const Home = () => "home-marker";\n');
+  await write(path.join(appDir, "ui/Memo.tsx"), '"use client";\nexport const Memo = () => "memo-marker";\n');
+  await write(
+    path.join(appDir, "page/_index.tsx"),
+    'import { Home } from "../ui/Home";\nexport default function Page() {\n  return <Home />;\n}\n',
+  );
+  await write(
+    path.join(appDir, "page/memo.tsx"),
+    'import { Memo } from "../ui/Memo";\nexport default function Page() {\n  return <Memo />;\n}\n',
+  );
+  const app = {
+    name: "demo",
+    cwdPath: appDir,
+    dist: { cwdPath: path.join(root, "dist/apps/demo") },
+    workspace: { workspaceRoot: root },
+    getPageKeys: async () => ["./_index.tsx", "./memo.tsx"],
+    getConfig: async () => ({ basePaths: [], optimizeImports: [], barrelImports: [] }),
+    getTsConfig: async () => ({ compilerOptions: { paths } }),
+    getPublicEnv: () => ({}),
+    log: () => undefined,
+    verbose: () => undefined,
+    logger: { warn: () => undefined },
+  };
+  return app;
+};
+
+describe("AllRoutesBuilder", () => {
+  test("writes the route manifest, then the preload table once the runtime chunks are known, and each route's modules", async () => {
+    const app = await writeApp();
+    const routes = new AllRoutesBuilder(app as never, "build");
+    const { manifest, manifestPath } = await routes.build();
+
+    expect(new Set(manifest.routeIds)).toEqual(new Set(["/:lang", "/:lang/memo"]));
+    expect(await Bun.file(manifestPath).json()).not.toHaveProperty("modulePreloads");
+
+    const runtimeChunks = { runtime: ["/_akan/client/rsc.js"], vendors: { react: ["/_akan/client/react.js"] } };
+    const preloads = await routes.writeModulePreloads(runtimeChunks);
+    expect(preloads.table).toMatchObject(runtimeChunks);
+    expect(new Set(Object.values(preloads.table.chunkVendors).flat())).toEqual(new Set(["react"]));
+    expect((await Bun.file(manifestPath).json()).modulePreloads).toEqual(preloads.table);
+
+    const chunksOf = (suffix: string) =>
+      Object.entries(manifest.clientManifest).find(([key]) => key.endsWith(suffix))?.[1].chunks ?? [];
+    const [home] = chunksOf("apps/demo/ui/Home.tsx#Home");
+    const [memo] = chunksOf("apps/demo/ui/Memo.tsx#Memo");
+    const shell = chunksOf("akanjs/ui/System/Client.tsx#Client");
+    const modules = preloads.modulesByRoute();
+    expect(shell.length).toBeGreaterThan(0);
+    for (const [routeId, own, other] of [
+      ["/:lang", home, memo],
+      ["/:lang/memo", memo, home],
+    ] as const) {
+      expect(modules[routeId]?.slice(0, 2)).toEqual(["/_akan/client/rsc.js", "/_akan/client/react.js"]);
+      expect(modules[routeId]).toEqual(expect.arrayContaining([own, ...shell]));
+      expect(modules[routeId]).not.toContain(other);
+    }
+  }, 30_000);
+});

package/frontendBuild/allRoutesBuilder.ts

@@ -1,11 +1,12 @@
 import path from "node:path";
-import type { BaseBuildArtifact, BuildRouteClientResult, RoutesManifest } from "akanjs/server";
+import type { RoutesManifest } from "akanjs/server";
 import { resolveSsrPageEntriesForApp } from "../artifact/implicitRootLayout";
 import { computeRouteSeedIndex, type RouteSeedIndex } from "../artifact/routeSeedIndex";
 import type { App } from "../commandDecorators";
 import type { ClientEntryDiscovery } from "./clientBuildTypes";
 import { GraphClientEntryDiscovery } from "./clientEntryDiscovery";
-import { RouteClientBuilder } from "./routeClientBuilder";
+import { type BuildRouteClientResult, RouteClientBuilder } from "./routeClientBuilder";
+import { RouteModulePreloads, type RuntimeChunks } from "./routeModulePreloads";
 import { RoutesManifestArtifactSerializer } from "./routesManifestArtifactSerializer";
 
 export interface BuildAllRoutesResult {
@@ -16,7 +17,6 @@ export interface BuildAllRoutesResult {
 
 export class AllRoutesBuilder {
   #app: App;
-  #artifact: BaseBuildArtifact;
   #command: "build" | "start";
   #artifactDir: string;
   #merged: Pick<RoutesManifest, "clientManifest" | "ssrManifest" | "knownEntries"> = {
@@ -26,11 +26,12 @@ export class AllRoutesBuilder {
   };
   #knownSet = new Set<string>();
   #routeIds: string[] = [];
+  #entriesByRoute = new Map<string, string[]>();
+  #externalsByChunkUrl: Record<string, string[]> = {};
   #discovery: ClientEntryDiscovery | null = null;
 
-  constructor(app: App, artifact: BaseBuildArtifact, command: "build" | "start" = "start") {
+  constructor(app: App, command: "build" | "start" = "start") {
     this.#app = app;
-    this.#artifact = artifact;
     this.#command = command;
     this.#artifactDir = `${command === "build" ? app.dist.cwdPath : app.cwdPath}/.akan/artifact`;
   }
@@ -46,7 +47,9 @@ export class AllRoutesBuilder {
     const allEntries = new Set<string>();
     for (const entry of seedIndex.entries) {
       const seeds = Array.from(new Set([...seedIndex.globalLayoutFiles, ...entry.seeds]));
-      for (const discovered of await this.#discovery.discover(seeds)) allEntries.add(discovered);
+      const routeEntries = await this.#discovery.discover(seeds);
+      for (const discovered of routeEntries) allEntries.add(discovered);
+      this.#entriesByRoute.set(entry.routeId, routeEntries);
       this.#routeIds.push(entry.routeId);
     }
     this.#app.verbose(`[build-all] ${allEntries.size} client entries across ${this.#routeIds.length} routes`);
@@ -54,11 +57,33 @@ export class AllRoutesBuilder {
     const delta = await this.#buildEntries([...allEntries]);
     this.#mergeDelta(delta);
     this.#merged.knownEntries = Array.from(this.#knownSet);
+    this.#externalsByChunkUrl = delta.externalsByChunkUrl ?? {};
 
     const manifest: RoutesManifest = {
       routeIds: this.#routeIds,
       ...this.#merged,
     };
+    const manifestPath = await this.#writeManifest(manifest);
+    this.#app.verbose(
+      `[build-all] wrote ${manifestPath} routes=${this.#routeIds.length} entries=${this.#merged.knownEntries.length}`,
+    );
+
+    return { manifest, manifestPath, seedIndex };
+  }
+
+  async writeModulePreloads(runtimeChunks: RuntimeChunks): Promise<RouteModulePreloads> {
+    const preloads = new RouteModulePreloads({
+      runtimeChunks,
+      entriesByRoute: this.#entriesByRoute,
+      clientManifest: this.#merged.clientManifest,
+      externalsByChunkUrl: this.#externalsByChunkUrl,
+      workspaceRoot: this.#app.workspace.workspaceRoot,
+    });
+    await this.#writeManifest({ routeIds: this.#routeIds, ...this.#merged, modulePreloads: preloads.table });
+    return preloads;
+  }
+
+  async #writeManifest(manifest: RoutesManifest) {
     const manifestPath = path.join(path.resolve(this.#artifactDir), "routes-manifest.json");
     await Bun.write(
       manifestPath,
@@ -70,11 +95,7 @@ export class AllRoutesBuilder {
         2,
       )}\n`,
     );
-    this.#app.verbose(
-      `[build-all] wrote ${manifestPath} routes=${this.#routeIds.length} entries=${this.#merged.knownEntries.length}`,
-    );
-
-    return { manifest, manifestPath, seedIndex };
+    return manifestPath;
   }
 
   async #buildEntries(entries: string[]): Promise<BuildRouteClientResult> {
@@ -91,7 +112,6 @@ export class AllRoutesBuilder {
       app: this.#app,
       seeds: [],
       entries,
-      artifact: this.#artifact,
       knownEntries: this.#knownSet,
       discovery: this.#discovery,
       command: this.#command,

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;