@runtypelabs/persona 1.48.0 → 2.0.0

package/src/runtime/init.test.ts

@@ -0,0 +1,236 @@
+// @vitest-environment jsdom
+
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+type Listener = () => void;
+
+const createAgentExperienceMock = vi.fn();
+
+vi.mock("../ui", () => ({
+  createAgentExperience: createAgentExperienceMock,
+}));
+
+function createMockController(config?: { launcher?: { enabled?: boolean; autoExpand?: boolean } }) {
+  let open = (config?.launcher?.enabled ?? true) ? (config?.launcher?.autoExpand ?? false) : true;
+  const launcherEnabled = config?.launcher?.enabled ?? true;
+  const listeners = new Map<string, Set<Listener>>();
+
+  const emit = (event: string) => {
+    const handlers = listeners.get(event);
+    if (!handlers) return;
+    handlers.forEach((handler) => handler());
+  };
+
+  return {
+    update: vi.fn(),
+    destroy: vi.fn(),
+    getState: vi.fn(() => ({
+      open: launcherEnabled && open,
+      launcherEnabled,
+      voiceActive: false,
+      streaming: false,
+    })),
+    on: vi.fn((event: string, handler: Listener) => {
+      const handlers = listeners.get(event) ?? new Set<Listener>();
+      handlers.add(handler);
+      listeners.set(event, handlers);
+      return () => {
+        handlers.delete(handler);
+      };
+    }),
+    off: vi.fn(),
+    open: vi.fn(() => {
+      open = true;
+      emit("widget:opened");
+    }),
+    close: vi.fn(() => {
+      open = false;
+      emit("widget:closed");
+    }),
+    toggle: vi.fn(() => {
+      open = !open;
+      emit(open ? "widget:opened" : "widget:closed");
+    }),
+    clearChat: vi.fn(),
+    isOpen: vi.fn(() => open),
+    isVoiceActive: vi.fn(() => false),
+    getMessages: vi.fn(() => []),
+    getStatus: vi.fn(() => "idle"),
+    getPersistentMetadata: vi.fn(() => ({})),
+    updatePersistentMetadata: vi.fn(),
+    showCSATFeedback: vi.fn(),
+    submitCSATFeedback: vi.fn(),
+    showNPSFeedback: vi.fn(),
+    submitNPSFeedback: vi.fn(),
+    injectMessage: vi.fn(),
+    injectAssistantMessage: vi.fn(),
+    injectUserMessage: vi.fn(),
+    injectSystemMessage: vi.fn(),
+    injectMessageBatch: vi.fn(),
+    getMessageById: vi.fn(),
+    getLastMessage: vi.fn(),
+    focusInput: vi.fn(),
+    setComposerText: vi.fn(),
+    getComposerText: vi.fn(),
+    submitComposerText: vi.fn(),
+    showEventStream: vi.fn(),
+    hideEventStream: vi.fn(),
+    isEventStreamVisible: vi.fn(() => false),
+    startVoiceRecognition: vi.fn(() => false),
+    stopVoiceRecognition: vi.fn(() => false),
+    showArtifacts: vi.fn(),
+    hideArtifacts: vi.fn(),
+    clearArtifacts: vi.fn(),
+    onArtifactSelect: vi.fn(),
+  };
+}
+
+describe("initAgentWidget docked mode", () => {
+  beforeEach(() => {
+    document.body.innerHTML = "";
+    createAgentExperienceMock.mockReset();
+    createAgentExperienceMock.mockImplementation((_mount, config) => createMockController(config));
+  });
+
+  it("wraps the target in a dock shell and restores it on destroy", async () => {
+    const { initAgentWidget } = await import("./init");
+    const wrapper = document.createElement("div");
+    wrapper.innerHTML = `<div id="content">Workspace</div>`;
+    document.body.appendChild(wrapper);
+    const target = wrapper.querySelector<HTMLElement>("#content")!;
+
+    const handle = initAgentWidget({
+      target,
+      config: {
+        launcher: {
+          mountMode: "docked",
+          dock: { width: "420px", collapsedWidth: "72px" },
+        },
+      },
+    });
+
+    const shell = wrapper.querySelector<HTMLElement>('[data-persona-host-layout="docked"]');
+    expect(shell).not.toBeNull();
+    expect(shell?.querySelector('[data-persona-dock-role="content"]')?.firstElementChild).toBe(target);
+    expect(shell?.querySelector('[data-persona-dock-role="panel"]')).not.toBeNull();
+    expect(handle.host).toBe(shell?.querySelector('[data-persona-dock-role="host"]'));
+
+    handle.destroy();
+
+    expect(wrapper.firstElementChild).toBe(target);
+    expect(wrapper.querySelector('[data-persona-host-layout="docked"]')).toBeNull();
+  });
+
+  it("rejects body as a docked target", async () => {
+    const { initAgentWidget } = await import("./init");
+
+    expect(() =>
+      initAgentWidget({
+        target: document.body,
+        config: {
+          launcher: {
+            mountMode: "docked",
+          },
+        },
+      })
+    ).toThrow('Docked widget target must be a concrete container element');
+  });
+
+  it("updates dock width on open and close events", async () => {
+    const { initAgentWidget } = await import("./init");
+    document.body.innerHTML = `<div id="content">Workspace</div>`;
+
+    const handle = initAgentWidget({
+      target: "#content",
+      config: {
+        launcher: {
+          mountMode: "docked",
+          autoExpand: true,
+          dock: { width: "400px", collapsedWidth: "80px" },
+        },
+      },
+    });
+
+    const panelSlot = document.querySelector<HTMLElement>('[data-persona-dock-role="panel"]')!;
+    expect(panelSlot.style.width).toBe("400px");
+
+    handle.close();
+    expect(panelSlot.style.width).toBe("80px");
+
+    handle.open();
+    expect(panelSlot.style.width).toBe("400px");
+  });
+
+  it("rebuilds when mount mode changes from floating to docked", async () => {
+    const { initAgentWidget } = await import("./init");
+    document.body.innerHTML = `<div id="content">Workspace</div>`;
+
+    const handle = initAgentWidget({
+      target: "#content",
+      config: {
+        launcher: {
+          mountMode: "floating",
+        },
+      },
+    });
+
+    expect(createAgentExperienceMock).toHaveBeenCalledTimes(1);
+    handle.update({
+      launcher: {
+        mountMode: "docked",
+        dock: { side: "left", width: "460px", collapsedWidth: "88px" },
+      },
+    });
+
+    expect(createAgentExperienceMock).toHaveBeenCalledTimes(2);
+    const shell = document.querySelector<HTMLElement>('[data-persona-host-layout="docked"]');
+    expect(shell).not.toBeNull();
+    expect(shell?.firstElementChild?.getAttribute("data-persona-dock-role")).toBe("panel");
+  });
+
+  it("updates dock config in place without rebuilding the controller", async () => {
+    const { initAgentWidget } = await import("./init");
+    document.body.innerHTML = `<div id="content">Workspace</div>`;
+
+    const handle = initAgentWidget({
+      target: "#content",
+      config: {
+        launcher: {
+          mountMode: "docked",
+          dock: { side: "right", width: "420px", collapsedWidth: "72px" },
+        },
+      },
+    });
+
+    expect(createAgentExperienceMock).toHaveBeenCalledTimes(1);
+    handle.update({
+      launcher: {
+        dock: { side: "left", width: "500px", collapsedWidth: "96px" },
+      },
+    });
+
+    expect(createAgentExperienceMock).toHaveBeenCalledTimes(1);
+    const shell = document.querySelector<HTMLElement>('[data-persona-host-layout="docked"]');
+    const panelSlot = document.querySelector<HTMLElement>('[data-persona-dock-role="panel"]');
+    expect(shell?.firstElementChild?.getAttribute("data-persona-dock-role")).toBe("panel");
+    expect(panelSlot?.style.width).toBe("96px");
+  });
+
+  it("supports shadow DOM hosts in docked mode", async () => {
+    const { initAgentWidget } = await import("./init");
+    document.body.innerHTML = `<div id="content">Workspace</div>`;
+
+    const handle = initAgentWidget({
+      target: "#content",
+      useShadowDom: true,
+      config: {
+        launcher: {
+          mountMode: "docked",
+        },
+      },
+    });
+
+    expect(handle.host.shadowRoot).not.toBeNull();
+    expect(handle.host.shadowRoot?.querySelector("#persona-root")).not.toBeNull();
+  });
+});

package/src/runtime/init.ts

@@ -1,5 +1,7 @@
 import { createAgentExperience, AgentWidgetController } from "../ui";
 import { AgentWidgetConfig as _AgentWidgetConfig, AgentWidgetInitOptions, AgentWidgetEvent as _AgentWidgetEvent } from "../types";
+import { isDockedMountMode } from "../utils/dock";
+import { createWidgetHostLayout } from "./host-layout";
 
 const ensureTarget = (target: string | HTMLElement): HTMLElement => {
   if (typeof window === "undefined" || typeof document === "undefined") {
@@ -29,7 +31,7 @@ const widgetCssHref = (): string | null => {
   return null;
 };
 
-const mountStyles = (root: ShadowRoot | HTMLElement) => {
+const mountStyles = (root: ShadowRoot | HTMLElement, ownerDocument: Document) => {
   const href = widgetCssHref();
 
   const adoptExistingStylesheet = () => {
@@ -41,7 +43,7 @@ const mountStyles = (root: ShadowRoot | HTMLElement) => {
       return;
     }
 
-    const globalLink = document.head.querySelector<HTMLLinkElement>(
+    const globalLink = ownerDocument.head.querySelector<HTMLLinkElement>(
       'link[data-persona]'
     );
     if (!globalLink) {
@@ -55,7 +57,7 @@ const mountStyles = (root: ShadowRoot | HTMLElement) => {
   if (root instanceof ShadowRoot) {
     // For shadow DOM, we need to load CSS into the shadow root
     if (href) {
-      const link = document.createElement("link");
+      const link = ownerDocument.createElement("link");
       link.rel = "stylesheet";
       link.href = href;
       link.setAttribute("data-persona", "true");
@@ -66,17 +68,17 @@ const mountStyles = (root: ShadowRoot | HTMLElement) => {
     // 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 = document.head.querySelector<HTMLLinkElement>(
+    const existing = ownerDocument.head.querySelector<HTMLLinkElement>(
       "link[data-persona]"
     );
     if (!existing) {
       if (href) {
         // ESM build - load CSS dynamically
-        const link = document.createElement("link");
+        const link = ownerDocument.createElement("link");
         link.rel = "stylesheet";
         link.href = href;
         link.setAttribute("data-persona", "true");
-        document.head.appendChild(link);
+        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
@@ -90,75 +92,132 @@ export const initAgentWidget = (
   options: AgentWidgetInitOptions
 ): AgentWidgetInitHandle => {
   const target = ensureTarget(options.target);
-  const host = document.createElement("div");
-  host.className = "persona-host";
-  
-  // When launcher is disabled (inline embed mode), ensure the host fills its container
-  const launcherEnabled = options.config?.launcher?.enabled ?? true;
-  if (!launcherEnabled) {
-    host.style.height = "100%";
-  }
-  
-  target.appendChild(host);
-
   const useShadow = options.useShadowDom === true;
-  let mount: HTMLElement;
-  let _root: ShadowRoot | HTMLElement;
-
-  if (useShadow) {
-    const shadowRoot = host.attachShadow({ mode: "open" });
-    _root = shadowRoot;
-    mount = document.createElement("div");
+  const ownerDocument = target.ownerDocument;
+  let config = options.config;
+  let hostLayout = createWidgetHostLayout(target, config);
+  let controller: AgentWidgetController;
+  let stateUnsubs: Array<() => void> = [];
+
+  const createMount = (host: HTMLElement, nextConfig?: _AgentWidgetConfig): HTMLElement => {
+    const launcherEnabled = nextConfig?.launcher?.enabled ?? true;
+    const shouldFillHost = !launcherEnabled || isDockedMountMode(nextConfig);
+    const mount = ownerDocument.createElement("div");
     mount.id = "persona-root";
-    // When launcher is disabled, ensure mount fills the host
-    if (!launcherEnabled) {
+
+    if (shouldFillHost) {
       mount.style.height = "100%";
       mount.style.display = "flex";
       mount.style.flexDirection = "column";
       mount.style.flex = "1";
       mount.style.minHeight = "0";
     }
-    shadowRoot.appendChild(mount);
-    mountStyles(shadowRoot);
-  } else {
-    _root = host;
-    mount = document.createElement("div");
-    mount.id = "persona-root";
-    // When launcher is disabled, ensure mount fills the host
-    if (!launcherEnabled) {
-      mount.style.height = "100%";
-      mount.style.display = "flex";
-      mount.style.flexDirection = "column";
-      mount.style.flex = "1";
-      mount.style.minHeight = "0";
+
+    if (useShadow) {
+      const shadowRoot = host.attachShadow({ mode: "open" });
+      shadowRoot.appendChild(mount);
+      mountStyles(shadowRoot, ownerDocument);
+    } else {
+      host.appendChild(mount);
+      mountStyles(host, ownerDocument);
     }
-    host.appendChild(mount);
-    mountStyles(host);
-  }
 
-  // Set instance id for window event scoping (mount.id is always "persona-root" for CSS)
-  if (target.id) {
-    mount.setAttribute("data-persona-instance", target.id);
-  }
+    if (target.id) {
+      mount.setAttribute("data-persona-instance", target.id);
+    }
+
+    return mount;
+  };
 
-  let controller = createAgentExperience(mount, options.config, {
-    debugTools: options.debugTools
-  });
+  const syncHostState = () => {
+    hostLayout.syncWidgetState(controller.getState());
+  };
+
+  const bindHostState = () => {
+    stateUnsubs.forEach((unsubscribe) => unsubscribe());
+    stateUnsubs = [
+      controller.on("widget:opened", syncHostState),
+      controller.on("widget:closed", syncHostState),
+    ];
+    syncHostState();
+  };
+
+  const mountController = () => {
+    const mount = createMount(hostLayout.host, config);
+    controller = createAgentExperience(mount, config, {
+      debugTools: options.debugTools
+    });
+    bindHostState();
+  };
+
+  const destroyCurrentController = () => {
+    stateUnsubs.forEach((unsubscribe) => unsubscribe());
+    stateUnsubs = [];
+    controller.destroy();
+  };
+
+  mountController();
   options.onReady?.();
 
-  const handle: AgentWidgetInitHandle = {
-    ...controller,
-    host,
+  const rebuildLayout = (nextConfig?: _AgentWidgetConfig) => {
+    destroyCurrentController();
+    hostLayout.destroy();
+    hostLayout = createWidgetHostLayout(target, nextConfig);
+    config = nextConfig;
+    mountController();
+  };
+
+  const handleBase = {
+    update(nextConfig: _AgentWidgetConfig) {
+      const mergedConfig = {
+        ...config,
+        ...nextConfig,
+        launcher: {
+          ...(config?.launcher ?? {}),
+          ...(nextConfig?.launcher ?? {}),
+          dock: {
+            ...(config?.launcher?.dock ?? {}),
+            ...(nextConfig?.launcher?.dock ?? {}),
+          },
+        },
+      } as _AgentWidgetConfig;
+      const previousDocked = isDockedMountMode(config);
+      const nextDocked = isDockedMountMode(mergedConfig);
+
+      if (previousDocked !== nextDocked) {
+        rebuildLayout(mergedConfig);
+        return;
+      }
+
+      config = mergedConfig;
+      hostLayout.updateConfig(config);
+      controller.update(nextConfig);
+      syncHostState();
+    },
     destroy() {
-      controller.destroy();
-      host.remove();
+      destroyCurrentController();
+      hostLayout.destroy();
       if (options.windowKey && typeof window !== "undefined") {
         delete (window as any)[options.windowKey];
       }
     }
   };
 
-  // Store on window if windowKey is provided
+  const handle = new Proxy(handleBase as AgentWidgetInitHandle, {
+    get(targetObject, prop, receiver) {
+      if (prop === "host") {
+        return hostLayout.host;
+      }
+
+      if (prop in targetObject) {
+        return Reflect.get(targetObject, prop, receiver);
+      }
+
+      const value = (controller as Record<PropertyKey, unknown>)[prop];
+      return typeof value === "function" ? (value as Function).bind(controller) : value;
+    }
+  }) as AgentWidgetInitHandle;
+
   if (options.windowKey && typeof window !== 'undefined') {
     (window as any)[options.windowKey] = handle;
   }

package/src/session.ts

@@ -10,7 +10,9 @@ import {
   InjectMessageOptions,
   InjectAssistantMessageOptions,
   InjectUserMessageOptions,
-  InjectSystemMessageOptions
+  InjectSystemMessageOptions,
+  PersonaArtifactRecord,
+  PersonaArtifactManualUpsert
 } from "./types";
 import {
   generateUserMessageId,
@@ -40,6 +42,10 @@ type SessionCallbacks = {
   onStreamingChanged: (streaming: boolean) => void;
   onError?: (error: Error) => void;
   onVoiceStatusChanged?: (status: VoiceStatus) => void;
+  onArtifactsState?: (state: {
+    artifacts: PersonaArtifactRecord[];
+    selectedId: string | null;
+  }) => void;
 };
 
 export class AgentWidgetSession {
@@ -56,6 +62,9 @@ export class AgentWidgetSession {
   // Agent execution state
   private agentExecution: AgentExecutionState | null = null;
 
+  private artifacts = new Map<string, PersonaArtifactRecord>();
+  private selectedArtifactId: string | null = null;
+
   // Voice support
   private voiceProvider: VoiceProvider | null = null;
   private voiceActive = false;
@@ -972,11 +981,128 @@ export class AgentWidgetSession {
     this.abortController = null;
     this.messages = [];
     this.agentExecution = null;
+    this.clearArtifactState();
     this.setStreaming(false);
     this.setStatus("idle");
     this.callbacks.onMessagesChanged([...this.messages]);
   }
 
+  public getArtifacts(): PersonaArtifactRecord[] {
+    return [...this.artifacts.values()];
+  }
+
+  public getArtifactById(id: string): PersonaArtifactRecord | undefined {
+    return this.artifacts.get(id);
+  }
+
+  public getSelectedArtifactId(): string | null {
+    return this.selectedArtifactId;
+  }
+
+  public selectArtifact(id: string | null): void {
+    this.selectedArtifactId = id;
+    this.emitArtifactsState();
+  }
+
+  public clearArtifacts(): void {
+    this.clearArtifactState();
+  }
+
+  public upsertArtifact(manual: PersonaArtifactManualUpsert): PersonaArtifactRecord {
+    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 ?? {}
+    };
+    this.artifacts.set(id, rec);
+    this.selectedArtifactId = id;
+    this.emitArtifactsState();
+    return rec;
+  }
+
+  private clearArtifactState(): void {
+    if (this.artifacts.size === 0 && this.selectedArtifactId === null) return;
+    this.artifacts.clear();
+    this.selectedArtifactId = null;
+    this.emitArtifactsState();
+  }
+
+  private emitArtifactsState(): void {
+    this.callbacks.onArtifactsState?.({
+      artifacts: [...this.artifacts.values()],
+      selectedId: this.selectedArtifactId
+    });
+  }
+
+  private applyArtifactStreamEvent(ev: AgentWidgetEvent): void {
+    switch (ev.type) {
+      case "artifact_start": {
+        if (ev.artifactType === "markdown") {
+          this.artifacts.set(ev.id, {
+            id: ev.id,
+            artifactType: "markdown",
+            title: ev.title,
+            status: "streaming",
+            markdown: ""
+          });
+        } else {
+          this.artifacts.set(ev.id, {
+            id: ev.id,
+            artifactType: "component",
+            title: ev.title,
+            status: "streaming",
+            component: ev.component ?? "",
+            props: {}
+          });
+        }
+        this.selectedArtifactId = ev.id;
+        break;
+      }
+      case "artifact_delta": {
+        const row = this.artifacts.get(ev.id);
+        if (row?.artifactType === "markdown") {
+          row.markdown = (row.markdown ?? "") + ev.artDelta;
+        }
+        break;
+      }
+      case "artifact_update": {
+        const row = this.artifacts.get(ev.id);
+        if (row?.artifactType === "component") {
+          row.props = { ...row.props, ...ev.props };
+          if (ev.component) row.component = ev.component;
+        }
+        break;
+      }
+      case "artifact_complete": {
+        const row = this.artifacts.get(ev.id);
+        if (row) row.status = "complete";
+        break;
+      }
+      default:
+        return;
+    }
+    this.emitArtifactsState();
+  }
+
   public hydrateMessages(messages: AgentWidgetMessage[]) {
     this.abortController?.abort();
     this.abortController = null;
@@ -1005,7 +1131,7 @@ export class AgentWidgetSession {
             agentName: event.message.agentMetadata.agentName ?? '',
             status: 'running',
             currentIteration: event.message.agentMetadata.iteration ?? 0,
-            maxIterations: 0
+            maxTurns: 0
           };
         } else if (event.message.agentMetadata.iteration !== undefined) {
           this.agentExecution.currentIteration = event.message.agentMetadata.iteration;
@@ -1031,6 +1157,13 @@ export class AgentWidgetSession {
         this.agentExecution.status = 'error';
       }
       this.callbacks.onError?.(event.error);
+    } else if (
+      event.type === "artifact_start" ||
+      event.type === "artifact_delta" ||
+      event.type === "artifact_update" ||
+      event.type === "artifact_complete"
+    ) {
+      this.applyArtifactStreamEvent(event);
     }
   };
 

package/src/styles/tailwind.css

@@ -14,7 +14,7 @@
 }
 
 @layer components {
-  .tvw-widget-shadow {
+  .persona-widget-shadow {
     box-shadow: 0 25px 50px -12px rgba(15, 23, 42, 0.35);
   }
 }