@akanjs/devkit 3.1.1-rc.18 → 3.1.1-rc.19

package/akanContext.ts

@@ -1,6 +1,6 @@
 import { readdir } from "node:fs/promises";
 import path from "node:path";
-import { capitalize, isRecord } from "akanjs/common";
+import { capitalize, isRecord, parseRouteModuleKey } from "akanjs/common";
 import { extractBlockVersion, readDevkitVersion } from "./agentsIndex";
 import { AppExecutor, LibExecutor, type SysExecutor, type WorkspaceExecutor } from "./executors";
 import { FileSys } from "./fileSys";
@@ -48,12 +48,25 @@ export interface AkanModuleContext {
   files: string[];
 }
 
+export interface AkanRouteContext {
+  /** The URL pattern without the `/:lang` segment every route starts with. */
+  path: string;
+  file: string;
+  search: string[];
+  /** The page or a layout above it calls `.guard()`. */
+  guarded: boolean;
+  devOnly: boolean;
+}
+
 export interface AkanSysContext {
   type: "app" | "lib";
   name: string;
   path: string;
   hasConfig: boolean;
   modules: AkanModuleContext[];
+  /** Listed for the app `--app` names only; reading them parses every route file. */
+  routes?: AkanRouteContext[];
+  routeError?: string;
 }
 
 export interface AkanPackageContext {
@@ -557,6 +570,34 @@ const getSysModules = async (
   return modules.sort((a, b) => `${a.sysName}:${a.path}`.localeCompare(`${b.sysName}:${b.path}`));
 };
 
+const getAppRoutes = async (app: AppExecutor, workspaceRoot: string): Promise<AkanRouteContext[]> => {
+  const sources = await app.getRouteSources();
+  const guardedLayouts = new Set<string>();
+  const pages: { source: (typeof sources)[number]; parsed: ReturnType<typeof parseRouteModuleKey> }[] = [];
+  for (const source of sources) {
+    const parsed = parseRouteModuleKey(source.key);
+    if (parsed.kind === "layout" && source.info.chain?.guarded) guardedLayouts.add(parsed.routeSegments.join("/"));
+    else if (parsed.kind === "page") pages.push({ source, parsed });
+  }
+  return pages
+    .map(({ source, parsed }) => {
+      const segments = parsed.routeSegments;
+      //? The layouts that wrap a page, as the route seed index walks them: an `_index` sits inside its own folder.
+      const reach = parsed.leaf === "_index" ? segments.length : segments.length - 1;
+      const underGuard = Array.from({ length: reach + 1 }, (_, idx) => segments.slice(0, idx).join("/")).some(
+        (prefix) => guardedLayouts.has(prefix),
+      );
+      return {
+        path: parsed.pattern.replace(/^\/:lang/, "") || "/",
+        file: path.relative(workspaceRoot, source.absPath),
+        search: source.info.chain?.search ?? [],
+        guarded: !!source.info.chain?.guarded || underGuard,
+        devOnly: source.info.devOnly,
+      };
+    })
+    .sort((a, b) => a.path.localeCompare(b.path));
+};
+
 const getSysContext = async (
   workspace: WorkspaceExecutor,
   type: "app" | "lib",
@@ -564,7 +605,7 @@ const getSysContext = async (
   options: AkanContextOptions,
 ): Promise<AkanSysContext> => {
   const sys = type === "app" ? AppExecutor.from(workspace, name) : LibExecutor.from(workspace, name);
-  return {
+  const context: AkanSysContext = {
     type,
     name,
     path: `${type}s/${name}`,
@@ -574,6 +615,12 @@ const getSysContext = async (
       module: options.module,
     }),
   };
+  if (sys instanceof AppExecutor && options.app === name)
+    await getAppRoutes(sys, workspace.workspaceRoot).then(
+      (routes) => (context.routes = routes),
+      (error: unknown) => (context.routeError = error instanceof Error ? error.message : String(error)),
+    );
+  return context;
 };
 
 export class AkanContextAnalyzer {
@@ -986,6 +1033,12 @@ export class AkanContextAnalyzer {
       ...context.pkgs.map((pkg) => `- ${pkg.name}${pkg.version ? ` (${pkg.version})` : ""}`),
     );
 
+    for (const app of context.apps) {
+      if (app.routeError) lines.push("", `## Routes: ${app.name}`, `- Not read: ${app.routeError}`);
+      else if (app.routes)
+        lines.push("", `## Routes: ${app.name}`, ...AkanContextAnalyzer.#routeLines(app.name, app.routes));
+    }
+
     const modules = AkanContextAnalyzer.findModules(context, moduleName);
     lines.push("", "## Modules");
     for (const module of modules) {
@@ -1000,4 +1053,34 @@ export class AkanContextAnalyzer {
     lines.push("", "## Validation", ...context.validationCommands.map((command) => `- \`${command}\``));
     return `${lines.join("\n")}\n`;
   }
+
+  static readonly routeListLimit = 60;
+
+  //? Past the limit the biggest top folders fold into one line each: a docs section alone would fill the context.
+  static #routeLines(appName: string, routes: AkanRouteContext[]) {
+    const folderOf = (route: AkanRouteContext) => route.file.split("/").slice(0, 4).join("/");
+    const groups = Map.groupBy(routes, folderOf);
+    const folded = new Set<string>();
+    let listed = routes.length;
+    for (const [folder, members] of [...groups].sort((a, b) => b[1].length - a[1].length)) {
+      if (listed <= AkanContextAnalyzer.routeListLimit) break;
+      folded.add(folder);
+      listed -= members.length;
+    }
+    const lines = [`Paths omit the \`/:lang\` prefix; \`akan preview ${appName} <path>\` opens one.`];
+    for (const route of routes) {
+      if (folded.has(folderOf(route))) continue;
+      const search = route.search.length ? ` ?${route.search.join("&")}` : "";
+      const marks = `${route.guarded ? " (guarded)" : ""}${route.devOnly ? " (dev only)" : ""}`;
+      lines.push(`- ${route.path}${search}${marks} — ${route.file}`);
+    }
+    for (const folder of folded) {
+      const members = groups.get(folder) ?? [];
+      const examples = members.slice(0, 3).map((route) => route.path);
+      lines.push(
+        `- ${folder}/: ${members.length} routes folded (${examples.join(", ")}, …); \`--format json\` lists every route`,
+      );
+    }
+    return lines;
+  }
 }

package/codeAgent/feedback/PreviewFeedback.ts

@@ -1,5 +1,5 @@
+import { PreviewView } from "../../preview/PreviewView";
 import { AkanEditScope } from "../tools/AkanEditScope";
-import { PreviewView } from "./PreviewView";
 import type { TurnFeedbackFinding, TurnFeedbackSource } from "./TurnFeedback";
 
 export interface PreviewFeedbackOptions {
@@ -35,7 +35,7 @@ export class PreviewFeedback implements TurnFeedbackSource {
     for (const route of this.#options.routes ?? ["/en/"]) {
       const url = new URL(route, this.#options.previewUrl).toString();
       const probe = await PreviewView.probe(url, { screenshot: !!this.#options.canSeeImages });
-      const problems = [...probe.pageErrors, ...probe.consoleErrors, ...probe.domFindings];
+      const problems = [...probe.pageErrors, ...probe.consoleErrors, ...probe.consoleWarnings, ...probe.domFindings];
       if (!problems.length) continue;
       findings.push(`**${url}**\n${problems.map((line) => `- ${line}`).join("\n")}`);
       if (probe.screenshot) images.push({ data: probe.screenshot, mimeType: "image/png" });

package/codeAgent/index.ts

@@ -1,5 +1,7 @@
 // Importing this barrel loads the engine (~122MiB resident); a host needing cheap pieces imports the owning module.
 // agent/consoleToStderr is deliberately absent: it takes over globalThis.console, so an RPC entry imports it first.
+
+export * from "../preview";
 export * from "./agent/AkanCodeCompaction";
 export * from "./agent/AkanCodeServices";
 export * from "./agent/akanCodeModel";
@@ -17,9 +19,7 @@ export * from "./agent/CodeSessionFork";
 export * from "./agent/CodeSessionIndex";
 export * from "./agent/SubagentPool";
 export * from "./feedback/DevLogFeedback";
-export * from "./feedback/PreviewChrome";
 export * from "./feedback/PreviewFeedback";
-export * from "./feedback/PreviewView";
 export * from "./feedback/TurnFeedback";
 export * from "./feedback/VerifyFeedback";
 export * from "./tools/AkanCli";

package/codeAgent/skills/akan-debug/SKILL.md

@@ -1,10 +1,42 @@
 ---
 name: akan-debug
-description: "Debug a running Akan app: where the dev-server log is, how to read it, and how to tell a runtime failure from a build one."
+description: "Check and debug a running Akan app: akan preview for what a page shows and throws, where the dev-server log is, how to read it, and how to tell a runtime failure from a build one."
 ---
 
 # Akan debug
 
+## See the change run: `akan preview`
+
+`akan preview <app> [paths]` opens pages of the app's dev server in a headless browser and prints, per page,
+the HTTP status, the title, a slice of the visible text, the uncaught errors and rejections the page reported,
+the server errors logged meanwhile, console errors and warnings, and layout smells. It exits 1 when a page failed.
+
+- It uses the dev server that answers for this app and checkout. With none, it starts one for the run and
+  stops it after; `--keep` leaves it up for the next preview. It never starts a second server beside a
+  running one.
+- Paths are comma-separated and get the default locale when they lack one: `akan preview <app> /board,/board/new`.
+  `--changed` adds the pages your uncommitted page and layout edits reach. A dynamic route needs a concrete
+  path (`/memo/1`); `akan context --app <app>` lists every route with its params and search names.
+- The viewport is a 390x844 phone; `--desktop` is 1280x800. `--csr` loads each page in the CSR boot the native
+  shells load. `--screenshot` saves a PNG per page under `local/apps/<app>/runtime/preview/`, for a model
+  that reads images. `--format json` gives the same report as data.
+
+### Which platforms that covers
+
+- Every change: the server-rendered web page and, with `--csr`, the bundle the iOS, Android and desktop
+  shells run.
+- A change to `native/`, `plugin/`, an `isNativeApp()` branch, `native` in `akan.config.ts` or an
+  `@akanjs/native` plugin also needs that shell: `akan start-ios`, `start-android` or `start-desktop` on top of
+  the running dev server. Errors thrown in the shell reach the same dev-server log as `ClientReport` lines
+  tagged with the platform and target. Capture the shell with `xcrun simctl io booted screenshot <file>.png` or
+  `adb exec-out screencap -p > <file>.png`. When you cannot run the shell, say so: "not checked on iOS".
+- Real devices, memory, OTA updates and store builds are for whoever releases.
+
+### What goes in your answer
+
+The verdict lines of the pages you changed (`ok    /en/board  200  "Board"  1.4s`) and every finding you left
+unfixed. "Not opened in a browser" is not an answer once `akan preview` can run.
+
 ## The log is a file, and that file is the whole session
 
 A supervised `akan start` writes **`local/apps/<app>/runtime/dev.log`** — no ANSI, nothing truncated, every
@@ -17,8 +49,10 @@ what survives in the scrollback is bordered and truncated to the pane.
 - `tail -n 200 local/apps/<app>/runtime/dev.log` after an edit, to see what the reload produced.
 - `akan logs <app>` tails a running server with `--level --grep --endpoint --trace --child --role --origin
   --since` and `--json`.
-- The dev server's URL is printed in that log, and the port is allocated rather than fixed — the log is the
-  only source for it.
+- The dev server's URL is printed in that log. A server `akan preview` started logs to
+  `local/apps/<app>/runtime/preview/server.log` instead.
+- An uncaught error or unhandled rejection in a page reaches the server log as a `ClientReport` error line,
+  naming the page, the client (`ssr` or `csr`) and the native target.
 
 ## Which loop you are in
 

package/codeAgent/tools/AkanCodePlugins.ts

@@ -1,12 +1,12 @@
 import type { InlineExtension } from "@earendil-works/pi-coding-agent";
 import type { CodeAgentMcpStatus, CodeAgentProfile, CodeAgentQuestion, CodeAgentSubagent } from "akanjs/common";
 import type { Workspace } from "../../commandDecorators";
+import { PreviewView } from "../../preview/PreviewView";
 import type { CodeAgentModelRef } from "../agent/akanCodeModel";
 import type { CodeMailbox } from "../agent/CodeMailbox";
 import { SubagentPool, type SubagentSpend } from "../agent/SubagentPool";
 import { DevLogFeedback } from "../feedback/DevLogFeedback";
 import { PreviewFeedback } from "../feedback/PreviewFeedback";
-import { PreviewView } from "../feedback/PreviewView";
 import { TurnFeedback, type TurnFeedbackSource } from "../feedback/TurnFeedback";
 import { VerifyFeedback } from "../feedback/VerifyFeedback";
 import { AkanToolPack } from "./AkanToolPack";

package/codeAgent/tools/akanCodePlugins.test.ts

@@ -5,7 +5,6 @@ import { makeCliTempWorkspace, tempRoots, writeText } from "../../testHelpers";
 import { CodeAgent, type CodeAgentOptions } from "../agent/CodeAgent";
 import { SubagentPool } from "../agent/SubagentPool";
 import { DevLogFeedback } from "../feedback/DevLogFeedback";
-import { PreviewView } from "../feedback/PreviewView";
 import { TurnFeedback, type TurnFeedbackSource } from "../feedback/TurnFeedback";
 import { AkanCodePlugins } from "./AkanCodePlugins";
 import { AkanEditScope } from "./AkanEditScope";
@@ -225,33 +224,6 @@ describe("AkanEnvKeys", () => {
   });
 });
 
-describe("PreviewView", () => {
-  test("reports whether this Bun build can drive a headless page at all", () => {
-    expect(typeof PreviewView.available).toBe("boolean");
-  });
-
-  test.skipIf(!PreviewView.available)(
-    "finds an empty body and a console error on a real page",
-    async () => {
-      const server = Bun.serve({
-        port: 0,
-        fetch: () =>
-          new Response('<!doctype html><html><body></body><script>console.error("boom")</script></html>', {
-            headers: { "content-type": "text/html" },
-          }),
-      });
-      try {
-        const probe = await PreviewView.probe(`http://localhost:${server.port}/`);
-        expect(probe.pageErrors.join(" ")).toContain("rendered empty");
-        expect(probe.consoleErrors.join(" ")).toContain("boom");
-      } finally {
-        server.stop(true);
-      }
-    },
-    30_000,
-  );
-});
-
 describe("SubagentPool", () => {
   const workspace = { workspaceRoot: "/tmp/akan" } as never;
 

package/executors.ts

@@ -49,6 +49,7 @@ import { JsonFormatter } from "./jsonFormatter";
 import { Linter } from "./linter";
 import { ManifestDependencies } from "./manifestDependencies";
 import { resolveRepoName } from "./repoIdentity";
+import type { RouteSourceInfo } from "./routeSourceValidator";
 import { AppInfo, isAkanFrameworkDependency, LibInfo, PkgInfo, WorkspaceInfo } from "./scanInfo";
 import { Spinner } from "./spinner";
 // Type-only: `getTypeChecker` loads it on demand to keep `typescript` out of the resident module graph.
@@ -66,6 +67,12 @@ export interface PageRoot {
   keyPrefix: string;
 }
 
+export interface AppRouteSource {
+  key: string;
+  absPath: string;
+  info: RouteSourceInfo;
+}
+
 export interface WrittenFileContent extends FileContent {
   written: boolean;
 }
@@ -1278,6 +1285,7 @@ export class AppExecutor extends SysExecutor {
   }
 
   #pageKeys: string[] | null = null;
+  #routeSources: AppRouteSource[] = [];
   #excludeDevOnlyPages = false;
   async getPageKeys({ refresh }: { refresh?: boolean } = {}): Promise<string[]> {
     if (this.#pageKeys && !refresh) return this.#pageKeys;
@@ -1288,6 +1296,7 @@ export class AppExecutor extends SysExecutor {
     const devOnlyKeys = new Set<string>();
     const devOnlyDirs: string[] = [];
     const pageRoots = await this.getPageRoots();
+    const routeSources: AppRouteSource[] = [];
     const libKeyPrefixes = pageRoots.map((root) => root.keyPrefix).filter(Boolean);
     for (const root of pageRoots) {
       if (!(await FileSys.dirExists(root.dir))) continue;
@@ -1333,6 +1342,7 @@ export class AppExecutor extends SysExecutor {
             rootLayout: isRootLayout,
             pattern: parsed.pattern,
           });
+          routeSources.push({ key, absPath, info });
           if (info.devOnly) {
             devOnlyKeys.add(key);
             //* A dev-only layout takes its whole subtree, or its pages would ship without their chrome.
@@ -1343,9 +1353,15 @@ export class AppExecutor extends SysExecutor {
       }
     }
     pageKeys.sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+    this.#routeSources = routeSources.sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
     this.#pageKeys = this.#excludeDevOnlyPages ? this.#dropDevOnlyPages(pageKeys, devOnlyKeys, devOnlyDirs) : pageKeys;
     return this.#pageKeys;
   }
+  /** Each page and layout file `getPageKeys` read, with what its chain declares; overrides files are not listed. */
+  async getRouteSources({ refresh }: { refresh?: boolean } = {}): Promise<AppRouteSource[]> {
+    await this.getPageKeys({ refresh });
+    return this.#routeSources;
+  }
   #dropDevOnlyPages(pageKeys: string[], devOnlyKeys: Set<string>, devOnlyDirs: string[]): string[] {
     if (!devOnlyKeys.size) return pageKeys;
     const isDevOnly = (key: string) => devOnlyKeys.has(key) || devOnlyDirs.some((dir) => key.startsWith(dir));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akanjs/devkit",
-  "version": "3.1.1-rc.18",
+  "version": "3.1.1-rc.19",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -34,6 +34,7 @@
     "./incrementalBuilder": "./incrementalBuilder/index.ts",
     "./mobile": "./mobile/index.ts",
     "./pipeline": "./pipeline/index.ts",
+    "./preview": "./preview/index.ts",
     "./transforms": "./transforms/index.ts",
     "./workflow": "./workflow/index.ts",
     "./*.ts": "./*.ts",
@@ -48,7 +49,7 @@
     "@earendil-works/pi-tui": "1.3.0",
     "@inquirer/prompts": "^8.7.3",
     "@tailwindcss/node": "^4.3.3",
-    "akanjs": "3.1.1-rc.18",
+    "akanjs": "3.1.1-rc.19",
     "chalk": "^6.0.1",
     "commander": "^15.0.0",
     "dayjs": "^1.11.23",

package/{codeAgent/feedback → preview}/PreviewChrome.ts

@@ -2,6 +2,8 @@ import { existsSync } from "node:fs";
 import { homedir } from "node:os";
 import path from "node:path";
 
+export type PreviewEngine = "webkit" | "chrome";
+
 // Bun.WebView's `webkit` backend is the macOS system framework and throws on every other platform.
 export class PreviewChrome {
   /** Read by `Bun.WebView` itself; listed so the availability check agrees with what the launcher will do. */
@@ -30,7 +32,7 @@ export class PreviewChrome {
     "Microsoft Edge.app/Contents/MacOS/Microsoft Edge",
   ];
 
-  static get backend(): "webkit" | "chrome" {
+  static get backend(): PreviewEngine {
     const declared = process.env[PreviewChrome.backendEnvKey];
     if (declared === "webkit" || declared === "chrome") return declared;
     return process.platform === "darwin" ? "webkit" : "chrome";
@@ -53,11 +55,15 @@ export class PreviewChrome {
   }
 
   static get available() {
-    return PreviewChrome.backend === "webkit" ? process.platform === "darwin" : !!PreviewChrome.executable();
+    return PreviewChrome.isAvailable();
+  }
+
+  static isAvailable(engine: PreviewEngine = PreviewChrome.backend) {
+    return engine === "webkit" ? process.platform === "darwin" : !!PreviewChrome.executable();
   }
 
-  static backendOption() {
-    if (PreviewChrome.backend === "webkit") return "webkit";
+  static backendOption(engine: PreviewEngine = PreviewChrome.backend) {
+    if (engine === "webkit") return "webkit";
     // Docker's default 64MB /dev/shm is below what Chromium's renderer allocates; the crash looks like a hung load.
     const argv = ["--disable-dev-shm-usage"];
     // Chromium refuses uid 0 with its sandbox on, and uid 0 is the ordinary uid in a container.
@@ -70,9 +76,9 @@ export class PreviewChrome {
     "apt-get update && apt-get install -y --no-install-recommends chromium fonts-liberation fonts-noto-color-emoji fonts-noto-cjk && rm -rf /var/lib/apt/lists/*",
   ];
 
-  static unavailableReason() {
-    if (PreviewChrome.available) return undefined;
-    if (PreviewChrome.backend === "webkit")
+  static unavailableReason(engine: PreviewEngine = PreviewChrome.backend) {
+    if (PreviewChrome.isAvailable(engine)) return undefined;
+    if (engine === "webkit")
       return `The webkit WebView backend exists only on macOS. Set ${PreviewChrome.backendEnvKey}=chrome and install a browser.`;
     return [
       "The page preview needs a browser and this machine has none on PATH.",

package/preview/PreviewView.ts

@@ -0,0 +1,219 @@
+import { PreviewChrome, type PreviewEngine } from "./PreviewChrome";
+
+export interface PreviewProbeOptions {
+  screenshot?: boolean;
+  width?: number;
+  height?: number;
+  engine?: PreviewEngine;
+  /** Bounds the whole probe: a dev server that is recovering takes the connection and never answers. */
+  timeoutMs?: number;
+  /** Waited after the load, so the errors effects throw land before the page is read. */
+  settleMs?: number;
+}
+
+export interface PreviewProbeResult {
+  url: string;
+  finalUrl: string;
+  status: number | null;
+  title: string;
+  text: string;
+  consoleErrors: string[];
+  consoleWarnings: string[];
+  pageErrors: string[];
+  /** Cheap structural smells that read as "the page is broken" without anyone looking at it. */
+  domFindings: string[];
+  screenshot?: string;
+}
+
+interface WebViewLike {
+  navigate(url: string): Promise<void>;
+  evaluate(expression: string): Promise<unknown>;
+  screenshot(options: { encoding: "base64" }): Promise<string>;
+  close(): void | Promise<void>;
+}
+
+interface PageRead {
+  href: string;
+  title: string;
+  text: string;
+  status: number | null;
+  empty: boolean;
+  pageErrors: string[];
+  domFindings: string[];
+}
+
+// Bun.WebView rather than a downloaded browser: on macOS its webkit backend needs no Chromium at all.
+// It is experimental, so its whole surface stays behind this adapter; a Bun minor that changes it breaks one file.
+export class PreviewView {
+  static get available() {
+    return PreviewView.isAvailable();
+  }
+
+  static isAvailable(engine: PreviewEngine = PreviewChrome.backend) {
+    return typeof (Bun as unknown as { WebView?: unknown }).WebView === "function" && PreviewChrome.isAvailable(engine);
+  }
+
+  static unavailableReason(engine: PreviewEngine = PreviewChrome.backend) {
+    if (typeof (Bun as unknown as { WebView?: unknown }).WebView !== "function")
+      return "This Bun build has no WebView, so the page preview is off.";
+    return PreviewChrome.unavailableReason(engine);
+  }
+
+  static async probe(
+    url: string,
+    {
+      screenshot = false,
+      width = 1280,
+      height = 800,
+      engine = PreviewChrome.backend,
+      timeoutMs = 30_000,
+      settleMs = 0,
+    }: PreviewProbeOptions = {},
+  ): Promise<PreviewProbeResult> {
+    const logs: string[] = [];
+    const deadline = Date.now() + timeoutMs;
+    const within = <T>(work: Promise<T>, what: string) => PreviewView.#within(work, deadline, `${what} ${url}`);
+    const view = PreviewView.#open({ width, height, engine, onConsole: (line) => logs.push(line) });
+    try {
+      let page = await PreviewView.#load(view, url, settleMs, within);
+      //? Right after a save the first load can render nothing (`[rscClient] module not loaded`); the next one has it.
+      if (page.empty) {
+        logs.length = 0;
+        page = await PreviewView.#load(view, url, settleMs, within);
+      }
+      const result: PreviewProbeResult = {
+        url,
+        finalUrl: page.href,
+        status: page.status ?? (await PreviewView.#statusOf(page.href, deadline)),
+        title: page.title,
+        text: page.text,
+        consoleErrors: logs.filter((line) => line.startsWith("error")),
+        consoleWarnings: logs.filter((line) => line.startsWith("warn")),
+        pageErrors: page.pageErrors,
+        domFindings: page.domFindings,
+      };
+      if (screenshot) result.screenshot = await within(view.screenshot({ encoding: "base64" }), "screenshotting");
+      return result;
+    } finally {
+      await view.close();
+    }
+  }
+
+  static async #load(
+    view: WebViewLike,
+    url: string,
+    settleMs: number,
+    within: <T>(work: Promise<T>, what: string) => Promise<T>,
+  ): Promise<PageRead> {
+    await within(view.navigate(url), "loading");
+    if (settleMs > 0) await Bun.sleep(settleMs);
+    const read = (await within(view.evaluate(readPageExpression), "reading")) as Partial<PageRead> | null;
+    return {
+      href: typeof read?.href === "string" ? read.href : url,
+      title: typeof read?.title === "string" ? read.title : "",
+      text: typeof read?.text === "string" ? read.text : "",
+      status: typeof read?.status === "number" && read.status > 0 ? read.status : null,
+      empty: read?.empty === true,
+      pageErrors: PreviewView.#strings(read?.pageErrors),
+      domFindings: PreviewView.#strings(read?.domFindings),
+    };
+  }
+
+  //? webkit has no Navigation Timing `responseStatus`, so the status comes from asking the server again, unredirected.
+  static async #statusOf(href: string, deadline: number) {
+    const left = Math.max(1, deadline - Date.now());
+    const response = await fetch(href, { redirect: "manual", signal: AbortSignal.timeout(left) }).catch(() => null);
+    return response?.status ?? null;
+  }
+
+  static async #within<T>(work: Promise<T>, deadline: number, what: string): Promise<T> {
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const expired = new Promise<never>((_, reject) => {
+      timer = setTimeout(
+        () => reject(new Error(`Timed out ${what}; the dev server may be rebuilding or stuck.`)),
+        Math.max(0, deadline - Date.now()),
+      );
+    });
+    try {
+      return await Promise.race([work, expired]);
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  static #open({
+    width,
+    height,
+    engine,
+    onConsole,
+  }: {
+    width: number;
+    height: number;
+    engine: PreviewEngine;
+    onConsole: (line: string) => void;
+  }) {
+    const Ctor = (Bun as unknown as { WebView: new (options: unknown) => WebViewLike }).WebView;
+    return new Ctor({
+      width,
+      height,
+      dataStore: "ephemeral",
+      backend: PreviewChrome.backendOption(engine),
+      // The console option is a callback taking `(type, ...args)`, not an object of console methods.
+      console: (type: string, ...args: unknown[]) => onConsole(`${type} ${PreviewView.formatConsole(args)}`),
+    });
+  }
+
+  /** Substitutes `%s` as the console does, since React passes a warning's detail as arguments, and cuts it short. */
+  static formatConsole(args: unknown[]) {
+    const [first, ...rest] = args;
+    const head =
+      typeof first === "string"
+        ? first.replace(/%[sdifoOc]/g, (token) => {
+            if (!rest.length) return token;
+            const value = rest.shift();
+            return token === "%c" ? "" : String(value);
+          })
+        : String(first);
+    return [head, ...rest.map(String)]
+      .join(" ")
+      .replace(/\n(\s*\n)+/g, "\n")
+      .slice(0, 1_500);
+  }
+
+  static #strings(value: unknown) {
+    return Array.isArray(value) ? value.filter((entry): entry is string => typeof entry === "string") : [];
+  }
+}
+
+// evaluate() takes one expression (a statement list is a SyntaxError), hence the IIFE; one call in flight per view.
+// `view.title` is only refreshed by a navigation, so the title is read from the document.
+const readPageExpression = `(() => {
+  const pageErrors = [];
+  const domFindings = [];
+  const body = document.body;
+  const rendered = body ? Array.from(body.children).filter((el) => !["SCRIPT", "STYLE", "TEMPLATE", "LINK", "NOSCRIPT"].includes(el.tagName) && !el.classList.contains("__akan_hmr_overlay")) : [];
+  const empty = !rendered.length && !(body && body.innerText && body.innerText.trim());
+  if (empty) pageErrors.push("The page body rendered empty.");
+  if (self.__AKAN_HMR_SYSTEM_PAGE__) pageErrors.push("The server could not render this page and answered with its error page: " + (body ? body.innerText.trim().replace(/\\s+/g, " ").slice(0, 400) : ""));
+  const overlay = document.querySelector('.__akan_hmr_overlay[data-status="error"]');
+  if (overlay) pageErrors.push("The dev build failed: " + overlay.textContent.trim().slice(0, 400));
+  const all = Array.from(document.querySelectorAll("body *"));
+  const viewportWidth = document.documentElement.clientWidth;
+  const pageWidth = document.documentElement.scrollWidth;
+  if (pageWidth > viewportWidth + 8) {
+    const wide = all.find((el) => el.getBoundingClientRect().right > viewportWidth + 8);
+    domFindings.push("The page is " + pageWidth + "px wide in a " + viewportWidth + "px viewport" + (wide ? ", first wider element: " + (wide.tagName.toLowerCase() + "." + (typeof wide.className === "string" ? wide.className : "")).slice(0, 120) : "") + ".");
+  }
+  const invisibleText = all.filter((el) => {
+    if (!el.textContent || !el.textContent.trim()) return false;
+    const style = getComputedStyle(el);
+    return style.color === style.backgroundColor && style.backgroundColor !== "rgba(0, 0, 0, 0)";
+  });
+  if (invisibleText.length) domFindings.push(invisibleText.length + " element(s) render text in the same colour as their background.");
+  const unresolved = all.filter((el) => /(^|\\s)(bg|text|border)-(base-100|base-content|primary-content|error)(\\s|$)/.test(typeof el.className === "string" ? el.className : ""));
+  if (unresolved.length) domFindings.push(unresolved.length + " element(s) use a dropped daisyUI colour slot that renders no CSS.");
+  const navigation = performance.getEntriesByType("navigation")[0];
+  const status = navigation && typeof navigation.responseStatus === "number" ? navigation.responseStatus : null;
+  const text = body ? body.innerText.trim().replace(/\\s+/g, " ").slice(0, 600) : "";
+  return { href: location.href, title: document.title, text, status, empty, pageErrors, domFindings };
+})()`;

package/preview/index.ts

@@ -0,0 +1,2 @@
+export * from "./PreviewChrome";
+export * from "./PreviewView";

package/preview/previewView.test.ts

@@ -0,0 +1,76 @@
+import { describe, expect, test } from "bun:test";
+import { PreviewView } from "./PreviewView";
+
+const serve = (html: string, status = 200) =>
+  Bun.serve({ port: 0, fetch: () => new Response(html, { status, headers: { "content-type": "text/html" } }) });
+
+describe("PreviewView", () => {
+  test("reports whether this Bun build can drive a headless page at all", () => {
+    expect(typeof PreviewView.available).toBe("boolean");
+  });
+
+  test("formats a console call the way the console prints it", () => {
+    expect(PreviewView.formatConsole(["%cstyled%c %s of %d", "color:red", "", "two", 3, "extra"])).toBe(
+      "styled two of 3 extra",
+    );
+    expect(PreviewView.formatConsole(["a\n\n\n  \nb"])).toBe("a\nb");
+    expect(PreviewView.formatConsole(["x".repeat(2_000)])).toHaveLength(1_500);
+  });
+
+  test.skipIf(!PreviewView.available)(
+    "finds an empty body and a console error on a real page",
+    async () => {
+      const server = serve('<!doctype html><html><body></body><script>console.error("boom")</script></html>');
+      try {
+        const probe = await PreviewView.probe(`http://localhost:${server.port}/`);
+        expect(probe.pageErrors.join(" ")).toContain("rendered empty");
+        expect(probe.consoleErrors.join(" ")).toContain("boom");
+      } finally {
+        server.stop(true);
+      }
+    },
+    30_000,
+  );
+
+  test.skipIf(!PreviewView.available)(
+    "reads the status, the live title, a failed dev build and a page wider than the viewport",
+    async () => {
+      const server = serve(
+        [
+          "<!doctype html><html><head><title>Before</title></head><body>",
+          '<div style="width:900px">wide</div>',
+          '<div class="__akan_hmr_overlay" data-status="error">Build failed: page.tsx</div>',
+          '<script>document.title = "After";</script>',
+          "</body></html>",
+        ].join(""),
+        404,
+      );
+      try {
+        const probe = await PreviewView.probe(`http://localhost:${server.port}/missing`, { width: 390, height: 844 });
+        expect(probe.status).toBe(404);
+        expect(probe.title).toBe("After");
+        expect(probe.text).toBe("wide Build failed: page.tsx");
+        expect(probe.pageErrors).toEqual(["The dev build failed: Build failed: page.tsx"]);
+        expect(probe.domFindings.join(" ")).toContain("first wider element: div");
+      } finally {
+        server.stop(true);
+      }
+    },
+    30_000,
+  );
+
+  test.skipIf(!PreviewView.available)(
+    "gives up on a server that takes the connection and never answers",
+    async () => {
+      const server = Bun.serve({ port: 0, fetch: () => new Promise<Response>(() => undefined) });
+      try {
+        await expect(PreviewView.probe(`http://localhost:${server.port}/`, { timeoutMs: 1_500 })).rejects.toThrow(
+          "Timed out loading",
+        );
+      } finally {
+        server.stop(true);
+      }
+    },
+    30_000,
+  );
+});

package/routeSourceValidator.test.ts

@@ -43,12 +43,14 @@ describe("RouteSourceValidator route chains", () => {
   const chain = (source: string, kind: "page" | "layout", pattern: string) =>
     RouteSourceValidator.validateRouteSourceExports(source, `page/${kind}.tsx`, kind, { pattern });
 
-  test("reads params, prompt, apps and devOnly off a page() chain without evaluating it", () => {
+  test("reads params, search names, prompt, apps, guard and devOnly off a page() chain without evaluating it", () => {
     const source = [
       'import { page } from "akanjs/client";',
       "export default page()",
       '  .param("projectId", ID, { desc: "The project." })',
       '  .search("status", String)',
+      "  .search(dynamicName, String)",
+      "  .guard(() => signedIn())",
       "  .config({ transition: 'stack', devOnly: true })",
       '  .prompt("briefProject", "Brief one project.")',
       '  .app("showProject", "Show one project.", ({ projectId }) => null)',
@@ -57,7 +59,14 @@ describe("RouteSourceValidator route chains", () => {
     ].join("\n");
     expect(chain(source, "page", "/:lang/project/:projectId")).toEqual({
       devOnly: true,
-      chain: { kind: "page", params: ["projectId"], prompt: "briefProject", apps: ["showProject", "showBoard"] },
+      chain: {
+        kind: "page",
+        params: ["projectId"],
+        prompt: "briefProject",
+        apps: ["showProject", "showBoard"],
+        search: ["status"],
+        guarded: true,
+      },
     });
   });
 

package/routeSourceValidator.ts

@@ -17,6 +17,10 @@ export interface RouteSourceChain {
   prompt?: string;
   /** The `.app()` names, each one MCP App the build gives a view of its own. */
   apps: string[];
+  /** The `.search()` names, in chain order; a name that is not a literal is left out. */
+  search: string[];
+  /** The chain calls `.guard()`, which gates this route and, on a layout, every route under it. */
+  guarded: boolean;
 }
 
 interface ChainStage {
@@ -104,6 +108,8 @@ export class RouteSourceValidator {
         params: chain.params,
         ...(chain.prompt ? { prompt: chain.prompt } : {}),
         apps: chain.apps,
+        search: chain.search,
+        guarded: chain.guarded,
       },
     };
   }
@@ -168,8 +174,10 @@ export class RouteSourceValidator {
   static #chainOf(kind: RouteSourceChain["kind"], stages: ChainStage[], filePath: string) {
     const params: string[] = [];
     const apps: string[] = [];
+    const search: string[] = [];
     let prompt: string | undefined;
     let devOnly = false;
+    let guarded = false;
     const literal = (stage: ChainStage) => {
       const first = stage.args[0];
       if (!first || !ts.isStringLiteralLike(first))
@@ -182,10 +190,14 @@ export class RouteSourceValidator {
       if (stage.name === "param") params.push(literal(stage));
       else if (stage.name === "prompt") prompt = literal(stage);
       else if (stage.name === "app") apps.push(literal(stage));
-      else if (stage.name === "config")
+      else if (stage.name === "guard") guarded = true;
+      else if (stage.name === "search") {
+        const first = stage.args[0];
+        if (first && ts.isStringLiteralLike(first)) search.push(first.text);
+      } else if (stage.name === "config")
         devOnly = RouteSourceValidator.#devOnlyOf(RouteSourceValidator.#unwrapExpression(stage.args[0]), filePath);
     }
-    return { kind, params, prompt, apps, devOnly };
+    return { kind, params, prompt, apps, search, guarded, devOnly };
   }
 
   /** The same rule the loader applies: a page names every `[x]` it sits under, a layout may name a subset. */

package/codeAgent/feedback/PreviewView.ts

@@ -1,95 +0,0 @@
-import { PreviewChrome } from "./PreviewChrome";
-
-export interface PreviewProbeResult {
-  url: string;
-  title: string;
-  consoleErrors: string[];
-  pageErrors: string[];
-  /** Cheap structural smells that read as "the page is broken" without anyone looking at it. */
-  domFindings: string[];
-  screenshot?: string;
-}
-
-interface WebViewLike {
-  navigate(url: string): Promise<void>;
-  evaluate(expression: string): Promise<unknown>;
-  screenshot(options: { encoding: "base64" }): Promise<string>;
-  close(): void | Promise<void>;
-  readonly title: string;
-}
-
-// Bun.WebView rather than a downloaded browser: on macOS its webkit backend needs no Chromium at all.
-// It is experimental, so its whole surface stays behind this adapter; a Bun minor that changes it breaks one file.
-export class PreviewView {
-  static get available() {
-    return typeof (Bun as unknown as { WebView?: unknown }).WebView === "function" && PreviewChrome.available;
-  }
-
-  static unavailableReason() {
-    if (typeof (Bun as unknown as { WebView?: unknown }).WebView !== "function")
-      return "This Bun build has no WebView, so the page preview is off.";
-    return PreviewChrome.unavailableReason();
-  }
-
-  static async probe(url: string, { screenshot = false, width = 1280, height = 800 } = {}) {
-    const logs: string[] = [];
-    const view = PreviewView.#open({ width, height, onConsole: (line) => logs.push(line) });
-    try {
-      await view.navigate(url);
-      const result: PreviewProbeResult = {
-        url,
-        title: view.title,
-        consoleErrors: logs.filter((line) => line.startsWith("error") || line.startsWith("warn")),
-        pageErrors: PreviewView.#strings(await view.evaluate(pageErrorsExpression)),
-        domFindings: PreviewView.#strings(await view.evaluate(domFindingsExpression)),
-      };
-      if (screenshot) result.screenshot = await view.screenshot({ encoding: "base64" });
-      return result;
-    } finally {
-      await view.close();
-    }
-  }
-
-  static #open({ width, height, onConsole }: { width: number; height: number; onConsole: (line: string) => void }) {
-    const Ctor = (Bun as unknown as { WebView: new (options: unknown) => WebViewLike }).WebView;
-    return new Ctor({
-      width,
-      height,
-      dataStore: "ephemeral",
-      backend: PreviewChrome.backendOption(),
-      // The console option is a callback taking `(type, ...args)`, not an object of console methods.
-      console: (type: string, ...args: unknown[]) => onConsole(`${type} ${args.map(String).join(" ")}`),
-    });
-  }
-
-  static #strings(value: unknown) {
-    return Array.isArray(value) ? value.filter((entry): entry is string => typeof entry === "string") : [];
-  }
-}
-
-// evaluate() takes one expression (a statement list is a SyntaxError), hence the IIFEs; one call in flight per view.
-const pageErrorsExpression = `(() => {
-  const found = [];
-  const root = document.getElementById("__next") || document.body;
-  const rendered = root ? Array.from(root.children).filter((el) => !["SCRIPT", "STYLE", "TEMPLATE", "LINK", "NOSCRIPT"].includes(el.tagName)) : [];
-  if (!rendered.length && !(root && root.innerText && root.innerText.trim())) found.push("The page body rendered empty.");
-  const overlay = document.querySelector("[data-nextjs-dialog], .error-overlay, #akan-error");
-  if (overlay) found.push("An error overlay is on the page: " + overlay.textContent.slice(0, 400));
-  return found;
-})()`;
-
-const domFindingsExpression = `(() => {
-  const found = [];
-  const all = Array.from(document.querySelectorAll("body *"));
-  const overflowing = all.filter((el) => el.scrollWidth > document.documentElement.clientWidth + 8);
-  if (overflowing.length) found.push(overflowing.length + " element(s) overflow the viewport horizontally, first: " + (overflowing[0].tagName + "." + overflowing[0].className).slice(0, 120));
-  const invisibleText = all.filter((el) => {
-    if (!el.textContent || !el.textContent.trim()) return false;
-    const style = getComputedStyle(el);
-    return style.color === style.backgroundColor && style.backgroundColor !== "rgba(0, 0, 0, 0)";
-  });
-  if (invisibleText.length) found.push(invisibleText.length + " element(s) render text in the same colour as their background.");
-  const unresolved = all.filter((el) => /(^|\\s)(bg|text|border)-(base-100|base-content|primary-content|error)(\\s|$)/.test(el.className || ""));
-  if (unresolved.length) found.push(unresolved.length + " element(s) use a dropped daisyUI colour slot that renders no CSS.");
-  return found;
-})()`;