@flamingo-stack/openframe-frontend-core 0.0.204 → 0.0.205

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

@@ -0,0 +1,114 @@
+'use client'
+
+/**
+ * Click-to-expand handler for chat-attachment images in the chat thread.
+ *
+ * Returns `{ panelRef, modal }`:
+ *   - `panelRef` — attach to the chat content wrapper. The hook
+ *     installs a delegated `click` listener on this ref.
+ *   - `modal` — render as a sibling of the chat panel (so it lives
+ *     OUTSIDE any overflow-hidden message bubbles). Returns `null`
+ *     while closed.
+ *
+ * Behavior on click:
+ *   1. Filter for `<img>` whose `src` starts with the runtime's
+ *      `attachmentViewUrlPrefix` (so non-chat images don't intercept).
+ *   2. Walk up to the nearest `[data-message-role]` ancestor — the
+ *      boundary the chat-shell wraps each message bubble with.
+ *   3. Collect ALL chat-attachment `<img>`s inside that boundary in
+ *      DOM order. Compute the clicked index for `initialIndex`.
+ *   4. Open `ImageGalleryModal` (UI-Kit, also used by
+ *      `roadmap-card.tsx` for screenshot expansion).
+ *
+ * The hook deliberately owns the click DOM-walk + modal state so
+ * the host component consumes a single `{panelRef, modal}` API.
+ */
+
+import { useCallback, useEffect, useRef, useState } from 'react'
+import { ImageGalleryModal } from '../../ui/image-gallery-modal'
+import { useRequiredChatRuntime } from '../../../contexts/chat-runtime-context'
+
+interface GalleryState {
+  isOpen: boolean
+  images: string[]
+  initialIndex: number
+}
+
+const CLOSED: GalleryState = { isOpen: false, images: [], initialIndex: 0 }
+
+export function useChatAttachmentImageGallery() {
+  const runtime = useRequiredChatRuntime()
+  const viewUrlPrefix = runtime.endpoints.attachmentViewUrlPrefix
+  const panelRef = useRef<HTMLDivElement | null>(null)
+  const [state, setState] = useState<GalleryState>(CLOSED)
+
+  const handleClose = useCallback(() => setState(CLOSED), [])
+
+  useEffect(() => {
+    const root = panelRef.current
+    if (!root) return
+
+    const onClick = (ev: Event) => {
+      const target = ev.target as HTMLElement | null
+      if (!target) return
+      // Match an <img> whose `src` starts with the proxy URL prefix.
+      const img = target.closest('img') as HTMLImageElement | null
+      if (!img || !img.src.startsWith(absolutize(viewUrlPrefix))) return
+
+      // Walk up to the message-bubble boundary.
+      const bubble = img.closest('[data-message-role]')
+      if (!bubble) {
+        // Fallback: open the modal with just the clicked image.
+        ev.preventDefault()
+        setState({ isOpen: true, images: [img.src], initialIndex: 0 })
+        return
+      }
+
+      // Collect all chat-attachment images inside this bubble in DOM
+      // order. The `closest` lookup matched img.src.startsWith already,
+      // but we re-check below because `querySelectorAll` returns ALL
+      // <img>s in the bubble (avatar images etc.).
+      const allImgs = Array.from(bubble.querySelectorAll('img')) as HTMLImageElement[]
+      const matching = allImgs.filter((el) => el.src.startsWith(absolutize(viewUrlPrefix)))
+      if (matching.length === 0) return
+
+      const idx = Math.max(0, matching.indexOf(img))
+      ev.preventDefault()
+      setState({
+        isOpen: true,
+        images: matching.map((el) => el.src),
+        initialIndex: idx,
+      })
+    }
+
+    root.addEventListener('click', onClick)
+    return () => root.removeEventListener('click', onClick)
+  }, [viewUrlPrefix])
+
+  // `ImageGalleryModal` doesn't accept `null` for `images` — render
+  // it only when open. Closing returns `null` so the modal unmounts
+  // and React garbage-collects any blob URLs it might hold.
+  const modal = state.isOpen ? (
+    <ImageGalleryModal
+      images={state.images}
+      isOpen={state.isOpen}
+      onClose={handleClose}
+      initialIndex={state.initialIndex}
+    />
+  ) : null
+
+  return { panelRef, modal }
+}
+
+/** Absolutize a prefix for comparison against `<img>.src`. Browsers
+ *  resolve `<img src="/api/storage/view/...">` to an absolute URL when
+ *  reading `.src` — we need the same shape on the prefix to match.
+ *
+ *  Embedded apps that supply an absolute prefix already work as-is
+ *  (the prefix matches `.src` directly). For relative prefixes (host
+ *  mode), prefix with `window.location.origin`. */
+function absolutize(prefix: string): string {
+  if (prefix.startsWith('http://') || prefix.startsWith('https://')) return prefix
+  if (typeof window === 'undefined') return prefix
+  return `${window.location.origin}${prefix.startsWith('/') ? '' : '/'}${prefix}`
+}

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

@@ -0,0 +1,429 @@
+'use client'
+
+/**
+ * Chat-attachment upload state machine.
+ *
+ * Multi-file state (precedent: hub `components/blog/image-upload-manager.tsx`).
+ * Magic-byte sniff via `file-type` BEFORE upload (rejects extension
+ * spoofs like `evil.exe` renamed `screenshot.png`). Per-attachment
+ * `AbortController` for clean remove-mid-upload.
+ *
+ * Auth propagation:
+ *   - `chatAuthedFetch` carries bearer-act-as headers + Supabase
+ *     session cookies — used both for minting the upload URL and as
+ *     the auth path before falling through to the signed PUT.
+ *   - The byte-PUT to the signed URL uses an inline `uploadWithProgress`
+ *     XHR helper (ported from the hub `unified-upload-service`) so the
+ *     lib-side chat hook is self-contained.
+ *
+ * URL endpoint: `runtime.endpoints.attachmentUploadUrl` (hub default
+ * `/api/storage/generate-upload-url`). Embedded apps override.
+ *
+ * Dedup: files keyed by `(name, size, lastModified)` — second pick of
+ * the same file is silently ignored.
+ */
+
+import { useCallback, useMemo, useRef, useState } from 'react'
+import { fileTypeFromBlob } from 'file-type'
+import { useRequiredChatRuntime } from '../../../contexts/chat-runtime-context'
+import { chatAuthedFetch } from '../utils/chat-authed-fetch'
+import {
+  CHAT_ATTACHMENT_MIME_TYPES,
+  CHAT_ATTACHMENT_CONCURRENT_UPLOADS_PER_USER,
+} from '../chat-attachment-bar'
+import type { ChatAttachment } from '../utils/chat-attachment-markdown'
+
+// ---------------------------------------------------------------------------
+// Inlined hub-side constants (single source of truth — `lib/config/
+// chat-attachment-config.ts` on the hub). Hard-coded here so the lib
+// hook is self-contained; if hub-side bumps the cap, update both.
+// ---------------------------------------------------------------------------
+
+const CHAT_ATTACHMENTS_BUCKET = 'chat-attachments'
+const CHAT_ATTACHMENTS_FOLDER = 'chat'
+const CHAT_ATTACHMENT_MAX_SIZE_BYTES = 25 * 1024 * 1024
+
+/** Cache-Control header for content-addressed uploads — Storage paths
+ *  embed `{timestamp}-{random}-{filename}` so a given URL is immutable. */
+const STORAGE_CACHE_CONTROL_IMMUTABLE = 'public, max-age=31536000, immutable'
+
+type Status = 'sniffing' | 'uploading' | 'ready' | 'error'
+
+/** Internal staged-attachment shape (more fields than the wire
+ *  `ChatAttachment` — carries state-machine metadata). */
+export interface StagedAttachment {
+  /** Stable client-side id; survives across re-renders. */
+  id: string
+  file: File
+  status: Status
+  /** Set when `status === 'ready'`. Server-issued. */
+  storagePath?: string
+  /** Set when `status === 'ready'`. Server-issued HMAC view token. */
+  viewToken?: string
+  /** 0-100 during 'uploading'. */
+  progress: number
+  /** Set when `status === 'error'`. */
+  errorMessage?: string
+}
+
+/** Response shape from `/api/storage/generate-upload-url`. */
+interface UploadUrlResponse {
+  uploadUrl: string
+  filePath: string
+  token: string
+  bucket: string
+  publicUrl: string | null
+  viewToken: string | null
+}
+
+interface UseChatAttachmentsApi {
+  attachments: StagedAttachment[]
+  /** All staged files in 'ready' state, projected to the wire
+   *  `ChatAttachment` shape — pass to `sendMessage`'s `pendingAttachments`. */
+  readyAttachments: ChatAttachment[]
+  /** True iff any attachment is mid-upload — Send button reads this
+   *  to disable itself. */
+  hasInflightUploads: boolean
+  addFiles: (files: FileList | File[]) => void
+  removeAttachment: (id: string) => void
+  clear: () => void
+}
+
+/**
+ * Inline `uploadWithProgress` — XHR PUT to a Supabase signed-upload URL
+ * with progress + abort support. Ported verbatim from the hub
+ * `unified-upload-service.ts`. Maps the XHR 0-100 to the caller's 10-95
+ * range (leaving 0-10 for the mint + 95-100 for state transitions).
+ *
+ * AbortSignal wiring: `signal?.addEventListener('abort', () => xhr.abort())`
+ * — without this, calling `removeAttachment`/`clear()` aborts the
+ * controller but the XHR runs to completion and bytes still land in
+ * Supabase.
+ */
+function uploadWithProgress(
+  url: string,
+  file: File,
+  token: string,
+  onProgress?: (progress: number) => void,
+  signal?: AbortSignal,
+): Promise<void> {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(new Error('Upload cancelled'))
+      return
+    }
+    const xhr = new XMLHttpRequest()
+    let isCompleted = false
+
+    const cleanup = () => {
+      if (isCompleted) return
+      isCompleted = true
+      xhr.upload.removeEventListener('progress', handleProgress)
+      xhr.removeEventListener('load', handleLoad)
+      xhr.removeEventListener('error', handleError)
+      xhr.removeEventListener('abort', handleAbort)
+      xhr.removeEventListener('timeout', handleTimeout)
+      signal?.removeEventListener('abort', handleSignalAbort)
+      if (xhr.readyState !== XMLHttpRequest.DONE) xhr.abort()
+    }
+
+    const handleProgress = (event: ProgressEvent) => {
+      if (event.lengthComputable && onProgress) {
+        // Map 0-100 of network progress to 10-95.
+        const pct = 10 + (event.loaded / event.total) * 85
+        onProgress(Math.round(pct))
+      }
+    }
+
+    const handleLoad = () => {
+      cleanup()
+      if (xhr.status >= 200 && xhr.status < 300) {
+        resolve()
+      } else {
+        reject(
+          new Error(
+            `Upload failed with status ${xhr.status}: ${xhr.responseText || xhr.statusText}`,
+          ),
+        )
+      }
+    }
+
+    const handleError = () => {
+      cleanup()
+      reject(new Error('Network error during upload'))
+    }
+    const handleAbort = () => {
+      cleanup()
+      reject(new Error('Upload cancelled'))
+    }
+    const handleTimeout = () => {
+      cleanup()
+      reject(new Error('Upload timed out'))
+    }
+    const handleSignalAbort = () => {
+      xhr.abort()
+    }
+    signal?.addEventListener('abort', handleSignalAbort, { once: true })
+
+    xhr.upload.addEventListener('progress', handleProgress)
+    xhr.addEventListener('load', handleLoad)
+    xhr.addEventListener('error', handleError)
+    xhr.addEventListener('abort', handleAbort)
+    xhr.addEventListener('timeout', handleTimeout)
+
+    xhr.open('PUT', url)
+    xhr.setRequestHeader('Authorization', `Bearer ${token}`)
+    // `x-upsert: true` — signed upload tokens can target the same path
+    // more than once on retry; without this header, Storage returns 409
+    // on the second attempt instead of overwriting.
+    xhr.setRequestHeader('x-upsert', 'true')
+    xhr.setRequestHeader('Content-Type', file.type)
+    xhr.setRequestHeader('cache-control', STORAGE_CACHE_CONTROL_IMMUTABLE)
+    xhr.timeout = 30 * 60 * 1000
+    xhr.send(file)
+  })
+}
+
+export function useChatAttachments(): UseChatAttachmentsApi {
+  const runtime = useRequiredChatRuntime()
+  const uploadUrlEndpoint = runtime.endpoints.attachmentUploadUrl
+
+  const [attachments, setAttachments] = useState<StagedAttachment[]>([])
+  // AbortControllers indexed by attachment id. Survives re-renders.
+  const controllersRef = useRef<Map<string, AbortController>>(new Map())
+
+  const updateOne = useCallback((id: string, patch: Partial<StagedAttachment>) => {
+    setAttachments((prev) => prev.map((a) => (a.id === id ? { ...a, ...patch } : a)))
+  }, [])
+
+  const removeAttachment = useCallback((id: string) => {
+    // Abort any in-flight work for this attachment.
+    const ctrl = controllersRef.current.get(id)
+    if (ctrl) {
+      ctrl.abort()
+      controllersRef.current.delete(id)
+    }
+    setAttachments((prev) => prev.filter((a) => a.id !== id))
+  }, [])
+
+  const clear = useCallback(() => {
+    for (const ctrl of controllersRef.current.values()) ctrl.abort()
+    controllersRef.current.clear()
+    setAttachments([])
+  }, [])
+
+  const uploadOne = useCallback(
+    async (att: StagedAttachment) => {
+      const ctrl = controllersRef.current.get(att.id)
+      try {
+        // 1. Magic-byte sniff. The `file` ARG is a Blob; `fileTypeFromBlob`
+        //    reads the first few KB. Rejects extension spoofs.
+        let sniffed: { mime: string } | undefined
+        try {
+          sniffed = await fileTypeFromBlob(att.file)
+        } catch (err) {
+          if (ctrl?.signal.aborted) return
+          throw new Error(
+            `Could not read file content: ${err instanceof Error ? err.message : String(err)}`,
+          )
+        }
+        if (ctrl?.signal.aborted) return
+        if (!sniffed) {
+          throw new Error('Unrecognized file format')
+        }
+        const actualMime = sniffed.mime
+        if (!(CHAT_ATTACHMENT_MIME_TYPES as readonly string[]).includes(actualMime)) {
+          throw new Error(
+            `File type "${actualMime}" is not allowed. ` +
+              `Allowed: ${CHAT_ATTACHMENT_MIME_TYPES.join(', ')}`,
+          )
+        }
+
+        // 2. Move to 'uploading' and POST the URL-mint request with
+        //    bearer-act-as headers (if present).
+        updateOne(att.id, { status: 'uploading', progress: 5 })
+
+        const urlResp = await chatAuthedFetch(uploadUrlEndpoint, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          signal: ctrl?.signal,
+          body: JSON.stringify({
+            fileName: att.file.name,
+            // Pass the SNIFFED MIME (not `file.type`, which can be a
+            // user-supplied lie) so the server's MIME pre-validation
+            // matches reality.
+            fileType: actualMime,
+            bucket: CHAT_ATTACHMENTS_BUCKET,
+            folder: CHAT_ATTACHMENTS_FOLDER,
+          }),
+        })
+
+        if (!urlResp.ok) {
+          const errBody = await urlResp.json().catch(() => ({}))
+          throw new Error(errBody.error || `Failed to mint upload URL: ${urlResp.statusText}`)
+        }
+
+        const mintData = (await urlResp.json()) as UploadUrlResponse
+        if (!mintData.viewToken) {
+          throw new Error('Server did not return a viewToken for the chat-attachments bucket')
+        }
+
+        // 3. PUT the bytes via inline `uploadWithProgress`.
+        await uploadWithProgress(
+          mintData.uploadUrl,
+          att.file,
+          mintData.token,
+          (pct) => {
+            updateOne(att.id, { progress: pct })
+          },
+          ctrl?.signal,
+        )
+
+        if (ctrl?.signal.aborted) return
+
+        // 4. Mark ready.
+        updateOne(att.id, {
+          status: 'ready',
+          progress: 100,
+          storagePath: mintData.filePath,
+          viewToken: mintData.viewToken,
+        })
+      } catch (err) {
+        if (ctrl?.signal.aborted) return
+        const message = err instanceof Error ? err.message : String(err)
+        updateOne(att.id, { status: 'error', progress: 0, errorMessage: message })
+      } finally {
+        controllersRef.current.delete(att.id)
+      }
+    },
+    [uploadUrlEndpoint, updateOne],
+  )
+
+  // `attachmentsRef` mirrors the staged set for SYNCHRONOUS reads
+  // during `addFiles`. Two assignment sites keep it in lockstep:
+  //   (a) `attachmentsRef.current = attachments` after every render —
+  //       picks up state mutations from `updateOne` / `removeAttachment`
+  //       / `clear`.
+  //   (b) `attachmentsRef.current = [...attachmentsRef.current,
+  //       ...additions]` INSIDE `addFiles` BEFORE `setAttachments`
+  //       commits — guarantees a SECOND `addFiles` call in the same
+  //       tick sees the first call's additions for dedup.
+  const attachmentsRef = useRef<StagedAttachment[]>([])
+  attachmentsRef.current = attachments
+
+  const addFiles = useCallback(
+    (files: FileList | File[]) => {
+      const arr = Array.from(files)
+      if (arr.length === 0) return
+
+      // Compute additions OUTSIDE the setState updater — the updater
+      // must be a pure function. React 18 StrictMode invokes updaters
+      // TWICE in dev; concurrent transitions can do the same in prod.
+      // If side effects (UUID gen, controllerRef.set, uploadOne) lived
+      // inside, each render double-fired the upload.
+      const prev = attachmentsRef.current
+      const seen = new Set(
+        prev.map((a) => `${a.file.name}|${a.file.size}|${a.file.lastModified}`),
+      )
+      const additions: StagedAttachment[] = []
+      // `error`-status chips don't count toward the cap — they're
+      // visual diagnostics, not active uploads. Without this filter
+      // a single oversized-file mistake would block the user from
+      // adding further files until they manually `×` the error chip.
+      const remainingSlots = Math.max(
+        0,
+        CHAT_ATTACHMENT_CONCURRENT_UPLOADS_PER_USER -
+          prev.filter((a) => a.status !== 'error').length,
+      )
+      for (const file of arr) {
+        if (additions.length >= remainingSlots) break
+        const key = `${file.name}|${file.size}|${file.lastModified}`
+        if (seen.has(key)) continue
+
+        // Size pre-check — server-side bucket policy is the
+        // authoritative gate, but rejecting here saves the user a
+        // round-trip on obviously-too-big files.
+        if (file.size > CHAT_ATTACHMENT_MAX_SIZE_BYTES) {
+          additions.push({
+            id: crypto.randomUUID(),
+            file,
+            status: 'error',
+            progress: 0,
+            errorMessage: `File too large (${(file.size / 1024 / 1024).toFixed(1)} MB; max 25 MB)`,
+          })
+          seen.add(key)
+          continue
+        }
+
+        additions.push({
+          id: crypto.randomUUID(),
+          file,
+          status: 'sniffing',
+          progress: 0,
+        })
+        seen.add(key)
+      }
+
+      if (additions.length === 0) return
+
+      // SYNCHRONOUSLY update the ref BEFORE the React commit. Without
+      // this, a second `addFiles` call in the SAME tick (paste-then-drop
+      // browser event sequence; touch-then-mouse on iOS hybrid; double
+      // user clicks on the chip-strip's hidden file input) would read
+      // the same stale `attachmentsRef.current` and bypass dedup.
+      attachmentsRef.current = [...prev, ...additions]
+
+      // Register AbortControllers + kick off uploads BEFORE the state
+      // commit. The XHR doesn't depend on React state; `uploadOne`'s
+      // `updateOne` calls are queued behind this `setAttachments`,
+      // so by the time the first progress callback fires React has
+      // already rendered the new chips.
+      for (const a of additions) {
+        if (a.status === 'sniffing') {
+          const ctrl = new AbortController()
+          controllersRef.current.set(a.id, ctrl)
+          void uploadOne(a)
+        }
+      }
+
+      // Pure updater — no side effects, idempotent under StrictMode
+      // double-invocation.
+      setAttachments((p) => [...p, ...additions])
+    },
+    [uploadOne],
+  )
+
+  // Memoized so `handleSend`'s `useCallback([readyAttachments, ...])`
+  // doesn't re-create the handler (and re-render `ChatInput`) on every
+  // unrelated re-render. Stable reference while the underlying
+  // attachments array is unchanged.
+  const readyAttachments: ChatAttachment[] = useMemo(
+    () =>
+      attachments
+        .filter(
+          (a): a is StagedAttachment & { storagePath: string; viewToken: string } =>
+            a.status === 'ready' && !!a.storagePath && !!a.viewToken,
+        )
+        .map((a) => ({
+          storagePath: a.storagePath,
+          viewToken: a.viewToken,
+          contentType: a.file.type,
+          fileName: a.file.name,
+          size: a.file.size,
+        })),
+    [attachments],
+  )
+
+  const hasInflightUploads = attachments.some(
+    (a) => a.status === 'sniffing' || a.status === 'uploading',
+  )
+
+  return {
+    attachments,
+    readyAttachments,
+    hasInflightUploads,
+    addFiles,
+    removeAttachment,
+    clear,
+  }
+}

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

@@ -0,0 +1,102 @@
+'use client'
+
+/**
+ * useChatCardItem — fetches the full mapped item for an inline chat
+ * card via the SAME list-API endpoint the public pages use.
+ *
+ * Single source of truth: no parallel `buildImageUrl` / `buildMetadata`
+ * synthesis. The chat renders the same shape, with the same joins
+ * (author / categories / platforms / hosts / etc.), as `/blog`,
+ * `/case-studies`, `/podcasts`, `/roadmap`, etc.
+ *
+ * Batching: every compact card with the same `(type, id)` shares one
+ * TanStack-Query entry; multiple refs of the same type in the same
+ * chat message produce ONE network request (TanStack dedups by
+ * queryKey). 5-minute staleTime matches `RelatedContentSection`.
+ *
+ * URL builder is read from `runtime.endpoints.buildListUrl` so the
+ * embedded app can supply a per-type URL builder against the reverse
+ * proxy; the hub wires the registry-driven builder directly.
+ */
+
+import { useQuery } from '@tanstack/react-query'
+import { useRequiredChatRuntime } from '../../../contexts/chat-runtime-context'
+
+export interface UseChatCardItemResult<T = unknown> {
+  item: T | undefined
+  isLoading: boolean
+  isError: boolean
+}
+
+/** Extract the items array from each endpoint's response shape (some
+ *  return `{ items }`, others `{ posts }`, etc.). Single normalization
+ *  point — callers always read `Item[]`. */
+function extractItems(data: unknown): unknown[] {
+  if (!data || typeof data !== 'object') return []
+  const obj = data as Record<string, unknown>
+  if (Array.isArray(obj.items)) return obj.items
+  if (Array.isArray(obj.posts)) return obj.posts
+  if (Array.isArray(obj.campaigns)) return obj.campaigns
+  if (Array.isArray(obj.completed) || Array.isArray(obj.inProgress)) {
+    // Delivery endpoint splits into completed/inProgress arrays — flatten.
+    const completed = Array.isArray(obj.completed) ? obj.completed : []
+    const inProgress = Array.isArray(obj.inProgress) ? obj.inProgress : []
+    return [...completed, ...inProgress]
+  }
+  if (Array.isArray(obj.data)) return obj.data
+  if (Array.isArray(data)) return data
+  return []
+}
+
+/** Extract a stable id from a fetched item — different shapes use
+ *  `id` vs `external_id`. Used by the chat loader to match the fetched
+ *  array element back to the marker's id. */
+function extractItemId(type: string, item: unknown): string | null {
+  if (!item || typeof item !== 'object') return null
+  const obj = item as Record<string, unknown>
+  if (type === 'roadmap_item' || type === 'delivery_item' || type === 'internal_task') {
+    const ext = obj.external_id
+    if (typeof ext === 'string') return ext
+  }
+  // RoadmapItem-shaped responses use `id` to carry the external_id; the
+  // mapper renames external_id→id at the API boundary. Treat both id and
+  // external_id as primary-key candidates for these clickup-backed types.
+  const id = obj.id
+  if (typeof id === 'string') return id
+  if (typeof id === 'number') return String(id)
+  return null
+}
+
+export function useChatCardItem<T = unknown>(
+  type: string,
+  id: string,
+): UseChatCardItemResult<T> {
+  // Read the list-URL builder from the chat runtime — hub uses the
+  // rag-table-config registry directly; embedded apps supply a per-type
+  // URL builder against the reverse proxy.
+  const runtime = useRequiredChatRuntime()
+  const url = runtime.endpoints.buildListUrl(type, [id])
+  const query = useQuery({
+    queryKey: ['chat-card-item', type, id],
+    queryFn: async (): Promise<T | null> => {
+      if (!url) return null
+      const res = await fetch(url)
+      if (!res.ok) return null
+      const data = await res.json()
+      const items = extractItems(data)
+      const match = items.find((it) => extractItemId(type, it) === id)
+      return (match ?? null) as T | null
+    },
+    enabled: !!url && id.length > 0,
+    // Don't refetch on window focus inside the chat — the chat panel
+    // is opened and closed frequently, and re-fetching every time the
+    // user toggles back to the tab is wasteful (the row's id-keyed
+    // payload is effectively immutable).
+    refetchOnWindowFocus: false,
+  })
+  return {
+    item: (query.data ?? undefined) as T | undefined,
+    isLoading: query.isLoading,
+    isError: query.isError,
+  }
+}