@ikijs/editor 0.9.0 → 0.10.1

package/README.md

@@ -49,60 +49,64 @@ leaves the document untouched.
 | Grid keyforms      | `computeGridOffsets`, `interpolateGridOffsets`, `upsertGridKeyform`                                                                                                      |
 | Factories          | `createDefaultPart`, `createDefaultMatrixDeformer`, `createDefaultWarpDeformer`, `createGridMesh`                                                                        |
 | Pixels             | `detectAlphaBbox`, `ALPHA_BBOX_THRESHOLD`, `AlphaBbox`, `ALPHA_OPAQUE`, `HEAD_BAND`, `SPECK_CORE_FRACTION`, `denseCoreOf`, `isSpeckCore`, `foregroundSpan`, `headHalfOf` |
-| Auto-rig           | `generateIkiFromLayerSet`, `parseLayerRoles`, `createLayerSetMeasurer`, `TurnTargets`, `DEFAULT_TURN_TARGETS`, `TurnSolveReport`                                         |
+| Auto-rig           | `generateIkiFromLayerSet`, `parseLayerRoles`, `createLayerSetMeasurer`, `TurnTargets`, `DEFAULT_TURN_TARGETS`, `TurnSolveReport`, `RigStyle`                             |
 | Bindings           | `captureBindingEndpoint`                                                                                                                                                 |
 
 ## Auto-rig
 
 `generateIkiFromLayerSet` turns role-named layers (`face`, `eye_L`, `eye_R`,
 `mouth`, plus optional `iris_*`, `brow_*`, `lash_*`, `hair_front`, `hair_back`,
-…) into a rigged model that blinks, gazes, opens its mouth, turns its head on a
-torso that follows and breathes, and emotes with its brows — including a
+…) into a rigged model that blinks, gazes, opens its mouth, turns its head over
+a torso that breathes, and emotes with its brows — including a
 hair-sway physics rig when a `hair_front` layer is present.
 
-On the turn the head's outline holds still — the bangs that draw it pin their
-own silhouette — while everything inside it slides: the face plate, its
-features, and the bangs' own inner strands. That slide is the plate's own ask, a
-quarter of its half-width, capped to what the held outline has room for when
-`turnTargets.headHalfWidth` was measured and uncut when it was not. That turn is
-**fitted, not tuned**: on a layer set with a `nose`, the cylinder's radius and
-each feature's own depth on top of that slide are solved from
-`options.turnTargets` — the cues a 30° reference measures (how far the eye pair
-slides, how much the far eye foreshortens, whether the silhouette holds),
-defaulting to `DEFAULT_TURN_TARGETS`. The features' slide is bounded by the art:
-every feature has to stay on the face plate, because past its contour the far
-eye is drawn over the side hair, which still bends with the plate inside that
-held outline and swallows it. Given `options.strandEdges`, the eyes are also
-kept from sliding the far iris under the bangs' side strand any further than it
-is painted — best effort, never a refusal: the fit prefers radii where some eye
-depth holds that, and where none does (a fringe spanning the face included) the
-rig is still built with the eyes' turn depth at 0. The report's `strandOverlap`
-gives, per side whose far iris the bangs' run still covers at some far stop,
-the covered width: how much of the iris's painted row the run covers at the
-stop where that is largest, in px and head half-widths, next to how much it
-covers at rest, and whether the bound held — `true` for an iris painted under
-its run that the turn took no deeper, `false` where the fitted radius could not
-hold it and the eyes' turn depth is 0.
-
-A target that came from the defaults is a style prior, not a measurement of
-this character, so it is **clamped** to what the layer set can do and the rig is
-built. So is an `eyeShift` you passed that runs past the room the art leaves the
-far eye — the face plate's edge, or the bangs' strand — since that room is a
-fact about these layers, not about the reference. Every other target you passed
-that this layer set cannot reach **throws**, naming the field and the range it
-could have had: a `farEyeRatio` or `silhouetteRatio` no radius renders, a
-`noseShift` / `mouthShift` outside what that feature can reach, or an
-`eyeShift` smaller than the slide the face's own turn already gives the eyes.
-Pass `options.onTurnSolved` to see what the turn settled on and which targets
-were clamped.
+The rig reproduces a Live2D default rig, measured on the Cubism sample models
+(the numbers are in `auto-rig/profile.ts`): the turn reads through parallax,
+not a reshaped face. The face plate translates, changing its width by a few
+percent, the chin leading it; the features lead the plate by their own amounts
+(the nose most, then the brows, eyes and mouth), the eyes foreshortening mildly
+about their own centres; the front hair rides the face where it lies over it and holds the head's
+outline where it draws it, and the back hair stays behind; the neck and the
+ears the face layer paints are cut off into islands of the plate's own mesh,
+drawn behind the head — the neck stays (only the chin's shade slides across
+it), the ears lag the face. AngleZ rolls the head 10° about the chin; the torso only
+breathes.
+
+On a layer set with a `nose`, `options.turnTargets` — the cues a 30° reference
+measures (how far the eye pair slides, how much the far eye foreshortens,
+whether the silhouette holds) — are **fitted** each by the one knob it reads:
+the turn's amount, the eyes' foreshortening, the hair's width, a feature's own
+shift. With none given the profile itself renders (`DEFAULT_TURN_TARGETS`
+expresses it in the cues' units). `options.style` tunes a character from the
+profile where the Live2D samples themselves disagree: the whole turn, the
+features' lead, the front hair's follow and its outline's, the blink and the
+hair sway. The turn
+is bounded by the art: the far eye stays inside the plate's outline and, given
+`options.strandEdges`, the far iris may not slide under the bangs' side strand
+any further than it is painted — best effort, never a refusal. The report's
+`strandOverlap` gives, per side whose far iris the bangs' run still covers at
+some far stop, the covered width: how much of the iris's painted row the run
+covers at the stop where that is largest, in px and head half-widths, next to
+how much it covers at rest, and whether the bound held.
+[`AUTO-RIG.md`](./AUTO-RIG.md) describes the model, the fit and the limits.
+
+An `eyeShift` you passed that runs past the room the art leaves the far eye —
+the face plate's edge, or the bangs' strand — is **clamped** and the rig is
+built, since that room is a fact about these layers, not about the reference;
+so is the profile's own turn where the art has less room than it needs. Every
+other target you passed that this layer set cannot reach **throws**, naming the
+field and the range it could have had: a `farEyeRatio` or `silhouetteRatio`
+out of the rig's reach, or a `noseShift` / `mouthShift` outside what that
+feature can reach. Pass `options.onTurnSolved` to see what the turn settled on
+and which targets were clamped.
 
 `turnTargets.headHalfWidth` is what the shift targets are fractions of, when a
 caller has measured the actual head (the face plate stands in otherwise).
 Alongside it, `options.headEdges` names, per side, every layer with an opaque
 pixel at the eye row and its own rest x there — a companion to a measured
 `headHalfWidth`, absent otherwise — so the solver can land each candidate
-through its OWN part's deformation (the bangs move with their hold, the back
-hair holds still, a face-plate or body edge slide) rather than assume the head
+through its OWN part's deformation (the bangs ride the face, the back hair
+stays behind it, a face-plate edge slides) rather than assume the head
 is centred on the face plate or that whichever part drew furthest out at rest
 is still the furthest out after it turns.
 

package/dist/index.d.mts

@@ -657,343 +657,207 @@ interface AlphaBbox {
 declare function detectAlphaBbox(rgba: ArrayLike<number>, width: number, height: number): AlphaBbox | null;
 
 /**
- * Role table, role parsing, bbox→transform math, and model assembly for the
- * AI auto-rig generator. All pure functions — no DOM, no canvas, no
- * crypto.randomUUID.
- *
- * L/R = CHARACTER frame: *_L is the character's left = screen right.
+ * Per-character tuning, starting from the profile: only the quantities the
+ * Live2D samples themselves disagree on by more than their own median
+ * (style, not construction). `turn`, `featureLead` and `sway` multiply the
+ * profile (1 = as measured); `hairFollow`, `outlineFollow` and `blink`
+ * replace its value.
  */
+interface RigStyle {
+    /** The whole turn — plate, features and hair (the samples' face slides
+     *  0.05–0.25 hh). Ignored when a `turnTargets.eyeShift` is given, which
+     *  fits it instead. */
+    turn?: number;
+    /** How far the features lead the plate (the nose leads it 2.2–4.4×). */
+    featureLead?: number;
+    /** The front hair's share of the face's turn (the samples' 1.0–1.37;
+     *  profile 1.1). */
+    hairFollow?: number;
+    /** Its outer edge's share, where the front hair draws the head's outline
+     *  (profile 0: the outline holds; `hairFollow` rides it whole). */
+    outlineFollow?: number;
+    /** How far the upper lid comes down, over the eye's height (0.30–0.67). */
+    blink?: number;
+    /** Hair sway amplitude (0.02–0.36 hh at the extremes). */
+    sway?: number;
+}
 
 /**
- * Input contract from the host app to this package's auto-rig functions.
- * Passed in after the host has decoded PNGs, computed alpha bboxes, and
- * mapped filenames to canonical roles.
+ * The public shapes of the auto-rig: what a host hands `generateIkiFromLayerSet`
+ * and what the turn solve reports back. Pixel measurement lives in
+ * `layer-measure.ts`; everything here is already-decoded geometry.
  */
+
+/** One role layer, as a host measured it off its decoded pixels. */
 interface LayerInput {
-    /** Canonical role, e.g. "eye_L". */
+    /** Canonical role (see `parseLayerRoles`); becomes the part id. */
     role: string;
-    /** Original file name — used in error messages and as a stable id. */
     fileName: string;
-    /** Shared canvas width (all layers have the same canvas size). */
     canvasW: number;
-    /** Shared canvas height. */
     canvasH: number;
-    /** Alpha-tight bounding box, top-left origin, +y down (image coords). */
+    /** Alpha bounding box in canvas px (y down) — the crop the atlas holds. */
     bbox: {
         x: number;
         y: number;
         w: number;
         h: number;
     };
-    /** Cropped image width = bbox.w. */
     cropW: number;
-    /** Cropped image height = bbox.h. */
     cropH: number;
-    /**
-     * The layer's painted half-width on every CROP row, top → bottom, one entry
-     * per row (`cropH` of them): half the row's opaque span in canvas px under
-     * the same alpha ≥ 128 rule the head's `headEdges` are measured with
-     * (`createLayerSetMeasurer`), 0 for a row with no opaque pixel.
-     * Optional, and only the FACE's is read: it gives the face plate a
-     * row-dependent turn radius and a chin swing (`faceRowProfile`,
-     * `turnSurface`); absent — from a host that does not measure it — the plate
-     * turns on one radius on every row. Validated before anything reads it: an
-     * array of length `cropH` whose every entry is a finite number in
-     * [0, cropW / 2], the most an inclusive span inside the crop can be.
-     */
+    /** Face only: half the opaque span of each crop row, canvas px (0 = none). */
     rowHalfWidths?: number[];
-    /**
-     * The tight box of the layer's alpha ≥ 128 pixels, in image coords like
-     * `bbox` and NOT grown: the drawing a viewer reads inside a soft feather,
-     * which the crop's alpha ≥ 8 rule takes in whole. Optional, and only the
-     * NOSE's is read: its centre and width are the nose's turn landmark
-     * (`turnLandmarks`), so a shaded nose is fitted by the drawing rather than
-     * by its feather, and its top edge at its centre x is the bridge top the
-     * nose tilts about on the turn (`NOSE_TURN_TILT_DEG`). Absent — from a
-     * host that does not measure it — the crop stands in for both. Validated
-     * before anything reads it: a plain object whose x, y, w and h are finite,
-     * w and h positive, and the box inside `bbox`.
-     */
+    /** Nose only: the tight box of its alpha ≥ 128 pixels, canvas px. */
     denseCore?: {
         x: number;
         y: number;
         w: number;
         h: number;
     };
+    /** Face only: per crop column, the canvas row of the last pixel of the
+     *  first dark stroke met going down from the plate's widest row (the jaw's
+     *  outline, across a neck), or −1 where the column leaves the paint first.
+     *  Where the head ends and the neck the body keeps begins. */
+    jawRows?: number[];
 }
 /**
- * Map an array of raw filenames to canonical `{ role, fileName }` pairs.
- *
- * Steps:
- *   1. Normalize each filename → role (normalizeRole).
- *   2. Eagerly check each role against ROLE_TABLE — unknown roles throw early
- *      with the offending fileName included in the message.
- *   3. Call assertRoleSet to check duplicates + required roles.
- *
- * Throws a path-qualified Error on any contract violation.
- */
-declare function parseLayerRoles(fileNames: string[]): {
-    role: string;
-    fileName: string;
-}[];
-/**
- * One side's iris and the bangs' run it would slide under on the turn, as
- * real pixel boundaries on ONE image row — the row holding that iris's centre
- * — in model coordinates: x is canvas x minus half the canvas width, like
- * `bboxToTransform`'s crop edges, and `y` is that row's centre. Every x is the
- * painted edge facing its clear neighbour, read under one opacity rule, so the
- * gap between an iris edge and a run edge is a real distance with no margin to
- * add. "Outer" is toward the head's edge on that side. The run is the one a
- * producer judges a strand: it may skip runs it judges hair detail
- * (`createLayerSetMeasurer` treats those narrower than half the iris's
- * painted width on the row as clear), so an iris under only such a wisp counts
- * as clear.
- *
- * One shape covers three cases:
- *   - an ordinary side strand outward of a clear iris (`runFace` outward of
- *     `irisOuter`);
- *   - a run over the iris centre that clears on the face side (`runFace`
- *     inward of that centre);
- *   - a fringe spanning the face: the run still covers the OTHER iris's
- *     centre, so it has no face-side end on this side and `runFace` is
- *     `null` — an absent edge, not an invented one.
+ * One side's iris against the `hair_front` run it would slide under on the
+ * turn, on the row holding the iris centre. Model coordinates: x is canvas x
+ * minus half the canvas width, y is half the canvas height minus canvas y.
  */
 interface IrisStrand {
-    /** The iris row's centre, model y. */
     y: number;
-    /** The outer end of that iris layer's opaque span on the row. */
     irisOuter: number;
-    /** Its inner end, toward the face. */
     irisInner: number;
-    /** The outer end of the `hair_front` run the iris would slide under. */
     runOuter: number;
-    /** The run's face-side end, or `null` when it reaches the other iris's
-     *  centre. */
+    /** The run's face-side end; `null` for a fringe spanning the face. */
     runFace: number | null;
 }
 /**
- * What a head does at full turn, as the cues `measure_turn_reference` reads off
- * a front/turned reference pair. The turn is fitted to these — the cylinder's
- * radius and the features' depths are solved from them, not tuned.
- *
- * Every field is optional: `DEFAULT_TURN_TARGETS` supplies the three a
- * reference measures, and the nose and the mouth derive from the eyes when they
- * are not given.
- *
- * What happens when the layer set cannot reach a target depends on where the
- * target came from. A number the CALLER passed is a measurement, so an
- * unreachable one throws, naming the field and what was on offer — except a
- * `silhouetteRatio` when no ratio in its own [0.5, 1.5] range renders on this
- * layer set: that throw names the field and the whole range instead of an
- * offer, since there is none narrower. Leaving the field out still rigs,
- * because a defaulted one clamps.
- *
- * A number this module filled in — a default, or a nose/mouth derived from the
- * eyes — is a style prior, not a promise about this character: it is CLAMPED
- * to what the layer set can do and the rig is built. The alternative is a
- * generator that refuses its own defaults, which would leave a perfectly good
- * layer set with no model at all. `solveTurnModel` reports which fields it
- * clamped.
- *
- * One measurement is clamped too: an `eyeShift` past the room the art leaves
- * the far eye — the face plate's edge, and the bangs' side strand when
- * `strandEdges` is given — whoever passed it. That room is a fact about this
- * layer set, not about the reference the shift was measured on, so the rig
- * takes as much of the shift as the art allows and keeps fitting the other
- * cues. An `eyeShift` below the slide the face's own turn already gives the
- * eyes is still refused: no depth reaches it.
+ * Head-turn cues at ±30°, as `measure_turn_reference` reads them off a front
+ * and a turned image. Shifts are fractions of the head half-width, taken as
+ * magnitudes: that tool signs them by the reference's turn direction.
  */
 interface TurnTargets {
-    /** How far the eye pair's centre slides toward the far side at full turn, as
-     *  a fraction of the head's half-width. The sign is ignored: which way is
-     *  the turn's own business. */
     eyeShift?: number;
-    /** The far eye's width over the near eye's at full turn, divided by the same
-     *  ratio at rest. 1 is no foreshortening; 0 is an edge-on far eye. */
     farEyeRatio?: number;
-    /** The head's half-width at full turn over its half-width at rest, as a
-     *  RENDER measures it — the outermost opaque edge on each side, whichever
-     *  part owns it. 1 holds the silhouette; below 1 narrows it. The hold that
-     *  produces it is fitted to it, so a measured one is met or refused, never
-     *  quietly rendered as something else. */
     silhouetteRatio?: number;
-    /** `eyeShift` for the nose. Derived from `eyeShift` when absent. */
     noseShift?: number;
-    /** `eyeShift` for the mouth. Derived from `eyeShift` when absent. */
     mouthShift?: number;
-    /** The head's own half-width at the eye row, in canvas px: what the shift
-     *  fractions are fractions OF, and the rest distance the silhouette hold
-     *  pivots on. Without it both fall back to the face plate's half-width, which
-     *  is narrower than the head the hair draws, so the shifts land short — an
-     *  approximation for callers that have no pixels, not a default to prefer. */
+    /** The head half-width the shifts are fractions of, canvas px. */
     headHalfWidth?: number;
 }
-/**
- * A `turnTargets` field this generator will not build a rig from: not a number,
- * outside its range, unreachable on this layer set, or a measured head narrower
- * than the face plate it is drawn around. Every one of them carries a number
- * the CALLER passed, so a host can tell them apart from the invariant breaks the
- * rest of the generator throws and report them as bad input instead of failing.
- */
+/** A turn target this layer set cannot reach, or turn input that is malformed. */
 declare class TurnTargetError extends Error {
     constructor(message: string);
 }
 /**
- * The reference the turn is fitted to when the caller measured none of its own:
- * a 3/4 portrait, which `measure_turn_reference` reads as 0.671 / −0.224 /
- * 1.012 (its raw turned far/near iris ratio is 0.71 — 0.67 is that ratio
- * normalised by the same ratio at rest, which is what the field means).
- * The silhouette is held exactly: a 1 % change is inside that tool's own noise.
+ * The Live2D profile's own turn (`profile.ts`), in the cues' units — what a
+ * rig with no `turnTargets` renders on a head whose silhouette at the eye row
+ * is back hair about 1 hh (eye row → chin) wide. eyeShift: the eye pair moves
+ * 0.211 hh at ±30 and that silhouette's centre −0.009 hh, over a 1 hh head
+ * half-width, 0.22. farEyeRatio: the far eye narrows to 0.85 and the near one
+ * widens to 1.085, and the cue is their ratio, 0.78. silhouetteRatio: the
+ * silhouette holds its width.
+ *
+ * With no target given the rig renders the profile itself, whatever the cues
+ * then read on its art (a head whose side locks draw its silhouette, and ride
+ * the face, reads a smaller eyeShift); a given target is fitted.
  */
 declare const DEFAULT_TURN_TARGETS: Readonly<Required<Pick<TurnTargets, "eyeShift" | "farEyeRatio" | "silhouetteRatio">>>;
-/** The turn depth of each feature family: the share of the pinned bulk slide
- *  (`headTurnParallaxUnit`) it gets back at full turn. Solved, never tuned. */
+/** How far each feature family stands in front of the plate, as the depth a
+ *  rotation would need to give its shift at ±30 (shift / sin 30°), in head
+ *  half-widths — the nose leads the mouth and the mouth the eyes. */
 interface TurnDepths {
     eye: number;
     nose: number;
     mouth: number;
 }
-/** What the turn solve settled on, for a caller that wants to see it — the
- *  cues it reached and the targets it had to cut down to reach them. */
+/** How much of a far iris's painted row the bangs' run covers. */
+interface StrandOverlap {
+    /** The turn stop (AngleX, degrees) where the coverage is largest. */
+    deg: number;
+    /** Covered width there, canvas px. */
+    px: number;
+    /** The same in head half-widths. */
+    hh: number;
+    /** Covered width at rest. */
+    restPx: number;
+    /** Whether the iris went no deeper under the run than it is painted.
+     *  Always `false` for a fringe spanning the face (`runFace: null`), which
+     *  has no side to keep the iris clear of. */
+    held: boolean;
+}
 interface TurnSolveReport {
-    /** Cylinder radius the face-warp bake and the parallax unit were built on. */
+    /** The curvature the plate would need to put the eyes as far in front of
+     *  its edge as their lead over it does, as a radius, canvas px. */
     radius: number;
-    /** Rest distance from the face centre the silhouette hold pivots on. */
+    /** The measured head half-width, canvas px, which the shift cues are
+     *  fractions of — on a set with none measured (hairless) the face crop's
+     *  half-width, while the cues are then fractions of the plate's painted
+     *  half-width at the eye row. */
     holdBase: number;
     depths: TurnDepths;
-    /** What the rig actually reaches, in the targets' own units. */
+    /** What the rig renders at ±30° (mean of both directions). */
     achieved: {
         eyeShift: number;
         farEyeRatio: number;
         silhouetteRatio: number;
     };
-    /** The targets the rig fell short of, cut down to what it can reach: every
-     *  defaulted field it could not reach, and an `eyeShift` — the caller's own
-     *  too — past the room the art leaves the far eye (the face plate's edge,
-     *  and the bangs' strand when `strandEdges` was given). Empty when every
-     *  target was met. */
+    /** Targets cut down to what this layer set can do. */
     clamped: (keyof TurnTargets)[];
-    /** Per side whose far iris the bangs' run covers at some far stop at the
-     *  fitted radius and depth (`options.strandEdges`): how much of it. Absent
-     *  when no side has an entry. Never a clamp: `clamped` still names an
-     *  `eyeShift` the strand bound cut short. */
     strandOverlap?: {
         left?: StrandOverlap;
         right?: StrandOverlap;
     };
 }
+interface HeadEdges {
+    left: {
+        role: string;
+        x: number;
+    }[];
+    right: {
+        role: string;
+        x: number;
+    }[];
+}
+interface GenerateOptions {
+    turnTargets?: TurnTargets;
+    /** Per-character tuning from the profile's defaults (`profile.ts`). */
+    style?: RigStyle;
+    onTurnSolved?: (report: TurnSolveReport) => void;
+    headEdges?: HeadEdges;
+    strandEdges?: {
+        left?: IrisStrand;
+        right?: IrisStrand;
+    };
+}
+
 /**
- * How much of one side's far iris the bangs' run covers: the length of the
- * landed iris span `[irisOuter, irisInner]` on its row that lies inside the
- * landed run `[runOuter, runFace]` — face-ward without end for a run with no
- * face-side edge (`runFace: null`) — at the far stop where that is largest.
- * Always read off real landed boundaries (`IrisStrand`).
+ * Map file names to roles. Throws on an unknown role, a role named twice, or
+ * a required role (`face`, `eye_L`, `eye_R`, `mouth`) missing.
  */
-interface StrandOverlap {
-    /** The far stop the covered width is largest at, degrees. */
-    deg: number;
-    /** That covered width, px. */
-    px: number;
-    /** `px` over the head half-width the shift cues are fractions of. */
-    hh: number;
-    /** The covered width as painted, at rest, px. */
-    restPx: number;
-    /** Whether this side's strand bound held at the fitted depth — the iris
-     *  kept no deeper under the run than it is painted, at every far stop. When
-     *  false the fitted radius could not hold it (always so for `runFace:
-     *  null`), the eyes' turn depth is 0, and `px` is the coverage that is
-     *  left. */
-    held: boolean;
-}
+declare function parseLayerRoles(fileNames: string[]): {
+    role: string;
+    fileName: string;
+}[];
+
 /**
- * Auto-rig: given decoded layer inputs and the shared canvas size, produce a
- * valid IkiModel ready for parseIkiModel.
- *
- *   - Validate all inputs before deriving anything.
- *   - Place parts at source-derived positions (bboxToTransform, unshifted).
- *   - Emit the standard parameters (STANDARD_PARAMETERS), plus a conditional
- *     HairSwayX/Z pair + hair-sway physics rigs when a hair_front layer is
- *     present.
- *   - Size every turn group's grid to its own members and the virtual lattice
- *     to those grids, then solve the turn on them (turnSetup, solveTurnModel):
- *     one surface — radius, travel, the head-level nod radius — that every
- *     bake below samples.
- *   - Build headDeformer (matrix, neck pivot, nod/tilt/breath bindings — the
- *     turn translates nothing rigidly; its travel is in the group grids), one
- *     warp deformer per turn group present — `faceWarp` for the plate,
- *     `eyeWarp_L/R`, `mouthWarp`, `noseWarp`, `browWarp_L/R`, `blushWarp_L/R`
- *     — each a warp2d over its own grid baked from that surface with the
- *     family's solved depth as keyform geometry (bakeTurnGroupWarp2D), and
- *     bodyDeformer when a body layer is present (matrix, torso-base pivot,
- *     AngleX follow + Breath follow).
- *   - Mesh parts (spec.mesh===true) → width:1, height:1, pixel grid mesh sized by
- *     meshCellsFor + role bindings, each face-family part on its group's warp.
- *   - Static parts (spec.mesh===false) → width:cropW, height:cropH, no mesh.
- *   - Part ids equal the role string (deterministic, no crypto.randomUUID).
- *   - Return parseIkiModel(structuredClone(model)) — every caller gets a
- *     validated model; bad assembly fails loudly.
+ * `generateIkiFromLayerSet`: role layers in, a rigged `.iki` out.
  *
- * `options.turnTargets` is what the head turn is fitted to: the cues a 30°
- * reference measures, defaulting to DEFAULT_TURN_TARGETS. A target the CALLER
- * passed that this layer set cannot reach throws; one that came from the
- * defaults is clamped to what it can do, and so is a caller's `eyeShift` past
- * the room the art leaves the far eye — see TurnTargets for why, and pass
- * `options.onTurnSolved` to see which ones were clamped and what the turn
- * ended up reaching.
- *
- * `options.strandEdges` gives each side's iris and the bangs' run it would
- * slide under as measured pixel edges (`IrisStrand`), and with it the turn
- * keeps each far iris from sliding under that run any further than it is
- * painted, best effort: where no radius the fit can use holds that, the rig
- * is still built, with the eyes' depth at 0, and the report's
- * `strandOverlap` says how much of the iris the bangs cover.
+ * The rig's shape follows a Live2D default rig (`profile.ts`): a torso that
+ * only breathes; a head deformer that rolls about the chin and breathes; one
+ * small warp grid per feature (each eye, each brow, the nose, the mouth),
+ * translating and foreshortening it by its own lead over the plate; and the
+ * plate, the hair and the blush moved by per-vertex keyforms of their own —
+ * the plate as up to four islands of one drawing: a head that slides, a neck
+ * that stays and two ears that lag. Blink, gaze, brows, mouth, breath and
+ * hair sway are part warps and bindings under those.
  */
+
 declare function generateIkiFromLayerSet(layers: LayerInput[], canvas: {
     width: number;
     height: number;
-}, options?: {
-    turnTargets?: TurnTargets;
-    /** Called once, after a turn is solved, with what it settled on. Not called
-     *  for a layer set without a nose, which solves no turn at all. */
-    onTurnSolved?: (report: TurnSolveReport) => void;
-    /** Every role with an opaque pixel in the eye-row band, per side, when
-     *  `turnTargets.headHalfWidth` was measured off that same union — a
-     *  companion to it, not a turn target itself (the caller-facing contract
-     *  stays the three cues). See `TurnSolveContext.headEdges`. */
-    headEdges?: {
-        left: {
-            role: string;
-            x: number;
-        }[];
-        right: {
-            role: string;
-            x: number;
-        }[];
-    };
-    /** Per side (`left` the −x side, `right` the +x side, like `headEdges`),
-     *  that side's iris and the bangs' run it would slide under on the turn,
-     *  as real pixel edges on the row holding the iris's centre — see
-     *  `IrisStrand` for the contract and its three cases (a strand outward of
-     *  a clear iris, a run over the iris centre that clears on the face side,
-     *  a fringe spanning the face). A side's iris is whichever of `iris_L` /
-     *  `iris_R` sits on that side; the sides are independent, so either may
-     *  be absent. With it the turn keeps each far iris from sliding under its
-     *  run any further than it is painted, best effort: never a refusal. The
-     *  report's `strandOverlap` gives, per side whose far iris the run still
-     *  covers at some far stop, the covered width at the stop where it is
-     *  largest, next to the painted one, and whether the bound held — `true`
-     *  for an iris painted under its run that the turn took no deeper,
-     *  `false` where the fitted radius could not hold it and the eyes' turn
-     *  depth is 0. It is always
-     *  validated against the layers first (`validateStrandEdges`), but only
-     *  the turn solve reads it, so like `headEdges` it has no effect on the
-     *  rig without a nose; absent or `{}`, the rig is the one built without
-     *  it. */
-    strandEdges?: {
-        left?: IrisStrand;
-        right?: IrisStrand;
-    };
-}): IkiModel;
+}, options?: GenerateOptions): IkiModel;
 
 /**
  * The alpha rules a layer set is measured by, and the pre-rig measurement of
@@ -1380,4 +1244,4 @@ declare function createGridMesh(cols: number, rows: number): IkiMesh;
  */
 declare function createDefaultWarpDeformer(model: IkiModel): IkiWarpDeformer;
 
-export { ALPHA_BBOX_THRESHOLD, ALPHA_OPAQUE, ATLAS_PADDING, AddDeformer, AddPart, AddPhysicsRig, type AlphaBbox, type ApplyAtlasInput, type AtlasAssignment, type AtlasLayout, type AtlasPlacement, type AtlasSource, CaptureGridKeyform, DEFAULT_TURN_TARGETS, type DeformerTransformChannel, DeleteDeformer, DeletePart, DeletePhysicsRig, type EditCommand, type EditTransformChannel, EditorDocument, HEAD_BAND, type IrisStrand, type LayerInput, type LayerSetMeasurement, type LayerSetMeasurer, type RgbaLayer, SPECK_CORE_FRACTION, SetDeformerBindings, SetDeformerParent, SetDeformerPivot, SetDeformerPivotX, SetDeformerPivotY, SetDeformerTransform, SetPartBindings, SetPartColor, SetPartDeformer, SetPartHeight, SetPartMesh, SetPartOrder, SetPartTransform, SetPartWidth, SetPhysicsRig, type StrandOverlap, type TurnDepths, type TurnSolveReport, TurnTargetError, type TurnTargets, UV_INSET_PX, captureBindingEndpoint, computeGridOffsets, createDefaultMatrixDeformer, createDefaultPart, createDefaultWarpDeformer, createGridMesh, createLayerSetMeasurer, denseCoreOf, detectAlphaBbox, foregroundSpan, generateIkiFromLayerSet, headHalfOf, interpolateGridOffsets, isSpeckCore, packAtlas, parseLayerRoles, upsertGridKeyform, uvRectFor, validateDeformerDelete, validateDeformerReparent, validatePartAttach };
+export { ALPHA_BBOX_THRESHOLD, ALPHA_OPAQUE, ATLAS_PADDING, AddDeformer, AddPart, AddPhysicsRig, type AlphaBbox, type ApplyAtlasInput, type AtlasAssignment, type AtlasLayout, type AtlasPlacement, type AtlasSource, CaptureGridKeyform, DEFAULT_TURN_TARGETS, type DeformerTransformChannel, DeleteDeformer, DeletePart, DeletePhysicsRig, type EditCommand, type EditTransformChannel, EditorDocument, HEAD_BAND, type IrisStrand, type LayerInput, type LayerSetMeasurement, type LayerSetMeasurer, type RgbaLayer, type RigStyle, SPECK_CORE_FRACTION, SetDeformerBindings, SetDeformerParent, SetDeformerPivot, SetDeformerPivotX, SetDeformerPivotY, SetDeformerTransform, SetPartBindings, SetPartColor, SetPartDeformer, SetPartHeight, SetPartMesh, SetPartOrder, SetPartTransform, SetPartWidth, SetPhysicsRig, type StrandOverlap, type TurnDepths, type TurnSolveReport, TurnTargetError, type TurnTargets, UV_INSET_PX, captureBindingEndpoint, computeGridOffsets, createDefaultMatrixDeformer, createDefaultPart, createDefaultWarpDeformer, createGridMesh, createLayerSetMeasurer, denseCoreOf, detectAlphaBbox, foregroundSpan, generateIkiFromLayerSet, headHalfOf, interpolateGridOffsets, isSpeckCore, packAtlas, parseLayerRoles, upsertGridKeyform, uvRectFor, validateDeformerDelete, validateDeformerReparent, validatePartAttach };