@flamingo-stack/openframe-frontend-core 0.0.213 → 0.0.214-snapshot.20260528192313

package/src/components/chat/entity-cards/.product-release-card.md

@@ -0,0 +1,29 @@
+<!-- source-hash: d44532c82b6ead050537a1a73696aeb3 -->
+Re-export shim that surfaces the canonical `ProductReleaseCard` component and its related types/skeleton under the `entity-cards/` namespace for unified chat barrel imports.
+
+## Key Components
+
+| Export | Source | Description |
+|--------|--------|-------------|
+| `ProductReleaseCard` | `shared/product-release/product-release-card` | Main card component (lg + sm variants) |
+| `ProductReleaseCardProps` | `shared/product-release/product-release-card` | Component props type |
+| `ProductReleaseCardSize` | `shared/product-release/product-release-card` | Size variant union type |
+| `ProductReleaseCardAnchorProps` | `shared/product-release/product-release-card` | Anchor/link props type |
+| `ProductReleaseCardSkeleton` | `shared/product-release/product-release-card-skeleton` | Loading skeleton component |
+
+## Usage Example
+
+```typescript
+// Via the chat barrel (preferred)
+import {
+  ProductReleaseCard,
+  ProductReleaseCardSkeleton,
+  type ProductReleaseCardProps,
+  type ProductReleaseCardSize,
+} from '@/components/chat'
+
+// Direct import (bypasses indirection)
+import { ProductReleaseCard } from '@/components/shared/product-release/product-release-card'
+```
+
+> **Source of Truth:** All component logic and variants live in `src/components/shared/product-release/`. This file is purely a re-export — do not add logic here.

package/src/components/chat/entity-cards/.program-card-defaults.md

@@ -0,0 +1,41 @@
+<!-- source-hash: b76130e377c5c19a3a90e82e946098da -->
+Provides fallback `ProgramConfig` defaults for the chat dispatch layer, ensuring `<ProgramCard size='sm'>` renders correctly without requiring embedders to supply hub-side catalog configuration.
+
+## Key Components
+
+### `makeDefault<T>`
+Generic factory function that constructs a minimal `ProgramConfig<T>` for a given program type. Populates only the fields the compact chat card actually reads (`type`, `labels.singular`) plus safe placeholder values for catalog-page fields (`dateField`, `table`, `apiEndpoint`, `icon`, `detailRoute`, `externalLinkLabel`) so TypeScript type-checking passes without binding embedders to hub-internal imports.
+
+### `DEFAULT_PROGRAM_CONFIGS`
+Exported `const` map of ready-to-use defaults for all three program types:
+
+| Key | `type` | `labels.singular` | `labels.plural` |
+|--------|---------|-------------------|-----------------|
+| `podcast` | `"podcast"` | `"Episode"` | `"Episodes"` |
+| `webinar` | `"webinar"` | `"Webinar"` | `"Webinars"` |
+| `event` | `"event"` | `"Event"` | `"Events"` |
+
+## Usage Example
+
+The chat dispatch reads `extras.programConfigs.X ?? DEFAULT_PROGRAM_CONFIGS.X`, so overriding is opt-in:
+
+```typescript
+import { DEFAULT_PROGRAM_CONFIGS } from './program-card-defaults'
+
+// Use defaults — no hub-side config required
+const config = DEFAULT_PROGRAM_CONFIGS.podcast
+// config.labels.singular → "Episode"
+// config.type            → "podcast"
+
+// Override only what you need; fallback handles the rest
+const customConfigs = {
+  podcast: {
+    ...DEFAULT_PROGRAM_CONFIGS.podcast,
+    icon: MyPodcastIcon,
+    externalLinkLabel: 'Listen Now',
+    detailRoute: '/podcasts',
+  },
+}
+```
+
+> **Why this exists:** Previously, missing `extras.programConfigs` caused the dispatch to return `null`, falling back to a bare text chip. These defaults decouple non-hub embedders (e.g. the validation app) from `currentPlatform()` and `buildContentURL` — hub-internal dependencies they cannot safely import.

package/src/components/chat/entity-cards/.program-card.md

@@ -0,0 +1,59 @@
+<!-- source-hash: 882a2c614fa33ecfd7b3ef948ea40a94 -->
+Brief overview of the `program-card.tsx` component — a pure presentational card for displaying podcasts, webinars, and events with two density modes.
+
+## Key Components
+
+### Exports
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `ProgramCardSkeleton` | Component | Loading placeholder supporting `default` and `sm` sizes |
+| `ProgramCard<T>` | Generic Component | Main card component, typed against `BaseProgramItem` |
+| `ProgramCardProps<T>` | Interface | Props contract for `ProgramCard` |
+
+### Internal Helpers
+
+- **`getHosts()`** — Normalizes host data from either a typed array or a JSON string
+- **`MediaGallery`** — Scrollable thumbnail strip with `ImageGalleryModal` lightbox integration
+
+### Card Sizes (`CardSize`)
+
+| Size | Layout | Use Case |
+|------|--------|----------|
+| `default` | Vertical, full detail | Standalone page/feed cards |
+| `sm` | Compact horizontal | Chat-inline embeds |
+
+### Type-Aware Metadata
+
+The card adapts displayed metadata based on `config.type`:
+
+- **`podcast`** → Duration via `formatDurationCompact`
+- **`event`** → Location name
+- **`webinar`** → Start time + duration via `formatTimeWithTimezone` / `formatDurationFromRange`
+
+## Usage Example
+
+```typescript
+import { ProgramCard } from './program-card'
+
+// Default (vertical) layout
+<ProgramCard
+  config={{ type: 'podcast', labels: { singular: 'Episode' } }}
+  item={episode}
+  href="/podcasts/ep-42"
+  size="default"
+/>
+
+// Compact inline variant (e.g., inside chat)
+<ProgramCard
+  config={{ type: 'webinar', labels: { singular: 'Webinar' } }}
+  item={webinarItem}
+  href="https://external.com/webinar"
+  target="_blank"
+  rel="noopener noreferrer"
+  size="sm"
+  placeholderUrl="https://cdn.example.com/og-fallback.png"
+/>
+```
+
+> **Note:** `ProgramCard` is purely presentational — it owns no navigation logic. Callers are responsible for computing and passing `href` and `target`.

package/src/components/chat/entity-cards/.roadmap-card.md

@@ -0,0 +1,46 @@
+<!-- source-hash: 853672c07dc2c32f2542a936a393a3ad -->
+Pure presentation component for roadmap items with two density modes — a rich default card (vote buttons, Figma/screenshot controls) and a compact horizontal variant for inline chat display.
+
+## Key Components
+
+| Export | Description |
+|--------|-------------|
+| `RoadmapCard` | Main card component, renders either `default` or `sm` layout |
+| `RoadmapCardSkeleton` | Loading placeholder matching both card densities |
+| `VoteType` | Union type `'up' \| 'down' \| null` for vote state |
+| `RoadmapCardProps` | Full props interface for the card |
+
+## Usage Example
+
+```typescript
+// Default (full roadmap page card with vote controls)
+<RoadmapCard
+  item={roadmapItem}
+  userVote={currentVote}
+  onVote={(type) => handleVote(item.id, type)}
+  isVoting={isPending}
+/>
+
+// Compact inline variant (chat/sidebar)
+<a href={`/roadmap/${item.id}`}>
+  <RoadmapCard
+    item={roadmapItem}
+    size="sm"
+    href={`/roadmap/${item.id}`}
+    cardType="delivery_item"
+    target="_blank"
+    rel="noopener noreferrer"
+  />
+</a>
+
+// Skeleton loader
+<RoadmapCardSkeleton size="sm" />
+```
+
+## Key Behaviors
+
+- **Icon resolution**: prefers `item.icon` (proxied), falls back to `TaskTypeIcon` for internal tasks, then initials
+- **`sm` branch**: wraps content in `<a>` when `href` is valid; renders a static `<span>` when no href is available
+- **Vote UI** (`default` only): rendered only when `onVote` is provided; buttons disabled during `isVoting`
+- **Screenshot gallery**: controlled via local `showScreenshots` state; Figma link and screenshot count displayed as metadata badges in the compact branch
+- **Responsive status badge**: shown inline on `md+` screens, moves below the header row on mobile

package/src/components/chat/entity-cards/.roadmap-vote-button.md

@@ -0,0 +1,52 @@
+<!-- source-hash: 69f5a0ba80b7e510b67573e50f546e85 -->
+A pure-presentational thumbs-up / thumbs-down vote button used within `RoadmapCard`'s default variant. Renders an icon with an optional vote count; all interaction logic is delegated to the parent via `onClick`.
+
+## Key Components
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `RoadmapVoteButtonProps` | `interface` | Prop contract for the button |
+| `RoadmapVoteButton` | `function` | Styled outline button with thumb icon and count |
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `voteType` | `'up' \| 'down'` | — | Selects `ThumbsUpIcon` or `ThumbsDownIcon` |
+| `count` | `number` | — | Vote tally displayed next to the icon |
+| `isActive` | `boolean` | — | Applies active background when the user has voted |
+| `onClick` | `() => void` | — | Click handler supplied by parent (e.g. `useRoadmapVoting`) |
+| `disabled` | `boolean` | `false` | Disables interaction and applies reduced opacity |
+| `showCount` | `boolean` | `true` | Toggles count label visibility |
+| `color` | `string` | — | Forwarded to the icon as a fill/stroke color |
+| `className` | `string` | — | Additional CSS classes merged via `cn()` |
+
+## Usage Example
+
+```typescript
+import { RoadmapVoteButton } from './roadmap-vote-button'
+
+function RoadmapCard() {
+  const { upvotes, hasVotedUp, handleVote } = useRoadmapVoting(itemId)
+
+  return (
+    <div className="flex gap-2">
+      <RoadmapVoteButton
+        voteType="up"
+        count={upvotes}
+        isActive={hasVotedUp}
+        onClick={() => handleVote('up')}
+        color="#FFC008"
+      />
+      <RoadmapVoteButton
+        voteType="down"
+        count={0}
+        isActive={false}
+        onClick={() => handleVote('down')}
+        showCount={false}
+        disabled
+      />
+    </div>
+  )
+}
+```

package/src/components/chat/entity-cards/.slack-message-card.md

@@ -0,0 +1,48 @@
+<!-- source-hash: 82997feaf6df9370cc3057cd02b01be6 -->
+Renders a visual card component for Slack message markers, supporting both `compact` and `row` display variants with optional anchor navigation and a loading skeleton state.
+
+## Key Components
+
+### `SlackMessageCard`
+Main card component that displays a Slack message entry with icon, title, preview text, channel name, and date. Rendering behavior varies by nav context:
+- Wraps in a caller-provided `<a>` via `anchorProps` if supplied
+- Falls back to a direct external `<a href>` if `item.url` is valid
+- Renders a static `<span>` when no link is available
+
+### `SlackMessageCardSkeleton`
+Animated placeholder matching the card layout for loading states. Accepts `variant` and `className` props.
+
+### `parseChannelFromUrl` *(internal)*
+Extracts the Slack channel ID from a Slack archive URL (`*.slack.com/archives/<channelId>/...`) as a fallback when `item.channel` is not set.
+
+### Interfaces
+
+| Interface | Purpose |
+|---|---|
+| `SlackMessageCardProps` | `item`, `variant`, `className`, `anchorProps` |
+| `SlackMessageCardAnchorProps` | Typed `<a>` prop bundle composed by the caller |
+
+## Usage Example
+
+```typescript
+import { SlackMessageCard, SlackMessageCardSkeleton } from './slack-message-card'
+
+// Compact card with caller-controlled navigation
+<SlackMessageCard
+  item={slackMessageItem}
+  variant="compact"
+  anchorProps={{
+    href: '/messages/123',
+    onClick: (e) => handleNavigate(e),
+  }}
+/>
+
+// Inline row variant (e.g. inside a list or table)
+<SlackMessageCard
+  item={slackMessageItem}
+  variant="row"
+/>
+
+// Skeleton while loading
+<SlackMessageCardSkeleton variant="compact" />
+```

package/src/components/chat/entity-cards/.task-type-icon.md

@@ -0,0 +1,47 @@
+<!-- source-hash: 3003c61a214e3bd7c976af0a59119cb4 -->
+Renders a Lucide icon corresponding to a ClickUp task type, resolved from `custom_item_id` via the `CUSTOM_ITEM_ID` map.
+
+## Key Components
+
+**`iconFor(customItemId)`** — Internal function that maps a `custom_item_id` integer to a Lucide icon component. Falls back to `CheckSquare` for unknown or `null`/`undefined` values.
+
+**`TaskTypeIcon`** — Client component that renders the resolved icon with configurable sizing via `className`.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `customItemId` | `number \| null \| undefined` | — | ClickUp `custom_item_id` to resolve |
+| `className` | `string` | `'h-5 w-5'` | Tailwind classes applied to the icon |
+
+**Type → Icon mapping:**
+
+| Task Type | Icon |
+|-----------|------|
+| `BUG` | `Bug` |
+| `REQUEST` | `Inbox` |
+| `FEATURE` | `Sparkles` |
+| `STORY` | `BookOpen` |
+| `EPIC` | `Trophy` |
+| `COMPONENT` | `Component` |
+| `INITIATIVE` | `Flag` |
+| `MILESTONE` | `Goal` |
+| `SUBTASK` | `ListTodo` |
+| `FORM` | `FileText` |
+| `RECURRING` | `Repeat` |
+| `PLAN` / `STRATEGY` | `Compass` |
+| `TASK` / default | `CheckSquare` |
+
+## Usage Example
+
+```typescript
+import { TaskTypeIcon } from './task-type-icon'
+import { CUSTOM_ITEM_ID } from '../utils/clickup-task-type-utils'
+
+// Render a bug icon
+<TaskTypeIcon customItemId={CUSTOM_ITEM_ID.BUG} />
+
+// Custom size via className
+<TaskTypeIcon customItemId={CUSTOM_ITEM_ID.EPIC} className="h-4 w-4 text-yellow-400" />
+
+// Safely handles null/undefined — renders CheckSquare fallback
+<TaskTypeIcon customItemId={task.custom_item_id} />
+```

package/src/components/chat/hooks/.index.md

@@ -1,31 +1,46 @@
-<!-- source-hash: c5ea66c3322aa31b6b73f0baba722b38 -->
-A centralized export module that provides access to all custom React hooks for real-time data processing and NATS messaging functionality in client-side components.
+<!-- source-hash: d1cebe46eff04115f214c16b75a69467 -->
+Barrel export file for the chat hooks module, re-exporting all public hooks from their individual files into a single `'use client'` entry point.
 
 ## Key Components
 
-**Re-exported Hooks:**
-- `use-chunk-catchup` - Hook for handling chunk synchronization and catch-up operations
-- `use-nats-dialog-subscription` - Hook for managing NATS dialog subscriptions and real-time messaging
-- `use-realtime-chunk-processor` - Hook for processing data chunks in real-time streams
+| Export Group | Hooks |
+|---|---|
+| **Realtime / Streaming** | `useChunkCatchup`, `useRealtimeChunkProcessor`, `useJetstreamDialogSubscription`, `useNatsDialogSubscription` |
+| **UI Utilities** | `useCollapsible`, `useCloseOnNavigation`, `useChatCardItem` |
+| **Chat Core** | `useChat`, `useSSE`, `useChatIdentity`, `useChatAttachments`, `useChatAttachmentImageGallery`, `useSlashCommands` |
+| **Transport Adapters** | `useSSEChatAdapter`, `useNatsChatAdapter` |
+| **Unified Surface** | `useUnifiedChat` (primary), `useEmbeddedChat` (legacy SSE alias) |
+| **Image Proxy** | `useProxiedImageUrl` |
 
 ## Usage Example
 
 ```typescript
-// Import individual hooks as needed
-import { useChunkCatchup, useNatsDialogSubscription, useRealtimeChunkProcessor } from './hooks'
-
-function RealtimeComponent() {
-  const { catchup, isLoading } = useChunkCatchup()
-  const { subscribe, unsubscribe, messages } = useNatsDialogSubscription()
-  const { processChunk, queueSize } = useRealtimeChunkProcessor()
-
-  // Use hooks for real-time data processing
-  return (
-    <div>
-      {/* Component implementation */}
-    </div>
-  )
+// Typical consumer — import directly from the module index
+import {
+  useUnifiedChat,
+  useChatAttachments,
+  useSlashCommands,
+} from '@flamingo/chat-hooks'
+
+function ChatPanel({ modes, activeMode }) {
+  const chat = useUnifiedChat({ modes, activeMode })
+  const attachments = useChatAttachments()
+  const slashCommands = useSlashCommands()
+
+  // ...
+}
+
+// Advanced: direct transport access
+import { useNatsChatAdapter } from '@flamingo/chat-hooks'
+
+function CustomTransportPanel() {
+  const nats = useNatsChatAdapter({ /* config */ })
+  // ...
 }
 ```
 
-This barrel export pattern allows for clean imports while maintaining separation of concerns across different real-time processing capabilities in the Flamingo/OpenFrame platform.
+## Notes
+
+- Marked `'use client'` — safe for React Server Component trees; hooks run only on the client.
+- `useUnifiedChat` is the recommended entry point for new consumers; `useEmbeddedChat` is the legacy SSE alias kept for backward compatibility.
+- `useProxiedImageUrl` reads proxy config from `ChatRuntime.endpoints`, keeping image-proxy resolution consistent between hub and embedder environments.

package/src/components/chat/hooks/.use-chat-attachment-image-gallery.md

@@ -0,0 +1,51 @@
+<!-- source-hash: 129697fa517b38437fd6fa76813ba652 -->
+Provides a React hook that enables click-to-expand image gallery functionality for chat attachment images within a chat thread panel.
+
+## Key Components
+
+### `useChatAttachmentImageGallery()`
+Primary export. Returns `{ panelRef, modal }`:
+- **`panelRef`** — `RefObject<HTMLDivElement>` to attach to the chat content wrapper; installs a delegated `click` listener
+- **`modal`** — JSX element (`ImageGalleryModal`) rendered when open, or `null` when closed (enabling React garbage collection of blob URLs)
+
+### `GalleryState` (interface)
+Internal state shape: `{ isOpen: boolean, images: string[], initialIndex: number }`
+
+### `absolutize(prefix: string)` (internal)
+Normalizes relative URL prefixes (e.g. `/api/storage/view/`) to absolute URLs for reliable comparison against browser-resolved `<img>.src` values.
+
+## Usage Example
+
+```typescript
+// In a chat panel host component
+export function ChatPanel() {
+  const { panelRef, modal } = useChatAttachmentImageGallery()
+
+  return (
+    <>
+      {/* panelRef wraps the scrollable message list */}
+      <div ref={panelRef} className="chat-thread-wrapper">
+        {/* ...message bubbles rendered here... */}
+      </div>
+
+      {/* modal renders outside overflow-hidden bubbles */}
+      {modal}
+    </>
+  )
+}
+```
+
+## Click Delegation Flow
+
+```mermaid
+graph TD
+    Click["Click Event"] --> ImgCheck{"img src starts\nwith viewUrlPrefix?"}
+    ImgCheck -->|No| Ignore["Ignore click"]
+    ImgCheck -->|Yes| BubbleWalk["Walk up to\n[data-message-role]"]
+    BubbleWalk --> NoBubble{"Bubble found?"}
+    NoBubble -->|No| SingleImg["Open modal with\nsingle image"]
+    NoBubble -->|Yes| Collect["Collect all matching\nimgs in bubble (DOM order)"]
+    Collect --> OpenModal["Open ImageGalleryModal\nwith computed initialIndex"]
+```
+
+> **Note:** The hook filters `<img>` elements by `attachmentViewUrlPrefix` from the chat runtime context, ensuring avatar and UI images are never intercepted.

package/src/components/chat/hooks/.use-chat-attachments.md

@@ -0,0 +1,48 @@
+<!-- source-hash: aa7997b65102b2c65fd293fc9f3faa3d -->
+Manages the upload state machine for chat file attachments, handling multi-file staging, magic-byte MIME validation, progress tracking, and per-file abort control before sending messages.
+
+## Key Components
+
+### `StagedAttachment`
+Internal state shape for each file in the upload pipeline. Tracks `id`, `file`, `status` (`sniffing | uploading | ready | error`), `progress` (0–100), `storagePath`, `viewToken`, and `errorMessage`.
+
+### `uploadWithProgress(url, file, token, onProgress?, signal?)`
+Inline XHR helper that PUTs file bytes to a Supabase signed URL. Maps raw network progress to the 10–95 range, supports `AbortSignal` cancellation, and handles timeout/error/abort events with proper cleanup.
+
+### `useChatAttachments()`
+Primary hook exposing `UseChatAttachmentsApi`:
+
+| Member | Description |
+|---|---|
+| `attachments` | Full staged array with state-machine metadata |
+| `readyAttachments` | Wire-format `ChatAttachment[]` for `sendMessage` |
+| `hasInflightUploads` | `true` while any upload is in-progress (disables Send) |
+| `addFiles(files)` | Stages and begins uploading files; deduplicates by `(name, size, lastModified)` |
+| `removeAttachment(id)` | Aborts in-flight XHR and removes the file |
+| `clear()` | Aborts all controllers and resets state |
+
+## Usage Example
+
+```typescript
+const {
+  attachments,
+  readyAttachments,
+  hasInflightUploads,
+  addFiles,
+  removeAttachment,
+  clear,
+} = useChatAttachments()
+
+// Stage files from an input element
+const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
+  if (e.target.files) addFiles(e.target.files)
+}
+
+// Pass ready attachments when sending
+await sendMessage(text, { pendingAttachments: readyAttachments })
+
+// Abort a specific upload mid-flight
+removeAttachment(attachmentId)
+```
+
+> **Security note:** Files are validated via magic-byte sniffing (`file-type`) before upload, rejecting extension spoofs (e.g. `evil.exe` renamed `screenshot.png`). The sniffed MIME — not `file.type` — is sent to the server for URL minting.

package/src/components/chat/hooks/.use-chat-card-item.md

@@ -0,0 +1,39 @@
+<!-- source-hash: 4c8bb965154478fda34b9e6e30abb929 -->
+Fetches a fully-mapped content item for an inline chat card by reusing the same list-API endpoint as public-facing pages (`/blog`, `/podcasts`, `/roadmap`, etc.), ensuring a single source of truth for item shape and joins.
+
+## Key Components
+
+### `useChatCardItem<T>(type, id)`
+Primary hook. Builds the list URL via `runtime.endpoints.buildListUrl`, fires a TanStack Query fetch, and returns the matched item. Deduplicated by `['chat-card-item', type, id]` query key — multiple references to the same `(type, id)` within one chat message produce a single network request. `refetchOnWindowFocus` is disabled to avoid wasteful re-fetches as the chat panel is toggled.
+
+### `extractItems(data)`
+Normalizes heterogeneous API response shapes (`{ items }`, `{ posts }`, `{ campaigns }`, `{ completed, inProgress }`, `{ data }`, or bare arrays) into a flat `unknown[]`. Single normalization point for all content types.
+
+### `extractItemId(type, item)`
+Resolves the primary key from a fetched item, handling both `id` and `external_id` fields for ClickUp-backed types (`roadmap_item`, `delivery_item`, `internal_task`).
+
+### `UseChatCardItemResult<T>`
+Return type interface exposing `item`, `isLoading`, and `isError`.
+
+## Usage Example
+
+```typescript
+import { useChatCardItem } from './use-chat-card-item'
+
+interface BlogPost {
+  id: string
+  title: string
+  author: string
+}
+
+function ChatBlogCard({ id }: { id: string }) {
+  const { item, isLoading, isError } = useChatCardItem<BlogPost>('post', id)
+
+  if (isLoading) return <Spinner />
+  if (isError || !item) return <ErrorCard />
+
+  return <BlogCardPreview title={item.title} author={item.author} />
+}
+```
+
+> **Runtime dependency:** The hook reads `runtime.endpoints.buildListUrl` from `ChatRuntimeContext`. Hub environments wire the registry-driven builder directly; embedded apps supply a per-type URL builder pointing at the reverse proxy.

package/src/components/chat/hooks/.use-chat-identity.md

@@ -0,0 +1,45 @@
+<!-- source-hash: b3bbee124a5b530f9a19e9b047eec040 -->
+Fetches and surfaces the current chat session's identity tier (`authTier`, `source`, `attachmentsEnabled`, `user`) via a lightweight `useEffect`/`useState` hook — no client-side cache by design.
+
+## Key Components
+
+### Interfaces
+
+- **`ChatIdentityResponse`** — Wire shape mirroring the hub's `/api/auth/identity` route response. Includes `authTier` (`'session' | 'bearer-act-as' | 'anon'`), `source`, `attachmentsEnabled` (server-computed), and a nullable `user` object with optional `firstName`, `lastName`, and `avatarUrl`.
+- **`ChatIdentitySurface`** — Extends `ChatIdentityResponse` with an `isLoading` boolean for skeleton/spinner states.
+
+### Hook
+
+- **`useChatIdentity()`** — Reads the identity endpoint URL from `useRequiredChatRuntime()`, fires an authenticated fetch via `chatAuthedFetch`, and returns identity data merged with `isLoading`. Falls back to `ANON_DEFAULTS` on errors or non-OK responses — never throws.
+
+### Constants
+
+- **`ANON_DEFAULTS`** — Safe fallback (`authTier: 'anon'`, `attachmentsEnabled: false`, `user: null`) used during loading and on any fetch failure.
+
+## Usage Example
+
+```typescript
+import { useChatIdentity } from './use-chat-identity'
+
+function AttachmentButton() {
+  const { isLoading, attachmentsEnabled, user } = useChatIdentity()
+
+  if (isLoading) return <Spinner />
+  if (!attachmentsEnabled) return null
+
+  return (
+    <button>
+      Attach file {user?.firstName ? `(${user.firstName})` : ''}
+    </button>
+  )
+}
+```
+
+## Design Notes
+
+| Concern | Decision |
+|---|---|
+| Caching | None — avoids stale identity across credential rotations |
+| Error handling | Falls back to anon defaults; never throws |
+| Credential changes | Re-fetches automatically when `proxyEmail` (from `localStorage`) changes |
+| `attachmentsEnabled` | Computed server-side; consumers read it directly without combining fields |

package/src/components/chat/hooks/.use-chat.md

@@ -0,0 +1,58 @@
+<!-- source-hash: c1d1e8fb922837f8d57888644f4624f5 -->
+Manages the client-side chat state for an AI assistant conversation, handling message streaming, tool approval workflows, and adaptive thinking display via SSE.
+
+## Key Components
+
+### `UseChatOptions`
+Configuration interface for the hook:
+- `useMock` / `debugMode` — toggle mock/debug SSE modes
+- `assistantName` / `assistantAvatar` — customize assistant identity
+- `streamFn` — override default SSE transport with a custom function
+- `initialMessages` — seed conversation state (e.g., from `localStorage`)
+- `onMessagesChange` — persistence callback triggered on every message update
+
+### `useChat(options)`
+Primary hook returning:
+
+| Return Value | Type | Description |
+|---|---|---|
+| `messages` | `Message[]` | Full conversation history |
+| `isTyping` | `boolean` | True until first text chunk arrives |
+| `isStreaming` | `boolean` | True while SSE stream is active |
+| `sseError` | `Error \| null` | Stream-level error state |
+| `sendMessage` | `fn` | Send a user turn, optionally hidden |
+| `abort` | `fn` | Cancel the active stream |
+| `reset` | `fn` | Reset SSE state |
+
+### `sendMessage(text, extra?, options?)`
+Appends a user message, creates an optimistic assistant placeholder, then iterates the SSE stream, handling three segment types:
+- **`text`** — accumulates into the last assistant message
+- **`thinking`** — prepended as a thinking card (always before answer text)
+- **`approval_request`** — renders a tool-approval card with `onApprove`/`onReject` callbacks
+- **`decision_resolved`** — flips approval card status and appends a receipt to the current turn
+
+## Usage Example
+
+```typescript
+import { useChat } from './use-chat'
+
+function ChatWidget() {
+  const { messages, isTyping, sendMessage, abort } = useChat({
+    assistantName: 'Mingo',
+    initialMessages: JSON.parse(localStorage.getItem('chat') ?? '[]'),
+    onMessagesChange: (msgs) => localStorage.setItem('chat', JSON.stringify(msgs)),
+    streamFn: myCustomStreamFn, // optional: bypass default SSE
+  })
+
+  return (
+    <div>
+      {messages.map((m) => <MessageBubble key={m.id} message={m} />)}
+      {isTyping && <TypingIndicator />}
+      <button onClick={() => sendMessage('Hello!')}>Send</button>
+      <button onClick={abort}>Stop</button>
+    </div>
+  )
+}
+```
+
+> **Hidden turns**: Pass `{ hidden: true }` to `sendMessage` for post-approval auto-continuation — the user message is added to LLM context but not rendered in the UI, keeping the visible thread clean.