@akanjs/devkit 3.1.1-rc.9 → 3.1.1

package/maintainabilityReport.test.ts

@@ -0,0 +1,130 @@
+import { describe, expect, test } from "bun:test";
+import type { SizeViolation } from "./maintainabilityContract";
+import { MaintainabilityReport } from "./maintainabilityReport";
+
+const fileOf = (file: string, lineCount = 450): SizeViolation => ({
+  kind: "size",
+  rule: "akan.size.file",
+  key: file,
+  file,
+  line: 1,
+  lineCount,
+  maxLines: 400,
+});
+
+const fixLinesOf = (message: string) => message.split("How to fix:\n")[1]?.split("\n") ?? [];
+
+describe("MaintainabilityReport", () => {
+  test("gives a client file, a ui/ or webkit/ file, a long component and a busy one the same ordered paths", () => {
+    const message = MaintainabilityReport.describe("apps/demo", [
+      fileOf("lib/court/Court.Zone.tsx"),
+      fileOf("ui/Board.tsx"),
+      fileOf("webkit/useBoard.tsx"),
+      {
+        ...fileOf("lib/court/Court.Zone.tsx", 300),
+        rule: "akan.size.component",
+        key: "lib/court/Court.Zone.tsx#Canvas",
+        line: 4,
+        maxLines: 250,
+        component: "Canvas",
+      },
+      {
+        kind: "storeAccess",
+        rule: "akan.component.store-access",
+        key: "lib/court/Court.Zone.tsx#Canvas",
+        file: "lib/court/Court.Zone.tsx",
+        line: 4,
+        component: "Canvas",
+        accessCount: 20,
+        maxAccesses: 16,
+      },
+    ]);
+    const [fix = "", ...rest] = fixLinesOf(message);
+    const order = ["mode/kind table", "webkit/use<X>.tsx", "`common/`", "add-mutation", "`lib/<sub>`"].map((path) =>
+      fix.indexOf(path),
+    );
+
+    expect(rest).toEqual([]);
+    expect(fix).toStartWith(
+      "  *.Zone.tsx, ui/**, webkit/**, component or hook, component or hook reaching the store often: ",
+    );
+    expect(order.every((idx) => idx > 0)).toBe(true);
+    expect([...order].sort((a, b) => a - b)).toEqual(order);
+    expect(fix).toContain('`{ [kind in cnst.X["value"]]: … }`');
+    expect(fix).toContain("akan workflow plan create-interaction");
+    expect(fix).toContain("never model-bound code moved into `ui/`");
+  });
+
+  test("names a write sent from the wrong place, a call per item and a raised entry with their own fixes", () => {
+    const message = MaintainabilityReport.describe("apps/demo", [
+      {
+        kind: "baselineGrowth",
+        rule: "akan.baseline.growth",
+        key: "lib/court/court.store.ts#assign",
+        file: "akan.baseline.json",
+        line: 5,
+        debtRule: "akan.store.multi-write",
+        count: 3,
+        committed: 2,
+        reference: "3f2a9c1d0b7e",
+      },
+      {
+        kind: "writePlacement",
+        rule: "akan.write.placement",
+        key: "webkit/useBoard.tsx",
+        file: "webkit/useBoard.tsx",
+        line: 7,
+        writes: ["st.do.removeBoard", "fetch.placeBoard"],
+      },
+      {
+        kind: "loopCall",
+        rule: "akan.service.call-in-loop",
+        key: "lib/court/court.service.ts#syncAll",
+        file: "lib/court/court.service.ts",
+        line: 12,
+        owner: "syncAll",
+        calls: ["this.pcService.getPc"],
+        recorded: 0,
+      },
+      {
+        kind: "multiWrite",
+        rule: "akan.component.write-chain",
+        key: "webkit/useBoard.tsx#useBoard",
+        file: "webkit/useBoard.tsx",
+        line: 9,
+        owner: "useBoard",
+        writes: ["st.do.removeBoard (per item)"],
+        writeCount: 2,
+      },
+    ]);
+
+    expect(message).toContain(
+      'akan.baseline.growth  entry "lib/court/court.store.ts#assign" under akan.store.multi-write allows 3 writes, above the 2 at 3f2a9c1d0b7e',
+    );
+    expect(message).toContain(
+      "akan.write.placement  sends 2 server write(s) from outside a store action or a module component: st.do.removeBoard, fetch.placeBoard",
+    );
+    expect(message).toContain(
+      "akan.service.call-in-loop  service method syncAll calls once per item: this.pcService.getPc, more than the 0 recorded",
+    );
+    expect(message).toContain("hook useBoard sends a write per item from one handler: st.do.removeBoard (per item)");
+    expect(fixLinesOf(message).map((line) => line.split(":")[0])).toEqual([
+      "  baseline entry",
+      "  write sent outside a store action or module component",
+      "  service call per item",
+      "  handler with several writes",
+    ]);
+  });
+
+  test("keeps the server files' own fixes", () => {
+    const message = MaintainabilityReport.describe("apps/demo", [
+      fileOf("lib/court/Court.View.tsx"),
+      fileOf("lib/court/court.service.ts", 520),
+    ]);
+
+    expect(fixLinesOf(message)).toEqual([
+      "  *.View.tsx: Move model-independent pieces into ui/ components and display logic onto Light<Model>.",
+      "  *.service.ts: Move state transitions into document chain methods, and split an unrelated responsibility into its own module.",
+    ]);
+  });
+});

package/maintainabilityReport.ts

@@ -0,0 +1,153 @@
+import { AbstractDoc } from "./abstractDoc";
+import type {
+  DebtRuleId,
+  MaintainabilityCommands,
+  MaintainabilityFailure,
+  MaintainabilityRuleId,
+} from "./maintainabilityContract";
+import { type FileKind, MaintainabilityLimits } from "./maintainabilityLimits";
+
+type FixKey = FileKind | Exclude<MaintainabilityRuleId, "akan.size.file">;
+
+export class MaintainabilityReport {
+  static readonly #clientSplitFix =
+    'Split it, in this order: a mode/kind table `{ [kind in cnst.X["value"]]: … }` in place of mode flags, each entry a component of the module owning the data of that kind; an interaction hook in `webkit/use<X>.tsx` with its pure logic in `common/` (`akan workflow plan create-interaction`); the writes behind one endpoint (`akan workflow plan add-mutation`); last, a sub-concept in its own module (`lib/<sub>` or `lib/_<feature>`), never model-bound code moved into `ui/`.';
+  static readonly #serverMarkupFix =
+    "Move model-independent pieces into ui/ components and display logic onto Light<Model>.";
+  static readonly #oneEndpointFix =
+    "Make it one service method that runs the writes inside `this.transaction(fn)`, with a side effect such as a push command in `this.afterCommit(fn)`, behind one endpoint the action calls once; a write per item becomes one endpoint taking the list. An MCP agent or another screen calling one endpoint alone skips the rest.";
+  static readonly #fixes: { [key in FixKey]: string } = {
+    ".Template.tsx": MaintainabilityReport.#clientSplitFix,
+    ".Unit.tsx": MaintainabilityReport.#serverMarkupFix,
+    ".Util.tsx": MaintainabilityReport.#clientSplitFix,
+    ".View.tsx": MaintainabilityReport.#serverMarkupFix,
+    ".Zone.tsx": MaintainabilityReport.#clientSplitFix,
+    "ui/": MaintainabilityReport.#clientSplitFix,
+    "webkit/": MaintainabilityReport.#clientSplitFix,
+    ".store.ts":
+      "Move business logic into the service behind an endpoint and derived values onto Light<Model>; an action is fetch, set, toast.",
+    ".document.ts":
+      "Move display and predicate logic onto Light<Model>, and split an unrelated concept into its own module.",
+    ".service.ts":
+      "Move state transitions into document chain methods, and split an unrelated responsibility into its own module.",
+    [AbstractDoc.suffix]:
+      "Trim the abstract to a title, one sentence naming what the module owns, and a `## Rules` list of the invariants the code cannot show.",
+    "akan.size.component": MaintainabilityReport.#clientSplitFix,
+    "akan.store.multi-write": MaintainabilityReport.#oneEndpointFix,
+    "akan.store.root-write-chain": `A store may call another through \`RootStore\`, but that does not make the writes one. ${MaintainabilityReport.#oneEndpointFix}`,
+    "akan.component.write-chain":
+      "Move the writes into one service method behind one endpoint, called by one store action the handler calls once; a component chaining `st.do` writes, or writing once per item, leaves an agent or another screen half-done.",
+    "akan.component.store-access": MaintainabilityReport.#clientSplitFix,
+    "akan.write.placement":
+      "A server write leaves the browser through one store action, started by one module component. Move a `fetch.<mutation>` into a store action, and hand `ui/` and `webkit/` code the write as an `onX` prop or hook argument from the module's `Zone` or `Util`: they stay free of any one model, and an agent or another screen reaches the write through the store.",
+    "akan.service.call-in-loop":
+      "Load the set once (`load<Model>Many(ids)`, one filter query) or write it once (one batch method), then loop in memory: a call per item is a round trip per item, so the endpoint slows as its input grows.",
+    "akan.baseline.growth":
+      "Restore the entry from the default branch, then split the file or move the writes instead: `akan lint` lowers an entry as the code shrinks and never raises one.",
+  };
+
+  static readonly #labels: { [key in FixKey]?: string } = {
+    "ui/": "ui/**",
+    "webkit/": "webkit/**",
+    "akan.size.component": "component or hook",
+    "akan.store.multi-write": "store action with several writes",
+    "akan.store.root-write-chain": "store method chaining other stores' writes",
+    "akan.component.write-chain": "handler with several writes",
+    "akan.component.store-access": "component or hook reaching the store often",
+    "akan.write.placement": "write sent outside a store action or module component",
+    "akan.service.call-in-loop": "service call per item",
+    "akan.baseline.growth": "baseline entry",
+  };
+
+  static readonly #units: { [rule in DebtRuleId]: string } = {
+    "akan.size.file": "lines",
+    "akan.size.component": "lines",
+    "akan.component.store-access": "store accesses",
+    "akan.store.multi-write": "writes",
+    "akan.store.root-write-chain": "writes",
+    "akan.component.write-chain": "writes",
+    "akan.write.placement": "writes",
+    "akan.service.call-in-loop": "calls per item",
+  };
+
+  static describe(sysPath: string, failures: MaintainabilityFailure[], commands: MaintainabilityCommands = {}) {
+    const groups = new Map<string, { labels: string[]; rules: Set<MaintainabilityRuleId> }>();
+    for (const failure of failures) {
+      const fixKey = MaintainabilityReport.#fixKeyOf(failure);
+      const fix = MaintainabilityReport.#fixes[fixKey];
+      const group = groups.get(fix) ?? { labels: [], rules: new Set() };
+      const label = MaintainabilityReport.#labelOf(fixKey);
+      if (!group.labels.includes(label)) group.labels.push(label);
+      group.rules.add(failure.rule);
+      groups.set(fix, group);
+    }
+    return [
+      `[maintainability] ${failures.length} violation(s) in ${sysPath}:`,
+      ...failures.map(
+        (failure) =>
+          `  ${sysPath}/${failure.file}:${failure.line}  ${failure.rule}  ${MaintainabilityReport.#problemOf(failure)}`,
+      ),
+      "How to fix:",
+      ...[...groups].flatMap(([fix, { labels, rules }]) => [
+        `  ${labels.join(", ")}: ${fix}`,
+        ...[...new Set([...rules].flatMap((rule) => commands[rule] ?? []))].map((command) => `    Path: ${command}`),
+      ]),
+    ].join("\n");
+  }
+
+  static entriesOf(sysPath: string, failures: MaintainabilityFailure[], commands: MaintainabilityCommands = {}) {
+    return failures.map((failure) => ({
+      file: `${sysPath}/${failure.file}`,
+      line: failure.line,
+      rule: failure.rule,
+      problem: MaintainabilityReport.#problemOf(failure),
+      fix: MaintainabilityReport.#fixes[MaintainabilityReport.#fixKeyOf(failure)],
+      path: commands[failure.rule]?.[0] ?? null,
+    }));
+  }
+
+  static #problemOf(failure: MaintainabilityFailure) {
+    if (failure.kind === "baselineGrowth") {
+      const entry = `entry "${failure.key}" under ${failure.debtRule}`;
+      return failure.committed === undefined
+        ? `${entry} is not in the baseline at ${failure.reference}, which may only shrink`
+        : `${entry} allows ${failure.count} ${MaintainabilityReport.#units[failure.debtRule]}, above the ${failure.committed} at ${failure.reference}; the baseline may only shrink`;
+    }
+    const grown = failure.recorded === undefined ? "" : `, more than the ${failure.recorded} recorded`;
+    if (failure.kind === "multiWrite") {
+      const writes = failure.writes.some((write) => write.endsWith("(per item)"))
+        ? "a write per item"
+        : `${failure.writes.length} writes`;
+      const listed = `${failure.writes.join(", ")}${grown}`;
+      if (failure.rule === "akan.component.write-chain")
+        return `${MaintainabilityReport.#unitOf(failure.owner)} ${failure.owner} sends ${writes} from one handler: ${listed}`;
+      if (failure.rule === "akan.store.root-write-chain")
+        return `store method ${failure.owner} chains ${writes} through other stores from the browser: ${listed}`;
+      return `store action ${failure.owner} sends ${writes} from the browser: ${listed}`;
+    }
+    if (failure.kind === "writePlacement")
+      return `sends ${failure.writes.length} server write(s) from outside a store action or a module component: ${failure.writes.join(", ")}${grown}`;
+    if (failure.kind === "loopCall")
+      return `service method ${failure.owner} calls once per item: ${failure.calls.join(", ")}${grown}`;
+    if (failure.kind === "storeAccess")
+      return `${MaintainabilityReport.#unitOf(failure.component)} ${failure.component} reaches the store ${failure.accessCount} times, over the ${failure.maxAccesses}-access limit${failure.recorded === undefined ? "" : `, up from ${failure.recorded}`}`;
+    const subject = failure.component
+      ? `${MaintainabilityReport.#unitOf(failure.component)} ${failure.component} has`
+      : "file has";
+    const up = failure.recorded === undefined ? "" : `, up from ${failure.recorded}`;
+    return `${subject} ${failure.lineCount} lines, over the ${failure.maxLines}-line limit${up}`;
+  }
+
+  static #unitOf(name: string) {
+    return /^use[A-Z]/.test(name) ? "hook" : "component";
+  }
+
+  static #fixKeyOf(failure: MaintainabilityFailure): FixKey {
+    if (failure.rule !== "akan.size.file") return failure.rule;
+    return MaintainabilityLimits.fileKindOf(failure.file) ?? "akan.size.component";
+  }
+
+  static #labelOf(fixKey: FixKey) {
+    return MaintainabilityReport.#labels[fixKey] ?? `*${fixKey}`;
+  }
+}

package/mobile/desktopRelease.test.ts

@@ -381,7 +381,7 @@ describe("DesktopRelease signer", () => {
 
   const windowsTool = (powershell: (out: string) => Promise<number>) =>
     recordingTool(async (cmd, env) => {
-      if (cmd[0] === "tar.exe") {
+      if (cmd[0] === path.join(process.env.SystemRoot ?? "C:\\Windows", "System32", "tar.exe")) {
         await Bun.write(path.join(extractedTo(cmd), cmd.at(-1) ?? ""), "MZ");
         return { code: 0, output: "" };
       }

package/mobile/desktopRelease.ts

@@ -245,7 +245,9 @@ Set-Content -LiteralPath $env:AKAN_SIGNER_OUT -Value $subject -Encoding UTF8`;
   }
 
   static async #subjectOf(run: SignatureTool, archive: string, tmp: string, exe: string) {
-    await run(["tar.exe", "-xzf", archive, "-C", tmp, exe]);
+    //? Windows' own bsdtar: a GNU tar ahead of it on PATH (Git's) takes `C:` for a remote host.
+    const tar = path.join(process.env.SystemRoot ?? "C:\\Windows", "System32", "tar.exe");
+    await run([tar, "-xzf", archive, "-C", tmp, exe]);
     const extracted = path.join(tmp, exe);
     if (!(await Bun.file(extracted).exists())) return { signer: null, unread: `the archive holds no ${exe}` };
     const out = path.join(tmp, "signer.txt");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akanjs/devkit",
-  "version": "3.1.1-rc.9",
+  "version": "3.1.1",
   "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.9",
+    "akanjs": "3.1.1",
     "chalk": "^6.0.1",
     "commander": "^15.0.0",
     "dayjs": "^1.11.23",

package/platformTest/LinuxDockerTarget.ts

@@ -40,6 +40,9 @@ export class LinuxDockerTarget extends PlatformTestTarget {
       "run",
       "-d",
       "--rm",
+      //? An init as PID 1 reaps orphans as a real host does; under `sleep` a killed orphan stays a zombie that still
+      //? answers kill(pid, 0).
+      "--init",
       "--name",
       container,
       "--cpus",

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";