Merge pull request #1065 from heygen-com/fix/nonlatin-media-src-resolution

miguel-heygen · web-flow · commit 720bb9d8514a · 2026-05-24T16:41:16.000-04:00
fix(engine): resolve encoded non-Latin media paths
diff --git a/packages/cli/src/utils/lintProject.test.ts b/packages/cli/src/utils/lintProject.test.ts
@@ -1,14 +1,12 @@
 import { describe, it, expect, afterEach } from "vitest";
-import { mkdirSync, writeFileSync, rmSync } from "node:fs";
+import { mkdirSync, mkdtempSync, writeFileSync, rmSync } from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 import { lintProject, shouldBlockRender } from "./lintProject.js";
 import type { ProjectDir } from "./project.js";
 
 function tmpProject(name: string): string {
-  const dir = join(tmpdir(), `hf-test-${name}-${Date.now()}`);
-  mkdirSync(dir, { recursive: true });
-  return dir;
+  return mkdtempSync(join(tmpdir(), `hf-test-${name}-`));
 }
 
 function validHtml(compId = "main"): string {
@@ -121,6 +119,29 @@ describe("lintProject", () => {
     expect(finding?.selector).toBe('[data-composition-id="scene"] .title');
   });
 
+  it("lints percent-encoded linked CSS filenames that exist decoded on disk", () => {
+    const encodedFilename = "%E6%97%A5%E6%9C%AC%E8%AA%9E.css";
+    const project = makeProject(validHtml(), {
+      "scene.html": `<html><head><link rel="stylesheet" href="${encodedFilename}"></head><body>
+  <div id="scene" data-composition-id="scene" data-width="1920" data-height="1080" data-start="0" data-duration="2"></div>
+  <script>window.__timelines = window.__timelines || {}; window.__timelines["scene"] = gsap.timeline({ paused: true });</script>
+</body></html>`,
+    });
+    writeFileSync(
+      join(project.dir, "compositions", decodeURIComponent(encodedFilename)),
+      '[data-composition-id="scene"] .title { opacity: 0; }',
+    );
+
+    const { results } = lintProject(project);
+    const subResult = results.find((result) => result.file === "compositions/scene.html");
+    const finding = subResult?.result.findings.find(
+      (item) => item.code === "composition_self_attribute_selector",
+    );
+
+    expect(finding).toBeDefined();
+    expect(finding?.selector).toBe('[data-composition-id="scene"] .title');
+  });
+
   it("aggregates errors across index.html and sub-compositions", () => {
     const project = makeProject(htmlWithMissingMediaId(), {
       "overlay.html": htmlWithMissingMediaId(),
@@ -182,6 +203,29 @@ function validHtmlWithAudio(compId = "main"): string {
 </body></html>`;
 }
 
+function validHtmlWithAudioSrc(src: string): string {
+  return `<html><body>
+  <div data-composition-id="main" data-width="1920" data-height="1080">
+    <audio id="music" src="${src}" data-start="0" data-track-index="0" data-volume="1"></audio>
+  </div>
+  <script>window.__timelines = window.__timelines || {}; window.__timelines["main"] = gsap.timeline({ paused: true });</script>
+</body></html>`;
+}
+
+function validHtmlWithMaskImageUrl(url: string): string {
+  return `<html><body>
+  <div data-composition-id="main" data-width="1920" data-height="1080">
+    <div class="hf-texture-text hf-texture-lava">TEXT</div>
+  </div>
+  <style>
+    .hf-texture-lava {
+      mask-image: url("${url}");
+    }
+  </style>
+  <script>window.__timelines = window.__timelines || {}; window.__timelines["main"] = gsap.timeline({ paused: true });</script>
+</body></html>`;
+}
+
 describe("audio_file_without_element", () => {
   it("warns when audio file exists but no <audio> element", () => {
     const project = makeProject(validHtml());
@@ -330,6 +374,46 @@ describe("audio_src_not_found", () => {
     expect(finding).toBeUndefined();
   });
 
+  it("does not error for percent-encoded non-Latin filenames that exist on disk", () => {
+    const encodedFilename =
+      "%D9%87%D9%86%D8%A7%20%D9%85%D8%B1%D9%88%D8%A7%20-%20%D9%85%D8%A8%D8%A7%D8%B1%D9%83.mp4";
+    const project = makeProject(validHtmlWithAudioSrc(`assets/${encodedFilename}`));
+    mkdirSync(join(project.dir, "assets"), { recursive: true });
+    writeFileSync(join(project.dir, "assets", decodeURIComponent(encodedFilename)), "fake");
+
+    const { results } = lintProject(project);
+
+    const first = results[0];
+    expect(first).toBeDefined();
+    const finding = first?.result.findings.find((f) => f.code === "audio_src_not_found");
+    expect(finding).toBeUndefined();
+  });
+
+  it("does not error for malformed percent sequences that are literal filenames", () => {
+    const filename = "100%-discount.mp4";
+    const project = makeProject(validHtmlWithAudioSrc(`assets/${filename}`));
+    mkdirSync(join(project.dir, "assets"), { recursive: true });
+    writeFileSync(join(project.dir, "assets", filename), "fake");
+
+    const { results } = lintProject(project);
+
+    const first = results[0];
+    expect(first).toBeDefined();
+    const finding = first?.result.findings.find((f) => f.code === "audio_src_not_found");
+    expect(finding).toBeUndefined();
+  });
+
+  it("does not treat decoded traversal as an existing file outside the project", () => {
+    const project = makeProject(
+      validHtmlWithAudioSrc("assets/foo/%2E%2E/%2E%2E/%2E%2E/etc/passwd"),
+    );
+
+    const { results } = lintProject(project);
+
+    const finding = results[0]?.result.findings.find((f) => f.code === "audio_src_not_found");
+    expect(finding).toBeDefined();
+  });
+
   it("deduplicates missing files across compositions", () => {
     const project = makeProject(validHtmlWithAudio(), {
       "captions.html": validHtmlWithAudio("captions"),
@@ -467,6 +551,30 @@ describe("texture_mask_asset_not_found", () => {
     expect(finding).toBeUndefined();
   });
 
+  it("checks mask-image URLs inside percent-encoded linked CSS filenames", () => {
+    const encodedFilename = "%E6%97%A5%E6%9C%AC%E8%AA%9E.css";
+    const project = makeProject(validHtml(), {
+      "scene.html": `<html><head><link rel="stylesheet" href="${encodedFilename}"></head><body>
+  <div data-composition-id="scene" data-width="1920" data-height="1080">
+    <div class="hf-texture-text hf-texture-lava">TEXT</div>
+  </div>
+  <script>window.__timelines = window.__timelines || {}; window.__timelines["scene"] = gsap.timeline({ paused: true });</script>
+</body></html>`,
+    });
+    writeFileSync(
+      join(project.dir, "compositions", decodeURIComponent(encodedFilename)),
+      '.hf-texture-lava { mask-image: url("masks/missing.png"); }',
+    );
+
+    const { results } = lintProject(project);
+    const finding = results[0]?.result.findings.find(
+      (item) => item.code === "texture_mask_asset_not_found",
+    );
+
+    expect(finding).toBeDefined();
+    expect(finding?.message).toContain("masks/missing.png");
+  });
+
   it("resolves root-absolute mask-image URLs from the project root", () => {
     const html = `<html><body>
   <div data-composition-id="main" data-width="1920" data-height="1080">
@@ -493,6 +601,33 @@ describe("texture_mask_asset_not_found", () => {
 
     expect(finding).toBeUndefined();
   });
+
+  it("does not error for percent-encoded non-Latin mask filenames that exist on disk", () => {
+    const encodedFilename = "%E6%97%A5%E6%9C%AC%E8%AA%9E.png";
+    const project = makeProject(validHtmlWithMaskImageUrl(`assets/${encodedFilename}`));
+    mkdirSync(join(project.dir, "assets"), { recursive: true });
+    writeFileSync(join(project.dir, "assets", decodeURIComponent(encodedFilename)), "fake");
+
+    const { results } = lintProject(project);
+    const finding = results[0]?.result.findings.find(
+      (item) => item.code === "texture_mask_asset_not_found",
+    );
+
+    expect(finding).toBeUndefined();
+  });
+
+  it("does not treat decoded mask traversal as an existing file outside the project", () => {
+    const project = makeProject(
+      validHtmlWithMaskImageUrl("assets/foo/%2E%2E/%2E%2E/%2E%2E/etc/passwd"),
+    );
+
+    const { results } = lintProject(project);
+    const finding = results[0]?.result.findings.find(
+      (item) => item.code === "texture_mask_asset_not_found",
+    );
+
+    expect(finding).toBeDefined();
+  });
 });
 
 describe("multiple_root_compositions", () => {
diff --git a/packages/cli/src/utils/lintProject.ts b/packages/cli/src/utils/lintProject.ts
@@ -1,8 +1,8 @@
 import { existsSync, readFileSync, readdirSync } from "node:fs";
-import { dirname, join, resolve, extname } from "node:path";
+import { dirname, extname, isAbsolute, join, posix, relative, resolve } from "node:path";
 import { lintHyperframeHtml, type HyperframeLintResult } from "@hyperframes/core/lint";
 import type { HyperframeLintFinding } from "@hyperframes/core/lint";
-import { rewriteAssetPath } from "@hyperframes/core";
+import { decodeUrlPathVariants, rewriteAssetPath } from "@hyperframes/core";
 import type { ProjectDir } from "./project.js";
 
 /**
@@ -62,9 +62,9 @@ function collectExternalStyles(
     const href = tag.match(/\bhref\s*=\s*["']([^"']+)["']/i)?.[1] ?? "";
     if (!isLocalStylesheetHref(href)) continue;
     const rootRelative = compSrcPath ? join(dirname(compSrcPath), href) : href;
-    const resolved = resolve(projectDir, rootRelative);
-    if (!existsSync(resolved)) continue;
-    styles.push({ href, content: readFileSync(resolved, "utf-8") });
+    const stylesheet = resolveExistingLocalAsset(projectDir, rootRelative);
+    if (!stylesheet) continue;
+    styles.push({ href, content: readFileSync(stylesheet.resolved, "utf-8") });
   }
   return styles;
 }
@@ -88,9 +88,12 @@ function collectCssSources(projectDir: string, html: string, compSrcPath?: strin
     if (!isLocalStylesheetHref(href)) continue;
 
     const rootRelativePath = compSrcPath ? join(dirname(compSrcPath), href) : href;
-    const resolved = resolve(projectDir, rootRelativePath);
-    if (!existsSync(resolved)) continue;
-    sources.push({ content: readFileSync(resolved, "utf-8"), rootRelativePath });
+    const stylesheet = resolveExistingLocalAsset(projectDir, rootRelativePath);
+    if (!stylesheet) continue;
+    sources.push({
+      content: readFileSync(stylesheet.resolved, "utf-8"),
+      rootRelativePath: stylesheet.rootRelativePath,
+    });
   }
 
   let tagMatch: RegExpExecArray | null;
@@ -113,16 +116,63 @@ function cleanAssetUrl(url: string): string {
   return url.trim().split(/[?#]/, 1)[0] ?? "";
 }
 
-function resolveCssAssetPath(
+function isWithinProjectRoot(projectDir: string, candidate: string): boolean {
+  const projectRoot = resolve(projectDir);
+  const relativePath = relative(projectRoot, candidate);
+  return relativePath === "" || (!relativePath.startsWith("..") && !isAbsolute(relativePath));
+}
+
+function addCandidate(candidates: string[], candidate: string): void {
+  if (!candidates.includes(candidate)) candidates.push(candidate);
+}
+
+function resolveLocalAssetCandidates(projectDir: string, url: string): string[] {
+  const cleanUrl = cleanAssetUrl(url);
+  const projectRoot = resolve(projectDir);
+  const candidates: string[] = [];
+
+  for (const variant of decodeUrlPathVariants(cleanUrl)) {
+    const projectRelative = variant.startsWith("/") ? variant.slice(1) : variant;
+    const resolved = resolve(projectRoot, projectRelative);
+    if (isWithinProjectRoot(projectRoot, resolved)) {
+      addCandidate(candidates, resolved);
+      continue;
+    }
+
+    const normalized = posix.normalize(projectRelative.replace(/\\/g, "/"));
+    const clamped = normalized.replace(/^(\.\.\/)+/, "");
+    if (clamped && !clamped.startsWith("..")) {
+      addCandidate(candidates, resolve(projectRoot, clamped));
+    }
+  }
+
+  return candidates;
+}
+
+function resolveExistingLocalAsset(
+  projectDir: string,
+  url: string,
+): { resolved: string; rootRelativePath: string } | null {
+  const projectRoot = resolve(projectDir);
+  const resolved = resolveLocalAssetCandidates(projectRoot, url).find(existsSync);
+  if (!resolved) return null;
+  return { resolved, rootRelativePath: relative(projectRoot, resolved) };
+}
+
+function resolveCssAssetCandidates(
   projectDir: string,
   url: string,
   htmlCompSrcPath?: string,
   cssRootRelativePath?: string,
-): string {
-  if (url.startsWith("/")) return resolve(projectDir, url.slice(1));
-  if (cssRootRelativePath) return resolve(projectDir, join(dirname(cssRootRelativePath), url));
-  if (htmlCompSrcPath) return resolve(projectDir, rewriteAssetPath(htmlCompSrcPath, url));
-  return resolve(projectDir, url);
+): string[] {
+  if (url.startsWith("/")) return resolveLocalAssetCandidates(projectDir, url);
+  if (cssRootRelativePath) {
+    return resolveLocalAssetCandidates(projectDir, join(dirname(cssRootRelativePath), url));
+  }
+  if (htmlCompSrcPath) {
+    return resolveLocalAssetCandidates(projectDir, rewriteAssetPath(htmlCompSrcPath, url));
+  }
+  return resolveLocalAssetCandidates(projectDir, url);
 }
 
 /**
@@ -265,8 +315,7 @@ function lintAudioSrcNotFound(
       // before serving. Mirror that rewrite here so the existence check sees
       // the same path the renderer will. Root-html srcs pass through unchanged.
       const rootRelative = compSrcPath ? rewriteAssetPath(compSrcPath, src) : src;
-      const resolved = resolve(projectDir, rootRelative);
-      if (!existsSync(resolved)) {
+      if (!resolveLocalAssetCandidates(projectDir, rootRelative).some(existsSync)) {
         missingSrcs.push(src);
       }
     }
@@ -304,14 +353,14 @@ function lintTextureMaskAssetNotFound(
         if (!url || isRemoteOrInlineUrl(url)) continue;
         if (/^__[A-Z_]+__$/.test(url)) continue;
 
-        const resolved = resolveCssAssetPath(
+        const candidates = resolveCssAssetCandidates(
           projectDir,
           url,
           compSrcPath,
           cssSource.rootRelativePath,
         );
-        if (existsSync(resolved)) continue;
-        missing.set(url, resolved);
+        if (candidates.some(existsSync)) continue;
+        missing.set(url, candidates[0] ?? resolve(projectDir, url));
       }
     }
   }
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
@@ -137,6 +137,7 @@ export {
   rewriteAssetPath,
   rewriteCssAssetUrls,
 } from "./compiler/rewriteSubCompPaths";
+export { decodeUrlPathVariants } from "./utils/urlPath";
 
 // Inline scripts
 export {
diff --git a/packages/core/src/utils/urlPath.ts b/packages/core/src/utils/urlPath.ts
@@ -0,0 +1,11 @@
+export function decodeUrlPathVariants(path: string): string[] {
+  const variants = [path];
+  try {
+    const decoded = decodeURIComponent(path);
+    if (decoded !== path) variants.unshift(decoded);
+  } catch {
+    // Malformed percent sequences may be literal filesystem names.
+  }
+
+  return variants;
+}
diff --git a/packages/engine/src/services/audioMixer.test.ts b/packages/engine/src/services/audioMixer.test.ts
@@ -1,5 +1,5 @@
 import { afterEach, describe, expect, it, vi } from "vitest";
-import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 
@@ -64,4 +64,42 @@ describe("processCompositionAudio", () => {
     expect(filter).toContain("volume=0");
     expect(filter).toContain("[mixed]volume=1[out]");
   });
+
+  it("prepares percent-encoded non-Latin audio srcs from decoded filesystem paths", async () => {
+    const baseDir = mkdtempSync(join(tmpdir(), "hf-audio-base-"));
+    const workDir = mkdtempSync(join(tmpdir(), "hf-audio-work-"));
+    tempDirs.push(baseDir, workDir);
+
+    const encodedFilename =
+      "%D9%87%D9%86%D8%A7%20%D9%85%D8%B1%D9%88%D8%A7%20-%20%D9%85%D8%A8%D8%A7%D8%B1%D9%83.mp4";
+    const filename = decodeURIComponent(encodedFilename);
+    mkdirSync(join(baseDir, "assets"), { recursive: true });
+    writeFileSync(join(baseDir, "assets", filename), "stub");
+
+    const result = await processCompositionAudio(
+      [
+        {
+          id: "voice",
+          src: `assets/${encodedFilename}`,
+          start: 0,
+          end: 2,
+          mediaStart: 0,
+          layer: 0,
+          volume: 1,
+          type: "audio",
+        },
+      ],
+      baseDir,
+      workDir,
+      join(baseDir, "out.m4a"),
+      2,
+    );
+
+    expect(result.success).toBe(true);
+    expect(result.error).toBeUndefined();
+    expect(runFfmpegMock).toHaveBeenCalledTimes(2);
+
+    const prepareArgs = runFfmpegMock.mock.calls[0]?.[0];
+    expect(prepareArgs).toContain(join(baseDir, "assets", filename));
+  });
 });
diff --git a/packages/engine/src/services/videoFrameExtractor.test.ts b/packages/engine/src/services/videoFrameExtractor.test.ts
diff --git a/packages/engine/src/services/videoFrameExtractor.ts b/packages/engine/src/services/videoFrameExtractor.ts
