@runtypelabs/persona 3.17.0 → 3.19.0

package/src/types/theme.ts

@@ -237,6 +237,19 @@ export interface MessageTokens {
   border?: TokenReference<'color'>;
 }
 
+/**
+ * Welcome / intro card rendered above the message list when no messages exist.
+ * Set `copy.showWelcomeCard: false` to hide it; use `layout.slots["body-top"]`
+ * to replace it wholesale.
+ */
+export interface IntroCardTokens extends ComponentTokenSet {
+  background?: TokenReference<'color'>;
+  borderRadius?: TokenReference<'radius'>;
+  padding?: TokenReference<'spacing'>;
+  /** Box-shadow on the intro card (token ref or raw CSS, e.g. `none`). */
+  shadow?: string;
+}
+
 /** Collapsible widget chrome (tool bubbles, reasoning bubbles, approval bubbles). */
 export interface CollapsibleWidgetTokens {
   /** Background for content areas. */
@@ -449,6 +462,8 @@ export interface ComponentTokens {
   panel: PanelTokens;
   header: HeaderTokens;
   message: MessageTokens;
+  /** Welcome / intro card shown above the message list. */
+  introCard?: IntroCardTokens;
   /** Markdown surfaces (chat + artifact pane). */
   markdown?: MarkdownTokens;
   voice: VoiceTokens;

package/src/types.ts

@@ -205,6 +205,31 @@ export type AgentMessageMetadata = {
    * or `prompt` step inside the nested flow). Stable key for that step.
    */
   parentStepId?: string;
+  /**
+   * Set to `true` on a tool-variant message produced from a `step_await`
+   * event (`awaitReason: "local_tool_required"`). Signals to UI code that
+   * the tool call is a LOCAL tool and the server is paused waiting for a
+   * `POST /v1/dispatch/resume` with the user's answer keyed by tool name.
+   */
+  awaitingLocalTool?: boolean;
+  /**
+   * 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
+   * answer-pill sheet for this tool call on subsequent render passes.
+   */
+  askUserQuestionAnswered?: boolean;
+  /**
+   * In-progress answers for a multi-question `ask_user_question` payload,
+   * keyed by question text. Persisted across refresh so the user lands back
+   * where they were if the page reloads mid-flow. Cleared once
+   * `askUserQuestionAnswered` flips to `true`.
+   */
+  askUserQuestionAnswers?: Record<string, string | string[]>;
+  /**
+   * Current page index for a multi-question `ask_user_question` payload's
+   * paginated stepper. Persists alongside `askUserQuestionAnswers`.
+   */
+  askUserQuestionIndex?: number;
 };
 
 export type AgentWidgetRequestMiddlewareContext = {
@@ -270,6 +295,8 @@ export type AgentWidgetActionHandler = (
 export type AgentWidgetStoredState = {
   messages?: AgentWidgetMessage[];
   metadata?: Record<string, unknown>;
+  artifacts?: PersonaArtifactRecord[];
+  selectedArtifactId?: string | null;
 };
 
 export interface AgentWidgetStorageAdapter {
@@ -857,6 +884,118 @@ export type AgentWidgetFeatureFlags = {
   artifacts?: AgentWidgetArtifactsFeature;
   /** Reveal animation for streaming assistant text. */
   streamAnimation?: AgentWidgetStreamAnimationFeature;
+  /**
+   * Built-in interactive answer-pill sheet shown when the assistant invokes
+   * the `ask_user_question` tool. Slides up over the composer with tappable
+   * pills + optional free-text input.
+   */
+  askUserQuestion?: AgentWidgetAskUserQuestionFeature;
+};
+
+/**
+ * Single selectable option in an `ask_user_question` prompt.
+ * Mirrors Anthropic's AskUserQuestion schema.
+ */
+export type AskUserQuestionOption = {
+  /** Pill label (required). */
+  label: string;
+  /** Optional long-form description (shown as a subtitle on tap-hover). */
+  description?: string;
+  /** Optional rich preview — reserved for future rendering; ignored in v1. */
+  preview?: string;
+};
+
+/**
+ * A single question in an `ask_user_question` tool call.
+ * The tool may carry 1–8 prompts. When more than one is supplied, the built-in
+ * renderer paginates them as a "Question N of M" stepper with Back / Next /
+ * Submit-all controls; single-question payloads render without stepper chrome.
+ */
+export type AskUserQuestionPrompt = {
+  /** The question text shown to the user. */
+  question: string;
+  /** Optional short header label (≤12 chars) used as a compact group title. */
+  header?: string;
+  /** 2–4 selectable options. */
+  options: AskUserQuestionOption[];
+  /** When true, the user can pick multiple options and submit together. Default false. */
+  multiSelect?: boolean;
+  /** When true, a free-text "Other…" pill expands to an input. Default true. */
+  allowFreeText?: boolean;
+};
+
+/** Parsed payload of an `ask_user_question` tool call. */
+export type AskUserQuestionPayload = {
+  /** 1–8 questions. Anything beyond the renderer's cap is truncated with a console warning. */
+  questions: AskUserQuestionPrompt[];
+};
+
+/**
+ * Style overrides for the answer-pill sheet. All values are raw CSS strings
+ * and are plumbed through as CSS custom properties on the sheet root.
+ */
+export type AgentWidgetAskUserQuestionStyles = {
+  sheetBackground?: string;
+  sheetBorder?: string;
+  sheetShadow?: string;
+  pillBackground?: string;
+  pillBackgroundSelected?: string;
+  pillTextColor?: string;
+  pillTextColorSelected?: string;
+  pillBorderRadius?: string;
+  customInputBackground?: string;
+};
+
+/**
+ * Feature config for the built-in `ask_user_question` answer-pill sheet.
+ * When a tool call with the name `ask_user_question` arrives, the widget
+ * renders an interactive sheet over the composer in place of the generic
+ * tool bubble.
+ */
+export type AgentWidgetAskUserQuestionFeature = {
+  /** Enable the feature. Defaults to true. When false, `ask_user_question` renders as a regular tool bubble. */
+  enabled?: boolean;
+  /** Slide-in animation duration in ms. Defaults to 180. */
+  slideInMs?: number;
+  /** Label for the free-text pill. Defaults to "Other…". */
+  freeTextLabel?: string;
+  /** Placeholder text in the free-text input. Defaults to "Type your answer…". */
+  freeTextPlaceholder?: string;
+  /** Button label for submitting multi-select / free-text answers. Defaults to "Send". */
+  submitLabel?: string;
+  /** Button label advancing to the next question in grouped (paginated) payloads. Defaults to "Next". */
+  nextLabel?: string;
+  /** Button label moving back to the previous question in grouped payloads. Defaults to "Back". */
+  backLabel?: string;
+  /** Button label submitting all answers from the final page of a grouped payload. Defaults to "Submit all". */
+  submitAllLabel?: string;
+  /**
+   * In grouped (multi-question) mode, auto-advance to the next page after a
+   * single-select pill pick or free-text submit on intermediate pages.
+   * Defaults to `true`. The final page never auto-submits — users always
+   * confirm with an explicit "Submit all" click. Multi-select pages always
+   * require an explicit Next regardless of this setting.
+   */
+  groupedAutoAdvance?: boolean;
+  /**
+   * Visual layout for the option list.
+   * - `"rows"` (default) — full-width stacked rows with always-visible
+   *   descriptions, right-edge number badges (single-select) or checkboxes
+   *   (multi-select), and an always-visible inline "Other" input.
+   * - `"pills"` — legacy compact pill list with horizontal wrap; description
+   *   surfaces as a tooltip and the "Other…" pill expands on click.
+   */
+  layout?: "rows" | "pills";
+  /**
+   * Button label for skipping the current question in grouped payloads.
+   * Defaults to "Skip". On intermediate pages Skip advances without recording
+   * an answer; on the final page Skip submits the partial answer record
+   * (skipped questions absent from the resolved object). For single-question
+   * payloads Skip behaves like dismiss.
+   */
+  skipLabel?: string;
+  /** Style overrides for the sheet and pills. */
+  styles?: AgentWidgetAskUserQuestionStyles;
 };
 
 export type SSEEventRecord = {
@@ -1011,6 +1150,103 @@ export type AgentWidgetDockConfig = {
   reveal?: "resize" | "overlay" | "push" | "emerge";
 };
 
+/**
+ * Layout configuration for `mountMode: "composer-bar"`. Controls how the
+ * collapsed pill is positioned and sized, and how the panel expands when
+ * the user opens it.
+ */
+export type AgentWidgetComposerBarConfig = {
+  /**
+   * Max-width of the collapsed pill composer at the bottom of the viewport.
+   * @default "720px"
+   */
+  collapsedMaxWidth?: string;
+  /**
+   * Bottom offset (CSS length) from the viewport edge in the collapsed state.
+   * @default "16px"
+   */
+  bottomOffset?: string;
+  /**
+   * Auto-expand the panel when the user submits a message while the composer
+   * is collapsed. When false, the message still sends but the panel remains
+   * collapsed (the host can drive expansion programmatically).
+   * @default true
+   */
+  expandOnSubmit?: boolean;
+  /**
+   * Size of the expanded chat panel.
+   * - `"anchored"` (default): the pill stays at the bottom of the viewport
+   *   and the chat history grows upward into a centered column above it.
+   *   Width is driven by `expandedMaxWidth`; the panel's top edge sits at
+   *   `expandedTopOffset` from the viewport top.
+   * - `"fullscreen"`: covers the entire viewport (mobile-app style). Inner
+   *   content is centered horizontally via `contentMaxWidth`.
+   * - `"modal"`: centered sheet with margins; size driven by
+   *   `modalMaxWidth` / `modalMaxHeight`.
+   * @default "anchored"
+   */
+  expandedSize?: "anchored" | "fullscreen" | "modal";
+  /**
+   * When `expandedSize === "anchored"`, max-width of the expanded panel
+   * column. Capped at `calc(100vw - 32px)` on narrow viewports.
+   * @default "880px"
+   */
+  expandedMaxWidth?: string;
+  /**
+   * When `expandedSize === "anchored"`, distance from the viewport top to
+   * the panel's top edge. Accepts any CSS length.
+   * @default "5vh"
+   */
+  expandedTopOffset?: string;
+  /**
+   * Max-width applied to messages, composer form, suggestions, and
+   * attachment previews so they center horizontally inside the expanded
+   * panel. Falls back to `layout.contentMaxWidth` when set; otherwise
+   * defaults to this value.
+   * @default "720px"
+   */
+  contentMaxWidth?: string;
+  /**
+   * When `expandedSize === "modal"`, max-width of the expanded sheet.
+   * @default "880px"
+   */
+  modalMaxWidth?: string;
+  /**
+   * When `expandedSize === "modal"`, max-height of the expanded sheet.
+   * @default "min(90vh, 800px)"
+   */
+  modalMaxHeight?: string;
+  /**
+   * Configuration for the "peek" banner — the chrome-less row above the
+   * collapsed pill that previews the most recent assistant message.
+   */
+  peek?: AgentWidgetComposerBarPeekConfig;
+};
+
+/**
+ * Configuration for the composer-bar peek banner. Reuses the same
+ * `streamAnimation` shape developers already configure for the main message
+ * stream, so the surface for animations is identical across both contexts.
+ *
+ * Resolution order:
+ * - If `peek.streamAnimation` is set, those values apply to the peek.
+ * - Otherwise the peek inherits from `features.streamAnimation`.
+ *
+ * Per-surface carve-outs:
+ * - `bubbleClass` from a plugin (used by `pop-bubble`) is ignored — the peek
+ *   has no bubble analog.
+ * - `containerClass`, `wrap` ("char" | "word"), `useCaret`, `placeholder`
+ *   ("skeleton"), `buffer` ("word" | "line"), `speed`, `duration`, and
+ *   custom plugins all apply unchanged.
+ */
+export type AgentWidgetComposerBarPeekConfig = {
+  /**
+   * Reveal animation for the peek's trailing-message preview. Same shape as
+   * `features.streamAnimation`. Omit to inherit from the main stream config.
+   */
+  streamAnimation?: AgentWidgetStreamAnimationFeature;
+};
+
 export type AgentWidgetLauncherConfig = {
   enabled?: boolean;
   title?: string;
@@ -1025,14 +1261,22 @@ export type AgentWidgetLauncherConfig = {
    * Controls how the launcher panel is mounted relative to the host page.
    * - "floating": default floating launcher / panel behavior
    * - "docked": wraps the target container and renders as a sibling dock
+   * - "composer-bar": persistent rounded-pill composer fixed to the bottom of
+   *   the viewport that morphs into a fullscreen (or modal) chat panel on
+   *   submit and minimizes back to the pill on close.
    *
    * @default "floating"
    */
-  mountMode?: "floating" | "docked";
+  mountMode?: "floating" | "docked" | "composer-bar";
   /**
    * Layout configuration for docked mode.
    */
   dock?: AgentWidgetDockConfig;
+  /**
+   * Layout configuration for composer-bar mode.
+   * Only applies when `mountMode === "composer-bar"`.
+   */
+  composerBar?: AgentWidgetComposerBarConfig;
   autoExpand?: boolean;
   width?: string;
   /**
@@ -2823,6 +3067,17 @@ export type AgentWidgetConfig = {
   autoFocusInput?: boolean;
   launcher?: AgentWidgetLauncherConfig;
   initialMessages?: AgentWidgetMessage[];
+  /**
+   * Artifacts to hydrate into the pane at init. Typically populated from
+   * `storageAdapter.load()` alongside `initialMessages` so the artifact pane
+   * survives a page refresh.
+   */
+  initialArtifacts?: PersonaArtifactRecord[];
+  /**
+   * Which artifact id (if any) should be selected in the pane at init. Paired
+   * with `initialArtifacts`.
+   */
+  initialSelectedArtifactId?: string | null;
   suggestionChips?: string[];
   suggestionChipsConfig?: AgentWidgetSuggestionChipsConfig;
   debug?: boolean;
@@ -3207,6 +3462,13 @@ export type AgentWidgetConfig = {
    * When `true`, uses default settings with sessionStorage.
    * When an object, allows customizing storage type, key prefix, and what to persist.
    *
+   * Setting this to `false` is the explicit kill-switch: it disables UI-state
+   * persistence **and** message-history persistence. When `false`, any
+   * `storageAdapter` you configure is ignored and the default localStorage
+   * adapter is not created — no chat history is read or written. Pass `true`
+   * (or omit) to keep the default behavior of persisting messages via the
+   * configured `storageAdapter` (or the built-in localStorage adapter).
+   *
    * @example
    * ```typescript
    * // Simple usage - persist open state in sessionStorage
@@ -3229,6 +3491,14 @@ export type AgentWidgetConfig = {
    *   }
    * }
    * ```
+   *
+   * @example
+   * ```typescript
+   * // Ephemeral widget — no message history written anywhere
+   * config: {
+   *   persistState: false
+   * }
+   * ```
    */
   persistState?: boolean | AgentWidgetPersistStateConfig;