@hyperframes/player 0.6.0 → 0.6.1

package/dist/hyperframes-player.d.cts

@@ -1,3 +1,29 @@
+/**
+ * Parent-frame media proxy subsystem.
+ *
+ * Maintains mirror copies of the iframe's timed `<audio>`/`<video>` elements
+ * in the parent frame so that mobile browsers — which gate `el.play()` on user
+ * activation in the *same* frame — can still produce audible output via proxies
+ * the parent controls directly.
+ *
+ * See the class-level JSDoc on `HyperframesPlayer` for the full ownership model.
+ */
+interface ProxyEntry {
+    el: HTMLMediaElement;
+    start: number;
+    duration: number;
+    /**
+     * Count of consecutive steady-state samples in which the proxy's
+     * `currentTime` was found drifted beyond `MIRROR_DRIFT_THRESHOLD_SECONDS`.
+     * Reset on every in-threshold sample. A write is only issued once this
+     * reaches `MIRROR_REQUIRED_CONSECUTIVE_DRIFT_SAMPLES`, absorbing
+     * single-sample jitter without thrashing.
+     */
+    driftSamples: number;
+}
+
+type ShaderLoadingMode = "composition" | "player" | "none";
+
 interface ControlsCallbacks {
     onPlay: () => void;
     onPause: () => void;
@@ -15,7 +41,6 @@ interface ControlsOptions {
 declare function formatSpeed(speed: number): string;
 declare function formatTime(seconds: number): string;
 
-type ShaderLoadingMode = "composition" | "player" | "none";
 declare class HyperframesPlayer extends HTMLElement {
     static get observedAttributes(): string[];
     private shadow;
@@ -24,124 +49,31 @@ declare class HyperframesPlayer extends HTMLElement {
     private posterEl;
     private controlsApi;
     private resizeObserver;
-    private shaderLoaderEl;
-    private shaderLoaderFillEl;
-    private shaderLoaderTitleEl;
-    private shaderLoaderDetailEl;
-    private shaderLoaderTransitionValueEl;
-    private shaderLoaderFrameLabelEl;
-    private shaderLoaderFrameValueEl;
-    private shaderLoaderFrameRowEl;
-    private shaderLoaderHideTimeout;
+    private shaderLoader;
+    private probe;
     private _ready;
-    private _duration;
     private _currentTime;
+    private _duration;
     private _paused;
+    private _lastUpdateMs;
     private _volume;
     private _compositionWidth;
     private _compositionHeight;
-    private _probeInterval;
-    private _lastUpdateMs;
     private _directTimelineAdapter;
-    private _directTimelineRaf;
-    /**
-     * Parent-frame audio/video proxies, preloaded mirror copies of the iframe's
-     * timed media. They exist as a fallback for environments that block iframe
-     * `.play()` — mobile browsers require the user gesture to originate in the
-     * same frame as the media element, and postMessage doesn't transfer user
-     * activation (User Activation v2). The runtime inside the iframe signals
-     * `media-autoplay-blocked` the first time a play() attempt rejects with
-     * `NotAllowedError`; receiving that message flips `_audioOwner` to `parent`
-     * and these proxies start driving audible output while the iframe keeps
-     * advancing timed media silently for frame-accurate state.
-     *
-     * Preloading at iframe-load time (rather than lazily on promotion) keeps
-     * the audible audio cut-in tight when the promotion fires mid-playback.
-     */
-    private _parentMedia;
-    /**
-     * Who owns audible playback right now.
-     *
-     * - `runtime` (default): the iframe's runtime drives timed media; parent
-     *   proxies stay paused and silent. This is the correct path on desktop,
-     *   in same-frame embeds, and anywhere the iframe has user activation.
-     * - `parent`: parent-frame proxies drive audible output; the iframe keeps
-     *   syncing timed media but at `muted = true` (orthogonal to author/user
-     *   volume settings). Entered only in response to an actual autoplay
-     *   rejection from the runtime — we don't guess device class.
-     *
-     * The transition is one-way per session; once autoplay is known to be
-     * gated, there's no benefit to attempting the iframe path again.
-     */
-    private _audioOwner;
-    /**
-     * Watches the iframe document for sub-composition media added after
-     * initial setup. Disconnected on iframe reload (fresh iframe = fresh
-     * observer against the new document).
-     */
-    private _mediaObserver?;
-    /**
-     * One-shot latch for `playbackerror`. Without it, under parent ownership
-     * where the parent frame itself lacks activation, every paused→playing
-     * transition in the iframe state loop would re-fire `play()` (and its
-     * rejection) on each proxy — spamming host subscribers through a whole
-     * playback session. Mirrors the `mediaAutoplayBlockedPosted` latch on the
-     * runtime side. Cleared on `_onIframeLoad` alongside the owner reset, so
-     * a fresh composition gets a fresh shot at surfacing the error.
-     */
-    private _playbackErrorPosted;
+    private _directTimelineClock;
+    private _media;
     constructor();
     connectedCallback(): void;
     disconnectedCallback(): void;
     attributeChangedCallback(name: string, _old: string | null, val: string | null): void;
     /**
-     * Access the inner `<iframe>` element rendering the composition.
-     *
-     * Use this when integrating the player with editors, recorders, or
-     * timeline tools (e.g. `@hyperframes/studio`) that need to inspect
-     * the composition's DOM or read its `__player` / `__timelines`
-     * runtime objects.
-     *
-     * **Common pitfall:** the iframe lives inside the player's Shadow DOM.
-     * Passing the `<hyperframes-player>` element itself to code that expects
-     * an `<iframe>` will silently break — `.contentWindow` returns `null`.
-     * Always extract `iframeElement` first:
-     *
-     * ```ts
-     * // ❌ Wrong — element ref doesn't expose contentWindow
-     * iframeRef.current = playerRef.current;
-     *
-     * // ✓ Right — bridge the actual iframe
-     * iframeRef.current = playerRef.current.iframeElement;
-     * ```
+     * The inner `<iframe>` rendering the composition. Use this when integrating
+     * with tools that need `contentWindow` — `.contentWindow` on the
+     * `<hyperframes-player>` element itself returns `null` (Shadow DOM).
      */
     get iframeElement(): HTMLIFrameElement;
     play(): void;
     pause(): void;
-    /**
-     * Move playback to `timeInSeconds`.
-     *
-     * Two transports, with different precision semantics — read this before
-     * writing assertions against `seek` from outside the player:
-     *
-     * - **Same-origin (sync) path** — when the runtime's `window.__player.seek`
-     *   is reachable, we call it directly. `timeInSeconds` is forwarded
-     *   *verbatim* (no rounding), so a same-origin scrub of `seek(7.3333)`
-     *   lands the runtime at `7.3333 s` — sub-frame precision relative to
-     *   `DEFAULT_FPS` (30). Studio scrub UIs that need fractional-frame
-     *   alignment (e.g. waveform scrubbing on long-duration audio) get the
-     *   exact requested time.
-     * - **Cross-origin (postMessage) path** — when same-origin access throws
-     *   or `__player.seek` is missing, we fall back to the postMessage bridge.
-     *   The wire protocol carries integer frames (`frame: Math.round(t × FPS)`),
-     *   so cross-origin embeds are *frame-quantized* and `seek(7.3333)` lands
-     *   at `Math.round(7.3333 × 30) / 30 ≈ 7.3333…` (same value here, but for
-     *   most fractional inputs you'll see a snap to the nearest 1/30 s).
-     *
-     * `this._currentTime` always reflects the *requested* `timeInSeconds`
-     * regardless of transport, so the controls UI shows the un-quantized value
-     * either way; the asymmetry only affects what the runtime actually paints.
-     */
     seek(timeInSeconds: number): void;
     get currentTime(): number;
     set currentTime(t: number);
@@ -161,172 +93,24 @@ declare class HyperframesPlayer extends HTMLElement {
     get loop(): boolean;
     set loop(l: boolean);
     private _sendControl;
-    private _shaderCaptureScaleParam;
-    private _shaderLoadingMode;
-    private _prepareSrc;
-    private _prepareSrcdoc;
     private _reloadShaderOptions;
-    private _createShaderLoader;
-    private _showShaderLoader;
-    private _hideShaderLoader;
-    private _scheduleShaderLoaderHideCleanup;
-    private _resetShaderLoader;
-    private _updateShaderLoader;
-    /**
-     * Reach into the runtime's `window.__player.seek` directly, skipping the
-     * postMessage hop. Same-origin only — cross-origin embeds throw a
-     * `SecurityError` on `contentWindow` property access, which we catch and
-     * report as a no-op so the caller can transparently fall back to the
-     * postMessage bridge. Returns `true` only when the runtime accepted the
-     * call (`__player.seek` exists, is callable, and didn't throw).
-     *
-     * Studio has used this access path privately via `iframe.contentWindow.__player`
-     * (see `useTimelinePlayer.ts`); this helper just formalizes the same
-     * detection inside the player so external scrub UIs get the same
-     * single-task latency. The runtime-side `seek` is the same wrapped
-     * function the postMessage handler calls (`installRuntimeControlBridge`
-     * routes through `player.seek`), so `markExplicitSeek()` and downstream
-     * runtime state stay identical between the two paths.
-     */
     private _trySyncSeek;
+    private _withDirectTimeline;
     private _tryDirectTimelineSeek;
     private _tryDirectTimelinePlay;
     private _tryDirectTimelinePause;
-    private _startDirectTimelineClock;
-    private _stopDirectTimelineClock;
-    private _resolveDirectTimelineAdapter;
-    private _resolveDirectTimelineAdapterFromWindow;
-    private _hasRuntimeBridge;
-    private _resolvePlaybackDurationAdapter;
-    private _isControlsClick;
     private _onMessage;
-    private _runtimeInjected;
+    private _onProbeReady;
+    private _rescale;
     private _onIframeLoad;
-    /** Inject the HyperFrames runtime into the iframe if not already present. */
-    private _injectRuntime;
-    private _updateScale;
     private _setupControls;
-    private _setupPoster;
-    private _playParentMedia;
-    private _reportPlaybackError;
-    private _pauseParentMedia;
-    /**
-     * Drag parent-proxy `currentTime` onto the iframe's timeline. Called on
-     * every runtime state message under parent ownership. Threshold is 50 ms
-     * — ITU-R BT.1359 puts A/V offset perceptibility at roughly ±45 ms, so
-     * anything looser risks audible lip-sync drift on talking-head content
-     * (a core use case). The re-seek cost at this tightness is a handful of
-     * extra `currentTime` writes per second; the media element's own buffer
-     * smooths them out without visible rebuffer on the mirror path.
-     */
-    private static readonly MIRROR_DRIFT_THRESHOLD_SECONDS;
-    /**
-     * How many *consecutive* over-threshold steady-state samples we wait for
-     * before issuing a `currentTime` write. A value of 2 means a single
-     * spike (one slow bridge tick, one tab-throttled rAF batch, one GC pause)
-     * is absorbed without a seek; sustained drift still corrects on the very
-     * next tick after the threshold is crossed twice in a row.
-     *
-     * **Coupling with the timeline-control bridge** — read before changing:
-     *   worst_case_correction_latency_ms
-     *     ≈ MIRROR_REQUIRED_CONSECUTIVE_DRIFT_SAMPLES × bridgeMaxPostIntervalMs
-     *
-     * `bridgeMaxPostIntervalMs` (currently `80`) lives at
-     * `packages/core/src/runtime/state.ts` (field on `RuntimeState`). At
-     * today's values, worst-case is `2 × 80 ms = 160 ms` — still well under
-     * the human shot-change tolerance for A/V re-sync. If you bump bridge
-     * cadence (raising `bridgeMaxPostIntervalMs`) you may need to drop this
-     * constant to `1` to keep the product under ~150 ms; if you tighten
-     * cadence you can raise this to absorb more jitter without perceptual
-     * cost. There is a back-reference in `state.ts` next to
-     * `bridgeMaxPostIntervalMs` so a change to either side surfaces the
-     * coupling.
-     */
-    private static readonly MIRROR_REQUIRED_CONSECUTIVE_DRIFT_SAMPLES;
-    /**
-     * Mirror parent-proxy `currentTime` to the iframe timeline. Defaults to
-     * the *coalesced* path: a single over-threshold sample is treated as
-     * jitter and merely increments a per-proxy counter; the actual seek only
-     * fires once `MIRROR_REQUIRED_CONSECUTIVE_DRIFT_SAMPLES` consecutive
-     * samples agree. Pass `{ force: true }` for one-shot alignment moments
-     * (audio-ownership promotion, brand-new proxy initialization) where we
-     * cannot tolerate even ~80 ms of misaligned audible playback.
-     *
-     * The counter is also reset on any in-threshold sample and on any
-     * out-of-range timeline position, so a proxy that drops back into a
-     * scene later starts fresh rather than carrying stale samples from the
-     * last time it was active.
-     */
-    private _mirrorParentMediaTime;
-    /**
-     * Take ownership of audible playback. Fired in response to the runtime's
-     * `media-autoplay-blocked` signal — the iframe has lost the autoplay lottery
-     * and will never produce audio without a fresh gesture inside itself.
-     *
-     * Effects, in order:
-     *   1. Ask the runtime to mute its own media output via the bridge. The
-     *      runtime then keeps advancing timed media for frame-accurate state
-     *      but produces no sound of its own, freeing us to be the single
-     *      audible source without racing a volume-reassert loop.
-     *   2. Align every parent proxy's currentTime to the iframe's timeline so
-     *      the cut-over is imperceptible.
-     *   3. If the player is currently playing, start the proxies.
-     *
-     * Idempotent: repeat calls are a no-op.
-     */
-    private _promoteToParentProxy;
-    /**
-     * Create a parent-frame media element, configure it, and start preloading.
-     * Returns the newly-created proxy entry, or `null` if one already exists for
-     * this src (dedup) — callers that need to act on the new element should
-     * branch on the return value rather than inferring via `_parentMedia.length`.
-     */
-    private _createParentMedia;
-    /**
-     * Set up a single parent-frame audio from an explicit URL (via `audio-src`).
-     * Convenience for the common single-narration case — starts preloading
-     * immediately without waiting for the iframe to load.
-     */
-    private _setupParentAudioFromUrl;
-    /**
-     * Mirror every timed iframe media element (`audio[data-start]`,
-     * `video[data-start]`) into a parent-frame proxy. The proxies preload at
-     * iframe-ready time so the cut-over to parent ownership — should the
-     * runtime's autoplay attempt later reject — is instantaneous.
-     *
-     * Under runtime ownership (the default) these proxies stay paused and
-     * inert; the iframe is the audible source. Ownership flips only in
-     * response to a real `media-autoplay-blocked` message from the runtime.
-     *
-     * Also installs a MutationObserver so that media added to the iframe
-     * *after* the initial scan (sub-composition activation is the common
-     * case) gets a proxy on the fly. Without this, under parent ownership
-     * late-added `<audio data-start>` would be silenced by the runtime
-     * (`outputMuted` sticks per-tick) but have no parent-frame counterpart
-     * to play — a silent hole in the audio track.
-     */
-    private _setupParentMedia;
-    /**
-     * Create a parent-frame proxy mirroring a single iframe media element.
-     * Extracted so both the initial scan and the MutationObserver path use
-     * identical URL-resolution and attribute parsing.
-     */
-    private _adoptIframeMedia;
-    /**
-     * Watch the iframe document for subtree additions of timed media so
-     * sub-composition activation (late-attached `<audio data-start>`) grows
-     * the parent-proxy set automatically. Disconnected on iframe reload via
-     * `_teardownMediaObserver`.
-     */
-    private _observeDynamicMedia;
-    private _teardownMediaObserver;
-    /**
-     * Inverse of `_adoptIframeMedia`: drop the parent proxy mirroring a removed
-     * iframe media element. Resolves the src identically so matching is exact,
-     * then pauses, clears the src (frees the decoder), and splices it out.
-     */
-    private _detachIframeMedia;
-    private _hidePoster;
+    get _audioOwner(): "parent" | "runtime";
+    get _parentMedia(): ProxyEntry[];
+    _mirrorParentMediaTime(t: number, opts?: {
+        force?: boolean;
+    }): void;
+    _promoteToParentProxy(): void;
+    _observeDynamicMedia(doc: Document): void;
 }
 
 export { type ControlsCallbacks, type ControlsOptions, HyperframesPlayer, SPEED_PRESETS, type ShaderLoadingMode, formatSpeed, formatTime };