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

package/src/components/tickets/.help-center-list.md

@@ -1,40 +1,51 @@
-<!-- source-hash: 827d4c23e1bcd10b78b97232f2822fa0 -->
-Renders the full Help Center surface for authenticated users, providing ticket listing, creation, filtering, pagination, and optimistic UI updates. Serves as the primary component mounted on the `/tickets` route in OpenFrame.
+<!-- source-hash: ec12c761ba72a6ce29047ad308561c0d -->
+Renders the full Help Center surface for the OpenFrame `/tickets` page, managing ticket listing, creation, optimistic updates, and drawer state via URL params.
 
 ## Key Components
 
-- **`HelpCenterList`** — Public entry point. Guards against unauthenticated access (renders skeleton during identity load, `EmptyState` for anon users), then delegates to `HelpCenterListAuthed`.
-- **`HelpCenterListAuthed`** — Internal component handling all authenticated state: merges optimistic + server tickets, manages expanded row, wires mutation callbacks, and composes the full page layout via `<DevSectionPage>`.
-- **`HelpCenterListProps`** — Accepts an optional `toast` override for testability.
-
-**Key hooks used:**
-- `useTicketsList` — fetches paginated tickets by `search`, `status`, `page`
-- `useTicketActions` — mutations (submit, close, reopen, send message) with optimistic callbacks
-- `useChatIdentity` — resolves session email/name; guards the auth gate
+### `HelpCenterList` (default export)
+Top-level component that gates rendering on auth state:
+- **Loading** → renders `DevSectionPage` with skeleton placeholders
+- **Anon** → renders a sign-in `EmptyState`
+- **Authed** → delegates to `HelpCenterListAuthed` with resolved session identity
+
+### `HelpCenterListAuthed` (internal)
+Core authenticated view handling:
+- **`useTicketsList`** — fetches paginated tickets from URL params (`?search=`, `?status=`, `?page=`); live-polls while a drawer is open
+- **`useTicketActions`** — mutation handlers with optimistic prepend/remove callbacks
+- **Optimistic state** — local `useState` (not TanStack cache) so pending placeholders survive refetches triggered by filter changes
+- **Drawer state** — derived from `?ticket=<external_id>` URL param; a single `setOpenTicket` callback reads/writes it via `router.replace`
+
+### `HelpCenterListProps`
+| Prop | Type | Description |
+|---|---|---|
+| `toast` | `typeof defaultToast` | Test-friendly toast override |
+| `backButton` | `{label?, href?} \| false` | Forwarded to `DevSectionPage` chrome |
+| `title` | `string` | Override hero title (e.g. `"Support Tickets"`) |
+| `shell` | `boolean` | Pass `false` when host layout provides the page container |
 
 ## Usage Example
 
 ```typescript
-// Mounted directly on the /tickets page (OpenFrame):
-import { HelpCenterList } from './help-center-list'
+// Standard mount on the /tickets route
+import { HelpCenterList } from '@openframe/lib'
 
 export default function TicketsPage() {
   return <HelpCenterList />
 }
 
-// With toast override for testing:
-import { mockToast } from '../test-utils'
-
-render(<HelpCenterList toast={mockToast} />)
+// Embedded in a custom host layout with overrides
+export default function SupportPage() {
+  return (
+    <HelpCenterList
+      title="Support Tickets"
+      backButton={{ label: 'Back to Dashboard', href: '/dashboard' }}
+      shell={false}
+    />
+  )
+}
 ```
 
-## State Model
-
-```text
-URL params        → search, status, page   (read by useTicketsList)
-optimisticTickets → local useState          (prepend on submit, remove on settle)
-expandedTicketId  → local useState          (single drawer open at a time)
-supportSystemDown → local useState          (disables create form on error)
-```
+> **Deep-linking:** Append `?ticket=<external_id>` to auto-open a specific ticket drawer on load. All open/close/share flows route through this single URL param.
 
-> **Note:** Optimistic placeholders are kept in local state (not the TanStack query cache) so URL filter changes don't discard in-flight submissions mid-render.
+**Source:** [`help-center-list.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/help-center-list.tsx)

package/src/components/tickets/.index.md

@@ -1,65 +1,50 @@
-<!-- source-hash: 9ab6eac897ae7fbb7ae6454201513bed -->
-Barrel export file for the tickets feature module, re-exporting all public components, hooks, and types related to ticket management and the Help Center UI.
+<!-- source-hash: b1b3afa2679df984c26b9b2281cbbe54 -->
+Barrel export file for the tickets domain, re-exporting all public components, hooks, and types from their respective modules.
 
 ## Key Components
 
-### Components
-| Export | Description |
-|--------|-------------|
-| `TicketCenter` | Main ticket management surface |
-| `TicketOpenForm` | Form for opening new tickets |
-| `TicketRow` | Individual ticket row renderer |
-| `TicketDetailDrawer` | Slide-out drawer for ticket details |
-| `TicketLinkedDeliveryCard` | Card linking a ticket to a delivery |
-| `HelpCenterList` | Full-page customer-facing ticket list, used by OpenFrame's `/tickets` route |
-| `HelpCenterCard` | Expandable card for a single Help Center entry |
-| `HelpCenterCreateForm` / `HelpCenterCreateFormSkeleton` | Ticket creation form with loading skeleton |
-
-### Hooks
-| Export | Description |
-|--------|-------------|
-| `useTicketsList` | Fetches and manages the tickets list state |
-| `useTicketActions` | Provides ticket mutation actions; `mapTicketActionError` maps error codes |
-| `useTicketEngagements` | Manages ticket engagement threads and file attachments |
-
-### Types & Constants
-| Export | Description |
-|--------|-------------|
-| `TicketData`, `AnyTicket`, `OptimisticTicket` | Core ticket data shapes |
-| `TicketClickupSummary` | ClickUp-specific ticket summary |
-| `TicketActionErrorCode`, `MappedTicketActionError` | Typed error handling |
-| `TICKET_TOAST_COPY` | Toast notification copy constants |
-| `isOptimistic` | Type guard for optimistic ticket entries |
-| `TicketRef`, `TicketEngagement`, `TicketEngagementFile` | Supporting types |
+**Components**
+- `TicketCenter` — Top-level ticket management surface
+- `TicketOpenForm` — Form for opening new tickets
+- `TicketRow` — Individual ticket list row
+- `TicketDetailDrawer` — Slide-out drawer for ticket details
+- `TicketLinkedDeliveryCard` — Card linking a ticket to a delivery
+- `TicketReplyComposer` — Composer for ticket replies
+- `HelpCenterList` — Full-page customer-facing ticket list; mounts inside `<PageShell>` for third-party embedders
+- `HelpCenterCard` — Individual help center ticket card
+- `HelpCenterCreateForm` / `HelpCenterCreateFormSkeleton` — Creation form with loading skeleton
+
+**Hooks**
+- `useTicketsList` — Fetches and manages the tickets list
+- `useTicketActions` — Ticket CRUD actions; exposes `mapTicketActionError` helper and `UseTicketActionsReturn` type
+- `useTicketEngagements` — Manages ticket engagement threads and file attachments
+
+**Types & Constants**
+- `TicketData`, `OptimisticTicket`, `AnyTicket` — Core ticket data shapes
+- `TicketClickupSummary` — ClickUp integration summary type
+- `TicketActionErrorCode`, `MappedTicketActionError` — Typed error handling
+- `TICKET_TOAST_COPY` — Toast notification strings
+- `isOptimistic` — Type guard for optimistic ticket entries
 
 ## Usage Example
 
 ```typescript
 import {
   HelpCenterList,
-  TicketDetailDrawer,
   useTicketsList,
   useTicketActions,
   isOptimistic,
   type AnyTicket,
-} from '@/features/tickets'
+} from '@openframe-oss-lib/tickets'
 
-function TicketsPage() {
+function MyHelpCenter() {
   const { tickets } = useTicketsList()
   const { closeTicket } = useTicketActions()
 
-  return (
-    <HelpCenterList>
-      {tickets.map((ticket: AnyTicket) => (
-        <TicketDetailDrawer
-          key={isOptimistic(ticket) ? ticket.optimisticId : ticket.id}
-          ticket={ticket}
-          onClose={() => closeTicket(ticket.id)}
-        />
-      ))}
-    </HelpCenterList>
-  )
+  const confirmed = tickets.filter((t: AnyTicket) => !isOptimistic(t))
+
+  return <HelpCenterList tickets={confirmed} onClose={closeTicket} />
 }
 ```
 
-> **Note:** Third-party embedders can mount `<HelpCenterList />` inside their own `<PageShell>` to get the full Help Center UX without the OpenFrame route wrapper.
+> Source: [`index.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/index.ts)

package/src/components/tickets/.ticket-center.md

@@ -1,51 +1,44 @@
-<!-- source-hash: 342918f6f476b195a4bfc05a9be396e0 -->
-Customer-facing ticket management surface that renders a full ticket workflow (open, view, reply, close, reopen) for authenticated users, and an identity-gated sign-in prompt for anonymous visitors.
+<!-- source-hash: b3b2b6747bc982e9566fa90a074c4272 -->
+Customer-facing ticket management surface component that gates rendering on authentication state and composes ticket listing, creation, and action handling into a single embeddable view.
 
 ## Key Components
 
-| Export / Symbol | Description |
-|---|---|
-| `TicketCenter` | Root exported component; handles identity resolution and delegates to `TicketCenterAuthed` or fallback states |
-| `TicketCenterAuthed` | Inner authenticated shell; owns optimistic state, query cache mutations, and composes the form + list |
-| `TicketCenterSkeleton` | Full-page skeleton shown during the first-mount identity resolution window |
-| `TicketListSkeleton` | List-only skeleton shown while ticket data is loading |
-| `TicketCenterProps` | Public prop interface — only exposes a `toast` override for testability |
+| Export | Type | Description |
+|--------|------|-------------|
+| `TicketCenter` | Component | Public entry point — resolves identity and delegates to the authed view or a sign-in gate |
+| `TicketCenterProps` | Interface | `toast` override for test-friendly injection |
+| `TicketCenterAuthed` | Internal Component | Full ticket UI: list, form, optimistic state, and row actions |
+| `TicketCenterSkeleton` | Internal Component | Full-page skeleton shown during initial identity resolution |
+| `TicketListSkeleton` | Internal Component | Row-level skeletons shown while the ticket list loads |
+
+### State managed by `TicketCenterAuthed`
+
+| State | Purpose |
+|-------|---------|
+| `optimisticTickets` | Local optimistic placeholders prepended above server rows until confirmed |
+| `expandedTicketId` | Tracks which `TicketRow` is currently expanded |
+| `supportSystemDown` | Disables the form and row actions when the upstream ticketing system is unavailable |
 
 ## Usage Example
 
+Mount at your app root alongside a `QueryClientProvider` and `ChatRuntimeContext.Provider` — this component provides neither:
+
 ```typescript
-// Minimal embed — relies on a QueryClientProvider + ChatRuntimeContext.Provider
-// already mounted at the app root (same pattern as <EmbeddableChat />)
-import { TicketCenter } from '@/components/ticket-center/ticket-center'
-
-export function SupportPage() {
-  return (
-    <main>
-      <TicketCenter />
-    </main>
-  )
-}
+import { TicketCenter } from '@openframe-oss-lib/ticket-center'
 
-// Test-friendly override — inject a mock toast to assert notifications
-import { TicketCenter } from '@/components/ticket-center/ticket-center'
-import { mockToast } from '@/test/helpers'
+// Minimal embed — toast defaults to the lib's singleton
+export function TicketsPage() {
+  return <TicketCenter />
+}
 
-render(<TicketCenter toast={mockToast} />)
+// With toast override (useful in tests or custom notification systems)
+export function TicketsPageCustomToast() {
+  return <TicketCenter toast={myCustomToast} />
+}
 ```
 
-## Identity Gate Behavior
-
-```mermaid
-flowchart TD
-    A["TicketCenter mounts"] --> B{"identity.isLoading?"}
-    B -->|yes| C["TicketCenterSkeleton"]
-    B -->|no| D{"authTier === anon\nor no email?"}
-    D -->|yes| E["EmptyState: Sign in prompt"]
-    D -->|no| F["TicketCenterAuthed"]
-    F --> G["TicketOpenForm"]
-    F --> H["TicketRow list\noptimistic + server merged"]
-```
+> **Identity gate:** Anonymous visitors see only a sign-in `EmptyState`. No list fetch or form is rendered, keeping the network tab clean and preventing 401s on submit.
 
-## Optimistic Update Strategy
+## Source
 
-Optimistic tickets are kept in **local state** (not the React Query cache) so a background refetch cannot overwrite pending placeholders mid-flight. The merged view is always `[...optimisticTickets, ...serverTickets]`, placing new pending rows at the top until the server response confirms or rejects them.
+[`ticket-center.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/ticket-center.tsx)

package/src/components/tickets/.ticket-detail-drawer.md

@@ -1,48 +1,38 @@
-<!-- source-hash: 8a7542421be9aaeac5211827f8967375 -->
-Expanded drawer component for a single ticket's detail view, rendering the conversation timeline, metadata, and status-dependent actions (reply/close/reopen).
+<!-- source-hash: 98bda0d90cb3c746f4f65c2eb703add4 -->
+Renders the expanded drawer view for a single support ticket, including the conversation timeline, metadata, and status-dependent actions (reply composer or reopen). Extracted from `ticket-row.tsx` to be shared across both the lib's `TicketRow` and the hub's `TicketCard` compositions.
 
 ## Key Components
 
-### `TicketDetailDrawer` (main export)
-The root drawer component that composes the full expanded ticket view:
-- Renders optional linked ClickUp delivery card
-- Delegates conversation rendering to `TicketTimelinePanel`
-- Conditionally renders `OpenActions` or `ReopenAction` based on ticket status
-
-### `TicketTimelinePanel`
-Internal component that builds a chronological conversation thread:
-- Splits legacy `ticket.body` on ` --- ` separators for historical compatibility
-- Fetches Note engagements via `useTicketEngagements`
-- Resolves customer identity with a 4-level precedence chain (live identity → mirror name → email → "You")
-- Shows skeleton loader during initial fetch; `EmptyState` when no content exists
-
-### `TicketRef`
-Minimal identity bundle (`id` + `external_id`) threaded through mutation callbacks — `external_id` targets HubSpot, `id` drives React/TanStack cache keys.
+- **`TicketDetailDrawer`** — Root component. Renders the assigned agent row, optional linked ClickUp delivery card, conversation timeline, reply-failure banner, and status-gated action area (composer for open tickets, reopen button for closed).
+- **`TicketTimelinePanel`** — Internal component. Fetches and renders the chronological conversation feed via `useTicketEngagements`, with Slack-style auto-scroll (`useStickToBottom`). Suppresses duplicate "Original message" body turns when a matching customer engagement already exists.
+- **`TicketRef`** — Exported type. Identity bundle `{ id, external_id }` threaded through action callbacks.
+- **`TicketDetailDrawerProps`** — Exported interface. Full prop surface including `onSendMessage`, `onClose`, `onReopen`, `replyError`, and `onClearReplyError`.
 
 ## Usage Example
 
 ```typescript
+import {
+  TicketDetailDrawer,
+  type TicketRef,
+} from '@openframe-oss-lib/ticket-detail-drawer'
+
 <TicketDetailDrawer
   ticket={ticket}
   busy={isMutating}
   supportSystemDown={false}
-  onSendMessage={async (ref, text, attachments) => {
-    await sendNoteEngagement(ref.external_id, text, attachments)
-    return true
+  onSendMessage={async (ref: TicketRef, text, attachments) => {
+    return await sendReply(ref.external_id, text, attachments)
   }}
-  onClose={async (ref, resolution) => {
-    await closeTicket(ref.external_id, resolution)
-    return true
+  onClose={async (ref: TicketRef) => {
+    return await closeTicket(ref.external_id)
   }}
-  onReopen={async (ref) => {
-    await reopenTicket(ref.external_id)
-    return true
+  onReopen={async (ref: TicketRef) => {
+    return await reopenTicket(ref.external_id)
   }}
   onActionCollapsed={() => setDrawerOpen(false)}
+  replyError={replyError}
+  onClearReplyError={() => clearReplyError(ticket.external_id)}
 />
 ```
 
-## Notes
-- All local state (composer text, attachments, close-confirm dialog) is owned here; parent owns ticket data and mutation callbacks
-- Optimistic tickets (pre-server-confirmation) skip the engagement fetch until a real `external_id` is available
-- The timeline intentionally has no inner scroll — content flows with the page to avoid competing scroll surfaces
+**Source:** [`ticket-detail-drawer.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/ticket-detail-drawer.tsx)

package/src/components/tickets/.ticket-open-form.md

@@ -1,41 +1,39 @@
-<!-- source-hash: b30cd8d851756508ef3f90328778876a -->
-A client-side React form component for creating new support tickets, rendered at the top of the `<TicketCenter />` view. Composes existing OSS-lib primitives for subject input, message textarea, file attachments, and submit action with multi-condition gating.
+<!-- source-hash: 6d7cfc4afa4176d11ba07ade11300b10 -->
+Form component that renders the "Open Ticket" submission UI at the top of `<TicketCenter />`, composing existing oss-lib primitives for subject input, message textarea, file attachments, and submit handling with multi-condition gating.
 
 ## Key Components
 
-### `TicketOpenFormProps`
+### `TicketOpenForm`
+
+Main exported component. Renders a two-column `<Card>` layout with a description panel on the left and the form fields on the right.
+
+**Props (`TicketOpenFormProps`):**
+
 | Prop | Type | Description |
-|------|------|-------------|
+|---|---|---|
 | `onSubmit` | `(input) => Promise<boolean>` | Wired to `useTicketActions().submitTicket`; returns `true` on success to trigger form reset |
-| `isSubmitting` | `boolean` | Parent-owned single-flight submission flag |
-| `supportSystemDown` | `boolean` | Disables all inputs and submit when the support system is offline |
-
-### Submit Gating (`canSubmit`)
-The submit button is enabled only when **all** conditions pass:
-
-```mermaid
-graph TD
-    A["canSubmit?"] --> B["not isSubmitting"]
-    A --> C["not supportSystemDown"]
-    A --> D["not hasInflightUploads"]
-    A --> E["subject.trim() not empty"]
-    A --> F["content.trim() not empty"]
-    A --> G["content within TICKET_TEXT_MAX_CHARS"]
-```
+| `isSubmitting` | `boolean` | Single-flight guard owned by the parent |
+| `supportSystemDown` | `boolean` | Disables all inputs and shows an error banner when `true` |
+
+**Submit gating — `canSubmit` is `true` only when all of the following hold:**
+- Subject and content are non-empty after trim
+- Content is within `TICKET_TEXT_MAX_CHARS`
+- No uploads are in-flight (`hasInflightUploads === false`)
+- `isSubmitting` is `false`
+- `supportSystemDown` is `false`
+
+**Character counter** — visible once content reaches 80% of `TICKET_TEXT_MAX_CHARS`; turns red when the limit is exceeded.
 
-### Internal State
-- `subject` / `content` — controlled inputs, cleared on successful submit
-- `attachments` — managed via `useChatAttachments()`, sharing the same upload pipeline as the chat composer
+**Attachment handling** — delegates entirely to `useChatAttachments`, reusing the same upload pipeline as the chat composer.
 
 ## Usage Example
 
 ```typescript
-import { TicketOpenForm } from './ticket-open-form'
+import { TicketOpenForm } from '@openframe/oss-lib'
 import { useTicketActions } from './hooks/use-ticket-actions'
 
 function TicketCenter() {
-  const { submitTicket, isSubmitting } = useTicketActions()
-  const supportSystemDown = false
+  const { submitTicket, isSubmitting, supportSystemDown } = useTicketActions()
 
   return (
     <TicketOpenForm
@@ -47,4 +45,4 @@ function TicketCenter() {
 }
 ```
 
-> A character counter appears once content reaches 80% of `TICKET_TEXT_MAX_CHARS` and turns red if the limit is exceeded, blocking submission.
+On successful submission (`onSubmit` resolves `true`), the form automatically clears subject, content, and all attachments.

package/src/components/tickets/.ticket-reply-composer.md

@@ -0,0 +1,51 @@
+<!-- source-hash: d48a2a82c23200567034e210dc847d5a -->
+Reply composer component for open support tickets, combining a `ChatInput` with file attachment support and a close-ticket confirmation dialog.
+
+## Key Components
+
+### `TicketReplyComposer`
+
+The main exported component. Renders a unified composer layout with:
+
+- **`ChatAttachmentChipStrip`** — staged file chips displayed above the input
+- **`ChatInput`** — primary text input with send button; disabled during in-flight uploads or when the support system is down
+- **`ChatAttachmentAddButton`** — attachment trigger in the bottom toolbar (hidden when `supportSystemDown`)
+- **`Close ticket` button** — opens an `AlertDialog` to confirm closure with an optional resolution note
+
+### `TicketReplyComposerProps`
+
+| Prop | Type | Description |
+|---|---|---|
+| `ticket` | `AnyTicket` | The ticket being replied to |
+| `busy` | `boolean` | Disables input while a send is in progress |
+| `supportSystemDown` | `boolean` | Signals connection loss; swaps in a placeholder and hides attachments |
+| `onSendMessage` | `TicketDetailDrawerProps['onSendMessage']` | Async send handler; returns `boolean` indicating success |
+| `onClose` | `TicketDetailDrawerProps['onClose']` | Async close handler; receives an optional resolution string |
+
+## Usage Example
+
+```typescript
+<TicketReplyComposer
+  ticket={ticket}
+  busy={isSending}
+  supportSystemDown={!isConnected}
+  onSendMessage={async (ref, text, attachments) => {
+    const ok = await sendReply(ref.id, text, attachments)
+    return ok
+  }}
+  onClose={async (ref, resolution) => {
+    await closeTicket(ref.id, resolution)
+  }}
+/>
+```
+
+## Behavior Notes
+
+- Draft text and staged files **survive a failed send** — `ChatInput` retains text; attachments are only cleared on success
+- Close confirmation uses a **non-destructive accent button** (closing is reversible via Reopen)
+- `autoFocus` uses `{ preventScroll: true }` internally, so the drawer's scroll-to-top animation is not interrupted
+- The drawer is **not collapsed** after closing a ticket (no `onActionCollapsed`) to preserve the in-place status badge update
+
+## Source
+
+[`ticket-reply-composer.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/ticket-reply-composer.tsx)

package/src/components/tickets/.ticket-row.md

@@ -1,12 +1,25 @@
-<!-- source-hash: a4bd0ac033c0ff89f6d4e4e0f75efebc -->
-Renders a single ticket row with an expandable inline drawer, combining a compact summary tile with a collapsible detail panel for the `TicketCenter` embed.
+<!-- source-hash: 0cb3a7a072b68a1f0cb377074de90f95 -->
+Renders a single ticket row combining a compact summary tile with an expandable detail drawer, managing toggle interactions and scroll positioning within a ticket list.
 
 ## Key Components
 
-- **`TicketRow`** — Main export. Composes a `<ChatTicketItem>` summary tile and a `<CollapsibleContent>` wrapping `<TicketDetailDrawer>`. Controlled via `expanded`/`onToggle` props owned by the parent `<TicketCenter>`.
-- **`TicketRowProps`** — Interface defining ticket data, expansion state, action handlers (`onSendMessage`, `onClose`, `onReopen`, `onActionCollapsed`), and UI flags (`busy`, `supportSystemDown`).
-- **`handleClick`** — Memoized click handler that toggles expansion and smooth-scrolls the row into view, pre-adjusting target Y position to account for any drawer above that is simultaneously collapsing.
-- **`tileData`** — Derived `ChatTicketItemData` object mapping raw `AnyTicket` fields to display values, including HubSpot pipeline stage label, relative timestamps, and ClickUp linked task status chips.
+### `TicketRow`
+The primary exported component that composes:
+- **`<ChatTicketItem>`** — compact summary tile acting as the collapsible trigger (avoids invalid button-in-button nesting via `onClick` prop)
+- **`<CollapsibleContent>` + `<TicketDetailDrawer>`** — animated drawer rendered only when this row is the active expanded one
+- **`scrollElementIntoView`** — scroll correction that pre-subtracts a collapsing sibling drawer's height to land at the correct post-animation position
+
+### `TicketRowProps`
+| Prop | Description |
+|---|---|
+| `ticket` | `AnyTicket` — real or optimistic placeholder |
+| `expanded` | Whether this row's drawer is open |
+| `onToggle` | Parent-owned expand/collapse state setter |
+| `busy` | Disables drawer actions during in-flight requests |
+| `supportSystemDown` | Surfaces degraded-mode UI in the drawer |
+| `onSendMessage / onClose / onReopen` | Forwarded to `<TicketDetailDrawer>` |
+| `onActionCollapsed` | Called after close/reopen so parent can collapse stale state |
+| `id` | DOM `id` for deep-link scroll targets (e.g. `ticket-<external_id>`) |
 
 ## Usage Example
 
@@ -14,17 +27,19 @@ Renders a single ticket row with an expandable inline drawer, combining a compac
 <TicketRow
   ticket={ticket}
   expanded={expandedTicketId === ticket.id}
-  onToggle={(id) => setExpandedTicketId((prev) => (prev === id ? null : id))}
-  busy={isBusy}
+  onToggle={setExpandedTicketId}
+  busy={isMutating}
   supportSystemDown={false}
   onSendMessage={handleSendMessage}
   onClose={handleClose}
   onReopen={handleReopen}
   onActionCollapsed={() => setExpandedTicketId(null)}
+  id={`ticket-${ticket.external_id}`}
 />
 ```
 
-## Notes
+> **Optimistic placeholders** (`isOptimistic(ticket) === true`) render the summary tile as non-interactive — click handler and drawer are suppressed until the real ticket ID arrives from the server.
+
+## Source
 
-- Optimistic tickets (pre-server-confirmation) disable click interaction and suppress drawer rendering since a real ticket ID is not yet available.
-- The scroll adjustment logic mirrors `<HelpCenterCard>` — queries `div[id^="ticket-drawer-"]` to find an open drawer above the clicked row and subtracts its height from the raw scroll target, ensuring the final scroll position matches the post-collapse layout.
+[`ticket-row.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/ticket-row.tsx)

package/src/components/tickets/.types.md

@@ -1,19 +1,35 @@
-<!-- source-hash: 63b1778d9923d2e7914bfaebf859d9ff -->
-Defines the shared type contract for the ticket management feature, including wire shapes for ticket data returned from the `POST /api/chat/agent/find-ticket` endpoint, optimistic UI helpers, error handling types, and UI constants.
+<!-- source-hash: eaad96fbee2b55e506fa06a65db08f00 -->
+Shared type contracts, constants, and utilities for the OpenFrame ticket system — consumed by both client-side hooks and UI components to describe ticket wire shapes, cache structure, error codes, and UX constants.
 
 ## Key Components
 
-| Export | Kind | Description |
-|--------|------|-------------|
-| `TicketData` | Interface | Wire shape of a ticket row from the find-ticket API, mirroring the server's `FindTicketResult` projection |
-| `TicketClickupSummary` | Interface | Compact projection of a linked ClickUp task for the ticket drawer's delivery card |
-| `OptimisticTicket` | Interface | Extends `TicketData` with `_optimistic: true` for pre-flight UI placeholders |
-| `AnyTicket` | Type | Union of `TicketData \| OptimisticTicket` |
-| `isOptimistic()` | Type Guard | Narrows `AnyTicket` to `OptimisticTicket` |
-| `TicketActionErrorCode` | Type | Discriminated string union of stable server-side error codes |
-| `MappedTicketActionError` | Interface | Structured error envelope with toast copy, cache hints, and retry metadata |
-| `TICKET_TEXT_MAX_CHARS` | Constant | Client-side cap of `5000` chars for ticket text inputs |
-| `TOAST_COPY` | Constant | Centralized `as const` map of all user-visible toast strings |
+### Interfaces
+
+| Name | Purpose |
+|---|---|
+| `TicketData` | Wire shape of a row from `POST /api/chat/agent/find-ticket`. Mirrors the server's `FindTicketResult` projection intentionally. |
+| `TicketAssignedOwner` | Resolved agent profile (name, email, avatar) joined from `hubspot_owners` → `profiles`. |
+| `TicketClickupSummary` | Compact projection of a linked ClickUp task for the "Linked delivery" drawer card. |
+| `OptimisticTicket` | Extends `TicketData` with `_optimistic: true` for pre-flight list entries before server confirmation. |
+| `TicketsCacheSlot` | Shape of a `['tickets', …]` TanStack Query cache slot — prevents the `t.map is not a function` class of cache mutation bugs. |
+| `MappedTicketActionError` | Structured error envelope with a typed code, toast copy, and retry/cache-eviction hints. |
+
+### Types & Union
+
+- **`AnyTicket`** — `TicketData | OptimisticTicket`
+- **`TicketActionErrorCode`** — discriminated union of 11 server-side error codes routed through `mapTicketActionError`
+
+### Functions
+
+- **`isOptimistic(t)`** — type guard narrowing `AnyTicket` to `OptimisticTicket`
+
+### Constants
+
+| Name | Value | Purpose |
+|---|---|---|
+| `TICKET_TEXT_MAX_CHARS` | `5000` | Client-side cap on ticket/comment text length |
+| `TICKET_LIVE_POLL_MS` | `8000` | Shared refetch interval (ms) for list + conversation polls on open drawers |
+| `TOAST_COPY` | `as const` object | Centralized, QA-auditable toast strings for all ticket actions |
 
 ## Usage Example
 
@@ -21,37 +37,39 @@ Defines the shared type contract for the ticket management feature, including wi
 import {
   AnyTicket,
   isOptimistic,
-  MappedTicketActionError,
+  TicketsCacheSlot,
+  TICKET_LIVE_POLL_MS,
   TICKET_TEXT_MAX_CHARS,
   TOAST_COPY,
-} from './types'
-
-// Narrow optimistic rows before rendering the drawer
-function renderTicket(ticket: AnyTicket) {
-  if (isOptimistic(ticket)) {
-    return <SkeletonDrawer />
-  }
-  return <TicketDrawer data={ticket} />
-}
+} from '@openframe/oss-lib'
 
-// Validate user input before submission
-if (content.length > TICKET_TEXT_MAX_CHARS) {
-  throw new Error(`Max ${TICKET_TEXT_MAX_CHARS} characters allowed`)
+// Type-guard before rendering optimistic rows
+function renderTicket(t: AnyTicket) {
+  if (isOptimistic(t)) return <SkeletonRow />
+  return <TicketRow data={t} />
 }
 
-// Handle a mapped server error
-function handleError(err: MappedTicketActionError) {
-  if (err.supportSystemDown) {
-    showSupportDownBanner()
-  }
-  if (err.removeRowFromCache) {
-    removeTicketFromList(ticketId)
-  }
-  toast({ title: err.message })
+// Safe cache mutation — always project through TicketsCacheSlot
+queryClient.setQueriesData<TicketsCacheSlot>(
+  { queryKey: ['tickets'] },
+  (old) => ({
+    ...old,
+    tickets: old?.tickets?.map((t) =>
+      t.id === updatedId ? { ...t, status: 'CLOSED' } : t
+    ),
+  })
+)
+
+// Enforce text cap before submitting
+if (body.length > TICKET_TEXT_MAX_CHARS) {
+  showError(`Max ${TICKET_TEXT_MAX_CHARS} characters`)
 }
 
-// Use centralized toast copy on success
-toast(TOAST_COPY.open_success)
+// Consistent poll cadence across list + conversation hooks
+useQuery({ queryKey: ['tickets'], refetchInterval: TICKET_LIVE_POLL_MS })
+
+// Centralized toast copy
+toast(TOAST_COPY.close_success)
 ```
 
-> **Note:** `TicketData` is intentionally duplicated from the server's `FindTicketResult`. If `FIND_TICKET_SELECT` gains a new column server-side, this interface must be updated to match.
+**Source:** [`types.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/types.ts)