@runtypelabs/persona 4.14.0 → 4.16.0

package/src/utils/code-generators.test.ts

@@ -563,6 +563,46 @@ describe("Full Config with Hooks Integration", () => {
 // Backward Compatibility Tests
 // =============================================================================
 
+describe("Suggestions Serialization", () => {
+  it("preserves structured suggestion configuration in every format", () => {
+    const config = {
+      ...minimalConfig,
+      suggestions: {
+        starters: {
+          variant: "card",
+          behavior: "fill",
+          items: [
+            {
+              id: "compare",
+              label: "Compare plans",
+              prompt: "Compare plans for my team",
+            },
+          ],
+        },
+        followUps: {
+          placement: "after-message",
+          overflow: "scroll",
+        },
+      },
+    };
+    const formats: CodeFormat[] = [
+      "esm",
+      "react-component",
+      "react-advanced",
+      "script-installer",
+      "script-manual",
+      "script-advanced",
+    ];
+
+    for (const format of formats) {
+      const code = generateCodeSnippet(config, format);
+      expect(code).toContain("suggestions");
+      expect(code).toContain("Compare plans");
+      expect(code).toContain("after-message");
+    }
+  });
+});
+
 describe("Backward Compatibility", () => {
   it("should work without options parameter", () => {
     const code = generateCodeSnippet(minimalConfig, "esm");

package/src/utils/code-generators.ts

@@ -430,6 +430,19 @@ function generateMarkdownConfig(config: any, indent: string): string[] {
   return lines;
 }
 
+// Suggestions may contain nested rich items. JSON object syntax is also valid
+// JavaScript/TypeScript, so preserve the complete public shape instead of
+// duplicating every leaf in each output-format generator.
+function generateSuggestionsConfig(config: any, indent: string): string[] {
+  if (!config.suggestions) return [];
+  const serialized = JSON.stringify(config.suggestions, null, 2).split("\n");
+  return serialized.map((line, index) => {
+    const prefix = index === 0 ? `${indent}suggestions: ` : indent;
+    const suffix = index === serialized.length - 1 ? "," : "";
+    return `${prefix}${line}${suffix}`;
+  });
+}
+
 // Helper to generate layout config (excluding render functions and slots)
 function generateLayoutConfig(config: any, indent: string): string[] {
   const lines: string[] = [];
@@ -697,6 +710,8 @@ function generateESMCode(config: any, options?: CodeGeneratorOptions): string {
     lines.push("    },");
   }
 
+  lines.push(...generateSuggestionsConfig(config, "    "));
+
   if (config.suggestionChips && config.suggestionChips.length > 0) {
     lines.push("    suggestionChips: [");
     config.suggestionChips.forEach((chip: string) => {
@@ -845,6 +860,8 @@ function generateReactComponentCode(config: any, options?: CodeGeneratorOptions)
     lines.push("        },");
   }
 
+  lines.push(...generateSuggestionsConfig(config, "        "));
+
   if (config.suggestionChips && config.suggestionChips.length > 0) {
     lines.push("        suggestionChips: [");
     config.suggestionChips.forEach((chip: string) => {
@@ -1110,6 +1127,8 @@ function generateReactAdvancedCode(config: any, options?: CodeGeneratorOptions):
     lines.push("        },");
   }
 
+  lines.push(...generateSuggestionsConfig(config, "        "));
+
   if (config.suggestionChips && config.suggestionChips.length > 0) {
     lines.push("        suggestionChips: [");
     config.suggestionChips.forEach((chip: string) => {
@@ -1312,6 +1331,7 @@ function buildSerializableConfig(config: any): Record<string, any> {
   if (config.voiceRecognition) serializableConfig.voiceRecognition = config.voiceRecognition;
   if (config.statusIndicator) serializableConfig.statusIndicator = config.statusIndicator;
   if (config.features) serializableConfig.features = config.features;
+  if (config.suggestions) serializableConfig.suggestions = config.suggestions;
   if (config.suggestionChips?.length > 0) serializableConfig.suggestionChips = config.suggestionChips;
   if (config.suggestionChipsConfig) serializableConfig.suggestionChipsConfig = config.suggestionChipsConfig;
   if (config.debug) serializableConfig.debug = config.debug;
@@ -1520,6 +1540,8 @@ function generateScriptManualCode(config: any, options?: CodeGeneratorOptions):
     lines.push("      },");
   }
 
+  lines.push(...generateSuggestionsConfig(config, "      "));
+
   if (config.suggestionChips && config.suggestionChips.length > 0) {
     lines.push("      suggestionChips: [");
     config.suggestionChips.forEach((chip: string) => {

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

@@ -32,6 +32,30 @@ describe("mergeConfigUpdate", () => {
     expect(next.suggestionChips).toEqual(["x"]);
   });
 
+  it("patches suggestion surfaces without dropping sibling behavior", () => {
+    const prev = base({
+      suggestions: {
+        starters: { variant: "card", behavior: "fill" },
+        followUps: { variant: "chip", placement: "after-message" },
+      },
+    });
+    const next = mergeConfigUpdate(prev, {
+      suggestions: {
+        followUps: { overflow: "wrap" },
+      },
+    });
+
+    expect(next.suggestions?.starters).toEqual({
+      variant: "card",
+      behavior: "fill",
+    });
+    expect(next.suggestions?.followUps).toEqual({
+      variant: "chip",
+      placement: "after-message",
+      overflow: "wrap",
+    });
+  });
+
   it("replaces callbacks wholesale", () => {
     const first = vi.fn();
     const second = vi.fn();

package/src/utils/config-merge.ts

@@ -25,6 +25,8 @@ const REPLACE_LEAF_PATHS = new Set<string>([
   "features.artifacts.display",
   "features.streamAnimation.plugins",
   "preferences",
+  // Discriminated union: recursive merge would splice two icon variants.
+  "welcome.icon",
 ]);
 
 // Recursive patch merge. A key merges recursively iff both previous and patch

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/icons.test.ts

@@ -0,0 +1,26 @@
+// @vitest-environment jsdom
+
+import { describe, expect, it, vi } from "vitest";
+
+import { renderLucideIcon } from "./icons";
+
+describe("renderLucideIcon", () => {
+  it.each(["lightbulb", "chart-column", "image", "pen-line"] as const)(
+    "renders %s as an inline svg",
+    (name) => {
+      const svg = renderLucideIcon(name);
+      expect(svg).not.toBeNull();
+      expect(svg?.tagName.toLowerCase()).toBe("svg");
+      expect(svg?.getAttribute("viewBox")).toBe("0 0 24 24");
+      // Geometry, not an empty shell.
+      expect(svg!.childNodes.length).toBeGreaterThan(0);
+    }
+  );
+
+  it("returns null and warns for a name outside the registry", () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    expect(renderLucideIcon("definitely-not-an-icon")).toBeNull();
+    expect(warn).toHaveBeenCalled();
+    warn.mockRestore();
+  });
+});

package/src/utils/icons.ts

@@ -70,6 +70,7 @@ import {
   Plus,
   Minus,
   Pencil,
+  PenLine,
   Trash,
   Trash2,
   Save,
@@ -117,12 +118,15 @@ import {
   Folder,
   FolderOpen,
   Files,
+  // ---------- Data ----------
+  ChartColumn,
   // ---------- Decorative ----------
   Sparkles,
   Zap,
   Sun,
   Moon,
   Flag,
+  Lightbulb,
   // ---------- Devices ----------
   Monitor,
   Smartphone,
@@ -220,6 +224,7 @@ const LUCIDE_ICONS = {
   "plus": Plus,
   "minus": Minus,
   "pencil": Pencil,
+  "pen-line": PenLine,
   "trash": Trash,
   "trash-2": Trash2,
   "save": Save,
@@ -267,12 +272,15 @@ const LUCIDE_ICONS = {
   "folder": Folder,
   "folder-open": FolderOpen,
   "files": Files,
+  // Data
+  "chart-column": ChartColumn,
   // Decorative
   "sparkles": Sparkles,
   "zap": Zap,
   "sun": Sun,
   "moon": Moon,
   "flag": Flag,
+  "lightbulb": Lightbulb,
   // Devices
   "monitor": Monitor,
   "smartphone": Smartphone,

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;
+        }
+      },
+    };
+  };
+};