@ikijs/editor 0.8.1 → 0.10.0

package/dist/index.d.ts

@@ -656,6 +656,408 @@ interface AlphaBbox {
  */
 declare function detectAlphaBbox(rgba: ArrayLike<number>, width: number, height: number): AlphaBbox | null;
 
+/**
+ * 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;
+}
+
+/**
+ * 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 (see `parseLayerRoles`); becomes the part id. */
+    role: string;
+    fileName: string;
+    canvasW: number;
+    canvasH: number;
+    /** Alpha bounding box in canvas px (y down) — the crop the atlas holds. */
+    bbox: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    };
+    cropW: number;
+    cropH: number;
+    /** Face only: half the opaque span of each crop row, canvas px (0 = none). */
+    rowHalfWidths?: number[];
+    /** 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[];
+}
+/**
+ * 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 {
+    y: number;
+    irisOuter: number;
+    irisInner: number;
+    runOuter: number;
+    /** The run's face-side end; `null` for a fringe spanning the face. */
+    runFace: number | null;
+}
+/**
+ * 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 {
+    eyeShift?: number;
+    farEyeRatio?: number;
+    silhouetteRatio?: number;
+    noseShift?: number;
+    mouthShift?: number;
+    /** The head half-width the shifts are fractions of, canvas px. */
+    headHalfWidth?: number;
+}
+/** A turn target this layer set cannot reach, or turn input that is malformed. */
+declare class TurnTargetError extends Error {
+    constructor(message: string);
+}
+/**
+ * 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">>>;
+/** 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;
+}
+/** 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 {
+    /** 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;
+    /** 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 renders at ±30° (mean of both directions). */
+    achieved: {
+        eyeShift: number;
+        farEyeRatio: number;
+        silhouetteRatio: number;
+    };
+    /** Targets cut down to what this layer set can do. */
+    clamped: (keyof TurnTargets)[];
+    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;
+    };
+}
+
+/**
+ * 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.
+ */
+declare function parseLayerRoles(fileNames: string[]): {
+    role: string;
+    fileName: string;
+}[];
+
+/**
+ * `generateIkiFromLayerSet`: role layers in, a rigged `.iki` out.
+ *
+ * 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?: GenerateOptions): IkiModel;
+
+/**
+ * The alpha rules a layer set is measured by, and the pre-rig measurement of
+ * that set, in one DOM-free copy — the way `detectAlphaBbox` is one.
+ *
+ * Both auto-rig hosts — the editor app (canvas `getImageData`) and
+ * `@ikijs/mcp`'s `auto_rig_from_layers` (a `sharp` raw buffer) — hand
+ * `createLayerSetMeasurer` the RGBA they decoded and rig what it measures, and
+ * `@ikijs/mcp`'s other tools (`measure_turn_reference`, `measure_layers`, the
+ * composer) read the same rules. Two copies would have to be kept identical by
+ * hand, or the head a render measures back, or the nose core the composer
+ * placed, would part from the one the rig was fitted to. Only decoding differs
+ * between the hosts.
+ */
+
+/** Half-height of the row band the head span is taken over, in px. Fixed at
+ *  ±10 rows rather than scaled to the image, and that is the convention: any
+ *  other measurement of head width meant to be compared with the one
+ *  `@ikijs/mcp`'s `measure_turn_reference` takes off a render — one taken off
+ *  layer alpha, a hand script — has to span the same band. Shared by that tool
+ *  and `createLayerSetMeasurer`, so the head it spans off the layers' alpha
+ *  union spans this band too. */
+declare const HEAD_BAND = 10;
+/** Alpha at or above this is opaque. Shared by `@ikijs/mcp`'s
+ *  `measure_turn_reference`, whose "alpha" foreground rule reads an engine
+ *  render's silhouette by it, and by the layer-alpha silhouette
+ *  `createLayerSetMeasurer` measures the head on, which has to follow that
+ *  rule to be comparable with a render. */
+declare const ALPHA_OPAQUE = 128;
+/**
+ * A layer's dense core: the tight box of its pixels at alpha ≥ ALPHA_OPAQUE,
+ * not grown. A soft-alpha part (a nose drawn as a shaded bump) is mostly
+ * feather, and the core is the drawing a viewer reads inside it — `@ikijs/mcp`'s
+ * composer sizes and places the nose by it, and `createLayerSetMeasurer` reads
+ * the same core as the nose's `LayerInput.denseCore`, its turn landmark. It is
+ * not the crop: that stays the alpha ≥ 8 box grown by 1 px (`detectAlphaBbox`).
+ * `null` when no pixel reaches the threshold, a part painted wholly
+ * translucent. A core that is a speck of its part (`isSpeckCore`) is not the
+ * drawing either, and both readers fall back to the whole part, as they do for
+ * `null`.
+ */
+declare function denseCoreOf(rgba: ArrayLike<number>, width: number, height: number): {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+} | null;
+/**
+ * The fraction of its part's width, or of its height, under which a dense core
+ * is a speck (`isSpeckCore`). Measured core/part ratios, width / height: the
+ * hero's composed nose 0.72 / 0.76 (core 39×63 in a 54×83 crop), three
+ * generated shaded-bump noses (the plugin's 0.11 nose prompt) 0.75–0.85 /
+ * 0.79–0.91, `@ikijs/mcp`'s `writeSoftNose` test fixture 0.56 / 0.63 and its
+ * `writeSoftNoseLayers` 0.40 / 0.40, a nostril mark ≤ 0.1. So the line sits at
+ * least 1.6× under every real nose and fixture, and 2.5× over a speck. At the
+ * line, sizing by the core would scale the whole part to 4× its layout width,
+ * the largest blow-up `@ikijs/mcp`'s composer still accepts.
+ */
+declare const SPECK_CORE_FRACTION = 0.25;
+/**
+ * Whether a dense core is a speck of its part: narrower than
+ * SPECK_CORE_FRACTION of the part's width, or shorter than that fraction of
+ * its height (strictly `<`). Either dimension counts, because the core does
+ * more than size a nose: its bottom row is the tip the composer places, and
+ * its top-centre the rig's tilt pivot, so a sliver misplaces the nose as
+ * surely as a speck mis-sizes it. A speck is a lone nostril mark or highlight,
+ * not the drawing, and every reader falls back to the whole part: `@ikijs/mcp`'s
+ * compose sizes and places its trimmed source part whole, and
+ * `createLayerSetMeasurer` hands the rig no core, so the crop stands in.
+ *
+ * The two apply it to different pixels — compose to the source part before
+ * resampling, the rig and `measure_layers` to the composed layer against its
+ * crop — so their verdicts can part, but only for a core within about a
+ * resampled pixel of the line, or one resampling pushes across ALPHA_OPAQUE.
+ * Compose's report carries its source verdict when that was a speck, and
+ * otherwise what the composed layer shows, so it warns of a parting either
+ * way; `measure_layers` reports the layer alone.
+ */
+declare function isSpeckCore(core: {
+    w: number;
+    h: number;
+}, part: {
+    w: number;
+    h: number;
+}): boolean;
+/**
+ * Outermost set pixels of `mask` across the row band `rowLo..rowHi` (clamped
+ * to the image) — the silhouette span at that height. An empty band returns
+ * `left > right`, which every caller has to check for.
+ *
+ * Shared by `@ikijs/mcp`'s `measure_turn_reference`, which spans a render's
+ * head with it, and `createLayerSetMeasurer`, which spans the layers' alpha
+ * union: the two heads are compared, so they have to be spanned the same way.
+ */
+declare function foregroundSpan(mask: Uint8Array, width: number, height: number, rowLo: number, rowHi: number): {
+    left: number;
+    right: number;
+};
+/**
+ * Half of a silhouette span, in px. The span is INCLUSIVE — `left` and `right`
+ * are both foreground columns — so the head is `right - left + 1` px wide.
+ * Shared by `@ikijs/mcp`'s `measure_turn_reference` and
+ * `createLayerSetMeasurer`: the two head half-widths are compared against each
+ * other, so they cannot be halved differently.
+ */
+declare function headHalfOf(span: {
+    left: number;
+    right: number;
+}): number;
+/** One decoded layer, as a host hands it to `LayerSetMeasurer.add`. */
+interface RgbaLayer {
+    /** Canonical role, e.g. "eye_L" — the host has run `parseLayerRoles` on
+     *  the set already. */
+    role: string;
+    /** Original file name: the `LayerInput`'s own, and named in errors. */
+    fileName: string;
+    /** Straight-alpha RGBA, stride 4, `canvas.width × canvas.height` pixels —
+     *  canvas `ImageData.data` or a `sharp` raw buffer alike. */
+    rgba: ArrayLike<number>;
+}
+/**
+ * Measures a layer set one decoded layer at a time, so a host holds one
+ * full-canvas RGBA buffer at once, however many layers the set has. Call
+ * `finish` once, after the last `add`: it hands back its own `layers` array,
+ * which a later `add` would change.
+ */
+interface LayerSetMeasurer {
+    /**
+     * Measure one layer while its `rgba` is in memory, keeping no reference to
+     * it: only the set's opaque union, this layer's per-row opaque extent and,
+     * for `hair_front`, its opaque mask outlive the call, so the host may drop
+     * `rgba` as soon as it returns. Returns the layer's `LayerInput` — its crop
+     * box, the face's `rowHalfWidths`, the nose's `denseCore` unless that is a
+     * speck of its crop (`isSpeckCore`) — or `null` for an empty layer, one with
+     * no pixel at or above `ALPHA_BBOX_THRESHOLD`, which it records nothing for:
+     * the host reports that with its own error. Throws, naming the file, when
+     * `rgba` is not `width × height × 4` long; checking the decoded dimensions
+     * is the host's job.
+     */
+    add(layer: RgbaLayer): LayerInput | null;
+    /** The set's measurement, over every layer `add` recorded. The set must be
+     *  one `parseLayerRoles` accepted; otherwise this may throw, or measure a
+     *  partial set the generator then refuses. */
+    finish(): LayerSetMeasurement;
+}
+interface LayerSetMeasurement {
+    /** Every recorded layer's `LayerInput`, in `add` order. */
+    layers: LayerInput[];
+    /** The head's half-width at the eye row, canvas px: half the opaque
+     *  (alpha ≥ ALPHA_OPAQUE) union's span over ±HEAD_BAND rows about the row
+     *  of the iris centres, or of the eye centres without irises. Absent when
+     *  the union has no span there — a layer set painted translucent below that
+     *  threshold. */
+    headHalfWidth?: number;
+    /** Whether `headHalfWidth` is wider than the face plate, and so applied;
+     *  the face plate stands in for it otherwise, as the generator's own
+     *  fallback. */
+    headHalfWidthApplied: boolean;
+    /**
+     * Ready to go into `generateIkiFromLayerSet`'s options, each key present
+     * only when measured: `turnTargets.headHalfWidth` when it is applied (merge
+     * the caller's own targets under it), `headEdges` — every layer's own
+     * opaque extent in the same eye-row band, per side, in model x — with it,
+     * and `strandEdges` whenever the set has `hair_front`, `iris_L` and `iris_R`
+     * and a side measures one (`IrisStrand`).
+     */
+    turnOptions: {
+        turnTargets?: {
+            headHalfWidth: number;
+        };
+        headEdges?: {
+            left: {
+                role: string;
+                x: number;
+            }[];
+            right: {
+                role: string;
+                x: number;
+            }[];
+        };
+        strandEdges?: {
+            left?: IrisStrand;
+            right?: IrisStrand;
+        };
+    };
+}
+/**
+ * Start measuring a layer set on a `canvas`-sized canvas: the pass a host runs
+ * between decoding its layers and `generateIkiFromLayerSet`. `add` each
+ * decoded layer, then `finish`.
+ *
+ * Throws before allocating anything when `canvas.width` or `canvas.height` is
+ * not a positive safe integer, or `width × height × 4` is not a safe integer.
+ * How large a canvas to accept at all is each host's own limit.
+ */
+declare function createLayerSetMeasurer(canvas: {
+    width: number;
+    height: number;
+}): LayerSetMeasurer;
+
 /**
  * Pure, binding-value logic for computing an endpoint (rest-to-posed delta or
  * ratio) when capturing a transform channel binding. No DOM, no @ikijs/engine —
@@ -842,342 +1244,4 @@ declare function createGridMesh(cols: number, rows: number): IkiMesh;
  */
 declare function createDefaultWarpDeformer(model: IkiModel): IkiWarpDeformer;
 
-/**
- * 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.
- */
-
-/**
- * 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.
- */
-interface LayerInput {
-    /** Canonical role, e.g. "eye_L". */
-    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). */
-    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
-     * (`@ikijs/mcp`'s `measure-turn`), 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 — as the editor's own import leaves 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.
-     */
-    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 — as the
-     * editor's own import leaves 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`.
-     */
-    denseCore?: {
-        x: number;
-        y: number;
-        w: number;
-        h: 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
- * (`@ikijs/mcp` 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.
- */
-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. */
-    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.
- */
-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. */
-    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.
- */
-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.
- */
-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. */
-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. */
-interface TurnSolveReport {
-    /** Cylinder radius the face-warp bake and the parallax unit were built on. */
-    radius: number;
-    /** Rest distance from the face centre the silhouette hold pivots on. */
-    holdBase: number;
-    depths: TurnDepths;
-    /** What the rig actually reaches, in the targets' own units. */
-    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. */
-    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;
-    };
-}
-/**
- * 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`).
- */
-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;
-}
-/**
- * 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.
- *
- * `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.
- */
-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;
-
-export { ALPHA_BBOX_THRESHOLD, 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, type IrisStrand, type LayerInput, 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, detectAlphaBbox, generateIkiFromLayerSet, interpolateGridOffsets, 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 };