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

package/src/components/shared/roadmap/.use-roadmap-voting.md

@@ -0,0 +1,68 @@
+<!-- source-hash: f066f48b7e750fe429b96a6f9a50da79 -->
+A `localStorage`-backed React hook providing optimistic up/down voting for roadmap cards, with one vote per task per user, automatic vote toggling/switching, and server sync via a configurable API endpoint.
+
+## Key Components
+
+### Types
+
+| Type | Description |
+|------|-------------|
+| `VoteType` | `'up' \| 'down' \| null` — current vote state for a task |
+| `VoteState` | Record mapping `taskId → VoteType` |
+| `UseRoadmapVotingOptions` | Configuration interface for endpoint and storage key |
+
+### Hook Return Values
+
+| Value | Type | Description |
+|-------|------|-------------|
+| `votes` | `VoteState` | All current votes keyed by `taskId` |
+| `isLoading` | `boolean` | `true` while hydrating from `localStorage` |
+| `getVote` | `(taskId) => VoteType` | Returns current vote for a task |
+| `toggleVote` | `async (taskId, voteType) => result` | Casts or removes a vote with optimistic update |
+| `clearVotes` | `() => void` | Clears all votes from state and `localStorage` |
+
+### Core Behavior
+
+- **Optimistic updates** — UI reflects vote immediately; reverts on API failure
+- **Toggle semantics** — clicking the active vote removes it; switching direction sends a remove + add pair to keep server totals consistent
+- **Namespace isolation** — `storageKey` option allows multiple roadmap surfaces on the same origin without vote cross-contamination
+- **Key change safety** — state resets and re-hydrates whenever `storageKey` changes mid-lifecycle
+
+## Usage Example
+
+```typescript
+import { useRoadmapVoting } from './use-roadmap-voting';
+
+function RoadmapCard({ taskId }: { taskId: string }) {
+  const { getVote, toggleVote, isLoading } = useRoadmapVoting({
+    voteApiEndpoint: '/api/roadmap/vote',
+    storageKey: 'roadmap_votes_v1_main',
+  });
+
+  const currentVote = getVote(taskId);
+
+  const handleVote = async (type: 'up' | 'down') => {
+    const { success, newVote } = await toggleVote(taskId, type);
+    if (!success) console.warn('Vote failed, reverted to:', newVote);
+  };
+
+  if (isLoading) return <span>Loading...</span>;
+
+  return (
+    <div>
+      <button
+        onClick={() => handleVote('up')}
+        style={{ fontWeight: currentVote === 'up' ? 'bold' : 'normal' }}
+      >
+        👍
+      </button>
+      <button
+        onClick={() => handleVote('down')}
+        style={{ fontWeight: currentVote === 'down' ? 'bold' : 'normal' }}
+      >
+        👎
+      </button>
+    </div>
+  );
+}
+```

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

@@ -0,0 +1,51 @@
+<!-- source-hash: a4fe8194703f767fe2216ee1b9351f99 -->
+A client-side React component that renders a single support ticket row in the Help Center list, featuring a toggleable expanded drawer for full ticket interaction.
+
+## Key Components
+
+### `HelpCenterCard` (default export)
+The primary component rendering a ticket summary row as a clickable `<button>` that toggles a `<TicketDetailDrawer>` below it. Key behaviors:
+
+- **Optimistic rows** are rendered as non-expandable (dimmed, `opacity-60`) until the server confirms the ticket ID
+- **Scroll-on-expand** uses `scrollElementIntoView` with a cross-row layout-shift correction — compensates when a sibling drawer above collapses simultaneously, shifting the page Y position
+- **Sticky header offset** (`STICKY_HEADER_OFFSET_PX = 96`) is applied both as `scrollMarginTop` inline style (for browser/anchor scrolls) and as `headerOffset` (for programmatic scroll), keeping them in sync from a single constant
+
+### `HelpCenterCardProps`
+```typescript
+interface HelpCenterCardProps {
+  ticket: AnyTicket
+  expanded: boolean
+  onToggle: (id: string) => void
+  busy: boolean
+  supportSystemDown: boolean
+  onSendMessage: TicketDetailDrawerProps['onSendMessage']
+  onClose: TicketDetailDrawerProps['onClose']
+  onReopen: TicketDetailDrawerProps['onReopen']
+  onActionCollapsed: () => void
+}
+```
+
+### `mapPriorityScheme` (internal)
+Maps ticket priority strings to `StatusBadge` color schemes. Kept separate from the shared `getStatusColorScheme` to avoid conflating workflow status with severity.
+
+| Priority | Color Scheme |
+|----------|-------------|
+| `HIGH` / `URGENT` | `error` (red) |
+| `MEDIUM` | `warning` (yellow) |
+| `LOW` / unknown | `default` |
+
+## Usage Example
+
+```typescript
+<HelpCenterCard
+  ticket={ticket}
+  expanded={expandedId === ticket.id}
+  onToggle={(id) => setExpandedId(prev => prev === id ? null : id)}
+  busy={isBusy}
+  supportSystemDown={false}
+  onSendMessage={handleSendMessage}
+  onClose={handleCloseTicket}
+  onReopen={handleReopenTicket}
+  onActionCollapsed={() => setExpandedId(null)}
+/>
+```

package/src/components/tickets/.help-center-create-form.md

@@ -0,0 +1,38 @@
+<!-- source-hash: a34cdabdcffe2227fd25cb927e40e785 -->
+Thin wrapper around `<ContactForm />` that preconfigures it for Help Center ticket creation, plus a pixel-accurate loading skeleton.
+
+## Key Components
+
+### `HelpCenterCreateForm`
+The primary export. Wraps `<ContactForm />` with ticket-specific configuration:
+- Hides irrelevant contact fields (`name`, `email`, `companySize`, `referralSource`, `helpCategory`)
+- Injects a locally-managed `Subject` input via `extraTopField`
+- Pre-fills hidden fields from session identity to satisfy Zod validators
+- Wires `onCustomSubmit` to `actions.submitTicket(...)` with subject validation before delegating
+
+### `HelpCenterCreateFormSkeleton`
+A loading placeholder that mirrors the real form's dimensions pixel-for-pixel (verified at `lg` breakpoint: 556px wrapper height). Includes 4 hidden `<input type="hidden">` elements to replicate Tailwind's `space-y-*` sibling spacing behavior — omitting them shifts the visible stack up by 24px on page load.
+
+### `HelpCenterCreateFormProps`
+| Prop | Type | Description |
+|------|------|-------------|
+| `actions` | `UseTicketActionsReturn` | Full actions bag; `submitTicket` is consumed |
+| `sessionName` | `string` | Pre-resolved identity name from parent |
+| `sessionEmail` | `string` | Pre-resolved identity email from parent |
+| `supportSystemDown` | `boolean` | Disables all inputs when HubSpot is unavailable |
+
+## Usage Example
+
+```typescript
+<HelpCenterCreateForm
+  actions={ticketActions}
+  sessionName={identity.name}
+  sessionEmail={identity.email}
+  supportSystemDown={ticketActions.onSupportSystemDown}
+/>
+
+// While identity.isLoading:
+<HelpCenterCreateFormSkeleton />
+```
+
+> **Note:** `sessionName`/`sessionEmail` must be passed from the parent rather than re-calling `useChatIdentity` inside this component — a second hook call mounts with `user = null`, causing react-hook-form to lock `defaultValues.email` to an empty string for the form's lifetime, silently failing Zod validation on submit.

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

@@ -0,0 +1,40 @@
+<!-- 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.
+
+## 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
+
+## Usage Example
+
+```typescript
+// Mounted directly on the /tickets page (OpenFrame):
+import { HelpCenterList } from './help-center-list'
+
+export default function TicketsPage() {
+  return <HelpCenterList />
+}
+
+// With toast override for testing:
+import { mockToast } from '../test-utils'
+
+render(<HelpCenterList toast={mockToast} />)
+```
+
+## 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)
+```
+
+> **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.

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

@@ -0,0 +1,65 @@
+<!-- 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.
+
+## 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 |
+
+## Usage Example
+
+```typescript
+import {
+  HelpCenterList,
+  TicketDetailDrawer,
+  useTicketsList,
+  useTicketActions,
+  isOptimistic,
+  type AnyTicket,
+} from '@/features/tickets'
+
+function TicketsPage() {
+  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>
+  )
+}
+```
+
+> **Note:** Third-party embedders can mount `<HelpCenterList />` inside their own `<PageShell>` to get the full Help Center UX without the OpenFrame route wrapper.

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

@@ -0,0 +1,51 @@
+<!-- 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.
+
+## 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 |
+
+## Usage Example
+
+```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>
+  )
+}
+
+// Test-friendly override — inject a mock toast to assert notifications
+import { TicketCenter } from '@/components/ticket-center/ticket-center'
+import { mockToast } from '@/test/helpers'
+
+render(<TicketCenter toast={mockToast} />)
+```
+
+## 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"]
+```
+
+## Optimistic Update Strategy
+
+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.

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

@@ -0,0 +1,48 @@
+<!-- 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).
+
+## 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.
+
+## Usage Example
+
+```typescript
+<TicketDetailDrawer
+  ticket={ticket}
+  busy={isMutating}
+  supportSystemDown={false}
+  onSendMessage={async (ref, text, attachments) => {
+    await sendNoteEngagement(ref.external_id, text, attachments)
+    return true
+  }}
+  onClose={async (ref, resolution) => {
+    await closeTicket(ref.external_id, resolution)
+    return true
+  }}
+  onReopen={async (ref) => {
+    await reopenTicket(ref.external_id)
+    return true
+  }}
+  onActionCollapsed={() => setDrawerOpen(false)}
+/>
+```
+
+## 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

package/src/components/tickets/.ticket-linked-delivery-card.md

@@ -0,0 +1,36 @@
+<!-- source-hash: 73401c7b99510ec750c43323cc9caed2 -->
+Renders a ClickUp delivery task linked to a HubSpot ticket as a single `<DeliveryRow />` tile, using the same primitive as the `/bug-fixes-and-enhancements` list view.
+
+## Key Components
+
+- **`TicketLinkedDeliveryCard`** — Main component that maps a `TicketClickupSummary` onto a `DeliveryItem` and renders it inside a bordered card container
+- **`TicketLinkedDeliveryCardProps`** — Props interface accepting a `clickup` summary object and optional `className`
+- **`DeliveryItem`** — Normalized shape passed to `<DeliveryRow />`, with fallbacks for all optional ClickUp fields
+- **`DeliveryRow`** — Shared primitive that handles display and navigation, receiving the pre-built `delivery_href` for deep-linking
+
+## Navigation Behavior
+
+Navigation uses `clickup.delivery_href`, built server-side via `buildDevSectionUrl('delivery', external_id)`. The URL includes `?search=<external_id>` to filter the destination list to the exact task — the same deep-link mechanism used by chat-inline delivery cards. Soft-nav via the env-aware `next/link` shim preserves React state and TanStack-Query cache on back-navigation.
+
+## Usage Example
+
+```typescript
+import { TicketLinkedDeliveryCard } from './ticket-linked-delivery-card'
+
+const clickupSummary: TicketClickupSummary = {
+  external_id: 'task-abc123',
+  title: 'Migrate auth service to OAuth2',
+  description: 'Refactor legacy token logic...',
+  status: 'in progress',
+  status_color: '#4eccc4',
+  task_type: 'Feature',
+  delivery_href: '/delivery?search=task-abc123',
+  clickup_url: 'https://app.clickup.com/t/abc123',
+  date_opened: 1710000000000,
+}
+
+<TicketLinkedDeliveryCard
+  clickup={clickupSummary}
+  className="mt-4"
+/>
+```

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

@@ -0,0 +1,50 @@
+<!-- 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.
+
+## Key Components
+
+### `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"]
+```
+
+### Internal State
+- `subject` / `content` — controlled inputs, cleared on successful submit
+- `attachments` — managed via `useChatAttachments()`, sharing the same upload pipeline as the chat composer
+
+## Usage Example
+
+```typescript
+import { TicketOpenForm } from './ticket-open-form'
+import { useTicketActions } from './hooks/use-ticket-actions'
+
+function TicketCenter() {
+  const { submitTicket, isSubmitting } = useTicketActions()
+  const supportSystemDown = false
+
+  return (
+    <TicketOpenForm
+      onSubmit={submitTicket}
+      isSubmitting={isSubmitting}
+      supportSystemDown={supportSystemDown}
+    />
+  )
+}
+```
+
+> A character counter appears once content reaches 80% of `TICKET_TEXT_MAX_CHARS` and turns red if the limit is exceeded, blocking submission.

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

@@ -0,0 +1,30 @@
+<!-- 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.
+
+## 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.
+
+## Usage Example
+
+```typescript
+<TicketRow
+  ticket={ticket}
+  expanded={expandedTicketId === ticket.id}
+  onToggle={(id) => setExpandedTicketId((prev) => (prev === id ? null : id))}
+  busy={isBusy}
+  supportSystemDown={false}
+  onSendMessage={handleSendMessage}
+  onClose={handleClose}
+  onReopen={handleReopen}
+  onActionCollapsed={() => setExpandedTicketId(null)}
+/>
+```
+
+## Notes
+
+- 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.

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

@@ -0,0 +1,57 @@
+<!-- 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.
+
+## 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 |
+
+## Usage Example
+
+```typescript
+import {
+  AnyTicket,
+  isOptimistic,
+  MappedTicketActionError,
+  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} />
+}
+
+// Validate user input before submission
+if (content.length > TICKET_TEXT_MAX_CHARS) {
+  throw new Error(`Max ${TICKET_TEXT_MAX_CHARS} characters allowed`)
+}
+
+// Handle a mapped server error
+function handleError(err: MappedTicketActionError) {
+  if (err.supportSystemDown) {
+    showSupportDownBanner()
+  }
+  if (err.removeRowFromCache) {
+    removeTicketFromList(ticketId)
+  }
+  toast({ title: err.message })
+}
+
+// Use centralized toast copy on success
+toast(TOAST_COPY.open_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.

package/src/components/tickets/hooks/.use-ticket-actions.md

@@ -0,0 +1,77 @@
+<!-- source-hash: 6164b984e1688be647fedf5037a794eb -->
+Brief description of the file's purpose: This hook encapsulates all ticket write operations (create, update, close, reopen, reply) for the Flamingo/OpenFrame tickets UI, routing them through a single `/api/chat/agent/ticket-action` endpoint with single-flight protection, per-row mutexes, a serialization queue, and mirror-sync retry logic.
+
+## Key Components
+
+### `useTicketActions(options: UseTicketActionsOptions): UseTicketActionsReturn`
+The primary exported hook. Accepts callback options from the parent and returns ticket action handlers plus loading state selectors.
+
+### `UseTicketActionsOptions`
+Configuration interface injected by the parent component:
+- `prependOptimistic` — adds an optimistic placeholder row to the QueryClient cache before the server roundtrip
+- `removeOptimistic` — removes the placeholder on mirror-sync failure or real ticket arrival
+- `removeTicketFromCache` — silent cache removal on `TICKET_NOT_FOUND`
+- `toast` — notification helper (injected for testability)
+- `onSupportSystemDown` — called on `412 HUBSPOT_DISCONNECTED`
+
+### `UseTicketActionsReturn`
+Returned handler surface:
+- `submitTicket(input)` — creates a new ticket with subject, content, and optional attachments
+- `sendMessage(ticket, text, attachments)` — sends a combined reply note
+- `closeTicket(ticket, resolution?)` — closes a ticket
+- `reopenTicket(ticket)` — reopens a closed ticket
+- `isSubmittingForm` — boolean loading state for form-level submission
+- `isRowBusy(localId)` — per-row busy predicate for UI disabling
+
+### `TicketRef`
+Decouples the local mirror UUID (`id`) from the HubSpot external id (`external_id`), both required for correct mutex and server routing.
+
+### Internal Mechanisms
+| Mechanism | Purpose |
+|---|---|
+| `formInFlightRef` + `isSubmittingForm` | Prevents duplicate form submits across async ticks |
+| `busyRowsRef` + `busyRows` | Per-row mutex preventing fan-out on the same ticket row |
+| `queueRef` / `enqueue` | Depth-1 serial queue preventing server rate-limit stampedes |
+| `watchMirrorSync` | 3s/6s/12s backoff refetch loop when `mirror_synced === false`; drops placeholder after 30s cap |
+| `watcherControllersRef` | `AbortController` map; aborted on unmount and on duplicate-submit replacement |
+
+## Usage Example
+
+```typescript
+const {
+  submitTicket,
+  sendMessage,
+  closeTicket,
+  reopenTicket,
+  isSubmittingForm,
+  isRowBusy,
+} = useTicketActions({
+  prependOptimistic: (placeholder) => {
+    queryClient.setQueryData(['tickets'], (old: TicketData) => ({
+      ...old,
+      tickets: [placeholder, ...(old?.tickets ?? [])],
+    }))
+  },
+  removeOptimistic: (id) => {
+    queryClient.setQueryData(['tickets'], (old: TicketData) => ({
+      ...old,
+      tickets: old?.tickets.filter((t) => t.id !== id) ?? [],
+    }))
+  },
+  removeTicketFromCache: (ticketId) => { /* cache mutation */ },
+  toast,
+  onSupportSystemDown: () => setSupportSystemDown(true),
+})
+
+// Create a ticket
+const ok = await submitTicket({
+  subject: 'VPN not connecting',
+  content: 'Unable to connect since this morning.',
+})
+
+// Close a ticket
+await closeTicket(
+  { id: ticket.id, external_id: ticket.external_id },
+  'Resolved by restarting the VPN client.'
+)
+```

package/src/components/tickets/hooks/.use-ticket-engagements.md

@@ -0,0 +1,42 @@
+<!-- source-hash: 14e8fee946105e4d0d83a53313cfd255 -->
+Fetches the conversation timeline (notes, messages, and attachments) for a single HubSpot ticket, powering the ticket drawer's timeline view. Intentionally separate from the ticket list hook since engagements require expensive multi-stage API calls and are only loaded on demand.
+
+## Key Components
+
+### Interfaces
+
+| Interface | Description |
+|---|---|
+| `TicketEngagementFile` | Attachment metadata: `id`, `name`, `url`, `mime`, `size` |
+| `TicketEngagement` | A single timeline entry with body, author info (`authorRole`, `authorName`, `authorEmail`, `authorAvatarUrl`), timestamp, and attachments |
+| `UseTicketEngagementsReturn` | Return shape: `engagements`, `isLoading`, `isFetching`, `error`, `refetch` |
+
+### Hook
+
+**`useTicketEngagements(externalTicketId, enabled?)`** — Queries `/api/chat/agent/list-engagements` via `embedAuthedFetch`. Skips execution for anonymous users, missing ticket IDs, and optimistic `temp-*` placeholders. Caching is intentionally disabled (`staleTime: 0`, `gcTime: 0`) so every drawer-open reflects live HubSpot state.
+
+## Usage Example
+
+```typescript
+const { engagements, isLoading, error, refetch } = useTicketEngagements(ticket.externalId)
+
+if (isLoading) return <Spinner />
+if (error) return <ErrorBanner message={error.message} />
+
+return (
+  <Timeline>
+    {engagements.map(e => (
+      <TimelineEntry
+        key={e.id}
+        body={e.body}
+        role={e.authorRole}   // 'customer' | 'support'
+        author={e.authorName}
+        avatarUrl={e.authorAvatarUrl}
+        attachments={e.attachments}
+      />
+    ))}
+  </Timeline>
+)
+```
+
+> **Security note:** The server-side route enforces ticket ownership via `ticketBelongsToCustomer` before returning notes — customers cannot enumerate another customer's timeline by guessing ticket IDs.