@runtypelabs/persona 1.48.0 → 2.0.0

package/src/components/tool-bubble.ts

@@ -11,15 +11,15 @@ export const updateToolBubbleUI = (messageId: string, bubble: HTMLElement, confi
   const expanded = toolExpansionState.has(messageId);
   const toolCallConfig = config?.toolCall ?? {};
   const header = bubble.querySelector('button[data-expand-header="true"]') as HTMLElement;
-  const content = bubble.querySelector('.tvw-border-t') as HTMLElement;
+  const content = bubble.querySelector('.persona-border-t') as HTMLElement;
   
   if (!header || !content) return;
   
   header.setAttribute("aria-expanded", expanded ? "true" : "false");
   
-  // Find toggle icon container - it's the direct child div of headerMeta (which has tvw-ml-auto)
-  const headerMeta = header.querySelector('.tvw-ml-auto') as HTMLElement;
-  const toggleIcon = headerMeta?.querySelector(':scope > .tvw-flex.tvw-items-center') as HTMLElement;
+  // Find toggle icon container - it's the direct child div of headerMeta (which has persona-ml-auto)
+  const headerMeta = header.querySelector('.persona-ml-auto') as HTMLElement;
+  const toggleIcon = headerMeta?.querySelector(':scope > .persona-flex.persona-items-center') as HTMLElement;
   if (toggleIcon) {
     toggleIcon.innerHTML = "";
     const iconColor = toolCallConfig.toggleTextColor || toolCallConfig.headerTextColor || "currentColor";
@@ -43,17 +43,17 @@ export const createToolBubble = (message: AgentWidgetMessage, config?: AgentWidg
     [
       "vanilla-message-bubble",
       "vanilla-tool-bubble",
-      "tvw-w-full",
-      "tvw-max-w-[85%]",
-      "tvw-rounded-2xl",
-      "tvw-bg-cw-surface",
-      "tvw-border",
-      "tvw-border-cw-message-border",
-      "tvw-text-cw-primary",
-      "tvw-shadow-sm",
-      "tvw-overflow-hidden",
-      "tvw-px-0",
-      "tvw-py-0"
+      "persona-w-full",
+      "persona-max-w-[85%]",
+      "persona-rounded-2xl",
+      "persona-bg-persona-surface",
+      "persona-border",
+      "persona-border-persona-message-border",
+      "persona-text-persona-primary",
+      "persona-shadow-sm",
+      "persona-overflow-hidden",
+      "persona-px-0",
+      "persona-py-0"
     ].join(" ")
   );
   // Set id for idiomorph matching
@@ -81,7 +81,7 @@ export const createToolBubble = (message: AgentWidgetMessage, config?: AgentWidg
   let expanded = toolExpansionState.has(message.id);
   const header = createElement(
     "button",
-    "tvw-flex tvw-w-full tvw-items-center tvw-justify-between tvw-gap-3 tvw-bg-transparent tvw-px-4 tvw-py-3 tvw-text-left tvw-cursor-pointer tvw-border-none"
+    "persona-flex persona-w-full persona-items-center persona-justify-between persona-gap-3 persona-bg-transparent persona-px-4 persona-py-3 persona-text-left persona-cursor-pointer persona-border-none"
   ) as HTMLButtonElement;
   header.type = "button";
   header.setAttribute("aria-expanded", expanded ? "true" : "false");
@@ -101,15 +101,15 @@ export const createToolBubble = (message: AgentWidgetMessage, config?: AgentWidg
     header.style.paddingBottom = toolCallConfig.headerPaddingY;
   }
 
-  const headerContent = createElement("div", "tvw-flex tvw-flex-col tvw-text-left");
-  const title = createElement("span", "tvw-text-xs tvw-text-cw-primary");
+  const headerContent = createElement("div", "persona-flex persona-flex-col persona-text-left");
+  const title = createElement("span", "persona-text-xs persona-text-persona-primary");
   if (toolCallConfig.headerTextColor) {
     title.style.color = toolCallConfig.headerTextColor;
   }
   title.textContent = describeToolTitle(tool);
   headerContent.appendChild(title);
 
-  const toggleIcon = createElement("div", "tvw-flex tvw-items-center");
+  const toggleIcon = createElement("div", "persona-flex persona-items-center");
   const iconColor = toolCallConfig.toggleTextColor || toolCallConfig.headerTextColor || "currentColor";
   const chevronIcon = renderLucideIcon(expanded ? "chevron-up" : "chevron-down", 16, iconColor, 2);
   if (chevronIcon) {
@@ -119,14 +119,14 @@ export const createToolBubble = (message: AgentWidgetMessage, config?: AgentWidg
     toggleIcon.textContent = expanded ? "Hide" : "Show";
   }
 
-  const headerMeta = createElement("div", "tvw-flex tvw-items-center tvw-gap-2 tvw-ml-auto");
+  const headerMeta = createElement("div", "persona-flex persona-items-center persona-gap-2 persona-ml-auto");
   headerMeta.append(toggleIcon);
 
   header.append(headerContent, headerMeta);
 
   const content = createElement(
     "div",
-    "tvw-border-t tvw-space-y-3 tvw-px-4 tvw-py-3"
+    "persona-border-t persona-border-gray-200 persona-bg-gray-50 persona-space-y-3 persona-px-4 persona-py-3"
   );
   content.style.display = expanded ? "" : "none";
 
@@ -148,7 +148,7 @@ export const createToolBubble = (message: AgentWidgetMessage, config?: AgentWidg
 
   // Add tool name at the top of content
   if (tool.name) {
-    const toolName = createElement("div", "tvw-text-xs tvw-text-cw-muted tvw-italic");
+    const toolName = createElement("div", "persona-text-xs persona-text-persona-muted persona-italic");
     if (toolCallConfig.contentTextColor) {
       toolName.style.color = toolCallConfig.contentTextColor;
     } else if (toolCallConfig.headerTextColor) {
@@ -159,10 +159,10 @@ export const createToolBubble = (message: AgentWidgetMessage, config?: AgentWidg
   }
 
   if (tool.args !== undefined) {
-    const argsBlock = createElement("div", "tvw-space-y-1");
+    const argsBlock = createElement("div", "persona-space-y-1");
     const argsLabel = createElement(
       "div",
-      "tvw-text-xs tvw-text-cw-muted"
+      "persona-text-xs persona-text-persona-muted"
     );
     if (toolCallConfig.labelTextColor) {
       argsLabel.style.color = toolCallConfig.labelTextColor;
@@ -170,7 +170,7 @@ export const createToolBubble = (message: AgentWidgetMessage, config?: AgentWidg
     argsLabel.textContent = "Arguments";
     const argsPre = createElement(
       "pre",
-      "tvw-max-h-48 tvw-overflow-auto tvw-whitespace-pre-wrap tvw-rounded-lg tvw-border tvw-px-3 tvw-py-2 tvw-text-xs tvw-text-cw-primary"
+      "persona-max-h-48 persona-overflow-auto persona-whitespace-pre-wrap persona-rounded-lg persona-border persona-border-gray-100 persona-bg-white persona-px-3 persona-py-2 persona-text-xs persona-text-persona-primary"
     );
     // Ensure font size matches header text (0.75rem / 12px)
     argsPre.style.fontSize = "0.75rem";
@@ -190,10 +190,10 @@ export const createToolBubble = (message: AgentWidgetMessage, config?: AgentWidg
   }
 
   if (tool.chunks && tool.chunks.length) {
-    const logsBlock = createElement("div", "tvw-space-y-1");
+    const logsBlock = createElement("div", "persona-space-y-1");
     const logsLabel = createElement(
       "div",
-      "tvw-text-xs tvw-text-cw-muted"
+      "persona-text-xs persona-text-persona-muted"
     );
     if (toolCallConfig.labelTextColor) {
       logsLabel.style.color = toolCallConfig.labelTextColor;
@@ -201,7 +201,7 @@ export const createToolBubble = (message: AgentWidgetMessage, config?: AgentWidg
     logsLabel.textContent = "Activity";
     const logsPre = createElement(
       "pre",
-      "tvw-max-h-48 tvw-overflow-auto tvw-whitespace-pre-wrap tvw-rounded-lg tvw-border tvw-px-3 tvw-py-2 tvw-text-xs tvw-text-cw-primary"
+      "persona-max-h-48 persona-overflow-auto persona-whitespace-pre-wrap persona-rounded-lg persona-border persona-border-gray-100 persona-bg-white persona-px-3 persona-py-2 persona-text-xs persona-text-persona-primary"
     );
     // Ensure font size matches header text (0.75rem / 12px)
     logsPre.style.fontSize = "0.75rem";
@@ -221,10 +221,10 @@ export const createToolBubble = (message: AgentWidgetMessage, config?: AgentWidg
   }
 
   if (tool.status === "complete" && tool.result !== undefined) {
-    const resultBlock = createElement("div", "tvw-space-y-1");
+    const resultBlock = createElement("div", "persona-space-y-1");
     const resultLabel = createElement(
       "div",
-      "tvw-text-xs tvw-text-cw-muted"
+      "persona-text-xs persona-text-persona-muted"
     );
     if (toolCallConfig.labelTextColor) {
       resultLabel.style.color = toolCallConfig.labelTextColor;
@@ -232,7 +232,7 @@ export const createToolBubble = (message: AgentWidgetMessage, config?: AgentWidg
     resultLabel.textContent = "Result";
     const resultPre = createElement(
       "pre",
-      "tvw-max-h-48 tvw-overflow-auto tvw-whitespace-pre-wrap tvw-rounded-lg tvw-border tvw-px-3 tvw-py-2 tvw-text-xs tvw-text-cw-primary"
+      "persona-max-h-48 persona-overflow-auto persona-whitespace-pre-wrap persona-rounded-lg persona-border persona-border-gray-100 persona-bg-white persona-px-3 persona-py-2 persona-text-xs persona-text-persona-primary"
     );
     // Ensure font size matches header text (0.75rem / 12px)
     resultPre.style.fontSize = "0.75rem";
@@ -254,7 +254,7 @@ export const createToolBubble = (message: AgentWidgetMessage, config?: AgentWidg
   if (tool.status === "complete" && typeof tool.duration === "number") {
     const duration = createElement(
       "div",
-      "tvw-text-xs tvw-text-cw-muted"
+      "persona-text-xs persona-text-persona-muted"
     );
     if (toolCallConfig.contentTextColor) {
       duration.style.color = toolCallConfig.contentTextColor;

package/src/defaults.ts

@@ -91,6 +91,12 @@ export const DEFAULT_WIDGET_CONFIG: Partial<AgentWidgetConfig> = {
   colorScheme: "light",
   launcher: {
     enabled: true,
+    mountMode: "floating",
+    dock: {
+      side: "right",
+      width: "420px",
+      collapsedWidth: "72px",
+    },
     title: "Chat Assistant",
     subtitle: "Here to help you get answers fast",
     agentIconText: "💬",
@@ -251,6 +257,10 @@ export function mergeWithDefaults(
     launcher: {
       ...DEFAULT_WIDGET_CONFIG.launcher,
       ...config.launcher,
+      dock: {
+        ...DEFAULT_WIDGET_CONFIG.launcher?.dock,
+        ...config.launcher?.dock,
+      },
       clearChat: {
         ...DEFAULT_WIDGET_CONFIG.launcher?.clearChat,
         ...config.launcher?.clearChat,
@@ -272,10 +282,26 @@ export function mergeWithDefaults(
       ...DEFAULT_WIDGET_CONFIG.voiceRecognition,
       ...config.voiceRecognition,
     },
-    features: {
-      ...DEFAULT_WIDGET_CONFIG.features,
-      ...config.features,
-    },
+    features: (() => {
+      const da = DEFAULT_WIDGET_CONFIG.features?.artifacts;
+      const ca = config.features?.artifacts;
+      const mergedArtifacts =
+        da === undefined && ca === undefined
+          ? undefined
+          : {
+              ...da,
+              ...ca,
+              layout: {
+                ...da?.layout,
+                ...ca?.layout,
+              },
+            };
+      return {
+        ...DEFAULT_WIDGET_CONFIG.features,
+        ...config.features,
+        ...(mergedArtifacts !== undefined ? { artifacts: mergedArtifacts } : {}),
+      };
+    })(),
     suggestionChips: config.suggestionChips ?? DEFAULT_WIDGET_CONFIG.suggestionChips,
     suggestionChipsConfig: {
       ...DEFAULT_WIDGET_CONFIG.suggestionChipsConfig,

package/src/index.ts

@@ -7,9 +7,16 @@ export type {
   AgentWidgetConfig,
   AgentWidgetTheme,
   AgentWidgetFeatureFlags,
+  AgentWidgetArtifactsFeature,
+  AgentWidgetArtifactsLayoutConfig,
+  PersonaArtifactKind,
+  PersonaArtifactRecord,
+  PersonaArtifactManualUpsert,
+  ArtifactConfigPayload,
   AgentWidgetInitOptions,
   AgentWidgetMessage,
   AgentWidgetLauncherConfig,
+  AgentWidgetDockConfig,
   AgentWidgetEvent,
   AgentWidgetStreamParser,
   AgentWidgetStreamParserResult,
@@ -25,6 +32,7 @@ export type {
   MessageContent,
   // Attachment config type
   AgentWidgetAttachmentsConfig,
+  AgentWidgetComposerConfig,
   // Layout types
   AgentWidgetLayoutConfig,
   AgentWidgetHeaderLayoutConfig,
@@ -62,6 +70,7 @@ export type {
   // Agent execution types
   AgentConfig,
   AgentLoopConfig,
+  AgentToolsConfig,
   AgentRequestOptions,
   AgentExecutionState,
   AgentMessageMetadata,
@@ -82,6 +91,11 @@ export type {
 } from "./types";
 
 export { initAgentWidgetFn as initAgentWidget };
+export {
+  createWidgetHostLayout,
+  type WidgetHostLayout,
+  type WidgetHostLayoutMode
+} from "./runtime/host-layout";
 export {
   createAgentExperience,
   type AgentWidgetController
@@ -125,6 +139,21 @@ export {
   fileToImagePart,
   validateImageFile
 } from "./utils/content";
+export {
+  collectEnrichedPageContext,
+  formatEnrichedContext,
+  generateStableSelector,
+  defaultParseRules
+} from "./utils/dom-context";
+export type {
+  EnrichedPageElement,
+  DomContextOptions,
+  DomContextMode,
+  ParseOptionsConfig,
+  ParseRule,
+  RuleScoringContext,
+  FormatEnrichedContextOptions
+} from "./utils/dom-context";
 export {
   AttachmentManager,
   type PendingAttachment,
@@ -135,6 +164,7 @@ export {
   generateUserMessageId,
   generateAssistantMessageId
 } from "./utils/message-id";
+export { isDockedMountMode, resolveDockConfig } from "./utils/dock";
 export { generateCodeSnippet } from "./utils/code-generators";
 export type { CodeFormat, CodeGeneratorHooks, CodeGeneratorOptions } from "./utils/code-generators";
 export { VERSION } from "./version";
@@ -144,6 +174,55 @@ export type { AgentWidgetInitHandle };
 export type { AgentWidgetPlugin } from "./plugins/types";
 export { pluginRegistry } from "./plugins/registry";
 
+// Theme system exports
+export {
+  createTheme,
+  resolveTokens,
+  themeToCssVariables,
+  applyThemeVariables,
+  getActiveTheme,
+  getColorScheme,
+  detectColorScheme,
+  createThemeObserver
+} from "./utils/theme";
+export {
+  DEFAULT_PALETTE,
+  DEFAULT_SEMANTIC,
+  DEFAULT_COMPONENTS,
+  validateTheme
+} from "./utils/tokens";
+export {
+  accessibilityPlugin,
+  animationsPlugin,
+  brandPlugin,
+  reducedMotionPlugin,
+  highContrastPlugin,
+  createPlugin
+} from "./utils/plugins";
+export {
+  migrateV1Theme,
+  validateV1Theme
+} from "./utils/migration";
+export type {
+  PersonaTheme,
+  PersonaThemePlugin,
+  CreateThemeOptions,
+  TokenReference,
+  ColorShade,
+  ColorPalette,
+  SpacingScale,
+  TypographyScale,
+  ShadowScale,
+  BorderScale,
+  RadiusScale,
+  SemanticColors,
+  SemanticSpacing,
+  SemanticTypography,
+  ComponentTokens,
+  ThemeValidationResult,
+  ThemeValidationError
+} from "./types/theme";
+
 // Component system exports
 export { componentRegistry } from "./components/registry";
 export type { ComponentRenderer, ComponentContext } from "./components/registry";
@@ -184,8 +263,7 @@ export {
   getHeaderLayout,
   buildHeaderWithLayout,
   buildDefaultHeader,
-  buildMinimalHeader,
-  buildExpandedHeader
+  buildMinimalHeader
 } from "./components/header-layouts";
 export type {
   HeaderLayoutContext,

package/src/install.ts

@@ -18,6 +18,8 @@ interface SiteAgentInstallConfig {
   clientToken?: string;
   flowId?: string;
   apiUrl?: string;
+  // Optional query param key that gates widget installation in preview mode
+  previewQueryParam?: string;
   // Shadow DOM option (defaults to false for better CSS compatibility)
   useShadowDom?: boolean;
 }
@@ -84,6 +86,12 @@ declare global {
       scriptConfig.apiUrl = apiUrl;
     }
 
+    // Optional preview query param gate
+    const previewQueryParam = script.getAttribute('data-preview-param');
+    if (previewQueryParam) {
+      scriptConfig.previewQueryParam = previewQueryParam;
+    }
+
     return scriptConfig;
   };
 
@@ -93,6 +101,20 @@ declare global {
   // Merge script attributes with window config (script attributes take precedence)
   const windowConfig: SiteAgentInstallConfig = window.siteAgentConfig || {};
   const config: SiteAgentInstallConfig = { ...windowConfig, ...scriptConfig };
+
+  const isPreviewModeEnabled = (): boolean => {
+    if (!config.previewQueryParam) {
+      return true;
+    }
+
+    const params = new URLSearchParams(window.location.search);
+    const value = params.get(config.previewQueryParam);
+    return value !== null && value !== "" && value.toLowerCase() !== "false" && value !== "0";
+  };
+
+  if (!isPreviewModeEnabled()) {
+    return;
+  }
   
   const version = config.version || "latest";
   const cdn = config.cdn || "jsdelivr";

package/src/plugins/types.ts

@@ -61,7 +61,30 @@ export interface AgentWidgetPlugin {
     config: AgentWidgetConfig;
     defaultRenderer: () => HTMLElement;
     onSubmit: (text: string) => void;
+    /**
+     * When true, the assistant stream is active — same moment `session.isStreaming()` becomes true.
+     * Prefer wiring controls to `data-persona-composer-disable-when-streaming` plus `setComposerDisabled`
+     * in the host, or react to `footer.dataset.personaComposerStreaming === "true"`.
+     */
+    streaming: boolean;
+    /**
+     * Legacy alias: host disables the primary submit control while `streaming` is true.
+     * @deprecated Use `streaming` for new plugins.
+     */
     disabled: boolean;
+    /** Opens the hidden file input when `config.attachments.enabled` is true (no-op otherwise). */
+    openAttachmentPicker: () => void;
+    /** From `config.composer.models` */
+    models?: Array<{ id: string; label: string }>;
+    /** From `config.composer.selectedModelId` */
+    selectedModelId?: string;
+    /** Updates `config.composer.selectedModelId` for the running widget instance. */
+    onModelChange?: (modelId: string) => void;
+    /**
+     * Same behavior as the built-in mic when voice is enabled.
+     * Omitted when `config.voiceRecognition.enabled` is not true.
+     */
+    onVoiceToggle?: () => void;
   }) => HTMLElement | null;
 
   /**

package/src/postprocessors.ts

@@ -162,7 +162,7 @@ export const createDirectivePostprocessor = (markdownConfig?: AgentWidgetMarkdow
     placeholders.forEach(({ token, type }) => {
       const tokenRegex = new RegExp(token.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"), "g");
       const safeType = escapeAttribute(type);
-      const replacement = `<div class="tvw-form-directive" data-tv-form="${safeType}"></div>`;
+      const replacement = `<div class="persona-form-directive" data-tv-form="${safeType}"></div>`;
       html = html.replace(tokenRegex, replacement);
     });
 
@@ -186,7 +186,7 @@ export const directivePostprocessor = (text: string): string => {
   placeholders.forEach(({ token, type }) => {
     const tokenRegex = new RegExp(token.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"), "g");
     const safeType = escapeAttribute(type);
-    const replacement = `<div class="tvw-form-directive" data-tv-form="${safeType}"></div>`;
+    const replacement = `<div class="persona-form-directive" data-tv-form="${safeType}"></div>`;
     html = html.replace(tokenRegex, replacement);
   });
 

package/src/runtime/host-layout.ts

@@ -0,0 +1,174 @@
+import type {
+  AgentWidgetConfig,
+  AgentWidgetStateSnapshot,
+} from "../types";
+import { isDockedMountMode, resolveDockConfig } from "../utils/dock";
+
+export type WidgetHostLayoutMode = "direct" | "docked";
+
+export type WidgetHostLayout = {
+  mode: WidgetHostLayoutMode;
+  host: HTMLElement;
+  shell: HTMLElement | null;
+  syncWidgetState: (state: Pick<AgentWidgetStateSnapshot, "open" | "launcherEnabled">) => void;
+  updateConfig: (config?: AgentWidgetConfig) => void;
+  destroy: () => void;
+};
+
+const setDirectHostStyles = (host: HTMLElement, config?: AgentWidgetConfig): void => {
+  const launcherEnabled = config?.launcher?.enabled ?? true;
+  host.className = "persona-host";
+  host.style.height = launcherEnabled ? "" : "100%";
+  host.style.display = launcherEnabled ? "" : "flex";
+  host.style.flexDirection = launcherEnabled ? "" : "column";
+  host.style.flex = launcherEnabled ? "" : "1 1 auto";
+  host.style.minHeight = launcherEnabled ? "" : "0";
+};
+
+const applyDockStyles = (
+  shell: HTMLElement,
+  contentSlot: HTMLElement,
+  dockSlot: HTMLElement,
+  host: HTMLElement,
+  config: AgentWidgetConfig | undefined,
+  expanded: boolean
+): void => {
+  const dock = resolveDockConfig(config);
+  const width = expanded ? dock.width : dock.collapsedWidth;
+
+  shell.dataset.personaHostLayout = "docked";
+  shell.dataset.personaDockSide = dock.side;
+  shell.dataset.personaDockOpen = expanded ? "true" : "false";
+  shell.style.display = "flex";
+  shell.style.flexDirection = "row";
+  shell.style.alignItems = "stretch";
+  shell.style.width = "100%";
+  shell.style.maxWidth = "100%";
+  shell.style.minWidth = "0";
+  shell.style.height = "100%";
+  shell.style.minHeight = "0";
+  shell.style.position = "relative";
+
+  contentSlot.style.display = "flex";
+  contentSlot.style.flexDirection = "column";
+  contentSlot.style.flex = "1 1 auto";
+  contentSlot.style.minWidth = "0";
+  contentSlot.style.minHeight = "0";
+  contentSlot.style.position = "relative";
+
+  dockSlot.style.display = "flex";
+  dockSlot.style.flexDirection = "column";
+  dockSlot.style.flex = `0 0 ${width}`;
+  dockSlot.style.width = width;
+  dockSlot.style.maxWidth = width;
+  dockSlot.style.minWidth = width;
+  dockSlot.style.minHeight = "0";
+  dockSlot.style.position = "relative";
+  dockSlot.style.overflow = "visible";
+  dockSlot.style.transition = "width 180ms ease, min-width 180ms ease, max-width 180ms ease, flex-basis 180ms ease";
+
+  host.className = "persona-host";
+  host.style.height = "100%";
+  host.style.minHeight = "0";
+  host.style.display = "flex";
+  host.style.flexDirection = "column";
+  host.style.flex = "1 1 auto";
+
+  if (dock.side === "left") {
+    if (shell.firstElementChild !== dockSlot) {
+      shell.replaceChildren(dockSlot, contentSlot);
+    }
+  } else if (shell.lastElementChild !== dockSlot) {
+    shell.replaceChildren(contentSlot, dockSlot);
+  }
+};
+
+const createDirectLayout = (target: HTMLElement, config?: AgentWidgetConfig): WidgetHostLayout => {
+  const host = target.ownerDocument.createElement("div");
+  setDirectHostStyles(host, config);
+  target.appendChild(host);
+
+  return {
+    mode: "direct",
+    host,
+    shell: null,
+    syncWidgetState: () => {},
+    updateConfig(nextConfig?: AgentWidgetConfig) {
+      setDirectHostStyles(host, nextConfig);
+    },
+    destroy() {
+      host.remove();
+    },
+  };
+};
+
+const createDockedLayout = (target: HTMLElement, config?: AgentWidgetConfig): WidgetHostLayout => {
+  const { ownerDocument } = target;
+  const originalParent = target.parentElement;
+
+  if (!originalParent) {
+    throw new Error("Docked widget target must be attached to the DOM");
+  }
+
+  const tagName = target.tagName.toUpperCase();
+  if (tagName === "BODY" || tagName === "HTML") {
+    throw new Error('Docked widget target must be a concrete container element, not "body" or "html"');
+  }
+
+  const originalNextSibling = target.nextSibling;
+  const shell = ownerDocument.createElement("div");
+  const contentSlot = ownerDocument.createElement("div");
+  const dockSlot = ownerDocument.createElement("aside");
+  const host = ownerDocument.createElement("div");
+  let expanded = (config?.launcher?.enabled ?? true) ? (config?.launcher?.autoExpand ?? false) : true;
+
+  contentSlot.dataset.personaDockRole = "content";
+  dockSlot.dataset.personaDockRole = "panel";
+  host.dataset.personaDockRole = "host";
+
+  dockSlot.appendChild(host);
+  originalParent.insertBefore(shell, target);
+  contentSlot.appendChild(target);
+  shell.appendChild(contentSlot);
+  shell.appendChild(dockSlot);
+  applyDockStyles(shell, contentSlot, dockSlot, host, config, expanded);
+
+  return {
+    mode: "docked",
+    host,
+    shell,
+    syncWidgetState(state) {
+      const nextExpanded = state.launcherEnabled ? state.open : true;
+      if (expanded === nextExpanded) return;
+      expanded = nextExpanded;
+      applyDockStyles(shell, contentSlot, dockSlot, host, config, expanded);
+    },
+    updateConfig(nextConfig?: AgentWidgetConfig) {
+      config = nextConfig;
+      if ((config?.launcher?.enabled ?? true) === false) {
+        expanded = true;
+      }
+      applyDockStyles(shell, contentSlot, dockSlot, host, config, expanded);
+    },
+    destroy() {
+      if (originalParent.isConnected) {
+        if (originalNextSibling && originalNextSibling.parentNode === originalParent) {
+          originalParent.insertBefore(target, originalNextSibling);
+        } else {
+          originalParent.appendChild(target);
+        }
+      }
+      shell.remove();
+    },
+  };
+};
+
+export const createWidgetHostLayout = (
+  target: HTMLElement,
+  config?: AgentWidgetConfig
+): WidgetHostLayout => {
+  if (isDockedMountMode(config)) {
+    return createDockedLayout(target, config);
+  }
+  return createDirectLayout(target, config);
+};