@flamingo-stack/openframe-frontend-core 0.0.551 → 0.0.552-snapshot.20260817220121

package/dist/index.js

@@ -702,6 +702,7 @@ import {
   brandMarkDataUri,
   buildAnchorProps,
   buildAutoContinuationDirective,
+  buildCaptionsUrl,
   buildChatAttachmentViewUrl,
   buildDefaultHref,
   buildDiscussAddendum,
@@ -717,6 +718,7 @@ import {
   buildSuggestionUrl,
   buildTicketOpenHref,
   canonicalContentRefType,
+  captionsEntityTypeForDocType,
   captureFirstTouchAttribution,
   cardAwareUrlTransform,
   changelogLabels,
@@ -848,6 +850,8 @@ import {
   getDocAncestorNodeIds,
   getDocSourceDefaultPath,
   getDynamicIcon,
+  getEntityCaptionUrls,
+  getEntityCaptionUrlsById,
   getExpandedRowModel,
   getFacetedRowModel,
   getFacetedUniqueValues,
@@ -954,6 +958,7 @@ import {
   readDismissCookie,
   readFetchedCardTitle,
   readLeadingDecisionFrame,
+  rebaseCaptionsUrl,
   rehypeStripUnsafe,
   releaseStatusOptions,
   releaseTypeOptions,
@@ -1012,6 +1017,7 @@ import {
   urlPathLooksLikeSvg,
   useAppLayoutDrawerContainer,
   useBoardCollapse,
+  useCaptions,
   useChat,
   useChatAttachmentImageGallery,
   useChatAttachments,
@@ -1064,7 +1070,7 @@ import {
   withFirstTouchAttribution,
   withWalkthroughOpenParam,
   writeDismissCookie
-} from "./chunk-JI4JR3KC.js";
+} from "./chunk-ZS7VC5SX.js";
 import "./chunk-7EUIW46X.js";
 import "./chunk-LXC6P2EO.js";
 import "./chunk-EL5YVPD5.js";
@@ -1200,7 +1206,7 @@ import {
   validateSchema,
   validateVariables,
   variablesToUrlParams
-} from "./chunk-4A736Z6S.js";
+} from "./chunk-VGLDA77S.js";
 import "./chunk-ZJJERZUA.js";
 import {
   AboutIcon,
@@ -1361,7 +1367,7 @@ import {
   PLAY_ICON_PATH
 } from "./chunk-JMZH4KMJ.js";
 import "./chunk-W72U7OU7.js";
-import "./chunk-Y2HKHGEW.js";
+import "./chunk-UWY722RH.js";
 import {
   Checkbox,
   DropdownMenu,
@@ -2307,6 +2313,7 @@ export {
   breakpoints,
   buildAnchorProps,
   buildAutoContinuationDirective,
+  buildCaptionsUrl,
   buildChatAttachmentViewUrl,
   buildDefaultHref,
   buildDiscussAddendum,
@@ -2324,6 +2331,7 @@ export {
   buildTicketOpenHref,
   buttonVariants,
   canonicalContentRefType,
+  captionsEntityTypeForDocType,
   captureFirstTouchAttribution,
   cardAwareUrlTransform,
   changelogLabels,
@@ -2483,6 +2491,8 @@ export {
   getDocSourceDefaultPath,
   getDynamicIcon,
   getEmbedProxyAuth,
+  getEntityCaptionUrls,
+  getEntityCaptionUrlsById,
   getExpandedRowModel,
   getFacetedRowModel,
   getFacetedUniqueValues,
@@ -2618,6 +2628,7 @@ export {
   readDismissCookie,
   readFetchedCardTitle,
   readLeadingDecisionFrame,
+  rebaseCaptionsUrl,
   rehypeStripUnsafe,
   releaseStatusOptions,
   releaseTypeOptions,
@@ -2700,6 +2711,7 @@ export {
   useAutoLimitTags,
   useBatchImages,
   useBoardCollapse,
+  useCaptions,
   useChat,
   useChatAttachmentImageGallery,
   useChatAttachments,

package/package.json

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

package/src/components/chat/entity-cards/chat-video-entity-card.tsx

@@ -2,6 +2,7 @@
 
 import React from 'react'
 import { EntityVideoSection } from '../../features/entity-video-section'
+import { captionsEntityTypeForDocType } from '../../features/captions-url'
 import type { ChatRef } from '../chat-ref.types'
 
 /**
@@ -55,6 +56,9 @@ export function ChatVideoEntityCard({
       highlightVideoUrl={highlightUrl}
       highlightVideoThumbnail={highlightPoster}
       mainVideoPoster={poster}
+      // Captions derive INSIDE the section from entity identity via the
+      // runtime's captions base — no caption data on the wire at all.
+      captionsEntity={{ type: captionsEntityTypeForDocType(chatRef.type), id: chatRef.id }}
       title={chatRef.title}
       // Intentionally omitted for chat density:
       //   videoSummary    — assistant text above already covers it.

package/src/components/chat/entity-cards/dispatch.tsx

@@ -418,10 +418,12 @@ function itemVideoMetadata(item: any): Record<string, string> | null {
     item?.highlight_video_thumbnail,
     item?.featured_image,
   )
+  const highlightVideoPoster = pick(m.highlightVideoPoster, item?.highlight_video_thumbnail)
   if (videoUrl) out.videoUrl = videoUrl
   if (youtubeUrl) out.youtubeUrl = youtubeUrl
   if (highlightVideoUrl) out.highlightVideoUrl = highlightVideoUrl
   if (videoPoster) out.videoPoster = videoPoster
+  if (highlightVideoPoster) out.highlightVideoPoster = highlightVideoPoster
   return out.videoUrl || out.youtubeUrl || out.highlightVideoUrl ? out : null
 }
 

package/src/components/features/__tests__/use-ios-native-video-fullscreen.test.tsx

@@ -0,0 +1,116 @@
+// @vitest-environment jsdom
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { renderHook } from '@testing-library/react';
+import { useIosNativeVideoFullscreen } from '../use-ios-native-video-fullscreen';
+
+/**
+ * The composed tree media-chrome dispatches through: the request starts at the
+ * fullscreen button inside `<media-controller>`, inside the player host's shadow
+ * root. The controller listener stands in for the handler that would service the
+ * request as element fullscreen when nothing claims it first.
+ */
+function mountPlayer({ supportsFullscreen = true }: { supportsFullscreen?: boolean } = {}) {
+  const host = document.createElement('div');
+  document.body.append(host);
+  const controller = document.createElement('div');
+  host.attachShadow({ mode: 'open' }).append(controller);
+  const button = document.createElement('button');
+  controller.append(button);
+
+  const webkitEnterFullscreen = vi.fn();
+  const video = Object.assign(document.createElement('video'), {
+    webkitSupportsFullscreen: supportsFullscreen,
+    webkitEnterFullscreen,
+  });
+  Object.assign(host, { media: { nativeEl: video } });
+
+  const serviced = vi.fn();
+  controller.addEventListener('mediaenterfullscreenrequest', serviced);
+
+  return {
+    playerRef: { current: host as unknown },
+    pressFullscreen: () =>
+      button.dispatchEvent(new CustomEvent('mediaenterfullscreenrequest', { bubbles: true, composed: true })),
+    serviced,
+    webkitEnterFullscreen,
+  };
+}
+
+function setShell(platform: 'ios' | 'android' | null): void {
+  if (platform === null) {
+    delete (globalThis as { Capacitor?: unknown }).Capacitor;
+    return;
+  }
+  (globalThis as { Capacitor?: unknown }).Capacitor = {
+    isNativePlatform: () => true,
+    getPlatform: () => platform,
+  };
+}
+
+afterEach(() => {
+  setShell(null);
+  document.body.innerHTML = '';
+});
+
+describe('useIosNativeVideoFullscreen', () => {
+  it('hands the request to the system player instead of the fullscreen API', () => {
+    setShell('ios');
+    const { playerRef, pressFullscreen, serviced, webkitEnterFullscreen } = mountPlayer();
+    renderHook(() => useIosNativeVideoFullscreen(playerRef));
+
+    pressFullscreen();
+
+    expect(webkitEnterFullscreen).toHaveBeenCalledTimes(1);
+    // Stopped in the capture phase, so element fullscreen is never requested.
+    expect(serviced).not.toHaveBeenCalled();
+  });
+
+  it('leaves the request to the player off the iOS shell', () => {
+    setShell(null);
+    const { playerRef, pressFullscreen, serviced, webkitEnterFullscreen } = mountPlayer();
+    renderHook(() => useIosNativeVideoFullscreen(playerRef));
+
+    pressFullscreen();
+
+    expect(webkitEnterFullscreen).not.toHaveBeenCalled();
+    expect(serviced).toHaveBeenCalledTimes(1);
+  });
+
+  it('leaves the request to the player on the Android shell', () => {
+    setShell('android');
+    const { playerRef, pressFullscreen, serviced, webkitEnterFullscreen } = mountPlayer();
+    renderHook(() => useIosNativeVideoFullscreen(playerRef));
+
+    pressFullscreen();
+
+    expect(webkitEnterFullscreen).not.toHaveBeenCalled();
+    expect(serviced).toHaveBeenCalledTimes(1);
+  });
+
+  // `webkitSupportsFullscreen` stays false until metadata loads — reachable on a
+  // Save-Data connection, where preload is 'none'.
+  it('leaves the request to the player while the video reports no fullscreen support', () => {
+    setShell('ios');
+    const { playerRef, pressFullscreen, serviced, webkitEnterFullscreen } = mountPlayer({
+      supportsFullscreen: false,
+    });
+    renderHook(() => useIosNativeVideoFullscreen(playerRef));
+
+    pressFullscreen();
+
+    expect(webkitEnterFullscreen).not.toHaveBeenCalled();
+    expect(serviced).toHaveBeenCalledTimes(1);
+  });
+
+  it('stops intercepting once unmounted', () => {
+    setShell('ios');
+    const { playerRef, pressFullscreen, serviced, webkitEnterFullscreen } = mountPlayer();
+    const { unmount } = renderHook(() => useIosNativeVideoFullscreen(playerRef));
+
+    unmount();
+    pressFullscreen();
+
+    expect(webkitEnterFullscreen).not.toHaveBeenCalled();
+    expect(serviced).toHaveBeenCalledTimes(1);
+  });
+});

package/src/components/features/captions-url.ts

@@ -30,5 +30,119 @@ export function getCaptionsUrl(
   if (!srtContent) return undefined
   const hash = `${srtContent.length}-${srtContent.slice(0, 8).replace(/\s/g, '')}`
   const variant = options?.variant ? `&variant=${options.variant}` : ''
-  return `/api/captions/${entityType}/${entityId}?v=${hash}${variant}`
+  return `${DEFAULT_CAPTIONS_PATH}/${entityType}/${entityId}?v=${hash}${variant}`
+}
+
+/** The slice of `ChatRuntime.endpoints` this module needs. */
+export interface CaptionsEndpoints {
+  /** Base URL prefix for the captions route (plain path base, no query
+   *  params) — e.g. `/content/api/captions` in a proxied embedder. Unset ⇒
+   *  the same-origin relative default `/api/captions` (the hub). Wired by
+   *  hosts exactly like every other endpoint on `ChatRuntime.endpoints`. */
+  captionsUrlPrefix?: string
+}
+
+/** Same-origin default — for hosts that serve the route themselves (the hub).
+ *  Cross-origin embedders set `endpoints.captionsUrlPrefix` instead. */
+const DEFAULT_CAPTIONS_PATH = '/api/captions'
+
+function resolveCaptionsBase(endpoints?: CaptionsEndpoints | null): string {
+  return endpoints?.captionsUrlPrefix || DEFAULT_CAPTIONS_PATH
+}
+
+/** Rebase an already-built relative `/api/captions/...` URL (e.g. one the hub
+ *  API computed server-side) onto the host's captions base. Same-origin hosts
+ *  (base = default) get the URL back untouched. Non-captions URLs pass through. */
+export function rebaseCaptionsUrl<T extends string | null | undefined>(
+  endpoints: CaptionsEndpoints | null | undefined,
+  url: T,
+): T | string {
+  if (!url || !url.startsWith(`${DEFAULT_CAPTIONS_PATH}/`)) return url
+  const base = resolveCaptionsBase(endpoints)
+  if (base === DEFAULT_CAPTIONS_PATH) return url
+  return `${base}${url.slice(DEFAULT_CAPTIONS_PATH.length)}`
+}
+
+/**
+ * The endpoints-aware entry point — `getCaptionsUrl` based on
+ * `endpoints.captionsUrlPrefix` (consumers hand over `runtime?.endpoints` and
+ * nothing else). Hub/same-origin hosts leave the prefix unset and resolve to
+ * the relative default.
+ */
+export function buildCaptionsUrl(
+  endpoints: CaptionsEndpoints | null | undefined,
+  entityType: string,
+  entityId: string | number,
+  srtContent?: string | null,
+  options?: { variant?: 'highlight' },
+): string | undefined {
+  const rel = getCaptionsUrl(entityType, entityId, srtContent, options)
+  return rel ? (rebaseCaptionsUrl(endpoints, rel) as string) : undefined
+}
+
+/** The two SRT columns every video entity carries — main video + highlight
+ *  reel. The caption URL shape is fully generic over these
+ *  (`?variant=highlight` is the only difference), so consumers never derive
+ *  the two URLs by hand. */
+export interface CaptionSrtFields {
+  id: string | number
+  srt_content?: string | null
+  highlight_srt_content?: string | null
+}
+
+export interface EntityCaptionUrls {
+  captionsUrl?: string
+  highlightCaptionsUrl?: string
+}
+
+/**
+ * THE one-stop caption derivation for a video entity: hand over the runtime
+ * `endpoints` + the entity row and get both `<track>` URLs back, base-resolved
+ * for the host (relative on the hub, proxied in embedders). Every view
+ * (release, onboarding guide, webinar, podcast, …) calls this once instead of
+ * hand-building main + highlight URLs separately.
+ */
+export function getEntityCaptionUrls(
+  endpoints: CaptionsEndpoints | null | undefined,
+  entityType: string,
+  entity: CaptionSrtFields | null | undefined,
+): EntityCaptionUrls {
+  if (!entity) return {}
+  return {
+    captionsUrl: buildCaptionsUrl(endpoints, entityType, entity.id, entity.srt_content),
+    highlightCaptionsUrl: buildCaptionsUrl(endpoints, entityType, entity.id, entity.highlight_srt_content, {
+      variant: 'highlight',
+    }),
+  }
+}
+
+/**
+ * Identity-only variant of `getEntityCaptionUrls` — for surfaces that know the
+ * entity's type + id but NOT its SRT columns (chat cards, whose hydration rows
+ * deliberately exclude the heavy SRT content). The `/api/captions` route is
+ * addressed purely by `<entityType>/<entityId>`, so the URLs derive from
+ * identity alone; a video without subtitles costs one silent 404 `<track>`
+ * fetch. No `?v=` cache-buster (no content to hash) — the route's own
+ * Cache-Control governs freshness.
+ */
+export function getEntityCaptionUrlsById(
+  endpoints: CaptionsEndpoints | null | undefined,
+  entityType: string,
+  entityId: string | number,
+): Required<EntityCaptionUrls> {
+  const base = resolveCaptionsBase(endpoints)
+  return {
+    captionsUrl: `${base}/${entityType}/${entityId}`,
+    highlightCaptionsUrl: `${base}/${entityType}/${entityId}?variant=highlight`,
+  }
+}
+
+/**
+ * Chat docType → captions-route entity type. Chat documentTypes equal the
+ * captions entity types for every video-bearing type except podcast
+ * (`podcast` vs `podcast_episode`). Kept here (not per-card) so the alias
+ * exists exactly once.
+ */
+export function captionsEntityTypeForDocType(docType: string): string {
+  return docType === 'podcast' ? 'podcast_episode' : docType
 }

package/src/components/features/entity-video-section.tsx

@@ -9,6 +9,7 @@ import {
 } from '../ui/tabs';
 import type { VideoTeaser } from '../../types/video-processing';
 import { Video } from './video';
+import { useCaptions } from './use-captions';
 import { VideoBitesStrip, type VideoBiteStripItem } from './video-bites-strip';
 import { DEFAULT_VIDEO_BITES_TITLE, type VideoBiteStripProfile } from './video-bites-shared';
 import { SECTION_HEADING_CLASS } from '../layout/page-heading';
@@ -77,6 +78,14 @@ export interface EntityVideoSectionProps {
    * player (`getCaptionsUrl(type, id, highlightSrt, { variant: 'highlight' })`).
    */
   highlightCaptionsUrl?: string | null;
+  /**
+   * Entity identity for caption derivation — the alternative to the explicit
+   * URL props above for hosts that don't hold the entity's SRT columns (chat
+   * cards). The section derives both `<track>` URLs itself from the runtime's
+   * captions base (`getEntityCaptionUrlsById`); explicit `captionsUrl` /
+   * `highlightCaptionsUrl` win when also provided.
+   */
+  captionsEntity?: { type: string; id: string | number } | null;
   /** LCP hint — when true, the full-video tab's poster eager-loads. */
   priority?: boolean;
 }
@@ -99,14 +108,25 @@ export function EntityVideoSection({
   bitesAutoScroll = true,
   MarkdownRenderer,
   srtContent,
-  captionsUrl,
-  highlightCaptionsUrl,
+  captionsUrl: captionsUrlProp,
+  highlightCaptionsUrl: highlightCaptionsUrlProp,
+  captionsEntity,
   priority = false,
 }: EntityVideoSectionProps) {
+  const captions = useCaptions();
   const hasFullVideo = !!(youtubeUrl || mainVideoUrl);
   const hasHighlight = !!highlightVideoUrl;
   const hasVideo = hasFullVideo || hasHighlight;
 
+  // Caption resolution: explicit URL props win (detail pages gate on their
+  // entity's SRT columns); otherwise derive from `captionsEntity` identity —
+  // the zero-knowledge path for chat cards.
+  const derivedCaptions = captionsEntity
+    ? captions.forEntityId(captionsEntity.type, captionsEntity.id)
+    : null;
+  const captionsUrl = captionsUrlProp ?? derivedCaptions?.captionsUrl;
+  const highlightCaptionsUrl = highlightCaptionsUrlProp ?? derivedCaptions?.highlightCaptionsUrl;
+
   if (!hasVideo && !videoSummary && (!videoBites || videoBites.length === 0)) {
     return null;
   }

package/src/components/features/index.ts

@@ -72,6 +72,7 @@ export * from './floating-walkthrough-video'
 export * from './use-walkthrough-video'
 export * from './use-video-warmup'
 export * from './captions-url'
+export * from './use-captions'
 export * from './video-source-selector'
 export * from './transcript-summary-editor'
 export * from './subtitles-editor'

package/src/components/features/use-captions.ts

@@ -0,0 +1,46 @@
+'use client'
+
+/**
+ * useCaptions — THE captions configurer.
+ *
+ * The ONE place in the lib that reads the chat-runtime endpoints
+ * (`endpoints.captionsUrlPrefix`) for caption purposes. Every caption
+ * consumer (`EntityVideoSection`, `ReleaseDetailPage`,
+ * `OnboardingGuideDetailView`, `useWalkthroughVideo`, …) calls this hook and
+ * uses the returned pre-bound helpers — no component reads runtime endpoint
+ * values for captions itself.
+ *
+ * The pure derivation logic lives in `captions-url.ts` (endpoint-agnostic,
+ * server-import-safe); this hook only binds it to the ambient runtime.
+ */
+
+import { useMemo } from 'react'
+import { useChatRuntime } from '../../contexts/chat-runtime-context'
+import {
+  getEntityCaptionUrls,
+  getEntityCaptionUrlsById,
+  rebaseCaptionsUrl,
+  type CaptionSrtFields,
+  type EntityCaptionUrls,
+} from './captions-url'
+
+export interface CaptionsApi {
+  /** Both track URLs from an entity row's SRT columns (presence-gated). */
+  forEntity: (entityType: string, entity: CaptionSrtFields | null | undefined) => EntityCaptionUrls
+  /** Both track URLs from entity identity alone (no SRT knowledge — chat cards). */
+  forEntityId: (entityType: string, entityId: string | number) => Required<EntityCaptionUrls>
+  /** Rebase an already-built relative `/api/captions/...` URL onto the host base. */
+  rebase: <T extends string | null | undefined>(url: T) => T | string
+}
+
+export function useCaptions(): CaptionsApi {
+  const endpoints = useChatRuntime()?.endpoints ?? null
+  return useMemo(
+    () => ({
+      forEntity: (entityType, entity) => getEntityCaptionUrls(endpoints, entityType, entity),
+      forEntityId: (entityType, entityId) => getEntityCaptionUrlsById(endpoints, entityType, entityId),
+      rebase: (url) => rebaseCaptionsUrl(endpoints, url),
+    }),
+    [endpoints],
+  )
+}

package/src/components/features/use-ios-native-video-fullscreen.ts

@@ -0,0 +1,89 @@
+'use client';
+
+/**
+ * iOS app shell only: hand the player's fullscreen control to Apple's own video
+ * player instead of the Fullscreen API.
+ *
+ * This is what media-chrome already does on iPhone Safari — `requestFullscreen`
+ * does not exist on `Element.prototype` there, so its `enterFullscreen` falls
+ * through to `media.webkitEnterFullscreen()` and the video is handed to the
+ * system player. The Capacitor shell turns element fullscreen ON (WKWebView's
+ * `isElementFullscreenEnabled`), so media-chrome takes the `requestFullscreen()`
+ * branch instead — and WebKit then hands the web view back with its scroll
+ * view's `contentInsetAdjustmentBehavior` reset from Capacitor's `.never` to
+ * `.automatic` and its own `safeAreaInsets` stranded at the fullscreen
+ * container's values. The app comes back from a video with a doubled top band
+ * and dead space above the home indicator until a rotation, and the shell can
+ * only paper over it afterwards (`MainViewController` KVOs `fullscreenState` to
+ * restore the behavior). Never entering element fullscreen is the actual fix.
+ *
+ * The takeover is an event interception, not a monkey-patch: the fullscreen
+ * button dispatches `mediaenterfullscreenrequest` (`composed`, `bubbles`) from
+ * inside the player's shadow trees, so a CAPTURE listener on the `<mux-player>`
+ * host sees it before the `<media-controller>` that would service it, and
+ * `stopImmediatePropagation()` is enough to claim the request. Which element
+ * media-chrome would have passed to `requestFullscreen` never enters into it.
+ *
+ * The player's own fullscreen STATE stays correct for free: the system player
+ * fires `webkitbeginfullscreen` / `webkitendfullscreen` on the `<video>`,
+ * `mux-video` re-dispatches both, and media-chrome's state mediator already
+ * listens for them.
+ *
+ * Anything the takeover cannot service falls through to media-chrome untouched:
+ * no `<video>` yet, or `webkitSupportsFullscreen` still false — it stays false
+ * until metadata has loaded, which is reachable on a Save-Data connection where
+ * preload is `'none'`.
+ */
+
+import { useEffect } from 'react';
+
+/** media-chrome's `MediaUIEvents.MEDIA_ENTER_FULLSCREEN_REQUEST`. Spelled out
+ *  rather than imported: media-chrome is a transitive dep of the Mux player, not
+ *  a declared one. */
+const ENTER_FULLSCREEN_REQUEST = 'mediaenterfullscreenrequest';
+
+/** The two `HTMLVideoElement` members WebKit adds for its own video-fullscreen
+ *  presentation — absent from the DOM lib, and absent at runtime off Apple. */
+interface NativeFullscreenVideo extends HTMLVideoElement {
+  webkitSupportsFullscreen?: boolean;
+  webkitEnterFullscreen?: () => void;
+}
+
+interface CapacitorGlobal {
+  isNativePlatform?: () => boolean;
+  getPlatform?: () => string;
+}
+
+/** Gated on the shell, not on the platform: element fullscreen behaves fine in
+ *  Safari (iPad) and on the desktop shell, where taking it away would only cost
+ *  the player its chrome in fullscreen. */
+function isIosAppShell(): boolean {
+  const capacitor = (globalThis as { Capacitor?: CapacitorGlobal }).Capacitor;
+  return capacitor?.isNativePlatform?.() === true && capacitor.getPlatform?.() === 'ios';
+}
+
+/** The real `<video>` behind `<mux-player>`: `player.media` is the `<mux-video>`
+ *  custom element and `nativeEl` is the element WebKit presents. */
+function nativeVideoElement(player: EventTarget): NativeFullscreenVideo | null {
+  const media = (player as { media?: { nativeEl?: unknown } | null }).media;
+  const element = media?.nativeEl ?? media;
+  return element instanceof HTMLVideoElement ? element : null;
+}
+
+export function useIosNativeVideoFullscreen(playerRef: { current: unknown }): void {
+  useEffect(() => {
+    if (!isIosAppShell()) return;
+    const player = playerRef.current;
+    if (!(player instanceof EventTarget)) return;
+
+    const takeOver = (event: Event) => {
+      const video = nativeVideoElement(player);
+      if (!video?.webkitSupportsFullscreen || typeof video.webkitEnterFullscreen !== 'function') return;
+      event.stopImmediatePropagation();
+      video.webkitEnterFullscreen();
+    };
+
+    player.addEventListener(ENTER_FULLSCREEN_REQUEST, takeOver, true);
+    return () => player.removeEventListener(ENTER_FULLSCREEN_REQUEST, takeOver, true);
+  }, [playerRef]);
+}

package/src/components/features/use-walkthrough-video.ts

@@ -6,8 +6,11 @@
  * SSOT for fetching + shaping the widget's data on the CLIENT (any embedder
  * reuses it). The public endpoint returns the RAW body `{ walkthroughVideo }`
  * (no {success,data} wrapper). The video's `captionsUrl` is a RELATIVE
- * `/api/captions/...` path; pass `transformCaptionsUrl` to route it through a
- * proxy (embedders) — omit it for same-origin hosts.
+ * `/api/captions/...` path; it is rebased automatically onto
+ * `ChatRuntime.endpoints.captionsUrlPrefix` (the standard runtime-endpoint
+ * wiring) — same-origin hosts leave that unset and get the URL unchanged.
+ * `transformCaptionsUrl` remains as an explicit override for hosts outside
+ * a runtime provider.
  *
  * SSR hosts (the hub) resolve the video server-side and pass it to the widget
  * directly; they don't need this hook. It exists for client-only embedders.
@@ -15,6 +18,7 @@
 
 import { useQuery } from '@tanstack/react-query';
 import type { WalkthroughVideoData } from './floating-walkthrough-video';
+import { useCaptions } from './use-captions';
 
 export interface UseWalkthroughVideoOptions {
   /** Absolute or proxied URL of the public GET route. */
@@ -22,7 +26,10 @@ export interface UseWalkthroughVideoOptions {
   /** SSR/initial seed to avoid a loading flash. */
   initialData?: WalkthroughVideoData | null;
   enabled?: boolean;
-  /** Rewrite the RELATIVE captionsUrl (e.g. prefix a `/content` proxy base). */
+  /** Rewrite the RELATIVE captionsUrl (e.g. prefix a `/content` proxy base).
+   *  OPTIONAL override — when unset, the URL is rebased onto
+   *  `ChatRuntime.endpoints.captionsUrlPrefix` (see `rebaseCaptionsUrl`), so
+   *  embedders inside a runtime provider need no wiring here at all. */
   transformCaptionsUrl?: (relativeUrl: string) => string;
 }
 
@@ -33,6 +40,7 @@ export interface UseWalkthroughVideoResult {
 
 export function useWalkthroughVideo(opts: UseWalkthroughVideoOptions): UseWalkthroughVideoResult {
   const { endpoint, initialData, enabled = true, transformCaptionsUrl } = opts;
+  const captions = useCaptions();
 
   const query = useQuery<WalkthroughVideoData | null>({
     queryKey: ['walkthrough-video', endpoint],
@@ -59,10 +67,14 @@ export function useWalkthroughVideo(opts: UseWalkthroughVideoOptions): UseWalkth
     // rewrite here (not in queryFn) means a second consumer of the same
     // endpoint can't inherit this observer's proxied captionsUrl from the cache.
     select: (video) => {
-      if (video?.captionsUrl && transformCaptionsUrl && video.captionsUrl.startsWith('/')) {
+      if (!video?.captionsUrl) return video;
+      if (transformCaptionsUrl && video.captionsUrl.startsWith('/')) {
         return { ...video, captionsUrl: transformCaptionsUrl(video.captionsUrl) };
       }
-      return video;
+      // Default: rebase onto the configured captions base. Same-origin hosts
+      // leave it unset and get the URL back unchanged — a no-op for them.
+      const rebased = captions.rebase(video.captionsUrl);
+      return rebased === video.captionsUrl ? video : { ...video, captionsUrl: rebased as string };
     },
   });
 

package/src/components/features/video.tsx

@@ -34,6 +34,7 @@ import React, { useCallback, useEffect, useImperativeHandle, useMemo, useRef, us
 import MuxPlayer from '@mux/mux-player-react';
 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';
 
 // =============================================================================
@@ -938,6 +939,10 @@ function FilePlayer({
     return () => { try { el.removeEventListener?.('ended', handler); } catch { /* ignore */ } };
   }, []);
 
+  // In the iOS shell the fullscreen control goes to Apple's video player rather
+  // than to element fullscreen, which WebKit exits by breaking the safe areas.
+  useIosNativeVideoFullscreen(hoverPlayerRef);
+
   // Imperative handle — snapshot getters + control mutators for handoff.
   useImperativeHandle(playerHandleRef, (): VideoPlayerHandle => ({
     getCurrentTime: () => hoverPlayerRef.current?.currentTime ?? 0,