@ikijs/editor 0.22.0 → 0.24.0

package/README.md

@@ -57,7 +57,7 @@ leaves the document untouched.
 ## 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

@@ -891,9 +891,12 @@ interface GenerateOptions {
  * wedge carries the painted line, fading out in the antialias column as the
  * painted edge does; the fan inside it is the crop's own pixels.
  *
- * Draw order: hair_back < body < elbow_L, arm_L, forearm_L, elbow_R, arm_R,
- * forearm_R < face … < hair_front. The forearm draws over the upper arm,
- * which draws over the cap.
+ * Draw order: hair_back < body < elbow_L, forearm_L, arm_L, elbow_R,
+ * forearm_R, arm_R < face … < hair_front. The upper arm draws over the
+ * forearm, which draws over the cap. On the inside of a bend the bands
+ * overlap, and the forearm's seam-row cut stays under the upper arm there, so
+ * the overlap shows the upper arm's bottom edge at the elbow row instead of
+ * the cut rotated up the sleeve.
  *
  * Signs: ParamArmX + raises the arm outward on either side, in degrees 1:1.
  * A rotation is CCW-positive, so an arm whose shoulder lies right of the
@@ -996,14 +999,19 @@ 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;
@@ -1014,7 +1022,9 @@ declare function parseLayerRoles(fileNames: 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).
+ * 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
@@ -1028,43 +1038,75 @@ declare function parseLayerRoles(fileNames: string[]): {
  * 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 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.
  *
- * 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.
+ * 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.
  *
- * A lip's columns outside the opening (the corner hooks) do not fold; only
- * the interior's edge columns read the nearest opening column.
+ * 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.
  *
- * Knots: the three parts share column knots every `MOUTH_KNOT_PX` plus the
+ * Shut, the line is a smooth parabola across the opening. Its chord joins the
+ * line's smoothed bottom (below) at the two end columns; its depth below the
+ * chord, half way, is the sag at the centre column of the drawn arc plus a
+ * fitted closing travel: a cubic in the column index, pinned to zero at the
+ * end columns and 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. That sag is capped at `CLOSED_SAG_MAX` of the
+ * opening's width, the drawn arc included, so a deep opening closes into a
+ * gentle smile and a line drawn deeper than the cap closes flatter than
+ * drawn. The seam is `Tu` plus the column's travel: the parabola minus the
+ * line's bottom averaged over 3 columns each side (the smoothed bottom), not
+ * minus `Tu` itself, so the end columns do not travel. `Tu` is an integer-row read, and a curve minus that staircase
+ * is a sawtooth the mesh would carry into the rendered line; against the
+ * smoothed bottom the stroke (whose antialiased edge is smooth) moves as one
+ * piece, and a kink drawn in it (a V at the centre) keeps only its offset
+ * from that average, which the cap counts in. Every closed shape and the
+ * preview are read off the seam.
+ *
+ * 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
+ * boundary. The travel'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
+ * travel 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
+ * 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
@@ -1093,10 +1135,11 @@ interface OpeningColumn {
     Bl: number;
     /** The interior's span. */
     H: number;
-    /** How far the skin tucks up under the line. */
+    /** 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. */
+    /** Where the lips meet when shut: the line's bottom edge after its closing
+     *  travel. */
     seam: number;
 }
 interface Opening {
@@ -1110,23 +1153,44 @@ interface Opening {
     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;
 /**
- * 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`
+ * `[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, 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;
+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.
@@ -1147,7 +1211,8 @@ declare function mouthRestShift(byRole: Map<string, LayerInput>): (role: "lip_up
  * 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: {
@@ -1451,10 +1516,17 @@ interface AtlasLayout {
  * BOTTOM only. Page left/top edges need no gutter.
  *
  * pageWidth/pageHeight = tight bound (max x+width+padding, max y+height+padding).
+ * When `maxSide` is given and the first layout is taller than it but not wider,
+ * the pack is retried at every width from the widest padded source up to `maxSide`, and the first
+ * layout that fits the height wins (shelf height is not monotonic in width);
+ * when none does the first is returned for the caller to refuse. The attempts
+ * are every width for this shelf order, not a proof that no packing exists.
+ *
  * Empty sources → { pageWidth: 0, pageHeight: 0, placements: [], padding }.
- * Throws a plain Error naming the offending source id on a non-finite or <= 0 dimension.
+ * Throws a plain Error naming the offending source id on a non-finite or <= 0 dimension,
+ * and on a supplied `maxSide` that is non-finite or <= 0.
  */
-declare function packAtlas(sources: AtlasSource[], padding?: number): AtlasLayout;
+declare function packAtlas(sources: AtlasSource[], padding?: number, maxSide?: number): AtlasLayout;
 /**
  * Convert a pixel placement into a UV rect, inset by `insetPx` on all four
  * edges and clamped to [0, 1] so the validator's bounds check always passes.
@@ -1545,4 +1617,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, 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 };
+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

@@ -891,9 +891,12 @@ interface GenerateOptions {
  * wedge carries the painted line, fading out in the antialias column as the
  * painted edge does; the fan inside it is the crop's own pixels.
  *
- * Draw order: hair_back < body < elbow_L, arm_L, forearm_L, elbow_R, arm_R,
- * forearm_R < face … < hair_front. The forearm draws over the upper arm,
- * which draws over the cap.
+ * Draw order: hair_back < body < elbow_L, forearm_L, arm_L, elbow_R,
+ * forearm_R, arm_R < face … < hair_front. The upper arm draws over the
+ * forearm, which draws over the cap. On the inside of a bend the bands
+ * overlap, and the forearm's seam-row cut stays under the upper arm there, so
+ * the overlap shows the upper arm's bottom edge at the elbow row instead of
+ * the cut rotated up the sleeve.
  *
  * Signs: ParamArmX + raises the arm outward on either side, in degrees 1:1.
  * A rotation is CCW-positive, so an arm whose shoulder lies right of the
@@ -996,14 +999,19 @@ 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;
@@ -1014,7 +1022,9 @@ declare function parseLayerRoles(fileNames: 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).
+ * 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
@@ -1028,43 +1038,75 @@ declare function parseLayerRoles(fileNames: string[]): {
  * 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 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.
  *
- * 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.
+ * 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.
  *
- * A lip's columns outside the opening (the corner hooks) do not fold; only
- * the interior's edge columns read the nearest opening column.
+ * 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.
  *
- * Knots: the three parts share column knots every `MOUTH_KNOT_PX` plus the
+ * Shut, the line is a smooth parabola across the opening. Its chord joins the
+ * line's smoothed bottom (below) at the two end columns; its depth below the
+ * chord, half way, is the sag at the centre column of the drawn arc plus a
+ * fitted closing travel: a cubic in the column index, pinned to zero at the
+ * end columns and 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. That sag is capped at `CLOSED_SAG_MAX` of the
+ * opening's width, the drawn arc included, so a deep opening closes into a
+ * gentle smile and a line drawn deeper than the cap closes flatter than
+ * drawn. The seam is `Tu` plus the column's travel: the parabola minus the
+ * line's bottom averaged over 3 columns each side (the smoothed bottom), not
+ * minus `Tu` itself, so the end columns do not travel. `Tu` is an integer-row read, and a curve minus that staircase
+ * is a sawtooth the mesh would carry into the rendered line; against the
+ * smoothed bottom the stroke (whose antialiased edge is smooth) moves as one
+ * piece, and a kink drawn in it (a V at the centre) keeps only its offset
+ * from that average, which the cap counts in. Every closed shape and the
+ * preview are read off the seam.
+ *
+ * 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
+ * boundary. The travel'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
+ * travel 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
+ * 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
@@ -1093,10 +1135,11 @@ interface OpeningColumn {
     Bl: number;
     /** The interior's span. */
     H: number;
-    /** How far the skin tucks up under the line. */
+    /** 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. */
+    /** Where the lips meet when shut: the line's bottom edge after its closing
+     *  travel. */
     seam: number;
 }
 interface Opening {
@@ -1110,23 +1153,44 @@ interface Opening {
     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;
 /**
- * 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`
+ * `[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, 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;
+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.
@@ -1147,7 +1211,8 @@ declare function mouthRestShift(byRole: Map<string, LayerInput>): (role: "lip_up
  * 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: {
@@ -1451,10 +1516,17 @@ interface AtlasLayout {
  * BOTTOM only. Page left/top edges need no gutter.
  *
  * pageWidth/pageHeight = tight bound (max x+width+padding, max y+height+padding).
+ * When `maxSide` is given and the first layout is taller than it but not wider,
+ * the pack is retried at every width from the widest padded source up to `maxSide`, and the first
+ * layout that fits the height wins (shelf height is not monotonic in width);
+ * when none does the first is returned for the caller to refuse. The attempts
+ * are every width for this shelf order, not a proof that no packing exists.
+ *
  * Empty sources → { pageWidth: 0, pageHeight: 0, placements: [], padding }.
- * Throws a plain Error naming the offending source id on a non-finite or <= 0 dimension.
+ * Throws a plain Error naming the offending source id on a non-finite or <= 0 dimension,
+ * and on a supplied `maxSide` that is non-finite or <= 0.
  */
-declare function packAtlas(sources: AtlasSource[], padding?: number): AtlasLayout;
+declare function packAtlas(sources: AtlasSource[], padding?: number, maxSide?: number): AtlasLayout;
 /**
  * Convert a pixel placement into a UV rect, inset by `insetPx` on all four
  * edges and clamped to [0, 1] so the validator's bounds check always passes.
@@ -1545,4 +1617,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, 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 };
+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 };