@flamingo-stack/openframe-frontend-core 0.0.216 → 0.0.217-snapshot.20260601151546

package/src/utils/embed-authed-fetch.ts

@@ -22,6 +22,117 @@
 
 import { applyProxyAuth } from './embed-proxy-auth-storage'
 
+// =============================================================================
+// Host-supplied auth adapter (opt-in)
+// =============================================================================
+
+/**
+ * Hosts that have their own auth model (cookie sessions, app-specific
+ * JWT in localStorage, OAuth access tokens, …) can register an adapter
+ * to override the lib's default `embedProxyAuth` flow. When set, the
+ * adapter's `getHeaders()` result is merged onto every `embedAuthedFetch`
+ * call AFTER the default proxy-auth header step (so adapter headers
+ * win over both caller and proxy values), and `credentials` overrides
+ * the default `'same-origin'` behaviour.
+ *
+ * Default (no adapter): MPH-style proxy-impersonation — bearer + act-as
+ * read from localStorage, `credentials: 'same-origin'`. No consumer
+ * needs to touch this unless they want a different auth model.
+ *
+ * Use cases:
+ *   - openframe-frontend has its own JWT in `localStorage.of_access_token`
+ *     and cookie-based session; register an adapter to attach the JWT
+ *     and request `credentials: 'include'` so cookies travel cross-origin
+ *     to the openframe gateway.
+ *   - Future embed hosts with OAuth access tokens, signed URLs, etc.
+ *
+ * Lifetime: setter is module-level (intentionally — `embedAuthedFetch`
+ * is a plain utility, not a hook, so it can't read React context). Host
+ * runtime providers should call `setEmbedAuthAdapter(...)` on mount and
+ * `setEmbedAuthAdapter(null)` on unmount. Multiple hosts registering at
+ * once is a programming error (one chat panel per app).
+ */
+export interface EmbedAuthAdapter {
+  /** Headers merged onto every embedded-fetch call. Return `{}` to add
+   *  nothing. Called per-request so reactive token refresh sees the latest
+   *  value from your auth store / storage. Values typed as
+   *  `string | undefined` so the common narrowed shape
+   *  `{ Authorization: token ? 'Bearer …' : undefined }` (or a conditional
+   *  `token ? { Authorization: … } : {}`) assigns cleanly — `undefined`
+   *  values are filtered before being merged into the request headers. */
+  getHeaders?: () => Record<string, string | undefined>
+  /** `RequestInit.credentials` mode. Default when no adapter: callers'
+   *  `init.credentials` or `'same-origin'`. Use `'include'` for cookie
+   *  auth against a different origin (CORS + `SameSite=None` required). */
+  credentials?: RequestCredentials
+  /**
+   * Optional 401 self-heal. When a request comes back `401`,
+   * `embedAuthedFetch` calls this once, and — if it resolves `true` —
+   * retries the SAME request exactly once with freshly-recomputed
+   * headers (so a rotated bearer from `getHeaders()` is picked up).
+   * Resolve `false` to surface the 401 to the caller unchanged.
+   *
+   * This is the capability the openframe `apiClient` has had all along
+   * (refresh-the-access-token-then-retry); registering it here gives the
+   * embedded chat/ticket surfaces the same self-healing auth instead of
+   * dying on an expired token. Concurrent 401s are de-duplicated by the
+   * wrapper, so this fires at most once per refresh cycle even when a
+   * stampede of chat requests all expire together — your implementation
+   * does NOT need its own in-flight guard (though a token-refresh manager
+   * that already dedups is harmless).
+   *
+   * Keep it idempotent and side-effect-light: on failure the wrapper just
+   * returns the original 401 — logout/redirect decisions belong to the
+   * host's own auth layer, not to this fetch wrapper.
+   */
+  refresh?: () => Promise<boolean>
+}
+
+/**
+ * The registered adapter is parked on `globalThis`, NOT in a module-private
+ * `let`. Reason: this lib ships multiple entry points (`/utils`,
+ * `/components/chat`, …) and a consumer's bundler can inline this file into
+ * more than one chunk — giving each chunk its OWN module scope. If the host
+ * calls `setEmbedAuthAdapter` from the `/utils` copy while the chat's
+ * `embedAuthedFetch` runs from the `/components/chat` copy, a module-local
+ * `let` would be set on one copy and read as `null` on the other (the exact
+ * "credentials: same-origin, no Bearer, no refresh" symptom). A single
+ * `globalThis` slot is shared across every copy, so registration always
+ * reaches the fetch path.
+ */
+const ADAPTER_GLOBAL_KEY = '__embedAuthedFetchAdapter__'
+
+function getRegisteredAuthAdapter(): EmbedAuthAdapter | null {
+  if (typeof globalThis === 'undefined') return null
+  return (globalThis as Record<string, unknown>)[ADAPTER_GLOBAL_KEY] as EmbedAuthAdapter | null ?? null
+}
+
+function storeRegisteredAuthAdapter(adapter: EmbedAuthAdapter | null): void {
+  if (typeof globalThis === 'undefined') return
+  ;(globalThis as Record<string, unknown>)[ADAPTER_GLOBAL_KEY] = adapter
+}
+
+/**
+ * Register a host-owned auth adapter for `embedAuthedFetch`. Pass `null`
+ * to clear (typically on provider unmount).
+ *
+ * Module-level state — there is one chat panel per app, so a single
+ * registration is sufficient. Calling this twice with different non-null
+ * adapters replaces the previous one (the most recent registration wins);
+ * a `console.warn` flags the overwrite so duplicate-provider mounts get
+ * caught in dev.
+ */
+export function setEmbedAuthAdapter(adapter: EmbedAuthAdapter | null): void {
+  if (adapter && getRegisteredAuthAdapter() && process.env.NODE_ENV !== 'production') {
+    console.warn(
+      '[setEmbedAuthAdapter] overwriting a previously-registered auth ' +
+        'adapter. Two chat-runtime providers should not coexist — verify ' +
+        'mount order and pass `null` from the unmounting provider.',
+    )
+  }
+  storeRegisteredAuthAdapter(adapter)
+}
+
 /**
  * `fetch` wrapper that attaches embed-proxy bearer headers (when
  * present in sessionStorage) and forces `credentials: 'same-origin'`
@@ -40,13 +151,26 @@ import { applyProxyAuth } from './embed-proxy-auth-storage'
  * the current window's origin; cross-origin URLs throw before the bearer
  * leaves the page. This is a defense-in-depth guard for future call sites
  * — there is no legitimate cross-origin use of this fetch wrapper.
+ *
+ * **401 self-heal:** when a registered adapter supplies `refresh`, a `401`
+ * response triggers a single token refresh + retry of the same request
+ * (see `EmbedAuthAdapter.refresh`). This is the openframe `apiClient`'s
+ * refresh-then-retry behaviour, lifted into the lib so embedded surfaces
+ * no longer need a host-side `window.fetch` monkey-patch to survive an
+ * expired access token mid-chat. With no adapter (or no `refresh`), the
+ * 401 passes straight through unchanged.
  */
 export function embedAuthedFetch(url: string, init: RequestInit = {}): Promise<Response> {
+  // Same-origin guard runs SYNCHRONOUSLY (not awaited inside the async
+  // helper below) so a bearer-leaking cross-origin URL throws before any
+  // promise is created — callers and tests rely on the synchronous throw.
   assertSameOrigin(url)
 
   // `applyProxyAuth` accepts `Record<string, string>`; normalize the
-  // caller's headers to that shape. RequestInit accepts `HeadersInit`
-  // which is broader (Headers instance OR array of tuples).
+  // caller's headers to that shape ONCE, up front. RequestInit accepts
+  // `HeadersInit` which is broader (Headers instance OR array of tuples).
+  // We re-derive the per-request headers from this base on every attempt
+  // (initial + post-refresh retry) so a rotated bearer is picked up.
   //
   // When the caller passes no headers, fall back to the same default
   // `applyProxyAuth` uses internally — `Content-Type: application/json` —
@@ -69,14 +193,114 @@ export function embedAuthedFetch(url: string, init: RequestInit = {}): Promise<R
     }
   }
 
-  const { url: authedUrl, headers } = applyProxyAuth(url, baseHeaders)
-  return fetch(authedUrl, {
+  return fetchWithRefresh(url, init, baseHeaders, false)
+}
+
+/**
+ * Single in-flight refresh shared across all concurrent `embedAuthedFetch`
+ * callers. A stampede of chat requests that all 401 at the same moment must
+ * trigger the adapter's `refresh()` ONCE, not N times — otherwise an
+ * expiring session fires a thundering herd of refresh calls at the auth
+ * server. Resets to `null` once settled so the next genuine expiry can
+ * refresh again.
+ */
+// Stored on `globalThis` rather than a module-local so the "single refresh"
+// guarantee survives module duplication. Bundlers can ship more than one copy
+// of this module (e.g. across chunks or a host + embedded build); a per-module
+// variable would let each copy run its own refresh cycle, re-creating the
+// thundering-herd this dedupe exists to prevent.
+const IN_FLIGHT_REFRESH_GLOBAL_KEY = '__embedAuthedFetchInFlightRefresh__'
+
+function getInFlightRefresh(): Promise<boolean> | null {
+  if (typeof globalThis === 'undefined') return null
+  return (
+    ((globalThis as Record<string, unknown>)[IN_FLIGHT_REFRESH_GLOBAL_KEY] as
+      | Promise<boolean>
+      | null
+      | undefined) ?? null
+  )
+}
+
+function setInFlightRefresh(refresh: Promise<boolean> | null): void {
+  if (typeof globalThis === 'undefined') return
+  ;(globalThis as Record<string, unknown>)[IN_FLIGHT_REFRESH_GLOBAL_KEY] = refresh
+}
+
+function dedupedRefresh(): Promise<boolean> {
+  const adapter = getRegisteredAuthAdapter()
+  if (!adapter?.refresh) return Promise.resolve(false)
+  let inFlightRefresh = getInFlightRefresh()
+  if (!inFlightRefresh) {
+    // Wrap in `Promise.resolve` so an adapter that throws synchronously
+    // (rather than rejecting) still funnels through the shared slot and
+    // clears it. A rejected refresh is treated as "could not refresh".
+    inFlightRefresh = Promise.resolve()
+      .then(() => adapter.refresh!())
+      .catch(() => false)
+      .finally(() => {
+        setInFlightRefresh(null)
+      })
+    setInFlightRefresh(inFlightRefresh)
+  }
+  return inFlightRefresh
+}
+
+/**
+ * Core fetch path: merge proxy-auth + adapter headers, issue the request,
+ * and — on a `401` with a refresh-capable adapter — refresh once and retry
+ * the identical request a single time. Mirrors the openframe `apiClient`'s
+ * refresh-then-retry contract (`isRetry` guards against infinite loops).
+ */
+async function fetchWithRefresh(
+  url: string,
+  init: RequestInit,
+  baseHeaders: Record<string, string>,
+  isRetry: boolean,
+): Promise<Response> {
+  // Re-run the merge each attempt: `applyProxyAuth` reads the latest stored
+  // proxy creds and `getHeaders()` reads the latest bearer, so a retry after
+  // refresh carries the rotated token rather than the stale one. `{...baseHeaders}`
+  // keeps the caller's normalized headers immutable across attempts.
+  const { url: authedUrl, headers } = applyProxyAuth(url, { ...baseHeaders })
+
+  // Host-supplied auth adapter layer. Runs AFTER the proxy-auth merge so
+  // adapter headers override both caller and proxy values — the adapter
+  // is the host's explicit "this is my auth model" override, intentionally
+  // last-writer-wins. When no adapter is registered, this is a zero-cost
+  // no-op (object spread of `{}`).
+  const adapter = getRegisteredAuthAdapter()
+  if (adapter?.getHeaders) {
+    // Filter `undefined` values — the adapter type allows them so consumers
+    // don't have to narrow `{ Authorization: token ? '…' : undefined }`-shaped
+    // returns, but `fetch` headers must be strings.
+    for (const [k, v] of Object.entries(adapter.getHeaders())) {
+      if (v !== undefined) headers[k] = v
+    }
+  }
+  const credentials = adapter?.credentials ?? init.credentials ?? 'same-origin'
+
+  const response = await fetch(authedUrl, {
     ...init,
     headers,
-    // Always include Supabase auth cookies. `applyProxyAuth` handles
-    // the bearer header layer; cookies are the session-tier carrier.
-    credentials: init.credentials ?? 'same-origin',
+    // Default `same-origin` carries Supabase cookies for the MPH proxy-
+    // auth model. Hosts on different origins (openframe-frontend ↔
+    // openframe gateway) register `credentials: 'include'` via the
+    // adapter to make their own cookies travel cross-origin (CORS +
+    // `SameSite=None` must be configured server-side for that to work).
+    credentials,
   })
+
+  // 401 self-heal: refresh the token once and retry. Only when an adapter
+  // opted into `refresh`, and only on the first attempt — a 401 on the
+  // retry means the fresh token is also unauthorized, so surface it.
+  if (response.status === 401 && !isRetry && adapter?.refresh) {
+    const refreshed = await dedupedRefresh()
+    if (refreshed) {
+      return fetchWithRefresh(url, init, baseHeaders, true)
+    }
+  }
+
+  return response
 }
 
 /**
@@ -118,6 +342,22 @@ function assertSameOrigin(url: string): void {
     )
   }
   if (target.origin !== pageOrigin) {
+    // Dev-mode escape hatch — embedded apps (e.g. openframe-frontend)
+    // run on a different origin from their gateway during local dev,
+    // and forcing a Next.js `rewrites()` workaround is more error-prone
+    // than relaxing the guard for the dev build. In production
+    // (`NODE_ENV === 'production'`) the guard stays absolute — same
+    // defense-in-depth bearer-leak protection as before. The check is
+    // baked at build time by Next/webpack/Turbopack so prod bundles
+    // contain only the throwing branch (no dev string in the artifact).
+    if (process.env.NODE_ENV !== 'production') {
+      console.warn(
+        `[embedAuthedFetch] cross-origin fetch to ${target.origin} ` +
+          `allowed in dev (NODE_ENV !== 'production'). Production builds ` +
+          `will reject this — wire a same-origin proxy before shipping.`,
+      )
+      return
+    }
     throw new Error(
       `embedAuthedFetch: refusing cross-origin fetch to ${target.origin} — pass a relative /api/* path instead`,
     )

package/src/utils/index.ts

@@ -120,7 +120,11 @@ export {
 // surfaces from importing a chat-prefixed symbol. Old chat-prefixed
 // aliases are kept as @deprecated re-exports at
 // `components/chat/utils/chat-authed-fetch.ts` + `chat-proxy-auth-storage.ts`.
-export { embedAuthedFetch } from './embed-authed-fetch'
+export {
+  embedAuthedFetch,
+  setEmbedAuthAdapter,
+  type EmbedAuthAdapter,
+} from './embed-authed-fetch'
 export {
   type EmbedProxyAuth,
   getEmbedProxyAuth,

package/src/utils/scroll-into-view.ts

@@ -1,74 +1,148 @@
 /**
- * `scrollElementIntoView` — canonical "smooth scroll element to top
- * of viewport, account for sticky chrome, optionally adjust for
- * known layout shifts" helper.
+ * `scrollElementIntoView` — canonical "scroll an element to the top of the
+ * viewport, account for sticky chrome, survive 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:
+ * One shared implementation so every caller (the ticket drawer expand, the
+ * hub's `useUnifiedNav` / `use-nav-link` hash scroll, doc-tree, delivery
+ * `?focus=`, sticky-section-nav, …) inherits the SAME cancellation-proof
+ * motion.
  *
- *   - `useUnifiedNav` same-URL re-scroll branch (hub)
- *   - `<HelpCenterCard>` click-to-expand (lib, with cross-row
- *     layout-shift adjustment)
- *   - Future ticket-row / docs anchor scrolls
+ * WHY A SELF-DRIVEN rAF TWEEN INSTEAD OF `window.scrollTo({behavior:'smooth'})`:
+ * the native smooth scroll is CANCELLABLE, and in real pages it gets cancelled
+ * constantly:
  *
- * 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, …).
+ *   - Browser SCROLL ANCHORING: when content is inserted/removed above or
+ *     around the target (a collapsible drawer expanding, an async image
+ *     loading, a list re-rendering) the browser issues a synchronous scrollTop
+ *     correction to keep the anchored element stable. Per CSSOM-View "perform a
+ *     scroll" step 1 ("abort any ongoing smooth scroll"), that correction
+ *     ABORTS an in-flight native smooth scroll — so it lands as an instant jump.
+ *     Anchoring is suppressed when the scroll offset is 0, which is exactly why
+ *     a native smooth scroll appears to work the FIRST time (page at top) and
+ *     jumps on every repeat (page already scrolled). This was a multi-day
+ *     "smooth only works once" bug on the /tickets drawer.
+ *   - A second programmatic scroll on the same frame, or a `focus()` without
+ *     `{preventScroll:true}`, cancels it the same way.
  *
- * 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.
+ * A tween that re-asserts the position with INSTANT writes every frame is
+ * immune: there is no "ongoing native smooth scroll" for anchoring/focus to
+ * abort, and any correction that lands between our frames is overwritten on the
+ * next frame. We also RECOMPUTE the target each frame, so an element whose
+ * final position is still settling (drawer still expanding, images loading)
+ * is tracked to its resting place instead of animating to a stale pixel.
+ *
+ * Honors `prefers-reduced-motion` (jumps instantly) and cancels on genuine user
+ * scroll intent (wheel / touch) so we never fight the user.
  */
 
 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. */
+  /** Pixels to subtract from the target element's `top` so it lands BELOW
+   *  sticky chrome. Defaults to 0. Pass `96` for the standard hub header. */
   headerOffset?: number
-  /** Scroll animation style. Defaults to `'smooth'`. Use `'instant'`
-   *  for imperative jumps where animation would feel laggy (deep
-   *  link land, programmatic focus moves). */
+  /** `'smooth'` (default) runs the self-driven tween; `'instant'` / `'auto'`
+   *  jump in one synchronous write (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. */
+  /** Optional adjustment applied to the computed pixel target each frame. The
+   *  callback receives the "raw" Y (`element.top + scrollY - headerOffset`) and
+   *  returns the FINAL target. Use when the caller knows about a layout shift
+   *  (e.g. a sibling drawer collapsing) the geometry can't yet reflect. */
   adjustTargetY?: (rawTargetY: number) => number
+  /** Tween duration in ms (smooth only). Default 320. */
+  durationMs?: number
+}
+
+/** Module-level handle to the in-flight tween so a new call (or a user
+ *  gesture) cancels the previous one — only ever one page-scroll animation at
+ *  a time. */
+let activeRaf = 0
+let teardownActive: (() => void) | null = null
+
+function cancelActiveScroll(): void {
+  if (activeRaf) {
+    cancelAnimationFrame(activeRaf)
+    activeRaf = 0
+  }
+  if (teardownActive) {
+    teardownActive()
+    teardownActive = null
+  }
 }
 
+const easeOutCubic = (t: number): number => 1 - Math.pow(1 - t, 3)
+
 /**
- * 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.
+ * Scroll the page so `target` lands at the top of the viewport (below sticky
+ * chrome via `headerOffset`). SSR-safe; `null`/`undefined` target is a no-op so
+ * callers can pass refs without defensive branching.
  */
 export function scrollElementIntoView(
   target: HTMLElement | null | undefined,
   options: ScrollElementIntoViewOptions = {},
 ): void {
   if (typeof window === 'undefined' || !target) return
-  const { headerOffset = 0, behavior = 'smooth', adjustTargetY } = options
-  const rawTargetY =
-    target.getBoundingClientRect().top + window.scrollY - headerOffset
-  const finalY = adjustTargetY ? adjustTargetY(rawTargetY) : rawTargetY
-  window.scrollTo({ top: Math.max(0, finalY), behavior })
+  const { headerOffset = 0, behavior = 'smooth', adjustTargetY, durationMs = 320 } = options
+
+  // Target is recomputed every frame: the row's absolute position can move as
+  // the page reflows (a sibling drawer collapsing) and the reachable max grows
+  // as the just-opened drawer expands. Clamp to the LIVE max each frame.
+  const computeTarget = (): number => {
+    const raw = target.getBoundingClientRect().top + window.scrollY - headerOffset
+    const adjusted = adjustTargetY ? adjustTargetY(raw) : raw
+    const maxScroll = Math.max(
+      0,
+      document.documentElement.scrollHeight - window.innerHeight,
+    )
+    return Math.min(Math.max(0, adjusted), maxScroll)
+  }
+
+  // Any prior animation loses — one page scroll at a time.
+  cancelActiveScroll()
+
+  const prefersReduced =
+    typeof window.matchMedia === 'function' &&
+    window.matchMedia('(prefers-reduced-motion: reduce)').matches
+
+  // Instant paths: a single synchronous write. No tween, no anchoring race.
+  if (behavior === 'instant' || behavior === 'auto' || prefersReduced) {
+    window.scrollTo(0, computeTarget())
+    return
+  }
+
+  // Smooth: self-driven tween with instant per-frame writes (anchoring-proof).
+  let startY: number | null = null
+  let startTime = 0
+
+  // Bail the moment the user takes over with a real scroll gesture — we must
+  // never fight them. (Not keydown: the ticket composer auto-focuses on open,
+  // and typing there should not abort the scroll.)
+  const onUserGesture = () => cancelActiveScroll()
+  window.addEventListener('wheel', onUserGesture, { passive: true })
+  window.addEventListener('touchmove', onUserGesture, { passive: true })
+  teardownActive = () => {
+    window.removeEventListener('wheel', onUserGesture)
+    window.removeEventListener('touchmove', onUserGesture)
+  }
+
+  const step = (now: number) => {
+    if (startY === null) {
+      startY = window.scrollY
+      startTime = now
+    }
+    const targetY = computeTarget()
+    const t = Math.min(1, (now - startTime) / durationMs)
+    const y = startY + (targetY - startY) * easeOutCubic(t)
+    window.scrollTo(0, y)
+    if (t < 1) {
+      activeRaf = requestAnimationFrame(step)
+    } else {
+      // Final exact write in case easing left a sub-pixel gap, then teardown.
+      window.scrollTo(0, computeTarget())
+      activeRaf = 0
+      if (teardownActive) {
+        teardownActive()
+        teardownActive = null
+      }
+    }
+  }
+  activeRaf = requestAnimationFrame(step)
 }