@pascal-app/core 1.0.1 → 1.0.4

package/dist/procedural-items/integration.d.ts

@@ -12,7 +12,7 @@ export declare function prepareProceduralPlacement(recipe: Recipe, nodes: QueryN
     id: `procedural-item_${string}`;
     type: "procedural-item";
     recipe: {
-        version: 1;
+        version: 2 | 1;
         name: string;
         description: string;
         parameters: {
@@ -22,9 +22,10 @@ export declare function prepareProceduralPlacement(recipe: Recipe, nodes: QueryN
             min: number;
             max: number;
             step: number;
-            unit: "count" | "m" | "rad";
+            unit: "count" | "m" | "rad" | "s" | "bool" | "choice";
+            options?: string[] | undefined;
             part?: string | undefined;
-            axis?: "x" | "y" | "z" | undefined;
+            axis?: "x" | "z" | "y" | undefined;
         }[];
         slots: {
             id: string;
@@ -36,16 +37,102 @@ export declare function prepareProceduralPlacement(recipe: Recipe, nodes: QueryN
             id: string;
             label: string;
             count: import("./recipe.js").Expr;
-            shapes: {
+            shapes: ({
                 id: string;
-                primitive: "box" | "roundedBox" | "cylinder";
+                primitive: "box" | "roundedBox" | "cylinder" | "ellipsoid";
                 slot: string;
                 size: [import("./recipe.js").Expr, import("./recipe.js").Expr, import("./recipe.js").Expr];
                 position: [import("./recipe.js").Expr, import("./recipe.js").Expr, import("./recipe.js").Expr];
+                support?: boolean | undefined;
+                when?: import("./recipe.js").Expr | undefined;
                 rotation?: [import("./recipe.js").Expr, import("./recipe.js").Expr, import("./recipe.js").Expr] | undefined;
                 radius?: import("./recipe.js").Expr | undefined;
+                topScale?: import("./recipe.js").Expr | undefined;
+                segments?: number | undefined;
+                open?: boolean | undefined;
+                inner?: import("./recipe.js").Expr | undefined;
+                arc?: import("./recipe.js").Expr | undefined;
+            } | {
+                id: string;
+                primitive: "extrude";
+                slot: string;
+                section: {
+                    kind: "rectangle";
+                    width: import("./recipe.js").Expr;
+                    depth: import("./recipe.js").Expr;
+                    corner?: import("./recipe.js").Expr | undefined;
+                } | {
+                    kind: "round";
+                    radius: import("./recipe.js").Expr;
+                    wall?: import("./recipe.js").Expr | undefined;
+                } | {
+                    kind: "oval";
+                    width: import("./recipe.js").Expr;
+                    depth: import("./recipe.js").Expr;
+                } | {
+                    kind: "section";
+                    family: "C" | "I" | "L" | "T" | "Z" | "rect-tube";
+                    width: import("./recipe.js").Expr;
+                    depth: import("./recipe.js").Expr;
+                    web: import("./recipe.js").Expr;
+                    flange: import("./recipe.js").Expr;
+                } | {
+                    kind: "polygon";
+                    outer: [import("./recipe.js").Expr, import("./recipe.js").Expr][];
+                    holes?: [import("./recipe.js").Expr, import("./recipe.js").Expr][][] | undefined;
+                };
+                length: import("./recipe.js").Expr;
+                position: [import("./recipe.js").Expr, import("./recipe.js").Expr, import("./recipe.js").Expr];
+                support?: boolean | undefined;
+                when?: import("./recipe.js").Expr | undefined;
+                bevel?: import("./recipe.js").Expr | undefined;
+                rotation?: [import("./recipe.js").Expr, import("./recipe.js").Expr, import("./recipe.js").Expr] | undefined;
+            } | {
+                id: string;
+                primitive: "revolve";
+                slot: string;
+                profile: [import("./recipe.js").Expr, import("./recipe.js").Expr][];
+                position: [import("./recipe.js").Expr, import("./recipe.js").Expr, import("./recipe.js").Expr];
                 support?: boolean | undefined;
-            }[];
+                when?: import("./recipe.js").Expr | undefined;
+                segments?: number | undefined;
+                arc?: import("./recipe.js").Expr | undefined;
+                rotation?: [import("./recipe.js").Expr, import("./recipe.js").Expr, import("./recipe.js").Expr] | undefined;
+            })[];
+            parent?: string | undefined;
+            frame?: {
+                position: [import("./recipe.js").Expr, import("./recipe.js").Expr, import("./recipe.js").Expr];
+                rotation?: [import("./recipe.js").Expr, import("./recipe.js").Expr, import("./recipe.js").Expr] | undefined;
+            } | undefined;
+            when?: import("./recipe.js").Expr | undefined;
+            motion?: {
+                kind: "hinge";
+                pivot: [import("./recipe.js").Expr, import("./recipe.js").Expr, import("./recipe.js").Expr];
+                axis: "x" | "z" | "y";
+                angle: import("./recipe.js").Expr;
+                delay?: import("./recipe.js").Expr | undefined;
+                duration?: import("./recipe.js").Expr | undefined;
+                easing?: "linear" | "smooth" | "soft" | undefined;
+            } | {
+                kind: "slide";
+                axis: "x" | "z" | "y";
+                distance: import("./recipe.js").Expr;
+                delay?: import("./recipe.js").Expr | undefined;
+                duration?: import("./recipe.js").Expr | undefined;
+                easing?: "linear" | "smooth" | "soft" | undefined;
+            } | {
+                kind: "spin";
+                pivot: [import("./recipe.js").Expr, import("./recipe.js").Expr, import("./recipe.js").Expr];
+                axis: "x" | "z" | "y";
+                radiansPerSecond: import("./recipe.js").Expr;
+            } | undefined;
+            light?: {
+                position: [import("./recipe.js").Expr, import("./recipe.js").Expr, import("./recipe.js").Expr];
+                color: string;
+                intensity?: number | undefined;
+                distance?: number | undefined;
+                emissiveSlot?: string | undefined;
+            } | undefined;
         }[];
         constraints: {
             left: import("./recipe.js").Expr;
@@ -62,6 +149,16 @@ export declare function prepareProceduralPlacement(recipe: Recipe, nodes: QueryN
             attachTo: "ceiling" | "wall-side";
             reference: string;
         } | undefined;
+        base?: import("./recipe.js").Expr | undefined;
+        cuts?: ({
+            shape: "rect";
+            size: [import("./recipe.js").Expr, import("./recipe.js").Expr];
+            center?: [import("./recipe.js").Expr, import("./recipe.js").Expr] | undefined;
+        } | {
+            shape: "circle";
+            diameter: import("./recipe.js").Expr;
+            center?: [import("./recipe.js").Expr, import("./recipe.js").Expr] | undefined;
+        })[] | undefined;
         surfaces?: {
             id: string;
             label: string;
@@ -70,6 +167,19 @@ export declare function prepareProceduralPlacement(recipe: Recipe, nodes: QueryN
             part?: string | undefined;
             rotation?: [import("./recipe.js").Expr, import("./recipe.js").Expr, import("./recipe.js").Expr] | undefined;
         }[] | undefined;
+        joints?: {
+            child: string;
+            kind: "fixed" | "continuous" | "revolute" | "prismatic";
+            origin: [import("./recipe.js").Expr, import("./recipe.js").Expr, import("./recipe.js").Expr];
+            axis: [import("./recipe.js").Expr, import("./recipe.js").Expr, import("./recipe.js").Expr];
+            delay?: import("./recipe.js").Expr | undefined;
+            duration?: import("./recipe.js").Expr | undefined;
+            easing?: "linear" | "smooth" | "soft" | undefined;
+            open?: import("./recipe.js").Expr | undefined;
+            rest?: import("./recipe.js").Expr | undefined;
+            range?: [import("./recipe.js").Expr, import("./recipe.js").Expr] | undefined;
+            speed?: import("./recipe.js").Expr | undefined;
+        }[] | undefined;
     };
     parameters: Record<string, number>;
     slots: Record<string, string>;
@@ -85,6 +195,17 @@ export declare function prepareProceduralPlacement(recipe: Recipe, nodes: QueryN
         fov?: number | undefined;
         zoom?: number | undefined;
     } | undefined;
+    provenance?: {
+        refs: {
+            id: string;
+            ns?: string | undefined;
+            role?: "primary" | "piece" | "absorbed" | "alias" | "derived" | undefined;
+        }[];
+        lineage?: {
+            op: "import" | "split" | "merge" | "duplicate" | "convert" | "promote" | "make-independent" | "attach";
+            fromIds: string[];
+        } | undefined;
+    } | undefined;
     wallId?: string | undefined;
     side?: "front" | "back" | undefined;
     supportSlabId?: string | undefined;

package/dist/procedural-items/integration.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"integration.d.ts","sourceRoot":"","sources":["../../src/procedural-items/integration.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,UAAU,EAA+B,MAAM,SAAS,CAAA;AACtE,OAAO,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,UAAU,CAAA;AAE5C,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,UAAU,EACjB,SAAS,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,IAAI,CAAC;IAAC,IAAI,CAAC,EAAE,OAAO,GAAG,MAAM,CAAA;CAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAiBzE"}
+{"version":3,"file":"integration.d.ts","sourceRoot":"","sources":["../../src/procedural-items/integration.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,UAAU,EAA+B,MAAM,SAAS,CAAA;AACtE,OAAO,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,UAAU,CAAA;AAE5C,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,UAAU,EACjB,SAAS,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,IAAI,CAAC;IAAC,IAAI,CAAC,EAAE,OAAO,GAAG,MAAM,CAAA;CAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAiBzE"}

package/dist/procedural-items/joints.d.ts

@@ -0,0 +1,56 @@
+import type { EvaluatedMotion, EvaluatedShape, Expr, Recipe, Vec3 } from './recipe.js';
+import { type Bounds, type Pose } from './spatial.js';
+export type PartPlacement = {
+    /** Rest pose of the part's frame in design space, joint included. */
+    pose: Pose;
+    /** The motion group the part's shapes and light ride in, if any. */
+    group?: string;
+    /** The group's motion, on the instance that owns the joint. */
+    motion?: EvaluatedMotion;
+};
+export declare function usesPartTree(recipe: Recipe): boolean;
+/** Structural checks that need no parameter values. */
+export declare function validatePartTree(recipe: Recipe): Map<string, {
+    child: string;
+    kind: "fixed" | "continuous" | "revolute" | "prismatic";
+    origin: [Expr, Expr, Expr];
+    axis: [Expr, Expr, Expr];
+    delay?: Expr | undefined;
+    duration?: Expr | undefined;
+    easing?: "linear" | "smooth" | "soft" | undefined;
+    open?: Expr | undefined;
+    rest?: Expr | undefined;
+    range?: [Expr, Expr] | undefined;
+    speed?: Expr | undefined;
+}>;
+/** True when the part or an ancestor moves (so it cannot carry supports or surfaces). */
+export declare function partMoves(recipe: Recipe, partId: string): boolean;
+/**
+ * Rest poses, groups and motions of every part instance of a v2 part tree, keyed
+ * `${part}:${index}`. A missing key means the instance is not built (its own or an
+ * ancestor's `when` is zero).
+ */
+export declare function placeParts(recipe: Recipe, value: (e: Expr, index: number) => number, counts: ReadonlyMap<string, number>): Map<string, PartPlacement>;
+/**
+ * Where each root joint group can reach: its shapes' box, grown by every nested group's
+ * reach, swept over its own travel (and range) interval. Intervals compose per joint, so
+ * nesting never multiplies samples.
+ */
+export declare function jointReach(motions: readonly EvaluatedMotion[], shapes: readonly EvaluatedShape[], shapeBounds: (shape: EvaluatedShape) => Bounds): {
+    motion: EvaluatedMotion;
+    bounds: Bounds;
+}[];
+export type OperablePart = {
+    id: string;
+    label: string;
+    kind: EvaluatedMotion['kind'];
+};
+/** Parts a person can operate (Play, E, controls): a flat motion or a non-fixed joint. */
+export declare function operableParts(recipe: Pick<Recipe, 'parts' | 'joints'>): OperablePart[];
+/** Where a motion group sits in its parent group at rest: its pivot less the parent's. */
+export declare function motionRestOffset(motion: EvaluatedMotion, motions: readonly EvaluatedMotion[]): Vec3;
+/** A motion's unit axis in its parent group's frame, which has design axes at rest. */
+export declare function motionAxis(motion: EvaluatedMotion): Vec3;
+/** The operable part that moves `partId`: itself, or its nearest operable ancestor. */
+export declare function operablePartFor(recipe: Pick<Recipe, 'parts' | 'joints'>, partId: string): OperablePart | undefined;
+//# sourceMappingURL=joints.d.ts.map

package/dist/procedural-items/joints.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"joints.d.ts","sourceRoot":"","sources":["../../src/procedural-items/joints.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,UAAU,CAAA;AACnF,OAAO,EACL,KAAK,MAAM,EAOX,KAAK,IAAI,EAIV,MAAM,WAAW,CAAA;AAUlB,MAAM,MAAM,aAAa,GAAG;IAC1B,qEAAqE;IACrE,IAAI,EAAE,IAAI,CAAA;IACV,oEAAoE;IACpE,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,+DAA+D;IAC/D,MAAM,CAAC,EAAE,eAAe,CAAA;CACzB,CAAA;AAID,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAKpD;AAED,uDAAuD;AACvD,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM;;;;;;;;;;;;GAuC9C;AAED,yFAAyF;AACzF,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAQjE;AAQD;;;;GAIG;AACH,wBAAgB,UAAU,CACxB,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,KAAK,MAAM,EACzC,MAAM,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,GAClC,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,CA6H5B;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CACxB,OAAO,EAAE,SAAS,eAAe,EAAE,EACnC,MAAM,EAAE,SAAS,cAAc,EAAE,EACjC,WAAW,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,MAAM,GAC7C;IAAE,MAAM,EAAE,eAAe,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,EAAE,CAmC/C;AAED,MAAM,MAAM,YAAY,GAAG;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,eAAe,CAAC,MAAM,CAAC,CAAA;CAAE,CAAA;AACvF,0FAA0F;AAC1F,wBAAgB,aAAa,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,OAAO,GAAG,QAAQ,CAAC,GAAG,YAAY,EAAE,CAOtF;AACD,0FAA0F;AAC1F,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,eAAe,EACvB,OAAO,EAAE,SAAS,eAAe,EAAE,GAClC,IAAI,CAGN;AACD,uFAAuF;AACvF,wBAAgB,UAAU,CAAC,MAAM,EAAE,eAAe,GAAG,IAAI,CAIxD;AACD,uFAAuF;AACvF,wBAAgB,eAAe,CAC7B,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,OAAO,GAAG,QAAQ,CAAC,EACxC,MAAM,EAAE,MAAM,GACb,YAAY,GAAG,SAAS,CAQ1B"}

package/dist/procedural-items/joints.js

@@ -0,0 +1,251 @@
+import { boundsOf, boxCorners, composePoses, eulerPose, hingePose, IDENTITY_POSE, poseDirection, posePoint, sweptHingeBounds, } from './spatial.js';
+const LIMITS = { hinge: Math.PI, slide: 5, spin: 20 };
+const KIND = { revolute: 'hinge', prismatic: 'slide', continuous: 'spin' };
+export function usesPartTree(recipe) {
+    // An explicitly present joints array, even empty, is v2 content.
+    return Boolean(recipe.joints !== undefined || recipe.parts.some((part) => part.parent || part.frame));
+}
+/** Structural checks that need no parameter values. */
+export function validatePartTree(recipe) {
+    const parts = new Map(recipe.parts.map((part) => [part.id, part]));
+    const joints = new Map();
+    for (const joint of recipe.joints ?? []) {
+        const part = parts.get(joint.child);
+        if (!part)
+            throw new Error(`Unknown joint part ${joint.child}`);
+        if (joints.has(joint.child))
+            throw new Error(`Part ${joint.child} has more than one joint`);
+        if (part.motion)
+            throw new Error(`Part ${joint.child} has both a motion and a joint`);
+        joints.set(joint.child, joint);
+        const timed = [joint.delay, joint.duration, joint.easing].some((v) => v !== undefined);
+        const valued = [joint.open, joint.rest, joint.range].some((v) => v !== undefined);
+        if (joint.kind === 'fixed' && (valued || timed || joint.speed !== undefined))
+            throw new Error(`Fixed joint ${joint.child} takes no values, speed or timing`);
+        if ((joint.kind === 'revolute' || joint.kind === 'prismatic') &&
+            (joint.open === undefined || joint.speed !== undefined))
+            throw new Error(`Joint ${joint.child} needs an open value and no speed`);
+        if (joint.kind === 'continuous' &&
+            (joint.speed === undefined || joint.open !== undefined || joint.range || timed))
+            throw new Error(`Continuous joint ${joint.child} needs a speed and no open value, range or timing`);
+    }
+    for (const part of recipe.parts) {
+        if (part.motion && (part.parent || part.frame))
+            throw new Error(`Part ${part.id} with a flat motion cannot sit in a part tree`);
+        if (!part.parent)
+            continue;
+        if (part.parent === part.id || !parts.has(part.parent))
+            throw new Error(`Unknown parent ${part.parent} for ${part.id}`);
+        if (parts.get(part.parent).motion)
+            throw new Error(`Part ${part.id} cannot hang from ${part.parent}, which has a flat motion`);
+        let depth = 0;
+        for (let at = part; at?.parent; at = parts.get(at.parent))
+            if (++depth > 8)
+                throw new Error(`Part tree around ${part.id} is cyclic or deeper than 8`);
+    }
+    return joints;
+}
+/** True when the part or an ancestor moves (so it cannot carry supports or surfaces). */
+export function partMoves(recipe, partId) {
+    const parts = new Map(recipe.parts.map((part) => [part.id, part]));
+    for (let at = parts.get(partId); at; at = at.parent ? parts.get(at.parent) : undefined) {
+        if (at.motion)
+            return true;
+        const joint = recipe.joints?.find((j) => j.child === at.id);
+        if (joint && joint.kind !== 'fixed')
+            return true;
+    }
+    return false;
+}
+function unit(axis, part) {
+    const length = Math.hypot(...axis);
+    if (!(length > 1e-9))
+        throw new Error(`Joint ${part} needs a nonzero axis`);
+    return axis.map((v) => v / length);
+}
+/**
+ * Rest poses, groups and motions of every part instance of a v2 part tree, keyed
+ * `${part}:${index}`. A missing key means the instance is not built (its own or an
+ * ancestor's `when` is zero).
+ */
+export function placeParts(recipe, value, counts) {
+    const parts = new Map(recipe.parts.map((part) => [part.id, part]));
+    const joints = new Map((recipe.joints ?? []).map((joint) => [joint.child, joint]));
+    const placed = new Map();
+    const vec = (v, i) => v.map((e) => value(e, i));
+    const place = (part, i) => {
+        const key = `${part.id}:${i}`;
+        if (placed.has(key))
+            return placed.get(key);
+        // A parent repeat that does not exist (count 0, or fewer repeats) carries no children.
+        if (i >= counts.get(part.id))
+            return null;
+        let parent = { pose: IDENTITY_POSE };
+        if (part.parent) {
+            const host = parts.get(part.parent);
+            // A single child rides repeat 0 of its parent; equal counts bind by index.
+            const single = counts.get(part.id) === 1;
+            if (!single && counts.get(part.id) !== counts.get(host.id))
+                throw new Error(`Part ${part.id} must repeat once or exactly as often as its parent ${host.id}`);
+            parent = place(host, single ? 0 : i);
+        }
+        if (!parent || (part.when !== undefined && value(part.when, i) === 0)) {
+            placed.set(key, null);
+            return null;
+        }
+        const frame = part.frame
+            ? composePoses(parent.pose, eulerPose(vec(part.frame.position, i), vec(part.frame.rotation ?? [0, 0, 0], i)))
+            : parent.pose;
+        const joint = joints.get(part.id);
+        let result = { pose: frame, group: parent.group };
+        if (joint) {
+            const origin = vec(joint.origin, i);
+            const axis = unit(vec(joint.axis, i), part.id);
+            const rest = joint.rest === undefined ? 0 : value(joint.rest, i);
+            const move = (amount) => joint.kind === 'prismatic'
+                ? { r: IDENTITY_POSE.r, t: axis.map((v) => v * amount) }
+                : hingePose(origin, axis, amount);
+            result = {
+                pose: joint.kind === 'fixed' || rest === 0 ? frame : composePoses(frame, move(rest)),
+                group: parent.group,
+            };
+            if (joint.kind !== 'fixed') {
+                const kind = KIND[joint.kind];
+                const open = joint.kind === 'continuous' ? value(joint.speed, i) : value(joint.open, i);
+                const range = joint.range?.map((e) => value(e, i));
+                if (range &&
+                    !(range[0] <= range[1] &&
+                        [rest, open].every((v) => v >= range[0] - 1e-9 && v <= range[1] + 1e-9)))
+                    throw new Error(`Joint ${part.id} rest and open values must lie within its range`);
+                if (range &&
+                    joint.kind !== 'continuous' &&
+                    range.some((end) => Math.abs(end - rest) > LIMITS[kind] + 1e-9))
+                    throw new Error(`Joint ${part.id} range must lie within ${LIMITS[kind]} of its rest value`);
+                let amount = joint.kind === 'continuous' ? open : open - rest;
+                if (!(Math.abs(amount) > 0 && Math.abs(amount) <= LIMITS[kind]))
+                    throw new Error(`Invalid ${kind} amount for ${part.id}: expected 0 < absolute value <= ${LIMITS[kind]}`);
+                const delay = joint.kind === 'continuous' ? 0 : value(joint.delay ?? 0, i);
+                const duration = joint.kind === 'continuous' ? 0 : value(joint.duration ?? 0.45, i);
+                const easing = joint.kind === 'continuous' ? 'linear' : (joint.easing ?? 'smooth');
+                if (!Number.isFinite(delay) ||
+                    !Number.isFinite(duration) ||
+                    delay < 0 ||
+                    delay > 1 ||
+                    (joint.kind !== 'continuous' && (duration < 0.1 || duration > 2)))
+                    throw new Error(`Invalid timing for ${part.id}`);
+                // Design-space axis at rest; a principal axis keeps today's flat form exactly.
+                let direction = unit(poseDirection(frame, axis), part.id);
+                const principal = direction.findIndex((v) => Math.abs(v) > 1 - 1e-9);
+                const flipped = principal >= 0 && direction[principal] < 0;
+                if (flipped)
+                    amount = -amount;
+                const letter = ['x', 'y', 'z'][principal >= 0
+                    ? principal
+                    : direction.map(Math.abs).indexOf(Math.max(...direction.map(Math.abs)))];
+                if (principal >= 0)
+                    direction = [0, 0, 0].map((_, k) => (k === principal ? 1 : 0));
+                const id = i ? `${part.id}~${i}` : part.id;
+                result.group = id;
+                result.motion = {
+                    id,
+                    partId: part.id,
+                    kind,
+                    axis: letter,
+                    pivot: kind === 'slide' ? [0, 0, 0] : posePoint(frame, origin),
+                    amount,
+                    delay,
+                    duration,
+                    easing,
+                    ...(principal < 0 && { direction }),
+                    ...(parent.group && { parent: parent.group }),
+                    // Relative to rest, and about the stored (positive) axis when the joint's was negative.
+                    ...(range && {
+                        range: (flipped
+                            ? [rest - range[1], rest - range[0]]
+                            : [range[0] - rest, range[1] - rest]),
+                    }),
+                };
+            }
+        }
+        placed.set(key, result);
+        return result;
+    };
+    const out = new Map();
+    for (const part of recipe.parts)
+        for (let i = 0; i < counts.get(part.id); i++) {
+            const at = place(part, i);
+            if (at)
+                out.set(`${part.id}:${i}`, at);
+        }
+    return out;
+}
+/**
+ * Where each root joint group can reach: its shapes' box, grown by every nested group's
+ * reach, swept over its own travel (and range) interval. Intervals compose per joint, so
+ * nesting never multiplies samples.
+ */
+export function jointReach(motions, shapes, shapeBounds) {
+    const own = new Map();
+    for (const shape of shapes) {
+        if (!shape.motionGroup)
+            continue;
+        const b = shapeBounds(shape);
+        own.set(shape.motionGroup, [...(own.get(shape.motionGroup) ?? []), b.min, b.max]);
+    }
+    const reach = (motion) => {
+        const points = [...(own.get(motion.id) ?? [])];
+        for (const child of motions)
+            if (child.parent === motion.id) {
+                const b = reach(child);
+                if (b)
+                    points.push(b.min, b.max);
+            }
+        if (!points.length)
+            return null;
+        const box = boundsOf(points);
+        const axis = motionAxis(motion);
+        const travel = [0, motion.amount, ...(motion.range ?? [])];
+        const [from, to] = [Math.min(...travel), Math.max(...travel)];
+        if (motion.kind === 'slide') {
+            const corners = boxCorners(box.min, box.max);
+            return boundsOf([from, to].flatMap((d) => corners.map((c) => c.map((v, k) => v + axis[k] * d))));
+        }
+        return motion.kind === 'spin'
+            ? sweptHingeBounds(box, motion.pivot, axis, 0, 2 * Math.PI)
+            : sweptHingeBounds(box, motion.pivot, axis, from, to);
+    };
+    return motions
+        .filter((motion) => !motion.parent)
+        .flatMap((motion) => {
+        const bounds = reach(motion);
+        return bounds ? [{ motion, bounds }] : [];
+    });
+}
+/** Parts a person can operate (Play, E, controls): a flat motion or a non-fixed joint. */
+export function operableParts(recipe) {
+    return recipe.parts.flatMap((part) => {
+        const joint = recipe.joints?.find((entry) => entry.child === part.id);
+        const kind = part.motion?.kind ?? (joint && joint.kind !== 'fixed' ? KIND[joint.kind] : undefined);
+        return kind ? [{ id: part.id, label: part.label, kind }] : [];
+    });
+}
+/** Where a motion group sits in its parent group at rest: its pivot less the parent's. */
+export function motionRestOffset(motion, motions) {
+    const parent = motion.parent ? motions.find((entry) => entry.id === motion.parent) : undefined;
+    return motion.pivot.map((v, i) => v - (parent?.pivot[i] ?? 0));
+}
+/** A motion's unit axis in its parent group's frame, which has design axes at rest. */
+export function motionAxis(motion) {
+    return (motion.direction ?? [0, 1, 2].map((k) => (['x', 'y', 'z'][k] === motion.axis ? 1 : 0)));
+}
+/** The operable part that moves `partId`: itself, or its nearest operable ancestor. */
+export function operablePartFor(recipe, partId) {
+    const operable = new Map(operableParts(recipe).map((part) => [part.id, part]));
+    const parts = new Map(recipe.parts.map((part) => [part.id, part]));
+    for (let id = partId, depth = 0; id && depth <= 8; depth++) {
+        if (operable.has(id))
+            return operable.get(id);
+        id = parts.get(id)?.parent;
+    }
+    return undefined;
+}

package/dist/procedural-items/library-colors.d.ts

@@ -49,6 +49,18 @@ export type LibraryColorMatch = {
     distance: number;
 };
 export declare function nearestLibraryColorRef(hex: string, catalog?: readonly MaterialCatalogItem[]): LibraryColorMatch | null;
+export type PascalMaterialHints = {
+    name?: string;
+    color?: string;
+    roughness?: number;
+    metalness?: number;
+    /** See-through: transmissive, or alpha-blended below the viewer's glass opacity. */
+    transparent?: boolean;
+    emissive?: boolean;
+    finish?: ProceduralFinish | 'color';
+};
+/** Deterministic finish/tone matching; uncertain colours keep their authored material. */
+export declare function matchPascalMaterial(slot: PascalMaterialHints): `library:${string}` | null;
 export declare function snapProceduralSlotsToLibrary(node: ProceduralItemNode, options?: {
     keepOverrides: true;
 }): ProceduralItemNode['slots'];

package/dist/procedural-items/library-colors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"library-colors.d.ts","sourceRoot":"","sources":["../../src/procedural-items/library-colors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAoB,KAAK,mBAAmB,EAAE,MAAM,qBAAqB,CAAA;AAChF,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,QAAQ,CAAA;AAChD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,UAAU,CAAA;AAEtC,KAAK,gBAAgB,GAAG,WAAW,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAA;AAItE,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAmB/B,CAAA;AAED,wBAAgB,4BAA4B,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAI5E;AAED,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,gBAAgB,EACxB,KAAK,EAAE,MAAM,GACZ,WAAW,MAAM,EAAE,GAAG,SAAS,CAGjC;AAED,MAAM,MAAM,iBAAiB,GAAG;IAC9B,GAAG,EAAE,WAAW,MAAM,EAAE,CAAA;IACxB,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,MAAM,CAAA;CACjB,CAAA;AAiCD,wBAAgB,sBAAsB,CACpC,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,SAAS,mBAAmB,EAAqB,GACzD,iBAAiB,GAAG,IAAI,CAc1B;AAED,wBAAgB,4BAA4B,CAC1C,IAAI,EAAE,kBAAkB,EACxB,OAAO,GAAE;IAAE,aAAa,EAAE,IAAI,CAAA;CAA4B,GACzD,kBAAkB,CAAC,OAAO,CAAC,CAU7B"}
+{"version":3,"file":"library-colors.d.ts","sourceRoot":"","sources":["../../src/procedural-items/library-colors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAoB,KAAK,mBAAmB,EAAE,MAAM,qBAAqB,CAAA;AAChF,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,QAAQ,CAAA;AAChD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,UAAU,CAAA;AAEtC,KAAK,gBAAgB,GAAG,WAAW,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAA;AAItE,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAmB/B,CAAA;AAED,wBAAgB,4BAA4B,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAI5E;AAED,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,gBAAgB,EACxB,KAAK,EAAE,MAAM,GACZ,WAAW,MAAM,EAAE,GAAG,SAAS,CAGjC;AAED,MAAM,MAAM,iBAAiB,GAAG;IAC9B,GAAG,EAAE,WAAW,MAAM,EAAE,CAAA;IACxB,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,MAAM,CAAA;CACjB,CAAA;AAiCD,wBAAgB,sBAAsB,CACpC,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,SAAS,mBAAmB,EAAqB,GACzD,iBAAiB,GAAG,IAAI,CAc1B;AAED,MAAM,MAAM,mBAAmB,GAAG;IAChC,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,oFAAoF;IACpF,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,MAAM,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAA;CACpC,CAAA;AAED,0FAA0F;AAC1F,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,mBAAmB,GAAG,WAAW,MAAM,EAAE,GAAG,IAAI,CAqCzF;AAED,wBAAgB,4BAA4B,CAC1C,IAAI,EAAE,kBAAkB,EACxB,OAAO,GAAE;IAAE,aAAa,EAAE,IAAI,CAAA;CAA4B,GACzD,kBAAkB,CAAC,OAAO,CAAC,CAQ7B"}

package/dist/procedural-items/library-colors.js

@@ -69,14 +69,48 @@ export function nearestLibraryColorRef(hex, catalog = MATERIAL_CATALOG) {
         name: entry.label,
     })));
 }
+/** Deterministic finish/tone matching; uncertain colours keep their authored material. */
+export function matchPascalMaterial(slot) {
+    if (slot.emissive)
+        return null;
+    const name = (slot.name ?? '').replace(/([a-z])([A-Z])/g, '$1 $2').replace(/[_-]/g, ' ');
+    const finish = slot.finish ??
+        (slot.transparent || /\b(glass|glazing|glazed|transparent)\b/i.test(name)
+            ? 'glass'
+            : (slot.metalness ?? 0) >= 0.5 ||
+                /\b(metal|metallic|steel|stainless|chrome|brass|copper|bronze|aluminum|aluminium|iron)\b/i.test(name)
+                ? 'metal'
+                : /\b(wood|wooden|timber|lumber|oak|walnut|pine|cedar|cherry|teak|mahogany|maple|birch|beech|bamboo|plywood)\b/i.test(name)
+                    ? 'wood'
+                    : undefined);
+    if (finish === 'glass')
+        return 'library:preset-glass';
+    if (finish && finish !== 'color') {
+        return resolveProceduralFinishRef(finish, slot.color ?? '') ?? null;
+    }
+    if (!slot.color)
+        return null;
+    if (finish !== 'color') {
+        const wood = nearestColor(slot.color, FINISH_LIBRARY_REFS.wood);
+        // Colour alone only implies wood near a curated brown tone, on a non-glossy dielectric.
+        if (wood &&
+            wood.distance <= 8 &&
+            (slot.metalness ?? 0) < 0.2 &&
+            (slot.roughness ?? 1) >= 0.4 &&
+            !/\b(fabric|leather|plastic|rubber|paint|ceramic)\b/i.test(name))
+            return wood.ref;
+        if ((slot.metalness ?? 0) >= 0.2 || (slot.roughness ?? 1) < 0.4)
+            return null;
+    }
+    const color = nearestLibraryColorRef(slot.color);
+    return color && (finish === 'color' || color.distance <= 6) ? color.ref : null;
+}
 export function snapProceduralSlotsToLibrary(node, options = { keepOverrides: true }) {
     const slots = { ...node.slots };
     for (const slot of node.recipe.slots) {
         if (options.keepOverrides && Object.hasOwn(node.slots, slot.id))
             continue;
-        const ref = slot.finish
-            ? resolveProceduralFinishRef(slot.finish, slot.color)
-            : nearestLibraryColorRef(slot.color)?.ref;
+        const ref = matchPascalMaterial({ finish: slot.finish ?? 'color', color: slot.color });
         if (ref)
             slots[slot.id] = ref;
     }

package/dist/procedural-items/motion-controller.d.ts

@@ -0,0 +1,29 @@
+import { type EvaluatedMotion, motionTimeline } from './recipe.js';
+export type MotionCommand = {
+    sequence: number;
+    scope: 'all' | {
+        partId: string;
+    };
+    target: boolean;
+};
+export declare class ProceduralMotionController {
+    readonly motions: readonly EvaluatedMotion[];
+    readonly timeline: ReturnType<typeof motionTimeline>;
+    private collective;
+    private parts;
+    private spins;
+    private targets;
+    private sequence;
+    constructor(motions: readonly EvaluatedMotion[], initial?: Record<string, boolean>);
+    command(command: MotionCommand): void;
+    tick(dt: number): {
+        times: Record<string, number>;
+        fractions: Record<string, number>;
+        spins: Record<string, {
+            phase: number;
+            speed: number;
+        }>;
+        pending: boolean;
+    };
+}
+//# sourceMappingURL=motion-controller.d.ts.map

package/dist/procedural-items/motion-controller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"motion-controller.d.ts","sourceRoot":"","sources":["../../src/procedural-items/motion-controller.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,eAAe,EAAsB,cAAc,EAAE,MAAM,UAAU,CAAA;AAEnF,MAAM,MAAM,aAAa,GAAG;IAC1B,QAAQ,EAAE,MAAM,CAAA;IAChB,KAAK,EAAE,KAAK,GAAG;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,CAAA;IACjC,MAAM,EAAE,OAAO,CAAA;CAChB,CAAA;AAID,qBAAa,0BAA0B;IASnC,QAAQ,CAAC,OAAO,EAAE,SAAS,eAAe,EAAE;IAR9C,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAC,OAAO,cAAc,CAAC,CAAA;IACpD,OAAO,CAAC,UAAU,CAAsB;IACxC,OAAO,CAAC,KAAK,CAA4B;IACzC,OAAO,CAAC,KAAK,CAAsD;IACnE,OAAO,CAAC,OAAO,CAA+C;IAC9D,OAAO,CAAC,QAAQ,CAAK;gBAGV,OAAO,EAAE,SAAS,eAAe,EAAE,EAC5C,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM;IAUvC,OAAO,CAAC,OAAO,EAAE,aAAa,GAAG,IAAI;IA8DrC,IAAI,CAAC,EAAE,EAAE,MAAM,GAAG;QAChB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;QAC7B,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;QACjC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE;YAAE,KAAK,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,MAAM,CAAA;SAAE,CAAC,CAAA;QACvD,OAAO,EAAE,OAAO,CAAA;KACjB;CAqDF"}