@runtypelabs/persona 3.21.3 → 3.22.0

package/dist/theme-editor.d.cts

@@ -771,6 +771,13 @@ type AgentWidgetRequestPayload = {
     metadata?: Record<string, unknown>;
     /** Per-turn template variables for /v1/client/chat (merged as root-level {{var}} in Runtype). */
     inputs?: Record<string, unknown>;
+    /**
+     * Per-turn page-discovered tools (WebMCP). Sent to Runtype's dispatch so the
+     * agent can call them as `webmcp:<name>`. The widget snapshots
+     * `document.modelContext.__getRegisteredTools()` each turn and ships only
+     * the JSON-serializable surface (no `execute`).
+     */
+    clientTools?: ClientToolDefinition[];
 };
 /**
  * Configuration for agent loop behavior.
@@ -846,6 +853,90 @@ type AgentRequestOptions = {
     /** Enable debug mode for additional event data */
     debugMode?: boolean;
 };
+/**
+ * Wire shape for a single client-discovered tool sent on `dispatch.clientTools[]`.
+ *
+ * Mirrors the SDK's `ClientToolDefinition` in `@runtypelabs/sdk`. Only the
+ * JSON-serializable surface of a WebMCP tool — the `execute` function stays
+ * client-side; the server merges these into the agent's tool catalog under
+ * the `webmcp:` namespace.
+ */
+type ClientToolDefinition = {
+    /** Bare tool name; the server prepends `webmcp:` on the wire. */
+    name: string;
+    description: string;
+    /** JSON Schema (per WebMCP spec) — passed through as-is. */
+    parametersSchema?: object;
+    /** Set to `'webmcp'` for tools discovered via the polyfill. */
+    origin?: 'webmcp' | 'local';
+    /** Origin of the page that registered the tool — for server-side audit. */
+    pageOrigin?: string;
+    /**
+     * WebMCP `Tool.annotations` (spec). Not used for gating server-side; the
+     * widget reads these client-side. Forwarded so traces/dashboards can show
+     * `readOnlyHint` / `untrustedContentHint` on tool-call records.
+     */
+    annotations?: {
+        readOnlyHint?: boolean;
+        untrustedContentHint?: boolean;
+    };
+};
+/**
+ * Information passed to the confirm-bubble handler before a `webmcp:*` tool
+ * call executes. Every WebMCP tool routes through this single gate.
+ */
+type WebMcpConfirmInfo = {
+    /** Bare tool name (no `webmcp:` prefix). */
+    toolName: string;
+    args: unknown;
+    description?: string;
+    annotations?: {
+        readOnlyHint?: boolean;
+        untrustedContentHint?: boolean;
+    };
+    /**
+     * Why the confirm was requested. Currently always `'gate'` — the default
+     * confirm-by-default gate that fires before every `webmcp:*` call. (The
+     * `@mcp-b/webmcp-polyfill` owns the spec's `requestUserInteraction` callback
+     * internally, so Persona no longer surfaces a nested in-tool confirm.)
+     */
+    reason: 'gate';
+};
+/**
+ * Resolves to `true` if the user approves the tool call; `false` to decline.
+ */
+type WebMcpConfirmHandler = (info: WebMcpConfirmInfo) => Promise<boolean>;
+/**
+ * Widget-level WebMCP configuration. Set `enabled: true` to opt in. The
+ * surface's server-side `webmcp` policy is the source of truth for which
+ * tools are accepted — these client-side options are convenience filters.
+ */
+type AgentWidgetWebMcpConfig = {
+    /** Master switch. Default: `false` (widget never installs the polyfill). */
+    enabled?: boolean;
+    /**
+     * Glob-ish name patterns to include client-side. `'*'` matches any chars
+     * except `:`. Patterns are matched against the bare tool name (no `webmcp:`
+     * prefix). If unset, all registered tools are included.
+     */
+    allowlist?: string[];
+    /**
+     * Per-tool gate policy. Called before the confirm gate for every
+     * `webmcp:*` call; return `true` to approve immediately and skip the
+     * confirmation UI entirely. Use this to auto-allow read-only tools (e.g.
+     * a catalog search) while still gating mutating ones. Only consulted on
+     * the default-UI path — a custom `onConfirm` takes full control instead.
+     */
+    autoApprove?: (info: WebMcpConfirmInfo) => boolean;
+    /**
+     * Confirm gate handler. When omitted, Persona renders its native in-panel
+     * approval bubble (the same chrome used for server-driven tool approvals)
+     * and resolves on the user's Approve/Deny click. Supply this to override
+     * with a custom confirmer (e.g. a route-level modal). The legacy
+     * `window.confirm` fallback only applies when no widget UI is attached.
+     */
+    onConfirm?: WebMcpConfirmHandler;
+};
 /**
  * Metadata attached to messages created during agent execution.
  */
@@ -872,6 +963,16 @@ type AgentMessageMetadata = {
      * `POST /v1/dispatch/resume` with the user's answer keyed by tool name.
      */
     awaitingLocalTool?: boolean;
+    /**
+     * The provider per-call id (`toolu_…`) carried on the `step_await` /
+     * `flow_await` events for a LOCAL tool (core#3878). Present only when the
+     * server emits it. Two PARALLEL calls to the same tool in one turn share a
+     * `toolName` (and a collapsed `toolId`) but get DISTINCT `webMcpToolCallId`s,
+     * so this is the key the widget batches a single `/resume` on — preferred
+     * over tool name, which collides for same-tool parallel calls. Absent →
+     * fall back to the legacy name-keyed resume contract.
+     */
+    webMcpToolCallId?: string;
     /**
      * Set to `true` once the user has picked / typed / dismissed an answer for
      * an `ask_user_question` tool call, so renderers stop re-mounting the
@@ -1484,6 +1585,14 @@ type AgentWidgetFeatureFlags = {
     showReasoning?: boolean;
     showToolCalls?: boolean;
     showEventStreamToggle?: boolean;
+    /**
+     * Up/Down arrow navigation through previously sent user messages in the
+     * composer, for quick re-entry or editing (shell / Slack style). History is
+     * only entered when the caret is at the start of the input, so normal
+     * multi-line cursor movement is preserved. Set to `false` to disable.
+     * @default true
+     */
+    composerHistory?: boolean;
     /** Shared transcript + event stream scroll-to-bottom affordance. */
     scrollToBottom?: AgentWidgetScrollToBottomFeature;
     /** Collapsed transcript behavior for tool call rows. */
@@ -3269,6 +3378,31 @@ type AgentWidgetLoadingIndicatorConfig = {
 type AgentWidgetConfig = {
     apiUrl?: string;
     flowId?: string;
+    /**
+     * Override the assistant-bubble copy shown when a dispatch fails before any
+     * response streams back (connection refused, CORS, 4xx/5xx, malformed
+     * stream). Provide a static string, or a function of the error so you can
+     * tailor the message per failure and decide whether to surface the raw
+     * reason. When omitted, a default message is shown that includes the
+     * underlying error detail.
+     *
+     * Returning an empty string suppresses the fallback bubble entirely (the
+     * `onError` callback still fires).
+     *
+     * @example
+     * ```typescript
+     * config: {
+     *   // Static
+     *   errorMessage: "We're having trouble connecting. Please try again."
+     *   // Or dynamic
+     *   errorMessage: (error) =>
+     *     error.message.includes("Failed to fetch")
+     *       ? "You appear to be offline."
+     *       : "Something went wrong. Please try again."
+     * }
+     * ```
+     */
+    errorMessage?: string | ((error: Error) => string);
     /**
      * Agent configuration for agent execution mode.
      * When provided, the widget uses agent loop execution instead of flow dispatch.
@@ -3500,6 +3634,26 @@ type AgentWidgetConfig = {
      * ```
      */
     approval?: AgentWidgetApprovalConfig | false;
+    /**
+     * WebMCP — consume page-registered tools (`document.modelContext.registerTool`).
+     * When `enabled`, the widget installs `@mcp-b/webmcp-polyfill`, snapshots the
+     * registry on every dispatch, ships it as `clientTools[]`, and executes
+     * returned `webmcp:*` tool calls with confirm-by-default gating.
+     *
+     * Server-side policy on the chat surface is the source of truth — these
+     * fields layer on top.
+     *
+     * @example
+     * ```typescript
+     * config: {
+     *   webmcp: {
+     *     enabled: true,
+     *     allowlist: ['search_*', 'list_*'],
+     *   }
+     * }
+     * ```
+     */
+    webmcp?: AgentWidgetWebMcpConfig;
     postprocessMessage?: (context: {
         text: string;
         message: AgentWidgetMessage;
@@ -4854,6 +5008,14 @@ declare function convertToPx(value: number, unit: 'px' | 'rem'): number;
 declare function convertFromPx(pxValue: number, unit: 'px' | 'rem'): number;
 declare function normalizeColorValue(value: string): string;
 declare function isValidHex(value: string): boolean;
+/**
+ * Parse an `rgb()` / `rgba()` string into `#rrggbb`. Accepts integer (0-255) or
+ * percentage channels; any alpha component is dropped. Returns `null` when the
+ * string is not a parseable rgb/rgba value, so callers can fall back. This lets
+ * the HSL/luminance paths — which otherwise `parseInt` hex digits — accept the
+ * `rgb()` inputs that `coerceColor` admits without producing `#NaNNaNNaN`.
+ */
+declare function rgbToHex(value: string): string | null;
 /**
  * Compute WCAG 2.x contrast ratio between two hex colors.
  * Returns a number ≥ 1 (e.g. 4.5 for AA normal text).
@@ -4880,4 +5042,189 @@ declare function paletteColorPath(family: string, shade: string): string;
 declare function resolveThemeColorPath(get: (path: string) => unknown, path: string, depth?: number): string;
 declare function tokenRefDisplayName(path: string): string;
 
-export { ADVANCED_TOKENS_SECTION, ALL_ROLES, ALL_TABS, BRAND_PALETTE_SECTION, BUILT_IN_PRESETS, type BuildTranscriptStreamFramesOptions, COLORS_SECTIONS, COLOR_FAMILIES, COMPONENTS_SECTIONS, COMPONENT_COLOR_SECTIONS, COMPONENT_SHAPE_SECTIONS, CONFIGURE_SECTIONS, CONFIGURE_SUB_GROUPS, type ColorScaleOptions, type CompareMode, type ConfigChangeListener, type ConfiguratorSnapshot, DEVICE_DIMENSIONS, type DetectedRoleAssignment, type FieldDef, type FieldType, HOME_SUGGESTION_CHIPS, INTERFACE_ROLES_SECTION, MOCK_BROWSER_CONTENT, MOCK_WORKSPACE_CONTENT, type OnChangeCallback, PALETTE_SECTION, PREVIEW_STORAGE_ADAPTER, type PreviewConfigOptions, type PreviewDevice, type PreviewLifecycleContext, type PreviewScene, type PreviewShellMode, type PreviewShellPalette, type PreviewTranscriptEntryPreset, ROLE_ASSISTANT_MESSAGES, ROLE_BORDERS, ROLE_FAMILIES, ROLE_FAMILY_LABELS, ROLE_HEADER, ROLE_INPUT, ROLE_INTENSITIES, ROLE_LINKS_FOCUS, ROLE_PRIMARY_ACTIONS, ROLE_SCROLL_TO_BOTTOM, ROLE_SURFACES, ROLE_USER_MESSAGES, type RoleAssignmentOptions, type RoleFamily, type RoleIntensity, type RoleTarget, type RoleTargetKind, SEMANTIC_COLORS_SECTION, SHADE_KEYS, SHELL_STYLE_ID, STATUS_COLORS_SECTION, STATUS_PALETTE_SECTION, STYLE_SECTIONS, STYLE_SECTIONS_V2, type SectionDef, type SectionPreset, type SelectOption, type SliderOptions, type SubGroupDef, THEME_EDITOR_PRESETS, THEME_SECTION, type TabDef, type ThemeEditorPreset, ThemeEditorState, type ThemePreviewHandle, type ThemePreviewOptions, type TokenRefOptions, type TranscriptStreamFrame, ZOOM_MAX, ZOOM_MIN, appendPreviewTranscriptEntry, applySceneConfig, applyShellTheme, buildPreviewConfig, buildPreviewConfigWithMessages, buildShellCss, buildSrcdoc, buildTranscriptStreamFrames, convertFromPx, convertToPx, createPreviewMessages, createPreviewTranscriptEntry, createThemePreview, detectRoleAssignment, escapeHtml, findSection, formatCssValue, generateColorScale, getPreviewTranscriptPresetLabel, getShellPalette, getThemeEditorPreset, hexToHsl, hslToHex, isValidHex, normalizeColorValue, paletteColorPath, parseCssValue, presetStreamsText, resolveRoleAssignment, resolveThemeColorPath, scopeSection, tokenRefDisplayName, wcagContrastRatio };
+/**
+ * Minimal local typings for the WebMCP `document.modelContext` surface, plus the
+ * structural state interface the tool factory operates on.
+ *
+ * We deliberately keep our own small WebMCP types rather than depending on
+ * `@mcp-b/webmcp-types`, so the tool definitions are transport-agnostic and the
+ * widget package takes on no polyfill dependency. These mirror the WebMCP draft
+ * (`registerTool(tool, { signal })`) and the MCP tool-result envelope that
+ * `@mcp-b/webmcp-polyfill` expects `execute` to return.
+ */
+
+interface ToolTextContent {
+    type: 'text';
+    text: string;
+}
+interface ToolResult {
+    content: ToolTextContent[];
+    /** Optional machine-readable mirror of the text content. */
+    structuredContent?: unknown;
+    isError?: boolean;
+}
+interface ToolAnnotations {
+    /** The tool has no side effects (pure read). */
+    readOnlyHint?: boolean;
+    /** The tool's output may contain text not to be trusted as instructions. */
+    untrustedContentHint?: boolean;
+}
+type ToolExecute = (input: unknown) => Promise<ToolResult> | ToolResult;
+interface WebMcpTool {
+    name: string;
+    description: string;
+    title?: string;
+    inputSchema?: object;
+    annotations?: ToolAnnotations;
+    execute: ToolExecute;
+}
+/** Wrap a JSON-serializable payload in the MCP tool-result envelope. */
+declare function toolResult(payload: unknown): ToolResult;
+/**
+ * Structural subset of `ThemeEditorState` (and the example app's `state`
+ * module) that the tools require. Anything satisfying this shape can be wired
+ * to the tools — the headless `ThemeEditorState`, or a host's stateful wrapper
+ * that also drives a live preview (e.g. a Persona widget styling itself).
+ */
+interface ThemeEditorLike {
+    get(path: string): unknown;
+    set(path: string, value: unknown): void;
+    setBatch(updates: Record<string, unknown>): void;
+    setTheme(theme: PersonaTheme): void;
+    setFullConfig(config: AgentWidgetConfig, theme?: PersonaTheme): void;
+    undo(): void;
+    redo(): void;
+    canUndo(): boolean;
+    canRedo(): boolean;
+    getHistoryIndex(): number;
+    getTheme(): PersonaTheme;
+    getConfig(): AgentWidgetConfig;
+    exportSnapshot(): ConfiguratorSnapshot;
+    resetToDefaults(): void;
+}
+/** Which theme variant(s) styling tools write to. */
+type EditTarget = 'light' | 'dark' | 'both';
+interface CreateThemeEditorToolsOptions {
+    /** Default variant for styling writes. Defaults to `'both'`. */
+    editTarget?: EditTarget;
+}
+
+/**
+ * WebMCP tool factory for the Persona theme editor.
+ *
+ * `createThemeEditorTools(state)` returns transport-agnostic tool definitions
+ * designed for Agent Experience: intent-level operations (set brand colors,
+ * assign a color role, set roundness…) rather than a 1:1 mapping of the ~150
+ * editor fields. Two altitudes — high-level semantic tools plus a low-level
+ * escape hatch (`set_theme_fields`) — keep the catalog small without losing
+ * coverage. Every mutation returns a compact summary + contrast warnings.
+ */
+
+declare function createThemeEditorTools(state: ThemeEditorLike, options?: CreateThemeEditorToolsOptions): WebMcpTool[];
+
+/**
+ * Input coercion for the WebMCP theme tools.
+ *
+ * Agent inputs are flexible by design (arcade.dev "parameter coercion"): colors
+ * accept hex with/without `#`, 3-digit hex, rgb(), and common CSS color names;
+ * enums accept friendly synonyms. Each coercer throws an Error whose message
+ * lists the valid options (arcade.dev "error-guided recovery").
+ */
+declare const CSS_NAMED_COLORS: Record<string, string>;
+/**
+ * Coerce a flexible color input into a canonical CSS color string.
+ * Accepts: `#1d4ed8`, `1d4ed8`, `#18f`, `rgb(...)`, `transparent`, and common
+ * CSS color names. Throws with guidance when the value can't be understood.
+ */
+declare function coerceColor(input: unknown): string;
+type BrandFamily = 'primary' | 'secondary' | 'accent';
+type RoleFamilyInput = BrandFamily | 'neutral';
+/** Coerce a palette family. Set `allowNeutral` for role assignments. */
+declare function coerceFamily(input: unknown, allowNeutral?: boolean): RoleFamilyInput;
+declare function coerceIntensity(input: unknown): 'solid' | 'soft';
+declare function coerceScheme(input: unknown): 'light' | 'dark' | 'auto';
+type RoundnessStyle = 'sharp' | 'default' | 'rounded' | 'pill';
+declare function coerceRoundnessStyle(input: unknown): RoundnessStyle;
+/** Coerce a radius value: numbers become `${n}px`; CSS strings are normalized. */
+declare function coerceRadius(input: unknown): string;
+
+/**
+ * Theme state summarization + contrast feedback for the WebMCP tools.
+ *
+ * Every mutation tool returns a compact `ThemeSummary` plus any contrast
+ * warnings, so an agent gets actionable feedback without a follow-up read
+ * (arcade.dev "proactive state-returning").
+ */
+
+declare const RADIUS_PRESETS: Record<string, Record<string, string>>;
+interface RoleState {
+    family: string;
+    intensity: string;
+}
+interface ThemeSummary {
+    brand: {
+        primary: string | null;
+        secondary: string | null;
+        accent: string | null;
+    };
+    roles: Record<string, RoleState | null>;
+    typography: {
+        fontFamily: string;
+        fontSize: string;
+        fontWeight: string;
+        lineHeight: string;
+    };
+    roundness: {
+        style: RoundnessStyle | 'custom';
+        radius: Record<string, string>;
+    };
+    colorScheme: string;
+    history: {
+        index: number;
+        canUndo: boolean;
+        canRedo: boolean;
+    };
+}
+declare function buildSummary(state: ThemeEditorLike): ThemeSummary;
+interface ContrastPair {
+    key: string;
+    label: string;
+    fg: string;
+    bg: string;
+}
+declare const CONTRAST_PAIRS: ContrastPair[];
+interface ContrastWarning {
+    code: 'contrast';
+    pair: string;
+    variant: 'light' | 'dark';
+    ratio: number;
+    threshold: number;
+    message: string;
+}
+declare const CONTRAST_THRESHOLDS: {
+    readonly AA: 4.5;
+    readonly AAA: 7;
+};
+type ContrastLevel = keyof typeof CONTRAST_THRESHOLDS;
+interface ContrastCheck {
+    pair: string;
+    label: string;
+    variant: 'light' | 'dark';
+    fg: string;
+    bg: string;
+    ratio: number;
+    threshold: number;
+    passes: boolean;
+    suggestion?: string;
+}
+interface ContrastReport {
+    level: ContrastLevel;
+    checks: ContrastCheck[];
+    failures: ContrastCheck[];
+}
+/** Run contrast over the named pairs (default: all) for the given variant(s). */
+declare function runContrastChecks(state: ThemeEditorLike, level?: ContrastLevel, variant?: 'light' | 'dark' | 'both', pairKeys?: string[]): ContrastReport;
+/** Compact contrast warnings for the regions a mutation touched. */
+declare function quickContrastWarnings(state: ThemeEditorLike, pairKeys: string[], variant?: 'light' | 'dark' | 'both', level?: ContrastLevel): ContrastWarning[];
+
+export { ADVANCED_TOKENS_SECTION, ALL_ROLES, ALL_TABS, BRAND_PALETTE_SECTION, BUILT_IN_PRESETS, type BuildTranscriptStreamFramesOptions, COLORS_SECTIONS, COLOR_FAMILIES, COMPONENTS_SECTIONS, COMPONENT_COLOR_SECTIONS, COMPONENT_SHAPE_SECTIONS, CONFIGURE_SECTIONS, CONFIGURE_SUB_GROUPS, CONTRAST_PAIRS, CSS_NAMED_COLORS, type ColorScaleOptions, type CompareMode, type ConfigChangeListener, type ConfiguratorSnapshot, type ContrastCheck, type ContrastLevel, type ContrastReport, type ContrastWarning, type CreateThemeEditorToolsOptions, DEVICE_DIMENSIONS, type DetectedRoleAssignment, type EditTarget, type FieldDef, type FieldType, HOME_SUGGESTION_CHIPS, INTERFACE_ROLES_SECTION, MOCK_BROWSER_CONTENT, MOCK_WORKSPACE_CONTENT, type OnChangeCallback, PALETTE_SECTION, PREVIEW_STORAGE_ADAPTER, type PreviewConfigOptions, type PreviewDevice, type PreviewLifecycleContext, type PreviewScene, type PreviewShellMode, type PreviewShellPalette, type PreviewTranscriptEntryPreset, RADIUS_PRESETS, ROLE_ASSISTANT_MESSAGES, ROLE_BORDERS, ROLE_FAMILIES, ROLE_FAMILY_LABELS, ROLE_HEADER, ROLE_INPUT, ROLE_INTENSITIES, ROLE_LINKS_FOCUS, ROLE_PRIMARY_ACTIONS, ROLE_SCROLL_TO_BOTTOM, ROLE_SURFACES, ROLE_USER_MESSAGES, type RoleAssignmentOptions, type RoleFamily, type RoleIntensity, type RoleState, type RoleTarget, type RoleTargetKind, SEMANTIC_COLORS_SECTION, SHADE_KEYS, SHELL_STYLE_ID, STATUS_COLORS_SECTION, STATUS_PALETTE_SECTION, STYLE_SECTIONS, STYLE_SECTIONS_V2, type SectionDef, type SectionPreset, type SelectOption, type SliderOptions, type SubGroupDef, THEME_EDITOR_PRESETS, THEME_SECTION, type TabDef, type ThemeEditorLike, type ThemeEditorPreset, ThemeEditorState, type ThemePreviewHandle, type ThemePreviewOptions, type ThemeSummary, type TokenRefOptions, type ToolAnnotations, type ToolExecute, type ToolResult, type ToolTextContent, type TranscriptStreamFrame, type WebMcpTool, ZOOM_MAX, ZOOM_MIN, appendPreviewTranscriptEntry, applySceneConfig, applyShellTheme, buildPreviewConfig, buildPreviewConfigWithMessages, buildShellCss, buildSrcdoc, buildSummary, buildTranscriptStreamFrames, coerceColor, coerceFamily, coerceIntensity, coerceRadius, coerceRoundnessStyle, coerceScheme, convertFromPx, convertToPx, createPreviewMessages, createPreviewTranscriptEntry, createThemeEditorTools, createThemePreview, detectRoleAssignment, escapeHtml, findSection, formatCssValue, generateColorScale, getPreviewTranscriptPresetLabel, getShellPalette, getThemeEditorPreset, hexToHsl, hslToHex, isValidHex, normalizeColorValue, paletteColorPath, parseCssValue, presetStreamsText, quickContrastWarnings, resolveRoleAssignment, resolveThemeColorPath, rgbToHex, runContrastChecks, scopeSection, tokenRefDisplayName, toolResult, wcagContrastRatio };