akanjs 2.3.5 → 2.3.6-rc.0

package/server/routing/apiRouter.ts

@@ -26,6 +26,7 @@ export interface ApiRouteInputs {
   prefix: string;
   websocketPrefix: string;
   routes: HttpRoutes;
+  builtinRoutes?: HttpRoutes;
   routeOptions?: Record<string, SignalRouteOptions>;
   renderEnvRoutes: HttpRoutes;
   /** Upgrades the incoming request into an app-signal WebSocket. */
@@ -71,6 +72,7 @@ export class ApiRouter {
     prefix,
     websocketPrefix,
     routes,
+    builtinRoutes,
     routeOptions,
     renderEnvRoutes,
     upgradeAppWs,
@@ -79,7 +81,8 @@ export class ApiRouter {
     const endpointEntries = Object.entries(routes ?? {}).map(
       ([p, handler]) => [ApiRouter.#applyGlobalPrefix(prefix, p, routeOptions?.[p]), handler] as const,
     );
-    const endpointPaths = new Set(endpointEntries.map(([path]) => path));
+    const builtinEntries = Object.entries(builtinRoutes ?? {});
+    const endpointPaths = new Set([...endpointEntries.map(([path]) => path), ...builtinEntries.map(([path]) => path)]);
     const routeTable = {
       [`${prefix}${websocketPrefix}` as "/api/ws"]: (req) => {
         const upgraded = upgradeAppWs(req, { createdAt: Date.now() });
@@ -87,6 +90,7 @@ export class ApiRouter {
         return new Response("Failed to upgrade to WebSocket", { status: 500 });
       },
       ...Object.fromEntries(endpointEntries),
+      ...Object.fromEntries(builtinEntries),
       ...(renderEnvRoutes ?? {}),
     } as NonNullHttpRoutes;
     return webProxyRunner

package/signal/index.ts

@@ -9,6 +9,7 @@ export * from "./internal";
 export * from "./internalArg";
 export * from "./internalInfo";
 export * from "./middleware";
+export * from "./openapi";
 export * from "./serializer";
 export * from "./serverSignal";
 export * from "./signalContext";

package/signal/openapi/index.ts

@@ -0,0 +1 @@
+export * from "./openapi";

package/signal/openapi/openapi.ts

@@ -0,0 +1,359 @@
+import { type Cls, FIELD_META, getNonArrayModel, PrimitiveRegistry, type PrimitiveScalar } from "akanjs/base";
+import { type ConstantCls, type ConstantField, ConstantRegistry, type ConstantType } from "akanjs/constant";
+import { FetchClient } from "akanjs/fetch";
+import type { SerializedArg, SerializedEndpoint, SerializedReturns, SerializedSignal } from "../types";
+
+type OpenApiSchema = Record<string, unknown>;
+type OpenApiParameter = Record<string, unknown>;
+type OpenApiOperation = Record<string, unknown>;
+type OpenApiPathItem = Record<string, OpenApiOperation>;
+
+export interface OpenApiDocumentOptions {
+  title?: string;
+  version?: string;
+  servers?: { url: string; description?: string }[];
+  description?: string;
+  resolveDescription?: (key: string) => string | undefined;
+  excludeSignals?: string[];
+  includeNonStandardPaths?: boolean;
+}
+
+export interface OpenApiDocument {
+  openapi: "3.1.0";
+  info: {
+    title: string;
+    version: string;
+    description?: string;
+  };
+  servers?: { url: string; description?: string }[];
+  paths: Record<string, OpenApiPathItem>;
+  components: {
+    schemas: Record<string, OpenApiSchema>;
+    securitySchemes?: Record<string, OpenApiSchema>;
+  };
+}
+
+const httpMethods = {
+  query: "get",
+  mutation: "post",
+} as const;
+
+export const createOpenApiDocument = (
+  serializedSignal: Record<string, SerializedSignal>,
+  options: OpenApiDocumentOptions = {},
+): OpenApiDocument => {
+  const paths: Record<string, OpenApiPathItem> = {};
+  const excludeSignals = new Set(options.excludeSignals ?? ["base"]);
+  let hasProtectedOperation = false;
+
+  for (const [refName, signal] of Object.entries(serializedSignal)) {
+    if (excludeSignals.has(refName)) continue;
+    for (const [endpointKey, endpoint] of collectRestEndpoints(refName, signal)) {
+      const method = httpMethods[endpoint.type as keyof typeof httpMethods];
+      if (!method) continue;
+
+      const path = toOpenApiPath(FetchClient.makeHttpUrl(endpointKey, endpoint, signal.prefix, new Map()));
+      if (!options.includeNonStandardPaths && isNonStandardOpenApiPath(path)) continue;
+      const operation = createOperation(refName, endpointKey, endpoint, options);
+      if (operation.security) hasProtectedOperation = true;
+      paths[path] ??= {};
+      paths[path][method] = operation;
+    }
+  }
+
+  return {
+    openapi: "3.1.0",
+    info: {
+      title: options.title ?? "Akan API",
+      version: options.version ?? "0.0.0",
+      ...(options.description ? { description: options.description } : {}),
+    },
+    ...(options.servers?.length ? { servers: options.servers } : {}),
+    paths,
+    components: {
+      schemas: createReferencedComponentSchemas(paths),
+      ...(hasProtectedOperation
+        ? {
+            securitySchemes: {
+              bearerAuth: {
+                type: "http",
+                scheme: "bearer",
+                bearerFormat: "JWT",
+              },
+            },
+          }
+        : {}),
+    },
+  };
+};
+
+const collectRestEndpoints = (refName: string, signal: SerializedSignal): [string, SerializedEndpoint][] => {
+  const baseEndpointEntries = Object.entries(FetchClient.getBaseEndpoint(refName, signal));
+  const sliceEndpointEntries = signal.slice
+    ? Object.entries(signal.slice).flatMap(([suffix, slice]) =>
+        Object.entries(FetchClient.getEndpointFromSlice(refName, suffix, slice)),
+      )
+    : [];
+  return [...baseEndpointEntries, ...sliceEndpointEntries, ...Object.entries(signal.endpoint)].filter(
+    ([, endpoint]) => endpoint.type === "query" || endpoint.type === "mutation",
+  );
+};
+
+const createOperation = (
+  refName: string,
+  endpointKey: string,
+  endpoint: SerializedEndpoint,
+  options: OpenApiDocumentOptions,
+): OpenApiOperation => {
+  const { paramArgs, searchArgs, bodyArgs, uploadArgs } = FetchClient.classifyHttpArgs(endpoint.args);
+  const description = options.resolveDescription?.(`${refName}.signal.${endpointKey}.desc`);
+  const guards = getProtectedGuards(endpoint.guards);
+  return {
+    tags: [refName],
+    operationId: endpointKey,
+    summary: options.resolveDescription?.(`${refName}.signal.${endpointKey}`) ?? endpointKey,
+    ...(description ? { description } : {}),
+    parameters: [
+      ...paramArgs.map((arg) => createParameter(refName, endpointKey, arg, "path", options)),
+      ...searchArgs.map((arg) => createParameter(refName, endpointKey, arg, "query", options)),
+    ],
+    ...(bodyArgs.length || uploadArgs.length ? { requestBody: createRequestBody(bodyArgs, uploadArgs) } : {}),
+    responses: {
+      "200": {
+        description: "Successful response",
+        content: createResponseContent(endpoint),
+      },
+      default: {
+        description: "Error response",
+      },
+    },
+    ...(guards.length ? { security: [{ bearerAuth: [] }], "x-akan-guards": guards } : {}),
+    "x-akan-signal": refName,
+    "x-akan-endpoint-type": endpoint.type,
+  };
+};
+
+const createParameter = (
+  refName: string,
+  endpointKey: string,
+  arg: SerializedArg,
+  location: "path" | "query",
+  options: OpenApiDocumentOptions,
+): OpenApiParameter => ({
+  name: arg.name,
+  in: location,
+  required: location === "path",
+  schema: createArgSchema(arg),
+  ...(arg.example !== undefined ? { example: arg.example } : {}),
+  ...(options.resolveDescription?.(`${refName}.signal.${endpointKey}.arg.${arg.name}.desc`)
+    ? { description: options.resolveDescription(`${refName}.signal.${endpointKey}.arg.${arg.name}.desc`) }
+    : {}),
+});
+
+const createRequestBody = (bodyArgs: SerializedArg[], uploadArgs: SerializedArg[]) => {
+  const required = [...bodyArgs, ...uploadArgs].filter((arg) => !arg.nullable).map((arg) => arg.name);
+  const schema = {
+    type: "object",
+    properties: Object.fromEntries(
+      [...bodyArgs, ...uploadArgs].map((arg) => [
+        arg.name,
+        uploadArgs.includes(arg) ? createUploadSchema(arg) : createArgSchema(arg),
+      ]),
+    ),
+    ...(required.length ? { required } : {}),
+  };
+  return {
+    required: required.length > 0,
+    content: {
+      [uploadArgs.length ? "multipart/form-data" : "application/json"]: {
+        schema,
+      },
+    },
+  };
+};
+
+const createResponseContent = (endpoint: SerializedEndpoint) =>
+  isBinaryResponseEndpoint(endpoint)
+    ? {
+        "application/octet-stream": {
+          schema: { type: "string", format: "binary" },
+        },
+      }
+    : {
+        "application/json": {
+          schema: createReturnSchema(endpoint.returns),
+        },
+      };
+
+const createReturnSchema = (returns: SerializedReturns): OpenApiSchema =>
+  withNullable(
+    withArrayDepth(createRefSchema(returns.refName, returns.modelType), returns.arrDepth ?? 0),
+    !!returns.nullable,
+  );
+
+const createArgSchema = (arg: SerializedArg): OpenApiSchema => {
+  const schema = arg.enum ? createEnumSchema(arg.enum) : createRefSchema(arg.refName, arg.modelType);
+  return withNullable(withArrayDepth(schema, arg.arrDepth ?? 0), !!arg.nullable);
+};
+
+const createUploadSchema = (arg: SerializedArg): OpenApiSchema => {
+  const fileSchema = { type: "string", format: "binary" };
+  return withNullable(withArrayDepth(fileSchema, arg.arrDepth ?? 0), !!arg.nullable);
+};
+
+const createRefSchema = (refName: string, modelType?: ConstantType): OpenApiSchema => {
+  if (!modelType) return createPrimitiveSchema(refName);
+  const modelRef = ConstantRegistry.getModelRef(refName, modelType);
+  return { $ref: `#/components/schemas/${ConstantRegistry.getModelName(modelRef as Cls)}` };
+};
+
+const createComponentSchemas = (): Record<string, OpenApiSchema> => {
+  const schemas: Record<string, OpenApiSchema> = {};
+  for (const [, database] of ConstantRegistry.database.entries()) {
+    [database.input, database.object, database.full, database.light, database.insight].forEach((modelRef) => {
+      schemas[ConstantRegistry.getModelName(modelRef)] = createModelSchema(modelRef);
+    });
+  }
+  for (const [, scalar] of ConstantRegistry.scalar.entries()) {
+    schemas[ConstantRegistry.getModelName(scalar.model)] = createModelSchema(scalar.model);
+  }
+  return schemas;
+};
+
+const createReferencedComponentSchemas = (paths: Record<string, OpenApiPathItem>): Record<string, OpenApiSchema> => {
+  const allSchemas = createComponentSchemas();
+  const referencedNames = collectSchemaRefNames(paths);
+  const pending = [...referencedNames];
+  for (let idx = 0; idx < pending.length; idx++) {
+    const schemaName = pending[idx];
+    if (!schemaName) continue;
+    const schema = allSchemas[schemaName];
+    if (!schema) continue;
+    for (const nestedName of collectSchemaRefNames(schema)) {
+      if (referencedNames.has(nestedName)) continue;
+      referencedNames.add(nestedName);
+      pending.push(nestedName);
+    }
+  }
+  return Object.fromEntries(
+    [...referencedNames]
+      .sort((a, b) => a.localeCompare(b))
+      .flatMap((name) => (allSchemas[name] ? ([[name, allSchemas[name]]] as const) : [])),
+  );
+};
+
+const collectSchemaRefNames = (value: unknown): Set<string> => {
+  const refs = new Set<string>();
+  const visit = (current: unknown) => {
+    if (!current || typeof current !== "object") return;
+    if (Array.isArray(current)) {
+      current.forEach(visit);
+      return;
+    }
+    const record = current as Record<string, unknown>;
+    if (typeof record.$ref === "string") {
+      const match = record.$ref.match(/^#\/components\/schemas\/(.+)$/);
+      if (match?.[1]) refs.add(match[1]);
+    }
+    Object.values(record).forEach(visit);
+  };
+  visit(value);
+  return refs;
+};
+
+const createModelSchema = (modelRef: ConstantCls): OpenApiSchema => {
+  const fields = (modelRef as { [FIELD_META]?: Record<string, ConstantField> })[FIELD_META] ?? {};
+  const properties: Record<string, OpenApiSchema> = {};
+  const required: string[] = [];
+  for (const [key, field] of Object.entries(fields)) {
+    const props = field.getProps();
+    properties[key] = createFieldSchema(field);
+    if (!props.nullable) required.push(key);
+  }
+  return {
+    type: "object",
+    properties,
+    ...(required.length ? { required } : {}),
+    additionalProperties: false,
+  };
+};
+
+const createFieldSchema = (field: ConstantField): OpenApiSchema => {
+  const props = field.getProps();
+  const schema = props.enum ? createInlineEnumSchema([...props.enum.values]) : createFieldRefSchema(props);
+  return withNullable(withArrayDepth(schema, props.arrDepth), props.nullable);
+};
+
+const createFieldRefSchema = (props: ReturnType<ConstantField["getProps"]>): OpenApiSchema => {
+  if (props.isMap) {
+    const [valueRef, valueArrDepth] = getNonArrayModel(props.of as Cls | Cls[]);
+    return {
+      type: "object",
+      additionalProperties: withArrayDepth(createModelRefSchema(valueRef as Cls), valueArrDepth),
+    };
+  }
+  return createModelRefSchema(props.modelRef as Cls);
+};
+
+const createModelRefSchema = (modelRef: Cls): OpenApiSchema => {
+  if (PrimitiveRegistry.has(modelRef))
+    return createPrimitiveSchema(PrimitiveRegistry.getName(modelRef as typeof PrimitiveScalar));
+  return { $ref: `#/components/schemas/${ConstantRegistry.getModelName(modelRef)}` };
+};
+
+const createPrimitiveSchema = (refName: string): OpenApiSchema => {
+  switch (refName) {
+    case "Boolean":
+      return { type: "boolean" };
+    case "Date":
+      return { type: "string", format: "date-time" };
+    case "Float":
+      return { type: "number" };
+    case "ID":
+      return { type: "string", pattern: "^[0-9a-fA-F]{24}$" };
+    case "Int":
+      return { type: "integer" };
+    case "Upload":
+      return { type: "string", format: "binary" };
+    case "Any":
+      return {};
+    case "String":
+    default:
+      return { type: "string" };
+  }
+};
+
+const createEnumSchema = (refName: string): OpenApiSchema => {
+  const enumRef = ConstantRegistry.enum.get(refName);
+  if (!enumRef) return { type: "string", "x-akan-enum": refName };
+  return createInlineEnumSchema([...enumRef.values]);
+};
+
+const createInlineEnumSchema = (values: unknown[]): OpenApiSchema => ({
+  type: values.every((value) => typeof value === "number") ? "number" : "string",
+  enum: values,
+});
+
+const withArrayDepth = (schema: OpenApiSchema, arrDepth: number): OpenApiSchema => {
+  let current = schema;
+  for (let idx = 0; idx < arrDepth; idx++) current = { type: "array", items: current };
+  return current;
+};
+
+const withNullable = (schema: OpenApiSchema, nullable: boolean): OpenApiSchema =>
+  nullable ? { anyOf: [schema, { type: "null" }] } : schema;
+
+const getProtectedGuards = (guards?: string[]) =>
+  (guards ?? []).filter((guard) => guard !== "None" && guard !== "Public");
+
+const isBinaryResponseEndpoint = (endpoint: SerializedEndpoint) =>
+  endpoint.returns.refName === "Upload" ||
+  (endpoint.returns.refName === "Any" &&
+    Boolean(endpoint.path?.includes("*") || endpoint.path?.toLowerCase().includes("blob")));
+
+const toOpenApiPath = (path: string) => {
+  const normalizedPath = path.startsWith("/") ? path : `/${path}`;
+  return normalizedPath.replace(/:([A-Za-z0-9_]+)/g, "{$1}");
+};
+
+const isNonStandardOpenApiPath = (path: string) => path.includes("*");

package/types/server/akanApp.d.ts

@@ -6,6 +6,7 @@ export interface AkanAppOptions {
     runtimeDir?: string;
     port?: number;
     wsBasePort?: number;
+    openapi?: boolean;
 }
 /** Gateway/orchestrator that starts Akan child servers and proxies HTTP/WebSocket traffic. */
 export declare class AkanApp {

package/types/server/akanServer.d.ts

@@ -7,6 +7,10 @@ export interface AkanServerProps extends AkanLibProps {
     env?: BaseEnv;
     prefix?: string;
     websocketPrefix?: string;
+    openapi?: boolean;
+}
+export interface AkanServerOptions {
+    openapi?: boolean;
 }
 export interface AkanServerConsoleInfo {
     name: string;
@@ -32,11 +36,13 @@ export declare class AkanServer {
     };
     prefix: string;
     websocketPrefix: string;
+    openapi: boolean;
     serverMode: "federation" | "batch" | "all";
     shutdownTimeoutMs: number;
-    constructor(name?: string, env?: BaseEnv, serverMode?: "federation" | "batch" | "all", ...libs: AkanLib[]);
+    constructor(name?: string, env?: BaseEnv, serverMode?: "federation" | "batch" | "all", ...libsOrOptions: (AkanLib | AkanServerOptions)[]);
     setPrefix(prefix: string): this;
     setWebsocketPrefix(websocketPrefix: string): this;
+    setOpenApi(openapi?: boolean): this;
     setDatabaseConfig(database: DatabaseConfig): this;
     setSolidConfig(solid: SolidConfig): this;
     setShutdownTimeout(timeoutMs: number): this;

package/types/server/artifact/builderRpc.d.ts

@@ -1,4 +1,4 @@
-import type { CssPayload, PagesBundlePayload } from "./ipcTypes.d.ts";
+import type { CssPayload, DevBuildStatus, PagesBundlePayload } from "./ipcTypes.d.ts";
 import type { BuildRouteClientResult } from "./manifestTypes.d.ts";
 export interface BuilderRpcEventHandlers {
     /**
@@ -20,6 +20,8 @@ export interface BuilderRpcEventHandlers {
      * worker subprocess.
      */
     onPagesUpdated?: (bundle: PagesBundlePayload) => void;
+    /** Builder reported a dev build phase success/failure. */
+    onBuildStatus?: (status: DevBuildStatus) => void;
 }
 /**
  * Typed RPC facade around the raw `BuilderTransport`. Handles the

package/types/server/artifact/ipcTypes.d.ts

@@ -27,6 +27,24 @@ export interface CssPayload {
     generation?: number;
     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;
@@ -63,11 +81,15 @@ export type BuilderEvent = {
     kinds: ("code" | "css" | "config")[];
     files: string[];
     generation?: number;
+    devPlan?: DevChangePlan;
 } | {
     type: "css-updated";
     data: CssPayload;
 } | {
     type: "pages-updated";
     data: PagesBundlePayload;
+} | {
+    type: "build-status";
+    data: DevBuildStatus;
 };
 export type BuilderMessage = BuilderReq | BuilderRes | BuilderEvent;

package/types/server/hmr/clientScript.d.ts

@@ -1 +1 @@
-export declare const HMR_CLIENT_SCRIPT = "(function(){\n  if (self.__AKAN_HMR_INSTALLED__) return;\n  self.__AKAN_HMR_INSTALLED__ = true;\n  var proto = location.protocol === \"https:\" ? \"wss:\" : \"ws:\";\n  var url = proto + \"//\" + location.host + \"/_akan/hmr\";\n  var attempts = 0;\n  var socket = null;\n  var lastBuildId = null;\n  var refreshRuntimePromise = null;\n  var refreshRuntime = null;\n  var pendingRefreshRegistrations = [];\n  var refreshQueue = Promise.resolve();\n  var overlayEl = null;\n  var overlayLabelEl = null;\n  var overlayStyleEl = null;\n  var overlayTimer = null;\n  var overlayHideTimer = null;\n  var overlayNextToken = 1;\n  var overlayJobs = {};\n  self.__AKAN_HMR_PHASE__ = null;\n\n  // Bun's React Fast Refresh transform can emit top-level calls to these globals\n  // even when we fall back to full reload instead of applying React Refresh.\n  self.$RefreshReg$ = self.$RefreshReg$ || function(type, id){\n    if (refreshRuntime) refreshRuntime.register(type, id);\n    else pendingRefreshRegistrations.push([type, id]);\n  };\n  self.$RefreshSig$ = self.$RefreshSig$ || function(){ return function(type){ return type; }; };\n  // Start installing React Refresh before the application module graph loads.\n  // Injecting the runtime only on the first update is too late for React's renderer hook.\n  ensureRefreshRuntime().catch(function(err){\n    console.warn(\"[akan-hmr] React Refresh runtime preload failed\", err);\n  });\n\n  function connect(){\n    try { socket = new WebSocket(url); }\n    catch(e){ console.error(\"[akan-hmr] ws init failed\", e); schedule(); return; }\n    socket.addEventListener(\"open\", function(){ attempts = 0; });\n    socket.addEventListener(\"message\", function(ev){\n      var msg;\n      try { msg = JSON.parse(ev.data); } catch (e){ return; }\n      if (!msg || typeof msg.type !== \"string\") return;\n      if (msg.type === \"hello\") {\n        if (lastBuildId !== null && msg.buildId !== lastBuildId) {\n          location.reload();\n          return;\n        }\n        lastBuildId = msg.buildId;\n        return;\n      }\n      if (msg.type === \"reload\") {\n        beginHmrOverlay(\"Reloading...\", true);\n        try { self.__AKAN_RSC_CLEAR_CACHE__ && self.__AKAN_RSC_CLEAR_CACHE__(); } catch(e){}\n        setTimeout(function(){ location.reload(); }, 30);\n        return;\n      }\n      if (msg.type === \"rsc-refresh\") {\n        refreshRsc(msg);\n        return;\n      }\n      if (msg.type === \"client-refresh\") {\n        refreshClient(msg);\n        return;\n      }\n      if (msg.type === \"css-update\") {\n        var cssUrl = selectCssUrl(msg.cssAssets);\n        if (cssUrl) swapCss(cssUrl);\n        else {\n          beginHmrOverlay(\"Reloading...\", true);\n          location.reload();\n        }\n        return;\n      }\n      if (msg.type === \"error\") { console.error(\"[akan-hmr]\", msg.message); return; }\n    });\n    socket.addEventListener(\"close\", function(){ socket = null; schedule(); });\n    socket.addEventListener(\"error\", function(){ try { socket && socket.close(); } catch(e){} });\n  }\n\n  function schedule(){\n    attempts = Math.min(attempts + 1, 6);\n    var delay = Math.min(30000, 250 * Math.pow(2, attempts - 1));\n    setTimeout(connect, delay);\n  }\n\n  function ensureOverlay(){\n    if (overlayEl && overlayLabelEl) return overlayEl;\n    if (!overlayStyleEl) {\n      overlayStyleEl = document.createElement(\"style\");\n      overlayStyleEl.textContent =\n        \"@keyframes akan-hmr-spin{to{transform:rotate(360deg)}}\" +\n        \".__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)}\" +\n        \".__akan_hmr_overlay[data-show=true]{opacity:1;transform:translateY(0)}\" +\n        \".__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}\" +\n        \"@media (prefers-reduced-motion:reduce){.__akan_hmr_overlay{transition:none}.__akan_hmr_spinner{animation:none}}\";\n      document.head.appendChild(overlayStyleEl);\n    }\n    overlayEl = document.createElement(\"div\");\n    overlayEl.className = \"__akan_hmr_overlay\";\n    overlayEl.setAttribute(\"role\", \"status\");\n    overlayEl.setAttribute(\"aria-live\", \"polite\");\n    overlayEl.innerHTML = '<span class=\"__akan_hmr_spinner\" aria-hidden=\"true\"></span><span data-akan-hmr-label>Updating...</span>';\n    overlayLabelEl = overlayEl.querySelector(\"[data-akan-hmr-label]\");\n    (document.body || document.documentElement).appendChild(overlayEl);\n    return overlayEl;\n  }\n\n  function activeOverlayTokens(){\n    return Object.keys(overlayJobs);\n  }\n\n  function latestOverlayLabel(){\n    var keys = activeOverlayTokens();\n    if (keys.length === 0) return \"Updating...\";\n    return overlayJobs[keys[keys.length - 1]] || \"Updating...\";\n  }\n\n  function showOverlayNow(){\n    overlayTimer = null;\n    if (activeOverlayTokens().length === 0) return;\n    var el = ensureOverlay();\n    if (overlayHideTimer) {\n      clearTimeout(overlayHideTimer);\n      overlayHideTimer = null;\n    }\n    if (overlayLabelEl) overlayLabelEl.textContent = latestOverlayLabel();\n    requestAnimationFrame(function(){ el.setAttribute(\"data-show\", \"true\"); });\n  }\n\n  function beginHmrOverlay(label, immediate){\n    var token = overlayNextToken++;\n    overlayJobs[token] = label || \"Updating...\";\n    if (overlayLabelEl) overlayLabelEl.textContent = latestOverlayLabel();\n    if (overlayHideTimer) {\n      clearTimeout(overlayHideTimer);\n      overlayHideTimer = null;\n    }\n    if (immediate) {\n      if (overlayTimer) clearTimeout(overlayTimer);\n      showOverlayNow();\n    } else if (!overlayTimer && (!overlayEl || overlayEl.getAttribute(\"data-show\") !== \"true\")) {\n      overlayTimer = setTimeout(showOverlayNow, 120);\n    }\n    return token;\n  }\n\n  function setHmrOverlayLabel(token, label){\n    if (!overlayJobs[token]) return;\n    overlayJobs[token] = label || \"Updating...\";\n    if (overlayLabelEl) overlayLabelEl.textContent = latestOverlayLabel();\n  }\n\n  function endHmrOverlay(token){\n    delete overlayJobs[token];\n    if (activeOverlayTokens().length > 0) {\n      if (overlayLabelEl) overlayLabelEl.textContent = latestOverlayLabel();\n      return;\n    }\n    if (overlayTimer) {\n      clearTimeout(overlayTimer);\n      overlayTimer = null;\n    }\n    if (!overlayEl) return;\n    overlayEl.setAttribute(\"data-show\", \"false\");\n    if (overlayHideTimer) clearTimeout(overlayHideTimer);\n    overlayHideTimer = setTimeout(function(){\n      if (overlayEl && activeOverlayTokens().length === 0 && overlayEl.parentNode) {\n        overlayEl.parentNode.removeChild(overlayEl);\n        overlayEl = null;\n        overlayLabelEl = null;\n      }\n    }, 180);\n  }\n\n  function refreshRsc(msg){\n    var started = performance.now();\n    var overlayToken = beginHmrOverlay(\"Refreshing page...\");\n    try { self.__AKAN_RSC_CLEAR_CACHE__ && self.__AKAN_RSC_CLEAR_CACHE__(); } catch(e){}\n    if (!self.__AKAN_RSC_REFRESH__) {\n      console.warn(\"[akan-hmr] RSC refresh API unavailable, falling back to full reload\");\n      setHmrOverlayLabel(overlayToken, \"Reloading...\");\n      setTimeout(function(){ location.reload(); }, 30);\n      return;\n    }\n    Promise.resolve(self.__AKAN_RSC_REFRESH__({ buildId: msg.buildId })).then(function(){\n      lastBuildId = msg.buildId;\n      endHmrOverlay(overlayToken);\n      console.debug && console.debug(\"[akan-hmr] RSC refreshed\", {\n        buildId: msg.buildId,\n        generation: msg.generation,\n        routeIds: msg.routeIds,\n        changedFiles: msg.changedFiles && msg.changedFiles.length,\n        durationMs: Math.round(performance.now() - started)\n      });\n    }, function(err){\n      console.error(\"[akan-hmr] RSC refresh failed, falling back to full reload\", err);\n      setHmrOverlayLabel(overlayToken, \"Update failed, reloading...\");\n      setTimeout(function(){ location.reload(); }, 250);\n    });\n  }\n\n  function ensureRefreshRuntime(){\n    if (refreshRuntimePromise) return refreshRuntimePromise;\n    refreshRuntimePromise = import(\"react-refresh/runtime\").then(function(mod){\n      var runtime = mod.default || mod;\n      if (!self.__AKAN_REACT_REFRESH_READY__) {\n        refreshRuntime = runtime;\n        runtime.injectIntoGlobalHook(self);\n        self.$RefreshReg$ = function(type, id){ runtime.register(type, id); };\n        self.$RefreshSig$ = runtime.createSignatureFunctionForTransform;\n        for (var i = 0; i < pendingRefreshRegistrations.length; i++) {\n          self.$RefreshReg$(pendingRefreshRegistrations[i][0], pendingRefreshRegistrations[i][1]);\n        }\n        pendingRefreshRegistrations = [];\n        self.__AKAN_REACT_REFRESH_READY__ = true;\n        self.__AKAN_REACT_REFRESH_RUNTIME__ = runtime;\n      }\n      return runtime;\n    });\n    return refreshRuntimePromise;\n  }\n\n  function refreshClient(msg){\n    refreshQueue = refreshQueue.then(function(){ return doRefreshClient(msg); }, function(){ return doRefreshClient(msg); });\n  }\n\n  function setHmrPhase(phase){\n    self.__AKAN_HMR_PHASE__ = phase;\n  }\n\n  function doRefreshClient(msg){\n    var started = performance.now();\n    var metadataAt = started;\n    var importAt = started;\n    var refreshAt = started;\n    var overlayToken = beginHmrOverlay(\"Updating...\");\n    var fallbackToRsc = false;\n    return ensureRefreshRuntime().then(function(runtime){\n      setHmrOverlayLabel(overlayToken, \"Fetching update...\");\n      var endpoint = new URL(\"/_akan/hmr/client-refresh\", location.origin);\n      endpoint.searchParams.set(\"url\", location.href);\n      if (msg.buildId != null) endpoint.searchParams.set(\"buildId\", String(msg.buildId));\n      return fetch(endpoint, { credentials: \"same-origin\", cache: \"no-store\" })\n        .then(function(res){\n          if (!res.ok) throw new Error(\"client-refresh metadata failed \" + res.status + \" \" + res.statusText);\n          return res.json();\n        })\n        .then(function(info){\n          metadataAt = performance.now();\n          var chunks = Array.isArray(info.chunks) ? info.chunks : [];\n          if (chunks.length === 0) throw new Error(\"no client chunks returned\");\n          setHmrPhase(\"refresh-import\");\n          setHmrOverlayLabel(overlayToken, \"Importing update...\");\n          return Promise.all(chunks.map(function(chunk){ return import(chunk); })).then(function(){\n            importAt = performance.now();\n            setHmrPhase(\"react-refresh\");\n            setHmrOverlayLabel(overlayToken, \"Applying update...\");\n            try {\n              runtime.performReactRefresh();\n            } finally {\n              setHmrPhase(null);\n            }\n            refreshAt = performance.now();\n            lastBuildId = msg.buildId;\n            console.debug && console.debug(\"[akan-hmr] React Fast Refresh applied\", {\n              buildId: msg.buildId,\n              generation: msg.generation,\n              chunks: chunks.length,\n              routeIds: info.routeIds || msg.routeIds,\n              changedFiles: msg.changedFiles && msg.changedFiles.length,\n              metadataMs: Math.round(metadataAt - started),\n              importMs: Math.round(importAt - metadataAt),\n              refreshMs: Math.round(refreshAt - importAt),\n              durationMs: Math.round(refreshAt - started)\n            });\n            endHmrOverlay(overlayToken);\n          }, function(err){\n            setHmrPhase(null);\n            throw err;\n          });\n        });\n    }).catch(function(err){\n      console.warn(\"[akan-hmr] React Fast Refresh failed, falling back to RSC refresh\", err);\n      fallbackToRsc = true;\n      endHmrOverlay(overlayToken);\n      refreshRsc(msg);\n    }).finally(function(){\n      if (!fallbackToRsc) endHmrOverlay(overlayToken);\n    });\n  }\n\n  function swapCss(href){\n    var overlayToken = beginHmrOverlay(\"Updating styles...\");\n    var link = document.createElement(\"link\");\n    link.rel = \"stylesheet\";\n    link.href = href;\n    link.setAttribute(\"data-akan-css\", \"pending\");\n    link.addEventListener(\"load\", function(){\n      var prev = document.querySelectorAll(\"link[data-akan-css=active]\");\n      for (var i = 0; i < prev.length; i++) prev[i].parentNode && prev[i].parentNode.removeChild(prev[i]);\n      link.setAttribute(\"data-akan-css\", \"active\");\n      endHmrOverlay(overlayToken);\n    });\n    link.addEventListener(\"error\", function(){\n      if (link.parentNode) link.parentNode.removeChild(link);\n      endHmrOverlay(overlayToken);\n    });\n    document.head.appendChild(link);\n  }\n\n  function selectCssUrl(cssAssets){\n    if (!cssAssets || typeof cssAssets !== \"object\") return null;\n    var parts = location.pathname.split(\"/\").filter(Boolean);\n    for (var i = 0; i < parts.length; i++) {\n      var asset = cssAssets[parts[i]];\n      if (asset && asset.cssUrl) return asset.cssUrl;\n    }\n    return cssAssets[\"\"] && cssAssets[\"\"].cssUrl ? cssAssets[\"\"].cssUrl : null;\n  }\n\n  connect();\n})();";
+export declare const HMR_CLIENT_SCRIPT = "(function(){\n  if (self.__AKAN_HMR_INSTALLED__) return;\n  self.__AKAN_HMR_INSTALLED__ = true;\n  var proto = location.protocol === \"https:\" ? \"wss:\" : \"ws:\";\n  var url = proto + \"//\" + location.host + \"/_akan/hmr\";\n  var attempts = 0;\n  var socket = null;\n  var lastBuildId = null;\n  var refreshRuntimePromise = null;\n  var refreshRuntime = null;\n  var pendingRefreshRegistrations = [];\n  var refreshQueue = Promise.resolve();\n  var overlayEl = null;\n  var overlayLabelEl = null;\n  var overlayDetailEl = null;\n  var overlayStyleEl = null;\n  var overlayTimer = null;\n  var overlayHideTimer = null;\n  var overlayNextToken = 1;\n  var overlayJobs = {};\n  var buildErrorStates = {};\n  self.__AKAN_HMR_PHASE__ = null;\n\n  // Bun's React Fast Refresh transform can emit top-level calls to these globals\n  // even when we fall back to full reload instead of applying React Refresh.\n  self.$RefreshReg$ = self.$RefreshReg$ || function(type, id){\n    if (refreshRuntime) refreshRuntime.register(type, id);\n    else pendingRefreshRegistrations.push([type, id]);\n  };\n  self.$RefreshSig$ = self.$RefreshSig$ || function(){ return function(type){ return type; }; };\n  // Start installing React Refresh before the application module graph loads.\n  // Injecting the runtime only on the first update is too late for React's renderer hook.\n  ensureRefreshRuntime().catch(function(err){\n    console.warn(\"[akan-hmr] React Refresh runtime preload failed\", err);\n  });\n\n  function connect(){\n    try { socket = new WebSocket(url); }\n    catch(e){ console.error(\"[akan-hmr] ws init failed\", e); schedule(); return; }\n    socket.addEventListener(\"open\", function(){ attempts = 0; });\n    socket.addEventListener(\"message\", function(ev){\n      var msg;\n      try { msg = JSON.parse(ev.data); } catch (e){ return; }\n      if (!msg || typeof msg.type !== \"string\") return;\n      if (msg.type === \"hello\") {\n        if (lastBuildId !== null && msg.buildId !== lastBuildId) {\n          location.reload();\n          return;\n        }\n        lastBuildId = msg.buildId;\n        return;\n      }\n      if (msg.type === \"reload\") {\n        beginHmrOverlay(\"Reloading...\", true);\n        try { self.__AKAN_RSC_CLEAR_CACHE__ && self.__AKAN_RSC_CLEAR_CACHE__(); } catch(e){}\n        setTimeout(function(){ location.reload(); }, 30);\n        return;\n      }\n      if (msg.type === \"rsc-refresh\") {\n        refreshRsc(msg);\n        return;\n      }\n      if (msg.type === \"client-refresh\") {\n        refreshClient(msg);\n        return;\n      }\n      if (msg.type === \"css-update\") {\n        var cssUrl = selectCssUrl(msg.cssAssets);\n        if (cssUrl) swapCss(cssUrl);\n        else {\n          beginHmrOverlay(\"Reloading...\", true);\n          location.reload();\n        }\n        return;\n      }\n      if (msg.type === \"build-status\") { handleBuildStatus(msg); return; }\n      if (msg.type === \"ok\") {\n        clearBuildErrorOverlay({\n          phase: \"build\",\n          generation: typeof msg.generation === \"number\" ? msg.generation : Number.MAX_SAFE_INTEGER,\n          files: 0\n        });\n        return;\n      }\n      if (msg.type === \"error\") {\n        console.error(\"[akan-hmr]\", msg.message);\n        showBuildErrorOverlay({ phase: \"build\", generation: 0, message: msg.message, files: 0 });\n        return;\n      }\n    });\n    socket.addEventListener(\"close\", function(){ socket = null; schedule(); });\n    socket.addEventListener(\"error\", function(){ try { socket && socket.close(); } catch(e){} });\n  }\n\n  function schedule(){\n    attempts = Math.min(attempts + 1, 6);\n    var delay = Math.min(30000, 250 * Math.pow(2, attempts - 1));\n    setTimeout(connect, delay);\n  }\n\n  function ensureOverlay(){\n    if (overlayEl && overlayLabelEl) return overlayEl;\n    if (!overlayStyleEl) {\n      overlayStyleEl = document.createElement(\"style\");\n      overlayStyleEl.textContent =\n        \"@keyframes akan-hmr-spin{to{transform:rotate(360deg)}}\" +\n        \".__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)}\" +\n        \".__akan_hmr_overlay[data-show=true]{opacity:1;transform:translateY(0)}\" +\n        \".__akan_hmr_overlay[data-status=error]{background:rgba(127,29,29,.96);border:1px solid rgba(252,165,165,.55)}\" +\n        \".__akan_hmr_overlay[data-status=ok]{background:rgba(6,95,70,.94);border:1px solid rgba(110,231,183,.45)}\" +\n        \".__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}\" +\n        \".__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)}\" +\n        \".__akan_hmr_body{display:flex;flex-direction:column;gap:3px;min-width:0}\" +\n        \".__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}\" +\n        \"@media (prefers-reduced-motion:reduce){.__akan_hmr_overlay{transition:none}.__akan_hmr_spinner{animation:none}}\";\n      document.head.appendChild(overlayStyleEl);\n    }\n    overlayEl = document.createElement(\"div\");\n    overlayEl.className = \"__akan_hmr_overlay\";\n    overlayEl.setAttribute(\"data-status\", \"updating\");\n    overlayEl.setAttribute(\"role\", \"status\");\n    overlayEl.setAttribute(\"aria-live\", \"polite\");\n    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>';\n    overlayLabelEl = overlayEl.querySelector(\"[data-akan-hmr-label]\");\n    overlayDetailEl = overlayEl.querySelector(\"[data-akan-hmr-detail]\");\n    (document.body || document.documentElement).appendChild(overlayEl);\n    return overlayEl;\n  }\n\n  function activeOverlayTokens(){\n    return Object.keys(overlayJobs);\n  }\n\n  function latestOverlayLabel(){\n    var keys = activeOverlayTokens();\n    if (keys.length === 0) return \"Updating...\";\n    return overlayJobs[keys[keys.length - 1]] || \"Updating...\";\n  }\n\n  function showOverlayNow(){\n    overlayTimer = null;\n    if (activeOverlayTokens().length === 0) return;\n    if (hasBuildErrors()) {\n      renderBuildErrorOverlay();\n      return;\n    }\n    var el = ensureOverlay();\n    el.setAttribute(\"data-status\", \"updating\");\n    if (overlayHideTimer) {\n      clearTimeout(overlayHideTimer);\n      overlayHideTimer = null;\n    }\n    if (overlayLabelEl) overlayLabelEl.textContent = latestOverlayLabel();\n    if (overlayDetailEl) overlayDetailEl.textContent = \"\";\n    requestAnimationFrame(function(){ el.setAttribute(\"data-show\", \"true\"); });\n  }\n\n  function beginHmrOverlay(label, immediate){\n    var token = overlayNextToken++;\n    overlayJobs[token] = label || \"Updating...\";\n    if (!hasBuildErrors() && overlayLabelEl) overlayLabelEl.textContent = latestOverlayLabel();\n    if (overlayHideTimer) {\n      clearTimeout(overlayHideTimer);\n      overlayHideTimer = null;\n    }\n    if (immediate) {\n      if (overlayTimer) clearTimeout(overlayTimer);\n      showOverlayNow();\n    } else if (!overlayTimer && (!overlayEl || overlayEl.getAttribute(\"data-show\") !== \"true\")) {\n      overlayTimer = setTimeout(showOverlayNow, 120);\n    }\n    return token;\n  }\n\n  function setHmrOverlayLabel(token, label){\n    if (!overlayJobs[token]) return;\n    overlayJobs[token] = label || \"Updating...\";\n    if (!hasBuildErrors() && overlayLabelEl) overlayLabelEl.textContent = latestOverlayLabel();\n  }\n\n  function endHmrOverlay(token){\n    delete overlayJobs[token];\n    if (hasBuildErrors()) {\n      renderBuildErrorOverlay();\n      return;\n    }\n    if (activeOverlayTokens().length > 0) {\n      if (overlayLabelEl) overlayLabelEl.textContent = latestOverlayLabel();\n      return;\n    }\n    if (overlayTimer) {\n      clearTimeout(overlayTimer);\n      overlayTimer = null;\n    }\n    if (!overlayEl) return;\n    overlayEl.setAttribute(\"data-show\", \"false\");\n    if (overlayHideTimer) clearTimeout(overlayHideTimer);\n    overlayHideTimer = setTimeout(function(){\n      if (overlayEl && activeOverlayTokens().length === 0 && overlayEl.parentNode) {\n        overlayEl.parentNode.removeChild(overlayEl);\n        overlayEl = null;\n        overlayLabelEl = null;\n        overlayDetailEl = null;\n      }\n    }, 180);\n  }\n\n  function handleBuildStatus(msg){\n    if (msg.status === \"error\") {\n      showBuildErrorOverlay(msg);\n      return;\n    }\n    if (msg.status === \"ok\") clearBuildErrorOverlay(msg);\n  }\n\n  function showBuildErrorOverlay(msg){\n    var phase = msg.phase || \"build\";\n    var generation = typeof msg.generation === \"number\" ? msg.generation : 0;\n    var previous = buildErrorStates[phase];\n    if (previous && generation < previous.generation) return;\n    buildErrorStates[phase] = {\n      phase: msg.phase || \"build\",\n      generation: generation,\n      message: msg.message || \"Build failed\",\n      files: typeof msg.files === \"number\" ? msg.files : 0\n    };\n    console.error(\"[akan-hmr] build failed\", buildErrorStates[phase]);\n    renderBuildErrorOverlay();\n  }\n\n  function renderBuildErrorOverlay(){\n    if (!hasBuildErrors()) return;\n    if (overlayTimer) {\n      clearTimeout(overlayTimer);\n      overlayTimer = null;\n    }\n    if (overlayHideTimer) {\n      clearTimeout(overlayHideTimer);\n      overlayHideTimer = null;\n    }\n    var el = ensureOverlay();\n    var phases = buildErrorPhases();\n    var latest = latestBuildErrorState();\n    el.setAttribute(\"data-status\", \"error\");\n    if (overlayLabelEl) overlayLabelEl.textContent = \"Build failed: \" + phases.join(\", \");\n    if (overlayDetailEl) overlayDetailEl.textContent = formatBuildStatusDetail(latest, phases.length);\n    requestAnimationFrame(function(){ el.setAttribute(\"data-show\", \"true\"); });\n  }\n\n  function clearBuildErrorOverlay(msg){\n    var phase = msg.phase || \"build\";\n    var current = buildErrorStates[phase];\n    if (!current) return;\n    var generation = typeof msg.generation === \"number\" ? msg.generation : 0;\n    var recovered = phase === \"backend\" ? generation >= current.generation : generation > current.generation;\n    if (!recovered) return;\n    delete buildErrorStates[phase];\n    if (hasBuildErrors()) {\n      renderBuildErrorOverlay();\n      return;\n    }\n    if (overlayHideTimer) clearTimeout(overlayHideTimer);\n    var el = ensureOverlay();\n    el.setAttribute(\"data-status\", \"ok\");\n    if (overlayLabelEl) overlayLabelEl.textContent = \"Build recovered\";\n    if (overlayDetailEl) overlayDetailEl.textContent = formatBuildStatusDetail(msg);\n    requestAnimationFrame(function(){ el.setAttribute(\"data-show\", \"true\"); });\n    overlayHideTimer = setTimeout(function(){\n      if (activeOverlayTokens().length > 0) {\n        showOverlayNow();\n        return;\n      }\n      if (!overlayEl) return;\n      overlayEl.setAttribute(\"data-show\", \"false\");\n      overlayHideTimer = setTimeout(function(){\n        if (overlayEl && activeOverlayTokens().length === 0 && !hasBuildErrors() && overlayEl.parentNode) {\n          overlayEl.parentNode.removeChild(overlayEl);\n          overlayEl = null;\n          overlayLabelEl = null;\n          overlayDetailEl = null;\n        }\n      }, 180);\n    }, 900);\n  }\n\n  function hasBuildErrors(){\n    return Object.keys(buildErrorStates).length > 0;\n  }\n\n  function buildErrorPhases(){\n    return Object.keys(buildErrorStates).sort();\n  }\n\n  function latestBuildErrorState(){\n    var phases = buildErrorPhases();\n    var latest = buildErrorStates[phases[0]];\n    for (var i = 1; i < phases.length; i++) {\n      var next = buildErrorStates[phases[i]];\n      if (!latest || next.generation >= latest.generation) latest = next;\n    }\n    return latest;\n  }\n\n  function formatBuildStatusDetail(msg, failedPhaseCount){\n    var parts = [];\n    if (typeof msg.generation === \"number\" && msg.generation > 0) parts.push(\"generation \" + msg.generation);\n    if (typeof msg.files === \"number\") parts.push(msg.files + \" file\" + (msg.files === 1 ? \"\" : \"s\"));\n    if (failedPhaseCount > 1) parts.push(failedPhaseCount + \" failed phases\");\n    var prefix = parts.length > 0 ? parts.join(\" \u00B7 \") : \"\";\n    if (!msg.message) return prefix;\n    return prefix ? prefix + \"\\n\" + msg.message : msg.message;\n  }\n\n  function refreshRsc(msg){\n    var started = performance.now();\n    var overlayToken = beginHmrOverlay(\"Refreshing page...\");\n    try { self.__AKAN_RSC_CLEAR_CACHE__ && self.__AKAN_RSC_CLEAR_CACHE__(); } catch(e){}\n    if (!self.__AKAN_RSC_REFRESH__) {\n      console.warn(\"[akan-hmr] RSC refresh API unavailable, falling back to full reload\");\n      setHmrOverlayLabel(overlayToken, \"Reloading...\");\n      setTimeout(function(){ location.reload(); }, 30);\n      return;\n    }\n    Promise.resolve(self.__AKAN_RSC_REFRESH__({ buildId: msg.buildId })).then(function(){\n      lastBuildId = msg.buildId;\n      endHmrOverlay(overlayToken);\n      console.debug && console.debug(\"[akan-hmr] RSC refreshed\", {\n        buildId: msg.buildId,\n        generation: msg.generation,\n        routeIds: msg.routeIds,\n        changedFiles: msg.changedFiles && msg.changedFiles.length,\n        durationMs: Math.round(performance.now() - started)\n      });\n    }, function(err){\n      console.error(\"[akan-hmr] RSC refresh failed, falling back to full reload\", err);\n      setHmrOverlayLabel(overlayToken, \"Update failed, reloading...\");\n      setTimeout(function(){ location.reload(); }, 250);\n    });\n  }\n\n  function ensureRefreshRuntime(){\n    if (refreshRuntimePromise) return refreshRuntimePromise;\n    refreshRuntimePromise = import(\"react-refresh/runtime\").then(function(mod){\n      var runtime = mod.default || mod;\n      if (!self.__AKAN_REACT_REFRESH_READY__) {\n        refreshRuntime = runtime;\n        runtime.injectIntoGlobalHook(self);\n        self.$RefreshReg$ = function(type, id){ runtime.register(type, id); };\n        self.$RefreshSig$ = runtime.createSignatureFunctionForTransform;\n        for (var i = 0; i < pendingRefreshRegistrations.length; i++) {\n          self.$RefreshReg$(pendingRefreshRegistrations[i][0], pendingRefreshRegistrations[i][1]);\n        }\n        pendingRefreshRegistrations = [];\n        self.__AKAN_REACT_REFRESH_READY__ = true;\n        self.__AKAN_REACT_REFRESH_RUNTIME__ = runtime;\n      }\n      return runtime;\n    });\n    return refreshRuntimePromise;\n  }\n\n  function refreshClient(msg){\n    refreshQueue = refreshQueue.then(function(){ return doRefreshClient(msg); }, function(){ return doRefreshClient(msg); });\n  }\n\n  function setHmrPhase(phase){\n    self.__AKAN_HMR_PHASE__ = phase;\n  }\n\n  function doRefreshClient(msg){\n    var started = performance.now();\n    var metadataAt = started;\n    var importAt = started;\n    var refreshAt = started;\n    var overlayToken = beginHmrOverlay(\"Updating...\");\n    var fallbackToRsc = false;\n    return ensureRefreshRuntime().then(function(runtime){\n      setHmrOverlayLabel(overlayToken, \"Fetching update...\");\n      var endpoint = new URL(\"/_akan/hmr/client-refresh\", location.origin);\n      endpoint.searchParams.set(\"url\", location.href);\n      if (msg.buildId != null) endpoint.searchParams.set(\"buildId\", String(msg.buildId));\n      return fetch(endpoint, { credentials: \"same-origin\", cache: \"no-store\" })\n        .then(function(res){\n          if (!res.ok) throw new Error(\"client-refresh metadata failed \" + res.status + \" \" + res.statusText);\n          return res.json();\n        })\n        .then(function(info){\n          metadataAt = performance.now();\n          var chunks = Array.isArray(info.chunks) ? info.chunks : [];\n          if (chunks.length === 0) throw new Error(\"no client chunks returned\");\n          setHmrPhase(\"refresh-import\");\n          setHmrOverlayLabel(overlayToken, \"Importing update...\");\n          return Promise.all(chunks.map(function(chunk){ return import(chunk); })).then(function(){\n            importAt = performance.now();\n            setHmrPhase(\"react-refresh\");\n            setHmrOverlayLabel(overlayToken, \"Applying update...\");\n            try {\n              runtime.performReactRefresh();\n            } finally {\n              setHmrPhase(null);\n            }\n            refreshAt = performance.now();\n            lastBuildId = msg.buildId;\n            console.debug && console.debug(\"[akan-hmr] React Fast Refresh applied\", {\n              buildId: msg.buildId,\n              generation: msg.generation,\n              chunks: chunks.length,\n              routeIds: info.routeIds || msg.routeIds,\n              changedFiles: msg.changedFiles && msg.changedFiles.length,\n              metadataMs: Math.round(metadataAt - started),\n              importMs: Math.round(importAt - metadataAt),\n              refreshMs: Math.round(refreshAt - importAt),\n              durationMs: Math.round(refreshAt - started)\n            });\n            endHmrOverlay(overlayToken);\n          }, function(err){\n            setHmrPhase(null);\n            throw err;\n          });\n        });\n    }).catch(function(err){\n      console.warn(\"[akan-hmr] React Fast Refresh failed, falling back to RSC refresh\", err);\n      fallbackToRsc = true;\n      endHmrOverlay(overlayToken);\n      refreshRsc(msg);\n    }).finally(function(){\n      if (!fallbackToRsc) endHmrOverlay(overlayToken);\n    });\n  }\n\n  function swapCss(href){\n    var overlayToken = beginHmrOverlay(\"Updating styles...\");\n    var link = document.createElement(\"link\");\n    link.rel = \"stylesheet\";\n    link.href = href;\n    link.setAttribute(\"data-akan-css\", \"pending\");\n    link.addEventListener(\"load\", function(){\n      var prev = document.querySelectorAll(\"link[data-akan-css=active]\");\n      for (var i = 0; i < prev.length; i++) prev[i].parentNode && prev[i].parentNode.removeChild(prev[i]);\n      link.setAttribute(\"data-akan-css\", \"active\");\n      endHmrOverlay(overlayToken);\n    });\n    link.addEventListener(\"error\", function(){\n      if (link.parentNode) link.parentNode.removeChild(link);\n      endHmrOverlay(overlayToken);\n    });\n    document.head.appendChild(link);\n  }\n\n  function selectCssUrl(cssAssets){\n    if (!cssAssets || typeof cssAssets !== \"object\") return null;\n    var parts = location.pathname.split(\"/\").filter(Boolean);\n    for (var i = 0; i < parts.length; i++) {\n      var asset = cssAssets[parts[i]];\n      if (asset && asset.cssUrl) return asset.cssUrl;\n    }\n    return cssAssets[\"\"] && cssAssets[\"\"].cssUrl ? cssAssets[\"\"].cssUrl : null;\n  }\n\n  connect();\n})();";

package/types/server/hmr/devHmrController.d.ts

@@ -1,9 +1,12 @@
-import { BuilderRpc, type ClientManifest, RouteClientCache, type RouteSeedIndex } from "../artifact.d.ts";
+import { BuilderRpc, type ClientManifest, type DevBuildStatus, RouteClientCache, type RouteSeedIndex } from "../artifact.d.ts";
 import type { RscWorker } from "../rscWorkerHost.d.ts";
 import type { RenderState } from "../types.d.ts";
-import { type HmrWsData, HmrWsHub } from "./wsHub.d.ts";
+import { type HmrMessage, type HmrWsData, HmrWsHub } from "./wsHub.d.ts";
 export declare function isAkanRuntimeMetadataFile(file: string): boolean;
 export declare function manifestClientEntriesForFiles(files: string[], clientManifest: ClientManifest, workspaceRoot?: string): Set<string>;
+export declare function devBuildStatusToHmrMessage(status: DevBuildStatus, previous?: DevBuildStatus): Extract<HmrMessage, {
+    type: "build-status";
+}> | null;
 export interface DevHmrControllerOptions {
     renderState: RenderState;
     rsc: RscWorker;

package/types/server/hmr/wsHub.d.ts

@@ -1,3 +1,4 @@
+import type { BuildPhase } from "../artifact.d.ts";
 export interface HmrWsData {
     kind: "akan-hmr";
     openedAt: number;
@@ -30,6 +31,16 @@ export type HmrMessage = {
         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;

package/types/server/routing/apiRouter.d.ts

@@ -23,6 +23,7 @@ export interface ApiRouteInputs {
     prefix: string;
     websocketPrefix: string;
     routes: HttpRoutes;
+    builtinRoutes?: HttpRoutes;
     routeOptions?: Record<string, SignalRouteOptions>;
     renderEnvRoutes: HttpRoutes;
     /** Upgrades the incoming request into an app-signal WebSocket. */
@@ -49,7 +50,7 @@ export declare class ApiRouter {
      *   2. Prefix every endpoint-generated route with `prefix`.
      *   3. Merge render-env routes (CSR/SSR) last so they can catch-all `/*`.
      */
-    static buildRoutes({ prefix, websocketPrefix, routes, routeOptions, renderEnvRoutes, upgradeAppWs, webProxyRunner, }: ApiRouteInputs): NonNullHttpRoutes;
+    static buildRoutes({ prefix, websocketPrefix, routes, builtinRoutes, routeOptions, renderEnvRoutes, upgradeAppWs, webProxyRunner, }: ApiRouteInputs): NonNullHttpRoutes;
     /**
      * Builds the `websocket` handler config for `Bun.serve`. Multiplexes two
      * logical channels on the same upgrade port:

package/types/signal/index.d.ts

@@ -9,6 +9,7 @@ export * from "./internal.d.ts";
 export * from "./internalArg.d.ts";
 export * from "./internalInfo.d.ts";
 export * from "./middleware.d.ts";
+export * from "./openapi.d.ts";
 export * from "./serializer.d.ts";
 export * from "./serverSignal.d.ts";
 export * from "./signalContext.d.ts";

package/types/signal/openapi/index.d.ts

@@ -0,0 +1 @@
+export * from "./openapi.d.ts";