@runtypelabs/persona 4.10.0 → 4.11.0

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

@@ -4,6 +4,51 @@ import { afterEach, describe, expect, it, vi } from "vitest";
 
 import { createWidgetHostLayout } from "./host-layout";
 
+describe("createWidgetHostLayout direct", () => {
+  afterEach(() => {
+    document.body.innerHTML = "";
+  });
+
+  it("makes the host shrinkable when the launcher is disabled", () => {
+    const target = document.createElement("div");
+    document.body.appendChild(target);
+
+    const layout = createWidgetHostLayout(target, { launcher: { enabled: false } });
+    // Flex items floor at min-width:auto; the host must stay shrinkable so a wide
+    // artifact split shrinks within the mount rather than enlarging the host.
+    expect(layout.host.style.minWidth).toBe("0px");
+    expect(layout.host.style.flex).toBe("1 1 auto");
+
+    layout.destroy();
+  });
+
+  it("leaves the host min-width unset when the launcher is enabled", () => {
+    const target = document.createElement("div");
+    document.body.appendChild(target);
+
+    const layout = createWidgetHostLayout(target, { launcher: { enabled: true } });
+    expect(layout.host.style.minWidth).toBe("");
+
+    layout.destroy();
+  });
+
+  it("restores/clears the shrinkable host baseline when the launcher toggles at runtime", () => {
+    const target = document.createElement("div");
+    document.body.appendChild(target);
+
+    const layout = createWidgetHostLayout(target, { launcher: { enabled: false } });
+    expect(layout.host.style.minWidth).toBe("0px");
+
+    layout.updateConfig({ launcher: { enabled: true } });
+    expect(layout.host.style.minWidth).toBe("");
+
+    layout.updateConfig({ launcher: { enabled: false } });
+    expect(layout.host.style.minWidth).toBe("0px");
+
+    layout.destroy();
+  });
+});
+
 describe("createWidgetHostLayout docked", () => {
   afterEach(() => {
     document.body.innerHTML = "";
@@ -39,6 +84,55 @@ describe("createWidgetHostLayout docked", () => {
     layout.destroy();
   });
 
+  it("keeps a shrinkable host baseline for non-emerge dock modes but pins it for emerge", () => {
+    for (const reveal of ["resize", "overlay", "push"] 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, dock: { width: "320px", reveal } },
+      });
+      // The docked host must shrink within its mount so a wide artifact split
+      // stays contained instead of enlarging the host.
+      expect(layout.host.style.minWidth, reveal).toBe("0px");
+
+      layout.destroy();
+      document.body.innerHTML = "";
+    }
+
+    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", reveal: "emerge" } },
+    });
+    // Emerge intentionally pins the host to its fixed width, overriding the baseline.
+    expect(layout.host.style.minWidth).toBe("320px");
+    layout.destroy();
+  });
+
+  it("restores the shrinkable host baseline when switching away from emerge", () => {
+    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", reveal: "emerge" } },
+    });
+    expect(layout.host.style.minWidth).toBe("320px");
+
+    layout.updateConfig({
+      launcher: { mountMode: "docked", autoExpand: true, dock: { width: "320px", reveal: "resize" } },
+    });
+    expect(layout.host.style.minWidth).toBe("0px");
+
+    layout.destroy();
+  });
+
   it("disables dock width transition when dock.animate is false", () => {
     const parent = document.createElement("div");
     document.body.appendChild(parent);

package/src/runtime/host-layout.ts

@@ -119,6 +119,9 @@ const setDirectHostStyles = (host: HTMLElement, config?: AgentWidgetConfig): voi
   host.style.flexDirection = launcherEnabled ? "" : "column";
   host.style.flex = launcherEnabled ? "" : "1 1 auto";
   host.style.minHeight = launcherEnabled ? "" : "0";
+  // Flex items floor at min-width:auto (content width); without this the host
+  // grows past a shrinkable mount when a wide artifact split opens inside it.
+  host.style.minWidth = launcherEnabled ? "" : "0";
 };
 
 const clearOverlayDockSlotStyles = (dockSlot: HTMLElement): void => {
@@ -170,7 +173,9 @@ const resetContentSlotFlexSizing = (contentSlot: HTMLElement): void => {
 
 const clearEmergeDockStyles = (host: HTMLElement, dockSlot: HTMLElement): void => {
   host.style.width = "";
-  host.style.minWidth = "";
+  // Restore the docked shrinkable baseline, not "": non-emerge dock modes must
+  // stay shrinkable. Emerge re-pins minWidth to its fixed width after this.
+  host.style.minWidth = "0";
   host.style.maxWidth = "";
   host.style.boxSizing = "";
   dockSlot.style.alignItems = "";
@@ -298,6 +303,9 @@ const applyDockStyles = (
   host.className = "persona-host";
   host.style.height = "100%";
   host.style.minHeight = "0";
+  // Shrinkable baseline so a wide artifact split shrinks within the dock host
+  // instead of enlarging it. Emerge overwrites this with its fixed width below.
+  host.style.minWidth = "0";
   host.style.display = "flex";
   host.style.flexDirection = "column";
   host.style.flex = "1 1 auto";

package/src/runtime/init.test.ts

@@ -92,6 +92,39 @@ describe("initAgentWidget windowKey and ready notifications", () => {
     createAgentExperienceMock.mockImplementation((_mount, config) => createMockController(config));
   });
 
+  it("makes the mount shrinkable when it fills the host (launcher disabled)", async () => {
+    const { initAgentWidget } = await import("./init");
+    document.body.innerHTML = `<div id="target"></div>`;
+
+    const handle = initAgentWidget({
+      target: "#target",
+      config: { launcher: { enabled: false } },
+    });
+
+    const mount = createAgentExperienceMock.mock.calls[0][0] as HTMLElement;
+    // shouldFillHost mounts must match the host's shrinkable baseline, else a
+    // wide artifact split forces the mount past its content-based minimum width.
+    expect(mount.style.minWidth).toBe("0px");
+    expect(mount.style.minHeight).toBe("0px");
+
+    handle.destroy();
+  });
+
+  it("leaves the mount min-width unset when the launcher is enabled (floating)", async () => {
+    const { initAgentWidget } = await import("./init");
+    document.body.innerHTML = `<div id="target"></div>`;
+
+    const handle = initAgentWidget({
+      target: "#target",
+      config: { launcher: { enabled: true } },
+    });
+
+    const mount = createAgentExperienceMock.mock.calls[0][0] as HTMLElement;
+    expect(mount.style.minWidth).toBe("");
+
+    handle.destroy();
+  });
+
   it("assigns the handle to window[windowKey] when windowKey is provided", async () => {
     const { initAgentWidget } = await import("./init");
     document.body.innerHTML = `<div id="target"></div>`;

package/src/runtime/init.ts

@@ -63,12 +63,16 @@ export const initAgentWidget = (
     const mount = ownerDocument.createElement("div");
     mount.setAttribute("data-persona-root", "true");
 
+    // Initial fill styling only. On every relayout the controller's
+    // applyFullHeightStyles resets mount.style.cssText and re-applies these
+    // (including the shrinkable min-width:0), so it owns the runtime truth.
     if (shouldFillHost) {
       mount.style.height = "100%";
       mount.style.display = "flex";
       mount.style.flexDirection = "column";
       mount.style.flex = "1";
       mount.style.minHeight = "0";
+      mount.style.minWidth = "0";
     }
 
     if (useShadow) {

package/src/styles/widget.css

@@ -163,6 +163,8 @@
   --persona-md-table-header-weight: 600;
   --persona-md-table-cell-padding: 0.5rem 0.75rem;
   --persona-md-table-border-radius: 0.375rem;
+  /* Width of the horizontal-scroll edge fade on wide tables; set to 0 to disable. */
+  --persona-md-table-scroll-fade: 24px;
 
   /* Markdown Horizontal Rule Variables */
   --persona-md-hr-color: var(--persona-divider, #e5e7eb);
@@ -643,6 +645,47 @@
   max-width: 85%;
 }
 
+/* Message row geometry is role-configurable. The row always spans the
+   transcript; its direct content track either shrink-wraps or fills that row.
+   `--persona-message-row-max-width` is resolved per role in ui.ts. */
+.persona-message-row {
+  width: 100%;
+  min-width: 0;
+}
+
+.persona-message-row > * {
+  min-width: 0;
+  max-width: var(--persona-message-row-max-width, 85%);
+}
+
+.persona-message-row[data-message-width="content"] > * {
+  flex: 0 1 auto;
+}
+
+.persona-message-row[data-message-width="full"] > * {
+  flex: 1 1 auto;
+  width: 100%;
+}
+
+/* Avatars live inside the role-sized content track. The bubble flexes into
+   the space left after the fixed avatar + gap instead of making a full row
+   overflow by the avatar width. */
+.persona-message-with-avatar {
+  min-width: 0;
+}
+
+.persona-message-with-avatar > .persona-message-bubble {
+  min-width: 0;
+  max-width: 100%;
+}
+
+.persona-message-row[data-message-width="full"]
+  > .persona-message-with-avatar
+  > .persona-message-bubble {
+  flex: 1 1 auto;
+  width: auto;
+}
+
 .persona-transition {
   transition: transform 160ms ease, background-color 160ms ease,
     box-shadow 160ms ease, opacity 160ms ease;
@@ -952,7 +995,8 @@
   cursor: pointer;
 }
 
-/* Send button tooltip */
+/* Shared icon-control tooltip. It is portaled to the document body (or the
+   widget ShadowRoot) and positioned in JS so panel overflow never clips it. */
 .persona-send-button-wrapper {
   position: relative;
   display: inline-flex;
@@ -960,47 +1004,46 @@
   justify-content: center;
 }
 
-.persona-send-button-tooltip {
-  position: absolute;
-  bottom: calc(100% + 8px);
-  left: 50%;
-  transform: translateX(-50%);
+.persona-control-tooltip {
+  position: fixed;
+  box-sizing: border-box;
+  max-width: min(320px, calc(100vw - 16px));
   background-color: var(--persona-tooltip-background, #111827);
   color: var(--persona-tooltip-foreground, #ffffff);
   padding: 6px 12px;
   border-radius: var(--persona-radius-sm, 0.125rem);
   font-size: 12px;
-  white-space: nowrap;
-  opacity: 0;
+  line-height: 1.35;
+  white-space: normal;
+  overflow-wrap: anywhere;
+  box-shadow: var(--persona-tooltip-shadow, 0 4px 12px rgba(15, 23, 42, 0.18));
+  opacity: 1;
   pointer-events: none;
-  transition: opacity 0.2s;
-  z-index: 1000;
+  transition: opacity 120ms ease;
 }
 
-.persona-send-button-tooltip::after {
-  content: "";
+.persona-control-tooltip[data-state="measuring"] {
+  visibility: hidden;
+  opacity: 0;
+}
+
+.persona-control-tooltip__arrow {
   position: absolute;
-  top: 100%;
-  left: 50%;
-  transform: translateX(-50%);
-  border: 4px solid transparent;
-  border-top-color: var(--persona-tooltip-background, #111827);
+  left: var(--persona-tooltip-arrow-x, 50%);
+  width: 8px;
+  height: 8px;
+  background: var(--persona-tooltip-background, #111827);
+  transform: translateX(-50%) rotate(45deg);
 }
 
-.persona-send-button-wrapper:hover .persona-send-button-tooltip,
-.persona-send-button-wrapper:focus-within .persona-send-button-tooltip {
-  opacity: 1;
+.persona-control-tooltip[data-placement="top"] .persona-control-tooltip__arrow {
+  top: calc(100% - 4px);
 }
 
-/* Hide tooltips on touch devices: hover doesn't exist, and they cause clipping issues */
-@media (hover: none), (max-width: 500px) {
-  .persona-send-button-wrapper:hover .persona-send-button-tooltip,
-  .persona-send-button-wrapper:focus-within .persona-send-button-tooltip {
-    opacity: 0;
-  }
+.persona-control-tooltip[data-placement="bottom"] .persona-control-tooltip__arrow {
+  bottom: calc(100% - 4px);
 }
 
-/* Clear chat button tooltip */
 .persona-clear-chat-button-wrapper {
   position: relative;
   display: inline-flex;
@@ -1008,30 +1051,9 @@
   justify-content: center;
 }
 
-.persona-clear-chat-tooltip {
-  background-color: var(--persona-tooltip-background, #111827);
-  color: var(--persona-tooltip-foreground, #ffffff);
-  padding: 6px 12px;
-  border-radius: var(--persona-radius-sm, 0.125rem);
-  font-size: 12px;
-  white-space: nowrap;
-  pointer-events: none;
-  z-index: 10000;
-}
-
-.persona-clear-chat-tooltip-arrow {
-  content: "";
-  position: absolute;
-  top: 100%;
-  left: 50%;
-  transform: translateX(-50%);
-  border: 4px solid transparent;
-  border-top-color: var(--persona-tooltip-background, #111827);
-}
-
-@media (hover: none), (max-width: 500px) {
-  .persona-clear-chat-tooltip {
-    display: none !important;
+@media (prefers-reduced-motion: reduce) {
+  .persona-control-tooltip {
+    transition: none;
   }
 }
 
@@ -1501,12 +1523,45 @@
   flex-grow: 1;
 }
 
+/* Wide tables scroll inside this wrapper instead of widening the chat column.
+   The table keeps width:100% so it fills when it fits, but auto-grows past the
+   wrapper when its content is wider, and the wrapper scrolls. Injected by
+   wrapScrollableTables() before each morph. */
+.persona-table-scroll {
+  display: block;
+  max-width: 100%;
+  overflow-x: auto;
+  margin: 0.5rem 0;
+}
+
+/* Edge fades (set by table-scroll-fade.ts) cue that the table scrolls; each
+   side shows only when there is more content that way. The fade is applied
+   instantly, not transitioned: each morph strips and re-applies the fade state,
+   so a transition would animate it from 0 on every streaming chunk (flicker) and
+   once more when the finished paint re-enables it (a single flash). Instant also
+   tracks the scroll position exactly instead of lagging behind the finger. */
+.persona-table-scroll[data-persona-scroll-x] {
+  -webkit-mask-image: linear-gradient(
+    to right,
+    transparent 0,
+    #000 var(--persona-fade-l, 0px),
+    #000 calc(100% - var(--persona-fade-r, 0px)),
+    transparent 100%
+  );
+  mask-image: linear-gradient(
+    to right,
+    transparent 0,
+    #000 var(--persona-fade-l, 0px),
+    #000 calc(100% - var(--persona-fade-r, 0px)),
+    transparent 100%
+  );
+}
+
 .persona-message-bubble table {
   width: 100%;
   border-collapse: collapse;
-  margin: 0.5rem 0;
+  margin: 0;
   font-size: 0.875rem;
-  overflow: hidden;
   border-radius: var(--persona-md-table-border-radius);
   border: 1px solid var(--persona-md-table-border-color);
 }
@@ -1536,13 +1591,18 @@
   background-color: rgba(0, 0, 0, 0.02);
 }
 
-/* While a message is still streaming, lock table column widths so incoming rows
-   append without the per-chunk horizontal reflow (Telegram-style space
-   reservation). The class is removed on the final render, relaxing the finished
-   table to natural content-fit widths. overflow-wrap keeps long cell content
-   from spilling past the fixed columns mid-stream. */
+/* While a message is still streaming, lock column widths to the header row
+   (table-layout: fixed) so incoming rows append without per-chunk reflow. width
+   auto sizes columns from the header and lets cells wrap, so a table that fits
+   once wrapped fills the column (min-width: 100%) with no scroll, while one too
+   wide even wrapped scrolls: it only shows the scroll fade when it genuinely
+   needs it, matching the finished table rather than forcing every cell onto one
+   line. The class is removed on the final render, settling columns to
+   content-fit widths. overflow-wrap keeps long words from spilling the column. */
 .persona-content-streaming table {
   table-layout: fixed;
+  width: auto;
+  min-width: 100%;
 }
 
 .persona-content-streaming th,

package/src/theme-editor/sections.test.ts

@@ -4,6 +4,39 @@ import { COMPONENTS_SECTIONS, CONFIGURE_SECTIONS, INTERFACE_ROLES_SECTION, STYLE
 import { ALL_ROLES } from "./role-mappings";
 
 describe("theme editor scroll-to-bottom controls", () => {
+  it("exposes clear style semantics and independent role width controls", () => {
+    const section = CONFIGURE_SECTIONS.find((entry) => entry.id === "messages-layout");
+    const fieldsByPath = new Map(
+      section?.fields.map((field) => [field.path, field]) ?? []
+    );
+
+    expect(fieldsByPath.get("layout.messages.layout")?.options).toEqual([
+      { value: "bubble", label: "Bubble — bubbles for both" },
+      { value: "minimal", label: "Minimal — user bubble, open assistant" },
+      { value: "flat", label: "Flat — open messages for both" },
+    ]);
+    expect(fieldsByPath.has("layout.messages.user.style")).toBe(false);
+    expect(fieldsByPath.has("layout.messages.assistant.style")).toBe(false);
+
+    expect(fieldsByPath.get("layout.messages.user.width")?.options).toEqual([
+      { value: "content", label: "Content" },
+      { value: "full", label: "Full" },
+    ]);
+    expect(fieldsByPath.get("layout.messages.assistant.width")?.options).toEqual([
+      { value: "content", label: "Content" },
+      { value: "full", label: "Full" },
+    ]);
+
+    const userMaxWidth = fieldsByPath.get("layout.messages.user.maxWidth");
+    const assistantMaxWidth = fieldsByPath.get(
+      "layout.messages.assistant.maxWidth"
+    );
+    expect(userMaxWidth?.parseValue?.(" 72ch ")).toBe("72ch");
+    expect(userMaxWidth?.parseValue?.("  ")).toBeUndefined();
+    expect(assistantMaxWidth?.parseValue?.("80%")).toBe("80%");
+    expect(assistantMaxWidth?.parseValue?.("")).toBeUndefined();
+  });
+
   it("exposes scroll-to-bottom config controls", () => {
     const featureSection = CONFIGURE_SECTIONS.find((section) => section.id === "features");
 

package/src/theme-editor/sections.ts

@@ -22,6 +22,11 @@ import {
   ROLE_BORDERS,
 } from './role-mappings';
 
+const parseOptionalCssValue = (value: unknown): string | undefined => {
+  const normalized = String(value ?? '').trim();
+  return normalized || undefined;
+};
+
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 // STYLE TAB: brand colors, chat colors, typography, shape, etc.
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -601,7 +606,11 @@ const headerLayoutSectionDef: SectionDef = {
 const messagesLayoutSectionDef: SectionDef = {
   id: 'messages-layout', title: 'Messages', collapsed: true,
   fields: [
-    { id: 'layout-messages', label: 'Messages Layout', type: 'select', path: 'layout.messages.layout', defaultValue: 'bubble', options: [{ value: 'bubble', label: 'Bubble' }, { value: 'flat', label: 'Flat' }, { value: 'minimal', label: 'Minimal' }] },
+    { id: 'layout-messages', label: 'Message Style', description: 'Minimal uses a user bubble with an open assistant response', type: 'select', path: 'layout.messages.layout', defaultValue: 'bubble', options: [{ value: 'bubble', label: 'Bubble — bubbles for both' }, { value: 'minimal', label: 'Minimal — user bubble, open assistant' }, { value: 'flat', label: 'Flat — open messages for both' }] },
+    { id: 'layout-message-user-width', label: 'User Width', description: 'Content hugs the message; Full fills the transcript track', type: 'select', path: 'layout.messages.user.width', defaultValue: 'content', options: [{ value: 'content', label: 'Content' }, { value: 'full', label: 'Full' }] },
+    { id: 'layout-message-user-max-width', label: 'User Max Width', description: 'Optional CSS width such as 80%, 42rem, or 72ch; blank uses the width mode default', type: 'text', path: 'layout.messages.user.maxWidth', defaultValue: '', parseValue: parseOptionalCssValue },
+    { id: 'layout-message-assistant-width', label: 'Assistant Width', description: 'Content hugs the message; Full fills the transcript track', type: 'select', path: 'layout.messages.assistant.width', defaultValue: 'content', options: [{ value: 'content', label: 'Content' }, { value: 'full', label: 'Full' }] },
+    { id: 'layout-message-assistant-max-width', label: 'Assistant Max Width', description: 'Optional CSS width such as 80%, 42rem, or 72ch; blank uses the width mode default', type: 'text', path: 'layout.messages.assistant.maxWidth', defaultValue: '', parseValue: parseOptionalCssValue },
     { id: 'layout-group', label: 'Group Consecutive', type: 'toggle', path: 'layout.messages.groupConsecutive', defaultValue: false },
     { id: 'layout-avatar-show', label: 'Show Avatars', type: 'toggle', path: 'layout.messages.avatar.show', defaultValue: false },
     { id: 'layout-avatar-pos', label: 'Avatar Position', type: 'select', path: 'layout.messages.avatar.position', defaultValue: 'left', options: [{ value: 'left', label: 'Left' }, { value: 'right', label: 'Right' }] },

package/src/types.ts

@@ -3975,6 +3975,27 @@ export type AgentWidgetTimestampConfig = {
   format?: (date: Date) => string;
 };
 
+/**
+ * Width configuration for one message role.
+ *
+ * `content` shrink-wraps the rendered message up to `maxWidth`; `full` fills
+ * the available transcript track up to `maxWidth`. The track already accounts
+ * for transcript padding and, when present, the avatar and its gap.
+ */
+export type AgentWidgetMessageRoleLayout = {
+  /**
+   * Message width behavior.
+   * - content: size to the rendered content (the backward-compatible default)
+   * - full: fill the available transcript track
+   */
+  width?: "content" | "full";
+  /**
+   * Optional CSS max-width (for example "80%", "42rem", or "72ch").
+   * Defaults to "85%" for content width and "100%" for full width.
+   */
+  maxWidth?: string;
+};
+
 /**
  * Message layout configuration
  * Allows customization of how chat messages are displayed
@@ -3993,6 +4014,10 @@ export type AgentWidgetMessageLayoutConfig = {
   timestamp?: AgentWidgetTimestampConfig;
   /** Group consecutive messages from the same role */
   groupConsecutive?: boolean;
+  /** Width behavior for user-authored message rows */
+  user?: AgentWidgetMessageRoleLayout;
+  /** Width behavior for assistant-authored message rows and assistant UI variants */
+  assistant?: AgentWidgetMessageRoleLayout;
   /**
    * Custom renderer for user messages
    * When provided, replaces the default user message rendering

package/src/ui.attachments-drop.test.ts

@@ -270,7 +270,8 @@ describe("attachment button live config updates", () => {
     expect(button().getAttribute("aria-label")).toBe("Add a photo");
     const updatedSvg = button().querySelector("svg")!.outerHTML;
     expect(updatedSvg).not.toBe(initialSvg);
-    const tooltip = button().parentElement!.querySelector(".persona-send-button-tooltip");
+    button().parentElement!.dispatchEvent(new MouseEvent("mouseenter"));
+    const tooltip = document.body.querySelector(".persona-control-tooltip");
     expect(tooltip?.textContent).toBe("Add a photo");
 
     controller.destroy();