@runtypelabs/persona 4.17.0 → 4.18.0

package/src/utils/__fixtures__/client-conversation-history-wire.json

@@ -0,0 +1,108 @@
+{
+  "_readme": "Generated by apps/api/tests/client-conversation-history-handlers.test.ts in runtypelabs/core. Do not hand-edit; regenerate with UPDATE_HISTORY_WIRE_FIXTURE=1. Pins the /v1/client/conversations wire shape a Persona message mapper must handle: divergent display vs model content, absent vs deliberately empty projections, withheld model-only content (displayAvailable false), media parts, and a terminal assistant turn finalized through the display-projections route. conversationRevision is normalized because it is a freshly minted opaque token.",
+  "list": [
+    {
+      "id": "record_fixture_0000000000",
+      "title": "record_fixture_0000000000",
+      "targetId": "flow_fixture_000000000000",
+      "flowId": "flow_fixture_000000000000",
+      "preview": "It is in transit and arrives Thursday.",
+      "messageCount": 9,
+      "createdAt": "2026-01-01T00:00:00.000Z",
+      "updatedAt": "2026-02-01T00:00:00.000Z"
+    }
+  ],
+  "detail": {
+    "id": "record_fixture_0000000000",
+    "title": "record_fixture_0000000000",
+    "targetId": "flow_fixture_000000000000",
+    "flowId": "flow_fixture_000000000000",
+    "preview": "It is in transit and arrives Thursday.",
+    "messageCount": 9,
+    "createdAt": "2026-01-01T00:00:00.000Z",
+    "updatedAt": "2026-02-01T00:00:00.000Z",
+    "conversationRevision": "<opaque>",
+    "messages": [
+      {
+        "id": "msg_string",
+        "role": "user",
+        "content": "Where is my order?",
+        "displayAvailable": true,
+        "timestamp": "2026-02-01T00:00:00.000Z"
+      },
+      {
+        "id": "msg_divergent",
+        "role": "assistant",
+        "content": "{\"directive\":\"order_card\",\"orderId\":\"A-1\"}",
+        "displayContent": "Order A-1 is on its way.",
+        "displayAvailable": true,
+        "timestamp": "2026-02-01T00:00:01.000Z"
+      },
+      {
+        "id": "msg_empty_projection",
+        "role": "assistant",
+        "content": "{\"directive\":\"open_modal\"}",
+        "displayContent": "",
+        "displayAvailable": true,
+        "timestamp": "2026-02-01T00:00:02.000Z"
+      },
+      {
+        "id": "msg_hidden_llm_content",
+        "role": "assistant",
+        "displayAvailable": false,
+        "timestamp": "2026-02-01T00:00:03.000Z"
+      },
+      {
+        "id": "msg_raw_directive",
+        "role": "assistant",
+        "displayAvailable": false,
+        "timestamp": "2026-02-01T00:00:04.000Z"
+      },
+      {
+        "id": "msg_image",
+        "role": "user",
+        "content": [
+          {
+            "text": "Looks like this:",
+            "type": "text"
+          },
+          {
+            "type": "image",
+            "image": "data:image/png;base64,AAAA"
+          }
+        ],
+        "displayAvailable": true,
+        "timestamp": "2026-02-01T00:00:05.000Z"
+      },
+      {
+        "id": "msg_file",
+        "role": "user",
+        "content": [
+          {
+            "data": "ZmFrZQ==",
+            "type": "file",
+            "filename": "receipt.pdf",
+            "mimeType": "application/pdf"
+          }
+        ],
+        "displayAvailable": true,
+        "timestamp": "2026-02-01T00:00:06.000Z"
+      },
+      {
+        "id": "msg_absent_content",
+        "role": "assistant",
+        "displayAvailable": false,
+        "timestamp": "2026-02-01T00:00:07.000Z"
+      },
+      {
+        "id": "msg_terminal_finalized",
+        "role": "assistant",
+        "content": "{\"tool\":\"track\",\"status\":\"in_transit\"}",
+        "displayContent": "It is in transit and arrives Thursday.",
+        "displayAvailable": true,
+        "timestamp": "2026-02-01T00:00:08.000Z"
+      }
+    ],
+    "nextMessageCursor": null
+  }
+}

package/src/utils/artifact-file.ts

@@ -115,3 +115,18 @@ export function downloadInfoFor(record: ArtifactDownloadSource): {
   const title = record.title || "artifact";
   return { filename: `${title}.md`, mime: "text/markdown", content: raw };
 }
+
+/** Save `content` as a browser download via a transient blob anchor. */
+export function triggerArtifactDownload(info: {
+  filename: string;
+  mime: string;
+  content: string;
+}): void {
+  const blob = new Blob([info.content], { type: info.mime });
+  const url = URL.createObjectURL(blob);
+  const a = document.createElement("a");
+  a.href = url;
+  a.download = info.filename;
+  a.click();
+  URL.revokeObjectURL(url);
+}

package/src/utils/artifact-gate.test.ts

@@ -371,6 +371,7 @@ describe("applyArtifactLayoutCssVars", () => {
               documentToolbarIconColor: "#60a5fa",
               documentToolbarToggleActiveBackground: "#262626",
               documentToolbarToggleActiveBorderColor: "#444444",
+              documentToolbarToggleActiveColor: "#e5e5e5",
             },
           },
         },
@@ -385,5 +386,8 @@ describe("applyArtifactLayoutCssVars", () => {
     expect(mount.style.getPropertyValue("--persona-artifact-doc-toggle-active-border").trim()).toBe(
       "#444444"
     );
+    expect(mount.style.getPropertyValue("--persona-artifact-doc-toggle-active-color").trim()).toBe(
+      "#e5e5e5"
+    );
   });
 });

package/src/utils/artifact-gate.ts

@@ -107,23 +107,19 @@ export function applyArtifactLayoutCssVars(mount: HTMLElement, config: AgentWidg
     mount.style.removeProperty("--persona-artifact-pane-padding");
   }
 
-  const iconColor = l?.documentToolbarIconColor?.trim();
-  if (iconColor) {
-    mount.style.setProperty("--persona-artifact-doc-toolbar-icon-color", iconColor);
-  } else {
-    mount.style.removeProperty("--persona-artifact-doc-toolbar-icon-color");
-  }
-  const toggleBg = l?.documentToolbarToggleActiveBackground?.trim();
-  if (toggleBg) {
-    mount.style.setProperty("--persona-artifact-doc-toggle-active-bg", toggleBg);
-  } else {
-    mount.style.removeProperty("--persona-artifact-doc-toggle-active-bg");
-  }
-  const toggleBorder = l?.documentToolbarToggleActiveBorderColor?.trim();
-  if (toggleBorder) {
-    mount.style.setProperty("--persona-artifact-doc-toggle-active-border", toggleBorder);
-  } else {
-    mount.style.removeProperty("--persona-artifact-doc-toggle-active-border");
+  const docToolbarVars: Array<[string | undefined, string]> = [
+    [l?.documentToolbarIconColor, "--persona-artifact-doc-toolbar-icon-color"],
+    [l?.documentToolbarToggleActiveBackground, "--persona-artifact-doc-toggle-active-bg"],
+    [l?.documentToolbarToggleActiveBorderColor, "--persona-artifact-doc-toggle-active-border"],
+    [l?.documentToolbarToggleActiveColor, "--persona-artifact-doc-toggle-active-color"],
+  ];
+  for (const [raw, name] of docToolbarVars) {
+    const value = raw?.trim();
+    if (value) {
+      mount.style.setProperty(name, value);
+    } else {
+      mount.style.removeProperty(name);
+    }
   }
 
   applyArtifactPaneBorderTheme(mount, config);

package/src/utils/artifact-resize.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect, it } from "vitest";
 import {
   ARTIFACT_RESIZE_CHAT_MIN_PX,
+  ARTIFACT_RESIZE_RAILED_TRANSCRIPT_MIN_PX,
   clampArtifactPaneWidth,
   maxArtifactWidthFromSplit,
   parseArtifactResizeMaxPxOptional,
@@ -61,4 +62,31 @@ describe("resolveArtifactPaneWidthPx", () => {
     const w = resolveArtifactPaneWidthPx(900, 1200, 8, 6, "200px", "320px");
     expect(w).toBeLessThanOrEqual(320);
   });
+
+  it("defaults the chat minimum to the flat reserve", () => {
+    const explicit = resolveArtifactPaneWidthPx(
+      2000,
+      1200,
+      8,
+      6,
+      "200px",
+      undefined,
+      ARTIFACT_RESIZE_CHAT_MIN_PX
+    );
+    expect(resolveArtifactPaneWidthPx(2000, 1200, 8, 6, "200px")).toBe(explicit);
+    expect(explicit).toBe(1200 - ARTIFACT_RESIZE_CHAT_MIN_PX - 16 - 6);
+  });
+
+  it("shrinks the max by a larger chat minimum (docked rail + transcript)", () => {
+    const railed = 260 + ARTIFACT_RESIZE_RAILED_TRANSCRIPT_MIN_PX;
+    const w = resolveArtifactPaneWidthPx(2000, 1200, 8, 6, "200px", undefined, railed);
+    expect(w).toBe(1200 - railed - 16 - 6);
+    expect(w).toBeLessThan(resolveArtifactPaneWidthPx(2000, 1200, 8, 6, "200px"));
+  });
+
+  it("keeps min over max when the chat minimum eats the row", () => {
+    // 1200 - 1100 - gaps - handle < the 200px pane min: min still wins.
+    const w = resolveArtifactPaneWidthPx(2000, 1200, 8, 6, "200px", undefined, 1100);
+    expect(w).toBe(200);
+  });
 });

package/src/utils/artifact-resize.ts

@@ -1,6 +1,12 @@
 /** Minimum width (px) reserved for the chat column while resizing the artifact pane. */
 export const ARTIFACT_RESIZE_CHAT_MIN_PX = 200;
 
+/**
+ * Minimum transcript width (px) preserved beside a docked history rail while
+ * resizing the artifact pane. Added to the rail's own rendered width.
+ */
+export const ARTIFACT_RESIZE_RAILED_TRANSCRIPT_MIN_PX = 360;
+
 /** Default minimum width (px) for the artifact column when `resizableMinWidth` is unset. */
 export const ARTIFACT_RESIZE_PANE_MIN_DEFAULT_PX = 200;
 
@@ -54,10 +60,11 @@ export function resolveArtifactPaneWidthPx(
   gapPx: number,
   handleWidthPx: number,
   resizableMinWidth?: string,
-  resizableMaxWidth?: string
+  resizableMaxWidth?: string,
+  chatMinPx: number = ARTIFACT_RESIZE_CHAT_MIN_PX
 ): number {
   const minPx = parseArtifactResizePx(resizableMinWidth, ARTIFACT_RESIZE_PANE_MIN_DEFAULT_PX);
-  let maxPx = maxArtifactWidthFromSplit(splitWidthPx, gapPx, handleWidthPx, ARTIFACT_RESIZE_CHAT_MIN_PX);
+  let maxPx = maxArtifactWidthFromSplit(splitWidthPx, gapPx, handleWidthPx, chatMinPx);
   maxPx = Math.max(minPx, maxPx);
   const cap = parseArtifactResizeMaxPxOptional(resizableMaxWidth);
   if (cap !== null) {

package/src/utils/buttons.ts

@@ -1,6 +1,10 @@
 import { createElement } from "./dom";
 import { renderLucideIcon } from "./icons";
-import { createDropdownMenu, type DropdownMenuItem } from "./dropdown";
+import {
+  createDropdownMenu,
+  type DropdownMenuHandle,
+  type DropdownMenuItem,
+} from "./dropdown";
 
 // ---------------------------------------------------------------------------
 // createIconButton
@@ -240,6 +244,182 @@ export function createToggleGroup(options: CreateToggleGroupOptions): ToggleGrou
   return { element: wrapper, setSelected };
 }
 
+// ---------------------------------------------------------------------------
+// createSplitButton
+// ---------------------------------------------------------------------------
+
+/** Options for {@link createSplitButton}. */
+export interface CreateSplitButtonOptions {
+  /** Primary action text (always the accessible name; hidden visually with `iconOnly`). */
+  label: string;
+  /** Lucide icon for the primary half. */
+  icon?: string;
+  /** Primary icon size in pixels. Default: 14. */
+  iconSize?: number;
+  /** Render the primary half icon-only. */
+  iconOnly?: boolean;
+  /** Menu items behind the chevron half. */
+  menuItems: DropdownMenuItem[];
+  /** Called when a menu item is selected. */
+  onSelect: (id: string) => void;
+  /** Click handler for the primary half. */
+  onPrimary?: (e: MouseEvent) => void;
+  /** Menu alignment relative to the whole control. Default: "bottom-left". */
+  position?: "bottom-left" | "bottom-right";
+  /**
+   * Portal target for the menu (escapes `overflow: hidden` containers). A
+   * thunk is resolved when the menu is first built, so it may depend on the
+   * control being in the DOM.
+   */
+  portal?: HTMLElement | (() => HTMLElement | null | undefined);
+  /** Accessible label of the chevron half. Default: "More options". */
+  chevronLabel?: string;
+  /** Chevron icon size in pixels. Default: 14. */
+  chevronIconSize?: number;
+  /** Extra CSS class(es) on the wrapper. */
+  className?: string;
+  /** Extra CSS class(es) on the primary button. */
+  primaryClassName?: string;
+  /** Extra CSS class(es) on the chevron button. */
+  chevronClassName?: string;
+}
+
+/** Handle returned by {@link createSplitButton}. */
+export interface SplitButtonHandle {
+  /** The bordered wrapper holding both halves. */
+  element: HTMLElement;
+  /** The primary-action half. */
+  primaryButton: HTMLButtonElement;
+  /** The menu-trigger half. */
+  chevronButton: HTMLButtonElement;
+  /** Open the menu. */
+  openMenu: () => void;
+  /** Close the menu. */
+  closeMenu: () => void;
+  /** Toggle the menu. */
+  toggleMenu: () => void;
+  /** Remove from DOM and clean up. */
+  destroy: () => void;
+}
+
+/**
+ * Creates a split button: one bordered control holding two separately
+ * invocable halves — a primary action button and an icon-only chevron that
+ * opens a dropdown menu — divided by an internal hairline. This is the
+ * Primer/Fluent/Material split-button anatomy; for a single button whose whole
+ * surface opens the menu, use {@link createComboButton} instead.
+ *
+ * Both halves are real `button`s (two tab stops). The chevron carries its own
+ * accessible label plus `aria-haspopup`/`aria-expanded`, kept accurate across
+ * outside-click dismissal.
+ *
+ * ```ts
+ * import { createSplitButton } from "@runtypelabs/persona";
+ *
+ * const split = createSplitButton({
+ *   label: "Copy",
+ *   icon: "copy",
+ *   menuItems: [{ id: "download", label: "Download" }],
+ *   onPrimary: () => copyToClipboard(),
+ *   onSelect: (id) => handleMenuAction(id),
+ * });
+ * toolbar.appendChild(split.element);
+ * ```
+ */
+export function createSplitButton(options: CreateSplitButtonOptions): SplitButtonHandle {
+  const {
+    label,
+    icon,
+    iconSize,
+    iconOnly,
+    menuItems,
+    onSelect,
+    onPrimary,
+    position = "bottom-left",
+    portal,
+    chevronLabel = "More options",
+    chevronIconSize,
+    className,
+    primaryClassName,
+    chevronClassName,
+  } = options;
+
+  const wrapper = createElement(
+    "div",
+    "persona-split-btn" + (className ? " " + className : ""),
+  );
+
+  const primaryBase = {
+    label,
+    className:
+      "persona-split-btn-primary" + (primaryClassName ? " " + primaryClassName : ""),
+    onClick: onPrimary,
+  };
+  const primaryButton =
+    iconOnly && icon
+      ? createIconButton({ ...primaryBase, icon, size: iconSize ?? 14 })
+      : createLabelButton({ ...primaryBase, icon, iconSize: iconSize ?? 14 });
+
+  const chevronButton = createIconButton({
+    icon: "chevron-down",
+    label: chevronLabel,
+    size: chevronIconSize ?? 14,
+    className:
+      "persona-split-btn-chevron" + (chevronClassName ? " " + chevronClassName : ""),
+    aria: { "aria-haspopup": "true", "aria-expanded": "false" },
+  });
+
+  wrapper.append(primaryButton, chevronButton);
+
+  let dropdown: DropdownMenuHandle | null = null;
+  const ensureMenu = (): DropdownMenuHandle => {
+    if (dropdown) return dropdown;
+    const target = (typeof portal === "function" ? portal() : portal) ?? undefined;
+    dropdown = createDropdownMenu({
+      items: menuItems,
+      onSelect,
+      anchor: wrapper,
+      position,
+      portal: target,
+      onOpenChange: (open) => {
+        chevronButton.setAttribute("aria-expanded", open ? "true" : "false");
+      },
+    });
+    // Non-portaled menus position absolutely inside the anchor.
+    if (!target) wrapper.appendChild(dropdown.element);
+    return dropdown;
+  };
+
+  // Build the (hidden) menu eagerly so it is queryable before first open, but
+  // wait a frame when the control is still detached: a portal thunk may need
+  // the mounted DOM to resolve its target.
+  if (wrapper.isConnected) {
+    ensureMenu();
+  } else {
+    requestAnimationFrame(() => {
+      if (!dropdown) ensureMenu();
+    });
+  }
+
+  chevronButton.addEventListener("click", (e) => {
+    e.stopPropagation();
+    ensureMenu().toggle();
+  });
+
+  return {
+    element: wrapper,
+    primaryButton,
+    chevronButton,
+    openMenu: () => ensureMenu().show(),
+    closeMenu: () => dropdown?.hide(),
+    toggleMenu: () => ensureMenu().toggle(),
+    destroy: () => {
+      dropdown?.destroy();
+      wrapper.remove();
+    },
+  };
+}
+
 // ---------------------------------------------------------------------------
 // createComboButton
 // ---------------------------------------------------------------------------
@@ -380,9 +560,16 @@ export function createComboButton(options: CreateComboButtonOptions): ComboButto
     wrapper.appendChild(dropdown.element);
   }
 
+  // A shell may lock the menu while it has nothing to act on (e.g. no active
+  // conversation behind a conversation-title menu); locked, the combo reads
+  // as a plain title.
+  const locked = (): boolean =>
+    wrapper.getAttribute("data-persona-menu-locked") === "true";
+
   // Click toggles dropdown
   wrapper.addEventListener("click", (e) => {
     e.stopPropagation();
+    if (locked()) return;
     const isOpen = !dropdown.element.classList.contains("persona-hidden");
     wrapper.setAttribute("aria-expanded", isOpen ? "false" : "true");
     dropdown.toggle();

package/src/utils/config-merge.test.ts

@@ -64,6 +64,97 @@ describe("mergeConfigUpdate", () => {
     expect(next.onSessionInit).toBe(second);
   });
 
+  it("replaces history identity/persistence callbacks wholesale", () => {
+    const firstProof = vi.fn();
+    const secondProof = vi.fn();
+    const firstGet = vi.fn();
+    const secondGet = vi.fn();
+    const firstSet = vi.fn();
+    const secondSet = vi.fn();
+    const firstClear = vi.fn();
+    const secondClear = vi.fn();
+    const firstClearSession = vi.fn();
+    const secondClearSession = vi.fn();
+
+    const prev = base({
+      getIdentityProof: firstProof,
+      getStoredConversationId: firstGet,
+      setStoredConversationId: firstSet,
+      clearStoredConversationId: firstClear,
+      clearStoredSessionId: firstClearSession,
+    });
+    const next = mergeConfigUpdate(prev, {
+      getIdentityProof: secondProof,
+      getStoredConversationId: secondGet,
+      setStoredConversationId: secondSet,
+      clearStoredConversationId: secondClear,
+      clearStoredSessionId: secondClearSession,
+    });
+
+    expect(next.getIdentityProof).toBe(secondProof);
+    expect(next.getStoredConversationId).toBe(secondGet);
+    expect(next.setStoredConversationId).toBe(secondSet);
+    expect(next.clearStoredConversationId).toBe(secondClear);
+    expect(next.clearStoredSessionId).toBe(secondClearSession);
+  });
+
+  it("preserves history identity/persistence callbacks absent from the patch", () => {
+    const getProof = vi.fn();
+    const getId = vi.fn();
+    const setId = vi.fn();
+    const clearId = vi.fn();
+    const clearSession = vi.fn();
+
+    const prev = base({
+      getIdentityProof: getProof,
+      getStoredConversationId: getId,
+      setStoredConversationId: setId,
+      clearStoredConversationId: clearId,
+      clearStoredSessionId: clearSession,
+    });
+    const next = mergeConfigUpdate(prev, { launcher: { title: "New" } });
+
+    expect(next.getIdentityProof).toBe(getProof);
+    expect(next.getStoredConversationId).toBe(getId);
+    expect(next.setStoredConversationId).toBe(setId);
+    expect(next.clearStoredConversationId).toBe(clearId);
+    expect(next.clearStoredSessionId).toBe(clearSession);
+  });
+
+  it("keeps features.history defaults when the host sets only enabled", () => {
+    const prev = base();
+    expect(prev.features?.history).toMatchObject({
+      enabled: false,
+      presentation: "panel",
+      showScopeStatus: true,
+    });
+
+    // Same guarantee through the defaults merge itself.
+    const withDefaults = mergeWithDefaults({ features: { history: { enabled: true } } });
+    expect(withDefaults.features?.history).toMatchObject({
+      enabled: true,
+      presentation: "panel",
+      showScopeStatus: true,
+    });
+
+    const next = mergeConfigUpdate(prev, { features: { history: { enabled: true } } });
+    expect(next.features?.history?.enabled).toBe(true);
+    expect(next.features?.history?.presentation).toBe("panel");
+    expect(next.features?.history?.showScopeStatus).toBe(true);
+    // Sibling feature blocks survive the history patch.
+    expect(next.features?.askUserQuestion?.enabled).toBe(true);
+  });
+
+  it("merges features.history.copy without dropping sibling copy overrides", () => {
+    const prev = base({ features: { history: { copy: { viewTitle: "Threads" } } } });
+    const next = mergeConfigUpdate(prev, {
+      features: { history: { copy: { emptyTitle: "Nothing yet" } } },
+    });
+    expect(next.features?.history?.copy?.viewTitle).toBe("Threads");
+    expect(next.features?.history?.copy?.emptyTitle).toBe("Nothing yet");
+    expect(next.features?.history?.presentation).toBe("panel");
+  });
+
   it("guards boolean|object unions in both directions", () => {
     const objFirst = base({ approval: { backgroundColor: "#ffffff" } });
     const toScalar = mergeConfigUpdate(objFirst, { approval: false });

package/src/utils/dropdown.ts

@@ -28,6 +28,11 @@ export interface CreateDropdownOptions {
    * Use this to escape `overflow: hidden` containers.
    */
   portal?: HTMLElement;
+  /**
+   * Fired on every open/close transition, including outside-click dismissal.
+   * Use to keep a trigger's `aria-expanded` accurate.
+   */
+  onOpenChange?: (open: boolean) => void;
 }
 
 export interface DropdownMenuHandle {
@@ -65,7 +70,7 @@ export interface DropdownMenuHandle {
  * ```
  */
 export function createDropdownMenu(options: CreateDropdownOptions): DropdownMenuHandle {
-  const { items, onSelect, anchor, position = 'bottom-left', portal } = options;
+  const { items, onSelect, anchor, position = 'bottom-left', portal, onOpenChange } = options;
 
   const menu = createElement("div", "persona-dropdown-menu persona-hidden");
   menu.setAttribute("role", "menu");
@@ -137,8 +142,10 @@ export function createDropdownMenu(options: CreateDropdownOptions): DropdownMenu
   }
 
   function show() {
+    const wasHidden = menu.classList.contains("persona-hidden");
     reposition();
     menu.classList.remove("persona-hidden");
+    if (wasHidden) onOpenChange?.(true);
     // Defer click-outside listener to avoid catching the triggering click
     requestAnimationFrame(() => {
       const handler = (e: MouseEvent) => {
@@ -152,9 +159,11 @@ export function createDropdownMenu(options: CreateDropdownOptions): DropdownMenu
   }
 
   function hide() {
+    const wasOpen = !menu.classList.contains("persona-hidden");
     menu.classList.add("persona-hidden");
     cleanupClickOutside?.();
     cleanupClickOutside = null;
+    if (wasOpen) onOpenChange?.(false);
   }
 
   function toggle() {