@runtypelabs/persona 4.8.0 → 4.10.0

package/src/utils/composer-history.ts

@@ -10,36 +10,44 @@
  * to the textarea.
  */
 
-export interface ComposerHistoryState {
+/**
+ * Generic over the entry type `T` so the same machine drives both composer
+ * surfaces: chip mode recalls `string`s (textarea values); inline mode recalls
+ * `ComposerDocument`s (blocks + mention ids). The machine never inspects an entry
+ * — it only indexes the list and swaps the draft — so it stays entirely
+ * value-agnostic. Defaults to `string` so every existing chip-mode caller is
+ * unchanged.
+ */
+export interface ComposerHistoryState<T = string> {
   /** Index into the history list, or -1 when not navigating. */
   index: number;
-  /** The user's in-progress text, saved when navigation begins. */
-  draft: string;
+  /** The user's in-progress entry, saved when navigation begins. */
+  draft: T;
 }
 
-export const INITIAL_HISTORY_STATE: ComposerHistoryState = {
+export const INITIAL_HISTORY_STATE: ComposerHistoryState<string> = {
   index: -1,
   draft: ""
 };
 
-export interface ComposerHistoryInput {
+export interface ComposerHistoryInput<T = string> {
   direction: "up" | "down";
-  /** Previously sent user-message texts, oldest first. */
-  history: string[];
-  /** Current textarea value (saved as the draft when navigation begins). */
-  currentValue: string;
-  /** True when the caret sits at the very start of the textarea. */
+  /** Previously sent user entries, oldest first. */
+  history: T[];
+  /** Current composer entry (saved as the draft when navigation begins). */
+  currentValue: T;
+  /** True when the caret sits at the very start of the composer. */
   atStart: boolean;
-  state: ComposerHistoryState;
+  state: ComposerHistoryState<T>;
 }
 
-export interface ComposerHistoryResult {
+export interface ComposerHistoryResult<T = string> {
   /** Whether the key was consumed (caller should preventDefault). */
   handled: boolean;
-  /** New textarea value to apply: only present when it should change. */
-  value?: string;
+  /** New entry to apply: only present when it should change. */
+  value?: T;
   /** Next navigation state. */
-  state: ComposerHistoryState;
+  state: ComposerHistoryState<T>;
 }
 
 /**
@@ -50,9 +58,9 @@ export interface ComposerHistoryResult {
  * - **Down** only acts while already navigating, stepping toward newer messages
  *   and finally restoring the saved draft once it walks past the newest entry.
  */
-export function navigateComposerHistory(
-  input: ComposerHistoryInput
-): ComposerHistoryResult {
+export function navigateComposerHistory<T = string>(
+  input: ComposerHistoryInput<T>
+): ComposerHistoryResult<T> {
   const { direction, history, currentValue, atStart, state } = input;
   const inHistory = state.index !== -1;
 
@@ -104,10 +112,12 @@ export function navigateComposerHistory(
     };
   }
 
-  // Stepped past the newest entry: restore the saved draft and exit.
+  // Stepped past the newest entry: restore the saved draft and exit. `index: -1`
+  // marks "not navigating"; the draft field is dead until the next Up overwrites
+  // it, so keep the existing (correctly-typed) value rather than fabricating one.
   return {
     handled: true,
     value: state.draft,
-    state: { ...INITIAL_HISTORY_STATE }
+    state: { index: -1, draft: state.draft }
   };
 }

package/src/utils/composer-input.ts

@@ -0,0 +1,159 @@
+/**
+ * The composer input surface the mention controller drives, abstracted over the
+ * two editing modes:
+ *
+ *  - **chip mode** (`display: "chip"`, default): a plain `<textarea>`. Logical
+ *    text is the raw value and logical caret is `selectionStart`.
+ *  - **inline mode** (`display: "inline"`, Phase 4): a contenteditable surface
+ *    whose atomic mention tokens collapse to a single `` in the logical text
+ *    (see `composer-document.ts`). Its adapter additionally implements the
+ *    optional document/token methods below.
+ *
+ * The controller only ever touches the composer through this capability, so the
+ * same menu/keyboard/search engine serves both surfaces. `ComposerInputCapability`
+ * is a superset of the public `AgentWidgetContextMentionComposerCapability`
+ * (`getValue`/`setValue`/`submit`) — the single source of truth for composer
+ * access — so a client `command:"action"` handler receives the same object.
+ *
+ * IMPORTANT (bundle guard): this module imports the document model TYPE-ONLY, so
+ * the chip chunk (`context-mentions.js`) never pulls `composer-document.ts`
+ * runtime. The contenteditable adapter, which does need it, lives in the separate
+ * inline chunk. Keep it that way — see `context-mentions-bundle.test.ts`.
+ */
+
+import type { MentionTriggerMatch } from "./mention-trigger";
+import type {
+  ComposerDocument,
+  ComposerMentionId
+} from "./composer-document";
+import type {
+  AgentWidgetContextMentionComposerCapability,
+  AgentWidgetContextMentionRef
+} from "../types";
+
+export interface ComposerInputCapability
+  extends AgentWidgetContextMentionComposerCapability {
+  /** The editable element — ARIA target for the menu, and focus receiver. */
+  readonly element: HTMLElement;
+  /** Text used for trigger parsing. Chip: `=== getValue()`; inline: text + ``. */
+  getLogicalText: () => string;
+  /** Caret/selection in LOGICAL coordinates. */
+  getSelection: () => { start: number; end: number };
+  /** Move the caret/selection (logical coordinates). */
+  setSelection: (start: number, end?: number) => void;
+  /** Replace the plain text and place the caret. No input event, no focus. */
+  setValueWithCaret: (value: string, caret: number) => void;
+  /** Fire input listeners after a programmatic edit. */
+  dispatchInput: () => void;
+  focus: () => void;
+
+  /**
+   * INLINE ONLY (contenteditable). Bounding rect (VIEWPORT coordinates) of the
+   * LOGICAL character range `[start, end)`, or `null` when unmeasurable (invalid
+   * range or a zero-size/degenerate rect). Used to trigger-anchor the mention menu
+   * horizontally to the `@` glyph. Chip (textarea) adapters omit it — no cheap
+   * per-glyph rect without a mirror-div hack, so the menu stays composer-anchored
+   * (graceful degradation). Callers treat a missing method exactly like a `null`
+   * result.
+   */
+  getLogicalRangeRect?: (start: number, end: number) => DOMRect | null;
+
+  // ---- inline-only (contenteditable adapter); chip adapters omit these ----
+
+  /** Canonical document (inline mode). */
+  getDocument?: () => ComposerDocument;
+  /**
+   * INLINE ONLY. Replace the active trigger range (`match`, logical coordinates)
+   * with an atomic mention token and place the caret after it. Returns the new
+   * mention's id (resolve-tracking key), or `null` if the range no longer matches
+   * the document (stale menu). Chip adapters leave this undefined — the controller
+   * then falls back to `stripMentionQuery`.
+   */
+  insertMentionAtTrigger?: (
+    ref: AgentWidgetContextMentionRef,
+    match: MentionTriggerMatch
+  ) => ComposerMentionId | null;
+  /**
+   * INLINE ONLY. Insert an atomic mention token at the current caret/selection
+   * (picker path — the affordance button opens with no trigger char to replace).
+   * Returns the new mention's id. Chip adapters leave this undefined.
+   */
+  insertMentionAtSelection?: (
+    ref: AgentWidgetContextMentionRef
+  ) => ComposerMentionId;
+  /**
+   * INLINE ONLY. Reflect a mention's resolve status on its live token element —
+   * used to surface resolve errors inline. Toggles the error styling for `"error"`
+   * and clears it otherwise. No-op for an unknown id. Chip adapters omit this.
+   */
+  setMentionStatus?: (
+    id: ComposerMentionId,
+    status: "pending" | "resolved" | "error"
+  ) => void;
+  /**
+   * INLINE ONLY. Replace the LOGICAL range `[start, end)` with plain `text`,
+   * preserving every mention token that lies outside the range, and place the
+   * caret after the inserted text. This is the token-safe edit the controller
+   * uses for query-strip / slash-completion / prompt-macro rewrites, since a plain
+   * `getValue()` string-slice would misalign against DISPLAY text (`@Label`
+   * expands a token to many chars) and re-rendering as one text block would
+   * destroy every token. Chip adapters omit it — there DISPLAY === LOGICAL, so the
+   * controller string-slices `getValue()` + `setValueWithCaret` instead.
+   */
+  replaceLogicalRange?: (start: number, end: number, text: string) => void;
+}
+
+/**
+ * Submit the form that owns a composer element: prefer `requestSubmit()` (fires
+ * native validation + a cancelable `submit`), falling back to a dispatched
+ * cancelable `submit` event where `requestSubmit` is unavailable. Shared by both
+ * composer adapters so submission behaves identically across editing modes.
+ */
+export function requestFormSubmit(form: HTMLFormElement | null | undefined): void {
+  if (!form) return;
+  if (typeof form.requestSubmit === "function") {
+    form.requestSubmit();
+  } else {
+    form.dispatchEvent(new Event("submit", { bubbles: true, cancelable: true }));
+  }
+}
+
+/**
+ * Chip-mode adapter: a `ComposerInputCapability` backed by a raw `<textarea>`.
+ * Logical text === value, logical caret === `selectionStart`. `submit()` derives
+ * the composer form from `textarea.form` (falling back to a dispatched `submit`
+ * event where `requestSubmit` is unavailable), matching the widget's own behavior
+ * — so the composer surface owns submission, no separate capability needed.
+ */
+export function createTextareaComposerInput(
+  textarea: HTMLTextAreaElement
+): ComposerInputCapability {
+  const dispatchInput = (): void => {
+    textarea.dispatchEvent(new Event("input", { bubbles: true }));
+  };
+  return {
+    element: textarea,
+    getValue: () => textarea.value,
+    getLogicalText: () => textarea.value,
+    getSelection: () => ({
+      start: textarea.selectionStart ?? 0,
+      end: textarea.selectionEnd ?? 0
+    }),
+    setSelection: (start, end = start) => {
+      textarea.setSelectionRange(start, end);
+    },
+    setValueWithCaret: (value, caret) => {
+      textarea.value = value;
+      textarea.setSelectionRange(caret, caret);
+    },
+    setValue: (value: string) => {
+      textarea.value = value;
+      textarea.setSelectionRange(value.length, value.length);
+      dispatchInput();
+      textarea.focus();
+    },
+    submit: () => requestFormSubmit(textarea.form),
+    dispatchInput,
+    focus: () => textarea.focus()
+  };
+}

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

@@ -0,0 +1,131 @@
+import { describe, expect, it, vi } from "vitest";
+
+import { mergeConfigUpdate } from "./config-merge";
+import { mergeWithDefaults } from "../defaults";
+import type { AgentWidgetConfig, StreamAnimationPlugin } from "../types";
+
+// Stored controller config is post-mergeWithDefaults; simulate that here.
+const base = (overrides: Partial<AgentWidgetConfig> = {}): AgentWidgetConfig =>
+  mergeWithDefaults({ apiUrl: "https://api.example.com/chat", ...overrides }) as AgentWidgetConfig;
+
+describe("mergeConfigUpdate", () => {
+  it("recursively merges nested plain objects, preserving sibling overrides", () => {
+    const prev = base({ launcher: { enabled: false, clearChat: { backgroundColor: "#123456" } } });
+    const next = mergeConfigUpdate(prev, { launcher: { title: "After" } });
+    expect(next.launcher?.clearChat?.backgroundColor).toBe("#123456");
+    expect(next.launcher?.title).toBe("After");
+    // Launcher defaults survive a partial patch.
+    expect(next.launcher?.mountMode).toBe("floating");
+  });
+
+  it("patches composerBar without replacing sibling launcher fields", () => {
+    const prev = base({ launcher: { title: "Keep", composerBar: { collapsedMaxWidth: "700px" } } });
+    const next = mergeConfigUpdate(prev, { launcher: { composerBar: { bottomOffset: "8px" } } });
+    expect(next.launcher?.title).toBe("Keep");
+    expect(next.launcher?.composerBar?.collapsedMaxWidth).toBe("700px");
+    expect(next.launcher?.composerBar?.bottomOffset).toBe("8px");
+  });
+
+  it("replaces arrays wholesale (suggestionChips)", () => {
+    const prev = base({ suggestionChips: ["a", "b", "c"] });
+    const next = mergeConfigUpdate(prev, { suggestionChips: ["x"] });
+    expect(next.suggestionChips).toEqual(["x"]);
+  });
+
+  it("replaces callbacks wholesale", () => {
+    const first = vi.fn();
+    const second = vi.fn();
+    const prev = base({ onSessionInit: first });
+    const next = mergeConfigUpdate(prev, { onSessionInit: second });
+    expect(next.onSessionInit).toBe(second);
+  });
+
+  it("guards boolean|object unions in both directions", () => {
+    const objFirst = base({ approval: { backgroundColor: "#ffffff" } });
+    const toScalar = mergeConfigUpdate(objFirst, { approval: false });
+    expect(toScalar.approval).toBe(false);
+
+    const scalarFirst = base({ persistState: true });
+    const toObject = mergeConfigUpdate(scalarFirst, { persistState: { storage: "local" } });
+    expect(toObject.persistState).toEqual({ storage: "local" });
+  });
+
+  it("replaces the headers map wholesale (stale keys do not survive)", () => {
+    const prev = base({ headers: { "X-A": "1", "X-B": "2" } });
+    const next = mergeConfigUpdate(prev, { headers: { "X-B": "3" } });
+    expect(next.headers).toEqual({ "X-B": "3" });
+    expect(next.headers?.["X-A"]).toBeUndefined();
+  });
+
+  it("replaces features.streamAnimation.plugins wholesale", () => {
+    const p1 = { name: "p1" } as StreamAnimationPlugin;
+    const p2 = { name: "p2" } as StreamAnimationPlugin;
+    const prev = base({ features: { streamAnimation: { plugins: { p1 } } } });
+    const next = mergeConfigUpdate(prev, { features: { streamAnimation: { plugins: { p2 } } } });
+    expect(next.features?.streamAnimation?.plugins).toEqual({ p2 });
+    expect(next.features?.streamAnimation?.plugins?.p1).toBeUndefined();
+  });
+
+  it("replaces storageAdapter wholesale (no hybrid: new adapter's absent save is not inherited)", () => {
+    const oldSave = vi.fn();
+    const oldLoad = vi.fn();
+    const newLoad = vi.fn();
+    const prev = base({ storageAdapter: { save: oldSave, load: oldLoad } });
+    const next = mergeConfigUpdate(prev, { storageAdapter: { load: newLoad } });
+    expect(next.storageAdapter?.load).toBe(newLoad);
+    expect(next.storageAdapter?.save).toBeUndefined();
+  });
+
+  it("resets a cleared key to its default value (launcher.title)", () => {
+    const prev = base({ launcher: { title: "Custom" } });
+    expect(prev.launcher?.title).toBe("Custom");
+    const next = mergeConfigUpdate(prev, { launcher: { title: undefined } });
+    expect(next.launcher?.title).toBe("Chat Assistant");
+    // Other launcher fields are untouched by the clear.
+    expect(next.launcher?.mountMode).toBe("floating");
+  });
+
+  it("leaves a cleared key unset when no default exists (launcher.closeButtonColor)", () => {
+    const prev = base({ launcher: { closeButtonColor: "#ff0000" } });
+    expect(prev.launcher?.closeButtonColor).toBe("#ff0000");
+    const next = mergeConfigUpdate(prev, { launcher: { closeButtonColor: undefined } });
+    // closeButtonColor is intentionally omitted from the launcher defaults.
+    expect(next.launcher?.closeButtonColor).toBeUndefined();
+  });
+
+  it("resets a cleared key with a truthy default (messageActions.showCopy resets to true)", () => {
+    const prev = base({ messageActions: { showCopy: false } });
+    expect(prev.messageActions?.showCopy).toBe(false);
+    const next = mergeConfigUpdate(prev, { messageActions: { showCopy: undefined } });
+    // The key must be absent (not own-undefined) so the default spread repopulates it.
+    expect(next.messageActions?.showCopy).toBe(true);
+  });
+
+  it("resets a cleared nested key with a truthy default (layout.header.showTitle resets to true)", () => {
+    const prev = base({ layout: { header: { showTitle: false } } });
+    expect(prev.layout?.header?.showTitle).toBe(false);
+    const next = mergeConfigUpdate(prev, { layout: { header: { showTitle: undefined } } });
+    expect(next.layout?.header?.showTitle).toBe(true);
+  });
+
+  it("preserves keys absent from the patch", () => {
+    const prev = base({ launcher: { title: "Keep", subtitle: "Sub" } });
+    const next = mergeConfigUpdate(prev, { launcher: { title: "New" } });
+    expect(next.launcher?.title).toBe("New");
+    expect(next.launcher?.subtitle).toBe("Sub");
+  });
+
+  it("deep-merges theme partials through update, preserving earlier theme overrides", () => {
+    const prev = base({ theme: { semantic: { colors: { primary: "#111111" } } } });
+    const next = mergeConfigUpdate(prev, { theme: { semantic: { colors: { secondary: "#222222" } } } });
+    expect(next.theme?.semantic?.colors?.primary).toBe("#111111");
+    expect(next.theme?.semantic?.colors?.secondary).toBe("#222222");
+  });
+
+  it("is idempotent: merging a config over its equal self is a no-op", () => {
+    const prev = base({ launcher: { clearChat: { backgroundColor: "#123456" } } });
+    const merged = mergeConfigUpdate(prev, { launcher: { title: "T" } });
+    const again = mergeConfigUpdate(merged, merged);
+    expect(again).toEqual(merged);
+  });
+});

package/src/utils/config-merge.ts

@@ -0,0 +1,61 @@
+import { mergeWithDefaults } from "../defaults";
+import type { AgentWidgetConfig, AgentWidgetConfigPatch } from "../types";
+
+// Same predicate as utils/deep-merge.ts: plain object, non-null, non-array.
+// Class instances and DOM nodes also pass here, so replace-leaf paths guard the
+// ones that must not be recursed into.
+const isPlainObject = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
+// Dotted paths whose plain-object value replaces wholesale instead of recursing.
+// - user-defined key maps: recursive merge would strand stale keys from the old value
+//   (headers, targetProviders, components, features.streamAnimation.plugins).
+// - implementation objects: partial merge splices two impls into a broken hybrid
+//   (agent, storageAdapter, voiceRecognition.provider.custom).
+const REPLACE_LEAF_PATHS = new Set<string>([
+  "headers",
+  "agent",
+  "storageAdapter",
+  "components",
+  "targetProviders",
+  "voiceRecognition.provider.custom",
+  "features.streamAnimation.plugins",
+]);
+
+// Recursive patch merge. A key merges recursively iff both previous and patch
+// values are plain objects and the path is not a replace-leaf; otherwise the
+// patch value replaces. A key present in the patch with value undefined is
+// deleted from the result (an own undefined property would shadow defaults in
+// mergeWithDefaults' spreads); absent keys are never visited, so they are
+// preserved. theme/darkTheme need no special case: the both-sides-plain-object
+// rule already reproduces mergeThemePartials/deepMerge (defaults.ts:225-236).
+const mergePatch = (previous: unknown, patch: unknown, path: string): unknown => {
+  if (!isPlainObject(previous) || !isPlainObject(patch)) return patch;
+  if (REPLACE_LEAF_PATHS.has(path)) return patch;
+
+  const result: Record<string, unknown> = { ...previous };
+  for (const key of Object.keys(patch)) {
+    if (patch[key] === undefined) {
+      delete result[key];
+      continue;
+    }
+    const childPath = path ? `${path}.${key}` : key;
+    result[key] = mergePatch(previous[key], patch[key], childPath);
+  }
+  return result;
+};
+
+/**
+ * Merge a config patch over the previous widget config with one consistent
+ * recursive policy, then re-apply mergeWithDefaults so a cleared
+ * (explicit-undefined) key resets to its default. The stored controller config
+ * is already post-mergeWithDefaults, so re-applying it is idempotent and keeps
+ * initial mount, live update, and rebuild on the same merge policy.
+ */
+export function mergeConfigUpdate(
+  previousConfig: AgentWidgetConfig,
+  patch: AgentWidgetConfigPatch
+): AgentWidgetConfig {
+  const merged = mergePatch(previousConfig, patch, "") as Partial<AgentWidgetConfig>;
+  return mergeWithDefaults(merged) as AgentWidgetConfig;
+}