@runtypelabs/persona 3.15.1 → 3.17.0

package/src/theme-editor/sections.ts

@@ -697,6 +697,89 @@ const featuresSectionDef: SectionDef = {
   ],
 };
 
+const streamAnimationSectionDef: SectionDef = {
+  id: 'stream-animation', title: 'Stream Animation', description: 'Control how assistant text appears while streaming.', collapsed: true,
+  fields: [
+    {
+      id: 'stream-anim-type',
+      label: 'Animation',
+      description: 'Reveal effect applied to each assistant reply as it streams.',
+      type: 'select',
+      path: 'features.streamAnimation.type',
+      defaultValue: 'none',
+      options: [
+        { value: 'none', label: 'None' },
+        { value: 'typewriter', label: 'Typewriter' },
+        { value: 'word-fade', label: 'Word fade' },
+        { value: 'letter-rise', label: 'Letter rise' },
+        { value: 'glyph-cycle', label: 'Glyph cycle' },
+        { value: 'wipe', label: 'Wipe' },
+        { value: 'pop-bubble', label: 'Pop bubble' },
+      ],
+    },
+    {
+      id: 'stream-anim-placeholder',
+      label: 'Pre-first-token Placeholder',
+      description: 'What to show before the first token arrives.',
+      type: 'select',
+      path: 'features.streamAnimation.placeholder',
+      defaultValue: 'none',
+      options: [
+        { value: 'none', label: 'Typing indicator (default)' },
+        { value: 'skeleton', label: 'Skeleton shimmer' },
+      ],
+    },
+    {
+      id: 'stream-anim-buffer',
+      label: 'Content Buffering',
+      description: 'Trim in-progress units so only complete words/lines reveal.',
+      type: 'select',
+      path: 'features.streamAnimation.buffer',
+      defaultValue: 'none',
+      options: [
+        { value: 'none', label: 'None — stream every character' },
+        { value: 'word', label: 'Word — hold until whitespace' },
+        { value: 'line', label: 'Line — hold until newline' },
+      ],
+    },
+    {
+      id: 'stream-anim-speed',
+      label: 'Per-unit Duration (ms)',
+      description: 'Animation length for each character or word.',
+      type: 'select',
+      path: 'features.streamAnimation.speed',
+      defaultValue: 120,
+      options: [
+        { value: '40', label: '40ms — snappy' },
+        { value: '80', label: '80ms' },
+        { value: '120', label: '120ms (default)' },
+        { value: '200', label: '200ms' },
+        { value: '320', label: '320ms' },
+        { value: '480', label: '480ms — slow' },
+      ],
+      formatValue: (v: unknown) => String(v ?? 120),
+      parseValue: (v: unknown) => Number(v),
+    },
+    {
+      id: 'stream-anim-duration',
+      label: 'Container Duration (ms)',
+      description: 'Length of container-level effects (pop-bubble, custom plugins).',
+      type: 'select',
+      path: 'features.streamAnimation.duration',
+      defaultValue: 1800,
+      options: [
+        { value: '600', label: '600ms' },
+        { value: '1200', label: '1200ms' },
+        { value: '1800', label: '1800ms (default)' },
+        { value: '2400', label: '2400ms' },
+        { value: '3600', label: '3600ms — slow' },
+      ],
+      formatValue: (v: unknown) => String(v ?? 1800),
+      parseValue: (v: unknown) => Number(v),
+    },
+  ],
+};
+
 const attachmentsSectionDef: SectionDef = {
   id: 'attachments-config', title: 'Attachments', collapsed: true,
   fields: [
@@ -773,7 +856,7 @@ export const CONFIGURE_SUB_GROUPS: SubGroupDef[] = [
   { label: 'Content', sections: [copySectionDef, suggestionsSectionDef] },
   { label: 'Layout', sections: [generalLayoutSectionDef, headerLayoutSectionDef, messagesLayoutSectionDef, messageActionsSectionDef] },
   { label: 'Widget', sections: [launcherBasicsSectionDef, launcherAdvancedSectionDef, sendButtonSectionDef, closeButtonSectionDef, clearChatSectionDef, statusIndicatorSectionDef] },
-  { label: 'Features', sections: [featuresSectionDef, attachmentsSectionDef, artifactsSectionDef, artifactCustomizationSectionDef] },
+  { label: 'Features', sections: [featuresSectionDef, streamAnimationSectionDef, attachmentsSectionDef, artifactsSectionDef, artifactCustomizationSectionDef] },
   { label: 'Developer', collapsedByDefault: true, sections: [apiIntegrationSectionDef, debugSectionDef, markdownSectionDef] },
 ];
 

package/src/types.ts

@@ -194,6 +194,17 @@ export type AgentMessageMetadata = {
   iteration?: number;
   turnId?: string;
   agentName?: string;
+  /**
+   * When this message was produced by a step inside a nested flow executed
+   * as a tool, identifies the parent tool call id. Enables renderers to
+   * visually group or indent nested-flow output under its parent tool.
+   */
+  parentToolId?: string;
+  /**
+   * Nested flow step id that produced this message (e.g. a `send-stream`
+   * or `prompt` step inside the nested flow). Stable key for that step.
+   */
+  parentStepId?: string;
 };
 
 export type AgentWidgetRequestMiddlewareContext = {
@@ -669,6 +680,167 @@ export type AgentWidgetReasoningDisplayFeature = {
   loadingAnimation?: AgentWidgetToolCallLoadingAnimation;
 };
 
+/**
+ * Reveal animation applied to assistant message text while it is streaming.
+ *
+ * Built-in types always available:
+ * - `none` — text appears as tokens arrive (default).
+ * - `typewriter` — characters fade in with a blinking caret.
+ * - `pop-bubble` — the bubble scales in; text streams normally afterward.
+ * - `letter-rise` — per-char translateY + fade reveal.
+ * - `word-fade` — per-word blur + translateY fade-in.
+ *
+ * Subpath plugins (import from `@runtypelabs/persona/animations/*` to register):
+ * - `wipe`, `glyph-cycle`.
+ *
+ * Custom types are allowed — register a plugin with any string name and
+ * reference it by that name in `type`.
+ */
+export type AgentWidgetStreamAnimationBuiltinType =
+  | "none"
+  | "typewriter"
+  | "word-fade"
+  | "letter-rise"
+  | "glyph-cycle"
+  | "wipe"
+  | "pop-bubble";
+
+export type AgentWidgetStreamAnimationType =
+  | AgentWidgetStreamAnimationBuiltinType
+  | (string & {});
+
+/**
+ * Placeholder shown inside a streaming assistant bubble before the first token arrives.
+ * - `none` — use the default typing-dots indicator (existing behavior).
+ * - `skeleton` — shimmer bars, replaced by streaming content once it starts.
+ */
+export type AgentWidgetStreamAnimationPlaceholder = "none" | "skeleton";
+
+/**
+ * How much of the accumulated streaming content to display while tokens are
+ * still arriving. Trimming to a boundary means in-progress words or lines
+ * stay hidden until they complete — useful for animations that benefit from
+ * unit-complete reveals (e.g. wipe, glyph-cycle).
+ * - `none` — show every character as it arrives (default).
+ * - `word` — trim to the last whitespace boundary.
+ * - `line` — trim to the last newline boundary.
+ */
+export type AgentWidgetStreamAnimationBuffer = "none" | "word" | "line";
+
+/**
+ * Context passed to plugin lifecycle hooks. Carries the live DOM references
+ * and resolved animation settings for the currently-streaming message.
+ */
+export type StreamAnimationContext = {
+  /** The `.persona-message-content` element owning the streamed text. */
+  container: HTMLElement;
+  /** The outer message bubble element. */
+  bubble: HTMLElement;
+  /** ID of the streaming message. */
+  messageId: string;
+  /** Read-only reference to the message being streamed. */
+  message: AgentWidgetMessage;
+  /** Effective `speed` from `streamAnimation.speed`. */
+  speed: number;
+  /** Effective `duration` from `streamAnimation.duration`. */
+  duration: number;
+};
+
+/**
+ * Pluggable stream animation. Third-party packages and inline registrations
+ * implement this interface to add custom reveal effects.
+ *
+ * Lifecycle:
+ * - When the widget mounts and detects a plugin (either passed via config or
+ *   auto-registered in the IIFE bundle), it injects `styles` once into the
+ *   widget's style host.
+ * - For each streaming assistant message whose `type` matches `name`, the
+ *   widget applies `containerClass` / `bubbleClass`, wraps text per `wrap`,
+ *   and — if `useCaret` is true — appends a blinking caret.
+ * - Hooks fire after the live DOM is morphed; plugins use stable element IDs
+ *   and `data-preserve-animation` to safely mutate per-char or per-word spans
+ *   without idiomorph clobbering in-flight work.
+ */
+export type StreamAnimationPlugin = {
+  /** Plugin identifier. Matches the `type` field in `streamAnimation`. */
+  name: string;
+  /** Class added to `.persona-message-content` while streaming. */
+  containerClass?: string;
+  /** Class added to the bubble element (e.g. a one-shot scale animation). */
+  bubbleClass?: string;
+  /** Wrap mode applied to text nodes during streaming. @default "none" */
+  wrap?: "none" | "char" | "word";
+  /**
+   * HTML tags whose descendant text is skipped during wrapping. Defaults to
+   * `["pre", "code", "a", "script", "style"]` — useful for keeping code
+   * blocks legible and link click-targets intact. Plugins that want to
+   * animate characters inside inline code (e.g. `glyph-cycle`) can narrow
+   * the list.
+   */
+  skipTags?: string[];
+  /** Append a blinking caret after the last rendered char/word. */
+  useCaret?: boolean;
+  /** CSS string injected into the widget style host on first activation. */
+  styles?: string;
+  /**
+   * Optional custom buffering strategy. Returns the portion of `content`
+   * that should be rendered during streaming. Use this for buffering
+   * schemes beyond the built-in `word` / `line` strategies.
+   */
+  bufferContent?: (content: string, message: AgentWidgetMessage) => string;
+  /**
+   * Fires once when the plugin is first activated inside a widget instance.
+   * Use this to set up MutationObservers or other long-lived listeners.
+   * Return an optional cleanup function that runs on widget destroy.
+   */
+  onAttach?: (root: HTMLElement | ShadowRoot) => (() => void) | void;
+  /** Fires after each render that reaches the live DOM. */
+  onAfterRender?: (ctx: StreamAnimationContext) => void;
+  /** Fires when a streamed message's `streaming` flag flips to false. */
+  onStreamComplete?: (ctx: StreamAnimationContext) => void;
+  /**
+   * Report whether the plugin still has in-flight animation work for a
+   * message. When `true`, the widget keeps rendering the message in its
+   * "streaming-animated" mode even after `message.streaming` flips false —
+   * preventing the final non-animated render from yanking the rug out from
+   * under unfinished per-char cycles or reveals.
+   */
+  isAnimating?: (message: AgentWidgetMessage) => boolean;
+};
+
+export type AgentWidgetStreamAnimationFeature = {
+  /** Reveal animation to apply while streaming. @default "none" */
+  type?: AgentWidgetStreamAnimationType;
+  /** Pre-first-token placeholder. @default "none" */
+  placeholder?: AgentWidgetStreamAnimationPlaceholder;
+  /**
+   * Per-unit animation duration (ms) for `typewriter`, `letter-rise`, `word-fade`,
+   * and per-unit plugin animations. Each arriving character/word animates from
+   * invisible to visible over this duration, independent of its position — the
+   * streaming cadence itself provides the visible stagger.
+   * @default 120
+   */
+  speed?: number;
+  /**
+   * Total duration of container-level animations (`pop-bubble` and custom
+   * plugin animations), in milliseconds.
+   * @default 1800
+   */
+  duration?: number;
+  /**
+   * Trim the accumulated streaming content to a word or line boundary before
+   * rendering. Hides in-progress units until they complete.
+   * @default "none"
+   */
+  buffer?: AgentWidgetStreamAnimationBuffer;
+  /**
+   * Extra animation plugins available to this widget instance. Keys are
+   * plugin names; the matching plugin activates when `type` is set to that
+   * name. Built-in types (`typewriter`, `pop-bubble`) are always registered.
+   */
+  plugins?: Record<string, StreamAnimationPlugin>;
+};
+
 export type AgentWidgetFeatureFlags = {
   showReasoning?: boolean;
   showToolCalls?: boolean;
@@ -683,6 +855,8 @@ export type AgentWidgetFeatureFlags = {
   eventStream?: EventStreamConfig;
   /** Optional artifact sidebar (split pane / mobile drawer) */
   artifacts?: AgentWidgetArtifactsFeature;
+  /** Reveal animation for streaming assistant text. */
+  streamAnimation?: AgentWidgetStreamAnimationFeature;
 };
 
 export type SSEEventRecord = {
@@ -985,6 +1159,10 @@ export type AgentWidgetSendButtonConfig = {
   backgroundColor?: string;
   textColor?: string;
   size?: string;
+  /** Lucide icon name shown while a response is streaming. Clicking the button in this state aborts the stream. Default: "square". */
+  stopIconName?: string;
+  /** Tooltip text shown while streaming. Default: "Stop generating". */
+  stopTooltipText?: string;
 };
 
 /** Optional composer UI state for custom `renderComposer` implementations. */
@@ -2597,11 +2775,21 @@ export type AgentWidgetConfig = {
     welcomeSubtitle?: string;
     inputPlaceholder?: string;
     sendButtonLabel?: string;
+    /** Button label shown in text mode while a response is streaming. Default: "Stop". */
+    stopButtonLabel?: string;
     /**
      * When false, the welcome / intro card is not shown above the message list.
      * @default true
      */
     showWelcomeCard?: boolean;
+    /**
+     * Per-stop-reason copy for the inline notice rendered on assistant
+     * bubbles when the runtime reports a non-natural stop (e.g. the agent
+     * loop hit `max_tool_calls` and was cut off mid-loop). Each key is
+     * optional — keys you omit fall back to the built-in defaults. Set a
+     * key to an empty string to suppress the notice for that reason.
+     */
+    stopReasonNotice?: Partial<Record<StopReasonKind, string>>;
   };
   /**
    * Semantic design tokens (`palette`, `semantic`, `components`).
@@ -3110,6 +3298,28 @@ export type AgentWidgetApproval = {
 
 export type AgentWidgetMessageVariant = "assistant" | "reasoning" | "tool" | "approval";
 
+/**
+ * Per-turn / per-step stop reason emitted by the runtime on
+ * `agent_turn_complete` and `step_complete` SSE events. The vocabulary is
+ * owned by the upstream Runtype API — do not extend without coordination.
+ *
+ * - `end_turn` — natural completion (no affordance needed)
+ * - `max_tool_calls` — agent loop tripped the configured tool-call ceiling
+ * - `length` — provider hit max output tokens
+ * - `content_filter` — provider content filter intervened
+ * - `error` — provider/runtime error (prefer existing error rendering)
+ * - `unknown` — explicitly reported but uninformative
+ *
+ * Absent (`undefined`) means "not reported" — distinct from `'unknown'`.
+ */
+export type StopReasonKind =
+  | 'end_turn'
+  | 'max_tool_calls'
+  | 'length'
+  | 'content_filter'
+  | 'error'
+  | 'unknown';
+
 /**
  * Represents a message in the chat conversation.
  *
@@ -3196,6 +3406,17 @@ export type AgentWidgetMessage = {
    * Contains execution context like iteration number and turn ID.
    */
   agentMetadata?: AgentMessageMetadata;
+  /**
+   * Per-turn stop reason reported by the runtime on `agent_turn_complete`
+   * (agent-loop path) or the last `step_complete` for a prompt step
+   * (dispatch / flow path). Absent when the API did not report a value.
+   *
+   * When set to a non-natural value (`max_tool_calls`, `length`,
+   * `content_filter`, `error`), the widget renders an inline notice on
+   * the assistant bubble. See `config.copy.stopReasonNotice` to override
+   * the default copy.
+   */
+  stopReason?: StopReasonKind;
 };
 
 // ============================================================================

package/src/ui.stop-button.test.ts

@@ -0,0 +1,165 @@
+// @vitest-environment jsdom
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { createAgentExperience } from "./ui";
+
+const createMount = () => {
+  const mount = document.createElement("div");
+  document.body.appendChild(mount);
+  return mount;
+};
+
+const flush = async (times = 4) => {
+  for (let i = 0; i < times; i += 1) {
+    // eslint-disable-next-line no-await-in-loop
+    await Promise.resolve();
+  }
+};
+
+describe("createAgentExperience stop-streaming submit button", () => {
+  const originalFetch = global.fetch;
+  let capturedSignals: AbortSignal[] = [];
+
+  beforeEach(() => {
+    capturedSignals = [];
+    vi.stubGlobal("requestAnimationFrame", (cb: (time: number) => void) => {
+      cb(0);
+      return 1;
+    });
+    vi.stubGlobal("cancelAnimationFrame", () => {});
+    window.scrollTo = vi.fn();
+
+    // Fetch hangs until the caller aborts the signal — models an in-flight
+    // SSE stream so the widget stays in the "streaming" state.
+    global.fetch = vi.fn().mockImplementation((_url: string, options: any) => {
+      const signal = options.signal as AbortSignal;
+      capturedSignals.push(signal);
+      return new Promise((_resolve, reject) => {
+        signal.addEventListener("abort", () => {
+          const err = new Error("aborted");
+          err.name = "AbortError";
+          reject(err);
+        });
+      });
+    }) as any;
+  });
+
+  afterEach(() => {
+    document.body.innerHTML = "";
+    global.fetch = originalFetch;
+    vi.restoreAllMocks();
+  });
+
+  it("keeps the submit button enabled while streaming and clicking it cancels the stream", async () => {
+    const mount = createMount();
+    const controller = createAgentExperience(mount, {
+      apiUrl: "https://api.example.com/chat",
+      launcher: { enabled: false },
+    });
+
+    const submit = mount.querySelector<HTMLButtonElement>(
+      "[data-persona-composer-submit]"
+    );
+    expect(submit).not.toBeNull();
+
+    const textarea = mount.querySelector<HTMLTextAreaElement>(
+      "[data-persona-composer-input]"
+    )!;
+    textarea.value = "Hello";
+    submit!.click();
+
+    await flush();
+
+    // Streaming is active: the button must stay enabled so it can be clicked
+    // again to stop the response.
+    expect(controller.getState().streaming).toBe(true);
+    expect(submit!.disabled).toBe(false);
+    expect(capturedSignals).toHaveLength(1);
+    expect(capturedSignals[0].aborted).toBe(false);
+
+    // Second click — acts as "stop generating".
+    submit!.click();
+
+    await flush();
+
+    expect(controller.getState().streaming).toBe(false);
+    expect(capturedSignals[0].aborted).toBe(true);
+    // No new request should have been fired by the stop click.
+    expect(capturedSignals).toHaveLength(1);
+    // Typed text is preserved so the user can resend after stopping.
+    expect(textarea.value).toBe("");
+    // (The textarea was cleared on the *first* submit, not by the stop click —
+    // that's fine because after cancel the user can keep typing.)
+
+    controller.destroy();
+  });
+
+  it("swaps to the stop icon while streaming and back to the send icon after cancel (icon mode)", async () => {
+    const mount = createMount();
+    const controller = createAgentExperience(mount, {
+      apiUrl: "https://api.example.com/chat",
+      launcher: { enabled: false },
+      sendButton: { useIcon: true, iconName: "arrow-up" },
+    });
+
+    const submit = mount.querySelector<HTMLButtonElement>(
+      "[data-persona-composer-submit]"
+    )!;
+    const textarea = mount.querySelector<HTMLTextAreaElement>(
+      "[data-persona-composer-input]"
+    )!;
+
+    // Initial state: send icon (aria-label tracks tooltip default).
+    expect(submit.getAttribute("aria-label")).toBe("Send message");
+
+    textarea.value = "Hi";
+    submit.click();
+    await flush();
+
+    expect(controller.getState().streaming).toBe(true);
+    expect(submit.getAttribute("aria-label")).toBe("Stop generating");
+
+    submit.click();
+    await flush();
+
+    expect(controller.getState().streaming).toBe(false);
+    expect(submit.getAttribute("aria-label")).toBe("Send message");
+
+    controller.destroy();
+  });
+
+  it("swaps the text label in text mode", async () => {
+    const mount = createMount();
+    const controller = createAgentExperience(mount, {
+      apiUrl: "https://api.example.com/chat",
+      launcher: { enabled: false },
+      sendButton: { useIcon: false },
+      copy: { sendButtonLabel: "Send", stopButtonLabel: "Stop" },
+    });
+
+    const submit = mount.querySelector<HTMLButtonElement>(
+      "[data-persona-composer-submit]"
+    )!;
+    const textarea = mount.querySelector<HTMLTextAreaElement>(
+      "[data-persona-composer-input]"
+    )!;
+
+    expect(submit.textContent).toBe("Send");
+
+    textarea.value = "Hi";
+    submit.click();
+    await flush();
+
+    expect(controller.getState().streaming).toBe(true);
+    expect(submit.textContent).toBe("Stop");
+
+    submit.click();
+    await flush();
+
+    expect(controller.getState().streaming).toBe(false);
+    expect(submit.textContent).toBe("Send");
+
+    controller.destroy();
+  });
+});