@hyperframes/lint 0.8.3 → 0.8.5

package/dist/browser.d.ts

@@ -9,12 +9,24 @@ type HyperframeLintFinding = {
     fixHint?: string;
     snippet?: string;
 };
+/**
+ * Where a single lint pass spent its time. Attributed per rule-source module
+ * ("gsap", "core", ...) rather than per rule, plus the single slowest rule as
+ * `<group>#<index-within-group>` so a pathological rule is locatable.
+ */
+type LintTimings = {
+    totalMs: number;
+    groupMs: Record<string, number>;
+    slowestRule: string;
+    slowestRuleMs: number;
+};
 type HyperframeLintResult = {
     ok: boolean;
     errorCount: number;
     warningCount: number;
     infoCount: number;
     findings: HyperframeLintFinding[];
+    timings?: LintTimings;
 };
 type HyperframeLinterOptions = {
     filePath?: string;

package/dist/browser.js

@@ -301,15 +301,6 @@ function buildLintContext(html, options = {}) {
 // src/rules/core.ts
 import postcss from "postcss";
 import selectorParser from "postcss-selector-parser";
-function escapeRegExp(value) {
-  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-}
-function selectorTargetsCompositionId(selector, compositionId) {
-  const escaped = escapeRegExp(compositionId);
-  return new RegExp(
-    String.raw`\[\s*data-composition-id\s*=\s*(?:"${escaped}"|'${escaped}')\s*\]`
-  ).test(selector);
-}
 function repeatedDescendantId(selector) {
   let repeated = null;
   const requiredPseudoIds = (pseudo) => {
@@ -705,36 +696,6 @@ var coreRules = [
     }
     return findings;
   },
-  // composition_self_attribute_selector
-  ({ styles, rootCompositionId, rootTag }) => {
-    const findings = [];
-    if (!rootCompositionId) return findings;
-    const seenSelectors = /* @__PURE__ */ new Set();
-    const rootId = readAttr(rootTag?.raw || "", "id");
-    for (const style of styles) {
-      let root;
-      try {
-        root = postcss.parse(style.content);
-      } catch {
-        continue;
-      }
-      root.walkRules((rule) => {
-        for (const selector of rule.selectors) {
-          if (!selectorTargetsCompositionId(selector, rootCompositionId)) continue;
-          if (seenSelectors.has(selector)) continue;
-          seenSelectors.add(selector);
-          findings.push({
-            code: "composition_self_attribute_selector",
-            severity: "warning",
-            message: "Selector matches the block's own id; will leak to sibling instances when the block is embedded twice.",
-            selector,
-            fixHint: rootId ? `Use #${rootId} for clearer authoring intent and instance-isolated styling.` : "Add a stable id to the composition root and use that id selector for clearer authoring intent and instance-isolated styling."
-          });
-        }
-      });
-    }
-    return findings;
-  },
   // studio_missing_editable_id
   ({ tags, rootTag }) => {
     const findings = [];
@@ -810,60 +771,13 @@ var coreRules = [
       }
     }
     return findings;
-  },
-  // pointer_events_none
-  // fallow-ignore-next-line complexity
-  ({ tags, styles }) => {
-    const findings = [];
-    const reported = /* @__PURE__ */ new Set();
-    for (const tag of tags) {
-      if (["script", "style", "link", "meta", "template", "noscript"].includes(tag.name)) continue;
-      const inlineStyle = readAttr(tag.raw, "style") ?? "";
-      if (!/pointer-events\s*:\s*none/i.test(inlineStyle)) continue;
-      const id = readAttr(tag.raw, "id");
-      const key = id ?? tag.raw;
-      if (reported.has(key)) continue;
-      reported.add(key);
-      findings.push({
-        code: "pointer_events_none",
-        severity: "info",
-        message: `<${tag.name}${id ? ` id="${id}"` : ""}> has \`pointer-events: none\` in its inline style. Elements with this property are harder to select in the Studio preview.`,
-        elementId: id || void 0,
-        fixHint: "If this element should be selectable in the Studio, remove `pointer-events: none` or move it to a wrapper that doesn't contain editable content.",
-        snippet: truncateSnippet(tag.raw)
-      });
-    }
-    for (const style of styles) {
-      let root;
-      try {
-        root = postcss.parse(style.content);
-      } catch {
-        continue;
-      }
-      root.walkDecls("pointer-events", (decl) => {
-        if (decl.value.trim().toLowerCase() !== "none") return;
-        const rule = decl.parent;
-        if (!rule || rule.type !== "rule") return;
-        const selector = rule.selector;
-        if (reported.has(selector)) return;
-        reported.add(selector);
-        findings.push({
-          code: "pointer_events_none",
-          severity: "info",
-          message: `\`${selector}\` sets \`pointer-events: none\`. Elements matching this selector are harder to select in the Studio preview.`,
-          selector,
-          fixHint: "If these elements should be selectable in the Studio, remove `pointer-events: none` or move it to a wrapper that doesn't contain editable content."
-        });
-      });
-    }
-    return findings;
   }
 ];
 
 // src/rules/media.ts
 import { validateColorGradingContract } from "@hyperframes/parsers/color-grading-contract";
 function tweensVolumeInSameCall(script, id) {
-  const selector = new RegExp(`#${escapeRegExp2(id)}(?![\\w-])`, "g");
+  const selector = new RegExp(`#${escapeRegExp(id)}(?![\\w-])`, "g");
   for (let hit = selector.exec(script); hit; hit = selector.exec(script)) {
     let depth = 0;
     const limit = Math.min(script.length, hit.index + 2e3);
@@ -879,11 +793,11 @@ function tweensVolumeInSameCall(script, id) {
   }
   return false;
 }
-function escapeRegExp2(value) {
+function escapeRegExp(value) {
   return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 function hasAttrName(tagSource, attr) {
-  const escaped = escapeRegExp2(attr);
+  const escaped = escapeRegExp(attr);
   const attrs = tagSource.replace(/^<\s*[a-z][\w:-]*/i, "");
   return new RegExp(`(?:^|\\s)${escaped}(?:\\s*=|\\s|/?>)`, "i").test(attrs);
 }
@@ -897,13 +811,13 @@ function selectorTargetsManagedMedia(selector, mediaIndex) {
   if (mediaIndex.hasVideo && /\bvideo\b/i.test(normalized)) return true;
   if (mediaIndex.hasAudio && /\baudio\b/i.test(normalized)) return true;
   for (const mediaId of mediaIndex.ids) {
-    const escapedId = escapeRegExp2(mediaId);
+    const escapedId = escapeRegExp(mediaId);
     if (new RegExp(`#${escapedId}(?![\\w-])`).test(normalized) || normalized.includes(`[id="${mediaId}"]`) || normalized.includes(`[id='${mediaId}']`)) {
       return true;
     }
   }
   for (const className of mediaIndex.classes) {
-    if (new RegExp(`\\.${escapeRegExp2(className)}(?![\\w-])`).test(normalized)) {
+    if (new RegExp(`\\.${escapeRegExp(className)}(?![\\w-])`).test(normalized)) {
       return true;
     }
   }
@@ -1006,7 +920,7 @@ function findImperativeMediaControlFindings(ctx) {
       }
     }
     for (const [variableName, elementId] of mediaVars) {
-      const escapedVar = escapeRegExp2(variableName);
+      const escapedVar = escapeRegExp(variableName);
       const variablePatterns = [
         { pattern: new RegExp(`\\b${escapedVar}\\.play\\s*\\(`, "g"), kind: "play()" },
         { pattern: new RegExp(`\\b${escapedVar}\\.pause\\s*\\(`, "g"), kind: "pause()" },
@@ -1402,8 +1316,29 @@ var mediaRules = [
   // imperative_media_control
   findImperativeMediaControlFindings,
   // audio_volume_double_automation
-  findVolumeDoubleAutomationFindings
+  findVolumeDoubleAutomationFindings,
+  // audio_volume_tween_overrides_gain
+  findVolumeTweenOverridesGainFindings
 ];
+function findVolumeTweenOverridesGainFindings(ctx) {
+  const boosted = ctx.tags.filter((tag) => isMediaTag(tag.name)).map((tag) => ({ tag, volume: Number(readAttr(tag.raw, "data-volume") ?? "1") })).filter((entry) => Number.isFinite(entry.volume) && entry.volume !== 1).filter((entry) => !readDecodedAttr(entry.tag.raw, "data-automation")).map((entry) => ({ ...entry, id: readAttr(entry.tag.raw, "id") })).filter((entry) => Boolean(entry.id));
+  if (boosted.length === 0) return [];
+  const script = ctx.scripts.map((block) => stripJsComments(block.content)).join("\n");
+  const findings = [];
+  for (const { tag, id, volume } of boosted) {
+    if (!tweensVolumeInSameCall(script, id)) continue;
+    const db = volume > 0 ? `${(20 * Math.log10(volume)).toFixed(1)} dB` : "silence";
+    findings.push({
+      code: "audio_volume_tween_overrides_gain",
+      severity: "warning",
+      message: `#${id} has data-volume="${volume}" (${db}) and a GSAP tween on \`volume\`. Tween values are absolute \u2014 they REPLACE this gain rather than scale it \u2014 so wherever the tween names a value the clip plays at that value, not at ${db}.`,
+      elementId: id,
+      fixHint: "Write the tween's targets in the same absolute gain (e.g. `volume: 1.95`, not `volume: 1`), or reset data-volume to 1 and let the tween carry the level on its own.",
+      snippet: truncateSnippet(tag.raw)
+    });
+  }
+  return findings;
+}
 function findVolumeDoubleAutomationFindings(ctx) {
   const automated = ctx.tags.filter((tag) => isMediaTag(tag.name)).map((tag) => ({ tag, automation: readDecodedAttr(tag.raw, "data-automation") })).filter((entry) => entry.automation && /"target"\s*:\s*"volume"/.test(entry.automation)).map((entry) => ({ ...entry, id: readAttr(entry.tag.raw, "id") })).filter((entry) => Boolean(entry.id));
   if (automated.length === 0) return [];
@@ -1439,17 +1374,6 @@ 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) {
-    const classAttr = readAttr(tag.raw, "class");
-    if (!classAttr) continue;
-    for (const className of classAttr.split(/\s+/).filter(Boolean)) {
-      counts.set(className, (counts.get(className) || 0) + 1);
-    }
-  }
-  return counts;
-}
 function readRegisteredTimelineCompositionId(script) {
   const match = script.match(WINDOW_TIMELINE_ASSIGN_PATTERN);
   return match?.[1] || match?.[2] || null;
@@ -1665,16 +1589,6 @@ function findMatchingSceneBoundary(time, boundaries) {
   }
   return null;
 }
-function isSuspiciousGlobalSelector(selector) {
-  if (!selector) return false;
-  if (selector.includes("[data-composition-id=")) return false;
-  if (selector.startsWith("#")) return false;
-  return selector.startsWith(".") || /^[a-z]/i.test(selector);
-}
-function getSingleClassSelector(selector) {
-  const match = selector.trim().match(/^\.(?<name>[A-Za-z0-9_-]+)$/);
-  return match?.groups?.name || null;
-}
 function readStyleProperty(style, property) {
   const escapedProperty = property.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
   const match = style.match(new RegExp(`(?:^|;)\\s*${escapedProperty}\\s*:\\s*([^;]+)`, "i"));
@@ -1918,7 +1832,7 @@ function isInsideGsapTweenVars(source, index, timelineVars) {
     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("|");
+        const receivers = ["gsap", ...timelineVars].map(escapeRegExp2).join("|");
         return new RegExp(`(?:${receivers})\\.(?:set|to|from|fromTo|timeline)\\b[\\s\\S]*$`).test(
           before
         );
@@ -1954,7 +1868,7 @@ function parseFunctionValueSource(code) {
   const firstParam = normalizeFirstParam((match[1] ?? "").split(",")[0] ?? "");
   return { firstParam, body: src.slice(match[0].length) };
 }
-function escapeRegExp3(value) {
+function escapeRegExp2(value) {
   return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 var NUMBER_METHODS = /* @__PURE__ */ new Set([
@@ -1968,7 +1882,7 @@ var NUMBER_METHODS = /* @__PURE__ */ new Set([
 function firstParamMemberAccessHazard(fn) {
   if (!fn.firstParam) return null;
   const pattern = new RegExp(
-    `\\b${escapeRegExp3(fn.firstParam)}\\s*\\.\\s*([A-Za-z_$][\\w$]*)`,
+    `\\b${escapeRegExp2(fn.firstParam)}\\s*\\.\\s*([A-Za-z_$][\\w$]*)`,
     "g"
   );
   let match;
@@ -2012,7 +1926,7 @@ function collectMeasuringFunctionNames(bodies) {
     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)) {
+        if (new RegExp(`\\b${escapeRegExp2(measured)}\\s*\\(`).test(body)) {
           measuring.add(name);
           grew = true;
           break;
@@ -2026,7 +1940,7 @@ function collectMeasuringFunctionNames(bodies) {
 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;
+    if (new RegExp(`\\b${escapeRegExp2(name)}\\b`).test(expression)) return true;
   }
   return false;
 }
@@ -2049,7 +1963,7 @@ function resolveScriptElementTokens(source, tags) {
     const template = match[2] ?? "";
     const staticParts = template.split(/\$\{[^}]*\}/);
     if (staticParts.every((part) => part === "")) continue;
-    const idPattern = new RegExp(`^${staticParts.map(escapeRegExp3).join(".*")}$`);
+    const idPattern = new RegExp(`^${staticParts.map(escapeRegExp2).join(".*")}$`);
     for (const id of documentIds) {
       if (idPattern.test(id)) add(match[1] ?? "", `#${id}`);
     }
@@ -2141,7 +2055,7 @@ function collectCssOpacityZeroSelectors(styles, tags) {
   return selectors;
 }
 var gsapRules = [
-  // overlapping_gsap_tweens + gsap_animates_clip_element + unscoped_gsap_selector
+  // overlapping_gsap_tweens + gsap_animates_clip_element
   // fallow-ignore-next-line complexity
   async ({ source, tags, scripts, styles, rootCompositionId }) => {
     const findings = [];
@@ -2161,7 +2075,6 @@ var gsapRules = [
         if (cls !== "clip") clipClasses.set(`.${cls}`, info);
       }
     }
-    const classUsage = countClassUsage(tags);
     const clipStartBoundariesByComposition = collectClipStartBoundariesByComposition(source, tags);
     const styleRules = collectSimpleStyleRules(styles);
     const reportedVisibleOverlayKeys = /* @__PURE__ */ new Set();
@@ -2284,20 +2197,6 @@ ${right.raw}`)
           snippet: truncateSnippet(win.raw)
         });
       }
-      if (!localTimelineCompId || localTimelineCompId === rootCompositionId) continue;
-      for (const win of gsapWindows) {
-        if (!isSuspiciousGlobalSelector(win.targetSelector)) continue;
-        const className = getSingleClassSelector(win.targetSelector);
-        if (className && (classUsage.get(className) || 0) < 2) continue;
-        findings.push({
-          code: "unscoped_gsap_selector",
-          severity: "error",
-          message: `Timeline "${localTimelineCompId}" uses unscoped selector "${win.targetSelector}" that will target elements in ALL compositions when bundled, causing data loss (opacity, transforms, etc.).`,
-          selector: win.targetSelector,
-          fixHint: `Scope the selector: \`[data-composition-id="${localTimelineCompId}"] ${win.targetSelector}\` or use a unique id.`,
-          snippet: truncateSnippet(win.raw)
-        });
-      }
     }
     return findings;
   },
@@ -2554,39 +2453,6 @@ ${right.raw}`)
     }
     return findings;
   },
-  // scene_layer_missing_visibility_kill
-  ({ scripts, tags }) => {
-    const findings = [];
-    const sceneElements = tags.filter((t) => {
-      const id = readAttr(t.raw, "id") || "";
-      return /^scene\d+$/i.test(id);
-    });
-    if (sceneElements.length < 2) return findings;
-    for (const script of scripts) {
-      const content = stripJsComments(script.content);
-      for (const tag of sceneElements) {
-        const id = readAttr(tag.raw, "id") || "";
-        const exitPattern = new RegExp(`["']#${id}["'][^)]*opacity\\s*:\\s*0`);
-        const hasExit = exitPattern.test(content);
-        if (!hasExit) continue;
-        const killPattern = new RegExp(`["']#${id}["'][^)]*visibility\\s*:\\s*["']hidden["']`);
-        const hasKill = killPattern.test(content);
-        if (!hasKill) {
-          const classes = (readAttr(tag.raw, "class") || "").split(/\s+/).filter(Boolean);
-          const isClip = classes.includes("clip");
-          const fixHint = isClip ? `"#${id}" is a clip element \u2014 the framework already manages its visibility. Wrap the scene's content in an inner non-clip <div>, move the exit tween and the hard kill (\`tl.set("<inner-selector>", { visibility: "hidden" }, <exit-end-time>)\`) onto that wrapper instead.` : `Add \`tl.set("#${id}", { visibility: "hidden" }, <exit-end-time>)\` after the scene's exit tweens.`;
-          findings.push({
-            code: "scene_layer_missing_visibility_kill",
-            severity: "error",
-            elementId: id,
-            message: `Scene layer "#${id}" exits via opacity tween but has no visibility: hidden hard kill. When scrubbing or when tweens conflict, the scene may remain partially visible and overlap the next scene.`,
-            fixHint
-          });
-        }
-      }
-    }
-    return findings;
-  },
   // gsap_timeline_not_registered
   ({ scripts, rawSource, options }) => {
     const findings = [];
@@ -2949,7 +2815,7 @@ ${other.raw}`)
       const timelineVars = collectTimelineVarNames(source);
       for (const timelineVar of timelineVars) {
         const callPattern = new RegExp(
-          `\\b${escapeRegExp3(timelineVar)}\\.(?:add|call)\\s*\\(`,
+          `\\b${escapeRegExp2(timelineVar)}\\.(?:add|call)\\s*\\(`,
           "g"
         );
         let match2;
@@ -2962,7 +2828,7 @@ ${other.raw}`)
           if (callbackExpressionHazard(firstArg)) report(site, site);
         }
         const eventCallbackPattern = new RegExp(
-          `\\b${escapeRegExp3(timelineVar)}\\.eventCallback\\s*\\(\\s*["']on[A-Za-z]+["']\\s*,`,
+          `\\b${escapeRegExp2(timelineVar)}\\.eventCallback\\s*\\(\\s*["']on[A-Za-z]+["']\\s*,`,
           "g"
         );
         while ((match2 = eventCallbackPattern.exec(source)) !== null) {
@@ -3204,31 +3070,6 @@ ${other.raw}`)
 ];
 
 // src/rules/captions.ts
-function extractArrayLiteral(src, varMatch) {
-  const openIdx = varMatch.index + varMatch[0].length - 1;
-  let depth = 0;
-  let inStr = false;
-  let strChar = "";
-  for (let i = openIdx; i < src.length; i++) {
-    const c = src[i];
-    if (inStr) {
-      if (c === "\\") {
-        i++;
-        continue;
-      }
-      if (c === strChar) inStr = false;
-    } else if (c === '"' || c === "'") {
-      inStr = true;
-      strChar = c;
-    } else if (c === "[") {
-      depth++;
-    } else if (c === "]") {
-      depth--;
-      if (depth === 0) return src.slice(openIdx, i + 1);
-    }
-  }
-  return null;
-}
 var captionRules = [
   // caption_exit_missing_hard_kill
   ({ scripts, styles, options, rootCompositionId }) => {
@@ -3296,22 +3137,6 @@ var captionRules = [
         fixHint: 'Embed the transcript as `var TRANSCRIPT = [{ "text": "...", "start": 0, "end": 1 }, ...]` with JSON-quoted property keys. See the captions skill for details.'
       });
     }
-    if (hasInlineTranscript) {
-      const varStart = /(?:const|let|var)\s+(?:TRANSCRIPT|script)\s*=\s*\[/.exec(allScript);
-      const transcriptJson = varStart ? extractArrayLiteral(allScript, varStart) : null;
-      if (transcriptJson) {
-        try {
-          JSON.parse(transcriptJson);
-        } catch {
-          findings.push({
-            code: "caption_transcript_parse_error",
-            severity: "error",
-            message: "Inline TRANSCRIPT array is not valid JSON. The studio caption editor may fail to parse it. Common cause: unquoted property keys with apostrophes in text.",
-            fixHint: `Use JSON-quoted keys: { "text": "don't", "start": 0, "end": 1 } instead of { text: "don't", start: 0, end: 1 }.`
-          });
-        }
-      }
-    }
     return findings;
   },
   // caption_container_relative_position
@@ -3696,33 +3521,6 @@ var compositionRules = [
     }
     return findings;
   },
-  // timed_element_missing_visibility_hidden
-  // fallow-ignore-next-line complexity
-  ({ tags }) => {
-    const findings = [];
-    for (const tag of tags) {
-      if (tag.name === "audio" || tag.name === "script" || tag.name === "style") continue;
-      if (!readAttr(tag.raw, "data-start")) 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") || "";
-      const hasClip = classAttr.split(/\s+/).includes("clip");
-      const hasHiddenStyle = /visibility\s*:\s*hidden/i.test(styleAttr) || /opacity\s*:\s*0/i.test(styleAttr);
-      if (!hasClip && !hasHiddenStyle) {
-        const elementId = readAttr(tag.raw, "id") || void 0;
-        findings.push({
-          code: "timed_element_missing_visibility_hidden",
-          severity: "info",
-          message: `<${tag.name}${elementId ? ` id="${elementId}"` : ""}> has data-start but no class="clip", visibility:hidden, or opacity:0. Consider adding initial hidden state if the element should not be visible before its start time.`,
-          elementId,
-          fixHint: 'Add class="clip" (with CSS: .clip { visibility: hidden; }) or style="opacity:0" if the element should start hidden.',
-          snippet: truncateSnippet(tag.raw)
-        });
-      }
-    }
-    return findings;
-  },
   // deprecated_data_layer + deprecated_data_end
   // fallow-ignore-next-line complexity
   ({ tags }) => {
@@ -3803,7 +3601,7 @@ var compositionRules = [
   // fallow-ignore-next-line complexity
   ({ tags }) => {
     const findings = [];
-    const skipTags = /* @__PURE__ */ new Set(["audio", "video", "script", "style", "template"]);
+    const skipTags = /* @__PURE__ */ new Set(["audio", "img", "video", "script", "style", "template"]);
     for (const tag of tags) {
       if (skipTags.has(tag.name)) continue;
       if (readDecodedAttr(tag.raw, "data-composition-id")) continue;
@@ -3817,10 +3615,17 @@ var compositionRules = [
       const elementId = readAttr(tag.raw, "id") || void 0;
       findings.push({
         code: "timed_element_missing_clip_class",
-        severity: "error",
-        message: `<${tag.name}${elementId ? ` id="${elementId}"` : ""}> has timing attributes but no class="clip". The element will be visible for the entire composition instead of only during its scheduled time range.`,
+        // Not an error: the runtime drives timed visibility off the `data-start`
+        // ATTRIBUTE, not this class — `syncTimedElementVisibility` walks
+        // `querySelectorAll("[data-start]")` and toggles `style.visibility`
+        // regardless of class (pinned by the runtime's own init test, which
+        // uses a bare `<div data-start data-duration>` with no `class="clip"`).
+        // The class is an authoring convention the tooling reads, so a missing
+        // one is worth flagging but does not break the render.
+        severity: "warning",
+        message: `<${tag.name}${elementId ? ` id="${elementId}"` : ""}> has timing attributes but no class="clip". The runtime still hides it outside its time range, but Studio and the GSAP clip-ownership rules use .clip to recognise a clip, so leaving it off makes the element harder to edit and to lint.`,
         elementId,
-        fixHint: 'Add class="clip" to the element. The HyperFrames runtime uses .clip to control visibility based on data-start/data-duration.',
+        fixHint: 'Add class="clip" to the element so Studio and the linter can recognise it as a clip.',
         snippet: truncateSnippet(tag.raw)
       });
     }
@@ -4679,36 +4484,22 @@ function collectGoogleFontFamilies(source, styles) {
   return families;
 }
 var fontRules = [
-  // google_fonts_import
-  ({ styles, source, rawSource, options }) => {
-    if (isRegistrySourceFile(options.filePath) || isRegistryInstalledFile(rawSource)) return [];
-    const findings = [];
-    const googleFontsInLink = /<link\b[^>]*fonts\.googleapis\.com[^>]*>/i.test(source);
-    const googleFontsInImport = styles.some(
-      (s) => /@import\s+url\s*\(\s*['"]?[^)]*fonts\.googleapis\.com/i.test(s.content)
-    );
-    if (googleFontsInLink || googleFontsInImport) {
-      findings.push({
-        code: "google_fonts_import",
-        severity: "warning",
-        message: "Composition loads fonts from fonts.googleapis.com. The producer resolves Google Fonts during compile/render, but raw external font requests add latency and can fail before canonicalization. Prefer mapped family names or local @font-face declarations when possible.",
-        fixHint: "For bundled fonts, remove the Google Fonts <link> or @import and keep the font-family declaration. For custom fonts, use @font-face { font-family: '...'; src: url('...woff2'); }."
-      });
-    }
-    return findings;
-  },
-  // system_font_will_alias — inform when a font will be silently substituted
+  // system_font_will_alias — only for distributed / Lambda renders, where
+  // system-font capture is disabled and the alias substitution does NOT happen,
+  // so the font silently falls back to whatever the OS provides. Under a local
+  // render the substitution is the renderer working as designed, not a defect,
+  // so there is nothing for the author to act on.
   ({ styles, options }) => {
+    if (!options.distributed) return [];
     const declared = extractFontFaceFamilies(styles);
     const used = extractUsedFontFamilies(styles);
     const aliased = collectAliasedFonts(used, declared);
     if (aliased.length === 0) return [];
-    const severity = options.distributed ? "warning" : "info";
     return [
       {
         code: "system_font_will_alias",
-        severity,
-        message: `Font ${aliased.length === 1 ? "family" : "families"} will be substituted at render time: ${aliased.join(", ")}. ` + (options.distributed ? "In distributed/Lambda rendering system-font capture is disabled \u2014 these fonts will fall back to OS defaults. Embed explicit @font-face declarations instead." : "The renderer maps these to bundled fonts for cross-platform consistency. Use the target font name directly for consistent preview and render results.")
+        severity: "warning",
+        message: `Font ${aliased.length === 1 ? "family" : "families"} will be substituted at render time: ${aliased.join(", ")}. In distributed/Lambda rendering system-font capture is disabled \u2014 these fonts will fall back to OS defaults. Embed explicit @font-face declarations instead.`
       }
     ];
   },
@@ -4804,35 +4595,63 @@ var slideshowRules = [
 ];
 
 // src/hyperframeLinter.ts
-var ALL_RULES = [
-  ...coreRules,
-  ...mediaRules,
-  ...gsapRules,
-  ...captionRules,
-  ...compositionRules,
-  ...adapterRules,
-  ...textureRules,
-  ...fontRules,
-  ...slideshowRules
+var RULE_GROUPS = [
+  { group: "core", rules: coreRules },
+  { group: "media", rules: mediaRules },
+  { group: "gsap", rules: gsapRules },
+  { group: "captions", rules: captionRules },
+  { group: "composition", rules: compositionRules },
+  { group: "adapters", rules: adapterRules },
+  { group: "textures", rules: textureRules },
+  { group: "fonts", rules: fontRules },
+  { group: "slideshow", rules: slideshowRules }
 ];
-async function lintHyperframeHtml(html, options = {}) {
-  const ctx = buildLintContext(html, options);
+var LINT_RULE_COUNT = RULE_GROUPS.reduce((n, g) => n + g.rules.length, 0);
+var LINT_RULE_GROUP_COUNTS = Object.fromEntries(
+  RULE_GROUPS.map(({ group, rules }) => [group, rules.length])
+);
+function dedupeKeyFor(finding) {
+  return [
+    finding.code,
+    finding.severity,
+    finding.selector || "",
+    finding.elementId || "",
+    finding.message
+  ].join("|");
+}
+async function runRules(ctx, filePath) {
   const findings = [];
   const seen = /* @__PURE__ */ new Set();
-  for (const rule of ALL_RULES) {
-    for (const finding of await Promise.resolve(rule(ctx))) {
-      const dedupeKey = [
-        finding.code,
-        finding.severity,
-        finding.selector || "",
-        finding.elementId || "",
-        finding.message
-      ].join("|");
-      if (seen.has(dedupeKey)) continue;
-      seen.add(dedupeKey);
-      findings.push(options.filePath ? { ...finding, file: options.filePath } : finding);
+  const groupMs = {};
+  let slowestRule = "";
+  let slowestRuleMs = 0;
+  for (const { group, rules } of RULE_GROUPS) {
+    for (let index = 0; index < rules.length; index++) {
+      const ruleStartedAt = performance.now();
+      const produced = await Promise.resolve(rules[index](ctx));
+      const ruleMs = performance.now() - ruleStartedAt;
+      groupMs[group] = (groupMs[group] ?? 0) + ruleMs;
+      if (ruleMs > slowestRuleMs) {
+        slowestRuleMs = ruleMs;
+        slowestRule = `${group}#${index}`;
+      }
+      collectFindings(produced, seen, filePath, findings);
     }
   }
+  return { findings, timings: { groupMs, slowestRule, slowestRuleMs } };
+}
+function collectFindings(produced, seen, filePath, into) {
+  for (const finding of produced) {
+    const dedupeKey = dedupeKeyFor(finding);
+    if (seen.has(dedupeKey)) continue;
+    seen.add(dedupeKey);
+    into.push(filePath ? { ...finding, file: filePath } : finding);
+  }
+}
+async function lintHyperframeHtml(html, options = {}) {
+  const startedAt = performance.now();
+  const ctx = buildLintContext(html, options);
+  const { findings, timings } = await runRules(ctx, options.filePath);
   const errorCount = findings.filter((f) => f.severity === "error").length;
   const warningCount = findings.filter((f) => f.severity === "warning").length;
   const infoCount = findings.filter((f) => f.severity === "info").length;
@@ -4841,7 +4660,8 @@ async function lintHyperframeHtml(html, options = {}) {
     errorCount,
     warningCount,
     infoCount,
-    findings
+    findings,
+    timings: { totalMs: performance.now() - startedAt, ...timings }
   };
 }
 function extractMediaUrls(html) {