@webmcpui/core 0.1.2 → 0.2.1

package/README.md

@@ -1,11 +1,19 @@
 # @webmcpui/core
 
-Framework-agnostic, WebMCP-native custom elements. Phase 1 ships form
-primitives — shared behavior (form association, validation, WebMCP exposure,
-theming) lives in a `WmcpFormControl` base class; each element is a thin
-subclass that supplies its control and specifics.
+Framework-agnostic, WebMCP-native custom elements. Every `<wmcp-*>` element is a
+proper, accessible HTML control first and, when you opt in, also registers an
+imperative [WebMCP](https://webmcpui.com/docs/webmcp) tool an agent can call.
 
-Shipped so far: `<wmcp-input>`, `<wmcp-textarea>`, `<wmcp-select>`, `<wmcp-checkbox>`.
+**Two families of primitives:**
+
+- **Form controls** expose a _value_ an agent can set — `<wmcp-input>`,
+  `<wmcp-textarea>`, `<wmcp-select>`, `<wmcp-checkbox>`, `<wmcp-radio>` /
+  `<wmcp-radio-group>`. Shared behavior (form association via `ElementInternals`,
+  Standard Schema validation, a11y, theming) lives in a `WmcpFormControl` base.
+- **Interaction primitives** expose an _action_ an agent can trigger —
+  `<wmcp-button>`, `<wmcp-dialog>`, `<wmcp-menu>`, `<wmcp-tabs>`,
+  `<wmcp-popover>` — or, for `<wmcp-toast>`, a _reading_ an agent can perceive.
+  They share a `WmcpAction` / `WmcpExposable` base.
 
 One source of truth (vanilla custom elements built with [Lit](https://lit.dev)),
 two distribution channels: an ESM package for build tools, and a single-file
@@ -21,11 +29,12 @@ pnpm add @webmcpui/core @webmcpui/tokens
 import { defineComponents } from '@webmcpui/core';
 import '@webmcpui/tokens/css'; // the theme tokens (CSS custom properties)
 
-defineComponents(); // registers <wmcp-input> (and future <wmcp-*> elements)
+defineComponents(); // registers every <wmcp-*> element
 ```
 
 ```html
 <wmcp-input label="Email" name="email" type="email"></wmcp-input>
+<wmcp-button variant="primary">Save</wmcp-button>
 ```
 
 Importing the package does **not** register elements — you call
@@ -45,7 +54,7 @@ For Webflow / WordPress / hand-written HTML — one tag, elements auto-register:
 
 See `examples/plain-html.html` for a working local version.
 
-## Standard Schema validation
+## Standard Schema validation (form controls)
 
 Bring any [Standard Schema](https://standardschema.dev) validator — Zod,
 Valibot, ArkType — set it as the `schema` property. No bespoke schema language.
@@ -59,51 +68,64 @@ input.schema = z.string().email('Enter a valid email');
 
 Validation runs on input and during native form validation; failures set
 `aria-invalid`, render an error message in a live region, and propagate to the
-containing `<form>` via ElementInternals.
-
-> **Note:** Standard Schema validates values but does not emit JSON Schema, so
-> the WebMCP tool's parameter schema is derived from the input `type`, not from
-> the validator. Richer tool schemas are a future enhancement.
+containing `<form>` via `ElementInternals`.
 
 ## WebMCP exposure
 
-Opt in with `expose`. The element registers an imperative WebMCP tool
-(`navigator.modelContext.registerTool`) on connect and unregisters on
-disconnect. It is feature-detected — a complete no-op when no agent/host is
-present (the common case today), so the input is always a good form control
-first.
+Opt in with `expose`. The element registers an imperative WebMCP tool on connect
+and unregisters on disconnect. It is feature-detected — preferring
+`document.modelContext` (canonical as of the Chrome 149+ origin trial) and
+falling back to the deprecated `navigator.modelContext` — and a complete no-op
+when no host is present, so the element is always a good control first.
 
 ```html
+<!-- form control → a "fill" tool that sets a value -->
 <wmcp-input label="Email" name="email" expose></wmcp-input>
-<!-- registers a "fill_email" tool an agent can call -->
+
+<!-- interaction primitive → an "action" tool the agent can trigger -->
+<wmcp-button tool-name="book_appointment" expose>Book</wmcp-button>
+
+<!-- a menu → a parameterized action (the agent picks which item) -->
+<wmcp-menu name="row_action" label="Actions" expose>
+  <option value="edit">Edit</option>
+  <option value="delete">Delete</option>
+</wmcp-menu>
 ```
 
+Consequential steps stay a deliberate human action: an agent can _set_ a value
+or _open_ a dialog, but submitting/confirming is the person's to make.
+
 ## Testing without a real agent
 
-No mainstream agent calls WebMCP yet, so `@webmcpui/core/testing` ships a fake
-host to exercise exposure end to end (and seeds the future inspector):
+No mainstream agent calls WebMCP broadly yet, so `@webmcpui/core/testing` ships a
+fake host to exercise exposure end to end:
 
 ```ts
 import { installFakeAgent } from '@webmcpui/core/testing';
 
 const agent = installFakeAgent();
-// ... connect a <wmcp-input expose> ...
+// ... connect a <wmcp-input expose> / <wmcp-button expose> ...
 await agent.call('fill_email', { value: 'agent@webmcpui.com' });
+await agent.call('click_button');
 agent.restore();
 ```
 
+## Documentation
+
+Full docs, live demos for every element, and `llms.txt` at
+**[webmcpui.com](https://webmcpui.com)**.
+
 ## Build & test
 
 ```bash
 pnpm build        # tsup → dist/ (ESM + IIFE + d.ts)
 pnpm typecheck    # tsc --noEmit
-pnpm test         # @web/test-runner in real Chromium (form association,
-                  # validation a11y, WebMCP exposure)
+pnpm test         # @web/test-runner in real Chromium
 pnpm test:smoke   # node smoke check against the built dist
 ```
 
 Tests run in a genuine browser via the Playwright launcher — form-associated
-custom elements and ElementInternals don't work under jsdom. First run needs
+custom elements and `ElementInternals` don't work under jsdom. First run needs
 the browser binary:
 
 ```bash

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { LitElement, CSSResultGroup, TemplateResult, nothing, CSSResult } from 'lit';
-import { J as JSONSchema } from './webmcp-JAn7I2xj.js';
-export { T as ToolDisposer, W as WebMCPToolDefinition, a as WebMCPToolResult, b as WebMCPToolResultContent, e as exposeTool, i as isWebMCPAvailable } from './webmcp-JAn7I2xj.js';
+import { J as JSONSchema, W as WebMCPToolResult } from './webmcp-DbmbtX6x.js';
+export { T as ToolDisposer, a as WebMCPToolDefinition, b as WebMCPToolResultContent, e as exposeTool, i as isWebMCPAvailable } from './webmcp-DbmbtX6x.js';
 
 /**
  * Minimal Standard Schema v1 types + a validation helper.
@@ -61,6 +61,51 @@ declare function validateStandard<Output>(schema: StandardSchemaV1<unknown, Outp
 /** Duck-type check that an unknown value is a Standard Schema. */
 declare function isStandardSchema(value: unknown): value is StandardSchemaV1;
 
+/**
+ * Base for every element that can register itself as a WebMCP tool — both the
+ * *value* controls ({@link WmcpFormControl}) and the *action* elements
+ * ({@link WmcpAction}).
+ *
+ * It owns only the exposure *mechanism*: the `expose` / `tool-name` /
+ * `tool-description` opt-in surface, the tool's lifecycle (register on connect,
+ * dispose on disconnect, re-register when its identity changes, drop when
+ * `expose` is turned off), and the single `exposeTool` call. The spec-sensitive
+ * registration/disposal itself lives one layer down in `exposeTool`, so this is
+ * thin wiring over a single source of truth.
+ *
+ * Each subtree supplies the *policy* via four hooks — {@link resolvedToolName},
+ * {@link defaultToolDescription}, {@link toolInputSchema}, {@link executeTool} —
+ * plus {@link toolReactiveProps} when extra properties feed the tool's name or
+ * description. Abstract — not registered on its own.
+ */
+declare abstract class WmcpExposable extends LitElement {
+    /** Whether to expose this element as a WebMCP tool. */
+    expose: boolean;
+    /** Override the generated WebMCP tool name. */
+    toolName: string;
+    /** Override the generated WebMCP tool description. */
+    toolDescription: string;
+    private toolDisposer;
+    /** The resolved WebMCP tool name. */
+    abstract get resolvedToolName(): string;
+    /** Description used when `tool-description` is not set. */
+    protected abstract get defaultToolDescription(): string;
+    /** JSON Schema for the tool's args. Defaults to a no-argument tool. */
+    protected toolInputSchema(): JSONSchema;
+    /** Invoked when the agent calls the tool; returns the agent-facing result. */
+    protected abstract executeTool(args: Record<string, unknown>): WebMCPToolResult | Promise<WebMCPToolResult>;
+    /**
+     * Property changes that alter the tool's *identity* (name/description) and so
+     * require re-registration. State read live inside {@link executeTool} does
+     * not belong here. Subclasses extend this with their own naming inputs.
+     */
+    protected get toolReactiveProps(): readonly string[];
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    updated(changed: Map<string, unknown>): void;
+    protected registerTool(): void;
+}
+
 /**
  * Base class for form-associated, agent-operable controls.
  *
@@ -86,7 +131,7 @@ declare const textFieldStyles: CSSResult;
  * that supplies its control markup and tool schema. Abstract — not registered
  * on its own.
  */
-declare abstract class WmcpFormControl extends LitElement {
+declare abstract class WmcpFormControl extends WmcpExposable {
     static formAssociated: boolean;
     static styles: CSSResultGroup;
     /** Visible label text. */
@@ -102,12 +147,6 @@ declare abstract class WmcpFormControl extends LitElement {
     helperText: string;
     /** Message shown when a `required` control is empty. */
     requiredMessage: string;
-    /** Whether to expose this control as a WebMCP tool. */
-    expose: boolean;
-    /** Override the generated WebMCP tool name. */
-    toolName: string;
-    /** Override the generated WebMCP tool description. */
-    toolDescription: string;
     /**
      * Standard Schema validator (Zod, Valibot, ArkType, …). Set as a property,
      * not an attribute. Validation runs on input and on form validation.
@@ -115,7 +154,6 @@ declare abstract class WmcpFormControl extends LitElement {
     schema?: StandardSchemaV1<unknown, unknown>;
     protected error: string;
     protected readonly internals: ElementInternals;
-    private toolDisposer;
     /** Noun used in default tool names/descriptions when `name` is empty. */
     protected get controlNoun(): string;
     /** The rendered control element (`<input>` / `<textarea>` / `<select>`). */
@@ -145,9 +183,10 @@ declare abstract class WmcpFormControl extends LitElement {
     protected get requiredMessageDefault(): string;
     disconnectedCallback(): void;
     updated(changed: Map<string, unknown>): void;
-    /** The resolved WebMCP tool name. */
     get resolvedToolName(): string;
-    protected registerTool(): void;
+    protected get defaultToolDescription(): string;
+    protected get toolReactiveProps(): readonly string[];
+    protected executeTool(args: Record<string, unknown>): Promise<WebMCPToolResult>;
     /**
      * Apply the agent's tool arguments to component state. Defaults to treating
      * `args.value` as the new string value; controls with a different shape
@@ -359,13 +398,401 @@ declare class WmcpRadioGroup extends WmcpFormControl {
     render(): TemplateResult;
 }
 
+/**
+ * Base class for agent-operable *action* elements.
+ *
+ * Where {@link WmcpFormControl} exposes a *value* an agent can set, an action
+ * element exposes an *action* an agent can trigger — a click, an open, a
+ * dismissal. The WebMCP exposure mechanism (the `expose` surface, the tool
+ * lifecycle, the `exposeTool` call) lives in the shared {@link WmcpExposable}
+ * base; this layer adds the action-flavored *policy*: a verb-prefixed tool name
+ * (`click_save`, `open_booking`), an action-shaped default description, and a
+ * no-argument tool by default.
+ *
+ * A subclass supplies {@link actionVerb} and {@link executeTool}, and may
+ * override {@link actionNoun}, {@link defaultNameSuffix}, or
+ * {@link toolInputSchema} (e.g. a menu whose action takes which-item). Abstract
+ * — not registered on its own.
+ *
+ * Extracted when the second action element (dialog) landed alongside the first
+ * (button) — two data points reveal what's genuinely shared, the same rule
+ * that produced `WmcpFormControl`.
+ */
+declare abstract class WmcpAction extends WmcpExposable {
+    /** Identifier used to build the default tool name. */
+    name: string;
+    /** Accessible name and the noun used in the default tool description. */
+    label: string;
+    /** Verb that prefixes the default tool name, e.g. `click` → `click_save`. */
+    protected abstract get actionVerb(): string;
+    /** Suffix for the default tool name when `name` is empty. */
+    protected get defaultNameSuffix(): string;
+    /** Human-readable noun for the thing being acted on. */
+    protected get actionNoun(): string;
+    get resolvedToolName(): string;
+    protected get defaultToolDescription(): string;
+    protected get toolReactiveProps(): readonly string[];
+    /**
+     * Perform the action and return the agent-facing result. Called when the
+     * agent invokes the tool; subclasses implement the actual effect.
+     */
+    protected abstract executeTool(args: Record<string, unknown>): WebMCPToolResult | Promise<WebMCPToolResult>;
+}
+
+/** Visual variants `<wmcp-button>` supports (shadcn-aligned). */
+type WmcpButtonVariant = 'primary' | 'secondary' | 'destructive' | 'outline' | 'ghost';
+/** Size variants `<wmcp-button>` supports. */
+type WmcpButtonSize = 'sm' | 'md' | 'lg';
+/** Native button behaviors `<wmcp-button>` mirrors. */
+type WmcpButtonType = 'button' | 'submit' | 'reset';
+/**
+ * `<wmcp-button>` — a themeable, agent-operable button. The first Phase 2
+ * interaction primitive.
+ *
+ * Where the form controls expose a *value* an agent can set, a button exposes
+ * an *action* an agent can trigger. When a WebMCP host is present and the
+ * button opts in (`expose`), it registers a tool that activates the button
+ * exactly as a human click would — running light-DOM `click` handlers and, for
+ * `type="submit"`/`"reset"`, driving the associated form. With no agent
+ * present (the common case today) it is simply a good, accessible button.
+ *
+ * Activation has a single path: both a real click and an agent tool call route
+ * through the inner native `<button>`, so behavior, focus, and form
+ * participation are identical for human and agent. A `disabled` button can be
+ * activated by neither.
+ *
+ * Form-associated, so `type="submit"` and `type="reset"` work from inside the
+ * shadow boundary (a native submit button there would not reach the outer
+ * form). Visible content is slotted; an explicit `label` is used for the
+ * accessible name and the default tool description when set.
+ *
+ * Not auto-registered — call `defineComponents()` (or load the CDN bundle).
+ */
+declare class WmcpButton extends WmcpAction {
+    static readonly tagName = "wmcp-button";
+    static formAssociated: boolean;
+    static shadowRootOptions: ShadowRootInit;
+    static styles: CSSResultGroup;
+    /** Visual variant. */
+    variant: WmcpButtonVariant;
+    /** Size. */
+    size: WmcpButtonSize;
+    /** Native button behavior: a plain button, a form submit, or a form reset. */
+    type: WmcpButtonType;
+    /** Disables the button for both humans and agents. */
+    disabled: boolean;
+    private readonly internals;
+    /** The inner native `<button>` that owns activation, focus, and a11y. */
+    private get button();
+    protected get actionVerb(): string;
+    protected get defaultNameSuffix(): string;
+    protected get actionNoun(): string;
+    protected get defaultToolDescription(): string;
+    protected executeTool(): WebMCPToolResult;
+    /**
+     * Activate the button as if a human clicked it: routes through the inner
+     * native button so light-DOM `click` handlers fire and `type`-driven form
+     * submission/reset happens. A no-op when disabled.
+     */
+    activate(): void;
+    /**
+     * Inner-button click handler. The native click already bubbles (composed) to
+     * the host, so light-DOM listeners fire without help; this only adds the
+     * cross-shadow form behavior a native submit/reset button can't do from here.
+     */
+    private onInnerClick;
+    render(): TemplateResult;
+}
+
+/**
+ * `<wmcp-dialog>` — a modal dialog whose *action* is being opened. The second
+ * Phase 2 interaction primitive, and the one that motivated the shared
+ * {@link WmcpAction} base.
+ *
+ * It wraps the native `<dialog>` element, so it inherits the platform's focus
+ * trap, top-layer stacking, backdrop, and Escape-to-close for free. The
+ * exposed WebMCP action is **open** — the agent surfaces the dialog for the
+ * user to review; closing/confirming stays a deliberate human (or
+ * programmatic) step. That asymmetry is the consent gate: an agent can ask for
+ * attention, but the irreversible confirm is the person's to make.
+ *
+ * Drive it declaratively with the reflected `open` attribute or imperatively
+ * with {@link show} / {@link close}; either way it emits composed `open` and
+ * `close` events. With no agent present it is simply an accessible modal.
+ *
+ * Not auto-registered — call `defineComponents()` (or load the CDN bundle).
+ */
+declare class WmcpDialog extends WmcpAction {
+    static readonly tagName = "wmcp-dialog";
+    static styles: CSSResultGroup;
+    /** Whether the dialog is open (reflected, so `[open]` styling works). */
+    open: boolean;
+    /** Open as a modal (focus-trapping, with backdrop). Set false for non-modal. */
+    modal: boolean;
+    /** Keep the dialog open when the backdrop is clicked (modal "static" mode). */
+    staticBackdrop: boolean;
+    /** Last `returnValue` the dialog closed with (mirrors native `<dialog>`). */
+    returnValue: string;
+    private get dialogEl();
+    protected get actionVerb(): string;
+    protected get defaultNameSuffix(): string;
+    protected get defaultToolDescription(): string;
+    protected executeTool(): WebMCPToolResult;
+    updated(changed: Map<string, unknown>): void;
+    /** Open the dialog (modal unless `modal` is false). */
+    show(): void;
+    /** Close the dialog, optionally recording a `returnValue`. */
+    close(returnValue?: string): void;
+    /** Reconcile our `open` state with the native dialog's imperative API. */
+    private syncNativeOpen;
+    /** Native `close` fires for Escape, backdrop, or our own `close()`. */
+    private onNativeClose;
+    /**
+     * Close on a backdrop click. A click whose target is the `<dialog>` itself
+     * is the backdrop — content clicks retarget to `.panel` or its children — so
+     * this never fires on the dialog's own frame or a text drag-select.
+     */
+    private onDialogClick;
+    render(): TemplateResult;
+}
+
+/** A single selectable item in a `<wmcp-menu>`. */
+interface WmcpMenuItem {
+    value: string;
+    label: string;
+    disabled?: boolean;
+}
+/**
+ * `<wmcp-menu>` — a menu-button whose exposed action is *selecting an item*.
+ * The first **parameterized** interaction primitive: where button and dialog
+ * expose no-argument actions, the menu's tool takes *which item* — an `enum`
+ * of the item values — so it pressure-tests the {@link WmcpAction} base the
+ * way `<wmcp-select>` did for `WmcpFormControl`.
+ *
+ * The popup uses the native Popover API (top layer, light-dismiss, and Escape
+ * for free); items come from declarative `<option>` children (no build) or the
+ * `items` property. Selecting an item — by human click, keyboard, or agent
+ * tool call — fires a composed `select` event (`detail: { value, label }`) and
+ * closes the menu. A menu dispatches actions; it does not hold a value.
+ *
+ * Not auto-registered — call `defineComponents()` (or load the CDN bundle).
+ */
+declare class WmcpMenu extends WmcpAction {
+    static readonly tagName = "wmcp-menu";
+    static styles: CSSResultGroup;
+    /** Trigger label. */
+    label: string;
+    /**
+     * Items as data. When non-empty, takes precedence over declarative
+     * `<option>` children. Set as a property, not an attribute.
+     */
+    items: WmcpMenuItem[];
+    /** Whether the popup is open (reflected). */
+    open: boolean;
+    /** The normalized item model actually rendered (property or declarative). */
+    private resolvedItems;
+    private itemObserver?;
+    private get menuEl();
+    private get itemButtons();
+    protected get actionVerb(): string;
+    protected get defaultNameSuffix(): string;
+    protected get actionNoun(): string;
+    protected get defaultToolDescription(): string;
+    protected get toolReactiveProps(): readonly string[];
+    protected toolInputSchema(): JSONSchema;
+    protected executeTool(args: Record<string, unknown>): WebMCPToolResult;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    willUpdate(changed: Map<string, unknown>): void;
+    private syncItems;
+    private readDeclarativeItems;
+    /** Dispatch the selection and close the menu. */
+    private selectItem;
+    private onItemClick;
+    /** Sync `open`/`aria-expanded` and move focus into the menu when it opens. */
+    private onToggle;
+    /** Roving focus among items with the arrow / Home / End keys. */
+    private onMenuKeydown;
+    render(): TemplateResult;
+}
+
+/** A single tab derived from a `[tab]` panel child of `<wmcp-tabs>`. */
+interface WmcpTabInfo {
+    value: string;
+    label: string;
+    disabled?: boolean;
+}
+/**
+ * `<wmcp-tabs>` — a tab set whose exposed action is *switching the active tab*.
+ * The first **stateful** interaction primitive: where button/dialog/menu are
+ * fire-and-forget dispatchers, a tab set holds a persistent `active` selection
+ * (reflected), and the agent's tool both reads and changes it.
+ *
+ * It confirms the {@link WmcpAction} base needs no "current value" concept — a
+ * stateful action element simply owns its own state (here `active`, like the
+ * dialog owns `open`) and its `executeTool` mutates it.
+ *
+ * Panels are declarative light-DOM children carrying a `tab` attribute (and an
+ * optional `tab-label`); the tablist is derived from them. Switching — by
+ * click, arrow keys, or agent — updates `active`, reveals the matching panel,
+ * and fires a composed `change` event (`detail: { value }`).
+ *
+ * Not auto-registered — call `defineComponents()` (or load the CDN bundle).
+ */
+declare class WmcpTabs extends WmcpAction {
+    static readonly tagName = "wmcp-tabs";
+    static styles: CSSResultGroup;
+    /** The value of the active tab (reflected — this is the persistent state). */
+    active: string;
+    /** Accessible name for the tablist. */
+    label: string;
+    /** The tab model derived from the `[tab]` panel children. */
+    private tabs;
+    private panelObserver?;
+    protected get actionVerb(): string;
+    protected get defaultNameSuffix(): string;
+    protected get actionNoun(): string;
+    protected get defaultToolDescription(): string;
+    protected get toolReactiveProps(): readonly string[];
+    protected toolInputSchema(): JSONSchema;
+    protected executeTool(args: Record<string, unknown>): WebMCPToolResult;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    updated(changed: Map<string, unknown>): void;
+    /** Light-DOM children that declare a tab via the `tab` attribute. */
+    private get panelEls();
+    private syncTabs;
+    /** Fall back to the first enabled tab when `active` is unset or invalid. */
+    private ensureActive;
+    /** Reflect the active tab onto the slotted panels (roles, labels, hidden). */
+    private applyPanels;
+    /** Switch the active tab, firing `change` when it actually moves. */
+    switchTo(value: string): void;
+    private get tabButtons();
+    /** Arrow / Home / End roving with automatic activation (ARIA tabs pattern). */
+    private onKeydown;
+    render(): TemplateResult;
+}
+
+/** Where the panel sits relative to its trigger. */
+type WmcpPopoverPlacement = 'top' | 'bottom' | 'left' | 'right';
+/** How the popover is opened: clicked (interactive) or hovered (tooltip). */
+type WmcpPopoverTrigger = 'click' | 'hover';
+/**
+ * `<wmcp-popover>` — a non-modal, anchored floating panel whose exposed action
+ * is being opened. The sibling of [dialog](./dialog.ts) (modal) and
+ * [menu](./menu.ts) (action list): same native-Popover-API + CSS-anchor
+ * machinery as the menu, but the content is arbitrary.
+ *
+ * `trigger="click"` (default) gives an interactive popover — click to toggle,
+ * with light-dismiss and Escape for free. `trigger="hover"` gives a tooltip —
+ * it opens on hover/focus, closes on leave/blur, and labels its trigger via
+ * `aria-describedby`. Either way the agent can `open` it; closing stays a
+ * human/light-dismiss step, the same consent posture as the dialog.
+ *
+ * Not auto-registered — call `defineComponents()` (or load the CDN bundle).
+ */
+declare class WmcpPopover extends WmcpAction {
+    static readonly tagName = "wmcp-popover";
+    static styles: CSSResultGroup;
+    /** Whether the panel is open (reflected). */
+    open: boolean;
+    /** Trigger text, used when no `trigger` slot content is provided. */
+    label: string;
+    /** Panel placement relative to the trigger. */
+    placement: WmcpPopoverPlacement;
+    /** Open on click (interactive popover) or on hover/focus (tooltip). */
+    trigger: WmcpPopoverTrigger;
+    private get panelEl();
+    protected get actionVerb(): string;
+    protected get defaultNameSuffix(): string;
+    protected get defaultToolDescription(): string;
+    protected executeTool(): WebMCPToolResult;
+    updated(changed: Map<string, unknown>): void;
+    /** Open the popover. */
+    show(): void;
+    /** Close the popover. */
+    close(): void;
+    private syncNativeOpen;
+    /** Native toggle fires for clicks, light-dismiss, Escape, and our own calls. */
+    private onToggle;
+    private closeTimer?;
+    disconnectedCallback(): void;
+    /** Open on hover/focus of the trigger *or* the panel. */
+    private openOnHover;
+    /**
+     * Close on leave/blur — but on a short delay, so the pointer can cross the
+     * gap from the trigger to the panel (and reach interactive content inside it)
+     * without the popover vanishing. Re-entering either cancels the close.
+     */
+    private scheduleHoverClose;
+    private cancelScheduledClose;
+    render(): TemplateResult;
+}
+
+/** A toast's severity, used for styling and the agent-readable summary. */
+type WmcpToastVariant = 'info' | 'success' | 'warning' | 'error';
+/** Options accepted by {@link WmcpToast.show}. */
+interface WmcpToastOptions {
+    title?: string;
+    message: string;
+    variant?: WmcpToastVariant;
+    /** Auto-dismiss after this many ms; `0` keeps it until dismissed. */
+    duration?: number;
+}
+/**
+ * `<wmcp-toast>` — a notification region, and the one component whose agent
+ * surface is *perceiving* rather than *actuating*.
+ *
+ * Page code throws toasts the way it always has — `el.show({ message })` — and
+ * they announce to screen readers via an `aria-live` region. When `expose` is
+ * set, the very same notifications become readable by an agent through a
+ * `read_<name>` tool: the machine-readable twin of the `aria-live`
+ * announcement. An agent acting on the user's behalf often has no other way to
+ * learn an outcome ("Payment declined", an async "Export ready"), so it reads
+ * the toasts rather than posting them.
+ *
+ * Extends {@link WmcpExposable} directly — not {@link WmcpAction} — because the
+ * tool reports state instead of triggering an action.
+ *
+ * Not auto-registered — call `defineComponents()` (or load the CDN bundle).
+ */
+declare class WmcpToast extends WmcpExposable {
+    static readonly tagName = "wmcp-toast";
+    static styles: CSSResultGroup;
+    /** Identifier used for the default tool name (`read_<name>`). */
+    name: string;
+    /** Accessible name for the live region. */
+    label: string;
+    /** Corner the toasts stack in. */
+    placement: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
+    /** Default auto-dismiss in ms; `0` keeps toasts until dismissed. */
+    duration: number;
+    private toasts;
+    private recent;
+    private nextId;
+    private timers;
+    /** Show a toast. Returns its id (pass to {@link dismiss}). */
+    show(options: WmcpToastOptions): number;
+    /** Dismiss a toast by id. */
+    dismiss(id: number): void;
+    /** Dismiss all visible toasts. */
+    clear(): void;
+    disconnectedCallback(): void;
+    get resolvedToolName(): string;
+    protected get defaultToolDescription(): string;
+    protected get toolReactiveProps(): readonly string[];
+    protected executeTool(): WebMCPToolResult;
+    render(): TemplateResult;
+}
+
 /**
  * Register all webmcpui custom elements. Idempotent — safe to call more than
  * once and safe alongside the CDN bundle (already-defined tags are skipped).
  */
 declare function defineComponents(): void;
 
-export { JSONSchema, StandardSchemaV1, type ValidationOutcome, WmcpCheckbox, WmcpFormControl, WmcpInput, type WmcpInputType, WmcpRadio, WmcpRadioGroup, type WmcpRadioOption, WmcpSelect, type WmcpSelectItem, type WmcpSelectOption, type WmcpSelectOptionGroup, WmcpTextarea, defineComponents, isStandardSchema, textFieldStyles, validateStandard };
+export { JSONSchema, StandardSchemaV1, type ValidationOutcome, WebMCPToolResult, WmcpAction, WmcpButton, type WmcpButtonSize, type WmcpButtonType, type WmcpButtonVariant, WmcpCheckbox, WmcpDialog, WmcpExposable, WmcpFormControl, WmcpInput, type WmcpInputType, WmcpMenu, type WmcpMenuItem, WmcpPopover, type WmcpPopoverPlacement, type WmcpPopoverTrigger, WmcpRadio, WmcpRadioGroup, type WmcpRadioOption, WmcpSelect, type WmcpSelectItem, type WmcpSelectOption, type WmcpSelectOptionGroup, type WmcpTabInfo, WmcpTabs, WmcpTextarea, WmcpToast, type WmcpToastOptions, type WmcpToastVariant, defineComponents, isStandardSchema, textFieldStyles, validateStandard };
 
 declare global {
   interface HTMLElementTagNameMap {
@@ -375,5 +802,11 @@ declare global {
     'wmcp-checkbox': import('./index.js').WmcpCheckbox;
     'wmcp-radio': import('./index.js').WmcpRadio;
     'wmcp-radio-group': import('./index.js').WmcpRadioGroup;
+    'wmcp-button': import('./index.js').WmcpButton;
+    'wmcp-dialog': import('./index.js').WmcpDialog;
+    'wmcp-menu': import('./index.js').WmcpMenu;
+    'wmcp-tabs': import('./index.js').WmcpTabs;
+    'wmcp-popover': import('./index.js').WmcpPopover;
+    'wmcp-toast': import('./index.js').WmcpToast;
   }
 }