@runtypelabs/persona 4.8.0 → 4.10.0

package/src/index-core.ts

@@ -5,6 +5,7 @@ import {
 
 export type {
   AgentWidgetConfig,
+  AgentWidgetConfigPatch,
   TargetResolver,
   ResolvedTarget,
   AgentWidgetFeatureFlags,
@@ -29,6 +30,25 @@ export type {
   // Context provider types (e.g. for config.contextProviders)
   AgentWidgetContextProvider,
   AgentWidgetContextProviderContext,
+  // Context mention types (e.g. for config.contextMentions)
+  AgentWidgetContextMentionConfig,
+  AgentWidgetContextMentionSource,
+  AgentWidgetContextMentionItem,
+  AgentWidgetContextMentionPayload,
+  AgentWidgetContextMentionRef,
+  AgentWidgetContextMentionSearchContext,
+  AgentWidgetContextMentionResolveContext,
+  AgentWidgetContextMentionMenuRenderContext,
+  AgentWidgetContextMentionItemRenderContext,
+  AgentWidgetContextMentionChipRenderContext,
+  AgentWidgetContextMentionTokenRenderContext,
+  // Per-mention LLM block formatter entry (config.contextMentions.llmFormat)
+  AgentWidgetMentionLlmEntry,
+  // Skills / slash-commands (config.contextMentions.triggers)
+  AgentWidgetMentionTriggerChannel,
+  AgentWidgetMentionTriggerPosition,
+  AgentWidgetContextMentionCommandContext,
+  AgentWidgetContextMentionComposerCapability,
   AgentWidgetCustomFetch,
   AgentWidgetSSEEventParser,
   AgentWidgetSSEEventResult,
@@ -226,6 +246,13 @@ export {
   fileToImagePart,
   validateImageFile
 } from "./utils/content";
+// Context mention helpers (for building config.contextMentions.sources)
+export {
+  defaultMentionFilter,
+  createStaticMentionSource,
+  createSlashCommandsSource,
+} from "./utils/mention-matcher";
+export type { SlashCommandDefinition } from "./utils/mention-matcher";
 export {
   collectEnrichedPageContext,
   formatEnrichedContext,

package/src/index-global.ts

@@ -137,3 +137,54 @@ setRuntypeTtsLoader(() => {
   }
   return import(/* @vite-ignore */ chunkUrl);
 });
+
+// ---------------------------------------------------------------------------
+// Deferred Context Mentions loading.
+//
+// This bundle is built with `./context-mentions-entry` external (see
+// `tsup.global.config.ts`): the mention controller/manager/menu runtime is kept
+// out of the CDN payload. Register a loader that imports the self-contained
+// `context-mentions.js` chunk from a sibling URL; the orchestrator calls it on
+// the first `@`/affordance-button interaction (and can prefetch on composer
+// focus) only when `contextMentions.enabled`. Same pattern as the chunks above.
+// ---------------------------------------------------------------------------
+
+import { setContextMentionsLoader } from "./context-mentions-loader";
+import { setContextMentionsInlineLoader } from "./context-mentions-inline-loader";
+
+setContextMentionsLoader(() => {
+  const chunkUrl = widgetScriptSrc?.replace(
+    /index\.global\.js($|\?)/,
+    "context-mentions.js$1",
+  );
+  if (!chunkUrl || chunkUrl === widgetScriptSrc) {
+    return Promise.reject(
+      new Error(
+        "Could not derive the context-mentions.js URL from the widget script URL " +
+          `(${widgetScriptSrc ?? "unavailable"}). Self-hosted deployments that ` +
+          "rename index.global.js should host context-mentions.js alongside it.",
+      ),
+    );
+  }
+  return import(/* @vite-ignore */ chunkUrl);
+});
+
+// Sibling loader for the inline-mention contenteditable chunk, loaded on composer
+// mount when `contextMentions.display === "inline"`. Same sibling-URL scheme.
+setContextMentionsInlineLoader(() => {
+  const chunkUrl = widgetScriptSrc?.replace(
+    /index\.global\.js($|\?)/,
+    "context-mentions-inline.js$1",
+  );
+  if (!chunkUrl || chunkUrl === widgetScriptSrc) {
+    return Promise.reject(
+      new Error(
+        "Could not derive the context-mentions-inline.js URL from the widget " +
+          `script URL (${widgetScriptSrc ?? "unavailable"}). Self-hosted ` +
+          "deployments that rename index.global.js should host " +
+          "context-mentions-inline.js alongside it.",
+      ),
+    );
+  }
+  return import(/* @vite-ignore */ chunkUrl);
+});

package/src/markdown-parsers-loader.ts

@@ -1,3 +1,4 @@
+import { createChunkLoader } from "./utils/chunk-loader";
 import type { Marked } from "marked";
 import type DOMPurify from "dompurify";
 
@@ -6,19 +7,22 @@ export type MarkdownParsersModule = {
   DOMPurify: typeof DOMPurify;
 };
 
-let loader: (() => Promise<MarkdownParsersModule>) | null = null;
-let moduleCache: MarkdownParsersModule | null = null;
-let loadPromise: Promise<MarkdownParsersModule> | null = null;
+// Memoization + rejection-retry semantics live in `createChunkLoader`. The
+// ESM/CJS fallback imports `./markdown-parsers-entry` directly; the IIFE/CDN
+// build registers a loader that fetches the `markdown-parsers.js` chunk.
+const { setLoader, load, provide, getSync } =
+  createChunkLoader<MarkdownParsersModule>({
+    fallbackImport: () => import("./markdown-parsers-entry"),
+  });
 
 // Surfaces that want to self-heal when the lazy `markdown-parsers.js` chunk
 // lands. See `onMarkdownParsersReady` below for why this is centralized.
 const readySubscribers = new Set<() => void>();
 
-// Flip `moduleCache` and fan out to everyone waiting to re-render, exactly once
-// per subscriber. Called from BOTH the eager (`provideMarkdownParsers`) and lazy
+// Fan out to everyone waiting to re-render, exactly once per subscriber.
+// Called from BOTH the eager (`provideMarkdownParsers`) and lazy
 // (`loadMarkdownParsers`) paths so a subscriber can't miss the transition.
-const markParsersReady = (mod: MarkdownParsersModule): MarkdownParsersModule => {
-  moduleCache = mod;
+const notifyParsersReady = (): void => {
   // Snapshot + clear first: fire-once semantics, and a callback that re-subscribes
   // (it won't — `onMarkdownParsersReady` no-ops once ready) can't loop.
   const subs = [...readySubscribers];
@@ -31,11 +35,25 @@ const markParsersReady = (mod: MarkdownParsersModule): MarkdownParsersModule =>
       /* subscriber threw: swallow so the remaining re-renders still run */
     }
   }
-  return mod;
 };
 
-export const setMarkdownParsersLoader = (l: () => Promise<MarkdownParsersModule>) => {
-  loader = l;
+export const setMarkdownParsersLoader = setLoader;
+
+// On a failed chunk load (404, ad blocker, offline), `createChunkLoader`
+// resets its cached promise so a later call retries. Pending subscribers are
+// KEPT — a surface that rendered escaped during the failed attempt must still
+// heal when a retry (kicked by a new subscriber or an explicit
+// loadMarkdownParsers() call) succeeds; dropping them left that surface
+// escaped forever after a transient failure. They're only retained while the
+// parsers stay unloaded — success releases them (fire-once in
+// `notifyParsersReady`), and callers can unsubscribe.
+export const loadMarkdownParsers = (): Promise<MarkdownParsersModule> => {
+  const cached = getSync();
+  if (cached) return Promise.resolve(cached);
+  return load().then((mod) => {
+    notifyParsersReady();
+    return mod;
+  });
 };
 
 /**
@@ -58,12 +76,13 @@ export const setMarkdownParsersLoader = (l: () => Promise<MarkdownParsersModule>
  * Fires at most once per subscription.
  */
 export const onMarkdownParsersReady = (cb: () => void): (() => void) => {
-  if (moduleCache) return () => {};
+  if (getSync()) return () => {};
   readySubscribers.add(cb);
   // Ensure the chunk is actually being fetched; harmless if already in flight.
   // Swallow rejection here — on failure the subscriber stays registered (see
-  // `onLoadFailure`) and the surface keeps its escaped fallback until a retry
-  // succeeds; this catch only avoids an unhandled rejection.
+  // the note on `loadMarkdownParsers`) and the surface keeps its escaped
+  // fallback until a retry succeeds; this catch only avoids an unhandled
+  // rejection.
   void loadMarkdownParsers().catch(() => {});
   return () => {
     readySubscribers.delete(cb);
@@ -79,36 +98,8 @@ export const onMarkdownParsersReady = (cb: () => void): (() => void) => {
  * it lazy-loads the `markdown-parsers.js` chunk instead.
  */
 export const provideMarkdownParsers = (mod: MarkdownParsersModule): void => {
-  markParsersReady(mod);
+  provide(mod);
+  notifyParsersReady();
 };
 
-// On a failed chunk load (404, ad blocker, offline), don't cache the rejected
-// promise: reset it so a later subscribe/load call can retry. Pending
-// subscribers are KEPT — a surface that rendered escaped during the failed
-// attempt must still heal when a retry (kicked by a new subscriber or an
-// explicit loadMarkdownParsers() call) succeeds; dropping them here left that
-// surface escaped forever after a transient failure. They're only retained
-// while the parsers stay unloaded — success releases them (fire-once in
-// `markParsersReady`), and callers can unsubscribe. On a permanently failing
-// setup they persist for the page's life, which is the price of healing.
-// Re-throw so awaiters of loadMarkdownParsers() still observe the rejection.
-const onLoadFailure = (err: unknown): never => {
-  loadPromise = null;
-  throw err;
-};
-
-export const loadMarkdownParsers = (): Promise<MarkdownParsersModule> => {
-  if (moduleCache) return Promise.resolve(moduleCache);
-  if (loadPromise) return loadPromise;
-  if (!loader) {
-    // Fallback for regular ESM/CJS consumers (they import directly)
-    loadPromise = import("./markdown-parsers-entry").then(markParsersReady, onLoadFailure);
-    return loadPromise;
-  }
-  loadPromise = loader().then(markParsersReady, onLoadFailure);
-  return loadPromise;
-};
-
-export const getMarkdownParsersSync = (): MarkdownParsersModule | null => {
-  return moduleCache;
-};
+export const getMarkdownParsersSync = getSync;

package/src/plugin-kit.test.ts

@@ -188,6 +188,46 @@ describe("createPopover", () => {
     expect(content.getRootNode()).toBe(shadow);
   });
 
+  it("anchors vertically to a verticalOffset when placement is top-start", () => {
+    const { anchor, content } = setup();
+    anchor.getBoundingClientRect = () =>
+      ({
+        left: 100,
+        right: 400,
+        top: 200,
+        bottom: 260,
+        width: 300,
+        height: 60,
+        x: 100,
+        y: 200,
+        toJSON: () => ({}),
+      }) as DOMRect;
+    content.getBoundingClientRect = () =>
+      ({
+        width: 180,
+        height: 100,
+        left: 0,
+        right: 180,
+        top: 0,
+        bottom: 100,
+        x: 0,
+        y: 0,
+        toJSON: () => ({}),
+      }) as DOMRect;
+
+    const popover = createPopover({
+      anchor,
+      content,
+      placement: "top-start",
+      offset: 6,
+      verticalOffset: () => 40,
+    });
+    popover.open();
+
+    // anchorTop = 200 + 40 = 240 → top = 240 - 6 - 100 = 134
+    expect(content.style.top).toBe("134px");
+  });
+
   it("destroy removes content and detaches listeners", () => {
     vi.useFakeTimers();
     const onDismiss = vi.fn();

package/src/plugin-kit.ts

@@ -117,6 +117,23 @@ export interface PopoverOptions {
   offset?: number;
   /** Set `content`'s `min-width` to the anchor's width. Default `false`. */
   matchAnchorWidth?: boolean;
+  /**
+   * Horizontal anchoring override for `*-start` placements. Returns the desired
+   * left offset in px measured from the anchor's LEFT edge (e.g. the `@` trigger's
+   * x within the composer), or `null` to left-align with the anchor as usual. When
+   * this option is present the content is content-sized and capped to the anchor's
+   * width, and the resolved left is clamped so the content never overflows the
+   * anchor's left/right edges (Slack-style: a near-right trigger shifts the menu
+   * left to fit). Omit it entirely for plain anchor-left/right placement.
+   */
+  horizontalOffset?: () => number | null;
+  /**
+   * Vertical anchoring override for `top-*` placements. Returns the desired
+   * anchor point's top offset in px measured from the anchor's TOP edge (e.g.
+   * the trigger line's top within the composer), or `null` to use the anchor's
+   * top edge as usual.
+   */
+  verticalOffset?: () => number | null;
   /**
    * Inline `z-index` for `content`. Default `2147483000` so it overlays the rest
    * of the widget. Pass `null` to leave z-index to your own CSS.
@@ -175,6 +192,8 @@ export function createPopover(options: PopoverOptions): PopoverHandle {
     placement = "bottom-start",
     offset = 6,
     matchAnchorWidth = false,
+    horizontalOffset,
+    verticalOffset,
     zIndex = 2147483000,
     onOpen,
     onDismiss,
@@ -189,16 +208,31 @@ export function createPopover(options: PopoverOptions): PopoverHandle {
     const rect = anchor.getBoundingClientRect();
     content.style.position = "fixed";
     if (matchAnchorWidth) content.style.minWidth = `${rect.width}px`;
+    // Trigger-anchored mode: content is sized to its own contents but never wider
+    // than the composer, so it can shift horizontally within the composer's span.
+    if (horizontalOffset) content.style.maxWidth = `${rect.width}px`;
+
+    // Single content measurement per reposition (after width constraints apply).
+    const contentRect = content.getBoundingClientRect();
 
+    const offY = verticalOffset?.() ?? null;
+    const anchorTop = offY != null ? rect.top + offY : rect.top;
     const top =
       placement === "top-start" || placement === "top-end"
-        ? rect.top - offset - content.getBoundingClientRect().height
+        ? anchorTop - offset - contentRect.height
         : rect.bottom + offset;
 
-    const left =
-      placement === "bottom-end" || placement === "top-end"
-        ? rect.right - content.getBoundingClientRect().width
-        : rect.left;
+    const isEnd = placement === "bottom-end" || placement === "top-end";
+    // Default: anchor left (or anchor right for `*-end`). Trigger-anchored mode
+    // (offset present and non-null) overrides with the clamped trigger position so
+    // the menu never overflows the anchor's edges — a near-right trigger shifts it
+    // left to fit (Slack-style). A null offset falls back to the default.
+    let left = isEnd ? rect.right - contentRect.width : rect.left;
+    const off = horizontalOffset?.() ?? null;
+    if (off != null) {
+      const maxLeft = Math.max(rect.left, rect.right - contentRect.width);
+      left = Math.min(Math.max(rect.left + off, rect.left), maxLeft);
+    }
 
     content.style.top = `${top}px`;
     content.style.left = `${left}px`;

package/src/runtime/init-update-reset.test.ts

@@ -0,0 +1,81 @@
+// @vitest-environment jsdom
+
+// End-to-end handle.update() through the REAL ui module (init.test.ts mocks it,
+// so it cannot see the controller's own patch merge). Regression: explicit
+// undefined resets must reach the controller, not be materialized as absent
+// keys by the handle's pre-merge.
+
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { initAgentWidget } from "./init";
+
+describe("handle.update explicit-undefined reset reaches the controller", () => {
+  afterEach(() => {
+    document.body.innerHTML = "";
+    vi.restoreAllMocks();
+  });
+
+  it("round-trips artifact pane appearance seamless -> panel via explicit undefined", () => {
+    window.scrollTo = vi.fn();
+    document.body.innerHTML = `<div id="target"></div>`;
+
+    const handle = initAgentWidget({
+      target: "#target",
+      config: {
+        apiUrl: "https://api.example.com/chat",
+        launcher: { enabled: false },
+        features: { artifacts: { enabled: true } },
+      },
+    });
+
+    const root = () => document.querySelector<HTMLElement>("[data-persona-root]")!;
+    expect(root().classList.contains("persona-artifact-appearance-panel")).toBe(true);
+
+    handle.update({
+      features: {
+        artifacts: {
+          layout: { paneAppearance: "seamless", splitGap: "0", paneShadow: "none" },
+        },
+      },
+    });
+    expect(root().classList.contains("persona-artifact-appearance-seamless")).toBe(true);
+
+    handle.update({
+      features: {
+        artifacts: {
+          layout: { paneAppearance: undefined, splitGap: undefined, paneShadow: undefined },
+        },
+      },
+    });
+    expect(root().classList.contains("persona-artifact-appearance-panel")).toBe(true);
+    expect(root().classList.contains("persona-artifact-appearance-seamless")).toBe(false);
+    expect(root().style.getPropertyValue("--persona-artifact-pane-shadow")).toBe("");
+
+    handle.destroy();
+  });
+
+  it("handle and controller stored configs converge on the same merged result", () => {
+    window.scrollTo = vi.fn();
+    document.body.innerHTML = `<div id="target"></div>`;
+
+    const handle = initAgentWidget({
+      target: "#target",
+      config: {
+        apiUrl: "https://api.example.com/chat",
+        launcher: { enabled: false, clearChat: { backgroundColor: "#123456" } },
+      },
+    });
+
+    // Sibling override must survive an unrelated patch in BOTH layers: the
+    // controller renders it now, and the handle's stored config must carry it
+    // into a mount-mode rebuild. tooltipText also renames the aria-label.
+    handle.update({ launcher: { clearChat: { tooltipText: "Wipe" } } });
+    const clear = () => document.querySelector<HTMLButtonElement>('button[aria-label="Wipe"]')!;
+    expect(clear().style.backgroundColor).toBe("rgb(18, 52, 86)");
+
+    handle.update({ launcher: { mountMode: "docked" } });
+    expect(clear().style.backgroundColor).toBe("rgb(18, 52, 86)");
+
+    handle.destroy();
+  });
+});

package/src/runtime/init.test.ts

@@ -483,3 +483,65 @@ describe("initAgentWidget docked mode", () => {
     handleB.destroy();
   });
 });
+
+describe("initAgentWidget update merge policy", () => {
+  beforeEach(() => {
+    document.body.innerHTML = "";
+    createAgentExperienceMock.mockReset();
+  });
+
+  it("passes the raw patch to the controller so explicit-undefined resets survive", async () => {
+    const { initAgentWidget } = await import("./init");
+    document.body.innerHTML = `<div id="target"></div>`;
+
+    let controllerRef: ReturnType<typeof createMockController> | undefined;
+    createAgentExperienceMock.mockImplementation((_mount, config) => {
+      controllerRef = createMockController(config);
+      return controllerRef;
+    });
+
+    const handle = initAgentWidget({
+      target: "#target",
+      config: {
+        apiUrl: "https://api.example.com/chat",
+        launcher: { enabled: false, clearChat: { backgroundColor: "#123456" } },
+      },
+    });
+
+    // The merged config materializes explicit-undefined as absence, which the
+    // controller's patch merge would preserve; only the raw patch carries resets.
+    const patch = { launcher: { clearChat: { tooltipText: "Clear" } } };
+    handle.update(patch);
+
+    const passed = controllerRef!.update.mock.calls.at(-1)?.[0] as any;
+    expect(passed).toBe(patch);
+
+    handle.destroy();
+  });
+
+  it("retains prior nested overrides when a mount-mode change rebuilds the controller", async () => {
+    const { initAgentWidget } = await import("./init");
+    document.body.innerHTML = `<div id="target"></div>`;
+
+    createAgentExperienceMock.mockImplementation((_mount, config) => createMockController(config));
+
+    const handle = initAgentWidget({
+      target: "#target",
+      config: {
+        apiUrl: "https://api.example.com/chat",
+        launcher: { enabled: false, clearChat: { backgroundColor: "#123456" } },
+      },
+    });
+
+    // Patch a sibling, then flip the mount mode to force a rebuild.
+    handle.update({ launcher: { clearChat: { tooltipText: "Clear" } } });
+    handle.update({ launcher: { mountMode: "docked" } });
+
+    const rebuildConfig = createAgentExperienceMock.mock.calls.at(-1)?.[1] as any;
+    expect(rebuildConfig.launcher.clearChat.backgroundColor).toBe("#123456");
+    expect(rebuildConfig.launcher.clearChat.tooltipText).toBe("Clear");
+    expect(rebuildConfig.launcher.mountMode).toBe("docked");
+
+    handle.destroy();
+  });
+});

package/src/runtime/init.ts

@@ -1,6 +1,7 @@
 import { createAgentExperience, AgentWidgetController } from "../ui";
-import { AgentWidgetConfig as _AgentWidgetConfig, AgentWidgetInitOptions, AgentWidgetEvent as _AgentWidgetEvent } from "../types";
+import { AgentWidgetConfig as _AgentWidgetConfig, AgentWidgetConfigPatch, AgentWidgetInitOptions, AgentWidgetEvent as _AgentWidgetEvent } from "../types";
 import { isComposerBarMountMode, isDockedMountMode } from "../utils/dock";
+import { mergeConfigUpdate } from "../utils/config-merge";
 import { createWidgetHostLayout } from "./host-layout";
 
 const ensureTarget = (target: string | HTMLElement): HTMLElement => {
@@ -126,19 +127,8 @@ export const initAgentWidget = (
   };
 
   const handleBase = {
-    update(nextConfig: _AgentWidgetConfig) {
-      const mergedConfig = {
-        ...config,
-        ...nextConfig,
-        launcher: {
-          ...(config?.launcher ?? {}),
-          ...(nextConfig?.launcher ?? {}),
-          dock: {
-            ...(config?.launcher?.dock ?? {}),
-            ...(nextConfig?.launcher?.dock ?? {}),
-          },
-        },
-      } as _AgentWidgetConfig;
+    update(nextConfig: AgentWidgetConfigPatch) {
+      const mergedConfig = mergeConfigUpdate(config ?? ({} as _AgentWidgetConfig), nextConfig);
       const previousDocked = isDockedMountMode(config);
       const nextDocked = isDockedMountMode(mergedConfig);
       const previousComposerBar = isComposerBarMountMode(config);
@@ -151,6 +141,9 @@ export const initAgentWidget = (
 
       config = mergedConfig;
       hostLayout.updateConfig(config);
+      // Pass the raw patch: mergedConfig materializes explicit-undefined resets
+      // as absent keys, which the controller's patch merge would preserve
+      // instead of clearing. Both layers share mergeConfigUpdate, so they converge.
       controller.update(nextConfig);
       syncHostState();
     },