@artooi/ag-ui-web-component 0.28.0 → 0.29.0

package/dist/ui/approval_card.d.ts

@@ -9,6 +9,11 @@ export interface ApprovalRequest {
     message?: string;
     /** Tool name, surfaced as a `data-tool-name` attribute for styling/tests. */
     toolName?: string;
+    /**
+     * The call's arguments, shown for editing when {@link ApprovalOptions.onEdit}
+     * is set. Omitted when the interrupt names no call whose arguments are known.
+     */
+    args?: Record<string, unknown>;
 }
 /** Options for {@link requestApproval}. */
 export interface ApprovalOptions {
@@ -19,6 +24,19 @@ export interface ApprovalOptions {
     signal?: AbortSignal;
     /** Localized strings; defaults to the English {@link DEFAULT_UI_STRINGS}. */
     strings?: UiStrings;
+    /**
+     * Offer the call's arguments for editing, and receive what the user approved.
+     *
+     * Called **only** on approval, and only when the text parses and differs from
+     * what was proposed -- an untouched call resolves as a plain approval, so a
+     * server sees `editedArgs` exactly when something was actually edited.
+     *
+     * Absent means no editor, which is deliberate: AG-UI gates this on the
+     * agent's own `approveWithEdits` capability, and a card that let a user
+     * rewrite arguments a server will discard is worse than one that does not
+     * offer to.
+     */
+    onEdit?: (args: Record<string, unknown>) => void;
 }
 /**
  * A fully custom renderer for a server-side-tool approval, set via

package/dist/ui/approval_card.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"approval_card.d.ts","sourceRoot":"","sources":["../../src/ui/approval_card.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsB,KAAK,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAErE,iFAAiF;AACjF,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAYD,2CAA2C;AAC3C,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,6EAA6E;IAC7E,OAAO,CAAC,EAAE,SAAS,CAAC;CACrB;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAC7B,OAAO,EAAE,eAAe,EACxB,OAAO,EAAE;IAAE,MAAM,EAAE,WAAW,CAAA;CAAE,KAC7B,OAAO,CAAC,OAAO,CAAC,CAAC;AAEtB;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,IAAI,GAAG,UAAU,EACvB,OAAO,EAAE,eAAe,EACxB,OAAO,GAAE,eAAoB,GAC5B,OAAO,CAAC,OAAO,CAAC,CAkDlB"}
+{"version":3,"file":"approval_card.d.ts","sourceRoot":"","sources":["../../src/ui/approval_card.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsB,KAAK,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAErE,iFAAiF;AACjF,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAYD,2CAA2C;AAC3C,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,6EAA6E;IAC7E,OAAO,CAAC,EAAE,SAAS,CAAC;IACpB;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;CAClD;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAC7B,OAAO,EAAE,eAAe,EACxB,OAAO,EAAE;IAAE,MAAM,EAAE,WAAW,CAAA;CAAE,KAC7B,OAAO,CAAC,OAAO,CAAC,CAAC;AAEtB;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,IAAI,GAAG,UAAU,EACvB,OAAO,EAAE,eAAe,EACxB,OAAO,GAAE,eAAoB,GAC5B,OAAO,CAAC,OAAO,CAAC,CA4DlB"}

package/dist/ui/checkpoint_menu.d.ts

@@ -1,4 +1,5 @@
 import type { RunRow } from "../core/run_index.js";
+import { type RelativeTimeFormatter } from "./relative_time.js";
 import { type UiStrings } from "./ui_strings.js";
 /** How the host continues a picked run. */
 export type CheckpointVerb = "resume" | "fork";
@@ -23,6 +24,15 @@ export declare class CheckpointMenu {
     /** Replace the rows. The host passes only `continuable` runs. */
     setRuns(runs: readonly RunRow[]): void;
     /** Re-localize a panel built before the host's strings resolved. */
+    /**
+     * Replace the timestamp formatter, or restore the built-in with `null`.
+     *
+     * The built-in is deliberately locale-neutral -- there is no `Intl` anywhere
+     * in this component, so it never disagrees with a host's own formatting by
+     * guessing a locale. That is a defensible default and a poor requirement, so
+     * this is the way out.
+     */
+    setRelativeTimeFormatter(format: RelativeTimeFormatter | null): void;
     setStrings(strings: UiStrings): void;
     open(): void;
     close(): void;

package/dist/ui/checkpoint_menu.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"checkpoint_menu.d.ts","sourceRoot":"","sources":["../../src/ui/checkpoint_menu.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAEnD,OAAO,EAAsB,KAAK,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAErE,2CAA2C;AAC3C,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,MAAM,CAAC;AAqB/C;;;;;;;;;;;;GAYG;AACH,qBAAa,cAAc;;IACzB,qEAAqE;IACrE,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC;IAUjC,YACE,MAAM,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,KAAK,IAAI,EACrD,OAAO,GAAE,SAA8B,EA+BxC;IAED,iEAAiE;IACjE,OAAO,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAGrC;IAED,oEAAoE;IACpE,UAAU,CAAC,OAAO,EAAE,SAAS,GAAG,IAAI,CAKnC;IAED,IAAI,IAAI,IAAI,CAYX;IAED,KAAK,IAAI,IAAI,CAOZ;IAqCD,IAAI,KAAK,IAAI,OAAO,CAEnB;CAuHF"}
+{"version":3,"file":"checkpoint_menu.d.ts","sourceRoot":"","sources":["../../src/ui/checkpoint_menu.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AACnD,OAAO,EAAE,KAAK,qBAAqB,EAAgB,MAAM,oBAAoB,CAAC;AAC9E,OAAO,EAAsB,KAAK,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAErE,2CAA2C;AAC3C,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,MAAM,CAAC;AAqB/C;;;;;;;;;;;;GAYG;AACH,qBAAa,cAAc;;IACzB,qEAAqE;IACrE,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC;IAWjC,YACE,MAAM,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,KAAK,IAAI,EACrD,OAAO,GAAE,SAA8B,EA+BxC;IAED,iEAAiE;IACjE,OAAO,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAGrC;IAED,oEAAoE;IACpE;;;;;;;OAOG;IACH,wBAAwB,CAAC,MAAM,EAAE,qBAAqB,GAAG,IAAI,GAAG,IAAI,CAEnE;IASD,UAAU,CAAC,OAAO,EAAE,SAAS,GAAG,IAAI,CAKnC;IAED,IAAI,IAAI,IAAI,CAYX;IAED,KAAK,IAAI,IAAI,CAOZ;IAqCD,IAAI,KAAK,IAAI,OAAO,CAEnB;CAoHF"}

package/dist/ui/confirmation_card.d.ts

@@ -19,6 +19,16 @@ export interface ConfirmationOptions {
     signal?: AbortSignal;
     /** Localized strings; defaults to the English {@link DEFAULT_UI_STRINGS}. */
     strings?: UiStrings;
+    /**
+     * Offer a third button — "always allow, this session" — and call this when
+     * the user picks it. The card still resolves `true`: the extra decision is
+     * *in addition to* approving this call, not instead of it.
+     *
+     * Absent means no button, which is deliberate: presence of the handler is
+     * what enables it, so the affordance can never be rendered with nothing
+     * listening. A caller that cannot honour the waiver simply does not pass one.
+     */
+    onAlwaysAllow?: () => void;
 }
 /**
  * Append an inline confirmation card to `host` (the chat message list) and
@@ -30,6 +40,12 @@ export interface ConfirmationOptions {
  * Answering it removes it: the record of the decision belongs to the tool card
  * this gates, which settles to `done` or `declined` and carries it. A spent
  * form left in place reads as still outstanding.
+ *
+ * With `onAlwaysAllow` set the card offers a third button. A prompt that is
+ * approved nearly every time is not a decision, it is a speed bump — and the
+ * reflex it trains is what makes the rare refusal easy to miss. Letting the
+ * user say "not this one again, this session" is the affordance that keeps the
+ * remaining prompts meaningful.
  */
 export declare function requestConfirmation(host: Node & ParentNode, request: ConfirmationRequest, options?: ConfirmationOptions): Promise<boolean>;
 //# sourceMappingURL=confirmation_card.d.ts.map

package/dist/ui/confirmation_card.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"confirmation_card.d.ts","sourceRoot":"","sources":["../../src/ui/confirmation_card.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsB,KAAK,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAErE,kDAAkD;AAClD,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAYD,+CAA+C;AAC/C,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,6EAA6E;IAC7E,OAAO,CAAC,EAAE,SAAS,CAAC;CACrB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,IAAI,GAAG,UAAU,EACvB,OAAO,EAAE,mBAAmB,EAC5B,OAAO,GAAE,mBAAwB,GAChC,OAAO,CAAC,OAAO,CAAC,CAyDlB"}
+{"version":3,"file":"confirmation_card.d.ts","sourceRoot":"","sources":["../../src/ui/confirmation_card.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsB,KAAK,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAErE,kDAAkD;AAClD,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAYD,+CAA+C;AAC/C,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,6EAA6E;IAC7E,OAAO,CAAC,EAAE,SAAS,CAAC;IACpB;;;;;;;;OAQG;IACH,aAAa,CAAC,EAAE,MAAM,IAAI,CAAC;CAC5B;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,IAAI,GAAG,UAAU,EACvB,OAAO,EAAE,mBAAmB,EAC5B,OAAO,GAAE,mBAAwB,GAChC,OAAO,CAAC,OAAO,CAAC,CAqElB"}

package/dist/ui/message_actions.d.ts

@@ -0,0 +1,46 @@
+import type { UiStrings } from "./ui_strings.js";
+/** What an action bar can do, beyond copying. */
+export interface MessageActionsOptions {
+    /** Localized strings. */
+    strings: UiStrings;
+    /**
+     * The text Copy puts on the clipboard. A function rather than a string
+     * because a bubble's content is rewritten while it streams, and the bar is
+     * attached to the element rather than to a snapshot of it.
+     */
+    text: () => string;
+    /**
+     * Report a rating for this message. Absent means no feedback buttons.
+     *
+     * The component stores nothing: a rating is the host's to keep, and a
+     * write-only table nobody reads is not worth a schema.
+     */
+    onFeedback?: (rating: "up" | "down") => void;
+}
+/**
+ * Give one finished message bubble its row of actions.
+ *
+ * **Finished** is load-bearing. A streaming bubble reassigns its `innerHTML` on
+ * every delta, so anything attached mid-stream is discarded and rebuilt for
+ * each one -- the same constraint `attachCopyButtons` records, one level up.
+ *
+ * Retry is deliberately **not** here: it belongs to the last turn only, so the
+ * element owns it and moves it as the transcript grows. Everything on this bar
+ * is safe to offer on any message, however old.
+ *
+ * Idempotent -- a bubble already given a bar is skipped, so a re-render or a
+ * second call cannot stack rows.
+ */
+export declare function attachMessageActions(bubble: HTMLElement, options: MessageActionsOptions): void;
+/**
+ * The empty action row on `bubble`, created if it has none yet.
+ *
+ * Shared so a bubble that wants *only* Retry -- a failed run, which has nothing
+ * worth copying and nothing to rate -- gets the same row, the same part name
+ * and the same accessible grouping as every other message, rather than a
+ * second thing that looks like one.
+ */
+export declare function messageActionBar(bubble: HTMLElement, strings: UiStrings): HTMLElement;
+/** Build one action button, labelled for screen readers rather than by glyph. */
+export declare function messageActionButton(modifier: string, label: string, glyph: string): HTMLButtonElement;
+//# sourceMappingURL=message_actions.d.ts.map

package/dist/ui/message_actions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"message_actions.d.ts","sourceRoot":"","sources":["../../src/ui/message_actions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAKjD,iDAAiD;AACjD,MAAM,WAAW,qBAAqB;IACpC,yBAAyB;IACzB,OAAO,EAAE,SAAS,CAAC;IACnB;;;;OAIG;IACH,IAAI,EAAE,MAAM,MAAM,CAAC;IACnB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,CAAC,MAAM,EAAE,IAAI,GAAG,MAAM,KAAK,IAAI,CAAC;CAC9C;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,qBAAqB,GAAG,IAAI,CAY9F;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,SAAS,GAAG,WAAW,CAmBrF;AAQD,iFAAiF;AACjF,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,GACZ,iBAAiB,CAYnB"}

package/dist/ui/page_quote_offer.d.ts

@@ -0,0 +1,33 @@
+/** A live page-side offer. */
+export interface PageQuoteOffer {
+    /** The button itself, for a host that wants to style or inspect it. */
+    readonly element: HTMLButtonElement;
+    /** Stop offering: every listener removed, the button and its styles gone. */
+    detach(): void;
+}
+/** What {@link attachQuoteOffer} needs to know. */
+export interface PageQuoteOfferOptions {
+    /** Where a selection is worth offering to quote. */
+    within: HTMLElement;
+    /** What the offer says. */
+    label: string;
+    /**
+     * A subtree to stay out of -- the chat widget itself.
+     *
+     * Its transcript runs this same gesture on the inside, so without this a
+     * selection there would be offered twice and quoted twice.
+     */
+    exclude: Node;
+    /** Take the offer. */
+    onQuote: (text: string) => void;
+}
+/**
+ * Offer to quote what the user selects inside `within`.
+ *
+ * Nothing is quoted until the offer is taken -- which is the whole point. An
+ * automatic version of this is easy to write and horrible to use: every drag
+ * made to read, to copy, or to fix a typo silently appends to whatever the user
+ * was in the middle of typing.
+ */
+export declare function attachQuoteOffer(options: PageQuoteOfferOptions): PageQuoteOffer;
+//# sourceMappingURL=page_quote_offer.d.ts.map

package/dist/ui/page_quote_offer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"page_quote_offer.d.ts","sourceRoot":"","sources":["../../src/ui/page_quote_offer.ts"],"names":[],"mappings":"AAuDA,8BAA8B;AAC9B,MAAM,WAAW,cAAc;IAC7B,uEAAuE;IACvE,QAAQ,CAAC,OAAO,EAAE,iBAAiB,CAAC;IACpC,6EAA6E;IAC7E,MAAM,IAAI,IAAI,CAAC;CAChB;AAED,mDAAmD;AACnD,MAAM,WAAW,qBAAqB;IACpC,oDAAoD;IACpD,MAAM,EAAE,WAAW,CAAC;IACpB,2BAA2B;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,OAAO,EAAE,IAAI,CAAC;IACd,sBAAsB;IACtB,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CACjC;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,qBAAqB,GAAG,cAAc,CA4F/E"}

package/dist/ui/quote_selection.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Reading a text selection out of the shadow tree, and shaping it for the
+ * composer.
+ *
+ * Selection is the one DOM API shadow encapsulation genuinely broke, and it
+ * broke it in two different directions. WebKit rescopes a selection made inside
+ * a shadow tree to the **host** element, so `document.getSelection()` reports
+ * the whole widget and none of the words; Chromium exposes the shadow nodes
+ * directly, so the same call reports exactly the words. `getComposedRanges` is
+ * the settled answer to both -- it hands back real endpoints for each shadow
+ * root it is *given permission to see* -- but it is recent enough that the
+ * direct read has to stay behind it.
+ */
+/**
+ * The longest quotation put into the composer, in characters.
+ *
+ * A cap rather than no cap because the point of a quotation is to say *which*
+ * part of an answer the next question is about. Select-all-then-quote is a
+ * gesture the transcript already answers -- it is the whole conversation, which
+ * the model has -- and pasting it back costs the user tokens to say nothing.
+ */
+export declare const MAX_QUOTE_CHARS = 500;
+/** A selection worth offering to quote. */
+export interface QuotableSelection {
+    /** The selected text, trimmed. Never empty. */
+    readonly text: string;
+    /**
+     * One **line** of the selection, for placing the affordance beside it.
+     *
+     * Deliberately not the selection's bounding box. See {@link lineToHangFrom}:
+     * the union of a selection spanning several elements has a centre with no
+     * selected text anywhere near it.
+     */
+    readonly rect: DOMRect;
+}
+/** Where a gesture ended, in viewport coordinates. */
+export interface Point {
+    readonly x: number;
+    readonly y: number;
+}
+/**
+ * The current selection, when it lies wholly inside `container`.
+ *
+ * `roots` are the shadow roots the read is allowed to look inside, in the shape
+ * `getComposedRanges` itself takes. Pass the one holding `container` for a
+ * selection made in a shadow tree, or nothing at all for one made in the page.
+ *
+ * `near` is where the gesture ended, when a pointer made it -- it decides which
+ * line of a multi-line selection the offer is hung from.
+ *
+ * `null` for no selection, a collapsed one, whitespace only, or one that
+ * starts or ends outside `container` -- a drag that ran off the transcript and
+ * into the page is not a quotation from the transcript.
+ */
+export declare function quotableSelection(container: HTMLElement, roots?: readonly ShadowRoot[], near?: Point): QuotableSelection | null;
+/**
+ * Wrap `text` as a markdown blockquote, ready to be followed by a question.
+ *
+ * Markdown rather than a bespoke fence because the transcript renders markdown
+ * and the server reads markdown: a quotation that survives both ends without a
+ * convention to agree on first. The trailing blank line is what leaves the
+ * caret on a fresh paragraph, which is the whole point of quoting into a
+ * composer rather than sending straight away.
+ */
+export declare function asQuote(text: string): string;
+//# sourceMappingURL=quote_selection.d.ts.map

package/dist/ui/quote_selection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"quote_selection.d.ts","sourceRoot":"","sources":["../../src/ui/quote_selection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,MAAM,CAAC;AAEnC,2CAA2C;AAC3C,MAAM,WAAW,iBAAiB;IAChC,+CAA+C;IAC/C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;;;OAMG;IACH,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;CACxB;AAED,sDAAsD;AACtD,MAAM,WAAW,KAAK;IACpB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;CACpB;AAOD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,WAAW,EACtB,KAAK,GAAE,SAAS,UAAU,EAAO,EACjC,IAAI,CAAC,EAAE,KAAK,GACX,iBAAiB,GAAG,IAAI,CAqB1B;AAED;;;;;;;;GAQG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAa5C"}

package/dist/ui/relative_time.d.ts

@@ -10,4 +10,14 @@ import { type UiStrings } from "./ui_strings.js";
  * filled in here; the bucketing stays integer-rounded and locale-neutral.
  */
 export declare function relativeTime(timestamp: number, now?: number, strings?: UiStrings): string;
+/**
+ * A host's replacement for {@link relativeTime}.
+ *
+ * Takes an epoch-milliseconds timestamp and returns the text a row shows.
+ * `Intl.RelativeTimeFormat` is the obvious implementation and is deliberately
+ * *not* the default: a component that guessed a locale would disagree with the
+ * host page's own formatting, and being wrong in a second language is worse
+ * than being neutral in one.
+ */
+export type RelativeTimeFormatter = (timestamp: number) => string;
 //# sourceMappingURL=relative_time.d.ts.map

package/dist/ui/relative_time.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"relative_time.d.ts","sourceRoot":"","sources":["../../src/ui/relative_time.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsB,KAAK,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAErE;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAC1B,SAAS,EAAE,MAAM,EACjB,GAAG,GAAE,MAAmB,EACxB,OAAO,GAAE,SAA8B,GACtC,MAAM,CAqBR"}
+{"version":3,"file":"relative_time.d.ts","sourceRoot":"","sources":["../../src/ui/relative_time.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsB,KAAK,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAErE;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAC1B,SAAS,EAAE,MAAM,EACjB,GAAG,GAAE,MAAmB,EACxB,OAAO,GAAE,SAA8B,GACtC,MAAM,CAqBR;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,qBAAqB,GAAG,CAAC,SAAS,EAAE,MAAM,KAAK,MAAM,CAAC"}

package/dist/ui/stick_to_bottom.d.ts

@@ -0,0 +1,55 @@
+/** A transcript that follows new content, unless the reader has other ideas. */
+export interface StickToBottom {
+    /**
+     * New content arrived. Scrolls to the bottom only while following, so
+     * reading older messages during a run is no longer undone on the next token.
+     */
+    readonly follow: () => void;
+    /** Go to the bottom and resume following, whatever the reader was doing. */
+    readonly jump: () => void;
+    /** Whether the transcript is currently following new content. */
+    readonly following: () => boolean;
+    readonly dispose: () => void;
+}
+export interface StickToBottomOptions {
+    /** The scrolling element -- the message list. */
+    readonly viewport: HTMLElement;
+    /**
+     * Called whenever the answer to "should a jump-to-latest affordance show?"
+     * changes. True means the reader has scrolled away *and* has since missed
+     * something; scrolling up through a settled transcript is not a reason to
+     * nag.
+     */
+    readonly onMissedContent: (missed: boolean) => void;
+}
+/**
+ * Follow the foot of a scrolling transcript, and stop when the reader scrolls
+ * away.
+ *
+ * Before this, eleven separate sites assigned `scrollTop = scrollHeight`
+ * unconditionally and nothing anywhere listened for a `scroll` event -- so
+ * nothing knew the reader had scrolled up, and scrolling back through a run was
+ * undone by the next token. Stick-to-bottom with a jump-to-latest affordance is
+ * a named primitive elsewhere for exactly this reason: shadcn ships it as
+ * `MessageScroller`, AI Elements as `ConversationScrollButton`.
+ *
+ * **Telling a reader's scroll from our own is the whole problem**, and the
+ * answer here is that it does not have to be told. A programmatic scroll only
+ * ever happens while already following, and it lands at the bottom, so the
+ * `scroll` event it provokes recomputes "at the bottom" as true and changes
+ * nothing. A reader's scroll is the only kind that can move the answer.
+ *
+ * A `ResizeObserver` covers the case scroll events cannot see: the *viewport*
+ * changing size. Resizing the panel, or the keyboard opening on a phone, moves
+ * the foot without anything scrolling and without any content arriving, so a
+ * pinned transcript would silently come unpinned.
+ *
+ * ⚠ It does **not** cover content that grows after insertion -- an image
+ * decoding, a chart laying out. A `ResizeObserver` on a scroll container does
+ * not fire when its `scrollHeight` changes, so catching that means observing
+ * every child, and the payoff is one late nudge in a case the reader can fix by
+ * scrolling. Insertion itself is covered: every site that adds to the
+ * transcript calls {@link StickToBottom.follow}.
+ */
+export declare function createStickToBottom({ viewport, onMissedContent, }: StickToBottomOptions): StickToBottom;
+//# sourceMappingURL=stick_to_bottom.d.ts.map

package/dist/ui/stick_to_bottom.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stick_to_bottom.d.ts","sourceRoot":"","sources":["../../src/ui/stick_to_bottom.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,MAAM,WAAW,aAAa;IAC5B;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,IAAI,CAAC;IAC5B,4EAA4E;IAC5E,QAAQ,CAAC,IAAI,EAAE,MAAM,IAAI,CAAC;IAC1B,iEAAiE;IACjE,QAAQ,CAAC,SAAS,EAAE,MAAM,OAAO,CAAC;IAClC,QAAQ,CAAC,OAAO,EAAE,MAAM,IAAI,CAAC;CAC9B;AAED,MAAM,WAAW,oBAAoB;IACnC,iDAAiD;IACjD,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC;IAC/B;;;;;OAKG;IACH,QAAQ,CAAC,eAAe,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;CACrD;AAWD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,mBAAmB,CAAC,EAClC,QAAQ,EACR,eAAe,GAChB,EAAE,oBAAoB,GAAG,aAAa,CA0DtC"}