@runtypelabs/persona 3.6.0 → 3.8.0

package/src/utils/auto-follow.ts

@@ -0,0 +1,112 @@
+export type FollowStateAction = "none" | "pause" | "resume";
+
+export type FollowStateController = {
+  isFollowing: () => boolean;
+  pause: () => boolean;
+  resume: () => boolean;
+};
+
+export type FollowStateScrollInput = {
+  following: boolean;
+  currentScrollTop: number;
+  lastScrollTop: number;
+  nearBottom: boolean;
+  userScrollThreshold: number;
+  isAutoScrolling?: boolean;
+  pauseOnUpwardScroll?: boolean;
+  pauseWhenAwayFromBottom?: boolean;
+  resumeRequiresDownwardScroll?: boolean;
+};
+
+export type FollowStateWheelInput = {
+  following: boolean;
+  deltaY: number;
+  nearBottom?: boolean;
+  resumeWhenNearBottom?: boolean;
+};
+
+export function createFollowStateController(initiallyFollowing = true): FollowStateController {
+  let following = initiallyFollowing;
+
+  return {
+    isFollowing: () => following,
+    pause: () => {
+      if (!following) return false;
+      following = false;
+      return true;
+    },
+    resume: () => {
+      if (following) return false;
+      following = true;
+      return true;
+    }
+  };
+}
+
+export function getScrollBottomOffset(element: Pick<HTMLElement, "scrollHeight" | "clientHeight">): number {
+  return Math.max(0, element.scrollHeight - element.clientHeight);
+}
+
+export function isElementNearBottom(
+  element: Pick<HTMLElement, "scrollTop" | "scrollHeight" | "clientHeight">,
+  threshold: number
+): boolean {
+  return getScrollBottomOffset(element) - element.scrollTop <= threshold;
+}
+
+export function resolveFollowStateFromScroll(
+  input: FollowStateScrollInput
+): { action: FollowStateAction; delta: number; nextLastScrollTop: number } {
+  const {
+    following,
+    currentScrollTop,
+    lastScrollTop,
+    nearBottom,
+    userScrollThreshold,
+    isAutoScrolling = false,
+    pauseOnUpwardScroll = false,
+    pauseWhenAwayFromBottom = true,
+    resumeRequiresDownwardScroll = false
+  } = input;
+
+  const delta = currentScrollTop - lastScrollTop;
+
+  if (isAutoScrolling || Math.abs(delta) < userScrollThreshold) {
+    return { action: "none", delta, nextLastScrollTop: currentScrollTop };
+  }
+
+  if (!following && nearBottom && (!resumeRequiresDownwardScroll || delta > 0)) {
+    return { action: "resume", delta, nextLastScrollTop: currentScrollTop };
+  }
+
+  if (following && pauseOnUpwardScroll && delta < 0) {
+    return { action: "pause", delta, nextLastScrollTop: currentScrollTop };
+  }
+
+  if (following && pauseWhenAwayFromBottom && !nearBottom) {
+    return { action: "pause", delta, nextLastScrollTop: currentScrollTop };
+  }
+
+  return { action: "none", delta, nextLastScrollTop: currentScrollTop };
+}
+
+export function resolveFollowStateFromWheel(
+  input: FollowStateWheelInput
+): FollowStateAction {
+  const {
+    following,
+    deltaY,
+    nearBottom = false,
+    resumeWhenNearBottom = false
+  } = input;
+
+  if (following && deltaY < 0) {
+    return "pause";
+  }
+
+  if (!following && resumeWhenNearBottom && deltaY > 0 && nearBottom) {
+    return "resume";
+  }
+
+  return "none";
+}

package/src/utils/constants.ts

@@ -7,6 +7,19 @@ export const statusCopy: Record<AgentWidgetSessionStatus, string> = {
   error: "Offline"
 };
 
+/**
+ * Default z-index for widget overlays. Used for the floating panel, launcher
+ * button, sidebar, mobile fullscreen, and docked mobile fullscreen modes.
+ * Integrators can override via `launcher.zIndex`.
+ */
+export const DEFAULT_OVERLAY_Z_INDEX = 100000;
+
+/**
+ * Z-index for elements portaled to document.body (tooltips, dropdowns).
+ * Must be above the widget overlay so portaled UI is not clipped.
+ */
+export const PORTALED_OVERLAY_Z_INDEX = DEFAULT_OVERLAY_Z_INDEX + 1;
+
 
 
 

package/src/utils/dropdown.ts

@@ -1,5 +1,6 @@
 import { createElement } from "./dom";
 import { renderLucideIcon } from "./icons";
+import { PORTALED_OVERLAY_Z_INDEX } from "./constants";
 
 export interface DropdownMenuItem {
   id: string;
@@ -73,7 +74,7 @@ export function createDropdownMenu(options: CreateDropdownOptions): DropdownMenu
   if (portal) {
     // Fixed positioning — menu is portaled outside the anchor's overflow context
     menu.style.position = "fixed";
-    menu.style.zIndex = "10000";
+    menu.style.zIndex = String(PORTALED_OVERLAY_Z_INDEX);
   } else {
     // Absolute positioning — menu lives inside the anchor
     menu.style.position = "absolute";

package/src/utils/overlay-host-stacking.test.ts

@@ -0,0 +1,61 @@
+// @vitest-environment jsdom
+
+import { afterEach, describe, expect, it } from "vitest";
+import { syncOverlayHostStacking } from "./overlay-host-stacking";
+
+describe("syncOverlayHostStacking", () => {
+  afterEach(() => {
+    document.body.innerHTML = "";
+  });
+
+  it("sets position relative on a static element and restores on teardown", () => {
+    const host = document.createElement("div");
+    document.body.appendChild(host);
+
+    const teardown = syncOverlayHostStacking(host);
+    expect(host.style.position).toBe("relative");
+    expect(host.style.zIndex).toBe("100000");
+    expect(host.style.isolation).toBe("isolate");
+
+    teardown();
+    expect(host.style.position).toBe("");
+    expect(host.style.zIndex).toBe("");
+    expect(host.style.isolation).toBe("");
+  });
+
+  it("preserves existing positioned value", () => {
+    const host = document.createElement("div");
+    host.style.position = "absolute";
+    document.body.appendChild(host);
+
+    const teardown = syncOverlayHostStacking(host);
+    expect(host.style.position).toBe("absolute");
+    expect(host.style.zIndex).toBe("100000");
+
+    teardown();
+    expect(host.style.position).toBe("absolute");
+    expect(host.style.zIndex).toBe("");
+  });
+
+  it("accepts custom z-index", () => {
+    const host = document.createElement("div");
+    document.body.appendChild(host);
+
+    const teardown = syncOverlayHostStacking(host, 42);
+    expect(host.style.zIndex).toBe("42");
+
+    teardown();
+  });
+
+  it("restores previous inline z-index on teardown", () => {
+    const host = document.createElement("div");
+    host.style.zIndex = "5";
+    document.body.appendChild(host);
+
+    const teardown = syncOverlayHostStacking(host);
+    expect(host.style.zIndex).toBe("100000");
+
+    teardown();
+    expect(host.style.zIndex).toBe("5");
+  });
+});

package/src/utils/overlay-host-stacking.ts

@@ -0,0 +1,38 @@
+import { DEFAULT_OVERLAY_Z_INDEX } from "./constants";
+
+/**
+ * Elevates the light-DOM host element's stacking context so viewport-covering
+ * overlays (sidebar, fullscreen) can escape parent stacking traps.
+ *
+ * - If the host has `position: static`, sets it to `relative` (required for
+ *   `z-index` to take effect).
+ * - Applies `z-index` matching the overlay default.
+ * - Applies `isolation: isolate` to create a predictable stacking context.
+ *
+ * @returns A teardown function that restores only the properties that were changed.
+ */
+export function syncOverlayHostStacking(
+  host: HTMLElement,
+  zIndex: number = DEFAULT_OVERLAY_Z_INDEX
+): () => void {
+  const originalPosition = host.style.position;
+  const originalZIndex = host.style.zIndex;
+  const originalIsolation = host.style.isolation;
+
+  const computed = getComputedStyle(host);
+  const positionWasSet = computed.position === "static" || computed.position === "";
+  if (positionWasSet) {
+    host.style.position = "relative";
+  }
+
+  host.style.zIndex = String(zIndex);
+  host.style.isolation = "isolate";
+
+  return () => {
+    if (positionWasSet) {
+      host.style.position = originalPosition;
+    }
+    host.style.zIndex = originalZIndex;
+    host.style.isolation = originalIsolation;
+  };
+}

package/src/utils/scroll-lock.test.ts

@@ -0,0 +1,64 @@
+// @vitest-environment jsdom
+
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { acquireScrollLock } from "./scroll-lock";
+
+describe("acquireScrollLock", () => {
+  beforeEach(() => {
+    document.body.style.overflow = "";
+    document.body.style.position = "";
+    document.body.style.top = "";
+    document.body.style.width = "";
+  });
+
+  afterEach(() => {
+    document.body.style.overflow = "";
+    document.body.style.position = "";
+    document.body.style.top = "";
+    document.body.style.width = "";
+  });
+
+  it("sets overflow hidden and position fixed on body", () => {
+    const release = acquireScrollLock();
+    expect(document.body.style.overflow).toBe("hidden");
+    expect(document.body.style.position).toBe("fixed");
+    expect(document.body.style.width).toBe("100%");
+
+    release();
+    expect(document.body.style.overflow).toBe("");
+    expect(document.body.style.position).toBe("");
+    expect(document.body.style.width).toBe("");
+  });
+
+  it("is ref-counted: first release does not unlock when second acquire is active", () => {
+    const release1 = acquireScrollLock();
+    const release2 = acquireScrollLock();
+    expect(document.body.style.overflow).toBe("hidden");
+
+    release1();
+    expect(document.body.style.overflow).toBe("hidden");
+
+    release2();
+    expect(document.body.style.overflow).toBe("");
+  });
+
+  it("release is idempotent", () => {
+    const release = acquireScrollLock();
+    release();
+    release();
+    expect(document.body.style.overflow).toBe("");
+  });
+
+  it("restores original body styles on release", () => {
+    document.body.style.overflow = "scroll";
+    document.body.style.position = "relative";
+
+    const release = acquireScrollLock();
+    expect(document.body.style.overflow).toBe("hidden");
+    expect(document.body.style.position).toBe("fixed");
+
+    release();
+    expect(document.body.style.overflow).toBe("scroll");
+    expect(document.body.style.position).toBe("relative");
+  });
+});

package/src/utils/scroll-lock.ts

@@ -0,0 +1,62 @@
+interface ScrollLockState {
+  originalOverflow: string;
+  originalPosition: string;
+  originalTop: string;
+  originalWidth: string;
+  scrollY: number;
+}
+
+let lockCount = 0;
+let savedState: ScrollLockState | null = null;
+
+/**
+ * Acquire a document-level scroll lock. The page body becomes non-scrollable
+ * via `overflow: hidden` with an iOS-safe `position: fixed` pattern that
+ * preserves the visual scroll position.
+ *
+ * Ref-counted: multiple callers can acquire; the lock is only released when
+ * all callers have released. Each release call is idempotent.
+ *
+ * @returns A release function. Call it exactly once per acquisition.
+ */
+export function acquireScrollLock(doc: Document = document): () => void {
+  lockCount++;
+
+  if (lockCount === 1) {
+    const body = doc.body;
+    const win = doc.defaultView ?? window;
+    const scrollY = win.scrollY || doc.documentElement.scrollTop;
+
+    savedState = {
+      originalOverflow: body.style.overflow,
+      originalPosition: body.style.position,
+      originalTop: body.style.top,
+      originalWidth: body.style.width,
+      scrollY,
+    };
+
+    body.style.overflow = "hidden";
+    body.style.position = "fixed";
+    body.style.top = `-${scrollY}px`;
+    body.style.width = "100%";
+  }
+
+  let released = false;
+
+  return () => {
+    if (released) return;
+    released = true;
+    lockCount = Math.max(0, lockCount - 1);
+
+    if (lockCount === 0 && savedState) {
+      const body = doc.body;
+      const win = doc.defaultView ?? window;
+      body.style.overflow = savedState.originalOverflow;
+      body.style.position = savedState.originalPosition;
+      body.style.top = savedState.originalTop;
+      body.style.width = savedState.originalWidth;
+      win.scrollTo(0, savedState.scrollY);
+      savedState = null;
+    }
+  };
+}

package/src/utils/theme.test.ts

@@ -218,6 +218,40 @@ describe('theme utils', () => {
     expect(cssVars['--persona-composer-shadow']).toBe('none');
   });
 
+  it('maps scroll-to-bottom component tokens to dedicated CSS variables', () => {
+    const theme = createTheme({
+      components: {
+        scrollToBottom: {
+          background: 'palette.colors.accent.500',
+          foreground: 'palette.colors.gray.50',
+          border: 'palette.colors.gray.900',
+          size: '40px',
+          borderRadius: 'palette.radius.full',
+          shadow: 'palette.shadows.md',
+          padding: '0.5rem 0.875rem',
+          gap: '0.5rem',
+          fontSize: '0.875rem',
+          iconSize: '14px',
+        },
+      },
+    } as any);
+
+    const cssVars = themeToCssVariables(theme);
+
+    expect(cssVars['--persona-scroll-to-bottom-bg']).toBe('#06b6d4');
+    expect(cssVars['--persona-scroll-to-bottom-fg']).toBe('#f9fafb');
+    expect(cssVars['--persona-scroll-to-bottom-border']).toBe('#111827');
+    expect(cssVars['--persona-scroll-to-bottom-size']).toBe('40px');
+    expect(cssVars['--persona-scroll-to-bottom-radius']).toBe('9999px');
+    expect(cssVars['--persona-scroll-to-bottom-shadow']).toBe(
+      '0 4px 6px -1px rgb(0 0 0 / 0.1), 0 2px 4px -2px rgb(0 0 0 / 0.1)'
+    );
+    expect(cssVars['--persona-scroll-to-bottom-padding']).toBe('0.5rem 0.875rem');
+    expect(cssVars['--persona-scroll-to-bottom-gap']).toBe('0.5rem');
+    expect(cssVars['--persona-scroll-to-bottom-font-size']).toBe('0.875rem');
+    expect(cssVars['--persona-scroll-to-bottom-icon-size']).toBe('14px');
+  });
+
   it('lets config.toolCall.shadow override theme tool bubble shadow on the root element', () => {
     const el = document.createElement('div');
     applyThemeVariables(el, {

package/src/utils/tokens.ts

@@ -312,6 +312,7 @@ export const DEFAULT_COMPONENTS: ComponentTokens = {
       border: 'palette.colors.gray.200',
       shadow: 'palette.shadows.sm',
     },
+    border: 'semantic.colors.border',
   },
   toolBubble: {
     shadow: 'palette.shadows.sm',
@@ -334,6 +335,28 @@ export const DEFAULT_COMPONENTS: ComponentTokens = {
     prose: {
       fontFamily: 'inherit',
     },
+    codeBlock: {
+      background: 'semantic.colors.container',
+      borderColor: 'semantic.colors.border',
+      textColor: 'inherit',
+    },
+    table: {
+      headerBackground: 'semantic.colors.container',
+      borderColor: 'semantic.colors.border',
+    },
+    hr: {
+      color: 'semantic.colors.divider',
+    },
+    blockquote: {
+      borderColor: 'palette.colors.gray.900',
+      background: 'transparent',
+      textColor: 'palette.colors.gray.500',
+    },
+  },
+  collapsibleWidget: {
+    container: 'palette.colors.gray.50',
+    surface: 'semantic.colors.surface',
+    border: 'semantic.colors.border',
   },
   voice: {
     recording: {
@@ -374,6 +397,18 @@ export const DEFAULT_COMPONENTS: ComponentTokens = {
       border: 'palette.colors.gray.200',
     },
   },
+  scrollToBottom: {
+    background: 'components.button.primary.background',
+    foreground: 'components.button.primary.foreground',
+    border: 'semantic.colors.primary',
+    size: '40px',
+    borderRadius: 'palette.radius.full',
+    shadow: 'palette.shadows.sm',
+    padding: '0.5rem 0.875rem',
+    gap: '0.5rem',
+    fontSize: '0.875rem',
+    iconSize: '14px',
+  },
   artifact: {
     pane: {
       background: 'semantic.colors.container',
@@ -656,6 +691,7 @@ export function themeToCssVariables(theme: PersonaTheme): Record<string, string>
   cssVars['--persona-radius-md'] = cssVars['--persona-palette-radius-md'] ?? '0.375rem';
   cssVars['--persona-radius-lg'] = cssVars['--persona-palette-radius-lg'] ?? '0.5rem';
   cssVars['--persona-radius-xl'] = cssVars['--persona-palette-radius-xl'] ?? '0.75rem';
+  cssVars['--persona-radius-full'] = cssVars['--persona-palette-radius-full'] ?? '9999px';
   cssVars['--persona-launcher-radius'] =
     cssVars['--persona-components-launcher-borderRadius'] ??
     cssVars['--persona-palette-radius-full'] ??
@@ -742,6 +778,42 @@ export function themeToCssVariables(theme: PersonaTheme): Record<string, string>
     cssVars['--persona-components-message-assistant-border'] ?? cssVars['--persona-border'];
   cssVars['--persona-message-assistant-shadow'] =
     cssVars['--persona-components-message-assistant-shadow'] ?? '0 1px 2px 0 rgb(0 0 0 / 0.05)';
+  cssVars['--persona-scroll-to-bottom-bg'] =
+    cssVars['--persona-components-scrollToBottom-background'] ??
+    cssVars['--persona-button-primary-bg'] ??
+    cssVars['--persona-accent'];
+  cssVars['--persona-scroll-to-bottom-fg'] =
+    cssVars['--persona-components-scrollToBottom-foreground'] ??
+    cssVars['--persona-button-primary-fg'] ??
+    cssVars['--persona-text-inverse'];
+  cssVars['--persona-scroll-to-bottom-border'] =
+    cssVars['--persona-components-scrollToBottom-border'] ??
+    cssVars['--persona-primary'];
+  cssVars['--persona-scroll-to-bottom-size'] =
+    cssVars['--persona-components-scrollToBottom-size'] ??
+    '40px';
+  cssVars['--persona-scroll-to-bottom-radius'] =
+    cssVars['--persona-components-scrollToBottom-borderRadius'] ??
+    cssVars['--persona-button-radius'] ??
+    cssVars['--persona-radius-full'] ??
+    '9999px';
+  cssVars['--persona-scroll-to-bottom-shadow'] =
+    cssVars['--persona-components-scrollToBottom-shadow'] ??
+    cssVars['--persona-palette-shadows-sm'] ??
+    '0 1px 2px 0 rgb(0 0 0 / 0.05)';
+  cssVars['--persona-scroll-to-bottom-padding'] =
+    cssVars['--persona-components-scrollToBottom-padding'] ??
+    '0.5rem 0.875rem';
+  cssVars['--persona-scroll-to-bottom-gap'] =
+    cssVars['--persona-components-scrollToBottom-gap'] ??
+    '0.5rem';
+  cssVars['--persona-scroll-to-bottom-font-size'] =
+    cssVars['--persona-components-scrollToBottom-fontSize'] ??
+    cssVars['--persona-palette-typography-fontSize-sm'] ??
+    '0.875rem';
+  cssVars['--persona-scroll-to-bottom-icon-size'] =
+    cssVars['--persona-components-scrollToBottom-iconSize'] ??
+    '14px';
 
   cssVars['--persona-tool-bubble-shadow'] =
     cssVars['--persona-components-toolBubble-shadow'] ?? '0 5px 15px rgba(15, 23, 42, 0.08)';
@@ -774,6 +846,46 @@ export function themeToCssVariables(theme: PersonaTheme): Record<string, string>
     cssVars['--persona-md-prose-font-family'] = mdProseFont;
   }
 
+  // Markdown code block
+  cssVars['--persona-md-code-block-bg'] =
+    cssVars['--persona-components-markdown-codeBlock-background'] ?? cssVars['--persona-container'];
+  cssVars['--persona-md-code-block-border-color'] =
+    cssVars['--persona-components-markdown-codeBlock-borderColor'] ?? cssVars['--persona-border'];
+  cssVars['--persona-md-code-block-text-color'] =
+    cssVars['--persona-components-markdown-codeBlock-textColor'] ?? 'inherit';
+
+  // Markdown table
+  cssVars['--persona-md-table-header-bg'] =
+    cssVars['--persona-components-markdown-table-headerBackground'] ?? cssVars['--persona-container'];
+  cssVars['--persona-md-table-border-color'] =
+    cssVars['--persona-components-markdown-table-borderColor'] ?? cssVars['--persona-border'];
+
+  // Markdown HR
+  cssVars['--persona-md-hr-color'] =
+    cssVars['--persona-components-markdown-hr-color'] ?? cssVars['--persona-divider'];
+
+  // Markdown blockquote
+  cssVars['--persona-md-blockquote-border-color'] =
+    cssVars['--persona-components-markdown-blockquote-borderColor'] ??
+    cssVars['--persona-palette-colors-gray-900'];
+  cssVars['--persona-md-blockquote-bg'] =
+    cssVars['--persona-components-markdown-blockquote-background'] ?? 'transparent';
+  cssVars['--persona-md-blockquote-text-color'] =
+    cssVars['--persona-components-markdown-blockquote-textColor'] ??
+    cssVars['--persona-palette-colors-gray-500'];
+
+  // Collapsible widget chrome (tool/reasoning/approval bubbles)
+  cssVars['--cw-container'] =
+    cssVars['--persona-components-collapsibleWidget-container'] ?? cssVars['--persona-surface'];
+  cssVars['--cw-surface'] =
+    cssVars['--persona-components-collapsibleWidget-surface'] ?? cssVars['--persona-surface'];
+  cssVars['--cw-border'] =
+    cssVars['--persona-components-collapsibleWidget-border'] ?? cssVars['--persona-border'];
+
+  // Message border
+  cssVars['--persona-message-border'] =
+    cssVars['--persona-components-message-border'] ?? cssVars['--persona-border'];
+
   // Icon button tokens
   const components = theme.components;
   const iconBtn = components?.iconButton;