@hatiolab/figure-model 0.5.0 → 0.5.1

package/dist/authoring-types.d.ts

@@ -0,0 +1,753 @@
+import type { FigureCavityRequest, FigureSectionRequest } from './shape-edit.ts';
+import type { SlotLayout } from './slot-layout.ts';
+import type { Axis, DetailLevel } from './words.ts';
+import type { FigurePlacement } from './asset-types.ts';
+/** The six faces of a box-shaped part, and the axis each one faces along. */
+export declare const FIGURE_FACES: {
+    readonly left: "x";
+    readonly right: "x";
+    readonly bottom: "y";
+    readonly top: "y";
+    readonly back: "z";
+    readonly front: "z";
+};
+export type FigureFace = keyof typeof FIGURE_FACES;
+/**
+ * The face a part is fastened by: one of its six, or `centre` -- its own middle, which every shape has (ADR-0093,
+ * 2026-09-26). Fastened by its centre, the part's middle is on the target's face (plus the gap), and a turn there
+ * turns it about its middle: a roller spinning in place.
+ */
+export type FigureChildFace = FigureFace | 'centre';
+/**
+ * UsdPhysics's joint types (ADR-0093, amended 2026-09-25: the joint follows USD). A `fixed` joint is a fastening; a
+ * `revolute` joint turns -- with no limits it turns without end, its value a phase (-180..180), as USD's revolute
+ * joint without limits does; a `prismatic` joint slides.
+ */
+export declare const FIGURE_JOINT_TYPES: readonly ["fixed", "revolute", "prismatic"];
+export type FigureJointType = (typeof FIGURE_JOINT_TYPES)[number];
+/** UsdPhysics's axis tokens. */
+export type FigureJointAxis = 'X' | 'Y' | 'Z';
+/**
+ * A joint, in UsdPhysics's words (ADR-0093): `body0` is what it hangs from -- a part's face, or the plane the figure is
+ * mounted on -- and `body1` the part it carries, by one of its faces. The joint frame is on body0's face (USD's
+ * `localPos0`), body1's face lies in it (`localPos1`); a moving joint turns about or slides along `axis` there.
+ * Angles are degrees and lengths millimetres, as in a USD stage with `metersPerUnit = 0.001`. The rest pose is every
+ * joint at 0.
+ *
+ * extensions, which USD has no field for: every length may be an expression of the figure's design inputs (a
+ * joint on a link moves when the link grows); the faces are named features; `mimic` (URDF's, and PhysX's and Newton's
+ * extensions); `travel`, a slide whose length follows a part's size.
+ */
+export interface FigureJoint {
+    id: string;
+    type: FigureJointType;
+    body0: {
+        part: string;
+        face: FigureFace;
+    } | {
+        plane: 'mounting-plane';
+    };
+    body1: {
+        part: string;
+        face: FigureChildFace;
+    };
+    /** Where on body0's face, and how body1 stands in the joint frame (quarter turns only, in degrees). */
+    origin?: {
+        facing?: 'meet' | 'flush';
+        gap?: FigureMeasure;
+        align?: Partial<Record<Axis, FigureFaceAlignment>>;
+        turn?: Partial<Record<Axis, number>>;
+        /**
+         * Degrees about the normal of the face the child is fastened by (r3 §6's twist): the faces still meet, so any
+         * angle holds -- a fan's blades at 120°, a spoke at 45°. `turn` stays quarter turns. Twisted, the child's place
+         * across the face is measured from the face's centre in the twisted frame: a blade `align.x.mm` 200 out and
+         * twisted 120° stands 200 out along the blade, about the hub. Edges cannot be lined up with a twisted child.
+         */
+        twist?: number;
+    };
+    /** The axis a moving joint turns about or slides along, in the joint frame (USD `physics:axis`). */
+    axis?: FigureJointAxis;
+    /** USD `physics:lowerLimit` / `physics:upperLimit`: degrees for revolute, millimetres for prismatic. */
+    lowerLimit?: number;
+    upperLimit?: number;
+    /**
+     * extension: a prismatic joint whose distance follows the figure -- its value is a share (0..1 unless the limits
+     * say otherwise) of this length: a part's width, the instance's, times and plus -- or a sum of such lengths, plus.
+     */
+    travel?: FigureTravel;
+    /** The state input that is the joint's value: its id (the joint's by default), label, starting value and sweep. */
+    state?: {
+        id?: string;
+        label?: string;
+        start?: number;
+        sweep?: number;
+    };
+    /**
+     * extension (URDF's mimic): the value is the leader's times `multiplier` plus `offset`, in this joint's unit. A sum
+     * follows several leaders, each times its own multiplier (ADR-0107 decision 2): a palletizer's wrist is -(J2 + J3),
+     * so its tool stays level. A follower has no control of its own either way.
+     */
+    mimic?: FigureMimic;
+    /**
+     * extension (r3 §8, a row of copies -- USD's PointInstancer, URDF has none): the part fastened is repeated along
+     * `axis` across the parent's face, from the parent's one edge to the other. Without `count` the row fills that
+     * length, as many copies as fit at `pitch`, and so follows the parent's size; with `count`, that many spread evenly
+     * over it. Only a fastening repeats. What is fastened to the part is on every copy, and every copy moves on the part's
+     * one control (ADR-0093, 2026-09-26). A row inside a row is a grid, each along its own axis.
+     * `rise`: each copy stands `mm` further along a second axis than the one before -- a stair's steps (G2).
+     */
+    repeat?: {
+        axis: FigureJointAxis;
+        pitch: FigureMeasure;
+        count?: number;
+        rise?: {
+            axis: FigureJointAxis;
+            mm: number;
+        };
+    };
+}
+export declare const SIGN: Record<FigureFace, number>;
+/**
+ * What a dimension follows. Named rather than implied, because "as wide as the gate" and "as wide as the
+ * opening" and "as wide as the rail" are three different intentions that happen to agree at one size.
+ */
+export type FigureDimensionSource = 
+/** The instance's own size on an axis, as a board scales it. */
+{
+    of: 'instance';
+    axis: Axis;
+}
+/** A design input the author declared, such as an opening width that is not the whole figure's width. */
+ | {
+    of: 'input';
+    input: string;
+}
+/** Another part's dimension on an axis. */
+ | {
+    of: 'part';
+    part: string;
+    axis: Axis;
+};
+/**
+ * A length a command takes: a fixed number of millimetres, or something the figure already knows, so the value
+ * keeps up when the instance is resized. `{ from: ..., times, plus }` reads the same sources a dimension link
+ * does, which is why an opening can be "the instance's width" in a gap as well as in a dimension. `{ sum, plus }`
+ * adds several such terms (ADR-0107 decision 2); the one-term form is the sum of one term, written shorter.
+ */
+export type FigureMeasure = number | {
+    from: FigureDimensionSource;
+    times?: number;
+    plus?: number;
+} | {
+    sum: FigureMeasureTerm[];
+    plus?: number;
+};
+/**
+ * One term of a length that is a sum (ADR-0107 decision 2): a source times a multiple. A quadruped stands as high as
+ * its hip, thigh, shin and foot are long together. `{ from, times, plus }` is the sum of one term.
+ */
+export interface FigureMeasureTerm {
+    from: FigureDimensionSource;
+    times?: number;
+}
+/**
+ * How far a slide goes at 1 when its control is a share (0..1): a source times and plus, a sum of sources plus, or
+ * without a source just `plus` millimetres.
+ */
+export type FigureTravel = {
+    source?: FigureDimensionSource;
+    times?: number;
+    plus?: number;
+} | {
+    sum: FigureMeasureTerm[];
+    plus?: number;
+};
+/** A follower's value: one leader's times a multiplier, or the sum of several leaders' each times its own, plus `offset`. */
+export type FigureMimic = {
+    joint: string;
+    multiplier: number;
+    offset?: number;
+} | {
+    sum: Array<{
+        joint: string;
+        multiplier: number;
+    }>;
+    offset?: number;
+};
+/** The joints a follower follows, each with its multiplier: one for a one-leader mimic, none for a joint that leads itself. */
+export declare function figureMimicLeadersOf(j: {
+    mimic?: FigureMimic | unknown;
+}): Array<{
+    joint: string;
+    multiplier: number;
+}>;
+/** Whether a length is written as something to follow: one source, or a sum of one term or more, each with a source. */
+export declare const followsSomething: (measure: unknown) => boolean;
+/** A length that follows something, as its terms and its margin; undefined for a number (or nothing). */
+export declare function followedTermsOf(measure: FigureMeasure | undefined): {
+    terms: FigureMeasureTerm[];
+    plus: number;
+    sum: boolean;
+} | undefined;
+/** Where a part sits inside the face it is fastened to, on one of that face's two axes. */
+export type FigureFaceAlignment = 'centre' | 'min' | 'max' | {
+    mm: FigureMeasure;
+};
+/** A reference an edit would leave on a face it takes away, and where it goes instead (ADR-0100 A8). */
+export interface FigureFaceRemap {
+    ref: {
+        kind: 'joint' | 'feature';
+        id: string;
+    };
+    to: {
+        face: string;
+    } | 'detach';
+}
+export type FigureAuthoringAction = 
+/**
+ * "This side of this part follows that." The value becomes `source × times + plus`, as graph nodes, so it
+ * keeps following after the instance is resized; or, given `sum`, the sum of each term's source times its own
+ * multiple, plus. An axis that already follows something is refused unless `replace` says so: a link is never
+ * overwritten in passing.
+ */
+({
+    kind: 'link-dimension';
+    part: string;
+    axis: Axis;
+    plus?: number;
+    replace?: boolean;
+    /**
+     * The author's "and narrow the sizes the figure may be placed at to what it then allows": a link that takes a
+     * difference (a leaf the opening less its gaps) makes the smallest sizes impossible, and without this the
+     * link is refused -- measuring again cannot help, since the link is not there to measure. The authored size
+     * must still lie inside.
+     */
+    narrowRange?: boolean;
+} & ({
+    source: FigureDimensionSource;
+    times?: number;
+} | {
+    sum: FigureMeasureTerm[];
+}))
+/**
+ * "This part follows the figure's size." One step for what took four: when the figure has no size, it is declared
+ * from its parts as they rest (and the range folded to what the figure holds); then each named measure follows the
+ * size in the proportion it has now, so nothing moves at the drawn size. A measure that follows something else is
+ * made to follow the size instead. No axes names every measure the shape has along X, Y and Z.
+ */
+ | {
+    kind: 'follow-size';
+    part: string;
+    axes?: Axis[];
+}
+/** "Stop following; this side is this long." The explicit way back to a fixed dimension. */
+ | {
+    kind: 'unlink-dimension';
+    part: string;
+    axis: Axis;
+    mm: number;
+}
+/**
+ * "Fasten this face of this part to that face of that one."
+ *
+ * Two faces do not place a part by themselves, so the rest is named too, with defaults:
+ *   - `facing`: `meet` (the default) puts the two faces against each other, the part outside its target past
+ *     that face — a leaf under a rail. `flush` lays them in the same plane pointing the same way, the part
+ *     inside its target — a panel set level with the front of a frame.
+ *   - `gap`: millimetres between the faces along the target face's normal. 0 by default.
+ *   - `align`: where the part sits within the face, on each of the face's own two axes. `centre` by default;
+ *     `min` and `max` bring the part's own edges level with the target's, and stay level as either is
+ *     resized, because all of it is written as graph nodes.
+ *
+ * Both parts must be box-shaped and unturned: a face of a turned body is not an axis-aligned plane, and this
+ * command says nothing about rotation. A fastening that would make a part its own ancestor is refused.
+ */
+ | {
+    kind: 'attach';
+    part: string;
+    face: FigureChildFace;
+    /** The face of another part, or the plane the figure is mounted on, which is a thing a part can stand on. */
+    to: {
+        part: string;
+        face: FigureFace;
+    } | {
+        plane: 'mounting-plane';
+    };
+    facing?: 'meet' | 'flush';
+    gap?: FigureMeasure;
+    align?: Partial<Record<Axis, FigureFaceAlignment>>;
+    /** Degrees about the face's normal (the record's `origin.twist`). */
+    twist?: number;
+    replace?: boolean;
+}
+/** "This part is not fastened to anything any more." It keeps where it is now, in the asset frame. */
+ | {
+    kind: 'detach';
+    part: string;
+}
+/**
+ * "This is a joint" -- URDF's joint record, with values (ADR-0093): which face of the child sits on which face
+ * of the parent, and whether it stays fixed, turns (revolute, continuous) or slides (prismatic). The record is the
+ * canon; the joint's graph nodes are made from it. `id` names it; a record with an id already there replaces it.
+ */
+/** `narrowRange` as for `link-dimension`: a joint that rows its part makes the largest size finite. */
+ | {
+    kind: 'set-joint';
+    joint: FigureJoint;
+    narrowRange?: boolean;
+}
+/** "This joint is gone." Its child stays where it stands, fastened to nothing. */
+ | {
+    kind: 'remove-joint';
+    id: string;
+}
+/**
+ * "This is the room it takes up" — a proposal the author has looked at, confirmed as it stands. `padding` widens
+ * the room on each side of an axis by that many millimetres. It is added to the expressions read from the parts,
+ * so the room still follows when the instance is resized; a fixed number typed by hand would not (chief
+ * architect's ruling 2026-09-24). Negative padding is refused.
+ */
+ | {
+    kind: 'declare-occupancy';
+    proposal: FigureOccupancyProposal;
+    placement?: FigurePlacement;
+    padding?: Partial<Record<Axis, number>>;
+}
+/**
+ * "Author this figure from the floor, the ceiling, a wall or its centre" (ADR-0097, designer 2026-09-27). The figure's
+ * own setting, apart from its room: a new figure with no part can choose it, and nothing is made up for it -- no room,
+ * no part. A part already fastened to the mounting plane by a face the new placement does not take is refused, not
+ * fastened again quietly.
+ */
+ | {
+    kind: 'set-placement';
+    placement: FigurePlacement;
+}
+/**
+ * "This figure takes its size from the place a board gives it, within this range." Declares the instance-size
+ * inputs `size.x · size.y · size.z` a part can then follow (`link-dimension` with `of: 'instance'`). Without them
+ * a board draws the figure at its authored size whatever box it is placed in. `at` is the authored size; absent,
+ * it is what the parts take up now. The range is the author's; the command refuses only a size the figure cannot
+ * take, found by `figureInstanceSizeLimitsOf` and folded by `foldInstanceSizeRange`
+ * (chief architect's ruling 2026-09-24). `replace` changes the range of sizes already declared.
+ */
+ | {
+    kind: 'declare-instance-size';
+    range: Record<Axis, {
+        min: number;
+        max: number;
+    }>;
+    at?: Partial<Record<Axis, number>>;
+    replace?: boolean;
+}
+/** "This face is what it is mounted on." A separate choice from the room it takes up. */
+ | {
+    kind: 'set-mounting-face';
+    part: string;
+    face: FigureFace;
+}
+/** "It is not mounted on anything in particular." */
+ | {
+    kind: 'clear-mounting-face';
+}
+/**
+ * "This part stays where it is on this axis." A position worked out from other values (so a part rises with the figure's height) becomes
+ * the part's own number at its current value, as a part made in the modeller has it -- the way out when a resize
+ * leaves a part in the air. A part fastened to another is placed by that; detach it first.
+ */
+ | {
+    kind: 'fix-position';
+    part: string;
+    axis: Axis;
+}
+/**
+ * "This part keeps its place in proportion to the figure's size on this axis." Where the part is now becomes a share of the instance size (`size.<axis>`), so at twice the size it is twice as far from the
+ * origin -- the bottom for Y on a figure standing on the floor, the centre for X and Z. The instance size must be
+ * declared on that axis. A part fastened to another is placed by that; detach it first. With `link-dimension`
+ * (`times` the part's share of the size) it is the way to make a part grow with the figure instead of filling what
+ * is left: ROBOT_ARM's tool flange filled the height the arm did not use, and at twice the height it grew from
+ * 46 mm to 1,946 mm below a wrist that had moved on.
+ */
+ | {
+    kind: 'scale-position';
+    part: string;
+    axis: Axis;
+}
+/**
+ * "The whole figure grows by one ratio." Declares `sizing: 'uniform'` and feeds every reader of the instance size
+ * the size that ratio gives: u = geomean(size.x/x₀, size.y/y₀, size.z/z₀), and each axis reads u × its authored
+ * size. A jointed figure placed at twice the height then stands 1.26 times larger all round, feet on the floor, the
+ * top of its box empty -- a mechanism does not shear (chief architect's ruling 2026-09-24). Only what reads the size
+ * follows; a part's own fixed number stays fixed, and the release gate says so (`SIZING_NOT_UNIFORM`).
+ */
+ | {
+    kind: 'scale-uniformly';
+}
+/**
+ * "Every length follows the one ratio." For a figure that grows by one ratio (`scale-uniformly` first): each part's
+ * own measure, each fastening's offset and gap in millimetres, and each row's pitch become their value now over the
+ * size the figure is at now, times that size -- written as the links a person would write one by one, so any part
+ * can be given its own number again (`unlink-dimension`). A measure that already follows something is left, and
+ * named (`proposeFigureProportion`). Angles, ratios and counts are not lengths (chief architect's ruling 2026-09-25).
+ */
+ | {
+    kind: 'follow-size-in-proportion';
+}
+/** "This figure is authored to this detail": S, M, L or XL, and so its part limit (`PART_LIMIT`). `null` declares none. */
+ | {
+    kind: 'set-detail-level';
+    level: DetailLevel | null;
+}
+/**
+ * "The copies of this repeated part stand this far apart." A row that fills the length it is given takes as many copies as fit at the pitch; the pitch becomes the part's own number,
+ * `<part>.repeat.pitch`, so it is edited, dragged and undone as any other value. Its lowest value keeps the copy
+ * count within the kernel's limit at the largest size the figure takes. A row of a fixed count is refused for now:
+ * its pitch is built into its length.
+ */
+ | {
+    kind: 'set-repeat';
+    part: string;
+    pitch: number | FigureMeasure;
+}
+/**
+ * "The figure has this design value" -- a number of its own, in a unit, held to a range (ADR-0096): what a row's pitch
+ * can be read from and what a board can be given to set. The id is new; the value lies within the range.
+ */
+ | {
+    kind: 'add-design-input';
+    id: string;
+    unit: 'mm' | 'ratio' | 'deg' | 'count';
+    min: number;
+    max: number;
+    value: number;
+}
+/** "This design input is held to this range." Its value stays within it; the size inputs have declare-instance-size. */
+ | {
+    kind: 'set-input-range';
+    input: string;
+    min: number;
+    max: number;
+}
+/** "A board may set this design input per instance", shown with this name (ADR-0096). Again with a label: renamed. */
+ | {
+    kind: 'publish-input';
+    input: string;
+    label: string;
+    hint?: string;
+}
+/** "A board no longer sets this design input." */
+ | {
+    kind: 'unpublish-input';
+    input: string;
+}
+/**
+ * "Repeat this part along this axis across what it is fastened to." Copies `pitch` apart from the parent's one edge
+ * to the other, as many as fit (`count: 'fills'`, the default) or a given number spread evenly; the row follows the
+ * parent's size. The part must be fastened, keep still and hold nothing. Written into its fastening's record.
+ */
+/**
+ * A row that fills its parent holds at most REPEAT_LIMIT copies, so a figure whose size it follows has a largest size.
+ * `narrowRange` is the author's "and narrow the sizes the figure may be placed at to what it then allows", as for
+ * `link-dimension`: without it such a row is refused while the declared range reaches past it.
+ */
+ | {
+    kind: 'make-repeat';
+    part: string;
+    axis: Axis;
+    pitch: number;
+    count?: number | 'fills';
+    rise?: {
+        axis: Axis;
+        mm: number;
+    };
+    narrowRange?: boolean;
+}
+/** "This part stands once again", where its fastening puts it. */
+ | {
+    kind: 'remove-repeat';
+    part: string;
+}
+/**
+ * "Move this part by so much, turn it by so much" -- a drag on the canvas. The part keeps how its place is worked out
+ * (a place that follows the figure's size still follows it) and gets the drag added as its own
+ * number: `<part>.position.nudge.<axis>` beside a worked-out place, the part's own `<part>.position.<axis>` where it
+ * had a plain number. Turns likewise, in degrees. `grow` multiplies a measure by the drag's factor and keeps how it
+ * is worked out: `<part>.dimension.scale.<axis>` beside the measure's rule, so the part still follows the figure's
+ * size, times what the author gave it. A cylinder's X and Z are its
+ * one radius. A part carried by a joint or fastened to another is placed by that and is refused.
+ */
+ | {
+    kind: 'nudge-part';
+    part: string;
+    by?: Partial<Record<Axis, number>>;
+    turn?: Partial<Record<Axis, number>>;
+    grow?: Partial<Record<Axis, number>>;
+}
+/**
+ * "Things are held here." A seat (things rest on it) or a grip (things are held in it), on a face of a part. The
+ * place is that face as the part stands, so it follows the part through its resizes and its motion: a grip on a
+ * robot's tool moves with the arm. `accepts` names the types it takes -- the format has no "anything" (a `slot`
+ * that took anything was ambiguous; ADR-0087 decision 3). `capacity` is how many at once. `region` is the room a
+ * held thing may take, in millimetres around the place; left out, the room is not checked, not unlimited.
+ * `replace` changes a place that already has this id.
+ */
+ | {
+    kind: 'add-binding';
+    id: string;
+    label: string;
+    role: 'seat' | 'grip';
+    part: string;
+    face: FigureFace;
+    accepts: readonly string[];
+    capacity: number;
+    region?: Record<Axis, number>;
+    replace?: boolean;
+}
+/** "Nothing is held here any more." */
+ | {
+    kind: 'remove-binding';
+    id: string;
+}
+/**
+ * "Things are held in these slots" (ADR-0118): tiers and slots laid out by a rule on a horizontal face of a part. Each
+ * slot becomes a place `t{tier}_s{slot}` and must name the types it takes. The count and the ids are the author's;
+ * resizing the figure does not change them. Setting it again replaces the layout.
+ */
+ | {
+    kind: 'set-slot-layout';
+    label: string;
+    role: 'seat' | 'grip';
+    anchors: {
+        id: string;
+        part: string;
+        face: FigureFace;
+    }[];
+    layout: SlotLayout;
+}
+/** "No slot layout any more." */
+ | {
+    kind: 'remove-slot-layout';
+}
+/**
+ * "This figure is a carrier MCS calls this, this big" (ADR-0123): the CARRIERTYPE code, written as compared, and the
+ * physical size in mm. `null` declares the figure no carrier.
+ */
+ | {
+    kind: 'set-carrier';
+    carrier: {
+        type: string;
+        dimensions: {
+            width: number;
+            length: number;
+            height: number;
+        };
+    } | null;
+}
+/**
+ * "This figure is called this." The name a person reads in the catalogue — not the type a board calls it by,
+ * which lives on the row. Blank is refused, as the format refuses it; surrounding space is dropped.
+ */
+ | {
+    kind: 'rename';
+    name: string;
+}
+/**
+ * Round a pushed rectangle's corners (ADR-0100 A2): one radius for all four, or a reach per plane axis; 0 is a sharp
+ * corner again, `null` takes the rounding away. The part keeps its id, its outer size and its faces.
+ */
+ | {
+    kind: 'set-section-corner';
+    part: string;
+    corner: number | Partial<Record<Axis, number>> | null;
+    remap?: FigureFaceRemap[];
+}
+/**
+ * Give a pushed rectangle or ellipse an inside, change it, or take it away (ADR-0100 A3, A4): walls, and each end open
+ * or closed by a thickness. Refused when it takes away a face something is fastened to.
+ */
+ | {
+    kind: 'set-cavity';
+    part: string;
+    cavity: FigureCavityRequest | null;
+    remap?: FigureFaceRemap[];
+}
+/**
+ * A pushed part's section in one step (ADR-0100 §3.2): a drawn section's points, a rectangle's or an ellipse's widths
+ * across, the push's length -- each face kept where the part's relations keep it, as a size typed into its field.
+ */
+ | ({
+    kind: 'set-section';
+    part: string;
+    remap?: FigureFaceRemap[];
+} & FigureSectionRequest);
+/**
+ * What taking a part away changed besides the part (chief architect's ruling 2026-09-27, ADR-0093): nothing the author
+ * did not pick goes with it; what hung from it, moved with it or followed it is let go, and named here, and one undo
+ * brings it all back.
+ */
+export interface RemovalNotice {
+    /** Parts that hung from it: they stand where they stood at rest, fastened to nothing; `control` moved one and went with its joint. */
+    released: Array<{
+        part: string;
+        control?: string;
+    }>;
+    /** Values that followed its size or place, now the numbers they were. */
+    fixed: Array<{
+        part: string;
+        value: number;
+        unit: string;
+    }>;
+    /** Parts that moved with its joint (or a released part's), each with a control of its own now. */
+    controls: Array<{
+        part: string;
+        control: string;
+        min: number;
+        max: number;
+    }>;
+    /** The figure stood on its face; it stands on no face of its own now. */
+    mountingFace?: boolean;
+    /** Places declared on it (a gripper's grip): they were its, and went with it. */
+    bindings?: Array<{
+        id: string;
+        label?: string;
+    }>;
+}
+/**
+ * "This part moves like this."
+ *
+ * Added on top of whatever the part is fastened to, never instead of it: the motion becomes its own node between
+ * the part's pose and the frame it is fastened into, so the fastening is still there and still holds when the
+ * parent is resized (designer's ruling 2026-09-23 — attachment and motion may not overwrite one pose).
+ *
+ * Named rather than assumed:
+ *   - `frame`: which frame the axis is measured in. `attachment`, the default, is the frame the part is fastened
+ *     into — the parent's, or the asset's for a part fastened to nothing. `asset` is only accepted for a part
+ *     fastened to nothing, where the two are the same frame; for a fastened part the axis would have to be
+ *     re-expressed, and this command does not do that quietly.
+ *   - `state`: the control a person moves — its id, unit, range and starting value, and optionally the name it
+ *     shows under and how long it takes to travel its range.
+ *   - `travel`: for a `ratio` control on a slide, how far the part goes at 1. It can follow the instance or a
+ *     part, so a gate opens by its own width whatever the gate's width is. A `mm` control needs none: it is the
+ *     distance.
+ *   - `clip`: optional, and named. A clip is declared, never inferred from an id.
+ */
+export interface FigureMotionRequest {
+    kind: 'add-motion';
+    part: string;
+    motion: {
+        kind: 'slide' | 'turn';
+        axis: Axis;
+        frame?: 'attachment' | 'asset';
+    };
+    state: {
+        id: string;
+        unit: 'mm' | 'deg' | 'ratio';
+        min: number;
+        max: number;
+        start?: number;
+        label?: string;
+        sweep?: number;
+    };
+    travel?: FigureTravel;
+    clip?: {
+        name: string;
+        duration: number;
+        keys: Array<{
+            at: number;
+            value: number;
+        }>;
+        loop?: 'wrap' | 'hold';
+        accumulates?: boolean;
+    };
+    replace?: boolean;
+}
+/**
+ * The room a figure takes up, worked out from its parts.
+ *
+ * Proposing and declaring are two steps on purpose (designer's ruling 2026-09-23). What the parts come to is
+ * a candidate; the author confirms it. Nothing here ever widens a declaration that is already in the asset
+ * because the model changed — a figure that has outgrown its declared volume is something the gate reports, not
+ * something an authoring command papers over. Re-propose and confirm again.
+ *
+ * `over` says which question is being answered, because they have different answers:
+ *   - `rest`: the room the figure takes up as it stands, every control at its starting value.
+ *   - `range`: the room it takes up anywhere in its travel, every control swept over its whole range.
+ *
+ * Naming the face the figure is mounted on is a separate command. It is a different claim from how much room
+ * the figure takes up, and an author may want one without the other.
+ */
+export interface FigureOccupancyProposal {
+    over: 'rest' | 'range';
+    /** What the bounds come to at the asset's current design inputs, so a person sees what they are confirming. */
+    at: Record<Axis, {
+        min: number;
+        max: number;
+    }>;
+    /** The parts the bounds were read from. */
+    parts: string[];
+    /** Parts left out, and why. A proposal never pretends to cover what it could not read. */
+    skipped: Array<{
+        part: string;
+        reason: string;
+    }>;
+    /**
+     * The figure this was read from, as one value. Confirming a proposal against a different figure is refused:
+     * comparing the list of parts was not enough, because widening a part keeps the list and changes the answer
+     * (designer's counterexample 2026-09-23 — a 100 mm part grown to 300 mm slipped an unseen volume through).
+     */
+    basis: string;
+}
+/** The places things are held, with the part and face each sits on -- what a screen lists. */
+export interface FigureBindingPlace {
+    id: string;
+    label: string;
+    role: 'seat' | 'grip';
+    part: string | null;
+    face: FigureFace | null;
+    accepts: string[];
+    capacity: number;
+    region: Record<Axis, number> | null;
+    /** For a place unfolded from the slot layout (ADR-0118): which slot it is and where on the face. */
+    slot?: {
+        tier: number;
+        slot: number;
+        anchorId: string;
+        tierPosition: {
+            x: number;
+            y: number;
+            z: number;
+        };
+        tierRotation: number;
+        offset: {
+            x: number;
+            z: number;
+        };
+        rotation: number;
+    };
+}
+/** What 「every length follows the one ratio」 changes, and what it leaves and why. */
+export interface FigureProportionPlan {
+    /** A part's own measure on a shape axis, and the share of the figure's size on that axis it becomes. */
+    dimensions: Array<{
+        part: string;
+        axis: Axis;
+        times: number;
+    }>;
+    /** A fastening's length in millimetres: an offset along a face axis, the gap, or a row's pitch. */
+    lengths: Array<{
+        joint: string;
+        at: 'gap' | 'pitch' | Axis;
+        axis: Axis;
+        times: number;
+    }>;
+    /**
+     * What stays as it is, with why. `follows`: it follows something already -- it grows with the ratio if what it
+     * follows does. Otherwise it is a length this command does not write, and keeps its number.
+     */
+    skipped: Array<{
+        what: string;
+        reason: string;
+        follows?: true;
+    }>;
+}
+//# sourceMappingURL=authoring-types.d.ts.map