@flamingo-stack/openframe-frontend-core 0.0.210 → 0.0.212-snapshot.20260528112413

package/src/components/footer-waitlist-button.tsx

@@ -1,6 +1,7 @@
 'use client';
 
-import { usePathname, useRouter } from '../embed-shims/next-navigation';
+import { useRouter } from '../embed-shims/next-navigation';
+import { useChatRuntime } from '../contexts/chat-runtime-context';
 import { useCallback } from 'react';
 import { OpenFrameLogo } from './icons';
 import { Button } from './ui/button';
@@ -11,27 +12,43 @@ export interface FooterWaitlistButtonProps {
 
 /**
  * Small wrapper around JoinWaitlistButton for use inside the footer.
- * Provides a default click handler that scrolls/focuses the wait-list form
- * if the user is already on /waitlist; otherwise navigates to it.
+ *
+ * Routes through the host's unified-navigation hook
+ * (`runtime.navigation.navigate`) when a `ChatRuntimeContext` is
+ * mounted — that's the same path EVERY other in-app navigation
+ * surface uses (source chips, inline cards, search-autocomplete,
+ * action cards). One rule, one decision tree across the whole app.
+ * The hub's `HubRuntimeProvider` wires `navigate` to its `useUnifiedNav`
+ * helper, so this button picks up cross-platform new-tab decisions,
+ * same-URL re-scroll handling, embed-mode short-circuiting, and any
+ * future host-side nav rules for free.
+ *
+ * Falls back to the embed-shim's `router.push` when no runtime is
+ * mounted (third-party embedders who haven't set up
+ * `ChatRuntimeContext` — the lib stays usable without forcing them
+ * to wire the full chat-runtime).
+ *
+ * Target URL: `/waitlist#top`. `#top` is the canonical "scroll to
+ * page top" anchor — the destination page has an explicit
+ * `<div id="top">` at the top of `<main>` so native browser anchor
+ * scroll works in every browser regardless of the HTML5 magic-anchor
+ * behavior.
  */
 export function FooterWaitlistButton({ className }: FooterWaitlistButtonProps) {
   const router = useRouter();
-  const pathname = usePathname();
+  const runtime = useChatRuntime();
 
   const handleClick = useCallback(() => {
-    if (pathname?.startsWith('/waitlist')) {
-      const anchor = document.getElementById('waitlist-form');
-      if (anchor) {
-        anchor.scrollIntoView({ behavior: 'smooth', block: 'center' } as any);
-        setTimeout(() => {
-          const input = anchor.querySelector('input[type="email"]') as HTMLInputElement | null;
-          input?.focus();
-        }, 400);
-        return;
-      }
+    const href = '/waitlist#top';
+    // Prefer the host's unified-nav callback (hub-wired
+    // `useUnifiedNav`). Falls back to the embed-shim's router when
+    // the host hasn't provided one.
+    if (runtime?.navigation?.navigate) {
+      const handled = runtime.navigation.navigate({ href });
+      if (handled) return;
     }
-    router.push('/waitlist#waitlist-form');
-  }, [pathname, router]);
+    router.push(href);
+  }, [router, runtime]);
 
   return (
     <Button 

package/src/components/navigation/app-header.tsx

@@ -6,7 +6,6 @@ import { cn } from '../../utils/cn'
 import { useOptionalNotifications } from '../features/notifications/notifications-context'
 import { LogOutIcon, OpenFrameLogo, OpenFrameText, UserIcon } from '../icons'
 import { BellIcon } from '../icons-v2-generated/interface/bell-icon'
-import { BellRingingIcon } from '../icons-v2-generated/interface/bell-ringing-icon'
 import { Menu01Icon, SearchIcon, XmarkIcon } from '../icons-v2-generated'
 import { DropdownMenu, DropdownMenuContent, DropdownMenuItem, DropdownMenuTrigger, SquareAvatar } from '../ui'
 import { HeaderButton } from './header-button'
@@ -210,20 +209,19 @@ function NotificationsHeaderButton({
   dimmedClass,
 }: NotificationsHeaderButtonProps) {
   const ctx = useOptionalNotifications()
-  const unreadCount = ctx?.unreadCount ?? fallbackUnreadCount
+  const hasUnread = (ctx?.unreadCount ?? fallbackUnreadCount) > 0
   const isActive = ctx?.isOpen ?? false
   const onClick = ctx?.toggle
-  const Icon = unreadCount > 0 ? BellRingingIcon : BellIcon
 
   return (
     <HeaderButton
       icon={
-        <div className="relative w-full h-full flex items-center justify-center">
-          <Icon className="h-4 w-4 md:w-6 md:h-6" />
-          {unreadCount > 0 && (
-            <span className="absolute top-2 right-2 bg-ods-accent text-ods-text-on-accent text-[8px] rounded-full w-3 h-3 md:w-4 md:h-4 flex items-center justify-center">
-              {unreadCount > 9 ? '9+' : unreadCount}
-            </span>
+        <div className="relative w-4 h-4 md:w-6 md:h-6">
+          <BellIcon className="w-full h-full" />
+          {hasUnread && (
+            <span
+              className="absolute top-0 right-0 bg-ods-warning rounded-full w-1.5 h-1.5 md:w-2 md:h-2"
+            />
           )}
         </div>
       }

package/src/components/navigation/sticky-section-nav.tsx

@@ -2,6 +2,7 @@
 
 import React, { useEffect, useState, useCallback, useRef } from 'react'
 import { cn } from '../../utils'
+import { scrollElementIntoView } from '../../utils/scroll-into-view'
 
 export interface StickyNavSection {
   id: string
@@ -97,7 +98,10 @@ export function useSectionNavigation(
   const isScrollingFromClick = useRef(false)
   const { offset = 100 } = options || {}
 
-  // Handle click - just scroll to the element
+  // Handle click - scroll to the element via the canonical helper.
+  // The `offset` prop maps to `headerOffset` (sticky chrome above the
+  // section nav); same smooth-scroll mechanics every other anchor
+  // surface in the app uses.
   const handleSectionClick = useCallback((sectionId: string) => {
     const targetElement = document.getElementById(sectionId)
     if (!targetElement) return
@@ -106,9 +110,7 @@ export function useSectionNavigation(
     isScrollingFromClick.current = true
     setActiveSection(sectionId)
 
-    // Scroll to element
-    const top = targetElement.offsetTop - offset
-    window.scrollTo({ top, behavior: 'smooth' })
+    scrollElementIntoView(targetElement, { headerOffset: offset })
 
     // Allow scroll spy again after scroll completes
     setTimeout(() => {

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

@@ -15,8 +15,10 @@
  * is a SIBLING of the toggle button, not nested inside it.
  */
 
+import { useCallback, useRef } from 'react'
 import { StatusBadge, type StatusBadgeProps } from '../ui'
 import { formatRelativeTime } from '../../utils/date-utils'
+import { scrollElementIntoView } from '../../utils/scroll-into-view'
 import { getStatusColorScheme } from '../chat/utils/agent-status-message'
 import { DevCardRowContent } from '../shared/dev-section/dev-card-row'
 import {
@@ -26,6 +28,23 @@ import {
 import type { AnyTicket } from './types'
 import { isOptimistic } from './types'
 
+/** Sticky page-chrome offset, applied two ways from this ONE constant:
+ *
+ *   1. As `scrollMarginTop` inline style on the wrapper — so any
+ *      anchor-driven or `scrollIntoView()`-driven scroll (browser
+ *      `#hash` navigation, Tab-focus into the card) lands BELOW the
+ *      sticky header.
+ *   2. As `headerOffset` passed to `scrollElementIntoView(...)` — for
+ *      the click-to-expand `window.scrollTo` path, which pre-computes
+ *      its target pixel and ignores CSS `scroll-margin-top`.
+ *
+ *  Single source of truth: change 96 here and BOTH paths follow. The
+ *  previous code combined a `scroll-mt-24` (=96px) Tailwind class
+ *  with this constant — two declarations, one comment binding them,
+ *  drift hazard. Now there's nothing to keep in sync.
+ */
+const STICKY_HEADER_OFFSET_PX = 96
+
 export interface HelpCenterCardProps {
   ticket: AnyTicket
   expanded: boolean
@@ -72,6 +91,39 @@ export function HelpCenterCard({
   const isExpandable = !optimistic
   const isExpanded = expanded && isExpandable
 
+  // Scroll-on-click — delegates to the canonical `scrollElementIntoView`
+  // helper with a cross-row layout-shift `adjustTargetY` callback. The
+  // helper owns the smooth-scroll mechanics + sticky-chrome offset; we
+  // pass the consumer-specific knowledge ("a sibling drawer above me
+  // is about to collapse — subtract its height from the target Y").
+  //
+  // Cross-row gotcha: if ANOTHER row above this one is currently
+  // expanded, its drawer collapses simultaneously with our toggle.
+  // The collapse shrinks the page above our row → our final Y is
+  // HIGHER than the current `rect.top`. By pre-subtracting the
+  // collapsing drawer's height we land at the post-shift position
+  // cleanly, without scrollIntoView's mid-animation drift.
+  const rowRef = useRef<HTMLDivElement | null>(null)
+  const handleClick = useCallback(() => {
+    onToggle(ticket.id)
+    scrollElementIntoView(rowRef.current, {
+      headerOffset: STICKY_HEADER_OFFSET_PX,
+      adjustTargetY: (raw) => {
+        if (!rowRef.current) return raw
+        const expandedDrawer = document.querySelector(
+          'div[id^="help-center-drawer-"]',
+        )
+        if (!(expandedDrawer instanceof HTMLElement)) return raw
+        const drawerRect = expandedDrawer.getBoundingClientRect()
+        const myRect = rowRef.current.getBoundingClientRect()
+        // Only adjust when the drawer is ABOVE us. Drawers below us
+        // don't shift our position when they collapse.
+        if (drawerRect.bottom > myRect.top) return raw
+        return raw - drawerRect.height
+      },
+    })
+  }, [onToggle, ticket.id])
+
   const rightBadges = (
     <>
       <StatusBadge
@@ -93,12 +145,14 @@ export function HelpCenterCard({
 
   return (
     <div
+      ref={rowRef}
+      style={{ scrollMarginTop: STICKY_HEADER_OFFSET_PX }}
       className={`border-b border-ods-border last:border-b-0 ${optimistic ? 'opacity-60' : ''}`}
       aria-busy={optimistic || undefined}
     >
       <button
         type="button"
-        onClick={isExpandable ? () => onToggle(ticket.id) : undefined}
+        onClick={isExpandable ? handleClick : undefined}
         disabled={!isExpandable}
         aria-expanded={isExpandable ? isExpanded : undefined}
         aria-controls={isExpanded ? `help-center-drawer-${ticket.id}` : undefined}

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

@@ -264,7 +264,15 @@ function HelpCenterListAuthed({
               />
             )
           ) : (
-            <div className="bg-ods-card border border-ods-border rounded-[6px] overflow-hidden w-full">
+            // `overflow-clip` (NOT `overflow-hidden`) — both visually
+            // clip the rounded corners, but `hidden` makes the element
+            // a "scroll container" per CSSOM spec, which causes
+            // `scrollIntoView` calls inside (`<HelpCenterCard>` click
+            // handlers) to try scrolling THIS div (can't, overflow
+            // hidden) instead of bubbling up to the window. `clip`
+            // keeps the visual clip but NOT the scroll-container
+            // status, so click-to-scroll actually moves the page.
+            <div className="bg-ods-card border border-ods-border rounded-[6px] overflow-clip w-full">
               {merged.map((ticket) => (
                 <HelpCenterCard
                   key={ticket.id}

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

@@ -212,9 +212,16 @@ function TicketTimelinePanel({ ticket }: { ticket: AnyTicket }) {
   return (
     <div className="bg-ods-card border border-ods-border rounded-[6px] overflow-hidden w-full">
       {/* Customer-authored description + any legacy `---`-joined
-          comments. Original message gets a special role label; legacy
-          updates get "Update N" or "Resolution". Timestamp matches the
-          ticket's creation time when available. */}
+          comments. Always rendered ABOVE the engagement timeline as
+          "Original message" because the server's intake-burst filter
+          (see `filterCustomerVisibleTimeline` in
+          `hubspot-conversations-utils.ts`) drops the customer's first
+          message from engagements when it was part of the HubSpot
+          Custom Channel bot intake — bodyTurns IS the canonical
+          original for those tickets. For tickets created without bot
+          intake (admin-created, email channel) bodyTurns shows the
+          manually-entered description and engagements show subsequent
+          replies — same flow, no duplication. */}
       {bodyTurns.map((turn, i) => {
         const isResolution = turn.startsWith('[Resolution]')
         const role =
@@ -315,11 +322,19 @@ function TicketTimelinePanel({ ticket }: { ticket: AnyTicket }) {
           avatarSrc = undefined
         }
 
+        // Role label: every engagement is a customer-visible
+        // Conversations message (customer ↔ agent on the Custom
+        // Channel). There are no internal Notes on this surface
+        // anymore — the read path explicitly filters them. So
+        // "Reply" for BOTH sides. The previous "Note" label for
+        // support bubbles was a legacy artifact from when Notes
+        // were rendered and made customers think their support
+        // engineer was leaving internal comments on their ticket.
         return (
           <ConversationCardRow
             key={eng.id}
             author={author}
-            role={isCustomer ? 'Reply' : 'Note'}
+            role="Reply"
             avatarSrc={avatarSrc}
             timestamp={eng.createdAt}
             body={stripAttachmentsPreamble(eng.body ?? '')}

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

@@ -18,7 +18,7 @@
  *      rendered only when this row is the expanded one.
  */
 
-import { useEffect, useRef } from 'react'
+import { useCallback, useRef } from 'react'
 import {
   Collapsible,
   CollapsibleContent,
@@ -28,6 +28,7 @@ import {
   type ChatTicketItemData,
 } from '../chat/entity-cards/chat-ticket-item'
 import { formatRelativeTime } from '../../utils/date-utils'
+import { scrollElementIntoView } from '../../utils/scroll-into-view'
 import {
   TicketDetailDrawer,
   type TicketDetailDrawerProps,
@@ -64,25 +65,35 @@ export function TicketRow({
   // arrived yet, so action targets would be undefined.
   const optimistic = isOptimistic(ticket)
 
-  // Scroll the row's summary tile to the top of the viewport when the
-  // user expands it. Without this, expanding a row near the bottom of
-  // the viewport leaves most of the drawer (timeline + composer)
-  // hidden — the user has to scroll manually to see what they just
-  // opened.
+  // Scroll the clicked card to the top of the viewport. Every click
+  // scrolls — first-click expansion, same-row re-click, cross-row
+  // switch. The clicked card lands at the top.
   //
-  // Uses smooth-scroll + `block: 'start'` so the tile lands at the top
-  // edge. Two RAFs let the Collapsible's height animation start before
-  // we measure the row position, otherwise the scroll lands at the
-  // pre-expansion position.
+  // Cross-row gotcha: if ANOTHER row above this one is currently
+  // expanded, its drawer is about to collapse simultaneously with our
+  // toggle. We pre-subtract its height from the target Y so the
+  // smooth-scroll lands at the FINAL post-collapse position cleanly.
+  // Same pattern as `<HelpCenterCard>` — the only diff is the drawer
+  // id prefix (`ticket-drawer-` vs `help-center-drawer-`).
   const rowRef = useRef<HTMLDivElement | null>(null)
-  useEffect(() => {
-    if (!expanded || optimistic) return
-    requestAnimationFrame(() => {
-      requestAnimationFrame(() => {
-        rowRef.current?.scrollIntoView({ behavior: 'smooth', block: 'start' })
-      })
+  const handleClick = useCallback(() => {
+    onToggle(ticket.id)
+    scrollElementIntoView(rowRef.current, {
+      adjustTargetY: (raw) => {
+        if (!rowRef.current) return raw
+        const expandedDrawer = document.querySelector(
+          'div[id^="ticket-drawer-"]',
+        )
+        if (!(expandedDrawer instanceof HTMLElement)) return raw
+        const drawerRect = expandedDrawer.getBoundingClientRect()
+        const myRect = rowRef.current.getBoundingClientRect()
+        // Only adjust when the drawer is ABOVE us. Drawers below
+        // don't shift our position when they collapse.
+        if (drawerRect.bottom > myRect.top) return raw
+        return raw - drawerRect.height
+      },
     })
-  }, [expanded, optimistic])
+  }, [onToggle, ticket.id])
 
   const tileData: ChatTicketItemData = {
     id: ticket.id,
@@ -112,14 +123,14 @@ export function TicketRow({
   }
 
   return (
-    <div ref={rowRef} className="scroll-mt-4">
+    <div ref={rowRef} className="scroll-mt-24">
       <Collapsible
         open={expanded && !optimistic}
         className="border-b border-ods-border last:border-b-0"
       >
       <ChatTicketItem
         ticket={tileData}
-        onClick={optimistic ? undefined : onToggle}
+        onClick={optimistic ? undefined : handleClick}
         aria-expanded={expanded && !optimistic}
         aria-controls={`ticket-drawer-${ticket.id}`}
       />

package/src/contexts/chat-runtime-context.tsx

@@ -62,12 +62,15 @@ export interface ChatRuntime {
      *      relative `/api/storage/view/chat-attachments/` is sufficient
      *      (same-origin); embedders supply an absolute hub URL so the
      *      browser can fetch cross-origin.
-     *    - `chatIdentityUrl` — GET endpoint the `useChatIdentity` hook
+     *    - `identityUrl` — GET endpoint the `useChatIdentity` hook
      *      hits to learn the `{authTier, source, attachmentsEnabled}`
-     *      capability bag for the current session. */
+     *      capability bag for the current session. Used beyond chat
+     *      (tickets / contact form / any embedded surface that needs
+     *      to identify the proxied customer), so the name has no
+     *      "chat" prefix even though the consuming hook still does. */
     attachmentUploadUrl: string
     attachmentViewUrlPrefix: string
-    chatIdentityUrl: string
+    identityUrl: string
     /** Optional URL prefix for the image proxy (`<prefix>?url=<external>`).
      *  When unset, lib's `getProxiedImageUrl` returns the original URL
      *  unchanged. Hub default: '/api/image-proxy'. Embedders that don't

package/src/nats/index.ts

@@ -1 +1,4 @@
 export * from './nats'
+export * from './shared-connection'
+export * from './nats-provider'
+export * from './use-nats-subscription'

package/src/nats/nats-provider.tsx

@@ -0,0 +1,146 @@
+'use client'
+
+import * as React from 'react'
+import type { NatsClient, NatsStatus } from './nats'
+import {
+  acquireClient,
+  releaseClient,
+  startConnectionLifecycle,
+  type AcquireClientOptions,
+  type NatsReconnectionBackoff,
+} from './shared-connection'
+
+export type { NatsReconnectionBackoff } from './shared-connection'
+
+export interface NatsProviderProps {
+  children: React.ReactNode
+  /** Return the current NATS WebSocket URL (or null when not yet available, e.g. unauthenticated). */
+  getWsUrl: () => string | null
+  /** Called before each reconnect attempt. */
+  onBeforeReconnect?: () => Promise<void> | void
+  clientConfig?: AcquireClientOptions
+  reconnectionBackoff?: NatsReconnectionBackoff
+  /**
+   * Bump this to force re-evaluating `getWsUrl()` (e.g. when auth state flips).
+   * Provider does not subscribe to external auth state by itself.
+   */
+  urlRevision?: unknown
+}
+
+export interface NatsContextValue {
+  client: NatsClient | null
+  status: NatsStatus
+  isReady: boolean
+  reconnectionCount: number
+}
+
+const NatsContext = React.createContext<NatsContextValue | null>(null)
+
+export function NatsProvider({
+  children,
+  getWsUrl,
+  onBeforeReconnect,
+  clientConfig,
+  reconnectionBackoff,
+  urlRevision,
+}: NatsProviderProps) {
+  const [client, setClient] = React.useState<NatsClient | null>(null)
+  const [status, setStatus] = React.useState<NatsStatus>('closed')
+  const [reconnectionCount, setReconnectionCount] = React.useState(0)
+
+  const getWsUrlRef = React.useRef(getWsUrl)
+  React.useEffect(() => {
+    getWsUrlRef.current = getWsUrl
+  }, [getWsUrl])
+
+  const onBeforeReconnectRef = React.useRef(onBeforeReconnect)
+  React.useEffect(() => {
+    onBeforeReconnectRef.current = onBeforeReconnect
+  }, [onBeforeReconnect])
+
+  const reconnectionBackoffRef = React.useRef(reconnectionBackoff)
+  React.useEffect(() => {
+    reconnectionBackoffRef.current = reconnectionBackoff
+  }, [reconnectionBackoff])
+
+  const clientConfigRef = React.useRef(clientConfig)
+  React.useEffect(() => {
+    clientConfigRef.current = clientConfig
+  }, [clientConfig])
+
+  const heldUrlRef = React.useRef<string | null>(null)
+  const hadConnectionBeforeRef = React.useRef(false)
+
+  React.useEffect(() => {
+    const wsUrl = getWsUrlRef.current()
+
+    if (!wsUrl) {
+      if (heldUrlRef.current) {
+        releaseClient(heldUrlRef.current)
+        heldUrlRef.current = null
+        setClient(null)
+        setStatus('closed')
+      }
+      return
+    }
+
+    if (heldUrlRef.current && heldUrlRef.current !== wsUrl) {
+      releaseClient(heldUrlRef.current)
+      heldUrlRef.current = null
+    }
+
+    const conn = acquireClient(wsUrl, clientConfigRef.current)
+    heldUrlRef.current = wsUrl
+    setClient(conn.client)
+    setStatus(conn.client.isConnected() ? 'connected' : 'connecting')
+
+    const lifecycle = startConnectionLifecycle({
+      conn,
+      wsUrl,
+      onBeforeReconnect: () => onBeforeReconnectRef.current?.(),
+      backoff: reconnectionBackoffRef.current,
+      getFreshUrl: () => getWsUrlRef.current(),
+      onStatusChange: (newStatus) => {
+        setStatus(newStatus)
+        if (newStatus === 'connected') {
+          if (hadConnectionBeforeRef.current) {
+            setReconnectionCount((c) => c + 1)
+          }
+          hadConnectionBeforeRef.current = true
+        }
+      },
+    })
+
+    return () => {
+      lifecycle.stop()
+      if (heldUrlRef.current) {
+        releaseClient(heldUrlRef.current)
+        heldUrlRef.current = null
+      }
+      setClient(null)
+      setStatus('closed')
+    }
+  }, [urlRevision])
+
+  const value = React.useMemo<NatsContextValue>(
+    () => ({
+      client,
+      status,
+      isReady: status === 'connected' && client !== null,
+      reconnectionCount,
+    }),
+    [client, status, reconnectionCount],
+  )
+
+  return <NatsContext.Provider value={value}>{children}</NatsContext.Provider>
+}
+
+export function useNats(): NatsContextValue {
+  const ctx = React.useContext(NatsContext)
+  if (!ctx) throw new Error('useNats must be used inside <NatsProvider>')
+  return ctx
+}
+
+export function useOptionalNats(): NatsContextValue | null {
+  return React.useContext(NatsContext)
+}

package/src/nats/nats.ts

@@ -9,6 +9,8 @@ import type {
   Subscription,
 } from 'nats.ws'
 
+export type { JsMsg, Msg, Subscription } from 'nats.ws'
+
 export type JetStreamDeliverPolicy = 'new' | 'byStartSequence'
 
 export interface JetStreamOrderedSubscribeOptions {