@runtypelabs/persona 4.19.0 → 4.21.0

package/src/types/theme.ts

@@ -663,21 +663,41 @@ export interface ComposerSegmentedTokens {
 }
 
 /**
- * Model picker popover (`composer.modelPicker.presentation: "popover"`).
+ * Model picker chrome (`composer.models`).
+ *
+ * The surface keys (`background`, `hoverBackground`, `borderColor`,
+ * `borderRadius`, `labelColor`) style the CLOSED control, so the native
+ * `<select>` and the `presentation: "popover"` trigger share one vocabulary.
+ * The `menu*`, `rowHoverBackground`, and `descriptionColor` keys style the
+ * popover panel and are inert under the native select, as is `suffixColor`,
+ * which a `<select>` cannot carry either.
  *
  * Every key is optional and unset ones emit nothing: the stylesheet's `var()`
  * fallbacks own the default look, which derives from the surface and ghost
- * button tokens. Inert under the native `<select>` presentation, except
- * `suffixColor`, which the native control cannot carry either.
+ * button tokens.
  */
 export interface ComposerModelPickerTokens {
+  /** Closed control fill. @default the ghost button fill (transparent) */
+  background?: TokenReference<'color'>;
+  /** Closed control fill under hover. @default the ghost hover wash */
+  hoverBackground?: TokenReference<'color'>;
+  /**
+   * Closed control outline, drawn as a 1px inset ring so setting it never
+   * resizes the control. @default none
+   */
+  borderColor?: TokenReference<'color'>;
+  /** Closed control corner radius. @default the ghost button radius */
+  borderRadius?: TokenReference<'radius'>;
   /** Panel fill behind the rows. @default semantic.colors.surface */
   menuBackground?: TokenReference<'color'>;
   /** Panel corner radius. @default palette.radius.lg */
   menuBorderRadius?: TokenReference<'radius'>;
   /** Row fill under hover and the focused option. @default the ghost hover wash */
   rowHoverBackground?: TokenReference<'color'>;
-  /** Row label and closed-control label color. @default inherited text */
+  /**
+   * Row label color, plus the closed control's text and chevron in both
+   * presentations. @default the ghost button foreground
+   */
   labelColor?: TokenReference<'color'>;
   /** Second line under a row label. @default semantic.colors.textMuted */
   descriptionColor?: TokenReference<'color'>;
@@ -685,6 +705,26 @@ export interface ComposerModelPickerTokens {
   suffixColor?: TokenReference<'color'>;
 }
 
+/**
+ * Composer overflow `+` menu panel (`composer.actionOverflow`).
+ *
+ * Every key is optional and unset ones emit nothing: the stylesheet's `var()`
+ * fallbacks own the default look. The panel is portaled outside the themed
+ * mount, so the menu forwards the configured values onto it when it opens.
+ */
+export interface ComposerOverflowMenuTokens {
+  /** Panel fill behind the rows. @default semantic.colors.surface */
+  background?: TokenReference<'color'>;
+  /** Panel border color. @default semantic.colors.border */
+  borderColor?: TokenReference<'color'>;
+  /** Panel corner radius. @default palette.radius.lg */
+  borderRadius?: TokenReference<'radius'>;
+  /** Row text and glyph color. @default semantic.colors.text */
+  foreground?: TokenReference<'color'>;
+  /** Panel elevation (raw CSS box-shadow, `none` allowed). @default palette.shadows.md */
+  shadow?: string;
+}
+
 /** Composer (message input) chrome. */
 export interface ComposerChromeTokens {
   /** Box-shadow on the composer form (raw CSS, e.g. `none`). */
@@ -719,8 +759,10 @@ export interface ComposerChromeTokens {
   overlayBand?: string;
   /** Segmented mode-group track. */
   segmented?: ComposerSegmentedTokens;
-  /** Model picker popover chrome. */
+  /** Model picker chrome (closed control plus popover panel). */
   modelPicker?: ComposerModelPickerTokens;
+  /** Overflow `+` menu panel chrome. */
+  overflowMenu?: ComposerOverflowMenuTokens;
 }
 
 /**

package/src/types.ts

@@ -908,6 +908,22 @@ export type AgentWidgetWebMcpConfig = {
    * `window.confirm` fallback only applies when no widget UI is attached.
    */
   onConfirm?: WebMcpConfirmHandler;
+  /**
+   * How the widget runs the `webmcp:*` calls of ONE turn when the model emits
+   * several at once.
+   *
+   * - `'parallel'` (default): every call executes concurrently and a gated
+   *   sibling's approval never blocks another's execution. Right for
+   *   independent, order-insensitive tools (catalog lookups, add-to-cart).
+   * - `'sequential'`: calls execute one at a time, in the order the model
+   *   emitted them; the next starts only after the previous one settles
+   *   (including its approval bubble). Use this when the page tools share
+   *   mutable state that concurrent execution would interleave, e.g. a
+   *   canvas where every stroke selects a color/tool before drawing.
+   *
+   * Either way, all outputs still return to the server in a single `/resume`.
+   */
+  execution?: 'parallel' | 'sequential';
 };
 
 /**
@@ -4007,6 +4023,16 @@ export type ComposerActionPlacement = "start" | "end";
  */
 export type ComposerActionPresentation = "bar" | "overflow" | "auto";
 
+/**
+ * When a composer action is mounted, as a function of the draft.
+ *
+ * - `"always"` (default): the control is always mounted.
+ * - `"when-empty"`: hidden as soon as the draft holds text or an attachment,
+ *   and while a response streams.
+ * - `"when-text"`: the inverse, on the same draft state the send control reads.
+ */
+export type ComposerActionVisibility = "always" | "when-empty" | "when-text";
+
 /**
  * Fields shared by every composer action.
  *
@@ -4022,6 +4048,13 @@ export type ComposerActionBase = {
   presentation?: ComposerActionPresentation;
   order?: number;
   visible?: boolean | ((state: Readonly<ComposerState>) => boolean);
+  /**
+   * Draft-driven visibility, on the same state `sendButton.visibility` reads.
+   * Hidden removes the control from layout and tab order. Combined with
+   * `visible`: both must pass.
+   * @default "always"
+   */
+  visibility?: ComposerActionVisibility;
   disabled?: boolean | ((state: Readonly<ComposerState>) => boolean);
   /** Disable while a response streams, through the composer's own mechanism. */
   disableWhenStreaming?: boolean;
@@ -4180,6 +4213,16 @@ export type ComposerMode = {
  */
 export type ComposerModeGroupPresentation = "buttons" | "segmented";
 
+/**
+ * Whether a group's active modes also render as removable chips.
+ *
+ * - `"auto"` (default): one chip per active mode, except under `"segmented"`
+ *   presentation, where the track already shows the state.
+ * - `"hidden"`: no chips for this group under any presentation. The pressed bar
+ *   button carries the state, and deselection stays on the button.
+ */
+export type ComposerModeChipVisibility = "auto" | "hidden";
+
 /**
  * Selection policy for a set of modes. `"single"` deselects siblings when one
  * is chosen; `"multiple"` toggles independently.
@@ -4189,6 +4232,12 @@ export type ComposerModeGroup = {
   selection: "single" | "multiple";
   /** @default "buttons" */
   presentation?: ComposerModeGroupPresentation;
+  /**
+   * Chip row policy for this group's active modes. The chip row itself is
+   * derived from its children, so a group with no other chips leaves no gap.
+   * @default "auto"
+   */
+  chipVisibility?: ComposerModeChipVisibility;
   /**
    * Accessible name for a segmented track. With it the track is a labelled
    * `role="group"`; without it the segments stand on their own names.
@@ -5641,6 +5690,8 @@ export type ClientSession = {
   targetId?: string;
   /** Opaque change token; differs whenever the conversation transcript mutated. */
   conversationRevision?: string;
+  /** Server-negotiated durable reconnect support for this client-token session. */
+  durableRecovery?: { enabled: boolean };
   /** Visitor grant backing history. `token` appears only at mint. */
   visitor?: ClientVisitorGrant;
   /** Configuration from the server */
@@ -5681,6 +5732,8 @@ export type ClientInitResponse = {
   conversationId?: string;
   targetId?: string;
   conversationRevision?: string;
+  /** Present on servers that understand the durable-recovery negotiation. */
+  durableRecovery?: { enabled: boolean };
   visitor?: ClientVisitorGrant;
   config: {
     welcomeMessage: string | null;
@@ -5772,6 +5825,16 @@ export interface WidgetHistoryInternals {
   /** Persist the revision beside the active conversation id (internal only). */
   setStoredConversationRevision?: (revision: string | null) => void;
   getStoredConversationRevision?: () => string | null;
+  /** Internal client-token durable resume handle, persisted with widget state. */
+  setStoredResumableHandle?: (
+    handle: { executionId: string; after: string } | null
+  ) => void;
+  getStoredResumableHandle?: () => {
+    executionId: string;
+    after: string;
+  } | null;
+  /** True only while Persona owns a persisted client-token recovery attempt. */
+  shouldResumeDurableConversation?: () => boolean;
   /** "Show earlier messages" cursor for the persisted transcript. */
   setStoredMessageCursor?: (cursor: string | null) => void;
   getStoredMessageCursor?: () => string | null;

package/src/ui.composer-action-visibility.test.ts

@@ -0,0 +1,202 @@
+// @vitest-environment jsdom
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { createAgentExperience } from "./ui";
+import type { ComposerAction } from "./types";
+
+const mounts: HTMLElement[] = [];
+const controllers: ReturnType<typeof createAgentExperience>[] = [];
+
+const makeController = (config: Record<string, unknown> = {}) => {
+  const mount = document.createElement("div");
+  document.body.appendChild(mount);
+  mounts.push(mount);
+  const controller = createAgentExperience(mount, {
+    apiUrl: "https://api.example.com/chat",
+    launcher: { enabled: false },
+    persistState: false,
+    suggestionChips: [],
+    ...config,
+  } as unknown as Parameters<typeof createAgentExperience>[1]);
+  controllers.push(controller);
+  return { mount, controller };
+};
+
+/** The store coalesces on a microtask, so state-driven syncs need a turn. */
+const flush = async (times = 4) => {
+  for (let i = 0; i < times; i += 1) {
+    // eslint-disable-next-line no-await-in-loop
+    await Promise.resolve();
+  }
+};
+
+const actionEl = (mount: HTMLElement, id: string) =>
+  mount.querySelector<HTMLElement>(`[data-persona-composer-action="${id}"]`);
+
+const typeInto = (mount: HTMLElement, value: string): void => {
+  const textarea = mount.querySelector<HTMLTextAreaElement>(
+    "[data-persona-composer-input]"
+  )!;
+  textarea.value = value;
+  textarea.dispatchEvent(new Event("input", { bubbles: true }));
+};
+
+const voiceAction = (patch: Partial<ComposerAction> = {}): ComposerAction =>
+  ({
+    id: "voice-mode",
+    placement: "end",
+    label: "Voice mode",
+    iconName: "mic",
+    onSelect: () => {},
+    ...patch,
+  }) as ComposerAction;
+
+describe("ComposerAction.visibility", () => {
+  beforeEach(() => {
+    window.scrollTo = vi.fn();
+  });
+
+  afterEach(() => {
+    controllers.splice(0).forEach((controller) => {
+      try {
+        controller.destroy();
+      } catch {
+        /* already destroyed in the test */
+      }
+    });
+    mounts.splice(0).forEach((mount) => mount.remove());
+    document.body.innerHTML = "";
+    window.localStorage.clear();
+    vi.restoreAllMocks();
+  });
+
+  it("mounts the control on every draft state under the default", async () => {
+    const { mount } = makeController({
+      composer: { actions: [voiceAction()] },
+    });
+
+    expect(actionEl(mount, "voice-mode")).toBeTruthy();
+    typeInto(mount, "Hello");
+    await flush();
+    expect(actionEl(mount, "voice-mode")).toBeTruthy();
+  });
+
+  it('"when-empty" drops the control out of the DOM once the draft has text', async () => {
+    const { mount } = makeController({
+      composer: { actions: [voiceAction({ visibility: "when-empty" })] },
+    });
+
+    await flush();
+    expect(actionEl(mount, "voice-mode")).toBeTruthy();
+
+    typeInto(mount, "Hello");
+    await flush();
+    // Removed, not faded: gone from layout and from tab order.
+    expect(actionEl(mount, "voice-mode")).toBeNull();
+
+    // Whitespace is not a draft.
+    typeInto(mount, "   ");
+    await flush();
+    expect(actionEl(mount, "voice-mode")).toBeTruthy();
+  });
+
+  it('"when-text" is the inverse of "when-empty" on the same state', async () => {
+    const { mount } = makeController({
+      composer: {
+        actions: [
+          voiceAction({ visibility: "when-empty" }),
+          voiceAction({ id: "improve", visibility: "when-text", label: "Improve" }),
+        ],
+      },
+    });
+
+    await flush();
+    expect(actionEl(mount, "voice-mode")).toBeTruthy();
+    expect(actionEl(mount, "improve")).toBeNull();
+
+    typeInto(mount, "Hello");
+    await flush();
+    expect(actionEl(mount, "voice-mode")).toBeNull();
+    expect(actionEl(mount, "improve")).toBeTruthy();
+  });
+
+  it('hides a "when-empty" control while streaming, and holds it across chunks', async () => {
+    const chunks = [
+      'data: {"type":"text_delta","delta":"one"}\n\n',
+      'data: {"type":"text_delta","delta":" two"}\n\n',
+    ];
+    let release: () => void = () => {};
+    const settled = new Promise<void>((resolve) => {
+      release = resolve;
+    });
+    const encoder = new TextEncoder();
+    global.fetch = vi.fn().mockImplementation(
+      async () =>
+        ({
+          ok: true,
+          headers: new Headers({ "content-type": "text/event-stream" }),
+          body: new ReadableStream({
+            async start(controller) {
+              for (const chunk of chunks) {
+                controller.enqueue(encoder.encode(chunk));
+                // Each chunk is its own turn, so the action row re-syncs between
+                // them: a post-render patch would be visible here.
+                await Promise.resolve();
+              }
+              await settled;
+              controller.close();
+            },
+          }),
+        }) as unknown as Response
+    );
+
+    const { mount } = makeController({
+      composer: { actions: [voiceAction({ visibility: "when-empty" })] },
+    });
+
+    typeInto(mount, "Hello");
+    await flush();
+    mount
+      .querySelector<HTMLButtonElement>("[data-persona-composer-submit]")!
+      .click();
+
+    // The draft cleared on submit; the stream is what keeps the control hidden.
+    for (let i = 0; i < 12; i += 1) {
+      // eslint-disable-next-line no-await-in-loop
+      await flush();
+      expect(actionEl(mount, "voice-mode")).toBeNull();
+    }
+
+    release();
+    await flush(20);
+    expect(actionEl(mount, "voice-mode")).toBeTruthy();
+  });
+
+  it("stays hidden when the visible predicate says so, whatever the draft", async () => {
+    const { mount } = makeController({
+      composer: {
+        actions: [voiceAction({ visibility: "when-empty", visible: false })],
+      },
+    });
+
+    await flush();
+    expect(actionEl(mount, "voice-mode")).toBeNull();
+  });
+
+  it("follows a live update() of the visibility mode", async () => {
+    const { mount, controller } = makeController({
+      composer: { actions: [voiceAction()] },
+    });
+
+    typeInto(mount, "Hello");
+    await flush();
+    expect(actionEl(mount, "voice-mode")).toBeTruthy();
+
+    controller.update({
+      composer: { actions: [voiceAction({ visibility: "when-empty" })] },
+    });
+    await flush();
+    expect(actionEl(mount, "voice-mode")).toBeNull();
+  });
+});

package/src/ui.composer-models.test.ts

@@ -335,6 +335,43 @@ describe("composer model picker", () => {
       );
     });
 
+    it("returns the menu to the stylesheet fallback when an update unsets the token", () => {
+      const token = "--persona-components-composer-modelPicker-menuBackground";
+      const { mount, controller } = makeController({
+        ...popoverConfig(),
+        theme: {
+          components: { composer: { modelPicker: { menuBackground: "#1e1f20" } } },
+        },
+      });
+      expect(mount.style.getPropertyValue(token)).toBe("#1e1f20");
+      // The panel is portaled to document.body, so it never inherits the
+      // mount's theme vars. Stamped on the trigger here because jsdom's
+      // computed style does not inherit custom properties.
+      const button = trigger(mount)!;
+      button.style.setProperty(token, "#1e1f20");
+
+      button.click();
+      const panel = menu()!;
+      expect(panel.style.getPropertyValue(token)).toBe("#1e1f20");
+      button.click();
+
+      // Explicit undefined is the documented reset, so the mount stops
+      // carrying the var; the trigger's stand-in follows it.
+      controller.update({
+        theme: {
+          components: { composer: { modelPicker: { menuBackground: undefined } } },
+        },
+      });
+      expect(mount.style.getPropertyValue(token)).toBe("");
+      button.style.removeProperty(token);
+
+      // The menu outlives the update, so the next open has to clear the value
+      // the first one stamped; an empty inline value is the fallback state.
+      trigger(mount)!.click();
+      expect(menu()).toBe(panel);
+      expect(panel.style.getPropertyValue(token)).toBe("");
+    });
+
     it("shows the selected label on the closed control", () => {
       const { mount } = makeController(
         popoverConfig({ selectedModelId: "smart" })

package/src/ui.composer-modes.test.ts

@@ -326,3 +326,85 @@ describe("composer modes", () => {
     expect(panel.querySelector('[role="menuitem"]')?.textContent).toContain("Hidden");
   });
 });
+
+describe("modeGroups chipVisibility", () => {
+  beforeEach(() => {
+    window.scrollTo = vi.fn();
+  });
+
+  afterEach(() => {
+    controllers.splice(0).forEach((controller) => {
+      try {
+        controller.destroy();
+      } catch {
+        /* already destroyed */
+      }
+    });
+    mounts.splice(0).forEach((mount) => mount.remove());
+    document.body.innerHTML = "";
+    window.localStorage.clear();
+    vi.restoreAllMocks();
+  });
+
+  const hiddenGroups: ComposerModeGroup[] = [
+    { id: "tool", selection: "single", chipVisibility: "hidden" },
+    { id: "style", selection: "multiple" },
+  ];
+
+  it("keeps the bar button but renders no chip for the opted-out group", async () => {
+    const { mount, controller } = makeController({
+      composer: { modes, modeGroups: hiddenGroups },
+    });
+
+    modeButton(mount, "search").click();
+    await flush();
+    expect(controller.getComposerState().activeModeIds).toEqual(["search"]);
+    expect(modeButton(mount, "search").getAttribute("aria-pressed")).toBe("true");
+    expect(chips(mount)).toHaveLength(0);
+  });
+
+  it("still chips a group that did not opt out", async () => {
+    const { mount } = makeController({
+      composer: { modes, modeGroups: hiddenGroups },
+    });
+
+    modeButton(mount, "search").click();
+    modeButton(mount, "concise").click();
+    await flush();
+    expect(
+      chips(mount).map((chip) => chip.getAttribute("data-persona-composer-mode"))
+    ).toEqual(["concise"]);
+  });
+
+  it("leaves no chip row gap when every active mode is suppressed", async () => {
+    const { mount } = makeController({
+      composer: {
+        modes,
+        modeGroups: hiddenGroups,
+        defaultActiveModeIds: ["search"],
+      },
+    });
+    await flush();
+    const row = chipRow(mount);
+    expect(row === null || row.style.display === "none").toBe(true);
+  });
+
+  it("follows a live update() that opts the group back in", async () => {
+    const { mount, controller } = makeController({
+      composer: {
+        modes,
+        modeGroups: hiddenGroups,
+        defaultActiveModeIds: ["search"],
+      },
+    });
+    await flush();
+    expect(chips(mount)).toHaveLength(0);
+
+    controller.update({ composer: { modes, modeGroups } });
+    await flush();
+    expect(
+      chips(mount).map((chip) => chip.getAttribute("data-persona-composer-mode"))
+    ).toEqual(["search"]);
+    expect(chipRow(mount)!.style.display).toBe("flex");
+  });
+});

package/src/ui.composer-overflow.test.ts

@@ -103,6 +103,84 @@ describe("composer overflow menu in the live widget", () => {
     vi.restoreAllMocks();
   });
 
+  it("forwards the panel surface tokens onto the portaled menu on open", () => {
+    const { mount } = makeController({
+      composer: {
+        actions: [action("folded", { presentation: "overflow" })],
+        actionOverflow: { enabled: true },
+      },
+    });
+    // The panel is portaled to document.body, so it never inherits the mount's
+    // theme vars. Stamped on the trigger here because jsdom's computed style
+    // does not inherit custom properties.
+    const trigger = triggerOf(mount)!;
+    trigger.style.setProperty(
+      "--persona-components-composer-overflowMenu-background",
+      "#353535"
+    );
+    trigger.style.setProperty(
+      "--persona-components-composer-overflowMenu-borderColor",
+      "rgba(255, 255, 255, 0.08)"
+    );
+
+    const panel = openPanel(mount)!;
+
+    expect(
+      panel.style.getPropertyValue(
+        "--persona-components-composer-overflowMenu-background"
+      )
+    ).toBe("#353535");
+    expect(
+      panel.style.getPropertyValue(
+        "--persona-components-composer-overflowMenu-borderColor"
+      )
+    ).toBe("rgba(255, 255, 255, 0.08)");
+    // Unset keys stamp nothing, so the stylesheet's fallback still stands.
+    expect(
+      panel.style.getPropertyValue(
+        "--persona-components-composer-overflowMenu-shadow"
+      )
+    ).toBe("");
+  });
+
+  it("returns the panel to the stylesheet fallback when an update unsets the token", () => {
+    const token = "--persona-components-composer-overflowMenu-background";
+    const { mount, controller } = makeController({
+      composer: {
+        actions: [action("folded", { presentation: "overflow" })],
+        actionOverflow: { enabled: true },
+      },
+      theme: {
+        components: { composer: { overflowMenu: { background: "#353535" } } },
+      },
+    });
+    expect(mount.style.getPropertyValue(token)).toBe("#353535");
+    // Stamped on the trigger for the same reason as the test above: jsdom's
+    // computed style does not inherit custom properties.
+    const trigger = triggerOf(mount)!;
+    trigger.style.setProperty(token, "#353535");
+
+    const panel = openPanel(mount)!;
+    expect(panel.style.getPropertyValue(token)).toBe("#353535");
+    triggerOf(mount)!.click();
+
+    // Explicit undefined is the documented reset, so the mount stops carrying
+    // the var; the trigger's stand-in follows it.
+    controller.update({
+      theme: {
+        components: { composer: { overflowMenu: { background: undefined } } },
+      },
+    });
+    expect(mount.style.getPropertyValue(token)).toBe("");
+    trigger.style.removeProperty(token);
+
+    // The panel outlives the update, so the next open has to clear the value
+    // the first one stamped; an empty inline value is the fallback state.
+    const reopened = openPanel(mount)!;
+    expect(reopened).toBe(panel);
+    expect(reopened.style.getPropertyValue(token)).toBe("");
+  });
+
   it("sorts the trigger at the 900 anchor by default", () => {
     const { mount } = makeController({
       composer: {

package/src/ui.history-lifecycle.test.ts

@@ -212,7 +212,7 @@ describe("history controller lifecycle", () => {
       expect(window.localStorage.getItem(keysA.storageKey)).toBe("cvt_alpha");
     });
 
-    it("drops the store entirely when history is disabled", async () => {
+    it("keeps the recovery credential store when history UI is disabled", async () => {
       await seed();
       const { controller } = mount({
         clientToken: TOKEN_A,
@@ -224,7 +224,7 @@ describe("history controller lifecycle", () => {
       await flush(20);
 
       expect(recorder.instances.length).toBe(1);
-      expect(recorder.instances[0]!.destroy).toHaveBeenCalledTimes(1);
+      expect(recorder.instances[0]!.destroy).not.toHaveBeenCalled();
       expect(recorder.instances[0]!.clear).not.toHaveBeenCalled();
     });
   });