chore: import upstream snapshot with attribution

skills/hyperframes-animation/rules/hacker-flip-3d.md

@@ -0,0 +1,223 @@
+---
+name: hacker-flip-3d
+description: Character-level 3D rotation with random glyph substitution for a decryption reveal effect.
+metadata:
+  tags: text, 3d, reveal, decode, hacker, randomization, perspective
+---
+
+# Hacker Flip 3D Reveal
+
+Characters flip down from 90° in 3D while cycling through random glyphs, then settle on the target character. Creates a "decryption" or airport flap-display reveal.
+
+## How It Works
+
+Each character gets its own per-char tween from `rotateX: 90deg` (hidden) to `rotateX: 0deg` (revealed), staggered across the word. During the flip:
+
+1. **Phase A (0 → ~`REVEAL_THRESHOLD` progress)**: character displays a randomly-substituted glyph that flickers (changes every `FLICKER_RATE` frames)
+2. **Phase B (`REVEAL_THRESHOLD` → 1.0 progress)**: character displays the REAL target character, settling into its final upright position
+
+The `REVEAL_THRESHOLD` separates "scrambled" from "revealed" — by the time the flip is mostly done, viewer sees the correct letter clicking into place.
+
+## HTML
+
+```html
+<div
+  class="scene"
+  id="hacker-flip-scene"
+  data-composition-id="hacker-flip-scene"
+  data-start="0"
+  data-duration="3"
+  data-track-index="0"
+>
+  <div class="hacker-text-wrap" id="hacker-text" data-target="{phrase}">
+    <!-- Per-char spans get injected by setup script below.
+         Ghost placeholder (data-ghost) is rendered identically to reserve width. -->
+  </div>
+</div>
+```
+
+`{phrase}` is the target word the flip resolves to (typically a brand or short label).
+
+## CSS
+
+```css
+.scene {
+  position: relative;
+  width: 100%;
+  height: 100%;
+  display: grid;
+  place-items: center;
+  background: {bgColor};
+  perspective: 1500px; /* REQUIRED — without this rotateX renders flat */
+}
+
+.hacker-text-wrap {
+  font-family: {monoFont};      /* monospace recommended so flicker glyphs hold width */
+  font-weight: 900;
+  font-size: HACKER_FONT_SIZE;
+  color: {textColor};
+  letter-spacing: 4px;
+  display: flex;
+  /* Ghost / live chars are absolutely stacked; container reserves layout width */
+  position: relative;
+}
+
+.hacker-char {
+  display: inline-block;
+  /* Hinge at the bottom edge — flap-display look */
+  transform-origin: bottom;
+  transform-style: preserve-3d;
+  /* Will-change improves render perf */
+  will-change: transform, opacity;
+}
+
+/* Ghost placeholder is hidden but reserves width for variable-glyph fonts.
+   Without this, narrow target glyphs collapse width when displayed and
+   characters shift horizontally during flicker. */
+.hacker-ghost {
+  opacity: 0;
+  pointer-events: none;
+}
+```
+
+## GSAP Timeline + Random Glyph Logic
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
+<script>
+  window.__timelines = window.__timelines || {};
+
+  const wrap = document.getElementById("hacker-text");
+  const targetWord = wrap.dataset.target;
+  const GLYPHS = "ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789!@#$%&*";
+
+  // Build live chars + ghost placeholders (ghost keeps layout width stable)
+  wrap.innerHTML = "";
+  const ghostRow = document.createElement("div");
+  ghostRow.className = "hacker-ghost";
+  ghostRow.style.display = "inline-flex";
+  ghostRow.style.position = "absolute";
+  ghostRow.style.left = "0";
+  ghostRow.style.top = "0";
+  ghostRow.textContent = targetWord;
+  wrap.appendChild(ghostRow);
+
+  const charEls = [];
+  const liveRow = document.createElement("div");
+  liveRow.style.display = "inline-flex";
+  liveRow.style.position = "relative";
+  for (const ch of targetWord) {
+    const span = document.createElement("span");
+    span.className = "hacker-char";
+    span.textContent = ch === " " ? " " : ch;
+    span.dataset.target = ch;
+    liveRow.appendChild(span);
+    charEls.push(span);
+  }
+  wrap.appendChild(liveRow);
+
+  // Deterministic "random" — seeded by char index + frame group so the same
+  // frame always yields the same glyph (HF seek determinism).
+  function pseudoGlyph(seed) {
+    const h = ((seed * 9301 + 49297) % 233280) / 233280;
+    return GLYPHS[Math.floor(h * GLYPHS.length)];
+  }
+
+  const tl = gsap.timeline({ paused: true });
+
+  // Per-char flip — stagger across the word
+  charEls.forEach((el, i) => {
+    const state = { p: 0 };
+    tl.to(
+      state,
+      {
+        p: 1,
+        duration: FLIP_DURATION,
+        ease: "power3.out",
+        onUpdate: () => {
+          // Phase A: random glyph flickering. Phase B: real character.
+          const progress = state.p;
+          if (progress < REVEAL_THRESHOLD) {
+            // Update glyph every FLICKER_RATE worth of progress
+            const flickerSeed = i * 1000 + Math.floor(progress * 100);
+            el.textContent = pseudoGlyph(flickerSeed);
+          } else {
+            el.textContent = el.dataset.target === " " ? " " : el.dataset.target;
+          }
+          // Flip rotateX from 90 (down) to 0 (upright)
+          const rotateX = 90 - progress * 90;
+          const opacity = Math.min(1, progress * 2);
+          el.style.transform = `rotateX(${rotateX}deg)`;
+          el.style.opacity = opacity;
+        },
+      },
+      i * CHAR_STAGGER,
+    );
+  });
+
+  window.__timelines["hacker-flip-scene"] = tl;
+</script>
+```
+
+## How to Choose Values
+
+- **HACKER_FONT_SIZE** — font-size of the flip text in px.
+  - Range: 6-10% of viewport min-dimension; the flip text is the focal beat, scale accordingly
+  - Constraints: ghost row must use the identical size so layout width stays stable mid-flicker
+  - Reference: ../../examples/proof-logo-chain.html uses `163px` at 1920×1080
+- **FLIP_DURATION** — per-character flip tween duration.
+  - Range: 0.4-1.0s; under 0.4s the random-glyph phase has no time to flicker, over 1.0s drags
+  - Effects: shorter feels snappy and modern; longer feels mechanical / typewriter
+  - Reference: ../../examples/proof-logo-chain.html uses `0.55s`
+- **CHAR_STAGGER** — delay between consecutive characters starting their flips, in seconds.
+  - Range: 0.03-0.08s; too fast and chars overlap visually, too slow and the effect feels labored
+  - Constraints: total decode time = `CHAR_STAGGER × (charCount − 1) + FLIP_DURATION`; ensure this fits the phase budget
+  - Reference: ../../examples/proof-logo-chain.html uses `0.033s` (≈2 frames at 60fps)
+- **REVEAL_THRESHOLD** — progress at which a glyph swaps from random → real.
+  - Range: 0.5-0.7; lower reveals too early (no decode tension), higher feels like a hard reveal at the end
+  - Effects: this is a discrete tuning of when the eye locks onto the real letter
+  - Reference: ../../examples/proof-logo-chain.html uses `0.6`
+- **FLICKER_RATE** — frames between glyph reshuffles during the random phase.
+  - Range: 3-6; lower than 3 looks like noise, higher than 6 looks like discrete typing instead of flicker
+  - Constraints: must be ≥ ~3 frames (see Critical Constraints)
+  - Reference: ../../examples/proof-logo-chain.html uses an equivalent of `3` (one shuffle every 3 internal-clock frames)
+- **{bgColor} / {textColor}** — stage background and live-character color tokens.
+- **{monoFont}** — monospace family preferred so flicker glyphs don't change width per swap; if a proportional font is required, the ghost placeholder makes the cost recoverable.
+- **{phrase}** — the target word the flip resolves to. Length feeds the total decode duration via `CHAR_STAGGER`.
+
+## Variations
+
+- **Top-down hinge** — swap `transform-origin: bottom` to `top` for a falling-flap look.
+- **Center spin** — `transform-origin: center` reads as a barrel roll, not a flap.
+- **Number-only pool** — restrict `GLYPHS` to digits for a price / countdown decode.
+- **Two-pass decode** — chain two `FLIP_DURATION` tweens with different glyph pools (e.g. symbols → letters → real) for a longer reveal.
+
+## Key Principles
+
+- **Threshold at ~`REVEAL_THRESHOLD`** for swap from random → real glyph — close enough to settled that viewer's eye catches the right letter
+- **Hinge at `transform-origin: bottom`** for flap-display look (vs `top` for top-down, vs `center` for spin)
+- **Deterministic random** via seeded hash — HF runtime seeks frame-by-frame, so the same frame must show the same glyph (no `Math.random()`)
+- **Ghost placeholder** sits behind the live chars with identical content + same font, reserving width — without it, narrow glyphs shift the layout mid-flicker
+- **Stagger in the 0.04-0.08s range** per char — too fast and chars overlap visually, too slow and effect feels labored
+- **Center the flip dead-center via `display: grid; place-items: center;`** on the scene root — and DO NOT add decorative headers/footers (timestamp lines, "// AUTH" tags, small status dots). The flip text IS the focal beat; surrounding clutter dilutes it. If a secondary label is necessary, promote it to BIG typography in the same stacked layout (56-72px caps + tracking), not a tiny corner annotation.
+
+## Critical Constraints
+
+- **`perspective` on scene root REQUIRED** — without parent perspective, `rotateX` looks like a 2D scale, not a 3D flip
+- **`transform-style: preserve-3d` on each char** — keeps 3D context intact when chars have their own transforms
+- **Timeline must be paused**: `gsap.timeline({ paused: true })`
+- **Registry key = `data-composition-id`**
+- **Deterministic randomness**: don't use `Math.random()`. Use a seed derived from char index + frame group so seek determinism holds
+- **`onUpdate` writes to DOM**: HF seeks every frame, so this runs many times — keep work O(1) per char per frame
+- **Flicker rate ≥ ~3 frames per glyph swap**: faster looks like noise, slower looks like discrete typing
+
+## Combinations
+
+- [card-morph-anchor.md](card-morph-anchor.md) — pair: hacker-flip reveals a phrase, then card morphs into the next shot
+- [counting-dynamic-scale.md](counting-dynamic-scale.md) — counterpart for numeric reveals (text vs number)
+
+## Pairs with HF skills
+
+- `/hyperframes-animation` — timeline + per-char stagger + `onUpdate`
+- `/hyperframes-core` — composition wiring
+- `/hyperframes-cli` — `hyperframes lint`