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

package/apiReference.ts

@@ -0,0 +1,240 @@
+import path from "node:path";
+import { DeclarationReader, type MemberFilter } from "./declarationReader";
+
+type Show =
+  | { kind: "signature" }
+  | ({ kind: "members" } & MemberFilter)
+  | { kind: "props"; omit?: string[] }
+  | { kind: "declaration" };
+
+interface Item {
+  name: string;
+  from?: string;
+  file?: string;
+  show: Show;
+}
+
+interface Section {
+  title: string;
+  intro?: string;
+  items: Item[];
+  routeStages?: boolean;
+}
+
+const sections: Section[] = [
+  {
+    title: "Routes (`page/`)",
+    items: [
+      { name: "page", from: "akanjs/client", show: { kind: "signature" } },
+      { name: "layout", from: "akanjs/client", show: { kind: "signature" } },
+      { name: "rootLayout", from: "akanjs/client", show: { kind: "signature" } },
+      { name: "RouteBaseArgs", file: "client/route/routeArgs.ts", show: { kind: "props" } },
+      {
+        name: "router",
+        from: "akanjs/client",
+        show: {
+          kind: "members",
+          only: [
+            "push",
+            "replace",
+            "back",
+            "backOrFallback",
+            "refresh",
+            "redirect",
+            "notFound",
+            "canGoBack",
+            "getPath",
+          ],
+        },
+      },
+      { name: "RouteOptions", file: "client/router.ts", show: { kind: "props" } },
+      { name: "Link", from: "akanjs/ui", show: { kind: "signature" } },
+      { name: "CommonLinkProps", file: "ui/Link/Anchor.tsx", show: { kind: "props" } },
+      { name: "usePageLocation", from: "akanjs/webkit", show: { kind: "signature" } },
+    ],
+    routeStages: true,
+  },
+  {
+    title: "Services and adapters (`lib/_<service>/`, `srvkit/`)",
+    items: [
+      { name: "adapt", from: "akanjs/service", show: { kind: "signature" } },
+      { name: "serve", from: "akanjs/service", show: { kind: "signature" } },
+      { name: "ServiceOptions", file: "service/serve.ts", show: { kind: "props" } },
+    ],
+  },
+  {
+    title: "Endpoints (`*.signal.ts`)",
+    intro:
+      "`endpoint(srv.<module>, ({ query, mutation, pubsub, message }) => ({ … }))`: each builder takes the return type and a `SignalOption`, then chains the stages below and ends in `.exec()`.",
+    items: [
+      { name: "endpoint", from: "akanjs/signal", show: { kind: "signature" } },
+      { name: "BuildEndpoint", file: "signal/endpointInfo.ts", show: { kind: "members", prefix: "" } },
+      {
+        name: "EndpointInfo",
+        file: "signal/endpointInfo.ts",
+        show: { kind: "members", only: ["param", "search", "body", "room", "msg", "with", "exec"] },
+      },
+      { name: "EndpointArgProps", file: "signal/endpointInfo.ts", show: { kind: "props" } },
+      {
+        name: "SignalOption",
+        file: "signal/types.ts",
+        show: {
+          kind: "props",
+          omit: ["live", "lock", "onFailed", "once", "scheduleCron", "scheduleTime", "scheduleType"],
+        },
+      },
+    ],
+  },
+  {
+    title: "Dictionaries (`*.dictionary.ts`)",
+    items: [
+      { name: "serviceDictionary", from: "akanjs/dictionary", show: { kind: "signature" } },
+      { name: "FunctionTranslation", file: "dictionary/dictInfo.ts", show: { kind: "members" } },
+      { name: "FieldTranslation", file: "dictionary/dictInfo.ts", show: { kind: "members" } },
+    ],
+  },
+  {
+    title: "App config (`akan.config.ts`)",
+    items: [
+      { name: "AppConfig", from: "akanjs", show: { kind: "declaration" } },
+      { name: "AppConfigInput", from: "akanjs", show: { kind: "props" } },
+      { name: "AkanWebOption", from: "akanjs", show: { kind: "declaration" } },
+      { name: "AkanI18nConfig", file: "common/localeConfig.ts", show: { kind: "props" } },
+    ],
+  },
+];
+
+const importOnly: Record<string, string[]> = {
+  "akanjs/base": ["Any", "Binary", "dayjs", "Float", "ID", "Int", "Upload"],
+  "akanjs/signal": ["internal", "None", "Public"],
+};
+
+const conventionImports = [
+  'import { fetch, usePage, <Model> } from "@apps/<app>/client"; // pages and UI',
+  'import * as cnst from "../cnst"; // inside lib/<module>/, beside srv and Err',
+  'import { Err } from "../dict";',
+  'import * as srv from "../srv";',
+  'import { BookApi } from "@apps/<app>/srvkit"; // a layer barrel: common, srvkit, ui, webkit',
+  'import { signedIn } from "@libs/shared/webkit"; // a workspace created with --libs true',
+];
+
+const routeInternals = ["assertPattern", "resolveArgs", "toRouteModule"];
+
+export class ApiReference {
+  static readonly guideline = "akanApi";
+
+  static target(cliDir: string) {
+    return path.join(cliDir, "guidelines", ApiReference.guideline, `${ApiReference.guideline}.instruction.md`);
+  }
+
+  static render(akanjsDir: string): string {
+    const reader = new DeclarationReader(akanjsDir);
+    const imports = new Map<string, Set<string>>();
+    const body: string[] = [];
+    for (const section of sections) {
+      body.push(`## ${section.title}`, "");
+      if (section.intro) body.push(section.intro, "");
+      const blocks: string[] = [];
+      for (const item of section.items) {
+        if (item.from) ApiReference.#addImport(imports, item.from, item.name, reader);
+        blocks.push(ApiReference.#renderItem(reader, item));
+      }
+      if (section.routeStages) blocks.push(ApiReference.#routeStages(reader));
+      body.push(...blocks.flatMap((block) => [block, ""]));
+    }
+    for (const [from, names] of Object.entries(importOnly))
+      for (const name of names) ApiReference.#addImport(imports, from, name, reader);
+    const importLines = [...imports.entries()]
+      .sort(([a], [b]) => a.localeCompare(b))
+      .map(([from, names]) => `import { ${[...names].sort((a, b) => a.localeCompare(b)).join(", ")} } from "${from}";`);
+    return [
+      "# Akan.js API reference",
+      "",
+      "Generated from the akanjs sources of this release: the import paths and signatures a first app needs, so none of",
+      "them has to be looked up in `node_modules`. A stage's return type is the same chain, left out below.",
+      "",
+      "## Imports",
+      "",
+      "```ts",
+      ...importLines,
+      ...conventionImports,
+      "```",
+      "",
+      ...body,
+    ]
+      .join("\n")
+      .trimEnd()
+      .concat("\n");
+  }
+
+  static #addImport(imports: Map<string, Set<string>>, from: string, name: string, reader: DeclarationReader) {
+    reader.exported(from, name);
+    if (from === "akanjs") return;
+    const names = imports.get(from) ?? new Set<string>();
+    names.add(name);
+    imports.set(from, names);
+  }
+
+  static #renderItem(reader: DeclarationReader, item: Item): string {
+    const symbol = item.from ? reader.exported(item.from, item.name) : reader.declared(item.file ?? "", item.name);
+    const where = item.from ? ` · \`${item.from}\`` : "";
+    const heading = `### \`${item.name}\`${where}`;
+    if (item.show.kind === "declaration")
+      return [heading, "", "```ts", reader.declarationText(symbol), "```"].join("\n");
+    if (item.show.kind === "signature")
+      return [heading, "", "```ts", ...reader.signatures(symbol, item.name), "```"].join("\n");
+    if (item.show.kind === "props")
+      return [heading, "", "```ts", ...reader.props(reader.declaredType(symbol), item.show.omit), "```"].join("\n");
+    const members = reader.members(reader.instanceType(symbol), item.show);
+    return [heading, "", "```ts", ...members.map(([, line]) => line), "```"].join("\n");
+  }
+
+  static #routeStages(reader: DeclarationReader): string {
+    const stagesOf = (name: string) =>
+      new Map(
+        reader.members(reader.instanceType(reader.exported("akanjs/client", name)), {
+          omit: name === "page" ? [...routeInternals, "loadApp"] : routeInternals,
+        }),
+      );
+    const page = stagesOf("page");
+    const layout = stagesOf("layout");
+    const root = stagesOf("rootLayout");
+    const shared = [...page.keys()].filter((key) => layout.has(key) && root.has(key));
+    const only = (stages: Map<string, string>, without: Map<string, string>[]) =>
+      [...stages.entries()].filter(([key]) => without.every((other) => !other.has(key))).map(([, line]) => line);
+    return [
+      "### Route stages",
+      "",
+      "Shared by `page()`, `layout()` and `rootLayout()`:",
+      "",
+      "```ts",
+      ...shared.map((key) => page.get(key) ?? ""),
+      "```",
+      "",
+      "Only on `page()`:",
+      "",
+      "```ts",
+      ...only(page, [layout, root]),
+      "```",
+      "",
+      "On `layout()` and `rootLayout()`, where a line replaces its shared form above:",
+      "",
+      "```ts",
+      reader.declarationText(reader.declared("client/route/LayoutDefinition.ts", "LayoutExtra")),
+      ...[...layout.entries()].filter(([key, line]) => page.get(key) !== line).map(([, line]) => line),
+      "```",
+      "",
+      "Only on `rootLayout()`, before `.param()` and `.search()`:",
+      "",
+      "```ts",
+      ...only(root, [page, layout]),
+      "```",
+    ].join("\n");
+  }
+}
+
+if (import.meta.main) {
+  const akanjsDir = path.resolve(import.meta.dir, "../../akanjs");
+  const target = ApiReference.target(path.resolve(import.meta.dir, "../cli"));
+  await Bun.write(target, ApiReference.render(akanjsDir));
+}

package/applicationBuildReporter.test.ts

@@ -14,13 +14,14 @@ describe("ApplicationBuildReporter.printSummary", () => {
   const rawLog = spyOn(Logger, "rawLog").mockImplementation(() => undefined);
   afterEach(() => rawLog.mockClear());
 
-  test("names every variable a deployed build needs when the build is for local", () => {
+  test("names the flag and the variables a deployed build needs when the build is for local", () => {
     ApplicationBuildReporter.printSummary(resultFor("local"));
 
     const notice = rawLog.mock.calls.map(([line]) => line).at(-1);
     expect(notice).toBe(ApplicationBuildReporter.localBuildNotice);
-    for (const key of ["AKAN_PUBLIC_ENV=main", "AKAN_PUBLIC_REPO_NAME", "AKAN_PUBLIC_SERVE_DOMAIN"])
-      expect(notice).toContain(key);
+    for (const part of ["akan build <app> --env main", "AKAN_PUBLIC_REPO_NAME", "AKAN_PUBLIC_SERVE_DOMAIN"])
+      expect(notice).toContain(part);
+    expect(notice).not.toContain("dev routes");
   });
 
   test("adds nothing to a build for a deployed environment", () => {
@@ -29,4 +30,25 @@ describe("ApplicationBuildReporter.printSummary", () => {
     expect(rawLog.mock.calls.map(([line]) => line)).not.toContain(ApplicationBuildReporter.localBuildNotice);
     expect(rawLog.mock.calls.at(-1)?.[0]).toBe("Done in 1.2s");
   });
+
+  test("lists the largest routes' JS before the paths, and how many more it left out", () => {
+    const routeJs = Array.from({ length: 12 }, (_, idx) => ({
+      routeId: `/:lang/r${idx}`,
+      files: 3,
+      rawBytes: (12 - idx) * 3 * 1024,
+      brotliBytes: (12 - idx) * 1024,
+    }));
+    ApplicationBuildReporter.printSummary({ ...resultFor("main"), routeJs });
+
+    const lines = rawLog.mock.calls.map(([line]) => line);
+    expect(lines.slice(1, 4)).toEqual([
+      "Route JS, largest first (brotli / raw):",
+      "  /:lang/r0    12.0KB    36.0KB",
+      "  /:lang/r1    11.0KB    33.0KB",
+    ]);
+    expect(lines).toContain("  …and 2 more");
+    expect(lines.indexOf("  …and 2 more")).toBeLessThan(
+      lines.indexOf("Route artifacts: dist/apps/shop/.akan/artifact"),
+    );
+  });
 });

package/applicationBuildReporter.ts

@@ -1,6 +1,7 @@
 import { realpathSync } from "node:fs";
 import path from "node:path";
 import { Logger } from "akanjs/common";
+import { RouteJsBudget, type RouteJsBudgetWarning, type RouteJsSize } from "./routeJsBudget";
 
 export interface ApplicationBuildPhaseResult {
   id: string;
@@ -16,6 +17,8 @@ export interface ApplicationBuildResult {
   outputDir: string;
   artifactDir: string;
   environment: string;
+  routeJs?: RouteJsSize[];
+  routeJsWarnings?: RouteJsBudgetWarning[];
 }
 
 export interface ApplicationBuildProgressReporter {
@@ -33,6 +36,10 @@ export class ApplicationBuildReporter {
 
   static printSummary(result: ApplicationBuildResult) {
     Logger.rawLog("");
+    if (result.routeJs?.length) {
+      for (const line of RouteJsBudget.formatTable(result.routeJs)) Logger.rawLog(line);
+      Logger.rawLog("");
+    }
     Logger.rawLog(`Route artifacts: ${result.artifactDir}`);
     Logger.rawLog(`Server output: ${result.outputDir}`);
     Logger.rawLog(`Done in ${ApplicationBuildReporter.formatDuration(result.durationMs)}`);
@@ -40,7 +47,7 @@ export class ApplicationBuildReporter {
   }
 
   static readonly localBuildNotice =
-    "Built for local, which serves the dev routes to every caller. For a host others can reach, build with AKAN_PUBLIC_ENV=main, AKAN_PUBLIC_REPO_NAME and AKAN_PUBLIC_SERVE_DOMAIN set.";
+    "Built for local: the server runs without endpoint rate limits, and boots on local defaults (Redis on localhost, the first database mode) where a deployment would stop to ask. For a host others can reach, run `akan build <app> --env main` with AKAN_PUBLIC_REPO_NAME and AKAN_PUBLIC_SERVE_DOMAIN set in the shell or the workspace .env.";
 
   static formatError(error: unknown, workspaceRoot = process.cwd()): string {
     if (error instanceof AggregateError) {

package/applicationBuildRunner.test.ts

@@ -159,7 +159,7 @@ console.info(new SampleService().name);
     }
   });
 
-  test("bakes into the route bundles the env their server env is, not the shell's that the root .env outranks", async () => {
+  test("builds for the shell's AKAN_PUBLIC_ENV over the root .env's, and for --env over both", async () => {
     const { root, workspace } = await createTempApp("portal");
     const shellEnv = process.env.AKAN_PUBLIC_ENV;
     const stoppedBeforePhases = (app: AppExecutor) => {
@@ -171,17 +171,37 @@ console.info(new SampleService().name);
     const bakedEnv = (app: AppExecutor) =>
       (bundleDefine(app, "build", "ssr") as { [key: string]: string })["process.env.AKAN_PUBLIC_ENV"];
     try {
+      expect(await readFile(path.join(root, ".env"), "utf8")).toContain("AKAN_PUBLIC_ENV=local\n");
       process.env.AKAN_PUBLIC_ENV = "main";
       const app = stoppedBeforePhases(AppExecutor.from(workspace, "portal"));
-      await expect(new ApplicationBuildRunner(app).build()).rejects.toThrow("stopped before the phases");
-      expect(bakedEnv(app)).toBe(JSON.stringify("local"));
+      const warn = spyOn(app.logger, "warn").mockImplementation(() => undefined);
+      const runner = new ApplicationBuildRunner(app);
+      await expect(runner.build()).rejects.toThrow("stopped before the phases");
+      expect(bakedEnv(app)).toBe(JSON.stringify("main"));
+      expect(warn.mock.calls.map(([line]) => line)).toEqual([
+        "The shell (or a .env.local) outranks the workspace .env: the bundles and the image take AKAN_PUBLIC_ENV=main (.env: local). Unset it there to build what the .env says.",
+      ]);
+      await runner.buildAppMeta();
+      expect(JSON.parse(await readFile(path.join(app.dist.cwdPath, "akan.env.json"), "utf8"))).toMatchObject({
+        AKAN_PUBLIC_ENV: "main",
+      });
+      expect(await readFile(path.join(app.dist.cwdPath, "Dockerfile"), "utf8")).toContain("ENV AKAN_PUBLIC_ENV=main\n");
 
       process.env.AKAN_PUBLIC_ENV = "main";
       const desktop = stoppedBeforePhases(AppExecutor.from(workspace, "portal"));
+      const desktopWarn = spyOn(desktop.logger, "warn").mockImplementation(() => undefined);
       await expect(new ApplicationBuildRunner(desktop, { environment: "debug" }).build()).rejects.toThrow(
         "stopped before the phases",
       );
       expect(bakedEnv(desktop)).toBe(JSON.stringify("debug"));
+      expect(desktopWarn).not.toHaveBeenCalled();
+
+      process.env.AKAN_PUBLIC_ENV = "";
+      const unset = stoppedBeforePhases(AppExecutor.from(workspace, "portal"));
+      await expect(new ApplicationBuildRunner(unset, { environment: "debug" }).build()).rejects.toThrow(
+        "stopped before the phases",
+      );
+      expect(bakedEnv(unset)).toBe(JSON.stringify("debug"));
     } finally {
       if (shellEnv === undefined) delete process.env.AKAN_PUBLIC_ENV;
       else process.env.AKAN_PUBLIC_ENV = shellEnv;
@@ -189,7 +209,7 @@ console.info(new SampleService().name);
     }
   });
 
-  test("bakes into the bundles every AKAN_PUBLIC_* its Dockerfile carries, and names the shell values it outranked", async () => {
+  test("bakes into the bundles every AKAN_PUBLIC_* its Dockerfile carries, each the shell's over the root .env's", async () => {
     const { root, workspace } = await createTempApp("portal");
     const keys = ["AKAN_PUBLIC_ENV", "AKAN_PUBLIC_REPO_NAME", "AKAN_PUBLIC_SERVE_DOMAIN"] as const;
     const shellEnv = Object.fromEntries(keys.map((key) => [key, process.env[key]]));
@@ -198,11 +218,8 @@ console.info(new SampleService().name);
       "AKAN_PUBLIC_ENV=main\nAKAN_PUBLIC_REPO_NAME=repo\nAKAN_PUBLIC_SERVE_DOMAIN=akanjs.com\n",
     );
     await Promise.all(["private", "public"].map((dir) => mkdir(path.join(root, "apps", "portal", dir))));
-    Object.assign(process.env, {
-      AKAN_PUBLIC_ENV: "local",
-      AKAN_PUBLIC_REPO_NAME: "shell-repo",
-      AKAN_PUBLIC_SERVE_DOMAIN: "localhost",
-    });
+    for (const key of keys) delete process.env[key];
+    process.env.AKAN_PUBLIC_REPO_NAME = "shell-repo";
     const app = AppExecutor.from(workspace, "portal");
     const warn = spyOn(app.logger, "warn").mockImplementation(() => undefined);
     const runner = new ApplicationBuildRunner(app);
@@ -214,11 +231,14 @@ console.info(new SampleService().name);
       const define = bundleDefine(app, "build", "csr") as { [key: string]: string };
       const imageEnv = (await app.getConfig()).getProductionEnv();
       for (const key of keys) expect(define[`process.env.${key}`]).toBe(JSON.stringify(imageEnv[key]));
-      expect(imageEnv.AKAN_PUBLIC_SERVE_DOMAIN).toBe("akanjs.com");
-      expect(warn).toHaveBeenCalledTimes(1);
-      expect(warn.mock.calls[0]?.[0]).toBe(
-        "The workspace .env outranks this process's environment: the bundles and the image take AKAN_PUBLIC_ENV=main (not local), AKAN_PUBLIC_REPO_NAME=repo (not shell-repo), AKAN_PUBLIC_SERVE_DOMAIN=akanjs.com (not localhost).",
-      );
+      expect(imageEnv).toMatchObject({
+        AKAN_PUBLIC_ENV: "main",
+        AKAN_PUBLIC_REPO_NAME: "shell-repo",
+        AKAN_PUBLIC_SERVE_DOMAIN: "akanjs.com",
+      });
+      expect(warn.mock.calls.map(([line]) => line)).toEqual([
+        "The shell (or a .env.local) outranks the workspace .env: the bundles and the image take AKAN_PUBLIC_REPO_NAME=shell-repo (.env: repo). Unset it there to build what the .env says.",
+      ]);
     } finally {
       for (const key of keys) {
         if (shellEnv[key] === undefined) delete process.env[key];

package/applicationBuildRunner.ts

@@ -9,14 +9,17 @@ import type {
   ApplicationBuildResult,
 } from "./applicationBuildReporter";
 import type { App } from "./commandDecorators";
-import { WorkspaceExecutor } from "./executors";
+import { parseEnvFile, WorkspaceExecutor } from "./executors";
 import {
   AllRoutesBuilder,
   CsrArtifactBuilder,
   FontPruner,
+  NARROWABLE_VENDOR_SPECIFIERS,
   precompressArtifacts,
   SsrBaseArtifactBuilder,
+  VendorImportScanner,
 } from "./frontendBuild";
+import { RouteJsBudget, type RouteJsBudgetMode, type RouteJsBudgetStatus, type RouteJsSize } from "./routeJsBudget";
 import { Spinner } from "./spinner";
 import { createServerEnvPlugin } from "./transforms/serverEnvPlugin";
 import { ServerEnvProfile } from "./transforms/serverEnvProfile";
@@ -31,7 +34,16 @@ export interface TypecheckOptions {
   report?: "pretty" | "records";
 }
 
-export type BuildPhaseId = "prepare" | "typecheck" | "backend" | "ssr" | "csr" | "assets" | "compress" | "metadata";
+export type BuildPhaseId =
+  | "prepare"
+  | "typecheck"
+  | "backend"
+  | "ssr"
+  | "csr"
+  | "assets"
+  | "compress"
+  | "budget"
+  | "metadata";
 
 export type BuildPhaseResult = ApplicationBuildPhaseResult & { id: BuildPhaseId };
 export type BuildResult = ApplicationBuildResult;
@@ -43,6 +55,8 @@ export interface ApplicationBuildRunnerOptions {
   environment?: string;
   /** Bundles `env/env.server.<environment>.<profile>.ts`, which may hold no secret, in place of the environment's file. */
   profile?: string;
+  /** `update` writes akan.budget.json, then enforces it; `report` names an overage without failing the build. */
+  budget?: RouteJsBudgetMode;
 }
 export interface BuildOptions {
   spinner?: boolean;
@@ -59,6 +73,7 @@ const BUILD_PHASE_EMOJIS: Record<BuildPhaseId, string> = {
   csr: "🎨",
   assets: "✂️",
   compress: "🗜️",
+  budget: "📏",
   metadata: "📝",
 };
 
@@ -86,39 +101,46 @@ export class ApplicationBuildRunner {
   #reporter?: BuildProgressReporter;
   #environment?: string;
   #profile?: string;
+  #budget: RouteJsBudgetMode;
+  #modulesByRoute?: Record<string, string[]>;
   #spinner?: boolean;
   #startedAt = Date.now();
   #phases: BuildPhaseResult[] = [];
 
-  constructor(app: App, { fast = false, reporter, environment, profile }: ApplicationBuildRunnerOptions = {}) {
+  constructor(
+    app: App,
+    { fast = false, reporter, environment, profile, budget = "report" }: ApplicationBuildRunnerOptions = {},
+  ) {
     this.#app = app;
     this.#fast = fast;
     this.#reporter = reporter;
     this.#environment = environment;
     this.#profile = profile;
+    this.#budget = budget;
   }
 
   get #envDir() {
     return path.join(this.#app.cwdPath, "env");
   }
 
-  //? Bundles bake AKAN_PUBLIC_* from process.env, where the shell outranks the .env that the server env and the
-  //? Dockerfile read: a page built otherwise drops the image's tokens as foreign or dials another serve domain.
+  //? Bundles bake AKAN_PUBLIC_* from process.env, which lacks `--env` and the defaults an unset repo name or serve
+  //? domain takes: a page built otherwise drops the image's tokens as foreign or dials another serve domain.
   #pinImageEnv(baseDevEnv: BaseDevEnv, environment: string) {
     const imageEnv = {
       AKAN_PUBLIC_ENV: environment,
       AKAN_PUBLIC_REPO_NAME: baseDevEnv.repoName,
       AKAN_PUBLIC_SERVE_DOMAIN: baseDevEnv.serveDomain,
     };
-    const outranked = Object.entries(imageEnv).filter(([key, value]) => {
-      const given = process.env[key];
-      return !!given && given !== value && !(key === "AKAN_PUBLIC_ENV" && this.#environment);
+    const dotenv = parseEnvFile(path.join(this.#app.workspace.workspaceRoot, ".env"));
+    const overridden = Object.entries(imageEnv).filter(([key, value]) => {
+      if (!dotenv[key] || dotenv[key] === value || WorkspaceExecutor.publicEnvPin?.[key]) return false;
+      return !(key === "AKAN_PUBLIC_ENV" && this.#environment);
     });
-    if (outranked.length)
+    if (overridden.length)
       this.#app.logger.warn(
-        `The workspace .env outranks this process's environment: the bundles and the image take ${outranked
-          .map(([key, value]) => `${key}=${value} (not ${process.env[key]})`)
-          .join(", ")}.`,
+        `The shell (or a .env.local) outranks the workspace .env: the bundles and the image take ${overridden
+          .map(([key, value]) => `${key}=${value} (.env: ${dotenv[key]})`)
+          .join(", ")}. Unset it there to build what the .env says.`,
       );
     Object.assign(process.env, imageEnv);
   }
@@ -176,9 +198,17 @@ export class ApplicationBuildRunner {
           ? `${result.files} files, ${ApplicationBuildRunner.formatBytes(result.inputBytes)} -> gzip ${ApplicationBuildRunner.formatBytes(result.outputBytes)} / br ${ApplicationBuildRunner.formatBytes(result.brotliBytes)}`
           : "no files",
     );
+    const routeJs = await this.#runPhase(
+      "budget",
+      "Measuring route JS",
+      () => this.#measureRouteJs(environment),
+      (result) => result?.summary ?? (this.#budget === "off" ? "off for this build" : "no server pages"),
+    );
     await this.#runPhase("metadata", "Writing production metadata", () => this.buildAppMeta());
     return {
       phases: this.#phases,
+      ...(routeJs ? { routeJs: routeJs.sizes } : {}),
+      ...(routeJs?.warnings ? { routeJsWarnings: routeJs.warnings } : {}),
       durationMs: Date.now() - this.#startedAt,
       outputDir: this.#app.dist.cwdPath,
       artifactDir: path.join(this.#app.dist.cwdPath, ".akan/artifact"),
@@ -293,7 +323,6 @@ export class ApplicationBuildRunner {
   #serverEnvPlugin(baseEnv: string, branches: Iterable<string>): BunPlugin {
     this.#serverEnv ??= createServerEnvPlugin({
       envDir: this.#envDir,
-      //? The root .env wins over the shell in baseDevEnv, so a `--env` build names its own; a desktop app runs it.
       environment: this.#environment ?? baseEnv,
       environments: ["local", "testing", ...branches],
       profile: this.#profile,
@@ -402,13 +431,46 @@ void run().catch((error) => {
       return null;
     }
     const { baseDevEnv, branches } = await this.#app.getConfig();
+    //? Routes first: the vendor entries export only the names the route bundles import.
+    const routes = new AllRoutesBuilder(this.#app, "build");
+    const allRoutes = await routes.build();
+    const vendorExports = await VendorImportScanner.exportsUsedIn(
+      path.join(this.#app.dist.cwdPath, ".akan/artifact/client"),
+      NARROWABLE_VENDOR_SPECIFIERS,
+    );
     const base = await new SsrBaseArtifactBuilder(this.#app, "build", {
       serverEnv: this.#serverEnvPlugin(baseDevEnv.env, branches),
+      vendorExports,
     }).build();
-    const allRoutes = await new AllRoutesBuilder(this.#app, base.artifact, "build").build();
+    this.#modulesByRoute = (await routes.writeModulePreloads(base.runtimeChunks)).modulesByRoute();
     return { base, allRoutes };
   }
 
+  //? After `compress`: a route is measured by the brotli bytes it is served as, read from the `.br` sidecars.
+  async #measureRouteJs(environment: string): Promise<(RouteJsBudgetStatus & { sizes: RouteJsSize[] }) | null> {
+    if (this.#budget === "off" || !this.#modulesByRoute) return null;
+    const sizes = await RouteJsBudget.measure(
+      path.join(this.#app.dist.cwdPath, ".akan/artifact"),
+      this.#modulesByRoute,
+    );
+    const budgetPath = path.join(this.#app.cwdPath, RouteJsBudget.fileName);
+    const { summary: status, warnings } = await RouteJsBudget.check(sizes, {
+      mode: this.#budget,
+      budgetPath,
+      source: path.relative(this.#app.workspace.workspaceRoot, budgetPath),
+      environment,
+    });
+    const largest = sizes[0];
+    const { formatBytes } = ApplicationBuildRunner;
+    return {
+      sizes,
+      summary: largest
+        ? `${sizes.length} routes, largest ${largest.routeId} ${formatBytes(largest.brotliBytes)} brotli (${formatBytes(largest.rawBytes)} raw); ${status}`
+        : status,
+      ...(warnings ? { warnings } : {}),
+    };
+  }
+
   //? Opt-in and outside `dist/`: a metafile is the size of the module graph, and `dist/` is what the image copies.
   async #buildOrThrow(label: string, config: Bun.BuildConfig): Promise<Bun.BuildOutput> {
     const flag = process.env.AKAN_BUILD_METAFILE;

package/artifact/implicitRootLayout.test.ts

@@ -101,6 +101,48 @@ describe("resolveSsrPageEntries", () => {
     expect(generatedDictMacro).toContain("export const allDictionary = getAllDictionary();");
   });
 
+  test("bootstraps the client runtime and store, not the client barrel, at every root boundary", async () => {
+    const appRoot = await makeTempRoot();
+    const pageRoot = path.join(appRoot, "page");
+
+    await write(path.join(appRoot, "env", "env.client.ts"), "export const env = {};\n");
+    await write(path.join(appRoot, "lib", "st.ts"), "export const st = {};\n");
+    await write(path.join(pageRoot, "(home)", "_layout.tsx"), 'export const theme = "dark";\n');
+    await write(path.join(pageRoot, "(admin)", "_layout.tsx"), 'export const theme = "light";\n');
+
+    const entries = await resolveSsrPageEntries({
+      appCwdPath: appRoot,
+      appName: "demo",
+      pageKeys: ["./(home)/_layout.tsx", "./(home)/_index.tsx", "./(admin)/_layout.tsx", "./(admin)/users.tsx"],
+    });
+
+    const roots = entries.filter((entry) => entry.key.endsWith("__root_layout.tsx"));
+    expect(roots.map((entry) => entry.key)).toEqual(["./(admin)/__root_layout.tsx", "./(home)/__root_layout.tsx"]);
+    for (const root of roots) {
+      const generatedSource = await Bun.file(root.moduleAbsPath).text();
+      expect(generatedSource).toContain('import "@apps/demo/lib/useClient";\nimport "@apps/demo/lib/st";\n');
+      expect(generatedSource).not.toContain("@apps/demo/client");
+    }
+  });
+
+  test("imports no store bootstrap for an app without a store", async () => {
+    const appRoot = await makeTempRoot();
+    await write(path.join(appRoot, "env", "env.client.ts"), "export const env = {};\n");
+    await write(path.join(appRoot, "page", "_layout.tsx"), 'export const theme = "dark";\n');
+
+    const entries = await resolveSsrPageEntries({
+      appCwdPath: appRoot,
+      appName: "demo",
+      pageKeys: ["./_layout.tsx", "./_index.tsx"],
+    });
+
+    const root = entries.find((entry) => entry.key === "./__root_layout.tsx");
+    const generatedSource = await Bun.file(root?.moduleAbsPath ?? "").text();
+    expect(generatedSource).toContain("<System.Provider");
+    expect(generatedSource).not.toContain("@apps/demo/lib/");
+    expect(generatedSource).not.toContain("@apps/demo/client");
+  });
+
   test("awaits an async grouped root layout in the CSR bundle instead of mounting it as JSX", async () => {
     const appRoot = await makeTempRoot();
     const pageRoot = path.join(appRoot, "page");