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

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

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

@@ -1,34 +1,14 @@
-/**
- * Resolves a name the agent read on screen to the element it names.
- *
- * Four vocabularies, every one of them something already on the screen rather than a selector the model invented:
- * the `data-akan-action` / `data-akan-state` annotation a control carries and `readScreen` prints beside it, a
- * container — an `Agent.Zone`, a `useScreenScope` scope, or an `Agent.Skip` region named by the marker left in its
- * place — a plain element id, what a docs slide is addressed by, and, last, a **heading by its own text**.
- *
- * A heading is matched on letters and digits alone, so the slug an agent naturally writes for a heading it read
- * ("images-and-public-env") finds "Images And Public Env". That tolerance is for headings only: a heading is a
- * landmark and scrolling to the wrong one costs nothing, while two buttons reading "Save" are not the same control
- * and matching a *control* by its label would drive the wrong one.
- *
- * Nothing hidden ever resolves, by the same rule `readScreen` skips it. A collapsed panel or an off-variant
- * duplicate is not what the user is looking at, and scrolling to one flashes a ring nobody can see — which reads
- * as the tool being broken rather than as a miss. A `display: contents` wrapper does not resolve either, even
- * though the reader now reads through it: it has no box, so `scrollIntoView` has nothing to scroll to.
- */
+/** Resolves an on-screen name to a visible element. Only headings match loosely: a loose control match is unsafe. */
 export declare class ScreenTarget {
     #private;
     static container(name: string, root?: HTMLElement | null): HTMLElement | null;
     static control(name: string, root?: HTMLElement | null): HTMLElement | null;
+    static controls(name: string, root?: HTMLElement | null): HTMLElement[];
     /** Matched on letters and digits only, so a slug written for a heading still finds it. */
     static heading(text: string, root?: HTMLElement | null): HTMLElement | null;
-    /** A control first — an annotated button is the most specific match — then a container, then a heading. */
     static find(name: string, root?: HTMLElement | null): HTMLElement | null;
-    /**
-     * The names a refusal can honestly offer for a region: the scope paths, plus every heading anchor on screen.
-     * Leaving the anchors out is what let a page of twenty named sections answer "nothing carries a name".
-     */
     static containerNames(root?: HTMLElement | null): string[];
     static anchorNames(root?: HTMLElement | null): string[];
     static targetNames(root?: HTMLElement | null): string[];
+    static visible(el: HTMLElement): boolean;
 }

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

@@ -1,21 +1,17 @@
 import type { AgentRefusal } from "akanjs/signal";
+import type { SliceStateKey } from "../state.d.ts";
 import type { StoreInstance } from "../storeInstance.d.ts";
-import type { SerializedStoreState } from "./types.d.ts";
-/**
- * Every store key an in-page agent may read, derived on the client from the store the browser is already running.
- *
- * Keys only — nothing here becomes a tool. What an agent may *do* is declared where the screen declares it, with
- * `st.tool` beside the control that does the same thing for the user; a store method nobody declared is the app's
- * own vocabulary and says nothing about what this screen offers. Deriving tools from the store published the
- * bundle rather than the screen, and every lever the screen did not have was noise the model paid for.
- *
- * Reads stay store-derived because a read has to be masked and only the store declares which model masks it. Which
- * of these keys is readable at a given moment is liveness rather than this catalogue — the keys the mounted
- * components subscribe. Plumbing in the base store opts out at the call site with `{ agent: false }`.
- *
- * It is derived on the client rather than shipped from the server: the store classes are in the bundle already,
- * and a second copy over the wire is a second thing to keep in step.
- */
+export interface SerializedStoreState {
+    /** Read off the live value — stores declare no types — so a `null`-initialized key says nothing. */
+    type: "string" | "number" | "boolean" | "date" | "list" | "map" | "object" | "unknown";
+    /** The model a read of this key is masked by. */
+    refName?: string;
+    modelType?: "input" | "full" | "light" | "insight";
+    /** A `search()` or `computed()` key; writing it throws. */
+    derived: boolean;
+    role?: SliceStateKey;
+}
+/** Every store key an agent may read and the model its reads are masked by. Keys only: tools come from `st.tool`. */
 export declare class StoreCatalogue {
     #private;
     readonly state: {

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

@@ -1,30 +1,18 @@
-import type { SurfaceSource, ToolEntry } from "../../vendor/use-agentic.d.ts";
+import { AgenticSurface, type SurfaceSource, type ToolEntry } from "../../vendor/use-agentic.d.ts";
 import { AgentBridge } from "./AgentBridge.d.ts";
-/**
- * The tools every akan screen has whatever it declares: where it can go, what it is rendering, what one of the
- * store keys it reads holds, and where on screen a thing the user is being told about actually is. Everything else
- * an agent may do is a component's own `st.tool` declaration — the store contributes no actions, because a method
- * on a store class is not something the screen offers the user.
- *
- * Per zone view: a zone's `readState` reaches the keys its own subtree subscribes, and its `readScreen` and
- * `highlight` reach into its own `data-agent-zone` container rather than the whole document. A page can shadow any
- * of them by registering a hook tool of the same name — hook entries win over a source's. **That is a root-scope
- * move only**: inside a zone the hook entry is registered under its scope-prefixed name, which can never collide
- * with the bare name a source publishes, so a zone drops a built-in with the session's `builtins` option instead.
- */
+/** Every screen's built-in tools. A same-named hook tool shadows one at root scope only; a zone uses `builtins`. */
 export declare class StoreSurfaceSource implements SurfaceSource {
     #private;
-    /** Defined in `akanjs/ui/styles.css`, so the flash follows the app's own theme tokens. */
-    static readonly highlightClass = "akan-agent-highlight";
-    /** Mirrors the animation in that stylesheet: the class outlives the ring by nothing. */
-    static readonly highlightMs = 2400;
-    /**
-     * What `tools()` contributes, in the order it builds them — the list a session's `builtins` option selects from.
-     * A screen that declares a hook tool of one of these names is not in it: that entry is the screen's, not this
-     * source's, so withholding the built-ins never withholds a tool a component published on purpose.
-     */
+    /** What a session's `builtins` option selects from, in build order. */
     static readonly builtins: readonly ["navigate", "goBack", "readScreen", "readState", "highlight"];
-    /** Lazy by default: `AgentBridge.of()` walks the whole store, so it waits for the first enumeration. */
+    /** Without a bridge, `AgentBridge.of()` runs at the first `readState` call. */
     constructor(bridge?: AgentBridge);
     tools: (view?: string[]) => ToolEntry[];
 }
+export interface StoreSurface {
+    bridge: AgentBridge;
+    source: StoreSurfaceSource;
+    surface: AgenticSurface;
+}
+/** Once per runtime, lazily; never attached on the server, where one global surface would span requests. */
+export declare const ensureStoreSurface: () => StoreSurface;

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

@@ -1,11 +1,12 @@
-export { AgentAbort, AgentProgress } from "../../vendor/use-agentic.d.ts";
+export { AgentAbort, AgentProgress, type AgentProgressStep } from "../../vendor/use-agentic.d.ts";
 export * from "./AgentBridge.d.ts";
 export * from "./AgentContext.d.ts";
+export * from "./AgentCursor.d.ts";
 export * from "./AgentPrompts.d.ts";
+export * from "./AgentVisual.d.ts";
+export * from "./ScreenFlash.d.ts";
 export * from "./ScreenReader.d.ts";
 export * from "./ScreenSettle.d.ts";
 export * from "./ScreenTarget.d.ts";
 export * from "./StoreCatalogue.d.ts";
 export * from "./StoreSurfaceSource.d.ts";
-export * from "./storeSurface.d.ts";
-export * from "./types.d.ts";

package/types/store/agentic/AgentValue.d.ts

@@ -1,18 +1,8 @@
 import { type CLIENT_VALUE, type Dayjs, type EnumInstance, type FIELD_META, type GetStateObject, type PrimitiveScalar, type UnCls } from "akanjs/base";
 import { type ConstantModelRef } from "akanjs/constant";
 type AgentSingleType = typeof PrimitiveScalar | EnumInstance<string, any> | ConstantModelRef;
-/** What a readable declaration names its value as. One level of array, because a published value is one JSON shape. */
+/** A scalar, an enum, or a model — or one array level of one. */
 export type AgentFieldType = AgentSingleType | AgentSingleType[];
-/**
- * A model class resolves to its state object rather than its instance type, so a component may hand over either
- * the hydrated document or the plain data copied out of one — masking reads the model that was named, not the
- * class the value still carries.
- *
- * A scalar is recognised by `refName` and has to be matched before `FIELD_META`: `via.ts` augments the global
- * `String`, `Boolean`, `Date` and `Map` constructors with `DatabaseConstantStatics`, so those four carry field
- * metadata and would otherwise read as models. A model carries no `refName`, and `Map` — carrying neither — falls
- * through to the model branch and is refused at declaration time instead.
- */
 export type AgentValueOf<T> = T extends readonly (infer F)[] ? AgentValueOf<F>[] : T extends {
     refName: "Any";
 } ? unknown : T extends EnumInstance<string, infer V> ? V : T extends DateConstructor ? Dayjs | Date | string : T extends {
@@ -23,21 +13,11 @@ export type AgentValueOf<T> = T extends readonly (infer F)[] ? AgentValueOf<F>[]
 } ? GetStateObject<UnCls<T>> : T extends {
     [CLIENT_VALUE]: infer V;
 } ? V : unknown;
-/**
- * Turns a declared type into what an agent may read of a value of that type.
- *
- * The type is the whole declaration: it typechecks what the component hands over, and it decides how the value is
- * rendered — a model class masks by that model, a `Date` leaves as an ISO string, a scalar passes. `Any` is the
- * escape hatch and passes the value untouched, so a payload nobody modeled stays publishable and the caller owns
- * whether it is JSON and whether it is worth its tokens.
- */
+/** Renders a value by its declared type: a model masks, a Date is ISO, an agent-faced primitive reads, Any passes. */
 export declare class AgentValue {
     #private;
     static serialize(type: AgentFieldType, value: unknown): unknown;
-    /**
-     * Reports an unreadable type the way `st.tool` reports an undescribable argument — on the console, and the
-     * declaration goes unpublished. Throwing would cost the route its server render over an agent-tooling mistake.
-     */
+    /** Logs and returns false for an unreadable type; throwing would cost the route its server render. */
     static publishable(owner: string, type: AgentFieldType): boolean;
 }
 export {};

package/types/store/agentic/StExposeBuilder.d.ts

@@ -3,19 +3,10 @@ export interface StExposeMeta {
     /** `false` keeps the key out of post-call diff reports — for values that change on their own every second. */
     report?: boolean;
 }
-/**
- * A read-only value past its description, waiting for the value itself. `.value()` is the one hook.
- *
- * The declared type is what makes the read safe: it typechecks what the component hands over and it decides how
- * the value is rendered, so a model's `hidden` and `secret` fields are stripped by the model that was named
- * rather than by whatever class the value still happens to carry.
- */
+/** `.value()` is the hook; the declared type, not the value's class, decides what the read masks. */
 export declare class StExposeBuilder<T extends AgentFieldType> {
     #private;
     constructor(name: string | null, type: T, desc: string, meta?: StExposeMeta);
-    /**
-     * A thunk is read when the agent reads, which is the difference that matters for a value assembled out of a ref
-     * the children fill in after this render — computing it here would publish whatever was there before they ran.
-     */
+    /** A thunk is evaluated when the agent reads, not at render. */
     value(value: AgentValueOf<T> | (() => AgentValueOf<T>) | null | undefined): void;
 }

package/types/store/agentic/StExposeDraft.d.ts

@@ -1,11 +1,5 @@
 import type { AgentFieldType } from "./AgentValue.d.ts";
 import { StExposeBuilder, type StExposeMeta } from "./StExposeBuilder.d.ts";
-/**
- * A readable value before it has said what it is: `st.expose("x", ID).desc("…")`.
- *
- * A falsy name declares nothing and publishes nothing, so a component whose publication is conditional keeps a
- * constant hook count instead of branching around the chain.
- */
 export declare class StExposeDraft<T extends AgentFieldType> {
     #private;
     constructor(name: string | null, type: T, meta?: StExposeMeta);

package/types/store/agentic/StStateBuilder.d.ts

@@ -6,13 +6,7 @@ export interface StStateMeta {
     /** Publishes a `set<Name>` tool writing the type this state declares. Read-only without it. */
     set?: boolean;
 }
-/**
- * Local state past its description, waiting for its initial value. `.init()` is the one hook and returns what
- * `useState` returns.
- *
- * The declared type does both halves: it renders the read, and — with `set` — it is the schema of the setter tool
- * an agent writes through. A type nothing can describe costs the write, not the read and not the render.
- */
+/** `.init()` is the hook and returns what `useState` returns; an undescribable type costs only the setter tool. */
 export declare class StStateBuilder<T extends AgentFieldType> {
     #private;
     constructor(name: string | null, type: T, desc: string, meta?: StStateMeta);

package/types/store/agentic/StStateDraft.d.ts

@@ -1,10 +1,5 @@
 import type { AgentFieldType } from "./AgentValue.d.ts";
 import { StStateBuilder, type StStateMeta } from "./StStateBuilder.d.ts";
-/**
- * Local state before it has said what it is: `st.useState("tab", String, { set: true }).desc("…")`.
- *
- * A falsy name keeps the state and publishes nothing, so a conditional surface never changes the hook count.
- */
 export declare class StStateDraft<T extends AgentFieldType> {
     #private;
     constructor(name: string | null, type: T, meta?: StStateMeta);

package/types/store/agentic/StToolBuilder.d.ts

@@ -1,22 +1,19 @@
 import { type CLIENT_VALUE, type EnumInstance } from "akanjs/base";
 import type { ParamFieldType } from "akanjs/constant";
+import type { ReactNode } from "react";
 import { type JsonSchema, type ToolConfirm, type ToolGuard } from "../../vendor/use-agentic.d.ts";
+/** `submit`'s value is what the model reads back; the first of the two calls settles the card. */
+export interface StToolCardControl {
+    submit: (value: unknown) => void;
+    cancel: (reason?: string) => void;
+}
 export interface StToolMeta {
-    /**
-     * Whether the call has to be waited out before what it did to the screen is reported back to the model. `false`
-     * is a read that returns what is already there; the default waits, because a write may still be landing when
-     * `exec` resolves and a report taken then describes the screen one tick before the call.
-     */
+    /** Default true: the screen is waited out before the call reports; `false` for a read of what is already there. */
     settle?: boolean;
     confirm?: ToolConfirm;
     guard?: ToolGuard;
 }
-/**
- * What one argument may be: a scalar, an enum, or **one** array level of either. The array level is here because
- * `fill<Model>Form` already describes exactly that for a form field, so the same shape reaching an agent through a
- * form and not through a component tool was an oversight rather than a boundary — and a tool that cannot say
- * "a list of these" says it in prose instead, which is a format the app then owns a parser for.
- */
+/** A scalar, an enum, or one array level of either. */
 export type StToolArgType = ParamFieldType | readonly [ParamFieldType];
 interface StToolArg {
     name: string;
@@ -31,23 +28,10 @@ export interface StToolArgOption<V> {
 type ScalarValue<T> = T extends EnumInstance<string, infer V> ? V : T extends {
     [CLIENT_VALUE]: infer V;
 } ? V : never;
-/** What one element carries, which is the whole argument unless it is an array. `oneOf` narrows this one. */
 type ElementValue<T> = T extends readonly [infer E] ? ScalarValue<E> : ScalarValue<T>;
 type ArgValue<T> = T extends readonly [unknown] ? ElementValue<T>[] : ElementValue<T>;
 type NarrowedValue<T, V> = T extends readonly [unknown] ? V[] : V;
-/**
- * A component tool past its description: `.arg()` for what the caller must pass, `.opt()` for what it may, and
- * one `.exec()`.
- *
- * This is not A12's rejected store-action builder — a store action derives its schema from the endpoint it is
- * named after, while a component tool exists nowhere else, so declaring is the only source there is. `.arg()` and
- * `.opt()` only accumulate data; `.exec()` is the one hook, so the chain must complete in one unconditional
- * statement.
- *
- * A falsy name declares the tool without publishing it: the callable still works for the click that a person
- * makes, and nothing reaches the agent. That is how a conditional surface stays writable at all — `.exec()` is a
- * hook, so a component can never skip the declaration, only the publication.
- */
+/** `.arg()`/`.opt()` only accumulate; `.exec()` is the hook. A falsy name declares the tool without publishing it. */
 export declare class StToolBuilder<Args extends unknown[] = []> {
     #private;
     constructor(name: string | null, desc: string, meta?: StToolMeta, args?: StToolArg[]);
@@ -55,22 +39,15 @@ export declare class StToolBuilder<Args extends unknown[] = []> {
     arg<T extends StToolArgType, const V extends ElementValue<T>>(name: string, type: T, option: StToolArgOption<V>): StToolBuilder<[...Args, NarrowedValue<T, V>]>;
     opt<T extends StToolArgType>(name: string, type: T): StToolBuilder<[...Args, ArgValue<T> | null]>;
     opt<T extends StToolArgType, const V extends ElementValue<T>>(name: string, type: T, option: StToolArgOption<V>): StToolBuilder<[...Args, NarrowedValue<T, V> | null]>;
-    /**
-     * The only hook in the chain. `run`, `guard`, and `confirm` stay always-latest, and so does the **name** —
-     * `desc` and `args` are read once per name because a component that renders once per row declares one tool
-     * many times and only its own arguments differ.
-     *
-     * The name has to follow the render, because withholding it is how a conditional surface is written
-     * (`st.tool(canRemove && "removeX")`). Frozen on the first render it failed both ways: a control that appeared
-     * later never published, and — worse — one that went away stayed published, leaving an agent a lever the screen
-     * no longer offers.
-     */
+    /** The hook. `run`/`guard`/`confirm` and the name follow every render; `desc`/`args` are read once per name. */
     exec(run: (...args: Args) => unknown): (...args: Args) => Promise<void>;
+    /** A tool the user answers with a chat card. Args are checked in the guard, before the card parks; no `confirm`. */
+    card(render: (control: StToolCardControl, ...args: Args) => ReactNode): void;
     static parametersOf(args: StToolArg[]): JsonSchema | undefined;
-    /** Scalars and enums only — the value arrives as JSON from a model, so a class instance has no way in. */
+    /** Scalars and enums only (a value arrives as JSON); throws for anything else. */
     static schemaOf(type: ParamFieldType): JsonSchema;
     static positionalOf(toolName: string, args: StToolArg[], named: Record<string, unknown>): unknown[];
-    /** What `AgentBridge` does for endpoint arguments, for a component tool's own — nothing on the wire enforces the published schema. */
+    /** Nothing on the wire enforces the published schema, so every argument value is checked here. */
     static checkedValue(toolName: string, argName: string, type: StToolArgType, value: unknown, oneOf?: readonly (string | number)[]): unknown;
 }
 export {};

package/types/store/agentic/StToolDraft.d.ts

@@ -1,11 +1,4 @@
 import { StToolBuilder, type StToolMeta } from "./StToolBuilder.d.ts";
-/**
- * A component tool before it has said what it does: `st.tool("x", { confirm }).desc("…")`.
- *
- * The description is the step that has to happen, so it is the one the type insists on. A model picks a tool by
- * that sentence and by nothing else, and the surface reads it a second time to tell fifty rows publishing one
- * interchangeable verb from two components that happened to pick the same name.
- */
 export declare class StToolDraft {
     #private;
     constructor(name: string | null, meta?: StToolMeta);

package/types/store/agentic/attachAgentic.d.ts

@@ -6,19 +6,11 @@ import { StStateDraft } from "./StStateDraft.d.ts";
 import type { StToolMeta } from "./StToolBuilder.d.ts";
 import { StToolDraft } from "./StToolDraft.d.ts";
 export interface StAgentic {
-    /**
-     * Local state the in-page agent can read: `.desc()` then `.init()`, which is the hook and returns what
-     * `useState` returns. Writes need `set: true` and go through the generated `set<Name>` tool.
-     */
+    /** Agent-readable local state: `.desc()` then `.init()` (the hook). Agent writes need `set: true`. */
     useState: <T extends AgentFieldType>(name: string | null, type: T, meta?: StStateMeta) => StStateDraft<T>;
     /** A read-only derived value the agent can read while the component is mounted: `.desc()` then `.value()`. */
     expose: <T extends AgentFieldType>(name: string | null, type: T, meta?: StExposeMeta) => StExposeDraft<T>;
-    /**
-     * A component tool: `.desc()`, then `.arg()` / `.opt()`, chained onto one `.exec()` hook.
-     *
-     * A falsy name declares the tool without publishing it — the callable still drives the click a person makes.
-     * Every one of these ends in a hook, so a conditional surface withholds the name rather than skipping the chain.
-     */
+    /** `.desc()`, `.arg()`/`.opt()`, then the hook `.exec()` or `.card()`. A falsy name declares without publishing. */
     tool: (name: string | null, meta?: StToolMeta) => StToolDraft;
 }
 /** Idempotent — `StoreRegistry.build` runs once per merged root, always onto the one instance. */

package/types/store/agentic/formFields.d.ts

@@ -5,61 +5,25 @@ export interface FormFieldRef {
     key: string;
     field: ConstantField;
 }
-/**
- * What a form's fields look like to an agent: which setter action belongs to which field, what shape a value for
- * it has, and whether a value it sent is one that field accepts.
- *
- * The action-to-field map is built **forward** from `formSetterNames`, never by taking a name apart:
- * `set(.+)On(.+)` has more than one reading whenever a field or a model name contains `On`.
- */
 export declare class FormFields {
     #private;
-    /** Every `set<Field>On<Model>` this client knows, against the field it writes. */
     static ref(action: string): FormFieldRef | null;
-    /** The fields of a model's form an agent may write, with the setter each one answers to. */
     static patchable(refName: string): {
         key: string;
         action: string;
         field: ConstantField;
         schema: JsonSchema;
     }[];
-    /**
-     * The shape a value for one field has, or null when there is nothing honest to publish.
-     *
-     * A relation is left out rather than described as its id: the form holds the whole related document, so writing
-     * an id would need a lookup the store does not do — a relation is picked or uploaded, never typed. `hidden`,
-     * `secret`, and `resolve` are out at every level, the first two because their reads are masked and a writer for
-     * one would be the door around that, the last because it is computed and has no setter at all.
-     */
+    /** Null for a relation (picked, never typed) and for hidden/secret/resolve, whose writer would bypass the mask. */
     static schema(field: ConstantField, depth?: number): JsonSchema | null;
-    /**
-     * The value the store should receive, or a throw naming what was wrong with the one that arrived.
-     *
-     * `additionalProperties: false` travels in the published schema and nothing on the wire enforces it, so an
-     * undeclared key is reported here rather than written into the form and shipped on the next submit.
-     */
+    /** Throws on a bad value: nothing on the wire enforces the published schema, `additionalProperties` included. */
     static checked(action: string, path: string, field: ConstantField, value: unknown, depth?: number): unknown;
-    /**
-     * The tool that lists what a field can be set to. One name across both picker hooks on purpose: a form draws a
-     * relation picker and an upload control side by side, and a model that learned this name on one field spells it
-     * the same on the next. Two names one word apart would cost a failed call to learn.
-     */
+    /** Shared by both picker hooks on purpose, so a model that learned it on one field spells it the same on the next. */
     static optionsToolName(refName: string, key: string): string;
-    /**
-     * The database model a relation field points at, or null for anything else — a primitive, an enum, a scalar.
-     * It is the question both picker hooks ask of a field `schema` refused, and the refusal alone does not answer
-     * it: a `hidden` scalar and an undescribable one are refused too, and neither is something to pick.
-     */
+    /** The database model a relation field points at, else null. */
     static relationOf(field: ConstantField): string | null;
     /** A field no annotated control can ever name: its rows are written through `writeOn<Model>(path, value)`. */
     static isComposite(field: ConstantField): boolean;
-    /**
-     * The embedded model an array field's rows are, or null for every other field.
-     *
-     * This is the one shape where writing the whole array is a hazard rather than an inconvenience: the agent has to
-     * echo every row it is *not* changing, `checked` validates types and not values, so one mistyped row it was never
-     * asked to touch is written silently. A relation array is excluded — its rows travel as ids, which are the payload
-     * and are refused by name when wrong — and so is an array of primitives, for the same reason.
-     */
+    /** The embedded model of an array field's rows, else null — relation and primitive arrays included. */
     static rowModelOf(field: ConstantField): (new (...args: never[]) => unknown) | null;
 }

package/types/store/agentic/index.d.ts

@@ -7,7 +7,7 @@ export * from "./StStateBuilder.d.ts";
 export * from "./StStateDraft.d.ts";
 export * from "./StToolBuilder.d.ts";
 export * from "./StToolDraft.d.ts";
+export * from "./useAgentReference.d.ts";
 export * from "./useFieldTool.d.ts";
-export * from "./useFileFieldTool.d.ts";
 export * from "./useFormTools.d.ts";
 export * from "./useRelationFieldTool.d.ts";

package/types/store/agentic/useAgentReference.d.ts

@@ -0,0 +1,14 @@
+import { type AgentFieldType, type AgentValueOf } from "./AgentValue.d.ts";
+/** `refName`/`refId`/`path` say what was pointed at; `value` is what the model is shown now, masked by `type`. */
+export interface AgentReferenceInput<T extends AgentFieldType> {
+    refName: string;
+    refId: string;
+    /** What the chip draws and what the token in the draft spells. */
+    label: string;
+    /** A dotted path into the document, in `pathSet`'s vocabulary. Absent points at the whole of it. */
+    path?: string;
+    type: T;
+    value: AgentValueOf<T>;
+}
+/** Stages a reference in the enclosing agent session; outside one it warns and does nothing. */
+export declare const useAgentReference: () => <T extends AgentFieldType>({ type, value, ...pointer }: AgentReferenceInput<T>) => void;

package/types/store/agentic/useFieldTool.d.ts

@@ -1,22 +1,25 @@
 export interface FieldToolOptions {
-    /** The control's own normalizer. Applied to the agent's write exactly as it is to the person's typing. */
+    /** Applied to the agent's write exactly as to the person's typing. */
     transform?: unknown;
-    /** True while the person cannot use the control. Publishes nothing, so the agent gets no lever the screen withholds. */
+    /** While true, nothing is published. */
     disabled?: boolean;
-    /** The person can drag entries into a new order, so `move<Field>On<Model>` is a lever the screen really has. */
+    /** Also publishes `move<Field>On<Model>`, for a list the person can drag. */
     sortable?: boolean;
 }
-/**
- * Publishes the setter a form control is already holding, for exactly as long as the control is usable.
- *
- * The control is the declaration — the same rule the rest of the surface follows. A handler passed by reference
- * (`onChange={st.do.setTitleOnTask}`) names the field it writes, so the tool and the person press one function;
- * an inline arrow names nothing and publishes nothing, which is the existing `data-akan-action` rule with
- * consequences. Publishing from the form's subscription instead would offer every field of the model, including
- * the ones this template draws no control for.
- *
- * `disabled` withdraws the tool for the same reason the whole surface is declaration-only: a field the person
- * cannot type into is not one an agent may write in their place. It also closes the field to `fill<Model>Form`,
- * whose guard offers only what a control published — so one gate covers both writers.
- */
+/** Publishes a by-reference setter while its control is usable; `disabled` also closes it to `fill<Model>Form`. */
 export declare const useFieldTool: (onChange: unknown, { transform, disabled, sortable }?: FieldToolOptions) => void;
+export interface FileFieldSource<T extends {
+    id: string;
+}> {
+    /** Read live on every call. Omitted publishes nothing. */
+    read?: () => readonly T[];
+    label: (file: T) => string;
+    /** The list's cap; nothing derives it from the field, so without it the limit is only the server's `Err`. */
+    max?: number;
+    min?: number;
+    disabled?: boolean;
+}
+/** Lists offered files and sets the field by id; `add`/`sub` are the only way to keep files `read` does not offer. */
+export declare const useFileFieldTool: <T extends {
+    id: string;
+}>(onChange: unknown, { read, label, max, min, disabled }: FileFieldSource<T>) => void;