akanjs 3.0.0-beta.2 → 3.0.0-beta.20

package/types/index.d.ts

@@ -2,11 +2,10 @@ import type { AkanI18nConfig } from "akanjs/common";
 import type { AkanImageConfig } from "akanjs/server";
 export declare const archs: readonly ["amd64", "arm64"];
 export type Arch = (typeof archs)[number];
-/** One image step. The object form runs only on the matching `TARGETARCH` leg of a multi-arch build. */
+/** The object form runs only on the matching `TARGETARCH` leg of a multi-arch build. */
 export type DockerRun = string | {
     [key in Arch]?: string;
 };
-/** The pieces Akan assembles a Dockerfile from. */
 export interface DockerImageConfig {
     image: string | {
         [key in Arch]?: string;
@@ -17,17 +16,10 @@ export interface DockerImageConfig {
     postRuns: DockerRun[];
     command: string[];
 }
-/**
- * A whole Dockerfile as a string, or the parts Akan assembles one from. The string form is taken verbatim —
- * nothing is merged into it, including the steps a lib contributes through its own `docker`.
- */
+/** The string form is taken verbatim: nothing is merged into it, not even a lib's `docker` steps. */
 export type DockerConfig = string | DockerImageConfig;
-/** What an `akan.config.ts` may write for `docker`: a whole Dockerfile, or any subset of the parts. */
 export type DockerOption = string | Partial<DockerImageConfig>;
-/**
- * A lib's contribution to the image of every app that mounts it — a lib never picks the base image or the
- * command, only the steps its own runtime needs.
- */
+/** Steps every app mounting the lib inherits; a lib never picks the base image or the command. */
 export interface LibDockerConfig {
     preRuns: DockerRun[];
     postRuns: DockerRun[];
@@ -42,39 +34,23 @@ export interface AkanRouteConfig {
     basePath?: string;
     domains: AkanRouteDomains;
 }
-/**
- * Which web surfaces an app serves, resolved. `ssr` is the RSC/SSR route renderer and everything it needs —
- * the pages bundle, the client bundles, the RSC worker process. `csr` is the single-file SPA shell that the
- * Capacitor mobile build ships and that `/__csr` serves.
- */
+/** `ssr`: the RSC/SSR renderer with its bundles and RSC worker; `csr`: the SPA shell Capacitor ships and `/__csr` serves. */
 export interface AkanWebConfig {
     ssr: boolean;
     csr: boolean;
 }
 /**
- * What an `akan.config.ts` may write. `false` is an API-only app — no web artifact is built and no web route
- * is mounted; `true` (the default) is both surfaces. The object form keeps SSR and toggles only the CSR
- * bundle, which is the whole range there is: the CSR bundle inlines the stylesheet the SSR build compiles, so
- * CSR without SSR would ship an unstyled app and is not expressible here.
+ * `false` is an API-only app, `true` (the default) both surfaces; the object form toggles only CSR, because the CSR
+ * bundle inlines the stylesheet the SSR build compiles.
  */
 export type AkanWebOption = boolean | {
     csr: boolean;
 };
-/**
- * How `akan build` trims the `public/` tree it copies into `dist`. Source trees are never touched: an app's
- * and a lib's `public/` keep every file, and only the build's own copy is trimmed.
- */
+/** Trims only the build's own copy of `public/`; source trees keep every file. */
 export interface AkanAssetsConfig {
-    /**
-     * Drop font files from the build's `public/` that no built surface references. A font with `optimize` on is
-     * served from `/_akan/fonts` after subsetting, so its source is a build input the image never reads.
-     */
+    /** Drops fonts no built surface references; an `optimize` font is served subset from `/_akan/fonts`. */
     pruneFonts: boolean;
-    /**
-     * Font files to keep whatever the scan concludes, as globs relative to this app's or lib's own `public/`
-     * (`"fonts/Assistant-*.woff2"`). For the case a scan cannot see: a URL assembled at runtime. Declare it in
-     * the `akan.config.ts` that owns the font, so the reason travels with the lib rather than with the app.
-     */
+    /** Globs relative to the owning app's or lib's `public/`, for fonts a scan cannot see (a runtime-built URL). */
     keepFonts: string[];
 }
 /** A lib picks only which of its own fonts must survive; whether to prune at all belongs to the app. */
@@ -166,10 +142,10 @@ export interface AkanExecutor {
 export interface AkanSyncContext {
     readonly appName: string;
     readonly appPath: string;
-    /** The full app/lib executor for advanced scan-result access and file operations. */
     readonly executor: AkanExecutor;
     getPath(rel: string): string;
     fileExists(rel: string): Promise<boolean>;
+    readFile(rel: string): Promise<string>;
     writeFile(rel: string, content: string, opts?: {
         overwrite?: boolean;
     }): Promise<void>;
@@ -178,7 +154,6 @@ export interface AkanSyncContext {
 }
 export interface AkanNativeContext {
     readonly appPath: string;
-    /** The app executor for advanced scan-result access and file operations. */
     readonly executor: AkanExecutor;
     readonly target: AkanMobileTargetConfig;
     readonly operation: "local" | "release";
@@ -199,14 +174,13 @@ export interface AkanNativeContext {
 export interface AkanPluginCapacitorConfig {
     /** Mobile permission that activates this plugin's native config (reuses the existing permission model). */
     permission?: MobilePermission;
-    /** Imperative native (Capacitor) project configuration. */
     configureNative?: (ctx: AkanNativeContext) => Promise<void>;
 }
+/** Read live by the CLI at build time; it carries functions, so it stays out of the serializable config results. */
 export interface AkanPlugin {
     name: string;
     /** Runtime npm packages this plugin needs; installed on demand by the CLI (e.g. firebase for push). */
     runtimePackages?: (ctx: PluginRuntimeContext) => string[];
-    /** Native (Capacitor) project configuration. */
     capacitor?: AkanPluginCapacitorConfig;
     /** Build-time asset generation (e.g. `public/firebase-messaging-sw.js`). */
     syncAssets?: (ctx: AkanSyncContext) => Promise<void>;
@@ -217,22 +191,27 @@ export interface AkanApiConfig {
     /** Where the websocket upgrade sits under `prefix`. Defaults to `/ws`. */
     websocketPrefix: string;
 }
+export interface AkanDatabaseConfig {
+    /**
+     * The build carries each mode's drivers; a deployment picks one with `AKAN_DATABASE_MODE` (required when there are
+     * several), and `akan start` runs the first unless the shell names another.
+     */
+    modes: DatabaseMode[];
+}
 export interface AppConfigResult {
     docker: DockerConfig;
-    defaultDatabaseMode: DatabaseMode;
+    database: AkanDatabaseConfig;
     /**
-     * Where this app mounts its endpoints. Declared here rather than only in `main.ts` because the value is baked
-     * into every client bundle: a prebuilt CSR shell or a mobile bundle never reaches the server that would tell
-     * it otherwise. `new AkanApp({ prefix })` still overrides the server and every server-rendered page.
+     * Baked into every client bundle, since a prebuilt CSR shell or mobile bundle never asks the server;
+     * `new AkanApp({ prefix })` still overrides the server and every server-rendered page.
      */
     api: AkanApiConfig;
     /** Web surfaces built into the app and mounted at boot. Both default to `true`. */
     web: AkanWebConfig;
     routes?: AkanRouteConfig[];
     /**
-     * Mounts `libs/<lib>/page` into this app under `page/(libs)/(<lib>)` on sync. `true` takes every lib
-     * dependency that ships a `page` folder, an array takes exactly the libs listed, `false` (the default)
-     * syncs nothing and removes what a previous sync created.
+     * Mounts `libs/<lib>/page` under `page/(libs)/(<lib>)` on sync: `true` every lib dependency with a `page` folder, an
+     * array exactly those libs, `false` (the default) nothing, removing what a previous sync created.
      */
     syncPageLibs?: string[] | boolean;
     externalLibs: string[];
@@ -243,7 +222,6 @@ export interface AppConfigResult {
     publicEnv: string[];
     mobile: AkanMobileConfig;
     secrets: string[];
-    /** How the build trims the `public/` copy it ships. */
     assets: AkanAssetsConfig;
 }
 export interface LibConfigResult {
@@ -278,24 +256,14 @@ export interface SubspaceDeclaration {
     repo: string;
     /** Apps this subspace serves. Libraries are never listed — they are derived from each app's closure. */
     apps: string[];
+    /** The subspace's own `AKAN_WORKSPACE_ID`, not this workspace's; only `akan subspace upload-env` reads it. */
+    workspaceId?: string;
 }
-/**
- * What `akan.subspace.ts` at a workspace root may write: the customer repos this workspace is mirrored
- * to. There is no branch field — the branch is whichever one the workspace is on, so one declaration
- * serves every release branch and each of them holds one akanjs version and one copy of the library
- * source.
- */
+/** `akan.subspace.ts`: the repos this workspace mirrors to, on whichever branch the workspace is on. */
 export interface SubspaceConfigInput {
-    /**
-     * Branches a push may target. A feature branch is refused, because pushing it would copy this
-     * workspace's branch namespace into every customer repo.
-     */
+    /** A feature branch is refused: pushing it would copy this workspace's branch namespace into every customer repo. */
     pushableBranches?: string[];
-    /**
-     * Workspace-root entries to keep out of every subspace, on top of the ones that always are. Top-level
-     * names or `dir/` prefixes — a workspace's own infra, release and benchmark trees are the usual
-     * entries.
-     */
+    /** Workspace-root names or `dir/` prefixes kept out of every subspace, on top of the ones that always are. */
     exclude?: string[];
     subspaces: SubspaceDeclaration[];
 }
@@ -355,10 +323,8 @@ export interface FileConventionScanResult {
     };
 }
 /**
- * What a *live* scan exposes on `AppInfo.file` / `LibInfo.file`: a set per module kind, with every file
- * type carrying all four kinds. `FileConventionScanResult` above is the serialized form that crosses a
- * process boundary as JSON, which is why it is arrays and why each file type lists only the kinds it can
- * hold. The two are not interchangeable — every reader of `.file` calls `.has()`.
+ * The live form of `FileConventionScanResult` on `AppInfo.file`/`LibInfo.file` (every reader calls `.has()`); the
+ * arrays above are its JSON form, which lists only the kinds each file type can hold.
  */
 export interface FileConventionScanSet {
     all: Set<string>;

package/types/server/akanApp.d.ts

@@ -1,5 +1,4 @@
 import { Logger } from "akanjs/common";
-/** Options for the Akan gateway that launches child server replicas and listens for traffic. */
 export interface AkanAppOptions {
     replica?: number | string;
     serverPath?: string;
@@ -7,41 +6,19 @@ export interface AkanAppOptions {
     port?: number;
     wsBasePort?: number;
     openapi?: boolean;
-    /**
-     * Where the signal endpoints are mounted, `/api` by default. Handed down as `AKAN_API_PREFIX`, which every
-     * server process reads — the replicas that build the route table, and the RSC worker, whose page-side
-     * `fetch.*` calls travel over HTTP like any other client's. A server-rendered page also carries it to the
-     * browser, so the tab's `fetchClient` follows the process that rendered it. A prebuilt CSR or mobile bundle
-     * cannot be reached that way and follows `akan.config.ts` instead.
-     */
+    /** Signal endpoint mount, `/api` by default; handed down as `AKAN_API_PREFIX` (CSR/mobile follow akan.config.ts). */
     prefix?: string;
     /** Where the websocket upgrade sits under `prefix`, `/ws` by default. Handed down as `AKAN_WS_PREFIX`. */
     websocketPrefix?: string;
-    /**
-     * Boot only these modules and the ones they reach, in every child. Omitted or empty mounts every enabled
-     * module. Handed down as `AKAN_MODULES`, since each replica builds its own container.
-     */
+    /** Boot only these modules and what they reach; omitted or empty mounts every enabled one. `AKAN_MODULES`. */
     modules?: string[];
-    /**
-     * The inverse of `modules`: mount everything except these and whatever reaches them, in every child. 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. Handed down as `AKAN_DISABLE_MODULES`, and applied after `modules`.
-     */
+    /** Mount all but these and whatever reaches them, applied after `modules`. `AKAN_DISABLE_MODULES`. */
     disableModules?: string[];
-    /**
-     * The same, by owning lib: every module the named libs registered stays out of every child, along with
-     * everything that reaches one. Handed down as `AKAN_DISABLE_LIBS`.
-     */
+    /** Like `disableModules`, by owning lib. `AKAN_DISABLE_LIBS`. */
     disableLibs?: string[];
-    /**
-     * Run the one replica in this process instead of spawning it — see `#startSolo`. Defaults on for a single
-     * traffic replica the environment configured, and off whenever `replica` is passed here, because code that
-     * states a topology is asking for the gateway that serves it. `AKAN_SOLO=false` turns it off; like
-     * `AKAN_SSR`, the env can only narrow, so it cannot force a gateway's replicas into one process.
-     */
+    /** In-process replica; default on for one env-set traffic replica, off if `replica` is passed or AKAN_SOLO=false. */
     solo?: boolean;
 }
-/** Gateway/orchestrator that starts Akan child servers and proxies HTTP/WebSocket traffic. */
 export declare class AkanApp {
     #private;
     readonly logger: Logger;

package/types/server/akanAppHeaders.d.ts

@@ -1,4 +1,3 @@
-/** What `Server.requestIP` reports for the socket this hop accepted. */
 export interface ProxyClientPeer {
     address: string;
     port: number;

package/types/server/akanOption.d.ts

@@ -1,45 +1,31 @@
 import type { BackendEnv, PromiseOrObject } from "akanjs/base";
 import type { Adaptor, AdaptorCls, LlmOption } from "akanjs/service";
-import type { CrossSiteOption, GuardCls, MiddlewareCls } from "akanjs/signal";
+import type { AgentQuotaHook, AgentUsageHook, CrossSiteOption, GuardCls, MiddlewareCls } from "akanjs/signal";
 import type { McpServerOption } from "./akanServer.d.ts";
 import type { WebProxyRegistration } from "./proxy.d.ts";
 export interface AdaptorOverride {
     role: AdaptorCls;
     adaptor: AdaptorCls;
 }
-/**
- * App/library server option builder: use objects, signal middleware, adaptor overrides, web proxies, and the
- * server settings an app owns — MCP, the agent relay's access guards, and the LLM the relay speaks to.
- */
 export declare class AkanOption<Env extends BackendEnv = BackendEnv> {
     #private;
-    constructor();
     use(fnOrObject: ((env: Env) => Record<string, PromiseOrObject<unknown>>) | Record<string, PromiseOrObject<unknown>>): this;
     applyMiddleware(...middlewares: MiddlewareCls[]): this;
     /** Rebinds a predefined adaptor role (e.g. `LlmAdaptorRole`) to the app's own implementation. Last writer wins. */
     applyAdaptor<T extends Adaptor>(role: AdaptorCls<T>, adaptor: AdaptorCls<T>): this;
     applyWebProxy(...proxies: WebProxyRegistration[]): this;
-    /**
-     * MCP server settings for the app mounting this option, merged over the `AKAN_MCP_*` environment and under an
-     * option the server is constructed with. The app's own `option.ts` is the last lib the server reads, so it wins
-     * over every library it depends on. The function form receives the server env, for a setting derived from it —
-     * a token verifier built on the app's signing secret, the issuer an authorization server publishes under.
-     */
+    /** Merged over the `AKAN_MCP_*` env and under the constructor option; the app's `option.ts` wins over its libs'. */
     setMcp(mcpOrFn?: boolean | McpServerOption | ((env: Env) => boolean | McpServerOption)): this;
-    /**
-     * Who may spend the LLM key through the `runAgentTurn` relay, named as the guards any other endpoint would
-     * name. With none the call is refused — the same answer `None` gives — because the framework has no account
-     * model to gate on. Several are ANDed; `null` clears what a library set.
-     */
+    /** Guards for the `runAgentTurn` relay: with none every call is refused, several are ANDed, `null` clears a lib's. */
     setAgentAccess(guards: GuardCls | GuardCls[] | null): this;
-    /**
-     * Which other origins may drive a mutation, on top of the one serving the request and the native shells.
-     * Needed only by a browser client hosted somewhere else — a separate admin domain, a partner embed. The gate
-     * itself is on by default and `{ enabled: false }` is for an API no browser reaches.
-     */
+    /** Called once per relayed turn with the provider's token counts, after the answer is sent; `null` clears a lib's. */
+    setAgentUsage(hook: AgentUsageHook | null): this;
+    /** Asked before a turn spends the key; `false` refuses it with `agent.error.quotaExceeded`. */
+    setAgentQuota(hook: AgentQuotaHook | null): this;
+    /** Extra origins that may drive a mutation beyond the serving one and native shells; the gate is on by default. */
     setCrossSite(crossSite: CrossSiteOption): this;
-    /** Settings for whichever adaptor fills `LlmAdaptorRole`, injected into it as the `llmOption` use. */
-    setLlm(llmOrFn: LlmOption | ((env: Env) => LlmOption)): this;
+    /** Injected into the `LlmAdaptorRole` adaptor as the `llmOption` use; merged in mount order, the app's last. */
+    setLlm<Option extends LlmOption>(llmOrFn: Option | ((env: Env) => Option)): this;
     /** Every entry in declaration order, duplicates kept: the boot stage rejects a key claimed twice. */
     getUses(env: Env): [string, PromiseOrObject<unknown>][];
     getMiddlewares(): MiddlewareCls[];
@@ -47,6 +33,8 @@ export declare class AkanOption<Env extends BackendEnv = BackendEnv> {
     getWebProxies(): WebProxyRegistration[];
     getMcp(env: Env): boolean | McpServerOption | undefined;
     getAgentAccess(): GuardCls | GuardCls[] | null | undefined;
+    getAgentUsage(): AgentUsageHook | null | undefined;
+    getAgentQuota(): AgentQuotaHook | null | undefined;
     getCrossSite(): CrossSiteOption | undefined;
     getLlm(env: Env): LlmOption;
 }

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,27 @@
-import type { CssPayload, DevBuildStatus, PagesBundlePayload } from "./ipcTypes.d.ts";
-import type { BuildRouteClientResult } from "./manifestTypes.d.ts";
+import type { BuildRouteClientResult, CssPayload, DevBuildStatus, PagesBundlePayload } 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.
-     */
+    /** A fresh `pages-*.js` bundle: re-import it in the running worker (`RscWorker.reload`) rather than respawning. */
     onPagesUpdated?: (bundle: PagesBundlePayload) => void;
-    /** Builder reported a dev build phase success/failure. */
     onBuildStatus?: (status: DevBuildStatus) => void;
 }
-/**
- * Typed RPC facade around the raw `BuilderTransport`. Handles the
- * 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/index.d.ts

@@ -1,6 +1,5 @@
 export * from "./builderRpc.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;
@@ -18,13 +19,7 @@ export interface BuildRouteResultPayload {
     routeId?: string;
     generation?: 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, {
@@ -59,6 +54,7 @@ export type BuilderReq = {
     id: number;
     routeId: string;
     seeds: string[];
+    graphSeeds?: string[];
     knownEntries: string[];
     generation?: number;
 };
@@ -73,12 +69,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,12 +85,7 @@ 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;
@@ -111,17 +97,9 @@ export interface PagesBundlePayload {
     changedFiles?: string[];
     reason?: BuilderStateReason;
 }
-/**
- * `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. */
     generation: number;
@@ -154,3 +132,18 @@ export type BuilderEvent = {
     data: BuilderMetrics;
 };
 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[]>;
+}

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