fix(cli): support arm64 hosts for --docker render (#1196)

* fix(cli): support arm64 hosts for `--docker` render

The Docker render path pinned `--platform linux/amd64` for both build
and run, which on Apple Silicon / Graviton forced qemu emulation of
chrome-headless-shell. The emulated chrome process either SEGV'd or
hung on page navigation, producing the failures reported in #1193 /
#1194 / #1195.

Derive the platform from `process.arch` instead. On arm64 hosts:

- The image builds natively (no qemu).
- The Dockerfile skips the chrome-headless-shell install because
  Chrome for Testing only publishes a `linux64` build (verified
  against the known-good-versions manifest).
- The wrapper script leaves `PRODUCER_HEADLESS_SHELL_PATH` unset
  when no headless-shell binary is present, so the engine falls
  back to the system chromium that the Dockerfile already
  installs from apt and points at via `PUPPETEER_EXECUTABLE_PATH`.

`TARGETARCH` is forwarded as an explicit `--build-arg` instead of
relying on BuildKit's automatic platform args — the legacy
builder (and some BuildKit configs, including colima on macOS)
leaves it unset, which would silently bypass the arch conditional
in the Dockerfile.

Image tags are now suffixed with `-arm64` on arm64 hosts so amd64
and arm64 images of the same hyperframes version can coexist in
the local cache.

The arm64 path renders correctly but loses byte-for-byte parity
with amd64 (system chromium uses screenshot capture, not
HeadlessExperimental.beginFrame). The CLI prints a one-line
warning so users comparing against amd64 baselines know.

Verified on macOS 26.5 / M4 Max:

- Before: `qemu: unknown option 'type=gpu-process'` followed by a
  chrome-headless-shell SIGSEGV after ~4 minutes.
- After: 300/300 frames captured in ~18s of render time (1m18s
  wallclock including a one-time image build), MP4 produced.

Closes #1193
Closes #1194
Closes #1195

* fix(cli): address review feedback on docker arm64 fix

Follow-up to 61880cdc. Addresses one substantive review comment from
@vanceingalls and three self-review gaps.

1. Restore loud build failure on amd64 when chrome-headless-shell is
   missing (per @vanceingalls). The original Dockerfile used an `&&`
   chain that crashed the build if `find` returned empty; the new
   `if/else` wrapper silently fell through to system chromium even on
   amd64, which would mask golden-baseline regressions from a future
   @puppeteer/browsers cache layout change. The else branch now checks
   `TARGETARCH = amd64` and exits 1 with an actionable error, while
   arm64 still falls through to the system-chromium wrapper cleanly.

2. Add `HYPERFRAMES_DOCKER_PLATFORM` env override. The fix derives
   platform from `process.arch`, which silently picks the wrong arch
   in three real-world cases: x64 Node under Rosetta on Apple Silicon
   (re-triggers issue #1193), parity-regen for amd64 golden baselines
   on an arm64 host, and DOCKER_HOST pointing at a remote daemon with
   a different arch. Empty/whitespace override is a no-op (falls back
   to arch detection) so `export FOO=""` doesn't pin platform to "".

3. Fail fast when `--gpu` is requested on arm64. Docker Desktop on
   Apple Silicon doesn't implement `--gpus` passthrough; the previous
   code would crash at `docker run` with an opaque device-driver
   error. We now short-circuit with errorBox pointing at the env
   override as the workaround.

4. Close the test gap on the default-arch resolution. Every previous
   test passed `arch` explicitly; a refactor that dropped the
   `= process.arch` default would pass all tests but break every arm64
   host at runtime. Added one assertion that calls
   `resolveDockerPlatform()` with no args, plus coverage for the env
   override.

The new arm64 platform-checking logic is extracted into
`resolveDockerHostPlatform()` so `renderDocker` itself stays focused
on the build/run wiring (and below the fallow complexity gate).

Test plan:
- `bunx vitest run packages/cli/src/utils/dockerRunArgs.test.ts` — 31 passed (was 27).
- `bunx vitest run packages/cli` — 647 passed (was 643).
- E2E on macOS 26.5 / M4 Max: deleted the cached arm64 image, ran
  `--docker --quality draft --workers 1` against the blank scaffold —
  300/300 frames in 1m1s wallclock, MP4 produced.

packages/cli/src/utils/dockerRunArgs.ts

@@ -17,6 +17,16 @@ export interface DockerRunArgsInput {
   outputDir: string;
   /** Filename within `outputDir` (joined to /output inside the container). */
   outputFilename: string;
+  /**
+   * Docker `--platform` value (`linux/amd64` or `linux/arm64`). When omitted,
+   * resolves to the host architecture via `resolveDockerPlatform()`. Pinning
+   * to `linux/amd64` on an arm64 host (the legacy default) forces qemu
+   * emulation of chrome-headless-shell, which segfaults or stalls on Apple
+   * Silicon — see issue #1193. Native `linux/arm64` falls back to the
+   * system chromium baked into the image at the cost of byte-for-byte
+   * parity with amd64 renders.
+   */
+  platform?: string;
   options: DockerRenderOptions;
 }
 
@@ -44,13 +54,39 @@ export interface DockerRenderOptions {
   pageSideCompositing?: boolean;
 }
 
+/**
+ * Maps Node's `process.arch` to a Docker `--platform` string. We only emit
+ * the two architectures the renderer actively supports — arm64 hosts (Apple
+ * Silicon, Graviton, Ampere) and everything else (treated as amd64).
+ *
+ * Honors `HYPERFRAMES_DOCKER_PLATFORM` as an escape hatch (typed loosely so
+ * the override can target future platforms without a CLI release):
+ *
+ * - Apple Silicon users running an x64 Node binary under Rosetta (where
+ *   `process.arch === "x64"` despite the host being arm64) can set it to
+ *   `linux/arm64` to avoid re-triggering issue #1193.
+ * - Maintainers regenerating amd64 golden baselines on an arm64 host can set
+ *   it to `linux/amd64` to keep the byte-for-byte guarantee.
+ * - Users on remote daemons (`DOCKER_HOST=ssh://amd64-server`) can force the
+ *   actual daemon arch instead of relying on local `process.arch`.
+ */
+export function resolveDockerPlatform(
+  arch: string = process.arch,
+  env: NodeJS.ProcessEnv = process.env,
+): string {
+  const override = env.HYPERFRAMES_DOCKER_PLATFORM;
+  if (override && override.trim() !== "") return override.trim();
+  return arch === "arm64" ? "linux/arm64" : "linux/amd64";
+}
+
 export function buildDockerRunArgs(input: DockerRunArgsInput): string[] {
   const { imageTag, projectDir, outputDir, outputFilename, options } = input;
+  const platform = input.platform ?? resolveDockerPlatform();
   return [
     "run",
     "--rm",
     "--platform",
-    "linux/amd64",
+    platform,
     "--shm-size=2g",
     // GPU encoding requires host GPU passthrough.
     ...(options.gpu ? ["--gpus", "all"] : []),