## Overview [#overview]

Cubitt's chat system ships three explicit layout variants — **Floating**, **Sidebar**, and **Fullscreen** — each composed from shared primitives. The library is data-layer agnostic — you own querying, streaming, and persistence. Cubitt renders whatever normalized rows you feed it.

* Each variant is its own compound component (`Chat.Floating`, `Chat.Sidebar`, `Chat.Fullscreen`).
* Message output is chunk-based — agent responses are rendered as a sequence of typed `ChunkRow` objects.
* A per-instance chunk registry lets you extend the system with custom renderers.
* Mode transitions are consumer-controlled — swap variants using your own state.

## Pick a Variant [#pick-a-variant]

|              | Floating                                 | Sidebar                                                 | Fullscreen                                   |
| ------------ | ---------------------------------------- | ------------------------------------------------------- | -------------------------------------------- |
| **Use case** | Floating helper, quick questions         | Persistent side panel                                   | Dedicated chat page                          |
| **Layout**   | Fixed bottom-center, animated            | Fixed right panel, full height                          | Full viewport with resizable panels          |
| **Chrome**   | Engagement-driven reveal                 | Always visible                                          | Always visible + nav sidebar                 |
| **Prompt**   | Engagement-driven expansion              | Always expanded                                         | Always expanded                              |
| **Panels**   | Sheet overlay                            | Sheet overlay                                           | Resizable side panels                        |
| **Example**  | [Floating Chat](/examples/chat/floating) | [Floating Chat](/examples/chat/floating) (click expand) | [Fullscreen Chat](/examples/chat/fullscreen) |

## Quick Start [#quick-start]

Minimal floating chat (example uses TanStack DB, but any data layer works):

```tsx
import {
  Chat,
  useChatSelection,
  MessageFeedScrollAnchor,
} from "@tilt-legal/cubitt-components/composites";
import { useLiveQuery } from "@tanstack/react-db";

function MyFloatingChat({ messagesCollection, chunksCollection, onModeChange }) {
  const { conversationId, handleNew, handleSelect } = useChatSelection();

  const { data: messages = [] } = useLiveQuery((q) =>
    q
      .from({ m: messagesCollection })
      .where(({ m }) => m.conversationId === conversationId)
      .orderBy(({ m }) => m.createdAt, "asc")
      .select(({ m }) => m),
  );

  const isStreaming = messages.some((msg) => msg.status === "running");

  return (
    <Chat.Floating
      conversationId={conversationId}
      hasMessages={messages.length > 0}
      isStreaming={isStreaming}
      onCancelStreaming={() => {
        /* cancel your stream */
      }}
      onNewConversation={handleNew}
      onSend={(payload) => {
        /* write to DB, start stream */
      }}
    >
      <Chat.Floating.Shell>
        <Chat.Floating.Header
          conversations={history}
          onConversationSelect={handleSelect}
          onNewConversation={handleNew}
          onModeChange={onModeChange}
        />
        <Chat.Floating.Content>
          <Chat.MessageList>
            {messages.map((msg) => (
              <MessageRow
                key={msg.id}
                messageId={msg.id}
                chunksCollection={chunksCollection}
              />
            ))}
          </Chat.MessageList>
          <MessageFeedScrollAnchor />
        </Chat.Floating.Content>
        <Chat.Floating.Footer
          files={{ available: myFiles }}
          instructions={{ available: myInstructions }}
        />
      </Chat.Floating.Shell>
    </Chat.Floating>
  );
}
```

## Built-in Chunks [#built-in-chunks]

| Type         | Description                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------------------- |
| `markdown`   | Streamdown-rendered markdown with optional inline citations                                             |
| `reasoning`  | Collapsible "thinking" accordion. Supports custom `label` (defaults to "Thinking...")                   |
| `task`       | Hierarchical task list with progress metadata                                                           |
| `table`      | Tabular data with optional headers                                                                      |
| `card`       | Title/description/link summary                                                                          |
| `alert`      | Inline alert banner (`info`, `warning`, `success`, `destructive`)                                       |
| `references` | Collapsible source list linked to inline citations                                                      |
| `artifact`   | Inline document preview card. Expands to a side panel (fullscreen) or Sheet overlay (floating/sidebar). |

<Callout type="info">
  Need a custom chunk type? See the [Chunk Registry](./custom-chunks).
</Callout>

## Pages [#pages]

<Cards>
  <Card title="Architecture" href="./architecture">
    Composition model, shared context, variant layout contexts, and data flow.
  </Card>

  <Card title="Data Contracts" href="./data-contracts">
    ChatMessageView, ChunkRow, MessagePayload, callbacks, and useChatSelection.
  </Card>

  <Card title="Floating" href="./floating">
    Floating chat bubble with engagement-driven animation lifecycle.
  </Card>

  <Card title="Sidebar" href="./sidebar">
    Fixed side panel with always-visible chrome.
  </Card>

  <Card title="Fullscreen" href="./fullscreen">
    Multi-panel page with resizable layout and conversation nav.
  </Card>

  <Card title="Messages" href="./messages">
    MessageEntry, ChunkList, message feeds, and citation sync.
  </Card>

  <Card title="Prompt Input" href="./prompt-input">
    Footer, file picker, instruction picker, and payload structure.
  </Card>

  <Card title="Chunk Registry" href="./custom-chunks">
    Custom chunk renderers, registry API, and chunk-panel co-location.
  </Card>
</Cards>