@ttt-productions/media-viewer 0.10.6 → 0.10.7

package/dist/react/use-media-playback.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"use-media-playback.d.ts","sourceRoot":"","sources":["../../src/react/use-media-playback.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,KAAK,EAAE,qBAAqB,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAE7E;;;GAGG;AACH,eAAO,MAAM,2BAA2B,OAAO,CAAC;AAEhD,MAAM,MAAM,sBAAsB,GAAG;IACnC,4DAA4D;IAC5D,QAAQ,EAAE,OAAO,CAAC;IAClB,sEAAsE;IACtE,QAAQ,EAAE;QACR,gBAAgB,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,cAAc,CAAC,gBAAgB,CAAC,KAAK,IAAI,CAAC;QACtE,YAAY,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,cAAc,CAAC,gBAAgB,CAAC,KAAK,IAAI,CAAC;QAClE,MAAM,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,cAAc,CAAC,gBAAgB,CAAC,KAAK,IAAI,CAAC;QAC5D,OAAO,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,cAAc,CAAC,gBAAgB,CAAC,KAAK,IAAI,CAAC;QAC7D,QAAQ,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,cAAc,CAAC,gBAAgB,CAAC,KAAK,IAAI,CAAC;QAC9D,OAAO,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,cAAc,CAAC,gBAAgB,CAAC,KAAK,IAAI,CAAC;KAC9D,CAAC;CACH,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,KAAK,CAAC,SAAS,CAAC,gBAAgB,GAAG,IAAI,CAAC,EACpD,KAAK,EAAE,kBAAkB,EACzB,mBAAmB,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,qBAAqB,CAAC;AACtD;;;;;;GAMG;AACH,QAAQ,CAAC,EAAE,MAAM,GAChB,sBAAsB,CA4LxB"}
+{"version":3,"file":"use-media-playback.d.ts","sourceRoot":"","sources":["../../src/react/use-media-playback.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,KAAK,EAAE,qBAAqB,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAE7E;;;GAGG;AACH,eAAO,MAAM,2BAA2B,OAAO,CAAC;AAEhD,MAAM,MAAM,sBAAsB,GAAG;IACnC,4DAA4D;IAC5D,QAAQ,EAAE,OAAO,CAAC;IAClB,sEAAsE;IACtE,QAAQ,EAAE;QACR,gBAAgB,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,cAAc,CAAC,gBAAgB,CAAC,KAAK,IAAI,CAAC;QACtE,YAAY,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,cAAc,CAAC,gBAAgB,CAAC,KAAK,IAAI,CAAC;QAClE,MAAM,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,cAAc,CAAC,gBAAgB,CAAC,KAAK,IAAI,CAAC;QAC5D,OAAO,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,cAAc,CAAC,gBAAgB,CAAC,KAAK,IAAI,CAAC;QAC7D,QAAQ,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,cAAc,CAAC,gBAAgB,CAAC,KAAK,IAAI,CAAC;QAC9D,OAAO,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,cAAc,CAAC,gBAAgB,CAAC,KAAK,IAAI,CAAC;KAC9D,CAAC;CACH,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,KAAK,CAAC,SAAS,CAAC,gBAAgB,GAAG,IAAI,CAAC,EACpD,KAAK,EAAE,kBAAkB,EACzB,mBAAmB,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,qBAAqB,CAAC;AACtD;;;;;;GAMG;AACH,QAAQ,CAAC,EAAE,MAAM,GAChB,sBAAsB,CAoNxB"}

package/dist/react/use-media-playback.js

@@ -35,11 +35,14 @@ mediaKey) {
     const onProgressSampleRef = React.useRef(onProgressSample);
     onEndedRef.current = onEnded;
     onProgressSampleRef.current = onProgressSample;
-    const seedPosition = () => typeof startAtSeconds === "number" && startAtSeconds > 0 ? startAtSeconds : null;
+    // The resume position implied by the CURRENT props: a positive
+    // startAtSeconds, or null when the caller supplies none. One declaration —
+    // the mount seed, the mediaKey reset, and the late-arrival effect all read it.
+    const seedFromProps = typeof startAtSeconds === "number" && startAtSeconds > 0 ? startAtSeconds : null;
     // Last known playback position. Seeded from startAtSeconds, then updated once
     // playback has actually started. Survives the unloadOnExit unload/remount
     // cycle because it lives on the (still-mounted) component instance.
-    const lastPositionRef = React.useRef(seedPosition());
+    const lastPositionRef = React.useRef(seedFromProps);
     // True once we have observed real playback progress — after this we resume
     // from lastPositionRef, never re-apply the original startAtSeconds prop.
     const hasStartedRef = React.useRef(false);
@@ -54,7 +57,7 @@ mediaKey) {
     const prevMediaKeyRef = React.useRef(mediaKey);
     if (prevMediaKeyRef.current !== mediaKey) {
         prevMediaKeyRef.current = mediaKey;
-        lastPositionRef.current = seedPosition();
+        lastPositionRef.current = seedFromProps;
         hasStartedRef.current = false;
         lastSampleAtRef.current = 0;
         if (hasEnded)
@@ -91,6 +94,31 @@ mediaKey) {
             /* setting currentTime before ready can throw in some engines; ignore */
         }
     }, []);
+    // Late-arriving resume position. `startAtSeconds` usually comes from an async
+    // app source (a user-prefs query); when that resolves AFTER this hook mounted,
+    // the mount-time seed above saw `undefined` and the element would silently
+    // start at 0. Adopt the value when it finally arrives — but ONLY while nothing
+    // has been seeded, no real playback has begun, and the element is still at the
+    // start, so a late value can never yank media the user is already watching and
+    // can never overwrite a truthful tracked position. A `mediaKey` change resets
+    // both refs in the render-phase block above, which re-arms this for the new
+    // source; the seek itself is applied here because the element may already have
+    // fired `loadedmetadata` (that is exactly this defect) and will not fire it
+    // again — when metadata has not landed yet, `onLoadedMetadata` applies it.
+    React.useEffect(() => {
+        if (seedFromProps === null)
+            return;
+        if (hasStartedRef.current)
+            return;
+        if (lastPositionRef.current !== null)
+            return;
+        const el = elementRef.current;
+        if (el && el.currentTime > 0.01)
+            return;
+        lastPositionRef.current = seedFromProps;
+        if (el)
+            applyInitialSeek(el);
+    }, [seedFromProps, applyInitialSeek, elementRef]);
     const onLoadedMetadata = React.useCallback((e) => {
         applyInitialSeek(e.currentTarget);
     }, [applyInitialSeek]);

package/dist/react/use-media-playback.js.map

@@ -1 +1 @@
-{"version":3,"file":"use-media-playback.js","sourceRoot":"","sources":["../../src/react/use-media-playback.ts"],"names":[],"mappings":"AAAA,YAAY,CAAC;AAEb,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAG/B;;;GAGG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG,IAAI,CAAC;AAgBhD;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,gBAAgB,CAC9B,UAAoD,EACpD,KAAyB,EACzB,mBAAsD;AACtD;;;;;;GAMG;AACH,QAAiB;IAEjB,MAAM,EAAE,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,UAAU,EAAE,GAAG,KAAK,CAAC;IAExE,MAAM,CAAC,QAAQ,EAAE,WAAW,CAAC,GAAG,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;IAEtD,4EAA4E;IAC5E,oDAAoD;IACpD,MAAM,UAAU,GAAG,KAAK,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IACzC,MAAM,mBAAmB,GAAG,KAAK,CAAC,MAAM,CAAC,gBAAgB,CAAC,CAAC;IAC3D,UAAU,CAAC,OAAO,GAAG,OAAO,CAAC;IAC7B,mBAAmB,CAAC,OAAO,GAAG,gBAAgB,CAAC;IAE/C,MAAM,YAAY,GAAG,GAAG,EAAE,CACxB,OAAO,cAAc,KAAK,QAAQ,IAAI,cAAc,GAAG,CAAC,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,IAAI,CAAC;IAEnF,8EAA8E;IAC9E,0EAA0E;IAC1E,oEAAoE;IACpE,MAAM,eAAe,GAAG,KAAK,CAAC,MAAM,CAAgB,YAAY,EAAE,CAAC,CAAC;IACpE,2EAA2E;IAC3E,yEAAyE;IACzE,MAAM,aAAa,GAAG,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAE1C,gFAAgF;IAChF,MAAM,eAAe,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;IAExC,0EAA0E;IAC1E,4EAA4E;IAC5E,wEAAwE;IACxE,4EAA4E;IAC5E,yEAAyE;IACzE,4DAA4D;IAC5D,MAAM,eAAe,GAAG,KAAK,CAAC,MAAM,CAAqB,QAAQ,CAAC,CAAC;IACnE,IAAI,eAAe,CAAC,OAAO,KAAK,QAAQ,EAAE,CAAC;QACzC,eAAe,CAAC,OAAO,GAAG,QAAQ,CAAC;QACnC,eAAe,CAAC,OAAO,GAAG,YAAY,EAAE,CAAC;QACzC,aAAa,CAAC,OAAO,GAAG,KAAK,CAAC;QAC9B,eAAe,CAAC,OAAO,GAAG,CAAC,CAAC;QAC5B,IAAI,QAAQ;YAAE,WAAW,CAAC,KAAK,CAAC,CAAC;IACnC,CAAC;IAED,MAAM,UAAU,GAAG,KAAK,CAAC,WAAW,CAAC,CAAC,EAAoB,EAAE,EAAE;QAC5D,MAAM,EAAE,GAAG,mBAAmB,CAAC,OAAO,CAAC;QACvC,IAAI,CAAC,EAAE;YAAE,OAAO;QAChB,MAAM,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;QAChE,EAAE,CAAC,EAAE,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC;IAC/B,CAAC,EAAE,EAAE,CAAC,CAAC;IAEP,MAAM,aAAa,GAAG,KAAK,CAAC,WAAW,CAAC,CAAC,EAAoB,EAAE,EAAE;QAC/D,IAAI,aAAa,CAAC,OAAO,EAAE,CAAC;YAC1B,eAAe,CAAC,OAAO,GAAG,EAAE,CAAC,WAAW,CAAC;QAC3C,CAAC;IACH,CAAC,EAAE,EAAE,CAAC,CAAC;IAEP,MAAM,gBAAgB,GAAG,KAAK,CAAC,WAAW,CAAC,CAAC,EAAoB,EAAE,EAAE;QAClE,MAAM,MAAM,GAAG,eAAe,CAAC,OAAO,CAAC;QACvC,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,IAAI,CAAC;YAAE,OAAO;QACtD,0EAA0E;QAC1E,2EAA2E;QAC3E,yEAAyE;QACzE,2EAA2E;QAC3E,IAAI,EAAE,CAAC,WAAW,GAAG,IAAI;YAAE,OAAO;QAClC,MAAM,GAAG,GAAG,EAAE,CAAC,QAAQ,CAAC;QACxB,MAAM,OAAO,GAAG,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;QACjF,IAAI,CAAC;YACH,EAAE,CAAC,WAAW,GAAG,OAAO,CAAC;QAC3B,CAAC;QAAC,MAAM,CAAC;YACP,wEAAwE;QAC1E,CAAC;IACH,CAAC,EAAE,EAAE,CAAC,CAAC;IAEP,MAAM,gBAAgB,GAAG,KAAK,CAAC,WAAW,CACxC,CAAC,CAAyC,EAAE,EAAE;QAC5C,gBAAgB,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC;IACpC,CAAC,EACD,CAAC,gBAAgB,CAAC,CACnB,CAAC;IAEF,MAAM,YAAY,GAAG,KAAK,CAAC,WAAW,CACpC,CAAC,CAAyC,EAAE,EAAE;QAC5C,MAAM,EAAE,GAAG,CAAC,CAAC,aAAa,CAAC;QAC3B,yEAAyE;QACzE,oDAAoD;QACpD,IAAI,CAAC,EAAE,CAAC,MAAM,IAAI,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC;YAC5B,aAAa,CAAC,OAAO,GAAG,IAAI,CAAC;QAC/B,CAAC;QACD,aAAa,CAAC,EAAE,CAAC,CAAC;QAClB,IAAI,EAAE,CAAC,MAAM;YAAE,OAAO,CAAC,mCAAmC;QAC1D,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,IAAI,GAAG,GAAG,eAAe,CAAC,OAAO,IAAI,2BAA2B,EAAE,CAAC;YACjE,eAAe,CAAC,OAAO,GAAG,GAAG,CAAC;YAC9B,UAAU,CAAC,EAAE,CAAC,CAAC;QACjB,CAAC;IACH,CAAC,EACD,CAAC,UAAU,EAAE,aAAa,CAAC,CAC5B,CAAC;IAEF,MAAM,MAAM,GAAG,KAAK,CAAC,WAAW,CAAC,GAAG,EAAE;QACpC,yEAAyE;QACzE,WAAW,CAAC,KAAK,CAAC,CAAC;IACrB,CAAC,EAAE,EAAE,CAAC,CAAC;IAEP,MAAM,OAAO,GAAG,KAAK,CAAC,WAAW,CAC/B,CAAC,CAAyC,EAAE,EAAE;QAC5C,MAAM,EAAE,GAAG,CAAC,CAAC,aAAa,CAAC;QAC3B,aAAa,CAAC,EAAE,CAAC,CAAC;QAClB,yEAAyE;QACzE,eAAe,CAAC,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACrC,UAAU,CAAC,EAAE,CAAC,CAAC;IACjB,CAAC,EACD,CAAC,UAAU,EAAE,aAAa,CAAC,CAC5B,CAAC;IAEF,MAAM,QAAQ,GAAG,KAAK,CAAC,WAAW,CAChC,CAAC,CAAyC,EAAE,EAAE;QAC5C,MAAM,EAAE,GAAG,CAAC,CAAC,aAAa,CAAC;QAC3B,aAAa,CAAC,EAAE,CAAC,CAAC;QAClB,sEAAsE;QACtE,eAAe,CAAC,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACrC,UAAU,CAAC,EAAE,CAAC,CAAC;IACjB,CAAC,EACD,CAAC,UAAU,EAAE,aAAa,CAAC,CAC5B,CAAC;IAEF,MAAM,cAAc,GAAG,KAAK,CAAC,WAAW,CACtC,CAAC,CAAyC,EAAE,EAAE;QAC5C,MAAM,EAAE,GAAG,CAAC,CAAC,aAAa,CAAC;QAC3B,uEAAuE;QACvE,aAAa,CAAC,OAAO,GAAG,IAAI,CAAC;QAC7B,eAAe,CAAC,OAAO,GAAG,EAAE,CAAC,WAAW,CAAC;QACzC,gDAAgD;QAChD,eAAe,CAAC,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACrC,UAAU,CAAC,EAAE,CAAC,CAAC;QACf,WAAW,CAAC,IAAI,CAAC,CAAC;QAClB,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC;IACzB,CAAC,EACD,CAAC,UAAU,CAAC,CACb,CAAC;IAEF,wEAAwE;IACxE,KAAK,CAAC,mBAAmB,CACvB,mBAAmB,EACnB,GAA0B,EAAE,CAAC,CAAC;QAC5B,OAAO;YACL,MAAM,EAAE,GAAG,UAAU,CAAC,OAAO,CAAC;YAC9B,IAAI,CAAC,EAAE;gBAAE,OAAO;YAChB,IAAI,CAAC;gBACH,EAAE,CAAC,WAAW,GAAG,CAAC,CAAC;YACrB,CAAC;YAAC,MAAM,CAAC;gBACP,YAAY;YACd,CAAC;YACD,eAAe,CAAC,OAAO,GAAG,CAAC,CAAC;YAC5B,WAAW,CAAC,KAAK,CAAC,CAAC;YACnB,KAAK,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;QACjC,CAAC;QACD,MAAM,CAAC,OAAe;YACpB,MAAM,EAAE,GAAG,UAAU,CAAC,OAAO,CAAC;YAC9B,IAAI,CAAC,EAAE;gBAAE,OAAO;YAChB,MAAM,GAAG,GAAG,EAAE,CAAC,QAAQ,CAAC;YACxB,MAAM,OAAO,GACX,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;YAC/F,IAAI,CAAC;gBACH,EAAE,CAAC,WAAW,GAAG,OAAO,CAAC;YAC3B,CAAC;YAAC,MAAM,CAAC;gBACP,YAAY;YACd,CAAC;YACD,aAAa,CAAC,OAAO,GAAG,IAAI,CAAC;YAC7B,eAAe,CAAC,OAAO,GAAG,OAAO,CAAC;QACpC,CAAC;KACF,CAAC,EACF,CAAC,UAAU,CAAC,CACb,CAAC;IAEF,yEAAyE;IACzE,gEAAgE;IAChE,KAAK,UAAU,CAAC;IAEhB,OAAO;QACL,QAAQ;QACR,QAAQ,EAAE;YACR,gBAAgB;YAChB,YAAY;YACZ,MAAM;YACN,OAAO;YACP,QAAQ;YACR,OAAO,EAAE,cAAc;SACxB;KACF,CAAC;AACJ,CAAC","sourcesContent":["\"use client\";\n\nimport * as React from \"react\";\nimport type { MediaPlaybackControls, MediaPlaybackProps } from \"../types.js\";\n\n/**\n * Throttle interval for periodic progress samples. A sample fires at most once\n * per this many milliseconds of active (non-paused) playback via `timeupdate`.\n */\nexport const PROGRESS_SAMPLE_INTERVAL_MS = 5000;\n\nexport type UseMediaPlaybackResult = {\n  /** Whether the media has ended (drives the end overlay). */\n  hasEnded: boolean;\n  /** Handlers to spread onto the underlying <video>/<audio> element. */\n  handlers: {\n    onLoadedMetadata: (e: React.SyntheticEvent<HTMLMediaElement>) => void;\n    onTimeUpdate: (e: React.SyntheticEvent<HTMLMediaElement>) => void;\n    onPlay: (e: React.SyntheticEvent<HTMLMediaElement>) => void;\n    onPause: (e: React.SyntheticEvent<HTMLMediaElement>) => void;\n    onSeeked: (e: React.SyntheticEvent<HTMLMediaElement>) => void;\n    onEnded: (e: React.SyntheticEvent<HTMLMediaElement>) => void;\n  };\n};\n\n/**\n * Shared playback API for VideoViewer and AudioViewer. Owns the additive\n * playback surface (onEnded, onProgressSample, startAtSeconds, endOverlay,\n * imperative controls) so both viewers behave identically. Adds NO observer —\n * everything is derived from native media element events (MEDIA-102).\n *\n * The element ref is supplied by the viewer (which already owns it for\n * autoplay/fullscreen). When the viewer unloads the element off-screen\n * (`unloadOnExit`) and remounts it on return, the last known playback position\n * is tracked in a component-scoped ref that outlives the element, so playback\n * resumes from where it left off — never from `startAtSeconds` again and never\n * from 0.\n */\nexport function useMediaPlayback(\n  elementRef: React.RefObject<HTMLMediaElement | null>,\n  props: MediaPlaybackProps,\n  playbackControlsRef?: React.Ref<MediaPlaybackControls>,\n  /**\n   * Stable identity for the CURRENT media source (the viewer passes its `url`).\n   * When this changes the media is a different asset, so all resume/progress/\n   * ended tracking is reset — a stale position from the previous media must NOT\n   * carry over onto the new element. Omit when the viewer never reuses one\n   * instance across sources.\n   */\n  mediaKey?: string,\n): UseMediaPlaybackResult {\n  const { onEnded, onProgressSample, startAtSeconds, endOverlay } = props;\n\n  const [hasEnded, setHasEnded] = React.useState(false);\n\n  // Latest callbacks/props via refs so handler identities stay stable and the\n  // element event handlers always see current values.\n  const onEndedRef = React.useRef(onEnded);\n  const onProgressSampleRef = React.useRef(onProgressSample);\n  onEndedRef.current = onEnded;\n  onProgressSampleRef.current = onProgressSample;\n\n  const seedPosition = () =>\n    typeof startAtSeconds === \"number\" && startAtSeconds > 0 ? startAtSeconds : null;\n\n  // Last known playback position. Seeded from startAtSeconds, then updated once\n  // playback has actually started. Survives the unloadOnExit unload/remount\n  // cycle because it lives on the (still-mounted) component instance.\n  const lastPositionRef = React.useRef<number | null>(seedPosition());\n  // True once we have observed real playback progress — after this we resume\n  // from lastPositionRef, never re-apply the original startAtSeconds prop.\n  const hasStartedRef = React.useRef(false);\n\n  // Throttle bookkeeping for periodic samples (wall-clock, active playback only).\n  const lastSampleAtRef = React.useRef(0);\n\n  // Render-phase reset-on-source-change: when the media source (`mediaKey`)\n  // changes, the same component/hook instance is being reused for a DIFFERENT\n  // asset (e.g. a playlist swapping `url` in place). Reset every piece of\n  // per-source tracking so the previous media's position/ended/throttle state\n  // cannot bleed onto the new element. This is the sanctioned render-phase\n  // reset-on-prop-change pattern (not a set-state-in-effect).\n  const prevMediaKeyRef = React.useRef<string | undefined>(mediaKey);\n  if (prevMediaKeyRef.current !== mediaKey) {\n    prevMediaKeyRef.current = mediaKey;\n    lastPositionRef.current = seedPosition();\n    hasStartedRef.current = false;\n    lastSampleAtRef.current = 0;\n    if (hasEnded) setHasEnded(false);\n  }\n\n  const emitSample = React.useCallback((el: HTMLMediaElement) => {\n    const cb = onProgressSampleRef.current;\n    if (!cb) return;\n    const duration = Number.isFinite(el.duration) ? el.duration : 0;\n    cb(el.currentTime, duration);\n  }, []);\n\n  const trackPosition = React.useCallback((el: HTMLMediaElement) => {\n    if (hasStartedRef.current) {\n      lastPositionRef.current = el.currentTime;\n    }\n  }, []);\n\n  const applyInitialSeek = React.useCallback((el: HTMLMediaElement) => {\n    const target = lastPositionRef.current;\n    if (typeof target !== \"number\" || target <= 0) return;\n    // Only seek a freshly-loaded element sitting at the start. This makes the\n    // handler idempotent (a metadata event on an already-positioned element is\n    // a no-op) and, crucially, re-applies the LAST KNOWN position to the new\n    // element created by an unloadOnExit remount — resuming, never restarting.\n    if (el.currentTime > 0.01) return;\n    const dur = el.duration;\n    const clamped = Number.isFinite(dur) && dur > 0 ? Math.min(target, dur) : target;\n    try {\n      el.currentTime = clamped;\n    } catch {\n      /* setting currentTime before ready can throw in some engines; ignore */\n    }\n  }, []);\n\n  const onLoadedMetadata = React.useCallback(\n    (e: React.SyntheticEvent<HTMLMediaElement>) => {\n      applyInitialSeek(e.currentTarget);\n    },\n    [applyInitialSeek],\n  );\n\n  const onTimeUpdate = React.useCallback(\n    (e: React.SyntheticEvent<HTMLMediaElement>) => {\n      const el = e.currentTarget;\n      // Any observed timeupdate while playing means playback has started; from\n      // now on we track live position for remount resume.\n      if (!el.paused && !el.ended) {\n        hasStartedRef.current = true;\n      }\n      trackPosition(el);\n      if (el.paused) return; // no periodic samples while paused\n      const now = Date.now();\n      if (now - lastSampleAtRef.current >= PROGRESS_SAMPLE_INTERVAL_MS) {\n        lastSampleAtRef.current = now;\n        emitSample(el);\n      }\n    },\n    [emitSample, trackPosition],\n  );\n\n  const onPlay = React.useCallback(() => {\n    // Playing again after an ended state (native replay) clears the overlay.\n    setHasEnded(false);\n  }, []);\n\n  const onPause = React.useCallback(\n    (e: React.SyntheticEvent<HTMLMediaElement>) => {\n      const el = e.currentTarget;\n      trackPosition(el);\n      // Flush a sample immediately on pause (final position for this segment).\n      lastSampleAtRef.current = Date.now();\n      emitSample(el);\n    },\n    [emitSample, trackPosition],\n  );\n\n  const onSeeked = React.useCallback(\n    (e: React.SyntheticEvent<HTMLMediaElement>) => {\n      const el = e.currentTarget;\n      trackPosition(el);\n      // Flush a sample on seek completion so the app sees the new position.\n      lastSampleAtRef.current = Date.now();\n      emitSample(el);\n    },\n    [emitSample, trackPosition],\n  );\n\n  const onEndedHandler = React.useCallback(\n    (e: React.SyntheticEvent<HTMLMediaElement>) => {\n      const el = e.currentTarget;\n      // Ended means the play cursor reached duration; record final position.\n      hasStartedRef.current = true;\n      lastPositionRef.current = el.currentTime;\n      // Flush a final sample with the ended position.\n      lastSampleAtRef.current = Date.now();\n      emitSample(el);\n      setHasEnded(true);\n      onEndedRef.current?.();\n    },\n    [emitSample],\n  );\n\n  // Imperative controls. restart() seeks to 0 and plays; seekTo(s) seeks.\n  React.useImperativeHandle(\n    playbackControlsRef,\n    (): MediaPlaybackControls => ({\n      restart() {\n        const el = elementRef.current;\n        if (!el) return;\n        try {\n          el.currentTime = 0;\n        } catch {\n          /* ignore */\n        }\n        lastPositionRef.current = 0;\n        setHasEnded(false);\n        void el.play().catch(() => {});\n      },\n      seekTo(seconds: number) {\n        const el = elementRef.current;\n        if (!el) return;\n        const dur = el.duration;\n        const clamped =\n          Number.isFinite(dur) && dur > 0 ? Math.min(Math.max(seconds, 0), dur) : Math.max(seconds, 0);\n        try {\n          el.currentTime = clamped;\n        } catch {\n          /* ignore */\n        }\n        hasStartedRef.current = true;\n        lastPositionRef.current = clamped;\n      },\n    }),\n    [elementRef],\n  );\n\n  // Ended state is cleared by onPlay (native replay / imperative restart).\n  // endOverlay itself is rendered by the viewer using `hasEnded`.\n  void endOverlay;\n\n  return {\n    hasEnded,\n    handlers: {\n      onLoadedMetadata,\n      onTimeUpdate,\n      onPlay,\n      onPause,\n      onSeeked,\n      onEnded: onEndedHandler,\n    },\n  };\n}\n"]}
+{"version":3,"file":"use-media-playback.js","sourceRoot":"","sources":["../../src/react/use-media-playback.ts"],"names":[],"mappings":"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","sourcesContent":["\"use client\";\n\nimport * as React from \"react\";\nimport type { MediaPlaybackControls, MediaPlaybackProps } from \"../types.js\";\n\n/**\n * Throttle interval for periodic progress samples. A sample fires at most once\n * per this many milliseconds of active (non-paused) playback via `timeupdate`.\n */\nexport const PROGRESS_SAMPLE_INTERVAL_MS = 5000;\n\nexport type UseMediaPlaybackResult = {\n  /** Whether the media has ended (drives the end overlay). */\n  hasEnded: boolean;\n  /** Handlers to spread onto the underlying <video>/<audio> element. */\n  handlers: {\n    onLoadedMetadata: (e: React.SyntheticEvent<HTMLMediaElement>) => void;\n    onTimeUpdate: (e: React.SyntheticEvent<HTMLMediaElement>) => void;\n    onPlay: (e: React.SyntheticEvent<HTMLMediaElement>) => void;\n    onPause: (e: React.SyntheticEvent<HTMLMediaElement>) => void;\n    onSeeked: (e: React.SyntheticEvent<HTMLMediaElement>) => void;\n    onEnded: (e: React.SyntheticEvent<HTMLMediaElement>) => void;\n  };\n};\n\n/**\n * Shared playback API for VideoViewer and AudioViewer. Owns the additive\n * playback surface (onEnded, onProgressSample, startAtSeconds, endOverlay,\n * imperative controls) so both viewers behave identically. Adds NO observer —\n * everything is derived from native media element events (MEDIA-102).\n *\n * The element ref is supplied by the viewer (which already owns it for\n * autoplay/fullscreen). When the viewer unloads the element off-screen\n * (`unloadOnExit`) and remounts it on return, the last known playback position\n * is tracked in a component-scoped ref that outlives the element, so playback\n * resumes from where it left off — never from `startAtSeconds` again and never\n * from 0.\n */\nexport function useMediaPlayback(\n  elementRef: React.RefObject<HTMLMediaElement | null>,\n  props: MediaPlaybackProps,\n  playbackControlsRef?: React.Ref<MediaPlaybackControls>,\n  /**\n   * Stable identity for the CURRENT media source (the viewer passes its `url`).\n   * When this changes the media is a different asset, so all resume/progress/\n   * ended tracking is reset — a stale position from the previous media must NOT\n   * carry over onto the new element. Omit when the viewer never reuses one\n   * instance across sources.\n   */\n  mediaKey?: string,\n): UseMediaPlaybackResult {\n  const { onEnded, onProgressSample, startAtSeconds, endOverlay } = props;\n\n  const [hasEnded, setHasEnded] = React.useState(false);\n\n  // Latest callbacks/props via refs so handler identities stay stable and the\n  // element event handlers always see current values.\n  const onEndedRef = React.useRef(onEnded);\n  const onProgressSampleRef = React.useRef(onProgressSample);\n  onEndedRef.current = onEnded;\n  onProgressSampleRef.current = onProgressSample;\n\n  // The resume position implied by the CURRENT props: a positive\n  // startAtSeconds, or null when the caller supplies none. One declaration —\n  // the mount seed, the mediaKey reset, and the late-arrival effect all read it.\n  const seedFromProps =\n    typeof startAtSeconds === \"number\" && startAtSeconds > 0 ? startAtSeconds : null;\n\n  // Last known playback position. Seeded from startAtSeconds, then updated once\n  // playback has actually started. Survives the unloadOnExit unload/remount\n  // cycle because it lives on the (still-mounted) component instance.\n  const lastPositionRef = React.useRef<number | null>(seedFromProps);\n  // True once we have observed real playback progress — after this we resume\n  // from lastPositionRef, never re-apply the original startAtSeconds prop.\n  const hasStartedRef = React.useRef(false);\n\n  // Throttle bookkeeping for periodic samples (wall-clock, active playback only).\n  const lastSampleAtRef = React.useRef(0);\n\n  // Render-phase reset-on-source-change: when the media source (`mediaKey`)\n  // changes, the same component/hook instance is being reused for a DIFFERENT\n  // asset (e.g. a playlist swapping `url` in place). Reset every piece of\n  // per-source tracking so the previous media's position/ended/throttle state\n  // cannot bleed onto the new element. This is the sanctioned render-phase\n  // reset-on-prop-change pattern (not a set-state-in-effect).\n  const prevMediaKeyRef = React.useRef<string | undefined>(mediaKey);\n  if (prevMediaKeyRef.current !== mediaKey) {\n    prevMediaKeyRef.current = mediaKey;\n    lastPositionRef.current = seedFromProps;\n    hasStartedRef.current = false;\n    lastSampleAtRef.current = 0;\n    if (hasEnded) setHasEnded(false);\n  }\n\n  const emitSample = React.useCallback((el: HTMLMediaElement) => {\n    const cb = onProgressSampleRef.current;\n    if (!cb) return;\n    const duration = Number.isFinite(el.duration) ? el.duration : 0;\n    cb(el.currentTime, duration);\n  }, []);\n\n  const trackPosition = React.useCallback((el: HTMLMediaElement) => {\n    if (hasStartedRef.current) {\n      lastPositionRef.current = el.currentTime;\n    }\n  }, []);\n\n  const applyInitialSeek = React.useCallback((el: HTMLMediaElement) => {\n    const target = lastPositionRef.current;\n    if (typeof target !== \"number\" || target <= 0) return;\n    // Only seek a freshly-loaded element sitting at the start. This makes the\n    // handler idempotent (a metadata event on an already-positioned element is\n    // a no-op) and, crucially, re-applies the LAST KNOWN position to the new\n    // element created by an unloadOnExit remount — resuming, never restarting.\n    if (el.currentTime > 0.01) return;\n    const dur = el.duration;\n    const clamped = Number.isFinite(dur) && dur > 0 ? Math.min(target, dur) : target;\n    try {\n      el.currentTime = clamped;\n    } catch {\n      /* setting currentTime before ready can throw in some engines; ignore */\n    }\n  }, []);\n\n  // Late-arriving resume position. `startAtSeconds` usually comes from an async\n  // app source (a user-prefs query); when that resolves AFTER this hook mounted,\n  // the mount-time seed above saw `undefined` and the element would silently\n  // start at 0. Adopt the value when it finally arrives — but ONLY while nothing\n  // has been seeded, no real playback has begun, and the element is still at the\n  // start, so a late value can never yank media the user is already watching and\n  // can never overwrite a truthful tracked position. A `mediaKey` change resets\n  // both refs in the render-phase block above, which re-arms this for the new\n  // source; the seek itself is applied here because the element may already have\n  // fired `loadedmetadata` (that is exactly this defect) and will not fire it\n  // again — when metadata has not landed yet, `onLoadedMetadata` applies it.\n  React.useEffect(() => {\n    if (seedFromProps === null) return;\n    if (hasStartedRef.current) return;\n    if (lastPositionRef.current !== null) return;\n    const el = elementRef.current;\n    if (el && el.currentTime > 0.01) return;\n    lastPositionRef.current = seedFromProps;\n    if (el) applyInitialSeek(el);\n  }, [seedFromProps, applyInitialSeek, elementRef]);\n\n  const onLoadedMetadata = React.useCallback(\n    (e: React.SyntheticEvent<HTMLMediaElement>) => {\n      applyInitialSeek(e.currentTarget);\n    },\n    [applyInitialSeek],\n  );\n\n  const onTimeUpdate = React.useCallback(\n    (e: React.SyntheticEvent<HTMLMediaElement>) => {\n      const el = e.currentTarget;\n      // Any observed timeupdate while playing means playback has started; from\n      // now on we track live position for remount resume.\n      if (!el.paused && !el.ended) {\n        hasStartedRef.current = true;\n      }\n      trackPosition(el);\n      if (el.paused) return; // no periodic samples while paused\n      const now = Date.now();\n      if (now - lastSampleAtRef.current >= PROGRESS_SAMPLE_INTERVAL_MS) {\n        lastSampleAtRef.current = now;\n        emitSample(el);\n      }\n    },\n    [emitSample, trackPosition],\n  );\n\n  const onPlay = React.useCallback(() => {\n    // Playing again after an ended state (native replay) clears the overlay.\n    setHasEnded(false);\n  }, []);\n\n  const onPause = React.useCallback(\n    (e: React.SyntheticEvent<HTMLMediaElement>) => {\n      const el = e.currentTarget;\n      trackPosition(el);\n      // Flush a sample immediately on pause (final position for this segment).\n      lastSampleAtRef.current = Date.now();\n      emitSample(el);\n    },\n    [emitSample, trackPosition],\n  );\n\n  const onSeeked = React.useCallback(\n    (e: React.SyntheticEvent<HTMLMediaElement>) => {\n      const el = e.currentTarget;\n      trackPosition(el);\n      // Flush a sample on seek completion so the app sees the new position.\n      lastSampleAtRef.current = Date.now();\n      emitSample(el);\n    },\n    [emitSample, trackPosition],\n  );\n\n  const onEndedHandler = React.useCallback(\n    (e: React.SyntheticEvent<HTMLMediaElement>) => {\n      const el = e.currentTarget;\n      // Ended means the play cursor reached duration; record final position.\n      hasStartedRef.current = true;\n      lastPositionRef.current = el.currentTime;\n      // Flush a final sample with the ended position.\n      lastSampleAtRef.current = Date.now();\n      emitSample(el);\n      setHasEnded(true);\n      onEndedRef.current?.();\n    },\n    [emitSample],\n  );\n\n  // Imperative controls. restart() seeks to 0 and plays; seekTo(s) seeks.\n  React.useImperativeHandle(\n    playbackControlsRef,\n    (): MediaPlaybackControls => ({\n      restart() {\n        const el = elementRef.current;\n        if (!el) return;\n        try {\n          el.currentTime = 0;\n        } catch {\n          /* ignore */\n        }\n        lastPositionRef.current = 0;\n        setHasEnded(false);\n        void el.play().catch(() => {});\n      },\n      seekTo(seconds: number) {\n        const el = elementRef.current;\n        if (!el) return;\n        const dur = el.duration;\n        const clamped =\n          Number.isFinite(dur) && dur > 0 ? Math.min(Math.max(seconds, 0), dur) : Math.max(seconds, 0);\n        try {\n          el.currentTime = clamped;\n        } catch {\n          /* ignore */\n        }\n        hasStartedRef.current = true;\n        lastPositionRef.current = clamped;\n      },\n    }),\n    [elementRef],\n  );\n\n  // Ended state is cleared by onPlay (native replay / imperative restart).\n  // endOverlay itself is rendered by the viewer using `hasEnded`.\n  void endOverlay;\n\n  return {\n    hasEnded,\n    handlers: {\n      onLoadedMetadata,\n      onTimeUpdate,\n      onPlay,\n      onPause,\n      onSeeked,\n      onEnded: onEndedHandler,\n    },\n  };\n}\n"]}

package/dist/types.d.ts

@@ -40,6 +40,10 @@ export type MediaPlaybackProps = {
     onProgressSample?: (currentTimeSeconds: number, durationSeconds: number) => void;
     /**
      * Initial playback position (seconds), applied once the element has metadata.
+     * May arrive late (e.g. from an async prefs read that resolves after the
+     * viewer mounted): a value that appears while playback has not yet begun is
+     * adopted and applied to the already-loaded element. Once real playback has
+     * begun a later value is ignored — it never yanks playing media.
      * Survives the `unloadOnExit` unload/remount cycle: once playback has started
      * the viewer tracks the live position internally and resumes from the LAST
      * KNOWN position on remount — it does not re-apply this prop and does not

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"","sourcesContent":["import type * as React from \"react\";\nimport type { MediaDiagnosticAdapter, AssetStatusHint } from \"./recovery.js\";\nimport type { AudioVisualizerMode } from \"./visualizer.js\";\n\nexport type { MediaDiagnosticAdapter, AssetStatusHint, DiagnosisResult, RecoveryState } from \"./recovery.js\";\nexport type { AudioVisualizerMode } from \"./visualizer.js\";\n\nexport type MediaViewerType = \"image\" | \"video\" | \"audio\" | \"other\";\nexport type FallbackMode = \"none\" | \"link\";\n\n/**\n * Imperative playback controls, exposed via the `playbackControlsRef` prop on\n * `VideoViewer` / `AudioViewer` (and forwarded by `MediaPreview` for\n * video/audio). Obtain via `React.useRef<MediaPlaybackControls>(null)`.\n */\nexport type MediaPlaybackControls = {\n  /** Seek to 0 and play from the start. Clears any end-overlay. */\n  restart(): void;\n  /** Seek to the given position (seconds), clamped to [0, duration]. */\n  seekTo(seconds: number): void;\n};\n\n/**\n * Additive, fully optional playback API shared by `VideoViewer` and\n * `AudioViewer`. Every field is optional; when all are absent the viewers\n * behave exactly as before.\n */\nexport type MediaPlaybackProps = {\n  /**\n   * Fires when the media element ends (native `ended` event) with the play\n   * cursor at duration. NOTE: when `loop` is set the browser restarts natively\n   * and emits no `ended` event, so `onEnded` never fires in that mode.\n   */\n  onEnded?: () => void;\n\n  /**\n   * Periodic playback-position reporting. Contract:\n   * - While playing, fires at most once every ~5 seconds of playback\n   *   (throttled off `timeupdate`).\n   * - Fires once immediately on pause, on seek completion (`seeked`), and on\n   *   ended — each carrying the exact position at that moment.\n   * - Never fires while paused (aside from the single pause-flush above).\n   * `durationSeconds` is `0` until the element's duration is known.\n   */\n  onProgressSample?: (currentTimeSeconds: number, durationSeconds: number) => void;\n\n  /**\n   * Initial playback position (seconds), applied once the element has metadata.\n   * Survives the `unloadOnExit` unload/remount cycle: once playback has started\n   * the viewer tracks the live position internally and resumes from the LAST\n   * KNOWN position on remount — it does not re-apply this prop and does not\n   * restart at 0.\n   */\n  startAtSeconds?: number;\n\n  /**\n   * Rendered as an overlay covering the media area when the media has ended.\n   * Removed when playback restarts (native replay or imperative `restart()`).\n   * The overlay only intercepts pointer events while shown and renders above\n   * the element. In a native-fullscreen exit state the overlay reappears over\n   * the inline element (it is part of normal document flow, not the fullscreen\n   * layer).\n   */\n  endOverlay?: React.ReactNode;\n\n  /** Imperative controls handle — see {@link MediaPlaybackControls}. */\n  playbackControlsRef?: React.Ref<MediaPlaybackControls>;\n};\n\nexport type BaseMediaProps = {\n  url: string;\n  className?: string;\n  mediaClassName?: string;\n  lazy?: boolean;\n  priority?: boolean;\n  skeleton?: boolean;\n  onLoad?: () => void;\n  onError?: () => void;\n  fallback?: React.ReactNode;\n  /**\n   * Load-watchdog budget in ms (default LOAD_WATCHDOG_MS). A visible, loading\n   * element that produces neither a load/metadata nor an error event within\n   * this budget synthesizes an error so the asset resolves to a bounded\n   * terminal state instead of an eternal skeleton. `0` disables.\n   */\n  loadTimeoutMs?: number;\n};\n\nexport type ImageViewerProps = BaseMediaProps & {\n  alt?: string;\n  enableZoom?: boolean;\n  unloadOnExit?: boolean;\n  isCircular?: boolean;\n  preventGestures?: boolean;\n};\n\nexport type VideoViewerProps = BaseMediaProps & MediaPlaybackProps & {\n  controls?: boolean;\n  autoPlay?: boolean;\n  muted?: boolean;\n  loop?: boolean;\n  posterUrl?: string;\n  enableFullscreen?: boolean;\n  unloadOnExit?: boolean;\n  preload?: \"auto\" | \"metadata\" | \"none\";\n  autoPlayOnVisible?: boolean;\n};\n\nexport type AudioViewerProps = BaseMediaProps & MediaPlaybackProps & {\n  autoPlay?: boolean;\n  loop?: boolean;\n  preload?: \"auto\" | \"metadata\" | \"none\";\n  onLoadChange?: (isLoading: boolean) => void;\n\n  // AudioViewer always uses the package-owned control surface. Native browser\n  // audio controls are intentionally not part of the public contract.\n  /** Initial visualizer mode (\"line\" oscilloscope | \"bars\" EQ). A persisted user choice wins. */\n  visualizerMode?: AudioVisualizerMode;\n  /** localStorage key base for the minimize/mode prefs. `null` disables persistence. */\n  persistKey?: string | null;\n  /** App-injected action buttons rendered at the end of the player control row. */\n  extraActions?: React.ReactNode;\n};\n\nexport type MediaPreviewProps = {\n  url?: string | File | Blob | null;\n  alt?: string;\n  type?: MediaViewerType | string;\n  className?: string;\n  unloadOnExit?: boolean;\n  isCircular?: boolean;\n  priority?: boolean;\n  skeleton?: boolean;\n  lazy?: boolean;\n  /** Video controls only. Audio always renders the canonical package-owned controls. */\n  controls?: boolean;\n  autoPlay?: boolean;\n  muted?: boolean;\n  loop?: boolean;\n  posterUrl?: string;\n  preload?: \"auto\" | \"metadata\" | \"none\";\n  autoPlayOnVisible?: boolean;\n  onLoad?: () => void;\n  onError?: () => void;\n  onLoadChange?: (isLoading: boolean) => void;\n\n  // -------------------------------------------------------------------------\n  // Playback API (additive, optional) — forwarded to the video/audio viewer.\n  // Ignored for image/other types. See MediaPlaybackProps for the contract.\n  // -------------------------------------------------------------------------\n  onEnded?: MediaPlaybackProps[\"onEnded\"];\n  onProgressSample?: MediaPlaybackProps[\"onProgressSample\"];\n  startAtSeconds?: MediaPlaybackProps[\"startAtSeconds\"];\n  endOverlay?: MediaPlaybackProps[\"endOverlay\"];\n  playbackControlsRef?: MediaPlaybackProps[\"playbackControlsRef\"];\n\n  // Audio always uses the package-owned player. These props customize that\n  // single control surface and are ignored for every other media type.\n  audioVisualizerMode?: AudioVisualizerMode;\n  audioPersistKey?: string | null;\n  audioExtraActions?: React.ReactNode;\n\n  fallbackMode?: FallbackMode;\n  fallbackLabel?: string;\n  filename?: string;\n  mime?: string;\n  name?: string;\n\n  // -------------------------------------------------------------------------\n  // Recovery adapter (additive, optional — backward-compatible)\n  // -------------------------------------------------------------------------\n  /**\n   * Injected diagnostic adapter. When provided, element load errors for\n   * assets the app believes are live will trigger the bounded recovery state\n   * machine. When omitted, the existing error fallback behavior is unchanged.\n   */\n  recoveryAdapter?: MediaDiagnosticAdapter;\n\n  /**\n   * Optional app hint about the server-side lifecycle state of the asset.\n   * Drives which recovery phase is shown (e.g. processing → skeleton,\n   * finalizing → spinner, failed/rejected → hard error immediately).\n   */\n  assetStatusHint?: AssetStatusHint;\n\n  /** Load-watchdog budget forwarded to the underlying viewer — see BaseMediaProps. */\n  loadTimeoutMs?: number;\n};\n\n/** Back-compat alias */\nexport type MediaViewerProps = MediaPreviewProps;\n"]}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"","sourcesContent":["import type * as React from \"react\";\nimport type { MediaDiagnosticAdapter, AssetStatusHint } from \"./recovery.js\";\nimport type { AudioVisualizerMode } from \"./visualizer.js\";\n\nexport type { MediaDiagnosticAdapter, AssetStatusHint, DiagnosisResult, RecoveryState } from \"./recovery.js\";\nexport type { AudioVisualizerMode } from \"./visualizer.js\";\n\nexport type MediaViewerType = \"image\" | \"video\" | \"audio\" | \"other\";\nexport type FallbackMode = \"none\" | \"link\";\n\n/**\n * Imperative playback controls, exposed via the `playbackControlsRef` prop on\n * `VideoViewer` / `AudioViewer` (and forwarded by `MediaPreview` for\n * video/audio). Obtain via `React.useRef<MediaPlaybackControls>(null)`.\n */\nexport type MediaPlaybackControls = {\n  /** Seek to 0 and play from the start. Clears any end-overlay. */\n  restart(): void;\n  /** Seek to the given position (seconds), clamped to [0, duration]. */\n  seekTo(seconds: number): void;\n};\n\n/**\n * Additive, fully optional playback API shared by `VideoViewer` and\n * `AudioViewer`. Every field is optional; when all are absent the viewers\n * behave exactly as before.\n */\nexport type MediaPlaybackProps = {\n  /**\n   * Fires when the media element ends (native `ended` event) with the play\n   * cursor at duration. NOTE: when `loop` is set the browser restarts natively\n   * and emits no `ended` event, so `onEnded` never fires in that mode.\n   */\n  onEnded?: () => void;\n\n  /**\n   * Periodic playback-position reporting. Contract:\n   * - While playing, fires at most once every ~5 seconds of playback\n   *   (throttled off `timeupdate`).\n   * - Fires once immediately on pause, on seek completion (`seeked`), and on\n   *   ended — each carrying the exact position at that moment.\n   * - Never fires while paused (aside from the single pause-flush above).\n   * `durationSeconds` is `0` until the element's duration is known.\n   */\n  onProgressSample?: (currentTimeSeconds: number, durationSeconds: number) => void;\n\n  /**\n   * Initial playback position (seconds), applied once the element has metadata.\n   * May arrive late (e.g. from an async prefs read that resolves after the\n   * viewer mounted): a value that appears while playback has not yet begun is\n   * adopted and applied to the already-loaded element. Once real playback has\n   * begun a later value is ignored — it never yanks playing media.\n   * Survives the `unloadOnExit` unload/remount cycle: once playback has started\n   * the viewer tracks the live position internally and resumes from the LAST\n   * KNOWN position on remount — it does not re-apply this prop and does not\n   * restart at 0.\n   */\n  startAtSeconds?: number;\n\n  /**\n   * Rendered as an overlay covering the media area when the media has ended.\n   * Removed when playback restarts (native replay or imperative `restart()`).\n   * The overlay only intercepts pointer events while shown and renders above\n   * the element. In a native-fullscreen exit state the overlay reappears over\n   * the inline element (it is part of normal document flow, not the fullscreen\n   * layer).\n   */\n  endOverlay?: React.ReactNode;\n\n  /** Imperative controls handle — see {@link MediaPlaybackControls}. */\n  playbackControlsRef?: React.Ref<MediaPlaybackControls>;\n};\n\nexport type BaseMediaProps = {\n  url: string;\n  className?: string;\n  mediaClassName?: string;\n  lazy?: boolean;\n  priority?: boolean;\n  skeleton?: boolean;\n  onLoad?: () => void;\n  onError?: () => void;\n  fallback?: React.ReactNode;\n  /**\n   * Load-watchdog budget in ms (default LOAD_WATCHDOG_MS). A visible, loading\n   * element that produces neither a load/metadata nor an error event within\n   * this budget synthesizes an error so the asset resolves to a bounded\n   * terminal state instead of an eternal skeleton. `0` disables.\n   */\n  loadTimeoutMs?: number;\n};\n\nexport type ImageViewerProps = BaseMediaProps & {\n  alt?: string;\n  enableZoom?: boolean;\n  unloadOnExit?: boolean;\n  isCircular?: boolean;\n  preventGestures?: boolean;\n};\n\nexport type VideoViewerProps = BaseMediaProps & MediaPlaybackProps & {\n  controls?: boolean;\n  autoPlay?: boolean;\n  muted?: boolean;\n  loop?: boolean;\n  posterUrl?: string;\n  enableFullscreen?: boolean;\n  unloadOnExit?: boolean;\n  preload?: \"auto\" | \"metadata\" | \"none\";\n  autoPlayOnVisible?: boolean;\n};\n\nexport type AudioViewerProps = BaseMediaProps & MediaPlaybackProps & {\n  autoPlay?: boolean;\n  loop?: boolean;\n  preload?: \"auto\" | \"metadata\" | \"none\";\n  onLoadChange?: (isLoading: boolean) => void;\n\n  // AudioViewer always uses the package-owned control surface. Native browser\n  // audio controls are intentionally not part of the public contract.\n  /** Initial visualizer mode (\"line\" oscilloscope | \"bars\" EQ). A persisted user choice wins. */\n  visualizerMode?: AudioVisualizerMode;\n  /** localStorage key base for the minimize/mode prefs. `null` disables persistence. */\n  persistKey?: string | null;\n  /** App-injected action buttons rendered at the end of the player control row. */\n  extraActions?: React.ReactNode;\n};\n\nexport type MediaPreviewProps = {\n  url?: string | File | Blob | null;\n  alt?: string;\n  type?: MediaViewerType | string;\n  className?: string;\n  unloadOnExit?: boolean;\n  isCircular?: boolean;\n  priority?: boolean;\n  skeleton?: boolean;\n  lazy?: boolean;\n  /** Video controls only. Audio always renders the canonical package-owned controls. */\n  controls?: boolean;\n  autoPlay?: boolean;\n  muted?: boolean;\n  loop?: boolean;\n  posterUrl?: string;\n  preload?: \"auto\" | \"metadata\" | \"none\";\n  autoPlayOnVisible?: boolean;\n  onLoad?: () => void;\n  onError?: () => void;\n  onLoadChange?: (isLoading: boolean) => void;\n\n  // -------------------------------------------------------------------------\n  // Playback API (additive, optional) — forwarded to the video/audio viewer.\n  // Ignored for image/other types. See MediaPlaybackProps for the contract.\n  // -------------------------------------------------------------------------\n  onEnded?: MediaPlaybackProps[\"onEnded\"];\n  onProgressSample?: MediaPlaybackProps[\"onProgressSample\"];\n  startAtSeconds?: MediaPlaybackProps[\"startAtSeconds\"];\n  endOverlay?: MediaPlaybackProps[\"endOverlay\"];\n  playbackControlsRef?: MediaPlaybackProps[\"playbackControlsRef\"];\n\n  // Audio always uses the package-owned player. These props customize that\n  // single control surface and are ignored for every other media type.\n  audioVisualizerMode?: AudioVisualizerMode;\n  audioPersistKey?: string | null;\n  audioExtraActions?: React.ReactNode;\n\n  fallbackMode?: FallbackMode;\n  fallbackLabel?: string;\n  filename?: string;\n  mime?: string;\n  name?: string;\n\n  // -------------------------------------------------------------------------\n  // Recovery adapter (additive, optional — backward-compatible)\n  // -------------------------------------------------------------------------\n  /**\n   * Injected diagnostic adapter. When provided, element load errors for\n   * assets the app believes are live will trigger the bounded recovery state\n   * machine. When omitted, the existing error fallback behavior is unchanged.\n   */\n  recoveryAdapter?: MediaDiagnosticAdapter;\n\n  /**\n   * Optional app hint about the server-side lifecycle state of the asset.\n   * Drives which recovery phase is shown (e.g. processing → skeleton,\n   * finalizing → spinner, failed/rejected → hard error immediately).\n   */\n  assetStatusHint?: AssetStatusHint;\n\n  /** Load-watchdog budget forwarded to the underlying viewer — see BaseMediaProps. */\n  loadTimeoutMs?: number;\n};\n\n/** Back-compat alias */\nexport type MediaViewerProps = MediaPreviewProps;\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ttt-productions/media-viewer",
-  "version": "0.10.6",
+  "version": "0.10.7",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ttt-productions/ttt-packages.git",
@@ -33,8 +33,8 @@
     "prepublishOnly": "npm run clean && npm run build"
   },
   "dependencies": {
-    "@ttt-productions/media-schemas": "^0.14.3",
-    "@ttt-productions/ui-core": "^0.11.10"
+    "@ttt-productions/media-schemas": "^0.14.4",
+    "@ttt-productions/ui-core": "^0.11.12"
   },
   "peerDependencies": {
     "react": ">=19.0.0",