@flamingo-stack/openframe-frontend-core 0.0.481 → 0.0.482

package/src/components/chat/.chat-attachment-bar.md

@@ -1,26 +1,17 @@
-<!-- source-hash: f3fb53b66abf55ba1b2ac14522e64cbb -->
-Provides two composable React primitives for the chat compose-box attachment UX: a `+` add-button rendered inline in the bottom controls row, and a horizontal chip strip rendered above the textarea showing staged file previews with upload progress.
+<!-- source-hash: 9b87d21631234ee48c0578e5959504ff -->
+Renders the two primary UI primitives for chat file attachments: a horizontal chip strip displayed above the textarea and a borderless `+` button rendered inline in the bottom-controls row.
 
 ## Key Components
 
-### Exports
-
-| Export | Type | Description |
-|--------|------|-------------|
-| `ChatAttachmentAddButton` | Component | Borderless `+` icon button for triggering file picker; renders an invisible 28×28 spacer when `attachmentsEnabled` is false to prevent layout shift |
-| `ChatAttachmentChipStrip` | Component | Horizontal strip of file chips above the textarea; returns `null` when no attachments are staged |
-| `StagedAttachment` | Interface | Shape consumed by the chip strip, mirrors the hub's `useChatAttachments` output |
-| `CHAT_ATTACHMENT_MIME_TYPES` | Constant | Allowed MIME types (JPEG, PNG, WebP, GIF, MP4, WebM, QuickTime) — excludes `image/svg+xml` for XSS safety |
-| `CHAT_ATTACHMENT_CONCURRENT_UPLOADS_PER_USER` | Constant | Client-side cap of 5 concurrent staged files |
-
-### Internal Helpers
-
-| Name | Purpose |
-|------|---------|
-| `AttachmentChip` | Single chip: inline blob thumbnail (images), progress bar overlay, filename, status text, × remove button |
-| `useObjectUrl` | Hook managing `URL.createObjectURL` lifecycle — revokes on unmount and file change |
-| `formatFileSize` | Human-readable byte formatter (B / KB / MB / GB) |
-| `extLabel` | Extracts up to 3-char file extension for non-image chip placeholders |
+| Export | Description |
+|---|---|
+| `ChatAttachmentAddButton` | Icon-only `+` button for triggering file selection; reserves layout space when disabled to prevent CLS |
+| `ChatAttachmentChipStrip` | Horizontal strip of staged-file chips rendered above the input; returns `null` when empty |
+| `AttachmentChip` | Internal chip component showing thumbnail/initials, upload progress, file name, size, and a remove button |
+| `StagedAttachment` | Interface describing a staged file (id, file, status, progress, storagePath, viewToken, errorMessage) |
+| `ChatAttachmentSize` | `'default' \| 'compact'` density union for narrow surfaces like the ticket-drawer composer |
+| `CHAT_ATTACHMENT_MIME_TYPES` | Allow-listed MIME types (images + video); excludes `image/svg+xml` for XSS safety |
+| `CHAT_ATTACHMENT_CONCURRENT_UPLOADS_PER_USER` | Client-side cap of 5 concurrent uploads |
 
 ## Usage Example
 
@@ -28,37 +19,38 @@ Provides two composable React primitives for the chat compose-box attachment UX:
 import {
   ChatAttachmentAddButton,
   ChatAttachmentChipStrip,
-  StagedAttachment,
+  type StagedAttachment,
 } from './chat-attachment-bar'
 
-function Composebox() {
-  const { attachments, addFiles, removeFile } = useChatAttachments()
-  const { attachmentsEnabled } = useChatIdentity()
-
+function ComposerToolbar({ attachments, onAdd, onRemove, isStreaming }) {
   return (
     <div className="flex flex-col">
-      {/* Chip strip floats above textarea — hidden when empty */}
+      {/* Chip strip floats above the textarea — hidden when empty */}
       <ChatAttachmentChipStrip
         attachments={attachments}
-        onRemove={removeFile}
+        onRemove={onRemove}
         disabled={isStreaming}
+        size="compact" // narrow drawer surface
       />
 
-      <textarea placeholder="Message…" />
-
-      {/* Bottom controls row */}
-      <div className="flex items-center gap-2">
-        <ChatAttachmentAddButton
-          attachmentsEnabled={attachmentsEnabled}
-          attachmentsCount={attachments.length}
-          onAddFiles={addFiles}
-          disabled={isStreaming}
-        />
-        <ModelDisplay />
-      </div>
+      {/* + button lives in the bottom-controls row */}
+      <ChatAttachmentAddButton
+        attachmentsEnabled={true}        // from useChatIdentity().attachmentsEnabled
+        attachmentsCount={attachments.length}
+        onAddFiles={onAdd}
+        disabled={isStreaming}
+        size="compact"
+      />
     </div>
   )
 }
 ```
 
-> **Layout stability note:** `ChatAttachmentAddButton` renders an invisible `<span>` placeholder before `attachmentsEnabled` resolves, preventing the bottom-controls row from shifting when chat identity loads asynchronously (~100–500 ms).
+## Notes
+
+- **No `capture="environment"`** on the hidden file input — prevents iOS Safari from forcing camera-only mode.
+- **Layout stability**: when `attachmentsEnabled` is `false` (async load or anon user), an invisible `<span>` with the same `h-7 w-7` footprint replaces the button, eliminating row-width jumps on identity resolution.
+- Image chips render a local `createObjectURL` blob preview immediately, independent of upload progress.
+- All colors use ODS design tokens; no hex values are used directly.
+
+**Source:** [`chat-attachment-bar.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/chat-attachment-bar.tsx)

package/src/components/chat/.chat-composer.md

@@ -0,0 +1,43 @@
+<!-- source-hash: f8f1c7865379c443151b15db768be877 -->
+Presentational footer composer for the OpenFrame chat panel, rendering either a live `ChatInput` or a read-only archived placeholder above the model/usage row, with optional entity-context picker integration.
+
+## Key Components
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `ChatComposer` | Component | Main composer component combining input, context strips, and model row |
+| `ChatComposerProps` | Interface | Full prop contract for the composer |
+
+## Key Behaviors
+
+- **Archived mode** — replaces the input with an unarchive prompt banner (`BoxArchiveIcon` + message)
+- **Context mode** — activated when `contextPicker` is set; wraps input in a unified card with a focus-ring border, renders `ChatContextMemoryBar` (ambient navigation history), `ChatContextChipStrip` (explicitly assigned items), and a `+` plus-menu anchored inside the input's start adornment
+- **Legacy mode** — plain `ChatInput` with an optional standalone `ChatAttachmentAddButton` to the left of the model row
+- **Icon resolution** — memoizes a `type → icon` map from `contextPicker.entityTypes` to avoid rebuilding on every render
+
+## Usage Example
+
+```typescript
+<ChatComposer
+  inputRef={inputRef}
+  onSend={handleSend}
+  onStop={handleStop}
+  sending={isSending}
+  placeholder="Message Mingo..."
+  model={{ name: 'gpt-4o', tokensUsed: 1200, tokenLimit: 8000 }}
+  contextPicker={pickerConfig}
+  selectedContextItems={selectedItems}
+  onToggleContextItem={handleToggle}
+  onRemoveContextItem={handleRemove}
+  contextMemoryItems={memoryItems}
+  contextPickerOpen={pickerOpen}
+  onOpenContextPicker={() => setPickerOpen(true)}
+  onCloseContextPicker={() => setPickerOpen(false)}
+  mentionQuery={mentionQuery}
+  onMentionQueryChange={setMentionQuery}
+/>
+```
+
+## Source
+
+[`chat-composer.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/chat-composer.tsx)

package/src/components/chat/.chat-container.md

@@ -1,15 +1,33 @@
-<!-- source-hash: 748948c6317fda009af640633bb6c0e5 -->
-Composable React components for building a full-screen chat interface shell, including layout, header, content area, and footer sections with ODS design token styling.
+<!-- source-hash: 837e81768e91b5500387c07ee348adb7 -->
+Compound component set providing the structural layout for an AI chat interface, including header (with avatar, connection status, ticket info, and MSP branding), scrollable content area, and footer regions.
 
 ## Key Components
 
-| Component | Description |
-|-----------|-------------|
-| `ChatContainer` | Root full-screen wrapper with ODS background and responsive padding |
-| `ChatHeader` | Rich header with avatar, user info, connection status, ticket context, and action buttons |
-| `ChatContent` | Flex-grow scrollable content region between header and footer |
-| `ChatFooter` | Sticky footer wrapper with optional full-width or narrow-column layout |
-| `ConnectionIndicator` | Internal dot badge showing `connected` / `connecting` / `disconnected` states using ODS attention tokens |
+| Export | Type | Description |
+|---|---|---|
+| `ChatContainer` | `forwardRef<HTMLDivElement>` | Root full-screen flex wrapper with ODS background and padding |
+| `ChatHeader` | `forwardRef<HTMLDivElement>` | Header with avatar, connection indicator, ticket status, MSP org card, and action buttons |
+| `ChatContent` | `forwardRef<HTMLDivElement>` | Flex-growing scrollable content region between header and footer |
+| `ChatFooter` | `forwardRef<HTMLDivElement>` | Sticky bottom area housing the input composer |
+| `ConnectionIndicator` | `FC` | Internal pulsing dot reflecting `connected` / `connecting` / `disconnected` states |
+
+### `ChatHeader` Notable Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `connectionStatus` | `'connected' \| 'connecting' \| 'disconnected'` | `'disconnected'` | Drives `ConnectionIndicator` color |
+| `ticketInfo` | `object` | — | Renders a ticket title, meta, and `TicketStatusTag` in the sub-row |
+| `mspOrganization` | `object` | — | Shows `MspOrganizationCard` when no `ticketInfo` is present |
+| `fullWidth` | `boolean` | `false` | Drops the `max-w-ods-content-narrow` column constraint for side-panel use |
+| `bare` | `boolean` | `false` | Removes card chrome (border, background, rounding) |
+| `isLoading` | `boolean` | `false` | Renders skeleton placeholders in place of avatar and name |
+
+### `ChatFooterProps`
+
+| Prop | Type | Description |
+|---|---|---|
+| `fullWidth` | `boolean` | Drops inner `max-w-ods-content-narrow` wrapper |
+| `contentClassName` | `string` *(deprecated)* | Legacy escape hatch for custom width/padding overrides |
 
 ## Usage Example
 
@@ -19,40 +37,38 @@ import {
   ChatHeader,
   ChatContent,
   ChatFooter,
-} from "./chat-container"
+} from "@openframe/ui/chat"
 
-export function MyChatShell() {
+export function MyChatPanel() {
   return (
     <ChatContainer>
       <ChatHeader
-        userName='Grace "Fae" Meadows'
+        userName="Fae"
         userTitle="Your Personal Assistant"
         connectionStatus="connected"
-        serverUrl="mcp.flamingo.run"
+        serverUrl="acme.flamingo.run"
         showNewChat
-        onNewChat={() => console.log("new chat")}
-        onClose={() => console.log("close")}
+        onNewChat={() => startNewSession()}
+        onClose={() => closePanel()}
         ticketInfo={{
-          title: "Printer offline – Ticket #4821",
-          meta: "Assigned to: J. Smith",
-          status: "in-progress",
+          title: "Printer not responding",
+          meta: "#4821 · Open",
+          status: "open",
+          statusName: "Open",
         }}
         fullWidth
       />
       <ChatContent>
-        {/* message list */}
+        {/* message bubbles */}
       </ChatContent>
       <ChatFooter fullWidth>
-        {/* input bar */}
+        {/* composer input */}
       </ChatFooter>
     </ChatContainer>
   )
 }
 ```
 
-## Notes
+## Source
 
-- `fullWidth` on both `ChatHeader` and `ChatFooter` drops the default `max-w-ods-content-narrow` (≈600px) column — use this when embedding the chat in a side panel.
-- `ChatFooter.contentClassName` is a legacy escape hatch for custom `max-w` overrides; prefer `fullWidth` for standard full-panel layouts.
-- `ChatHeader` accepts a `bare` prop to remove card chrome (shadow, border, background) for flush-mounted contexts.
-- All components are `forwardRef`-compatible and spread unknown props to their root `<div>`.
+[`chat-container.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/chat-container.tsx)

package/src/components/chat/.chat-context-memory-bar.md

@@ -0,0 +1,53 @@
+<!-- source-hash: 841aa743a8a7671177fef949f75252e1 -->
+A passive "context memory" strip rendered above the chat composer, showing a count of ambient remembered entities ("5 recently viewed items in context") with an ellipsis trigger that opens a scrollable dropdown listing each item with an optional remove button.
+
+## Key Components
+
+### `ChatContextMemoryBar` (exported component)
+
+The sole export. Renders `null` when `items` is empty, so it has zero DOM footprint when unused.
+
+**Props (`ChatContextMemoryBarProps`):**
+
+| Prop | Type | Description |
+|---|---|---|
+| `items` | `ChatContextItem[]` | Remembered entities, most-recent-first |
+| `onRemove` | `(item: ChatContextItem) => void` | Optional removal handler; omit for read-only |
+| `resolveIcon` | `(item: ChatContextItem) => React.ReactNode` | Entity-type icon resolver matching the picker/chip icon map |
+| `disabled` | `boolean` | Disables remove buttons (e.g. during streaming) |
+| `className` | `string` | Additional classes for the root strip |
+
+### Internal behaviors
+
+- **Outside-click dismiss** — uses capture-phase `mousedown`/`touchstart` listeners on `document` to reliably close the dropdown even inside resizable drawers or `contentEditable` ancestors that may call `stopPropagation`.
+- **Auto-close on empty** — a `useEffect` watching `items.length` closes the dropdown before the bar unmounts, preventing a stale popover outliving its trigger.
+- **Escape key** — closes the dropdown via `onKeyDown` on the root element.
+
+## Usage Example
+
+```typescript
+import { ChatContextMemoryBar } from './chat-context-memory-bar'
+import type { ChatContextItem } from './types/context-item.types'
+
+const memoryItems: ChatContextItem[] = [
+  { type: 'ticket', id: '42', label: 'Printer offline – HQ' },
+  { type: 'device',  id: '7',  label: 'DESKTOP-ABC123' },
+]
+
+function Composer() {
+  const handleRemove = (item: ChatContextItem) => {
+    console.log('Remove from memory:', item.id)
+  }
+
+  return (
+    <ChatContextMemoryBar
+      items={memoryItems}
+      onRemove={handleRemove}
+      resolveIcon={(item) => <EntityIcon type={item.type} />}
+      disabled={isStreaming}
+    />
+  )
+}
+```
+
+> **Placement note:** This "ambient" bar sits above `<ChatContextChipStrip>` (user-assigned items). Both live above the textarea — memory on top (passive), chips below (active per-message selection).

package/src/components/chat/.chat-context-picker.md

@@ -0,0 +1,89 @@
+<!-- source-hash: 561900464791edb34123d4b8cbc3991e -->
+Renders a three-part entity-context picker UI for the chat composer: a `+` trigger button, a two-level popover for browsing and searching entity types/items, and a chip strip for displaying selected items.
+
+## Key Components
+
+### `ChatComposerPlusMenu`
+The `+` button rendered inside the composer input. Toggles the context picker open/closed, with visual states (grey → white → accent-yellow) reflecting hover, press, and open states.
+
+**Props:**
+| Prop | Type | Description |
+|---|---|---|
+| `onToggle` | `() => void` | Opens/closes the picker |
+| `open` | `boolean` | Drives the accent-yellow active state |
+| `disabled` | `boolean` | Disables the trigger during streaming |
+| `dropdown` | `React.ReactNode` | The `<ChatContextPicker>` anchored to this button |
+
+### `ChatContextPicker`
+A two-level popover (`bottom-full` positioned above the input). Level 1 lists entity types; Level 2 shows a debounced-search, multi-select list of items with checkmarks. Supports `@`-mention query seeding.
+
+**Props:**
+| Prop | Type | Description |
+|---|---|---|
+| `open` | `boolean` | Controls render |
+| `config` | `ChatContextPickerConfig` | Host-provided entity types and `search()` resolver |
+| `selectedItems` | `ChatContextItem[]` | Drives ✓ state |
+| `onToggleItem` | `(item) => void` | Add/remove selection |
+| `onClose` | `() => void` | Escape, outside-click, or X |
+| `mentionQuery` | `string \| null` | Pre-filters type list from `@` trigger |
+
+### Constants
+
+| Constant | Value | Purpose |
+|---|---|---|
+| `CHAT_CONTEXT_ITEMS_DEFAULT_MAX` | `10` | Max selectable items |
+| `SEARCH_DEBOUNCE_MS` | `300` | Keystroke debounce before calling `config.search()` |
+| `ITEMS_SKELETON_ROWS` | `10` | Suspense fallback row count |
+
+## Usage Example
+
+```typescript
+import {
+  ChatComposerPlusMenu,
+  ChatContextPicker,
+} from './chat-context-picker'
+
+function ComposerToolbar() {
+  const [open, setOpen] = useState(false)
+  const [selected, setSelected] = useState<ChatContextItem[]>([])
+
+  const config: ChatContextPickerConfig = {
+    entityTypes: [
+      { id: 'device', label: 'Device' },
+      { id: 'script', label: 'Script' },
+    ],
+    search: async (type, query, signal) => fetchItems(type, query, signal),
+  }
+
+  const toggleItem = (item: ChatContextItem) =>
+    setSelected((prev) =>
+      prev.some((i) => i.id === item.id)
+        ? prev.filter((i) => i.id !== item.id)
+        : [...prev, item],
+    )
+
+  return (
+    <ChatComposerPlusMenu
+      open={open}
+      onToggle={() => setOpen((v) => !v)}
+      dropdown={
+        <ChatContextPicker
+          open={open}
+          config={config}
+          selectedItems={selected}
+          onToggleItem={toggleItem}
+          onClose={() => setOpen(false)}
+        />
+      }
+    />
+  )
+}
+```
+
+## Behavioral Notes
+
+- **Height measurement** (`useLayoutEffect`): caps the popover to the real visible space above the button by walking up to the nearest `overflow` clip ancestor — handles drawer/panel layouts without hard-coded pixel values.
+- **Outside-click handling**: ignores clicks on `[data-context-trigger]` so the `+` button can toggle cleanly without immediately re-closing.
+- **Library boundary**: the component owns only UI and selection state. All data fetching is delegated to `config.search()` — the library has no knowledge of specific entity types.
+
+**Source:** [`chat-context-picker.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/chat-context-picker.tsx)

package/src/components/chat/.chat-header-icon-button.md

@@ -0,0 +1,43 @@
+<!-- source-hash: 3f73058e6afda4a07e57e42605ab516d -->
+A 56×56 square icon button component for the chat panel's top-navigation bar, supporting configurable 1px cell dividers and accessible focus styling.
+
+## Key Components
+
+- **`ChatHeaderIconButton`** — A `forwardRef` button component rendering a fixed-size (`size-14`) icon cell with optional left/right/none border dividers, hover background transitions, and focus-visible ring support.
+- **`ChatHeaderIconButtonProps`** — Extends `React.ButtonHTMLAttributes<HTMLButtonElement>` with a `divider` prop (`'left' | 'right' | 'none'`, default `'left'`).
+
+## Usage Example
+
+```typescript
+import { ChatHeaderIconButton } from './chat-header-icon-button'
+import { X, ChevronLeft, ArchiveIcon } from 'lucide-react'
+
+// Trailing cell (default left divider)
+<ChatHeaderIconButton onClick={onClose} aria-label="Close chat">
+  <X className="size-5" />
+</ChatHeaderIconButton>
+
+// Leading back chevron (right divider)
+<ChatHeaderIconButton divider="right" onClick={onBack} aria-label="Go back">
+  <ChevronLeft className="size-5" />
+</ChatHeaderIconButton>
+
+// No divider
+<ChatHeaderIconButton divider="none" onClick={onArchive} aria-label="Archive">
+  <ArchiveIcon className="size-5" />
+</ChatHeaderIconButton>
+
+// As a Radix asChild trigger
+<DropdownMenu.Trigger asChild>
+  <ChatHeaderIconButton aria-label="More options">
+    <MoreHorizontal className="size-5" />
+  </ChatHeaderIconButton>
+</DropdownMenu.Trigger>
+```
+
+## Notes
+
+- Icon color stays `ods-text-secondary` on hover — only the background transitions to `ods-bg-hover`.
+- `forwardRef` + full prop spread make it composable as a Radix `asChild` trigger.
+- `type="button"` is set by default to prevent accidental form submission.
+- Source: [`chat-header-icon-button.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/chat-header-icon-button.tsx)

package/src/components/chat/.chat-header-search-field.md

@@ -0,0 +1,51 @@
+<!-- source-hash: a50c170e985f2e097a37aa07979fae4b -->
+Controlled inline search field that replaces the chat panel header's title area when search is active, debouncing typed input before emitting it to the host for server-side refetching.
+
+## Key Components
+
+### `ChatHeaderSearchField`
+
+The primary export. Renders a leading `SearchIcon` alongside a borderless, full-height `<input>` that takes over the header title slot. Manages its own text state locally for snappy typing, then propagates the debounced query (300 ms) via `onSearchChange`.
+
+**Collapse lifecycle** — exit animations are coordinated manually:
+
+1. `beginCollapse()` sets `exiting = true`, disabling the input and triggering CSS leave animations.
+2. `finishCollapse()` is called on `animationend` of the root element (bubbled child events are ignored).
+3. A 240 ms `setTimeout` fallback fires `finishCollapse` when `animationend` never fires (reduced-motion or stripped utilities).
+
+**Stale-debounce guard** — when Escape is pressed or the field blurs empty, the cleared term is emitted synchronously and recorded in `lastEmitted`, preventing the still-pending 300 ms debounce from triggering a redundant server round-trip after unmount begins.
+
+### `ChatHeaderSearchFieldProps`
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `initialValue` | `string` | `''` | Seeds the input on mount |
+| `onSearchChange` | `(query: string) => void` | — | Receives the debounced search term |
+| `onCollapse` | `() => void` | — | Called after the leave animation completes |
+| `autoFocus` | `boolean` | `true` | Focuses the input on mount |
+| `className` | `string` | — | Appended to the root element |
+
+## Usage Example
+
+```typescript
+import { ChatHeaderSearchField } from './chat-header-search-field'
+
+function ChatPanelHeader() {
+  const [searchOpen, setSearchOpen] = React.useState(false)
+  const [query, setQuery] = React.useState('')
+
+  return (
+    <header>
+      {searchOpen ? (
+        <ChatHeaderSearchField
+          initialValue={query}
+          onSearchChange={(term) => setQuery(term)}
+          onCollapse={() => setSearchOpen(false)}
+        />
+      ) : (
+        <h1>Chats</h1>
+      )}
+    </header>
+  )
+}
+```

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

@@ -1,29 +1,35 @@
-<!-- source-hash: 6d459e335b05378d1756f274a61128f0 -->
-A controlled chat input component with slash-command autocomplete, send/stop functionality, and an imperative ref API for programmatic control.
+<!-- source-hash: 5ef079ca48dfe4a6d1f2fa08a9c755fe -->
+Rich contenteditable chat input component with support for `@`-mention chips, slash-command suggestions, send/stop controls, and a ghost preview overlay.
 
 ## Key Components
 
-### `ChatInput` (default export)
-A `forwardRef` component that renders a textarea-based chat input with:
-- **Slash command autocomplete** — triggers on `/` prefix, debounced 150ms, keyboard-navigable dropdown
-- **Send/Stop modes** — toggles between send and stop-stream actions based on `sending`/`onStop` props
-- **Awaiting response indicator** — replaces input with `ChatTypingIndicator` while waiting for a reply
-- **Auto-refocus** — restores focus after send completes or streaming stops
+### Exported
 
-### `ChatInputRef` (imperative handle)
-Exposed methods for parent components:
+- **`ChatInput`** (`forwardRef<ChatInputRef, ChatInputProps>`) — Primary component. Renders a `contenteditable` div editor rather than a `<textarea>`, enabling inline mention chips as atomic DOM nodes.
+
+### Internal Helpers
+
+| Function | Purpose |
+|---|---|
+| `parseSegments` | Splits a draft string into `text` and `mention` segments using `MENTION_GLOBAL` regex |
+| `serialize` | Walks the editor's `childNodes` to reconstruct the draft string from text nodes and chip elements |
+| `buildChipEl` | Creates a non-React DOM node for a committed `@`-mention using `renderToStaticMarkup` on the `Tag` component |
+| `rebuildDom` | Replaces editor content wholesale from a value string + metadata map |
+| `placeCaretAtEnd` / `placeCaretAtOffset` | Caret placement utilities using the Selection API |
+| `insertTextAtCaret` | Inserts plain text at caret without injecting `<br>` or `<div>` elements |
+
+### `ChatInputRef` (Imperative Handle)
 
 | Method | Description |
 |---|---|
 | `focus()` / `blur()` | Programmatic focus control |
-| `clear()` | Resets input value |
-| `setValue(next)` | Prefills input, places caret at end |
-| `setValueAndCursor(next, offset)` | Prefills input with clamped caret position |
-| `submit(next)` | Fires `onSend` and clears, bypassing user interaction |
-| `getValue()` | Returns current value via stable ref |
-
-### `SLASH_INPUT_TRIGGER`
-Regex `/^\/([a-z][a-z0-9-]*)?$/` — kept in sync with server-side slash command registration to prevent suggesting commands the API would reject.
+| `clear()` | Resets draft and metadata |
+| `setValue(next)` | Replaces editor content |
+| `setValueAndCursor(next, offset)` | Replaces content and positions caret |
+| `submit(next)` | Fires the send handler directly |
+| `getValue()` | Synchronous draft read |
+| `removeMentionTrigger()` | Strips trailing `@query` from draft |
+| `commitMention(token, meta?)` | Replaces in-progress `@query` with a chip token |
 
 ## Usage Example
 
@@ -32,25 +38,52 @@ import { useRef } from "react"
 import { ChatInput } from "./chat-input"
 import type { ChatInputRef } from "./types"
 
-function ChatPanel() {
+function MyComposer() {
   const inputRef = useRef<ChatInputRef>(null)
 
-  const prefillSlashCommand = () => {
-    inputRef.current?.setValue("/reboot ")
-  }
-
   return (
     <ChatInput
       ref={inputRef}
-      sending={false}
-      awaitingResponse={false}
-      onSend={(message) => console.log("Sending:", message)}
-      onStop={() => abortStream()}
-      slashCommands={{
-        fetchCommands: async (prefix, signal) => fetchSlashCommands(prefix, signal),
+      placeholder="Type a message..."
+      onSend={(message) => {
+        console.log("Sending:", message)
+        return fetch("/api/chat", { method: "POST", body: message })
+          .then(() => true)
       }}
+      onMentionQueryChange={(query) => {
+        // fetch mention suggestions for `query`
+      }}
+      slashCommands={[
+        { name: "summarize", description: "Summarize the conversation" },
+      ]}
       autoFocus
     />
   )
 }
-```
+
+// Imperative control
+inputRef.current?.setValue("/summarize ")
+inputRef.current?.commitMention("ticket:abc123", {
+  label: "Ticket #123",
+  icon: <TicketIcon />,
+})
+```
+
+## Key Regex Constants
+
+```typescript
+// Committed mention token in draft string
+const MENTION_GLOBAL = /@[A-Za-z0-9_.+/=-]+:[A-Za-z0-9_.+/=-]+/g
+
+// In-progress @query at end of draft (excludes email addresses)
+const MENTION_TRIGGER_AT_END = /(^|\s)@([\w.-]*)$/
+
+// Slash command activation trigger
+const SLASH_INPUT_TRIGGER = /^\/([a-z][a-z0-9-]*)?$/
+```
+
+> **Note:** `SLASH_INPUT_TRIGGER` is shared with `lib/config/slash-commands-config.ts` and the chat-route slash dispatch parser — keep all three in sync.
+
+## Source
+
+[`chat-input.tsx` on GitHub](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/chat-input.tsx)

package/src/components/chat/.chat-list-empty-state.md

@@ -0,0 +1,44 @@
+<!-- source-hash: 5fc10ddb4837c0d5506138aed4e8345a -->
+Reusable empty-state component for chat-list surfaces, rendering a muted icon above a title and optional description in a vertically centred layout.
+
+## Key Components
+
+### `ChatListEmptyState`
+A client component that renders a centred empty state with three elements:
+- **Icon** — a 24px muted glyph (`ods-text-secondary`) wrapped in a fixed `size-6` container
+- **Title** — displayed as an `h4` paragraph
+- **Description** — optional `h6` caption rendered below the title
+
+### `ChatListEmptyStateProps`
+
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `icon` | `React.ReactNode` | ✅ | Pre-sized 24px icon glyph |
+| `title` | `React.ReactNode` | ✅ | Title line rendered as `h4` |
+| `description` | `React.ReactNode` | ❌ | Optional caption rendered as `h6` |
+| `className` | `string` | ❌ | Appended to root element |
+
+## Usage Example
+
+```typescript
+import { ChatListEmptyState } from './chat-list-empty-state'
+import { ChatsIcon } from '../icons'
+
+// With title only
+<ChatListEmptyState
+  icon={<ChatsIcon size={24} />}
+  title="No active chats"
+/>
+
+// With description
+<ChatListEmptyState
+  icon={<ChatsIcon size={24} />}
+  title="No archived chats"
+  description="Completed conversations will appear here."
+  className="my-custom-class"
+/>
+```
+
+> **Design note:** This component is shared between the "Current Chats" rail and the Chat Archive page (Figma node `113:60939`) to keep both surfaces visually consistent.
+
+**Source:** [`flamingo-stack/openframe-oss-lib`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/chat-list-empty-state.tsx)