@ikijs/editor 0.30.1 → 0.32.0

package/README.md

@@ -40,19 +40,19 @@ 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`, `mouthOpening`, `mouthFold`, `mouthRestShift`, `columnRuns`, `LIP_ROLES`, `LipRole`, `Opening`, `OpeningColumn`, `TurnTargets`, `DEFAULT_TURN_TARGETS`, `TurnSolveReport`, `HairSideRoom`, `RigPlan`, `RigPlanError`, `RIG_PLAN_FIELDS`, `RigPlanReport`, `RigPatch`, `PatchReport`, `PatchError`, `SHUT_BY`, `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`, `HairSideRoom`, `RigPlan`, `RigPlanError`, `RIG_PLAN_FIELDS`, `RigPlanReport`, `RigPatch`, `PatchReport`, `PatchError`, `RigBakes`, `BakeTarget`, `BakeReport`, `BakeError`, `rigidResidual`, `SHUT_BY`, `LayerGeometryError` |
+| Bindings           | `captureBindingEndpoint`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
 
 ## Auto-rig
 
@@ -100,7 +100,19 @@ profile in three groups (`turn`, `hair`, `eyes`: the whole turn, the
 features' lead, the front hair's follow and its outline's, the blink and the
 hair sway), validated against `RIG_PLAN_FIELDS`. `options.patches` adds displacements to a generated rig's keyform
 stops (`RigPatch`), replayed on every rig and reported through
-`options.onPatchesApplied`; a refused op throws `PatchError`. The turn
+`options.onPatchesApplied`; a refused op throws `PatchError`. `options.customParts` adds parts the
+auto-rigger has no role for (`CustomPart`: `id`, `layer`, `anchor`, `tie`,
+`after`, and `occlusion`: roles whose parts hide it by an amount keyed on a
+parameter), unrigged on `headDeformer` with a plain mesh and drawn after the
+`after` role's last part; the rest of the model is as without them but for
+the `order` of every part after an inserted one (a set rigged without
+`customParts` is byte-identical), and a malformed entry throws
+`CustomPartError`. `options.bakes` (`RigBakes`: control lattices per
+parameter stop, `meshes` to re-mesh) writes warps on those parts that
+land them where the lattice asks, solved in closed form through the
+head's frame; a `rigid` custom part refuses a bend over 0.0025 face
+widths (`rigidResidual`), a refused input throws `BakeError`, and
+`options.onBakesApplied` gets what each part was asked for. The turn
 is bounded by the art: the far eye stays inside the plate's outline and, given
 `options.strandEdges`, the far iris may not slide under the bangs' side strand
 any further than it is painted — best effort, never a refusal. The report's

package/dist/index.d.mts

@@ -251,10 +251,11 @@ declare class AddDeformer implements EditCommand {
  * visually predictable.
  *
  * No `parseIkiModel` pre-check is needed: removing an element from an already-
- * valid model cannot introduce a structural violation — EXCEPT for clip-mask
- * references, the one part→part reference in the contract. `apply` refuses to
- * delete a part still used as another part's `clip.masks` entry (guard below),
- * so it can never leave a dangling mask ref that would fail `toIkiModel()`.
+ * valid model cannot introduce a structural violation — EXCEPT for the part→part
+ * references in the contract: `clip.masks` and `occlusion.by`. `apply` refuses to
+ * delete a part still used as another part's `clip.masks` or `occlusion.by`
+ * entry (guards below), so it can never leave a dangling ref that would fail
+ * `toIkiModel()`.
  *
  * Texture-reference safety (package invariant): `apply` refuses to delete a
  * part that still carries `part.texture`. Texture/atlas state is non-undoable
@@ -1052,6 +1053,145 @@ interface PatchReport {
 declare class PatchError extends Error {
     constructor(message: string);
 }
+/**
+ * A part the auto-rigger has no role for (a hairpin, a twin tail): drawn from
+ * its own canvas-sized layer, hung on the head with plain warps.
+ */
+interface CustomPart {
+    /** A plain identifier; never a role's name or a part id a role yields. */
+    id: string;
+    layer: {
+        fileName: string;
+        /** The layer's alpha box in canvas px, as `LayerInput.bbox`. */
+        bbox: {
+            x: number;
+            y: number;
+            w: number;
+            h: number;
+        };
+    };
+    /** The role whose layer the part is fixed against. */
+    anchor: string;
+    /** Where the part meets the anchor, canvas px: inside both layers' boxes. */
+    tie: [number, number];
+    /** A role of the set: the part is drawn right after that role's last part. */
+    after: string;
+    /** The matrix deformer it hangs on; only `headDeformer` (the default) is
+     *  accepted. */
+    deformer?: string;
+    /** The art does not bend (a hairpin, a ribbon): a bake that bends it more
+     *  than 0.0025 face widths at a stop is refused (`BakeError`). */
+    rigid?: boolean;
+    /** Hide the part where the parts of these roles cover it, by an amount keyed on a
+     *  parameter (`IkiPart.occlusion`). `by` lists roles of the set: the
+     *  generator writes the part ids those roles yield. The parameter is one
+     *  the model declares and not a physics output; the stops follow the
+     *  format's rules. */
+    occlusion?: {
+        by: string[];
+        parameter: string;
+        stops: {
+            value: number;
+            amount: number;
+        }[];
+    };
+}
+/** A `customParts` entry that is malformed or misses the layer set. Its
+ *  message starts `customParts[i].<field>` (`customParts` alone for a
+ *  non-array). */
+declare class CustomPartError extends Error {
+    constructor(message: string);
+}
+/**
+ * One lattice a bake spreads over the custom parts it names: `(cols + 1) x
+ * (rows + 1)` control points laid evenly over `box`, listed row-major from the
+ * top-left (the top row first, each row left to right). Every position and
+ * displacement is in canvas px, origin top-left, y DOWN.
+ *
+ * A stop is exact where the bake writes it, and so is the end key a side's
+ * outermost stop gets at the parameter's range end; between keys the motion
+ * is interpolated, and under a parent that rotates with the parameter (the
+ * head's roll) it bows off the straight line, so put a stop where the path
+ * matters. A side with no stop is not moved by this target. Targets that name the same part and
+ * parameter add.
+ */
+interface BakeTarget {
+    /** A label for reports; the rig ignores it. */
+    id?: string;
+    /** A parameter the model declares. */
+    param: string;
+    /** Custom part ids only: a bake moves nothing else. */
+    parts: string[];
+    /** Canvas px; absent, the union of the parts' rest boxes grown by 2 px. */
+    box?: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    };
+    /** Integers 1 to 32. */
+    grid: {
+        cols: number;
+        rows: number;
+    };
+    /** Keyed by a value of `param` inside its range, never its default (rest is
+     *  implicit). A stop is the part's TOTAL landed displacement from rest when
+     *  `param` alone is at that value and every other parameter is at its
+     *  default: the head's own carry is included, so a neighbour's measured
+     *  displacement at that pose is written as it is. */
+    stops: Record<string, [number, number][]>;
+    /** Fill a missing stop from the one at the value mirrored about the rest
+     *  value: the lattice reflected about the box's vertical centre line, `dx`
+     *  negated. A written stop is never overwritten. */
+    mirror?: boolean;
+    /** Why the target exists, for whoever edits the bakes next; ignored. */
+    why?: string;
+}
+/**
+ * Lattice bakes for custom parts: what moves them when the head turns or the
+ * hair sways, which an unrigged custom part otherwise does not. A bake moves
+ * custom parts only.
+ */
+interface RigBakes {
+    targets: BakeTarget[];
+    /** Re-mesh a custom part before baking: `rows` (canvas-px y, strictly
+     *  increasing, first the part's top and last its bottom within 0.5 px) with
+     *  `cols`, or `cellPx` for a uniform grid. "The box" here is the part's own
+     *  rest box (its layer's bbox), not a target's `box`. */
+    meshes?: Record<string, {
+        rows: number[];
+        cols: number;
+    } | {
+        cellPx: number;
+    }>;
+}
+/** What a bake asked of one custom part on one parameter, for a caller that
+ *  checks the landing. */
+interface BakeReport {
+    part: string;
+    param: string;
+    /** The stops written, ascending (rest, implicit, not among them). */
+    stops: number[];
+    vertexCount: number;
+    /** Per stop, in `stops` order: each vertex's wanted displacement from rest,
+     *  `[dx0, dy0, dx1, dy1, ...]` in canvas px (y down), before the offsets
+     *  were rounded. */
+    wanted: number[][];
+    /** The end keys the bake wrote at the parameter's range ends, ascending,
+     *  each with the displacement it was solved for (`wanted` as above): its
+     *  side's outermost stop's. A side with no stop, or whose outermost stop is
+     *  at the end, has none. */
+    ends: {
+        value: number;
+        wanted: number[];
+    }[];
+}
+/** A `bakes` input that is malformed or misses the model. Its message starts
+ *  with the path of the field (`bakes.targets[2].stops["30"][7]`,
+ *  `bakes.meshes.tail_R.rows[0]`). */
+declare class BakeError extends Error {
+    constructor(message: string);
+}
 interface HeadEdges {
     left: {
         role: string;
@@ -1076,6 +1216,17 @@ interface GenerateOptions {
     /** Displacements added to the generated rig's stops (`RigPatch`), replayed
      *  on every rig; a refused op throws `PatchError` and rigs nothing. */
     patches?: RigPatch[];
+    /** Parts the auto-rigger has no role for, put in the model unrigged: drawn
+     *  from their own layers, hung on the head. Every entry is checked first
+     *  (`CustomPartError`). */
+    customParts?: CustomPart[];
+    /** Lattices that move the custom parts when a parameter does (`RigBakes`):
+     *  written as warps on the parts, after the patches. A refused input throws
+     *  `BakeError` and rigs nothing. */
+    bakes?: RigBakes;
+    /** What `bakes` asked of each custom part and parameter — called only when
+     *  `bakes` is given, and only for a model that validates. */
+    onBakesApplied?: (report: BakeReport[]) => void;
     /** What each of `patches` moved, in order — called only when `patches` is
      *  given, and only for a model that validates. */
     onPatchesApplied?: (report: PatchReport[]) => void;
@@ -1130,17 +1281,17 @@ interface GenerateOptions {
  * the shoulder's +: it turns CW on the +x side, CCW on the −x side.
  */
 
-type Point = {
+type Point$1 = {
     x: number;
     y: number;
 };
 interface ArmGeometry {
     /** The shoulder pivot, model space: the deltoid cap's centre. */
-    shoulder: Point;
+    shoulder: Point$1;
     /** r_u: the upper arm's half-width under the cap, px. */
     shoulderRadius: number;
     /** The elbow pivot, model space. Its y is the seam the two meshes meet on. */
-    elbow: Point;
+    elbow: Point$1;
     /** The elbow cap's largest radius, px. */
     capRadius: number;
     /** The cap's radius on each of its `CAP_SEGMENTS + 1` rays, from the elbow
@@ -1395,6 +1546,26 @@ declare function mouthFold(role: LipRole | LipInsideRole, opening: Opening): (co
  *  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;
 
+/**
+ * The `bakes` generator input, in two steps. `parseBakes` checks the whole
+ * input before anything is applied, so a refusal changes nothing; each
+ * message starts at the path of the field (`bakes.targets[2].stops["30"][7]`).
+ * `applyBakes` then re-meshes the named parts and writes their warps, solved
+ * in closed form through the head's chain.
+ */
+
+type Point = [number, number];
+/**
+ * The largest distance, over the point set, from where `moved` puts a point
+ * to where the least-squares rigid fit of `rest` puts it: 0 for a rigid
+ * motion, the bend of anything else. The fit is a rotation and a translation,
+ * no scale and no reflection, and it minimises the summed squares, not the
+ * largest distance (so the result can exceed the minimax one). Both lists
+ * hold the same points in the same order, in one frame, so their lengths must
+ * be equal.
+ */
+declare function rigidResidual(rest: readonly Point[], moved: readonly Point[]): number;
+
 /**
  * `generateIkiFromLayerSet`: role layers in, a rigged `.iki` out.
  *
@@ -1760,10 +1931,11 @@ declare function validateDeformerReparent(deformers: IkiDeformer[], deformerId:
  * `toIkiModel()` refuses.
  *
  * Note: there is no validatePartDelete here, but NOT because parts are
- * unreferenced — `clip.masks` names parts by id. That invariant is enforced
- * closer to the edits that could break it: `DeletePart` refuses to remove a
- * part still used as a mask, and `SetPartMesh` refuses to strip the mesh off
- * one (masks must be mesh parts). No command creates or edits `clip`.
+ * unreferenced — `clip.masks` and `occlusion.by` name parts by id. That
+ * invariant is enforced closer to the edits that could break it: `DeletePart`
+ * refuses to remove a part still used as a mask or an occluder, and
+ * `SetPartMesh` refuses to strip the mesh off one (both must be mesh parts).
+ * No command creates or edits `clip` or `occlusion`.
  */
 declare function validateDeformerDelete(deformers: IkiDeformer[], parts: IkiPart[], physicsChains: IkiPhysicsChain[], deformerId: string): void;
 /**
@@ -1820,4 +1992,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 HairSideRoom, type IrisStrand, LIP_INSIDE_ROLES, LIP_ROLES, LayerGeometryError, type LayerInput, type LayerSetMeasurement, type LayerSetMeasurer, type LipInsideRole, type LipRole, type Opening, type OpeningColumn, PatchError, type PatchReport, RIG_PLAN_FIELDS, type RgbaLayer, type RigPatch, type RigPlan, RigPlanError, type RigPlanField, type RigPlanReport, SHUT_BY, 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, styleRemovedMessage, 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, BakeError, type BakeReport, type BakeTarget, CaptureGridKeyform, type CustomPart, CustomPartError, DEFAULT_TURN_TARGETS, type DeformerTransformChannel, DeleteDeformer, DeletePart, DeletePhysicsRig, type EditCommand, type EditTransformChannel, EditorDocument, type ForearmPoseGeometry, HEAD_BAND, type HairSideRoom, type IrisStrand, LIP_INSIDE_ROLES, LIP_ROLES, LayerGeometryError, type LayerInput, type LayerSetMeasurement, type LayerSetMeasurer, type LipInsideRole, type LipRole, type Opening, type OpeningColumn, PatchError, type PatchReport, RIG_PLAN_FIELDS, type RgbaLayer, type RigBakes, type RigPatch, type RigPlan, RigPlanError, type RigPlanField, type RigPlanReport, SHUT_BY, 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, rigidResidual, styleRemovedMessage, upsertGridKeyform, uvRectFor, validateDeformerDelete, validateDeformerReparent, validatePartAttach };

package/dist/index.d.ts

@@ -251,10 +251,11 @@ declare class AddDeformer implements EditCommand {
  * visually predictable.
  *
  * No `parseIkiModel` pre-check is needed: removing an element from an already-
- * valid model cannot introduce a structural violation — EXCEPT for clip-mask
- * references, the one part→part reference in the contract. `apply` refuses to
- * delete a part still used as another part's `clip.masks` entry (guard below),
- * so it can never leave a dangling mask ref that would fail `toIkiModel()`.
+ * valid model cannot introduce a structural violation — EXCEPT for the part→part
+ * references in the contract: `clip.masks` and `occlusion.by`. `apply` refuses to
+ * delete a part still used as another part's `clip.masks` or `occlusion.by`
+ * entry (guards below), so it can never leave a dangling ref that would fail
+ * `toIkiModel()`.
  *
  * Texture-reference safety (package invariant): `apply` refuses to delete a
  * part that still carries `part.texture`. Texture/atlas state is non-undoable
@@ -1052,6 +1053,145 @@ interface PatchReport {
 declare class PatchError extends Error {
     constructor(message: string);
 }
+/**
+ * A part the auto-rigger has no role for (a hairpin, a twin tail): drawn from
+ * its own canvas-sized layer, hung on the head with plain warps.
+ */
+interface CustomPart {
+    /** A plain identifier; never a role's name or a part id a role yields. */
+    id: string;
+    layer: {
+        fileName: string;
+        /** The layer's alpha box in canvas px, as `LayerInput.bbox`. */
+        bbox: {
+            x: number;
+            y: number;
+            w: number;
+            h: number;
+        };
+    };
+    /** The role whose layer the part is fixed against. */
+    anchor: string;
+    /** Where the part meets the anchor, canvas px: inside both layers' boxes. */
+    tie: [number, number];
+    /** A role of the set: the part is drawn right after that role's last part. */
+    after: string;
+    /** The matrix deformer it hangs on; only `headDeformer` (the default) is
+     *  accepted. */
+    deformer?: string;
+    /** The art does not bend (a hairpin, a ribbon): a bake that bends it more
+     *  than 0.0025 face widths at a stop is refused (`BakeError`). */
+    rigid?: boolean;
+    /** Hide the part where the parts of these roles cover it, by an amount keyed on a
+     *  parameter (`IkiPart.occlusion`). `by` lists roles of the set: the
+     *  generator writes the part ids those roles yield. The parameter is one
+     *  the model declares and not a physics output; the stops follow the
+     *  format's rules. */
+    occlusion?: {
+        by: string[];
+        parameter: string;
+        stops: {
+            value: number;
+            amount: number;
+        }[];
+    };
+}
+/** A `customParts` entry that is malformed or misses the layer set. Its
+ *  message starts `customParts[i].<field>` (`customParts` alone for a
+ *  non-array). */
+declare class CustomPartError extends Error {
+    constructor(message: string);
+}
+/**
+ * One lattice a bake spreads over the custom parts it names: `(cols + 1) x
+ * (rows + 1)` control points laid evenly over `box`, listed row-major from the
+ * top-left (the top row first, each row left to right). Every position and
+ * displacement is in canvas px, origin top-left, y DOWN.
+ *
+ * A stop is exact where the bake writes it, and so is the end key a side's
+ * outermost stop gets at the parameter's range end; between keys the motion
+ * is interpolated, and under a parent that rotates with the parameter (the
+ * head's roll) it bows off the straight line, so put a stop where the path
+ * matters. A side with no stop is not moved by this target. Targets that name the same part and
+ * parameter add.
+ */
+interface BakeTarget {
+    /** A label for reports; the rig ignores it. */
+    id?: string;
+    /** A parameter the model declares. */
+    param: string;
+    /** Custom part ids only: a bake moves nothing else. */
+    parts: string[];
+    /** Canvas px; absent, the union of the parts' rest boxes grown by 2 px. */
+    box?: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    };
+    /** Integers 1 to 32. */
+    grid: {
+        cols: number;
+        rows: number;
+    };
+    /** Keyed by a value of `param` inside its range, never its default (rest is
+     *  implicit). A stop is the part's TOTAL landed displacement from rest when
+     *  `param` alone is at that value and every other parameter is at its
+     *  default: the head's own carry is included, so a neighbour's measured
+     *  displacement at that pose is written as it is. */
+    stops: Record<string, [number, number][]>;
+    /** Fill a missing stop from the one at the value mirrored about the rest
+     *  value: the lattice reflected about the box's vertical centre line, `dx`
+     *  negated. A written stop is never overwritten. */
+    mirror?: boolean;
+    /** Why the target exists, for whoever edits the bakes next; ignored. */
+    why?: string;
+}
+/**
+ * Lattice bakes for custom parts: what moves them when the head turns or the
+ * hair sways, which an unrigged custom part otherwise does not. A bake moves
+ * custom parts only.
+ */
+interface RigBakes {
+    targets: BakeTarget[];
+    /** Re-mesh a custom part before baking: `rows` (canvas-px y, strictly
+     *  increasing, first the part's top and last its bottom within 0.5 px) with
+     *  `cols`, or `cellPx` for a uniform grid. "The box" here is the part's own
+     *  rest box (its layer's bbox), not a target's `box`. */
+    meshes?: Record<string, {
+        rows: number[];
+        cols: number;
+    } | {
+        cellPx: number;
+    }>;
+}
+/** What a bake asked of one custom part on one parameter, for a caller that
+ *  checks the landing. */
+interface BakeReport {
+    part: string;
+    param: string;
+    /** The stops written, ascending (rest, implicit, not among them). */
+    stops: number[];
+    vertexCount: number;
+    /** Per stop, in `stops` order: each vertex's wanted displacement from rest,
+     *  `[dx0, dy0, dx1, dy1, ...]` in canvas px (y down), before the offsets
+     *  were rounded. */
+    wanted: number[][];
+    /** The end keys the bake wrote at the parameter's range ends, ascending,
+     *  each with the displacement it was solved for (`wanted` as above): its
+     *  side's outermost stop's. A side with no stop, or whose outermost stop is
+     *  at the end, has none. */
+    ends: {
+        value: number;
+        wanted: number[];
+    }[];
+}
+/** A `bakes` input that is malformed or misses the model. Its message starts
+ *  with the path of the field (`bakes.targets[2].stops["30"][7]`,
+ *  `bakes.meshes.tail_R.rows[0]`). */
+declare class BakeError extends Error {
+    constructor(message: string);
+}
 interface HeadEdges {
     left: {
         role: string;
@@ -1076,6 +1216,17 @@ interface GenerateOptions {
     /** Displacements added to the generated rig's stops (`RigPatch`), replayed
      *  on every rig; a refused op throws `PatchError` and rigs nothing. */
     patches?: RigPatch[];
+    /** Parts the auto-rigger has no role for, put in the model unrigged: drawn
+     *  from their own layers, hung on the head. Every entry is checked first
+     *  (`CustomPartError`). */
+    customParts?: CustomPart[];
+    /** Lattices that move the custom parts when a parameter does (`RigBakes`):
+     *  written as warps on the parts, after the patches. A refused input throws
+     *  `BakeError` and rigs nothing. */
+    bakes?: RigBakes;
+    /** What `bakes` asked of each custom part and parameter — called only when
+     *  `bakes` is given, and only for a model that validates. */
+    onBakesApplied?: (report: BakeReport[]) => void;
     /** What each of `patches` moved, in order — called only when `patches` is
      *  given, and only for a model that validates. */
     onPatchesApplied?: (report: PatchReport[]) => void;
@@ -1130,17 +1281,17 @@ interface GenerateOptions {
  * the shoulder's +: it turns CW on the +x side, CCW on the −x side.
  */
 
-type Point = {
+type Point$1 = {
     x: number;
     y: number;
 };
 interface ArmGeometry {
     /** The shoulder pivot, model space: the deltoid cap's centre. */
-    shoulder: Point;
+    shoulder: Point$1;
     /** r_u: the upper arm's half-width under the cap, px. */
     shoulderRadius: number;
     /** The elbow pivot, model space. Its y is the seam the two meshes meet on. */
-    elbow: Point;
+    elbow: Point$1;
     /** The elbow cap's largest radius, px. */
     capRadius: number;
     /** The cap's radius on each of its `CAP_SEGMENTS + 1` rays, from the elbow
@@ -1395,6 +1546,26 @@ declare function mouthFold(role: LipRole | LipInsideRole, opening: Opening): (co
  *  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;
 
+/**
+ * The `bakes` generator input, in two steps. `parseBakes` checks the whole
+ * input before anything is applied, so a refusal changes nothing; each
+ * message starts at the path of the field (`bakes.targets[2].stops["30"][7]`).
+ * `applyBakes` then re-meshes the named parts and writes their warps, solved
+ * in closed form through the head's chain.
+ */
+
+type Point = [number, number];
+/**
+ * The largest distance, over the point set, from where `moved` puts a point
+ * to where the least-squares rigid fit of `rest` puts it: 0 for a rigid
+ * motion, the bend of anything else. The fit is a rotation and a translation,
+ * no scale and no reflection, and it minimises the summed squares, not the
+ * largest distance (so the result can exceed the minimax one). Both lists
+ * hold the same points in the same order, in one frame, so their lengths must
+ * be equal.
+ */
+declare function rigidResidual(rest: readonly Point[], moved: readonly Point[]): number;
+
 /**
  * `generateIkiFromLayerSet`: role layers in, a rigged `.iki` out.
  *
@@ -1760,10 +1931,11 @@ declare function validateDeformerReparent(deformers: IkiDeformer[], deformerId:
  * `toIkiModel()` refuses.
  *
  * Note: there is no validatePartDelete here, but NOT because parts are
- * unreferenced — `clip.masks` names parts by id. That invariant is enforced
- * closer to the edits that could break it: `DeletePart` refuses to remove a
- * part still used as a mask, and `SetPartMesh` refuses to strip the mesh off
- * one (masks must be mesh parts). No command creates or edits `clip`.
+ * unreferenced — `clip.masks` and `occlusion.by` name parts by id. That
+ * invariant is enforced closer to the edits that could break it: `DeletePart`
+ * refuses to remove a part still used as a mask or an occluder, and
+ * `SetPartMesh` refuses to strip the mesh off one (both must be mesh parts).
+ * No command creates or edits `clip` or `occlusion`.
  */
 declare function validateDeformerDelete(deformers: IkiDeformer[], parts: IkiPart[], physicsChains: IkiPhysicsChain[], deformerId: string): void;
 /**
@@ -1820,4 +1992,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 HairSideRoom, type IrisStrand, LIP_INSIDE_ROLES, LIP_ROLES, LayerGeometryError, type LayerInput, type LayerSetMeasurement, type LayerSetMeasurer, type LipInsideRole, type LipRole, type Opening, type OpeningColumn, PatchError, type PatchReport, RIG_PLAN_FIELDS, type RgbaLayer, type RigPatch, type RigPlan, RigPlanError, type RigPlanField, type RigPlanReport, SHUT_BY, 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, styleRemovedMessage, 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, BakeError, type BakeReport, type BakeTarget, CaptureGridKeyform, type CustomPart, CustomPartError, DEFAULT_TURN_TARGETS, type DeformerTransformChannel, DeleteDeformer, DeletePart, DeletePhysicsRig, type EditCommand, type EditTransformChannel, EditorDocument, type ForearmPoseGeometry, HEAD_BAND, type HairSideRoom, type IrisStrand, LIP_INSIDE_ROLES, LIP_ROLES, LayerGeometryError, type LayerInput, type LayerSetMeasurement, type LayerSetMeasurer, type LipInsideRole, type LipRole, type Opening, type OpeningColumn, PatchError, type PatchReport, RIG_PLAN_FIELDS, type RgbaLayer, type RigBakes, type RigPatch, type RigPlan, RigPlanError, type RigPlanField, type RigPlanReport, SHUT_BY, 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, rigidResidual, styleRemovedMessage, upsertGridKeyform, uvRectFor, validateDeformerDelete, validateDeformerReparent, validatePartAttach };