@ikijs/editor 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,916 @@
+import { IkiDeformer, IkiPart, IkiPhysics, IkiDeformerBinding, IkiMatrixDeformer, IkiBinding, IkiMesh, IkiModel, IkiWarpDeformer, IkiTexture, IkiUvRect, IkiTransform, IkiDeformerTransform, IkiTransformChannel, IkiGridKeyform, IkiPhysicsChain } from '@ikijs/format';
+
+/**
+ * One invertible edit. The document is passed IN at apply/invert time — a
+ * command is constructed from `(partId, value)` alone, before any document
+ * exists — so the same command object can be applied, inverted, and re-applied
+ * by the undo/redo stack.
+ *
+ * Prior-value capture happens exactly ONCE, on the first {@link apply}. `redo`
+ * (a second `apply`) reuses that captured value rather than re-reading the
+ * current field, so undo always restores the original target.
+ */
+interface EditCommand {
+    apply(doc: EditorDocument): void;
+    invert(doc: EditorDocument): void;
+    readonly label: string;
+}
+/** Channels of {@link IkiTransform} this editor can edit (object-field names,
+ *  NOT the binding `IkiTransformChannel` vocabulary). */
+type EditTransformChannel = "x" | "y" | "rotation" | "scaleX" | "scaleY" | "opacity";
+/**
+ * Generic single-field command: reads/writes one field of the resolved part via
+ * a getter/setter closure, capturing the prior value on the first `apply` and
+ * restoring it on `invert`. `T` is the captured value's type; for cloned values
+ * (the color tuple) the getter/setter perform the copy.
+ */
+declare class FieldCommand<T> implements EditCommand {
+    private readonly partId;
+    private readonly newValue;
+    private readonly get;
+    private readonly set;
+    readonly label: string;
+    private captured;
+    private prevValue;
+    constructor(partId: string, newValue: T, label: string, get: (part: IkiPart) => T, set: (part: IkiPart, value: T) => void);
+    apply(doc: EditorDocument): void;
+    invert(doc: EditorDocument): void;
+}
+/** Edit a part's RGBA fill. The 4-tuple is mutable, so the command clones on
+ *  construction (caller's array), on capture (part's current color), and on
+ *  assign (writing to the part) — it never retains the caller's or model's
+ *  array by reference. */
+declare class SetPartColor extends FieldCommand<[
+    number,
+    number,
+    number,
+    number
+]> {
+    constructor(partId: string, rgba: [number, number, number, number]);
+}
+/** Edit a part's width (model-space units). */
+declare class SetPartWidth extends FieldCommand<number> {
+    constructor(partId: string, value: number);
+}
+/** Edit a part's height (model-space units). */
+declare class SetPartHeight extends FieldCommand<number> {
+    constructor(partId: string, value: number);
+}
+/** Edit a part's paint order. */
+declare class SetPartOrder extends FieldCommand<number> {
+    constructor(partId: string, value: number);
+}
+/**
+ * Edit one channel of a part's base transform. `x`/`y` are required; the rest
+ * are optional and may be absent on the part. For an optional channel the
+ * command captures the raw current value INCLUDING `undefined`, and restoring
+ * `undefined` DELETES the key so undo returns the part to its original
+ * (possibly-omitted) shape. Engine defaults (rotation 0 / scale 1 / opacity 1)
+ * are NOT substituted here.
+ */
+declare class SetPartTransform extends FieldCommand<number | undefined> {
+    constructor(partId: string, channel: EditTransformChannel, value: number);
+}
+/**
+ * Capture the warp deformer's grid as one keyform at the driving parameter
+ * `value`, upserting `offsets` into `warps[0].keyforms`. The 4-tuple-style
+ * mutable `offsets` array is cloned on construction so a later caller mutation
+ * cannot corrupt apply/redo (mirrors {@link SetPartColor}).
+ *
+ * `apply` validates BEFORE mutating: the deformer must have a grid warp, the
+ * offsets length must equal `grid.points.length`, and `value` must lie within
+ * the driving parameter's declared `[min,max]` (fail fast, before
+ * `parseIkiModel` would reject it). Prior keyforms are deep-copied once on the
+ * first `apply` (capture-once like {@link FieldCommand}); `invert` restores
+ * that deep copy so re-apply after undo never aliases.
+ */
+declare class CaptureGridKeyform implements EditCommand {
+    private readonly deformerId;
+    private readonly value;
+    readonly label = "Capture grid keyform";
+    private readonly offsets;
+    private captured;
+    private prevKeyforms;
+    constructor(deformerId: string, value: number, offsets: number[]);
+    apply(doc: EditorDocument): void;
+    invert(doc: EditorDocument): void;
+}
+/**
+ * Generic single-field command targeting a matrix deformer, mirroring
+ * {@link FieldCommand} but resolving via `doc.findMatrixDeformer` instead of
+ * `doc.findPart`. Capture-once on first `apply`; restore on `invert`.
+ */
+declare class DeformerFieldCommand<T> implements EditCommand {
+    private readonly deformerId;
+    private readonly newValue;
+    private readonly get;
+    private readonly set;
+    readonly label: string;
+    private captured;
+    private prevValue;
+    constructor(deformerId: string, newValue: T, label: string, get: (deformer: IkiMatrixDeformer) => T, set: (deformer: IkiMatrixDeformer, value: T) => void);
+    apply(doc: EditorDocument): void;
+    invert(doc: EditorDocument): void;
+}
+/** Edit a matrix deformer's pivot x. */
+declare class SetDeformerPivotX extends DeformerFieldCommand<number> {
+    constructor(deformerId: string, value: number);
+}
+/** Edit a matrix deformer's pivot y. */
+declare class SetDeformerPivotY extends DeformerFieldCommand<number> {
+    constructor(deformerId: string, value: number);
+}
+/**
+ * Set a matrix deformer's pivot x and y atomically (one drag = one undo step).
+ * {@link SetDeformerPivotX} and {@link SetDeformerPivotY} remain for the
+ * Inspector's single-axis number inputs.
+ */
+declare class SetDeformerPivot implements EditCommand {
+    private readonly deformerId;
+    readonly label = "Set pivot";
+    private captured;
+    private prevPivot;
+    private readonly pivot;
+    constructor(deformerId: string, pivot: {
+        x: number;
+        y: number;
+    });
+    apply(doc: EditorDocument): void;
+    invert(doc: EditorDocument): void;
+}
+/** Channels of {@link IkiDeformerTransform} this editor can edit. */
+type DeformerTransformChannel = "x" | "y" | "rotation" | "scaleX" | "scaleY";
+/**
+ * Edit one channel of a matrix deformer's base transform. Because
+ * {@link IkiDeformerTransform} REQUIRES finite `x` and `y`, this command
+ * captures and restores the WHOLE prior `transform` object (present or absent)
+ * rather than a single channel, so undo can delete the transform when it did
+ * not previously exist, and redo never produces a partial object missing `x`/`y`.
+ *
+ * When no `transform` is present on the deformer, `apply` creates one from
+ * the identity base `{ x: 0, y: 0 }` — the minimal valid shape the validator
+ * accepts — then writes the edited channel. For example, editing `rotation`
+ * on a transform-less deformer yields `{ x: 0, y: 0, rotation: <value> }`.
+ */
+declare class SetDeformerTransform implements EditCommand {
+    private readonly deformerId;
+    private readonly channel;
+    private readonly value;
+    readonly label = "Set deformer transform";
+    private captured;
+    private prevTransform;
+    constructor(deformerId: string, channel: DeformerTransformChannel, value: number);
+    apply(doc: EditorDocument): void;
+    invert(doc: EditorDocument): void;
+}
+/**
+ * Replace a matrix deformer's `bindings` array wholesale. A single command
+ * covers add, edit, and remove (pass the desired final array; pass `[]` to
+ * remove all). Mirrors {@link CaptureGridKeyform}'s deep-copy discipline:
+ * clone-on-construction, capture-once, fresh deep copy on invert.
+ *
+ * Each {@link IkiDeformerBinding} is a flat object so a per-element spread
+ * `{ ...b }` is a sufficient deep copy.
+ */
+declare class SetDeformerBindings implements EditCommand {
+    private readonly deformerId;
+    readonly label = "Set deformer bindings";
+    private readonly bindings;
+    private captured;
+    private prevBindings;
+    constructor(deformerId: string, bindings: IkiDeformerBinding[]);
+    apply(doc: EditorDocument): void;
+    invert(doc: EditorDocument): void;
+}
+/**
+ * Reparent a deformer (matrix or warp) under a new parent, or promote it to
+ * root (`newParentId === undefined`). Calls {@link validateDeformerReparent}
+ * FIRST so invalid reparents (cycles, warp parent, unknown id) throw before any
+ * capture or mutation — a throwing apply leaves the model and undo stack
+ * untouched.
+ *
+ * Absent-vs-present distinction: captures both the prior `parent` value AND
+ * whether the key was present on the object, so `invert` can delete the key
+ * (restore "absent") rather than blindly assigning `undefined`.
+ */
+declare class SetDeformerParent implements EditCommand {
+    private readonly deformerId;
+    private readonly newParentId;
+    readonly label = "Set deformer parent";
+    private captured;
+    private prevParent;
+    private prevHadParent;
+    constructor(deformerId: string, newParentId: string | undefined);
+    apply(doc: EditorDocument): void;
+    invert(doc: EditorDocument): void;
+}
+/**
+ * Add a new part to the model. Validates the candidate model with
+ * {@link parseIkiModel} BEFORE mutating, so a structurally invalid part
+ * (bad color tuple, missing required fields, id collision with a deformer)
+ * throws an `IkiFormatError` and leaves the model untouched.
+ *
+ * Captures the prior base-UV entry for the part's id on the FIRST apply so
+ * invert can restore the exact pre-add state. This guards the id-reuse hazard:
+ * DeletePart(X) → AddPart(X′, different mesh) → undo(add) → undo(delete) —
+ * without restore, X's constructor-captured base would be gone, causing
+ * applyAtlas to fail when X is restored by the undo of the delete.
+ */
+declare class AddPart implements EditCommand {
+    readonly label = "Add part";
+    private readonly part;
+    private captured;
+    private prevBaseMeshUvs;
+    constructor(part: IkiPart);
+    apply(doc: EditorDocument): void;
+    invert(doc: EditorDocument): void;
+}
+/**
+ * Add a new deformer (matrix or warp) to the model. Validates the candidate
+ * model with {@link parseIkiModel} BEFORE mutating — this enforces the warp
+ * rest-grid invariant, points length, pivot, parent, and bindings without
+ * hand-rolling partial checks. Mirrors {@link AddPart} but also tracks whether
+ * `model.deformers` was absent before the first apply, so `invert` can restore
+ * the exact key-absence state (mirrors {@link SetDeformerBindings}).
+ */
+declare class AddDeformer implements EditCommand {
+    readonly label = "Add deformer";
+    private readonly deformer;
+    private captured;
+    private prevDeformersAbsent;
+    constructor(deformer: IkiDeformer);
+    apply(doc: EditorDocument): void;
+    invert(doc: EditorDocument): void;
+}
+/**
+ * Delete a part by id, preserving its original array slot so `invert` restores
+ * it at the same position. Slot position is cosmetic (the renderer uses the
+ * `order` field for paint ordering), but restoring the index keeps undo
+ * 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()`.
+ *
+ * Texture-reference safety (package invariant): `apply` refuses to delete a
+ * part that still carries `part.texture`. Texture/atlas state is non-undoable
+ * per the 5b boundary; clear the texture first via
+ * {@link EditorDocument.clearPartTextureRef} (model-committed) or
+ * {@link EditorDocument.applyAtlas} with no assignment (imported) — both are
+ * non-undoable. By the time a part is deletable it carries no texture, so
+ * `invert` can never restore a stale texture index that would render the wrong
+ * atlas region after a later atlas repack. No transactional atlas capture is
+ * needed in this command.
+ */
+declare class DeletePart implements EditCommand {
+    private readonly partId;
+    readonly label = "Delete part";
+    private captured;
+    private removed;
+    private index;
+    constructor(partId: string);
+    apply(doc: EditorDocument): void;
+    invert(doc: EditorDocument): void;
+}
+/**
+ * Delete a deformer by id. Calls {@link validateDeformerDelete} FIRST so the
+ * delete is refused while anything still references it — a child deformer, an
+ * attached part, or a physics chain anchored to it — enforcing the same
+ * referential safety as {@link SetDeformerParent} and {@link SetPartDeformer}.
+ *
+ * `invert` re-inserts the deformer at its original index.
+ */
+declare class DeleteDeformer implements EditCommand {
+    private readonly deformerId;
+    readonly label = "Delete deformer";
+    private captured;
+    private removed;
+    private index;
+    constructor(deformerId: string);
+    apply(doc: EditorDocument): void;
+    invert(doc: EditorDocument): void;
+}
+/**
+ * Replace a part's `bindings` array wholesale. A single command covers add,
+ * edit, and remove (pass the desired final array; pass `[]` to remove all).
+ * Mirrors {@link SetDeformerBindings}'s deep-copy and absent-vs-empty discipline:
+ * clone-on-construction, capture-once, fresh deep copy on every assign/invert.
+ *
+ * Each {@link IkiBinding} is a flat object, so a per-element spread `{ ...b }`
+ * is a sufficient deep copy.
+ *
+ * Validates the WRITTEN bindings against the declared parameters via a narrow
+ * synthetic {@link parseIkiModel} candidate (so unrelated in-flight invalid
+ * editor state — e.g. a NaN width on another part — cannot false-reject a
+ * binding edit). Validation runs BEFORE any mutation; on failure the model and
+ * undo stack are left untouched.
+ *
+ * Empty bindings → omit the `bindings` key on the candidate AND delete
+ * `part.bindings` on apply (keeps the model shape minimal; represents "no
+ * bindings" as an absent key rather than an empty array).
+ */
+declare class SetPartBindings implements EditCommand {
+    private readonly partId;
+    readonly label = "Set part bindings";
+    private readonly bindings;
+    private captured;
+    private prevBindings;
+    constructor(partId: string, bindings: IkiBinding[]);
+    apply(doc: EditorDocument): void;
+    invert(doc: EditorDocument): void;
+}
+/**
+ * Attach a part to a deformer, or detach it (`newDeformerId === undefined`).
+ * Calls {@link validatePartAttach} FIRST so invalid attachments (warp without
+ * mesh, unknown ids) throw before any capture or mutation.
+ *
+ * Absent-vs-present distinction mirrors {@link SetDeformerParent}: captures
+ * both the prior `deformer` value and whether the key was present, so `invert`
+ * can delete the key rather than assigning `undefined`.
+ */
+declare class SetPartDeformer implements EditCommand {
+    private readonly partId;
+    private readonly newDeformerId;
+    readonly label = "Set part deformer";
+    private captured;
+    private prevDeformer;
+    private prevHadDeformer;
+    constructor(partId: string, newDeformerId: string | undefined);
+    apply(doc: EditorDocument): void;
+    invert(doc: EditorDocument): void;
+}
+/**
+ * Add, regenerate, or remove the triangle mesh on a part.
+ *
+ * - `mesh !== undefined` → add or replace the mesh, registering the
+ *   unit-square base UVs in the side-table so {@link EditorDocument.applyAtlas}
+ *   can remap them later.
+ * - `mesh === undefined` → delete `part.mesh` and remove the side-table entry.
+ *
+ * Fails fast (BEFORE any mutation) on warp-topology violations:
+ *   - REMOVE while `part.warps` is present (even empty) or the part is
+ *     attached to a warp deformer — the format rejects any `warps` key once
+ *     the mesh is gone.
+ *   - ADD/REPLACE while `part.warps` has authored offsets (`length > 0`) —
+ *     regenerating the mesh invalidates offset positions silently; the user
+ *     must remove the warps first.
+ *
+ * The remove guard checks PRESENCE of `part.warps` (not length) while the
+ * add/replace guard checks LENGTH > 0. This asymmetry is intentional: the
+ * format allows `warps: []` only when a mesh exists, so any present key
+ * (even empty) would become invalid after mesh removal; but replacing a mesh
+ * under an empty `warps: []` is harmless because there are no authored offsets.
+ */
+declare class SetPartMesh implements EditCommand {
+    private readonly partId;
+    readonly label = "Set part mesh";
+    private readonly mesh;
+    private captured;
+    private prevHadMesh;
+    private prevMesh;
+    private prevBaseMeshUvs;
+    constructor(partId: string, mesh: IkiMesh | undefined);
+    apply(doc: EditorDocument): void;
+    invert(doc: EditorDocument): void;
+}
+/**
+ * Add a physics rig to `model.physics`. Mirrors {@link AddDeformer}: clone on
+ * construction, cheap friendly duplicate-id pre-check, full synthetic-candidate
+ * validation before mutating, capture the absent-vs-present `physics` state once,
+ * and on invert delete the key when the array empties back to its prior absence.
+ */
+declare class AddPhysicsRig implements EditCommand {
+    readonly label = "Add physics rig";
+    private readonly rig;
+    private captured;
+    private prevPhysicsAbsent;
+    constructor(rig: IkiPhysics);
+    apply(doc: EditorDocument): void;
+    invert(doc: EditorDocument): void;
+}
+/**
+ * Delete a physics rig by id. Mirrors {@link DeleteDeformer}: resolve/validate
+ * first, capture the removed rig + its index once, splice. Removing the LAST rig
+ * deletes the `physics` key to keep the exported shape minimal; invert re-inserts
+ * at the original index (recreating the array if it was deleted).
+ */
+declare class DeletePhysicsRig implements EditCommand {
+    private readonly rigId;
+    readonly label = "Delete physics rig";
+    private captured;
+    private removed;
+    private index;
+    constructor(rigId: string);
+    apply(doc: EditorDocument): void;
+    invert(doc: EditorDocument): void;
+}
+/**
+ * Replace a physics rig in place (tuning). Mirrors {@link SetDeformerBindings}
+ * but DEEP-clones the nested `input`/`output` (a shallow spread would alias them).
+ * Forbids rename (`rig.id` must equal the target `rigId`) — this command tunes a
+ * rig, never re-keys it. Validates the whole candidate (the edited rig swapped in
+ * at its index) so cross-rig rules still run, then captures the prior rig once.
+ */
+declare class SetPhysicsRig implements EditCommand {
+    private readonly rigId;
+    readonly label = "Set physics rig";
+    private readonly rig;
+    private captured;
+    private prevRig;
+    constructor(rigId: string, rig: IkiPhysics);
+    apply(doc: EditorDocument): void;
+    invert(doc: EditorDocument): void;
+}
+
+/**
+ * One part mapped to an imported atlas source. `index` is always 0 because the
+ * atlas is a single page; only the `uv` sub-rectangle varies per part.
+ */
+interface AtlasAssignment {
+    partId: string;
+    uv: IkiUvRect;
+}
+/** Input to {@link EditorDocument.applyAtlas}: the new atlas table plus the
+ *  per-part UV assignments into it. */
+interface ApplyAtlasInput {
+    textures: IkiTexture[];
+    partTextureAssignments: AtlasAssignment[];
+}
+/**
+ * In-memory editing session over a single {@link IkiModel}. The model is held
+ * directly (no superset) and mutated in place by invertible {@link EditCommand}s
+ * pushed through {@link execute}; undo/redo invert/re-apply them.
+ *
+ * The constructor `structuredClone`s the input so the caller's model is never
+ * mutated. Parts are addressed by stable `id`, never by array index.
+ */
+declare class EditorDocument {
+    private readonly model;
+    private readonly undoStack;
+    private readonly redoStack;
+    /** Editor-only session state, never serialized; keyed by stable part id. The
+     *  unmodified BASE local uvs of every mesh part, captured once at construction
+     *  so atlas remaps always derive from the original (idempotent). */
+    private readonly baseMeshUvs;
+    constructor(model: IkiModel);
+    /** Live reference to the working model — for READ access. Mutate it only
+     *  through {@link execute}/{@link undo}/{@link redo}. */
+    getModel(): IkiModel;
+    /** Resolve a part by stable id. Throws a plain `Error` (NOT an
+     *  `IkiFormatError`) with a path-qualified message if the id is unknown. */
+    findPart(id: string): IkiPart;
+    /** Resolve a warp deformer by stable id. Throws a path-qualified plain
+     *  `Error` if no deformer matches the id or the match is not a warp deformer.
+     *  READ/mutate-through accessor, consistent with {@link findPart}. */
+    findWarpDeformer(id: string): IkiWarpDeformer;
+    /** Resolve a matrix deformer by stable id. Throws a path-qualified plain
+     *  `Error` if no deformer matches the id or the match is a warp deformer
+     *  (`kind === "warp"`). A `kind` of `"matrix"` or `undefined` is a matrix
+     *  deformer. READ/mutate-through accessor, consistent with {@link findPart}. */
+    findMatrixDeformer(id: string): IkiMatrixDeformer;
+    /** Resolve any deformer (matrix or warp) by stable id. Throws a
+     *  path-qualified plain `Error` if no deformer matches the id.
+     *  READ/mutate-through accessor, consistent with {@link findPart}. */
+    findDeformer(id: string): IkiDeformer;
+    /** Resolve a physics rig by stable id. Throws a path-qualified plain `Error`
+     *  if no rig matches the id. The `physics` array is optional, so guard it.
+     *  READ/mutate-through accessor, consistent with {@link findDeformer}. */
+    findPhysicsRig(id: string): IkiPhysics;
+    /**
+     * Record the base mesh UVs for a part inserted AFTER construction (e.g. by
+     * {@link AddPart}). Returns the PRIOR entry for that id (or `undefined` if
+     * none existed) so the caller can restore it on undo. No-op for meshless
+     * parts (returns `undefined`). Must be called by any command that pushes a
+     * mesh part into the model so the part joins the constructor-captured base-UV
+     * side state required by {@link applyAtlas}.
+     *
+     * The returned prior value is what {@link restoreBaseMeshUvs} expects on
+     * undo — pass it verbatim. Hazard guarded: DeletePart(X) → AddPart(X′) →
+     * undo(add) → undo(delete); without restore, X's constructor-captured entry
+     * would be permanently gone after undo of the add, causing applyAtlas to
+     * fail when X is restored.
+     */
+    captureBaseMeshUvs(partId: string): number[] | undefined;
+    /**
+     * Restore the base-UV side state to exactly what it was before a
+     * {@link captureBaseMeshUvs} call. Called from {@link AddPart.invert}:
+     * pass the value returned by captureBaseMeshUvs on first apply.
+     * - `prev` is `number[]` → sets the entry (restores a prior mesh's base).
+     * - `prev` is `undefined` → deletes the entry (no entry existed before the
+     *   add, so a later different-mesh part reusing the id must not inherit this
+     *   one's base).
+     * DeletePart does NOT call this — the entry persists across delete/undo so
+     * the restored part still has its base available for applyAtlas.
+     */
+    restoreBaseMeshUvs(partId: string, prev: number[] | undefined): void;
+    /** The construction-captured base UVs for a mesh part. Throws a path-qualified
+     *  plain `Error` if absent. SINGLE accessor for both apply branches — never
+     *  read `baseMeshUvs` with a bare `!` elsewhere. */
+    private requireBaseUvs;
+    /**
+     * Replace the atlas table and rewrite every part's texture reference in a
+     * single atomic step. For every part in `partTextureAssignments` set
+     * `texture = { index: 0, uv }`; CLEAR `texture` (delete the key) on every
+     * other part.
+     *
+     * Mesh parts are textured as a MATCHED PAIR: an assigned mesh part also has
+     * its per-vertex `mesh.uvs` remapped (from the construction-captured base)
+     * into the same `uv` rect; an unassigned mesh part has its `mesh.uvs` restored
+     * to that base. Quad parts carry `texture.uv` only and are untouched here.
+     *
+     * Deliberately NON-undoable: it does NOT push to or clear the undo/redo
+     * stacks (texture/atlas state is not undoable in 5b — the unified
+     * editor-state superset is deferred to 5d). `canUndo()`/`canRedo()` are
+     * unchanged after a call.
+     *
+     * Validate-all-then-apply: structural input validation, per-partId
+     * resolution, and a base-UV preflight over every mesh part all run BEFORE any
+     * mutation, so a bad input (wrong shape, duplicate partId, unknown partId, or
+     * a mesh part with no captured base) throws a plain `Error` and leaves the
+     * model exactly as it was — never a partial application.
+     */
+    applyAtlas(input: ApplyAtlasInput): void;
+    /**
+     * Clear a model-committed texture reference from a single part. Deliberately
+     * NON-undoable, matching {@link applyAtlas} — texture/atlas state is not in
+     * the undo model (unified editor-state is deferred). Does NOT push to or
+     * clear the undo/redo stacks. Does NOT touch `mesh.uvs` — atlas-space UVs on
+     * an untextured mesh are inert for color rendering; a later atlas import
+     * remaps from the base UVs anyway.
+     *
+     * This is the single consistent texture/atlas undo boundary: by the time a
+     * part is deletable (no texture), its DeletePart snapshot carries no texture
+     * reference, so no stale index can resurface on undo after a later atlas
+     * repack.
+     *
+     * Throws a path-qualified plain `Error` (NOT `IkiFormatError`) if the part
+     * id is unknown — same contract as {@link findPart}.
+     */
+    clearPartTextureRef(partId: string): void;
+    /**
+     * Validate the structural shape of an {@link ApplyAtlasInput} without
+     * touching the model, returning a known-good `{ texture?, assignmentsByPart }`
+     * for {@link applyAtlas} to resolve and apply.
+     */
+    private normalizeAtlasInput;
+    /**
+     * Overwrite a part's whole transform with a fresh copy of `transform`.
+     * Replacing the whole object (rather than individual channels) preserves any
+     * optional keys already absent from the incoming value.
+     *
+     * Deliberately NON-undoable — used ONLY for an editor app's transient capture
+     * pose. Does NOT push to or clear undoStack/redoStack (sibling to
+     * {@link applyAtlas}'s non-undoable boundary). The caller is responsible for
+     * restoring the exact prior snapshot when the capture pose ends.
+     *
+     * `IkiTransform` is a flat number map, so a shallow spread is a sufficient
+     * deep copy — no aliasing of the caller's object remains.
+     */
+    setPartTransformEphemeral(partId: string, transform: IkiTransform): void;
+    /**
+     * Overwrite a matrix deformer's optional transform with a fresh copy, or
+     * delete it when `transform` is `undefined`.
+     * `undefined` deletes the key, restoring the deformer to the same state as
+     * one that never had a transform (absent-vs-present matters for downstream
+     * renderers).
+     *
+     * Deliberately NON-undoable — used ONLY for an editor app's transient capture
+     * pose. Does NOT push to or clear undoStack/redoStack (sibling to
+     * {@link applyAtlas}'s non-undoable boundary). The caller is responsible for
+     * restoring the exact prior snapshot when the capture pose ends.
+     *
+     * `IkiDeformerTransform` is a flat number map, so a shallow spread is a
+     * sufficient deep copy — no aliasing of the caller's object remains.
+     */
+    setDeformerTransformEphemeral(deformerId: string, transform: IkiDeformerTransform | undefined): void;
+    /**
+     * Overwrite a part's whole bindings array with a fresh deep copy, or delete
+     * the key when `bindings` is empty.
+     *
+     * Deliberately NON-undoable — used ONLY for an editor app's transient capture
+     * neutralization (zeroing the row being recaptured so the preview reflects
+     * base-only during posing). Does NOT push to or clear undoStack/redoStack.
+     * The caller is responsible for restoring the original bindings when the
+     * capture session ends.
+     */
+    setPartBindingsEphemeral(partId: string, bindings: IkiBinding[]): void;
+    /**
+     * Overwrite a matrix deformer's whole bindings array with a fresh deep copy,
+     * or delete the key when `bindings` is empty.
+     *
+     * Deliberately NON-undoable — used ONLY for an editor app's transient capture
+     * neutralization (zeroing the row being recaptured so the preview reflects
+     * base-only during posing). Does NOT push to or clear undoStack/redoStack.
+     * The caller is responsible for restoring the original bindings when the
+     * capture session ends.
+     */
+    setDeformerBindingsEphemeral(deformerId: string, bindings: IkiDeformerBinding[]): void;
+    /** Apply a command and record it as one undo step. Clears the redo stack. */
+    execute(cmd: EditCommand): void;
+    /** Invert the most recent command and move it onto the redo stack. */
+    undo(): void;
+    /** Re-apply the most recently undone command and move it back onto undo. */
+    redo(): void;
+    canUndo(): boolean;
+    canRedo(): boolean;
+    /**
+     * Validate and export the current working model by running it through
+     * {@link parseIkiModel}. Uses `structuredClone` so the validator's
+     * normalized output cannot alias the working model. Propagates
+     * `IkiFormatError` unchanged on failure — callers surface `.message`.
+     */
+    toIkiModel(): IkiModel;
+    /**
+     * Pretty-print the validated model as a `.iki` JSON string. Always
+     * validates first — invalid documents never reach a file.
+     */
+    serialize(): string;
+}
+
+/**
+ * Alpha bounding-box scan shared by every auto-rig ingestion path.
+ *
+ * The scan itself is environment-free — it only needs indexable RGBA bytes — so
+ * a browser editor (canvas `ImageData`) and the Node MCP server (a `sharp`
+ * raw buffer) run the SAME code instead of two copies that have to be kept
+ * byte-identical by hand. Only decoding differs between them.
+ */
+/** Alpha at or above this counts as coverage; below it is treated as empty. */
+declare const ALPHA_BBOX_THRESHOLD = 8;
+/** Top-left origin, +y down — image space, not model space. */
+interface AlphaBbox {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+/**
+ * Tight bounding box of every pixel with alpha >= {@link ALPHA_BBOX_THRESHOLD},
+ * expanded 1px on each side (clamped to the image) for AA / extrude margin.
+ *
+ * Returns `null` when no pixel passes the threshold, leaving the "empty layer"
+ * error to the caller: each ingestion path reports it with its own error type
+ * and message.
+ */
+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
+ * crypto.randomUUID.
+ *
+ * L/R = CHARACTER frame: *_L is the character's left = screen right.
+ */
+
+/**
+ * Input contract from the host app to this package's auto-rig functions.
+ * Passed in after the host has decoded PNGs, computed alpha bboxes, and
+ * mapped filenames to canonical roles.
+ */
+interface LayerInput {
+    /** Canonical role, e.g. "eye_L". */
+    role: string;
+    /** Original file name — used in error messages and as a stable id. */
+    fileName: string;
+    /** Shared canvas width (all layers have the same canvas size). */
+    canvasW: number;
+    /** Shared canvas height. */
+    canvasH: number;
+    /** Alpha-tight bounding box, top-left origin, +y down (image coords). */
+    bbox: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    };
+    /** Cropped image width = bbox.w. */
+    cropW: number;
+    /** Cropped image height = bbox.h. */
+    cropH: number;
+}
+/**
+ * Map an array of raw filenames to canonical `{ role, fileName }` pairs.
+ *
+ * Steps:
+ *   1. Normalize each filename → role (normalizeRole).
+ *   2. Eagerly check each role against ROLE_TABLE — unknown roles throw early
+ *      with the offending fileName included in the message.
+ *   3. Call assertRoleSet to check duplicates + required roles.
+ *
+ * Throws a path-qualified Error on any contract violation.
+ */
+declare function parseLayerRoles(fileNames: string[]): {
+    role: string;
+    fileName: string;
+}[];
+/**
+ * Auto-rig: given decoded layer inputs and the shared canvas size, produce a
+ * valid IkiModel ready for parseIkiModel.
+ *
+ *   - Validate all inputs before deriving anything.
+ *   - Place parts at source-derived positions (bboxToTransform, unshifted).
+ *   - Emit the standard parameters (same ids/ranges as sample-model.ts), plus a
+ *     conditional HairSwayX descriptor + hair-sway physics rig when a hair_front
+ *     layer is present.
+ *   - Build headDeformer (matrix, neck pivot, AngleX+Breath bindings) and faceWarp
+ *     (warp, 4×4, baked cylinder warp center-relative on faceCenterX).
+ *   - Mesh parts (spec.mesh===true) → width:1, height:1, pixel grid mesh 4×4 + role bindings.
+ *   - Static parts (spec.mesh===false) → width:cropW, height:cropH, no mesh.
+ *   - Part ids equal the role string (deterministic, no crypto.randomUUID).
+ *   - Return parseIkiModel(structuredClone(model)) — every caller gets a
+ *     validated model; bad assembly fails loudly.
+ */
+declare function generateIkiFromLayerSet(layers: LayerInput[], canvas: {
+    width: number;
+    height: number;
+}): IkiModel;
+
+export { ALPHA_BBOX_THRESHOLD, ATLAS_PADDING, AddDeformer, AddPart, AddPhysicsRig, type AlphaBbox, type ApplyAtlasInput, type AtlasAssignment, type AtlasLayout, type AtlasPlacement, type AtlasSource, CaptureGridKeyform, type DeformerTransformChannel, DeleteDeformer, DeletePart, DeletePhysicsRig, type EditCommand, type EditTransformChannel, EditorDocument, type LayerInput, SetDeformerBindings, SetDeformerParent, SetDeformerPivot, SetDeformerPivotX, SetDeformerPivotY, SetDeformerTransform, SetPartBindings, SetPartColor, SetPartDeformer, SetPartHeight, SetPartMesh, SetPartOrder, SetPartTransform, SetPartWidth, SetPhysicsRig, UV_INSET_PX, captureBindingEndpoint, computeGridOffsets, createDefaultMatrixDeformer, createDefaultPart, createDefaultWarpDeformer, createGridMesh, detectAlphaBbox, generateIkiFromLayerSet, interpolateGridOffsets, packAtlas, parseLayerRoles, upsertGridKeyform, uvRectFor, validateDeformerDelete, validateDeformerReparent, validatePartAttach };