fix: add media rendering guardrails to prevent silent failures (#112)

## Summary - **Lint rules** catch media elements missing `id` (renderer silently skips them), missing `src`, `preload="none"` (blocks renderer), and video nested in timed divs (freezes playback). Upgraded `video_nested_in_timed_element` from warning to error. - **Compiler** strips `preload="none"` from media during compilation. Runs parallel, cached keyframe interval analysis via ffprobe — warns on sparse keyframes (>2s) that cause seek failures and audio/video desync. Suggested ffmpeg command preserves audio (`-c:a copy`). - **Pre-render lint** lints `index.html` + all `compositions/*.html` sub-compositions before render via shared `lintProject()` helper. Warns by default; `--strict` blocks on errors, `--strict-all` blocks on errors + warnings. - **Render orchestrator** logs a hint to retry with `--workers 1` when parallel capture times out on video-heavy compositions. - **Refactor**: extracted `runFfprobe()` + `parseProbeJson()` helpers to deduplicate ~80 lines of spawn boilerplate across 3 ffprobe functions. Extracted `shouldBlockRender()` so strict flag tests exercise production code. Shared `lintProject()` used by both `lint` and `render` commands. ## Context Discovered during a real composition build session where: 1. `<audio>` without `id` rendered silently (preview worked fine because runtime queries `[data-start]`, but renderer queries `[id][src]`) 2. `<video>` inside timed `<div>` froze on first frame 3. `preload="none"` caused 45s renderer timeout 4. YouTube clips with sparse keyframes from `yt-dlp --download-sections` caused audio/video desync 5. Parallel workers timed out on video-heavy compositions ## Test plan - [x] Core: 365/365 tests passing (5 new lint tests) - [x] Engine: 24/24 tests passing - [x] CLI: 14/14 tests passing (7 lintProject + 7 shouldBlockRender) - [x] Lint + format hooks pass - [ ] Manual: create a composition with `<audio data-start="0" src="test.wav">` (no id) — verify `npx hyperframes lint` catches it - [ ] Manual: run `npx hyperframes render --strict` with lint errors — verify it blocks - [ ] Manual: run `npx hyperframes render --strict-all` with lint warnings — verify it blocks
2026-09-08 10:46:06 +00:00 · 2026-03-30 11:07:19 -07:00
parent 808d196fe0
commit 229538c622
15 changed files with 7334 additions and 173 deletions
@@ -0,0 +1,169 @@
+import { describe, it, expect, afterEach } from "vitest";
+import { mkdirSync, 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;
+}
+
+function validHtml(compId = "main"): string {
+  return `<html><body>
+  <div data-composition-id="${compId}" data-width="1920" data-height="1080"></div>
+  <script>window.__timelines = window.__timelines || {}; window.__timelines["${compId}"] = gsap.timeline({ paused: true });</script>
+</body></html>`;
+}
+
+function htmlWithMissingMediaId(): string {
+  return `<html><body>
+  <div data-composition-id="main" data-width="1920" data-height="1080">
+    <audio data-start="0" data-duration="10" src="narration.wav"></audio>
+  </div>
+  <script>window.__timelines = window.__timelines || {}; window.__timelines["main"] = gsap.timeline({ paused: true });</script>
+</body></html>`;
+}
+
+function htmlWithPreloadNone(): string {
+  return `<html><body>
+  <div data-composition-id="captions" data-width="1920" data-height="1080">
+    <video id="v1" data-start="0" data-duration="10" src="clip.mp4" muted playsinline preload="none"></video>
+  </div>
+  <script>window.__timelines = window.__timelines || {}; window.__timelines["captions"] = gsap.timeline({ paused: true });</script>
+</body></html>`;
+}
+
+let dirs: string[] = [];
+
+function makeProject(indexHtml: string, subComps?: Record<string, string>): ProjectDir {
+  const dir = tmpProject("lint");
+  dirs.push(dir);
+  writeFileSync(join(dir, "index.html"), indexHtml);
+  if (subComps) {
+    const compsDir = join(dir, "compositions");
+    mkdirSync(compsDir, { recursive: true });
+    for (const [name, html] of Object.entries(subComps)) {
+      writeFileSync(join(compsDir, name), html);
+    }
+  }
+  return { dir, name: "test-project", indexPath: join(dir, "index.html") };
+}
+
+afterEach(() => {
+  for (const d of dirs) {
+    rmSync(d, { recursive: true, force: true });
+  }
+  dirs = [];
+});
+
+describe("lintProject", () => {
+  it("returns zero errors/warnings for a clean project", () => {
+    const project = makeProject(validHtml());
+    const { totalErrors, totalWarnings, results } = lintProject(project);
+
+    expect(totalErrors).toBe(0);
+    expect(totalWarnings).toBe(0);
+    expect(results).toHaveLength(1);
+    expect(results[0]!.file).toBe("index.html");
+  });
+
+  it("detects errors in index.html", () => {
+    const project = makeProject(htmlWithMissingMediaId());
+    const { totalErrors, results } = lintProject(project);
+
+    expect(totalErrors).toBeGreaterThan(0);
+    const mediaFinding = results[0]!.result.findings.find((f) => f.code === "media_missing_id");
+    expect(mediaFinding).toBeDefined();
+  });
+
+  it("lints sub-compositions in compositions/ directory", () => {
+    const project = makeProject(validHtml(), {
+      "captions.html": htmlWithMissingMediaId(),
+    });
+    const { totalErrors, results } = lintProject(project);
+
+    expect(results).toHaveLength(2);
+    expect(results[1]!.file).toBe("compositions/captions.html");
+    expect(totalErrors).toBeGreaterThan(0);
+    const subFindings = results[1]!.result.findings;
+    expect(subFindings.some((f) => f.code === "media_missing_id")).toBe(true);
+  });
+
+  it("aggregates errors across index.html and sub-compositions", () => {
+    const project = makeProject(htmlWithMissingMediaId(), {
+      "overlay.html": htmlWithMissingMediaId(),
+    });
+    const { totalErrors, results } = lintProject(project);
+
+    expect(results).toHaveLength(2);
+    // Both files have media_missing_id errors
+    const rootErrors = results[0]!.result.errorCount;
+    const subErrors = results[1]!.result.errorCount;
+    expect(totalErrors).toBe(rootErrors + subErrors);
+  });
+
+  it("aggregates warnings from sub-compositions", () => {
+    const project = makeProject(validHtml(), {
+      "captions.html": htmlWithPreloadNone(),
+    });
+    const { totalWarnings, results } = lintProject(project);
+
+    expect(results).toHaveLength(2);
+    expect(totalWarnings).toBeGreaterThan(0);
+    const preloadWarning = results[1]!.result.findings.find((f) => f.code === "media_preload_none");
+    expect(preloadWarning).toBeDefined();
+  });
+
+  it("handles project with no compositions/ directory", () => {
+    const project = makeProject(validHtml());
+    // No compositions/ dir created
+    const { results } = lintProject(project);
+
+    expect(results).toHaveLength(1);
+  });
+
+  it("ignores non-HTML files in compositions/", () => {
+    const project = makeProject(validHtml(), {
+      "captions.html": validHtml("captions"),
+    });
+    // Add a non-HTML file
+    writeFileSync(join(project.dir, "compositions", "readme.txt"), "not html");
+
+    const { results } = lintProject(project);
+
+    expect(results).toHaveLength(2); // index.html + captions.html, not readme.txt
+  });
+});
+
+describe("shouldBlockRender", () => {
+  it("default: does not block on errors", () => {
+    expect(shouldBlockRender(false, false, 5, 0)).toBe(false);
+  });
+
+  it("default: does not block on warnings", () => {
+    expect(shouldBlockRender(false, false, 0, 3)).toBe(false);
+  });
+
+  it("--strict: blocks on errors", () => {
+    expect(shouldBlockRender(true, false, 1, 0)).toBe(true);
+  });
+
+  it("--strict: does not block on warnings only", () => {
+    expect(shouldBlockRender(true, false, 0, 5)).toBe(false);
+  });
+
+  it("--strict-all: blocks on errors", () => {
+    expect(shouldBlockRender(true, true, 1, 0)).toBe(true);
+  });
+
+  it("--strict-all: blocks on warnings", () => {
+    expect(shouldBlockRender(true, true, 0, 1)).toBe(true);
+  });
+
+  it("--strict-all: does not block when clean", () => {
+    expect(shouldBlockRender(true, true, 0, 0)).toBe(false);
+  });
+});