@ikijs/editor 0.19.0 → 0.21.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`, `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`, `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
@@ -85,6 +85,10 @@ hangs from it. `arm_L` / `arm_R`, each a whole arm drawn hanging with its
 shoulder at the top, hang from it too: each becomes an elbow cap, an upper
 arm and a forearm cut from the one crop, turning about the shoulder and the
 elbow on `ParamArmL/R` and `ParamElbowL/R`. An arm needs a `body`.
+`forearm_pose_L` / `forearm_pose_R`, a second forearm drawn raised, swap in for
+the hanging one at the elbow on `ParamArmPoseL/R` and rock on
+`ParamArmPoseAngleL/R`; a model with them also declares a `Wave` motion. A
+pose forearm needs its arm.
 
 On a layer set with a `nose`, `options.turnTargets` — the cues a 30° reference
 measures (how far the eye pair slides, how much the far eye foreshortens,

package/dist/index.d.mts

@@ -713,14 +713,18 @@ interface LayerInput {
     cropH: number;
     /** 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` only:
+    /** `face` / `hair_front` / `hair_back` / `body` / `arm_L` / `arm_R` /
+     *  `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. */
+     *  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?: {
@@ -767,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);
@@ -923,9 +929,9 @@ interface ArmGeometry {
  * The arm's pivots, read off the widest opaque run of each crop row
  * (`rowRuns`); a row without one, or a layer without runs, reads as the
  * crop:
- * - r_u is half the median width over the `CAP_ROWS` rows;
- * - the shoulder pivot lies r_u under the first painted row's centre, at the
- *   run centre of the row it lands in;
+ * - the shoulder pivot and r_u are `endPivot(layer, "top")`: r_u is half the
+ *   median width over the `CAP_ROWS` rows, the pivot lies r_u under the first
+ *   painted row's centre, at the run centre of the row it lands in;
  * - the elbow is the centre of the row `ELBOW_AT` of the way from there to
  *   the last painted row, at its run centre;
  * - the cap radius is half the elbow's run + 1 px, kept inside the crop;
@@ -941,13 +947,60 @@ interface ArmGeometry {
  */
 declare function armGeometry(layer: LayerInput, bodyAxisX: number): ArmGeometry;
 
+/**
+ * The pose forearm. A second drawn forearm per side (`forearm_pose_L` /
+ * `forearm_pose_R`), drawn raised: it hangs from the arm's elbow and is
+ * swapped in for the hanging forearm by a switch.
+ * - One part, the role's own id, over its crop's box on `armPoseDeformer_X`,
+ *   a child of `armDeformer_X` pivoting at the arm's elbow. It is not a child
+ *   of `forearmDeformer_X`, so `ParamElbowX` never moves it, and the shoulder
+ *   still carries it.
+ * - `ParamArmPoseX` (0..1) swaps: the hanging forearm and the elbow cap fade
+ *   out on it, 1 to 0 (`armParts`), the pose forearm fades in, 0 to 1. The
+ *   pair is exclusive by construction, and between the ends both show at
+ *   partial opacity. The part has no mesh: the engine draws a meshless part
+ *   as its full-box quad with its texture rect, and a rigid part needs no
+ *   more.
+ * - `ParamArmPoseAngleX` rocks it about the elbow, in degrees over
+ *   `POSE_ANGLE_RANGE`. + tips the raised hand outward, away from the body,
+ *   mirrored per side. The part points up from its pivot where the hanging
+ *   forearm points down, so its rotate binding takes −side × the value; the
+ *   elbow's multiplier is the same −side, which gives the shoulder's reading.
+ * The composer puts the drawing's elbow end on the pivot (`measure` warns
+ * when it is off), so the rig does not use the crop's own pivot
+ * (`forearmPoseGeometry`).
+ *
+ * It draws after the hair, above the face and the front hair: a raised hand
+ * passes them (`ROLE_TABLE`).
+ */
+
+interface ForearmPoseGeometry {
+    /** The elbow end's pivot, model space: where the drawing's elbow end is
+     *  centred. */
+    pivot: {
+        x: number;
+        y: number;
+    };
+    /** r_e: half the elbow end's width, px. */
+    radius: number;
+    /** The first painted row's model y: the raised hand's top. */
+    top: number;
+}
+/**
+ * The pose forearm's own geometry: the shoulder rule run from the bottom
+ * (`endPivot`), since it is drawn standing up from its elbow, plus the top of
+ * the paint.
+ */
+declare function forearmPoseGeometry(layer: LayerInput): ForearmPoseGeometry;
+
 /** 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, or an arm
- * without a body.
+ * 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;
@@ -962,15 +1015,18 @@ declare function parseLayerRoles(fileNames: string[]): {
  * turns on BodyAngleX/Y/Z, its legs planted; a head deformer hung from it
  * that rolls about the chin and breathes; each arm hung from it too, as an
  * upper arm, a forearm and an elbow cap turning about the shoulder and the
- * elbow (`arms.ts`); one small warp grid per feature
+ * elbow (`arms.ts`), and with a drawn pose forearm a switch that swaps it in
+ * for the hanging one (`forearm-pose.ts`); one small warp grid per feature
  * (each eye, each brow, the nose, the mouth), translating and foreshortening
  * it by its own lead over the plate; and the plate, the hair and the blush
  * moved by per-vertex keyforms of their own — the plate as up to four
  * islands of one drawing: a head that slides, a neck that stays on the torso
  * 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
- * (`animations.ts`).
+ * 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`).
  */
 
 declare function generateIkiFromLayerSet(layers: LayerInput[], canvas: {
@@ -1106,11 +1162,12 @@ interface RgbaLayer {
 interface LayerSetMeasurer {
     /**
      * Measure one layer while its `rgba` is in memory, keeping no reference to
-     * it: only the set's opaque union, this layer's per-row opaque extent and
+     * it: only the set's opaque union (a pose forearm, hidden at rest, stays out
+     * 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 and
-     * arms' `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
@@ -1367,4 +1424,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, 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, 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, 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 };

package/dist/index.d.ts

@@ -713,14 +713,18 @@ interface LayerInput {
     cropH: number;
     /** 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` only:
+    /** `face` / `hair_front` / `hair_back` / `body` / `arm_L` / `arm_R` /
+     *  `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. */
+     *  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?: {
@@ -767,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);
@@ -923,9 +929,9 @@ interface ArmGeometry {
  * The arm's pivots, read off the widest opaque run of each crop row
  * (`rowRuns`); a row without one, or a layer without runs, reads as the
  * crop:
- * - r_u is half the median width over the `CAP_ROWS` rows;
- * - the shoulder pivot lies r_u under the first painted row's centre, at the
- *   run centre of the row it lands in;
+ * - the shoulder pivot and r_u are `endPivot(layer, "top")`: r_u is half the
+ *   median width over the `CAP_ROWS` rows, the pivot lies r_u under the first
+ *   painted row's centre, at the run centre of the row it lands in;
  * - the elbow is the centre of the row `ELBOW_AT` of the way from there to
  *   the last painted row, at its run centre;
  * - the cap radius is half the elbow's run + 1 px, kept inside the crop;
@@ -941,13 +947,60 @@ interface ArmGeometry {
  */
 declare function armGeometry(layer: LayerInput, bodyAxisX: number): ArmGeometry;
 
+/**
+ * The pose forearm. A second drawn forearm per side (`forearm_pose_L` /
+ * `forearm_pose_R`), drawn raised: it hangs from the arm's elbow and is
+ * swapped in for the hanging forearm by a switch.
+ * - One part, the role's own id, over its crop's box on `armPoseDeformer_X`,
+ *   a child of `armDeformer_X` pivoting at the arm's elbow. It is not a child
+ *   of `forearmDeformer_X`, so `ParamElbowX` never moves it, and the shoulder
+ *   still carries it.
+ * - `ParamArmPoseX` (0..1) swaps: the hanging forearm and the elbow cap fade
+ *   out on it, 1 to 0 (`armParts`), the pose forearm fades in, 0 to 1. The
+ *   pair is exclusive by construction, and between the ends both show at
+ *   partial opacity. The part has no mesh: the engine draws a meshless part
+ *   as its full-box quad with its texture rect, and a rigid part needs no
+ *   more.
+ * - `ParamArmPoseAngleX` rocks it about the elbow, in degrees over
+ *   `POSE_ANGLE_RANGE`. + tips the raised hand outward, away from the body,
+ *   mirrored per side. The part points up from its pivot where the hanging
+ *   forearm points down, so its rotate binding takes −side × the value; the
+ *   elbow's multiplier is the same −side, which gives the shoulder's reading.
+ * The composer puts the drawing's elbow end on the pivot (`measure` warns
+ * when it is off), so the rig does not use the crop's own pivot
+ * (`forearmPoseGeometry`).
+ *
+ * It draws after the hair, above the face and the front hair: a raised hand
+ * passes them (`ROLE_TABLE`).
+ */
+
+interface ForearmPoseGeometry {
+    /** The elbow end's pivot, model space: where the drawing's elbow end is
+     *  centred. */
+    pivot: {
+        x: number;
+        y: number;
+    };
+    /** r_e: half the elbow end's width, px. */
+    radius: number;
+    /** The first painted row's model y: the raised hand's top. */
+    top: number;
+}
+/**
+ * The pose forearm's own geometry: the shoulder rule run from the bottom
+ * (`endPivot`), since it is drawn standing up from its elbow, plus the top of
+ * the paint.
+ */
+declare function forearmPoseGeometry(layer: LayerInput): ForearmPoseGeometry;
+
 /** 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, or an arm
- * without a body.
+ * 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;
@@ -962,15 +1015,18 @@ declare function parseLayerRoles(fileNames: string[]): {
  * turns on BodyAngleX/Y/Z, its legs planted; a head deformer hung from it
  * that rolls about the chin and breathes; each arm hung from it too, as an
  * upper arm, a forearm and an elbow cap turning about the shoulder and the
- * elbow (`arms.ts`); one small warp grid per feature
+ * elbow (`arms.ts`), and with a drawn pose forearm a switch that swaps it in
+ * for the hanging one (`forearm-pose.ts`); one small warp grid per feature
  * (each eye, each brow, the nose, the mouth), translating and foreshortening
  * it by its own lead over the plate; and the plate, the hair and the blush
  * moved by per-vertex keyforms of their own — the plate as up to four
  * islands of one drawing: a head that slides, a neck that stays on the torso
  * 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
- * (`animations.ts`).
+ * 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`).
  */
 
 declare function generateIkiFromLayerSet(layers: LayerInput[], canvas: {
@@ -1106,11 +1162,12 @@ interface RgbaLayer {
 interface LayerSetMeasurer {
     /**
      * Measure one layer while its `rgba` is in memory, keeping no reference to
-     * it: only the set's opaque union, this layer's per-row opaque extent and
+     * it: only the set's opaque union (a pose forearm, hidden at rest, stays out
+     * 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 and
-     * arms' `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
@@ -1367,4 +1424,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, 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, 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, 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 };