@hyperframes/lint 0.8.66 → 0.8.68

package/dist/browser.d.ts

@@ -4,6 +4,9 @@ type HyperframeLintFinding = {
     severity: HyperframeLintSeverity;
     message: string;
     file?: string;
+    /** One-based coordinates in the original source; absent when no unique location exists. */
+    line?: number;
+    column?: number;
     selector?: string;
     elementId?: string;
     fixHint?: string;
@@ -36,6 +39,7 @@ type HyperframeLinterOptions = {
     externalStyles?: Array<{
         href: string;
         content: string;
+        file?: string;
     }>;
     /**
      * Set to `true` when linting compositions destined for distributed / Lambda

package/dist/browser.js

@@ -1,5 +1,9 @@
+// src/sourceLocations.ts
+import { Parser as Parser2 } from "htmlparser2";
+
 // src/utils.ts
 import { Parser } from "htmlparser2";
+import { parse } from "acorn";
 var COMPOSITION_ID_IN_CSS_PATTERN = /\[data-composition-id=["']([^"']+)["']\]/g;
 var TIMELINE_REGISTRY_INIT_PATTERN = /window\.__timelines\s*=\s*window\.__timelines\s*\|\|\s*\{\}|window\.__timelines\s*=\s*\{\}|window\.__timelines\s*\?\?=\s*\{\}/i;
 var TIMELINE_REGISTRY_OBJECT_LITERAL_PATTERN = /window\.__timelines\s*=\s*\{\s*(?:["'][^"']+["']|[A-Za-z_$][\w$]*)\s*:/i;
@@ -53,6 +57,7 @@ function parseHtmlStructure(source) {
         blocks[name].push({
           attrs: block.attrs,
           content: source.slice(block.contentStart, parser.startIndex),
+          contentStart: block.contentStart,
           raw: source.slice(block.index, parser.endIndex + 1),
           index: block.index
         });
@@ -202,11 +207,17 @@ function readTimelineRegistryTopLevelKeys(source) {
 function getInlineScriptSyntaxError(source) {
   if (!source.trim()) return null;
   try {
-    new Function(source);
+    parse(source, {
+      ecmaVersion: "latest",
+      sourceType: "script",
+      allowReturnOutsideFunction: true
+    });
     return null;
   } catch (error) {
-    if (error instanceof Error) return error.message;
-    return String(error);
+    return {
+      message: error instanceof Error ? error.message : String(error),
+      offset: error instanceof SyntaxError && "pos" in error && typeof error.pos === "number" ? error.pos : void 0
+    };
   }
 }
 function stripStringLiterals(source) {
@@ -525,7 +536,7 @@ function stripCssComments(source) {
   }
   return out;
 }
-function stripHtmlCommentsOnce(source) {
+function stripHtmlCommentsOnce(source, removed) {
   let out = "";
   let i = 0;
   for (; ; ) {
@@ -534,14 +545,17 @@ function stripHtmlCommentsOnce(source) {
     const end = source.indexOf("-->", start + 4);
     if (end < 0) return out + source.slice(i);
     out += source.slice(i, start);
+    removed?.(start, end + 3);
     i = end + 3;
   }
 }
-function stripHtmlComments(source) {
+function stripHtmlComments(source, pass) {
   let out = source;
   for (let prev = ""; prev !== out; ) {
     prev = out;
-    out = stripHtmlCommentsOnce(out);
+    const ranges = [];
+    out = stripHtmlCommentsOnce(out, pass ? (start, end) => ranges.push([start, end]) : void 0);
+    if (ranges.length) pass?.(ranges);
   }
   return out;
 }
@@ -557,16 +571,100 @@ function hasCaptionStyles(styles) {
   return styles.some((s) => /\.caption[-_]?(?:group|word)/i.test(s.content));
 }
 function truncateSnippet(value, maxLength = 220) {
-  const normalized = value.replace(/\s+/g, " ").trim();
-  if (!normalized) return void 0;
-  if (normalized.length <= maxLength) return normalized;
-  return `${normalized.slice(0, maxLength - 3)}...`;
+  const normalized2 = value.replace(/\s+/g, " ").trim();
+  if (!normalized2) return void 0;
+  if (normalized2.length <= maxLength) return normalized2;
+  return `${normalized2.slice(0, maxLength - 3)}...`;
+}
+
+// src/sourceLocations.ts
+function normalized(source) {
+  let text = "";
+  const offsets = [];
+  for (let i = 0; i < source.length; i++) {
+    const char = source[i];
+    if (/\s/.test(char)) {
+      if (text.endsWith(" ")) continue;
+      text += " ";
+    } else text += char;
+    offsets.push(i);
+  }
+  return { text, offsets };
+}
+function createSourceLocator(source) {
+  const tags = parseHtmlStructure(source).tags;
+  const searchable = source.split("");
+  const parser = new Parser2({
+    oncomment() {
+      searchable.fill("\0", parser.startIndex, parser.endIndex + 1);
+    }
+  });
+  parser.write(source);
+  parser.end();
+  const normalizedSource = normalized(searchable.join(""));
+  const at = (offset) => {
+    const before = source.slice(0, offset);
+    return {
+      line: before.split(/\r\n|\r|\n/).length,
+      column: offset - Math.max(before.lastIndexOf("\n"), before.lastIndexOf("\r"))
+    };
+  };
+  return (finding) => {
+    if (finding.line !== void 0) return { line: finding.line, column: finding.column };
+    if (finding.snippet) {
+      const offset = snippetOffset(normalizedSource, finding.snippet);
+      return offset === void 0 ? {} : at(offset);
+    }
+    const id = finding.elementId ?? /^#([\w-]+)$/.exec(finding.selector ?? "")?.[1];
+    if (!id) return {};
+    const matches = tags.filter((tag) => readDecodedAttr(tag.raw, "id") === id);
+    return matches.length === 1 ? at(matches[0].index) : {};
+  };
+}
+function snippetOffset(source, snippet) {
+  const needle = snippet.replace(/\s+/g, " ").trim().replace(/\.\.\.$/, "");
+  if (!needle) return void 0;
+  const index = source.text.indexOf(needle);
+  if (index < 0 || source.text.indexOf(needle, index + 1) >= 0) return void 0;
+  return source.offsets[index];
+}
+
+// src/sourceCoordinates.ts
+function mappedHtmlSource(original) {
+  let offsets;
+  const source = stripHtmlComments(original, (ranges) => {
+    const previous = offsets;
+    const length = (previous?.length ?? original.length + 1) - ranges.reduce((n, [a, b]) => n + b - a, 0);
+    offsets = new Uint32Array(length);
+    let target = 0;
+    let start = 0;
+    const spans = [
+      ...ranges,
+      [previous ? previous.length : original.length + 1, 0]
+    ];
+    for (const [a, b] of spans) {
+      for (let i = start; i < a; i++) offsets[target++] = previous ? previous[i] : i;
+      start = b;
+    }
+  });
+  return { source, originalOffset: (index) => offsets ? offsets[index] : index };
+}
+function sourcePosition(source, offset, file) {
+  if (!Number.isInteger(offset) || offset < 0 || offset > source.length) return {};
+  const before = source.slice(0, offset);
+  return {
+    ...file ? { file } : {},
+    line: before.split(/\r\n|\r|\n/).length,
+    column: offset - Math.max(before.lastIndexOf("\n"), before.lastIndexOf("\r"))
+  };
 }
 
 // src/context.ts
 function buildLintContext(html, options = {}) {
   const rawSource = html || "";
-  let source = stripHtmlComments(rawSource);
+  const mapped = mappedHtmlSource(rawSource);
+  let source = mapped.source;
+  let sourceStart = 0;
   const initialStructure = parseHtmlStructure(source);
   const templateTags = initialStructure.tags.filter(
     (tag) => tag.name === "template" && tag.closeIndex != null
@@ -579,7 +677,8 @@ function buildLintContext(html, options = {}) {
   const template = templateTags[0];
   let structure = initialStructure;
   if (template && !findRootTag(sourceWithoutTemplates)) {
-    source = source.slice(template.index + template.raw.length, template.closeIndex);
+    sourceStart = template.index + template.raw.length;
+    source = source.slice(sourceStart, template.closeIndex);
     structure = parseHtmlStructure(source);
   }
   const tags = structure.tags;
@@ -589,14 +688,23 @@ function buildLintContext(html, options = {}) {
       attrs: `href="${style.href}"`,
       content: style.content,
       raw: style.content,
-      index: -1
+      index: -1,
+      file: style.file ?? style.href
     }))
   ];
   const scripts = structure.scripts;
   const compositionIds = collectCompositionIds(tags);
   const rootTag = findRootTag(source, tags);
   const rootCompositionId = readDecodedAttr(rootTag?.raw || "", "data-composition-id");
+  const locate = (block, offset) => {
+    if (offset === void 0 || offset < 0 || offset > block.content.length) return {};
+    if (block.index === -1) return sourcePosition(block.content, offset, block.file);
+    if (block.contentStart === void 0) return {};
+    const originalOffset = mapped.originalOffset(sourceStart + block.contentStart + offset);
+    return originalOffset === void 0 ? {} : sourcePosition(rawSource, originalOffset, options.filePath);
+  };
   return {
+    locate,
     source,
     rawSource,
     tags,
@@ -616,7 +724,7 @@ import {
   HTML_BODY_CSS_WIDTH_FIRST_RE,
   HTML_BODY_CSS_HEIGHT_FIRST_RE,
   VIEWPORT_META_SIZE_RE
-} from "@hyperframes/parsers";
+} from "@hyperframes/parsers/composition";
 function repeatedDescendantId(selector) {
   let repeated = null;
   const requiredPseudoIds = (pseudo) => {
@@ -994,7 +1102,7 @@ var coreRules = [
     return findings;
   },
   // CSS selector safety
-  ({ styles }) => {
+  ({ styles, locate }) => {
     const findings = [];
     const reportedRepeatedIds = /* @__PURE__ */ new Set();
     const reportedHiddenStyleSelectors = /* @__PURE__ */ new Set();
@@ -1004,6 +1112,10 @@ var coreRules = [
         root = postcss.parse(style.content);
       } catch (error) {
         findings.push({
+          ...locate(
+            style,
+            error instanceof postcss.CssSyntaxError ? cssErrorOffset(style.content, error) : void 0
+          ),
           code: "css_parse_error",
           severity: "error",
           message: `CSS parse error: ${error instanceof Error ? error.message : "unknown"}`
@@ -1069,7 +1181,7 @@ var coreRules = [
     ];
   },
   // invalid_inline_script_syntax (JS parse error)
-  ({ scripts }) => {
+  ({ scripts, locate }) => {
     const findings = [];
     for (const script of scripts) {
       const attrs = script.attrs || "";
@@ -1080,9 +1192,10 @@ var coreRules = [
       const syntaxError = getInlineScriptSyntaxError(script.content);
       if (!syntaxError) continue;
       findings.push({
+        ...locate(script, syntaxError.offset),
         code: "invalid_inline_script_syntax",
         severity: "error",
-        message: `Inline script has invalid syntax: ${syntaxError}`,
+        message: `Inline script has invalid syntax: ${syntaxError.message}`,
         fixHint: "Fix the inline script syntax before render verification.",
         snippet: truncateSnippet(script.content)
       });
@@ -1148,7 +1261,7 @@ var coreRules = [
     return findings;
   },
   // non_deterministic_code
-  ({ scripts }) => {
+  ({ scripts, locate }) => {
     const findings = [];
     const patterns = [
       {
@@ -1199,8 +1312,10 @@ var coreRules = [
       const withoutComments = stripJsComments(script.content);
       const executable = stripStringLiterals(withoutComments);
       for (const { pattern, label, hint, scansStrings } of patterns) {
-        if (pattern.test(scansStrings ? withoutComments : executable)) {
+        const match = pattern.exec(scansStrings ? withoutComments : executable);
+        if (match) {
           findings.push({
+            ...locate(script, match.index),
             code: "non_deterministic_code",
             severity: "error",
             message: `Script contains \`${label}\` which produces non-deterministic output. Renders may differ between frames or runs.`,
@@ -1213,10 +1328,24 @@ var coreRules = [
     return findings;
   }
 ];
+function cssErrorOffset(source, error) {
+  if (error.input && "offset" in error.input && typeof error.input.offset === "number")
+    return error.input.offset;
+  const { line, column } = error;
+  if (line === void 0 || column === void 0) return void 0;
+  let offset = 0;
+  let currentLine = 1;
+  for (const match of source.matchAll(/\n/g)) {
+    if (currentLine >= line) break;
+    offset = match.index + 1;
+    currentLine++;
+  }
+  return currentLine === line ? offset + column - 1 : void 0;
+}
 
 // src/rules/media.ts
 import { validateColorGradingContract } from "@hyperframes/parsers/color-grading-contract";
-import { extractMediaSrcMutations } from "@hyperframes/parsers";
+import { extractMediaSrcMutations } from "@hyperframes/parsers/composition";
 import { parseHTML } from "linkedom";
 function tweensVolumeInSameCall(script, id) {
   const selector = new RegExp(`#${escapeRegExp(id)}(?![\\w-])`, "g");
@@ -1363,18 +1492,18 @@ function classNamesFromAttr(classAttr) {
   return classAttr.split(/\s+/).filter(Boolean);
 }
 function selectorTargetsManagedMedia(selector, mediaIndex) {
-  const normalized = selector.trim();
-  if (!normalized) return false;
-  if (mediaIndex.hasVideo && /\bvideo\b/i.test(normalized)) return true;
-  if (mediaIndex.hasAudio && /\baudio\b/i.test(normalized)) return true;
+  const normalized2 = selector.trim();
+  if (!normalized2) return false;
+  if (mediaIndex.hasVideo && /\bvideo\b/i.test(normalized2)) return true;
+  if (mediaIndex.hasAudio && /\baudio\b/i.test(normalized2)) return true;
   for (const mediaId of mediaIndex.ids) {
     const escapedId = escapeRegExp(mediaId);
-    if (new RegExp(`#${escapedId}(?![\\w-])`).test(normalized) || normalized.includes(`[id="${mediaId}"]`) || normalized.includes(`[id='${mediaId}']`)) {
+    if (new RegExp(`#${escapedId}(?![\\w-])`).test(normalized2) || normalized2.includes(`[id="${mediaId}"]`) || normalized2.includes(`[id='${mediaId}']`)) {
       return true;
     }
   }
   for (const className of mediaIndex.classes) {
-    if (new RegExp(`\\.${escapeRegExp(className)}(?![\\w-])`).test(normalized)) {
+    if (new RegExp(`\\.${escapeRegExp(className)}(?![\\w-])`).test(normalized2)) {
       return true;
     }
   }
@@ -2075,6 +2204,45 @@ function findAudioGroupCarveAttrFindings(ctx) {
   return findings;
 }
 
+// src/scriptPositions.ts
+import { parse as parse2 } from "acorn";
+import { simple } from "acorn-walk";
+var callIndexes = /* @__PURE__ */ new WeakMap();
+function callsFor(script) {
+  const cached = callIndexes.get(script);
+  if (cached) return cached;
+  const calls = [];
+  try {
+    const ast = parse2(script.content, {
+      ecmaVersion: "latest",
+      sourceType: "script",
+      allowReturnOutsideFunction: true
+    });
+    simple(ast, {
+      CallExpression: (node) => {
+        calls.push(node);
+      }
+    });
+  } catch {
+  }
+  calls.sort((a, b) => a.start - b.start);
+  callIndexes.set(script, calls);
+  return calls;
+}
+function gsapCallOffset(script, method) {
+  return callsFor(script).find(
+    ({ callee }) => callee.type === "MemberExpression" && !callee.computed && callee.object.type === "Identifier" && callee.object.name === "gsap" && callee.property.type === "Identifier" && callee.property.name === method
+  )?.start;
+}
+function containingCallOffset(script, tokenOffset) {
+  let start;
+  for (const call of callsFor(script)) {
+    if (call.start > tokenOffset) break;
+    if (call.end > tokenOffset) start = call.start;
+  }
+  return start;
+}
+
 // src/rules/composition.ts
 import { COMPOSITION_VARIABLE_TYPES, isSafeMediaUrl } from "@hyperframes/parsers/composition";
 import { COMPOSITION_ATTRIBUTES, readClipTiming } from "@hyperframes/parsers/composition-contract";
@@ -2113,8 +2281,8 @@ function readTagTiming(rawTag) {
 }
 function countPhysicalLines(source) {
   if (source.length === 0) return 0;
-  const normalized = source.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
-  const withoutFinalNewline = normalized.endsWith("\n") ? normalized.slice(0, -1) : normalized;
+  const normalized2 = source.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+  const withoutFinalNewline = normalized2.endsWith("\n") ? normalized2.slice(0, -1) : normalized2;
   return withoutFinalNewline.split("\n").length;
 }
 function countStructuralLines(source) {
@@ -2127,8 +2295,8 @@ function isCaptionCue(tag) {
 }
 function isRegistrySourceFile(filePath) {
   if (!filePath) return false;
-  const normalized = filePath.replace(/\\/g, "/");
-  return /(?:^|\/)registry\/blocks\/([^/]+)\/\1\.html$/i.test(normalized);
+  const normalized2 = filePath.replace(/\\/g, "/");
+  return /(?:^|\/)registry\/blocks\/([^/]+)\/\1\.html$/i.test(normalized2);
 }
 function isRegistryInstalledFile(rawSource) {
   return /^\s*<!--\s*hyperframes-registry-item:[^>]*-->/i.test(rawSource.slice(0, 512));
@@ -3078,8 +3246,8 @@ function zeroValue(value) {
   return Number(value.trim()) === 0;
 }
 function isGsapColorProperty(property) {
-  const normalized = property.toLowerCase();
-  return !normalized.startsWith("--") && (normalized.endsWith("color") || normalized === "fill" || normalized === "stroke");
+  const normalized2 = property.toLowerCase();
+  return !normalized2.startsWith("--") && (normalized2.endsWith("color") || normalized2 === "fill" || normalized2 === "stroke");
 }
 function collectStaticCssVariableDefinitions(tags, styles) {
   const definitions = /* @__PURE__ */ new Set();
@@ -3206,10 +3374,10 @@ function styleHasHiddenInitialState(style) {
 function styleHasOpaqueBackground(style) {
   const background = readStyleProperty(style, "background") || readStyleProperty(style, "background-color");
   if (!background) return false;
-  const normalized = background.toLowerCase().replace(/\s+/g, "");
-  if (normalized === "transparent" || normalized === "none") return false;
-  if (/rgba?\([^)]*,0(?:\.0+)?\)$/.test(normalized)) return false;
-  if (/hsla?\([^)]*,0(?:\.0+)?\)$/.test(normalized)) return false;
+  const normalized2 = background.toLowerCase().replace(/\s+/g, "");
+  if (normalized2 === "transparent" || normalized2 === "none") return false;
+  if (/rgba?\([^)]*,0(?:\.0+)?\)$/.test(normalized2)) return false;
+  if (/hsla?\([^)]*,0(?:\.0+)?\)$/.test(normalized2)) return false;
   return true;
 }
 function styleLooksFullFrameOverlay(style) {
@@ -3284,8 +3452,8 @@ function targetedSelectorTokens(selector) {
     const compounds = group.trim().split(/[\s>+~]+/).filter(Boolean);
     const last = compounds[compounds.length - 1];
     if (!last) continue;
-    const simple = last.match(/[#.][A-Za-z0-9_-]+/g);
-    if (simple) for (const token of simple) tokens.add(token);
+    const simple2 = last.match(/[#.][A-Za-z0-9_-]+/g);
+    if (simple2) for (const token of simple2) tokens.add(token);
   }
   return tokens;
 }
@@ -3324,7 +3492,7 @@ function scanScriptsForRegexMatches(scripts, pattern, options) {
         content.length,
         match.index + match[0].length + options.contextAfter
       );
-      hits.push({ match, snippet: content.slice(contextStart, contextEnd) });
+      hits.push({ match, snippet: content.slice(contextStart, contextEnd), script });
     }
   }
   return hits;
@@ -3591,9 +3759,9 @@ function elementLevelTokens(tokens, tagsByToken) {
   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;
+  const normalized2 = value.replace(/!important\s*$/i, "").trim();
+  if (!normalized2 || /^none$/i.test(normalized2)) return false;
+  return normalized2.split(/[\s,]+/).filter(Boolean).length >= 2;
 }
 function gsapDasharrayValueLooksMultiComponent(valueSource) {
   const literal = valueSource.trim().match(/^(["'`])([\s\S]*)\1$/)?.[2];
@@ -4030,19 +4198,20 @@ ${right.raw}`)
     return findings;
   },
   // gsap_infinite_repeat
-  ({ scripts, rootTag }) => {
+  ({ scripts, rootTag, locate }) => {
     const findings = [];
     const declaredDuration = Number.parseFloat(
       rootTag ? readAttr(rootTag.raw, "data-duration") ?? "" : ""
     );
     const hasFiniteCompositionWindow = Number.isFinite(declaredDuration) && declaredDuration > 0;
     const pattern = /repeat\s*:\s*-1(?!\d)/g;
-    for (const { snippet } of scanScriptsForRegexMatches(scripts, pattern, {
+    for (const { snippet, match, script } of scanScriptsForRegexMatches(scripts, pattern, {
       stripComments: true,
       contextBefore: 60,
       contextAfter: 60
     })) {
       findings.push({
+        ...locate(script, containingCallOffset(script, match.index)),
         code: "gsap_infinite_repeat",
         severity: hasFiniteCompositionWindow ? "warning" : "error",
         message: hasFiniteCompositionWindow ? `GSAP tween uses \`repeat: -1\` (infinite), but the composition declares a finite ${declaredDuration}s window. HyperFrames clips deterministic seeking and export to that explicit duration.` : "GSAP tween uses `repeat: -1` (infinite) without a finite composition `data-duration`. The timeline can report an unbounded duration and make render planning fail.",
@@ -4053,15 +4222,16 @@ ${right.raw}`)
     return findings;
   },
   // gsap_repeat_ceil_overshoot
-  ({ scripts }) => {
+  ({ scripts, locate }) => {
     const findings = [];
     const pattern = /repeat\s*:\s*Math\.ceil\s*\([^)]+\)\s*-\s*1/g;
-    for (const { snippet } of scanScriptsForRegexMatches(scripts, pattern, {
+    for (const { snippet, match, script } of scanScriptsForRegexMatches(scripts, pattern, {
       stripComments: false,
       contextBefore: 40,
       contextAfter: 40
     })) {
       findings.push({
+        ...locate(script, containingCallOffset(script, match.index)),
         code: "gsap_repeat_ceil_overshoot",
         severity: "warning",
         message: "GSAP repeat calculation uses `Math.ceil` which can overshoot the composition duration. For example, Math.ceil(10.5 / 2) - 1 = 5 repeats \u2192 6 cycles \xD7 2s = 12s, exceeding 10.5s.",
@@ -4072,15 +4242,16 @@ ${right.raw}`)
     return findings;
   },
   // gsap_repeat_floor_unclamped
-  ({ scripts }) => {
+  ({ scripts, locate }) => {
     const findings = [];
     const pattern = /repeat\s*:\s*Math\.floor\s*\([^)]+\)\s*-\s*1/g;
-    for (const { snippet } of scanScriptsForRegexMatches(scripts, pattern, {
+    for (const { snippet, match, script } of scanScriptsForRegexMatches(scripts, pattern, {
       stripComments: false,
       contextBefore: 40,
       contextAfter: 40
     })) {
       findings.push({
+        ...locate(script, containingCallOffset(script, match.index)),
         code: "gsap_repeat_floor_unclamped",
         severity: "warning",
         message: "GSAP repeat calculation can evaluate to -1 when the composition is shorter than one cycle, which GSAP interprets as an infinite repeat.",
@@ -4091,7 +4262,7 @@ ${right.raw}`)
     return findings;
   },
   // gsap_timeline_not_registered
-  ({ scripts, rawSource, options }) => {
+  ({ scripts, rawSource, options, locate }) => {
     const findings = [];
     const canInheritFromHost = options.isSubComposition || rawSource.trimStart().toLowerCase().startsWith("<template");
     for (const script of scripts) {
@@ -4100,6 +4271,7 @@ ${right.raw}`)
       const hasRegistration = WINDOW_TIMELINE_ASSIGN_PATTERN.test(content) || TIMELINE_REGISTRY_OBJECT_LITERAL_PATTERN.test(content);
       if (hasRegistration || canInheritFromHost) continue;
       findings.push({
+        ...locate(script, gsapCallOffset(script, "timeline")),
         code: "gsap_timeline_not_registered",
         severity: "error",
         message: "GSAP timeline is created but never registered in window.__timelines. The runtime discovers timelines from this registry \u2014 without registration, animations will not play during preview or render.",
@@ -5142,6 +5314,7 @@ var textureRules = [
 ];
 
 // src/rules/fonts.ts
+import postcss3 from "postcss";
 import { FONT_ALIAS_KEYS, resolveAliasDisplayName } from "@hyperframes/parsers/composition";
 var GENERIC_FAMILIES = /* @__PURE__ */ new Set([
   "serif",
@@ -5288,7 +5461,7 @@ var fontRules = [
     ];
   },
   // font_family_without_font_face
-  ({ styles, source, rawSource, options }) => {
+  ({ styles, source, rawSource, options, locate }) => {
     if (isRegistrySourceFile(options.filePath) || isRegistryInstalledFile(rawSource)) return [];
     const findings = [];
     const declared = extractFontFaceFamilies(styles);
@@ -5299,6 +5472,7 @@ var fontRules = [
     );
     if (undeclared.length === 0) return findings;
     findings.push({
+      ...uniqueFontLocation(styles, undeclared, locate),
       code: "font_family_without_font_face",
       severity: "error",
       message: `Font ${undeclared.length === 1 ? "family" : "families"} used without @font-face declaration: ${undeclared.join(", ")}. These are not in the auto-resolved font list, so the renderer cannot supply them automatically. Text will fall back to a generic font, producing incorrect typography in the video.`,
@@ -5307,6 +5481,26 @@ var fontRules = [
     return findings;
   }
 ];
+function uniqueFontLocation(styles, families, locate) {
+  const locations = [];
+  for (const style of styles) {
+    try {
+      postcss3.parse(style.content).walkDecls(/^font-family$/i, (decl) => {
+        let parent = decl.parent;
+        while (parent) {
+          if (parent.type === "atrule" && parent.name.toLowerCase() === "font-face") return;
+          parent = parent.parent;
+        }
+        if (!decl.value.split(",").some((part) => families.includes(normalizeUsedFontName(part) ?? "")))
+          return;
+        locations.push(locate(style, decl.source?.start?.offset));
+      });
+    } catch {
+      return {};
+    }
+  }
+  return locations.length === 1 ? locations[0] : {};
+}
 
 // src/rules/slideshow.ts
 import {
@@ -5579,13 +5773,27 @@ function collectFindings(produced, seen, filePath, into) {
     const dedupeKey = dedupeKeyFor(finding);
     if (seen.has(dedupeKey)) continue;
     seen.add(dedupeKey);
-    into.push(filePath ? { ...finding, file: filePath } : finding);
+    into.push(filePath ? { ...finding, file: 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 { findings: rawFindings, timings } = await runRules(ctx, options.filePath);
+  const locate = createSourceLocator(html);
+  const findings = rawFindings.map((finding) => {
+    if (finding.line !== void 0 || finding.code === "invalid_inline_script_syntax" || finding.code === "non_deterministic_code" || [
+      "gsap_infinite_repeat",
+      "gsap_repeat_ceil_overshoot",
+      "gsap_repeat_floor_unclamped"
+    ].includes(finding.code))
+      return finding;
+    if (finding.snippet && options.externalStyles?.some(
+      (style) => style.content.replace(/\s+/g, " ").includes(finding.snippet.replace(/\.\.\.$/, ""))
+    ))
+      return finding;
+    return { ...finding, ...locate(finding) };
+  });
   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;