@runtypelabs/persona 3.15.1 → 3.17.0

package/src/session.ts

@@ -971,6 +971,11 @@ export class AgentWidgetSession {
   public cancel() {
     this.abortController?.abort();
     this.abortController = null;
+    // Stop any in-progress audio too — when the user hits "stop", they want
+    // the assistant to actually stop talking, not just stop generating tokens.
+    // Both helpers are safe no-ops when audio isn't configured.
+    this.stopSpeaking();
+    this.stopVoicePlayback();
     this.setStreaming(false);
     this.setStatus("idle");
   }

package/src/styles/widget.css

@@ -2824,3 +2824,136 @@
     transform: translateX(0);
   }
 }
+
+/* ============================================================
+   Stream animations — reveal effects for assistant message text
+   while streaming. Opt-in via `features.streamAnimation.type`.
+   Units are staggered via `--char-index` / `--word-index`
+   (set inline on each wrapper span). Timing is configured via
+   `--persona-stream-step` and `--persona-stream-duration` on
+   the `.persona-message-content` container.
+   ============================================================ */
+
+/* Per-char/per-word spans need to be inline-block so `transform` works for
+   the rise/fade animations. Each span animates from the moment it is first
+   added to the DOM — streaming itself provides the visible stagger, so the
+   CSS animation has no per-index delay. An index-based delay would compound
+   with the stream's arrival cadence and leave later chars permanently hidden. */
+[data-persona-root] .persona-stream-char,
+[data-persona-root] .persona-stream-word {
+  display: inline-block;
+  will-change: opacity, transform, filter;
+}
+
+/* Group chars belonging to the same word so the browser treats the word as a
+   single break unit. Without this, every inline-block char introduces a break
+   opportunity and words get split mid-letter during streaming, then snap back
+   when the final content replaces the wrapped spans. */
+[data-persona-root] .persona-stream-word-group {
+  white-space: nowrap;
+}
+
+/* ---------- typewriter: fade per arriving char + blinking caret ---------- */
+@keyframes persona-stream-typewriter-in {
+  from { opacity: 0; }
+  to { opacity: 1; }
+}
+[data-persona-root] .persona-stream-typewriter .persona-stream-char {
+  animation: persona-stream-typewriter-in var(--persona-stream-step, 120ms) ease-out both;
+}
+
+/* ---------- letter-rise: per-char translateY + fade ---------- */
+@keyframes persona-stream-letter-rise {
+  from { opacity: 0; transform: translateY(8px); }
+  to { opacity: 1; transform: translateY(0); }
+}
+[data-persona-root] .persona-stream-letter-rise .persona-stream-char {
+  animation: persona-stream-letter-rise calc(var(--persona-stream-step, 120ms) * 2)
+    ease-out both;
+}
+
+/* ---------- word-fade: per-word blur + translateY fade-in ---------- */
+@keyframes persona-stream-word-fade {
+  from { opacity: 0; filter: blur(4px); transform: translateY(3px); }
+  to { opacity: 1; filter: blur(0); transform: translateY(0); }
+}
+[data-persona-root] .persona-stream-word-fade .persona-stream-word {
+  animation: persona-stream-word-fade calc(var(--persona-stream-step, 120ms) * 3)
+    ease-out both;
+}
+
+/* The following animations live in subpath plugin modules — their CSS is
+   injected by the plugin when activated, not by the core stylesheet:
+   - `wipe`        → @runtypelabs/persona/animations/wipe
+   - `glyph-cycle` → @runtypelabs/persona/animations/glyph-cycle */
+
+/* ---------- pop-bubble: scale + opacity entrance on the bubble ---------- */
+@keyframes persona-stream-pop-in {
+  0%   { transform: scale(0.6); opacity: 0; }
+  100% { transform: scale(1);   opacity: 1; }
+}
+[data-persona-root] .persona-stream-pop {
+  transform-origin: bottom left;
+  animation: persona-stream-pop-in 400ms cubic-bezier(0.2, 0.9, 0.3, 1.4) both;
+}
+
+/* ---------- caret used by typewriter ---------- */
+@keyframes persona-stream-blink {
+  0%, 50%      { opacity: 1; }
+  50.01%, 100% { opacity: 0; }
+}
+[data-persona-root] .persona-stream-caret {
+  display: inline-block;
+  width: 2px;
+  height: 1em;
+  margin-left: 1px;
+  vertical-align: -2px;
+  background: currentColor;
+  animation: persona-stream-blink 1s steps(1) infinite;
+}
+
+/* ---------- skeleton placeholder (pre-first-token) ---------- */
+@keyframes persona-stream-skeleton-shimmer {
+  0%   { background-position: 200% 0; }
+  100% { background-position: -200% 0; }
+}
+[data-persona-root] .persona-stream-skeleton {
+  padding: 2px 0;
+  /* The assistant bubble sizes to content. Give the skeleton an intrinsic
+     width so the bubble expands; the bubble's own `max-width: 85%` clamps
+     the upper bound. */
+  width: 260px;
+  max-width: 100%;
+}
+[data-persona-root] .persona-stream-skeleton-line {
+  width: 100%;
+  height: 10px;
+  border-radius: 3px;
+  background: linear-gradient(
+    90deg,
+    color-mix(in srgb, currentColor 12%, transparent) 0%,
+    color-mix(in srgb, currentColor 22%, transparent) 50%,
+    color-mix(in srgb, currentColor 12%, transparent) 100%
+  );
+  background-size: 200% 100%;
+  animation: persona-stream-skeleton-shimmer 1.4s linear infinite;
+}
+
+/* ---------- reduced-motion: disable per-unit and container animations ---------- */
+@media (prefers-reduced-motion: reduce) {
+  [data-persona-root] .persona-stream-typewriter .persona-stream-char,
+  [data-persona-root] .persona-stream-letter-rise .persona-stream-char,
+  [data-persona-root] .persona-stream-word-fade .persona-stream-word,
+  [data-persona-root] .persona-stream-pop,
+  [data-persona-root] .persona-stream-caret,
+  [data-persona-root] .persona-stream-skeleton-line {
+    animation: none !important;
+    opacity: 1 !important;
+    filter: none !important;
+    transform: none !important;
+    color: inherit !important;
+    background: none !important;
+    -webkit-background-clip: border-box !important;
+            background-clip: border-box !important;
+  }
+}

package/src/testing/index.ts

@@ -0,0 +1,11 @@
+/** @runtypelabs/persona/testing — Helpers for mocking SSE streams in demos, previews, and tests. */
+
+export {
+  createMockSSEStream,
+  createMockSSEResponse,
+  buildAssistantTurnFrames,
+  type MockSSEFrame,
+  type CreateMockSSEStreamOptions,
+  type MockSSEResponseOptions,
+  type AssistantTurnFramesOptions,
+} from "./mock-stream";

package/src/testing/mock-stream.test.ts

@@ -0,0 +1,80 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  buildAssistantTurnFrames,
+  createMockSSEResponse,
+  createMockSSEStream,
+} from "./mock-stream";
+
+async function readAll(stream: ReadableStream<Uint8Array>): Promise<string> {
+  const reader = stream.getReader();
+  const decoder = new TextDecoder();
+  let out = "";
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    out += decoder.decode(value);
+  }
+  return out;
+}
+
+describe("createMockSSEStream", () => {
+  it("emits bare `data:` frames by default", async () => {
+    const frames = [
+      { type: "agent_turn_start", executionId: "e-1", turnId: "t-1" },
+      { type: "agent_turn_delta", executionId: "e-1", turnId: "t-1", delta: "hi" },
+      { type: "agent_turn_complete", executionId: "e-1", turnId: "t-1" },
+    ];
+    const text = await readAll(createMockSSEStream(frames, { delayMs: 0 }));
+
+    expect(text).not.toContain("event:");
+    expect(text.split("\n\n").filter(Boolean)).toHaveLength(3);
+    expect(text).toContain('"type":"agent_turn_delta"');
+    expect(text).toContain('"delta":"hi"');
+  });
+
+  it("emits named event frames when eventName is set", async () => {
+    const text = await readAll(
+      createMockSSEStream([{ type: "ping" }], { delayMs: 0, eventName: "message" })
+    );
+    expect(text.startsWith("event: message\n")).toBe(true);
+  });
+});
+
+describe("buildAssistantTurnFrames", () => {
+  it("chunks text into delta frames bracketed by start/complete", () => {
+    const frames = buildAssistantTurnFrames({
+      executionId: "exec-1",
+      turnId: "turn-1",
+      text: "abcdefghij",
+      chunkSize: 4,
+    });
+
+    expect(frames[0]).toEqual({ type: "agent_turn_start", executionId: "exec-1", turnId: "turn-1" });
+    expect(frames[frames.length - 1]).toEqual({
+      type: "agent_turn_complete",
+      executionId: "exec-1",
+      turnId: "turn-1",
+    });
+
+    const deltas = frames.filter((f) => f.type === "agent_turn_delta");
+    expect(deltas.map((f) => f.delta)).toEqual(["abcd", "efgh", "ij"]);
+    expect(deltas.every((f) => f.executionId === "exec-1" && f.turnId === "turn-1")).toBe(true);
+  });
+
+  it("defaults turnId and chunkSize", () => {
+    const frames = buildAssistantTurnFrames({ executionId: "exec-2", text: "hello" });
+    expect(frames[0].turnId).toBe("turn-1");
+    const deltaCount = frames.filter((f) => f.type === "agent_turn_delta").length;
+    expect(deltaCount).toBeGreaterThanOrEqual(1);
+  });
+});
+
+describe("createMockSSEResponse", () => {
+  it("wraps the stream in a text/event-stream Response", async () => {
+    const res = createMockSSEResponse([{ type: "ping" }], { delayMs: 0 });
+    expect(res.status).toBe(200);
+    expect(res.headers.get("Content-Type")).toBe("text/event-stream");
+    expect(await res.text()).toContain('"type":"ping"');
+  });
+});

package/src/testing/mock-stream.ts

@@ -0,0 +1,94 @@
+/** Shared helpers for mocking SSE streams in demos, previews, and tests. */
+
+export interface MockSSEFrame {
+  type: string;
+  [key: string]: unknown;
+}
+
+export interface CreateMockSSEStreamOptions {
+  /** Delay in ms between emitted frames. Default: 100. */
+  delayMs?: number;
+  /**
+   * Named event name. When set, each frame is emitted as `event: <name>\ndata: ...\n\n`.
+   * Omit for bare `data: ...\n\n` form (both are valid SSE and the widget parser accepts either).
+   */
+  eventName?: string;
+}
+
+const encoder = new TextEncoder();
+
+export function createMockSSEStream(
+  frames: ReadonlyArray<MockSSEFrame>,
+  options?: CreateMockSSEStreamOptions
+): ReadableStream<Uint8Array> {
+  const delayMs = options?.delayMs ?? 100;
+  const prefix = options?.eventName ? `event: ${options.eventName}\n` : "";
+  let index = 0;
+
+  return new ReadableStream<Uint8Array>({
+    async pull(controller) {
+      if (index >= frames.length) {
+        controller.close();
+        return;
+      }
+      await new Promise<void>((resolve) => setTimeout(resolve, delayMs));
+      const payload = JSON.stringify(frames[index]);
+      controller.enqueue(encoder.encode(`${prefix}data: ${payload}\n\n`));
+      index += 1;
+    },
+  });
+}
+
+export interface AssistantTurnFramesOptions {
+  /** Execution id shared across the turn's frames. */
+  executionId: string;
+  /** Turn id. Default: `turn-1`. */
+  turnId?: string;
+  /** Assistant text content to stream. */
+  text: string;
+  /** Approximate characters per `agent_turn_delta` frame. Default: 32. */
+  chunkSize?: number;
+}
+
+/**
+ * Builds the standard `agent_turn_start` → many `agent_turn_delta` → `agent_turn_complete`
+ * frame sequence for simulating a streaming assistant reply. The frames drive the same
+ * client pipeline as real SSE, so stream animations (typewriter, word-fade, etc.) engage.
+ */
+export function buildAssistantTurnFrames(options: AssistantTurnFramesOptions): MockSSEFrame[] {
+  const { executionId, text } = options;
+  const turnId = options.turnId ?? "turn-1";
+  const chunkSize = Math.max(1, options.chunkSize ?? 32);
+
+  const frames: MockSSEFrame[] = [{ type: "agent_turn_start", executionId, turnId }];
+  for (let i = 0; i < text.length; i += chunkSize) {
+    frames.push({
+      type: "agent_turn_delta",
+      executionId,
+      turnId,
+      delta: text.slice(i, i + chunkSize),
+    });
+  }
+  frames.push({ type: "agent_turn_complete", executionId, turnId });
+  return frames;
+}
+
+export interface MockSSEResponseOptions extends CreateMockSSEStreamOptions {
+  status?: number;
+  headers?: Record<string, string>;
+}
+
+/** Convenience wrapper: returns a `Response` ready to hand back from a `customFetch` implementation. */
+export function createMockSSEResponse(
+  frames: ReadonlyArray<MockSSEFrame>,
+  options?: MockSSEResponseOptions
+): Response {
+  const stream = createMockSSEStream(frames, options);
+  return new Response(stream, {
+    status: options?.status ?? 200,
+    headers: {
+      "Content-Type": "text/event-stream",
+      ...options?.headers,
+    },
+  });
+}

package/src/testing.ts

@@ -0,0 +1,2 @@
+/** Entry point for @runtypelabs/persona/testing */
+export * from "./testing/index";

package/src/theme-editor/index.ts

@@ -84,6 +84,8 @@ export {
   getPreviewTranscriptPresetLabel,
   createPreviewTranscriptEntry,
   appendPreviewTranscriptEntry,
+  presetStreamsText,
+  buildTranscriptStreamFrames,
   createPreviewMessages,
   applySceneConfig,
   buildPreviewConfig,
@@ -94,6 +96,8 @@ export type {
   PreviewTranscriptEntryPreset,
   PreviewShellPalette,
   PreviewConfigOptions,
+  TranscriptStreamFrame,
+  BuildTranscriptStreamFramesOptions,
 } from './preview-utils';
 
 // Role mappings (Interface Roles editor)

package/src/theme-editor/preview-utils.test.ts

@@ -3,7 +3,9 @@ import { describe, expect, it } from "vitest";
 import {
   appendPreviewTranscriptEntry,
   buildPreviewConfig,
+  buildTranscriptStreamFrames,
   createPreviewTranscriptEntry,
+  presetStreamsText,
 } from "./preview-utils";
 
 describe("theme editor preview demo data", () => {
@@ -55,4 +57,62 @@ describe("theme editor preview demo data", () => {
     expect(updated[0].variant).toBe("tool");
     expect(updated[1].variant).toBe("reasoning");
   });
+
+  it("creates assistant code-block, table, and image presets with markdown content", () => {
+    const code = createPreviewTranscriptEntry("assistant-code-block", 1);
+    const table = createPreviewTranscriptEntry("assistant-markdown-table", 2);
+    const image = createPreviewTranscriptEntry("assistant-image", 3);
+
+    for (const message of [code, table, image]) {
+      expect(message.role).toBe("assistant");
+      expect(message.variant).toBeUndefined();
+      expect(typeof message.content).toBe("string");
+    }
+
+    expect(code.content).toContain("```ts");
+    expect(table.content).toContain("| Preset");
+    expect(image.content).toContain("![");
+  });
+
+  it("flags assistant text presets as streaming and non-text presets as not", () => {
+    expect(presetStreamsText("assistant-message")).toBe(true);
+    expect(presetStreamsText("assistant-code-block")).toBe(true);
+    expect(presetStreamsText("assistant-markdown-table")).toBe(true);
+    expect(presetStreamsText("assistant-image")).toBe(true);
+    expect(presetStreamsText("user-message")).toBe(false);
+    expect(presetStreamsText("reasoning-streaming")).toBe(false);
+    expect(presetStreamsText("tool-running")).toBe(false);
+  });
+
+  it("builds a single done frame for non-streaming presets", () => {
+    const frames = buildTranscriptStreamFrames("user-message", 0);
+    expect(frames).toHaveLength(1);
+    expect(frames[0].done).toBe(true);
+    expect(frames[0].delayMs).toBe(0);
+    expect(frames[0].message.role).toBe("user");
+  });
+
+  it("builds progressive snapshots for assistant text presets ending with streaming:false", () => {
+    const frames = buildTranscriptStreamFrames("assistant-message", 0, { chunkSize: 10, delayMs: 5 });
+    expect(frames.length).toBeGreaterThan(1);
+
+    const first = frames[0];
+    expect(first.message.content).toBe("");
+    expect(first.message.streaming).toBe(true);
+    expect(first.delayMs).toBe(0);
+    expect(first.done).toBe(false);
+
+    for (let i = 1; i < frames.length - 1; i += 1) {
+      expect(frames[i].message.streaming).toBe(true);
+      expect(frames[i].done).toBe(false);
+      expect(frames[i].delayMs).toBe(5);
+    }
+
+    const last = frames[frames.length - 1];
+    expect(last.message.streaming).toBe(false);
+    expect(last.done).toBe(true);
+    const completed = createPreviewTranscriptEntry("assistant-message", 0);
+    expect(last.message.content).toBe(completed.content);
+    expect(last.message.id).toBe(completed.id);
+  });
 });

package/src/theme-editor/preview-utils.ts

@@ -200,6 +200,9 @@ export type PreviewScene = 'home' | 'conversation' | 'minimized' | 'artifact';
 export type PreviewTranscriptEntryPreset =
   | 'user-message'
   | 'assistant-message'
+  | 'assistant-code-block'
+  | 'assistant-markdown-table'
+  | 'assistant-image'
   | 'reasoning-streaming'
   | 'reasoning-complete'
   | 'tool-running'
@@ -208,6 +211,9 @@ export type PreviewTranscriptEntryPreset =
 const PREVIEW_TRANSCRIPT_PRESET_LABELS: Record<PreviewTranscriptEntryPreset, string> = {
   'user-message': 'User message',
   'assistant-message': 'Assistant message',
+  'assistant-code-block': 'Assistant — code block',
+  'assistant-markdown-table': 'Assistant — markdown table',
+  'assistant-image': 'Assistant — image',
   'reasoning-streaming': 'Reasoning (streaming)',
   'reasoning-complete': 'Reasoning (complete)',
   'tool-running': 'Tool call (running)',
@@ -240,6 +246,56 @@ export function createPreviewTranscriptEntry(
         content: 'Absolutely. I can keep going and explain what happens next.',
         createdAt,
       };
+    case 'assistant-code-block':
+      return {
+        id: `preview-seq-assistant-code-${suffix}`,
+        role: 'assistant',
+        content: [
+          "Here's how you'd wire up a streaming animation:",
+          '',
+          '```ts',
+          "import { createAgentExperience } from '@runtypelabs/persona';",
+          '',
+          'createAgentExperience(el, {',
+          '  features: {',
+          '    streamAnimation: { type: "letter-rise", speed: 120 },',
+          '  },',
+          '});',
+          '```',
+          '',
+          'Swap the `type` value to try the other presets.',
+        ].join('\n'),
+        createdAt,
+      };
+    case 'assistant-markdown-table':
+      return {
+        id: `preview-seq-assistant-table-${suffix}`,
+        role: 'assistant',
+        content: [
+          'Here are the built-in streaming animations at a glance:',
+          '',
+          '| Preset       | Wrap unit | Best for                    |',
+          '| ------------ | --------- | --------------------------- |',
+          '| Typewriter   | Character | Classic terminal feel       |',
+          '| Letter rise  | Character | Soft, staggered entrance    |',
+          '| Word fade    | Word      | Longer-form assistant replies |',
+          '| Pop bubble   | Bubble    | Short, punchy affirmations  |',
+        ].join('\n'),
+        createdAt,
+      };
+    case 'assistant-image':
+      return {
+        id: `preview-seq-assistant-image-${suffix}`,
+        role: 'assistant',
+        content: [
+          "Here's the reference diagram you asked for — let me know if you'd like a different view:",
+          '',
+          '![Stream animation reference](https://placehold.co/320x200/png?text=Stream+Animation)',
+          '',
+          'The gradient shows how per-unit delays stagger across the reply.',
+        ].join('\n'),
+        createdAt,
+      };
     case 'reasoning-streaming':
       return {
         id: `preview-seq-reasoning-stream-${suffix}`,
@@ -312,6 +368,79 @@ export function appendPreviewTranscriptEntry(
   return [...messages, createPreviewTranscriptEntry(preset, messages.length)];
 }
 
+/** Presets whose assistant content should stream in so Stream Animation settings engage. */
+export function presetStreamsText(preset: PreviewTranscriptEntryPreset): boolean {
+  return (
+    preset === 'assistant-message' ||
+    preset === 'assistant-code-block' ||
+    preset === 'assistant-markdown-table' ||
+    preset === 'assistant-image'
+  );
+}
+
+export interface TranscriptStreamFrame {
+  /** Message to upsert into the session. */
+  message: AgentWidgetMessage;
+  /** Delay from the previous frame in ms. The first frame uses 0. */
+  delayMs: number;
+  /** True when this is the final frame (message is no longer streaming). */
+  done: boolean;
+}
+
+export interface BuildTranscriptStreamFramesOptions {
+  /** Characters per progressive chunk. Default: 24. */
+  chunkSize?: number;
+  /** Delay between chunks in ms. Default: 42. */
+  delayMs?: number;
+}
+
+/**
+ * Builds progressive snapshots for a transcript preset suitable for feeding into
+ * `injectTestMessage({ type: 'message', message })` on a timer. Each frame upserts
+ * the same message id with more content, ending with `streaming: false`.
+ *
+ * - Streaming-capable presets (assistant text) yield many frames.
+ * - All other presets yield a single `done` frame matching `createPreviewTranscriptEntry`.
+ */
+export function buildTranscriptStreamFrames(
+  preset: PreviewTranscriptEntryPreset,
+  suffix: number,
+  options?: BuildTranscriptStreamFramesOptions
+): TranscriptStreamFrame[] {
+  const completed = createPreviewTranscriptEntry(preset, suffix);
+  if (!presetStreamsText(preset) || typeof completed.content !== 'string') {
+    return [{ message: completed, delayMs: 0, done: true }];
+  }
+
+  const chunkSize = Math.max(1, options?.chunkSize ?? 24);
+  const delayMs = Math.max(0, options?.delayMs ?? 42);
+  const fullText = completed.content;
+  const frames: TranscriptStreamFrame[] = [];
+
+  // Seed with an empty streaming bubble so the animation plugin can attach from the first tick.
+  frames.push({
+    message: { ...completed, content: '', streaming: true },
+    delayMs: 0,
+    done: false,
+  });
+
+  for (let i = chunkSize; i < fullText.length; i += chunkSize) {
+    frames.push({
+      message: { ...completed, content: fullText.slice(0, i), streaming: true },
+      delayMs,
+      done: false,
+    });
+  }
+
+  frames.push({
+    message: { ...completed, content: fullText, streaming: false },
+    delayMs,
+    done: true,
+  });
+
+  return frames;
+}
+
 const createAdvancedTranscriptPreviewMessages = (): AgentWidgetMessage[] => [
   {
     id: "preview-adv-1",

package/src/theme-editor/sections.test.ts

@@ -60,4 +60,23 @@ describe("theme editor scroll-to-bottom controls", () => {
     expect(debugSection?.fields.some((field) => field.path === "features.reasoningDisplay.previewMaxLines")).toBe(true);
     expect(debugSection?.fields.some((field) => field.path === "features.reasoningDisplay.activeMinHeight")).toBe(true);
   });
+
+  it("exposes stream animation controls", () => {
+    const section = CONFIGURE_SECTIONS.find((entry) => entry.id === "stream-animation");
+
+    expect(section).toBeDefined();
+    const paths = section?.fields.map((field) => field.path) ?? [];
+    expect(paths).toEqual(
+      expect.arrayContaining([
+        "features.streamAnimation.type",
+        "features.streamAnimation.placeholder",
+        "features.streamAnimation.buffer",
+        "features.streamAnimation.speed",
+        "features.streamAnimation.duration",
+      ])
+    );
+
+    const speedField = section?.fields.find((field) => field.path === "features.streamAnimation.speed");
+    expect(speedField?.parseValue?.("240")).toBe(240);
+  });
 });