@hyperframes/lint 0.8.111 → 0.8.113

package/dist/browser.js

@@ -10,7 +10,7 @@ var TIMELINE_REGISTRY_OBJECT_LITERAL_PATTERN = /window\.__timelines\s*=\s*\{\s*(
 var TIMELINE_REGISTRY_ASSIGN_PATTERN = /window\.__timelines(?:\[[^\]]+\]|\.[A-Za-z_$][\w$]*)\s*=/i;
 var WINDOW_TIMELINE_ASSIGN_PATTERN = /window\.__timelines(?:\[\s*(?:["']([^"']+)["']|[A-Za-z_$][\w$.]*)\s*\]|\.\s*([A-Za-z_$][\w$]*))\s*=\s*([A-Za-z_$][\w$]*)/i;
 var INVALID_SCRIPT_CLOSE_PATTERN = /<script[^>]*>[\s\S]*?<\s*\/\s*script(?!>)/i;
-var TIMELINE_REGISTRY_KEY_PATTERN = /window\.__timelines(?:\[\s*["']([^"']+)["']\s*\]|\.\s*([A-Za-z_$][\w$]*))\s*=/g;
+var TIMELINE_REGISTRY_KEY_PATTERN = /window\.__timelines(?:\[\s*["']([^"']+)["']\s*\]|\.\s*([A-Za-z_$][\w$]*))\s*(?:\?\?|\|\||&&)?=/g;
 var TIMELINE_REGISTRY_OBJECT_OPEN_PATTERN = /window\.__timelines\s*=\s*\{/i;
 var TIMELINE_REGISTRY_OBJECT_ENTRY_PATTERN = /(?:["']([^"']+)["']|([A-Za-z_$][\w$]*))\s*:\s*[A-Za-z_$][\w$]*/g;
 function parseHtmlStructure(source) {
@@ -114,9 +114,7 @@ function readAttr(tagSource, attr) {
   return match?.[1] || null;
 }
 function hasAttrName(tagSource, attr) {
-  const escaped = attr.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-  const attrs = tagSource.replace(/^<\s*[a-z][\w:-]*/i, "");
-  return new RegExp(`(?:^|\\s)${escaped}(?:\\s*=|\\s|/?>)`, "i").test(attrs);
+  return readDecodedAttr(tagSource, attr) !== null;
 }
 function isAudibleVideoTag(tagSource) {
   if (hasAttrName(tagSource, "muted")) return false;
@@ -796,6 +794,34 @@ function repeatedDescendantId(selector) {
   }
   return repeated;
 }
+function addUnescapedDigitIds(selector, ids) {
+  try {
+    selectorParser((root) => {
+      root.walkIds((node) => {
+        if (/^#\d/.test(node.toString().trim())) ids.add(node.value);
+      });
+    }).processSync(selector);
+  } catch {
+  }
+}
+var SELECTOR_CALL_PATTERN = /(?:\.(?:querySelector(?:All)?|closest|matches|to|from|fromTo|set|toArray)\s*\(|(?<![\w$-])(?:trigger|endTrigger|pin|scrollTrigger|scroller|pinnedContainer|pinSpacer)["']?\s*:)\s*(["'`])((?:\\.|(?!\1)[^\\])*)\1/g;
+function digitIdsTargetedBySelectors(styles, scripts) {
+  const ids = /* @__PURE__ */ new Set();
+  for (const style of styles) {
+    try {
+      postcss.parse(style.content).walkRules((rule) => {
+        for (const selector of rule.selectors) addUnescapedDigitIds(selector, ids);
+      });
+    } catch {
+    }
+  }
+  for (const script of scripts) {
+    for (const match of stripJsComments(script.content).matchAll(SELECTOR_CALL_PATTERN)) {
+      addUnescapedDigitIds(match[2] ?? "", ids);
+    }
+  }
+  return ids;
+}
 function resolvedRuleSelectors(rule) {
   let ancestor = rule.parent;
   while (ancestor && ancestor.type !== "rule") ancestor = ancestor.parent;
@@ -814,16 +840,20 @@ function resolvedRuleSelectors(rule) {
     })
   );
 }
+function rightmostCompoundNodes(selectorNode) {
+  const subject = [];
+  selectorNode.each((node) => {
+    if (node.type === "combinator") subject.length = 0;
+    else subject.push(node);
+  });
+  return subject;
+}
 function selectorAliasesRuntimeHiddenStyle(selector) {
   let unsafe = false;
   try {
     selectorParser((root) => {
       root.each((selectorNode) => {
-        const subject = [];
-        selectorNode.each((node) => {
-          if (node.type === "combinator") subject.length = 0;
-          else subject.push(node);
-        });
+        const subject = rightmostCompoundNodes(selectorNode);
         const hostScoped = subject.some(
           (node) => node.type === "attribute" && ["data-composition-src", "data-composition-file"].includes(
             node.attribute.toLowerCase()
@@ -846,6 +876,57 @@ function selectorAliasesRuntimeHiddenStyle(selector) {
   }
   return unsafe;
 }
+var POSITION_PROPERTIES = /* @__PURE__ */ new Set(["left", "top", "right", "bottom", "inset"]);
+function weakIdOf(node) {
+  if (node.type === "attribute" && node.attribute.toLowerCase() === "id") {
+    return node.operator === "=" && node.value ? node.value : null;
+  }
+  if (node.type !== "pseudo" || node.value.toLowerCase() !== ":where") return null;
+  const inner = node.nodes.flatMap((option) => option.nodes).find((n) => n.type === "id");
+  return inner ? inner.value : null;
+}
+function reducedSpecificityId(selector) {
+  let matched = null;
+  try {
+    selectorParser((root) => {
+      root.each((selectorNode) => {
+        const subject = rightmostCompoundNodes(selectorNode);
+        if (subject.some((node) => node.type === "id")) return;
+        for (const node of subject) matched = weakIdOf(node) ?? matched;
+      });
+    }).processSync(selector);
+  } catch {
+    return null;
+  }
+  return matched;
+}
+function cssIdSelector(id) {
+  return `#${id.replace(
+    /[^a-zA-Z0-9_-]|^-?\d/g,
+    (match) => Array.from(match, (char) => `\\${char.codePointAt(0)?.toString(16)} `).join("")
+  )}`;
+}
+function reducedSpecificityIdFindings(rule, reported) {
+  const positionProps = rule.nodes.flatMap(
+    (node) => node.type === "decl" && !node.important && POSITION_PROPERTIES.has(node.prop.toLowerCase()) ? [node.prop] : []
+  );
+  if (positionProps.length === 0) return [];
+  const findings = [];
+  for (const selector of resolvedRuleSelectors(rule)) {
+    const id = reported.has(selector) ? null : reducedSpecificityId(selector);
+    if (id === null) continue;
+    reported.add(selector);
+    findings.push({
+      code: "id_override_reduced_specificity",
+      severity: "warning",
+      message: `Selector "${selector}" sets ${positionProps.join("/")} through [id=...] or :where(#id), which has class-level or zero specificity, so a compound class rule (e.g. ".parent .row") on the same element can silently win over this override.`,
+      selector,
+      fixHint: `Use \`${cssIdSelector(id)}\` instead; id specificity beats any selector built only from classes.`,
+      snippet: truncateSnippet(rule.toString())
+    });
+  }
+  return findings;
+}
 function ruleForcesOpacityZero(rule) {
   let forcesOpacityZero = false;
   rule.walkDecls(/^opacity$/i, (declaration) => {
@@ -853,6 +934,34 @@ function ruleForcesOpacityZero(rule) {
   });
   return forcesOpacityZero;
 }
+var CSS_TRANSITION_PROPERTY_PATTERN = /^(?:-webkit-)?transition(?:-[a-z][a-z-]*)?$/i;
+var TRANSITION_NONE_PROPERTIES = /* @__PURE__ */ new Set(["transition", "transition-property"]);
+var TRANSITION_TIME_PROPERTIES = /* @__PURE__ */ new Set([
+  "transition",
+  "transition-duration",
+  "transition-delay"
+]);
+function hasNonZeroTime(value) {
+  const times = value.match(/[+-]?(?:\d*\.)?\d+m?s\b/g) ?? [];
+  return value.includes("var(") || times.some((time) => Number.parseFloat(time) !== 0);
+}
+function isSeekUnsafeTransition(declaration) {
+  const property = declaration.prop.trim().toLowerCase();
+  if (!CSS_TRANSITION_PROPERTY_PATTERN.test(property)) return false;
+  const name = property.replace(/^-webkit-/, "");
+  const value = declaration.value.trim().toLowerCase();
+  if (value === "none" && TRANSITION_NONE_PROPERTIES.has(name)) return false;
+  return !TRANSITION_TIME_PROPERTIES.has(name) || hasNonZeroTime(value);
+}
+function cssTransitionFinding(declaration, details) {
+  return {
+    code: "css_transition_used",
+    severity: "warning",
+    message: `CSS declaration \`${declaration.prop}: ${declaration.value}\` runs on the browser clock and cannot be seeked deterministically across render workers.`,
+    fixHint: "Keep the class or attribute swap for state; put the visual change on the paused GSAP timeline.",
+    ...details
+  };
+}
 function isStudioTimelineElement(tag) {
   if (["script", "style", "link", "meta", "template", "noscript"].includes(tag.name)) {
     return false;
@@ -971,15 +1080,18 @@ function describeRootDimensionsDrift(source, dataWidth, dataHeight) {
 }
 var coreRules = [
   // id_requires_css_escape
-  ({ tags }) => {
+  ({ tags, styles, scripts }) => {
     const findings = [];
+    let targeted;
     for (const tag of tags) {
       const id = readAttr(tag.raw, "id");
       if (!id || !/^\d/.test(id)) continue;
+      targeted ??= digitIdsTargetedBySelectors(styles, scripts);
+      const used = targeted.has(id);
       findings.push({
         code: "id_requires_css_escape",
-        severity: "warning",
-        message: `id="${id}" starts with a digit, so the common selector \`#${id}\` throws a SyntaxError in querySelector().`,
+        severity: used ? "error" : "warning",
+        message: used ? `id="${id}" starts with a digit, and the selector \`#${id}\` used in this composition is invalid: querySelector and GSAP throw a SyntaxError, and CSS drops the rule.` : `id="${id}" starts with a digit, so the common selector \`#${id}\` throws a SyntaxError in querySelector().`,
         elementId: id,
         fixHint: "Rename the id to start with a letter (recommended), or build selectors with `#${CSS.escape(id)}` at runtime.",
         snippet: truncateSnippet(tag.raw)
@@ -1123,11 +1235,55 @@ var coreRules = [
     }
     return findings;
   },
+  // css_transition_used
+  ({ styles, tags }) => {
+    const findings = [];
+    for (const style of styles) {
+      if (!/transition/i.test(style.content)) continue;
+      let root;
+      try {
+        root = postcss.parse(style.content);
+      } catch {
+        continue;
+      }
+      root.walkDecls((declaration) => {
+        if (!isSeekUnsafeTransition(declaration)) return;
+        const selector = declaration.parent?.type === "rule" ? declaration.parent.selector : void 0;
+        findings.push(
+          cssTransitionFinding(declaration, {
+            selector,
+            snippet: truncateSnippet(declaration.toString())
+          })
+        );
+      });
+    }
+    for (const tag of tags) {
+      const inlineStyle = readDecodedAttr(tag.raw, "style");
+      if (!inlineStyle || !/transition/i.test(inlineStyle)) continue;
+      let root;
+      try {
+        root = postcss.parse(inlineStyle);
+      } catch {
+        continue;
+      }
+      root.walkDecls((declaration) => {
+        if (!isSeekUnsafeTransition(declaration)) return;
+        findings.push(
+          cssTransitionFinding(declaration, {
+            elementId: readDecodedAttr(tag.raw, "id") || void 0,
+            snippet: truncateSnippet(tag.raw)
+          })
+        );
+      });
+    }
+    return findings;
+  },
   // CSS selector safety
   ({ styles, locate }) => {
     const findings = [];
     const reportedRepeatedIds = /* @__PURE__ */ new Set();
     const reportedHiddenStyleSelectors = /* @__PURE__ */ new Set();
+    const reportedReducedIdSelectors = /* @__PURE__ */ new Set();
     for (const style of styles) {
       let root;
       try {
@@ -1146,6 +1302,7 @@ var coreRules = [
       }
       root.walkRules((rule) => {
         const forcesOpacityZero = ruleForcesOpacityZero(rule);
+        findings.push(...reducedSpecificityIdFindings(rule, reportedReducedIdSelectors));
         for (const selector of resolvedRuleSelectors(rule)) {
           const repeatedId = repeatedDescendantId(selector);
           if (repeatedId && !reportedRepeatedIds.has(repeatedId)) {
@@ -2383,6 +2540,7 @@ var HEAVY_OVERLAY_EXEMPT_TAGS = /* @__PURE__ */ new Set([
 ]);
 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 COMPUTED_TIMELINE_REGISTRATION_PATTERN = /window\.__timelines\s*\[(?!\s*["'])(?:[^\r\n[\]]|\[[^\r\n\]]*\])+\]\s*(?:\?\?|\|\||&&)?=/;
 function readTagTiming(rawTag) {
   return readClipTiming({ getAttribute: (name) => readAttr(rawTag, name) });
 }
@@ -2691,6 +2849,26 @@ function negativeZIndexFinding(match, selector) {
     snippet: truncateSnippet(match[0])
   };
 }
+function hasComputedTimelineRegistration(scripts) {
+  return scripts.some(
+    (script) => COMPUTED_TIMELINE_REGISTRATION_PATTERN.test(stripJsCode(script.content))
+  );
+}
+function mountsSource(tag) {
+  return Boolean(
+    readAttr(tag.raw, "data-composition-src") || readAttr(tag.raw, "data-composition-file")
+  );
+}
+function missingTimelineFinding(tag, compositionId, isRoot) {
+  return {
+    code: "missing_data_no_timeline",
+    severity: "warning",
+    message: isRoot ? "This composition has no `window.__timelines` registration but is missing `data-no-timeline`. The producer polls for timeline registration for up to 45 seconds before timing out, adding 45 s to every render." : `Composition host "${compositionId}" has neither a matching \`window.__timelines\` registration nor \`data-no-timeline\`. The producer waits up to 45 seconds for every \`data-composition-id\` before rendering.`,
+    elementId: readAttr(tag.raw, "id") || void 0,
+    fixHint: isRoot ? 'Add `data-no-timeline` to the root element to skip the poll: `<div data-composition-id="..." data-no-timeline ...>`.' : "If this is a static section, use a plain `id` instead of `data-composition-id`, or add `data-no-timeline`. Otherwise, register its timeline or mount it with `data-composition-src`.",
+    snippet: truncateSnippet(tag.raw)
+  };
+}
 var compositionRules = [
   // duplicate_composition_id catches meta-tag/root collisions that create duplicate composition entries.
   ({ tags }) => {
@@ -2959,27 +3137,25 @@ var compositionRules = [
     return findings;
   },
   // missing_data_no_timeline
-  // The producer polls window.__timelines[id] with a 45-second timeout waiting
-  // for GSAP timeline registration. Compositions that never call
-  // window.__timelines[id] = tl stall for 45 s every render. Adding
-  // data-no-timeline to the root element tells the producer to skip the poll.
-  ({ rootTag, rootCompositionId, scripts, rawSource, options }) => {
-    if (options.isSubComposition) return [];
+  // The producer polls window.__timelines[id] for every composition id in the
+  // rendered document. A timeline-free root or bare nested composition host
+  // therefore spends the full 45-second readiness budget unless it explicitly
+  // opts out with data-no-timeline.
+  ({ rootTag, rootCompositionId, tags, scripts, rawSource, options }) => {
     if (!rootCompositionId || !rootTag) return [];
-    const tagNoValues = rootTag.raw.replace(/"[^"]*"|'[^']*'/g, '""');
-    if (/(?:^|\s)data-no-timeline(?=[\s>=/]|$)/i.test(tagNoValues)) return [];
     if (/<script\b[^>]*\bsrc\s*=/i.test(rawSource)) return [];
-    const registersTimeline = scripts.some((s) => s.content.includes("window.__timelines["));
-    if (registersTimeline) return [];
-    return [
-      {
-        code: "missing_data_no_timeline",
-        severity: "warning",
-        message: "This composition has no `window.__timelines` registration but is missing `data-no-timeline`. The producer polls for timeline registration for up to 45 seconds before timing out, adding 45 s to every render.",
-        fixHint: 'Add `data-no-timeline` to the root element to skip the poll: `<div data-composition-id="..." data-no-timeline ...>`.',
-        snippet: truncateSnippet(rootTag.raw)
-      }
-    ];
+    if (hasComputedTimelineRegistration(scripts)) return [];
+    const registeredIds = new Set(
+      scripts.flatMap((script) => extractTimelineRegistryKeys(stripJsComments(script.content)))
+    );
+    return tags.flatMap((tag) => {
+      const compositionId = readDecodedAttr(tag.raw, "data-composition-id");
+      if (!compositionId || registeredIds.has(compositionId)) return [];
+      const isRoot = tag.index === rootTag.index;
+      if (isRoot ? options.isSubComposition : isInsideInertTemplate(tag, tags)) return [];
+      if (readDecodedAttr(tag.raw, "data-no-timeline") !== null || mountsSource(tag)) return [];
+      return [missingTimelineFinding(tag, compositionId, isRoot)];
+    });
   },
   // negative_z_index
   // An element at a negative z-index is silently absent from both `snapshot`
@@ -4282,7 +4458,7 @@ ${right.raw}`)
           severity: "warning",
           message: `${fromToWindows.length} tl.fromTo() calls target "${selector}" with no stable baseline. The last-authored fromTo "from" values become the element's resting state for any seek before the first tween actually runs, because GSAP applies fromTo from-values at authoring time (immediateRender), not at tween position.`,
           selector,
-          fixHint: `Add \`immediateRender: false\` to the destination vars of each future fromTo, or set a safe resting state with an earlier \`tl.set("${selector}", { ... }, 0)\`. Pre-first-tween seeks must not inherit whichever fromTo call happened to author last.`,
+          fixHint: `Add \`immediateRender: false\` to every fromTo except the earliest-positioned one (at ${firstFromToPosition}s), so pre-first-tween seeks keep its "from" values. A hiding \`tl.set(..., 0)\` baseline trips gsap_timeline_set_initial_hide, and a \`gsap.set\` authored before the fromTo calls is overwritten by them.`,
           snippet: truncateSnippet(fromToWindows.map((win) => win.raw).join("\n"))
         });
       }
@@ -4415,7 +4591,7 @@ ${right.raw}`)
         const cssFromScale = scaleProps.length > 0 ? matchCssTransform(sel, cssScaleSelectors) : void 0;
         if (!cssFromTranslate && !cssFromScale) continue;
         const existing = conflicts.get(sel) ?? {
-          cssTransform: [cssFromTranslate, cssFromScale].filter(Boolean).join(" "),
+          cssTransform: [...new Set([cssFromTranslate, cssFromScale].filter(Boolean))].join(" "),
           props: /* @__PURE__ */ new Set(),
           raw: call.raw
         };