akanjs 2.2.4 → 2.2.6

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

@@ -0,0 +1,73 @@
+export interface BuildRouteResultPayload {
+    manifestDelta: Record<string, {
+        id: string;
+        chunks: string[];
+        name: string;
+        async: boolean;
+    }>;
+    ssrManifestDelta: Record<string, Record<string, {
+        id: string;
+        chunks: string[];
+        name: string;
+        async: boolean;
+    }>>;
+    newEntries: string[];
+    discoveredEntries?: string[];
+    clientDeps: string[];
+    clientDepsByEntry?: Record<string, string[]>;
+    routeId?: string;
+    generation?: number;
+}
+export interface CssPayload {
+    cssAssets: Record<string, {
+        cssUrl: string;
+        cssRelPath: string;
+    }>;
+    cssBase64ByUrl: Record<string, string>;
+    generation?: number;
+    changedFiles?: string[];
+}
+export type BuilderReq = {
+    type: "build-route";
+    id: number;
+    routeId: string;
+    seeds: string[];
+    knownEntries: string[];
+    generation?: number;
+};
+export type BuilderRes = {
+    type: "build-route-res";
+    id: number;
+    ok: true;
+    data: BuildRouteResultPayload;
+} | {
+    type: "build-route-res";
+    id: number;
+    ok: false;
+    error: string;
+};
+export interface PagesBundlePayload {
+    bundlePath: string;
+    buildId: number;
+    generation?: number;
+    changedFiles?: string[];
+}
+export type BuilderEvent = {
+    type: "builder-ready";
+    buildId: string;
+} | {
+    type: "backend-ready";
+    pid: number;
+} | {
+    type: "invalidate";
+    kinds: ("code" | "css" | "config")[];
+    files: string[];
+    generation?: number;
+} | {
+    type: "css-updated";
+    data: CssPayload;
+} | {
+    type: "pages-updated";
+    data: PagesBundlePayload;
+};
+export type BuilderMessage = BuilderReq | BuilderRes | BuilderEvent;

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

@@ -0,0 +1,16 @@
+import type { SsrManifest } from "../ssrTypes.d.ts";
+export interface ClientManifestEntry {
+    id: string;
+    chunks: string[];
+    name: string;
+    async?: boolean;
+}
+export type ClientManifest = Record<string, ClientManifestEntry>;
+export interface BuildRouteClientResult {
+    manifestDelta: ClientManifest;
+    ssrManifestDelta: SsrManifest;
+    newEntries: string[];
+    discoveredEntries?: string[];
+    clientDeps: string[];
+    clientDepsByEntry?: Record<string, string[]>;
+}

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

@@ -0,0 +1,45 @@
+import type { SsrManifest } from "../ssrTypes.d.ts";
+import type { BuildRouteClientResult, ClientManifest } from "./manifestTypes.d.ts";
+import type { RoutesManifest } from "./routesManifestStore.d.ts";
+/**
+ * Snapshot of every per-route build's accumulated output for one HMR
+ * generation. Callers should take a `snapshot()` before rendering so an
+ * invalidate cannot mutate the manifest while a request is consuming it.
+ */
+export interface MergedManifest {
+    generation: number;
+    clientManifest: ClientManifest;
+    ssrManifest: SsrManifest;
+    /** Absolute entry-file paths seen across every build so far. */
+    knownEntries: Set<string>;
+}
+type RouteBuildFn = (routeId: string, info: {
+    seeds: string[];
+    knownEntries: Set<string>;
+    generation: number;
+}) => Promise<BuildRouteClientResult>;
+type OnMergeFn = (routeId: string, info: {
+    delta: BuildRouteClientResult;
+    merged: MergedManifest;
+    generation: number;
+}) => void | Promise<void>;
+interface RouteClientCacheOptions {
+    buildRoute: RouteBuildFn;
+    onMerge?: OnMergeFn;
+}
+export interface InvalidateClientEntriesOptions {
+    routePredicate: (routeId: string) => boolean;
+    staleEntries: Iterable<string>;
+}
+export declare class RouteClientCache {
+    #private;
+    merged: MergedManifest;
+    constructor({ buildRoute, onMerge }: RouteClientCacheOptions);
+    seed(manifest: RoutesManifest): void;
+    ensure(routeId: string, seeds: string[]): Promise<MergedManifest>;
+    snapshot(): MergedManifest;
+    invalidate(predicate: (routeId: string) => boolean): string[];
+    invalidateClientEntries({ routePredicate, staleEntries }: InvalidateClientEntriesOptions): string[];
+    clear(): string[];
+}
+export {};

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

@@ -0,0 +1,43 @@
+/**
+ * Runtime counterpart to `akanjs/devkit`'s `routeSeedIndex.ts`. The index
+ * itself is computed at build time by the CLI (which walks the `pages`
+ * registry and parses loader sources) and serialized to
+ * `route-seed-index.json`. The server only loads that JSON at boot and matches
+ * incoming pathnames against its route seed entries.
+ *
+ * Keeping this runtime-safe means `akanjs/server` never has to reach into
+ * `app/pages.ts` or Function.prototype.toString() — which is what made the
+ * previous in-process computation prone to drifting from the build pipeline.
+ */
+export interface RouteSeedEntry {
+    routeId: string;
+    pattern: string;
+    seeds: string[];
+}
+export interface RouteSeedIndex {
+    entries: RouteSeedEntry[];
+    globalLayoutFiles: string[];
+}
+export interface MatchedRoute {
+    entry: RouteSeedEntry;
+    params: Record<string, string>;
+}
+type SerializedRouteSeedEntry = Pick<RouteSeedEntry, "routeId"> & Partial<Pick<RouteSeedEntry, "pattern" | "seeds">>;
+interface SerializedRouteSeedIndex {
+    entries: SerializedRouteSeedEntry[];
+    globalLayoutFiles?: string[];
+}
+export declare const ROUTE_SEED_INDEX_JSON = "route-seed-index.json";
+export declare class RouteSeedIndexStore {
+    #private;
+    static load(artifactDir: string): Promise<RouteSeedIndex>;
+    static normalize(index: SerializedRouteSeedIndex, artifactDir: string): RouteSeedIndex;
+    /**
+     * Match `pathname` against every registered route pattern using the same
+     * `:param` semantics as route tree matching. Returns the first entry that
+     * matches, along with the extracted parameters.
+     */
+    static match(pathname: string, entries: RouteSeedEntry[]): MatchedRoute | null;
+    static matchPrefix(pathname: string, entries: RouteSeedEntry[]): MatchedRoute | null;
+}
+export {};

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

@@ -0,0 +1,16 @@
+import type { SsrManifest } from "../ssrTypes.d.ts";
+import type { ClientManifest } from "./manifestTypes.d.ts";
+export interface RoutesManifest {
+    routeIds: string[];
+    clientManifest: ClientManifest;
+    ssrManifest: SsrManifest;
+    knownEntries: string[];
+}
+type SerializedRoutesManifest = Omit<RoutesManifest, "knownEntries"> & Partial<Pick<RoutesManifest, "knownEntries">>;
+export declare class RoutesManifestStore {
+    #private;
+    static serialize(manifest: RoutesManifest, artifactDir: string): RoutesManifest;
+    static read(artifactDir: string): Promise<RoutesManifest | null>;
+    static normalize(manifest: SerializedRoutesManifest, artifactDir: string): RoutesManifest;
+}
+export {};

package/types/server/artifact.d.ts

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

package/types/server/decorators.d.ts

@@ -0,0 +1,6 @@
+/** Method decorator that catches errors and logs a warning instead of throwing. */
+export declare const Try: () => (_target: unknown, key: string, descriptor: PropertyDescriptor) => void;
+/** Method decorator that runs the method inside the detected database transaction. */
+export declare const Transaction: () => MethodDecorator;
+/** Method decorator that caches method results for the given timeout in milliseconds. */
+export declare const Cache: (timeout?: number, getCacheKey?: (...args: unknown[]) => string) => MethodDecorator;

package/types/server/di/diLifecycle.d.ts

@@ -0,0 +1,45 @@
+import type { BaseEnv } from "akanjs/base";
+import { Logger } from "akanjs/common";
+import { type Adaptor, type AdaptorCls, type Service, type ServiceCls, type WebsocketAdaptor } from "akanjs/service";
+import type { ServerSignal, ServerSignalCls } from "../../signal/serverSignal.d.ts";
+import type { AkanLib } from "../akanLib.d.ts";
+import type { WebProxyRegistration } from "../proxy.d.ts";
+import type { SignalRoutes } from "../types.d.ts";
+/**
+ * Owns the app's DI container state (registry + live maps + init order) and
+ * encapsulates every init / destroy step. `AkanServer` delegates to this so the
+ * top-level class can focus on HTTP / WS wiring and process lifecycle.
+ */
+export declare class DiLifecycle {
+    #private;
+    readonly logger: Logger;
+    readonly registry: import("akanjs/service").InjectRegistry;
+    readonly live: import("akanjs/service").LiveRegistry;
+    readonly hierarchy: {
+        adaptorStages: string[][];
+        serviceStages: string[][];
+    };
+    readonly webProxies: WebProxyRegistration[];
+    constructor(env: BaseEnv, serverMode: "federation" | "batch" | "all", ...libs: AkanLib[]);
+    /** Run every init stage in dependency order and collect the generated routes. */
+    initializeAll(): Promise<SignalRoutes>;
+    destroyAll(): Promise<void>;
+    /** Register scheduled jobs declared on internal signals. */
+    registerSchedule(serverMode: "federation" | "batch" | "all"): void;
+    /** Run the framework-level scheduler's onInit hooks after routes come up. */
+    runSchedulerInit(): Promise<void>;
+    /** Run the framework-level scheduler's onDestroy hooks during shutdown. */
+    runSchedulerDestroy(): Promise<void>;
+    /** Destroy services in reverse init order. Errors are logged, not thrown. */
+    destroyServices(): Promise<void>;
+    /** Destroy adaptors in reverse init order. Errors are logged, not thrown. */
+    destroyAdaptors(): Promise<void>;
+    destroyUses(): Promise<void>;
+    getWebsocketAdaptor(): WebsocketAdaptor | undefined;
+    getByClass(cls: ServiceCls): Service;
+    getByClass(cls: ServerSignalCls): ServerSignal;
+    getByClass(cls: AdaptorCls): Adaptor;
+    getService<T = Service>(refName: string): T;
+    getSignal<T = ServerSignal>(refName: string): T;
+    getAdaptor<T = Adaptor>(refName: string): T;
+}

package/types/server/di/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./diLifecycle.d.ts";
+export * from "./resolveAdaptorHierarchy.d.ts";
+export * from "./resolveHierarchy.d.ts";
+export * from "./resolveServiceHierarchy.d.ts";

package/types/server/di/predefinedAdaptor.d.ts

@@ -0,0 +1,33 @@
+import type { DatabaseMode } from "akanjs";
+import { type AdaptorCls, BlobStorage, type CacheAdaptor, type CompressAdaptor, ConsoleLogger, type DatabaseAdaptor, JsonCompressor, type LoggingAdaptor, type QueueAdaptor, type ScheduleAdaptor, Scheduler, SolidCache, SolidPubSub, SolidQueue, SqliteDatabase, type StorageAdaptor, type WebsocketAdaptor } from "akanjs/service";
+export interface PredefinedAdaptor {
+    database: AdaptorCls<DatabaseAdaptor>;
+    cache: AdaptorCls<CacheAdaptor>;
+    storage: AdaptorCls<StorageAdaptor>;
+    queue: AdaptorCls<QueueAdaptor>;
+    schedule: AdaptorCls<ScheduleAdaptor>;
+    logging: AdaptorCls<LoggingAdaptor>;
+    websocket: AdaptorCls<WebsocketAdaptor>;
+    compress: AdaptorCls<CompressAdaptor>;
+}
+export declare const predefinedAdaptorRole: {
+    database: AdaptorCls<DatabaseAdaptor>;
+    cache: AdaptorCls<CacheAdaptor>;
+    storage: AdaptorCls<StorageAdaptor>;
+    queue: AdaptorCls<QueueAdaptor>;
+    schedule: AdaptorCls<ScheduleAdaptor>;
+    logging: AdaptorCls<LoggingAdaptor>;
+    websocket: AdaptorCls<WebsocketAdaptor>;
+    compress: AdaptorCls<CompressAdaptor>;
+};
+export declare const predefinedAdaptor: {
+    database: typeof SqliteDatabase;
+    cache: typeof SolidCache;
+    storage: typeof BlobStorage;
+    queue: typeof SolidQueue;
+    schedule: typeof Scheduler;
+    logging: typeof ConsoleLogger;
+    websocket: typeof SolidPubSub;
+    compress: typeof JsonCompressor;
+};
+export declare const getPredefinedAdaptor: (mode?: DatabaseMode) => PredefinedAdaptor;

package/types/server/di/resolveAdaptorHierarchy.d.ts

@@ -0,0 +1,21 @@
+import { INJECT_META } from "akanjs/base";
+import type { AdaptorCls, InjectInfo } from "akanjs/service";
+import { type DependencyNode } from "./resolveHierarchy.d.ts";
+interface AdaptorNode extends DependencyNode {
+    adaptor: AdaptorCls;
+}
+export interface AdaptorHierarchy {
+    graph: Map<string, AdaptorNode>;
+    classToKey: Map<AdaptorCls, string>;
+    /** Each stage contains adaptor map keys that can be initialized concurrently. Stages run sequentially. */
+    stages: string[][];
+}
+/**
+ * Recursively collects all AdaptorCls referenced via `plug` injections,
+ * starting from the given sources (services, adaptors, or anything with INJECT_META).
+ */
+export declare function collectAdaptors(sources: {
+    [INJECT_META]: Record<string, InjectInfo>;
+}[]): Set<AdaptorCls>;
+export declare function resolveAdaptorHierarchy(adaptorMap: Map<string, AdaptorCls>, adaptorRole?: Map<AdaptorCls, AdaptorCls>): AdaptorHierarchy;
+export {};

package/types/server/di/resolveHierarchy.d.ts

@@ -0,0 +1,11 @@
+export interface DependencyNode {
+    key: string;
+    dependencies: string[];
+}
+/**
+ * Groups nodes into sequential stages where all nodes within a stage
+ * can be initialized concurrently (all their dependencies are satisfied
+ * by earlier stages).
+ */
+export declare function topologicalStages<T extends DependencyNode>(graph: Map<string, T>): string[][];
+export declare function traceCycle<T extends DependencyNode>(graph: Map<string, T>, candidates: string[]): string[];

package/types/server/di/resolveServiceHierarchy.d.ts

@@ -0,0 +1,13 @@
+import type { ServiceCls } from "akanjs/service";
+import { type DependencyNode } from "./resolveHierarchy.d.ts";
+interface ServiceNode extends DependencyNode {
+    service: ServiceCls;
+}
+export interface ServiceHierarchy {
+    graph: Map<string, ServiceNode>;
+    classToKey: Map<ServiceCls, string>;
+    /** Each stage contains service map keys that can be initialized concurrently. Stages run sequentially. */
+    stages: string[][];
+}
+export declare function resolveServiceHierarchy(serviceMap: Map<string, ServiceCls>): ServiceHierarchy;
+export {};

package/types/server/di/utils.d.ts

@@ -0,0 +1,14 @@
+interface StageTask {
+    label: string;
+    run: () => Promise<unknown>;
+}
+/**
+ * Run every task in parallel and, if any rejects, throw a single
+ * `AggregateError` that enumerates every failing label + cause. This replaces
+ * the previous `Promise.all` flow where a second concurrent failure in the
+ * same stage would hide the first, making boot errors hard to localize.
+ */
+export declare const runStage: (stageLabel: string, tasks: StageTask[]) => Promise<void>;
+export declare const toError: (reason: unknown) => Error;
+export declare const reasonMessage: (reason: unknown) => string;
+export {};

package/types/server/di.d.ts

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

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

@@ -0,0 +1,13 @@
+/**
+ * Runtime-safe change-classification types shared between the dev-time
+ * filesystem watcher (which lives in `akanjs/devkit/frontendBuild`) and
+ * the server-side HMR controller that consumes its batches over IPC.
+ *
+ * Keeping these as a types-only module lets the server package stay
+ * completely independent of `fs.watch` / `node:fs`.
+ */
+export type ChangeKind = "code" | "css" | "config" | "ignore";
+export interface ChangeBatch {
+    files: string[];
+    kinds: Set<Exclude<ChangeKind, "ignore">>;
+}

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

@@ -0,0 +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 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(){};\n  self.$RefreshSig$ = self.$RefreshSig$ || function(){ return function(type){ return type; }; };\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        reloadForHmr(msg);\n        return;\n      }\n      if (msg.type === \"client-refresh\") {\n        reloadForHmr(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  // goseoghyeon: CSR route registry keeps stale module refs, so JS/RSC HMR uses full reload for now.\n  function reloadForHmr(msg){\n    try { self.__AKAN_RSC_CLEAR_CACHE__ && self.__AKAN_RSC_CLEAR_CACHE__(); } catch(e){}\n    if (msg && msg.buildId != null) lastBuildId = msg.buildId;\n    location.reload();\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        runtime.injectIntoGlobalHook(self);\n        self.$RefreshReg$ = function(type, id){ runtime.register(type, id); };\n        self.$RefreshSig$ = runtime.createSignatureFunctionForTransform;\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

@@ -0,0 +1,24 @@
+import { BuilderRpc, type ClientManifest, 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";
+export interface DevHmrControllerOptions {
+    renderState: RenderState;
+    rsc: RscWorker;
+    seedIndex: RouteSeedIndex;
+    upgradeHmrWs: (req: Request, data: HmrWsData) => boolean;
+}
+export declare class DevHmrController {
+    #private;
+    readonly routeCache: RouteClientCache;
+    constructor({ renderState, rsc, seedIndex, upgradeHmrWs }: DevHmrControllerOptions);
+    get hub(): HmrWsHub;
+    get builderRpc(): BuilderRpc;
+    dispose(): void;
+    broadcastError(message: string): void;
+    handleWs(req: Request): Response | undefined;
+    handleClientRefresh(req: Request): Promise<Response>;
+    ensureRoute(url: URL): Promise<import("..").MergedManifest>;
+    routeIdsForPath(pathname: string): string[] | undefined;
+    static clientChunkUrls(clientManifest: ClientManifest): string[];
+}

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

@@ -0,0 +1,4 @@
+export * from "./changeBatch.d.ts";
+export * from "./clientScript.d.ts";
+export * from "./devHmrController.d.ts";
+export * from "./wsHub.d.ts";

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

@@ -0,0 +1,45 @@
+export interface HmrWsData {
+    kind: "akan-hmr";
+    openedAt: number;
+}
+export type HmrMessage = {
+    type: "hello";
+    buildId: number;
+    cssAssets?: Record<string, {
+        cssUrl: string;
+        cssRelPath: string;
+    }>;
+} | {
+    type: "reload";
+    buildId: number;
+} | {
+    type: "rsc-refresh";
+    buildId: number;
+    generation?: number;
+    changedFiles?: string[];
+    routeIds?: string[];
+} | {
+    type: "client-refresh";
+    buildId: number;
+    generation?: number;
+    changedFiles?: string[];
+    routeIds?: string[];
+} | {
+    type: "css-update";
+    cssAssets?: Record<string, {
+        cssUrl: string;
+        cssRelPath: string;
+    }>;
+} | {
+    type: "error";
+    message: string;
+};
+export declare const HMR_WS_TOPIC = "__akan_hmr";
+export declare class HmrWsHub {
+    #private;
+    get size(): number;
+    setPublisher(publish: (topic: string, payload: string) => void): void;
+    attach(ws: Bun.ServerWebSocket<HmrWsData>): void;
+    detach(ws: Bun.ServerWebSocket<HmrWsData>): void;
+    broadcast(msg: HmrMessage): void;
+}

package/types/server/hmr.d.ts

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

package/types/server/imageOptimizer.d.ts

@@ -0,0 +1,12 @@
+import { type AkanImageConfig } from "./types.d.ts";
+export interface ImageOptimizerOptions {
+    publicDir: string;
+    cacheDir: string;
+    prodMode: boolean;
+    config?: Partial<AkanImageConfig>;
+}
+export declare class ImageOptimizer {
+    #private;
+    constructor({ publicDir, cacheDir, prodMode, config }: ImageOptimizerOptions);
+    handle(req: Request): Promise<Response>;
+}

package/types/server/imageOptimizerError.d.ts

@@ -0,0 +1,4 @@
+export declare class ImageOptimizerError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}

package/types/server/index.d.ts

@@ -0,0 +1,14 @@
+export * from "./akanApp.d.ts";
+export * from "./akanLib.d.ts";
+export * from "./akanOption.d.ts";
+export * from "./akanServer.d.ts";
+export * from "./artifact.d.ts";
+export * from "./decorators.d.ts";
+export type { ChangeBatch, ChangeKind } from "./hmr/changeBatch.d.ts";
+export * from "./processMetricsCollector.d.ts";
+export * from "./proxy.d.ts";
+export * from "./routeElementComposer.d.ts";
+export * from "./routeTreeBuilder.d.ts";
+export * from "./sitemap.d.ts";
+export type { SsrManifest, SsrManifestEntry } from "./ssrTypes.d.ts";
+export * from "./types.d.ts";

package/types/server/lifecycle/shutdownManager.d.ts

@@ -0,0 +1,13 @@
+import type { Logger } from "akanjs/common";
+export declare class ShutdownManager {
+    #private;
+    /**
+     * Registers process-level handlers that drive `onShutdown` on:
+     *   - SIGTERM / SIGINT (graceful stop → exit(0) on success, exit(1) on error)
+     *   - uncaughtException / unhandledRejection (best-effort stop → exit(1))
+     *
+     * Kept separate from `AkanServer` so the server class doesn't have to know about
+     * Node-level process events, and so tests can opt out by not calling it.
+     */
+    static register(logger: Logger, onShutdown: () => Promise<void>): void;
+}

package/types/server/logging/rotatingLogWriter.d.ts

@@ -0,0 +1,20 @@
+export interface RotatingLogWriterOptions {
+    logDir: string;
+    appName: string;
+    environment: string;
+    operationMode: string;
+    maxSizeBytes?: number;
+    maxFiles?: number;
+    now?: () => Date;
+    warn?: (message: string) => void;
+}
+export declare class RotatingLogWriter {
+    #private;
+    static readonly defaultMaxSizeBytes: number;
+    static readonly defaultMaxFiles = 100;
+    constructor(options: RotatingLogWriterOptions);
+    static fromRuntimeDir(runtimeDir: string): RotatingLogWriter | null;
+    static sanitizeFilePart(value: string): string;
+    write(processKey: string, chunk: string): void;
+    close(): Promise<void>;
+}

package/types/server/processMetricsCollector.d.ts

@@ -0,0 +1,10 @@
+import type { AkanMetricsReport } from "akanjs/service";
+export declare class ProcessMetricsCollector {
+    #private;
+    static parseMemoryLogIntervalMs(value?: string | undefined): number;
+    /** Begin sampling event-loop lag. Idempotent; safe to call from each server role. */
+    static startEventLoopLagMonitor(intervalMs?: number): void;
+    static collect(extra?: AkanMetricsReport): Promise<AkanMetricsReport>;
+    static formatBytes(bytes?: number): string;
+    static format(metrics: AkanMetricsReport): string;
+}

package/types/server/proxy/akanResponse.d.ts

@@ -0,0 +1,7 @@
+import { type WebProxyNextInit, type WebProxyResult } from "./types.d.ts";
+/** Helpers for returning next/rewrite/redirect results from Akan web proxies. */
+export declare class AkanResponse {
+    static next(init?: WebProxyNextInit): WebProxyResult;
+    static redirect(url: string | URL, status?: number): Response;
+    static rewrite(url: string | URL, init?: WebProxyNextInit): WebProxyResult;
+}

package/types/server/proxy/bunRequestFields.d.ts

@@ -0,0 +1 @@
+export declare const copyBunRequestFields: (target: Request, source: Request) => Request;

package/types/server/proxy/hostBasePathWebProxy.d.ts

@@ -0,0 +1,6 @@
+import type { WebProxy } from "./types.d.ts";
+export declare class HostBasePathWebProxy implements WebProxy {
+    #private;
+    static readonly refName = "HostBasePathWebProxy";
+    use(request: Bun.BunRequest): Response | import("./types.d.ts").WebProxyResult | undefined;
+}

package/types/server/proxy/index.d.ts

@@ -0,0 +1,6 @@
+export { AkanResponse } from "./akanResponse.d.ts";
+export { copyBunRequestFields } from "./bunRequestFields.d.ts";
+export { HostBasePathWebProxy } from "./hostBasePathWebProxy.d.ts";
+export { LocaleWebProxy } from "./localeWebProxy.d.ts";
+export type { WebProxy, WebProxyCls, WebProxyMatcher, WebProxyNextInit, WebProxyRegistration, WebProxyResult, WebProxyReturn, WebProxyRunResult, } from "./types.d.ts";
+export { WebProxyRunner } from "./webProxyRunner.d.ts";

package/types/server/proxy/localeWebProxy.d.ts

@@ -0,0 +1,5 @@
+import type { WebProxy } from "./types.d.ts";
+export declare class LocaleWebProxy implements WebProxy {
+    static readonly refName = "LocaleWebProxy";
+    use(request: Bun.BunRequest): Response | import("./types.d.ts").WebProxyResult;
+}

package/types/server/proxy/types.d.ts

@@ -0,0 +1,37 @@
+import type { Cls, PromiseOrObject } from "akanjs/base";
+export declare const WEB_PROXY_RESULT: unique symbol;
+export type WebProxyNextInit = {
+    request?: {
+        headers?: HeadersInit;
+    };
+};
+export type WebProxyResult = {
+    readonly [WEB_PROXY_RESULT]: true;
+    readonly type: "next";
+    readonly request?: {
+        readonly headers?: HeadersInit;
+    };
+} | {
+    readonly [WEB_PROXY_RESULT]: true;
+    readonly type: "rewrite";
+    readonly url: string | URL;
+    readonly request?: {
+        readonly headers?: HeadersInit;
+    };
+};
+export type WebProxyReturn = Response | WebProxyResult | undefined;
+export interface WebProxy {
+    use(request: Bun.BunRequest): PromiseOrObject<WebProxyReturn>;
+}
+export type WebProxyCls = Cls<WebProxy, {
+    readonly refName: string;
+}>;
+export type WebProxyMatcher = string | RegExp | ((request: Request) => boolean);
+export type WebProxyRegistration = WebProxyCls | {
+    proxy: WebProxyCls;
+    matcher?: WebProxyMatcher;
+};
+export interface WebProxyRunResult {
+    request: Request;
+    response?: Response;
+}