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

package/types/ui/Agent/Chat.d.ts

@@ -1,97 +1,64 @@
+import { type AgentVisualOption } from "akanjs/store";
 import { type ReactNode } from "react";
 import { type AgentRunner, type AgentSessionOptions, type CompactOptions, type SessionHistory } from "../../vendor/use-agentic.d.ts";
+import { type BuiltinOption, type PersistOption } from "./agentSessionOf.d.ts";
 import type { AttachLimits, AttachReader } from "./attachment.d.ts";
-import type { PersistOption } from "./sessionHistory.d.ts";
-import type { BuiltinOption } from "./sessionView.d.ts";
+import { type ReferenceSource } from "./useReferenceMenu.d.ts";
 import type { VoiceEngine } from "./voice.d.ts";
 export interface ChatProps {
-    /** Reaches whichever surface is showing — the launcher while closed, the panel while open. */
+    /** Applied to the launcher while closed and to the panel while open. */
     className?: string;
     title?: string;
-    /** App-global framing. Route-scoped guidance layers on it through mounted `Agent.Guide`s. */
+    /** App-global framing; route-scoped `Agent.Guide`s layer on it. */
     instructions?: string;
-    /** Swap the transport; the default drives the app's `runAgentTurn` endpoint. */
+    /** Defaults to the app's `runAgentTurn` endpoint. */
     runner?: AgentRunner;
     maxTurns?: number;
-    /**
-     * When the conversation summarizes itself to stay inside the model's window — `at` estimated tokens, `keep`
-     * messages left verbatim below the summary. Tune it per provider; `{ at: 0 }` turns it off.
-     */
+    /** Summarizes past `at` estimated tokens or near the server's context window, keeping `keep` messages verbatim;
+     *  `{ at: Infinity }` leaves only the window guard, `{ at: 0 }` turns it all off. */
     compact?: CompactOptions;
-    /**
-     * Which of the runtime's own tools this chat's agent gets — all of them by default, `false` none, an array
-     * exactly the ones it names. A chat that must not leave the screen it is on drops `navigate` and `goBack`.
-     */
+    /** Every runtime tool by default, `false` none, an array exactly the ones it names. */
     builtins?: BuiltinOption;
-    /** Called after a compaction replaced messages with one summary — where a host syncs its own watermark. */
+    /** Called after a compaction replaced messages with one summary. */
     onCompact?: AgentSessionOptions["onCompact"];
     defaultOpen?: boolean;
-    /**
-     * Controlled open state. Pass it with `onOpenChange` to drive the panel from the app's own control — a header
-     * button, a menu item — instead of the built-in launcher. Left off, the panel owns the state as before.
-     */
+    /** Controlled open state, paired with `onOpenChange`; left off, the panel owns it. */
     open?: boolean;
-    /**
-     * Left off while `open` is controlled, the panel cannot close itself — so it draws **no close button** rather
-     * than an inert one. That is the shape of a fixed panel with nowhere to close to, and it is also what keeps a
-     * controlled chat assemblable by a server component, since this is the only prop here that is a function.
-     */
+    /** Left off while `open` is controlled, the panel draws no close button. */
     onOpenChange?: (open: boolean) => void;
-    /** `false` draws no launcher, for an app that opens the panel from a control of its own. */
+    /** On by default; `false` draws nothing, `{ cursor: false }` / `{ reveal: false }` turn one effect off. */
+    visual?: boolean | AgentVisualOption;
+    /** `false` draws no launcher. */
     launcher?: boolean;
-    /**
-     * Keeps the transcript across reloads — sessionStorage by default, `{ storage: "local" }` to outlive the tab, or
-     * a `SessionHistory` of the app's own to keep it anywhere else, a server included.
-     *
-     * Ignored, like every session option above it, when an enclosing `Agent.Zone` or `AgentProvider` already holds a
-     * session: this chat then binds to that one, and the options belong to whoever built it.
-     */
+    /** sessionStorage by default, `{ storage: "local" }` to outlive the tab, or an app `SessionHistory`. Ignored, like
+     *  every session option above, when an enclosing `Agent.Zone` or `AgentProvider` already holds a session. */
     persist?: PersistOption | SessionHistory;
-    /** Renders in the page flow instead of floating above it — a zone chat that lives inside its own section. */
+    /** Renders in the page flow instead of floating above it. */
     inline?: boolean;
-    /** `false` gives the browser its own Cmd/Ctrl+L back, for an app whose shell already spends that chord. */
+    /** `false` leaves Cmd/Ctrl+L to the browser. */
     shortcut?: boolean;
-    /** One surface each, where `className` reaches both. */
     launcherClassName?: string;
     panelClassName?: string;
-    /** Shown in place of the intro line while the transcript is empty — where starter questions go. */
+    /** Shown in place of the intro line while the transcript is empty. */
     intro?: ReactNode;
     /** Extra header controls, left of the built-in clear and close buttons. */
     header?: ReactNode;
-    /**
-     * `false` draws no header bar at all — for an `inline` chat inside a panel the app already titles. The extra
-     * `header` controls go with it, and the clear action stays reachable as the `/new` command.
-     */
+    /** `false` draws no header bar, `header` included; clearing stays reachable as `/new`. */
     chrome?: boolean;
-    /** The composer's opening text, read once at mount — where a `?prompt=` lands without sending it. */
+    /** The composer's opening text, read once at mount. */
     defaultDraft?: string;
-    /**
-     * Reads a file the user attached into an attachment, or answers `null` to leave it to the built-in reader
-     * (images as bytes, text as text). This is where an app puts what needs a parser — a PDF's text, a spreadsheet's
-     * cells — since the framework carries attachments but depends on nothing that can extract one. It runs before
-     * the built-in, so it can also replace how an image is prepared.
-     */
+    /** Runs before the built-in reader, which `null` falls back to. The provider fetches a `url` itself, so answer
+     *  `data` too when it cannot reach it — `data` is then what is sent and `url` only draws the chip. */
     attach?: AttachReader;
-    /**
-     * Raises or lowers what the composer accepts — per file, per message, and how many. The defaults are what one
-     * turn's JSON safely carries to a conservative provider; an app pointed at a larger request limit, or one whose
-     * `attach` uploads and answers a `url`, has no reason to inherit them.
-     */
+    /** What the composer's `@` menu can point at, one entry per document kind. */
+    reference?: readonly ReferenceSource[];
+    /** Draws `@` pointers as names; on when `reference` is set, `false` keeps the plain textarea. */
+    mentions?: boolean;
+    /** Overrides the per-file, per-message and count ceilings on attachments. */
     attachLimits?: AttachLimits;
-    /**
-     * Speech in and out. The engine listens and speaks; this component decides when — a press-to-talk microphone
-     * whose transcript lands in the composer for the user to correct, and a reply read aloud **only when the ask
-     * itself came in by voice**, so a typed question never turns the speakers on.
-     */
+    /** Speech in and out; a reply is read aloud only when the ask came in by voice. */
     voice?: VoiceEngine;
 }
-/**
- * The user-facing half of the in-page agent: one floating chat wired to the same surface the dock inspects.
- * The conversation loop runs in this browser session — every tool call executes here, gated by the approval
- * card — and the session lives in a ref, so it survives reopening the panel and dies with the page unless
- * `persist` keeps it. An enclosing AgentProvider's session wins, which is how an app isolates a surface or swaps
- * the loop while keeping this UI.
- */
-export declare const DefaultChat: ({ className, title, instructions, runner, maxTurns, compact, builtins, onCompact, defaultOpen, open: openProp, onOpenChange, launcher, persist, inline, shortcut, launcherClassName, panelClassName, intro, header, chrome, defaultDraft, attach, attachLimits, voice, }: ChatProps) => ReactNode;
+export declare const DefaultChat: ({ className, title, instructions, runner, maxTurns, compact, builtins, onCompact, defaultOpen, open: openProp, onOpenChange, launcher, visual, persist, inline, shortcut, launcherClassName, panelClassName, intro, header, chrome, defaultDraft, attach, attachLimits, reference, mentions, voice, }: ChatProps) => ReactNode;
 declare const _default: import("react").ComponentType<ChatProps>;
 export default _default;

package/types/ui/Agent/ChatCommands.d.ts

@@ -5,28 +5,18 @@ export interface ChatCommandContext {
 }
 export interface ChatCommand {
     name: string;
-    /** Accepted but not listed: one row per command, so the menu names each thing once. */
+    /** Accepted but not listed in the menu. */
     aliases?: string[];
     description: string;
     run: (context: ChatCommandContext) => void | Promise<void>;
 }
-/**
- * The chat's own slash commands — the whole `/` menu, since an app's prompts are `page().prompt()` declarations
- * served over MCP and not listed by a browser chat.
- *
- * Output goes through `session.note`, never `send`: a command is answered by this browser, so its text belongs in
- * the transcript the user reads and nowhere in the history the model reads.
- */
+/** Output goes through `session.note`, never `send`: the user reads it, the model never does. */
 export declare class ChatCommands {
     #private;
     static list(l: (key: string) => string): ChatCommand[];
     static find(name: string, l: (key: string) => string): ChatCommand | null;
-    /** A command is user-typed, so a failure inside one lands in the transcript instead of at the page. */
+    /** A failure is reported into the transcript instead of thrown. */
     static run(command: ChatCommand, context: ChatCommandContext): Promise<void>;
-    /**
-     * The conversation as markdown. The relay is stateless and the transcript lives only in this browser, so an
-     * export is the only way a wrong answer can reach whoever could fix it — which is why the header carries where
-     * and when it happened. Local notes are left out: they are this chat talking to itself.
-     */
+    /** The conversation as markdown, local notes left out. */
     static transcriptOf(messages: readonly ChatMessage[], where?: string): string;
 }

package/types/ui/Agent/Composer.d.ts

@@ -1,13 +1,21 @@
 import { type KeyboardEvent, type RefObject } from "react";
-import type { AgentSession, MessageAttachment } from "../../vendor/use-agentic.d.ts";
+import type { AgentSession, MessageAttachment, MessageReference } from "../../vendor/use-agentic.d.ts";
+/** Every offset is into the draft string, tokens included. */
+export interface ComposerHandle {
+    focus: () => void;
+    caret: () => number | null;
+    setCaret: (at: number) => void;
+}
 export interface ComposerProps {
     className?: string;
     session: AgentSession;
     draft: string;
     attached: readonly MessageAttachment[];
-    /** Files still being read. An `attach` that uploads takes seconds, and a panel that shows nothing looks broken. */
+    /** What the draft's `@[…](mention:…)` tokens point at; the text carries them, chips only show them. */
+    references?: readonly MessageReference[];
+    /** Files still being read. */
     pending?: number;
-    /** Absent when the screen cannot listen — the same rule as publishing no tool for a control that is not drawn. */
+    /** Absent when the screen cannot listen. */
     mic?: {
         listening: boolean;
         onToggle: () => void;
@@ -16,10 +24,15 @@ export interface ComposerProps {
     onKeyDown: (event: KeyboardEvent<HTMLTextAreaElement>) => void;
     onFiles: (files: File[]) => void;
     onRemoveFile: (idx: number) => void;
+    /** Keyed on `refName/refId#path`, not on a row index. */
+    onRemoveReference?: (key: string) => void;
     onSend: () => void;
     onStop: () => void;
     inputRef?: RefObject<HTMLTextAreaElement | null>;
+    /** Draws each `@` pointer as its name; set only when the chat has `reference` sources. */
+    mentions?: boolean;
+    /** Filled by whichever input is drawn. An override that draws its own textarea leaves it null and `inputRef` answers. */
+    handleRef?: RefObject<ComposerHandle | null>;
 }
-/** What the user writes with: the staged files above, and the controls that send or stop below them. */
-export declare const DefaultComposer: ({ className, session, draft, attached, pending, mic, onDraft, onKeyDown, onFiles, onRemoveFile, onSend, onStop, inputRef, }: ComposerProps) => import("react/jsx-runtime").JSX.Element;
+export declare const DefaultComposer: ({ className, session, draft, attached, references, pending, mic, onDraft, onKeyDown, onFiles, onRemoveFile, onRemoveReference, onSend, onStop, inputRef, mentions, handleRef, }: ComposerProps) => import("react/jsx-runtime").JSX.Element;
 export declare const Composer: import("react").ComponentType<ComposerProps>;

package/types/ui/Agent/Dock.d.ts

@@ -1,17 +1,45 @@
-import { type AgentBridge } from "akanjs/store";
-import { AgenticSurface } from "../../vendor/use-agentic.d.ts";
+import { type AgentBridge, type SerializedStoreState } from "akanjs/store";
+import { type ReactNode } from "react";
+import { type AgentCall, AgenticSurface, type PublishedTool, type SurfaceView } from "../../vendor/use-agentic.d.ts";
 export interface DockProps {
     className?: string;
-    /** The store keys and their masking. Defaults to the app's own. */
+    /** Defaults to the app's own. */
     bridge?: AgentBridge;
-    /** Where the declared tools live. Pass a zone's own to inspect it; defaults to the whole screen's. */
+    /** Defaults to the whole screen's; pass a zone's own to inspect it. */
     surface?: AgenticSurface;
     open?: boolean;
 }
-/**
- * The in-page surface of the agent: what this screen declared an agent may do, what it may read, and what it has
- * done. Tools come from the surface rather than from the store, because a tool exists only where a component
- * declared one — the dock is the way to see that this screen published what its author thought it did, which is
- * the one thing no amount of reading the source answers. Renders nothing on `AKAN_PUBLIC_ENV=main`.
- */
 export declare const Dock: ({ className, bridge, surface, open }: DockProps) => import("react/jsx-runtime").JSX.Element | null;
+interface SectionProps {
+    className?: string;
+    title: string;
+    count: number;
+    children: ReactNode;
+    open?: boolean;
+}
+export declare function Section({ className, title, count, children, open }: SectionProps): import("react/jsx-runtime").JSX.Element;
+interface TranscriptProps {
+    className?: string;
+    calls: readonly AgentCall[];
+}
+export declare function Transcript({ className, calls }: TranscriptProps): import("react/jsx-runtime").JSX.Element;
+interface ToolProps {
+    className?: string;
+    surface: SurfaceView;
+    tool: PublishedTool;
+    onRun: () => void;
+}
+export declare function Tool({ className, surface, tool, onRun }: ToolProps): import("react/jsx-runtime").JSX.Element;
+interface StateKeyProps {
+    className?: string;
+    bridge: AgentBridge;
+    name: string;
+    entry: SerializedStoreState;
+    live?: boolean;
+}
+export declare function StateKey({ className, bridge, name, entry, live }: StateKeyProps): import("react/jsx-runtime").JSX.Element;
+interface ContextProps {
+    className?: string;
+}
+export declare function Context({ className }: ContextProps): import("react/jsx-runtime").JSX.Element | null;
+export {};

package/types/ui/Agent/Guide.d.ts

@@ -1,9 +1,5 @@
 export interface GuideProps {
     instructions: string;
 }
-/**
- * Standing agent guidance scoped to a route subtree: render it from a `_layout.tsx` or a page and the text joins
- * the turn's instructions while that subtree is mounted. Nesting layers naturally — each mounted Guide contributes
- * its block, and navigating away withdraws it. Renders nothing.
- */
+/** Joins the turn's instructions while mounted; renders nothing. */
 export declare const Guide: ({ instructions }: GuideProps) => null;

package/types/ui/Agent/History.d.ts

@@ -3,24 +3,7 @@ export interface HistoryProps {
     load: SessionHistory["load"];
     save: SessionHistory["save"];
     clear: SessionHistory["clear"];
-    /** Where a host with its own server-side summary moves its watermark — see `onCompact` on the session options. */
     onCompact?: AgentSessionOptions["onCompact"];
 }
-/**
- * Puts the enclosing zone's transcript wherever the app keeps it, as a mounted component rather than a prop.
- *
- * `persist` does the same thing and has to be passed to whoever builds the session, which makes every ancestor up
- * to that point a client component — a function cannot cross the server/client boundary as a prop. Mounted here
- * instead, the only client module an app needs is this leaf, and `Agent.Zone` and the chat inside it can be
- * assembled by a server component. Same shape as `Agent.Guide`, and it renders nothing.
- *
- * Restoring follows the session's one rule: it lands only while nothing has happened to the conversation yet, so
- * mounting with the zone restores and mounting later saves from there on.
- *
- * The store is attached for exactly as long as this is mounted. A zone's own session dies with it, so that is the
- * whole story there — but a session the app handed in (`Agent.Zone`'s `session` prop) outlives this, and its
- * saving stops on unmount: nothing is claiming to persist it any more, and a component that is gone should not
- * still be writing. A host that wants the store to outlive the view calls `session.setHistory` itself, which also
- * takes the slot, so a later unmount here leaves it alone.
- */
+/** Attaches the enclosing session's history while mounted; restoring lands only before the conversation started. */
 export declare const History: ({ load, save, clear, onCompact }: HistoryProps) => null;

package/types/ui/Agent/Launcher.d.ts

@@ -2,12 +2,12 @@ import type { Ref } from "react";
 export interface LauncherProps {
     className?: string;
     label: string;
-    /** The chord that opens the chat, shown on hover. Null until the platform is known, which needs the client. */
+    /** Shown on hover; null until the client knows the platform. */
     hotkey?: {
         label: string;
         keys: string;
     } | null;
-    /** Messages that arrived while the panel was closed, so a finished turn is not silent. */
+    /** Messages that arrived while the panel was closed. */
     unread: number;
     onOpen: () => void;
     buttonRef?: Ref<HTMLButtonElement>;

package/types/ui/Agent/Markdown.d.ts

@@ -1,6 +1,6 @@
 export interface CodeProps {
     className?: string;
-    /** The fence's info word, kept so a highlighter bound to this slot knows what it was handed. */
+    /** The fence's info word. */
     lang?: string;
     text: string;
 }
@@ -9,11 +9,7 @@ export interface MarkdownProps {
     className?: string;
     children: string;
 }
-/**
- * The chat's own markdown renderer: React elements, never `dangerouslySetInnerHTML`, and no parser dependency.
- * `Bun.markdown` is the obvious candidate and cannot serve this — it is a runtime API the bundler passes through
- * verbatim, so it is undefined in the browser, and assistant text arrives here as SSE deltas the client accrues.
- */
+/** React elements, never `dangerouslySetInnerHTML`; not `Bun.markdown`, which is undefined in the browser. */
 export declare const DefaultMarkdown: ({ className, children }: MarkdownProps) => import("react/jsx-runtime").JSX.Element;
 declare const _default: import("react").ComponentType<MarkdownProps>;
 export default _default;

package/types/ui/Agent/MentionNode.d.ts

@@ -0,0 +1,18 @@
+import { type LexicalNode, type NodeKey, type SerializedTextNode, TextNode } from "lexical";
+import { type MessageReference } from "../../vendor/use-agentic.d.ts";
+export interface SerializedMentionNode extends SerializedTextNode {
+    reference: MessageReference;
+}
+export declare class MentionNode extends TextNode {
+    #private;
+    static getType(): string;
+    static clone(node: MentionNode): MentionNode;
+    static importJSON(json: Parameters<typeof TextNode.importJSON>[0]): MentionNode;
+    constructor(reference?: MessageReference, key?: NodeKey);
+    get reference(): MessageReference;
+    getTextContent(): string;
+    createDOM(...args: Parameters<TextNode["createDOM"]>): HTMLElement;
+    exportJSON(): SerializedMentionNode;
+}
+export declare const $createMentionNode: (reference: MessageReference) => MentionNode;
+export declare const $isMentionNode: (node: LexicalNode | null | undefined) => node is MentionNode;

package/types/ui/Agent/Menu.d.ts

@@ -1,18 +1,18 @@
 export interface MenuRow {
     name: string;
     description?: string;
-    /** The argument names a prompt takes, shown so a user knows what to type after the name. */
+    /** The argument names a row takes. */
     hint?: string;
     pick: () => void;
 }
 export interface MenuProps {
     className?: string;
     rows: MenuRow[];
-    /** Index the arrows are on. Enter picks it and Tab completes its name, so it has to be visible. */
     selected: number;
+    /** Drawn before each row name; `/` by default. */
+    prefix?: string;
     onPick: (row: MenuRow) => void;
 }
-/** The `/` menu: this chat's own commands first, then the app's `prompt()` endpoints. */
-export declare const DefaultAgentMenu: ({ className, rows, selected, onPick }: MenuProps) => import("react/jsx-runtime").JSX.Element | null;
+export declare const DefaultAgentMenu: ({ className, rows, selected, prefix, onPick }: MenuProps) => import("react/jsx-runtime").JSX.Element | null;
 declare const _default: import("react").ComponentType<MenuProps>;
 export default _default;

package/types/ui/Agent/Question.d.ts

@@ -3,12 +3,7 @@ export interface QuestionProps {
     className?: string;
     question: PendingQuestion;
 }
-/**
- * The agent's question, parked above the composer while the loop waits on it. Only the picks live here — the
- * composer below is the free-text answer, so the panel never grows a second input meaning the same thing. There is
- * always that way out of the options: the model wrote them, and only the user knows whether the answer is among
- * them. Mounted keyed by call id, so a second ask starts with nothing picked.
- */
+/** Only the picks: the composer below is the free-text answer. */
 export declare const DefaultQuestion: ({ className, question }: QuestionProps) => import("react/jsx-runtime").JSX.Element;
 declare const _default: import("react").ComponentType<QuestionProps>;
 export default _default;

package/types/ui/Agent/Queued.d.ts

@@ -2,15 +2,10 @@ import type { QueuedMessage } from "./useChatQueue.d.ts";
 export interface QueuedProps {
     className?: string;
     message: QueuedMessage;
-    /** Hands the message back to the composer to be changed — the only way to edit what is already out of it. */
+    /** Hands the message back to the composer. */
     onEdit: () => void;
     onCancel: () => void;
 }
-/**
- * The message waiting for the running turn to end, parked above the composer where the question card sits. It is
- * shown rather than silently held because a send that vanished from the composer and has not appeared in the
- * transcript reads as lost, and because taking it back or dropping it needs somewhere to click.
- */
 export declare const DefaultQueued: ({ className, message, onEdit, onCancel }: QueuedProps) => import("react/jsx-runtime").JSX.Element;
 declare const _default: import("react").ComponentType<QueuedProps>;
 export default _default;

package/types/ui/Agent/Refer.d.ts

@@ -0,0 +1,9 @@
+import { type MessageReference } from "../../vendor/use-agentic.d.ts";
+export interface ReferenceChipsProps {
+    className?: string;
+    references: readonly MessageReference[];
+    /** Omitted for a sent message: what is already on the wire cannot be taken back. */
+    onRemove?: (key: string) => void;
+    removeLabel?: string;
+}
+export declare const ReferenceChips: ({ className, references, onRemove, removeLabel }: ReferenceChipsProps) => import("react/jsx-runtime").JSX.Element;

package/types/ui/Agent/RichInput.d.ts

@@ -0,0 +1,14 @@
+import { type KeyboardEvent as ReactKeyboardEvent, type RefObject } from "react";
+import type { ComposerHandle } from "./Composer.d.ts";
+interface RichInputProps {
+    className?: string;
+    draft: string;
+    placeholder: string;
+    onDraft: (text: string) => void;
+    /** The textarea's own handler, fed a synthetic event: the chat reads keys off the draft and caret, not the DOM. */
+    onKeyDown: (event: ReactKeyboardEvent<HTMLTextAreaElement>) => void;
+    onFiles: (files: File[]) => void;
+    handleRef?: RefObject<ComposerHandle | null>;
+}
+export declare const RichInput: ({ className, draft, placeholder, onDraft, onKeyDown, onFiles, handleRef, }: RichInputProps) => import("react/jsx-runtime").JSX.Element;
+export default RichInput;

package/types/ui/Agent/Skip.d.ts

@@ -1,22 +1,10 @@
 import type { ReactNode } from "react";
 export interface SkipProps {
     className?: string;
-    /**
-     * What `readScreen` prints in place of the region, and the name `section` takes to read it anyway. Required
-     * because the marker is the whole point: an unnamed one tells the agent a region exists and nothing about it.
-     */
+    /** What `readScreen` prints in place of the region, and the name `section` takes to read it anyway. */
     label: string;
     children: ReactNode;
 }
-/**
- * A region the default `readScreen` leaves out, for chrome that costs the agent tokens and answers nothing — a
- * footer, a cookie banner, a repeated nav. What stands in its place is `[skipped: <label>]`, so an agent asked
- * about the footer says it did not read one instead of reporting that the page has none, and `section: "<label>"`
- * reads it on request.
- *
- * **This hides text, not behaviour.** Tools and state keys are declarations, not markup: an `st.tool` inside here
- * is published exactly as before, and `highlight` still reaches a control in here. It renders a wrapper element,
- * so where a div between a flex container and its children would move the layout, put the attribute on the element
- * the page already renders — `<footer data-agent-skip="site footer">`.
- */
+/** Hides text from `readScreen`, not tools or state. Where a wrapper div would move the layout, put
+ *  `data-agent-skip="<label>"` on an element the page already renders. */
 export declare const Skip: ({ className, label, children }: SkipProps) => import("react/jsx-runtime").JSX.Element;

package/types/ui/Agent/Steps.d.ts

@@ -0,0 +1,17 @@
+import type { AgentProgressReport, ChatMessage, ToolCallResult } from "../../vendor/use-agentic.d.ts";
+export interface StepsProps {
+    /** One agent turn as rendered: tool messages keep only the results no call row claims. */
+    messages: readonly ChatMessage[];
+    /** True only for the last turn while the session is still working on it. */
+    isRunning: boolean;
+    /** What the running call last reported about itself. */
+    progress?: (AgentProgressReport & {
+        callId: string;
+    }) | null;
+    /** Results by call id across the transcript, so a call's own row resolves in place. */
+    results?: ReadonlyMap<string, ToolCallResult>;
+}
+/** Draws the turn's messages flat into a Fragment: no element, no `className`. */
+export declare const DefaultSteps: ({ messages, progress, results }: StepsProps) => import("react/jsx-runtime").JSX.Element;
+declare const _default: import("react").ComponentType<StepsProps>;
+export default _default;

package/types/ui/Agent/ToolCard.d.ts

@@ -0,0 +1,9 @@
+import type { PendingCard } from "../../vendor/use-agentic.d.ts";
+export interface ToolCardProps {
+    className?: string;
+    card: PendingCard;
+}
+/** Always draws a skip, so a card rendering no cancel of its own cannot park the turn for good. */
+export declare const DefaultToolCard: ({ className, card }: ToolCardProps) => import("react/jsx-runtime").JSX.Element;
+declare const _default: import("react").ComponentType<ToolCardProps>;
+export default _default;

package/types/ui/Agent/Zone.d.ts

@@ -1,48 +1,31 @@
+import type { AgentVisualOption } from "akanjs/store";
 import { type ReactNode } from "react";
 import { type AgentRunner, type AgentSession, type AgentSessionOptions, type CompactOptions, type SessionHistory } from "../../vendor/use-agentic.d.ts";
-import type { PersistOption } from "./sessionHistory.d.ts";
-import type { BuiltinOption } from "./sessionView.d.ts";
+import { type BuiltinOption, type PersistOption } from "./agentSessionOf.d.ts";
 export interface ZoneProps {
     className?: string;
     /** Names the zone; the scope id and the `data-agent-zone` container both derive from it. */
     id: string;
     label?: string;
-    /** Zone-scoped guidance — a mounted Guide, so the root agent reads it too (ancestor rule), a sibling zone never does. */
+    /** A mounted Guide: the root agent reads it too, a sibling zone never does. */
     instructions?: string;
     runner?: AgentRunner;
     maxTurns?: number;
-    /** When this zone's conversation summarizes itself — same contract as the chat's own `compact`. */
+    /** Same contract as the chat's own `compact`. */
     compact?: CompactOptions;
-    /**
-     * Which of the runtime's own tools this zone's agent gets — all of them by default, `false` none, an array
-     * exactly the ones it names. `builtins={["readScreen", "readState"]}` is how a zone that must not leave the
-     * screen stops being able to: the tools are withheld, not discouraged, so a prompt cannot talk the model past it.
-     */
+    /** Every runtime tool by default, `false` none, an array exactly the ones it names. */
     builtins?: BuiltinOption;
-    /**
-     * Keeps this zone's transcript across reloads, keyed by the zone's scope path — web storage by default, or a
-     * `SessionHistory` of the app's own to keep it anywhere else, a server included.
-     */
+    /** Keyed by the zone's scope path; web storage by default, or an app `SessionHistory`. */
     persist?: PersistOption | SessionHistory;
-    /** Called after a compaction replaced messages with one summary — where a host syncs its own watermark. */
+    /** Called after a compaction replaced messages with one summary. */
     onCompact?: AgentSessionOptions["onCompact"];
-    /**
-     * Runs this zone on a session the app built instead of one of its own, and the app then owns it: unmounting the
-     * zone leaves it running. Read once at mount, like every other session option here.
-     */
+    /** On by default; `false` draws nothing, `{ cursor: false }` / `{ reveal: false }` turn one effect off. */
+    visual?: boolean | AgentVisualOption;
+    /** An app-built session the app keeps owning: unmounting leaves it running. Read once at mount. */
     session?: AgentSession;
-    /** Hands the session out once it exists, for a page or store that wants to send into it or watch it. */
+    /** Called once the session exists. */
     onSession?: (session: AgentSession) => void;
     children: ReactNode;
 }
-/**
- * A zone agent: one subtree with its own conversation over a scoped view of the same surface. Everything mounted
- * inside — hook tools, `st.use` subscriptions, guides — belongs to this zone's session *and* to the root agent:
- * zones are views, never walls. An `Agent.Chat` mounted inside binds to this session automatically, so two zones
- * on one screen run two conversations in parallel, each seeing only its own subtree.
- *
- * **Everything a zone publishes is named `<id>.<name>`.** Instructions that name a tool must carry the prefix —
- * a bare name is a tool that does not exist, and the model calling it spends a turn on `Unknown tool`. Build the
- * name from the id rather than writing it twice, and read `Agent.Context`'s Assemble to see the published list.
- */
-export declare const Zone: ({ className, id, label, instructions, runner, maxTurns, compact, builtins, persist, onCompact, session: provided, onSession, children, }: ZoneProps) => import("react/jsx-runtime").JSX.Element;
+/** Everything a zone publishes is named `<id>.<name>`, so instructions naming a tool must carry the prefix. */
+export declare const Zone: ({ className, id, label, instructions, runner, maxTurns, compact, builtins, persist, onCompact, visual, session: provided, onSession, children, }: ZoneProps) => import("react/jsx-runtime").JSX.Element;

package/types/ui/Agent/agentSessionOf.d.ts

@@ -1,27 +1,31 @@
-import { type AgentRunner, AgentSession, type AgentSessionOptions, type CompactOptions, type SessionHistory } from "../../vendor/use-agentic.d.ts";
-import { type PersistOption } from "./sessionHistory.d.ts";
-import { type BuiltinOption } from "./sessionView.d.ts";
+import { type AgentVisualOption, StoreSurfaceSource } from "akanjs/store";
+import { type AgenticSurface, type AgentRunner, AgentSession, type AgentSessionOptions, type CompactOptions, type SessionHistory, type SurfaceView } from "../../vendor/use-agentic.d.ts";
+/** A tool the akan runtime contributes to every screen, whatever that screen declares. */
+export type AgentBuiltin = (typeof StoreSurfaceSource.builtins)[number];
+/** `true` (the default) takes all of them, `false` none, an array exactly the ones it names. */
+export type BuiltinOption = boolean | AgentBuiltin[];
+export type PersistOption = boolean | {
+    storage?: "session" | "local";
+    key?: string;
+};
 export interface AgentSessionSetup {
-    /** Read per call rather than captured, so text the session builds follows a language switched mid-conversation. */
+    /** Read per call, so the session's own text follows a language switched mid-conversation. */
     l: (key: string) => string;
-    /** The zone's scope path, empty for the root agent — it picks both the surface view and the persistence key. */
+    /** The zone's scope path, empty for the root agent; it picks both the surface view and the persistence key. */
     view?: string[];
     runner?: AgentRunner;
     instructions?: string;
     maxTurns?: number;
     compact?: CompactOptions;
-    /**
-     * Which of the runtime's own tools this session gets: all of them by default, none with `false`, exactly the
-     * ones an array names. A zone whose conversation must stay on one screen takes `navigate` and `goBack` off it.
-     */
+    /** Every runtime tool by default, `false` none, an array exactly the ones it names. */
     builtins?: BuiltinOption;
-    /** Web storage by default; a `SessionHistory` puts the transcript wherever the app keeps it, including a server. */
+    /** Web storage by default, or an app `SessionHistory`. */
     persist?: PersistOption | SessionHistory;
-    /** Called after a compaction replaced messages with one summary — where a host syncs its own watermark. */
+    /** Called after a compaction replaced messages with one summary. */
     onCompact?: AgentSessionOptions["onCompact"];
+    /** `false` draws nothing while this session drives the page. */
+    visual?: boolean | AgentVisualOption;
 }
-/**
- * The one place a chat session is wired to the akan runtime. Chat and Zone both build one, and building it twice
- * is how a zone came to be the only surface with no `compact` option — an option added on one side of a copy.
- */
-export declare const agentSessionOf: ({ l, view, runner, instructions, maxTurns, compact, builtins, persist, onCompact, }: AgentSessionSetup) => AgentSession;
+export declare const agentSessionOf: ({ l, view, runner, instructions, maxTurns, compact, builtins, persist, onCompact, visual, }: AgentSessionSetup) => AgentSession;
+export declare const sessionView: (surface: AgenticSurface, path: string[], builtins?: BuiltinOption) => SurfaceView;
+export declare const sessionHistoryOf: (persist: PersistOption | SessionHistory | undefined, pathKey?: string) => SessionHistory | undefined;