@akanjs/devkit 3.1.0-rc.20 → 3.1.0-rc.22

package/frontendBuild/csrArtifactBuilder.ts

@@ -6,6 +6,7 @@ import type { App } from "../commandDecorators";
 import { createBrowserDirnamePlugin } from "../transforms/browserDirnamePlugin";
 import { bundleDefine } from "./bundleDefine";
 import { CsrEntryFiles } from "./csrEntryFiles";
+import { type McpAppView, McpAppViewBuilder } from "./mcpAppViewBuilder";
 import { PagesBundleBuilder } from "./pagesBundleBuilder";
 import { PagesEntrySourceGenerator } from "./pagesEntrySourceGenerator";
 
@@ -77,11 +78,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 {

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,24 @@
+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
+  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

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

@@ -0,0 +1,22 @@
+export const A = () => {
+  const uploading = st.use.xUploading(); // @ok
+  const formUploading = st.use.xFormUploading(); // @ok
+  const busy = uploading || !!formUploading.voice; // @ok
+  const first = st.use.a() || fallback; // @ok
+  const picked = st.use.b() ? one : two; // @ok
+  if (st.use.c()) run(); // @ok
+  switch (st.use.mode()) { case "a": run(); } // @ok
+  for (const item of st.use.items()) run(item); // @ok
+  const selected = st.sel((s) => s.d); // @ok
+  const latest = st.ref((s) => s.e); // @ok
+  const save = st.tool("save").desc("d").exec(async () => { await st.do.saveX(); }); // @ok
+  const [f, setF] = st.useState("f", String).desc("d").init(""); // @ok
+  st.expose("g", String).desc("d").value(f); // @ok
+  useEffect(() => st.sub((s) => s.h, run), []); // @ok
+  return <div onClick={() => st.do.setNameOnX(st.get().name)}>{open ? <Child /> : null}</div>; // @ok
+};
+export const B = memo(() => { const a = st.use.a(); return null; }); // @ok
+export const C = forwardRef((props, ref) => { const b = st.sel((s) => s.b); return null; }); // @ok
+export const useTools = () => { const tool = (name) => st.tool(name).desc("d").exec(() => run()); tool("a"); }; // @ok
+export const D = () => <Load.Units renderItem={(item) => <Row key={item.id} id={item.id} />} />; // @ok
+export const E = () => { const busy = open && other.use.x(); return busy; }; // @ok

package/lint/no-conditional-st-hook.grit

@@ -0,0 +1,75 @@
+engine biome(1.0)
+language js(typescript, jsx)
+
+// `st.use.<key>()`, `st.sel()`, `st.ref()` and the builders' last step (`st.tool(…)….exec()` / `.card()`,
+// `st.useState(…)….init()`, `st.expose(…)….value()`) are React hooks that Biome's `useHookAtTopLevel` cannot see:
+// it recognises a hook by a `use` prefix on the called name. A hook a render skips shifts every later hook by one
+// slot, and production React does not check the order — a later `useRef` then receives a frozen store value and
+// the screen dies far from the cause ("Cannot add property current, object is not extensible").
+//
+// Reported: the right operand of `||` / `&&` / `??`, a ternary branch, an `if` / `else` body, a `switch` case, a
+// loop, a `catch` block, and a callback handed to a call or a JSX prop inside a component (`.map`, `useEffect`,
+// an event handler, a render prop — `Load.Units` calls `renderList` only while the list is non-empty). A test
+// position is not reported: `if (st.use.x())` always runs.
+//
+// Not reported: a hook after an early `return` (GritQL sees no statement order), a local helper the component
+// calls (`const tool = (name) => st.tool(name)…exec(…)` runs a fixed number of times when called at top level),
+// and a hook reached through anything but the `st` identifier.
+//
+pattern st_hook_call() {
+  or {
+    `st.use.$key($args)`,
+    `st.slice.$slice.use.$key($args)`,
+    `st.sel($args)`,
+    `st.ref($args)`,
+    `$chain.exec($args)` where { $chain <: r"st\s*\.\s*tool\s*\([\s\S]*" },
+    `$chain.card($args)` where { $chain <: r"st\s*\.\s*tool\s*\([\s\S]*" },
+    `$chain.init($args)` where { $chain <: r"st\s*\.\s*useState\s*\([\s\S]*" },
+    `$chain.value($args)` where { $chain <: r"st\s*\.\s*expose\s*\([\s\S]*" }
+  }
+}
+
+pattern function_like() {
+  or {
+    JsArrowFunctionExpression(),
+    JsFunctionExpression(),
+    JsFunctionDeclaration(),
+    JsMethodObjectMember(),
+    JsMethodClassMember()
+  }
+}
+
+JsCallExpression() as $call where {
+  $call <: st_hook_call(),
+  or {
+    $call <: within JsLogicalExpression(right = $right) where { $right <: contains $call },
+    $call <: within JsConditionalExpression(consequent = $then, alternate = $else) where {
+      or { $then <: contains $call, $else <: contains $call }
+    },
+    $call <: within JsIfStatement(consequent = $then, else_clause = $else) where {
+      or { $then <: contains $call, $else <: contains $call }
+    },
+    $call <: within JsForOfStatement(body = $body) where { $body <: contains $call },
+    $call <: within JsForInStatement(body = $body) where { $body <: contains $call },
+    $call <: within or {
+      JsCaseClause(),
+      JsDefaultClause(),
+      JsForStatement(),
+      JsWhileStatement(),
+      JsDoWhileStatement(),
+      JsCatchClause()
+    },
+    // The callback must be handed over inside another function: a component passed to `memo()` / `forwardRef()`
+    // at module level is not one.
+    $call <: within function_like() as $inner where {
+      $inner <: within or { JsCallArguments(), JsxExpressionAttributeValue(), JsxExpressionChild() } as $slot where {
+        $slot <: within function_like()
+      }
+    }
+  },
+  register_diagnostic(
+    span = $call,
+    message = "This st hook does not run on every render — it sits behind a condition, in a loop, or in a nested function. React matches hooks by call order, so the hooks after it shift by one slot and a later one reads another hook's state; production React does not check, and the screen crashes somewhere else. Read each st.use.* into its own const at the top of the component, then combine the values: const uploading = st.use.xUploading(); const formUploading = st.use.xFormUploading(); const busy = uploading || !!formUploading.voice. For a list, move the hook into a child component rendered per item.",
+    severity = "error"
+  )
+}

package/mobile/desktopServerStage.ts

@@ -33,6 +33,7 @@ export class DesktopServerStage {
     "console.js",
     "console-runtime.js",
     "csr",
+    "mcp-apps",
     "public",
     ".akan",
   ]);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akanjs/devkit",
-  "version": "3.1.0-rc.20",
+  "version": "3.1.0-rc.22",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -48,7 +48,7 @@
     "@earendil-works/pi-tui": "1.3.0",
     "@inquirer/prompts": "^8.7.3",
     "@tailwindcss/node": "^4.3.3",
-    "akanjs": "3.1.0-rc.20",
+    "akanjs": "3.1.0-rc.22",
     "chalk": "^6.0.1",
     "commander": "^15.0.0",
     "dayjs": "^1.11.23",