@energy8platform/golem 0.1.0

package/dist/lib/ktx2.d.ts

@@ -0,0 +1,15 @@
+export interface Ktx2Info {
+    width: number;
+    height: number;
+    levels: number;
+    hasAlpha: boolean;
+    uastc: boolean;
+}
+/** Transcode level 0 of a KTX2 texture to RGBA8. */
+export declare function ktx2ToRgba(data: Uint8Array): Promise<Ktx2Info & {
+    rgba: Uint8Array;
+}>;
+/** Transcode a KTX2 texture to a PNG buffer. */
+export declare function ktx2ToPng(data: Uint8Array): Promise<Ktx2Info & {
+    png: Buffer;
+}>;

package/dist/lib/mcp-server.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/lib/preview/harness.d.ts

@@ -0,0 +1,16 @@
+export interface RenderOptions {
+    animation?: string;
+    times: number[];
+    overlayBones?: boolean;
+    background?: string;
+    scale?: number;
+    sheetColumns?: number;
+    onionSkin?: boolean;
+    region?: [number, number, number, number];
+}
+export interface RenderResult {
+    frames: string[];
+    sheet: string;
+    width: number;
+    height: number;
+}

package/dist/lib/preview/render-preview.d.ts

@@ -0,0 +1,27 @@
+import { type RigDocument } from "../rig-format";
+export interface PreviewOptions {
+    /** directory that asset.src paths are relative to */
+    assetsDir: string;
+    animation?: string;
+    /** explicit sample times, OR fps (+ optional count) evenly over the animation */
+    times?: number[];
+    fps?: number;
+    count?: number;
+    overlayBones?: boolean;
+    background?: string;
+    scale?: number;
+    sheetColumns?: number;
+    /** ghost the previous frame under each frame */
+    onionSkin?: boolean;
+    /** crop [x, y, w, h] in DOCUMENT pixels — zoom on a detail without spending tokens on the whole canvas */
+    region?: [number, number, number, number];
+}
+export interface PreviewResult {
+    frames: Buffer[];
+    sheet: Buffer;
+    times: number[];
+    width: number;
+    height: number;
+}
+export declare function closePreview(): Promise<void>;
+export declare function renderPreview(doc: RigDocument, opts: PreviewOptions): Promise<PreviewResult>;

package/dist/lib/preview/viewer.d.ts

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,109 @@
+/**
+ * rig-anim — pure animation math shared by the runtime, the checker, the importer and tests. No PixiJS.
+ *
+ * - easing + track sampling, Pose: Map<"target:id:prop", value>
+ * - 2D affine matrices with PixiJS layout (a b c d tx ty; x' = a·x + c·y + tx, y' = b·x + d·y + ty)
+ * - bone world transforms with shear and inherit modes, constraints (ik / transform / path) applied in `order`
+ * - attachment geometry in document space: region corners, skinned mesh vertices, lattice deformation
+ */
+import type { RigDocument, Animation, Track, Bone, Attachment, RegionAttachment, MeshAttachment, PathAttachment } from "./rig-format";
+export type EaseSpec = Track["keys"][number]["ease"];
+export declare function ease(spec: EaseSpec): (t: number) => number;
+export type Val = number | string | null | number[] | string[];
+/** key: "bone:id:prop" | "slot:id:prop" | "deform:id:prop" | "ik:id:prop" | "transform:id:prop" | "path:id:prop" | "drawOrder:order:order" */
+export type Pose = Map<string, Val>;
+export declare const pk: (target: string, id: string, prop: string) => string;
+export declare function sample(track: Track, t: number): Val;
+export declare function poseOf(anim: Animation, t: number, out?: Pose): Pose;
+/** Crossfade: numbers (and number arrays) interpolate toward `to` (or rest when absent there); discrete values hold until w = 1. */
+export declare function blendPoses(from: Pose, to: Pose, w: number, restOf: (key: string) => Val): Pose;
+/** Setup value of a pose key. */
+export declare function restValue(doc: RigDocument, key: string): Val;
+/** "#rrggbbaa" → [r, g, b, a] in 0..1 */
+export declare const colorToArray: (c: string) => number[];
+/** Numeric lattice deform params of one attachment present in the pose, or undefined when it has none. */
+export declare function deformParams(pose: Pose, attachmentId: string): Record<string, number> | undefined;
+export interface Affine {
+    a: number;
+    b: number;
+    c: number;
+    d: number;
+    tx: number;
+    ty: number;
+}
+/** translate · rotate(deg, clockwise in Y-down) · shear · scale — PixiJS setTransform semantics with shear as axis angles */
+export declare function affineOf(x: number, y: number, rotationDeg: number, sx: number, sy: number, shearX?: number, shearY?: number): Affine;
+/** parent ∘ local (apply local first, then parent) — PixiJS Matrix.append */
+export declare function mul(p: Affine, l: Affine): Affine;
+export declare const apply: (m: Affine, x: number, y: number) => [number, number];
+export declare function invert(m: Affine): Affine;
+/** rotation of the x axis of an affine, degrees */
+export declare const rotationOf: (m: Affine) => number;
+/**
+ * Where a world matrix puts a bone, which way its x axis points, and how long its axes are — the inverse of
+ * `affineOf` for everything except shear, which cannot be recovered from the axes alone (a sheared y axis is
+ * reported by its length, and `angle` follows the x axis only). Reading a posed bone goes through here so the
+ * numbers an agent gets are the numbers the runtime drew.
+ */
+export declare function decompose(m: Affine): {
+    x: number;
+    y: number;
+    angle: number;
+    scaleX: number;
+    scaleY: number;
+};
+export interface BoneState {
+    /** effective local values (setup + pose + constraint adjustments) */
+    x: number;
+    y: number;
+    rotation: number;
+    scaleX: number;
+    scaleY: number;
+    shearX: number;
+    shearY: number;
+    world: Affine;
+}
+export interface Skeleton {
+    doc: RigDocument;
+    pose: Pose;
+    bones: Map<string, BoneState>;
+    /** attachment shown per slot (pose or setup), null = hidden */
+    attachment: Map<string, Attachment | null>;
+}
+/** world transform of one bone from its effective local values and its parent's world transform, honouring `inherit` */
+export declare function boneWorldOf(bone: Bone, s: Omit<BoneState, "world">, parent: Affine | undefined): Affine;
+export declare function boneOrder(doc: RigDocument): Bone[];
+/** Full skeleton evaluation for a pose: bone locals, constraints in order, world transforms, shown attachments. */
+export declare function evaluate(doc: RigDocument, pose: Pose): Skeleton;
+/** Bone world transforms for a pose (constraints applied). */
+export declare function boneWorld(doc: RigDocument, pose: Pose): Map<string, Affine>;
+/** world-space control points of a path attachment (2 numbers per vertex) */
+export declare function pathWorldVertices(skel: Skeleton, slotId: string, att: PathAttachment): number[];
+/** path length: `lengths[i]` is the length up to the end of curve i; an open path stores one extra entry */
+export declare function pathLength(vertexCount: number, closed: boolean, lengths: number[]): number;
+/**
+ * Sample positions and tangents along a path made of cubic bezier curves through the attachment vertices
+ * (vertex layout: [c_prev, p, c_next] triples; curve i runs p_i → c_next_i → c_prev_{i+1} → p_{i+1}).
+ */
+/**
+ * Points along a path attachment (document space). `positions` are absolute distances along the path (or fractions of
+ * its length when `percent`). With `constantSpeed` the length of the posed curve is measured (4 chords per curve for
+ * the total, 10 chords inside the curve that holds the position); otherwise the stored setup `lengths` and the raw
+ * curve parameter are used. Closed paths wrap; positions beyond an open path continue along its end tangents.
+ * `angle` is the tangent direction in degrees.
+ */
+export declare function samplePath(points: number[], closed: boolean, lengths: number[], constantSpeed: boolean, positions: number[], percent: boolean): {
+    x: number;
+    y: number;
+    angle: number;
+}[];
+/** skinned or bone-local vertices of a mesh/path attachment in document space, deform offsets applied */
+export declare function attachmentWorldVertices(skel: Skeleton, slotId: string, att: MeshAttachment | PathAttachment): number[];
+/** image-local (centre-relative) → document matrix for a region attachment */
+export declare function regionMatrix(skel: Skeleton, slotId: string, att: RegionAttachment): Affine;
+export declare function regionSize(doc: RigDocument, att: RegionAttachment): [number, number];
+/**
+ * Outline of a slot's shown attachment in document space: region → `samplesPerEdge` points per edge clockwise
+ * from the top-left (lattice deform applied), mesh → hull vertices (or all), path/hidden → undefined.
+ */
+export declare function slotOutline(doc: RigDocument, pose: Pose, slotId: string, samplesPerEdge?: number, skel?: Skeleton): [number, number][] | undefined;

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

@@ -0,0 +1,26 @@
+/**
+ * rig-api — the tool registry. MCP (stdio), the CLI and the editor's HTTP server all register these same tools,
+ * so a human in the editor and an agent over MCP perform identical operations with identical history.
+ *
+ * Each tool reads `rig.json`, applies, writes back. Stateless per call: agents can crash/retry freely; the file
+ * is the state. Every mutation first snapshots the previous file into `.rig-history/` (rig_undo / rig_diff) and
+ * answers with what changed; structural tools also return the compact rig summary.
+ */
+import { z } from "zod";
+import { RigDocument } from "./rig-format";
+export interface ToolResult {
+    text: string;
+    image?: Buffer;
+    doc?: RigDocument;
+    isError?: boolean;
+}
+/** `input` is the BUILT schema, not the raw shape: see `tool` below for why every caller has to share this one object */
+export interface ToolDef {
+    name: string;
+    description: string;
+    input: z.AnyZodObject;
+    run(args: Record<string, unknown>): Promise<ToolResult>;
+}
+export declare const tools: ToolDef[];
+export declare function callTool(name: string, args: unknown): Promise<ToolResult>;
+export declare const closeTools: () => Promise<void>;

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

@@ -0,0 +1,20 @@
+import type { RigDocument } from "./rig-format";
+export interface Rect {
+    id: string;
+    width: number;
+    height: number;
+}
+export interface Packed {
+    width: number;
+    height: number;
+    frames: Map<string, [number, number, number, number]>;
+}
+export interface PackOptions {
+    /** gap between frames in px (default 2); never less than 2·extrude */
+    padding?: number;
+    /** px of edge replication into the gutter (default 1) */
+    extrude?: number;
+    maxSize?: number;
+}
+export declare function packRects(rects: Rect[], opts?: PackOptions): Packed;
+export declare function buildAtlas(doc: RigDocument, assetsDir: string, outDir: string, opts?: PackOptions): Promise<RigDocument>;

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

@@ -0,0 +1,45 @@
+/**
+ * rig-check — cheap self-critique for agents, computed from the document alone (no browser).
+ *
+ * Findings are hints, not a pass/fail gate: `rest_overlap` is normal for cut-out characters,
+ * `out_of_canvas` may be intended for a jump. `deform_flip` and `mesh_fold` are the real errors (folded mesh/lattice);
+ * `weights_sum` flags skinned-mesh vertices whose influence weights don't add to 1.
+ *
+ * `mesh_fold` is graded by how much of the mesh folds — the folded triangles' rest area over the mesh's total rest
+ * area, at the worst sampled time. A dense mesh bent hard at a joint almost always pinches one hairline triangle
+ * somewhere; that is a `warn`, not something to stop for. `error` is reserved for a fold big enough to see
+ * (≥ `FOLD_ERROR_RATIO` of the mesh), which is what a torn limb or a collapsed silhouette looks like.
+ *
+ * Constraints get four of their own: `constraint_dead` (every mix is 0 at rest and no track lifts one — the solver
+ * skips it), `constraint_cycle` (the target is a bone the constraint drives, or hangs off one: it reads what it
+ * writes — an error), `ik_unreachable` (the target sits beyond the chain's reach for most of an animation, so the
+ * limb hangs straight instead of following) and `path_missing` (a path constraint whose target slot never shows a
+ * path attachment — an error).
+ */
+import { type RigDocument } from "./rig-format";
+export interface Finding {
+    level: "error" | "warn" | "info";
+    code: string;
+    /** slot / track / asset the finding is about */
+    subject: string;
+    message: string;
+    animation?: string;
+    time?: number;
+}
+export interface CheckOptions {
+    /** only this animation (plus the rest pose) */
+    animation?: string;
+    /** sampling rate for outlines (default 30) and for the fold check (default 60) */
+    fps?: number;
+    deformFps?: number;
+    /** rest_overlap threshold as a fraction of the smaller box (default 0.6) */
+    overlap?: number;
+    /** px of allowed overflow before out_of_canvas fires (default 1) */
+    margin?: number;
+}
+export declare function checkRig(doc: RigDocument, opts?: CheckOptions): Finding[];
+/** One-line count plus the findings — appended to preview results and returned by rig_check.
+ * A single noisy code (e.g. mesh_fold across 100 meshes) is capped at 5 lines so it can't crowd out every
+ * other kind of finding within `max`; the rest fold into one "… N more <code>" line, then the overall `max`
+ * still applies on top of that. */
+export declare function summarize(findings: Finding[], max?: number): string;

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

@@ -0,0 +1,59 @@
+/**
+ * rig-constraints — pure helpers for authoring constraints: which bones a constraint drives, the 1–2 bone chain
+ * behind a limb, the bend sign that reproduces a pose, IK reach, and path geometry from anchor points.
+ * The solvers themselves live in rig-anim.ts and are not touched here. No node:*, no DOM.
+ */
+import { type RigDocument, type IkConstraint } from "./rig-format";
+import { type Pose, type Skeleton } from "./rig-anim";
+export type Pt = [number, number];
+/** bone id → ids of the constraints that write that bone, in the order the solver applies them */
+export declare function drivenBones(doc: RigDocument): Map<string, string[]>;
+/**
+ * A constraint's property at one moment: the keyed value, else the document's. That is the read the solvers make
+ * to decide whether they run at all (`cnum` in rig-anim.ts), so anything asking "is this constraint live here?"
+ * has to make the same one — hence one exported copy rather than a fourth private one.
+ */
+export declare const mixAt: (pose: Pose, kind: string, id: string, prop: string, rest: number) => number;
+/**
+ * The constraint that owns a bone's transform in this pose, or undefined when the bone is really editable there.
+ * The LAST constraint in solver order wins (it writes last), and one counts only while it is actually mixed IN —
+ * the solvers' own early-outs, listed once in `MIX_PROPS`. A mixed-out constraint therefore blocks nothing: at
+ * that frame the solver skips it and whatever wrote before it stands.
+ * `Stage.driverOf` forwards to this function over the editor's own pose signal — there is no second copy left.
+ */
+export declare function driverAt(doc: RigDocument, pose: Pose, bone: string): {
+    kind: "ik" | "transform" | "path";
+    id: string;
+    target: string;
+} | undefined;
+/** [parent, bone] when the parent has exactly one child (an unambiguous limb), else [bone] */
+export declare function ikChainFor(doc: RigDocument, bone: string): string[];
+/** world point at the far end of the chain's last bone (its `length` along its x axis) */
+export declare function chainEnd(skel: Skeleton, chain: string[]): Pt;
+/**
+ * `bendPositive` for a two-bone chain: the sign of the cross product of the chain's two segments as they are posed
+ * now — parent origin → child origin, then child origin → the chain's tip. That is the triangle the two-bone solver
+ * works in (`bendDir` picks which side of it the joint falls on), so the sign matches it even when the parent is
+ * sheared or its child hangs off its x axis, where "the parent's x axis" would not.
+ * A straight chain (cross ≈ 0) answers `true`, matching Spine's default.
+ * A chain whose last bone has `length: 0` has no measurable bend either (the tip coincides with the bone's own
+ * origin, so the cross product is always exactly 0) and likewise answers `true`.
+ */
+export declare function bendSignFor(skel: Skeleton, chain: string[]): boolean;
+/** distance from the chain root to the target and the chain's maximum reach, both in world px */
+export declare function ikReach(skel: Skeleton, c: IkConstraint): {
+    distance: number;
+    reach: number;
+};
+/** anchor points of a path attachment in document space (every third vertex, starting at index 1) */
+export declare const pathAnchors: (world: number[]) => Pt[];
+/**
+ * Anchor points → the format's `[cPrev, anchor, cNext]` triples. Control points come from Catmull-Rom tangents
+ * ((next − prev) / 6), which makes the curve pass through every anchor with C1 continuity; the ends of an open
+ * path use the single available neighbour. Coordinates are converted into the slot bone's space.
+ */
+export declare function pathFromPoints(skel: Skeleton, slotId: string, points: Pt[], closed: boolean): {
+    vertices: number[];
+    closed: boolean;
+    lengths: number[];
+};

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

@@ -0,0 +1,27 @@
+/**
+ * rig-deform — 3×3 control-grid deformer for a slot's attachment (pure math, no PixiJS).
+ *
+ * Control points live on an interpolating biquadratic (Lagrange) patch over the image:
+ * rows r=0..2 at v=0,0.5,1 of the height (top→bottom), cols c=0..2 at u=0,0.5,1 of the width.
+ * Each control point carries an offset (dx, dy) in image pixels. With zero offsets the patch is the
+ * identity, and moving control point (r,c) by d moves the surface at that point by exactly d.
+ *
+ * Named params are dimensionless fractions of the image size (see spec §1); raw `p<r><c>x|y` are pixels.
+ * All contributions add.
+ */
+export declare const DEFORM_NAMED: readonly ["bulge", "bend", "sway", "squash"];
+export declare const DEFORM_PROP_RE: RegExp;
+/** |value| bound per named param. bulge/squash reach a degenerate (zero-area) patch at 1, hence 0.9. */
+export declare const DEFORM_BOUNDS: Record<(typeof DEFORM_NAMED)[number], number>;
+export interface Pivot {
+    x: number;
+    y: number;
+}
+/** Named params + raw offsets → 18 numbers [dx00, dy00, dx01, dy01, …] row-major by (r*3+c). */
+export declare function controlOffsets(params: Record<string, number>, w: number, h: number, pivot: Pivot, out?: Float64Array): Float64Array;
+/** Patch offset at normalized image coords (u, v) ∈ [0,1]². */
+export declare function evalPatch(offsets: ArrayLike<number>, u: number, v: number): [number, number];
+/** n×n render vertices (row-major, x fastest — PlaneGeometry order), pivot baked in, image-local pixels. */
+export declare function gridPositions(offsets: ArrayLike<number>, w: number, h: number, pivot: Pivot, n: number, out?: Float32Array): Float32Array;
+/** Minimum Jacobian determinant of (u,v)→image map over a sample grid, normalized so identity = 1. ≤ 0 means a fold. */
+export declare function minJacobian(offsets: ArrayLike<number>, w: number, h: number, samples?: number): number;