@lostgradient/cinder 0.3.0 → 0.4.0

package/src/components/chat/container/chat-events.ts

@@ -14,7 +14,7 @@ export type ChatStopGeneratingEvent = {
 
 /** Event fired when scroll state changes. */
 export type ChatScrollStateChangeEvent = {
-  isAtBottom: boolean;
+  atBottom: boolean;
   scrollTop: number;
   scrollHeight: number;
 };
@@ -22,5 +22,5 @@ export type ChatScrollStateChangeEvent = {
 /** Event fired when unread indicator state changes. */
 export type ChatUnreadIndicatorChangeEvent = {
   unreadCount: number;
-  hasNewMessageIndicator: boolean;
+  newMessageIndicatorVisible: boolean;
 };

package/src/components/chat/container/chat-history-trigger.svelte

@@ -33,7 +33,7 @@
     };
   };
 
-  export function focus(options?: FocusOptions): void {
+  export function focus(options: FocusOptions | undefined = undefined): void {
     buttonElement?.focus(options);
   }
 </script>
@@ -93,6 +93,14 @@
     box-shadow: var(--_cinder-focus-ring-shadow);
   }
 
+  @media (forced-colors: active) {
+    .chat-history-trigger-button:focus-visible {
+      outline: var(--cinder-ring-width) solid ButtonText;
+      outline-offset: 3px;
+      box-shadow: none;
+    }
+  }
+
   .sr-only {
     position: absolute;
     width: 1px;

package/src/components/chat/container/chat.svelte

@@ -19,7 +19,7 @@
 </script>
 
 <script lang="ts">
-  import { onMount, tick, untrack } from 'svelte';
+  import { tick, untrack } from 'svelte';
   import { classNames } from '../../../utilities/class-names.ts';
   import {
     getMessages,
@@ -71,29 +71,25 @@
   let {
     id,
     conversation,
-    isAtBottom = $bindable(true),
+    atBottom = $bindable(true),
     unreadCount = $bindable(0),
-    hasNewMessageIndicator = $bindable(false),
+    newMessageIndicatorVisible = $bindable(false),
     class: className,
     surfaceMode = 'default',
     density = 'comfortable',
     variant = 'bubble',
     bottomThreshold = DEFAULT_SCROLL_CONFIGURATION.bottomThreshold,
     jumpThreshold = DEFAULT_SCROLL_CONFIGURATION.jumpThreshold,
-    isStreaming = false,
+    streaming = false,
     streamingStatus,
-    allowAttachments = true,
-    allowSearch = true,
+    capabilities,
     virtualized = false,
     virtualizationEstimatedRowHeight = 88,
     virtualizationOverscan = 3,
     virtualizationInitialHeight = 640,
-    hasMoreHistory = true,
+    moreHistoryAvailable = true,
     loadEarlierLabel = 'Load earlier messages',
     loadingEarlierLabel = 'Loading earlier messages',
-    allowCopy = true,
-    allowEditing = true,
-    allowRetry = true,
     header,
     empty,
     emptyPrompts,
@@ -220,14 +216,23 @@
     getJumpThreshold: () => jumpThreshold,
     onScrollStateChange: handleScrollStateChange,
     onReachBottom: () => {
-      if (unreadState.unreadCount > 0 || unreadState.hasNewMessageIndicator) {
+      // The sentinel fires when the user reaches the bottom via
+      // IntersectionObserver, which does not emit onScrollStateChange.
+      // Update the bindable prop here so it stays in sync with the sentinel path.
+      atBottom = true;
+      if (unreadState.unreadCount > 0 || unreadState.newMessageIndicatorVisible) {
         unreadState.markAllAsRead();
       }
     },
   });
 
   const unreadState = useChatUnreadState({
-    onUnreadIndicatorChange: (event) => onunreadindicatorchange?.(event),
+    onUnreadIndicatorChange: (event) => {
+      // Update the bindable props at the mutation site rather than via a $effect.
+      unreadCount = event.unreadCount;
+      newMessageIndicatorVisible = event.newMessageIndicatorVisible;
+      onunreadindicatorchange?.(event);
+    },
   });
 
   const keyboardNav = useChatKeyboardNav({
@@ -254,7 +259,14 @@
   // does not tear down and reopen the real-time subscription each render.
   const conversationId = $derived(conversation.id);
 
-  const showTypingIndicator = $derived(isStreaming && !streamingMessageId);
+  const showTypingIndicator = $derived(streaming && !streamingMessageId);
+
+  // Expand capabilities object with per-feature defaults.
+  const allowAttachments = $derived(capabilities?.attachments ?? true);
+  const allowSearch = $derived(capabilities?.search ?? true);
+  const allowCopy = $derived(capabilities?.copy ?? true);
+  const allowEditing = $derived(capabilities?.editing ?? true);
+  const allowRetry = $derived(capabilities?.retry ?? true);
   const toolCallPairsByCallId = $derived.by(() => {
     const toolCallPairs = pairToolCallsWithResults(messages);
     const map = new Map<string, ReturnType<typeof pairToolCallsWithResults>>();
@@ -277,7 +289,7 @@
     });
   });
   let hasMounted = $state(false);
-  onMount(() => {
+  $effect(() => {
     hasMounted = true;
   });
 
@@ -382,7 +394,7 @@
   // ==========================================================================
 
   const viewportAttach = $derived(viewportAttachment ?? noopAttachment);
-  const effectiveHasMoreHistory = $derived(adapterHasMoreHistory ?? hasMoreHistory);
+  const effectiveHasMoreHistory = $derived(adapterHasMoreHistory ?? moreHistoryAvailable);
   const hasHistoryLoader = $derived(
     onloadhistory !== undefined || adapter?.loadOlderMessages !== undefined,
   );
@@ -467,25 +479,6 @@
     return '';
   });
 
-  // ==========================================================================
-  // Sync Bindable Props with Helper State
-  // ==========================================================================
-
-  // Sync isAtBottom from scrollState to bindable prop
-  $effect(() => {
-    isAtBottom = scrollState.isAtBottom;
-  });
-
-  // Sync unreadCount from unreadState to bindable prop
-  $effect(() => {
-    unreadCount = unreadState.unreadCount;
-  });
-
-  // Sync hasNewMessageIndicator from unreadState to bindable prop
-  $effect(() => {
-    hasNewMessageIndicator = unreadState.hasNewMessageIndicator;
-  });
-
   // ==========================================================================
   // Scroll Anchoring via $effect.pre
   // ==========================================================================
@@ -509,8 +502,8 @@
     const currentScrollExtent = isVirtualized ? chatVirtualizer.scrollSize : viewport.scrollHeight;
     void currentScrollExtent;
 
-    // Read isAtBottom without making it a dependency (prevents loops)
-    const atBottom = untrack(() => scrollState.isAtBottom);
+    // Read atBottom without making it a dependency (prevents loops)
+    const atBottom = untrack(() => scrollState.atBottom);
 
     // Skip if user initiated a smooth scroll (e.g., via jump button)
     if (scrollState.isUserScrolling) return undefined;
@@ -643,12 +636,15 @@
   }
 
   function handleScrollStateChange(event: {
-    isAtBottom: boolean;
+    atBottom: boolean;
     scrollTop: number;
     scrollHeight: number;
   }): void {
     clearHistoryAnchorAfterScroll(event.scrollTop);
 
+    // Update the bindable prop at the mutation site rather than via a $effect.
+    atBottom = event.atBottom;
+
     onscrollstatechange?.(event);
   }
 
@@ -694,9 +690,9 @@
   // ==========================================================================
 
   $effect(() => {
-    // Pass a getter function for isAtBottom to avoid creating a scroll dependency.
+    // Pass a getter function for scrollState.atBottom to avoid creating a scroll dependency.
     // The effect should only re-run when messages change, not on every scroll.
-    unreadState.processMessages(messages, conversation.id, () => scrollState.isAtBottom);
+    unreadState.processMessages(messages, conversation.id, () => scrollState.atBottom);
   });
 
   // ==========================================================================
@@ -872,8 +868,13 @@
       () => onsubmit?.({ message, attachments }),
     );
 
-    // Auto-scroll after sending
-    scrollState.setIsAtBottom(true);
+    // Auto-scroll after sending.
+    // Also update the bindable prop so the parent binding reflects the new
+    // atBottom=true state immediately — scrollState.setAtBottom() only
+    // updates the internal helper state; the bindable must be written explicitly
+    // (matching the pattern in handleScrollStateChange and onReachBottom).
+    scrollState.setAtBottom(true);
+    atBottom = true;
     tick().then(() => {
       if (isVirtualized) {
         chatVirtualizer.scrollToOffset(chatVirtualizer.scrollSize, { behavior: 'instant' });
@@ -1394,7 +1395,7 @@
           });
         }
         // Auto-scroll if at bottom
-        if (scrollState.isAtBottom && viewport) {
+        if (scrollState.atBottom && viewport) {
           if (isVirtualized) {
             chatVirtualizer.scrollToOffset(chatVirtualizer.scrollSize, { behavior: 'instant' });
           } else {
@@ -1683,7 +1684,7 @@
   <div class="chat-input-wrapper">
     <ChatJumpControls
       showJumpButton={scrollState.showJumpButton}
-      hasNewMessageIndicator={unreadState.hasNewMessageIndicator}
+      hasNewMessageIndicator={unreadState.newMessageIndicatorVisible}
       unreadCount={unreadState.unreadCount}
       displayUnreadCount={unreadState.displayUnreadCount}
       hasLargeCount={unreadState.hasLargeCount}
@@ -1696,10 +1697,10 @@
         id={inputId}
         bind:this={inputRef}
         onsubmit={(message, attachments) => handleSubmit(message, attachments)}
-        disabled={isStreaming}
-        sending={isStreaming}
+        disabled={streaming}
+        sending={streaming}
         {allowAttachments}
-        onstop={isStreaming ? handleStopGenerating : undefined}
+        onstop={streaming ? handleStopGenerating : undefined}
         {onattachmentadd}
         {onattachmentremove}
         {onattachmentfailure}

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

@@ -2,7 +2,7 @@
  * Runes helper for chat scroll state management.
  *
  * Manages:
- * - isAtBottom state for auto-scroll decisions
+ * - atBottom state for auto-scroll decisions
  * - showJumpButton state for jump-to-latest visibility
  * - Scroll event listener attachment
  * - IntersectionObserver for bottom sentinel
@@ -60,13 +60,13 @@ export interface UseChatScrollStateOptions {
 /** Return type for the scroll state helper */
 export interface UseChatScrollStateReturn {
   /** Whether the viewport is at or near the bottom */
-  readonly isAtBottom: boolean;
+  readonly atBottom: boolean;
   /** Whether the jump-to-latest button should be visible */
   readonly showJumpButton: boolean;
   /** Whether user is in a smooth scroll animation (used by parent for auto-scroll logic) */
   readonly isUserScrolling: boolean;
-  /** Set isAtBottom state directly */
-  setIsAtBottom(value: boolean): void;
+  /** Set atBottom state directly */
+  setAtBottom(value: boolean): void;
   /** Create a scroll event listener attachment for the viewport */
   createScrollAttachment(): Attachment<HTMLElement>;
   /**
@@ -167,7 +167,7 @@ export function useChatScrollState(options?: UseChatScrollStateOptions): UseChat
   }
 
   // Reactive state
-  let isAtBottom = $state(true);
+  let atBottom = $state(true);
   let showJumpButton = $state(false);
 
   // Non-reactive bookkeeping
@@ -175,10 +175,10 @@ export function useChatScrollState(options?: UseChatScrollStateOptions): UseChat
   let isUserScrolling = false; // Prevents auto-scroll from interrupting user-initiated smooth scroll
 
   /**
-   * Set isAtBottom state directly.
+   * Set atBottom state directly.
    */
-  function setIsAtBottom(value: boolean): void {
-    isAtBottom = value;
+  function setAtBottom(value: boolean): void {
+    atBottom = value;
   }
 
   /**
@@ -197,24 +197,27 @@ export function useChatScrollState(options?: UseChatScrollStateOptions): UseChat
             clientHeight: element.clientHeight,
           };
 
-          const atBottom = checkIsAtBottom(state, getBottomThreshold?.() ?? bottomThreshold);
+          const scrolledToBottom = checkIsAtBottom(
+            state,
+            getBottomThreshold?.() ?? bottomThreshold,
+          );
           const shouldShowJump = shouldShowJumpToLatest(
             state,
             getJumpThreshold?.() ?? jumpThreshold,
           );
 
           // Update reactive state
-          isAtBottom = atBottom;
+          atBottom = scrolledToBottom;
           showJumpButton = shouldShowJump;
 
           // Clear unread when scrolled to bottom
-          if (atBottom) {
+          if (scrolledToBottom) {
             onReachBottom?.();
           }
 
           // Emit scroll state change
           onScrollStateChange?.({
-            isAtBottom: atBottom,
+            atBottom: scrolledToBottom,
             scrollTop: state.scrollTop,
             scrollHeight: state.scrollHeight,
           });
@@ -233,9 +236,9 @@ export function useChatScrollState(options?: UseChatScrollStateOptions): UseChat
    * Exposed for use with useIntersection attachment-based wiring.
    */
   function handleSentinelEntry(entry: IntersectionObserverEntry): void {
-    const atBottom = entry.isIntersecting;
-    if (atBottom && !isAtBottom) {
-      isAtBottom = true;
+    const sentinelVisible = entry.isIntersecting;
+    if (sentinelVisible && !atBottom) {
+      atBottom = true;
       onReachBottom?.();
     }
   }
@@ -308,13 +311,13 @@ export function useChatScrollState(options?: UseChatScrollStateOptions): UseChat
   }
 
   return {
-    get isAtBottom() {
-      return isAtBottom;
+    get atBottom() {
+      return atBottom;
     },
     get showJumpButton() {
       return showJumpButton;
     },
-    setIsAtBottom,
+    setAtBottom,
     createScrollAttachment,
     createSentinelObserver,
     handleSentinelEntry,

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/index.ts

@@ -12,7 +12,7 @@
 import Chat from './chat.svelte';
 
 export default Chat;
-export type { ChatProps, ReadReceipt, TypingParticipant } 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.

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