@runtypelabs/persona 3.6.0 → 3.8.0

package/src/components/event-stream-view.ts

@@ -1,5 +1,11 @@
 import { createElement } from "../utils/dom";
 import { renderLucideIcon } from "../utils/icons";
+import {
+  createFollowStateController,
+  isElementNearBottom,
+  resolveFollowStateFromScroll,
+  resolveFollowStateFromWheel
+} from "../utils/auto-follow";
 import type { EventStreamBuffer } from "../utils/event-stream-buffer";
 import type {
   SSEEventRecord,
@@ -391,6 +397,10 @@ export function createEventStreamView(
     config,
     plugins = [],
   } = options;
+  const scrollToBottomConfig = config?.features?.scrollToBottom;
+  const scrollToBottomEnabled = scrollToBottomConfig?.enabled !== false;
+  const scrollToBottomIconName = scrollToBottomConfig?.iconName ?? "arrow-down";
+  const scrollToBottomLabel = scrollToBottomConfig?.label ?? "";
 
   const esConfig: EventStreamConfig = config?.features?.eventStream ?? {};
 
@@ -438,7 +448,7 @@ export function createEventStreamView(
     let lastKnownTypes: string[] = [];
     let lastTypeCounts: Record<string, number> = {};
     let lastFilteredCount = 0;
-    let userScrolledUp = false;
+    const autoFollow = createFollowStateController();
     let newEventsSincePause = 0;
     let lastRenderTime = 0;
     let pendingUpdate = false;
@@ -638,18 +648,23 @@ export function createEventStreamView(
     // Scroll-to-bottom indicator
     const scrollIndicator = createElement(
       "div",
-      "persona-absolute persona-bottom-3 persona-left-1/2 persona-transform persona--translate-x-1/2 persona-bg-persona-accent persona-text-white persona-text-xs persona-px-3 persona-py-1.5 persona-rounded-full persona-cursor-pointer persona-shadow-md persona-z-10 persona-flex persona-items-center persona-gap-1"
+      "persona-scroll-to-bottom-indicator persona-absolute persona-bottom-3 persona-left-1/2 persona-transform persona--translate-x-1/2 persona-cursor-pointer persona-z-10 persona-text-xs"
     );
     applyCustomClasses(scrollIndicator, customClasses?.scrollIndicator);
     scrollIndicator.style.display = "none";
+    scrollIndicator.setAttribute(
+      "data-persona-scroll-to-bottom-has-label",
+      scrollToBottomLabel ? "true" : "false"
+    );
     const arrowIcon = renderLucideIcon(
-      "arrow-down",
-      "12px",
+      scrollToBottomIconName,
+      "14px",
       "currentColor",
       2
     );
     if (arrowIcon) scrollIndicator.appendChild(arrowIcon);
     const indicatorText = createElement("span", "");
+    indicatorText.textContent = scrollToBottomLabel;
     scrollIndicator.appendChild(indicatorText);
 
     // No matching events message
@@ -753,7 +768,7 @@ export function createEventStreamView(
     function resetScrollState() {
       lastFilteredCount = 0;
       newEventsSincePause = 0;
-      userScrolledUp = false;
+      autoFollow.resume();
       scrollIndicator.style.display = "none";
     }
 
@@ -766,12 +781,14 @@ export function createEventStreamView(
       dirtyExpandId = eventId;
       // Save scroll position — user-initiated expand/collapse should not auto-scroll
       const savedScrollTop = eventsList.scrollTop;
-      const wasUserScrolledUp = userScrolledUp;
+      const wasAutoFollowing = autoFollow.isFollowing();
       suppressScrollHandler = true;
-      userScrolledUp = true; // prevent auto-scroll during re-render
+      autoFollow.pause(); // prevent auto-scroll during re-render
       updateNow();
       eventsList.scrollTop = savedScrollTop;
-      userScrolledUp = wasUserScrolledUp;
+      if (wasAutoFollowing) {
+        autoFollow.resume();
+      }
       suppressScrollHandler = false;
     }
 
@@ -780,13 +797,7 @@ export function createEventStreamView(
     // ========================================================================
 
     function isNearBottom(): boolean {
-      const threshold = 50;
-      return (
-        eventsList.scrollHeight -
-          eventsList.scrollTop -
-          eventsList.clientHeight <=
-        threshold
-      );
+      return isElementNearBottom(eventsList, 50);
     }
 
     function updateNow() {
@@ -833,9 +844,11 @@ export function createEventStreamView(
       }
 
       // Track new events since user scrolled up
-      if (userScrolledUp && newCount > lastFilteredCount) {
+      if (scrollToBottomEnabled && !autoFollow.isFollowing() && newCount > lastFilteredCount) {
         newEventsSincePause += newCount - lastFilteredCount;
-        indicatorText.textContent = `${newEventsSincePause} new event${newEventsSincePause === 1 ? "" : "s"}`;
+        indicatorText.textContent = scrollToBottomLabel
+          ? `${scrollToBottomLabel}${newEventsSincePause > 0 ? ` (${newEventsSincePause})` : ""}`
+          : "";
         scrollIndicator.style.display = "";
       }
       lastFilteredCount = newCount;
@@ -939,7 +952,7 @@ export function createEventStreamView(
       }
 
       // Auto-scroll if user hasn't scrolled up
-      if (!userScrolledUp) {
+      if (autoFollow.isFollowing()) {
         eventsList.scrollTop = eventsList.scrollHeight;
       }
     }
@@ -1064,30 +1077,56 @@ export function createEventStreamView(
     const handleListScroll = () => {
       if (suppressScrollHandler) return;
       const currentScrollTop = eventsList.scrollTop;
-      const scrollingDown = currentScrollTop > lastScrollTop;
-      lastScrollTop = currentScrollTop;
+      const { action, nextLastScrollTop } = resolveFollowStateFromScroll({
+        following: autoFollow.isFollowing(),
+        currentScrollTop,
+        lastScrollTop,
+        nearBottom: isNearBottom(),
+        userScrollThreshold: 1,
+        resumeRequiresDownwardScroll: true
+      });
+      lastScrollTop = nextLastScrollTop;
 
-      if (isNearBottom() && scrollingDown) {
-        // User scrolled back down to bottom — re-enable auto-scroll
-        userScrolledUp = false;
+      if (action === "resume") {
+        autoFollow.resume();
         newEventsSincePause = 0;
         scrollIndicator.style.display = "none";
-      } else if (!isNearBottom()) {
-        userScrolledUp = true;
+      } else if (action === "pause") {
+        autoFollow.pause();
+        if (scrollToBottomEnabled) {
+          indicatorText.textContent = scrollToBottomLabel;
+          scrollIndicator.style.display = "";
+        }
       }
     };
 
     // Wheel events fire synchronously before rAF callbacks, so we can
     // detect upward scroll intent before the next updateNow() auto-scrolls.
     const handleWheel = (e: WheelEvent) => {
-      if (e.deltaY < 0) {
-        userScrolledUp = true;
+      const action = resolveFollowStateFromWheel({
+        following: autoFollow.isFollowing(),
+        deltaY: e.deltaY,
+        nearBottom: isNearBottom(),
+        resumeWhenNearBottom: true
+      });
+
+      if (action === "pause") {
+        autoFollow.pause();
+        if (scrollToBottomEnabled) {
+          indicatorText.textContent = scrollToBottomLabel;
+          scrollIndicator.style.display = "";
+        }
+      } else if (action === "resume") {
+        autoFollow.resume();
+        newEventsSincePause = 0;
+        scrollIndicator.style.display = "none";
       }
     };
 
     const handleScrollIndicatorClick = () => {
+      if (!scrollToBottomEnabled) return;
       eventsList.scrollTop = eventsList.scrollHeight;
-      userScrolledUp = false;
+      autoFollow.resume();
       newEventsSincePause = 0;
       scrollIndicator.style.display = "none";
     };

package/src/components/header-builder.ts

@@ -1,6 +1,7 @@
 import { createElement, createElementInDocument } from "../utils/dom";
 import { renderLucideIcon } from "../utils/icons";
 import { AgentWidgetConfig } from "../types";
+import { PORTALED_OVERLAY_Z_INDEX } from "../utils/constants";
 
 /** CSS `color` values; variables are set on `[data-persona-root]` from `theme.components.header`. */
 export const HEADER_THEME_CSS = {
@@ -233,6 +234,7 @@ export const buildHeader = (context: HeaderBuildContext): HeaderElements => {
 
         // Position tooltip above button
         portaledTooltip.style.position = "fixed";
+        portaledTooltip.style.zIndex = String(PORTALED_OVERLAY_Z_INDEX);
         portaledTooltip.style.left = `${buttonRect.left + buttonRect.width / 2}px`;
         portaledTooltip.style.top = `${buttonRect.top - 8}px`;
         portaledTooltip.style.transform = "translate(-50%, -100%)";
@@ -389,6 +391,7 @@ export const buildHeader = (context: HeaderBuildContext): HeaderElements => {
 
       // Position tooltip above button
       portaledTooltip.style.position = "fixed";
+      portaledTooltip.style.zIndex = String(PORTALED_OVERLAY_Z_INDEX);
       portaledTooltip.style.left = `${buttonRect.left + buttonRect.width / 2}px`;
       portaledTooltip.style.top = `${buttonRect.top - 8}px`;
       portaledTooltip.style.transform = "translate(-50%, -100%)";

package/src/components/launcher.ts

@@ -3,6 +3,7 @@ import { AgentWidgetConfig } from "../types";
 import { positionMap } from "../utils/positioning";
 import { isDockedMountMode } from "../utils/dock";
 import { renderLucideIcon } from "../utils/icons";
+import { DEFAULT_OVERLAY_Z_INDEX } from "../utils/constants";
 
 export interface LauncherButton {
   element: HTMLButtonElement;
@@ -174,12 +175,16 @@ export const createLauncherButton = (
         : positionMap["bottom-right"];
 
     const floatingBase =
-      "persona-fixed persona-flex persona-items-center persona-gap-3 persona-rounded-launcher persona-bg-persona-surface persona-py-2.5 persona-pl-3 persona-pr-3 persona-transition hover:persona-translate-y-[-2px] persona-cursor-pointer persona-z-50";
+      "persona-fixed persona-flex persona-items-center persona-gap-3 persona-rounded-launcher persona-bg-persona-surface persona-py-2.5 persona-pl-3 persona-pr-3 persona-transition hover:persona-translate-y-[-2px] persona-cursor-pointer";
     const dockedBase =
       "persona-relative persona-mt-4 persona-mb-4 persona-mx-auto persona-flex persona-items-center persona-justify-center persona-rounded-launcher persona-bg-persona-surface persona-transition hover:persona-translate-y-[-2px] persona-cursor-pointer";
 
     button.className = dockedMode ? dockedBase : `${floatingBase} ${positionClass}`;
-    
+
+    if (!dockedMode) {
+      button.style.zIndex = String(launcher.zIndex ?? DEFAULT_OVERLAY_Z_INDEX);
+    }
+
     // Apply launcher border and shadow from config (with defaults matching previous Tailwind classes)
     const defaultBorder = "1px solid var(--persona-border, #e5e7eb)";
     const defaultShadow = "var(--persona-shadow, 0 10px 15px -3px rgba(0, 0, 0, 0.1), 0 4px 6px -4px rgba(0, 0, 0, 0.1))";

package/src/components/panel.ts

@@ -2,6 +2,7 @@ import { createElement } from "../utils/dom";
 import { AgentWidgetConfig } from "../types";
 import { positionMap } from "../utils/positioning";
 import { isDockedMountMode } from "../utils/dock";
+import { DEFAULT_OVERLAY_Z_INDEX } from "../utils/constants";
 import { buildHeader, attachHeaderToContainer, HeaderElements } from "./header-builder";
 import { buildHeaderWithLayout } from "./header-layouts";
 import { buildComposer, ComposerElements } from "./composer-builder";
@@ -58,8 +59,9 @@ export const createWrapper = (config?: AgentWidgetConfig): PanelWrapper => {
 
   const wrapper = createElement(
     "div",
-    `persona-widget-wrapper persona-fixed ${position} persona-z-50 persona-transition`
+    `persona-widget-wrapper persona-fixed ${position} persona-transition`
   );
+  wrapper.style.zIndex = String(config?.launcher?.zIndex ?? DEFAULT_OVERLAY_Z_INDEX);
 
   const panel = createElement(
     "div",

package/src/defaults.ts

@@ -102,6 +102,11 @@ export const DEFAULT_WIDGET_CONFIG: Partial<AgentWidgetConfig> = {
   features: {
     showReasoning: true,
     showToolCalls: true,
+    scrollToBottom: {
+      enabled: true,
+      iconName: "arrow-down",
+      label: "",
+    },
   },
   suggestionChips: [
     "What can you help me with?",
@@ -214,6 +219,8 @@ export function mergeWithDefaults(
     features: (() => {
       const da = DEFAULT_WIDGET_CONFIG.features?.artifacts;
       const ca = config.features?.artifacts;
+      const dsb = DEFAULT_WIDGET_CONFIG.features?.scrollToBottom;
+      const csb = config.features?.scrollToBottom;
       const mergedArtifacts =
         da === undefined && ca === undefined
           ? undefined
@@ -225,9 +232,17 @@ export function mergeWithDefaults(
                 ...ca?.layout,
               },
             };
+      const mergedScrollToBottom =
+        dsb === undefined && csb === undefined
+          ? undefined
+          : {
+              ...dsb,
+              ...csb,
+            };
       return {
         ...DEFAULT_WIDGET_CONFIG.features,
         ...config.features,
+        ...(mergedScrollToBottom !== undefined ? { scrollToBottom: mergedScrollToBottom } : {}),
         ...(mergedArtifacts !== undefined ? { artifacts: mergedArtifacts } : {}),
       };
     })(),

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

@@ -228,7 +228,7 @@ describe("createWidgetHostLayout docked", () => {
       const dockSlot = layout.shell?.querySelector<HTMLElement>('[data-persona-dock-role="panel"]');
       layout.syncWidgetState({ open: true, launcherEnabled: true });
       expect(dockSlot?.style.position).toBe("fixed");
-      expect(dockSlot?.style.zIndex).toBe("9999");
+      expect(dockSlot?.style.zIndex).toBe("100000");
       expect(layout.shell?.dataset.personaDockMobileFullscreen).toBe("true");
 
       layout.destroy();

package/src/runtime/host-layout.ts

@@ -3,6 +3,7 @@ import type {
   AgentWidgetStateSnapshot,
 } from "../types";
 import { isDockedMountMode, resolveDockConfig } from "../utils/dock";
+import { DEFAULT_OVERLAY_Z_INDEX } from "../utils/constants";
 
 export type WidgetHostLayoutMode = "direct" | "docked";
 
@@ -198,7 +199,7 @@ const applyDockStyles = (
     dockSlot.style.minWidth = "0";
     dockSlot.style.minHeight = "0";
     dockSlot.style.overflow = "hidden";
-    dockSlot.style.zIndex = String(config?.launcher?.zIndex ?? 9999);
+    dockSlot.style.zIndex = String(config?.launcher?.zIndex ?? DEFAULT_OVERLAY_Z_INDEX);
     dockSlot.style.transform = "none";
     dockSlot.style.transition = "none";
     dockSlot.style.pointerEvents = "auto";

package/src/scroll-to-bottom-defaults.test.ts

@@ -0,0 +1,13 @@
+import { describe, expect, it } from "vitest";
+
+import { DEFAULT_WIDGET_CONFIG } from "./defaults";
+
+describe("scroll-to-bottom defaults", () => {
+  it("defaults to an enabled icon-only circular control", () => {
+    expect(DEFAULT_WIDGET_CONFIG.features?.scrollToBottom).toEqual({
+      enabled: true,
+      iconName: "arrow-down",
+      label: "",
+    });
+  });
+});

package/src/styles/widget.css

@@ -834,6 +834,10 @@
   overflow-y: auto;
 }
 
+.persona-widget-body {
+  overscroll-behavior: contain;
+}
+
 .persona-overflow-hidden {
   overflow: hidden;
 }
@@ -2320,6 +2324,46 @@
   background: var(--persona-label-btn-hover-bg, var(--persona-container, #f3f4f6));
 }
 
+[data-persona-root] .persona-scroll-to-bottom-indicator {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  gap: var(--persona-scroll-to-bottom-gap, 0.5rem);
+  min-height: var(--persona-scroll-to-bottom-size, 40px);
+  border-radius: var(--persona-scroll-to-bottom-radius, var(--persona-radius-full, 9999px));
+  border: 1px solid var(--persona-scroll-to-bottom-border, var(--persona-primary, #111827));
+  background: var(--persona-scroll-to-bottom-bg, var(--persona-button-primary-bg, var(--persona-accent, #0f0f0f)));
+  color: var(--persona-scroll-to-bottom-fg, var(--persona-button-primary-fg, var(--persona-text-inverse, #ffffff)));
+  box-shadow: var(--persona-scroll-to-bottom-shadow, 0 4px 6px -1px rgb(0 0 0 / 0.1), 0 2px 4px -2px rgb(0 0 0 / 0.1));
+  font-size: var(--persona-scroll-to-bottom-font-size, 0.875rem);
+  line-height: 1;
+}
+
+[data-persona-root] .persona-scroll-to-bottom-indicator[data-persona-scroll-to-bottom-has-label="true"] {
+  padding: var(--persona-scroll-to-bottom-padding, 0.5rem 0.875rem);
+}
+
+[data-persona-root] .persona-scroll-to-bottom-indicator[data-persona-scroll-to-bottom-has-label="false"] {
+  width: var(--persona-scroll-to-bottom-size, 40px);
+  height: var(--persona-scroll-to-bottom-size, 40px);
+  padding: 0;
+  gap: 0;
+}
+
+[data-persona-root] .persona-scroll-to-bottom-indicator svg {
+  width: var(--persona-scroll-to-bottom-icon-size, 14px);
+  height: var(--persona-scroll-to-bottom-icon-size, 14px);
+}
+
+[data-persona-root] .persona-scroll-to-bottom-indicator:hover {
+  opacity: 0.92;
+}
+
+[data-persona-root] .persona-scroll-to-bottom-indicator:focus-visible {
+  outline: 2px solid var(--persona-accent, #171717);
+  outline-offset: 2px;
+}
+
 /* Toggle group — mutually exclusive button set created by createToggleGroup() */
 [data-persona-root] .persona-toggle-group {
   display: inline-flex;

package/src/theme-editor/index.ts

@@ -101,6 +101,7 @@ export {
   ROLE_USER_MESSAGES,
   ROLE_ASSISTANT_MESSAGES,
   ROLE_PRIMARY_ACTIONS,
+  ROLE_SCROLL_TO_BOTTOM,
   ROLE_INPUT,
   ROLE_LINKS_FOCUS,
   ROLE_BORDERS,

package/src/theme-editor/role-mappings.ts

@@ -95,6 +95,17 @@ export const ROLE_PRIMARY_ACTIONS: RoleAssignmentOptions = {
   ],
 };
 
+export const ROLE_SCROLL_TO_BOTTOM: RoleAssignmentOptions = {
+  roleId: 'role-scroll-to-bottom',
+  helper: 'Scroll-to-bottom affordances in transcript and event stream',
+  intensities: ROLE_INTENSITIES,
+  targets: [
+    { path: 'components.scrollToBottom.background', kind: 'background' },
+    { path: 'components.scrollToBottom.foreground', kind: 'foreground' },
+    { path: 'components.scrollToBottom.border', kind: 'border' },
+  ],
+};
+
 export const ROLE_INPUT: RoleAssignmentOptions = {
   roleId: 'role-input',
   helper: 'Message input field',
@@ -137,6 +148,7 @@ export const ALL_ROLES: RoleAssignmentOptions[] = [
   ROLE_USER_MESSAGES,
   ROLE_ASSISTANT_MESSAGES,
   ROLE_PRIMARY_ACTIONS,
+  ROLE_SCROLL_TO_BOTTOM,
   ROLE_INPUT,
   ROLE_LINKS_FOCUS,
   ROLE_BORDERS,

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

@@ -0,0 +1,43 @@
+import { describe, expect, it } from "vitest";
+
+import { COMPONENTS_SECTIONS, CONFIGURE_SECTIONS, INTERFACE_ROLES_SECTION } from "./sections";
+import { ALL_ROLES } from "./role-mappings";
+
+describe("theme editor scroll-to-bottom controls", () => {
+  it("exposes scroll-to-bottom config controls", () => {
+    const featureSection = CONFIGURE_SECTIONS.find((section) => section.id === "features");
+
+    expect(featureSection?.fields.some((field) => field.path === "features.scrollToBottom.enabled")).toBe(true);
+    expect(featureSection?.fields.some((field) => field.path === "features.scrollToBottom.iconName")).toBe(true);
+    expect(featureSection?.fields.some((field) => field.path === "features.scrollToBottom.label")).toBe(true);
+  });
+
+  it("exposes scroll-to-bottom component token controls", () => {
+    const fieldPaths = COMPONENTS_SECTIONS.flatMap((section) => section.fields.map((field) => field.path));
+
+    expect(fieldPaths).toContain("theme.components.scrollToBottom.background");
+    expect(fieldPaths).toContain("theme.components.scrollToBottom.foreground");
+    expect(fieldPaths).toContain("theme.components.scrollToBottom.border");
+    expect(fieldPaths).toContain("theme.components.scrollToBottom.size");
+    expect(fieldPaths).toContain("theme.components.scrollToBottom.borderRadius");
+    expect(fieldPaths).toContain("theme.components.scrollToBottom.shadow");
+    expect(fieldPaths).toContain("theme.components.scrollToBottom.padding");
+    expect(fieldPaths).toContain("theme.components.scrollToBottom.gap");
+    expect(fieldPaths).toContain("theme.components.scrollToBottom.fontSize");
+    expect(fieldPaths).toContain("theme.components.scrollToBottom.iconSize");
+  });
+
+  it("adds a scroll-to-bottom interface role mapping", () => {
+    const role = ALL_ROLES.find((entry) => entry.roleId === "role-scroll-to-bottom");
+
+    expect(role).toBeDefined();
+    expect(role?.targets.map((target) => target.path)).toEqual(
+      expect.arrayContaining([
+        "components.scrollToBottom.background",
+        "components.scrollToBottom.foreground",
+        "components.scrollToBottom.border",
+      ])
+    );
+    expect(INTERFACE_ROLES_SECTION.fields.some((field) => field.id === "role-scroll-to-bottom")).toBe(true);
+  });
+});

package/src/theme-editor/sections.ts

@@ -8,6 +8,7 @@ import {
   ROLE_USER_MESSAGES,
   ROLE_ASSISTANT_MESSAGES,
   ROLE_PRIMARY_ACTIONS,
+  ROLE_SCROLL_TO_BOTTOM,
   ROLE_INPUT,
   ROLE_LINKS_FOCUS,
   ROLE_BORDERS,
@@ -420,6 +421,36 @@ const buttonColorsSectionDef: SectionDef = {
   ],
 };
 
+const scrollToBottomSectionDef: SectionDef = {
+  id: 'scroll-to-bottom-style',
+  title: 'Scroll To Bottom',
+  description: 'Style the floating jump-to-latest affordance.',
+  collapsed: true,
+  fields: [
+    { id: 'scroll-bottom-bg', label: 'Background', type: 'token-ref', path: 'theme.components.scrollToBottom.background', defaultValue: 'components.button.primary.background', tokenRef: { tokenType: 'color' } },
+    { id: 'scroll-bottom-fg', label: 'Foreground', type: 'token-ref', path: 'theme.components.scrollToBottom.foreground', defaultValue: 'components.button.primary.foreground', tokenRef: { tokenType: 'color' } },
+    { id: 'scroll-bottom-border', label: 'Border', type: 'token-ref', path: 'theme.components.scrollToBottom.border', defaultValue: 'semantic.colors.primary', tokenRef: { tokenType: 'color' } },
+    { id: 'scroll-bottom-size', label: 'Size', type: 'text', path: 'theme.components.scrollToBottom.size', defaultValue: '40px' },
+    { id: 'scroll-bottom-radius', label: 'Border Radius', type: 'select', path: 'theme.components.scrollToBottom.borderRadius', defaultValue: 'palette.radius.full', options: [
+      { value: 'palette.radius.md', label: 'Medium' },
+      { value: 'palette.radius.lg', label: 'Large' },
+      { value: 'palette.radius.xl', label: 'Extra Large' },
+      { value: 'palette.radius.full', label: 'Full' },
+    ] },
+    { id: 'scroll-bottom-shadow', label: 'Shadow', type: 'select', path: 'theme.components.scrollToBottom.shadow', defaultValue: 'palette.shadows.sm', options: [
+      { value: 'palette.shadows.none', label: 'None' },
+      { value: 'palette.shadows.sm', label: 'Small' },
+      { value: 'palette.shadows.md', label: 'Medium' },
+      { value: 'palette.shadows.lg', label: 'Large' },
+      { value: 'palette.shadows.xl', label: 'Extra Large' },
+    ] },
+    { id: 'scroll-bottom-padding', label: 'Padding', type: 'text', path: 'theme.components.scrollToBottom.padding', defaultValue: '0.5rem 0.875rem' },
+    { id: 'scroll-bottom-gap', label: 'Gap', type: 'text', path: 'theme.components.scrollToBottom.gap', defaultValue: '0.5rem' },
+    { id: 'scroll-bottom-font-size', label: 'Font Size', type: 'text', path: 'theme.components.scrollToBottom.fontSize', defaultValue: '0.875rem' },
+    { id: 'scroll-bottom-icon-size', label: 'Icon Size', type: 'text', path: 'theme.components.scrollToBottom.iconSize', defaultValue: '14px' },
+  ],
+};
+
 /** Shared shape sections (not scoped to light/dark) */
 export const COMPONENT_SHAPE_SECTIONS: SectionDef[] = [
   panelLayoutSectionDef,
@@ -435,6 +466,7 @@ export const COMPONENT_COLOR_SECTIONS: SectionDef[] = [
   messageColorsSectionDef,
   inputColorsSectionDef,
   buttonColorsSectionDef,
+  scrollToBottomSectionDef,
 ];
 
 export const COMPONENTS_SECTIONS: SectionDef[] = [
@@ -655,6 +687,9 @@ const featuresSectionDef: SectionDef = {
   fields: [
     { id: 'feat-voice', label: 'Voice Recognition', description: 'Enable voice input', type: 'toggle', path: 'voiceRecognition.enabled', defaultValue: false },
     { id: 'feat-auto-focus', label: 'Auto Focus Input', description: 'Focus input after panel opens', type: 'toggle', path: 'autoFocusInput', defaultValue: false },
+    { id: 'feat-scroll-bottom-enabled', label: 'Scroll To Bottom', description: 'Show a jump-to-latest affordance when the user scrolls away from new content', type: 'toggle', path: 'features.scrollToBottom.enabled', defaultValue: true },
+    { id: 'feat-scroll-bottom-icon', label: 'Scroll To Bottom Icon', type: 'text', path: 'features.scrollToBottom.iconName', defaultValue: 'arrow-down' },
+    { id: 'feat-scroll-bottom-label', label: 'Scroll To Bottom Label', description: 'Leave empty for icon-only mode', type: 'text', path: 'features.scrollToBottom.label', defaultValue: '' },
   ],
 };
 
@@ -826,6 +861,13 @@ export const INTERFACE_ROLES_SECTION: SectionDef = {
       path: 'theme.components.button.primary.background',
       roleAssignment: ROLE_PRIMARY_ACTIONS,
     },
+    {
+      id: 'role-scroll-to-bottom',
+      label: 'Scroll To Bottom',
+      type: 'role-assignment',
+      path: 'theme.components.scrollToBottom.background',
+      roleAssignment: ROLE_SCROLL_TO_BOTTOM,
+    },
     {
       id: 'role-input',
       label: 'Input Field',

package/src/theme-reference.ts

@@ -138,6 +138,8 @@ export const THEME_TOKEN_DOCS = {
       approval:
         'requested (background, border, text), approve (background, foreground), deny (background, foreground).',
       attachment: 'image (background, border).',
+      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.',
       reasoningBubble: 'shadow — reasoning/thinking row box-shadow.',
       composer: 'shadow — message input form box-shadow.',
@@ -201,6 +203,12 @@ export const THEME_TOKEN_DOCS = {
       properties:
         'enabled, iconColor, backgroundColor, borderWidth, borderColor, borderRadius, size.',
     },
+    scrollToBottom: {
+      description:
+        'Shared transcript + event-stream jump-to-latest affordance.',
+      properties:
+        'features.scrollToBottom.enabled, features.scrollToBottom.iconName, features.scrollToBottom.label (empty string renders icon-only). Defaults: enabled=true, iconName="arrow-down", label="".',
+    },
     toolCall: {
       description: 'Tool call display styling.',
       properties:

package/src/types/theme.ts

@@ -233,6 +233,18 @@ export interface MessageTokens {
     /** Assistant bubble box-shadow (token ref or raw CSS, e.g. `none`). */
     shadow?: string;
   };
+  /** Border color between messages in the thread. */
+  border?: TokenReference<'color'>;
+}
+
+/** Collapsible widget chrome (tool bubbles, reasoning bubbles, approval bubbles). */
+export interface CollapsibleWidgetTokens {
+  /** Background for content areas. */
+  container?: TokenReference<'color'>;
+  /** Background for code blocks inside collapsible sections. */
+  surface?: TokenReference<'color'>;
+  /** Border color for collapsible sections. */
+  border?: TokenReference<'color'>;
 }
 
 export interface MarkdownTokens {
@@ -262,6 +274,27 @@ export interface MarkdownTokens {
       fontWeight?: string;
     };
   };
+  /** Fenced code block styling. */
+  codeBlock?: {
+    background?: TokenReference<'color'>;
+    borderColor?: TokenReference<'color'>;
+    textColor?: TokenReference<'color'>;
+  };
+  /** Table styling. */
+  table?: {
+    headerBackground?: TokenReference<'color'>;
+    borderColor?: TokenReference<'color'>;
+  };
+  /** Horizontal rule styling. */
+  hr?: {
+    color?: TokenReference<'color'>;
+  };
+  /** Blockquote styling. */
+  blockquote?: {
+    borderColor?: TokenReference<'color'>;
+    background?: TokenReference<'color'>;
+    textColor?: TokenReference<'color'>;
+  };
 }
 
 export interface VoiceTokens {
@@ -393,6 +426,14 @@ export interface LabelButtonTokens {
   gap?: string;
 }
 
+/** Scroll-to-bottom pill chrome shared by transcript + event stream. */
+export interface ScrollToBottomTokens extends ComponentTokenSet {
+  size?: string;
+  gap?: string;
+  fontSize?: string;
+  iconSize?: string;
+}
+
 /** Toggle group chrome (used by createToggleGroup). */
 export interface ToggleGroupTokens {
   /** Gap between toggle buttons. Default: 0 (connected). */
@@ -420,6 +461,8 @@ export interface ComponentTokens {
   iconButton?: IconButtonTokens;
   /** Label button styling tokens. */
   labelButton?: LabelButtonTokens;
+  /** Scroll-to-bottom indicator styling tokens. */
+  scrollToBottom?: ScrollToBottomTokens;
   /** Toggle group styling tokens. */
   toggleGroup?: ToggleGroupTokens;
   /** Artifact toolbar, tab strip, and pane chrome. */
@@ -428,6 +471,8 @@ export interface ComponentTokens {
     tab?: ArtifactTabTokens;
     pane?: ArtifactPaneTokens;
   };
+  /** Collapsible widget chrome (tool/reasoning/approval bubbles). */
+  collapsibleWidget?: CollapsibleWidgetTokens;
 }
 
 export interface PaletteExtras {