Skip to content

Write HTML. Render video. Built for agents.

14.9 KB
Raw Blame
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
import {
  classifyWebAudioMediaRoute,
  isRouteSelectionSettled,
  nativeUnexpressibleProcessing,
  reportWebAudioMediaRoute,
} from "./webAudioRoute";

const SAME_ORIGIN = window.location.origin;
const CROSS_ORIGIN = "https://cdn.example.com";

function audio(attrs: Record<string, string> = {}): HTMLAudioElement {
  const el = document.createElement("audio");
  for (const [name, value] of Object.entries(attrs)) el.setAttribute(name, value);
  return el;
}

/** jsdom never runs the resource selection algorithm, so `currentSrc` has to be
 *  planted to exercise the branch where the browser has already committed. */
function withCurrentSrc(el: HTMLAudioElement, currentSrc: string): HTMLAudioElement {
  Object.defineProperty(el, "currentSrc", { value: currentSrc, configurable: true });
  return el;
}

/**
 * Shadows the IDL `crossOrigin` accessor with a plain data property, so the
 * value is visible ONLY via the property — unlike `el.crossOrigin = value`
 * (which jsdom, like real browsers, reflects straight back to the
 * `crossorigin` attribute), this simulates a host whose IDL property is
 * genuinely decoupled from the attribute, per `hasCorsOptIn`'s secondary read.
 */
function withUnreflectedCrossOrigin(el: HTMLAudioElement, value: string): HTMLAudioElement {
  Object.defineProperty(el, "crossOrigin", { value, configurable: true });
  return el;
}

/** Stubs the document's actual security origin (`window.origin`) for the
 *  duration of `run`, then restores it — distinct from `location.origin`,
 *  which stays URL-shaped even inside an opaque sandboxed document. */
function withSelfOrigin<T>(origin: string, run: () => T): T {
  const original = Object.getOwnPropertyDescriptor(window, "origin");
  Object.defineProperty(window, "origin", { value: origin, configurable: true });
  try {
    return run();
  } finally {
    if (original) Object.defineProperty(window, "origin", original);
    else delete (window as { origin?: string }).origin;
  }
}

/** The one console line `reportWebAudioMediaRoute` emits for `el`, or "". */
function bypassLine(el: HTMLAudioElement): string {
  const info = vi.spyOn(console, "info").mockImplementation(() => {});
  reportWebAudioMediaRoute(el, classifyWebAudioMediaRoute(el));
  return (info.mock.calls[0]?.[0] as string) ?? "";
}

describe("classifyWebAudioMediaRoute", () => {
  it("routes same-origin media through Web Audio", () => {
    expect(classifyWebAudioMediaRoute(audio({ src: "/assets/vo.mp3" }))).toEqual({
      kind: "web-audio",
    });
    expect(classifyWebAudioMediaRoute(audio({ src: `${SAME_ORIGIN}/assets/vo.mp3` }))).toEqual({
      kind: "web-audio",
    });
  });

  it("withholds capture from cross-origin media with no CORS opt-in", () => {
    // The bug: createMediaElementSource here builds a node that outputs silence
    // per spec, without throwing, and permanently steals the element's native
    // output on the way.
    const route = classifyWebAudioMediaRoute(audio({ src: `${CROSS_ORIGIN}/track.mp3` }));

    expect(route).toEqual({
      kind: "decode-only",
      reason: "cross_origin_no_cors",
      asset: `${CROSS_ORIGIN}/track.mp3`,
    });
  });

  it("treats any crossorigin attribute as the opt-in, whatever its value", () => {
    // Enumerated attribute: the invalid-value default is `anonymous`, so every
    // one of these makes the fetch a CORS request. Matching on "anonymous"
    // would strip Web Audio from two of the three.
    for (const value of ["anonymous", "use-credentials", "", "garbage"]) {
      const el = audio({ src: `${CROSS_ORIGIN}/track.mp3`, crossorigin: value });
      expect(classifyWebAudioMediaRoute(el)).toEqual({ kind: "web-audio" });
    }
  });

  it("keeps non-http(s) schemes on the pre-existing path", () => {
    // blob:/data: are same-origin by construction and file: has an opaque
    // origin no comparison can settle — guessing there would cost Web Audio on
    // compositions that never had this problem.
    for (const src of ["blob:https://cdn.example.com/abc", "data:audio/mp3;base64,AAAA"]) {
      expect(classifyWebAudioMediaRoute(audio({ src }))).toEqual({ kind: "web-audio" });
    }
  });

  it("judges only currentSrc once the browser has committed to a resource", () => {
    // The element ended up on a same-origin file. A cross-origin <source> the
    // browser passed over must not cost it its graph.
    const el = audio();
    el.innerHTML =
      `<source src="${CROSS_ORIGIN}/track.mp3">` + `<source src="/assets/fallback.mp3">`;
    withCurrentSrc(el, `${SAME_ORIGIN}/assets/fallback.mp3`);

    expect(classifyWebAudioMediaRoute(el)).toEqual({ kind: "web-audio" });
  });

  it("prefers a src attribute over <source> children, as the spec does", () => {
    const el = audio({ src: "/assets/vo.mp3" });
    el.innerHTML = `<source src="${CROSS_ORIGIN}/track.mp3">`;

    expect(classifyWebAudioMediaRoute(el)).toEqual({ kind: "web-audio" });
  });

  it("checks every <source> candidate while selection is still unsettled", () => {
    // No currentSrc and no src attribute: any candidate could still win, so the
    // conservative read is the only safe one — the node is unbuildable-back.
    const el = audio();
    el.innerHTML = `<source src="/assets/first.mp3">` + `<source src="${CROSS_ORIGIN}/second.mp3">`;

    expect(classifyWebAudioMediaRoute(el)).toEqual({
      kind: "decode-only",
      reason: "cross_origin_no_cors",
      asset: `${CROSS_ORIGIN}/second.mp3`,
    });
  });

  it("routes an element with no resolvable source through Web Audio", () => {
    expect(classifyWebAudioMediaRoute(audio())).toEqual({ kind: "web-audio" });
  });

  it("treats an unreflected empty-string crossOrigin IDL property as opt-in", () => {
    // The IDL fallback for `crossorigin=""` / bare `crossorigin` is the empty
    // string. A host whose property setter doesn't reflect to the attribute
    // (unlike jsdom's own accessor, which does) must not have that empty
    // string misread as "no opt-in" — `Boolean("")` is false, which is
    // exactly the fail-open this test guards against.
    const el = withUnreflectedCrossOrigin(audio({ src: `${CROSS_ORIGIN}/track.mp3` }), "");
    expect(el.getAttribute("crossorigin")).toBeNull(); // confirms it's genuinely unreflected

    expect(classifyWebAudioMediaRoute(el)).toEqual({ kind: "web-audio" });
  });

  it("does not treat an untouched crossOrigin IDL property as opt-in", () => {
    // The other direction of the same risk: a host must not default
    // `crossOrigin` to a truthy/string value for elements that never opted
    // in, or the cross-origin check would be permanently disabled.
    const el = audio({ src: `${CROSS_ORIGIN}/track.mp3` });
    expect(el.crossOrigin).toBeNull();

    expect(classifyWebAudioMediaRoute(el)).toEqual({
      kind: "decode-only",
      reason: "cross_origin_no_cors",
      asset: `${CROSS_ORIGIN}/track.mp3`,
    });
  });

  it("withholds capture when the document's security origin is opaque, even though the URL origins match", () => {
    // See withSelfOrigin above for why this differs from location.origin.
    const asset = `${SAME_ORIGIN}/assets/vo.mp3`;
    const route = withSelfOrigin("null", () => classifyWebAudioMediaRoute(audio({ src: asset })));

    expect(route).toEqual({ kind: "decode-only", reason: "opaque_document_origin", asset });
  });

  it("reports opacity, not foreignness, when the document is opaque AND the asset is remote", () => {
    // Both conditions hold. Opacity is the blocking one and the only one the
    // author cannot fix by moving the asset, so it must win the reason.
    const asset = `${CROSS_ORIGIN}/track.mp3`;
    const route = withSelfOrigin("null", () => classifyWebAudioMediaRoute(audio({ src: asset })));

    expect(route).toEqual({ kind: "decode-only", reason: "opaque_document_origin", asset });
  });

  it("still lets a crossorigin opt-in rescue an opaque document", () => {
    const el = audio({ src: `${CROSS_ORIGIN}/track.mp3`, crossorigin: "anonymous" });
    const route = withSelfOrigin("null", () => classifyWebAudioMediaRoute(el));

    expect(route).toEqual({ kind: "web-audio" });
  });

  it("keeps today's same-origin result when window.origin genuinely matches", () => {
    const asset = `${SAME_ORIGIN}/assets/vo.mp3`;
    const route = withSelfOrigin(SAME_ORIGIN, () =>
      classifyWebAudioMediaRoute(audio({ src: asset })),
    );

    expect(route).toEqual({ kind: "web-audio" });
  });
});

describe("isRouteSelectionSettled", () => {
  it("is unsettled for an element with only <source> children", () => {
    const el = audio();
    el.innerHTML = `<source src="/assets/first.mp3">`;
    expect(isRouteSelectionSettled(el)).toBe(false);
  });

  it("is settled once a src attribute is definitive, even before load", () => {
    expect(isRouteSelectionSettled(audio({ src: "/assets/vo.mp3" }))).toBe(true);
  });

  it("is settled once currentSrc has committed", () => {
    const el = withCurrentSrc(audio(), `${SAME_ORIGIN}/assets/vo.mp3`);
    expect(isRouteSelectionSettled(el)).toBe(true);
  });

  it("is unsettled for an element with no source at all", () => {
    expect(isRouteSelectionSettled(audio())).toBe(false);
  });
});

describe("nativeUnexpressibleProcessing", () => {
  it("reports nothing for a bare track", () => {
    expect(nativeUnexpressibleProcessing(audio({ src: "/a.mp3", "data-volume": "0.5" }))).toEqual(
      [],
    );
  });

  it("names every authored intention native output cannot carry", () => {
    const el = audio({
      "data-fx-chain": "[]",
      "data-automation": "{}",
      "data-audio-group": "vo",
      // `el.volume` is spec-pinned to [0,1], so a boost cannot survive a route
      // whose only gain stage is the element itself.
      "data-volume": "2",
    });

    expect(nativeUnexpressibleProcessing(el)).toEqual([
      "fx-chain",
      "automation",
      "audio-group",
      "above-unity-gain",
    ]);
  });
});

describe("reportWebAudioMediaRoute", () => {
  beforeEach(() => {
    vi.restoreAllMocks();
  });

  it("emits a scrapable console line and a bridge diagnostic for a CORS bypass", () => {
    const info = vi.spyOn(console, "info").mockImplementation(() => {});
    const post = vi.spyOn(window.parent, "postMessage").mockImplementation(() => {});
    const el = audio({ src: `${CROSS_ORIGIN}/track.mp3` });

    reportWebAudioMediaRoute(el, classifyWebAudioMediaRoute(el));

    // The CLI's check gate matches this token, not the prose around it.
    expect(info.mock.calls[0]?.[0]).toContain("[hyperframes] runtime_web_audio_bypass");
    expect(post).toHaveBeenCalledWith(
      expect.objectContaining({ type: "diagnostic", code: "runtime_web_audio_bypass" }),
      "*",
    );
  });

  it("latches to one diagnostic per element", () => {
    const info = vi.spyOn(console, "info").mockImplementation(() => {});
    const el = audio({ src: `${CROSS_ORIGIN}/track.mp3` });
    const route = classifyWebAudioMediaRoute(el);

    reportWebAudioMediaRoute(el, route);
    reportWebAudioMediaRoute(el, route);

    expect(info).toHaveBeenCalledTimes(1);
  });

  it("says nothing for an eligible element", () => {
    const info = vi.spyOn(console, "info").mockImplementation(() => {});
    const el = audio({ src: "/assets/vo.mp3" });

    reportWebAudioMediaRoute(el, classifyWebAudioMediaRoute(el));

    expect(info).not.toHaveBeenCalled();
  });

  it("names the dropped processing, and offers a proxy, when a same-origin URL could exist", () => {
    const line = bypassLine(audio({ src: `${CROSS_ORIGIN}/track.mp3`, "data-audio-group": "vo" }));

    expect(line).toContain("audio-group");
    expect(line).toContain("proxy or download the asset to a same-origin URL");
  });

  it("tells an opaque document to fix the sandbox, not to move the asset", () => {
    // The whole point of the second reason. Nothing is same-origin with an
    // opaque origin, so the proxy advice names a fix that cannot exist here.
    const el = audio({ src: `${SAME_ORIGIN}/assets/vo.mp3`, "data-audio-group": "vo" });

    const line = withSelfOrigin("null", () => bypassLine(el));

    expect(line).toContain("audio-group");
    expect(line).toContain("allow-same-origin");
    expect(line).toContain("Access-Control-Allow-Origin");
    expect(line).not.toContain("proxy or download");
  });

  it("puts the opaque reason and its note on the bridge message, not just the console", () => {
    const posted: unknown[] = [];
    const post = vi
      .spyOn(window.parent, "postMessage")
      .mockImplementation((message: unknown) => void posted.push(message));
    vi.spyOn(console, "info").mockImplementation(() => {});
    const el = audio({ src: `${SAME_ORIGIN}/assets/vo.mp3` });

    withSelfOrigin("null", () => reportWebAudioMediaRoute(el, classifyWebAudioMediaRoute(el)));

    const details = (posted[0] as { details?: Record<string, unknown> })?.details ?? {};
    expect(details.reason).toBe("opaque_document_origin");
    expect(String(details.note)).toContain("opaque");
    post.mockRestore();
  });

  describe("render mode", () => {
    afterEach(() => {
      delete window.__HF_EXPORT_RENDER_SEEK_CONFIG;
    });

    it("says nothing during a render pass", () => {
      // Render never plays through Web Audio: the producer mixes offline from
      // the source files and applies the FX chain there, so "native playback
      // cannot reproduce: fx-chain" would be an outright false claim — and the
      // engine forwards every console line into producer stdout, so an ungated
      // report lands in every render log.
      window.__HF_EXPORT_RENDER_SEEK_CONFIG = { mode: "frames" };
      const info = vi.spyOn(console, "info").mockImplementation(() => {});
      const post = vi.spyOn(window.parent, "postMessage").mockImplementation(() => {});
      const el = audio({ src: `${CROSS_ORIGIN}/track.mp3`, "data-fx-chain": "[]" });

      reportWebAudioMediaRoute(el, classifyWebAudioMediaRoute(el));

      expect(info).not.toHaveBeenCalled();
      expect(post).not.toHaveBeenCalled();
    });

    it("still reports once the same element is seen outside a render pass", () => {
      // The render-mode skip must not consume the element's one-shot latch.
      window.__HF_EXPORT_RENDER_SEEK_CONFIG = { mode: "frames" };
      const info = vi.spyOn(console, "info").mockImplementation(() => {});
      const el = audio({ src: `${CROSS_ORIGIN}/track.mp3` });
      reportWebAudioMediaRoute(el, classifyWebAudioMediaRoute(el));
      expect(info).not.toHaveBeenCalled();

      delete window.__HF_EXPORT_RENDER_SEEK_CONFIG;
      reportWebAudioMediaRoute(el, classifyWebAudioMediaRoute(el));

      expect(info).toHaveBeenCalledTimes(1);
    });

    it("leaves the verdict itself untouched — only the report is gated", () => {
      window.__HF_EXPORT_RENDER_SEEK_CONFIG = { mode: "frames" };

      expect(classifyWebAudioMediaRoute(audio({ src: `${CROSS_ORIGIN}/track.mp3` }))).toEqual({
        kind: "decode-only",
        reason: "cross_origin_no_cors",
        asset: `${CROSS_ORIGIN}/track.mp3`,
      });
    });
  });
});