@askrjs/askr 0.0.92 → 0.0.94

package/dist/{index-DA3g8lm8.d.ts → index-KQ7Vl4-8.d.ts}

@@ -1,7 +1,5 @@
-import { i as JSXElementType, r as JSXElement, s as Props } from "./types-BA9FJtfR.js";
-import { O as QueryPrefetchContext, _ as CoreTelemetry, v as DataRuntime } from "./index-2bk8nldG.js";
-import { t as Scheduler } from "./scheduler-CmLO4Dfm.js";
-import "./jsx-runtime-C_0v1pMN.js";
+import { i as JSXElementType, r as JSXElement, s as Props } from "./types-DkVJhVs9.js";
+import "./jsx-runtime-BTzDdBJ_.js";
 import { AuthContext, AuthRequirement } from "@askrjs/auth";
 import { InferSchema, ObjectSchema } from "@askrjs/schema";
 //#region src/runtime/state.d.ts
@@ -59,6 +57,7 @@ declare function state<T>(initialValue: T): StateTuple<T>;
 /**
  * Common call contracts: SSR types
  */
+/** Arbitrary serializable data attached to an SSR render pass (e.g. loader output). */
 type SSRData = Record<string, unknown>;
 /** Styles produced while rendering a request, kept with that request's SSR context. */
 interface SSRStyleRegistration {
@@ -69,6 +68,7 @@ interface DocumentRenderRoute {
   path: string;
   namespace?: string;
 }
+/** Request/render metadata passed to a {@link DocumentRenderer}. */
 interface DocumentRenderContext {
   mode: 'ssr' | 'ssg';
   url: string;
@@ -82,11 +82,14 @@ interface DocumentRenderContext {
   cspNonce?: string;
   styles?: readonly SSRStyleRegistration[];
 }
+/** Arguments passed to a {@link DocumentRenderer}: the rendered app HTML and its context. */
 interface DocumentRenderArgs {
   appHtml: string;
   context: DocumentRenderContext;
 }
+/** Wraps rendered app HTML in a full document (`<html>`, `<head>`, etc.) for SSR/SSG output. */
 type DocumentRenderer = (args: DocumentRenderArgs) => string;
+/** How to react when SSR styles were registered but not included in the rendered document. */
 type SSRStyleRegistrationValidation = 'warn' | 'error' | 'off';
 /** Full context for sink-based streaming SSR */
 type SSRContext = {
@@ -120,6 +123,7 @@ type ComponentFunction = (props: Props, context?: ComponentContext) => JSXElemen
 type ContextKey = symbol;
 type Renderable = RenderableChild;
 type ContextScopeChildren = Renderable | (() => Renderable);
+/** A lexical scope created by {@link defineScope}; render it as a provider component, read it with {@link readScope}. */
 interface Scope<T> {
   (props: {
     value: T;
@@ -132,7 +136,9 @@ interface ContextFrame {
   parent: ContextFrame | null;
   values: Map<ContextKey, unknown> | null;
 }
+/** Create a new lexical {@link Scope} with `defaultValue`, readable via {@link readScope}. */
 declare function defineScope<T>(defaultValue: T): Scope<T>;
+/** Read the current value of a {@link Scope} during component render or an async resource. */
 declare function readScope<T>(context: Scope<T>): T;
 //#endregion
 //#region src/runtime/component-cleanup.d.ts
@@ -141,16 +147,232 @@ type OwnedChildScope = {
   dispose(): void;
 };
 //#endregion
+//#region src/data/types.d.ts
+/** Freshness classification for a {@link Query}'s current data. */
+type QueryConsistency = 'fresh' | 'stale' | 'refreshing' | 'pending-write';
+/** Why a {@link Query} is stale. */
+type QueryStaleReason = 'aborted' | 'error' | 'inconsistent';
+/** Isolated cache/state container backing queries and mutations, e.g. one per test or request. */
+interface DataRuntime {
+  readonly queryCache: Map<string, unknown>;
+  readonly queryData: Map<string, unknown>;
+  /** Test-only query overrides keyed by the canonical query key. */
+  readonly queryTestOverrides: Map<string, unknown>;
+  /** Test-only mutation overrides keyed by the canonical mutation key. */
+  readonly mutationTestOverrides: Map<string, unknown>;
+}
+/** Options for {@link createDataRuntime}. */
+interface DataRuntimeOptions {
+  queryCache?: Map<string, unknown>;
+  queryData?: Map<string, unknown>;
+  queryTestOverrides?: Map<string, unknown>;
+  mutationTestOverrides?: Map<string, unknown>;
+}
+/** Reusable query definition for {@link defineQuery}: key, fetcher, and freshness checks. */
+interface QueryDefinition<TInput, TResult extends {}> {
+  readonly key: (input: TInput) => string;
+  readonly fetch: (context: TInput & {
+    signal: AbortSignal;
+  }) => Promise<TResult>;
+  readonly isConsistent?: (data: TResult) => boolean;
+  readonly reconcile?: (data: TResult, context: {
+    key: string;
+  }) => Promise<boolean> | boolean;
+}
+/** Context passed to server prefetch callbacks, exposing a scoped `prefetch` helper. */
+interface QueryPrefetchContext {
+  readonly runtime: DataRuntime;
+  readonly request?: Request;
+  readonly signal: AbortSignal;
+  readonly mode: 'ssr' | 'spa';
+  prefetch<TInput, TResult extends {}>(query: QueryDefinition<TInput, TResult>, input: TInput): Promise<boolean>;
+}
+/** Server-side handler that resolves a {@link QueryDefinition}'s data for `serveQuery`. */
+type ServerQueryHandler<TInput, TResult extends {}> = (context: {
+  input: TInput;
+  request?: Request;
+  signal: AbortSignal;
+}) => Promise<TResult> | TResult;
+/** Options for {@link invalidate} and {@link QueryScope.invalidate}. */
+interface InvalidateOptions {
+  markPendingWrite?: boolean;
+  runtime?: DataRuntime;
+}
+/** Options for {@link invalidateOnInterval}. */
+interface InvalidateOnIntervalOptions extends InvalidateOptions {
+  intervalMs: number;
+  activeOn?: string | readonly string[];
+  visibleOnly?: boolean;
+  focusedOnly?: boolean;
+}
+/** A JSON-serializable value usable as part of a query key or invalidation prefix. */
+type QueryKeyPart = string | number | boolean | null | undefined | readonly QueryKeyPart[] | {
+  readonly [key: string]: QueryKeyPart;
+};
+/** Namespaced key-building and invalidation helper returned by {@link queryScope}. */
+interface QueryScope {
+  key(...parts: QueryKeyPart[]): string;
+  prefix(...parts: QueryKeyPart[]): string;
+  invalidate(parts: readonly QueryKeyPart[], options?: InvalidateOptions): void;
+}
+type QueryControls = {
+  refresh(): Promise<void>;
+};
+type QueryLoading = {
+  data: null;
+  error: null;
+  loading: true;
+  refreshing: false;
+  stale: false;
+  consistency: 'fresh';
+  staleReason: null;
+};
+type QueryFresh<T> = {
+  data: T;
+  error: null;
+  loading: false;
+  refreshing: false;
+  stale: false;
+  consistency: 'fresh';
+  staleReason: null;
+};
+type QueryRefreshing<T> = {
+  data: T;
+  error: null;
+  loading: false;
+  refreshing: true;
+  stale: true;
+  consistency: 'refreshing';
+  staleReason: null;
+};
+type QueryPendingWrite<T> = {
+  data: T;
+  error: null;
+  loading: false;
+  refreshing: true;
+  stale: true;
+  consistency: 'pending-write';
+  staleReason: null;
+};
+type QueryStaleValue<T> = {
+  data: T;
+  error: null;
+  loading: false;
+  refreshing: false;
+  stale: true;
+  consistency: 'stale';
+  staleReason: 'aborted' | 'inconsistent';
+};
+type QueryStaleErrorWithValue<T> = {
+  data: T;
+  error: {};
+  loading: false;
+  refreshing: false;
+  stale: true;
+  consistency: 'stale';
+  staleReason: 'error';
+};
+type QueryStaleError = {
+  data: null;
+  error: {};
+  loading: false;
+  refreshing: false;
+  stale: true;
+  consistency: 'stale';
+  staleReason: 'error';
+};
+/** Reactive read state for a query cell: data, loading/refresh flags, and freshness. */
+type Query<T extends {}> = QueryControls & (QueryLoading | QueryFresh<T> | QueryRefreshing<T> | QueryPendingWrite<T> | QueryStaleValue<T> | QueryStaleErrorWithValue<T> | QueryStaleError);
+type MutationControls<TInput, TResult> = {
+  execute(input: TInput): Promise<TResult>;
+  abort(): void;
+  reset(): void;
+};
+type MutationIdle = {
+  status: 'idle';
+  pending: false;
+  error: null;
+  result: null;
+};
+type MutationPending = {
+  status: 'pending';
+  pending: true;
+  error: null;
+  result: null;
+};
+type MutationSuccess<TResult> = {
+  status: 'success';
+  pending: false;
+  error: null;
+  result: TResult;
+};
+type MutationError = {
+  status: 'error';
+  pending: false;
+  error: {};
+  result: null;
+};
+/** Reactive state for a mutation cell: status, error/result, and execute/abort/reset controls. */
+type Mutation<TInput, TResult> = MutationControls<TInput, TResult> & (MutationIdle | MutationPending | MutationSuccess<TResult> | MutationError);
+type QueryOptions<T> = {
+  key: string;
+  fetch: (ctx: {
+    signal: AbortSignal;
+  }) => Promise<T>;
+  isConsistent?: (data: T) => boolean;
+  reconcile?: (data: T, ctx: {
+    key: string;
+  }) => Promise<boolean> | boolean;
+  runtime?: DataRuntime;
+  initialData?: T;
+  skipInitialFetch?: boolean;
+};
+/** Options for {@link createMutation}. */
+type MutationOptions<TInput, TResult> = {
+  /** Stable identity used by runtime-scoped mutation test overrides. */
+  key?: string;
+  action: (input: TInput, ctx: {
+    signal: AbortSignal;
+  }) => Promise<TResult>;
+  affects?: (input: TInput, result: TResult) => string[];
+  afterSuccess?: 'invalidate';
+  runtime?: DataRuntime;
+};
+//#endregion
+//#region src/common/telemetry.d.ts
+interface TelemetryFields {
+  requestId?: string;
+  traceId?: string;
+  route?: string;
+  action?: string;
+  operation?: string;
+  status?: number;
+  durationMs?: number;
+}
+type TelemetrySpan = <T>(fields: TelemetryFields, work: () => T) => T;
+/**
+ * Structural subset implemented by `createTelemetry()` from `@askrjs/otel`.
+ * Core does not install an OpenTelemetry SDK, backend, or exporter.
+ */
+interface CoreTelemetry {
+  routeMatch?: TelemetrySpan;
+  loader?: TelemetrySpan;
+  queryPrefetch?: TelemetrySpan;
+  ssrRender?: TelemetrySpan;
+}
+//#endregion
 //#region src/common/router.d.ts
 /**
  * Common call contracts: Router types
  */
+/** Path parameters captured for a matched route, keyed by parameter name. */
 type RouteParams = Record<string, string>;
 type StripRoutePathSuffix<Path extends string> = Path extends `${infer Base}?${string}` ? StripRoutePathSuffix<Base> : Path extends `${infer Base}#${string}` ? StripRoutePathSuffix<Base> : Path;
 type TrimRoutePathSlashes<Path extends string> = Path extends `/${infer Rest}` ? TrimRoutePathSlashes<Rest> : Path extends `${infer Rest}/` ? TrimRoutePathSlashes<Rest> : Path;
 type TrimRoutePathWhitespace<Path extends string> = Path extends `${' ' | '\n' | '\t' | '\r'}${infer Rest}` ? TrimRoutePathWhitespace<Rest> : Path extends `${infer Rest}${' ' | '\n' | '\t' | '\r'}` ? TrimRoutePathWhitespace<Rest> : Path;
 type ExtractRouteSegmentParam<Segment extends string> = Segment extends `{${infer Param}}` ? TrimRoutePathWhitespace<Param> extends `*${infer SplatParam}` ? TrimRoutePathWhitespace<SplatParam> extends '' ? never : TrimRoutePathWhitespace<SplatParam> extends '*' ? never : TrimRoutePathWhitespace<SplatParam> : TrimRoutePathWhitespace<Param> extends '' ? never : TrimRoutePathWhitespace<Param> : Segment extends '*' ? '*' : never;
 type ExtractRoutePathParamNames<Path extends string> = TrimRoutePathSlashes<StripRoutePathSuffix<Path>> extends `${infer Segment}/${infer Rest}` ? ExtractRouteSegmentParam<Segment> | ExtractRoutePathParamNames<Rest> : ExtractRouteSegmentParam<TrimRoutePathSlashes<StripRoutePathSuffix<Path>>>;
+/** Statically infers the param record shape from a route path string literal, e.g. `/posts/{id}`. */
 type RoutePathParams<Path extends string> = [ExtractRoutePathParamNames<Path>] extends [never] ? Record<never, string> : { [Key in ExtractRoutePathParamNames<Path>]: string; };
 /**
  * A route page component: a regular component that receives route params as
@@ -160,23 +382,28 @@ type RoutePathParams<Path extends string> = [ExtractRoutePathParamNames<Path>] e
  * assignable.
  */
 type RouteComponent<TParams extends RouteParams = RouteParams> = (props: TParams) => RenderableChild;
+/** The rendering mode a route is currently being evaluated under. */
 type RouteMode = 'spa' | 'ssr' | 'ssg';
 type AccessRedirectStatus = 301 | 302 | 303 | 307 | 308;
 type AccessDenyStatus = 401 | 403 | 404;
 interface AccessAllowDecision {
   kind: 'allow';
 }
+/** Policy decision produced by {@link redirect}: sends the visitor to another URL. */
 interface AccessRedirectDecision {
   kind: 'redirect';
   to: string;
   status?: AccessRedirectStatus;
   replace?: boolean;
 }
+/** Policy decision produced by {@link deny}/{@link unauthorized}/{@link forbidden}/{@link notFound}. */
 interface AccessDenyDecision {
   kind: 'deny';
   status: AccessDenyStatus;
 }
+/** Outcome of a {@link RoutePolicy} evaluation: allow, redirect, or deny. */
 type AccessDecision = AccessAllowDecision | AccessRedirectDecision | AccessDenyDecision;
+/** Context passed to route policies, auth resolvers, and loaders. */
 interface RouteContext<TParams extends RouteParams = RouteParams> {
   mode: RouteMode;
   params: TParams;
@@ -187,8 +414,11 @@ interface RouteContext<TParams extends RouteParams = RouteParams> {
   auth: AuthContext;
   signal: AbortSignal;
 }
+/** A route access-control check, evaluated against {@link RouteContext} to produce an {@link AccessDecision}. */
 type RoutePolicy = (context: RouteContext) => AccessDecision | PromiseLike<AccessDecision>;
+/** Resolves the {@link AuthContext} for a route request. */
 type RouteAuthResolver = (context: Omit<RouteContext, 'auth'>) => AuthContext | PromiseLike<AuthContext>;
+/** Auth configuration shared across a route registry or a single route. */
 interface RouteAuthOptions {
   resolve: RouteAuthResolver;
   loginPath?: string | ((context: RouteContext) => string | PromiseLike<string>);
@@ -198,6 +428,7 @@ interface CommonAccessOptions {
   auth?: AuthRequirement;
   policies?: readonly RoutePolicy[];
 }
+/** A route's metadata, or a function computing it from the resolved context. */
 type RouteMetaSource<TParams extends RouteParams = RouteParams> = RouteMeta | ((context: RouteContext<TParams>) => RouteMeta | PromiseLike<RouteMeta>);
 /**
  * Options for `route()` declarations.
@@ -253,7 +484,9 @@ interface RouteMeta {
 }
 /** A stable, typed reference returned by route() for destination construction. */
 type RouteSearchValue = string | number | boolean | null | undefined | readonly (string | number | boolean | null)[];
+/** A route's query-string parameters, keyed by name. */
 type RouteSearch = Record<string, RouteSearchValue>;
+/** Stable, typed reference to a route returned by `route()`, used to build destinations. */
 interface RouteRef<TParams extends RouteParams = RouteParams, TSearch = RouteSearch> {
   readonly path: string;
   /** @internal Executable schema retained for destination validation. */
@@ -264,9 +497,11 @@ interface RouteRef<TParams extends RouteParams = RouteParams, TSearch = RouteSea
   readonly __search?: TSearch;
 }
 type RouteRefSearch<TSchema extends ObjectSchema<RouteSearch> | undefined> = TSchema extends ObjectSchema<RouteSearch> ? InferSchema<TSchema> : RouteSearch;
+/** A resolved navigation target with a computed `href`, produced by {@link to}. */
 interface RouteDestination {
   readonly href: string;
 }
+/** Options accepted by the `page()` route-declaration helper. */
 interface PageHelperOptions extends CommonAccessOptions {
   preload?: (context: RouteContext & {
     request?: Request;
@@ -298,12 +533,15 @@ interface LayoutScopeRecord {
 interface PageScopeRecord {
   component: RouteComponent;
 }
+/** Options for {@link createRouteRegistry}. */
 interface RouteRegistryOptions {
   auth?: RouteAuthOptions;
   /** Public pathname prefix for applications mounted below the origin root. */
   basePath?: string;
 }
+/** A callback that declares routes via `route()`/`page()`/`group()`, passed to {@link createRouteRegistry}. */
 type RouteDefinition = () => void;
+/** Options for resolving a route request (used internally by `createSPA`/`hydrateSPA`/SSR). */
 interface RouteRequestOptions {
   /** Explicit route source shared by the application renderers. */
   registry: RouteRegistry;
@@ -316,13 +554,16 @@ interface RouteRequestOptions {
   request?: Request;
   telemetry?: CoreTelemetry;
 }
+/** A resolved route request that should render `handler` with `params`. */
 interface RouteRenderResult<TParams extends RouteParams = RouteParams> {
   kind: 'render';
   handler: RouteHandler<TParams>;
   params: TParams;
   record?: RouteRecord;
 }
+/** Outcome of resolving a route request: render, redirect, deny, or no match. */
 type RouteRequestResult<TParams extends RouteParams = RouteParams> = RouteRenderResult<TParams> | AccessRedirectDecision | AccessDenyDecision | null;
+/** Options accepted by the `group()` route-declaration helper. */
 interface GroupHelperOptions extends CommonAccessOptions {
   layout?: (props: {
     children?: RenderableChild;
@@ -381,34 +622,40 @@ interface RouteManifest {
   basePath?: string;
 }
 declare const routeRegistryBrand: unique symbol;
+/** A function rendering a matched route's page content, with layouts already composed. */
 interface RouteHandler<TParams extends RouteParams = RouteParams> {
   (params: TParams, context?: {
     signal: AbortSignal;
   }): RenderableChild;
 }
+/** A single path-to-handler binding as seen by low-level navigation code. */
 interface Route<TParams extends RouteParams = RouteParams> {
   path: string;
   handler: RouteHandler<TParams>;
   namespace?: string;
 }
+/** Opaque handle produced by {@link createRouteRegistry}, required by `createSPA`/`hydrateSPA`. */
 interface RouteRegistry {
   /** Internal brand: registries must come from createRouteRegistry(). */
   readonly [routeRegistryBrand]: true;
   manifest: RouteManifest;
   routes: readonly Route[];
 }
+/** A single matched route, as reported by {@link currentRoute} and activity predicates. */
 interface RouteMatch<TParams extends RouteParams = RouteParams> {
   path: string;
   params: Readonly<TParams>;
   name?: string;
   namespace?: string;
 }
+/** Read-only accessor for the current route's query-string parameters. */
 interface RouteQuery {
   get(key: string): string | null;
   getAll(key: string): string[];
   has(key: string): boolean;
   toJSON(): Record<string, string | string[]>;
 }
+/** Full description of the currently active route, returned by {@link currentRoute}. */
 interface RouteSnapshot<TParams extends RouteParams = RouteParams> {
   path: string;
   params: Readonly<TParams>;
@@ -514,6 +761,70 @@ interface ReadableSource<T = unknown> {
   _version?: number;
 }
 //#endregion
+//#region src/runtime/scheduler.d.ts
+/**
+ * Serialized update scheduler — safer design (no inline execution, explicit flush)
+ *
+ * Key ideas:
+ * - Never execute a task inline from `enqueue`.
+ * - `flush()` is explicit and non-reentrant.
+ * - `runWithSyncProgress()` allows enqueues temporarily but does not run tasks
+ *   inline; it runs `fn` and then does an explicit `flush()`.
+ * - `waitForFlush()` is race-free with a monotonic `flushVersion`.
+ */
+type Task = () => void;
+type SchedulerLane = 'derived' | 'component' | 'reactive' | 'post';
+type SchedulerBulkCommitProbe = () => boolean;
+declare class Scheduler {
+  private bulkCommitProbe;
+  private lanes;
+  private running;
+  private inHandler;
+  private depth;
+  private executionDepth;
+  private flushVersion;
+  private kickScheduled;
+  private allowSyncProgress;
+  private waiters;
+  private taskCount;
+  setBulkCommitProbe(probe: SchedulerBulkCommitProbe): void;
+  private isBulkCommitActive;
+  private hasPendingTasks;
+  private getPendingTaskCount;
+  private compactLane;
+  private scheduleFlushKick;
+  enqueue(task: Task): void;
+  enqueueInLane(lane: SchedulerLane, task: Task): void;
+  flush(): void;
+  runWithSyncProgress<T>(fn: () => T): T;
+  waitForFlush(targetVersion?: number, timeoutMs?: number): Promise<void>;
+  getState(): {
+    queueLength: number;
+    running: boolean;
+    depth: number;
+    executionDepth: number;
+    taskCount: number;
+    flushVersion: number;
+    laneQueues: {
+      derived: number;
+      component: number;
+      reactive: number;
+      post: number;
+    };
+    inHandler: boolean;
+    allowSyncProgress: boolean;
+  };
+  getFlushVersion(): number;
+  flushIfQueued(): void;
+  runInHandlerScope<T>(fn: () => T, flushMode?: 'defer' | 'sync'): T;
+  setInHandler(v: boolean): void;
+  isInHandler(): boolean;
+  isExecuting(): boolean;
+  clearPendingSyncTasks(): number;
+  private resolveWaiters;
+}
+declare function scheduleEventHandler(handler: EventListener): EventListener;
+//#endregion
 //#region src/common/dom-range.d.ts
 /**
  * Internal DOM range shape shared by runtime ownership records and the
@@ -562,6 +873,7 @@ interface ChildScopeTransactionSnapshot {
 }
 //#endregion
 //#region src/runtime/runtime.d.ts
+/** Diagnostic breakdown of a keyed-list reorder decision, returned by {@link RuntimeRendererHost.isKeyedReorderFastPathEligible}. */
 interface RuntimeKeyedReorderDecision {
   useFastPath: boolean;
   totalKeyed: number;
@@ -572,6 +884,7 @@ interface RuntimeKeyedReorderDecision {
   hasPropChanges: boolean;
   isWholeKeyedList: boolean;
 }
+/** The renderer implementation an {@link AskrRuntime} delegates DOM evaluation and cleanup to. */
 interface RuntimeRendererHost {
   evaluate(node: unknown, target: Element | null, context?: object, retainedOwner?: ComponentInstance): void;
   cleanupInstancesUnder(node: Node): void;
@@ -583,10 +896,12 @@ interface RuntimeRendererHost {
   isKeyedReorderFastPathEligible(parent: Element, children: unknown[], oldKeyMap: Map<string | number, Element> | undefined): RuntimeKeyedReorderDecision;
   markReactivePropsDirtySource(source: ReadableSource<unknown>): void;
 }
+/** Options for {@link createRuntime}. */
 interface AskrRuntimeOptions {
   scheduler?: Scheduler;
   renderer?: RuntimeRendererHost;
 }
+/** A scheduler + renderer host pairing; owns scheduling and renderer wiring for an app instance. */
 declare class AskrRuntime {
   readonly scheduler: Scheduler;
   private rendererHost;
@@ -594,7 +909,9 @@ declare class AskrRuntime {
   get renderer(): RuntimeRendererHost;
   configureRenderer(renderer: RuntimeRendererHost): void;
 }
+/** Create a new {@link AskrRuntime} instance with its own scheduler/renderer wiring. */
 declare function createRuntime(options?: AskrRuntimeOptions): AskrRuntime;
+/** Get the process-wide default {@link AskrRuntime}. */
 declare function getDefaultRuntime(): AskrRuntime;
 //#endregion
 //#region src/runtime/for-signals.d.ts
@@ -786,6 +1103,7 @@ type SnapshotSourceBrand = {
 };
 //#endregion
 //#region src/runtime/derive.d.ts
+/** A reactive derived value produced by {@link derive}; call it to read the current result. */
 interface Derived<T> extends ReadableSource<T> {
   (): T;
 }
@@ -813,6 +1131,7 @@ interface RenderDiagnosticsOptions {
 declare function configureRenderDiagnostics(options: RenderDiagnosticsOptions): () => void;
 //#endregion
 //#region src/runtime/selector.d.ts
+/** A fine-grained reactive membership check produced by {@link selector}. */
 interface Selector<T> {
   (candidate: T): boolean;
 }
@@ -851,35 +1170,50 @@ type IndexedForProps<T> = ForBaseProps<T> & {
   by?: never;
   byIndex: true;
 };
+/** Props for {@link For}. */
 type ForProps<T, K extends string | number = string | number> = KeyedForProps<T, K> | IndexedForProps<T>;
+/** Render a keyed or indexed list, reconciling items by key instead of position. */
 declare const For: <T, K extends string | number = string | number>(props: ForProps<T, K>) => JSXElement;
 //#endregion
 //#region src/control/show.d.ts
 type ShowSource<T> = T | (() => T);
 type Truthy<T> = T extends false | '' | 0 | 0n | null | undefined ? never : T;
+/** Props for {@link Show}. */
 type ShowProps<T> = {
   when: ShowSource<T>;
   fallback?: BoundaryChild;
   children: BoundaryChild | ((value: Truthy<T>) => BoundaryChild);
 };
+/** Conditionally render children based on `when`, narrowing truthy values for the render function form. */
 declare const Show: <T>(props: ShowProps<T>) => JSXElement;
 //#endregion
 //#region src/control/case.d.ts
 type MatchChild = BoundaryChild | (() => BoundaryChild);
+/** Props for {@link Match}, valid only as a direct child of {@link Case}. */
 type MatchProps = {
   key?: string | number | null;
   when: unknown;
   children: MatchChild;
 };
+/** Props for {@link Case}. */
 type CaseProps = {
   fallback?: BoundaryChild;
   children?: unknown;
 };
+/** Declares one branch of a {@link Case}; only valid as its direct child. */
 declare function Match(_props: MatchProps): null;
+/** Render the first matching {@link Match} child (by `when`), or `fallback` if none match. */
 declare const Case: (props: CaseProps) => JSXElement;
 //#endregion
 //#region src/csp-nonce.d.ts
+/** Lexical scope carrying the CSP nonce for the current render, if any. */
 declare const CspNonceScope: Scope<string | undefined>;
+/**
+ * Read the CSP nonce for the current render from {@link CspNonceScope}.
+ *
+ * @returns The active nonce, or `undefined` when called outside of a
+ * component render or when no nonce was configured.
+ */
 declare function cspNonce(): string | undefined;
 //#endregion
 //#region src/common/render-context.d.ts
@@ -915,14 +1249,87 @@ declare function registerSSRStyle(id: string, cssText: string): void;
 interface Ref<T extends Element = Element> {
   current: T | null;
 }
+/** Create a new, empty {@link Ref} holder. */
 declare function createRef<T extends Element = Element>(): Ref<T>;
 //#endregion
+//#region src/data/mutation-cell.d.ts
+/**
+ * Create a reactive {@link Mutation} cell bound to the current component,
+ * running `options.action` on `execute()` and optionally invalidating
+ * affected query prefixes on success.
+ */
+declare function createMutation<TInput, TResult>(options: MutationOptions<TInput, TResult>): Mutation<TInput, TResult>;
+//#endregion
+//#region src/data/query-cell.d.ts
+/**
+ * Create a reactive {@link Query} cell bound to the current component, either
+ * from inline `options` (key + fetch) or a reusable {@link QueryDefinition}
+ * plus its input.
+ */
+declare function createQuery<T extends {}>(options: QueryOptions<T>): Query<T>;
+declare function createQuery<TInput, TResult extends {}>(definition: QueryDefinition<TInput, TResult>, input: TInput, options?: Omit<QueryOptions<TResult>, 'key' | 'fetch'>): Query<TResult>;
+//#endregion
+//#region src/data/data-runtime.d.ts
+/** Create a new, isolated {@link DataRuntime} with its own query/mutation caches. */
+declare function createDataRuntime(options?: DataRuntimeOptions): DataRuntime;
+/** Get the process-wide default {@link DataRuntime} used when none is provided explicitly. */
+declare function getDefaultDataRuntime(): DataRuntime;
+//#endregion
+//#region src/data/invalidation.d.ts
+/** Mark all cached queries whose key starts with `prefix` as stale, triggering a refresh. */
+declare function invalidate(prefix: string, options?: InvalidateOptions): void;
+/** Create a {@link QueryScope} that namespaces keys and invalidations under `namespace`. */
+declare function queryScope(namespace: string): QueryScope;
+/**
+ * Periodically invalidate queries matching `prefix` on a fixed interval,
+ * optionally gated by active route, document visibility, or window focus.
+ */
+declare function invalidateOnInterval(prefix: string, options: InvalidateOnIntervalOptions): void;
+//#endregion
+//#region src/data/query-registry.d.ts
+/** Lookup table of server handlers keyed by their {@link QueryDefinition}, built by {@link defineServerQueries}. */
+interface ServerQueryRegistry {
+  readonly entries: readonly ServerQueryEntry<unknown, {}>[];
+  get<TInput, TResult extends {}>(query: QueryDefinition<TInput, TResult>): ServerQueryHandler<TInput, TResult> | undefined;
+}
+/** A query paired with the server handler that resolves it, produced by {@link serveQuery}. */
+interface ServerQueryEntry<TInput, TResult extends {}> {
+  readonly query: QueryDefinition<TInput, TResult>;
+  readonly handler: ServerQueryHandler<TInput, TResult>;
+}
+/** Pair a {@link QueryDefinition} with the server-side handler that resolves it. */
+declare function serveQuery<TInput, TResult extends {}>(query: QueryDefinition<TInput, TResult>, handler: ServerQueryHandler<TInput, TResult>): ServerQueryEntry<TInput, TResult>;
+/** Build a {@link ServerQueryRegistry} from one or more {@link serveQuery} entries. */
+declare function defineServerQueries(...entries: readonly ServerQueryEntry<any, any>[]): ServerQueryRegistry;
+/** Freeze and return a reusable {@link QueryDefinition}. */
+declare function defineQuery<TInput, TResult extends {}>(definition: QueryDefinition<TInput, TResult>): QueryDefinition<TInput, TResult>;
+/**
+ * Create a {@link QueryPrefetchContext} for prefetching query data ahead of
+ * render, e.g. during SSR route resolution.
+ */
+declare function createQueryPrefetchContext(options?: {
+  runtime?: DataRuntime;
+  registry?: ServerQueryRegistry;
+  request?: Request;
+  signal?: AbortSignal;
+  mode?: 'ssr' | 'spa';
+  telemetry?: CoreTelemetry;
+}): QueryPrefetchContext;
+/** Prefetch `query` with `input` into a {@link QueryPrefetchContext}'s runtime. */
+declare function prefetchQuery<TInput, TResult extends {}>(context: QueryPrefetchContext, query: QueryDefinition<TInput, TResult>, input: TInput): Promise<boolean>;
+/** Extract a runtime's cached query data into a JSON-serializable snapshot, dropping non-serializable values. */
+declare function dehydrateDataRuntime(runtime: DataRuntime): Record<string, unknown>;
+/** Load a {@link dehydrateDataRuntime} snapshot back into a runtime's query cache. */
+declare function hydrateDataRuntime(runtime: DataRuntime, data: unknown): void;
+//#endregion
 //#region src/actions/index.d.ts
+/** A declared server action, built by {@link defineAction}, bound to a form via {@link ActionForm}. */
 interface ActionDescriptor<TInput extends Record<string, unknown> = Record<string, unknown>> {
   readonly id: string;
   readonly input: ObjectSchema<TInput>;
   readonly invalidates: readonly string[];
 }
+/** Declare a server action with a stable id, input schema, and query prefixes to invalidate on success. */
 declare function defineAction<TInput extends Record<string, unknown>>(options: {
   readonly id: string;
   readonly input: ObjectSchema<TInput>;
@@ -934,6 +1341,7 @@ declare function ActionForm<TInput extends Record<string, unknown>>({ action, ch
   readonly children?: RenderableChild;
   readonly [key: string]: unknown;
 }): JSXElement;
+/** Server-replayed validation failure for an {@link ActionForm} submission. */
 interface ActionValidationError {
   readonly kind: 'invalid';
   readonly action: string;
@@ -941,6 +1349,7 @@ interface ActionValidationError {
   readonly issues: readonly unknown[];
   readonly fieldErrors: Readonly<Record<string, readonly string[]>>;
 }
+/** Pending/result/error status for an action, as reported by the `action()` hook. */
 interface ActionStatus<TResult = unknown> {
   readonly pending: boolean;
   readonly result?: TResult;
@@ -952,4 +1361,4 @@ declare function action<TInput extends Record<string, unknown>, TResult = unknow
   submit(input: TInput): Promise<TResult>;
 };
 //#endregion
-export { RouteHandler as $, RuntimeKeyedReorderDecision as A, SSRData as At, AccessRedirectStatus as B, selector as C, readScope as Ct, derive as D, DocumentRenderArgs as Dt, Derived as E, VNode as Et, AccessAllowDecision as F, StateTuple as Ft, ParsedSegment as G, LayoutScopeRecord as H, AccessDecision as I, state as It, RouteAuthResolver as J, Route as K, AccessDenyDecision as L, createRuntime as M, SSRStyleRegistrationValidation as Mt, getDefaultRuntime as N, State as Nt, AskrRuntime as O, DocumentRenderContext as Ot, getSignal as P, StateSetter as Pt, RouteDestination as Q, AccessDenyStatus as R, Selector as S, defineScope as St, configureRenderDiagnostics as T, RenderableChild as Tt, PageHelperOptions as U, GroupHelperOptions as V, PageScopeRecord as W, RouteContext as X, RouteComponent as Y, RouteDefinition as Z, MatchProps as _, RouteRequestResult as _t, action as a, RouteOptions as at, For as b, RouteSnapshot as bt, createRef as c, RoutePolicy as ct, registerSSRStyle as d, RouteRef as dt, RouteManifest as et, CspNonceScope as f, RouteRefSearch as ft, Match as g, RouteRequestOptions as gt, CaseProps as h, RouteRenderResult as ht, ActionValidationError as i, RouteMode as it, RuntimeRendererHost as j, SSRStyleRegistration as jt, AskrRuntimeOptions as k, DocumentRenderer as kt, DeferredBoundaryRegistration as l, RouteQuery as lt, Case as m, RouteRegistryOptions as mt, ActionForm as n, RouteMeta as nt, defineAction as o, RouteParams as ot, cspNonce as p, RouteRegistry as pt, RouteAuthOptions as q, ActionStatus as r, RouteMetaSource as rt, Ref as s, RoutePathParams as st, ActionDescriptor as t, RouteMatch as tt, SSRPortalState as u, RouteRecord as ut, Show as v, RouteSearch as vt, RenderDiagnosticsOptions as w, ComponentFunction as wt, ForProps as x, Scope as xt, ShowProps as y, RouteSearchValue as yt, AccessRedirectDecision as z };
+export { AccessDecision as $, Scope as $t, Case as A, RouteRegistry as At, RenderDiagnosticsOptions as B, DataRuntimeOptions as Bt, Ref as C, RouteParams as Ct, registerSSRStyle as D, RouteRecord as Dt, SSRPortalState as E, RouteQuery as Et, ShowProps as F, RouteSearch as Ft, AskrRuntimeOptions as G, Query as Gt, Derived as H, InvalidateOptions as Ht, For as I, RouteSearchValue as It, createRuntime as J, QueryKeyPart as Jt, RuntimeKeyedReorderDecision as K, QueryConsistency as Kt, ForProps as L, RouteSnapshot as Lt, Match as M, RouteRenderResult as Mt, MatchProps as N, RouteRequestOptions as Nt, CspNonceScope as O, RouteRef as Ot, Show as P, RouteRequestResult as Pt, AccessAllowDecision as Q, ServerQueryHandler as Qt, Selector as R, CoreTelemetry as Rt, createMutation as S, RouteOptions as St, DeferredBoundaryRegistration as T, RoutePolicy as Tt, derive as U, Mutation as Ut, configureRenderDiagnostics as V, InvalidateOnIntervalOptions as Vt, AskrRuntime as W, MutationOptions as Wt, scheduleEventHandler as X, QueryScope as Xt, getDefaultRuntime as Y, QueryPrefetchContext as Yt, getSignal as Z, QueryStaleReason as Zt, invalidateOnInterval as _, RouteManifest as _t, action as a, DocumentRenderArgs as an, LayoutScopeRecord as at, getDefaultDataRuntime as b, RouteMetaSource as bt, ServerQueryRegistry as c, SSRData as cn, ParsedSegment as ct, defineServerQueries as d, State as dn, RouteAuthResolver as dt, defineScope as en, AccessDenyDecision as et, dehydrateDataRuntime as f, StateSetter as fn, RouteComponent as ft, invalidate as g, RouteHandler as gt, serveQuery as h, RouteDestination as ht, ActionValidationError as i, VNode as in, GroupHelperOptions as it, CaseProps as j, RouteRegistryOptions as jt, cspNonce as k, RouteRefSearch as kt, createQueryPrefetchContext as l, SSRStyleRegistration as ln, Route as lt, prefetchQuery as m, state as mn, RouteDefinition as mt, ActionForm as n, ComponentFunction as nn, AccessRedirectDecision as nt, defineAction as o, DocumentRenderContext as on, PageHelperOptions as ot, hydrateDataRuntime as p, StateTuple as pn, RouteContext as pt, RuntimeRendererHost as q, QueryDefinition as qt, ActionStatus as r, RenderableChild as rn, AccessRedirectStatus as rt, ServerQueryEntry as s, DocumentRenderer as sn, PageScopeRecord as st, ActionDescriptor as t, readScope as tn, AccessDenyStatus as tt, defineQuery as u, SSRStyleRegistrationValidation as un, RouteAuthOptions as ut, queryScope as v, RouteMatch as vt, createRef as w, RoutePathParams as wt, createQuery as x, RouteMode as xt, createDataRuntime as y, RouteMeta as yt, selector as z, DataRuntime as zt };