@runtypelabs/persona 3.3.0 → 3.5.0

package/dist/theme-reference.js

@@ -0,0 +1 @@
+var e={colors:{primary:{50:"#eff6ff",100:"#dbeafe",200:"#bfdbfe",300:"#93c5fd",400:"#60a5fa",500:"#3b82f6",600:"#2563eb",700:"#1d4ed8",800:"#1e40af",900:"#1e3a8a",950:"#172554"},secondary:{50:"#f5f3ff",100:"#ede9fe",200:"#ddd6fe",300:"#c4b5fd",400:"#a78bfa",500:"#8b5cf6",600:"#7c3aed",700:"#6d28d9",800:"#5b21b6",900:"#4c1d95",950:"#2e1065"},accent:{50:"#ecfeff",100:"#cffafe",200:"#a5f3fc",300:"#67e8f9",400:"#22d3ee",500:"#06b6d4",600:"#0891b2",700:"#0e7490",800:"#155e75",900:"#164e63",950:"#083344"},gray:{50:"#f9fafb",100:"#f3f4f6",200:"#e5e7eb",300:"#d1d5db",400:"#9ca3af",500:"#6b7280",600:"#4b5563",700:"#374151",800:"#1f2937",900:"#111827",950:"#030712"},success:{50:"#f0fdf4",100:"#dcfce7",200:"#bbf7d0",300:"#86efac",400:"#4ade80",500:"#22c55e",600:"#16a34a",700:"#15803d",800:"#166534",900:"#14532d"},warning:{50:"#fefce8",100:"#fef9c3",200:"#fef08a",300:"#fde047",400:"#facc15",500:"#eab308",600:"#ca8a04",700:"#a16207",800:"#854d0e",900:"#713f12"},error:{50:"#fef2f2",100:"#fee2e2",200:"#fecaca",300:"#fca5a5",400:"#f87171",500:"#ef4444",600:"#dc2626",700:"#b91c1c",800:"#991b1b",900:"#7f1d1d"}},spacing:{0:"0px",1:"0.25rem",2:"0.5rem",3:"0.75rem",4:"1rem",5:"1.25rem",6:"1.5rem",8:"2rem",10:"2.5rem",12:"3rem",16:"4rem",20:"5rem",24:"6rem",32:"8rem",40:"10rem",48:"12rem",56:"14rem",64:"16rem"},typography:{fontFamily:{sans:'system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif',serif:'Georgia, Cambria, "Times New Roman", Times, serif',mono:"ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace"},fontSize:{xs:"0.75rem",sm:"0.875rem",base:"1rem",lg:"1.125rem",xl:"1.25rem","2xl":"1.5rem","3xl":"1.875rem","4xl":"2.25rem"},fontWeight:{normal:"400",medium:"500",semibold:"600",bold:"700"},lineHeight:{tight:"1.25",normal:"1.5",relaxed:"1.625"}},shadows:{none:"none",sm:"0 1px 2px 0 rgb(0 0 0 / 0.05)",md:"0 4px 6px -1px rgb(0 0 0 / 0.1), 0 2px 4px -2px rgb(0 0 0 / 0.1)",lg:"0 10px 15px -3px rgb(0 0 0 / 0.1), 0 4px 6px -4px rgb(0 0 0 / 0.1)",xl:"0 20px 25px -5px rgb(0 0 0 / 0.1), 0 8px 10px -6px rgb(0 0 0 / 0.1)","2xl":"0 25px 50px -12px rgb(0 0 0 / 0.25)"},borders:{none:"none",sm:"1px solid",md:"2px solid",lg:"4px solid"},radius:{none:"0px",sm:"0.125rem",md:"0.375rem",lg:"0.5rem",xl:"0.75rem","2xl":"1rem",full:"9999px"}};var o={overview:"Persona uses a three-layer design token system: palette \u2192 semantic \u2192 components. Most themes only need palette.colors overrides \u2014 semantic and component layers auto-derive from palette values. Config also accepts non-theme appearance options (launcher, sendButton, toolCall, etc.).",layers:{palette:{description:"Primitive design tokens. Override specific shades to change the entire widget feel.",colors:{description:"7 color scales, each with shades 50 (lightest) to 950 (darkest). Override only the shades you need.",scales:{gray:"Neutrals \u2014 backgrounds, text, borders. Key shades: 50 (lightest bg), 100 (secondary bg), 200 (borders), 500 (muted text), 900 (primary text).",primary:"Brand color \u2014 buttons, links, interactive elements. Key shades: 500 (default), 600 (hover).",accent:"Secondary highlight. Key shades: 500 (default), 600 (hover).",secondary:"Tertiary color scale.",success:"Positive feedback (default: green).",warning:"Caution feedback (default: yellow).",error:"Error/danger feedback (default: red)."}},radius:{description:"Border radius scale. Add custom keys like launcher, button.",defaults:{none:"0px",sm:"0.125rem",md:"0.375rem",lg:"0.5rem",xl:"0.75rem","2xl":"1rem",full:"9999px"}},typography:{fontFamily:"Three stacks: sans (system-ui), serif (Georgia), mono (ui-monospace). Override individual stack values.",fontSize:"Scale: xs (0.75rem), sm (0.875rem), base (1rem), lg (1.125rem), xl (1.25rem), 2xl (1.5rem), 3xl (1.875rem), 4xl (2.25rem).",fontWeight:"normal (400), medium (500), semibold (600), bold (700).",lineHeight:"tight (1.25), normal (1.5), relaxed (1.625)."},shadows:"Scale: none, sm, md, lg, xl, 2xl. Values are CSS box-shadow strings.",borders:"Scale: none, sm (1px solid), md (2px solid), lg (4px solid).",spacing:"Scale: 0 (0px), 1 (0.25rem), 2 (0.5rem), 3 (0.75rem), 4 (1rem), 5 (1.25rem), 6 (1.5rem), 8 (2rem), 10 (2.5rem), 12 (3rem), 16-64."},semantic:{description:'Design intent tokens. Auto-derived from palette by default. Override to redirect token resolution. Values are token reference strings like "palette.colors.primary.500".',colors:{primary:"palette.colors.primary.500 \u2014 Primary brand color.",secondary:"palette.colors.gray.500 \u2014 Secondary color.",accent:"palette.colors.primary.600 \u2014 Accent/interactive color.",surface:"palette.colors.gray.50 \u2014 Panel/card backgrounds.",background:"palette.colors.gray.50 \u2014 Page background.",container:"palette.colors.gray.100 \u2014 Container backgrounds.",text:"palette.colors.gray.900 \u2014 Primary text.",textMuted:"palette.colors.gray.500 \u2014 Muted/secondary text.",textInverse:"palette.colors.gray.50 \u2014 Text on dark backgrounds.",border:"palette.colors.gray.200 \u2014 Default border color.",divider:"palette.colors.gray.200 \u2014 Divider lines.",interactive:{default:"palette.colors.primary.500",hover:"palette.colors.primary.600",focus:"palette.colors.primary.700",active:"palette.colors.primary.800",disabled:"palette.colors.gray.300"},feedback:{success:"palette.colors.success.500",warning:"palette.colors.warning.500",error:"palette.colors.error.500",info:"palette.colors.primary.500"}},spacing:"xs (0.25rem), sm (0.5rem), md (1rem), lg (1.5rem), xl (2rem), 2xl (2.5rem).",typography:"fontFamily, fontSize, fontWeight, lineHeight \u2014 reference palette typography tokens."},components:{description:"UI element tokens. Rarely needed for basic theming. Override for fine-grained control. All values are token references or raw CSS strings.",button:{description:"Three variants: primary, secondary, ghost.",properties:"background, foreground, borderRadius, padding."},input:{description:"Message input field.",properties:"background, placeholder, borderRadius, padding, focus.border, focus.ring."},launcher:{description:"Floating launcher button.",properties:"size (60px), iconSize (28px), borderRadius, shadow."},panel:{description:"Chat panel container.",properties:"width, maxWidth (400px), height (600px), maxHeight, borderRadius, shadow."},header:{description:"Chat panel header.",properties:"background, border, borderRadius, padding, iconBackground, iconForeground, titleForeground, subtitleForeground, actionIconForeground, shadow, borderBottom."},message:{description:"Chat message bubbles.",user:"background, text, borderRadius, shadow.",assistant:"background, text, borderRadius, border (optional), shadow (optional)."},markdown:{description:"Markdown rendering in messages and artifact pane.",properties:"inlineCode (background, foreground), link.foreground, prose.fontFamily, heading.h1/h2 (fontSize, fontWeight)."},voice:"recording (indicator, background, border), processing (icon, background), speaking (icon).",approval:"requested (background, border, text), approve (background, foreground), deny (background, foreground).",attachment:"image (background, border).",toolBubble:"shadow \u2014 tool call row box-shadow.",reasoningBubble:"shadow \u2014 reasoning/thinking row box-shadow.",composer:"shadow \u2014 message input form box-shadow.",artifact:"toolbar (icon styling, copy menu), tab (background, active states), pane (background, toolbarBackground)."}},colorScheme:'"dark" merges darkTheme overrides on top of theme. "auto" detects system preference or <html class="dark">. "light" is default. colorScheme does NOT auto-invert colors \u2014 provide dark palette and semantic overrides yourself.',plugins:{description:"Plugins transform theme tokens before resolution. Use with createTheme().",available:{brandPlugin:'Auto-generates full color scales from a single brand hex: brandPlugin({ colors: { primary: "#7c3aed" } }).',accessibilityPlugin:"Enhanced focus indicators and disabled states.",highContrastPlugin:"Increased contrast for visual accessibility.",reducedMotionPlugin:"Disables all animations (sets transitions to 0ms).",animationsPlugin:"Adds transition and easing tokens."},usage:'createTheme(themeOverrides, { plugins: [brandPlugin({ colors: { primary: "#7c3aed" } })] })'},widgetConfig:{description:'Non-theme config options on the widget config object that affect appearance. These are siblings of "theme" in the config, not nested inside it.',launcher:{description:"Floating launcher button and panel positioning.",properties:{enabled:"Show/hide the launcher button.",title:"Header title text.",subtitle:"Header subtitle text.",position:'"bottom-right" | "bottom-left" | "top-right" | "top-left".',width:"Chat panel width (CSS value).",fullHeight:"Fill full height of container.",mountMode:'"floating" | "docked".',agentIconText:"Emoji/text for agent icon.",border:"Border style for launcher button.",shadow:"Box shadow for launcher button.",collapsedMaxWidth:"Max-width for launcher pill when panel closed."}},sendButton:{description:"Send button appearance.",properties:"backgroundColor, textColor, borderWidth, borderColor, paddingX, paddingY, iconText, iconName, size."},closeButton:{description:"Close button (on launcher config).",properties:"closeButtonSize, closeButtonColor, closeButtonBackgroundColor, closeButtonBorderWidth, closeButtonBorderColor, closeButtonBorderRadius."},clearChat:{description:"Clear chat button (on launcher.clearChat config).",properties:"enabled, iconColor, backgroundColor, borderWidth, borderColor, borderRadius, size."},toolCall:{description:"Tool call display styling.",properties:"shadow, backgroundColor, borderColor, borderWidth, borderRadius, headerBackgroundColor, headerTextColor, headerPaddingX, headerPaddingY, contentBackgroundColor, contentTextColor, contentPaddingX, contentPaddingY, codeBlockBackgroundColor, codeBlockBorderColor, codeBlockTextColor, toggleTextColor, labelTextColor."},approval:{description:"Tool approval bubble styling and behavior. Set to false to disable.",properties:"backgroundColor, borderColor, titleColor, descriptionColor, approveButtonColor, approveButtonTextColor, denyButtonColor, denyButtonTextColor, parameterBackgroundColor, parameterTextColor, title, approveLabel, denyLabel."},copy:{description:"Widget text content.",properties:"showWelcomeCard (boolean), welcomeTitle, welcomeSubtitle, inputPlaceholder, sendButtonLabel."},voiceRecognition:{description:"Voice input configuration.",properties:"enabled, pauseDuration, iconColor, backgroundColor."},textToSpeech:{description:"Text-to-speech for assistant messages.",properties:'enabled, provider ("browser" | "runtype"), browserFallback, voice, rate, pitch.'},suggestionChips:"string[] \u2014 Suggested prompts shown to the user.",messageActions:{description:"Message action buttons (copy, upvote, downvote).",properties:'enabled, showCopy, showUpvote, showDownvote, visibility ("hover" | "always"), align ("left" | "center" | "right"), layout ("pill-inside" | "row-inside").'},attachments:{description:"File attachment configuration.",properties:"enabled, allowedTypes (string[]), maxFileSize (bytes), maxFiles, buttonIconName, buttonTooltipText."},markdown:{description:"Markdown rendering configuration.",properties:"options (gfm, breaks, headerIds, headerPrefix, pedantic, mangle, silent), disableDefaultStyles."},layout:{description:"Layout configuration.",showHeader:"boolean \u2014 show/hide the header section entirely.",showFooter:"boolean \u2014 show/hide the footer/composer section entirely.",contentMaxWidth:'CSS width value for centering content (e.g. "720px", "90ch").',header:'"default" | "minimal". Options: showIcon, showTitle, showSubtitle, showCloseButton, showClearChat.',messages:'"bubble" | "flat" | "minimal". Options: groupConsecutive, avatar (show, position, userAvatar, assistantAvatar), timestamp (show, position).'},statusIndicator:{description:"Status text shown below the composer.",properties:{visible:"Show/hide the status indicator.",align:'"left" | "center" | "right" \u2014 text alignment (default: "right").',idleText:'Text shown when idle (default: "Online").',idleLink:"URL to open when idle text is clicked (wraps text in a link).",connectingText:'Text shown while connecting (default: "Connecting\u2026").',connectedText:'Text shown while streaming (default: "Streaming\u2026").',errorText:'Text shown on error (default: "Offline").'}},features:{description:"Feature flags.",properties:"showReasoning (AI thinking steps), showToolCalls (tool invocations), artifacts (sidebar config)."}}},r={darkIndigo:{description:"Dark mode with indigo accent \u2014 override grays for dark backgrounds and semantic tokens for inverted text/surface",theme:{palette:{colors:{primary:{500:"#6366f1",600:"#4f46e5"},gray:{50:"#f1f5f9",100:"#1e293b",200:"#334155",500:"#94a3b8",900:"#0f172a",950:"#020617"}}},semantic:{colors:{surface:"palette.colors.gray.900",background:"palette.colors.gray.900",container:"palette.colors.gray.100",text:"palette.colors.gray.50",textMuted:"palette.colors.gray.500",textInverse:"palette.colors.gray.900",border:"palette.colors.gray.200"}}}},warmVintage:{description:"Warm sepia tones with serif font and subtle radius",theme:{palette:{colors:{primary:{500:"#b45309",600:"#92400e"},gray:{50:"#fef3c7",100:"#fef9c3",200:"#d6d3d1",500:"#78716c",900:"#44403c"}},radius:{sm:"0.125rem",md:"0.25rem",lg:"0.375rem"},typography:{fontFamily:{sans:'Georgia, Cambria, "Times New Roman", Times, serif'}}}}},neonCyberpunk:{description:"Neon on dark with monospace font \u2014 full semantic override for dark background",theme:{palette:{colors:{primary:{500:"#f0abfc",600:"#e879f9"},accent:{500:"#22d3ee",600:"#06b6d4"},gray:{50:"#f0abfc",100:"#1e0a3c",200:"#3b0764",500:"#c084fc",900:"#0c0a1a",950:"#050412"}},radius:{sm:"0",md:"0.25rem",lg:"0.375rem"},typography:{fontFamily:{sans:"ui-monospace, SFMono-Regular, Menlo, monospace"}}},semantic:{colors:{surface:"palette.colors.gray.900",background:"palette.colors.gray.950",container:"palette.colors.gray.100",text:"palette.colors.gray.50",textMuted:"palette.colors.gray.500",border:"palette.colors.gray.200"}}}},cleanRounded:{description:"Clean light theme with large radius and panel styling",theme:{palette:{radius:{sm:"6px",md:"8px",lg:"12px",launcher:"50px",button:"8px"}},components:{panel:{borderRadius:"16px",shadow:"palette.shadows.2xl"}}}}};function n(){return{tokenDocs:o,defaultColorPalette:e.colors,defaultRadius:e.radius,examples:r,sdkPresets:["shop","minimal","fullscreen"]}}export{r as THEME_EXAMPLES,o as THEME_TOKEN_DOCS,n as getThemeReference};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@runtypelabs/persona",
-  "version": "3.3.0",
+  "version": "3.5.0",
   "description": "Themeable, pluggable streaming agent widget for websites, in plain JS with support for voice input and reasoning / tool output.",
   "type": "module",
   "main": "dist/index.cjs",
@@ -12,6 +12,11 @@
       "import": "./dist/index.js",
       "require": "./dist/index.cjs"
     },
+    "./theme-reference": {
+      "types": "./dist/theme-reference.d.ts",
+      "import": "./dist/theme-reference.js",
+      "require": "./dist/theme-reference.cjs"
+    },
     "./widget.css": {
       "import": "./widget.css",
       "default": "./dist/widget.css"
@@ -70,7 +75,8 @@
     "access": "public"
   },
   "scripts": {
-    "build": "rimraf dist && pnpm run build:styles && pnpm run build:client && pnpm run build:installer",
+    "build": "rimraf dist && pnpm run build:styles && pnpm run build:client && pnpm run build:installer && pnpm run build:theme-ref",
+    "build:theme-ref": "tsup src/theme-reference.ts --format esm,cjs --minify --dts",
     "build:styles": "node -e \"const fs=require('fs');fs.mkdirSync('dist',{recursive:true});fs.copyFileSync('src/styles/widget.css','dist/widget.css');\"",
     "build:client": "tsup src/index.ts --format esm,cjs,iife --global-name AgentWidget --minify --sourcemap --splitting false --dts --loader \".css=text\"",
     "build:installer": "tsup src/install.ts --format iife --global-name SiteAgentInstaller --out-dir dist --minify --sourcemap --no-splitting",

package/src/components/panel.ts

@@ -164,14 +164,14 @@ export const buildPanel = (config?: AgentWidgetConfig, showClose = true): PanelE
     messagesWrapper.style.width = "100%";
   }
 
+  introCard.setAttribute("data-persona-intro-card", "");
   const showWelcomeCard = config?.copy?.showWelcomeCard !== false;
   if (!showWelcomeCard) {
+    introCard.style.display = "none";
     body.classList.remove("persona-gap-6");
     body.classList.add("persona-gap-3");
-    body.append(messagesWrapper);
-  } else {
-    body.append(introCard, messagesWrapper);
   }
+  body.append(introCard, messagesWrapper);
 
   // Build composer/footer using extracted builder
   const composerElements: ComposerElements = buildComposer({ config });

package/src/theme-reference.ts

@@ -0,0 +1,414 @@
+/**
+ * Theme Reference — Structured documentation and examples for the Persona v2 theme system.
+ *
+ * Exported via the `@runtypelabs/persona/theme-reference` entry point so it stays
+ * out of the IIFE widget bundle. Intended for AI/MCP tool consumption.
+ */
+
+import { DEFAULT_PALETTE } from './utils/tokens'
+import type { DeepPartial, PersonaTheme } from './types/theme'
+
+// ---------------------------------------------------------------------------
+// Token System Documentation
+// ---------------------------------------------------------------------------
+
+export const THEME_TOKEN_DOCS = {
+  overview:
+    'Persona uses a three-layer design token system: palette → semantic → components. Most themes only need palette.colors overrides — semantic and component layers auto-derive from palette values. Config also accepts non-theme appearance options (launcher, sendButton, toolCall, etc.).',
+
+  layers: {
+    palette: {
+      description:
+        'Primitive design tokens. Override specific shades to change the entire widget feel.',
+      colors: {
+        description:
+          '7 color scales, each with shades 50 (lightest) to 950 (darkest). Override only the shades you need.',
+        scales: {
+          gray: 'Neutrals — backgrounds, text, borders. Key shades: 50 (lightest bg), 100 (secondary bg), 200 (borders), 500 (muted text), 900 (primary text).',
+          primary:
+            'Brand color — buttons, links, interactive elements. Key shades: 500 (default), 600 (hover).',
+          accent: 'Secondary highlight. Key shades: 500 (default), 600 (hover).',
+          secondary: 'Tertiary color scale.',
+          success: 'Positive feedback (default: green).',
+          warning: 'Caution feedback (default: yellow).',
+          error: 'Error/danger feedback (default: red).',
+        },
+      },
+      radius: {
+        description: 'Border radius scale. Add custom keys like launcher, button.',
+        defaults: {
+          none: '0px',
+          sm: '0.125rem',
+          md: '0.375rem',
+          lg: '0.5rem',
+          xl: '0.75rem',
+          '2xl': '1rem',
+          full: '9999px',
+        },
+      },
+      typography: {
+        fontFamily:
+          'Three stacks: sans (system-ui), serif (Georgia), mono (ui-monospace). Override individual stack values.',
+        fontSize:
+          'Scale: xs (0.75rem), sm (0.875rem), base (1rem), lg (1.125rem), xl (1.25rem), 2xl (1.5rem), 3xl (1.875rem), 4xl (2.25rem).',
+        fontWeight: 'normal (400), medium (500), semibold (600), bold (700).',
+        lineHeight: 'tight (1.25), normal (1.5), relaxed (1.625).',
+      },
+      shadows:
+        'Scale: none, sm, md, lg, xl, 2xl. Values are CSS box-shadow strings.',
+      borders: 'Scale: none, sm (1px solid), md (2px solid), lg (4px solid).',
+      spacing:
+        'Scale: 0 (0px), 1 (0.25rem), 2 (0.5rem), 3 (0.75rem), 4 (1rem), 5 (1.25rem), 6 (1.5rem), 8 (2rem), 10 (2.5rem), 12 (3rem), 16-64.',
+    },
+
+    semantic: {
+      description:
+        'Design intent tokens. Auto-derived from palette by default. Override to redirect token resolution. Values are token reference strings like "palette.colors.primary.500".',
+      colors: {
+        primary: 'palette.colors.primary.500 — Primary brand color.',
+        secondary: 'palette.colors.gray.500 — Secondary color.',
+        accent: 'palette.colors.primary.600 — Accent/interactive color.',
+        surface: 'palette.colors.gray.50 — Panel/card backgrounds.',
+        background: 'palette.colors.gray.50 — Page background.',
+        container: 'palette.colors.gray.100 — Container backgrounds.',
+        text: 'palette.colors.gray.900 — Primary text.',
+        textMuted: 'palette.colors.gray.500 — Muted/secondary text.',
+        textInverse: 'palette.colors.gray.50 — Text on dark backgrounds.',
+        border: 'palette.colors.gray.200 — Default border color.',
+        divider: 'palette.colors.gray.200 — Divider lines.',
+        interactive: {
+          default: 'palette.colors.primary.500',
+          hover: 'palette.colors.primary.600',
+          focus: 'palette.colors.primary.700',
+          active: 'palette.colors.primary.800',
+          disabled: 'palette.colors.gray.300',
+        },
+        feedback: {
+          success: 'palette.colors.success.500',
+          warning: 'palette.colors.warning.500',
+          error: 'palette.colors.error.500',
+          info: 'palette.colors.primary.500',
+        },
+      },
+      spacing:
+        'xs (0.25rem), sm (0.5rem), md (1rem), lg (1.5rem), xl (2rem), 2xl (2.5rem).',
+      typography:
+        'fontFamily, fontSize, fontWeight, lineHeight — reference palette typography tokens.',
+    },
+
+    components: {
+      description:
+        'UI element tokens. Rarely needed for basic theming. Override for fine-grained control. All values are token references or raw CSS strings.',
+      button: {
+        description: 'Three variants: primary, secondary, ghost.',
+        properties: 'background, foreground, borderRadius, padding.',
+      },
+      input: {
+        description: 'Message input field.',
+        properties:
+          'background, placeholder, borderRadius, padding, focus.border, focus.ring.',
+      },
+      launcher: {
+        description: 'Floating launcher button.',
+        properties: 'size (60px), iconSize (28px), borderRadius, shadow.',
+      },
+      panel: {
+        description: 'Chat panel container.',
+        properties:
+          'width, maxWidth (400px), height (600px), maxHeight, borderRadius, shadow.',
+      },
+      header: {
+        description: 'Chat panel header.',
+        properties:
+          'background, border, borderRadius, padding, iconBackground, iconForeground, titleForeground, subtitleForeground, actionIconForeground, shadow, borderBottom.',
+      },
+      message: {
+        description: 'Chat message bubbles.',
+        user: 'background, text, borderRadius, shadow.',
+        assistant:
+          'background, text, borderRadius, border (optional), shadow (optional).',
+      },
+      markdown: {
+        description: 'Markdown rendering in messages and artifact pane.',
+        properties:
+          'inlineCode (background, foreground), link.foreground, prose.fontFamily, heading.h1/h2 (fontSize, fontWeight).',
+      },
+      voice:
+        'recording (indicator, background, border), processing (icon, background), speaking (icon).',
+      approval:
+        'requested (background, border, text), approve (background, foreground), deny (background, foreground).',
+      attachment: 'image (background, border).',
+      toolBubble: 'shadow — tool call row box-shadow.',
+      reasoningBubble: 'shadow — reasoning/thinking row box-shadow.',
+      composer: 'shadow — message input form box-shadow.',
+      artifact:
+        'toolbar (icon styling, copy menu), tab (background, active states), pane (background, toolbarBackground).',
+    },
+  },
+
+  colorScheme:
+    '"dark" merges darkTheme overrides on top of theme. "auto" detects system preference or <html class="dark">. "light" is default. colorScheme does NOT auto-invert colors — provide dark palette and semantic overrides yourself.',
+
+  plugins: {
+    description:
+      'Plugins transform theme tokens before resolution. Use with createTheme().',
+    available: {
+      brandPlugin:
+        'Auto-generates full color scales from a single brand hex: brandPlugin({ colors: { primary: "#7c3aed" } }).',
+      accessibilityPlugin:
+        'Enhanced focus indicators and disabled states.',
+      highContrastPlugin: 'Increased contrast for visual accessibility.',
+      reducedMotionPlugin:
+        'Disables all animations (sets transitions to 0ms).',
+      animationsPlugin: 'Adds transition and easing tokens.',
+    },
+    usage:
+      'createTheme(themeOverrides, { plugins: [brandPlugin({ colors: { primary: "#7c3aed" } })] })',
+  },
+
+  widgetConfig: {
+    description:
+      'Non-theme config options on the widget config object that affect appearance. These are siblings of "theme" in the config, not nested inside it.',
+    launcher: {
+      description: 'Floating launcher button and panel positioning.',
+      properties: {
+        enabled: 'Show/hide the launcher button.',
+        title: 'Header title text.',
+        subtitle: 'Header subtitle text.',
+        position:
+          '"bottom-right" | "bottom-left" | "top-right" | "top-left".',
+        width: 'Chat panel width (CSS value).',
+        fullHeight: 'Fill full height of container.',
+        mountMode: '"floating" | "docked".',
+        agentIconText: 'Emoji/text for agent icon.',
+        border: 'Border style for launcher button.',
+        shadow: 'Box shadow for launcher button.',
+        collapsedMaxWidth: 'Max-width for launcher pill when panel closed.',
+      },
+    },
+    sendButton: {
+      description: 'Send button appearance.',
+      properties:
+        'backgroundColor, textColor, borderWidth, borderColor, paddingX, paddingY, iconText, iconName, size.',
+    },
+    closeButton: {
+      description: 'Close button (on launcher config).',
+      properties:
+        'closeButtonSize, closeButtonColor, closeButtonBackgroundColor, closeButtonBorderWidth, closeButtonBorderColor, closeButtonBorderRadius.',
+    },
+    clearChat: {
+      description: 'Clear chat button (on launcher.clearChat config).',
+      properties:
+        'enabled, iconColor, backgroundColor, borderWidth, borderColor, borderRadius, size.',
+    },
+    toolCall: {
+      description: 'Tool call display styling.',
+      properties:
+        'shadow, backgroundColor, borderColor, borderWidth, borderRadius, headerBackgroundColor, headerTextColor, headerPaddingX, headerPaddingY, contentBackgroundColor, contentTextColor, contentPaddingX, contentPaddingY, codeBlockBackgroundColor, codeBlockBorderColor, codeBlockTextColor, toggleTextColor, labelTextColor.',
+    },
+    approval: {
+      description:
+        'Tool approval bubble styling and behavior. Set to false to disable.',
+      properties:
+        'backgroundColor, borderColor, titleColor, descriptionColor, approveButtonColor, approveButtonTextColor, denyButtonColor, denyButtonTextColor, parameterBackgroundColor, parameterTextColor, title, approveLabel, denyLabel.',
+    },
+    copy: {
+      description: 'Widget text content.',
+      properties:
+        'showWelcomeCard (boolean), welcomeTitle, welcomeSubtitle, inputPlaceholder, sendButtonLabel.',
+    },
+    voiceRecognition: {
+      description: 'Voice input configuration.',
+      properties: 'enabled, pauseDuration, iconColor, backgroundColor.',
+    },
+    textToSpeech: {
+      description: 'Text-to-speech for assistant messages.',
+      properties:
+        'enabled, provider ("browser" | "runtype"), browserFallback, voice, rate, pitch.',
+    },
+    suggestionChips:
+      'string[] — Suggested prompts shown to the user.',
+    messageActions: {
+      description: 'Message action buttons (copy, upvote, downvote).',
+      properties:
+        'enabled, showCopy, showUpvote, showDownvote, visibility ("hover" | "always"), align ("left" | "center" | "right"), layout ("pill-inside" | "row-inside").',
+    },
+    attachments: {
+      description: 'File attachment configuration.',
+      properties:
+        'enabled, allowedTypes (string[]), maxFileSize (bytes), maxFiles, buttonIconName, buttonTooltipText.',
+    },
+    markdown: {
+      description: 'Markdown rendering configuration.',
+      properties:
+        'options (gfm, breaks, headerIds, headerPrefix, pedantic, mangle, silent), disableDefaultStyles.',
+    },
+    layout: {
+      description: 'Layout configuration.',
+      showHeader: 'boolean — show/hide the header section entirely.',
+      showFooter: 'boolean — show/hide the footer/composer section entirely.',
+      contentMaxWidth:
+        'CSS width value for centering content (e.g. "720px", "90ch").',
+      header:
+        '"default" | "minimal". Options: showIcon, showTitle, showSubtitle, showCloseButton, showClearChat.',
+      messages:
+        '"bubble" | "flat" | "minimal". Options: groupConsecutive, avatar (show, position, userAvatar, assistantAvatar), timestamp (show, position).',
+    },
+    statusIndicator: {
+      description: 'Status text shown below the composer.',
+      properties: {
+        visible: 'Show/hide the status indicator.',
+        align: '"left" | "center" | "right" — text alignment (default: "right").',
+        idleText: 'Text shown when idle (default: "Online").',
+        idleLink: 'URL to open when idle text is clicked (wraps text in a link).',
+        connectingText: 'Text shown while connecting (default: "Connecting…").',
+        connectedText: 'Text shown while streaming (default: "Streaming…").',
+        errorText: 'Text shown on error (default: "Offline").',
+      },
+    },
+    features: {
+      description: 'Feature flags.',
+      properties:
+        'showReasoning (AI thinking steps), showToolCalls (tool invocations), artifacts (sidebar config).',
+    },
+  },
+}
+
+// ---------------------------------------------------------------------------
+// Example Themes
+// ---------------------------------------------------------------------------
+
+export interface ThemeExample {
+  description: string
+  colorScheme?: 'light' | 'dark' | 'auto'
+  theme: DeepPartial<PersonaTheme>
+}
+
+export const THEME_EXAMPLES: Record<string, ThemeExample> = {
+  darkIndigo: {
+    description:
+      'Dark mode with indigo accent — override grays for dark backgrounds and semantic tokens for inverted text/surface',
+    theme: {
+      palette: {
+        colors: {
+          primary: { 500: '#6366f1', 600: '#4f46e5' },
+          gray: {
+            50: '#f1f5f9',
+            100: '#1e293b',
+            200: '#334155',
+            500: '#94a3b8',
+            900: '#0f172a',
+            950: '#020617',
+          },
+        },
+      },
+      semantic: {
+        colors: {
+          surface: 'palette.colors.gray.900',
+          background: 'palette.colors.gray.900',
+          container: 'palette.colors.gray.100',
+          text: 'palette.colors.gray.50',
+          textMuted: 'palette.colors.gray.500',
+          textInverse: 'palette.colors.gray.900',
+          border: 'palette.colors.gray.200',
+        },
+      },
+    },
+  },
+  warmVintage: {
+    description: 'Warm sepia tones with serif font and subtle radius',
+    theme: {
+      palette: {
+        colors: {
+          primary: { 500: '#b45309', 600: '#92400e' },
+          gray: {
+            50: '#fef3c7',
+            100: '#fef9c3',
+            200: '#d6d3d1',
+            500: '#78716c',
+            900: '#44403c',
+          },
+        },
+        radius: { sm: '0.125rem', md: '0.25rem', lg: '0.375rem' },
+        typography: {
+          fontFamily: {
+            sans: 'Georgia, Cambria, "Times New Roman", Times, serif',
+          },
+        },
+      },
+    },
+  },
+  neonCyberpunk: {
+    description:
+      'Neon on dark with monospace font — full semantic override for dark background',
+    theme: {
+      palette: {
+        colors: {
+          primary: { 500: '#f0abfc', 600: '#e879f9' },
+          accent: { 500: '#22d3ee', 600: '#06b6d4' },
+          gray: {
+            50: '#f0abfc',
+            100: '#1e0a3c',
+            200: '#3b0764',
+            500: '#c084fc',
+            900: '#0c0a1a',
+            950: '#050412',
+          },
+        },
+        radius: { sm: '0', md: '0.25rem', lg: '0.375rem' },
+        typography: {
+          fontFamily: {
+            sans: 'ui-monospace, SFMono-Regular, Menlo, monospace',
+          },
+        },
+      },
+      semantic: {
+        colors: {
+          surface: 'palette.colors.gray.900',
+          background: 'palette.colors.gray.950',
+          container: 'palette.colors.gray.100',
+          text: 'palette.colors.gray.50',
+          textMuted: 'palette.colors.gray.500',
+          border: 'palette.colors.gray.200',
+        },
+      },
+    },
+  },
+  cleanRounded: {
+    description: 'Clean light theme with large radius and panel styling',
+    theme: {
+      palette: {
+        radius: {
+          sm: '6px',
+          md: '8px',
+          lg: '12px',
+          launcher: '50px',
+          button: '8px',
+        },
+      },
+      components: {
+        panel: { borderRadius: '16px', shadow: 'palette.shadows.2xl' },
+      },
+    },
+  },
+}
+
+// ---------------------------------------------------------------------------
+// Reference Payload
+// ---------------------------------------------------------------------------
+
+/**
+ * Complete theme reference payload for AI / MCP tool consumption.
+ *
+ * Returns token system docs, the default color palette and radius scale,
+ * example themes, and a list of SDK-bundled presets.
+ */
+export function getThemeReference() {
+  return {
+    tokenDocs: THEME_TOKEN_DOCS,
+    defaultColorPalette: DEFAULT_PALETTE.colors,
+    defaultRadius: DEFAULT_PALETTE.radius,
+    examples: THEME_EXAMPLES,
+    sdkPresets: ['shop', 'minimal', 'fullscreen'],
+  }
+}

package/src/ui.ts

@@ -2624,6 +2624,20 @@ export const createAgentExperience = (
       "Ask anything about your account or products.";
     textarea.placeholder = config.copy?.inputPlaceholder ?? "How can I help...";
 
+    // Toggle welcome card visibility
+    const introCard = body.querySelector("[data-persona-intro-card]") as HTMLElement | null;
+    if (introCard) {
+      const showCard = config.copy?.showWelcomeCard !== false;
+      introCard.style.display = showCard ? "" : "none";
+      if (showCard) {
+        body.classList.remove("persona-gap-3");
+        body.classList.add("persona-gap-6");
+      } else {
+        body.classList.remove("persona-gap-6");
+        body.classList.add("persona-gap-3");
+      }
+    }
+
     // Only update send button text if NOT using icon mode
     const useIcon = config.sendButton?.useIcon ?? false;
     if (!useIcon) {
@@ -4824,6 +4838,30 @@ export const createAgentExperience = (
         tooltip.style.display = "none";
       }
       
+      // Update contentMaxWidth on messages wrapper and composer
+      const updatedContentMaxWidth = config.layout?.contentMaxWidth;
+      if (updatedContentMaxWidth) {
+        messagesWrapper.style.maxWidth = updatedContentMaxWidth;
+        messagesWrapper.style.marginLeft = "auto";
+        messagesWrapper.style.marginRight = "auto";
+        messagesWrapper.style.width = "100%";
+        if (composerForm) {
+          composerForm.style.maxWidth = updatedContentMaxWidth;
+          composerForm.style.marginLeft = "auto";
+          composerForm.style.marginRight = "auto";
+        }
+      } else {
+        messagesWrapper.style.maxWidth = "";
+        messagesWrapper.style.marginLeft = "";
+        messagesWrapper.style.marginRight = "";
+        messagesWrapper.style.width = "";
+        if (composerForm) {
+          composerForm.style.maxWidth = "";
+          composerForm.style.marginLeft = "";
+          composerForm.style.marginRight = "";
+        }
+      }
+
       // Update status indicator visibility and text
       const statusIndicatorConfig = config.statusIndicator ?? {};
       const isVisible = statusIndicatorConfig.visible ?? true;
@@ -4841,6 +4879,13 @@ export const createAgentExperience = (
         };
         applyStatusToElement(statusText, getCurrentStatusText(currentStatus), statusIndicatorConfig, currentStatus);
       }
+
+      // Update status text alignment
+      statusText.classList.remove("persona-text-left", "persona-text-center", "persona-text-right");
+      const alignClass = statusIndicatorConfig.align === "left" ? "persona-text-left"
+        : statusIndicatorConfig.align === "center" ? "persona-text-center"
+        : "persona-text-right";
+      statusText.classList.add(alignClass);
     },
     open() {
       if (!launcherEnabled) return;