@flamingo-stack/openframe-frontend-core 0.0.521 → 0.0.522-snapshot.20260807100640

package/src/components/chat/hooks/use-jetstream-dialog-subscription.ts

@@ -1,6 +1,6 @@
 'use client'
 
-import { useEffect, useRef, useState } from 'react'
+import { useCallback, useEffect, useRef, useState } from 'react'
 import {
   acquireClient as acquireSharedClient,
   releaseClient as releaseSharedClient,
@@ -20,7 +20,24 @@ const DEFAULT_STREAM_NAME = 'CHAT_CHUNKS'
  * absence worth resyncing for. Alt-tabbing must not churn the consumer; a
  * window that sat in the tray must not come back showing a stale conversation.
  */
-const RESYNC_AFTER_HIDDEN_MS = 10_000
+export const RESYNC_AFTER_HIDDEN_MS = 10_000
+/**
+ * How long resync requests are gathered before one is acted on.
+ *
+ * A single reveal can be reported twice: the page sees `visibilitychange`, and
+ * a host that knows the window was away reports it too (`resyncSignal`),
+ * neither able to tell whether the other noticed. Both land within a frame or
+ * two of each other, being driven by the same OS event, and acting on both
+ * rebuilds the consumer and refetches history twice for one reveal.
+ *
+ * Gathered on the TRAILING edge, so a request is deferred and never dropped.
+ * Two reports of one reveal collapse into one rebuild; two genuinely different
+ * signals — a notification reply landing just before the user opens the window
+ * — also collapse into one, which is correct, because a single refetch after
+ * the last of them covers both. The cost is a second of latency on a path whose
+ * next step is a network round trip.
+ */
+const RESYNC_COALESCE_MS = 1_000
 /**
  * Floor between two reported recoveries. Every recovery costs the caller a
  * history refetch, and a consumer that cannot hold its sequence — gap, reset,
@@ -60,6 +77,7 @@ export function useJetStreamDialogSubscription({
   clientConfig = {},
   reconnectionBackoff,
   inactiveThresholdMs,
+  resyncSignal = 0,
 }: UseJetStreamDialogSubscriptionOptions): UseJetStreamDialogSubscriptionReturn {
   const [isConnected, setIsConnected] = useState(false)
   const [isSubscribed, setIsSubscribed] = useState(false)
@@ -73,6 +91,8 @@ export function useJetStreamDialogSubscription({
   const [currentStreamSeq, setCurrentStreamSeq] = useState<number | null>(null)
 
   const lastRecoveryReportRef = useRef(0)
+  const resyncTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null)
+  const lastResyncSignalRef = useRef(resyncSignal)
   const clientRef = useRef<NatsClient | null>(null)
   const subscriptionRef = useRef<JetStreamSubscriptionHandle | null>(null)
   const highestStreamSeqRef = useRef<number | null>(null)
@@ -245,7 +265,26 @@ export function useJetStreamDialogSubscription({
   // ignoring optStartSeq).
   useEffect(() => {
     highestStreamSeqRef.current = null
+    // A host's signal counts per dialog (it can carry a per-conversation term),
+    // so the baseline has to move with the dialog or a switch to one with a
+    // LOWER count would swallow every later resync for it.
+    lastResyncSignalRef.current = resyncSignal
     setCurrentStreamSeq(null)
+    // A resync gathered for the previous dialog must not land on this one: the
+    // counter says nothing about which conversation it meant, so callers would
+    // refetch the wrong one. The dialog change supersedes it — the new dialog
+    // loads its own history regardless. As cleanup, so it covers unmount too,
+    // which is the same rule.
+    return () => {
+      if (resyncTimerRef.current !== null) {
+        clearTimeout(resyncTimerRef.current)
+        resyncTimerRef.current = null
+      }
+    }
+    // `resyncSignal` is read as the new baseline, not depended on: reacting to
+    // it here would reset the baseline on the very change meant to trigger a
+    // resync, and the effect below owns that.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [dialogId])
 
   // Coming back into view after a real absence is treated exactly like a
@@ -256,8 +295,20 @@ export function useJetStreamDialogSubscription({
   // report that: the tail simply stays quiet, and the conversation on screen
   // stays frozen at whatever was there when the window went away (the user's
   // manual fix is a page refresh, which is exactly the history refetch this
-  // triggers). Bumping the counter rebuilds the consumer from the last sequence
-  // seen AND tells callers to refetch history.
+  // triggers). Rebuilds the consumer from the last sequence seen AND tells
+  // callers to refetch history.
+  //
+  // Every source funnels through here (see `RESYNC_COALESCE_MS`). Restarting
+  // the timer rather than dropping is what makes that safe: a request is only
+  // ever folded into the one that follows it, never discarded.
+  const requestResync = useCallback(() => {
+    if (resyncTimerRef.current !== null) clearTimeout(resyncTimerRef.current)
+    resyncTimerRef.current = setTimeout(() => {
+      resyncTimerRef.current = null
+      setReconnectionCount((c) => c + 1)
+    }, RESYNC_COALESCE_MS)
+  }, [])
+
   useEffect(() => {
     if (!enabled) return
     let hiddenSince = document.visibilityState === 'hidden' ? Date.now() : 0
@@ -270,13 +321,27 @@ export function useJetStreamDialogSubscription({
       const awayMs = hiddenSince === 0 ? 0 : Date.now() - hiddenSince
       hiddenSince = 0
       if (awayMs >= RESYNC_AFTER_HIDDEN_MS) {
-        setReconnectionCount((c) => c + 1)
+        requestResync()
       }
     }
 
     document.addEventListener('visibilitychange', onVisibilityChange)
     return () => document.removeEventListener('visibilitychange', onVisibilityChange)
-  }, [enabled])
+  }, [enabled, requestResync])
+
+  useEffect(() => {
+    // Held, not consumed, while disabled: it fires once on enable instead.
+    // A host reports a signal against the conversation, not against this hook's
+    // readiness, so one arriving while the caller is still assembling the
+    // subscription describes a gap in the history the caller is fetching right
+    // now. Dropping it would leave that fetch's result stale with nothing left
+    // to say so.
+    if (!enabled) return
+    // The mount value is a baseline, not a signal.
+    if (resyncSignal <= lastResyncSignalRef.current) return
+    lastResyncSignalRef.current = resyncSignal
+    requestResync()
+  }, [enabled, resyncSignal, requestResync])
 
   // Subscription lifecycle: (re)create the ephemeral JetStream consumer whenever
   // we transition into a connected state for a dialog, and whenever the dialog

package/src/components/chat/types/api.types.ts

@@ -131,6 +131,22 @@ export interface UseJetStreamDialogSubscriptionOptions {
   /** Consumer inactivity threshold in ms before NATS auto-cleans it. Defaults to the
    *  client's, and applies only to the first consumer — recreations use nats.ws's. */
   inactiveThresholdMs?: number
+  /**
+   * A counter the host bumps when it knows, from outside the page, that the tail
+   * may have missed something.
+   *
+   * The hook's own detector is `visibilitychange`, which a browser tab reports
+   * honestly and an embedding shell may not — and which says nothing at all
+   * about a write made on the page's behalf while it was away. A host holding
+   * either kind of knowledge bumps this instead of hoping the page noticed.
+   *
+   * Treated exactly like a reconnect: the consumer is rebuilt from the highest
+   * sequence already seen, and `reconnectionCount` moves so callers refetch
+   * persisted history. Any increase counts; the value itself means nothing, and
+   * an increase arriving alongside a `visibilitychange` costs one rebuild, not
+   * two.
+   */
+  resyncSignal?: number
 }
 
 export interface UseJetStreamDialogSubscriptionReturn {
@@ -138,10 +154,12 @@ export interface UseJetStreamDialogSubscriptionReturn {
   isSubscribed: boolean
   /**
    * Incremented each time the live tail is re-established: a NATS reconnect, a
-   * JetStream ordered-consumer recreation, or the page returning to view after
-   * being hidden long enough to have missed something. All three mean the same
-   * thing to the caller — the tail may have skipped messages, so persisted
-   * history has to be refetched. Starts at 0.
+   * JetStream ordered-consumer recreation, the page returning to view after
+   * being hidden long enough to have missed something, or a host reporting the
+   * same via `resyncSignal`. All of them mean the same thing to the caller —
+   * the tail may have skipped messages, so persisted history has to be
+   * refetched. One absence counts once even when two sources report it.
+   * Starts at 0.
    */
   reconnectionCount: number
   /** Highest JetStream stream sequence observed so far (null before first delivery). */

package/src/components/chat/utils/__tests__/history-merge.test.ts

@@ -930,3 +930,102 @@ describe('mid-stream refetch (turn partially persisted)', () => {
     expect(ids(merged)).toEqual([U0.id, A0.id, PERSISTED_PARTIAL.id, unrelatedLive.id])
   })
 })
+
+describe('ordering of surviving realtime messages', () => {
+  // The merge concatenates: all persisted history, then every realtime message
+  // the coverage rules kept, each side in its own order. These pin that
+  // contract, which nothing asserted before — the suite tested only WHICH
+  // messages survive, never where they land — and which an attempt to
+  // chronologically interleave the two sides repeatedly broke.
+  const H_U0: TestMessage = { ...U0, streamSeq: 5 }
+  const H_A0: TestMessage = { ...A0, streamSeq: 10 }
+  /**
+   * Sent from a notification while the window was away, and persisted. NO
+   * `streamSeq`: the backend does not stamp user MESSAGE_REQUEST rows, which is
+   * the missing signal that makes interleaving guesswork.
+   */
+  const AWAY_U: TestMessage = {
+    id: 'bbbb0001',
+    role: 'user',
+    content: 'replied from a notification',
+    timestamp: t(3000),
+  }
+  /** Mingo's answer to it. Assistant rows DO carry a sequence. */
+  const AWAY_A: TestMessage = {
+    id: 'bbbb0002',
+    role: 'assistant',
+    content: txt('answered while the window was away'),
+    timestamp: t(3100),
+    streamSeq: 80,
+  }
+
+  it('appends surviving realtime messages after all persisted history', () => {
+    // A technician direct message the snapshot has not caught up with. Its own
+    // role's persisted max (H_U0, seq 5) is below it, so coverage keeps it.
+    const unpersistedDirect: TestMessage = {
+      id: 'direct-1500-old',
+      role: 'user',
+      content: 'a direct message history has not persisted yet',
+      timestamp: t(1500),
+      streamSeq: 40,
+    }
+    const merged = mergeHistoryWithRealtime({
+      processedHistory: [H_U0, H_A0, AWAY_U, AWAY_A],
+      existingMessages: [H_U0, H_A0, unpersistedDirect],
+      streamingMessageId: null,
+      historyFetchedAt: 9000,
+      historyMaxStreamSeq: 80,
+      realtimeSeenStreamSeq: 40,
+    })
+
+    expect(ids(merged)).toEqual([H_U0.id, H_A0.id, AWAY_U.id, AWAY_A.id, unpersistedDirect.id])
+  })
+
+  it('keeps survivors in store order, sequence or no sequence', () => {
+    // The guard against reordering the two kinds against each other: an
+    // optimistic bubble carries no sequence and a replayed direct message does,
+    // and sorting by sequence would render the user's question below the reply
+    // that came after it.
+    const optimistic: TestMessage = {
+      id: 'optimistic-9400-x',
+      role: 'user',
+      content: 'just typed, no seq of its own',
+      timestamp: t(9400),
+    }
+    const laterDirect: TestMessage = {
+      id: 'direct-9500-x',
+      role: 'user',
+      content: 'and a direct message after it',
+      timestamp: t(9500),
+      streamSeq: 40,
+    }
+    const merged = mergeHistoryWithRealtime({
+      processedHistory: [H_U0, H_A0, AWAY_U, AWAY_A],
+      existingMessages: [H_U0, H_A0, optimistic, laterDirect],
+      streamingMessageId: null,
+      // Before either was minted, so neither can be in the snapshot.
+      historyFetchedAt: 9000,
+      historyMaxStreamSeq: 80,
+      realtimeSeenStreamSeq: 40,
+    })
+
+    expect(ids(merged)).toEqual([H_U0.id, H_A0.id, AWAY_U.id, AWAY_A.id, optimistic.id, laterDirect.id])
+  })
+
+  it('keeps history in snapshot order even when its sequences do not climb', () => {
+    // The snapshot is the server's account of the conversation; the merge is
+    // not entitled to second-guess it from a `streamSeq` that looks out of
+    // order, which is what any sort of the two sides together would do.
+    const outOfOrder: TestMessage = { ...H_A0, id: 'aaaa0009', streamSeq: 3 }
+    const merged = mergeHistoryWithRealtime({
+      processedHistory: [H_U0, outOfOrder, AWAY_U, AWAY_A],
+      existingMessages: [H_U0],
+      streamingMessageId: null,
+      historyFetchedAt: 9000,
+      historyMaxStreamSeq: 80,
+      realtimeSeenStreamSeq: 0,
+    })
+
+    expect(ids(merged)).toEqual([H_U0.id, outOfOrder.id, AWAY_U.id, AWAY_A.id])
+  })
+})

package/src/components/ui/__tests__/tab-navigation.test.tsx

@@ -1,4 +1,4 @@
-import { describe, it, expect, beforeAll } from 'vitest'
+import { describe, it, expect, beforeAll, vi } from 'vitest'
 import { render, fireEvent, screen } from '@testing-library/react'
 import { mockReplace, setMockSearchParams } from '../../../../vitest.setup'
 import { TabNavigation, type TabItem } from '../tab-navigation'
@@ -156,4 +156,36 @@ describe('TabNavigation with urlSync', () => {
       expect(nav.active).toBe('general')
     })
   })
+  describe('the underline', () => {
+    it('is sized in real pixels rather than a scaled 1px bar', () => {
+      // Regression guard. The underline used to be `w-px` stretched with
+      // `scaleX(width)`, which is only exact when one CSS pixel lands on a whole
+      // device pixel. At 125%/150% OS scaling or any browser zoom the base is
+      // rasterized to the nearest whole device pixel and `scaleX` multiplies
+      // that rounding by the tab's width, so the bar rendered visibly shorter or
+      // longer than the tab it underlines — while `offsetWidth` had been right
+      // all along. Asserting the STYLE (not the pixels, which jsdom has none of)
+      // is what keeps the multiplier from coming back.
+      const widthSpy = vi.spyOn(HTMLElement.prototype, 'offsetWidth', 'get').mockReturnValue(120)
+      const leftSpy = vi.spyOn(HTMLElement.prototype, 'offsetLeft', 'get').mockReturnValue(40)
+
+      try {
+        setMockSearchParams(new URLSearchParams('tab=general'))
+        const { container } = render(
+          <TabNavigation tabs={TABS} urlSync>
+            {() => null}
+          </TabNavigation>
+        )
+
+        const underline = container.querySelector('[aria-hidden]') as HTMLElement
+        expect(underline.style.width).toBe('120px')
+        expect(underline.style.transform).toBe('translateX(40px)')
+        expect(underline.style.transform).not.toContain('scaleX')
+        expect(underline.className).not.toContain('w-px')
+      } finally {
+        widthSpy.mockRestore()
+        leftSpy.mockRestore()
+      }
+    })
+  })
 })

package/src/components/ui/tab-navigation.tsx

@@ -231,12 +231,29 @@ const TabBar = memo(function TabBar({
     return { background: c }
   }, [leftFade, rightFade])
 
-  // A 1px bar scaled to width, rather than an animated `left`/`width` pair:
-  // transform and opacity are the only two properties the compositor can
-  // animate without laying the strip out again on every frame.
+  // Real width, moved by `translateX`. This used to be a 1px bar stretched with
+  // `scaleX(width)` — transform and opacity being the only properties the
+  // compositor can animate without laying out again — but scaling from a ONE
+  // PIXEL base turns that pixel into an error multiplier.
+  //
+  // A CSS pixel only lands on a whole device pixel at integer scale factors. At
+  // 125% / 150% OS scaling, a scaled Mac resolution, or any browser zoom, the
+  // base is rasterized at the nearest whole device pixel — call it 0.8 or 1.33
+  // CSS px — and `scaleX(150)` multiplies that rounding by 150. The underline
+  // then renders a fifth short or a third long, per tab, with `measureIndicator`
+  // having been perfectly correct all along. It shows up from the SECOND tab
+  // change on, because that is when the transition promotes the bar into its own
+  // composited layer, where it is rasterized in its own 1×4 coordinate space and
+  // only then stretched.
+  //
+  // Animating `width` costs a layout per frame for this one element — it is
+  // `absolute`, so nothing else in the strip is laid out with it, and 200ms of
+  // that for a 4px-tall bar is not measurable. Correctness at every zoom level
+  // is worth more than keeping one property on the compositor.
   const isPlaced = indicator.width > 0
   const indicatorStyle: React.CSSProperties = {
-    transform: `translateX(${indicator.left}px) scaleX(${indicator.width})`,
+    width: `${indicator.width}px`,
+    transform: `translateX(${indicator.left}px)`,
     opacity: isPlaced ? 1 : 0,
   }
   const shouldAnimateIndicator = hasPlacedIndicatorRef.current
@@ -302,13 +319,13 @@ const TabBar = memo(function TabBar({
         })}
 
         {/* One underline for the whole strip, sliding between tabs. Inside the
-            scroll container so it travels with the content; `origin-left` +
-            `w-px` make scaleX(n) read as "n pixels wide". */}
+            scroll container so it travels with the content. Width comes from the
+            style below in real pixels — see why it is not a scaled 1px bar. */}
         <div
           aria-hidden
           className={cn(
-            "pointer-events-none absolute bottom-0 left-0 h-1 w-px origin-left bg-ods-accent",
-            shouldAnimateIndicator && "transition-[transform,opacity] duration-200 ease-out motion-reduce:transition-none"
+            "pointer-events-none absolute bottom-0 left-0 h-1 bg-ods-accent",
+            shouldAnimateIndicator && "transition-[transform,width,opacity] duration-200 ease-out motion-reduce:transition-none"
           )}
           style={indicatorStyle}
         />