spine-rigc 0.2.1 → 0.3.0

package/docs/AUTHORING.md

@@ -20,7 +20,8 @@ that can see that, and a run that skips it has verified nothing about the motion
 - The motion spec and emitted shapes: [`src/types.ts`](../src/types.ts)
 - What the format holds and rigc covers: [SPEC_COVERAGE.md](SPEC_COVERAGE.md)
 - Reproducing a shot you were given as pictures: **§8**, and read it *before* you
-  start measuring rather than after; then **§9** for the loop that closes it
+  start measuring rather than after; **§8.1** if the figure has more joints than you
+  can measure one at a time; then **§9** for the loop that closes it
 - The conventions an editor user follows without being told — one image per
   attachment, keying practice, curve kind, draw order — sourced from Spine's own
   public documentation: **§10**
@@ -81,7 +82,7 @@ What the flags mean:
 | `--out` | directory for `skeleton.json` + `skeleton.atlas`; atlas page paths are written relative to it |
 | `--images` | where the rig spec's `image` names resolve (overrides the rig's own `images` field, and is relative to your working directory) |
 | `--manifest` | a cut manifest. Only for a rig with **measured art** behind it; a foreign skeleton has none |
-| `--profile` | `spine` = the 18 validity rules · `spine-html` = all 32 (**the default**) |
+| `--profile` | `spine` = the 20 validity rules · `spine-html` = all 34 (**the default**) |
 
 Pick the profile deliberately. `spine-html` adds one renderer's policy and one
 project's canvas budget, and those rules fire on perfectly correct Spine data
@@ -257,6 +258,14 @@ behind it writes literal `x`/`y` instead.
 `spec` must be exactly `"rigc-rig/1"`. `name` must be a non-empty string. `bones`
 must be non-empty. `slots` must be present (it may be empty).
 
+🚫 **Every example value below is invented.** Names, coordinates, vertex lists and
+payloads in this guide are written to illustrate a field, never copied out of a
+reference export — an example lifted from one would be handing an authoring agent an
+answer to the rung it is standing on, which is the rule §10.6 states and the honesty
+rule in [LADDER.md](LADDER.md) turns on. If a snippet here matches a reference file,
+that is a defect in this guide: report it. (It has happened — 2026-08-23, see
+[`bench/runs/README.md`](../bench/runs/README.md), *What a run may read*.)
+
 ### 3.1 `skeleton` — the header
 
 | Field | Spine meaning | Default |
@@ -349,9 +358,9 @@ Geometry comes in one of two fields:
 
 ```json
 "weights": [
-  [{ "bone": "tail3", "x": 184.91, "y": -2.83, "weight": 0.006 },
-   { "bone": "tail4", "x": 92.72,  "y": -2.83, "weight": 0.994 }],
-  [{ "bone": "tail4", "x": 84.66,  "y": -8.47, "weight": 1 }]
+  [{ "bone": "link_a", "x": 40, "y": 0,  "weight": 0.25 },
+   { "bone": "link_b", "x": -20, "y": 0, "weight": 0.75 }],
+  [{ "bone": "link_b", "x": -60, "y": 12, "weight": 1 }]
 ]
 ```
 
@@ -393,6 +402,59 @@ they encode a deformation model rather than a table of numbers, which is why the
 are code invoked by data. A generator is for a skeleton with **no** manifest; a cut
 that has one invokes the same builders through the manifest's `mesh` block.
 
+**Bounding box** ([Spine: bounding boxes](http://esotericsoftware.com/spine-bounding-boxes))
+and **clipping** ([Spine: clipping](http://esotericsoftware.com/spine-clipping))
+attachments — a polygon, and nothing else.
+
+**When you need one:** a *bounding box* is a shape the game hit-tests against — a
+hurt box, a pick region, a trigger volume — that follows the skeleton and draws
+nothing. A *clipping* attachment is a **mask**: everything drawn from the slot
+carrying it up to and including `end` is clipped to the polygon, so a window, a
+portal or a wipe is one attachment rather than a second set of art.
+
+```json
+"hitbox_a": { "hitbox_a": { "type": "boundingbox", "vertexCount": 4,
+                            "vertices": [-30, -10, 30, -10, 30, 50, -30, 50] } },
+"mask_a": { "mask_a": { "type": "clipping", "end": "box", "vertexCount": 3,
+                        "vertices": [0, 0, 200, 0, 0, 160],
+                        "color": "ff00ffff" } }
+```
+
+Both polygons above are invented — an axis-aligned rectangle and a right triangle,
+in round numbers, so that nothing here can be mistaken for a shape measured off a
+reference. A real one is measured off your own art (§8) or drawn to the volume the
+game needs.
+
+| Field | Meaning |
+| --- | --- |
+| `vertexCount` | **required.** How many vertices the polygon has, stated outright — see the warning below |
+| `vertices` / `weights` | the same two encodings a mesh's geometry uses, with the same by-name default and the same `"boneIndexing": "raw"` opt-in |
+| `color` | `rrggbbaa`; the colour the editor draws the outline in |
+| `end` | clipping only. The **last** slot the clip applies to, by name |
+| `convex`, `inverse` | clipping only, 4.3, both default false |
+
+🚨 **`vertexCount` has no parser default and rigc will not infer one.** A mesh gets
+its count from `uvs.length`; a polygon has no uvs, and the parser reads
+`map.vertexCount << 1` as the number of coordinates to expect. With the field
+absent that is `undefined << 1` = **0**, so the coordinate array is decoded as a
+*weighted* run — bone counts and weights read out of your x/y pairs — and the
+attachment ends up holding nothing. It loads. Neither type draws a pixel, so
+nothing downstream notices. rigc requires the count and cross-checks it against
+whichever encoding you used; `A33_VERTEX_ATTACHMENT_GEOMETRY` checks it again on
+the artifact.
+
+⚠️ **A clipping `end` that names nothing is not an error to Spine.**
+`skeletonData.findSlot` returns `null` on a miss and the parser assigns that null
+without a word, so the clip never ends — it runs to the bottom of the draw order
+and takes every slot below it out of the frame. rigc refuses a name the rig does
+not declare. Omitting `end` entirely is the format's own way of saying "clip
+everything after this one", and is left alone.
+
+🚫 Under the default `spine-html` profile a clipping attachment is refused by
+`A11_NO_CLIPPING_ATTACHMENTS` — that renderer skips them silently, so a mask that
+was supposed to hide something would not. It is valid Spine and `--profile spine`
+accepts it; the refusal is policy, not validity.
+
 ### 3.5 `constraints` — 4.3's single typed array
 
 Spine 4.3 folds every constraint into one `constraints` array with a `type`
@@ -413,7 +475,38 @@ Field lists are in [`src/rig.ts`](../src/rig.ts); three traps worth carrying her
   them parses cleanly and does nothing at all. rigc refuses it up front, and `A23`
   catches it from the other side.
 
-### 3.6 `invariants` — what the artifact cannot say about itself
+### 3.6 `events` — names the animation can fire
+
+**When you need one:** something outside the skeleton has to happen on a
+particular frame — a footstep sound, a spawn, a hit window opening. Spine
+[events](http://esotericsoftware.com/spine-events) carry no rendering effect at
+all; they are a named signal the game listens for, with an optional payload.
+
+The **declaration** lives here, in the rig spec, because the name is structure.
+The **firings** live in the motion spec (§4.8), because when they happen is time.
+
+```json
+"events": {
+  "cue_a": {},
+  "cue_b": { "audio": "cue_b.ogg", "volume": 0.8, "string": "line-01" }
+}
+```
+
+An object keyed by event name — the one top-level collection in the format that
+is not an array. Every field is optional and each is the payload a firing
+**inherits** when it does not override it: `int` (0), `float` (0), `string`
+(`""`), `audio` (none), `volume` and `balance`.
+
+- **An empty object is the normal case, not a stub.** Most events carry no payload:
+  the name *is* the signal, and the declaration exists so the firings in §4.8 have
+  something to resolve against. Write `{}` and move on.
+- ⚠️ `volume` and `balance` are read **only when `audio` is set**. Without an
+  audio path the parser drops them without a word, so rigc refuses that pairing
+  rather than emitting two numbers no runtime will read.
+- An event that nothing fires is legitimate: a skeleton may declare the vocabulary
+  its game listens for and key only some of it in any one animation.
+
+### 3.7 `invariants` — what the artifact cannot say about itself
 
 Optional, and only meaningful for rigc's own formations: `meshSlots` and
 `meshTriangles` (the two halves of the mesh budget `A13` measures against),
@@ -456,6 +549,7 @@ time puts it here.
 | `note` | free text |
 | `tracks` | the timelines |
 | `drawOrder` | the draw-order timeline — §4.7. Not a track: it names no target |
+| `events` | the event timeline — §4.8. Not a track, for the same reason |
 
 `groups` (`name → [member, …]`) lets one track target several bones or slots at
 once; `lag` shifts every key of a track, and `stagger` adds a per-member delay in
@@ -496,6 +590,19 @@ stepped.
   Seconds, not frames: nothing requires a key to land on any frame grid, and a
   reference rendered at some rate says nothing about where its keys are. Put keys
   where the motion changes.
+- **Key times are quantised onto a 1e-6 s grid by rounding DOWN, never to
+  nearest.** A key time is a position against the sample grid a player will step,
+  and the two directions of a half-step error are not the same size. `2/12 s` and
+  `5/30 s` are both 0.16666666…; `0.166667` is *larger* than either, so a key
+  emitted there is applied at sample **3** of a 12 fps playback and not sample 2 —
+  a whole frame late, with nothing raised. On a **stepped** timeline (an attachment
+  timeline always is) that is the wrong picture rather than a slightly wrong value:
+  the spineboy run's muzzle flare fired a frame late for exactly this until the
+  run's own frame check caught it (issue #99). Rounding down cannot do that; the
+  worst it can do is put a key a millionth of a second early, on the sample it was
+  written for. ⚠️ What this does **not** protect you from is rounding your own
+  times before you write them — write `2/12`, not `0.1667`, and let the compiler
+  do the quantising.
 - **No key may land past the animation's `duration`.** Nothing that plays the
   animation for the duration it declares ever reaches such a key, so it is a
   compile error — checked on **every timeline**, not just on the latest key in the
@@ -578,6 +685,53 @@ the emitted file is the parser's requirement rather than a decision of yours, so
 you state the set of moves and rigc writes them in the order the parser needs.
 `A31_DRAW_ORDER_OFFSETS_RESOLVE` checks all four from the other side.
 
+### 4.8 `events` — firing a declared event
+
+The second timeline that names no target, and it sits on the animation for the
+same reason `drawOrder` does: 4.3 writes it as `animations.<a>.events`, beside
+`bones` and `slots`.
+
+```json
+"animations": {
+  "walk": {
+    "duration": 1.0666666,
+    "loop": true,
+    "events": [
+      { "t": 0, "name": "cue_a" },
+      { "t": 0.5333333, "name": "cue_a", "int": 2 }
+    ],
+    "tracks": []
+  }
+}
+```
+
+- `name` must be a key of the rig spec's `events` block (§3.6). A miss is a
+  compile error here; in raw JSON the parser **throws** `Event not found` in the
+  consumer's process, which is late.
+- `int`, `float` and `string` override the declaration's payload **for this firing
+  only**. Omit them and the firing inherits the declared defaults, which is what
+  the editor writes.
+- `volume` and `balance` are accepted only on an event that declares `audio`, for
+  the same reason as §3.6.
+- Event keys are **instantaneous** and carry no `ease` or `curve`.
+- Its last key counts towards the declared duration like any other (R7).
+
+rigc refuses three things here, and only the first is loud in the parser:
+
+| You wrote | You get |
+| --- | --- |
+| a name the rig spec does not declare | `event "X" is not declared in the rig spec's "events" block; declared: …` |
+| a key time earlier than the key before it | `key times must not go backwards (at t=0.25, after t=0.5)` |
+| `volume`/`balance` on an event with no `audio` | `volume is set but event "X" declares no "audio"` |
+
+The ordering rule is **non-decreasing**, not strictly increasing: two different
+events on one frame is an ordinary thing to want, and unlike a value track there
+is no contradiction in it. What is refused is going *backwards* —
+`readAnimation` fills frame `i` from key `i` in array order and never sorts, so a
+decreasing time builds an `EventTimeline` whose earlier firing is simply
+unreachable, with a perfectly clean load.
+`A32_EVENT_KEYS_RESOLVE` checks all three from the other side.
+
 ---
 
 ## 5. Reading a failure
@@ -609,6 +763,12 @@ the frequent ones, verbatim:
 | `animation "A" has two tracks on X.property; merge them into one track` | one timeline per target property |
 | `no stage size: give the rig spec a \`skeleton.width\`/\`skeleton.height\`` | §3.1 |
 | `drawOrder at t=…: slot "X" is not one this rig emits` / `is offset twice in one key` / `puts it at N, outside the … emitted slots` | §4.7 |
+| `events at t=…: event "X" is not declared in the rig spec's "events" block` | declare it in the rig spec (§3.6), or fix the name |
+| `events: key times must not go backwards` | put the firings in time order (§4.8) |
+| `events at t=…: volume is set but event "X" declares no "audio"` | drop `volume`/`balance`, or give the event an audio path |
+| `vertexCount is undefined; a polygon needs at least 3 vertices, stated outright` | give the bounding box or clipping attachment a `vertexCount` (§3.4) |
+| `vertexCount N wants M unweighted numbers and "vertices" holds K` | fix the count or the array; they decide the encoding between them |
+| `end names slot "X", which this rig does not declare` | fix the clipping attachment's `end`, or add the slot |
 | `bone "X" takes its position from …, which needs a cut manifest` | R8 — pass `--manifest`, or write literal `x`/`y` |
 
 ### 5.2 Assertions — the gate
@@ -668,6 +828,8 @@ The report prints one line per assertion:
 | `A29_STROKE_WITHIN_CONTACT_DEPTH` | archetype | the animation drives deeper than the manifest's measured contact depth |
 | `A30_STROKE_WITHIN_CAP_CONTAINMENT` | archetype | the animation drives past the measured containment ceiling, or scales a bone in the axis subtree |
 | `A31_DRAW_ORDER_OFFSETS_RESOLVE` | both | a draw-order key names a slot the skeleton does not have, offsets one slot twice, puts a slot outside the slots array, or lists its offsets out of slot order (§4.7). The only assertion that runs **before** `A00` — the last of those shapes makes the loader spin rather than return, so the round trip is refused instead of attempted |
+| `A32_EVENT_KEYS_RESOLVE` | both | an event key fires a name the skeleton's `events` block does not declare, sits earlier in time than the key before it, or sets `volume`/`balance` on an event with no `audio` (§4.8). **SKIP** when no animation carries an event timeline |
+| `A33_VERTEX_ATTACHMENT_GEOMETRY` | both | a bounding box or clipping polygon whose `vertexCount` is missing or disagrees with its vertex array, a weighted run that decodes to the wrong number of vertices or an out-of-range bone index, or a clipping `end` naming a slot the skeleton does not have (§3.4). **SKIP** when the skeleton carries neither type |
 
 `both ◑` marks a mixed assertion: its validity half always runs and its policy
 clauses are gated by profile.
@@ -681,9 +843,14 @@ a **`NotImplementedError` naming the field**, because the parser's own behaviour
 worse: an unknown attachment `type` returns `null` and the attachment disappears,
 and a constraint entry with an unrecognised `type` matches no case and vanishes.
 
+Each is deferred for a stated reason, and the reason is the same one in every row:
+**not one of these types appears anywhere in the benchmark corpus** (SPEC_COVERAGE
+parts 3-1 and 4-2), so none of them is on the ladder's critical path. The message
+says so, because a deferral without its reason is a wall rather than a work item.
+
 | You wrote | You get |
 | --- | --- |
-| attachment `type` of `boundingbox`, `point`, `clipping`, `path`, `linkedmesh` | `attachment type "X" is in the Spine 4.3 format and rigc does not emit it yet. Implemented: region, mesh.` |
+| attachment `type` of `point`, `path`, `linkedmesh` | `attachment type "X" is in the Spine 4.3 format and rigc does not emit it yet. Implemented: region, mesh, boundingbox, clipping. point, path and linkedmesh are deliberately deferred: not one of them appears anywhere in the benchmark corpus …` |
 | constraint `type` of `path` or `slider` | `constraint type "X" … Implemented: ik, transform, physics.` |
 | mesh `generator.kind` of `contour` | `the "contour" generator would triangulate a part's own alpha mask, and src/mesh.ts has no triangulator` |
 
@@ -774,6 +941,28 @@ where one part's **interior detail** — a marking, a highlight, anything not on
 outline — lies inside the other part's area, and see which survives. Then write the
 slots in that order (R4), because there is no other place in the file to say it.
 
+**That reads the reference only, so it settles the edges the reference happens to
+show an interior detail on, and no more. There is a second test, and it decides more
+of them: render your own candidate both ways and measure the same feature on both
+sides.** Build the pair, render each back at the frames' own scale, and compare
+like with like. A part whose unoccluded size you can compute is a ruler — composite
+it alone, then read how much of it survives in the reference and how much survives
+in each build. If a part that measures 110 px on its own reads 100 px in the
+reference, the build that also reads 100 px is covering it the way the reference
+does and the build that reads 108 px is not, and that is the order. It costs two
+builds and it reaches edges the frames never show a marking on: on the ladder a brief
+has settled a single edge of a chain from interior detail and said outright that the
+frames did not show the rest, and rendering like-for-like settled three more of them
+— worth a measurable drop in window MAE, a convention the gate cannot see and the
+measures can.
+
+⚠️ **The same test knows when to stay silent, and you have to let it.** Run on
+another shot, two orders came out **0.8 % apart over the whole shot and pointing
+opposite ways** — a gap well inside the objective's own scatter, which
+is correctly *no answer*. A difference that small is not a quiet vote for the
+winner; it means the frames do not decide this edge, and you ship it on reasoning
+and say in the log that is what you did.
+
 And the general form of all three: **when a reading implies a key, look for a second
 way to get the same number before you author it.** A wrong measurement costs one
 spurious key; a wrong measurement you believed costs the shape of the whole shot.
@@ -797,16 +986,156 @@ linear, stepped or bezier and never compares two handle shapes; `check` measures
 rendered result, so it can tell you a curve is *wrong* without telling you what it
 should have been. What does not follow is that omitting `ease` abstains. It authors
 constant speed on every span — the one shape a hand-animated reference almost never
-has (§10.4) — and the ladder has measured both sides of that bet. Rung 6 keyed
-everything linear for exactly the reasoning above and scored `curve_kinds` **34/539**,
-its single largest structural gap. Rung 3's second attempt — same brief, same frames —
-applied §10.4's rule instead and went 41/69 → 49/69, with `key_counts` rising beside
-it and every other section figure unchanged. ⇒ Take the curve *kind* from what the motion does — starts, stops,
-accelerates, settles, falls — rather than from how far apart the keys are; take its
+has (§10.4) — and the ladder has measured both sides of that bet. A run that keyed
+everything linear for exactly the reasoning above scored under a **sixteenth** of its
+`curve_kinds` measure, and that was its single largest structural gap. A second
+attempt at another rung — same brief, same frames, same model as its own first, with
+§10.4's rule added and nothing else — lifted `curve_kinds` by a fifth, with
+`key_counts` rising beside it and every other section figure unchanged. ⇒ Take the
+curve *kind* from what the motion does — starts, stops, accelerates, settles,
+falls — rather than from how far apart the keys are; take its
 shape from §10.4's automatic-handle advice and a small reused `easings` table; and
 leave `check` to catch the one thing no static reading can, an easing applied the
 wrong way round.
 
+### 8.1 Getting a pose for a figure with a dozen joints
+
+Everything above measures a *part*, and §9 checks a pose you already have. Between
+them sits the question neither answers — where do a dozen bones go on this frame —
+and on a character that gap is most of the run. What follows is not Spine's and no
+public page has an opinion about it, but it decides whether the search converges at
+all, so it sits here rather than being rediscovered once per figure.
+
+**Fit the rendered composite, never a part on its own.** The first trap above tells
+you to measure each part on pixels that can only be that part. On a figure with limbs
+there are no such pixels: an arm crosses a torso, one leg crosses the other, a held
+prop is drawn over both, and **every frame is a frame where parts are touching** — the
+trap with no way out of it. So the objective is the whole picture. Render your
+candidate through the same rasteriser that drew the reference, into the frames' own
+viewport, and minimise the difference over the bones' local transforms; that is §8's
+*"look for a second way to get the same number"* applied to a whole pose at once, and
+it is the render loop **§9.1** sends you into. Read §9.1's warning about where a
+bone's local transform lives *before* you write the first sweep — a fitter that is
+posing nothing reports a flat number and looks like a bad objective.
+
+⚠️ **Fitting one part at a time in sequence is the same mistake wearing a
+schedule.** A near arm solved against the composite while the far arm is still
+wrong is being scored on a picture the other arm is spoiling, and the minimum it
+walks to is not its own. The knobs come down together, coarse first — the next two
+rules are how.
+
+**Compare at a reduced resolution first. At full resolution the objective is flat
+over the range a joint has to travel.** Sweep one bone alone across the width of the
+figure against a single frame and watch the number: at full resolution it can wander
+inside a few percent for the whole sweep with no slope anywhere in it, because a
+limb fifty pixels from where it belongs overlaps the reference no better than one a
+hundred pixels away — both are *no overlap*, and the difference between them is
+aliasing. A coordinate search sees noise, reports no improvement, and leaves the frame
+at a pose that shares almost nothing with the picture. ⇒ **Box-average both sides
+before comparing them and run the search coarse to fine.** The coarsest level places
+the body, the next the limbs, the last two the pixels. The same sweep at the coarse
+level has a slope on it, because at that block size the two figures still overlap and
+the number knows which way to go.
+
+⚠️ **The coarsest level is for the body and nothing else.** A block big enough to
+give the whole figure a gradient is a block a shin is one cell of, and one cell
+cannot say which way a shin points. Place the root and the torso there, then decide
+each limb at a level whose cells are smaller than the part that level is moving.
+
+**Scan each knob's whole plausible range. Do not line-search out from where it sits.**
+A search that steps out from the current value cannot bring an arm 60° round, because
+the first step overlaps the reference no better than standing still did — so it
+reports no improvement and stops, correctly, on the objective it was given. A figure
+whose legs have folded under it is that failure with a picture attached: a real local
+minimum, sat in for as long as you care to iterate. ⇒ For each knob, evaluate the
+whole range that bone can plausibly take — a few dozen samples across it, which is
+nothing beside the frames you are fitting — take the best, and refine only after
+that. The cost is linear in the number of knobs, and it is the difference between a
+fit that converges and a fit that reports success on a folded figure.
+
+⚠️ **Some knobs only decide together.** A part hanging three rotations below a
+shoulder is placed by none of them alone: each single-knob scan finds its own best
+while the part is still nowhere near, because every value of that knob is wrong given
+the other two. Where a chain ends in something whose position you can actually see —
+a hand, a foot, a held prop — scan the two links above it as a **pair**, over the
+grid. That is the product of two ranges on a handful of chains, not on every bone.
+
+**Re-fit the setup pose against frames drawn from every shot, not against one.** Every
+animation is measured from the setup pose, so an error in it is an error in all of
+them — and it is exactly the error one frame cannot show you. Fit an attachment's
+offset against a single frame and that frame's own rotations absorb whatever you got
+wrong: the picture comes out right, the offset is wrong, and every other shot pays
+for it. Across a spread it cannot hide, because a wrong offset would have to be
+absorbed by a *different* rotation in each frame and no one value of the offset does
+that. ⇒ Fit the setup pose against one clear frame to get near, then re-fit it
+against a handful of frames drawn from **every** animation at once, and hold it fixed
+while the per-frame poses are fitted. It is the spread that identifies it — a
+sequence of single-frame fits, one per shot, is not the same thing.
+
+**Seed each frame's search from its neighbour's solution — as one start among the
+full-range scans, never instead of them.** Adjacent frames are adjacent poses, so the
+answer next door is a better first guess than the middle of any range, and it costs one
+extra evaluation per knob to try it. What it must not do is *replace* the scans: the
+neighbouring frame's pose is precisely where a line search would have started, and a
+limb 60° out in one frame stays 60° out in the next for the reason the rule above
+gives — stepping away from it overlaps no better, so the whole series inherits one
+frame's local minimum and looks stable while it does. ⇒ Scan the whole range, add the
+neighbour's value to the starts, take the best of them. Fit outward from a frame you
+trust in both directions rather than only forward, so a bad frame seeds its neighbour
+and not every frame behind it.
+
+⚠️ **Then measure the adjacency drift, because a fit that lost a limb teleports.**
+Fitted frame by frame with nothing tying the frames together, a leg has two answers
+wherever the other leg is near it, and no single frame's number prefers the right one:
+some frames land on the wrong leg, every one of them cheap, and the series jumps back
+and forth between the two. That defect is invisible in any per-frame figure and loud in
+the relation between two — the reading §9.2's `Δpx` and `ref Δ` columns already make
+for the whole figure, and the chain table localises: a chain whose worst slot drift on
+one frame runs many times its own mean across the set did not travel that far, it was
+lost and refound somewhere else. **A limb that moves much further between two adjacent
+frames than the reference's own frame-to-frame change is a fit that lost it, not a limb
+that moved.** Read it per chain rather than per figure — one leg swapped for its twin
+is a small share of a whole-frame delta and vanishes into it.
+
+**Two near-identical parts need one calibrated separator, decided once and pinned.** A
+front limb and a rear one are often the same drawing twice, differing by a tint or by
+nothing at all; a search scoring a whole composite cannot tell which of the two it just
+placed, because exchanging them costs almost nothing on the frames where they overlap.
+Left to the per-frame fit, that assignment is re-decided on every frame — the teleport
+above, arriving by a second route. ⇒ Settle it the way §8 settles a draw-order edge:
+build both hypotheses, render each at the frames' own scale, and compare like with like
+— but calibrate on the frames where the two parts are *unambiguous*, the ones where
+they are far apart or only one of them is drawn, and read the separation there, where
+it is a real gap rather than a rounding difference. Then **pin the assignment for the
+run** and let no per-frame search reopen it. ⚠️ The same test knows when to stay silent
+here too: two hypotheses that come out inside the objective's own scatter mean the
+frames do not decide this, and you ship it on reasoning and say in the log that is what
+you did.
+
+**Spend each iteration on the worst chain, and stop re-fitting the ones already at the
+floor.** §9.2's chain table is this loop's work queue: it gives every limb a worst slot
+drift, an error per pixel, and a share of the set's error. ⇒ Take the next iteration to
+the worst **per-pixel** chain rather than the largest share — the share confounds
+*wrong* with *big*, as §9.2 says beside the table, and the chain holding most of a
+run's error is routinely the one that simply covers most of the figure. Then freeze the
+chains that have converged. Re-fitting them spends the budget the broken chain needed,
+and it is not merely wasteful: chains share parents, so a search free to move a
+converged limb's ancestors will walk it back off the floor to buy a fraction of a point
+somewhere else. ⚠️ **A blank where a drift should be is the loudest row in the table,
+not a quiet one.** The matcher refuses to name a distance past the part's own size
+(§9.2), so a limb far enough out reports no match rather than a large number — read
+that beside a high figure per pixel as the strongest signal the table has.
+
+**What comes out is a pose per frame, and a pose per frame is not a key.** Two things
+decide what survives the reduction, and **§10.3** states both: declare one tolerance
+in pixels at the end of what each bone swings rather than a figure in degrees, and
+deal with the gauges — the directions the pixels cannot see — *before* the series
+becomes keys, because a fitter will have wandered along every one of them; fold the
+exact ones out and penalise the rest. Then close
+the loop with **§9**: the fit's own number says how near this pose is to this frame,
+and only `check` says whether the shot is the shot. **§9.3** is the list of what even
+that cannot see.
+
 ---
 
 ## 9. Checking against the frames — `rigc check`
@@ -816,11 +1145,13 @@ bun cli.ts check --candidate path/to/spine --frames path/to/reference/frames
 ```
 
 `--frames` takes either a **skeleton root** (the directory holding `frames.json`,
-which checks every animation of that shot) or **one animation directory** inside
-it. Everything else is optional: `--atlas` when the candidate's atlas is not beside
-its skeleton, `--as <name>` when your animation is called something the frame
-directory is not, `--all-frames` to list every frame instead of the worst by MAE,
-`--json <out>` for the whole per-frame, per-slot report.
+which checks every animation of that shot, framed per set — see the scope note
+below) or **one animation directory** inside it. Everything else is optional:
+`--atlas` when the candidate's atlas is not beside its skeleton, `--as <name>` when
+your animation is called something the frame directory is not, `--framing shared`
+to fit one framing across every set instead of one each, `--all-frames` to list
+every frame instead of the worst by MAE, `--json <out>` for the whole per-frame,
+per-slot report.
 
 ⚠️ **A frame set may be contact-sheets-only.** `check` only reads `fNNNN.png`
 files — a committed reference set that ships a contact sheet plus a couple of
@@ -885,10 +1216,47 @@ pixels rather than quad corners (issue #34, closed by #39; see §9.2). Pin to a
 you can name a reason for, and read the unpinned framing line first when you are not
 sure whether you have one.
 
-⚠️ **The framing is over the frames you compare.** `--frames <root>` fits one
-framing across every set under it; `--frames <root>/<one-set>` fits one to that set
-alone. Both are right and they are not the same number, so compare like with like
-across builds.
+⚠️ **The framing is over the frames you compare, and `check` decides it PER SET.**
+Point it at a skeleton root and each animation directory under it is asked its own
+question first: *do this set's own drawn pixels land in the box `frames.json`
+records?* The sets that do are measured in that box, which is exact — it is not an
+estimate of where the frames were drawn, it is where they were drawn — and nothing
+another set does can move them. The sets that do not are measured in **one shared
+framing** fitted across every set, printed as the header's `shared box` line. Each
+set says which it got on its own `framed to` line.
+
+Why the split falls there, both halves measured on an 8-shot character (147 frames):
+
+- **Deciding the declared box per set is worth 15–25 MAE.** Over the union, one shot
+  that is not in the frames' coordinates puts the pooled correction over the
+  one-pixel threshold and the *whole root* falls back to a fit. Per set, the shots
+  that qualify read what pinning by hand reads: `idle` **18.77** where a whole-root
+  run read 41.59, with not one key different (issue #100).
+- **Fitting per set is worse, so `check` does not.** `fitFraming` registers extent,
+  and extent is not alignment (see the ⚠️ in §9.2), so on a shot whose silhouette
+  genuinely differs one shot's frames do not constrain the fit enough: `hit` reads
+  **92.36** fitted on its own against 60.59 in the shared fit, and a two-frame stills
+  set reads 101.94 against 42.98. More frames is a better-conditioned fit, so the
+  fallback is deliberately the shared one.
+
+`--framing shared` measures **every** set in the shared framing, which is what a
+whole-root run used to do. It answers one question and it is a good one — *does a
+single box serve every set?* — and it is the wrong number to read as one shot's
+fidelity.
+
+⚠️ The two are different measurements and their absolute numbers are not comparable.
+The `scope` line at the top of the report says which one you got. `--viewport` pins
+one box for the whole run whichever scope you ask for, because a pin is a claim
+about your candidate's own coordinates and those do not change between shots.
+
+⚠️ **`--frames <root>/<one-set>` is a third number for a set that cannot take the
+declared box**, and it is the least constrained of the three: the fit has only that
+set's frames to work from, where a root run's shared fit has every frame in the
+skeleton. Measured on the same character, `hit` reads 60.50 at the root and 92.41
+pointed at its own directory. A set that DOES take the declared box reads the same
+either way — that box is not fitted to anything — so pointing at one directory is
+exact for a shot you authored in the frames' coordinates and a rough estimate for
+one you did not.
 
 ### 9.1 Why this exists
 
@@ -910,6 +1278,52 @@ your run ceasing to be an honest authoring run. It is a loop, in the way `build`
 a loop. `bench` and `diff` against a rung's export are not — they read the answer,
 and [the ladder's honesty rule](LADDER.md) makes them a finish line you reach once.
 
+🚨 **If you drive the runtime yourself, a bone's local transform lives on
+`bone.pose`.** A shot whose poses have to be *fitted* rather than read sends you
+past `check` and into your own render loop over
+`@esotericsoftware/spine-core` — that is §8's *"look for a second way to get the
+same number"* applied to a whole pose, and it is a legitimate thing to build — §8.1
+is how that search is set up so it converges. The
+first thing it hits is not a subtlety. **spine-core 4.3 keeps a bone's local
+transform on `bone.pose`, not on the bone**, so `bone.rotation = …` — or `.x`,
+`.y`, `.scaleX` — is neither an error nor a rotation: it adds a property nothing
+reads, and every frame renders as the setup pose. Write `bone.pose.rotation`.
+Rung 8 lost a loop to it at a flat 17.3; driven through `bone.pose`, the same
+poses measured **2.76**.
+
+🚨 **That trap has a twin one level up: the *setup* transform lives on
+`bone.data.setupPose`, not on `bone.data`.** `BoneData` extends `PosedData`,
+which carries the whole setup transform on a `setupPose` object, so
+`bone.data.rotation` — or `.x`, `.y`, `.scaleX` — is `undefined`, and
+`bone.data.rotation + delta` is `NaN`. Read and write it as
+`bone.data.setupPose.rotation`. This one is worse to spot than the `bone.pose`
+trap, because nothing on the path raises: `undefined` propagates to `NaN`, and
+`NaN` serialises to `null`, so a fit writes `"px": null` into its own placements
+file, the next build reads those as zero, `validate` is green and `check` runs.
+⇒ **A `null` in your own placements dump is the signature of having read
+`bone.data` directly** — nothing in this format is ever legitimately null. On
+spineboy it cost the candidate MAE 13.0 → 114.6 with a green gate throughout
+([`bench/runs/2026-08-23-spineboy-2/LOOP.md`](../bench/runs/2026-08-23-spineboy-2/LOOP.md),
+§4.1). Note that the two names are not the same thing: `bone.data.setupPose` is
+the setup transform, while `bone.setupPose()` on a `Bone` is the method that
+resets `bone.pose` back to it.
+
+🚨 **A region attachment's own offsets are cached.** `attachment.x`, `.y`,
+`.rotation`, `.scaleX/.scaleY` are inputs to a quad spine-core computes once and
+stores; what gets drawn is that stored quad — `computeWorldVertices` reads
+`getOffsets(pose)`, never the fields — so writing them is, again, neither an
+error nor a move. **Call `attachment.updateSequence()` after every write**, or
+every frame renders the quad it was loaded with. A setup fit on spineboy ran
+4,500 renders and reported the same number for all of them before this surfaced
+([`bench/runs/2026-08-23-spineboy-2/LOOP.md`](../bench/runs/2026-08-23-spineboy-2/LOOP.md),
+§4.2).
+
+⇒ **An MAE that is identical across every pose, and that does not move for any
+parameter you sweep — a bone's local transform, an attachment's offsets — is one
+of these inert writes and not a wrong animation.** The parameter you swept was
+never read; a wrong rig moves the number, a write to a field nothing reads
+cannot.
+
 ### 9.2 Reading the table
 
 ```
@@ -922,6 +1336,7 @@ and [the ladder's honesty rule](LADDER.md) makes them a finish line you reach on
   ── heavy — candidate animation "heavy", 12 fps ──
      frames     65 on disk, candidate samples 65, 65 compared
      MAE        mean 23.10  worst 43.36 at f0029   (0..255 over the union alpha; …)
+                ⤷ over the REFERENCE's own drawn pixels, mean 23.90 — the union figure compares two builds …
      slot drift worst 2.1 px  "pendulum" at f0029
      per-frame 1 of 64 adjacent pair(s) change by a different amount than the reference does; worst
                f0018, yours moved 0 px where the reference moved 374
@@ -1012,6 +1427,20 @@ because an ad-hoc re-render check naturally computes that one, and on every set
 measured so far it comes out ten to twenty-five times smaller and correspondingly
 blunter.
 
+⚠️ **Half of that denominator is yours, so do not optimise against it.** The union
+is the pixels *either* side drew, and a large, mostly transparent sprite adds many
+cheap pixels to it — so the *mean falls* on a candidate that got worse. That is not
+hypothetical: spineboy-2's muzzle flare walked its own scale to 13x under a fitting
+loop doing exactly this, and cost every set in that run its framing (issue #119).
+So the line under the MAE divides the same difference by the pixels the
+**reference** drew, a denominator nothing you do can grow. Read the union figure to
+compare two builds of your own rig, where both sides cover about the same ground,
+and the reference-denominator figure when you are deciding whether a change made
+the shot better; it is not bounded by 255. A set that draws more than half again as
+much ink as the reference does gets `⚠️ overdraw` beside those two numbers, with
+both pixel counts, because at that point the first figure is cheap for a reason
+that has nothing to do with your keys.
+
 **`Δpx` and `ref Δ`** are the two columns that do **not** compare you against the
 reference. They compare each side against **itself one frame earlier**: how many
 pixels of your own frame moved since your own previous frame, and the same for the
@@ -1074,6 +1503,39 @@ summary line carries the same denominator. `N reference component(s) no slot
 reaches` means the reference frame contains something none of your slots overlaps:
 a part you have not authored, or one you have put somewhere else entirely.
 
+**The `chains` block is the same two measures on the unit you actually repair.**
+
+```
+     chains     6 from the candidate's own bone tree — the roster is at the foot of the report
+       chain                 slots   worst slot drift                     mean   MAE in it   share
+       neck                    5/5   3.0 px "goggles" f0004              2.3 px       30.37    24.3%
+       rear-upper-arm          6/6   2.2 px "gun" f0000                  1.4 px       46.26    34.6%
+       front-thigh             3/3   16.3 px "front-shin" f0003          7.2 px       48.18     9.0%
+```
+
+`check` cuts **your own** bone tree at every branch point — a chain runs from a
+root or a fork down to the next fork; a single-bone chain that is itself a fork
+folds into its parent, so a `torso` that branches three ways joins the trunk rather
+than becoming a row of its own; and each chain is named after the first bone in it
+that carries a slot. On a biped that lands on the parts you would name (`neck`,
+`front-thigh`, the gun arm); on a serial figure with no fork it is one chain, and
+the slot rows under it still say which link moved. Which bones and slots went where
+is printed as a roster at the foot of the report, so it is never a guess. `MAE
+share` divides the difference over the **reference's** own drawn pixels — the
+denominator from the line above, which nothing you draw can grow — and splits it by
+giving each of those pixels to the chain whose ink is nearest, so the shares
+partition the set and no chain can look better by drawing more: growing its ink
+only pulls more of the reference's pixels, and their error, into it. Read `MAE in
+it` beside the share, because the share alone confounds *wrong* with *big* — a head
+and its features cover a lot of a figure and can carry a third of the error at a
+below-average figure per pixel. Reference ink further from your ink than the part's
+own size is left `(unattributed)` rather than charged to a neighbour, and a chain
+reading 0 % on `0/3` slots drawn is missing, not clean. The rollup at the foot gives
+each chain one line across every set — the sentence a run's README quotes instead of
+a per-shot list. **§8.1** is how to act on it: the next iteration goes to the worst
+chain by error per pixel, and a chain already at the floor is frozen rather than
+re-fitted.
+
 ### 9.3 What it still cannot see
 
 - **Anything a frame does not contain.** Bone `length`, the setup `inherit` mode,
@@ -1086,7 +1548,20 @@ a part you have not authored, or one you have put somewhere else entirely.
   still cannot tell you is *how* a silhouette got its shape: a hull moved by a
   bone chain and the same hull moved by deform keys render to the same pixels, and
   the frames cannot separate them. Choose on what the rig has to do next, not on
-  what the frames appear to say.
+  what the frames appear to say. ⚠️ **But `bench` does see it.** Take a disc that
+  squashes as it travels: a region on a bone that scales, and a grid mesh weighted
+  1.0 to that same bone, draw the same pixels on every frame — and they are
+  different files. One has a region and one bone; the other has a hull, a
+  triangulation and a weight per vertex, and a rig that meshes one part usually
+  meshes its neighbour and carries the bones to drive them. `attachments.type_counts`,
+  `attachments.mesh_weighted`, `attachments.region_size` and the bone count that
+  comes with the choice all move on that decision, while `animations.deform` moves
+  for neither, because neither one deforms with keys — the whole difference is which
+  machinery renders identical pixels. That is not an argument for guessing: the
+  frames cannot choose, and this guide will not tell you which way any reference
+  went. It is an argument for **writing down which way you went and why at the
+  moment you decide it**, rather than meeting the decision again in the measures
+  after the run is over.
 - **Which of two explanations is right.** A slot 3 px low every frame and a slot
   3 px low at one frame have the same drift and opposite causes. The table gives
   you the frame index; §8's rule still applies — look for a second way to get the
@@ -1143,6 +1618,31 @@ attachment name"* — [Images](http://esotericsoftware.com/spine-images). ⇒ in
 keep the placeholder equal to the PNG's basename and no `path` is written (R5). A
 `path` in the emitted file means the two disagreed.
 
+🧩 **⇒ When the art is named after the parts, the art's names are the rig's names —
+and this is the largest lever §10 has.** *One image → one slot → one attachment,
+named after the image* reads as a structural rule. It is also, and mostly, a
+**naming** rule, and naming is what whole sections of the measures are made of:
+five of `bones`'s eight name-matched measures (`names`, `parent_by_name`, `order`,
+`length_present`, `inherit_present`) and every `slots` measure but the count are
+scored over the names the two sides **share** ([`src/diff.ts`](../src/diff.ts)), so
+a rig whose names miss reads near zero on all of them however well it is built. ⇒
+carry each part's own name straight through — PNG basename → slot → attachment, and
+the bone that moves it — instead of inventing a scheme of your own.
+
+**Both directions are measured.** The one run whose art shipped a separate PNG per
+body part, each named for the part, applied this deliberately and posted `names`
+measures **an order of magnitude** above anything on the ladder before it — without
+either side seeing the other. Every honest run before it read near zero on the same
+measures. It is the largest single thing any run has got out of a convention.
+
+⚠️ **And the other half, which matters just as much: when the art is *not* named
+after the parts, no naming strategy beats any other and the measure is noise.** On a
+shot whose two PNGs are called things like `square` and `pendulum`, the names carry
+nothing a rig could inherit, every candidate name is as good as every other, and the
+name measures are reporting the honesty rule's own price rather than a defect in
+your rig. Do not spend a loop hunting for better names there, and do not read the
+low figure as a miss — say in the log that the art did not carry them.
+
 📗 **Housekeeping the format fixes for you.** The default skin *"always has the name
 `default`"* and *"bones are ordered so that the parent always comes before a child
 bone"* — [JSON format](http://esotericsoftware.com/spine-json-format). §3.4.
@@ -1200,7 +1700,19 @@ all the time"*, and Clean Up *"deletes all unnecessary keys … keying the same
 multiple times in a row, keying the same values as the setup pose"*, because *"often
 it is convenient to set keys liberally when designing an animation, then use Clean
 Up afterward"* — [Keys](http://esotericsoftware.com/spine-keys). ⇒ a shipped export
-is dense, but it does not repeat a value.
+is dense, and what it does not carry is a key its own neighbours already imply.
+
+🧩 **⇒ A hold still needs a key at both ends, and two equal values are not a
+repeat.** Clean Up's *"keying the same value multiple times in a row"* is about
+**three or more** — a run of keys whose interior ones their neighbours imply. Two
+keys of equal value imply nothing: they are the only way to say *nothing moves here*
+on an interpolated timeline, and deleting either one ramps the value through the
+hold. Stillness is a thing a shot does, sometimes for a twelfth of a second and
+sometimes for nine, and it is authored, not omitted. ⇒ Key the start of a hold and
+key its end, at the same value; drop the ones in between. This is §9.2's *"held pose
+that is not held"* from the other side, and the same place catches it — a sloped
+hold shows up in `check`'s per-frame column and nowhere else, because it is cheap in
+every single frame and wrong only in the relation between two.
 
 📗 **Add a key when a curve cannot carry the shape.** *"If a curve is not smooth
 enough, it is easily remedied by adding another key"*, and the **Bounce** handle
@@ -1217,6 +1729,52 @@ minimal one-key-per-pose spec produces.
 one.** Reaching for a target density is guessing. The frames are the only thing that
 can say where the motion turns; §8 is how to read them.
 
+⚠️ **Two rules for a run that *fits* a pose series rather than reading it off the
+frames.** Neither is Spine's — no public page has an opinion about a fitter — but
+both decide where the keys above actually land, so they sit beside them. Both were
+paid for on the ladder. (**§8.1** is how the series gets fitted in the first place.)
+
+**A key tolerance on a rotation is not a number of degrees.** The same angular error
+costs a different number of pixels at every level of a hierarchy, because everything
+below the bone comes with it. Measured on rung 8's four-link chain: **a quarter of a
+degree on the last link moves the chain's end 0.15 px, and the same quarter degree
+on the plate the chain hangs from moves it 0.69 px.** One figure in degrees applied
+per property therefore keys the far end of the chain roughly four times too loosely
+while over-keying the near end — it is not one tolerance at all. ⇒ Declare **one**
+tolerance, **in pixels at the end of what the bone swings**, and convert it per bone
+by that bone's lever arm. With that, the whole trade reads as one curve and you can
+pick a point on it deliberately: that shot measured 0.6 px → 259 keys → 1.619 window
+MAE, 0.3 px → 300 → 1.402, 0.15 px → 377 → 1.305.
+
+**A rig's parameters are not identified by its pixels — remove the gauges before you
+key.** A bone that carries no attachment is an exact gauge: turn it by δ, turn its
+children back by δ, and **not one pixel changes**. Anything optimising against pixels
+is free to wander along that direction, and it does. On the spineboy run the figure's
+topmost body bone carries no art and every moving bone sits under it, and a
+coordinate descent walked it to **+181°** against its child's **−184°** — a pose
+whose picture is right on every frame and whose key series spins the whole figure
+through a full turn between two of them. The rendered result is correct and the
+authored rig is nonsense, and no amount of further fitting finds it, because every
+point on the gauge orbit has identical error. ⇒ Fold each gauge out *before* the
+series becomes keys — for a rotation gauge, take the median of the values along the
+chain and fold it back. The same shape exists wherever a transform is unobservable: a
+bone with no art, a slot-less parent chain, a uniform scale split across two bones.
+
+⚠️ **That fold is exact only when the gauge bone's children sit at its own origin** —
+and a character's body bone almost never has them there, which is the very shape the
+paragraph above was written from. Turn the parent by δ and a child *at the origin*
+back by δ and the child is where it was; a child sitting 10 units off swings through
+an arc of that radius first, and the counter-turn only spins it on the spot. The fold
+moves art, so it **changes the picture**. Measured on the second spineboy run, whose
+`hip` carries no attachment and has three children 9–13 units off it: the fold cost
+**3 MAE on every `idle` frame** — mean 23.0 with it against 19.9 without, same search
+— and it was removed. ⇒ Read the children's offsets before you fold. At the origin,
+fold: it is exact and it is cheap. Off the origin the degeneracy is still there but
+it is **soft**, not exact, and a soft degeneracy is *regularised, not folded* — leave
+the values alone and add a penalty on the gauge direction to the objective instead.
+That run used **2e-5 per squared degree** of hip rotation: invisible at animator-sized
+angles, and still decisive against the +181° against −184° above.
+
 ### 10.4 Curves
 
 📗 **Linear is what a *new* key gets, and it does not survive contact with a curve.**
@@ -1250,6 +1808,35 @@ and **Ease in** (*"the value changes more slowly near the next key"*) —
 across the file, is how an editor rig reads. Raw `curve` is R6's escape hatch — one
 key needing a shape no other key has — not the normal way to write a curve.
 
+🚨 **The table is a constraint on where the keys go, not a formatting step applied
+afterwards — it has to exist while the keys are chosen.** A run that plans its keys
+by fitting each span's **own** handles, and then writes the nearest entry of a named
+table, has bought a key count at one tolerance and shipped it at another. Nothing in
+the loop can see that: the timeline count, the key count, the curve kinds and the
+duration are all unmoved, so `diff` does not shift and the gate stays green, while
+the rendered result changes by a multiple. Rung 8's first version did exactly this
+and went from **1.07 to 4.65 MAE** — four times its own fit's floor. ⇒ Two passes.
+Pass A fits freely and exists only to *discover* which shapes the shot uses; those
+are clustered into the table; pass B re-plans **every** timeline under the table it
+will actually write. Never fit free handles and substitute the nearest named shape
+after the fact. (The table's size then trades against the key count at a fixed
+tolerance — that shot ran 4 easings/368 keys, 8/314, 12/300, 16/284 — because a
+richer table holds more spans.) This is rung 6's clamp defect in another suit:
+**a constraint that is not enforced where the value is written is not a
+constraint.**
+
+🧩 **⇒ A span with no interior sample takes the automatic handles, not linear.** Two
+keys on adjacent samples leave pass B nothing to fit — the samples cannot constrain
+that span's shape at all — and a planner with nothing to fit leaves `ease` off, which
+is linear (§4.5): the one shape this section says to argue for rather than default to.
+"No information" is not an argument for constant speed. Take instead the tangents the
+keys either side imply — the editor's own **automatic handles**, quoted above — and
+snap *those* to the nearest table entry, exactly as you would a fitted span. Rung 8's
+second version did this for its adjacent pairs and the samples barely moved (**17.34 →
+17.26 MAE**) while `curve_kinds` changed wholesale: nil in the frames, large in the
+structure, which is the signature of a convention rather than a fidelity fix — and
+this section's whole subject.
+
 📗 **Handles are normalised, and that is the shape an `easings` entry takes.** For a
 Bezier key, *"the X axis is from 0 to 1 and represents the percent of time between
 the two keyframes. The Y axis is from 0 to 1 and represents the percent of the