Skip to content

Write HTML. Render video. Built for agents.

14.0 KB
Raw Blame
// @vitest-environment jsdom
import { afterEach, describe, expect, it, vi } from "vitest";
import { applyCaptionOverrides } from "./captionOverrides";

function installCaptionOverrideFetch(overrides: unknown) {
  vi.stubGlobal("fetch", async () => ({
    ok: true,
    async json() {
      return overrides;
    },
  }));
}

function installGsapMock() {
  const setCalls: Array<{ target: Element; vars: Record<string, unknown> }> = [];
  const gsap = {
    set(target: Element, vars: Record<string, unknown>) {
      setCalls.push({ target, vars });
      for (const [key, value] of Object.entries(vars)) {
        if (key === "fontSize" && typeof value === "string" && target instanceof HTMLElement) {
          target.style.fontSize = value;
        }
      }
    },
    killTweensOf() {},
    getTweensOf() {
      return [];
    },
  };
  Object.defineProperty(window, "gsap", {
    configurable: true,
    value: gsap,
  });
  return { setCalls };
}

/** A gsap mock whose `getTweensOf` returns the supplied colour tweens, so classification is testable. */
function installGsapMockWithTweens(tweens: Array<Record<string, unknown>>) {
  const gsap = {
    set(target: HTMLElement, vars: Record<string, unknown>) {
      if (typeof vars.color === "string") target.style.color = vars.color;
    },
    killTweensOf() {},
    getTweensOf() {
      return tweens.map((vars, i) => ({ vars, startTime: () => i }));
    },
  };
  Object.defineProperty(window, "gsap", { configurable: true, value: gsap });
  return tweens;
}

async function flushCaptionOverrides() {
  for (let i = 0; i < 4; i++) {
    await Promise.resolve();
  }
}

afterEach(() => {
  vi.clearAllMocks();
  vi.restoreAllMocks();
  vi.unstubAllGlobals();
  document.head.innerHTML = "";
  document.body.innerHTML = "";
  Reflect.deleteProperty(window, "gsap");
});

describe("applyCaptionOverrides", () => {
  it("treats a missing optional sidecar as a silent no-op", async () => {
    installGsapMock();
    const json = vi.fn();
    vi.stubGlobal("fetch", async () => ({ ok: false, status: 404, json }));
    const error = vi.spyOn(console, "error").mockImplementation(() => {});
    document.body.innerHTML = `<div class="caption-group"><span>Hi</span></div>`;

    applyCaptionOverrides();
    await flushCaptionOverrides();

    expect(json).not.toHaveBeenCalled();
    expect(error).not.toHaveBeenCalled();
  });

  it.each([
    ["malformed JSON", () => Promise.reject(new SyntaxError("Unexpected token"))],
    ["a non-array root", () => Promise.resolve({ wordIndex: 0 })],
    ["a non-object entry", () => Promise.resolve([null])],
  ])("reports a present sidecar containing %s", async (_shape, json) => {
    installGsapMock();
    vi.stubGlobal("fetch", async () => ({ ok: true, status: 200, json }));
    const error = vi.spyOn(console, "error").mockImplementation(() => {});
    document.body.innerHTML = `<div class="caption-group"><span>Hi</span></div>`;

    applyCaptionOverrides();
    await flushCaptionOverrides();

    expect(error).toHaveBeenCalledOnce();
    expect(error.mock.calls[0]?.[0]).toContain("caption-overrides.json");
  });

  it("accepts an empty array as the explicit no-op payload", async () => {
    installGsapMock();
    installCaptionOverrideFetch([]);
    const error = vi.spyOn(console, "error").mockImplementation(() => {});
    document.body.innerHTML = `<div class="caption-group"><span>Hi</span></div>`;

    applyCaptionOverrides();
    await flushCaptionOverrides();

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

  it("reuses existing caption wrappers when overrides are applied more than once", async () => {
    const { setCalls } = installGsapMock();
    installCaptionOverrideFetch([{ wordIndex: 0, x: 12, y: -4, scale: 1.2 }]);
    document.body.innerHTML = `
      <div class="caption-group">
        <span id="w0">Hello</span>
      </div>
    `;

    applyCaptionOverrides();
    await flushCaptionOverrides();
    applyCaptionOverrides();
    await flushCaptionOverrides();

    const group = document.querySelector(".caption-group");
    const word = document.getElementById("w0");
    const wrappers = group?.querySelectorAll('[data-caption-wrapper="true"]');
    const wrapper = wrappers?.item(0);
    if (!group || !word || !wrapper) throw new Error("Expected wrapped caption word");

    expect(wrappers).toHaveLength(1);
    expect(wrapper.parentElement).toBe(group);
    expect(word.parentElement).toBe(wrapper);
    expect(setCalls.map((call) => call.target)).toEqual([wrapper, wrapper]);
  });

  it("treats a pre-wrapped word as the wordIndex target, not as another word", async () => {
    installGsapMock();
    installCaptionOverrideFetch([{ wordIndex: 0, fontSize: 72 }]);
    document.body.innerHTML = `
      <div class="caption-group">
        <span data-caption-wrapper="true">
          <span id="w0">Hello</span>
        </span>
      </div>
    `;

    applyCaptionOverrides();
    await flushCaptionOverrides();

    const word = document.getElementById("w0");
    const wrapper = word?.parentElement;
    if (!(word instanceof HTMLElement) || !wrapper) {
      throw new Error("Expected pre-wrapped caption word");
    }

    expect(word.style.fontSize).toBe("72px");
    expect(wrapper.getAttribute("style") ?? "").not.toContain("font-size");
  });

  it("resolves wordId overrides against the inner word of an existing wrapper", async () => {
    const { setCalls } = installGsapMock();
    installCaptionOverrideFetch([{ wordId: "w0", x: 16 }]);
    document.body.innerHTML = `
      <div class="caption-group">
        <span data-caption-wrapper="true">
          <span id="w0">Hello</span>
        </span>
      </div>
    `;

    applyCaptionOverrides();
    await flushCaptionOverrides();

    const word = document.getElementById("w0");
    const wrapper = word?.parentElement;
    if (!(word instanceof HTMLElement) || !wrapper) {
      throw new Error("Expected pre-wrapped caption word");
    }

    expect(setCalls).toHaveLength(1);
    expect(setCalls[0]?.target).toBe(wrapper);
    expect(setCalls[0]?.vars).toEqual({ x: 16 });
  });
});

/** Mounts one caption word whose stylesheet (rest) colour is `rest`. */
function mountWord(rest: string) {
  document.head.innerHTML = `<style>#w0 { color: ${rest}; }</style>`;
  document.body.innerHTML = `<div class="caption-group"><span id="w0">Hi</span></div>`;
}

const SHIPPED_REST = "rgba(255, 255, 255, 0.55)";

describe("caption colour classification", () => {
  it.each([
    [{ dimColor: "#888", activeColor: "#fff" }, "#fff"],
    [{ dimColor: "#888" }, "#ffffff"],
  ])("lights up a word whose only tween leaves its rest colour, with %o", async (override, lit) => {
    // The shape the shipped caption scripts emit: dim by CSS, one tween to white when spoken.
    const tweens = installGsapMockWithTweens([{ color: "#ffffff" }]);
    installCaptionOverrideFetch([{ wordIndex: 0, ...override }]);
    mountWord(SHIPPED_REST);

    applyCaptionOverrides();
    await flushCaptionOverrides();

    expect(tweens[0].color).toBe(lit);
  });

  it("classifies a return to the rest colour as dim, however the colour is spelled", async () => {
    const tweens = installGsapMockWithTweens([
      { color: "white" },
      { color: "rgba(255,255,255,.55)" },
    ]);
    installCaptionOverrideFetch([{ wordIndex: 0, dimColor: "#888", activeColor: "#0f0" }]);
    mountWord(SHIPPED_REST);

    applyCaptionOverrides();
    await flushCaptionOverrides();

    expect(tweens.map((tw) => tw.color)).toEqual(["#0f0", "#888"]);
  });

  it("lights up a fromTo() from a dim colour into the word's own stylesheet colour", async () => {
    const tweens = installGsapMockWithTweens([{ color: "#fff", startAt: { color: "#444" } }]);
    installCaptionOverrideFetch([{ wordIndex: 0, dimColor: "#888", activeColor: "#0f0" }]);
    mountWord("#fff");

    applyCaptionOverrides();
    await flushCaptionOverrides();

    expect(tweens[0].color).toBe("#0f0");
  });

  it("repaints a word the playhead already lit with its rest colour, so it is dim before it is spoken", async () => {
    // Overrides can land after the word lit up; its invalidated tween re-reads its start from this.
    const tweens = installGsapMockWithTweens([{ color: "#ffffff" }]);
    installCaptionOverrideFetch([{ wordIndex: 0, activeColor: "#0f0" }]);
    mountWord(SHIPPED_REST);
    document.getElementById("w0")!.style.color = "#ffffff";

    applyCaptionOverrides();
    await flushCaptionOverrides();

    expect(tweens[0].color).toBe("#0f0");
    expect(document.getElementById("w0")!.style.color).toBe(SHIPPED_REST);
  });

  it("leaves the colour a from() tween has rendered on its word", async () => {
    // The from() is mid-way (#a2a2a2) when the overrides land; its recorded start stays #444.
    installGsapMockWithTweens([{ color: "#444", runBackwards: true }]);
    installCaptionOverrideFetch([{ wordIndex: 0, activeColor: "#0f0" }]);
    mountWord("#fff");
    document.getElementById("w0")!.style.color = "#a2a2a2";

    applyCaptionOverrides();
    await flushCaptionOverrides();

    expect(document.getElementById("w0")!.style.color).toBe("rgb(162, 162, 162)");
  });

  it("resolves each distinct tween colour once per apply, not once per word", async () => {
    installGsapMockWithTweens([{ color: "#ffffff" }, { color: SHIPPED_REST }]);
    // An override that leaves the colours as they are, so every word sees the same two.
    installCaptionOverrideFetch(
      [0, 1, 2].map((wordIndex) => ({ wordIndex, activeColor: "#ffffff" })),
    );
    document.head.innerHTML = `<style>span { color: ${SHIPPED_REST}; }</style>`;
    document.body.innerHTML = `<div class="caption-group"><span></span><span></span><span></span></div>`;
    const computed = vi.spyOn(window, "getComputedStyle");

    applyCaptionOverrides();
    await flushCaptionOverrides();

    // One rest colour per word, plus the two tween colours.
    expect(computed).toHaveBeenCalledTimes(3 + 2);
  });
});

describe("caption state declaration", () => {
  it("honours a declared state when dim and active colours are IDENTICAL", async () => {
    // Without the declaration both tweens return the word to its rest colour, so both read as dim
    // and `activeColor` is silently dropped.
    const tweens = installGsapMockWithTweens([
      { color: "#888", data: { captionState: "dim" } },
      { color: "#888", data: { captionState: "active" } },
    ]);
    installCaptionOverrideFetch([{ wordIndex: 0, dimColor: "#111", activeColor: "#eee" }]);
    mountWord("#888");

    applyCaptionOverrides();
    await flushCaptionOverrides();

    expect(tweens[0].color).toBe("#111");
    expect(tweens[1].color).toBe("#eee");
  });

  it("invalidates every colour tween on the word, so each re-reads its start from the dimmed word", async () => {
    const tween = (color: string, at: number) => ({
      vars: { color },
      startTime: () => at,
      invalidate: vi.fn(),
    });
    const rendered = [tween("#fff", 0), tween("#222", 1)];
    const gsap = { set() {}, killTweensOf() {}, getTweensOf: () => rendered };
    Object.defineProperty(window, "gsap", { configurable: true, value: gsap });
    installCaptionOverrideFetch([{ wordIndex: 0, dimColor: "#111" }]);
    mountWord("#222");

    applyCaptionOverrides();
    await flushCaptionOverrides();

    expect(rendered.map((tw) => [tw.vars.color, tw.invalidate.mock.calls.length])).toEqual([
      ["#fff", 1],
      ["#111", 1],
    ]);
  });

  it("leaves a from() colour tween as recorded, so it still lights the word up to its own colour", async () => {
    const from = {
      vars: { color: "#444", runBackwards: true },
      startTime: () => 0,
      invalidate: vi.fn(),
    };
    const gsap = { set() {}, killTweensOf() {}, getTweensOf: () => [from] };
    Object.defineProperty(window, "gsap", { configurable: true, value: gsap });
    installCaptionOverrideFetch([{ wordIndex: 0, dimColor: "#888" }]);
    document.body.innerHTML = `<div class="caption-group"><span id="w0">Hi</span></div>`;

    applyCaptionOverrides();
    await flushCaptionOverrides();

    expect(from.invalidate).not.toHaveBeenCalled();
  });

  it("leaves a word with no colour tween to its own classes under an active-only override", async () => {
    const set = vi.fn((el: HTMLElement, vars: Record<string, unknown>) => {
      if (vars.color) el.style.color = String(vars.color);
    });
    Object.defineProperty(window, "gsap", {
      configurable: true,
      value: { set, killTweensOf() {}, getTweensOf: () => [] },
    });
    installCaptionOverrideFetch([{ wordIndex: 0, activeColor: "#ff0" }]);
    document.body.innerHTML = `<style>.w { color: #888; }</style><div class="caption-group"><span class="w">Hi</span></div>`;

    applyCaptionOverrides();
    await flushCaptionOverrides();

    expect(document.querySelector<HTMLElement>(".w")?.style.color).toBe("");
  });

  it("prefers the declaration over the rest colour, per tween, when they disagree", async () => {
    // The first two are the reverse of what the rest colour infers; the third is undeclared.
    const tweens = installGsapMockWithTweens([
      { color: "#222", data: { captionState: "active" } },
      { color: "#fff", data: { captionState: "dim" } },
      { color: "#222" },
    ]);
    installCaptionOverrideFetch([{ wordIndex: 0, dimColor: "#111", activeColor: "#eee" }]);
    mountWord("#222");

    applyCaptionOverrides();
    await flushCaptionOverrides();

    expect(tweens.map((tw) => tw.color)).toEqual(["#eee", "#111", "#111"]);
  });

  it("falls through to the rest colour for a malformed declaration", async () => {
    // A typo, a primitive, or a null must never ship a broken composition — an unrecognised value
    // is not a state, so classification continues as if nothing was declared.
    for (const data of [{ captionState: "typo" }, { captionState: 42 }, null, "notAnObject"]) {
      const tweens = installGsapMockWithTweens([{ color: "#222", data }, { color: "#fff" }]);
      installCaptionOverrideFetch([{ wordIndex: 0, dimColor: "#dim", activeColor: "#active" }]);
      mountWord("#222");

      applyCaptionOverrides();
      await flushCaptionOverrides();

      expect(tweens[0].color).toBe("#dim");
      expect(tweens[1].color).toBe("#active");
    }
  });
});