akanjs 3.0.0-beta.8 → 3.0.0

package/types/fetch/requestStorage.d.ts

@@ -40,15 +40,12 @@ declare global {
 }
 export declare const requestStorage: RequestStorage | null;
 export declare function createRequestStore(request: Request, policy?: Partial<Omit<AkanRequestPolicy, "tags">>): AkanRequestStore;
-/** Stores theme preference on the active request when server rendering. */
 export declare function setRequestTheme(theme: AkanTheme | undefined): void;
 export declare function getRequestTheme(): AkanTheme | undefined;
 export declare function setRequestFrameState(frameState: unknown): void;
 export declare function getRequestFrameState<FrameState = unknown>(): FrameState | undefined;
 export declare function pushRequestFallback(storeOrRequest: Request | AkanRequestStore): () => void;
-/** Returns the active server request store from AsyncLocalStorage or the fallback stack. */
 export declare function getRequestStore(): AkanRequestStore | undefined;
-/** Returns the active server request from AsyncLocalStorage or the fallback stack. */
 export declare function getRequest(options?: {
     trackDynamic?: boolean;
 }): Request | undefined;
@@ -61,25 +58,15 @@ export declare function updateRequestPolicy(patch: Partial<Omit<AkanRequestPolic
 /** @internal Route cache tag collection is reserved for framework-owned cache policy experiments. */
 export declare function cacheTag(...tags: string[]): AkanRequestPolicy | undefined;
 export declare function getRequestDynamicUsage(): AkanDynamicUsage | undefined;
-/**
- * Deduplicates a promise-producing query within the active request, and says whether this caller is the one
- * that started it.
- *
- * `owned` is what lets the caller skip copying the response. The copy exists because one response object is
- * handed to every caller in the request and a parsed model can hold references into it, so a second caller must
- * not be given the same graph — but a query asked for once (which is nearly all of them: the key carries the
- * URL and the auth headers) has no second caller to protect, and copying for it is a whole JSON round-trip
- * spent on nothing.
- */
+/** Deduplicates within the active request; `owned` means this caller started it and may skip the defensive copy. */
 export declare function claimRequestQuery<T>(key: string, factory: () => Promise<T>): {
     value: Promise<T>;
     owned: boolean;
 };
 /** Appends to the active request's query log; outside a request there is nothing to read it, so nothing is kept. */
 export declare function recordRequestQuery(record: RequestQueryRecord): void;
-/** Deduplicates a promise-producing query within the active request. */
 export declare function memoizeRequestQuery<T>(key: string, factory: () => Promise<T>): Promise<T>;
-/** Returns current request headers as a Map, or an empty Map outside a request. */
+/** An empty Map outside a request. */
 export declare function headers(options?: {
     trackDynamic?: boolean;
 }): Map<string, string>;
@@ -90,7 +77,7 @@ export interface CookieEntry {
     value: string;
 }
 export declare function parseCookieHeader(cookieHeader: string): Map<string, CookieEntry>;
-/** Returns parsed cookies from the current request, or an empty Map outside a request. */
+/** An empty Map outside a request. */
 export declare function cookies(options?: {
     trackDynamic?: boolean;
 }): Map<string, CookieEntry>;

package/types/fetch/types.d.ts

@@ -1,7 +1,6 @@
 import { type Environment, type SLICE_META } from "akanjs/base";
 import type { DatabaseSignal } from "akanjs/signal";
 import type { SliceMeta } from "./fetchType/appliedReturn.type";
-/** Account data made available to services for the current app/environment. */
 export type Account<AddData = unknown> = {
     appName: string;
     environment: Environment;

package/types/index.d.ts

@@ -1,12 +1,12 @@
+import type { AkanNativeConfig } from "./vendor/@akanjs/native/packages/cli/src/config.d.ts";
 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,21 +17,39 @@ 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[];
 }
+/** `${process.platform}-${process.arch}` of the computer a desktop app is built on, which is the one it runs on. */
+export declare const binPlatforms: readonly ["darwin-arm64", "darwin-x64", "linux-arm64", "linux-x64", "win32-arm64", "win32-x64"];
+export type BinPlatform = (typeof binPlatforms)[number];
+/** Downloaded when the desktop app is built; the file must hash to `sha256`, so plain http is as safe as https. */
+export interface AkanBinUrlSource {
+    url: string;
+    sha256: string;
+    /** The executable inside the archive `url` names (.zip, .tar.gz, .tgz, .tar.xz, .tar.bz2, .tar). */
+    file?: string;
+}
+/** A file on the building computer, relative to the `akan.config.ts` that declares it. */
+export interface AkanBinPathSource {
+    path: string;
+    /** The executable inside the archive `path` names. */
+    file?: string;
+}
+export type AkanBinSource = AkanBinUrlSource | AkanBinPathSource;
+/**
+ * Executables a desktop app carries, by the name its code spawns and then by platform. Their folder comes first on
+ * the app's PATH, so the carried server's `spawn("ffmpeg")` runs the carried file; a native plugin finds it in
+ * `ctx.binDir`.
+ */
+export type AkanBinConfig = Record<string, {
+    [platform in BinPlatform]?: AkanBinSource;
+}>;
 export interface AkanRouteDomains {
     main?: string[];
     develop?: string[];
@@ -42,95 +60,204 @@ 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 the native apps ship 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. */
 export type LibAssetsConfig = Pick<AkanAssetsConfig, "keepFonts">;
 export type DatabaseMode = "single" | "multiple" | "cluster";
-export type MobileEnv = "local" | "debug" | "develop" | "main";
-export type MobilePermission = "camera" | "contacts" | "location" | "push" | "speech";
-export interface AkanMobileTargetAssets {
-    icon?: string;
-    splash?: string;
-}
-export interface AkanMobileTargetDeepLinks {
+export type NativeEnv = "local" | "debug" | "develop" | "main";
+export type NativePermission = "camera" | "contacts" | "location" | "push" | "speech";
+export type AkanNativeValue = string | number | boolean | AkanNativeValue[] | {
+    [key: string]: AkanNativeValue;
+};
+/**
+ * One bundle id, or one per platform, for an app whose store listings already carry different ids. A platform without
+ * its own takes `default`.
+ */
+export type AkanNativeAppId = string | {
+    default?: string;
+    ios?: string;
+    android?: string;
+    macos?: string;
+    windows?: string;
+    linux?: string;
+};
+export interface AkanNativeDeepLinks {
+    /** Custom URL schemes the app opens (`board://…`). */
     schemes?: string[];
+    /** Hosts whose https links open the app: universal links (iOS, `ios.teamId`) and app links (Android). */
     domains?: string[];
-    ios?: {
-        teamId?: string;
-    };
-    android?: {
-        sha256CertFingerprints?: string[];
-    };
 }
-export interface AkanMobileTargetFiles {
-    ios?: Record<string, string>;
-    android?: Record<string, string>;
+/**
+ * Where an installed app looks for newer releases of itself (the native runtime's updates plugin): the whole app on a
+ * desktop, the web bundle on a phone. `akan publish-update` writes and signs a release with a key on this machine;
+ * `akan pack-update` writes an unsigned phone bundle for whoever holds the key to sign.
+ */
+export interface AkanNativeUpdatesConfig {
+    /**
+     * A static base URL, https in a release build: `<url>/<os>-<arch>/<channel>.json` (desktop) or `<url>/<platform>/…`
+     * (a phone's web bundle).
+     */
+    url: string;
+    /** The update key's public half, the raw 32-byte Ed25519 key in base64 (`akan update-keygen` prints it). */
+    publicKey: string;
+    /**
+     * The manifest the app follows, e.g. a "pilot" target's "pilot". Default: the backend env the app is built for
+     * (`main`, `develop`, `debug`, `local`).
+     */
+    channel?: string;
+    /** How long a newly applied release has to call notifyReady() before it is rolled back, ms. Default 10000. */
+    readyTimeout?: number;
 }
-export interface AkanCapacitorLikeConfig {
-    plugins?: Record<string, unknown>;
-    android?: Record<string, unknown>;
-    ios?: Record<string, unknown>;
-    [key: string]: unknown;
+export interface AkanNativeIosConfig {
+    /** Where the iOS app starts, over the section's `indexPath`. */
+    indexPath?: string;
+    /** The Apple team id: the universal links of `deepLinks.domains` (apple-app-site-association). */
+    teamId?: string;
+    infoPlist?: Record<string, AkanNativeValue>;
+    entitlements?: Record<string, AkanNativeValue>;
+    /** The app's part of the iOS privacy manifest (PrivacyInfo.xcprivacy), which an App Store upload requires. */
+    privacy?: AkanNativeConfig["privacy"];
+    /** Files copied into the app bundle, keyed by their path there; the value is the source, relative to the app folder. */
+    files?: Record<string, string>;
+}
+export interface AkanNativeAndroidConfig {
+    /** Where the Android app starts, over the section's `indexPath`. */
+    indexPath?: string;
+    /** The signing certificates' SHA-256 fingerprints: the app links of `deepLinks.domains` (assetlinks.json). */
+    sha256CertFingerprints?: string[];
+    /** The Firebase project's google-services.json, relative to the app folder, for FCM push. */
+    googleServices?: string;
+    /** The notification channel, status bar icon (relative to the app folder) and accent color of pushes. */
+    push?: NonNullable<AkanNativeConfig["push"]>["android"];
+    /** Media plays with sound without a tap first, as it does on iOS and the desktop: a signage screen. */
+    autoplay?: boolean;
+    /** XML at the `<manifest>` level; `${applicationId}` is replaced. */
+    manifest?: string[];
+    /** XML inside `<application>`. */
+    application?: string[];
+    /** XML inside the app's activity. */
+    activity?: string[];
+    /** Files copied into the app, keyed `res/<type>/<file>` or `assets/<path>`; the value is the source. */
+    files?: Record<string, string>;
+}
+export interface AkanNativeDesktopServerConfig {
+    /**
+     * Packages the image installs and the desktop app's server goes without, along with what only they pull in: an
+     * addon that needs the image's system (a ROS install), code only a process the desktop app never starts loads.
+     * The server's own bundle must not import them. The image is unchanged.
+     */
+    omit?: string[];
 }
-export interface AkanMobileTargetConfig extends AkanCapacitorLikeConfig {
-    name: string;
+export interface AkanNativeDesktopConfig {
+    /** Where the desktop app starts, over the section's `indexPath`. */
+    indexPath?: string;
+    /**
+     * The desktop app carries the app's server (API only, database mode single, on loopback) and its pages call
+     * nothing else: `true`, or `{ omit }` to carry it without some of the image's packages. `build-desktop`,
+     * `start-desktop` and `publish-update` all read it, and an installed app refuses a release that carries a server
+     * when it has none, or none when it has one.
+     */
+    server?: boolean | AkanNativeDesktopServerConfig;
+    /**
+     * `"reload"`: a window whose page's process ends (a crash, a hang) loads it again every time, waiting
+     * longer after each end in a row, and the app relaunches when the webview's browser process ends — for an
+     * app nobody attends. `"errorPage"` (default): one reload, then an error page, and a quit for the browser.
+     */
+    recovery?: "errorPage" | "reload";
+    /** The main window from its first frame: borderless fullscreen, and no taskbar button (Windows, Linux). */
+    window?: {
+        fullscreen?: boolean;
+        skipTaskbar?: boolean;
+    };
+    /**
+     * Windows: `"auto"` answers getDisplayMedia() with the first screen at once, no picker or gesture — remote
+     * support on an unattended screen; it covers every media request, so not for an app that asks for a camera.
+     */
+    screenCapture?: "picker" | "auto";
+    /**
+     * macOS: entitlements of the app's executable beyond what it gets by itself — the JIT's under the hardened runtime and
+     * the camera's or microphone's when a usage text asks for it — e.g. `com.apple.security.cs.disable-library-validation`
+     * for a native addon signed by another team. Read when the app is signed with a team (a Developer ID).
+     */
+    entitlements?: Record<string, AkanNativeValue>;
+}
+/**
+ * What a native app (iOS, Android, desktop) is: the app's `native` section and each of its targets have this shape. A
+ * target takes the section and overrides it field by field: objects merge key by key, and any other value — a list
+ * included — replaces the section's.
+ */
+export interface AkanNativeSettings {
+    /** The client the app opens, a basePath the routes declare; an app without basePaths leaves it out. */
     basePath?: string;
+    /**
+     * Where the app starts, and falls back to for a deep link's stack and a back with no history. Default `/`. A platform
+     * section's own `indexPath` (`desktop.indexPath`) wins on that platform.
+     */
     indexPath?: string;
+    /** Default: the app's folder name. */
+    appName?: string;
+    /** Default: one made from the repository's and the app's names. */
+    appId?: AkanNativeAppId;
+    /** Executables, archives and the Swift module; letters, digits, `.`, `_` and `-`. Default: the app's folder name. */
+    fileName?: string;
+    /** Default `0.0.1`. */
+    version?: string;
+    /** Default 1. */
+    buildNum?: number;
+    /** A square PNG, relative to the app folder, or it with the color behind its transparent areas. */
+    icon?: string | {
+        image: string;
+        backgroundColor?: string;
+    };
+    /** A PNG shown centered at launch, or the launch screen's color, image and when it hides. */
+    splash?: string | NonNullable<AkanNativeConfig["splash"]>;
+    permissions?: NativePermission[];
+    /** Native runtime plugins beyond the ones the permissions bring: a builtin id (`"iap"`) or a folder, from the app's. */
+    plugins?: string[];
+    deepLinks?: AkanNativeDeepLinks;
+    updates?: Partial<AkanNativeUpdatesConfig>;
+    ios?: AkanNativeIosConfig;
+    android?: AkanNativeAndroidConfig;
+    desktop?: AkanNativeDesktopConfig;
+}
+/** `native` in akan.config.ts. Without `targets` the app has one target, named `default`. */
+export interface AkanNativeAppConfig extends AkanNativeSettings {
+    targets?: Record<string, AkanNativeSettings>;
+}
+/** One target of the app, its fields over the app's `native` section and the defaults. */
+export interface AkanNativeTarget extends Omit<AkanNativeSettings, "appName" | "appId" | "version" | "buildNum" | "updates"> {
+    name: string;
     appName: string;
-    appId: string;
+    appId: AkanNativeAppId;
     version: string;
     buildNum: number;
-    assets?: AkanMobileTargetAssets;
-    permissions?: MobilePermission[];
-    deepLinks?: AkanMobileTargetDeepLinks;
-    files?: AkanMobileTargetFiles;
+    updates?: AkanNativeUpdatesConfig;
 }
-export interface AkanMobileConfig extends AkanCapacitorLikeConfig {
+export interface AkanNativeAppResult {
     appName: string;
-    appId: string;
+    appId: AkanNativeAppId;
+    fileName?: string;
     version: string;
     buildNum: number;
-    targets: Record<string, AkanMobileTargetConfig>;
-}
-export interface PluginRuntimeContext {
-    readonly appName: string;
-    readonly mobile: AkanMobileConfig;
-    /** True when any mobile target declares the given permission. */
-    hasMobilePermission(permission: MobilePermission): boolean;
+    targets: Record<string, AkanNativeTarget>;
 }
 export interface AkanScanInfo {
     /** Transitive lib dependencies of the app (or direct deps of a lib). */
@@ -166,48 +293,34 @@ 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>;
     /** Resolves `env/env.client.ts` and returns its exported `env`, or null when absent/invalid. */
     readEnvClient(): Promise<Record<string, unknown> | null>;
 }
-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";
-    readonly env: MobileEnv;
-    /** Set NS-prefixed usage descriptions in the iOS Info.plist (Debug + Release). */
-    setIosUsageDescriptions(descriptions: Record<string, string>): Promise<void>;
-    /** Merge raw key/values into the iOS Info.plist (Debug + Release). */
-    updateIosInfoPlist(values: Record<string, unknown>): Promise<void>;
-    /** Contribute entries to the iOS entitlements file (merged, then written once per prepare). */
-    addIosEntitlements(entitlements: Record<string, string | string[]>): void;
-    /** Transform `ios/App/App/AppDelegate.swift` in place (no-op when the file is absent). */
-    editIosAppDelegate(transform: (content: string) => string): Promise<void>;
-    /** Add `uses-permission` entries to the Android manifest (without the `android.permission.` prefix). */
-    addAndroidPermissions(permissions: string[]): void;
-    /** Add `uses-feature` entries to the Android manifest. */
-    addAndroidFeatures(features: string[]): void;
-}
-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>;
-}
+/** What a plugin adds to a native app whose target asks for its permission; the native build merges every one. */
+export interface AkanPluginNativeConfig {
+    permission: NativePermission;
+    /** Native runtime plugins, by builtin id (`"camera"`). */
+    plugins?: string[];
+    /** iOS usage texts by description name (`cameraUsageDescription`); `$(PRODUCT_NAME)` becomes the app name. */
+    usageDescriptions?: Record<string, string>;
+    infoPlist?: Record<string, AkanNativeValue>;
+    entitlements?: Record<string, AkanNativeValue>;
+    /** `uses-permission` names, without the `android.permission.` prefix. */
+    androidPermissions?: string[];
+    /** `uses-feature` names, declared as not required. */
+    androidFeatures?: string[];
+}
+/** 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;
+    native?: AkanPluginNativeConfig;
     /** Build-time asset generation (e.g. `public/firebase-messaging-sw.js`). */
     syncAssets?: (ctx: AkanSyncContext) => Promise<void>;
 }
@@ -217,37 +330,48 @@ 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[];
+    /** Dependencies whose install scripts `bun install --production` runs, in the image and in a desktop app's server. */
+    trustedDependencies: string[];
+    /** Every desktop build, run and dev session carries these, server or not; the image installs through `docker`. */
+    bin: AkanBinConfig;
     barrelImports: string[];
     optimizeImports: string[];
     images: AkanImageConfig;
     i18n: AkanI18nConfig;
     publicEnv: string[];
-    mobile: AkanMobileConfig;
+    native: AkanNativeAppResult;
     secrets: string[];
-    /** How the build trims the `public/` copy it ships. */
     assets: AkanAssetsConfig;
 }
 export interface LibConfigResult {
     externalLibs: string[];
+    trustedDependencies: string[];
+    /** Carried by the desktop app of every app that depends on this lib; an app's own entry of the same name wins. */
+    bin: AkanBinConfig;
     /** Image steps every app that mounts this lib inherits, unless that app declares a whole Dockerfile. */
     docker: LibDockerConfig;
     /** Which of this lib's own public fonts every app that mounts it must keep. */
@@ -264,12 +388,15 @@ export interface LibConfigContext {
     readonly name: string;
     readonly type: "lib";
 }
-export type AppConfigInput = Omit<DeepPartial<AppConfigResult>, "docker" | "web"> & {
+export type AppConfigInput = Omit<DeepPartial<AppConfigResult>, "docker" | "web" | "bin" | "native"> & {
     docker?: DockerOption;
     web?: AkanWebOption;
+    bin?: AkanBinConfig;
+    native?: AkanNativeAppConfig;
     plugins?: AkanPlugin[];
 };
-export type LibConfigInput = DeepPartial<LibConfigResult> & {
+export type LibConfigInput = Omit<DeepPartial<LibConfigResult>, "bin"> & {
+    bin?: AkanBinConfig;
     plugins?: AkanPlugin[];
 };
 export interface SubspaceDeclaration {
@@ -278,29 +405,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 cloud workspace this subspace deploys from — its own `AKAN_WORKSPACE_ID`, not this workspace's.
-     * `akan subspace upload-env` is the only thing that reads it.
-     */
+    /** 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[];
 }
@@ -360,10 +472,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/native/desktop.d.ts

@@ -0,0 +1,3 @@
+export { AkanNativeError, mimeFor } from "../vendor/@akanjs/native/packages/core/src/index.d.ts";
+export type { DesktopContext, DesktopPlugin, NativeEvent } from "../vendor/@akanjs/native/packages/desktop/src/plugin.d.ts";
+export { createPageVeto, defineDesktopPlugin, externalOpenAllowed } from "../vendor/@akanjs/native/packages/desktop/src/plugin.d.ts";

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,5 @@
-/** What `Server.requestIP` reports for the socket this hop accepted. */
+/** The Host every request the gateway hands a replica carries; a browser never sends it to a replica's port. */
+export declare const AKAN_CHILD_HOST = "akan-child";
 export interface ProxyClientPeer {
     address: string;
     port: number;