@akanjs/devkit 3.0.0-beta.26 → 3.0.0-beta.28

package/mobile/mobileTarget.test.ts

@@ -1,7 +1,14 @@
 import { describe, expect, test } from "bun:test";
 import type { AkanMobileTargetConfig } from "../akanConfig";
 import type { App } from "../commandDecorators";
-import { getMobileTargetChoices, resolveMobilePath, resolveMobileTargets, targetHtmlFilename } from "./mobileTarget";
+import {
+  appIdsOf,
+  getMobileTargetChoices,
+  resolveAppId,
+  resolveMobilePath,
+  resolveMobileTargets,
+  targetHtmlFilename,
+} from "./mobileTarget";
 
 const target = {
   name: "akanjs",
@@ -19,6 +26,17 @@ describe("mobile target helpers", () => {
     expect(resolveMobilePath({ ...target, basePath: undefined }, "/order/123")).toBe("/order/123");
   });
 
+  test("an app id per platform falls back to default, and a platform with neither is refused", () => {
+    const appId = { default: "com.yeollege", ios: "com.puffinplanet.yeollege" };
+    expect(resolveAppId(appId, "ios")).toBe("com.puffinplanet.yeollege");
+    expect(resolveAppId(appId, "android")).toBe("com.yeollege");
+    expect(resolveAppId("com.one.app", "macos")).toBe("com.one.app");
+    expect(() => resolveAppId({ ios: "com.puffinplanet.yeollege" }, "android")).toThrow(
+      "mobile.appId names no id for android",
+    );
+    expect(appIdsOf(appId)).toEqual(["com.yeollege", "com.puffinplanet.yeollege"]);
+  });
+
   test("selects the self-contained html file for a target", () => {
     expect(targetHtmlFilename(target)).toBe("akanjs.html");
     expect(targetHtmlFilename({ ...target, basePath: undefined })).toBe("index.html");
@@ -36,6 +54,37 @@ describe("mobile target helpers", () => {
     await expect(resolveMobileTargets(app, undefined)).resolves.toEqual([{ name: "akanjs", config: target }]);
   });
 
+  test("a target naming no basePath is a template in an app with basePaths, never a page of its own", async () => {
+    const template = { ...target, name: "default", basePath: undefined };
+    const appWith = (basePaths: string[]) =>
+      ({
+        name: "angelo",
+        getConfig: async () => ({ basePaths: new Set(basePaths), mobile: { targets: { default: template } } }),
+      }) as unknown as App;
+
+    const two = appWith(["soft", "office"]);
+    await expect(getMobileTargetChoices(two)).resolves.toEqual(["soft", "office"]);
+    await expect(resolveMobileTargets(two, undefined)).rejects.toThrow(
+      "Multiple mobile targets found for angelo. Pass --target <soft|office|all>.",
+    );
+    await expect(resolveMobileTargets(two, "office")).resolves.toEqual([
+      { name: "office", config: { ...template, name: "office", basePath: "office" } },
+    ]);
+    await expect(resolveMobileTargets(two, "all")).resolves.toEqual([
+      { name: "soft", config: { ...template, name: "soft", basePath: "soft" } },
+      { name: "office", config: { ...template, name: "office", basePath: "office" } },
+    ]);
+
+    const one = appWith(["soft"]);
+    const soft = [{ name: "soft", config: { ...template, name: "soft", basePath: "soft" } }];
+    await expect(resolveMobileTargets(one, undefined)).resolves.toEqual(soft);
+    await expect(resolveMobileTargets(one, "all")).resolves.toEqual(soft);
+
+    await expect(resolveMobileTargets(appWith([]), undefined)).resolves.toEqual([
+      { name: "default", config: template },
+    ]);
+  });
+
   test("resolves a route base path onto the default mobile target config", async () => {
     const app = {
       getConfig: async () => ({

package/mobile/mobileTarget.ts

@@ -1,4 +1,5 @@
-import type { AkanMobileTargetConfig, MobileEnv } from "../akanConfig";
+import type { AkanMobileAppId } from "akanjs";
+import type { AkanAppConfig, AkanMobileTargetConfig, MobileEnv } from "../akanConfig";
 import type { App } from "../commandDecorators";
 
 export type MobilePlatform = "ios" | "android";
@@ -20,10 +21,15 @@ export const getMobileTargets = async (app: App): Promise<ResolvedMobileTarget[]
   return Object.entries(config.mobile.targets).map(([name, target]) => ({ name, config: target }));
 };
 
+//* An app with basePaths builds a CSR page per basePath and none at its root, so a target naming no basePath opens
+//* nothing on its own there; it is the template each basePath's target is made from.
+const isTemplateOnly = ({ basePaths, mobile }: Pick<AkanAppConfig, "basePaths" | "mobile">) =>
+  basePaths.size > 0 && Object.values(mobile.targets).every((target) => !target.basePath);
+
 export const getMobileTargetChoices = async (app: App): Promise<string[]> => {
   const config = await app.getConfig();
   const targetNames = Object.keys(config.mobile.targets);
-  if (targetNames.length > 0) return targetNames;
+  if (targetNames.length > 0 && !isTemplateOnly(config)) return targetNames;
   return [...config.basePaths];
 };
 
@@ -51,7 +57,7 @@ export const resolveMobileTargets = async (
   const config = await app.getConfig();
   const targets = await getMobileTargets(app);
   if (targets.length === 0) throw new Error(`No mobile targets configured for ${app.name}`);
-  if (!selection && targets.length === 1) return targets;
+  if (!selection && targets.length === 1 && !isTemplateOnly(config)) return targets;
   if (!selection) {
     const choices = await getMobileTargetChoices(app);
     if (choices.length === 1) return resolveMobileTargets(app, choices[0]);
@@ -60,7 +66,7 @@ export const resolveMobileTargets = async (
   if (selection === "all") {
     if (Object.keys(config.mobile.targets).length > 1) return targets;
     const basePaths = [...config.basePaths];
-    if (basePaths.length > 1) {
+    if (basePaths.length > 1 || isTemplateOnly(config)) {
       return basePaths.flatMap((basePath) => {
         const resolved = resolveMobileTargetByBasePath(targets, basePath);
         return resolved ? [resolved] : [];
@@ -76,6 +82,16 @@ export const resolveMobileTargets = async (
   throw new Error(`Mobile target '${selection}' was not found. Available: ${choices.join(", ")}`);
 };
 
+export const resolveAppId = (appId: AkanMobileAppId, platform: NativePlatform): string => {
+  if (typeof appId === "string") return appId;
+  const id = appId[platform] ?? appId.default;
+  if (!id) throw new Error(`mobile.appId names no id for ${platform}; give it ${platform} or default.`);
+  return id;
+};
+
+export const appIdsOf = (appId: AkanMobileAppId): string[] =>
+  typeof appId === "string" ? [appId] : Object.values(appId).filter((id): id is string => !!id);
+
 export const resolveMobilePath = (target: AkanMobileTargetConfig, pathname: string) => {
   const basePath = trimSlashes(target.basePath ?? "");
   const normalizedPath = `/${pathname.replace(/^\/+/, "")}`;

package/mobile/nativeApp.test.ts

@@ -22,7 +22,10 @@ const appDir = "/repo/apps/portal";
 
 const fakeApp = (plugins: AkanPlugin[] = []) =>
   ({
+    name: "portal",
     cwdPath: appDir,
+    workspace: { workspaceRoot: "/repo" },
+    getScanInfo: () => ({ getLibs: () => [] }),
     dist: { cwdPath: "/repo/dist/apps/portal" },
     getConfig: async () => ({ i18n: { locales: ["en", "ko"] }, api: { prefix: "/api", websocketPrefix: "/ws" } }),
     collectPlugins: async () => plugins,
@@ -38,6 +41,21 @@ describe("NativeApp", () => {
     expect(admin.outDir("android")).toBe(path.join(appDir, ".akan/mobile/admin/native/android"));
   });
 
+  test("a dev boot that came up says so in one line: platform, device, dev server, time", () => {
+    const app = { ...fakeApp(), name: "portal" } as unknown as App;
+    const startedAt = performance.now() - 12_400;
+    expect(new NativeApp(app, target()).readyLine("macos", { upstream: "http://localhost:8283", startedAt })).toMatch(
+      /^portal desktop ready · http:\/\/localhost:8283 · 12\.\ds$/,
+    );
+    expect(
+      new NativeApp(app, target({ name: "admin" })).readyLine("ios", {
+        upstream: "http://localhost:8283",
+        device: { name: "iPhone 16" },
+        startedAt,
+      }),
+    ).toMatch(/^portal\/admin ios ready · iPhone 16 · http:\/\/localhost:8283 · 12\.\ds$/);
+  });
+
   test("opens a dev build on its target's home, the CSR shell under the locale", () => {
     expect(new NativeApp(fakeApp(), target({ indexPath: "/explore" })).startPath("en")).toBe(
       "/en/explore?csr=true&akanMobileTarget=default&akanMobileIndexPath=%2Fexplore",
@@ -54,13 +72,31 @@ describe("NativeApp", () => {
       target({ basePath: undefined, permissions: ["push"] }),
     );
 
-    const { config, warnings } = await app.config();
+    const { config, warnings } = await app.config({ platform: "android" });
 
     expect(warnings).toEqual([]);
     expect(config.plugins).toEqual([...NativeConfig.basePlugins, "push"]);
     expect(config.web.dir).toBe(path.join(appDir, ".akan/mobile/default/web"));
   });
 
+  test("a config nothing is built from (the update key's) stages no desktop bin", async () => {
+    const { config } = await new NativeApp(fakeApp(), target({ basePath: undefined })).config({
+      platform: "macos",
+      stageBin: false,
+    });
+    expect(config.desktop?.bin).toBeUndefined();
+  });
+
+  test("follows the updates channel of the backend env it is built for", async () => {
+    const updates = { url: "https://releases.example.com/portal", publicKey: `${"a".repeat(43)}=` };
+    const built = async (env?: "debug" | "main") =>
+      (await new NativeApp(fakeApp(), target({ basePath: undefined, updates }), env).config({ platform: "android" }))
+        .config.updates;
+
+    expect(await built("main")).toEqual({ ...updates, channel: "main" });
+    expect(await built("debug")).toEqual({ ...updates, channel: "debug" });
+  });
+
   test("a desktop app is this computer's platform", () => {
     expect(["darwin", "win32", "linux"].map((host) => NativeApp.desktopPlatform(host as NodeJS.Platform))).toEqual([
       "macos",

package/mobile/nativeApp.ts

@@ -1,7 +1,11 @@
 import { mkdir } from "node:fs/promises";
 import path from "node:path";
 import type { AkanNativeConfig } from "@akanjs/native/config";
+import type { MobileEnv } from "akanjs";
 import type { App } from "../commandDecorators";
+import { Executor } from "../executors";
+import { DesktopBin } from "./desktopBin";
+import type { DesktopServerBundle } from "./desktopServerStage";
 import {
   type DesktopPlatform,
   type MobilePlatform,
@@ -10,7 +14,9 @@ import {
   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];
@@ -24,6 +30,19 @@ export interface NativeRunOptions {
   teamId?: string;
 }
 
+interface NativeDevBoot {
+  steps: string[];
+  lines: NativeAppLineRead[];
+}
+
+export interface NativeBuildOptions {
+  profile?: "debug" | "release";
+  /** The server a desktop app carries (the target's `native.desktop.server`), staged by DesktopServerStage. */
+  server?: DesktopServerBundle;
+  /** Windows: an NSIS setup program beside the app folder. */
+  installer?: boolean;
+}
+
 export interface NativeDevOptions extends NativeRunOptions {
   /** The akan dev server the gateway proxies. */
   upstream: string;
@@ -35,10 +54,13 @@ export interface NativeDevOptions extends NativeRunOptions {
 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?: MobileEnv,
   ) {
     this.targetRoot = path.join(app.cwdPath, ".akan", "mobile", target.name);
     this.web = new NativeWebDir(path.join(this.targetRoot, "web"));
@@ -58,20 +80,48 @@ export class NativeApp {
     });
   }
 
-  async config() {
-    const [appConfig, plugins] = await Promise.all([this.app.getConfig(), this.app.collectPlugins()]);
+  /** 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,
+  }: {
+    server?: DesktopServerBundle;
+    platform: NativePlatform;
+    stageBin?: boolean;
+  }) {
+    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) : [];
     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() {
-    const [api, { config, warnings }] = await Promise.all([NativeApi.load(this.app.cwdPath), this.config()]);
+  async prepare(platform: NativePlatform, server?: DesktopServerBundle) {
+    const [api, { config, warnings }] = await Promise.all([
+      NativeApi.load(this.app.cwdPath),
+      this.config({ platform, ...(server ? { server } : {}) }),
+    ]);
     for (const warning of warnings) this.app.logger.warn(warning);
     const problems = api.validateConfig(config, { appDir: this.app.cwdPath });
     if (problems.length)
@@ -83,7 +133,9 @@ export class NativeApp {
 
   //? The app's own output: its console (mirrored by a dev build), the simulator log stream or logcat.
   #appLine = (line: string) => {
-    this.app.logger.info(`[${this.target.name}] ${line}`);
+    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.
@@ -98,24 +150,32 @@ export class NativeApp {
       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" }: { profile?: "debug" | "release" } = {}) {
+  async build(platform: NativePlatform, { profile = "release", server, installer = false }: NativeBuildOptions = {}) {
+    NativeApp.#assertServerPlatform(platform, server);
+    if (installer && platform !== "windows") throw new Error(`An installer is built for Windows, not for ${platform}.`);
     await this.assembleWeb();
-    const { api, config } = await this.prepare();
-    return await api.build({ ...this.#task(platform, config), profile });
+    const { api, config } = await this.prepare(platform, server);
+    return await api.build({
+      ...this.#task(platform, config),
+      profile,
+      ...(installer ? { windows: { installer } } : {}),
+    });
   }
 
   async run(
     platform: NativePlatform,
-    { device, teamId, profile = "debug" }: NativeRunOptions & { profile?: "debug" | "release" } = {},
+    { device, teamId, profile = "debug", server }: NativeRunOptions & NativeBuildOptions = {},
   ) {
+    NativeApp.#assertServerPlatform(platform, server);
     await this.assembleWeb();
-    const { api, config } = await this.prepare();
+    const { api, config } = await this.prepare(platform, server);
     return await api.run({
       ...this.#task(platform, config),
       profile,
@@ -125,27 +185,56 @@ export class NativeApp {
     });
   }
 
-  //* The gateway serves the page and its HMR socket on the app origin; API calls go to the dev server itself (baseEnv),
-  //* which an Android device reaches through the reversed port.
+  //* 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) {
-    await mkdir(this.web.dir, { recursive: true });
-    const [{ api, config }, { api: routes }] = await Promise.all([this.prepare(), this.app.getConfig()]);
-    return await api.dev({
-      ...this.#task(platform, config),
-      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}`],
-      onLine: this.#appLine,
-      startPath: this.startPath(lang),
-      ...(device ? { device } : {}),
-      ...(teamId ? { ios: { signing: { teamId } } } : {}),
-    });
+    const startedAt = performance.now();
+    const boot: NativeDevBoot = { steps: [], lines: [] };
+    this.#boot = boot;
+    try {
+      await mkdir(this.web.dir, { recursive: true });
+      const [{ api, config }, { api: routes }] = await Promise.all([this.prepare(platform), this.app.getConfig()]);
+      const session = await api.dev({
+        ...this.#task(platform, config),
+        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),
+        ...(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();
-    const { api, config } = await this.prepare();
+    const { api, config } = await this.prepare("ios");
     return await api.release({
       ...this.#task("ios", config),
       platform: "ios",
@@ -153,13 +242,67 @@ export class NativeApp {
     });
   }
 
+  /** 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);
+    if (!this.target.config.updates)
+      throw new Error(
+        `Mobile target '${this.target.name}' has no updates: { url, publicKey } in akan.config.ts; \`akan update-keygen ${this.app.name}\` prints the key.`,
+      );
+    await this.assembleWeb();
+    const { api, config } = await this.prepare(platform, server);
+    return await api.publishUpdate({
+      ...this.#task(platform, config),
+      platform,
+      out: this.updatesDir,
+      ...(channel ? { channel } : {}),
+    });
+  }
+
+  /** 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();
-    const { api, config } = await this.prepare();
+    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();
+    const { api, config } = await this.prepare(platform);
+    if (!config.updates)
+      throw new Error(
+        `Mobile target '${this.target.name}' takes no updates: add mobile.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;
@@ -192,6 +335,12 @@ export class NativeApp {
     return `/${home.join("/")}?${params}`;
   }
 
+  //? 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";

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 };
+  }
+}