@runtypelabs/persona 1.48.0 → 2.1.0

package/src/utils/dom.ts

@@ -12,6 +12,18 @@ export const createElement = <K extends keyof HTMLElementTagNameMap>(
   return element;
 };
 
+export const createElementInDocument = <K extends keyof HTMLElementTagNameMap>(
+  documentRef: Document,
+  tag: K,
+  className?: string
+): HTMLElementTagNameMap[K] => {
+  const element = documentRef.createElement(tag);
+  if (className) {
+    element.className = className;
+  }
+  return element;
+};
+
 export const createFragment = (): DocumentFragment => {
   return document.createDocumentFragment();
 };
@@ -22,4 +34,3 @@ export const createFragment = (): DocumentFragment => {
 
 
 
-

package/src/utils/message-fingerprint.test.ts

@@ -0,0 +1,187 @@
+import { describe, it, expect, vi } from "vitest";
+import {
+  computeMessageFingerprint,
+  createMessageCache,
+  getCachedWrapper,
+  setCachedWrapper,
+  pruneCache,
+  type FingerprintableMessage,
+} from "./message-fingerprint";
+
+function makeMessage(overrides: Partial<FingerprintableMessage> = {}): FingerprintableMessage {
+  return {
+    id: "msg-1",
+    role: "assistant",
+    content: "Hello world",
+    streaming: false,
+    ...overrides,
+  };
+}
+
+function createFakeWrapper(id: string): HTMLElement {
+  return {
+    id: `wrapper-${id}`,
+    cloneNode: vi.fn(function (this: HTMLElement) {
+      return { ...this };
+    }),
+  } as unknown as HTMLElement;
+}
+
+describe("computeMessageFingerprint", () => {
+  it("produces a stable fingerprint for the same message", () => {
+    const msg = makeMessage();
+    const fp1 = computeMessageFingerprint(msg, 0);
+    const fp2 = computeMessageFingerprint(msg, 0);
+    expect(fp1).toBe(fp2);
+  });
+
+  it("changes when content changes", () => {
+    const fp1 = computeMessageFingerprint(makeMessage({ content: "Hello" }), 0);
+    const fp2 = computeMessageFingerprint(makeMessage({ content: "Hello world" }), 0);
+    expect(fp1).not.toBe(fp2);
+  });
+
+  it("changes when streaming changes", () => {
+    const fp1 = computeMessageFingerprint(makeMessage({ streaming: false }), 0);
+    const fp2 = computeMessageFingerprint(makeMessage({ streaming: true }), 0);
+    expect(fp1).not.toBe(fp2);
+  });
+
+  it("changes when role changes", () => {
+    const fp1 = computeMessageFingerprint(makeMessage({ role: "assistant" }), 0);
+    const fp2 = computeMessageFingerprint(makeMessage({ role: "user" }), 0);
+    expect(fp1).not.toBe(fp2);
+  });
+
+  it("changes when variant changes", () => {
+    const fp1 = computeMessageFingerprint(makeMessage({ variant: undefined }), 0);
+    const fp2 = computeMessageFingerprint(makeMessage({ variant: "reasoning" }), 0);
+    expect(fp1).not.toBe(fp2);
+  });
+
+  it("changes when configVersion changes", () => {
+    const msg = makeMessage();
+    const fp1 = computeMessageFingerprint(msg, 0);
+    const fp2 = computeMessageFingerprint(msg, 1);
+    expect(fp1).not.toBe(fp2);
+  });
+
+  it("changes when rawContent changes", () => {
+    const fp1 = computeMessageFingerprint(makeMessage({ rawContent: undefined }), 0);
+    const fp2 = computeMessageFingerprint(makeMessage({ rawContent: '{"action":"checkout"}' }), 0);
+    expect(fp1).not.toBe(fp2);
+  });
+
+  it("changes when llmContent changes", () => {
+    const fp1 = computeMessageFingerprint(makeMessage({ llmContent: undefined }), 0);
+    const fp2 = computeMessageFingerprint(makeMessage({ llmContent: "context for llm" }), 0);
+    expect(fp1).not.toBe(fp2);
+  });
+
+  it("changes when approval status changes", () => {
+    const fp1 = computeMessageFingerprint(makeMessage({ approval: { status: "pending" } }), 0);
+    const fp2 = computeMessageFingerprint(makeMessage({ approval: { status: "approved" } }), 0);
+    expect(fp1).not.toBe(fp2);
+  });
+
+  it("changes when toolCall status changes", () => {
+    const fp1 = computeMessageFingerprint(makeMessage({ toolCall: { status: "running" } }), 0);
+    const fp2 = computeMessageFingerprint(makeMessage({ toolCall: { status: "complete" } }), 0);
+    expect(fp1).not.toBe(fp2);
+  });
+
+  it("changes when reasoning chunks change", () => {
+    const fp1 = computeMessageFingerprint(makeMessage({ reasoning: { chunks: ["step 1"] } }), 0);
+    const fp2 = computeMessageFingerprint(makeMessage({ reasoning: { chunks: ["step 1", "step 2"] } }), 0);
+    expect(fp1).not.toBe(fp2);
+  });
+
+  it("changes when contentParts length changes", () => {
+    const fp1 = computeMessageFingerprint(makeMessage({ contentParts: [] }), 0);
+    const fp2 = computeMessageFingerprint(makeMessage({ contentParts: [{ type: "text", text: "hi" }] }), 0);
+    expect(fp1).not.toBe(fp2);
+  });
+
+  it("handles undefined optional fields", () => {
+    const msg: FingerprintableMessage = { id: "x", role: "user", content: "" };
+    const fp = computeMessageFingerprint(msg, 0);
+    expect(typeof fp).toBe("string");
+    expect(fp.length).toBeGreaterThan(0);
+  });
+
+  it("detects streaming content appends via last-32-chars check", () => {
+    const fp1 = computeMessageFingerprint(
+      makeMessage({ content: "The quick brown fox jumps over the lazy dog" }),
+      0
+    );
+    const fp2 = computeMessageFingerprint(
+      makeMessage({ content: "The quick brown fox jumps over the lazy dog!" }),
+      0
+    );
+    expect(fp1).not.toBe(fp2);
+  });
+});
+
+describe("MessageCache", () => {
+  it("returns null for unknown message id", () => {
+    const cache = createMessageCache();
+    expect(getCachedWrapper(cache, "unknown", "fp")).toBeNull();
+  });
+
+  it("returns cached wrapper on fingerprint match", () => {
+    const cache = createMessageCache();
+    const wrapper = createFakeWrapper("msg-1");
+    setCachedWrapper(cache, "msg-1", "fp-abc", wrapper);
+
+    const result = getCachedWrapper(cache, "msg-1", "fp-abc");
+    expect(result).toBe(wrapper);
+  });
+
+  it("returns null on fingerprint mismatch", () => {
+    const cache = createMessageCache();
+    const wrapper = createFakeWrapper("msg-1");
+    setCachedWrapper(cache, "msg-1", "fp-abc", wrapper);
+
+    const result = getCachedWrapper(cache, "msg-1", "fp-different");
+    expect(result).toBeNull();
+  });
+
+  it("overwrites entry on re-set", () => {
+    const cache = createMessageCache();
+    const wrapper1 = createFakeWrapper("msg-1");
+    const wrapper2 = createFakeWrapper("msg-1");
+    setCachedWrapper(cache, "msg-1", "fp-1", wrapper1);
+    setCachedWrapper(cache, "msg-1", "fp-2", wrapper2);
+
+    expect(getCachedWrapper(cache, "msg-1", "fp-1")).toBeNull();
+    expect(getCachedWrapper(cache, "msg-1", "fp-2")).toBe(wrapper2);
+  });
+
+  it("prunes entries for removed message IDs", () => {
+    const cache = createMessageCache();
+    setCachedWrapper(cache, "a", "fp-a", createFakeWrapper("a"));
+    setCachedWrapper(cache, "b", "fp-b", createFakeWrapper("b"));
+    setCachedWrapper(cache, "c", "fp-c", createFakeWrapper("c"));
+
+    const active = new Set(["a", "b"]);
+    pruneCache(cache, active);
+
+    expect(getCachedWrapper(cache, "a", "fp-a")).not.toBeNull();
+    expect(getCachedWrapper(cache, "b", "fp-b")).not.toBeNull();
+    expect(getCachedWrapper(cache, "c", "fp-c")).toBeNull();
+  });
+
+  it("handles pruning with empty active set", () => {
+    const cache = createMessageCache();
+    setCachedWrapper(cache, "a", "fp-a", createFakeWrapper("a"));
+
+    pruneCache(cache, new Set());
+    expect(getCachedWrapper(cache, "a", "fp-a")).toBeNull();
+  });
+
+  it("handles pruning an empty cache", () => {
+    const cache = createMessageCache();
+    pruneCache(cache, new Set(["a"]));
+    expect(cache.size).toBe(0);
+  });
+});

package/src/utils/message-fingerprint.ts

@@ -0,0 +1,105 @@
+/**
+ * Message-level fingerprint cache for skipping re-renders of unchanged messages.
+ *
+ * During streaming, every SSE chunk triggers renderMessagesWithPluginsImpl which
+ * rebuilds ALL message bubbles. The fingerprint cache lets us skip rebuilding
+ * messages whose content hasn't changed, so only the actively streaming message
+ * is re-rendered each cycle.
+ */
+
+export type FingerprintableMessage = {
+  id: string;
+  role: string;
+  content: string;
+  streaming?: boolean;
+  variant?: string;
+  rawContent?: string;
+  llmContent?: string;
+  approval?: { status?: string; [key: string]: unknown };
+  toolCall?: { status?: string; [key: string]: unknown };
+  reasoning?: { chunks?: string[]; status?: string; [key: string]: unknown };
+  contentParts?: unknown[];
+};
+
+export type MessageCacheEntry = {
+  fingerprint: string;
+  wrapper: HTMLElement;
+};
+
+export type MessageCache = Map<string, MessageCacheEntry>;
+
+/**
+ * Compute a fast fingerprint for a message to detect changes.
+ * Uses string concatenation with a delimiter rather than JSON.stringify for performance.
+ * The configVersion parameter ensures cache invalidation when widget config changes.
+ */
+export function computeMessageFingerprint(
+  message: FingerprintableMessage,
+  configVersion: number
+): string {
+  return [
+    message.id,
+    message.role,
+    message.content?.length ?? 0,
+    message.content?.slice(-32) ?? "",
+    message.streaming ? "1" : "0",
+    message.variant ?? "",
+    message.rawContent?.length ?? 0,
+    message.llmContent?.length ?? 0,
+    message.approval?.status ?? "",
+    message.toolCall?.status ?? "",
+    message.reasoning?.chunks?.length ?? 0,
+    message.contentParts?.length ?? 0,
+    configVersion,
+  ].join("\x00");
+}
+
+/**
+ * Create a new message cache instance.
+ */
+export function createMessageCache(): MessageCache {
+  return new Map();
+}
+
+/**
+ * Look up a cached wrapper for a message. Returns the cached wrapper
+ * if the fingerprint matches, or null if the message needs re-rendering.
+ */
+export function getCachedWrapper(
+  cache: MessageCache,
+  messageId: string,
+  fingerprint: string
+): HTMLElement | null {
+  const entry = cache.get(messageId);
+  if (entry && entry.fingerprint === fingerprint) {
+    return entry.wrapper;
+  }
+  return null;
+}
+
+/**
+ * Store a rendered wrapper in the cache.
+ */
+export function setCachedWrapper(
+  cache: MessageCache,
+  messageId: string,
+  fingerprint: string,
+  wrapper: HTMLElement
+): void {
+  cache.set(messageId, { fingerprint, wrapper });
+}
+
+/**
+ * Remove cache entries for messages that no longer exist.
+ * Call after each render pass with the current message IDs.
+ */
+export function pruneCache(
+  cache: MessageCache,
+  activeMessageIds: Set<string>
+): void {
+  for (const key of cache.keys()) {
+    if (!activeMessageIds.has(key)) {
+      cache.delete(key);
+    }
+  }
+}

package/src/utils/migration.ts

@@ -0,0 +1,220 @@
+import type { AgentWidgetTheme } from '../types';
+import type { PersonaTheme } from '../types/theme';
+
+export interface V1ToV2MigrationOptions {
+  warn?: boolean;
+  colorScheme?: 'light' | 'dark' | 'auto';
+}
+
+const v1ToV2Mapping: Record<string, string> = {
+  primary: 'palette.colors.primary.500',
+  secondary: 'palette.colors.secondary.500',
+  accent: 'palette.colors.accent.600',
+  surface: 'palette.colors.gray.50',
+  muted: 'palette.colors.gray.500',
+  container: 'palette.colors.gray.100',
+  border: 'palette.colors.gray.200',
+  divider: 'palette.colors.gray.200',
+  messageBorder: 'palette.colors.gray.200',
+  inputBackground: 'palette.colors.gray.50',
+  callToAction: 'palette.colors.gray.900',
+  callToActionBackground: 'palette.colors.gray.50',
+  sendButtonBackgroundColor: 'semantic.colors.primary',
+  sendButtonTextColor: 'semantic.colors.textInverse',
+  sendButtonBorderColor: 'semantic.colors.primary',
+  closeButtonColor: 'palette.colors.gray.500',
+  closeButtonBackgroundColor: 'transparent',
+  clearChatIconColor: 'palette.colors.gray.500',
+  clearChatBackgroundColor: 'transparent',
+  micIconColor: 'palette.colors.gray.900',
+  micBackgroundColor: 'transparent',
+  recordingIconColor: 'palette.colors.white',
+  recordingBackgroundColor: 'palette.colors.error.500',
+  tooltipBackground: 'palette.colors.gray.900',
+  tooltipForeground: 'palette.colors.white',
+};
+
+const v1RadiusMapping: Record<string, string> = {
+  radiusSm: 'palette.radius.md',
+  radiusMd: 'palette.radius.lg',
+  radiusLg: 'palette.radius.xl',
+  launcherRadius: 'palette.radius.full',
+  buttonRadius: 'palette.radius.full',
+};
+
+export function migrateV1Theme(
+  v1Theme: AgentWidgetTheme | undefined,
+  options: V1ToV2MigrationOptions = {}
+): Partial<PersonaTheme> {
+  if (!v1Theme) {
+    return {};
+  }
+
+  const migrated: any = {
+    palette: {
+      colors: {
+        primary: {},
+        gray: {},
+        secondary: {},
+        accent: {},
+        success: {},
+        warning: {},
+        error: {},
+      },
+    },
+    semantic: {
+      colors: {
+        interactive: {},
+        feedback: {},
+      },
+    },
+  };
+
+  for (const [key, value] of Object.entries(v1Theme)) {
+    if (!value) continue;
+
+    if (key in v1ToV2Mapping) {
+      const v2Path = v1ToV2Mapping[key];
+      const [category, type, name, shade] = v2Path.split('.');
+
+      if (category === 'palette' && type === 'colors') {
+        const colorName = name as keyof typeof migrated.palette.colors;
+        if (migrated.palette.colors[colorName]) {
+          (migrated.palette.colors[colorName] as any)[shade || '500'] = value;
+        }
+      } else if (category === 'semantic') {
+        const pathParts = v2Path.replace('semantic.colors.', '').split('.');
+        if (pathParts.length === 1) {
+          migrated.semantic.colors[pathParts[0]] = value;
+        } else {
+          (migrated.semantic.colors as any)[pathParts[0]] = {
+            ...(migrated.semantic.colors as any)[pathParts[0]],
+            [pathParts[1]]: value,
+          };
+        }
+      }
+    } else if (key in v1RadiusMapping) {
+      if (!migrated.palette.radius) {
+        migrated.palette.radius = {};
+      }
+      const radiusKey = key.replace('radius', '').toLowerCase();
+      (migrated.palette.radius as any)[radiusKey || 'md'] = value;
+    } else if (key === 'inputFontFamily') {
+      if (!migrated.palette.typography) {
+        migrated.palette.typography = { fontFamily: {} };
+      }
+      migrated.palette.typography.fontFamily = {
+        sans: value === 'sans-serif' ? 'system-ui, sans-serif' : undefined,
+        serif: value === 'serif' ? 'Georgia, serif' : undefined,
+        mono: value === 'mono' ? 'monospace' : undefined,
+      };
+    } else if (key === 'inputFontWeight') {
+      if (!migrated.palette.typography) {
+        migrated.palette.typography = { fontWeight: {} };
+      }
+      migrated.palette.typography.fontWeight = {
+        normal: value,
+      };
+    } else if (key === 'panelBorder') {
+      if (!migrated.components) {
+        migrated.components = {};
+      }
+      if (!migrated.components.panel) {
+        migrated.components.panel = {};
+      }
+      migrated.components.panel.border = value;
+    } else if (key === 'panelShadow') {
+      if (!migrated.components) {
+        migrated.components = {};
+      }
+      if (!migrated.components.panel) {
+        migrated.components.panel = {};
+      }
+      migrated.components.panel.shadow = value;
+    } else if (key === 'panelBorderRadius') {
+      if (!migrated.components) {
+        migrated.components = {};
+      }
+      if (!migrated.components.panel) {
+        migrated.components.panel = {};
+      }
+      migrated.components.panel.borderRadius = value;
+    } else if (key === 'messageUserShadow') {
+      if (!migrated.components) migrated.components = {};
+      if (!migrated.components.message) migrated.components.message = {};
+      if (!migrated.components.message.user) migrated.components.message.user = {};
+      (migrated.components.message.user as { shadow?: string }).shadow = value as string;
+    } else if (key === 'messageAssistantShadow') {
+      if (!migrated.components) migrated.components = {};
+      if (!migrated.components.message) migrated.components.message = {};
+      if (!migrated.components.message.assistant) migrated.components.message.assistant = {};
+      (migrated.components.message.assistant as { shadow?: string }).shadow = value as string;
+    } else if (key === 'toolBubbleShadow') {
+      if (!migrated.components) migrated.components = {};
+      if (!migrated.components.toolBubble) migrated.components.toolBubble = {};
+      (migrated.components.toolBubble as { shadow?: string }).shadow = value as string;
+    } else if (key === 'reasoningBubbleShadow') {
+      if (!migrated.components) migrated.components = {};
+      if (!migrated.components.reasoningBubble) migrated.components.reasoningBubble = {};
+      (migrated.components.reasoningBubble as { shadow?: string }).shadow = value as string;
+    } else if (key === 'composerShadow') {
+      if (!migrated.components) migrated.components = {};
+      if (!migrated.components.composer) migrated.components.composer = {};
+      (migrated.components.composer as { shadow?: string }).shadow = value as string;
+    }
+  }
+
+  if (options.warn !== false) {
+    console.warn(
+      '[Persona Widget] v1 theme configuration detected. ' +
+        'v1 themes are deprecated in v2.0.0. ' +
+        'Please migrate to the new semantic token system. ' +
+        'See https://persona.sh/docs/v2-migration for guidance.'
+    );
+  }
+
+  return migrated;
+}
+
+export function validateV1Theme(v1Theme: unknown): {
+  valid: boolean;
+  warnings: string[];
+} {
+  const warnings: string[] = [];
+  const theme = v1Theme as AgentWidgetTheme | undefined;
+
+  if (!theme) {
+    return { valid: true, warnings: [] };
+  }
+
+  const v1ThemeChromeKeys = new Set([
+    'panelBorder',
+    'panelShadow',
+    'panelBorderRadius',
+    'messageUserShadow',
+    'messageAssistantShadow',
+    'toolBubbleShadow',
+    'reasoningBubbleShadow',
+    'composerShadow',
+  ]);
+
+  const deprecatedProperties = Object.keys(theme).filter(
+    (key) =>
+      !(
+        key in v1ToV2Mapping ||
+        key in v1RadiusMapping ||
+        key === 'inputFontFamily' ||
+        key === 'inputFontWeight' ||
+        key.startsWith('panel') ||
+        v1ThemeChromeKeys.has(key)
+      )
+  );
+
+  if (deprecatedProperties.length > 0) {
+    warnings.push(
+      `The following v1 theme properties have no v2 equivalent and will be ignored: ${deprecatedProperties.join(', ')}`
+    );
+  }
+
+  return { valid: true, warnings };
+}

package/src/utils/morph.ts

@@ -27,7 +27,7 @@ export const morphMessages = (
         // Preserve typing indicator dots to maintain animation continuity
         // Also preserve elements with data-preserve-animation attribute for custom loading indicators
         if (preserveTypingAnimation) {
-          if (oldNode.classList.contains("tvw-animate-typing") ||
+          if (oldNode.classList.contains("persona-animate-typing") ||
               oldNode.hasAttribute("data-preserve-animation")) {
             return false;
           }