@urbicon-ui/blocks 6.34.0 → 6.36.0

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';

package/dist/components/Chat/CitationChip/CitationChip.svelte

@@ -0,0 +1,107 @@
+<script lang="ts">
+  import { Popover } from '../../../primitives';
+  import { getBlocksConfig, resolveSlotClasses } from '../../../provider';
+  import { resolveIcon } from '../../../icons';
+  import LinkIconDefault from '../../../icons/LinkIcon.svelte';
+  import { checkLinkUrl } from '../markdown/url-policy.js';
+  import { citationChipVariants } from './citation-chip.variants';
+  import type { CitationChipProps } from './index';
+
+  const LinkIcon = resolveIcon('link', LinkIconDefault);
+
+  let {
+    source,
+    index,
+    citationStyle = 'numeric',
+    urlPolicy,
+    openLabel = 'Open source',
+    label,
+    class: className,
+    unstyled: unstyledProp = false,
+    slotClasses: slotClassesProp = {},
+    preset,
+    ...restProps
+  }: CitationChipProps = $props();
+
+  const blocksConfig = getBlocksConfig();
+  const unstyled = $derived(unstyledProp || blocksConfig?.unstyled || false);
+
+  const variantProps = $derived({ citationStyle });
+  const styles = $derived(citationChipVariants(variantProps));
+  const slotClasses = $derived(
+    resolveSlotClasses(blocksConfig, 'CitationChip', preset, variantProps, slotClassesProp)
+  );
+
+  // Numeric markers show the 1-based ordinal, falling back to the raw id when
+  // no index is supplied (standalone reference lists). Label markers show the
+  // (truncated) title.
+  const displayLabel = $derived(
+    citationStyle === 'label' ? source.title : index != null ? String(index) : source.id
+  );
+
+  const ariaLabel = $derived(
+    label ?? (index != null ? `Source ${index}: ${source.title}` : `Source: ${source.title}`)
+  );
+
+  // Run the same strict URL policy as the streaming-markdown engine: a blocked
+  // or absent URL yields no link, only the title/snippet.
+  const linkCheck = $derived(
+    source.url !== undefined ? checkLinkUrl(source.url, urlPolicy) : ({ ok: false } as const)
+  );
+  const linkHref = $derived(linkCheck.ok ? linkCheck.href : undefined);
+</script>
+
+<!-- The aria-label on Popover lands on the panel via its restProps spread, so
+     the opened popover is not an unnamed dialog (axe: aria-dialog-name). -->
+<Popover placement="bottom-start" aria-label={ariaLabel}>
+  {#snippet trigger()}
+    <button
+      type="button"
+      class={unstyled
+        ? [slotClasses?.trigger, className].filter(Boolean).join(' ')
+        : styles.trigger({ class: [slotClasses?.trigger, className] })}
+      aria-label={ariaLabel}
+      {...restProps}
+    >
+      <!-- truncate must sit on an inner block-ish span: on the inline-flex
+           trigger itself the ellipsis never renders and justify-center clips
+           the START of long labels. -->
+      <span class="min-w-0 truncate">{displayLabel}</span>
+    </button>
+  {/snippet}
+  <div
+    class={unstyled
+      ? (slotClasses?.popover ?? '')
+      : styles.popover({ class: slotClasses?.popover })}
+  >
+    <span
+      class={unstyled ? (slotClasses?.title ?? '') : styles.title({ class: slotClasses?.title })}
+    >
+      {source.title}
+    </span>
+    {#if source.snippet}
+      <p
+        class={unstyled
+          ? (slotClasses?.snippet ?? '')
+          : styles.snippet({ class: slotClasses?.snippet })}
+      >
+        {source.snippet}
+      </p>
+    {/if}
+    {#if linkHref}
+      <a
+        href={linkHref}
+        target="_blank"
+        rel="noopener noreferrer"
+        class={unstyled ? (slotClasses?.link ?? '') : styles.link({ class: slotClasses?.link })}
+      >
+        <LinkIcon
+          class={unstyled
+            ? (slotClasses?.linkIcon ?? '')
+            : styles.linkIcon({ class: slotClasses?.linkIcon })}
+        />
+        {openLabel}
+      </a>
+    {/if}
+  </div>
+</Popover>

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

@@ -0,0 +1,4 @@
+import type { CitationChipProps } from './index.js';
+declare const CitationChip: import("svelte").Component<CitationChipProps, {}, "">;
+type CitationChip = ReturnType<typeof CitationChip>;
+export default CitationChip;

package/dist/components/Chat/CitationChip/citation-chip.variants.d.ts

@@ -0,0 +1,40 @@
+import { type SlotNames, type VariantProps } from '../../../utils/variants.js';
+export declare const citationChipVariants: ((props?: {
+    citationStyle?: "numeric" | "label" | undefined;
+} | undefined) => {
+    trigger: (props?: ({
+        citationStyle?: "numeric" | "label" | undefined;
+    } & {
+        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;
+    popover: (props?: ({
+        citationStyle?: "numeric" | "label" | undefined;
+    } & {
+        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;
+    title: (props?: ({
+        citationStyle?: "numeric" | "label" | undefined;
+    } & {
+        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;
+    snippet: (props?: ({
+        citationStyle?: "numeric" | "label" | undefined;
+    } & {
+        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;
+    link: (props?: ({
+        citationStyle?: "numeric" | "label" | undefined;
+    } & {
+        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;
+    linkIcon: (props?: ({
+        citationStyle?: "numeric" | "label" | undefined;
+    } & {
+        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 CitationChipVariants = VariantProps<typeof citationChipVariants>;
+/** Slot names derived from the tv() config — single source of truth for slotClasses. */
+export type CitationChipSlots = SlotNames<typeof citationChipVariants>;

package/dist/components/Chat/CitationChip/citation-chip.variants.js

@@ -0,0 +1,42 @@
+import { tv } from '../../../utils/variants.js';
+export const citationChipVariants = tv({
+    slots: {
+        // Compact inline chip in the Badge soft-primary idiom. `align-baseline`
+        // + `leading-none` keep it seated on the text baseline so an inline
+        // citation marker never bumps the surrounding line height.
+        trigger: [
+            'inline-flex items-center justify-center align-baseline',
+            'bg-primary-subtle text-primary-emphasis',
+            'text-xs font-medium leading-none tabular-nums',
+            'rounded-full px-1.5 py-0.5 cursor-pointer',
+            'transition-colors duration-[var(--blocks-duration-fast)] ease-out',
+            'hover:bg-primary/15',
+            'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary'
+        ],
+        // Content wrapper INSIDE the Popover panel — the panel itself already
+        // supplies surface / border / shadow / padding, so this only lays out.
+        popover: 'flex flex-col gap-1.5 max-w-xs',
+        title: 'font-medium text-text-primary text-sm',
+        snippet: 'text-text-secondary text-sm line-clamp-3',
+        link: [
+            'inline-flex items-center gap-1 self-start',
+            'text-sm text-primary rounded-modify',
+            'hover:underline',
+            'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary'
+        ],
+        linkIcon: 'h-3.5 w-3.5 shrink-0'
+    },
+    variants: {
+        citationStyle: {
+            // Numeric marker — a fixed-width numeric pill; no truncation.
+            numeric: {},
+            // Label marker — carries the source title, capped so a long title
+            // can't stretch the chip across the line. The ellipsis itself lives on
+            // an inner span (truncate doesn't render on the inline-flex trigger).
+            label: { trigger: 'max-w-[16ch]' }
+        }
+    },
+    defaultVariants: {
+        citationStyle: 'numeric'
+    }
+});

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

@@ -0,0 +1,69 @@
+import type { HTMLButtonAttributes } from 'svelte/elements';
+import type { MarkdownUrlPolicy } from '../markdown/types.js';
+import type { CitationChipSlots } from './citation-chip.variants.js';
+/**
+ * A cited source surfaced behind a `[id]` citation marker. `id` keys the
+ * source to its marker; `title` is always shown, `url` / `snippet` are optional
+ * and only render when present (and, for `url`, when the URL policy allows it).
+ */
+export interface CitationSource {
+    /** Stable id — matches the `[id]` marker in the streamed markdown. */
+    id: string;
+    /** Human-readable source title, always shown in the popover (and as the chip label under `citationStyle="label"`). */
+    title: string;
+    /** Source URL. Rendered as an outbound link only when it passes the `urlPolicy`; a blocked or absent URL shows title/snippet with no link. */
+    url?: string;
+    /** Short excerpt shown under the title, clamped to ~3 lines. */
+    snippet?: string;
+}
+/**
+ * @description Compact source marker rendered for a `[id]` citation. StreamingMarkdown wires it up automatically from its `sources` prop — each in-text marker becomes a CitationChip whose click opens a Popover with the source title, snippet, and a policy-checked outbound link. Also usable standalone for source footers / reference lists outside a streamed message.
+ * @tag ai
+ * @related StreamingMarkdown
+ * @related Badge
+ * @related Popover
+ * @stability experimental
+ */
+export interface CitationChipProps extends Omit<HTMLButtonAttributes, 'class' | 'children'> {
+    /** The cited source. Required. */
+    source: CitationSource;
+    /** 1-based ordinal shown as the chip label under `citationStyle="numeric"`. Falls back to `source.id` when omitted. */
+    index?: number;
+    /**
+     * What the chip shows: `numeric` renders `index` (or `source.id` as a
+     * fallback) as a compact numeric pill; `label` renders the (truncated)
+     * `source.title`.
+     * @default 'numeric'
+     */
+    citationStyle?: 'numeric' | 'label';
+    /**
+     * URL policy applied to `source.url` before it becomes a link (same strict
+     * default as the streaming-markdown engine — untrusted LLM output). A blocked
+     * URL yields no link in the popover, only title/snippet.
+     */
+    urlPolicy?: MarkdownUrlPolicy;
+    /**
+     * Text of the outbound link in the popover.
+     * @default 'Open source'
+     */
+    openLabel?: string;
+    /**
+     * Override the trigger's `aria-label`. Defaults to
+     * `Source {index}: {title}` (or `Source: {title}` without an index).
+     */
+    label?: string;
+    /** Extra classes merged onto the trigger chip (the root slot). */
+    class?: string;
+    /** Strip all default tv() classes; combine with `class` / `slotClasses` for a custom look. */
+    unstyled?: boolean;
+    /** Per-slot class overrides. Slots: `trigger` (root chip), `popover` (content wrapper), `title`, `snippet`, `link`, `linkIcon`. */
+    slotClasses?: Partial<Record<CitationChipSlots, string>>;
+    /**
+     * Apply a named preset registered via `<BlocksProvider presets={{ CitationChip: {...} }}>`.
+     * Prefer this over `class` overrides when the requested look falls outside the
+     * semantic intent palette.
+     */
+    preset?: string;
+}
+export { default as CitationChip } from './CitationChip.svelte';
+export { type CitationChipSlots, type CitationChipVariants, citationChipVariants } from './citation-chip.variants.js';

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

@@ -0,0 +1,2 @@
+export { default as CitationChip } from './CitationChip.svelte';
+export { citationChipVariants } from './citation-chip.variants.js';

package/dist/components/Chat/CodeBlock/CodeBlock.svelte

@@ -0,0 +1,120 @@
+<script lang="ts">
+  import { getBlocksConfig, resolveSlotClasses } from '../../../provider';
+  import { resolveIcon } from '../../../icons';
+  import CopyIconDefault from '../../../icons/CopyIcon.svelte';
+  import CheckIconDefault from '../../../icons/CheckIcon.svelte';
+  import { codeBlockVariants, type CodeBlockVariants } from './code-block.variants';
+  import type { CodeBlockProps } from './index';
+
+  let {
+    code,
+    lang,
+    showCopy = true,
+    wrap = false,
+    copyLabel = 'Copy code',
+    copiedLabel = 'Copied',
+    onCopy,
+    actions,
+    class: className,
+    unstyled: unstyledProp = false,
+    slotClasses: slotClassesProp = {},
+    preset,
+    ...restProps
+  }: CodeBlockProps = $props();
+
+  const blocksConfig = getBlocksConfig();
+  const unstyled = $derived(unstyledProp || blocksConfig?.unstyled || false);
+
+  const CopyIcon = resolveIcon('copy', CopyIconDefault);
+  const CheckIcon = resolveIcon('check', CheckIconDefault);
+
+  const variantProps: CodeBlockVariants = $derived({ wrap });
+  const styles = $derived(codeBlockVariants(variantProps));
+  const slotClasses = $derived(
+    resolveSlotClasses(blocksConfig, 'CodeBlock', preset, variantProps, slotClassesProp)
+  );
+
+  function cls(name: keyof typeof slotClasses, extra?: string | (string | undefined)[]) {
+    if (unstyled) {
+      const own = slotClasses?.[name];
+      return [own, ...(Array.isArray(extra) ? extra : [extra])].filter(Boolean).join(' ');
+    }
+    const slotFns = styles as Record<string, (args: { class?: unknown }) => string>;
+    return slotFns[name]({
+      class: [slotClasses?.[name], ...(Array.isArray(extra) ? extra : [extra])]
+    });
+  }
+
+  const showHeader = $derived(!!lang || showCopy || !!actions);
+  const regionLabel = $derived(lang ? `${lang} code` : 'Code');
+
+  let copied = $state(false);
+  let resetTimer: ReturnType<typeof setTimeout> | undefined;
+
+  async function copyCode() {
+    try {
+      await navigator.clipboard.writeText(code);
+      copied = true;
+      if (resetTimer) clearTimeout(resetTimer);
+      resetTimer = setTimeout(() => {
+        copied = false;
+        resetTimer = undefined;
+      }, 2000);
+      onCopy?.(code);
+    } catch (err) {
+      // Never swallow silently — but leave state untouched so the UI does not
+      // falsely confirm a copy that failed (e.g. denied clipboard permission).
+      console.error('CodeBlock: failed to copy code', err);
+    }
+  }
+
+  // Clear a pending reset on unmount so the timer can't fire into a torn-down component.
+  $effect(() => () => {
+    if (resetTimer) clearTimeout(resetTimer);
+  });
+</script>
+
+<div class={cls('root', className)} {...restProps}>
+  {#if showHeader}
+    <div class={cls('header')}>
+      <span class={cls('langLabel')}>{lang ?? ''}</span>
+      <div class="flex items-center gap-1">
+        {@render actions?.()}
+        {#if showCopy}
+          <button
+            type="button"
+            class={cls('copyButton')}
+            onclick={copyCode}
+            aria-label={copied ? copiedLabel : copyLabel}
+          >
+            {#if copied}
+              <CheckIcon size={14} />
+            {:else}
+              <CopyIcon size={14} />
+            {/if}
+            <span>{copied ? copiedLabel : copyLabel}</span>
+          </button>
+        {/if}
+      </div>
+    </div>
+  {/if}
+
+  <!--
+    Scrollable code region: tabindex=0 + role=region + aria-label so keyboard
+    users can reach and scroll the overflow (WCAG 2.1.1). Svelte flags tabindex
+    on a "noninteractive" element, but a focusable scroll container is the
+    sanctioned exception here.
+  -->
+  <!-- svelte-ignore a11y_no_noninteractive_tabindex -->
+  <pre class={cls('pre')} tabindex="0" role="region" aria-label={regionLabel}><code
+      class={cls('code')}>{code}</code
+    ></pre>
+
+  <!--
+    Copy confirmation for screen readers. A label change on the button the user
+    just activated is not a reliable announcement — a live status region is. It
+    must exist in the DOM before `copied` flips, so it always renders and only
+    its text content changes.
+  -->
+  <span class="sr-only" role="status">{copied ? copiedLabel : ''}</span>
+</div>

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

@@ -0,0 +1,4 @@
+import type { CodeBlockProps } from './index.js';
+declare const CodeBlock: import("svelte").Component<CodeBlockProps, {}, "">;
+type CodeBlock = ReturnType<typeof CodeBlock>;
+export default CodeBlock;

package/dist/components/Chat/CodeBlock/code-block.variants.d.ts

@@ -0,0 +1,40 @@
+import { type SlotNames, type VariantProps } from '../../../utils/variants.js';
+export declare const codeBlockVariants: ((props?: {
+    wrap?: boolean | undefined;
+} | undefined) => {
+    root: (props?: ({
+        wrap?: boolean | undefined;
+    } & {
+        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;
+    header: (props?: ({
+        wrap?: boolean | undefined;
+    } & {
+        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;
+    langLabel: (props?: ({
+        wrap?: boolean | undefined;
+    } & {
+        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;
+    copyButton: (props?: ({
+        wrap?: boolean | undefined;
+    } & {
+        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;
+    pre: (props?: ({
+        wrap?: boolean | undefined;
+    } & {
+        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;
+    code: (props?: ({
+        wrap?: boolean | undefined;
+    } & {
+        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 CodeBlockVariants = VariantProps<typeof codeBlockVariants>;
+/** Slot names derived from the tv() config — single source of truth for slotClasses. */
+export type CodeBlockSlots = SlotNames<typeof codeBlockVariants>;

package/dist/components/Chat/CodeBlock/code-block.variants.js

@@ -0,0 +1,51 @@
+import { tv } from '../../../utils/variants.js';
+export const codeBlockVariants = tv({
+    slots: {
+        // Architectural surface — an elevated card, structure radius, clipped so the
+        // scrollable body respects the rounded corners.
+        root: [
+            'relative block w-full overflow-hidden box-border',
+            'bg-surface-elevated border border-border-subtle rounded-contain'
+        ],
+        // Header only renders when there is something to show (lang / copy / actions).
+        header: [
+            'flex items-center justify-between gap-2',
+            'px-3 py-1.5 border-b border-border-subtle'
+        ],
+        langLabel: ['font-mono text-xs text-text-tertiary select-none'],
+        copyButton: [
+            'inline-flex items-center gap-1.5',
+            'px-2 py-1 rounded-modify',
+            'font-mono text-xs text-text-secondary',
+            'cursor-pointer select-none',
+            'transition-[color,background-color] duration-[var(--blocks-duration-fast)] ease-out',
+            'hover:bg-surface-hover hover:text-text-primary',
+            'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary focus-visible:ring-offset-2'
+        ],
+        // The scrollable region. Body horizontal scroll stays INSIDE the block —
+        // never the page. Focusable + role=region so keyboard users can reach the
+        // scroll (a11y for scrollable content).
+        pre: [
+            'm-0 px-3 py-2.5',
+            'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary focus-visible:ring-inset'
+        ],
+        code: ['font-mono text-sm text-text-primary']
+    },
+    variants: {
+        // false → single-line semantics, horizontal scroll inside the block.
+        // true  → soft-wrap long lines, no horizontal scroll.
+        wrap: {
+            true: {
+                pre: 'whitespace-pre-wrap break-words',
+                code: 'whitespace-pre-wrap break-words'
+            },
+            false: {
+                pre: 'overflow-x-auto',
+                code: 'whitespace-pre'
+            }
+        }
+    },
+    defaultVariants: {
+        wrap: false
+    }
+});