@runtypelabs/persona 3.16.0 → 3.17.0

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);
+  });
 });

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] },
 ];