akanjs 3.0.0-beta.9 → 3.0.1

package/types/server/resolver/signal.resolver.d.ts

@@ -18,26 +18,16 @@ export declare class SignalResolver {
         registry: InjectRegistry;
         live: LiveRegistry;
     }): ServerSignalCls;
-    /**
-     * Attaches the change listeners that feed live rooms, once per model that declares a `.live()` slice.
-     *
-     * Only the document write paths reach here. A query-level write — `updateManyByQuery`, the generated
-     * `update<Filter>` / `remove<Filter>`, `updateById` / `removeById` — is one atomic statement that fires no
-     * document hooks at all, exactly as it fires no cascade, so a model whose fields move that way will not push
-     * those moves to a live list. It is the same blind spot cascade has and it cannot be closed from here.
-     */
     static registerLiveSync(sliceCls: SliceCls, { registry, live }: {
         registry: InjectRegistry;
         live: LiveRegistry;
     }): string[];
     static resolveSchedule(internalCls: InternalCls, internal: Internal, serverMode: "federation" | "batch" | "all"): void;
-    /** Why an internal is not scheduled on this server, or null when it is. `placement` marks a deliberate role split. */
     static getScheduleSkipReason(internalInfo: InternalInfo, serverMode: "federation" | "batch" | "all"): {
         reason: string;
         placement: boolean;
     } | null;
     static resolveSlice(sliceCls: SliceCls): EndpointCls;
-    /** Same rule across endpoint classes, which are resolved one at a time and then folded into one table. */
     static mergeHttpRoutes(target: HttpRoutes, source: HttpRoutes): void;
     static resolveEndpoint(endpointCls: EndpointCls, endpoint: Endpoint, { registry, env, live, middleware, }: {
         registry: InjectRegistry;
@@ -45,11 +35,6 @@ export declare class SignalResolver {
         live: LiveRegistry;
         middleware: Map<string, MiddlewareCls>;
     }): SignalRoutes;
-    /**
-     * Re-checks the guards of every room this socket is subscribed to and drops the ones that no
-     * longer pass. Called when the socket's credential changes: a pubsub room is authorized once at
-     * subscribe time, so without this a signed-out socket would keep receiving its old rooms.
-     */
     static revalidateWsRooms(ws: Bun.ServerWebSocket<any>, registry: InjectRegistry, live?: LiveRegistry): Promise<string[]>;
     static handleWsOpen(ws: Bun.ServerWebSocket<any>, registry: InjectRegistry): Promise<void>;
     static handleWsClose(ws: Bun.ServerWebSocket<any>, registry: InjectRegistry, live?: LiveRegistry): Promise<void>;

package/types/server/routeElementComposer.d.ts

@@ -30,7 +30,7 @@ export declare class RouteElementComposer {
         params: Record<string, string>;
         searchParams: Record<string, string | string[]>;
     }): Promise<Head | null | undefined>;
-    static resolveHeadWithMetadata({ pathRoute, params, searchParams, }: {
+    static resolveHeadWithSnapshot({ pathRoute, params, searchParams, }: {
         pathRoute: PathRoute;
         params: Record<string, string>;
         searchParams: Record<string, string[] | string>;
@@ -51,13 +51,7 @@ export declare class RouteElementComposer {
         searchParams: Record<string, string | string[]>;
         navKey?: string;
     }): ReactNode;
-    static renderAsync({ routeRender, children, params, searchParams, }: {
-        routeRender: RouteRender;
-        children: ReactNode;
-        params: Record<string, string>;
-        searchParams: Record<string, string | string[]>;
-    }): Promise<ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | Iterable<ReactNode> | (string | number | bigint | boolean | import("react").ReactPortal | ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined)>;
-    static AsyncRender: (props: {
+    static AsyncRender: ({ routeRender, children, params, searchParams, }: {
         routeRender: RouteRender;
         children: ReactNode;
         params: Record<string, string>;

package/types/server/routeState.d.ts

@@ -62,7 +62,6 @@ export declare function isAkanRouterStateV1(value: unknown): value is AkanRouter
 export declare function encodeAkanRouterState(state: AkanRouterStateV1): string;
 export declare function encodeAkanHeadSnapshot(snapshot: AkanHeadSnapshotV1): string | null;
 export declare function decodeAkanHeadSnapshot(value: string | null | undefined): AkanHeadSnapshotDecodeResult;
-export declare function readAkanHeadSnapshotResponseHeader(headers: Headers): AkanHeadSnapshotDecodeResult;
 export declare function decodeAkanRouterState(value: string | null | undefined): AkanRouterStateV1 | null;
 export declare function appendAkanRouterStateRequestHeaders(headers: Headers, state: AkanRouterStateV1 | null | undefined): void;
 export declare function readAkanRouterStateResponseHeader(headers: Headers): AkanRouterStateV1 | null;
@@ -92,3 +91,4 @@ export declare function resolveAkanRscPatchDecision({ currentState, targetState,
     partialDecision: AkanRscPartialDecision;
 }): AkanRscPatchDecision;
 export declare function countCommonRouteSegments(currentSegments: AkanRouteSegmentState[], targetSegments: AkanRouteSegmentState[]): number;
+export declare function isAkanRscPartialCommitEnabled(): boolean;

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

@@ -4,12 +4,7 @@ import type { HmrWsHub } from "../hmr/wsHub.d.ts";
 import { type WebProxyRunner } from "../proxy.d.ts";
 import type { HttpRoutes, SignalRouteOptions, WebsocketRoutes } from "../types.d.ts";
 import { AppWsData } from "./appWsData.d.ts";
-/**
- * Minimal render-state view the HMR WS hello message needs.
- * `LazyHmrController` exposes this shape via `state.buildId` / `state.cssAssets`,
- * so the ws handler can greet freshly-connected clients
- * without reaching into the full controller.
- */
+import type { HostAllowlist } from "./hostAllowlist.d.ts";
 export interface HmrStateSource {
     readonly state: {
         buildId: number;
@@ -17,7 +12,16 @@ export interface HmrStateSource {
             cssUrl: string;
             cssRelPath: string;
         }>;
+        csrGeneration?: number;
+        ssrGeneration?: number;
+        ssrEpoch?: number;
     };
+    /** Called before each hello: brings what the state says about the dev registries up to what is on disk. */
+    refresh?: () => void;
+    /** Sent right after hello: the build statuses failing now, which the socket connected too late to hear. */
+    errors?: () => {
+        phase: string;
+    }[];
 }
 export type NonNullHttpRoutes = NonNullable<HttpRoutes>;
 export interface ApiRouteInputs {
@@ -27,14 +31,13 @@ export interface ApiRouteInputs {
     builtinRoutes?: HttpRoutes;
     routeOptions?: Record<string, SignalRouteOptions>;
     renderEnvRoutes: HttpRoutes;
-    /** Upgrades the incoming request into an app-signal WebSocket. */
     upgradeAppWs: (req: Request, data: AppWsData) => boolean;
     webProxyRunner?: WebProxyRunner | null;
+    hostAllowlist?: HostAllowlist | null;
 }
 export interface WebsocketHandlersInputs {
     wsRoutes: WebsocketRoutes;
     registry: InjectRegistry;
-    /** Only live rooms need it — a room is released from the routing table when its last socket goes. */
     live?: LiveRegistry;
     hmrHub: HmrWsHub | null;
     hmrState: HmrStateSource | null;
@@ -46,19 +49,9 @@ type WsTaggedData = {
 };
 export declare class ApiRouter {
     #private;
-    /**
-     * Builds the full route table served by `Bun.serve`. Responsibilities:
-     *   1. Expose the WS upgrade endpoint at `<prefix><websocketPrefix>`.
-     *   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, builtinRoutes, routeOptions, renderEnvRoutes, upgradeAppWs, webProxyRunner, }: ApiRouteInputs): NonNullHttpRoutes;
-    /**
-     * Builds the `websocket` handler config for `Bun.serve`. Multiplexes two
-     * logical channels on the same upgrade port:
-     *   - `kind === "akan-hmr"` — dev HMR, delegated to `HmrWsHub`.
-     *   - everything else — app signal channel, dispatched via `wsRoutes`.
-     */
+    static buildRoutes({ prefix, websocketPrefix, routes, builtinRoutes, routeOptions, renderEnvRoutes, upgradeAppWs, webProxyRunner, hostAllowlist, }: ApiRouteInputs): NonNullHttpRoutes;
     static buildWebsocketHandlers({ wsRoutes, registry, live, hmrHub, hmrState, logger, onDrain, }: WebsocketHandlersInputs): Bun.WebSocketHandler<WsTaggedData>;
+    static applyGlobalPrefix(prefix: string, path: string, options?: SignalRouteOptions): string;
+    static joinRoutePath(prefix: string, path: string): string;
 }
 export {};

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

@@ -1,40 +1,14 @@
-/**
- * Credential snapshot taken at the websocket handshake and carried on `ws.data` for the life of the
- * socket, so auth middleware and guards can read the caller the same way they read an HTTP request.
- * Only the credential headers are copied — retaining the whole `Request` would pin it for as long
- * as the socket stays open.
- */
 export declare class AppWsData {
     static fromRequest(req: Request): AppWsData;
     static of(ws: Bun.ServerWebSocket<unknown>): AppWsData;
-    /**
-     * Swaps the credential the socket authenticates with. Callers must run this synchronously on the
-     * auth frame: frames arrive in order, so a subscribe sent right after the credential must not be
-     * able to observe the previous one.
-     */
     static applyCredential(data: AppWsData, jwt: string | null): void;
     createdAt: number;
     headers: Headers;
     cookies: Bun.CookieMap;
     account?: unknown;
-    /**
-     * Identity of this connection, minted here so every app socket carries one from its first frame and
-     * adaptors and endpoints only ever read it. Per-connection and process-local — a reconnect gets a new
-     * one, and the federation gateway's own socket is a different one — so it is never a caller identity.
-     * It outlives a credential swap on purpose: the socket is still the same socket.
-     */
     socketId: string;
-    /**
-     * The caller's address as the nearest proxy recorded it, or null when nothing did.
-     *
-     * The handshake headers alone cannot say whether a proxy wrote them or the client did, so this trusts them —
-     * a socket that reached a child came through the gateway, which already resolved the question. `ipOf` is what
-     * an endpoint should read: it has the peer, so it can decide.
-     */
     get ip(): string | null;
-    /** The caller's source port as the nearest proxy recorded it, or null when nothing did. */
     get port(): number | null;
-    /** The address to answer on: what a proxy recorded, else this socket's own peer. */
     ipOf(ws: Bun.ServerWebSocket<unknown>): string | null;
     constructor(headers: Headers);
 }

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

@@ -0,0 +1,8 @@
+export declare class HostAllowlist {
+    #private;
+    constructor(hosts: Iterable<string>);
+    /** `AKAN_ALLOWED_HOSTS`: comma-separated `host:port` entries; unset or blank serves every Host. */
+    static fromEnv(env?: Record<string, string | undefined>): HostAllowlist | null;
+    allows(req: Request): boolean;
+    refuse(): Response;
+}

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

@@ -1,4 +1,5 @@
 import type { AkanChildRole, AkanMetricsReport } from "akanjs/service";
+import type { OpsRoute } from "../ops/opsRoute.d.ts";
 import type { HttpRoutes } from "../types.d.ts";
 export interface SoloAppStatus {
     role: AkanChildRole;
@@ -7,11 +8,6 @@ export interface SoloAppStatus {
     port: number | null;
     metrics: AkanMetricsReport;
 }
-/**
- * The gateway's `/_akan/app/*` surface, answered by a process nothing is proxying. The payload keeps the
- * gateway's own shape — a `children` array with this process as its only entry — so a probe, a k8s check and
- * `akan` tooling read one contract whether or not a gateway is in front.
- */
 export declare const createSoloAppRoutes: (read: () => SoloAppStatus, logStream?: {
     handle(req: Request): Response;
-} | null) => HttpRoutes;
+} | null, ops?: OpsRoute | null) => HttpRoutes;

package/types/server/rscClient.d.ts

@@ -5,17 +5,5 @@ declare global {
     var __RSC_PUSH__: ((type: InlineRscChunk[0], data: string) => void) | undefined;
     var __RSC_CLOSE__: (() => void) | undefined;
     var __AKAN_RSC_INITIAL_STATE__: string | undefined;
-    var __AKAN_RSC_NAVIGATE__: ((href: string, options?: {
-        replace?: boolean;
-        scrollToTop?: boolean;
-    }) => Promise<void>) | undefined;
-    var __AKAN_RSC_REFRESH__: ((options?: {
-        buildId?: number;
-    }) => Promise<void>) | undefined;
-    var __AKAN_RSC_CLEAR_CACHE__: (() => void) | undefined;
-    var __AKAN_RSC_IS_FROM_CACHE__: (() => boolean) | undefined;
-    var __AKAN_DEV_SYNC_NAVIGATION__: ((href: string, kind: "push" | "replace" | "back" | "pop") => void) | undefined;
-    var __AKAN_DEV_SYNC_NAVIGATION_APPLYING__: boolean | undefined;
-    var __AKAN_GET_SYNC_ROUTE_HREF__: ((href: string) => string) | undefined;
 }
 export {};

package/types/server/rscClientFetch.d.ts

@@ -1,8 +1,4 @@
 import { type AkanRouterStateV1, type AkanRscPatchMetadata } from "./routeState.d.ts";
-type RscNavigate = (href: string, options?: {
-    replace?: boolean;
-    scrollToTop?: boolean;
-}) => Promise<void> | void;
 export type RscClientFetchResponseResult = {
     type: "response";
     response: Response;
@@ -10,6 +6,8 @@ export type RscClientFetchResponseResult = {
     type: "patch";
     response: Response;
     patch: AkanRscPatchMetadata;
+} | {
+    type: "not-found";
 } | {
     type: "redirected";
     status?: number;
@@ -17,8 +15,10 @@ export type RscClientFetchResponseResult = {
 export declare function fetchRscNavigationResponse(href: string, options: {
     buildId?: number;
     currentRouterState: AkanRouterStateV1 | null;
-    navigate?: RscNavigate;
+    navigate?: (href: string, options?: {
+        replace?: boolean;
+        scrollToTop?: boolean;
+    }) => Promise<void> | void;
     sendRouterState?: boolean;
     shouldApplyNavigation?: () => boolean;
 }): Promise<RscClientFetchResponseResult>;
-export {};

package/types/server/rscClientPatch.d.ts

@@ -10,7 +10,7 @@ interface ValidateRscSegmentPatchInput<T extends PromiseLike<unknown>> {
     getCurrentNavId?: () => number;
     getHeadSnapshotPatchFailureReason?: (snapshot: AkanHeadSnapshotV1) => AkanSegmentPatchFailureReason | null;
 }
-export declare function validateRscPatchAndRequestFullFallback<T extends PromiseLike<unknown>>({ href, response, patch, currentTree, createThenable, navId, getCurrentNavId, }: ValidateRscSegmentPatchInput<T>): Promise<{
+export declare function validateRscPatchAndRequestFullFallback<T extends PromiseLike<unknown>>(input: ValidateRscSegmentPatchInput<T>): Promise<{
     sendRouterState: false;
     patchResult: AkanSegmentPatchResult<T>;
 }>;

package/types/server/rscHttp.d.ts

@@ -13,6 +13,7 @@ export declare function encodeAkanRedirectDigest(input: {
 export declare function decodeAkanRedirectDigest(digest: unknown): Omit<RscRedirectRow, "rowId">;
 export declare function isRscPayloadResponse(res: Response): boolean;
 export declare function getRscPayloadStream(res: Response): ReadableStream<Uint8Array> | null;
+export declare function concatBytes(left: Uint8Array, right: Uint8Array): Uint8Array<ArrayBuffer>;
 export declare function guardRscRedirectRows(stream: ReadableStream<Uint8Array>, options?: {
     onRedirect?: (redirect: RscRedirectRow) => void;
 }): ReadableStream<Uint8Array>;

package/types/server/rscNavigationState.d.ts

@@ -68,8 +68,9 @@ export declare function applyAkanSegmentCachePatch<T>({ currentTree, targetRoute
 }): AkanSegmentPatchResult<T>;
 export declare function rememberRscCacheEntry<T>(cache: RscNavigationCache<T>, href: string, thenable: T, maxEntries: number): void;
 export declare function deleteRscCacheEntryIfCurrent<T>(cache: RscNavigationCache<T>, href: string, thenable: T): boolean;
-export declare function rememberRscCacheNode<T>(cache: RscNavigationCache<RscNavigationCacheNode<T>>, node: RscNavigationCacheNode<T>, maxEntries: number): void;
-export declare function rememberRscPatchCacheNode<T>(cache: RscNavigationCache<RscPatchNavigationCacheNode<T>>, node: RscPatchNavigationCacheNode<T>, maxEntries: number): void;
+export declare function rememberRscCacheNode<N extends {
+    href: string;
+}>(cache: RscNavigationCache<N>, node: N, maxEntries: number): void;
 export declare function resolveCachedRscPatchNavigation<T>({ currentTree, node, partialCommitEnabled, navId, getCurrentNavId, }: {
     currentTree: AkanSegmentCacheNode<T> | null;
     node: RscPatchNavigationCacheNode<T>;

package/types/server/rscPagePrompts.d.ts

@@ -3,18 +3,9 @@ import { Logger } from "akanjs/common";
 import type { PagePromptEntry, PagePromptRun, PagePromptRunInput } from "../signal/mcp/pagePrompt.d.ts";
 interface RscPagePromptsProps {
     routes: () => PathRoute[];
-    /** The worker's own request scope — the ALS store the page's `fetch.*` calls record into. */
     run: <T>(request: Request, routeId: string, fn: () => Promise<T>) => Promise<T>;
     defaultLocale: () => string;
 }
-/**
- * Page prompts, read off `page().prompt()` declarations and answered by running the page's body.
- *
- * Running means calling the route's render functions — root layouts, layouts, then the page — inside one
- * request scope and reading the `fetch.*` queries they made off that scope's log. Nothing is rendered: the JSX a
- * body returns is an element tree nobody walks, so a client component's code never runs and the screen's data
- * footprint is exactly the set of endpoints the page asked for, with the arguments it asked with.
- */
 export declare class RscPagePrompts {
     #private;
     static readonly logger: Logger;

package/types/server/rscWorkerCache.d.ts

@@ -1,5 +1,7 @@
+import type { PageConfig } from "akanjs/client";
 import { type LruTtlCache, type RouteCacheEntry, type RouteCacheInvalidation, type RouteCacheRenderState } from "./cachePolicy.d.ts";
-import type { AkanRouterStateV1, AkanRscPatchDecision, AkanRscPatchMetadata } from "./routeState.d.ts";
+import { type AkanHeadSnapshotV1, type AkanRouterStateV1, type AkanRscPatchDecision, type AkanRscPatchMetadata } from "./routeState.d.ts";
+import type { RscTraceMetadata } from "./ssrTypes.d.ts";
 export interface CachedRscResult {
     chunks: Uint8Array[];
     bytes: number;
@@ -22,8 +24,10 @@ export interface RscPatchCacheKeyInput {
     targetRouterState: AkanRouterStateV1;
     patch: AkanRscPatchMetadata;
 }
-export declare function createRscPatchCacheKey({ baseEntry, targetRouterState, patch }: RscPatchCacheKeyInput): string;
-export declare function createRscPatchCacheEntry(input: RscPatchCacheKeyInput): RouteCacheEntry;
+export declare function createRscPatchCacheEntry({ baseEntry, targetRouterState, patch }: RscPatchCacheKeyInput): {
+    key: string;
+    ttl: number;
+};
 export declare function isRscPatchResultCacheEligible(input: {
     partialCommitEnabled: boolean;
     patch?: AkanRscPatchMetadata;
@@ -63,3 +67,37 @@ export declare function shouldUseRscWorkerFullResultCache(input: {
     patchCacheEntry: RouteCacheEntry | null;
 }): boolean;
 export declare function invalidateCachedRscResults(cache: LruTtlCache<CachedRscResult>, invalidation: RouteCacheInvalidation): void;
+export type CachedRscReplayMessage = {
+    type: "meta";
+    requestId: string;
+    theme?: string;
+    status?: number;
+    trace?: RscTraceMetadata;
+} | {
+    type: "cache-state";
+    requestId: string;
+    state: RouteCacheRenderState;
+} | {
+    type: "chunk";
+    requestId: string;
+    data: Uint8Array;
+} | {
+    type: "end";
+    requestId: string;
+};
+export declare function replayCachedRscResult(input: {
+    requestId: string;
+    chunks: readonly Uint8Array[];
+    theme?: string;
+    trace?: RscTraceMetadata;
+    cacheState?: RouteCacheRenderState;
+    send: (message: CachedRscReplayMessage) => void;
+    isCancelled: () => boolean;
+    yieldToHost?: () => Promise<void>;
+}): Promise<boolean>;
+export declare function resolveAkanRscHeadSafePatchDecision({ partialCommitEnabled, patchDecision, pageConfig, headSnapshot, }: {
+    partialCommitEnabled: boolean;
+    patchDecision: AkanRscPatchDecision;
+    pageConfig?: PageConfig;
+    headSnapshot?: AkanHeadSnapshotV1;
+}): AkanRscPatchDecision;

package/types/server/rscWorkerHost.d.ts

@@ -1,4 +1,4 @@
-import { type AkanI18nConfig, type LogRecord } from "akanjs/common";
+import { type LogRecord } from "akanjs/common";
 import type { AkanTheme } from "akanjs/fetch";
 import type { AkanMetricsReport } from "akanjs/service";
 import type { PagePromptEntry, PagePromptRun, PagePromptRunInput } from "../signal/mcp/pagePrompt.d.ts";
@@ -15,6 +15,7 @@ export interface RscPending {
         status?: number;
         trace?: RscTraceMetadata;
     }) => void;
+    onTheme?: (theme: AkanTheme | undefined) => void;
     onCacheState?: (state: RouteCacheRenderState) => void;
     onRedirect?: (location: string, method: RscRedirectMethod, status: RscRedirectStatus) => void;
     onLateRedirect?: (location: string, method: RscRedirectMethod, status: RscRedirectStatus) => void;
@@ -50,18 +51,6 @@ export declare function nextRscHostPendingChunkCount(currentPendingChunks: numbe
 export declare function isRscHostPendingChunkOverflow(pendingChunks: number, maxPendingChunks: number): boolean;
 export declare function createIdempotentRscRenderCancel(onCancel: (reason?: unknown) => void): (reason?: unknown) => void;
 export declare function createRscWorkerInvalidateCacheMessage(invalidation?: string | RouteCacheInvalidation): RscWorkerInvalidateCacheMessage;
-/**
- * The RSC worker samples its own process with the same `ProcessMetricsCollector.collect` its host
- * replica uses, so its report carries `pid` / `rssBytes` / `role` / … under the identical names.
- * `AkanServer` spreads the host's report into its own `collect({ role, ...webRouter.getMetrics() })`
- * and `collect` spreads `extra` last (`processMetricsCollector.ts:122`) — so passing these through
- * unprefixed silently overwrote the replica's own process fields, and the replica's RSS was reported
- * nowhere. Rename them onto `rscWorker*`; the `rsc*` render counters, which only the worker
- * produces, pass through untouched.
- *
- * XXX A new process-level field in `ProcessMetricsCollector.collect` must be added here too, or it
- * starts shadowing the replica again.
- */
 export declare function projectRscWorkerProcessMetrics(metrics: AkanMetricsReport): AkanMetricsReport;
 export declare function createRscHostRenderStream(input: {
     setPending: (pending: RscPending) => void;
@@ -76,48 +65,27 @@ export interface RscWorkerReloadInput {
     clientManifest: ClientManifest;
     cssAssets?: Record<string, CssAsset>;
     buildId: number;
-    /**
-     * When the builder emits a freshly bundled `pages-*.js` the host forwards
-     * the new absolute path here so the worker re-imports the new bundle.
-     * Undefined means "keep using the current bundle" (e.g. client-manifest-only
-     * reload after a lazy route build).
-     */
+    /** Undefined keeps the latest bundle a reload named (e.g. a client-manifest-only reload after a lazy route build). */
     pagesBundlePath?: string;
 }
-export interface RscWorkerRestartOptions {
-    /** Initial delay before the first restart attempt. Default: 200ms. */
-    baseDelayMs?: number;
-    /** Upper bound for the exponential backoff. Default: 30s. */
-    maxDelayMs?: number;
-    /**
-     * Give up after this many consecutive failed restarts. `undefined` (default)
-     * means retry forever so a short-lived supervisor outage doesn't wedge the
-     * SSR path permanently.
-     */
-    maxAttempts?: number;
-}
-export interface RscWorkerOptions {
-    clientManifest: ClientManifest;
-    /**
-     * Absolute path to the pre-built server pages bundle. Produced by
-     * `akanjs/devkit`'s `PagesBundleBuilder`; the RSC worker imports it with
-     * `await import(bundlePath?v=<buildId>)` — no runtime transforms.
-     */
+export interface RscAdoptedBundle {
     pagesBundlePath: string;
-    /** Initial build id for the pages bundle (see `pagesBundlePath`). */
-    pagesBundleBuildId: number;
-    cssAssets?: Record<string, CssAsset>;
-    i18n?: AkanI18nConfig;
-    /** Exponential-backoff settings for automatic crash recovery. */
-    restart?: RscWorkerRestartOptions;
+    buildId: number;
+}
+/** A reload the worker did not take: what it runs instead, and whether a later reload failed in this one's place. */
+export interface RscReloadFailure extends Error {
+    /** What the worker runs now. */
+    adopted: RscAdoptedBundle;
+    /** The latest state it was asked to take, which a later reload may have moved past the caller's own. */
+    failed: RscAdoptedBundle;
 }
 export declare class RscWorker {
     #private;
     readonly ready: Promise<void>;
-    /** Set by the replica: where the worker's forwarded log records go (its hub, or up to the gateway). */
     onLogRecords: ((records: LogRecord[], dropped: number) => void) | null;
-    constructor(artifact: BaseBuildArtifact);
-    render(req: Request): ReadableStream<Uint8Array>;
+    constructor(artifact: BaseBuildArtifact, { failBeforeReady }?: {
+        failBeforeReady?: boolean;
+    });
     renderWithMeta(req: Request, options?: {
         clientManifest?: ClientManifest;
         signal?: AbortSignal;
@@ -129,18 +97,7 @@ export declare class RscWorker {
     setLogLevel(minSev: number | null): void;
     getMetrics(): AkanMetricsReport;
     restartWhenIdle(reason: string): boolean;
-    /**
-     * Update just the CSS assets the worker inlines into rendered HTML, without
-     * re-importing any pages. Cheap enough to use for CSS-only HMR cycles so
-     * a subsequent hard refresh serves the latest hashed stylesheet.
-     */
     updateCssAssets(cssAssets: Record<string, CssAsset>): void;
-    /**
-     * Apply a new client manifest + CSS assets and instruct the worker to re-import
-     * the pages bundle with a bumped cache-bust token. When `pagesBundlePath`
-     * is provided the worker switches to the new bundle URL too (the builder
-     * emits a fresh hashed filename on every rebundle). Resolves once the
-     * worker has acknowledged via `reloaded`.
-     */
-    reload(input: RscWorkerReloadInput): Promise<void>;
+    /** Resolves with the pages bundle the worker runs once it has taken this reload, or a later one. */
+    reload(input: RscWorkerReloadInput): Promise<RscAdoptedBundle>;
 }

package/types/server/selfExec.d.ts

@@ -0,0 +1,8 @@
+export declare class SelfExec {
+    #private;
+    static adopt(): void;
+    /** A desktop app's carried server: only its shell starts the app executable as Bun. */
+    static get carried(): boolean;
+    static env(env?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+    static command(script: string, ...args: string[]): string[];
+}

package/types/server/ssrFromRscRenderer.d.ts

@@ -1,5 +1,6 @@
 import { type AkanRequestStore } from "akanjs/fetch";
-import type { SsrChunkRegistryStats, SsrFromRscInput, SsrLateRedirect } from "./ssrTypes.d.ts";
+import type { ReactNode } from "react";
+import type { SsrChunkRegistryStats, SsrDocumentOptions, SsrFromRscInput, SsrLateRedirect } from "./ssrTypes.d.ts";
 export declare class SsrChunkRegistry<T> {
     #private;
     readonly maxEntries: number;
@@ -11,7 +12,6 @@ export declare class SsrChunkRegistry<T> {
 }
 export type InlineRscChunk = readonly [1, string] | readonly [3, string];
 export declare function encodeInlineRscChunk(chunk: Uint8Array): InlineRscChunk;
-export declare function htmlEscapeJsonString(value: string): string;
 export declare function createInlineRscScript(chunk: Uint8Array): string;
 export declare function createSoftRedirectScript(redirect: SsrLateRedirect): string;
 export declare function sanitizeFlightForClientStream(stream: ReadableStream<Uint8Array>): ReadableStream<Uint8Array>;
@@ -36,17 +36,7 @@ export declare class SsrFromRscRenderer {
     #private;
     static getChunkRegistryStats(): SsrChunkRegistryStats;
     render(input: SsrFromRscInput): Promise<ReadableStream<Uint8Array>>;
-    /**
-     * React rejects `stream.allReady` for any fatal error raised after the shell flushed — an abort landing
-     * mid-flush, a `flushCompletedQueues` invariant — and it attaches a handler to that promise itself only on
-     * the shell-error path, because `completeShell` replaces `onShellError` with a noop. Shell-first streaming
-     * never reads `allReady`, so an unheld rejection reaches `process.on("unhandledRejection")`, and under
-     * federation that took the whole replica down over one request's render.
-     *
-     * Holding it keeps the failure scoped to the stream that raised it. The response cannot become a 5xx — the
-     * shell's headers and markup are already on the wire — so the client gets a truncated document and the stack
-     * goes to the log; every other request and socket on the replica survives.
-     */
+    static renderDocument(root: ReactNode, options: SsrDocumentOptions): Promise<ReadableStream<Uint8Array>>;
     static holdPostShellErrors(stream: {
         allReady: Promise<void>;
     }, report: (error: unknown) => void): void;

package/types/server/ssrTypes.d.ts

@@ -40,12 +40,7 @@ export interface RscTraceMetadata {
     patchHeadSafe?: boolean;
     patchHeadSnapshot?: string;
     routeState?: string;
-    /**
-     * Resolved from the matched route's `pageConfig.ssr === "block"`. Rides the
-     * trace so the host (which never resolves pageConfig itself) can decide
-     * whether the full-document SSR pass buffers until every Suspense boundary
-     * resolves. Absent/`false` means stream the shell first.
-     */
+    /** The route's `pageConfig.ssr === "block"`, carried here because the host never resolves pageConfig itself. */
     ssrBlocking?: boolean;
 }
 export interface SsrFromRscInput {
@@ -54,34 +49,20 @@ export interface SsrFromRscInput {
     rscStream: ReadableStream<Uint8Array>;
     ssrManifest: SsrManifest;
     bootstrapModules?: string[];
-    /** Extra inline JS appended to the framework's bootstrap script. The HMR
-     * dev client lives here so the browser wires up its reload channel before
-     * any application module evaluates. */
     extraBootstrapInline?: string;
-    /**
-     * Bare specifier -> served URL mapping for the `<script type="importmap">`
-     * the HTML stream should prepend to `<head>`. Used so per-route client
-     * chunks (which externalize `react`, `react-dom/client`, ...) resolve
-     * those specifiers to the base build's vendor entries at load time,
-     * guaranteeing one React instance across rscClient and every route
-     * chunk.
-     *
-     * Injection happens via a stream transform, not React children, because the
-     * spec is strict: import maps must be acquired before any module script fetch
-     * starts, including modulepreload. Akan writes bootstrap module preloads
-     * directly after this importmap and delays the executable module script until
-     * the Fizz HTML stream has completed.
-     */
     importmap?: Record<string, string>;
     theme?: AkanTheme;
     injectThemeInitScript?: boolean;
     lateControl?: Promise<SsrLateRedirect | null>;
     onCancel?: (reason?: unknown) => void;
-    /**
-     * When true, buffer the whole document until every Suspense boundary resolves
-     * (`stream.allReady`) before emitting a byte, matching `pageConfig.ssr:
-     * "block"`. Defaults to shell-first streaming so `Loading` fallbacks surface.
-     * The `AKAN_SSR_WAIT_FOR_ALL_READY=1` env var forces blocking globally.
-     */
+    /** Buffers until `stream.allReady` (`pageConfig.ssr: "block"`); `AKAN_SSR_WAIT_FOR_ALL_READY=1` forces it globally. */
     waitForAllReady?: boolean;
+    /** Buffers like `waitForAllReady` and writes every Suspense boundary in place, for a reader that runs no script. */
+    inlineBoundaries?: boolean;
+}
+export interface SsrDocumentOptions {
+    bootstrap: string;
+    waitForAllReady?: boolean;
+    inlineBoundaries?: boolean;
+    onError: (error: unknown, phase?: string) => void;
 }

package/types/server/staticPath.d.ts

@@ -1,17 +1 @@
-/**
- * The file a URL path names inside one directory, or `null` when it names something outside it.
- *
- * Every static route the web router serves goes through here, so this is the single place a request path stops
- * being a string and becomes a file. The order matters: percent-decoding first (so `%2e%2e` is seen as `..`),
- * then a NUL check (a truncating byte in a path), then `path.resolve` to collapse the traversal, then
- * containment against the base **with a separator** — without it `/public-secrets` passes a `/public` check.
- *
- * Symlinks are followed, like nginx and `serve-static` do: `akan sync` builds `public/libs/<lib>` as a link to
- * `<workspaceRoot>/libs/<lib>/public`, so a link out of the tree is how a lib ships its assets, not an attack.
- * Refusing those would 404 every lib asset under `akan start` and nothing else — `akan build` copies `public/`
- * with `dereference: true`, so a built app has no links left to refuse. Traversal is what the string checks
- * above stop, and they run before any of this touches the filesystem.
- *
- * Callers check existence after this, so a path that resolves to nothing is handed back and 404s there.
- */
 export declare const resolveStaticPath: (baseDir: string, urlPath: string) => string | null;

package/types/server/systemPageDocument.d.ts

@@ -9,6 +9,8 @@ export interface SystemPageOptions {
     stylesheetHref?: string | null;
     showDetails?: boolean;
     error?: unknown;
+    /** Dev only: the HMR client, so a page that failed to render reloads once a later build fixes it. */
+    script?: string;
 }
 export interface SystemPageHomeHrefOptions {
     pathname: string;
@@ -35,4 +37,12 @@ export declare const SYSTEM_PAGE_STATUS_COPY: {
 export declare const SYSTEM_PAGE_STYLE = "\n:root { color-scheme: dark; --akan-primary: #ff493b; --akan-secondary: #2b2e33; --akan-accent: #d1a23b; --akan-foreground: #ffffff; --akan-background: #1a1a1a; --akan-error: #f02020; }\nbody { margin: 0; min-height: 100vh; font-family: ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, \"Segoe UI\", sans-serif; background: var(--akan-background); color: var(--akan-foreground); }\na { color: inherit; }\n.akan-system-page { min-height: 100vh; display: grid; place-items: center; padding: 32px 18px; box-sizing: border-box; background: radial-gradient(circle at top left, rgba(255, 73, 59, 0.16), transparent 34%), linear-gradient(135deg, var(--akan-background), #111); }\n.akan-system-card { width: min(720px, 100%); border: 1px solid rgba(255, 255, 255, 0.12); border-radius: 32px; background: linear-gradient(145deg, rgba(42, 42, 42, 0.96), rgba(43, 46, 51, 0.78)); box-shadow: 0 24px 80px rgba(0, 0, 0, 0.36); padding: clamp(28px, 6vw, 56px); }\n.akan-system-status { margin: 0 0 18px; font-weight: 800; font-size: clamp(4rem, 18vw, 8rem); line-height: 0.85; letter-spacing: -0.08em; color: var(--akan-primary); }\n.akan-system-eyebrow { margin: 0 0 10px; color: var(--akan-accent); font-size: 0.78rem; font-weight: 800; letter-spacing: 0.18em; text-transform: uppercase; }\n.akan-system-title { margin: 0; max-width: 12ch; font-size: clamp(2rem, 7vw, 4rem); line-height: 0.95; letter-spacing: -0.055em; color: var(--akan-foreground); }\n.akan-system-description { margin: 22px 0 0; max-width: 56ch; color: rgba(255, 255, 255, 0.76); font-size: 1.05rem; line-height: 1.75; }\n.akan-system-path { margin: 22px 0 0; overflow-wrap: anywhere; border: 1px solid rgba(255, 255, 255, 0.1); border-radius: 16px; background: rgba(26, 26, 26, 0.72); padding: 12px 14px; color: rgba(255, 255, 255, 0.72); font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace; font-size: 0.88rem; }\n.akan-system-actions { margin-top: 30px; display: flex; flex-wrap: wrap; gap: 12px; }\n.akan-system-action { display: inline-flex; min-height: 44px; align-items: center; justify-content: center; border: 1px solid var(--akan-primary); border-radius: 999px; background: var(--akan-primary); box-shadow: 0 12px 34px rgba(255, 73, 59, 0.26); color: var(--akan-foreground); padding: 0 18px; font-weight: 800; text-decoration: none; }\n.akan-system-secondary { border: 1px solid rgba(255, 255, 255, 0.12); background: var(--akan-secondary); color: var(--akan-foreground); }\n.akan-system-details { margin-top: 28px; max-height: 260px; overflow: auto; border-radius: 18px; background: rgba(26, 26, 26, 0.82); border: 1px solid rgba(240, 32, 32, 0.22); padding: 16px; color: rgba(255, 255, 255, 0.78); font-size: 0.82rem; line-height: 1.55; white-space: pre-wrap; }\n";
 export declare function createSystemPageDocument(options: SystemPageOptions): ReactNode;
 export declare function getSystemPageErrorDetails(error: unknown): string;
+export declare function getPathnameLocale(pathname: string, i18n: AkanI18nConfig): string;
 export declare function getSystemPageHomeHref({ pathname, i18n, basePaths, headerBasePath, }: SystemPageHomeHrefOptions): string;
+export interface SubRouteIndexOptions {
+    locale: string;
+    basePaths: string[];
+    subRoutes?: Record<string, string[]>;
+}
+export declare const getSubRouteIndexHref: (locale: string, basePath: string) => string;
+export declare function createSubRouteIndexDocument({ locale, basePaths, subRoutes }: SubRouteIndexOptions): ReactNode;