@hyperframes/lint 0.7.21 → 0.7.23

package/dist/index.js

@@ -222,8 +222,12 @@ function truncateSnippet(value, maxLength = 220) {
 function buildLintContext(html, options = {}) {
   const rawSource = html || "";
   let source = stripHtmlComments(rawSource);
+  const sourceWithoutTemplates = source.replace(
+    /<template\b[^>]*>[\s\S]*?<\/template(?:\s[^>]*)?>/gi,
+    " "
+  );
   const templateMatch = source.match(/<template[^>]*>([\s\S]*)<\/template>/i);
-  if (templateMatch?.[1]) source = templateMatch[1];
+  if (templateMatch?.[1] && !findRootTag(sourceWithoutTemplates)) source = templateMatch[1];
   const tags = extractOpenTags(source);
   const styles = [
     ...extractBlocks(source, STYLE_BLOCK_PATTERN),
@@ -294,6 +298,8 @@ var STRAY_HEAD_CLOSE_PATTERN = /<\/(?:style|script)(?:\s[^>]*)?>/i;
 var MARKDOWN_CODE_FENCE_PATTERN = /```[^\r\n`]*(?:\r?\n|$)[\s\S]*?```/i;
 var ORPHAN_CSS_AT_RULE_PATTERN = /(?:^|\s)@(?:container|font-face|keyframes|layer|media|page|property|scope|supports)[^{<]*\{[\s\S]*?:[\s\S]*?\}/i;
 var ORPHAN_CSS_RULE_PATTERN = /(?:^|\s)(?:\/\*[\s\S]*?\*\/\s*)?(?:@[a-z-]+[^{}<]*|[.#][\w-]+[^{}<]*|[a-z][\w-]*(?:\s+[.#:[\w-][^{}<]*)?)\s*\{[^{}]*:[^{}]*\}/i;
+var VISIBLE_MARKUP_COMMENT_PATTERN = /\/\*[\s\S]*?\*\//g;
+var VISIBLE_MARKUP_COMMENT_PROTECTED_BLOCK_PATTERN = /<(style|script|template|title|noscript|pre|code|textarea|text)\b[^>]*>[\s\S]*?<\/\1(?:\s[^>]*)?>/gi;
 function findCodeFenceLeak(headWithoutValidBlocks) {
   return MARKDOWN_CODE_FENCE_PATTERN.exec(headWithoutValidBlocks)?.[0] ?? null;
 }
@@ -332,6 +338,46 @@ function findLeakedTextBeforeCompositionRoot(source, rootTag) {
   if (prefixEnd <= prefixStart) return null;
   return findLeakedTextInHeadContent(source.slice(prefixStart, prefixEnd));
 }
+function findProtectedVisibleMarkupRanges(source) {
+  const ranges = [];
+  for (const match of source.matchAll(VISIBLE_MARKUP_COMMENT_PROTECTED_BLOCK_PATTERN)) {
+    ranges.push({ start: match.index, end: match.index + match[0].length });
+  }
+  return ranges;
+}
+function isInsideSourceRange(index, ranges) {
+  return ranges.some((range) => range.start <= index && index < range.end);
+}
+function isInsideHtmlTag(source, index) {
+  let inTag = false;
+  let quote = null;
+  for (let i = 0; i < index; i++) {
+    const char = source[i];
+    if (!inTag) {
+      if (char === "<") inTag = true;
+      continue;
+    }
+    if (quote) {
+      if (char === quote) quote = null;
+      continue;
+    }
+    if (char === '"' || char === "'") {
+      quote = char;
+    } else if (char === ">") {
+      inTag = false;
+    }
+  }
+  return inTag;
+}
+function findVisibleMarkupCommentLeak(source) {
+  const protectedRanges = findProtectedVisibleMarkupRanges(source);
+  for (const match of source.matchAll(VISIBLE_MARKUP_COMMENT_PATTERN)) {
+    if (isInsideHtmlTag(source, match.index)) continue;
+    if (isInsideSourceRange(match.index, protectedRanges)) continue;
+    return match[0];
+  }
+  return null;
+}
 var coreRules = [
   // root_missing_composition_id + root_missing_dimensions
   ({ rootTag }) => {
@@ -372,6 +418,20 @@ var coreRules = [
       }
     ];
   },
+  // visible_markup_comment
+  ({ source }) => {
+    const snippet = findVisibleMarkupCommentLeak(source);
+    if (!snippet) return [];
+    return [
+      {
+        code: "visible_markup_comment",
+        severity: "error",
+        message: "CSS/JS block comment syntax (`/* ... */`) appears in visible HTML markup. HTML only treats `<!-- ... -->` as comments, so this renders as on-screen text.",
+        fixHint: "Remove the text or convert it to a real HTML comment (`<!-- ... -->`). Keep CSS comments inside `<style>` and JS comments inside `<script>`.",
+        snippet: truncateSnippet(snippet)
+      }
+    ];
+  },
   // missing_timeline_registry + timeline_registry_missing_init
   ({ source, rawSource, options }) => {
     if (options.isSubComposition || rawSource.trimStart().toLowerCase().startsWith("<template")) {
@@ -1127,6 +1187,7 @@ async function loadParseGsapScript() {
   return mod.parseGsapScriptAcorn;
 }
 var SCENE_BOUNDARY_EPSILON_SECONDS = 0.05;
+var UNRESOLVED_TARGET = "__unresolved__";
 function countClassUsage(tags) {
   const counts = /* @__PURE__ */ new Map();
   for (const tag of tags) {
@@ -1489,6 +1550,7 @@ var gsapRules = [
         const left = gsapWindows[i];
         if (!left) continue;
         if (left.end <= left.position) continue;
+        if (left.targetSelector === UNRESOLVED_TARGET) continue;
         for (let j = i + 1; j < gsapWindows.length; j++) {
           const right = gsapWindows[j];
           if (!right) continue;
@@ -1515,6 +1577,7 @@ ${right.raw}`)
       }
       if (clipStartBoundaries.length > 0) {
         for (const win of gsapWindows) {
+          if (win.targetSelector === UNRESOLVED_TARGET) continue;
           if (!isSceneBoundaryExit(win)) continue;
           const boundary = findMatchingSceneBoundary(win.end, clipStartBoundaries);
           if (boundary == null) continue;
@@ -2719,6 +2782,91 @@ var compositionRules = [
         snippet: truncateSnippet(rootTag.raw)
       }
     ];
+  },
+  // root_composition_missing_duration_source
+  //
+  // The render engine (packages/engine/src/services/frameCapture.ts) needs a
+  // positive window.__hf.duration to know how many frames to capture. GSAP
+  // timelines set this automatically. Non-GSAP runtimes (CSS, WAAPI, Lottie)
+  // are now auto-inferred by the runtime too (see
+  // packages/core/src/runtime/init.ts resolveAdapterDurationFloorSeconds and
+  // the adapters' getInferredDurationSeconds) — so data-duration is optional
+  // wherever the runtime can work it out on its own.
+  //
+  // This rule fires for cases where the total render length is not reliably
+  // determinable without an explicit data-duration:
+  //   - No GSAP timeline AND no data-duration AND no non-GSAP animation
+  //     signal at all (nothing for any adapter to discover — render fails).
+  //   - Three.js used with no data-duration (no discoverable AnimationClip
+  //     duration in this codebase's adapter — see adapters/three.ts).
+  //   - Any infinite CSS animation-iteration-count with no data-duration,
+  //     EVEN when a finite CSS animation is present alongside it. An unbounded
+  //     animation makes the intended total length ambiguous — the runtime will
+  //     infer a finite sibling's length if one exists, but that's a fallback,
+  //     not a declaration of intent, so we still require data-duration here.
+  //     (This is intentionally stricter than the runtime's own inference.)
+  // Purely finite CSS/WAAPI animations and Lottie are excluded — the runtime
+  // infers those unambiguously, so requiring data-duration there would be a
+  // false positive against the runtime's own auto-inference. Note lint is
+  // advisory by default (see shouldBlockRender) — it only blocks render under
+  // --strict/--strict-all — so a strict flag here nudges toward an explicit,
+  // guaranteed-correct value without failing renders that would succeed.
+  // fallow-ignore-next-line complexity
+  ({ rootTag, scripts, styles, tags, options }) => {
+    if (options.isSubComposition) return [];
+    if (!rootTag) return [];
+    if (readAttr(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));
+    const hasRegisteredTimeline = allScriptTexts.some(
+      (t) => WINDOW_TIMELINE_ASSIGN_PATTERN.test(t)
+    );
+    if (hasGsapTimeline && hasRegisteredTimeline) return [];
+    const allCss = styles.map((s) => s.content).join("\n");
+    const allInlineStyles = tags.map((t) => readAttr(t.raw, "style") || "").join("\n");
+    const combinedCss = `${allCss}
+${allInlineStyles}`.replace(/\/\*[\s\S]*?\*\//g, "");
+    const usesLottie = tags.some((t) => readAttr(t.raw, "data-lottie-src") !== null) || allScriptTexts.some((t) => /lottie\.(loadAnimation)\b|__hfLottie\b/.test(t));
+    const usesThree = allScriptTexts.some((t) => /\bTHREE\./.test(t));
+    const usesWaapi = allScriptTexts.some((t) => /\.animate\s*\(\s*[[{$A-Za-z_]/.test(t));
+    const hasCssAnimationName = /\banimation(?:-name)?\s*:/.test(combinedCss);
+    const hasInfiniteCssAnimation = /\banimation(?:-iteration-count)?\s*:[^;{}]*(?<![\w-])infinite(?![\w-])/.test(combinedCss);
+    const hasAnyNonGsapSignal = usesLottie || usesThree || usesWaapi || hasCssAnimationName;
+    if (!hasAnyNonGsapSignal) {
+      return [
+        {
+          code: "root_composition_missing_duration_source",
+          severity: "error",
+          message: 'Root composition has no data-duration, no GSAP timeline, and no CSS/WAAPI/Lottie/Three.js animation for the runtime to infer a duration from. The render engine cannot determine how long to capture and will fail with "Composition has zero duration".',
+          fixHint: 'Add data-duration="<seconds>" to the root element, or add a paused GSAP timeline registered on window.__timelines.',
+          snippet: truncateSnippet(rootTag.raw)
+        }
+      ];
+    }
+    if (usesThree) {
+      return [
+        {
+          code: "root_composition_missing_duration_source",
+          severity: "error",
+          message: `Root composition uses Three.js with no data-duration. The runtime cannot discover a Three.js scene's duration automatically (no AnimationClip/AnimationMixer inspection) \u2014 render will fail with "Composition has zero duration".`,
+          fixHint: 'Add data-duration="<seconds>" to the root element.',
+          snippet: truncateSnippet(rootTag.raw)
+        }
+      ];
+    }
+    if (hasInfiniteCssAnimation && !usesLottie && !usesWaapi) {
+      return [
+        {
+          code: "root_composition_missing_duration_source",
+          severity: "error",
+          message: 'Root composition uses a CSS animation with animation-iteration-count: infinite and no data-duration, so the intended total length is ambiguous. If a finite animation is also present the runtime infers that length; with no finite source the render fails with "Composition has zero duration". Declare the intended length explicitly.',
+          fixHint: 'Add data-duration="<seconds>" to the root element with the intended total length.',
+          snippet: truncateSnippet(rootTag.raw)
+        }
+      ];
+    }
+    return [];
   }
 ];
 
@@ -2751,7 +2899,7 @@ var adapterRules = [
       (t) => /["']three["']/.test(t) && /importmap/.test(scripts.find((s) => s.content === t)?.attrs || "")
     );
     const hasThreeModuleImport = texts.some(
-      (t) => /\bimport\b.*['"]three['"]/.test(t) || /\bfrom\s+['"]three['"]/.test(t)
+      (t) => /\b(?:import|from)\s*[^;\n]*['"][^'"]*three[^'"]*['"]/i.test(t)
     );
     if (!usesThree || hasThreeScript || hasThreeImportMap || hasThreeModuleImport) return [];
     return [
@@ -2958,6 +3106,12 @@ var GENERIC_FAMILIES = /* @__PURE__ */ new Set([
   "math",
   "emoji",
   "fangsong",
+  // Vendor-prefixed system-font keywords. Like `system-ui`, the engine resolves
+  // these to the OS UI font — they are never installable files and must not be
+  // flagged as a missing @font-face, even when a generic fallback follows them
+  // (e.g. `-apple-system, system-ui, sans-serif`).
+  "-apple-system",
+  "blinkmacsystemfont",
   "inherit",
   "initial",
   "unset",
@@ -2982,6 +3136,11 @@ function extractFontFaceFamilies(styles) {
   }
   return families;
 }
+function normalizeUsedFontName(part) {
+  const name = part.trim().replace(/^['"]|['"]$/g, "").trim().toLowerCase();
+  if (!name || name.includes("(") || name.includes(")")) return null;
+  return name;
+}
 function extractUsedFontFamilies(styles) {
   const used = [];
   const seen = /* @__PURE__ */ new Set();
@@ -2990,9 +3149,8 @@ function extractUsedFontFamilies(styles) {
     const withoutFontFace = stripCssComments(style.content).replace(/@font-face\s*\{[^}]*\}/gi, "");
     let match;
     while ((match = propRe.exec(withoutFontFace)) !== null) {
-      const stack = match[1];
-      for (const part of stack.split(",")) {
-        const name = part.trim().replace(/^['"]|['"]$/g, "").trim().toLowerCase();
+      for (const part of match[1].split(",")) {
+        const name = normalizeUsedFontName(part);
         if (name && !GENERIC_FAMILIES.has(name) && !seen.has(name)) {
           seen.add(name);
           used.push(name);
@@ -3301,6 +3459,11 @@ import { existsSync, readFileSync, readdirSync } from "fs";
 import { dirname, extname, isAbsolute, join, posix, relative, resolve } from "path";
 import { decodeUrlPathVariants } from "@hyperframes/parsers/composition";
 import { rewriteAssetPath } from "@hyperframes/parsers/asset-paths";
+import { checkSubCompositionUsability } from "@hyperframes/parsers/sub-composition-validity";
+import { parseHTML } from "linkedom";
+function parseSubCompHtml(html) {
+  return parseHTML(html).document;
+}
 var AUDIO_EXTENSIONS = /* @__PURE__ */ new Set([".mp3", ".wav", ".aac", ".ogg", ".m4a", ".flac", ".opus"]);
 var STYLE_BLOCK_RE = /<style\b[^>]*>([\s\S]*?)<\/style>/gi;
 var OPEN_TAG_RE = /<([a-z][\w:-]*)(\s[^<>]*?)?>/gi;
@@ -3462,7 +3625,8 @@ async function lintProject(projectDir) {
     ...lintMissingLocalAsset(projectDir, allHtmlSources),
     ...lintTextureMaskAssetNotFound(projectDir, allHtmlSources),
     ...lintMultipleRootCompositions(projectDir),
-    ...lintDuplicateAudioTracks(allHtmlSources)
+    ...lintDuplicateAudioTracks(allHtmlSources),
+    ...lintMissingOrEmptySubComposition(projectDir, rootHtml)
   ];
   if (projectFindings.length > 0) {
     for (const finding of projectFindings) {
@@ -3680,6 +3844,52 @@ function lintDuplicateAudioTracks(htmlSources) {
   }
   return findings;
 }
+function lintMissingOrEmptySubComposition(projectDir, rootHtml) {
+  const checked = /* @__PURE__ */ new Map();
+  const visited = /* @__PURE__ */ new Set();
+  const walk = (html) => {
+    const compositionSrcRe = /<[^>]*\bdata-composition-src\s*=\s*["']([^"']+)["'][^>]*>/gi;
+    const scannable = maskNonScannableRanges(html);
+    let match;
+    while ((match = compositionSrcRe.exec(scannable)) !== null) {
+      const srcPath = (match[1] ?? "").trim();
+      if (!srcPath) continue;
+      if (/^__[A-Z_]+__$/.test(srcPath)) continue;
+      const filePath = resolve(projectDir, srcPath);
+      if (visited.has(filePath)) continue;
+      visited.add(filePath);
+      if (!existsSync(filePath)) {
+        if (!checked.has(srcPath)) {
+          checked.set(srcPath, { srcPath, problem: "the file does not exist" });
+        }
+        continue;
+      }
+      const fileHtml = readFileSync(filePath, "utf-8");
+      const validity = checkSubCompositionUsability(fileHtml, parseSubCompHtml);
+      if (!validity.ok) {
+        if (!checked.has(srcPath)) {
+          checked.set(srcPath, {
+            srcPath,
+            problem: validity.detail ?? "the file is empty or could not be parsed"
+          });
+        }
+        continue;
+      }
+      walk(fileHtml);
+    }
+  };
+  walk(rootHtml);
+  const findings = [];
+  for (const { srcPath, problem } of checked.values()) {
+    findings.push({
+      code: "missing_or_empty_sub_composition",
+      severity: "error",
+      message: `data-composition-src references "${srcPath}", but ${problem}.`,
+      fixHint: `Fix this before rendering \u2014 the render pre-flight rejects unusable sub-compositions. Write valid HTML into "${srcPath}" \u2014 it needs a <template> or <body> containing an element with data-composition-id, data-width, and data-height. Preview/studio still tolerates and skips the scene while you author it. If a scene-authoring step is still running, wait for it to finish before referencing the file, or re-run the step that generates it.`
+    });
+  }
+  return findings;
+}
 export {
   lintHyperframeHtml,
   lintMediaUrls,