akanjs 2.3.5 → 2.3.6-rc.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # akanjs
 
+## 2.3.5
+
+### Patch Changes
+
+- Fix Akan document and service type regressions for extended constant, document, signal, and store models.
+
 ## 2.3.2
 
 ### Minor Changes

package/README.ko.md

@@ -1,6 +1,6 @@
 # Akan.js
 
-[English](https://unpkg.com/akanjs@latest/README.md) | [Docs](https://akanjs.com/docs) | [npm](https://www.npmjs.com/package/akanjs)
+[English](./README.md) | [Docs](https://akanjs.com/docs) | [npm](https://www.npmjs.com/package/akanjs)
 
 **한 줄의 비즈니스 코드로 웹·iOS·Android·서버·DB를 한 번에.**  
 **One line of business code ships web, iOS, Android, server, and database together.**

package/README.md

@@ -1,6 +1,6 @@
 # Akan.js
 
-[한국어](https://unpkg.com/akanjs@latest/README.ko.md) | [Docs](https://akanjs.com/docs) | [npm](https://www.npmjs.com/package/akanjs)
+[한국어](./README.ko.md) | [Docs](https://akanjs.com/docs) | [npm](https://www.npmjs.com/package/akanjs)
 
 **One line of business code ships web, iOS, Android, server, and database together.**
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akanjs",
-  "version": "2.3.5",
+  "version": "2.3.6-rc.0",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {

package/server/akanApp.ts

@@ -46,6 +46,7 @@ export interface AkanAppOptions {
   runtimeDir?: string;
   port?: number;
   wsBasePort?: number;
+  openapi?: boolean;
 }
 
 interface AkanReplicaConfig {
@@ -70,6 +71,7 @@ export class AkanApp {
   readonly #socketRunId = `${process.pid}-${Date.now().toString(36)}`;
   readonly #port: number;
   readonly #wsBasePort: number;
+  readonly #openapi?: boolean;
   readonly #children = new Map<number, ChildState>();
   readonly #roomChildren = new Map<string, Set<number>>();
   readonly #childRooms = new Map<number, Set<string>>();
@@ -97,15 +99,17 @@ export class AkanApp {
   #stopping = false;
 
   constructor(serverPath = "./server", options: AkanAppOptions = {}) {
-    this.#serverPath = AkanApp.#resolveServerPath(options.serverPath ?? serverPath);
+    const resolvedOptions = options;
+    this.#serverPath = AkanApp.#resolveServerPath(resolvedOptions.serverPath ?? serverPath);
     this.#artifactDir = path.resolve(path.dirname(this.#serverPath), ".akan", "artifact");
-    this.#replica = AkanApp.#parseReplicaConfig(options.replica);
+    this.#replica = AkanApp.#parseReplicaConfig(resolvedOptions.replica);
     this.#runtimeDir =
-      (options.runtimeDir ?? process.env.AKAN_RUNTIME_DIR ?? process.env.NODE_ENV === "production")
+      (resolvedOptions.runtimeDir ?? process.env.AKAN_RUNTIME_DIR ?? process.env.NODE_ENV === "production")
         ? path.resolve(process.cwd(), "runtime")
         : path.resolve(process.cwd(), "local", "apps", process.env.AKAN_PUBLIC_APP_NAME ?? "unknown", "runtime");
-    this.#port = Number(options.port ?? process.env.PORT ?? 8282);
-    this.#wsBasePort = Number(options.wsBasePort ?? process.env.AKAN_WS_BASE_PORT ?? this.#port + 10_000);
+    this.#port = Number(resolvedOptions.port ?? process.env.PORT ?? 8282);
+    this.#wsBasePort = Number(resolvedOptions.wsBasePort ?? process.env.AKAN_WS_BASE_PORT ?? this.#port + 10_000);
+    this.#openapi = resolvedOptions.openapi;
   }
 
   static #resolveServerPath(serverPath: string) {
@@ -225,6 +229,7 @@ export class AkanApp {
         SERVER_MODE: role,
         AKAN_CHILD_SOCKET: upstream.http.socketPath,
         AKAN_CHILD_WS_PORT: upstream.ws ? String(upstream.ws.port) : "",
+        ...(this.#openapi === undefined ? {} : { AKAN_OPENAPI: this.#openapi ? "true" : "false" }),
       },
       ipc: (message) => this.#handleMessage(idx, message as AkanIpcMessage, proc),
       stdout: "pipe",
@@ -777,6 +782,7 @@ export class AkanApp {
       case "invalidate":
       case "css-updated":
       case "pages-updated":
+      case "build-status":
         this.#fanoutToFederation(message);
         return;
       case "build-route-res":

package/server/akanServer.ts

@@ -10,6 +10,8 @@ import type {
   SolidConfig,
 } from "akanjs/service";
 import type { ServerSignal, ServerSignalCls, WebsocketPublishData } from "akanjs/signal";
+import { createOpenApiDocument } from "../signal/openapi";
+import { FetchSerializer } from "../signal/serializer";
 import type { AkanLib, AkanLibProps } from "./akanLib";
 import type { BuilderRpc } from "./artifact";
 import { DiLifecycle } from "./di/diLifecycle";
@@ -26,12 +28,18 @@ export interface AkanServerProps extends AkanLibProps {
   env?: BaseEnv;
   prefix?: string;
   websocketPrefix?: string;
+  openapi?: boolean;
+}
+
+export interface AkanServerOptions {
+  openapi?: boolean;
 }
 
 interface AkanAppPrepared {
   routes: SignalRoutes["routes"];
   routeOptions: SignalRoutes["routeOptions"];
   wsRoutes: WebsocketRoutes;
+  builtinRoutes: HttpRoutes;
   renderEnvRoutes: HttpRoutes;
   hmrHub: HmrWsHub | null;
   builderRpc: BuilderRpc | null;
@@ -64,6 +72,7 @@ export class AkanServer {
   readonly env: BaseEnv & { database?: DatabaseConfig; solid?: SolidConfig };
   prefix = "/api";
   websocketPrefix = "/ws";
+  openapi = AkanServer.#isOpenApiEnvEnabled();
   serverMode: "federation" | "batch" | "all";
   shutdownTimeoutMs = 30_000;
 
@@ -78,12 +87,14 @@ export class AkanServer {
       | "batch"
       | "all"
       | undefined) ?? "all",
-    ...libs: AkanLib[]
+    ...libsOrOptions: (AkanLib | AkanServerOptions)[]
   ) {
+    const { libs, options } = AkanServer.#splitLibsAndOptions(libsOrOptions);
     this.name = name;
     this.logger = new Logger(name);
     this.libs = libs;
     this.env = { ...env };
+    this.openapi = options?.openapi ?? this.openapi;
     this.serverMode = serverMode;
     this.#di = new DiLifecycle(this.env, serverMode, ...libs);
   }
@@ -95,6 +106,11 @@ export class AkanServer {
     this.websocketPrefix = websocketPrefix;
     return this;
   }
+  setOpenApi(openapi = true) {
+    if (this.status !== "stopped") throw new Error("OpenAPI config must be set before app initialization.");
+    this.openapi = openapi;
+    return this;
+  }
   setDatabaseConfig(database: DatabaseConfig) {
     if (this.status !== "stopped") throw new Error("Database config must be set before app initialization.");
     this.env.database = database;
@@ -170,6 +186,7 @@ export class AkanServer {
         routes,
         routeOptions,
         wsRoutes,
+        builtinRoutes: this.#createBuiltinRoutes(),
         renderEnvRoutes: {},
         hmrHub: null,
         builderRpc: null,
@@ -185,7 +202,17 @@ export class AkanServer {
     });
     const { renderEnvRoutes, hmrHub, builderRpc } = await webRouter.initializeRoute();
     const webProxyRunner = WebProxyRunner.create(this.#di.webProxies);
-    this.#prepared = { routes, routeOptions, wsRoutes, renderEnvRoutes, hmrHub, builderRpc, webRouter, webProxyRunner };
+    this.#prepared = {
+      routes,
+      routeOptions,
+      wsRoutes,
+      builtinRoutes: this.#createBuiltinRoutes(),
+      renderEnvRoutes,
+      hmrHub,
+      builderRpc,
+      webRouter,
+      webProxyRunner,
+    };
     this.status = "initialized";
     return this;
   }
@@ -200,7 +227,8 @@ export class AkanServer {
       : Number(process.env.AKAN_CHILD_WS_PORT || process.env.PORT || 8282);
     const unix = process.env.AKAN_CHILD_SOCKET || undefined;
     this.logger.verbose(`${this.name} is serving on ${unix ? `unix://${unix}` : `port ${port}`}`);
-    const { routes, routeOptions, wsRoutes, renderEnvRoutes, hmrHub, webRouter, webProxyRunner } = this.#prepared;
+    const { routes, routeOptions, wsRoutes, builtinRoutes, renderEnvRoutes, hmrHub, webRouter, webProxyRunner } =
+      this.#prepared;
     const websocketHandlers = {
       ...ApiRouter.buildWebsocketHandlers({
         wsRoutes,
@@ -220,6 +248,7 @@ export class AkanServer {
         prefix: this.prefix,
         websocketPrefix: this.websocketPrefix,
         routes,
+        builtinRoutes,
         routeOptions,
         renderEnvRoutes,
         upgradeAppWs: (req, data) => this.#server?.upgrade(req, { data }) ?? false,
@@ -236,6 +265,7 @@ export class AkanServer {
           prefix: this.prefix,
           websocketPrefix: this.websocketPrefix,
           routes,
+          builtinRoutes,
           routeOptions,
           renderEnvRoutes,
           upgradeAppWs: (req, data) => this.#wsServer?.upgrade(req, { data }) ?? false,
@@ -390,6 +420,47 @@ export class AkanServer {
     );
   }
 
+  #createBuiltinRoutes(): HttpRoutes {
+    if (!this.openapi) return {};
+    return {
+      "/openapi.json": {
+        GET: () =>
+          Response.json(
+            createOpenApiDocument(FetchSerializer.serializeRegistry(this.#di.live).signal, {
+              title: `${this.env.appName} API`,
+              version: "0.0.0",
+              servers: this.#getOpenApiServers(),
+            }),
+          ),
+      },
+    };
+  }
+
+  #getOpenApiServers() {
+    const serverHttpUri = (this.env as { serverHttpUri?: string }).serverHttpUri;
+    if (!serverHttpUri) return undefined;
+    return [{ url: serverHttpUri.replace(/\/api\/?$/, "") }];
+  }
+
+  static #splitLibsAndOptions(libsOrOptions: (AkanLib | AkanServerOptions)[]) {
+    const last = libsOrOptions.at(-1);
+    const options = AkanServer.#isServerOptions(last) ? last : undefined;
+    const libs = (options ? libsOrOptions.slice(0, -1) : libsOrOptions) as AkanLib[];
+    return { libs, options };
+  }
+
+  static #isServerOptions(value: AkanLib | AkanServerOptions | undefined): value is AkanServerOptions {
+    return Boolean(
+      value && !("database" in value) && !("service" in value) && !("scalar" in value) && "openapi" in value,
+    );
+  }
+
+  static #isOpenApiEnvEnabled() {
+    return [process.env.AKAN_OPENAPI, process.env.AKAN_PUBLIC_OPENAPI].some(
+      (value) => value === "true" || value === "1",
+    );
+  }
+
   async #withShutdownTimeout<T>(promise: Promise<T>) {
     let timeout: Timer | null = null;
     try {

package/server/artifact/builderRpc.ts

@@ -6,6 +6,7 @@ import type {
   BuilderRes,
   BuildRouteResultPayload,
   CssPayload,
+  DevBuildStatus,
   PagesBundlePayload,
 } from "./ipcTypes";
 import type { BuildRouteClientResult } from "./manifestTypes";
@@ -26,6 +27,8 @@ export interface BuilderRpcEventHandlers {
    * worker subprocess.
    */
   onPagesUpdated?: (bundle: PagesBundlePayload) => void;
+  /** Builder reported a dev build phase success/failure. */
+  onBuildStatus?: (status: DevBuildStatus) => void;
 }
 
 /**
@@ -76,6 +79,9 @@ export class BuilderRpc {
         case "pages-updated":
           handlers.onPagesUpdated?.(ev.data);
           return;
+        case "build-status":
+          handlers.onBuildStatus?.(ev.data);
+          return;
         default:
           return;
       }

package/server/artifact/ipcTypes.ts

@@ -16,6 +16,35 @@ export interface CssPayload {
   changedFiles?: string[];
 }
 
+export type DevChangeRole = "server" | "client" | "shared" | "barrel" | "config" | "css";
+
+export type DevChangeAction =
+  | "restart-backend"
+  | "rebuild-client"
+  | "rebuild-css"
+  | "sync-generated"
+  | "restart-dev-host"
+  | "report-error";
+
+export interface DevChangePlan {
+  generation: number;
+  files: string[];
+  generatedFiles: string[];
+  roles: DevChangeRole[];
+  actions: DevChangeAction[];
+  reasonByFile: Record<string, string[]>;
+}
+
+export type BuildPhase = "scan" | "barrel" | "csr" | "pages" | "css" | "route" | "backend";
+
+export interface DevBuildStatus {
+  generation: number;
+  phase: BuildPhase;
+  ok: boolean;
+  files: string[];
+  message?: string;
+}
+
 export type BuilderReq = {
   type: "build-route";
   id: number;
@@ -39,8 +68,15 @@ export interface PagesBundlePayload {
 export type BuilderEvent =
   | { type: "builder-ready"; buildId: string }
   | { type: "backend-ready"; pid: number }
-  | { type: "invalidate"; kinds: ("code" | "css" | "config")[]; files: string[]; generation?: number }
+  | {
+      type: "invalidate";
+      kinds: ("code" | "css" | "config")[];
+      files: string[];
+      generation?: number;
+      devPlan?: DevChangePlan;
+    }
   | { type: "css-updated"; data: CssPayload }
-  | { type: "pages-updated"; data: PagesBundlePayload };
+  | { type: "pages-updated"; data: PagesBundlePayload }
+  | { type: "build-status"; data: DevBuildStatus };
 
 export type BuilderMessage = BuilderReq | BuilderRes | BuilderEvent;

package/server/hmr/clientScript.ts

@@ -14,11 +14,13 @@ export const HMR_CLIENT_SCRIPT = `(function(){
   var refreshQueue = Promise.resolve();
   var overlayEl = null;
   var overlayLabelEl = null;
+  var overlayDetailEl = null;
   var overlayStyleEl = null;
   var overlayTimer = null;
   var overlayHideTimer = null;
   var overlayNextToken = 1;
   var overlayJobs = {};
+  var buildErrorStates = {};
   self.__AKAN_HMR_PHASE__ = null;
 
   self.$RefreshReg$ = self.$RefreshReg$ || function(type, id){
@@ -69,7 +71,20 @@ export const HMR_CLIENT_SCRIPT = `(function(){
         }
         return;
       }
-      if (msg.type === "error") { console.error("[akan-hmr]", msg.message); return; }
+      if (msg.type === "build-status") { handleBuildStatus(msg); return; }
+      if (msg.type === "ok") {
+        clearBuildErrorOverlay({
+          phase: "build",
+          generation: typeof msg.generation === "number" ? msg.generation : Number.MAX_SAFE_INTEGER,
+          files: 0
+        });
+        return;
+      }
+      if (msg.type === "error") {
+        console.error("[akan-hmr]", msg.message);
+        showBuildErrorOverlay({ phase: "build", generation: 0, message: msg.message, files: 0 });
+        return;
+      }
     });
     socket.addEventListener("close", function(){ socket = null; schedule(); });
     socket.addEventListener("error", function(){ try { socket && socket.close(); } catch(e){} });
@@ -87,18 +102,25 @@ export const HMR_CLIENT_SCRIPT = `(function(){
       overlayStyleEl = document.createElement("style");
       overlayStyleEl.textContent =
         "@keyframes akan-hmr-spin{to{transform:rotate(360deg)}}" +
-        ".__akan_hmr_overlay{position:fixed;left:16px;bottom:16px;z-index:2147483647;display:flex;align-items:center;gap:9px;padding:10px 12px;border-radius:999px;background:rgba(17,24,39,.94);color:#fff;font:500 13px/1.2 ui-sans-serif,system-ui,-apple-system,BlinkMacSystemFont,Segoe UI,sans-serif;box-shadow:0 10px 28px rgba(0,0,0,.28);pointer-events:none;opacity:0;transform:translateY(6px);transition:opacity .15s ease,transform .15s ease;backdrop-filter:blur(8px)}" +
+        ".__akan_hmr_overlay{position:fixed;left:16px;bottom:16px;z-index:2147483647;display:flex;align-items:flex-start;gap:9px;max-width:min(420px,calc(100vw - 32px));padding:10px 12px;border-radius:16px;background:rgba(17,24,39,.94);color:#fff;font:500 13px/1.25 ui-sans-serif,system-ui,-apple-system,BlinkMacSystemFont,Segoe UI,sans-serif;box-shadow:0 10px 28px rgba(0,0,0,.28);pointer-events:none;opacity:0;transform:translateY(6px);transition:opacity .15s ease,transform .15s ease;backdrop-filter:blur(8px)}" +
         ".__akan_hmr_overlay[data-show=true]{opacity:1;transform:translateY(0)}" +
-        ".__akan_hmr_spinner{width:14px;height:14px;border:2px solid rgba(255,255,255,.32);border-top-color:#fff;border-radius:999px;animation:akan-hmr-spin .75s linear infinite;flex:none}" +
+        ".__akan_hmr_overlay[data-status=error]{background:rgba(127,29,29,.96);border:1px solid rgba(252,165,165,.55)}" +
+        ".__akan_hmr_overlay[data-status=ok]{background:rgba(6,95,70,.94);border:1px solid rgba(110,231,183,.45)}" +
+        ".__akan_hmr_spinner{width:14px;height:14px;margin-top:1px;border:2px solid rgba(255,255,255,.32);border-top-color:#fff;border-radius:999px;animation:akan-hmr-spin .75s linear infinite;flex:none}" +
+        ".__akan_hmr_overlay[data-status=error] .__akan_hmr_spinner,.__akan_hmr_overlay[data-status=ok] .__akan_hmr_spinner{animation:none;border-color:rgba(255,255,255,.72);border-top-color:rgba(255,255,255,.72)}" +
+        ".__akan_hmr_body{display:flex;flex-direction:column;gap:3px;min-width:0}" +
+        ".__akan_hmr_detail{font:400 12px/1.35 ui-sans-serif,system-ui,-apple-system,BlinkMacSystemFont,Segoe UI,sans-serif;color:rgba(255,255,255,.82);white-space:pre-wrap;overflow-wrap:anywhere}" +
         "@media (prefers-reduced-motion:reduce){.__akan_hmr_overlay{transition:none}.__akan_hmr_spinner{animation:none}}";
       document.head.appendChild(overlayStyleEl);
     }
     overlayEl = document.createElement("div");
     overlayEl.className = "__akan_hmr_overlay";
+    overlayEl.setAttribute("data-status", "updating");
     overlayEl.setAttribute("role", "status");
     overlayEl.setAttribute("aria-live", "polite");
-    overlayEl.innerHTML = '<span class="__akan_hmr_spinner" aria-hidden="true"></span><span data-akan-hmr-label>Updating...</span>';
+    overlayEl.innerHTML = '<span class="__akan_hmr_spinner" aria-hidden="true"></span><span class="__akan_hmr_body"><span data-akan-hmr-label>Updating...</span><span class="__akan_hmr_detail" data-akan-hmr-detail></span></span>';
     overlayLabelEl = overlayEl.querySelector("[data-akan-hmr-label]");
+    overlayDetailEl = overlayEl.querySelector("[data-akan-hmr-detail]");
     (document.body || document.documentElement).appendChild(overlayEl);
     return overlayEl;
   }
@@ -116,19 +138,25 @@ export const HMR_CLIENT_SCRIPT = `(function(){
   function showOverlayNow(){
     overlayTimer = null;
     if (activeOverlayTokens().length === 0) return;
+    if (hasBuildErrors()) {
+      renderBuildErrorOverlay();
+      return;
+    }
     var el = ensureOverlay();
+    el.setAttribute("data-status", "updating");
     if (overlayHideTimer) {
       clearTimeout(overlayHideTimer);
       overlayHideTimer = null;
     }
     if (overlayLabelEl) overlayLabelEl.textContent = latestOverlayLabel();
+    if (overlayDetailEl) overlayDetailEl.textContent = "";
     requestAnimationFrame(function(){ el.setAttribute("data-show", "true"); });
   }
 
   function beginHmrOverlay(label, immediate){
     var token = overlayNextToken++;
     overlayJobs[token] = label || "Updating...";
-    if (overlayLabelEl) overlayLabelEl.textContent = latestOverlayLabel();
+    if (!hasBuildErrors() && overlayLabelEl) overlayLabelEl.textContent = latestOverlayLabel();
     if (overlayHideTimer) {
       clearTimeout(overlayHideTimer);
       overlayHideTimer = null;
@@ -145,11 +173,15 @@ export const HMR_CLIENT_SCRIPT = `(function(){
   function setHmrOverlayLabel(token, label){
     if (!overlayJobs[token]) return;
     overlayJobs[token] = label || "Updating...";
-    if (overlayLabelEl) overlayLabelEl.textContent = latestOverlayLabel();
+    if (!hasBuildErrors() && overlayLabelEl) overlayLabelEl.textContent = latestOverlayLabel();
   }
 
   function endHmrOverlay(token){
     delete overlayJobs[token];
+    if (hasBuildErrors()) {
+      renderBuildErrorOverlay();
+      return;
+    }
     if (activeOverlayTokens().length > 0) {
       if (overlayLabelEl) overlayLabelEl.textContent = latestOverlayLabel();
       return;
@@ -166,10 +198,117 @@ export const HMR_CLIENT_SCRIPT = `(function(){
         overlayEl.parentNode.removeChild(overlayEl);
         overlayEl = null;
         overlayLabelEl = null;
+        overlayDetailEl = null;
       }
     }, 180);
   }
 
+  function handleBuildStatus(msg){
+    if (msg.status === "error") {
+      showBuildErrorOverlay(msg);
+      return;
+    }
+    if (msg.status === "ok") clearBuildErrorOverlay(msg);
+  }
+
+  function showBuildErrorOverlay(msg){
+    var phase = msg.phase || "build";
+    var generation = typeof msg.generation === "number" ? msg.generation : 0;
+    var previous = buildErrorStates[phase];
+    if (previous && generation < previous.generation) return;
+    buildErrorStates[phase] = {
+      phase: msg.phase || "build",
+      generation: generation,
+      message: msg.message || "Build failed",
+      files: typeof msg.files === "number" ? msg.files : 0
+    };
+    console.error("[akan-hmr] build failed", buildErrorStates[phase]);
+    renderBuildErrorOverlay();
+  }
+
+  function renderBuildErrorOverlay(){
+    if (!hasBuildErrors()) return;
+    if (overlayTimer) {
+      clearTimeout(overlayTimer);
+      overlayTimer = null;
+    }
+    if (overlayHideTimer) {
+      clearTimeout(overlayHideTimer);
+      overlayHideTimer = null;
+    }
+    var el = ensureOverlay();
+    var phases = buildErrorPhases();
+    var latest = latestBuildErrorState();
+    el.setAttribute("data-status", "error");
+    if (overlayLabelEl) overlayLabelEl.textContent = "Build failed: " + phases.join(", ");
+    if (overlayDetailEl) overlayDetailEl.textContent = formatBuildStatusDetail(latest, phases.length);
+    requestAnimationFrame(function(){ el.setAttribute("data-show", "true"); });
+  }
+
+  function clearBuildErrorOverlay(msg){
+    var phase = msg.phase || "build";
+    var current = buildErrorStates[phase];
+    if (!current) return;
+    var generation = typeof msg.generation === "number" ? msg.generation : 0;
+    var recovered = phase === "backend" ? generation >= current.generation : generation > current.generation;
+    if (!recovered) return;
+    delete buildErrorStates[phase];
+    if (hasBuildErrors()) {
+      renderBuildErrorOverlay();
+      return;
+    }
+    if (overlayHideTimer) clearTimeout(overlayHideTimer);
+    var el = ensureOverlay();
+    el.setAttribute("data-status", "ok");
+    if (overlayLabelEl) overlayLabelEl.textContent = "Build recovered";
+    if (overlayDetailEl) overlayDetailEl.textContent = formatBuildStatusDetail(msg);
+    requestAnimationFrame(function(){ el.setAttribute("data-show", "true"); });
+    overlayHideTimer = setTimeout(function(){
+      if (activeOverlayTokens().length > 0) {
+        showOverlayNow();
+        return;
+      }
+      if (!overlayEl) return;
+      overlayEl.setAttribute("data-show", "false");
+      overlayHideTimer = setTimeout(function(){
+        if (overlayEl && activeOverlayTokens().length === 0 && !hasBuildErrors() && overlayEl.parentNode) {
+          overlayEl.parentNode.removeChild(overlayEl);
+          overlayEl = null;
+          overlayLabelEl = null;
+          overlayDetailEl = null;
+        }
+      }, 180);
+    }, 900);
+  }
+
+  function hasBuildErrors(){
+    return Object.keys(buildErrorStates).length > 0;
+  }
+
+  function buildErrorPhases(){
+    return Object.keys(buildErrorStates).sort();
+  }
+
+  function latestBuildErrorState(){
+    var phases = buildErrorPhases();
+    var latest = buildErrorStates[phases[0]];
+    for (var i = 1; i < phases.length; i++) {
+      var next = buildErrorStates[phases[i]];
+      if (!latest || next.generation >= latest.generation) latest = next;
+    }
+    return latest;
+  }
+
+  function formatBuildStatusDetail(msg, failedPhaseCount){
+    var parts = [];
+    if (typeof msg.generation === "number" && msg.generation > 0) parts.push("generation " + msg.generation);
+    if (typeof msg.files === "number") parts.push(msg.files + " file" + (msg.files === 1 ? "" : "s"));
+    if (failedPhaseCount > 1) parts.push(failedPhaseCount + " failed phases");
+    var prefix = parts.length > 0 ? parts.join(" · ") : "";
+    if (!msg.message) return prefix;
+    return prefix ? prefix + "\\n" + msg.message : msg.message;
+  }
+
   function refreshRsc(msg){
     var started = performance.now();
     var overlayToken = beginHmrOverlay("Refreshing page...");

package/server/hmr/devHmrController.ts

@@ -3,6 +3,7 @@ import { Logger } from "akanjs/common";
 import {
   BuilderRpc,
   type ClientManifest,
+  type DevBuildStatus,
   RouteClientCache,
   type RouteSeedIndex,
   RouteSeedIndexStore,
@@ -10,7 +11,7 @@ import {
 import type { RscWorker } from "../rscWorkerHost";
 import type { RenderState } from "../types";
 import type { ChangeKind } from "./changeBatch";
-import { type HmrWsData, HmrWsHub } from "./wsHub";
+import { type HmrMessage, type HmrWsData, HmrWsHub } from "./wsHub";
 
 const APP_RUNTIME_METADATA_BASENAMES = new Set(["dict.ts", "sig.ts", "useClient.ts"]);
 
@@ -44,6 +45,34 @@ export function manifestClientEntriesForFiles(
   return entries;
 }
 
+export function devBuildStatusToHmrMessage(
+  status: DevBuildStatus,
+  previous?: DevBuildStatus,
+): Extract<HmrMessage, { type: "build-status" }> | null {
+  if (!status.ok) {
+    return {
+      type: "build-status",
+      status: "error",
+      generation: status.generation,
+      phase: status.phase,
+      message: status.message,
+      files: status.files.length,
+    };
+  }
+  if (!previous || previous.ok) return null;
+  const recovered =
+    status.phase === "backend" ? status.generation >= previous.generation : status.generation > previous.generation;
+  if (!recovered) return null;
+  return {
+    type: "build-status",
+    status: "ok",
+    generation: status.generation,
+    phase: status.phase,
+    message: status.message,
+    files: status.files.length,
+  };
+}
+
 export interface DevHmrControllerOptions {
   renderState: RenderState;
   rsc: RscWorker;
@@ -69,6 +98,7 @@ export class DevHmrController {
   readonly #clientEntriesByRouteId = new Map<string, Set<string>>();
   readonly #dirty = new Set<Exclude<ChangeKind, "ignore">>();
   readonly #dirtyFiles = new Set<string>();
+  readonly #buildStatusByPhase = new Map<DevBuildStatus["phase"], DevBuildStatus>();
 
   constructor({ renderState, rsc, seedIndex, upgradeHmrWs }: DevHmrControllerOptions) {
     this.#renderState = renderState;
@@ -166,6 +196,9 @@ export class DevHmrController {
       onInvalidate: (ev) => {
         this.#recordInvalidate(ev.files, new Set(ev.kinds), ev.generation);
       },
+      onBuildStatus: (status) => {
+        this.#recordBuildStatus(status);
+      },
       onCssUpdated: (css) => {
         const started = Date.now();
         const cssBytesByUrl = Object.fromEntries(
@@ -217,6 +250,17 @@ export class DevHmrController {
     });
   }
 
+  #recordBuildStatus(status: DevBuildStatus): void {
+    const previous = this.#buildStatusByPhase.get(status.phase);
+    this.#buildStatusByPhase.set(status.phase, status);
+    const message = devBuildStatusToHmrMessage(status, previous);
+    if (!message) return;
+    this.#hub.broadcast(message);
+    this.#logger.verbose(
+      `[hmr] build-status status=${message.status} generation=${message.generation} phase=${message.phase} files=${message.files ?? 0}`,
+    );
+  }
+
   #createRouteCache() {
     return new RouteClientCache({
       buildRoute: async (routeId, { seeds, knownEntries, generation }) => {

package/server/hmr/wsHub.ts

@@ -1,4 +1,5 @@
 import { Logger } from "akanjs/common";
+import type { BuildPhase } from "../artifact";
 
 export interface HmrWsData {
   kind: "akan-hmr";
@@ -21,6 +22,15 @@ export type HmrMessage =
       routeIds?: string[];
     }
   | { type: "css-update"; cssAssets?: Record<string, { cssUrl: string; cssRelPath: string }> }
+  | { type: "ok"; generation?: number }
+  | {
+      type: "build-status";
+      status: "building" | "error" | "ok";
+      generation: number;
+      phase: BuildPhase;
+      message?: string;
+      files?: number;
+    }
   | { type: "error"; message: string };
 
 export const HMR_WS_TOPIC = "__akan_hmr";