akanjs 3.0.0-beta.9 → 3.0.0

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

@@ -9,6 +9,5 @@ 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

@@ -1,17 +1,5 @@
 import { type AgentFieldType, type AgentValueOf } from "./AgentValue.d.ts";
-/**
- * What a component hands over when the user points at data it is already drawing.
- *
- * The pointer and the value are declared apart on purpose. `refName`/`refId`/`path` say *what was pointed at*, and
- * travel so the agent can read it again later; `type` and `value` say *what is being shown to the model now*, and
- * the component supplies the value it already holds, so there is no round trip. They come apart because the two
- * are genuinely different in the case this exists for: a rich-text field stored as `field(Any)` is an editor
- * document at its path and a paragraph of prose to a reader, and the model wants the paragraph.
- *
- * `type` is `st.expose`'s vocabulary, not a second one. It decides what leaves the browser — a model class masks
- * by that model, a scalar passes, `Any` passes untouched — so naming a `Light` class that does not carry the field
- * is how a reference arrives empty.
- */
+/** `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;
@@ -22,11 +10,5 @@ export interface AgentReferenceInput<T extends AgentFieldType> {
     type: T;
     value: AgentValueOf<T>;
 }
-/**
- * Points the enclosing agent session at data, from anywhere that draws it.
- *
- * No-ops outside a session rather than throwing, the same call `AgentValue.publishable` makes: a card carrying a
- * reference button is mounted on whatever routes render it, and a route that happens to host no agent must not
- * lose its render over it.
- */
+/** 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;

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

@@ -1,19 +1,2 @@
-/**
- * One tool that fills several fields of a form at once, published while a component subscribes `<model>Form`.
- *
- * The per-field setters are published by the controls themselves (`useFieldTool`), which is what keeps them to
- * the fields this screen draws. This one exists for what a control cannot reach: a list, a map, an embedded
- * object — the shapes a `st.tool` argument cannot describe one control at a time — and for filling a fresh form
- * in one call. It is a patch, not a replacement, so it never clears what the person already typed.
- *
- * Its schema is every writable field of the model, because a declaration is mount-static and cannot know which
- * controls will render. The **guard** is where the screen gets its say: a plain field has to have published its
- * own setter, and a composite is waved through because its rows are written with `writeOn<Model>(path, value)`,
- * which no control can annotate — so this is the one place an agent can reach a field the screen may not show.
- *
- * The entry is a pure function of `refName`: the schema comes from the model, the guard re-reads the live surface,
- * and every `write` reaches the one store instance. So a form put on screen by a shell that subscribes it
- * (`Model.EditModal`) and by the `Template` inside it registers one declaration twice — the same description both
- * times, which is what the surface reads as interchangeable rather than as a clash an app has to suppress.
- */
+/** Publishes `fill<Model>Form`: a patch over every writable field, gated per field by the controls on screen. */
 export declare const useFormTools: (refName: string | null, write: (action: string, value: unknown) => void) => void;

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

@@ -4,24 +4,11 @@ export interface RelationFieldSource<T extends {
 }> {
     /** Read live from the store rather than closed over: `load` below changes the list mid-call. */
     read: () => DataList<T>;
-    /** Loads the options an agent never opened the dropdown to fetch. */
     load: () => Promise<unknown> | unknown;
-    /** How one option reads to a person, so the agent can match what it sees on screen. */
     label: (model: T) => string;
     disabled?: boolean;
 }
-/**
- * The two tools a relation picker owes an agent: list the documents it can pick, then pick by id.
- *
- * `FormFields` publishes no schema for a relation, and it is right not to — the form holds the whole related
- * document, so an id would need a lookup the store does not do. The picker is where that lookup lives: it holds
- * the slice list, the loader, and the label each option renders with. So the field reaches an agent from the one
- * component that can resolve it, which is the rule every other control follows — the control is the declaration.
- *
- * Listing is its own tool because loading is its own step for a person too: the options arrive when the dropdown
- * opens, and an agent never opens it. Folding the load into the setter would leave an agent guessing ids in order
- * to learn them from the refusal.
- */
+/** A relation picker's two tools: list the pickable documents (loading them first), then set by id. */
 export declare const useRelationFieldTool: <T extends {
     id: string;
 }>(onChange: unknown, { read, load, label, disabled }: RelationFieldSource<T>) => void;