@energy8platform/golem 0.1.0

package/dist/lib/editor/api.d.ts

@@ -0,0 +1,42 @@
+/**
+ * editor/api.ts — the only place that talks to editor/server.ts.
+ * Every call names the rig by its path relative to the server root; the file on disk is the state.
+ */
+import type { RigDocument } from "../rig-format";
+/** `status` is the HTTP status: 409 means a stale `baseVersion` — the tool never ran, so it is not a tool error */
+export interface ToolResult {
+    text: string;
+    doc?: RigDocument;
+    image?: string;
+    isError?: boolean;
+    version: string;
+    status: number;
+}
+export declare function getDoc(rig: string): Promise<{
+    doc: RigDocument;
+    version: string;
+}>;
+/**
+ * `baseVersion` is the version the caller edited: the server refuses with 409 when the file has moved on since.
+ * Left out (a read-only tool, and every other client of this route) it is absent from the JSON, and unchecked.
+ */
+export declare function callTool(rig: string, name: string, args: Record<string, unknown>, baseVersion?: string): Promise<ToolResult>;
+/** SSE; returns unsubscribe. onState(false) on error, onState(true) on (re)open. EventSource reconnects by itself. */
+export declare function subscribe(rig: string, onChanged: (version: string) => void, onState: (online: boolean) => void): () => void;
+/** URL for an asset `src` that is relative to the rig file's directory */
+export declare const assetUrl: (rigDir: string, src: string) => string;
+export type RigEntry = {
+    rig: string;
+    name: string;
+    mtimeMs: number;
+};
+export type FileEntry = {
+    name: string;
+    width: number;
+    height: number;
+};
+export declare function listRigs(): Promise<RigEntry[]>;
+export declare function createRig(rig: string, name: string, width: number, height: number): Promise<ToolResult>;
+export declare function listFiles(rig: string): Promise<FileEntry[]>;
+/** one PNG into the rig's directory; the server refuses an existing name (409) and anything that is not a PNG */
+export declare function upload(rig: string, file: File): Promise<FileEntry>;

package/dist/lib/editor/app.d.ts

@@ -0,0 +1,13 @@
+import "./editor.css";
+import { Stage } from "./stage";
+import * as store from "./store";
+import { Timeline } from "./timeline";
+declare global {
+    interface Window {
+        editor: {
+            store: typeof store;
+            stage: Stage;
+            timeline: Timeline;
+        };
+    }
+}

package/dist/lib/editor/atlas-detect.d.ts

@@ -0,0 +1,28 @@
+/**
+ * editor/atlas-detect.ts — connected islands of opaque pixels on a sheet, as rectangles. Pure: a `Mask` in,
+ * `Rect`s out, so it runs in Node for the tests; the browser side (`maskFromImageData`) is one loop.
+ */
+export type Rect = [number, number, number, number];
+export interface Mask {
+    width: number;
+    height: number;
+    alpha: Uint8Array;
+}
+export declare function maskFromImageData(img: {
+    width: number;
+    height: number;
+    data: Uint8ClampedArray;
+}): Mask;
+/**
+ * Every 4-connected island of pixels with `alpha > threshold`, after growing the mask by `gap` px (a square
+ * kernel), so fragments closer than that count as one part. The rectangle is the bbox of the ORIGINAL opaque
+ * pixels of the island, not of the grown one, so it stays tight; islands with a bbox area under `minArea` are
+ * dropped (specks, stray strokes). Sorted by top, then left.
+ */
+export declare function detectIslands(m: Mask, o?: {
+    gap?: number;
+    minArea?: number;
+    threshold?: number;
+}): Rect[];
+/** the bbox of the opaque pixels inside `r` (clipped to the mask), or undefined when there are none */
+export declare function alphaBBox(m: Mask, r: Rect, threshold?: number): Rect | undefined;

package/dist/lib/editor/atlas-panel.d.ts

@@ -0,0 +1 @@
+export declare function AtlasPanel(): import("preact").JSX.Element;

package/dist/lib/editor/atlas.d.ts

@@ -0,0 +1,39 @@
+/**
+ * editor/atlas.ts — the Stage's atlas mode: the sheet on a checkerboard, its rectangles (named in the accent
+ * colour with a label, proposed grey and dashed, the selected ones with grips), and the three gestures —
+ * marquee on empty pixels, move from inside, resize by a grip. Rectangles are store state; a finished gesture
+ * commits through `setRect` / `addProposed`, so the document changes only for named ones (`rig_set_asset`).
+ */
+import { Container, Graphics } from "pixi.js";
+export declare class AtlasView {
+    /** the checkerboard and the sheet, with the name labels on top — one container, so the Stage shows and hides it as one */
+    readonly view: Container<import("pixi.js").ContainerChild>;
+    private labels;
+    private gesture?;
+    /** the sheet's size once decoded — the Stage fits the camera to it */
+    size?: {
+        width: number;
+        height: number;
+    };
+    get ready(): boolean;
+    /**
+     * Decode `url`, show it, and hand its alpha to the store. Every failure (a broken PNG, a sheet over 8192 px a
+     * side, a canvas that will not give its pixels) is a status and `atlasFailed`, never a rejection. A view the
+     * Stage replaced while the image decoded does nothing on return — the store belongs to the sheet open NOW.
+     */
+    load(url: string, name: string): Promise<void>;
+    /** the overlay for this frame: every rectangle, the selection's grips, the gesture in progress */
+    draw(gfx: Graphics, zoom: number): void;
+    private label;
+    /** the cursor for a hover point: a grip's, `move` inside a selected rectangle, crosshair on empty pixels */
+    cursorAt(p: [number, number], zoom: number): string;
+    /** a press: a grip or the inside of a SELECTED rectangle starts an edit; inside any other selects it (Shift adds); empty starts a marquee */
+    onDown(p: [number, number], zoom: number, shift: boolean): void;
+    onMove(p: [number, number]): boolean;
+    /** a moved rectangle stays on the sheet (the preview too, so what is dragged is what is committed) */
+    private onSheet;
+    /** the gesture's result: a moved/resized rectangle (resizes snap), or a new proposed one (snaps; nothing opaque = dropped) */
+    onUp(): void;
+    /** the sheet's and the checkerboard's GPU textures go with the sprites — nothing else holds them */
+    destroy(): void;
+}

package/dist/lib/editor/gizmo-math.d.ts

@@ -0,0 +1,36 @@
+/** Pure math for the editor gizmos — no DOM, no PixiJS; tested in Node. */
+import { type Affine } from "../rig-anim";
+export interface TransformValues {
+    x: number;
+    y: number;
+    rotation: number;
+    scaleX: number;
+    scaleY: number;
+    shearX: number;
+    shearY: number;
+}
+/**
+ * Cheap order- and length-sensitive hash of a number array — used where an equality check would be too
+ * expensive to run on every doc change (e.g. `structureKeyOf` over a mesh's uvs/triangles, JSON.stringify of
+ * which is too slow for rigs with 100+ meshes). Not a checksum: collisions are possible, just unlikely enough
+ * for a "does this need a rebuild" gate.
+ *
+ * Small non-negative integers (triangle/vertex indices) leave a double's low 32-bit word at 0, so folding lo
+ * and hi into the running hash as two separate multiply-xor steps (as an earlier version of this function did)
+ * left the low-word step contributing nothing beyond the loop index — collapsing most of a 54-element
+ * `triangles` permutation's entropy down to the handful of bits `hi` varies over, which collided ~3% of the
+ * time on realistic triangle arrays. Instead each element's (lo, hi, index) is combined and run through a full
+ * murmur3 avalanche (fmix32) BEFORE folding into `h`, so a coarse difference in `hi` alone still spreads across
+ * all 32 bits of that element's contribution; measured at 0 collisions over 5000 permutations of a 54-element,
+ * 18-distinct-value array (see the collision-rate test in gizmo-math.test.ts).
+ */
+export declare function hashNumbers(arr: readonly number[]): number;
+export declare const deltaDeg: (a: number, b: number) => number;
+export declare const angleDeg: (fx: number, fy: number, tx: number, ty: number) => number;
+/** the resize cursor whose axis is closest to a screen direction (degrees, y down); an axis has no sign, so 180° folds onto 0° */
+export declare function cursorFor(angleDeg: number): string;
+export declare function decompose(m: Affine): TransformValues;
+export declare function localFromWorld(parentWorld: Affine | undefined, world: Affine): TransformValues;
+export declare const toLocal: (m: Affine, x: number, y: number) => [number, number];
+export declare function hitRegion(m: Affine, w: number, h: number, px: number, py: number): boolean;
+export declare function hitMesh(v: number[], tri: number[], px: number, py: number): boolean;

package/dist/lib/editor/gizmos.d.ts

@@ -0,0 +1,185 @@
+/**
+ * editor/gizmos.ts — the drag handles on the selected bone / region and the single tool call each gesture commits.
+ *
+ * A gizmo is a small state machine: `handles()` says where the grips are (document space), `hit()` finds one under
+ * the pointer, `begin()` snapshots the document, the skeleton and the values the drag starts from, `drag()` returns
+ * a *preview* document rebuilt from that snapshot every move (never from the previous preview, so a gesture never
+ * accumulates), and `commit()` names the one tool call that makes the preview real.
+ *
+ * Everything here is pure except `draw`, which paints into a PixiJS `Graphics` — imported as a type only, so the
+ * math below runs in Node.
+ */
+import type { Graphics } from "pixi.js";
+import { type Skeleton } from "../rig-anim";
+import type { RigDocument } from "../rig-format";
+import { type TransformValues } from "./gizmo-math";
+export type { TransformValues };
+export interface Mods {
+    shift: boolean;
+    alt: boolean;
+}
+export interface Handle {
+    id: "move" | "rotate" | "scale" | "scaleY";
+    x: number;
+    y: number;
+    cursor: string;
+    /** drawn radius in screen px, `GRIP_PX` by default — a path's tangent grips are smaller than their anchor */
+    r?: number;
+    /** a path TANGENT grip: the one control point it drags (an anchor grip moves the whole selection instead) */
+    vertex?: number;
+}
+export interface GizmoContext {
+    shown(): RigDocument;
+    skel(): Skeleton;
+    mode(): "setup" | "animate";
+    animId(): string | undefined;
+    time(): number;
+}
+export interface ToolCall {
+    tool: string;
+    args: Record<string, unknown>;
+}
+export interface Gizmo {
+    handles(zoom: number): Handle[];
+    draw(g: Graphics, zoom: number): void;
+    /** nearest handle within 8 screen px, or undefined */
+    hit(p: [number, number], zoom: number): Handle | undefined;
+    begin(h: Handle, p: [number, number]): void;
+    /** returns the draft document for the pointer at p */
+    drag(p: [number, number], mods: Mods): RigDocument;
+    /** the tool call that commits the gesture (undefined = nothing changed) */
+    commit(): ToolCall | undefined;
+}
+/** pure: local transform patch for a bone whose joint should sit at world point p */
+export declare function boneMoveValues(skel: Skeleton, doc: RigDocument, boneId: string, p: [number, number]): {
+    x: number;
+    y: number;
+};
+/**
+ * pure: local rotation so the bone's x axis points from its joint to p (exact under a scaled parent — the direction
+ * is measured in the parent's frame, not in world, so non-uniform parent scale does not skew the answer).
+ * `affineOf` builds the x axis at `rotation + shearX`, so the shear has to come back out of the measured angle.
+ * Assumes `inherit: "normal"`; the other modes replace the parent's linear part and are not editable this way.
+ */
+export declare function boneRotationValue(skel: Skeleton, doc: RigDocument, boneId: string, p: [number, number]): number;
+/**
+ * pure: the `rig_update_bone` args that move `boneId` under `newParent` while keeping its world matrix — the local
+ * transform is its world matrix expressed in the new parent's frame.
+ *
+ * Throws when the new parent is the bone itself or one of its descendants (that would cut the branch off the tree),
+ * and when either bone is unknown. `approximate` warns that the answer only holds for `inherit: "normal"`: the other
+ * modes replace the parent's linear part, so no local transform under an arbitrary parent reproduces the old world.
+ * The caller passes the REST skeleton — `rig_update_bone` writes setup values, not posed ones.
+ */
+export declare function reparentArgs(skel: Skeleton, doc: RigDocument, boneId: string, newParent: string): {
+    id: string;
+    parent: string;
+    transform: TransformValues;
+    approximate: boolean;
+};
+export declare class BoneGizmo implements Gizmo {
+    private ctx;
+    private boneId;
+    private start?;
+    private patch?;
+    constructor(ctx: GizmoContext, boneId: string);
+    handles(zoom: number): Handle[];
+    draw(g: Graphics, zoom: number): void;
+    hit(p: [number, number], zoom: number): Handle | undefined;
+    begin(handle: Handle, p: [number, number]): void;
+    drag(p: [number, number], mods: Mods): RigDocument;
+    /** the preview: setup edits the rest transform, animate writes absolute keys at t (merged into the tracks) */
+    private write;
+    commit(): ToolCall | undefined;
+}
+export declare class RegionGizmo implements Gizmo {
+    private ctx;
+    private attachmentId;
+    private start?;
+    private patch?;
+    constructor(ctx: GizmoContext, attachmentId: string);
+    private region;
+    /** the world transform of the bone the attachment's slot hangs on */
+    private boneWorld;
+    handles(zoom: number): Handle[];
+    draw(g: Graphics, zoom: number): void;
+    hit(p: [number, number], zoom: number): Handle | undefined;
+    begin(handle: Handle, p: [number, number]): void;
+    drag(p: [number, number], mods: Mods): RigDocument;
+    commit(): ToolCall | undefined;
+}
+/**
+ * The selected vertices of one mesh — or the selected ANCHORS of one path attachment, plus the two bezier
+ * tangents of a single selected anchor: a grip on each, and a drag that moves them by one world delta.
+ *
+ * A mesh and a path are the same problem, and this solves it once: both carry the same `VertexData` (`vertices`
+ * in the slot bone's space, or `weights` skinned to bones), and both modes write THE SAME NUMBERS — the drag,
+ * mapped into each influence's own bone by `deformOffsetsFor`. **Setup** adds them into the rest shape, so a
+ * skinned mesh (or a skinned PATH — five of `ross`'s seven are) keeps its weights and every value the drag did
+ * not touch. **Animate** writes them as a `deform.<id>.vertices` key at the current time instead, one key for the
+ * whole selection, one tool call. (`ross`'s `tail_path` arrives from Spine with 17 such tracks.) The only
+ * difference is the frame: setup maps the drag through the REST matrices, animate through the posed ones.
+ *
+ * A path's grips sit on its ANCHORS (vertex 3i + 1 of the `[cPrev, p, cNext]` triples), and an anchor drags its
+ * whole triple, so the curve keeps its shape around the anchor — which is what a hand expects. The tangents are
+ * grips of their own, shown only while exactly ONE anchor is selected (all of them at once would put ten more
+ * grips on `ross`'s five-anchor `tail_path`, and a mesh-sized path far more) and dragged one at a time.
+ */
+export declare class VertexGizmo implements Gizmo {
+    private ctx;
+    private attachmentId;
+    private indices;
+    private start?;
+    private delta?;
+    private patch?;
+    private offsets?;
+    constructor(ctx: GizmoContext, attachmentId: string, indices: () => number[]);
+    private attachment;
+    /** the selected indices that actually exist — a stale selection must not throw mid-frame */
+    private selected;
+    handles(_zoom: number): Handle[];
+    /** a selected anchor and its tangents are one widget, so they get the connecting arms; loose vertex grips are not */
+    draw(g: Graphics, zoom: number): void;
+    hit(p: [number, number], zoom: number): Handle | undefined;
+    begin(handle: Handle, p: [number, number]): void;
+    /** which VERTICES a grip drags: a mesh's whole selection, every selected anchor's triple, or the one tangent the grip names */
+    private moved;
+    /** the deform offsets the animation already has at `t` — undefined when there is no track, or its length is stale */
+    private keyAt;
+    drag(p: [number, number], _mods: Mods): RigDocument;
+    /**
+     * The drag as a local offset per influence — the `deform.<id>.vertices` layout — folded over every moved vertex.
+     * One key for the whole selection: each list feeds the next call as its base, and the snapshot's base is copied
+     * rather than handed over, so no future in-place writer downstream can spoil the next move's baseline.
+     * Rebuilt from that base every move, so a gesture never accumulates.
+     */
+    private localDeltas;
+    /**
+     * Setup: the same local offsets added into the REST shape, which is the whole of the edit. Every value the drag
+     * did not move is passed through untouched — byte for byte, not through a round trip that should be the
+     * identity and is not quite (it rounds).
+     *
+     * Deliberately not `fitVertices`: that re-derives each influence from ONE world point, which is right only for
+     * a vertex whose influences already agree on where that vertex is at rest. Spine's do not — 24 of `ross`'s 49
+     * skinned meshes carry over a pixel of spread, and `blendInfluences` produces the disagreement on purpose (it
+     * is what keeps an inserted anchor's shape in every pose). Fitting throws that away for a position that only
+     * matches at rest: the difference contains neither the drag nor the pose, so even a 1 px nudge in setup moves
+     * `tail_path`'s anchor ~24 px, and `n_fur`'s vertex 0 ~489 px, once the animation poses the bones. Adding the
+     * drag in each bone's own frame moves the vertex by exactly the drag at rest and leaves the spread alone.
+     */
+    private shift;
+    commit(): ToolCall | undefined;
+}
+export type RectHandle = "move" | "n" | "s" | "e" | "w" | "nw" | "ne" | "sw" | "se";
+type Rect = [number, number, number, number];
+/** the eight grips of a rectangle, clockwise from the top-left corner */
+export declare function rectHandles([x, y, w, h]: Rect, _zoom: number): {
+    id: RectHandle;
+    x: number;
+    y: number;
+    cursor: string;
+}[];
+/** a grip within 8 screen px, else the nearest edge LINE within that (the whole side resizes, not just its mid grip), else `move` for a press inside the rectangle, else undefined */
+export declare function rectHit(r: Rect, p: [number, number], zoom: number): RectHandle | undefined;
+/** the rectangle after dragging `h` from p0 to p — integers, at least 1×1, and an edge never passes its opposite */
+export declare function rectDrag(h: RectHandle, [x, y, w, h0]: Rect, p0: [number, number], p: [number, number]): Rect;

package/dist/lib/editor/layers.d.ts

@@ -0,0 +1 @@
+export declare function LayersList(): import("preact").JSX.Element | null;

package/dist/lib/editor/library.d.ts

@@ -0,0 +1,3 @@
+export declare function FilesList(): import("preact").JSX.Element;
+/** thumbnails of every asset: drag one onto the canvas or a bone row to place it, double-click places it centred */
+export declare function AssetBin(): import("preact").JSX.Element | null;

package/dist/lib/editor/panels.d.ts

@@ -0,0 +1,26 @@
+/** editor/panels.tsx — the side panels: the hierarchy tree here, the properties forms in `props.tsx`. */
+import type { ComponentChildren } from "preact";
+export { Properties } from "./props";
+/**
+ * Remove the selected node. The Delete key (app.tsx) and the tree's context menu share this, so both ask the same
+ * question before a bone takes its children's parent and its keys with it — and before a slot or an attachment
+ * takes away animation the user cannot see from the tree.
+ */
+export declare function deleteSelection(): void;
+/** `constraints` is the group heading — the one row that stands for no object of its own */
+type MenuAt = {
+    kind: "bone" | "slot" | "attachment" | "constraint" | "constraints";
+    id: string;
+    x: number;
+    y: number;
+};
+/** the tree's right-click menu; app.tsx closes it on Escape and on a press outside it */
+export declare const treeMenu: import("@preact/signals-core").Signal<MenuAt | undefined>;
+export declare const closeTreeMenu: () => undefined;
+/** a collapsible block of the left panel; the fold state lives in the store (and localStorage) */
+export declare function Section({ id, title, children }: {
+    id: string;
+    title: string;
+    children: ComponentChildren;
+}): import("preact").JSX.Element;
+export declare function Tree(): import("preact").JSX.Element | null;

package/dist/lib/editor/props.d.ts

@@ -0,0 +1,19 @@
+/**
+ * An input whose DOM value follows the document — but never while the user is typing into it, so a ticking
+ * playhead cannot rewrite the field under the cursor. Commits on `change` and on Enter (which then blurs);
+ * a blur that did not change the text commits nothing.
+ */
+export declare function Input({ name, value, type, step, class: cls, placeholder, onCommit }: {
+    name: string;
+    value: string;
+    type?: "text" | "number";
+    step?: number;
+    class?: string;
+    placeholder?: string;
+    onCommit: (v: string) => void;
+}): import("preact").JSX.Element;
+/**
+ * The right-hand panel: the form for what is selected, then — for the track picked in the timeline, whatever else
+ * is selected — its adjustment sliders and the selected key's easing.
+ */
+export declare function Properties(): import("preact").JSX.Element;

package/dist/lib/editor/server.d.ts

@@ -0,0 +1,11 @@
+export interface EditorServer {
+    port: number;
+    url: string;
+    close(): Promise<void>;
+}
+/** `root` — where the rigs live (every path in the API is relative to it); `assets` — where editor.html and dist/ are (default: this package). */
+export declare function startEditorServer(opts: {
+    root: string;
+    port?: number;
+    assets?: string;
+}): Promise<EditorServer>;

package/dist/lib/editor/stage.d.ts

@@ -0,0 +1,222 @@
+import { type Skeleton } from "../rig-anim";
+import { type Selection } from "./store";
+export declare class Stage {
+    private host;
+    private app;
+    private camera;
+    private paper;
+    private overlay;
+    private gfx;
+    private labels;
+    private labelPool;
+    private player?;
+    private textures?;
+    private assetKey;
+    private structKey;
+    private appliedOverlays;
+    private t;
+    private gen;
+    private fitted;
+    private destroyed;
+    private dispose;
+    private gizmo?;
+    private atlas?;
+    /** the sheet `atlas` was built for, and whether the atlas is what is on screen right now */
+    private atlasFor?;
+    private atlasOn;
+    /** the sheet is decoded and on screen in atlas mode (tests wait on it) */
+    get atlasReady(): boolean;
+    /**
+     * The bone gizmo override: while `from` is selected, the handles (and the drag) belong to `to` — the target bone
+     * of the IK that drives `from`. `syncGizmo` consults it and drops it as soon as it stops holding.
+     */
+    private redirect?;
+    /** gizmos read the shown document lazily, so the handles follow the draft while a gesture runs */
+    private ctx;
+    readonly ready: Promise<void>;
+    /** true when the Space held right now was used to pan — the keyboard map then skips the play/pause toggle */
+    pannedWithSpace: boolean;
+    constructor(host: HTMLElement);
+    private init;
+    /**
+     * A confirmed document: our own commits are by far the commonest, and they only change numbers, so try the
+     * cheap swap first (the draft path does the same) and rebuild only when the display objects themselves would
+     * differ — new textures, or a slot / attachment added, removed or retyped.
+     */
+    private applyDoc;
+    private rebuild;
+    /** a gesture's preview (or the confirmed document again when the gesture is cancelled): same structure, new numbers */
+    private applyDraft;
+    /** push the shown pose (and slot visibility) into the player, then redraw the overlay */
+    private applyPose;
+    private reference?;
+    private referenceSrc?;
+    /** the underlay is on screen — a texture loaded and the sprite visible (tests read it) */
+    get referenceShown(): boolean;
+    /** `meta.reference` → a sprite between the paper and the rig; re-decoded only when `src` changes */
+    private applyReference;
+    private startPlayback;
+    private tick;
+    /** doc px → screen px (canvas client coords); the camera never rotates, so this is exact without a render */
+    toScreen(x: number, y: number): [number, number];
+    toDoc(sx: number, sy: number): [number, number];
+    get zoom(): number;
+    /** true once the rig's display objects are on screen (textures loaded) */
+    get rendered(): boolean;
+    /**
+     * The status bar's readout: the pointer in document px and the camera scale. `pointermove` fires far faster
+     * than the screen refreshes, so the signals are written at most once per animation frame.
+     */
+    private at?;
+    private viewFrame;
+    private publishView;
+    /** the document fills the viewport with a margin — in atlas mode the sheet does, once it is decoded */
+    fit(): void;
+    /**
+     * The gizmo for the current selection: a bone always, a region attachment in setup mode, a grip on every
+     * selected mesh vertex — a whole mesh gets no transform box, it is edited through its vertices and the panel.
+     *
+     * The vertex gizmo reads `selectedVertices` lazily (through `.peek()`, so this effect is not re-entered): the
+     * list is the truth while several vertices are picked, and `selection.index` covers the moment a fresh pick has
+     * only set the primary one.
+     *
+     * A bone driven by a live IK is the one exception: `redirect` (set by the pointer handler) points the gizmo at
+     * the constraint's TARGET bone while the selection stays on the driven bone, so its form keeps showing. The
+     * redirection is re-checked here rather than remembered, so a changed selection or a deleted target drops it by
+     * itself. A mix faded to 0 drops it too, but only when this effect runs again (a new selection, a changed
+     * document) or at the next press: `syncGizmo` does not run on the playhead — that is what `liveGizmo` below is
+     * for, and why the redirected handles can outlive the mix that earned them by a few frames of playback.
+     */
+    private syncGizmo;
+    /**
+     * The constraint that owns a bone's transform right now, or undefined when the bone is free. Forwards to
+     * `driverAt` (rig-constraints.ts) over the editor's own `pose` signal (`poseOf(currentAnim, time)` in animate
+     * mode, rest otherwise) — the same sampler that function expects, and the same rule the solvers apply.
+     */
+    private driverOf;
+    /**
+     * The gizmo the pointer and the overlay may use: none at all while a live transform or path constraint owns the
+     * selected bone, since every drag on it is refused — grips (and their cursors) would promise an edit that cannot
+     * happen. Checked here rather than in `syncGizmo` because a keyed mix fades in and out under a still selection,
+     * and `syncGizmo` does not run on the playhead.
+     */
+    private get liveGizmo();
+    /**
+     * A press on the SELECTED bone when a constraint owns it. Writing such a bone by hand is silently undone by the
+     * next evaluation (the stage A review found this), so the gesture is moved or refused instead:
+     * - IK with a live mix → the drag is handed to the constraint's target bone (`redirect`), which is what posing
+     *   an IK limb means; the selection stays put so the panel still shows the bone that was clicked;
+     * - transform / path → nothing to hand it to: the press is refused and says where the value comes from.
+     *
+     * Only a press that grabs the DRIVEN bone's own handles is intercepted — once redirected, the target's grips are
+     * dragged like any other, and a press on empty canvas still picks. Under IK both `scale` grips are left alone:
+     * `applyIk` never writes `scaleY` and only writes `scaleX` under `stretch`, so scaling a chain bone on either
+     * axis is a real edit that must stay reachable (and the `scale` grip wins the tie at the bone's tip). The
+     * exemption is IK-SPECIFIC: a transform constraint with `mixScaleX`/`mixScaleY` (and a path one with
+     * `rotateMode: chainScale`) does write scale, so there a scale press falls through to the refusal below instead
+     * of promising an edit the next evaluation would undo. `alt` drops the redirection altogether (the user really
+     * does mean the local value); in `pick` the same modifier means "bones only", and the two agree.
+     */
+    private grabDriven;
+    /**
+     * End of a gizmo drag: exactly one tool call (one history snapshot) or nothing at all. The gesture flag is
+     * cleared whatever happens, so a throwing gizmo cannot wedge the editor into "a drag is in progress".
+     */
+    private endGesture;
+    /** the stroke in progress: which mesh it paints, and the confirmed weights it started from */
+    private stroke?;
+    /** the bone gesture in progress: the press (joint) and the live drag point (tip) */
+    private boneDraft?;
+    /**
+     * One brush step. It accumulates on what is already SHOWN (the previous step's draft), not on the confirmed
+     * document, so holding the brush over one spot keeps adding — that is what a paint stroke means.
+     */
+    private paintStep;
+    /** End of a stroke: one `rig_set_weights` when the weights actually moved, nothing at all otherwise. */
+    private endStroke;
+    /** the bone joint within 8 screen px of a document point, nearest wins — the picker's rule, also the brush's */
+    private nearestJoint;
+    /**
+     * Ctrl-click (or Cmd-click) on the SELECTED path's curve: one `rig_path_anchor insert` at the point clicked, or
+     * nothing at all when nothing is selected, the click misses the curve, or the split would land on an anchor —
+     * `false` tells the caller to fall through to the normal click instead of swallowing it. `hit.t` is
+     * `nearestOnPath`'s own parametrization of the curve, which is exactly what `pathAnchorOp` (via `splitCurve`)
+     * consumes, so there is no unit conversion between the two.
+     *
+     * The anchor guard is the same pick radius the grips use, applied to where the new anchor would GO: on an anchor
+     * `nearestOnPath` returns the sampled endpoint, so `t` is 0 or 1 and the tool refuses outright with a red error;
+     * a third of a pixel off one it returns `t = 0.0005` and the insert succeeds, leaving a second anchor on top of
+     * the first. Neither is what the hand meant — within grabbing distance of an anchor, the click meant the anchor,
+     * and falling through selects it.
+     */
+    private tryInsertAnchor;
+    /** camera (wheel zoom toward the cursor, middle button / Space+drag pan), gizmo drags, and click-to-select. */
+    private bindPointer;
+    /**
+     * World-space vertices of a mesh attachment (2 per vertex, the shown deform applied) — what the overlay draws,
+     * what the picker hits and what the properties panel reads. Throws for anything that is not a mesh.
+     */
+    meshWorld(id: string): number[];
+    /** the path attachment the selection is working on — the attachment itself, or the one an anchor belongs to */
+    private selectedPath;
+    /**
+     * The visible path (any path, selected or not — a path has no fill, so its curve is the only thing about it a
+     * click can land on) whose curve passes closest to (x, y), within `r` document px, or undefined. Same slots-loop
+     * and de-dup `drawPaths` uses, so this only offers what is actually on screen.
+     */
+    private nearestPathCurve;
+    /**
+     * What is under a point in document space: a vertex of the mesh (or an anchor of the path) being edited first,
+     * then the closest bone joint within 8 screen px, then that same mesh's own triangles, then the topmost
+     * attachment whose shape contains the point, then — last resort — the curve of any visible path, selected or
+     * not (a path has no fill, so this is the only way to pick one that is not already selected). `alt` skips
+     * vertices, attachments and path curves, and picks bones only.
+     *
+     * NB: a vertex hit also WRITES `selectedVertices` (that is where Shift-toggling lives) and returns the selection
+     * that goes with it — the caller must store what it gets back, or the two would disagree.
+     */
+    pick(x: number, y: number, alt?: boolean, shift?: boolean): Selection | undefined;
+    /** the shown attachments of visible slots, front to back — the order the player draws them, reversed */
+    private drawOrder;
+    /** current evaluated skeleton for the shown doc and pose — the store computes and memoizes it for everyone */
+    get skeleton(): Skeleton;
+    private drawOverlay;
+    /**
+     * The selected constraint: the bones it writes stroked over the normal skeleton in the warning colour (the last
+     * one out to its tip, where the chain ends), a dashed line from that tip to what the constraint reaches for, and
+     * a diamond on the target bone. A path constraint aims at a SLOT instead, so the dash runs to the nearest anchor
+     * of the curve that slot shows and the curve is stroked with it. Drawn only for the ONE selected constraint: a
+     * rig with 26 of them costs nothing while none is picked.
+     */
+    private drawConstraint;
+    /** a dashed segment: `Graphics` has no dash pattern, so the dashes are stepped by hand (60 of them at most) */
+    private dashed;
+    /**
+     * Every visible slot that SHOWS a path attachment strokes its curve — a path has no image, so without this the
+     * only thing on screen would be the bones it drives. Unselected it is a thin grey line; the selected attachment
+     * (or the one an anchor of which is selected) is stroked in the accent colour and grows a dot on every ANCHOR,
+     * exactly as a selected mesh does with its vertices. Costs one map lookup per slot when the rig has no path.
+     */
+    private drawPaths;
+    /**
+     * A path attachment's curve from its world control points. The vertices are `[cPrev, anchor, cNext]` triples, so
+     * curve i runs anchor i → cNext i → cPrev i+1 → anchor i+1 — the layout `samplePath` walks.
+     */
+    private strokePathCurve;
+    /**
+     * The selected mesh: its outline, a dot on every vertex (the selected ones accented) and — on demand, or once
+     * the zoom makes them readable — every triangle edge. Only the mesh the SELECTION is working on is drawn this
+     * way: a rig with a hundred meshes would otherwise spend its frame stroking edges nobody is looking at.
+     */
+    private drawMesh;
+    /**
+     * The weight heatmap of the mesh being painted: every triangle filled with the mean weight of the brush's bone
+     * over its corners (grey → accent), a dot per vertex in its own weight's colour, and the brush ring.
+     *
+     * Both the triangles and the dots are BATCHED by quantized weight — one `fill()` per colour level instead of
+     * one per shape. A 289-vertex mesh has ~540 triangles, and 540 separate fills is 540 draw calls a frame; 17
+     * levels is 17, whatever the mesh's size, and the quantization is invisible at alpha 0.35.
+     */
+    private drawWeights;
+    destroy(): void;
+}