From 1770de7c8713016b07fa101042de0696122e558e Mon Sep 17 00:00:00 2001
From: Miguel Angel Simon Sierra <miguel.sierra@heygen.com>
Date: Tue, 14 Jul 2026 19:19:51 -0400
Subject: [PATCH 1/4] docs: document HEVC input support and the preview-only
 codec caveat

---
 docs/guides/rendering.mdx                           | 13 +++++++++++++
 docs/guides/troubleshooting.mdx                     | 12 ++++++++++++
 skills-manifest.json                                |  4 ++--
 .../references/variables-and-media.md               |  2 ++
 skills/media-use/SKILL.md                           |  6 ++++++
 5 files changed, 35 insertions(+), 2 deletions(-)

diff --git a/docs/guides/rendering.mdx b/docs/guides/rendering.mdx
index db82fce4e5..7427b0e18d 100644
--- a/docs/guides/rendering.mdx
+++ b/docs/guides/rendering.mdx
@@ -157,6 +157,19 @@ npx hyperframes render --video-bitrate 10M --output controlled.mp4
 
 **Tip**: The default `standard` preset (CRF 18) is visually lossless at 1080p — most people cannot distinguish it from the source. Use `--quality draft` for faster iteration, or `--quality high` / `--crf 10` when file size is no concern.
 
+## Input Video Codecs
+
+Video assets referenced by a composition (a `<video src="...">` clip) are decoded by FFmpeg, not by the browser: the pipeline pre-extracts every input video into frame images and injects them during capture, so the render never depends on what the capture browser can play. Any codec your FFmpeg build decodes works as an input, including:
+
+- H.264 / AVC
+- **HEVC / H.265, 8-bit and 10-bit** (`hvc1` and `hev1`): common for storage-optimized asset libraries; renders identically on macOS and Linux, no hardware decoder required
+- VP8 / VP9 and ProRes 4444 (with alpha; see [Transparent Video](#transparent-video))
+- HDR sources (HLG / PQ) are tone-mapped for SDR renders; see the [HDR guide](/guides/hdr)
+
+The one caveat is **live preview**: `preview`, `play`, Studio, and published player pages play the file in a real browser, so playback there depends on that browser's codec support. Chrome (107+), Edge, and Safari hardware-decode HEVC on most modern machines; Firefox does not. If an HEVC asset shows a black frame in preview while rendering fine, generate an H.264 proxy for authoring (for example with `ffmpeg -i asset.mp4 -c:v libx264 -crf 18 proxy.mp4`, or via the media-use skill) and swap the original back in for the final render, or just keep the HEVC source, since the rendered output is unaffected.
+
+`hyperframes lint` emits an info-level `hevc_preview_codec` note when a composition references an HEVC video, as a reminder of this preview-only limitation.
+
 ## Animated GIF
 
 Use GIF when the output needs to autoplay inline in GitHub PRs, READMEs, issue reports, and docs pages:
diff --git a/docs/guides/troubleshooting.mdx b/docs/guides/troubleshooting.mdx
index 94f143f6c8..cdb4e459b6 100644
--- a/docs/guides/troubleshooting.mdx
+++ b/docs/guides/troubleshooting.mdx
@@ -135,6 +135,18 @@ If your issue is about a specific coding mistake (animations not working, video
 
     See [Rendering: Options](/guides/rendering#options) for all available flags.
   </Accordion>
+
+  <Accordion title="Video asset plays black in preview but renders fine (HEVC/H.265)">
+    Rendering decodes video assets with FFmpeg, so HEVC (H.265) inputs render correctly on every platform. Live preview is different: `preview`, `play`, Studio, and published player pages play the file in your browser, and not every browser decodes HEVC (Chrome 107+, Edge, and Safari do on most modern hardware; Firefox does not).
+
+    If an HEVC asset shows a black or frozen frame in preview:
+
+    1. Confirm the render itself is fine: `npx hyperframes render` output will contain the video.
+    2. For authoring, generate an H.264 proxy (`ffmpeg -i asset.mp4 -c:v libx264 -crf 18 proxy.mp4`) and point the composition at it while you iterate.
+    3. Swap the HEVC original back before the final render, or keep the proxy; both render correctly.
+
+    `npx hyperframes lint` flags HEVC assets with an info-level `hevc_preview_codec` note. See [Rendering: Input Video Codecs](/guides/rendering#input-video-codecs).
+  </Accordion>
 </AccordionGroup>
 
 ## System Diagnostics
diff --git a/skills-manifest.json b/skills-manifest.json
index a0feea2cf0..64fe6eed6c 100644
--- a/skills-manifest.json
+++ b/skills-manifest.json
@@ -30,7 +30,7 @@
       "files": 8
     },
     "hyperframes-core": {
-      "hash": "690ebb3ba5420b90",
+      "hash": "51ff05e641f546d0",
       "files": 14
     },
     "hyperframes-creative": {
@@ -46,7 +46,7 @@
       "files": 10
     },
     "media-use": {
-      "hash": "7a51f53cf615fe97",
+      "hash": "373c5ff1308597ae",
       "files": 124
     },
     "motion-graphics": {
diff --git a/skills/hyperframes-core/references/variables-and-media.md b/skills/hyperframes-core/references/variables-and-media.md
index e4f00b2148..71c217207a 100644
--- a/skills/hyperframes-core/references/variables-and-media.md
+++ b/skills/hyperframes-core/references/variables-and-media.md
@@ -105,3 +105,5 @@ Video elements must be muted and inline. Audio must be a separate `<audio>` elem
 - For volume fades/ducking, animate `volume` on the timeline (`tl.to("#bgm", { volume: 0, duration: 1 }, "outro")`) rather than swapping `data-volume`. The runtime probes the timeline's volume keyframes and applies them identically in preview and render; `data-volume` is the static baseline for elements no tween touches.
 
 For media duration: `<video>` and `<audio>` can omit `data-duration` if the media's intrinsic length is known and you want the full clip. Otherwise provide `data-duration` explicitly.
+
+Input codecs: render decodes video via FFmpeg (frames are pre-extracted and injected), so HEVC/H.265 assets (8/10-bit) render correctly everywhere; only live preview depends on the browser's codec support (`lint` emits an info-level `hevc_preview_codec` note; use an H.264 proxy for authoring if preview shows black).
diff --git a/skills/media-use/SKILL.md b/skills/media-use/SKILL.md
index 07d6e5669c..66443b98de 100644
--- a/skills/media-use/SKILL.md
+++ b/skills/media-use/SKILL.md
@@ -364,6 +364,12 @@ removal, upscale, lipsync, translate). Run the tool, then register the output
 with `resolve --from <output> --type <type>` so it joins the ledger + global
 cache.
 
+HEVC/H.265 sources need no conversion for **render** (FFmpeg pre-decodes all
+input video); only live preview depends on the browser's codec support. If an
+HEVC asset previews black, make an H.264 authoring proxy (`ffmpeg -i in.mp4
+-c:v libx264 -crf 18 proxy.mp4`), register it with `resolve --from`, and keep
+either file for the final render.
+
 ## CLI tools used (what to run, and how to enable each)
 
 `resolve` auto-cascades; each provider shells one CLI. HeyGen is the

From ca117d835f74f19516ff0b843202b8a585614959 Mon Sep 17 00:00:00 2001
From: Miguel Angel Simon Sierra <miguel.sierra@heygen.com>
Date: Tue, 14 Jul 2026 19:26:50 -0400
Subject: [PATCH 2/4] feat(lint): flag HEVC video assets with info-level
 preview note

---
 packages/lint/src/assetResolution.ts |  75 ++++++++++
 packages/lint/src/hevcPreviewLint.ts | 202 +++++++++++++++++++++++++++
 packages/lint/src/project.test.ts    | 169 +++++++++++++++++++++-
 packages/lint/src/project.ts         |  75 ++--------
 4 files changed, 456 insertions(+), 65 deletions(-)
 create mode 100644 packages/lint/src/assetResolution.ts
 create mode 100644 packages/lint/src/hevcPreviewLint.ts

diff --git a/packages/lint/src/assetResolution.ts b/packages/lint/src/assetResolution.ts
new file mode 100644
index 0000000000..4ff76a1411
--- /dev/null
+++ b/packages/lint/src/assetResolution.ts
@@ -0,0 +1,75 @@
+import { existsSync } from "node:fs";
+import { isAbsolute, posix, relative, resolve } from "node:path";
+import { decodeUrlPathVariants } from "@hyperframes/parsers/composition";
+
+/**
+ * Shared local-asset resolution helpers used by both the project-level lint
+ * rules (`project.ts`) and the HEVC preview-codec check
+ * (`hevcPreviewLint.ts`). Split out so the latter doesn't need to import from
+ * `project.ts` (which imports it back to run the rule) — that would be a
+ * circular import within the package.
+ */
+
+export function isRemoteOrInlineUrl(url: string): boolean {
+  return /^(https?:|data:|blob:|\/\/|#)/i.test(url);
+}
+
+export function cleanAssetUrl(url: string): string {
+  return url.trim().split(/[?#]/, 1)[0] ?? "";
+}
+
+export 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);
+}
+
+export 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;
+}
+
+export 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 maskRange(src: string, pattern: RegExp): string {
+  return src.replace(pattern, (m) => " ".repeat(m.length));
+}
+
+/** Blanks out comments, `<style>`, and `<script>` bodies so tag-scanning
+ * regexes don't false-positive on commented-out or scripted markup. */
+export function maskNonScannableRanges(html: string): string {
+  let out = maskRange(html, /<!--[\s\S]*?-->/g);
+  out = maskRange(out, /<style\b[^>]*>[\s\S]*?<\/style\b[^>]*>/gi);
+  out = maskRange(out, /<script\b[^>]*>[\s\S]*?<\/script\b[^>]*>/gi);
+  return out;
+}
diff --git a/packages/lint/src/hevcPreviewLint.ts b/packages/lint/src/hevcPreviewLint.ts
new file mode 100644
index 0000000000..d8759101d3
--- /dev/null
+++ b/packages/lint/src/hevcPreviewLint.ts
@@ -0,0 +1,202 @@
+// fallow-ignore-file code-duplication
+import { execFile, execSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { rewriteAssetPath } from "@hyperframes/parsers/asset-paths";
+import {
+  cleanAssetUrl,
+  isRemoteOrInlineUrl,
+  maskNonScannableRanges,
+  resolveExistingLocalAsset,
+} from "./assetResolution.js";
+import type { HyperframeLintFinding } from "./types.js";
+
+/** Structurally compatible with `project.ts`'s (unexported) `HtmlSource` —
+ * duplicated as a shape, not imported, to avoid a circular import between
+ * this file and `project.ts` (which imports `lintHevcPreviewCodec` below). */
+interface HtmlSourceLike {
+  html: string;
+  compSrcPath?: string;
+}
+
+const FFPROBE_PATH_ENV = "HYPERFRAMES_FFPROBE_PATH";
+const PROBE_TIMEOUT_MS = 4000;
+
+// Minimal PATH/env-based ffprobe resolution, duplicated from
+// packages/cli/src/browser/ffmpeg.ts (findFFprobe). packages/lint must not
+// depend on packages/cli (the CLI depends on @hyperframes/lint, which would
+// create an import cycle) or packages/engine (too heavy for a lint check),
+// so only the ffprobe-lookup half is re-implemented here — no ffmpeg lookup,
+// no install-hint text, no Linux-distro detection.
+
+function chooseBestFfprobeCandidate(candidates: string[]): string | undefined {
+  const normalized = candidates.map((s) => s.trim()).filter(Boolean);
+  if (normalized.length === 0) return undefined;
+  const preferredExe = normalized.find((c) => c.toLowerCase().endsWith("ffprobe.exe"));
+  if (preferredExe) return preferredExe;
+  const exact = normalized.find((c) => c.toLowerCase().endsWith("ffprobe"));
+  if (exact) return exact;
+  const nonShellShim = normalized.find((c) => {
+    const lower = c.toLowerCase();
+    return !lower.endsWith(".cmd") && !lower.endsWith(".bat");
+  });
+  return nonShellShim ?? normalized[0];
+}
+
+function findFFprobeOnPath(): string | undefined {
+  try {
+    const cmd = process.platform === "win32" ? "where ffprobe" : "which ffprobe";
+    const output = execSync(cmd, {
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "pipe"],
+      timeout: 5000,
+    });
+    const candidate = chooseBestFfprobeCandidate(output.split(/\r?\n/));
+    return candidate ? resolve(candidate) : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+const COMMON_BIN_DIRS =
+  process.platform === "win32"
+    ? []
+    : ["/opt/homebrew/bin", "/usr/local/bin", "/usr/bin", "/bin", "/snap/bin"];
+
+function findFFprobeInCommonDirs(): string | undefined {
+  for (const dir of COMMON_BIN_DIRS) {
+    const candidate = `${dir}/ffprobe`;
+    if (existsSync(candidate)) return candidate;
+  }
+  return undefined;
+}
+
+function findFFprobe(): string | undefined {
+  const configured = process.env[FFPROBE_PATH_ENV]?.trim();
+  if (configured) return existsSync(configured) ? resolve(configured) : undefined;
+  return findFFprobeOnPath() ?? findFFprobeInCommonDirs();
+}
+
+function execFileAsync(file: string, args: string[]): Promise<string> {
+  return new Promise((resolvePromise, reject) => {
+    execFile(file, args, { timeout: PROBE_TIMEOUT_MS }, (error, stdout) => {
+      if (error) reject(error);
+      else resolvePromise(stdout.toString());
+    });
+  });
+}
+
+function hasHevcStream(json: unknown): boolean {
+  if (typeof json !== "object" || json === null) return false;
+  const streams = Reflect.get(json, "streams");
+  if (!Array.isArray(streams)) return false;
+  return streams.some((stream) => {
+    if (typeof stream !== "object" || stream === null) return false;
+    return Reflect.get(stream, "codec_name") === "hevc";
+  });
+}
+
+// Best-effort: any failure (ffprobe missing, times out, non-video file,
+// unparsable output) resolves to "not HEVC" rather than throwing. This rule
+// must never fail lint/check just because ffprobe isn't installed.
+async function probeIsHevc(ffprobePath: string, filePath: string): Promise<boolean> {
+  try {
+    const stdout = await execFileAsync(ffprobePath, [
+      "-v",
+      "error",
+      "-select_streams",
+      "v:0",
+      "-show_entries",
+      "stream=codec_name",
+      "-of",
+      "json",
+      filePath,
+    ]);
+    return hasHevcStream(JSON.parse(stdout));
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Collects local `<video src>` references, resolved to their absolute path
+ * and deduped by that path — this is both the candidate set AND the in-run
+ * probe cache for `lintHevcPreviewCodec` below: the same file referenced
+ * twice only ends up as one map entry, so it's only probed once.
+ *
+ * Files that don't resolve to an existing local asset are skipped here —
+ * `missing_local_asset` already reports those, and hevc_preview_codec never
+ * probes a file that doesn't exist.
+ */
+// fallow-ignore-next-line complexity
+export function collectLocalVideoCandidates(
+  projectDir: string,
+  htmlSources: HtmlSourceLike[],
+): Map<string, string> {
+  const candidates = new Map<string, string>();
+  const videoSrcRe = /<video\b[^>]*\bsrc\s*=\s*["']([^"']+)["'][^>]*>/gi;
+
+  for (const { html, compSrcPath } of htmlSources) {
+    const scannable = maskNonScannableRanges(html);
+    const re = new RegExp(videoSrcRe.source, videoSrcRe.flags);
+    let match: RegExpExecArray | null;
+    while ((match = re.exec(scannable)) !== null) {
+      const src = cleanAssetUrl(match[1] ?? "");
+      if (!src) continue;
+      if (isRemoteOrInlineUrl(src)) continue;
+      if (/^__[A-Z_]+__$/.test(src)) continue;
+      const rootRelative = compSrcPath ? rewriteAssetPath(compSrcPath, src) : src;
+      const resolvedAsset = resolveExistingLocalAsset(projectDir, rootRelative);
+      if (!resolvedAsset) continue;
+      if (!candidates.has(resolvedAsset.resolved)) candidates.set(resolvedAsset.resolved, src);
+    }
+  }
+
+  return candidates;
+}
+
+/**
+ * INFO-only finding: a locally referenced `<video>` file is encoded as
+ * HEVC/H.265. The render pipeline pre-decodes video with FFmpeg (never the
+ * browser decoder) so rendering is unaffected, but live preview and the
+ * embeddable player play the file directly in-browser, where HEVC support
+ * varies. Never escalated beyond "info" — this must not fail lint or check.
+ *
+ * `candidates` maps each unique resolved file path to a display src string
+ * (already deduped by the caller, so each file is probed exactly once here);
+ * files missing from disk are the caller's responsibility to have excluded —
+ * `missing_local_asset` covers those and this rule never probes them.
+ */
+export async function lintHevcPreviewCodec(
+  candidates: Map<string, string>,
+): Promise<HyperframeLintFinding[]> {
+  if (candidates.size === 0) return [];
+
+  const ffprobePath = findFFprobe();
+  if (!ffprobePath) return [];
+
+  const entries = [...candidates.entries()];
+  const isHevc = await Promise.all(
+    entries.map(([resolvedPath]) => probeIsHevc(ffprobePath, resolvedPath)),
+  );
+
+  const hevcSrcs = entries.filter((_, i) => isHevc[i]).map(([, src]) => src);
+  if (hevcSrcs.length === 0) return [];
+
+  const unique = [...new Set(hevcSrcs)];
+  return [
+    {
+      code: "hevc_preview_codec",
+      severity: "info",
+      message:
+        `Video file(s) use the HEVC/H.265 codec: ${unique.join(", ")}. ` +
+        "The render pipeline pre-decodes video with FFmpeg and never uses the browser's video decoder, so these render correctly. " +
+        "Live preview/player playback requires a browser with HEVC support. " +
+        "If preview playback fails, generate an H.264 proxy (e.g. via the media-use skill) and reference that instead.",
+      fixHint:
+        unique.length === 1
+          ? `Generate an H.264 proxy for "${unique[0]}" (e.g. via the media-use skill) if it fails to play in preview.`
+          : "Generate H.264 proxies for these files (e.g. via the media-use skill) if they fail to play in preview.",
+    },
+  ];
+}
diff --git a/packages/lint/src/project.test.ts b/packages/lint/src/project.test.ts
index a2705d4ced..ca20318f10 100644
--- a/packages/lint/src/project.test.ts
+++ b/packages/lint/src/project.test.ts
@@ -1,10 +1,17 @@
-import { describe, it, expect, afterEach } from "vitest";
+import { describe, it, expect, afterEach, beforeEach, vi } from "vitest";
+import { ChildProcess, execFile } from "node:child_process";
 import { mkdirSync, mkdtempSync, writeFileSync, rmSync } from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 import type { HyperframeLintFinding } from "./types.js";
 import { lintProject } from "./project.js";
 
+// Keep project lint tests independent of the host's ffprobe installation.
+vi.mock("node:child_process", () => {
+  const mocked = { ChildProcess: class {}, execFile: vi.fn(), execSync: vi.fn() };
+  return { ...mocked, default: mocked };
+});
+
 function tmpProject(name: string): string {
   return mkdtempSync(join(tmpdir(), `hf-lint-test-${name}-`));
 }
@@ -235,3 +242,163 @@ describe("template shell style sources", () => {
     expect(findings.some((finding) => finding.code === "texture_mask_asset_not_found")).toBe(true);
   });
 });
+
+describe("hevc_preview_codec", () => {
+  interface ProbeStream {
+    codec_name: string;
+    codec_tag_string: string;
+  }
+
+  const mockExecFile = vi.mocked(execFile);
+
+  // Any real file works as a stand-in "ffprobe" path — execFile itself is
+  // mocked below, so it's never actually spawned.
+  const FAKE_FFPROBE_PATH = process.execPath;
+
+  function mockFfprobeStreams(streamsByFile: Record<string, ProbeStream[]>): void {
+    mockExecFile.mockImplementation((_file, args, _options, callback) => {
+      const filePath = args[args.length - 1] ?? "";
+      callback(
+        null,
+        Buffer.from(JSON.stringify({ streams: streamsByFile[filePath] ?? [] })),
+        Buffer.alloc(0),
+      );
+      return new ChildProcess();
+    });
+  }
+
+  function videoHtml(...videoSrcs: string[]): string {
+    const videoTags = videoSrcs
+      .map(
+        (src, i) =>
+          `<video id="v${i}" class="clip" src="${src}" muted data-start="${i * 5}" data-duration="5"></video>`,
+      )
+      .join("\n    ");
+    return `<html><body>
+  <div data-composition-id="main" data-width="1920" data-height="1080" data-start="0" data-duration="10">
+    ${videoTags}
+  </div>
+  <script src="https://cdn.jsdelivr.net/npm/gsap@3/dist/gsap.min.js"></script>
+  <script>window.__timelines = window.__timelines || {}; window.__timelines["main"] = gsap.timeline({ paused: true });</script>
+</body></html>`;
+  }
+
+  function makeVideoProject(
+    videoSrc: string,
+    writeVideoFile = true,
+  ): { project: string; videoAbsPath: string } {
+    const project = makeProject(videoHtml(videoSrc));
+    const videoAbsPath = join(project, videoSrc);
+    if (writeVideoFile) writeFileSync(videoAbsPath, "fake video bytes");
+    return { project, videoAbsPath };
+  }
+
+  async function hevcFindings(project: string): Promise<HyperframeLintFinding[]> {
+    const { results } = await lintProject(project);
+    return results.flatMap((r) => r.result.findings).filter((f) => f.code === "hevc_preview_codec");
+  }
+
+  beforeEach(() => {
+    process.env.HYPERFRAMES_FFPROBE_PATH = FAKE_FFPROBE_PATH;
+    mockExecFile.mockReset();
+  });
+
+  afterEach(() => {
+    delete process.env.HYPERFRAMES_FFPROBE_PATH;
+    mockExecFile.mockReset();
+  });
+
+  it("flags an HEVC video with exactly one info finding naming the file", async () => {
+    const { project, videoAbsPath } = makeVideoProject("clip.mp4");
+    mockFfprobeStreams({
+      [videoAbsPath]: [{ codec_name: "hevc", codec_tag_string: "hvc1" }],
+    });
+
+    const result = await lintProject(project);
+    const findings = result.results
+      .flatMap((entry) => entry.result.findings)
+      .filter((finding) => finding.code === "hevc_preview_codec");
+
+    expect(findings).toHaveLength(1);
+    expect(findings[0]?.severity).toBe("info");
+    expect(findings[0]?.code).toBe("hevc_preview_codec");
+    expect(findings[0]?.message).toContain("clip.mp4");
+    expect(findings[0]?.message).toContain("requires a browser with HEVC support");
+    expect(result.totalErrors).toBe(0);
+    expect(result.results[0]?.result.ok).toBe(true);
+  });
+
+  it('flags an hev1-tagged HEVC video the same way (ffprobe reports codec_name "hevc" regardless of the container fourcc)', async () => {
+    const { project, videoAbsPath } = makeVideoProject("clip-hev1.mp4");
+    mockFfprobeStreams({
+      [videoAbsPath]: [{ codec_name: "hevc", codec_tag_string: "hev1" }],
+    });
+
+    const findings = await hevcFindings(project);
+
+    expect(findings).toHaveLength(1);
+    expect(findings[0]?.message).toContain("clip-hev1.mp4");
+  });
+
+  it("does not flag an H.264 video", async () => {
+    const { project, videoAbsPath } = makeVideoProject("clip.mp4");
+    mockFfprobeStreams({
+      [videoAbsPath]: [{ codec_name: "h264", codec_tag_string: "avc1" }],
+    });
+
+    const findings = await hevcFindings(project);
+
+    expect(findings).toHaveLength(0);
+  });
+
+  it("does not flag anything, and lint completes normally, when ffprobe cannot be resolved", async () => {
+    const { project } = makeVideoProject("clip.mp4");
+    process.env.HYPERFRAMES_FFPROBE_PATH = join(project, "missing-ffprobe");
+
+    const { results, totalErrors } = await lintProject(project);
+
+    const findings = results.flatMap((r) => r.result.findings);
+    expect(findings.some((f) => f.code === "hevc_preview_codec")).toBe(false);
+    expect(mockExecFile).not.toHaveBeenCalled();
+    expect(totalErrors).toBe(0);
+  });
+
+  it("silently skips the finding when ffprobe errors or times out", async () => {
+    const { project } = makeVideoProject("clip.mp4");
+    mockExecFile.mockImplementation((_file, _args, _options, callback) => {
+      callback(new Error("ffprobe timed out"), Buffer.alloc(0), Buffer.alloc(0));
+      return new ChildProcess();
+    });
+
+    const { results, totalErrors } = await lintProject(project);
+
+    const findings = results.flatMap((entry) => entry.result.findings);
+    expect(findings.some((finding) => finding.code === "hevc_preview_codec")).toBe(false);
+    expect(totalErrors).toBe(0);
+  });
+
+  it("does not probe or flag a missing video file — missing_local_asset covers it instead", async () => {
+    const { project } = makeVideoProject("missing.mp4", false);
+
+    const { results } = await lintProject(project);
+
+    const findings = results.flatMap((r) => r.result.findings);
+    expect(findings.some((f) => f.code === "hevc_preview_codec")).toBe(false);
+    expect(findings.some((f) => f.code === "missing_local_asset")).toBe(true);
+    expect(mockExecFile).not.toHaveBeenCalled();
+  });
+
+  it("probes the same HEVC file once when referenced twice (per-run cache)", async () => {
+    const project = makeProject(videoHtml("clip.mp4", "clip.mp4"));
+    const videoAbsPath = join(project, "clip.mp4");
+    writeFileSync(videoAbsPath, "fake video bytes");
+    mockFfprobeStreams({
+      [videoAbsPath]: [{ codec_name: "hevc", codec_tag_string: "hvc1" }],
+    });
+
+    const findings = await hevcFindings(project);
+
+    expect(findings).toHaveLength(1);
+    expect(mockExecFile).toHaveBeenCalledTimes(1);
+  });
+});
diff --git a/packages/lint/src/project.ts b/packages/lint/src/project.ts
index a23226542f..2185983ce6 100644
--- a/packages/lint/src/project.ts
+++ b/packages/lint/src/project.ts
@@ -1,10 +1,18 @@
 export { shouldBlockRender } from "./shouldBlockRender.js";
 import { existsSync, readFileSync, readdirSync } from "node:fs";
-import { dirname, extname, isAbsolute, join, posix, relative, resolve } from "node:path";
-import { decodeUrlPathVariants } from "@hyperframes/parsers/composition";
+import { dirname, extname, join, relative, resolve } from "node:path";
 import { rewriteAssetPath } from "@hyperframes/parsers/asset-paths";
 import { checkSubCompositionUsability } from "@hyperframes/parsers/sub-composition-validity";
 import { parseHTML } from "linkedom";
+import {
+  cleanAssetUrl,
+  isRemoteOrInlineUrl,
+  isWithinProjectRoot,
+  maskNonScannableRanges,
+  resolveExistingLocalAsset,
+  resolveLocalAssetCandidates,
+} from "./assetResolution.js";
+import { collectLocalVideoCandidates, lintHevcPreviewCodec } from "./hevcPreviewLint.js";
 import { lintHyperframeHtml } from "./hyperframeLinter.js";
 import type { HyperframeLintFinding, HyperframeLintResult } from "./types.js";
 import type { ParsableDocumentLike } from "@hyperframes/parsers/sub-composition-validity";
@@ -113,57 +121,6 @@ function collectCssSources(projectDir: string, html: string, compSrcPath?: strin
   return sources;
 }
 
-function isRemoteOrInlineUrl(url: string): boolean {
-  return /^(https?:|data:|blob:|\/\/|#)/i.test(url);
-}
-
-function cleanAssetUrl(url: string): string {
-  return url.trim().split(/[?#]/, 1)[0] ?? "";
-}
-
-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,
@@ -250,6 +207,7 @@ export async function lintProject(
     ...(!entryFile ? lintMultipleRootCompositions(projectDir) : []),
     ...lintDuplicateAudioTracks(allHtmlSources),
     ...lintMissingOrEmptySubComposition(projectDir, rootHtml),
+    ...(await lintHevcPreviewCodec(collectLocalVideoCandidates(projectDir, allHtmlSources))),
   ];
   if (projectFindings.length > 0) {
     for (const finding of projectFindings) {
@@ -343,17 +301,6 @@ function lintAudioSrcNotFound(
   return findings;
 }
 
-function maskRange(src: string, pattern: RegExp): string {
-  return src.replace(pattern, (m) => " ".repeat(m.length));
-}
-
-function maskNonScannableRanges(html: string): string {
-  let out = maskRange(html, /<!--[\s\S]*?-->/g);
-  out = maskRange(out, /<style\b[^>]*>[\s\S]*?<\/style\b[^>]*>/gi);
-  out = maskRange(out, /<script\b[^>]*>[\s\S]*?<\/script\b[^>]*>/gi);
-  return out;
-}
-
 // fallow-ignore-next-line complexity
 function lintMissingLocalAsset(
   projectDir: string,

From 4ac56472ee936b997cc1a6a7bddd6bdf868bb18e Mon Sep 17 00:00:00 2001
From: Miguel Angel Simon Sierra <miguel.sierra@heygen.com>
Date: Tue, 14 Jul 2026 19:33:22 -0400
Subject: [PATCH 3/4] refactor(lint): bound concurrent ffprobe processes in
 HEVC probe

---
 packages/lint/src/hevcPreviewLint.ts | 16 ++++++++++++++--
 1 file changed, 14 insertions(+), 2 deletions(-)

diff --git a/packages/lint/src/hevcPreviewLint.ts b/packages/lint/src/hevcPreviewLint.ts
index d8759101d3..b9a90d06e1 100644
--- a/packages/lint/src/hevcPreviewLint.ts
+++ b/packages/lint/src/hevcPreviewLint.ts
@@ -21,6 +21,8 @@ interface HtmlSourceLike {
 
 const FFPROBE_PATH_ENV = "HYPERFRAMES_FFPROBE_PATH";
 const PROBE_TIMEOUT_MS = 4000;
+// Bounds concurrent ffprobe child processes for compositions referencing many videos.
+const PROBE_CONCURRENCY = 8;
 
 // Minimal PATH/env-based ffprobe resolution, duplicated from
 // packages/cli/src/browser/ffmpeg.ts (findFFprobe). packages/lint must not
@@ -176,8 +178,18 @@ export async function lintHevcPreviewCodec(
   if (!ffprobePath) return [];
 
   const entries = [...candidates.entries()];
-  const isHevc = await Promise.all(
-    entries.map(([resolvedPath]) => probeIsHevc(ffprobePath, resolvedPath)),
+  const isHevc = new Array<boolean>(entries.length).fill(false);
+  let nextIndex = 0;
+  const workerCount = Math.min(PROBE_CONCURRENCY, entries.length);
+  await Promise.all(
+    Array.from({ length: workerCount }, async () => {
+      while (nextIndex < entries.length) {
+        const index = nextIndex++;
+        const entry = entries[index];
+        if (!entry) break;
+        isHevc[index] = await probeIsHevc(ffprobePath, entry[0]);
+      }
+    }),
   );
 
   const hevcSrcs = entries.filter((_, i) => isHevc[i]).map(([, src]) => src);

From 811b7554c6327224d0d23da556fd308448de36a3 Mon Sep 17 00:00:00 2001
From: Miguel Angel Simon Sierra <miguel.sierra@heygen.com>
Date: Tue, 14 Jul 2026 19:54:41 -0400
Subject: [PATCH 4/4] refactor(parsers): single shared FFmpeg/FFprobe binary
 resolver

The cli, engine, and lint packages each carried their own copy of the
ffmpeg/ffprobe lookup, annotated fallow-ignore code-duplication, and the
copies had drifted: the engine copy handled Windows PATHEXT and executed
which/where without a shell but lacked the Homebrew-dirs fallback for
GUI-spawned processes; the cli copy had the opposite. One resolver in
@hyperframes/parsers (the dependency-graph bottom) now carries the union
of both hardenings, and all three packages delegate to it. Every
consumer gets strictly more robust resolution; env-override semantics
per call site are preserved via configuredMustExist.
---
 bun.lock                                      |  28 ++--
 packages/cli/package.json                     |   1 +
 packages/cli/src/browser/ffmpeg.test.ts       |  68 +++-----
 packages/cli/src/browser/ffmpeg.ts            |  76 +--------
 packages/engine/package.json                  |   1 +
 .../engine/src/utils/ffmpegBinaries.test.ts   |  38 +----
 packages/engine/src/utils/ffmpegBinaries.ts   |  98 +-----------
 packages/lint/src/hevcPreviewLint.ts          |  64 +-------
 packages/parsers/package.json                 |  10 ++
 packages/parsers/src/ffBinaries.test.ts       | 140 +++++++++++++++++
 packages/parsers/src/ffBinaries.ts            | 147 ++++++++++++++++++
 packages/parsers/tsup.config.ts               |   1 +
 12 files changed, 355 insertions(+), 317 deletions(-)
 create mode 100644 packages/parsers/src/ffBinaries.test.ts
 create mode 100644 packages/parsers/src/ffBinaries.ts

diff --git a/bun.lock b/bun.lock
index 77c87f2c0b..c833ba73f7 100644
--- a/bun.lock
+++ b/bun.lock
@@ -22,7 +22,7 @@
     },
     "packages/aws-lambda": {
       "name": "@hyperframes/aws-lambda",
-      "version": "0.7.48",
+      "version": "0.7.57",
       "dependencies": {
         "@aws-sdk/client-s3": "^3.700.0",
         "@aws-sdk/client-sfn": "^3.700.0",
@@ -54,7 +54,7 @@
     },
     "packages/cli": {
       "name": "@hyperframes/cli",
-      "version": "0.7.48",
+      "version": "0.7.57",
       "bin": {
         "hyperframes": "./dist/cli.js",
       },
@@ -83,6 +83,7 @@
         "@hyperframes/engine": "workspace:*",
         "@hyperframes/gcp-cloud-run": "workspace:*",
         "@hyperframes/lint": "workspace:*",
+        "@hyperframes/parsers": "workspace:*",
         "@hyperframes/producer": "workspace:*",
         "@hyperframes/studio": "workspace:*",
         "@hyperframes/studio-server": "workspace:*",
@@ -103,7 +104,7 @@
     },
     "packages/core": {
       "name": "@hyperframes/core",
-      "version": "0.7.48",
+      "version": "0.7.57",
       "dependencies": {
         "@chenglou/pretext": "^0.0.5",
         "@hyperframes/lint": "workspace:*",
@@ -128,10 +129,11 @@
     },
     "packages/engine": {
       "name": "@hyperframes/engine",
-      "version": "0.7.48",
+      "version": "0.7.57",
       "dependencies": {
         "@hono/node-server": "^1.13.0",
         "@hyperframes/core": "workspace:^",
+        "@hyperframes/parsers": "workspace:^",
         "hono": "^4.6.0",
         "linkedom": "^0.18.12",
         "puppeteer": "^25.2.1",
@@ -146,7 +148,7 @@
     },
     "packages/gcp-cloud-run": {
       "name": "@hyperframes/gcp-cloud-run",
-      "version": "0.7.48",
+      "version": "0.7.57",
       "dependencies": {
         "@google-cloud/storage": "^7.14.0",
         "@google-cloud/workflows": "^4.2.0",
@@ -166,7 +168,7 @@
     },
     "packages/lint": {
       "name": "@hyperframes/lint",
-      "version": "0.7.48",
+      "version": "0.7.57",
       "dependencies": {
         "@hyperframes/parsers": "workspace:*",
         "htmlparser2": "^10.1.0",
@@ -183,7 +185,7 @@
     },
     "packages/parsers": {
       "name": "@hyperframes/parsers",
-      "version": "0.7.48",
+      "version": "0.7.57",
       "dependencies": {
         "@babel/parser": "^7.27.0",
         "acorn": "^8.17.0",
@@ -203,7 +205,7 @@
     },
     "packages/player": {
       "name": "@hyperframes/player",
-      "version": "0.7.48",
+      "version": "0.7.57",
       "dependencies": {
         "@hyperframes/core": "workspace:*",
       },
@@ -218,7 +220,7 @@
     },
     "packages/producer": {
       "name": "@hyperframes/producer",
-      "version": "0.7.48",
+      "version": "0.7.57",
       "dependencies": {
         "@fontsource/archivo-black": "^5.2.8",
         "@fontsource/eb-garamond": "^5.2.7",
@@ -263,7 +265,7 @@
     },
     "packages/sdk": {
       "name": "@hyperframes/sdk",
-      "version": "0.7.48",
+      "version": "0.7.57",
       "dependencies": {
         "@hyperframes/core": "workspace:*",
         "@hyperframes/parsers": "workspace:*",
@@ -293,7 +295,7 @@
     },
     "packages/shader-transitions": {
       "name": "@hyperframes/shader-transitions",
-      "version": "0.7.48",
+      "version": "0.7.57",
       "dependencies": {
         "html2canvas": "^1.4.1",
       },
@@ -305,7 +307,7 @@
     },
     "packages/studio": {
       "name": "@hyperframes/studio",
-      "version": "0.7.48",
+      "version": "0.7.57",
       "dependencies": {
         "@codemirror/autocomplete": "^6.20.1",
         "@codemirror/commands": "^6.10.3",
@@ -353,7 +355,7 @@
     },
     "packages/studio-server": {
       "name": "@hyperframes/studio-server",
-      "version": "0.7.48",
+      "version": "0.7.57",
       "dependencies": {
         "@hyperframes/core": "workspace:*",
         "@hyperframes/parsers": "workspace:*",
diff --git a/packages/cli/package.json b/packages/cli/package.json
index f979d456a5..1af1a55f01 100644
--- a/packages/cli/package.json
+++ b/packages/cli/package.json
@@ -52,6 +52,7 @@
     "@hyperframes/engine": "workspace:*",
     "@hyperframes/gcp-cloud-run": "workspace:*",
     "@hyperframes/lint": "workspace:*",
+    "@hyperframes/parsers": "workspace:*",
     "@hyperframes/producer": "workspace:*",
     "@hyperframes/studio": "workspace:*",
     "@hyperframes/studio-server": "workspace:*",
diff --git a/packages/cli/src/browser/ffmpeg.test.ts b/packages/cli/src/browser/ffmpeg.test.ts
index f541e6d40f..0ab7be840b 100644
--- a/packages/cli/src/browser/ffmpeg.test.ts
+++ b/packages/cli/src/browser/ffmpeg.test.ts
@@ -1,55 +1,29 @@
-import { execSync } from "node:child_process";
-import { existsSync } from "node:fs";
-import { resolve } from "node:path";
-import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-
-vi.mock("node:child_process", () => ({ execSync: vi.fn() }));
-vi.mock("node:fs", () => ({ existsSync: vi.fn() }));
-
-const mockExec = vi.mocked(execSync);
-const mockExists = vi.mocked(existsSync);
-
-// The common-dir fallback list is platform-gated (empty on win32), so pin the
-// platform to a POSIX value to keep the test deterministic on Windows CI.
-const originalPlatform = process.platform;
-beforeEach(() => {
-  Object.defineProperty(process, "platform", { value: "linux", configurable: true });
-  vi.resetModules();
-});
-
-afterEach(() => {
-  Object.defineProperty(process, "platform", { value: originalPlatform, configurable: true });
-  vi.clearAllMocks();
-  delete process.env.HYPERFRAMES_FFMPEG_PATH;
-});
-
-describe("findFFmpeg", () => {
-  it("prefers the real Windows exe when where lists a cmd shim first", async () => {
-    Object.defineProperty(process, "platform", { value: "win32", configurable: true });
-    mockExec.mockReturnValue("C:\\tools\\ffmpeg.cmd\r\nC:\\tools\\ffmpeg.exe\r\n");
-
-    const { findFFmpeg } = await import("./ffmpeg.js");
-    expect(findFFmpeg()).toBe(resolve("C:\\tools\\ffmpeg.exe"));
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { afterEach, describe, expect, it } from "vitest";
+import { findFFmpeg, findFFprobe } from "./ffmpeg.js";
+
+// Lookup mechanics (PATH scan, common-dir fallback, Windows shim preference)
+// are covered by @hyperframes/parsers ffBinaries.test.ts. These tests pin the
+// CLI wrapper's contract: a configured-but-missing override means "not found"
+// so callers surface the install hint instead of a spawn error.
+describe("findFFmpeg / findFFprobe", () => {
+  afterEach(() => {
+    delete process.env.HYPERFRAMES_FFMPEG_PATH;
+    delete process.env.HYPERFRAMES_FFPROBE_PATH;
   });
 
-  it("falls back to a common install dir when `which` fails (GUI-launched PATH)", async () => {
-    // Simulate a process whose PATH lacks /opt/homebrew/bin: `which ffmpeg` throws.
-    mockExec.mockImplementation(() => {
-      throw new Error("which: no ffmpeg in PATH");
-    });
-    mockExists.mockImplementation((p) => p === "/opt/homebrew/bin/ffmpeg");
+  it("returns undefined when the env override points at a missing file", () => {
+    process.env.HYPERFRAMES_FFMPEG_PATH = join(tmpdir(), "missing-ffmpeg");
+    process.env.HYPERFRAMES_FFPROBE_PATH = join(tmpdir(), "missing-ffprobe");
 
-    const { findFFmpeg } = await import("./ffmpeg.js");
-    expect(findFFmpeg()).toBe("/opt/homebrew/bin/ffmpeg");
+    expect(findFFmpeg()).toBeUndefined();
+    expect(findFFprobe()).toBeUndefined();
   });
 
-  it("returns undefined when ffmpeg is on neither PATH nor a common dir", async () => {
-    mockExec.mockImplementation(() => {
-      throw new Error("not found");
-    });
-    mockExists.mockReturnValue(false);
+  it("returns the configured path when the env override exists", () => {
+    process.env.HYPERFRAMES_FFMPEG_PATH = process.execPath;
 
-    const { findFFmpeg } = await import("./ffmpeg.js");
-    expect(findFFmpeg()).toBeUndefined();
+    expect(findFFmpeg()).toBe(process.execPath);
   });
 });
diff --git a/packages/cli/src/browser/ffmpeg.ts b/packages/cli/src/browser/ffmpeg.ts
index e5f77cf62c..676c595cc4 100644
--- a/packages/cli/src/browser/ffmpeg.ts
+++ b/packages/cli/src/browser/ffmpeg.ts
@@ -1,79 +1,17 @@
-// fallow-ignore-file code-duplication
-import { execSync } from "node:child_process";
-import { existsSync } from "node:fs";
-import { resolve } from "node:path";
+import { findFfBinary } from "@hyperframes/parsers/ff-binaries";
 import { detectLinuxDistro, ffmpegInstallCommand } from "./linuxDeps.js";
 
-export const FFMPEG_PATH_ENV = "HYPERFRAMES_FFMPEG_PATH";
-export const FFPROBE_PATH_ENV = "HYPERFRAMES_FFPROBE_PATH";
-
-function chooseBestPathCandidate(
-  name: "ffmpeg" | "ffprobe",
-  candidates: string[],
-): string | undefined {
-  const normalized = candidates.map((s) => s.trim()).filter(Boolean);
-  if (normalized.length === 0) return undefined;
-  const lowerName = name.toLowerCase();
-  const preferredExe = normalized.find((candidate) =>
-    candidate.toLowerCase().endsWith(`${lowerName}.exe`),
-  );
-  if (preferredExe) return preferredExe;
-  const exact = normalized.find((candidate) => candidate.toLowerCase().endsWith(lowerName));
-  if (exact) return exact;
-  const nonShellShim = normalized.find((candidate) => {
-    const lower = candidate.toLowerCase();
-    return !lower.endsWith(".cmd") && !lower.endsWith(".bat");
-  });
-  return nonShellShim ?? normalized[0];
-}
-
-function findOnPath(name: "ffmpeg" | "ffprobe"): string | undefined {
-  try {
-    const cmd = process.platform === "win32" ? `where ${name}` : `which ${name}`;
-    const output = execSync(cmd, {
-      encoding: "utf-8",
-      stdio: ["pipe", "pipe", "pipe"],
-      timeout: 5000,
-    });
-    const candidate = chooseBestPathCandidate(name, output.split(/\r?\n/));
-    return candidate ? resolve(candidate) : undefined;
-  } catch {
-    return undefined;
-  }
-}
-
-// GUI/Dock/launchd-spawned processes on macOS don't inherit the shell PATH, so
-// `which ffmpeg` fails even when ffmpeg is installed via Homebrew. Probe the
-// well-known install dirs as a fallback. (No-op on Windows, where `where` and
-// installer-added PATH entries cover it.)
-const COMMON_BIN_DIRS =
-  process.platform === "win32"
-    ? []
-    : ["/opt/homebrew/bin", "/usr/local/bin", "/usr/bin", "/bin", "/snap/bin"];
-
-function findInCommonDirs(name: "ffmpeg" | "ffprobe"): string | undefined {
-  for (const dir of COMMON_BIN_DIRS) {
-    const candidate = `${dir}/${name}`;
-    if (existsSync(candidate)) return candidate;
-  }
-  return undefined;
-}
-
-function findConfiguredBinary(
-  envName: string,
-  binaryName: "ffmpeg" | "ffprobe",
-): string | undefined {
-  const configured = process.env[envName]?.trim();
-  if (configured) return existsSync(configured) ? resolve(configured) : undefined;
-  return findOnPath(binaryName) ?? findInCommonDirs(binaryName);
-}
+export { FFMPEG_PATH_ENV, FFPROBE_PATH_ENV } from "@hyperframes/parsers/ff-binaries";
 
+// `configuredMustExist`: the CLI surfaces an install hint when a binary is
+// missing, so an env override pointing at a nonexistent file reports as
+// not-found instead of being handed to spawn.
 export function findFFmpeg(): string | undefined {
-  return findConfiguredBinary(FFMPEG_PATH_ENV, "ffmpeg");
+  return findFfBinary("ffmpeg", { configuredMustExist: true });
 }
 
 export function findFFprobe(): string | undefined {
-  return findConfiguredBinary(FFPROBE_PATH_ENV, "ffprobe");
+  return findFfBinary("ffprobe", { configuredMustExist: true });
 }
 
 export function getFFmpegInstallHint(): string {
diff --git a/packages/engine/package.json b/packages/engine/package.json
index a5e3361cbe..fcec2af0fc 100644
--- a/packages/engine/package.json
+++ b/packages/engine/package.json
@@ -47,6 +47,7 @@
   "dependencies": {
     "@hono/node-server": "^1.13.0",
     "@hyperframes/core": "workspace:^",
+    "@hyperframes/parsers": "workspace:^",
     "hono": "^4.6.0",
     "linkedom": "^0.18.12",
     "puppeteer": "^25.2.1",
diff --git a/packages/engine/src/utils/ffmpegBinaries.test.ts b/packages/engine/src/utils/ffmpegBinaries.test.ts
index d55730d69e..5388e50432 100644
--- a/packages/engine/src/utils/ffmpegBinaries.test.ts
+++ b/packages/engine/src/utils/ffmpegBinaries.test.ts
@@ -1,7 +1,4 @@
-// fallow-ignore-file code-duplication
-import { chmodSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join, resolve } from "node:path";
+import { resolve } from "node:path";
 import { afterEach, describe, expect, it, vi } from "vitest";
 import {
   assertConfiguredFfmpegBinariesExist,
@@ -48,39 +45,6 @@ describe("ffmpeg binary env resolution", () => {
     expect(() => assertConfiguredFfmpegBinariesExist()).not.toThrow();
   });
 
-  it("prefers the real Windows exe when PATH lookup lists a cmd shim first", async () => {
-    vi.resetModules();
-    vi.doMock("child_process", () => ({
-      execFileSync: () => "C:\\tools\\ffmpeg.cmd\r\nC:\\tools\\ffmpeg.exe\r\n",
-    }));
-
-    const { getFfmpegBinary: getMockedFfmpegBinary } = await import("./ffmpegBinaries.js");
-
-    expect(getMockedFfmpegBinary()).toBe(resolve("C:\\tools\\ffmpeg.exe"));
-  });
-
-  it("falls back to scanning PATH when which/where fails", async () => {
-    const binDir = mkdtempSync(join(tmpdir(), "hyperframes-ffmpeg-path-"));
-    const ffmpegPath = join(binDir, process.platform === "win32" ? "ffmpeg.exe" : "ffmpeg");
-    const execFileSync = vi.fn(() => {
-      throw new Error("lookup command failed");
-    });
-    writeFileSync(ffmpegPath, "#!/bin/sh\n");
-    chmodSync(ffmpegPath, 0o755);
-    process.env.PATH = binDir;
-    vi.resetModules();
-    vi.doMock("child_process", () => ({ execFileSync }));
-
-    try {
-      const { getFfmpegBinary: getMockedFfmpegBinary } = await import("./ffmpegBinaries.js");
-
-      expect(getMockedFfmpegBinary()).toBe(resolve(ffmpegPath));
-      expect(execFileSync).toHaveBeenCalledOnce();
-    } finally {
-      rmSync(binDir, { force: true, recursive: true });
-    }
-  });
-
   it("calls out a mangled replacement character in configured binary paths", () => {
     process.env.HYPERFRAMES_FFMPEG_PATH = "/missing/ffmpeg�.exe";
 
diff --git a/packages/engine/src/utils/ffmpegBinaries.ts b/packages/engine/src/utils/ffmpegBinaries.ts
index 46c470bcf8..702f0a591d 100644
--- a/packages/engine/src/utils/ffmpegBinaries.ts
+++ b/packages/engine/src/utils/ffmpegBinaries.ts
@@ -1,99 +1,17 @@
-// fallow-ignore-file code-duplication
-import { execFileSync } from "child_process";
-import { accessSync, constants, existsSync } from "fs";
-import { delimiter, join, resolve } from "path";
+import { existsSync } from "fs";
+import { FFMPEG_PATH_ENV, FFPROBE_PATH_ENV, findFfBinary } from "@hyperframes/parsers/ff-binaries";
 
-export const FFMPEG_PATH_ENV = "HYPERFRAMES_FFMPEG_PATH";
-export const FFPROBE_PATH_ENV = "HYPERFRAMES_FFPROBE_PATH";
-
-const pathCache = new Map<string, string | undefined>();
-
-function candidateFileName(candidate: string): string {
-  return candidate.split(/[\\/]/).at(-1)?.toLowerCase() ?? candidate.toLowerCase();
-}
-
-function chooseBestPathCandidate(
-  name: "ffmpeg" | "ffprobe",
-  candidates: readonly string[],
-): string | undefined {
-  const normalized = candidates.map((candidate) => candidate.trim()).filter(Boolean);
-  return (
-    normalized.find((candidate) => candidateFileName(candidate) === `${name}.exe`) ??
-    normalized.find((candidate) => candidateFileName(candidate) === name) ??
-    normalized.find((candidate) => !candidateFileName(candidate).match(/\.(cmd|bat)$/i)) ??
-    normalized[0]
-  );
-}
-
-function scanPath(name: "ffmpeg" | "ffprobe"): string | undefined {
-  const pathValue = process.env.PATH;
-  if (!pathValue) return undefined;
-
-  const extensions =
-    process.platform === "win32"
-      ? [
-          ".exe",
-          ...new Set(
-            (process.env.PATHEXT ?? ".COM;.EXE;.BAT;.CMD")
-              .split(";")
-              .map((ext) => ext.trim().toLowerCase())
-              .filter(Boolean),
-          ),
-          "",
-        ]
-      : [""];
-  const candidates: string[] = [];
-  for (const dir of pathValue.split(delimiter)) {
-    if (!dir) continue;
-    for (const ext of extensions) {
-      const candidate = join(dir, `${name}${ext}`);
-      if (isExecutablePathCandidate(candidate)) candidates.push(candidate);
-    }
-  }
-  return chooseBestPathCandidate(name, candidates);
-}
-
-function isExecutablePathCandidate(candidate: string): boolean {
-  if (process.platform === "win32") return existsSync(candidate);
-  try {
-    accessSync(candidate, constants.X_OK);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-function findOnPath(name: "ffmpeg" | "ffprobe"): string | undefined {
-  if (pathCache.has(name)) return pathCache.get(name);
-  let found: string | undefined;
-  try {
-    const command = process.platform === "win32" ? "where" : "which";
-    const output = execFileSync(command, [name], {
-      encoding: "utf-8",
-      stdio: ["pipe", "pipe", "pipe"],
-      timeout: 5000,
-    });
-    found = chooseBestPathCandidate(name, output.split(/\r?\n/));
-  } catch {
-    found = scanPath(name);
-  }
-  const resolved = found ? resolve(found) : undefined;
-  pathCache.set(name, resolved);
-  return resolved;
-}
-
-function getConfiguredBinary(envName: string, binaryName: "ffmpeg" | "ffprobe"): string {
-  const configured = process.env[envName]?.trim();
-  if (configured) return resolve(configured);
-  return findOnPath(binaryName) ?? binaryName;
-}
+export { FFMPEG_PATH_ENV, FFPROBE_PATH_ENV };
 
+// The engine hands spawn a bare binary name as the last resort so the spawn
+// error names what the user must install; a configured-but-missing override
+// is surfaced separately by assertConfiguredFfmpegBinariesExist below.
 export function getFfmpegBinary(): string {
-  return getConfiguredBinary(FFMPEG_PATH_ENV, "ffmpeg");
+  return findFfBinary("ffmpeg") ?? "ffmpeg";
 }
 
 export function getFfprobeBinary(): string {
-  return getConfiguredBinary(FFPROBE_PATH_ENV, "ffprobe");
+  return findFfBinary("ffprobe") ?? "ffprobe";
 }
 
 export function assertConfiguredFfmpegBinariesExist(): void {
diff --git a/packages/lint/src/hevcPreviewLint.ts b/packages/lint/src/hevcPreviewLint.ts
index b9a90d06e1..db1c2e5361 100644
--- a/packages/lint/src/hevcPreviewLint.ts
+++ b/packages/lint/src/hevcPreviewLint.ts
@@ -1,8 +1,6 @@
-// fallow-ignore-file code-duplication
-import { execFile, execSync } from "node:child_process";
-import { existsSync } from "node:fs";
-import { resolve } from "node:path";
+import { execFile } from "node:child_process";
 import { rewriteAssetPath } from "@hyperframes/parsers/asset-paths";
+import { findFfBinary } from "@hyperframes/parsers/ff-binaries";
 import {
   cleanAssetUrl,
   isRemoteOrInlineUrl,
@@ -19,66 +17,10 @@ interface HtmlSourceLike {
   compSrcPath?: string;
 }
 
-const FFPROBE_PATH_ENV = "HYPERFRAMES_FFPROBE_PATH";
 const PROBE_TIMEOUT_MS = 4000;
 // Bounds concurrent ffprobe child processes for compositions referencing many videos.
 const PROBE_CONCURRENCY = 8;
 
-// Minimal PATH/env-based ffprobe resolution, duplicated from
-// packages/cli/src/browser/ffmpeg.ts (findFFprobe). packages/lint must not
-// depend on packages/cli (the CLI depends on @hyperframes/lint, which would
-// create an import cycle) or packages/engine (too heavy for a lint check),
-// so only the ffprobe-lookup half is re-implemented here — no ffmpeg lookup,
-// no install-hint text, no Linux-distro detection.
-
-function chooseBestFfprobeCandidate(candidates: string[]): string | undefined {
-  const normalized = candidates.map((s) => s.trim()).filter(Boolean);
-  if (normalized.length === 0) return undefined;
-  const preferredExe = normalized.find((c) => c.toLowerCase().endsWith("ffprobe.exe"));
-  if (preferredExe) return preferredExe;
-  const exact = normalized.find((c) => c.toLowerCase().endsWith("ffprobe"));
-  if (exact) return exact;
-  const nonShellShim = normalized.find((c) => {
-    const lower = c.toLowerCase();
-    return !lower.endsWith(".cmd") && !lower.endsWith(".bat");
-  });
-  return nonShellShim ?? normalized[0];
-}
-
-function findFFprobeOnPath(): string | undefined {
-  try {
-    const cmd = process.platform === "win32" ? "where ffprobe" : "which ffprobe";
-    const output = execSync(cmd, {
-      encoding: "utf-8",
-      stdio: ["pipe", "pipe", "pipe"],
-      timeout: 5000,
-    });
-    const candidate = chooseBestFfprobeCandidate(output.split(/\r?\n/));
-    return candidate ? resolve(candidate) : undefined;
-  } catch {
-    return undefined;
-  }
-}
-
-const COMMON_BIN_DIRS =
-  process.platform === "win32"
-    ? []
-    : ["/opt/homebrew/bin", "/usr/local/bin", "/usr/bin", "/bin", "/snap/bin"];
-
-function findFFprobeInCommonDirs(): string | undefined {
-  for (const dir of COMMON_BIN_DIRS) {
-    const candidate = `${dir}/ffprobe`;
-    if (existsSync(candidate)) return candidate;
-  }
-  return undefined;
-}
-
-function findFFprobe(): string | undefined {
-  const configured = process.env[FFPROBE_PATH_ENV]?.trim();
-  if (configured) return existsSync(configured) ? resolve(configured) : undefined;
-  return findFFprobeOnPath() ?? findFFprobeInCommonDirs();
-}
-
 function execFileAsync(file: string, args: string[]): Promise<string> {
   return new Promise((resolvePromise, reject) => {
     execFile(file, args, { timeout: PROBE_TIMEOUT_MS }, (error, stdout) => {
@@ -174,7 +116,7 @@ export async function lintHevcPreviewCodec(
 ): Promise<HyperframeLintFinding[]> {
   if (candidates.size === 0) return [];
 
-  const ffprobePath = findFFprobe();
+  const ffprobePath = findFfBinary("ffprobe", { configuredMustExist: true });
   if (!ffprobePath) return [];
 
   const entries = [...candidates.entries()];
diff --git a/packages/parsers/package.json b/packages/parsers/package.json
index dfe852fe86..f6cdea5ced 100644
--- a/packages/parsers/package.json
+++ b/packages/parsers/package.json
@@ -87,6 +87,12 @@
       "node": "./dist/subCompositionValidity.js",
       "import": "./src/subCompositionValidity.ts",
       "types": "./src/subCompositionValidity.ts"
+    },
+    "./ff-binaries": {
+      "bun": "./src/ffBinaries.ts",
+      "node": "./dist/ffBinaries.js",
+      "import": "./src/ffBinaries.ts",
+      "types": "./src/ffBinaries.ts"
     }
   },
   "publishConfig": {
@@ -140,6 +146,10 @@
       "./sub-composition-validity": {
         "import": "./dist/subCompositionValidity.js",
         "types": "./dist/subCompositionValidity.d.ts"
+      },
+      "./ff-binaries": {
+        "import": "./dist/ffBinaries.js",
+        "types": "./dist/ffBinaries.d.ts"
       }
     },
     "main": "./dist/index.js",
diff --git a/packages/parsers/src/ffBinaries.test.ts b/packages/parsers/src/ffBinaries.test.ts
new file mode 100644
index 0000000000..858750bac5
--- /dev/null
+++ b/packages/parsers/src/ffBinaries.test.ts
@@ -0,0 +1,140 @@
+import { chmodSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+type FfBinariesModule = typeof import("./ffBinaries.js");
+
+// The module caches system lookups in module state, so each test that
+// exercises lookup mechanics resets modules and dynamic-imports a fresh copy.
+async function importFresh(): Promise<FfBinariesModule> {
+  return import("./ffBinaries.js");
+}
+
+describe("findFfBinary", () => {
+  const originalFfmpegPath = process.env.HYPERFRAMES_FFMPEG_PATH;
+  const originalPath = process.env.PATH;
+  const originalPlatform = process.platform;
+
+  afterEach(() => {
+    vi.resetModules();
+    vi.doUnmock("node:child_process");
+    vi.doUnmock("node:fs");
+    if (originalFfmpegPath === undefined) delete process.env.HYPERFRAMES_FFMPEG_PATH;
+    else process.env.HYPERFRAMES_FFMPEG_PATH = originalFfmpegPath;
+    if (originalPath === undefined) delete process.env.PATH;
+    else process.env.PATH = originalPath;
+    Object.defineProperty(process, "platform", { value: originalPlatform, configurable: true });
+  });
+
+  it("returns the resolved env override without touching the system", async () => {
+    process.env.HYPERFRAMES_FFMPEG_PATH = "/tools/ffmpeg";
+    vi.resetModules();
+    const { findFfBinary } = await importFresh();
+
+    expect(findFfBinary("ffmpeg")).toBe(resolve("/tools/ffmpeg"));
+  });
+
+  it("treats a missing env override as not-found when configuredMustExist is set", async () => {
+    process.env.HYPERFRAMES_FFMPEG_PATH = join(tmpdir(), "definitely-missing-ffmpeg");
+    vi.resetModules();
+    const { findFfBinary } = await importFresh();
+
+    expect(findFfBinary("ffmpeg", { configuredMustExist: true })).toBeUndefined();
+    expect(findFfBinary("ffmpeg")).toBe(resolve(join(tmpdir(), "definitely-missing-ffmpeg")));
+  });
+
+  it("prefers the real Windows exe when where lists a cmd shim first", async () => {
+    delete process.env.HYPERFRAMES_FFMPEG_PATH;
+    Object.defineProperty(process, "platform", { value: "win32", configurable: true });
+    vi.resetModules();
+    vi.doMock("node:child_process", () => {
+      const mocked = { execFileSync: () => "C:\\tools\\ffmpeg.cmd\r\nC:\\tools\\ffmpeg.exe\r\n" };
+      return { ...mocked, default: mocked };
+    });
+    const { findFfBinary } = await importFresh();
+
+    expect(findFfBinary("ffmpeg")).toBe(resolve("C:\\tools\\ffmpeg.exe"));
+  });
+
+  it("falls back to scanning PATH when which/where fails", async () => {
+    delete process.env.HYPERFRAMES_FFMPEG_PATH;
+    const binDir = mkdtempSync(join(tmpdir(), "hyperframes-ffbinaries-"));
+    const ffmpegPath = join(binDir, process.platform === "win32" ? "ffmpeg.exe" : "ffmpeg");
+    writeFileSync(ffmpegPath, "#!/bin/sh\n");
+    chmodSync(ffmpegPath, 0o755);
+    process.env.PATH = binDir;
+    const execFileSync = vi.fn(() => {
+      throw new Error("lookup command failed");
+    });
+    vi.resetModules();
+    vi.doMock("node:child_process", () => ({ execFileSync, default: { execFileSync } }));
+
+    try {
+      const { findFfBinary } = await importFresh();
+
+      expect(findFfBinary("ffmpeg")).toBe(resolve(ffmpegPath));
+      expect(execFileSync).toHaveBeenCalledOnce();
+    } finally {
+      rmSync(binDir, { force: true, recursive: true });
+    }
+  });
+
+  it("falls back to a common install dir when which and the PATH scan both fail", async () => {
+    delete process.env.HYPERFRAMES_FFMPEG_PATH;
+    Object.defineProperty(process, "platform", { value: "linux", configurable: true });
+    process.env.PATH = "";
+    vi.resetModules();
+    vi.doMock("node:child_process", () => {
+      const mocked = {
+        execFileSync: () => {
+          throw new Error("which: no ffmpeg in PATH");
+        },
+      };
+      return { ...mocked, default: mocked };
+    });
+    vi.doMock("node:fs", () => {
+      const mocked = {
+        existsSync: (candidate: unknown) => candidate === "/opt/homebrew/bin/ffmpeg",
+        accessSync: () => {
+          throw new Error("not executable");
+        },
+        constants: { X_OK: 1 },
+      };
+      return { ...mocked, default: mocked };
+    });
+    const { findFfBinary } = await importFresh();
+
+    expect(findFfBinary("ffmpeg")).toBe(resolve("/opt/homebrew/bin/ffmpeg"));
+  });
+
+  it("returns undefined when the binary is nowhere, and caches the miss until cleared", async () => {
+    delete process.env.HYPERFRAMES_FFMPEG_PATH;
+    Object.defineProperty(process, "platform", { value: "linux", configurable: true });
+    process.env.PATH = "";
+    const execFileSync = vi.fn(() => {
+      throw new Error("not found");
+    });
+    vi.resetModules();
+    vi.doMock("node:child_process", () => ({ execFileSync, default: { execFileSync } }));
+    vi.doMock("node:fs", () => {
+      const mocked = {
+        existsSync: () => false,
+        accessSync: () => {
+          throw new Error("not executable");
+        },
+        constants: { X_OK: 1 },
+      };
+      return { ...mocked, default: mocked };
+    });
+    const { findFfBinary, clearFfBinaryLookupCache } = await importFresh();
+
+    expect(findFfBinary("ffmpeg")).toBeUndefined();
+    expect(findFfBinary("ffmpeg")).toBeUndefined();
+    expect(execFileSync).toHaveBeenCalledOnce();
+
+    clearFfBinaryLookupCache();
+    expect(findFfBinary("ffmpeg")).toBeUndefined();
+    expect(execFileSync).toHaveBeenCalledTimes(2);
+  });
+});
diff --git a/packages/parsers/src/ffBinaries.ts b/packages/parsers/src/ffBinaries.ts
new file mode 100644
index 0000000000..1f29666301
--- /dev/null
+++ b/packages/parsers/src/ffBinaries.ts
@@ -0,0 +1,147 @@
+import { execFileSync } from "node:child_process";
+import { accessSync, constants, existsSync } from "node:fs";
+import { delimiter, join, resolve } from "node:path";
+
+/**
+ * Shared FFmpeg/FFprobe binary resolution for every package that shells out
+ * to them (engine, cli, lint). Node-only: import via the
+ * `@hyperframes/parsers/ff-binaries` subpath, never from a browser bundle.
+ */
+
+export const FFMPEG_PATH_ENV = "HYPERFRAMES_FFMPEG_PATH";
+export const FFPROBE_PATH_ENV = "HYPERFRAMES_FFPROBE_PATH";
+
+export type FfBinaryName = "ffmpeg" | "ffprobe";
+
+const ENV_BY_NAME: Record<FfBinaryName, string> = {
+  ffmpeg: FFMPEG_PATH_ENV,
+  ffprobe: FFPROBE_PATH_ENV,
+};
+
+const pathLookupCache = new Map<FfBinaryName, string | undefined>();
+
+function candidateFileName(candidate: string): string {
+  return candidate.split(/[\\/]/).at(-1)?.toLowerCase() ?? candidate.toLowerCase();
+}
+
+function chooseBestPathCandidate(
+  name: FfBinaryName,
+  candidates: readonly string[],
+): string | undefined {
+  const normalized = candidates.map((candidate) => candidate.trim()).filter(Boolean);
+  return (
+    normalized.find((candidate) => candidateFileName(candidate) === `${name}.exe`) ??
+    normalized.find((candidate) => candidateFileName(candidate) === name) ??
+    normalized.find((candidate) => !candidateFileName(candidate).match(/\.(cmd|bat)$/i)) ??
+    normalized[0]
+  );
+}
+
+function isExecutablePathCandidate(candidate: string): boolean {
+  if (process.platform === "win32") return existsSync(candidate);
+  try {
+    accessSync(candidate, constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function scanPath(name: FfBinaryName): string | undefined {
+  const pathValue = process.env.PATH;
+  if (!pathValue) return undefined;
+
+  const extensions =
+    process.platform === "win32"
+      ? [
+          ".exe",
+          ...new Set(
+            (process.env.PATHEXT ?? ".COM;.EXE;.BAT;.CMD")
+              .split(";")
+              .map((ext) => ext.trim().toLowerCase())
+              .filter(Boolean),
+          ),
+          "",
+        ]
+      : [""];
+  const candidates: string[] = [];
+  for (const dir of pathValue.split(delimiter)) {
+    if (!dir) continue;
+    for (const ext of extensions) {
+      const candidate = join(dir, `${name}${ext}`);
+      if (isExecutablePathCandidate(candidate)) candidates.push(candidate);
+    }
+  }
+  return chooseBestPathCandidate(name, candidates);
+}
+
+// GUI/Dock/launchd-spawned processes on macOS don't inherit the shell PATH, so
+// `which ffmpeg` fails even when ffmpeg is installed via Homebrew. Probe the
+// well-known install dirs as a last resort. (No-op on Windows, where `where`
+// and installer-added PATH entries cover it.)
+const COMMON_BIN_DIRS =
+  process.platform === "win32"
+    ? []
+    : ["/opt/homebrew/bin", "/usr/local/bin", "/usr/bin", "/bin", "/snap/bin"];
+
+function findInCommonDirs(name: FfBinaryName): string | undefined {
+  for (const dir of COMMON_BIN_DIRS) {
+    const candidate = `${dir}/${name}`;
+    if (existsSync(candidate)) return candidate;
+  }
+  return undefined;
+}
+
+function lookupOnSystem(name: FfBinaryName): string | undefined {
+  if (pathLookupCache.has(name)) return pathLookupCache.get(name);
+  let found: string | undefined;
+  try {
+    const command = process.platform === "win32" ? "where" : "which";
+    const output = execFileSync(command, [name], {
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "pipe"],
+      timeout: 5000,
+    });
+    found = chooseBestPathCandidate(name, output.split(/\r?\n/));
+  } catch {
+    found = scanPath(name);
+  }
+  found ??= findInCommonDirs(name);
+  const resolved = found ? resolve(found) : undefined;
+  pathLookupCache.set(name, resolved);
+  return resolved;
+}
+
+export interface FindFfBinaryOptions {
+  /**
+   * How to treat an env override that points at a missing file: `true`
+   * reports the binary as not found (callers that surface an install hint or
+   * skip probing), `false`/unset returns the configured path as-is (callers
+   * that validate the override separately and want spawn errors to name the
+   * path the user configured).
+   */
+  configuredMustExist?: boolean;
+}
+
+/**
+ * Resolve an FFmpeg-family binary: env override first, then `which`/`where`,
+ * then a manual PATH scan (covers Windows PATHEXT), then well-known Unix
+ * install dirs. System lookups are cached per binary for the process
+ * lifetime; the env override is re-read on every call.
+ */
+export function findFfBinary(
+  name: FfBinaryName,
+  options: FindFfBinaryOptions = {},
+): string | undefined {
+  const configured = process.env[ENV_BY_NAME[name]]?.trim();
+  if (configured) {
+    if (options.configuredMustExist && !existsSync(configured)) return undefined;
+    return resolve(configured);
+  }
+  return lookupOnSystem(name);
+}
+
+/** Test hook: drop cached system lookups so resolution can be re-exercised. */
+export function clearFfBinaryLookupCache(): void {
+  pathLookupCache.clear();
+}
diff --git a/packages/parsers/tsup.config.ts b/packages/parsers/tsup.config.ts
index 62c3c4957e..52d059222c 100644
--- a/packages/parsers/tsup.config.ts
+++ b/packages/parsers/tsup.config.ts
@@ -14,6 +14,7 @@ export default defineConfig({
     assets: "src/assets.ts",
     composition: "src/composition.ts",
     subCompositionValidity: "src/subCompositionValidity.ts",
+    ffBinaries: "src/ffBinaries.ts",
   },
   format: ["esm"],
   outDir: "dist",