@ikijs/editor 0.21.0 → 0.23.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`,
-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`,
+and `mouth` — or the lip set `mouth_inner`, `lip_lower`, `lip_upper`, which folds open instead of crossfading, with optional `mouth_tongue` / `mouth_teeth` clipped to `mouth_inner` (only with the lip set) — 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

@@ -993,20 +993,196 @@ 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 lip set's optional inside parts, back to front: cut from the interior
+ *  and clipped to `mouth_inner` (`mouth.ts`). */
+declare const LIP_INSIDE_ROLES: readonly ["mouth_tongue", "mouth_teeth"];
+type LipInsideRole = (typeof LIP_INSIDE_ROLES)[number];
+declare const isLipInsideRole: (role: string) => role is LipInsideRole;
 /** 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`) 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.
+ * lip set) or a partial or mixed one, a lip set's inside part without the set,
+ * 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). Between the interior and the skin it may
+ * carry two inside parts, `mouth_tongue` then `mouth_teeth`, cut from the
+ * interior and clipped to it: the rig reads nothing off them but their box.
+ *
+ * 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).
+ *
+ * The line is thinned at every key: its column is squashed toward its bottom
+ * edge by `UPPER_THIN` (`Tu` in the opening, the line's own bottom past it),
+ * one scale per column so the mesh, linear between its rows, keeps that edge
+ * where it was drawn. The thin belongs to the stack above the line's bottom,
+ * not to the line alone: the contract lets the interior reach up inside the
+ * line's ink (`Tu <= T <= lineTop`), and a line thinned over it would uncover
+ * it under its old top, so the interior's rows above `Tu` come down by the
+ * same scale. The fold below acts on the thinned positions.
+ *
+ * MouthOpen 0 folds shut onto a seam, 1 is the art as drawn and thinned (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, 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.
+ *
+ * Shut, the line is shaped the way an artist draws a closed mouth: from
+ * `END_TAPER_FROM` of the opening's half-width out, each column is squashed
+ * about its thinned centre row, down to `END_TAPER` of its height at the
+ * line's box edge, so the ends taper; the drawn flick past a corner is pulled
+ * toward it (`FLICK_PULL`) and squashed to `FLICK_SQUASH`. Every closed-key
+ * shape is linear in `1 - v`. `w'` therefore follows the shaped line, not the
+ * drawn one: it is measured up from the closed line's bottom edge (which the
+ * taper raises by half the height it takes off) by the stroke `w` (the line's
+ * height at the opening's centre), capped by the column's own ink and thinned
+ * and squashed with the line. The skin's top and the interior's closing point
+ * then stay inside the line's closed ink at every column, the tapered ends
+ * included, and tucked skin never shows above the line.
+ *
+ * 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.
+ *
+ * The lower lip's columns outside the opening (the corner hooks) do not fold,
+ * the line's are only thinned and shaped (no travel), and the interior's edge
+ * columns read the nearest opening column.
+ *
+ * The inside parts move rigidly per column, after the stack's thin: the teeth
+ * by the line's travel, so they ride under its bottom edge (no taper: the
+ * closed interior clips them away), the tongue by the interior's bottom-edge
+ * travel, so it rides the opening's bottom.
+ *
+ * Knots: the 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 resamples each column through the lip meshes' own landed rows
+ * (`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 shut: inside the thinned,
+     *  squashed line's ink. */
+    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;
+    /** The upper line at a column of `lip_upper`, model y: inside the opening
+     *  the run the contract reads (`Tu`, `lineTop`) and the closed taper's
+     *  squash; past it (the drawn flick) the column's own ink span and
+     *  `FLICK_SQUASH`; `undefined` where `lip_upper` has no run. */
+    line(col: number): {
+        bottom: number;
+        top: number;
+        squash: number;
+    } | undefined;
+}
+declare function mouthOpening(byRole: Map<string, LayerInput>): Opening;
+/**
+ * `[dx, dy]` of a model-y rest position at pixel column `col` for MouthOpen
+ * `v` (0 shut, 1 as drawn), the thin first at every `v` and the fold on the
+ * thinned position. `lip_upper`'s column is squashed toward its line's bottom;
+ * shut, squashed by its `squash` about the thinned centre row and carried by
+ * the travel, or past the opening (the drawn flick, which now moves too)
+ * squashed and pulled toward the corner. `lip_lower` moves by its travel in
+ * the opening and 0 outside it. `mouth_inner`, its rows above `Tu` thinned,
+ * 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.
+ * `mouth_teeth`, its rows above `Tu` thinned, moves by the line's travel and
+ * `mouth_tongue` by the interior's bottom edge's, each one number per column.
+ */
+declare function mouthFold(role: LipRole | LipInsideRole, opening: Opening): (col: number, y: number, v: number) => [number, number];
+/** A lip's dy at MouthOpen 0 at a canvas pixel `(col, row)` as the mesh
+ *  renders it, for the composer's closed preview: read at the pixel's centre
+ *  off the STORED offsets (the numbers the `.iki` carries, rounded as
+ *  `localWarp` rounds them) of the `columnMesh` triangle containing it — the
+ *  cell by knot and row, its triangle by the cell's top-left–bottom-right
+ *  diagonal, the three vertices weighted barycentrically. The thin and the
+ *  taper move a column's rows by different amounts and the renderer is
+ *  linear over a triangle, never bilinear over a cell, so no one row stands
+ *  for the column. `undefined` for a pixel centre outside the part's box (the
+ *  mesh's domain), which has no field. `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, row: number) => number | undefined;
+
 /**
  * `generateIkiFromLayerSet`: role layers in, a rigged `.iki` out.
  *
@@ -1026,7 +1202,8 @@ declare function parseLayerRoles(fileNames: string[]): {
  * the default expressions and the Nod, Shake and Tilt motions, and
  * 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`).
+ * crossfades; the lip set folds open like the eyelid (`mouth.ts`), its
+ * optional `mouth_tongue` and `mouth_teeth` clipped to its interior.
  */
 
 declare function generateIkiFromLayerSet(layers: LayerInput[], canvas: {
@@ -1424,4 +1601,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_INSIDE_ROLES, LIP_ROLES, LayerGeometryError, type LayerInput, type LayerSetMeasurement, type LayerSetMeasurer, type LipInsideRole, 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, isLipInsideRole, isSpeckCore, mouthFold, mouthOpening, mouthRestShift, packAtlas, parseLayerRoles, partIdsOfRole, upsertGridKeyform, uvRectFor, validateDeformerDelete, validateDeformerReparent, validatePartAttach };

package/dist/index.d.ts

@@ -993,20 +993,196 @@ 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 lip set's optional inside parts, back to front: cut from the interior
+ *  and clipped to `mouth_inner` (`mouth.ts`). */
+declare const LIP_INSIDE_ROLES: readonly ["mouth_tongue", "mouth_teeth"];
+type LipInsideRole = (typeof LIP_INSIDE_ROLES)[number];
+declare const isLipInsideRole: (role: string) => role is LipInsideRole;
 /** 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`) 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.
+ * lip set) or a partial or mixed one, a lip set's inside part without the set,
+ * 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). Between the interior and the skin it may
+ * carry two inside parts, `mouth_tongue` then `mouth_teeth`, cut from the
+ * interior and clipped to it: the rig reads nothing off them but their box.
+ *
+ * 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).
+ *
+ * The line is thinned at every key: its column is squashed toward its bottom
+ * edge by `UPPER_THIN` (`Tu` in the opening, the line's own bottom past it),
+ * one scale per column so the mesh, linear between its rows, keeps that edge
+ * where it was drawn. The thin belongs to the stack above the line's bottom,
+ * not to the line alone: the contract lets the interior reach up inside the
+ * line's ink (`Tu <= T <= lineTop`), and a line thinned over it would uncover
+ * it under its old top, so the interior's rows above `Tu` come down by the
+ * same scale. The fold below acts on the thinned positions.
+ *
+ * MouthOpen 0 folds shut onto a seam, 1 is the art as drawn and thinned (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, 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.
+ *
+ * Shut, the line is shaped the way an artist draws a closed mouth: from
+ * `END_TAPER_FROM` of the opening's half-width out, each column is squashed
+ * about its thinned centre row, down to `END_TAPER` of its height at the
+ * line's box edge, so the ends taper; the drawn flick past a corner is pulled
+ * toward it (`FLICK_PULL`) and squashed to `FLICK_SQUASH`. Every closed-key
+ * shape is linear in `1 - v`. `w'` therefore follows the shaped line, not the
+ * drawn one: it is measured up from the closed line's bottom edge (which the
+ * taper raises by half the height it takes off) by the stroke `w` (the line's
+ * height at the opening's centre), capped by the column's own ink and thinned
+ * and squashed with the line. The skin's top and the interior's closing point
+ * then stay inside the line's closed ink at every column, the tapered ends
+ * included, and tucked skin never shows above the line.
+ *
+ * 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.
+ *
+ * The lower lip's columns outside the opening (the corner hooks) do not fold,
+ * the line's are only thinned and shaped (no travel), and the interior's edge
+ * columns read the nearest opening column.
+ *
+ * The inside parts move rigidly per column, after the stack's thin: the teeth
+ * by the line's travel, so they ride under its bottom edge (no taper: the
+ * closed interior clips them away), the tongue by the interior's bottom-edge
+ * travel, so it rides the opening's bottom.
+ *
+ * Knots: the 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 resamples each column through the lip meshes' own landed rows
+ * (`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 shut: inside the thinned,
+     *  squashed line's ink. */
+    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;
+    /** The upper line at a column of `lip_upper`, model y: inside the opening
+     *  the run the contract reads (`Tu`, `lineTop`) and the closed taper's
+     *  squash; past it (the drawn flick) the column's own ink span and
+     *  `FLICK_SQUASH`; `undefined` where `lip_upper` has no run. */
+    line(col: number): {
+        bottom: number;
+        top: number;
+        squash: number;
+    } | undefined;
+}
+declare function mouthOpening(byRole: Map<string, LayerInput>): Opening;
+/**
+ * `[dx, dy]` of a model-y rest position at pixel column `col` for MouthOpen
+ * `v` (0 shut, 1 as drawn), the thin first at every `v` and the fold on the
+ * thinned position. `lip_upper`'s column is squashed toward its line's bottom;
+ * shut, squashed by its `squash` about the thinned centre row and carried by
+ * the travel, or past the opening (the drawn flick, which now moves too)
+ * squashed and pulled toward the corner. `lip_lower` moves by its travel in
+ * the opening and 0 outside it. `mouth_inner`, its rows above `Tu` thinned,
+ * 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.
+ * `mouth_teeth`, its rows above `Tu` thinned, moves by the line's travel and
+ * `mouth_tongue` by the interior's bottom edge's, each one number per column.
+ */
+declare function mouthFold(role: LipRole | LipInsideRole, opening: Opening): (col: number, y: number, v: number) => [number, number];
+/** A lip's dy at MouthOpen 0 at a canvas pixel `(col, row)` as the mesh
+ *  renders it, for the composer's closed preview: read at the pixel's centre
+ *  off the STORED offsets (the numbers the `.iki` carries, rounded as
+ *  `localWarp` rounds them) of the `columnMesh` triangle containing it — the
+ *  cell by knot and row, its triangle by the cell's top-left–bottom-right
+ *  diagonal, the three vertices weighted barycentrically. The thin and the
+ *  taper move a column's rows by different amounts and the renderer is
+ *  linear over a triangle, never bilinear over a cell, so no one row stands
+ *  for the column. `undefined` for a pixel centre outside the part's box (the
+ *  mesh's domain), which has no field. `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, row: number) => number | undefined;
+
 /**
  * `generateIkiFromLayerSet`: role layers in, a rigged `.iki` out.
  *
@@ -1026,7 +1202,8 @@ declare function parseLayerRoles(fileNames: string[]): {
  * the default expressions and the Nod, Shake and Tilt motions, and
  * 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`).
+ * crossfades; the lip set folds open like the eyelid (`mouth.ts`), its
+ * optional `mouth_tongue` and `mouth_teeth` clipped to its interior.
  */
 
 declare function generateIkiFromLayerSet(layers: LayerInput[], canvas: {
@@ -1424,4 +1601,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_INSIDE_ROLES, LIP_ROLES, LayerGeometryError, type LayerInput, type LayerSetMeasurement, type LayerSetMeasurer, type LipInsideRole, 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, isLipInsideRole, isSpeckCore, mouthFold, mouthOpening, mouthRestShift, packAtlas, parseLayerRoles, partIdsOfRole, upsertGridKeyform, uvRectFor, validateDeformerDelete, validateDeformerReparent, validatePartAttach };