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

package/types/base/baseEnv.d.ts

@@ -12,8 +12,6 @@ export type BackendEnv = {
     hostname?: string | null;
     port?: number;
     database?: {
-        mode?: DatabaseMode;
-        driver?: "sqlite" | "libsql" | "postgres";
         sqlite?: {
             filePath?: string;
             journalMode?: string;
@@ -34,6 +32,7 @@ export type BackendEnv = {
             database?: string;
             user?: string;
             password?: string;
+            insightUrl?: string;
         };
     };
     solid?: {
@@ -44,6 +43,7 @@ export type BackendEnv = {
         cleanupIntervalMs?: number;
         queuePollIntervalMs?: number;
         queueLeaseMs?: number;
+        queueFailedRetentionMs?: number;
     };
     onCleanup?: () => Promise<void>;
 };
@@ -64,19 +64,16 @@ export type ClientEnv = BaseEnv & {
     serverWsProtocol: "ws:" | "wss:";
     serverWsUri: string;
 };
-/** Leading slash, no trailing slash. A blank value — or a bare `/`, which would swallow every page route — is no prefix at all and falls through to the next source. */
+/** Leading slash, no trailing slash; a blank value or a bare `/` (it would swallow every page route) is no prefix. */
 export declare const normalizeRoutePrefix: (value: string | undefined | null) => string | undefined;
 /**
- * Three sources, narrowest first. The global is what a server-rendered page's bootstrap script writes, so the
- * browser follows the process that rendered it. `AKAN_API_PREFIX` is deliberately outside the `AKAN_PUBLIC_*`
- * namespace: only that namespace is inlined into client bundles at build time, so a name inside it could never
- * act as a runtime override. `AKAN_PUBLIC_API_PREFIX` is the build-time default, and the only one a prebuilt CSR
- * or mobile bundle can read. Written out rather than looked up by key — a computed `process.env[...]` is opaque
- * to the bundler's define pass, and the public value would stop being inlined.
+ * Narrowest first: the SSR bootstrap global, then `AKAN_API_PREFIX` (outside `AKAN_PUBLIC_*`, which is inlined at build
+ * time, so it can override at runtime), then the build-time default. Written out: a computed `process.env[...]` escapes
+ * the bundler's define pass.
  */
 export declare const getApiPrefix: () => string;
 export declare const getWsPrefix: () => string;
 /** `AkanApp` rewrites `process.env` for the replica it runs in-process, after this module may already have cached. */
 export declare const resetEnvCache: () => void;
-/** Reads and caches Akan runtime environment values from process/browser environment settings. */
+/** Cached after the first call. */
 export declare const getEnv: () => ClientEnv;

package/types/base/databaseModes.d.ts

@@ -0,0 +1,28 @@
+import type { DatabaseMode } from "./baseEnv.d.ts";
+export interface DatabaseModeRequest {
+    /** `AKAN_DATABASE_MODE`: the mode a deployment names. */
+    requested: string | undefined;
+    /** `AKAN_DATABASE_MODES`: what the build carries drivers for, first one the default. Unset allows any. */
+    declared: string | undefined;
+    /** A developer machine, which may leave the mode unnamed when the build carries several. */
+    local: boolean;
+}
+/** Shared by the CLI and the server. */
+export declare class DatabaseModes {
+    #private;
+    static readonly all: readonly ["single", "multiple", "cluster"];
+    /** Packages a mode imports at runtime. A build carries them for every mode the app declares. */
+    static readonly drivers: {
+        [mode in DatabaseMode]: readonly string[];
+    };
+    static describe(mode: DatabaseMode): string;
+    static parse(value: string, source: string): DatabaseMode;
+    static parseList(value: string, source: string): DatabaseMode[];
+    /**
+     * Throws when a build carrying several modes names none: the fallback would be a SQLite file in each container,
+     * which a cluster deployment would discover only once its instances disagreed.
+     */
+    static resolve({ requested, declared, local }: DatabaseModeRequest): DatabaseMode;
+    /** `resolve` for readers that cannot fail a boot; the boot itself resolves again and reports the reason. */
+    static settle(request: DatabaseModeRequest): DatabaseMode | undefined;
+}

package/types/base/index.d.ts

@@ -1,5 +1,6 @@
 export * from "./base.d.ts";
 export * from "./baseEnv.d.ts";
+export * from "./databaseModes.d.ts";
 export * from "./primitiveRegistry.d.ts";
 export * from "./symbols.d.ts";
 export * from "./types.d.ts";

package/types/base/primitiveRegistry.d.ts

@@ -2,22 +2,31 @@ import dayjsLib, { type Dayjs } from "dayjs";
 import { CLIENT_VALUE, DEFAULT_VALUE, EXAMPLE_VALUE, PURIFIED_VALUE, SERVER_VALUE } from "./symbols.d.ts";
 import type { Cls } from "./types.d.ts";
 export type { Dayjs };
-/** Shared dayjs factory re-export used by Akan documents, services, stores, and UI. */
 export declare const dayjs: typeof dayjsLib;
-/** Registry that maps Akan primitive scalar names to their runtime scalar classes. */
 export declare class PrimitiveRegistry {
     #private;
-    static register(scalar: typeof PrimitiveScalar, { overwrite }?: {
-        overwrite?: boolean | undefined;
-    }): void;
+    static register(scalar: typeof PrimitiveScalar): void;
     static get(name: string): typeof PrimitiveScalar;
     static getName(scalar: typeof PrimitiveScalar): string;
     static has(modelRef: Cls): boolean;
     static hasName(name: string): boolean;
     static getNames(): string[];
     static getAll(): (typeof PrimitiveScalar)[];
+    /** The agent face `modelRef` declares, or null for anything that is not a registered primitive declaring one. */
+    static agentOf(modelRef: unknown): PrimitiveAgentFace | null;
+}
+export interface PrimitiveJsonSchema {
+    [key: string]: unknown;
+}
+/**
+ * How an agent sees a primitive whose stored shape is not the one a model should read: `schema` is its published shape
+ * and `read` maps a stored or wire value into it. No `write`: every input already runs through `parseValue`.
+ */
+export interface PrimitiveAgentFace<Value = unknown> {
+    schema: PrimitiveJsonSchema;
+    read(value: Value): unknown;
 }
-export type PrimitiveValue = string | number | boolean | Dayjs | Date | Uint8Array | null | undefined;
+export type PrimitiveValue = string | number | boolean | Dayjs | Date | Uint8Array | object | null | undefined;
 export declare class PrimitiveScalar {
     static refName: string;
     static [SERVER_VALUE]: unknown;
@@ -25,6 +34,10 @@ export declare class PrimitiveScalar {
     static [DEFAULT_VALUE]: unknown;
     static [PURIFIED_VALUE]: unknown;
     static [EXAMPLE_VALUE]: unknown;
+    /** The wire shape, for a primitive the built-in schema table cannot know. Absent, it is published as a string. */
+    static jsonSchema?: PrimitiveJsonSchema;
+    /** Absent, an agent sees the wire shape. */
+    static agent?: PrimitiveAgentFace;
     static validate(value: PrimitiveValue): boolean;
     static parseValue(value: PrimitiveValue): PrimitiveValue;
     static serializeValue(value: PrimitiveValue): PrimitiveValue;
@@ -38,7 +51,7 @@ export declare class PrimitiveScalar {
         optional?: boolean;
     }): void;
 }
-/** Integer primitive scalar. Accepts safe integer numbers after parsing. */
+/** Safe integers only. */
 export declare class Int extends PrimitiveScalar {
     static refName: "Int";
     static [SERVER_VALUE]: number;
@@ -50,7 +63,7 @@ export declare class Int extends PrimitiveScalar {
     static parseValue(input: string | number): number;
     static serializeValue(value: number): number;
 }
-/** Floating point primitive scalar. Accepts finite numbers after parsing. */
+/** Finite numbers only. */
 export declare class Float extends PrimitiveScalar {
     static refName: "Float";
     static [SERVER_VALUE]: number;
@@ -62,7 +75,7 @@ export declare class Float extends PrimitiveScalar {
     static parseValue(input: string | number): number;
     static serializeValue(value: number): number;
 }
-/** 24-character hexadecimal id primitive used by Akan document and signal models. */
+/** 24 hexadecimal characters. */
 export declare class ID extends PrimitiveScalar {
     static refName: "ID";
     static [SERVER_VALUE]: string;
@@ -77,7 +90,7 @@ export declare class ID extends PrimitiveScalar {
         optional?: boolean;
     }): void;
 }
-/** Open object primitive for intentionally flexible payloads or metadata blobs. */
+/** An intentionally open payload. */
 export declare class Any extends PrimitiveScalar {
     static refName: "Any";
     static [DEFAULT_VALUE]: object | null;

package/types/base/symbols.d.ts

@@ -13,7 +13,7 @@ export declare const STATE_META: unique symbol;
 export declare const STATE_INIT_META: unique symbol;
 export declare const STATE_DERIVED_META: unique symbol;
 export declare const ACTION_META: unique symbol;
-/** Which module declared each action. See `ActionOwner`. */
+/** Which module declared each action. */
 export declare const ACTION_OWNER_META: unique symbol;
 /** What a dispatcher does, carried on the function so a component handed one can annotate the DOM with it. */
 export declare const ACTION_TAG: unique symbol;

package/types/client/cn.d.ts

@@ -1,17 +1,7 @@
 import { type ClassNameValue } from "tailwind-merge";
-/**
- * Akan's semantic color tokens beyond tailwind-merge's built-in Tailwind palette.
- * Registering them under `theme.color` teaches tailwind-merge that `bg-*`/`text-*`/
- * `border-*`/… built from these names belong to the same conflict group, so
- * `cn("bg-primary", "bg-open")` correctly resolves to `"bg-open"` instead of keeping both.
- */
+/** Registered with tailwind-merge so `cn("bg-primary", "bg-open")` resolves to `"bg-open"` instead of keeping both. */
 export declare const colorTokens: string[];
-/**
- * Akan's semantic radius tokens (`--radius-box` / `--radius-field` in ui/styles.css). Without them
- * `cn("rounded-field", "rounded-full")` keeps both classes and stylesheet order decides the winner.
- */
+/** `--radius-box` / `--radius-field`; unregistered, `cn("rounded-field", "rounded-full")` would keep both. */
 export declare const radiusTokens: string[];
-/** The one class-combining function: joins strings/arrays/conditional parts (`cond && "x"`) and
- *  resolves Tailwind conflicts with a shared tailwind-merge instance that knows Akan's semantic
- *  color tokens. clsx-style object syntax (`{ x: cond }`) is not supported — write `cond && "x"`. */
+/** Joins class parts and resolves Tailwind conflicts; object syntax (`{ x: cond }`) is unsupported — write `cond && "x"`. */
 export declare const cn: (...inputs: ClassNameValue[]) => string;

package/types/client/cookie.d.ts

@@ -10,11 +10,7 @@ export declare const cookies: () => Map<string, {
     value: string;
 }>;
 export declare const setCookie: (key: string, value: string, options?: CookieOptions) => void;
-/**
- * Reads through `cookies()` on both sides, which is the only way the two agree: a hand-rolled
- * `split("=")[1]` truncates a value at its first `=` (base64 padding) and never decodes the `j:` form the
- * server branch does. Capacitor's own docs say to read `document.cookie`, and `cookies()` does.
- */
+/** Reads through `cookies()` on both sides: a hand-rolled `split("=")` cuts base64 padding and skips the `j:` form. */
 export declare const getCookie: (key: string) => string | undefined;
 export declare const removeCookie: (key: string, options?: {
     path: string;
@@ -22,17 +18,14 @@ export declare const removeCookie: (key: string, options?: {
 export declare const headers: () => Map<string, string>;
 export declare const getHeader: (key: string) => string | undefined;
 export { authTokenKey };
-/** The auth token this app holds in the cookie jar, under the app-scoped key or a legacy global one. */
+/** The auth token this app holds: on a CSR client the one `fetch` sends first, since a native shell's page keeps no
+ * session cookie; then the cookie jar, under the app-scoped key or a legacy global one. */
 export declare const getAuthToken: () => string | undefined;
-/** The auth token this app holds in client storage — localStorage under SSR, Capacitor Preferences on CSR. */
+/** The auth token this app holds in client storage — the OS credential store in a native app, localStorage elsewhere. */
 export declare const getStoredAuthToken: () => Promise<string | undefined>;
-/**
- * Decodes the current JWT into account data when it belongs to this app/environment.
- *
- * The two credentials read here are exactly the two the server honours — the app-scoped auth cookie and
- * `Authorization: Bearer` (`AccountMiddleware`). It used to fall back to a bare `jwt` *header*, which nothing
- * sends and no guard accepts, so a request carrying one read as signed in here and anonymous at the endpoint.
- */
+/** The current JWT's account when minted for this app and environment. Reads only the two credentials the server
+ * honours — the app-scoped auth cookie (a CSR client's bearer token) and `Authorization: Bearer` — so the two never
+ * disagree on who is signed in. */
 export declare const getAccount: <AddData = unknown>() => Account<AddData>;
 export interface GetOption {
     unauthorize: string;
@@ -40,7 +33,7 @@ export interface GetOption {
 interface SetAuthOption {
     jwt: string;
 }
-/** Sets the active auth token on fetch, cookie storage, and client storage. */
+/** Sets the active auth token on fetch, the cookie jar (except on a CSR client), and client storage. */
 export declare const setAuth: ({ jwt }: SetAuthOption) => void;
 interface InitAuthOption {
     jwt?: string;

package/types/client/csrTypes.d.ts

@@ -11,20 +11,9 @@ export type PageSafeAreaConfig = boolean | "top" | "bottom" | {
     bottom?: boolean;
     android?: "auto" | "edge-to-edge" | "none";
 };
-/**
- * Server-render strategy for the initial full-document SSR pass.
- * - `"stream"` (default): flush the shell — including any `Loading` Suspense
- *   fallback — as soon as it is ready, then stream the resolved page. Redirects
- *   decided in the shell still become real HTTP redirects; redirects thrown
- *   inside suspended content degrade to soft (client) redirects.
- * - `"block"`: buffer the whole document until every Suspense boundary resolves
- *   before sending a byte. The `Loading` fallback never reaches the browser, but
- *   a non-redirect error thrown in slow content can still yield a clean error
- *   page. Use only for routes that need that guarantee and do not care about SEO
- *   or first-paint of the fallback.
- */
+/** `"stream"` flushes the shell (`Loading` included) then streams; a redirect in suspended content becomes a client one.
+ * `"block"` buffers the whole document, so an error in slow content can still render a clean error page. */
 export type SsrRenderMode = "stream" | "block";
-/** Per-page CSR configuration for transition, safe-area, and gesture behavior. */
 export interface PageConfig {
     transition?: TransitionType;
     safeArea?: PageSafeAreaConfig;
@@ -36,20 +25,12 @@ export interface PageConfig {
     cache?: boolean;
     /** Initial full-document SSR strategy. Defaults to `"stream"`. */
     ssr?: SsrRenderMode;
-    /**
-     * Opt in to guarded RSC page suffix commits when the page does not require
-     * head/metadata updates and the retained route chain head is invariant for
-     * sibling navigations under the same layout.
-     */
+    /** Opt-in suffix-only RSC commits, for a page needing no head update under a layout head its siblings share. */
     rscPatchHeadSafe?: boolean;
     topSafeAreaColor?: string;
     bottomSafeAreaColor?: string;
-    /**
-     * Keeps the route out of `akan build`. The route still serves under `akan start`, but nothing about it
-     * reaches production: no bundle, no manifest entry, no URL. On a `_layout`, every route under that
-     * directory is excluded with it. Must be written as a literal `true`/`false` — the build reads it from
-     * the source without evaluating the module.
-     */
+    /** Keeps the route (on a `_layout`, its whole directory) out of `akan build` while `akan start` serves it. Write a
+     * literal `true`/`false`: the build reads it off the source without evaluating the module. */
     devOnly?: boolean;
 }
 export interface CsrState {
@@ -74,7 +55,6 @@ export interface PageProps {
         [key: string]: string | string[];
     };
 }
-/** Props passed to Akan layout route modules. */
 export interface LayoutProps extends PageProps {
     children: ReactNode;
 }
@@ -106,7 +86,6 @@ export interface AkanHeadSnapshotV1 {
 }
 export interface ResolvedHead {
     node: Head | null | undefined;
-    hasExplicitLanguageAlternates: boolean;
     headSnapshot?: AkanHeadSnapshotV1;
 }
 export type ResolveHeadResult = Head | ResolvedHead | null | undefined;
@@ -122,8 +101,7 @@ export interface RouteRender {
     render: LayoutRender | PageRender;
     isAsync?: boolean;
     Loading?: LayoutLoadingRender | PageLoadingRender;
-    /** Loads the module and populates `Loading` without running `render`/`resolveHead`.
-     * Used by the patch (suffix) compose path, which never calls `resolveHead`. */
+    /** Loads the module and fills `Loading` without running `render`/`resolveHead` (the suffix compose path). */
     resolveLoading?: () => void | Promise<void>;
     NotFound?: LayoutNotFoundRender;
     Error?: LayoutErrorRender;
@@ -160,53 +138,24 @@ export interface WebAppManifest {
     screenshots?: WebAppManifestIcon[];
     [key: string]: unknown;
 }
-export interface AkanMetadata {
-    title?: string;
-    description?: string;
-    robots?: string;
-    openGraph?: {
-        title?: string;
-        description?: string;
-        type?: string;
-        url?: string;
-        siteName?: string;
-        images?: string | string[];
-    };
-    twitter?: {
-        card?: "summary" | "summary_large_image" | "app" | "player" | (string & {});
-        title?: string;
-        description?: string;
-        images?: string | string[];
-    };
-    alternates?: {
-        canonical?: string;
-        languages?: Record<string, string>;
-    };
-}
-export type GenerateMetadata = (props: PageProps) => PromiseOrObject<AkanMetadata | null | undefined>;
 export interface PageModule {
     default?: PageRender;
     pageConfig?: PageConfig;
     head?: Head;
-    metadata?: AkanMetadata;
     generateHead?: GenerateHead;
-    generateMetadata?: GenerateMetadata;
     Loading?: PageLoadingRender;
 }
 export interface LayoutModule {
     default?: LayoutRender;
     pageConfig?: PageConfig;
     head?: Head;
-    metadata?: AkanMetadata;
     generateHead?: GenerateHead;
-    generateMetadata?: GenerateMetadata;
     fonts?: ReactFont[];
     manifest?: WebAppManifest;
     theme?: string;
     reconnect?: boolean;
     wsConnect?: boolean;
     layoutStyle?: "mobile" | "web";
-    gaTrackingId?: string;
     Loading?: LayoutLoadingRender;
     NotFound?: LayoutNotFoundRender;
     Error?: LayoutErrorRender;

package/types/client/decorators.d.ts

@@ -2,6 +2,6 @@ interface ToastProps {
     root?: string;
     duration?: number;
 }
-/** Decorates async actions with loading/success/error toast messages from `msg`. */
+/** Toasts `<root>.<key>-loading` / `-success` around the method; an error is toasted and logged, not rethrown. */
 export declare const Toast: ({ root, duration }?: ToastProps) => (target: any, key: string, descriptor: PropertyDescriptor) => void;
 export {};

package/types/client/device.d.ts

@@ -1,20 +1,19 @@
 import type { RefObject } from "react";
-import type { CapacitorDeviceInfo, CapacitorHapticsModule, CapacitorKeyboardModule } from "./capacitor.d.ts";
-type DeviceInfo = CapacitorDeviceInfo;
-type Keyboard = CapacitorKeyboardModule["Keyboard"];
-type Haptics = CapacitorHapticsModule["Haptics"];
-type ImpactStyle = CapacitorHapticsModule["ImpactStyle"];
+import type { DeviceInfo } from "./native.d.ts";
+type NativeModule = typeof import("./native.d.ts");
+type NativeControls = Pick<NativeModule, "haptics" | "keyboard">;
+type DebugPayload = Record<string, unknown>;
+export declare function debugFrame(event: string, payload?: DebugPayload): void;
 interface DeviceInitOption {
     lang: string;
     info: DeviceInfo;
     topSafeArea: number;
     bottomSafeArea: number;
-    keyboard: Keyboard;
-    haptics: Haptics;
-    impactStyle: ImpactStyle;
+    /** The shell's keyboard and haptics; a page outside a native shell has neither. */
+    native: NativeControls | null;
 }
+export declare const isNativeTarget: () => boolean;
 export declare const isMobileDevice: () => boolean;
-/** Capacitor-aware device helper for platform info, safe areas, keyboard, haptics, and scroll state. */
 export declare class Device {
     #private;
     static instance: Device | null;
@@ -28,9 +27,8 @@ export declare class Device {
     topSafeArea: number;
     bottomSafeArea: number;
     isMobile: boolean;
-    constructor({ lang, info, topSafeArea, bottomSafeArea, keyboard, haptics, impactStyle }: DeviceInitOption);
+    constructor({ lang, info, topSafeArea, bottomSafeArea, native }: DeviceInitOption);
     setPageContentRef(pageContentRef: RefObject<HTMLDivElement | null>): void;
-    showKeyboard(): Promise<void>;
     hideKeyboard(): Promise<void>;
     listenKeyboardChanged(onKeyboardChanged: (height: number) => void): void;
     unlistenKeyboardChanged(): void;

package/types/client/index.d.ts

@@ -6,7 +6,6 @@ export * from "./csrTypes.d.ts";
 export * from "./decorators.d.ts";
 export * from "./device.d.ts";
 export * from "./frameConfig.d.ts";
-export * from "./frameDebug.d.ts";
 export * from "./locale.d.ts";
 export * from "./makePageProto.d.ts";
 export * from "./route.d.ts";

package/types/client/native.d.ts

@@ -0,0 +1,26 @@
+import { browser } from "../vendor/@akanjs/native/plugins/browser/src/index.d.ts";
+import { opener } from "../vendor/@akanjs/native/plugins/opener/src/index.d.ts";
+export { AkanNativeError, fileBlob, releaseFile } from "../vendor/@akanjs/native/packages/core/src/index.d.ts";
+export { app } from "../vendor/@akanjs/native/plugins/app/src/index.d.ts";
+export { appState } from "../vendor/@akanjs/native/plugins/app-state/src/index.d.ts";
+export type { Photo } from "../vendor/@akanjs/native/plugins/camera/src/index.d.ts";
+export type { DeviceInfo } from "../vendor/@akanjs/native/plugins/device/src/index.d.ts";
+export { device } from "../vendor/@akanjs/native/plugins/device/src/index.d.ts";
+export { dialog } from "../vendor/@akanjs/native/plugins/dialog/src/index.d.ts";
+export type { Position } from "../vendor/@akanjs/native/plugins/geolocation/src/index.d.ts";
+export { haptics } from "../vendor/@akanjs/native/plugins/haptics/src/index.d.ts";
+export type { IapProduct, IapTransaction } from "../vendor/@akanjs/native/plugins/iap/src/index.d.ts";
+export { keyboard } from "../vendor/@akanjs/native/plugins/keyboard/src/index.d.ts";
+export { preferences } from "../vendor/@akanjs/native/plugins/preferences/src/index.d.ts";
+export type { PushAction, PushMessage, PushPermissionState, PushToken as NativePushToken, } from "../vendor/@akanjs/native/plugins/push/src/index.d.ts";
+export { push } from "../vendor/@akanjs/native/plugins/push/src/index.d.ts";
+export { secureStorage } from "../vendor/@akanjs/native/plugins/secure-storage/src/index.d.ts";
+export { browser, opener };
+export declare const loadCamera: () => Promise<typeof import("../vendor/@akanjs/native/plugins/camera/src/index.d.ts")>;
+export declare const loadGeolocation: () => Promise<typeof import("../vendor/@akanjs/native/plugins/geolocation/src/index.d.ts")>;
+export declare const loadIap: () => Promise<typeof import("../vendor/@akanjs/native/plugins/iap/src/index.d.ts")>;
+/** Inside an iOS or Android shell of the native runtime; a mobile target opened in a browser is not. */
+export declare const isNativeApp: () => boolean;
+export declare const nativePlatform: () => "ios" | "android" | null;
+/** http(s) in the in-app browser, anything else (mailto:, tel:) in the app the system picks. */
+export declare const openExternalUrl: (url: string) => Promise<void>;

package/types/client/route/RootLayoutDefinition.d.ts

@@ -12,6 +12,5 @@ export declare class RootLayoutDefinition<Args extends RouteArgsShape = Record<n
     reconnect(on?: boolean): this;
     wsConnect(on?: boolean): this;
     layoutStyle(style: "mobile" | "web"): this;
-    gaTrackingId(id: string): this;
     protected extendModule(module: PageModule & LayoutModule): PageModule & LayoutModule;
 }

package/types/client/route/RouteDefinition.d.ts

@@ -1,21 +1,17 @@
 import { type PromiseOrObject } from "akanjs/base";
 import type { ReactNode } from "react";
-import type { AkanMetadata, Head, LayoutModule, PageConfig, PageModule } from "../csrTypes.d.ts";
+import type { Head, LayoutModule, PageConfig, PageModule } from "../csrTypes.d.ts";
 import { type RouteArgInfo, type RouteArgInput, type RouteBaseArgs } from "./routeArgs.d.ts";
 export type RouteArgsShape = Record<string, unknown>;
 export type RouteKind = "page" | "layout" | "rootLayout";
 /** Interned: a definition built inside the pages bundle must be recognised by a loader bundled apart from it. */
 export declare const routeDefinitionMarker: unique symbol;
 type HeadStage<Args> = Head | ((args: Args) => PromiseOrObject<Head | null | undefined>);
-type MetadataStage<Args> = AkanMetadata | ((args: Args) => PromiseOrObject<AkanMetadata | null | undefined>);
 export interface RouteArgResolveOption {
     /** A prompt's arguments are strings a person typed: a list is comma-separated and a bad value is refused. */
     strict?: boolean;
 }
-/**
- * What a route file declares in place of named exports. The chain is the only surface — the module exports the
- * finished definition and the loader turns it back into the module shape every renderer already reads.
- */
+/** What a route file declares in place of named exports; the loader turns it back into the module shape. */
 export declare abstract class RouteDefinition<Args extends RouteArgsShape = Record<never, never>, Extra extends object = Record<never, never>> {
     #private;
     readonly [routeDefinitionMarker] = true;
@@ -23,21 +19,13 @@ export declare abstract class RouteDefinition<Args extends RouteArgsShape = Reco
     readonly args: RouteArgInfo[];
     config(config: PageConfig): this;
     head(head: HeadStage<RouteBaseArgs & Args>): this;
-    metadata(metadata: MetadataStage<RouteBaseArgs & Args>): this;
     loading(render: (args: RouteBaseArgs & Args & Extra) => PromiseOrObject<ReactNode>): this;
     render(render: (args: RouteBaseArgs & Args & Extra) => PromiseOrObject<ReactNode>): this;
     get pageConfig(): PageConfig | undefined;
     protected declare(arg: RouteArgInfo): void;
-    /**
-     * Typed values out of the URL halves the router matched. A path value the declared type refuses is a URL that
-     * matched the pattern and nothing under it, so a page answers not-found; a search value that fails is dropped
-     * the way an absent one is. Under `strict` both are refused by name, which is what a prompt caller can act on.
-     */
+    /** A path value the type refuses answers not-found; a failing search value is dropped. `strict` refuses both by name. */
     resolveArgs(input: RouteArgInput, { strict }?: RouteArgResolveOption): Record<string, unknown>;
-    /**
-     * The `[x]` segments of the file's path against the `.param()` stages. A page must name every segment it sits
-     * under, so nothing reaches its body undeclared; a layout may name a subset, since most read none of them.
-     */
+    /** A page must declare every `[x]` segment it sits under with `.param()`; a layout may declare a subset. */
     assertPattern(pattern: string, key: string): void;
     /** The module shape every route loader reads, so a chain and a legacy module walk one path from here on. */
     toRouteModule(): PageModule & LayoutModule;

package/types/client/route/resolveRouteModule.d.ts

@@ -16,9 +16,5 @@ export interface ResolvedRouteModule {
     definition?: RouteDefinition;
 }
 export declare const isRouteDefinition: (value: unknown) => value is RouteDefinition;
-/**
- * Every loader — the RSC worker, the CSR boot, the generated root layout — reads route modules by their named
- * exports. A chain module has one export, so it is unfolded into that shape here and nothing downstream learns
- * which of the two it was reading; a legacy module passes through untouched.
- */
+/** Unfolds a chain module into the named-export shape every loader reads; a legacy module passes through untouched. */
 export declare const resolveRouteModule: (mod: RouteModuleSource, key: string, { kind, pattern }?: ResolveRouteModuleOption) => ResolvedRouteModule;

package/types/client/router.d.ts

@@ -8,8 +8,9 @@ export interface DeepLinkOptions extends RouteOptions {
     resetStack?: boolean;
 }
 export interface RouterInstance {
-    push: (href: string, routeOptions?: RouteOptions) => void;
-    replace: (href: string, routeOptions?: RouteOptions) => void;
+    /** May answer a promise that rejects when the route refused to move — see `Router.navigation`. */
+    push: (href: string, routeOptions?: RouteOptions) => void | Promise<void>;
+    replace: (href: string, routeOptions?: RouteOptions) => void | Promise<void>;
     back: (routeOptions?: RouteOptions) => void;
     refresh: () => void;
 }
@@ -52,8 +53,6 @@ export declare class AkanNotFoundError extends Error {
 export declare const normalizeDeepLinkHref: (href: string, origin?: string) => string;
 declare global {
     var __AKAN_ROUTER__: Router | undefined;
-    var __AKAN_DEV_SYNC_NAVIGATION__: ((href: string, kind: "push" | "replace" | "back" | "pop") => void) | undefined;
-    var __AKAN_DEV_SYNC_NAVIGATION_APPLYING__: boolean | undefined;
 }
 export declare const getPathInfo: (requestUrl: string, lang: string, prefix: string) => {
     path: string;
@@ -70,6 +69,9 @@ declare class Router {
     enterDeepLink(href: string, options?: DeepLinkOptions): boolean;
     push(href: string, routeOptions?: RouteOptions): never;
     replace(href: string, routeOptions?: RouteOptions): never;
+    /** The last `push`/`replace`; rejects when the route refused to move. A method, not a getter: through the `router`
+     * Proxy a getter would run with the Proxy as `this` and fail on the private field. */
+    navigation(): Promise<void>;
     canGoBack(): boolean;
     backOrFallback(fallbackHref?: string, routeOptions?: RouteOptions): never;
     back(routeOptions?: RouteOptions): never;
@@ -77,6 +79,8 @@ declare class Router {
     redirect(href: string, options?: RedirectOptions): never;
     notFound(): never;
     setLang(lang: string): never;
+    /** A pathname without its locale and base-path segments; unlike `getPath`, it needs no browser. */
+    routeOf(pathname: string): string;
     getPath(pathname?: string): string;
     getFullPath(withLang?: boolean): string;
     getPrefix(): string;

package/types/client/rscNavigation.d.ts

@@ -1,22 +1,25 @@
 declare global {
     var __AKAN_RSC_CLEAR_CACHE__: (() => void) | undefined;
     var __AKAN_RSC_IS_FROM_CACHE__: (() => boolean) | undefined;
+    var __AKAN_RSC_REFRESH__: ((options?: {
+        buildId?: number;
+    }) => Promise<void>) | undefined;
     var __AKAN_RSC_NAVIGATE__: ((href: string, options?: {
         replace?: boolean;
         scrollToTop?: boolean;
     }) => Promise<void>) | undefined;
+    var __AKAN_DEV_SYNC_NAVIGATION__: ((href: string, kind: "push" | "replace" | "back" | "pop") => void) | undefined;
+    var __AKAN_DEV_SYNC_NAVIGATION_APPLYING__: boolean | undefined;
+    var __AKAN_GET_SYNC_ROUTE_HREF__: ((href: string) => string) | undefined;
 }
 export declare const clearRscNavigationCache: () => void;
-/**
- * True when the page tree currently on screen was replayed from the RSC navigation cache instead of
- * fetched from the server. Data hydrated out of such a payload can be arbitrarily old, so anything
- * that must show current values should refetch.
- */
+/** True when the page on screen was replayed from the RSC navigation cache, so its hydrated data may be stale. */
 export declare const isRscNavigationFromCache: () => boolean;
 export declare const navigateRsc: (href: string, options?: {
     replace?: boolean;
     scrollToTop?: boolean;
 }) => Promise<void> | undefined;
+export declare const refreshRsc: () => Promise<void> | undefined;
 export declare const useRscNavigation: () => {
     clearCache: () => void;
     isFromCache: () => boolean;

package/types/client/sharedContext.d.ts

@@ -1,21 +1,4 @@
 import { type Context } from "react";
-/**
- * A React context interned on `globalThis`, which is how every context this framework owns must be made.
- *
- * An akan build does not give an app one copy of `akanjs`: it inlines each reachable module into every client
- * chunk that reaches it — four copies of the agent runtime in this repo's own docs app. A context is identified
- * by object identity, so a Provider mounted from one copy is invisible to a consumer holding another, and the
- * consumer silently reads the context's default instead.
- *
- * Silently is the whole problem. `UiOverrideContext` was a plain `createContext`, so a route's `_overrides.tsx`
- * bound its slots in the chunk holding the generated provider and every overridable component in another chunk
- * kept rendering the framework default — no throw, no warning, and only *some* slots affected, which reads like
- * a bug in the app's own component. The same shape cost a zone every tool it declared.
- *
- * The rule is therefore mechanical rather than case-by-case: a context whose Provider and consumers can be
- * bundled apart is every context worth having, so all of them go through here. A test fails if one does not.
- *
- * `use-agentic` carries its own twin under a `useAgentic.` prefix, deliberately — it ships as a standalone
- * package and cannot import this one. The prefixes keep the two namespaces from ever meeting.
- */
+/** Every framework context is made here: a build inlines modules into each client chunk, so a plain `createContext`
+ * copy silently misses a Provider from another chunk. `use-agentic` keeps its own `useAgentic.`-prefixed twin. */
 export declare const sharedContext: <T>(name: string, initial: T) => Context<T>;