@akanjs/cli 2.4.0-rc.8 → 2.4.0

package/incrementalBuilder.proc.js

@@ -778,6 +778,13 @@ var normalizeStringList = (values) => {
   const normalized = values?.map((value) => value.trim()).filter(Boolean) ?? [];
   return normalized.length > 0 ? [...new Set(normalized)] : undefined;
 };
+var sanitizeAppIdSegment = (value) => {
+  const cleaned = value.toLowerCase().replace(/[^a-z0-9]+/g, "");
+  if (!cleaned)
+    return "app";
+  return /^[a-z]/.test(cleaned) ? cleaned : `app${cleaned}`;
+};
+var deriveDefaultAppId = (orgName, appName) => `com.${sanitizeAppIdSegment(orgName)}.${sanitizeAppIdSegment(appName)}`;
 var normalizeDeepLinkDomain = (domain) => {
   const normalized = domain.trim();
   if (!normalized)
@@ -818,6 +825,7 @@ class AkanAppConfig {
   i18n;
   publicEnv;
   mobile;
+  hasMobileConfig;
   secrets;
   baseDevEnv;
   libs;
@@ -848,6 +856,7 @@ class AkanAppConfig {
     process.env.AKAN_PUBLIC_LOCALES = this.i18n.locales.join(",");
     this.publicEnv = config?.publicEnv ?? [];
     this.secrets = config?.secrets ?? [];
+    this.hasMobileConfig = Boolean(config.mobile);
     this.mobile = this.#resolveMobileConfig(config.mobile);
     this.docker = this.#makeDockerContent(config?.docker ?? {});
   }
@@ -858,7 +867,7 @@ class AkanAppConfig {
       ...rawMobile
     } = mobile ?? {};
     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);
@@ -4324,6 +4333,8 @@ var BACKEND_RECOVERY_MAX_ATTEMPTS = 5;
 var BACKEND_STDERR_TAIL_LIMIT = 40;
 var BUILDER_READY_TIMEOUT_MS = 150000;
 var BUILDER_START_MAX_ATTEMPTS = 3;
+var BUILDER_RECOVERY_BASE_DELAY_MS = 2000;
+var BUILDER_RECOVERY_MAX_DELAY_MS = 60000;
 var SOURCE_EXTS = new Set([".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"]);
 var 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;
 var SERVER_SUFFIXES = [".service.ts", ".document.ts"];
@@ -4400,6 +4411,43 @@ var mergeBackendRestartReasons = (current, next) => ({
 });
 var shouldReplaceLastGoodMessage = (current, next) => !current || generationValue(next.data.generation) >= generationValue(current.data.generation);
 var shouldQueueBuildStatusReplay = (backendReady, pendingReplayCount) => !backendReady || pendingReplayCount > 0;
+var hasBuildFailureForGeneration = (statusByPhase, generation) => {
+  if (typeof generation !== "number")
+    return false;
+  for (const status of statusByPhase.values()) {
+    if (!status.ok && status.generation === generation)
+      return true;
+  }
+  return false;
+};
+var mergeDevPlans = (current, next) => {
+  if (!current)
+    return next;
+  if (!next)
+    return current;
+  const reasonByFile = { ...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
+  };
+};
+var mergeInvalidateMessages = (current, next) => {
+  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)
+  };
+};
 var buildStatusReplaySequence = (pendingReplay, latestByPhase) => [...pendingReplay, ...latestByPhase.values()];
 
 class BackendImportGraph {
@@ -4522,8 +4570,12 @@ class AkanAppHost {
   #restartTimer = null;
   #backendRecoveryTimer = null;
   #backendRecoveryAttempts = 0;
+  #backendGaveUp = false;
   #backendLifecycleState = "stopped";
   #pendingRestartReason = null;
+  #pendingRecycle = null;
+  #builderRecoveryTimer = null;
+  #builderRecoveryAttempts = 0;
   #backendStartStatus = null;
   #backendBuildStatusGeneration = 0;
   #backendStderrTail = [];
@@ -4561,6 +4613,10 @@ class AkanAppHost {
       clearTimeout(this.#backendRecoveryTimer);
       this.#backendRecoveryTimer = null;
     }
+    if (this.#builderRecoveryTimer) {
+      clearTimeout(this.#builderRecoveryTimer);
+      this.#builderRecoveryTimer = null;
+    }
     await this.#stopBackend();
     this.#stopBuilder();
     return this;
@@ -4576,6 +4632,7 @@ class AkanAppHost {
   }
   #startBackend(startStatus = null) {
     this.#backendStartStatus = startStatus;
+    this.#backendGaveUp = false;
     this.#setBackendLifecycleState("starting");
     this.#backendReady = false;
     this.#backendStderrTail = [];
@@ -4767,7 +4824,8 @@ class AkanAppHost {
     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) {
@@ -4814,6 +4872,7 @@ ${this.#backendStderrTail.join(`
     if (message.type === "build-status") {
       this.#recordBuildStatus(message.data);
       this.#sendOrQueueBuildStatus(message.data);
+      this.#reviveBackendAfterGreenBuild(message.data);
       return;
     }
     if (message.type === "pages-updated")
@@ -4828,19 +4887,25 @@ ${this.#backendStderrTail.join(`
   }
   async#handleInvalidate(message) {
     this.#logDevPlan(message);
-    if (shouldRestartDevHostByDevPlan(message)) {
-      try {
-        await this.#restartDevHost(message);
-      } catch (err) {
-        this.#recordDevHostRestartFailure(message, err, "Config");
+    const wantsDevHostRestart = shouldRestartDevHostByDevPlan(message);
+    const pending = this.#pendingRecycle;
+    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;
     }
@@ -4850,6 +4915,70 @@ ${this.#backendStderrTail.join(`
     }
     this.#sendToBackend(message);
   }
+  #deferRecycle(message, { refreshConfig, generation }) {
+    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 = {
+      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);
+  }
+  #resurrectDevChildren(message) {
+    const generation = message.devPlan?.generation ?? message.generation;
+    if (!this.#backend)
+      this.#startBackend({ generation, files: message.files });
+    this.#scheduleBuilderRecovery({ generation, files: message.files });
+  }
+  #scheduleBuilderRecovery(reason) {
+    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;
+      this.#recoverBuilder(reason);
+    }, delay);
+  }
+  async#recoverBuilder(reason) {
+    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 = {
+      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 });
+    }
+  }
+  #reviveBackendAfterGreenBuild(status) {
+    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) {
     const generation = message.devPlan?.generation ?? message.generation;
     this.logger.warn(`[dev-host] recycling builder/backend for runtime metadata generation=${generation ?? "(unknown)"} files=${message.files.length}`);
@@ -4870,6 +4999,11 @@ ${this.#backendStderrTail.join(`
       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();
@@ -4907,7 +5041,7 @@ ${this.#backendStderrTail.join(`
       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);
@@ -14077,6 +14211,7 @@ var resolveMobilePath = (target, pathname) => {
 };
 var targetHtmlFilename = (target) => target.basePath?.replace(/^\/+|\/+$/g, "") ? `${target.basePath.replace(/^\/+|\/+$/g, "")}.html` : "index.html";
 // pkgs/@akanjs/devkit/capacitorApp.ts
+var SWIFTUICORE_MIN_IOS_MAJOR = 18;
 var iosNativeBlockedEnvKeys = new Set([
   "AR",
   "AS",
@@ -14114,17 +14249,56 @@ async function writeRootCapacitorConfig(appRoot, content) {
   await clearRootCapacitorConfigs(appRoot);
   await Bun.write(path42.join(appRoot, "capacitor.config.json"), content);
 }
-var 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;
+var virtualInterfacePrefixes = [
+  "bridge",
+  "utun",
+  "llw",
+  "awdl",
+  "ap",
+  "vmnet",
+  "vnic",
+  "tap",
+  "tun",
+  "docker",
+  "veth",
+  "vboxnet",
+  "gif",
+  "stf"
+];
+var physicalInterfacePrefixes = ["en", "eth", "wlan", "wlp", "enp", "eno", "wlo"];
+var isPrivateLanIpv4 = (address) => {
+  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;
+};
+var scoreDevHostCandidate = (name, address) => {
+  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;
+};
+var selectLocalDevHost = (interfaces, { override } = {}) => {
+  const candidates = [];
+  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 };
 };
 var isRecord2 = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 var asString = (value) => typeof value === "string" ? value : undefined;
@@ -14144,6 +14318,30 @@ var dedupeIosRunTargets = (targets) => {
   }
   return [...byKey.values()];
 };
+var formatSimctlRuntime = (key) => {
+  if (!key)
+    return;
+  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;
+  return `${match[1]} ${match[2]}${match[3] ? `.${match[3]}` : ""}`;
+};
+var parseIosRuntimeMajor = (runtime) => {
+  const major = runtime?.match(/(\d+)/)?.[1];
+  if (major === undefined)
+    return;
+  const parsed = Number.parseInt(major, 10);
+  return Number.isNaN(parsed) ? undefined : parsed;
+};
+var iosRunTargetRank = (target) => {
+  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);
+};
+var sortIosRunTargets = (targets) => [...targets].sort((a, b) => iosRunTargetRank(b) - iosRunTargetRank(a) || a.name.localeCompare(b.name));
 function walkRecords(value, visit) {
   if (Array.isArray(value)) {
     for (const item of value)
@@ -14196,21 +14394,38 @@ function parseSimctlDevices(output) {
   try {
     const json = JSON.parse(output);
     const devices = json.devices ?? {};
-    return Object.values(devices).flat().filter(isRecord2).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", state: asString(device.state) }];
+    return Object.entries(devices).flatMap(([runtimeKey, list]) => {
+      const runtime = formatSimctlRuntime(runtimeKey);
+      return (Array.isArray(list) ? list : []).filter(isRecord2).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",
+            state: asString(device.state),
+            runtime: runtime ?? formatSimctlRuntime(asString(device.runtimeIdentifier))
+          }
+        ];
+      });
     });
   } catch {
     const targets = [];
+    let runtime;
     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;
   }
@@ -14245,6 +14460,13 @@ function buildIosNativeRunCommand({
 }
 function classifyIosRunFailure(log) {
   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 \u2014 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",
@@ -14342,6 +14564,21 @@ function formatIosRunFailureMessage(input2) {
 function sanitizeIosNativeRunEnv(env) {
   return Object.fromEntries(Object.entries(env).filter(([key]) => !iosNativeBlockedEnvKeys.has(key)));
 }
+var PLACEHOLDER_APP_IDS = [
+  "com.myapp.app",
+  "com.myorg.myapp",
+  "com.example.app",
+  "com.example.myapp"
+];
+var placeholderAppIdSegment = /^(example|examples|myorg|myapp|mycompany|myorganization|changeme|todo|sample|test)$/;
+var isPlaceholderAppId = (appId) => {
+  const normalized = appId?.trim().toLowerCase() ?? "";
+  if (!normalized)
+    return true;
+  if (PLACEHOLDER_APP_IDS.includes(normalized))
+    return true;
+  return normalized.split(".").some((segment) => placeholderAppIdSegment.test(segment));
+};
 var androidReleaseSigningKeys = [
   "MYAPP_RELEASE_STORE_FILE",
   "MYAPP_RELEASE_STORE_PASSWORD",
@@ -14590,23 +14827,37 @@ class CapacitorApp {
     await this.#runIosPhysicalDevice({ operation, env, runTarget, noAllowProvisioningUpdates });
   }
   async#selectIosRunTarget(deviceId) {
-    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 select2({
+    const selected = await select2({
       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 ? ` \u2014 ${target.runtime}` : ""}${target.state ? ` (${target.state})` : ""}`,
         value: target
       }))
     });
+    this.#warnIfLegacySimulatorRuntime(selected);
+    return selected;
+  }
+  #warnIfLegacySimulatorRuntime(target) {
+    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() {
     const devices = await this.#loadPhysicalIosDevices();
@@ -14853,7 +15104,13 @@ ${error.message}`;
   }
   async#writeCapacitorConfig({ operation }, commandEnv) {
     await mkdir11(this.targetRoot, { recursive: true });
-    const localIp = operation === "local" ? getLocalIP() : undefined;
+    let localIp;
+    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,
@@ -14864,6 +15121,17 @@ ${error.message}`;
     await Bun.write(path42.join(this.targetRoot, "capacitor.config.json"), content);
     return content;
   }
+  #logDevHostResolution(resolution, commandEnv) {
+    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;
@@ -17112,10 +17380,14 @@ 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) {
     return this.#enqueueWork(`build-route:${msg.routeId}`, async () => this.#handleBuildRoute(msg));
   }
@@ -17304,7 +17576,7 @@ ${cssText}`).toString(36);
     });
   }
   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,
@@ -17401,45 +17673,122 @@ ${cssText}`).toString(36);
     }
   }
   async boot() {
-    process.on("message", async (msg) => {
-      if (!msg || typeof msg !== "object")
-        return;
-      switch (msg.type) {
-        case "build-route": {
-          const res = await this.handleBuildRoute(msg);
-          process.send?.(res);
-          return;
-        }
-        default:
-          return;
-      }
-    });
-    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})`);
   }
+  async announceRecoveredState(changedFiles) {
+    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() {
     return true;
   }
-  static async create() {
+  static async#buildBootDeps(app) {
+    const { artifact: artifact2, cssCompiler: cssCompiler2, optimizedFonts } = await new SsrBaseArtifactBuilder(app).build();
+    await new CsrArtifactBuilder(app).build();
+    const discovery = await GraphClientEntryDiscovery.create(app);
+    return { artifact: artifact2, cssCompiler: cssCompiler2, optimizedFonts, discovery };
+  }
+  static #recoverBoot(app, bootError, logger) {
+    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, message) => {
+      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) => {
+      (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 {
+              if (new Set(batch.kinds).has("config"))
+                await app.getConfig({ refresh: true });
+              const deps = await IncrementalBuilder.#buildBootDeps(app);
+              const builder2 = new IncrementalBuilder({ app, watch: true, initialGeneration: generation, ...deps });
+              watcher.stop();
+              logger.info(`boot build recovered generation=${generation}`);
+              resolve({ builder: builder2, 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() {
+    const logger = new Logger11("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: artifact2, cssCompiler: cssCompiler2, optimizedFonts } = await new SsrBaseArtifactBuilder(app).build();
-    await new CsrArtifactBuilder(app).build();
-    const discovery = await GraphClientEntryDiscovery.create(app);
-    return new IncrementalBuilder({ app, cssCompiler: cssCompiler2, artifact: artifact2, watch, optimizedFonts, discovery });
+    let builder2 = null;
+    process.on("message", (msg) => {
+      if (!msg || typeof msg !== "object" || msg.type !== "build-route")
+        return;
+      if (!builder2) {
+        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;
+      }
+      builder2.handleBuildRoute(msg).then((res) => process.send?.(res));
+    });
+    process.on("disconnect", () => {
+      logger.warn("host IPC channel closed; exiting builder");
+      process.exit(0);
+    });
+    let recoveredFiles = null;
+    try {
+      builder2 = new IncrementalBuilder({ app, watch, ...await IncrementalBuilder.#buildBootDeps(app) });
+    } catch (err) {
+      if (!watch)
+        throw err;
+      const recovered = await IncrementalBuilder.#recoverBoot(app, err, logger);
+      builder2 = recovered.builder;
+      recoveredFiles = recovered.changedFiles;
+    }
+    await builder2.boot();
+    if (recoveredFiles)
+      await builder2.announceRecoveredState(recoveredFiles);
   }
 }
-(await IncrementalBuilder.create()).boot().catch((err) => {
+IncrementalBuilder.main().catch((err) => {
   console.error(err);
   process.exit(1);
 });