Skip to content

Write HTML. Render video. Built for agents.

6.3 KB
Raw Blame
import { parseHTML } from "linkedom";
import { parseGsapScriptAcorn } from "./gsapParserAcorn.js";
import type { GsapAnimation } from "./gsapSerialize.js";
import { TIMING_TOLERANCE_SECONDS } from "./compositionDuration.js";
import { isSubCompositionHost, topLevelElements } from "./topLevelElements.js";
import type { StructureNode } from "./topLevelElements.js";

const NON_RENDERED = new Set(["script", "style", "template", "noscript", "link", "meta"]);

export type TimingFinding =
  | {
      kind: "tween-outside-window";
      selector: string;
      elementId: string | null;
      dataStart: number;
      dataEnd: number | null;
      tweenStart: number;
      tweenEnd: number;
    }
  | { kind: "animated-without-timing"; selector: string; elementId: string | null }
  | { kind: "timeline-exceeds-root-duration"; rootDuration: number; timelineEnd: number };

/** Timing that could not be read statically. Reported, never flagged. */
export interface UnresolvedTiming {
  selector: string;
  reason: "duration" | "position" | "stagger" | "start-attribute";
}

export interface TimingMismatchReport {
  findings: TimingFinding[];
  unresolved: UnresolvedTiming[];
}

interface DomNode extends StructureNode<DomNode> {
  el: Element;
}

const toNode = (el: Element): DomNode => ({
  tag: el.tagName,
  attrs: Object.fromEntries(Array.from(el.attributes, (a) => [a.name, a.value])),
  children: Array.from(el.children, toNode),
  el,
});

const numeric = (value: string | null | undefined): number | null => {
  if (value == null || value.trim() === "") return null;
  const n = Number(value);
  return Number.isFinite(n) ? n : null;
};

function queryAll(root: Element, selector: string): Element[] {
  try {
    return Array.from(root.querySelectorAll(selector));
  } catch {
    return [];
  }
}

type Anim = GsapAnimation;

const unresolvedReason = (anim: Anim): UnresolvedTiming["reason"] | null => {
  if (anim.durationUnresolved) return "duration";
  if (anim.resolvedStart === undefined) return "position";
  return anim.extras?.stagger === undefined ? null : "stagger";
};

interface Layout {
  rowEls: Set<Element>;
  insideRow: Set<Element>;
}

/** Where each element sits: inside a timeline row (timed clip or sub-composition), or loose. */
function rowMembership(root: Element): Layout {
  const rows = topLevelElements(toNode(root));
  const rowEls = new Set(rows.map((r) => r.el));
  const insideRow = new Set<Element>();
  for (const row of rows) {
    insideRow.add(row.el);
    for (const d of Array.from(row.el.querySelectorAll("*"))) insideRow.add(d);
  }
  return { rowEls, insideRow };
}

const attrNumber = (el: Element, name: string): number | null => numeric(el.getAttribute(name));

function windowFinding(
  el: Element,
  selector: string,
  anim: Anim,
  start: number,
  end: number,
): TimingFinding | null {
  const dataStart = attrNumber(el, "data-start");
  const duration = attrNumber(el, "data-duration");
  if (dataStart === null) return null;
  const dataEnd = duration === null ? null : dataStart + duration;
  const beforeStart = anim.method !== "set" && start < dataStart - TIMING_TOLERANCE_SECONDS;
  const afterEnd = dataEnd !== null && start > dataEnd + TIMING_TOLERANCE_SECONDS;
  if (!beforeStart && !afterEnd) return null;
  const elementId = el.getAttribute("id");
  return {
    kind: "tween-outside-window",
    selector,
    elementId,
    dataStart,
    dataEnd,
    tweenStart: start,
    tweenEnd: end,
  };
}

const tweenEnd = (anim: Anim): number =>
  (anim.resolvedStart as number) + (anim.method === "set" ? 0 : (anim.duration ?? 0.5));

/** Findings and unresolved entries for one resolved tween against one target element. */
function checkTarget(
  el: Element,
  selector: string,
  anim: Anim,
  layout: Layout,
  report: TimingMismatchReport,
) {
  if (!layout.insideRow.has(el)) {
    if (!NON_RENDERED.has(el.tagName.toLowerCase())) {
      report.findings.push({
        kind: "animated-without-timing",
        selector,
        elementId: el.getAttribute("id"),
      });
    }
    return;
  }
  if (!layout.rowEls.has(el) || isSubCompositionHost(toNode(el))) return;
  if (el.hasAttribute("data-start") && attrNumber(el, "data-start") === null) {
    report.unresolved.push({ selector, reason: "start-attribute" });
    return;
  }
  const found = windowFinding(el, selector, anim, anim.resolvedStart as number, tweenEnd(anim));
  if (found) report.findings.push(found);
}

/** Checks one tween against its targets and returns its end, or null when its timing is unresolved. */
function checkTween(
  anim: Anim,
  root: Element,
  layout: Layout,
  seenUntimed: Set<Element>,
  report: TimingMismatchReport,
): number | null {
  const selector = anim.targetSelector;
  const targets = queryAll(root, selector).filter((el) => el !== root);
  const reason = unresolvedReason(anim);
  if (reason) {
    if (targets.length > 0) report.unresolved.push({ selector, reason });
    return null;
  }
  for (const el of targets) {
    const loose = !layout.insideRow.has(el);
    if (loose && seenUntimed.has(el)) continue;
    if (loose) seenUntimed.add(el);
    checkTarget(el, selector, anim, layout, report);
  }
  return tweenEnd(anim);
}

/**
 * Compares the GSAP timeline in a composition file with the timing attributes of its elements.
 * Attributes are authoritative: a tween that places an element outside its window is a finding.
 */
export function timingMismatches(html: string): TimingMismatchReport {
  const report: TimingMismatchReport = { findings: [], unresolved: [] };
  const { document } = parseHTML(html);
  const root = document.querySelector("[data-composition-id]");
  if (!root) return report;

  const layout = rowMembership(root);
  const seenUntimed = new Set<Element>();
  const scripts = Array.from(document.querySelectorAll("script:not([src])"));
  const anims = scripts.flatMap((s) => parseGsapScriptAcorn(s.textContent ?? "").animations);
  const ends = anims
    .filter((anim) => !anim.global && !anim.hasUnresolvedSelector)
    .map((anim) => checkTween(anim, root, layout, seenUntimed, report));
  const timelineEnd = Math.max(0, ...ends.filter((e): e is number => e !== null));

  const rootDuration = attrNumber(root, "data-duration");
  if (rootDuration !== null && timelineEnd > rootDuration + TIMING_TOLERANCE_SECONDS) {
    report.findings.push({ kind: "timeline-exceeds-root-duration", rootDuration, timelineEnd });
  }
  return report;
}