docs(lambda): document webm support + simplify-review fixes (#953)

* docs(lambda): document webm support in distributed mode

PR 8.4 of the WebM distributed-rendering plan (v1.5 backlog #1; see
DISTRIBUTED-RENDERING-PLAN.md §7.2). User-facing docs catch up with the
shipped capability.

Updates docs/deploy/migrating-to-hyperframes-lambda.mdx:

- "Output format" row in the migration table now lists `webm` alongside
  mp4 / mov / png-sequence with a note that webm uses libvpx-vp9 +
  closed-GOP concat-copy. HDR mp4 remains the only refused format.

- "No webm distributed" caveat replaced with "webm uses closed-GOP VP9"
  explainer covering the encoder args (`-g <chunkSize>`,
  `-keyint_min <chunkSize>`, `-auto-alt-ref 0`, `-cpu-used 2`), why
  alt-ref disable is load-bearing, and that the output preserves alpha
  via yuva420p with Opus audio.

- Migration checklist no longer asks adopters to filter out webm
  compositions; only HDR-dependent renders need to stay on the previous
  framework.

aws-lambda.mdx doesn't currently call out webm as unsupported (only HDR
in the v1 surface list), so it gets no copy edits beyond the migration
guide.

The internal planning doc (DISTRIBUTED-RENDERING-PLAN.md §7.2, §8,
§12 — kept outside the repo) gets matching updates: format support
matrix flipped ✓, v1.5 backlog #1 marked shipped, HDR promoted to the
new top item, and the rev-12 → rev-13 status line.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* refactor: address simplify-review findings on webm stack

Folds in cleanups identified by a multi-agent code-review pass over the
4-PR webm-distributed stack:

- plan.ts: `resolveEncoderTriple()` webm case now calls
  `getEncoderPreset(quality, "webm")` for its preset string instead of
  hardcoding "good". The hardcode was wrong for `quality: "draft"`
  (`getEncoderPreset` returns "realtime" for that tier) — would have
  silently overridden the draft → realtime mapping for distributed webm
  renders.
- chunkEncoder.ts: trim the new VP9 closed-GOP comment block from ~18
  lines of WHY narration down to the 6 lines that actually explain why
  (alt-ref + cpu-used drift). Match the alpha branch's idempotent-push
  comment to the same standard.
- chunkEncoder.test.ts: drop the duplicate WHY comment that restated
  the implementation comment in plain words.
- webm-concat-copy.test.ts: rewrite the file-header docstring to
  describe the contract being tested instead of the PR-8.1-gating
  history; strip "PR 8.2 / Path A / Path B" references from error
  messages (they belong in PR bodies, not in test output). Consolidate
  the yuva420p alpha smoke into a single `it()` block (was a full
  4-test describe with duplicated setup) — the yuv420p block already
  covers the probe/decode/frame-count contract; the alpha smoke only
  needs to prove the alpha args don't break concat-copy.
- plan.test.ts: drop the "PR 8.1 proved the contract" comment.
- webm-vp9 fixture: drop the aspirational "Other webm-with-audio
  fixtures cover the mux path separately when added" sentence (no
  other fixtures exist). Regenerated the baseline via
  `docker:test:update webm-vp9` to reflect the updated comment.
- migrating-to-hyperframes-lambda.mdx: add a paragraph about
  distributed webm's perf cost — ~10-25% larger files at constant CRF
  due to forced keyframes, and slower per-chunk encode due to
  `-cpu-used 2` being more conservative than the libvpx default.

All unit tests + the webm-vp9 distributed-simulated regression still
pass after these changes.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(cli): accept --format=webm in `hyperframes lambda render`

The CLI's `lambda render` subcommand's FORMATS allowlist and the
`RenderArgs.format` type still narrowed to `mp4 | mov | png-sequence`,
so even though the producer + aws-lambda packages now support webm
end-to-end, the CLI surface rejected it with `--format must be mp4|mov|
png-sequence`. Add webm to both spots and update the --help description.

Surfaced during real-AWS deploy prep — the local lambda-local /
distributed-simulated tests didn't go through the CLI so the gap went
unnoticed.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(producer): font cache writes to /tmp on Lambda (read-only \$HOME)

The deterministic Google Fonts cache was rooted at
`\$HOME/.cache/hyperframes/fonts`, which fails on AWS Lambda — the
runtime's `\$HOME` resolves to a `/home/sbx_*` directory tree that's
read-only. `mkdirSync(..., { recursive: true })` can't create that
path and the plan stage trips with `ENOENT: no such file or directory,
mkdir '/home/sbx_user1051/.cache/hyperframes/fonts/space-mono'` on
every Lambda render that pulls a Google Font (i.e. every distributed
fixture using `@import url("https://fonts.googleapis.com/...")`).

Detect Lambda via `\$AWS_LAMBDA_FUNCTION_NAME` and route the cache to
`tmpdir()/hyperframes/fonts` in that case. Lambda's `/tmp` survives
across invocations on a warm container, so cache hit rate is the same
as non-Lambda runs. Also honor an explicit
`\$HYPERFRAMES_FONT_CACHE_DIR` override for adopters who want a
different location regardless of the runtime.

Surfaced while verifying webm distributed end-to-end on real AWS — the
same bug affects mp4 fixtures using Google Fonts; webm just happened to
be the one I tried first.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* refactor: extract DistributedFormat type + trim font-cache resolver

Second simplify-review pass on the webm stack flagged two cleanups:

1. **`DistributedFormat` type duplicated 10 times.** Every file in the
   distributed pipeline carried its own copy of
   `"mp4" | "mov" | "png-sequence" | "webm"` — adding a new format
   meant a 10-place edit with no compile-time guarantee they stayed in
   sync. Extract a single source of truth in
   `packages/producer/src/services/distributed/shared.ts`, re-export
   from `@hyperframes/producer/distributed` and
   `@hyperframes/aws-lambda/sdk`, and have all callers pull from
   there. The aws-lambda `ALLOWED_FORMATS` runtime tuple and the CLI's
   `FORMATS` tuple now both use `satisfies readonly DistributedFormat[]`
   so the compiler enforces the runtime allowlist stays in sync with
   the type.

2. **`deterministicFonts.ts` font-cache resolver was over-commented.**
   Trim the 7-line block to 4 lines (drop the aspirational
   "and other read-only-FS execution environments" — only Lambda is
   detected — and the warm-container `/tmp` persistence narration —
   anyone reading already knows Lambda /tmp semantics). Collapse the
   two-step `if (explicit && explicit.length > 0)` into a single
   nullish-coalesce expression now that the empty-string defensive
   check is gone (`process.env.X` is `string | undefined`, no third
   shape to guard against).

Out-of-scope skips (called out by the agents, deferred):
- In-process `RenderConfig.format` and the in-process CLI's
  `render.ts` format union still carry their own inline copies. The
  union happens to coincide today but they're separate concerns —
  leaving them alone limits this PR's blast radius.
- `fontCacheDir(slug)` / `resolveFontCacheRoot()` naming asymmetry
  flagged as taste; skipping.
- Pre-existing redundant `existsSync` before `mkdirSync({ recursive:
  true })` in `fontCacheDir` — out of scope.

All tests + typecheck still pass. Lambda render still works
end-to-end (no functional changes).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs(lambda): drop plan-doc reference from migration checklist

PR review feedback: source/docs should not mention the
distributed-rendering planning doc. Tighten the migration checklist
sentence to describe the webm path directly rather than referencing
the doc's version label.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* refactor(producer): split resolveEncoderTriple into mp4 + non-mp4 helpers

CI Fallow audit on PR #953 flagged `resolveEncoderTriple` at CRAP 31.6 —
the function interleaved (a) mp4 codec validation + dispatch, (b) the
non-mp4 codec-rejection throw, and (c) per-format dispatch. Splitting
into `resolveMp4EncoderTriple` + `resolveNonMp4EncoderTriple` drops the
top-level function's cyclomatic complexity below the threshold while
preserving every error message and code path. Behavior unchanged.

Also extracts an `EncoderTriple` type alias so the three functions
share the return shape declaratively rather than repeating it.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: jrusso1020

docs/deploy/migrating-to-hyperframes-lambda.mdx

@@ -42,7 +42,7 @@ Most adopters' render config maps directly:
 | `fps` | `--fps=30` (CLI) or `config.fps` (SDK) | 24, 30, 60 only — non-integer NTSC rationals are an in-process-only feature. |
 | `width` / `height` | `--width` / `--height` flags, or `config.width` / `config.height` | Even integers ≤ 7680 (yuv420p parity). |
 | `codec: 'h264' / 'h265'` | `--codec=h264` or `--codec=h265` (mp4 only) | h265 uses libx265 with closed-GOP keyint params so chunked concat-copy round-trips losslessly. |
-| Output format | `--format=mp4 / mov / png-sequence` | Distributed mode refuses webm + HDR at plan time. |
+| Output format | `--format=mp4 / mov / webm / png-sequence` | webm uses libvpx-vp9 + closed-GOP concat-copy. Distributed mode still refuses HDR mp4 at plan time. |
 | Quality preset | `--quality=draft / standard / high` | Maps onto ffmpeg encoder presets. |
 | Chunk size in frames | `--chunk-size=240` (default 240) | ~8s at 30 fps; sized to fit Lambda's 15-min cap with headroom. |
 | Max parallel chunks | `--max-parallel-chunks=16` (default 16) | Caps the Map state's fan-out. |
@@ -64,9 +64,11 @@ HyperFrames refuses `data-gpu-mode="hardware"` in distributed mode — hardware
 
 `hdrMode: 'force-hdr'` is rejected at plan time. The v1.5 backlog covers HDR mp4 via `-bsf:v hevc_metadata` re-application; for now, HDR renders use the in-process renderer outside Lambda.
 
-### No webm distributed
+### webm uses closed-GOP VP9
 
-VP9 in matroska doesn't round-trip cleanly through concat-copy (the moov-atom keyframe assumptions don't hold). webm renders use the in-process renderer or accept a controlled re-encode at the assemble stage — coming in v1.5. The Lambda handler refuses webm with `FORMAT_NOT_SUPPORTED_IN_DISTRIBUTED` so the failure is loud.
+webm distributed renders go through libvpx-vp9 with `-g <chunkSize>`, `-keyint_min <chunkSize>`, `-auto-alt-ref 0`, and `-cpu-used 2`. The alt-ref disable is the load-bearing bit: libvpx-vp9's default non-displayable alt-ref frames can land anywhere in a GOP, which breaks concat-copy at chunk seams. Closed-GOP forces a keyframe at every chunk boundary so `ffmpeg -f concat -c copy` round-trips losslessly. Output is `yuva420p` to preserve alpha. Audio is muxed as Opus.
+
+Distributed webm files are typically ~10-25% larger than the same composition rendered in-process at the same CRF, because closed-GOP forces more keyframes than the in-process single-pass would emit. Per-chunk encode is also slower than libvpx-vp9's default speed/quality tradeoff (`-cpu-used 2` is more conservative than the default for `-deadline good`). The single-machine in-process renderer remains the right choice for short webm renders; distributed pays for itself once a render's wall-clock exceeds what one machine delivers.
 
 ### State files are local by default
 
@@ -78,7 +80,7 @@ The default policy doc emitted by `hyperframes lambda policies user/role` uses `
 
 ## Migration checklist
 
-1. **Inventory** the compositions you want to migrate. Filter out anything that needs HDR or webm — those stay on your current framework for now.
+1. **Inventory** the compositions you want to migrate. Filter out anything that needs HDR — that stays on your current framework for now. webm renders distributed via closed-GOP VP9 + concat-copy (see the webm section above).
 2. **Translate** each composition to plain HTML. The `[Concepts](/concepts)` page covers the data-attribute conventions; the `/hyperframes` skill (`npx skills add heygen-com/hyperframes`) makes Claude / Cursor / Codex aware of them too.
 3. **Wire** the new composition into your build pipeline alongside the old one. HyperFrames doesn't need an external bundler — you can `npx hyperframes preview` against the HTML directly.
 4. **Deploy** in a separate AWS account or with a `--stack-name=hyperframes-staging` first. Run a real render with `--wait`; verify the output bytes.

packages/aws-lambda/src/events.ts

@@ -16,7 +16,7 @@
  * results per §2.4).
  */
 
-import type { DistributedRenderConfig } from "@hyperframes/producer/distributed";
+import type { DistributedFormat, DistributedRenderConfig } from "@hyperframes/producer/distributed";
 
 /** Discriminator for the three roles the one Lambda image fulfills. */
 export type LambdaAction = "plan" | "renderChunk" | "assemble";
@@ -65,7 +65,7 @@ export interface RenderChunkEvent {
   /** S3 URI prefix where the chunk output should be uploaded (`s3://bucket/{prefix}/`). */
   ChunkOutputS3Prefix: string;
   /** Output container format from the plan's encoder.json; drives file vs frame-dir handling. */
-  Format: "mp4" | "mov" | "png-sequence" | "webm";
+  Format: DistributedFormat;
 }
 
 /** Activity C: fetch planDir + all chunks + audio, assemble, upload final. */
@@ -80,7 +80,7 @@ export interface AssembleEvent {
   /** Final output S3 URI (`s3://bucket/key.mp4`). */
   OutputS3Uri: string;
   /** Output container format; drives file vs frame-dir handling. */
-  Format: "mp4" | "mov" | "png-sequence" | "webm";
+  Format: DistributedFormat;
 }
 
 /**
@@ -106,7 +106,7 @@ export interface PlanLambdaResult {
   Fps: 24 | 30 | 60;
   Width: number;
   Height: number;
-  Format: "mp4" | "mov" | "png-sequence" | "webm";
+  Format: DistributedFormat;
   HasAudio: boolean;
   AudioS3Uri: string | null;
   FfmpegVersion: string;

packages/aws-lambda/src/formatExtension.ts

@@ -6,7 +6,9 @@
  * looks like vs a png-sequence.
  */
 
-export type DistributedFormat = "mp4" | "mov" | "png-sequence" | "webm";
+import type { DistributedFormat } from "@hyperframes/producer/distributed";
+
+export type { DistributedFormat } from "@hyperframes/producer/distributed";
 
 // Closed-enum lookup table. TS enforces exhaustiveness via the
 // `Record<DistributedFormat, string>` annotation — adding a format to

packages/aws-lambda/src/handler.ts

@@ -25,7 +25,7 @@ import {
   renderChunk,
 } from "@hyperframes/producer/distributed";
 import { resolveChromeExecutablePath } from "./chromium.js";
-import { formatExtension } from "./formatExtension.js";
+import { type DistributedFormat, formatExtension } from "./formatExtension.js";
 import type {
   AssembleEvent,
   AssembleLambdaResult,
@@ -433,7 +433,7 @@ async function downloadChunkObjects(
   s3: S3Client,
   uris: string[],
   workDir: string,
-  format: "mp4" | "mov" | "png-sequence" | "webm",
+  format: DistributedFormat,
 ): Promise<string[]> {
   const chunksDir = join(workDir, "chunks");
   mkdirSync(chunksDir, { recursive: true });

packages/aws-lambda/src/sdk/index.ts

@@ -24,3 +24,4 @@ export {
 } from "./costAccounting.js";
 export { InvalidConfigError, validateDistributedRenderConfig } from "./validateConfig.js";
 export type { SerializableDistributedRenderConfig } from "../events.js";
+export type { DistributedFormat } from "../formatExtension.js";

packages/aws-lambda/src/sdk/validateConfig.ts

@@ -18,6 +18,7 @@
  * size cap, GPU mode at runtime) needs the actual planner.
  */
 
+import type { DistributedFormat } from "../formatExtension.js";
 import type { SerializableDistributedRenderConfig } from "../events.js";
 
 /** Thrown for any client-side `SerializableDistributedRenderConfig` violation. */
@@ -32,7 +33,12 @@ export class InvalidConfigError extends Error {
 }
 
 const ALLOWED_FPS = [24, 30, 60] as const;
-const ALLOWED_FORMATS = ["mp4", "mov", "png-sequence", "webm"] as const;
+const ALLOWED_FORMATS = [
+  "mp4",
+  "mov",
+  "png-sequence",
+  "webm",
+] as const satisfies readonly DistributedFormat[];
 const ALLOWED_CODECS = ["h264", "h265"] as const;
 const ALLOWED_QUALITIES = ["draft", "standard", "high"] as const;
 const ALLOWED_RUNTIME_CAPS = ["lambda", "temporal", "cloud-run-job", "k8s-job", "none"] as const;

packages/cli/src/commands/lambda.ts

@@ -9,6 +9,7 @@
  */
 
 import { defineCommand } from "citty";
+import type { DistributedFormat } from "@hyperframes/aws-lambda/sdk";
 import type { Example } from "./_examples.js";
 import { c } from "../ui/colors.js";
 
@@ -100,7 +101,7 @@ export default defineCommand({
     width: { type: "string", description: "Render width in pixels" },
     height: { type: "string", description: "Render height in pixels" },
     fps: { type: "string", description: "Render fps (24 | 30 | 60)" },
-    format: { type: "string", description: "mp4 | mov | png-sequence (default: mp4)" },
+    format: { type: "string", description: "mp4 | mov | png-sequence | webm (default: mp4)" },
     codec: { type: "string", description: "h264 | h265 (mp4 only)" },
     quality: { type: "string", description: "draft | standard | high" },
     "chunk-size": { type: "string", description: "Frames per chunk (default: 240)" },
@@ -325,7 +326,12 @@ function parseEnum<T extends string>(
   throw new Error(`${errorPrefix} must be ${allowed.join("|")}; got ${s}`);
 }
 
-const FORMATS = ["mp4", "mov", "png-sequence"] as const;
+const FORMATS = [
+  "mp4",
+  "mov",
+  "png-sequence",
+  "webm",
+] as const satisfies readonly DistributedFormat[];
 const CODECS = ["h264", "h265"] as const;
 const QUALITIES = ["draft", "standard", "high"] as const;
 const CHROME_SOURCES = ["sparticuz", "chrome-headless-shell"] as const;

packages/cli/src/commands/lambda/render.ts

@@ -5,7 +5,10 @@
  */
 
 import { resolve as resolvePath } from "node:path";
-import type { SerializableDistributedRenderConfig } from "@hyperframes/aws-lambda/sdk";
+import type {
+  DistributedFormat,
+  SerializableDistributedRenderConfig,
+} from "@hyperframes/aws-lambda/sdk";
 import { c } from "../../ui/colors.js";
 import { requireStack, stateFilePath } from "./state.js";
 
@@ -23,7 +26,7 @@ export interface RenderArgs {
   fps: 24 | 30 | 60;
   width: number;
   height: number;
-  format: "mp4" | "mov" | "png-sequence";
+  format: DistributedFormat;
   codec?: "h264" | "h265";
   quality?: "draft" | "standard" | "high";
   chunkSize?: number;

packages/engine/src/services/chunkEncoder.test.ts

@@ -551,10 +551,6 @@ describe("buildEncoderArgs lockGopForChunkConcat", () => {
     expect(args.indexOf("-x264-params")).toBe(-1);
   });
 
-  // Closed-GOP for libvpx-vp9 is required to make `ffmpeg -f concat -c copy`
-  // stitch VP9 chunks losslessly: every chunk's first frame must be an
-  // independently-decodable keyframe with no alt-ref references reaching
-  // back across the seam.
   it("true appends closed-GOP args for libvpx-vp9", () => {
     const args = buildEncoderArgs(
       {
@@ -570,16 +566,9 @@ describe("buildEncoderArgs lockGopForChunkConcat", () => {
     );
     expect(args[args.indexOf("-g") + 1]).toBe("240");
     expect(args[args.indexOf("-keyint_min") + 1]).toBe("240");
-    // Alt-ref frames are non-displayable references that break concat-copy
-    // at chunk seams; closed-GOP must disable them.
     expect(args[args.indexOf("-auto-alt-ref") + 1]).toBe("0");
-    // cpu-used is locked so workers with different libvpx-vp9 defaults
-    // produce visually consistent output across chunk boundaries.
     expect(args[args.indexOf("-cpu-used") + 1]).toBe("2");
-    // libvpx-vp9 uses `-deadline good` for non-ultrafast presets — the
-    // closed-GOP path doesn't change that.
     expect(args[args.indexOf("-deadline") + 1]).toBe("good");
-    // x264/x265-only params must not leak into the VP9 branch.
     expect(args.indexOf("-x264-params")).toBe(-1);
     expect(args.indexOf("-x265-params")).toBe(-1);
     expect(args.indexOf("-sc_threshold")).toBe(-1);

packages/engine/src/services/chunkEncoder.ts

@@ -255,25 +255,13 @@ export function buildEncoderArgs(
     args.push("-deadline", preset === "ultrafast" ? "realtime" : "good");
     args.push("-row-mt", "1");
 
-    // Closed-GOP args for distributed chunk concat-copy. Mirrors the
-    // libx264/libx265 branch above: `lockGopForChunkConcat=true` lays a
-    // keyframe at every chunk boundary so `ffmpeg -f concat -c copy` can
-    // stitch sibling chunks losslessly.
-    //
-    // VP9-specific: `-auto-alt-ref 0` is mandatory. Alt-ref (a.k.a.
-    // "ARNR") frames are non-displayable references libvpx-vp9 inserts
-    // anywhere in the GOP for compression; they break concat-copy at
-    // chunk seams because the boundary frame is no longer the first
-    // displayable reference. The alpha branch below already disables
-    // alt-ref for an unrelated reason (alpha + alt-ref is unsupported);
-    // closed-GOP extends that to every pixel format.
-    //
-    // `-cpu-used 2` pins the libvpx-vp9 speed/quality tradeoff so chunks
-    // encoded on workers with different default cpu-used values still
-    // produce visually consistent output across seams. libvpx-vp9's
-    // default with `-deadline good` has drifted across versions
-    // historically — locking it makes the planHash round-trip
-    // deterministic.
+    // `-auto-alt-ref 0` is mandatory for chunk concat-copy: libvpx-vp9's
+    // alt-ref frames can reference frames in either direction inside a
+    // GOP, so a chunk-boundary frame is not guaranteed to be the first
+    // displayable reference when alt-ref is on. `-cpu-used 2` pins the
+    // speed/quality tradeoff against libvpx-vp9 default drift across
+    // versions, so the planHash round-trips deterministically across
+    // worker images.
     const lockGopVp9 = options.lockGopForChunkConcat === true;
     if (lockGopVp9) {
       if (
@@ -299,10 +287,8 @@ export function buildEncoderArgs(
     }
     if (pixelFormat === "yuva420p") {
       // Alpha + alt-ref is unsupported by libvpx-vp9. The closed-GOP
-      // branch above already disables alt-ref; only push the flag for
-      // the non-locked alpha case to keep the args list clean (a second
-      // `-auto-alt-ref 0` is harmless but noisier in `ffmpeg -loglevel`
-      // diagnostics).
+      // branch above already emits `-auto-alt-ref 0`, so skip the
+      // duplicate push.
       if (!lockGopVp9) {
         args.push("-auto-alt-ref", "0");
       }