@lostgradient/cinder 0.2.0 → 0.4.0

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

@@ -40,7 +40,7 @@ export interface UseChatUnreadStateReturn {
   /** Current count of unread messages */
   readonly unreadCount: number;
   /** Whether the new message indicator should be visible */
-  readonly hasNewMessageIndicator: boolean;
+  readonly newMessageIndicatorVisible: boolean;
   /** ID of the first unread message (for divider placement) */
   readonly firstUnreadId: string | null;
   /** Formatted unread count for display (caps at "99+") */
@@ -55,10 +55,10 @@ export interface UseChatUnreadStateReturn {
    * Process messages to detect new arrivals and update unread state.
    * Should be called in an $effect when messages change.
    *
-   * @param getIsAtBottom - Getter function to read isAtBottom without creating a dependency.
-   *                        This allows the effect to only re-run when messages change, not on scroll.
+   * @param getAtBottom - Getter function to read atBottom without creating a dependency.
+   *                      This allows the effect to only re-run when messages change, not on scroll.
    */
-  processMessages(messages: Message[], conversationId: string, getIsAtBottom: () => boolean): void;
+  processMessages(messages: Message[], conversationId: string, getAtBottom: () => boolean): void;
   /** Cleanup resources */
   destroy(): void;
 }
@@ -80,9 +80,9 @@ export interface UseChatUnreadStateReturn {
  *   });
  *
  *   // Call in an $effect to process message changes
- *   // Pass a getter function for isAtBottom to avoid creating a scroll dependency
+ *   // Pass a getter function for atBottom to avoid creating a scroll dependency
  *   $effect(() => {
- *     unreadState.processMessages(messages, conversation.id, () => scrollState.isAtBottom);
+ *     unreadState.processMessages(messages, conversation.id, () => scrollState.atBottom);
  *   });
  *
  *   // Mark as read when user scrolls to bottom
@@ -99,7 +99,7 @@ export function useChatUnreadState(options?: UseChatUnreadStateOptions): UseChat
 
   // Internal reactive state
   let unreadCount = $state(0);
-  let hasNewMessageIndicator = $state(false);
+  let newMessageIndicatorVisible = $state(false);
   let firstUnreadId = $state<string | null>(null);
 
   // Non-reactive bookkeeping (prevents $effect infinite loops)
@@ -116,16 +116,16 @@ export function useChatUnreadState(options?: UseChatUnreadStateOptions): UseChat
 
   /**
    * Fire the indicator-change callback from the mutation sites that actually
-   * change `unreadCount` / `hasNewMessageIndicator`. Driving it here (rather
+   * change `unreadCount` / `newMessageIndicatorVisible`. Driving it here (rather
    * than from an `$effect`) avoids the spurious `{ unreadCount: 0,
-   * hasNewMessageIndicator: false }` notification that an effect would emit on
+   * 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(): void {
     onUnreadIndicatorChange?.({
       unreadCount,
-      hasNewMessageIndicator,
+      newMessageIndicatorVisible,
     });
   }
 
@@ -133,9 +133,9 @@ export function useChatUnreadState(options?: UseChatUnreadStateOptions): UseChat
    * Mark all messages as read (resets unread state).
    */
   function markAllAsRead(): void {
-    const changed = unreadCount !== 0 || hasNewMessageIndicator;
+    const changed = unreadCount !== 0 || newMessageIndicatorVisible;
     unreadCount = 0;
-    hasNewMessageIndicator = false;
+    newMessageIndicatorVisible = false;
     firstUnreadId = null;
     if (changed) notifyIndicatorChange();
   }
@@ -144,12 +144,12 @@ export function useChatUnreadState(options?: UseChatUnreadStateOptions): UseChat
    * Process messages to detect new arrivals and update unread state.
    * This should be called from an $effect in the parent component.
    *
-   * @param getIsAtBottom - Getter function to read isAtBottom without creating a dependency.
+   * @param getAtBottom - Getter function to read atBottom without creating a dependency.
    */
   function processMessages(
     messages: Message[],
     conversationId: string,
-    getIsAtBottom: () => boolean,
+    getAtBottom: () => boolean,
   ): void {
     // Check if conversation has changed - reset tracking if so
     if (conversationId !== previousConversationId) {
@@ -177,15 +177,15 @@ export function useChatUnreadState(options?: UseChatUnreadStateOptions): UseChat
 
     if (wasAppended) {
       // New messages arrived at the end
-      // Read isAtBottom via getter to avoid creating a reactive dependency
+      // Read atBottom via getter to avoid creating a reactive dependency
       // The getter is called inside untrack to ensure no dependency tracking
-      const atBottom = untrack(getIsAtBottom);
+      const atBottom = untrack(getAtBottom);
 
       if (!atBottom) {
         // User is reading history - show indicator
         const newMessageCount = currentCount - prevCount;
         unreadCount += newMessageCount;
-        hasNewMessageIndicator = true;
+        newMessageIndicatorVisible = true;
 
         // Set first unread ID if not already set
         // The first new message is at index (currentCount - newMessageCount)
@@ -225,8 +225,8 @@ export function useChatUnreadState(options?: UseChatUnreadStateOptions): UseChat
     get unreadCount() {
       return unreadCount;
     },
-    get hasNewMessageIndicator() {
-      return hasNewMessageIndicator;
+    get newMessageIndicatorVisible() {
+      return newMessageIndicatorVisible;
     },
     get firstUnreadId() {
       return firstUnreadId;

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

@@ -0,0 +1,328 @@
+import type { Attachment } from 'svelte/attachments';
+import type { VirtualItem } from '../../../_internal/virtual-item.ts';
+
+type ChatScrollBehavior = ScrollBehavior | 'instant';
+
+type ChatScrollToOptions = {
+  align?: 'auto' | 'start' | 'center' | 'end';
+  behavior?: ChatScrollBehavior;
+};
+
+export type ChatVirtualizerOptions = {
+  getScrollElement: () => HTMLElement | null;
+  getCount: () => number;
+  getItemKey: (index: number) => string | number;
+  getEstimatedSize: () => number;
+  getOverscan: () => number;
+  getInitialHeight: () => number;
+  getScrollPaddingStart?: () => number;
+};
+
+export type ChatVirtualWindowInput = {
+  scrollTop: number;
+  containerHeight: number;
+  itemCount: number;
+  itemSize: number;
+  overscan: number;
+};
+
+export type ChatVirtualWindow = {
+  startIndex: number;
+  endIndex: number;
+};
+
+export function calculateChatVirtualWindow(input: ChatVirtualWindowInput): ChatVirtualWindow {
+  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 {
+  #scrollElement: HTMLElement | null = null;
+  #scrollOffset = $state(0);
+  #measurementVersion = $state(0);
+  #offsetsCache: number[] | null = null;
+  #offsetsCacheCount = -1;
+  #offsetsCacheMeasurementVersion = -1;
+  #measuredSizes = new Map<string | number, number>();
+
+  constructor(readonly options: ChatVirtualizerOptions) {}
+
+  get virtualItems(): VirtualItem[] {
+    return this.#virtualItems();
+  }
+
+  get totalSize(): number {
+    const offsets = this.#offsets();
+    return offsets[offsets.length - 1] ?? 0;
+  }
+
+  get scrollPaddingStart(): number {
+    return this.#scrollPaddingStart();
+  }
+
+  get scrollSize(): number {
+    return this.scrollPaddingStart + this.totalSize;
+  }
+
+  get scrollOffset(): number {
+    return this.#scrollOffset;
+  }
+
+  setScrollElement(element: HTMLElement | null): void {
+    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: Attachment<HTMLElement> = (node) => {
+    this.setScrollElement(node);
+
+    return () => {
+      if (this.#scrollElement === node) {
+        this.setScrollElement(null);
+      }
+    };
+  };
+
+  measureElement: Attachment<HTMLElement> = (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: HTMLElement | null): void {
+    if (!node) return;
+
+    this.#measureNode(node);
+  }
+
+  syncOptions(): void {
+    const count = this.options.getCount();
+    const currentKeys = new Set<string | number>();
+    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: number, options: ChatScrollToOptions = { align: 'auto' }): void {
+    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: number): VirtualItem | null {
+    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: number, options?: ChatScrollToOptions): void {
+    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 = (): void => {
+    this.#scrollOffset = this.#scrollElement?.scrollTop ?? 0;
+  };
+
+  #getScrollElement(): HTMLElement | null {
+    return this.#scrollElement ?? this.options.getScrollElement();
+  }
+
+  #containerHeight(): number {
+    const element = this.#getScrollElement();
+    return element?.clientHeight || this.options.getInitialHeight();
+  }
+
+  #scrollPaddingStart(): number {
+    return Math.max(0, this.options.getScrollPaddingStart?.() ?? 0);
+  }
+
+  #estimatedSize(): number {
+    return Math.max(1, this.options.getEstimatedSize());
+  }
+
+  #itemSize(index: number): number {
+    const key = this.options.getItemKey(index);
+    return this.#measuredSizes.get(key) ?? this.#estimatedSize();
+  }
+
+  #offsets(): number[] {
+    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<number>({ 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: HTMLElement): number {
+    const rectHeight = node.getBoundingClientRect().height;
+    return Math.ceil(rectHeight || node.scrollHeight || node.offsetHeight || 0);
+  }
+
+  #measureNode(node: HTMLElement): void {
+    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: readonly number[], scrollTop: number): number {
+    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: readonly number[], viewportEnd: number): number {
+    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: number, offsets: readonly number[]): VirtualItem {
+    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(): VirtualItem[] {
+    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/index.ts

@@ -12,9 +12,18 @@
 import Chat from './chat.svelte';
 
 export default Chat;
-export type { ChatProps } from './chat.types.ts';
+export type { ChatCapabilities, ChatProps, ReadReceipt, TypingParticipant } from './chat.types.ts';
 export { Chat };
 
+// Adapter seam — the optional event/transport boundary around <Chat>. Type-only.
+export type {
+  ChatAdapter,
+  ChatAdapterErrorEvent,
+  ChatCommand,
+  ChatPushHandlers,
+  ChatReadReceiptEvent,
+} from './adapter';
+
 // Conversation builders — an ergonomic, immutable way to construct the
 // ConversationHistory Chat renders, for apps without their own conversation state.
 export {

package/src/components/chat/input/chat-input.svelte

@@ -14,12 +14,14 @@
     value?: string;
     /** Placeholder text */
     placeholder?: string;
+    /** Accessible label passed to the inner message editor */
+    composerLabel?: string;
     /** Whether the input is disabled */
     disabled?: boolean;
     /** Whether a submission is in progress */
     sending?: boolean;
     /** Error message to display */
-    error?: string | undefined;
+    error?: string;
     /** Additional CSS class */
     class?: string;
 
@@ -105,6 +107,7 @@
     id,
     value = $bindable(''),
     placeholder = 'Type a message...',
+    composerLabel = 'Message',
     disabled = false,
     sending = false,
     error,
@@ -497,6 +500,7 @@
       bind:value
       bind:this={editorRef}
       {placeholder}
+      label={composerLabel}
       readonly={disabled || sending}
       showToolbar={false}
       showModeToggle={false}
@@ -533,12 +537,18 @@
       {/if}
 
       <!-- Visually hidden shortcut description: always in the accessibility tree even when hint is container-queried away -->
-      <span id={shortcutDescriptionId} class="sr-only"
-        >Press Enter to send, Shift+Enter for newline</span
-      >
-      <span id={hintId} class="chat-input-hint" aria-hidden="true">
-        <kbd>Enter</kbd> to send, <kbd>Shift</kbd>+<kbd>Enter</kbd> for newline
+      <span id={shortcutDescriptionId} class="sr-only">
+        {#if showStopButton}
+          Response is streaming. Use the stop button to stop generation.
+        {:else}
+          Press Enter to send, Shift+Enter for newline
+        {/if}
       </span>
+      {#if !showStopButton}
+        <span id={hintId} class="chat-input-hint" aria-hidden="true">
+          <kbd>Enter</kbd> to send, <kbd>Shift</kbd>+<kbd>Enter</kbd> for newline
+        </span>
+      {/if}
     </div>
 
     <div class="chat-input-footer-right">
@@ -554,6 +564,7 @@
           data-stop
           onclick={onstop}
           aria-label="Stop generating"
+          aria-describedby={shortcutDescriptionId}
         >
           <Square class="icon-sm" />
         </button>
@@ -706,12 +717,10 @@
   }
 
   /* The button is a 44px touch target but the visible chip is the centered
-     1.25rem `::before` circle. Reserve a transparent outline placeholder for
-     forced-colors, and paint the ring on the visible circle (Strategy B-inset)
-     so it hugs the chip rather than the oversized hit area. */
+     1.25rem `::before` circle. Paint the ring on the visible circle so it hugs
+     the chip rather than the oversized hit area. */
   .chat-input-attachment-remove:focus-visible {
     opacity: 1;
-    outline: var(--cinder-ring-width) solid transparent;
   }
 
   .chat-input-attachment-remove:focus-visible::before {
@@ -720,9 +729,14 @@
   }
 
   @media (forced-colors: active) {
-    .chat-input-attachment-remove:focus-visible {
+    /* Forced-colors strips the box-shadow ring, so repaint a system-color
+       outline directly on the visible `::before` circle (which is round via
+       border-radius: full, so the outline follows the chip). Painting on the
+       circle itself avoids depending on fragile parent-to-pseudo offset math. */
+    .chat-input-attachment-remove:focus-visible::before {
+      box-shadow: none;
       outline: var(--cinder-ring-width) solid ButtonText;
-      outline-offset: -12px;
+      outline-offset: var(--cinder-ring-offset);
     }
   }
 
@@ -753,6 +767,13 @@
     border-radius: 0;
   }
 
+  .chat-input-editor-container :global(textarea.markdown-editor),
+  .chat-input-editor-container :global(.ProseMirror) {
+    field-sizing: content;
+    max-height: 12rem;
+    overflow-y: auto;
+  }
+
   .chat-input-editor-container :global(.markdown-editor:focus-within) {
     border-color: transparent;
     box-shadow: none;
@@ -855,6 +876,7 @@
 
   .chat-input-send:focus-visible {
     outline: var(--cinder-ring-width) solid transparent;
+    outline-offset: 3px;
     box-shadow: var(--_cinder-focus-ring-shadow);
   }
 
@@ -874,7 +896,7 @@
 
   @media (forced-colors: active) {
     .chat-input-send:focus-visible {
-      outline: var(--cinder-ring-width) solid ButtonText;
+      outline: var(--cinder-ring-width) solid Highlight;
       outline-offset: 3px;
     }
   }