@akanjs/devkit 3.2.0-rc.0 → 3.2.0-rc.1

package/CHANGELOG.md

@@ -177,6 +177,10 @@
   - **The CSR build and its MCP App views** rewrite `akanjs/ui` imports to the components a file names, as the SSR route builds already did, so a page that imports `Link` no longer bundles every component.
   - **Animations use `@react-spring/web`** instead of the `react-spring` umbrella package, which also installed the native, three.js, konva and zdog renderers.
 
+- 686e0b8: `akan preview` and the code agent's page preview bound a page only once the browser is up. Before, a process's first page shared its `timeoutMs` with starting the browser. On a cold machine where Chrome took longer than that to start, the first page failed as `Timed out loading …; the dev server may be rebuilding or stuck.`
+
+  Starting the browser now has its own bound of 120 s, `startTimeoutMs` on `PreviewView.probe`. Running out of it reads `Timed out starting the <engine> browser after 120 s.`, where the engine is `chrome` or `webkit`. A browser that misses its bound may still come up late, so later pages in that process try again, but each waits only its own `timeoutMs` for the browser. Once the browser answers, the full bound applies again. So a browser that never starts holds the first page for 120 s, where before it held it for `timeoutMs` (60 s for `akan preview`, 30 s for the code agent's check).
+
 - eefd9cb: `akan preview <app> /_akan/studio` opens Studio instead of a 404. Preview added the default locale to every path, and the server routes `/_akan/*` without one, so `/en/_akan/studio` matched no page. A path under `/_akan`, `/__csr`, `/__rsc`, `/.well-known` or the app's API prefix, a file the app's `public/` holds, and the server's own `/favicon.ico`, `/robots.txt`, `sitemap.xml` and `manifest.webmanifest` now open as written: no locale, and no CSR boot query under `--csr`. Every other path, including one that already starts with a locale or ends in a dotted segment such as `/release/1.2.3`, is a page and gets the default locale as before. The `akan-debug` skill and the `akan preview` reference say so.
 - 4fcf44f: A new `rename-key` workflow renames a slice key or a Filter query key everywhere it is spelled. That covers the key itself, every name derived from it (`initMemoInPublic`, `memoListInPublic`, `queryByName`) in the app and every lib, and its module dictionary entry. It is the same rename the editor extension's F2 runs, so agents get it through `plan_workflow` / `apply_workflow` and the CLI through `akan workflow plan rename-key --app <app> --module <module> --slice <key> --to <newKey>` (or `--query <key>`). The plan lists each file it will change. A use that could also be another model's is left alone, and `akan verify` then reports it.
 - 9a9e1fa: A server page from `akan build` now preloads its client modules from `<head>`, so a cold load stops waiting on chains of imports.
@@ -343,6 +347,7 @@
 - Updated dependencies [df32c46]
 - Updated dependencies [5f809e8]
 - Updated dependencies [206bb69]
+- Updated dependencies [6291fec]
 - Updated dependencies [0c480c6]
 - Updated dependencies [d9eaacc]
   - akanjs@3.2.0

package/createTunnel.test.ts

@@ -20,10 +20,20 @@ const publicBlobOf = (publicKey: string) => {
   return parsed.getPublicSSH();
 };
 
+//? ssh2 1.17's keygen strips a leading zero byte off an ed25519 public key, so 1 pair in 256 cannot be read back.
+const ed25519Pair = () => {
+  for (let tries = 1; ; tries++) {
+    const pair = utils.generateKeyPairSync("ed25519");
+    const parsed = utils.parseKey(pair.private);
+    if (!(parsed instanceof Error)) return pair;
+    if (tries === 8) throw parsed;
+  }
+};
+
 const sshServers: { server: Server; clients: Set<Connection> }[] = [];
 
 const startSshServer = async () => {
-  const hostKey = utils.generateKeyPairSync("ed25519");
+  const hostKey = ed25519Pair();
   const methods: string[] = [];
   const clients = new Set<Connection>();
   const server = new Server({ hostKeys: [hostKey.private] }, (client) => {
@@ -136,7 +146,7 @@ describe("createTunnel", () => {
     const ssh = await startSshServer();
     const knownHosts = path.join(root, "known_hosts.json");
     const keyPath = path.join(root, "id_tunnel");
-    await writeFile(keyPath, utils.generateKeyPairSync("ed25519").private);
+    await writeFile(keyPath, ed25519Pair().private);
     Object.assign(process.env, {
       SSH_TUNNEL_PORT: String(ssh.port),
       SSH_TUNNEL_KNOWN_HOSTS: knownHosts,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akanjs/devkit",
-  "version": "3.2.0-rc.0",
+  "version": "3.2.0-rc.1",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -41,7 +41,7 @@
     "./*": "./*.ts"
   },
   "dependencies": {
-    "@akanjs/language": "3.2.0-rc.0",
+    "@akanjs/language": "3.2.0-rc.1",
     "@earendil-works/pi-agent-core": "1.3.0",
     "@earendil-works/pi-ai": "1.3.0",
     "@earendil-works/pi-codemode": "1.3.0",
@@ -50,7 +50,7 @@
     "@earendil-works/pi-tui": "1.3.0",
     "@inquirer/prompts": "^8.7.3",
     "@tailwindcss/node": "^4.3.3",
-    "akanjs": "3.2.0-rc.0",
+    "akanjs": "3.2.0-rc.1",
     "chalk": "^6.0.1",
     "commander": "^15.0.0",
     "dayjs": "^1.11.23",

package/preview/PreviewChrome.ts

@@ -12,12 +12,12 @@ export class PreviewChrome {
   /** Set this to drive Chrome on macOS too, e.g. to reproduce what a pod sees. */
   static readonly backendEnvKey = "AKAN_CODE_WEBVIEW_BACKEND";
 
-  /** The executables Bun looks for on PATH before giving up. */
+  /** The executables Bun looks for on PATH before giving up, in its order: the first found is the one it starts. */
   static readonly executables = [
-    "chromium",
-    "chromium-browser",
     "google-chrome-stable",
     "google-chrome",
+    "chromium-browser",
+    "chromium",
     "brave-browser",
     "microsoft-edge",
     "chrome",

package/preview/PreviewView.ts

@@ -5,7 +5,8 @@ export interface PreviewProbeOptions {
   width?: number;
   height?: number;
   engine?: PreviewEngine;
-  /** Bounds the whole probe: a dev server that is recovering takes the connection and never answers. */
+  startTimeoutMs?: number;
+  /** Bounds the probe once the browser is up: 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;
@@ -45,6 +46,10 @@ interface PageRead {
 // 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 {
+  /** A view's first navigation includes the browser's start, which took ~35 s on a cold CI runner. */
+  static readonly startTimeoutMs = 120_000;
+  static readonly #stalled = new Set<PreviewEngine>();
+
   static get available() {
     return PreviewView.isAvailable();
   }
@@ -66,15 +71,31 @@ export class PreviewView {
       width = 1280,
       height = 800,
       engine = PreviewChrome.backend,
+      startTimeoutMs = PreviewView.startTimeoutMs,
       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 {
+      //? A browser that missed its start bound may still come up, so a later page retries it within only its own bound.
+      const startMs = PreviewView.#stalled.has(engine) ? Math.min(startTimeoutMs, timeoutMs) : startTimeoutMs;
+      const stalled = new Error(`Timed out starting the ${engine} browser after ${startMs / 1_000} s.`);
+      await PreviewView.#within(view.navigate("about:blank"), Date.now() + startMs, stalled).then(
+        () => PreviewView.#stalled.delete(engine),
+        (error: unknown) => {
+          if (error === stalled) PreviewView.#stalled.add(engine);
+          throw error;
+        },
+      );
+      const deadline = Date.now() + timeoutMs;
+      const within = <T>(work: Promise<T>, what: string) =>
+        PreviewView.#within(
+          work,
+          deadline,
+          new Error(`Timed out ${what} ${url}; the dev server may be rebuilding or stuck.`),
+        );
       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) {
@@ -126,13 +147,10 @@ export class PreviewView {
     return response?.status ?? null;
   }
 
-  static async #within<T>(work: Promise<T>, deadline: number, what: string): Promise<T> {
+  static async #within<T>(work: Promise<T>, deadline: number, expiry: Error): 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()),
-      );
+      timer = setTimeout(() => reject(expiry), Math.max(0, deadline - Date.now()));
     });
     try {
       return await Promise.race([work, expired]);

package/preview/previewView.test.ts

@@ -1,9 +1,42 @@
 import { describe, expect, test } from "bun:test";
+import { chmod, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { PreviewChrome } from "./PreviewChrome";
 import { PreviewView } from "./PreviewView";
 
 const serve = (html: string, status = 200) =>
   Bun.serve({ port: 0, fetch: () => new Response(html, { status, headers: { "content-type": "text/html" } }) });
 
+const browserTestMs = PreviewView.startTimeoutMs + 30_000;
+const slowChromeRuns = PreviewView.isAvailable("chrome") && process.platform !== "win32";
+
+const withSlowChrome = async (body: string, startSeconds = 3) => {
+  const dir = await mkdtemp(path.join(tmpdir(), "akan-slow-chrome-"));
+  const chrome = path.join(dir, "chrome");
+  await writeFile(chrome, `#!/bin/sh\nsleep ${startSeconds}\nexec "${PreviewChrome.executable()}" "$@"\n`);
+  await chmod(chrome, 0o755);
+  const script = `const { PreviewView } = await import(${JSON.stringify(path.join(import.meta.dir, "PreviewView.ts"))});\n${body}`;
+  //? Chrome is spawned once per process, so only a fresh process takes the slow executable.
+  const child = Bun.spawn([process.execPath, "-e", script], {
+    env: { ...process.env, [PreviewChrome.pathEnvKey]: chrome },
+    stdout: "pipe",
+    stderr: "pipe",
+    timeout: PreviewView.startTimeoutMs + 15_000,
+  });
+  try {
+    const [out, err, code] = await Promise.all([
+      new Response(child.stdout).text(),
+      new Response(child.stderr).text(),
+      child.exited,
+    ]);
+    return { code, out: out.trim(), err };
+  } finally {
+    child.kill();
+    await rm(dir, { recursive: true, force: true });
+  }
+};
+
 describe("PreviewView", () => {
   test("reports whether this Bun build can drive a headless page at all", () => {
     expect(typeof PreviewView.available).toBe("boolean");
@@ -29,7 +62,7 @@ describe("PreviewView", () => {
         server.stop(true);
       }
     },
-    30_000,
+    browserTestMs,
   );
 
   test.skipIf(!PreviewView.available)(
@@ -56,7 +89,7 @@ describe("PreviewView", () => {
         server.stop(true);
       }
     },
-    30_000,
+    browserTestMs,
   );
 
   test.skipIf(!PreviewView.available)(
@@ -71,6 +104,57 @@ describe("PreviewView", () => {
         server.stop(true);
       }
     },
-    30_000,
+    browserTestMs,
+  );
+
+  test.skipIf(!slowChromeRuns)(
+    "starts the page's bound once the browser is up, however long Chrome takes to spawn",
+    async () => {
+      const server = serve("<!doctype html><title>Up</title><body>up</body>");
+      try {
+        const { code, out, err } = await withSlowChrome(
+          `const probe = await PreviewView.probe("http://localhost:${server.port}/", { engine: "chrome", timeoutMs: 1_500 });
+console.log(probe.text);`,
+        );
+        expect(out || err).toBe("up");
+        expect(code).toBe(0);
+      } finally {
+        server.stop(true);
+      }
+    },
+    browserTestMs,
+  );
+
+  test.skipIf(!slowChromeRuns)(
+    "gives a later page only its own bound for a browser that missed its start, and recovers once it is up",
+    async () => {
+      const { code, out, err } = await withSlowChrome(
+        `const open = () =>
+  PreviewView.probe("about:blank", { engine: "chrome", startTimeoutMs: 1_500, timeoutMs: 1_000 }).then(
+    () => "opened",
+    (error) => error.message,
+  );
+console.log(await open());
+console.log(await open());
+let late = await open();
+for (let tries = 0; late !== "opened" && tries < 100; tries++) late = await open();
+console.log(late);
+Bun.WebView.closeAll();
+await Bun.sleep(500);
+console.log(await open());
+Bun.WebView.closeAll();`,
+        6,
+      );
+      expect(out || err).toBe(
+        [
+          "Timed out starting the chrome browser after 1.5 s.",
+          "Timed out starting the chrome browser after 1 s.",
+          "opened",
+          "Timed out starting the chrome browser after 1.5 s.",
+        ].join("\n"),
+      );
+      expect(code).toBe(0);
+    },
+    browserTestMs,
   );
 });