@energy8platform/golem 0.1.0

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

@@ -0,0 +1,21 @@
+import type { RigDocument } from "./rig-format";
+export declare function historyDir(rigPath: string): string;
+/** oldest → newest absolute paths */
+export declare function listHistory(rigPath: string): Promise<string[]>;
+export declare const redoDir: (rigPath: string) => string;
+/** oldest → newest absolute paths of redo entries */
+export declare function listRedo(rigPath: string): Promise<string[]>;
+/** Discard every redo entry (invoked whenever a new mutation is pushed). */
+export declare function clearRedo(rigPath: string): Promise<void>;
+/** Store `contents` as the newest snapshot; keeps the last `keep`. A new mutation invalidates redo unless `keepRedo`. */
+export declare function pushHistory(rigPath: string, contents: string, keep?: number, opts?: {
+    keepRedo?: boolean;
+}): Promise<string>;
+/** Contents of the `steps`-th newest snapshot; it and everything newer are discarded. */
+export declare function popHistory(rigPath: string, steps?: number): Promise<string>;
+/** Undo `steps` mutations: the current file goes to the redo stack; returns the contents to write back. */
+export declare function undo(rigPath: string, steps?: number): Promise<string>;
+/** Redo the last undo: returns the contents to write back; the pre-redo state is snapshotted into history. */
+export declare function redo(rigPath: string): Promise<string>;
+/** Human-readable structural difference; empty when the documents are identical. */
+export declare function diffDocs(a: RigDocument, b: RigDocument): string[];

package/dist/lib/rig-import-layers.d.ts

@@ -0,0 +1,32 @@
+import { type RigDocument } from "./rig-format";
+type Doc = RigDocument;
+/**
+ * Optional sidecar `layers.json` in the layers dir (written by the segmentation step):
+ *   [{ "file": "arm_l.png", "id": "arm_l", "role": "arm_l", "parent": "torso", "z": 3,
+ *      "bbox": [x, y, w, h], "joint": [x, y], "inpainted": true, "prompt": "..." }]
+ * Without it: every PNG is a full-canvas layer, id/role from filename (`03_arm_l.png` → z=3, id=arm_l).
+ * Layers are assumed to share the document canvas size unless bbox is given.
+ */
+export interface LayerSpec {
+    file: string;
+    id?: string;
+    role?: string;
+    parent?: string;
+    z?: number;
+    bbox?: [number, number, number, number];
+    joint?: [number, number];
+    inpainted?: boolean;
+    prompt?: string;
+    sourceImage?: string;
+    /** swap patch (closed eyes, mouth shape): no bone of its own, slot on `parent`'s bone, hidden until an animation shows it */
+    swap?: boolean;
+    /** attach to this existing bone instead of creating one (accessory drawn with the bone, e.g. a hat on `head`) */
+    bone?: string;
+    /** slot id for swap layers; several assets with the same `slot` become one hidden slot (mouth shapes) */
+    slot?: string;
+    /** blend mode of the slot (`add` for glow/fire layers painted on black) */
+    blend?: "normal" | "add" | "multiply" | "screen";
+}
+export declare function pngSize(buf: Buffer): [number, number];
+export declare function importLayers(doc: Doc, dir: string, relPrefix?: string): Promise<Doc>;
+export {};

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

@@ -0,0 +1,9 @@
+/**
+ * Write `value` as pretty JSON to `path`, atomically. The temp file is a SIBLING — a rename across devices is
+ * neither atomic nor guaranteed to work — named so the editor watcher's basename filter ignores it (and matched
+ * by `.gitignore`'s `.*.tmp`, so a crash between the write and the rename cannot leave a tracked stray behind).
+ * A failed write removes it rather than leaving it around.
+ */
+/** Write `data` to `path` atomically — the temp-sibling-then-rename dance `saveJson` documents above. */
+export declare function saveBytes(path: string, data: Buffer | string): Promise<void>;
+export declare const saveJson: (path: string, value: unknown) => Promise<void>;

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

@@ -0,0 +1,2 @@
+import type { AlphaMask } from "./rig-mesh";
+export declare function alphaMaskFromPng(buf: Buffer, frame?: [number, number, number, number]): AlphaMask;

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

@@ -0,0 +1,143 @@
+import { type Skeleton } from "./rig-anim";
+import type { RigDocument, MeshAttachment, RegionAttachment, Asset } from "./rig-format";
+export interface AlphaMask {
+    width: number;
+    height: number;
+    alpha: Uint8Array;
+}
+export type Pt = [number, number];
+export interface TraceOptions {
+    threshold?: number;
+    tolerance?: number;
+    margin?: number;
+}
+/**
+ * Every separate opaque island's outline, simplified and offset, largest first. A layer is not always one blob —
+ * a closed-eyes overlay is two strokes, a dashed outfit trim is a dozen — and meshing only the biggest one drops
+ * the rest of the image silently. Holes (a loop wound against the largest loop's orientation, e.g. the inside of
+ * a ring) are dropped, as is any island under `MIN_ISLAND_AREA` of the largest.
+ */
+export declare function traceHulls(mask: AlphaMask, opts?: TraceOptions): Pt[][];
+/** the outline of the largest opaque island only — `traceHulls` when every island matters */
+export declare function traceHull(mask: AlphaMask, opts?: TraceOptions): Pt[];
+export declare function signedArea(p: Pt[]): number;
+export declare function pointInPolygon(poly: Pt[], x: number, y: number): boolean;
+export declare function distanceToPolygon(poly: Pt[], x: number, y: number): number;
+export declare function interiorPoints(hull: Pt[], spacing: number): Pt[];
+/** hull edges longer than `spacing` are subdivided so the outline survives Delaunay; outside triangles are culled */
+export declare function triangulate(hull: Pt[], interior: Pt[], spacing: number): {
+    vertices: number[];
+    triangles: number[];
+    hull: number;
+};
+/** `minArea`: ignore a flipped triangle whose rest-pose area (px²) is below this — hairline slivers flip sign from
+ * rounding noise alone and aren't a real fold. Default 0 keeps every flip (the pre-existing behaviour). */
+export declare function foldedTriangles(rest: number[], world: number[], triangles: number[], minArea?: number): number[];
+/** signed area of triangle (a, b, c) of a flat [x, y, …] vertex array — negative when it winds the other way */
+export declare const triangleArea: (v: number[], a: number, b: number, c: number) => number;
+/** total area of a mesh's triangles in the given vertex positions — the denominator for "how much of it folded" */
+export declare function meshArea(vertices: number[], triangles: number[]): number;
+/**
+ * World positions of a mesh's REST shape under the given skeleton — `attachmentWorldVertices` with the pose's
+ * deform offsets left out, which is what auto-weighting and the weight brush measure distances against (a mesh
+ * is skinned to where its rest vertices are, not to where a deform key happens to have pushed them).
+ */
+export declare function meshWorldVertices(skel: Skeleton, slotId: string, att: MeshAttachment): number[];
+/** 6 decimals, the precision rest shapes, weights and deform offsets are written at — what rig.json keeps
+ * (`+ 0` turns a rounded -0 back into 0). Shared with the registry tools, the editor's gizmos and verify-mesh. */
+export declare const round6: (v: number) => number;
+/**
+ * region → mesh over already-traced islands: each island is filled with an interior grid and triangulated on its
+ * own, then the islands are concatenated with their triangle indices offset. uvs are x/imgW, y/imgH; vertices are
+ * slot-bone local, through the region placement.
+ * `hull` (the leading vertices that form THE outline) only makes sense for a single island, so a multi-island
+ * mesh reports 0 — consumers then treat every vertex as outline, which is right when there is more than one.
+ */
+export declare function meshFromIslands(islands: Pt[][], region: RegionAttachment, asset: Asset, mask: {
+    width: number;
+    height: number;
+}, spacing?: number): MeshAttachment;
+/** region → mesh: every opaque island's outline + an interior grid, triangulated (see `traceHulls`, `meshFromIslands`) */
+export declare function meshFromMask(mask: AlphaMask, region: RegionAttachment, asset: Asset, opts?: {
+    spacing?: number;
+    tolerance?: number;
+    margin?: number;
+    threshold?: number;
+}): MeshAttachment;
+/** `radius` is the falloff's distance scale, in world px — see `autoWeights` */
+export interface AutoWeightsOptions {
+    bones: string[];
+    radius: number;
+    maxInfluences: number;
+}
+/** normalized weights below this are dropped rather than kept as a dead influence that rounds to 0 in the file */
+export declare const MIN_AUTO_WEIGHT = 0.000001;
+/** default candidates: the slot's bone, its parent, its direct children */
+export declare function defaultWeightBones(doc: RigDocument, slotId: string): string[];
+/**
+ * Inverse-distance skinning. For every vertex: the distance `d` to each candidate bone's segment (joint → joint +
+ * length along x; length 0 = a point), weight `1 / (d/radius + 1)²`, top-K by weight, normalized; influences hold
+ * the vertex in each bone's local space.
+ *
+ * `radius` scales the falloff: it is the distance, in world px, at which the weight has fallen to 1/4 of its
+ * value at the joint. `1` reproduces the historical law `1 / (d + 1px)²` exactly — which is why it is the
+ * default, and omitting `radius` changes nothing. A larger radius flattens the curve, so bones farther away keep
+ * a meaningful share; a smaller one sharpens it, so the nearest bone dominates within a few px.
+ *
+ * There is deliberately no cutoff at any radius: every candidate bone keeps a nonzero share, however far past
+ * `radius` it sits. A hard cutoff is what this replaced, and it was worse than useless — the middle of a limb
+ * sat beyond `radius` of both of its joints (the old default was half the mesh's extent), so it had no bone in
+ * range at all and had to snap to its single nearest bone at w=1; neighbouring vertices snapping to *different*
+ * bones is a hard seam with no blend, and it flips the triangles between them as soon as those bones
+ * counter-rotate.
+ */
+export declare function autoWeights(doc: RigDocument, skel: Skeleton, att: MeshAttachment, opts: AutoWeightsOptions): MeshAttachment;
+/**
+ * What the fitting and deform math below actually reads: the slot the points live in, plus the `VertexData` a
+ * mesh and a PATH carry identically (`vertices`, or `weights` skinned to bones). Neither cares which of the two
+ * it was handed — a path attachment is skinned exactly like a mesh, vertex for vertex.
+ */
+export type VertexAttachment = Pick<MeshAttachment, "slot" | "vertices" | "weights">;
+/** one rest shape, never both — what a vertex gesture commits and what `rig_set_mesh` / `rig_set_path_attachment` take */
+export type VertexPatch = {
+    vertices: number[];
+    weights?: undefined;
+} | {
+    weights: NonNullable<MeshAttachment["weights"]>;
+    vertices?: undefined;
+};
+/**
+ * How many CONTROL POINTS a mesh or a path holds: one influence list each when skinned, two numbers of
+ * `vertices` each when not. The same count for both shapes, in one place — the gizmo, the anchor tool, the tree's
+ * delete and the properties panel all ask it, and a copy that got the weighted branch wrong would read half a
+ * skinned path as a whole one.
+ */
+export declare const vertexCount: (att: Pick<VertexAttachment, "vertices" | "weights">) => number;
+/**
+ * New local data so the attachment's vertices sit at `targetWorld` (flat, all vertices) under `skel`:
+ * `vertices` → slot-bone local; `weights` → every influence's x,y re-expressed in its bone.
+ *
+ * @deprecated Not the way to MOVE a vertex — `deformOffsetsFor` plus `VertexGizmo.shift` is, and this has no
+ * caller left in the project. Kept for a future "normalize this attachment's vertices to these positions", which
+ * is what it actually is; every gesture that reached for it collapsed the per-bone spread instead.
+ *
+ * A skinned vertex's influences do not
+ * generally agree on where it is (Spine's rarely do, and `blendInfluences` disagrees on purpose), and re-deriving
+ * them all from one world point throws that spread away for a position that only matches in the pose `skel` is
+ * in — measured at 489 px of animated drift on `ross`'s `n_fur` for a 0.01 px setup nudge.
+ */
+export declare function fitVertices(skel: Skeleton, att: VertexAttachment, targetWorld: number[]): VertexPatch;
+/** flat offset length for an attachment: 2·n unweighted, 2·Σ influences weighted */
+export declare const deformLength: (att: VertexAttachment) => number;
+/** deform offsets (format of the `vertices` key) that move vertex `index` by `worldDelta`, starting from `base` (or zeros) */
+export declare function deformOffsetsFor(skel: Skeleton, att: VertexAttachment, base: number[] | undefined, index: number, worldDelta: [number, number]): number[];
+export interface BrushOptions {
+    bone: string;
+    center: [number, number];
+    radius: number;
+    strength: number;
+    maxInfluences: number;
+    slotBone: string;
+}
+/** add strength·(1 − d/radius) of `bone` to vertices within radius (negative strength removes), renormalize, keep top-K; a vertex left without influences gets the slot bone at 1 */
+export declare function paintWeights(skel: Skeleton, att: MeshAttachment, world: number[], opts: BrushOptions): MeshAttachment;

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

@@ -0,0 +1,101 @@
+/**
+ * rig-path — pure geometry for path attachments: splitting a curve without changing its shape, blending
+ * influence lists, curve lengths and hit-testing. Shared by the registry tools and the editor. No node:*, no DOM.
+ *
+ * Control-point layout, fixed by the format and verified against spine-core: vertex i*3+1 is anchor i, its
+ * triple is [cPrev, p, cNext], and curve i runs p_i → cNext_i → cPrev_{i+1} → p_{i+1}. The index wrapping a
+ * CLOSED path needs is taken from `samplePath` (rig-anim.ts) rather than derived again here: that sampler is
+ * pinned against the spine-core runtime, so it is what these control points mean.
+ */
+import type { Pt } from "./rig-constraints";
+import type { Influence } from "./rig-format";
+/** flat [x, y, …] ↔ point pairs — the format stores flat arrays, the geometry below reads points */
+export declare const toPoints: (flat: number[]) => Pt[];
+export declare const flatten: (pts: Pt[]) => number[];
+/** anchors of a path: the vertices at 1, 4, 7, … (`vertexCount` counts POINTS, not numbers) */
+export declare const anchorCount: (vertexCount: number) => number;
+/** curves of a path: one per anchor when closed (the last wraps), one fewer when open */
+export declare const curveCount: (vertexCount: number, closed: boolean) => number;
+/** point on the cubic bezier through p0..p3 at parameter t */
+export declare function bezierPointAt(p0: Pt, p1: Pt, p2: Pt, p3: Pt, t: number): Pt;
+/** cubic bezier length, approximated by 8 chords (the curve bulges outward, so this runs a few % longer than the straight p0→p3 chord) */
+export declare function bezierLength(p0: Pt, p1: Pt, p2: Pt, p3: Pt, chords?: number): number;
+/** the point of curve `i` at parameter `t`, in whatever space `worldPoints` are given in (same wrapping as `samplePath`) */
+export declare const pathPointAt: (worldPoints: number[], i: number, t: number) => Pt;
+/**
+ * Cumulative curve lengths of a path in the space its points are given in — one entry per curve, which is the
+ * convention `pathFromPoints` writes. (A Spine-imported OPEN path carries one entry more; `pathLength` reads
+ * `lengths` by curve index, so shortening to one-per-curve loses nothing, and with `constantSpeed` on the
+ * runtime measures the posed curve and never reads these at all.)
+ */
+export declare function curveLengths(worldPoints: number[], closed: boolean): number[];
+/**
+ * De Casteljau split of curve `i` at `t`: the five control points the split changes or adds, in world space.
+ * The two halves p0 → a → d → f and f → e → c → p3 are, together, the ORIGINAL curve — exactly, not to some
+ * tolerance — so inserting an anchor this way moves nothing that was already drawn.
+ *
+ * `coeffs` are the affine coefficients of those five points over the curve's own four control points
+ * `[p_i, cNext_i, cPrev_{i+1}, p_{i+1}]`, in the order `[cNextI, triple[0], triple[1], triple[2], cPrevNext]`.
+ * Each row sums to 1 and is non-negative for t in (0, 1), so a WEIGHTED path can rebuild the five influence
+ * lists from the four it already has (`blendInfluences`) and stay skinned to the same bones.
+ */
+export declare function splitCurve(worldPoints: number[], closed: boolean, i: number, t: number): {
+    cNextI: Pt;
+    triple: [Pt, Pt, Pt];
+    cPrevNext: Pt;
+    coeffs: number[][];
+};
+/**
+ * Apply a `splitCurve` to a list with ONE ENTRY PER CONTROL POINT: `cNext_i` and `cPrev_{i+1}` are replaced
+ * (the split moves them) and the new anchor's `[cPrev, p, cNext]` triple goes in between. The point array, the
+ * local `vertices` and the `weights` lists are all this shape and must stay in step, so they share this.
+ * On a closed path the last curve's `cPrev_{i+1}` is entry 0 and the triple appends at the end — the same
+ * wrapping `curveOf` reads the curve with.
+ */
+export declare function insertTriple<T>(items: T[], i: number, cNextI: T, triple: [T, T, T], cPrevNext: T): T[];
+/** drop anchor `i`'s whole `[cPrev, p, cNext]` triple from a per-control-point list */
+export declare function removeTriple<T>(items: T[], i: number): T[];
+/**
+ * Blend skinned control points by affine coefficients: the WHOLE influence list, positions included.
+ *
+ * Under linear blend skinning a control point sits at `P_k = Σ_j w_kj · W_j(q_kj)`, so the affine combination
+ * `P' = Σ_k c_k · P_k` expands — every bone matrix `W_j` being affine — into a control point of the same form:
+ *
+ *     w'_j = Σ_k c_k · w_kj                 q'_j = Σ_k c_k · w_kj · q_kj / w'_j
+ *
+ * That is an identity in the bone matrices, so the blended point follows `P'` in EVERY pose, which is the only
+ * thing worth having: a split anchor that is right at rest and wrong the moment the bones move has preserved
+ * nothing. Mapping the blended WORLD point back through each bone's inverse instead — what `fitVertices` does,
+ * correctly, for its own job of fitting existing influences to one target position — agrees with this only
+ * where the bones stand in their setup pose. On ross's posed tail that route drifts by ~50 px.
+ *
+ * `coeffs` must sum to 1 (affine, not linear) and each source list must already be normalized.
+ */
+export declare function blendInfluences(sources: Influence[][], coeffs: number[]): Influence[];
+/**
+ * The DEFORM OFFSETS of a blended control point — the same `Σ c·w·d / w'` its rest positions get, and for the
+ * same reason. An offset adds to the stored position INSIDE each bone's frame (`attachmentWorldVertices` poses
+ * `q_kj + d_kj`), so a deformed control point is `Σ_j w_kj · W_j(q_kj + d_kj)`; running the derivation in
+ * `blendInfluences` over that instead of over `q` alone gives back the very same identity with `q + d` in place
+ * of `q`, and subtracting the rest half leaves `d'_j = Σ_k c_k·w_kj·d_kj / w'_j`. The blended anchor therefore
+ * sits on the DEFORMED curve in every pose exactly as its rest position sits on the rest curve — and, the blend
+ * being linear in `d`, at every time between two keys as well, not only on them.
+ *
+ * `sources` are the same four influence lists the positions blend from and `chunks` their offset pairs in the
+ * same order, so the result is aligned to `blendInfluences(sources, coeffs)` influence for influence: the weights
+ * decide which bones survive and in what order, and they are identical in both calls.
+ */
+export declare function blendOffsets(sources: Influence[][], chunks: number[][], coeffs: number[]): number[];
+/** the same blend for an UNWEIGHTED path, where a control point is one pair in the slot bone's space */
+export declare const blendPairs: (chunks: number[][], coeffs: number[]) => number[];
+/**
+ * Nearest point on the POSED curve: which curve, its parameter, and the world distance — so the caller can
+ * apply its own pick threshold (a click far from the curve is a miss, not a very bad hit).
+ * 16 samples per curve locate the minimum, then 8 rounds of golden-section refine it inside the bracket its
+ * two neighbours make — down to ~1/350 of a curve, well under a pixel on any curve a user can see.
+ */
+export declare function nearestOnPath(worldPoints: number[], closed: boolean, p: Pt): {
+    curve: number;
+    t: number;
+    d: number;
+};

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

@@ -0,0 +1,101 @@
+/**
+ * rig-presets v1 — parametric animation generators.
+ *
+ * A preset = (doc, params) → Animation. The Animation keeps `preset: {name, params}`
+ * so an agent can re-tune params instead of editing keys.
+ * Presets pick bones by `role`; missing roles are skipped, root is the fallback.
+ * Image deformation (rig-deform.ts) goes through `deform` tracks on slots: breathing bulges the torso
+ * image with the neck and waist pinned instead of scaling the torso bone (which stretched children).
+ */
+import type { RigDocument, Animation } from "./rig-format";
+export interface Preset<P> {
+    name: string;
+    defaults: P;
+    build(doc: RigDocument, params: P): Animation;
+}
+export interface IdleBreathingParams {
+    id: string;
+    period: number;
+    amplitude: number;
+    headBob: number;
+    armSway: number;
+}
+export declare const idleBreathing: Preset<IdleBreathingParams>;
+export interface WinBounceParams {
+    id: string;
+    duration: number;
+    height: number;
+    bounces: number;
+    squash: number;
+}
+export declare const winBounce: Preset<WinBounceParams>;
+export interface AnticipationShakeParams {
+    id: string;
+    duration: number;
+    amplitude: number;
+    frequency: number;
+    grow: boolean;
+    scaleUp: number;
+}
+export declare const anticipationShake: Preset<AnticipationShakeParams>;
+export interface BlinkParams {
+    id: string;
+    slot: string;
+    closed?: string;
+    period: number;
+    hold: number;
+}
+export declare const blink: Preset<BlinkParams>;
+export interface MouthTalkParams {
+    id: string;
+    slot: string;
+    frames: (string | null)[];
+    rate: number;
+    duration: number;
+}
+export declare const mouthTalk: Preset<MouthTalkParams>;
+export interface DimParams {
+    id: string;
+    alpha: number;
+    duration: number;
+}
+export declare const dim: Preset<DimParams>;
+export interface SymbolIdleParams {
+    id: string;
+    period: number;
+    float: number;
+    pulse: number;
+    tilt: number;
+}
+export declare const symbolIdle: Preset<SymbolIdleParams>;
+export interface SymbolWinParams {
+    id: string;
+    duration: number;
+    pop: number;
+    wobble: number;
+    wobbles: number;
+}
+export declare const symbolWin: Preset<SymbolWinParams>;
+export interface WeightShiftParams {
+    id: string;
+    period: number;
+    shift: number;
+    lean: number;
+    dip: number;
+}
+/** Idle variation: hips sway sideways, torso leans against it, legs pivot so the feet stay planted (asin(shift/leg length)). */
+export declare const weightShift: Preset<WeightShiftParams>;
+export declare const presets: {
+    readonly idle_breathing: Preset<IdleBreathingParams>;
+    readonly win_bounce: Preset<WinBounceParams>;
+    readonly anticipation_shake: Preset<AnticipationShakeParams>;
+    readonly blink: Preset<BlinkParams>;
+    readonly mouth_talk: Preset<MouthTalkParams>;
+    readonly dim: Preset<DimParams>;
+    readonly symbol_idle: Preset<SymbolIdleParams>;
+    readonly symbol_win: Preset<SymbolWinParams>;
+    readonly weight_shift: Preset<WeightShiftParams>;
+};
+export type PresetName = keyof typeof presets;
+/** Build an animation from a preset name + partial params, replacing any animation with the same id. */
+export declare function applyPreset(doc: RigDocument, name: PresetName, params?: Record<string, unknown>): RigDocument;

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

@@ -0,0 +1,2 @@
+/** Reentrant so an HTTP transaction can call the same registry used directly by MCP and CLI. */
+export declare function withRigQueue<T>(path: string, op: () => Promise<T>): Promise<T>;

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

@@ -0,0 +1,70 @@
+/**
+ * rig-runtime v2 — PixiJS (v8) binding for `energy8.rig` documents.
+ *
+ * - Pose math lives in rig-anim.ts / rig-deform.ts (pure); this file only owns display objects.
+ * - One display object per attachment: region → Sprite (or a 9×9 MeshPlane when a lattice deform animates it),
+ *   mesh → Mesh with its own geometry, vertices skinned on the CPU every pose (positions in document space).
+ * - All display objects live in ONE flat container sorted by draw order (slot z, or the drawOrder track).
+ * - 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 { 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;
+export interface PlayOptions {
+    loop?: boolean;
+    /** crossfade seconds from current pose */
+    mix?: number;
+    onComplete?: () => void;
+    onEvent?: (name: string, payload?: Record<string, unknown>) => void;
+}
+/** 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>>;
+/**
+ * Atlas-space uv (0..1 over the source image) for a point given in original-image fractions,
+ * honouring frame, trim and 90° packing rotation.
+ */
+export declare function atlasUV(asset: Asset, u: number, v: number, sourceW: number, sourceH: number): [number, number];
+export declare class RigPlayer {
+    doc: RigDocument;
+    readonly view: Container<import("pixi.js").ContainerChild>;
+    readonly state: AnimationState;
+    private items;
+    private skel;
+    private textures;
+    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 */
+    constructor(doc: RigDocument, textures: Map<string, Texture>, opts?: {
+        mix?: number;
+    });
+    /** 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. */
+    play(animId: string, opts?: PlayOptions): Promise<PlayResult>;
+    /**
+     * Swap the document for pose evaluation without rebuilding display objects — valid only when slots/attachments
+     * keep their ids and types (the editor uses it during drags). Throws otherwise: rebuild the player.
+     */
+    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;
+    /** Stop playback and immediately restore the complete setup pose. */
+    stop(): void;
+    /** dt in seconds */
+    tick(dt: number): void;
+    /** Apply a pose (rest where silent) to the display objects. */
+    setPose(pose: Pose): void;
+    /** World-space bone positions — used by editor gizmos and renderPreview overlays */
+    bonePositions(): Record<string, {
+        x: number;
+        y: number;
+        rotation: number;
+    }>;
+    /** current world transforms (for tests and tools) */
+    get world(): Map<string, Affine>;
+}

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

@@ -0,0 +1,64 @@
+/**
+ * rig-state — animation state machine over a pose sink (RigPlayer, or anything with `setPose`).
+ *
+ * - base: the looping default (`idle`); shown whenever nothing else is active. A non-looping base holds its end pose.
+ * - main: one-shot (or forced loop) requests with priorities and a FIFO queue. Equal/higher priority interrupts,
+ *   lower priority queues (or is dropped). After completion → next queued, else base, else hold the last pose.
+ * - overlays: named independent loops whose keys override the shown pose (blink, mouth). Non-looping overlays
+ *   remove themselves when done.
+ * - crossfade: numbers blend from the last composed pose; discrete keys (attachment) hold until the mix ends.
+ * Every `play` promise resolves — a game can `await` it without risk of hanging.
+ */
+import type { RigDocument } from "./rig-format";
+import { type Pose } from "./rig-anim";
+export interface PoseSink {
+    doc: RigDocument;
+    setPose(pose: Pose): void;
+}
+export type PlayResult = "completed" | "interrupted" | "dropped" | "stopped";
+export interface PlayOptions {
+    /** default 0; a request interrupts the current one when its priority is >= */
+    priority?: number;
+    /** default: the animation's own `loop` */
+    loop?: boolean;
+    /** crossfade seconds from the current pose; default: the state's `mix` */
+    mix?: number;
+    /** what to do when a higher-priority animation is playing (default "queue") */
+    ifBusy?: "queue" | "drop" | "interrupt";
+    /** synchronous callback, in addition to the returned promise */
+    onComplete?: (result: PlayResult) => void;
+}
+export declare class AnimationState {
+    private readonly sink;
+    onEvent?: (name: string, payload?: Record<string, unknown>) => void;
+    private base?;
+    private main?;
+    private queue;
+    private overlays;
+    /** last composed pose without overlays — mix snapshots start here */
+    private pose;
+    private from?;
+    private mixLeft;
+    private mixTotal;
+    /** a mix begun in this update shows weight 0 for the frame it starts on */
+    private mixFresh;
+    private readonly defaultMix;
+    constructor(sink: PoseSink, opts?: {
+        mix?: number;
+    });
+    /** id of the animation currently shown (main, else base) */
+    get current(): string | undefined;
+    get baseId(): string | undefined;
+    private channel;
+    setBase(id?: string, opts?: {
+        mix?: number;
+    }): void;
+    play(id: string, opts?: PlayOptions): Promise<PlayResult>;
+    /** Independent loop on top of the shown pose; `undefined` removes it. */
+    setOverlay(name: string, id?: string): void;
+    /** Clear everything and show the setup pose. Pending plays resolve as "stopped". */
+    stop(): void;
+    update(dt: number): void;
+    private beginMix;
+    private advance;
+}

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

@@ -0,0 +1,60 @@
+/**
+ * rig-symbol — a rig as a slot symbol view for @energy8platform/game-engine (SymbolView, engine ≥ 0.43: square or rectangular cells).
+ *
+ * The interface is copied structurally (playIdle / playWin / showStatic / resize) so this package does not
+ * depend on the engine. Centred at the origin and scaled so the rig canvas fits the cell, like AnimatedSymbol.
+ * `setDim(on)` is an extra for non-winning symbols. Updated through a ticker (Ticker.shared by default).
+ */
+import { Container, type Texture } from "pixi.js";
+import { RigPlayer } from "./rig-runtime";
+import type { RigDocument } from "./rig-format";
+export interface TickerLike {
+    add(fn: (t: {
+        deltaMS: number;
+    }) => void): unknown;
+    remove(fn: (t: {
+        deltaMS: number;
+    }) => void): unknown;
+}
+/** a square cell (px) or a rectangular one, as the engine's SymbolView.resize takes */
+export type SymbolSize = number | {
+    width: number;
+    height: number;
+};
+export interface RigSymbolOptions {
+    /** cell size in px: a number scales the larger canvas side to it, a rectangle fits the canvas inside it */
+    size: SymbolSize;
+    /** animation ids to use; missing ones are skipped gracefully */
+    animations?: {
+        idle?: string;
+        win?: string;
+        dim?: string;
+    };
+    /** crossfade seconds between states (default 0.15) */
+    mix?: number;
+    ticker?: TickerLike;
+}
+/** structural copy of the engine's SymbolView */
+export interface SymbolViewLike extends Container {
+    playIdle?(): void;
+    playWin?(): Promise<void>;
+    showStatic?(): void;
+    resize?(size: SymbolSize): void;
+}
+export declare class RigSymbol extends Container implements SymbolViewLike {
+    readonly doc: RigDocument;
+    readonly player: RigPlayer;
+    private readonly names;
+    private readonly ticker;
+    private readonly onTick;
+    constructor(doc: RigDocument, textures: Map<string, Texture>, opts: RigSymbolOptions);
+    private has;
+    resize(size: SymbolSize): void;
+    playIdle(): void;
+    /** resolves when the win animation completes (or immediately if there is none / it was replaced) */
+    playWin(): Promise<void>;
+    showStatic(): void;
+    /** dim as a held base pose (non-winning symbol); off → back to idle */
+    setDim(on: boolean): void;
+    destroy(options?: Parameters<Container["destroy"]>[0]): void;
+}

package/dist/lib/rig-template-library.d.ts

@@ -0,0 +1,3 @@
+import type { AnimationTemplate } from "./rig-templates";
+export declare function loadLibrary(path: string): Promise<AnimationTemplate[]>;
+export declare function saveTemplate(path: string, tpl: AnimationTemplate): Promise<void>;