Merge remote-tracking branch 'origin/main' into fix/audio-volume-automation

# Conflicts: # packages/engine/src/services/audioMixer.test.ts
2026-09-03 23:03:09 +00:00 · 2026-05-24 16:46:52 -04:00
parent 167a222318 720bb9d851
commit 947bf6cc78
7 changed files with 318 additions and 45 deletions
@@ -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", () => {
@@ -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));
      }
    }
  }
@@ -137,6 +137,7 @@ export {
  rewriteAssetPath,
  rewriteCssAssetUrls,
 } from "./compiler/rewriteSubCompPaths";
+export { decodeUrlPathVariants } from "./utils/urlPath";

 // Inline scripts
 export {
@@ -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;
+}
@@ -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";

@@ -107,4 +107,42 @@ describe("processCompositionAudio", () => {
    expect(filter).toContain("lt(t\\,1)");
    expect(filter).toContain("adelay=2000|2000");
  });
+
+  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));
+  });
 });
@@ -137,6 +137,35 @@ describe("resolveProjectRelativeSrc — sub-composition path clamping", () => {
      join(compiledDir, "assets/foo.mp4"),
    );
  });
+
+  it("resolves percent-encoded non-Latin filenames across scripts", () => {
+    const projectDir = join(tmp, "project");
+    const cases = [
+      ["arabic", "%D9%87%D9%86%D8%A7-%D9%85%D8%B1%D9%88%D8%A7.mp4"],
+      ["japanese", "%E6%97%A5%E6%9C%AC%E8%AA%9E.mp4"],
+      ["cyrillic", "%D0%BF%D1%80%D0%B8%D0%B2%D0%B5%D1%82.mp4"],
+      ["korean", "%ED%95%9C%EA%B8%80.mp4"],
+    ] as const;
+
+    for (const [, encodedFilename] of cases) {
+      const filename = decodeURIComponent(encodedFilename);
+      writeFileSync(join(projectDir, "assets", filename), "");
+
+      expect(resolveProjectRelativeSrc(`assets/${encodedFilename}`, projectDir)).toBe(
+        join(projectDir, "assets", filename),
+      );
+    }
+  });
+
+  it("falls back to literal filenames when percent sequences are malformed", () => {
+    const projectDir = join(tmp, "project");
+    const filename = "100%-discount.mp4";
+    writeFileSync(join(projectDir, "assets", filename), "");
+
+    expect(resolveProjectRelativeSrc(`assets/${filename}`, projectDir)).toBe(
+      join(projectDir, "assets", filename),
+    );
+  });
 });

 describe("parseVideoElements", () => {
@@ -9,6 +9,7 @@ import { spawn } from "child_process";
 import { existsSync, mkdirSync, readdirSync, rmSync } from "fs";
 import { isAbsolute, join, posix, resolve, sep } from "path";
 import { parseHTML } from "linkedom";
+import { decodeUrlPathVariants } from "@hyperframes/core";
 import { trackChildProcess } from "../utils/processTracker.js";
 import { extractMediaMetadata, type VideoMetadata } from "../utils/ffprobe.js";
 import {
@@ -516,30 +517,39 @@ export function resolveProjectRelativeSrc(
 ): string {
  const qIdx = src.indexOf("?");
  const cleanSrc = qIdx >= 0 ? src.slice(0, qIdx) : src;
-  const fromCompiled = compiledDir ? join(compiledDir, cleanSrc) : null;
-  const fromBase = join(baseDir, cleanSrc);
  const candidates: string[] = [];
-  if (fromCompiled) candidates.push(fromCompiled);
-  candidates.push(fromBase);
-  // If the joined result escapes the project root (either via leading `..`
-  // or mid-path traversal that path.join collapsed past baseDir), retry
-  // with the basename re-anchored at the project root. This mirrors the
-  // browser URL clamp without relying on a particular `..` shape.
-  const baseAbs = resolve(baseDir);
-  const fromBaseAbs = resolve(fromBase);
-  if (!fromBaseAbs.startsWith(baseAbs + sep) && fromBaseAbs !== baseAbs) {
-    // Normalize first (`assets/../../assets/foo.mp4` → `../assets/foo.mp4`)
-    // then strip any remaining leading `..` segments. Stripping `..` from the
-    // raw input would leave dangling siblings (`assets/../../assets/foo`
-    // would become `assets/assets/foo` instead of `assets/foo`).
-    const normalized = posix.normalize(cleanSrc.replace(/\\/g, "/"));
-    const stripped = normalized.replace(/^(\.\.\/)+/, "");
-    if (stripped && stripped !== src && !stripped.startsWith("..")) {
-      if (compiledDir) candidates.push(join(compiledDir, stripped));
-      candidates.push(join(baseDir, stripped));
+
+  const addCandidate = (candidate: string): void => {
+    if (!candidates.includes(candidate)) candidates.push(candidate);
+  };
+
+  for (const variant of decodeUrlPathVariants(cleanSrc)) {
+    const fromCompiled = compiledDir ? join(compiledDir, variant) : null;
+    const fromBase = join(baseDir, variant);
+
+    // If the joined result escapes the project root (either via leading `..`
+    // or mid-path traversal that path.join collapsed past baseDir), retry
+    // with the basename re-anchored at the project root. This mirrors the
+    // browser URL clamp without relying on a particular `..` shape.
+    const baseAbs = resolve(baseDir);
+    const fromBaseAbs = resolve(fromBase);
+    if (!fromBaseAbs.startsWith(baseAbs + sep) && fromBaseAbs !== baseAbs) {
+      // Normalize first (`assets/../../assets/foo.mp4` → `../assets/foo.mp4`)
+      // then strip any remaining leading `..` segments. Stripping `..` from the
+      // raw input would leave dangling siblings (`assets/../../assets/foo`
+      // would become `assets/assets/foo` instead of `assets/foo`).
+      const normalized = posix.normalize(variant.replace(/\\/g, "/"));
+      const stripped = normalized.replace(/^(\.\.\/)+/, "");
+      if (stripped && stripped !== variant && !stripped.startsWith("..")) {
+        if (compiledDir) addCandidate(join(compiledDir, stripped));
+        addCandidate(join(baseDir, stripped));
+      }
    }
+
+    if (fromCompiled) addCandidate(fromCompiled);
+    addCandidate(fromBase);
  }
-  return candidates.find(existsSync) ?? fromBase;
+  return candidates.find(existsSync) ?? join(baseDir, cleanSrc);
 }

 export async function extractAllVideoFrames(