@urbicon-ui/blocks 6.34.0 → 6.36.0

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

@@ -0,0 +1,102 @@
+import type { Snippet } from 'svelte';
+import type { HTMLAttributes } from 'svelte/elements';
+import type { ChatMessageData, ChatMessagePart, ChatRole } from '../chat.types.js';
+import type { MarkdownUrlPolicy } from '../markdown/types.js';
+import type { ChatMessageSlots, ChatMessageVariants } from './chat-message.variants.js';
+/**
+ * Per-part snippet overrides keyed by part `type`. When a renderer exists for a
+ * part's type it replaces the built-in rendering for that part (one level up
+ * from StreamingMarkdown's node `renderers`) — this is how P3 swaps in
+ * ToolCallCard / ReasoningDisclosure and P4 adds A2UIView without touching this
+ * component. `source` is intentionally not overridable here: sources are
+ * collected into the citation footer, not rendered inline.
+ */
+export type ChatPartRenderers = {
+    [K in Exclude<ChatMessagePart['type'], 'source'>]?: Snippet<[
+        Extract<ChatMessagePart, {
+            type: K;
+        }>
+    ]>;
+};
+/**
+ * @description Renders one `ChatMessageData` — its ordered parts (markdown text via
+ * StreamingMarkdown, reasoning, tool-call status lines, policy-checked attachment
+ * chips) plus a citation footer, streaming placeholder, error/aborted Alert, a
+ * hover-revealed copy/regenerate action bar and a timestamp. `layout="bubble"`
+ * (default) tints and aligns per role; `layout="plain"` is a document-like
+ * full-width Claude-style column. Untrusted URLs never render as inline media —
+ * only as `urlPolicy`-checked download links. Compose many of these under
+ * ChatMessageList; the consumer owns the `ChatMessageData[]`.
+ *
+ * @tag ai
+ * @tag display
+ * @related ChatMessageList
+ * @related StreamingMarkdown
+ * @stability experimental
+ *
+ * @example
+ * ```svelte
+ * <ChatMessage message={msg} onRegenerate={() => regenerate(msg.id)} />
+ * ```
+ */
+export interface ChatMessageProps extends Omit<ChatMessageVariants, 'role'>, Omit<HTMLAttributes<HTMLDivElement>, 'children' | 'class'> {
+    /** The message to render. The component never mutates it. */
+    message: ChatMessageData;
+    /**
+     * URL policy applied to attachment links and forwarded to StreamingMarkdown /
+     * CitationChip. Strict by default (untrusted LLM/server output). Keep it
+     * referentially stable to avoid re-parsing streamed markdown.
+     */
+    urlPolicy?: MarkdownUrlPolicy;
+    /** Provide to render a "Regenerate" action. Called on click. */
+    onRegenerate?: () => void;
+    /** Provide to render a "Retry" button in the error/aborted Alert. Called on click. */
+    onRetry?: () => void;
+    /** Avatar override. Receives the message role; default is the Avatar primitive with a role icon. */
+    avatar?: Snippet<[{
+        role: ChatRole;
+    }]>;
+    /** Action-bar override. Receives the message; default is copy (+ regenerate when `onRegenerate` is set). */
+    actions?: Snippet<[{
+        message: ChatMessageData;
+    }]>;
+    /** Metadata override. Receives the message; default is `createdAt` as a `<time>` element. */
+    metadata?: Snippet<[{
+        message: ChatMessageData;
+    }]>;
+    /** Per-part-type render overrides (see `ChatPartRenderers`). */
+    partRenderers?: ChatPartRenderers;
+    /** Display names per role, shown in the `plain`-layout header. */
+    roleLabels?: Partial<Record<ChatRole, string>>;
+    /** Accessible label / tooltip for the copy action. @default 'Copy message' */
+    copyLabel?: string;
+    /** Accessible label shown briefly after a successful copy. @default 'Copied' */
+    copiedLabel?: string;
+    /** Accessible label / tooltip for the regenerate action. @default 'Regenerate' */
+    regenerateLabel?: string;
+    /** Label for the retry button in the error/aborted Alert. @default 'Retry' */
+    retryLabel?: string;
+    /** Alert title for `status === 'error'`. @default 'Something went wrong' */
+    errorLabel?: string;
+    /** Alert title for `status === 'aborted'`. @default 'Generation stopped' */
+    abortedLabel?: string;
+    /** Extra classes merged onto the root element. */
+    class?: string;
+    /** Remove all default tv classes. */
+    unstyled?: boolean;
+    /**
+     * Per-slot class overrides. Slots: root | container | header | roleName | avatar |
+     * bubble | partsFlow | attachment | attachmentIcon | attachmentName | attachmentSize |
+     * sourcesFooter | placeholder | statusAlert | footer | actions | actionButton |
+     * metadata. Reasoning and tool-call parts render through ReasoningDisclosure /
+     * ToolCallCard, which take their own `slotClasses`.
+     */
+    slotClasses?: Partial<Record<ChatMessageSlots, string>>;
+    /**
+     * Apply a named preset registered via `<BlocksProvider presets={{ ChatMessage: {...} }}>`.
+     * Prefer this over `class` overrides for reusable custom looks.
+     */
+    preset?: string;
+}
+export { default as ChatMessage } from './ChatMessage.svelte';
+export { type ChatMessageSlots, type ChatMessageVariants, chatMessageVariants } from './chat-message.variants.js';

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

@@ -0,0 +1,2 @@
+export { default as ChatMessage } from './ChatMessage.svelte';
+export { chatMessageVariants } from './chat-message.variants.js';

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);
+}