akanjs 3.0.2 → 3.1.0-rc.0

package/fetch/fetchType/buildFetch.type.ts

@@ -19,6 +19,7 @@ export type FetchProxySignalInput<
 > = {
   handler: Record<string, unknown>;
   serializedSignal: Record<string, SerializedSignal>;
+  ownSerializedSignal?: Record<string, SerializedSignal>;
   _FetchType: FetchType;
   _SliceMetaObj: SliceMetaObj;
 };

package/index.ts

@@ -1,5 +1,11 @@
 import type { AkanNativeConfig } from "./vendor/@akanjs/native/packages/cli/src/config.ts";
-import type { AkanI18nConfig } from "akanjs/common";
+import type {
+  AkanI18nConfig,
+  PipelineActionName,
+  PipelineMilestone,
+  PipelineOtaPlatform,
+  PipelineTrigger,
+} from "akanjs/common";
 import type { AkanImageConfig } from "akanjs/server";
 
 export const archs = ["amd64", "arm64"] as const;
@@ -126,12 +132,18 @@ export interface AkanNativeDeepLinks {
  */
 export interface AkanNativeUpdatesConfig {
   /**
-   * A static base URL, https in a release build: `<url>/<os>-<arch>/<channel>.json` (desktop) or `<url>/<platform>/…`
-   * (a phone's web bundle).
+   * A static base URL, https in a release build, with no query: `<url>/<os>-<arch>/<channel>.json` (desktop) or
+   * `<url>/<platform>/<channel>/<nativeApi>.json` (a phone's web bundle, one envelope per binary generation).
    */
   url: string;
-  /** The update key's public half, the raw 32-byte Ed25519 key in base64 (`akan update-keygen` prints it). */
-  publicKey: string;
+  /**
+   * The keys a phone binary trusts, raw 32-byte Ed25519 public keys in base64 (`akan update-keygen` prints one), 1 to
+   * 3: the online signing key first, offline spares after it, since a key may revoke only keys listed before it. A
+   * desktop app trusts the first.
+   */
+  publicKeys?: string[];
+  /** The one-key form of `publicKeys`. */
+  publicKey?: string;
   /**
    * The manifest the app follows, e.g. a "pilot" target's "pilot". Default: the backend env the app is built for
    * (`main`, `develop`, `debug`, `local`).
@@ -139,6 +151,11 @@ export interface AkanNativeUpdatesConfig {
   channel?: string;
   /** How long a newly applied release has to call notifyReady() before it is rolled back, ms. Default 10000. */
   readyTimeout?: number;
+  /**
+   * Where a phone posts what became of each release (downloaded, applied, confirmed, rolled back, failed) at its next
+   * launch or return to the foreground, so rollback rates are visible. Left out, nothing is sent.
+   */
+  report?: { url: string };
 }
 
 export interface AkanNativeIosConfig {
@@ -182,6 +199,23 @@ export interface AkanNativeDesktopServerConfig {
    * The server's own bundle must not import them. The image is unchanged.
    */
   omit?: string[];
+  /**
+   * The server bundles `env/env.server.<env>.<profile>.ts` in place of `env/env.server.<env>.ts`, so the environment's
+   * own file and its secrets stay off the computers the app is installed on. The build refuses a profile file that holds
+   * a secret-named value.
+   */
+  profile?: string;
+  /** What the server mounts, as `AKAN_MODULES`: names, or `@edge` for every module whose `serve()` lists edge. */
+  modules?: string[];
+  /**
+   * Variables the server starts with over the image's, written into the app where anyone on the computer reads them:
+   * the build refuses a secret-named one, and those the launcher or the stage sets.
+   */
+  env?: Record<string, string>;
+  /** Crashes in a row before the app gives up on its server, 5 unless named; `"forever"` for a screen nobody attends. */
+  restart?: "forever" | number;
+  /** Asks the running server's health route every `intervalMs` (10 s) and restarts it after `failures` (3) missed. */
+  watchdog?: boolean | { intervalMs?: number; failures?: number };
 }
 
 export interface AkanNativeDesktopConfig {
@@ -189,7 +223,8 @@ export interface AkanNativeDesktopConfig {
   indexPath?: string;
   /**
    * The desktop app carries the app's server (API only, database mode single, on loopback) and its pages call
-   * nothing else: `true`, or `{ omit }` to carry it without some of the image's packages. `build-desktop`,
+   * nothing else: `true`, or `{ omit, profile, modules }` to carry it without some of the image's packages, with a
+   * secret-free env, or with only some modules. `build-desktop`,
    * `start-desktop` and `publish-update` all read it, and an installed app refuses a release that carries a server
    * when it has none, or none when it has one.
    */
@@ -200,13 +235,23 @@ export interface AkanNativeDesktopConfig {
    * app nobody attends. `"errorPage"` (default): one reload, then an error page, and a quit for the browser.
    */
   recovery?: "errorPage" | "reload";
-  /** The main window from its first frame: borderless fullscreen, and no taskbar button (Windows, Linux). */
-  window?: { fullscreen?: boolean; skipTaskbar?: boolean };
+  /**
+   * The main window from its first frame: borderless fullscreen, no taskbar button (Windows, Linux), and no title
+   * bar or border (`frameless`, a kiosk drawn at an exact size).
+   */
+  window?: { fullscreen?: boolean; skipTaskbar?: boolean; frameless?: boolean };
   /**
    * Windows: `"auto"` answers getDisplayMedia() with the first screen at once, no picker or gesture — remote
    * support on an unattended screen; it covers every media request, so not for an app that asks for a camera.
    */
   screenCapture?: "picker" | "auto";
+  /**
+   * Windows installer: `"bootstrapper"` (default) carries Microsoft's small setup that downloads the WebView2 Runtime
+   * where none is installed; `"standalone"` carries the whole runtime (~200 MB) for a PC offline at install.
+   */
+  webview2?: "bootstrapper" | "standalone";
+  /** Windows: who publishes the app, as the installed app's Publisher and its executable's company name (default: the app name). */
+  publisher?: string;
   /**
    * macOS: entitlements of the app's executable beyond what it gets by itself — the JIT's under the hardened runtime and
    * the camera's or microphone's when a usage text asks for it — e.g. `com.apple.security.cs.disable-library-validation`
@@ -264,11 +309,18 @@ export interface AkanNativeSettings {
   icon?: string | { image: string; backgroundColor?: string };
   /** A PNG shown centered at launch, or the launch screen's color, image and when it hides. */
   splash?: string | NonNullable<AkanNativeConfig["splash"]>;
+  /** A window's and an external view's color before its page paints (and the splash's default): one, or `{ light, dark }`. Default white / black. */
+  backgroundColor?: string | { light: string; dark: string };
   permissions?: NativePermission[];
   /** Native runtime plugins beyond the ones the permissions bring: a builtin id (`"iap"`) or a folder, from the app's. */
   plugins?: string[];
   deepLinks?: AkanNativeDeepLinks;
   updates?: Partial<AkanNativeUpdatesConfig>;
+  /**
+   * The web inspector (Safari's, `chrome://inspect`) in a release build too, as a debug build always has it: for an
+   * internal test target only, since anyone holding the device can then read and drive the page.
+   */
+  devtools?: boolean;
   ios?: AkanNativeIosConfig;
   android?: AkanNativeAndroidConfig;
   desktop?: AkanNativeDesktopConfig;
@@ -429,12 +481,180 @@ export interface LibConfigContext {
   readonly type: "lib";
 }
 
+export type PipelineDuration = number | `${number}s` | `${number}m` | `${number}h`;
+
+/** In the `PipelinePattern` dialect of `akanjs/common`; a leading `!` excludes. */
+export type PipelineGlob = string | readonly string[];
+
+/** Every key given must hold. `branch` and `trigger` are decided by the planner, `changed` by the executor. */
+export interface PipelineWhen {
+  branch?: PipelineGlob;
+  trigger?: PipelineTrigger | readonly PipelineTrigger[];
+  /** Paths changed since the branch's newest successful build; an unknown baseline counts as changed. */
+  changed?: PipelineGlob;
+}
+
+export interface PipelineStepInput {
+  sh: string;
+  id?: string;
+  name?: string;
+  /** Relative to the workspace root, never above it. */
+  cwd?: string;
+  env?: Record<string, string>;
+  secrets?: readonly string[];
+  timeout?: PipelineDuration;
+  /** Total attempts. */
+  retry?: number | { attempts: number; delay?: PipelineDuration };
+  allowFailure?: boolean;
+  skipExitCodes?: readonly number[];
+}
+
+export type PipelineStepLike = string | PipelineStepInput;
+
+/** `timeout` and `allowFailure` cover the whole stage, every parallel branch and per-app copy included. */
+export interface PipelineStageBase {
+  id?: string;
+  description?: string;
+  milestone?: PipelineMilestone;
+  when?: PipelineWhen;
+  timeout?: PipelineDuration;
+  allowFailure?: boolean;
+}
+
+export interface PipelineShellStageInput extends PipelineStageBase {
+  name: string;
+  /** Exactly one of `sh` and `steps`. */
+  sh?: string;
+  steps?: readonly PipelineStepLike[];
+  env?: Record<string, string>;
+  secrets?: readonly string[];
+  /** For each step that names no `retry` of its own. */
+  retry?: PipelineStepInput["retry"];
+  use?: never;
+  parallel?: never;
+  matrix?: never;
+}
+
+/** No action parameters yet: rollout wait and prepull stay the executor's settings. */
+export interface PipelineActionStageInput extends PipelineStageBase {
+  use: Exclude<PipelineActionName, "ota">;
+  name?: string;
+  retry?: number;
+  targets?: never;
+  platforms?: never;
+  sh?: never;
+  steps?: never;
+  parallel?: never;
+  matrix?: never;
+}
+
+/**
+ * An over-the-air update of the app's native web bundle, packed per target and platform for the executor to sign and
+ * publish. Every target named must declare `native.updates`.
+ */
+export interface PipelineOtaStageInput extends PipelineStageBase {
+  use: "ota";
+  name?: string;
+  retry?: number;
+  /** Default: every native target that declares `native.updates`. */
+  targets?: readonly string[];
+  /** Default: both. */
+  platforms?: readonly PipelineOtaPlatform[];
+  sh?: never;
+  steps?: never;
+  parallel?: never;
+  matrix?: never;
+}
+
+export type AppPipelineStageInput = PipelineActionStageInput | PipelineOtaStageInput | PipelineShellStageInput;
+
+export interface AppPipelineInput {
+  schemaVersion?: 1;
+  /** This app's stages in order, the actions it takes included. */
+  stages: readonly AppPipelineStageInput[];
+  env?: Record<string, string>;
+  /** Apps whose turn comes before this one's where apps run one at a time (deploy). Apps not in the run are ignored. */
+  after?: readonly string[];
+}
+
+export interface PipelineContext {
+  readonly branch: string;
+  readonly env: string;
+  /** Apps this run builds. */
+  readonly apps: readonly string[];
+  /** Every app in this checkout: a subspace sees its slice only. */
+  readonly workspaceApps: readonly string[];
+  readonly trigger: PipelineTrigger;
+  readonly buildNum: number;
+  readonly commit: string | null;
+}
+
+export interface AppPipelineContext extends PipelineContext {
+  readonly app: string;
+}
+
+/** Read by `akan pipeline` alone: the app config loader drops it, so it never reaches `akan.app.json`. */
+export type AppPipelineConfig = AppPipelineInput | ((ctx: AppPipelineContext) => AppPipelineInput);
+
+/** What an app without a `pipeline` runs. */
+export const defaultAppPipeline = {
+  stages: [{ use: "build" }, { use: "docker" }, { use: "deploy" }],
+} as const satisfies AppPipelineInput;
+
+/** One copy per app of the run, each with AKAN_CI_APP; `when.app` narrows the apps. */
+export interface PipelineMatrixStageInput extends Omit<PipelineShellStageInput, "matrix" | "when"> {
+  matrix: "apps";
+  maxParallel?: number;
+  when?: PipelineWhen & { app?: PipelineGlob };
+}
+
+export interface PipelineParallelStageInput extends PipelineStageBase {
+  name: string;
+  parallel: readonly PipelineShellStageInput[];
+  maxParallel?: number;
+  /** Cancel the other branches when one fails. */
+  failFast?: boolean;
+  env?: Record<string, string>;
+  secrets?: readonly string[];
+  use?: never;
+  sh?: never;
+  steps?: never;
+  matrix?: never;
+}
+
+export type WorkspacePipelineStageInput =
+  | PipelineShellStageInput
+  | PipelineMatrixStageInput
+  | PipelineParallelStageInput;
+
+export interface PipelinePostInput {
+  success?: readonly PipelineStepLike[];
+  failure?: readonly PipelineStepLike[];
+  canceled?: readonly PipelineStepLike[];
+  always?: readonly PipelineStepLike[];
+}
+
+export interface WorkspacePipelineInput {
+  schemaVersion?: 1;
+  /** For every step of the run, app stages included. */
+  env?: Record<string, string>;
+  timeout?: PipelineDuration;
+  /** Before any app stage. */
+  before?: readonly WorkspacePipelineStageInput[];
+  /** After every app's last stage. */
+  after?: readonly WorkspacePipelineStageInput[];
+  post?: PipelinePostInput;
+}
+
+export type WorkspacePipelineConfig = WorkspacePipelineInput | ((ctx: PipelineContext) => WorkspacePipelineInput);
+
 export type AppConfigInput = Omit<DeepPartial<AppConfigResult>, "docker" | "web" | "bin" | "native"> & {
   docker?: DockerOption;
   web?: AkanWebOption;
   bin?: AkanBinConfig;
   native?: AkanNativeAppConfig;
   plugins?: AkanPlugin[];
+  pipeline?: AppPipelineConfig;
 };
 export type LibConfigInput = Omit<DeepPartial<LibConfigResult>, "bin"> & {
   bin?: AkanBinConfig;
@@ -446,11 +666,11 @@ export interface SubspaceDeclaration {
   repo: string;
   /** Apps this subspace serves. Libraries are never listed — they are derived from each app's closure. */
   apps: string[];
-  /** The subspace's own `AKAN_WORKSPACE_ID`, not this workspace's; only `akan subspace upload-env` reads it. */
+  /** The subspace's own `AKAN_WORKSPACE_ID`, not this workspace's: `akan subspace upload-env` and `--subspace` read it. */
   workspaceId?: string;
 }
 
-/** `akan.subspace.ts`: the repos this workspace mirrors to, on whichever branch the workspace is on. */
+/** The repos this workspace mirrors to, on whichever branch the workspace is on. */
 export interface SubspaceConfigInput {
   /** A feature branch is refused: pushing it would copy this workspace's branch namespace into every customer repo. */
   pushableBranches?: string[];
@@ -459,6 +679,19 @@ export interface SubspaceConfigInput {
   subspaces: SubspaceDeclaration[];
 }
 
+/** The workspace root's `akan.config.ts`. It never reaches a subspace, and app or lib settings are refused in it. */
+/** The cloud a workspace's CLI talks to when a command names no `--host`: a self-hosted akasys, say. */
+export interface WorkspaceCloudConfig {
+  /** The cloud's origin, e.g. `https://cloud.example.com`. Default: Akan Cloud. */
+  host?: string;
+}
+
+export interface WorkspaceConfig {
+  subspace?: SubspaceConfigInput;
+  pipeline?: WorkspacePipelineConfig;
+  cloud?: WorkspaceCloudConfig;
+}
+
 export type AppConfig = AppConfigInput | ((app: AppConfigContext) => AppConfigInput);
 export type LibConfig = LibConfigInput | ((lib: LibConfigContext) => LibConfigInput);
 export type AkanConfigFile = object;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akanjs",
-  "version": "3.0.2",
+  "version": "3.1.0-rc.0",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -233,7 +233,6 @@
   },
   "peerDependencies": {
     "@happy-dom/global-registrator": "^20.11.2",
-    "@libsql/client": "^0.17.3",
     "@playwright/test": "^1.60.0",
     "@react-spring/web": "^10.1.0",
     "@use-gesture/react": "^10.3.1",
@@ -258,9 +257,6 @@
     "@happy-dom/global-registrator": {
       "optional": true
     },
-    "@libsql/client": {
-      "optional": true
-    },
     "@playwright/test": {
       "optional": true
     },

package/server/akanApp.ts

@@ -346,6 +346,7 @@ export class AkanApp {
         ...this.#childEnv(idx, role),
         AKAN_CHILD_SOCKET: upstream.http.socketPath,
         AKAN_CHILD_WS_PORT: upstream.ws ? String(upstream.ws.port) : "",
+        ...(this.#printChildStderr || Logger.isNdjson ? {} : { AKAN_CHILD_STDERR_HIDDEN: "1" }),
       },
       ipc: (message) => this.#handleMessage(idx, message as AkanIpcMessage, proc),
       stdout: "pipe",
@@ -626,7 +627,7 @@ export class AkanApp {
   static readonly #immutableArtifacts = [
     { prefix: "/_akan/client/", root: "client", strip: "/_akan/client/".length, type: "application/javascript" },
     { prefix: "/_akan/styles/", root: "", strip: "/_akan/".length, type: "text/css; charset=utf-8" },
-    { prefix: "/_akan/fonts/", root: "", strip: "/_akan/".length, type: "font/woff2" },
+    { prefix: "/_akan/fonts/", root: "", strip: "/_akan/".length, type: "font/woff2", anyOrigin: true },
   ] as const;
 
   async #serveImmutableArtifact(req: Request, url: URL): Promise<Response | null> {
@@ -640,6 +641,7 @@ export class AkanApp {
     return this.#fileResponse(req, filePath, {
       contentType: file.type || artifact.type,
       cacheControl: "public, max-age=31536000, immutable",
+      anyOrigin: "anyOrigin" in artifact,
     });
   }
 
@@ -975,10 +977,11 @@ export class AkanApp {
   async #fileResponse(
     req: Request,
     filePath: string,
-    options: { contentType: string; cacheControl?: string },
+    options: { contentType: string; cacheControl?: string; anyOrigin?: boolean },
   ): Promise<Response> {
     const headers = new Headers({ "Content-Type": options.contentType });
     if (options.cacheControl) headers.set("Cache-Control", options.cacheControl);
+    if (options.anyOrigin) headers.set("Access-Control-Allow-Origin", "*");
     headers.set("X-Content-Type-Options", "nosniff");
     headers.set("Referrer-Policy", "strict-origin-when-cross-origin");
     return await encodedFileResponse(req, filePath, options.contentType, headers);

package/server/akanServer.ts

@@ -46,6 +46,7 @@ import { SignalResolver } from "./resolver";
 import { type ApiRouteInputs, ApiRouter } from "./routing/apiRouter";
 import type { AppWsData } from "./routing/appWsData";
 import { HostAllowlist } from "./routing/hostAllowlist";
+import { RoomReplay } from "./routing/roomReplay";
 import { createSoloAppRoutes } from "./routing/soloAppRoutes";
 import {
   getWebConfigFromEnv,
@@ -105,6 +106,16 @@ export interface McpServerOption {
   rateLimit?: McpRateLimitOption | false;
   /** Characters a page prompt may attach before its lists are cut; 60,000 by default. `AKAN_MCP_PROMPT_BUDGET`. */
   promptBudget?: number;
+  /**
+   * MCP Apps: a `.prompt()` page is a tool as well, whose result a host speaking the extension renders from the CSR
+   * shell; an endpoint kept off the shelf by `mcp: false` stays callable by that view. `true` by default. `AKAN_MCP_APPS`.
+   */
+  apps?: boolean;
+  /**
+   * Speak the modern `2026-07-28` revision (`server/discover`) beside the legacy ones. On unless MCP Apps renders views,
+   * since claude.ai renders a view only for a server it reached through `initialize`. `AKAN_MCP_MODERN`.
+   */
+  modern?: boolean;
 }
 
 interface AkanAppPrepared {
@@ -172,6 +183,7 @@ export class AkanServer {
   #lastMetrics: AkanMetricsReport = {};
   #stopping: Promise<void> | null = null;
   #parentGone: boolean = false;
+  #schedules = true;
   #orphanExiting = false;
   constructor(
     name = "AkanServer",
@@ -188,6 +200,8 @@ export class AkanServer {
     this.logger = new Logger(name);
     this.libs = libs;
     this.env = { ...env };
+    
+    if (AkanServer.#isEdge(this.env) && !AkanServer.#isEnvEnabled("AKAN_MCP", "AKAN_PUBLIC_MCP")) this.mcp = false;
     this.openapi = options?.openapi ?? this.openapi;
     
     EndpointRateLimit.reset();
@@ -467,15 +481,18 @@ export class AkanServer {
         return;
       }
       const publishData: WebsocketPublishData = { type: "pub", roomId, data };
-      server?.publish(roomId, JSON.stringify(publishData));
-      wsServer?.publish(roomId, JSON.stringify(publishData));
+      const subscribed = (server?.subscriberCount(roomId) ?? 0) + (wsServer?.subscriberCount(roomId) ?? 0) > 0;
+      const frame = roomReplay.frameOf(publishData, subscribed);
+      server?.publish(roomId, frame);
+      wsServer?.publish(roomId, frame);
     };
-    SignalResolver.setLocalPublish(localPublish, websocket, this.#di.live);
+    const roomReplay = new RoomReplay({ vouches: this.#solo });
+    SignalResolver.setLocalPublish(localPublish, websocket, this.#di.live, roomReplay);
     this.#localPublish = localPublish;
 
     this.status = "running";
     this.#metricsTimer ??= ProcessMetricsCollector.startReporting(() => this.#reportMetrics());
-    this.#di.registerSchedule(this.serverMode);
+    if (this.#schedules) this.#di.registerSchedule(this.serverMode);
     this.logger.verbose(`🚀 ${this.name} is running on ${unix ? `unix://${unix}` : `port ${port}`}`);
     const wsPort = this.#wsServer?.port;
     this.#sendReady({
@@ -488,12 +505,17 @@ export class AkanServer {
       healthPath: "/_akan/app/child-health",
       crossSite: CrossSiteGuard.option(),
     });
-    await this.#di.runSchedulerInit();
+    if (this.#schedules) await this.#di.runSchedulerInit();
     ShutdownManager.register(this.logger, () => this.stop());
     return this;
   }
 
-  async start({ listen, web }: { listen?: boolean; web?: AkanWebOption } = {}) {
+  /**
+   * `listen: false` serves no HTTP and still runs the internals, as a batch replica does; `schedules: false` runs
+   * none of them (init, interval, cron, queue workers), as a test or a script wants.
+   */
+  async start({ listen, web, schedules }: { listen?: boolean; web?: AkanWebOption; schedules?: boolean } = {}) {
+    this.#schedules = schedules ?? true;
     const isNoListenCommand = process.env.AKAN_COMMAND_TYPE === "script" || process.env.AKAN_COMMAND_TYPE === "console";
     const shouldListen = (listen ?? !isNoListenCommand) && this.serverMode !== "batch";
     
@@ -508,7 +530,7 @@ export class AkanServer {
       if (!isNoListenCommand) {
         Logger.role = this.serverMode;
         this.#metricsTimer ??= ProcessMetricsCollector.startReporting(() => this.#reportMetrics());
-        this.#di.registerSchedule(this.serverMode);
+        if (this.#schedules) this.#di.registerSchedule(this.serverMode);
         await this.#startLogTransport();
         this.#sendReady({
           type: "ready",
@@ -516,7 +538,7 @@ export class AkanServer {
           replicaIdx: Number(process.env.AKAN_REPLICA_IDX ?? 0),
           role: this.serverMode,
         });
-        await this.#di.runSchedulerInit();
+        if (this.#schedules) await this.#di.runSchedulerInit();
         ShutdownManager.register(this.logger, () => this.stop());
       }
       return this;
@@ -672,6 +694,8 @@ export class AkanServer {
             readOnly: this.mcpReadOnly,
             auth: this.mcpAuth,
             pagePrompts: webRouter?.pagePrompts(),
+            apps: this.mcpOption.apps !== false,
+            appShell: this.mcpOption.apps === false ? undefined : webRouter?.mcpAppShell(),
           })
         : null;
     const mcpRoutes: HttpRoutes = mcpRouter?.createRoutes() ?? {};
@@ -823,6 +847,10 @@ export class AkanServer {
     );
   }
 
+  static #isEdge(env: BackendEnv) {
+    return ((env as { operationMode?: string }).operationMode ?? process.env.AKAN_PUBLIC_OPERATION_MODE) === "edge";
+  }
+
   static #isEnvEnabled(...names: string[]) {
     return names.some((name) => process.env[name] === "true" || process.env[name] === "1");
   }
@@ -864,11 +892,19 @@ export class AkanServer {
       ...(Number.isInteger(promptBudget) && promptBudget > 0 ? { promptBudget } : {}),
       ...(process.env.AKAN_MCP_LANGUAGE ? { language: process.env.AKAN_MCP_LANGUAGE } : {}),
       ...(AkanServer.#isEnvOff("AKAN_MCP_LEGACY_TEXT") ? { legacyTextBlock: false } : {}),
+      ...(AkanServer.#isEnvOff("AKAN_MCP_APPS") ? { apps: false } : {}),
+      ...AkanServer.#mcpModernFromEnv(),
       ...AkanServer.#mcpOutputSchemaFromEnv(),
       ...AkanServer.#mcpRateLimitFromEnv(),
     };
   }
 
+  static #mcpModernFromEnv(): Pick<McpServerOption, "modern"> {
+    const raw = process.env.AKAN_MCP_MODERN;
+    if (raw === "true" || raw === "1") return { modern: true };
+    return AkanServer.#isEnvOff("AKAN_MCP_MODERN") ? { modern: false } : {};
+  }
+
   static #mcpRateLimitFromEnv(): Pick<McpServerOption, "rateLimit"> {
     const raw = process.env.AKAN_MCP_RATE_LIMIT?.trim().toLowerCase();
     if (raw === "off" || raw === "false" || raw === "0") return { rateLimit: false };

package/server/artifact/builderRpc.ts

@@ -104,9 +104,14 @@ export class BuilderRpc {
     };
   }
 
-  /** Arms dev CSR, which the builder skips by default (a full browser build per save), and keeps it in sync after. */
-  async buildCsr(reason: string): Promise<void> {
-    await this.#request<void>(`build-csr (${reason})`, (id) => this.#send({ type: "build-csr", id, reason }));
+  /**
+   * Arms dev CSR, which the builder skips by default (a full browser build per save), and keeps it in sync after.
+   * `shell` arms nothing: it asks for an MCP Apps view's single-file build, rebuilt only once a save moved past it.
+   */
+  async buildCsr(reason: string, { shell = false }: { shell?: boolean } = {}): Promise<void> {
+    await this.#request<void>(`build-csr (${reason})`, (id) =>
+      this.#send({ type: "build-csr", id, reason, ...(shell ? { shell } : {}) }),
+    );
   }
 
   static #timeoutMs(): number {

package/server/artifact/ipcTypes.ts

@@ -70,8 +70,11 @@ export type BuilderRes =
   | { type: "build-route-res"; id: number; ok: true; data: BuildRouteResultPayload }
   | { type: "build-route-res"; id: number; ok: false; error: string };
 
-/** Sent by the first `/__csr` or `?csr=true` request (a device WebView in mobile dev) to arm the lazy dev CSR build. */
-export type BuilderCsrReq = { type: "build-csr"; id: number; reason: string };
+/**
+ * Sent by the first `/__csr` or `?csr=true` request (a device WebView in mobile dev) to arm the lazy dev CSR build.
+ * `shell` asks once for the single-file build an MCP Apps view boots from, whatever the dev CSR mode, and arms nothing.
+ */
+export type BuilderCsrReq = { type: "build-csr"; id: number; reason: string; shell?: boolean };
 
 export type BuilderCsrRes =
   | { type: "build-csr-res"; id: number; ok: true }