akanjs 3.0.2 → 3.1.0-rc.1

package/vendor/@akanjs/native/packages/core/src/kernel.ts

@@ -279,3 +279,52 @@ export function decideNavigation(
   if (!topLevel) return FRAME_SCHEMES.includes(scheme) ? "load" : "drop";
   return externalSchemes(extra).includes(scheme) ? "open" : "drop";
 }
+
+export interface UpdateDecisionInput {
+  /** The binary's keyIds, in `updates.publicKeys` order. */
+  ring: readonly string[];
+  /** keyIds state.json has revoked. */
+  revoked: readonly string[];
+  /** The envelope's keyId, whose signature over the manifest verified. */
+  signer: string;
+  revokeKeys: readonly string[];
+  resetSequence: boolean;
+  sequence: number;
+  /** The binary's own bundle (updates.json `embeddedSequence`). */
+  embedded: number;
+  /** The bundle running now, null for the binary's own. */
+  running: { sequence: number; keyId: string } | null;
+}
+
+export type UpdateDecision =
+  | { kind: "untrusted" | "revoked" | "self-revoke" | "revoke-later" }
+  | { kind: "take" | "stale"; baseline: number; revoke: string[] };
+
+/**
+ * Whether a web bundle manifest is taken (updates protocol v2, vectors/updates.json). A key may revoke only keys listed
+ * before it, so a leaked online key — listed first — cannot revoke the offline spares that recover from it, and
+ * `resetSequence` counts only on a manifest that newly revokes a key, so replaying it cannot roll anyone back. A bundle a
+ * revoked key signed sets no bar, and revocations apply even when the release itself is not newer.
+ */
+export function updateDecision(input: UpdateDecisionInput): UpdateDecision {
+  const { ring, revoked, signer, revokeKeys } = input;
+  const index = ring.indexOf(signer);
+  if (index < 0) return { kind: "untrusted" };
+  if (revoked.includes(signer)) return { kind: "revoked" };
+  if (revokeKeys.includes(signer)) return { kind: "self-revoke" };
+  if (revokeKeys.some((id) => ring.indexOf(id) > index)) return { kind: "revoke-later" };
+  const revoke = ring.filter((id) => revokeKeys.includes(id) && !revoked.includes(id));
+  const running = input.running && ![...revoked, ...revoke].includes(input.running.keyId) ? input.running.sequence : 0;
+  const baseline = input.resetSequence && revoke.length ? input.embedded : Math.max(input.embedded, running);
+  return { kind: input.sequence > baseline ? "take" : "stale", baseline, revoke };
+}
+
+/** One answer of updateDecision as the vectors write it. */
+export const updateDecisionWire = (decision: UpdateDecision) =>
+  decision.kind === "take" || decision.kind === "stale"
+    ? `${decision.kind}:${decision.baseline}:${decision.revoke.join(",")}`
+    : decision.kind;
+
+/** The v2 envelope of a channel for one native API: one file per binary generation, so each takes its own fixes. */
+export const updateManifestUrl = (url: string, platform: string, channel: string, nativeApi: string) =>
+  `${url}/${platform}/${channel}/${nativeApi}.json`;

package/vendor/@akanjs/native/packages/core/vectors/updates.json

@@ -0,0 +1,31 @@
+{
+  "about": "Web bundle updates, protocol v2 (architecture.md \"업데이트\"). keyIds: [raw Ed25519 public key in base64, its keyId: the first 8 bytes of its sha256 in hex]. decisions: [the binary's keyIds in updates.publicKeys order, keyIds state.json has revoked, the envelope's keyId, the manifest's revokeKeys, its resetSequence, its sequence, the binary's embeddedSequence, the running bundle as [sequence, keyId] or null for the app's own, the answer, why] for a manifest whose signature verified; the answer is untrusted | revoked | self-revoke | revoke-later, or take|stale:<the sequence it had to beat>:<keyIds it newly revokes, comma-separated>, revocations applying even to a stale manifest. urls: [updates.url, platform, channel, nativeApi, the envelope's URL].",
+  "keyIds": [
+    ["BwcHBwcHBwcHBwcHBwcHBwcHBwcHBwcHBwcHBwcHBwc=", "4bb06f8e4e3a7715"],
+    ["11qYAYKxCrfVS/7TyWQHOg7hcvPapiMlrwIaaPcHURo=", "21fe31dfa154a261"],
+    ["AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=", "66687aadf862bd77"]
+  ],
+  "decisions": [
+    [["a1a1a1a1a1a1a1a1", "b2b2b2b2b2b2b2b2", "c3c3c3c3c3c3c3c3"], [], "a1a1a1a1a1a1a1a1", [], false, 200, 100, null, "take:100:", "signed by the first key, nothing running but the app's own bundle"],
+    [["a1a1a1a1a1a1a1a1", "b2b2b2b2b2b2b2b2", "c3c3c3c3c3c3c3c3"], [], "d4d4d4d4d4d4d4d4", [], false, 200, 100, null, "untrusted", "a key the binary does not carry"],
+    [["a1a1a1a1a1a1a1a1", "b2b2b2b2b2b2b2b2", "c3c3c3c3c3c3c3c3"], ["a1a1a1a1a1a1a1a1"], "a1a1a1a1a1a1a1a1", [], false, 200, 100, null, "revoked", "a key revoked earlier signs nothing"],
+    [["a1a1a1a1a1a1a1a1", "b2b2b2b2b2b2b2b2", "c3c3c3c3c3c3c3c3"], [], "b2b2b2b2b2b2b2b2", ["b2b2b2b2b2b2b2b2"], false, 200, 100, null, "self-revoke", "a key never revokes itself"],
+    [["a1a1a1a1a1a1a1a1", "b2b2b2b2b2b2b2b2", "c3c3c3c3c3c3c3c3"], [], "a1a1a1a1a1a1a1a1", ["b2b2b2b2b2b2b2b2"], false, 200, 100, null, "revoke-later", "a key revokes only keys listed before it"],
+    [["a1a1a1a1a1a1a1a1", "b2b2b2b2b2b2b2b2", "c3c3c3c3c3c3c3c3"], [], "b2b2b2b2b2b2b2b2", ["a1a1a1a1a1a1a1a1"], false, 300, 100, [500, "a1a1a1a1a1a1a1a1"], "take:100:a1a1a1a1a1a1a1a1", "the bundle a revoked key signed no longer sets the bar"],
+    [["a1a1a1a1a1a1a1a1", "b2b2b2b2b2b2b2b2", "c3c3c3c3c3c3c3c3"], [], "b2b2b2b2b2b2b2b2", ["a1a1a1a1a1a1a1a1"], true, 300, 100, [500, "b2b2b2b2b2b2b2b2"], "take:100:a1a1a1a1a1a1a1a1", "resetSequence with a new revocation compares with the app's own bundle"],
+    [["a1a1a1a1a1a1a1a1", "b2b2b2b2b2b2b2b2", "c3c3c3c3c3c3c3c3"], ["a1a1a1a1a1a1a1a1"], "b2b2b2b2b2b2b2b2", ["a1a1a1a1a1a1a1a1"], true, 300, 100, [500, "b2b2b2b2b2b2b2b2"], "stale:500:", "replayed: nothing new revoked, so the reset does not apply"],
+    [["a1a1a1a1a1a1a1a1", "b2b2b2b2b2b2b2b2", "c3c3c3c3c3c3c3c3"], [], "b2b2b2b2b2b2b2b2", ["a1a1a1a1a1a1a1a1", "d4d4d4d4d4d4d4d4"], false, 200, 100, null, "take:100:a1a1a1a1a1a1a1a1", "an id this binary does not carry is ignored"],
+    [["a1a1a1a1a1a1a1a1", "b2b2b2b2b2b2b2b2", "c3c3c3c3c3c3c3c3"], [], "a1a1a1a1a1a1a1a1", [], false, 100, 100, null, "stale:100:", "no newer than the app's own bundle"],
+    [["a1a1a1a1a1a1a1a1", "b2b2b2b2b2b2b2b2", "c3c3c3c3c3c3c3c3"], [], "a1a1a1a1a1a1a1a1", [], false, 150, 100, [150, "a1a1a1a1a1a1a1a1"], "stale:150:", "the bundle already running"],
+    [["a1a1a1a1a1a1a1a1", "b2b2b2b2b2b2b2b2", "c3c3c3c3c3c3c3c3"], [], "c3c3c3c3c3c3c3c3", ["a1a1a1a1a1a1a1a1", "b2b2b2b2b2b2b2b2"], false, 120, 100, null, "take:100:a1a1a1a1a1a1a1a1,b2b2b2b2b2b2b2b2", "the last key revokes both before it"],
+    [["a1a1a1a1a1a1a1a1", "b2b2b2b2b2b2b2b2", "c3c3c3c3c3c3c3c3"], [], "b2b2b2b2b2b2b2b2", ["a1a1a1a1a1a1a1a1", "a1a1a1a1a1a1a1a1"], false, 200, 100, null, "take:100:a1a1a1a1a1a1a1a1", "listed twice, revoked once"],
+    [["a1a1a1a1a1a1a1a1", "b2b2b2b2b2b2b2b2", "c3c3c3c3c3c3c3c3"], [], "a1a1a1a1a1a1a1a1", [], false, 160, 100, [150, "b2b2b2b2b2b2b2b2"], "take:150:", "another trusted key's bundle sets the bar"],
+    [["a1a1a1a1a1a1a1a1", "b2b2b2b2b2b2b2b2", "c3c3c3c3c3c3c3c3"], ["a1a1a1a1a1a1a1a1"], "c3c3c3c3c3c3c3c3", ["b2b2b2b2b2b2b2b2"], false, 200, 100, [900, "a1a1a1a1a1a1a1a1"], "take:100:b2b2b2b2b2b2b2b2", "a bundle of a key revoked before still runs this session but sets no bar"],
+    [["a1a1a1a1a1a1a1a1", "b2b2b2b2b2b2b2b2", "c3c3c3c3c3c3c3c3"], [], "a1a1a1a1a1a1a1a1", [], true, 300, 100, [500, "a1a1a1a1a1a1a1a1"], "stale:500:", "resetSequence without a revocation does nothing"],
+    [["a1a1a1a1a1a1a1a1"], [], "a1a1a1a1a1a1a1a1", [], false, 200, 100, null, "take:100:", "a ring of one"]
+  ],
+  "urls": [
+    ["https://asset.akamir.com/ota/inst1/pathA", "ios", "main", "0123456789abcdef", "https://asset.akamir.com/ota/inst1/pathA/ios/main/0123456789abcdef.json"],
+    ["http://10.0.2.2:8790", "android", "pilot", "fedcba9876543210", "http://10.0.2.2:8790/android/pilot/fedcba9876543210.json"]
+  ]
+}

package/vendor/@akanjs/native/packages/desktop/src/dispatcher.ts

@@ -33,6 +33,12 @@ import type {
 /** How long the window waits for one plugin's setup. */
 export const SETUP_TIMEOUT_MS = 3000;
 
+/**
+ * How long the launch waits for a gate plugin's setup. A gate decides whether this launch runs at all, so passing it
+ * by on time starts what the losing launch must not: a second app's server on the same data (single-instance).
+ */
+export const GATE_TIMEOUT_MS = 30_000;
+
 /**
  * How long a page's call to a plugin whose setup is still running (it outlasted SETUP_TIMEOUT_MS)
  * waits for it before it is answered INTERNAL with `retryable`.
@@ -189,6 +195,7 @@ export const COALESCE_MS = 100;
 
 export interface DispatcherOptions {
   setupTimeoutMs?: number;
+  gateTimeoutMs?: number;
   setupWaitMs?: number;
   /** The app's resolved capabilities from boot.json (PL-11). Absent: everything is allowed. */
   acl?: ResolvedAcl | null;
@@ -301,18 +308,19 @@ export function createDispatcher(
   };
 
   const timeout = options.setupTimeoutMs ?? SETUP_TIMEOUT_MS;
+  const gateTimeout = options.gateTimeoutMs ?? GATE_TIMEOUT_MS;
   /** Setups still running (plugin lifecycle rule: calls and $listen wait for them). */
   const settingUp = new Map<string, Promise<unknown>>();
-  const setUp = async (plugin: DesktopPlugin) => {
+  const setUp = async (plugin: DesktopPlugin, limit = timeout) => {
     let timer: ReturnType<typeof setTimeout> | undefined;
     try {
       const done = Promise.resolve(plugin.setup?.(context(plugin)));
       settingUp.set(plugin.id, done);
       const forget = () => void settingUp.delete(plugin.id);
       done.then(forget, forget);
-      const late = new Promise<"late">((resolve) => (timer = setTimeout(() => resolve("late"), timeout)));
+      const late = new Promise<"late">((resolve) => (timer = setTimeout(() => resolve("late"), limit)));
       if ((await Promise.race([done, late])) === "late")
-        console.warn(`[akan-native] ${plugin.id} setup took over ${timeout} ms; creating the window anyway`);
+        console.warn(`[akan-native] ${plugin.id} setup took over ${limit} ms; creating the window anyway`);
     } catch (error) {
       console.error(`[akan-native] ${plugin.id} setup failed`, error);
     } finally {
@@ -322,10 +330,10 @@ export function createDispatcher(
   
   const setups = (async () => {
     for (const plugin of plugins.filter((p) => p.launchPhase === "gate")) {
-      await setUp(plugin);
+      await setUp(plugin, gateTimeout);
       if (launch.exit !== undefined) return;
     }
-    await Promise.all(plugins.filter((p) => p.launchPhase !== "gate").map(setUp));
+    await Promise.all(plugins.filter((p) => p.launchPhase !== "gate").map((plugin) => setUp(plugin)));
   })();
   const launched = setups.then(() => {
     launching = false;

package/vendor/@akanjs/native/packages/desktop/src/main.ts

@@ -49,6 +49,7 @@ interface ShellConfig {
   /** desktop.window: the main window from its first frame, unless the launch phase says otherwise. */
   fullscreen?: boolean;
   skipTaskbar?: boolean;
+  frameless?: boolean;
 }
 
 const finite = (v: unknown): v is number => typeof v === "number" && Number.isFinite(v);
@@ -62,6 +63,7 @@ export function launchBounds(window: LaunchWindow): LaunchWindow {
   if (window.maximized === true) out.maximized = true;
   if (typeof window.fullscreen === "boolean") out.fullscreen = window.fullscreen;
   if (typeof window.skipTaskbar === "boolean") out.skipTaskbar = window.skipTaskbar;
+  if (typeof window.frameless === "boolean") out.frameless = window.frameless;
   return out;
 }
 
@@ -154,6 +156,7 @@ export async function startMain(workerUrl: string): Promise<never> {
     height: shell.height ?? 720,
     fullscreen: shell.fullscreen === true,
     skipTaskbar: shell.skipTaskbar === true,
+    frameless: shell.frameless === true,
     ...bounds,
     appDir: paths.appDir,
     initJs,

package/vendor/@akanjs/native/packages/desktop/src/plugin.ts

@@ -170,6 +170,8 @@ export interface LaunchWindow {
   fullscreen?: boolean;
   /** No taskbar button (Windows, Linux; macOS has none). */
   skipTaskbar?: boolean;
+  /** No title bar or border. */
+  frameless?: boolean;
 }
 
 /** What the launch phase decided; sent to the main thread with "ready". */

package/vendor/@akanjs/native/packages/desktop/src/server.ts

@@ -20,8 +20,15 @@ export interface ServerManifest {
   /** The file in resources/server that starts the server. */
   entry: string;
   env: Record<string, string>;
+  /** Crashes in a row before the launcher gives up, MAX_FAILURES unless named; "forever" never gives up. */
+  restart?: number | "forever";
+  /** The health route asked every `intervalMs` once the server is ready; `failures` missed in a row restart it. */
+  watchdog?: { intervalMs: number; failures: number };
 }
 
+/** Answered by the server's own process, solo or behind its gateway, without a database round trip. */
+export const HEALTH_PATH = "/_akan/app/health";
+
 /** Set by the launcher at every start, so desktop.server.env may not name them (cli lib/desktop-server.ts). */
 export const LAUNCHER_ENV_KEYS = [
   "BUN_BE_BUN",
@@ -138,6 +145,8 @@ export interface DesktopServerOptions {
   stopGrace?: number;
   restartDelay?(failures: number, everReady: boolean): number;
   now?(): number;
+  /** Whether the server at `url` answers its health route; the watchdog's question. */
+  probe?(url: string, timeoutMs: number): Promise<boolean>;
 }
 
 export interface DesktopServer {
@@ -186,14 +195,28 @@ export function createServerStatus() {
 export function readServerManifest(resources: string): ServerManifest | null {
   const file = join(resources, "server.json");
   if (!existsSync(file)) return null;
-  const raw = JSON.parse(readFileSync(file, "utf8")) as { entry?: unknown; env?: unknown };
+  const raw = JSON.parse(readFileSync(file, "utf8")) as {
+    entry?: unknown;
+    env?: unknown;
+    restart?: unknown;
+    watchdog?: { intervalMs?: unknown; failures?: unknown } | null;
+  };
   if (typeof raw.entry !== "string" || !raw.entry) throw new Error(`${file}: entry must name a file`);
   const env = Object.fromEntries(
     Object.entries((raw.env ?? {}) as Record<string, unknown>).filter(
       (entry): entry is [string, string] => typeof entry[1] === "string",
     ),
   );
-  return { entry: raw.entry, env };
+  const restart =
+    raw.restart === "forever" || (Number.isInteger(raw.restart) && (raw.restart as number) > 0)
+      ? (raw.restart as number | "forever")
+      : undefined;
+  const { intervalMs, failures } = raw.watchdog ?? {};
+  const watchdog =
+    Number.isInteger(intervalMs) && (intervalMs as number) > 0 && Number.isInteger(failures) && (failures as number) > 0
+      ? { intervalMs: intervalMs as number, failures: failures as number }
+      : undefined;
+  return { entry: raw.entry, env, ...(restart ? { restart } : {}), ...(watchdog ? { watchdog } : {}) };
 }
 
 export function serverArgv(execPath: string, resources: string, entry: string): string[] {
@@ -299,6 +322,16 @@ export function jwtSecret(dataDir: string): string {
   return secret;
 }
 
+async function probeHealth(url: string, timeoutMs: number): Promise<boolean> {
+  try {
+    const response = await fetch(url, { signal: AbortSignal.timeout(timeoutMs) });
+    await response.body?.cancel().catch(() => {});
+    return response.ok;
+  } catch {
+    return false;
+  }
+}
+
 export function restartDelay(failures: number, everReady = true): number {
   return everReady ? Math.min(1000 * 2 ** (failures - 1), 30_000) : BOOT_RESTART_DELAY;
 }
@@ -404,6 +437,8 @@ export function createDesktopServer(options: DesktopServerOptions): DesktopServe
   const pickPort = options.freePort ?? loopbackPort;
   const argv = serverArgv(options.execPath ?? process.execPath, options.resources, options.manifest.entry);
   const grace = options.stopGrace ?? STOP_GRACE;
+  const maxFailures = options.manifest.restart === "forever" ? Infinity : (options.manifest.restart ?? MAX_FAILURES);
+  const probe = options.probe ?? probeHealth;
   const logs = join(dataDir, "runtime", "logs");
   const outputLog = join(logs, "server-output.log");
   let outputSize = -1;
@@ -474,19 +509,46 @@ export function createDesktopServer(options: DesktopServerOptions): DesktopServe
 
   const failed = (why: string) => {
     failures++;
-    const line = `[akan-native] the server ${why} (${failures} of ${MAX_FAILURES} in a row)`;
+    const count = Number.isFinite(maxFailures) ? `${failures} of ${maxFailures}` : `${failures}`;
+    const line = `[akan-native] the server ${why} (${count} in a row)`;
     console.error(line);
     record(line);
     setState(everReady ? "restarting" : "starting");
-    if (failures >= MAX_FAILURES)
+    if (failures >= maxFailures)
       return giveUp(
-        `The app's server stopped ${MAX_FAILURES} times in a row and is not restarted again. Its logs are in ${logs}.`,
+        `The app's server stopped ${maxFailures} times in a row and is not restarted again. Its logs are in ${logs}.`,
       );
-    restartTimer = setTimeout(() => void launch(), (options.restartDelay ?? restartDelay)(failures, everReady));
+    
+    const paced = everReady || failures >= MAX_FAILURES;
+    restartTimer = setTimeout(() => void launch(), (options.restartDelay ?? restartDelay)(failures, paced));
+  };
+
+  const watch = (child: ServerProcess) => {
+    const { watchdog } = options.manifest;
+    if (!watchdog) return () => {};
+    let missed = 0;
+    let asking = false;
+    const timer = setInterval(async () => {
+      if (asking || proc !== child || stopping) return;
+      asking = true;
+      const healthy = await probe(`http://127.0.0.1:${port}${HEALTH_PATH}`, Math.min(watchdog.intervalMs, 5000));
+      asking = false;
+      if (proc !== child || stopping) return;
+      missed = healthy ? 0 : missed + 1;
+      if (missed < watchdog.failures) return;
+      const line = `[akan-native] the server missed ${missed} health checks in a row; killing it to restart`;
+      console.error(line);
+      record(line);
+      clearInterval(timer);
+      child.kill("SIGKILL");
+    }, watchdog.intervalMs);
+    timer.unref?.();
+    return () => clearInterval(timer);
   };
 
   const run = () => {
     let readyAt: number | null = null;
+    let unwatch = () => {};
     const child = spawn(argv, {
       cwd: dataDir,
       env,
@@ -496,6 +558,7 @@ export function createDesktopServer(options: DesktopServerOptions): DesktopServe
         if (type !== "ready" || readyAt !== null) return;
         readyAt = now();
         setState("up");
+        unwatch = watch(child);
         if (!everReady) {
           everReady = true;
           settleReady(true);
@@ -513,6 +576,7 @@ export function createDesktopServer(options: DesktopServerOptions): DesktopServe
     proc = child;
     child.exited.then(
       (code) => {
+        unwatch();
         if (proc === child) proc = null;
         child.killGroup?.(stopping ? "SIGKILL" : "SIGTERM");
         if (stopping) return;

package/vendor/@akanjs/native/plugins/external-view/native-plugin.json

@@ -0,0 +1,23 @@
+{
+  "id": "external-view",
+  "apiVersion": 1,
+  "methods": [
+    "open",
+    "navigate",
+    "reload",
+    "close",
+    "list",
+    "setVisible",
+    "setBounds",
+    "evaluate",
+    "sendKey",
+    "setMuted",
+    "clearData",
+    "capture"
+  ],
+  "events": ["load", "loadFailed", "gone", "consoleMessage"],
+  "web": null,
+  "desktop": "./src/desktop.ts",
+  "ios": null,
+  "android": null
+}

package/vendor/@akanjs/native/plugins/external-view/src/desktop.ts

@@ -0,0 +1,321 @@
+
+
+import { mkdirSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { AkanNativeError } from "../../../packages/core/src/index.ts";
+import { type DesktopContext, defineDesktopPlugin } from "../../../packages/desktop/src/plugin.ts";
+import type {
+  ExternalViewApi,
+  ExternalViewBounds,
+  ExternalViewConsoleLevel,
+  ExternalViewEvents,
+  ExternalViewState,
+} from "./index.ts";
+
+const ID = /^[A-Za-z0-9_-]{1,64}$/;
+const LEVELS: ExternalViewConsoleLevel[] = ["debug", "info", "warn", "error"];
+/** consoleMessage per view: this many in CONSOLE_WINDOW_MS, the rest counted and reported with the next one. */
+export const CONSOLE_BURST = 20;
+export const CONSOLE_WINDOW_MS = 10_000;
+
+function id(args: unknown): string {
+  const value = (args as { id?: unknown } | undefined)?.id;
+  if (typeof value !== "string" || !ID.test(value))
+    throw new AkanNativeError("INVALID_ARGS", "id must be 1-64 letters, digits, - or _");
+  return value;
+}
+
+function text(args: unknown, name: string): string {
+  const value = (args as Record<string, unknown> | undefined)?.[name];
+  if (typeof value !== "string" || !value) throw new AkanNativeError("INVALID_ARGS", `${name} must be a string`);
+  return value;
+}
+
+function bool(args: unknown, name: string): boolean {
+  const value = (args as Record<string, unknown> | undefined)?.[name];
+  if (typeof value !== "boolean") throw new AkanNativeError("INVALID_ARGS", `${name} must be a boolean`);
+  return value;
+}
+
+function bounds(value: unknown): ExternalViewBounds | undefined {
+  if (value === undefined || value === "fill") return value;
+  const b = value as Record<string, unknown> | null;
+  const ok = !!b && ["x", "y", "width", "height"].every((k) => typeof b[k] === "number" && Number.isFinite(b[k]));
+  if (!ok || (b?.width as number) <= 0 || (b?.height as number) <= 0)
+    throw new AkanNativeError("INVALID_ARGS", 'bounds must be "fill" or { x, y, width, height } with a positive size');
+  return value as ExternalViewBounds;
+}
+
+export function consoleLevel(value: unknown): ExternalViewConsoleLevel | null {
+  if (value === undefined || value === false) return null;
+  if (value === true) return "warn";
+  if (typeof value === "string" && (LEVELS as string[]).includes(value)) return value as ExternalViewConsoleLevel;
+  throw new AkanNativeError("INVALID_ARGS", `console must be a boolean or one of ${LEVELS.join(", ")}`);
+}
+
+const shell = (ctx: DesktopContext, op: string, args: Record<string, unknown>) => ctx.shell(`externalView.${op}`, args);
+
+/** The engine's own text, which the shell sends on as a string: JSON, or not, as the engine had it. */
+function parsed(value: unknown): unknown {
+  if (typeof value !== "string") return value;
+  try {
+    return JSON.parse(value) as unknown;
+  } catch {
+    return value;
+  }
+}
+
+function state(raw: unknown): ExternalViewState {
+  const { view, ...rest } = raw as { view: string } & Omit<ExternalViewState, "id">;
+  return { id: view, ...rest };
+}
+
+/** Chrome's virtual key code for a KeyboardEvent.code, which a trusted key event needs beside `key`. */
+export function virtualKey(code: string): number {
+  const letter = /^Key([A-Z])$/.exec(code);
+  if (letter?.[1]) return letter[1].charCodeAt(0);
+  const digit = /^(?:Digit|Numpad)([0-9])$/.exec(code);
+  if (digit?.[1]) return (code.startsWith("Numpad") ? 96 : 48) + Number(digit[1]);
+  const fn = /^F([0-9]{1,2})$/.exec(code);
+  if (fn?.[1] && Number(fn[1]) >= 1 && Number(fn[1]) <= 24) return 111 + Number(fn[1]);
+  const named: Record<string, number> = {
+    Space: 32,
+    Enter: 13,
+    NumpadEnter: 13,
+    Escape: 27,
+    Tab: 9,
+    Backspace: 8,
+    Delete: 46,
+    ArrowLeft: 37,
+    ArrowUp: 38,
+    ArrowRight: 39,
+    ArrowDown: 40,
+    Home: 36,
+    End: 35,
+    PageUp: 33,
+    PageDown: 34,
+    Slash: 191,
+    Minus: 189,
+    Equal: 187,
+    Period: 190,
+    Comma: 188,
+    Semicolon: 186,
+    Quote: 222,
+    BracketLeft: 219,
+    BracketRight: 221,
+    Backslash: 220,
+    Backquote: 192,
+  };
+  const known = named[code];
+  if (known === undefined) throw new AkanNativeError("INVALID_ARGS", `code ${code} is not a key sendKey knows`);
+  return known;
+}
+
+interface CdpConsoleCall {
+  type?: string;
+  args?: { value?: unknown; description?: string; unserializableValue?: string; type?: string }[];
+  stackTrace?: { callFrames?: { url?: string; lineNumber?: number }[] };
+}
+interface CdpException {
+  exceptionDetails?: {
+    text?: string;
+    url?: string;
+    lineNumber?: number;
+    exception?: { description?: string };
+    stackTrace?: CdpConsoleCall["stackTrace"];
+  };
+}
+
+/** One console call or uncaught exception as a message, from the protocol event the shell passed on. */
+export function consoleMessageOf(
+  method: string,
+  params: unknown,
+): Omit<ExternalViewEvents["consoleMessage"], "id"> | null {
+  if (method === "Runtime.exceptionThrown") {
+    const details = (params as CdpException).exceptionDetails ?? {};
+    const frame = details.stackTrace?.callFrames?.[0];
+    return {
+      level: "error",
+      text: details.exception?.description ?? details.text ?? "Uncaught exception",
+      ...(details.url || frame?.url ? { url: details.url || frame?.url } : {}),
+      ...(typeof details.lineNumber === "number" ? { line: details.lineNumber + 1 } : {}),
+    };
+  }
+  if (method !== "Runtime.consoleAPICalled") return null;
+  const call = params as CdpConsoleCall;
+  const level: ExternalViewConsoleLevel =
+    call.type === "error" || call.type === "assert"
+      ? "error"
+      : call.type === "warning"
+        ? "warn"
+        : call.type === "debug"
+          ? "debug"
+          : "info";
+  const parts = (call.args ?? []).map((arg) =>
+    typeof arg.value === "string"
+      ? arg.value
+      : String(arg.value ?? arg.unserializableValue ?? arg.description ?? arg.type),
+  );
+  const frame = call.stackTrace?.callFrames?.[0];
+  return {
+    level,
+    text: parts.join(" "),
+    ...(frame?.url ? { url: frame.url } : {}),
+    ...(typeof frame?.lineNumber === "number" ? { line: frame.lineNumber + 1 } : {}),
+  };
+}
+
+/** Lets CONSOLE_BURST messages through per window of time, and counts what it held back for the next one. */
+export function createConsoleCap(now: () => number = Date.now) {
+  const views = new Map<string, { since: number; sent: number; dropped: number }>();
+  return (view: string): { pass: boolean; dropped: number } => {
+    const t = now();
+    const entry = views.get(view) ?? { since: t, sent: 0, dropped: 0 };
+    if (t - entry.since >= CONSOLE_WINDOW_MS) Object.assign(entry, { since: t, sent: 0 });
+    views.set(view, entry);
+    if (entry.sent >= CONSOLE_BURST) {
+      entry.dropped++;
+      return { pass: false, dropped: 0 };
+    }
+    entry.sent++;
+    const dropped = entry.dropped;
+    entry.dropped = 0;
+    return { pass: true, dropped };
+  };
+}
+
+export function createDesktopExternalView() {
+  /** The console level each view was opened with: the shell sends every message, and this filters them. */
+  const levels = new Map<string, ExternalViewConsoleLevel>();
+
+  return defineDesktopPlugin<ExternalViewApi, ExternalViewEvents>({
+    id: "external-view",
+    methods: {
+      async open(args, ctx) {
+        const view = id(args);
+        const url = text(args, "url");
+        const allowOrigins = (args as { allowOrigins?: unknown }).allowOrigins;
+        if (!Array.isArray(allowOrigins) || !allowOrigins.length || allowOrigins.some((o) => typeof o !== "string"))
+          throw new AkanNativeError("INVALID_ARGS", "allowOrigins must be a list of origins");
+        const level = consoleLevel(args.console);
+        const opened = state(
+          await shell(ctx, "open", {
+            view,
+            url,
+            allowOrigins,
+            ...(args.bounds !== undefined ? { bounds: bounds(args.bounds) } : {}),
+            ...(typeof args.initScript === "string" ? { initScript: args.initScript } : {}),
+            muted: args.muted === true,
+            autoplay: args.autoplay !== false,
+            console: level !== null,
+            ...(args.window !== undefined ? { window: args.window } : {}),
+          }),
+        );
+        if (level) levels.set(view, level);
+        else levels.delete(view);
+        return opened;
+      },
+      async navigate(args, ctx) {
+        await shell(ctx, "navigate", { view: id(args), url: text(args, "url") });
+      },
+      async reload(args, ctx) {
+        await shell(ctx, "reload", { view: id(args) });
+      },
+      async close(args, ctx) {
+        const view = id(args);
+        await shell(ctx, "close", { view });
+        levels.delete(view);
+      },
+      async list(_args, ctx) {
+        return ((await shell(ctx, "list", {})) as unknown[]).map(state);
+      },
+      async setVisible(args, ctx) {
+        await shell(ctx, "setVisible", { view: id(args), visible: bool(args, "visible") });
+      },
+      async setBounds(args, ctx) {
+        await shell(ctx, "setBounds", { view: id(args), bounds: bounds(args.bounds) ?? "fill" });
+      },
+      async evaluate(args, ctx) {
+        return { value: parsed(await shell(ctx, "evaluate", { view: id(args), script: text(args, "script") })) };
+      },
+      async sendKey(args, ctx) {
+        const view = id(args);
+        const key = text(args, "key");
+        const code = text(args, "code");
+        const vk = virtualKey(code);
+        const base = { key, code, windowsVirtualKeyCode: vk, nativeVirtualKeyCode: vk };
+        
+        const typed = key.length === 1 ? { text: key, unmodifiedText: key } : {};
+        await shell(ctx, "cdp", {
+          view,
+          method: "Input.dispatchKeyEvent",
+          params: { type: "keyDown", ...base, ...typed },
+        });
+        await shell(ctx, "cdp", { view, method: "Input.dispatchKeyEvent", params: { type: "keyUp", ...base } });
+      },
+      async setMuted(args, ctx) {
+        await shell(ctx, "setMuted", { view: id(args), muted: bool(args, "muted") });
+      },
+      async clearData(args, ctx) {
+        await shell(ctx, "clearData", { view: id(args) });
+      },
+      async capture(args, ctx) {
+        const view = id(args);
+        const shot = parsed(
+          await shell(ctx, "cdp", { view, method: "Page.captureScreenshot", params: { format: "png" } }),
+        ) as { data?: string } | null;
+        if (!shot?.data) throw new AkanNativeError("INTERNAL", "the view answered no screenshot");
+        const dir = join(tmpdir(), "akan-native-external-view");
+        mkdirSync(dir, { recursive: true });
+        const file = join(dir, `${view}-${Date.now()}.png`);
+        const bytes = Buffer.from(shot.data, "base64");
+        await Bun.write(file, bytes);
+        
+        const size = bytes.length >= 24 ? { width: bytes.readUInt32BE(16), height: bytes.readUInt32BE(20) } : {};
+        return { ...ctx.registerFile(file, "image/png"), ...size };
+      },
+    },
+    events: {
+      load: (emit, ctx) =>
+        ctx.onNativeEvent("externalView", (e) => {
+          if (e.event !== "load") return;
+          emit(
+            { id: e.view as string, state: e.state as "started" | "finished", url: e.url as string },
+            { window: e.window as number },
+          );
+        }),
+      loadFailed: (emit, ctx) =>
+        ctx.onNativeEvent("externalView", (e) => {
+          if (e.event !== "loadFailed") return;
+          emit(
+            { id: e.view as string, url: e.url as string, errorCode: e.errorCode as string },
+            { window: e.window as number },
+          );
+        }),
+      gone: (emit, ctx) =>
+        ctx.onNativeEvent("externalView", (e) => {
+          if (e.event !== "gone") return;
+          emit(
+            { id: e.view as string, reason: e.reason as string, restarts: e.restarts as number },
+            { window: e.window as number },
+          );
+        }),
+      consoleMessage: (emit, ctx) => {
+        const cap = createConsoleCap();
+        return ctx.onNativeEvent("externalView", (e) => {
+          if (e.event !== "cdp") return;
+          const view = e.view as string;
+          const min = levels.get(view);
+          const message = min ? consoleMessageOf(e.method as string, e.params) : null;
+          if (!min || !message || LEVELS.indexOf(message.level) < LEVELS.indexOf(min)) return;
+          const { pass, dropped } = cap(view);
+          if (!pass) return;
+          emit({ id: view, ...message, ...(dropped ? { dropped } : {}) }, { window: e.window as number });
+        });
+      },
+    },
+  });
+}
+
+export default createDesktopExternalView();