@ikijs/editor 0.20.0 → 0.22.0

package/README.md

@@ -40,24 +40,24 @@ leaves the document untouched.
 
 ## API
 
-| Area               | Exports                                                                                                                                                                                                                                                         |
-| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Document           | `EditorDocument`, `EditCommand`                                                                                                                                                                                                                                 |
-| Part edits         | `AddPart`, `DeletePart`, `SetPartColor`, `SetPartWidth`, `SetPartHeight`, `SetPartOrder`, `SetPartTransform`, `SetPartBindings`, `SetPartMesh`, `SetPartDeformer`                                                                                               |
-| Deformer edits     | `AddDeformer`, `DeleteDeformer`, `SetDeformerParent`, `SetDeformerTransform`, `SetDeformerBindings`, `SetDeformerPivot` (+ `X`/`Y`), `CaptureGridKeyform`                                                                                                       |
-| Physics edits      | `AddPhysicsRig`, `SetPhysicsRig`, `DeletePhysicsRig`                                                                                                                                                                                                            |
-| Referential guards | `validateDeformerReparent`, `validateDeformerDelete`, `validatePartAttach`                                                                                                                                                                                      |
-| Atlas              | `packAtlas`, `uvRectFor`, `ATLAS_PADDING`, `UV_INSET_PX`                                                                                                                                                                                                        |
-| 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`, `partIdsOfRole`, `createLayerSetMeasurer`, `armGeometry`, `ArmGeometry`, `forearmPoseGeometry`, `ForearmPoseGeometry`, `TurnTargets`, `DEFAULT_TURN_TARGETS`, `TurnSolveReport`, `RigStyle`, `LayerGeometryError` |
-| Bindings           | `captureBindingEndpoint`                                                                                                                                                                                                                                        |
+| Area               | Exports                                                                                                                                                                                                                                                                                                                                                                          |
+| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Document           | `EditorDocument`, `EditCommand`                                                                                                                                                                                                                                                                                                                                                  |
+| Part edits         | `AddPart`, `DeletePart`, `SetPartColor`, `SetPartWidth`, `SetPartHeight`, `SetPartOrder`, `SetPartTransform`, `SetPartBindings`, `SetPartMesh`, `SetPartDeformer`                                                                                                                                                                                                                |
+| Deformer edits     | `AddDeformer`, `DeleteDeformer`, `SetDeformerParent`, `SetDeformerTransform`, `SetDeformerBindings`, `SetDeformerPivot` (+ `X`/`Y`), `CaptureGridKeyform`                                                                                                                                                                                                                        |
+| Physics edits      | `AddPhysicsRig`, `SetPhysicsRig`, `DeletePhysicsRig`                                                                                                                                                                                                                                                                                                                             |
+| Referential guards | `validateDeformerReparent`, `validateDeformerDelete`, `validatePartAttach`                                                                                                                                                                                                                                                                                                       |
+| Atlas              | `packAtlas`, `uvRectFor`, `ATLAS_PADDING`, `UV_INSET_PX`                                                                                                                                                                                                                                                                                                                         |
+| 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`, `partIdsOfRole`, `createLayerSetMeasurer`, `armGeometry`, `ArmGeometry`, `forearmPoseGeometry`, `ForearmPoseGeometry`, `mouthOpening`, `mouthFold`, `mouthRestShift`, `columnRuns`, `LIP_ROLES`, `LipRole`, `Opening`, `OpeningColumn`, `TurnTargets`, `DEFAULT_TURN_TARGETS`, `TurnSolveReport`, `RigStyle`, `LayerGeometryError` |
+| Bindings           | `captureBindingEndpoint`                                                                                                                                                                                                                                                                                                                                                         |
 
 ## Auto-rig
 
 `generateIkiFromLayerSet` turns role-named layers (`face`, `eye_L`, `eye_R`,
-`mouth`, plus optional `iris_*`, `brow_*`, `lash_*`, `lash_lower_*`, `hair_front`, `hair_back`,
+and `mouth` — or the lip set `mouth_inner`, `lip_lower`, `lip_upper`, which folds open instead of crossfading — plus optional `iris_*`, `brow_*`, `lash_*`, `lash_lower_*`, `hair_front`, `hair_back`,
 `body`, `arm_*`, …) into a rigged model that blinks, gazes, opens its mouth, turns its head over
 a body warp that breathes, follows the head a little and turns on
 `ParamBodyAngleX/Y/Z`, and emotes with its brows — including a

package/dist/index.d.mts

@@ -714,14 +714,17 @@ interface LayerInput {
     /** Face only: half the opaque span of each crop row, canvas px (0 = none). */
     rowHalfWidths?: number[];
     /** `face` / `hair_front` / `hair_back` / `body` / `arm_L` / `arm_R` /
-     *  `forearm_pose_L` / `forearm_pose_R` only:
+     *  `forearm_pose_L` / `forearm_pose_R` /
+     *  `mouth_inner` / `lip_lower` / `lip_upper` only:
      *  per crop row, its opaque (alpha ≥ 128) runs as a flat list of canvas
      *  columns `[start0, end0, start1, end1, …]`, each end exclusive (`[]` for a
      *  row with none). The actual pixels, so a gap in the hair is a gap here:
      *  the turn and the nod read off it where back hair is painted behind the
      *  front hair, and the crown's turn reads the face's so it never bares skin.
      *  The body's place the hips (where it splits into legs), and an arm's place
-     *  its shoulder and elbow pivots, a pose forearm's its elbow-end pivot. */
+     *  its shoulder and elbow pivots, a pose forearm's its elbow-end pivot, and
+     *  a lip set's place the mouth's opening: the upper line's bottom, the
+     *  interior's span, the skin's top. */
     rowRuns?: number[][];
     /** Nose only: the tight box of its alpha ≥ 128 pixels, canvas px. */
     denseCore?: {
@@ -768,9 +771,11 @@ declare class TurnTargetError extends Error {
     constructor(message: string);
 }
 /**
- * Art geometry the rig cannot build on — today a body whose hips leave no row
- * line under its pivots, or too little room for its motion (`body.ts`). A fact about the layers, not a bug, so a
- * host reports it as an input error.
+ * Art geometry the rig cannot build on — a body whose hips leave no row line
+ * under its pivots, or too little room for its motion (`body.ts`), an arm
+ * without room for its pivots, a lip set whose interior has no opaque pixel
+ * (`mouth.ts`). A fact about the layers, not a bug, so a host reports it as an
+ * input error.
  */
 declare class LayerGeometryError extends Error {
     constructor(message: string);
@@ -988,19 +993,141 @@ interface ForearmPoseGeometry {
  */
 declare function forearmPoseGeometry(layer: LayerInput): ForearmPoseGeometry;
 
+/** The lip set's roles, back to front (`mouth.ts`). */
+declare const LIP_ROLES: readonly ["mouth_inner", "lip_lower", "lip_upper"];
+type LipRole = (typeof LIP_ROLES)[number];
 /** The part ids a `role`'s layer becomes, back to front: every one of them
  *  takes its texture from the layer's crop. Throws on an unknown role. */
 declare function partIdsOfRole(role: string): readonly string[];
 /**
  * Map file names to roles. Throws on an unknown role, a role named twice, a
- * required role (`face`, `eye_L`, `eye_R`, `mouth`) missing, an arm without a
- * body, or a pose forearm without its arm.
+ * required role (`face`, `eye_L`, `eye_R`) missing, no mouth (`mouth`, or the
+ * lip set) or a partial or mixed one, an arm without a body, or a pose forearm
+ * without its arm.
  */
 declare function parseLayerRoles(fileNames: string[]): {
     role: string;
     fileName: string;
 }[];
 
+/**
+ * The lip set: a mouth that folds open the way the eyelid folds shut. Three
+ * parts, back to front: `mouth_inner` (the interior and the opening's lower
+ * outline band), `lip_lower` (the lower lip's skin) and `lip_upper` (the upper
+ * lip line and the corner hooks).
+ *
+ * What the rig reads is the layers' own alpha edges, as exclusive run
+ * boundaries in model y (+y up; a run of crop rows `[a, b)` is the span
+ * `[rowTop(b), rowTop(a)]`). Per canvas column inside the opening (where
+ * `mouth_inner` has a run): the interior's top `T` and bottom `Bb`, the line
+ * of `lip_upper` at the interior's top (`Tu` its bottom edge, `lineTop` its
+ * top) and the skin's top `Bl`. Each part has one affine warp per column that
+ * lands its OWN boundary on its target, so no relation between two parts'
+ * boundaries enters the closure; there is no colour read. The art's contract:
+ * the interior reaches the line (`T >= Tu`; lower would show the face between
+ * them at rest) and the skin reaches the interior (`Bl >= Bb`; an overlap is
+ * fine, a gap is not).
+ *
+ * MouthOpen 0 folds shut onto a seam, 1 is the art as drawn (the widening of
+ * `mouthWiden` apart). The line comes down until its bottom edge is on the
+ * seam, the skin until its top is one overlap `w'` up under the line (`w'` is
+ * the stroke `w`, the line's height at the opening's centre, capped by the
+ * line's own ink at that column so tucked skin never shows above it), and the
+ * interior's bottom rides the skin's top, so the band is never covered. The
+ * interior's top closes onto the same edge, `S + w'`: the whole column scales
+ * by `v` about it, so shut its height is zero (a degenerate triangle draws
+ * nothing, at every column and between knots; an inverted sliver would leak
+ * through texture filtering where the line is thin), and its top sits
+ * `w'(1 - v)` above the line's bottom edge, under the line's ink, so the slit
+ * between the line and the skin is always backed. The slit opens once
+ * `v * H > w'(1 - v)`; that dead zone is accepted: lip-sync noise near 0 does
+ * not flicker through it.
+ *
+ * The seam is the line's drawn bottom edge `Tu` plus one smooth closing
+ * travel `D`, a cubic in the column index pinned to zero at the opening's two
+ * end columns, so the closed line's ends are the drawn line's own ends. It is
+ * fitted by least squares to the raw per-column travel `(T - UPPER_SHARE * H)
+ * - Tu`, how far the line's bottom is from the share's point in the
+ * interior's span. The travel is fitted, not the seam, because `Tu` is an
+ * integer-row read: a smooth seam minus that staircase is a sawtooth the mesh
+ * would carry into the rendered line, while a smooth travel carries the
+ * drawn stroke (whose antialiased edge is smooth) as one piece. The share sets
+ * the travel's depth (the sag), the art's two arcs its shape; the cubic keeps
+ * an asymmetric mouth's tilt and cannot wobble.
+ *
+ * A lip's columns outside the opening (the corner hooks) do not fold; only
+ * the interior's edge columns read the nearest opening column.
+ *
+ * Knots: the three parts share column knots every `MOUTH_KNOT_PX` plus the
+ * opening's boundaries `x0`, `x1` and `x1 + 1`, each an integer canvas
+ * boundary. The fit's x is the column index, which is the mesh's boundary
+ * position: a knot at boundary `b` samples column `b`, so the mesh renders the
+ * fit exactly at its knots and the pinned ends render as pinned (`x1` and
+ * `x1 + 1` both sample the last column; the second sits at its right edge).
+ * The preview shifts each column by the field at the column's centre
+ * (`mouthRestShift`). A part's mesh rounds its local x, so one knot
+ * reconstructs to slightly different model x per part; the fold therefore
+ * reads the knot itself, by vertex index, and maps every knot through one rule
+ * (`columnOfKnot`).
+ *
+ * The anchor (`mouthAnchor`) is where the head's frame and the turn read the
+ * mouth's resting place (the chin lead, the chin estimate, the solve). A
+ * single closed mouth is its box centre (its box the union with `mouth_open`);
+ * for a lip set it is the seam at the opening's centre column, where the lips
+ * meet, with the interior's centre across and the union of the three as box.
+ */
+
+/** Per canvas column, its opaque runs as `[top, bottom)` crop rows, top
+ *  first: the transpose of `rowRuns`. */
+declare function columnRuns(layer: LayerInput): Map<number, number[][]>;
+/** What the fold reads off one canvas column, all model y. */
+interface OpeningColumn {
+    /** The interior's top and bottom edges. */
+    T: number;
+    Bb: number;
+    /** The upper line's bottom and top edges, and its height. */
+    Tu: number;
+    lineTop: number;
+    lineH: number;
+    /** The skin's top edge. */
+    Bl: number;
+    /** The interior's span. */
+    H: number;
+    /** How far the skin tucks up under the line. */
+    overlap: number;
+    /** Where the lips meet when shut: the line's bottom edge after its smooth
+     *  closing travel. */
+    seam: number;
+}
+interface Opening {
+    /** The first and last canvas columns where `mouth_inner` has a run. */
+    x0: number;
+    x1: number;
+    /** The opening's centre column: where the stroke and the anchor are read. */
+    centre: number;
+    canvasW: number;
+    /** The stroke: the line's height at the opening's centre column. */
+    w: number;
+    /** A column's values; outside `x0..x1`, or in a gap, the nearest one's. */
+    at(col: number): OpeningColumn;
+}
+declare function mouthOpening(byRole: Map<string, LayerInput>): Opening;
+/**
+ * dy of a model-y rest position at pixel column `col` for MouthOpen `v`
+ * (0 shut, 1 as drawn). A lip outside the opening moves 0; `mouth_inner`
+ * scales its column by `v` about `S + w'`, which carries its top and bottom
+ * edges along the line and the skin and needs no read of its own height.
+ */
+declare function mouthFold(role: LipRole, opening: Opening): (col: number, y: number, v: number) => number;
+/** A lip's translate at MouthOpen 0 per canvas column as the mesh renders it,
+ *  for the composer's closed preview: the linear interpolation at the column's
+ *  centre between the STORED offsets of the part's two bracketing knots (the
+ *  numbers the `.iki` carries, rounded as `localWarp` rounds them), 0 outside
+ *  the part's box. `byRole` must be the layers as the rig measures them (the
+ *  canvas-sized ones): a box measured on a smaller frame clamps differently,
+ *  and the knot grid starts at the union's edge. */
+declare function mouthRestShift(byRole: Map<string, LayerInput>): (role: "lip_upper" | "lip_lower", col: number) => number;
+
 /**
  * `generateIkiFromLayerSet`: role layers in, a rigged `.iki` out.
  *
@@ -1018,7 +1145,9 @@ declare function parseLayerRoles(fileNames: string[]): {
  * and two ears that lag. Blink, gaze, brows, mouth, breath and
  * hair sway are part warps and bindings under those. The model also declares
  * the default expressions and the Nod, Shake and Tilt motions, and
- * with a pose forearm the Wave (`animations.ts`).
+ * with a pose forearm the Wave (`animations.ts`). The mouth has two paths,
+ * chosen by the layers: `mouth` alone stretches, with `mouth_open` it
+ * crossfades; the lip set folds open like the eyelid (`mouth.ts`).
  */
 
 declare function generateIkiFromLayerSet(layers: LayerInput[], canvas: {
@@ -1158,8 +1287,8 @@ interface LayerSetMeasurer {
      * of it and of the per-role edges), this layer's per-row opaque extent and
      * the `LayerInput` it returns 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 face's, hair layers', body's, arms'
-     * and pose forearms' `rowRuns`, the nose's
+     * box, the face's `rowHalfWidths`, the face's, hair layers', body's, arms',
+     * pose forearms' and lip set's `rowRuns`, 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
@@ -1416,4 +1545,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 ArmGeometry, type AtlasAssignment, type AtlasLayout, type AtlasPlacement, type AtlasSource, CaptureGridKeyform, DEFAULT_TURN_TARGETS, type DeformerTransformChannel, DeleteDeformer, DeletePart, DeletePhysicsRig, type EditCommand, type EditTransformChannel, EditorDocument, type ForearmPoseGeometry, HEAD_BAND, type IrisStrand, LayerGeometryError, 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, armGeometry, captureBindingEndpoint, computeGridOffsets, createDefaultMatrixDeformer, createDefaultPart, createDefaultWarpDeformer, createGridMesh, createLayerSetMeasurer, denseCoreOf, detectAlphaBbox, forearmPoseGeometry, foregroundSpan, generateIkiFromLayerSet, headHalfOf, interpolateGridOffsets, isSpeckCore, packAtlas, parseLayerRoles, partIdsOfRole, upsertGridKeyform, uvRectFor, validateDeformerDelete, validateDeformerReparent, validatePartAttach };
+export { ALPHA_BBOX_THRESHOLD, ALPHA_OPAQUE, ATLAS_PADDING, AddDeformer, AddPart, AddPhysicsRig, type AlphaBbox, type ApplyAtlasInput, type ArmGeometry, type AtlasAssignment, type AtlasLayout, type AtlasPlacement, type AtlasSource, CaptureGridKeyform, DEFAULT_TURN_TARGETS, type DeformerTransformChannel, DeleteDeformer, DeletePart, DeletePhysicsRig, type EditCommand, type EditTransformChannel, EditorDocument, type ForearmPoseGeometry, HEAD_BAND, type IrisStrand, LIP_ROLES, LayerGeometryError, type LayerInput, type LayerSetMeasurement, type LayerSetMeasurer, type LipRole, type Opening, type OpeningColumn, 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, armGeometry, captureBindingEndpoint, columnRuns, computeGridOffsets, createDefaultMatrixDeformer, createDefaultPart, createDefaultWarpDeformer, createGridMesh, createLayerSetMeasurer, denseCoreOf, detectAlphaBbox, forearmPoseGeometry, foregroundSpan, generateIkiFromLayerSet, headHalfOf, interpolateGridOffsets, isSpeckCore, mouthFold, mouthOpening, mouthRestShift, packAtlas, parseLayerRoles, partIdsOfRole, upsertGridKeyform, uvRectFor, validateDeformerDelete, validateDeformerReparent, validatePartAttach };

package/dist/index.d.ts

@@ -714,14 +714,17 @@ interface LayerInput {
     /** Face only: half the opaque span of each crop row, canvas px (0 = none). */
     rowHalfWidths?: number[];
     /** `face` / `hair_front` / `hair_back` / `body` / `arm_L` / `arm_R` /
-     *  `forearm_pose_L` / `forearm_pose_R` only:
+     *  `forearm_pose_L` / `forearm_pose_R` /
+     *  `mouth_inner` / `lip_lower` / `lip_upper` only:
      *  per crop row, its opaque (alpha ≥ 128) runs as a flat list of canvas
      *  columns `[start0, end0, start1, end1, …]`, each end exclusive (`[]` for a
      *  row with none). The actual pixels, so a gap in the hair is a gap here:
      *  the turn and the nod read off it where back hair is painted behind the
      *  front hair, and the crown's turn reads the face's so it never bares skin.
      *  The body's place the hips (where it splits into legs), and an arm's place
-     *  its shoulder and elbow pivots, a pose forearm's its elbow-end pivot. */
+     *  its shoulder and elbow pivots, a pose forearm's its elbow-end pivot, and
+     *  a lip set's place the mouth's opening: the upper line's bottom, the
+     *  interior's span, the skin's top. */
     rowRuns?: number[][];
     /** Nose only: the tight box of its alpha ≥ 128 pixels, canvas px. */
     denseCore?: {
@@ -768,9 +771,11 @@ declare class TurnTargetError extends Error {
     constructor(message: string);
 }
 /**
- * Art geometry the rig cannot build on — today a body whose hips leave no row
- * line under its pivots, or too little room for its motion (`body.ts`). A fact about the layers, not a bug, so a
- * host reports it as an input error.
+ * Art geometry the rig cannot build on — a body whose hips leave no row line
+ * under its pivots, or too little room for its motion (`body.ts`), an arm
+ * without room for its pivots, a lip set whose interior has no opaque pixel
+ * (`mouth.ts`). A fact about the layers, not a bug, so a host reports it as an
+ * input error.
  */
 declare class LayerGeometryError extends Error {
     constructor(message: string);
@@ -988,19 +993,141 @@ interface ForearmPoseGeometry {
  */
 declare function forearmPoseGeometry(layer: LayerInput): ForearmPoseGeometry;
 
+/** The lip set's roles, back to front (`mouth.ts`). */
+declare const LIP_ROLES: readonly ["mouth_inner", "lip_lower", "lip_upper"];
+type LipRole = (typeof LIP_ROLES)[number];
 /** The part ids a `role`'s layer becomes, back to front: every one of them
  *  takes its texture from the layer's crop. Throws on an unknown role. */
 declare function partIdsOfRole(role: string): readonly string[];
 /**
  * Map file names to roles. Throws on an unknown role, a role named twice, a
- * required role (`face`, `eye_L`, `eye_R`, `mouth`) missing, an arm without a
- * body, or a pose forearm without its arm.
+ * required role (`face`, `eye_L`, `eye_R`) missing, no mouth (`mouth`, or the
+ * lip set) or a partial or mixed one, an arm without a body, or a pose forearm
+ * without its arm.
  */
 declare function parseLayerRoles(fileNames: string[]): {
     role: string;
     fileName: string;
 }[];
 
+/**
+ * The lip set: a mouth that folds open the way the eyelid folds shut. Three
+ * parts, back to front: `mouth_inner` (the interior and the opening's lower
+ * outline band), `lip_lower` (the lower lip's skin) and `lip_upper` (the upper
+ * lip line and the corner hooks).
+ *
+ * What the rig reads is the layers' own alpha edges, as exclusive run
+ * boundaries in model y (+y up; a run of crop rows `[a, b)` is the span
+ * `[rowTop(b), rowTop(a)]`). Per canvas column inside the opening (where
+ * `mouth_inner` has a run): the interior's top `T` and bottom `Bb`, the line
+ * of `lip_upper` at the interior's top (`Tu` its bottom edge, `lineTop` its
+ * top) and the skin's top `Bl`. Each part has one affine warp per column that
+ * lands its OWN boundary on its target, so no relation between two parts'
+ * boundaries enters the closure; there is no colour read. The art's contract:
+ * the interior reaches the line (`T >= Tu`; lower would show the face between
+ * them at rest) and the skin reaches the interior (`Bl >= Bb`; an overlap is
+ * fine, a gap is not).
+ *
+ * MouthOpen 0 folds shut onto a seam, 1 is the art as drawn (the widening of
+ * `mouthWiden` apart). The line comes down until its bottom edge is on the
+ * seam, the skin until its top is one overlap `w'` up under the line (`w'` is
+ * the stroke `w`, the line's height at the opening's centre, capped by the
+ * line's own ink at that column so tucked skin never shows above it), and the
+ * interior's bottom rides the skin's top, so the band is never covered. The
+ * interior's top closes onto the same edge, `S + w'`: the whole column scales
+ * by `v` about it, so shut its height is zero (a degenerate triangle draws
+ * nothing, at every column and between knots; an inverted sliver would leak
+ * through texture filtering where the line is thin), and its top sits
+ * `w'(1 - v)` above the line's bottom edge, under the line's ink, so the slit
+ * between the line and the skin is always backed. The slit opens once
+ * `v * H > w'(1 - v)`; that dead zone is accepted: lip-sync noise near 0 does
+ * not flicker through it.
+ *
+ * The seam is the line's drawn bottom edge `Tu` plus one smooth closing
+ * travel `D`, a cubic in the column index pinned to zero at the opening's two
+ * end columns, so the closed line's ends are the drawn line's own ends. It is
+ * fitted by least squares to the raw per-column travel `(T - UPPER_SHARE * H)
+ * - Tu`, how far the line's bottom is from the share's point in the
+ * interior's span. The travel is fitted, not the seam, because `Tu` is an
+ * integer-row read: a smooth seam minus that staircase is a sawtooth the mesh
+ * would carry into the rendered line, while a smooth travel carries the
+ * drawn stroke (whose antialiased edge is smooth) as one piece. The share sets
+ * the travel's depth (the sag), the art's two arcs its shape; the cubic keeps
+ * an asymmetric mouth's tilt and cannot wobble.
+ *
+ * A lip's columns outside the opening (the corner hooks) do not fold; only
+ * the interior's edge columns read the nearest opening column.
+ *
+ * Knots: the three parts share column knots every `MOUTH_KNOT_PX` plus the
+ * opening's boundaries `x0`, `x1` and `x1 + 1`, each an integer canvas
+ * boundary. The fit's x is the column index, which is the mesh's boundary
+ * position: a knot at boundary `b` samples column `b`, so the mesh renders the
+ * fit exactly at its knots and the pinned ends render as pinned (`x1` and
+ * `x1 + 1` both sample the last column; the second sits at its right edge).
+ * The preview shifts each column by the field at the column's centre
+ * (`mouthRestShift`). A part's mesh rounds its local x, so one knot
+ * reconstructs to slightly different model x per part; the fold therefore
+ * reads the knot itself, by vertex index, and maps every knot through one rule
+ * (`columnOfKnot`).
+ *
+ * The anchor (`mouthAnchor`) is where the head's frame and the turn read the
+ * mouth's resting place (the chin lead, the chin estimate, the solve). A
+ * single closed mouth is its box centre (its box the union with `mouth_open`);
+ * for a lip set it is the seam at the opening's centre column, where the lips
+ * meet, with the interior's centre across and the union of the three as box.
+ */
+
+/** Per canvas column, its opaque runs as `[top, bottom)` crop rows, top
+ *  first: the transpose of `rowRuns`. */
+declare function columnRuns(layer: LayerInput): Map<number, number[][]>;
+/** What the fold reads off one canvas column, all model y. */
+interface OpeningColumn {
+    /** The interior's top and bottom edges. */
+    T: number;
+    Bb: number;
+    /** The upper line's bottom and top edges, and its height. */
+    Tu: number;
+    lineTop: number;
+    lineH: number;
+    /** The skin's top edge. */
+    Bl: number;
+    /** The interior's span. */
+    H: number;
+    /** How far the skin tucks up under the line. */
+    overlap: number;
+    /** Where the lips meet when shut: the line's bottom edge after its smooth
+     *  closing travel. */
+    seam: number;
+}
+interface Opening {
+    /** The first and last canvas columns where `mouth_inner` has a run. */
+    x0: number;
+    x1: number;
+    /** The opening's centre column: where the stroke and the anchor are read. */
+    centre: number;
+    canvasW: number;
+    /** The stroke: the line's height at the opening's centre column. */
+    w: number;
+    /** A column's values; outside `x0..x1`, or in a gap, the nearest one's. */
+    at(col: number): OpeningColumn;
+}
+declare function mouthOpening(byRole: Map<string, LayerInput>): Opening;
+/**
+ * dy of a model-y rest position at pixel column `col` for MouthOpen `v`
+ * (0 shut, 1 as drawn). A lip outside the opening moves 0; `mouth_inner`
+ * scales its column by `v` about `S + w'`, which carries its top and bottom
+ * edges along the line and the skin and needs no read of its own height.
+ */
+declare function mouthFold(role: LipRole, opening: Opening): (col: number, y: number, v: number) => number;
+/** A lip's translate at MouthOpen 0 per canvas column as the mesh renders it,
+ *  for the composer's closed preview: the linear interpolation at the column's
+ *  centre between the STORED offsets of the part's two bracketing knots (the
+ *  numbers the `.iki` carries, rounded as `localWarp` rounds them), 0 outside
+ *  the part's box. `byRole` must be the layers as the rig measures them (the
+ *  canvas-sized ones): a box measured on a smaller frame clamps differently,
+ *  and the knot grid starts at the union's edge. */
+declare function mouthRestShift(byRole: Map<string, LayerInput>): (role: "lip_upper" | "lip_lower", col: number) => number;
+
 /**
  * `generateIkiFromLayerSet`: role layers in, a rigged `.iki` out.
  *
@@ -1018,7 +1145,9 @@ declare function parseLayerRoles(fileNames: string[]): {
  * and two ears that lag. Blink, gaze, brows, mouth, breath and
  * hair sway are part warps and bindings under those. The model also declares
  * the default expressions and the Nod, Shake and Tilt motions, and
- * with a pose forearm the Wave (`animations.ts`).
+ * with a pose forearm the Wave (`animations.ts`). The mouth has two paths,
+ * chosen by the layers: `mouth` alone stretches, with `mouth_open` it
+ * crossfades; the lip set folds open like the eyelid (`mouth.ts`).
  */
 
 declare function generateIkiFromLayerSet(layers: LayerInput[], canvas: {
@@ -1158,8 +1287,8 @@ interface LayerSetMeasurer {
      * of it and of the per-role edges), this layer's per-row opaque extent and
      * the `LayerInput` it returns 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 face's, hair layers', body's, arms'
-     * and pose forearms' `rowRuns`, the nose's
+     * box, the face's `rowHalfWidths`, the face's, hair layers', body's, arms',
+     * pose forearms' and lip set's `rowRuns`, 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
@@ -1416,4 +1545,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 ArmGeometry, type AtlasAssignment, type AtlasLayout, type AtlasPlacement, type AtlasSource, CaptureGridKeyform, DEFAULT_TURN_TARGETS, type DeformerTransformChannel, DeleteDeformer, DeletePart, DeletePhysicsRig, type EditCommand, type EditTransformChannel, EditorDocument, type ForearmPoseGeometry, HEAD_BAND, type IrisStrand, LayerGeometryError, 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, armGeometry, captureBindingEndpoint, computeGridOffsets, createDefaultMatrixDeformer, createDefaultPart, createDefaultWarpDeformer, createGridMesh, createLayerSetMeasurer, denseCoreOf, detectAlphaBbox, forearmPoseGeometry, foregroundSpan, generateIkiFromLayerSet, headHalfOf, interpolateGridOffsets, isSpeckCore, packAtlas, parseLayerRoles, partIdsOfRole, upsertGridKeyform, uvRectFor, validateDeformerDelete, validateDeformerReparent, validatePartAttach };
+export { ALPHA_BBOX_THRESHOLD, ALPHA_OPAQUE, ATLAS_PADDING, AddDeformer, AddPart, AddPhysicsRig, type AlphaBbox, type ApplyAtlasInput, type ArmGeometry, type AtlasAssignment, type AtlasLayout, type AtlasPlacement, type AtlasSource, CaptureGridKeyform, DEFAULT_TURN_TARGETS, type DeformerTransformChannel, DeleteDeformer, DeletePart, DeletePhysicsRig, type EditCommand, type EditTransformChannel, EditorDocument, type ForearmPoseGeometry, HEAD_BAND, type IrisStrand, LIP_ROLES, LayerGeometryError, type LayerInput, type LayerSetMeasurement, type LayerSetMeasurer, type LipRole, type Opening, type OpeningColumn, 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, armGeometry, captureBindingEndpoint, columnRuns, computeGridOffsets, createDefaultMatrixDeformer, createDefaultPart, createDefaultWarpDeformer, createGridMesh, createLayerSetMeasurer, denseCoreOf, detectAlphaBbox, forearmPoseGeometry, foregroundSpan, generateIkiFromLayerSet, headHalfOf, interpolateGridOffsets, isSpeckCore, mouthFold, mouthOpening, mouthRestShift, packAtlas, parseLayerRoles, partIdsOfRole, upsertGridKeyform, uvRectFor, validateDeformerDelete, validateDeformerReparent, validatePartAttach };