@hyperframes/lint 0.7.58 → 0.7.60

package/dist/index.js

@@ -57,7 +57,7 @@ function findHtmlTag(tags) {
 function findRootTag(source, parsedTags) {
   const tags = parsedTags ?? parseHtmlStructure(source).tags;
   const bodyTag = tags.find((tag) => tag.name === "body");
-  if (bodyTag && (readAttr(bodyTag.raw, "data-composition-id") || readAttr(bodyTag.raw, "data-width") || readAttr(bodyTag.raw, "data-height"))) {
+  if (bodyTag && (readDecodedAttr(bodyTag.raw, "data-composition-id") || readAttr(bodyTag.raw, "data-width") || readAttr(bodyTag.raw, "data-height"))) {
     return bodyTag;
   }
   const bodyStart = bodyTag ? bodyTag.index + bodyTag.raw.length : 0;
@@ -67,7 +67,7 @@ function findRootTag(source, parsedTags) {
   for (const tag of bodyTags) {
     if (tag.index < skipBefore) continue;
     if (["script", "style", "meta", "link", "title"].includes(tag.name)) continue;
-    if (tag.name === "svg" && !readAttr(tag.raw, "data-composition-id") && !readAttr(tag.raw, "data-width") && !readAttr(tag.raw, "data-height")) {
+    if (tag.name === "svg" && !readDecodedAttr(tag.raw, "data-composition-id") && !readAttr(tag.raw, "data-width") && !readAttr(tag.raw, "data-height")) {
       skipBefore = tag.endIndex ?? Infinity;
       continue;
     }
@@ -81,6 +81,20 @@ function readAttr(tagSource, attr) {
   const match = tagSource.match(new RegExp(`(?<![\\w-])${escaped}\\s*=\\s*["']([^"']+)["']`, "i"));
   return match?.[1] || null;
 }
+function readDecodedAttr(tagSource, attr) {
+  if (!tagSource) return null;
+  let value = null;
+  const parser = new Parser(
+    {
+      onattribute(name, decodedValue) {
+        if (value === null && name.toLowerCase() === attr.toLowerCase()) value = decodedValue;
+      }
+    },
+    { decodeEntities: true, lowerCaseAttributeNames: false, lowerCaseTags: true }
+  );
+  parser.end(tagSource);
+  return value;
+}
 function readJsonAttr(tagSource, attr) {
   if (!tagSource) return null;
   const escaped = attr.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
@@ -93,7 +107,7 @@ function readJsonAttr(tagSource, attr) {
 function collectCompositionIds(tags) {
   const ids = /* @__PURE__ */ new Set();
   for (const tag of tags) {
-    const compId = readAttr(tag.raw, "data-composition-id");
+    const compId = readDecodedAttr(tag.raw, "data-composition-id");
     if (compId) ids.add(compId);
   }
   return ids;
@@ -270,7 +284,7 @@ function buildLintContext(html, options = {}) {
   const scripts = structure.scripts;
   const compositionIds = collectCompositionIds(tags);
   const rootTag = findRootTag(source, tags);
-  const rootCompositionId = readAttr(rootTag?.raw || "", "data-composition-id");
+  const rootCompositionId = readDecodedAttr(rootTag?.raw || "", "data-composition-id");
   return {
     source,
     rawSource,
@@ -306,7 +320,7 @@ function isStudioTimelineElement(tag) {
 function describeStudioElement(tag) {
   const parts = [`<${tag.name}`];
   const className = readAttr(tag.raw, "class");
-  const compositionId = readAttr(tag.raw, "data-composition-id");
+  const compositionId = readDecodedAttr(tag.raw, "data-composition-id");
   const dataStart = readAttr(tag.raw, "data-start");
   const dataTrack = readAttr(tag.raw, "data-track-index") ?? readAttr(tag.raw, "data-track");
   if (className) {
@@ -428,7 +442,7 @@ var coreRules = [
   // root_missing_composition_id + root_missing_dimensions
   ({ rootTag }) => {
     const findings = [];
-    if (!rootTag || !readAttr(rootTag.raw, "data-composition-id")) {
+    if (!rootTag || !readDecodedAttr(rootTag.raw, "data-composition-id")) {
       findings.push({
         code: "root_missing_composition_id",
         severity: "error",
@@ -504,15 +518,10 @@ var coreRules = [
     return findings;
   },
   // timeline_id_mismatch
-  ({ source }) => {
+  ({ source, compositionIds }) => {
     const findings = [];
-    const htmlCompIds = /* @__PURE__ */ new Set();
+    const htmlCompIds = new Set(compositionIds);
     const timelineRegKeys = /* @__PURE__ */ new Set();
-    const compIdRe = /data-composition-id\s*=\s*["']([^"']+)["']/gi;
-    let m;
-    while ((m = compIdRe.exec(source)) !== null) {
-      if (m[1]) htmlCompIds.add(m[1]);
-    }
     for (const key of extractTimelineRegistryKeys(source)) {
       timelineRegKeys.add(key);
     }
@@ -567,7 +576,7 @@ var coreRules = [
     for (const tag of tags) {
       const src = readAttr(tag.raw, "data-composition-src");
       if (!src) continue;
-      if (readAttr(tag.raw, "data-composition-id")) continue;
+      if (readDecodedAttr(tag.raw, "data-composition-id")) continue;
       findings.push({
         code: "host_missing_composition_id",
         severity: "error",
@@ -642,7 +651,7 @@ var coreRules = [
         code: "studio_missing_editable_id",
         severity: "warning",
         message: `${descriptor} has no id, so Studio cannot use a stable edit target for its timeline and canvas controls.`,
-        selector: readAttr(tag.raw, "data-composition-id") ? `[data-composition-id="${readAttr(tag.raw, "data-composition-id")}"]` : void 0,
+        selector: readDecodedAttr(tag.raw, "data-composition-id") ? `[data-composition-id="${readDecodedAttr(tag.raw, "data-composition-id")}"]` : void 0,
         fixHint: 'Add a stable, human-readable id such as id="hero-title" or id="scene-1-card" to every timeline-visible element you want agents or Studio to edit.',
         snippet: truncateSnippet(tag.raw)
       });
@@ -1001,7 +1010,7 @@ var mediaRules = [
     for (const tag of tags) {
       if (tag.name === "video" || tag.name === "audio") continue;
       if (voidElements.has(tag.name)) continue;
-      if (readAttr(tag.raw, "data-composition-id")) continue;
+      if (readDecodedAttr(tag.raw, "data-composition-id")) continue;
       if (readAttr(tag.raw, "data-start")) {
         timedTagPositions.push({
           name: tag.name,
@@ -1247,6 +1256,10 @@ async function loadParseGsapScript() {
 }
 var SCENE_BOUNDARY_EPSILON_SECONDS = 0.05;
 var UNRESOLVED_TARGET = "__unresolved__";
+function targetHasNoStableIdentity(selector, identity) {
+  if (identity) return false;
+  return selector === UNRESOLVED_TARGET || selector === "dwell/hold" || selector.startsWith("proxy \u2192 ");
+}
 function countClassUsage(tags) {
   const counts = /* @__PURE__ */ new Map();
   for (const tag of tags) {
@@ -1304,6 +1317,7 @@ async function extractGsapWindows(script) {
     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,
       properties: Object.keys(animation.properties),
@@ -1395,7 +1409,7 @@ function findTagEnd(source, tag) {
 }
 function collectCompositionRanges(source, tags) {
   return tags.map((tag) => {
-    const id = readAttr(tag.raw, "data-composition-id");
+    const id = readDecodedAttr(tag.raw, "data-composition-id");
     if (!id) return null;
     return {
       id,
@@ -1628,12 +1642,14 @@ var gsapRules = [
         const left = gsapWindows[i];
         if (!left) continue;
         if (left.end <= left.position) continue;
-        if (left.targetSelector === UNRESOLVED_TARGET) continue;
+        if (targetHasNoStableIdentity(left.targetSelector, left.targetIdentity)) continue;
         for (let j = i + 1; j < gsapWindows.length; j++) {
           const right = gsapWindows[j];
           if (!right) continue;
           if (right.end <= right.position) continue;
-          if (left.targetSelector !== right.targetSelector) continue;
+          const leftIdentity = left.targetIdentity ?? left.targetSelector;
+          const rightIdentity = right.targetIdentity ?? right.targetSelector;
+          if (leftIdentity !== rightIdentity) continue;
           const overlapStart = Math.max(left.position, right.position);
           const overlapEnd = Math.min(left.end, right.end);
           if (overlapEnd <= overlapStart) continue;
@@ -2404,6 +2420,28 @@ import { COMPOSITION_VARIABLE_TYPES } from "@hyperframes/parsers/composition";
 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 countPhysicalLines(source) {
   if (source.length === 0) return 0;
@@ -2414,6 +2452,11 @@ function countPhysicalLines(source) {
 function countStructuralLines(source) {
   return countPhysicalLines(source.replace(/<style\b[^>]*>[\s\S]*?<\/style>/gi, "<style></style>"));
 }
+function isCaptionCue(tag) {
+  const classTokens = (readAttr(tag.raw, "class") || "").split(/\s+/).filter(Boolean);
+  const id = readAttr(tag.raw, "id");
+  return classTokens.some((token) => CAPTION_CUE_TOKEN.test(token)) || Boolean(id && CAPTION_CUE_TOKEN.test(id));
+}
 function isRegistrySourceFile(filePath) {
   if (!filePath) return false;
   const normalized = filePath.replace(/\\/g, "/");
@@ -2424,7 +2467,7 @@ function isRegistryInstalledFile(rawSource) {
 }
 function isCompositionRootOrMount(rawTag) {
   return Boolean(
-    readAttr(rawTag, "data-composition-id") || readAttr(rawTag, "data-composition-src")
+    readDecodedAttr(rawTag, "data-composition-id") || readAttr(rawTag, "data-composition-src")
   );
 }
 function extractCssUrlReferences(css) {
@@ -2457,6 +2500,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) {
@@ -2500,7 +2570,36 @@ function declaredIdsForBindingCheck(tags) {
   if (declared.size === 0 && !findHtmlTag(tags)) return null;
   return declared;
 }
+function isInsideInertTemplate(tag, tags) {
+  return tags.some(
+    (candidate) => candidate.name === "template" && candidate.closeIndex != null && tag.index > candidate.index && tag.index < candidate.closeIndex
+  );
+}
 var compositionRules = [
+  // duplicate_composition_id catches meta-tag/root collisions that create duplicate composition entries.
+  ({ tags }) => {
+    const tagsByCompositionId = /* @__PURE__ */ new Map();
+    for (const tag of tags) {
+      if (isInsideInertTemplate(tag, tags)) continue;
+      const compositionId = readDecodedAttr(tag.raw, "data-composition-id");
+      if (!compositionId || compositionId.trim().length === 0) continue;
+      const matchingTags = tagsByCompositionId.get(compositionId) ?? [];
+      matchingTags.push(tag.raw);
+      tagsByCompositionId.set(compositionId, matchingTags);
+    }
+    const findings = [];
+    for (const [compositionId, matchingTags] of tagsByCompositionId) {
+      if (matchingTags.length < 2) continue;
+      findings.push({
+        code: "duplicate_composition_id",
+        severity: "error",
+        message: `Composition id "${compositionId}" is used by ${matchingTags.length} elements. Each data-composition-id value must be unique within a composition file.`,
+        fixHint: "Keep data-composition-id on exactly one element, the composition root. Remove it from metadata or duplicate hosts, especially a <meta> tag carrying the same data-composition-id as the root <div>, which causes a silent duplicate-id collision.",
+        snippet: truncateSnippet(matchingTags[0] ?? "")
+      });
+    }
+    return findings;
+  },
   // invalid_parent_traversal_in_asset_path — catches `../` traversal in src,
   // href, inline-style url(), and <style> url() asset references on
   // compositions. Sub-compositions live under compositions/ but are served
@@ -2575,6 +2674,7 @@ var compositionRules = [
     const trackCounts = /* @__PURE__ */ new Map();
     for (const tag of tags) {
       if (TRACK_DENSITY_EXEMPT_TAGS.has(tag.name)) continue;
+      if (isCaptionCue(tag)) continue;
       if (isCompositionRootOrMount(tag.raw)) continue;
       if (!readAttr(tag.raw, "data-start")) continue;
       const track = readAttr(tag.raw, "data-track-index");
@@ -2601,7 +2701,7 @@ var compositionRules = [
     for (const tag of tags) {
       if (tag.name === "audio" || tag.name === "script" || tag.name === "style") continue;
       if (!readAttr(tag.raw, "data-start")) continue;
-      if (readAttr(tag.raw, "data-composition-id")) continue;
+      if (readDecodedAttr(tag.raw, "data-composition-id")) continue;
       if (readAttr(tag.raw, "data-composition-src")) continue;
       const classAttr = readAttr(tag.raw, "class") || "";
       const styleAttr = readAttr(tag.raw, "style") || "";
@@ -2701,7 +2801,7 @@ var compositionRules = [
     const skipTags = /* @__PURE__ */ new Set(["audio", "video", "script", "style", "template"]);
     for (const tag of tags) {
       if (skipTags.has(tag.name)) continue;
-      if (readAttr(tag.raw, "data-composition-id")) continue;
+      if (readDecodedAttr(tag.raw, "data-composition-id")) continue;
       if (readAttr(tag.raw, "data-composition-src")) continue;
       const hasStart = readAttr(tag.raw, "data-start") !== null;
       const hasDuration = readAttr(tag.raw, "data-duration") !== null;
@@ -2767,7 +2867,7 @@ var compositionRules = [
     const findings = [];
     if (options.isSubComposition) return findings;
     if (!rootTag) return findings;
-    const compId = readAttr(rootTag.raw, "data-composition-id");
+    const compId = readDecodedAttr(rootTag.raw, "data-composition-id");
     if (!compId) return findings;
     const hasStart = readAttr(rootTag.raw, "data-start") !== null;
     if (!hasStart) {
@@ -3125,7 +3225,7 @@ var compositionRules = [
   ({ rootTag, scripts, styles, tags, options }) => {
     if (options.isSubComposition) return [];
     if (!rootTag) return [];
-    if (readAttr(rootTag.raw, "data-composition-id") === null) return [];
+    if (readDecodedAttr(rootTag.raw, "data-composition-id") === null) return [];
     if (readAttr(rootTag.raw, "data-duration") !== null) return [];
     const allScriptTexts = scripts.map((s) => stripJsComments(s.content));
     const hasGsapTimeline = allScriptTexts.some((t) => /gsap\.timeline\s*\(/.test(t));
@@ -3177,6 +3277,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).`
+      }
+    ];
   }
 ];
 
@@ -3606,7 +3755,7 @@ function parseTiming(raw) {
 }
 function collectCompositionIdScenes(ctx, seen, out) {
   for (const tag of ctx.tags) {
-    const compositionId = readAttr(tag.raw, "data-composition-id");
+    const compositionId = readDecodedAttr(tag.raw, "data-composition-id");
     if (!compositionId || !isSceneLikeCompositionId(compositionId) || seen.has(compositionId))
       continue;
     const timing = parseTiming(tag.raw);
@@ -3906,8 +4055,10 @@ async function lintProject(projectDir, entryFile) {
       const out = [];
       for (const entry of readdirSync(dir, { withFileTypes: true })) {
         const relPath = rel ? `${rel}/${entry.name}` : entry.name;
-        if (entry.isDirectory()) out.push(...collectHtmlFiles(join(dir, entry.name), relPath));
-        else if (entry.isFile() && entry.name.endsWith(".html") && !entry.name.startsWith("._")) {
+        if (entry.isDirectory()) {
+          if (!rel && entry.name === "components") continue;
+          out.push(...collectHtmlFiles(join(dir, entry.name), relPath));
+        } else if (entry.isFile() && entry.name.endsWith(".html") && !entry.name.startsWith("._")) {
           out.push(relPath);
         }
       }