@flamingo-stack/openframe-frontend-core 0.0.215 → 0.0.216

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

@@ -39,11 +39,23 @@ import {
   type OptimisticTicket,
   type TicketActionErrorCode,
   type TicketData,
+  type TicketsCacheSlot,
   TOAST_COPY,
 } from '../types'
 
 const TICKET_ACTION_ENDPOINT = '/api/chat/agent/ticket-action'
 
+/** Codes that populate the inline reply-failure banner above the drawer
+ *  composer. Other codes (system-down, ticket-gone, rate-limit) are
+ *  full-row / full-system signals covered by the toast + supportSystemDown
+ *  handling — surfacing them in the inline banner too would be redundant. */
+const REPLY_BANNER_CODES: ReadonlySet<TicketActionErrorCode> = new Set<TicketActionErrorCode>([
+  'HUBSPOT_5XX',
+  'HUBSPOT_400_VALIDATION',
+  'HUBSPOT_404_THREAD',
+  'HUBSPOT_REPLY_UNKNOWN',
+])
+
 /** 3 attempts × backoff (cumulative ~21s wall-clock). After this we
  *  drop the optimistic row and ask the user to reload. */
 const MIRROR_SYNC_BACKOFF_MS = [3_000, 6_000, 12_000] as const
@@ -125,6 +137,14 @@ export interface UseTicketActionsReturn {
   isSubmittingForm: boolean
   /** Per-row in-flight set (read-only). UI uses `isRowBusy(localId)`. */
   isRowBusy: (localId: string) => boolean
+  /** Most recent reply failure for a given ticket id (`external_id`).
+   *  Drives the inline "couldn't send" banner above the composer in
+   *  `<TicketDetailDrawer>`. Cleared on the next successful send OR
+   *  via `clearReplyError(ticketId)`. */
+  replyErrorFor: (ticketExternalId: string) => MappedTicketActionError | null
+  /** Clear the persisted reply-failure banner for a ticket (e.g. when
+   *  the user dismisses it or starts a new draft). */
+  clearReplyError: (ticketExternalId: string) => void
 }
 
 export function useTicketActions(options: UseTicketActionsOptions): UseTicketActionsReturn {
@@ -151,6 +171,37 @@ export function useTicketActions(options: UseTicketActionsOptions): UseTicketAct
   }, [])
   const isRowBusy = useCallback((id: string) => busyRows.has(id), [busyRows])
 
+  // Persisted reply-failure banner state — keyed by the ticket's
+  // HubSpot `external_id`. The drawer reads `replyErrorFor(externalId)`
+  // and renders an inline "couldn't send — retry" banner above the
+  // composer. Cleared automatically on the next successful send and
+  // explicitly by the dismiss-X / "Retry" actions in the banner UI.
+  // Distinct from the transient toast — the banner persists so the
+  // user can locate their failed draft after dismissing the toast.
+  const [replyErrorByTicket, setReplyErrorByTicket] = useState<
+    Map<string, MappedTicketActionError>
+  >(() => new Map())
+  const setReplyError = useCallback(
+    (externalId: string, mapped: MappedTicketActionError | null) => {
+      setReplyErrorByTicket((prev) => {
+        const next = new Map(prev)
+        if (mapped) next.set(externalId, mapped)
+        else next.delete(externalId)
+        return next
+      })
+    },
+    [],
+  )
+  const replyErrorFor = useCallback(
+    (externalId: string): MappedTicketActionError | null =>
+      replyErrorByTicket.get(externalId) ?? null,
+    [replyErrorByTicket],
+  )
+  const clearReplyError = useCallback(
+    (externalId: string) => setReplyError(externalId, null),
+    [setReplyError],
+  )
+
   // Mirror-sync watcher controllers tracked by placeholder id so we can
   // abort prior watchers when a new submit lands AND so unmount cleans
   // them up without leaking setState calls. Single source of truth for
@@ -262,9 +313,15 @@ export function useTicketActions(options: UseTicketActionsOptions): UseTicketAct
     [queryClient, removeOptimistic, toast],
   )
 
+  // Last `surfaceError` mapping — sendMessage reads this immediately
+  // after the catch returns so it can decide whether to populate the
+  // inline reply banner. Cleared on every read by the consumer to
+  // prevent a stale failure from leaking into the next attempt.
+  const lastUpdateErrorRef = useRef<MappedTicketActionError | null>(null)
   const surfaceError = useCallback(
     (err: unknown, action: string): MappedTicketActionError => {
       const mapped = mapTicketActionError(err)
+      lastUpdateErrorRef.current = mapped
       if (mapped.supportSystemDown) onSupportSystemDown()
       toast({
         title: `Could not ${action}`,
@@ -302,6 +359,10 @@ export function useTicketActions(options: UseTicketActionsOptions): UseTicketAct
         // seconds via the mirror refetch. Drawer uses live chat
         // identity for own-replies during this window anyway.
         customer_name: null,
+        // No assignee until the real ticket lands. Drawer renders
+        // "Unassigned" for this brief window.
+        assigned_to: null,
+        assignedOwner: null,
         hubspot_updated_at: new Date().toISOString(),
         _optimistic: true,
       }
@@ -366,13 +427,63 @@ export function useTicketActions(options: UseTicketActionsOptions): UseTicketAct
             ticket_id: ticket.external_id,
           } as unknown as Record<string, unknown>)
           toast(successCopy)
-          // Invalidate BOTH ticket list (status / pipeline may have
-          // changed) AND engagements (comments + attachments produce a
-          // new Note that the timeline must pick up).
-          await Promise.all([
-            queryClient.invalidateQueries({ queryKey: ['tickets'] }),
-            queryClient.invalidateQueries({ queryKey: ['ticket-engagements'] }),
-          ])
+
+          // OPTIMISTIC in-place row update on the tickets cache.
+          //
+          // Previously this code called
+          // `queryClient.invalidateQueries({ queryKey: ['tickets'] })`
+          // which forced a full refetch. When the user is on a
+          // filtered view (e.g. ?status=open) and CLOSES a ticket from
+          // its drawer, the refetched list excludes the now-closed
+          // row, the parent `<HelpCenterCard>` for that row unmounts,
+          // and the inline drawer dies with it — user-facing bug
+          // "close button refreshes the whole page and dismisses the
+          // ticket I was working on" (reported 2026-05-29).
+          //
+          // The mutation already knows what changed (status, content
+          // addendum, attachments) — apply those fields in place
+          // across every `['tickets']` cache slot. The row stays in
+          // the list with the new badge; React doesn't reconcile away
+          // the card; the drawer stays mounted and the user can
+          // continue working.
+          //
+          // Filter-mismatch trade-off: a row that no longer matches a
+          // slot's filter (e.g. CLOSED row in ?status=open cache)
+          // stays visually until next manual refetch (filter change,
+          // page nav, manual reload). Acceptable — the user opted into
+          // the action; carrying their drawer through it is more
+          // important than instantly hiding the row.
+          const statusUpdate =
+            (serverArgs as { status?: 'OPEN' | 'CLOSED' }).status ?? null
+          if (statusUpdate) {
+            // The `useTicketsList` query (in `use-tickets-list.ts`)
+            // returns `FindTicketResponse` — an OBJECT shape
+            // `{ tickets: TicketData[], count, page, totalPages, ... }` —
+            // NOT a bare `TicketData[]`. The previous version of this
+            // callback assumed an array and crashed at runtime with
+            // `t.map is not a function` on every close/reopen
+            // (reported 2026-05-29 in prod). Project the nested
+            // tickets array, map, and reassemble the wrapper.
+            queryClient.setQueriesData<TicketsCacheSlot | undefined>(
+              { queryKey: ['tickets'] },
+              (prev) => {
+                if (!prev || !Array.isArray(prev.tickets)) return prev
+                let mutated = false
+                const nextTickets = prev.tickets.map((t) => {
+                  if (t.id !== ticket.id || t.status === statusUpdate) return t
+                  mutated = true
+                  return { ...t, status: statusUpdate }
+                })
+                return mutated ? { ...prev, tickets: nextTickets } : prev
+              },
+            )
+          }
+
+          // Engagements ALWAYS need to refetch — the addendum / new
+          // attachment / status-change-note must land in the timeline.
+          // Scoped to the engagements query only; doesn't touch the
+          // list cache.
+          await queryClient.invalidateQueries({ queryKey: ['ticket-engagements'] })
           return true
         })
       } catch (err) {
@@ -393,12 +504,18 @@ export function useTicketActions(options: UseTicketActionsOptions): UseTicketAct
   )
 
   const sendMessage = useCallback(
-    (ticket: TicketRef, text: string, attachments: ChatAttachment[]) => {
+    async (ticket: TicketRef, text: string, attachments: ChatAttachment[]) => {
       const trimmed = text.trim()
       const hasText = trimmed.length > 0
       const hasFiles = attachments.length > 0
-      if (!hasText && !hasFiles) return Promise.resolve(false)
-      return updateTicket(
+      if (!hasText && !hasFiles) return false
+      // Clear any stale mapped error from a prior non-sendMessage action
+      // (closeTicket / reopenTicket) so the post-call read only picks up
+      // an error THIS sendMessage produced. Without this clear, a prior
+      // close-failure's mapped error could leak into the banner via the
+      // post-call `lastUpdateErrorRef.current` read.
+      lastUpdateErrorRef.current = null
+      const ok = await updateTicket(
         ticket,
         {
           ...(hasText ? { content_addendum: trimmed } : {}),
@@ -407,8 +524,33 @@ export function useTicketActions(options: UseTicketActionsOptions): UseTicketAct
         TOAST_COPY.comment_success,
         'send message',
       )
+      // Banner-state coupling: SUCCESS clears any stale failure banner
+      // for this ticket; FAILURE populates the banner ONLY for the
+      // reply-specific code subset (HUBSPOT_5XX / 400 / 404 / UNKNOWN).
+      // Other codes (TICKET_NOT_FOUND, HUBSPOT_DISCONNECTED, RATE_LIMITED)
+      // are full-row / full-system signals already covered by the
+      // existing toast + supportSystemDown handling — surfacing them in
+      // the inline banner too would be redundant.
+      if (ok) {
+        clearReplyError(ticket.external_id)
+      } else {
+        // Line 466's `.current = null` narrows the property to literal
+        // `null`. `tsc -p tsconfig.declarations.json` (declarations
+        // build, distinct from the `tsc --noEmit` pre-step) doesn't
+        // widen that narrowing across the `await updateTicket(...)`,
+        // so the read here is typed `never`. The runtime type IS
+        // `MappedTicketActionError | null` per the useRef declaration;
+        // the assertion just tells TS to honor it instead of the stale
+        // narrowing.
+        const mapped = lastUpdateErrorRef.current as MappedTicketActionError | null
+        if (mapped && REPLY_BANNER_CODES.has(mapped.code)) {
+          setReplyError(ticket.external_id, mapped)
+        }
+        lastUpdateErrorRef.current = null
+      }
+      return ok
     },
-    [updateTicket],
+    [updateTicket, clearReplyError, setReplyError],
   )
 
   const closeTicket = useCallback(
@@ -439,8 +581,19 @@ export function useTicketActions(options: UseTicketActionsOptions): UseTicketAct
       reopenTicket,
       isSubmittingForm,
       isRowBusy,
+      replyErrorFor,
+      clearReplyError,
     }),
-    [submitTicket, sendMessage, closeTicket, reopenTicket, isSubmittingForm, isRowBusy],
+    [
+      submitTicket,
+      sendMessage,
+      closeTicket,
+      reopenTicket,
+      isSubmittingForm,
+      isRowBusy,
+      replyErrorFor,
+      clearReplyError,
+    ],
   )
 }
 
@@ -512,6 +665,38 @@ export function mapTicketActionError(err: unknown): MappedTicketActionError {
           supportSystemDown: false,
           removeRowFromCache: false,
         }
+      case 'HUBSPOT_5XX':
+        return {
+          code: err.code,
+          message:
+            "We couldn't reach the support system. Your reply wasn't sent — please retry in a moment.",
+          supportSystemDown: false,
+          removeRowFromCache: false,
+        }
+      case 'HUBSPOT_400_VALIDATION':
+        return {
+          code: err.code,
+          message:
+            'Your reply was rejected. Please rephrase or remove unsupported content and try again.',
+          supportSystemDown: false,
+          removeRowFromCache: false,
+        }
+      case 'HUBSPOT_404_THREAD':
+        return {
+          code: err.code,
+          message:
+            'This conversation is no longer accepting replies. Open a new ticket to continue.',
+          supportSystemDown: false,
+          removeRowFromCache: false,
+        }
+      case 'HUBSPOT_REPLY_UNKNOWN':
+        return {
+          code: err.code,
+          message:
+            "Your reply didn't go through. Please retry.",
+          supportSystemDown: false,
+          removeRowFromCache: false,
+        }
       default:
         return {
           code: 'UNKNOWN',
@@ -546,9 +731,20 @@ function cacheContainsTicket(
   queryClient: ReturnType<typeof useQueryClient>,
   expectedTicketId: string,
 ): boolean {
-  const entries = queryClient.getQueriesData<TicketData[] | undefined>({ queryKey: ['tickets'] })
+  // Cache slot is `TicketsCacheSlot` (`{ tickets, count, … }`), NOT a
+  // bare `TicketData[]`. The previous code's `Array.isArray(data)` guard
+  // silently fell through to `return false` on real responses — the
+  // post-create watcher therefore NEVER detected the real row arriving
+  // early and always waited the full timeout. Project the nested array.
+  const entries = queryClient.getQueriesData<TicketsCacheSlot | undefined>({
+    queryKey: ['tickets'],
+  })
   for (const [, data] of entries) {
-    if (Array.isArray(data) && data.some((t) => t.external_id === expectedTicketId)) {
+    if (
+      data &&
+      Array.isArray(data.tickets) &&
+      data.tickets.some((t) => t.external_id === expectedTicketId)
+    ) {
       return true
     }
   }

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

@@ -46,12 +46,17 @@ import {
   ConversationCardRowSkeletonList,
 } from './../shared/dev-section/dev-card-row'
 import type { TicketAttachment } from './../ui/ticket-attachments-list'
+import { SquareAvatar } from './../ui/square-avatar'
 import { useTicketEngagements } from './hooks/use-ticket-engagements'
 import type {
   TicketEngagementFile,
 } from './hooks/use-ticket-engagements'
 import { TicketLinkedDeliveryCard } from './ticket-linked-delivery-card'
-import type { AnyTicket } from './types'
+import type {
+  AnyTicket,
+  TicketAssignedOwner,
+  MappedTicketActionError,
+} from './types'
 import { isOptimistic, TICKET_TEXT_MAX_CHARS } from './types'
 
 /** Identity bundle threaded through the action callbacks: local mirror
@@ -76,6 +81,15 @@ export interface TicketDetailDrawerProps {
   /** Called after a successful close/reopen so the parent can collapse
    *  the drawer (status flipped — current action set is now stale). */
   onActionCollapsed: () => void
+  /** Persisted reply-failure surface — when non-null the drawer renders
+   *  an inline banner above the composer with the mapped copy + a
+   *  dismiss control. Distinct from the transient toast; the banner
+   *  stays visible so the customer can locate the failed draft after
+   *  the toast disappears. Cleared on the next successful send. */
+  replyError?: MappedTicketActionError | null
+  /** Dismiss-X handler for the banner. Parent calls
+   *  `actions.clearReplyError(ticket.external_id)`. */
+  onClearReplyError?: () => void
 }
 
 export function TicketDetailDrawer({
@@ -86,10 +100,19 @@ export function TicketDetailDrawer({
   onClose,
   onReopen,
   onActionCollapsed,
+  replyError,
+  onClearReplyError,
 }: TicketDetailDrawerProps) {
   const isClosed = (ticket.status ?? '').toUpperCase() === 'CLOSED'
   return (
     <div className="bg-ods-card border-t border-ods-border px-4 py-4 flex flex-col gap-4">
+      {/* Assignee header — surfaces who's looking at this ticket on the
+          support side. Populated server-side via `attachOwnerProfiles`;
+          falls back to "Unassigned" when no agent is assigned OR when
+          the owner couldn't be resolved (deleted between ticket update
+          + next owners reconcile). */}
+      <AssignedAgentRow assignedOwner={ticket.assignedOwner} />
+
       {/* Linked ClickUp delivery — rendered only when the server's
           `attachClickupTasks` step populated `ticket.clickup`. Customer
           tickets with no linked task skip this entirely. The card itself
@@ -107,6 +130,19 @@ export function TicketDetailDrawer({
       </div>
 
       <div className="border-t border-ods-border pt-4">
+        {/* Reply-failure banner — populated by `useTicketActions` when
+            the last sendMessage attempt for THIS ticket failed with a
+            reply-specific code. Rendered above the composer/reopen so
+            the customer sees it in context of their failed draft. Open
+            (composer) actions still allow Retry; the closed (reopen)
+            state still shows the banner because the user might have
+            tried to reply to a then-closing ticket. */}
+        {replyError && (
+          <ReplyFailureBanner
+            error={replyError}
+            onDismiss={onClearReplyError ?? (() => undefined)}
+          />
+        )}
         {isClosed ? (
           <ReopenAction
             ticketRef={{ id: ticket.id, external_id: ticket.external_id }}
@@ -408,8 +444,15 @@ function ReopenAction({
   onActionCollapsed: TicketDetailDrawerProps['onActionCollapsed']
 }) {
   const handleReopen = async () => {
-    const ok = await onReopen(ticketRef)
-    if (ok) onActionCollapsed()
+    // Intentionally do NOT call `onActionCollapsed()` here. Pre-PR #1053
+    // every reopen was followed by a full list refetch which removed
+    // the (now-OPEN) row from a `?status=closed` view, so collapsing
+    // the drawer hid the disappearance flash. After #1053+#1055 the
+    // row stays in the list with the optimistic in-place status
+    // update — collapsing the drawer now actively dismisses the
+    // ticket the user is working on. Keep it mounted; the badge flip
+    // is enough feedback. (Reported 2026-05-29.)
+    void (await onReopen(ticketRef))
   }
   return (
     <div className="flex justify-end">
@@ -465,9 +508,14 @@ function OpenActions({
 
   const confirmClose = async () => {
     setCloseDialogOpen(false)
-    const ok = await onClose(ticketRef, resolution.trim() || undefined)
+    await onClose(ticketRef, resolution.trim() || undefined)
     setResolution('')
-    if (ok) onActionCollapsed()
+    // Intentionally do NOT call `onActionCollapsed()` here. See the
+    // matching comment in ReopenActions.handleReopen above — collapsing
+    // the drawer after a successful close now dismisses the ticket the
+    // user is actively working on, which is the exact UX bug PR #1053
+    // set out to fix. The optimistic in-place status update keeps the
+    // row mounted with the new badge; that's the only feedback needed.
   }
 
   return (
@@ -562,3 +610,95 @@ function OpenActions({
     </div>
   )
 }
+
+/**
+ * Persistent banner above the drawer composer/actions when the most
+ * recent customer reply failed with a reply-specific code (HUBSPOT_5XX
+ * / 400 / 404 / UNKNOWN). The transient toast already fired at the
+ * moment of failure; this banner stays until the next successful send
+ * OR the user dismisses it explicitly. Wording is sourced from
+ * `mapTicketActionError` so a future copy update lives in one place.
+ *
+ * 404_THREAD is the only terminal code in the set — the banner copy
+ * reads "open a new ticket" and Retry would just re-fail. We still
+ * render a Dismiss control instead of hiding Retry so the visual shape
+ * is uniform; the parent's composer continues to function for any
+ * non-thread-deletion reply path.
+ */
+function ReplyFailureBanner({
+  error,
+  onDismiss,
+}: {
+  error: MappedTicketActionError
+  onDismiss: () => void
+}) {
+  return (
+    <div
+      role="status"
+      aria-live="polite"
+      className="mb-3 flex items-start gap-3 rounded-md border border-ods-attention-red-error bg-ods-attention-red-error-secondary px-3 py-2 text-sm text-ods-attention-red-error"
+    >
+      <span className="font-medium leading-snug">{error.message}</span>
+      <Button
+        type="button"
+        variant="transparent"
+        onClick={onDismiss}
+        aria-label="Dismiss reply failure"
+        className="ml-auto px-2 py-0.5 text-xs font-medium uppercase tracking-wider text-ods-attention-red-error hover:bg-ods-attention-red-error/10 border-transparent"
+      >
+        Dismiss
+      </Button>
+    </div>
+  )
+}
+
+/**
+ * Compact "Assigned to" row at the top of the drawer. Surfaces the
+ * support-side agent — name + avatar — so the customer knows who's
+ * looking at their ticket. Renders "Unassigned" when the ticket has no
+ * `hubspot_owner_id` OR when the owner couldn't be resolved against
+ * the mirror (deleted between ticket update + next reconcile).
+ *
+ * Avatar comes from the canonical `<SquareAvatar variant="round">` so
+ * it picks up the initials-fallback + image-proxy behavior used
+ * everywhere else in the lib (matches the dev-section message-bubble
+ * avatars). No bespoke avatar markup.
+ */
+function AssignedAgentRow({
+  assignedOwner,
+}: {
+  assignedOwner: TicketAssignedOwner | null
+}) {
+  // Display label precedence:
+  //   1. `name` from the mirror (employee match OR HubSpot's first+last)
+  //   2. `email` local-part — covers HubSpot owners that exist but have
+  //      no name (rare but real; the ticket IS assigned and rendering
+  //      "Unassigned" would be misleading)
+  //   3. "Unassigned" — only when the ticket has no `assigned_to` OR
+  //      the owner couldn't be resolved against the mirror at all
+  const trimmedName = assignedOwner?.name?.trim() || null
+  const emailFallback = assignedOwner?.email?.trim() || null
+  const displayLabel =
+    trimmedName ?? (emailFallback ? emailFallback.split('@')[0] : null)
+  return (
+    <div className="flex items-center gap-2 text-xs">
+      <span className="text-ods-text-secondary uppercase tracking-wider font-medium">
+        Assigned to
+      </span>
+      {displayLabel ? (
+        <span className="flex items-center gap-1.5 text-ods-text-primary font-medium">
+          <SquareAvatar
+            size="sm"
+            variant="round"
+            src={assignedOwner?.avatarUrl ?? undefined}
+            alt={displayLabel}
+            fallback={displayLabel}
+          />
+          {displayLabel}
+        </span>
+      ) : (
+        <span className="text-ods-text-secondary italic">Unassigned</span>
+      )}
+    </div>
+  )
+}

package/src/components/tickets/types.ts

@@ -51,9 +51,30 @@ export interface TicketData {
    *  Channels, so this is the only reliable source for "what's the
    *  customer's name." */
   customer_name: string | null
+  /** HubSpot owner id of the agent assigned to this ticket. Carried as
+   *  raw id for debugging; rendering goes through `assignedOwner`. Null
+   *  when unassigned. */
+  assigned_to: string | null
+  /** Resolved assigned-owner profile — name + email + avatar. Populated
+   *  server-side via `attachOwnerProfiles` which joins through the
+   *  `hubspot_owners` mirror to `profiles` by email. Drives the
+   *  "Assigned to" attribution in the drawer header. Null when
+   *  unassigned OR the owner couldn't be resolved (rare — only when
+   *  the agent was deleted from HubSpot between the ticket update and
+   *  the next owners reconcile). */
+  assignedOwner: TicketAssignedOwner | null
   hubspot_updated_at: string
 }
 
+/** Resolved profile of a ticket's assigned agent — surfaced in the
+ *  drawer header. Subset of the server's `MirroredOwnerProfile`
+ *  trimmed to just the rendering fields. */
+export interface TicketAssignedOwner {
+  name: string | null
+  email: string | null
+  avatarUrl: string | null
+}
+
 /** Compact projection of a linked ClickUp task — matches the server's
  *  `ClickupSummary` and aligns with `DeliveryItem` so the linked-card
  *  on a ticket can render through the same `DeliveryRow` primitive used
@@ -118,10 +139,40 @@ export function isOptimistic(t: AnyTicket): t is OptimisticTicket {
   return (t as OptimisticTicket)._optimistic === true
 }
 
+/**
+ * Shape of a single `['tickets', …]` TanStack-Query cache slot.
+ * Mirrors `FindTicketResponse` in `hooks/use-tickets-list.ts` — kept
+ * here because the cache-mutation call sites in `useTicketActions` and
+ * `<HelpCenterList>` would otherwise have to redeclare the shape inline.
+ *
+ * A 2026-05-29 prod regression (`t.map is not a function` on
+ * close/reopen) was caused by assuming the cache held a bare
+ * `TicketData[]` instead of this wrapper — every helper that calls
+ * `queryClient.setQueriesData` / `getQueriesData` on `['tickets']`
+ * MUST type the value through this shape and project / reassemble
+ * `tickets` explicitly.
+ */
+export interface TicketsCacheSlot {
+  tickets?: TicketData[]
+  count?: number
+  totalCount?: number
+  page?: number
+  pageSize?: number
+  totalPages?: number
+  scope?: 'self' | 'all'
+}
+
 /**
  * Stable server-side error codes the ticket-action helpers route
  * through `mapTicketActionError`. Anything else is treated as a generic
  * server error.
+ *
+ * Reply-specific codes (`HUBSPOT_5XX` / `HUBSPOT_400_VALIDATION` /
+ * `HUBSPOT_404_THREAD` / `HUBSPOT_REPLY_UNKNOWN`) drive the drawer
+ * banner that appears above the composer when a customer reply fails.
+ * Distinct from `HUBSPOT_DISCONNECTED` (whole-system) and
+ * `TICKET_NOT_FOUND` (terminal-row) — the reply codes are per-attempt
+ * + retryable except for `HUBSPOT_404_THREAD`.
  */
 export type TicketActionErrorCode =
   | 'PROPOSAL_NOT_CLAIMABLE'
@@ -130,6 +181,10 @@ export type TicketActionErrorCode =
   | 'HUBSPOT_DISCONNECTED'
   | 'RATE_LIMITED'
   | 'INVALID_TOOL_ARGS'
+  | 'HUBSPOT_5XX'
+  | 'HUBSPOT_400_VALIDATION'
+  | 'HUBSPOT_404_THREAD'
+  | 'HUBSPOT_REPLY_UNKNOWN'
   | 'UNKNOWN'
 
 export interface MappedTicketActionError {

package/src/components/ui/filter-pill-row.tsx

@@ -0,0 +1,72 @@
+'use client'
+
+/**
+ * Shared filter section wrapper with responsive layout.
+ *
+ * Provides the consistent card container for any filter row (status,
+ * platform, section, etc.) Single row on desktop with flex-wrap,
+ * stacks naturally on mobile.
+ *
+ * Lifted from hub `components/admin/shared/filter-section.tsx` so
+ * lib catalog views can render their own filter pills without an
+ * injected slot.
+ */
+
+import { Filter } from 'lucide-react'
+import { Button } from './button'
+
+export interface FilterPillRowOption {
+  value: string
+  label: string
+}
+
+export interface FilterPillRowProps {
+  /** Label shown next to the filter icon, e.g. "Section", "Platform". */
+  label: string
+  /** The currently selected filter value. */
+  selectedValue: string
+  /** Callback when a filter option is selected. */
+  onValueChange: (value: string) => void
+  /** Available filter options. */
+  options: FilterPillRowOption[]
+  /** Optional count label, e.g. "Showing 1-10 of 42 items". */
+  countLabel?: string
+  /** Optional children to render instead of options (for custom filter content). */
+  children?: React.ReactNode
+}
+
+export function FilterPillRow({
+  label,
+  selectedValue,
+  onValueChange,
+  options,
+  countLabel,
+  children,
+}: FilterPillRowProps) {
+  return (
+    <div className="flex flex-wrap items-center gap-3 p-4 bg-ods-card border border-ods-border rounded-lg">
+      <div className="flex items-center gap-2">
+        <Filter className="h-4 w-4 text-ods-accent" />
+        <span className="text-h5 text-ods-text-secondary">{label}</span>
+      </div>
+      {children ||
+        options.map((opt) => (
+          <Button
+            key={opt.value}
+            type="button"
+            variant={selectedValue === opt.value ? 'accent' : 'outline'}
+            size="small-legacy"
+            onClick={() => onValueChange(opt.value)}
+            className="text-h3"
+          >
+            {opt.label}
+          </Button>
+        ))}
+      {countLabel && (
+        <div className="ml-auto text-[12px] font-['DM_Sans'] text-ods-text-secondary shrink-0">
+          {countLabel}
+        </div>
+      )}
+    </div>
+  )
+}

package/src/components/ui/index.ts

@@ -154,4 +154,5 @@ export * from './ticket-attachments-list'
 export * from './ticket-note-card'
 export * from './ticket-notes-section'
 export * from './simple-markdown-renderer'
+export * from './filter-pill-row'