@flamingo-stack/openframe-frontend-core 0.0.212 → 0.0.213-snapshot.20260528174436

package/src/components/chat/entity-cards/.investor-update-card.md

@@ -0,0 +1,47 @@
+<!-- source-hash: 756619c21c965403499e06eb7fef94fa -->
+Pure presentation component for rendering investor update cards in two density modes (`default` and `sm`), with no internal click logic — callers supply the resolved `href`.
+
+## Key Components
+
+### `InvestorUpdateCard`
+Main card component. Renders differently based on the `size` prop:
+- **`default`** — delegates to `AdminContentCard` with image, title, summary, badges, and period meta
+- **`sm`** — compact horizontal layout using shared `COMPACT_CARD_*` utility classes
+
+### `InvestorUpdateCardSkeleton`
+Loading placeholder matching the visual footprint of each density mode. Uses `animate-pulse` for the default size.
+
+### `InvestorUpdateCardProps`
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `update` | `InvestorUpdate` | Entity data |
+| `href` | `string` | Resolved detail URL (caller-supplied) |
+| `target` | `'_blank'` | Optional new-tab behavior |
+| `placeholderUrl` | `string \| null` | OG fallback when `featured_image` is absent |
+| `size` | `'default' \| 'sm'` | Card density (defaults to `'default'`) |
+
+## Usage Example
+
+```typescript
+// Default density — full card
+<InvestorUpdateCard
+  update={investorUpdate}
+  href={`/investor-updates/${investorUpdate.slug}`}
+  placeholderUrl="/images/update-placeholder.png"
+/>
+
+// Compact horizontal — e.g. inside a chat dispatch or sidebar list
+<InvestorUpdateCard
+  update={investorUpdate}
+  href={`/investor-updates/${investorUpdate.slug}`}
+  target="_blank"
+  rel="noopener noreferrer"
+  size="sm"
+/>
+
+// Skeleton while data loads
+<InvestorUpdateCardSkeleton size="sm" />
+```
+
+> **Design note:** The component intentionally owns zero click/navigation logic. Tab behavior (`target="_blank"`) is resolved externally (e.g. via `computeIsNewTab`) and passed in, keeping the component fully declarative.

package/src/components/chat/entity-cards/.onboarding-guide-card.md

@@ -0,0 +1,58 @@
+<!-- source-hash: ecac941a52e178236e11d54fe42337ec -->
+Pure presentation component that renders an onboarding guide card in three layout variants — `catalog`, `default`, and `sm` — plus matching skeleton states for loading UI.
+
+## Key Components
+
+### `OnboardingGuideCard`
+Main card component. Stateless and click-logic-free; the caller wraps with navigation and provides the resolved `href`.
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `guide` | `OnboardingGuide` | Guide entity data |
+| `href` | `string` | Detail URL resolved by caller |
+| `target` | `'_blank'` | Optional new-tab behavior |
+| `size` | `'catalog' \| 'default' \| 'sm'` | Layout variant (default: `'default'`) |
+| `placeholderUrl` | `string \| null` | OG fallback image for catalog/sm |
+| `className` | `string` | Additional CSS classes |
+
+### `OnboardingGuideCardSkeleton`
+Loading placeholder that mirrors each layout variant's structure with animated pulse states.
+
+### `HORIZONTAL_SIZE_TOKENS`
+Internal token map for spacing/typography in the `default` variant.
+
+## Variants
+
+| Variant | Layout | Use Case |
+|---------|--------|----------|
+| `catalog` | Hero image + author grid | Public catalog page |
+| `default` | Horizontal step-numbered | "More in section" rail |
+| `sm` | Compact horizontal | Chat-inline rendering |
+
+## Usage Example
+
+```typescript
+import { OnboardingGuideCard, OnboardingGuideCardSkeleton } from './onboarding-guide-card'
+
+// Loading state
+if (isLoading) {
+  return <OnboardingGuideCardSkeleton size="catalog" />
+}
+
+// Catalog variant (public listing)
+<OnboardingGuideCard
+  guide={guide}
+  href={`/guides/${guide.slug}`}
+  size="catalog"
+  placeholderUrl={ogImageUrl}
+/>
+
+// Chat inline (sm variant, new tab)
+<OnboardingGuideCard
+  guide={guide}
+  href={`/guides/${guide.slug}`}
+  size="sm"
+  target="_blank"
+  rel="noopener noreferrer"
+/>
+```

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

@@ -0,0 +1,31 @@
+<!-- source-hash: 192500e77aad1a0a4024a9e7d8dfcfec -->
+Provides the lib-side default implementation of `buildProductReleaseCardProps` for chat dispatch, satisfying the three fields required by the compact (`size='sm'`) `<ProductReleaseCard>` variant without requiring hub-side extras.
+
+## Key Components
+
+### Interfaces
+- **`ReleaseLike`** — Loosely typed shape for raw API row data, covering image URLs, video URLs, and release date fields
+- **`DerivedSmProps`** — Output shape containing only the three sm-relevant props: `coverImage`, `hasVideoCover`, and `formattedDate`
+
+### Functions
+- **`pickCover(item)`** — Resolves the best cover image URL by mirroring the hub's `resolveReleaseCover` precedence: video thumbnails take priority when a video is set, falling back to `featured_image` then `og_image_url`
+- **`defaultBuildProductReleaseCardProps(item)`** — Main export; builds the `DerivedSmProps` bundle from an unknown API row, using `formatReleaseDate` for TZ-safe date formatting
+
+## Usage Example
+
+```typescript
+import { defaultBuildProductReleaseCardProps } from './product-release-card-defaults'
+
+// Used as fallback when opts.extras.buildProductReleaseCardProps is not supplied
+const props = defaultBuildProductReleaseCardProps(apiRow)
+// → { coverImage: 'https://...', hasVideoCover: true, formattedDate: 'Jan 15, 2025' }
+
+// Hub-side embedders override with their richer builder via extras:
+const cardProps = (opts.extras?.buildProductReleaseCardProps ?? defaultBuildProductReleaseCardProps)(row)
+```
+
+## Notes
+
+- Uses `formatReleaseDate` (not `new Date().toLocaleDateString`) to avoid UTC off-by-one day shifts on date-only `YYYY-MM-DD` strings
+- Produces an empty string for `formattedDate` when `release_date` is absent, rather than throwing
+- lg-only fields (`changelogCounts`, badge color, view count) are intentionally omitted — hub embedders supply those via `extras`

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.