freecodego 0.1.7-alpha.2.1 → 0.1.7-rc.2.2

package/dist/assets/design/skills/hyperframes-animation/rules/chromatic-glitch.md

@@ -0,0 +1,150 @@
+---
+name: chromatic-glitch
+description: RGB-split / slice glitch that snaps sharp — offset color copies jitter on a deterministic hash of quantized timeline time (never Math.random), or horizontal slices displace and converge; a brief vibration, then a clean resolve. Entrance or emphasis punctuation; finite, seek-safe.
+metadata:
+  tags: glitch, rgb-split, chromatic, slice, jitter, stutter, text, snap, distortion
+---
+
+# Chromatic Glitch
+
+Digital interference as punctuation: for a fraction of a second the element **breaks** — offset color copies shudder behind it, or horizontal slices displace sideways — then it **snaps sharp** and holds clean. The payoff is the resolve; the glitch exists to make the clean state land harder. Two forms: an **RGB-split jitter** (warm + cool ghost copies vibrating behind the base) and a **slice displacement** (horizontal bands that arrive offset and converge).
+
+Boundaries: [motion-blur-streak.md](motion-blur-streak.md) is velocity blur tied to **travel** — its element is going somewhere fast. A glitching element is **in place**; the disturbance is temporal, not directional. [hacker-flip-3d.md](hacker-flip-3d.md) substitutes **glyphs** (a decode); here the glyphs are fixed and only displaced copies of them move.
+
+## How It Works
+
+The subject is stacked: the **base copy on top** (full legibility at every frame), ghost copies behind. All motion comes from one finite **amplitude-envelope** tween read by an `onUpdate`:
+
+1. **Quantized time** — `const step = Math.floor(tl.time() / JITTER_STEP)`. The stutter comes from offsets that hold for `JITTER_STEP` and then jump. Smoothly interpolated offsets read as wobble, not glitch — **the quantization IS the digital texture**.
+2. **Deterministic hash** — offsets are a pure function of `(step, layerIndex)`:
+
+   ```js
+   const glitchHash = (n) => {
+     const x = Math.sin(n * 127.1 + 311.7) * 43758.5453;
+     return x - Math.floor(x); // 0..1, pure — a scrub to any t recomputes the same frame
+   };
+   ```
+
+3. **Amplitude envelope** — a proxy tween carries `amp: 1 → 0` over `GLITCH_DUR`. Per-frame offset = `amp × (glitchHash(step * 13 + layer * 7) * 2 − 1) × MAX_SPLIT`. When the envelope hits zero the copies sit at exactly 0 — the snap-sharp is built into the math, and a final `tl.set` clamps the rest state so the hold is bit-exact.
+
+The **slice form** swaps color copies for `SLICE_COUNT` full copies, each clipped to a horizontal band via `clip-path: inset()`; per-band `x` (and optional `scaleX` stretch) start at hash-derived offsets and converge to 0 under a stepped ease.
+
+## Recipe
+
+```html
+<!-- inside a standard scene clip (hyperframes-core) -->
+<!-- Form A: RGB-split — ghosts behind, base on top. Copies metric-identical (one grid cell, same font stack); aria-hidden on every non-base copy. -->
+<div class="glitch-stack" id="glitch-stack">
+  <span class="glitch-copy warm" aria-hidden="true">{glitchText}</span>
+  <span class="glitch-copy cool" aria-hidden="true">{glitchText}</span>
+  <span class="glitch-base">{glitchText}</span>
+</div>
+```
+
+```css
+.glitch-stack {
+  display: grid; /* all copies share one cell — pixel-identical boxes */
+}
+.glitch-base,
+.glitch-copy {
+  grid-area: 1 / 1;
+}
+.glitch-base {
+  z-index: 2; /* grid items take z-index without position */
+  color: {textColor};
+}
+.glitch-copy {
+  z-index: 1;
+  opacity: 0; /* raised only while the envelope is live */
+  will-change: transform; /* updates every frame while live */
+  mix-blend-mode: screen; /* additive on dark bg; drop to normal (and lower opacity) on light */
+}
+.glitch-copy.warm {
+  color: {warmSplit}; /* classic: red/orange */
+}
+.glitch-copy.cool {
+  color: {coolSplit}; /* classic: cyan/blue */
+}
+```
+
+```js
+// Form A: RGB-split jitter — envelope snaps to full amplitude, decays to zero.
+// All per-frame state derives from tl.time() + the envelope: pure, replays on seek.
+const copies = gsap.utils.toArray("#glitch-stack .glitch-copy");
+const amp = { a: 0 };
+tl.set(amp, { a: 1 }, GLITCH_START);
+tl.set(copies, { opacity: SPLIT_OPACITY }, GLITCH_START);
+tl.to(
+  amp,
+  {
+    a: 0,
+    duration: GLITCH_DUR,
+    ease: "power3.in", // most of the violence up front, dying fast
+    onUpdate: () => {
+      const step = Math.floor(tl.time() / JITTER_STEP); // quantized — the stutter
+      copies.forEach((el, layer) => {
+        const jx = (glitchHash(step * 13 + layer * 7) * 2 - 1) * MAX_SPLIT * amp.a;
+        const jy = (glitchHash(step * 29 + layer * 11) * 2 - 1) * MAX_SPLIT * 0.35 * amp.a;
+        gsap.set(el, { x: jx, y: jy });
+      });
+    },
+  },
+  GLITCH_START,
+);
+// The clean resolve: clamp ghosts to exact rest — never rely on the decay
+// landing on zero. A ghost left 1px off reads as a bug every frame after.
+tl.set(copies, { x: 0, y: 0, opacity: 0 }, GLITCH_START + GLITCH_DUR);
+
+// Form B: slice displacement — N band copies of the same content converge.
+const slices = gsap.utils.toArray("#slice-stack .slice");
+const bandH = 100 / slices.length;
+slices.forEach((el, i) => {
+  gsap.set(el, { clipPath: `inset(${i * bandH}% 0 ${100 - (i + 1) * bandH}% 0)` });
+  const dir = glitchHash(i * 3 + 1) > 0.5 ? 1 : -1;
+  tl.fromTo(
+    el,
+    {
+      x: dir * (SLICE_OFFSET_MIN + glitchHash(i * 5 + 2) * (SLICE_OFFSET_MAX - SLICE_OFFSET_MIN)),
+      scaleX: 1 + glitchHash(i * 7 + 3) * SLICE_STRETCH,
+      opacity: 1,
+    },
+    { x: 0, scaleX: 1, duration: SLICE_RESOLVE_DUR, ease: "steps(SLICE_STEPS)" },
+    SLICE_START + glitchHash(i * 11 + 4) * SLICE_JITTER_LAG,
+  );
+});
+```
+
+## Variations
+
+- **Glitch-stretch entrance** — the element ENTERS glitching: layer `fromTo(stack, { scaleX: STRETCH_FROM, opacity: 0 }, { scaleX: 1, opacity: 1, duration: GLITCH_DUR, ease: "power4.out" })` (`STRETCH_FROM` 1.3–1.8) on the whole stack while the envelope runs. Stretch, split, and envelope all die at the same frame — the word is simply _there_, sharp.
+- **Emphasis burst on a held word** — a spasm, not an arrival: 2–3 short envelopes (`GLITCH_DUR` ~0.12–0.2s each) separated by clean gaps of ~0.2–0.4s, each its own `set(amp)/to(amp)/set(rest)` triplet. The clean frames between bursts make it read as energy instead of a rendering fault.
+- **Slice reveal** — Form B as the arrival itself: bands start opaque but displaced, converge under the stepped ease. Drop the color copies for the monochrome version — the restrained enterprise read of this rule.
+- **Card / non-text glitch** — the stacked-copy machinery is content-agnostic (logo lockup, small card). Keep `MAX_SPLIT` proportional (~1% of element width) — oversized splits read as broken layout, not interference.
+
+## Values
+
+| token                                        | range                                  | notes                                                                                         |
+| -------------------------------------------- | -------------------------------------- | --------------------------------------------------------------------------------------------- |
+| MAX_SPLIT                                    | 4–14px at headline sizes (~0.06–0.1em) | vertical ~35% of horizontal; base must stay legible at peak                                   |
+| JITTER_STEP                                  | 1/30–1/12 s                            | shorter = frantic buzz, longer = VHS stutter; **≥ one render frame** or quantization vanishes |
+| GLITCH_DUR                                   | 0.25–0.6s entrance; 0.12–0.2s burst    | ≥ ~1s stops reading as an event and starts reading as a broken render                         |
+| SPLIT_OPACITY                                | 0.5–0.9 (screen on dark)               | 0.35–0.6 unblended on light — screen on white is invisible                                    |
+| SLICE_COUNT                                  | 4–10                                   | more = finer tear, diminishing past ~10                                                       |
+| SLICE_OFFSET_MIN / MAX                       | 12–60px                                | derive per-band values from `glitchHash(i)`, never uniform — equal offsets read mechanical    |
+| SLICE_STRETCH                                | 0–0.5                                  | 0 pure displacement; ~0.3 stretched-scanline read                                             |
+| SLICE_RESOLVE_DUR / SLICE_STEPS / JITTER_LAG | 0.2–0.4s / 3–6 / ≤0.08s per band       | the stepped ease keeps the settle digital                                                     |
+| {warmSplit} / {coolSplit}                    | —                                      | classic red/cyan; any opposing warm+cool brand pair survives                                  |
+
+## Critical Constraints
+
+- **Quantize time — the stutter IS the effect.** Offsets hold for `JITTER_STEP` then jump; if the glitch looks like jelly, you interpolated. `JITTER_STEP` ≥ one render frame or the quantization silently disappears.
+- **Pure functions of (quantized time, index)** — every per-frame value comes from `glitchHash`; the hash inputs use `tl.time()`, nothing else.
+- **Clamp the rest state** — `tl.set({ x: 0, y: 0, opacity: 0 })` on the ghosts at envelope end; never rely on the decay landing exactly on zero.
+- **Base on top, always legible** — ghosts vibrate _behind_ the base; a glitch that destroys legibility for more than ~2 frames is a tear-down, not an accent.
+- **Brief, then clean** — the clean hold after the snap is the actual beat; `GLITCH_DUR` well under half the element's screen time. Emphasis bursts are separate finite triplets.
+- **No CSS `@keyframes` glitch loops** — the classic CSS glitch snippet runs on the wall clock and desyncs from seek; every displacement goes through the timeline's `onUpdate`.
+- **Match the register** — RGB-split is a loud consumer/tech gesture; the monochrome slice variant is the only form that belongs in a restrained enterprise composition.
+
+## See also
+
+`kinetic-beat-slam` (one beat lands with the glitch-stretch entrance) · `spring-pop-entrance` (pop clean, burst on the stress beat) · `gradient-text-sweep` (gradient carries the hold after the resolve) · `discrete-text-sequence` (state swap masked at max amplitude) · `motion-blur-streak` (the traveling sibling — if it's moving fast, blur it there).

package/dist/assets/design/skills/hyperframes-animation/rules/context-sensitive-cursor.md

@@ -0,0 +1,140 @@
+---
+name: context-sensitive-cursor
+description: Cursor color and styling that adapt to the current text segment being typed — accent color on highlights, dim on placeholders, etc.
+metadata:
+  tags: cursor, color, context, typewriter, styling, segment
+---
+
+# Context-Sensitive Cursor
+
+In a typewriter sequence, the cursor's color (and optionally height / blink behavior) matches the **active text segment** — brand accent while typing the brand name, dim on placeholders, success color on the completion mark. The eye lands on the keyword being typed because the cursor shifts with it; a fixed single-color cursor is visual noise by comparison. Layers on top of [discrete-text-sequence](discrete-text-sequence.md)'s SEQUENCE pattern.
+
+## How It Works
+
+The text is authored as a SEQUENCE of `{ t, text, segment, color }` entries; a linear driver's `onUpdate` reverse-searches for the current entry and writes both the visible text and the cursor's `background` (the cursor is a colored block, so `background`, NOT `color`). A second linear tween sweeps a phase `p` through `2π × BLINK_CYCLES_PER_SCENE` and gates cursor opacity on `sin(p) > 0` — a deterministic square-wave blink on the timeline.
+
+## Recipe
+
+```html
+<!-- inside a standard scene clip (hyperframes-core) -->
+<div class="terminal">
+  <div class="prompt">$</div>
+  <div class="text-wrap">
+    <span class="text" id="text"></span><span class="cursor" id="cursor">_</span>
+  </div>
+</div>
+```
+
+```css
+.terminal {
+  font-family: {monoFont}; /* proportional fonts drift the cursor mid-segment */
+  display: flex;
+  align-items: baseline;
+  white-space: pre; /* preserve trailing spaces — cursor sits at segment end */
+}
+.text {
+  white-space: pre;
+}
+.cursor {
+  display: inline-block; /* inline ignores width/height */
+  width: {cursorWidth}px;
+  height: {cursorHeight}px;
+  background: {textColor}; /* default — overridden per segment in onUpdate */
+  vertical-align: {cursorBaselineFix}px; /* small negative — anchor to baseline, not line-height */
+}
+```
+
+```js
+// Adjacent entries usually share a text prefix but may differ in `segment` —
+// that's what shifts the cursor color mid-line.
+const SEQUENCE = [
+  { t: 0, text: "", segment: "main", color: "{mainColor}" },
+  { t: T_LEADIN_END, text: "{leadInChunk}", segment: "main", color: "{mainColor}" },
+  { t: T_BRAND_IN, text: "{leadInBrandPrefix}", segment: "brand", color: "{brandColor}" },
+  { t: T_BRAND_OUT, text: "{leadInBrandFull}", segment: "main", color: "{mainColor}" },
+  { t: T_CMD_IN, text: "{leadInCmdPrefix}", segment: "cmd", color: "{cmdColor}" },
+  { t: T_SUCCESS, text: "{leadInDone}", segment: "success", color: "{successColor}" },
+];
+
+function entryAt(time) {
+  for (let i = SEQUENCE.length - 1; i >= 0; i--) {
+    if (time >= SEQUENCE[i].t) return SEQUENCE[i];
+  }
+  return SEQUENCE[0];
+}
+
+const textEl = document.getElementById("text");
+const cursorEl = document.getElementById("cursor");
+
+const driver = { t: 0 };
+tl.to(
+  driver,
+  {
+    t: DURATION,
+    duration: DURATION,
+    ease: "none",
+    onUpdate: () => {
+      const entry = entryAt(driver.t);
+      textEl.textContent = entry.text;
+      cursorEl.style.background = entry.color;
+    },
+  },
+  0,
+);
+
+// Deterministic square-wave blink
+const blink = { p: 0 };
+tl.to(
+  blink,
+  {
+    p: Math.PI * 2 * BLINK_CYCLES_PER_SCENE,
+    duration: DURATION,
+    ease: "none",
+    onUpdate: () => {
+      cursorEl.style.opacity = Math.sin(blink.p) > 0 ? "1" : "0";
+    },
+  },
+  0,
+);
+```
+
+## Variations
+
+- **Non-blinking during active typing** — suppress blink while letters are appearing (solid cursor), resume on idle. This MUST be a pure function of the driver's time: tracking a mutable `lastChangeTime` in `onUpdate` is not reverse-seek-safe (scrubbing backwards leaves the stale forward-pass value behind and the cursor blinks — or holds solid — at the wrong frames). Bake the change times from the SEQUENCE instead — every entry whose `text` differs from its predecessor is a typing event:
+
+```js
+// Baked once at build time — no runtime state.
+const CHANGE_TIMES = SEQUENCE.filter((e, i) => i > 0 && e.text !== SEQUENCE[i - 1].text).map(
+  (e) => e.t,
+);
+// In onUpdate — identical result at any seek, either direction:
+const isTyping = CHANGE_TIMES.some((t) => t <= driver.t && driver.t - t < TYPING_GRACE);
+cursorEl.style.opacity = isTyping ? "1" : Math.sin(blink.p) > 0 ? "1" : "0";
+```
+
+- **Cursor HEIGHT shifts on segment** — larger cursor on the brand segment: `cursorEl.style.height = entry.segment === "brand" ? cursorHeightEmphasis : cursorHeight` (1.1–1.25×; more reads as glitch).
+- **Contrast reversal** — a dark-text-on-light segment needs a dark cursor too; keep `entry.color` as the single source of truth and read from it.
+
+## Values
+
+| token                  | range                       | notes                                                                                           |
+| ---------------------- | --------------------------- | ----------------------------------------------------------------------------------------------- |
+| DURATION               | 4–8s per typed line         | `≥ SEQUENCE[last].t + closing dwell`                                                            |
+| entry `t` spacing      | 0.2–0.5s micro-additions    | ascending, non-uniform — slow down on highlights                                                |
+| segment palette        | 3–4 colors max              | more reads as random; brand vs success should differ in saturation/luminance                    |
+| cursorWidth / Height   | 8–24px / 0.85–1.0× fontSize | too thin vanishes in render compression; too tall outranks the text                             |
+| cursorBaselineFix      | small negative px           | drop the block to the text baseline                                                             |
+| BLINK_CYCLES_PER_SCENE | period ≈ 0.6–1.2s           | **whole number** — otherwise the sin sweep ends mid-cycle and the cursor pops on the last frame |
+| TYPING_GRACE           | 0.15–0.3s                   | **< shortest dwell between adjacent entries** — otherwise the cursor never blinks               |
+
+## Critical Constraints
+
+- **Cursor color goes on `background`** — it's a colored block, not a glyph.
+- **Blink is timeline-driven sin, pure of any mutable tracker** — the typing-grace variation shows the seek-safe form.
+- **`white-space: pre` on text and container** — collapsed trailing spaces park the cursor in the wrong column.
+- **Monospace font + `display: inline-block` cursor** — proportional faces drift the cursor mid-segment; inline ignores the block geometry.
+- **BLINK_CYCLES_PER_SCENE is a whole number** for the fixed DURATION.
+
+## See also
+
+`discrete-text-sequence` (the underlying SEQUENCE pattern) · `camera-cursor-tracking` (camera follows the cursor) · `press-release-spring` (post-typing confirm press).

package/dist/assets/design/skills/hyperframes-animation/rules/control-target-sync.md

@@ -0,0 +1,131 @@
+---
+name: control-target-sync
+description: The live-sync couple — a scrubbed/typed/picked control drives a second element's property in the SAME beat. Readout tween + target transform tween share one timeline label (continuous scrub), or one threshold state array carries both sides (discrete steps). Makes "change this, watch it change" read as causality.
+metadata:
+  tags: control, scrub, live-sync, mirror, panel, editor, couple, readout, ui
+---
+
+# Control-Target Sync
+
+THE live-editing move: an inspector/editor control is manipulated — a value scrubbed, a field retyped, a dropdown picked — and a **bound second element answers in the same frame**. The button rotates WHILE the rotation value scrubs; icons resize PER KEYSTROKE. The persuasion is causality — one gesture, two surfaces changing together — and this rule is the coupling contract that produces it.
+
+Nearest precedent is [reactive-displacement.md](reactive-displacement.md): that rule also derives two elements' motion from one source, but it is **collision physics** — an entering intruder displaces an exiting victim, once, as a transition, and the victim leaves. This rule is a **live editing mirror**: the control is manipulated repeatedly across several beats, the target answers every time, and both sides hold the stage throughout. The numeric readout rides [counting-dynamic-scale.md](counting-dynamic-scale.md)'s proxy pattern; discrete steps ride [discrete-text-sequence.md](discrete-text-sequence.md)'s threshold pattern — what this rule adds is the law that binds either of them to the target.
+
+## How It Works
+
+An **edit beat** is a set of concurrent tweens at ONE timeline label: `tl.addLabel("edit1", …)`, then the **readout tween** (numeric proxy + `onUpdate` writing `textContent` only) and the **target transform tween** (`rotation` / `x` / `y` / `scale` to the same endpoint), both placed at the label with the same **duration** and **ease**. The two motions are two projections of one gesture — value at 40% ⇒ target at 40%, on every frame, under any seek. That mathematical lockstep reads as "the panel is editing the page," not "two animations happen to overlap."
+
+For **discrete edits** (per-keystroke retypes, dropdown picks, unit snaps) the couple steps instead of glides: a single threshold state array carries BOTH sides — each state holds the readout text AND the target's property value — and one driver applies whichever state is active. Both sides read from the same state object, so they cannot desync.
+
+Chain 2–4 edit beats with short holds between, and end on a **landed** edit — the last value applied and holding, never a tooltip with the dropdown unopened.
+
+## Recipe
+
+```html
+<!-- Bipartite by construction: target surface + inspector panel share the frame.
+     Every scrubbed readout gets `font-variant-numeric: tabular-nums` and a fixed
+     min-width (≥ the longest value) or the panel edge jitters as digits change. -->
+<div class="target-surface">
+  <div class="target-button" id="target-button">{buttonLabel}</div>
+  <div class="preview-row">
+    <div class="preview-icon">{iconA}</div>
+    …
+  </div>
+</div>
+<div class="panel">
+  <div class="field-row">
+    <span>Rotation</span><span class="field-value" id="rotation-readout">0°</span>
+  </div>
+  <div class="field-row">
+    <span>Class</span><span class="field-value mono" id="class-readout">text-1xl</span>
+  </div>
+</div>
+```
+
+```js
+// ---- Continuous couple: ONE label; both tweens share duration AND ease ----
+tl.addLabel("edit1", EDIT1_AT);
+const rotState = { v: 0 };
+const rotReadout = document.getElementById("rotation-readout");
+tl.to(
+  rotState,
+  {
+    v: ROT_TARGET,
+    duration: SCRUB_DUR,
+    ease: SCRUB_EASE,
+    onUpdate: () => {
+      rotReadout.textContent = `${Math.round(rotState.v)}°`;
+    },
+  },
+  "edit1",
+);
+tl.to(
+  "#target-button",
+  { rotation: ROT_TARGET, duration: SCRUB_DUR, ease: SCRUB_EASE },
+  "edit1", // same label — the mirror answers in the same frame
+);
+
+// ---- Discrete couple: ONE state array carries BOTH sides ----
+const STEPS = [
+  { t: 0.0, text: "text-1xl", scale: 1.0 }, // must equal the initial state
+  { t: 0.4, text: "text-4xl", scale: 1.9 },
+  { t: 1.0, text: "text-xl", scale: 0.85 }, // backspace
+  { t: 1.35, text: "text-2xl", scale: 1.3 }, // lands
+];
+const stepAt = (time) => [...STEPS].reverse().find((s) => time >= s.t) ?? STEPS[0];
+
+tl.addLabel("edit3", EDIT3_AT);
+const classReadout = document.getElementById("class-readout");
+const stepDriver = { t: 0 };
+let lastStep = null;
+tl.to(
+  stepDriver,
+  {
+    t: STEPS_TOTAL,
+    duration: STEPS_TOTAL,
+    ease: "none",
+    onUpdate: () => {
+      const s = stepAt(stepDriver.t);
+      if (s !== lastStep) {
+        classReadout.textContent = s.text; // control steps
+        gsap.set(".preview-icon", { scale: s.scale }); // target steps — same state object
+        lastStep = s;
+      }
+    },
+  },
+  "edit3",
+);
+```
+
+## Variations
+
+- **Dropdown pick → instant conversion (self-conversion)** — the pick converts the panel's own readout in place (`tl.set("#padding-readout", { textContent: "6 px" }, "pick")`); control and target collapse into one element. Compose the dropdown from neighbors: menu pops via [spring-pop-entrance.md](spring-pop-entrance.md), row hover-stepping via [dynamic-content-sequencing.md](dynamic-content-sequencing.md). The conversion must be an INSTANT snap — tweening between unit strings reads as broken, and instantness is the feature being sold.
+- **Easing-handle drag → target re-animates (deferred mirror)** — the edit authors a _behavior_, so the mirror is a **replay**, not a concurrent transform: beat 1 drags the handle (handle tween + coords readout), then at a later label the target performs its motion with the newly-authored curve (`tl.fromTo("#toggle-knob", { x: 0 }, { x: KNOB_TRAVEL, duration: REPLAY_DUR, ease: AUTHORED_EASE }, "replay")`), often under a zoom-out ([viewport-change.md](viewport-change.md)). The one sanctioned case where the response is not in the gesture's beat; the replay must still be unmistakably the edited parameter.
+- **Read-sync mirror (reverse direction)** — the gesture happens ON the target (hovering swatches, selecting an element) and the PANEL readout is the bound side. Same discrete contract — one state array of `{ t, hoverTarget, readout }` drives both the highlight and the text.
+- **Color couple** — the readout counts (`0 → 80`) while the target's `backgroundColor` tweens between two palette stops at the same label. Keep it two fixed stops (GSAP interpolates); never derive per-frame hex strings by hand.
+
+## Values
+
+| token                | range                           | notes                                                                                                                                 |
+| -------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| SCRUB_DUR            | 0.8–1.6 s                       | the viewer must see BOTH sides move — under ~0.6 s the mirror registers subconsciously at best                                        |
+| SCRUB_EASE           | `power1.inOut` / `power2.inOut` | shared verbatim by both tweens. Never `back.out` / `elastic.out` — an overshooting value reads as a broken hinge; the readout is data |
+| edit endpoints       | visible but plausible           | −10° tilt, 38 px shift, 1xl → 4xl → 2xl; a 2° rotation doesn't demo anything                                                          |
+| HOLD_BETWEEN         | 0.3–0.8 s                       | each landed value gets a breath; below 0.3 s the beats smear into one gesture                                                         |
+| BEAT_COUNT           | 2–4                             | one edit is a moment, not a demo; past 4 the shot reads as a settings tour                                                            |
+| STEP gaps (discrete) | 0.15–0.5 s                      | keystroke pacing per discrete-text-sequence; first state must equal the on-load state                                                 |
+| VALUE_MIN_WIDTH      | ≥ longest value's width         | without it the panel edge jitters as digit counts change                                                                              |
+
+## Critical Constraints
+
+- **One label, one gesture** — readout tween and target tween share position, duration, AND ease; never sequence readout-then-target, and never stagger the target behind the readout even by 0.1 s — a delayed response reads as an animation following an edit, not a bound surface. A mismatched ease desyncs the mirror mid-tween even when endpoints agree.
+- **Discrete steps share one state object** — both sides read the same array entry, so desync is impossible by construction; first entry mirrors the initial DOM state.
+- **The readout is data** — no overshoot, no bounce on the settle; the target may carry the gesture's ease but lands exactly on the edited value.
+- **Co-visibility is load-bearing** — control and target share the frame for every edit beat; a camera move must never crop the mirror out (punch-and-return around the beats, not through them).
+- **`tabular-nums` + fixed `min-width`** on every scrubbed readout; `onUpdate` is O(1) — text writes only, discrete drivers guard writes with a last-state check.
+- **End on a landed edit** — the final beat resolves with the value applied and holding (or the deferred-mirror replay); never mid-gesture or on an unopened menu.
+- **The gesture's actor is a separate rule** — cursor glide, grab-cursor flip, and click feedback come from the cursor rules; this rule owns only the couple.
+
+## See also
+
+`cursor-click-ripple` / `context-sensitive-cursor` (the hand performing the gesture) · `counting-dynamic-scale` (the readout half alone, when there is no bound target) · `discrete-text-sequence` (retypes inside the control field) · `spring-pop-entrance` (dropdowns/chrome around the couple) · `multi-phase-camera` (punch-and-return framing) · `chart-scrub-readout` (the sibling READ direction — a scrub interrogates a chart instead of editing a target).

package/dist/assets/design/skills/hyperframes-animation/rules/coordinate-target-zoom.md

@@ -0,0 +1,138 @@
+---
+name: coordinate-target-zoom
+description: Zoom into a specific non-centered element by combining scale with counter-translation — target ends at viewport center after the zoom completes.
+metadata:
+  tags: camera, zoom, scale, translate, target, off-center, focus
+---
+
+# Coordinate Target Zoom
+
+A simple `scale > 1` on a wrapper pushes off-center content OFF the visible canvas. To zoom _into_ a specific non-centered element, apply scale AND an inverse translation in lockstep so the target lands at viewport center.
+
+## How It Works
+
+Two nested wrappers, separated concerns — never scale and translate on the SAME element (`translate * scale` ≠ `scale * translate` in CSS transform composition):
+
+1. **Outer wrapper** applies `scale` (the zoom) around `transform-origin: 50% 50%`
+2. **Inner wrapper** applies `translate(x, y)` (the counter-shift)
+
+The counter-translate is the **negation** of the target's offset from viewport center:
+
+```
+T = -offset
+```
+
+Derivation: the inner translate moves the target to `offset + T` in pre-scale units; the outer scale S (around center) maps that to `S × (offset + T)`; landing at center means `S × (offset + T) = 0` → **`T = -offset`**. The formula does NOT depend on S — the translate is identical at 1.5×, 2×, or 3×. A common wrong intuition is `T = -offset × (S - 1)`: it coincidentally matches at S = 2 and is wrong at every other scale.
+
+UNVERIFIABLE **This is the NESTED-wrapper formula.** The single-wrapper camera in [viewport-change.md](viewport-change.md) puts `translate(x,y) scale(S)` on ONE element, where CSS applies scale first — there the counter-translate is **`T = -offset × S`**. The two formulas are not interchangeable; match the formula to the wrapper structure.
+
+## Getting the offset
+
+`T = -offset` is only as good as `offset`. The #1 way this pattern ships broken is hand-computing `offset` from a layout formula, getting the **sign** or magnitude wrong, and letting the zoom amplify a small error off-screen. **Default to measuring the target's real laid-out center; reserve the formula for symmetric rows.**
+
+**Default — measure the actual center (works for ANY layout).** Immune to sign errors because it reads the rendered DOM, not a mental model:
+
+```js
+await document.fonts.ready; // metrics final; fallback fonts are 10–30px off → tens of px after a 3×+ zoom
+const W = 1920,
+  H = 1080;
+const r = document.getElementById("target-card").getBoundingClientRect();
+const TARGET_OFFSET_X = r.left + r.width / 2 - W / 2;
+const TARGET_OFFSET_Y = r.top + r.height / 2 - H / 2;
+```
+
+Measure **once at setup** and bake — never per-frame in `onUpdate`. Because the measurement is async (`fonts.ready`), build and register the timeline inside the same `async` setup so the baked offset is ready before `window.__timelines[id]` is published.
+
+**Shortcut — symmetric equal-width row ONLY:**
+
+```js
+const index_offset = targetIndex - (N - 1) / 2;
+const TARGET_OFFSET_X = index_offset * (CARD_WIDTH + CARD_GAP);
+```
+
+UNVERIFIABLE This assumes every sibling is the **same width**. The moment the row is asymmetric, it gives the wrong answer — often the wrong **sign**: the heavier side shifts the centered target the _opposite_ way you'd guess (e.g. `companion(220) + gap + wordmark + gap + chip(110)` puts the wordmark ~55px **right** of center, but "chip − companion" intuition says left). For anything but equal cards, **measure**.
+
+**Headroom budget — cap the scale from the measured size.** A zoom multiplies any centering error; keep the target ≤ ~88% of the canvas at peak:
+
+```js
+const maxScale = Math.min((0.88 * W) / r.width, (0.88 * H) / r.height);
+const ZOOM_SCALE = Math.min(DESIRED_SCALE, maxScale);
+```
+
+A target filling 97%+ of the frame reads as cut-off the instant its center is slightly off — and a hand-baked offset always is. (The perception gate flags this as `primary-offscreen`; `data-layout-allow-overflow` does **not** exempt it.)
+
+## Recipe
+
+```html
+<div class="zoom-outer" id="zoom-outer">
+  <div class="zoom-inner" id="zoom-inner">
+    <div class="content">
+      <div class="card">{other}</div>
+      <div class="card target" id="target-card">{target}</div>
+      <div class="card">{other}</div>
+    </div>
+  </div>
+</div>
+```
+
+```css
+.scene {
+  overflow: hidden; /* REQUIRED — at zoom > 1 the scaled content leaks past the frame */
+}
+.zoom-outer {
+  width: 100%;
+  height: 100%;
+  display: grid;
+  place-items: center;
+  transform-origin: 50% 50%; /* center scaling is what the counter-translate math assumes */
+  will-change: transform;
+}
+.zoom-inner {
+  display: grid;
+  place-items: center;
+  will-change: transform;
+}
+```
+
+```js
+// TARGET_OFFSET_X/Y and ZOOM_SCALE come from "Getting the offset" — measured
+// at setup (after fonts.ready), baked. Counter-translation = -offset.
+const counterX = -TARGET_OFFSET_X;
+const counterY = -TARGET_OFFSET_Y;
+
+// Scale and counter-translate MUST share position, duration, AND ease —
+// otherwise the target visibly wanders mid-zoom.
+tl.to("#zoom-outer", { scale: ZOOM_SCALE, duration: ZOOM_DUR, ease: "power3.inOut" }, ZOOM_AT);
+tl.to(
+  "#zoom-inner",
+  { x: counterX, y: counterY, duration: ZOOM_DUR, ease: "power3.inOut" },
+  ZOOM_AT,
+);
+```
+
+## Variations
+
+- **Zoom out (target → wide view)**: reverse the phases — start zoomed-in, then tween to `scale: 1` + `x: 0, y: 0`; the "reveal" beat is the panorama.
+- **Multi-target zoom sequence**: chain zooms (target A → pause → target B → pull back); each segment needs its own counter-translation pair.
+
+## Values
+
+| token      | range                                   | notes                                                                                      |
+| ---------- | --------------------------------------- | ------------------------------------------------------------------------------------------ |
+| ZOOM_SCALE | 1.5× modest → 3× dominant → 5×+ extreme | cap via the headroom budget; raster media needs `sourceResolution ≥ rendered × ZOOM_SCALE` |
+| ZOOM_DUR   | 1.0–2.0s                                | under 0.8s feels like a teleport, over 2.5s drags; both tweens share it                    |
+| ZOOM_AT    | after the layout lands + 0.5–1.5s       | give the viewer time to scan the layout before the camera commits                          |
+| DWELL      | ≥ 1.0s after the zoom settles           | 1.5–2s ideal — the viewer must be able to read the target (climax dwell)                   |
+
+## Critical Constraints
+
+- **Outer scales, inner translates** — never both transforms on one element; nested wrappers keep the math clean.
+- **`transform-origin: 50% 50%` on the outer wrapper** — non-center origin breaks the counter-translate derivation.
+- **`overflow: hidden` on the scene root** — zoomed content leaks past the frame otherwise.
+- **Scale and counter-translate share duration + ease** at the same timeline position, or the target drifts mid-zoom.
+- **Offset measured once at setup** (after `fonts.ready`), baked — never recomputed per-frame, never hand-derived for a non-symmetric layout (wrong sign → target shoved off-frame).
+- **Scale within the headroom budget** — target ≤ ~88% of the canvas at peak, derived from the measured size.
+
+## See also
+
+[viewport-change.md](viewport-change.md) (single-wrapper form, `T = -offset × S`) · [multi-phase-camera.md](multi-phase-camera.md) (a zoom phase inside a phased camera) · [sine-wave-loop.md](sine-wave-loop.md) (idle breathing after the zoom settles) · [discrete-text-sequence.md](discrete-text-sequence.md) (text assembly in the target before the zoom).