akanjs 3.0.2 → 3.1.0-rc.0

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();

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

@@ -0,0 +1,106 @@
+import { definePlugin, type FileRef } from "../../../packages/core/src/index.ts";
+
+/**
+ * A third-party page shown first-party inside an app window, for signage: a scoreboard, a menu board. The view is a
+ * webview of its own laid over the window's page, which cannot draw over it — hide the view to show the page.
+ *
+ * Nothing of the app reaches the view: no bridge, no init script of the app, no app scheme. It keeps its own browser
+ * profile (cookies, storage, cache), so `clearData` never touches the app's, and it navigates only to `allowOrigins`;
+ * popups, downloads and device permissions are refused. Listing the plugin in `native.plugins` is what lets an app
+ * open one.
+ *
+ * Windows has every method. macOS (14 or later, for its separate profile) has all but `sendKey`, `setMuted` and
+ * `capture`, and sends no `loadFailed` or `consoleMessage`. Linux, iOS and Android: UNSUPPORTED.
+ */
+export type ExternalViewBounds = "fill" | { x: number; y: number; width: number; height: number };
+
+export type ExternalViewConsoleLevel = "debug" | "info" | "warn" | "error";
+
+export interface ExternalViewOpenOptions {
+  /** Names the view in every later call: letters, digits, `-` and `_`. */
+  id: string;
+  url: string;
+  /** The origins it may navigate to (`https://host[:port]`); `url` must be on one. */
+  allowOrigins: string[];
+  /** Logical pixels in the window's content area; "fill" (default) follows the window's size. */
+  bounds?: ExternalViewBounds;
+  /** Runs at the start of every top document, before the page's own scripts; read what it keeps with `evaluate`. */
+  initScript?: string;
+  muted?: boolean;
+  /** Media plays with sound without a gesture first (default true): nobody taps a signage screen. */
+  autoplay?: boolean;
+  /** Sends the page's console as `consoleMessage` from this level up (`true` is "warn"); off by default. */
+  console?: boolean | ExternalViewConsoleLevel;
+  /** The window it is laid over; the calling page's window by default. */
+  window?: number;
+}
+
+export interface ExternalViewState {
+  id: string;
+  window: number;
+  url: string;
+  visible: boolean;
+  /** Times its web process ended and the view loaded its page again. */
+  restarts: number;
+}
+
+export interface ExternalViewApi {
+  /** Opens the view, or brings an open one with this id to these options (a page that mounts again finds it). */
+  open(args: ExternalViewOpenOptions): Promise<ExternalViewState>;
+  /** Rejects NOT_ALLOWED for a URL on none of its `allowOrigins`. */
+  navigate(args: { id: string; url: string }): Promise<void>;
+  reload(args: { id: string }): Promise<void>;
+  close(args: { id: string }): Promise<void>;
+  list(): Promise<ExternalViewState[]>;
+  setVisible(args: { id: string; visible: boolean }): Promise<void>;
+  setBounds(args: { id: string; bounds: ExternalViewBounds }): Promise<void>;
+  /** The script's completion value; a promise is not awaited. An exception answers `null`: catch it in the script. */
+  evaluate(args: { id: string; script: string }): Promise<{ value: unknown }>;
+  /** A trusted key press (`{ key: "z", code: "KeyZ" }`), whether or not the view has the focus. Windows only. */
+  sendKey(args: { id: string; key: string; code: string }): Promise<void>;
+  /** The view's own sound only; the system volume is the volume plugin's. Windows only. */
+  setMuted(args: { id: string; muted: boolean }): Promise<void>;
+  /** Clears the view's cookies, storage and cache; the app's own stay. */
+  clearData(args: { id: string }): Promise<void>;
+  /** A PNG of the view's content, not of the screen. Windows only. */
+  capture(args: { id: string }): Promise<FileRef & { width?: number; height?: number }>;
+}
+
+export interface ExternalViewEvents {
+  load: { id: string; state: "started" | "finished"; url: string };
+  /**
+   * A navigation that failed. `errorCode`: `http<status>` for a server's 4xx or 5xx page, else WebView2's own
+   * (`hostNameNotResolved`, `cannotConnect`, `timeout`, `certificate`, `disconnected`, …; a refused connection is
+   * `unknown`). Windows only.
+   */
+  loadFailed: { id: string; url: string; errorCode: string };
+  /** Its web process ended; the view loads its page again by itself, sooner the first times. */
+  gone: { id: string; reason: string; restarts: number };
+  /** `dropped`: messages left out before this one, past the rate cap. Windows only. */
+  consoleMessage: {
+    id: string;
+    level: ExternalViewConsoleLevel;
+    text: string;
+    url?: string;
+    line?: number;
+    dropped?: number;
+  };
+}
+
+export const externalView = definePlugin<ExternalViewApi, ExternalViewEvents>("external-view", {
+  methods: [
+    "open",
+    "navigate",
+    "reload",
+    "close",
+    "list",
+    "setVisible",
+    "setBounds",
+    "evaluate",
+    "sendKey",
+    "setMuted",
+    "clearData",
+    "capture",
+  ],
+  events: ["load", "loadFailed", "gone", "consoleMessage"],
+});