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

package/dist/utils/scroll-into-view.d.ts

@@ -0,0 +1,63 @@
+/**
+ * `scrollElementIntoView` — canonical "smooth scroll element to top
+ * of viewport, account for sticky chrome, optionally adjust for
+ * known layout shifts" helper.
+ *
+ * Before this util existed, ~3 different call sites in the lib + hub
+ * had the same 5-line snippet copy-pasted with subtle differences:
+ *
+ *   - `useUnifiedNav` same-URL re-scroll branch (hub)
+ *   - `<HelpCenterCard>` click-to-expand (lib, with cross-row
+ *     layout-shift adjustment)
+ *   - Future ticket-row / docs anchor scrolls
+ *
+ * The canonical pattern is `window.scrollTo({top, behavior:'smooth'})`
+ * with a pre-computed pixel target — NOT `element.scrollIntoView()`.
+ * Pre-computing the target lets the browser run a clean uninterrupted
+ * smooth animation to a fixed pixel value. `scrollIntoView` re-targets
+ * continuously as the page layout shifts during the animation, which
+ * causes visible jitter when content above the target is also moving
+ * (a sibling collapsing, an async image loading, …).
+ *
+ * The `adjustTargetY` callback is the escape hatch for cases where
+ * the consumer KNOWS about an upcoming layout shift and can compute
+ * the correct FINAL target before the animation starts. Example: in
+ * `HelpCenterCard`, clicking row B while row A above is currently
+ * expanded — A's drawer collapses simultaneously with B's expansion,
+ * shifting B's tile up by A's drawer height. The consumer passes
+ * `adjustTargetY: raw => raw - getAboveDrawerHeight()` and the
+ * browser smooth-scrolls to the post-collapse position directly.
+ */
+export interface ScrollElementIntoViewOptions {
+    /** Pixels to subtract from the target element's `top` so it lands
+     *  BELOW sticky chrome. Defaults to 0. Pass `96` (matches
+     *  `scroll-mt-24`) for the standard hub header offset. */
+    headerOffset?: number;
+    /** Scroll animation style. Defaults to `'smooth'`. Use `'instant'`
+     *  for imperative jumps where animation would feel laggy (deep
+     *  link land, programmatic focus moves). */
+    behavior?: ScrollBehavior;
+    /** Optional adjustment applied to the computed pixel target. The
+     *  callback receives the "raw" Y (`element.top + scrollY -
+     *  headerOffset`) and returns the FINAL pixel target. Use this
+     *  when the caller knows about a layout shift that will happen
+     *  between the call and the animation completing — the browser's
+     *  smooth-scroll commits to a single pixel value, so providing the
+     *  post-shift target up front lands the element correctly even as
+     *  content above it moves. */
+    adjustTargetY?: (rawTargetY: number) => number;
+}
+/**
+ * Scroll the page so `target` lands at the top of the viewport,
+ * accounting for sticky chrome via `headerOffset`. Returns void; the
+ * scroll runs async via the browser's smooth-scroll engine.
+ *
+ * Accepts:
+ *   - `HTMLElement` — direct reference (most common from `useRef`).
+ *   - `null` / `undefined` — no-op so callers can pass refs without
+ *     defensive branching.
+ *
+ * SSR-safe: short-circuits when `window` is undefined.
+ */
+export declare function scrollElementIntoView(target: HTMLElement | null | undefined, options?: ScrollElementIntoViewOptions): void;
+//# sourceMappingURL=scroll-into-view.d.ts.map

package/dist/utils/scroll-into-view.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scroll-into-view.d.ts","sourceRoot":"","sources":["../../src/utils/scroll-into-view.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,MAAM,WAAW,4BAA4B;IAC3C;;8DAE0D;IAC1D,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB;;gDAE4C;IAC5C,QAAQ,CAAC,EAAE,cAAc,CAAA;IACzB;;;;;;;kCAO8B;IAC9B,aAAa,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,MAAM,CAAA;CAC/C;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,WAAW,GAAG,IAAI,GAAG,SAAS,EACtC,OAAO,GAAE,4BAAiC,GACzC,IAAI,CAON"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flamingo-stack/openframe-frontend-core",
-  "version": "0.0.210",
+  "version": "0.0.212-snapshot.20260528112413",
   "description": "Shared design system and components for all Flamingo platforms",
   "type": "module",
   "main": "./dist/index.js",

package/src/components/chat/hooks/use-chat-identity.ts

@@ -8,8 +8,9 @@
  * (attachment button, drawer composer, /tickets gate) on chat-side
  * identity tiers WITHOUT sending a chat message first.
  *
- * Server-side parity: the route at `/api/chat/identity` runs the same
- * 3-tier `requireChatAuth` chain the chat itself uses.
+ * Server-side parity: the host's identity endpoint (hub default
+ * `/api/auth/identity`, override via `runtime.endpoints.identityUrl`)
+ * runs the same 3-tier `requireChatAuth` chain the chat itself uses.
  * `attachmentsEnabled` is computed server-side as
  * `authTier !== 'anon' AND isSelfScopedSource(source)` — single
  * source of truth, consumers don't combine the fields themselves.
@@ -27,7 +28,7 @@
  *   3. The fetch is cheap and short — no perf justification for a
  *      cache layer
  *
- * Endpoint URL: read from `useRequiredChatRuntime().endpoints.chatIdentityUrl`
+ * Endpoint URL: read from `useRequiredChatRuntime().endpoints.identityUrl`
  * so embedded apps with their own reverse-proxy topology can override.
  */
 
@@ -37,9 +38,9 @@ import { chatAuthedFetch } from '../utils/chat-authed-fetch'
 import { getChatProxyAuth } from '../utils/chat-proxy-auth-storage'
 
 /**
- * Wire-shape for the `/api/chat/identity` route response. Mirrors
- * the hub's `ChatIdentityResponse` (in `app/api/chat/identity/route.ts`)
- * — kept in sync there. Lib-side declaration so the chat panel can
+ * Wire-shape for the identity route response. Mirrors the hub's
+ * `ChatIdentityResponse` (in `app/api/auth/identity/route.ts`) —
+ * kept in sync there. Lib-side declaration so the chat panel can
  * compile without depending on hub-internal types.
  */
 export interface ChatIdentityResponse {
@@ -87,7 +88,7 @@ const ANON_DEFAULTS: ChatIdentityResponse = {
 
 export function useChatIdentity(): ChatIdentitySurface {
   const runtime = useRequiredChatRuntime()
-  const url = runtime.endpoints.chatIdentityUrl
+  const url = runtime.endpoints.identityUrl
   // `getChatProxyAuth()` reads localStorage every render. If the user
   // pastes bearer creds mid-session (via the `/debug` creds bar),
   // their email arrives here and the effect's dep changes → refetch.

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

@@ -1,28 +1,19 @@
 'use client'
 
-import { useCallback, useEffect, useRef, useState } from 'react'
+import { useEffect, useRef, useState } from 'react'
 import {
-  createNatsClient,
+  acquireClient as acquireSharedClient,
+  releaseClient as releaseSharedClient,
+  startConnectionLifecycle,
   type JetStreamSubscriptionHandle,
   type NatsClient,
+  type SharedConnection,
 } from '../../../nats'
 import {
   type UseJetStreamDialogSubscriptionOptions,
   type UseJetStreamDialogSubscriptionReturn,
-  NETWORK_CONFIG,
 } from '../types'
 
-type SharedConnection = {
-  wsUrl: string
-  client: NatsClient
-  connectPromise: Promise<void> | null
-  refCount: number
-  closeTimer: ReturnType<typeof setTimeout> | null
-  retryTimer: ReturnType<typeof setTimeout> | null
-}
-
-let shared: SharedConnection | null = null
-
 const DEFAULT_INACTIVE_THRESHOLD_MS = 5 * 60_000
 const DEFAULT_STREAM_NAME = 'CHAT_CHUNKS'
 
@@ -110,75 +101,23 @@ export function useJetStreamDialogSubscription({
 
   const hadConnectionBeforeRef = useRef(false)
 
-  const acquireClient = useCallback(
-    (url: string): SharedConnection => {
-      if (shared?.wsUrl !== url) {
-        if (shared) {
-          if (shared.closeTimer) clearTimeout(shared.closeTimer)
-          const old = shared
-          shared = null
-          void old.client.close().catch(() => {})
-        }
-
-        const { name = 'openframe-frontend-jetstream', user = 'machine', pass = '' } = clientConfig
-
-        const client = createNatsClient({
-          servers: url,
-          name,
-          user,
-          pass,
-          connectTimeoutMs: NETWORK_CONFIG.CONNECT_TIMEOUT_MS,
-          reconnect: false,
-          pingIntervalMs: NETWORK_CONFIG.PING_INTERVAL_MS,
-          maxPingOut: NETWORK_CONFIG.MAX_PING_OUT,
-        })
-        shared = {
-          wsUrl: url,
-          client,
-          connectPromise: null,
-          refCount: 0,
-          closeTimer: null,
-          retryTimer: null,
-        }
-      }
-
-      shared.refCount += 1
-      if (shared.closeTimer) {
-        clearTimeout(shared.closeTimer)
-        shared.closeTimer = null
-      }
-      return shared
-    },
-    [clientConfig],
-  )
-
-  const releaseClient = useCallback((url: string) => {
-    if (!shared || shared.wsUrl !== url) return
-
-    shared.refCount = Math.max(0, shared.refCount - 1)
-    if (shared.refCount > 0) return
-
-    shared.closeTimer = setTimeout(() => {
-      const s = shared
-      shared = null
-      if (s) {
-        if (s.retryTimer) {
-          clearTimeout(s.retryTimer)
-          s.retryTimer = null
-        }
-        void s.client.close().catch(() => {})
-      }
-    }, NETWORK_CONFIG.SHARED_CLOSE_DELAY_MS)
-  }, [])
+  const clientConfigRef = useRef(clientConfig)
+  useEffect(() => {
+    clientConfigRef.current = clientConfig
+  }, [clientConfig])
 
   const currentWsUrlRef = useRef<string>('')
 
-  // Connection lifecycle: acquire/release the shared client based on enabled + URL.
+  // Resolve the URL synchronously each render so the effect depends on the URL string
+  // itself, not the (often inline-allocated) getNatsWsUrl callback identity. Otherwise
+  // every silent token rotation that rebuilds getNatsWsUrl in the caller would tear
+  // the WS down and reacquire even though the resolved URL hasn't changed.
+  const wsUrl = getNatsWsUrl()
+
   useEffect(() => {
-    const wsUrl = getNatsWsUrl()
     if (!enabled || !wsUrl) {
       if (currentWsUrlRef.current && clientRef.current) {
-        releaseClient(currentWsUrlRef.current)
+        releaseSharedClient(currentWsUrlRef.current)
         clientRef.current = null
         currentWsUrlRef.current = ''
         setIsConnected(false)
@@ -199,166 +138,80 @@ export function useJetStreamDialogSubscription({
       currentWsUrlRef.current !== wsUrl &&
       clientRef.current
     ) {
-      releaseClient(currentWsUrlRef.current)
+      releaseSharedClient(currentWsUrlRef.current)
       clientRef.current = null
       setIsConnected(false)
     }
 
     currentWsUrlRef.current = wsUrl
-    const sharedConn = acquireClient(wsUrl)
+    const cfg = clientConfigRef.current
+    const sharedConn = acquireSharedClient(wsUrl, {
+      name: cfg.name ?? 'openframe-frontend-jetstream',
+      user: cfg.user ?? 'machine',
+      pass: cfg.pass ?? '',
+    })
     const client = sharedConn.client
 
     clientRef.current = client
-    setIsConnected(false)
-
-    let closed = false
-    let retryAttempt = 0
-
-    function scheduleRetry() {
-      if (closed) return
-      if (shared !== sharedConn) return
-
-      if (sharedConn.retryTimer) {
-        clearTimeout(sharedConn.retryTimer)
-        sharedConn.retryTimer = null
-      }
-
-      const cfg = reconnectionBackoffRef.current ?? {}
-      const fastRetries = cfg.fastRetries ?? 0
-      const fastDelay = cfg.fastRetryDelayMs ?? NETWORK_CONFIG.RETRY_INITIAL_DELAY_MS
-      const baseDelay = cfg.initialDelayMs ?? NETWORK_CONFIG.RETRY_INITIAL_DELAY_MS
-      const maxDelay = cfg.maxDelayMs ?? NETWORK_CONFIG.RETRY_MAX_DELAY_MS
-      const multiplier = cfg.multiplier ?? NETWORK_CONFIG.RETRY_BACKOFF_MULTIPLIER
-
-      const delay =
-        retryAttempt < fastRetries
-          ? fastDelay
-          : Math.min(baseDelay * multiplier ** (retryAttempt - fastRetries), maxDelay)
-      const jitteredDelay = delay * (0.5 + Math.random() * 0.5)
-      retryAttempt++
-
-      sharedConn.retryTimer = setTimeout(async () => {
-        sharedConn.retryTimer = null
-        if (closed) return
-        if (shared !== sharedConn) return
-
-        try {
-          await onBeforeReconnectRef.current?.()
-        } catch {
-          // Token refresh failed; still try to reconnect.
-        }
-
-        if (closed) return
-        if (shared !== sharedConn) return
-
-        const freshUrl = getNatsWsUrlRef.current()
-        if (freshUrl !== wsUrl) return
+    setIsConnected(client.isConnected())
 
+    const tearDownSubscription = () => {
+      if (subscriptionRef.current) {
         try {
-          sharedConn.connectPromise = null
-          sharedConn.connectPromise = client.connect()
-          await sharedConn.connectPromise
-          if (!closed && shared === sharedConn) {
-            retryAttempt = 0
-            setIsConnected(true)
-          }
+          subscriptionRef.current.unsubscribe()
         } catch {
-          sharedConn.connectPromise = null
-          if (!closed && shared === sharedConn) {
-            scheduleRetry()
-          }
-        }
-      }, jitteredDelay)
-    }
-
-    const unsubscribeStatus = client.onStatus((event) => {
-      const connected = event.status === 'connected'
-      // `error` is a protocol-level signal (e.g. -ERR Permissions Violation when
-      // CONSUMER.CREATE is denied) that does NOT close the WebSocket. Treating
-      // it as a disconnect causes scheduleRetry() to fire on every -ERR, which
-      // re-runs onBeforeReconnect (auth refresh / `/api/me`) on a loop. Real
-      // transport loss arrives separately as `disconnected` or `closed`.
-      const disconnected = event.status === 'closed' || event.status === 'disconnected'
-      if (connected) {
-        setIsConnected(true)
-        if (hadConnectionBeforeRef.current) {
-          setReconnectionCount((c) => c + 1)
-        }
-        hadConnectionBeforeRef.current = true
-        retryAttempt = 0
-        onConnectRef.current?.()
-      }
-      if (event.status === 'error') {
-        // Subscription-level failures (e.g. consumer.get rejected by JetStream
-        // ACLs) already surface to the subscribe effect via the rejected
-        // promise; log here for diagnostics and let the existing WS connection
-        // keep running.
-        console.warn('[JetStream] NATS protocol error:', event.data)
-        return
-      }
-      if (disconnected) {
-        setIsConnected(false)
-        setIsSubscribed(false)
-
-        if (subscriptionRef.current) {
-          try {
-            subscriptionRef.current.unsubscribe()
-          } catch {
-            // ignore
-          }
-          subscriptionRef.current = null
+          // ignore
         }
-
-        onDisconnectRef.current?.()
-        scheduleRetry()
+        subscriptionRef.current = null
       }
-    })
+    }
 
-    ;(async () => {
-      try {
-        sharedConn.connectPromise ||= client.connect()
-        await sharedConn.connectPromise
-        if (!closed) {
+    const lifecycle = startConnectionLifecycle({
+      conn: sharedConn,
+      wsUrl,
+      onBeforeReconnect: () => onBeforeReconnectRef.current?.(),
+      backoff: reconnectionBackoffRef.current,
+      getFreshUrl: () => getNatsWsUrlRef.current(),
+      // JetStream emits 'error' for protocol-level failures (e.g. -ERR Permissions
+      // Violation when CONSUMER.CREATE is denied) without closing the WebSocket.
+      // Retrying on 'error' would loop onBeforeReconnect on every -ERR; let the
+      // subscribe effect surface those via its own rejected promise instead.
+      shouldRetryOn: (status) => status === 'closed' || status === 'disconnected',
+      onStatusChange: (status, evt) => {
+        if (status === 'connected') {
           setIsConnected(true)
+          if (hadConnectionBeforeRef.current) {
+            setReconnectionCount((c) => c + 1)
+          }
           hadConnectionBeforeRef.current = true
+          onConnectRef.current?.()
         }
-      } catch {
-        sharedConn.connectPromise = null
-        if (!closed) {
+        if (status === 'error') {
+          console.warn('[JetStream] NATS protocol error:', evt.data)
+          return
+        }
+        if (status === 'closed' || status === 'disconnected') {
           setIsConnected(false)
+          setIsSubscribed(false)
+          tearDownSubscription()
           onDisconnectRef.current?.()
-          scheduleRetry()
         }
-      }
-    })()
+      },
+    })
 
     return () => {
-      closed = true
+      lifecycle.stop()
       setIsConnected(false)
       setIsSubscribed(false)
-      unsubscribeStatus()
-
-      if (sharedConn.retryTimer) {
-        clearTimeout(sharedConn.retryTimer)
-        sharedConn.retryTimer = null
-      }
-
-      if (subscriptionRef.current) {
-        try {
-          subscriptionRef.current.unsubscribe()
-        } catch {
-          // ignore
-        }
-        subscriptionRef.current = null
-      }
+      tearDownSubscription()
 
       if (clientRef.current && currentWsUrlRef.current) {
-        releaseClient(currentWsUrlRef.current)
+        releaseSharedClient(currentWsUrlRef.current)
         clientRef.current = null
         currentWsUrlRef.current = ''
       }
     }
-  }, [enabled, getNatsWsUrl, acquireClient, releaseClient])
+  }, [enabled, wsUrl])
 
   // Subscription lifecycle: (re)create the ephemeral JetStream consumer whenever
   // we transition into a connected state for a dialog, and whenever the dialog