@hyperframes/lint 0.7.59 → 0.7.61

package/dist/index.js

@@ -686,6 +686,17 @@ var coreRules = [
         pattern: /crypto\.getRandomValues\s*\(/,
         label: "crypto.getRandomValues()",
         hint: "Remove time-dependent code. Use a seeded PRNG for deterministic renders."
+      },
+      {
+        pattern: /gsap\.utils\.random\s*\(/,
+        label: "gsap.utils.random()",
+        hint: "Each render worker initializes independently, so random values diverge across chunks. Use a seeded PRNG or fixed values."
+      },
+      {
+        // GSAP string form: "random(...)" / "+=random(...)" — re-rolls at tween init.
+        pattern: /["'`](?:[+-]=)?random\(\s*[-\d[]/,
+        label: '"random(...)" tween value',
+        hint: "GSAP random string values re-roll at tween init and each render worker initializes independently. Use fixed values or precompute with a seeded PRNG."
       }
     ];
     for (const script of scripts) {
@@ -1311,19 +1322,24 @@ async function extractGsapWindows(script) {
   if (parsed.animations.length === 0) return [];
   const windows = [];
   for (const animation of parsed.animations) {
-    if (typeof animation.position !== "number") continue;
+    const start = animation.resolvedStart ?? (typeof animation.position === "number" ? animation.position : null);
+    if (start === null) continue;
     const repeat = extrasNumber(animation.extras?.repeat);
-    const cycleCount = repeat > 0 ? repeat + 1 : 1;
+    const infiniteRepeat = repeat < 0;
+    const cycleCount = infiniteRepeat ? 1 : repeat > 0 ? repeat + 1 : 1;
     const effectiveDuration = animation.method === "set" ? 0 : (animation.duration ?? 0) * cycleCount;
     windows.push({
       targetSelector: animation.targetSelector,
       targetIdentity: animation.targetIdentity,
-      position: animation.position,
-      end: animation.position + effectiveDuration,
+      position: start,
+      end: infiniteRepeat && animation.method !== "set" ? Number.POSITIVE_INFINITY : start + effectiveDuration,
       properties: Object.keys(animation.properties),
       propertyValues: animation.properties,
+      fromPropertyValues: animation.fromProperties,
       overwriteAuto: unwrapRaw(animation.extras?.overwrite) === "auto",
+      immediateRender: unwrapRaw(animation.extras?.immediateRender) === "true",
       method: animation.method,
+      global: animation.global,
       raw: synthesizeWindowRaw(parsed.timelineVar, animation)
     });
   }
@@ -1352,6 +1368,30 @@ function isHiddenGsapState(values) {
   const display = stringValue(values.display)?.toLowerCase();
   return zeroValue(values.opacity) || zeroValue(values.autoAlpha) || visibility === "hidden" || display === "none";
 }
+function extractStandaloneHiddenSelectors(script) {
+  const selectors = /* @__PURE__ */ new Set();
+  const source = stripJsComments(script);
+  const functionRanges = collectFunctionBodyRanges(source);
+  const aliases = /* @__PURE__ */ new Map();
+  for (const match2 of source.matchAll(
+    /(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*(["'`])([^"'`]+)\2\s*;/g
+  )) {
+    aliases.set(match2[1] ?? "", match2[3] ?? "");
+  }
+  const pattern = /gsap\.set\s*\(\s*([^,]+?)\s*,\s*\{([\s\S]*?)\}\s*\)/g;
+  let match;
+  while ((match = pattern.exec(source)) !== null) {
+    if (indexInsideNonIifeRange(match.index, source, functionRanges)) continue;
+    const target = (match[1] ?? "").trim();
+    const selector = /^(["'`])([^"'`]+)\1$/.exec(target)?.[2] ?? aliases.get(target);
+    if (!selector) continue;
+    const body = match[2] ?? "";
+    if (/(?:opacity|autoAlpha)\s*:\s*0(?:\.0+)?\s*(?:,|$)/.test(body)) {
+      selectors.add(selector);
+    }
+  }
+  return selectors;
+}
 function oneValue(values, keys) {
   for (const key of keys) {
     const value = values[key];
@@ -1609,6 +1649,329 @@ function scanScriptsForRegexMatches(scripts, pattern, options) {
   }
   return hits;
 }
+var RELATIVE_TWEEN_VALUE = /^[+-]=/;
+function isRelativeTweenValue(value) {
+  return typeof value === "string" && RELATIVE_TWEEN_VALUE.test(value.trim());
+}
+var TRANSFORM_SENSITIVE_READ = /\.getBoundingClientRect\s*\(|\bgetComputedStyle\s*\(|\bgsap\.getProperty\s*\(/;
+var TRANSFORM_INVARIANT_READ = /\.(?:getTotalLength|getBBox)\s*\(|\.(?:offsetWidth|offsetHeight|clientWidth|clientHeight)\b/;
+var CALLBACK_MEASUREMENT_PATTERN = /\.(?:getBoundingClientRect|getTotalLength|getBBox)\s*\(|\bgetComputedStyle\s*\(|\.(?:offsetWidth|offsetHeight|clientWidth|clientHeight)\b/;
+function indexTagsByToken(tags) {
+  const tagsByToken = /* @__PURE__ */ new Map();
+  const addToken = (token, tag) => {
+    const list = tagsByToken.get(token);
+    if (list) list.push(tag);
+    else tagsByToken.set(token, [tag]);
+  };
+  for (const tag of tags) {
+    const id = readAttr(tag.raw, "id");
+    if (id) addToken(`#${id}`, tag);
+    for (const cls of readAttr(tag.raw, "class")?.split(/\s+/).filter(Boolean) ?? [])
+      addToken(`.${cls}`, tag);
+  }
+  return tagsByToken;
+}
+function resolveSelectorTagIndexes(selector, tagsByToken) {
+  const indexes = /* @__PURE__ */ new Set();
+  for (const token of targetedSelectorTokens(selector)) {
+    for (const tag of tagsByToken.get(token) ?? []) indexes.add(tag.index);
+  }
+  return indexes;
+}
+function selectorResolvesFaithfully(selector) {
+  return selector.split(",").every((group) => {
+    const token = group.trim();
+    if (!token || token.includes("[")) return false;
+    return !/[\s>+~]/.test(token);
+  });
+}
+function targetsShareElement(a, b, tagsByToken) {
+  if (!targetHasNoStableIdentity(a.selector, a.identity) && !targetHasNoStableIdentity(b.selector, b.identity) && (a.identity ?? a.selector) === (b.identity ?? b.selector)) {
+    return true;
+  }
+  if (!selectorResolvesFaithfully(a.selector) || !selectorResolvesFaithfully(b.selector)) {
+    return false;
+  }
+  const aTags = resolveSelectorTagIndexes(a.selector, tagsByToken);
+  if (aTags.size === 0) return false;
+  const bTags = resolveSelectorTagIndexes(b.selector, tagsByToken);
+  for (const index of bTags) if (aTags.has(index)) return true;
+  return false;
+}
+function matchBalanced(source, openIndex, open, close) {
+  let depth = 0;
+  for (let i = openIndex; i < source.length; i++) {
+    const ch = source[i];
+    if (ch === open) depth++;
+    else if (ch === close) {
+      depth--;
+      if (depth === 0) return source.slice(openIndex, i + 1);
+    }
+  }
+  return null;
+}
+function enclosingObjectLiteral(source, index) {
+  let depth = 0;
+  for (let i = index; i >= 0; i--) {
+    const ch = source[i];
+    if (ch === "}") depth++;
+    else if (ch === "{") {
+      if (depth === 0) return matchBalanced(source, i, "{", "}");
+      depth--;
+    }
+  }
+  return null;
+}
+function objectLiteralHasTopLevelRelativeValue(objectLiteral) {
+  let depth = 0;
+  let inString = null;
+  for (let i = 0; i < objectLiteral.length; i++) {
+    const ch = objectLiteral[i] ?? "";
+    const prev = objectLiteral[i - 1] ?? "";
+    if (inString) {
+      if (ch === inString && prev !== "\\") inString = null;
+      continue;
+    }
+    if (ch === '"' || ch === "'" || ch === "`") {
+      inString = ch;
+      if (depth === 1 && /^[+-]=/.test(objectLiteral.slice(i + 1))) return true;
+      continue;
+    }
+    if (ch === "{" || ch === "(" || ch === "[") depth++;
+    else if (ch === "}" || ch === ")" || ch === "]") depth--;
+  }
+  return false;
+}
+function isInsideGsapTweenVars(source, index, timelineVars) {
+  let depth = 0;
+  for (let i = index; i >= 0; i--) {
+    const ch = source[i];
+    if (ch === "}") depth++;
+    else if (ch === "{") {
+      if (depth === 0) {
+        const before = source.slice(Math.max(0, i - 240), i).replace(/\s+/g, " ");
+        const receivers = ["gsap", ...timelineVars].map(escapeRegExp3).join("|");
+        return new RegExp(`(?:${receivers})\\.(?:set|to|from|fromTo|timeline)\\b[\\s\\S]*$`).test(
+          before
+        );
+      }
+      depth--;
+    }
+  }
+  return false;
+}
+function sliceExpression(source, start) {
+  let depth = 0;
+  for (let i = start; i < source.length; i++) {
+    const ch = source[i] ?? "";
+    if ("({[".includes(ch)) depth++;
+    else if (")}]".includes(ch)) {
+      if (depth === 0) return source.slice(start, i);
+      depth--;
+    } else if (ch === "," && depth === 0) return source.slice(start, i);
+  }
+  return source.slice(start);
+}
+function normalizeFirstParam(raw) {
+  let param = raw.trim().replace(/=.*$/, "").trim();
+  param = param.replace(/\s*:\s*[\w$|<>,\s[\].]+$/, "").trim();
+  if (!param || /^[[{]/.test(param)) return null;
+  if (!/^[A-Za-z_$][\w$]*$/.test(param)) return null;
+  return param;
+}
+function parseFunctionValueSource(code) {
+  const src = code.trim();
+  const match = src.match(/^(?:async\s+)?function\s*[\w$]*\s*\(([^)]*)\)/) ?? src.match(/^(?:async\s*)?\(([^)]*)\)\s*=>/) ?? src.match(/^(?:async\s*)?([A-Za-z_$][\w$]*)\s*=>/);
+  if (!match) return null;
+  const firstParam = normalizeFirstParam((match[1] ?? "").split(",")[0] ?? "");
+  return { firstParam, body: src.slice(match[0].length) };
+}
+function escapeRegExp3(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+var NUMBER_METHODS = /* @__PURE__ */ new Set([
+  "toFixed",
+  "toString",
+  "toPrecision",
+  "toExponential",
+  "toLocaleString",
+  "valueOf"
+]);
+function firstParamMemberAccessHazard(fn) {
+  if (!fn.firstParam) return null;
+  const pattern = new RegExp(
+    `\\b${escapeRegExp3(fn.firstParam)}\\s*\\.\\s*([A-Za-z_$][\\w$]*)`,
+    "g"
+  );
+  let match;
+  while ((match = pattern.exec(fn.body)) !== null) {
+    const member = match[1] ?? "";
+    const after = fn.body.slice(match.index + match[0].length);
+    const isCall = /^\s*\(/.test(after);
+    if (isCall && NUMBER_METHODS.has(member)) continue;
+    return member;
+  }
+  return null;
+}
+function collectTimelineVarNames(source) {
+  return [...source.matchAll(/(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*gsap\.timeline\b/g)].map((m) => m[1] ?? "").filter(Boolean);
+}
+function collectNamedFunctionBodies(source) {
+  const bodies = /* @__PURE__ */ new Map();
+  const declPattern = /(?:^|[^.\w$])function\s+([A-Za-z_$][\w$]*)\s*\(/g;
+  let match;
+  while ((match = declPattern.exec(source)) !== null) {
+    const braceIndex = source.indexOf("{", declPattern.lastIndex);
+    if (braceIndex < 0) continue;
+    const body = matchBalanced(source, braceIndex, "{", "}");
+    if (body) bodies.set(match[1] ?? "", body);
+  }
+  const assignPattern = /(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*(?:async\s*)?(?:function\b[^{]*|\([^)]*\)\s*=>\s*|[A-Za-z_$][\w$]*\s*=>\s*)/g;
+  while ((match = assignPattern.exec(source)) !== null) {
+    const bodyStart = assignPattern.lastIndex;
+    const body = source[bodyStart] === "{" ? matchBalanced(source, bodyStart, "{", "}") : sliceExpression(source, bodyStart);
+    if (body) bodies.set(match[1] ?? "", body);
+  }
+  return bodies;
+}
+function collectMeasuringFunctionNames(bodies) {
+  const measuring = /* @__PURE__ */ new Set();
+  for (const [name, body] of bodies) {
+    if (CALLBACK_MEASUREMENT_PATTERN.test(body)) measuring.add(name);
+  }
+  for (let pass = 0; pass < 3; pass++) {
+    let grew = false;
+    for (const [name, body] of bodies) {
+      if (measuring.has(name)) continue;
+      for (const measured of measuring) {
+        if (new RegExp(`\\b${escapeRegExp3(measured)}\\s*\\(`).test(body)) {
+          measuring.add(name);
+          grew = true;
+          break;
+        }
+      }
+    }
+    if (!grew) break;
+  }
+  return measuring;
+}
+function expressionReachesMeasurement(expression, measuring) {
+  if (CALLBACK_MEASUREMENT_PATTERN.test(expression)) return true;
+  for (const name of measuring) {
+    if (new RegExp(`\\b${escapeRegExp3(name)}\\b`).test(expression)) return true;
+  }
+  return false;
+}
+function resolveScriptElementTokens(source, tags) {
+  const documentIds = tags.map((tag) => readAttr(tag.raw, "id")).filter((id) => id !== null);
+  const tokensByVar = /* @__PURE__ */ new Map();
+  const add = (name, token) => {
+    const tokens = tokensByVar.get(name) ?? /* @__PURE__ */ new Set();
+    tokens.add(token);
+    tokensByVar.set(name, tokens);
+  };
+  for (const match of source.matchAll(
+    /(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*document\.getElementById\(\s*(["'])([^"'`]+)\2/g
+  )) {
+    add(match[1] ?? "", `#${match[3] ?? ""}`);
+  }
+  for (const match of source.matchAll(
+    /(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*document\.getElementById\(\s*`([^`]*)`/g
+  )) {
+    const template = match[2] ?? "";
+    const staticParts = template.split(/\$\{[^}]*\}/);
+    if (staticParts.every((part) => part === "")) continue;
+    const idPattern = new RegExp(`^${staticParts.map(escapeRegExp3).join(".*")}$`);
+    for (const id of documentIds) {
+      if (idPattern.test(id)) add(match[1] ?? "", `#${id}`);
+    }
+  }
+  for (const match of source.matchAll(
+    /(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*document\.querySelector\(\s*(["'])([^"'`]+)\2/g
+  )) {
+    for (const token of targetedSelectorTokens(match[3] ?? "")) add(match[1] ?? "", token);
+  }
+  for (const match of source.matchAll(
+    /\b([A-Za-z_$][\w$]*)\.setAttribute\(\s*(["'])class\2\s*,\s*(["'])([^"'`]*)\3/g
+  )) {
+    for (const cls of (match[4] ?? "").split(/\s+/).filter(Boolean)) add(match[1] ?? "", `.${cls}`);
+  }
+  for (const match of source.matchAll(/\b([A-Za-z_$][\w$]*)\.className\s*=\s*(["'])([^"'`]*)\2/g)) {
+    for (const cls of (match[3] ?? "").split(/\s+/).filter(Boolean)) add(match[1] ?? "", `.${cls}`);
+  }
+  return tokensByVar;
+}
+function elementLevelTokens(tokens, tagsByToken) {
+  const expanded = new Set(tokens);
+  for (const token of [...expanded]) {
+    for (const tag of tagsByToken.get(token) ?? []) {
+      for (const own of tagSimpleSelectors(tag)) expanded.add(own);
+    }
+  }
+  return expanded;
+}
+function isMultiComponentDasharray(value) {
+  const normalized = value.replace(/!important\s*$/i, "").trim();
+  if (!normalized || /^none$/i.test(normalized)) return false;
+  return normalized.split(/[\s,]+/).filter(Boolean).length >= 2;
+}
+function gsapDasharrayValueLooksMultiComponent(valueSource) {
+  const literal = valueSource.trim().match(/^(["'`])([\s\S]*)\1$/)?.[2];
+  if (literal === void 0) return false;
+  return isMultiComponentDasharray(literal.replace(/\$\{[^}]*\}/g, "0"));
+}
+function collectFunctionBodyRanges(source) {
+  const ranges = [];
+  const openerPatterns = [/\bfunction\b[^{;()]*\([^)]*\)\s*\{/g, /=>\s*\{/g];
+  for (const pattern of openerPatterns) {
+    let match;
+    while ((match = pattern.exec(source)) !== null) {
+      const braceIndex = match.index + match[0].length - 1;
+      const body = matchBalanced(source, braceIndex, "{", "}");
+      if (body) ranges.push({ start: braceIndex, end: braceIndex + body.length });
+    }
+  }
+  return ranges;
+}
+function indexInsideAnyRange(index, ranges) {
+  return ranges.some((range) => index > range.start && index < range.end);
+}
+function isIifeBody(source, range) {
+  let j = range.end;
+  while (j < source.length && /\s/.test(source[j])) j++;
+  if (source[j] !== ")") return false;
+  j++;
+  while (j < source.length && /\s/.test(source[j])) j++;
+  return source[j] === "(" || source.startsWith(".call", j) || source.startsWith(".apply", j);
+}
+function indexInsideNonIifeRange(index, source, ranges) {
+  return ranges.some(
+    (range) => index > range.start && index < range.end && !isIifeBody(source, range)
+  );
+}
+function collectCssOpacityZeroSelectors(styles, tags) {
+  const selectors = /* @__PURE__ */ new Set();
+  const opacityExactlyZero = /opacity\s*:\s*0(?:\.0+)?\s*(?:;|$)/;
+  for (const style of styles) {
+    for (const [, selector, body] of style.content.matchAll(
+      /([#.][a-zA-Z0-9_-]+)\s*\{([^}]+)\}/g
+    )) {
+      if (body && opacityExactlyZero.test(body)) {
+        selectors.add((selector ?? "").trim());
+      }
+    }
+  }
+  for (const tag of tags) {
+    const inlineStyle = readAttr(tag.raw, "style");
+    if (!inlineStyle || !opacityExactlyZero.test(inlineStyle)) continue;
+    const id = readAttr(tag.raw, "id");
+    if (id) selectors.add(`#${id}`);
+    for (const cls of readAttr(tag.raw, "class")?.split(/\s+/).filter(Boolean) ?? []) {
+      selectors.add(`.${cls}`);
+    }
+  }
+  return selectors;
+}
 var gsapRules = [
   // overlapping_gsap_tweens + gsap_animates_clip_element + unscoped_gsap_selector
   // fallow-ignore-next-line complexity
@@ -1726,7 +2089,11 @@ ${right.raw}`)
           message: `Full-frame overlay "${selector}" starts visible before its first GSAP opacity tween at ${firstVisible.position.toFixed(2)}s. It will cover earlier render frames, often as a blank/white video.`,
           selector,
           elementId: readAttr(tag.raw, "id") || void 0,
-          fixHint: `Add \`opacity: 0\` to "${selector}" in CSS/inline styles, or add \`tl.set("${selector}", { opacity: 0 }, 0)\` before the reveal tween.`,
+          // gsap_timeline_set_initial_hide warns on `tl.set(..., 0)` initial hides
+          // (a zero-duration set at 0 does not render at exactly t=0), so this hint
+          // must not recommend that pattern — advise authored CSS or an immediate
+          // gsap.set() instead, keeping the two rules' advice consistent.
+          fixHint: `Add \`opacity: 0\` to "${selector}" in CSS/inline styles, or add an immediate \`gsap.set("${selector}", { opacity: 0 })\` (outside the timeline) before the reveal tween.`,
           snippet: truncateSnippet(firstVisible.raw)
         });
       }
@@ -2015,40 +2382,39 @@ ${right.raw}`)
     }
     return findings;
   },
-  // gsap_from_opacity_noop — CSS opacity:0 + gsap.from({opacity:0}) = invisible forever
+  // CSS/GSAP-hidden reveal safety. A fromTo() whose from-vars make an element
+  // visible but whose destination omits opacity works during sequential seeks,
+  // yet cold render workers restore the authored hidden state and encode it
+  // permanently invisible.
   // fallow-ignore-next-line complexity
   async ({ styles, scripts, tags }) => {
     const findings = [];
-    const cssOpacityZeroSelectors = /* @__PURE__ */ new Set();
-    const opacityExactlyZero = /opacity\s*:\s*0(?:\.0+)?\s*(?:;|$)/;
-    for (const style of styles) {
-      for (const [, selector, body] of style.content.matchAll(
-        /([#.][a-zA-Z0-9_-]+)\s*\{([^}]+)\}/g
-      )) {
-        if (body && opacityExactlyZero.test(body)) {
-          cssOpacityZeroSelectors.add((selector ?? "").trim());
-        }
-      }
-    }
-    for (const tag of tags) {
-      const inlineStyle = readAttr(tag.raw, "style");
-      if (!inlineStyle || !opacityExactlyZero.test(inlineStyle)) continue;
-      const id = readAttr(tag.raw, "id");
-      const classes = readAttr(tag.raw, "class")?.split(/\s+/).filter(Boolean) ?? [];
-      if (id) cssOpacityZeroSelectors.add(`#${id}`);
-      for (const cls of classes) cssOpacityZeroSelectors.add(`.${cls}`);
-    }
-    if (cssOpacityZeroSelectors.size === 0) return findings;
+    const cssOpacityZeroSelectors = collectCssOpacityZeroSelectors(styles, tags);
     for (const script of scripts) {
       if (!/gsap\.timeline/.test(script.content)) continue;
       const windows = await cachedExtractGsapWindows(script.content);
+      const hiddenSelectors = /* @__PURE__ */ new Set([
+        ...cssOpacityZeroSelectors,
+        ...extractStandaloneHiddenSelectors(script.content)
+      ]);
       for (const win of windows) {
+        const sel = win.targetSelector;
+        const cssKey = sel.startsWith("#") || sel.startsWith(".") ? sel : `#${sel}`;
+        if (!hiddenSelectors.has(cssKey)) continue;
+        if (win.method === "fromTo" && win.fromPropertyValues && isVisibleGsapState(win.fromPropertyValues) && !win.properties.some((property) => property === "opacity" || property === "autoAlpha")) {
+          findings.push({
+            code: "gsap_cold_seek_hidden_fromto_missing_reveal",
+            severity: "error",
+            message: `"${sel}" starts hidden, but its gsap.fromTo() makes it visible only in the from-vars and omits opacity/autoAlpha from the destination. Cold render workers restore the hidden authored state, so the encoded element can stay invisible even when sequential snapshots look correct.`,
+            selector: sel,
+            fixHint: `Add \`opacity: 1\` (or \`autoAlpha: 1\`) to the destination vars for "${sel}" so every seek path establishes the visible end state explicitly.`,
+            snippet: truncateSnippet(win.raw)
+          });
+          continue;
+        }
         if (win.method !== "from") continue;
         if (!win.properties.includes("opacity")) continue;
         if (win.propertyValues["opacity"] !== 0) continue;
-        const sel = win.targetSelector;
-        const cssKey = sel.startsWith("#") || sel.startsWith(".") ? sel : `#${sel}`;
-        if (!cssOpacityZeroSelectors.has(cssKey)) continue;
         findings.push({
           code: "gsap_from_opacity_noop",
           severity: "error",
@@ -2085,18 +2451,7 @@ ${right.raw}`)
     const findings = [];
     const layoutSubtreeRanges = tags.filter((t) => t.name.toLowerCase() === "canvas" && /\blayoutsubtree\b/i.test(t.raw)).map((t) => ({ start: t.index, end: findTagEnd(source, t) }));
     const isHtmlInCanvas = (tag) => layoutSubtreeRanges.some((r) => tag.index > r.start && tag.index < r.end);
-    const tagsByToken = /* @__PURE__ */ new Map();
-    const addToken = (token, tag) => {
-      const list = tagsByToken.get(token);
-      if (list) list.push(tag);
-      else tagsByToken.set(token, [tag]);
-    };
-    for (const tag of tags) {
-      const id = readAttr(tag.raw, "id");
-      if (id) addToken(`#${id}`, tag);
-      for (const cls of readAttr(tag.raw, "class")?.split(/\s+/).filter(Boolean) ?? [])
-        addToken(`.${cls}`, tag);
-    }
+    const tagsByToken = indexTagsByToken(tags);
     const allTargetsHtmlInCanvas = (selector) => {
       if (layoutSubtreeRanges.length === 0) return false;
       const matched = [...targetedSelectorTokens(selector)].flatMap(
@@ -2182,6 +2537,202 @@ ${right.raw}`)
     }
     return findings;
   },
+  // gsap_relative_value_second_writer — a relative tween value ("+=..."/"-=...") on a
+  // property that another writer is still ACTIVE on when the relative tween starts.
+  // The relative tween captures its base at tween INIT, which happens on first render:
+  // the sequential path inits it mid-flight of the other writer, a cold render worker
+  // landing later inits it with the other writer's end state — the same frame then
+  // renders at two different positions (a visible snap at chunk boundaries).
+  // GSAP renders children in start-time order within a single seek pass, so a writer
+  // that completes strictly BEFORE the relative tween's start yields identical bases
+  // on every seek path and is never flagged. Single-writer relative values are
+  // seek-stable. from()/fromTo() resolve their values at build (immediateRender), so
+  // they are exempt. The position PARAMETER ("+=0.5") is not a tween value — the
+  // parser keeps it out of properties — so it can never be flagged here.
+  async ({ scripts, tags }) => {
+    const findings = [];
+    const tagsByToken = indexTagsByToken(tags);
+    for (const script of scripts) {
+      if (!/gsap\.timeline/.test(script.content)) continue;
+      const windows = await cachedExtractGsapWindows(script.content);
+      for (const win of windows) {
+        if (win.method === "from" || win.method === "fromTo") continue;
+        if (win.overwriteAuto) continue;
+        if (targetHasNoStableIdentity(win.targetSelector, win.targetIdentity)) continue;
+        const relativeProps = Object.entries(win.propertyValues).filter(([, value]) => isRelativeTweenValue(value)).map(([prop]) => prop);
+        if (relativeProps.length === 0) continue;
+        const target = { selector: win.targetSelector, identity: win.targetIdentity };
+        for (const other of windows) {
+          if (other === win) continue;
+          if (other.position > win.position || other.end <= win.position) continue;
+          const sharedProps = relativeProps.filter((prop) => other.properties.includes(prop));
+          if (sharedProps.length === 0) continue;
+          if (!targetsShareElement(
+            target,
+            { selector: other.targetSelector, identity: other.targetIdentity },
+            tagsByToken
+          )) {
+            continue;
+          }
+          const values = sharedProps.map((prop) => `${prop}: "${win.propertyValues[prop]}"`).join(", ");
+          const overlapEnd = Math.min(win.end, other.end);
+          const formatTime = (t) => Number.isFinite(t) ? `${t.toFixed(2)}s` : "\u221E";
+          findings.push({
+            code: "gsap_relative_value_second_writer",
+            severity: "error",
+            message: `Relative value(s) ${values} on "${win.targetSelector}" start while another writer for the same propert${sharedProps.length > 1 ? "ies" : "y"} is active between ${formatTime(win.position)} and ${formatTime(overlapEnd)}. Relative tweens capture their base at tween init: the sequential path inits mid-flight of the other writer, a cold render worker landing later inits with its end state \u2014 the same frame renders at two different positions (snap at chunk boundaries).`,
+            selector: win.targetSelector,
+            fixHint: `Use absolute values for ${sharedProps.join(", ")}, or a fromTo() with explicit endpoints, so every seek path resolves the same state. Single-writer relative values are safe; the conflict is the second writer.`,
+            snippet: truncateSnippet(`${win.raw}
+${other.raw}`)
+          });
+        }
+      }
+    }
+    return findings;
+  },
+  // gsap_repeat_refresh_relative_value — repeatRefresh re-resolves the tween's values
+  // on every repeat iteration, so a relative value ACCUMULATES per cycle. A cold render
+  // worker seeking non-linearly into iteration N skips the accumulation a sequential
+  // playhead performed, so workers disagree on where the element is.
+  ({ scripts }) => {
+    const findings = [];
+    for (const script of scripts) {
+      const source = stripJsComments(script.content);
+      const pattern = /repeatRefresh\s*:\s*true\b/g;
+      let match;
+      while ((match = pattern.exec(source)) !== null) {
+        const objectLiteral = enclosingObjectLiteral(source, match.index);
+        if (!objectLiteral || !objectLiteralHasTopLevelRelativeValue(objectLiteral)) continue;
+        findings.push({
+          code: "gsap_repeat_refresh_relative_value",
+          severity: "error",
+          message: '`repeatRefresh: true` combined with a relative value ("+="/"-=") accumulates per repeat iteration. A cold render worker seeking non-linearly into iteration N never performed the earlier iterations\' accumulation, so its rendered position diverges from the sequential path.',
+          fixHint: "Remove `repeatRefresh: true`, or replace the relative value with absolute endpoints (e.g. a fromTo()) so each iteration resolves to the same state on every seek path.",
+          snippet: truncateSnippet(objectLiteral)
+        });
+      }
+    }
+    return findings;
+  },
+  // gsap_function_value_hazard — function-valued tween vars re-run at tween INIT,
+  // which is seek-order-dependent. A value reading transform-SENSITIVE geometry
+  // (getBoundingClientRect/getComputedStyle/gsap.getProperty) captures whatever state
+  // the worker's own seek order produced — error. Transform-INVARIANT layout reads
+  // (offsetWidth, getTotalLength, ...) are deterministic across cold render workers
+  // unless the measured layout itself animates — warning. GSAP function values receive
+  // (index, target, targets) — index is a NUMBER, so a method call on the first
+  // parameter (assuming it is the element) throws at init — error. Pure-index
+  // arithmetic, gsap.utils.wrap/distribute, and closures over constants are statically
+  // opaque or safe and are never flagged.
+  //
+  // Uses the raw parser output instead of the windows machinery: windows drop tweens
+  // with string positions ("+=0.5", labels), and position is irrelevant to whether a
+  // VALUE is hazardous.
+  async ({ scripts }) => {
+    const findings = [];
+    const parseGsapScript = await loadParseGsapScript();
+    for (const script of scripts) {
+      if (!/gsap\.timeline/.test(script.content)) continue;
+      const parsed = parseGsapScript(script.content);
+      for (const anim of parsed.animations) {
+        const raw = synthesizeWindowRaw(parsed.timelineVar, anim);
+        const entries = [
+          ...Object.entries(anim.properties),
+          ...Object.entries(anim.fromProperties ?? {})
+        ];
+        for (const [prop, value] of entries) {
+          if (typeof value !== "string" || !value.startsWith("__raw:")) continue;
+          const fn = parseFunctionValueSource(value.slice(6));
+          if (!fn) continue;
+          const readsSensitive = TRANSFORM_SENSITIVE_READ.test(fn.body);
+          const readsInvariant = TRANSFORM_INVARIANT_READ.test(fn.body);
+          const badMember = firstParamMemberAccessHazard(fn);
+          if (!readsSensitive && !readsInvariant && !badMember) continue;
+          const reason = readsSensitive ? "reads transform-sensitive geometry, so its result depends on the worker's own seek order" : badMember ? `accesses .${badMember} on its first parameter \u2014 GSAP function values receive (index, target, targets), so the first parameter is a NUMBER and this throws at tween init` : "measures layout at tween init, which is deterministic across cold render workers only while the measured layout never animates";
+          findings.push({
+            code: "gsap_function_value_hazard",
+            severity: readsSensitive || badMember ? "error" : "warning",
+            message: `Function-valued tween var for ${prop} on "${anim.targetSelector}" ${reason}. Each render worker initializes tweens independently.`,
+            selector: anim.targetSelector,
+            fixHint: badMember ? "Use the SECOND parameter for the element: (index, target) => ... \u2014 or index arithmetic like (i) => i * 20." : "Compute the value once at build time (before the timeline is registered) and pass a constant, or derive it from fixed composition coordinates.",
+            snippet: truncateSnippet(raw)
+          });
+        }
+      }
+    }
+    return findings;
+  },
+  // gsap_callback_dom_measurement — DOM measurement reachable from timeline callbacks
+  // (tl.add(fn) / tl.call(fn) / eventCallback / onStart-style vars). The capture path
+  // seeks with suppressEvents=false (core/src/adapters/gsap.ts), so callbacks re-fire
+  // on EVERY seek, including rewinds — and a cold render worker executes them against
+  // whatever DOM state its own non-linear seek order produced. Geometry measured
+  // inside a callback is therefore seek-order-dependent, and anything measured before
+  // the callback ran (e.g. a build-time getTotalLength() on a path whose `d` the
+  // callback assigns) is stale or zero. Warning, not error: gsap.getProperty-style
+  // derived-output callbacks were excluded, but the remaining reads can still be
+  // legitimate when the measured layout is static.
+  ({ scripts }) => {
+    const findings = [];
+    for (const script of scripts) {
+      const source = stripJsComments(script.content);
+      if (!/gsap\.timeline/.test(source)) continue;
+      const bodies = collectNamedFunctionBodies(source);
+      const measuring = collectMeasuringFunctionNames(bodies);
+      const callbackExpressionHazard = (expression) => {
+        const trimmed = expression.trim();
+        const inline = parseFunctionValueSource(trimmed);
+        if (inline) return expressionReachesMeasurement(inline.body, measuring);
+        if (/^[A-Za-z_$][\w$]*$/.test(trimmed)) return measuring.has(trimmed);
+        return false;
+      };
+      const report = (site, snippet) => {
+        findings.push({
+          code: "gsap_callback_dom_measurement",
+          severity: "warning",
+          message: "Timeline callback reaches DOM measurement (getBoundingClientRect/getTotalLength/getComputedStyle/...). The renderer seeks with suppressEvents=false, so callbacks re-fire on every seek \u2014 and a cold render worker runs them against whatever DOM state its own non-linear seek order produced. Measured geometry is seek-order-dependent, and values measured at build time (before the callback ran) are stale or zero.",
+          selector: truncateSnippet(site, 120),
+          fixHint: "Do all measurement and DOM setup synchronously at build time, before registering the timeline \u2014 or derive geometry from fixed composition coordinates instead of measuring.",
+          snippet: truncateSnippet(snippet)
+        });
+      };
+      const timelineVars = collectTimelineVarNames(source);
+      for (const timelineVar of timelineVars) {
+        const callPattern = new RegExp(
+          `\\b${escapeRegExp3(timelineVar)}\\.(?:add|call)\\s*\\(`,
+          "g"
+        );
+        let match2;
+        while ((match2 = callPattern.exec(source)) !== null) {
+          const parenIndex = match2.index + match2[0].length - 1;
+          const argsWithParens = matchBalanced(source, parenIndex, "(", ")");
+          if (!argsWithParens) continue;
+          const firstArg = sliceExpression(argsWithParens.slice(1, -1), 0);
+          const site = match2[0] + firstArg + ", ...)";
+          if (callbackExpressionHazard(firstArg)) report(site, site);
+        }
+        const eventCallbackPattern = new RegExp(
+          `\\b${escapeRegExp3(timelineVar)}\\.eventCallback\\s*\\(\\s*["']on[A-Za-z]+["']\\s*,`,
+          "g"
+        );
+        while ((match2 = eventCallbackPattern.exec(source)) !== null) {
+          const expression = sliceExpression(source, eventCallbackPattern.lastIndex);
+          const site = match2[0] + expression + ")";
+          if (callbackExpressionHazard(expression)) report(site, site);
+        }
+      }
+      const varsCallbackPattern = /\bon(?:Start|Update|Complete|Repeat|ReverseComplete|Interrupt|Overwrite)\s*:\s*/g;
+      let match;
+      while ((match = varsCallbackPattern.exec(source)) !== null) {
+        if (!isInsideGsapTweenVars(source, match.index, timelineVars)) continue;
+        const expression = sliceExpression(source, varsCallbackPattern.lastIndex);
+        const site = match[0] + expression;
+        if (callbackExpressionHazard(expression)) report(site, site);
+      }
+    }
+    return findings;
+  },
   // gsap_group_selector_keyframes
   ({ scripts }) => {
     const findings = [];
@@ -2202,6 +2753,204 @@ ${right.raw}`)
       });
     }
     return findings;
+  },
+  // svg_drawon_css_dasharray_conflict — GSAP sets/tweens strokeDasharray on an element
+  // whose CSS declares a MULTI-component stroke-dasharray (e.g. `10 10`). GSAP merges
+  // dash lists per component, so `strokeDasharray: 641.4` over CSS `10 10` computes to
+  // "641.4px, 10px" — the gap stays 10px and the hide-then-draw-on trick silently
+  // fails: the line is visible the whole scene. A static two-component GSAP value is
+  // the explicit fix form and is not flagged.
+  // fallow-ignore-next-line complexity
+  ({ scripts, styles, tags }) => {
+    const findings = [];
+    const tagsByToken = indexTagsByToken(tags);
+    const multiDashTokens = /* @__PURE__ */ new Set();
+    for (const style of styles) {
+      for (const [, selectorList, body] of style.content.matchAll(/([^{}]+)\{([^}]+)\}/g)) {
+        if (!selectorList || !body) continue;
+        const value = readStyleProperty(body, "stroke-dasharray");
+        if (!value || !isMultiComponentDasharray(value)) continue;
+        for (const group of selectorList.split(",")) {
+          const trimmed = group.trim();
+          if (!trimmed || /[\s>+~]/.test(trimmed)) continue;
+          for (const token of targetedSelectorTokens(trimmed)) multiDashTokens.add(token);
+        }
+      }
+    }
+    for (const tag of tags) {
+      const inlineValue = readStyleProperty(readAttr(tag.raw, "style") ?? "", "stroke-dasharray");
+      if (!inlineValue || !isMultiComponentDasharray(inlineValue)) continue;
+      for (const token of tagSimpleSelectors(tag)) multiDashTokens.add(token);
+    }
+    if (multiDashTokens.size === 0) return findings;
+    for (const script of scripts) {
+      const source = stripJsComments(script.content);
+      const varTokens = resolveScriptElementTokens(source, tags);
+      const reported = /* @__PURE__ */ new Set();
+      const writerPattern = /\b[\w$]+\.(set|to|fromTo)\s*\(\s*(?:(["'])([^"'`]+)\2|([A-Za-z_$][\w$]*))\s*,\s*\{/g;
+      let match;
+      while ((match = writerPattern.exec(source)) !== null) {
+        const method = match[1] ?? "";
+        const braceIndex = match.index + match[0].length - 1;
+        const firstVars = matchBalanced(source, braceIndex, "{", "}");
+        if (!firstVars) continue;
+        const varsObjects = [firstVars];
+        if (method === "fromTo") {
+          const afterFirst = source.slice(braceIndex + firstVars.length);
+          const secondOpen = /^\s*,\s*\{/.exec(afterFirst);
+          if (secondOpen) {
+            const secondBrace = braceIndex + firstVars.length + secondOpen[0].length - 1;
+            const secondVars = matchBalanced(source, secondBrace, "{", "}");
+            if (secondVars) varsObjects.push(secondVars);
+          }
+        }
+        const quotedSelector = match[3];
+        const targetTokens = quotedSelector ? targetedSelectorTokens(quotedSelector) : varTokens.get(match[4] ?? "") ?? /* @__PURE__ */ new Set();
+        if (targetTokens.size === 0) continue;
+        const expanded = elementLevelTokens(targetTokens, tagsByToken);
+        for (const varsObject of varsObjects) {
+          const propMatch = varsObject.match(/\bstrokeDasharray\s*:\s*/) ?? varsObject.match(/["']stroke-dasharray["']\s*:\s*/);
+          if (!propMatch || propMatch.index === void 0) continue;
+          const valueSource = sliceExpression(varsObject, propMatch.index + propMatch[0].length);
+          if (gsapDasharrayValueLooksMultiComponent(valueSource)) continue;
+          const conflictToken = [...expanded].find((token) => multiDashTokens.has(token));
+          if (!conflictToken) continue;
+          const targetLabel = quotedSelector ?? match[4] ?? "";
+          if (reported.has(targetLabel + conflictToken)) continue;
+          reported.add(targetLabel + conflictToken);
+          findings.push({
+            code: "svg_drawon_css_dasharray_conflict",
+            severity: "error",
+            message: `GSAP writes strokeDasharray on "${targetLabel}", but its CSS ("${conflictToken}") declares a multi-component stroke-dasharray. GSAP merges dash lists per component, so the CSS gap survives (e.g. "641.4px, 10px") \u2014 the draw-on hide only hides one gap's worth and the line stays visible the whole scene.`,
+            selector: quotedSelector ?? void 0,
+            fixHint: `Remove the CSS stroke-dasharray from "${conflictToken}" (decorative dashes belong on a separate element), or set the full two-component value in GSAP: strokeDasharray: "\${len} \${len}".`,
+            snippet: truncateSnippet(match[0] + firstVars.slice(1))
+          });
+        }
+      }
+    }
+    return findings;
+  },
+  // gsap_timeline_set_initial_hide — a zero-duration tl.set(...) at position 0 inside
+  // the paused timeline does NOT render while the playhead sits exactly at 0 (verified
+  // against this repo's GSAP: tl.time(0) leaves the target untouched; only a seek past
+  // 0 applies it). Frame 0 therefore shows the UN-hidden state, then the element pops
+  // hidden on frame 1 — and only for the worker that renders frame 0. Targets already
+  // hidden by authored CSS/inline styles or by a standalone gsap.set are exempt: the
+  // tl.set is then a defensive re-assertion and frame 0 is hidden anyway.
+  //
+  // Only sets that precede every tween in source order qualify: the parser resolves a
+  // mutated position variable (`var t = 0; ...; tl.set(sel, vars, t)`) to its INITIAL
+  // binding, so late hard-kills can masquerade as position-0 sets. Genuine
+  // initial-state hides are authored before the timeline's tweens.
+  async ({ scripts, styles, tags }) => {
+    const findings = [];
+    const cssHiddenSelectors = collectCssOpacityZeroSelectors(styles, tags);
+    const tagsByToken = indexTagsByToken(tags);
+    for (const script of scripts) {
+      if (!/gsap\.timeline/.test(script.content)) continue;
+      const windows = await cachedExtractGsapWindows(script.content);
+      const alreadyHidden = /* @__PURE__ */ new Set([
+        ...cssHiddenSelectors,
+        ...extractStandaloneHiddenSelectors(script.content)
+      ]);
+      const isInstantHold = (win) => win.method === "set" || (win.method === "to" || win.method === "fromTo") && win.end === win.position;
+      const firstTweenIndex = windows.findIndex((win) => !isInstantHold(win));
+      const initialHolds = firstTweenIndex < 0 ? windows : windows.slice(0, firstTweenIndex);
+      for (const win of initialHolds) {
+        if (!isInstantHold(win) || win.position !== 0) continue;
+        if (win.global || win.immediateRender) continue;
+        if (targetHasNoStableIdentity(win.targetSelector, win.targetIdentity)) continue;
+        const targetTokens = [...targetedSelectorTokens(win.targetSelector)];
+        const hiddenByToken = targetTokens.length > 0 && targetTokens.every((token) => alreadyHidden.has(token));
+        const resolvedTags = targetTokens.flatMap((token) => tagsByToken.get(token) ?? []);
+        const hiddenByElement = resolvedTags.length > 0 && resolvedTags.every(
+          (tag) => tagSimpleSelectors(tag).some((token) => alreadyHidden.has(token))
+        );
+        if (hiddenByToken || hiddenByElement) continue;
+        const offset = win.propertyValues["strokeDashoffset"];
+        const hidesByOffset = numberValue(offset) !== null && !zeroValue(offset);
+        const hides = isHiddenGsapState(win.propertyValues) || zeroValue(win.propertyValues["scale"]) || hidesByOffset;
+        if (!hides) continue;
+        findings.push({
+          code: "gsap_timeline_set_initial_hide",
+          severity: "warning",
+          message: `Initial hidden state for "${win.targetSelector}" is set via tl.set(...) at position 0 inside the paused timeline. A zero-duration set at 0 does not render while the playhead sits exactly at 0, so frame 0 shows the un-hidden state.`,
+          selector: win.targetSelector,
+          fixHint: "Use gsap.set(...) (immediate, outside the timeline) for initial states, or author the hidden state directly in CSS/attributes.",
+          snippet: truncateSnippet(win.raw)
+        });
+      }
+    }
+    return findings;
+  },
+  // svg_measure_before_path_d — getTotalLength() on a <path> that has no static `d`
+  // attribute in the HTML. In Chrome getTotalLength() on a d-less path returns 0,
+  // silently killing dash animations (offset 0 == length 0 == nothing to draw). If a
+  // d assignment exists but only inside a function body, execution order is statically
+  // undecidable — WARNING; if NO d assignment exists anywhere — ERROR. Element
+  // identity is resolved conservatively (literal / template getElementById,
+  // querySelector); createElementNS-built paths and unresolved variables are skipped.
+  // fallow-ignore-next-line complexity
+  ({ scripts, styles, tags }) => {
+    const findings = [];
+    const tagsByToken = indexTagsByToken(tags);
+    const cssProvidesD = styles.some((style) => /\bd\s*:\s*path\(/.test(style.content));
+    for (const script of scripts) {
+      const source = stripJsComments(script.content);
+      const varTokens = resolveScriptElementTokens(source, tags);
+      const functionRanges = collectFunctionBodyRanges(source);
+      const createdVars = new Set(
+        [...source.matchAll(/([A-Za-z_$][\w$]*)\s*=\s*document\.createElementNS\(/g)].map(
+          (m) => m[1] ?? ""
+        )
+      );
+      const dAssignments = [
+        ...[...source.matchAll(/\b([A-Za-z_$][\w$]*)\.setAttribute\(\s*["']d["']\s*,/g)].map(
+          (m) => ({ varName: m[1] ?? "", index: m.index ?? 0 })
+        ),
+        ...[
+          ...source.matchAll(
+            /\.(?:set|to|fromTo)\s*\(\s*([A-Za-z_$][\w$]*)\s*,\s*\{[^{}]*\battr\s*:\s*\{[^{}]*\bd\s*:/g
+          )
+        ].map((m) => ({ varName: m[1] ?? "", index: m.index ?? 0 }))
+      ];
+      const reported = /* @__PURE__ */ new Set();
+      const measurePattern = /\b([A-Za-z_$][\w$]*)\.getTotalLength\s*\(/g;
+      let match;
+      while ((match = measurePattern.exec(source)) !== null) {
+        const varName = match[1] ?? "";
+        if (createdVars.has(varName)) continue;
+        const tokens = varTokens.get(varName);
+        if (!tokens || tokens.size === 0) continue;
+        const resolvedTags = [...tokens].flatMap((token) => tagsByToken.get(token) ?? []);
+        const dLessPaths = resolvedTags.filter(
+          (tag) => tag.name.toLowerCase() === "path" && readAttr(tag.raw, "d") === null
+        );
+        if (dLessPaths.length === 0 || dLessPaths.length !== resolvedTags.length) continue;
+        if (cssProvidesD) continue;
+        const measureIndex = match.index;
+        const assignedBeforeInScope = dAssignments.some(
+          (assign) => assign.varName === varName && assign.index < measureIndex && (!indexInsideAnyRange(assign.index, functionRanges) || functionRanges.some(
+            (range) => assign.index > range.start && assign.index < range.end && measureIndex > range.start && measureIndex < range.end
+          ))
+        );
+        if (assignedBeforeInScope) continue;
+        const sameVarAssignmentExists = dAssignments.some((a) => a.varName === varName);
+        const tokenLabel = [...tokens].join(", ");
+        if (reported.has(tokenLabel)) continue;
+        reported.add(tokenLabel);
+        findings.push({
+          code: "svg_measure_before_path_d",
+          severity: sameVarAssignmentExists ? "warning" : "error",
+          message: sameVarAssignmentExists ? `getTotalLength() is called on "${tokenLabel}", whose \`d\` is only assigned inside a function body \u2014 if the measure runs before that function (e.g. the function is a timeline callback), the length is 0 and the dash animation is dead.` : `getTotalLength() is called on "${tokenLabel}", but the path has no static \`d\` attribute and no d assignment exists anywhere \u2014 getTotalLength() returns 0 in Chrome, silently killing dash animations.`,
+          selector: tokenLabel,
+          fixHint: "Assign the path's `d` synchronously at build time (top level, before measuring), or author a static d attribute in the HTML.",
+          snippet: truncateSnippet(match[0] + ")")
+        });
+      }
+    }
+    return findings;
   }
 ];
 
@@ -2417,11 +3166,36 @@ var captionRules = [
 
 // src/rules/composition.ts
 import { COMPOSITION_VARIABLE_TYPES } from "@hyperframes/parsers/composition";
+import { COMPOSITION_ATTRIBUTES, readClipTiming } from "@hyperframes/parsers/composition-contract";
 var MAX_COMPOSITION_LINES = 300;
 var MAX_TIMED_ELEMENTS_PER_TRACK = 3;
 var TRACK_DENSITY_EXEMPT_TAGS = /* @__PURE__ */ new Set(["audio", "script", "style", "video"]);
 var CAPTION_CUE_TOKEN = /^(?:caption(?:[-_](?:group|word|line|block|cue|text))?|subtitle(?:[-_](?:group|line|cue|text))?|cg-.+)$/i;
+var HEAVY_OVERLAY_ELEMENT_COUNT_WARN = 25;
+var HEAVY_OVERLAY_EXEMPT_TAGS = /* @__PURE__ */ new Set([
+  "audio",
+  "body",
+  "br",
+  "defs",
+  "head",
+  "hr",
+  "html",
+  "link",
+  "meta",
+  "script",
+  "source",
+  "style",
+  "template",
+  "title",
+  "use",
+  "video"
+]);
+var HEAVY_OVERLAY_CSS_PATTERN = /(?:filter\s*:[^;}]*\bblur\s*\()|(?:clip-path\s*:(?!\s*(?:none|inherit|initial|unset)\b)\s*[^;}]+)|(?:radial-gradient\s*\()/i;
+var INLINE_STYLE_DISPLAY_NONE_PATTERN = /(?:^|;)\s*display\s*:\s*none\b/i;
 var OVERLAP_EPSILON_SECONDS = 1e-6;
+function readTagTiming(rawTag) {
+  return readClipTiming({ getAttribute: (name) => readAttr(rawTag, name) });
+}
 function countPhysicalLines(source) {
   if (source.length === 0) return 0;
   const normalized = source.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
@@ -2479,6 +3253,33 @@ function leftmostCompoundClasses(selector) {
   const leftmost = selector.trim().split(/[\s>+~]+/)[0] ?? "";
   return (leftmost.match(/\.([\w-]+)/g) ?? []).map((c) => c.slice(1));
 }
+function leftmostCompoundId(selector) {
+  const leftmost = selector.trim().split(/[\s>+~]+/)[0] ?? "";
+  return leftmost.match(/#([\w-]+)/)?.[1] ?? null;
+}
+function collectHeavyOverlayHooks(styles) {
+  const classes = /* @__PURE__ */ new Set();
+  const ids = /* @__PURE__ */ new Set();
+  for (const style of styles) {
+    const noComments = style.content.replace(/\/\*[\s\S]*?\*\//g, "");
+    const ruleWithBody = /([^{}]+)\{([^{}]*)\}/g;
+    let m;
+    while ((m = ruleWithBody.exec(noComments)) !== null) {
+      const header = (m[1] ?? "").trim();
+      const body = m[2] ?? "";
+      if (!header || header.startsWith("@")) continue;
+      if (!HEAVY_OVERLAY_CSS_PATTERN.test(body)) continue;
+      for (const sel of header.split(",")) {
+        const trimmed = sel.trim();
+        if (!trimmed) continue;
+        for (const cls of leftmostCompoundClasses(trimmed)) classes.add(cls);
+        const idToken = leftmostCompoundId(trimmed);
+        if (idToken) ids.add(idToken);
+      }
+    }
+  }
+  return { classes, ids };
+}
 function rootClassStyledSelectors(styles, rootClasses) {
   const offenders = [];
   for (const style of styles) {
@@ -2629,7 +3430,7 @@ var compositionRules = [
       if (isCaptionCue(tag)) continue;
       if (isCompositionRootOrMount(tag.raw)) continue;
       if (!readAttr(tag.raw, "data-start")) continue;
-      const track = readAttr(tag.raw, "data-track-index");
+      const track = readAttr(tag.raw, COMPOSITION_ATTRIBUTES.trackIndex);
       if (!track) continue;
       trackCounts.set(track, (trackCounts.get(track) ?? 0) + 1);
     }
@@ -2678,7 +3479,8 @@ var compositionRules = [
   ({ tags }) => {
     const findings = [];
     for (const tag of tags) {
-      if (readAttr(tag.raw, "data-layer") && !readAttr(tag.raw, "data-track-index")) {
+      const timing = readTagTiming(tag.raw);
+      if (timing.diagnostics.some(({ code }) => code === "deprecated-layer")) {
         const elementId = readAttr(tag.raw, "id") || void 0;
         findings.push({
           code: "deprecated_data_layer",
@@ -2689,7 +3491,7 @@ var compositionRules = [
           snippet: truncateSnippet(tag.raw)
         });
       }
-      if (readAttr(tag.raw, "data-end") && !readAttr(tag.raw, "data-duration")) {
+      if (timing.diagnostics.some(({ code }) => code === "deprecated-end")) {
         const elementId = readAttr(tag.raw, "id") || void 0;
         findings.push({
           code: "deprecated_data_end",
@@ -2779,14 +3581,12 @@ var compositionRules = [
     const findings = [];
     const trackMap = /* @__PURE__ */ new Map();
     for (const tag of tags) {
-      const startStr = readAttr(tag.raw, "data-start");
-      const durationStr = readAttr(tag.raw, "data-duration");
-      const trackStr = readAttr(tag.raw, "data-track-index");
-      if (!startStr || !durationStr || !trackStr) continue;
-      const start = Number(startStr);
-      const duration = Number(durationStr);
+      const trackStr = readAttr(tag.raw, COMPOSITION_ATTRIBUTES.trackIndex);
+      if (!trackStr) continue;
+      const timing = readTagTiming(tag.raw);
+      const { start, duration } = timing;
       const track = trackStr;
-      if (Number.isNaN(start) || Number.isNaN(duration)) continue;
+      if (start == null || duration == null) continue;
       const clips = trackMap.get(track) || [];
       clips.push({
         start,
@@ -3229,6 +4029,55 @@ ${allInlineStyles}`.replace(/\/\*[\s\S]*?\*\//g, "");
       ];
     }
     return [];
+  },
+  // composition_heavy_overlay_count_high
+  // Field signal ts=1784040753 (#hyperframes-cli-feedback): a composition
+  // with ~40 heavy overlay DOM elements — `filter:blur`, oversized
+  // `radial-gradient`, and `clip-path` animations — captures solid-black for
+  // the first ~half of the render, recovering near the end. Reproduces
+  // identically via drawElement AND forced --no-browser-gpu screenshot
+  // capture AND `snapshot`, so the offender is the capture layer itself, not
+  // encoder/mux. Independent of duration (padding the timeline grows the bad
+  // zone proportionally, doesn't shift it). Reporter's workaround was to
+  // split into per-transition mini compositions + FFmpeg concat.
+  //
+  // Presence alone matters: opacity:0 and visibility:hidden overlays still
+  // contribute to the capture-layer regression, so they're counted-in. The
+  // only escape hatch is `display: none` — an element removed from the render
+  // tree can't feed the compositor. Warn at 25, well below the observed
+  // 40-element repro, to give authors lead time before hitting the bug.
+  // fallow-ignore-next-line complexity
+  ({ tags, styles, rawSource, options }) => {
+    if (isRegistrySourceFile(options.filePath) || isRegistryInstalledFile(rawSource)) return [];
+    const { classes: heavyClassTokens, ids: heavyIds } = collectHeavyOverlayHooks(styles);
+    let heavyCount = 0;
+    for (const tag of tags) {
+      if (HEAVY_OVERLAY_EXEMPT_TAGS.has(tag.name)) continue;
+      if (isCompositionRootOrMount(tag.raw)) continue;
+      const styleAttr = readJsonAttr(tag.raw, "style") ?? "";
+      if (styleAttr && INLINE_STYLE_DISPLAY_NONE_PATTERN.test(styleAttr)) continue;
+      let heavy = false;
+      if (styleAttr && HEAVY_OVERLAY_CSS_PATTERN.test(styleAttr)) heavy = true;
+      if (!heavy && (heavyClassTokens.size > 0 || heavyIds.size > 0)) {
+        const classList = (readAttr(tag.raw, "class") || "").split(/\s+/).filter(Boolean);
+        if (classList.some((cls) => heavyClassTokens.has(cls))) heavy = true;
+        if (!heavy) {
+          const idValue = readAttr(tag.raw, "id");
+          if (idValue && heavyIds.has(idValue)) heavy = true;
+        }
+      }
+      if (heavy) heavyCount += 1;
+    }
+    if (heavyCount < HEAVY_OVERLAY_ELEMENT_COUNT_WARN) return [];
+    const splitTarget = options.isSubComposition ? "Split this sub-composition further into per-transition mini-compositions" : "Split coherent scenes / transitions into separate .html files under compositions/";
+    return [
+      {
+        code: "composition_heavy_overlay_count_high",
+        severity: "warning",
+        message: `This composition has ${heavyCount} elements carrying "heavy overlay" CSS (filter:blur, radial-gradient, or clip-path). Field signal: a composition with ~40 such elements \u2014 including opacity:0 / visibility:hidden ones \u2014 captures solid-black for the first ~half of the render, recovering near the end. Reproduces identically via drawElement, forced screenshot capture, and snapshot, so the capture layer itself is the offender (not encoder/mux). Independent of duration. Presence alone matters; only display:none elements are excluded here.`,
+        fixHint: `${splitTarget} and concat the pieces (FFmpeg or the runtime's slideshow) so each capture only sees a small subset of heavy overlays at once. Even hidden overlays (opacity:0 / visibility:hidden) contribute \u2014 either remove truly unused ones from the source or scope them into their own per-transition sub-composition. If an overlay is genuinely inert for the whole clip, use display:none so it never enters the render tree. Field ref ts=1784040753 (#hyperframes-cli-feedback).`
+      }
+    ];
   }
 ];
 
@@ -3499,7 +4348,7 @@ function extractFontFaceFamilies(styles) {
   return families;
 }
 function normalizeUsedFontName(part) {
-  const name = part.trim().replace(/^['"]|['"]$/g, "").trim().toLowerCase();
+  const name = part.trim().replace(/\s*!important\s*$/i, "").replace(/^['"]|['"]$/g, "").trim().toLowerCase();
   if (!name || name.includes("(") || name.includes(")")) return null;
   return name;
 }
@@ -3815,11 +4664,118 @@ function shouldBlockRender(strictErrors, strictAll, totalErrors, totalWarnings)
 
 // src/project.ts
 import { existsSync, readFileSync, readdirSync } from "fs";
-import { dirname, extname, isAbsolute, join, posix, relative, resolve } from "path";
-import { decodeUrlPathVariants } from "@hyperframes/parsers/composition";
-import { rewriteAssetPath } from "@hyperframes/parsers/asset-paths";
+import { dirname, extname, join, relative, resolve } from "path";
+import { rewriteAssetPath as rewriteAssetPath2 } from "@hyperframes/parsers/asset-paths";
 import { checkSubCompositionUsability } from "@hyperframes/parsers/sub-composition-validity";
 import { parseHTML } from "linkedom";
+import {
+  cleanAssetUrl as cleanAssetUrl2,
+  isRemoteOrInlineUrl as isRemoteOrInlineUrl2,
+  isWithinProjectRoot,
+  maskNonScannableRanges as maskNonScannableRanges2,
+  resolveExistingLocalAsset as resolveExistingLocalAsset2,
+  resolveLocalAssetCandidates
+} from "@hyperframes/parsers/asset-resolution";
+
+// src/hevcPreviewLint.ts
+import { execFile } from "child_process";
+import { rewriteAssetPath } from "@hyperframes/parsers/asset-paths";
+import { findFfBinary } from "@hyperframes/parsers/ff-binaries";
+import {
+  cleanAssetUrl,
+  isRemoteOrInlineUrl,
+  maskNonScannableRanges,
+  resolveExistingLocalAsset
+} from "@hyperframes/parsers/asset-resolution";
+var PROBE_TIMEOUT_MS = 4e3;
+var PROBE_CONCURRENCY = 8;
+function execFileAsync(file, args) {
+  return new Promise((resolvePromise, reject) => {
+    execFile(file, args, { timeout: PROBE_TIMEOUT_MS }, (error, stdout) => {
+      if (error) reject(error);
+      else resolvePromise(stdout.toString());
+    });
+  });
+}
+function hasHevcStream(json) {
+  if (typeof json !== "object" || json === null) return false;
+  const streams = Reflect.get(json, "streams");
+  if (!Array.isArray(streams)) return false;
+  return streams.some((stream) => {
+    if (typeof stream !== "object" || stream === null) return false;
+    return Reflect.get(stream, "codec_name") === "hevc";
+  });
+}
+async function probeIsHevc(ffprobePath, filePath) {
+  try {
+    const stdout = await execFileAsync(ffprobePath, [
+      "-v",
+      "error",
+      "-select_streams",
+      "v:0",
+      "-show_entries",
+      "stream=codec_name",
+      "-of",
+      "json",
+      filePath
+    ]);
+    return hasHevcStream(JSON.parse(stdout));
+  } catch {
+    return false;
+  }
+}
+function collectLocalVideoCandidates(projectDir, htmlSources) {
+  const candidates = /* @__PURE__ */ new Map();
+  const videoSrcRe = /<video\b[^>]*\bsrc\s*=\s*["']([^"']+)["'][^>]*>/gi;
+  for (const { html, compSrcPath } of htmlSources) {
+    const scannable = maskNonScannableRanges(html);
+    const re = new RegExp(videoSrcRe.source, videoSrcRe.flags);
+    let match;
+    while ((match = re.exec(scannable)) !== null) {
+      const src = cleanAssetUrl(match[1] ?? "");
+      if (!src) continue;
+      if (isRemoteOrInlineUrl(src)) continue;
+      if (/^__[A-Z_]+__$/.test(src)) continue;
+      const rootRelative = compSrcPath ? rewriteAssetPath(compSrcPath, src) : src;
+      const resolvedAsset = resolveExistingLocalAsset(projectDir, rootRelative);
+      if (!resolvedAsset) continue;
+      if (!candidates.has(resolvedAsset.resolved)) candidates.set(resolvedAsset.resolved, src);
+    }
+  }
+  return candidates;
+}
+async function lintHevcPreviewCodec(candidates) {
+  if (candidates.size === 0) return [];
+  const ffprobePath = findFfBinary("ffprobe", { configuredMustExist: true });
+  if (!ffprobePath) return [];
+  const entries = [...candidates.entries()];
+  const isHevc = new Array(entries.length).fill(false);
+  let nextIndex = 0;
+  const workerCount = Math.min(PROBE_CONCURRENCY, entries.length);
+  await Promise.all(
+    Array.from({ length: workerCount }, async () => {
+      while (nextIndex < entries.length) {
+        const index = nextIndex++;
+        const entry = entries[index];
+        if (!entry) break;
+        isHevc[index] = await probeIsHevc(ffprobePath, entry[0]);
+      }
+    })
+  );
+  const hevcSrcs = entries.filter((_, i) => isHevc[i]).map(([, src]) => src);
+  if (hevcSrcs.length === 0) return [];
+  const unique = [...new Set(hevcSrcs)];
+  return [
+    {
+      code: "hevc_preview_codec",
+      severity: "info",
+      message: `Video file(s) use the HEVC/H.265 codec: ${unique.join(", ")}. The render pipeline pre-decodes video with FFmpeg and never uses the browser's video decoder, so these render correctly. Live preview/player playback automatically uses a cached H.264 proxy when the browser cannot decode HEVC. If playback still fails, verify ffmpeg/ffprobe are installed and auto-proxying is enabled.`,
+      fixHint: unique.length === 1 ? `If "${unique[0]}" fails to play in preview, run hyperframes doctor and confirm media.autoProxy is not false.` : "If these files fail to play in preview, run hyperframes doctor and confirm media.autoProxy is not false."
+    }
+  ];
+}
+
+// src/project.ts
 function parseSubCompHtml(html) {
   return parseHTML(html).document;
 }
@@ -3844,7 +4800,7 @@ function collectLocalStylesheets(projectDir, document, compSrcPath) {
     const href = link.getAttribute("href") ?? "";
     if (!isLocalStylesheetHref(href)) continue;
     const rootRelative = compSrcPath ? join(dirname(compSrcPath), href) : href;
-    const stylesheet = resolveExistingLocalAsset(projectDir, rootRelative);
+    const stylesheet = resolveExistingLocalAsset2(projectDir, rootRelative);
     if (!stylesheet) continue;
     styles.push({
       href,
@@ -3882,52 +4838,13 @@ function collectCssSources(projectDir, html, compSrcPath) {
   }
   return sources;
 }
-function isRemoteOrInlineUrl(url) {
-  return /^(https?:|data:|blob:|\/\/|#)/i.test(url);
-}
-function cleanAssetUrl(url) {
-  return url.trim().split(/[?#]/, 1)[0] ?? "";
-}
-function isWithinProjectRoot(projectDir, candidate) {
-  const projectRoot = resolve(projectDir);
-  const relativePath = relative(projectRoot, candidate);
-  return relativePath === "" || !relativePath.startsWith("..") && !isAbsolute(relativePath);
-}
-function addCandidate(candidates, candidate) {
-  if (!candidates.includes(candidate)) candidates.push(candidate);
-}
-function resolveLocalAssetCandidates(projectDir, url) {
-  const cleanUrl = cleanAssetUrl(url);
-  const projectRoot = resolve(projectDir);
-  const candidates = [];
-  for (const variant of decodeUrlPathVariants(cleanUrl)) {
-    const projectRelative = variant.startsWith("/") ? variant.slice(1) : variant;
-    const resolved = resolve(projectRoot, projectRelative);
-    if (isWithinProjectRoot(projectRoot, resolved)) {
-      addCandidate(candidates, resolved);
-      continue;
-    }
-    const normalized = posix.normalize(projectRelative.replace(/\\/g, "/"));
-    const clamped = normalized.replace(/^(\.\.\/)+/, "");
-    if (clamped && !clamped.startsWith("..")) {
-      addCandidate(candidates, resolve(projectRoot, clamped));
-    }
-  }
-  return candidates;
-}
-function resolveExistingLocalAsset(projectDir, url) {
-  const projectRoot = resolve(projectDir);
-  const resolved = resolveLocalAssetCandidates(projectRoot, url).find(existsSync);
-  if (!resolved) return null;
-  return { resolved, rootRelativePath: relative(projectRoot, resolved) };
-}
 function resolveCssAssetCandidates(projectDir, url, htmlCompSrcPath, cssRootRelativePath) {
   if (url.startsWith("/")) return resolveLocalAssetCandidates(projectDir, url);
   if (cssRootRelativePath) {
     return resolveLocalAssetCandidates(projectDir, join(dirname(cssRootRelativePath), url));
   }
   if (htmlCompSrcPath) {
-    return resolveLocalAssetCandidates(projectDir, rewriteAssetPath(htmlCompSrcPath, url));
+    return resolveLocalAssetCandidates(projectDir, rewriteAssetPath2(htmlCompSrcPath, url));
   }
   return resolveLocalAssetCandidates(projectDir, url);
 }
@@ -3992,7 +4909,8 @@ async function lintProject(projectDir, entryFile) {
     ...lintTextureMaskAssetNotFound(projectDir, allHtmlSources),
     ...!entryFile ? lintMultipleRootCompositions(projectDir) : [],
     ...lintDuplicateAudioTracks(allHtmlSources),
-    ...lintMissingOrEmptySubComposition(projectDir, rootHtml)
+    ...lintMissingOrEmptySubComposition(projectDir, rootHtml),
+    ...await lintHevcPreviewCodec(collectLocalVideoCandidates(projectDir, allHtmlSources))
   ];
   if (projectFindings.length > 0) {
     for (const finding of projectFindings) {
@@ -4044,7 +4962,7 @@ function lintAudioSrcNotFound(projectDir, htmlSources) {
       const src = match[1];
       if (/^(https?:|data:|blob:)/i.test(src)) continue;
       if (/^__[A-Z_]+__$/.test(src)) continue;
-      const rootRelative = compSrcPath ? rewriteAssetPath(compSrcPath, src) : src;
+      const rootRelative = compSrcPath ? rewriteAssetPath2(compSrcPath, src) : src;
       if (!resolveLocalAssetCandidates(projectDir, rootRelative).some(existsSync)) {
         missingSrcs.push(src);
       }
@@ -4061,32 +4979,23 @@ function lintAudioSrcNotFound(projectDir, htmlSources) {
   }
   return findings;
 }
-function maskRange(src, pattern) {
-  return src.replace(pattern, (m) => " ".repeat(m.length));
-}
-function maskNonScannableRanges(html) {
-  let out = maskRange(html, /<!--[\s\S]*?-->/g);
-  out = maskRange(out, /<style\b[^>]*>[\s\S]*?<\/style\b[^>]*>/gi);
-  out = maskRange(out, /<script\b[^>]*>[\s\S]*?<\/script\b[^>]*>/gi);
-  return out;
-}
 function lintMissingLocalAsset(projectDir, htmlSources) {
   const findings = [];
   const localAssetSrcRe = /<(video|img|source)\b[^>]*\bsrc\s*=\s*["']([^"']+)["'][^>]*>/gi;
   const missingByTag = /* @__PURE__ */ new Map();
   for (const { html, compSrcPath } of htmlSources) {
-    const scannable = maskNonScannableRanges(html);
+    const scannable = maskNonScannableRanges2(html);
     const re = new RegExp(localAssetSrcRe.source, localAssetSrcRe.flags);
     let match;
     while ((match = re.exec(scannable)) !== null) {
       const tagName = (match[1] ?? "").toLowerCase();
       const rawSrc = match[2] ?? "";
-      const src = cleanAssetUrl(rawSrc);
+      const src = cleanAssetUrl2(rawSrc);
       if (!src) continue;
-      if (isRemoteOrInlineUrl(src)) continue;
+      if (isRemoteOrInlineUrl2(src)) continue;
       if (/^__[A-Z_]+__$/.test(src)) continue;
-      const rootRelative = compSrcPath ? rewriteAssetPath(compSrcPath, src) : src;
-      const resolvedAsset = resolveExistingLocalAsset(projectDir, rootRelative);
+      const rootRelative = compSrcPath ? rewriteAssetPath2(compSrcPath, src) : src;
+      const resolvedAsset = resolveExistingLocalAsset2(projectDir, rootRelative);
       if (resolvedAsset) continue;
       const resolvedKey = resolve(projectDir, rootRelative);
       let bucket = missingByTag.get(tagName);
@@ -4116,8 +5025,8 @@ function lintTextureMaskAssetNotFound(projectDir, htmlSources) {
       const pattern = new RegExp(MASK_IMAGE_URL_RE.source, MASK_IMAGE_URL_RE.flags);
       while ((match = pattern.exec(cssSource.content)) !== null) {
         const rawUrl = match[1] ?? match[2] ?? match[3] ?? "";
-        const url = cleanAssetUrl(rawUrl);
-        if (!url || isRemoteOrInlineUrl(url)) continue;
+        const url = cleanAssetUrl2(rawUrl);
+        if (!url || isRemoteOrInlineUrl2(url)) continue;
         if (/^__[A-Z_]+__$/.test(url)) continue;
         const candidates = resolveCssAssetCandidates(
           projectDir,
@@ -4217,7 +5126,7 @@ function lintMissingOrEmptySubComposition(projectDir, rootHtml) {
   const visited = /* @__PURE__ */ new Set();
   const walk = (html) => {
     const compositionSrcRe = /<[^>]*\bdata-composition-src\s*=\s*["']([^"']+)["'][^>]*>/gi;
-    const scannable = maskNonScannableRanges(html);
+    const scannable = maskNonScannableRanges2(html);
     let match;
     while ((match = compositionSrcRe.exec(scannable)) !== null) {
       const srcPath = (match[1] ?? "").trim();