@energy8platform/golem 0.3.0 → 0.5.0

package/dist/lib/harness.js

@@ -49592,6 +49592,7 @@ ${parts.join("\n")}
   });
   var Interpolation = { interpolation: external_exports.enum(["segment", "pchip"]).optional() };
   var Track = external_exports.discriminatedUnion("target", [
+    external_exports.object({ target: external_exports.literal("control"), id: Id, prop: external_exports.literal("value"), ...Interpolation, keys: external_exports.array(Key).min(1) }),
     external_exports.object({ target: external_exports.literal("bone"), id: Id, prop: BoneProp, ...Interpolation, keys: external_exports.array(Key).min(1) }),
     external_exports.object({ target: external_exports.literal("slot"), id: Id, prop: SlotProp, ...Interpolation, keys: external_exports.array(Key).min(1) }),
     external_exports.object({ target: external_exports.literal("deform"), id: Id, prop: DeformProp, ...Interpolation, keys: external_exports.array(Key).min(1) }),
@@ -49614,6 +49615,25 @@ ${parts.join("\n")}
     /** if generated from a preset — keep params so the agent can re-tune instead of re-keying */
     preset: external_exports.object({ name: external_exports.string(), params: external_exports.record(external_exports.unknown()) }).optional()
   });
+  var RigControl = external_exports.object({
+    id: Id,
+    label: external_exports.string().optional(),
+    min: external_exports.number().finite(),
+    max: external_exports.number().finite(),
+    default: external_exports.number().finite()
+  }).strict();
+  var ControlValues = external_exports.array(external_exports.union([external_exports.number().finite(), external_exports.array(external_exports.number().finite()).min(1)])).min(2);
+  var ControlChannel = external_exports.discriminatedUnion("target", [
+    external_exports.object({ target: external_exports.literal("bone"), id: Id, prop: BoneProp, values: ControlValues }).strict(),
+    external_exports.object({ target: external_exports.literal("slot"), id: Id, prop: external_exports.literal("alpha"), values: ControlValues }).strict(),
+    external_exports.object({ target: external_exports.literal("deform"), id: Id, prop: external_exports.literal("vertices"), values: ControlValues }).strict()
+  ]);
+  var ControlBinding = external_exports.object({
+    id: Id,
+    axes: external_exports.array(external_exports.object({ control: Id, keys: external_exports.array(external_exports.number().finite()).min(2).max(32) }).strict()).min(1).max(2),
+    /** Flattened grid, first axis varies fastest. Linear / bilinear interpolation. */
+    channels: external_exports.array(ControlChannel).min(1)
+  }).strict();
   var Reference = external_exports.object({
     src: external_exports.string(),
     opacity: external_exports.number().min(0).max(1).default(0.5),
@@ -49639,7 +49659,9 @@ ${parts.join("\n")}
     ik: external_exports.array(IkConstraint).default([]),
     transform: external_exports.array(TransformConstraint).default([]),
     path: external_exports.array(PathConstraint).default([]),
-    animations: external_exports.array(Animation)
+    animations: external_exports.array(Animation),
+    controls: external_exports.array(RigControl).optional(),
+    controlBindings: external_exports.array(ControlBinding).optional()
   });
   var RigDocument = external_exports.preprocess((input) => {
     const v2 = input?.version;
@@ -49714,6 +49736,8 @@ ${parts.join("\n")}
     dup(doc.ik, "ik");
     dup(doc.transform, "transform");
     dup(doc.path, "path");
+    dup(doc.controls ?? [], "control");
+    dup(doc.controlBindings ?? [], "control binding");
     const bones = new Set(doc.bones.map((b2) => b2.id));
     const assets = new Map(doc.assets.map((a2) => [a2.id, a2]));
     const slots = new Set(doc.slots.map((s2) => s2.id));
@@ -49788,13 +49812,47 @@ ${parts.join("\n")}
       for (const b2 of c2.bones) if (!bones.has(b2)) errs.push(`path "${c2.id}": unknown bone "${b2}"`);
       if (!slots.has(c2.target)) errs.push(`path "${c2.id}": unknown target slot "${c2.target}"`);
     }
+    const controls = new Map((doc.controls ?? []).map((c2) => [c2.id, c2]));
+    const driven = /* @__PURE__ */ new Set();
+    for (const c2 of controls.values()) if (!(c2.min < c2.max && c2.default >= c2.min && c2.default <= c2.max))
+      errs.push(`control "${c2.id}": require min < max and default within range`);
+    for (const b2 of doc.controlBindings ?? []) {
+      const prefix = `control binding "${b2.id}"`;
+      if (new Set(b2.axes.map((a2) => a2.control)).size !== b2.axes.length) errs.push(`${prefix}: axes must use different controls`);
+      for (const axis of b2.axes) {
+        const c2 = controls.get(axis.control);
+        if (!c2) errs.push(`${prefix}: unknown control "${axis.control}"`);
+        else if (axis.keys[0] !== c2.min || axis.keys.at(-1) !== c2.max) errs.push(`${prefix}: keys must span the control's full range`);
+        if (axis.keys.some((v2, i2) => i2 > 0 && v2 <= axis.keys[i2 - 1])) errs.push(`${prefix}: keys must be strictly increasing`);
+      }
+      const count2 = b2.axes.reduce((n2, a2) => n2 * a2.keys.length, 1);
+      for (const ch of b2.channels) {
+        const key = `${ch.target}.${ch.id}.${ch.prop}`;
+        if (driven.has(key)) errs.push(`${prefix}: channel ${key} already owned by a binding`);
+        driven.add(key);
+        if (ch.values.length !== count2) errs.push(`${prefix}: ${key} needs ${count2} grid values`);
+        if (ch.target === "deform") {
+          const att = attachments.get(ch.id);
+          if (!att || att.type === "region") errs.push(`${prefix}: vertices need a mesh or path attachment`);
+          else {
+            const n2 = att.weights ? att.weights.reduce((s2, a2) => s2 + a2.length * 2, 0) : att.vertices.length;
+            if (ch.values.some((v2) => !Array.isArray(v2) || v2.length !== n2)) errs.push(`${prefix}: ${key} needs arrays of ${n2} offsets`);
+          }
+        } else {
+          if (!(ch.target === "bone" ? bones : slots).has(ch.id)) errs.push(`${prefix}: unknown ${ch.target} "${ch.id}"`);
+          if (ch.values.some((v2) => typeof v2 !== "number")) errs.push(`${prefix}: ${key} needs numeric values`);
+          if (ch.target === "slot" && ch.values.some((v2) => typeof v2 === "number" && (v2 < 0 || v2 > 1))) errs.push(`${prefix}: alpha must be in 0..1`);
+        }
+      }
+    }
     for (const a2 of doc.animations) {
       const tracks = /* @__PURE__ */ new Set();
       for (const t2 of a2.tracks) {
         const tid = trackId(t2);
         if (tracks.has(tid)) errs.push(`animation "${a2.id}": duplicate track ${tid}`);
         tracks.add(tid);
-        const known = t2.target === "bone" ? bones.has(t2.id) : t2.target === "slot" ? slots.has(t2.id) : t2.target === "deform" ? attachments.has(t2.id) : t2.target === "ik" ? iks.has(t2.id) : t2.target === "transform" ? transforms.has(t2.id) : t2.target === "path" ? paths.has(t2.id) : true;
+        if (driven.has(tid)) errs.push(`animation "${a2.id}": ${tid} is controlled by a binding; animate its control instead`);
+        const known = t2.target === "bone" ? bones.has(t2.id) : t2.target === "slot" ? slots.has(t2.id) : t2.target === "deform" ? attachments.has(t2.id) : t2.target === "ik" ? iks.has(t2.id) : t2.target === "transform" ? transforms.has(t2.id) : t2.target === "path" ? paths.has(t2.id) : t2.target === "control" ? controls.has(t2.id) : true;
         if (!known) errs.push(`animation "${a2.id}": unknown ${t2.target} "${t2.id}"`);
         const bound = t2.target === "deform" ? DEFORM_BOUNDS[t2.prop] : void 0;
         const att = t2.target === "deform" ? attachments.get(t2.id) : void 0;
@@ -49802,6 +49860,10 @@ ${parts.join("\n")}
         for (const k2 of t2.keys) {
           if (k2.t <= prev && prev >= 0) errs.push(`animation "${a2.id}" ${tid}: keys not strictly increasing`);
           if (k2.t > a2.duration) errs.push(`animation "${a2.id}" ${tid}: key at ${k2.t}s exceeds duration`);
+          if (t2.target === "control") {
+            const c2 = controls.get(t2.id);
+            if (typeof k2.v !== "number" || !Number.isFinite(k2.v) || c2 && (k2.v < c2.min || k2.v > c2.max)) errs.push(`animation "${a2.id}" ${tid}: control key outside its finite range`);
+          }
           if (t2.target === "slot" && t2.prop === "attachment") {
             if (k2.v !== null && typeof k2.v !== "string") errs.push(`animation "${a2.id}" ${tid}: attachment key must be an attachment id or null`);
             else if (typeof k2.v === "string") {
@@ -49840,6 +49902,52 @@ ${parts.join("\n")}
     return doc;
   }
 
+  // src/rig-controls.ts
+  function controlPose(doc, values) {
+    const out2 = /* @__PURE__ */ new Map();
+    for (const [id, value] of Object.entries(values)) {
+      const c2 = doc.controls?.find((c3) => c3.id === id);
+      if (!c2) throw new Error(`unknown control "${id}"`);
+      if (!Number.isFinite(value)) throw new Error(`control "${id}" must be finite`);
+      out2.set(`control:${id}:value`, Math.max(c2.min, Math.min(c2.max, value)));
+    }
+    return out2;
+  }
+  function bracket(keys, value) {
+    let i2 = 0;
+    while (i2 < keys.length - 2 && value > keys[i2 + 1]) i2++;
+    return [i2, Math.max(0, Math.min(1, (value - keys[i2]) / (keys[i2 + 1] - keys[i2])))];
+  }
+  function sampleBinding(binding, values) {
+    const [x2, u2] = bracket(binding.axes[0].keys, values[0]);
+    const [y2, v2] = binding.axes[1] ? bracket(binding.axes[1].keys, values[1]) : [0, 0];
+    const width = binding.axes[0].keys.length, a2 = y2 * width + x2;
+    const mix = (a3, b2, u3) => a3 + (b2 - a3) * u3;
+    return binding.channels.map((ch) => {
+      const read = (i2, j2) => j2 === void 0 ? ch.values[i2] : ch.values[i2][j2];
+      const at = (j2) => {
+        const top = mix(read(a2, j2), read(a2 + 1, j2), u2);
+        return binding.axes[1] ? mix(top, mix(read(a2 + width, j2), read(a2 + width + 1, j2), u2), v2) : top;
+      };
+      return Array.isArray(ch.values[0]) ? ch.values[0].map((_, j2) => at(j2)) : at();
+    });
+  }
+  function resolveControls(doc, input) {
+    if (!doc.controlBindings?.length) return input;
+    const out2 = new Map(input), controls = new Map(doc.controls?.map((c2) => [c2.id, c2]));
+    for (const b2 of doc.controlBindings) {
+      const values = b2.axes.map((axis) => {
+        const c2 = controls.get(axis.control);
+        const value = input.get(`control:${c2.id}:value`) ?? c2.default;
+        if (typeof value !== "number" || !Number.isFinite(value)) throw new Error(`control "${c2.id}" must be finite`);
+        return Math.max(c2.min, Math.min(c2.max, value));
+      });
+      const sampled = sampleBinding(b2, values);
+      b2.channels.forEach((ch, i2) => out2.set(`${ch.target}:${ch.id}:${ch.prop}`, sampled[i2]));
+    }
+    return out2;
+  }
+
   // src/rig-anim.ts
   var DEG2 = Math.PI / 180;
   var named = {
@@ -49943,6 +50051,7 @@ ${parts.join("\n")}
   }
   function restValue(doc, key) {
     const [target, id, prop] = key.split(":");
+    if (target === "control") return doc.controls?.find((c2) => c2.id === id)?.default ?? 0;
     if (target === "bone") return doc.bones.find((b2) => b2.id === id).transform[prop];
     if (target === "slot") {
       const s2 = doc.slots.find((s3) => s3.id === id);
@@ -50045,7 +50154,9 @@ ${parts.join("\n")}
       for (const k2 of kids.get(id) ?? []) stack.push(k2.id);
     }
   }
-  function evaluate(doc, pose) {
+  function evaluate(doc, pose, modifiers) {
+    pose = resolveControls(doc, pose);
+    if (modifiers) for (const modify of modifiers) pose = modify(new Map(pose));
     const skel = { doc, pose, bones: /* @__PURE__ */ new Map(), attachment: /* @__PURE__ */ new Map() };
     for (const b2 of boneOrder(doc)) {
       const s2 = localOf(doc, pose, b2);
@@ -50850,9 +50961,23 @@ ${parts.join("\n")}
       this.state = new AnimationState(this, { ...opts, mix: opts.mix ?? 0.18 });
       this.setPose(/* @__PURE__ */ new Map());
     }
+    inputPose = /* @__PURE__ */ new Map();
+    controlOverrides = /* @__PURE__ */ new Map();
+    /** Manual inputs override animated controls until resetControls; values are clamped to declared ranges. */
+    setControls(values) {
+      this.controlOverrides = controlPose(this.doc, values);
+      this.setPose(this.inputPose);
+    }
+    resetControls() {
+      this.controlOverrides.clear();
+      this.setPose(this.inputPose);
+    }
     view = new Container();
     state;
     items = [];
+    beforePose = /* @__PURE__ */ new Set();
+    afterPose = /* @__PURE__ */ new Set();
+    clipPoints = /* @__PURE__ */ new Map();
     skel;
     textures;
     pages = /* @__PURE__ */ new Map();
@@ -50861,6 +50986,35 @@ ${parts.join("\n")}
     /** slots the editor has selected; setPose draws them at GHOST_ALPHA at least */
     ghosts = /* @__PURE__ */ new Set();
     clipGraphics = /* @__PURE__ */ new Map();
+    /** Read-only render handles for in-page tools. Nodes remain owned by the player. */
+    get renderItems() {
+      return this.items;
+    }
+    /** Current document-space clipping polygons, keyed by path attachment id. */
+    get clipPolygons() {
+      return this.clipPoints;
+    }
+    /**
+     * Modify resolved control outputs before skeleton evaluation, constraints and skinning.
+     * Callbacks run in registration order, each with its own map. Change control inputs via setControls.
+     */
+    onBeforePose(callback) {
+      this.beforePose.add(callback);
+      return () => {
+        this.beforePose.delete(callback);
+      };
+    }
+    /** Subscribe after the base pose has been rebuilt. Return value removes the callback. */
+    onAfterPose(callback) {
+      this.afterPose.add(callback);
+      return () => {
+        this.afterPose.delete(callback);
+      };
+    }
+    /** Rebuild the current pose without advancing playback; useful for reversible overlays. */
+    refreshPose() {
+      this.setPose(this.inputPose);
+    }
     /** whole atlas page as a plain texture (identity uv mapping) for skinned meshes */
     pageTexture(tex) {
       let page = this.pages.get(tex.source);
@@ -50915,7 +51069,11 @@ ${parts.join("\n")}
     }
     /** Apply a pose (rest where silent) to the display objects. */
     setPose(pose) {
-      const skel = this.skel = evaluate(this.doc, pose);
+      this.inputPose = new Map(pose);
+      if (this.controlOverrides.size) pose = new Map([...pose, ...this.controlOverrides]);
+      this.clipPoints.clear();
+      const skel = this.skel = evaluate(this.doc, pose, this.beforePose);
+      pose = skel.pose;
       const clips = new Set(this.doc.slots.flatMap((s2) => s2.clip ? [s2.clip] : []));
       for (const [id, g2] of this.clipGraphics) if (!clips.has(id)) {
         g2.destroy();
@@ -50933,7 +51091,9 @@ ${parts.join("\n")}
         const vertices = attachmentWorldVertices(skel, att.slot, att);
         const n2 = Math.max(32, vertices.length * 4);
         const points = samplePath(vertices, true, att.lengths, true, Array.from({ length: n2 }, (_, i2) => i2 / n2), true);
-        g2.clear().poly(points.flatMap((p2) => [p2.x, p2.y]), true).fill(16777215);
+        const polygon = points.flatMap((p2) => [p2.x, p2.y]);
+        this.clipPoints.set(id, polygon);
+        g2.clear().poly(polygon, true).fill(16777215);
       }
       const m2 = new Matrix();
       const orderV = pose.get(pk("drawOrder", "order", "order"));
@@ -50954,6 +51114,7 @@ ${parts.join("\n")}
         it.node.tint = rgbOf(color);
         it.node.zIndex = order.size ? order.get(s2.id) ?? 0 : numOf(pose, pk("slot", s2.id, "z"), s2.z);
         if (it.skinned) {
+          it.node.setFromMatrix(m2.identity());
           const v2 = attachmentWorldVertices(skel, s2.id, it.att);
           const buf = it.skinned.mesh.geometry.getBuffer("aPosition");
           buf.data.set(v2);
@@ -50986,6 +51147,7 @@ ${parts.join("\n")}
           it.node.scale.y *= h2 / (this.textures.get(att.asset)?.height ?? h2);
         }
       }
+      for (const callback of this.afterPose) callback(this);
     }
     /** World-space bone positions — used by editor gizmos and renderPreview overlays */
     bonePositions() {

package/dist/lib/interactive-bones.d.ts

@@ -0,0 +1,37 @@
+import type { RigPlayer } from "./rig-runtime";
+import type { PartTransform } from "./interactive-editor";
+export interface BoneEditPatch {
+    format: "golem.bone-edits";
+    version: 1;
+    documentId: string;
+    transforms: Record<string, PartTransform>;
+}
+export interface InteractiveBoneEditorOptions {
+    player: Pick<RigPlayer, "doc" | "onBeforePose" | "refreshPose">;
+    documentId: string;
+    onChange?: (patch: BoneEditPatch) => void;
+    onRender?: () => void;
+    historyLimit?: number;
+}
+/** Add bone offsets after expression controls, before constraints and native skinning. */
+export declare function createInteractiveBoneEditor(options: InteractiveBoneEditorOptions): {
+    getTransform: (id: string) => {
+        x: number;
+        y: number;
+        rotation: number;
+        scaleX: number;
+        scaleY: number;
+    };
+    exportPatch: () => BoneEditPatch;
+    validatePatch: (value: unknown) => BoneEditPatch;
+    readonly canUndo: boolean;
+    readonly canRedo: boolean;
+    setTransform(id: string, value: Partial<PartTransform>): void;
+    importPatch(value: unknown): void;
+    reset(id?: string): void;
+    setVisible(value: boolean): void;
+    undo(): void;
+    redo(): void;
+    dispose(): void;
+};
+export type InteractiveBoneEditor = ReturnType<typeof createInteractiveBoneEditor>;

package/dist/lib/interactive-editor.d.ts

@@ -0,0 +1,80 @@
+import type { RigPlayer } from "./rig-runtime";
+export interface EditorPoint {
+    x: number;
+    y: number;
+}
+export interface PartTransform {
+    x: number;
+    y: number;
+    rotation: number;
+    scaleX: number;
+    scaleY: number;
+}
+export interface InteractiveEditPatch {
+    format: "golem.interactive-edits";
+    version: 1;
+    documentId: string;
+    transforms: Record<string, PartTransform>;
+}
+export interface EditorGroup {
+    id: string;
+    members: readonly string[];
+    pivotBone?: string;
+}
+export type InteractivePlayer = Pick<RigPlayer, "doc" | "view" | "world" | "renderItems" | "clipPolygons" | "onAfterPose" | "refreshPose">;
+export interface InteractiveEditorOptions {
+    player: InteractivePlayer;
+    /** Transparent overlay aligned with the player's rendered viewport. It is cleared by the editor. */
+    overlay: HTMLCanvasElement;
+    /** Host-defined stable rig fingerprint; mismatched patches are rejected. */
+    documentId: string;
+    groups?: readonly EditorGroup[];
+    /** Override when overlay backing pixels differ from the renderer's logical coordinates. */
+    screenToDocument?: (client: EditorPoint) => EditorPoint;
+    documentToOverlay?: (point: EditorPoint) => EditorPoint;
+    alphaFallback?: "skip" | "geometry";
+    onChange?: (patch: InteractiveEditPatch) => void;
+    onSelection?: (id: string | null) => void;
+    onHover?: (id: string | null) => void;
+    onError?: (error: Error) => void;
+    onGestureStart?: () => void;
+    /** Render the host scene after a manual refresh; never called from the pose hook. */
+    onRender?: () => void;
+    historyLimit?: number;
+}
+export interface EditorFrame {
+    id: string;
+    center: EditorPoint;
+    corners: EditorPoint[];
+    handles: {
+        name: string;
+        p: EditorPoint;
+    }[];
+}
+/** Embedded part editor. Source documents are never mutated; edits replay after every evaluated pose. */
+export declare function createInteractiveEditor(options: InteractiveEditorOptions): {
+    select: (id: string | null) => void;
+    hitTest: (p: EditorPoint) => string | null;
+    getFrame: (id: string) => EditorFrame | null;
+    getTransform: (id: string) => {
+        x: number;
+        y: number;
+        rotation: number;
+        scaleX: number;
+        scaleY: number;
+    };
+    readonly selection: string | null;
+    readonly canUndo: boolean;
+    readonly canRedo: boolean;
+    exportPatch: () => InteractiveEditPatch;
+    setEnabled(value: boolean): void;
+    setVisible(value: boolean): void;
+    setTransform(id: string, value: Partial<PartTransform>): void;
+    reset(id?: string): void;
+    undo(): void;
+    redo(): void;
+    importPatch(value: unknown): void;
+    dispose(): void;
+};
+export type InteractiveEditor = ReturnType<typeof createInteractiveEditor>;
+export { createInteractiveBoneEditor, type BoneEditPatch, type InteractiveBoneEditorOptions } from "./interactive-bones";