@runtypelabs/persona 4.7.0 → 4.8.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.ts

@@ -28,6 +28,10 @@ import {
   generateAssistantMessageId
 } from "./utils/message-id";
 import { IMAGE_ONLY_MESSAGE_FALLBACK_TEXT } from "./utils/content";
+import {
+  buildArtifactRefRawContent,
+  resolveArtifactDisplayMode
+} from "./utils/artifact-display";
 import type {
   VoiceProvider,
   VoiceStatus,
@@ -2607,33 +2611,82 @@ export class AgentWidgetSession {
     const id =
       manual.id ||
       `art_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 9)}`;
-    if (manual.artifactType === "markdown") {
-      const rec: PersonaArtifactRecord = {
-        id,
-        artifactType: "markdown",
-        title: manual.title,
-        status: "complete",
-        markdown: manual.content
-      };
-      this.artifacts.set(id, rec);
-      this.selectedArtifactId = id;
-      this.emitArtifactsState();
-      return rec;
-    }
-    const rec: PersonaArtifactRecord = {
-      id,
-      artifactType: "component",
-      title: manual.title,
-      status: "complete",
-      component: manual.component,
-      props: manual.props ?? {}
-    };
+    const rec: PersonaArtifactRecord =
+      manual.artifactType === "markdown"
+        ? {
+            id,
+            artifactType: "markdown",
+            title: manual.title,
+            status: "complete",
+            markdown: manual.content,
+            ...(manual.file ? { file: manual.file } : {})
+          }
+        : {
+            id,
+            artifactType: "component",
+            title: manual.title,
+            status: "complete",
+            component: manual.component,
+            props: manual.props ?? {}
+          };
     this.artifacts.set(id, rec);
     this.selectedArtifactId = id;
     this.emitArtifactsState();
+    if (manual.transcript !== false) {
+      this.injectArtifactRefBlock(rec);
+    }
     return rec;
   }
 
+  /**
+   * Injects (or refreshes) the in-thread artifact block for a programmatically
+   * upserted artifact, matching the streamed UX: the resolved display mode
+   * picks the component ("card"/"panel" → reference card, "inline" → inline
+   * preview).
+   *
+   * Unlike the streamed path (which embeds content on `artifact_complete`),
+   * the programmatic record is complete up front, so the final markdown /
+   * file meta / component name + props are embedded immediately and the block
+   * hydrates after a refresh without the original registry state.
+   *
+   * A re-upsert of the same id rebuilds the existing block's persisted
+   * rawContent in place (the registry is not persisted, so hydration reads
+   * these props); without this the block would keep the first version's
+   * content after a refresh.
+   */
+  private injectArtifactRefBlock(rec: PersonaArtifactRecord): void {
+    const refId = `artifact-ref-${rec.id}`;
+    const displayMode = resolveArtifactDisplayMode(
+      this.config.features?.artifacts,
+      rec.artifactType
+    );
+    const rawContent = buildArtifactRefRawContent(displayMode, {
+      artifactId: rec.id,
+      title: rec.title,
+      artifactType: rec.artifactType,
+      status: "complete",
+      ...(rec.file ? { file: rec.file } : {}),
+      ...(rec.component ? { component: rec.component } : {}),
+      ...(rec.props ? { componentProps: rec.props } : {}),
+      ...(rec.markdown !== undefined ? { markdown: rec.markdown } : {})
+    });
+    // Re-upsert: mutate the STORED message (inject stores a copy via
+    // ensureSequence, so a local copy would be lost) and notify so the
+    // transcript re-renders and persistence picks up the new version.
+    const existing = this.messages.find((m) => m.id === refId);
+    if (existing) {
+      existing.rawContent = rawContent;
+      existing.streaming = false;
+      this.callbacks.onMessagesChanged([...this.messages]);
+      return;
+    }
+    this.injectAssistantMessage({
+      id: refId,
+      content: "",
+      rawContent
+    });
+  }
+
   private clearArtifactState(): void {
     if (this.artifacts.size === 0 && this.selectedArtifactId === null) return;
     this.artifacts.clear();
@@ -2657,7 +2710,8 @@ export class AgentWidgetSession {
             artifactType: "markdown",
             title: ev.title,
             status: "streaming",
-            markdown: ""
+            markdown: "",
+            ...(ev.file ? { file: ev.file } : {})
           });
         } else {
           this.artifacts.set(ev.id, {