akanjs 3.0.0-beta.2 → 3.0.0-beta.21

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,6 @@ 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.
- */
 export interface HmrStateSource {
     readonly state: {
         buildId: number;
@@ -27,14 +21,12 @@ 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;
 }
 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 +38,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 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/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";
@@ -50,18 +50,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 +64,16 @@ 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 current bundle (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.
-     */
-    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;
-}
 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 +85,6 @@ 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>;
 }

package/types/server/ssrFromRscRenderer.d.ts

@@ -11,7 +11,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 +35,6 @@ 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 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,12 @@ 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;
 }

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

@@ -35,4 +35,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;

package/types/server/systemPages.d.ts

@@ -1,12 +1,11 @@
-import { type SubRouteIndexOptions } from "./subRouteIndexDocument.d.ts";
-import { type SystemPageKind, type SystemPageOptions } from "./systemPageDocument.d.ts";
+import { type SubRouteIndexOptions, type SystemPageKind, type SystemPageOptions } from "./systemPageDocument.d.ts";
 export interface SystemPageResponseOptions extends SystemPageOptions {
     method?: string;
 }
 export interface SubRouteIndexResponseOptions extends SubRouteIndexOptions {
     method?: string;
 }
-export { createSystemPageDocument, getSystemPageHomeHref } from "./systemPageDocument.d.ts";
+export { getSystemPageHomeHref } from "./systemPageDocument.d.ts";
 export declare function createSystemPageResponse(options: SystemPageResponseOptions): Promise<Response>;
 export declare function createSubRouteIndexResponse(options: SubRouteIndexResponseOptions): Promise<Response>;
 export declare function createSystemPageHeaders(): Headers;

package/types/server/tunnel/TunnelAgent.d.ts

@@ -0,0 +1,29 @@
+import { Logger, type TunnelReadyFrame } from "akanjs/common";
+export interface TunnelAgentOptions {
+    /** The gateway, as `wss://tunnel.akanjs.com` — scheme included, no path, no trailing slash. */
+    gatewayUrl: string;
+    token: string;
+    hostnames: string[];
+    /** The local app, as `http://localhost:8282`. */
+    origin: string;
+    /** Where a `tcp` stream dials. Local by construction: an agent is a door into one machine, not a router. */
+    tcpHost?: string;
+    name?: string;
+    /** Attempts on a link that has never gone ready before the agent gives up (default 10). */
+    retryLimit?: number;
+    onReady?: (ready: TunnelReadyFrame) => void;
+    /** The control socket dropped and a reconnect is scheduled; the share is down until `onReady` comes again. */
+    onLost?: (reason: string) => void;
+    /** The gateway refused this agent for good. Nothing is retried after one of these. */
+    onFatal?: (error: Error) => void;
+}
+/** Dials out to the gateway, so its machine needs no public address, no inbound port and no NAT traversal. */
+export declare class TunnelAgent {
+    #private;
+    readonly logger: Logger;
+    constructor(options: TunnelAgentOptions);
+    get ready(): TunnelReadyFrame | null;
+    /** Resolves with the gateway's own view of the share — the hostnames and URLs it will actually serve. */
+    start(): Promise<TunnelReadyFrame>;
+    stop(reason?: string): Promise<void>;
+}

package/types/server/tunnel/TunnelDataSocket.d.ts

@@ -0,0 +1,22 @@
+import { type Logger } from "akanjs/common";
+export interface TunnelDataSocketOptions {
+    gatewayUrl: string;
+    token: string;
+    sessionId: string;
+    /** Where an `http` or `websocket` stream is replayed, as an http(s) URL with no trailing slash. */
+    origin: string;
+    /** Where a `tcp` stream dials; the port comes from the open frame. */
+    tcpHost: string;
+    logger: Logger;
+    onIdle: (socket: TunnelDataSocket) => void;
+    onBusy: (socket: TunnelDataSocket) => void;
+    onGone: (socket: TunnelDataSocket) => void;
+}
+/** Carries one stream at a time, which is what lets a payload frame be bare bytes with no stream id. */
+export declare class TunnelDataSocket {
+    #private;
+    constructor(options: TunnelDataSocketOptions);
+    get busy(): boolean;
+    open(): void;
+    close(): void;
+}

package/types/server/tunnel/TunnelHttpStream.d.ts

@@ -0,0 +1,10 @@
+import { type TunnelOpenFrame } from "akanjs/common";
+import { type TunnelStream, type TunnelStreamLink } from "./tunnelStream.d.ts";
+export declare class TunnelHttpStream implements TunnelStream {
+    #private;
+    constructor(open: TunnelOpenFrame, link: TunnelStreamLink, origin: string);
+    run(): Promise<void>;
+    push(data: Uint8Array): void;
+    end(): void;
+    reset(): void;
+}