@lostgradient/cinder 0.6.0 → 0.8.0

package/src/components/chat/container/use-chat-unread-state.svelte.ts

@@ -0,0 +1,170 @@
+/**
+ * Runes helper for chat unread state tracking.
+ *
+ * Manages:
+ * - Unread message count
+ * - New message indicator visibility
+ * - First unread message ID for divider placement
+ * - Screen reader announcements
+ */
+import { untrack } from 'svelte';
+import { useAnnouncer } from '../../../utilities/use-announcer.svelte.ts';
+import { formatUnreadCount, isLargeCount } from './scroll-utilities';
+// ==========================================================================
+// Helper
+// ==========================================================================
+/**
+ * Creates reactive state and methods for tracking unread messages.
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   import { useChatUnreadState } from './use-chat-unread-state.svelte';
+ *
+ *   const unreadState = useChatUnreadState({
+ *     onUnreadIndicatorChange: (event) => console.log('Unread changed:', event),
+ *   });
+ *
+ *   // Call in an $effect to process message changes
+ *   // Pass a getter function for atBottom to avoid creating a scroll dependency
+ *   $effect(() => {
+ *     unreadState.processMessages(messages, conversation.id, () => scrollState.atBottom);
+ *   });
+ *
+ *   // Mark as read when user scrolls to bottom
+ *   if (atBottom) unreadState.markAllAsRead();
+ * </script>
+ *
+ * <div aria-live="polite" class="sr-only">
+ *   {unreadState.announcerMessage}
+ * </div>
+ * ```
+ */
+export function useChatUnreadState(options) {
+    const { announcerDebounceMs = 300, onUnreadIndicatorChange } = options ?? {};
+    // Internal reactive state
+    let unreadCount = $state(0);
+    let newMessageIndicatorVisible = $state(false);
+    let firstUnreadId = $state(null);
+    // Non-reactive bookkeeping (prevents $effect infinite loops)
+    let previousMessageCount = 0;
+    let previousLastMessageId = null;
+    let previousConversationId = null;
+    // Screen reader announcements - use debounce to batch rapid message arrivals
+    const announcer = useAnnouncer({ debounceMs: announcerDebounceMs });
+    // Derived display values
+    const displayUnreadCount = $derived(formatUnreadCount(unreadCount));
+    const hasLargeCount = $derived(isLargeCount(unreadCount));
+    /**
+     * Fire the indicator-change callback from the mutation sites that actually
+     * change `unreadCount` / `newMessageIndicatorVisible`. Driving it here (rather
+     * than from an `$effect`) avoids the spurious `{ unreadCount: 0,
+     * newMessageIndicatorVisible: false }` notification that an effect would emit on
+     * mount, and keeps the contract aligned with `onScrollStateChange`, which
+     * only fires from its own mutation site.
+     */
+    function notifyIndicatorChange() {
+        onUnreadIndicatorChange?.({
+            unreadCount,
+            newMessageIndicatorVisible,
+        });
+    }
+    /**
+     * Mark all messages as read (resets unread state).
+     */
+    function markAllAsRead() {
+        const changed = unreadCount !== 0 || newMessageIndicatorVisible;
+        unreadCount = 0;
+        newMessageIndicatorVisible = false;
+        firstUnreadId = null;
+        if (changed)
+            notifyIndicatorChange();
+    }
+    /**
+     * Process messages to detect new arrivals and update unread state.
+     * This should be called from an $effect in the parent component.
+     *
+     * @param getAtBottom - Getter function to read atBottom without creating a dependency.
+     */
+    function processMessages(messages, conversationId, getAtBottom) {
+        // Check if conversation has changed - reset tracking if so
+        if (conversationId !== previousConversationId) {
+            // Conversation switched - reset all tracking state
+            previousMessageCount = messages.length;
+            previousLastMessageId = messages.at(-1)?.id ?? null;
+            previousConversationId = conversationId;
+            // Reset all unread state when switching conversations
+            markAllAsRead();
+            return; // Don't trigger new message detection on conversation switch
+        }
+        const currentCount = messages.length;
+        const prevCount = previousMessageCount;
+        const currentLastMessageId = messages.at(-1)?.id ?? null;
+        // Detect whether new messages were appended (vs prepended history)
+        // Appended: last message ID changed AND count increased
+        // Prepended: last message ID unchanged but count increased (history loaded)
+        const wasAppended = currentCount > prevCount &&
+            prevCount > 0 &&
+            currentLastMessageId !== null &&
+            currentLastMessageId !== previousLastMessageId;
+        if (wasAppended) {
+            // New messages arrived at the end
+            // Read atBottom via getter to avoid creating a reactive dependency
+            // The getter is called inside untrack to ensure no dependency tracking
+            const atBottom = untrack(getAtBottom);
+            if (!atBottom) {
+                // User is reading history - show indicator
+                const newMessageCount = currentCount - prevCount;
+                unreadCount += newMessageCount;
+                newMessageIndicatorVisible = true;
+                // Set first unread ID if not already set
+                // The first new message is at index (currentCount - newMessageCount)
+                if (firstUnreadId === null) {
+                    const firstNewIndex = currentCount - newMessageCount;
+                    const firstNewMessage = messages[firstNewIndex];
+                    if (firstNewMessage) {
+                        firstUnreadId = firstNewMessage.id;
+                    }
+                }
+                // Announce to screen readers using accumulated unreadCount
+                // (not newMessageCount) to handle debouncing correctly - if multiple
+                // batches arrive within the debounce window, we announce the total
+                announcer.announce(unreadCount === 1 ? 'New message received' : `${unreadCount} new messages received`);
+                // Notify the consumer at the mutation site so the callback reflects the
+                // freshly-updated unread state and never fires spuriously on mount.
+                notifyIndicatorChange();
+            }
+        }
+        previousMessageCount = currentCount;
+        previousLastMessageId = currentLastMessageId;
+    }
+    /**
+     * Cleanup resources.
+     */
+    function destroy() {
+        announcer.destroy();
+    }
+    return {
+        get unreadCount() {
+            return unreadCount;
+        },
+        get newMessageIndicatorVisible() {
+            return newMessageIndicatorVisible;
+        },
+        get firstUnreadId() {
+            return firstUnreadId;
+        },
+        get displayUnreadCount() {
+            return displayUnreadCount;
+        },
+        get hasLargeCount() {
+            return hasLargeCount;
+        },
+        get announcerMessage() {
+            return announcer.message;
+        },
+        markAllAsRead,
+        processMessages,
+        destroy,
+    };
+}

package/src/components/chat/container/use-chat-virtualizer.svelte.ts

@@ -0,0 +1,260 @@
+export function calculateChatVirtualWindow(input) {
+    const itemCount = Math.max(0, Math.trunc(input.itemCount));
+    if (itemCount === 0)
+        return { startIndex: 0, endIndex: 0 };
+    const itemSize = Math.max(1, input.itemSize);
+    const overscan = Math.max(0, Math.trunc(input.overscan));
+    const scrollTop = Math.max(0, input.scrollTop);
+    const containerHeight = Math.max(0, input.containerHeight);
+    const visibleCount = Math.max(1, Math.ceil(containerHeight / itemSize));
+    const maxStartIndex = Math.max(0, itemCount - visibleCount);
+    const startIndex = Math.min(maxStartIndex, Math.max(0, Math.floor(scrollTop / itemSize) - overscan));
+    const endIndex = Math.min(itemCount, startIndex + visibleCount + overscan * 2);
+    return { startIndex, endIndex };
+}
+export class ChatVirtualizer {
+    options;
+    #scrollElement = null;
+    #scrollOffset = $state(0);
+    #measurementVersion = $state(0);
+    #offsetsCache = null;
+    #offsetsCacheCount = -1;
+    #offsetsCacheMeasurementVersion = -1;
+    #measuredSizes = new Map();
+    constructor(options) {
+        this.options = options;
+    }
+    get virtualItems() {
+        return this.#virtualItems();
+    }
+    get totalSize() {
+        const offsets = this.#offsets();
+        return offsets[offsets.length - 1] ?? 0;
+    }
+    get scrollPaddingStart() {
+        return this.#scrollPaddingStart();
+    }
+    get scrollSize() {
+        return this.scrollPaddingStart + this.totalSize;
+    }
+    get scrollOffset() {
+        return this.#scrollOffset;
+    }
+    setScrollElement(element) {
+        if (this.#scrollElement === element)
+            return;
+        this.#scrollElement?.removeEventListener('scroll', this.#handleScroll);
+        this.#scrollElement = element;
+        this.#scrollOffset = element?.scrollTop ?? 0;
+        this.#scrollElement?.addEventListener('scroll', this.#handleScroll, { passive: true });
+    }
+    scrollElement = (node) => {
+        this.setScrollElement(node);
+        return () => {
+            if (this.#scrollElement === node) {
+                this.setScrollElement(null);
+            }
+        };
+    };
+    measureElement = (node) => {
+        this.measureElementNode(node);
+        if (typeof ResizeObserver !== 'function')
+            return undefined;
+        const resizeObserver = new ResizeObserver(() => {
+            this.measureElementNode(node);
+        });
+        resizeObserver.observe(node);
+        return () => {
+            resizeObserver.disconnect();
+        };
+    };
+    measureElementNode(node) {
+        if (!node)
+            return;
+        this.#measureNode(node);
+    }
+    syncOptions() {
+        const count = this.options.getCount();
+        const currentKeys = new Set();
+        for (let index = 0; index < count; index += 1) {
+            currentKeys.add(this.options.getItemKey(index));
+        }
+        let changed = false;
+        for (const key of this.#measuredSizes.keys()) {
+            if (!currentKeys.has(key)) {
+                this.#measuredSizes.delete(key);
+                changed = true;
+            }
+        }
+        if (changed)
+            this.#measurementVersion += 1;
+    }
+    scrollToIndex(index, options = { align: 'auto' }) {
+        const count = this.options.getCount();
+        if (count === 0)
+            return;
+        const clampedIndex = Math.max(0, Math.min(Math.trunc(index), count - 1));
+        const offsets = this.#offsets();
+        const itemStart = offsets[clampedIndex] ?? 0;
+        const itemEnd = offsets[clampedIndex + 1] ?? itemStart + this.#estimatedSize();
+        const itemSize = itemEnd - itemStart;
+        const viewportHeight = this.#containerHeight();
+        const paddingStart = this.#scrollPaddingStart();
+        const viewportStart = Math.max(0, this.scrollOffset - paddingStart);
+        const viewportEnd = viewportStart + viewportHeight;
+        let offset = itemStart + paddingStart;
+        if (options.align === 'end') {
+            offset = itemEnd + paddingStart - viewportHeight;
+        }
+        else if (options.align === 'center') {
+            offset = itemStart + paddingStart - (viewportHeight - itemSize) / 2;
+        }
+        else if (options.align === 'auto') {
+            if (itemStart >= viewportStart && itemEnd <= viewportEnd)
+                return;
+            offset =
+                itemStart < viewportStart
+                    ? itemStart + paddingStart
+                    : itemEnd + paddingStart - viewportHeight;
+        }
+        this.scrollToOffset(offset, options);
+    }
+    getVirtualItem(index) {
+        const count = this.options.getCount();
+        if (count === 0)
+            return null;
+        const clampedIndex = Math.max(0, Math.min(Math.trunc(index), count - 1));
+        return this.#virtualItemAt(clampedIndex, this.#offsets());
+    }
+    scrollToOffset(offset, options) {
+        const element = this.#getScrollElement();
+        const maximumOffset = Math.max(0, this.scrollSize - this.#containerHeight());
+        const top = Math.min(maximumOffset, Math.max(0, offset));
+        this.#scrollOffset = top;
+        if (element) {
+            const behavior = options?.behavior === 'instant' ? 'auto' : options?.behavior;
+            if (typeof element.scrollTo === 'function' && behavior && behavior !== 'auto') {
+                element.scrollTo({ top, behavior });
+                return;
+            }
+            element.scrollTop = top;
+            return;
+        }
+    }
+    #handleScroll = () => {
+        this.#scrollOffset = this.#scrollElement?.scrollTop ?? 0;
+    };
+    #getScrollElement() {
+        return this.#scrollElement ?? this.options.getScrollElement();
+    }
+    #containerHeight() {
+        const element = this.#getScrollElement();
+        return element?.clientHeight || this.options.getInitialHeight();
+    }
+    #scrollPaddingStart() {
+        return Math.max(0, this.options.getScrollPaddingStart?.() ?? 0);
+    }
+    #estimatedSize() {
+        return Math.max(1, this.options.getEstimatedSize());
+    }
+    #itemSize(index) {
+        const key = this.options.getItemKey(index);
+        return this.#measuredSizes.get(key) ?? this.#estimatedSize();
+    }
+    #offsets() {
+        const count = this.options.getCount();
+        const measurementVersion = this.#measurementVersion;
+        if (this.#offsetsCache &&
+            this.#offsetsCacheCount === count &&
+            this.#offsetsCacheMeasurementVersion === measurementVersion) {
+            return this.#offsetsCache;
+        }
+        const offsets = Array.from({ length: count + 1 });
+        let offset = 0;
+        offsets[0] = 0;
+        for (let index = 0; index < count; index += 1) {
+            offset += this.#itemSize(index);
+            offsets[index + 1] = offset;
+        }
+        this.#offsetsCache = offsets;
+        this.#offsetsCacheCount = count;
+        this.#offsetsCacheMeasurementVersion = measurementVersion;
+        return offsets;
+    }
+    #readElementSize(node) {
+        const rectHeight = node.getBoundingClientRect().height;
+        return Math.ceil(rectHeight || node.scrollHeight || node.offsetHeight || 0);
+    }
+    #measureNode(node) {
+        const index = Number(node.dataset['cinderVirtualIndex']);
+        if (!Number.isInteger(index) || index < 0 || index >= this.options.getCount())
+            return;
+        const measuredSize = this.#readElementSize(node);
+        if (measuredSize <= 0)
+            return;
+        const key = this.options.getItemKey(index);
+        if (this.#measuredSizes.get(key) === measuredSize)
+            return;
+        this.#measuredSizes.set(key, measuredSize);
+        this.#measurementVersion += 1;
+    }
+    #startIndex(offsets, scrollTop) {
+        const count = Math.max(0, offsets.length - 1);
+        let low = 0;
+        let high = count;
+        while (low < high) {
+            const mid = Math.floor((low + high) / 2);
+            if ((offsets[mid + 1] ?? 0) <= scrollTop) {
+                low = mid + 1;
+            }
+            else {
+                high = mid;
+            }
+        }
+        return low;
+    }
+    #endIndex(offsets, viewportEnd) {
+        const count = Math.max(0, offsets.length - 1);
+        let low = 0;
+        let high = count;
+        while (low < high) {
+            const mid = Math.floor((low + high) / 2);
+            if ((offsets[mid] ?? 0) < viewportEnd) {
+                low = mid + 1;
+            }
+            else {
+                high = mid;
+            }
+        }
+        return low;
+    }
+    #virtualItemAt(index, offsets) {
+        const start = offsets[index] ?? 0;
+        const end = offsets[index + 1] ?? start + this.#estimatedSize();
+        return {
+            key: this.options.getItemKey(index),
+            index,
+            start,
+            end,
+            size: end - start,
+            lane: 0,
+        };
+    }
+    #virtualItems() {
+        const count = this.options.getCount();
+        if (count === 0)
+            return [];
+        const offsets = this.#offsets();
+        const overscan = Math.max(0, Math.trunc(this.options.getOverscan()));
+        const scrollTop = Math.max(0, this.scrollOffset - this.#scrollPaddingStart());
+        const viewportEnd = scrollTop + Math.max(0, this.#containerHeight());
+        const visibleStartIndex = this.#startIndex(offsets, scrollTop);
+        const visibleEndIndex = Math.max(visibleStartIndex + 1, this.#endIndex(offsets, viewportEnd));
+        const startIndex = Math.max(0, visibleStartIndex - overscan);
+        const endIndex = Math.min(count, visibleEndIndex + overscan);
+        return Array.from({ length: endIndex - startIndex }, (_, offset) => {
+            const index = startIndex + offset;
+            return this.#virtualItemAt(index, offsets);
+        });
+    }
+}

package/src/components/chat/conversation-model.ts

@@ -0,0 +1,44 @@
+/**
+ * Conversationalist data model types for the Chat component.
+ *
+ * Chat renders immutable transcript snapshots and keeps its public `conversation`
+ * prop aligned with the published `conversationalist` package. This file is a
+ * type-only bridge so Cinder does not maintain a stale structural mirror.
+ *
+ * @module
+ */
+
+import type { ToMarkdownOptions as ConversationalistToMarkdownOptions } from 'conversationalist/markdown';
+
+export type {
+  AssistantMessage,
+  ContainerUploadContent,
+  ConversationHistory,
+  ConversationStatus,
+  ImageContent,
+  JSONValue,
+  Message,
+  MessageInput,
+  MessageRole,
+  MultiModalContent,
+  RedactedThinkingContent,
+  ServerToolResultContent,
+  ServerToolResultType,
+  ServerToolUseContent,
+  TextContent,
+  ThinkingContent,
+  TokenUsage,
+  ToolAction,
+  ToolCall,
+  ToolError,
+  ToolErrorCategory,
+  ToolResult,
+  WebSearchToolResultContent,
+} from 'conversationalist';
+export type { ToolCallPair } from 'conversationalist/utilities';
+
+/** Base options shared by all transcript export operations. */
+export type ExportOptions = Omit<ConversationalistToMarkdownOptions, 'includeMetadata'>;
+
+/** Options for exporting a transcript to markdown. */
+export type ToMarkdownOptions = ConversationalistToMarkdownOptions;

package/src/components/chat/export/conversation-export-actions.svelte

@@ -0,0 +1,174 @@
+<script lang="ts" module>
+export {};
+</script>
+
+<script lang="ts">
+import { classNames } from '../../../utilities/class-names.ts';
+import { stringifyOrNull } from '../../../utilities/stringify.ts';
+import { createCopyState } from '../../copy-button/use-copy-state.svelte.ts';
+import Dropdown from '../../dropdown/dropdown.svelte';
+import DropdownItem from '../../dropdown-item/dropdown-item.svelte';
+import DropdownMenu from '../../dropdown-menu/dropdown-menu.svelte';
+import DropdownTrigger from '../../dropdown-trigger/dropdown-trigger.svelte';
+import Check from 'lucide-svelte/icons/check';
+import Copy from 'lucide-svelte/icons/copy';
+import FileCode from 'lucide-svelte/icons/file-code';
+import FileText from 'lucide-svelte/icons/file-text';
+import { getMessages, messagesToMarkdown } from '../utilities';
+let { id, conversation, onexported, onexportfailed, class: className, } = $props();
+const copyState = createCopyState();
+/**
+ * Exports the conversation as Markdown.
+ * Uses the browser-compatible messagesToMarkdown helper (no Node.js APIs).
+ */
+async function handleExportMarkdown() {
+    const messages = getMessages(conversation, { includeHidden: false });
+    const markdown = messagesToMarkdown(messages);
+    const succeeded = await copyState.trigger('markdown', markdown);
+    if (succeeded) {
+        onexported?.('markdown');
+    }
+    else {
+        onexportfailed?.('markdown', 'Clipboard access denied. Please copy manually.');
+    }
+}
+/**
+ * Exports the conversation as JSON.
+ * Includes schema version and strips transient metadata.
+ */
+async function handleExportJSON() {
+    // Get messages without hidden ones, strip transient metadata
+    const messages = getMessages(conversation, { includeHidden: false });
+    const cleanedMessages = messages.map((message) => {
+        // Strip transient metadata (keys starting with _) from message metadata
+        if (message.metadata) {
+            const cleanedMetadata = {};
+            for (const [key, value] of Object.entries(message.metadata)) {
+                if (!key.startsWith('_')) {
+                    cleanedMetadata[key] = value;
+                }
+            }
+            return {
+                ...message,
+                metadata: Object.keys(cleanedMetadata).length > 0 ? cleanedMetadata : undefined,
+            };
+        }
+        return message;
+    });
+    const exportData = {
+        schemaVersion: '1.0',
+        exportedAt: new Date().toISOString(),
+        conversationId: conversation.id,
+        messages: cleanedMessages,
+    };
+    // Guard against circular references or other JSON serialization failures
+    const json = stringifyOrNull(exportData);
+    if (json === null) {
+        onexportfailed?.('json', 'Failed to serialize conversation data');
+        return;
+    }
+    const succeeded = await copyState.trigger('json', json);
+    if (succeeded) {
+        onexported?.('json');
+    }
+    else {
+        onexportfailed?.('json', 'Clipboard access denied. Please copy manually.');
+    }
+}
+const formatLabels = {
+    markdown: 'Markdown',
+    json: 'JSON',
+};
+</script>
+
+<div class={classNames('conversation-export-actions', className)}>
+  <!-- Screen reader announcement for copy success -->
+  <div class="sr-only" aria-live="polite" aria-atomic="true">
+    {#if copyState.copiedKey}
+      Copied as {formatLabels[copyState.copiedKey]}
+    {/if}
+  </div>
+
+  <Dropdown {id}>
+    <DropdownTrigger class="export-trigger" aria-label="Export conversation" showCaret={false}>
+      <Copy class="cinder-icon-sm" />
+    </DropdownTrigger>
+    <DropdownMenu>
+      <!-- Markdown export -->
+      <DropdownItem onclick={handleExportMarkdown}>
+        {#if copyState.copiedKey === 'markdown'}
+          <Check class="cinder-icon-sm export-icon-success" />
+        {:else}
+          <FileText class="cinder-icon-sm" />
+        {/if}
+        <span>Copy as {formatLabels.markdown}</span>
+        {#if copyState.copiedKey === 'markdown'}
+          <span class="copied-label">Copied!</span>
+        {/if}
+      </DropdownItem>
+
+      <!-- JSON export -->
+      <DropdownItem onclick={handleExportJSON}>
+        {#if copyState.copiedKey === 'json'}
+          <Check class="cinder-icon-sm export-icon-success" />
+        {:else}
+          <FileCode class="cinder-icon-sm" />
+        {/if}
+        <span>Copy as {formatLabels.json}</span>
+        {#if copyState.copiedKey === 'json'}
+          <span class="copied-label">Copied!</span>
+        {/if}
+      </DropdownItem>
+    </DropdownMenu>
+  </Dropdown>
+</div>
+
+<style>
+  .conversation-export-actions {
+    display: flex;
+    align-items: center;
+  }
+
+  /* Style the DropdownTrigger button as icon-only */
+  .conversation-export-actions :global(.export-trigger) {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    padding: var(--cinder-space-1-5);
+    color: var(--cinder-text-muted);
+    background: transparent;
+    border: none;
+    border-radius: var(--cinder-radius-sm);
+    cursor: pointer;
+    transition: background-color var(--cinder-duration-fast) var(--cinder-ease-standard);
+  }
+
+  @media (hover: hover) {
+    .conversation-export-actions :global(.export-trigger:hover) {
+      background: var(--cinder-surface-hover);
+    }
+  }
+
+  .conversation-export-actions :global(.export-trigger:focus-visible) {
+    outline: var(--cinder-ring-width) solid transparent;
+    box-shadow: var(--_cinder-focus-ring-shadow);
+  }
+
+  @media (forced-colors: active) {
+    .conversation-export-actions :global(.export-trigger:focus-visible) {
+      outline: var(--cinder-ring-width) solid ButtonText;
+      outline-offset: 3px;
+    }
+  }
+
+  .export-icon-success {
+    color: var(--cinder-success);
+  }
+
+  .copied-label {
+    margin-inline-start: auto;
+    font-size: var(--cinder-text-xs);
+    color: var(--cinder-success);
+    font-weight: var(--cinder-font-medium);
+  }
+</style>

package/src/components/chat/export/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Chat export components.
+ *
+ * DEP-55: Copy/export actions for chat messages and conversations.
+ *
+ * @module
+ */
+
+export { default as ConversationExportActions } from './conversation-export-actions.svelte';