feat(experiments): hfir, an assembly-like IR agents write instead of HTML

[miguel-heygen]

What

An experiment under experiments/hfir/: a flat, assembly-flavoured IR that an agent writes instead of HTML, which compiles to a normal HyperFrames composition.

Not shipped, not proposed for shipping, not wired into anything. It exists to answer a question with a runnable prototype instead of an argument.

Why

The provocation, roughly: code no longer needs to be intuitive to us, because increasingly no human reads it. It needs to be intuitive to agents, and agents want the opposite of what humans want, explicitness and dials rather than terseness and convention. "Assembly for programmatic video rather than Ruby on Rails."

So: what if an agent never wrote HTML at all?

What it looks like

A complete scene, with no HTML and no CSS anywhere in it:

CANVAS  1280 720 30
FRAMES  60

DECL    box   rect
DECL    tag   text

SET   0   box  x 120
SET   0   box  opacity 0
RAMP  15  box  opacity 1
RAMP  45  box  x 960
RAMP  45  box  fill #0F7A52
SET   30  tag  text FRAME_30_EXACTLY

The one design decision that matters: SET and RAMP are different opcodes. SET is a hard step that holds; RAMP interpolates linearly into the stated value. Interpolation is declared per property, per segment. There is no implicit tween and no easing name to misinterpret.

How it runs

Chrome never sees the IR. It is compiled ahead of time in Node:

scene.hfir  --compile.mjs-->  index.html (empty divs + WAAPI .animate())  -->  Chrome

The output is an ordinary composition, so lint, check, render, preview and Studio all work on it unchanged. No new runtime, no interpreter to ship.

It targets WAAPI rather than CSS keyframes because seeking by currentTime is the path the engine treats as authoritative, and it is a Baseline web standard rather than a Chromium internal. The useful consequence is that the IR inherits browser text shaping, compositing and colour for free while the agent never touches the cascade or the box model.

Verified, not asserted

Rendered, and frames checked against the table by eye:

Frame	Table says	Pixels show
0	box opacity 0	box genuinely absent, text white at exactly (120,120)
29 → 30	SET is a step	white text on 29, blue on 30, nothing in between
45	two RAMPs	box at x=960, colour interpolated red → green

60 frames of 720p in ~2.5s.

Test plan

• Unit tests added/updated
• Manual testing performed
• Documentation updated (if applicable)

6 tests covering keyframe placement on exact frames, SET vs RAMP easing, and the three parse errors (undeclared element, unmapped property, op past the end). Plus the render above.

node experiments/hfir/compile.mjs experiments/hfir/scene.hfir /tmp/hfir/index.html
npx hyperframes render /tmp/hfir

What it is not

Being blunt so nobody over-reads this:

• Not a format. ~200 lines written in an afternoon. No spec, no versioning, no round-trip from Studio back to the IR, no error recovery beyond three parse checks.
• Not complete. No layout (absolute pixels only), no text wrapping, no media, no sub-compositions, no audio. Eight properties are mapped.
• Not literally assembly. The timeline is fully explicit, but everything underneath it, layout, shaping, rasterisation, is still the browser doing enormous amounts of work on our behalf. It is closer to a tracker file than to x86.
• Not proven better. It shows the idea is possible, not that it wins.

The bit I would actually like a second opinion on

This is also the honest answer to "should we build a native renderer": the explicitness people want from native turns out to be a compiler problem rather than an engine problem. Solving it this way keeps the installed renderer, the standards floor, and the enormous amount of HTML/CSS in every model's training data.

If that reasoning is wrong, this is a cheap place to find out.

The follow-up worth running either way: give an agent the IR spec and the HTML spec cold, same prompts, and measure first-valid-render rate and repair loops. Nobody in the category publishes that number for any format.