@runtypelabs/persona 4.7.0 → 4.9.0

package/src/defaults.ts

@@ -144,6 +144,7 @@ export const DEFAULT_WIDGET_CONFIG: Partial<AgentWidgetConfig> = {
       collapsedMode: "tool-call",
       activePreview: false,
       grouped: false,
+      groupedMode: "stack",
       previewMaxLines: 3,
       expandable: true,
       loadingAnimation: "none",

package/src/generated/runtype-openapi-contract.ts

@@ -22,6 +22,7 @@ export type RuntypeExecutionStreamEvent = ({
   totalSteps?: number;
   type: "execution_start";
 }) | ({
+  claudeManagedAgentId?: string;
   completedAt?: string;
   durationMs?: number;
   executionId: string;
@@ -66,6 +67,15 @@ export type RuntypeExecutionStreamEvent = ({
   completedAt?: string;
   content?: string;
   cost?: number;
+  estimatedContextBreakdown?: {
+  categories: Record<string, {
+  chars: number;
+  estimatedTokens: number;
+}>;
+  contextWindowSize?: number;
+  estimatedTotalTokens: number;
+  estimatedUtilizationPercent?: number;
+};
   executionId: string;
   fallback?: {
   attempts: Array<{
@@ -103,6 +113,7 @@ export type RuntypeExecutionStreamEvent = ({
   type: "step_start";
 } | ({
   completedAt?: string;
+  cost?: number;
   durationMs?: number;
   error?: string;
   executionId: string;
@@ -208,6 +219,11 @@ export type RuntypeExecutionStreamEvent = ({
   artifactType: "markdown" | "component";
   component?: string;
   executionId?: string;
+  file?: {
+  language?: string;
+  mimeType: string;
+  path: string;
+};
   id: string;
   seq?: number;
   title?: string;
@@ -316,6 +332,14 @@ export type RuntypeExecutionStreamEvent = ({
   awaitReason?: string;
   awaitedAt?: string;
   crawlId?: string;
+  elicitation?: {
+  message: string;
+  mode: "form" | "url";
+  pauseCount?: number;
+  requestedSchema?: Record<string, unknown>;
+  serverName?: string;
+  url?: string;
+};
   executionId: string;
   origin?: "webmcp" | "sdk";
   pageOrigin?: string;
@@ -416,6 +440,14 @@ export type RuntypeFlowSSEEvent = {
   awaitReason?: string;
   awaitedAt: string;
   crawlId?: string;
+  elicitation?: {
+  message: string;
+  mode: "form" | "url";
+  pauseCount?: number;
+  requestedSchema?: Record<string, unknown>;
+  serverName?: string;
+  url?: string;
+};
   executionId?: string;
   flowId: string;
   origin?: "webmcp" | "sdk";
@@ -466,7 +498,7 @@ export type RuntypeFlowSSEEvent = {
   completedAt?: string;
   duration?: number;
   durationMs?: number;
-  error?: string;
+  error?: string | null;
   executionId?: string;
   executionTime?: number;
   id?: string;
@@ -510,13 +542,21 @@ export type RuntypeFlowSSEEvent = {
   totalSteps: number;
   type: "step_skip";
   when: string;
-} | {
+} | ({
+  elicitation?: {
+  message: string;
+  mode: "form" | "url";
+  pauseCount?: number;
+  requestedSchema?: Record<string, unknown>;
+  serverName?: string;
+  url?: string;
+};
   executionId?: string;
   reason?: string;
   seq?: number;
   type: "step_await";
   [key: string]: unknown;
-} | ({
+}) | ({
   agentContext?: {
   executionId: string;
   iteration: number;
@@ -735,6 +775,18 @@ export type RuntypeClientChatRequest = {
 export type RuntypeClientChatStreamEvent = RuntypeExecutionStreamEvent;
 
 export type RuntypeClientResumeRequest = {
+  clientTools?: Array<{
+  description: string;
+  name: string;
+  origin?: "webmcp" | "sdk";
+  pageOrigin?: string;
+  parametersSchema: {
+  type: "object";
+  [key: string]: unknown;
+};
+  untrustedContentHint?: boolean;
+}>;
+  clientToolsFingerprint?: string;
   executionId: string;
   messages?: Array<{
   content: string | (Array<{

package/src/index-core.ts

@@ -10,8 +10,12 @@ export type {
   AgentWidgetFeatureFlags,
   AgentWidgetArtifactsFeature,
   AgentWidgetArtifactsLayoutConfig,
+  PersonaArtifactDisplayMode,
   PersonaArtifactKind,
   PersonaArtifactRecord,
+  PersonaArtifactActionContext,
+  PersonaArtifactStatusLabelContext,
+  PersonaArtifactCustomAction,
   PersonaArtifactManualUpsert,
   ArtifactConfigPayload,
   AgentWidgetInitOptions,
@@ -25,6 +29,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,
@@ -188,6 +211,17 @@ export {
   createDirectivePostprocessor
 } from "./postprocessors";
 export type { MarkdownProcessorOptions } from "./postprocessors";
+// Markdown parser-readiness escape hatch. On the IIFE/CDN build `marked` +
+// `DOMPurify` load lazily, so content injected right after init can render as
+// escaped plain text until the chunk resolves. Hosts can `await
+// loadMarkdownParsers()` before injecting, or `onMarkdownParsersReady(cb)` to be
+// told when they land (both resolve/no-op instantly on the npm build, where the
+// parsers are bundled eagerly).
+export {
+  loadMarkdownParsers,
+  onMarkdownParsersReady
+} from "./markdown-parsers-loader";
+export type { MarkdownParsersModule } from "./markdown-parsers-loader";
 export {
   createDefaultSanitizer,
   resolveSanitizer
@@ -211,6 +245,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,
@@ -361,7 +402,11 @@ export type {
 
 // Component system exports
 export { componentRegistry } from "./components/registry";
-export type { ComponentRenderer, ComponentContext } from "./components/registry";
+export type {
+  ComponentRenderer,
+  ComponentContext,
+  ComponentRegistrationOptions
+} from "./components/registry";
 export {
   createComponentStreamParser,
   isComponentDirectiveType

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/index.ts

@@ -37,3 +37,11 @@ export type {
   DemoCarouselOptions,
   DemoCarouselHandle
 } from "./components/demo-carousel";
+
+// Accessible roving-tabindex tablist helper for custom artifact tab bars
+// (features.artifacts.renderTabBar).
+export { createRovingTablist } from "./utils/roving-tablist";
+export type {
+  RovingTablistController,
+  RovingTablistOptions
+} from "./utils/roving-tablist";

package/src/markdown-parsers-loader.test.ts

@@ -0,0 +1,158 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import type { MarkdownParsersModule } from "./markdown-parsers-loader";
+
+/**
+ * Tests for the parser-ready subscription registry.
+ *
+ * The loader holds module-level singleton state (`moduleCache`, subscribers), and
+ * `vitest.setup.ts` eager-provides parsers into the shared graph — which would make
+ * `onMarkdownParsersReady` no-op everywhere. So each test imports a FRESH copy of
+ * the loader via `vi.resetModules()` + dynamic import, starting from the unloaded
+ * (IIFE/CDN) state, and drives the transition itself.
+ */
+
+// A stand-in parsers module; the registry never touches its fields.
+const FAKE_PARSERS = {} as unknown as MarkdownParsersModule;
+
+const freshLoader = async () => {
+  vi.resetModules();
+  return import("./markdown-parsers-loader");
+};
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe("onMarkdownParsersReady", () => {
+  it("fires a pending subscriber once when the lazy chunk resolves", async () => {
+    const loader = await freshLoader();
+    loader.setMarkdownParsersLoader(() => Promise.resolve(FAKE_PARSERS));
+
+    const cb = vi.fn();
+    loader.onMarkdownParsersReady(cb);
+    expect(cb).not.toHaveBeenCalled(); // not yet: chunk not loaded
+
+    await loader.loadMarkdownParsers();
+    expect(cb).toHaveBeenCalledTimes(1);
+  });
+
+  it("kicks the load itself so a lone surface still heals", async () => {
+    const loader = await freshLoader();
+    const load = vi.fn(() => Promise.resolve(FAKE_PARSERS));
+    loader.setMarkdownParsersLoader(load);
+
+    const cb = vi.fn();
+    // No explicit loadMarkdownParsers() call — subscribing must trigger it.
+    loader.onMarkdownParsersReady(cb);
+    await vi.waitFor(() => expect(cb).toHaveBeenCalledTimes(1));
+    expect(load).toHaveBeenCalledTimes(1);
+  });
+
+  it("does not fire (and returns a no-op) when parsers are already loaded", async () => {
+    const loader = await freshLoader();
+    loader.provideMarkdownParsers(FAKE_PARSERS); // eager/ESM steady state
+
+    const cb = vi.fn();
+    const unsub = loader.onMarkdownParsersReady(cb);
+    await Promise.resolve();
+    expect(cb).not.toHaveBeenCalled();
+    expect(() => unsub()).not.toThrow();
+  });
+
+  it("unsubscribe prevents the callback from firing", async () => {
+    const loader = await freshLoader();
+    loader.setMarkdownParsersLoader(() => Promise.resolve(FAKE_PARSERS));
+
+    const cb = vi.fn();
+    const unsub = loader.onMarkdownParsersReady(cb);
+    unsub();
+
+    await loader.loadMarkdownParsers();
+    expect(cb).not.toHaveBeenCalled();
+  });
+
+  it("fires each subscriber exactly once (no re-fire on a later load call)", async () => {
+    const loader = await freshLoader();
+    loader.setMarkdownParsersLoader(() => Promise.resolve(FAKE_PARSERS));
+
+    const cb = vi.fn();
+    loader.onMarkdownParsersReady(cb);
+
+    await loader.loadMarkdownParsers();
+    await loader.loadMarkdownParsers(); // cached; must not re-notify
+    expect(cb).toHaveBeenCalledTimes(1);
+  });
+
+  it("provideMarkdownParsers (eager) flushes pending subscribers", async () => {
+    const loader = await freshLoader();
+    // Subscribe while still unloaded, then have the eager path provide.
+    loader.setMarkdownParsersLoader(() => new Promise(() => {})); // never resolves
+    const cb = vi.fn();
+    loader.onMarkdownParsersReady(cb);
+
+    loader.provideMarkdownParsers(FAKE_PARSERS);
+    expect(cb).toHaveBeenCalledTimes(1);
+  });
+
+  it("keeps pending subscribers across a failed chunk load so a successful retry heals them", async () => {
+    const loader = await freshLoader();
+    let attempt = 0;
+    loader.setMarkdownParsersLoader(() => {
+      attempt += 1;
+      return attempt === 1
+        ? Promise.reject(new Error("chunk 404"))
+        : Promise.resolve(FAKE_PARSERS);
+    });
+
+    const cb = vi.fn();
+    loader.onMarkdownParsersReady(cb);
+    await expect(loader.loadMarkdownParsers()).rejects.toThrow("chunk 404");
+    // Failed attempt: not fired, but still registered.
+    expect(cb).not.toHaveBeenCalled();
+
+    // A later subscribe re-triggers the load (rejected promise was not cached)
+    // and the retry heals BOTH the new subscriber and the one that rendered
+    // escaped during the failed attempt.
+    const cb2 = vi.fn();
+    loader.onMarkdownParsersReady(cb2);
+    await vi.waitFor(() => expect(cb2).toHaveBeenCalledTimes(1));
+    expect(cb).toHaveBeenCalledTimes(1);
+    expect(attempt).toBe(2);
+  });
+
+  it("unsubscribing after a failed load still prevents firing on the retry", async () => {
+    const loader = await freshLoader();
+    let attempt = 0;
+    loader.setMarkdownParsersLoader(() => {
+      attempt += 1;
+      return attempt === 1
+        ? Promise.reject(new Error("chunk 404"))
+        : Promise.resolve(FAKE_PARSERS);
+    });
+
+    const cb = vi.fn();
+    const unsub = loader.onMarkdownParsersReady(cb);
+    await expect(loader.loadMarkdownParsers()).rejects.toThrow("chunk 404");
+    unsub();
+
+    await loader.loadMarkdownParsers();
+    expect(cb).not.toHaveBeenCalled();
+    expect(attempt).toBe(2);
+  });
+
+  it("one throwing subscriber does not starve the others", async () => {
+    const loader = await freshLoader();
+    loader.setMarkdownParsersLoader(() => Promise.resolve(FAKE_PARSERS));
+
+    const boom = vi.fn(() => {
+      throw new Error("subscriber blew up");
+    });
+    const ok = vi.fn();
+    loader.onMarkdownParsersReady(boom);
+    loader.onMarkdownParsersReady(ok);
+
+    await loader.loadMarkdownParsers();
+    expect(boom).toHaveBeenCalledTimes(1);
+    expect(ok).toHaveBeenCalledTimes(1);
+  });
+});

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,12 +7,86 @@ 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>();
+
+// 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 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];
+  readySubscribers.clear();
+  for (const cb of subs) {
+    // One bad subscriber must not starve the others (or leave messages escaped).
+    try {
+      cb();
+    } catch {
+      /* subscriber threw: swallow so the remaining re-renders still run */
+    }
+  }
+};
+
+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;
+  });
+};
 
-export const setMarkdownParsersLoader = (l: () => Promise<MarkdownParsersModule>) => {
-  loader = l;
+/**
+ * Register `cb` to run once the markdown parsers (marked + DOMPurify) become
+ * available, i.e. when the lazy `markdown-parsers.js` chunk resolves on the
+ * IIFE/CDN build. Returns an unsubscribe function.
+ *
+ * This exists so every markdown render surface (chat messages, artifact pane,
+ * and any future one) shares a SINGLE self-heal path instead of each wiring its
+ * own `loadMarkdownParsers().then(reRender)`. Before this, a new surface that
+ * forgot to do that rendered escaped plain text until a user interaction forced
+ * a re-render — the recurring first-render bug (chat messages, then the artifact
+ * pane) this centralizes away.
+ *
+ * If the parsers are ALREADY loaded, `cb` is not scheduled and a no-op
+ * unsubscribe is returned: the caller's first render already used real markdown,
+ * so there is nothing to heal (this is the ESM/CJS build's steady state, and the
+ * CDN build's state after the first chunk load). Registering also kicks the load
+ * so a surface that renders before anything else triggers it still heals.
+ * Fires at most once per subscription.
+ */
+export const onMarkdownParsersReady = (cb: () => void): (() => void) => {
+  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
+  // 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);
+  };
 };
 
 /**
@@ -23,27 +98,8 @@ export const setMarkdownParsersLoader = (l: () => Promise<MarkdownParsersModule>
  * it lazy-loads the `markdown-parsers.js` chunk instead.
  */
 export const provideMarkdownParsers = (mod: MarkdownParsersModule): void => {
-  moduleCache = mod;
-};
-
-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((mod) => {
-      moduleCache = mod;
-      return mod;
-    });
-    return loadPromise;
-  }
-  loadPromise = loader().then((mod) => {
-    moduleCache = mod;
-    return mod;
-  });
-  return loadPromise;
+  provide(mod);
+  notifyParsersReady();
 };
 
-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`;