Setting the file. One moment.
Skill 18 · Hyperframes Animation
Subchapter 18.72
rules/coordinate-target-zoom.mdMarkdown7 KBView on GitHub
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.
Two nested wrappers, separated concerns — never scale and translate on the SAME element ( ≠ in CSS transform composition):
translate * scalescale * translatescale (the zoom) around transform-origin: 50% 50%translate(x, y) (the counter-shift)The counter-translate is the negation of the target’s offset from viewport center:
T = -offsetDerivation: 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.
⚠️ This is the NESTED-wrapper formula. The single-wrapper camera in 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.
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:
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:
const index_offset = targetIndex - (N - 1) / 2;
const TARGET_OFFSET_X = index_offset * (CARD_WIDTH + CARD_GAP);⚠️ 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:
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.)
<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>.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;
}// 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,
);scale: 1 + x: 0, y: 0; the “reveal” beat is the panorama.| 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) |
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.fonts.ready), baked — never recomputed per-frame, never hand-derived for a non-symmetric layout (wrong sign → target shoved off-frame).viewport-change.md (single-wrapper form, T = -offset × S) · multi-phase-camera.md (a zoom phase inside a phased camera) · sine-wave-loop.md (idle breathing after the zoom settles) · discrete-text-sequence.md (text assembly in the target before the zoom).