@hyperframes/core 0.8.45 → 0.8.47

package/dist/compositionReadiness.d.ts

@@ -0,0 +1,28 @@
+/** A composition is "ready" once every declared input settles, not just once
+ * its duration is known. Each input returns null (nothing to wait on) or a
+ * promise that resolves once it settles. */
+export type CompositionReadinessInput = (doc: Document) => Promise<void> | null;
+export interface PendingCompositionAssets {
+    pendingMedia: HTMLMediaElement[];
+    pendingImages: HTMLImageElement[];
+    fontsLoading: boolean;
+}
+export declare function isRealmElement(node: Node): node is Element;
+export declare function isRealmHtmlMediaElement(node: Node): node is HTMLMediaElement;
+/** One DOM pass for every declared-media asset not yet ready. */
+export declare function scanPendingCompositionAssets(doc: Document): PendingCompositionAssets;
+/** Declared-media readiness input: waits on the composition's own video,
+ * audio, image and font-face loads. */
+export declare function mediaReadinessInput(doc: Document): Promise<void> | null;
+export interface CompositionReadinessResult {
+    timedOut: boolean;
+}
+/** Invokes `onSettled` once every input settles, or the timeout elapses.
+ * Calls back synchronously, before returning, when nothing is pending — a
+ * caller that plays right after this call sees the decision already
+ * applied, same as before this gate existed. */
+export declare function settleCompositionReadiness(doc: Document, onSettled: (result: CompositionReadinessResult) => void, opts?: {
+    inputs?: CompositionReadinessInput[];
+    timeoutMs?: number;
+}): void;
+//# sourceMappingURL=compositionReadiness.d.ts.map

package/dist/compositionReadiness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compositionReadiness.d.ts","sourceRoot":"","sources":["../src/compositionReadiness.ts"],"names":[],"mappings":"AAAA;;4CAE4C;AAC5C,MAAM,MAAM,yBAAyB,GAAG,CAAC,GAAG,EAAE,QAAQ,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;AAEhF,MAAM,WAAW,wBAAwB;IACvC,YAAY,EAAE,gBAAgB,EAAE,CAAC;IACjC,aAAa,EAAE,gBAAgB,EAAE,CAAC;IAClC,YAAY,EAAE,OAAO,CAAC;CACvB;AAWD,wBAAgB,cAAc,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,IAAI,OAAO,CAI1D;AAED,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,IAAI,gBAAgB,CAM5E;AAED,iEAAiE;AACjE,wBAAgB,4BAA4B,CAAC,GAAG,EAAE,QAAQ,GAAG,wBAAwB,CAOpF;AAyBD;uCACuC;AACvC,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAMvE;AAID,MAAM,WAAW,0BAA0B;IACzC,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED;;;gDAGgD;AAChD,wBAAgB,0BAA0B,CACxC,GAAG,EAAE,QAAQ,EACb,SAAS,EAAE,CAAC,MAAM,EAAE,0BAA0B,KAAK,IAAI,EACvD,IAAI,GAAE;IAAE,MAAM,CAAC,EAAE,yBAAyB,EAAE,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAO,GACtE,IAAI,CAiBN"}

package/dist/compositionReadiness.js

@@ -0,0 +1,79 @@
+// HTMLMediaElement.HAVE_FUTURE_DATA per spec, used as a literal because not
+// every DOM implementation defines the named static (e.g. happy-dom leaves
+// it undefined).
+const HAVE_FUTURE_DATA = 3;
+// `doc` is a foreign (same-origin) iframe document, so its elements belong to
+// that iframe's own realm — instanceof checks against this window's globals
+// would silently reject every one of them. Resolve the class from the node's
+// own defaultView first.
+export function isRealmElement(node) {
+    const view = node.ownerDocument?.defaultView;
+    if (view && node instanceof view.Element)
+        return true;
+    return node instanceof Element;
+}
+export function isRealmHtmlMediaElement(node) {
+    if (!isRealmElement(node))
+        return false;
+    if (node.tagName !== "AUDIO" && node.tagName !== "VIDEO")
+        return false;
+    const view = node.ownerDocument?.defaultView;
+    if (view && node instanceof view.HTMLMediaElement)
+        return true;
+    return node instanceof HTMLMediaElement;
+}
+/** One DOM pass for every declared-media asset not yet ready. */
+export function scanPendingCompositionAssets(doc) {
+    const pendingMedia = Array.from(doc.querySelectorAll("video, audio"))
+        .filter(isRealmHtmlMediaElement)
+        .filter((el) => el.readyState < HAVE_FUTURE_DATA);
+    const pendingImages = Array.from(doc.querySelectorAll("img")).filter((img) => !img.complete);
+    const fontsLoading = doc.fonts?.status === "loading";
+    return { pendingMedia, pendingImages, fontsLoading };
+}
+function collectPendingCompositionAssets(doc, { pendingMedia, pendingImages, fontsLoading }) {
+    const mediaReady = pendingMedia.map((el) => new Promise((resolve) => {
+        const onSettled = () => {
+            el.removeEventListener("canplay", onSettled);
+            el.removeEventListener("error", onSettled);
+            resolve();
+        };
+        el.addEventListener("canplay", onSettled);
+        el.addEventListener("error", onSettled);
+    }));
+    const imagesReady = pendingImages.map((img) => img.decode ? img.decode().catch(() => { }) : Promise.resolve());
+    const fontsReady = fontsLoading && doc.fonts ? doc.fonts.ready.then(() => { }) : Promise.resolve();
+    return Promise.all([...mediaReady, ...imagesReady, fontsReady]).then(() => { });
+}
+/** Declared-media readiness input: waits on the composition's own video,
+ * audio, image and font-face loads. */
+export function mediaReadinessInput(doc) {
+    const scan = scanPendingCompositionAssets(doc);
+    if (scan.pendingMedia.length === 0 && scan.pendingImages.length === 0 && !scan.fontsLoading) {
+        return null;
+    }
+    return collectPendingCompositionAssets(doc, scan);
+}
+const DEFAULT_TIMEOUT_MS = 8_000;
+/** Invokes `onSettled` once every input settles, or the timeout elapses.
+ * Calls back synchronously, before returning, when nothing is pending — a
+ * caller that plays right after this call sees the decision already
+ * applied, same as before this gate existed. */
+export function settleCompositionReadiness(doc, onSettled, opts = {}) {
+    const inputs = opts.inputs ?? [mediaReadinessInput];
+    const pending = inputs.map((input) => input(doc)).filter((p) => p !== null);
+    if (pending.length === 0) {
+        onSettled({ timedOut: false });
+        return;
+    }
+    const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    let timeoutId;
+    const timeout = new Promise((resolve) => {
+        timeoutId = setTimeout(() => resolve("timed-out"), timeoutMs);
+    });
+    Promise.race([Promise.all(pending).then(() => "done"), timeout]).then((result) => {
+        clearTimeout(timeoutId);
+        onSettled({ timedOut: result === "timed-out" });
+    });
+}
+//# sourceMappingURL=compositionReadiness.js.map

package/dist/compositionReadiness.js.map

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