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

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

@@ -4,6 +4,8 @@ type DeviceInfo = CapacitorDeviceInfo;
 type Keyboard = CapacitorKeyboardModule["Keyboard"];
 type Haptics = CapacitorHapticsModule["Haptics"];
 type ImpactStyle = CapacitorHapticsModule["ImpactStyle"];
+type DebugPayload = Record<string, unknown>;
+export declare function debugFrame(event: string, payload?: DebugPayload): void;
 interface DeviceInitOption {
     lang: string;
     info: DeviceInfo;
@@ -14,7 +16,6 @@ interface DeviceInitOption {
     impactStyle: ImpactStyle;
 }
 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;

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/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

@@ -5,13 +5,12 @@ declare global {
         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;

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>;

package/types/client/storage.d.ts

@@ -1,5 +1,5 @@
 export declare const storage: {
     getItem: (key: string) => Promise<string | null | undefined>;
-    setItem: (key: string, value: string) => Promise<void>;
+    setItem: (key: string, value: string) => Promise<void | undefined>;
     removeItem: (key: string) => Promise<void>;
 };

package/types/client/types.d.ts

@@ -31,7 +31,6 @@ export declare const isFontPreloadEnabled: (font: ReactFont) => boolean;
 export declare const getFontStyles: (font: ReactFont) => ReactFontStyle[];
 export declare const getFontFaces: (font: ReactFont) => ReactFontFace[];
 export declare const getOptimizedFontSrc: (font: ReactFont, path: ReactFontPath) => string;
-/** Common props for list/zone components that render many model records. */
 export interface ModelsProps<M extends {
     id: string;
 }> {
@@ -41,7 +40,6 @@ export interface ModelsProps<M extends {
     init?: FetchInitForm<any, any>;
     onClickItem?: (model: M) => unknown;
 }
-/** Common props for unit/view components that render one named model record. */
 export type ModelProps<T extends string, L extends {
     id: string;
 }> = {
@@ -134,7 +132,6 @@ export interface ReactFont {
     adjustFontFallback?: boolean;
     optimize?: boolean;
 }
-/** Font declaration consumed by Akan layout modules and font optimization. */
 export type Font = ReactFont;
 export interface RootLayoutProps {
     children: ReactNode;

package/types/common/CodeAgentClient.d.ts

@@ -0,0 +1,20 @@
+import { type CodeAgentCommand, type CodeAgentEvent } from "./codeAgentWire.d.ts";
+export interface CodeAgentTransport {
+    send(line: string): void | Promise<void>;
+    /** Called once with a handler that receives whole lines. */
+    onLine(handler: (line: string) => void): void;
+    close?(): void | Promise<void>;
+}
+export declare class CodeAgentClient {
+    #private;
+    constructor(transport: CodeAgentTransport);
+    /** The highest sequence accepted; a reconnecting host replays from here. */
+    get lastSeq(): number;
+    /** Call on a new session, which restarts the sequence. */
+    resetSeq(): void;
+    on(listener: (event: CodeAgentEvent) => void): () => boolean;
+    send(command: CodeAgentCommand): Promise<unknown>;
+    close(): Promise<void>;
+    /** Feed raw chunks when the transport is byte-oriented rather than line-oriented. */
+    push(chunk: string): void;
+}

package/types/common/CodeTranscript.d.ts

@@ -0,0 +1,72 @@
+import type { CodeAgentApprovalRequest, CodeAgentEvent, CodeAgentQuestion, CodeAgentSessionInfo, CodeAgentStopReason, CodeAgentSubagent, CodeAgentToolOutcome, CodeAgentToolSummary } from "akanjs/common";
+export type CodeTranscriptPart = {
+    kind: "user";
+    id: string;
+    text: string;
+    images?: number;
+} | {
+    kind: "assistant";
+    id: string;
+    text: string;
+    streaming: boolean;
+    truncated: boolean;
+} | {
+    kind: "thinking";
+    id: string;
+    text: string;
+} | {
+    kind: "tool";
+    id: string;
+    tool: CodeAgentToolSummary;
+    outcome?: CodeAgentToolOutcome;
+    output?: string;
+    progress?: string;
+} | {
+    kind: "notice";
+    id: string;
+    level: "info" | "warning" | "error";
+    text: string;
+} | {
+    kind: "question";
+    id: string;
+    question: CodeAgentQuestion;
+    rendered?: string;
+} | {
+    kind: "approval";
+    id: string;
+    request: CodeAgentApprovalRequest;
+    approved?: boolean;
+} | {
+    kind: "host";
+    id: string;
+    hostKind: string;
+    text: string;
+};
+export declare class CodeTranscript {
+    #private;
+    get parts(): readonly CodeTranscriptPart[];
+    get info(): CodeAgentSessionInfo | undefined;
+    get headline(): string;
+    get context(): {
+        used: number;
+        max: number | undefined;
+    } | undefined;
+    get streaming(): boolean;
+    get compacting(): boolean;
+    get question(): CodeAgentQuestion | undefined;
+    get approval(): CodeAgentApprovalRequest | undefined;
+    get stopReason(): CodeAgentStopReason | undefined;
+    get queue(): {
+        steering: number;
+        followUp: number;
+    };
+    get subagents(): CodeAgentSubagent[];
+    /** Bumped on every applied event. */
+    get revision(): number;
+    /** Drops every row but keeps the session info; the model's own window is untouched. */
+    clear(): void;
+    /** A locally typed prompt, drawn before the engine echoes it back as a `message` matched by text. */
+    echo(text: string, images?: number): void;
+    note(level: "info" | "warning" | "error", text: string): void;
+    apply(event: CodeAgentEvent): void;
+}

package/types/common/Logger.d.ts

@@ -52,19 +52,14 @@ export interface LoggerEmitInput {
     context?: string;
     attrs?: LogAttrs;
 }
-/** Log-level aware logger used by Akan runtime, CLI, and application services. */
 export declare class Logger {
     #private;
-    /** `AKAN_LOG_STDOUT_LEVEL` names what the container's stdout carries; without it the console level is that. */
     static level: LogLevel;
     static fileLevel: LogLevel;
     static format: LogFormat;
-    /** Which process this is (`gateway`, `all`, `batch`, `rsc-worker`); the owner sets it at boot. */
+    /** `gateway`, `all`, `batch` or `rsc-worker`; the owner sets it at boot. */
     static role: string | null;
-    /**
-     * Whether this process writes its own lines to the terminal. Off in every server process of an ndjson
-     * deployment: the hub owner writes the one JSON stream, and a text line from anyone would corrupt it.
-     */
+    /** Off in every server process of an ndjson deployment but the hub owner, whose JSON stream a text line corrupts. */
     static consoleOutput: boolean;
     /** Set by the trace layer when a flight recorder or a per-request debug floor can be active. */
     static contextGate: boolean;
@@ -75,27 +70,16 @@ export declare class Logger {
     static removeSink(sink: LoggerSink): void;
     static isVerbose(): boolean;
     static get isNdjson(): boolean;
-    /** For hot-path callers that would otherwise build a message the level is about to discard. */
     static shouldLog(logLevel: LogLevelInput): boolean;
     static normalizeLevel(level: LogLevelInput): LogLevel;
-    /** The lowest named level whose severity is at least `sev`. */
     static levelAtOrAbove(sev: number): LogLevel;
     static render(record: LogRecord): string;
-    /** `key=value` pairs; a string with whitespace is quoted so the line stays splittable. */
     static formatAttrs(attrs: LogAttrs): string;
-    /**
-     * A record somebody asked for below the level — a failed call's flight recorder, a request carrying
-     * `x-akan-debug` — passes every floor between here and the reader; the floors exist to drop what nobody asked for.
-     */
+    /** A flight-recorder or `x-akan-debug` record passes every floor between here and the reader. */
     static isPromoted(record: LogRecord): boolean;
     static redactAttrs(attrs: LogAttrs): LogAttrs;
-    /** A structured record from a caller that has more than a sentence to say — the canonical request line. */
     static emit({ level, name, message, context, attrs }: LoggerEmitInput): void;
-    /**
-     * Writes records that were captured below the gate and are now promoted — a failed request's flight
-     * recorder. They bypass the console level, since not showing them is what the recorder was for, and reach
-     * sinks under their own floors; each is marked `flight` so a reader knows why a trace line appears at info.
-     */
+    /** Writes a failed request's flight-recorder records past the console level, each marked `flight`. */
     static replay(records: LogRecord[], { evicted }?: {
         evicted?: number;
     }): void;

package/types/common/TrustedProxy.d.ts

@@ -1,36 +1,10 @@
-/**
- * Whether the hop that connected is allowed to name the caller.
- *
- * `x-real-ip` and `x-forwarded-for` are just request headers: anyone can send them. They are the truth only when
- * the peer that sent them is a proxy we put there — otherwise a client forges its own address and walks past
- * every `.with(Ip)` guard, rate limit and audit line at once.
- *
- * The default trusts a private, loopback or link-local peer and nothing else, because that is exactly the shape
- * of a proxy on the same network: an ingress, a service mesh, the dev machine. A gateway reachable from the
- * internet sees a public peer, so a header from there is dropped rather than believed. `AKAN_TRUSTED_PROXIES`
- * takes a comma-separated CIDR list for the case the proxy is not private — and `*` for "the deployment
- * guarantees nothing untrusted can reach this port", which is the old behaviour, written down.
- */
 export declare class TrustedProxy {
     #private;
     static configure(list: string | null | undefined): void;
     static reset(): void;
     static isTrusted(address: string | null | undefined): boolean;
-    /**
-     * The caller's address as recorded by a proxy, but only when the peer is one. Falls back to the peer itself,
-     * which is the right answer for a process nothing is proxying, and `null` when there is no peer either.
-     *
-     * `null` and `undefined` mean different things here. `null` is what `Server.requestIP` answers for a socket
-     * that has no address — a unix socket, which is how a gateway reaches its children — and only a process on
-     * this machine can open one, so the headers it wrote are a local proxy's and are believed. `undefined` is
-     * "nobody asked": no resolver was registered, and a header from an unknown peer is a header the client wrote.
-     */
+    /** A `null` peer is a unix socket, which only a local proxy opens, so its headers count; `undefined` is not. */
     static clientAddress(headers: Headers, peerAddress: string | null | undefined): string | null;
-    /**
-     * Whether an address is one no public name should resolve to: the local ranges `isTrusted` reads, plus the
-     * unspecified address, the carrier-grade NAT block `100.64/10`, multicast and the reserved top of IPv4. Used
-     * to refuse a fetch whose destination a caller chose by name, so it judges the address alone and never the
-     * configured proxy list — a trusted proxy is still not somewhere to send an outbound request.
-     */
+    /** For refusing an outbound fetch to a caller-chosen name: judges the address alone, never the proxy list. */
     static isPrivateAddress(address: string): boolean;
 }

package/types/common/applyMixins.d.ts

@@ -1,3 +1,6 @@
 type Cls<T = unknown> = new (...args: never[]) => T;
+export declare const getAllPropertyDescriptors: (objRef: Cls) => {
+    [key: string]: PropertyDescriptor;
+};
 export declare const applyMixins: (derivedCtor: Cls, constructors: (Cls | undefined)[], avoidKeys?: Set<string>) => Cls<unknown>;
 export {};

package/types/common/authToken.d.ts

@@ -1,19 +1,8 @@
 /** The pre-scoping key. Read as a fallback, never written; drop it once deployments have rotated past it. */
 export declare const legacyAuthTokenKey = "jwt";
-/**
- * Cookies carry no port (RFC 6265), so every app served from one host shares a jar — which on localhost is
- * every app in the workspace at once. Under a global `jwt` key each signin overwrites the neighbour's
- * session, and the JWT's own `appName` check only turns the stolen cookie into a failing credential.
- */
 export declare const authTokenKey: () => string;
 /** Matches both spellings so a signout can sweep a jar written before and after the key was scoped. */
 export declare const isAuthTokenKey: (key: string) => boolean;
-/** Whether a raw `cookie` header carries an auth token under either spelling. */
 export declare const cookieHeaderHasAuthToken: (cookieHeader: string | null | undefined) => boolean;
-/** Whether a token was minted for this app and environment — the same pair the server's account check makes. */
 export declare const isOwnAuthToken: (jwt: string) => boolean;
-/**
- * Reads the app-scoped token, falling back to a leftover global one only when its payload names this app —
- * a neighbour's token would decode fine here and fail every guard, so adopting it is worse than none.
- */
 export declare const readAuthToken: (read: (key: string) => string | null | undefined) => string | undefined;

package/types/common/capitalize.d.ts

@@ -1,2 +1,2 @@
-/** Uppercases only the first character of a string. */
 export declare const capitalize: (str: string) => string;
+export declare const lowerlize: (str: string) => string;

package/types/common/clamp.d.ts

@@ -1,2 +1 @@
-/** Constrains a value to `[min, max]`. */
 export declare const clamp: (value: number, min: number, max: number) => number;

package/types/common/clientAddress.d.ts

@@ -1,19 +1,5 @@
-/** Headers a proxy hop writes so the next hop can still name the original caller. */
 export declare const forwardedHeaders: readonly ["x-real-ip", "x-forwarded-for", "x-forwarded-port", "x-forwarded-host", "x-forwarded-proto"];
-/**
- * An IPv4 client reaching a dual-stack listener is reported as `::ffff:203.0.113.10`. That form is not a
- * valid destination for a `udp4` socket and does not compare equal to the same address written plainly, so
- * it is unwrapped at every boundary rather than at each call site that happens to remember.
- */
 export declare const normalizeIpAddress: (address: string) => string;
-/**
- * The caller's address as the nearest proxy recorded it. `x-real-ip` is one hop's word for who the client is
- * and wins; `x-forwarded-for` is a chain appended left to right, so its *first* entry is the original client
- * and everything after it is a proxy.
- *
- * Returns `null` rather than a placeholder. A socket peer behind a proxy is the proxy, so `127.0.0.1` here
- * would be indistinguishable from a genuinely local caller — and that is the failure this exists to prevent.
- */
+/** `x-real-ip`, else the first `x-forwarded-for` entry; `null`, never a placeholder, when neither is set. */
 export declare const clientAddressFromHeaders: (headers: Headers) => string | null;
-/** The client port the nearest proxy recorded, for correlating a connection with a peer's own logs. */
 export declare const clientPortFromHeaders: (headers: Headers) => number | null;