@runtypelabs/persona 4.15.0 → 4.17.0

package/src/styles/widget.css

@@ -4,6 +4,10 @@
   font-size: var(--persona-font-size, 1rem);
   font-weight: var(--persona-font-weight, 400);
   line-height: var(--persona-line-height, 1.5);
+
+  /* Column widths plugin content can consume; --persona-content-max-width is
+     re-set inline from layout.contentMaxWidth (default 768px). */
+  --persona-welcome-max-width: 640px;
   
   /* Theme-aware markdown variables - inherit from theme colors set by JavaScript */
   --persona-md-code-block-bg: var(--persona-container, #f3f4f6);
@@ -236,6 +240,157 @@
   border-radius: var(--persona-button-radius);
 }
 
+/* Launcher surface + teaser --------------------------------------------- */
+
+/* Without a teaser the wrapper generates no box, so the launcher button keeps
+   its own fixed placement exactly as it did before the wrapper existed. */
+.persona-launcher-surface {
+  display: contents;
+}
+
+.persona-launcher-surface[data-teaser] {
+  display: flex;
+  position: fixed;
+  flex-direction: column;
+  align-items: flex-end;
+  gap: 10px;
+}
+
+.persona-launcher-surface[data-teaser^="top"] {
+  flex-direction: column-reverse;
+}
+
+.persona-launcher-surface[data-teaser$="left"] {
+  align-items: flex-start;
+}
+
+.persona-launcher-teaser {
+  display: flex;
+  align-items: flex-start;
+  gap: 2px;
+  max-width: min(260px, calc(100vw - 48px));
+  padding: 2px;
+  border: 1px solid var(--persona-border, #e5e7eb);
+  border-radius: var(--persona-radius-lg, 1rem);
+  background-color: var(--persona-surface, #ffffff);
+  box-shadow: var(
+    --persona-launcher-shadow,
+    0 10px 15px -3px rgba(0, 0, 0, 0.1),
+    0 4px 6px -4px rgba(0, 0, 0, 0.1)
+  );
+}
+
+.persona-launcher-teaser[hidden] {
+  display: none;
+}
+
+.persona-launcher-teaser-text {
+  flex: 1 1 auto;
+  min-width: 0;
+  padding: 8px 10px;
+  border: 0;
+  border-radius: inherit;
+  background: transparent;
+  color: var(--persona-text, #111827);
+  font: inherit;
+  font-size: 0.875rem;
+  line-height: 1.4;
+  text-align: left;
+  cursor: pointer;
+}
+
+.persona-launcher-teaser-dismiss {
+  flex: 0 0 auto;
+  display: grid;
+  place-items: center;
+  width: 22px;
+  height: 22px;
+  margin-top: 4px;
+  padding: 0;
+  border: 0;
+  border-radius: var(--persona-launcher-radius, 9999px);
+  background: transparent;
+  color: var(--persona-muted, #6b7280);
+  font-size: 0.875rem;
+  line-height: 1;
+  cursor: pointer;
+}
+
+.persona-launcher-teaser-dismiss:hover {
+  background-color: var(--persona-border, #e5e7eb);
+}
+
+/* display: grid above beats the UA [hidden] rule; dismissible: false relies on this. */
+.persona-launcher-teaser-dismiss[hidden] {
+  display: none;
+}
+
+/* An empty transcript still counts as a flex child, so the body's gap
+   inserts phantom space below the welcome and fakes scrollable height. */
+.persona-widget-messages:empty {
+  display: none;
+}
+
+/* Scrollbars ------------------------------------------------------------- */
+
+/* One appearance for every scroller in the widget: thin, themed thumb, bare
+   track. Standard properties only: mixing ::-webkit-scrollbar styling with
+   them makes Chromium drop the pseudo-element rules, so webkit selectors are
+   reserved for the hidden states below, where both mechanisms agree.
+   scrollbar-color inherits from the root; scrollbar-width does not, hence
+   the descendant rule. */
+[data-persona-root] {
+  scrollbar-color: var(
+      --persona-scrollbar-thumb,
+      var(--persona-border, #e5e7eb)
+    )
+    var(--persona-scrollbar-track, transparent);
+}
+[data-persona-root],
+[data-persona-root] * {
+  scrollbar-width: thin;
+}
+
+/* "on-scroll" policy (the default): bars hide at rest. ui.ts stamps the
+   resolved policy on the root and flips data-persona-scrollbar-visible on
+   the transcript while the reader is scrolling or away from the resting
+   position. The reserved gutter keeps classic scrollbars (Windows,
+   always-show macOS) from reflowing the transcript on toggle. */
+[data-persona-scrollbar="on-scroll"] .persona-widget-body {
+  scrollbar-gutter: stable;
+}
+[data-persona-scrollbar="on-scroll"]
+  .persona-widget-body:not([data-persona-scrollbar-visible]),
+[data-persona-scrollbar="hidden"] .persona-widget-body {
+  scrollbar-width: none;
+}
+[data-persona-scrollbar="on-scroll"]
+  .persona-widget-body:not([data-persona-scrollbar-visible])::-webkit-scrollbar,
+[data-persona-scrollbar="hidden"] .persona-widget-body::-webkit-scrollbar {
+  display: none;
+}
+
+/* Inner scrollers under the same policy: hidden at rest, hover reveals for
+   pointer users. Edge fades stay the primary overflow affordance there, and
+   morph re-renders make per-element JS wiring fragile, so hover is the whole
+   reveal story for these surfaces. */
+[data-persona-scrollbar="on-scroll"] .persona-artifact-list:not(:hover),
+[data-persona-scrollbar="on-scroll"]
+  .persona-suggestions[data-overflow="scroll"]:not(:hover),
+[data-persona-scrollbar="hidden"] .persona-artifact-list,
+[data-persona-scrollbar="hidden"] .persona-suggestions[data-overflow="scroll"] {
+  scrollbar-width: none;
+}
+[data-persona-scrollbar="on-scroll"]
+  .persona-artifact-list:not(:hover)::-webkit-scrollbar,
+[data-persona-scrollbar="on-scroll"]
+  .persona-suggestions[data-overflow="scroll"]:not(:hover)::-webkit-scrollbar,
+[data-persona-scrollbar="hidden"] .persona-artifact-list::-webkit-scrollbar,
+[data-persona-scrollbar="hidden"]
+  .persona-suggestions[data-overflow="scroll"]::-webkit-scrollbar {
+  display: none;
+}
+
 /* Suggestions ----------------------------------------------------------- */
 
 .persona-suggestions {
@@ -254,13 +409,28 @@
   display: none !important;
 }
 
+/* `itemGap` is the space between items; the variant-less 8px above stays the
+   fallback for containers rendered before a variant is assigned. */
+.persona-suggestions[data-variant="chip"] {
+  gap: var(--persona-components-suggestion-chip-itemGap, 8px);
+}
+
+.persona-suggestions[data-variant="card"] {
+  gap: var(--persona-components-suggestion-card-itemGap, 8px);
+}
+
+.persona-suggestions[data-variant="list"] {
+  gap: var(--persona-components-suggestion-list-itemGap, 8px);
+}
+
 .persona-suggestions[data-persona-suggestion-surface="starter"] {
   margin-top: 16px;
 }
 
-[data-persona-suggestions="follow-up"] {
-  /* The transcript body uses a roomy 24px section gap; pull contextual
-     follow-ups closer to the answer they belong to. */
+/* Follow-ups sit 12px from their answer. The body gap is 24px with the
+   welcome host visible and already 12px when it is hidden, so the pull-up
+   only applies in the roomy case. */
+.persona-gap-6 > [data-persona-suggestions="follow-up"] {
   margin-top: -12px;
 }
 
@@ -352,6 +522,15 @@
   flex-wrap: wrap;
 }
 
+/* Composer surface only: transcript follow-ups and welcome rows stay
+   left-aligned. fit-content centers a single row while wrapped rows keep a
+   shared left edge; per-row `justify-content: center` would rag them. */
+[data-persona-composer-suggestions].persona-suggestions[data-variant="chip"] {
+  width: fit-content;
+  max-width: 100%;
+  margin-inline: auto;
+}
+
 .persona-suggestion {
   appearance: none;
   display: flex;
@@ -398,7 +577,7 @@
 }
 
 .persona-suggestion--card {
-  align-items: flex-start;
+  align-items: center;
   min-height: var(--persona-components-suggestion-card-minHeight, 72px);
   gap: var(--persona-components-suggestion-card-gap, 0.625rem);
   padding: var(--persona-components-suggestion-card-padding, 1rem);
@@ -422,7 +601,7 @@
 }
 
 .persona-suggestion--list {
-  align-items: flex-start;
+  align-items: center;
   width: 100%;
   min-height: var(--persona-components-suggestion-list-minHeight, 44px);
   gap: var(--persona-components-suggestion-list-gap, 0.625rem);
@@ -445,6 +624,13 @@
   line-height: var(--persona-components-suggestion-list-lineHeight, 1.35);
 }
 
+/* Title + description content reads top-aligned; a lone label centers in
+   the min-height instead of leaving dead space under the text. */
+.persona-suggestion--card:has(.persona-suggestion__description),
+.persona-suggestion--list:has(.persona-suggestion__description) {
+  align-items: flex-start;
+}
+
 .persona-suggestion__icon,
 .persona-suggestion__arrow {
   flex: 0 0 auto;
@@ -648,6 +834,154 @@
   }
 }
 
+/* Welcome surface ------------------------------------------------------- */
+
+/* Interior padding rides the intro-card alias: the tokens layer zeroes the
+   horizontal component when the card resolves flat (no background, no
+   shadow), so default installs align the title with the content column
+   instead of indenting it by an invisible card inset. */
+.persona-welcome {
+  padding: var(--persona-intro-card-padding, 1.5rem);
+}
+
+.persona-welcome[hidden],
+.persona-welcome-greeting[hidden] {
+  display: none !important;
+}
+
+.persona-welcome-icon {
+  display: flex;
+  margin-bottom: 12px;
+  color: var(--persona-accent, currentColor);
+}
+
+.persona-welcome-icon[hidden] {
+  display: none !important;
+}
+
+.persona-welcome-icon-image {
+  width: 40px;
+  height: 40px;
+  border-radius: 999px;
+  object-fit: cover;
+}
+
+.persona-welcome-icon-text {
+  font-size: 32px;
+  line-height: 1;
+}
+
+/* Welcome copy: `components.introCard.title` / `.subtitle` typography.
+   Fallbacks reproduce the utility classes these rules replaced, so an
+   unset token renders pixel-identically. Margins stay untokenized. */
+.persona-welcome-title {
+  font-family: var(--persona-components-introCard-title-fontFamily, inherit);
+  font-size: var(--persona-components-introCard-title-fontSize, 1.125rem);
+  font-weight: var(--persona-components-introCard-title-fontWeight, 600);
+  line-height: var(--persona-components-introCard-title-lineHeight, 1.75rem);
+  letter-spacing: var(--persona-components-introCard-title-letterSpacing, normal);
+  color: var(--persona-components-introCard-title-color, var(--persona-primary, #171717));
+}
+
+.persona-welcome-subtitle {
+  margin-top: 0.5rem;
+  font-family: var(--persona-components-introCard-subtitle-fontFamily, inherit);
+  font-size: var(--persona-components-introCard-subtitle-fontSize, 0.875rem);
+  font-weight: var(--persona-components-introCard-subtitle-fontWeight, inherit);
+  line-height: var(--persona-components-introCard-subtitle-lineHeight, 1.25rem);
+  letter-spacing: var(--persona-components-introCard-subtitle-letterSpacing, normal);
+  color: var(--persona-components-introCard-subtitle-color, var(--persona-muted, #6b7280));
+}
+
+/* Plugin-owned welcome (`renderWelcome`): the host keeps its position and the
+   default children are hidden by selector, so nothing about their own hidden
+   state has to be saved and restored when the plugin returns null again. */
+.persona-welcome[data-persona-welcome-content="plugin"]
+  > :not([data-persona-welcome-plugin]) {
+  display: none !important;
+}
+
+.persona-welcome[data-persona-welcome-content="plugin"] {
+  background: transparent;
+  box-shadow: none;
+}
+
+/* Overlay state: a plugin element covers the messages area while it is active.
+   The body stops scrolling underneath so the absolute box maps to the visible
+   transcript rather than scrolling away with the content. */
+/* Wide panels: the card variant shares the transcript column
+   (--persona-content-max-width, re-set inline from layout.contentMaxWidth)
+   so its left-aligned text lines up with messages and composer; at launcher
+   width the cap never bites. The plugin overlay stays full-bleed via the
+   :not(). */
+.persona-welcome:not([data-persona-welcome-overlay]) {
+  width: 100%;
+  max-width: var(--persona-content-max-width, 768px);
+  margin-inline: auto;
+}
+
+/* The centered hero keeps the narrower consumer-product column, where
+   centered text makes the split against the transcript read as intended. */
+.persona-welcome[data-persona-welcome-variant="hero"]:not(
+    [data-persona-welcome-overlay]
+  ) {
+  max-width: var(--persona-welcome-max-width, 640px);
+}
+
+/* The greeting bubble is a sibling of the transcript wrapper, outside its
+   inline width cap; mirror the cap so it shares the same column. */
+.persona-welcome-greeting {
+  width: 100%;
+  max-width: var(--persona-content-max-width, 768px);
+  margin-inline: auto;
+}
+
+.persona-welcome[data-persona-welcome-overlay] {
+  position: absolute;
+  inset: 0;
+  z-index: 5;
+  overflow-y: auto;
+  /* Plugin overlays are opaque surfaces regardless of the intro-card theme,
+     so they keep full interior padding even when the card resolves flat. */
+  padding: 1.5rem;
+  /* !important: the host doubles as the intro card and carries an inline
+     background (--persona-intro-card-bg, default transparent); the overlay
+     must stay opaque or the transcript bleeds through the plugin stack. */
+  background: var(
+    --persona-container,
+    var(--persona-surface, #ffffff)
+  ) !important;
+}
+
+.persona-widget-body.persona-welcome-overlay-active {
+  overflow: hidden;
+}
+
+/* Hero: auto block margins center the surface in the empty conversation
+   without `justify-content`, which would make overflowing content
+   unreachable in the scroll body. */
+.persona-welcome[data-persona-welcome-variant="hero"] {
+  margin-block: auto;
+  text-align: center;
+}
+
+.persona-welcome[data-persona-welcome-variant="hero"] .persona-welcome-icon {
+  justify-content: center;
+}
+
+.persona-welcome[data-persona-welcome-variant="hero"] .persona-suggestions {
+  margin-inline: auto;
+  justify-content: center;
+}
+
+.persona-welcome[data-persona-welcome-variant="hero"]
+  .persona-suggestions[data-variant="card"],
+.persona-welcome[data-persona-welcome-variant="hero"]
+  .persona-suggestions[data-variant="list"] {
+  text-align: start;
+  width: 100%;
+}
+
 /* Composer ghost icon buttons (attachment + mention): transparent, neutral
    foreground, subtle hover. Themeable via `components.button.ghost.*`
    → `--persona-button-ghost-*`. The `[data-persona-root]` prefix outranks the
@@ -1410,6 +1744,9 @@
 [data-persona-root] .persona-widget-composer:not(.persona-pill-composer) {
   padding: var(--persona-composer-padding, 0.75rem 1rem);
   gap: var(--persona-composer-gap, 0.5rem);
+  /* `components.composer.borderColor`; the fallback matches the
+     `persona-border-persona-border` utility the form carries. */
+  border-color: var(--persona-composer-border-color, var(--persona-border, #e5e7eb));
 }
 
 /* Composer type scale, themeable via `components.composer.fontSize` /
@@ -3176,7 +3513,10 @@
 }
 
 [data-persona-root] .persona-artifact-list::-webkit-scrollbar-thumb {
-  background: var(--persona-artifact-tab-list-scrollbar, var(--persona-border, #e5e7eb));
+  background: var(
+    --persona-artifact-tab-list-scrollbar,
+    var(--persona-scrollbar-thumb, var(--persona-border, #e5e7eb))
+  );
   border-radius: 9999px;
 }
 
@@ -4237,13 +4577,17 @@
 }
 
 @media (min-width: 641px) {
+  /* Drawer width is its own knob (`layout.drawerWidth`), not the split's
+     pane vars: those are always materialized with split defaults, so reading
+     them here would resize every host's drawer. The outer min() keeps an
+     oversized value inside the panel. */
   [data-persona-root].persona-artifact-narrow-host .persona-artifact-pane {
     position: absolute;
     top: 0;
     right: 0;
     bottom: 0;
-    width: min(calc(100% - 1rem), 22rem) !important;
-    max-width: 22rem !important;
+    width: min(100%, var(--persona-artifact-drawer-width, min(calc(100% - 1rem), 22rem))) !important;
+    max-width: var(--persona-artifact-drawer-width, 22rem) !important;
     z-index: 60;
     transform: translateX(100%);
     transition: transform 0.2s ease;
@@ -4260,7 +4604,7 @@
     top: 0;
     right: 0;
     bottom: 0;
-    width: min(100vw - 1.5rem, 22rem);
+    width: min(100vw, var(--persona-artifact-drawer-width, min(100vw - 1.5rem, 22rem)));
     z-index: 60;
     transform: translateX(100%);
     transition: transform 0.2s ease;

package/src/testing/mock-stream.test.ts

@@ -39,6 +39,25 @@ describe("createMockSSEStream", () => {
     );
     expect(text.startsWith("event: message\n")).toBe(true);
   });
+
+  it("rejects reads with AbortError once the signal aborts, like a real fetch", async () => {
+    const abort = new AbortController();
+    const frames = Array.from({ length: 5 }, (_, i) => ({
+      type: "agent_turn_delta",
+      delta: `chunk-${i}`,
+    }));
+    const reader = createMockSSEStream(frames, {
+      delayMs: 0,
+      signal: abort.signal,
+    }).getReader();
+
+    const first = await reader.read();
+    expect(first.done).toBe(false);
+
+    abort.abort();
+
+    await expect(reader.read()).rejects.toMatchObject({ name: "AbortError" });
+  });
 });
 
 describe("buildAssistantTurnFrames", () => {

package/src/testing/mock-stream.ts

@@ -13,16 +13,27 @@ export interface CreateMockSSEStreamOptions {
    * Omit for bare `data: ...\n\n` form (both are valid SSE and the widget parser accepts either).
    */
   eventName?: string;
+  /**
+   * Abort signal, typically the `RequestInit.signal` a `customFetch` receives.
+   * A real `fetch` rejects its reads when the dispatch is aborted (cancel,
+   * clearChat, a superseding send); without this the mock keeps emitting into
+   * the client's read loop after the widget thinks the turn is dead.
+   */
+  signal?: AbortSignal | null;
 }
 
 const encoder = new TextEncoder();
 
+const abortError = () =>
+  new DOMException("The operation was aborted.", "AbortError");
+
 export function createMockSSEStream(
   frames: ReadonlyArray<MockSSEFrame>,
   options?: CreateMockSSEStreamOptions
 ): ReadableStream<Uint8Array> {
   const delayMs = options?.delayMs ?? 100;
   const prefix = options?.eventName ? `event: ${options.eventName}\n` : "";
+  const signal = options?.signal ?? null;
   let index = 0;
 
   return new ReadableStream<Uint8Array>({
@@ -31,7 +42,16 @@ export function createMockSSEStream(
         controller.close();
         return;
       }
+      // Check on both sides of the delay: the abort usually lands mid-wait.
+      if (signal?.aborted) {
+        controller.error(abortError());
+        return;
+      }
       await new Promise<void>((resolve) => setTimeout(resolve, delayMs));
+      if (signal?.aborted) {
+        controller.error(abortError());
+        return;
+      }
       const payload = JSON.stringify(frames[index]);
       controller.enqueue(encoder.encode(`${prefix}data: ${payload}\n\n`));
       index += 1;

package/src/theme-editor/sections.ts

@@ -501,6 +501,9 @@ const suggestionStyleSectionDef: SectionDef = {
     ] },
     { id: 'suggestion-list-bg', label: 'List Background', type: 'color', path: 'theme.components.suggestion.list.background', defaultValue: 'transparent' },
     { id: 'suggestion-list-border', label: 'List Border', type: 'token-ref', path: 'theme.components.suggestion.list.border', defaultValue: 'semantic.colors.border', tokenRef: { tokenType: 'color' } },
+    { id: 'suggestion-chip-item-gap', label: 'Chip Spacing', description: 'Space between chips', type: 'text', path: 'theme.components.suggestion.chip.itemGap', defaultValue: '8px' },
+    { id: 'suggestion-card-item-gap', label: 'Card Spacing', description: 'Space between cards', type: 'text', path: 'theme.components.suggestion.card.itemGap', defaultValue: '8px' },
+    { id: 'suggestion-list-item-gap', label: 'List Spacing', description: 'Space between list rows', type: 'text', path: 'theme.components.suggestion.list.itemGap', defaultValue: '8px' },
   ],
 };
 
@@ -535,6 +538,31 @@ const componentShadowsSectionDef: SectionDef = {
 };
 
 /** Shared shape sections (not scoped to light/dark) */
+// Blank keeps the built-in fallback: parseOptionalCssValue drops the path so
+// the CSS variable never emits.
+const TEXT_FONT_WEIGHT_OPTIONS: { value: string; label: string }[] = [
+  { value: '', label: 'Default' },
+  { value: '400', label: 'Normal (400)' },
+  { value: '500', label: 'Medium (500)' },
+  { value: '600', label: 'Semibold (600)' },
+  { value: '700', label: 'Bold (700)' },
+];
+
+const textStylesSectionDef: SectionDef = {
+  id: 'comp-text-styles',
+  title: 'Header & Welcome Text',
+  description: 'Typography for the header title and the welcome greeting. Leave blank to keep the built-in defaults.',
+  collapsed: true,
+  fields: [
+    { id: 'header-title-font-family', label: 'Header Title Font', description: 'CSS font-family, e.g. Georgia, serif', type: 'text', path: 'theme.components.header.title.fontFamily', defaultValue: '', parseValue: parseOptionalCssValue },
+    { id: 'header-title-font-size', label: 'Header Title Size', description: 'CSS length, e.g. 1.125rem', type: 'text', path: 'theme.components.header.title.fontSize', defaultValue: '', parseValue: parseOptionalCssValue },
+    { id: 'header-title-font-weight', label: 'Header Title Weight', type: 'select', path: 'theme.components.header.title.fontWeight', defaultValue: '', options: TEXT_FONT_WEIGHT_OPTIONS, parseValue: parseOptionalCssValue },
+    { id: 'welcome-title-font-family', label: 'Welcome Title Font', description: 'CSS font-family, e.g. Georgia, serif', type: 'text', path: 'theme.components.introCard.title.fontFamily', defaultValue: '', parseValue: parseOptionalCssValue },
+    { id: 'welcome-title-font-size', label: 'Welcome Title Size', description: 'CSS length, e.g. 1.5rem', type: 'text', path: 'theme.components.introCard.title.fontSize', defaultValue: '', parseValue: parseOptionalCssValue },
+    { id: 'welcome-title-font-weight', label: 'Welcome Title Weight', type: 'select', path: 'theme.components.introCard.title.fontWeight', defaultValue: '', options: TEXT_FONT_WEIGHT_OPTIONS, parseValue: parseOptionalCssValue },
+  ],
+};
+
 export const COMPONENT_SHAPE_SECTIONS: SectionDef[] = [
   panelLayoutSectionDef,
   launcherLayoutSectionDef,
@@ -542,6 +570,7 @@ export const COMPONENT_SHAPE_SECTIONS: SectionDef[] = [
   inputShapeSectionDef,
   composerSpacingSectionDef,
   buttonShapeSectionDef,
+  textStylesSectionDef,
   componentShadowsSectionDef,
 ];
 
@@ -609,7 +638,7 @@ const copySectionDef: SectionDef = {
   fields: [
     { id: 'copy-show-welcome-card', label: 'Show Welcome Card', type: 'toggle', path: 'copy.showWelcomeCard', defaultValue: true },
     { id: 'copy-welcome-title', label: 'Welcome Title', type: 'text', path: 'copy.welcomeTitle', defaultValue: 'Hello 👋' },
-    { id: 'copy-welcome-subtitle', label: 'Welcome Subtitle', type: 'text', path: 'copy.welcomeSubtitle', defaultValue: 'Ask anything about your account or products.' },
+    { id: 'copy-welcome-subtitle', label: 'Welcome Subtitle', type: 'text', path: 'copy.welcomeSubtitle', defaultValue: 'I can answer questions and help you get things done here.' },
     { id: 'copy-placeholder', label: 'Input Placeholder', type: 'text', path: 'copy.inputPlaceholder', defaultValue: 'Type your message…' },
     { id: 'copy-send-label', label: 'Send Button Label', type: 'text', path: 'copy.sendButtonLabel', defaultValue: 'Send' },
   ],

package/src/theme-reference.ts

@@ -120,7 +120,9 @@ export const THEME_TOKEN_DOCS = {
       header: {
         description: 'Chat panel header.',
         properties:
-          'background, border, borderRadius, padding, iconBackground, iconForeground, titleForeground, subtitleForeground, actionIconForeground, shadow, borderBottom.',
+          'background, border, borderRadius, padding, iconBackground, iconForeground, actionIconForeground, shadow, borderBottom, title and subtitle (each fontFamily, fontSize, fontWeight, lineHeight, letterSpacing, color).',
+        legacy:
+          'titleForeground and subtitleForeground are legacy aliases of header.title.color and header.subtitle.color. Both still work; the title/subtitle color wins when both are set.',
       },
       message: {
         description: 'Chat message bubbles.',
@@ -131,7 +133,19 @@ export const THEME_TOKEN_DOCS = {
       markdown: {
         description: 'Markdown rendering in messages and artifact pane.',
         properties:
-          'inlineCode (background, foreground), link.foreground, prose.fontFamily, heading.h1/h2 (fontSize, fontWeight).',
+          'inlineCode (background, foreground), link.foreground, prose.fontFamily, heading.h1/h2 (fontSize, fontWeight), codeBlock (background, borderColor, textColor, borderRadius: follows palette.radius.md), table (headerBackground, borderColor), hr.color, blockquote (borderColor, background, textColor).',
+      },
+      introCard: {
+        description:
+          'Welcome surface above the message list. Flat by default (transparent, no shadow).',
+        properties:
+          'background, borderRadius, padding, shadow, border (full CSS shorthand, default none), title and subtitle (each fontFamily, fontSize, fontWeight, lineHeight, letterSpacing, color).',
+      },
+      suggestion: {
+        description:
+          'Starter prompt and follow-up suggestion chrome. Three variants: chip, card, list.',
+        properties:
+          'background, foreground, border, borderRadius, padding, shadow, gap (icon to copy inside one item), itemGap (space between items, default 8px), minHeight, fontSize, lineHeight, iconSize, hoverBackground, hoverForeground, hoverBorder, pressedBackground, focusRing, disabledOpacity.',
       },
       voice:
         'recording (indicator, background, border), processing (icon, background), speaking (icon).',
@@ -141,9 +155,11 @@ export const THEME_TOKEN_DOCS = {
       scrollToBottom:
         'Floating scroll-to-bottom affordance shared by transcript and event stream: background, foreground, border, size, borderRadius, shadow, padding, gap, fontSize, iconSize.',
       toolBubble: 'shadow: tool call row box-shadow.',
+      scrollbar:
+        'Shared scrollbar appearance for every scroller: thumb (default semantic.colors.border), track (default transparent).',
       reasoningBubble: 'shadow: reasoning/thinking row box-shadow.',
       composer:
-        'Message input form: shadow (box-shadow), padding (form inset), gap (textarea row to actions row), fontSize and lineHeight (textarea type).',
+        'Message input form: shadow (box-shadow), borderColor, padding (form inset), gap (textarea row to actions row), fontSize and lineHeight (textarea type).',
       artifact:
         'toolbar (icon styling, copy menu), tab (background, active states), pane (background, toolbarBackground).',
     },
@@ -235,7 +251,7 @@ export const THEME_TOKEN_DOCS = {
     copy: {
       description: 'Widget text content.',
       properties:
-        'showWelcomeCard (boolean), welcomeTitle, welcomeSubtitle, inputPlaceholder, sendButtonLabel.',
+        'inputPlaceholder, sendButtonLabel, stopButtonLabel. (showWelcomeCard, welcomeTitle, welcomeSubtitle are deprecated aliases of the welcome namespace.)',
     },
     voiceRecognition: {
       description: 'Voice input configuration.',
@@ -252,6 +268,12 @@ export const THEME_TOKEN_DOCS = {
       properties:
         'starters.items, starters.variant ("card" | "chip" | "list"), starters.placement ("auto" | "welcome" | "composer"), starters.behavior ("send" | "fill"), starters.overflow ("scroll" | "wrap"), starters.maxItems, followUps.enabled, followUps.expose, followUps.variant, followUps.placement ("auto" | "after-message" | "composer"), followUps.behavior, followUps.overflow ("scroll" | "wrap"), followUps.maxItems.',
     },
+    welcome: {
+      description:
+        'First-open welcome surface. Supersedes copy.welcomeTitle / welcomeSubtitle / showWelcomeCard.',
+      properties:
+        'title, subtitle, icon ({ type: "lucide", name } | { type: "image", url, alt } | { type: "text", text } | function), variant ("card" | "hero" | "none"), dismiss ("never" | "on-first-message"), message (display-only greeting bubble, ignored under "hero").',
+    },
     suggestionChips:
       'Deprecated string[] shorthand for starter prompts. Prefer suggestions.starters.items.',
     messageActions: {