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

package/akanConfig/akanConfig.ts

@@ -8,9 +8,11 @@ import type { AkanImageConfig } from "akanjs/server";
 import type { App, Lib } from "../commandDecorators";
 import { LibExecutor, WorkspaceExecutor } from "../executors";
 import type { BaseDevEnv, PackageJson } from "../types";
+import { AkanBin } from "./akanBin";
 import {
   type AkanApiConfig,
   type AkanAssetsConfig,
+  type AkanBinConfig,
   type AkanDatabaseConfig,
   type AkanMobileConfig,
   type AkanMobileTargetConfig,
@@ -107,13 +109,19 @@ const normalizeDeepLinks = (deepLinks: DeepPartial<AkanMobileTargetConfig["deepL
   } satisfies AkanMobileTargetConfig["deepLinks"];
 };
 
-type AppConfigDeclaration = Omit<DeepPartial<AppConfigResult>, "docker" | "web"> & {
+type AppConfigDeclaration = Omit<DeepPartial<AppConfigResult>, "docker" | "web" | "bin"> & {
   docker?: DockerOption;
   web?: AkanWebOption;
+  bin?: AkanBinConfig;
 };
 
+type LibConfigDeclaration = Omit<DeepPartial<LibConfigResult>, "bin"> & { bin?: AkanBinConfig };
+
 export interface LibContributions {
   externalLibs: string[];
+  trustedDependencies?: string[];
+  /** Per lib, since an app carries only the entries of the libs it depends on. */
+  bin?: { lib: string; bin: AkanBinConfig }[];
   docker: LibDockerConfig;
   /** Keep globs rewritten to the app's own `public/`, where `akan sync` mounts each lib's assets. */
   keepFonts?: string[];
@@ -121,10 +129,19 @@ export interface LibContributions {
 
 const emptyLibContributions = (): LibContributions => ({
   externalLibs: [],
+  trustedDependencies: [],
+  bin: [],
   docker: { preRuns: [], postRuns: [] },
   keepFonts: [],
 });
 
+const normalizePackageNames = (names: unknown, owner: string): string[] => {
+  if (names === undefined) return [];
+  if (!Array.isArray(names) || names.some((name) => typeof name !== "string" || !name.trim()))
+    throw new Error(`${owner}: trustedDependencies lists package names`);
+  return [...new Set(names.map((name: string) => name.trim()))];
+};
+
 const normalizeKeepFonts = (keepFonts: string[] | undefined) => [
   ...new Set((keepFonts ?? []).map((glob) => glob.trim().replace(/^\/+/, "")).filter(Boolean)),
 ];
@@ -145,6 +162,10 @@ export class AkanAppConfig implements AppConfigResult {
   database: AkanDatabaseConfig;
   web: AkanWebConfig;
   externalLibs: string[];
+  trustedDependencies: string[];
+  /** The app's own entries; the libs' are in `libBins`. */
+  bin: AkanBinConfig;
+  libBins: { lib: string; bin: AkanBinConfig }[];
   barrelImports: string[];
   optimizeImports: string[];
   images: AkanImageConfig;
@@ -183,6 +204,15 @@ export class AkanAppConfig implements AppConfigResult {
     this.#applyRoutes(config?.routes);
     this.database = AkanAppConfig.#database(app, config);
     this.externalLibs = [...new Set([...(config?.externalLibs ?? []), ...libContributions.externalLibs])];
+    const owner = `apps/${app.name}/akan.config.ts`;
+    this.trustedDependencies = [
+      ...new Set([
+        ...normalizePackageNames(config?.trustedDependencies, owner),
+        ...(libContributions.trustedDependencies ?? []),
+      ]),
+    ];
+    this.bin = AkanBin.parse(config?.bin, owner, app.cwdPath);
+    this.libBins = libContributions.bin ?? [];
     this.barrelImports = [
       ...DEFAULT_BARREL_IMPORTS,
       ...WORKSPACE_BARREL_FACETS.map((facet) => `@apps/${app.name}/${facet}`),
@@ -239,6 +269,7 @@ export class AkanAppConfig implements AppConfigResult {
     const buildNum = rawMobile.buildNum ?? 1;
     const files = AkanAppConfig.#resolveMobileFiles(rawMobile.files as AkanMobileConfig["files"], "mobile", configPath);
     const native = rawMobile.native as AkanMobileConfig["native"];
+    const updates = rawMobile.updates as AkanMobileConfig["updates"];
     const defaultTargetName = this.#defaultMobileTargetName(rawTargets);
     const targetEntries = Object.entries(
       rawTargets ?? {
@@ -263,6 +294,11 @@ export class AkanAppConfig implements AppConfigResult {
           configPath,
         );
         const fileName = (target.fileName ?? rawMobile.fileName) as string | undefined;
+        const targetUpdates = updates || target.updates ? { ...updates, ...target.updates } : undefined;
+        if (targetUpdates && (!targetUpdates.url || !targetUpdates.publicKey))
+          throw new Error(
+            `${where}.updates in ${configPath} has no url or publicKey; give them in mobile.updates or the target's own.`,
+          );
         const resolved = {
           name,
           basePath,
@@ -279,6 +315,7 @@ export class AkanAppConfig implements AppConfigResult {
           ...(native || target.native
             ? { native: AkanAppConfig.#mergeNative(native, target.native as AkanMobileTargetConfig["native"]) }
             : {}),
+          ...(targetUpdates ? { updates: targetUpdates } : {}),
         } satisfies AkanMobileTargetConfig;
         return [name, resolved];
       }),
@@ -291,10 +328,11 @@ export class AkanAppConfig implements AppConfigResult {
       buildNum,
       ...(files ? { files } : {}),
       ...(native ? { native } : {}),
+      ...(updates ? { updates } : {}),
       targets,
     };
   }
-  static readonly #mobileKeys = ["appName", "appId", "fileName", "version", "buildNum", "files", "native"];
+  static readonly #mobileKeys = ["appName", "appId", "fileName", "version", "buildNum", "files", "native", "updates"];
   static readonly #targetKeys = [
     "basePath",
     "indexPath",
@@ -308,6 +346,7 @@ export class AkanAppConfig implements AppConfigResult {
     "deepLinks",
     "files",
     "native",
+    "updates",
   ];
   //* The Capacitor keys used to pass straight through; the native runtime takes typed ones, so a leftover is refused.
   static #assertMobileKeys(section: object, known: string[], where: string, configPath: string) {
@@ -350,10 +389,21 @@ export class AkanAppConfig implements AppConfigResult {
       if (merged.length) android[key] = merged;
       else delete android[key];
     }
+    const pushAndroid = { ...base?.push?.android, ...override?.push?.android };
+    const privacy = { ...base?.privacy, ...override?.privacy };
+    const window = { ...base?.desktop?.window, ...override?.desktop?.window };
+    const desktop = {
+      ...base?.desktop,
+      ...override?.desktop,
+      ...(Object.keys(window).length ? { window } : {}),
+    };
     return {
       ...(plugins.length ? { plugins } : {}),
       ...(Object.keys(ios).length ? { ios } : {}),
       ...(Object.keys(android).length ? { android } : {}),
+      ...(Object.keys(pushAndroid).length ? { push: { android: pushAndroid } } : {}),
+      ...(Object.keys(privacy).length ? { privacy } : {}),
+      ...(Object.keys(desktop).length ? { desktop } : {}),
     };
   }
   #defaultMobileTargetName(rawTargets: DeepPartial<AkanMobileConfig>["targets"] | undefined) {
@@ -405,18 +455,39 @@ export class AkanAppConfig implements AppConfigResult {
       command: docker?.command ?? ["bun", "main.js"],
     };
   }
-  #makeDockerfile(): string {
+  /** What the built server runs with in its image; a desktop app's carried server starts from the same values. */
+  getProductionEnv(environment: string = this.baseDevEnv.env): Record<string, string> {
+    return {
+      PORT: "8282",
+      NODE_ENV: "production",
+      AKAN_PUBLIC_REPO_NAME: this.baseDevEnv.repoName,
+      AKAN_PUBLIC_SERVE_DOMAIN: this.baseDevEnv.serveDomain,
+      AKAN_PUBLIC_APP_NAME: this.app.name,
+      AKAN_PUBLIC_ENV: environment,
+      ...(this.basePaths.size ? { AKAN_PUBLIC_BASE_PATHS: [...this.basePaths].join(",") } : {}),
+      AKAN_PUBLIC_DEFAULT_LOCALE: this.i18n.defaultLocale,
+      AKAN_PUBLIC_LOCALES: this.i18n.locales.join(","),
+      AKAN_PUBLIC_API_PREFIX: this.api.prefix,
+      AKAN_PUBLIC_WS_PREFIX: this.api.websocketPrefix,
+      AKAN_PUBLIC_OPERATION_MODE: "cloud",
+      AKAN_DATABASE_MODES: this.database.modes.join(","),
+      // File logging is off: a container's writable layer is ephemeral and stdout is the collection path.
+      AKAN_LOG_TO_FILE: "0",
+      // The web env matches what was built (a deployment can only narrow it).
+      ...(this.web.ssr ? {} : { AKAN_SSR: "false" }),
+      ...(this.web.csr ? {} : { AKAN_CSR: "false" }),
+    };
+  }
+  dockerfileFor(environment: string): string {
+    return this.#makeDockerfile(environment);
+  }
+  #makeDockerfile(environment?: string): string {
     if (typeof this.docker === "string") return this.docker;
     const { image, preRuns, postRuns, command } = this.docker;
     const preRunScripts = this.#getDockerRunScripts(preRuns);
     const postRunScripts = this.#getDockerRunScripts(postRuns);
     const imageScript = this.#getDockerImageScript(image, DEFAULT_DOCKER_IMAGE);
-    // The web env matches what was built (a deployment can only narrow it). File logging is off: a container's
-    // writable layer is ephemeral and stdout is the collection path.
-    const webEnvLines = [
-      ...(this.web.ssr ? [] : ["ENV AKAN_SSR=false"]),
-      ...(this.web.csr ? [] : ["ENV AKAN_CSR=false"]),
-    ].join("\n");
+    const envLines = Object.entries(this.getProductionEnv(environment)).map(([key, value]) => `ENV ${key}=${value}`);
     return `${imageScript}
 RUN apt-get update && apt-get upgrade -y && apt-get install -y --no-install-recommends ca-certificates tzdata && rm -rf /var/lib/apt/lists/*
 RUN ln -sf /usr/share/zoneinfo/Asia/Seoul /etc/localtime
@@ -428,21 +499,7 @@ COPY ./package.json ./package.json
 RUN bun install --production
 ${postRunScripts.join("\n")}
 COPY . .
-ENV PORT=8282
-ENV NODE_ENV=production
-ENV AKAN_PUBLIC_REPO_NAME=${this.baseDevEnv.repoName}
-ENV AKAN_PUBLIC_SERVE_DOMAIN=${this.baseDevEnv.serveDomain}
-ENV AKAN_PUBLIC_APP_NAME=${this.app.name}
-ENV AKAN_PUBLIC_ENV=${this.baseDevEnv.env}
-${this.basePaths.size ? `ENV AKAN_PUBLIC_BASE_PATHS=${[...this.basePaths].join(",")}` : ""}
-ENV AKAN_PUBLIC_DEFAULT_LOCALE=${this.i18n.defaultLocale}
-ENV AKAN_PUBLIC_LOCALES=${this.i18n.locales.join(",")}
-ENV AKAN_PUBLIC_API_PREFIX=${this.api.prefix}
-ENV AKAN_PUBLIC_WS_PREFIX=${this.api.websocketPrefix}
-ENV AKAN_PUBLIC_OPERATION_MODE=cloud
-ENV AKAN_DATABASE_MODES=${this.database.modes.join(",")}
-ENV AKAN_LOG_TO_FILE=0
-${webEnvLines}
+${envLines.join("\n")}
 CMD [${command.map((c) => `"${c}"`).join(",")}]`;
   }
   static #importGeneration = 0;
@@ -485,6 +542,10 @@ CMD [${command.map((c) => `"${c}"`).join(",")}]`;
     );
     return {
       externalLibs: libConfigs.flatMap((libConfig) => libConfig?.externalLibs ?? []),
+      trustedDependencies: libConfigs.flatMap((libConfig) => libConfig?.trustedDependencies ?? []),
+      bin: libConfigs.flatMap((libConfig) =>
+        libConfig && Object.keys(libConfig.bin).length ? [{ lib: libConfig.lib.name, bin: libConfig.bin }] : [],
+      ),
       docker: {
         preRuns: libConfigs.flatMap((libConfig) => libConfig?.docker.preRuns ?? []),
         postRuns: libConfigs.flatMap((libConfig) => libConfig?.docker.postRuns ?? []),
@@ -554,6 +615,7 @@ CMD [${command.map((c) => `"${c}"`).join(",")}]`;
           this.#resolveProductionDependencyVersion(lib),
         ]),
       ),
+      ...(this.trustedDependencies.length ? { trustedDependencies: this.trustedDependencies } : {}),
       ...data,
     };
   }
@@ -607,13 +669,18 @@ function mergeImageConfig(config: Partial<AkanImageConfig> = {}): AkanImageConfi
 export class AkanLibConfig implements LibConfigResult {
   lib: Lib;
   externalLibs: string[];
+  trustedDependencies: string[];
+  bin: AkanBinConfig;
   docker: LibDockerConfig;
   assets: LibAssetsConfig;
   /** Live-only: plugins declared in this lib's `akan.config.ts` (never serialized). */
   plugins: AkanPlugin[];
-  constructor(lib: Lib, config: DeepPartial<LibConfigResult>, plugins: AkanPlugin[] = []) {
+  constructor(lib: Lib, config: LibConfigDeclaration, plugins: AkanPlugin[] = []) {
     this.lib = lib;
     this.externalLibs = config?.externalLibs ?? [];
+    const owner = `libs/${lib.name}/akan.config.ts`;
+    this.trustedDependencies = normalizePackageNames(config?.trustedDependencies, owner);
+    this.bin = AkanBin.parse(config?.bin, owner, lib.cwdPath);
     this.docker = { preRuns: config?.docker?.preRuns ?? [], postRuns: config?.docker?.postRuns ?? [] };
     this.assets = { keepFonts: normalizeKeepFonts(config?.assets?.keepFonts as string[] | undefined) };
     this.plugins = plugins;
@@ -621,7 +688,7 @@ export class AkanLibConfig implements LibConfigResult {
   static async from(lib: Lib, { bustImportCache = false }: { bustImportCache?: boolean } = {}) {
     const configImp = await AkanAppConfig.importConfigModule(lib.cwdPath, { bustImportCache });
     const resolved = typeof configImp === "function" ? configImp(lib) : configImp;
-    const { plugins, ...config } = (resolved ?? {}) as DeepPartial<LibConfigResult> & { plugins?: AkanPlugin[] };
+    const { plugins, ...config } = (resolved ?? {}) as LibConfigDeclaration & { plugins?: AkanPlugin[] };
     return new AkanLibConfig(lib, config, plugins ?? []);
   }
 }

package/akanConfig/index.ts

@@ -1,2 +1,3 @@
+export * from "./akanBin";
 export * from "./akanConfig";
 export * from "./types";

package/akanConfig/types.ts

@@ -1,12 +1,17 @@
 export type {
   AkanApiConfig,
   AkanAssetsConfig,
+  AkanBinConfig,
+  AkanBinPathSource,
+  AkanBinSource,
+  AkanBinUrlSource,
   AkanConfigFile,
   AkanDatabaseConfig,
   AkanExecutor,
   AkanMobileConfig,
   AkanMobileNativeConfig,
   AkanMobileTargetConfig,
+  AkanMobileUpdatesConfig,
   AkanNativeValue,
   AkanPlugin,
   AkanPluginNativeConfig,
@@ -20,6 +25,7 @@ export type {
   AppConfigResult,
   AppScanResult,
   Arch,
+  BinPlatform,
   DatabaseMode,
   DeepPartial,
   DockerConfig,
@@ -39,4 +45,4 @@ export type {
   ScanResult,
   WorkspaceScanResult,
 } from "akanjs";
-export { archs } from "akanjs";
+export { archs, binPlatforms } from "akanjs";

package/applicationBuildRunner.test.ts

@@ -1,8 +1,11 @@
 import { describe, expect, test } from "bun:test";
-import { rm } from "node:fs/promises";
+import { mkdtemp, readFile, rm } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
-import { AKAN_BACKEND_MINIFY, AKAN_OPTIONAL_BACKEND_EXTERNALS } from "./applicationBuildRunner";
+import { AkanAppConfig } from "./akanConfig";
+import { AKAN_BACKEND_MINIFY, AKAN_OPTIONAL_BACKEND_EXTERNALS, ApplicationBuildRunner } from "./applicationBuildRunner";
+import type { App } from "./commandDecorators";
+import { Executor } from "./executors";
 
 describe("ApplicationBuildRunner", () => {
   test("externalizes Akan optional backend dependencies", () => {
@@ -44,4 +47,35 @@ console.info(new SampleService().name);
       await rm(dir, { recursive: true, force: true });
     }
   });
+
+  test("an image of a --env build boots the env its server carries, not the root .env's", async () => {
+    const root = await mkdtemp(path.join(os.tmpdir(), "akan-build-meta-"));
+    const baseDevEnv = {
+      repoName: "akanjs",
+      serveDomain: "akanjs.com",
+      env: "local" as const,
+      portOffset: 0,
+      workspaceRoot: root,
+    };
+    const config = new AkanAppConfig(
+      { name: "portal" } as never,
+      [],
+      { name: "repo", version: "1.0.0", description: "repo" },
+      {},
+      baseDevEnv,
+    );
+    const app = {
+      getConfig: async () => config,
+      dist: new Executor("dist", root),
+      workspace: { workspaceRoot: root },
+    } as unknown as App;
+    try {
+      await new ApplicationBuildRunner(app, { environment: "debug" }).buildAppMeta();
+      expect(await readFile(path.join(root, "Dockerfile"), "utf8")).toContain("ENV AKAN_PUBLIC_ENV=debug\n");
+      await new ApplicationBuildRunner(app).buildAppMeta();
+      expect(await readFile(path.join(root, "Dockerfile"), "utf8")).toContain("ENV AKAN_PUBLIC_ENV=local\n");
+    } finally {
+      await rm(root, { recursive: true, force: true });
+    }
+  });
 });

package/applicationBuildRunner.ts

@@ -15,6 +15,7 @@ import {
   SsrBaseArtifactBuilder,
 } from "./frontendBuild";
 import { Spinner } from "./spinner";
+import { createServerEnvPlugin } from "./transforms/serverEnvPlugin";
 
 export interface TypecheckOptions {
   clean?: boolean;
@@ -29,6 +30,8 @@ export type BuildProgressReporter = ApplicationBuildProgressReporter;
 export interface ApplicationBuildRunnerOptions {
   fast?: boolean;
   reporter?: BuildProgressReporter;
+  /** The backend env the build is for, when it is not the workspace's own (a mobile or desktop build's `--env`). */
+  environment?: string;
 }
 export interface BuildOptions {
   spinner?: boolean;
@@ -76,14 +79,16 @@ export class ApplicationBuildRunner {
   #app: App;
   #fast: boolean;
   #reporter?: BuildProgressReporter;
+  #environment?: string;
   #spinner?: boolean;
   #startedAt = Date.now();
   #phases: BuildPhaseResult[] = [];
 
-  constructor(app: App, { fast = false, reporter }: ApplicationBuildRunnerOptions = {}) {
+  constructor(app: App, { fast = false, reporter, environment }: ApplicationBuildRunnerOptions = {}) {
     this.#app = app;
     this.#fast = fast;
     this.#reporter = reporter;
+    this.#environment = environment;
   }
 
   async build({ spinner = false }: BuildOptions = {}): Promise<BuildResult> {
@@ -133,7 +138,7 @@ export class ApplicationBuildRunner {
           ? `${result.files} files, ${ApplicationBuildRunner.formatBytes(result.inputBytes)} -> gzip ${ApplicationBuildRunner.formatBytes(result.outputBytes)} / br ${ApplicationBuildRunner.formatBytes(result.brotliBytes)}`
           : "no files",
     );
-    await this.#runPhase("metadata", "Writing production metadata", () => this.#buildAppMeta());
+    await this.#runPhase("metadata", "Writing production metadata", () => this.buildAppMeta());
     return {
       phases: this.#phases,
       durationMs: Date.now() - this.#startedAt,
@@ -175,11 +180,12 @@ export class ApplicationBuildRunner {
     }
   }
 
-  async #buildAppMeta() {
+  async buildAppMeta() {
     const akanConfig = await this.#app.getConfig();
+    const dockerfile = akanConfig.dockerfileFor(this.#environment ?? akanConfig.baseDevEnv.env);
     await Promise.all([
       this.#app.dist.writeJson("package.json", akanConfig.getProductionPackageJson()),
-      this.#app.dist.writeFile(`${this.#app.dist.cwdPath}/Dockerfile`, akanConfig.dockerfile),
+      this.#app.dist.writeFile(`${this.#app.dist.cwdPath}/Dockerfile`, dockerfile),
       this.#app.dist.writeJson("akan.build.json", {
         buildId: await this.#resolveBuildId(),
         akanVersion: akanConfig.akanVersion,
@@ -204,7 +210,7 @@ export class ApplicationBuildRunner {
   }
 
   async #buildBackend() {
-    const { externalLibs, web } = await this.#app.getConfig();
+    const { externalLibs, web, baseDevEnv, branches } = await this.#app.getConfig();
     const backendEntryPoints = [`${this.#app.cwdPath}/main.ts`, `${this.#app.cwdPath}/server.ts`];
     for (const entrypoint of backendEntryPoints) {
       if (!(await Bun.file(entrypoint).exists())) throw new Error(`Backend entrypoint not found: ${entrypoint}`);
@@ -217,7 +223,16 @@ export class ApplicationBuildRunner {
       // `akan build` must embed production react-server-dom regardless of the shell's NODE_ENV.
       define: { "process.env.NODE_ENV": JSON.stringify("production") },
     } satisfies Omit<Bun.BuildConfig, "entrypoints">;
-    const backendConfig = { ...sharedConfig, plugins: [this.#createExternalSpecifiersPlugin(externalLibs)] };
+    const serverEnvPlugin = createServerEnvPlugin({
+      envDir: path.join(this.#app.cwdPath, "env"),
+      //? The root .env wins over the shell in baseDevEnv, so a `--env` build names its own; a desktop app runs it.
+      environment: this.#environment ?? baseDevEnv.env,
+      environments: ["local", "testing", ...branches],
+    });
+    const backendConfig = {
+      ...sharedConfig,
+      plugins: [this.#createExternalSpecifiersPlugin(externalLibs), serverEnvPlugin],
+    };
     //* Built apart so main.js keeps its own module copies; splitting moves lazy vendor `import()`s out of the boot parse.
     const [mainResult, serverResult] = [
       await this.#buildOrThrow("backend", { ...backendConfig, entrypoints: [backendEntryPoints[0]] }),

package/biome.base.json

@@ -137,7 +137,8 @@
         "!**/*.spec.tsx",
         "!**/*.constant.ts",
         "!**/common/**",
-        "!**/env/**"
+        "!**/env/**",
+        "!{apps,libs}/*/native/**"
       ],
       "plugins": ["./node_modules/@akanjs/devkit/lint/no-throw-raw-error.grit"]
     },
@@ -225,6 +226,7 @@
         "{apps,libs}/**/*.ts",
         "{apps,libs}/**/*.tsx",
         "!{apps,libs}/**/webkit/**",
+        "!{apps,libs}/*/native/**",
         "!**/*.test.ts",
         "!**/*.test.tsx",
         "!**/*.spec.ts",

package/csrE2e/csrE2eHarness.fixture.ts

@@ -54,6 +54,7 @@ export class CsrE2eHarness {
   readonly #lang: string;
   readonly #mobileTarget: string;
   readonly #edited = new Map<string, string>();
+  readonly #console: string[];
   #marker = "";
   #csr: boolean = true;
 
@@ -63,14 +64,39 @@ export class CsrE2eHarness {
     server: CsrE2eServer | null;
     lang: string;
     mobileTarget: string;
+    console: string[];
   }) {
     this.origin = options.origin;
     this.#view = options.view;
+    this.#console = options.console;
     this.#server = options.server;
     this.#lang = options.lang;
     this.#mobileTarget = options.mobileTarget;
   }
 
+  /** What keeps this host from driving a page, or null when a `Bun.WebView` opens one and answers. */
+  static async preflight(backend = CsrE2eHarness.#defaultBackend()): Promise<string | null> {
+    if (typeof (Bun as { WebView?: unknown }).WebView !== "function") return `Bun ${Bun.version} has no Bun.WebView`;
+    let view: Bun.WebView | null = null;
+    try {
+      const opened = new Bun.WebView({
+        width: 320,
+        height: 240,
+        backend: backend === "chrome" ? { type: "chrome", url: false } : backend,
+      });
+      view = opened;
+      const answer = await Promise.race([
+        opened.navigate("about:blank").then(async () => await opened.evaluate<number>("1 + 1")),
+        Bun.sleep(30_000).then(() => null),
+      ]);
+      return answer === 2 ? null : `a ${backend} Bun.WebView did not answer within 30s`;
+    } catch (error) {
+      return `a ${backend} Bun.WebView cannot start: ${error instanceof Error ? error.message : String(error)}`;
+    } finally {
+      view?.close();
+    }
+  }
+
   /** E2E suites run only with `AKAN_CSR_E2E=1`: they boot a dev server and a browser. */
   static get enabled() {
     return process.env.AKAN_CSR_E2E === "1";
@@ -91,13 +117,19 @@ export class CsrE2eHarness {
       await CsrE2eHarness.#waitForHealth(origin, server, options.startTimeoutMs ?? 180_000);
       const { width, height } = { width: 390, height: 844, ...options.viewport };
       const backend = options.backend ?? CsrE2eHarness.#defaultBackend();
+      const messages: string[] = [];
+      const print = process.env.AKAN_CSR_E2E_CONSOLE === "1";
       //? `url: false` spawns a fresh Chrome instead of attaching to one the developer runs with remote debugging on.
       const view = new Bun.WebView({
         width,
         height,
         backend: backend === "chrome" ? { type: "chrome", url: false } : backend,
-        //? AKAN_CSR_E2E_CONSOLE=1 prints the page's console: the only view of a hydration warning or a failed patch.
-        ...(process.env.AKAN_CSR_E2E_CONSOLE === "1" ? { console: globalThis.console } : {}),
+        //? Kept for `consoleMessages()`; AKAN_CSR_E2E_CONSOLE=1 also prints it, the only view of a hydration warning or
+        //? a failed patch. An uncaught error is not a console call and never arrives here.
+        console: (type: string, ...args: unknown[]) => {
+          messages.push(`[${type}] ${args.map(CsrE2eHarness.#formatArg).join(" ")}`);
+          if (print) globalThis.console.info(`[page ${type}]`, ...args);
+        },
       });
       return new CsrE2eHarness({
         origin,
@@ -105,6 +137,7 @@ export class CsrE2eHarness {
         server,
         lang: options.lang ?? "en",
         mobileTarget: options.mobileTarget ?? "e2e",
+        console: messages,
       });
     } catch (error) {
       await CsrE2eHarness.#stopServer(server);
@@ -120,6 +153,7 @@ export class CsrE2eHarness {
       url.searchParams.set("akanMobileTarget", this.#mobileTarget);
     }
     this.#csr = csr;
+    this.#console.length = 0;
     await this.#view.navigate(url.toString());
     await this.#markBoot();
   }
@@ -346,6 +380,11 @@ export class CsrE2eHarness {
     return [await read(logPath), await read(logPath.replace(/\.log$/, ".err.log"))];
   }
 
+  /** The page's console calls since `open()`, as `[type] text`. */
+  consoleMessages(): string[] {
+    return [...this.#console];
+  }
+
   /** Whether the page reloaded since `open()`: the boot marker lives only in the page `open()` loaded. */
   async reloaded() {
     const marker = await this.evaluate(
@@ -378,7 +417,17 @@ export class CsrE2eHarness {
     await CsrE2eHarness.#stopServer(this.#server);
   }
 
-  static #defaultBackend() {
+  static #formatArg(arg: unknown): string {
+    if (typeof arg === "string") return arg;
+    try {
+      return JSON.stringify(arg) ?? String(arg);
+    } catch {
+      // A circular descriptor still names itself.
+      return String(arg);
+    }
+  }
+
+  static #defaultBackend(): "webkit" | "chrome" {
     const requested = process.env.AKAN_CSR_E2E_BACKEND;
     if (requested === "webkit" || requested === "chrome") return requested;
     return process.platform === "darwin" ? "webkit" : "chrome";
@@ -411,8 +460,9 @@ export class CsrE2eHarness {
     const errPath = logPath.replace(/\.log$/, ".err.log");
     //? A `Bun.file` sink writes from offset 0 without truncating, so the last run's tail would outlive this one's start.
     await Promise.all([Bun.write(logPath, ""), Bun.write(errPath, "")]);
-    //? Its own process group, so stopping it reaches the gateway, the builder and every replica it spawned.
-    const proc = Bun.spawn(["bun", cli, "start", app, "--plain"], {
+    //? Its own process group, so stopping it reaches the gateway, the builder and every replica it spawned. That group
+    //? outlives a run killed before it could stop it, so `--kill` takes the suite's own port back from it first.
+    const proc = Bun.spawn(["bun", cli, "start", app, "--plain", "--kill"], {
       cwd: workspaceRoot,
       env: { ...process.env, AKAN_DEV_PORT: String(port), ...env },
       stdout: Bun.file(logPath),

package/csrE2e/csrPageStack.e2e.test.ts

@@ -176,6 +176,71 @@ describe.skipIf(!CsrE2eHarness.enabled)("CSR page stack (minimal, /e2e/stack)",
     expect(await csr.ticksOver("tab-a")).toBeGreaterThan(0);
   }, 60_000);
 
+  test("a page that redirects after an await lands on the target, inside the target's own async layout", async () => {
+    await csr.open(TAB_B);
+    await csr.evaluate((next: string) => {
+      window.dispatchEvent(new CustomEvent("akan:sync-navigation", { detail: { href: next, kind: "push" } }));
+    }, "/e2e/stack/redirect?delay=120");
+    await csr.waitFor((pathname: string) => location.pathname.endsWith(pathname), {
+      args: ["/e2e/tabbed/home"],
+      timeout: 10_000,
+    });
+    await csr.waitFor(() => document.querySelectorAll('[data-e2e="tabbar"]').length === 1, { timeout: 10_000 });
+    await csr.waitFor(
+      () =>
+        (window as unknown as { __akanE2eProbes?: Record<string, { mounted?: boolean }> }).__akanE2eProbes?.home
+          ?.mounted,
+      { timeout: 10_000 },
+    );
+    expect(await csr.probe("home")).toMatchObject({ activity: "current", mounted: true });
+    expect(await csr.reloaded()).toBe(false);
+  }, 60_000);
+
+  test("an async render that throws is logged with its route instead of leaving a blank page in silence", async () => {
+    await csr.open("/e2e/stack/broken");
+    await csr.waitFor(() => true);
+    await Bun.sleep(500);
+    expect(
+      csr.consoleMessages().some((line) => /render of page \d+ of \S*\/e2e\/stack\/broken failed/.test(line)),
+    ).toBe(true);
+  }, 60_000);
+
+  test("the memory frame trace records navigation without writing it to the console", async () => {
+    await csr.open(TAB_A);
+    await csr.evaluate(() => localStorage.setItem("akan:debug:frame", "memory"));
+    try {
+      await csr.open(TAB_A);
+      await csr.navigate(item("71"));
+      const events = await csr.evaluate(() =>
+        ((window as { __AKAN_FRAME_TRACE__?: { event: string }[] }).__AKAN_FRAME_TRACE__ ?? []).map(
+          (entry) => entry.event,
+        ),
+      );
+      expect(events).toContain("router.push");
+      expect(events).toContain("navigation.commit");
+      expect(csr.consoleMessages().some((line) => line.includes("[akan:frame:"))).toBe(false);
+    } finally {
+      await csr.evaluate(() => localStorage.removeItem("akan:debug:frame"));
+    }
+  }, 60_000);
+
+  test("a cached page whose layout redirected renders that layout again when it is back on screen", async () => {
+    await csr.evaluate(() => {
+      (globalThis as { __e2eSignedIn?: boolean }).__e2eSignedIn = false;
+    });
+    await csr.open("/e2e/gate/home");
+    await csr.waitFor((pathname: string) => location.pathname.endsWith(pathname), {
+      args: [TAB_B],
+      timeout: 10_000,
+    });
+    await csr.evaluate(() => {
+      (globalThis as { __e2eSignedIn?: boolean }).__e2eSignedIn = true;
+    });
+    await csr.navigate("/e2e/gate/home", "replace");
+    await csr.waitFor(() => document.querySelectorAll('[data-e2e="gate-tabbar"]').length === 1, { timeout: 10_000 });
+    expect(await csr.probe("gate-home")).toMatchObject({ activity: "current", mounted: true });
+  }, 60_000);
+
   test("back returns to the previous entry without a reload", async () => {
     await csr.open(TAB_A);
     await csr.navigate(item("6"));