@runtypelabs/persona 4.7.0 → 4.9.0

package/src/runtime/host-layout.test.ts

@@ -527,4 +527,167 @@ describe("createWidgetHostLayout docked", () => {
       layout.destroy();
     });
   });
+
+  describe("detached docked", () => {
+    it("leaves the dock slot flush when detachedPanel is unset", () => {
+      const parent = document.createElement("div");
+      document.body.appendChild(parent);
+      const target = document.createElement("div");
+      parent.appendChild(target);
+
+      const layout = createWidgetHostLayout(target, {
+        launcher: {
+          mountMode: "docked",
+          autoExpand: true,
+          dock: { width: "320px" },
+        },
+      });
+
+      const dockSlot = layout.shell?.querySelector<HTMLElement>('[data-persona-dock-role="panel"]');
+      expect(dockSlot?.style.padding).toBe("");
+      expect(dockSlot?.style.background).toBe("");
+
+      layout.destroy();
+    });
+
+    it("pads the dock slot with the default inset and canvas when detached", () => {
+      const parent = document.createElement("div");
+      document.body.appendChild(parent);
+      const target = document.createElement("div");
+      parent.appendChild(target);
+
+      const layout = createWidgetHostLayout(target, {
+        launcher: {
+          mountMode: "docked",
+          autoExpand: true,
+          detachedPanel: true,
+          dock: { width: "320px" },
+        },
+      });
+
+      const dockSlot = layout.shell?.querySelector<HTMLElement>('[data-persona-dock-role="panel"]');
+      expect(dockSlot?.style.padding).toBe("16px");
+      expect(dockSlot?.style.background).toBe("transparent");
+      expect(dockSlot?.style.boxSizing).toBe("border-box");
+
+      layout.destroy();
+    });
+
+    it("resolves detached inset and canvas from panel theme tokens", () => {
+      const parent = document.createElement("div");
+      document.body.appendChild(parent);
+      const target = document.createElement("div");
+      parent.appendChild(target);
+
+      const layout = createWidgetHostLayout(target, {
+        launcher: {
+          mountMode: "docked",
+          autoExpand: true,
+          detachedPanel: true,
+          dock: { width: "320px" },
+        },
+        theme: {
+          components: { panel: { inset: "24px", canvasBackground: "#eee" } },
+        },
+      });
+
+      const dockSlot = layout.shell?.querySelector<HTMLElement>('[data-persona-dock-role="panel"]');
+      expect(dockSlot?.style.padding).toBe("24px");
+      expect(dockSlot?.style.background).toBe("rgb(238, 238, 238)");
+
+      layout.destroy();
+    });
+
+    it("shrinks the emerge host by the inset so it fits the padded slot", () => {
+      const parent = document.createElement("div");
+      document.body.appendChild(parent);
+      const target = document.createElement("div");
+      parent.appendChild(target);
+
+      const layout = createWidgetHostLayout(target, {
+        launcher: {
+          mountMode: "docked",
+          autoExpand: true,
+          detachedPanel: true,
+          dock: { width: "320px", reveal: "emerge" },
+        },
+      });
+
+      const host = layout.shell?.querySelector<HTMLElement>('[data-persona-dock-role="host"]');
+      // jsdom simplifies the calc expression (320px - 2 * 16px).
+      expect(host?.style.width).toBe("calc(288px)");
+
+      layout.destroy();
+    });
+
+    it("resolves a percentage emerge width to px before subtracting the inset", () => {
+      const parent = document.createElement("div");
+      document.body.appendChild(parent);
+      const target = document.createElement("div");
+      parent.appendChild(target);
+
+      const layout = createWidgetHostLayout(target, {
+        launcher: {
+          mountMode: "docked",
+          autoExpand: true,
+          detachedPanel: true,
+          dock: { width: "50%", reveal: "emerge" },
+        },
+      });
+      const shell = layout.shell!;
+      Object.defineProperty(shell, "clientWidth", { get: () => 800, configurable: true });
+      layout.updateConfig({
+        launcher: {
+          mountMode: "docked",
+          autoExpand: true,
+          detachedPanel: true,
+          dock: { width: "50%", reveal: "emerge" },
+        },
+      });
+
+      const host = shell.querySelector<HTMLElement>('[data-persona-dock-role="host"]');
+      // 50% of 800px resolved to px, then jsdom simplifies (400px - 2 * 16px).
+      expect(host?.style.width).toBe("calc(368px)");
+
+      layout.destroy();
+    });
+
+    it("clears detached chrome and pads nothing while the panel is collapsed", () => {
+      for (const reveal of ["resize", "emerge"] as const) {
+        const parent = document.createElement("div");
+        document.body.appendChild(parent);
+        const target = document.createElement("div");
+        parent.appendChild(target);
+
+        const layout = createWidgetHostLayout(target, {
+          launcher: {
+            mountMode: "docked",
+            autoExpand: false,
+            detachedPanel: true,
+            dock: { width: "320px", reveal },
+          },
+        });
+
+        const dockSlot = layout.shell?.querySelector<HTMLElement>('[data-persona-dock-role="panel"]');
+        // Collapsed: truly 0-width slot with no padding/background/box-sizing residue.
+        expect(dockSlot?.style.width, reveal).toBe("0px");
+        expect(dockSlot?.style.padding, reveal).toBe("");
+        expect(dockSlot?.style.background, reveal).toBe("");
+        expect(dockSlot?.style.boxSizing, reveal).toBe("");
+        // Padding rides the width transition so the canvas gutter shrinks with the column.
+        expect(dockSlot?.style.transition, reveal).toContain("padding");
+
+        // Opening restores the chrome; closing clears it again.
+        layout.syncWidgetState({ open: true, launcherEnabled: true });
+        expect(dockSlot?.style.padding, reveal).toBe("16px");
+        expect(dockSlot?.style.boxSizing, reveal).toBe("border-box");
+        layout.syncWidgetState({ open: false, launcherEnabled: true });
+        expect(dockSlot?.style.padding, reveal).toBe("");
+        expect(dockSlot?.style.boxSizing, reveal).toBe("");
+
+        layout.destroy();
+        document.body.innerHTML = "";
+      }
+    });
+  });
 });

package/src/runtime/host-layout.ts

@@ -5,6 +5,12 @@ import type {
 } from "../types";
 import { isDockedMountMode, resolveDockConfig } from "../utils/dock";
 import { DEFAULT_OVERLAY_Z_INDEX } from "../utils/constants";
+import { createThemeObserver, getActiveTheme } from "../utils/theme";
+import {
+  DEFAULT_PANEL_CANVAS_BACKGROUND,
+  DEFAULT_PANEL_INSET,
+  resolveTokenValue,
+} from "../utils/tokens";
 
 export type WidgetHostLayoutMode = "direct" | "docked";
 
@@ -208,6 +214,51 @@ const orderDockChildren = (
   }
 };
 
+/**
+ * Detached inset + canvas literals for the dockSlot. The panel CSS vars are set
+ * inline on the widget root inside the slot, so they cannot cascade up to the
+ * slot; resolve the token values here and apply literals.
+ */
+const resolveDetachedSlotStyles = (
+  config: AgentWidgetConfig | undefined
+): { inset: string; canvasBackground: string } => {
+  const theme = getActiveTheme(config);
+  const panel = theme.components?.panel;
+  const resolve = (raw: string | undefined, fallback: string): string => {
+    if (raw == null || raw === "") return fallback;
+    return resolveTokenValue(theme, raw) ?? raw;
+  };
+  return {
+    inset: resolve(panel?.inset, DEFAULT_PANEL_INSET),
+    canvasBackground: resolve(panel?.canvasBackground, DEFAULT_PANEL_CANVAS_BACKGROUND),
+  };
+};
+
+type DetachedSlotStyles = { inset: string; canvasBackground: string };
+
+/**
+ * Detached docked mode pads the slot so the canvas shows around the panel card.
+ * Padding, never margin, keeps parseDockWidthToPx push math truthful; box-sizing
+ * border-box keeps the slot outer width (and max-height) inclusive of the
+ * padding so the panel shrinks inside rather than overflowing.
+ */
+const applyDetachedDockSlotChrome = (
+  dockSlot: HTMLElement,
+  detached: boolean,
+  inset: string,
+  canvasBackground: string
+): void => {
+  if (!detached) {
+    dockSlot.style.padding = "";
+    dockSlot.style.background = "";
+    dockSlot.style.boxSizing = "";
+    return;
+  }
+  dockSlot.style.boxSizing = "border-box";
+  dockSlot.style.padding = inset;
+  dockSlot.style.background = canvasBackground;
+};
+
 const applyDockStyles = (
   shell: HTMLElement,
   pushTrack: HTMLElement,
@@ -215,10 +266,16 @@ const applyDockStyles = (
   dockSlot: HTMLElement,
   host: HTMLElement,
   config: AgentWidgetConfig | undefined,
-  expanded: boolean
+  expanded: boolean,
+  // Cached slot styles; null when not detached. Resolved once per config/scheme
+  // change so getActiveTheme never runs on the resize/ResizeObserver path.
+  detachedSlotStyles: DetachedSlotStyles | null
 ): void => {
   const dock = resolveDockConfig(config);
   const usePush = dock.reveal === "push";
+  const detached = detachedSlotStyles != null;
+  const detachedInset = detachedSlotStyles?.inset ?? "";
+  const detachedCanvas = detachedSlotStyles?.canvasBackground ?? "";
 
   migrateDockChildren(shell, pushTrack, contentSlot, dockSlot, usePush);
   orderDockChildren(shell, pushTrack, contentSlot, dockSlot, dock.side, usePush);
@@ -260,6 +317,8 @@ const applyDockStyles = (
     clearMobileFullscreenDockSlotStyles(dockSlot);
     resetContentSlotFlexSizing(contentSlot);
     clearEmergeDockStyles(host, dockSlot);
+    // Mobile fullscreen is flush regardless of detachedPanel.
+    applyDetachedDockSlotChrome(dockSlot, false, "", "");
 
     shell.style.display = "flex";
     shell.style.flexDirection = "column";
@@ -314,6 +373,9 @@ const applyDockStyles = (
   shell.removeAttribute("data-persona-dock-mobile-fullscreen");
   clearMobileFullscreenDockSlotStyles(dockSlot);
   applyDockSlotMaxHeight(dockSlot, dock.maxHeight);
+  // Chrome only when open: a collapsed detached slot with padding + border-box
+  // floors at 2*inset, painting a permanent canvas strip past the 0px width.
+  applyDetachedDockSlotChrome(dockSlot, detached && expanded, detachedInset, detachedCanvas);
 
   if (dock.reveal === "overlay") {
     shell.style.display = "flex";
@@ -435,8 +497,10 @@ const applyDockStyles = (
     }
 
     const width = expanded ? dock.width : "0px";
+    // Detached collapse snaps padding off as width animates to 0; animate padding
+    // alongside so the canvas gutter shrinks with the column.
     const dockTransition = dock.animate
-      ? "width 180ms ease, min-width 180ms ease, max-width 180ms ease, flex-basis 180ms ease"
+      ? `width 180ms ease, min-width 180ms ease, max-width 180ms ease, flex-basis 180ms ease${detached ? ", padding 180ms ease" : ""}`
       : "none";
     const collapsedClosed = !expanded;
 
@@ -454,9 +518,17 @@ const applyDockStyles = (
 
     if (isEmerge) {
       dockSlot.style.alignItems = dock.side === "right" ? "flex-start" : "flex-end";
-      host.style.width = dock.width;
-      host.style.minWidth = dock.width;
-      host.style.maxWidth = dock.width;
+      // Emerge pins the host to a fixed width and reveals it as the slot grows.
+      // When detached, shrink that fixed width by the padding so the host fits
+      // the padded slot content-box instead of overflowing one side. Resolve a
+      // percentage dock.width to px first: a raw % re-resolves against the
+      // padding-reduced content box and un-pins as the slot animates open.
+      const emergeHostWidth = detached
+        ? `calc(${parseDockWidthToPx(dock.width, shell.clientWidth)}px - (2 * ${detachedInset}))`
+        : dock.width;
+      host.style.width = emergeHostWidth;
+      host.style.minWidth = emergeHostWidth;
+      host.style.maxWidth = emergeHostWidth;
       host.style.boxSizing = "border-box";
     }
   }
@@ -518,12 +590,38 @@ const createDockedLayout = (target: HTMLElement, config?: AgentWidgetConfig): Wi
     resizeObserver = null;
   };
 
+  // Resolved once per config/scheme change; the resize paths reuse this so
+  // getActiveTheme never runs per frame.
+  let detachedSlotStyles: DetachedSlotStyles | null = null;
+  const refreshDetachedSlotStyles = (): void => {
+    detachedSlotStyles =
+      config?.launcher?.detachedPanel === true ? resolveDetachedSlotStyles(config) : null;
+  };
+  refreshDetachedSlotStyles();
+
+  const reapplyDockStyles = (): void => {
+    applyDockStyles(shell, pushTrack, contentSlot, dockSlot, host, config, expanded, detachedSlotStyles);
+  };
+
+  // Scheme-dependent canvas tokens are baked to literals at layout time, so an
+  // OS dark-mode flip leaves a stale canvas until we recompute and re-apply.
+  let cleanupSchemeObserver: (() => void) | null = null;
+  const syncSchemeObserver = (): void => {
+    cleanupSchemeObserver?.();
+    cleanupSchemeObserver = null;
+    if (config?.launcher?.detachedPanel !== true || config?.colorScheme !== "auto") return;
+    cleanupSchemeObserver = createThemeObserver(() => {
+      refreshDetachedSlotStyles();
+      reapplyDockStyles();
+    });
+  };
+
   const syncPushResizeObserver = (): void => {
     disconnectResizeObserver();
     if (resolveDockConfig(config).reveal !== "push") return;
     if (typeof ResizeObserver === "undefined") return;
     resizeObserver = new ResizeObserver(() => {
-      applyDockStyles(shell, pushTrack, contentSlot, dockSlot, host, config, expanded);
+      reapplyDockStyles();
     });
     resizeObserver.observe(shell);
   };
@@ -531,7 +629,7 @@ const createDockedLayout = (target: HTMLElement, config?: AgentWidgetConfig): Wi
   let heightChainChecked = false;
 
   const layout = (): void => {
-    applyDockStyles(shell, pushTrack, contentSlot, dockSlot, host, config, expanded);
+    reapplyDockStyles();
     syncPushResizeObserver();
     // Check the height chain once, the first time the panel is actually shown
     // in a layout that depends on it (mobile fullscreen is fixed-position and
@@ -562,6 +660,7 @@ const createDockedLayout = (target: HTMLElement, config?: AgentWidgetConfig): Wi
   }
 
   layout();
+  syncSchemeObserver();
 
   return {
     mode: "docked",
@@ -578,10 +677,14 @@ const createDockedLayout = (target: HTMLElement, config?: AgentWidgetConfig): Wi
       if ((config?.launcher?.enabled ?? true) === false) {
         expanded = true;
       }
+      refreshDetachedSlotStyles();
       layout();
+      syncSchemeObserver();
     },
     destroy() {
       ownerWindow?.removeEventListener("resize", onViewportResize);
+      cleanupSchemeObserver?.();
+      cleanupSchemeObserver = null;
       disconnectResizeObserver();
       if (originalParent.isConnected) {
         if (originalNextSibling && originalNextSibling.parentNode === originalParent) {

package/src/runtime/init.ts

@@ -19,71 +19,28 @@ const ensureTarget = (target: string | HTMLElement): HTMLElement => {
   return target;
 };
 
-const widgetCssHref = (): string | null => {
-  try {
-    // This works in ESM builds but not in IIFE builds
-    if (typeof import.meta !== "undefined" && import.meta.url) {
-      return new URL("../widget.css", import.meta.url).href;
-    }
-  } catch {
-    // Fallback for IIFE builds where CSS should be loaded separately
-  }
-  return null;
-};
-
+// CSS arrives via the installer's link[data-persona] or a consumer import of
+// @runtypelabs/persona/widget.css; the widget never self-locates its stylesheet.
+// A new URL(..., import.meta.url) here breaks consumer bundlers (webpack
+// resolves the literal at build time), so shadow roots only clone the head link.
 const mountStyles = (root: ShadowRoot | HTMLElement, ownerDocument: Document) => {
-  const href = widgetCssHref();
-
-  const adoptExistingStylesheet = () => {
-    if (!(root instanceof ShadowRoot)) {
-      return;
-    }
-
-    if (root.querySelector('link[data-persona]')) {
-      return;
-    }
-
-    const globalLink = ownerDocument.head.querySelector<HTMLLinkElement>(
-      'link[data-persona]'
-    );
-    if (!globalLink) {
-      return;
-    }
+  if (!(root instanceof ShadowRoot)) {
+    return;
+  }
 
-    const clonedLink = globalLink.cloneNode(true) as HTMLLinkElement;
-    root.insertBefore(clonedLink, root.firstChild);
-  };
+  if (root.querySelector('link[data-persona]')) {
+    return;
+  }
 
-  if (root instanceof ShadowRoot) {
-    // For shadow DOM, we need to load CSS into the shadow root
-    if (href) {
-      const link = ownerDocument.createElement("link");
-      link.rel = "stylesheet";
-      link.href = href;
-      link.setAttribute("data-persona", "true");
-      root.insertBefore(link, root.firstChild);
-    } else {
-      adoptExistingStylesheet();
-    }
-    // If href is null (IIFE build), CSS should already be loaded globally
-  } else {
-    // For non-shadow DOM, check if CSS is already loaded
-    const existing = ownerDocument.head.querySelector<HTMLLinkElement>(
-      "link[data-persona]"
-    );
-    if (!existing) {
-      if (href) {
-        // ESM build - load CSS dynamically
-        const link = ownerDocument.createElement("link");
-        link.rel = "stylesheet";
-        link.href = href;
-        link.setAttribute("data-persona", "true");
-        ownerDocument.head.appendChild(link);
-      }
-      // IIFE build - CSS should be loaded via <link> tag before script
-      // If not found, we'll assume it's loaded globally or warn in dev
-    }
+  const globalLink = ownerDocument.head.querySelector<HTMLLinkElement>(
+    'link[data-persona]'
+  );
+  if (!globalLink) {
+    return;
   }
+
+  const clonedLink = globalLink.cloneNode(true) as HTMLLinkElement;
+  root.insertBefore(clonedLink, root.firstChild);
 };
 
 export type AgentWidgetInitHandle = AgentWidgetController & { host: HTMLElement };

package/src/session.mentions.test.ts

@@ -0,0 +1,175 @@
+import { describe, it, expect } from "vitest";
+import { AgentWidgetSession } from "./session";
+import type {
+  AgentWidgetMessage,
+  AgentWidgetRequestPayload,
+  ContentPart,
+} from "./types";
+import type { MentionSubmitBundle } from "./context-mentions-entry";
+
+/** A closed, empty SSE stream so `dispatch` completes with no events. */
+function closedStream(): ReadableStream<Uint8Array> {
+  return new ReadableStream({ start: (c) => c.close() });
+}
+
+/**
+ * Regression coverage for the mention/command submit path:
+ * - an empty-text, chip-only submit must NOT render the "[Image]" fallback
+ *   (that fallback is for image-only turns);
+ * - a `command: "server"` mention's `resolve().context` must ride to the
+ *   backend under request `context.mentions` (the c1 dispatch channel).
+ */
+describe("AgentWidgetSession — mention/command submit", () => {
+  function makeSession(captured: { payload?: AgentWidgetRequestPayload }) {
+    let messages: AgentWidgetMessage[] = [];
+    let status = "idle";
+    let streaming = false;
+    const session = new AgentWidgetSession(
+      {
+        apiUrl: "http://localhost:8000",
+        customFetch: async (_url, _init, payload) => {
+          captured.payload = payload;
+          return { ok: true, body: closedStream() } as unknown as Response;
+        },
+      },
+      {
+        onMessagesChanged: (m) => {
+          messages = m;
+        },
+        onStatusChanged: (s) => {
+          status = s;
+        },
+        onStreamingChanged: (s) => {
+          streaming = s;
+        },
+        onError: () => {},
+      }
+    );
+    return {
+      session,
+      user: () => messages.find((m) => m.role === "user"),
+      status: () => status,
+      streaming: () => streaming,
+    };
+  }
+
+  it("renders no [Image] fallback for a command-only submit and forwards context.mentions", async () => {
+    const captured: { payload?: AgentWidgetRequestPayload } = {};
+    const { session, user } = makeSession(captured);
+
+    // A server skill: `/lookup 1042` resolved to structured context, namespaced
+    // `{ [sourceId]: { [itemId]: context } }` exactly as the manager builds it.
+    const context = { commands: { lookup: { intent: "lookup-order", orderId: "1042" } } };
+    const refs = [{ sourceId: "commands", itemId: "lookup", label: "lookup" }];
+    const bundle: MentionSubmitBundle = {
+      blocks: [],
+      contentParts: [],
+      context,
+    };
+
+    await session.sendMessage("", {
+      mentions: {
+        refs,
+        finalize: async () => bundle,
+      },
+    });
+
+    const msg = user();
+    expect(msg).toBeDefined();
+    // The bug: an empty-text, mention-only submit used to display "[Image]".
+    expect(msg!.content).toBe("");
+    expect(msg!.content).not.toBe("[Image]");
+    // The command chip echoes immediately as a ref.
+    expect(msg!.contextMentions).toEqual(refs);
+    // Structured server-command data is merged onto the message…
+    expect(msg!.mentionContext).toEqual(context);
+    // …and rides to the backend under request `context.mentions`.
+    expect(captured.payload?.context).toMatchObject({ mentions: context });
+  });
+
+  it("merges resolved @-mention llmContent into the dispatched snapshot", async () => {
+    const captured: { payload?: AgentWidgetRequestPayload } = {};
+    const { session } = makeSession(captured);
+
+    await session.sendMessage("summarize this", {
+      mentions: {
+        refs: [{ sourceId: "files", itemId: "app", label: "App.tsx" }],
+        finalize: async (): Promise<MentionSubmitBundle> => ({
+          blocks: ["```App.tsx\nFILE BODY\n```"],
+          contentParts: [],
+          context: {},
+        }),
+      },
+    });
+
+    const dispatched = (captured.payload?.messages ?? []).find(
+      (m) => m.role === "user"
+    );
+    // The client collapses `llmContent` into the payload `content` field via the
+    // content-priority chain, so the model must see the resolved file body
+    // appended to the typed prose — not just the raw "summarize this".
+    const sent = dispatched?.content;
+    expect(typeof sent).toBe("string");
+    expect(sent as string).toContain("FILE BODY");
+    expect(sent as string).toContain("summarize this");
+    // Mention blocks lead; the typed prose lands last (joined by a blank line).
+    expect(sent as string).toBe("```App.tsx\nFILE BODY\n```\n\nsummarize this");
+  });
+
+  it("still renders the [Image] fallback for an image-only submit", async () => {
+    const captured: { payload?: AgentWidgetRequestPayload } = {};
+    const { session, user } = makeSession(captured);
+
+    const contentParts: ContentPart[] = [
+      { type: "image", image: "data:image/png;base64,abc123", mimeType: "image/png" },
+    ];
+    await session.sendMessage("", { contentParts });
+
+    expect(user()!.content).toBe("[Image]");
+  });
+
+  it("cancel() during a pending mention finalize aborts the turn without dispatching", async () => {
+    const captured: { payload?: AgentWidgetRequestPayload } = {};
+    const { session, status, streaming } = makeSession(captured);
+
+    let releaseFinalize!: (bundle: MentionSubmitBundle) => void;
+    const pending = new Promise<MentionSubmitBundle>((resolve) => {
+      releaseFinalize = resolve;
+    });
+
+    const sent = session.sendMessage("summarize this", {
+      mentions: {
+        refs: [{ sourceId: "files", itemId: "app", label: "App.tsx" }],
+        finalize: () => pending,
+      },
+    });
+
+    // Stop mid-resolution, then let finalize settle: dispatch must not fire.
+    session.cancel();
+    releaseFinalize({ blocks: ["```App.tsx\nBODY\n```"], contentParts: [], context: {} });
+    await sent;
+
+    expect(captured.payload).toBeUndefined();
+    expect(status()).toBe("idle");
+    expect(streaming()).toBe(false);
+  });
+
+  it("dispatches a normal mention submit once finalize resolves", async () => {
+    const captured: { payload?: AgentWidgetRequestPayload } = {};
+    const { session, streaming } = makeSession(captured);
+
+    await session.sendMessage("summarize this", {
+      mentions: {
+        refs: [{ sourceId: "files", itemId: "app", label: "App.tsx" }],
+        finalize: async (): Promise<MentionSubmitBundle> => ({
+          blocks: ["```App.tsx\nBODY\n```"],
+          contentParts: [],
+          context: {},
+        }),
+      },
+    });
+
+    expect(captured.payload).toBeDefined();
+    expect(streaming()).toBe(false);
+  });
+});