@akanjs/devkit 3.0.0-beta.27 → 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/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"));

package/executors.test.ts

@@ -1,4 +1,5 @@
 import { describe, expect, test } from "bun:test";
+import { existsSync } from "node:fs";
 import { lstat, mkdir, readFile, readlink, rm, stat, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { AkanAppConfig } from "./akanConfig";
@@ -326,6 +327,37 @@ describe("Workspace and app executor environment contracts", () => {
     expect((await stat(path.join(root, "dist/apps/demo/public"))).isDirectory()).toBe(true);
   });
 
+  test("akan start clears the dev output and keeps native builds, update releases and the bin downloads", async () => {
+    const root = await makeTempRoot();
+    process.env.AKAN_PUBLIC_REPO_NAME = "repo";
+    process.env.AKAN_PUBLIC_SERVE_DOMAIN = "example.com";
+    process.env.AKAN_PUBLIC_ENV = "local";
+    process.env.PORT_OFFSET = "0";
+    await writeJson(path.join(root, "package.json"), rootPackageJson());
+    await mkdir(path.join(root, "apps/startclean/page"), { recursive: true });
+    await writeFile(path.join(root, "apps/startclean/akan.config.ts"), "export default {};\n");
+    const akan = path.join(root, "apps/startclean/.akan");
+    const kept = [
+      "mobile/desktop/updates/macos-arm64/main.json",
+      "mobile/desktop/native/macos/App.app",
+      "cache/bin/ffmpeg",
+    ];
+    const removed = [
+      "artifact/client/app.js",
+      "generated/dict/index.ts",
+      "cache/cssCandidates.json",
+      "desktop/server/main.js",
+    ];
+    for (const file of [...kept, ...removed]) await writeText(path.join(akan, file), "x");
+
+    const app = AppExecutor.from(new WorkspaceExecutor({ workspaceRoot: root, repoName: "repo" }), "startclean");
+    await app.prepareCommand("start");
+
+    for (const file of kept) expect(existsSync(path.join(akan, file))).toBe(true);
+    for (const file of [...removed, "artifact", "generated", "desktop"])
+      expect(existsSync(path.join(akan, file))).toBe(false);
+  });
+
   describe("syncPages", () => {
     // `AppExecutor.from` memoises by name, so each test needs a name no other test has used.
     const makeAppWithLibPages = async (
@@ -963,6 +995,17 @@ describe("WorkspaceExecutor listing", () => {
       ["@sample/tool", "akanjs", "zeta-tool"],
     ]);
   });
+
+  test("never takes a scratch workspace under a local/ folder for a package, app or lib", async () => {
+    const root = await makeTempRoot();
+    await writeJson(path.join(root, "pkgs/@akanjs/devkit/package.json"), { name: "@akanjs/devkit" });
+    await writeJson(path.join(root, "pkgs/@akanjs/devkit/local/akan-cli-x/package.json"), { name: "repo" });
+    await writeText(path.join(root, "apps/portal/akan.config.ts"), "");
+    await writeText(path.join(root, "libs/util/local/akan-cli-y/akan.config.ts"), "");
+
+    const workspace = new WorkspaceExecutor({ workspaceRoot: root, repoName: "repo" });
+    expect(await workspace.getExecs()).toEqual([["portal"], [], ["@akanjs/devkit"]]);
+  });
 });
 
 describe("SysExecutor module listing", () => {

package/executors.ts

@@ -790,7 +790,8 @@ export class WorkspaceExecutor extends Executor {
   }
   async #getDirHasFile(basePath: string, targetFilename: string) {
     if (!(await FileSys.dirExists(basePath))) return [];
-    const AVOID_DIRS = ["node_modules", "dist", "public", "webkit"];
+    //? `local/` is gitignored scratch: a test's temporary workspace there has a package.json of its own.
+    const AVOID_DIRS = ["node_modules", "dist", "public", "webkit", "local"];
     const getDirs = async (dirname: string, maxDepth = 3, results: string[] = [], prefix = "") => {
       const dirs = await this.readdir(dirname);
       await Promise.all(
@@ -1118,6 +1119,20 @@ export class AppExecutor extends SysExecutor {
   static from(executor: SysExecutor | WorkspaceExecutor, name: string) {
     return new AppExecutor({ workspace: executor instanceof WorkspaceExecutor ? executor : executor.workspace, name });
   }
+  //* Not dev output: native builds and the update releases waiting to be uploaded, and the downloaded `bin` sources.
+  static readonly #keptOnStart = [path.join(".akan", "mobile"), path.join(".akan", "cache", "bin")];
+  async #removeDevOutput(dir = ".akan") {
+    const entries = await readDirEntries(this.getPath(dir)).catch(() => [] as string[]);
+    await Promise.all(
+      entries.map(async (name) => {
+        const entry = path.join(dir, name);
+        if (AppExecutor.#keptOnStart.includes(entry)) return;
+        if (AppExecutor.#keptOnStart.some((kept) => kept.startsWith(`${entry}${path.sep}`)))
+          return await this.#removeDevOutput(entry);
+        await this.removeDir(entry);
+      }),
+    );
+  }
   getEnv() {
     return WorkspaceExecutor.getBaseDevEnv().env;
   }
@@ -1174,7 +1189,7 @@ export class AppExecutor extends SysExecutor {
         ...(akanConfig.web.ssr ? [this.cp("public", `${this.dist.cwdPath}/public`, { dereference: true })] : []),
       ]);
     } else {
-      await this.removeDir(".akan");
+      await this.#removeDevOutput();
       //? `akan start` keeps the full dev surface: the incremental builder is also the file watcher.
       if (!akanConfig.web.ssr || !akanConfig.web.csr)
         this.logger.verbose(