@akanjs/devkit 2.4.0-rc.8 → 2.4.0

package/CHANGELOG.md

@@ -1,5 +1,58 @@
 # @akanjs/devkit
 
+## 2.4.0
+
+### Minor Changes
+
+- 23d43b3: Harden dev host recovery during failed builds:
+
+  - Defer builder/backend recycle while a generation's build is still failing
+  - Merge deferred invalidate batches so restarts cover every skipped change
+  - Recover the builder with exponential backoff instead of giving up
+  - Revive a backend that gave up once the build goes green again
+  - Resurrect dev children after a failed recycle so the error overlay stays reachable
+  - Enter degraded builder boot mode on compile errors and retry on the next edit
+  - Announce recovered pages/css state after a degraded boot succeeds
+
+- 18abf71: Improve dev server stability:
+
+  - Add `isPortInUseError` utility for detecting EADDRINUSE across Bun versions
+  - Stop crash-looping replicas after max boot failures in dev mode (`akan start`)
+  - Handle parent IPC disconnect to prevent orphaned gateway/child processes
+  - Report `wsUpstream` in ready IPC so gateway routes to the actual bound port
+  - Fall back to ephemeral port when preferred WS port is in use
+  - Support controlled dev-host restart on config changes (`akan.config.ts`, `tsconfig`)
+  - Forward backend build-status IPC to dev host for error surfacing in HMR overlay
+  - Limit backend recovery attempts (5 max) and idle until next server-side edit
+  - Add integration tests for config-edit restart and boot-failure recovery
+
+- 23d43b3: Improve the mobile Capacitor workflow:
+
+  - Auto-declare default Capacitor plugins in the app package.json before iOS/Android launch
+  - Expand mobile runtime peer dependencies and workspace-root preflight installs
+  - Derive repo-scoped default bundle ids to avoid Apple portal collisions
+  - Add `akan doctor --ios` to flag placeholder bundle identifiers
+  - Add `--device` to `akan start ios` for non-interactive simulator/device selection
+  - Prefer newer iOS runtimes and warn on SwiftUICore-incompatible simulators
+  - Detect SwiftUICore dyld failures with actionable guidance
+  - Select a routable LAN host for mobile live reload with override support
+  - Raise Android minSdkVersion to 26 for bundled Capacitor plugins
+  - Include `@capacitor-community/fcm` in push notification runtime packages
+  - Resolve client port from `window.location` on the browser client
+
+### Patch Changes
+
+- d56a8f0: Ship Pretendard as the default font for newly created apps:
+
+  - Bundle Pretendard woff2 files under the app template `public/fonts`
+  - Declare `fonts` with `default: true` in the generated root `_layout.tsx`
+
+- Updated dependencies [d56a8f0]
+- Updated dependencies [23d43b3]
+- Updated dependencies [18abf71]
+- Updated dependencies [23d43b3]
+  - akanjs@2.4.0
+
 ## 2.3.11
 
 ### Minor Changes

package/akanApp/akanApp.host.test.ts

@@ -4,8 +4,10 @@ import {
   backendRestartReasonFromMessage,
   buildStatusReplaySequence,
   createBackendBuildStatus,
+  hasBuildFailureForGeneration,
   isLegacyBackendFallbackFile,
   mergeBackendRestartReasons,
+  mergeInvalidateMessages,
   normalizeBackendReportedGeneration,
   shouldAbandonBackendRecovery,
   shouldMarkBuildPhaseRecovered,
@@ -226,6 +228,96 @@ describe("backend recovery abandonment", () => {
   });
 });
 
+describe("hasBuildFailureForGeneration", () => {
+  const status = (phase: DevBuildStatus["phase"], generation: number, ok: boolean): DevBuildStatus => ({
+    generation,
+    phase,
+    ok,
+    files: [],
+  });
+
+  test("detects a failing phase recorded for the same generation", () => {
+    const statusByPhase = new Map<DevBuildStatus["phase"], DevBuildStatus>([
+      ["csr", status("csr", 3, false)],
+      ["barrel", status("barrel", 3, true)],
+    ]);
+    expect(hasBuildFailureForGeneration(statusByPhase, 3)).toBe(true);
+  });
+
+  test("ignores stale failures from earlier generations", () => {
+    const statusByPhase = new Map<DevBuildStatus["phase"], DevBuildStatus>([
+      ["csr", status("csr", 3, false)],
+      ["barrel", status("barrel", 4, true)],
+    ]);
+    expect(hasBuildFailureForGeneration(statusByPhase, 4)).toBe(false);
+  });
+
+  test("treats unknown generations and green boards as healthy", () => {
+    const statusByPhase = new Map<DevBuildStatus["phase"], DevBuildStatus>([["csr", status("csr", 3, false)]]);
+    expect(hasBuildFailureForGeneration(statusByPhase, undefined)).toBe(false);
+    expect(hasBuildFailureForGeneration(new Map(), 3)).toBe(false);
+  });
+});
+
+describe("mergeInvalidateMessages", () => {
+  const invalidate = (
+    generation: number,
+    files: string[],
+    actions: DevChangeAction[],
+  ): Extract<BuilderMessage, { type: "invalidate" }> => ({
+    type: "invalidate",
+    kinds: ["code"],
+    files,
+    generation,
+    devPlan: {
+      generation,
+      files,
+      generatedFiles: [],
+      roles: ["shared"],
+      actions,
+      reasonByFile: { [files[0] ?? "/repo/a.ts"]: ["shared-path"] },
+    },
+  });
+
+  test("unions files, kinds, and actions while keeping the latest generation", () => {
+    const merged = mergeInvalidateMessages(
+      invalidate(3, ["/repo/b.ts", "/repo/a.ts"], ["restart-builder"]),
+      invalidate(5, ["/repo/c.ts"], ["rebuild-client"]),
+    );
+
+    expect(merged.generation).toBe(5);
+    expect(merged.files).toEqual(["/repo/a.ts", "/repo/b.ts", "/repo/c.ts"]);
+    expect(merged.devPlan?.generation).toBe(5);
+    expect(merged.devPlan?.actions).toEqual(["rebuild-client", "restart-builder"]);
+  });
+
+  test("keeps the surviving devPlan when only one side carries one", () => {
+    const withPlan = invalidate(3, ["/repo/a.ts"], ["restart-builder"]);
+    const withoutPlan: Extract<BuilderMessage, { type: "invalidate" }> = {
+      type: "invalidate",
+      kinds: ["css"],
+      files: ["/repo/style.css"],
+      generation: 4,
+    };
+
+    const merged = mergeInvalidateMessages(withPlan, withoutPlan);
+    expect(merged.devPlan?.actions).toEqual(["restart-builder"]);
+    expect(merged.kinds).toEqual(["code", "css"]);
+    expect(merged.generation).toBe(4);
+  });
+
+  test("merges per-file reasons without duplicating entries", () => {
+    const current = invalidate(3, ["/repo/a.ts"], ["restart-builder"]);
+    const next = invalidate(4, ["/repo/a.ts"], ["restart-builder"]);
+    const nextPlan = next.devPlan;
+    if (!nextPlan) throw new Error("devPlan expected");
+    nextPlan.reasonByFile["/repo/a.ts"] = ["runtime-metadata", "shared-path"];
+
+    const merged = mergeInvalidateMessages(current, next);
+    expect(merged.devPlan?.reasonByFile["/repo/a.ts"]).toEqual(["runtime-metadata", "shared-path"]);
+  });
+});
+
 describe("normalizeBackendReportedGeneration", () => {
   test("drops the gateway's unknown-generation sentinel", () => {
     expect(normalizeBackendReportedGeneration(-1)).toBeUndefined();

package/akanApp/akanApp.host.ts

@@ -1,6 +1,6 @@
 import path from "node:path";
 import { Logger } from "akanjs/common";
-import type { BuilderMessage, BuildPhase, DevBuildStatus, DevChangeRole } from "akanjs/server";
+import type { BuilderMessage, BuildPhase, DevBuildStatus, DevChangePlan, DevChangeRole } from "akanjs/server";
 import type { App } from "../commandDecorators";
 import { createTunnel } from "../createTunnel";
 import { WorkspaceExecutor } from "../executors";
@@ -17,6 +17,10 @@ const BACKEND_RECOVERY_MAX_ATTEMPTS = 5;
 const BACKEND_STDERR_TAIL_LIMIT = 40;
 const BUILDER_READY_TIMEOUT_MS = 150000;
 const BUILDER_START_MAX_ATTEMPTS = 3;
+// The builder is the file watcher: while it is down no edit can trigger a retry, so unlike the
+// backend the recovery loop never gives up — it only backs off.
+const BUILDER_RECOVERY_BASE_DELAY_MS = 2_000;
+const BUILDER_RECOVERY_MAX_DELAY_MS = 60_000;
 const SOURCE_EXTS = new Set([".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"]);
 const NON_SOURCE_EXT_RE =
   /\.(css|scss|sass|less|json|svg|png|jpe?g|webp|gif|avif|ico|woff2?|ttf|otf|mp3|mp4|wav|html)$/i;
@@ -156,6 +160,55 @@ export const shouldReplaceLastGoodMessage = (
 export const shouldQueueBuildStatusReplay = (backendReady: boolean, pendingReplayCount: number): boolean =>
   !backendReady || pendingReplayCount > 0;
 
+/**
+ * Recycling the builder/backend on a generation whose build already failed is guaranteed to strand
+ * the dev server: the rebooted builder hits the same compile error and exits before builder-ready.
+ * Failing phase statuses for a generation arrive over IPC before that generation's invalidate, so
+ * the host can check them here and defer the recycle until a healthy batch lands.
+ */
+export const hasBuildFailureForGeneration = (
+  statusByPhase: ReadonlyMap<BuildPhase, DevBuildStatus>,
+  generation: number | undefined,
+): boolean => {
+  if (typeof generation !== "number") return false;
+  for (const status of statusByPhase.values()) {
+    if (!status.ok && status.generation === generation) return true;
+  }
+  return false;
+};
+
+const mergeDevPlans = (current?: DevChangePlan, next?: DevChangePlan): DevChangePlan | undefined => {
+  if (!current) return next;
+  if (!next) return current;
+  const reasonByFile: Record<string, string[]> = { ...current.reasonByFile };
+  for (const [file, reasons] of Object.entries(next.reasonByFile)) {
+    reasonByFile[file] = [...new Set([...(reasonByFile[file] ?? []), ...reasons])].sort();
+  }
+  return {
+    generation: Math.max(current.generation, next.generation),
+    files: [...new Set([...current.files, ...next.files])].sort(),
+    generatedFiles: [...new Set([...current.generatedFiles, ...next.generatedFiles])].sort(),
+    roles: [...new Set([...current.roles, ...next.roles])].sort(),
+    actions: [...new Set([...current.actions, ...next.actions])].sort(),
+    reasonByFile,
+  };
+};
+
+/** A deferred recycle accumulates every batch it skipped so the eventual restart covers them all. */
+export const mergeInvalidateMessages = (
+  current: Extract<BuilderMessage, { type: "invalidate" }>,
+  next: Extract<BuilderMessage, { type: "invalidate" }>,
+): Extract<BuilderMessage, { type: "invalidate" }> => {
+  const generation = Math.max(generationValue(current.generation), generationValue(next.generation));
+  return {
+    type: "invalidate",
+    kinds: [...new Set([...current.kinds, ...next.kinds])].sort(),
+    files: [...new Set([...current.files, ...next.files])].sort(),
+    generation: generation >= 0 ? generation : undefined,
+    devPlan: mergeDevPlans(current.devPlan, next.devPlan),
+  };
+};
+
 export const buildStatusReplaySequence = (
   pendingReplay: readonly DevBuildStatus[],
   latestByPhase: ReadonlyMap<BuildPhase, DevBuildStatus>,
@@ -281,8 +334,12 @@ export class AkanAppHost {
   #restartTimer: ReturnType<typeof setTimeout> | null = null;
   #backendRecoveryTimer: ReturnType<typeof setTimeout> | null = null;
   #backendRecoveryAttempts = 0;
+  #backendGaveUp = false;
   #backendLifecycleState: BackendLifecycleState = "stopped";
   #pendingRestartReason: BackendRestartReason | null = null;
+  #pendingRecycle: { message: Extract<BuilderMessage, { type: "invalidate" }>; refreshConfig: boolean } | null = null;
+  #builderRecoveryTimer: ReturnType<typeof setTimeout> | null = null;
+  #builderRecoveryAttempts = 0;
   #backendStartStatus: { generation?: number; files: string[] } | null = null;
   #backendBuildStatusGeneration = 0;
   #backendStderrTail: string[] = [];
@@ -320,6 +377,10 @@ export class AkanAppHost {
       clearTimeout(this.#backendRecoveryTimer);
       this.#backendRecoveryTimer = null;
     }
+    if (this.#builderRecoveryTimer) {
+      clearTimeout(this.#builderRecoveryTimer);
+      this.#builderRecoveryTimer = null;
+    }
     await this.#stopBackend();
     this.#stopBuilder();
     return this;
@@ -335,6 +396,7 @@ export class AkanAppHost {
   }
   #startBackend(startStatus: { generation?: number; files: string[] } | null = null) {
     this.#backendStartStatus = startStatus;
+    this.#backendGaveUp = false;
     this.#setBackendLifecycleState("starting");
     this.#backendReady = false;
     this.#backendStderrTail = [];
@@ -531,7 +593,8 @@ export class AkanAppHost {
   #scheduleBackendRecovery(reason: string) {
     if (this.#backendRecoveryTimer || this.#backend) return;
     if (shouldAbandonBackendRecovery(this.#backendRecoveryAttempts)) {
-      const message = `Backend exited ${this.#backendRecoveryAttempts} times in a row (${reason}); waiting for a server-side edit to retry.`;
+      const message = `Backend exited ${this.#backendRecoveryAttempts} times in a row (${reason}); waiting for an edit or a green build to retry.`;
+      this.#backendGaveUp = true;
       this.#setBackendLifecycleState("stopped", `gave up after ${this.#backendRecoveryAttempts} recovery attempts`);
       this.logger.error(`[backend-recovery] ${message}`);
       if (this.#backendStderrTail.length > 0) {
@@ -576,6 +639,7 @@ export class AkanAppHost {
     if (message.type === "build-status") {
       this.#recordBuildStatus(message.data);
       this.#sendOrQueueBuildStatus(message.data);
+      this.#reviveBackendAfterGreenBuild(message.data);
       return;
     }
     if (message.type === "pages-updated") this.#recordLastGood(message);
@@ -590,19 +654,25 @@ export class AkanAppHost {
     this.#logDevPlan(message);
     // Config changes subsume builder restarts: the dev-host restart recycles builder and backend
     // AND re-runs the prepare step, so check it first when a batch carries both actions.
-    if (shouldRestartDevHostByDevPlan(message)) {
-      try {
-        await this.#restartDevHost(message);
-      } catch (err) {
-        this.#recordDevHostRestartFailure(message, err, "Config");
+    const wantsDevHostRestart = shouldRestartDevHostByDevPlan(message);
+    const pending = this.#pendingRecycle;
+    // A pending (deferred) recycle rides along on the next code batch — that batch is where the
+    // fix lands; css-only batches cannot heal a compile error, so they never resume it.
+    if (wantsDevHostRestart || shouldRestartBuilderByDevPlan(message) || (pending && message.kinds.includes("code"))) {
+      const refreshConfig = wantsDevHostRestart || (pending?.refreshConfig ?? false);
+      const merged = pending ? mergeInvalidateMessages(pending.message, message) : message;
+      const generation = message.devPlan?.generation ?? message.generation;
+      if (hasBuildFailureForGeneration(this.#buildStatusByPhase, generation)) {
+        this.#deferRecycle(merged, { refreshConfig, generation });
+        return;
       }
-      return;
-    }
-    if (shouldRestartBuilderByDevPlan(message)) {
+      this.#pendingRecycle = null;
       try {
-        await this.#restartDevChildren(message);
+        if (refreshConfig) await this.#restartDevHost(merged);
+        else await this.#restartDevChildren(merged);
       } catch (err) {
-        this.#recordDevHostRestartFailure(message, err, "Runtime metadata");
+        this.#recordDevHostRestartFailure(merged, err, refreshConfig ? "Config" : "Runtime metadata");
+        this.#resurrectDevChildren(merged);
       }
       return;
     }
@@ -612,6 +682,79 @@ export class AkanAppHost {
     }
     this.#sendToBackend(message);
   }
+  #deferRecycle(
+    message: Extract<BuilderMessage, { type: "invalidate" }>,
+    { refreshConfig, generation }: { refreshConfig: boolean; generation?: number },
+  ): void {
+    this.#pendingRecycle = { message, refreshConfig };
+    const kind = refreshConfig ? "Config" : "Runtime metadata";
+    this.logger.warn(
+      `[dev-host] ${kind.toLowerCase()} restart deferred generation=${generation ?? "(unknown)"}; keeping the running dev server until the build error is fixed`,
+    );
+    const status: DevBuildStatus = {
+      generation: generation ?? this.#nextBackendBuildStatusGeneration(),
+      phase: "scan",
+      ok: false,
+      files: message.files,
+      message: `${kind} change is on hold while the build is failing; it will apply automatically once the error is fixed.`,
+    };
+    this.#recordBuildStatus(status);
+    this.#sendOrQueueBuildStatus(status);
+  }
+  /**
+   * A failed recycle must never leave the dev server dead: bring the backend back up on the
+   * last-good artifact so the error overlay stays reachable, and keep retrying the builder —
+   * the builder is the file watcher, so without it no edit could ever trigger a recovery.
+   */
+  #resurrectDevChildren(message: Extract<BuilderMessage, { type: "invalidate" }>): void {
+    const generation = message.devPlan?.generation ?? message.generation;
+    if (!this.#backend) this.#startBackend({ generation, files: message.files });
+    this.#scheduleBuilderRecovery({ generation, files: message.files });
+  }
+  #scheduleBuilderRecovery(reason: { generation?: number; files: string[] }): void {
+    if (this.#builderRecoveryTimer || this.#builder) return;
+    const attempt = this.#builderRecoveryAttempts;
+    const delay = Math.min(BUILDER_RECOVERY_BASE_DELAY_MS * 2 ** attempt, BUILDER_RECOVERY_MAX_DELAY_MS);
+    this.#builderRecoveryAttempts = attempt + 1;
+    this.logger.warn(
+      `[builder-recovery] builder is down; retrying start in ${delay}ms (attempt ${this.#builderRecoveryAttempts})`,
+    );
+    this.#builderRecoveryTimer = setTimeout(() => {
+      this.#builderRecoveryTimer = null;
+      if (this.#builder) return;
+      void this.#recoverBuilder(reason);
+    }, delay);
+  }
+  async #recoverBuilder(reason: { generation?: number; files: string[] }): Promise<void> {
+    try {
+      await this.#startBuilder();
+    } catch (err) {
+      this.logger.warn(`[builder-recovery] builder start failed: ${err instanceof Error ? err.message : String(err)}`);
+      this.#scheduleBuilderRecovery(reason);
+      return;
+    }
+    this.#builderRecoveryAttempts = 0;
+    this.logger.info("[builder-recovery] builder recovered");
+    const status: DevBuildStatus = {
+      generation: reason.generation ?? this.#nextBackendBuildStatusGeneration(),
+      phase: "scan",
+      ok: true,
+      files: reason.files,
+      message: "Builder recovered",
+    };
+    this.#recordBuildStatus(status);
+    this.#sendOrQueueBuildStatus(status);
+    if (!this.#backend && !this.#backendRecoveryTimer) {
+      this.#startBackend({ generation: reason.generation, files: reason.files });
+    }
+  }
+  /** A backend that gave up recovering on broken code gets one fresh chance whenever a build goes green. */
+  #reviveBackendAfterGreenBuild(status: DevBuildStatus): void {
+    if (!status.ok || !this.#backendGaveUp || this.#backend || this.#backendRecoveryTimer) return;
+    this.logger.info(`[backend-recovery] build went green (generation=${status.generation}); retrying backend`);
+    this.#backendRecoveryAttempts = 0;
+    this.#startBackend({ generation: status.generation, files: status.files });
+  }
   async #restartDevChildren(message: Extract<BuilderMessage, { type: "invalidate" }>): Promise<void> {
     const generation = message.devPlan?.generation ?? message.generation;
     this.logger.warn(
@@ -646,6 +789,11 @@ export class AkanAppHost {
       clearTimeout(this.#backendRecoveryTimer);
       this.#backendRecoveryTimer = null;
     }
+    if (this.#builderRecoveryTimer) {
+      clearTimeout(this.#builderRecoveryTimer);
+      this.#builderRecoveryTimer = null;
+    }
+    this.#builderRecoveryAttempts = 0;
     this.#pendingRestartReason = null;
     this.#lastGoodFrontend = {};
     this.#buildStatusByPhase.clear();
@@ -693,7 +841,7 @@ export class AkanAppHost {
       phase: "scan",
       ok: false,
       files: message.files,
-      message: `${kind} change requires restarting \`akan start\` to apply: ${detail}`,
+      message: `${kind} change failed to apply; recovering the dev server automatically: ${detail}`,
     };
     this.#recordBuildStatus(status);
     this.#sendOrQueueBuildStatus(status);

package/akanConfig/akanConfig.test.ts

@@ -4,7 +4,7 @@ import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import type { PackageJson } from "../types";
-import { AkanAppConfig, AkanLibConfig } from "./akanConfig";
+import { AkanAppConfig, AkanLibConfig, deriveDefaultAppId } from "./akanConfig";
 import type { DeepPartial, LibConfigResult } from "./types";
 
 const akanPackageJson = JSON.parse(
@@ -48,14 +48,14 @@ describe("AkanAppConfig", () => {
     expect(config.images.formats).toEqual(["image/webp"]);
     expect(config.mobile).toMatchObject({
       appName: "portal",
-      appId: "com.portal.app",
+      appId: "com.akanjs.portal",
       version: "0.0.1",
       buildNum: 1,
       targets: {
         default: {
           name: "default",
           appName: "portal",
-          appId: "com.portal.app",
+          appId: "com.akanjs.portal",
           version: "0.0.1",
           buildNum: 1,
         },
@@ -368,6 +368,28 @@ describe("AkanAppConfig", () => {
         ),
     ).toThrow("unknown basePath");
   });
+
+  test("derives a repo-scoped default appId and records explicit-mobile intent", () => {
+    // No mobile section: appId defaults to the repo-scoped reverse-DNS id, and mobile is not explicit.
+    const withoutMobile = new AkanAppConfig(app, [], packageJson, {}, baseDevEnv);
+    expect(withoutMobile.mobile.appId).toBe("com.akanjs.portal");
+    expect(withoutMobile.hasMobileConfig).toBe(false);
+
+    // Explicit mobile section without appId still uses the repo-scoped default but marks intent.
+    const withMobile = new AkanAppConfig(app, [], packageJson, { mobile: { version: "2.0.0" } }, baseDevEnv);
+    expect(withMobile.mobile.appId).toBe("com.akanjs.portal");
+    expect(withMobile.hasMobileConfig).toBe(true);
+  });
+});
+
+describe("deriveDefaultAppId", () => {
+  test("sanitizes org/app names into a valid reverse-DNS bundle id", () => {
+    expect(deriveDefaultAppId("leading-flight-guidance", "myapp")).toBe("com.leadingflightguidance.myapp");
+    expect(deriveDefaultAppId("Acme Corp", "Store")).toBe("com.acmecorp.store");
+    // Empty org and digit-leading segments stay valid package identifiers.
+    expect(deriveDefaultAppId("", "app")).toBe("com.app.app");
+    expect(deriveDefaultAppId("123repo", "9app")).toBe("com.app123repo.app9app");
+  });
 });
 
 describe("AkanLibConfig", () => {

package/akanConfig/akanConfig.ts

@@ -123,6 +123,21 @@ const normalizeStringList = (values: string[] | undefined) => {
   return normalized.length > 0 ? [...new Set(normalized)] : undefined;
 };
 
+// Reduce a free-form name to a valid reverse-DNS / Android package segment: lowercase, alphanumerics
+// only (hyphens/spaces dropped), never empty, never starting with a digit.
+const sanitizeAppIdSegment = (value: string): string => {
+  const cleaned = value.toLowerCase().replace(/[^a-z0-9]+/g, "");
+  if (!cleaned) return "app";
+  return /^[a-z]/.test(cleaned) ? cleaned : `app${cleaned}`;
+};
+
+// The default mobile bundle id for an app that has not pinned `mobile.appId`. Uses the workspace
+// (repo) name as the org segment so the default is far less collision-prone than a bare
+// `com.<appName>.app`, which Apple's portal routinely already has claimed. Apps that ship pin an
+// explicit appId, so this only affects unconfigured/dev apps.
+export const deriveDefaultAppId = (orgName: string, appName: string): string =>
+  `com.${sanitizeAppIdSegment(orgName)}.${sanitizeAppIdSegment(appName)}`;
+
 const normalizeDeepLinkDomain = (domain: string) => {
   const normalized = domain.trim();
   if (!normalized) return "";
@@ -164,6 +179,8 @@ export class AkanAppConfig implements AppConfigResult {
   i18n: AkanI18nConfig;
   publicEnv: string[];
   mobile: AkanMobileConfig;
+  /** True only when the app's akan.config.ts explicitly declares a `mobile` section (vs. the synthesized default). */
+  hasMobileConfig: boolean;
   secrets: string[];
   baseDevEnv: BaseDevEnv;
   libs: string[];
@@ -202,6 +219,7 @@ export class AkanAppConfig implements AppConfigResult {
     process.env.AKAN_PUBLIC_LOCALES = this.i18n.locales.join(",");
     this.publicEnv = (config?.publicEnv as string[] | undefined) ?? ([] as string[]);
     this.secrets = (config?.secrets as string[] | undefined) ?? ([] as string[]);
+    this.hasMobileConfig = Boolean(config.mobile);
     this.mobile = this.#resolveMobileConfig(config.mobile);
     this.docker = this.#makeDockerContent(config?.docker ?? {});
   }
@@ -212,7 +230,7 @@ export class AkanAppConfig implements AppConfigResult {
       ...rawMobile
     } = (mobile ?? {}) as DeepPartial<AkanMobileConfig> & { indexPath?: unknown };
     const appName = rawMobile.appName ?? this.app.name;
-    const appId = rawMobile.appId ?? `com.${this.app.name}.app`;
+    const appId = rawMobile.appId ?? deriveDefaultAppId(this.baseDevEnv.repoName, this.app.name);
     const version = rawMobile.version ?? "0.0.1";
     const buildNum = rawMobile.buildNum ?? 1;
     const defaultTargetName = this.#defaultMobileTargetName(rawTargets);

package/capacitorApp.test.ts

@@ -12,12 +12,17 @@ import {
   formatAndroidReleaseSigningError,
   getAdbDeviceStateIssues,
   getMissingAndroidReleaseSigningKeys,
+  isPlaceholderAppId,
   materializeCapacitorConfig,
   parseDevicectlDevices,
+  parseIosRuntimeMajor,
   parseSimctlDevices,
   raiseGradleMinSdkVersion,
   rootCapacitorConfigFilenames,
+  SWIFTUICORE_MIN_IOS_MAJOR,
   sanitizeIosNativeRunEnv,
+  selectLocalDevHost,
+  sortIosRunTargets,
   writeRootCapacitorConfig,
 } from "./capacitorApp";
 
@@ -182,17 +187,42 @@ describe("iOS native run helpers", () => {
       parseSimctlDevices(
         JSON.stringify({
           devices: {
-            "iOS 18.0": [
+            "com.apple.CoreSimulator.SimRuntime.iOS-18-2": [
               { udid: "11111111-2222-3333-4444-555555555555", name: "iPhone 16", state: "Shutdown", isAvailable: true },
             ],
           },
         }),
       ),
     ).toEqual([
-      { id: "11111111-2222-3333-4444-555555555555", name: "iPhone 16", kind: "simulator", state: "Shutdown" },
+      {
+        id: "11111111-2222-3333-4444-555555555555",
+        name: "iPhone 16",
+        kind: "simulator",
+        state: "Shutdown",
+        runtime: "iOS 18.2",
+      },
     ]);
   });
 
+  test("sorts run targets so booted / connected / newest-runtime targets come first", () => {
+    const ios17 = { id: "a", name: "iPhone 15", kind: "simulator" as const, state: "Shutdown", runtime: "iOS 17.5" };
+    const ios18 = { id: "b", name: "iPhone 16", kind: "simulator" as const, state: "Shutdown", runtime: "iOS 18.2" };
+    const booted17 = { id: "c", name: "iPhone SE", kind: "simulator" as const, state: "Booted", runtime: "iOS 17.0" };
+    const device = { id: "d", name: "Seok iPhone", kind: "device" as const, state: "available wired paired" };
+    // Input is in the old ascending-runtime order that used to default to iOS 17.
+    const sorted = sortIosRunTargets([ios17, ios18, booted17, device]);
+    expect(sorted.map((t) => t.id)).toEqual(["d", "c", "b", "a"]);
+    // Newest available simulator beats the older one, so the interactive default is no longer iOS 17.
+    expect(sortIosRunTargets([ios17, ios18]).map((t) => t.id)).toEqual(["b", "a"]);
+  });
+
+  test("parses the major iOS runtime version", () => {
+    expect(parseIosRuntimeMajor("iOS 18.2")).toBe(18);
+    expect(parseIosRuntimeMajor("iOS 17.5")).toBe(17);
+    expect(parseIosRuntimeMajor(undefined)).toBeUndefined();
+    expect(SWIFTUICORE_MIN_IOS_MAJOR).toBe(18);
+  });
+
   test("builds xcodebuild destinations and output paths by target kind", () => {
     const deviceCommand = buildIosNativeRunCommand({
       appRoot: "/repo/apps/minimal",
@@ -228,6 +258,11 @@ describe("iOS native run helpers", () => {
     expect(classifyIosRunFailure("arm64-apple-darwin20.0: error: unknown argument: '-index-store-path'").kind).toBe(
       "compiler-toolchain",
     );
+    expect(
+      classifyIosRunFailure(
+        "dyld[1234]: Library not loaded: /System/Library/Frameworks/SwiftUICore.framework/SwiftUICore",
+      ).kind,
+    ).toBe("simulator-runtime");
   });
 
   test("removes shell compiler variables from iOS native run env", () => {
@@ -240,6 +275,55 @@ describe("iOS native run helpers", () => {
       }),
     ).toEqual({ AKAN_PUBLIC_APP_NAME: "minimal" });
   });
+
+  test("flags placeholder bundle identifiers that Apple's portal already claims", () => {
+    for (const appId of ["com.myapp.app", "com.myorg.myapp", "com.example.foo", "com.changeme.app", ""]) {
+      expect(isPlaceholderAppId(appId)).toBe(true);
+    }
+    for (const appId of ["com.minimal.app", "com.nearthlab.leadingflight", "io.akanjs.demo"]) {
+      expect(isPlaceholderAppId(appId)).toBe(false);
+    }
+  });
+});
+
+describe("selectLocalDevHost", () => {
+  const build = (map: Record<string, { family: string; address: string; internal?: boolean }[]>) =>
+    map as unknown as Parameters<typeof selectLocalDevHost>[0];
+
+  test("prefers a routable LAN NIC over an inactive bridge enumerated first", () => {
+    const resolution = selectLocalDevHost(
+      build({
+        bridge0: [{ family: "IPv4", address: "192.168.2.1" }],
+        en0: [{ family: "IPv4", address: "172.25.140.140" }],
+        bridge100: [{ family: "IPv4", address: "192.168.3.1" }],
+        en8: [{ family: "IPv4", address: "172.25.40.227" }],
+      }),
+    );
+    expect(resolution.host).toBe("172.25.140.140");
+    expect(resolution.source).toBe("detected");
+  });
+
+  test("an explicit override always wins and is trimmed", () => {
+    const resolution = selectLocalDevHost(build({ en0: [{ family: "IPv4", address: "172.25.140.140" }] }), {
+      override: " 10.0.0.9 ",
+    });
+    expect(resolution).toMatchObject({ host: "10.0.0.9", source: "override" });
+  });
+
+  test("never selects a link-local address when a real LAN address exists", () => {
+    const resolution = selectLocalDevHost(
+      build({
+        en0: [{ family: "IPv4", address: "169.254.10.10" }],
+        en1: [{ family: "IPv4", address: "192.168.1.5" }],
+      }),
+    );
+    expect(resolution.host).toBe("192.168.1.5");
+  });
+
+  test("falls back to loopback when nothing routable is present", () => {
+    const resolution = selectLocalDevHost(build({ lo0: [{ family: "IPv4", address: "127.0.0.1", internal: true }] }));
+    expect(resolution).toMatchObject({ host: "127.0.0.1", source: "loopback" });
+  });
 });
 
 describe("Android signing diagnostics", () => {

package/capacitorApp.ts

@@ -34,6 +34,8 @@ export interface IosRunTarget {
   name: string;
   kind: IosRunTargetKind;
   state?: string;
+  /** Display runtime for simulators, e.g. "iOS 18.2". Undefined for physical devices. */
+  runtime?: string;
   devicectlId?: string;
   xcodebuildId?: string;
 }
@@ -56,8 +58,13 @@ export type IosRunFailureKind =
   | "device-registration"
   | "device-state"
   | "devicectl-unavailable"
+  | "simulator-runtime"
   | "unknown";
 
+// Recent iOS SDKs (iOS 18+) split SwiftUI into a SwiftUICore dylib that does not exist on older
+// runtimes, so an app built against them dyld-crashes at launch on an iOS <18 simulator/device.
+export const SWIFTUICORE_MIN_IOS_MAJOR = 18;
+
 export interface IosRunFailureClassification {
   kind: IosRunFailureKind;
   title: string;
@@ -113,15 +120,75 @@ interface MaterializeCapacitorConfigOptions {
   localIp?: string;
 }
 
-const getLocalIP = () => {
-  const interfaces = os.networkInterfaces();
-  for (const iface of Object.values(interfaces)) {
-    if (!iface) continue;
-    for (const alias of iface) {
-      if (alias.family === "IPv4" && !alias.internal) return alias.address;
+export interface LocalDevHostResolution {
+  host: string;
+  source: "override" | "detected" | "loopback";
+  candidates: { name: string; address: string }[];
+}
+
+// Interface-name prefixes that are almost never the routable LAN NIC a physical device can reach:
+// bridges (Thunderbolt/USB), tunnels, AirDrop/awrl, VM/container virtual adapters.
+const virtualInterfacePrefixes = [
+  "bridge",
+  "utun",
+  "llw",
+  "awdl",
+  "ap",
+  "vmnet",
+  "vnic",
+  "tap",
+  "tun",
+  "docker",
+  "veth",
+  "vboxnet",
+  "gif",
+  "stf",
+];
+const physicalInterfacePrefixes = ["en", "eth", "wlan", "wlp", "enp", "eno", "wlo"];
+
+const isPrivateLanIpv4 = (address: string): boolean => {
+  if (address.startsWith("10.") || address.startsWith("192.168.")) return true;
+  const secondOctet = Number(address.match(/^172\.(\d+)\./)?.[1]);
+  return Number.isFinite(secondOctet) && secondOctet >= 16 && secondOctet <= 31;
+};
+
+// Higher = more likely to be the reachable LAN address. Link-local (169.254) is never routable;
+// virtual/bridge interfaces are demoted below real NICs; private-LAN ranges get a small boost.
+const scoreDevHostCandidate = (name: string, address: string): number => {
+  const lowerName = name.toLowerCase();
+  let score = 0;
+  if (address.startsWith("169.254.")) score -= 1000;
+  if (virtualInterfacePrefixes.some((prefix) => lowerName.startsWith(prefix))) score -= 100;
+  else if (physicalInterfacePrefixes.some((prefix) => lowerName.startsWith(prefix))) score += 100;
+  if (isPrivateLanIpv4(address)) score += 10;
+  return score;
+};
+
+// Pick the dev-server host a physical device should connect to. An explicit override always wins;
+// otherwise rank non-internal IPv4 interfaces so a down/virtual interface (e.g. an inactive
+// Thunderbolt bridge enumerated first) never shadows a real LAN NIC. Deterministic tie-break.
+export const selectLocalDevHost = (
+  interfaces: NodeJS.Dict<os.NetworkInterfaceInfo[]>,
+  { override }: { override?: string } = {},
+): LocalDevHostResolution => {
+  const candidates: { name: string; address: string }[] = [];
+  for (const [name, aliases] of Object.entries(interfaces)) {
+    for (const alias of aliases ?? []) {
+      if (alias.family !== "IPv4" || alias.internal) continue;
+      candidates.push({ name, address: alias.address });
     }
   }
-  return "127.0.0.1";
+  const trimmedOverride = override?.trim();
+  if (trimmedOverride) return { host: trimmedOverride, source: "override", candidates };
+  const [best] = [...candidates].sort(
+    (a, b) =>
+      scoreDevHostCandidate(b.name, b.address) - scoreDevHostCandidate(a.name, a.address) ||
+      a.name.localeCompare(b.name) ||
+      a.address.localeCompare(b.address),
+  );
+  return best
+    ? { host: best.address, source: "detected", candidates }
+    : { host: "127.0.0.1", source: "loopback", candidates };
 };
 
 const isRecord = (value: unknown): value is Record<string, unknown> =>
@@ -147,6 +214,38 @@ const dedupeIosRunTargets = (targets: IosRunTarget[]) => {
   return [...byKey.values()];
 };
 
+// Normalize a simctl runtime — either the JSON key ("com.apple.CoreSimulator.SimRuntime.iOS-18-2")
+// or a per-device `runtimeIdentifier` / text header ("iOS 18.2") — into a "iOS 18.2" display string.
+const formatSimctlRuntime = (key?: string): string | undefined => {
+  if (!key) return undefined;
+  if (/^(iOS|watchOS|tvOS|visionOS)\s+[\d.]+$/i.test(key)) return key;
+  const match = key.match(/(iOS|watchOS|tvOS|visionOS)-(\d+)(?:-(\d+))?/i);
+  if (!match) return undefined;
+  return `${match[1]} ${match[2]}${match[3] ? `.${match[3]}` : ""}`;
+};
+
+// Extract the major OS version from a runtime display string ("iOS 18.2" → 18). Undefined for
+// physical devices (no runtime) or unparseable values.
+export const parseIosRuntimeMajor = (runtime?: string): number | undefined => {
+  const major = runtime?.match(/(\d+)/)?.[1];
+  if (major === undefined) return undefined;
+  const parsed = Number.parseInt(major, 10);
+  return Number.isNaN(parsed) ? undefined : parsed;
+};
+
+// Rank for default-target ordering: ready targets (booted simulator / connected device) first, then
+// physical devices, then newer simulator runtimes. Fixes the old ascending-runtime order that made a
+// stale iOS 17.x simulator the default pick.
+const iosRunTargetRank = (target: IosRunTarget): number => {
+  const state = target.state?.toLowerCase() ?? "";
+  const ready = state.includes("booted") || state.includes("connected") || state.includes("available") ? 1000 : 0;
+  const device = target.kind === "device" ? 500 : 0;
+  return ready + device + (parseIosRuntimeMajor(target.runtime) ?? 0);
+};
+
+export const sortIosRunTargets = (targets: IosRunTarget[]): IosRunTarget[] =>
+  [...targets].sort((a, b) => iosRunTargetRank(b) - iosRunTargetRank(a) || a.name.localeCompare(b.name));
+
 function walkRecords(value: unknown, visit: (record: Record<string, unknown>) => void) {
   if (Array.isArray(value)) {
     for (const item of value) walkRecords(item, visit);
@@ -202,22 +301,36 @@ export function parseSimctlDevices(output: string): IosRunTarget[] {
   try {
     const json = JSON.parse(output) as { devices?: Record<string, unknown[]> };
     const devices = json.devices ?? {};
-    return Object.values(devices)
-      .flat()
-      .filter(isRecord)
-      .flatMap((device) => {
+    return Object.entries(devices).flatMap(([runtimeKey, list]) => {
+      const runtime = formatSimctlRuntime(runtimeKey);
+      return (Array.isArray(list) ? list : []).filter(isRecord).flatMap((device) => {
         const id = firstString(device.udid, device.UDID, device.identifier);
         const name = firstString(device.name, device.displayName);
         const isAvailable = device.isAvailable !== false && device.availabilityError === undefined;
         if (!id || !name || !isAvailable) return [];
-        return [{ id, name, kind: "simulator" as const, state: asString(device.state) }];
+        return [
+          {
+            id,
+            name,
+            kind: "simulator" as const,
+            state: asString(device.state),
+            runtime: runtime ?? formatSimctlRuntime(asString(device.runtimeIdentifier)),
+          },
+        ];
       });
+    });
   } catch {
     const targets: IosRunTarget[] = [];
+    let runtime: string | undefined;
     for (const line of output.split(/\r?\n/)) {
+      const header = line.match(/^--\s*(.+?)\s*--\s*$/);
+      if (header) {
+        runtime = formatSimctlRuntime(header[1]);
+        continue;
+      }
       const match = line.match(/^\s*(.+?)\s+\(([0-9A-Fa-f-]{20,})\)\s+\(([^)]+)\)/);
       if (!match) continue;
-      targets.push({ id: match[2], name: match[1].trim(), kind: "simulator", state: match[3] });
+      targets.push({ id: match[2], name: match[1].trim(), kind: "simulator", state: match[3], runtime });
     }
     return targets;
   }
@@ -260,6 +373,16 @@ export function buildIosNativeRunCommand({
 
 export function classifyIosRunFailure(log: string): IosRunFailureClassification {
   const lower = log.toLowerCase();
+  if (
+    lower.includes("swiftuicore") &&
+    (lower.includes("library not loaded") || lower.includes("library missing") || lower.includes("dyld"))
+  ) {
+    return {
+      kind: "simulator-runtime",
+      title: "App crashed loading SwiftUICore — the iOS runtime is too old.",
+      detail: `The build links SwiftUICore, which only exists on iOS ${SWIFTUICORE_MIN_IOS_MAJOR}+. Rerun on an iOS ${SWIFTUICORE_MIN_IOS_MAJOR} or newer simulator/device (pass --device to pick one non-interactively).`,
+    };
+  }
   if (lower.includes("unknown argument: '-index-store-path'") || lower.includes("compiler was not recognized")) {
     return {
       kind: "compiler-toolchain",
@@ -379,6 +502,24 @@ export function sanitizeIosNativeRunEnv(env: MobileCommandEnv): MobileCommandEnv
   return Object.fromEntries(Object.entries(env).filter(([key]) => !iosNativeBlockedEnvKeys.has(key)));
 }
 
+// Bundle IDs that ship as scaffold placeholders (or use an obviously generic org segment) and are
+// almost always already claimed on Apple's developer portal, so device signing fails with
+// "cannot be registered to your development team". A unique reverse-DNS id fixes it.
+export const PLACEHOLDER_APP_IDS = [
+  "com.myapp.app",
+  "com.myorg.myapp",
+  "com.example.app",
+  "com.example.myapp",
+] as const;
+const placeholderAppIdSegment = /^(example|examples|myorg|myapp|mycompany|myorganization|changeme|todo|sample|test)$/;
+
+export const isPlaceholderAppId = (appId: string | null | undefined): boolean => {
+  const normalized = appId?.trim().toLowerCase() ?? "";
+  if (!normalized) return true;
+  if ((PLACEHOLDER_APP_IDS as readonly string[]).includes(normalized)) return true;
+  return normalized.split(".").some((segment) => placeholderAppIdSegment.test(segment));
+};
+
 const androidReleaseSigningKeys = [
   "MYAPP_RELEASE_STORE_FILE",
   "MYAPP_RELEASE_STORE_PASSWORD",
@@ -651,22 +792,46 @@ export class CapacitorApp {
   }
 
   async #selectIosRunTarget(deviceId?: string) {
-    const targets = await this.#loadIosRunTargets();
+    const targets = sortIosRunTargets(await this.#loadIosRunTargets());
     if (deviceId) {
-      const found = targets.find((target) => target.id === deviceId);
-      if (!found) throw new Error(`iOS run target '${deviceId}' was not found.`);
+      const needle = deviceId.toLowerCase();
+      const found =
+        targets.find((target) => target.id === deviceId) ??
+        targets.find((target) => target.name.toLowerCase() === needle) ??
+        targets.find(
+          (target) =>
+            target.name.toLowerCase().includes(needle) ||
+            target.id.toLowerCase().includes(needle) ||
+            (target.runtime?.toLowerCase().includes(needle) ?? false),
+        );
+      if (!found) {
+        const available = targets.map((t) => `${t.name}${t.runtime ? ` (${t.runtime})` : ""}`).join(", ") || "none";
+        throw new Error(`iOS run target '${deviceId}' was not found. Available: ${available}`);
+      }
+      this.#warnIfLegacySimulatorRuntime(found);
       return found;
     }
     if (targets.length === 0) {
       throw new Error("No iOS run targets found. Open Simulator or connect an iPhone, then retry.");
     }
-    return await select<IosRunTarget>({
+    const selected = await select<IosRunTarget>({
       message: "Select iOS run target",
       choices: targets.map((target) => ({
-        name: `[${target.kind}] ${target.name}${target.state ? ` (${target.state})` : ""}`,
+        name: `[${target.kind}] ${target.name}${target.runtime ? ` — ${target.runtime}` : ""}${target.state ? ` (${target.state})` : ""}`,
         value: target,
       })),
     });
+    this.#warnIfLegacySimulatorRuntime(selected);
+    return selected;
+  }
+
+  #warnIfLegacySimulatorRuntime(target: IosRunTarget) {
+    if (target.kind !== "simulator") return;
+    const major = parseIosRuntimeMajor(target.runtime);
+    if (major === undefined || major >= SWIFTUICORE_MIN_IOS_MAJOR) return;
+    this.app.logger.warn(
+      `Selected simulator runs ${target.runtime ?? "an older iOS"}. Recent SDK builds link SwiftUICore and require iOS ${SWIFTUICORE_MIN_IOS_MAJOR}+; if the app crashes at launch with a "Library not loaded: SwiftUICore" dyld error, pick an iOS ${SWIFTUICORE_MIN_IOS_MAJOR}+ simulator instead.`,
+    );
   }
 
   async #loadIosRunTargets() {
@@ -937,7 +1102,13 @@ export class CapacitorApp {
   }
   async #writeCapacitorConfig({ operation }: Pick<RunConfig, "operation">, commandEnv: MobileCommandEnv) {
     await mkdir(this.targetRoot, { recursive: true });
-    const localIp = operation === "local" ? getLocalIP() : undefined;
+    let localIp: string | undefined;
+    if (operation === "local") {
+      const override = commandEnv.AKAN_PUBLIC_CLIENT_HOST ?? process.env.AKAN_PUBLIC_CLIENT_HOST;
+      const resolution = selectLocalDevHost(os.networkInterfaces(), { override });
+      localIp = resolution.host;
+      this.#logDevHostResolution(resolution, commandEnv);
+    }
     const config = materializeCapacitorConfig(this.target, {
       operation,
       localIp,
@@ -947,6 +1118,21 @@ export class CapacitorApp {
     await Bun.write(path.join(this.targetRoot, "capacitor.config.json"), content);
     return content;
   }
+  // Surface the live-reload URL a physical device must reach, and warn when auto-detection landed on
+  // a likely-unreachable host so a blank WebView is not mistaken for an app bug.
+  #logDevHostResolution(resolution: LocalDevHostResolution, commandEnv: MobileCommandEnv) {
+    this.app.log(`Mobile live-reload server: ${this.#localCsrUrl(resolution.host, commandEnv)}`);
+    if (resolution.source === "override") return;
+    const suspicious = resolution.host === "127.0.0.1" || resolution.host.startsWith("169.254.");
+    const alternatives = resolution.candidates.filter((candidate) => candidate.address !== resolution.host);
+    if (!suspicious && alternatives.length === 0) return;
+    const alternativeText = alternatives.length
+      ? ` Other interfaces: ${alternatives.map((candidate) => `${candidate.address} (${candidate.name})`).join(", ")}.`
+      : "";
+    this.app.logger.warn(
+      `A physical device must reach ${resolution.host} on your LAN.${suspicious ? " That address looks non-routable." : ""}${alternativeText} If the device shows a blank screen, pin the right one with AKAN_PUBLIC_CLIENT_HOST=<ip>.`,
+    );
+  }
   async #prepareTargetAssets() {
     if (!this.target.assets) return;
     await mkdir(this.targetAssetRoot, { recursive: true });

package/incrementalBuilder/incrementalBuilder.proc.ts

@@ -36,8 +36,14 @@ interface IncrementalBuilderOptions {
   cssCompiler: CssCompiler;
   optimizedFonts: Awaited<ReturnType<FontOptimizer["optimize"]>>;
   discovery: ClientEntryDiscovery;
+  initialGeneration?: number;
 }
 
+type IncrementalBuilderBootDeps = Pick<
+  IncrementalBuilderOptions,
+  "artifact" | "cssCompiler" | "optimizedFonts" | "discovery"
+>;
+
 class IncrementalBuilder {
   #logger = new Logger("IncrementalBuilder");
   #app: App;
@@ -62,11 +68,16 @@ class IncrementalBuilder {
     this.#cssCompiler = options.cssCompiler;
     this.#optimizedFonts = options.optimizedFonts;
     this.#discovery = options.discovery;
+    this.#generation = options.initialGeneration ?? 0;
     this.#changePlanner = new DevChangePlanner({ workspaceRoot: options.app.workspace.workspaceRoot });
     this.#generatedIndexSync = new DevGeneratedIndexSync({ workspaceRoot: options.app.workspace.workspaceRoot });
     this.#autoImportSync = new AutoImportSync({ workspaceRoot: options.app.workspace.workspaceRoot });
   }
 
+  get #artifactDir() {
+    return `${this.#app.cwdPath}/.akan/artifact`;
+  }
+
   async handleBuildRoute(msg: BuilderReq): Promise<BuilderRes> {
     return this.#enqueueWork(`build-route:${msg.routeId}`, async () => this.#handleBuildRoute(msg));
   }
@@ -255,7 +266,7 @@ class IncrementalBuilder {
     });
   }
   async installWatcher() {
-    const [appDir, artifactDir] = [`${this.#app.cwdPath}/page`, `${this.#app.cwdPath}/.akan/artifact`];
+    const [appDir, artifactDir] = [`${this.#app.cwdPath}/page`, this.#artifactDir];
     const roots = await new WatchRootResolver(this.#app).resolve();
     const watcher = new HmrWatcher({
       roots,
@@ -365,48 +376,142 @@ class IncrementalBuilder {
   }
 
   async boot(): Promise<void> {
-    process.on("message", async (msg: BuilderMessage) => {
-      if (!msg || typeof msg !== "object") return;
-      switch (msg.type) {
-        case "build-route": {
-          const res = await this.handleBuildRoute(msg);
-          process.send?.(res);
-          return;
-        }
-        default:
-          return;
-      }
-    });
-    // The IPC channel closes when the dev host dies (including SIGKILL); exit instead of running
-    // as an orphaned watcher that keeps rebuilding for nobody.
-    process.on("disconnect", () => {
-      this.#logger.warn("host IPC channel closed; exiting builder");
-      process.exit(0);
-    });
     if (this.#watch) await this.installWatcher();
     process.send?.({ type: "builder-ready" });
     this.#logger.verbose(`ready (watch=${this.#watch})`);
   }
 
+  /**
+   * After a degraded boot recovers, the backend is still serving the last-good bundle; push a
+   * fresh pages/css state so connected browsers pick up the fixed code without another edit.
+   */
+  async announceRecoveredState(changedFiles: string[]): Promise<void> {
+    const generation = ++this.#generation;
+    await this.#enqueueWork("boot-recovered", async () => {
+      try {
+        const next = await new PagesBundleBuilder(this.#app).build();
+        process.send?.({
+          type: "pages-updated",
+          data: { bundlePath: next.bundlePath, buildId: next.buildId, generation, changedFiles },
+        });
+        this.#sendBuildStatus("pages", { generation, ok: true, files: changedFiles, message: "Boot build recovered" });
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        this.#logger.error(`recovered pages rebundle failed: ${message}`);
+        this.#sendBuildStatus("pages", { generation, ok: false, files: changedFiles, message });
+      }
+      this.scheduleCssRebuild(this.#artifactDir, { refresh: true, generation, changedFiles });
+    });
+  }
+
   #shouldRebuildCsr() {
     // CSR is served by `akn start`, so rebuild dev CSR artifacts until incremental CSR HMR is implemented.
     return true;
   }
 
-  static async create() {
+  static async #buildBootDeps(app: App): Promise<IncrementalBuilderBootDeps> {
+    const { artifact, cssCompiler, optimizedFonts } = await new SsrBaseArtifactBuilder(app).build();
+    await new CsrArtifactBuilder(app).build();
+    const discovery = await GraphClientEntryDiscovery.create(app);
+    return { artifact, cssCompiler, optimizedFonts, discovery };
+  }
+
+  /**
+   * A compile error in the boot build must not kill the builder: the builder is the dev server's
+   * file watcher, so exiting here leaves nothing to notice the fix. Report the failure, emit
+   * builder-ready so the host keeps the backend serving the last-good artifact, then retry the
+   * boot build on every file change until it succeeds.
+   */
+  static #recoverBoot(
+    app: App,
+    bootError: unknown,
+    logger: Logger,
+  ): Promise<{ builder: IncrementalBuilder; changedFiles: string[] }> {
+    const firstMessage = bootError instanceof Error ? bootError.message : String(bootError);
+    logger.error(`boot build failed; entering degraded watch mode until the error is fixed: ${firstMessage}`);
+    let generation = 0;
+    const sendFailure = (files: string[], message: string) => {
+      process.send?.({
+        type: "build-status",
+        data: { generation, phase: "pages", ok: false, files, message: `Boot build failed: ${message}` },
+      });
+    };
+    sendFailure([], firstMessage);
+    process.send?.({ type: "builder-ready" });
+    return new Promise((resolve, reject) => {
+      void (async () => {
+        const roots = await new WatchRootResolver(app).resolve();
+        const watcher = new HmrWatcher({
+          roots,
+          logger,
+          onBatch: async (batch) => {
+            generation += 1;
+            const files = [...batch.files].sort();
+            try {
+              // A broken akan.config.ts caches its import failure; re-import it before rebuilding.
+              if (new Set(batch.kinds).has("config")) await app.getConfig({ refresh: true });
+              const deps = await IncrementalBuilder.#buildBootDeps(app);
+              const builder = new IncrementalBuilder({ app, watch: true, initialGeneration: generation, ...deps });
+              watcher.stop();
+              logger.info(`boot build recovered generation=${generation}`);
+              resolve({ builder, changedFiles: files });
+            } catch (err) {
+              const message = err instanceof Error ? err.message : String(err);
+              logger.error(`boot build retry failed: ${message}`);
+              sendFailure(files, message);
+            }
+          },
+        });
+        watcher.start();
+        logger.warn(`[degraded] watching ${roots.length} roots for a fix`);
+      })().catch(reject);
+    });
+  }
+
+  static async main(): Promise<void> {
+    const logger = new Logger("IncrementalBuilder");
     const { appName, repoName, workspaceRoot } = WorkspaceExecutor.getBaseDevEnv();
     if (!workspaceRoot || !appName) throw new Error("AKAN_WORKSPACE_ROOT or AKAN_PUBLIC_APP_NAME is not set");
     const workspace = WorkspaceExecutor.fromRoot({ workspaceRoot, repoName });
     const app = AppExecutor.from(workspace, appName);
     const watch = process.env.AKAN_WATCH !== "0";
-    const { artifact, cssCompiler, optimizedFonts } = await new SsrBaseArtifactBuilder(app).build();
-    await new CsrArtifactBuilder(app).build();
-    const discovery = await GraphClientEntryDiscovery.create(app);
-    return new IncrementalBuilder({ app, cssCompiler, artifact, watch, optimizedFonts, discovery });
+    let builder: IncrementalBuilder | null = null;
+    // Registered before the boot build so build-route requests get an error response (instead of
+    // hanging the backend) while the builder is still booting or recovering from a failed build.
+    process.on("message", (msg: BuilderMessage) => {
+      if (!msg || typeof msg !== "object" || msg.type !== "build-route") return;
+      if (!builder) {
+        process.send?.({
+          type: "build-route-res",
+          id: msg.id,
+          ok: false,
+          error: "builder is recovering from a failed boot build; retry after the build error is fixed",
+        });
+        return;
+      }
+      void builder.handleBuildRoute(msg).then((res) => process.send?.(res));
+    });
+    // The IPC channel closes when the dev host dies (including SIGKILL); exit instead of running
+    // as an orphaned watcher that keeps rebuilding for nobody.
+    process.on("disconnect", () => {
+      logger.warn("host IPC channel closed; exiting builder");
+      process.exit(0);
+    });
+    let recoveredFiles: string[] | null = null;
+    try {
+      builder = new IncrementalBuilder({ app, watch, ...(await IncrementalBuilder.#buildBootDeps(app)) });
+    } catch (err) {
+      if (!watch) throw err;
+      const recovered = await IncrementalBuilder.#recoverBoot(app, err, logger);
+      builder = recovered.builder;
+      recoveredFiles = recovered.changedFiles;
+    }
+    await builder.boot();
+    if (recoveredFiles) await builder.announceRecoveredState(recoveredFiles);
   }
 }
 
-void (await IncrementalBuilder.create()).boot().catch((err) => {
+void IncrementalBuilder.main().catch((err) => {
   console.error(err);
   process.exit(1);
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akanjs/devkit",
-  "version": "2.4.0-rc.8",
+  "version": "2.4.0",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -32,7 +32,7 @@
     "@langchain/openai": "^1.4.6",
     "@tailwindcss/node": "^4.3.0",
     "@trapezedev/project": "^7.1.4",
-    "akanjs": "2.4.0-rc.8",
+    "akanjs": "2.4.0",
     "chalk": "^5.6.2",
     "commander": "^14.0.3",
     "daisyui": "5.5.23",