@flamingo-stack/openframe-frontend-core 0.0.503 → 0.0.504-snapshot.20260801181709

package/src/components/navigation/top-navigation.tsx

@@ -5,6 +5,17 @@ import { cn } from '../../utils/cn';
 
 export type TopNavigationCenterBreakpoint = 'md' | 'lg';
 
+export type TopNavigationSize = 'small' | 'big';
+
+// Bar height + square-cell width per size (Figma 2797-5978 `size` axis).
+// Heights are FIXED across breakpoints. `--top-nav-cell` is consumed by
+// `HeaderButton` (and any custom cell) so cell widths follow the size without
+// each cell knowing about it.
+const SIZE_CLASSES: Record<TopNavigationSize, string> = {
+  small: 'h-14 [--top-nav-cell:3.5rem]',
+  big: 'h-[72px] [--top-nav-cell:4.5rem]',
+};
+
 // Literal class maps — Tailwind's scanner needs the full class strings.
 const CENTER_VISIBILITY: Record<TopNavigationCenterBreakpoint, string> = {
   md: 'hidden md:flex',
@@ -52,6 +63,9 @@ export interface TopNavigationProps extends React.HTMLAttributes<HTMLElement> {
   backgroundClassName?: string;
   /** Top border on mobile (the ODS spec bar shows it below md). Default true. */
   mobileTopBorder?: boolean;
+  /** Bar size (Figma 2797-5978 `size` axis): `small` = 56px (console),
+   *  `big` = 72px (marketing/hub sites). Fixed across breakpoints. */
+  size?: TopNavigationSize;
 }
 
 const hasContent = (node: React.ReactNode): boolean => node !== null && node !== undefined && node !== false;
@@ -80,6 +94,7 @@ export function TopNavigation({
   sideActions,
   backgroundClassName,
   mobileTopBorder = true,
+  size = 'small',
   className,
   children,
   ...props
@@ -87,7 +102,8 @@ export function TopNavigation({
   return (
     <header
       className={cn(
-        'flex h-12 w-full items-center border-b border-ods-border md:h-14',
+        'flex w-full items-center border-b border-ods-border',
+        SIZE_CLASSES[size],
         mobileTopBorder && 'border-t md:border-t-0',
         backgroundClassName ?? 'bg-ods-card',
         className,

package/src/components/navigation/unread-dot.tsx

@@ -0,0 +1,34 @@
+'use client'
+
+import React from 'react'
+import { cn } from '../../utils/cn'
+
+/**
+ * The ONE unread-indicator dot (`bg-ods-warning`, top-right of an icon
+ * inside a `relative` wrapper). Previously duplicated in
+ * `NotificationsHeaderButton` and `NavigationSidebarItemButton` — both
+ * now render THIS, as does `TicketAlertsButton`.
+ *
+ * Size variants preserve the two pre-existing renders exactly (neither
+ * may silently change):
+ *   - `responsive` — header cells: `w-1.5 h-1.5 md:w-2 md:h-2`
+ *   - `fixed`      — sidebar collapsed icon: `w-2 h-2`
+ */
+export interface UnreadDotProps {
+  size?: 'responsive' | 'fixed'
+  className?: string
+}
+
+export function UnreadDot({ size = 'responsive', className }: UnreadDotProps) {
+  return (
+    <span
+      className={cn(
+        'absolute top-0 right-0 bg-ods-warning rounded-full',
+        size === 'responsive' ? 'w-1.5 h-1.5 md:w-2 md:h-2' : 'w-2 h-2',
+        className,
+      )}
+    />
+  )
+}
+
+export default UnreadDot

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

@@ -28,7 +28,7 @@ Shared type contracts, constants, and utilities for the OpenFrame ticket system
 | 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 |
+| `TICKET_MARK_READ_DEBOUNCE_MS` | `2000` | Trailing debounce for drawer mark-read while new messages stream in |
 | `TOAST_COPY` | `as const` object | Centralized, QA-auditable toast strings for all ticket actions |
 
 ## Usage Example
@@ -38,7 +38,6 @@ import {
   AnyTicket,
   isOptimistic,
   TicketsCacheSlot,
-  TICKET_LIVE_POLL_MS,
   TICKET_TEXT_MAX_CHARS,
   TOAST_COPY,
 } from '@openframe/oss-lib'

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

@@ -26,6 +26,7 @@ import {
   TicketDetailDrawer,
   type TicketDetailDrawerProps,
 } from './ticket-detail-drawer'
+import { useOptionalTicketLive } from './ticket-live-provider'
 import type { AnyTicket } from './types'
 import { isOptimistic } from './types'
 
@@ -118,8 +119,23 @@ export function HelpCenterCard({
     return () => cancelAnimationFrame(raf)
   }, [isExpanded])
 
+  // Unread replies for this row — read from the provider's single summary
+  // map (missing key / no provider = 0). The provider masks the open
+  // ticket to 0 and zeroes on markRead, so no local state here.
+  const live = useOptionalTicketLive()
+  const unreadCount =
+    (!optimistic && ticket.external_id && live?.unreadByTicket[ticket.external_id]) || 0
+
   const rightBadges = (
     <>
+      {unreadCount > 0 && (
+        <StatusBadge
+          text={`${unreadCount} NEW`}
+          colorScheme="warning"
+          variant="card"
+          className="border border-ods-border"
+        />
+      )}
       <StatusBadge
         text={rawStatus}
         colorScheme={getStatusColorScheme(rawStatus)}

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

@@ -44,7 +44,7 @@ import { useTicketActions } from './hooks/use-ticket-actions'
 import { HelpCenterCard } from './help-center-card'
 import { HelpCenterCreateForm, HelpCenterCreateFormSkeleton } from './help-center-create-form'
 import type { AnyTicket, OptimisticTicket, TicketsCacheSlot } from './types'
-import { isOptimistic, TICKET_LIVE_POLL_MS } from './types'
+import { isOptimistic } from './types'
 
 export interface HelpCenterListProps {
   /** Toast override (test-friendly). Defaults to the lib's shared
@@ -212,11 +212,11 @@ function HelpCenterListAuthed({
     search,
     status,
     page,
-    // Live status: while a drawer is open, poll so an out-of-band HubSpot
-    // status change (e.g. agent closes the ticket) flips the badge +
-    // open/reopen affordance within one interval. Idle (no drawer) → no poll.
-    // `ticketParam` (the open ticket's external_id) is the open signal.
-    refetchInterval: ticketParam ? TICKET_LIVE_POLL_MS : false,
+    // No interval polling (deleted 2026-08): `TicketLiveProvider`
+    // invalidates `['tickets']` on stream events; focus/mount refetch
+    // covers hosts without a stream. Disclosed trade-off: a bare
+    // status/pipeline change with no accompanying reply has no live
+    // path until the next event/focus/reconnect.
   })
 
   // Open state DERIVED from the URL param. `?ticket=` carries the user-facing

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

@@ -11,28 +11,19 @@ Fetches and manages the conversation timeline (Note engagements and attachments)
 
 ### Hook
 
-**`useTicketEngagements(externalTicketId, enabled?, refetchInterval?)`**
+**`useTicketEngagements(externalTicketId, enabled?)`**
 
 - Skips fetching for optimistic (`temp-*`) ticket IDs and unauthenticated (`anon`) identities
 - Posts to `/api/chat/agent/list-engagements` via `embedAuthedFetch`
 - Disables all caching (`staleTime: 0`, `gcTime: 0`) to ensure HubSpot truth on every drawer open
-- Supports configurable live-polling via `refetchInterval`; polling automatically stops when the drawer unmounts
+- No interval polling — live refresh is push-driven (`TicketLiveProvider` invalidates `['ticket-engagements', id]` on stream events); focus/mount refetch is the no-stream fallback
 - Fixes a skeleton double-flash by treating a fetchable ticket as "loading" from the very first render, even before `useChatIdentity` resolves
 
 ## Usage Example
 
 ```typescript
-// Basic usage — fetch once when drawer opens
+// Fetch when the drawer opens; live updates arrive via TicketLiveProvider
 const { engagements, isLoading, error } = useTicketEngagements(ticket.externalId)
-
-// Live-polling variant — refresh every 15 seconds while drawer is open
-const TICKET_LIVE_POLL_MS = 15_000
-
-const { engagements, isFetching, refetch } = useTicketEngagements(
-  ticket.externalId,
-  true,
-  TICKET_LIVE_POLL_MS,
-)
 ```
 
 ## Notes

package/src/components/tickets/hooks/.use-tickets-list.md

@@ -9,7 +9,6 @@ Input interface controlling the query:
 - `search` — free-text FTS filter; empty string returns all tickets
 - `status` — `'open'` | `'closed'` | `'all'` (empty/`'all'` omits the filter)
 - `page` / `pageSize` — 1-based pagination; server caps `pageSize` at 100
-- `refetchInterval` — optional polling interval (ms) for live status updates; paused on hidden tabs
 
 ### `UseTicketsListReturn`
 Output shape:
@@ -41,7 +40,6 @@ const {
   status: 'open',
   page: currentPage,
   pageSize: 20,
-  refetchInterval: isDrawerOpen ? 10_000 : false,
 })
 ```
 

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

@@ -33,6 +33,7 @@ import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
 import { useQueryClient } from '@tanstack/react-query'
 import { useRequiredChatRuntime } from '../../../contexts/chat-runtime-context'
 import { embedAuthedFetch } from '../../../utils/embed-authed-fetch'
+import { useOptionalTicketLive } from '../ticket-live-provider'
 import type { ChatAttachment } from '../../chat/utils/chat-attachment-markdown'
 import {
   type AnyTicket,
@@ -154,6 +155,10 @@ export function useTicketActions(options: UseTicketActionsOptions): UseTicketAct
   // the bare hub path when unconfigured.
   const ticketActionEndpoint =
     useRequiredChatRuntime().endpoints.ticketActionUrl ?? TICKET_ACTION_ENDPOINT
+  // Optional live-stream context: a first-ever ticket must retry the
+  // provider's `no-stream` (204) subscription so replies stream in.
+  const ticketLive = useOptionalTicketLive()
+  const notifyTicketCreated = ticketLive?.notifyTicketCreated
   const { prependOptimistic, removeOptimistic, removeTicketFromCache, toast, onSupportSystemDown } = options
 
   // Form-level single-flight uses BOTH a ref (for synchronous guarding
@@ -390,6 +395,9 @@ export function useTicketActions(options: UseTicketActionsOptions): UseTicketAct
             await queryClient.invalidateQueries({ queryKey: ['tickets'] })
             removeOptimistic(placeholderId)
           }
+          // A zero-ticket viewer's stream returned 204 before this
+          // create — nudge the provider to (re)subscribe.
+          notifyTicketCreated?.()
           return true
         })
       } catch (err) {
@@ -409,6 +417,7 @@ export function useTicketActions(options: UseTicketActionsOptions): UseTicketAct
       queryClient,
       toast,
       watchMirrorSync,
+      notifyTicketCreated,
       surfaceError,
     ],
   )

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

@@ -77,14 +77,6 @@ export interface UseTicketEngagementsReturn {
 export function useTicketEngagements(
   externalTicketId: string | null | undefined,
   enabled = true,
-  /** Poll cadence (ms) for live conversation refresh while the drawer is
-   *  open. The drawer only mounts this hook when expanded, so a constant
-   *  here is already gated to "drawer open" — closing the drawer unmounts
-   *  the panel and the polling stops. `false`/undefined disables it (the
-   *  default, preserving prior fetch-once-per-open behavior for any other
-   *  caller). Mirrors `useTicketsList.refetchInterval`; see
-   *  `TICKET_LIVE_POLL_MS`. */
-  refetchInterval: number | false = false,
 ): UseTicketEngagementsReturn {
   const identity = useChatIdentity()
   const identityKey = identity.user?.email ?? 'anon'
@@ -115,11 +107,10 @@ export function useTicketEngagements(
     gcTime: 0,
     refetchOnMount: 'always',
     refetchOnWindowFocus: true,
-    // Live conversation: poll while the caller opts in (drawer open). New
-    // agent replies + attachments appear within one interval without a
-    // manual refresh. `refetchIntervalInBackground` stays false (default)
-    // so polling pauses on a hidden tab.
-    refetchInterval,
+    // NO interval polling (deleted 2026-08): new agent replies arrive via
+    // `TicketLiveProvider`'s stream-driven invalidation of
+    // `['ticket-engagements', id]`; focus/mount refetch is the no-stream
+    // fallback.
     queryFn: async (): Promise<TicketEngagement[]> => {
       const response = await embedAuthedFetch(listEngagementsEndpoint, {
         method: 'POST',

package/src/components/tickets/hooks/use-tickets-list.ts

@@ -59,13 +59,6 @@ export interface UseTicketsListFilters {
   page?: number
   /** Items per page (server caps at 100). Defaults to 20. */
   pageSize?: number
-  /** Poll interval (ms) for live updates — e.g. so a ticket CLOSED out-of-band
-   *  on HubSpot flips the status badge + open/reopen affordance without a manual
-   *  refresh. `false`/0/undefined disables polling. The hub passes a value only
-   *  while a drawer is open (mirror webhooks keep the server fresh; this surfaces
-   *  it client-side). TanStack pauses interval polling while the tab is hidden,
-   *  so there are no wasted background requests. */
-  refetchInterval?: number | false
 }
 
 export interface UseTicketsListReturn {
@@ -116,8 +109,6 @@ export function useTicketsList(filters: UseTicketsListFilters): UseTicketsListRe
   // previous identity's data.
   const identityKey = customerEmail || 'anon'
 
-  const refetchInterval = filters.refetchInterval ?? false
-
   const query = useQuery({
     queryKey: ['tickets', 'self', identityKey, search, statusFilter, page, pageSize],
     enabled,
@@ -130,10 +121,8 @@ export function useTicketsList(filters: UseTicketsListFilters): UseTicketsListRe
     gcTime: 0,
     refetchOnMount: 'always',
     refetchOnWindowFocus: true,
-    // Live status: poll while the caller opts in (drawer open). Defaults to
-    // false. `refetchIntervalInBackground` stays false (the default) so polling
-    // pauses on a hidden tab — no wasted requests when the user tabs away.
-    refetchInterval,
+    // NO interval polling (deleted 2026-08): live freshness is push-driven
+    // — `TicketLiveProvider` invalidates `['tickets']` on stream events.
     queryFn: async (): Promise<FindTicketResponse> => {
       const body: Record<string, string | number> = {
         query: search,

package/src/components/tickets/index.ts

@@ -38,6 +38,12 @@ export {
   type TicketEngagement,
   type TicketEngagementFile,
 } from './hooks/use-ticket-engagements'
+export {
+  TicketLiveProvider,
+  useTicketLive,
+  useOptionalTicketLive,
+  type TicketLiveContextValue,
+} from './ticket-live-provider'
 export {
   type TicketData,
   type TicketClickupSummary,
@@ -45,6 +51,10 @@ export {
   type AnyTicket,
   type TicketActionErrorCode,
   type MappedTicketActionError,
+  type TicketStreamEvent,
+  type TicketStreamEventType,
+  type TicketMessageStreamData,
+  type TicketUnreadSummary,
   TOAST_COPY as TICKET_TOAST_COPY,
   isOptimistic,
 } from './types'

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

@@ -21,6 +21,7 @@
  * callbacks; we don't reach into the QueryClient.
  */
 
+import { useEffect, useRef } from 'react'
 import { useStickToBottom } from 'use-stick-to-bottom'
 import { Button } from './../ui/button'
 import { useChatIdentity } from './../chat/hooks/use-chat-identity'
@@ -40,13 +41,14 @@ import type {
   TicketEngagementFile,
 } from './hooks/use-ticket-engagements'
 import { TicketLinkedDeliveryCard } from './ticket-linked-delivery-card'
+import { useOptionalTicketLive } from './ticket-live-provider'
 import { TicketReplyComposer } from './ticket-reply-composer'
 import type {
   AnyTicket,
   TicketAssignedOwner,
   MappedTicketActionError,
 } from './types'
-import { isOptimistic, TICKET_LIVE_POLL_MS } from './types'
+import { isOptimistic, TICKET_MARK_READ_DEBOUNCE_MS } from './types'
 
 /** Identity bundle threaded through the action callbacks: local mirror
  *  UUID + HubSpot external_id. Actions send `external_id` to HubSpot
@@ -204,18 +206,48 @@ function TicketTimelinePanel({ ticket }: { ticket: AnyTicket }) {
   // Optimistic placeholders don't have a real external_id yet — skip
   // the engagement fetch until the real ticket lands.
   const externalId = isOptimistic(ticket) ? null : ticket.external_id
-  // Live conversation refresh: this panel only mounts while the drawer is
-  // open, so the constant interval is already gated to "open" (closing the
-  // drawer unmounts the panel → polling stops). New agent replies +
-  // attachments surface within one cadence without a manual refresh — the
-  // same 8s the list-level status/assignee poll uses (single source:
-  // TICKET_LIVE_POLL_MS). A background poll never flashes the skeleton
-  // (the `isLoading` guard below keys off "no data yet", not `isFetching`).
-  const { engagements, isLoading } = useTicketEngagements(
-    externalId,
-    !!externalId,
-    TICKET_LIVE_POLL_MS,
-  )
+  // Live conversation refresh is PUSH-driven: `TicketLiveProvider`
+  // invalidates `['ticket-engagements', id]` on stream events, so new
+  // agent replies surface without any interval (polling was deleted
+  // 2026-08; `refetchOnWindowFocus` remains the no-stream fallback).
+  const { engagements, isLoading } = useTicketEngagements(externalId, !!externalId)
+
+  // Read-state lifecycle — this panel mounts exactly while the drawer is
+  // open, so it owns: register the open ticket (provider suppresses
+  // unread bumps + masks the row), markRead on open, debounced markRead
+  // as new messages stream in, flush on close. The provider's callbacks
+  // are stable (useCallback) so these effects don't re-fire on unrelated
+  // context-value changes.
+  const live = useOptionalTicketLive()
+  const setOpenTicketId = live?.setOpenTicketId
+  const markRead = live?.markRead
+  const markReadDebounceRef = useRef<ReturnType<typeof setTimeout> | null>(null)
+
+  useEffect(() => {
+    if (!externalId || !setOpenTicketId || !markRead) return
+    setOpenTicketId(externalId)
+    void markRead(externalId)
+    return () => {
+      // Flush a pending debounced markRead on close so a reply that
+      // arrived moments before closing is still receipted.
+      if (markReadDebounceRef.current) {
+        clearTimeout(markReadDebounceRef.current)
+        markReadDebounceRef.current = null
+        void markRead(externalId)
+      }
+      setOpenTicketId(null)
+    }
+  }, [externalId, setOpenTicketId, markRead])
+
+  const engagementsCount = engagements.length
+  useEffect(() => {
+    if (!externalId || !markRead || engagementsCount === 0) return
+    if (markReadDebounceRef.current) clearTimeout(markReadDebounceRef.current)
+    markReadDebounceRef.current = setTimeout(() => {
+      markReadDebounceRef.current = null
+      void markRead(externalId)
+    }, TICKET_MARK_READ_DEBOUNCE_MS)
+  }, [engagementsCount, externalId, markRead])
 
   // Slack-style auto-tail (same lib mechanism `ChatMessageList` uses): jump to
   // the newest message on open (`initial:'instant'`), smooth-scroll on a new