@urbicon-ui/blocks 6.35.0 → 6.37.0

package/dist/components/Chat/ChatMessageList/ChatMessageList.svelte

@@ -0,0 +1,301 @@
+<script lang="ts">
+  import { getBlocksConfig, resolveSlotClasses } from '../../../provider';
+  import { resolveIcon } from '../../../icons';
+  import ArrowDownIconDefault from '../../../icons/ArrowDownIcon.svelte';
+  import MessageSquareIconDefault from '../../../icons/MessageSquareIcon.svelte';
+  import { Badge } from '../../../primitives/Badge';
+  import { EmptyState } from '../../EmptyState';
+  import type { ChatMessageData, ChatMessageStatus } from '../chat.types';
+  import ChatMessage from '../ChatMessage/ChatMessage.svelte';
+  import { chatMessageListVariants } from './chat-message-list.variants';
+  import {
+    appendedCount,
+    classifyTransition,
+    type ListIdSnapshot,
+    type ListTransition,
+    resolveScrollIntent
+  } from './chat-scroll';
+  import type { ChatMessageListProps } from './index';
+
+  const ArrowDownIcon = resolveIcon('arrowDown', ArrowDownIconDefault);
+  const MessageSquareIcon = resolveIcon('messageSquare', MessageSquareIconDefault);
+
+  let {
+    messages,
+    message: messageSnippet,
+    empty,
+    urlPolicy,
+    partRenderers,
+    layout,
+    density,
+    onRegenerate,
+    onRetry,
+    onStickChange,
+    listLabel = 'Conversation',
+    scrollToBottomLabel = 'Scroll to bottom',
+    newMessagesLabel = 'New messages',
+    generatingLabel = 'Generating response…',
+    errorLabel = 'Something went wrong',
+    abortedLabel = 'Generation stopped',
+    emptyTitle = 'No messages yet',
+    emptyDescription,
+    class: className = '',
+    unstyled: unstyledProp = false,
+    slotClasses: slotClassesProp = {},
+    preset,
+    ...restProps
+  }: ChatMessageListProps = $props();
+
+  const blocksConfig = getBlocksConfig();
+  const unstyled = $derived(unstyledProp || blocksConfig?.unstyled || false);
+
+  const styles = $derived(chatMessageListVariants({}));
+  const slotClasses = $derived(
+    resolveSlotClasses(blocksConfig, 'ChatMessageList', preset, {}, slotClassesProp)
+  );
+
+  function slot(name: keyof typeof styles, extra?: string | false): string {
+    const overrides = [slotClasses?.[name], extra].filter(Boolean).join(' ');
+    if (unstyled) return overrides;
+    return styles[name]({ class: overrides });
+  }
+
+  // ── Stick state ──────────────────────────────────────────────────────────
+  // `stuck` = the list follows growing content. See chat-scroll.ts for the
+  // direction/proximity model that classifies scroll events without any
+  // "programmatic scroll" suppression flag.
+  let viewportRef = $state<HTMLDivElement>();
+  let contentRef = $state<HTMLDivElement>();
+  let stuck = $state(true);
+  let newCount = $state(0);
+  let lastScrollTop = 0;
+
+  const showJumpButton = $derived(!stuck && messages.length > 0);
+
+  function scrollNow(behavior: ScrollBehavior = 'instant') {
+    const el = viewportRef;
+    if (!el) return;
+    el.scrollTo({ top: el.scrollHeight, behavior });
+  }
+
+  /**
+   * Scroll to the newest message and resume following. Exposed on the
+   * instance (`bind:this`) for consumer-driven jumps.
+   */
+  export function scrollToBottom(behavior: ScrollBehavior = 'instant') {
+    setStuck(true);
+    scrollNow(behavior);
+  }
+
+  function setStuck(next: boolean) {
+    if (stuck === next) return;
+    stuck = next;
+    if (next) newCount = 0;
+    onStickChange?.(next);
+  }
+
+  function handleScroll() {
+    const el = viewportRef;
+    if (!el) return;
+    const snapshot = {
+      scrollTop: el.scrollTop,
+      scrollHeight: el.scrollHeight,
+      clientHeight: el.clientHeight
+    };
+    const intent = resolveScrollIntent(snapshot, lastScrollTop);
+    lastScrollTop = snapshot.scrollTop;
+    if (intent === 'stick') setStuck(true);
+    else if (intent === 'unstick') setStuck(false);
+  }
+
+  // Follow growing content (streaming tokens) and viewport resizes while
+  // stuck. Content growth below the fold never fires scroll events, so the
+  // engine observes sizes instead.
+  $effect(() => {
+    const viewport = viewportRef;
+    const content = contentRef;
+    if (!viewport || typeof ResizeObserver === 'undefined') return;
+    const ro = new ResizeObserver(() => {
+      if (stuck) scrollNow();
+    });
+    ro.observe(viewport);
+    if (content) ro.observe(content);
+    return () => ro.disconnect();
+  });
+
+  // ── List transitions (append / prepend / replace) ────────────────────────
+  // The pre-effect classifies the change and snapshots the scroll metrics
+  // BEFORE the DOM updates; the post-effect applies the matching correction
+  // after. Plain (non-reactive) carriers hand the verdict across the pair.
+  let prevIds: ListIdSnapshot = { firstId: undefined, lastId: undefined, length: 0 };
+  let pendingTransition: ListTransition = 'none';
+  let pendingPrependHeight = 0;
+  let pendingPrependTop = 0;
+  let pendingAppended = 0;
+
+  $effect.pre(() => {
+    const next: ListIdSnapshot = {
+      firstId: messages[0]?.id,
+      lastId: messages[messages.length - 1]?.id,
+      length: messages.length
+    };
+    const transition = classifyTransition(prevIds, next);
+    pendingTransition = transition;
+    if (transition === 'append') pendingAppended = appendedCount(prevIds.length, next.length);
+    if (transition === 'prepend' && viewportRef) {
+      pendingPrependHeight = viewportRef.scrollHeight;
+      pendingPrependTop = viewportRef.scrollTop;
+    }
+    prevIds = next;
+  });
+
+  $effect(() => {
+    // Subscribe to the SAME signals as the pre-effect (length + boundary ids),
+    // not just the array reference: an in-place `messages.push(m)` — the
+    // idiomatic Svelte-5 stream append — changes length but not the reference,
+    // and `void messages` alone would miss it (review finding, P2 wave).
+    void messages.length;
+    void messages[0]?.id;
+    void messages[messages.length - 1]?.id;
+    const transition = pendingTransition;
+    pendingTransition = 'none';
+
+    if (transition === 'prepend' && viewportRef) {
+      // Keep the previously visible message visually still: shift scrollTop
+      // by exactly the height the prepended history added above it.
+      const delta = viewportRef.scrollHeight - pendingPrependHeight;
+      viewportRef.scrollTop = pendingPrependTop + delta;
+      lastScrollTop = viewportRef.scrollTop;
+    } else if (transition === 'initial' || transition === 'replace') {
+      // A conversation opens (or resets) at its newest message.
+      setStuck(true);
+      scrollNow();
+    } else if (transition === 'append') {
+      if (stuck) scrollNow();
+      else newCount += pendingAppended;
+    }
+  });
+
+  // ── Screen-reader strategy ───────────────────────────────────────────────
+  // The visible log is aria-live="off" — announcing every streamed token is
+  // spam. A visually hidden status region announces the start of generation
+  // and, when a reply settles, its full text once (a deliberate trade-off:
+  // the answer is what the user asked for; a short cue would force a manual
+  // hunt through the log). Transitions settling in the SAME tick collapse to
+  // the last one — accepted: parallel assistant streams are out of scope.
+  let announcement = $state('');
+  // Deliberately a plain Map, NOT SvelteMap: it is only read/written inside
+  // the effect below — reactivity here would re-trigger that very effect.
+  const announcedStatus = new Map<string, ChatMessageStatus | undefined>();
+  // First effect run only REGISTERS the mounted history — announcing it would
+  // read the newest old message aloud on every conversation open.
+  let announceSyncDone = false;
+
+  function messageText(msg: ChatMessageData): string {
+    return msg.parts.flatMap((p) => (p.type === 'text' ? [p.text] : [])).join('\n\n');
+  }
+
+  function settledAnnouncement(msg: ChatMessageData): string {
+    if (msg.status === 'error') return errorLabel;
+    if (msg.status === 'aborted') return abortedLabel;
+    return messageText(msg);
+  }
+
+  $effect(() => {
+    const seen = new Set<string>();
+    const announceable = announceSyncDone;
+    for (const msg of messages) {
+      seen.add(msg.id);
+      if (msg.role !== 'assistant') continue;
+      const prev = announcedStatus.get(msg.id);
+      const known = announcedStatus.has(msg.id);
+      if (msg.status === 'streaming' && prev !== 'streaming') {
+        if (announceable || !known) announcement = generatingLabel;
+      } else if (known && prev === 'streaming' && msg.status !== 'streaming') {
+        // Settle: text when there is any, the error/aborted label otherwise —
+        // never leave a stale "generating" in the region (review finding).
+        announcement = settledAnnouncement(msg) || '';
+      } else if (announceable && !known && msg.status !== 'streaming') {
+        // A reply that arrives already settled (fast/cached models stream
+        // nothing) must still be announced (review finding).
+        announcement = settledAnnouncement(msg) || announcement;
+      }
+      announcedStatus.set(msg.id, msg.status);
+    }
+    for (const id of announcedStatus.keys()) {
+      if (!seen.has(id)) announcedStatus.delete(id);
+    }
+    announceSyncDone = true;
+  });
+</script>
+
+<div
+  {...restProps}
+  class={unstyled
+    ? [slotClasses?.root, className].filter(Boolean).join(' ')
+    : styles.root({ class: [slotClasses?.root, className] })}
+  data-stuck={stuck || undefined}
+>
+  <!-- Focusable scroll container (axe: scrollable-region-focusable) -->
+  <!-- svelte-ignore a11y_no_noninteractive_tabindex -->
+  <div
+    bind:this={viewportRef}
+    class={slot('viewport')}
+    role="region"
+    aria-label={listLabel}
+    tabindex="0"
+    onscroll={handleScroll}
+  >
+    {#if messages.length === 0}
+      <div class={slot('empty')}>
+        {#if empty}
+          {@render empty()}
+        {:else}
+          <EmptyState icon={MessageSquareIcon} title={emptyTitle} description={emptyDescription} />
+        {/if}
+      </div>
+    {:else}
+      <div bind:this={contentRef} class={slot('content')} role="log" aria-live="off">
+        {#each messages as msg, i (msg.id)}
+          {@const isLast = i === messages.length - 1}
+          {#if messageSnippet}
+            {@render messageSnippet({ message: msg, index: i, isLast })}
+          {:else}
+            <ChatMessage
+              message={msg}
+              {urlPolicy}
+              {partRenderers}
+              {layout}
+              {density}
+              onRegenerate={isLast && msg.role === 'assistant' && onRegenerate
+                ? () => onRegenerate(msg)
+                : undefined}
+              onRetry={onRetry ? () => onRetry(msg) : undefined}
+            />
+          {/if}
+        {/each}
+      </div>
+    {/if}
+  </div>
+
+  {#if showJumpButton}
+    <button
+      type="button"
+      class={slot('newButton')}
+      aria-label={newCount > 0 ? `${newCount} ${newMessagesLabel}` : scrollToBottomLabel}
+      onclick={() => {
+        scrollToBottom();
+        // Re-sticking unmounts this button — hand focus to the viewport so a
+        // keyboard activation does not drop focus to <body> (WCAG 2.4.3).
+        viewportRef?.focus();
+      }}
+    >
+      <ArrowDownIcon size={16} />
+      {#if newCount > 0}
+        <Badge intent="primary" size="xs" counter>{newCount}</Badge>
+      {/if}
+    </button>
+  {/if}
+
+  <div class="sr-only" role="status">{announcement}</div>
+</div>

package/dist/components/Chat/ChatMessageList/ChatMessageList.svelte.d.ts

@@ -0,0 +1,6 @@
+import type { ChatMessageListProps } from './index.js';
+declare const ChatMessageList: import("svelte").Component<ChatMessageListProps, {
+    scrollToBottom: (behavior?: ScrollBehavior) => void;
+}, "">;
+type ChatMessageList = ReturnType<typeof ChatMessageList>;
+export default ChatMessageList;

package/dist/components/Chat/ChatMessageList/chat-message-list.variants.d.ts

@@ -0,0 +1,23 @@
+import { type SlotNames, type VariantProps } from '../../../utils/variants.js';
+export declare const chatMessageListVariants: ((props?: {} | undefined) => {
+    root: (props?: ({} & {
+        class?: string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | /*elided*/ any | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined;
+    }) | undefined) => string;
+    viewport: (props?: ({} & {
+        class?: string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | /*elided*/ any | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined;
+    }) | undefined) => string;
+    content: (props?: ({} & {
+        class?: string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | /*elided*/ any | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined;
+    }) | undefined) => string;
+    empty: (props?: ({} & {
+        class?: string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | /*elided*/ any | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined;
+    }) | undefined) => string;
+    newButton: (props?: ({} & {
+        class?: string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | /*elided*/ any | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined;
+    }) | undefined) => string;
+}) & {
+    readonly config: import("../../../utils/variants.js").TVConfig;
+};
+export type ChatMessageListVariants = VariantProps<typeof chatMessageListVariants>;
+/** Slot names derived from the tv() config — single source of truth for slotClasses. */
+export type ChatMessageListSlots = SlotNames<typeof chatMessageListVariants>;

package/dist/components/Chat/ChatMessageList/chat-message-list.variants.js

@@ -0,0 +1,32 @@
+import { tv } from '../../../utils/variants.js';
+export const chatMessageListVariants = tv({
+    slots: {
+        // Positioning context for the floating new-messages button; fills the
+        // parent (Chat's body region) and delegates all scrolling to the viewport.
+        root: ['relative flex h-full min-h-0 flex-col'],
+        // The one scrolling element. Browser scroll anchoring is disabled — the
+        // engine does its own deterministic prepend anchoring (Safari has no
+        // overflow-anchor support, so we correct manually everywhere).
+        viewport: [
+            'min-h-0 flex-1 overflow-y-auto overscroll-contain',
+            '[overflow-anchor:none]',
+            'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary focus-visible:ring-inset'
+        ],
+        // The log element whose children are the messages.
+        content: ['flex flex-col gap-4 p-4'],
+        empty: ['flex h-full items-center justify-center p-6'],
+        // Floating pill centered over the bottom edge of the viewport.
+        newButton: [
+            'absolute bottom-3 left-1/2 -translate-x-1/2',
+            'inline-flex items-center gap-1.5',
+            'rounded-full border border-border-default bg-surface-overlay',
+            'px-3 py-1.5 text-sm text-text-primary',
+            'shadow-[var(--blocks-shadow-md)]',
+            'cursor-pointer select-none',
+            'transition-[background-color,color] duration-[var(--blocks-duration-fast)] ease-out',
+            'hover:bg-surface-hover',
+            'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary focus-visible:ring-offset-2'
+        ]
+    },
+    variants: {}
+});

package/dist/components/Chat/ChatMessageList/chat-scroll.d.ts

@@ -0,0 +1,45 @@
+/** Scroll metrics of the viewport at one point in time. */
+export interface ScrollSnapshot {
+    scrollTop: number;
+    scrollHeight: number;
+    clientHeight: number;
+}
+/**
+ * Distance from the bottom edge within which the user counts as "at the
+ * bottom": entering it re-sticks, and tiny upward wiggles inside it (trackpad
+ * inertia, macOS bounce) never unstick.
+ */
+export declare const RESTICK_PX = 24;
+export declare function distanceFromBottom(snapshot: ScrollSnapshot): number;
+/**
+ * Classify one scroll event. `lastScrollTop` is the previous event's position.
+ * Order matters: the bottom zone wins over direction, so bounce-back at the
+ * bottom edge stays stuck.
+ */
+export declare function resolveScrollIntent(snapshot: ScrollSnapshot, lastScrollTop: number): 'stick' | 'unstick' | 'none';
+/**
+ * How the message list changed between two renders, judged purely from ids —
+ * content growth inside an existing message (streaming) is deliberately NOT a
+ * transition (the follow behaviour reacts to it via ResizeObserver instead).
+ *
+ * - `append`   — new messages at the end (feeds the new-messages counter).
+ * - `prepend`  — older messages loaded at the top (needs the scroll anchor fix).
+ * - `truncate` — trailing messages removed (stable head, shorter list): NOT an
+ *   arrival, so it must never bump the counter (review finding, P2 wave).
+ * - `replace`  — both ends changed or the list was reset (jump to bottom).
+ * - `initial`  — first non-empty render (open at the bottom).
+ * Simultaneous append+prepend degrades to `replace` — rare (history load
+ * during streaming) and safe: worst case is one jump to the bottom.
+ */
+export type ListTransition = 'none' | 'initial' | 'append' | 'prepend' | 'truncate' | 'replace';
+export interface ListIdSnapshot {
+    firstId: string | undefined;
+    lastId: string | undefined;
+    length: number;
+}
+export declare function classifyTransition(prev: ListIdSnapshot, next: ListIdSnapshot): ListTransition;
+/**
+ * New messages added by an `append` transition. A same-length append (the tail
+ * message was swapped for a new id) still counts as one new message.
+ */
+export declare function appendedCount(prevLength: number, nextLength: number): number;

package/dist/components/Chat/ChatMessageList/chat-scroll.js

@@ -0,0 +1,52 @@
+// Pure decision logic for the ChatMessageList scroll engine — kept free of
+// DOM/Svelte so the invariants are node-testable.
+//
+// Core idea: programmatic follow-scrolling only ever moves DOWN, so any UPWARD
+// scroll movement is user intent and breaks the stick. Re-sticking happens by
+// proximity: whoever scrolls back into the bottom zone follows again. This
+// needs no "suppress programmatic scroll" flag and no event-source sniffing.
+/**
+ * Distance from the bottom edge within which the user counts as "at the
+ * bottom": entering it re-sticks, and tiny upward wiggles inside it (trackpad
+ * inertia, macOS bounce) never unstick.
+ */
+export const RESTICK_PX = 24;
+/** Minimum upward movement (px) that counts as deliberate user scrolling. */
+const UPWARD_INTENT_PX = 1;
+export function distanceFromBottom(snapshot) {
+    return Math.max(0, snapshot.scrollHeight - snapshot.scrollTop - snapshot.clientHeight);
+}
+/**
+ * Classify one scroll event. `lastScrollTop` is the previous event's position.
+ * Order matters: the bottom zone wins over direction, so bounce-back at the
+ * bottom edge stays stuck.
+ */
+export function resolveScrollIntent(snapshot, lastScrollTop) {
+    if (distanceFromBottom(snapshot) <= RESTICK_PX)
+        return 'stick';
+    if (snapshot.scrollTop < lastScrollTop - UPWARD_INTENT_PX)
+        return 'unstick';
+    return 'none';
+}
+export function classifyTransition(prev, next) {
+    if (next.length === 0)
+        return prev.length === 0 ? 'none' : 'replace';
+    if (prev.length === 0)
+        return 'initial';
+    const firstStable = prev.firstId === next.firstId;
+    const lastStable = prev.lastId === next.lastId;
+    if (firstStable && lastStable && next.length === prev.length)
+        return 'none';
+    if (firstStable)
+        return next.length < prev.length ? 'truncate' : 'append';
+    if (lastStable)
+        return 'prepend';
+    return 'replace';
+}
+/**
+ * New messages added by an `append` transition. A same-length append (the tail
+ * message was swapped for a new id) still counts as one new message.
+ */
+export function appendedCount(prevLength, nextLength) {
+    return Math.max(1, nextLength - prevLength);
+}

package/dist/components/Chat/ChatMessageList/index.d.ts

@@ -0,0 +1,93 @@
+import type { Snippet } from 'svelte';
+import type { HTMLAttributes } from 'svelte/elements';
+import type { ChatMessageProps } from '../ChatMessage/index.js';
+import type { ChatMessageData } from '../chat.types.js';
+import type { MarkdownUrlPolicy } from '../markdown/types.js';
+import type { ChatMessageListSlots } from './chat-message-list.variants.js';
+/** Render context handed to the per-message override snippet. */
+export interface ChatMessageListItemContext {
+    message: ChatMessageData;
+    index: number;
+    isLast: boolean;
+}
+/**
+ * @description Scrollable conversation log with a stick-to-bottom engine: follows
+ * streaming content while the reader is at the bottom, breaks off on upward scroll,
+ * and offers a floating jump-back button with a new-message counter. Anchors the
+ * scroll position when older history is prepended. Announces generation start and
+ * the completed answer once to screen readers instead of every token. Renders
+ * ChatMessage per entry by default; override per message via the `message` snippet.
+ *
+ * @tag ai
+ * @tag display
+ * @related ChatMessage
+ * @related Chat
+ * @related PromptInput
+ * @stability experimental
+ *
+ * @example
+ * ```svelte
+ * <ChatMessageList
+ *   {messages}
+ *   onRegenerate={(m) => regenerate(m.id)}
+ *   onStickChange={(stuck) => (following = stuck)}
+ * />
+ * ```
+ */
+export interface ChatMessageListProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children'> {
+    /**
+     * The conversation, oldest first. The component never mutates it. Note:
+     * rest attributes (incl. a raw `onscroll`) land on the non-scrolling root —
+     * observe follow-state via `onStickChange` instead.
+     */
+    messages: ChatMessageData[];
+    /** Per-message renderer override. Default: `<ChatMessage>` wired with the props below. */
+    message?: Snippet<[ChatMessageListItemContext]>;
+    /** Empty-state content. Default: an EmptyState with `emptyTitle`/`emptyDescription`. */
+    empty?: Snippet;
+    /** URL policy handed to every default ChatMessage (links, citations, attachments). */
+    urlPolicy?: MarkdownUrlPolicy;
+    /** Part-renderer overrides handed to every default ChatMessage. */
+    partRenderers?: ChatMessageProps['partRenderers'];
+    /** Message layout handed to every default ChatMessage. */
+    layout?: ChatMessageProps['layout'];
+    /** Message density handed to every default ChatMessage. */
+    density?: ChatMessageProps['density'];
+    /** Regenerate handler — wired only to the last message when it is an assistant message. */
+    onRegenerate?: (message: ChatMessageData) => void;
+    /** Retry handler for messages in `error`/`aborted` status. */
+    onRetry?: (message: ChatMessageData) => void;
+    /** Fires when the list starts (`true`) or stops (`false`) following new content. */
+    onStickChange?: (stuck: boolean) => void;
+    /** Accessible name of the scrollable conversation region. */
+    listLabel?: string;
+    /** Accessible label of the jump button when there are no new messages. */
+    scrollToBottomLabel?: string;
+    /** Label suffix of the jump button while new messages are pending (prefixed with the count). */
+    newMessagesLabel?: string;
+    /** Screen-reader announcement when an assistant message starts streaming. */
+    generatingLabel?: string;
+    /** Screen-reader announcement when a stream ends in `error` without text. */
+    errorLabel?: string;
+    /** Screen-reader announcement when a stream ends in `aborted` without text. */
+    abortedLabel?: string;
+    /** Empty-state heading. */
+    emptyTitle?: string;
+    /** Empty-state description. */
+    emptyDescription?: string;
+    /** Extra classes merged onto the root element. */
+    class?: string;
+    /** Remove all default tv classes. */
+    unstyled?: boolean;
+    /** Per-slot class overrides. Slots: root | viewport | content | empty | newButton */
+    slotClasses?: Partial<Record<ChatMessageListSlots, string>>;
+    /**
+     * Apply a named preset registered via `<BlocksProvider presets={{ ChatMessageList: {...} }}>`.
+     * Prefer this over `class` overrides when the requested look falls outside the
+     * semantic intent palette.
+     */
+    preset?: string;
+}
+export { default as ChatMessageList } from './ChatMessageList.svelte';
+export { type ChatMessageListVariants, chatMessageListVariants } from './chat-message-list.variants.js';
+export { appendedCount, classifyTransition, distanceFromBottom, type ListIdSnapshot, type ListTransition, resolveScrollIntent, type ScrollSnapshot } from './chat-scroll.js';

package/dist/components/Chat/ChatMessageList/index.js

@@ -0,0 +1,3 @@
+export { default as ChatMessageList } from './ChatMessageList.svelte';
+export { chatMessageListVariants } from './chat-message-list.variants.js';
+export { appendedCount, classifyTransition, distanceFromBottom, resolveScrollIntent } from './chat-scroll.js';