akanjs 3.0.0-beta.9 → 3.0.0

package/types/signal/sliceInfo.d.ts

@@ -5,42 +5,17 @@ import type { ServiceModel } from "akanjs/service";
 import { type ArgInfo, type EndpointArgProps, type InternalArgInfo, type InternalArgProps } from "./endpointInfo.d.ts";
 import type { InternalArgCls } from "./internalArg.d.ts";
 import type { CnstFull, CnstInput, CnstInsight, CnstLight, DbFilter, SignalOption, SrvMap, SrvRefName } from "./types.d.ts";
-/**
- * What a slice declares when it opts into live sync. Nothing here is required — `.live()` on its own is the whole
- * opt-in, and every default below is the conservative reading.
- */
 export interface LiveSliceOption<ArgName extends string = string> {
     /**
-     * The sort keys a client may reproduce well enough to place a row itself. Anything else falls back to a refetch,
-     * because the client would otherwise have to guess where a new row goes.
-     *
-     * `latest` is `{ createdAt: -1 }` on a real column, which a client compares identically. A key that sorts on a
-     * field inside `_doc` is checked at boot and warned about: SQLite orders those by SQL value and Postgres by
-     * jsonb type, so the two servers do not even agree with each other.
+     * Keys a client may place a new row under itself (default `["latest"]`); any other sort refetches. A key on a
+     * `_doc` field is warned about at boot: SQLite orders it by SQL value and Postgres by jsonb type.
      */
     sort?: string[];
-    /**
-     * Downgrades this slice to invalidation only: subscribers are told their list moved and refetch, and no
-     * membership is evaluated. Required for a query holding `q.raw()`, `q.search()`, or `exists`/`missing` on a
-     * `_doc` field, none of which can be answered without the database.
-     */
+    /** Invalidation only: subscribers refetch. Required for `q.raw()`, `q.search()` or `exists`/`missing` on `_doc`. */
     fallback?: "invalidate";
     /** `light` sends the row and costs nothing to apply; `id` sends the id alone for a room where the row is bulky. */
     payload?: "light" | "id";
-    /**
-     * The arguments that switch live sync off for as long as they carry a value, named for this slice.
-     *
-     * A filter often builds a different query shape depending on what it was handed — `search ? q.search(text) : {}`
-     * is the common one — so the same slice is routable blank and unroutable with text in the box. Naming the
-     * argument makes that explicit: the client opens no room while it is filled and the window updates by
-     * refetching, which is what a slice with no `.live()` at all does. Clearing it opens the room again.
-     *
-     * Only a nullable argument can be named, which in practice means a `search`: a `param` is always present, so
-     * naming one would switch live off for good. That is refused at boot rather than left to be discovered.
-     *
-     * This is not `fallback`. `fallback: "invalidate"` keeps the room and gives up precision — every write on the
-     * model tells the room to refetch. `pauseOn` gives up the room and keeps precision everywhere else.
-     */
+    /** Nullable arguments that close the room while they carry a value (the list refetches); a `param` is refused. */
     pauseOn?: ArgName[];
 }
 export interface ResolvedLiveSliceOption {
@@ -68,10 +43,10 @@ export declare class SliceInfo<RefName extends string = string, Input = any, Ful
     execFn: ((...args: [...ServerArgs, ...InternalArgs]) => QueryOf<DocumentModel<Full>>) | null;
     constructor(refName: RefName, input: Cls<Input>, full: Cls<Full>, light: Cls<Light>, insight: Cls<Insight>, filter: FilterCls<Filter>, signalOption?: SignalOption);
     param<ArgName extends string, Arg extends ParamFieldType, _ClientArg = FieldToValue<Arg>, _ServerArg = DocumentModel<_ClientArg>>(name: ArgName, arg: Arg, option?: Omit<EndpointArgProps, "nullable">): SliceInfo<RefName, Input, Full, Light, Insight, Filter, Srvs, [...ArgNames, ArgName], [...Args, arg: _ClientArg], InternalArgs, [...ServerArgs, arg: _ServerArg]>;
+    /** @deprecated Slices are GET queries, which carry no body: `fetch` never sends this argument. Use `.search`. */
     body<ArgName extends string, ExplicitType = unknown, Arg extends ConstantFieldTypeInput = PlainTypeToFieldType<ExplicitType>, Optional extends boolean = false, _ArgType = unknown extends ExplicitType ? FieldToValue<Arg> : ExplicitType, _ClientArg = UploadableClientArg<PurifiedModel<_ArgType>>, _ServerArg = DocumentModel<_ArgType>>(name: ArgName, arg: Arg, option?: EndpointArgProps<Optional>): SliceInfo<RefName, Input, Full, Light, Insight, Filter, Srvs, [...ArgNames, ArgName], Optional extends true ? [...Args, arg?: _ClientArg | null] : [...Args, arg: _ClientArg], InternalArgs, [...ServerArgs, arg: _ServerArg | (Optional extends true ? undefined : never)]>;
     search<ArgName extends string, ExplicitType = unknown, Arg extends ConstantFieldTypeInput = PlainTypeToFieldType<ExplicitType>, _ArgType = unknown extends ExplicitType ? FieldToValue<Arg> : ExplicitType, _ClientArg = PurifiedModel<_ArgType>, _ServerArg = DocumentModel<_ArgType>>(name: ArgName, arg: Arg, option?: Omit<EndpointArgProps, "nullable">): SliceInfo<RefName, Input, Full, Light, Insight, Filter, Srvs, [...ArgNames, ArgName], [...Args, arg?: _ClientArg | null], InternalArgs, [...ServerArgs, arg: _ServerArg | undefined]>;
     with<ArgType, Optional extends boolean = false>(argRef: InternalArgCls<ArgType>, option?: InternalArgProps<Optional>): SliceInfo<RefName, Input, Full, Light, Insight, Filter, Srvs, ArgNames, Args, [...InternalArgs, arg: NonNullable<ArgType> | (Optional extends true ? null : never)], ServerArgs>;
-    /** Opts this slice into live sync. Declaring nothing at all is what keeps a slice out of it entirely. */
     live(option?: LiveSliceOption<ArgNames[number]>): this;
     exec(query: (this: {
         [K in keyof Srvs as K extends string ? Uncapitalize<K> : never]: Srvs[K];

package/types/signal/trace.d.ts

@@ -1,7 +1,5 @@
 import { type LogAttrs, type LogFlightRecorder } from "akanjs/common";
-/** Whether full request tracing (`AKAN_TRACE=1`) is enabled. Cached after first read. */
 export declare const isTraceEnabled: () => boolean;
-/** Override the trace flag at runtime (tests / harness control). */
 export declare const setTraceEnabled: (enabled: boolean) => void;
 export declare const isLogContextEnabled: () => boolean;
 export declare const setLogContextEnabled: (enabled: boolean) => void;
@@ -14,11 +12,6 @@ export declare const setFlightRecorderEnabled: (enabled: boolean) => void;
 /** `AKAN_LOG_FLIGHT_MS`: a call at least this long is "slow" for both the recorder and the `slow` canonical mode. */
 export declare const getFlightThresholdMs: () => number;
 export declare const setFlightThresholdMs: (ms: number) => void;
-/**
- * `x-akan-debug` lowers one request's log floor to `trace`. Honoured in `local` unconditionally, and elsewhere only
- * when the header carries the value of `AKAN_LOG_DEBUG_HEADER`: a client that can lower a server's log level is a
- * log-volume vector, so outside development it has to prove it was told the secret.
- */
 export declare const isDebugHeaderAllowed: () => boolean;
 export interface SpanRecord {
     name: string;
@@ -27,7 +20,6 @@ export interface SpanRecord {
 export type TraceMode = "context" | "full";
 export type TraceOrigin = "http" | "websocket" | "mcp" | "internal" | "page";
 export type TraceOutcome = "ok" | "error";
-/** Per-request trace context. Threaded via {@link AsyncLocalStorage}. */
 export declare class SignalTrace {
     #private;
     /** Total captured records the process holds at once (`AKAN_LOG_FLIGHT_MAX`); a call past it runs unrecorded. */
@@ -39,7 +31,6 @@ export declare class SignalTrace {
     readonly mode: TraceMode;
     readonly startedAt: number;
     readonly spans: SpanRecord[];
-    /** What the canonical line carries beyond timing — `userId` once the caller is known. */
     readonly attrs: LogAttrs;
     dbQueryCount: number;
     dbQueryMs: number;
@@ -56,11 +47,10 @@ export declare class SignalTrace {
         mode?: TraceMode;
         origin?: TraceOrigin;
     });
-    /** The trace a call runs under given what is switched on, or `null` when both modes are off. */
+    /** `null` when both modes are off. */
     static create(endpointKey: string, endpointType: string, origin: TraceOrigin): SignalTrace | null;
     static get activeFlights(): number;
     get endpoint(): string;
-    /** Attaches the ring unless the process is already holding its cap; a trace past the cap simply is not recorded. */
     startFlightRecorder(): boolean;
     /** Honours `x-akan-debug` for this call when the deployment allows it; anything else is ignored, not refused. */
     applyDebugHeader(value: string | null | undefined): boolean;
@@ -73,34 +63,17 @@ export declare class SignalTrace {
     finalize(): void;
 }
 export declare const getCurrentTrace: () => SignalTrace | undefined;
-/** Run `fn` with `trace` as the ambient request trace. */
 export declare const runWithTrace: <T>(trace: SignalTrace, fn: () => T) => T;
-/**
- * Run `fn` as the whole life of `trace`: a throw marks the outcome before it propagates, and the trace is
- * finalized after the caller's own catch has run — which is what lets an error log carry the traceId.
- */
+/** Finalizes `trace` after the caller's own catch has run, which is what lets an error log carry the traceId. */
 export declare const runTraced: <T>(trace: SignalTrace | null, fn: () => Promise<T>) => Promise<T>;
-/**
- * Time an async stage under the current trace. When tracing is off (or no trace is
- * active) this is a thin passthrough with no measurement overhead.
- */
 export declare const traceSpan: <T>(name: string, fn: () => Promise<T>) => Promise<T>;
-/** Record a DB query duration against the current trace (no-op when untraced). */
 export declare const traceDbQuery: (durationMs: number) => void;
-/** Record a cache hit/miss against the current trace (no-op when untraced). */
 export declare const traceCache: (hit: boolean) => void;
-/** Record a DataLoader batch against the current trace (no-op when untraced). */
 export declare const traceDataLoaderBatch: (keyCount: number) => void;
-/**
- * Process-wide aggregator. Keeps rolling per-endpoint, per-span statistics with a
- * bounded sample ring per span so percentiles stay representative of steady state
- * without unbounded memory growth.
- */
 declare class TraceAggregator {
     #private;
     ingest(trace: SignalTrace): void;
     reset(): void;
-    /** Summarized snapshot suitable for JSON exposure on the metrics endpoint. */
     snapshot(): {
         enabled: boolean;
         endpoints: {
@@ -123,7 +96,6 @@ declare class TraceAggregator {
     };
 }
 export declare const traceAggregator: TraceAggregator;
-/** Snapshot of all aggregated trace stats. Safe to call when tracing is disabled. */
 export declare const getTraceSnapshot: () => {
     enabled: boolean;
     endpoints: {

package/types/signal/types.d.ts

@@ -46,6 +46,8 @@ interface InitOption {
     serverMode?: "federation" | "batch" | "all";
     operationMode?: ("cloud" | "edge" | "local" | (string & {}))[];
     enabled?: boolean;
+    /** Instances booting together take turns and one that waited skips its own run; unset, every instance runs it. */
+    once?: boolean;
 }
 interface TimerOption {
     serverMode?: "federation" | "batch" | "all";
@@ -70,59 +72,31 @@ export interface SignalOption<Response = any, Nullable extends boolean = false,
     path?: string;
     serverMode?: "federation" | "batch" | "all";
     /**
-     * How long this endpoint may take, in milliseconds. It bounds both ends: the `Timeout` middleware — registered
-     * by default — rejects the call with `base.error.gatewayTimeout` once it is spent, and the value is serialized
-     * to the client, where it becomes that call's request budget in place of the client default. Declared nowhere,
-     * neither side imposes one beyond the client's own default.
-     *
-     * Losing the race does not stop the work: the handler runs to completion with nobody holding its result.
+     * Milliseconds; the server rejects with `base.error.gatewayTimeout` and the client sizes its request budget from
+     * it. Losing the race does not stop the handler, which runs to completion with nobody holding its result.
      */
     timeout?: number;
     partial?: _Key[] | readonly _Key[];
     /**
-     * How long this endpoint's answer may be reused, in milliseconds. The `Cache` middleware — registered by
-     * default — keeps the handler's result under the endpoint's key and its arguments and serves it until it
-     * expires; declared nowhere, nothing is cached.
-     *
-     * **Only a `query` that takes no internal argument may carry one.** Internal arguments are how a call learns
-     * who is asking (`.with(Self)`), so an endpoint that has them answers per caller, and one shared entry would be
-     * one caller's answer handed to the next; such an endpoint is named in the log and left uncached. Guards still
-     * run on every hit — a shared answer is not a public one.
+     * Milliseconds to reuse the answer, keyed by endpoint and arguments; unset caches nothing. Only a `query` with no
+     * internal argument may carry one (those answer per caller), and the lookup runs after the guards.
      */
     cache?: number;
     guards?: GuardCls[];
     middlewares?: MiddlewareCls[];
     prefix?: false | string;
     globalPrefix?: false;
-    /**
-     * HTTP verb for a `mutation`, `POST` unless named. Only a foreign wire protocol needs the others — a client
-     * that cannot be changed and sends `PATCH /rest/v1/<table>`. Every other endpoint type ignores it.
-     */
+    /** HTTP verb of a `mutation`, `POST` unless named; every other endpoint type ignores it. */
     method?: HttpMutationMethod;
-    /** Marks this mutation as the framework file-upload endpoint (see resolveFileUploadCapability). */
     fileUpload?: boolean;
-    /**
-     * Whether this endpoint belongs on an agent's shelf. `true` — the default — publishes it to MCP subject to the
-     * guard and shape rules; `false` keeps it out of the catalogue entirely.
-     *
-     * This is curation, not authorization: HTTP serves the endpoint exactly as before, and the guards are still the
-     * only thing deciding who may call it. Write it where an endpoint is perfectly guarded and still has no business
-     * on a shelf — a step of a UI-driven state machine (`requestPhoneCodeForSignin`), or a read a model would only
-     * ever call by mistake. Every catalogue entry carries the model schemas it mentions, so one endpoint dropped
-     * here is kilobytes off every `tools/list`.
-     */
+    /** `false` keeps it out of the MCP catalogue (default `true`); curation, not authorization — HTTP still serves it. */
     mcp?: boolean;
     /**
-     * What a `pubsub(Binary)` does when a subscriber cannot keep up. `"coalesce"` (the default) keeps only the
-     * newest frame per room, which is what a telemetry or video stream wants — an old frame is worthless once a
-     * newer one exists. Name `"queue"` when the frames are a sequence a subscriber has to see in full, such as
-     * deltas against a base it already holds; the send buffer then grows with the slowest subscriber.
+     * A slow subscriber of a `pubsub(Binary)`: `"coalesce"` (default) keeps only the newest frame per room, `"queue"`
+     * delivers every frame and grows the send buffer with the slowest subscriber.
      */
     backpressure?: "coalesce" | "queue";
-    /**
-     * Set by the resolver on the pubsub endpoint it generates for a `.live()` slice, never by hand. It carries what
-     * the room needs to route a change — which model, and how the slice asked to be treated.
-     */
+    /** Set by the resolver on the pubsub endpoint it generates for a `.live()` slice, never by hand. */
     live?: LiveEndpointOption;
     scheduleType?: "init" | "destroy" | "cron" | "interval" | "timeout";
     scheduleCron?: string;
@@ -138,25 +112,13 @@ interface SerializedSignalOption {
     guards?: string[];
     method?: HttpMutationMethod;
     fileUpload?: boolean;
-    /**
-     * Only ever `false`, and only when something declared it: `true` is the default, so serializing it would ship a
-     * field per endpoint that says nothing. Resolved here rather than left to the reader because the browser API
-     * explorer has guard *names* and no classes, and a second implementation of the rule would eventually disagree
-     * with the catalogue.
-     */
+    /** Only ever `false`, when declared. Resolved here because the API explorer holds guard names, not classes. */
     mcp?: false;
-    /**
-     * Only ever `false`, and only when one of the guards declares `static agents = false`: a person-only act. Resolved
-     * here for the same reason `mcp` is — the reader holds guard names, not classes.
-     */
+    /** Only ever `false`, when a guard declares `static agents = false` (a person-only act). */
     agents?: false;
 }
 export interface SerializedSlice extends SerializedSignalOption {
-    /**
-     * Present when the slice declared `.live()`. `sort` is the allowlist of sort keys a subscriber may place a new
-     * row under itself; on any other sort an insertion refetches instead of guessing where the row goes. `pauseOn`
-     * names the arguments that switch the room off while they carry a value, and travels only when there are any.
-     */
+    /** `sort`: keys a subscriber may place a new row under itself (others refetch); `pauseOn` travels only when set. */
     live?: {
         sort: string[];
         pauseOn?: string[];
@@ -178,31 +140,22 @@ export interface SerializedArg {
     nullable?: boolean;
     example?: string | number | boolean | Date;
     enum?: string;
-    /** The values this arg accepts, when they are a fixed list the caller has to pick from. */
     oneOf?: (string | number)[];
-    /** For an id a filter declared against a model: the model it points at, so a UI can offer a picker. */
+    /** The model a filter's id argument points at, so a UI can offer a picker. */
     ref?: string;
 }
 export interface SerializedEndpoint extends SerializedSignalOption {
     type: "query" | "mutation" | "pubsub" | "message";
     returns: SerializedReturns;
-    /**
-     * The deadline the endpoint declared, in milliseconds. It travels because the client has to size its own
-     * request budget from it: a call the server is allowed to spend five minutes on is one the browser must not
-     * abandon after the client default.
-     */
+    /** Milliseconds; the client sizes its request budget from it. */
     timeout?: number;
 }
 export interface SerializedFilter {
-    /** Every filter query the model declares, by key, with the args each one takes. */
     filter: {
         [key: string]: SerializedArg[];
     };
     sortKeys: string[];
-    /**
-     * The field map behind each sort key, which a live subscriber needs to place a new row without asking the server
-     * where it goes. Only the keys a `.live({ sort })` allowlist names are ever compared against it.
-     */
+    /** The field map behind each sort key, which a live subscriber needs to place a new row itself. */
     sorts?: {
         [key: string]: {
             [path: string]: 1 | -1;
@@ -223,10 +176,7 @@ export interface SerializedSignal {
     createGuards?: string[];
     updateGuards?: string[];
     removeGuards?: string[];
-    /**
-     * Which generated CRUD verbs this model keeps off the agent shelf. Carried on the signal because the endpoints
-     * it names do not exist until `FetchClient.getBaseEndpoint` synthesizes them. Only the `false` keys travel.
-     */
+    /** Generated CRUD verbs kept off the agent shelf, carried here because `FetchClient.getBaseEndpoint` synthesizes them. */
     mcp?: SerializedSignalMcp;
     /** Which generated CRUD verbs a person-only guard protects, by the same verb map; only the `false` keys travel. */
     agents?: SerializedSignalMcp;
@@ -250,11 +200,8 @@ export type WebsocketMessageData = {
     data: object | object[];
 };
 /**
- * One document change, as one live room sees it.
- *
- * The verb is relative to the room and not to the database: a row edited out of a filter arrives as `leave` in the
- * list it left and `enter` in the one it joined, and a soft delete is a `leave` everywhere. `invalidate` carries no
- * document at all — it is what a room that cannot be routed in memory sends instead, and it means refetch.
+ * `op` is relative to the room, not the database: a row edited out of a filter is `leave` there and `enter` where it
+ * joined, a soft delete is `leave` everywhere, and `invalidate` (no document) means refetch.
  */
 export interface LiveEventPayload {
     op: "enter" | "update" | "leave" | "invalidate";
@@ -262,9 +209,8 @@ export interface LiveEventPayload {
     light?: object | null;
 }
 /**
- * `roomId` is the room the server actually joined; `requestRoomId` is the one the client built from the arguments
- * it sent. They differ only for a live room, whose id also carries the caller's resolved internal arguments so
- * that two subscribers of the same `inSelf` slice do not share one room. The client re-keys on the pair.
+ * `roomId` is the room the server joined, `requestRoomId` the one the client built; they differ only for a live room,
+ * whose id also carries the caller's internal arguments. The client re-keys on the pair.
  */
 export type WebsocketSubscribeAck = {
     type: "sub";

package/types/store/SliceRequest.d.ts

@@ -1,16 +1,6 @@
-/**
- * Which list request for one slice is the current one.
- *
- * Every paging action reads state, fires a fetch, and writes the answer back. Two of them in flight — a user
- * clicking page 2 then page 3 — race, and the *slower* response used to win: the list from one page landed under
- * the page number of another, and the spinner was cleared by whichever finished last. Nothing in the state could
- * say which request a response belonged to, so a ticket says it instead.
- *
- * One per slice rather than per action, because every one of them writes the same `<model>List`.
- */
+/** Which of a slice's in-flight list requests is current, so a slower, older response is dropped. */
 export declare class SliceRequest {
     #private;
-    /** Takes the next ticket and makes it the current one, so every earlier request is now stale. */
     claim(): number;
     isCurrent(ticket: number): boolean;
 }

package/types/store/action.d.ts

@@ -32,16 +32,12 @@ export interface NewOption {
     modal?: string;
     setDefault?: boolean;
     sliceName?: string;
-    /**
-     * The draft scope this form belongs to, already built by the shell that holds the raw seed. Absent means no
-     * draft: `new<Model>` merges its argument into `default<Model>`, whose date defaults would rotate the key on
-     * every open, so the scope cannot be derived from what arrives here.
-     */
+    /** Built by the shell from the raw seed (merged date defaults would rotate the key). Absent means no draft. */
     draftScope?: string;
 }
 export interface EditOption {
     modal?: string | null;
-    /** As `NewOption.draftScope`. For an edit the shell builds it from the record id. */
+    /** Built by the shell from the record id. Absent means no draft. */
     draftScope?: string;
 }
 type PartialOrNull<O> = {

package/types/store/actionTag.d.ts

@@ -3,19 +3,10 @@ export interface ActionOwner {
     refName: string;
 }
 export interface ActionTag {
-    /** The `st.do` key this function is. */
     action: string;
     /** The state path it writes, when it writes exactly one — `userForm.name` for a field setter. */
     state?: string;
 }
-/**
- * Marks a dispatcher with what it does, so a component handed one by reference can say so in the DOM.
- *
- * `onChange={st.do.setNameOnUser}` is the house form for every model field, which means the component already holds
- * everything an annotation needs — it just has no way to read it off a function. This is that way, and it is why
- * `data-akan-*` costs an app no code at all: nobody writes the attribute, the setter carries its own name.
- *
- * Non-enumerable, so it survives neither `{...fn}` nor `JSON.stringify` and shows up in no spread.
- */
+/** Tags a dispatcher (non-enumerable) so a control handed it by reference can emit `data-akan-*`. */
 export declare const tagAction: <T extends (...args: never[]) => unknown>(fn: T, tag: ActionTag) => T;
 export declare const actionTagOf: (value: unknown) => ActionTag | undefined;

package/types/store/agent/AgentBridge.d.ts

@@ -1,24 +1,10 @@
 import type { AgentRefusal } from "akanjs/signal";
 import type { StoreInstance } from "../storeInstance.d.ts";
-import type { SerializedStoreState } from "./types.d.ts";
-/**
- * What an in-page agent may read out of the store the user is looking at.
- *
- * Reads only. Driving the app is a component's declaration to make: `st.tool` binds a name and a schema to the
- * same handler the control on screen calls, so what an agent can do is what the screen offers the user and nothing
- * else. A store method that no component declared is not a lever this screen has — publishing one made the surface
- * the bundle rather than the screen, and gave the model levers whose effect it could not see.
- *
- * A key is readable while a mounted component subscribes it through `st.use` / `st.sel` / `st.ref`, and its value
- * is masked by the model that key declares. Masking is not optional even though the data mostly came from the
- * server already masked: `<model>Form` holds what the *user* typed, credentials included, and an in-page agent
- * ships what it reads to a remote model. The mask is by the declared model rather than by the value's class,
- * because `immerify` copies a form into a plain object and the class is gone by the time anyone can ask.
- */
+import { type SerializedStoreState } from "./StoreCatalogue.d.ts";
+/** Masked store reads for an in-page agent: `<model>Form` holds typed credentials, and reads ship to a remote model. */
 export declare class AgentBridge {
     #private;
     readonly refusals: AgentRefusal[];
-    /** The bridge for the app running in this process: the one store every `st.use` goes through. */
     static of(): AgentBridge;
     constructor(instance: StoreInstance);
     get state(): {
@@ -27,11 +13,6 @@ export declare class AgentBridge {
     subscribe(listener: () => void): () => void;
     /** The keys one view may read right now: subscribed by a mounted component and catalogued. */
     readableKeys(viewKey?: string): string[];
-    /**
-     * The value behind a state key, stripped of what the model marks `hidden` or `secret`.
-     *
-     * The key itself has to be one the screen reads, not merely one its store owns: a component subscribing
-     * `userList` says the screen shows a user list, and says nothing about `userForm` sitting in the same store.
-     */
+    /** The masked value of a key a mounted component reads; throws for any other key. */
     read(key: string, viewKey?: string): unknown;
 }

package/types/store/agent/AgentContext.d.ts

@@ -1,13 +1,7 @@
 import type { ContextBlock, SurfaceView } from "../../vendor/use-agentic.d.ts";
 import type { StoreInstance } from "../storeInstance.d.ts";
 import type { AgentBridge } from "./AgentBridge.d.ts";
-/**
- * The akan default context for a turn: where the user is (route), what is on screen (scopes and their curated
- * resources), and which store keys the mounted components are reading (live keys). Live entries carry names and
- * small primitives only — anything bigger is one `readState` call away, masked — so the block cannot bloat with
- * what happens to be in the store. Base-store plumbing is kept off the surface by `st.use.x({ agent: false })`
- * at each call site, and the route block carries the three of them that matter.
- */
+/** A turn's default context: route, on-screen scopes, and live keys (small primitives inline, the rest by name). */
 export declare class AgentContext {
     #private;
     static of(): AgentContext;

package/types/store/agent/AgentCursor.d.ts

@@ -0,0 +1,24 @@
+/** A plain DOM element, not a React one: it outlives route changes, exists once, and is created on first use. */
+export declare class AgentCursor {
+    #private;
+    static readonly className = "akan-agent-cursor";
+    /** Matches the transform transition in `akanjs/ui/styles.css`. */
+    static readonly travelMs = 320;
+    /** Pixels below which the pointer jumps instead of gliding. */
+    static readonly travelFrom = 200;
+    /** Pixels the pointer drifts off a pressed control while it waits. */
+    static readonly driftBy = 18;
+    /** Fade delay after the last call, for a host that reports no turn boundary (one that does calls `hold`). */
+    static readonly idleMs = 1400;
+    static readonly thinkingClass = "akan-agent-cursor-thinking";
+    static readonly scrollingClass = "akan-agent-cursor-scrolling";
+    /** Travels to the control once it has stopped moving, then presses it. Resolves when the press has landed. */
+    static press(target: HTMLElement): Promise<void>;
+    static scroll(way: "up" | "down"): void;
+    /** Keeps the pointer up for as long as the turn runs, instead of for `idleMs` after the last call. */
+    static hold(): void;
+    static release(): void;
+    /** Drifts clear of the last pressed control and shows the waiting spinner; a no-op before the first press. */
+    static think(): void;
+    static hide(): void;
+}

package/types/store/agent/AgentPrompts.d.ts

@@ -1,10 +1,5 @@
 import type { PromptContent, PromptResult } from "akanjs/signal";
 import type { ChatMessage } from "../../vendor/use-agentic.d.ts";
-/**
- * The chat's slash-command parser and the bridge from prompt messages to chat turns. The app's own prompts are
- * `page().prompt()` declarations served over MCP, which a browser chat does not list; what stays here is what the
- * chat's built-in commands need.
- */
 export declare class AgentPrompts {
     #private;
     /** `/name arg1 "an arg with spaces"` — positional because a prompt's arguments are flat strings by protocol. */

package/types/store/agent/AgentVisual.d.ts

@@ -0,0 +1,25 @@
+import type { ToolActivity } from "../../vendor/use-agentic.d.ts";
+export interface AgentVisualOption {
+    /** Ring the control a call was published from, scrolling to it first when it is off screen. */
+    reveal?: boolean;
+    /** The pointer that travels to the control and presses it. */
+    cursor?: boolean;
+}
+/** Draws where an agent call lands, from tool activity: a store action cannot tell agent writes from the user's. */
+export declare class AgentVisual {
+    #private;
+    /** Past this many calls in one turn the reveal only rings, without scrolling. */
+    static readonly revealCap = 4;
+    /** How many of a form patch's fields are drawn. */
+    static readonly fieldCap = 5;
+    /** The longest a navigate call waits for its press to land. */
+    static readonly leadMs = 600;
+    /** The handlers `agentSessionOf` hands the session. `true` is every effect; an object turns one of them off. */
+    static sink(option?: boolean | AgentVisualOption): {
+        onActivity: (event: ToolActivity) => void | Promise<void>;
+        onTurn: (running: boolean) => void;
+    } | undefined;
+    /** Resets the per-turn scroll budget; the pointer is held until the turn ends. */
+    static turn(running: boolean, { cursor }?: AgentVisualOption): void;
+    static on(event: ToolActivity, { reveal, cursor }?: AgentVisualOption): void | Promise<void>;
+}

package/types/store/agent/ScreenFlash.d.ts

@@ -0,0 +1,23 @@
+/** Scrolls an element into view, then rings it once the scroll has landed. */
+export declare class ScreenFlash {
+    /** Defined in `akanjs/ui/styles.css`, so the flash follows the app's own theme tokens. */
+    static readonly ringClass = "akan-agent-highlight";
+    /** Mirrors the animation length in that stylesheet. */
+    static readonly ringMs = 2400;
+    /** The lighter, shorter ring for a control the agent just drove. */
+    static readonly actingClass = "akan-agent-acting";
+    static readonly actingMs = 1000;
+    static show(target: HTMLElement): void;
+    static reveal(target: HTMLElement): "up" | "down";
+    /** Inside the viewport with `margin` px to spare vertically, not merely intersecting it. */
+    static inView(target: HTMLElement, margin?: number): boolean;
+    /** Painted at its own centre, not just laid out — `checkVisibility` passes a control under a modal backdrop. */
+    static onTop(target: HTMLElement): boolean;
+    /** Added once the element stops moving, so it is not already fading when a smooth scroll arrives. */
+    static ring(target: HTMLElement, { className, ms }?: {
+        className?: string | undefined;
+        ms?: number | undefined;
+    }): void;
+    /** Runs `done` once the element's position holds (no browser fires a consistent scroll end); capped at 90 frames. */
+    static whenStill(target: HTMLElement, done: () => void): void;
+}

package/types/store/agent/ScreenReader.d.ts

@@ -1,37 +1,14 @@
-/**
- * Serializes what the page is rendering into compact text an agent can answer questions from: headings keep their
- * level and their anchor, links keep their href, controls keep their value and `data-akan-*` annotation. The
- * agent's own UI is marked `data-agent-ui` and skipped, so a turn never re-reads its own transcript, and a
- * password value is never read — the screen shows dots, so the DOM holds more than the user sees.
- *
- * A region the app marks `data-agent-skip` — what `Agent.Skip` renders — costs a `[skipped: <name>]` line instead
- * of its text. It stands in the output rather than vanishing because a deleted region reads as an absent one, and
- * an agent asked about a footer it never saw answers that the page has none. Naming the region as `section` reads
- * it: the marker is what the default read leaves out, not a wall.
- *
- * A heading carries `(#anchor)` whenever it opens a container that has an id or a scope path, because that is the
- * name `readScreen({ section })` and `highlight` take: printing the text without the name leaves an agent
- * guessing at a slug. For the same reason a truncated read ends with the headings below the cut instead of only
- * a character count — otherwise everything past the limit is unreachable, since nothing names it.
- */
 export interface ScreenReadOptions {
-    /**
-     * Carry each image's address as well as its caption. Off by default because a gallery is one long URL per
-     * thumbnail, which is the read's whole budget spent on the part of the screen it can say the least about.
-     */
+    /** Also print each image's address. Default false. */
     images?: boolean;
 }
+/** The rendered page as compact text for an agent; skips `data-agent-ui` and never reads a password value. */
 export declare class ScreenReader {
     #private;
     static readonly limit = 8000;
     static read(root?: HTMLElement | null, options?: ScreenReadOptions): string;
-    /**
-     * One heading's own section: the heading, then what follows it until the next heading of the same level or
-     * higher. Reads the heading's container when the heading is the only one in it — the shape a docs slide or an
-     * `<article>` has — and otherwise the heading's own following siblings.
-     */
+    /** One heading's section: its container when that holds no peer heading, else its following siblings. */
     static readFrom(heading: HTMLElement, root?: HTMLElement | null, options?: ScreenReadOptions): string;
-    /** The anchor a heading is addressable by: its own id, or the id or scope path of the container it opens. */
     static anchorOf(heading: HTMLElement): string;
     constructor({ images }?: ScreenReadOptions);
 }

package/types/store/agent/ScreenSettle.d.ts

@@ -5,18 +5,7 @@ export interface ScreenSettleOptions {
     appearMs?: number;
     timeoutMs?: number;
 }
-/**
- * Waits until the screen stops changing.
- *
- * The surface is read synchronously and the app is not: `router.push` returns while the RSC payload for the new
- * route is still in flight, and a store action that fires `void fetch.*` commits a tick later. A tool that returns
- * at either of those moments reports the screen it replaced — and the `readScreen` the agent calls next reads the
- * page the user already left.
- *
- * Quiescence rather than a framework signal, because there is no one signal: the client router hands its promise
- * to nobody, and a change may land in the store, in a refetch, or in a streamed Suspense boundary. A
- * MutationObserver sees all three, and every wait is bounded — a screen that never holds still still answers.
- */
+/** Resolves once the DOM stops mutating, always bounded; no single router or store signal says "settled". */
 export declare class ScreenSettle {
     static wait({ quietMs, appearMs, timeoutMs }?: ScreenSettleOptions): Promise<void>;
 }