@artooi/ag-ui-web-component 0.1.0

package/dist/ag_ui_chat.d.ts

@@ -0,0 +1,85 @@
+import type { Context, Tool } from "@ag-ui/core";
+import { type ClientTool } from "./client_tool_registry.js";
+import { MESSAGE_ROLE } from "./constants.js";
+import { type ClientConversationStore, type NavigationCheckpoint } from "./conversation_store.js";
+import { type AgentFactory } from "./create_http_agent.js";
+import { type PageMap } from "./page_map.js";
+import { type RouteMap } from "./route_map.js";
+import { type StateHook } from "./state_hook.js";
+/** The role a rendered chat message takes. */
+export type MessageRole = (typeof MESSAGE_ROLE)[keyof typeof MESSAGE_ROLE];
+/** `detail` shape of the {@link SUBMIT_EVENT} CustomEvent. */
+export interface SubmitDetail {
+    readonly content: string;
+}
+/**
+ * `<ag-ui-chat>` — a framework-free chat sidebar Web Component over AG-UI.
+ *
+ * Owns the Shadow DOM shell (header, scrolling message list, input row),
+ * builds an {@link AgUiClient} on first send (via the overridable
+ * {@link agentFactory}), and renders streaming assistant text plus tool-call
+ * activity. Emits a {@link SUBMIT_EVENT} for host visibility.
+ *
+ * The per-run frontend tool catalog and context are supplied by
+ * {@link getTools} / {@link getContext}, which later phases (the tool
+ * registry, DOM driver) populate.
+ */
+export declare class AgUiChat extends HTMLElement {
+    #private;
+    /** Agent factory; override to inject a custom or fake agent (tests). */
+    agentFactory: AgentFactory;
+    /** Extra HTTP headers for the AG-UI endpoint (e.g. CSRF). */
+    headers: Record<string, string>;
+    /** When true, destructive tools execute without a confirmation modal. */
+    autoConfirm: boolean;
+    /**
+     * Per-run frontend tool catalog provider. Defaults to the built-in
+     * `route.*` tools (when a {@link routeMap} is set) plus the tools registered
+     * via {@link registerTool} / {@link registerStateHook}; override to supply a
+     * fully custom catalog.
+     */
+    getTools: () => Tool[];
+    /**
+     * Per-run context provider. Defaults to the compact page map (when a
+     * {@link getPageMap} provider is set and {@link autoInjectPageMap} is on).
+     */
+    getContext: () => Context[];
+    /**
+     * Navigable routes the agent can jump to via the built-in `route.*` tools.
+     * A compact summary also rides in each run's context.
+     */
+    routeMap: RouteMap;
+    /**
+     * Optional client-side router. When set (an SPA), `navigate_to_route` routes
+     * in-page and the run loop continues; when unset (an MPA like the admin), it
+     * falls back to `window.location` and the resumable-loop machinery applies.
+     */
+    navigate: ((path: string) => void) | null;
+    /** Provider for the per-run page map; see {@link getContext}. */
+    getPageMap: (() => PageMap) | null;
+    /** Whether to auto-inject the page map into context each run. */
+    autoInjectPageMap: boolean;
+    /**
+     * Persistence for the conversation + navigation checkpoint. Defaults to
+     * per-tab `sessionStorage` so the chat survives full page reloads; inject a
+     * server-backed store for cross-tab/device durability.
+     */
+    conversationStore: ClientConversationStore;
+    /**
+     * Builds the tool result a navigating tool resumes with after the page
+     * reloads. Defaults to the landed URL; a host (e.g. the admin package) can
+     * override to include a page snapshot or post-reload validation errors.
+     */
+    navigationResult: (checkpoint: NavigationCheckpoint) => unknown;
+    constructor();
+    /** Declare a frontend tool the agent may call. */
+    registerTool(tool: ClientTool): void;
+    /** Bind a piece of host state to `read_<name>` / `set_<name>` tools. */
+    registerStateHook(hook: StateHook): void;
+    /** The AG-UI endpoint URL, read from the `endpoint` attribute. */
+    get endpoint(): string;
+    connectedCallback(): void;
+    /** Append a message bubble and return it. */
+    appendMessage(role: MessageRole, content: string): HTMLDivElement;
+}
+//# sourceMappingURL=ag_ui_chat.d.ts.map

package/dist/ag_ui_chat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ag_ui_chat.d.ts","sourceRoot":"","sources":["../src/ag_ui_chat.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAW,IAAI,EAAE,MAAM,aAAa,CAAC;AAO1D,OAAO,EAAE,KAAK,UAAU,EAAsB,MAAM,2BAA2B,CAAC;AAEhF,OAAO,EAAE,YAAY,EAAkC,MAAM,gBAAgB,CAAC;AAC9E,OAAO,EACL,KAAK,uBAAuB,EAC5B,KAAK,oBAAoB,EAE1B,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,KAAK,YAAY,EAAmB,MAAM,wBAAwB,CAAC;AAG5E,OAAO,EAAwB,KAAK,OAAO,EAAE,MAAM,eAAe,CAAC;AACnE,OAAO,EAAoB,KAAK,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AACjE,OAAO,EAAwB,KAAK,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAIvE,8CAA8C;AAC9C,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,OAAO,YAAY,CAAC,CAAC;AAE3E,8DAA8D;AAC9D,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,QAAS,SAAQ,WAAW;;IACvC,wEAAwE;IACxE,YAAY,EAAE,YAAY,CAAmB;IAE7C,6DAA6D;IAC7D,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAM;IAErC,yEAAyE;IACzE,WAAW,UAAS;IAEpB;;;;;OAKG;IACH,QAAQ,EAAE,MAAM,IAAI,EAAE,CAOpB;IAEF;;;OAGG;IACH,UAAU,EAAE,MAAM,OAAO,EAAE,CAAuE;IAElG;;;OAGG;IACH,QAAQ,EAAE,QAAQ,CAAM;IAExB;;;;OAIG;IACH,QAAQ,EAAE,CAAC,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC,GAAG,IAAI,CAAQ;IAEjD,iEAAiE;IACjE,UAAU,EAAE,CAAC,MAAM,OAAO,CAAC,GAAG,IAAI,CAAQ;IAE1C,iEAAiE;IACjE,iBAAiB,UAAQ;IAEzB;;;;OAIG;IACH,iBAAiB,EAAE,uBAAuB,CAA6B;IAEvE;;;;OAIG;IACH,gBAAgB,EAAE,CAAC,UAAU,EAAE,oBAAoB,KAAK,OAAO,CAG5D;;IAyBH,kDAAkD;IAClD,YAAY,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI;IAIpC,wEAAwE;IACxE,iBAAiB,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI;IA0BxC,kEAAkE;IAClE,IAAI,QAAQ,IAAI,MAAM,CAErB;IAED,iBAAiB,IAAI,IAAI;IA6CzB,6CAA6C;IAC7C,aAAa,CAAC,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,GAAG,cAAc;CAiMlE"}

package/dist/agui_client.d.ts

@@ -0,0 +1,99 @@
+import { type AbstractAgent } from "@ag-ui/client";
+import type { Context, Message, Tool } from "@ag-ui/core";
+/** A tool call surfaced to the host by {@link AgUiClient}. */
+export interface AgUiToolCall {
+    readonly id: string;
+    readonly name: string;
+    readonly args: Record<string, unknown>;
+}
+/** The result of executing a frontend tool, destined for a tool-result message. */
+export interface ToolExecution {
+    /** String content for the AG-UI tool-result message. */
+    content: string;
+    /** Present when the handler failed; surfaced for logging. */
+    error?: string;
+    /**
+     * When `true`, a navigating tool triggered a page reload. The loop stops
+     * without appending a result — the result is supplied after the next mount
+     * (see the resume path). Mutually exclusive with a usable `content`.
+     */
+    halt?: boolean;
+}
+/**
+ * Executes a frontend tool call.
+ *
+ * Returns the {@link ToolExecution} to post back to the agent, or ``null`` when
+ * the call is not a frontend tool the host owns (a server-side tool the server
+ * already executed — the client must not re-run for it).
+ */
+export type ExecuteTool = (call: AgUiToolCall) => Promise<ToolExecution | null>;
+/**
+ * Callbacks the {@link AgUiClient} invokes as a run progresses. The host
+ * (the `<ag-ui-chat>` element) implements these to render streaming text and
+ * tool activity into the chat.
+ */
+export interface AgUiClientHandlers {
+    onRunStart(): void;
+    /** Fired on every streamed token; ``buffer`` is the full text so far. */
+    onTextDelta(buffer: string): void;
+    /** Fired when the assistant message completes; ``buffer`` is the final text. */
+    onTextEnd(buffer: string): void;
+    /** Fired when the agent finishes calling a tool (server- or frontend-side). */
+    onToolCall(call: AgUiToolCall): void;
+    onRunEnd(): void;
+    onError(message: string): void;
+}
+/**
+ * Provider of the per-run frontend tool catalog and context. Both are read
+ * fresh on every {@link AgUiClient.send} so the catalog reflects the current
+ * page state.
+ */
+export interface AgUiRunInputs {
+    getTools?: () => Tool[];
+    getContext?: () => Context[];
+}
+export interface AgUiClientConfig extends AgUiRunInputs {
+    /** The AG-UI agent to drive. Injected so it can be faked in tests. */
+    agent: AbstractAgent;
+    handlers: AgUiClientHandlers;
+    /** Executes frontend tool calls. Omit for server-only tool sets. */
+    executeTool?: ExecuteTool;
+    /**
+     * Invoked with the latest history whenever it changes, so the host can
+     * persist it for durability across page reloads. Omit to keep the
+     * conversation in-memory only.
+     */
+    onPersist?: (messages: readonly Message[]) => void;
+}
+/**
+ * Thin orchestration layer over an AG-UI {@link AbstractAgent}.
+ *
+ * Translates AG-UI's subscriber callbacks into the host's
+ * {@link AgUiClientHandlers}, and appends the user message + current frontend
+ * tool catalog + context to each run.
+ */
+export declare class AgUiClient {
+    #private;
+    constructor(config: AgUiClientConfig);
+    /** Whether a run is currently in flight. */
+    get running(): boolean;
+    /** The current conversation history (for persistence / rehydration). */
+    get messages(): readonly Message[];
+    /**
+     * Append a user message and run the agent to completion.
+     *
+     * When the agent calls frontend tools, this executes them and re-runs the
+     * agent with the results, looping until the agent stops calling frontend
+     * tools (bounded by {@link MAX_TOOL_ROUNDS}).
+     */
+    send(content: string): Promise<void>;
+    /**
+     * Resume the run loop after a navigating tool's result was supplied
+     * post-reload (via {@link addToolResult}). Unlike {@link send}, adds no user
+     * message — it simply continues the conversation already in history.
+     */
+    resume(): Promise<void>;
+    /** Append a frontend tool result to history (used by the resume path). */
+    addToolResult(toolCallId: string, content: string): void;
+}
+//# sourceMappingURL=agui_client.d.ts.map

package/dist/agui_client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agui_client.d.ts","sourceRoot":"","sources":["../src/agui_client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,aAAa,EAAoC,MAAM,eAAe,CAAC;AACrF,OAAO,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AAG1D,8DAA8D;AAC9D,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACxC;AAED,mFAAmF;AACnF,MAAM,WAAW,aAAa;IAC5B,wDAAwD;IACxD,OAAO,EAAE,MAAM,CAAC;IAChB,6DAA6D;IAC7D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED;;;;;;GAMG;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,IAAI,EAAE,YAAY,KAAK,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAAC;AAEhF;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,UAAU,IAAI,IAAI,CAAC;IACnB,yEAAyE;IACzE,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,gFAAgF;IAChF,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,+EAA+E;IAC/E,UAAU,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI,CAAC;IACrC,QAAQ,IAAI,IAAI,CAAC;IACjB,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,MAAM,IAAI,EAAE,CAAC;IACxB,UAAU,CAAC,EAAE,MAAM,OAAO,EAAE,CAAC;CAC9B;AAED,MAAM,WAAW,gBAAiB,SAAQ,aAAa;IACrD,sEAAsE;IACtE,KAAK,EAAE,aAAa,CAAC;IACrB,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,oEAAoE;IACpE,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B;;;;OAIG;IACH,SAAS,CAAC,EAAE,CAAC,QAAQ,EAAE,SAAS,OAAO,EAAE,KAAK,IAAI,CAAC;CACpD;AAED;;;;;;GAMG;AACH,qBAAa,UAAU;;gBAQT,MAAM,EAAE,gBAAgB;IASpC,4CAA4C;IAC5C,IAAI,OAAO,IAAI,OAAO,CAErB;IAED,wEAAwE;IACxE,IAAI,QAAQ,IAAI,SAAS,OAAO,EAAE,CAEjC;IAED;;;;;;OAMG;IACG,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAM1C;;;;OAIG;IACG,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAI7B,0EAA0E;IAC1E,aAAa,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI;CA+EzD"}

package/dist/animations.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Visible-action animation primitives.
+ *
+ * These run against the **host page** DOM (not the element's shadow root) so a
+ * user watches the agent type, highlight, and click at human-readable speed.
+ * Each is configurable; pass small/zero durations in tests (or use fake timers).
+ */
+/** An element whose `value` can be typed into. */
+export type TextLikeElement = HTMLInputElement | HTMLTextAreaElement;
+export interface TypeOptions {
+    /** Milliseconds between characters. Default 35. */
+    charDelayMs?: number;
+}
+/**
+ * Clear ``el`` and type ``value`` one character at a time, firing ``input``
+ * events as a real user would, then a final ``change`` event.
+ */
+export declare function typeInto(el: TextLikeElement, value: string, options?: TypeOptions): Promise<void>;
+export interface HighlightClickOptions {
+    /** Milliseconds to hold the highlight before clicking. Default 280. */
+    highlightMs?: number;
+}
+/** Outline ``el``, pause so the user sees it, then click and restore. */
+export declare function highlightThenClick(el: HTMLElement, options?: HighlightClickOptions): Promise<void>;
+/** Scroll ``el`` to the vertical centre of the viewport. */
+export declare function scrollIntoCenterView(el: HTMLElement): void;
+export interface FlashOptions {
+    /** Milliseconds to hold the focus flash. Default 200. */
+    flashMs?: number;
+}
+/** Focus ``el`` and briefly flash a ring around it. */
+export declare function focusWithFlash(el: HTMLElement, options?: FlashOptions): Promise<void>;
+//# sourceMappingURL=animations.d.ts.map

package/dist/animations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"animations.d.ts","sourceRoot":"","sources":["../src/animations.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAUH,kDAAkD;AAClD,MAAM,MAAM,eAAe,GAAG,gBAAgB,GAAG,mBAAmB,CAAC;AAErE,MAAM,WAAW,WAAW;IAC1B,mDAAmD;IACnD,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;GAGG;AACH,wBAAsB,QAAQ,CAC5B,EAAE,EAAE,eAAe,EACnB,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,WAAgB,GACxB,OAAO,CAAC,IAAI,CAAC,CAYf;AAED,MAAM,WAAW,qBAAqB;IACpC,uEAAuE;IACvE,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,yEAAyE;AACzE,wBAAsB,kBAAkB,CACtC,EAAE,EAAE,WAAW,EACf,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,IAAI,CAAC,CAUf;AAED,4DAA4D;AAC5D,wBAAgB,oBAAoB,CAAC,EAAE,EAAE,WAAW,GAAG,IAAI,CAE1D;AAED,MAAM,WAAW,YAAY;IAC3B,yDAAyD;IACzD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,uDAAuD;AACvD,wBAAsB,cAAc,CAAC,EAAE,EAAE,WAAW,EAAE,OAAO,GAAE,YAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAO/F"}

package/dist/client_tool_registry.d.ts

@@ -0,0 +1,32 @@
+import type { Tool } from "@ag-ui/core";
+/**
+ * A tool the frontend declares and executes itself.
+ *
+ * `parameters` is a JSON Schema (and may carry the `x-destructive` extension).
+ * `handler` receives the parsed arguments and returns a result that is
+ * JSON-serialised into the AG-UI tool-result message sent back to the agent.
+ */
+export interface ClientTool {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+    handler: (args: Record<string, unknown>) => unknown | Promise<unknown>;
+}
+/**
+ * Holds the frontend tools a host has declared on an `<ag-ui-chat>` element.
+ *
+ * Produces AG-UI {@link Tool} definitions for `RunAgentInput.tools` and looks
+ * up handlers when the agent calls a tool. Pure (no DOM); the element owns one
+ * instance.
+ */
+export declare class ClientToolRegistry {
+    #private;
+    /** Register a tool. Throws if the name is already taken. */
+    register(tool: ClientTool): void;
+    has(name: string): boolean;
+    /** Return a registered tool or throw. */
+    get(name: string): ClientTool;
+    /** AG-UI tool definitions for `RunAgentInput.tools`. */
+    tools(): Tool[];
+}
+//# sourceMappingURL=client_tool_registry.d.ts.map

package/dist/client_tool_registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client_tool_registry.d.ts","sourceRoot":"","sources":["../src/client_tool_registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AAExC;;;;;;GAMG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpC,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACxE;AAED;;;;;;GAMG;AACH,qBAAa,kBAAkB;;IAG7B,4DAA4D;IAC5D,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI;IAOhC,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI1B,yCAAyC;IACzC,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU;IAQ7B,wDAAwD;IACxD,KAAK,IAAI,IAAI,EAAE;CAOhB"}

package/dist/confirmation_modal.d.ts

@@ -0,0 +1,14 @@
+/** What the confirmation modal displays. */
+export interface ConfirmationRequest {
+    toolName: string;
+    args: Record<string, unknown>;
+}
+/**
+ * Render a confirmation modal into ``host`` and resolve when the user decides.
+ *
+ * Resolves ``true`` if the user confirms, ``false`` if they cancel or dismiss
+ * via the backdrop. The modal is appended to ``host`` (the chat container
+ * inside the element's shadow root) and removed once resolved.
+ */
+export declare function requestConfirmation(host: Node & ParentNode, request: ConfirmationRequest): Promise<boolean>;
+//# sourceMappingURL=confirmation_modal.d.ts.map

package/dist/confirmation_modal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"confirmation_modal.d.ts","sourceRoot":"","sources":["../src/confirmation_modal.ts"],"names":[],"mappings":"AAAA,4CAA4C;AAC5C,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,IAAI,GAAG,UAAU,EACvB,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,OAAO,CAAC,CAoDlB"}

package/dist/constants.d.ts

@@ -0,0 +1,40 @@
+/** The Custom Element tag name registered by {@link defineAgUiChat}. */
+export declare const ELEMENT_TAG = "ag-ui-chat";
+/**
+ * Event dispatched by `<ag-ui-chat>` when the user submits a message.
+ * `detail` carries `{ content: string }`. Later phases wire this to the
+ * AG-UI client; for now it is the public seam for host integration.
+ */
+export declare const SUBMIT_EVENT = "ag-ui-submit";
+/** Roles a chat message can take. */
+export declare const MESSAGE_ROLE: {
+    readonly USER: "user";
+    readonly ASSISTANT: "assistant";
+};
+/**
+ * JSON-Schema extension key marking a tool as destructive. Mirrors the
+ * `django-ag-ui` server side. When a tool's `parameters` carries
+ * `{ "x-destructive": true }`, the element gates its execution behind the
+ * confirmation modal (unless `autoConfirm` is set).
+ */
+export declare const X_DESTRUCTIVE_KEY = "x-destructive";
+/**
+ * JSON-Schema extension key marking a tool as navigating — its handler triggers
+ * a full page reload (an MPA navigation). When a tool's `parameters` carries
+ * `{ "x-navigates": true }`, the element checkpoints the call before the reload
+ * and resumes the run loop once the next page mounts. Mirrors `x-destructive`.
+ */
+export declare const X_NAVIGATES_KEY = "x-navigates";
+/** Upper bound on frontend tool-call → re-run rounds within one send. */
+export declare const MAX_TOOL_ROUNDS = 10;
+/**
+ * Lifecycle status of a rendered tool-call card. A card opens as `PENDING`
+ * while the call runs, then settles to `DONE`, `ERROR`, or `DECLINED`.
+ */
+export declare const TOOL_CALL_STATUS: {
+    readonly PENDING: "pending";
+    readonly DONE: "done";
+    readonly ERROR: "error";
+    readonly DECLINED: "declined";
+};
+//# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAGA,wEAAwE;AACxE,eAAO,MAAM,WAAW,eAAe,CAAC;AAExC;;;;GAIG;AACH,eAAO,MAAM,YAAY,iBAAiB,CAAC;AAE3C,qCAAqC;AACrC,eAAO,MAAM,YAAY;;;CAGf,CAAC;AAEX;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,kBAAkB,CAAC;AAEjD;;;;;GAKG;AACH,eAAO,MAAM,eAAe,gBAAgB,CAAC;AAE7C,yEAAyE;AACzE,eAAO,MAAM,eAAe,KAAK,CAAC;AAElC;;;GAGG;AACH,eAAO,MAAM,gBAAgB;;;;;CAKnB,CAAC"}

package/dist/conversation_store.d.ts

@@ -0,0 +1,54 @@
+import type { Message } from "@ag-ui/core";
+/**
+ * A checkpoint recorded just before a navigating tool reloads the page.
+ *
+ * The reload destroys the in-memory run loop, so the element persists this
+ * marker first; on the next mount it supplies the tool's result and resumes.
+ */
+export interface NavigationCheckpoint {
+    /** The tool-call id whose result must be supplied after the reload. */
+    readonly toolCallId: string;
+}
+/**
+ * Client-side persistence seam for the conversation and a pending-navigation
+ * checkpoint, keyed by `thread_id`.
+ *
+ * The default {@link SessionStorageStore} keeps everything per-tab in
+ * `sessionStorage`, so the chat survives the full page reloads of a
+ * multi-page app. A host may inject a server-backed store instead (e.g. one
+ * that rehydrates from a history endpoint); `loadMessages` is therefore
+ * async-friendly. The checkpoint methods stay synchronous — the marker is a
+ * tiny local hint a server store can derive from history and no-op.
+ */
+export interface ClientConversationStore {
+    /** A stable conversation id, generated and persisted on first read. */
+    threadId(): string;
+    /** Load the persisted message history, or `null` when none exists. */
+    loadMessages(threadId: string): Promise<readonly Message[] | null>;
+    /** Persist the message history. */
+    saveMessages(threadId: string, messages: readonly Message[]): void;
+    /** Load the pending-navigation checkpoint, or `null` when none is set. */
+    loadCheckpoint(threadId: string): NavigationCheckpoint | null;
+    /** Set the pending-navigation checkpoint, or clear it when given `null`. */
+    saveCheckpoint(threadId: string, checkpoint: NavigationCheckpoint | null): void;
+    /** Forget the conversation and checkpoint (e.g. a "new chat" action). */
+    clear(threadId: string): void;
+}
+/**
+ * Default {@link ClientConversationStore}: per-tab `sessionStorage`.
+ *
+ * Survives full page reloads and same-tab navigation, clears on tab close —
+ * the right scope for an embedded agent's conversation in a multi-page app.
+ * One thread id per tab; the message history and checkpoint are namespaced by
+ * it so two tabs hold independent conversations.
+ */
+export declare class SessionStorageStore implements ClientConversationStore {
+    #private;
+    threadId(): string;
+    loadMessages(threadId: string): Promise<readonly Message[] | null>;
+    saveMessages(threadId: string, messages: readonly Message[]): void;
+    loadCheckpoint(threadId: string): NavigationCheckpoint | null;
+    saveCheckpoint(threadId: string, checkpoint: NavigationCheckpoint | null): void;
+    clear(threadId: string): void;
+}
+//# sourceMappingURL=conversation_store.d.ts.map

package/dist/conversation_store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conversation_store.d.ts","sourceRoot":"","sources":["../src/conversation_store.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAE3C;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IACnC,uEAAuE;IACvE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,uBAAuB;IACtC,uEAAuE;IACvE,QAAQ,IAAI,MAAM,CAAC;IACnB,sEAAsE;IACtE,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,OAAO,EAAE,GAAG,IAAI,CAAC,CAAC;IACnE,mCAAmC;IACnC,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,OAAO,EAAE,GAAG,IAAI,CAAC;IACnE,0EAA0E;IAC1E,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,oBAAoB,GAAG,IAAI,CAAC;IAC9D,4EAA4E;IAC5E,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,oBAAoB,GAAG,IAAI,GAAG,IAAI,CAAC;IAChF,yEAAyE;IACzE,KAAK,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B;AAMD;;;;;;;GAOG;AACH,qBAAa,mBAAoB,YAAW,uBAAuB;;IACjE,QAAQ,IAAI,MAAM;IAUlB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,OAAO,EAAE,GAAG,IAAI,CAAC;IAIlE,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,OAAO,EAAE,GAAG,IAAI;IAIlE,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,oBAAoB,GAAG,IAAI;IAI7D,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,oBAAoB,GAAG,IAAI,GAAG,IAAI;IAS/E,KAAK,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;CAkB9B"}

package/dist/create_http_agent.d.ts

@@ -0,0 +1,22 @@
+import { type AbstractAgent } from "@ag-ui/client";
+import type { Message } from "@ag-ui/core";
+/** Config for {@link createHttpAgent}. */
+export interface HttpAgentOptions {
+    endpoint: string;
+    headers?: Record<string, string>;
+    /** Stable conversation id, so the agent's runs share a thread. */
+    threadId?: string;
+    /** Rehydrated history to seed the agent with (durable conversation). */
+    initialMessages?: readonly Message[];
+}
+/**
+ * Build an AG-UI {@link HttpAgent} pointed at ``endpoint``.
+ *
+ * This is the default agent factory used by ``<ag-ui-chat>``. Tests and
+ * advanced hosts override the element's ``agentFactory`` to inject a
+ * different {@link AbstractAgent} (e.g. a fake, or a middleware-wrapped one).
+ */
+export declare function createHttpAgent(options: HttpAgentOptions): AbstractAgent;
+/** Signature of the agent factory the element calls to build its agent. */
+export type AgentFactory = (options: HttpAgentOptions) => AbstractAgent;
+//# sourceMappingURL=create_http_agent.d.ts.map

package/dist/create_http_agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create_http_agent.d.ts","sourceRoot":"","sources":["../src/create_http_agent.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,aAAa,EAAa,MAAM,eAAe,CAAC;AAC9D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAE3C,0CAA0C;AAC1C,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,kEAAkE;IAClE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,wEAAwE;IACxE,eAAe,CAAC,EAAE,SAAS,OAAO,EAAE,CAAC;CACtC;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,gBAAgB,GAAG,aAAa,CAgBxE;AAED,2EAA2E;AAC3E,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,EAAE,gBAAgB,KAAK,aAAa,CAAC"}

package/dist/define_ag_ui_chat.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Register the `<ag-ui-chat>` Custom Element.
+ *
+ * Idempotent: calling it more than once (or after another module already
+ * registered the tag) is a no-op. Registration is an explicit step rather
+ * than an import side effect so the package is SSR-safe and tree-shakeable.
+ */
+export declare function defineAgUiChat(): void;
+//# sourceMappingURL=define_ag_ui_chat.d.ts.map

package/dist/define_ag_ui_chat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define_ag_ui_chat.d.ts","sourceRoot":"","sources":["../src/define_ag_ui_chat.ts"],"names":[],"mappings":"AAGA;;;;;;GAMG;AACH,wBAAgB,cAAc,IAAI,IAAI,CAIrC"}

package/dist/dom_driver.d.ts

@@ -0,0 +1,24 @@
+import { type HighlightClickOptions, type TextLikeElement, type TypeOptions } from "./animations.js";
+/**
+ * Generic, framework-free DOM-driving primitives.
+ *
+ * Each operates on an element the caller has already located. Host packages
+ * (e.g. `django-admin-agent`) wrap these with environment-aware lookups —
+ * `fill_field(name, value)` finds `#id_<name>` then calls {@link fillField}.
+ */
+export interface FillFieldOptions extends TypeOptions, FlashOptionsLike {
+}
+interface FlashOptionsLike {
+    flashMs?: number;
+}
+/** Scroll to, focus (with a flash), and type ``value`` into a text field. */
+export declare function fillField(el: TextLikeElement, value: string, options?: FillFieldOptions): Promise<void>;
+/** Scroll to, highlight, and click an element. */
+export declare function clickElement(el: HTMLElement, options?: HighlightClickOptions): Promise<void>;
+/**
+ * Set a `<select>` or checkbox value without typing animation, dispatching the
+ * ``input`` and ``change`` events frameworks listen for.
+ */
+export declare function setControlValue(el: HTMLInputElement | HTMLSelectElement, value: string | boolean): void;
+export {};
+//# sourceMappingURL=dom_driver.d.ts.map

package/dist/dom_driver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dom_driver.d.ts","sourceRoot":"","sources":["../src/dom_driver.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,qBAAqB,EAG1B,KAAK,eAAe,EACpB,KAAK,WAAW,EAEjB,MAAM,iBAAiB,CAAC;AAEzB;;;;;;GAMG;AAEH,MAAM,WAAW,gBAAiB,SAAQ,WAAW,EAAE,gBAAgB;CAAG;AAE1E,UAAU,gBAAgB;IACxB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,6EAA6E;AAC7E,wBAAsB,SAAS,CAC7B,EAAE,EAAE,eAAe,EACnB,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC,IAAI,CAAC,CAIf;AAED,kDAAkD;AAClD,wBAAsB,YAAY,CAChC,EAAE,EAAE,WAAW,EACf,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,IAAI,CAAC,CAGf;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,EAAE,EAAE,gBAAgB,GAAG,iBAAiB,EACxC,KAAK,EAAE,MAAM,GAAG,OAAO,GACtB,IAAI,CAQN"}

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+export { AgUiChat, type MessageRole, type SubmitDetail } from "./ag_ui_chat.js";
+export { AgUiClient, type AgUiClientConfig, type AgUiClientHandlers, type AgUiRunInputs, type AgUiToolCall, type ExecuteTool, type ToolExecution, } from "./agui_client.js";
+export { type FlashOptions, focusWithFlash, type HighlightClickOptions, highlightThenClick, scrollIntoCenterView, type TextLikeElement, type TypeOptions, typeInto, } from "./animations.js";
+export { type ClientTool, ClientToolRegistry } from "./client_tool_registry.js";
+export { type ConfirmationRequest, requestConfirmation } from "./confirmation_modal.js";
+export { ELEMENT_TAG, MAX_TOOL_ROUNDS, MESSAGE_ROLE, SUBMIT_EVENT, TOOL_CALL_STATUS, X_DESTRUCTIVE_KEY, X_NAVIGATES_KEY, } from "./constants.js";
+export { type ClientConversationStore, type NavigationCheckpoint, SessionStorageStore, } from "./conversation_store.js";
+export { type AgentFactory, createHttpAgent, type HttpAgentOptions, } from "./create_http_agent.js";
+export { defineAgUiChat } from "./define_ag_ui_chat.js";
+export { clickElement, type FillFieldOptions, fillField, setControlValue, } from "./dom_driver.js";
+export { isDestructive } from "./is_destructive.js";
+export { isNavigates } from "./is_navigates.js";
+export { createPageMapContext, type PageMap } from "./page_map.js";
+export { createRouteTools, type Route, type RouteMap } from "./route_map.js";
+export { createStateHookTools, type StateHook } from "./state_hook.js";
+export { type SettledStatus, ToolCallCard, type ToolCallStatus, } from "./tool_call_card.js";
+export { VERSION } from "./version.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,KAAK,WAAW,EAAE,KAAK,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAChF,OAAO,EACL,UAAU,EACV,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,EACvB,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,KAAK,aAAa,GACnB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,KAAK,YAAY,EACjB,cAAc,EACd,KAAK,qBAAqB,EAC1B,kBAAkB,EAClB,oBAAoB,EACpB,KAAK,eAAe,EACpB,KAAK,WAAW,EAChB,QAAQ,GACT,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,KAAK,UAAU,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAChF,OAAO,EAAE,KAAK,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AACxF,OAAO,EACL,WAAW,EACX,eAAe,EACf,YAAY,EACZ,YAAY,EACZ,gBAAgB,EAChB,iBAAiB,EACjB,eAAe,GAChB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,KAAK,uBAAuB,EAC5B,KAAK,oBAAoB,EACzB,mBAAmB,GACpB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EACL,KAAK,YAAY,EACjB,eAAe,EACf,KAAK,gBAAgB,GACtB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,EACL,YAAY,EACZ,KAAK,gBAAgB,EACrB,SAAS,EACT,eAAe,GAChB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,oBAAoB,EAAE,KAAK,OAAO,EAAE,MAAM,eAAe,CAAC;AACnE,OAAO,EAAE,gBAAgB,EAAE,KAAK,KAAK,EAAE,KAAK,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC7E,OAAO,EAAE,oBAAoB,EAAE,KAAK,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACvE,OAAO,EACL,KAAK,aAAa,EAClB,YAAY,EACZ,KAAK,cAAc,GACpB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC"}