@hatiolab/figure-model 0.1.36 → 0.1.38

package/dist/v3-authoring-actions.d.ts

@@ -0,0 +1,226 @@
+import type { Axis } from './types.ts';
+import type { V3Asset } from './v3-asset-types.ts';
+/** The six faces of a box-shaped part, and the axis each one faces along. */
+export declare const V3_FACES: {
+    readonly left: "x";
+    readonly right: "x";
+    readonly bottom: "y";
+    readonly top: "y";
+    readonly back: "z";
+    readonly front: "z";
+};
+export type V3Face = keyof typeof V3_FACES;
+/**
+ * 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 V3DimensionSource = 
+/** 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.
+ */
+export type V3Measure = number | {
+    from: V3DimensionSource;
+    times?: number;
+    plus?: number;
+};
+/** Where a part sits inside the face it is fastened to, on one of that face's two axes. */
+export type V3FaceAlignment = 'centre' | 'min' | 'max' | {
+    mm: V3Measure;
+};
+export type V3AuthoringAction = 
+/**
+ * "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. 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;
+    source: V3DimensionSource;
+    times?: number;
+    plus?: number;
+    replace?: boolean;
+}
+/** "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: V3Face;
+    /** 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: V3Face;
+    } | {
+        plane: 'mounting-plane';
+    };
+    facing?: 'meet' | 'flush';
+    gap?: V3Measure;
+    align?: Partial<Record<Axis, V3FaceAlignment>>;
+    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 part moves like this" — see `V3MotionRequest`. */
+ | V3MotionRequest
+/** "This part does not move any more." The control it created and the clip that drove it go with it. */
+ | {
+    kind: 'remove-motion';
+    part: string;
+}
+/** "This is the room it takes up" — a proposal the author has looked at, confirmed as it stands. */
+ | {
+    kind: 'declare-occupancy';
+    proposal: V3OccupancyProposal;
+    placement: 'floor' | 'ceiling' | 'center';
+}
+/** "This face is what it is mounted on." A separate choice from the room it takes up. */
+ | {
+    kind: 'set-mounting-face';
+    part: string;
+    face: V3Face;
+}
+/** "It is not mounted on anything in particular." */
+ | {
+    kind: 'clear-mounting-face';
+};
+/** Apply one authoring command. Throws on any refusal, leaving the asset it was given untouched. */
+export declare function applyV3Authoring(source: V3Asset, action: V3AuthoringAction): V3Asset;
+/** What each part is fastened to, for a reader that wants the structure rather than the graph. */
+export declare function v3AttachmentsOf(asset: V3Asset): Record<string, string | null>;
+/**
+ * "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 (V3 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 V3MotionRequest {
+    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?: {
+        source?: V3DimensionSource;
+        times?: number;
+        plus?: number;
+    };
+    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 (V3 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 V3OccupancyProposal {
+    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
+     * (V3 designer's counterexample 2026-09-23 — a 100 mm part grown to 300 mm slipped an unseen volume through).
+     */
+    basis: string;
+}
+/** What the parts come to, and what a person is being asked to confirm. Reads the asset; changes nothing. */
+export declare function proposeV3Occupancy(asset: V3Asset, options?: {
+    over?: 'rest' | 'range';
+}): V3OccupancyProposal;
+//# sourceMappingURL=v3-authoring-actions.d.ts.map

package/dist/v3-authoring-actions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"v3-authoring-actions.d.ts","sourceRoot":"","sources":["../src/v3-authoring-actions.ts"],"names":[],"mappings":"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"}