@energy8platform/golem 0.1.0

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

@@ -0,0 +1,46 @@
+/**
+ * rig-templates — turn a finished animation into a reusable preset ("rig_save_as_preset").
+ *
+ * A template stores tracks relative to the source rig's rest pose and keyed by bone `role`, so it can be
+ * instantiated on a different rig: bone x/y/rotation as deltas, scale as ratios, slot alpha as a delta,
+ * deform params as-is, attachment/z unchanged. Params are scalar multipliers: `amplitude` (every relative
+ * value), `speed` (time), plus optional named groups that scale only the listed source tracks.
+ * Pure (no node:*) so the editor bundles it and previews param changes locally; the library on disk
+ * (a JSON array of templates, `presets.json` next to the rig by default) lives in `rig-template-library.ts`.
+ */
+import type { RigDocument, Animation, Track } from "./rig-format";
+type Key = Track["keys"][number];
+export interface TemplateTrack {
+    target: Track["target"];
+    /** source id (bone or slot) — used when the target rig has no matching role */
+    id: string;
+    /** role of the bone (or of the slot's bone) in the source rig */
+    role?: string;
+    prop: string;
+    /** values relative to rest (see module doc) */
+    keys: Key[];
+}
+export interface TemplateParam {
+    default: number; /** source track ids `target.id.prop`; absent = every track */
+    tracks?: string[];
+}
+export interface AnimationTemplate {
+    name: string;
+    duration: number;
+    loop: boolean;
+    events: Animation["events"];
+    tracks: TemplateTrack[];
+    params: Record<string, TemplateParam>;
+    /** source track ids left out because their keys are arrays (see `extractTemplate`) — absent when nothing was */
+    skipped?: string[];
+    source: {
+        rig: string;
+        animation: string;
+    };
+}
+export declare function extractTemplate(doc: RigDocument, animId: string, name: string, groups?: Record<string, string[]>): AnimationTemplate;
+export declare function instantiateTemplate(doc: RigDocument, tpl: AnimationTemplate, params?: Record<string, number>, id?: string): Animation;
+/** replace/add the instantiated animation in the document */
+export declare function applyTemplate(doc: RigDocument, tpl: AnimationTemplate, params?: Record<string, number>, id?: string): RigDocument;
+export declare function describeTemplate(t: AnimationTemplate): string;
+export {};

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

@@ -0,0 +1,376 @@
+/**
+ * rig-tools v0 — pure operations over RigDocument. No UI, no MCP; both sit on top of this.
+ * Every op returns a NEW document (undo-friendly, MCP-friendly).
+ */
+import { type RigDocument, type Bone, type Slot, type Track, type Attachment, type RegionAttachment, type MeshAttachment, type Influence, type Animation, type Reference, type Asset } from "./rig-format";
+import { type EaseSpec } from "./rig-anim";
+import { type Pt } from "./rig-constraints";
+type Doc = RigDocument;
+type Key = Track["keys"][number];
+type Transform = Bone["transform"];
+/** patches may give any subset of transform fields; `parent: null` detaches the bone (makes it a root) */
+export type BonePatch = Partial<Omit<Bone, "id" | "transform" | "parent">> & {
+    parent?: string | null;
+    transform?: Partial<Transform>;
+};
+export type SlotPatch = Partial<Omit<Slot, "id">>;
+export type KeyInput = Omit<Key, "ease"> & {
+    ease?: Key["ease"];
+};
+/** region placement: image centre in the slot bone's space */
+export type RegionPlacement = {
+    x?: number;
+    y?: number;
+    rotation?: number;
+    scaleX?: number;
+    scaleY?: number;
+    width?: number;
+    height?: number;
+};
+export declare function createDoc(name: string, width: number, height: number, notes?: string): Doc;
+/** One image as a rig: canvas = image + margin on every side, root at the image's bottom centre, slot pivot (0.5, 1). */
+export declare function createSymbol(name: string, asset: {
+    id?: string;
+    src: string;
+    width: number;
+    height: number;
+}, margin?: number, notes?: string): Doc;
+/** Swap a layer's file (e.g. after regeneration). Pivots are fractions, so slots keep working; provenance is merged. */
+export declare function replaceAsset(doc: Doc, id: string, next: {
+    src: string;
+    width: number;
+    height: number;
+    prompt?: string;
+    sourceImage?: string;
+    inpainted?: boolean;
+    bbox?: [number, number, number, number];
+}): Doc;
+export type AssetPatch = {
+    src?: string;
+    width?: number;
+    height?: number;
+    frame?: [number, number, number, number] | null;
+    origin?: Asset["origin"];
+};
+/**
+ * Create or patch an asset. `image` is the size of the PNG `src` names (the caller reads it — this module cannot
+ * read files); a `frame` must fit inside it. Size is only derived from `frame`/`image` when this patch actually
+ * REFRAMES (a `frame` or `src` was given) — with a frame the asset's size IS the frame's, without one it's the
+ * image's; an unrelated patch (e.g. `origin` only) leaves the current width/height alone, since for a packed
+ * atlas asset (rotate/trim) the frame's [w, h] is the packed size, not the true one `width`/`height` store.
+ * Re-framing an asset that regions already show keeps the SOURCE pixel that sat under each image centre
+ * where it was drawn (spec §3): the old centre lands at (u, v) of the new frame, so each placement moves by
+ * −L·(u, v) in its own rotated, scaled frame. A mesh keeps its uvs — they index the old pixels — and is named
+ * in `notes` so the caller re-traces it. Only a frame or src change resets `rotate`/`trim` (packer fields).
+ */
+export declare function setAsset(doc: Doc, id: string, patch: AssetPatch, image?: {
+    width: number;
+    height: number;
+}): {
+    doc: Doc;
+    notes: string[];
+};
+export declare function removeAsset(doc: Doc, id: string): Doc;
+/**
+ * One mutation for "this picture on that bone, here": the slot (`slot ?? asset`, created on `bone` when missing —
+ * an existing slot keeps its own bone), a region attachment named like the asset with its centre at the DOCUMENT
+ * point (x, y) expressed in the slot bone's rest frame, and the slot showing it.
+ */
+export declare function placeAsset(doc: Doc, p: {
+    asset: string;
+    bone: string;
+    x: number;
+    y: number;
+    slot?: string;
+    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 type MetaPatch = {
+    name?: string;
+    width?: number;
+    height?: number;
+    notes?: string;
+    reference?: (Partial<Omit<Reference, 'src'>> & {
+        src: string;
+    }) | null;
+};
+/**
+ * Patch the document's meta. Resizing the canvas moves nothing — bones keep their document coordinates, only the
+ * bounds change. `reference: null` clears the editor's underlay; a reference `src` has to stay inside the rig's
+ * directory, since that is the only place the editor server serves images from.
+ */
+export declare function setMeta(doc: Doc, patch: MetaPatch): Doc;
+export declare function addBone(doc: Doc, bone: BonePatch & {
+    id: string;
+}): Doc;
+export declare function updateBone(doc: Doc, id: string, patch: BonePatch): Doc;
+/** `approx` is the largest of its re-bound slots' (see `rebindSlot`), 0 when every re-expression was exact. */
+export declare function removeBone(doc: Doc, id: string): {
+    doc: Doc;
+    approx: number;
+};
+/**
+ * Create or patch a slot. A NEW slot is appended to every `drawOrder` key (it draws on top — the same place
+ * `z = max + 1` puts it), so a rig with such keys stays valid. A `bone` change on an existing slot goes through
+ * `rebindSlot`, so the images stay where they are on the document.
+ */
+export declare function setSlot(doc: Doc, slot: SlotPatch & {
+    id: string;
+}): Doc;
+export declare function removeSlot(doc: Doc, id: string): Doc;
+/**
+ * Move `slotId` onto `bone` WITHOUT moving what it shows. Every region's placement and every unweighted mesh or
+ * path vertex is re-expressed in the new bone's REST frame; weighted data is left alone — its points live in the
+ * influence bones, and the slot bone is not one of them. A region has no shear, so between two bones whose axes
+ * are not similar (a shear, a non-uniform scale, a mirror) the decomposition cannot be exact: `approx` is the
+ * largest distance (document px) any region corner moved, 0 when the re-expression is exact.
+ */
+export declare function rebindSlot(doc: Doc, slotId: string, bone: string): {
+    doc: Doc;
+    approx: number;
+};
+/** setup draw order in one call: `order` lists every slot back-to-front (the drawOrder key's order); z = index */
+export declare function setDrawOrder(doc: Doc, order: string[]): Doc;
+/** Create or patch a region attachment (an image placed in a slot). Placement is the image CENTRE in the slot bone's space. */
+export declare function setAttachment(doc: Doc, att: RegionPlacement & {
+    id: string;
+    slot?: string;
+    asset?: string;
+}): Doc;
+/** Create or replace any attachment (mesh / path / region) from a full description. */
+export declare function setAttachmentRaw(doc: Doc, att: Record<string, unknown> & {
+    id: string;
+}): Doc;
+/**
+ * Replace the geometry arrays of a mesh attachment. `vertices` and `weights` are exclusive: giving one drops
+ * the other, and exactly one must remain. Deform `vertices` keys whose length no longer matches the mesh are
+ * dropped (returned in `dropped`) — they would otherwise make the document invalid.
+ */
+export declare function setMesh(doc: Doc, id: string, patch: {
+    vertices?: number[];
+    weights?: MeshAttachment["weights"];
+    uvs?: number[];
+    triangles?: number[];
+    hull?: number;
+}): {
+    doc: Doc;
+    dropped: string[];
+};
+/** Replace a mesh's skinning (drops its unweighted `vertices`); stale deform vertex keys are pruned. */
+export declare const setWeights: (doc: Doc, id: string, weights: NonNullable<MeshAttachment["weights"]>) => {
+    doc: Doc;
+    dropped: string[];
+};
+/** Replace a REGION attachment by the given mesh (same id); lattice deform tracks on that id are removed (returned). */
+export declare function convertToMesh(doc: Doc, mesh: MeshAttachment): {
+    doc: Doc;
+    droppedTracks: string[];
+};
+export declare function removeAttachment(doc: Doc, id: string): Doc;
+/** the region attachment currently at rest in a slot (undefined when hidden or not a region) */
+export declare const restRegion: (doc: Doc, slotId: string) => RegionAttachment | undefined;
+/** region placement equivalent to a v1 pivot (fraction) + bone-local offset for an image of size w×h */
+export declare function placementFromPivot(pivot: {
+    x: number;
+    y: number;
+}, offset: Partial<Transform>, w: number, h: number): Required<Pick<RegionPlacement, "x" | "y" | "rotation" | "scaleX" | "scaleY">>;
+export type ConstraintKind = "ik" | "transform" | "path";
+/** which list holds `id` — constraint ids are unique across the three kinds */
+export declare const constraintKind: (doc: Doc, id: string) => ConstraintKind | undefined;
+/**
+ * Create or patch a constraint. The patch is merged over the current value and re-parsed, so schema defaults
+ * fill in on creation and a patch only has to name what changes (an explicit `undefined` changes nothing).
+ * A constraint's KIND is fixed on creation: changing it means removing the constraint and creating it again,
+ * because the three kinds share an id space and their fields (and tracks) do not translate.
+ */
+export declare function setConstraint(doc: Doc, kind: ConstraintKind, id: string, patch: Record<string, unknown>): Doc;
+/** Remove a constraint of any kind together with its tracks (mix / position / …). */
+export declare function removeConstraint(doc: Doc, id: string): Doc;
+/**
+ * Rig a limb in one call: `ikChainFor(bone)` gets a target bone at the chain's current tip and an IK constraint
+ * `<bone>_ik` whose bend sign reproduces the authored pose, so adding it moves nothing.
+ *
+ * The target is parented to the ROOT bone, never inside the chain: a target dragged by the bones it drives is a
+ * cycle (the solver would read what it just wrote). When the two-bone chain would reach up to the root — the only
+ * parent available for the target — the chain DEGRADES to the single bone (a one-bone IK aims that bone at the
+ * target and is cycle-free), and `note` says so; only a `bone` that is itself a root is refused (by `ikChainFor`).
+ */
+export declare function addIkChain(doc: Doc, bone: string, opts?: {
+    target?: string;
+    mix?: number;
+    softness?: number;
+}): {
+    doc: Doc;
+    chain: string[];
+    target: string;
+    bendPositive: boolean;
+    note?: string;
+};
+/** the vertex data of a path: anchors to smooth into a curve, or the raw control points themselves */
+export interface PathGeometryIn {
+    points?: Pt[];
+    vertices?: number[];
+    weights?: Influence[][];
+    closed?: boolean;
+}
+/**
+ * Create or replace a PATH attachment. Two forms, exactly one per call:
+ *   `points`   — anchors in DOCUMENT space; the curve is rebuilt with Catmull-Rom tangents (the agent's form).
+ *   `vertices` / `weights` — raw control points, [cPrev, p, cNext] per anchor, in the slot bone's space
+ *                            (or skinned), which is the ONLY form that preserves authored tangents and weights.
+ * `lengths` are re-measured in both cases. Deform tracks whose length no longer fits are dropped.
+ * `closed` and `constantSpeed` keep the attachment's current values when it already exists.
+ */
+export declare function setPathAttachment(doc: Doc, id: string, slot: string, geom: PathGeometryIn): {
+    doc: Doc;
+    dropped: string[];
+};
+/**
+ * Structural path edit. `insert` splits the curve AFTER anchor `index` at parameter `t`, which leaves the curve's
+ * shape untouched (de Casteljau); `remove` drops an anchor's triple, which necessarily changes the shape.
+ *
+ * A skinned path stays skinned: the five control points a split touches get their influence lists — bones,
+ * weights and bone-space positions alike — blended from the four the curve already had, by the split's own
+ * affine coefficients (`blendInfluences`). No bone appears or disappears, every list still sums to 1, and the
+ * shape is preserved in every POSE, not only in the setup one.
+ *
+ * `insert` also carries the DEFORM tracks through: the same coefficients blend the offsets of the same four
+ * control points (`blendOffsets`), which is the identity again with `q + d` in place of `q`, so the animated
+ * curve is unchanged too. That makes an insert lossless — which matters, because a single Ctrl-click on `ross`'s
+ * `tail_path` reaches 17 of them. `remove` cannot make that promise (it changes the curve's shape by
+ * construction), so its stale keys are still dropped and reported in `dropped`.
+ */
+export declare function pathAnchorOp(doc: Doc, id: string, op: "insert" | "remove", index: number, t?: number): {
+    doc: Doc;
+    dropped: string[];
+};
+/**
+ * Replace the keys of one track (creating the animation/track if missing). Manual edit → drops `preset`.
+ * `merge: true` keeps existing keys except those at the given times (fix one key without retyping all).
+ */
+export declare function setKeys(doc: Doc, animId: string, track: Omit<Track, "keys">, keys: KeyInput[], duration?: number, opts?: {
+    merge?: boolean;
+}): Doc;
+/**
+ * Re-tune one existing track without retyping keys: `amplitude` scales deviations from the rest value
+ * (scale props as ratios), `offset` adds a constant, `timeScale` stretches key times (duration grows to fit).
+ */
+export declare function adjustTrack(doc: Doc, animId: string, track: Omit<Track, "keys">, adj: {
+    amplitude?: number;
+    offset?: number;
+    timeScale?: number;
+}): Doc;
+export declare function removeAnimation(doc: Doc, id: string): Doc;
+/** Animation properties without touching keys. Creates the animation when missing. `rename` changes the id. */
+export declare function setAnimation(doc: Doc, id: string, patch: {
+    duration?: number;
+    loop?: boolean;
+    events?: Animation["events"];
+    rename?: string;
+}): Doc;
+/** Remove the keys of one track at the given times (1e-6 tolerance); an emptied track is dropped. Manual edit → drops `preset`. */
+export declare function removeKeys(doc: Doc, animId: string, track: Omit<Track, "keys">, times: number[]): Doc;
+/**
+ * Copy every `target: "bone"` track of each `from[i]` bone onto `to[i]`, pair by pair, replacing whatever
+ * `to[i]` already held for that prop. `phase` rotates each key's time by a fraction of the animation's duration,
+ * wrapping around (0.5 = half a cycle later, 1 is a full turn — the same identity as 0); `mirrorX` negates the
+ * props in `MIRRORED_BONE_PROPS`. A source bone with no bone tracks is collected into `empty` rather than failing the
+ * call — an agent may name a whole limb when only half of it is animated.
+ *
+ * Easing belongs to the key that STARTS a segment, so rotating keys around the end can split the segment that
+ * ran from the last key to the first: on a looping animation that is the same segment and nothing is lost, on a
+ * one-shot animation it is a different curve — `rig_copy_tracks` says so once when that applies. A track keyed at
+ * both 0 and `duration` (the standard closed-loop shape) keys the SAME point of the circle twice; any nonzero
+ * shift would send both copies to the same time, so the duplicate at `duration` is dropped before shifting. That
+ * is lossless when the two ends agree (the ordinary case: the cycle returns to where it started). Nothing forces
+ * them to — a tail can author a different rest angle at the loop's seam — so a drop where they DISAGREE is
+ * collected into `lossy` (bone, prop, both values) instead of silently discarding the segment between them: not
+ * an error (the source shape is legal), not something to nudge either key to avoid (there is no basis to pick
+ * which end wins), just a fact the caller needs to hear.
+ */
+export declare function copyTracks(doc: Doc, animId: string, from: string[], to: string[], opts: {
+    phase?: number;
+    mirrorX?: boolean;
+}): {
+    doc: Doc;
+    copied: number;
+    empty: string[];
+    lossy: string[];
+};
+/** compact key summary for one track: count and value range (or the set of discrete values) */
+export declare function trackSummary(t: Track): string;
+export type RenameKind = "bone" | "slot" | "attachment" | "asset" | "constraint";
+/**
+ * Rename one thing and every reference to it (spec §3). A bone is named by bone parents, slots, ik/transform
+ * chains and targets, path chains, every mesh/path influence and bone tracks; a slot by its attachments, path
+ * constraint targets (those aim at a slot), slot tracks and every drawOrder key; an attachment by the slot that
+ * shows it, `attachment` key values and deform tracks; an asset by regions and meshes; a constraint by its own
+ * tracks. Roles are not ids and stay. Templates in presets.json are a separate file and are NOT rewritten.
+ */
+export declare function rename(doc: Doc, kind: RenameKind, id: string, to: string): Doc;
+/** Compact text for agents. `verbose`: slot pivot/offset and every track with its key summary (no asset prompts). */
+/**
+ * One attachment in one line: what shape it is, and the counts an agent needs before it asks for the arrays.
+ * `deform.<id>.vertices` keys are `deformLength` numbers long, which is 2·Σ influences on a skinned shape and
+ * 2·vertices otherwise, so it is stated rather than left to be derived from the two counts.
+ */
+export declare function describeAttachment(doc: Doc, att: Attachment): string;
+export declare function describe(doc: Doc, opts?: {
+    verbose?: boolean;
+}): string;
+export interface PoseReport {
+    animation?: string;
+    t: number;
+    /** the animation's duration, so a caller can see that a `t` beyond it was clamped rather than sampled */
+    duration?: number;
+    bones: {
+        id: string;
+        x: number;
+        y: number;
+        angle: number;
+        scaleX: number;
+        scaleY: number;
+        local: {
+            x: number;
+            y: number;
+            rotation: number;
+        };
+    }[];
+    slots: {
+        id: string;
+        attachment: string | null;
+        bbox?: [number, number, number, number];
+    }[];
+}
+/**
+ * Where every bone and slot actually IS after `evaluate`: posed, not rest — constraints have run, so this is
+ * what the runtime draws. Without `animation`, the pose is empty (rest); `bones`/`slots` narrow the report and
+ * an id the document does not have is an error, not a silent drop, so a typo shows up at once.
+ */
+export declare function poseReport(doc: Doc, opts: {
+    animation?: string;
+    t?: number;
+    bones?: string[];
+    slots?: string[];
+}): PoseReport;
+/**
+ * A bone sent to a point in DOCUMENT coordinates — the gesture a human gets by dragging the bone in the editor.
+ *
+ * The point is converted through the parent's world matrix TAKEN FROM THE POSE AT `t`, never from rest: a goal
+ * solved against the setup pose is exact at rest and off by the parent's animated turn in every other frame.
+ * Which bone is actually written follows the editor's rule (`Stage.grabDriven`), because a bone a solver owns
+ * cannot be posed by writing it — a live ik hands the edit to its target bone, a live transform or path refuses.
+ */
+export declare function setGoal(doc: Doc, bone: string, x: number, y: number, opts: {
+    animation?: string;
+    t?: number;
+    ease?: EaseSpec;
+}): {
+    doc: Doc;
+    wrote: string;
+    redirected?: string;
+    origin: Pt;
+    tip: Pt;
+};
+export {};

package/dist/lib/runtime.d.ts

@@ -0,0 +1,9 @@
+/**
+ * `@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 { 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";