@hyperframes/lint 0.9.12 → 0.9.14

package/dist/browser.js

@@ -1824,6 +1824,71 @@ function findLinkedClipFindings(ctx) {
   return findings;
 }
 
+// src/rules/audioAttributes.ts
+var AUDIO_ATTRIBUTES = {
+  "data-automation": { list: "lanes", noun: "automation", item: "Lane" },
+  "data-fx-chain": { list: "nodes", noun: "chain", item: "Node" }
+};
+var AUDIO_ATTRIBUTE_VERSION = 1;
+function audioAttributeShapeError(attr, json) {
+  const { list, noun, item } = AUDIO_ATTRIBUTES[attr];
+  const parsed = parseEnvelope(json);
+  if (typeof parsed === "string") return parsed;
+  if (parsed.version !== AUDIO_ATTRIBUTE_VERSION) {
+    return `unsupported ${noun} version: ${String(parsed.version)}`;
+  }
+  const entries = parsed[list];
+  if (!Array.isArray(entries)) return `it is missing a \`${list}\` array`;
+  for (const [i, entry] of entries.entries()) {
+    const reason = entryShapeError(attr, item, i, entry);
+    if (reason) return reason;
+  }
+  return null;
+}
+function parseEnvelope(json) {
+  let raw;
+  try {
+    raw = JSON.parse(json);
+  } catch (err) {
+    return `it is not valid JSON (${err.message})`;
+  }
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw))
+    return "it is not a JSON object";
+  return raw;
+}
+function entryShapeError(attr, item, i, entry) {
+  if (typeof entry !== "object" || entry === null) return `${item} ${i} is not an object`;
+  const fields = entry;
+  if (attr === "data-fx-chain") {
+    return typeof fields.type === "string" ? null : `Node ${i} has no effect \`type\``;
+  }
+  if (typeof fields.target !== "string") return `Lane ${i} has no \`target\``;
+  if (!Array.isArray(fields.points)) return `Lane ${i} is missing a \`points\` array`;
+  return null;
+}
+function findUnreadableAudioAttributeFindings(ctx) {
+  const findings = [];
+  for (const tag of ctx.tags) {
+    for (const attr of Object.keys(AUDIO_ATTRIBUTES)) {
+      const value = readDecodedAttr(tag.raw, attr);
+      if (value === null || value === "") continue;
+      const reason = audioAttributeShapeError(attr, value);
+      if (!reason) continue;
+      const id = readAttr(tag.raw, "id");
+      const { list } = AUDIO_ATTRIBUTES[attr];
+      findings.push({
+        code: "audio_attribute_unreadable",
+        severity: "error",
+        message: `${id ? `#${id}` : `<${tag.name}>`} has a \`${attr}\` the render cannot read: ${reason}. The render fails on it, locally and in the cloud.`,
+        elementId: id || void 0,
+        fixHint: `Write it as {"version": ${AUDIO_ATTRIBUTE_VERSION}, "${list}": [...]}, or remove the attribute.`,
+        snippet: truncateSnippet(tag.raw)
+      });
+    }
+  }
+  return findings;
+}
+
 // src/rules/media.ts
 function tweensVolumeInSameCall(script, id) {
   const selector = new RegExp(`#${escapeRegExp(id)}(?![\\w-])`, "g");
@@ -2556,7 +2621,8 @@ var mediaRules = [
   findAudioGroupCarveAttrFindings,
   // audio_group_holds_elements
   findAudioGroupHoldsElementsFindings,
-  findLinkedClipFindings
+  findLinkedClipFindings,
+  findUnreadableAudioAttributeFindings
 ];
 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));
@@ -6420,7 +6486,11 @@ var textureRules = [
 
 // src/rules/fonts.ts
 import postcss3 from "postcss";
-import { FONT_ALIAS_KEYS, resolveAliasDisplayName } from "@hyperframes/parsers/composition";
+import {
+  FONT_ALIAS_KEYS,
+  parseFontShorthand,
+  resolveAliasDisplayName
+} from "@hyperframes/parsers/composition";
 var GENERIC_FAMILIES = /* @__PURE__ */ new Set([
   "serif",
   "sans-serif",
@@ -6503,14 +6573,20 @@ function resolveUsedFontNames(value, properties, resolving = /* @__PURE__ */ new
     return resolveUsedFontNames(referenced, properties, new Set(resolving).add(property));
   });
 }
+function usedFamilyList(decl) {
+  if (isFontFaceDeclaration(decl)) return "";
+  if (decl.prop.toLowerCase() !== "font") return decl.value;
+  const shorthand = parseFontShorthand(decl.value);
+  return shorthand.certain ? shorthand.families : "";
+}
+var FONT_FAMILY_PROPS = /^font(?:-family)?$/i;
 function extractUsedFontFamilies(styles) {
   const used = [];
   const seen = /* @__PURE__ */ new Set();
   const properties = collectFontCustomProperties(styles);
   for (const style of styles) {
-    parseFontCss(style.content)?.walkDecls(/^font-family$/i, (decl) => {
-      if (isFontFaceDeclaration(decl)) return;
-      for (const name of resolveUsedFontNames(decl.value, properties)) {
+    parseFontCss(style.content)?.walkDecls(FONT_FAMILY_PROPS, (decl) => {
+      for (const name of resolveUsedFontNames(usedFamilyList(decl), properties)) {
         if (!GENERIC_FAMILIES.has(name) && !seen.has(name)) {
           seen.add(name);
           used.push(name);
@@ -6612,9 +6688,33 @@ var fontRules = [
       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.`,
-      fixHint: "Add @font-face { font-family: '...'; src: url('capture/assets/fonts/...woff2'); } for each font family, pointing to the captured .woff2 files. For an OS-bundled system font (e.g. Hiragino Sans, Microsoft YaHei) that has no downloadable file, use src: local('Exact Font Name') instead. The declaration alone satisfies this check without needing a font file."
+      fixHint: "Add @font-face { font-family: '...'; src: url('capture/assets/fonts/...woff2'); } for each font family, pointing to the captured .woff2 files, or switch to a Google Fonts family. An OS font such as PingFang SC or Hiragino Sans renders locally from the installed copy, but a cloud render has no copy and refuses it."
     });
     return findings;
+  },
+  ({ styles, rawSource, options, locate }) => {
+    if (isRegistrySourceFile(options.filePath) || isRegistryInstalledFile(rawSource)) return [];
+    const findings = [];
+    for (const style of styles) {
+      parseFontCss(style.content)?.walkAtRules(/^font-face$/i, (rule) => {
+        let family = null;
+        let sources = "";
+        rule.walkDecls((decl) => {
+          const prop = decl.prop.toLowerCase();
+          if (prop === "font-family") family = normalizeUsedFontName(decl.value);
+          else if (prop === "src") sources += ` ${decl.value}`;
+        });
+        if (!family || !/\blocal\s*\(/i.test(sources) || /\burl\s*\(/i.test(sources)) return;
+        findings.push({
+          ...locate(style, rule.source?.start?.offset),
+          code: "font_face_local_only",
+          severity: "warning",
+          message: `@font-face '${family}' only names a font installed on this machine (src: local()). A local render uses the installed copy; a cloud render or another machine has none and falls back to a different font.`,
+          fixHint: "Add a url() source to the font file (.woff2) inside the project, or use a Google Fonts family, so every render draws the same glyphs."
+        });
+      });
+    }
+    return findings;
   }
 ];
 function uniqueFontLocation(styles, families, locate) {
@@ -6622,10 +6722,9 @@ function uniqueFontLocation(styles, families, locate) {
   const properties = collectFontCustomProperties(styles);
   for (const style of styles) {
     try {
-      postcss3.parse(style.content).walkDecls(/^font-family$/i, (decl) => {
-        if (isFontFaceDeclaration(decl)) return;
-        if (!resolveUsedFontNames(decl.value, properties).some((name) => families.includes(name)))
-          return;
+      postcss3.parse(style.content).walkDecls(FONT_FAMILY_PROPS, (decl) => {
+        const named = resolveUsedFontNames(usedFamilyList(decl), properties);
+        if (!named.some((name) => families.includes(name))) return;
         locations.push(locate(style, decl.source?.start?.offset));
       });
     } catch {

package/dist/index.d.ts

@@ -109,4 +109,11 @@ interface ProjectLintResult {
 declare function collectExternalStyles(projectDir: string, html: string, compSrcPath?: string): NonNullable<HyperframeLinterOptions["externalStyles"]>;
 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, collectExternalStyles, lintHyperframeHtml, lintMediaUrls, lintProject, shouldBlockRender };
+type AudioAttribute = "data-automation" | "data-fx-chain";
+/**
+ * Why the renderer would refuse an audio attribute's value before reading any lane or effect, or null when the
+ * envelope reads. Lane targets and effect types are left to the render: they need core's effect registry.
+ */
+declare function audioAttributeShapeError(attr: AudioAttribute, json: string): string | null;
+
+export { type AudioAttribute, type HyperframeLintFinding, type HyperframeLintResult, type HyperframeLintSeverity, type HyperframeLinterOptions, LINT_RULE_COUNT, LINT_RULE_GROUP_COUNTS, type LintTimings, type ProjectLintResult, audioAttributeShapeError, collectExternalStyles, lintHyperframeHtml, lintMediaUrls, lintProject, shouldBlockRender };

package/dist/index.js

@@ -1830,6 +1830,71 @@ function findLinkedClipFindings(ctx) {
   return findings;
 }
 
+// src/rules/audioAttributes.ts
+var AUDIO_ATTRIBUTES = {
+  "data-automation": { list: "lanes", noun: "automation", item: "Lane" },
+  "data-fx-chain": { list: "nodes", noun: "chain", item: "Node" }
+};
+var AUDIO_ATTRIBUTE_VERSION = 1;
+function audioAttributeShapeError(attr, json) {
+  const { list, noun, item } = AUDIO_ATTRIBUTES[attr];
+  const parsed = parseEnvelope(json);
+  if (typeof parsed === "string") return parsed;
+  if (parsed.version !== AUDIO_ATTRIBUTE_VERSION) {
+    return `unsupported ${noun} version: ${String(parsed.version)}`;
+  }
+  const entries = parsed[list];
+  if (!Array.isArray(entries)) return `it is missing a \`${list}\` array`;
+  for (const [i, entry] of entries.entries()) {
+    const reason = entryShapeError(attr, item, i, entry);
+    if (reason) return reason;
+  }
+  return null;
+}
+function parseEnvelope(json) {
+  let raw;
+  try {
+    raw = JSON.parse(json);
+  } catch (err) {
+    return `it is not valid JSON (${err.message})`;
+  }
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw))
+    return "it is not a JSON object";
+  return raw;
+}
+function entryShapeError(attr, item, i, entry) {
+  if (typeof entry !== "object" || entry === null) return `${item} ${i} is not an object`;
+  const fields = entry;
+  if (attr === "data-fx-chain") {
+    return typeof fields.type === "string" ? null : `Node ${i} has no effect \`type\``;
+  }
+  if (typeof fields.target !== "string") return `Lane ${i} has no \`target\``;
+  if (!Array.isArray(fields.points)) return `Lane ${i} is missing a \`points\` array`;
+  return null;
+}
+function findUnreadableAudioAttributeFindings(ctx) {
+  const findings = [];
+  for (const tag of ctx.tags) {
+    for (const attr of Object.keys(AUDIO_ATTRIBUTES)) {
+      const value = readDecodedAttr(tag.raw, attr);
+      if (value === null || value === "") continue;
+      const reason = audioAttributeShapeError(attr, value);
+      if (!reason) continue;
+      const id = readAttr(tag.raw, "id");
+      const { list } = AUDIO_ATTRIBUTES[attr];
+      findings.push({
+        code: "audio_attribute_unreadable",
+        severity: "error",
+        message: `${id ? `#${id}` : `<${tag.name}>`} has a \`${attr}\` the render cannot read: ${reason}. The render fails on it, locally and in the cloud.`,
+        elementId: id || void 0,
+        fixHint: `Write it as {"version": ${AUDIO_ATTRIBUTE_VERSION}, "${list}": [...]}, or remove the attribute.`,
+        snippet: truncateSnippet(tag.raw)
+      });
+    }
+  }
+  return findings;
+}
+
 // src/rules/media.ts
 function tweensVolumeInSameCall(script, id) {
   const selector = new RegExp(`#${escapeRegExp(id)}(?![\\w-])`, "g");
@@ -2562,7 +2627,8 @@ var mediaRules = [
   findAudioGroupCarveAttrFindings,
   // audio_group_holds_elements
   findAudioGroupHoldsElementsFindings,
-  findLinkedClipFindings
+  findLinkedClipFindings,
+  findUnreadableAudioAttributeFindings
 ];
 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));
@@ -6426,7 +6492,11 @@ var textureRules = [
 
 // src/rules/fonts.ts
 import postcss3 from "postcss";
-import { FONT_ALIAS_KEYS, resolveAliasDisplayName } from "@hyperframes/parsers/composition";
+import {
+  FONT_ALIAS_KEYS,
+  parseFontShorthand,
+  resolveAliasDisplayName
+} from "@hyperframes/parsers/composition";
 var GENERIC_FAMILIES = /* @__PURE__ */ new Set([
   "serif",
   "sans-serif",
@@ -6509,14 +6579,20 @@ function resolveUsedFontNames(value, properties, resolving = /* @__PURE__ */ new
     return resolveUsedFontNames(referenced, properties, new Set(resolving).add(property));
   });
 }
+function usedFamilyList(decl) {
+  if (isFontFaceDeclaration(decl)) return "";
+  if (decl.prop.toLowerCase() !== "font") return decl.value;
+  const shorthand = parseFontShorthand(decl.value);
+  return shorthand.certain ? shorthand.families : "";
+}
+var FONT_FAMILY_PROPS = /^font(?:-family)?$/i;
 function extractUsedFontFamilies(styles) {
   const used = [];
   const seen = /* @__PURE__ */ new Set();
   const properties = collectFontCustomProperties(styles);
   for (const style of styles) {
-    parseFontCss(style.content)?.walkDecls(/^font-family$/i, (decl) => {
-      if (isFontFaceDeclaration(decl)) return;
-      for (const name of resolveUsedFontNames(decl.value, properties)) {
+    parseFontCss(style.content)?.walkDecls(FONT_FAMILY_PROPS, (decl) => {
+      for (const name of resolveUsedFontNames(usedFamilyList(decl), properties)) {
         if (!GENERIC_FAMILIES.has(name) && !seen.has(name)) {
           seen.add(name);
           used.push(name);
@@ -6618,9 +6694,33 @@ var fontRules = [
       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.`,
-      fixHint: "Add @font-face { font-family: '...'; src: url('capture/assets/fonts/...woff2'); } for each font family, pointing to the captured .woff2 files. For an OS-bundled system font (e.g. Hiragino Sans, Microsoft YaHei) that has no downloadable file, use src: local('Exact Font Name') instead. The declaration alone satisfies this check without needing a font file."
+      fixHint: "Add @font-face { font-family: '...'; src: url('capture/assets/fonts/...woff2'); } for each font family, pointing to the captured .woff2 files, or switch to a Google Fonts family. An OS font such as PingFang SC or Hiragino Sans renders locally from the installed copy, but a cloud render has no copy and refuses it."
     });
     return findings;
+  },
+  ({ styles, rawSource, options, locate }) => {
+    if (isRegistrySourceFile(options.filePath) || isRegistryInstalledFile(rawSource)) return [];
+    const findings = [];
+    for (const style of styles) {
+      parseFontCss(style.content)?.walkAtRules(/^font-face$/i, (rule) => {
+        let family = null;
+        let sources = "";
+        rule.walkDecls((decl) => {
+          const prop = decl.prop.toLowerCase();
+          if (prop === "font-family") family = normalizeUsedFontName(decl.value);
+          else if (prop === "src") sources += ` ${decl.value}`;
+        });
+        if (!family || !/\blocal\s*\(/i.test(sources) || /\burl\s*\(/i.test(sources)) return;
+        findings.push({
+          ...locate(style, rule.source?.start?.offset),
+          code: "font_face_local_only",
+          severity: "warning",
+          message: `@font-face '${family}' only names a font installed on this machine (src: local()). A local render uses the installed copy; a cloud render or another machine has none and falls back to a different font.`,
+          fixHint: "Add a url() source to the font file (.woff2) inside the project, or use a Google Fonts family, so every render draws the same glyphs."
+        });
+      });
+    }
+    return findings;
   }
 ];
 function uniqueFontLocation(styles, families, locate) {
@@ -6628,10 +6728,9 @@ function uniqueFontLocation(styles, families, locate) {
   const properties = collectFontCustomProperties(styles);
   for (const style of styles) {
     try {
-      postcss3.parse(style.content).walkDecls(/^font-family$/i, (decl) => {
-        if (isFontFaceDeclaration(decl)) return;
-        if (!resolveUsedFontNames(decl.value, properties).some((name) => families.includes(name)))
-          return;
+      postcss3.parse(style.content).walkDecls(FONT_FAMILY_PROPS, (decl) => {
+        const named = resolveUsedFontNames(usedFamilyList(decl), properties);
+        if (!named.some((name) => families.includes(name))) return;
         locations.push(locate(style, decl.source?.start?.offset));
       });
     } catch {
@@ -8134,6 +8233,7 @@ function isSnippetFragment(html) {
 export {
   LINT_RULE_COUNT,
   LINT_RULE_GROUP_COUNTS,
+  audioAttributeShapeError,
   collectExternalStyles,
   lintHyperframeHtml,
   lintMediaUrls,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/lint",
-  "version": "0.9.12",
+  "version": "0.9.14",
   "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.9.12"
+    "@hyperframes/parsers": "0.9.14"
   },
   "devDependencies": {
     "@types/node": "^25.0.10",