@akanjs/devkit 3.0.0-beta.9 → 3.0.0

package/mobile/nativeApp.ts

@@ -0,0 +1,454 @@
+import path from "node:path";
+import type { AkanNativeConfig } from "@akanjs/native/config";
+import type { NativeEnv } from "akanjs";
+import type { App } from "../commandDecorators";
+import { Executor } from "../executors";
+import { type DesktopArch, DesktopBin } from "./desktopBin";
+import type { DesktopServerBundle } from "./desktopServerStage";
+import {
+  type DesktopPlatform,
+  type MobilePlatform,
+  type NativePlatform,
+  type ResolvedMobileTarget,
+  targetHtmlFilename,
+} from "./mobileTarget";
+import { NativeApi, type NativeBuildApiModule } from "./nativeApi";
+import { NativeAppLine, type NativeAppLineRead } from "./nativeAppLine";
+import { NativeConfig } from "./nativeConfig";
+import { NativePluginFolders } from "./nativePluginFolders";
+import { NativeWebDir } from "./nativeWebDir";
+
+type TaskOptions = Parameters<NativeBuildApiModule["build"]>[0];
+type DeviceSelector = NonNullable<Parameters<NativeBuildApiModule["run"]>[0]["device"]>;
+type ReleaseOptions = Parameters<NativeBuildApiModule["release"]>[0];
+type AndroidSigning = Extract<ReleaseOptions, { platform: "android" }>["signing"];
+
+export interface NativeRunOptions {
+  device?: DeviceSelector;
+  /** Narrows the iPhone signing to one Apple team. */
+  teamId?: string;
+}
+
+interface NativeDevBoot {
+  steps: string[];
+  lines: NativeAppLineRead[];
+}
+
+export interface NativeBuildOptions {
+  profile?: "debug" | "release";
+  /** The server a desktop app carries (the target's `desktop.server`), staged by DesktopServerStage. */
+  server?: DesktopServerBundle;
+  /** What a person downloads beside the app: a Windows NSIS setup program, a macOS dmg, a Linux AppImage. */
+  installer?: boolean;
+  /** The CPU the desktop app runs on, of the same OS; a macOS app is arm64 only. Default this computer's. */
+  arch?: DesktopArch;
+}
+
+export interface NativeDevOptions extends NativeRunOptions {
+  /** The akan dev server the gateway proxies. */
+  upstream: string;
+  lang: string;
+}
+
+/** One native target of an app on the native runtime (a phone, or this computer as a desktop app): where it builds,
+ * what it ships, and the calls into the API. */
+export class NativeApp {
+  readonly targetRoot: string;
+  readonly web: NativeWebDir;
+  //? A dev boot holds its steps and the app's first lines back: one line says it is up, all of it when it failed.
+  #boot: NativeDevBoot | null = null;
+
+  constructor(
+    readonly app: App,
+    readonly target: ResolvedMobileTarget,
+    readonly env?: NativeEnv,
+  ) {
+    this.targetRoot = path.join(app.cwdPath, ".akan", "native", target.name);
+    this.web = new NativeWebDir(path.join(this.targetRoot, "web"));
+  }
+
+  outDir(platform: NativePlatform) {
+    return path.join(this.targetRoot, "build", platform);
+  }
+
+  //? Apart from the builds: a desktop build empties its folder first, which would take a release and its installer.
+  devOutDir(platform: NativePlatform) {
+    return path.join(this.targetRoot, "dev", platform);
+  }
+
+  /** Where the app starts on `platform`: its platform section's `indexPath`, else the target's. */
+  indexPath(platform: NativePlatform) {
+    const { config } = this.target;
+    const section = platform === "ios" ? config.ios : platform === "android" ? config.android : config.desktop;
+    return section?.indexPath ?? config.indexPath;
+  }
+
+  /** The web root, from the production build the native commands run first. */
+  async assembleWeb(platform: NativePlatform) {
+    const dist = this.app.dist.cwdPath;
+    return await this.web.assemble(
+      { ...this.target.config, indexPath: this.indexPath(platform) },
+      {
+        html: path.join(dist, "csr", targetHtmlFilename(this.target.config)),
+        publicDir: path.join(dist, "public"),
+        fontsDir: path.join(dist, ".akan", "artifact", "fonts"),
+      },
+    );
+  }
+
+  /** Where a desktop build stages the executables it carries (akan.config.ts `bin`). */
+  get binDir() {
+    return path.join(this.targetRoot, "bin");
+  }
+
+  /** `stageBin: false` for a config nothing is built from (the update key's): staging downloads the `bin` sources. */
+  async config({
+    server,
+    platform,
+    stageBin = true,
+    arch,
+  }: {
+    server?: DesktopServerBundle;
+    platform: NativePlatform;
+    stageBin?: boolean;
+    arch?: DesktopArch;
+  }) {
+    const [appConfig, plugins, nativePlugins] = await Promise.all([
+      this.app.getConfig(),
+      this.app.collectPlugins(),
+      NativePluginFolders.of(this.app),
+    ]);
+    const desktop = platform === "macos" || platform === "windows" || platform === "linux";
+    const carried = desktop && stageBin ? await new DesktopBin(this.app, appConfig).stage(this.binDir, arch) : [];
+    return NativeConfig.build({
+      appPath: this.app.cwdPath,
+      target: this.target.config,
+      webDir: this.web.dir,
+      contributions: plugins.flatMap((plugin) => (plugin.native ? [plugin.native] : [])),
+      locales: appConfig.i18n.locales,
+      env: this.env,
+      platform,
+      nativePlugins,
+      ...(server ? { desktopServer: server } : {}),
+      ...(carried.length ? { desktopBin: this.binDir } : {}),
+    });
+  }
+
+  /** The API and the config it is about to build, refused here when the runtime would refuse it later. */
+  async prepare(platform: NativePlatform, server?: DesktopServerBundle, arch?: DesktopArch) {
+    const [api, { config, warnings }] = await Promise.all([
+      NativeApi.load(this.app.cwdPath),
+      this.config({ platform, ...(server ? { server } : {}), ...(arch ? { arch } : {}) }),
+    ]);
+    for (const warning of warnings) this.app.logger.warn(warning);
+    this.#assertValid(api, config);
+    return { api, config };
+  }
+
+  #assertValid(api: NativeBuildApiModule, config: AkanNativeConfig) {
+    const problems = api.validateConfig(config, { appDir: this.app.cwdPath });
+    if (problems.length)
+      throw new Error(
+        `Native target '${this.target.name}' makes an invalid native config:\n- ${problems.join("\n- ")}`,
+      );
+  }
+
+  //? The app's own output: its console (mirrored by a dev build), the simulator log stream or logcat.
+  #appLine = (line: string) => {
+    const read = NativeAppLine.read(line, { verbose: Executor.verbose });
+    if (this.#boot) this.#boot.lines.push(read);
+    else this.app.logger[read.level](read.message);
+  };
+
+  //* `AKAN_PUBLIC_*` is already inlined into the CSR bundle, so the runtime reads no .env file of its own.
+  #task(platform: NativePlatform, config: AkanNativeConfig, outDir = this.outDir(platform)): TaskOptions {
+    return {
+      appDir: this.app.cwdPath,
+      config,
+      platform,
+      outDir,
+      envFiles: false,
+      skipWebBuild: true,
+      log: (event) => {
+        if (event.level === "error") this.app.logger.error(event.message);
+        else if (event.level === "warn") this.app.logger.warn(event.message);
+        else if (this.#boot) this.#boot.steps.push(event.message);
+        else if (event.level === "tool") this.app.logger.verbose(event.message);
+        else this.app.logger.info(event.message);
+      },
+    };
+  }
+
+  async build(
+    platform: NativePlatform,
+    { profile = "release", server, installer = false, arch }: NativeBuildOptions = {},
+  ) {
+    NativeApp.#assertServerPlatform(platform, server);
+    NativeApp.assertInstaller(platform, installer);
+    await this.assembleWeb(platform);
+    const { api, config } = await this.prepare(platform, server, arch);
+    return await api.build({
+      ...this.#task(platform, config),
+      profile,
+      ...(arch ? { arch } : {}),
+      ...(platform === "windows"
+        ? {
+            windows: {
+              ...(installer ? { installer } : {}),
+              ...(profile === "release" ? NativeApp.#windowsSigning(api) : {}),
+            },
+          }
+        : {}),
+      ...(platform === "macos"
+        ? {
+            macos: {
+              ...(profile === "release" ? api.macosDistributionFromEnv(process.env) : {}),
+              ...(installer ? { dmg: true } : {}),
+            },
+          }
+        : {}),
+      ...(platform === "linux" && installer ? { linux: { appImage: true } } : {}),
+    });
+  }
+
+  async run(
+    platform: NativePlatform,
+    { device, teamId, profile = "debug", server }: NativeRunOptions & NativeBuildOptions = {},
+  ) {
+    NativeApp.#assertServerPlatform(platform, server);
+    await this.assembleWeb(platform);
+    const { api, config } = await this.prepare(platform, server);
+    return await api.run({
+      ...this.#task(platform, config),
+      profile,
+      onLine: this.#appLine,
+      ...(device ? { device } : {}),
+      ...(teamId ? { ios: { signing: { teamId } } } : {}),
+    });
+  }
+
+  //* The gateway serves the page, its HMR socket and its API calls on the app origin. The dev server's own port is
+  //* reversed too: a browser the app hands off to (auth-session) opens it directly (baseEnv getServerOrigin).
+  async dev(platform: NativePlatform, { upstream, lang, device, teamId }: NativeDevOptions) {
+    const startedAt = performance.now();
+    const boot: NativeDevBoot = { steps: [], lines: [] };
+    this.#boot = boot;
+    try {
+      //? The runtime bundles an index.html it finds here as the dev build's page, and a release build leaves one.
+      await this.web.clear();
+      const [{ api, config }, { api: routes }] = await Promise.all([this.prepare(platform), this.app.getConfig()]);
+      const session = await api.dev({
+        ...this.#task(platform, config, this.devOutDir(platform)),
+        upstream,
+        hmrPath: "/_akan/hmr",
+        //? A dev page calls its own origin (akanjs baseEnv), so the gateway relays the socket it opens for the API too.
+        wsPaths: [`${routes.prefix}${routes.websocketPrefix}`],
+        reversePorts: [Number(new URL(upstream).port)],
+        onLine: this.#appLine,
+        startPath: this.startPath(lang, platform),
+        ...(device ? { device } : {}),
+        ...(teamId ? { ios: { signing: { teamId } } } : {}),
+      });
+      this.#boot = null;
+      this.app.logger.info(this.readyLine(platform, { upstream, device: session.device, startedAt }));
+      for (const step of [...boot.steps, `pages through ${session.gateway}`]) this.app.logger.debug(step);
+      for (const line of boot.lines) this.app.logger[line.level](line.message);
+      return session;
+    } catch (error) {
+      this.#boot = null;
+      for (const step of boot.steps) this.app.logger.info(step);
+      for (const line of boot.lines) this.app.logger[line.level === "debug" ? "info" : line.level](line.message);
+      throw error;
+    }
+  }
+
+  /** What a dev boot that came up says, and all it says: `cmdc ios ready · iPhone 16 · http://localhost:8283 · 12.4s`. */
+  readyLine(
+    platform: NativePlatform,
+    { upstream, device, startedAt }: { upstream: string; device?: { name: string }; startedAt: number },
+  ) {
+    const label = platform === "ios" || platform === "android" ? platform : "desktop";
+    const target = this.target.name === "default" ? "" : `/${this.target.name}`;
+    const seconds = ((performance.now() - startedAt) / 1000).toFixed(1);
+    return [`${this.app.name}${target} ${label} ready`, ...(device ? [device.name] : []), upstream, `${seconds}s`].join(
+      " · ",
+    );
+  }
+
+  async releaseIos({ teamId, adHoc = false }: { teamId?: string; adHoc?: boolean } = {}) {
+    await this.assembleWeb("ios");
+    const { api, config } = await this.prepare("ios");
+    return await api.release({
+      ...this.#task("ios", config),
+      platform: "ios",
+      signing: { ...(teamId ? { teamId } : {}), ...(adHoc ? { distribution: "ad-hoc" as const } : {}) },
+    });
+  }
+
+  /** Where publishUpdate writes: upload this folder as the target's updates.url. */
+  get updatesDir() {
+    return path.join(this.targetRoot, "updates");
+  }
+
+  /** A signed release installed apps take through the updates plugin, from a release build of this bundle. */
+  async publishUpdate(
+    platform: NativePlatform,
+    { channel, server }: { channel?: string; server?: DesktopServerBundle } = {},
+  ) {
+    NativeApp.#assertServerPlatform(platform, server);
+    this.#assertUpdates();
+    await this.assembleWeb(platform);
+    const { api, config } = await this.prepare(platform, server);
+    return await api.publishUpdate({
+      ...this.#task(platform, config),
+      platform,
+      out: this.updatesDir,
+      ...(channel ? { channel } : {}),
+      //? The updater keeps the installed app's signature, so a release is signed as the downloaded app was.
+      ...(platform === "macos" ? { macos: api.macosDistributionFromEnv(process.env) } : {}),
+      ...(platform === "windows" ? { windows: NativeApp.#windowsSigning(api) } : {}),
+    });
+  }
+
+  /**
+   * What publishing refuses once the release is built: no updates settings, an invalid config, no signing key or
+   * another app's, and a desktop release whose server presence is not its channel's previous release's.
+   */
+  async assertPublishable(
+    platform: NativePlatform,
+    { channel, server = false }: { channel?: string; server?: boolean } = {},
+  ) {
+    this.#assertUpdates();
+    const [api, { config }] = await Promise.all([
+      NativeApi.load(this.app.cwdPath),
+      this.config({ platform, stageBin: false }),
+    ]);
+    this.#assertValid(api, config);
+    try {
+      api.checkPublishUpdate({
+        appDir: this.app.cwdPath,
+        config,
+        platform,
+        out: this.updatesDir,
+        server,
+        ...(channel ? { channel } : {}),
+      });
+    } catch (error) {
+      throw new Error(
+        `Native target '${this.target.name}': ${error instanceof Error ? error.message : String(error)}`,
+        {
+          cause: error,
+        },
+      );
+    }
+  }
+
+  #assertUpdates() {
+    if (!this.target.config.updates)
+      throw new Error(
+        `Native target '${this.target.name}' has no updates: add native.updates: { url, publicKey } to akan.config.ts; \`akan update-keygen ${this.app.name}\` prints the key.`,
+      );
+  }
+
+  /** The key update releases of this target's app id on `platform` are signed with: made once, then read. */
+  async updateKeygen(platform: NativePlatform) {
+    const [api, { config }] = await Promise.all([
+      NativeApi.load(this.app.cwdPath),
+      this.config({ platform, stageBin: false }),
+    ]);
+    return api.updateKeygen({ config });
+  }
+
+  async releaseAndroid({ formats = ["aab"] }: { formats?: ("aab" | "apk")[] } = {}) {
+    const signing = NativeApp.androidSigning();
+    await this.assembleWeb("android");
+    const { api, config } = await this.prepare("android");
+    return await api.release({ ...this.#task("android", config), platform: "android", signing, formats });
+  }
+
+  /** An unsigned OTA update of this target's web bundle for `platform`, and the channel its binary follows. */
+  async packUpdate(platform: MobilePlatform, { out }: { out?: string } = {}) {
+    await this.assembleWeb(platform);
+    const { api, config } = await this.prepare(platform);
+    if (!config.updates)
+      throw new Error(
+        `Native target '${this.target.name}' takes no updates: add native.updates: { url, publicKey } to akan.config.ts first.`,
+      );
+    const packed = await api.packUpdate({
+      ...this.#task(platform, config),
+      platform,
+      out: out ?? path.join(this.targetRoot, "updates", platform),
+    });
+    return { ...packed, channel: config.updates.channel ?? "production" };
+  }
+
+  static async compareBundles(appDir: string, shipped: string, bundle: string) {
+    return (await NativeApi.load(appDir)).compareBundles(shipped, bundle);
+  }
+
+  //* The names the Gradle build read, so a CI that already holds these secrets keeps working.
+  static androidSigning(env: Record<string, string | undefined> = process.env): AndroidSigning {
+    const keystore = env.MYAPP_RELEASE_STORE_FILE;
+    const storePassword = env.MYAPP_RELEASE_STORE_PASSWORD;
+    const alias = env.MYAPP_RELEASE_KEY_ALIAS;
+    const keyPassword = env.MYAPP_RELEASE_KEY_PASSWORD;
+    if (!keystore || !storePassword || !alias) {
+      const missing = Object.entries({
+        MYAPP_RELEASE_STORE_FILE: keystore,
+        MYAPP_RELEASE_STORE_PASSWORD: storePassword,
+        MYAPP_RELEASE_KEY_ALIAS: alias,
+      }).flatMap(([key, value]) => (value ? [] : [key]));
+      throw new Error(
+        `An Android release is signed with the upload key; set ${missing.join(", ")} in the environment.`,
+      );
+    }
+    return { keystore, storePassword, alias, ...(keyPassword ? { keyPassword } : {}) };
+  }
+
+  /** The first page of a dev build, the target's home as a release bundle opens it; the dev server answers the CSR
+   * shell only for `?csr=true`. */
+  startPath(lang: string, platform: NativePlatform) {
+    const basePath = this.target.config.basePath?.replace(/^\/+|\/+$/g, "");
+    const indexPath = this.indexPath(platform);
+    const params = new URLSearchParams({ csr: "true", akanMobileTarget: this.target.name });
+    if (basePath) params.set("akanMobileBasePath", basePath);
+    if (indexPath) params.set("akanMobileIndexPath", indexPath);
+    const home = [lang, basePath, indexPath]
+      .flatMap((part) => (part ?? "").split("/"))
+      .filter((segment) => segment.length > 0);
+    return `/${home.join("/")}?${params}`;
+  }
+
+  static #windowsSigning(api: NativeBuildApiModule) {
+    const signing = api.windowsSigningFromEnv(process.env);
+    return signing ? { signing } : {};
+  }
+
+  //* `installer` is the file a person downloads: a setup program on Windows, a disk image on macOS, an AppImage on Linux.
+  static assertInstaller(platform: NativePlatform, installer: boolean) {
+    if (installer && (platform === "ios" || platform === "android"))
+      throw new Error(`An installer is built for a desktop app (Windows, macOS, Linux), not for ${platform}.`);
+  }
+
+  //? A phone runs no Bun, so only a desktop app can carry the server.
+  static #assertServerPlatform(platform: NativePlatform, server: DesktopServerBundle | undefined) {
+    if (server && (platform === "ios" || platform === "android"))
+      throw new Error(`Only a desktop app carries its server; ${platform} cannot run one.`);
+  }
+
+  //* A desktop app builds only on its own OS, so the platform is this computer's.
+  static desktopPlatform(host: NodeJS.Platform = process.platform): DesktopPlatform {
+    if (host === "darwin") return "macos";
+    if (host === "win32") return "windows";
+    if (host === "linux") return "linux";
+    throw new Error(`A desktop app builds on macOS, Windows or Linux, not on ${host}.`);
+  }
+
+  static async devices(appDir: string, platform: MobilePlatform) {
+    return await (await NativeApi.load(appDir)).devices({ platform });
+  }
+
+  static async doctor(appDir: string, platforms: NativePlatform[]) {
+    return await (await NativeApi.load(appDir)).doctor({ platforms });
+  }
+}

package/mobile/nativeAppLine.test.ts

@@ -0,0 +1,69 @@
+import { describe, expect, test } from "bun:test";
+import { NativeAppLine } from "./nativeAppLine";
+
+describe("NativeAppLine", () => {
+  test("a page logger line keeps its level and its logger's name", () => {
+    expect(NativeAppLine.read("[page warn] [WsClient] WebSocket message process failed")).toEqual({
+      level: "warn",
+      message: "[page:WsClient] WebSocket message process failed",
+    });
+  });
+
+  test("a bare console call keeps its level, `log` reading as info", () => {
+    expect(NativeAppLine.read("[page log] hello")).toEqual({ level: "info", message: "[page] hello" });
+    expect(NativeAppLine.read("[page debug] [akan:frame:x:1] csr.render {}")).toEqual({
+      level: "debug",
+      message: "[page:akan:frame:x:1] csr.render {}",
+    });
+  });
+
+  test("a continuation line follows its message's level without a prefix of its own", () => {
+    expect(NativeAppLine.read("[page+ error]     at run (app.js:1:2)")).toEqual({
+      level: "error",
+      message: "      at run (app.js:1:2)",
+    });
+  });
+
+  test("a carried server's line keeps the level its logger wrote, and one without a level stays visible", () => {
+    const line = "[server] [minimal] 81 - 09/30/2026, 12:30:06 PM   ERROR  boom +2ms";
+    expect(NativeAppLine.read(line)).toEqual({ level: "error", message: line });
+    expect(NativeAppLine.read("[server] \u001b[32m[minimal] 81 -\u001b[39m WARN  slow").level).toBe("warn");
+    expect(NativeAppLine.read("[server]     at run (main.js:1:2)").level).toBe("info");
+  });
+
+  test("a second window is named, the first is not", () => {
+    expect(NativeAppLine.read("[page#2 info] [App] ready")).toEqual({ level: "info", message: "[page#2:App] ready" });
+  });
+
+  test("logcat lines read by tag and priority", () => {
+    expect(NativeAppLine.read("W/AkanNativeConsole( 1234): [WsClient] failed")).toEqual({
+      level: "warn",
+      message: "[page:WsClient] failed",
+    });
+    expect(NativeAppLine.read("E/AndroidRuntime( 1234): FATAL EXCEPTION: main")).toEqual({
+      level: "error",
+      message: "[AndroidRuntime] FATAL EXCEPTION: main",
+    });
+    expect(
+      NativeAppLine.read("I/AkanNative( 1234): pages from http://10.0.2.2:5000 (akan-native dev --hmr)").level,
+    ).toBe("debug");
+  });
+
+  test("the host's own lines stay visible but for where its pages come from", () => {
+    expect(NativeAppLine.read("[akan-native] opened in the browser: https://x.test")).toEqual({
+      level: "info",
+      message: "[akan-native] opened in the browser: https://x.test",
+    });
+    expect(
+      NativeAppLine.read("[akan-native native] pages from http://127.0.0.1:6000 (akan-native dev --hmr)").level,
+    ).toBe("debug");
+  });
+
+  test("a line no page or host wrote is kept for debug, or for info when verbose", () => {
+    expect(NativeAppLine.read("WebContent[123] Could not signal service")).toEqual({
+      level: "debug",
+      message: "WebContent[123] Could not signal service",
+    });
+    expect(NativeAppLine.read("WebContent[123] Could not signal service", { verbose: true }).level).toBe("info");
+  });
+});

package/mobile/nativeAppLine.ts

@@ -0,0 +1,71 @@
+import type { LogLevel } from "akanjs/common";
+
+export interface NativeAppLineRead {
+  level: LogLevel;
+  message: string;
+}
+
+//* A line a native dev build prints — the page console its host mirrors, the simulator's console, logcat — read back
+//* at the level the page logged it, so the terminal shows it once, stamped by the app's own logger.
+export class NativeAppLine {
+  //? The host's grammar (desktop host.ts, iOS AkanNativeShell.swift): `[page<+><#window> <level>] text`, where `+`
+  //? marks a continuation line of a multi-line message and `#n` any window but the first.
+  static readonly #page = /^\[page(\+)?(?:#(\d+))? (trace|verbose|debug|log|info|warn|error)\] ?(.*)$/;
+  static readonly #logcat = /^([VDIWEFA])\/([^(]+?)\s*\(\s*\d+\):\s?(.*)$/;
+  static readonly #named = /^\[([^\]\s]+)\] ([\s\S]*)$/;
+  //? A server the desktop app carries (host server.ts): `[server] <its own log line>`, whose level word the akan logger
+  //? wrote; a line without one (a crash's stack) is still the app's and stays visible.
+  static readonly #server = /^\[server\] /;
+  static readonly #serverLevel = /\b(TRACE|VERBOSE|DEBUG|INFO|WARN|ERROR)\b/;
+  static readonly #logcatLevels: { [priority: string]: LogLevel } = {
+    V: "verbose",
+    D: "debug",
+    I: "info",
+    W: "warn",
+    E: "error",
+    F: "error",
+    A: "error",
+  };
+
+  /** `verbose` keeps the lines no page or host wrote (WebKit, the simulator) at info instead of debug. */
+  static read(line: string, { verbose = false }: { verbose?: boolean } = {}): NativeAppLineRead {
+    const logcat = NativeAppLine.#logcat.exec(line);
+    if (logcat) {
+      const [, priority = "I", tag = "", text = ""] = logcat;
+      const level = NativeAppLine.#logcatLevels[priority] ?? "info";
+      if (tag === "AkanNativeConsole") return NativeAppLine.#pageLine(level, text, { continuation: false });
+      if (tag === "AkanNative") return NativeAppLine.#hostLine(`[akan-native] ${text}`, level);
+      return { level, message: `[${tag}] ${text}` };
+    }
+    const page = NativeAppLine.#page.exec(line);
+    if (page) {
+      const [, continuation, window, level = "info", text = ""] = page;
+      return NativeAppLine.#pageLine(level === "log" ? "info" : (level as LogLevel), text, {
+        continuation: continuation === "+",
+        window,
+      });
+    }
+    if (line.startsWith("[akan-native")) return NativeAppLine.#hostLine(line, "info");
+    if (NativeAppLine.#server.test(line)) {
+      const word = NativeAppLine.#serverLevel.exec(Bun.stripANSI(line))?.[1];
+      return { level: word ? (word.toLowerCase() as LogLevel) : "info", message: line };
+    }
+    return { level: verbose ? "info" : "debug", message: line };
+  }
+
+  static #pageLine(
+    level: LogLevel,
+    text: string,
+    { continuation, window }: { continuation: boolean; window?: string },
+  ): NativeAppLineRead {
+    if (continuation) return { level, message: `  ${text}` };
+    const named = NativeAppLine.#named.exec(text);
+    const scope = `page${window ? `#${window}` : ""}${named ? `:${named[1]}` : ""}`;
+    return { level, message: `[${scope}] ${named ? named[2] : text}` };
+  }
+
+  //? The host's own lines are about the host, not the app: where its pages come from is boot detail.
+  static #hostLine(line: string, level: LogLevel): NativeAppLineRead {
+    return { level: /\bpages from\b/.test(line) ? "debug" : level, message: line };
+  }
+}