@vfrey/vfrey 0.0.1 → 1.0.0-beta.1

package/src/scene/inspect/page-scripts.ts

@@ -0,0 +1,272 @@
+/**
+ * The JavaScript that runs inside the scene's page for `vfrey scene inspect`, as plain strings (the page is not built by
+ * a bundler, so none of this may use TypeScript or helpers a transpiler would add).
+ *
+ * HOOK runs before the scene's own scripts. It keeps the stack of every GSAP timeline call and of `vfrey.block` and
+ * `vfrey.transition`, which is how a tween is traced back to the line that wrote it.
+ */
+export const HOOK = String.raw`(function () {
+  Error.stackTraceLimit = 60;
+  var rec = (window.__vfInspect = { tweens: new Map(), standalone: [], cues: [], errors: [] });
+  window.addEventListener("error", function (e) { rec.errors.push(String(e.message || e)); });
+  function stack() { return new Error().stack || ""; }
+  function wrapTimeline(tl) {
+    ["to", "from", "fromTo", "set"].forEach(function (m) {
+      var orig = tl[m];
+      if (typeof orig !== "function") return;
+      tl[m] = function __vfHook() {
+        var before = new Set(tl.getChildren(false, true, false));
+        var s = stack();
+        var out = orig.apply(this, arguments);
+        tl.getChildren(false, true, false).forEach(function (c) {
+          if (!before.has(c)) rec.tweens.set(c, { method: m, stack: s });
+        });
+        return out;
+      };
+    });
+  }
+  function wrapGsap(g) {
+    if (!g || g.__vfWrapped) return;
+    g.__vfWrapped = true;
+    var timeline = g.timeline;
+    g.timeline = function () {
+      var tl = timeline.apply(this, arguments);
+      wrapTimeline(tl);
+      return tl;
+    };
+    ["to", "from", "fromTo", "set"].forEach(function (m) {
+      var orig = g[m];
+      if (typeof orig !== "function") return;
+      g[m] = function __vfHook() {
+        var s = stack();
+        var t = orig.apply(this, arguments);
+        if (t && typeof t.targets === "function") rec.standalone.push({ tween: t, method: m, stack: s });
+        return t;
+      };
+    });
+  }
+  var realGsap;
+  Object.defineProperty(window, "gsap", { configurable: true, get: function () { return realGsap; }, set: function (v) { realGsap = v; try { wrapGsap(v); } catch (e) { rec.errors.push(String(e)); } } });
+  function resolve(t) { return typeof t === "string" ? document.querySelector(t) : t; }
+  function wrapVfrey(v) {
+    if (!v || v.__vfWrapped) return;
+    v.__vfWrapped = true;
+    ["block", "transition"].forEach(function (kind) {
+      var orig = v[kind];
+      if (typeof orig !== "function") return;
+      v[kind] = function __vfHook(a, b, c) {
+        var s = stack();
+        var entry = { kind: kind, stack: s };
+        if (kind === "block") { entry.el = resolve(a); entry.start = b; entry.duration = c; }
+        else { entry.from = resolve(a); entry.to = resolve(b); entry.options = c && typeof c === "object" ? JSON.parse(JSON.stringify(c)) : {}; }
+        rec.cues.push(entry);
+        return orig.apply(this, arguments);
+      };
+    });
+  }
+  var realVfrey;
+  Object.defineProperty(window, "vfrey", { configurable: true, get: function () { return realVfrey; }, set: function (v) { realVfrey = v; try { wrapVfrey(v); } catch (e) { rec.errors.push(String(e)); } } });
+})();`;
+
+/** Embeds a block (an element with `data-composition-src`) the way the renderer does: its markup inside the host, its scoped CSS, then its scripts. */
+export const LOAD_SUBS = String.raw`(async function (subs) {
+  var rec = window.__vfInspect;
+  for (var i = 0; i < subs.length; i++) {
+    var sub = subs[i];
+    var host = document.querySelector('[data-composition-src="' + sub.src + '"]');
+    if (!host) { rec.errors.push("no element for " + sub.src); continue; }
+    try {
+      var html = await (await fetch(sub.src)).text();
+      var doc = new DOMParser().parseFromString(html, "text/html");
+      var root = doc.querySelector("[data-composition-id]");
+      if (!root) continue;
+      root.querySelectorAll("script").forEach(function (s) { s.remove(); });
+      root.removeAttribute("id");
+      host.appendChild(document.importNode(root, true));
+      var style = document.createElement("style");
+      style.textContent = sub.css;
+      document.head.appendChild(style);
+      for (var k = 0; k < sub.scripts.length; k++) {
+        var sc = sub.scripts[k];
+        var el = document.createElement("script");
+        el.textContent = "(function(){" + "\n".repeat(sc.line - 1) + " ".repeat(Math.max(0, sc.col - 1)) + sc.text + "\n})();\n//# sourceURL=" + location.origin + "/" + sc.file;
+        document.body.appendChild(el);
+      }
+    } catch (e) { rec.errors.push(sub.src + ": " + e); }
+  }
+})`;
+
+const SKIP = "html,head,script,style,meta,link,title,noscript,template";
+
+/** `window.__vfCollect(params)`: seeks every timeline, then describes the elements asked for. Returns plain JSON. */
+export const COLLECT = String.raw`(function () {
+  var rec = window.__vfInspect;
+  var SKIP = ${JSON.stringify(SKIP)};
+  var NOT_PROPS = { duration: 1, ease: 1, delay: 1, stagger: 1, repeat: 1, yoyo: 1, repeatDelay: 1, paused: 1, overwrite: 1, immediateRender: 1, lazy: 1, startAt: 1, runBackwards: 1, id: 1, data: 1, callbackScope: 1, defaults: 1, yoyoEase: 1, inherit: 1, parent: 1, keyframes: 1, repeatRefresh: 1, reversed: 1, onComplete: 1, onStart: 1, onUpdate: 1, onRepeat: 1, onReverseComplete: 1, onInterrupt: 1, onToggle: 1, onCompleteParams: 1, onReverseCompleteParams: 1, onStartParams: 1, onUpdateParams: 1, onRepeatParams: 1 };
+  function norm(s) { return String(s).replace(/\s+/g, " ").trim().toLowerCase(); }
+  function offsetOf(el) {
+    var sum = 0;
+    for (var n = el; n && n.nodeType === 1; n = n.parentElement) { var s = parseFloat(n.getAttribute("data-start")); if (isFinite(s)) sum += s; }
+    return sum;
+  }
+  function label(n) { return n.tagName.toLowerCase() + (n.id ? "#" + n.id : ""); }
+  function timed(el, t) {
+    var chain = [];
+    for (var n = el; n && n.nodeType === 1; n = n.parentElement) chain.unshift(n);
+    var local = t;
+    for (var i = 0; i < chain.length; i++) {
+      var s = parseFloat(chain[i].getAttribute("data-start"));
+      if (!isFinite(s)) continue;
+      var d = parseFloat(chain[i].getAttribute("data-duration"));
+      if (local < s - 1e-6) return { active: false, why: "before data-start " + s + "s of " + label(chain[i]) };
+      if (isFinite(d) && local >= s + d - 1e-6) return { active: false, why: "after data-start " + s + "s + data-duration " + d + "s of " + label(chain[i]) };
+      local -= s;
+    }
+    return { active: true };
+  }
+  function pathOf(el) {
+    if (el.id && document.querySelectorAll("#" + CSS.escape(el.id)).length === 1) return "#" + CSS.escape(el.id);
+    var parts = [];
+    for (var n = el; n && n.nodeType === 1 && n !== document.documentElement; n = n.parentElement) {
+      if (n.id && document.querySelectorAll("#" + CSS.escape(n.id)).length === 1) { parts.unshift("#" + CSS.escape(n.id)); break; }
+      var part = n.tagName.toLowerCase();
+      var cls = Array.prototype.filter.call(n.classList, function (c) { return !/^vf-/.test(c); }).slice(0, 2);
+      if (cls.length) part += "." + cls.map(CSS.escape).join(".");
+      var sibs = n.parentElement ? Array.prototype.filter.call(n.parentElement.children, function (c) { return c.tagName === n.tagName; }) : [];
+      if (sibs.length > 1) part += ":nth-of-type(" + (sibs.indexOf(n) + 1) + ")";
+      parts.unshift(part);
+      if (n === document.body) break;
+    }
+    return parts.join(" > ");
+  }
+  function globalStart(tw) {
+    var s = 0;
+    for (var n = tw; n && n.parent && n.parent !== gsap.globalTimeline; n = n.parent) s += n.startTime();
+    return s;
+  }
+  function plain(v) {
+    if (typeof v === "number" || typeof v === "boolean") return v;
+    if (typeof v === "string") return v.length > 80 ? v.slice(0, 77) + "..." : v;
+    if (typeof v === "function") return "(function)";
+    if (v && v.nodeType === 1) return "<" + label(v) + ">";
+    try { var j = JSON.stringify(v); return j.length > 80 ? j.slice(0, 77) + "..." : j; } catch (e) { return "(object)"; }
+  }
+  function props(vars) {
+    var out = {};
+    Object.keys(vars || {}).forEach(function (k) { if (!NOT_PROPS[k]) out[k] = plain(vars[k]); });
+    return out;
+  }
+  function allTweens() {
+    var out = [];
+    var seen = new Set();
+    var tls = [];
+    var reg = window.__timelines || {};
+    Object.keys(reg).forEach(function (k) { if (reg[k] && tls.indexOf(reg[k]) < 0) tls.push(reg[k]); });
+    function add(tw, onTimeline) {
+      if (seen.has(tw)) return;
+      seen.add(tw);
+      var info = rec.tweens.get(tw) || null;
+      var vars = tw.vars || {};
+      var targets = [];
+      try { targets = tw.targets().filter(function (t) { return t && t.nodeType === 1; }); } catch (e) {}
+      if (!targets.length && (!onTimeline || !Object.keys(props(vars)).length)) return;
+      var hostOffset = 0;
+      var first = targets[0];
+      var tlRoot = tw; while (tlRoot.parent && tlRoot.parent !== gsap.globalTimeline) tlRoot = tlRoot.parent;
+      tls.forEach(function (tl) { if (tl === tlRoot) { var comp = tl.__vfHost; if (comp) hostOffset = offsetOf(comp); } });
+      var start = (onTimeline ? globalStart(tw) : 0) + hostOffset;
+      var ease = typeof vars.ease === "string" ? vars.ease : null;
+      out.push({
+        tween: tw, targets: targets, method: info ? info.method : null, stack: info ? info.stack : "", onTimeline: onTimeline,
+        start: Math.round(start * 1000) / 1000, duration: Math.round(tw.duration() * 1000) / 1000, ease: ease,
+        props: props(vars), from: vars.startAt ? props(vars.startAt) : null, runBackwards: Boolean(vars.runBackwards),
+        stagger: vars.stagger !== undefined ? plain(vars.stagger) : null,
+      });
+    }
+    tls.forEach(function (tl) {
+      tl.getChildren(true, true, false).forEach(function (tw) { add(tw, true); });
+    });
+    rec.standalone.forEach(function (s) { add(s.tween, false); var last = out[out.length - 1]; if (last && last.tween === s.tween) { last.method = s.method; last.stack = s.stack; } });
+    return out;
+  }
+  function seek(t) {
+    var reg = window.__timelines || {};
+    Object.keys(reg).forEach(function (k) {
+      var tl = reg[k];
+      if (!tl || typeof tl.time !== "function") return;
+      var host = document.querySelector('[data-composition-id="' + k + '"]');
+      var comp = !host ? null : host.hasAttribute("data-composition-src") ? host : host.parentElement && host.parentElement.hasAttribute("data-composition-src") ? host.parentElement : null;
+      tl.__vfHost = comp;
+      var local = comp ? t - offsetOf(comp) : t;
+      tl.pause();
+      tl.time(Math.max(0, Math.min(local, tl.duration())), false);
+    });
+  }
+  function ancestors(el) { var out = []; for (var n = el; n && n.nodeType === 1; n = n.parentElement) out.push(n); return out; }
+  window.__vfCollect = function (p) {
+    seek(p.at);
+    var tweens = allTweens();
+    var all = Array.prototype.slice.call(document.body.querySelectorAll("*")).filter(function (e) { return !e.matches(SKIP); });
+    var found;
+    if (p.selector) found = Array.prototype.slice.call(document.querySelectorAll(p.selector)).filter(function (e) { return !e.matches(SKIP); });
+    else if (p.text) {
+      var needle = norm(p.text);
+      found = all.filter(function (e) {
+        if (norm(e.textContent).indexOf(needle) < 0) return false;
+        return !Array.prototype.some.call(e.children, function (c) { return norm(c.textContent).indexOf(needle) >= 0; });
+      });
+    } else found = all;
+    var cues = rec.cues;
+    var out = [];
+    var truncated = false;
+    found.forEach(function (el) {
+      var cs = getComputedStyle(el);
+      var r = el.getBoundingClientRect();
+      var st = timed(el, p.at);
+      var eff = 1;
+      ancestors(el).forEach(function (n) { eff *= parseFloat(getComputedStyle(n).opacity); });
+      var onScreen = r.right > 0 && r.bottom > 0 && r.left < 1080 && r.top < 1920;
+      var why = !st.active ? st.why : cs.display === "none" ? "display none" : cs.visibility === "hidden" ? "visibility hidden" : eff <= 0.001 ? "opacity 0" : r.width * r.height === 0 ? "no size" : !onScreen ? "outside the frame" : null;
+      if (!p.selector && !p.text && why) return;
+      if (out.length >= p.limit) { truncated = true; return; }
+      var own = el.getAttribute("data-vfsrc");
+      var via = null;
+      if (!own) { var a = el.closest("[data-vfsrc]"); if (a) via = { src: a.getAttribute("data-vfsrc"), path: pathOf(a) }; }
+      var anc = ancestors(el);
+      var rules = [];
+      p.rules.forEach(function (rule) { try { if (el.matches(rule.sel)) rules.push(rule.i); } catch (e) {} });
+      var upper = [];
+      anc.slice(1, 9).forEach(function (n) {
+        var rs = [];
+        p.rules.forEach(function (rule) { try { if (n.matches(rule.sel)) rs.push(rule.i); } catch (e) {} });
+        upper.push({ path: pathOf(n), src: n.getAttribute("data-vfsrc"), rules: rs });
+      });
+      var tw = [];
+      tweens.forEach(function (t, idx) {
+        var hit = t.targets.indexOf(el);
+        if (hit >= 0) tw.push({ i: idx, via: null });
+        else for (var k = 0; k < t.targets.length; k++) { if (t.targets[k].contains(el)) { tw.push({ i: idx, via: pathOf(t.targets[k]) }); break; } }
+      });
+      var cu = [];
+      cues.forEach(function (c, idx) {
+        if (c.kind === "block" && c.el && c.el.contains(el)) cu.push(idx);
+        if (c.kind === "transition" && ((c.from && c.from.contains(el)) || (c.to && c.to.contains(el)))) cu.push(idx);
+      });
+      out.push({
+        path: pathOf(el), tag: el.tagName.toLowerCase(), id: el.id || null, classes: Array.prototype.slice.call(el.classList),
+        src: own, via: via, visible: !why, hidden: why,
+        box: { x: Math.round(r.left * 10) / 10, y: Math.round(r.top * 10) / 10, w: Math.round(r.width * 10) / 10, h: Math.round(r.height * 10) / 10 },
+        opacityEffective: Math.round(eff * 1000) / 1000,
+        styles: { color: cs.color, backgroundColor: cs.backgroundColor, fontFamily: cs.fontFamily, fontSize: cs.fontSize, fontWeight: cs.fontWeight, opacity: cs.opacity, transform: cs.transform },
+        text: norm(el.textContent).slice(0, 60),
+        rules: rules, upper: upper, tweens: tw, cues: cu,
+      });
+    });
+    return {
+      matched: found.length, truncated: truncated, elements: out,
+      tweens: tweens.map(function (t) { return { method: t.method, stack: t.stack, onTimeline: t.onTimeline, start: t.start, duration: t.duration, ease: t.ease, props: t.props, from: t.from, runBackwards: t.runBackwards, stagger: t.stagger, targets: t.targets.length }; }),
+      cues: cues.map(function (c) { return { kind: c.kind, stack: c.stack, start: c.start === undefined ? null : c.start, duration: c.duration === undefined ? null : c.duration, options: c.options || null, host: c.el ? pathOf(c.el) : null, from: c.from ? pathOf(c.from) : null, to: c.to ? pathOf(c.to) : null }; }),
+      errors: rec.errors,
+    };
+  };
+})();`;

package/src/scene/inspect/report.ts

@@ -0,0 +1,405 @@
+import { inlineDecls, mapStack, specificity, type Decl, type Pos, type Rule, type Scan } from "./source.js";
+
+/** What the page hands back (see COLLECT in page-scripts.ts). */
+export interface RawTween {
+  method: string | null;
+  stack: string;
+  onTimeline: boolean;
+  start: number;
+  duration: number;
+  ease: string | null;
+  props: Record<string, string | number | boolean>;
+  from: Record<string, string | number | boolean> | null;
+  runBackwards: boolean;
+  stagger: string | number | boolean | null;
+  targets: number;
+}
+export interface RawCue {
+  kind: "block" | "transition";
+  stack: string;
+  start: number | null;
+  duration: number | null;
+  options: Record<string, unknown> | null;
+  host: string | null;
+  from: string | null;
+  to: string | null;
+}
+export interface RawElement {
+  path: string;
+  tag: string;
+  id: string | null;
+  classes: string[];
+  src: string | null;
+  via: { src: string; path: string } | null;
+  visible: boolean;
+  hidden: string | null;
+  box: { x: number; y: number; w: number; h: number };
+  opacityEffective: number;
+  styles: Record<string, string>;
+  text: string;
+  rules: number[];
+  upper: Array<{ path: string; src: string | null; rules: number[] }>;
+  tweens: Array<{ i: number; via: string | null }>;
+  cues: number[];
+}
+export interface Raw {
+  matched: number;
+  truncated: boolean;
+  elements: RawElement[];
+  tweens: RawTween[];
+  cues: RawCue[];
+  errors: string[];
+}
+
+export interface SceneFile {
+  label: string;
+  source: string;
+  scan: Scan;
+}
+
+export interface Located extends Pos {
+  /** The source line, trimmed. */
+  code: string;
+}
+
+export interface CssDecl {
+  property: string;
+  value: string;
+  important: boolean;
+  /** Where the declaration is. */
+  at: Located;
+  /** `rule` for a stylesheet, `inline` for a style attribute. */
+  from: "rule" | "inline";
+  selector: string | null;
+  atrule: string | null;
+  /** The rule's own line, when it is a rule. */
+  rule: Pos | null;
+  /** True when this declaration wins the cascade for its property (an inline GSAP value can still override it at runtime). */
+  wins: boolean;
+  /** Set when the element does not set the property itself and gets it from this ancestor. */
+  inheritedFrom: string | null;
+}
+
+export interface TweenReport {
+  /** `to`, `from`, `fromTo` or `set`; null when GSAP made it without a call the inspector saw. */
+  method: string | null;
+  start: number;
+  end: number;
+  duration: number;
+  ease: string | null;
+  props: Record<string, string | number | boolean>;
+  from: Record<string, string | number | boolean> | null;
+  stagger: string | number | boolean | null;
+  /** Elements this tween animates; more than one means a shared tween. */
+  targets: number;
+  /** The path of the ancestor the tween targets, when it is not the element itself. */
+  via: string | null;
+  /** Where the tween call is written. */
+  site: Located | null;
+  /** The vfrey cue that ran it, with the line that called the cue. */
+  cue: { name: string; site: Located | null } | null;
+  /** `vfrey.transition` made this one (no line of the scene wrote it). */
+  madeBy: { name: string; site: Located | null } | null;
+  /** CSS families (color, background, font, opacity, transform) this tween moves. */
+  affects: string[];
+}
+
+export interface CueReport {
+  name: string;
+  detail: string;
+  site: Located | null;
+}
+
+export interface ElementReport {
+  selector: string;
+  tag: string;
+  id: string | null;
+  classes: string[];
+  /** The opening tag in the scene's file; null when a script created the element. */
+  source: Located | null;
+  scriptCreated: boolean;
+  /** For a script-created element: the nearest ancestor that is in the file. */
+  nearestSource: (Located & { selector: string }) | null;
+  visible: boolean;
+  hiddenBecause: string | null;
+  box: { x: number; y: number; w: number; h: number };
+  styles: Record<string, string>;
+  css: Record<string, CssDecl[]>;
+  tweens: TweenReport[];
+  cues: CueReport[];
+  text: string;
+}
+
+export interface InspectReport {
+  scene: string;
+  engine: "html";
+  at: number;
+  frame: { width: number; height: number };
+  query: { selector: string | null; text: string | null };
+  matched: number;
+  shown: number;
+  truncated: boolean;
+  elements: ElementReport[];
+  warnings: string[];
+}
+
+export const FAMILIES: Record<string, string[]> = {
+  color: ["color"],
+  background: ["background", "background-color", "background-image"],
+  font: ["font", "font-family", "font-size", "font-weight"],
+  opacity: ["opacity"],
+  transform: ["transform", "translate", "scale", "rotate"],
+};
+
+const GSAP_FAMILY: Array<[RegExp, string]> = [
+  [/^(x|y|z|xPercent|yPercent|scale|scaleX|scaleY|rotation|rotate|rotationX|rotationY|skewX|skewY|transform|translate|translateX|translateY|transformOrigin)$/, "transform"],
+  [/^(opacity|autoAlpha)$/, "opacity"],
+  [/^color$/, "color"],
+  [/^(backgroundColor|background)$/, "background"],
+  [/^(fontSize|fontWeight|fontFamily)$/, "font"],
+];
+
+export function familiesOf(props: Record<string, unknown>): string[] {
+  const out = new Set<string>();
+  for (const key of Object.keys(props)) for (const [re, family] of GSAP_FAMILY) if (re.test(key)) out.add(family);
+  return [...out];
+}
+
+function lineOf(files: Map<string, SceneFile>, pos: Pos, fromCol = false): Located {
+  const text = files.get(pos.file)?.source.split("\n")[pos.line - 1] ?? "";
+  return { ...pos, code: (fromCol ? text.slice(pos.col - 1) : text).trim().slice(0, 110) };
+}
+
+export function parseSrc(src: string): Pos | null {
+  const m = /^(.*):(\d+):(\d+)$/.exec(src);
+  return m ? { file: m[1]!, line: Number(m[2]), col: Number(m[3]) } : null;
+}
+
+export interface BuildInput {
+  raw: Raw;
+  files: Map<string, SceneFile>;
+  rules: Rule[];
+  origin: string;
+  scene: string;
+  at: number;
+  query: { selector: string | null; text: string | null };
+  warnings: string[];
+}
+
+function markWinner(decls: CssDecl[], specs: number[]): void {
+  // important beats normal, an inline style beats a rule, then specificity, then the later declaration.
+  const key = (d: CssDecl, i: number) => [d.important ? 1 : 0, d.from === "inline" ? 1 : 0, specs[i]!, i];
+  let best = 0;
+  decls.forEach((d, i) => {
+    const a = key(d, i);
+    const b = key(decls[best]!, best);
+    for (let n = 0; n < a.length; n += 1) {
+      if (a[n] !== b[n]) {
+        if (a[n]! > b[n]!) best = i;
+        break;
+      }
+    }
+  });
+  decls.forEach((d, i) => {
+    d.wins = i === best;
+  });
+}
+
+/** Joins what the page saw with the scene's source: positions, CSS rules, tween call sites. */
+export function buildReport(input: BuildInput): InspectReport {
+  const { raw, files, rules, origin } = input;
+  const fileOf = (url: string): string | null => {
+    if (!url.startsWith(`${origin}/`)) return null;
+    return decodeURIComponent(url.slice(origin.length + 1).split(/[?#]/)[0]!);
+  };
+  const locate = (pos: Pos | null, fromCol = false): Located | null => (pos ? lineOf(files, pos, fromCol) : null);
+  const tweenReports = raw.tweens.map((t) => {
+    const mapped = mapStack(t.stack, fileOf);
+    return { raw: t, mapped };
+  });
+  const toCue = (c: RawCue): CueReport => {
+    const mapped = mapStack(c.stack, fileOf);
+    const site = locate(mapped.site);
+    if (c.kind === "block") return { name: "vfrey.block", detail: `${c.host ?? "?"} starts at ${c.start}s${c.duration != null ? `, lasts ${c.duration}s` : ""}`, site };
+    const o = c.options ?? {};
+    const bits = [o.type, o.at != null ? `at ${o.at}s` : null, o.duration != null ? `${o.duration}s` : null].filter(Boolean).join(", ");
+    return { name: "vfrey.transition", detail: `${c.from ?? "?"} -> ${c.to ?? "?"}${bits ? ` (${bits})` : ""}`, site };
+  };
+  const cueReports = raw.cues.map(toCue);
+  const scanFor = (pos: Pos) => files.get(pos.file)?.scan.tags.find((t) => t.line === pos.line && t.col === pos.col) ?? null;
+
+  const elements: ElementReport[] = raw.elements.map((e) => {
+    const srcPos = e.src ? parseSrc(e.src) : null;
+    const viaPos = e.via ? parseSrc(e.via.src) : null;
+    const css: Record<string, CssDecl[]> = {};
+    const declsOf = (rs: number[], pos: Pos | null): Array<{ rule: Rule | null; d: Decl }> => {
+      const out: Array<{ rule: Rule | null; d: Decl }> = [];
+      for (const i of rs) for (const d of rules[i]!.decls) out.push({ rule: rules[i]!, d });
+      const t = pos ? scanFor(pos) : null;
+      if (t?.attrs.style && pos) for (const d of inlineDecls(t.attrs.style, pos)) out.push({ rule: null, d });
+      return out;
+    };
+    const family = (decls: Array<{ rule: Rule | null; d: Decl }>, props: string[], at: Pos | null, inheritedFrom: string | null): CssDecl[] => {
+      const list: CssDecl[] = [];
+      const specs: number[] = [];
+      for (const { rule, d } of decls) {
+        if (!props.includes(d.prop)) continue;
+        const file = rule ? rule.file : at!.file;
+        list.push({
+          property: d.prop,
+          value: d.value,
+          important: d.important,
+          at: lineOf(files, { file, line: d.line, col: d.col }),
+          from: rule ? "rule" : "inline",
+          selector: rule ? rule.selectorText : null,
+          atrule: rule?.atrule ?? null,
+          rule: rule ? { file: rule.file, line: rule.line, col: rule.col } : null,
+          wins: false,
+          inheritedFrom,
+        });
+        specs.push(rule ? specificity(rule.selector) : 0);
+      }
+      markWinner(list, specs);
+      return list;
+    };
+    const own = declsOf(e.rules, srcPos);
+    for (const [name, props] of Object.entries(FAMILIES)) {
+      let list = family(own, props, srcPos, null);
+      if (list.length === 0 && (name === "color" || name === "font")) {
+        for (const up of e.upper) {
+          list = family(declsOf(up.rules, up.src ? parseSrc(up.src) : null), props, up.src ? parseSrc(up.src) : null, up.path);
+          if (list.length) break;
+        }
+      }
+      if (list.length) css[name] = list;
+    }
+    const tweens: TweenReport[] = e.tweens.map(({ i, via }) => {
+      const { raw: t, mapped } = tweenReports[i]!;
+      const transition = raw.cues.findIndex((c, ci) => c.kind === "transition" && e.cues.includes(ci));
+      const madeBy = !mapped.site && transition >= 0 ? { name: "vfrey.transition", site: cueReports[transition]!.site } : null;
+      return {
+        method: t.method,
+        start: t.start,
+        end: Math.round((t.start + t.duration) * 1000) / 1000,
+        duration: t.duration,
+        ease: t.ease,
+        props: t.props,
+        from: t.from,
+        stagger: t.stagger,
+        targets: t.targets,
+        via,
+        site: locate(mapped.site),
+        cue: mapped.cue ? { name: mapped.cue.name, site: locate(mapped.cue.site) } : null,
+        madeBy,
+        affects: familiesOf({ ...t.props, ...(t.from ?? {}) }),
+      };
+    });
+    for (const ci of e.cues) {
+      const cue = raw.cues[ci]!;
+      if (cue.kind !== "transition") continue;
+      const at = typeof cue.options?.at === "number" ? cue.options.at : null;
+      raw.tweens.forEach((t, ti) => {
+        if (t.targets !== 0 || !("p" in t.props) || (at !== null && Math.abs(t.start - at) > 0.002) || tweens.some((x) => x.start === t.start && x.madeBy)) return;
+        void ti;
+        tweens.push({
+          method: t.method,
+          start: t.start,
+          end: Math.round((t.start + t.duration) * 1000) / 1000,
+          duration: t.duration,
+          ease: t.ease,
+          props: t.props,
+          from: null,
+          stagger: null,
+          targets: 0,
+          via: null,
+          site: null,
+          cue: null,
+          madeBy: { name: "vfrey.transition (progress p drives the shader and the shots' opacity)", site: cueReports[ci]!.site },
+          affects: ["opacity"],
+        });
+      });
+    }
+    tweens.sort((a, b) => a.start - b.start);
+    return {
+      selector: e.path,
+      tag: e.tag,
+      id: e.id,
+      classes: e.classes,
+      source: srcPos ? locate(srcPos, true) : null,
+      scriptCreated: !srcPos,
+      nearestSource: viaPos && e.via ? { ...locate(viaPos, true)!, selector: e.via.path } : null,
+      visible: e.visible,
+      hiddenBecause: e.hidden,
+      box: e.box,
+      styles: e.styles,
+      css,
+      tweens,
+      cues: e.cues.map((i) => cueReports[i]!),
+      text: e.text,
+    };
+  });
+  return {
+    scene: input.scene,
+    engine: "html",
+    at: input.at,
+    frame: { width: 1080, height: 1920 },
+    query: input.query,
+    matched: raw.matched,
+    shown: elements.length,
+    truncated: raw.truncated,
+    elements,
+    warnings: [...input.warnings, ...raw.errors.map((e) => `page: ${e}`)],
+  };
+}
+
+const loc = (l: Located | Pos | null) => (l ? `${l.file}:${l.line}:${l.col}` : "?");
+const secs = (n: number) => `${n}s`;
+const pv = (props: Record<string, unknown>) => Object.entries(props).map(([k, v]) => `${k}:${v}`).join(" ");
+
+function tweenLine(t: TweenReport, n: number): string[] {
+  const kind = t.method ?? "tween";
+  const body = kind === "fromTo" && t.from ? `{${pv(t.from)}} -> {${pv(t.props)}}` : `{${pv(t.props)}}`;
+  const ease = t.duration > 0 ? `  ease ${t.ease ?? "default"}` : "";
+  const out = [`    ${n}. ${kind} ${body}  start ${secs(t.start)}  duration ${secs(t.duration)}  ends ${secs(t.end)}${ease}${t.stagger != null ? `  stagger ${t.stagger}` : ""}${t.targets > 1 ? `  (shared by ${t.targets} elements)` : ""}${t.via ? `  (targets ancestor ${t.via})` : ""}`];
+  if (t.site) out.push(`       at ${loc(t.site)}  ${t.site.code}`);
+  if (t.cue) out.push(`       cue ${t.cue.name} at ${loc(t.cue.site)}${t.cue.site ? `  ${t.cue.site.code}` : ""}`);
+  if (t.madeBy) out.push(`       made by ${t.madeBy.name} at ${loc(t.madeBy.site)}${t.madeBy.site ? `  ${t.madeBy.site.code}` : ""}`);
+  if (!t.site && !t.madeBy) out.push("       (call site not traced)");
+  return out;
+}
+
+/** The report as short text for an agent. */
+export function formatText(r: InspectReport, maxTweens = 12): string {
+  const what = r.query.selector ? `selector ${r.query.selector}` : r.query.text ? `text "${r.query.text}"` : "all visible elements";
+  const lines = [`${r.scene} at ${secs(r.at)}, frame ${r.frame.width}x${r.frame.height}: ${r.matched} match${r.matched === 1 ? "" : "es"} for ${what}${r.truncated ? ` (showing ${r.shown})` : ""}`];
+  for (const w of r.warnings) lines.push(`! ${w}`);
+  if (r.elements.length === 0) lines.push("No element matched. Fix: check the selector or text against index.html, or try another --at time.");
+  for (const e of r.elements) {
+    lines.push("");
+    lines.push(`${e.selector}  <${e.tag}${e.id ? `#${e.id}` : ""}${e.classes.length ? `.${e.classes.join(".")}` : ""}>${e.text ? `  "${e.text}"` : ""}`);
+    if (e.source) lines.push(`  source ${loc(e.source)}  ${e.source.code}`);
+    else if (e.nearestSource) lines.push(`  source created by a script; nearest markup ${e.nearestSource.selector} at ${loc(e.nearestSource)}  ${e.nearestSource.code}`);
+    else lines.push("  source created by a script (no markup for it in the file)");
+    lines.push(`  box x ${e.box.x} y ${e.box.y} ${e.box.w}x${e.box.h}  ${e.visible ? "visible" : `not visible: ${e.hiddenBecause}`}`);
+    const s = e.styles;
+    lines.push(`  style color ${s.color} | background ${s.backgroundColor} | font ${s.fontFamily} ${s.fontSize} w${s.fontWeight} | opacity ${s.opacity} | transform ${s.transform}`);
+    const families = Object.keys(e.css);
+    if (families.length) {
+      lines.push("  css (* = wins the cascade; a GSAP tween below may still override it at runtime)");
+      for (const family of families) {
+        for (const d of e.css[family]!) {
+          const where = d.from === "inline" ? "style attribute" : `${d.selector}${d.atrule ? ` in ${d.atrule}` : ""}`;
+          lines.push(`    ${d.wins ? "*" : " "} ${d.property}: ${d.value}${d.important ? " !important" : ""}  ${where}  at ${loc(d.at)}${d.rule ? ` (rule starts ${d.rule.line}:${d.rule.col})` : ""}${d.inheritedFrom ? `  inherited from ${d.inheritedFrom}` : ""}`);
+        }
+      }
+    } else lines.push("  css no rule sets color, background, font, opacity or transform on it (inherited, or set by a script)");
+    if (e.cues.length) for (const c of e.cues) lines.push(`  cue ${c.name} ${c.detail}  at ${loc(c.site)}${c.site ? `  ${c.site.code}` : ""}`);
+    if (e.tweens.length) {
+      lines.push(`  tweens on the timeline (${e.tweens.length})`);
+      e.tweens.slice(0, maxTweens).forEach((t, i) => lines.push(...tweenLine(t, i + 1)));
+      if (e.tweens.length > maxTweens) lines.push(`    ... ${e.tweens.length - maxTweens} more (use --json for all)`);
+    } else lines.push("  tweens none target it");
+  }
+  return `${lines.join("\n")}\n`;
+}
+