@hyperframes/lint 0.8.206 → 0.8.208

package/dist/browser.js

@@ -4117,6 +4117,23 @@ ${allInlineStyles}`.replace(/\/\*[\s\S]*?\*\//g, "");
         snippet: truncateSnippet(rootTag.raw)
       }
     ];
+  },
+  // subcomposition_linked_style_names_root_id
+  // The compiler flattens a sub-composition root into its host and rewrites inline <style>
+  // selectors to match; a linked stylesheet is not rewritten, so `#root-id` in it matches nothing.
+  ({ styles, rootTag, options }) => {
+    if (!options.isSubComposition || !rootTag) return [];
+    const rootId = readAttr(rootTag.raw, "id");
+    if (!rootId) return [];
+    const escaped = rootId.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const names = new RegExp(`#${escaped}(?![\\w-])`);
+    return styles.filter((style) => style.index === -1 && names.test(stripCssComments(style.content))).map((style) => ({
+      code: "subcomposition_linked_style_names_root_id",
+      severity: "warning",
+      message: `The linked stylesheet "${style.rootRelativePath ?? style.file}" has a rule on #${rootId}, the id of this sub-composition's root. The root is merged into its host when the composition is compiled, so that selector matches nothing (the same rule in an inline <style> is rewritten and works).`,
+      fixHint: `Move the #${rootId} rules into a <style> inside the <template>, where they are rewritten for the merged root, or select a child element of the root in the linked file instead of the root itself.`,
+      snippet: truncateSnippet(style.content.slice(0, 120))
+    }));
   }
 ];
 var CLIP_MEDIA_TAGS = /* @__PURE__ */ new Set(["img", "video", "audio"]);
@@ -6872,6 +6889,68 @@ var shaderRules = [
   })
 ];
 
+// src/rules/rootPaths.ts
+var URL_ATTRS = ["src", "href", "poster", "xlink:href"];
+var ROOT_PATH = /^\/(?!\/)/;
+var CSS_ROOT_URL = /\burl\(\s*["']?(\/(?!\/)[^"')\s]*)/g;
+var SCRIPT_ROOT_URL = /\b(?:fetch|new\s+URL)\(\s*(["'`])(\/(?!\/)[^"'`$]*)\1/g;
+function relativeForm(path, cssFile) {
+  const depth = (cssFile ?? "").split("/").filter(Boolean).length - 1;
+  return `${"../".repeat(Math.max(depth, 0))}${path.slice(1)}`;
+}
+function rootPathFinding(path, cssFile, snippet) {
+  return {
+    code: "root_path_missing_in_preview",
+    severity: "warning",
+    message: `"${path}" starts at the server's root. Render and snapshot serve the project there, but Studio's preview serves it under the project's own path, so the preview cannot find this file.`,
+    fixHint: `Use "${relativeForm(path, cssFile)}" instead.`,
+    snippet: truncateSnippet(snippet)
+  };
+}
+function cssRootPaths(css, cssFile) {
+  return [...css.matchAll(CSS_ROOT_URL)].map(
+    (match) => rootPathFinding(match[1] ?? "", cssFile, match[0])
+  );
+}
+function tagRootPaths(tag) {
+  if (tag.name === "a" || tag.name === "base") return [];
+  const paths = URL_ATTRS.map((attr) => readAttr(tag.raw, attr)?.trim() ?? "").filter(
+    (value) => ROOT_PATH.test(value)
+  );
+  return [
+    ...paths.map((path) => rootPathFinding(path, void 0, tag.raw)),
+    ...cssRootPaths(readAttr(tag.raw, "style") ?? "")
+  ];
+}
+var scriptRootPaths = (script) => [...script.matchAll(SCRIPT_ROOT_URL)].map(
+  (match) => rootPathFinding(match[2] ?? "", void 0, match[0])
+);
+function invalidImportMap(script) {
+  if (!/\btype\s*=\s*["']?importmap\b/i.test(script.attrs)) return [];
+  try {
+    JSON.parse(script.content);
+    return [];
+  } catch (error) {
+    return [
+      {
+        code: "import_map_invalid",
+        severity: "warning",
+        message: `This import map is not valid JSON (${error instanceof Error ? error.message : String(error)}). The browser ignores it, and preview cannot map root module paths ("/assets/x.js") to the project.`,
+        fixHint: "Make the import map valid JSON: double-quoted keys and values, no trailing commas.",
+        snippet: truncateSnippet(script.content)
+      }
+    ];
+  }
+}
+var rootPathRules = [
+  (ctx) => [
+    ...ctx.tags.flatMap(tagRootPaths),
+    ...ctx.styles.flatMap((style) => cssRootPaths(style.content, style.rootRelativePath)),
+    ...ctx.scripts.flatMap((script) => scriptRootPaths(script.content)),
+    ...ctx.scripts.flatMap(invalidImportMap)
+  ]
+];
+
 // src/hyperframeLinter.ts
 var RULE_GROUPS = [
   { group: "core", rules: coreRules },
@@ -6884,7 +6963,8 @@ var RULE_GROUPS = [
   { group: "fonts", rules: fontRules },
   { group: "slideshow", rules: slideshowRules },
   { group: "structure", rules: structureRules },
-  { group: "shaders", rules: shaderRules }
+  { group: "shaders", rules: shaderRules },
+  { group: "rootPaths", rules: rootPathRules }
 ];
 var LINT_RULE_COUNT = RULE_GROUPS.reduce((n, g) => n + g.rules.length, 0);
 var LINT_RULE_GROUP_COUNTS = Object.fromEntries(

package/dist/index.js

@@ -4123,6 +4123,23 @@ ${allInlineStyles}`.replace(/\/\*[\s\S]*?\*\//g, "");
         snippet: truncateSnippet(rootTag.raw)
       }
     ];
+  },
+  // subcomposition_linked_style_names_root_id
+  // The compiler flattens a sub-composition root into its host and rewrites inline <style>
+  // selectors to match; a linked stylesheet is not rewritten, so `#root-id` in it matches nothing.
+  ({ styles, rootTag, options }) => {
+    if (!options.isSubComposition || !rootTag) return [];
+    const rootId = readAttr(rootTag.raw, "id");
+    if (!rootId) return [];
+    const escaped = rootId.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const names = new RegExp(`#${escaped}(?![\\w-])`);
+    return styles.filter((style) => style.index === -1 && names.test(stripCssComments(style.content))).map((style) => ({
+      code: "subcomposition_linked_style_names_root_id",
+      severity: "warning",
+      message: `The linked stylesheet "${style.rootRelativePath ?? style.file}" has a rule on #${rootId}, the id of this sub-composition's root. The root is merged into its host when the composition is compiled, so that selector matches nothing (the same rule in an inline <style> is rewritten and works).`,
+      fixHint: `Move the #${rootId} rules into a <style> inside the <template>, where they are rewritten for the merged root, or select a child element of the root in the linked file instead of the root itself.`,
+      snippet: truncateSnippet(style.content.slice(0, 120))
+    }));
   }
 ];
 var CLIP_MEDIA_TAGS = /* @__PURE__ */ new Set(["img", "video", "audio"]);
@@ -6878,6 +6895,68 @@ var shaderRules = [
   })
 ];
 
+// src/rules/rootPaths.ts
+var URL_ATTRS = ["src", "href", "poster", "xlink:href"];
+var ROOT_PATH = /^\/(?!\/)/;
+var CSS_ROOT_URL = /\burl\(\s*["']?(\/(?!\/)[^"')\s]*)/g;
+var SCRIPT_ROOT_URL = /\b(?:fetch|new\s+URL)\(\s*(["'`])(\/(?!\/)[^"'`$]*)\1/g;
+function relativeForm(path, cssFile) {
+  const depth = (cssFile ?? "").split("/").filter(Boolean).length - 1;
+  return `${"../".repeat(Math.max(depth, 0))}${path.slice(1)}`;
+}
+function rootPathFinding(path, cssFile, snippet) {
+  return {
+    code: "root_path_missing_in_preview",
+    severity: "warning",
+    message: `"${path}" starts at the server's root. Render and snapshot serve the project there, but Studio's preview serves it under the project's own path, so the preview cannot find this file.`,
+    fixHint: `Use "${relativeForm(path, cssFile)}" instead.`,
+    snippet: truncateSnippet(snippet)
+  };
+}
+function cssRootPaths(css, cssFile) {
+  return [...css.matchAll(CSS_ROOT_URL)].map(
+    (match) => rootPathFinding(match[1] ?? "", cssFile, match[0])
+  );
+}
+function tagRootPaths(tag) {
+  if (tag.name === "a" || tag.name === "base") return [];
+  const paths = URL_ATTRS.map((attr) => readAttr(tag.raw, attr)?.trim() ?? "").filter(
+    (value) => ROOT_PATH.test(value)
+  );
+  return [
+    ...paths.map((path) => rootPathFinding(path, void 0, tag.raw)),
+    ...cssRootPaths(readAttr(tag.raw, "style") ?? "")
+  ];
+}
+var scriptRootPaths = (script) => [...script.matchAll(SCRIPT_ROOT_URL)].map(
+  (match) => rootPathFinding(match[2] ?? "", void 0, match[0])
+);
+function invalidImportMap(script) {
+  if (!/\btype\s*=\s*["']?importmap\b/i.test(script.attrs)) return [];
+  try {
+    JSON.parse(script.content);
+    return [];
+  } catch (error) {
+    return [
+      {
+        code: "import_map_invalid",
+        severity: "warning",
+        message: `This import map is not valid JSON (${error instanceof Error ? error.message : String(error)}). The browser ignores it, and preview cannot map root module paths ("/assets/x.js") to the project.`,
+        fixHint: "Make the import map valid JSON: double-quoted keys and values, no trailing commas.",
+        snippet: truncateSnippet(script.content)
+      }
+    ];
+  }
+}
+var rootPathRules = [
+  (ctx) => [
+    ...ctx.tags.flatMap(tagRootPaths),
+    ...ctx.styles.flatMap((style) => cssRootPaths(style.content, style.rootRelativePath)),
+    ...ctx.scripts.flatMap((script) => scriptRootPaths(script.content)),
+    ...ctx.scripts.flatMap(invalidImportMap)
+  ]
+];
+
 // src/hyperframeLinter.ts
 var RULE_GROUPS = [
   { group: "core", rules: coreRules },
@@ -6890,7 +6969,8 @@ var RULE_GROUPS = [
   { group: "fonts", rules: fontRules },
   { group: "slideshow", rules: slideshowRules },
   { group: "structure", rules: structureRules },
-  { group: "shaders", rules: shaderRules }
+  { group: "shaders", rules: shaderRules },
+  { group: "rootPaths", rules: rootPathRules }
 ];
 var LINT_RULE_COUNT = RULE_GROUPS.reduce((n, g) => n + g.rules.length, 0);
 var LINT_RULE_GROUP_COUNTS = Object.fromEntries(
@@ -7066,6 +7146,7 @@ import {
   resolveLocalAssetCandidates,
   resolveProjectRelativeSrc
 } from "@hyperframes/parsers/asset-resolution";
+import { encodeUrlPath } from "@hyperframes/parsers";
 
 // src/hevcPreviewLint.ts
 import { execFile } from "child_process";
@@ -7591,10 +7672,18 @@ function lintProjectAudioFiles(projectDir, htmlSources) {
   }
   return findings;
 }
+function urlSafeSrcOf(projectDir, rootRelative) {
+  if (!/[?#]/.test(rootRelative)) return null;
+  const literal = resolve(projectDir, rootRelative.replace(/^\//, ""));
+  if (!existsSync2(literal)) return null;
+  return encodeUrlPath(rootRelative);
+}
+var urlSafeHint = (safe) => `The file exists, but a "#" or "?" in a src ends the file name there. Write the src as "${safe}".`;
 function lintAudioSrcNotFound(projectDir, htmlSources) {
   const findings = [];
   const audioSrcRe = mediaSrcTagRe("audio");
   const missingByFile = /* @__PURE__ */ new Map();
+  const urlSafe = /* @__PURE__ */ new Map();
   for (const { html, compSrcPath } of htmlSources) {
     const scannable = maskNonScannableRanges2(html);
     let match;
@@ -7604,6 +7693,8 @@ function lintAudioSrcNotFound(projectDir, htmlSources) {
       if (isUnresolvedAssetPlaceholder2(src)) continue;
       const rootRelative = compSrcPath ? rewriteAssetPath2(compSrcPath, src, (path) => existsSync2(join3(projectDir, path))) : src;
       if (!existsSync2(resolveProjectRelativeSrc(rootRelative, projectDir))) {
+        const safe = urlSafeSrcOf(projectDir, rootRelative);
+        if (safe) urlSafe.set(src, safe);
         const file = sourceFile(projectDir, compSrcPath);
         missingByFile.set(file, (missingByFile.get(file) ?? /* @__PURE__ */ new Set()).add(src));
       }
@@ -7616,7 +7707,7 @@ function lintAudioSrcNotFound(projectDir, htmlSources) {
       severity: "error",
       file,
       message: `<audio> element references file(s) not found in the project: ${unique.join(", ")}. The rendered video will be silent.`,
-      fixHint: unique.length === 1 ? `Add the file "${unique[0]}" to the project directory, or update the src attribute to point to an existing file.` : `Add the missing files to the project directory, or update the src attributes to point to existing files.`
+      fixHint: unique.length === 1 && urlSafe.has(unique[0]) ? urlSafeHint(urlSafe.get(unique[0])) : unique.length === 1 ? `Add the file "${unique[0]}" to the project directory, or update the src attribute to point to an existing file.` : `Add the missing files to the project directory, or update the src attributes to point to existing files.`
     });
   }
   return findings;
@@ -7625,6 +7716,7 @@ function lintMissingLocalAsset(projectDir, htmlSources) {
   const findings = [];
   const localAssetSrcRe = mediaSrcTagRe("video|img|source");
   const missingByTag = /* @__PURE__ */ new Map();
+  const urlSafe = /* @__PURE__ */ new Map();
   for (const { html, compSrcPath } of htmlSources) {
     const scannable = maskNonScannableRanges2(html);
     const re = new RegExp(localAssetSrcRe.source, localAssetSrcRe.flags);
@@ -7639,6 +7731,12 @@ function lintMissingLocalAsset(projectDir, htmlSources) {
       const rootRelative = compSrcPath ? rewriteAssetPath2(compSrcPath, src, (path) => existsSync2(join3(projectDir, path))) : src;
       const resolvedAsset = resolveExistingLocalAsset3(projectDir, rootRelative);
       if (resolvedAsset) continue;
+      const rawRoot = rawSrc.trim();
+      const safe = urlSafeSrcOf(
+        projectDir,
+        compSrcPath ? rewriteAssetPath2(compSrcPath, rawRoot, (path) => existsSync2(join3(projectDir, path))) : rawRoot
+      );
+      if (safe) urlSafe.set(src, safe);
       const resolvedKey = resolve(projectDir, rootRelative);
       const file = sourceFile(projectDir, compSrcPath);
       const bucketKey = `${file}\0${tagName}`;
@@ -7657,7 +7755,7 @@ function lintMissingLocalAsset(projectDir, htmlSources) {
       severity: "error",
       file,
       message: `<${tagName}> element references local file(s) not found in the project: ${unique.join(", ")}. The renderer will silently skip these and produce a video with missing visuals.`,
-      fixHint: unique.length === 1 ? `Add "${unique[0]}" to the project directory, or update the src attribute to point to an existing file. Common cause: captured asset filenames are unreliable (heygen-logo.svg often contains Google, nvidia-logo.svg may contain Autodesk, etc.). Open the contact sheets and verify the file actually exists at this path before referencing it.` : "Add the missing files to the project directory, or update the src attributes to point to existing files. Captured asset filenames are unreliable. Verify against capture/contact-sheets/ and capture/extracted/asset-descriptions.md."
+      fixHint: unique.length === 1 && urlSafe.has(unique[0]) ? urlSafeHint(urlSafe.get(unique[0])) : unique.length === 1 ? `Add "${unique[0]}" to the project directory, or update the src attribute to point to an existing file. Common cause: captured asset filenames are unreliable (heygen-logo.svg often contains Google, nvidia-logo.svg may contain Autodesk, etc.). Open the contact sheets and verify the file actually exists at this path before referencing it.` : "Add the missing files to the project directory, or update the src attributes to point to existing files. Captured asset filenames are unreliable. Verify against capture/contact-sheets/ and capture/extracted/asset-descriptions.md."
     });
   }
   return findings;

package/package.json

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