@hyperframes/core 0.8.15 → 0.8.17

package/dist/runtime/webAudioRoute.js

@@ -0,0 +1,221 @@
+import { HF_AUDIO_AUTOMATION_ATTR } from "../audioAutomation.js";
+import { HF_AUDIO_FX_ATTR } from "../audioFx.js";
+import { HF_AUDIO_GROUP_ATTR } from "../audioGroups.js";
+import { postRuntimeMessage } from "./bridge.js";
+/** Fired when the runtime withholds Web Audio capture from a media element. */
+const DIAGNOSTIC_BYPASS_CODE = "runtime_web_audio_bypass";
+function getAttr(el, name) {
+    return typeof el.getAttribute === "function" ? el.getAttribute(name) : null;
+}
+function hasAttr(el, name) {
+    return getAttr(el, name) !== null;
+}
+/**
+ * `crossorigin` is an enumerated attribute whose invalid-value default is
+ * `anonymous`, so PRESENCE is the opt-in — `crossorigin=""` and even
+ * `crossorigin="garbage"` both make the fetch a CORS request. Comparing the
+ * value against `"anonymous"` would wrongly block those.
+ *
+ * Two independent reads, because a spec-faithful host and a permissive one
+ * disagree about where the truth lives:
+ *  - `getAttribute` is the primary read and covers every real browser: the
+ *    markup is unambiguous regardless of what the IDL getter does with it.
+ *  - `el.crossOrigin` is a secondary read for a host that sets the IDL
+ *    property without reflecting it back to the attribute — some
+ *    jsdom-style test/preview hosts do this. The check is `!= null`
+ *    (covers both `null` and `undefined`), not a truthiness check, ON
+ *    PURPOSE: `crossorigin=""` is a valid, common opt-in (see above), and
+ *    its IDL fallback value is the empty string — a falsy value that
+ *    `Boolean(el.crossOrigin)` would silently misread as "not opted in",
+ *    reintroducing the exact silent-audio bug this module exists to close.
+ */
+function hasCorsOptIn(el) {
+    if (hasAttr(el, "crossorigin"))
+        return true;
+    return el.crossOrigin != null;
+}
+function baseUri(el) {
+    if (typeof el.baseURI === "string" && el.baseURI)
+        return el.baseURI;
+    return typeof document !== "undefined" ? document.baseURI : "";
+}
+/**
+ * The URLs whose origin could decide this element's route.
+ *
+ * Order matters and mirrors the HTML resource selection algorithm. Once
+ * `currentSrc` is set the browser has COMMITTED to that resource, so it is the
+ * only candidate that can matter; a `<source>` sibling it passed over must not
+ * cost a same-origin element its Web Audio graph. A `src` attribute is equally
+ * definitive — the spec has it win outright over `<source>` children. Only
+ * before selection settles (no `currentSrc`, no `src`) do the `<source>`
+ * candidates matter, and there the conservative read is right: any of them
+ * could be the one that gets picked.
+ */
+function routeCandidates(el) {
+    const current = typeof el.currentSrc === "string" ? el.currentSrc : "";
+    if (current)
+        return [current];
+    const srcAttr = getAttr(el, "src");
+    if (srcAttr)
+        return [srcAttr];
+    if (typeof el.querySelectorAll !== "function")
+        return [];
+    const sources = [];
+    for (const source of Array.from(el.querySelectorAll("source"))) {
+        const value = source.getAttribute("src");
+        if (value)
+            sources.push(value);
+    }
+    return sources;
+}
+/**
+ * Whether this URL would make MediaElementSource silent. Only http(s) is
+ * judged: `blob:` and `data:` are same-origin by construction, and a `file:`
+ * page's opaque origin can't be compared meaningfully — so those keep the
+ * pre-existing behaviour rather than losing Web Audio on a guess. The guard
+ * changes behaviour ONLY in the case that is already known-broken.
+ */
+function isCorsSilenced(rawUrl, el) {
+    if (typeof window === "undefined")
+        return false;
+    let url;
+    try {
+        url = new URL(rawUrl, baseUri(el));
+    }
+    catch {
+        return false;
+    }
+    if (url.protocol !== "http:" && url.protocol !== "https:")
+        return false;
+    if (url.origin === window.location.origin)
+        return false;
+    return !hasCorsOptIn(el);
+}
+/**
+ * Whether resource selection has settled enough for a verdict to be a FACT
+ * rather than a guess. `currentSrc`/`src` are both definitive per the HTML
+ * resource-selection algorithm (see `routeCandidates` above); before either
+ * is set, a verdict can only be built from `<source>` children, any of which
+ * the browser may still pass over before committing.
+ *
+ * `classifyWebAudioMediaRoute` itself stays unsettled-tolerant on purpose —
+ * the schedule path needs *a* verdict even before selection settles, and
+ * conservatively withholding the node there costs nothing but a decode-only
+ * fallback. This predicate exists for the one caller that must NOT act on a
+ * guess: the discovery-time diagnostic, which drops a message in a human's
+ * lap and only gets to say it once (see `reportWebAudioMediaRoute`'s latch).
+ */
+export function isRouteSelectionSettled(el) {
+    const current = typeof el.currentSrc === "string" ? el.currentSrc : "";
+    if (current)
+        return true;
+    return hasAttr(el, "src");
+}
+/**
+ * Pure — no node creation, no diagnostics, no element mutation. Called from
+ * both the schedule path (where it withholds the node) and the discovery path
+ * (where it only reports), which is the point: `hyperframes check` never calls
+ * `play()`, so a verdict reachable only from the transport would be invisible
+ * to the very gate meant to surface it.
+ */
+export function classifyWebAudioMediaRoute(el) {
+    for (const candidate of routeCandidates(el)) {
+        if (isCorsSilenced(candidate, el)) {
+            return { kind: "decode-only", reason: "cross_origin_no_cors", asset: candidate };
+        }
+    }
+    return { kind: "web-audio" };
+}
+/**
+ * Processing the native HTMLMediaElement fallback cannot reproduce. The track
+ * stays AUDIBLE either way — silence is the bug being fixed, so failing closed
+ * would just reinstate it — but these authored intentions are quietly dropped,
+ * which is worth saying out loud.
+ *
+ * Wider than the FX/automation pair the schedule path already tests: group
+ * membership carries a whole shared bus (chain, fader, its own automation
+ * clock), and an above-unity `data-volume` cannot survive a route whose only
+ * gain stage is `el.volume`, which the spec pins to [0,1].
+ */
+export function nativeUnexpressibleProcessing(el) {
+    const lost = [];
+    if (hasAttr(el, HF_AUDIO_FX_ATTR))
+        lost.push("fx-chain");
+    if (hasAttr(el, HF_AUDIO_AUTOMATION_ATTR))
+        lost.push("automation");
+    if (hasAttr(el, HF_AUDIO_GROUP_ATTR))
+        lost.push("audio-group");
+    const volume = Number.parseFloat(getAttr(el, "data-volume") ?? "");
+    if (Number.isFinite(volume) && volume > 1)
+        lost.push("above-unity-gain");
+    return lost;
+}
+/**
+ * Render never plays through Web Audio at all: the producer mixes offline from
+ * the source files, and that mix applies the FX chain itself (see
+ * `applyAudioFxChain` in `packages/engine/src/services/audioMixer.ts`). So a
+ * bypass is not a fact about the render, and `lostProcessing` would be an
+ * outright false claim there — the offline mix DOES reproduce the chain the
+ * line says native output cannot. The engine forwards every console line to
+ * producer stdout, so an ungated report would also land in every render log.
+ *
+ * Reporting is all that is gated: `classifyWebAudioMediaRoute` stays pure and
+ * the routing decision is unchanged, which costs nothing in render because the
+ * element is not the audio source there in the first place.
+ *
+ * Same signal `mediaProxy.ts`'s `isRenderMode` gates on. The `<video>` half of
+ * that check (the injected render-frame sibling) is deliberately not mirrored:
+ * only `<audio>` ever reaches this module.
+ */
+function isRenderMode() {
+    // Read through an inline cast rather than the ambient `Window` augmentation
+    // in `window.d.ts`: that augmentation is only in scope for programs that
+    // include it (core's own tsconfig does), and this module is also exported
+    // as `./runtime/web-audio-route` for non-runtime consumers (e.g. the studio
+    // asset sidebar's preview player, `AudioRow.tsx`) whose tsconfig doesn't
+    // pull it in. This is a plain existence check, so the cast costs nothing.
+    return (typeof window !== "undefined" &&
+        !!window
+            .__HF_EXPORT_RENDER_SEEK_CONFIG);
+}
+// One diagnostic per element. Latched only when something is actually emitted,
+// so an early "web-audio" verdict taken before the resource selection settled
+// can't suppress the real one at `loadedmetadata`.
+const diagnosedElements = new WeakSet();
+/**
+ * Emit the one-time diagnostic for a non-Web-Audio verdict.
+ *
+ * The bypass always reports: it is an accident by definition, and the whole
+ * complaint in #3458 is that nothing was said.
+ */
+export function reportWebAudioMediaRoute(el, route) {
+    if (route.kind === "web-audio")
+        return;
+    if (isRenderMode())
+        return;
+    if (diagnosedElements.has(el))
+        return;
+    const lost = nativeUnexpressibleProcessing(el);
+    diagnosedElements.add(el);
+    const details = {
+        asset: route.asset,
+        reason: route.reason,
+        lostProcessing: lost,
+        note: "cross-origin media without a `crossorigin` opt-in is silent through createMediaElementSource (Web Audio spec); using native playback instead",
+    };
+    postRuntimeMessage({
+        source: "hf-preview",
+        type: "diagnostic",
+        code: DIAGNOSTIC_BYPASS_CODE,
+        details,
+    });
+    // The stable code lives in the console text so the CLI's scraper
+    // (packages/cli/src/utils/checkBrowser.ts) can match a token, not prose —
+    // same contract mediaProxy.ts's diagnostics use.
+    const lostNote = lost.length > 0
+        ? ` Native playback cannot reproduce: ${lost.join(", ")} — proxy or download the asset to a same-origin URL to keep it.`
+        : "";
+    console.info(`[hyperframes] ${DIAGNOSTIC_BYPASS_CODE}: "${route.asset}" (${route.reason}): ` +
+        `Web Audio capture withheld; the track plays through native HTMLMediaElement output.${lostNote}`);
+}
+//# sourceMappingURL=webAudioRoute.js.map

package/dist/runtime/webAudioRoute.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/core",
-  "version": "0.8.15",
+  "version": "0.8.17",
   "description": "",
   "repository": {
     "type": "git",
@@ -171,6 +171,10 @@
       "import": "./dist/runtime/stackingContext.js",
       "types": "./dist/runtime/stackingContext.d.ts"
     },
+    "./runtime/web-audio-route": {
+      "import": "./dist/runtime/webAudioRoute.js",
+      "types": "./dist/runtime/webAudioRoute.d.ts"
+    },
     "./compiler/html-document": {
       "import": "./dist/compiler/htmlDocument.js",
       "types": "./dist/compiler/htmlDocument.d.ts"
@@ -274,9 +278,9 @@
     "bpm-detective": "^2.0.5",
     "linkedom": "^0.18.12",
     "postcss": "^8.5.8",
-    "@hyperframes/parsers": "0.8.15",
-    "@hyperframes/studio-server": "0.8.15",
-    "@hyperframes/lint": "0.8.15"
+    "@hyperframes/parsers": "0.8.17",
+    "@hyperframes/lint": "0.8.17",
+    "@hyperframes/studio-server": "0.8.17"
   },
   "devDependencies": {
     "@types/jsdom": "^28.0.0",