@artooi/agents-web-components 0.0.0-stage → 0.1.0

package/dist/ui/placement/panel_placement.d.ts

@@ -0,0 +1,173 @@
+import type { ChatCorner, ChatSurfaceReport } from "../../tools/chat_surface_tools.js";
+import type { UiStrings } from "../ui_strings.js";
+/**
+ * What the placement needs from the element that owns it.
+ *
+ * Everything the element keeps private is reached through a thunk here, the
+ * same shape `PanelDragOptions` and `ResizeOptions` already give their hosts:
+ * read per call, so a value the element replaces later (the resolved string
+ * table, the connected flag) is never captured stale.
+ */
+export interface PlacementHost {
+    /** The custom element itself: its inline style, attributes and box. */
+    readonly element: HTMLElement;
+    /** The collapsed widget's button, which a drag moves and a resize carries. */
+    readonly launcher: HTMLButtonElement;
+    /** The shadow root, searched for a header mid-drag. */
+    readonly root: ShadowRoot;
+    /** Whether the element is in the document. */
+    readonly connected: () => boolean;
+    /** Whether the widget is collapsed. */
+    readonly collapsed: () => boolean;
+    /** Whether the current placement has a collapsed state at all. */
+    readonly collapsible: () => boolean;
+    /** The resolved string table. */
+    readonly strings: () => UiStrings;
+    /** Read a layout preference, durable store first. */
+    readonly readPreference: (base: string) => string | null;
+    /** Persist a layout preference to both stores. */
+    readonly writePreference: (base: string, value: string) => void;
+    /** Drop a layout preference from both stores. */
+    readonly clearPreference: (base: string) => void;
+    /** Tell the reader the agent moved their window, with the way back. */
+    readonly announceSurfaceChange: (text: string, undo: () => void) => void;
+}
+/**
+ * Where the panel and its launcher sit, and how big the panel is: the dragged
+ * launcher, the dragged header, the eight resize grips, the corner the panel
+ * opens from, and the persisted record of all of it.
+ *
+ * Owned one-to-one by an `<ag-ui-chat>`, and holding no state outside the
+ * instance, so two elements on a page place themselves independently.
+ */
+export declare class PanelPlacement {
+    #private;
+    constructor(host: PlacementHost);
+    /**
+     * Make the header a title bar. Only while open: a collapsed widget has no
+     * header on screen, and the launcher is the handle then.
+     */
+    enablePanelDrag(header: HTMLElement): void;
+    /**
+     * Let the launcher be dragged. Only while collapsed: the launcher is scaled
+     * away and unclickable behind the open panel, so a drag there would move
+     * something nobody can see.
+     */
+    enableLauncherDrag(signal: AbortSignal): void;
+    /** Build the eight resize grips into `chat`, with one of them in the tab order. */
+    mountResizeGrips(chat: HTMLElement): void;
+    /** Restore the current placement's dragged size before the panel paints. */
+    restoreSize(): void;
+    /**
+     * Swap the dragged size for the one stored under the placement just set, so a
+     * floating drag never sizes a sidebar. Between two corner placements a stated
+     * spot moves with the size, as on resetSize, so the launcher keeps its corner.
+     * Before connect the namespace is unclaimed, and connect restores the size.
+     */
+    switchPlacement(previous: string | null): void;
+    /**
+     * Drop the current placement's dragged size and its stored copy, so the
+     * placement's own size and the host's tokens apply again; other placements
+     * keep theirs. For a host entering a sized state of its
+     * own, which a user's drag would otherwise outrank.
+     *
+     * A docked panel the user dragged off its dock goes back to it as well, and
+     * the stored spot with it: there the position is part of the same resting
+     * state the host is asking for. A corner panel keeps a dragged position, as
+     * it always has.
+     */
+    resetSize(): void;
+    /**
+     * Stand the larger panel back on the screen once the element has stamped the
+     * maximized state, whose rules size the box outright, over any dragged size
+     * still held inline. The stored size and every stored spot are kept: restore
+     * puts them back.
+     */
+    enterMaximized(): void;
+    /** Put the stored size back once the element has left the maximized state. */
+    leaveMaximized(): void;
+    /**
+     * A zero-sized box carrying the host's viewport insets as padding, so they
+     * can be read back as used pixel lengths. See the `.viewport-probe` rule for
+     * why a custom property cannot be read directly.
+     */
+    readonly probe: HTMLDivElement;
+    /**
+     * Whether a pointer or key gesture is currently placing the widget.
+     *
+     * Read from the stamp the drag helpers already set, rather than tracked
+     * separately: one source of truth, and it clears on `pointercancel` as well
+     * as `pointerup`, which is the end a touch gesture usually gets. The one
+     * gesture that stamps nothing is an arrow key on a grip, which applies a box
+     * per key and states it only when the key comes up, hence #resizing.
+     */
+    dragging(): boolean;
+    /** The report behind `AgUiChat.describeSurface`, whose doc is the contract. */
+    describeSurface(): ChatSurfaceReport;
+    /** The move behind `AgUiChat.moveTo`, whose doc is the contract. */
+    moveTo(corner: ChatCorner, options?: {
+        readonly announce?: boolean;
+    }): boolean;
+    /** Stamp the measured anchor so the shadow CSS can place the grip. */
+    syncResizeAnchor(): void;
+    /**
+     * Drop any dragged size the new placement has taken ownership of.
+     *
+     * Without this a size survives the switch as an inline property and silently
+     * overrides the placement it moved to — the panel keeps a floating height
+     * while docked, and reads as a component that cannot do full height.
+     */
+    releaseOwnedAxes(): void;
+    /**
+     * Write where a docked panel stands, and return the bar's height.
+     *
+     * Under the bar it is the strip's border box, which is 0 whenever the strip
+     * is not drawn (a phone with the panel open, where the panel is the screen).
+     * Under a host anchor it is the anchor's top, or its bottom on the side below,
+     * and its right, measured against the
+     * layout viewport a fixed element is placed in; an anchor of null leaves the
+     * panel in its placement's own corner. Every other surface carries neither
+     * property, so nothing stale is left behind by a live switch.
+     */
+    syncDock(bar: HTMLElement, anchor: Element | null): number;
+    /**
+     * Publish the measured viewport height so the stylesheet can size a
+     * full-bleed panel to what the user can see.
+     *
+     * No CSS length carries this. An on-screen keyboard has no effect on any
+     * viewport-percentage unit, so a panel sized from `100dvh` puts its composer
+     * behind the keyboard being typed into. Written inline, and read through a
+     * token the host's own `--ag-ui-viewport-height` still outranks.
+     *
+     * Removed rather than frozen when the two viewports agree, so a desktop that
+     * never diverges carries no inline override at all and the declared fallback
+     * stays in charge.
+     */
+    publishVisualViewport(): void;
+    /**
+     * Re-apply the dragged position against the current viewport: on connect,
+     * whenever the window resizes, and before an expand. The viewport that
+     * stored a position may since have shrunk, and a launcher past the edge is
+     * unreachable -- it is the only way back to a collapsed conversation.
+     *
+     * The one gate on whether a stored position is this element's to honour: the
+     * gestures check their own before they ever reach the placing below.
+     */
+    restoreLauncherPosition(): void;
+    /**
+     * Re-apply it for a change in the panel's own layout, which needs no window or
+     * reopen to happen: a line typed in the composer is one. A position waiting to
+     * be handed back under data-launcher-drag="false" waits on, because a panel that leaves for the
+     * host's corner as the reader starts typing is a jump with no cause they can see.
+     * It waits no longer than the panel stays on the screen: a host's size can stand
+     * it off an edge, where its header is out of reach until something else happens.
+     */
+    settleLauncherPosition(): void;
+    /**
+     * Give the position back to the host when the new placement owns it, the way
+     * releaseOwnedAxes gives back a size. Without this a dragged inset survives
+     * the switch inline and pins a sidebar to wherever the floating launcher was.
+     */
+    releaseLauncherPosition(): void;
+}
+//# sourceMappingURL=panel_placement.d.ts.map

package/dist/ui/placement/panel_placement.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"panel_placement.d.ts","sourceRoot":"","sources":["../../../src/ui/placement/panel_placement.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,mCAAmC,CAAC;AACvF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAwKlD;;;;;;;GAOG;AACH,MAAM,WAAW,aAAa;IAC5B,uEAAuE;IACvE,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC;IAC9B,8EAA8E;IAC9E,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,CAAC;IACrC,uDAAuD;IACvD,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,8CAA8C;IAC9C,QAAQ,CAAC,SAAS,EAAE,MAAM,OAAO,CAAC;IAClC,uCAAuC;IACvC,QAAQ,CAAC,SAAS,EAAE,MAAM,OAAO,CAAC;IAClC,kEAAkE;IAClE,QAAQ,CAAC,WAAW,EAAE,MAAM,OAAO,CAAC;IACpC,iCAAiC;IACjC,QAAQ,CAAC,OAAO,EAAE,MAAM,SAAS,CAAC;IAClC,qDAAqD;IACrD,QAAQ,CAAC,cAAc,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;IACzD,kDAAkD;IAClD,QAAQ,CAAC,eAAe,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAChE,iDAAiD;IACjD,QAAQ,CAAC,eAAe,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACjD,uEAAuE;IACvE,QAAQ,CAAC,qBAAqB,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,IAAI,KAAK,IAAI,CAAC;CAC1E;AAED;;;;;;;GAOG;AACH,qBAAa,cAAc;;IAGzB,YAAY,IAAI,EAAE,aAAa,EAE9B;IAED;;;OAGG;IACH,eAAe,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI,CAQzC;IAED;;;;OAIG;IACH,kBAAkB,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI,CAS5C;IAED,mFAAmF;IACnF,gBAAgB,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI,CA6BxC;IAED,4EAA4E;IAC5E,WAAW,IAAI,IAAI,CAKlB;IAED;;;;;OAKG;IACH,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAY7C;IAED;;;;;;;;;;OAUG;IACH,SAAS,IAAI,IAAI,CAoBhB;IAED;;;;;OAKG;IACH,cAAc,IAAI,IAAI,CAErB;IAED,8EAA8E;IAC9E,cAAc,IAAI,IAAI,CAGrB;IAqDD;;;;OAIG;IACH,QAAQ,CAAC,KAAK,iBAAiC;IA6I/C;;;;;;;;OAQG;IACH,QAAQ,IAAI,OAAO,CAOlB;IAED,+EAA+E;IAC/E,eAAe,IAAI,iBAAiB,CA4BnC;IAED,oEAAoE;IACpE,MAAM,CAAC,MAAM,EAAE,UAAU,EAAE,OAAO,GAAE;QAAE,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAO,GAAG,OAAO,CAmDjF;IAuJD,sEAAsE;IACtE,gBAAgB,IAAI,IAAI,CAavB;IA4ED;;;;;;OAMG;IACH,gBAAgB,IAAI,IAAI,CAQvB;IAiBD;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,GAAG,EAAE,WAAW,EAAE,MAAM,EAAE,OAAO,GAAG,IAAI,GAAG,MAAM,CA6CzD;IAqRD;;;;;;;;;;;;OAYG;IACH,qBAAqB,IAAI,IAAI,CAgD5B;IAiQD;;;;;;;;OAQG;IACH,uBAAuB,IAAI,IAAI,CAG9B;IAED;;;;;;;OAOG;IACH,sBAAsB,IAAI,IAAI,CAG7B;IAgKD;;;;OAIG;IACH,uBAAuB,IAAI,IAAI,CAY9B;CAiMF"}

package/dist/ui/placement/place_widget.d.ts

@@ -0,0 +1,31 @@
+import type { ExpandCorner, Extent, LauncherBox } from "./launcher_placement.js";
+import type { PanelRect } from "./resize_handle.js";
+/** Where to put the host box, and where the launcher sits inside it. */
+export interface WidgetInsets {
+    /** An `inset` shorthand for the host box. */
+    readonly hostInset: string;
+    /** An `inset` shorthand for the launcher, relative to the host box. */
+    readonly launcherInset: string;
+}
+/**
+ * Express a panel and its launcher, both already positioned, as the two
+ * `inset` shorthands the element writes.
+ *
+ * Both are measured from the **same** corner, which is what stops a later
+ * resize from dragging the launcher: the pinned corner is the one edge a
+ * resize cannot move. Which corner that is says nothing about where either box
+ * ends up -- the positions are absolute and arrive decided -- so re-picking it
+ * moves nothing, and the launcher may sit outside its own host box. Nothing
+ * clips it there, and that is what lets a launcher be flush to a screen corner
+ * while the panel it opens keeps its margin.
+ *
+ * `screen` is the **whole** viewport, not the part a host has left free. These
+ * are CSS `inset` values on a fixed element, and the browser measures those
+ * from the real edges -- so a `bottom` expressed against a box inset from the
+ * top comes out short by exactly that inset. It only shows when the corner
+ * flips mid-drag, because that is when the same point stops being expressed
+ * from `top` and starts being expressed from `bottom`: the widget then leaps by
+ * the reserved edge, which is a jump the gesture cannot explain.
+ */
+export declare function placeWidget(host: PanelRect, launcher: LauncherBox, corner: ExpandCorner, screen: Extent): WidgetInsets;
+//# sourceMappingURL=place_widget.d.ts.map

package/dist/ui/placement/place_widget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"place_widget.d.ts","sourceRoot":"","sources":["../../../src/ui/placement/place_widget.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AACjF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAEpD,wEAAwE;AACxE,MAAM,WAAW,YAAY;IAC3B,6CAA6C;IAC7C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,uEAAuE;IACvE,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAChC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,WAAW,CACzB,IAAI,EAAE,SAAS,EACf,QAAQ,EAAE,WAAW,EACrB,MAAM,EAAE,YAAY,EACpB,MAAM,EAAE,MAAM,GACb,YAAY,CAed"}

package/dist/ui/placement/preset_styles.d.ts

@@ -0,0 +1,2 @@
+export declare const PRESET_STYLES: string;
+//# sourceMappingURL=preset_styles.d.ts.map

package/dist/ui/placement/preset_styles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"preset_styles.d.ts","sourceRoot":"","sources":["../../../src/ui/placement/preset_styles.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,aAAa,EAAE,MA8C3B,CAAC"}

package/dist/ui/placement/resize_handle.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Which edges a grip drags. An axis left out is an axis the grip does not
+ * move: the left-edge grip is `{ x: "left" }`, the top-right corner is
+ * `{ x: "right", y: "top" }`.
+ */
+export interface ResizeGrip {
+    readonly x?: "left" | "right";
+    readonly y?: "top" | "bottom";
+}
+/** Which edges the layout holds still while the panel changes size. */
+export interface ResizeAnchor {
+    /** The horizontal edge that does not move. */
+    readonly x: "left" | "right";
+    /** The vertical edge that does not move. */
+    readonly y: "top" | "bottom";
+}
+/**
+ * What the current placement allows: both axes, width only, or nothing. Which
+ * edges a given grip drags is separate, and fixed when the grip is built.
+ */
+export type ResizeAxis = "none" | "width" | "both";
+/** Persisted size, in CSS pixels. Either axis may be absent. */
+export interface ResizeSize {
+    readonly width?: number;
+    readonly height?: number;
+}
+/** The panel's position on screen, in viewport coordinates. */
+export interface PanelRect {
+    readonly left: number;
+    readonly top: number;
+    readonly right: number;
+    readonly bottom: number;
+}
+/** What the handle needs from its host to do its job. */
+export interface ResizeOptions {
+    /**
+     * Which axes the current placement allows, read per interaction. A getter
+     * because `placement` is a live attribute, and a value read at construction
+     * would survive the host switching to a docked or full-bleed layout.
+     */
+    readonly axis: () => ResizeAxis;
+    /** The panel's current bounding box. */
+    readonly rect: () => PanelRect;
+    /** Apply a box (the host decides what that costs in properties). */
+    readonly apply: (box: PanelRect) => void;
+    /**
+     * Called once per completed resize, for persistence: on `pointerup` for a
+     * drag, and when the key comes up (or focus leaves the handle) for a key
+     * press. Never per pointer move, and never per key repeat.
+     */
+    readonly commit: (box: PanelRect) => void;
+    /** Accessible label. */
+    readonly label: string;
+}
+/**
+ * A drag handle that resizes the chat panel from one edge or corner.
+ *
+ * The rule that keeps it correct is that **the edge a grip does not drag is the
+ * one that stays put**. That is the whole model, and it is what lets the same
+ * code serve all eight grips: the left-edge grip moves the left edge and holds
+ * the right, the right-edge grip does the reverse, a corner does both axes.
+ *
+ * Which edge the *layout* pins is a different question and is deliberately not
+ * asked here. It matters only to the host, which has to rewrite its own
+ * position when a grip drags the very edge the layout was holding still --
+ * dragging the pinned edge of a panel is a move as much as a resize. The
+ * handle reports the box it wants; what that costs in CSS properties is the
+ * host's problem.
+ *
+ * An earlier version took the anchor and derived the direction from it, which
+ * is where the asymmetries lived: whether an arrow key grew or shrank the
+ * panel depended on which corner the single grip had been placed on. With the
+ * grip stated outright, an arrow simply moves the edge it names.
+ */
+export declare function createResizeHandle(grip: ResizeGrip, options: ResizeOptions): HTMLDivElement;
+/** The hyphenated name of a grip, for its class and part. */
+export declare function gripName(grip: ResizeGrip): string;
+//# sourceMappingURL=resize_handle.d.ts.map

package/dist/ui/placement/resize_handle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resize_handle.d.ts","sourceRoot":"","sources":["../../../src/ui/placement/resize_handle.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAC9B,QAAQ,CAAC,CAAC,CAAC,EAAE,KAAK,GAAG,QAAQ,CAAC;CAC/B;AAED,uEAAuE;AACvE,MAAM,WAAW,YAAY;IAC3B,8CAA8C;IAC9C,QAAQ,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAC7B,4CAA4C;IAC5C,QAAQ,CAAC,CAAC,EAAE,KAAK,GAAG,QAAQ,CAAC;CAC9B;AAED;;;GAGG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,CAAC;AAEnD,gEAAgE;AAChE,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,+DAA+D;AAC/D,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,yDAAyD;AACzD,MAAM,WAAW,aAAa;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,UAAU,CAAC;IAChC,wCAAwC;IACxC,QAAQ,CAAC,IAAI,EAAE,MAAM,SAAS,CAAC;IAC/B,oEAAoE;IACpE,QAAQ,CAAC,KAAK,EAAE,CAAC,GAAG,EAAE,SAAS,KAAK,IAAI,CAAC;IACzC;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,SAAS,KAAK,IAAI,CAAC;IAC1C,wBAAwB;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAUD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,aAAa,GAAG,cAAc,CAiG3F;AAUD,6DAA6D;AAC7D,wBAAgB,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAEjD"}

package/dist/ui/placement/resize_styles.d.ts

@@ -0,0 +1,2 @@
+export declare const RESIZE_STYLES: string;
+//# sourceMappingURL=resize_styles.d.ts.map

package/dist/ui/placement/resize_styles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resize_styles.d.ts","sourceRoot":"","sources":["../../../src/ui/placement/resize_styles.ts"],"names":[],"mappings":"AACA,eAAO,MAAM,aAAa,EAAE,MAuM3B,CAAC"}

package/dist/ui/placement/sidebar_styles.d.ts

@@ -0,0 +1,2 @@
+export declare const SIDEBAR_STYLES: string;
+//# sourceMappingURL=sidebar_styles.d.ts.map

package/dist/ui/placement/sidebar_styles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sidebar_styles.d.ts","sourceRoot":"","sources":["../../../src/ui/placement/sidebar_styles.ts"],"names":[],"mappings":"AACA,eAAO,MAAM,cAAc,EAAE,MA+G5B,CAAC"}

package/dist/ui/placement/small_viewport_styles.d.ts

@@ -0,0 +1,2 @@
+export declare const SMALL_VIEWPORT_STYLES: string;
+//# sourceMappingURL=small_viewport_styles.d.ts.map

package/dist/ui/placement/small_viewport_styles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"small_viewport_styles.d.ts","sourceRoot":"","sources":["../../../src/ui/placement/small_viewport_styles.ts"],"names":[],"mappings":"AACA,eAAO,MAAM,qBAAqB,EAAE,MAoEnC,CAAC"}

package/dist/ui/placement/surface_for.d.ts

@@ -0,0 +1,93 @@
+import type { ResizeAxis } from "./resize_handle.js";
+/**
+ * What a collapsed panel shrinks to, stamped on the element as
+ * data-collapsed-to so the stylesheet draws it.
+ *
+ * - `launcher` -- the round button in a corner.
+ * - `rail` -- the slim full-height edge the sidebar docks against; the same
+ *   launcher element, shaped by the stylesheet.
+ * - `header` -- the in-flow collapse: the body hides and the header bar stays
+ *   in the host's layout, so there is no launcher at all.
+ * - `bar` -- `collapse-to="bar"` over a placement that would otherwise
+ *   collapse to `launcher`: a strip along the bottom edge, the panel rising
+ *   from its right end.
+ * - `none` -- `collapse-to="none"` over any collapsible placement: collapsed
+ *   is hidden, and the host's own control brings the panel back.
+ * - `null` -- no collapsed state. `page` is a dedicated route rather than a
+ *   panel on someone else's page, so there is no "away" for it to go to:
+ *   collapsing it left a strip of application chrome fixed over a route with
+ *   no owner, and it hides the launcher, so the usual way back did not exist.
+ *   The header drops its collapse control here, but a control removed from
+ *   the UI is not a state removed from the model: the property, the attribute
+ *   and a value restored from storage all still reach it, so every one of
+ *   those paths asks this record; the stylesheet covers the one path that
+ *   never does, an attribute written straight onto the element.
+ */
+export type CollapseTarget = "launcher" | "rail" | "header" | "bar" | "none" | null;
+/**
+ * Everything the script needs to know about one display surface, in one
+ * record, so a placement's behaviour is read in one place rather than
+ * assembled from a table per question.
+ *
+ * The stylesheet still carries each surface's look (one module per placement
+ * under this directory); this is the part of a surface that code decides.
+ */
+export interface Surface {
+    /** What collapsing shrinks the panel to; `null` when it cannot collapse. */
+    readonly collapseTo: CollapseTarget;
+    /**
+     * Whether a gesture may move the launcher. The rest have nowhere to put it:
+     * the rail is a docked edge, `header` and `null` have no launcher, a
+     * full-bleed panel covers the screen it would be opening into, and the bar
+     * and the host's own control are not a launcher at all.
+     */
+    readonly launcherDraggable: boolean;
+    /**
+     * Whether the header drag and `moveTo` may move the open panel. The same
+     * answer as {@link launcherDraggable} for every placement on its own; the two
+     * part under `collapse-to="bar"` and `"none"`, where a corner panel still
+     * moves like one but has no launcher left to drag.
+     */
+    readonly panelMovable: boolean;
+    /**
+     * Which axes the resize grips may change. A full-bleed layout is the whole
+     * viewport by definition and cannot be resized; a docked panel owns its
+     * height, leaving only its inner edge.
+     */
+    readonly resizeAxis: ResizeAxis;
+    /**
+     * Whether a first mount with nothing stored starts collapsed. Only the
+     * corner placements do: a launcher is the resting state of every corner chat
+     * in the field, and mounting open put a 380x560 panel over the host page's
+     * corner on a visitor's first load, uninvited. The placements that place
+     * themselves start open -- a host that docks a sidebar has already decided
+     * the widget belongs on screen, and one that embeds it has given it a box.
+     *
+     * Separate from {@link launcherDraggable} although the two agree today:
+     * "has a launcher to rest on" and "the launcher can be moved" are different
+     * questions, and a surface with a fixed launcher would answer them apart.
+     */
+    readonly startsCollapsed: boolean;
+    /**
+     * What the header's maximize control grows: both axes for a corner or docked
+     * panel, the width for a side column, and `null` where there is no control
+     * (a surface that already fills its box, or that the host sized).
+     */
+    readonly maximizes: "both" | "width" | null;
+}
+/**
+ * The surface `placement` and `collapse-to` describe together. Read per
+ * interaction by every caller, because both are live attributes.
+ *
+ * `collapse-to` only ever replaces the round launcher or the whole collapsed
+ * state, never a placement's own shape: `bar` applies where the placement
+ * collapses to `launcher`, so the sidebar keeps its rail and an embedded chat
+ * its header bar, and `none` applies to every collapsible placement. Absent,
+ * `auto` and any other value leave the placement as it was. Both turn the
+ * launcher drag off, because there is no launcher left to drag, and keep the
+ * placement's own answer for moving the panel: a corner panel rises from the
+ * bar or the anchor until the user drags it somewhere else, and a placement
+ * that owns its position keeps owning it.
+ */
+export declare function surfaceFor(placement: string | null, collapseTo?: string | null): Surface;
+//# sourceMappingURL=surface_for.d.ts.map

package/dist/ui/placement/surface_for.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"surface_for.d.ts","sourceRoot":"","sources":["../../../src/ui/placement/surface_for.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAErD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,MAAM,cAAc,GAAG,UAAU,GAAG,MAAM,GAAG,QAAQ,GAAG,KAAK,GAAG,MAAM,GAAG,IAAI,CAAC;AAEpF;;;;;;;GAOG;AACH,MAAM,WAAW,OAAO;IACtB,4EAA4E;IAC5E,QAAQ,CAAC,UAAU,EAAE,cAAc,CAAC;IACpC;;;;;OAKG;IACH,QAAQ,CAAC,iBAAiB,EAAE,OAAO,CAAC;IACpC;;;;;OAKG;IACH,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAC/B;;;;OAIG;IACH,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;IAChC;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;IAClC;;;;OAIG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC;CAC7C;AAiFD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,EAAE,UAAU,GAAE,MAAM,GAAG,IAAW,GAAG,OAAO,CAS9F"}

package/dist/ui/progress/prettify_tool_name.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Prettify a raw tool name for display: separators become spaces and the
+ * first letter is capitalised — `list_projects` → "List projects",
+ * `invoices.retrieve` → "Invoices retrieve".
+ *
+ * Final fallback of the tool-card label chain (`x-summary` →
+ * `toolSummaries` → fetched catalog → this). Purely cosmetic: the original
+ * name still rides on the card's dataset for debugging.
+ */
+export declare function prettifyToolName(name: string): string;
+//# sourceMappingURL=prettify_tool_name.d.ts.map

package/dist/ui/progress/prettify_tool_name.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prettify_tool_name.d.ts","sourceRoot":"","sources":["../../../src/ui/progress/prettify_tool_name.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAMrD"}

package/dist/ui/progress/run_announcer.d.ts

@@ -0,0 +1,41 @@
+/**
+ * The screen-reader-only status region, and the one short thing it says at a
+ * time about how a run is going.
+ *
+ * The transcript cannot do this job. It is rewritten on every animation frame
+ * while an answer streams, so as a live region it re-announced the whole
+ * answer tens of times per turn -- not merely unhelpful but actively hostile.
+ * The published fix for this exact bug (Microsoft's Bot Framework WebChat
+ * #3236) is architectural rather than a matter of tuning attributes: demote the
+ * visible transcript out of live-region duty and put one synthesised status per
+ * event into a separate invisible region. MDN and Scott O'Hara prescribe the
+ * same empty-region-then-inject shape.
+ *
+ * Roughly four calls land per turn -- responding, answered, a card is waiting,
+ * stopped or failed -- so the user is told what happened and reads the answer
+ * itself by navigating the log, at their own pace, rather than having it
+ * shouted at them a token at a time.
+ *
+ * Owned one-to-one by an `<ag-ui-chat>`, and holding no state outside the
+ * instance. The element places {@link region} in its shadow root.
+ */
+export declare class RunAnnouncer {
+    #private;
+    /** The invisible `role="status"` region the statuses are written into. */
+    readonly region: HTMLDivElement;
+    /** Stamp the region's live-region semantics, before the element places it. */
+    mount(): void;
+    /**
+     * Say one short thing to a screen reader, without touching the transcript.
+     *
+     * **The clear is load-bearing, twice.** A reader announces a live region when
+     * its content *changes*, so setting the same string twice running -- two turns
+     * in a row both starting -- is not a change and is silently not announced.
+     * Emptying first makes the next set a change again. It also stops a stale
+     * status being read out when a reader later lands on the region.
+     */
+    announce(message: string): void;
+    /** Cancel a pending clear, so no timer outlives the element's connection. */
+    dispose(): void;
+}
+//# sourceMappingURL=run_announcer.d.ts.map

package/dist/ui/progress/run_announcer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run_announcer.d.ts","sourceRoot":"","sources":["../../../src/ui/progress/run_announcer.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,YAAY;;IACvB,0EAA0E;IAC1E,QAAQ,CAAC,MAAM,iBAAiC;IAIhD,8EAA8E;IAC9E,KAAK,IAAI,IAAI,CAOZ;IAED;;;;;;;;OAQG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAS9B;IAED,6EAA6E;IAC7E,OAAO,IAAI,IAAI,CAKd;CACF"}

package/dist/ui/progress/run_notice.d.ts

@@ -0,0 +1,21 @@
+/**
+ * A muted one-line notice about something the run did (history condensed, a
+ * skill loaded), rendered inline between turns.
+ *
+ * Distinct from a tool card, which reports work the agent asked for and
+ * settles, and from an error, which is a failure. A notice never settles and
+ * takes no action of its own.
+ *
+ * It may carry exactly one control, and only ever an undo. That is a narrower
+ * rule than "no controls", which is what this said until the agent could move
+ * the panel it speaks from: something that rearranges the user's window without
+ * being asked has to be both visible and reversible, and a notice is already
+ * the surface that says what the run did. Anything the user has to *decide* is
+ * a confirmation card instead -- the difference is that this reports something
+ * already done.
+ */
+export declare function renderRunNotice(icon: string, text: string, kind: string, undo?: {
+    readonly label: string;
+    readonly onActivate: () => void;
+}): HTMLDivElement;
+//# sourceMappingURL=run_notice.d.ts.map

package/dist/ui/progress/run_notice.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run_notice.d.ts","sourceRoot":"","sources":["../../../src/ui/progress/run_notice.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,IAAI,CAAC,EAAE;IAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,UAAU,EAAE,MAAM,IAAI,CAAA;CAAE,GACjE,cAAc,CAuChB"}

package/dist/ui/progress/run_notice_styles.d.ts

@@ -0,0 +1,2 @@
+export declare const RUN_NOTICE_STYLES: string;
+//# sourceMappingURL=run_notice_styles.d.ts.map

package/dist/ui/progress/run_notice_styles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run_notice_styles.d.ts","sourceRoot":"","sources":["../../../src/ui/progress/run_notice_styles.ts"],"names":[],"mappings":"AACA,eAAO,MAAM,iBAAiB,EAAE,MAkD/B,CAAC"}

package/dist/ui/progress/subagent_panel.d.ts

@@ -0,0 +1,101 @@
+import type { SUBAGENT_PHASE } from "../../constants.js";
+import { type UiStrings } from "../ui_strings.js";
+/** One phase of a delegation's life, as the server spells it. */
+export type SubAgentPhase = (typeof SUBAGENT_PHASE)[keyof typeof SUBAGENT_PHASE];
+/**
+ * One tool call the child made, as the two tool phases report it.
+ *
+ * `ok` is a tri-state and stays one here rather than collapsing to a boolean:
+ * `null` is the call in flight, `true` a result the child accepted, `false` a
+ * result that came back to it. Flattening `null` into `false` would draw a
+ * running call as a failed one for as long as it runs.
+ */
+export interface SubAgentTool {
+    readonly toolCallId: string;
+    readonly name: string;
+    readonly ok: boolean | null;
+}
+/**
+ * One narrowed progress announcement about a delegation.
+ *
+ * Every field but `phase` and `delegationId` is nullable because the wire's
+ * `value` is `unknown` and a malformed announcement must not take the run down
+ * with it. `null` means "said nothing about this", never "said nothing was
+ * there" — the panel leaves what it already shows alone.
+ */
+export interface SubAgentUpdate {
+    /** The **parent's** `delegate_task` tool-call id, not the child's run id. */
+    readonly delegationId: string;
+    /** The child agent's name, for a host that wants to style or select by it. */
+    readonly agent: string | null;
+    readonly phase: SubAgentPhase;
+    /** The server's pre-rendered line. The collapsed row needs nothing else. */
+    readonly status: string | null;
+    /** Present on the two tool phases only. */
+    readonly tool: SubAgentTool | null;
+}
+/**
+ * The nested surface for one delegation: a collapsed status row that expands
+ * onto the child agent's own tool calls.
+ *
+ * ## Where it goes and why
+ *
+ * Into {@link ToolCallCard.subagentSlot} — the card the parent's own
+ * `delegate_task` call already drew. The wire keys progress on the *parent's*
+ * tool-call id, so the thing being narrated is already on screen; a floating
+ * element would have duplicated its identity and then had to explain the
+ * relationship. Attaching instead means the delegation reuses how tool cards
+ * already behave, and there is no second visual language to learn.
+ *
+ * ## The shape
+ *
+ * One row per delegation, live, carrying nothing but the server's own `status`
+ * line — which is what makes a ten-step child cost one row until somebody opens
+ * it. Two alternatives were rejected on the way here and both are worth naming:
+ * a bare status line is cheaper and gives up the detail entirely, and inline
+ * child cards in the transcript interleave parent and child with nothing marking
+ * whose is whose, in an order the persisted transcript will not reproduce.
+ *
+ * A child's steps are keyed by the child's own `toolCallId`, so the `tool_call`
+ * that opens one and the `tool_result` that settles it are the same row updated
+ * in place rather than two rows stacked.
+ *
+ * ## What it never does
+ *
+ * It never renders failure text. A `failed` phase carries none, on purpose; the
+ * detail arrives on the ordinary `TOOL_CALL_RESULT` and lands in the same card's
+ * result region, a few pixels below. Anything invented here would be this
+ * component guessing at words the server declined to send.
+ *
+ * Nothing here is persisted: the events ride the imperative carrier, so a thread
+ * restore rebuilds the tool card and not the delegation under it.
+ *
+ * Pure DOM, like the other widgets: the host appends {@link element}, and all
+ * chrome text comes from {@link UiStrings}. The status line is server text and
+ * is set with `textContent`, never parsed as markup.
+ */
+export declare class SubAgentPanel {
+    #private;
+    /** The panel's root; append this into the delegating card's slot. */
+    readonly element: HTMLDivElement;
+    /**
+     * The child agent's name, as the last update that carried one gave it.
+     *
+     * Read back rather than only written to the DOM, because the two carriers
+     * split the name away from the close: `SUBAGENT_STARTED` names the agent and
+     * `SUBAGENT_FINISHED` carries only an id, so whoever words the closing line
+     * has to recover the name from what the delegation already told it.
+     */
+    get agent(): string | null;
+    constructor(strings?: UiStrings);
+    /**
+     * Fold one announcement in.
+     *
+     * Every field is applied only when the update actually carried it, so a phase
+     * that says nothing about the agent or the status leaves both as they stand.
+     * That is what lets `finished` be two keys wide on the wire without blanking
+     * the row it closes.
+     */
+    report(update: SubAgentUpdate): void;
+}
+//# sourceMappingURL=subagent_panel.d.ts.map

package/dist/ui/progress/subagent_panel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subagent_panel.d.ts","sourceRoot":"","sources":["../../../src/ui/progress/subagent_panel.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,EAAsB,KAAK,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAEtE,iEAAiE;AACjE,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,OAAO,cAAc,CAAC,CAAC;AAEjF;;;;;;;GAOG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,EAAE,OAAO,GAAG,IAAI,CAAC;CAC7B;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,cAAc;IAC7B,6EAA6E;IAC7E,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,8EAA8E;IAC9E,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC;IAC9B,4EAA4E;IAC5E,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,2CAA2C;IAC3C,QAAQ,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI,CAAC;CACpC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,qBAAa,aAAa;;IACxB,qEAAqE;IACrE,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC;IAEjC;;;;;;;OAOG;IACH,IAAI,KAAK,IAAI,MAAM,GAAG,IAAI,CAEzB;IAgBD,YAAY,OAAO,GAAE,SAA8B,EA2ClD;IAED;;;;;;;OAOG;IACH,MAAM,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI,CAYnC;CAmDF"}