spine-rigc 0.16.0 → 0.17.0

package/cli.ts

@@ -114,6 +114,7 @@ import {
 } from './src/render.ts';
 import { CLI_DEFAULT_PROFILE, reportLines, validate, VALIDATE_PROFILES, type ValidateProfile } from './src/validate.ts';
 import { parseMotionSpec } from './src/motion.ts';
+import type { FoldLimit, TurnCeiling } from './src/depth.ts';
 import type { CompileResult } from './src/types.ts';
 
 /**
@@ -407,10 +408,72 @@ function runGate(
  * unconditionally, so a build whose only mesh was a ribbon or a contour got a
  * sentence about a rim ring and a seam it does not have.
  */
+/**
+ * What a depth map and a soft region put on a mesh, when it named either.
+ *
+ * The digests are the reason this prints at all: a claim about a rig can name
+ * WHICH sheet produced it, and two runs a reader believes differ can be shown to
+ * have read the same pixels. The ranges and counts are what say the input
+ * reached the geometry rather than merely being resolved — a `carried 0` never
+ * gets here (it is refused) and a `ramped 0` is a hard-edged mask, which is
+ * legal and usually not what somebody meant.
+ */
+/**
+ * One axis's two ceilings, as `+31.41 / -18.03`, or what is unbounded on it.
+ *
+ * ⚠️ `none` and a number are different claims and are printed differently. A
+ * sheet with no gradient along an axis cannot fold anything on it AT ANY ANGLE,
+ * which is a fact about the sheet worth reading; printing `90` for it would be
+ * a limit nothing measured.
+ */
+function ceilingPair(axis: { positive: FoldLimit | null; negative: FoldLimit | null }): string {
+  const one = (l: FoldLimit | null, sign: string) => (l === null ? `${sign}none` : `${sign}${l.degrees.toFixed(2)}°`);
+  return `${one(axis.positive, '+')} / ${one(axis.negative, '-')}`;
+}
+
+/** The tightest of the four, so the line that names a triangle names the right one. */
+function tightestFold(c: TurnCeiling): { kind: string; sign: string; limit: FoldLimit } | null {
+  const all = [
+    { kind: 'yaw', sign: '+', limit: c.yaw.positive },
+    { kind: 'yaw', sign: '-', limit: c.yaw.negative },
+    { kind: 'pitch', sign: '+', limit: c.pitch.positive },
+    { kind: 'pitch', sign: '-', limit: c.pitch.negative },
+  ].filter((e): e is { kind: string; sign: string; limit: FoldLimit } => e.limit !== null);
+  if (all.length === 0) return null;
+  return all.reduce((best, e) => (e.limit.degrees < best.limit.degrees ? e : best));
+}
+
+function meshDepthNote(m: CompileResult['meshes'][number]): string {
+  const parts: string[] = [];
+  if (m.depth) {
+    parts.push(
+      `depth "${m.depth.image}" ${m.depth.digest} near=${m.depth.near} zScale=${m.depth.zScale} ` +
+        `z=[${m.depth.range[0]}, ${m.depth.range[1]}]`,
+    );
+    const c = m.depth.ceiling;
+    parts.push(`turn ceiling  yaw ${ceilingPair(c.yaw)}   pitch ${ceilingPair(c.pitch)}`);
+    const worst = tightestFold(c);
+    parts.push(
+      worst === null
+        ? `              nothing in this sheet folds: ${c.measured} triangle(s) measured, none with a depth gradient across it`
+        : `              first to fold: ${worst.kind} ${worst.sign} at ${worst.limit.degrees.toFixed(2)}°, ` +
+          `triangle ${worst.limit.triangle} [${worst.limit.ids.join(',')}]` +
+          `${c.degenerate ? `; ${c.degenerate} triangle(s) too flat in setup to measure` : ''}`,
+    );
+  }
+  if (m.soft) {
+    parts.push(
+      `soft "${m.soft.mask}" ${m.soft.digest} -> ${m.soft.bone}, ${m.soft.carried} carried / ${m.soft.ramped} in the falloff`,
+    );
+  }
+  return parts.length === 0 ? '' : `\n        ${parts.join('\n        ')}`;
+}
+
 const MESH_KIND_NOTES: Record<CompileResult['meshes'][number]['kind'], string> = {
   ring: 'ring      rim ring pinned on the window edge, seam ring pinned on the mask contour, aperture moves',
   ribbon: 'ribbon    entry row pinned, rows share their weights so the strip lengthens without widening',
   contour: 'contour   the art\'s own silhouette, every vertex pinned to the slot bone (geometry, not a deformation)',
+  grid: 'grid      a lattice over the part window at stated column and row positions, every vertex pinned to the slot bone',
   authored: 'authored  geometry rigc did not build; it assumes nothing about the topology',
 };
 
@@ -796,7 +859,8 @@ function cmdBuild(flags: Record<string, string>): void {
   for (const m of result.meshes) {
     console.log(
       `  MESH  ${m.slot.padEnd(12)} ${m.kind.padEnd(8)} ${m.vertices} vertices / ${m.triangles} triangles  ` +
-        `${meshBudget(result.rig)}  bones=[${m.bones.join(', ')}]  attachments=[${m.attachments.join(', ')}]${meshFit(m)}`,
+        `${meshBudget(result.rig)}  bones=[${m.bones.join(', ')}]  attachments=[${m.attachments.join(', ')}]${meshFit(m)}` +
+        meshDepthNote(m),
     );
   }
   for (const ph of result.physics) {
@@ -2223,9 +2287,14 @@ function cmdExplain(flags: Record<string, string>): void {
     console.log('\nmeshes');
     for (const kind of new Set(result.meshes.map((m) => m.kind))) console.log(`  ${MESH_KIND_NOTES[kind]}`);
     for (const m of result.meshes) {
+      // The depth block belongs here more than it belongs in `build`: `explain`
+      // is the command that says what a spec MEANS, and the turn ceiling is the
+      // number an author needs before writing a key rather than after a refusal.
+      // It was absent, while `docs/AUTHORING.md` said both commands printed it.
       console.log(
         `  ${m.slot.padEnd(12)} ${m.kind.padEnd(8)} ${m.vertices} vertices / ${m.triangles} triangles  ` +
-          `${meshBudget(result.rig)}  bones=[${m.bones.join(', ')}]${meshFit(m)}`,
+          `${meshBudget(result.rig)}  bones=[${m.bones.join(', ')}]${meshFit(m)}` +
+          meshDepthNote(m),
       );
     }
   }

package/docs/AUTHORING.md

@@ -788,9 +788,11 @@ silhouette, and an octagon's sides pass `R · cos(π/8)` from its centre, so 5.7
 the drawing — its whole ink outline, between the spokes — was not going to be
 drawn, and every assertion passed (issue #277).
 
-The generators are `ring`, `ribbon` and `contour` (see
+The generators are `ring`, `ribbon`, `contour` and `grid` (see
 [`src/mesh.ts`](../src/mesh.ts)); the first two encode a deformation model rather
-than a table of numbers, which is why they are code invoked by data. A generator
+than a table of numbers, which is why they are code invoked by data. The last two
+are geometry: they pin every vertex to the slot bone and exist to give a
+`deform` timeline (§4.12) somewhere to push. A generator
 is for a skeleton with **no** manifest; a cut that has one invokes the same
 builders through the manifest's `mesh` block.
 
@@ -910,109 +912,206 @@ Self-intersection is refused; **holes are not cut out**; and nothing here does
 interior/Steiner points, so a contour mesh bends only where its outline has
 vertices.
 
-🖼️ **Worked example: [`gallery/flex`](https://github.com/firejune/rigc/tree/main/gallery/flex)** — four contours over real art, with
-the `tolerance`/`margin` sweep that picked their settings and what each one measured.
+#### `grid` — a lattice over the part window
 
-**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:** the part is a plate whose *surface* moves — a face that
+turns, a cloth that ripples — and a `deform` model (§4.12) needs interior
+vertices to push. A `contour` gives you the silhouette and nothing inside it;
+this gives you columns and rows.
 
-**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.
+It takes **no geometry and no size**: like a `contour`, the window is the
+attachment's own `image`, and every vertex is pinned to the slot bone at weight
+1, so an undeformed grid draws exactly what the region drew.
 
 ```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" } }
+"generator": { "kind": "grid", "us": [0.0235, 0.1471, 0.5, 0.8529, 0.9765],
+                               "vs": [0.0263, 0.2632, 0.5, 0.7368, 0.9737] }
 ```
 
-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.
+| `us` / `vs` | column and row positions across the window, `0..1`, ascending, at least two each. **Positions, not a count** |
+| `cols` / `rows` | an even division of the whole window instead. Refused beside `us`/`vs` |
+| `depth` | a depth map, below — this is the generator it was built for |
+
+⭐ **Positions, because [FACE §4.1](FACE.md) places columns where the drawing
+needs them.** The five above are `gallery/portrait`'s own — dense at the
+silhouette, sparse across the middle, and not reaching the window edge. A
+generator that could only divide evenly would be a step backwards from the table
+it replaces, and it does replace it: the selftest builds that exact mesh from
+those five numbers and requires it to come out identical to the 25 vertex pairs
+and 32 triangles the example shipped by hand.
+
+🚨 **The reason to generate this at all is the hull.** Spine's `hull` is a
+**count** — the first `hull` entries of the vertex list are the outline — so the
+perimeter must be listed first and in walk order (top row, right column, bottom
+row, left column), interior after. A hand-numbered grid written a row at a time
+puts interior vertices in the hull, and the mesh loads, draws and deforms wrong
+with nothing anywhere to say so. The generator satisfies that by construction
+rather than being checked afterwards.
+
+| The input | What you get |
+| --- | --- |
+| positions **and** a count | `states both positions ("us"/"vs") and a count ("cols"/"rows") … Drop one` |
+| neither | `A lattice is not a default` |
+| one axis only | `a lattice needs both axes` |
+| positions that do not ascend | `"us" is not ascending: [1]=0.6 and [2]=0.6` — equal neighbours put two vertices in one place and collapse a row of triangles to zero area |
+| a position outside `0..1` | `positions are fractions of the part window, 0..1` |
+| `cols` or `rows` under 2 | `it is a whole number of at least 2` |
 
-⚠️ **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.
+#### `depth` — give every vertex its own z, instead of one cylinder radius
 
-🚫 Under `--profile spine-html` 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 the default
-`--profile spine` accepts it; the refusal is policy, not validity.
+**On a `contour` or a `grid`.** A grid is the one it was built for: a turn
+needs interior vertices to move, and a contour has none of its own.
 
-**Path attachment** ([Spine: paths](http://esotericsoftware.com/spine-paths)) — a
-composite cubic Bezier, and the only attachment whose purpose is to be *followed*.
+A `yaw` or `pitch` key (§4.12) turns a part by treating it as painted on a
+cylinder: a vertex `u` off the axis gets `z = √(radius² − u²)`. That is the right
+model for a fringe or a plate that really does bend like a barrel, and the wrong
+one for a face — a nose is not on the skull's cylinder and an ear is behind it,
+and no single radius puts both where they are.
 
-**When you need one:** a path constraint has nowhere to aim without it (§3.5). The
-curve is not drawn — no runtime renders a path — and it deforms with its slot's
-bone like any other vertex attachment, so an animated path is a moving track.
+Name a **depth map** on the generator and every vertex gets its own `z`, sampled
+off a greyscale sheet in the part's own pixel grid:
 
 ```json
-"track": { "track": { "type": "path", "vertexCount": 9,
-                      "vertices": [-30, 0,  0, 0,  30, 0,  60, 0,  90, 0,
-                                   120, 0,  150, 0,  180, 0,  210, 0] } }
+"generator": {
+  "kind": "contour", "tolerance": 1.5, "margin": 2,
+  "depth": { "image": "face_depth.png", "near": "white", "zScale": 40 }
+}
 ```
 
-That is nine invented points forming a straight line: knots at x = 0, 90 and 180
-with their handles evenly spaced between them, which is the simplest path there is
-and the one worth reading twice.
-
 | Field | Meaning |
 | --- | --- |
-| `vertexCount` | **required**, and a multiple of 3 — see below |
-| `vertices` / `weights` | the same two encodings a mesh's geometry uses, with the same by-name default |
-| `closed` | default false. When true the last knot joins the first |
-| `constantSpeed` | default **true**: the runtime re-measures the curve every frame so travel along it is even. `false` makes it trust the emitted `lengths` instead — cheaper, and exact only while the path holds its setup shape |
-| `color` | `rrggbbaa`; the colour the editor draws the curve in |
-
-🚨 **`vertexCount` counts knots AND handles, and the arithmetic is not the one you
-would guess.** The vertices are walked in groups of three, and an **open** path
-drops the first and last point — those two are the outer control handles of the end
-knots, and no curve uses them. So:
-
-- an open path of K curves has `vertexCount = 3(K + 1)`, minimum **6** (one curve);
-- a closed one has `vertexCount = 3K`, minimum **3**, because the chain wraps.
-
-A count that is not a multiple of 3 does not throw anywhere:
-`Utils.newArray(vertexCount / 3, 0)` takes a fractional size happily, the groups of
-six then straddle the knots, and bones slide along a curve nobody drew. rigc refuses
-it, and `A33_VERTEX_ATTACHMENT_GEOMETRY` refuses it again on the artifact.
-
-⚠️ **`lengths` is not yours to write.** The emitted file carries one — the
-cumulative arc length at the end of each curve, in world units, in the setup pose —
-and rigc **measures** it off the geometry above, exactly as it measures a region's
-`width`/`height` off its PNG (R5). Writing one is a `CompileError`: it is a second
-copy of a number the vertices already determine, a copy that disagrees is only
-visible under `constantSpeed: false`, and there it silently rescales the whole
-traversal. `explain` prints the measurement, so `position: 0.25` on a curve that
-reports `180 long` is a bone at 45 units along it.
+| `image` | **required.** The sheet, relative to the rig's `images` directory, and the **same pixel size as this attachment's `image`**. It is not packed into the atlas — it is a measurement rigc reads at compile time, not art anything draws |
+| `near` | **required.** `"white"` or `"black"` — which end of the range is closest to the viewer. Stated rather than defaulted: both conventions are in use, and a sheet read with the wrong one turns the part inside out with every gate still green |
+| `zScale` | **required.** How many world units the map's full range spans, in the attachment's own units — the number `radius` used to carry. 8 bits of level say nothing about scale, so this is authored, never measured |
+| `gamma`, `contrast`, `bias` | the tone curve applied to the nearness, defaults `1` / `1` / `0`. State them when a consumer's own renderer curves the same sheet, so the mesh and that renderer describe one surface |
+
+The order is fixed and it matters, because every step is a place two
+implementations can silently disagree: **bilinear sample of the raw level** (at
+pixel centres, which is what a GPU's linear filter does), then `near`, then the
+curve clamped back into 0..1, then `zScale`. Naming a map changes no emitted byte
+on its own — a `yaw` or `pitch` key has to ask for it with `"depth": true`.
+
+`build` and `explain` report the sheet's digest (over the levels, so a re-encode
+of the same map reads the same) and the `z` range actually sampled, which is the
+number that says whether the map covers the part or a corner of it.
+
+⭐ **And the TURN CEILING — the angle to write on the key, before you write it.**
+
+```
+  MESH  face   grid  1089 vertices / 2048 triangles  (budget 3000)  bones=[face]
+        depth "face_depth.png" f552a2f50d21 near=white zScale=60 z=[0, 60]
+        turn ceiling  yaw +31.41° / -32.01°   pitch +32.01° / -31.41°
+                      first to fold: yaw + at 31.41°, triangle 960 [113,112,593]
+```
+
+Past that angle a triangle turns inside out and `A39` refuses the build by name.
+The loop this replaces is *pick an angle, build, read the refusal, guess again*.
+
+The arithmetic is exact and worth knowing, because it tells you what to change.
+A `yaw` sends each vertex to `x' = u·cos t − z·sin t`, so a triangle's area is
+`A₀·cos t − A_yaw·sin t` where `A_yaw` is the same area with **z substituted for
+u** — and it reaches zero at `tan t = A₀/A_yaw`. Three consequences:
+
+- ⚠️ **The ceiling is a property of the SHEET, not of the mesh.** Over a smooth
+  map the limit approaches `1 / max|dz/du|`, the reciprocal of its steepest
+  slope, with no mesh term in it. Refining the lattice does not lower the angle
+  — it finds slopes that were always there. So a ceiling you cannot live with is
+  fixed by editing the depth map, not by meshing differently:
+  [`docs/FACE.md` §2.2](FACE.md) has the measured ladder and the rule.
+- **The four numbers are four different answers**, each from its own triangle.
+  A part that turns 30° left and 18° right is ordinary, not an anomaly.
+- **`none` means no gradient on that axis**, and is a different statement from a
+  large number. A sheet varying linearly along one axis cannot fold the other at
+  *any* angle — `A_pitch` is then identically zero — so a linear ramp reports a
+  yaw ceiling and `pitch +none / -none`.
+
+⛔ It is a **report and never a refusal**. `A39` owns the refusal, from the
+artifact and through the runtime; a second wall here would be the compiler
+inventing a policy out of a measurement. What holds the two together is a
+control: `TC01` requires this number to be the angle `A39` actually fires at, on
+the triangle `A39` actually names, to 0.01°.
+
+🚨 **The one that will catch you: the sheet has to cover the mesh, and usually
+it does not.** A contour mesh puts every vertex *on* the silhouette and pushes it
+`margin` pixels outside; a grid spans the whole window, corners included. A depth
+sheet is usually cut to the art's own alpha, so both reach past it — and a naive
+sample gives those vertices the background depth and folds them away from the
+turn, with correct arithmetic and plausible numbers all the way down. rigc
+refuses it instead:
+
+| The input | What you get |
+| --- | --- |
+| a sheet cut to the art's alpha, on a **contour** | `does not cover 12 of the mesh's 12 vertices … A contour mesh puts every vertex ON the silhouette and pushes it out by the margin … Dilate the sheet past the mesh margin, or lower the margin.` |
+| a sheet cut to the art's alpha, on a **grid** | `does not cover 36 of the mesh's 81 vertices … A grid spans the whole part window, corners included … Dilate the sheet to the window, or state "us"/"vs" that keep the lattice inside the art.` — the two topologies run out of sheet for different reasons, and the message says which |
+| a sheet that is not the part's size | `the depth map … is 32x32 and the part is 64x64. A depth map is sampled in the part's own pixel grid` |
+| a colour sheet | `the depth map … is not greyscale — pixel (0, 0) is rgb(10, 200, 10)` |
+| `zScale` at or below 0 | `it is how many units the map's full range spans, so a positive number. To put the near end at the back, say "near": "black"` |
+| `gamma` or `contrast` at or below 0 | `collapses the range onto the midpoint … so the map would describe a flat part` |
+| a `near` that is neither | `it is "white" or "black"` |
+
+A sheet with **no alpha channel** covers its whole grid by construction and the
+coverage check has nothing to test; what its background level means is then your
+statement, and the reported range is where it shows up.
+
+##### `soft` — which part is soft, and which bone carries it
+
+A mesh can say **which vertices are soft**, so a `physics` constraint (§3.5) on
+their bone answers an impact over exactly that region — a chest, a cheek, a
+hanging sleeve.
+
+```json
+"generator": {
+  "kind": "grid", "cols": 9, "rows": 9,
+  "depth": { "image": "face_depth.png", "near": "white", "zScale": 40 },
+  "soft":  { "bone": "cheek_wobble", "mask": "cheek_soft.png" }
+}
+```
 
+| Field | Meaning |
+| --- | --- |
+| `bone` | **required.** The bone the region is carried by. It has to already exist — a bone a physics constraint targets is part of the skeleton, not a side effect of a mesh |
+| `mask` | **required.** A greyscale sheet in the part's own pixel grid: the level IS the weight, black still and white fully carried, sampled at each vertex. Alpha is not read — a transparent pixel is black |
+
+The remainder always stays on the slot bone, so every vertex closes at 1 by
+construction rather than by `A20` catching it later. `build` and `explain` report
+the mask's digest, how many vertices were carried outright and how many landed in
+the painted falloff.
+
+🚨 **Why a painted mask and not a depth threshold.** rigc tried the threshold —
+"the near part wobbles" — for exactly one day. It is wrong, and instructively so:
+**softness and prominence are different properties of a drawing.** The most
+prominent thing on a face is the nose, and a nose does not wobble. A threshold
+produced a region that was plausible, gated green and carried the wrong pixels.
+It also claimed something untrue — "no mask painted" — while the renderer this
+was modelled on had a hand-painted spring mask all along. rigc does not get to
+delete an input by guessing it.
+
+⭐ The falloff is painted for the same reason. A `feather` parameter would be
+rigc guessing the shape of something you can simply draw.
+
+**`A21_MESH_RIM_PINNED` splits on this rather than being relaxed.** A wobbling
+silhouette is *supposed* to move; the invariant is that nothing else does. Every
+vertex must be pinned to the slot bone or shared between it and the one declared
+bone, must close at 1, and at least one must actually be carried.
+
+| The input | What you get |
+| --- | --- |
+| a bone the rig does not declare | `names bone "x", which this rig does not declare … a bone a physics constraint has to target is part of the skeleton` |
+| the slot's own bone | `moves nothing — a soft region needs a bone that can move independently` |
+| a mask that is black everywhere | `carries no vertex of this mesh — every one of its 49 vertices samples black` |
+| a colour mask | `is not greyscale — pixel (0, 0) is rgb(10, 200, 10)` |
+| a mask that is not the part's size | `is 48x32 and the part is 96x64` |
+| a mask that is not on disk | `the soft mask "x.png" is not at …` |
+
+🚨 **What it cannot do yet.** A carried mesh has two bones on some vertices, and
+a `transform` key (§4.12) needs one coordinate space to be evaluated in — so the
+**angle** a raised surface turns through and the **impact** a soft one answers
+cannot ride the *same* attachment today. `SF03` holds that refusal, so the day it
+changes something fails and says so;
+[#389](https://github.com/firejune/rigc/issues/389) has the arithmetic showing it
+need not be true. Until then, put the two on separate slots.
 #### 3.4.1 A skin that switches bones and constraints on
 
 **When you need one:** a skin that is more than a change of art — a variant with an
@@ -2082,7 +2181,7 @@ example needed it:
 
 | `kind` | Parameters | What it evaluates | Worked case |
 | --- | --- | --- | --- |
-| `yaw` | `radius`, `degrees`, `about` | `dx = (x−about)·(cos t − 1) − z·sin t`, `z = √(radius² − (x−about)²)` — the 2.5D turn (FACE §1) | `gallery/portrait` |
+| `yaw` | `radius` **or** `depth`, `degrees`, `about` | `dx = (x−about)·(cos t − 1) − z·sin t`, with `z = √(radius² − (x−about)²)` from a cylinder or `z` read per vertex off a depth map — the 2.5D turn (FACE §1) | `gallery/portrait` |
 | `pitch` | the same | the same expression with `y` for `x` — a nod rather than a turn | `gallery/nod` |
 | `affine` | `scale`, `about` | `dx = (sx−1)·(x−ax)`, `dy = (sy−1)·(y−ay)` — a scale about a fixed point | `gallery/squash` |
 | `wave` | `amplitude`, `wavelength`, `phase`, `along`, `axis` | `d = amplitude · sin(2π·along/wavelength + phase)` | `gallery/nod` |
@@ -2105,6 +2204,24 @@ of a run leaves a **step at the run's edge**, and that is one half of the defect
 [#313](https://github.com/firejune/rigc/issues/313) records. If you want a
 partial run, write it.
 
+**There is no `parallax` kind, and the reason is worth stating.** A pure depth
+slide — `d = z · offset`, no angle — is this form with a term dropped: subtract
+them and the whole remainder is `u·(cos t − 1)`, independent of the depth, so
+the slide *is* a turn at a small angle (at 16° the gap is 2.32px, at 1°
+0.0091px, quartering with each halving). 🚨 And what it is for is not rigc's to
+state: a depth slide is a **camera** move, driven by a pointer rather than by a
+clock, and this spec is a timeline. What rigc states about a raised surface is
+the **angle** it may turn through, and — for a soft one — how it answers an
+**impact**. The camera belongs to whatever draws the result.
+
+**A turn projects off one surface, stated one way.** `"depth": true` reads each
+vertex's `z` off the map its attachment's generator names (§3.4) instead of
+deriving it from a `radius`; the closed form does not change, only where `z`
+comes from. Saying both is refused — they are two answers to how far forward a
+vertex sits, and a key carrying both leaves a reader unable to say which one the
+output came from. So is `"depth": true` on an attachment that named no map,
+rather than a silent fall back to a cylinder.
+
 **It is not a `rigc tween`.** MOTION §7 refuses a command that generates
 in-betweens and this is not one: the transform is evaluated **at one key**, from
 parameters that key states, and what happens between two keys is still the

package/docs/FACE.md

@@ -245,6 +245,139 @@ shape the drawing only implies. Two readings that help:
    measured 5.406 on the artifact. If the fringe does not read as separate,
    this is the one number to move, and moving it moves nothing else.
 
+### 2.1 One depth per part, and the limit of that
+
+Everything above states **one depth per part** — a stand-off the whole plate
+shares. That is the right resolution for a part list: the fringe is 26 in front
+of the skull, and arguing about which *pixel* of the fringe is 26 would be
+arguing past what the drawing says.
+
+It stops being the right resolution the moment a part's own surface is the
+subject. §4 meshes the face plate into columns precisely because the plate is not
+flat, and §4.2 then finds that refining those columns makes the fold **worse**,
+not better — the columns are sampling a cylinder that was never the shape of a
+face. A cylinder is one number pretending to be a surface, and past a certain
+density the pretence is what fails.
+
+⭐ **Two things had to arrive together, and both are now generated rather than
+written.** The lattice itself was hand-numbered — this example's 25 vertex pairs,
+32 triangles and hull walk were a person's arithmetic — and
+[AUTHORING §3.4](AUTHORING.md#grid--a-lattice-over-the-part-window)'s `grid`
+generator now builds it from the column positions alone, reproducing this one
+exactly. That is the prerequisite: a turn needs interior vertices to move, and
+§4.3's contour has none.
+
+⭐ **And a depth map is the number above becoming a surface.** A greyscale sheet in the
+part's own pixel grid gives every mesh vertex its own `z`, sampled where the
+vertex actually is, and `yaw`/`pitch` project off it with the same closed form as
+§1 — only the source of `z` changes. What it buys is stated where it is authored:
+[AUTHORING §3.4](AUTHORING.md#depth--give-every-vertex-its-own-z-instead-of-one-cylinder-radius),
+with the sampling order, the refusals and the one that matters most (a sheet cut
+to the art covers **none** of a contour mesh's vertices, because they all sit on
+the silhouette and outside it).
+
+⭐ **And the mesh really is evaluating the pixels' model — measured, not
+asserted.** A consumer that renders the same sheet in a shader displaces every
+PIXEL by its own depth; a mesh displaces vertices and interpolates across
+triangles. On a dome (a ramp would prove nothing — linear interpolation is exact
+on a linear field) at 18°, the two evaluations converge as the lattice refines:
+
+| lattice | 3×3 | 5×5 | 9×9 | 17×17 | 33×33 |
+| --- | --- | --- | --- | --- | --- |
+| mean disagreement, px | 6.4141 | 1.8452 | 0.5887 | 0.2276 | **0.0926** |
+| the same lattice reading a **cylinder** instead | 3.8972 | 3.1628 | 3.2558 | 3.3429 | **3.3777** |
+
+🚨 **Read the second row before the first.** A mesh evaluating the wrong surface
+does not converge — it settles at ~3.4px however dense it gets — and at 3×3 it
+reads *better* than the right one. So one measurement at one density cannot tell
+the two models apart, and would have picked the wrong one. The claim is the
+convergence, never a single number. (`CS01`–`CS03` in `selftest.ts`; the worst
+case falls more slowly than the mean and is expected to, because the dome's rim
+has an unbounded depth gradient.)
+
+⚠️ **This is not the same quantity as §4.2's fold angle, which refining makes
+WORSE.** Both are true: a finer lattice buys fidelity to the model and costs the
+angle at which a column pair inverts. This measures the first; `A39` refuses the
+second.
+
+⚠️ **It does not make depth measurable.** The map is relative — 8 bits of level
+say nothing about world units — so `zScale` is authored exactly as the fringe's
+26 was, and the two warnings above survive intact: get it right and the parallax
+is free, get it wrong and nothing complains. What the map removes is the
+*resolution* limit, not the judgement.
+
+### 2.2 The angle belongs to the map, not to the mesh
+
+§2.1 leaves an open question and it has now been measured. §4.2 finds that
+refining the lattice makes the fold **worse**, and read that as the cylinder's
+error surfacing — so per-vertex depth ought to have bought the angle back. ⛔ **It
+does not, and it never could have.**
+
+Two neighbouring vertices swap places when the turn tips one past the other,
+which is `tan t ≥ Δu/Δz` — so the largest turn a part supports is
+
+    tan t_max = 1 / max |dz/du|
+
+**the reciprocal of the steepest slope anywhere in its depth map**, and there is
+no mesh in that formula at all. Refining the lattice does not change the angle;
+it changes which slopes the lattice is close enough to *find*. A map with a
+vertical edge has an infinite slope there, so a fine enough mesh folds at any
+angle you name.
+
+⭐ **Which is exactly what a dome is.** `z = Z√(1 − r²)` is vertical at its rim,
+and an even lattice over it folds at `tan t = √h·√(R/2)/Z` for spacing
+`h = W/(side−1)` — a **√h** that goes to zero. Measured against that closed form
+over a 1,300× range of vertex counts, agreeing to ≤ 1.2°:
+
+| lattice | 5×5 | 17×17 | 33×33 | 65×65 | 129×129 | 181×181 |
+| --- | --- | --- | --- | --- | --- | --- |
+| **dome**, largest turn admitted | 62° | 41° | 31° | 23° | 17° | **14°** |
+| the closed form above | 59.0° | 39.8° | 30.5° | 22.6° | 16.4° | **14.0°** |
+| **raised cosine**, slope bounded | 73° | 65° | 64° | 64° | 64° | **63°** |
+| its closed form, `atan(2R/Zπ)` | 64.8° | 64.8° | 64.8° | 64.8° | 64.8° | **64.8°** |
+
+⇒ **Author the map so its slope is bounded, and the angle stops depending on the
+mesh.** A raised cosine — flat at the centre, flat again at the rim — holds
+63–64° from 289 vertices to 32,761. The dome loses three quarters of its angle
+over the same refinement. Both are "correct" depth; only one of them is a
+*surface a turn can be built on*, and the difference is entirely in the input.
+
+🚨 **So a map traced straight off a rendered normal or a photogrammetry pass is
+the dome case, not the cosine case.** Where the part curves away to its
+silhouette is where every such map goes vertical. Flattening it there — letting
+z reach its floor *before* the outline rather than at it — is the edit that buys
+the angle, and it is an edit to the sheet. rigc will not do it for you: the
+compiler never invents a value that is not in the spec, and a depth map is a
+measurement.
+
+⚠️ **This does not touch §2.1's convergence.** A finer lattice still evaluates
+the map's own surface more faithfully; it also finds steeper slopes in it. Those
+are two different quantities and both are true — §2.1 measures the first, `A39`
+refuses the second. What is new here is that the second is a fact about the
+sheet, and can be fixed there.
+
+⭐ **And you no longer have to find the ceiling by building into it.** `build`
+and `explain` print it for any mesh with a depth map — per axis, per direction,
+naming the triangle that goes first — from `tan t = A₀/A_axis` on the mesh's own
+geometry ([AUTHORING §3.4](AUTHORING.md)):
+
+```
+        turn ceiling  yaw +31.41° / -32.01°   pitch +32.01° / -31.41°
+                      first to fold: yaw + at 31.41°, triangle 960 [113,112,593]
+```
+
+Read it as a fact about **the sheet**. If the number is too small, the fix is in
+the map — flatten it where the part curves away — and not in the lattice.
+
+📐 Method, harness and the full ladders live in the repository rather than in
+this package, as
+[`bench/studies/2026-09-05-density`](https://github.com/firejune/rigc/tree/main/bench/studies/2026-09-05-density) —
+the same study also measures why `contour` is the wrong generator for a turn: it
+saturates at 868 vertices however fine the tolerance, its vertices all sit on the
+silhouette so it samples **2 %** of the depth range, and its ear-clipped interior
+holds triangles three orders of magnitude apart in area, the smallest of which
+reverse under a fraction of a pixel.
+
 ---
 
 ## 3. One shared shift, then residuals

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spine-rigc",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "Rig compiler for Spine — declarative rig specs in, Spine 4.3 skeleton data out, verified by a spine-core round-trip. Built so AI agents can author rigs and check their own work; the output imports into the Spine editor.",
   "type": "module",
   "bin": {