@hyperframes/lint 0.8.191 → 0.8.192

package/dist/browser.js

@@ -2618,7 +2618,11 @@ function containingCallOffset(script, tokenOffset) {
 }
 
 // src/rules/composition.ts
-import { COMPOSITION_VARIABLE_TYPES, isSafeMediaUrl } from "@hyperframes/parsers/composition";
+import {
+  COMPOSITION_VARIABLE_TYPES,
+  isCompositionVariable,
+  isSafeMediaUrl
+} from "@hyperframes/parsers/composition";
 import { COMPOSITION_ATTRIBUTES, readClipTiming } from "@hyperframes/parsers/composition-contract";
 import { resolveCompositionDuration } from "@hyperframes/parsers/composition-duration";
 import {
@@ -2922,6 +2926,16 @@ function variablesDeclarationFindings(tag, tags) {
       });
       continue;
     }
+    if (!isCompositionVariable(e)) {
+      findings.push({
+        code: "invalid_composition_variables_declaration",
+        severity: "error",
+        message: `data-composition-variables entry [${i}] has a default that does not match its type, or an enum without an options array.`,
+        fixHint: "Use number defaults for number variables, boolean defaults for boolean variables, and string defaults for other types. Enum variables also require an options array.",
+        snippet: truncateSnippet(tag.raw)
+      });
+      continue;
+    }
     const id = String(e.id);
     if ((e.type === "image" || varSrcIds.has(id)) && typeof e.default === "string" && e.default.length > 0 && !isSafeMediaUrl(e.default)) {
       findings.push({
@@ -4960,7 +4974,7 @@ ${right.raw}`)
     return findings;
   },
   // gsap_timeline_registered_before_async_build — registering window.__timelines[id]
-  // BEFORE the timeline is built inside document.fonts.ready (or any async callback)
+  // BEFORE the timeline is built inside a font-ready callback
   // leaves an EMPTY timeline registered. The runtime's sub-composition readiness gate
   // treats "key present" as "ready" and nests the child ONCE, while still empty — so the
   // animation never renders when this composition is mounted as a sub-composition.
@@ -4969,9 +4983,11 @@ ${right.raw}`)
     const findings = [];
     for (const script of scripts) {
       const content = stripJsComments(script.content);
-      const regIdx = content.search(/window\s*\.\s*__timelines\s*\[/);
+      const regIdx = content.search(
+        /window\s*\.\s*__timelines\s*(?:\[[^\]]+\]|\.\s*[A-Za-z_$][\w$]*)\s*=\s*(?!=)/
+      );
       if (regIdx < 0) continue;
-      const fontsReadyIdx = content.search(/document\s*\.\s*fonts\s*\.\s*ready/);
+      const fontsReadyIdx = content.search(/document\s*\.\s*fonts\s*\.\s*(?:ready\b|load\s*\()/);
       if (fontsReadyIdx < 0) continue;
       if (regIdx >= fontsReadyIdx) continue;
       const tail = content.slice(fontsReadyIdx);
@@ -4979,8 +4995,8 @@ ${right.raw}`)
       findings.push({
         code: "gsap_timeline_registered_before_async_build",
         severity: "error",
-        message: 'window.__timelines is assigned BEFORE the timeline is built inside document.fonts.ready. An empty timeline registered early gets nested empty when this composition is used as a sub-composition (the readiness gate treats "key present" as "ready" and never re-nests), so the animation renders blank.',
-        fixHint: "Move the `window.__timelines[id] = tl;` assignment to the END of the document.fonts.ready callback, after the tweens are added. Optionally call window.__hfForceTimelineRebind() right after, to re-nest the populated timeline."
+        message: 'window.__timelines is assigned BEFORE the timeline is built inside document.fonts.ready or document.fonts.load(). An empty timeline registered early gets nested empty when this composition is used as a sub-composition (the readiness gate treats "key present" as "ready" and never re-nests), so the animation renders blank.',
+        fixHint: "Move the `window.__timelines[id] = tl;` assignment to the END of the font-ready callback, after the tweens are added. Optionally call window.__hfForceTimelineRebind() right after, to re-nest the populated timeline."
       });
     }
     return findings;
@@ -6020,22 +6036,29 @@ var GENERIC_FAMILIES = /* @__PURE__ */ new Set([
   "unset",
   "revert"
 ]);
-function stripCssComments2(css) {
-  return css.replace(/\/\*[\s\S]*?\*\//g, " ");
+function parseFontCss(css) {
+  try {
+    return postcss3.parse(css);
+  } catch {
+    return null;
+  }
+}
+function isFontFaceDeclaration(decl) {
+  let parent = decl.parent;
+  while (parent) {
+    if (parent.type === "atrule" && parent.name.toLowerCase() === "font-face") return true;
+    parent = parent.parent;
+  }
+  return false;
 }
 function extractFontFaceFamilies(styles) {
   const families = /* @__PURE__ */ new Set();
-  const fontFaceRe = /@font-face\s*\{[^}]*\}/gi;
-  const familyRe = /font-family\s*:\s*(['"]?)([^;'"]+)\1/i;
   for (const style of styles) {
-    const content = stripCssComments2(style.content);
-    let match;
-    while ((match = fontFaceRe.exec(content)) !== null) {
-      const familyMatch = match[0].match(familyRe);
-      if (familyMatch?.[2]) {
-        families.add(familyMatch[2].trim().toLowerCase());
-      }
-    }
+    parseFontCss(style.content)?.walkDecls(/^font-family$/i, (decl) => {
+      if (!isFontFaceDeclaration(decl)) return;
+      const name = normalizeUsedFontName(decl.value);
+      if (name) families.add(name);
+    });
   }
   return families;
 }
@@ -6044,22 +6067,43 @@ function normalizeUsedFontName(part) {
   if (!name || name.includes("(") || name.includes(")")) return null;
   return name;
 }
+function collectFontCustomProperties(styles) {
+  const properties = /* @__PURE__ */ new Map();
+  for (const style of styles) {
+    parseFontCss(style.content)?.walkDecls(/^--/, (decl) => {
+      if (!isFontFaceDeclaration(decl)) properties.set(decl.prop, decl.value);
+    });
+  }
+  return properties;
+}
+function resolveUsedFontNames(value, properties, resolving = /* @__PURE__ */ new Set()) {
+  return postcss3.list.comma(value).flatMap((part) => {
+    const variable = /^var\(\s*(--[^\s,()]+)\s*(?:,[\s\S]*)?\)$/i.exec(part.trim());
+    if (!variable) {
+      const name = normalizeUsedFontName(part);
+      return name ? [name] : [];
+    }
+    const property = variable[1];
+    if (!property || resolving.has(property) || resolving.size >= 8) return [];
+    const referenced = properties.get(property);
+    if (referenced === void 0) return [];
+    return resolveUsedFontNames(referenced, properties, new Set(resolving).add(property));
+  });
+}
 function extractUsedFontFamilies(styles) {
   const used = [];
   const seen = /* @__PURE__ */ new Set();
-  const propRe = /font-family\s*:\s*([^;}{]+)/gi;
+  const properties = collectFontCustomProperties(styles);
   for (const style of styles) {
-    const withoutFontFace = stripCssComments2(style.content).replace(/@font-face\s*\{[^}]*\}/gi, "");
-    let match;
-    while ((match = propRe.exec(withoutFontFace)) !== null) {
-      for (const part of match[1].split(",")) {
-        const name = normalizeUsedFontName(part);
-        if (name && !GENERIC_FAMILIES.has(name) && !seen.has(name)) {
+    parseFontCss(style.content)?.walkDecls(/^font-family$/i, (decl) => {
+      if (isFontFaceDeclaration(decl)) return;
+      for (const name of resolveUsedFontNames(decl.value, properties)) {
+        if (!GENERIC_FAMILIES.has(name) && !seen.has(name)) {
           seen.add(name);
           used.push(name);
         }
       }
-    }
+    });
   }
   return used;
 }
@@ -6162,15 +6206,12 @@ var fontRules = [
 ];
 function uniqueFontLocation(styles, families, locate) {
   const locations = [];
+  const properties = collectFontCustomProperties(styles);
   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) ?? "")))
+        if (isFontFaceDeclaration(decl)) return;
+        if (!resolveUsedFontNames(decl.value, properties).some((name) => families.includes(name)))
           return;
         locations.push(locate(style, decl.source?.start?.offset));
       });
@@ -6178,7 +6219,7 @@ function uniqueFontLocation(styles, families, locate) {
       return {};
     }
   }
-  return locations.length === 1 ? locations[0] : {};
+  return locations.length === 1 ? locations[0] ?? {} : {};
 }
 
 // src/rules/slideshow.ts

package/dist/index.d.ts

@@ -98,6 +98,6 @@ interface ProjectLintResult {
     totalWarnings: number;
     totalInfos: number;
 }
-declare function lintProject(projectDir: string, entryFile?: string, hostOptions?: Pick<HyperframeLinterOptions, "host">): Promise<ProjectLintResult>;
+declare function lintProject(projectDir: string, entryFile?: string, hostOptions?: Pick<HyperframeLinterOptions, "host" | "isSubComposition">): Promise<ProjectLintResult>;
 
 export { type HyperframeLintFinding, type HyperframeLintResult, type HyperframeLintSeverity, type HyperframeLinterOptions, LINT_RULE_COUNT, LINT_RULE_GROUP_COUNTS, type LintTimings, type ProjectLintResult, lintHyperframeHtml, lintMediaUrls, lintProject, shouldBlockRender };

package/dist/index.js

@@ -2624,7 +2624,11 @@ function containingCallOffset(script, tokenOffset) {
 }
 
 // src/rules/composition.ts
-import { COMPOSITION_VARIABLE_TYPES, isSafeMediaUrl } from "@hyperframes/parsers/composition";
+import {
+  COMPOSITION_VARIABLE_TYPES,
+  isCompositionVariable,
+  isSafeMediaUrl
+} from "@hyperframes/parsers/composition";
 import { COMPOSITION_ATTRIBUTES, readClipTiming } from "@hyperframes/parsers/composition-contract";
 import { resolveCompositionDuration } from "@hyperframes/parsers/composition-duration";
 import {
@@ -2928,6 +2932,16 @@ function variablesDeclarationFindings(tag, tags) {
       });
       continue;
     }
+    if (!isCompositionVariable(e)) {
+      findings.push({
+        code: "invalid_composition_variables_declaration",
+        severity: "error",
+        message: `data-composition-variables entry [${i}] has a default that does not match its type, or an enum without an options array.`,
+        fixHint: "Use number defaults for number variables, boolean defaults for boolean variables, and string defaults for other types. Enum variables also require an options array.",
+        snippet: truncateSnippet(tag.raw)
+      });
+      continue;
+    }
     const id = String(e.id);
     if ((e.type === "image" || varSrcIds.has(id)) && typeof e.default === "string" && e.default.length > 0 && !isSafeMediaUrl(e.default)) {
       findings.push({
@@ -4966,7 +4980,7 @@ ${right.raw}`)
     return findings;
   },
   // gsap_timeline_registered_before_async_build — registering window.__timelines[id]
-  // BEFORE the timeline is built inside document.fonts.ready (or any async callback)
+  // BEFORE the timeline is built inside a font-ready callback
   // leaves an EMPTY timeline registered. The runtime's sub-composition readiness gate
   // treats "key present" as "ready" and nests the child ONCE, while still empty — so the
   // animation never renders when this composition is mounted as a sub-composition.
@@ -4975,9 +4989,11 @@ ${right.raw}`)
     const findings = [];
     for (const script of scripts) {
       const content = stripJsComments(script.content);
-      const regIdx = content.search(/window\s*\.\s*__timelines\s*\[/);
+      const regIdx = content.search(
+        /window\s*\.\s*__timelines\s*(?:\[[^\]]+\]|\.\s*[A-Za-z_$][\w$]*)\s*=\s*(?!=)/
+      );
       if (regIdx < 0) continue;
-      const fontsReadyIdx = content.search(/document\s*\.\s*fonts\s*\.\s*ready/);
+      const fontsReadyIdx = content.search(/document\s*\.\s*fonts\s*\.\s*(?:ready\b|load\s*\()/);
       if (fontsReadyIdx < 0) continue;
       if (regIdx >= fontsReadyIdx) continue;
       const tail = content.slice(fontsReadyIdx);
@@ -4985,8 +5001,8 @@ ${right.raw}`)
       findings.push({
         code: "gsap_timeline_registered_before_async_build",
         severity: "error",
-        message: 'window.__timelines is assigned BEFORE the timeline is built inside document.fonts.ready. An empty timeline registered early gets nested empty when this composition is used as a sub-composition (the readiness gate treats "key present" as "ready" and never re-nests), so the animation renders blank.',
-        fixHint: "Move the `window.__timelines[id] = tl;` assignment to the END of the document.fonts.ready callback, after the tweens are added. Optionally call window.__hfForceTimelineRebind() right after, to re-nest the populated timeline."
+        message: 'window.__timelines is assigned BEFORE the timeline is built inside document.fonts.ready or document.fonts.load(). An empty timeline registered early gets nested empty when this composition is used as a sub-composition (the readiness gate treats "key present" as "ready" and never re-nests), so the animation renders blank.',
+        fixHint: "Move the `window.__timelines[id] = tl;` assignment to the END of the font-ready callback, after the tweens are added. Optionally call window.__hfForceTimelineRebind() right after, to re-nest the populated timeline."
       });
     }
     return findings;
@@ -6026,22 +6042,29 @@ var GENERIC_FAMILIES = /* @__PURE__ */ new Set([
   "unset",
   "revert"
 ]);
-function stripCssComments2(css) {
-  return css.replace(/\/\*[\s\S]*?\*\//g, " ");
+function parseFontCss(css) {
+  try {
+    return postcss3.parse(css);
+  } catch {
+    return null;
+  }
+}
+function isFontFaceDeclaration(decl) {
+  let parent = decl.parent;
+  while (parent) {
+    if (parent.type === "atrule" && parent.name.toLowerCase() === "font-face") return true;
+    parent = parent.parent;
+  }
+  return false;
 }
 function extractFontFaceFamilies(styles) {
   const families = /* @__PURE__ */ new Set();
-  const fontFaceRe = /@font-face\s*\{[^}]*\}/gi;
-  const familyRe = /font-family\s*:\s*(['"]?)([^;'"]+)\1/i;
   for (const style of styles) {
-    const content = stripCssComments2(style.content);
-    let match;
-    while ((match = fontFaceRe.exec(content)) !== null) {
-      const familyMatch = match[0].match(familyRe);
-      if (familyMatch?.[2]) {
-        families.add(familyMatch[2].trim().toLowerCase());
-      }
-    }
+    parseFontCss(style.content)?.walkDecls(/^font-family$/i, (decl) => {
+      if (!isFontFaceDeclaration(decl)) return;
+      const name = normalizeUsedFontName(decl.value);
+      if (name) families.add(name);
+    });
   }
   return families;
 }
@@ -6050,22 +6073,43 @@ function normalizeUsedFontName(part) {
   if (!name || name.includes("(") || name.includes(")")) return null;
   return name;
 }
+function collectFontCustomProperties(styles) {
+  const properties = /* @__PURE__ */ new Map();
+  for (const style of styles) {
+    parseFontCss(style.content)?.walkDecls(/^--/, (decl) => {
+      if (!isFontFaceDeclaration(decl)) properties.set(decl.prop, decl.value);
+    });
+  }
+  return properties;
+}
+function resolveUsedFontNames(value, properties, resolving = /* @__PURE__ */ new Set()) {
+  return postcss3.list.comma(value).flatMap((part) => {
+    const variable = /^var\(\s*(--[^\s,()]+)\s*(?:,[\s\S]*)?\)$/i.exec(part.trim());
+    if (!variable) {
+      const name = normalizeUsedFontName(part);
+      return name ? [name] : [];
+    }
+    const property = variable[1];
+    if (!property || resolving.has(property) || resolving.size >= 8) return [];
+    const referenced = properties.get(property);
+    if (referenced === void 0) return [];
+    return resolveUsedFontNames(referenced, properties, new Set(resolving).add(property));
+  });
+}
 function extractUsedFontFamilies(styles) {
   const used = [];
   const seen = /* @__PURE__ */ new Set();
-  const propRe = /font-family\s*:\s*([^;}{]+)/gi;
+  const properties = collectFontCustomProperties(styles);
   for (const style of styles) {
-    const withoutFontFace = stripCssComments2(style.content).replace(/@font-face\s*\{[^}]*\}/gi, "");
-    let match;
-    while ((match = propRe.exec(withoutFontFace)) !== null) {
-      for (const part of match[1].split(",")) {
-        const name = normalizeUsedFontName(part);
-        if (name && !GENERIC_FAMILIES.has(name) && !seen.has(name)) {
+    parseFontCss(style.content)?.walkDecls(/^font-family$/i, (decl) => {
+      if (isFontFaceDeclaration(decl)) return;
+      for (const name of resolveUsedFontNames(decl.value, properties)) {
+        if (!GENERIC_FAMILIES.has(name) && !seen.has(name)) {
           seen.add(name);
           used.push(name);
         }
       }
-    }
+    });
   }
   return used;
 }
@@ -6168,15 +6212,12 @@ var fontRules = [
 ];
 function uniqueFontLocation(styles, families, locate) {
   const locations = [];
+  const properties = collectFontCustomProperties(styles);
   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) ?? "")))
+        if (isFontFaceDeclaration(decl)) return;
+        if (!resolveUsedFontNames(decl.value, properties).some((name) => families.includes(name)))
           return;
         locations.push(locate(style, decl.source?.start?.offset));
       });
@@ -6184,7 +6225,7 @@ function uniqueFontLocation(styles, families, locate) {
       return {};
     }
   }
-  return locations.length === 1 ? locations[0] : {};
+  return locations.length === 1 ? locations[0] ?? {} : {};
 }
 
 // src/rules/slideshow.ts
@@ -6750,6 +6791,7 @@ import {
 } from "@hyperframes/parsers/reference-resolver";
 import { checkSubCompositionUsability } from "@hyperframes/parsers/sub-composition-validity";
 import { parseHTML as parseHTML3 } from "linkedom";
+import postcss4 from "postcss";
 import {
   cleanAssetUrl as cleanAssetUrl2,
   collectSubCompositionSrcs,
@@ -7070,6 +7112,7 @@ function contentDigest(html) {
   return createHash("sha256").update(html).digest("hex").slice(0, 16);
 }
 var AUDIO_EXTENSIONS = /* @__PURE__ */ new Set([".mp3", ".wav", ".aac", ".ogg", ".m4a", ".flac", ".opus"]);
+var CSS_URL_RE = /\burl\(\s*(?:"([^"]+)"|'([^']+)'|([^"')\s]+))\s*\)/gi;
 var MASK_IMAGE_URL_RE = /\b(?:-webkit-)?mask-image\s*:\s*[^;{}]*url\(\s*(?:"([^"]+)"|'([^']+)'|([^"')\s]+))\s*\)/gi;
 function isLocalStylesheetHref(href) {
   return !!href && !/^(https?:|data:|blob:|\/\/)/i.test(href);
@@ -7362,9 +7405,16 @@ function lintTextureMaskAssetNotFound(projectDir, htmlSources) {
   for (const { html, compSrcPath } of htmlSources) {
     const file = sourceFile(projectDir, compSrcPath);
     for (const cssSource of collectCssSources(projectDir, html, compSrcPath)) {
-      let match;
-      const pattern = new RegExp(MASK_IMAGE_URL_RE.source, MASK_IMAGE_URL_RE.flags);
-      while ((match = pattern.exec(cssSource.content)) !== null) {
+      let matches = [];
+      try {
+        postcss4.parse(cssSource.content).walkDecls(/^(?:-webkit-)?mask-image$/i, (declaration) => {
+          matches.push(...declaration.value.matchAll(CSS_URL_RE));
+        });
+      } catch (error) {
+        if (!(error instanceof postcss4.CssSyntaxError)) throw error;
+        matches = [...cssSource.content.matchAll(MASK_IMAGE_URL_RE)];
+      }
+      for (const match of matches) {
         const rawUrl = match[1] ?? match[2] ?? match[3] ?? "";
         if (isUnresolvedAssetPlaceholder2(rawUrl)) continue;
         const url = cleanAssetUrl2(rawUrl);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/lint",
-  "version": "0.8.191",
+  "version": "0.8.192",
   "repository": {
     "type": "git",
     "url": "https://github.com/heygen-com/hyperframes",
@@ -35,7 +35,7 @@
     "linkedom": "^0.18.12",
     "postcss": "^8.5.8",
     "postcss-selector-parser": "^7.1.4",
-    "@hyperframes/parsers": "0.8.191"
+    "@hyperframes/parsers": "0.8.192"
   },
   "devDependencies": {
     "@types/node": "^25.0.10",