@runtypelabs/persona 3.18.0 → 3.20.0

package/dist/theme-editor.d.cts

@@ -1726,6 +1726,101 @@ 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.
+ */
+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.
+ */
+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;
+};
 type AgentWidgetLauncherConfig = {
     enabled?: boolean;
     title?: string;
@@ -1740,14 +1835,22 @@ 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;
     /**
@@ -3715,6 +3818,13 @@ 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
@@ -3737,6 +3847,14 @@ type AgentWidgetConfig = {
      *   }
      * }
      * ```
+     *
+     * @example
+     * ```typescript
+     * // Ephemeral widget — no message history written anywhere
+     * config: {
+     *   persistState: false
+     * }
+     * ```
      */
     persistState?: boolean | AgentWidgetPersistStateConfig;
     /**
@@ -3979,6 +4097,22 @@ type InjectMessageOptions = {
      * Consumers can detect this in `messageTransform` to render custom UI.
      */
     voiceProcessing?: boolean;
+    /**
+     * Raw structured payload (typically a JSON string) representing the
+     * full directive that produced this message — e.g. `{ "text": "...",
+     * "component": "Foo", "props": {...} }`.
+     *
+     * Mirrors the field populated by stream parsers during normal LLM
+     * responses. Set this when injecting a message that should render as a
+     * component directive (`hasComponentDirective` /
+     * `extractComponentDirectiveFromMessage` look at `rawContent` first).
+     *
+     * Priority for the API payload remains:
+     * `contentParts > llmContent > rawContent > content`. Pass `llmContent`
+     * alongside `rawContent` if the LLM should see something other than the
+     * raw directive.
+     */
+    rawContent?: string;
 };
 /**
  * Options for injecting assistant messages (most common case).
@@ -3995,6 +4129,57 @@ type InjectUserMessageOptions = Omit<InjectMessageOptions, "role">;
  * Role defaults to 'system'.
  */
 type InjectSystemMessageOptions = Omit<InjectMessageOptions, "role">;
+/**
+ * Options for injecting an assistant message that renders as a component
+ * directive — sugar over `injectAssistantMessage` for the common case of
+ * "render this registered component, same as if the LLM had emitted it".
+ *
+ * Equivalent to calling `injectAssistantMessage({ content: text, rawContent:
+ * JSON.stringify({ text, component, props }), llmContent })`.
+ *
+ * @example
+ * widget.injectComponentDirective({
+ *   component: "DynamicForm",
+ *   props: { title: "Book a demo", fields: [...] },
+ *   text: "Share your details to book a demo.",
+ *   llmContent: "[Showed booking form]"
+ * });
+ */
+type InjectComponentDirectiveOptions = {
+    /**
+     * Name of a renderer registered via `componentRegistry.register(...)`.
+     */
+    component: string;
+    /**
+     * Props passed to the component renderer.
+     */
+    props?: Record<string, unknown>;
+    /**
+     * Bubble copy displayed above (or with) the rendered component.
+     * Mirrors the `text` field in a streamed JSON directive.
+     * @default ""
+     */
+    text?: string;
+    /**
+     * Content sent to the LLM in API requests. When omitted, the raw
+     * directive JSON is what the LLM would see (per the standard
+     * priority chain). Provide a redacted/short version to avoid sending
+     * the full directive in subsequent turns.
+     */
+    llmContent?: string;
+    /**
+     * Optional message ID. If omitted, an assistant id is auto-generated.
+     */
+    id?: string;
+    /**
+     * Optional creation timestamp (ISO string). If omitted, uses current time.
+     */
+    createdAt?: string;
+    /**
+     * Optional sequence number for ordering.
+     */
+    sequence?: number;
+};
 type PersonaArtifactRecord = {
     id: string;
     artifactType: PersonaArtifactKind;
@@ -4362,6 +4547,12 @@ type Controller = {
      * Inject multiple messages in a single batch with one sort and one render pass.
      */
     injectMessageBatch: (optionsList: InjectMessageOptions[]) => AgentWidgetMessage[];
+    /**
+     * Convenience method for injecting an assistant message that renders as a
+     * registered component — same shape Persona produces from a streamed
+     * `{ "text": "...", "component": "...", "props": {...} }` payload.
+     */
+    injectComponentDirective: (options: InjectComponentDirectiveOptions) => AgentWidgetMessage;
     /**
      * @deprecated Use injectMessage() instead.
      */

package/dist/theme-editor.d.ts

@@ -1726,6 +1726,101 @@ 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.
+ */
+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.
+ */
+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;
+};
 type AgentWidgetLauncherConfig = {
     enabled?: boolean;
     title?: string;
@@ -1740,14 +1835,22 @@ 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;
     /**
@@ -3715,6 +3818,13 @@ 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
@@ -3737,6 +3847,14 @@ type AgentWidgetConfig = {
      *   }
      * }
      * ```
+     *
+     * @example
+     * ```typescript
+     * // Ephemeral widget — no message history written anywhere
+     * config: {
+     *   persistState: false
+     * }
+     * ```
      */
     persistState?: boolean | AgentWidgetPersistStateConfig;
     /**
@@ -3979,6 +4097,22 @@ type InjectMessageOptions = {
      * Consumers can detect this in `messageTransform` to render custom UI.
      */
     voiceProcessing?: boolean;
+    /**
+     * Raw structured payload (typically a JSON string) representing the
+     * full directive that produced this message — e.g. `{ "text": "...",
+     * "component": "Foo", "props": {...} }`.
+     *
+     * Mirrors the field populated by stream parsers during normal LLM
+     * responses. Set this when injecting a message that should render as a
+     * component directive (`hasComponentDirective` /
+     * `extractComponentDirectiveFromMessage` look at `rawContent` first).
+     *
+     * Priority for the API payload remains:
+     * `contentParts > llmContent > rawContent > content`. Pass `llmContent`
+     * alongside `rawContent` if the LLM should see something other than the
+     * raw directive.
+     */
+    rawContent?: string;
 };
 /**
  * Options for injecting assistant messages (most common case).
@@ -3995,6 +4129,57 @@ type InjectUserMessageOptions = Omit<InjectMessageOptions, "role">;
  * Role defaults to 'system'.
  */
 type InjectSystemMessageOptions = Omit<InjectMessageOptions, "role">;
+/**
+ * Options for injecting an assistant message that renders as a component
+ * directive — sugar over `injectAssistantMessage` for the common case of
+ * "render this registered component, same as if the LLM had emitted it".
+ *
+ * Equivalent to calling `injectAssistantMessage({ content: text, rawContent:
+ * JSON.stringify({ text, component, props }), llmContent })`.
+ *
+ * @example
+ * widget.injectComponentDirective({
+ *   component: "DynamicForm",
+ *   props: { title: "Book a demo", fields: [...] },
+ *   text: "Share your details to book a demo.",
+ *   llmContent: "[Showed booking form]"
+ * });
+ */
+type InjectComponentDirectiveOptions = {
+    /**
+     * Name of a renderer registered via `componentRegistry.register(...)`.
+     */
+    component: string;
+    /**
+     * Props passed to the component renderer.
+     */
+    props?: Record<string, unknown>;
+    /**
+     * Bubble copy displayed above (or with) the rendered component.
+     * Mirrors the `text` field in a streamed JSON directive.
+     * @default ""
+     */
+    text?: string;
+    /**
+     * Content sent to the LLM in API requests. When omitted, the raw
+     * directive JSON is what the LLM would see (per the standard
+     * priority chain). Provide a redacted/short version to avoid sending
+     * the full directive in subsequent turns.
+     */
+    llmContent?: string;
+    /**
+     * Optional message ID. If omitted, an assistant id is auto-generated.
+     */
+    id?: string;
+    /**
+     * Optional creation timestamp (ISO string). If omitted, uses current time.
+     */
+    createdAt?: string;
+    /**
+     * Optional sequence number for ordering.
+     */
+    sequence?: number;
+};
 type PersonaArtifactRecord = {
     id: string;
     artifactType: PersonaArtifactKind;
@@ -4362,6 +4547,12 @@ type Controller = {
      * Inject multiple messages in a single batch with one sort and one render pass.
      */
     injectMessageBatch: (optionsList: InjectMessageOptions[]) => AgentWidgetMessage[];
+    /**
+     * Convenience method for injecting an assistant message that renders as a
+     * registered component — same shape Persona produces from a streamed
+     * `{ "text": "...", "component": "...", "props": {...} }` payload.
+     */
+    injectComponentDirective: (options: InjectComponentDirectiveOptions) => AgentWidgetMessage;
     /**
      * @deprecated Use injectMessage() instead.
      */