@energy8platform/golem 0.2.1 → 0.5.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;
+        min?: number | undefined;
+        max?: number | undefined;
+        during?: [number, number] | undefined;
+        minRatio?: number | undefined;
+        maxRatio?: number | undefined;
+    }, {
+        b: string;
+        a: string;
+        min?: number | undefined;
+        max?: number | undefined;
+        during?: [number, 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;
+        min?: number | undefined;
+        max?: number | undefined;
+        space?: "local" | "world" | 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;
+        min?: number | undefined;
+        max?: number | undefined;
+        during?: [number, 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;
+        min?: number | undefined;
+        max?: number | undefined;
+        during?: [number, number] | undefined;
+        minRatio?: number | undefined;
+        maxRatio?: number | undefined;
+    }[] | undefined;
+    conditions?: {
+        bone: string;
+        prop: "x" | "y" | "rotation";
+        whenSlotVisible: string;
+        min?: number | undefined;
+        max?: number | undefined;
+        space?: "local" | "world" | 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

@@ -8,8 +8,8 @@
  * - play/tick/stop are a thin wrapper over an AnimationState (see rig-state.ts) kept for simple consumers
  *   (harness, viewer). Games should drive `state` directly for queues, priorities and overlays.
  */
-import { Container, Texture } from "pixi.js";
-import { type RigDocument, type Asset } from "./rig-format";
+import { Container, Sprite, Mesh, MeshPlane, Texture } from "pixi.js";
+import { type RigDocument, type Slot, type Attachment, type Asset } from "./rig-format";
 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) */
@@ -23,6 +23,22 @@ export interface PlayOptions {
     onComplete?: () => void;
     onEvent?: (name: string, payload?: Record<string, unknown>) => void;
 }
+export interface RigRenderItem {
+    att: Attachment;
+    slot: Slot;
+    node: Sprite | MeshPlane | Mesh;
+    /** lattice-deformed region */
+    lattice?: {
+        plane: MeshPlane;
+        offsets: Float64Array;
+        applied: Float64Array;
+    };
+    /** skinned mesh */
+    skinned?: {
+        mesh: Mesh;
+        positions: Float32Array;
+    };
+}
 /** Build the asset-id → Texture map, loading each `src` once and cutting atlas frames (with rotation and trim). */
 export declare function createTextures(doc: RigDocument, loadSource: (src: string) => Promise<Texture>): Promise<Map<string, Texture>>;
 /**
@@ -32,9 +48,17 @@ export declare function createTextures(doc: RigDocument, loadSource: (src: strin
 export declare function atlasUV(asset: Asset, u: number, v: number, sourceW: number, sourceH: number): [number, number];
 export declare class RigPlayer {
     doc: RigDocument;
+    private inputPose;
+    private controlOverrides;
+    /** Manual inputs override animated controls until resetControls; values are clamped to declared ranges. */
+    setControls(values: Record<string, number>): void;
+    resetControls(): void;
     readonly view: Container<import("pixi.js").ContainerChild>;
     readonly state: AnimationState;
     private items;
+    private beforePose;
+    private afterPose;
+    private clipPoints;
     private skel;
     private textures;
     private pages;
@@ -42,10 +66,26 @@ export declare class RigPlayer {
     private hidden;
     /** slots the editor has selected; setPose draws them at GHOST_ALPHA at least */
     private ghosts;
-    /** `mix`: default crossfade seconds for state transitions (setBase, completion → base); play() passes its own */
+    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;
     });
+    /** Read-only render handles for in-page tools. Nodes remain owned by the player. */
+    get renderItems(): readonly Readonly<RigRenderItem>[];
+    /** Current document-space clipping polygons, keyed by path attachment id. */
+    get clipPolygons(): ReadonlyMap<string, readonly number[]>;
+    /**
+     * Modify resolved control outputs before skeleton evaluation, constraints and skinning.
+     * Callbacks run in registration order, each with its own map. Change control inputs via setControls.
+     */
+    onBeforePose(callback: (pose: Pose) => Pose): () => void;
+    /** Subscribe after the base pose has been rebuilt. Return value removes the callback. */
+    onAfterPose(callback: (player: RigPlayer) => void): () => void;
+    /** Rebuild the current pose without advancing playback; useful for reversible overlays. */
+    refreshPose(): void;
     /** whole atlas page as a plain texture (identity uv mapping) for skinned meshes */
     private pageTexture;
     /** Replace whatever is playing (no queueing). Resolves when the animation completes or is replaced. */

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[];

package/dist/lib/runtime.d.ts

@@ -2,8 +2,10 @@
  * `@energy8platform/golem/runtime` — the browser half: play a rig document in PixiJS v8.
  * Depends on pixi.js (peer) and zod only; no node, no tools, no editor.
  */
-export { RigPlayer, createTextures, atlasUV, MESH_GRID, type PlayOptions } from "./rig-runtime";
+export { RigPlayer, createTextures, atlasUV, MESH_GRID, type PlayOptions, type RigRenderItem } from "./rig-runtime";
 export { RigSymbol, type RigSymbolOptions, type SymbolSize, type SymbolViewLike, type TickerLike } from "./rig-symbol";
 export { AnimationState, type PlayResult, type PoseSink } from "./rig-state";
 export { parse, validate, migrateV1, RigDocument as RigDocumentSchema } from "./rig-format";
 export type { RigDocument, Bone, Slot, Asset, Attachment, Animation, Track, Key } from "./rig-format";
+export type { RigControl, ControlBinding } from "./rig-format";
+export { controlPose, resolveControls, sampleBinding } from "./rig-controls";