@akanjs/devkit 3.1.0-rc.9 → 3.1.1-rc.0

package/mobile/desktopServerStage.ts

@@ -1,7 +1,7 @@
 import { cp, mkdir, readdir, rm, writeFile } from "node:fs/promises";
 import path from "node:path";
-import type { ServerPolicy } from "@akanjs/native/api";
 import { toError } from "akanjs/common";
+import type { ServerPolicy } from "akanjs/native/api";
 import type { AkanAppConfig, NativeEnv } from "../akanConfig";
 import type { App } from "../commandDecorators";
 import type { PackageJson } from "../types";
@@ -33,6 +33,7 @@ export class DesktopServerStage {
     "console.js",
     "console-runtime.js",
     "csr",
+    "mcp-apps",
     "public",
     ".akan",
   ]);

package/mobile/nativeApi.ts

@@ -1,5 +1,5 @@
 import path from "node:path";
-import type * as NativeBuildApi from "@akanjs/native/api";
+import type * as NativeBuildApi from "akanjs/native/api";
 
 export type NativeBuildApiModule = typeof NativeBuildApi;
 

package/mobile/nativeApp.ts

@@ -1,7 +1,7 @@
 import path from "node:path";
-import type { AkanNativeConfig } from "@akanjs/native/config";
 import type { NativeEnv } from "akanjs";
 import { toError } from "akanjs/common";
+import type { AkanNativeConfig } from "akanjs/native/config";
 import type { App } from "../commandDecorators";
 import { Executor } from "../executors";
 import { type DesktopArch, DesktopBin } from "./desktopBin";

package/mobile/nativeConfig.ts

@@ -1,6 +1,5 @@
 import { readFileSync } from "node:fs";
 import path from "node:path";
-import type { AkanNativeConfig } from "@akanjs/native/config";
 import type {
   AkanNativeDmgConfig,
   AkanNativeTarget,
@@ -10,6 +9,7 @@ import type {
   NativePermission,
 } from "akanjs";
 import { trimSlashes } from "akanjs/common";
+import type { AkanNativeConfig } from "akanjs/native/config";
 import type { DesktopServerBundle } from "./desktopServerStage";
 import { type NativePlatform, resolveAppId } from "./mobileTarget";
 import type { NativePluginFolder } from "./nativePluginFolders";

package/mobile/updatePackFolder.ts

@@ -1,8 +1,8 @@
 import { mkdtemp, rm } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
-import type { BundleInfo, UpdateManifest } from "@akanjs/native/api";
 import type { NativeEnv } from "akanjs";
+import type { BundleInfo, UpdateManifest } from "akanjs/native/api";
 import { ExitCodeError } from "../commandDecorators/exitCodeError";
 import type { MobilePlatform } from "./mobileTarget";
 

package/mobile/updateUploader.ts

@@ -1,7 +1,7 @@
 import { readdir } from "node:fs/promises";
 import path from "node:path";
-import type { UpdateEnvelope, UpdateManifest } from "@akanjs/native/api";
 import { isRecord, trimTrailingSlashes } from "akanjs/common";
+import type { UpdateEnvelope, UpdateManifest } from "akanjs/native/api";
 import { UpdatePackFolder } from "./updatePackFolder";
 
 /** What the uploader needs of an S3 client; Bun.S3Client is one. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akanjs/devkit",
-  "version": "3.1.0-rc.9",
+  "version": "3.1.1-rc.0",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -14,7 +14,7 @@
     "directory": "pkgs/@akanjs/devkit"
   },
   "engines": {
-    "bun": ">=1.4.0"
+    "bun": ">=1.4.4"
   },
   "exports": {
     ".": {
@@ -46,25 +46,25 @@
     "@earendil-works/pi-coding-agent": "1.3.0",
     "@earendil-works/pi-mcp": "1.3.0",
     "@earendil-works/pi-tui": "1.3.0",
-    "@inquirer/prompts": "^8.4.3",
-    "@tailwindcss/node": "^4.3.0",
-    "akanjs": "3.1.0-rc.9",
-    "chalk": "^5.6.2",
-    "commander": "^14.0.3",
-    "dayjs": "^1.11.20",
-    "fontaine": "^0.8.0",
+    "@inquirer/prompts": "^8.7.3",
+    "@tailwindcss/node": "^4.3.3",
+    "akanjs": "3.1.1-rc.0",
+    "chalk": "^6.0.1",
+    "commander": "^15.0.0",
+    "dayjs": "^1.11.23",
+    "fontaine": "^1.0.1",
     "fonteditor-core": "^2.6.3",
-    "ignore": "^7.0.5",
-    "ora": "^9.4.0",
+    "ignore": "^7.0.12",
+    "ora": "^9.4.1",
     "ssh2": "^1.17.0",
-    "subset-font": "^2.5.0",
+    "subset-font": "^2.9.0",
     "tailwind-scrollbar": "^4.0.2",
-    "tailwindcss": "^4.3.0",
-    "typebox": "1.1.38",
+    "tailwindcss": "^4.3.3",
+    "typebox": "1.3.37",
     "typescript": "^6.0.3"
   },
   "peerDependencies": {
-    "react": "19.3.0"
+    "react": "19.3.1"
   },
   "peerDependenciesMeta": {
     "react": {

package/routeSourceValidator.test.ts

@@ -43,7 +43,7 @@ describe("RouteSourceValidator route chains", () => {
   const chain = (source: string, kind: "page" | "layout", pattern: string) =>
     RouteSourceValidator.validateRouteSourceExports(source, `page/${kind}.tsx`, kind, { pattern });
 
-  test("reads params, prompt and devOnly off a page() chain without evaluating it", () => {
+  test("reads params, prompt, apps and devOnly off a page() chain without evaluating it", () => {
     const source = [
       'import { page } from "akanjs/client";',
       "export default page()",
@@ -51,11 +51,13 @@ describe("RouteSourceValidator route chains", () => {
       '  .search("status", String)',
       "  .config({ transition: 'stack', devOnly: true })",
       '  .prompt("briefProject", "Brief one project.")',
-      "  .render(async ({ projectId }) => null);",
+      '  .app("showProject", "Show one project.", ({ projectId }) => null)',
+      '  .app("showBoard", "Show its board.", ({ projectId }) => null)',
+      "  .render(async ({ projectId, showProject }) => showProject);",
     ].join("\n");
     expect(chain(source, "page", "/:lang/project/:projectId")).toEqual({
       devOnly: true,
-      chain: { kind: "page", params: ["projectId"], prompt: "briefProject" },
+      chain: { kind: "page", params: ["projectId"], prompt: "briefProject", apps: ["showProject", "showBoard"] },
     });
   });
 
@@ -88,16 +90,29 @@ describe("RouteSourceValidator route chains", () => {
     expect(() => chain("export default page().param(name, ID).render(() => null);", "page", "/:lang/:x")).toThrow(
       ".param() takes a string literal first",
     );
+    expect(() => chain('export default page().app(name, "x", () => null).render(() => null);', "page", "/")).toThrow(
+      ".app() takes a string literal first",
+    );
     expect(() => chain("export default page().config({ devOnly: flag }).render(() => null);", "page", "/")).toThrow(
       "devOnly must be a literal true or false",
     );
+    const indirect = [
+      'const memo = page().app("showMemo", "x", () => null).render(() => null);',
+      "export default memo;",
+    ];
+    expect(() => chain(indirect.join("\n"), "page", "/")).toThrow('exports its chain through "memo"');
+    const renamed = [indirect[0], "export { memo as default };"];
+    expect(() => chain(renamed.join("\n"), "page", "/")).toThrow('exports its chain through "memo"');
   });
 
-  test("still reads the legacy shape as before", () => {
+  test("still reads the legacy shape as before, which never takes a guard", () => {
     const source = [
       "export default function Page() { return null; }",
       "export const pageConfig = { devOnly: false };",
     ].join("\n");
     expect(chain(source, "page", "/")).toEqual({ devOnly: false });
+    expect(() => chain(`${source}\nexport const guard = async () => undefined;`, "page", "/")).toThrow(
+      "exports guard beside a legacy default",
+    );
   });
 });

package/routeSourceValidator.ts

@@ -15,6 +15,8 @@ export interface RouteSourceChain {
   params: string[];
   /** The `.prompt()` name, when the page publishes itself as an MCP prompt. */
   prompt?: string;
+  /** The `.app()` names, each one MCP App the build gives a view of its own. */
+  apps: string[];
 }
 
 interface ChainStage {
@@ -80,6 +82,10 @@ export class RouteSourceValidator {
       throw new Error(`[route-convention] head and generateHead cannot both be exported in ${filePath}`);
     }
     const chain = RouteSourceValidator.#readChain(sourceFile, filePath);
+    if (!chain && exported.has("guard"))
+      throw new Error(
+        `[route-convention] ${filePath} exports guard beside a legacy default; declare it with .guard() on its chain`,
+      );
     if (!chain) return { devOnly: RouteSourceValidator.#readDevOnly(sourceFile, filePath) };
     const named = [...exported].filter((name) => name !== "default");
     if (named.length)
@@ -93,34 +99,75 @@ export class RouteSourceValidator {
     if (options.pattern) RouteSourceValidator.#assertChainParams(chain, options.pattern, filePath);
     return {
       devOnly: chain.devOnly,
-      chain: { kind: chain.kind, params: chain.params, ...(chain.prompt ? { prompt: chain.prompt } : {}) },
+      chain: {
+        kind: chain.kind,
+        params: chain.params,
+        ...(chain.prompt ? { prompt: chain.prompt } : {}),
+        apps: chain.apps,
+      },
     };
   }
 
   // Null for the legacy shape. Read off the source because the build enumerates routes without importing them.
   static #readChain(sourceFile: ts.SourceFile, filePath: string) {
     for (const statement of sourceFile.statements) {
+      const local = RouteSourceValidator.#defaultLocalOf(statement);
+      if (local && RouteSourceValidator.#bindsChain(sourceFile, local))
+        throw new Error(
+          `[route-convention] ${filePath} exports its chain through "${local}"; write \`export default page()…\` — the build reads the chain without evaluating the module`,
+        );
       if (!ts.isExportAssignment(statement) || statement.isExportEquals) continue;
-      let node = RouteSourceValidator.#unwrapExpression(statement.expression);
-      const stages: ChainStage[] = [];
-      while (node && ts.isCallExpression(node)) {
-        const callee = node.expression;
-        if (ts.isPropertyAccessExpression(callee)) {
-          stages.unshift({ name: callee.name.text, args: node.arguments });
-          node = callee.expression;
-          continue;
-        }
-        if (ts.isIdentifier(callee) && chainRoots.has(callee.text))
-          return RouteSourceValidator.#chainOf(callee.text as RouteSourceChain["kind"], stages, filePath);
-        return null;
+      const walked = RouteSourceValidator.#walkChain(RouteSourceValidator.#unwrapExpression(statement.expression));
+      return walked ? RouteSourceValidator.#chainOf(walked.kind, walked.stages, filePath) : null;
+    }
+    return null;
+  }
+
+  static #defaultLocalOf(statement: ts.Statement): string | undefined {
+    if (ts.isExportAssignment(statement) && !statement.isExportEquals) {
+      const node = RouteSourceValidator.#unwrapExpression(statement.expression);
+      return node && ts.isIdentifier(node) ? node.text : undefined;
+    }
+    if (!ts.isExportDeclaration(statement) || statement.moduleSpecifier || statement.isTypeOnly) return undefined;
+    const clause = statement.exportClause;
+    if (!clause || !ts.isNamedExports(clause)) return undefined;
+    const element = clause.elements.find((element) => !element.isTypeOnly && element.name.text === "default");
+    return element?.propertyName && ts.isIdentifier(element.propertyName) ? element.propertyName.text : undefined;
+  }
+
+  static #walkChain(start: ts.Expression | undefined) {
+    let node = start;
+    const stages: ChainStage[] = [];
+    while (node && ts.isCallExpression(node)) {
+      const callee = node.expression;
+      if (ts.isPropertyAccessExpression(callee)) {
+        stages.unshift({ name: callee.name.text, args: node.arguments });
+        node = callee.expression;
+        continue;
       }
+      if (ts.isIdentifier(callee) && chainRoots.has(callee.text))
+        return { kind: callee.text as RouteSourceChain["kind"], stages };
       return null;
     }
     return null;
   }
 
+  static #bindsChain(sourceFile: ts.SourceFile, name: string) {
+    return sourceFile.statements.some(
+      (statement) =>
+        ts.isVariableStatement(statement) &&
+        statement.declarationList.declarations.some(
+          (declaration) =>
+            ts.isIdentifier(declaration.name) &&
+            declaration.name.text === name &&
+            !!RouteSourceValidator.#walkChain(RouteSourceValidator.#unwrapExpression(declaration.initializer)),
+        ),
+    );
+  }
+
   static #chainOf(kind: RouteSourceChain["kind"], stages: ChainStage[], filePath: string) {
     const params: string[] = [];
+    const apps: string[] = [];
     let prompt: string | undefined;
     let devOnly = false;
     const literal = (stage: ChainStage) => {
@@ -134,10 +181,11 @@ export class RouteSourceValidator {
     for (const stage of stages) {
       if (stage.name === "param") params.push(literal(stage));
       else if (stage.name === "prompt") prompt = literal(stage);
+      else if (stage.name === "app") apps.push(literal(stage));
       else if (stage.name === "config")
         devOnly = RouteSourceValidator.#devOnlyOf(RouteSourceValidator.#unwrapExpression(stage.args[0]), filePath);
     }
-    return { kind, params, prompt, devOnly };
+    return { kind, params, prompt, apps, devOnly };
   }
 
   /** The same rule the loader applies: a page names every `[x]` it sits under, a layout may name a subset. */

package/scanInfo.ts

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 import path from "node:path";
 import type {
   AppConfigResult,
@@ -295,11 +296,19 @@ class ScanInfo {
 }
 
 export const isAkanFrameworkDependency = (dep: string) => dep === "akanjs" || dep.startsWith("akanjs/");
+export interface MigrationScanEntry {
+  id: string;
+  checksum: string;
+}
+
 export class AppInfo extends ScanInfo {
+  static readonly migrationDir = "script/migration";
+  static readonly #migrationIdRe = /^\d{12}_[A-Za-z][A-Za-z0-9]*$/;
   readonly type = "app";
   readonly exec: AppExecutor;
   readonly akanConfig: AppConfigResult;
   readonly libDeps: string[];
+  readonly migrations: MigrationScanEntry[];
 
   static appInfos = new Map<string, AppInfo>();
   static async fromExecutor(exec: AppExecutor, options: { refresh?: boolean } = {}) {
@@ -314,17 +323,21 @@ export class AppInfo extends ScanInfo {
         LibInfo.libInfos.set(libName, await LibInfo.fromExecutor(libExecutor));
       }),
     );
-    const libDeps = await AppInfo.#getAllLibDeps(exec, scanResult.libDeps);
-    const appInfo = new AppInfo(exec, scanResult as AppScanResult, libDeps);
+    const [libDeps, migrations] = await Promise.all([
+      AppInfo.#getAllLibDeps(exec, scanResult.libDeps),
+      AppInfo.scanMigrations(exec),
+    ]);
+    const appInfo = new AppInfo(exec, scanResult as AppScanResult, libDeps, migrations);
     AppInfo.appInfos.set(exec.name, appInfo);
     return appInfo;
   }
 
-  constructor(exec: AppExecutor, scanResult: AppScanResult, libDeps: string[]) {
+  constructor(exec: AppExecutor, scanResult: AppScanResult, libDeps: string[], migrations: MigrationScanEntry[] = []) {
     super(scanResult);
     this.exec = exec;
     this.akanConfig = scanResult.akanConfig;
     this.libDeps = libDeps;
+    this.migrations = migrations;
   }
   override getScanResult(): AppScanResult {
     return this.scanResult as AppScanResult;
@@ -334,6 +347,26 @@ export class AppInfo extends ScanInfo {
     (this.scanResult as AppScanResult).routes = routes;
   }
 
+  //* Line endings and a BOM dropped: an editor or autocrlf would otherwise record another checksum for the same script.
+  static async scanMigrations(exec: AppExecutor) {
+    const files = (await exec.readdir(AppInfo.migrationDir)).filter(
+      (file) => file.endsWith(".ts") && !/\.(test|spec|d)\.ts$/.test(file),
+    );
+    return await Promise.all(
+      files.map(async (file) => {
+        const id = file.slice(0, -".ts".length);
+        if (!AppInfo.#migrationIdRe.test(id))
+          throw new Error(
+            `${AppInfo.migrationDir}/${file}: a migration is named <yyyyMMddHHmm>_<camelName>.ts; create one with \`akan create-migration\``,
+          );
+        const source = (await exec.readFile(`${AppInfo.migrationDir}/${file}`))
+          .replace(/^\uFEFF/, "")
+          .replaceAll("\r\n", "\n");
+        return { id, checksum: createHash("sha256").update(source).digest("hex") };
+      }),
+    );
+  }
+
   static async #getAllLibDeps(exec: AppExecutor, libDeps: string[], libSet = new Set<string>()) {
     await Promise.all(
       libDeps.map(async (libName) => {

package/subspace.test.ts

@@ -245,7 +245,7 @@ describe("Subspace push", () => {
     expect(second.sha).not.toBe(first.sha);
   });
 
-  test("keeps the subspace's own root config and drops a Jenkinsfile an earlier push left there", async () => {
+  test("keeps the subspace's own root config and a Jenkinsfile an earlier push left there, never the workspace's", async () => {
     const { workRoot, bareRoot, subspace } = await makeMirror("own-served", "own-private", "own-kit");
     const customer = await cloneSubspace(workRoot, bareRoot, "own-customer");
     await write(path.join(customer, "akan.config.ts"), "export default { pipeline: {} };\n");
@@ -261,7 +261,8 @@ describe("Subspace push", () => {
     expect(await FileSys.readText(path.join(subspaceRoot, "akan.config.ts"))).toContain(
       "export default { pipeline: {} };",
     );
-    expect(await FileSys.fileExists(path.join(subspaceRoot, "Jenkinsfile"))).toBe(false);
+    expect(await FileSys.fileExists(path.join(subspaceRoot, "Jenkinsfile"))).toBe(true);
+    expect(await FileSys.readText(path.join(subspaceRoot, "Jenkinsfile"))).toContain("pipeline { agent none }");
   });
 
   test("refuses a lock that resolves from a registry only this machine reaches, before it clones", async () => {

package/subspaceClone.ts

@@ -47,10 +47,6 @@ export class SubspaceClone {
     this.#clone = new Executor(`subspace-${declaration.name}`, this.#clonePath);
   }
 
-  async #cloneGit(args: string[]) {
-    return await this.#workspace.spawn("git", ["-C", this.#clonePath, ...args]);
-  }
-
   async #ensure(branch: string) {
     if (!(await FileSys.dirExists(path.join(this.#clonePath, ".git")))) {
       await rm(this.#clonePath, { recursive: true, force: true });
@@ -160,15 +156,13 @@ export class SubspaceClone {
     await rm(path.join(this.#clonePath, SubspaceClone.holdDir), { recursive: true, force: true });
   }
 
-  //* A root entry last written by a sync commit is a copy an earlier push left there, the parent's Jenkinsfile among them:
-  //* it goes. Any other is the subspace's own and is held through the extraction.
+  //* Held even when an earlier push left it, the workspace's Jenkinsfile among them: it is the subspace's only copy.
   async #holdRootEntries() {
     const holdRoot = path.join(this.#clonePath, SubspaceClone.holdDir, "root");
     const held: string[] = [];
     for (const entry of SubspaceClone.subspaceOwnedRootEntries) {
       const from = path.join(this.#clonePath, entry);
       if (!(await FileSys.entryExists(from))) continue;
-      if (await this.#isPushedCopy(entry)) continue;
       await mkdir(holdRoot, { recursive: true });
       await rename(from, path.join(holdRoot, entry));
       held.push(entry);
@@ -185,11 +179,6 @@ export class SubspaceClone {
     }
   }
 
-  async #isPushedCopy(entry: string) {
-    const subject = await this.#cloneGit(["log", "-1", "--format=%s", "--", entry]).catch(() => "");
-    return subject.trim().startsWith(SubspaceClone.syncSubjectPrefix);
-  }
-
   static async #copyMissing(from: string, to: string) {
     await mkdir(to, { recursive: true });
     for (const entry of await readdir(from, { withFileTypes: true })) {

package/transforms/barrelImportsPlugin.ts

@@ -10,14 +10,16 @@ export interface BarrelImportsPluginOptions {
   skipPath?: (absPath: string) => boolean;
   /** Runs after the rewrite in the same onLoad (Bun's onLoad cannot fall through); null means no change. */
   pipeAfter?: (source: string, args: { path: string }) => string | Promise<string | null> | null;
+  /** Barrels the bundle leaves external: a rewritten import would inline the modules the import map already serves. */
+  external?: readonly string[];
 }
 
 export const createBarrelImportsPlugin = async (
   app: App,
-  { skipPath = defaultSkipPath, pipeAfter }: BarrelImportsPluginOptions = {},
+  { skipPath = defaultSkipPath, pipeAfter, external = [] }: BarrelImportsPluginOptions = {},
 ): Promise<BunPlugin> => {
   const akanConfig = await app.getConfig();
-  const barrels = [...new Set(akanConfig.barrelImports)].filter(Boolean);
+  const barrels = [...new Set(akanConfig.barrelImports)].filter((barrel) => barrel && !external.includes(barrel));
   const analyzer = new BarrelAnalyzer({
     resolvePackage: await createTsconfigPackageResolver(app),
   });

package/transforms/mcpAppPageTrimmer.test.ts

@@ -0,0 +1,89 @@
+import { describe, expect, test } from "bun:test";
+import { symlink } from "node:fs/promises";
+import path from "node:path";
+import { tempDirs, writeText } from "../testHelpers";
+import { McpAppPageTrimmer } from "./mcpAppPageTrimmer";
+
+const makeTempRoot = tempDirs("akan-mcp-app-trim-");
+
+describe("McpAppPageTrimmer", () => {
+  test("hands every stage but the apps a function that draws nothing, and keeps the rest of the chain as written", () => {
+    const source = [
+      'import { fetch, Memo } from "@apps/minimal/client";',
+      'import { Screen } from "@apps/minimal/ui";',
+      "export default page()",
+      '  .param("memoId", ID)',
+      "  .config({ topInset: 48 })",
+      "  .guard(async ({ memoId }) => { await fetch.memo(memoId); })",
+      "  .head(<title>Memo</title>)",
+      "  .loading(() => <Screen>loading</Screen>)",
+      '  .app("showMemo", "Show one memo.", ({ memoId }) => <Memo.Zone.View view={fetch.viewMemo(memoId).memoView} />)',
+      "  .render(({ memoId, showMemo }) => (",
+      '    <Screen className="pb-10">{showMemo}</Screen>',
+      "  ));",
+    ].join("\n");
+    expect(McpAppPageTrimmer.trim(source, "memo.tsx")).toBe(
+      [
+        'import { fetch, Memo } from "@apps/minimal/client";',
+        'import { Screen } from "@apps/minimal/ui";',
+        "export default page()",
+        '  .param("memoId", ID)',
+        "  .config({ topInset: 48 })",
+        "  .guard(() => null)",
+        "  .head(() => null)",
+        "  .loading(() => null)",
+        '  .app("showMemo", "Show one memo.", ({ memoId }) => <Memo.Zone.View view={fetch.viewMemo(memoId).memoView} />)',
+        "  .render(() => null);",
+      ].join("\n"),
+    );
+  });
+
+  test("trims a page reached through a link, as a synced lib page is", async () => {
+    const root = await makeTempRoot();
+    await writeText(
+      path.join(root, "libs/shared/page/login.tsx"),
+      [
+        "const page = () => ({ render: (draw: () => string) => draw });",
+        'export default page().render(() => "drawn by the render");',
+      ].join("\n"),
+    );
+    await symlink(path.join(root, "libs/shared/page"), path.join(root, "linked"));
+    await writeText(path.join(root, "entry.ts"), 'import login from "./linked/login.tsx";\nexport { login };\n');
+    const result = await Bun.build({
+      entrypoints: [path.join(root, "entry.ts")],
+      plugins: [McpAppPageTrimmer.plugin([path.join(root, "linked/login.tsx")])],
+    });
+    const [output] = result.outputs;
+    expect(result.success).toBe(true);
+    expect(await output?.text()).not.toContain("drawn by the render");
+  });
+
+  test("drops a lazy component only the page's render drew, with what it imports", async () => {
+    const root = await makeTempRoot();
+    await writeText(path.join(root, "Globe.ts"), 'export default "a heavy globe";\n');
+    await writeText(
+      path.join(root, "trip.tsx"),
+      [
+        "const lazy = (load: () => Promise<unknown>) => ({ load });",
+        'const Globe = lazy(() => import("./Globe"));',
+        "const page = () => ({ app: (name: string, draw: () => unknown) => ({ render: (render: () => unknown) => [name, draw, render] }) });",
+        'export default page().app("showTrip", () => "a trip card").render(() => Globe);',
+      ].join("\n"),
+    );
+    await writeText(path.join(root, "entry.ts"), 'import trip from "./trip.tsx";\nconsole.info(trip);\n');
+    const result = await Bun.build({
+      entrypoints: [path.join(root, "entry.ts")],
+      plugins: [McpAppPageTrimmer.plugin([path.join(root, "trip.tsx")])],
+      splitting: false,
+    });
+    const text = (await result.outputs[0]?.text()) ?? "";
+    expect(result.success).toBe(true);
+    expect(text).toContain("a trip card");
+    expect(text).not.toContain("a heavy globe");
+  });
+
+  test("leaves a module with no chain as it is", () => {
+    const legacy = "export default function Page() { return <main />; }\nexport const pageConfig = {};";
+    expect(McpAppPageTrimmer.trim(legacy, "legacy.tsx")).toBe(legacy);
+  });
+});

package/transforms/mcpAppPageTrimmer.ts

@@ -0,0 +1,70 @@
+import { realpathSync } from "node:fs";
+import path from "node:path";
+import type { BunPlugin } from "bun";
+import ts from "typescript";
+import { PureLazyMarker } from "./pureLazyMarker";
+
+type ChainStage = ts.CallExpression & { expression: ts.PropertyAccessExpression };
+
+//* An MCP App's view runs its page's `.app()` loads and no other stage, so the view build hands each such stage a
+//* function that draws nothing, and the bundler drops what only the page's own markup reached.
+export class McpAppPageTrimmer {
+  static readonly #unused = new Set(["render", "head", "loading", "guard"]);
+
+  /** Trims exactly `pagePaths`: the rest of the graph loads as it does for the CSR shell. */
+  static plugin(pagePaths: string[]): BunPlugin {
+    return {
+      name: "akan-mcp-app-page",
+      setup(build) {
+        if (!pagePaths.length) return;
+        //? The bundler loads a module by the path a link points at: a synced lib page is one under `page/(libs)`.
+        const loadedPaths = new Set(
+          pagePaths.flatMap((pagePath) => [pagePath, McpAppPageTrimmer.#realPathOf(pagePath)]),
+        );
+        const filter = new RegExp(`^(?:${[...loadedPaths].map((pagePath) => RegExp.escape(pagePath)).join("|")})$`);
+        //? The bundler runs one onLoad per module, so this one also marks the page's own `lazy()` components.
+        build.onLoad({ filter }, async (args) => ({
+          contents: PureLazyMarker.mark(McpAppPageTrimmer.trim(await Bun.file(args.path).text(), args.path), args.path),
+          loader: path.extname(args.path).slice(1) as "tsx" | "ts" | "jsx" | "js",
+        }));
+      },
+    };
+  }
+
+  static trim(source: string, filePath: string): string {
+    const sourceFile = ts.createSourceFile(filePath, source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
+    const spans = McpAppPageTrimmer.#stagesOf(sourceFile)
+      .flatMap((stage) => {
+        const [first] = stage.arguments;
+        if (!first || !McpAppPageTrimmer.#unused.has(stage.expression.name.text)) return [];
+        return [{ start: first.getStart(sourceFile), end: first.getEnd() }];
+      })
+      .sort((a, b) => b.start - a.start);
+    let trimmed = source;
+    for (const { start, end } of spans) trimmed = `${trimmed.slice(0, start)}() => null${trimmed.slice(end)}`;
+    return trimmed;
+  }
+
+  static #realPathOf(filePath: string) {
+    try {
+      return realpathSync(filePath);
+    } catch {
+      return filePath;
+    }
+  }
+
+  static #stagesOf(sourceFile: ts.SourceFile): ChainStage[] {
+    const stages: ChainStage[] = [];
+    for (const statement of sourceFile.statements) {
+      if (!ts.isExportAssignment(statement) || statement.isExportEquals) continue;
+      let node: ts.Expression = statement.expression;
+      while (ts.isParenthesizedExpression(node) || ts.isAsExpression(node) || ts.isSatisfiesExpression(node))
+        node = node.expression;
+      while (ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression)) {
+        stages.push(node as ChainStage);
+        node = node.expression.expression;
+      }
+    }
+    return stages;
+  }
+}