@ikijs/editor 0.8.1 → 0.9.0

package/dist/index.d.ts

@@ -656,192 +656,6 @@ interface AlphaBbox {
  */
 declare function detectAlphaBbox(rgba: ArrayLike<number>, width: number, height: number): AlphaBbox | null;
 
-/**
- * Pure, binding-value logic for computing an endpoint (rest-to-posed delta or
- * ratio) when capturing a transform channel binding. No DOM, no @ikijs/engine —
- * the single home of the additive-vs-multiplicative rule, reused by both the
- * part and deformer capture paths.
- *
- * Additive channels (translateX, translateY, rotate, scaleX, scaleY) return the
- * delta: `posedValue - restValue`. The binding will multiply that delta across
- * the driven range.
- *
- * Opacity is multiplicative: returns the ratio `posedValue / restValue`. The
- * binding will multiply by that ratio across the driven range. When `restValue`
- * is 0 (a degenerate case: base opacity cannot be represented multiplicatively
- * since 0 * x ≡ 0), this returns 0 as a documented fallback — it does NOT
- * recover `posedValue` and is NOT unit-tested as an identity. The store layer
- * additionally skips an opacity capture when rest opacity is 0, surfacing an
- * editError.
- *
- * Deformer channels never include opacity (they use `IkiMatrixChannel`), so the
- * opacity branch is reached only for parts.
- *
- * Finiteness of the captured value is NOT validated here; the store's
- * `captureEndpoint` finite-value guard is the appropriate layer for that check.
- */
-declare function captureBindingEndpoint(channel: IkiTransformChannel, restValue: number, posedValue: number): number;
-
-/**
- * Pure, grid-size-agnostic keyform/offset math for authoring a warp-deformer
- * grid by dragging. No DOM, no `@ikijs/engine` — the load-bearing testable core.
- * Constraints derive only from the input array lengths, never the sample grid.
- */
-/**
- * Interpolate the grid offsets at `value`, mirroring the engine's
- * `accumulateKeyformOffsets` clamp+lerp semantics: clamp to the first/last
- * keyform (NO extrapolation) and linearly interpolate the bracketing pair.
- * Returns a NEW array of length `keyforms[0].offsets.length`. Throws on empty.
- */
-declare function interpolateGridOffsets(keyforms: {
-    value: number;
-    offsets: number[];
-}[], value: number): number[];
-/**
- * Per-control-point delta of the dragged grid from the rest grid: for each
- * point `i`, `(draggedX_i - restX_i, draggedY_i - restY_i)`. The DOM layer
- * assembles the full `restFrameDraggedPoints` (including untouched points), so
- * this is a straight subtract — no prior-offset blending.
- *
- * Both arrays must have the SAME length and that length must be even (x,y
- * pairs). Returns a NEW array of length `restPoints.length`.
- */
-declare function computeGridOffsets(restPoints: number[], restFrameDraggedPoints: number[]): number[];
-/**
- * Insert or replace the keyform at `value`, returning a NEW array. If a keyform
- * already exists with an exact-match `value`, REPLACE its offsets (with a copy);
- * otherwise INSERT `{ value, offsets: [...offsets] }` at the position that keeps
- * the array strictly ascending by value. The input array and its keyform objects
- * are never mutated, and `offsets` is copied so the result never aliases the
- * caller's array.
- *
- * Deliberately RANGE-FREE — a generic, reusable array op. Value-range
- * enforcement is the command's job, not this helper's.
- */
-declare function upsertGridKeyform(keyforms: IkiGridKeyform[], value: number, offsets: number[]): IkiGridKeyform[];
-
-declare const ATLAS_PADDING = 2;
-declare const UV_INSET_PX = 0.5;
-/** Intrinsic pixel size of one decoded image; id is an editor-only stable key. */
-interface AtlasSource {
-    id: string;
-    width: number;
-    height: number;
-}
-/** Sub-image pixel rect within the page, top-left origin, EXCLUDING the gutter. */
-interface AtlasPlacement {
-    id: string;
-    x: number;
-    y: number;
-    width: number;
-    height: number;
-}
-interface AtlasLayout {
-    pageWidth: number;
-    pageHeight: number;
-    placements: AtlasPlacement[];
-    padding: number;
-}
-/**
- * Deterministic shelf/row packer. Sources are sorted by id for stability so
- * identical inputs always produce an identical layout.
- *
- * Padding is one-sided: each placement reserves `padding` px on its RIGHT and
- * BOTTOM only. Page left/top edges need no gutter.
- *
- * pageWidth/pageHeight = tight bound (max x+width+padding, max y+height+padding).
- * Empty sources → { pageWidth: 0, pageHeight: 0, placements: [], padding }.
- * Throws a plain Error naming the offending source id on a non-finite or <= 0 dimension.
- */
-declare function packAtlas(sources: AtlasSource[], padding?: 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.
- */
-declare function uvRectFor(placement: AtlasPlacement, page: {
-    width: number;
-    height: number;
-}, insetPx?: number): IkiUvRect;
-
-/**
- * Validate that reparenting `deformerId` under `newParentId` keeps the deformer
- * hierarchy valid. Pass `newParentId === undefined` to move to root (always legal).
- * Checks: existence, self-reference, undeclared parent, kind constraint (warp
- * deformers cannot be parents), and cycle detection via the proposed edge.
- */
-declare function validateDeformerReparent(deformers: IkiDeformer[], deformerId: string, newParentId: string | undefined): void;
-/**
- * Validate that deleting `deformerId` is safe. Throws when the deformer does
- * not exist, when another deformer is parented to it (must be reparented or
- * detached first), when a part is attached to it (must be detached first), or
- * when a physics chain anchors to it (must be re-anchored or deleted first).
- *
- * Every id that can reference a deformer must be covered here: the format
- * validator rejects a dangling reference at export, so a delete this function
- * lets through does not fail now — it strands the document in a state
- * `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`.
- */
-declare function validateDeformerDelete(deformers: IkiDeformer[], parts: IkiPart[], physicsChains: IkiPhysicsChain[], deformerId: string): void;
-/**
- * Validate that attaching part `partId` to deformer `newDeformerId` is valid.
- * Pass `newDeformerId === undefined` to detach (always legal).
- * Checks: part existence, undeclared deformer, and mesh-required-for-warp.
- */
-declare function validatePartAttach(deformers: IkiDeformer[], partId: string, parts: IkiPart[], newDeformerId: string | undefined): void;
-
-/**
- * Create a minimal valid part with a collision-free id and a paint order one
- * above the current top-most part so it is immediately visible in the viewport.
- * Uses a distinct non-white blue tint so it is distinguishable from the canvas
- * background without requiring a texture.
- *
- * No optional keys (`texture`, `mesh`, `deformer`, `bindings`, `warps`) are set
- * — the format treats all of them as absent by default.
- */
-declare function createDefaultPart(model: IkiModel): IkiPart;
-/**
- * Create a minimal valid matrix deformer rooted at the canvas origin.
- * `kind` is omitted because the format treats its absence as "matrix" (the
- * default), keeping the serialised model compact.
- */
-declare function createDefaultMatrixDeformer(model: IkiModel): IkiMatrixDeformer;
-/**
- * Create a regular grid mesh in part LOCAL space (±0.5 unit frame).
- *
- * Vertices span x ∈ [-0.5, 0.5] and y ∈ [-0.5, 0.5] (+y up, engine convention).
- * Row 0 is the TOP of the grid (y = +0.5); row index increases downward.
- * UVs are unit-square base coordinates: u = col/cols (0..1 left→right),
- * v = row/rows (0..1 top→bottom). The top row maps to v=0 because v and y
- * run in opposite directions — keeps textures upright without a post-flip.
- * The UV-to-texture remap (atlas rect) is applied later in SetPartMesh, not here.
- *
- * Index winding per cell: [BL, BR, TL] then [TL, BR, TR], matching the engine's
- * implicit-quad convention (see examples/editor/src/mesh-generator.ts).
- *
- * Bounds are validated BEFORE any array allocation because this factory runs
- * before SetPartMesh's parseIkiModel — an unbounded count would freeze the
- * editor before the format-level 65536 limit is ever reached.
- */
-declare function createGridMesh(cols: number, rows: number): IkiMesh;
-/**
- * Create a 4×4-cell warp deformer whose rest grid spans a quarter of the
- * canvas in each direction (`±canvas.width/4` × `±canvas.height/4`). For the
- * 1000-unit sample canvas this gives x,y ∈ [−250, 250], which is large enough
- * to cover a typical face part without spilling to the edge.
- *
- * `warps` is omitted — the format treats its absence as "rest grid only", so
- * the deformer is immediately usable without authored keyforms.
- * `parent` is omitted — the deformer is placed at root; the caller may
- * reparent it via `SetDeformerParent` after creation.
- */
-declare function createDefaultWarpDeformer(model: IkiModel): IkiWarpDeformer;
-
 /**
  * Role table, role parsing, bbox→transform math, and model assembly for the
  * AI auto-rig generator. All pure functions — no DOM, no canvas, no
@@ -879,10 +693,10 @@ interface LayerInput {
      * The layer's painted half-width on every CROP row, top → bottom, one entry
      * per row (`cropH` of them): half the row's opaque span in canvas px under
      * the same alpha ≥ 128 rule the head's `headEdges` are measured with
-     * (`@ikijs/mcp`'s `measure-turn`), 0 for a row with no opaque pixel.
+     * (`createLayerSetMeasurer`), 0 for a row with no opaque pixel.
      * Optional, and only the FACE's is read: it gives the face plate a
      * row-dependent turn radius and a chin swing (`faceRowProfile`,
-     * `turnSurface`); absent — as the editor's own import leaves it — the plate
+     * `turnSurface`); absent — from a host that does not measure it — the plate
      * turns on one radius on every row. Validated before anything reads it: an
      * array of length `cropH` whose every entry is a finite number in
      * [0, cropW / 2], the most an inclusive span inside the crop can be.
@@ -895,8 +709,8 @@ interface LayerInput {
      * NOSE's is read: its centre and width are the nose's turn landmark
      * (`turnLandmarks`), so a shaded nose is fitted by the drawing rather than
      * by its feather, and its top edge at its centre x is the bridge top the
-     * nose tilts about on the turn (`NOSE_TURN_TILT_DEG`). Absent — as the
-     * editor's own import leaves it — the crop stands in for both. Validated
+     * nose tilts about on the turn (`NOSE_TURN_TILT_DEG`). Absent — from a
+     * host that does not measure it — the crop stands in for both. Validated
      * before anything reads it: a plain object whose x, y, w and h are finite,
      * w and h positive, and the box inside `bbox`.
      */
@@ -931,8 +745,9 @@ declare function parseLayerRoles(fileNames: string[]): {
  * gap between an iris edge and a run edge is a real distance with no margin to
  * add. "Outer" is toward the head's edge on that side. The run is the one a
  * producer judges a strand: it may skip runs it judges hair detail
- * (`@ikijs/mcp` treats those narrower than half the iris's painted width on
- * the row as clear), so an iris under only such a wisp counts as clear.
+ * (`createLayerSetMeasurer` treats those narrower than half the iris's
+ * painted width on the row as clear), so an iris under only such a wisp counts
+ * as clear.
  *
  * One shape covers three cases:
  *   - an ordinary side strand outward of a clear iris (`runFace` outward of
@@ -1180,4 +995,389 @@ declare function generateIkiFromLayerSet(layers: LayerInput[], canvas: {
     };
 }): IkiModel;
 
-export { ALPHA_BBOX_THRESHOLD, ATLAS_PADDING, AddDeformer, AddPart, AddPhysicsRig, type AlphaBbox, type ApplyAtlasInput, type AtlasAssignment, type AtlasLayout, type AtlasPlacement, type AtlasSource, CaptureGridKeyform, DEFAULT_TURN_TARGETS, type DeformerTransformChannel, DeleteDeformer, DeletePart, DeletePhysicsRig, type EditCommand, type EditTransformChannel, EditorDocument, type IrisStrand, type LayerInput, 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, captureBindingEndpoint, computeGridOffsets, createDefaultMatrixDeformer, createDefaultPart, createDefaultWarpDeformer, createGridMesh, detectAlphaBbox, generateIkiFromLayerSet, interpolateGridOffsets, packAtlas, parseLayerRoles, upsertGridKeyform, uvRectFor, validateDeformerDelete, validateDeformerReparent, validatePartAttach };
+/**
+ * The alpha rules a layer set is measured by, and the pre-rig measurement of
+ * that set, in one DOM-free copy — the way `detectAlphaBbox` is one.
+ *
+ * Both auto-rig hosts — the editor app (canvas `getImageData`) and
+ * `@ikijs/mcp`'s `auto_rig_from_layers` (a `sharp` raw buffer) — hand
+ * `createLayerSetMeasurer` the RGBA they decoded and rig what it measures, and
+ * `@ikijs/mcp`'s other tools (`measure_turn_reference`, `measure_layers`, the
+ * composer) read the same rules. Two copies would have to be kept identical by
+ * hand, or the head a render measures back, or the nose core the composer
+ * placed, would part from the one the rig was fitted to. Only decoding differs
+ * between the hosts.
+ */
+
+/** Half-height of the row band the head span is taken over, in px. Fixed at
+ *  ±10 rows rather than scaled to the image, and that is the convention: any
+ *  other measurement of head width meant to be compared with the one
+ *  `@ikijs/mcp`'s `measure_turn_reference` takes off a render — one taken off
+ *  layer alpha, a hand script — has to span the same band. Shared by that tool
+ *  and `createLayerSetMeasurer`, so the head it spans off the layers' alpha
+ *  union spans this band too. */
+declare const HEAD_BAND = 10;
+/** Alpha at or above this is opaque. Shared by `@ikijs/mcp`'s
+ *  `measure_turn_reference`, whose "alpha" foreground rule reads an engine
+ *  render's silhouette by it, and by the layer-alpha silhouette
+ *  `createLayerSetMeasurer` measures the head on, which has to follow that
+ *  rule to be comparable with a render. */
+declare const ALPHA_OPAQUE = 128;
+/**
+ * A layer's dense core: the tight box of its pixels at alpha ≥ ALPHA_OPAQUE,
+ * not grown. A soft-alpha part (a nose drawn as a shaded bump) is mostly
+ * feather, and the core is the drawing a viewer reads inside it — `@ikijs/mcp`'s
+ * composer sizes and places the nose by it, and `createLayerSetMeasurer` reads
+ * the same core as the nose's `LayerInput.denseCore`, its turn landmark. It is
+ * not the crop: that stays the alpha ≥ 8 box grown by 1 px (`detectAlphaBbox`).
+ * `null` when no pixel reaches the threshold, a part painted wholly
+ * translucent. A core that is a speck of its part (`isSpeckCore`) is not the
+ * drawing either, and both readers fall back to the whole part, as they do for
+ * `null`.
+ */
+declare function denseCoreOf(rgba: ArrayLike<number>, width: number, height: number): {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+} | null;
+/**
+ * The fraction of its part's width, or of its height, under which a dense core
+ * is a speck (`isSpeckCore`). Measured core/part ratios, width / height: the
+ * hero's composed nose 0.72 / 0.76 (core 39×63 in a 54×83 crop), three
+ * generated shaded-bump noses (the plugin's 0.11 nose prompt) 0.75–0.85 /
+ * 0.79–0.91, `@ikijs/mcp`'s `writeSoftNose` test fixture 0.56 / 0.63 and its
+ * `writeSoftNoseLayers` 0.40 / 0.40, a nostril mark ≤ 0.1. So the line sits at
+ * least 1.6× under every real nose and fixture, and 2.5× over a speck. At the
+ * line, sizing by the core would scale the whole part to 4× its layout width,
+ * the largest blow-up `@ikijs/mcp`'s composer still accepts.
+ */
+declare const SPECK_CORE_FRACTION = 0.25;
+/**
+ * Whether a dense core is a speck of its part: narrower than
+ * SPECK_CORE_FRACTION of the part's width, or shorter than that fraction of
+ * its height (strictly `<`). Either dimension counts, because the core does
+ * more than size a nose: its bottom row is the tip the composer places, and
+ * its top-centre the rig's tilt pivot, so a sliver misplaces the nose as
+ * surely as a speck mis-sizes it. A speck is a lone nostril mark or highlight,
+ * not the drawing, and every reader falls back to the whole part: `@ikijs/mcp`'s
+ * compose sizes and places its trimmed source part whole, and
+ * `createLayerSetMeasurer` hands the rig no core, so the crop stands in.
+ *
+ * The two apply it to different pixels — compose to the source part before
+ * resampling, the rig and `measure_layers` to the composed layer against its
+ * crop — so their verdicts can part, but only for a core within about a
+ * resampled pixel of the line, or one resampling pushes across ALPHA_OPAQUE.
+ * Compose's report carries its source verdict when that was a speck, and
+ * otherwise what the composed layer shows, so it warns of a parting either
+ * way; `measure_layers` reports the layer alone.
+ */
+declare function isSpeckCore(core: {
+    w: number;
+    h: number;
+}, part: {
+    w: number;
+    h: number;
+}): boolean;
+/**
+ * Outermost set pixels of `mask` across the row band `rowLo..rowHi` (clamped
+ * to the image) — the silhouette span at that height. An empty band returns
+ * `left > right`, which every caller has to check for.
+ *
+ * Shared by `@ikijs/mcp`'s `measure_turn_reference`, which spans a render's
+ * head with it, and `createLayerSetMeasurer`, which spans the layers' alpha
+ * union: the two heads are compared, so they have to be spanned the same way.
+ */
+declare function foregroundSpan(mask: Uint8Array, width: number, height: number, rowLo: number, rowHi: number): {
+    left: number;
+    right: number;
+};
+/**
+ * Half of a silhouette span, in px. The span is INCLUSIVE — `left` and `right`
+ * are both foreground columns — so the head is `right - left + 1` px wide.
+ * Shared by `@ikijs/mcp`'s `measure_turn_reference` and
+ * `createLayerSetMeasurer`: the two head half-widths are compared against each
+ * other, so they cannot be halved differently.
+ */
+declare function headHalfOf(span: {
+    left: number;
+    right: number;
+}): number;
+/** One decoded layer, as a host hands it to `LayerSetMeasurer.add`. */
+interface RgbaLayer {
+    /** Canonical role, e.g. "eye_L" — the host has run `parseLayerRoles` on
+     *  the set already. */
+    role: string;
+    /** Original file name: the `LayerInput`'s own, and named in errors. */
+    fileName: string;
+    /** Straight-alpha RGBA, stride 4, `canvas.width × canvas.height` pixels —
+     *  canvas `ImageData.data` or a `sharp` raw buffer alike. */
+    rgba: ArrayLike<number>;
+}
+/**
+ * Measures a layer set one decoded layer at a time, so a host holds one
+ * full-canvas RGBA buffer at once, however many layers the set has. Call
+ * `finish` once, after the last `add`: it hands back its own `layers` array,
+ * which a later `add` would change.
+ */
+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,
+     * for `hair_front`, its opaque mask 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 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 that with its own error. Throws, naming the file, when
+     * `rgba` is not `width × height × 4` long; checking the decoded dimensions
+     * is the host's job.
+     */
+    add(layer: RgbaLayer): LayerInput | null;
+    /** The set's measurement, over every layer `add` recorded. The set must be
+     *  one `parseLayerRoles` accepted; otherwise this may throw, or measure a
+     *  partial set the generator then refuses. */
+    finish(): LayerSetMeasurement;
+}
+interface LayerSetMeasurement {
+    /** Every recorded layer's `LayerInput`, in `add` order. */
+    layers: LayerInput[];
+    /** The head's half-width at the eye row, canvas px: half the opaque
+     *  (alpha ≥ ALPHA_OPAQUE) union's span over ±HEAD_BAND rows about the row
+     *  of the iris centres, or of the eye centres without irises. Absent when
+     *  the union has no span there — a layer set painted translucent below that
+     *  threshold. */
+    headHalfWidth?: number;
+    /** Whether `headHalfWidth` is wider than the face plate, and so applied;
+     *  the face plate stands in for it otherwise, as the generator's own
+     *  fallback. */
+    headHalfWidthApplied: boolean;
+    /**
+     * Ready to go into `generateIkiFromLayerSet`'s options, each key present
+     * only when measured: `turnTargets.headHalfWidth` when it is applied (merge
+     * the caller's own targets under it), `headEdges` — every layer's own
+     * opaque extent in the same eye-row band, per side, in model x — with it,
+     * and `strandEdges` whenever the set has `hair_front`, `iris_L` and `iris_R`
+     * and a side measures one (`IrisStrand`).
+     */
+    turnOptions: {
+        turnTargets?: {
+            headHalfWidth: number;
+        };
+        headEdges?: {
+            left: {
+                role: string;
+                x: number;
+            }[];
+            right: {
+                role: string;
+                x: number;
+            }[];
+        };
+        strandEdges?: {
+            left?: IrisStrand;
+            right?: IrisStrand;
+        };
+    };
+}
+/**
+ * Start measuring a layer set on a `canvas`-sized canvas: the pass a host runs
+ * between decoding its layers and `generateIkiFromLayerSet`. `add` each
+ * decoded layer, then `finish`.
+ *
+ * Throws before allocating anything when `canvas.width` or `canvas.height` is
+ * not a positive safe integer, or `width × height × 4` is not a safe integer.
+ * How large a canvas to accept at all is each host's own limit.
+ */
+declare function createLayerSetMeasurer(canvas: {
+    width: number;
+    height: number;
+}): LayerSetMeasurer;
+
+/**
+ * Pure, binding-value logic for computing an endpoint (rest-to-posed delta or
+ * ratio) when capturing a transform channel binding. No DOM, no @ikijs/engine —
+ * the single home of the additive-vs-multiplicative rule, reused by both the
+ * part and deformer capture paths.
+ *
+ * Additive channels (translateX, translateY, rotate, scaleX, scaleY) return the
+ * delta: `posedValue - restValue`. The binding will multiply that delta across
+ * the driven range.
+ *
+ * Opacity is multiplicative: returns the ratio `posedValue / restValue`. The
+ * binding will multiply by that ratio across the driven range. When `restValue`
+ * is 0 (a degenerate case: base opacity cannot be represented multiplicatively
+ * since 0 * x ≡ 0), this returns 0 as a documented fallback — it does NOT
+ * recover `posedValue` and is NOT unit-tested as an identity. The store layer
+ * additionally skips an opacity capture when rest opacity is 0, surfacing an
+ * editError.
+ *
+ * Deformer channels never include opacity (they use `IkiMatrixChannel`), so the
+ * opacity branch is reached only for parts.
+ *
+ * Finiteness of the captured value is NOT validated here; the store's
+ * `captureEndpoint` finite-value guard is the appropriate layer for that check.
+ */
+declare function captureBindingEndpoint(channel: IkiTransformChannel, restValue: number, posedValue: number): number;
+
+/**
+ * Pure, grid-size-agnostic keyform/offset math for authoring a warp-deformer
+ * grid by dragging. No DOM, no `@ikijs/engine` — the load-bearing testable core.
+ * Constraints derive only from the input array lengths, never the sample grid.
+ */
+/**
+ * Interpolate the grid offsets at `value`, mirroring the engine's
+ * `accumulateKeyformOffsets` clamp+lerp semantics: clamp to the first/last
+ * keyform (NO extrapolation) and linearly interpolate the bracketing pair.
+ * Returns a NEW array of length `keyforms[0].offsets.length`. Throws on empty.
+ */
+declare function interpolateGridOffsets(keyforms: {
+    value: number;
+    offsets: number[];
+}[], value: number): number[];
+/**
+ * Per-control-point delta of the dragged grid from the rest grid: for each
+ * point `i`, `(draggedX_i - restX_i, draggedY_i - restY_i)`. The DOM layer
+ * assembles the full `restFrameDraggedPoints` (including untouched points), so
+ * this is a straight subtract — no prior-offset blending.
+ *
+ * Both arrays must have the SAME length and that length must be even (x,y
+ * pairs). Returns a NEW array of length `restPoints.length`.
+ */
+declare function computeGridOffsets(restPoints: number[], restFrameDraggedPoints: number[]): number[];
+/**
+ * Insert or replace the keyform at `value`, returning a NEW array. If a keyform
+ * already exists with an exact-match `value`, REPLACE its offsets (with a copy);
+ * otherwise INSERT `{ value, offsets: [...offsets] }` at the position that keeps
+ * the array strictly ascending by value. The input array and its keyform objects
+ * are never mutated, and `offsets` is copied so the result never aliases the
+ * caller's array.
+ *
+ * Deliberately RANGE-FREE — a generic, reusable array op. Value-range
+ * enforcement is the command's job, not this helper's.
+ */
+declare function upsertGridKeyform(keyforms: IkiGridKeyform[], value: number, offsets: number[]): IkiGridKeyform[];
+
+declare const ATLAS_PADDING = 2;
+declare const UV_INSET_PX = 0.5;
+/** Intrinsic pixel size of one decoded image; id is an editor-only stable key. */
+interface AtlasSource {
+    id: string;
+    width: number;
+    height: number;
+}
+/** Sub-image pixel rect within the page, top-left origin, EXCLUDING the gutter. */
+interface AtlasPlacement {
+    id: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+interface AtlasLayout {
+    pageWidth: number;
+    pageHeight: number;
+    placements: AtlasPlacement[];
+    padding: number;
+}
+/**
+ * Deterministic shelf/row packer. Sources are sorted by id for stability so
+ * identical inputs always produce an identical layout.
+ *
+ * Padding is one-sided: each placement reserves `padding` px on its RIGHT and
+ * BOTTOM only. Page left/top edges need no gutter.
+ *
+ * pageWidth/pageHeight = tight bound (max x+width+padding, max y+height+padding).
+ * Empty sources → { pageWidth: 0, pageHeight: 0, placements: [], padding }.
+ * Throws a plain Error naming the offending source id on a non-finite or <= 0 dimension.
+ */
+declare function packAtlas(sources: AtlasSource[], padding?: 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.
+ */
+declare function uvRectFor(placement: AtlasPlacement, page: {
+    width: number;
+    height: number;
+}, insetPx?: number): IkiUvRect;
+
+/**
+ * Validate that reparenting `deformerId` under `newParentId` keeps the deformer
+ * hierarchy valid. Pass `newParentId === undefined` to move to root (always legal).
+ * Checks: existence, self-reference, undeclared parent, kind constraint (warp
+ * deformers cannot be parents), and cycle detection via the proposed edge.
+ */
+declare function validateDeformerReparent(deformers: IkiDeformer[], deformerId: string, newParentId: string | undefined): void;
+/**
+ * Validate that deleting `deformerId` is safe. Throws when the deformer does
+ * not exist, when another deformer is parented to it (must be reparented or
+ * detached first), when a part is attached to it (must be detached first), or
+ * when a physics chain anchors to it (must be re-anchored or deleted first).
+ *
+ * Every id that can reference a deformer must be covered here: the format
+ * validator rejects a dangling reference at export, so a delete this function
+ * lets through does not fail now — it strands the document in a state
+ * `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`.
+ */
+declare function validateDeformerDelete(deformers: IkiDeformer[], parts: IkiPart[], physicsChains: IkiPhysicsChain[], deformerId: string): void;
+/**
+ * Validate that attaching part `partId` to deformer `newDeformerId` is valid.
+ * Pass `newDeformerId === undefined` to detach (always legal).
+ * Checks: part existence, undeclared deformer, and mesh-required-for-warp.
+ */
+declare function validatePartAttach(deformers: IkiDeformer[], partId: string, parts: IkiPart[], newDeformerId: string | undefined): void;
+
+/**
+ * Create a minimal valid part with a collision-free id and a paint order one
+ * above the current top-most part so it is immediately visible in the viewport.
+ * Uses a distinct non-white blue tint so it is distinguishable from the canvas
+ * background without requiring a texture.
+ *
+ * No optional keys (`texture`, `mesh`, `deformer`, `bindings`, `warps`) are set
+ * — the format treats all of them as absent by default.
+ */
+declare function createDefaultPart(model: IkiModel): IkiPart;
+/**
+ * Create a minimal valid matrix deformer rooted at the canvas origin.
+ * `kind` is omitted because the format treats its absence as "matrix" (the
+ * default), keeping the serialised model compact.
+ */
+declare function createDefaultMatrixDeformer(model: IkiModel): IkiMatrixDeformer;
+/**
+ * Create a regular grid mesh in part LOCAL space (±0.5 unit frame).
+ *
+ * Vertices span x ∈ [-0.5, 0.5] and y ∈ [-0.5, 0.5] (+y up, engine convention).
+ * Row 0 is the TOP of the grid (y = +0.5); row index increases downward.
+ * UVs are unit-square base coordinates: u = col/cols (0..1 left→right),
+ * v = row/rows (0..1 top→bottom). The top row maps to v=0 because v and y
+ * run in opposite directions — keeps textures upright without a post-flip.
+ * The UV-to-texture remap (atlas rect) is applied later in SetPartMesh, not here.
+ *
+ * Index winding per cell: [BL, BR, TL] then [TL, BR, TR], matching the engine's
+ * implicit-quad convention (see examples/editor/src/mesh-generator.ts).
+ *
+ * Bounds are validated BEFORE any array allocation because this factory runs
+ * before SetPartMesh's parseIkiModel — an unbounded count would freeze the
+ * editor before the format-level 65536 limit is ever reached.
+ */
+declare function createGridMesh(cols: number, rows: number): IkiMesh;
+/**
+ * Create a 4×4-cell warp deformer whose rest grid spans a quarter of the
+ * canvas in each direction (`±canvas.width/4` × `±canvas.height/4`). For the
+ * 1000-unit sample canvas this gives x,y ∈ [−250, 250], which is large enough
+ * to cover a typical face part without spilling to the edge.
+ *
+ * `warps` is omitted — the format treats its absence as "rest grid only", so
+ * the deformer is immediately usable without authored keyforms.
+ * `parent` is omitted — the deformer is placed at root; the caller may
+ * reparent it via `SetDeformerParent` after creation.
+ */
+declare function createDefaultWarpDeformer(model: IkiModel): IkiWarpDeformer;
+
+export { ALPHA_BBOX_THRESHOLD, ALPHA_OPAQUE, ATLAS_PADDING, AddDeformer, AddPart, AddPhysicsRig, type AlphaBbox, type ApplyAtlasInput, 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, type LayerInput, type LayerSetMeasurement, type LayerSetMeasurer, type RgbaLayer, 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, captureBindingEndpoint, computeGridOffsets, createDefaultMatrixDeformer, createDefaultPart, createDefaultWarpDeformer, createGridMesh, createLayerSetMeasurer, denseCoreOf, detectAlphaBbox, foregroundSpan, generateIkiFromLayerSet, headHalfOf, interpolateGridOffsets, isSpeckCore, packAtlas, parseLayerRoles, upsertGridKeyform, uvRectFor, validateDeformerDelete, validateDeformerReparent, validatePartAttach };