hyperframes/registry/components/iris-reveal/README.md

iris-reveal

A circle clip-path opens from an authored origin (iris_x/iris_y percent) revealing state B over state A in one confident pass, then holds still on B. The classic register dims and desaturates the before state so the after state lands in full color; register: plain leaves both states untouched. A thin accent rim rides the exact iris edge while the pass runs and dissolves just before the circle clears the frame corners. Clip-path only, seek-safe in both directions.

Files

• iris-reveal.html: the mountable sub-composition (install target: compositions/components/iris-reveal.html).
• registry-item.json: registry metadata and the variables block.
• demo.html: a 1920x1080 host that mounts the primitive with non-default variables (QA gallery input).

Variables

id	type	default	notes
iris_x	number	50	iris origin, percent of frame width (0 to 100)
iris_y	number	50	iris origin, percent of frame height (0 to 100)
open_at	number	0.35	seconds after mount start when the iris begins opening (0 to 8)
register	enum	color	color dims and desaturates state A; plain leaves both states alone
accent	enum	green	green maps to --brand, blue to --accent, violet to --accent-2
exit	enum	none	none holds the final frame; fade and up release the stage

Envelope: IN = open_at + 1.10s iris pass, OUT = 0.5s only when exit is fade or up, HOLD is the sole elastic phase. The iris-open sync point (hf:sfx id iris-land-soft) fires when the iris clears the frame, 1.45s at defaults.

The slot mechanism

The primitive ships two named slot panels inside its <template> (the before-after-wipe convention):

<div class="ir-slot" data-slot="before">...</div>
<div class="ir-slot" data-slot="after">...</div>

Each slot's default children are a token-styled wireframe card (muted on the before layer, brand-tinted on the after layer), so an untouched mount still reads as a tasteful reveal. To show your own content, install the component and replace the children of each [data-slot] element in your installed copy (the runtime clones only the primitive's own template on mount, so slot content lives in the component file, not on the host clip).

Rules:

• Both slots are full-bleed and share one coordinate space; align the two states so the iris reads as one surface changing, not two images stacked.
• Direct img/video children are automatically sized to cover the panel (object-fit: cover). Arbitrary HTML works too; size it in cqw/cqh.
• With register: color the grayscale/dim treatment applies to whatever you put in the before slot; switch to plain if your before content must stay full color.
• Keep the rim SVG alone; it renders above slot content and is owned by the timeline.

Worked example

Install, then fill the slots with two screenshots:

npx hyperframes add iris-reveal

In compositions/components/iris-reveal.html, replace each slot's default block:

<div class="ir-slot" data-slot="before">
  <img src="../../assets/scene-night.png" alt="" />
</div>
...
<div class="ir-slot" data-slot="after">
  <img src="../../assets/scene-day.png" alt="" />
</div>

Mount it from a host composition like any sub-composition:

<div
  class="clip"
  data-composition-id="iris-reveal"
  data-composition-src="./components/iris-reveal.html"
  data-variable-values='{"iris_x":30,"iris_y":40,"open_at":0.6,"accent":"blue"}'
  data-start="2"
  data-duration="3.5"
  data-track-index="0"
></div>

The iris opens 0.6s after the clip mounts from a point in the upper-left third, clears the frame 1.1s later, and the revealed state holds for the rest of the clip window (exit defaults to none; frame roots own scene transitions).