@akanjs/devkit 3.1.0-rc.8 → 3.1.0

package/frontendBuild/csrArtifactBuilder.test.ts

@@ -61,4 +61,44 @@ console.info(await result.outputs[0].text());
     expect(firstOutput).toBe(secondOutput);
     expect(firstOutput).not.toContain(path.basename(first));
   });
+
+  //? The shape of `@lexical/code-prism` under a `lazy()` editor, which threw in every view and CSR shell carrying it.
+  test("runs a lazily imported module's CommonJS side-effect import before the imports after it", async () => {
+    const root = await makeTempRoot();
+    const app = { getPublicEnv: () => ({ AKAN_PUBLIC_ENV: "main" }) };
+    await writeText(path.join(root, "node_modules/core/package.json"), '{ "name": "core", "main": "index.js" }\n');
+    await writeText(
+      path.join(root, "node_modules/core/index.js"),
+      "var Core = { langs: [] };\nglobalThis.Core = Core;\nmodule.exports = Core;\n",
+    );
+    await writeText(path.join(root, "node_modules/core/components/a.js"), 'Core.langs.push("a");\n');
+    await writeText(
+      path.join(root, "node_modules/highlight/package.json"),
+      '{ "name": "highlight", "type": "module", "main": "index.js" }\n',
+    );
+    await writeText(
+      path.join(root, "node_modules/highlight/index.js"),
+      'import "core";\nimport "core/components/a.js";\nexport const langs = () => globalThis.Core.langs;\n',
+    );
+    await writeText(
+      path.join(root, "entry.ts"),
+      'import("highlight").then(({ langs }) => console.info(langs().join()));\n',
+    );
+    const result = await Bun.build({
+      ...CsrArtifactBuilder.bundleOptions(app as never, "build"),
+      entrypoints: [path.join(root, "entry.ts")],
+    });
+    expect(result.success).toBe(true);
+    await Bun.write(path.join(root, "out.js"), (await result.outputs[0]?.text()) ?? "");
+
+    const proc = Bun.spawn([process.execPath, "out.js"], { cwd: root, stdout: "pipe", stderr: "pipe" });
+    const [stdout, stderr] = await Promise.all([
+      new Response(proc.stdout).text(),
+      new Response(proc.stderr).text(),
+      proc.exited,
+    ]);
+
+    expect(stderr).toBe("");
+    expect(stdout.trim()).toBe("a");
+  });
 });

package/frontendBuild/csrArtifactBuilder.ts

@@ -4,8 +4,10 @@ import type { BaseBuildArtifact } from "akanjs/server";
 import { type PageEntry, resolveSsrPageEntriesForApp } from "../artifact/implicitRootLayout";
 import type { App } from "../commandDecorators";
 import { createBrowserDirnamePlugin } from "../transforms/browserDirnamePlugin";
+import { SideEffectImportOrder } from "../transforms/sideEffectImportOrder";
 import { bundleDefine } from "./bundleDefine";
 import { CsrEntryFiles } from "./csrEntryFiles";
+import { type McpAppView, McpAppViewBuilder } from "./mcpAppViewBuilder";
 import { PagesBundleBuilder } from "./pagesBundleBuilder";
 import { PagesEntrySourceGenerator } from "./pagesEntrySourceGenerator";
 
@@ -77,11 +79,32 @@ export class CsrArtifactBuilder {
     }
 
     await this.#inlineCsrArtifacts(cssAssets);
+    await this.#buildMcpAppViews(pageEntries, { basePaths, cssAssets, options });
     if (this.#command === "build") await CsrArtifactBuilder.writePublicEnv(this.#app, options.define);
     this.#app.verbose(`[csr-build] output -> ${this.#outputDir}`);
     return { outputDir: this.#outputDir };
   }
 
+  /** The MCP App views alone: a dev server under the CSR registry reads them, with no `csr/` to build beside them. */
+  async buildMcpAppViews(): Promise<McpAppView[]> {
+    const pageKeys = await this.#app.getPageKeys();
+    if (pageKeys.length === 0) return [];
+    const pageEntries = await resolveSsrPageEntriesForApp(this.#app, pageKeys);
+    const akanConfig = await this.#app.getConfig();
+    return await this.#buildMcpAppViews(pageEntries, {
+      basePaths: [...akanConfig.basePaths],
+      cssAssets: await this.#loadCssAssets(),
+      options: CsrArtifactBuilder.bundleOptions(this.#app, this.#command, akanConfig.optimizeImports),
+    });
+  }
+
+  async #buildMcpAppViews(pageEntries: PageEntry[], option: Parameters<McpAppViewBuilder["build"]>[1]) {
+    const views = await new McpAppViewBuilder(this.#app, this.#command).build(pageEntries, option);
+    if (views.length)
+      this.#app.verbose(`[csr-build] ${views.length} MCP App view(s): ${views.map((view) => view.name).join(", ")}`);
+    return views;
+  }
+
   //? No `env` option: Bun inlines the `.env` it read at process start over `define`, so a native build's `--env` lost.
   static bundleOptions(app: App, command: "build" | "start", optimizeImports: string[] = []) {
     return {
@@ -91,7 +114,7 @@ export class CsrArtifactBuilder {
       define: bundleDefine(app, command, "csr"),
       optimizeImports,
       // A raw `.css` in the route graph is Tailwind source; the base artifact's compiled sheet is the only stylesheet.
-      plugins: [PagesBundleBuilder.createCssStubPlugin(), createBrowserDirnamePlugin()],
+      plugins: [PagesBundleBuilder.createCssStubPlugin(), createBrowserDirnamePlugin(), SideEffectImportOrder.plugin()],
     };
   }
 

package/frontendBuild/cssCandidateCache.test.ts

@@ -23,6 +23,22 @@ describe("CssCandidateCache token extraction", () => {
     expect(candidates).not.toContain("_td");
   });
 
+  test("keeps a bracket nested one level inside another whole, rather than cutting it at the inner `]`", async () => {
+    const candidates = await scan(
+      `const c = "hidden [[data-theme=light]_&]:block has-[[aria-expanded=true]]:opacity-100 [&_[data-x]]:p-2 [&:has([data-state=open])]:p-1";`,
+    );
+    expect(candidates).toEqual(
+      expect.arrayContaining([
+        "[[data-theme=light]_&]:block",
+        "has-[[aria-expanded=true]]:opacity-100",
+        "[&_[data-x]]:p-2",
+        "[&:has([data-state=open])]:p-1",
+      ]),
+    );
+    expect(candidates).not.toContain("[[data-theme=light]_");
+    expect(candidates).not.toContain("[&_[data-x]");
+  });
+
   test("keeps Tailwind v4's variable shorthand whole, and leaves a call's argument its own candidate", async () => {
     const candidates = await scan(
       `const c = "max-md:top-(--keyboard-top) min-h-(--x) bg-(color:--brand)/50"; cn("flex"); fn(value);`,

package/frontendBuild/cssCandidateCache.ts

@@ -1,10 +1,12 @@
 import { stat } from "node:fs/promises";
 
-// The leading `[` alternation keeps arbitrary variants (`[&_td]:px-3`) whole. Brackets hold no whitespace: a labelled
-// tuple type scanned as a class compiles to a rule lightningcss cannot parse, and it then drops every variant rule.
-// Parentheses pass only as Tailwind v4's variable shorthand, `(--x)` or `(length:--x)`, so `cn("flex")` still yields
-// `flex` on its own.
-const CANDIDATE_RE = /-?(?:[\w@]|\[[^\]\s]+\])[\w:/.-]*(?:(?:\[[^\]\s]+\]|\((?:[a-z-]+:)?--[^)\s]+\))[\w:/.-]*)*/g;
+// The leading `[` alternation keeps arbitrary variants (`[&_td]:px-3`) whole, and a bracket may hold one nested
+// bracket (`[&_[data-slot=x]]:p-2`, `has-[[aria-expanded=true]]:x`), or the candidate is cut at the inner `]` and the
+// rule silently never compiles. Brackets hold no whitespace: a labelled tuple type scanned as a class compiles to a
+// rule lightningcss cannot parse, and it then drops every variant rule. Parentheses pass only as Tailwind v4's
+// variable shorthand, `(--x)` or `(length:--x)`, so `cn("flex")` still yields `flex` on its own.
+const CANDIDATE_RE =
+  /-?(?:[\w@]|\[(?:[^[\]\s]|\[[^[\]\s]+\])+\])[\w:/.-]*(?:(?:\[(?:[^[\]\s]|\[[^[\]\s]+\])+\]|\((?:[a-z-]+:)?--[^)\s]+\))[\w:/.-]*)*/g;
 
 interface CachedFile {
   mtimeMs: number;
@@ -20,7 +22,7 @@ interface CacheFile {
 /** Tailwind candidates per source file, on disk: the batch worker that compiles CSS exits before the next save. */
 export class CssCandidateCache {
   // Bump when the token regex or the entry shape changes, so stale extractions are not reused.
-  static readonly #version = 4;
+  static readonly #version = 5;
   readonly #path: string;
   readonly #entries = new Map<string, CachedFile>();
   #dirty = false;

package/frontendBuild/fontPruner.ts

@@ -103,6 +103,7 @@ export class FontPruner {
       { dir: path.join(this.#artifactRoot, "client-ssr"), label: ".akan/artifact/client-ssr", needles: bundled },
       { dir: path.join(this.#artifactRoot, "server"), label: ".akan/artifact/server", needles: bundled },
       { dir: path.join(this.#app.dist.cwdPath, "csr"), label: "csr", needles: bundled },
+      { dir: path.join(this.#app.dist.cwdPath, "mcp-apps"), label: "mcp-apps", needles: bundled },
     ];
     for (const root of roots) {
       const pending = root.needles.filter((candidate) => !referrers.has(candidate.rel));

package/frontendBuild/mcpAppViewBuilder.test.ts

@@ -0,0 +1,170 @@
+import { describe, expect, test } from "bun:test";
+import path from "node:path";
+import { tempDirs, writeText as write } from "../testHelpers";
+import { McpAppViewBuilder } from "./mcpAppViewBuilder";
+
+const makeTempRoot = tempDirs("akan-mcp-app-views-");
+
+const memoPage = [
+  'import { page } from "akanjs/client";',
+  "export default page()",
+  '  .param("memoId", ID)',
+  '  .app("showMemo", "Show one memo.", ({ memoId }) => null)',
+  '  .app("showMemoImages", "Show its images.", ({ memoId }) => null)',
+  "  .render(() => null);",
+].join("\n");
+
+describe("McpAppViewBuilder.discover", () => {
+  test("finds each app of each page, under the root layout that renders the system provider", async () => {
+    const appRoot = await makeTempRoot();
+    const file = (rel: string) => path.join(appRoot, rel);
+    await write(file("generated/__root_layout.tsx"), "export function McpAppRoot() {}\n");
+    await write(file("generated/(home)/__root_layout.tsx"), "export const guard = userLayout.guard;\n");
+    await write(file("page/(home)/memo/[memoId].tsx"), memoPage);
+    await write(
+      file("page/admin/report.tsx"),
+      'export default page().app("showReport", "Show the report.", () => null).render(() => null);',
+    );
+    await write(file("page/plain.tsx"), "export default page().render(() => null);");
+    const entries = [
+      { key: "./__root_layout.tsx", moduleAbsPath: file("generated/__root_layout.tsx") },
+      { key: "./(home)/__root_layout.tsx", moduleAbsPath: file("generated/(home)/__root_layout.tsx") },
+      { key: "./(home)/memo/[memoId].tsx", moduleAbsPath: file("page/(home)/memo/[memoId].tsx") },
+      { key: "./admin/report.tsx", moduleAbsPath: file("page/admin/report.tsx") },
+      { key: "./plain.tsx", moduleAbsPath: file("page/plain.tsx") },
+    ];
+    const views = await McpAppViewBuilder.discover(entries, ["admin"]);
+    expect(views.map(({ name, page, root, basePath }) => [name, page.key, root?.key, basePath])).toEqual([
+      ["showMemo", "./(home)/memo/[memoId].tsx", "./__root_layout.tsx", ""],
+      ["showMemoImages", "./(home)/memo/[memoId].tsx", "./__root_layout.tsx", ""],
+      ["showReport", "./admin/report.tsx", "./__root_layout.tsx", "admin"],
+    ]);
+  });
+
+  test("takes the overrides over each page by route, outermost first, and none from a sibling group", async () => {
+    const appRoot = await makeTempRoot();
+    const file = (rel: string) => path.join(appRoot, rel);
+    await write(file("page/(home)/memo.tsx"), memoPage);
+    const entries = [
+      { key: "./(home)/memo.tsx", moduleAbsPath: file("page/(home)/memo.tsx") },
+      { key: "./(home)/memo/_overrides.tsx", moduleAbsPath: file("generated/memo_overrides.tsx") },
+      { key: "./_overrides.tsx", moduleAbsPath: file("generated/_overrides.tsx") },
+      { key: "./(home)/_overrides.tsx", moduleAbsPath: file("generated/home_overrides.tsx") },
+      { key: "./(tab)/_overrides.tsx", moduleAbsPath: file("generated/tab_overrides.tsx") },
+    ];
+    const [view] = await McpAppViewBuilder.discover(entries, []);
+    expect(view?.rootOverrides).toEqual([]);
+    expect(view?.overrides.map((entry) => entry.key)).toEqual([
+      "./_overrides.tsx",
+      "./(home)/_overrides.tsx",
+      "./(home)/memo/_overrides.tsx",
+    ]);
+  });
+
+  test("puts the overrides on the root layout's node and above it outside that layout, as the route tree does", async () => {
+    const appRoot = await makeTempRoot();
+    const file = (rel: string) => path.join(appRoot, rel);
+    await write(file("generated/(home)/__root_layout.tsx"), "export function McpAppRoot() {}\n");
+    await write(file("page/(home)/memo.tsx"), memoPage);
+    const entries = [
+      { key: "./(home)/__root_layout.tsx", moduleAbsPath: file("generated/(home)/__root_layout.tsx") },
+      { key: "./(home)/memo.tsx", moduleAbsPath: file("page/(home)/memo.tsx") },
+      { key: "./(home)/memo/_overrides.tsx", moduleAbsPath: file("generated/memo_overrides.tsx") },
+      { key: "./(home)/_overrides.tsx", moduleAbsPath: file("generated/home_overrides.tsx") },
+      { key: "./_overrides.tsx", moduleAbsPath: file("generated/_overrides.tsx") },
+    ];
+    const [view] = await McpAppViewBuilder.discover(entries, []);
+    expect(view?.root?.key).toBe("./(home)/__root_layout.tsx");
+    expect(view?.rootOverrides.map((entry) => entry.key)).toEqual(["./_overrides.tsx", "./(home)/_overrides.tsx"]);
+    expect(view?.overrides.map((entry) => entry.key)).toEqual(["./(home)/memo/_overrides.tsx"]);
+  });
+
+  test("keeps an override inside the root layout when its folder holds a layout above the root's", async () => {
+    const appRoot = await makeTempRoot();
+    const file = (rel: string) => path.join(appRoot, rel);
+    await write(file("generated/oauth/__root_layout.tsx"), "export function McpAppRoot() {}\n");
+    await write(file("page/(libs)/(shared)/oauth/consent.tsx"), memoPage);
+    const entries = [
+      { key: "./(libs)/(shared)/oauth/__root_layout.tsx", moduleAbsPath: file("generated/oauth/__root_layout.tsx") },
+      { key: "./(libs)/(shared)/_layout.tsx", moduleAbsPath: file("page/(libs)/(shared)/_layout.tsx") },
+      { key: "./(libs)/(shared)/oauth/consent.tsx", moduleAbsPath: file("page/(libs)/(shared)/oauth/consent.tsx") },
+      { key: "./(libs)/(shared)/oauth/_overrides.tsx", moduleAbsPath: file("generated/oauth_overrides.tsx") },
+      { key: "./(libs)/(shared)/_overrides.tsx", moduleAbsPath: file("generated/shared_overrides.tsx") },
+      { key: "./_overrides.tsx", moduleAbsPath: file("generated/_overrides.tsx") },
+    ];
+    const [view] = await McpAppViewBuilder.discover(entries, []);
+    expect(view?.rootOverrides.map((entry) => entry.key)).toEqual([
+      "./_overrides.tsx",
+      "./(libs)/(shared)/oauth/_overrides.tsx",
+    ]);
+    expect(view?.overrides.map((entry) => entry.key)).toEqual(["./(libs)/(shared)/_overrides.tsx"]);
+  });
+
+  test("names two pages that claim one app, and a page with no root layout to provide for it", async () => {
+    const appRoot = await makeTempRoot();
+    const file = (rel: string) => path.join(appRoot, rel);
+    await write(file("page/a.tsx"), memoPage);
+    await write(file("page/b.tsx"), memoPage);
+    const entries = [
+      { key: "./a.tsx", moduleAbsPath: file("page/a.tsx") },
+      { key: "./b.tsx", moduleAbsPath: file("page/b.tsx") },
+    ];
+    await expect(McpAppViewBuilder.discover(entries, [])).rejects.toThrow(
+      'app "showMemo" is declared by both ./a.tsx and ./b.tsx',
+    );
+    const [view] = await McpAppViewBuilder.discover(entries.slice(0, 1), []);
+    expect(view?.root).toBeNull();
+  });
+
+  test("refuses a name MCP would not list, and two that differ only in case", async () => {
+    const appRoot = await makeTempRoot();
+    const file = (rel: string) => path.join(appRoot, rel);
+    await write(file("page/a.tsx"), memoPage);
+    await write(file("page/b.tsx"), memoPage.replace('"showMemo"', '"ShowMemo"'));
+    await write(file("page/c.tsx"), memoPage.replace('"showMemo"', '"../showMemo"'));
+    const entryOf = (name: string) => ({ key: `./${name}.tsx`, moduleAbsPath: file(`page/${name}.tsx`) });
+    await expect(McpAppViewBuilder.discover([entryOf("a"), entryOf("b")], [])).rejects.toThrow(
+      'apps "showMemo" (./a.tsx) and "ShowMemo" (./b.tsx) differ only in case',
+    );
+    await expect(McpAppViewBuilder.discover([entryOf("c")], [])).rejects.toThrow(
+      'app name "../showMemo" in ./c.tsx must match',
+    );
+  });
+});
+
+describe("McpAppViewBuilder.entryOf", () => {
+  test("boots the one app with its page, the root layout and overrides it sits under, by relative path", () => {
+    const view = {
+      name: "showMemo",
+      page: { key: "./memo/[memoId].tsx", moduleAbsPath: "/app/page/memo/[memoId].tsx" },
+      root: { key: "./__root_layout.tsx", moduleAbsPath: "/app/.akan/generated/root-layouts/__root_layout.tsx" },
+      rootOverrides: [{ key: "./_overrides.tsx", moduleAbsPath: "/app/.akan/generated/overrides/_overrides.tsx" }],
+      overrides: [{ key: "./memo/_overrides.tsx", moduleAbsPath: "/app/.akan/generated/overrides/memo.tsx" }],
+      basePath: "admin",
+    };
+    expect(McpAppViewBuilder.entryOf(view, "/app/.akan/generated/mcp-apps")).toBe(
+      [
+        'import { McpAppBoot } from "akanjs/webkit";',
+        'import * as page from "../../../page/memo/[memoId].tsx";',
+        'import * as root from "../root-layouts/__root_layout.tsx";',
+        'import rootOverride0 from "../overrides/_overrides.tsx";',
+        'import override0 from "../overrides/memo.tsx";',
+        "void McpAppBoot.run({",
+        '  app: "showMemo",',
+        "  page,",
+        "  root,",
+        "  rootOverrides: [rootOverride0],",
+        "  overrides: [override0],",
+        '  basePath: "admin",',
+        "});",
+        "",
+      ].join("\n"),
+    );
+    expect(
+      McpAppViewBuilder.entryOf(
+        { ...view, root: null, rootOverrides: [], overrides: [] },
+        "/app/.akan/generated/mcp-apps",
+      ),
+    ).toContain("const root = {};\nvoid McpAppBoot.run({");
+  });
+});

package/frontendBuild/mcpAppViewBuilder.ts

@@ -0,0 +1,245 @@
+import { mkdir, readdir, rename, rm, unlink } from "node:fs/promises";
+import path from "node:path";
+import { parseRouteModuleKey } from "akanjs/common";
+import type { BaseBuildArtifact } from "akanjs/server";
+import type { PageEntry } from "../artifact/implicitRootLayout";
+import type { App } from "../commandDecorators";
+import { McpAppPageTrimmer } from "../transforms/mcpAppPageTrimmer";
+import { PureLazyMarker } from "../transforms/pureLazyMarker";
+import { CsrArtifactBuilder } from "./csrArtifactBuilder";
+import { CsrEntryFiles } from "./csrEntryFiles";
+
+type CssAsset = NonNullable<BaseBuildArtifact["cssAssets"]>[string];
+
+interface McpAppViewBuildOption {
+  basePaths: string[];
+  cssAssets: Record<string, CssAsset>;
+  /** The CSR shell's own bundle options, so a view inlines the same env and stubs the same stylesheets. */
+  options: ReturnType<typeof CsrArtifactBuilder.bundleOptions>;
+}
+
+export interface McpAppView {
+  name: string;
+  page: PageEntry;
+  /** The generated root layout that renders `System.Provider` for the page, whose `McpAppRoot` the view uses. */
+  root: PageEntry | null;
+  /** The generated wrappers of the `_overrides.tsx` the web draws outside the root layout, outermost first: they also
+   * reach what it draws beside the page, its toasts and approvals. */
+  rootOverrides: PageEntry[];
+  /** The generated wrappers of the rest of the `_overrides.tsx` over the page, outermost first, around it alone. */
+  overrides: PageEntry[];
+  basePath: string;
+}
+
+//* One single-file HTML per `.app()`, which an MCP host renders as that app's view: its entry imports the app's page,
+//* trimmed to its loads, and the page's root layout for its providers. Built beside `csr/`, never inside it: a native
+//* app packs `csr/`, which needs none of them.
+export class McpAppViewBuilder {
+  /** The folder the server reads views from: `WebRouter.mcpAppViewDir`. */
+  static readonly dirName = "mcp-apps";
+  /** `PageDefinition.promptName`, which also keeps a view's file name inside its folder. */
+  static readonly #appName = /^[A-Za-z0-9_-]{1,64}$/;
+
+  readonly #app: App;
+  readonly #command: "build" | "start";
+
+  constructor(app: App, command: "build" | "start") {
+    this.#app = app;
+    this.#command = command;
+  }
+
+  get outputDir(): string {
+    return this.#command === "build"
+      ? path.join(this.#app.dist.cwdPath, McpAppViewBuilder.dirName)
+      : path.join(this.#app.cwdPath, ".akan", "artifact", McpAppViewBuilder.dirName);
+  }
+
+  async build(
+    pageEntries: PageEntry[],
+    { basePaths, cssAssets, options }: McpAppViewBuildOption,
+  ): Promise<McpAppView[]> {
+    const views = await McpAppViewBuilder.discover(pageEntries, basePaths);
+    if (!views.length) {
+      await rm(this.outputDir, { recursive: true, force: true });
+      return views;
+    }
+    //? Built aside, then moved in a file at a time: a host may read a view while `akan start` rebuilds them.
+    const stagingDir = `${this.outputDir}.next`;
+    await rm(stagingDir, { recursive: true, force: true });
+    const generatedDir = path.join(this.#app.cwdPath, ".akan", "generated", McpAppViewBuilder.dirName);
+    await rm(generatedDir, { recursive: true, force: true });
+    await mkdir(generatedDir, { recursive: true });
+    const files = Object.fromEntries(
+      views.flatMap((view) => [
+        [path.join(generatedDir, `${view.name}.html`), McpAppViewBuilder.htmlOf(view)],
+        [path.join(generatedDir, `${view.name}.view.tsx`), McpAppViewBuilder.entryOf(view, generatedDir)],
+      ]),
+    );
+    const pagePaths = [...new Set(views.map((view) => view.page.moduleAbsPath))];
+    const result = await Bun.build({
+      ...options,
+      plugins: [...options.plugins, McpAppPageTrimmer.plugin(pagePaths), PureLazyMarker.plugin()],
+      entrypoints: views.map((view) => path.join(generatedDir, `${view.name}.html`)),
+      files,
+      root: generatedDir,
+      outdir: stagingDir,
+    });
+    if (!result.success) {
+      const logs = result.logs.map((log) => log.message).join("\n");
+      throw new Error(`[mcp-app-build] failed${logs ? `\n${logs}` : ""}`);
+    }
+    for (const view of views) await this.#inline(view, stagingDir, cssAssets[view.basePath]);
+    await this.#publish(views, stagingDir);
+    return views;
+  }
+
+  async #publish(views: McpAppView[], stagingDir: string) {
+    const names = new Set(views.map((view) => `${view.name}.html`));
+    await mkdir(this.outputDir, { recursive: true });
+    for (const name of names) await rename(path.join(stagingDir, name), path.join(this.outputDir, name));
+    for (const name of await readdir(this.outputDir))
+      if (!names.has(name)) await rm(path.join(this.outputDir, name), { recursive: true, force: true });
+    const strays = await readdir(stagingDir);
+    if (strays.length)
+      this.#app.logger.warn(
+        `[mcp-app-build] ${strays.join(", ")} reached no view; a view loads nothing beside its own file`,
+      );
+    await rm(stagingDir, { recursive: true, force: true });
+  }
+
+  /** Every `.app()` the pages declare, read off their sources without evaluating them. */
+  static async discover(pageEntries: PageEntry[], basePaths: string[]): Promise<McpAppView[]> {
+    const { RouteSourceValidator } = await import("../routeSourceValidator");
+    const roots = pageEntries.filter((entry) => parseRouteModuleKey(entry.key).isInternalRootLayout);
+    const overrides = pageEntries.filter((entry) => parseRouteModuleKey(entry.key).kind === "overrides");
+    const layoutNodes = new Set(
+      pageEntries.flatMap((entry) => {
+        const parsed = parseRouteModuleKey(entry.key);
+        return parsed.kind === "layout" && !parsed.isInternalRootLayout ? [parsed.routeSegments.join("/")] : [];
+      }),
+    );
+    const owners = new Map<string, { name: string; key: string }>();
+    const views: McpAppView[] = [];
+    for (const page of pageEntries) {
+      if (parseRouteModuleKey(page.key).kind !== "page") continue;
+      const source = await Bun.file(page.moduleAbsPath).text();
+      const apps =
+        RouteSourceValidator.validateRouteSourceExports(source, page.moduleAbsPath, "page").chain?.apps ?? [];
+      for (const name of apps) {
+        if (!McpAppViewBuilder.#appName.test(name))
+          throw new Error(
+            `[route-convention] app name "${name}" in ${page.key} must match ${McpAppViewBuilder.#appName}`,
+          );
+        //? Keyed in lower case: a case-insensitive disk would write two such views to one file.
+        const owner = owners.get(name.toLowerCase());
+        if (owner?.name === name)
+          throw new Error(`[route-convention] app "${name}" is declared by both ${owner.key} and ${page.key}`);
+        if (owner)
+          throw new Error(
+            `[route-convention] apps "${owner.name}" (${owner.key}) and "${name}" (${page.key}) differ only in case; their views would share one file`,
+          );
+        owners.set(name.toLowerCase(), { name, key: page.key });
+        const root = await McpAppViewBuilder.#rootOf(page.key, roots);
+        views.push({
+          name,
+          page,
+          root,
+          ...McpAppViewBuilder.#overridesOf(page.key, root, overrides, layoutNodes),
+          basePath: CsrEntryFiles.basePathOfPageKey(page.key, basePaths) ?? "",
+        });
+      }
+    }
+    return views;
+  }
+
+  static htmlOf(view: McpAppView): string {
+    return `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>${view.name}</title>
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="./${view.name}.view.tsx"></script>
+  </body>
+</html>
+`;
+  }
+
+  static entryOf(view: McpAppView, fromDir: string): string {
+    const specifier = (absPath: string) => {
+      const relative = path.relative(fromDir, absPath).split(path.sep).join("/");
+      return JSON.stringify(relative.startsWith(".") ? relative : `./${relative}`);
+    };
+    const importsOf = (entries: PageEntry[], name: string) =>
+      entries.map((entry, idx) => `import ${name}${idx} from ${specifier(entry.moduleAbsPath)};\n`).join("");
+    const namesOf = (entries: PageEntry[], name: string) => entries.map((_, idx) => `${name}${idx}`).join(", ");
+    return `import { McpAppBoot } from "akanjs/webkit";
+import * as page from ${specifier(view.page.moduleAbsPath)};
+${view.root ? `import * as root from ${specifier(view.root.moduleAbsPath)};` : "const root = {};"}
+${importsOf(view.rootOverrides, "rootOverride")}${importsOf(view.overrides, "override")}void McpAppBoot.run({
+  app: ${JSON.stringify(view.name)},
+  page,
+  root,
+  rootOverrides: [${namesOf(view.rootOverrides, "rootOverride")}],
+  overrides: [${namesOf(view.overrides, "override")}],
+  basePath: ${JSON.stringify(view.basePath)},
+});
+`;
+  }
+
+  //? By route segments, as the route tree nests them (`RouteLayering`): a folder's `_overrides.tsx` also covers the
+  //? page file named like the folder (`memo/_overrides.tsx` over `memo.tsx`), and one on a root node sits outside the
+  //? root layout — the root layout's own node, or one above it that holds no layout of its own.
+  static #overridesOf(pageKey: string, root: PageEntry | null, overrides: PageEntry[], layoutNodes: Set<string>) {
+    const pageSegments = parseRouteModuleKey(pageKey).routeSegments;
+    const rootDepth = root ? parseRouteModuleKey(root.key).routeSegments.length : 0;
+    const over = overrides
+      .map((entry) => ({ entry, segments: parseRouteModuleKey(entry.key).routeSegments }))
+      .filter(({ segments }) => segments.every((segment, idx) => pageSegments[idx] === segment))
+      .sort((a, b) => a.segments.length - b.segments.length);
+    const onRootNode = (segments: string[]) =>
+      segments.length === rootDepth || (segments.length < rootDepth && !layoutNodes.has(segments.join("/")));
+    return {
+      rootOverrides: over.filter(({ segments }) => onRootNode(segments)).map(({ entry }) => entry),
+      overrides: over.filter(({ segments }) => !onRootNode(segments)).map(({ entry }) => entry),
+    };
+  }
+
+  //? The outermost root boundary over the page: the one a page is drawn under without an ancestor root, which alone
+  //? renders `System.Provider` and so exports `McpAppRoot`.
+  static async #rootOf(pageKey: string, roots: PageEntry[]): Promise<PageEntry | null> {
+    const dirOf = (key: string) => key.slice(0, key.lastIndexOf("/") + 1);
+    const pageDir = dirOf(pageKey);
+    const over = roots
+      .filter((root) => pageDir.startsWith(dirOf(root.key)))
+      .sort((a, b) => dirOf(a.key).length - dirOf(b.key).length);
+    for (const root of over)
+      if ((await Bun.file(root.moduleAbsPath).text()).includes("export function McpAppRoot")) return root;
+    return null;
+  }
+
+  async #inline(view: McpAppView, dir: string, cssAsset: CssAsset | undefined) {
+    const htmlPath = path.join(dir, `${view.name}.html`);
+    let html = await Bun.file(htmlPath).text();
+    if (cssAsset) {
+      const artifactDir = path.join(
+        this.#command === "build" ? this.#app.dist.cwdPath : this.#app.cwdPath,
+        ".akan",
+        "artifact",
+      );
+      const css = await Bun.file(path.join(artifactDir, cssAsset.cssRelPath)).text();
+      html = CsrArtifactBuilder.injectBeforeHeadEnd(html, CsrArtifactBuilder.createInlineStyle(css));
+    } else this.#app.logger.warn(`[mcp-app-build] no compiled stylesheet for ${view.name}; its view ships without CSS`);
+    const scripts: string[] = [];
+    html = await CsrArtifactBuilder.replaceModuleScriptSrc(html, async (src) => {
+      const jsPath = CsrArtifactBuilder.resolveHtmlAssetPath(htmlPath, src);
+      scripts.push(jsPath);
+      return await Bun.file(jsPath).text();
+    });
+    await Bun.write(htmlPath, html);
+    for (const script of scripts) await unlink(script).catch(() => undefined);
+  }
+}

package/incrementalBuilder/buildBatch.proc.ts

@@ -108,10 +108,10 @@ class BuildBatch {
   async #buildShell(): Promise<void> {
     const started = Date.now();
     try {
-      await new CsrArtifactBuilder(this.#app, "start", "en", { cssAssets: this.#request.cssAssets }).build();
-      this.#logger.verbose(`csr-shell ok (${Date.now() - started}ms)`);
+      await new CsrArtifactBuilder(this.#app, "start", "en", { cssAssets: this.#request.cssAssets }).buildMcpAppViews();
+      this.#logger.verbose(`mcp-app-views ok (${Date.now() - started}ms)`);
     } catch (err) {
-      this.#fail("shell", "csr-shell", err);
+      this.#fail("shell", "mcp-app-views", err);
     }
   }
 

package/incrementalBuilder/buildBatchProtocol.ts

@@ -3,8 +3,8 @@ import type { BaseBuildArtifact, CssPayload, HmrTrace, PagesBundlePayload } from
 
 export type OptimizedFonts = Awaited<ReturnType<FontOptimizer["optimize"]>>;
 
-// `base` is the boot build: it always runs alone, before the builder can serve anything. `shell` is the single-file
-// CSR build an MCP Apps view needs under the dev CSR registry, made on request and reported to no tab.
+// `base` is the boot build: it always runs alone, before the builder can serve anything. `shell` is the MCP App views'
+// single-file build under the dev CSR registry, made on request and reported to no tab.
 export type BuildBatchNeed = "base" | "pages" | "css" | "csr" | "ssr" | "shell";
 
 // JSON only: the worker is spawned per batch and receives this in its argv.

package/lint/__fixtures__/no-conditional-st-hook/bad.tsx

@@ -0,0 +1,45 @@
+export const A = () => {
+  const busy = st.use.xUploading() || !!st.use.xFormUploading().voice; // @flag
+  const shown = open && st.sel((s) => s.a); // @flag
+  const label = name ?? st.use.defaultName(); // @flag
+  const picked = open ? st.use.b() : null; // @flag
+  const latest = open ? null : st.ref((s) => s.c); // @flag
+  if (open) { const d = st.use.d(); } // @flag
+  if (open) { run(); } else { const e = st.slice.inOrg.use.e(); } // @flag
+  switch (mode) { case "a": st.use.f(); } // @flag
+  for (const item of items) st.use.g(); // @flag
+  while (more) st.use.h(); // @flag
+  try { run(); } catch { st.use.i(); } // @flag
+  const rows = items.map((item) => st.use.j()); // @flag
+  useEffect(() => { st.use.k(); }, []); // @flag
+  const tool = open && st.tool("x").desc("d").exec(() => run()); // @flag
+  const card = open ? st.tool("y").desc("d").card(() => null) : null; // @flag
+  const [l] = open ? st.useState("l", String).desc("d").init("") : []; // @flag
+  if (open) st.expose("m", String).desc("d").value("x"); // @flag
+  const save = st.tool("z").desc("d").exec(async () => { st.use.n(); }); // @flag
+  const { title = st.use.title() } = props; // @flag
+  let cached = initial; cached ||= st.use.s(); // @flag
+  cached ??= st.use.t(); // @flag
+  cached &&= st.use.u(); // @flag
+  for (let i = 0; i < st.use.count(); i++) run(i); // @flag
+  const formatted = props.format?.(st.use.v()); // @flag
+  const chained = props.api?.format(st.use.w()); // @flag
+  const computed = open ? st["use"].x() : null; // @flag
+  const computedKey = open ? st.use["y"]() : null; // @flag
+  const computedSlice = open ? st.slice["inOrg"].use.z() : null; // @flag
+  useEffect(() => { void (async () => { await load(); st.use.aa(); })(); }, []); // @flag
+  return <div onClick={() => st.use.o()} />; // @flag
+};
+export const B = () => <Load.Units renderList={(list) => <X a={st.use.p()} />} />; // @flag
+export const C = () => <Load.Stream of={q}>{(v) => <X a={st.sel((s) => s.q)} />}</Load.Stream>; // @flag
+export const useD = () => useMemo(() => st.use.r(), []); // @flag
+export const E = ({ name = st.use.defaultName() }) => <p>{name}</p>; // @flag
+export function F({ name = st.sel((s) => s.name) }) { return <p>{name}</p>; } // @flag
+export const G = () => {
+  const renderRow = (item) => <X a={st.use.bb()} />; // @flag
+  return <Load.Units renderItem={renderRow} />;
+};
+export const H = () => {
+  function row(item) { return <X a={st.ref((s) => s.cc)} />; } // @flag
+  return <ul>{items.map(row)}</ul>;
+};