@runtypelabs/persona 4.15.0 → 4.17.0

package/src/utils/content-width.test.ts

@@ -0,0 +1,37 @@
+import { describe, expect, it } from "vitest";
+
+import { resolveContentMaxWidth } from "./content-width";
+import type { AgentWidgetConfig } from "../types";
+
+const cfg = (value?: Partial<AgentWidgetConfig>) =>
+  value as AgentWidgetConfig | undefined;
+
+describe("resolveContentMaxWidth", () => {
+  it("defaults panels to the surveyed 768px column", () => {
+    expect(resolveContentMaxWidth(cfg({}), false)).toBe("768px");
+    expect(resolveContentMaxWidth(undefined, false)).toBe("768px");
+  });
+
+  it("keeps the composer-bar's own 720px fallback", () => {
+    expect(resolveContentMaxWidth(cfg({}), true)).toBe("720px");
+  });
+
+  it("lets layout.contentMaxWidth win everywhere", () => {
+    const config = cfg({ layout: { contentMaxWidth: "90ch" } });
+    expect(resolveContentMaxWidth(config, false)).toBe("90ch");
+    expect(resolveContentMaxWidth(config, true)).toBe("90ch");
+  });
+
+  it("passes the \"none\" opt-out through untouched", () => {
+    expect(
+      resolveContentMaxWidth(cfg({ layout: { contentMaxWidth: "none" } }), false)
+    ).toBe("none");
+  });
+
+  it("prefers composerBar.contentMaxWidth over the 720px fallback", () => {
+    const config = cfg({
+      launcher: { composerBar: { contentMaxWidth: "600px" } },
+    });
+    expect(resolveContentMaxWidth(config, true)).toBe("600px");
+  });
+});

package/src/utils/content-width.ts

@@ -0,0 +1,17 @@
+import type { AgentWidgetConfig } from "../types";
+
+/**
+ * Resolver-owned default: every surveyed product caps the conversation
+ * column (704 to 896px, modal value 768px,
+ * "Hero width versus transcript width"). Kept out of defaults.ts so a
+ * materialized value cannot override the composer-bar's own 720px fallback.
+ * `"none"` opts out (applied as `max-width: none`).
+ */
+export const resolveContentMaxWidth = (
+  config: AgentWidgetConfig | undefined,
+  composerBar: boolean
+): string =>
+  config?.layout?.contentMaxWidth ??
+  (composerBar
+    ? config?.launcher?.composerBar?.contentMaxWidth ?? "720px"
+    : "768px");

package/src/utils/plugin-storage.test.ts

@@ -0,0 +1,94 @@
+// @vitest-environment jsdom
+
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { createPluginStorageFactory, pluginStorageKey } from "./plugin-storage";
+import type { AgentWidgetConfig } from "../types";
+
+const config = (patch: Partial<AgentWidgetConfig> = {}): AgentWidgetConfig =>
+  ({ apiUrl: "https://api.example.com/chat", ...patch }) as AgentWidgetConfig;
+
+describe("plugin storage facade", () => {
+  afterEach(() => {
+    window.localStorage.clear();
+    vi.restoreAllMocks();
+  });
+
+  it("namespaces keys by keyPrefix and plugin id", () => {
+    expect(pluginStorageKey(config(), "home-screen", "view")).toBe(
+      "persona-plugin:home-screen:view"
+    );
+    expect(
+      pluginStorageKey(
+        config({ persistState: { keyPrefix: "myapp-" } }),
+        "home-screen",
+        "view"
+      )
+    ).toBe("myapp-plugin:home-screen:view");
+  });
+
+  it("reads and writes localStorage under the namespaced key", () => {
+    const storage = createPluginStorageFactory(() => config())("pre-chat");
+    storage.set("identity", "ada");
+
+    expect(window.localStorage.getItem("persona-plugin:pre-chat:identity")).toBe(
+      "ada"
+    );
+    expect(storage.get("identity")).toBe("ada");
+
+    storage.remove("identity");
+    expect(storage.get("identity")).toBeNull();
+  });
+
+  it("keeps two plugins from colliding on the same key", () => {
+    const factory = createPluginStorageFactory(() => config());
+    factory("a").set("view", "home");
+    factory("b").set("view", "chat");
+
+    expect(factory("a").get("view")).toBe("home");
+    expect(factory("b").get("view")).toBe("chat");
+  });
+
+  it("downgrades to an in-memory map under persistState: false", () => {
+    const storage = createPluginStorageFactory(() =>
+      config({ persistState: false })
+    )("pre-chat");
+    storage.set("identity", "ada");
+
+    expect(storage.get("identity")).toBe("ada");
+    expect(window.localStorage.getItem("persona-plugin:pre-chat:identity")).toBeNull();
+  });
+
+  it("falls back to memory when localStorage access throws (private mode)", () => {
+    const setItem = vi
+      .spyOn(Storage.prototype, "setItem")
+      .mockImplementation(() => {
+        throw new Error("blocked");
+      });
+    const getItem = vi
+      .spyOn(Storage.prototype, "getItem")
+      .mockImplementation(() => {
+        throw new Error("blocked");
+      });
+
+    const storage = createPluginStorageFactory(() => config())("home-screen");
+    expect(() => storage.set("view", "home")).not.toThrow();
+    expect(storage.get("view")).toBe("home");
+
+    setItem.mockRestore();
+    getItem.mockRestore();
+  });
+
+  it("follows a live keyPrefix change through controller.update()", () => {
+    let current = config();
+    const storage = createPluginStorageFactory(() => current)("home-screen");
+    storage.set("view", "home");
+
+    current = config({ persistState: { keyPrefix: "next-" } });
+    expect(storage.get("view")).toBeNull();
+    storage.set("view", "chat");
+    expect(window.localStorage.getItem("next-plugin:home-screen:view")).toBe(
+      "chat"
+    );
+  });
+});

package/src/utils/plugin-storage.ts

@@ -0,0 +1,98 @@
+import type { AgentWidgetConfig } from "../types";
+
+/**
+ * Synchronous key-value store handed to plugin render hooks. Backed by
+ * `localStorage`, namespaced per plugin id. The async `storageAdapter` cannot
+ * back a synchronous API and `persistState` is not a general key-value surface.
+ */
+export interface AgentWidgetPluginStorage {
+  get: (key: string) => string | null;
+  set: (key: string, value: string) => void;
+  remove: (key: string) => void;
+}
+
+/** One factory per widget instance; the in-memory fallback is shared by it. */
+export type PluginStorageFactory = (
+  pluginId: string
+) => AgentWidgetPluginStorage;
+
+const resolveKeyPrefix = (config: AgentWidgetConfig | undefined): string => {
+  const persist = config?.persistState;
+  return (
+    (typeof persist === "object" ? persist?.keyPrefix : undefined) ?? "persona-"
+  );
+};
+
+export const pluginStorageKey = (
+  config: AgentWidgetConfig | undefined,
+  pluginId: string,
+  key: string
+): string => `${resolveKeyPrefix(config)}plugin:${pluginId}:${key}`;
+
+/**
+ * `persistState: false` and blocked storage both downgrade to a per-instance
+ * Map. localStorage access can throw (Safari private mode, partitioned
+ * iframes), so the first throw switches this instance to the Map for good.
+ */
+export const createPluginStorageFactory = (
+  getConfig: () => AgentWidgetConfig | undefined
+): PluginStorageFactory => {
+  const memory = new Map<string, string>();
+  let blocked = false;
+
+  const store = (): Storage | null => {
+    if (blocked) return null;
+    if (getConfig()?.persistState === false) return null;
+    try {
+      if (typeof window === "undefined" || !window.localStorage) return null;
+      return window.localStorage;
+    } catch {
+      blocked = true;
+      return null;
+    }
+  };
+
+  return (pluginId: string): AgentWidgetPluginStorage => {
+    const keyFor = (key: string) =>
+      pluginStorageKey(getConfig(), pluginId, key);
+
+    return {
+      get: (key) => {
+        const full = keyFor(key);
+        const local = store();
+        if (local) {
+          try {
+            return local.getItem(full);
+          } catch {
+            blocked = true;
+          }
+        }
+        return memory.get(full) ?? null;
+      },
+      set: (key, value) => {
+        const full = keyFor(key);
+        const local = store();
+        if (local) {
+          try {
+            local.setItem(full, value);
+            return;
+          } catch {
+            blocked = true;
+          }
+        }
+        memory.set(full, value);
+      },
+      remove: (key) => {
+        const full = keyFor(key);
+        memory.delete(full);
+        const local = store();
+        if (!local) return;
+        try {
+          local.removeItem(full);
+        } catch {
+          blocked = true;
+        }
+      },
+    };
+  };
+};

package/src/utils/theme.test.ts

@@ -137,6 +137,36 @@ describe('theme utils', () => {
     expect(cssVars['--persona-button-radius']).toBe('6px');
   });
 
+  it('zeroes horizontal intro-card padding when the card resolves flat', () => {
+    const cssVars = themeToCssVariables(createTheme({} as any));
+    expect(cssVars['--persona-intro-card-padding']).toBe('1.5rem 0');
+  });
+
+  it('keeps full intro-card padding when a background or shadow makes it a card', () => {
+    const withBackground = themeToCssVariables(
+      createTheme({
+        components: { introCard: { background: '#ffffff' } },
+      } as any)
+    );
+    expect(withBackground['--persona-intro-card-padding']).toBe('1.5rem');
+
+    const withShadow = themeToCssVariables(
+      createTheme({
+        components: { introCard: { shadow: '0 1px 2px rgba(0,0,0,0.1)' } },
+      } as any)
+    );
+    expect(withShadow['--persona-intro-card-padding']).toBe('1.5rem');
+  });
+
+  it('lets an explicit intro-card padding token win over the flat default', () => {
+    const cssVars = themeToCssVariables(
+      createTheme({
+        components: { introCard: { padding: '2rem' } },
+      } as any)
+    );
+    expect(cssVars['--persona-intro-card-padding']).toBe('2rem');
+  });
+
   it.each([
     {
       role: 'surface',
@@ -287,6 +317,61 @@ describe('theme utils', () => {
     expect(customVars['--persona-header-action-icon-fg']).toBe('#9ca3af');
   });
 
+  it('emits full-path CSS variables for header and welcome text style tokens', () => {
+    const theme = createTheme({
+      components: {
+        introCard: {
+          title: { fontFamily: 'Georgia, serif', fontSize: '1.5rem' },
+        },
+        header: {
+          title: {
+            fontFamily: 'Inter, sans-serif',
+            color: 'palette.colors.secondary.500',
+          },
+        },
+      },
+    } as any);
+    const cssVars = themeToCssVariables(theme);
+
+    expect(cssVars['--persona-components-introCard-title-fontFamily']).toBe(
+      'Georgia, serif'
+    );
+    expect(cssVars['--persona-components-introCard-title-fontSize']).toBe('1.5rem');
+    expect(cssVars['--persona-components-header-title-fontFamily']).toBe(
+      'Inter, sans-serif'
+    );
+    // title.color supersedes the legacy titleForeground alias.
+    expect(cssVars['--persona-header-title-fg']).toBe('#8b5cf6');
+  });
+
+  it('keeps titleForeground working when no header.title.color is set', () => {
+    const cssVars = themeToCssVariables(
+      createTheme({
+        components: {
+          header: { titleForeground: 'palette.colors.gray.500' },
+        },
+      } as any)
+    );
+
+    expect(cssVars['--persona-header-title-fg']).toBe('#6b7280');
+  });
+
+  it('emits suggestion itemGap for every variant, defaulting to 8px', () => {
+    const defaults = themeToCssVariables(createTheme());
+    expect(defaults['--persona-components-suggestion-chip-itemGap']).toBe('8px');
+    expect(defaults['--persona-components-suggestion-card-itemGap']).toBe('8px');
+    expect(defaults['--persona-components-suggestion-list-itemGap']).toBe('8px');
+
+    const custom = themeToCssVariables(
+      createTheme({
+        components: { suggestion: { list: { itemGap: '20px' } } },
+      } as any)
+    );
+    expect(custom['--persona-components-suggestion-list-itemGap']).toBe('20px');
+    // Sibling variants keep the default.
+    expect(custom['--persona-components-suggestion-chip-itemGap']).toBe('8px');
+  });
+
   it('maps button.ghost tokens to the composer ghost icon-button CSS variables', () => {
     const cssVars = themeToCssVariables(createTheme());
 
@@ -574,4 +659,56 @@ describe('theme utils', () => {
     const cssVars = themeToCssVariables(theme);
     expect(cssVars['--persona-code-bg']).toBe('#fafafa');
   });
+
+  it('derives the shared scrollbar variables from components.scrollbar with border fallback', () => {
+    const defaults = themeToCssVariables(createTheme({} as any));
+    expect(defaults['--persona-scrollbar-thumb']).toBe(defaults['--persona-border']);
+    expect(defaults['--persona-scrollbar-track']).toBe('transparent');
+
+    const themed = themeToCssVariables(
+      createTheme({
+        components: { scrollbar: { thumb: '#00dfc1', track: '#111111' } },
+      } as any)
+    );
+    expect(themed['--persona-scrollbar-thumb']).toBe('#00dfc1');
+    expect(themed['--persona-scrollbar-track']).toBe('#111111');
+  });
+
+  it('exposes intro card border and composer border color tokens', () => {
+    const defaults = themeToCssVariables(createTheme({} as any));
+    expect(defaults['--persona-intro-card-border']).toBe('none');
+    expect(defaults['--persona-composer-border-color']).toBe(defaults['--persona-border']);
+
+    const themed = themeToCssVariables(
+      createTheme({
+        components: {
+          introCard: { border: '1px solid rgba(0, 0, 0, 0.1)' },
+          composer: { borderColor: 'rgba(29, 28, 23, 0.25)' },
+        },
+      } as any)
+    );
+    expect(themed['--persona-intro-card-border']).toBe('1px solid rgba(0, 0, 0, 0.1)');
+    expect(themed['--persona-composer-border-color']).toBe('rgba(29, 28, 23, 0.25)');
+  });
+
+  it('follows the palette radius for markdown code blocks so square themes get square code', () => {
+    const defaults = themeToCssVariables(createTheme({} as any));
+    expect(defaults['--persona-md-code-block-border-radius']).toBe('0.375rem');
+
+    const square = themeToCssVariables(
+      createTheme({
+        palette: {
+          radius: { sm: '0px', md: '0px', lg: '0px', xl: '0px', '2xl': '0px' },
+        },
+      } as any)
+    );
+    expect(square['--persona-md-code-block-border-radius']).toBe('0px');
+
+    const explicit = themeToCssVariables(
+      createTheme({
+        components: { markdown: { codeBlock: { borderRadius: '2px' } } },
+      } as any)
+    );
+    expect(explicit['--persona-md-code-block-border-radius']).toBe('2px');
+  });
 });

package/src/utils/tokens.ts

@@ -344,6 +344,7 @@ export const DEFAULT_COMPONENTS: ComponentTokens = {
       borderRadius: 'palette.radius.full',
       padding: '0.5rem 0.875rem',
       gap: '0.5rem',
+      itemGap: '8px',
       minHeight: '36px',
       fontSize: '0.8125rem',
       lineHeight: '1.25',
@@ -362,6 +363,7 @@ export const DEFAULT_COMPONENTS: ComponentTokens = {
       padding: '1rem',
       shadow: 'palette.shadows.sm',
       gap: '0.625rem',
+      itemGap: '8px',
       minHeight: '72px',
       fontSize: '0.875rem',
       lineHeight: '1.35',
@@ -379,6 +381,7 @@ export const DEFAULT_COMPONENTS: ComponentTokens = {
       borderRadius: 'palette.radius.md',
       padding: '0.75rem',
       gap: '0.625rem',
+      itemGap: '8px',
       minHeight: '44px',
       fontSize: '0.875rem',
       lineHeight: '1.35',
@@ -399,6 +402,10 @@ export const DEFAULT_COMPONENTS: ComponentTokens = {
   composer: {
     shadow: 'palette.shadows.none',
   },
+  scrollbar: {
+    thumb: 'semantic.colors.border',
+    track: 'transparent',
+  },
   markdown: {
     inlineCode: {
       background: 'palette.colors.gray.50',
@@ -415,6 +422,7 @@ export const DEFAULT_COMPONENTS: ComponentTokens = {
       background: 'semantic.colors.container',
       borderColor: 'semantic.colors.border',
       textColor: 'inherit',
+      borderRadius: 'palette.radius.md',
     },
     table: {
       headerBackground: 'semantic.colors.container',
@@ -851,10 +859,15 @@ export function themeToCssVariables(theme: PersonaTheme): Record<string, string>
     cssVars['--persona-components-header-iconBackground'] ?? cssVars['--persona-primary'];
   cssVars['--persona-header-icon-fg'] =
     cssVars['--persona-components-header-iconForeground'] ?? cssVars['--persona-text-inverse'];
+  // `title.color` / `subtitle.color` supersede the legacy *Foreground tokens.
   cssVars['--persona-header-title-fg'] =
-    cssVars['--persona-components-header-titleForeground'] ?? cssVars['--persona-primary'];
+    cssVars['--persona-components-header-title-color'] ??
+    cssVars['--persona-components-header-titleForeground'] ??
+    cssVars['--persona-primary'];
   cssVars['--persona-header-subtitle-fg'] =
-    cssVars['--persona-components-header-subtitleForeground'] ?? cssVars['--persona-text-muted'];
+    cssVars['--persona-components-header-subtitle-color'] ??
+    cssVars['--persona-components-header-subtitleForeground'] ??
+    cssVars['--persona-text-muted'];
   cssVars['--persona-header-action-icon-fg'] =
     cssVars['--persona-components-header-actionIconForeground'] ?? cssVars['--persona-muted'];
 
@@ -870,10 +883,25 @@ export function themeToCssVariables(theme: PersonaTheme): Record<string, string>
     cssVars['--persona-components-introCard-background'] ?? 'transparent';
   cssVars['--persona-intro-card-radius'] =
     cssVars['--persona-components-introCard-borderRadius'] ?? '1rem';
-  cssVars['--persona-intro-card-padding'] =
+  // Flat cards (transparent background, no shadow) drop the horizontal
+  // component of the stock padding so the welcome text shares the content
+  // column's left edge instead of carrying an invisible card inset. Compared
+  // by resolved value, not key presence: DEFAULT_COMPONENTS materializes the
+  // introCard tokens into every theme. A non-stock padding is emitted as-is;
+  // '1.5rem 1.5rem' forces the symmetric inset on a flat card.
+  const introBg = cssVars['--persona-components-introCard-background'];
+  const introShadow = cssVars['--persona-components-introCard-shadow'];
+  const introCardFlat =
+    (!introBg || introBg === 'transparent' || introBg === 'none') &&
+    (!introShadow || introShadow === 'none');
+  const introPadding =
     cssVars['--persona-components-introCard-padding'] ?? '1.5rem';
+  cssVars['--persona-intro-card-padding'] =
+    introCardFlat && introPadding === '1.5rem' ? '1.5rem 0' : introPadding;
   cssVars['--persona-intro-card-shadow'] =
     cssVars['--persona-components-introCard-shadow'] ?? 'none';
+  cssVars['--persona-intro-card-border'] =
+    cssVars['--persona-components-introCard-border'] ?? 'none';
 
   cssVars['--persona-input-background'] =
     cssVars['--persona-components-input-background'] ?? cssVars['--persona-surface'];
@@ -947,6 +975,18 @@ export function themeToCssVariables(theme: PersonaTheme): Record<string, string>
     cssVars['--persona-components-composer-fontSize'] ?? '0.875rem';
   cssVars['--persona-composer-line-height'] =
     cssVars['--persona-components-composer-lineHeight'] ?? '1.25rem';
+  cssVars['--persona-composer-border-color'] =
+    cssVars['--persona-components-composer-borderColor'] ??
+    cssVars['--persona-border'] ??
+    '#e5e7eb';
+
+  // Scrollbars (every scroller in the widget consumes these two)
+  cssVars['--persona-scrollbar-thumb'] =
+    cssVars['--persona-components-scrollbar-thumb'] ??
+    cssVars['--persona-border'] ??
+    '#e5e7eb';
+  cssVars['--persona-scrollbar-track'] =
+    cssVars['--persona-components-scrollbar-track'] ?? 'transparent';
 
   cssVars['--persona-md-inline-code-bg'] =
     cssVars['--persona-components-markdown-inlineCode-background'] ?? cssVars['--persona-container'];
@@ -979,6 +1019,12 @@ export function themeToCssVariables(theme: PersonaTheme): Record<string, string>
     cssVars['--persona-components-markdown-codeBlock-borderColor'] ?? cssVars['--persona-border'];
   cssVars['--persona-md-code-block-text-color'] =
     cssVars['--persona-components-markdown-codeBlock-textColor'] ?? 'inherit';
+  // Follows the palette radius so square-corner themes get square code blocks;
+  // the 0.375rem fallback matches palette.radius.md's default.
+  cssVars['--persona-md-code-block-border-radius'] =
+    cssVars['--persona-components-markdown-codeBlock-borderRadius'] ??
+    cssVars['--persona-radius-md'] ??
+    '0.375rem';
 
   // Markdown table
   cssVars['--persona-md-table-header-bg'] =