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

[jrusso1020]

Description

PR 4 of 4 in the WebM distributed-rendering series. Originally
docs-only; expanded to fold in simplify-review findings + two bugs
uncovered while verifying webm distributed end-to-end against a real
AWS Lambda stack.

Real-AWS verification

Deployed hyperframes-webm-test stack to us-east-1, ran a webm
render through the full plan → renderChunk × 4 → assemble pipeline on
real Lambda, and verified the output:

Check	Result
Render status	SUCCESS (after fixing the font-cache bug below)
Output	109 KB webm
Codec / dims / pix_fmt	VP9 / 640×360 / yuv420p + ALPHA_MODE=1 tag
Frame count	60 (= 4 chunks × 15 frames, no seam loss)
Duration	2.000s exact
ffmpeg -f null - decode	clean
PSNR vs local baseline	58–63 dB across all 60 frames
Lambda render cost	$0.0002

Stack + S3 bucket torn down cleanly post-verification.

Commits

• docs(lambda): document webm support in distributed mode —
  updates docs/deploy/migrating-to-hyperframes-lambda.mdx: format
  table now lists webm, "No webm distributed" caveat replaced with
  "webm uses closed-GOP VP9" explainer, migration checklist no longer
  filters out webm.

• refactor: address simplify-review findings on webm stack —
  bundle of cleanups identified by a multi-agent code-review pass:

  • Fix plan.ts resolveEncoderTriple() webm preset hardcode (was
    wrong for quality: "draft").
  • Trim WHAT-not-WHY narration in chunkEncoder.ts and its mirror
    in chunkEncoder.test.ts.
  • Strip stale narrative references from source — those belong in
    PR bodies, not in test output or source comments.
  • Consolidate smoke test yuva420p describe from a 4-test block with
    duplicated setup into a single focused it() block.
  • Drop aspirational comment in the webm-vp9 fixture; baseline
    regenerated.
  • Document distributed webm's perf cost (10-25% larger files at
    constant CRF, slower per-chunk encode) in the migration doc.

• fix(cli): accept --format=webm in hyperframes lambda render —
  surfaced during real-AWS deploy prep. The CLI's lambda render
  FORMATS allowlist and RenderArgs.format type still narrowed to
  mp4 | mov | png-sequence.

• fix(producer): font cache writes to /tmp on Lambda — surfaced
  by the first real-AWS render attempt failing at plan stage with
  ENOENT: no such file or directory, mkdir '/home/sbx_user1051/.cache/hyperframes/fonts/space-mono'. The
  deterministic Google Fonts cache was rooted at $HOME/.cache/...,
  which fails on Lambda — $HOME resolves to /home/sbx_* which is
  read-only. Not webm-specific: this bug affected every existing
  distributed fixture using Google Fonts. Fix detects Lambda via
  $AWS_LAMBDA_FUNCTION_NAME and routes to tmpdir()/hyperframes/fonts.

• refactor: extract DistributedFormat type + trim font-cache resolver
  — second simplify-review pass identified that the
  "mp4" | "mov" | "png-sequence" | "webm" union was duplicated
  12+ times across producer, aws-lambda, CLI, and the harness.
  Extracted to a single source of truth in
  packages/producer/src/services/distributed/shared.ts and
  re-exported through @hyperframes/producer/distributed and
  @hyperframes/aws-lambda/sdk. The runtime ALLOWED_FORMATS tuple
  and CLI FORMATS tuple now use as const satisfies readonly DistributedFormat[] so the compiler enforces tuple ↔ type sync.
  Also trimmed the over-commented font-cache resolver and collapsed
  the empty-string defensive check into a nullish-coalesce.

• docs(lambda): drop plan-doc reference from migration checklist
  — review feedback: source/docs should not reference the internal
  planning doc. Tightened the migration checklist sentence to
  describe the webm path directly.

Testing

Local:

• bunx vitest run --root packages/engine src/services/chunkEncoder.test.ts — passes
• bun test packages/producer/tests/distributed/_smoke/webm-concat-copy.test.ts — passes (now with real alpha checks)
• bun test packages/producer/src/services/distributed/planFormatBanlist.test.ts — passes
• docker:test webm-vp9 (in-process) — passes
• docker:test --mode=distributed-simulated for all 5 distributed fixtures (mp4-h264-sdr, mp4-h265-sdr, mov-prores, png-sequence, webm-vp9) — 5/5 pass

Real AWS:

• hyperframes lambda deploy --stack-name=hyperframes-webm-test --region=us-east-1 --concurrency=4 — stack created
• hyperframes lambda render webm-vp9 --format=webm --chunk-size=15 --max-parallel-chunks=4 --wait — succeeded, PSNR 58–63 dB vs local baseline
• hyperframes lambda destroy + S3 cleanup — stack and bucket fully reclaimed

🤖 Generated with Claude Code

[jrusso1020]

• docs(lambda): document webm support + simplify-review fixes #953 👈 (View in Graphite)
• test(producer): add webm-vp9 distributed regression fixture #952
• feat(producer): enable webm in distributed mode via concat-copy #951
• feat(engine): closed-GOP VP9 encoder args + concat-copy smoke test #950
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[miguel-heygen]

APPROVE — clean stack-finisher with real bug fixes.

Verified:

• resolveEncoderTriple preset fix: previously hardcoded preset: "good" for webm, silently overriding quality: "draft" mapping. Now delegates to getEncoderPreset so draft actually gets -deadline realtime. Genuine correctness fix.
• Lambda font cache fix: $HOME/.cache/hyperframes/fonts is read-only on Lambda (/home/sbx_*). Routes to tmpdir() when $AWS_LAMBDA_FUNCTION_NAME is set. Supports $HYPERFRAMES_FONT_CACHE_DIR override. Not webm-specific — affects all distributed renders with Google Fonts.
• DistributedFormat consolidation: single source of truth in shared.ts, replaces 12+ inline union literals. satisfies readonly DistributedFormat[] ensures compile-time alignment.
• CLI format allowlist: lambda render now accepts webm (was hardcoded to mp4/mov/png-sequence).
• Docs: format table, migration checklist, perf tradeoffs (10-25% larger) all accurate.
• Test cleanup: 4-block yuva420p smoke consolidated to single it() with try/finally. PR-track narrative removed from source.
• Net -48 lines (235 added, 283 removed) — genuine simplification.

All CI green.

[vanceingalls]

Docs + cleanup PR closes out the webm-distributed series cleanly. The DistributedFormat type centralization, the resolveEncoderTriple correctness fix, and the Lambda font-cache routing are all good. Doc claims cross-reference cleanly to the code.

Strengths

• Single source of truth for the format union — packages/producer/src/services/distributed/shared.ts:21 defines DistributedFormat and the lambda + CLI + harness + planHash + plan/renderChunk/assemble all derive from it. The as const satisfies readonly DistributedFormat[] pattern at validateConfig.ts:35 and lambda.ts:328 is exactly right — the runtime allowlist is provably aligned with the compile-time union, so a future format add starts at one type definition and the TS compiler enumerates every callsite that needs updating.
• resolveEncoderTriple bug fix is a real correctness improvement. Before, the webm branch returned preset: "good" unconditionally; that silently overrode getEncoderPreset's draft-tier mapping to -deadline realtime. Now plan.ts:559-568 defers to the engine helper, and getEncoderPreset("draft", "webm") at chunkEncoder.ts:50-56 correctly returns realtime. The inline comment captures the "why hardcoding was wrong" in one paragraph.
• Font-cache fix is environment-correct. AWS_LAMBDA_FUNCTION_NAME is set by the Lambda runtime before module init, so the module-level GOOGLE_FONTS_CACHE_DIR const at deterministicFonts.ts:345 resolves to tmpdir()/hyperframes/fonts on Lambda. HYPERFRAMES_FONT_CACHE_DIR as an explicit override is good defensive design for adopters running in other write-restricted environments.
• Doc claims verified against code. VP9 closed-GOP args (-g, -keyint_min, -auto-alt-ref 0, -cpu-used 2) match chunkEncoder.ts:265-280. "Audio is muxed as Opus" matches chunkEncoder.ts:541 (libopus, 128k). The cost-transparency paragraph (10-25% file-size penalty + -cpu-used 2 slowdown vs. in-process default) is exactly the kind of trade-off info adopters need to know before migrating short webm renders — surfacing the cost up front beats a wiki page nobody reads.

Findings

nit — webm-with-audio coverage gap. The doc states "Audio is muxed as Opus" (migrating-to-hyperframes-lambda.mdx:71), and the engine path exists at chunkEncoder.ts:541. But the webm-vp9 fixture explicitly omits audio (tests/distributed/webm-vp9/src/index.html:93-95) and the trimmed comment now drops the "Other webm-with-audio fixtures cover the mux path separately when added" note. That removes the only in-tree breadcrumb that the audio path is uncovered by distributed-mode regression. Not a blocker — the engine-level mux is exercised by other tests — but a one-line // TODO: distributed webm-with-audio fixture in the fixture comment would let future contributors find the gap without grepping. (Or a follow-up ticket.)

nit — formatExtension.ts re-export shape. Lines 9-11 import then re-export the same type from the same package. export type { DistributedFormat } from "@hyperframes/producer/distributed" alone would do it; the local import type is dead unless something inside the file uses it. (Doesn't — formatExtension(format: DistributedFormat) resolves through the re-export.) Cosmetic.

nit — stacked-PR CI gap. baseRefName is test/producer-webm-vp9-distributed-fixture, so the main CI workflow's branches: [main] trigger filter means Test / Typecheck / Build / CLI smoke did NOT run on this head SHA. Author's PR body lists local bunx vitest + bun test + docker:test passes, which is fine, but they aren't CI-verified on this commit. The three workflows that DID run (regression, preview-regression, Player perf) all pass. Per the stack plan, this closes once #952 lands and #953 rebases onto main. Flagging per discipline; not a blocker since this PR's diff is dominated by type-alias substitution + docs + doc-comment trims, all of which are visually verifiable in review.

CI

Verbatim status: regression SUCCESS (8 shards + parent), preview-regression SUCCESS, Player perf SUCCESS, Preflight SUCCESS on regression+preview-regression workflows. Graphite / mergeability_check IN_PROGRESS (non-blocking). Mintlify Deployment SKIPPED. WIP SUCCESS. No failures. Missing from rollup (stacked-PR gap): Build, Typecheck, Test, CLI smoke.

Verdict

Verdict: APPROVE
Reasoning: Doc claims cross-reference cleanly to the code; the bundled bug fixes (encoder-preset hardcode, font-cache write path, CLI format allowlist) are real correctness improvements that the real-AWS verification caught. The type consolidation reduces format-add blast radius from ~10 callsites to 1. Findings are nits — none block merge.

— Vai

[jrusso1020]

Thanks for the careful read both of you.

• webm-with-audio coverage TODO breadcrumb (Vai, nit) — noted; declining a TODO comment on the fixture (we have a follow-up ticket for distributed webm-with-audio coverage; in-tree TODOs tend to outlive the work). Will track externally.
• formatExtension.ts re-export shape (Vai, nit) — verified: dropping the local import type produces TS2304 because export type { ... } from "..." doesn't bring the symbol into the module's local scope for use in function signatures. Both lines are load-bearing; leaving as-is.
• Stacked-PR CI gap (Vai, process note) — noted; will resolve when feat(engine): closed-GOP VP9 encoder args + concat-copy smoke test #950 merges and the rest restack onto main.

[vanceingalls]

Re-review against head a338ebaa (prior approve was on 9ded0e69).

What changed since prior approve

One new commit on this PR's branch: a338ebaa docs(lambda): drop plan-doc reference from migration checklist. The PR's base (test/producer-webm-vp9-distributed-fixture) also advanced via a rebase pulling in main's recent merges (#944, #947, #956, #948, #949, #954) but those land through the parent stack, not this PR.

The only diff this PR introduces vs. prior approve:

-1. **Inventory** the compositions you want to migrate. ... webm renders distributed-mode under v1.5 via closed-GOP VP9.
+1. **Inventory** the compositions you want to migrate. ... webm renders distributed via closed-GOP VP9 + concat-copy (see the webm section above).

Tightening the migration checklist sentence to point at the doc's own webm section rather than the version label. No code touched, no regression surface. Good edit.

Prior nits status

• webm-with-audio coverage gap — not addressed. Cosmetic; the engine-level mux path is still exercised by other tests. Not worth holding the PR.
• formatExtension.ts re-export shape — not addressed. The import type { DistributedFormat } at line 9 is still dead (file's only consumer is the re-export on line 11). Cosmetic.
• Stacked-PR CI gap — unchanged. baseRefName is still test/producer-webm-vp9-distributed-fixture, so Build/Typecheck/Test/CLI smoke from the main CI workflow still don't run on this head SHA (the workflow's branches: [main] filter excludes it). Will resolve once the parent PR (#952) lands and this rebases onto main.

None of these are blockers; all three were nits in the prior review and remain nits.

CI

At time of re-review: Preflight PASS, preview-regression PASS, player-perf PASS, Preview parity PASS, regression-shards (all 8 shards) PENDING (running on the new head). Graphite / mergeability_check pending (non-blocking). No failures. Same stacked-PR gap as before.

Verdict

Verdict: APPROVE
Reasoning: Single new commit is a doc-only tightening that addresses upstream review feedback cleanly. No new code surface, no regression risk. Prior nits remain cosmetic. Stacked-PR CI gap resolves on rebase to main.

Review by Vai (re-review)

[vanceingalls]

Round 3 re-review.

Delta since round 2 approval at a338eba: the tip commit's patch on docs/deploy/migrating-to-hyperframes-lambda.mdx is byte-identical (verified via gh api .../commits/<sha> .files[].patch on both SHAs). The new HEAD f5fbae58 differs only because Graphite restacked the parent chain underneath — the trailing 12 commits in compare/a338eba...f5fbae58 are previously-reviewed stack commits whose parent pointers got rewritten, not new content on this PR.

No new functional changes to evaluate. Round 2 verdict carries.

Verdict: APPROVE
Reasoning: Tip patch byte-identical; restack-only delta; re-stamping per the branch-protection rule that invalidates prior approval on SHA change.

Review by Vai (re-review round 3)

[vanceingalls]

Re-stamp at ff7f9767 — restacked. Prior approve (f5fbae5) still applies content-wise; this is the post-restack head. No new substantive changes.

Re-review by Vai (post-restack re-stamp)

The base branch was changed.

[miguel-heygen]

Re-approving at f2c22be — same 6 commits cherry-picked onto fresh main after #951/#952 squash-merges. No content changes from last APPROVE at ff7f976.

[vanceingalls]

Re-stamp at f2c22be0 after force-push rebase post-#952 merge. Same content as ff7f9767 (6 PR #953-specific commits cherry-picked cleanly onto fresh main). No new substantive changes; all prior round-3 nits unchanged.

Re-stamp by Vai (post-rebase)

[miguel-heygen]

Re-approving at 1cb7ef3 — resolveEncoderTriple split into resolveMp4EncoderTriple + resolveNonMp4EncoderTriple to clear fallow CRAP threshold. Behavior unchanged, clean decomposition.

[vanceingalls]

Re-stamp at 1cb7ef3d — pure refactor split of resolveEncoderTriple → resolveMp4EncoderTriple + resolveNonMp4EncoderTriple to clear fallow's CRAP 31.6 finding. Single-file diff (+34/-21 in plan.ts); behavior-preserving per the PR body. Same content end-state as prior approves; same review verdict applies.

CI still in_progress on this head (Build/Typecheck/Test/CLI smoke/regression-shards/Windows pending) but were all green on the prior head and the diff is pure-refactor.

Re-stamp by Vai (post-refactor)