@mevdragon/vidfarm-devcli 0.13.0 → 0.15.0

package/.agents/skills/hyperframes-animation/rules/camera-cursor-tracking.md

@@ -0,0 +1,246 @@
+---
+name: camera-cursor-tracking
+description: Two-phase virtual camera that locks viewport to a moving focal point with configurable initial positioning.
+metadata:
+  tags: camera, tracking, viewport, two-phase, spring
+---
+
+# Two-Phase Camera Cursor Tracking
+
+Keeps a horizontally-growing element (e.g. a search bar with typing text, a long URL animating in) visible by switching between two camera modes.
+
+## How It Works
+
+Separate **World Space** (the full target element with all content) from **Screen Space** (the viewport). Two phases:
+
+- **Phase 1 (Static)** — The world container sits at a fixed initial offset. Camera doesn't move. This anchors the viewer's eye to the composition before tracking begins.
+- **Phase 2 (Tracking)** — Activates when the focal point (cursor, highlight, last typed glyph) exceeds a target screen position (e.g. a configurable fraction `CURSOR_TARGET_FRACTION` of viewport width from the left). The world container translates leftward (`x: -<delta>`) keeping the focal point pinned at that screen position.
+
+The offset math is **mathematically continuous** at the phase boundary — at the instant tracking starts, the world position equals what the static phase had. So the transition is seamless.
+
+The piecewise form used in code is:
+
+```
+finalWorldX = Math.min(INITIAL_OFFSET, trackingOffset)
+```
+
+`INITIAL_OFFSET` is the static-phase value; `trackingOffset` is whatever shift keeps the focal point at `CURSOR_TARGET_FRACTION × viewportWidth`. While the focal point hasn't grown past the target screen X, `trackingOffset` exceeds `INITIAL_OFFSET` (it's a less-negative number) and `Math.min` returns the static value. Once the focal point would cross the target, `trackingOffset` overtakes `INITIAL_OFFSET` and tracking takes over.
+
+## HTML
+
+```html
+<div
+  class="scene"
+  id="tracking-scene"
+  data-composition-id="tracking-scene"
+  data-start="0"
+  data-duration="5"
+  data-track-index="0"
+>
+  <div class="viewport">
+    <div class="world">
+      <div class="search-bar">
+        <span class="text" id="reveal-text">{phrase}</span><span class="cursor">|</span>
+      </div>
+    </div>
+  </div>
+</div>
+```
+
+## CSS (hero-frame layout)
+
+```css
+.scene {
+  position: relative;
+  width: 100%;
+  height: 100%;
+}
+
+.viewport {
+  position: absolute;
+  inset: 0;
+  overflow: hidden; /* clip the world content */
+  display: flex;
+  align-items: center;
+  justify-content: flex-start;
+  padding-left: VIEWPORT_PAD_LEFT; /* "left margin" — variation: left-aligned init */
+}
+
+.world {
+  display: flex;
+  align-items: center;
+  white-space: nowrap; /* keep text on one line for camera-tracking */
+  transform: translateX(0); /* GSAP will animate this */
+}
+
+.search-bar {
+  font-family: {font};
+  font-size: BAR_FONT_SIZE;
+  font-weight: BAR_FONT_WEIGHT;
+  color: {textColor};
+  letter-spacing: BAR_LETTER_SPACING;
+}
+
+.search-bar .text {
+  /* Width grows as more characters reveal */
+  display: inline-block;
+  overflow: hidden;
+  vertical-align: bottom;
+}
+
+.search-bar .cursor {
+  display: inline-block;
+  width: CURSOR_WIDTH;
+  margin-left: CURSOR_GAP;
+  background: {accentColor};
+  height: CURSOR_HEIGHT_EM;
+  vertical-align: bottom;
+  /* No `animation: blink` CSS keyframe here — HF renders by seeking a paused
+     timeline, and CSS animation clocks are NOT synced to that seek. A CSS
+     blink will flicker non-deterministically. Drive cursor blink as a finite
+     yoyo tween on the GSAP timeline instead — see GSAP Timeline section. */
+}
+```
+
+## GSAP Timeline
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
+<script>
+  window.__timelines = window.__timelines || {};
+  const tl = gsap.timeline({ paused: true });
+
+  // Pre-measure target text width to compute tracking distance.
+  // Build the timeline SYNCHRONOUSLY — see Critical Constraints for why
+  // a fonts.ready gate causes worker-race flicker.
+  const textEl = document.getElementById("reveal-text");
+  const fullText = textEl.textContent;
+  const targetCursorScreenX = CURSOR_TARGET_FRACTION * VIEWPORT_WIDTH;
+  const fullWidth = textEl.scrollWidth; // total text width after full reveal
+  const trackingDelta = Math.max(0, VIEWPORT_PAD_LEFT + fullWidth - targetCursorScreenX);
+
+  // Phase 1 — text reveals progressively; camera holds.
+  // Reveal via max-width tween (no layout-property tweens on width/left/top).
+  tl.fromTo(
+    ".search-bar .text",
+    { maxWidth: 0 },
+    {
+      maxWidth: fullWidth,
+      duration: REVEAL_DUR,
+      ease: "none", // linear typing rate
+    },
+    REVEAL_START,
+  );
+
+  // Phase 2 — camera tracks. Begin BEFORE full reveal so the boundary feels
+  // continuous (text is still revealing as camera starts moving). The
+  // Math.min(INITIAL_OFFSET, trackingOffset) formulation makes the handoff
+  // mathematically continuous; see How It Works.
+  tl.to(
+    ".world",
+    {
+      x: -trackingDelta,
+      duration: TRACK_DUR,
+      ease: "power2.inOut",
+    },
+    TRACK_START,
+  );
+
+  // Cursor blink — GSAP-driven (NEVER CSS @keyframes infinite, which doesn't
+  // sync with HF's seek-by-frame). Finite yoyo, repeats computed from scene
+  // length so blinks land deterministically across frames.
+  const blinkRepeats = Math.ceil(SCENE_DURATION / BLINK_HALF_PERIOD) - 1;
+  tl.to(
+    ".search-bar .cursor",
+    {
+      opacity: 0,
+      duration: BLINK_HALF_PERIOD,
+      ease: "steps(1)", // hard on/off, no fade
+      yoyo: true,
+      repeat: blinkRepeats,
+    },
+    0,
+  );
+
+  window.__timelines["tracking-scene"] = tl;
+</script>
+```
+
+### Variations
+
+- **Centered → Center-Tracked**: set `.viewport { justify-content: center; padding: 0; }`. Camera tracks once the focal point crosses the midline (`CURSOR_TARGET_FRACTION = 0.5`).
+- **Left-Aligned → Right-Tracked**: as written above. Best when content exceeds viewport width from the start.
+- **Continuous typing driver**: replace the `maxWidth` tween with an `onUpdate` typing clock (`charsTyped = Math.floor(progress)`) plus per-frame `measureNodeWidth` to drive the cursor screen X. Required when the typed text is consumed elsewhere in the scene (e.g. by a parent strip's camera offset).
+
+## How to Choose Values
+
+- **VIEWPORT_PAD_LEFT** — left-edge padding of the world inside the viewport (Phase 1 anchor X).
+  - Range: 0 → ~10% of viewport width
+  - Effects: 0 hugs the left edge; larger inset feels more like a centered hero frame
+  - Constraints: must match the CSS `padding-left` on `.viewport` or the camera math drifts
+- **VIEWPORT_WIDTH** — the composition's `data-width` in CSS pixels.
+  - Constraints: must equal the scene root's `data-width`; never tweened
+- **CURSOR_TARGET_FRACTION** — fraction of viewport width where the focal point locks during Phase 2.
+  - Range: 0.5 (center-tracked) → 0.75 (right-leaning, more text visible behind cursor)
+  - Effects: lower values leave less revealed text in frame; higher values delay tracking
+- **BAR_FONT_SIZE** — hero element font size.
+  - Range: ~8-12% of viewport height; below ~6% reads as a UI widget rather than a cinematic element
+- **BAR_FONT_WEIGHT** — weight of the search-bar text.
+  - Range: discrete; 400 for neutral demo text, 700 for hero / headline framing
+- **BAR_LETTER_SPACING** — `letter-spacing` for the bar text.
+  - Range: slight negative (tighter, more cinematic) → 0 (default)
+- **CURSOR_WIDTH** — visual cursor stroke width in CSS pixels.
+  - Range: ~4-10 px at 1080p; thinner reads as typed text, thicker reads as a block caret
+- **CURSOR_GAP** — `margin-left` between text and cursor.
+  - Range: a few px of breathing room; do not exceed the cursor width or it visually detaches
+- **CURSOR_HEIGHT_EM** — cursor height as an em multiple of the font.
+  - Range: 0.85-1.0; matches the visual height of the typed glyphs
+- **REVEAL_START** — when Phase 1 typing begins.
+  - Constraints: typically 0; if preceded by another phase, ≥ that phase's end + small buffer
+- **REVEAL_DUR** — duration of the Phase 1 reveal tween.
+  - Range: scale with character count (target an average per-character cadence in the 0.05-0.15s range)
+  - Constraints: must end before `SCENE_DURATION` and ideally overlap slightly with the tracking phase
+- **TRACK_START** — when Phase 2 camera motion begins.
+  - Range: usually before reveal completes so the handoff feels continuous; can equal `REVEAL_START` if the focal point is already past the target at t=0
+  - Constraints: `TRACK_START < REVEAL_START + REVEAL_DUR` for a smooth crossfade
+- **TRACK_DUR** — duration of the camera pan.
+  - Range: 0.8-2.0s; under 0.5s reads as a snap, over 2.5s drags
+- **SCENE_DURATION** — must match the scene root's `data-duration`.
+  - Constraints: feeds the blink repeat count; mismatch causes blinks to truncate or run past the end
+- **BLINK_HALF_PERIOD** — half-period of the cursor blink (one on-state OR one off-state).
+  - Range: 0.2-0.4s; 0.3s reads as a natural caret blink
+  - Constraints: derived value `Math.ceil(SCENE_DURATION / BLINK_HALF_PERIOD) - 1` must be ≥ 0
+- **Ease choices** — discrete:
+  - Camera pan: `power2.inOut` or `power3.inOut` for cinematic settle; avoid `back.out` (overshoot reads as UI bounce, not camera)
+  - Reveal: `"none"` for linear typing; any easing distorts the per-keystroke cadence
+  - Blink: `"steps(1)"` for hard on/off; any easing fades the cursor and breaks the caret feel
+
+## Key Principles
+
+- **Measure with `getBoundingClientRect()` / probe nodes**, not by character count × font-size. Proportional fonts have variable glyph widths.
+- **`white-space: nowrap`** on the world — text must stay on one line for camera math to work
+- **Pre-allocate the world width** by setting `maxWidth` at full target width — prevents layout shift mid-tween
+- **Eased camera** (`power2.inOut` / `power3.inOut`), not linear — natural pan feel
+- **Spring-like via easing**, not via stiffness/damping params — GSAP doesn't have a built-in spring, but `back.out(${BOUNCE_FACTOR})` or `power4.out` approximate the settling feel
+
+## Critical Constraints
+
+- **Build the timeline SYNCHRONOUSLY, no fonts.ready gate** — HF renders frames in parallel workers, each a fresh browser. If you wrap the timeline build in `document.fonts.ready.then(...)`, some workers will seek frames BEFORE the Promise resolves and find no timeline registered → those frames render at CSS initial state (e.g. `max-width: 0` ⇒ empty text), other workers render correctly → visible flicker between empty and filled. Register `window.__timelines[id] = tl` at script-parse time, even if fonts haven't loaded yet — the camera math can tolerate a few percent width error from fallback-font measurement, but worker-race flicker is unacceptable.
+- **If precise post-font measurement matters**, re-measure inside the tween's `onUpdate` (still deterministic per-frame seek), not via a Promise gate. Or set `font-display: block` on the @font-face to force the browser to wait for the font before painting any text.
+- **Timeline must be paused**: `gsap.timeline({ paused: true })`. Never `tl.play()`
+- **Registry key = `data-composition-id`**: `window.__timelines["tracking-scene"]` must match scene root
+- **Continuous math at phase boundary**: the world's `x` at the moment tracking starts must equal the static-phase offset. The `Math.min(INITIAL_OFFSET, trackingOffset)` formulation guarantees this; do NOT switch to a hard `if (typingProgress > threshold)` branch or the camera will visibly jump.
+- **Inline cursor, not absolutely positioned**: cursor should be a sibling of the text (inline-block) so it follows text flow naturally — absolute positioning misaligns with the camera math
+- **`overflow: hidden` on `.viewport`**: clip the world's left edge as it pans off-screen
+- **Cursor blink via GSAP, NOT CSS `@keyframes ... infinite`** — HF renders by seeking the paused timeline; CSS animation clocks are NOT synchronized with that seek, so any CSS-driven blink will flicker non-deterministically across frames. Always drive blink as a finite yoyo tween on the paused GSAP timeline (repeat count computed from scene length).
+
+## Combinations
+
+- [context-sensitive-cursor.md](context-sensitive-cursor.md) — change cursor color/style per text segment during typing
+- [discrete-text-sequence.md](discrete-text-sequence.md) — non-linear text reveals that pair with this camera
+
+## Pairs with HF skills
+
+- `/hyperframes-animation` — timeline + tween API
+- `/hyperframes-core` — composition wiring + `data-*` attributes
+- `/hyperframes-cli` — `hyperframes lint` to validate the registry key + duration

package/.agents/skills/hyperframes-animation/rules/card-morph-anchor.md

@@ -0,0 +1,267 @@
+---
+name: card-morph-anchor
+description: Container morphs dimensions and border-radius between shots, serving as a visual transition anchor.
+metadata:
+  tags: morph, anchor, transition, border-radius, container, shape
+---
+
+# Card Morph Anchor
+
+A container smoothly transforms its width, height, border-radius, and (optionally) background between two visual states. The morph itself **IS the shot transition** — no separate transition effect needed. The viewer's eye tracks the morphing container as the anchor between shots.
+
+## How It Works
+
+A single GSAP tween animates multiple container properties simultaneously (width / height / border-radius / background). At the same time:
+
+1. **Old content** fades out during the first ~40% of the morph
+2. **New content** fades in during the last ~40% of the morph
+3. **Optional final fade** — the morph container itself fades to 0, revealing the actual next-shot element rendered behind it
+
+The persistent container provides visual continuity even as content and shape change.
+
+## HTML
+
+```html
+<div
+  class="scene"
+  id="morph-scene"
+  data-composition-id="morph-scene"
+  data-start="0"
+  data-duration="4"
+  data-track-index="0"
+>
+  <!-- The persistent morph container -->
+  <div class="morph-card">
+    <div class="content-old">
+      <h2>{shotOneHeadline}</h2>
+      <p>{shotOneSubcopy}</p>
+    </div>
+    <div class="content-new">
+      <img src="{shotTwoIcon}" alt="logo" />
+    </div>
+  </div>
+
+  <!-- Optional: actual next-shot element behind the morph -->
+  <div class="next-shot-anchor">
+    <img src="{nextShotAnchor}" alt="anchor" />
+  </div>
+</div>
+```
+
+## CSS (hero-frame layout)
+
+Card starts as a wide rectangle (shot 1 state). All properties present from the start; only opacities differ:
+
+```css
+.scene {
+  position: relative;
+  width: 100%;
+  height: 100%;
+  display: grid;
+  place-items: center;
+}
+
+.morph-card {
+  position: relative;
+  width: {SHOT_ONE_W}px;
+  height: {SHOT_ONE_H}px;
+  border-radius: {SHOT_ONE_RADIUS}px;
+  background: {surfaceShotOne};
+  overflow: hidden;
+  box-shadow: 0 20px 60px rgba(0, 0, 0, 0.4);
+  display: grid;
+  place-items: center;
+}
+
+.content-old,
+.content-new {
+  position: absolute;
+  inset: 0;
+  display: grid;
+  place-items: center;
+  padding: 32px;
+}
+
+.content-old {
+  opacity: 1;
+}
+.content-new {
+  opacity: 0;
+}
+
+.next-shot-anchor {
+  position: absolute;
+  left: 50%;
+  top: 50%;
+  transform: translate(-50%, -50%);
+  opacity: 0; /* GSAP fades this in as morph card fades out */
+  /* Use DOM ORDER for stacking — render .next-shot-anchor BEFORE .morph-card
+     in markup so the morph card is naturally on top. Do NOT use z-index: -1
+     and then snap it positive mid-fade — that causes a visible pop. */
+}
+```
+
+## GSAP Timeline
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
+<script>
+  window.__timelines = window.__timelines || {};
+  const tl = gsap.timeline({ paused: true });
+
+  // Named constants — assign in your example only. See "How to Choose Values".
+  const HOLD_BEAT; // s — pre-morph dwell on shot 1
+  const MORPH_START; // s — usually = HOLD_BEAT
+  const MORPH_DUR; // s — full container morph length
+  const SHOT_TWO_W; // px — final container width
+  const SHOT_TWO_H; // px — final container height
+  const SHOT_TWO_RADIUS; // px — ≤ min(SHOT_TWO_W, SHOT_TWO_H) / 2
+  const OLD_FADE_FRAC; // 0..0.5 — fraction of MORPH_DUR for old content fade
+  const NEW_FADE_FRAC; // 0..0.5 — fraction of MORPH_DUR for new content fade
+  const FINAL_FADE_FRAC; // 0..0.3 — optional tail fade for handoff
+  // {surfaceShotTwo} is a CSS background token (solid or gradient).
+
+  // Hold shot 1 — let the viewer register the wide banner before morphing.
+
+  // Phase 1 — Morph container properties simultaneously
+  tl.to(
+    ".morph-card",
+    {
+      width: SHOT_TWO_W,
+      height: SHOT_TWO_H,
+      borderRadius: SHOT_TWO_RADIUS,
+      background: "{surfaceShotTwo}",
+      duration: MORPH_DUR,
+      ease: "power2.inOut",
+    },
+    MORPH_START,
+  );
+
+  // Phase 2 — Old content fades during the FIRST OLD_FADE_FRAC of the morph
+  tl.to(
+    ".content-old",
+    {
+      opacity: 0,
+      duration: MORPH_DUR * OLD_FADE_FRAC,
+      ease: "power1.in",
+    },
+    MORPH_START,
+  );
+
+  // Phase 3 — New content fades in during the LAST NEW_FADE_FRAC of the morph
+  tl.to(
+    ".content-new",
+    {
+      opacity: 1,
+      duration: MORPH_DUR * NEW_FADE_FRAC,
+      ease: "power1.out",
+    },
+    MORPH_START + MORPH_DUR * (1 - NEW_FADE_FRAC),
+  );
+
+  // Optional Phase 4 — Final fade: morph container disappears at the very end,
+  // revealing the actual next-shot element behind it.
+  tl.to(
+    ".morph-card",
+    {
+      opacity: 0,
+      duration: MORPH_DUR * FINAL_FADE_FRAC,
+      ease: "power1.in",
+    },
+    MORPH_START + MORPH_DUR * (1 - FINAL_FADE_FRAC),
+  );
+
+  window.__timelines["morph-scene"] = tl;
+</script>
+```
+
+## Key Properties to Morph
+
+| Property           | Shape of change                                                | Visual effect                |
+| ------------------ | -------------------------------------------------------------- | ---------------------------- |
+| `width` / `height` | `SHOT_ONE_W × SHOT_ONE_H` → `SHOT_TWO_W × SHOT_TWO_H`          | wide card shrinks to an icon |
+| `borderRadius`     | `SHOT_ONE_RADIUS` → `SHOT_TWO_RADIUS` (≤ half of smaller side) | rectangle becomes a circle   |
+| `background`       | `{surfaceShotOne}` → `{surfaceShotTwo}` (solid or gradient)    | container identity shifts    |
+| `boxShadow`        | base shadow → accent glow token                                | emphasis changes             |
+
+GSAP tweens all of these simultaneously when included in one `tl.to(...)` call.
+
+## How to Choose Values
+
+- **HOLD_BEAT** — pre-morph dwell so the viewer registers shot 1 before it changes
+  - Range: 0.6-1.5 s
+  - Effects: low end feels rushed / glitchy; high end stalls pacing
+  - Constraints: must be ≥ shot 1's content entry settle time
+- **MORPH_START** — when the container morph begins
+  - Range: equal to `HOLD_BEAT` in the canonical pattern
+  - Constraints: must be > any shot-1 entry tween end
+- **MORPH_DUR** — full length of the simultaneous container morph
+  - Range: 0.6-1.2 s
+  - Effects: low end reads as a snap; high end loses momentum
+  - Constraints: short morphs (<0.5s) cannot fit both old-fade and new-fade
+- **SHOT_TWO_W / SHOT_TWO_H** — final container dimensions
+  - Range: 80-400 px when handing off to an icon-sized anchor
+  - Constraints: if handing off (`.next-shot-anchor`), MUST match the anchor's dimensions exactly to avoid a visible pop
+- **SHOT_TWO_RADIUS** — final corner radius (use to read as circle / pill / soft-rect)
+  - Range: 0 to `min(SHOT_TWO_W, SHOT_TWO_H) / 2`
+  - Effects: half-of-smaller-side = perfect circle; smaller = soft rect
+  - Constraints: > half is visually clamped — wastes the tween
+- **OLD_FADE_FRAC** — fraction of `MORPH_DUR` over which shot-1 content fades out, starting at `MORPH_START`
+  - Range: 0.3-0.5
+  - Effects: low end clips shot 1 too early; high end overlaps with shot 2 content
+  - Constraints: `OLD_FADE_FRAC + NEW_FADE_FRAC ≤ 1` (gap between is the "shape-only" moment)
+- **NEW_FADE_FRAC** — fraction of `MORPH_DUR` over which shot-2 content fades in, ending at `MORPH_START + MORPH_DUR`
+  - Range: 0.3-0.5
+  - Effects: symmetric to OLD_FADE_FRAC
+- **FINAL_FADE_FRAC** — optional tail fraction during which the morph container itself fades to 0 for handoff
+  - Range: 0 (no handoff) or 0.1-0.2
+  - Constraints: only use when `.next-shot-anchor` matches the morph's final visual exactly
+- **Ease family** — discrete choice
+  - Options: `power2.inOut` (canonical, balanced), `power3.inOut` (snappier), `expo.inOut` (most cinematic but can feel sluggish at low durations)
+  - Avoid `back.out` / `elastic.out` on the morph itself — overshoot fights the dimensional change
+
+CSS-side placeholders (`SHOT_ONE_W`, `SHOT_ONE_H`, `SHOT_ONE_RADIUS`, `{surfaceShotOne}`, `{surfaceShotTwo}`) take real values in the example. Pick `{surfaceShotOne}` and `{surfaceShotTwo}` so the gradient/solid stops counts match (GSAP can interpolate background gradients only when stop counts agree).
+
+## Key Principles
+
+- **All target properties in one tween** — they share a single ease and duration so they morph in lockstep
+- **Old content fades early, new content fades late** — the container shape change happens between, providing a natural "blink" moment
+- **Final fade is optional** — use it when the next shot has a real anchor element to hand off to (e.g. avatar that the icon morphed into "is")
+- **Same easing for shape and crossfade** — avoid mixing `power2.inOut` morph with `bounce.out` content, looks unsynchronized
+- **❗ If you use `.next-shot-anchor` for handoff, its visuals must be pixel-identical to `.morph-card`'s final state** — same `width` / `height`, same `border-radius`, same `background`, same `box-shadow`, same internal icon dimensions. Any visual delta between the two = visible pop during the crossfade. If you can't match exactly, **drop the handoff** and just hold the morph card at its final state (add a breath if needed for life).
+
+## Critical Constraints
+
+- **`overflow: hidden`** on the morph container — content must clip during shape change, otherwise content overflows the morphing border radius
+- **Hold a beat before morphing** — let the viewer register shot 1's content before morphing; instant morph reads as glitchy
+- **Timeline must be paused**: `gsap.timeline({ paused: true })`. Never `tl.play()`
+- **Registry key = `data-composition-id`**: `window.__timelines["morph-scene"]` must match scene root
+- **Use `background` tween, not `background-color`**: gradients need `background` (GSAP supports gradient interpolation when targets are gradients with same number of stops). For solid → solid, `backgroundColor` works.
+- **`borderRadius` should be ≤ half the smaller dimension** at end state — otherwise the radius is visually clamped and the morph looks abrupt at the boundary
+- **❗ Don't snap `z-index` mid-fade** — if you need `.next-shot-anchor` to appear from behind the morph card, use **DOM order** (render `.next-shot-anchor` BEFORE `.morph-card` so the morph card is naturally on top), then crossfade their opacities. A `tl.set({ zIndex: ... })` call during an active opacity tween causes a visible flicker as the stacking order flips before the opacity transition finishes.
+
+## Variation: Morphing to a target element's position
+
+When shot 2 isn't centered (e.g. the morph card "lands" on a specific icon in a dock, sidebar, or grid), compute the target `top` / `left` from the **target element's element-position**, not its visual center. Common mistake: subtracting `height/2` to get center, then applying that to the morph-card's `top` — but if `.morph-card` uses absolute positioning with `top` + `margin: 0` (no transform-centering), `top` represents the **element top edge**, not the center.
+
+Math template (example: morph card lands on icon at bottom dock):
+
+```
+target_element_top = viewport_height − dock_bottom_offset − dock_padding_y − icon_height
+                   = 1080 − 60 − 22 − 110 = 888 px
+```
+
+Then tween `.morph-card { top: 888 }` so its element-top aligns with the target icon's element-top. If you mistakenly tween to `888 + icon_height/2 = 943` you'll land below; tweening to a "center" value like `top: 933` (off-by-arithmetic) will be even worse.
+
+Always **measure the target element with `getBoundingClientRect()`** before the timeline starts, and use those numbers — don't hand-compute from CSS values, since paddings, borders, and parent transforms compound.
+
+## Combinations
+
+- [scale-swap-transition.md](scale-swap-transition.md) — simpler morph without dimension change (just scale + content swap)
+- [sine-wave-loop.md](sine-wave-loop.md) — gentle breathing on the final state (e.g. final small circular icon idles with a breath)
+
+## Pairs with HF skills
+
+- `/hyperframes-animation` — timeline + multi-property tween reference
+- `/hyperframes-core` — composition wiring, `data-*` attributes
+- `/hyperframes-cli` — `hyperframes lint` to verify scene structure