akanjs 3.0.0-beta.9 → 3.0.1

package/types/server/akanServer.d.ts

@@ -15,82 +15,42 @@ export interface AkanServerOptions {
     openapi?: boolean;
     /** `/mcp` is mounted by default; `false` takes it off, and the object form carries the rest of its settings. */
     mcp?: boolean | McpServerOption;
-    /**
-     * Boot only these modules and the ones they reach; every other module stays out of the container, so its
-     * services, signals, routes and schedules do not exist. Omitted or empty mounts every enabled module.
-     */
+    /** Boot only these modules and what they reach; omitted or empty mounts every enabled module. */
     modules?: string[];
-    /**
-     * The inverse of `modules`: mount everything except these and whatever reaches them. Written for a lib the
-     * app depends on but does not serve — `server.ts` is generated from the dependency graph, so a lib cannot be
-     * dropped by editing it. Applied after `modules`, so a module named by both stays out.
-     */
+    /** Mount all but these and whatever reaches them; applied after `modules`, so one named by both stays out. */
     disableModules?: string[];
-    /**
-     * The same, by owning lib: every module the named libs registered stays out, along with everything that
-     * reaches one. This is the spelling for a lib the app depends on but does not serve — it does not drift as
-     * the lib gains modules.
-     */
+    /** Like `disableModules`, by owning lib, so it does not drift as the lib gains modules. */
     disableLibs?: string[];
 }
 export interface McpServerOption {
     enabled?: boolean;
-    /**
-     * Drops every mutation from the catalogue whatever its guards allow — for a deployment that must not be able to
-     * write, such as a read replica or a demo. Off by default, and reported per endpoint in the boot log, because a
-     * switch that silently unlists a published endpoint cannot tell its author why it vanished.
-     */
+    /** Drops every mutation from the catalogue whatever its guards allow; off by default, reported per endpoint. */
     readOnly?: boolean;
-    /**
-     * Mount path, `/mcp` by default. The published OAuth resource identifier follows it, so changing it changes
-     * the `aud` a token has to carry.
-     */
+    /** Mount path, `/mcp` by default; the OAuth resource id (the `aud` a token must carry) follows it. */
     path?: string;
-    /** Reported as `serverInfo.version`. Defaults to `0.0.0`, the same placeholder the OpenAPI document uses. */
+    /** Reported as `serverInfo.version`; `0.0.0` by default. */
     version?: string;
-    /**
-     * Free-text usage guidance handed to the model alongside the tool list — the one place to say what this app
-     * is for and which tool to reach for first. Defaults to a bare one-liner naming the app.
-     */
+    /** Guidance handed to the model with the tool list; defaults to a one-liner naming the app. */
     instructions?: string;
-    /**
-     * Extra origins allowed past the DNS-rebinding check, beyond the server's own host. Needed only for a
-     * browser-hosted MCP client; native ones send no `Origin` at all.
-     */
+    /** Origins let past the DNS-rebinding check beyond the server's own host (only browser-hosted clients send one). */
     allowedOrigins?: string[];
-    /** Entries per catalogue page. A client that wants the whole list follows `nextCursor` until it stops. */
     pageSize?: number;
-    /**
-     * The one language the catalogue and its error text are written in, `en` by default. Server-wide on purpose:
-     * the document is built once at boot and cached by clients, and it is read by a model rather than by a person.
-     */
+    /** Language of the catalogue and its error text, `en` by default; server-wide because clients cache the document. */
     language?: string;
-    /**
-     * Whether a structured result also ships as serialized JSON in the text block, `true` by default because that
-     * is what the spec asks of a server for clients that predate `structuredContent`. It is also a flat doubling:
-     * every model-returning tool sends its whole payload twice, so a deployment whose clients read the structured
-     * half turns this off and halves what each of those calls costs the model. `AKAN_MCP_LEGACY_TEXT=false`.
-     */
+    /** Repeat structured results as JSON in the text block, per spec; `true` by default. `AKAN_MCP_LEGACY_TEXT`. */
     legacyTextBlock?: boolean;
     /**
-     * How much of a result's shape each tool advertises: `shallow` (default) names nested models instead of inlining
-     * them, `full` inlines the whole closure, `none` publishes no `outputSchema` and keeps the text block on. The
-     * listing is re-sent to every agent that connects, and the nested closures were most of it. `AKAN_MCP_OUTPUT_SCHEMA`.
+     * `shallow` (default) names nested models, `full` inlines the whole closure, `none` publishes no `outputSchema` and
+     * keeps the text block on. `AKAN_MCP_OUTPUT_SCHEMA`.
      */
     outputSchema?: "full" | "shallow" | "none";
-    /** OAuth resource-server identity: which issuers a client may authenticate with, and the scopes to demand. */
     auth?: McpAuthOption;
     /**
-     * Per-caller budget for `tools/call`, `resources/read` and `prompts/get`: 120 calls a minute and 8 in flight by
-     * default, counted per process. `false` takes it off. `AKAN_MCP_RATE_LIMIT` (`<calls>` or `<calls>/<seconds>`,
-     * `off` to disable) and `AKAN_MCP_CONCURRENT`.
+     * Per-caller budget for tools/call, resources/read and prompts/get: 120/min and 8 in flight per process by default;
+     * `false` disables. `AKAN_MCP_RATE_LIMIT` (`<calls>[/<seconds>]` or `off`), `AKAN_MCP_CONCURRENT`.
      */
     rateLimit?: McpRateLimitOption | false;
-    /**
-     * Characters of screen data one page prompt may attach before its lists are cut, 60,000 by default. A page's
-     * `{ limit: 0 }` is right for a screen and wrong for a model's window, so the cap is the server's, not the
-     * page's. `AKAN_MCP_PROMPT_BUDGET`.
-     */
+    /** Characters a page prompt may attach before its lists are cut; 60,000 by default. `AKAN_MCP_PROMPT_BUDGET`. */
     promptBudget?: number;
 }
 export interface AkanServerConsoleInfo {
@@ -130,7 +90,7 @@ export declare class AkanServer {
     setPrefix(prefix: string): this;
     setWebsocketPrefix(websocketPrefix: string): this;
     setOpenApi(openapi?: boolean): this;
-    /** Narrows the web surface this process serves. Never widens it past what the build produced. */
+    /** Narrows the web surface; never widens it past what the build produced. */
     setWeb(web?: AkanWebOption): this;
     setMcp(mcp?: boolean | McpServerOption): this;
     setDatabaseConfig(database: DatabaseConfig): this;

package/types/server/animatedImage.d.ts

@@ -1,7 +1 @@
-/**
- * `Bun.Image.metadata()` reports only `{ width, height, format }` — there is no frame count — and an
- * animated GIF decodes to its first frame without erroring. So an optimizer that re-encodes whatever
- * decodes would silently drop the animation. These readers answer the question from the container bytes
- * instead, so an animated source can be passed through untouched.
- */
 export declare const isAnimatedImage: (buffer: Buffer, contentType: string) => boolean;

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

@@ -1,50 +1,29 @@
-import type { CssPayload, DevBuildStatus, PagesBundlePayload } from "./ipcTypes.d.ts";
-import type { BuildRouteClientResult } from "./manifestTypes.d.ts";
+import type { BuildRouteClientResult, CsrUpdatedPayload, CssPayload, DevBuildStatus, PagesBundlePayload, SsrUpdatedPayload } from "./ipcTypes.d.ts";
 export interface BuilderRpcEventHandlers {
-    /**
-     * Filesystem batch invalidation from the builder's watcher. The backend
-     * should treat this as a hint to clear its route cache and broadcast a
-     * dev reload to connected HMR clients.
-     */
+    /** A watcher batch changed files: clear the route cache and broadcast a dev reload. */
     onInvalidate?: (event: {
         kinds: ("code" | "css" | "config")[];
         files: string[];
         generation?: number;
     }) => void;
-    /** Builder proactively recompiled CSS; payload includes base64 bytes. */
     onCssUpdated?: (css: CssPayload) => void;
-    /**
-     * Builder emitted a freshly bundled `pages-*.js`. Backend should
-     * re-import it (e.g. by calling `RscWorker.reload({ pagesBundlePath,
-     * buildId })`) so new user code takes effect without spawning a new
-     * worker subprocess.
-     */
-    onPagesUpdated?: (bundle: PagesBundlePayload) => void;
-    /** Builder reported a dev build phase success/failure. */
+    /** A fresh `pages-*.js` bundle: re-import it in the running worker (`RscWorker.reload`) rather than respawning. */
+    onPagesUpdated?: (bundle: PagesBundlePayload) => void | Promise<void>;
+    onCsrUpdated?: (update: CsrUpdatedPayload) => void;
+    onSsrUpdated?: (update: SsrUpdatedPayload) => void;
     onBuildStatus?: (status: DevBuildStatus) => void;
 }
-/**
- * Typed RPC facade around the raw `BuilderTransport`. Handles the
- * correlation-id bookkeeping (request promise + resolver map) and exposes
- * a narrow surface matching the three builder operations.
- *
- * Only one `BuilderRpc` instance should exist per backend process. It
- * subscribes to the transport at construction and unsubscribes on
- * `dispose()`.
- */
+/** One per backend process: subscribes to the IPC channel on construction and unsubscribes on `dispose()`. */
 export declare class BuilderRpc {
     #private;
     constructor(handlers?: BuilderRpcEventHandlers);
-    buildRoute(routeId: string, { seeds, knownEntries, generation }: {
+    buildRoute(routeId: string, { seeds, graphSeeds, knownEntries, generation, }: {
         seeds: string[];
+        graphSeeds?: string[];
         knownEntries: Set<string>;
         generation?: number;
     }): Promise<BuildRouteClientResult>;
-    /**
-     * Ask the builder to build the dev CSR artifact and keep it in sync from now on. The builder skips
-     * CSR by default (a full minified browser-target build of every page, ~350 MB per save), so the
-     * first `/__csr` or `?csr=true` request has nothing to serve until this resolves.
-     */
+    /** Arms dev CSR, which the builder skips by default (a full browser build per save), and keeps it in sync after. */
     buildCsr(reason: string): Promise<void>;
     dispose(): void;
 }

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

@@ -0,0 +1,4 @@
+import type { DevBuildStatus } from "./ipcTypes.d.ts";
+export declare class DevBuildRecovery {
+    static recovers(previous: DevBuildStatus | undefined, status: DevBuildStatus): boolean;
+}

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

@@ -1,6 +1,6 @@
 export * from "./builderRpc.d.ts";
+export * from "./devBuildRecovery.d.ts";
 export * from "./ipcTypes.d.ts";
-export * from "./manifestTypes.d.ts";
 export * from "./routeClientCache.d.ts";
 export * from "./routeSeedIndexStore.d.ts";
 export * from "./routesManifestStore.d.ts";

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

@@ -1,3 +1,4 @@
+import type { SsrManifest } from "../ssrTypes.d.ts";
 export interface BuildRouteResultPayload {
     manifestDelta: Record<string, {
         id: string;
@@ -17,14 +18,10 @@ export interface BuildRouteResultPayload {
     clientDepsByEntry?: Record<string, string[]>;
     routeId?: string;
     generation?: number;
+    /** The newest save batch whose files its client-entry discovery had taken in when it started. */
+    seenGeneration?: number;
 }
-/**
- * Marks a frontend payload that re-announces a freshly booted artifact rather than reporting an edit.
- * A recycled builder rebuilds every artifact from scratch, but a running backend read
- * `base-artifact.json` once at boot and never re-reads it, so the new state has to be pushed. The
- * host drops such a payload when the hashed output did not actually move, which keeps a clean
- * recycle invisible to connected browsers.
- */
+/** Re-announces a recycled builder's artifact (not an edit); the host drops it when the hashed output did not move. */
 export type BuilderStateReason = "builder-recycle";
 export interface CssPayload {
     cssAssets: Record<string, {
@@ -46,19 +43,22 @@ export interface DevChangePlan {
     actions: DevChangeAction[];
     reasonByFile: Record<string, string[]>;
 }
-export type BuildPhase = "scan" | "barrel" | "csr" | "pages" | "css" | "route" | "backend";
+export type BuildPhase = "scan" | "barrel" | "csr" | "ssr" | "pages" | "css" | "route" | "backend";
 export interface DevBuildStatus {
     generation: number;
     phase: BuildPhase;
     ok: boolean;
     files: string[];
     message?: string;
+    /** The route a route build's status speaks for. */
+    scope?: string;
 }
 export type BuilderReq = {
     type: "build-route";
     id: number;
     routeId: string;
     seeds: string[];
+    graphSeeds?: string[];
     knownEntries: string[];
     generation?: number;
 };
@@ -73,12 +73,7 @@ export type BuilderRes = {
     ok: false;
     error: string;
 };
-/**
- * Dev CSR artifacts are only reachable through the opt-in `/__csr` and `?csr=true` routes (mobile
- * local dev points a device WebView at the latter), so the builder skips them until a request
- * actually needs one. The first such request arms the builder through this pair and waits for the
- * build, after which every save keeps CSR in sync.
- */
+/** Sent by the first `/__csr` or `?csr=true` request (a device WebView in mobile dev) to arm the lazy dev CSR build. */
 export type BuilderCsrReq = {
     type: "build-csr";
     id: number;
@@ -94,40 +89,67 @@ export type BuilderCsrRes = {
     ok: false;
     error: string;
 };
-/**
- * Asks the builder to finish its queued work and exit, which is the only way bundler memory is
- * returned to the OS (see `BuilderMetrics`). The host's existing restart path brings up a
- * replacement, so a graceful drain — rather than a kill — keeps a rebuild in flight from being
- * truncated.
- */
+/** Drain and exit (the only way bundler memory returns to the OS); draining, not killing, keeps a rebuild whole. */
 export type BuilderControl = {
     type: "builder-shutdown";
     reason: string;
 };
+/** Epoch-ms marks a save picks up on its way to the page, so a slow update says which hop it waited in. */
+export interface HmrTrace {
+    eventAt?: number;
+    flushAt?: number;
+    batchAt?: number;
+    spawnAt?: number;
+    workerStartAt?: number;
+    workerAt?: number;
+    patchAt?: number;
+    sentAt?: number;
+    broadcastAt?: number;
+}
 export interface PagesBundlePayload {
     bundlePath: string;
     buildId: number;
     generation?: number;
     changedFiles?: string[];
     reason?: BuilderStateReason;
+    trace?: HmrTrace;
+    /** False when no changed file is one the server renders (a `"use client"` edit that kept its export names). */
+    serverTouched?: boolean;
 }
-/**
- * `Bun.build` retains native bundler arenas that `Bun.gc(true)` never reclaims — the JS heap stays flat
- * while RSS climbs. **How much comes back without exiting is platform-specific**: measured on Bun
- * 1.3.14, macOS returns none of it (0% after 60s idle) while Linux purges 46-59% after ~10-15s idle.
- * The dev host recycles past a ceiling to bound the macOS case.
- *
- * Because this is only reported when the builder's queues drain, `rssBytes` is a *peak* sample. On
- * Linux it goes stale within seconds, so the host re-reads the builder's RSS from the OS before acting
- * on it. See `local/optimize-resource/09-linux-retention-measurement.md`.
- */
+/** `Bun.build` keeps native arenas `Bun.gc(true)` never frees (macOS returns none when idle): hence recycling. */
 export interface BuilderMetrics {
+    /** A peak sampled when the queues drain; stale within seconds on Linux, so the host re-reads RSS from the OS. */
     rssBytes: number;
-    /** The builder's newest generation; 0 until it has processed a watch batch since spawning. */
+    /** The builder's newest generation; a replacement builder continues from the last one its host saw. */
     generation: number;
     /** Work items completed since this builder spawned, so a host can require real work before recycling. */
     workCount: number;
 }
+export interface CsrUpdatedPayload {
+    generation: number;
+    mode: "registry" | "artifact";
+    reload: boolean;
+    reason?: string;
+    patchUrl?: string;
+    changedIds?: string[];
+    trace?: HmrTrace;
+}
+/** A new generation of the SSR dev registry, where SSR pages load their client code from: a patch, or a reload. */
+export interface SsrUpdatedPayload {
+    generation: number;
+    reload: boolean;
+    reason?: string;
+    patchUrl?: string;
+    changedIds?: string[];
+    trace?: HmrTrace;
+    /** The save also changed what the server renders: the tabs get this patch with that batch's RSC refresh. */
+    hold?: boolean;
+    /** The watch batch this patch came from, which the `pages-updated` releasing it names as its generation. */
+    batchGeneration?: number;
+    epoch?: number;
+    /** The registry's first build: no tab holds a module of it, so there is nothing to send them. */
+    first?: boolean;
+}
 export type BuilderEvent = {
     type: "builder-ready";
     buildId?: string;
@@ -146,11 +168,38 @@ export type BuilderEvent = {
 } | {
     type: "pages-updated";
     data: PagesBundlePayload;
+} | {
+    type: "csr-updated";
+    data: CsrUpdatedPayload;
+} | {
+    type: "ssr-updated";
+    data: SsrUpdatedPayload;
 } | {
     type: "build-status";
     data: DevBuildStatus;
 } | {
     type: "builder-metrics";
     data: BuilderMetrics;
+}
+/** The boot builds settled (the SSR registry's, and CSR's when the env arms it): their workers are a boot's peak. */
+ | {
+    type: "boot-armed";
 };
 export type BuilderMessage = BuilderReq | BuilderRes | BuilderCsrReq | BuilderCsrRes | BuilderControl | BuilderEvent;
+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[]>;
+    /** The newest save batch whose files its client-entry discovery had taken in when it started. */
+    seenGeneration?: number;
+}

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

@@ -1,11 +1,7 @@
 import type { SsrManifest } from "../ssrTypes.d.ts";
-import type { BuildRouteClientResult, ClientManifest } from "./manifestTypes.d.ts";
+import type { BuildRouteClientResult, ClientManifest } from "./ipcTypes.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.
- */
+/** One HMR generation's merged route builds; render from a `snapshot()`, which an invalidate cannot mutate. */
 export interface MergedManifest {
     generation: number;
     clientManifest: ClientManifest;
@@ -30,22 +26,25 @@ interface RouteClientCacheOptions {
 export interface InvalidateClientEntriesOptions {
     routePredicate: (routeId: string) => boolean;
     staleEntries: Iterable<string>;
+    /** The saved files behind it: a build still running that bundled one of them is built again. */
+    files?: Iterable<string>;
+    /** The save batch behind it: a route build whose discovery had taken that batch in is neither dropped nor rebuilt. */
+    batch?: number;
 }
 export declare class RouteClientCache {
     #private;
     merged: MergedManifest;
     constructor({ buildRoute, onMerge }: RouteClientCacheOptions);
-    /**
-     * Bumped on every mutation of `merged`, including a delta merge that leaves `generation` where it was. It lets a
-     * consumer memoize work derived from the manifest — merging the runtime manifest over it, say — without having to
-     * copy the manifest to find out whether anything changed. In production nothing after `seed` moves it at all.
-     */
+    /** Bumped on every change to `merged`, even a delta merge that keeps `generation`: a memo key for derived work. */
     get revision(): number;
     seed(manifest: RoutesManifest): void;
     ensure(routeId: string, seeds: string[]): Promise<MergedManifest>;
     snapshot(): MergedManifest;
-    invalidate(predicate: (routeId: string) => boolean): string[];
-    invalidateClientEntries({ routePredicate, staleEntries }: InvalidateClientEntriesOptions): string[];
+    invalidate(predicate: (routeId: string) => boolean, { files, batch }?: {
+        files?: Iterable<string>;
+        batch?: number;
+    }): string[];
+    invalidateClientEntries({ routePredicate, staleEntries, files, batch, }: InvalidateClientEntriesOptions): string[];
     clear(): string[];
 }
 export {};

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

@@ -1,14 +1,3 @@
-/**
- * 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;
@@ -32,11 +21,6 @@ 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;
 }

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

@@ -1,5 +1,5 @@
 import type { SsrManifest } from "../ssrTypes.d.ts";
-import type { ClientManifest } from "./manifestTypes.d.ts";
+import type { ClientManifest } from "./ipcTypes.d.ts";
 export interface RoutesManifest {
     routeIds: string[];
     clientManifest: ClientManifest;

package/types/server/binaryPubsub.d.ts

@@ -1,10 +1,3 @@
-/**
- * Sends binary pubsub frames and absorbs a slow subscriber. `Server.publish` reports `-1` when the socket is
- * backpressured, `0` when the room has no subscriber, and the byte count otherwise — so a room that cannot
- * keep up parks its newest frame here and every earlier one is dropped, rather than queueing behind the
- * slowest subscriber until the send buffer is the stream. Bun fires `drain` per socket when its buffer
- * empties; that is what flushes the parked frames.
- */
 export declare class BinaryPubsub {
     #private;
     get coalescedCount(): number;
@@ -12,7 +5,6 @@ export declare class BinaryPubsub {
     publish(roomId: string, frame: Uint8Array, { coalesce }?: {
         coalesce?: boolean;
     }): void;
-    /** Retries every parked room. A room still backpressured re-parks itself and waits for the next drain. */
     flush(): void;
     clear(): void;
 }

package/types/server/cachePolicy.d.ts

@@ -4,6 +4,7 @@ export interface RouteCacheKeyInput {
     request: Request;
     url: URL;
     theme?: string;
+    variant?: string;
 }
 export interface RouteCacheRenderState {
     cacheable: boolean;
@@ -55,7 +56,6 @@ export declare function resolveAutoRouteCacheTtl(input: {
     defaultTtl?: number;
     defaultEnabled?: boolean;
 }): number | null;
-export declare function combineMinRevalidate(...values: Array<number | false | null | undefined>): number | false | undefined;
 export declare function getClientFacingOrigin(request: Request, url?: URL): string;
 export declare function isPublicRouteCacheableRequest(request: Request): boolean;
 export declare function isRouteCachePathAllowed(pathname: string, options?: {
@@ -63,12 +63,11 @@ export declare function isRouteCachePathAllowed(pathname: string, options?: {
     deny?: string | null;
     defaultAllow?: boolean;
 }): boolean;
-export declare function createRouteCacheKey({ request, url, theme }: RouteCacheKeyInput): string;
+export declare function createRouteCacheKey({ request, url, theme, variant }: RouteCacheKeyInput): string;
 export declare function createRouteCacheEntry(input: RouteCacheKeyInput & {
     ttl: number;
 }): RouteCacheEntry;
 export declare function resolvePublicRouteCacheEntryDecision(input: PublicRouteCacheEntryInput): RouteCacheEntryDecision;
-export declare function resolvePublicRouteCacheEntry(input: PublicRouteCacheEntryInput): RouteCacheEntry | null;
 export declare function resolveRouteCacheStoreTtl(baseTtl: number, state: RouteCacheRenderState): number | null;
 export declare function shouldStoreRouteCache(input: {
     policy?: AkanRequestPolicy;
@@ -79,22 +78,13 @@ export declare function shouldStoreRouteCache(input: {
 export declare function hasRouteCacheInvalidationScope(invalidation?: RouteCacheInvalidation): boolean;
 export declare function shouldInvalidateRouteCacheEntry(metadata: RouteCacheMetadata, invalidation: RouteCacheInvalidation): boolean;
 export interface LruTtlCacheOptions<T> {
-    /**
-     * Measures one entry's payload. Entry count alone says nothing about a cache whose entries span
-     * three orders of magnitude, and a byte ceiling needs a running total to enforce. The default
-     * reports 0 rather than guessing, so `byteSize` stays honest about not knowing.
-     */
+    /** Defaults to reporting 0 rather than guessing, so `byteSize` stays honest about not knowing. */
     sizeOf?: (value: T) => number;
     /** Total payload ceiling. 0 leaves the cache bounded only by `maxEntries`. */
     maxBytes?: number;
     /** An entry over this is not stored at all, rather than evicting everything else to fit it. */
     maxEntryBytes?: number;
-    /**
-     * Cadence of the idle sweep. Without one a filled cache never shrinks: an entry is dropped only
-     * when its own key is fetched after expiry or when a write evicts it, so a pod that stops
-     * serving holds its peak forever — measured at 100 entries / 21.4 MiB still resident 310s after
-     * the last request, with a 30s TTL. 0 disables it.
-     */
+    /** Idle sweep cadence; without it a cache nobody reads or writes never releases expired entries. 0 disables it. */
     sweepIntervalMs?: number;
 }
 export declare class LruTtlCache<T> {
@@ -104,16 +94,8 @@ export declare class LruTtlCache<T> {
     get size(): number;
     get byteSize(): number;
     get(key: string): T | null;
-    /** Returns whether the entry was stored; a payload over `maxEntryBytes` is rejected. */
     set(key: string, value: T, ttlSeconds: number): boolean;
-    /**
-     * Drops every expired entry. Deliberately a full scan rather than a walk from the oldest that
-     * stops at the first live entry: insertion order is *LRU* order because `get` reinserts, and TTLs
-     * differ per entry, so expiry is not monotonic in map order and an early break would leave
-     * expired entries behind. The map is bounded by `maxEntries`, so the scan is cheap.
-     */
     sweepExpired(now?: number): number;
-    /** Stops the idle sweep. The cache stays usable; only the timer goes away. */
     dispose(): void;
     delete(key: string): boolean;
     invalidate(predicate: (key: string, value: T) => boolean): number;

package/types/server/console.d.ts

@@ -3,7 +3,7 @@ import type { Adaptor, Service } from "akanjs/service";
 import type { ServerSignal } from "akanjs/signal";
 import type { AkanServer } from "./akanServer.d.ts";
 import { type AkanConsoleCommand } from "./consoleSession.d.ts";
-export * from "./consoleEvaluator.d.ts";
+export { evaluateAkanConsoleInput, isAkanConsoleInputComplete } from "./consoleSession.d.ts";
 export interface AkanConsoleOptions {
     prompt?: string;
     globals?: Record<string, unknown>;
@@ -14,10 +14,7 @@ export interface AkanConsoleOptions {
 }
 /** `level=warn grep="payment failed" endpoint=mutation:*` → a query object the socket parses. */
 export declare const parseAkanConsoleQuery: (args: string) => Record<string, string>;
-/**
- * `.tail` and `.trace` attach to the *running* server's control socket — the console booted its own
- * `listen: false` server, whose logs are not the ones anybody is looking for.
- */
+/** Attaches to the running server's control socket, not the console's own `listen: false` server. */
 export declare const createAkanConsoleLogCommands: (appName: string, runtimeDir: string) => Record<string, AkanConsoleCommand>;
 export interface AkanConsoleContext extends Record<string, unknown> {
     server: AkanServer;
@@ -29,7 +26,7 @@ export interface AkanConsoleContext extends Record<string, unknown> {
     methods: (value: unknown) => string[];
     debug: () => ReturnType<AkanServer["inspectConsole"]>;
 }
-export declare const assertAkanConsoleAllowed: (env?: Pick<BaseEnv, "environment" | "operationMode">) => void;
+export declare const assertAkanConsoleAllowed: (env?: Partial<Pick<BaseEnv, "environment" | "operationMode">>) => void;
 export declare const getAkanConsoleMethods: (value: unknown) => string[];
 export declare const createAkanConsoleContext: (server: AkanServer, globals?: Record<string, unknown>) => AkanConsoleContext;
 export declare const startAkanConsole: (server: AkanServer, options?: AkanConsoleOptions) => Promise<void>;

package/types/server/consoleSession.d.ts

@@ -11,12 +11,12 @@ export interface AkanConsoleSessionOptions {
     /** Dot-commands beyond the built-ins, keyed with their leading dot (`.tail`). */
     commands?: Record<string, AkanConsoleCommand>;
 }
+export declare const isAkanConsoleInputComplete: (source: string) => boolean;
+export declare const evaluateAkanConsoleInput: (source: string, context: Record<string, unknown>) => Promise<unknown>;
 export declare class AkanConsoleSession {
     #private;
     constructor(options: AkanConsoleSessionOptions);
-    /** Runs when the session closes; what a command that holds a connection uses to let go of it. */
     onClose(dispose: () => void): void;
-    /** Output that arrives between keystrokes: the prompt line is cleared, the text lands, the prompt redraws. */
     write(text: string): void;
     run(): Promise<void>;
 }

package/types/server/contentEncoding.d.ts

@@ -1,9 +1,3 @@
-/**
- * br is tried first: it is ~15% smaller than gzip across the artifact and ~22% on the CSS bundle, and on a
- * model listing it is half of gzip's size at the same cost. The gzip entry stays the fallback because browsers
- * only advertise `br` on secure origins, so a plain-http dev server or an intermediary that rewrites
- * Accept-Encoding still gets a compressed body.
- */
 export declare const CONTENT_ENCODINGS: readonly [{
     readonly encoding: "br";
     readonly ext: ".br";
@@ -17,12 +11,10 @@ export type ContentEncoding = (typeof CONTENT_ENCODINGS)[number]["encoding"];
 /** `q=0` is an explicit refusal, not a preference. */
 export declare const acceptsEncoding: (acceptEncoding: string, accept: RegExp) => boolean;
 export declare const isCompressibleContentType: (contentType: string) => boolean;
-export declare const negotiateContentEncoding: (req: Request) => ContentEncoding | null;
-/**
- * Compresses a fully-materialized response the caller accepts an encoding for, or hands back the original.
- *
- * Buffers the body, so it is only ever applied where the body is already in memory — a signal endpoint's JSON.
- * A streamed response (SSR HTML, an RSC flight payload, an event stream) must not reach this: buffering one
- * would hold the whole render before the first byte, which is the opposite of what streaming it was for.
- */
 export declare const compressResponse: (req: Request, response: Response) => Promise<Response>;
+export interface EncodedSidecar {
+    bytes: ArrayBuffer;
+    encoding: string;
+}
+export declare const resolveEncodedSidecar: (req: Request, filePath: string, contentType: string) => Promise<EncodedSidecar | null>;
+export declare const encodedFileResponse: (req: Request, filePath: string, contentType: string, headers: Headers) => Promise<Response>;

package/types/server/crawler.d.ts

@@ -0,0 +1 @@
+export declare const isCrawlerUserAgent: (userAgent: string | null | undefined) => boolean;

package/types/server/decorators.d.ts

@@ -1,16 +1,4 @@
-/**
- * Method decorators for a server class: `@Transaction`, `@Try`, `@CacheMethod`. Kept because `libs/util`'s
- * storage adaptors use `@Try` on their remote calls; new code follows the adaptor rule instead
- * (`catch` → `logger.error` → `return null`).
- */
 /** 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.
- *
- * Not `Cache` — `akanjs/signal` exports a `Cache` **middleware class**, and an app importing both barrels got
- * one name meaning two things.
- */
-export declare const CacheMethod: (timeout?: number, getCacheKey?: (...args: unknown[]) => string) => MethodDecorator;