Skip to content

Write HTML. Render video. Built for agents.

10.0 KB
Raw Blame
/**
 * Caption Overrides — applies per-word style overrides from a JSON data file.
 *
 * Strategy: wrap each overridden word span in an inline-block wrapper span,
 * then apply transforms to the wrapper. The inner span keeps all its original
 * GSAP animations (entrance, karaoke, exit) untouched. No tweens are killed.
 *
 * Matching (in priority order):
 * 1. `wordId` — matches by element ID (document.getElementById)
 * 2. `wordIndex` — fallback, DOM traversal order across .caption-group > span
 */

import { isHtmlElement } from "./domRealm";

interface CaptionOverride {
  wordId?: string;
  wordIndex?: number;
  x?: number;
  y?: number;
  scale?: number;
  rotation?: number;
  /** Color when the word is being spoken (karaoke active state) */
  activeColor?: string;
  /** Color before and after the word is spoken (dim/inactive state) */
  dimColor?: string;
  opacity?: number;
  fontSize?: number;
  fontWeight?: number;
  fontFamily?: string;
}

function isCaptionOverride(value: unknown): value is CaptionOverride {
  return typeof value === "object" && value !== null && !Array.isArray(value);
}

function parseCaptionOverridePayload(value: unknown): CaptionOverride[] {
  if (!Array.isArray(value)) {
    throw new Error("expected a JSON array");
  }
  if (!value.every(isCaptionOverride)) {
    throw new Error("every array entry must be an object");
  }
  return value;
}

interface GsapTween {
  vars: Record<string, unknown>;
  startTime(): number;
  invalidate?(): void;
}

interface GsapStatic {
  set: (target: Element, vars: Record<string, unknown>) => void;
  killTweensOf: (target: Element, props: string) => void;
  getTweensOf: (target: Element) => GsapTween[];
}

/**
 * The caption state a composition DECLARES for a colour tween, if any.
 *
 * Authored as `data: { captionState: "dim" | "active" }` in the tween's vars. GSAP passes unknown
 * vars through untouched, so this costs a declaring composition nothing at runtime.
 *
 * It exists because the fallback below has to GUESS. Classifying by colour equality breaks outright
 * when a composition's two states share a colour: every tween matches the rest colour, and the
 * active override is silently dropped. A declaration is the composition telling us what it built,
 * rather than us inferring it from what it happens to look like.
 */
function declaredCaptionState(tween: GsapTween): "dim" | "active" | undefined {
  const data = tween.vars.data as { captionState?: unknown } | undefined;
  const state = data?.captionState;
  return state === "dim" || state === "active" ? state : undefined;
}

function resolveCaptionWordElement(el: Element | null): HTMLElement | null {
  if (!isHtmlElement(el)) return null;
  if (el.dataset.captionWrapper !== "true") return el;

  const inner = el.querySelector<HTMLElement>(":scope > span");
  return inner ?? null;
}

function getCaptionWordElements(): HTMLElement[] {
  const wordEls: HTMLElement[] = [];
  const groups = document.querySelectorAll(".caption-group");

  for (const group of groups) {
    for (const child of group.children) {
      if (!isHtmlElement(child)) continue;

      const wordEl =
        child.dataset.captionWrapper === "true"
          ? child.querySelector<HTMLElement>(":scope > span")
          : child.tagName === "SPAN"
            ? child
            : null;

      if (wordEl) wordEls.push(wordEl);
    }
  }

  return wordEls;
}

function getOrCreateCaptionWrapper(el: HTMLElement): HTMLElement {
  const parent = el.parentElement;
  if (parent?.dataset.captionWrapper === "true") return parent;

  const wrapper = document.createElement("span");
  wrapper.style.display = "inline-block";
  wrapper.dataset.captionWrapper = "true";
  el.parentNode?.insertBefore(wrapper, el);
  wrapper.appendChild(el);
  return wrapper;
}

const gsapOf = () => (window as unknown as { gsap?: GsapStatic }).gsap;

const fetchOverridesPayload = (): Promise<unknown> =>
  fetch("caption-overrides.json").then((r) => (r.ok ? r.json() : null));

const parseOverrides = (data: unknown): readonly CaptionOverride[] =>
  data === null ? [] : parseCaptionOverridePayload(data);

function logInvalidOverrides(error: unknown): void {
  const message = error instanceof Error ? error.message : String(error);
  console.error(`[HyperFrames] Invalid caption-overrides.json: ${message}`);
}

/** The page's caption overrides; empty when there are none or no GSAP to apply them with. */
export function fetchCaptionOverrides(): Promise<readonly CaptionOverride[]> {
  if (!gsapOf()) return Promise.resolve([]);
  return fetchOverridesPayload()
    .then(parseOverrides)
    .catch((error: unknown) => {
      logInvalidOverrides(error);
      return [];
    });
}

export function applyCaptionOverrides(
  within?: readonly Element[],
  beforeRewrite?: () => void,
): Promise<void> {
  if (!gsapOf()) return Promise.resolve();
  // Only fetch overrides if the composition has caption groups
  if (document.querySelectorAll(".caption-group").length === 0) return Promise.resolve();
  return fetchOverridesPayload()
    .then((data) => applyFetchedCaptionOverrides(parseOverrides(data), within, beforeRewrite))
    .catch(logInvalidOverrides);
}

function findOverrideTarget(override: CaptionOverride, wordEls: HTMLElement[]): HTMLElement | null {
  const byId = override.wordId
    ? resolveCaptionWordElement(document.getElementById(override.wordId))
    : null;
  return byId ?? (override.wordIndex !== undefined ? (wordEls[override.wordIndex] ?? null) : null);
}

function definedProps(override: CaptionOverride, keys: (keyof CaptionOverride)[]) {
  return Object.fromEntries(
    keys.filter((key) => override[key] !== undefined).map((key) => [key, override[key]]),
  );
}

// The colour the browser paints on `el` with `color` inline, so any spelling compares equal.
// An empty `color` reads the stylesheet colour past whatever GSAP has rendered inline.
function paintedColor(el: HTMLElement, color: string): string {
  const inline = el.style.color;
  el.style.color = color;
  const painted = getComputedStyle(el).color;
  el.style.color = inline;
  return painted;
}

// What the word shows before it is spoken: its first colour tween's start colour (a fromTo()),
// else its stylesheet colour.
function restColorOf(el: HTMLElement, colorTweens: GsapTween[]): string {
  const startAt = colorTweens[0]?.vars.startAt as { color?: unknown } | undefined;
  return paintedColor(el, startAt?.color === undefined ? "" : String(startAt.color));
}

// A declaration wins, per tween; otherwise a tween back to the word's rest colour is dim.
// `painted` caches resolutions for one apply: tween colours repeat, and each forces a style recalc.
function tweenState(
  tw: GsapTween,
  el: HTMLElement,
  rest: string,
  painted: Map<string, string>,
): "dim" | "active" {
  const declared = declaredCaptionState(tw);
  if (declared) return declared;
  const color = String(tw.vars.color);
  // var() and currentColor resolve per word, so only plain colours are shared.
  if (/var\(|currentcolor/i.test(color)) return paintedColor(el, color) === rest ? "dim" : "active";
  if (!painted.has(color)) painted.set(color, paintedColor(el, color));
  return painted.get(color) === rest ? "dim" : "active";
}

// What the invalidated tweens re-read their start from, wherever the playhead has been. A from()
// recorded its own start, and a word with no colour tween keeps its classes' colours.
function restPaintOf(
  override: CaptionOverride,
  colorTweens: GsapTween[],
  rest: string,
): string | undefined {
  if (override.dimColor) return override.dimColor;
  if (colorTweens.length === 0 || colorTweens.some((tw) => tw.vars.runBackwards)) return undefined;
  return rest;
}

function rewriteColorTweens(
  gsap: GsapStatic,
  el: HTMLElement,
  override: CaptionOverride,
  painted: Map<string, string>,
): void {
  const colorTweens = gsap
    .getTweensOf(el)
    .filter((tw) => tw.vars.color !== undefined)
    .sort((a, b) => a.startTime() - b.startTime());
  const rest = restColorOf(el, colorTweens);

  for (const tw of colorTweens) {
    const state = tweenState(tw, el, rest, painted);
    const color = state === "dim" ? override.dimColor : override.activeColor;
    if (color) tw.vars.color = color;
    // Each re-reads its start from the word as repainted below, rewritten or not.
    // A from() re-read that way would end on that colour instead.
    if (!tw.vars.runBackwards) tw.invalidate?.();
  }

  const restPaint = restPaintOf(override, colorTweens, rest);
  if (restPaint) gsap.set(el, { color: restPaint });
}

function applyWordOverride(
  gsap: GsapStatic,
  el: HTMLElement,
  override: CaptionOverride,
  painted: Map<string, string>,
): void {
  // Split into transform props (wrapper) and style props (word span)
  const transformProps = definedProps(override, ["x", "y", "scale", "rotation"]);
  const styleProps = definedProps(override, ["opacity", "fontWeight", "fontFamily"]);
  if (override.fontSize !== undefined) styleProps.fontSize = `${override.fontSize}px`;

  if (override.activeColor || override.dimColor) rewriteColorTweens(gsap, el, override, painted);

  // Apply non-color style props
  if (Object.keys(styleProps).length > 0) {
    gsap.set(el, styleProps);
  }

  // Wrap the word in an inline-block span and apply transforms to the wrapper.
  // This preserves all GSAP entrance/exit/karaoke animations on the inner span.
  if (Object.keys(transformProps).length > 0) {
    const wrapper = getOrCreateCaptionWrapper(el);
    gsap.set(wrapper, transformProps);
  }
}

export function applyFetchedCaptionOverrides(
  overrides: readonly CaptionOverride[],
  within?: readonly Element[],
  beforeRewrite: () => void = () => {},
): void {
  const gsap = gsapOf();
  if (!gsap || overrides.length === 0) return;
  beforeRewrite();

  // Build word element index for wordIndex fallback
  const wordEls = getCaptionWordElements();
  const painted = new Map<string, string>();

  for (const override of overrides) {
    const el = findOverrideTarget(override, wordEls);
    if (!el || (within && !within.some((root) => root.contains(el)))) continue;
    applyWordOverride(gsap, el, override, painted);
  }
}