@energy8platform/golem 0.2.0 → 0.3.0

package/dist/lib/rig-gates.d.ts

@@ -0,0 +1,209 @@
+/** Brief-specific pass/fail measurements over the real evaluator and AnimationState. */
+import { z } from 'zod';
+import type { RigDocument } from './rig-format';
+export declare const GateConfig: z.ZodObject<{
+    animation: z.ZodString;
+    fps: z.ZodDefault<z.ZodNumber>;
+    requiredAnimations: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    motion: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        bone: z.ZodString;
+        channel: z.ZodDefault<z.ZodEnum<["position", "rotation"]>>;
+        space: z.ZodDefault<z.ZodEnum<["world", "local"]>>;
+        minAmplitude: z.ZodOptional<z.ZodNumber>;
+        maxSpeed: z.ZodOptional<z.ZodNumber>;
+        maxAcceleration: z.ZodOptional<z.ZodNumber>;
+        maxJerk: z.ZodOptional<z.ZodNumber>;
+        maxStep: z.ZodOptional<z.ZodNumber>;
+        maxSetupDrift: z.ZodOptional<z.ZodNumber>;
+        during: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
+    }, "strip", z.ZodTypeAny, {
+        bone: string;
+        channel: "rotation" | "position";
+        space: "local" | "world";
+        minAmplitude?: number | undefined;
+        maxSpeed?: number | undefined;
+        maxAcceleration?: number | undefined;
+        maxJerk?: number | undefined;
+        maxStep?: number | undefined;
+        maxSetupDrift?: number | undefined;
+        during?: [number, number] | undefined;
+    }, {
+        bone: string;
+        channel?: "rotation" | "position" | undefined;
+        space?: "local" | "world" | undefined;
+        minAmplitude?: number | undefined;
+        maxSpeed?: number | undefined;
+        maxAcceleration?: number | undefined;
+        maxJerk?: number | undefined;
+        maxStep?: number | undefined;
+        maxSetupDrift?: number | undefined;
+        during?: [number, number] | undefined;
+    }>, "many">>;
+    distances: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        a: z.ZodString;
+        b: z.ZodString;
+        min: z.ZodOptional<z.ZodNumber>;
+        max: z.ZodOptional<z.ZodNumber>;
+        minRatio: z.ZodOptional<z.ZodNumber>;
+        maxRatio: z.ZodOptional<z.ZodNumber>;
+        during: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
+    }, "strip", z.ZodTypeAny, {
+        b: string;
+        a: string;
+        during?: [number, number] | undefined;
+        min?: number | undefined;
+        max?: number | undefined;
+        minRatio?: number | undefined;
+        maxRatio?: number | undefined;
+    }, {
+        b: string;
+        a: string;
+        during?: [number, number] | undefined;
+        min?: number | undefined;
+        max?: number | undefined;
+        minRatio?: number | undefined;
+        maxRatio?: number | undefined;
+    }>, "many">>;
+    conditions: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        whenSlotVisible: z.ZodString;
+        bone: z.ZodString;
+        prop: z.ZodEnum<["x", "y", "rotation"]>;
+        space: z.ZodDefault<z.ZodEnum<["world", "local"]>>;
+        min: z.ZodOptional<z.ZodNumber>;
+        max: z.ZodOptional<z.ZodNumber>;
+        required: z.ZodDefault<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        bone: string;
+        prop: "x" | "y" | "rotation";
+        space: "local" | "world";
+        whenSlotVisible: string;
+        required: boolean;
+        min?: number | undefined;
+        max?: number | undefined;
+    }, {
+        bone: string;
+        prop: "x" | "y" | "rotation";
+        whenSlotVisible: string;
+        space?: "local" | "world" | undefined;
+        min?: number | undefined;
+        max?: number | undefined;
+        required?: boolean | undefined;
+    }>, "many">>;
+    transitions: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        from: z.ZodString;
+        to: z.ZodString;
+        fromTime: z.ZodDefault<z.ZodNumber>;
+        mix: z.ZodDefault<z.ZodNumber>;
+        maxStep: z.ZodNumber;
+        duration: z.ZodDefault<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        mix: number;
+        duration: number;
+        maxStep: number;
+        from: string;
+        to: string;
+        fromTime: number;
+    }, {
+        maxStep: number;
+        from: string;
+        to: string;
+        mix?: number | undefined;
+        duration?: number | undefined;
+        fromTime?: number | undefined;
+    }>, "many">>;
+}, "strict", z.ZodTypeAny, {
+    animation: string;
+    fps: number;
+    requiredAnimations: string[];
+    motion: {
+        bone: string;
+        channel: "rotation" | "position";
+        space: "local" | "world";
+        minAmplitude?: number | undefined;
+        maxSpeed?: number | undefined;
+        maxAcceleration?: number | undefined;
+        maxJerk?: number | undefined;
+        maxStep?: number | undefined;
+        maxSetupDrift?: number | undefined;
+        during?: [number, number] | undefined;
+    }[];
+    distances: {
+        b: string;
+        a: string;
+        during?: [number, number] | undefined;
+        min?: number | undefined;
+        max?: number | undefined;
+        minRatio?: number | undefined;
+        maxRatio?: number | undefined;
+    }[];
+    conditions: {
+        bone: string;
+        prop: "x" | "y" | "rotation";
+        space: "local" | "world";
+        whenSlotVisible: string;
+        required: boolean;
+        min?: number | undefined;
+        max?: number | undefined;
+    }[];
+    transitions: {
+        mix: number;
+        duration: number;
+        maxStep: number;
+        from: string;
+        to: string;
+        fromTime: number;
+    }[];
+}, {
+    animation: string;
+    fps?: number | undefined;
+    requiredAnimations?: string[] | undefined;
+    motion?: {
+        bone: string;
+        channel?: "rotation" | "position" | undefined;
+        space?: "local" | "world" | undefined;
+        minAmplitude?: number | undefined;
+        maxSpeed?: number | undefined;
+        maxAcceleration?: number | undefined;
+        maxJerk?: number | undefined;
+        maxStep?: number | undefined;
+        maxSetupDrift?: number | undefined;
+        during?: [number, number] | undefined;
+    }[] | undefined;
+    distances?: {
+        b: string;
+        a: string;
+        during?: [number, number] | undefined;
+        min?: number | undefined;
+        max?: number | undefined;
+        minRatio?: number | undefined;
+        maxRatio?: number | undefined;
+    }[] | undefined;
+    conditions?: {
+        bone: string;
+        prop: "x" | "y" | "rotation";
+        whenSlotVisible: string;
+        space?: "local" | "world" | undefined;
+        min?: number | undefined;
+        max?: number | undefined;
+        required?: boolean | undefined;
+    }[] | undefined;
+    transitions?: {
+        maxStep: number;
+        from: string;
+        to: string;
+        mix?: number | undefined;
+        duration?: number | undefined;
+        fromTime?: number | undefined;
+    }[] | undefined;
+}>;
+export type GateConfig = z.infer<typeof GateConfig>;
+export declare function runGates(doc: RigDocument, config: z.input<typeof GateConfig>): {
+    pass: boolean;
+    animation: string;
+    fps: number;
+    interval: number;
+    expected: number;
+    inspected: number;
+    metrics: Record<string, unknown>;
+    failures: string[];
+};

package/dist/lib/rig-mesh.d.ts

@@ -10,6 +10,7 @@ export interface TraceOptions {
     threshold?: number;
     tolerance?: number;
     margin?: number;
+    minIslandRatio?: number;
 }
 /**
  * Every separate opaque island's outline, simplified and offset, largest first. A layer is not always one blob —

package/dist/lib/rig-motion.d.ts

@@ -0,0 +1,22 @@
+/** Reusable authoring operations. All output is ordinary editable tracks and constraints. */
+import type { RigDocument } from './rig-format';
+/** Blend between neighbouring chain joints by projected distance along the polyline. */
+export declare function gradientWeights(doc: RigDocument, id: string, bones: string[]): RigDocument;
+/** Smooth through triangle adjacency; locked vertices are fixed boundary conditions. */
+export declare function smoothWeights(doc: RigDocument, id: string, iterations?: number, strength?: number, locked?: number[]): RigDocument;
+/** Rigid or mixed binding for a vertex selection or document-space rectangle. */
+export declare function pinWeights(doc: RigDocument, id: string, bone: string, vertices?: number[], region?: [number, number, number, number]): RigDocument;
+/** Switch following controls while preserving the evaluated world pose at the contact time. */
+export declare function attachToBone(doc: RigDocument, animation: string, bone: string, target: string, t: number): RigDocument;
+export interface SpringOptions {
+    driver: string;
+    driverProp?: "rotation" | "x" | "y";
+    bones: string[];
+    frequency?: number;
+    damping?: number;
+    gain?: number;
+    fps?: number;
+    maxAngle?: number;
+}
+/** Velocity-driven damped oscillator, baked at uniform times. No runtime simulation is needed. */
+export declare function bakeSecondary(doc: RigDocument, animation: string, opts: SpringOptions): RigDocument;

package/dist/lib/rig-qa.d.ts

@@ -0,0 +1,35 @@
+export declare const sha256: (data: string | Buffer) => string;
+export interface CaptureIdentity {
+    document: string;
+    assets: Record<string, string>;
+    renderer: string;
+    masks: Record<string, string>;
+}
+export interface RenderManifest {
+    version: 1;
+    rigFile: string;
+    capturedAt: string;
+    identity: CaptureIdentity;
+    animation: string | null;
+    transparent: boolean;
+    scale: number;
+    times: number[];
+    render: {
+        background?: string;
+        overlayBones: boolean;
+        onionSkin: boolean;
+        weightBone?: string;
+        debugFillMasks: Record<string, string>;
+        region?: [number, number, number, number];
+    };
+    frames: {
+        file: string;
+        sha256: string;
+    }[];
+}
+export declare function verifyRenderManifest(rigPath: string, framesDir: string, expected: {
+    animation?: string;
+    times: number[];
+    renderer: string;
+    transparent?: boolean;
+}): Promise<RenderManifest>;

package/dist/lib/rig-quality.d.ts

@@ -0,0 +1,12 @@
+/** Motion diagnostics describe measured evidence; semantic rules are supplied by the brief. */
+import type { Animation, RigDocument } from './rig-format';
+import type { Finding } from './rig-check';
+export interface QualityOptions {
+    secondaryBones?: string[];
+    /** [foreground, background] slot pairs from the art brief, e.g. face above scarf. */
+    frontOf?: [string, string][];
+    /** Attachment → named normalized image coordinates (0..1). */
+    landmarks?: Record<string, Record<string, [number, number]>>;
+    landmarkTolerance?: number;
+}
+export declare function motionQuality(doc: RigDocument, anim: Animation, opts?: QualityOptions): Finding[];

package/dist/lib/rig-runtime.d.ts

@@ -14,6 +14,8 @@ import { type Pose, type Affine } from "./rig-anim";
 import { AnimationState, type PlayResult } from "./rig-state";
 /** vertices per axis of a lattice-deformed region's render mesh (8 segments) */
 export declare const MESH_GRID = 9;
+/** the least alpha an editor-selected slot is drawn with, so a part faded out at rest can still be seen */
+export declare const GHOST_ALPHA = 0.5;
 export interface PlayOptions {
     loop?: boolean;
     /** crossfade seconds from current pose */
@@ -38,9 +40,14 @@ export declare class RigPlayer {
     private pages;
     /** slots the editor hides; honoured by setPose */
     private hidden;
-    /** `mix`: default crossfade seconds for state transitions (setBase, completion → base); play() passes its own */
+    /** slots the editor has selected; setPose draws them at GHOST_ALPHA at least */
+    private ghosts;
+    private clipGraphics;
+    /** Default crossfade is 0.18 seconds; explicit mix: 0 requests a hard cut. */
     constructor(doc: RigDocument, textures: Map<string, Texture>, opts?: {
         mix?: number;
+        missingAnimation?: "warn" | "throw";
+        onWarning?: (message: string) => void;
     });
     /** whole atlas page as a plain texture (identity uv mapping) for skinned meshes */
     private pageTexture;
@@ -53,6 +60,8 @@ export declare class RigPlayer {
     updateDoc(doc: RigDocument): void;
     /** Editor-only: hide a slot's display object regardless of the pose (restored by passing `true`). */
     setSlotVisible(slotId: string, visible: boolean): void;
+    /** Editor-only: draw these slots at GHOST_ALPHA at least, whatever the pose says (an empty list clears it). */
+    setGhostSlots(slotIds: Iterable<string>): void;
     /** Stop playback and immediately restore the complete setup pose. */
     stop(): void;
     /** dt in seconds */

package/dist/lib/rig-state.d.ts

@@ -30,6 +30,7 @@ export interface PlayOptions {
 }
 export declare class AnimationState {
     private readonly sink;
+    private readonly opts;
     onEvent?: (name: string, payload?: Record<string, unknown>) => void;
     private base?;
     private main?;
@@ -45,6 +46,8 @@ export declare class AnimationState {
     private readonly defaultMix;
     constructor(sink: PoseSink, opts?: {
         mix?: number;
+        missingAnimation?: "warn" | "throw";
+        onWarning?: (message: string) => void;
     });
     /** id of the animation currently shown (main, else base) */
     get current(): string | undefined;

package/dist/lib/rig-tools.d.ts

@@ -85,7 +85,10 @@ export declare function placeAsset(doc: Doc, p: {
     z?: number;
 }): Doc;
 /** Parts-first regeneration prompt for one layer: style anchor + provenance + rig context + chroma-key rules. */
-export declare function layerPrompt(doc: Doc, assetId: string): string;
+export declare function layerPrompt(doc: Doc, assetId: string, opts?: {
+    method?: "part" | "repair";
+    removed?: string[];
+}): string;
 export type MetaPatch = {
     name?: string;
     width?: number;
@@ -200,6 +203,7 @@ export declare function addIkChain(doc: Doc, bone: string, opts?: {
     target?: string;
     mix?: number;
     softness?: number;
+    bones?: string[];
 }): {
     doc: Doc;
     chain: string[];