@autoaiai/aicut 0.1.11 → 0.1.13

package/skills/motion-graphics/references/craft.md

@@ -1,136 +0,0 @@
-# Craft: type, motion, and the recurring element
-
-## Optical centering
-
-Centering the layout box leaves text sitting low, because the box carries ascender and descender space that nobody perceives. Centre the **ink**: cap top of the first line to baseline of the last.
-
-`MG.opticalCenter()` does this with real font metrics from canvas `measureText`:
-
-```js
-const m = mctx.measureText('H');
-baseline = (lineHeight - (m.fontBoundingBoxAscent + m.fontBoundingBoxDescent)) / 2 + m.fontBoundingBoxAscent;
-cap      = m.actualBoundingBoxAscent;
-```
-
-Measured on a real piece before the fix, scenes sat 28–41px below centre in a 1080 frame. Nobody could name it; everybody felt it.
-
-**Whether a rule or underline counts** depends on its role:
-
-- Fixed part of the lockup (under a logo, under a URL) → include it. Otherwise the composition is bottom-heavy by half the rule's overhang.
-- A highlight that moves from line to line → exclude it. Include it and the framing shifts depending on where the highlight happens to be parked.
-
-## Type that fills its measure
-
-Short lines in a big frame look like a mistake. Two checks worth doing numerically:
-
-**Does the text fill the measure?** Sum the token widths, not the `.line` box — a block element reports the container width, and if a camera scale is active you will read that scaled. At one point three lines of 84px type left 413px of empty frame; at 112px the first line filled 756 of 880 and the scene stopped looking broken.
-
-**Is the hierarchy right?** If a small supporting line ends up the *widest* element on screen, the hierarchy is inverted and it reads as unbalanced no matter what else you do. Shorten it or enlarge the headline until the primary line is clearly the widest.
-
-## Leading, spacing, and where a rule fits
-
-**Uniform leading, sized so a highlight fits in any gap.** Giving extra margin only to the underlined line makes that line breathe differently from the rest — someone will say "the underlined text takes up more space" without knowing why. The gap should be identical whether the rule is there or not: the rule lives in the gap, it does not create it.
-
-**Word gaps are margin, not text nodes.** An inline-block containing only a space collapses to zero and the words come out glued together. Use `margin-right` on the token, zero it before punctuation, and zero it on the last token of a line — otherwise a trailing margin shifts centred lines off-centre.
-
-Strip that last margin in JS rather than with `:last-child`, because with grouped targets (`*{two words}`) the last token of the *group* is also `:last-child` of its wrapper and would eat the space before the next word.
-
-## Choosing a motion language
-
-Pick one way things arrive and one way they leave, and hold to it across the whole piece. Mixing them is the most common reason work looks amateur, and it is invisible while you build scene by scene.
-
-The choice is about tone. Six that cover most briefs, all in `MG.ENTER` / `MG.EXIT`:
-
-**`speed`** — arrives fast with a directional smear and brakes hard. Urgency, sport, news, anything about being quick. Loud; wears out on long pieces.
-
-**`pop`** — grows from nothing and overshoots. Playful, consumer, product. Reads friendly, reads cheap if overdone.
-
-**`wipe`** — a hard edge uncovers it and nothing moves. Editorial, architectural, confident. The most restrained option that still has energy, and the best default when the type itself is the point.
-
-**`drift`** — barely moves; the fade does the work. Premium, calm, serious. Needs slower timings all round or it looks like nothing happened.
-
-**`rise`** — comes up out of its own baseline behind a mask. Cinematic titles. Requires `overflow: hidden` on a wrapper per line.
-
-**`focus`** — resolves from blurred. Photographic, dreamy. Expensive to render; check the frame rate before committing.
-
-Two levers change the feel more than the language does:
-
-**Stagger unit.** Per-letter is energetic and becomes exhausting past a few words. Per-word is the middle. Per-line is calm and is usually right for sentences. The same `pop` staggered per-letter and per-line are two different pieces.
-
-**Duration ratio.** An entrance that is 60% of the hold reads as busy; 25% reads as composed.
-
-### Directional smear
-
-If the language is `speed`, the blur has to be directional — `filter: blur()` is isotropic and wrong for linear motion. Offset copies in a shadow list give the direction, and shadow lists interpolate between keyframes so it animates for free.
-
-`MG.trail(size, k, {dx, dy, colour})` takes a direction and a colour. Both matter: the trail belongs *behind* the motion, so it flips when the object does, and a hardcoded dark trail is invisible on a dark background.
-
-There is a better and costlier option: render several subframes per output frame and average them in ffmpeg with `tmix`. That is true motion blur in every direction at once, at N× the capture time. Worth it for a hero piece.
-
-### What holds regardless of language
-
-**Arrivals decelerate, departures accelerate.** Matching curves makes everything rubbery.
-
-```js
-brake  = cubic-bezier(.12,.85,.25,1)     // arrivals
-launch = cubic-bezier(.55,0,.9,.35)      // departures
-breath = cubic-bezier(.45,0,.55,1)       // anything continuous
-```
-
-**Chained ease-outs read as stop-start.** Every segment decelerates to zero and the next starts fast. For anything continuous, ease-in-out.
-
-**For large type, scale the exit down.** Exit distance is proportional to font size, so at 112px the default sweep crosses half the screen and collides with the next scene. A factor around 0.55 keeps the language at a fraction of the distance.
-
-**Nothing should ever be perfectly still.** A frame that holds motionless for two seconds reads as *stuck*. This is easy to misdiagnose: on a real piece the complaint was "it feels janky", and the measurement showed **zero dropped frames** at a median of 8.3ms. It was not performance. It was that scenes had no camera, so between entrance and exit the image was frozen.
-
-Every scene gets a slow push: settle over ~1.5s, then keep drifting to about 1.007 by the time it leaves. At 1.014 people report things "levitating".
-
-**Overlap, but not too much.** Scenes overlap — the outgoing text is still leaving as the next arrives — and that is what makes it flow. But when the two are at very different type sizes, a big smear draws over the small type underneath and reads as a mistake. The right gap is not a constant: it depends on the exit duration plus the stagger. Widen it until the frame actually clears, and check by rendering the transition rather than by arithmetic.
-
-### On dark backgrounds
-
-Three things break quietly:
-
-- A trail with a hardcoded dark colour simply does not exist. Pass `{colour:'255,255,255'}`.
-- Large flat dark areas band. A static grain layer at around 5% opacity fixes it.
-- Two stacked vignette gradients draw the edge of the ellipse, very visible in 9:16. Use one.
-
-## A recurring element as the spine
-
-One element that persists across every scene is the cheapest way to make a sequence feel composed rather than assembled. The form is open — a rule under the key word, a dot, a cursor, a shape that reframes each card, a mask edge that wipes between them. What follows uses a travelling rule as the worked example because the geometry is easy to talk about, but the principles transfer.
-
-Treat it as a character, not a graphic. Some things that make that work:
-
-**Constant thickness.** Draw it 100px wide and resolve the real width with `scaleX`, so the thickness never changes wherever it goes.
-
-**Rotate on its axis.** `transform-origin: center`, not `left`. A rectangle tilted two degrees reads as a head turning; it is the cheapest expressive lever available and the single thing that turns a bar into a character.
-
-**Ask for tilt in pixels, not degrees.** A 300px bar and a 78px bar must lean the *same amount visually*; with a fixed angle the short one is imperceptible.
-
-```js
-const tilt = px => Math.min(8, Math.atan2(px, width / 2) * 180 / Math.PI);
-```
-
-**Stretch by edges, not from the centre**, when the targets share an edge. Left-aligned lines all start at the same x and differ only in where they end. Stretching from the centre pushes both ends, so reaching a long item also grows leftward — off the frame. Interpolate the left and right edges independently and let the travelling edge carry the stretch.
-
-**Weight on landing.** Overshoot, stretch on the way, rebound twice, settle. Squash and stretch, but on the X axis only — thickening the bar is cartoon vocabulary and clashes with a speed-based language.
-
-**An idle vocabulary** for when it waits: breathe, twitch, look (tilt and hold), nod, yawn, shiver. Draw them from a shuffled deck rather than sampling independently, so no two waits look the same and none is only breathing. End long waits with a slow settle — contract slightly, tilt, sink — so the next move reads as waking up.
-
-**Seed the randomness.** With `Math.random()` the preview and the export are different films, and so is every re-render.
-
-**Stop when the scene stops.** Once the piece has landed its final beat, it should be still. Idle gestures during the closing frame read as noise exactly when attention should be on the payoff. "Still" here still includes the camera's global drift — that is fine, it moves everything together.
-
-## Two things that look right and are not
-
-**An element that crosses text reads as a rendering bug**, even when the copy explicitly calls for a strikethrough — and even when the strike is typographically well placed at a third of cap height above the baseline. It also contradicts the rule that keeps it behind the type. If a line needs negating, let the gesture do it — park under the word and shake.
-
-**An element that flies past a line without stopping reads as a blink.** Either stop on it — three deliberate stops down a three-line block reads as following the reading — or make the transit short and let the letters cut through it. What does not work is a fast pass at full size across a line it never lands on.
-
-## When the words are the problem
-
-If you are writing copy too and two rounds of alternatives all feel wrong, stop generating options. The words are usually fine; the *slot* has no defined job. Ask what that beat is for — name the problem, answer the objection, show proof, make the promise — and the line tends to write itself.
-
-A defensive beat (security, guarantees, risk) dropped into the middle of a persuasive sequence will feel wrong no matter how well phrased, because it interrupts the momentum. That is a structural problem, not a wording one.
-
-And when someone says a section is "too slow", scale its whole sequence by a factor rather than trimming one hold. The internal rhythm is usually right; there is just too much of it.

package/skills/motion-graphics/references/engine.md

@@ -1,130 +0,0 @@
-# The timeline engine
-
-## Why paused WAAPI and not something else
-
-| Approach | Why not |
-| --- | --- |
-| CSS animations | Run on wall-clock time. You cannot ask for frame 847. |
-| GSAP / anime.js | Seekable, but a dependency, and you still hand-roll the export. |
-| After Effects / Rive | Not code. Not diffable, not scriptable, not re-renderable from a prompt. |
-| Screen recording | Non-deterministic. Drops frames, varies by machine, cannot re-render at another size. |
-
-Paused WAAPI gives seekability with zero dependencies, and — the part people underrate — it makes the animation *queryable*. You can put the piece at t=7.2 and read a `getBoundingClientRect()`. Every verification technique in `verify.md` depends on that.
-
-## Absolute time
-
-`tl()` takes keyframes in absolute seconds and converts them to `delay` + `duration` + fractional offsets. That means `seek(t)` is `currentTime = t` for every animation, with no bookkeeping.
-
-Because `fill: 'both'` is set, an element holds its first keyframe before its delay and its last one after. So a single animation genuinely describes the element's whole life.
-
-## The four failure modes, in depth
-
-### 1. Two animations, one property
-
-```js
-beat(el, tIn, null);          // entrance, fill:both
-tl(el, [exit keyframes]);     // exit, fill:both      ← collides
-```
-
-Both fill backwards. The later-created animation has higher composite order, so *its* first keyframe applies from time zero. If that keyframe says `opacity: 1`, the element is on screen for the entire piece.
-
-The symptom is confusing because it presents as a *content* bug — the closing logo visible behind scene two — rather than an animation bug. If you see something from a later scene bleeding into an earlier one, count the animations on that element before anything else.
-
-Same rule applies to a travelling element: one element, one animation, all its moves in one list. That is what `Track` is for.
-
-Different properties on the same element are fine — a `z-index` animation alongside a `transform` animation does not collide.
-
-### 2. seek() without pause
-
-```js
-function seek(s){ A.forEach(a => a.currentTime = s * 1000); }   // wrong
-```
-
-If a preview loop is running, the animations are *playing*. You set the time, control returns to the browser, several milliseconds elapse, and the screenshot captures a slightly later moment. In a preview that is invisible. In an export it silently offsets every single frame, and the video looks fine — which is what makes it dangerous.
-
-Pause first, and cancel the preview loop the first time an external seek arrives, or it will fire mid-export and start playback again.
-
-### 3. Non-monotonic keyframes
-
-Chaining moves by hand ("this one at t+0.3, then that one at t+0.5") eventually schedules something before the previous move finished. WAAPI throws `Offsets must be monotonically non-decreasing` for the *whole animation*, naming nothing.
-
-`Track.push` clamps with `Math.max(t, last)`. Times in your script become intentions: too early degrades to "immediately after".
-
-This bites twice. The second time is when you assemble a track out of several sequences — a shared camera built from per-scene windows, say. If one scene runs longer than planned its window overlaps the next, and the assembled list is out of order. Clamp there too:
-
-```js
-bk.push({ t: Math.max(prev, Math.min(prev + .45, next.t0 - .01)), ... });
-```
-
-### 4. Measuring after animating
-
-`fill: 'both'` applies immediately, so once the animations exist every rect includes a transform. Anything you measure then is wrong.
-
-Fixed order: **build DOM → optically centre → measure targets → create animations.** If a later stage needs a measurement, take it in the measuring stage and keep it.
-
-## Porting CSS keyframes faithfully
-
-If you are reproducing an existing CSS animation, port it *literally*, including the parts that look like oversights. Three details that changed the result when they were "cleaned up":
-
-**A keyframe that omits a property is not the same as one that repeats it.** In
-
-```css
-0%   { opacity:0; transform: translateX(-1.45em) scaleX(1.55); }
-28%  { opacity:1; }                       /* no transform */
-68%  { transform: translateX(.055em) scaleX(.955); }
-```
-
-the transform interpolates 0% → 68% in one stretch. Adding a transform at 28% changes the trajectory. `tl()` preserves omissions — just leave the property out of that step.
-
-**`em` resolves against the element the animation is on, not the visual size of the thing.** A camera on a wrapper that never sets `font-size` gets the document's 16px, so `translateX(.10em)` is 1.6px — not 16.7px as it would be inside a 167px headline. Reproducing the "intended" value moved the scene 15px.
-
-**Ancestors count.** If the original had the mark nested *inside* the element the camera scales, it is scaled too. Reproduce the containment or replicate the transform on its layer.
-
-Every one of these was found by a pixel diff, not by looking.
-
-## Camera and shared tracks
-
-The camera goes on the full-canvas scene element, not on the text block. Two reasons:
-
-- Its centre is the canvas centre, so any other full-canvas layer can reuse the *identical* transform string and stay locked to the type. Put it on the text block and a left-aligned scene scales about its own centre, which no other layer can match.
-- Scenes are `inset: 0`, so this works at any canvas height.
-
-Because the content inside a scene is optically shifted by `dy`, scaling about the canvas centre displaces it by `(1-s)·dy`. The `cameraKeyframes` helper cancels that with a `translateY` term, so the push happens about the content's own centre without moving the transform origin. With dy = 31px and a 3% scale that is ~0.9px — small, and exactly the kind of thing a pixel diff catches and an eye does not.
-
-## Layering
-
-The recurring mark belongs **behind** the text (`z-index` below the scenes). When it moves between lines it has to cross the line in between; in front that reads as a strikethrough — a rendering bug — while behind, the letters cut through it and it reads as passing underneath.
-
-If some moment genuinely needs it in front (covering something up), animate `z-index` — it interpolates discretely, which is what you want:
-
-```js
-tl(overlay, [
-  { t: 0,        zIndex: '0', ease: 'linear' },
-  { t: cover - .01, zIndex: '0', ease: 'linear' },
-  { t: cover,    zIndex: '2' }
-]);
-```
-
-Keep it below any full-canvas overlay such as a vignette, or it will render on top of the grade.
-
-## Deriving times instead of hard-coding them
-
-Scenes whose length depends on a sequence of moves should publish their end time rather than have it guessed:
-
-```js
-let t = arrive(start, targets[0]);
-targets.slice(1).forEach(g => { t = hop(t + .16, g); });
-const sceneOut = t + .3;                 // the scene is as long as the moves need
-```
-
-Hard-coded times made a five-item list end after three items, because the moves grew and the scene did not. Derive downstream times from `sceneOut`.
-
-The counterweight: scenes that are structurally alike should *be* alike. A scene twice as long as its neighbours reads as a mistake even when its content earns the time. Same shape, same duration, same gap — then the piece feels composed rather than assembled.
-
-Expose the derived times for the verification scripts:
-
-```js
-window.__times = { ...T, sceneOut, end };
-```
-
-Verification scripts that hard-code timestamps go stale the first time you retime anything, and then report failures that are not there.

package/skills/motion-graphics/references/export.md

@@ -1,67 +0,0 @@
-# Export
-
-`scripts/export.js` renders every aspect ratio and works unchanged for any piece exposing `window.__seek` and `window.__duration`.
-
-```sh
-npm i playwright && npx playwright install chromium
-node export.js            # 1:1, 4:5 and 9:16
-node export.js 9x16       # one
-FPS=30 CRF=20 node export.js
-```
-
-## Aspect ratios: change the canvas, never pad
-
-Keep the width fixed (1080) and vary only the canvas **height**, read from a query parameter:
-
-```js
-const ALTO = Math.round(+new URLSearchParams(location.search).get('h') || 1080);
-```
-
-Padding a square with flat colour is the obvious shortcut and it is wrong whenever anything reaches the frame edge. A vignette arriving at the border at ~4.5% black meets flat background and leaves a visible seam. A taller canvas puts the gradient across the whole frame and the composition simply gets more room.
-
-Everything that referenced the canvas centre has to follow — optical centering uses `ALTO/2`, and the fit calculation becomes `min(innerWidth/1080, innerHeight/ALTO)`. Then verify the centring is identical across formats; it should come out the same to within a few pixels.
-
-| | Size | Where |
-| --- | --- | --- |
-| 1:1 | 1080×1080 | LinkedIn, Instagram feed, Facebook, X |
-| 4:5 | 1080×1350 | Instagram and LinkedIn feed — more height on mobile |
-| 9:16 | 1080×1920 | Reels, Stories, TikTok, Shorts |
-
-A square composition centred in 9:16 leaves large empty margins. That is normal and correct — platform UI occupies those areas — and scaling the content up is not an option without a redesign, since it already fills the width.
-
-## Encoder flags that decide whether the file works
-
-```
--c:v libx264 -pix_fmt yuv420p -crf 17 -preset slow
--f lavfi -i anullsrc=channel_layout=stereo:sample_rate=44100 -shortest -c:a aac -b:a 96k
--movflags +faststart
-```
-
-- **`yuv420p`** — x264 defaults to a chroma format that platforms and QuickTime will not decode. This is the single most common reason an exported file "does not work".
-- **`+faststart`** — moves the index to the front. Without it, playback waits for the whole file to download; in a feed that decides whether anyone sees it.
-- **Silent audio track** — some platforms reject video-only uploads outright. `anullsrc` plus `-shortest` costs nothing.
-- **CRF 17** — visually lossless for flat graphics. A 24-second 1080×1080 piece lands around 3 MB.
-
-60fps is worth it for fast motion with trails. 30fps roughly halves the file if that matters more.
-
-## The Playwright trap
-
-```js
-await page.screenshot({ animations: 'disabled' });   // never
-```
-
-That option does not freeze anything. It **fast-forwards every animation to its end state**, so all N frames come out identical. The timeline is already paused; passing it is the bug.
-
-## Checking the output
-
-```sh
-ffprobe -v error -select_streams v:0 \
-  -show_entries stream=width,height,r_frame_rate,pix_fmt \
-  -show_entries format=duration -of csv=p=0:nk=1 out.mp4
-```
-
-Confirm the dimensions, `yuv420p`, the frame rate, the duration against `window.__duration`, and that an audio stream exists. Cheap, and it catches a bad render before an upload does.
-
-## Timing
-
-Roughly 1400 frames per format for a 24-second piece at 60fps, about 60–90 seconds of capture each plus encoding. Run it in the background and do something else. If you change the animation mid-export, kill it and restart — half the frames will be from the old version and the seam is not obvious.

package/skills/motion-graphics/references/physics.md

@@ -1,100 +0,0 @@
-# Physics: when to integrate instead of ease
-
-## The rule
-
-An easing curve is a *shape*, not a simulation. `ease-out` decelerates; a falling object accelerates. For anything thrown, dropped, bounced or toppled, integrate the motion at a fixed `dt` and emit the sampled points as keyframes with `linear` easing between them. The sampling carries the curve.
-
-The same applies to departures. Something pulling away — a vehicle, a launch — starts slow and builds, which is `x = ½at²`; `ease-out` does the exact opposite and `ease-in` only approximates it. Integrate with a constant acceleration and a speed cap, and scale the motion trail by `v/vmax` so the smear grows with the speed — the trail sits *behind* the motion, so flip its offsets with the direction. Which direction is not free either: if the object came to rest in some orientation, it now has a facing, and driving the other way reads as reversing. Mirror the whole departure off a single `dir` so it stays consistent. Add the two beats that sell it: a weight-transfer squat before moving, and a couple of rocking oscillations that go nowhere before it grips.
-
-```js
-const dt = 1/240;                 // finer than the frame rate: bounces are brief
-let x = x0, y = y0, vx = v0x, vy = v0y, t = 0;
-const pts = [];
-while (t < limit){
-  t += dt;
-  vy += g * dt;  y += vy * dt;  x += vx * dt;
-  pts.push({ t: t0 + t, x, y });
-}
-tl(el, pts.map(p => ({
-  t: p.t,
-  transform: `translate(${p.x.toFixed(2)}px, ${p.y.toFixed(2)}px)`,
-  ease: 'linear'
-})));
-```
-
-Around 120 keyframes for a second of motion is fine. Values that work as a starting point for a hand-sized object in a 1080 frame: `g ≈ 4400 px/s²`, launch `vy ≈ -1150 px/s`, restitution `≈ 0.46`.
-
-## Boxes and discs are different solvers
-
-`PHYS.drop()` models a **rectangle** — corner contact, and a topple that ends with a face lying flat. `PHYS.roll()` models anything **round** — the contact height is the radius at any angle, so there is no topple: it bounces, then rolls, then friction stops it.
-
-Running a disc through the box solver produces something that rises and falls with every rotation, because the solver thinks the contact height changes as it spins. It looks wrong and the cause is not obvious from the animation.
-
-For the disc, the impact also couples spin to the surface through a tangential impulse. That is what makes a coin read as a coin rather than as a bouncing ball with a texture on it.
-
-## How many bounces
-
-`stop` — the vertical speed below which bouncing ends — is a **directorial** control, not an implementation detail. It is the knob that decides "bounces twice" against "bounces five times", which is usually the thing the brief actually specifies. Default 90 px/s; raise it for fewer bounces.
-
-## Contact with rotation
-
-If the object spins, the axis-aligned bottom is not what touches the floor. For a box of half-extents `a` (x) and `b` (y) rotated by θ, the centre rests at
-
-```
-h(θ) = a·|sin θ| + b·|cos θ|
-```
-
-above the floor. Use that for the contact test and a corner touches first, which is what actually happens.
-
-## Coming to rest — the part that goes wrong
-
-A tumbling object that stops bouncing is usually left tilted, resting on a corner. From there it topples: it pivots about that corner under gravity until a face lies flat.
-
-Do **not** tween the angle to upright. It is not a fall — a fall accelerates — and it looks exactly as artificial as it is. Keep integrating:
-
-```
-τ = -g · (horizontal lever arm of the contact corner)
-α = τ / I,   I = (4/3)(a² + b²)   for a rectangle about its corner
-```
-
-While pivoting, the centre also **drops** (a corner rest is higher than a face rest) and **shifts horizontally** as it swings about the fixed corner. Those two are what make it read as real; a pure rotation reads as a tween no matter how well eased.
-
-### Bug 1: the pivot jumps when the contact corner changes
-
-Track the contact corner from the signs of sine and cosine:
-
-```js
-u = a · sign(sin θ)      v = b · sign(cos θ)
-cx = pivotX - (u·cos θ - v·sin θ)
-cy = floor   - (u·sin θ + v·cos θ)
-```
-
-This description is continuous through the tipping point — where the same corner stays down and the object simply passes from one face's basin to the next — and only changes at multiples of 90°, when a face slaps flat and the pivot genuinely moves to the other corner. Re-anchor the pivot from the current centre at that instant and the position stays continuous.
-
-Describing it instead with 90° "frames" that swap the half-extents makes the centre jump the width of the box at the tipping point. Measured: **44.67px between consecutive frames**, and it was not obvious in playback.
-
-Related: deriving the pivot side from `Math.sign(θ)` alone flips it at θ = 0, jumping the centre by the full box width. Carry the side as state.
-
-### Bug 2: it never comes to rest
-
-A box has **four** stable orientations, not one. If the simulation only models "upright", an object that tips past its balance point rotates toward lying down and then oscillates forever, because there is no rest state there to catch it.
-
-For a box taller than it is wide, lying down is the *lower* energy state — so a spinning letter will essentially always end up fallen, never standing. That is correct physics, and worth telling whoever asked, because they may expect it to land neatly upright.
-
-The honest lever on the outcome is the **throw**, not the landing. Changing the initial spin changes where it comes to rest; clamping the final angle is just a tween wearing a costume. If a particular resting pose is required, either tune the launch until physics produces it, or say plainly that it will not.
-
-## Physics and format interact
-
-If any part of the geometry derives from the canvas height — a floor at `ALTO - 200`, a launch from the top of frame — then each aspect ratio simulates a different fall and each MP4 ends at a different time. Every file looks fine on its own, which is what makes it hard to catch.
-
-Derive physics geometry from fixed canvas coordinates, or accept the divergence deliberately and check that `window.__duration` matches across formats.
-
-## Verify a simulation numerically
-
-Two checks catch nearly everything:
-
-**Continuity.** Sample the element's position at the target frame rate and report the largest jump between consecutive frames. Real motion is smooth; a discontinuity means a bookkeeping bug. Compare the worst jump against the expected velocity: 108 px/s at 60fps should show 1.8px per frame, and a 9.67px jump was a sign flip.
-
-**Rest.** Confirm it actually stops, and where. A hardcoded settle keyframe that used a fixed X while the simulation ended somewhere else made a letter slide sideways to reach an invented point — it read as teleporting.
-
-Also check it rests *on* the surface: measure the object's bottom against the surface's top and expect them equal, not approximately equal.

package/skills/motion-graphics/references/verify.md

@@ -1,124 +0,0 @@
-# Verify by measuring
-
-The whole point of a seekable timeline is that you can interrogate any moment. Use it. Before claiming something is fixed, write six lines that check it and print a number.
-
-All of these assume the page exposes `window.__seek(seconds)` and `window.__duration`, and — for anything time-relative — `window.__times`.
-
-## The harness
-
-```js
-const { chromium } = require('playwright');
-const b = await chromium.launch();
-const p = await b.newPage({ viewport: { width: 1080, height: 1080 } });
-const errs = []; p.on('pageerror', e => errs.push(String(e)));
-await p.goto('file:///.../video.html');
-await p.evaluate(() => document.fonts.ready);
-// then: await p.evaluate(t => window.__seek(t), 7.2);
-```
-
-Always collect `pageerror`. A thrown exception while building the timeline leaves a half-built animation that still renders something plausible.
-
-## Frame times — is it actually janky?
-
-```js
-const dt = await p.evaluate(() => new Promise(res => {
-  const out = []; let prev = performance.now(), n = 0;
-  document.body.click();                       // restart playback
-  const tick = now => { out.push(now - prev); prev = now;
-    if (++n < 600) requestAnimationFrame(tick); else res(out); };
-  requestAnimationFrame(tick);
-}));
-```
-
-Report median, p95, and the count over 20ms. Do this **before** touching the design when someone says it feels janky. On a real piece the answer was 8.3ms median and zero dropped frames — the problem was that scenes had no camera and held frozen. Redesigning motion because of an imagined performance problem wastes a lot of time.
-
-## Composition — is it centred?
-
-Find the ink bounding box by scanning pixels, and report the top and bottom margins.
-
-```js
-const im = PNG.sync.read(await p.screenshot());
-let top = 1e9, bot = -1;
-for (let y = 0; y < H; y++) for (let x = 0; x < 1080; x++){
-  const k = (y*1080 + x) * 4;
-  const dark   = (im.data[k] + im.data[k+1] + im.data[k+2]) / 3 < 170;
-  const accent = im.data[k] - im.data[k+2] > 60;      // exclude the accent colour
-  if (dark && !accent){ if (y < top) top = y; if (y > bot) bot = y; }
-}
-```
-
-Under 10px of imbalance in a 1080 frame is fine. 28–41px is what "it feels off" looks like as a number.
-
-## Overflow — does anything leave the frame?
-
-Sample the element's rect across the window where it should stay put, and report the worst excursion past 0 and past the canvas width. Also report the maximum width: a smear that grows to 859px in a 1080 frame is going to clip even if it happens to stay inside on this particular line.
-
-## Continuity — does it jump?
-
-```js
-let prev = null, worst = 0, when = 0;
-for (let t = t0; t <= t1; t += 1/60){
-  const x = await p.evaluate(tt => { window.__seek(tt);
-    return document.getElementById('thing').getBoundingClientRect().left; }, t);
-  if (prev !== null && Math.abs(x - prev) > worst){ worst = Math.abs(x - prev); when = t; }
-  prev = x;
-}
-```
-
-Compare the worst jump against the expected velocity at that moment. Anything much larger is a bookkeeping bug, not motion.
-
-## Reproducing a reference exactly
-
-If you are porting an existing animation, diff it. Note that a CSS-animated reference is also seekable:
-
-```js
-await ref.evaluate(t => {
-  const a = document.getAnimations();
-  a.forEach(x => x.pause());
-  a.forEach(x => x.currentTime = t * 1000);
-}, t);
-```
-
-Then compare two ways, and let the second one decide:
-
-**Pixels** — count differing pixels with a small per-channel tolerance (8/255 covers antialiasing noise). This is a coarse net that catches anything structural.
-
-**Geometry** — compare `getBoundingClientRect()` element by element at matching instants and report the worst deviation in px. *This is the real claim.* Pixel counts explode from sub-pixel offsets: on one comparison the geometry agreed to 0.38px while the pixel count sat at 0.4%, purely because two animations with different absolute durations resolve their easing curves with slightly different precision and every edge antialiases differently. Judging by pixels alone would have sent you hunting a bug that did not exist.
-
-Two things the geometric check needs:
-
-- **Skip anything invisible.** An element parked off-screen at `opacity: 0` in both files can be thousands of pixels apart and it means nothing. Reading a 2771px "deviation" from an invisible bar is a memorable way to learn this.
-- **Compensate deliberate differences.** If the port is optically recentred by 31px or runs at 90% speed, apply that shift and that time scale in the comparison. The claim is "same movement", not "same coordinates".
-
-Expect residual sub-pixel differences from integer rounding: `offsetWidth` returns integers where `getBoundingClientRect()` is fractional, which is worth ~0.2px on its own.
-
-## The trap: suspect the check first
-
-When a check that used to pass suddenly fails, **suspect the check**. In practice the large majority of alarms were the measurement's fault:
-
-| What it looked like | What it was |
-| --- | --- |
-| The recurring mark flies 1256px off frame | Measurement window written for the old timing; it was sampling the entrance, which is *supposed* to start off-frame |
-| Scene 1 has no text at all | Fixed timestamp in the audit script; after a retime it landed after the text had left |
-| The URL scene is empty | Same — by that timestamp the mark had already covered the word, which is the intended behaviour |
-| The port broke, 4.7% difference | Race in the harness: the reference starts its animations in a `requestAnimationFrame` *after* `fonts.ready`, so `getAnimations()` returned an empty list and the diff compared against a blank frame |
-
-Confirm the failure independently before you "fix" working code. Two habits prevent most of it:
-
-- Derive measurement windows from `window.__times` instead of hard-coding seconds.
-- Wait for the thing you are about to measure: `await page.waitForFunction(() => document.getAnimations().length > 5)`.
-
-## Contact sheets
-
-For anything about rhythm, render a strip of frames and look at it as one image:
-
-```js
-for (let i = 0; i < n; i++){
-  await p.evaluate(t => window.__seek(t), t0 + i * step);
-  await p.screenshot({ path: `f${i}.png`, clip: { x, y, width, height } });
-}
-```
-
-Then tile them with PIL and label each with its timestamp. A 30-frame sheet across the whole piece catches structural problems — overlapping scenes, a beat that never fires, an accent parked in the wrong place — faster than watching it.
-
-Two cautions: crop generously or you will diagnose a problem that is only your crop (a rule "vanishing" because the camera pushed it past the clip edge), and remember `getBoundingClientRect()` on a block element returns the *container* width, scaled by any active camera — measure the tokens if you want the text width.