@ikijs/editor 0.5.0 → 0.7.0

package/README.md

@@ -72,12 +72,29 @@ 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. A target you passed that this layer set cannot
-reach **throws**, naming the field and the range it could have had; 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. Pass `options.onTurnSolved` to see what the turn settled on and which
-targets were clamped.
+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.
 
 `turnTargets.headHalfWidth` is what the shift targets are fractions of, when a
 caller has measured the actual head (the face plate stands in otherwise).
@@ -89,10 +106,24 @@ hair holds still, a face-plate or body edge slide) 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.
 
+`options.strandEdges` gives, per side, that side's iris and the `hair_front`
+run it would slide under on the turn, as real pixel edges on the row holding
+the iris's centre (`IrisStrand`: the iris's opaque span, and the run's outer
+and face-side ends). One shape covers a strand outward of a clear iris, a run
+over the iris centre that clears on the face side, and a fringe spanning the
+face, whose `runFace` is `null` because it has no face-side end on that side.
+`@ikijs/mcp` measures it off the pixels it decodes. It is always validated
+against the layers, but like `headEdges` it is only read by the turn solve, so
+it has no effect on the rig without a `nose`; absent or `{}`, the rig is exactly
+the one built without it.
+
 It takes **already-decoded** layer geometry (`LayerInput`), never pixels, which
 is what keeps this package free of any image dependency: the editor app
 decodes with canvas, `@ikijs/mcp` decodes with `sharp`, and both feed the same
-pure function.
+pure function — including the optional `rowHalfWidths` (one entry per crop row,
+half that row's opaque span in canvas px), which `@ikijs/mcp` measures for the
+face so the plate turns on a radius that varies by row; absent, it turns on one
+constant radius.
 
 `*_L` / `*_R` are the **character's** sides — `eye_L` is the character's left
 eye, which appears on the viewer's right.

package/dist/index.d.mts

@@ -875,6 +875,19 @@ interface LayerInput {
     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[];
 }
 /**
  * Map an array of raw filenames to canonical `{ role, fileName }` pairs.
@@ -891,6 +904,40 @@ 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
@@ -908,6 +955,14 @@ declare function parseLayerRoles(fileNames: string[]): {
  * 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
@@ -973,9 +1028,43 @@ interface TurnSolveReport {
         farEyeRatio: number;
         silhouetteRatio: number;
     };
-    /** Defaulted fields the layer set could not reach, cut down to what it can.
-     *  Empty when every target was met. */
+    /** 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
@@ -983,16 +1072,23 @@ interface TurnSolveReport {
  *
  *   - Validate all inputs before deriving anything.
  *   - Place parts at source-derived positions (bboxToTransform, unshifted).
- *   - Emit the standard parameters (same ids/ranges as sample-model.ts), plus a
- *     conditional HairSwayX descriptor + hair-sway physics rig when a hair_front
- *     layer is present.
+ *   - 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 face warp),
+ *     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), and faceWarp (warp, FACE_GRID_CELLS²,
- *     baked cylinder warp center-relative on faceCenterX).
+ *     AngleX follow + Breath follow).
  *   - Mesh parts (spec.mesh===true) → width:1, height:1, pixel grid mesh sized by
- *     meshCellsFor + role bindings.
+ *     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
@@ -1001,9 +1097,17 @@ interface TurnSolveReport {
  * `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 — see TurnTargets for why the two
- * differ, and pass `options.onTurnSolved` to see which ones were clamped and
- * what the turn ended up reaching.
+ * 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;
@@ -1027,6 +1131,29 @@ declare function generateIkiFromLayerSet(layers: LayerInput[], canvas: {
             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 LayerInput, SetDeformerBindings, SetDeformerParent, SetDeformerPivot, SetDeformerPivotX, SetDeformerPivotY, SetDeformerTransform, SetPartBindings, SetPartColor, SetPartDeformer, SetPartHeight, SetPartMesh, SetPartOrder, SetPartTransform, SetPartWidth, SetPhysicsRig, 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, 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 };

package/dist/index.d.ts

@@ -875,6 +875,19 @@ interface LayerInput {
     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[];
 }
 /**
  * Map an array of raw filenames to canonical `{ role, fileName }` pairs.
@@ -891,6 +904,40 @@ 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
@@ -908,6 +955,14 @@ declare function parseLayerRoles(fileNames: string[]): {
  * 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
@@ -973,9 +1028,43 @@ interface TurnSolveReport {
         farEyeRatio: number;
         silhouetteRatio: number;
     };
-    /** Defaulted fields the layer set could not reach, cut down to what it can.
-     *  Empty when every target was met. */
+    /** 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
@@ -983,16 +1072,23 @@ interface TurnSolveReport {
  *
  *   - Validate all inputs before deriving anything.
  *   - Place parts at source-derived positions (bboxToTransform, unshifted).
- *   - Emit the standard parameters (same ids/ranges as sample-model.ts), plus a
- *     conditional HairSwayX descriptor + hair-sway physics rig when a hair_front
- *     layer is present.
+ *   - 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 face warp),
+ *     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), and faceWarp (warp, FACE_GRID_CELLS²,
- *     baked cylinder warp center-relative on faceCenterX).
+ *     AngleX follow + Breath follow).
  *   - Mesh parts (spec.mesh===true) → width:1, height:1, pixel grid mesh sized by
- *     meshCellsFor + role bindings.
+ *     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
@@ -1001,9 +1097,17 @@ interface TurnSolveReport {
  * `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 — see TurnTargets for why the two
- * differ, and pass `options.onTurnSolved` to see which ones were clamped and
- * what the turn ended up reaching.
+ * 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;
@@ -1027,6 +1131,29 @@ declare function generateIkiFromLayerSet(layers: LayerInput[], canvas: {
             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 LayerInput, SetDeformerBindings, SetDeformerParent, SetDeformerPivot, SetDeformerPivotX, SetDeformerPivotY, SetDeformerTransform, SetPartBindings, SetPartColor, SetPartDeformer, SetPartHeight, SetPartMesh, SetPartOrder, SetPartTransform, SetPartWidth, SetPhysicsRig, 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, 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 };