@flamingo-stack/openframe-frontend-core 0.0.557 → 0.0.558-1830.4885.1

package/package.json

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

package/src/components/features/video.tsx

@@ -36,6 +36,7 @@ import { VideoPlayBadge, VideoUnmuteGlyph } from './video-center-badge';
 import { fetchPriorityProp } from '../../utils/fetch-priority';
 import { useIosNativeVideoFullscreen } from './use-ios-native-video-fullscreen';
 import { saveDataEnabled } from './use-video-warmup';
+import { useAuthedAssetSrc } from '../../hooks/use-authed-asset-src';
 
 // =============================================================================
 // Dev-only hover→playing latency instrumentation gate. Always on in dev
@@ -647,6 +648,16 @@ function FilePlayer({
   // an early manifest fetch is at most one bounded manifest+segment — the
   // Save-Data verification gate covers it (see plan A2.4).
   const effectivePreload = preload ?? (saveDataEnabled() ? 'none' : 'metadata');
+  // THE captions seam. `<track src>` is a browser subresource: it carries no
+  // custom headers, so it authenticates by cookie only. Fine on the cookie-auth
+  // web, a guaranteed 401 on every HEADER-auth host — native shells and
+  // dev-ticket web — whose caption route sits behind the same proxied
+  // `/content/api/captions` path as every other embedded endpoint. Resolving it
+  // through `useAuthedAssetSrc` puts the track on the SAME single auth knob as
+  // every embedded `fetch` (adapter bearer + 401-refresh-retry), so a host
+  // configures `endpoints.captionsUrlPrefix` and nothing else — no per-surface,
+  // per-host caption plumbing. Cookie-auth hosts get the URL back untouched.
+  const resolvedCaptionsUrl = useAuthedAssetSrc(captionsUrl, 'text/vtt, */*');
   // True while hover playback is running MUTED because the browser's autoplay
   // policy blocked sound (no user activation yet). Drives the center unmute
   // control — the industry pattern (muted autoplay + explicit unmute button)
@@ -1030,10 +1041,10 @@ function FilePlayer({
         ...(fit === 'cover' ? ({ '--media-object-fit': 'cover' } as React.CSSProperties) : {}),
       }}
     >
-      {captionsUrl ? (
+      {resolvedCaptionsUrl ? (
         <track
           kind="captions"
-          src={captionsUrl}
+          src={resolvedCaptionsUrl}
           srcLang="en"
           label="English"
           default

package/src/hooks/index.ts

@@ -8,6 +8,7 @@ export * from './use-copy-to-clipboard'
 // Image authentication hooks
 export * from './use-batch-images'
 export * from './use-authenticated-image'
+export * from './use-authed-asset-src'
 export * from './use-authed-image-src'
 
 // URL State Management hooks

package/src/hooks/use-authed-asset-src.ts

@@ -0,0 +1,98 @@
+'use client'
+
+import { useEffect, useReducer } from 'react'
+import { embedAuthedFetch, needsBearerAssetFetch } from '../utils/embed-authed-fetch'
+
+/**
+ * Resolve ANY asset URL the browser would load natively — `<img src>`,
+ * `<track src>`, a font, a poster — for hosts whose auth rides in request
+ * HEADERS instead of cookies: native shells (`capacitor://`, `tauri://`) and
+ * dev-ticket web, both in bearer mode. A native subresource load can't carry
+ * an `Authorization` header, so a gateway URL that works on the cookie-auth
+ * web 401s there.
+ *
+ * When `needsBearerAssetFetch` says the URL is bearer-authed, this hook
+ * fetches it through `embedAuthedFetch` (bearer + deduped 401-refresh-retry +
+ * the adapter's cross-origin guard — the SAME single auth knob every embedded
+ * `fetch` in the lib rides) and returns a blob object-URL. Every other URL is
+ * returned unchanged, so on the cookie-auth web the hook is a pass-through.
+ *
+ * Returns `undefined` while the fetch is in flight OR after it fails, so
+ * callers show their existing placeholder / "no captions" branch instead of a
+ * broken asset; a failed fetch retries on the next mount.
+ *
+ * Cache: module-level, session-lifetime, keyed by full URL — so the two
+ * `<track>` URLs of one player, or the same avatar in twenty rows, cost one
+ * request. Gateway URLs carry a `?v=<content-hash>` cache-buster, so changed
+ * content is a new key; entries are never revoked (a VTT / avatar is a few KB
+ * — refcount churn isn't worth it) and are dropped wholesale at session end
+ * via `clearAuthedAssetCache`.
+ */
+
+const resolvedCache = new Map<string, string>()
+const inFlight = new Map<string, Promise<void>>()
+let cacheGeneration = 0
+
+/**
+ * Drop every cached blob and revoke its object URL. Hosts call this at
+ * session end (logout / forced re-login) so a follow-on login as a
+ * different identity cannot be served blobs fetched under the previous
+ * one's bearer. Fetches still in flight when the clear happens are fenced
+ * by a generation counter — their results are revoked instead of cached.
+ */
+export function clearAuthedAssetCache(): void {
+  cacheGeneration++
+  for (const url of resolvedCache.values()) URL.revokeObjectURL(url)
+  resolvedCache.clear()
+  inFlight.clear()
+}
+
+function fetchAsBlobUrl(src: string, accept: string): Promise<void> {
+  let pending = inFlight.get(src)
+  if (!pending) {
+    const startedGeneration = cacheGeneration
+    pending = embedAuthedFetch(src, { headers: { Accept: accept } })
+      .then(async response => {
+        if (!response.ok) throw new Error(`asset fetch failed: ${response.status}`)
+        const blobUrl = URL.createObjectURL(await response.blob())
+        if (startedGeneration === cacheGeneration) {
+          resolvedCache.set(src, blobUrl)
+        } else {
+          URL.revokeObjectURL(blobUrl)
+        }
+      })
+      .finally(() => {
+        if (inFlight.get(src) === pending) inFlight.delete(src)
+      })
+    inFlight.set(src, pending)
+  }
+  return pending
+}
+
+/**
+ * @param src    the asset URL (relative or absolute), or null/undefined
+ * @param accept `Accept` header for the authed fetch — narrow it to what the
+ *               consumer renders (`image/*`, `text/vtt`); it also replaces
+ *               `embedAuthedFetch`'s default JSON `Content-Type` on the GET.
+ */
+export function useAuthedAssetSrc(src?: string | null, accept = '*/*'): string | undefined {
+  const bearerSrc = src && needsBearerAssetFetch(src) ? src : null
+  const [, rerender] = useReducer((c: number) => c + 1, 0)
+
+  useEffect(() => {
+    if (!bearerSrc || resolvedCache.has(bearerSrc)) return
+    let cancelled = false
+    fetchAsBlobUrl(bearerSrc, accept)
+      .catch(() => {})
+      .finally(() => {
+        if (!cancelled) rerender()
+      })
+    return () => {
+      cancelled = true
+    }
+  }, [bearerSrc, accept])
+
+  if (!src) return undefined
+  if (!bearerSrc) return src
+  return resolvedCache.get(bearerSrc)
+}

package/src/hooks/use-authed-image-src.ts

@@ -1,93 +1,24 @@
 'use client'
 
-import { useEffect, useReducer } from 'react'
-import { embedAuthedFetch, needsBearerAssetFetch } from '../utils/embed-authed-fetch'
+import { clearAuthedAssetCache, useAuthedAssetSrc } from './use-authed-asset-src'
 
 /**
- * Resolve an image URL for hosts whose auth rides in request headers
- * instead of cookies (native shells — `capacitor://localhost`,
- * `tauri://localhost` — running in bearer mode). A native `<img>` load
- * can't carry an `Authorization` header, so a gateway image URL that
- * works on the cookie-auth web 401s in a shell. When
- * `needsBearerAssetFetch` says the URL's origin is bearer-authed, this
- * hook fetches it through `embedAuthedFetch` (bearer + deduped
- * 401-refresh-retry + the adapter's cross-origin guard) and returns a
- * blob object-URL; every other URL is returned unchanged, so on the
- * cookie-auth web the hook is a pass-through.
+ * Image flavor of `useAuthedAssetSrc` — see that hook for the full contract.
+ * Kept as its own export because it is the lib's most-used consumer (avatars,
+ * entity images, markdown `<img>`) and because hosts already import this name.
  *
- * Returns `undefined` while the fetch is in flight OR after it fails, so
- * callers show their existing initials/placeholder fallback instead of a
- * broken image; a failed fetch retries on the next mount.
- *
- * Cache: module-level, session-lifetime, keyed by full URL. Gateway image
- * URLs carry a `?v=<content-hash>` cache-buster, so a changed image is a
- * new key; entries are never revoked (avatars are a few KB — refcount
- * churn isn't worth it).
- *
- * Distinct from the legacy `useAuthenticatedImage`, which ALWAYS
- * blob-fetches with `credentials: 'include'` and its own global config.
- * This hook is pass-through-first and keys off the single auth knob the
- * lib already has: the registered `EmbedAuthAdapter`.
+ * Distinct from the legacy `useAuthenticatedImage`, which ALWAYS blob-fetches
+ * with `credentials: 'include'` and its own global config. This hook is
+ * pass-through-first and keys off the single auth knob the lib already has:
+ * the registered `EmbedAuthAdapter`.
  */
-
-const resolvedCache = new Map<string, string>()
-const inFlight = new Map<string, Promise<void>>()
-let cacheGeneration = 0
+export function useAuthedImageSrc(src?: string | null): string | undefined {
+  return useAuthedAssetSrc(src, 'image/*')
+}
 
 /**
- * Drop every cached blob and revoke its object URL. Hosts call this at
- * session end (logout / forced re-login) so a follow-on login as a
- * different identity cannot be served blobs fetched under the previous
- * one's bearer. Fetches still in flight when the clear happens are fenced
- * by a generation counter — their results are revoked instead of cached.
+ * Session-end cache drop. Now an alias of `clearAuthedAssetCache` — one cache
+ * backs every authed asset (images AND caption tracks), so hosts keep calling
+ * this single function on logout / forced re-login.
  */
-export function clearAuthedImageCache(): void {
-  cacheGeneration++
-  for (const url of resolvedCache.values()) URL.revokeObjectURL(url)
-  resolvedCache.clear()
-  inFlight.clear()
-}
-
-function fetchAsBlobUrl(src: string): Promise<void> {
-  let pending = inFlight.get(src)
-  if (!pending) {
-    const startedGeneration = cacheGeneration
-    pending = embedAuthedFetch(src, { headers: { Accept: 'image/*' } })
-      .then(async response => {
-        if (!response.ok) throw new Error(`image fetch failed: ${response.status}`)
-        const blobUrl = URL.createObjectURL(await response.blob())
-        if (startedGeneration === cacheGeneration) {
-          resolvedCache.set(src, blobUrl)
-        } else {
-          URL.revokeObjectURL(blobUrl)
-        }
-      })
-      .finally(() => {
-        if (inFlight.get(src) === pending) inFlight.delete(src)
-      })
-    inFlight.set(src, pending)
-  }
-  return pending
-}
-
-export function useAuthedImageSrc(src?: string | null): string | undefined {
-  const bearerSrc = src && needsBearerAssetFetch(src) ? src : null
-  const [, rerender] = useReducer((c: number) => c + 1, 0)
-
-  useEffect(() => {
-    if (!bearerSrc || resolvedCache.has(bearerSrc)) return
-    let cancelled = false
-    fetchAsBlobUrl(bearerSrc)
-      .catch(() => {})
-      .finally(() => {
-        if (!cancelled) rerender()
-      })
-    return () => {
-      cancelled = true
-    }
-  }, [bearerSrc])
-
-  if (!src) return undefined
-  if (!bearerSrc) return src
-  return resolvedCache.get(bearerSrc)
-}
+export const clearAuthedImageCache = clearAuthedAssetCache

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

@@ -1,5 +1,5 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
-import { embedAuthedFetch, setEmbedAuthAdapter } from '../embed-authed-fetch'
+import { embedAuthedFetch, needsBearerAssetFetch, setEmbedAuthAdapter } from '../embed-authed-fetch'
 
 /**
  * Tests focus on the same-origin guard rather than the proxy-auth
@@ -205,3 +205,52 @@ describe('embedAuthedFetch adapter.allowedOrigins (native-shell cross-origin san
     expect(() => embedAuthedFetch('javascript:alert(1)')).toThrow(/non-http\(s\)/i)
   })
 })
+
+/**
+ * `needsBearerAssetFetch` decides whether a `<img>` / `<track>` URL has to be
+ * blob-fetched (see `useAuthedAssetSrc`). The signal is the adapter's
+ * `Authorization` header — i.e. the host authenticates by HEADER, so nothing
+ * the browser fetches on its own carries auth, same-origin included.
+ */
+describe('needsBearerAssetFetch (native subresources that cannot carry a header)', () => {
+  const bearer = { getHeaders: () => ({ Authorization: 'Bearer t' }) }
+
+  afterEach(() => {
+    setEmbedAuthAdapter(null)
+  })
+
+  it('is false with no adapter registered (the hub — cookies or nothing)', () => {
+    expect(needsBearerAssetFetch('/content/api/captions/release/1')).toBe(false)
+  })
+
+  it('is false in cookie mode (adapter supplies no Authorization)', () => {
+    setEmbedAuthAdapter({ getHeaders: () => ({}) })
+    expect(needsBearerAssetFetch('/content/api/captions/release/1')).toBe(false)
+  })
+
+  it('is TRUE for a relative proxy path in header-auth mode (dev-ticket web)', () => {
+    setEmbedAuthAdapter(bearer)
+    expect(needsBearerAssetFetch('/content/api/captions/release/1')).toBe(true)
+  })
+
+  it('is TRUE for an absolute same-origin URL in header-auth mode', () => {
+    setEmbedAuthAdapter(bearer)
+    expect(needsBearerAssetFetch('http://localhost:3000/content/api/image-proxy?u=x')).toBe(true)
+  })
+
+  it('is TRUE for a cross-origin gateway the adapter sanctions (native shell)', () => {
+    setEmbedAuthAdapter({ ...bearer, allowedOrigins: ['https://gateway.example'] })
+    expect(needsBearerAssetFetch('https://gateway.example/content/api/captions/release/1')).toBe(true)
+  })
+
+  it('is false for a third-party origin the bearer does not belong to', () => {
+    setEmbedAuthAdapter({ ...bearer, allowedOrigins: ['https://gateway.example'] })
+    expect(needsBearerAssetFetch('https://cdn.example.com/pic.png')).toBe(false)
+  })
+
+  it('is false for non-http(s) schemes (data:/blob: assets load natively)', () => {
+    setEmbedAuthAdapter(bearer)
+    expect(needsBearerAssetFetch('data:image/png;base64,AAAA')).toBe(false)
+    expect(needsBearerAssetFetch('blob:http://localhost:3000/abc')).toBe(false)
+  })
+})

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

@@ -158,32 +158,49 @@ export function hasEmbedAuthAdapter(): boolean {
 
 /**
  * Whether `url` is an asset the browser CANNOT load natively because its
- * auth rides in request headers: the registered adapter is currently
- * supplying an `Authorization` header AND the URL's origin is one the
- * adapter explicitly sanctions for that bearer (`allowedOrigins` — the
- * host's gateway, cross-origin by construction in native shells).
+ * auth rides in request headers.
  *
- * Native asset loads (`<img src>`, CSS `background-image`) can't carry
- * custom headers, so a URL this returns `true` for must go through
- * `embedAuthedFetch` → blob object-URL instead (see `useAuthedImageSrc`).
- * Everything else — cookie-auth web (no Authorization), relative /
- * same-origin URLs (cookies work), third-party origins the bearer does
- * NOT belong to (public images) — loads natively, unchanged.
+ * Native asset loads (`<img src>`, `<track src>`, CSS `background-image`)
+ * can't carry custom headers, so a URL this returns `true` for must go
+ * through `embedAuthedFetch` → blob object-URL instead (see
+ * `useAuthedAssetSrc` / `useAuthedImageSrc`).
+ *
+ * The single signal is the registered adapter: when it supplies an
+ * `Authorization` header, the host authenticates by HEADER, so nothing the
+ * browser fetches on its own is authenticated. That holds for BOTH shapes a
+ * header-auth host takes:
+ *
+ *   - a cross-origin gateway URL — sanctioned via `allowedOrigins` (native
+ *     shells, whose page origin is `capacitor://` / `tauri://`);
+ *   - a same-origin / relative reverse-proxy path (`/content/api/...`) —
+ *     dev-ticket web, where the token lives in localStorage and there is NO
+ *     session cookie to fall back on. This case used to be excluded on the
+ *     assumption that same-origin implies "cookies work"; true for a cookie
+ *     session, false for every header-auth host, which is exactly when this
+ *     predicate is consulted at all.
+ *
+ * Everything else loads natively, unchanged: cookie-auth web (the adapter
+ * supplies no `Authorization`), no adapter at all (the hub), and third-party
+ * origins the bearer does NOT belong to (public images) — those stay out of
+ * reach of the token by the same origin rules `embedAuthedFetch` enforces.
  */
 export function needsBearerAssetFetch(url: string): boolean {
   if (typeof window === 'undefined') return false
   const adapter = getRegisteredAuthAdapter()
-  if (!adapter?.allowedOrigins?.length || adapter.getHeaders?.().Authorization === undefined) {
-    return false
-  }
+  if (!adapter || adapter.getHeaders?.().Authorization === undefined) return false
   let target: URL
+  let pageOrigin: string
   try {
     target = new URL(url, window.location.href)
+    // Same reason `assertSameOrigin` derives it this way: test environments
+    // mock `window.location` as a plain object with no `origin` field.
+    pageOrigin = new URL(window.location.href).origin
   } catch {
     return false
   }
   if (target.protocol !== 'http:' && target.protocol !== 'https:') return false
-  return adapter.allowedOrigins.includes(target.origin)
+  if (target.origin === pageOrigin) return true
+  return adapter.allowedOrigins?.includes(target.origin) ?? false
 }
 
 /**