@forgeax/engine-animation 0.1.2

package/dist/__tests__/morph-weights-playback.integration.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"morph-weights-playback.integration.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/morph-weights-playback.integration.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/morph-weights.unit.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=morph-weights.unit.test.d.ts.map

package/dist/__tests__/morph-weights.unit.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"morph-weights.unit.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/morph-weights.unit.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/public-animation-target-api.test-d.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=public-animation-target-api.test-d.d.ts.map

package/dist/__tests__/public-animation-target-api.test-d.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"public-animation-target-api.test-d.d.ts","sourceRoot":"","sources":["../../src/__tests__/public-animation-target-api.test-d.ts"],"names":[],"mappings":""}

package/dist/__tests__/resolver-ownership.integration.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=resolver-ownership.integration.test.d.ts.map

package/dist/__tests__/resolver-ownership.integration.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolver-ownership.integration.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/resolver-ownership.integration.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/root-surface.unit.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=root-surface.unit.test.d.ts.map

package/dist/__tests__/root-surface.unit.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"root-surface.unit.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/root-surface.unit.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/scene-instance-target-collection.integration.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=scene-instance-target-collection.integration.test.d.ts.map

package/dist/__tests__/scene-instance-target-collection.integration.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scene-instance-target-collection.integration.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/scene-instance-target-collection.integration.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/scriptable-pack-consumer.test-d.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=scriptable-pack-consumer.test-d.d.ts.map

package/dist/__tests__/scriptable-pack-consumer.test-d.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scriptable-pack-consumer.test-d.d.ts","sourceRoot":"","sources":["../../src/__tests__/scriptable-pack-consumer.test-d.ts"],"names":[],"mappings":""}

package/dist/__tests__/time-delta-regression.integration.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=time-delta-regression.integration.test.d.ts.map

package/dist/__tests__/time-delta-regression.integration.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"time-delta-regression.integration.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/time-delta-regression.integration.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/transform-target-playback.integration.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=transform-target-playback.integration.test.d.ts.map

package/dist/__tests__/transform-target-playback.integration.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transform-target-playback.integration.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/transform-target-playback.integration.test.ts"],"names":[],"mappings":""}

package/dist/animation-diagnostic.d.ts

@@ -0,0 +1,27 @@
+import type { World } from '@forgeax/engine-ecs';
+export type AnimationDiagnosticCode = 'animation-target-missing' | 'animation-target-transform-missing' | 'animation-target-id-duplicate' | 'animation-target-owner-stale' | 'animation-channel-missing' | 'animation-target-morph-weights-missing' | 'animation-morph-weight-count-mismatch';
+export interface AnimationDiagnosticDetail {
+    readonly player: number;
+    readonly clip: number;
+    readonly channel: number;
+    readonly targetId: string;
+    readonly reason: 'target-missing' | 'transform-missing' | 'target-id-duplicate' | 'target-stale' | 'channel-missing' | 'morph-weights-missing' | 'morph-weight-count-mismatch';
+    readonly target?: number;
+    readonly property?: 'translation' | 'rotation' | 'scale' | 'weights';
+    readonly expectedWeightCount?: number;
+    readonly actualWeightCount?: number;
+}
+export interface AnimationDiagnostic {
+    readonly code: AnimationDiagnosticCode;
+    readonly hint: string;
+    readonly detail: Readonly<AnimationDiagnosticDetail>;
+}
+export type AnimationDiagnosticListener = (world: World, diagnostic: Readonly<AnimationDiagnostic>) => void;
+/** Observe unique channel-level diagnostic facts for editor/runtime projection. */
+export declare function subscribeAnimationDiagnostics(listener: AnimationDiagnosticListener): () => void;
+/** @internal */
+export declare function isAnimationDevMode(): boolean;
+export declare function emitAnimationDiagnostic(world: World, diagnostic: AnimationDiagnostic): void;
+/** @internal */
+export declare function _resetAnimationWarnsForTests(world: World): void;
+//# sourceMappingURL=animation-diagnostic.d.ts.map

package/dist/animation-diagnostic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"animation-diagnostic.d.ts","sourceRoot":"","sources":["../src/animation-diagnostic.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AAEjD,MAAM,MAAM,uBAAuB,GAC/B,0BAA0B,GAC1B,oCAAoC,GACpC,+BAA+B,GAC/B,8BAA8B,GAC9B,2BAA2B,GAC3B,wCAAwC,GACxC,uCAAuC,CAAC;AAE5C,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EACX,gBAAgB,GAChB,mBAAmB,GACnB,qBAAqB,GACrB,cAAc,GACd,iBAAiB,GACjB,uBAAuB,GACvB,6BAA6B,CAAC;IAClC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,CAAC,EAAE,aAAa,GAAG,UAAU,GAAG,OAAO,GAAG,SAAS,CAAC;IACrE,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAC;IACtC,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;CACrC;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,IAAI,EAAE,uBAAuB,CAAC;IACvC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,yBAAyB,CAAC,CAAC;CACtD;AAED,MAAM,MAAM,2BAA2B,GAAG,CACxC,KAAK,EAAE,KAAK,EACZ,UAAU,EAAE,QAAQ,CAAC,mBAAmB,CAAC,KACtC,IAAI,CAAC;AAKV,mFAAmF;AACnF,wBAAgB,6BAA6B,CAAC,QAAQ,EAAE,2BAA2B,GAAG,MAAM,IAAI,CAG/F;AAED,gBAAgB;AAChB,wBAAgB,kBAAkB,IAAI,OAAO,CAI5C;AAED,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,KAAK,EAAE,UAAU,EAAE,mBAAmB,GAAG,IAAI,CAyB3F;AAED,gBAAgB;AAChB,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CAE/D"}

package/dist/animation-player.d.ts

@@ -0,0 +1,13 @@
+export declare const AnimationPlayer: import("@forgeax/engine-ecs").Component<"AnimationPlayer", {
+    readonly clips: "array<shared<AnimationClip>>";
+    readonly times: "array<f32>";
+    readonly weights: "array<f32>";
+    readonly speeds: "array<f32>";
+    readonly graph: "shared<AnimationGraph>";
+    readonly nodeWeights: "array<f32>";
+    readonly nodeTimes: "array<f32>";
+    readonly nodeSpeeds: "array<f32>";
+    readonly paused: "bool";
+    readonly looping: "bool";
+}>;
+//# sourceMappingURL=animation-player.d.ts.map

package/dist/animation-player.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"animation-player.d.ts","sourceRoot":"","sources":["../src/animation-player.ts"],"names":[],"mappings":"AAoEA,eAAO,MAAM,eAAe;;;;;;;;;;;EAe1B,CAAC"}

package/dist/animation-target.d.ts

@@ -0,0 +1,21 @@
+import { type EntityHandle, type World } from '@forgeax/engine-ecs';
+import { type Result } from '@forgeax/engine-types';
+export declare const AnimationTargetId: import("@forgeax/engine-ecs").Component<"AnimationTargetId", {
+    readonly value: "string";
+}>;
+export declare const AnimationTargets: import("@forgeax/engine-ecs").RelationshipTargetComponent<import("@forgeax/engine-ecs").Component<"AnimationTargets", {
+    targets: "array<entity>";
+}>>, AnimatedBy: import("@forgeax/engine-ecs").Component<"AnimatedBy", {
+    player: "entity";
+}>;
+export type BindAnimationTargetsErrorCode = 'animation-target-player-invalid' | 'animation-target-invalid' | 'animation-target-outside-player-root' | 'animation-target-name-missing' | 'animation-target-id-invalid' | 'animation-target-id-duplicate' | 'animation-target-player-conflict' | 'animation-target-capacity-reserve-failed' | 'animation-target-bind-failed';
+export declare class BindAnimationTargetsError extends Error {
+    readonly code: BindAnimationTargetsErrorCode;
+    readonly expected: string;
+    readonly hint: string;
+    readonly detail: Readonly<Record<string, unknown>>;
+    readonly name = "BindAnimationTargetsError";
+    constructor(code: BindAnimationTargetsErrorCode, expected: string, hint: string, detail: Readonly<Record<string, unknown>>);
+}
+export declare function bindAnimationTargets(world: World, player: EntityHandle, targets: readonly EntityHandle[]): Result<void, BindAnimationTargetsError>;
+//# sourceMappingURL=animation-target.d.ts.map

package/dist/animation-target.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"animation-target.d.ts","sourceRoot":"","sources":["../src/animation-target.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,YAAY,EACjB,KAAK,KAAK,EACX,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAAwC,KAAK,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAI1F,eAAO,MAAM,iBAAiB;;EAE5B,CAAC;AAEH,eAAO,MAAgB,gBAAgB;;KAAU,UAAU;;EAQzD,CAAC;AAEH,MAAM,MAAM,6BAA6B,GACrC,iCAAiC,GACjC,0BAA0B,GAC1B,sCAAsC,GACtC,+BAA+B,GAC/B,6BAA6B,GAC7B,+BAA+B,GAC/B,kCAAkC,GAClC,0CAA0C,GAC1C,8BAA8B,CAAC;AAEnC,qBAAa,yBAA0B,SAAQ,KAAK;IAIhD,QAAQ,CAAC,IAAI,EAAE,6BAA6B;IAC5C,QAAQ,CAAC,QAAQ,EAAE,MAAM;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM;IACrB,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IANpD,SAAkB,IAAI,+BAA+B;gBAG1C,IAAI,EAAE,6BAA6B,EACnC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAIrD;AAsHD,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,KAAK,EACZ,MAAM,EAAE,YAAY,EACpB,OAAO,EAAE,SAAS,YAAY,EAAE,GAC/B,MAAM,CAAC,IAAI,EAAE,yBAAyB,CAAC,CAsFzC"}

package/dist/assets/animation-decoder.d.ts

@@ -0,0 +1,4 @@
+import { type AnimationClip, type AnimationGraph, type AssetDecoderContribution } from '@forgeax/engine-types';
+export declare const animationClipContribution: AssetDecoderContribution<AnimationClip, 'animation-clip'>;
+export declare const animationGraphContribution: AssetDecoderContribution<AnimationGraph, 'animation-graph'>;
+//# sourceMappingURL=animation-decoder.d.ts.map

package/dist/assets/animation-decoder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"animation-decoder.d.ts","sourceRoot":"","sources":["../../src/assets/animation-decoder.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,aAAa,EAClB,KAAK,cAAc,EAEnB,KAAK,wBAAwB,EAI9B,MAAM,uBAAuB,CAAC;AAiD/B,eAAO,MAAM,yBAAyB,EAAE,wBAAwB,CAAC,aAAa,EAAE,gBAAgB,CAc7F,CAAC;AAEJ,eAAO,MAAM,0BAA0B,EAAE,wBAAwB,CAC/D,cAAc,EACd,iBAAiB,CA+BlB,CAAC"}

package/dist/chunk-DMXAQUPI.mjs

@@ -0,0 +1,52 @@
+// src/target-id.ts
+import { blake3 } from "@noble/hashes/blake3.js";
+var NAMESPACE = Uint8Array.of(
+  49,
+  121,
+  245,
+  25,
+  217,
+  39,
+  79,
+  242,
+  181,
+  150,
+  111,
+  208,
+  119,
+  2,
+  57,
+  17
+);
+var TARGET_ID_PATTERN = /^[0-9a-f]{32}$/;
+var textEncoder = new TextEncoder();
+function deriveAnimationTargetId(path) {
+  const segments = path.map((segment) => textEncoder.encode(segment));
+  const input = new Uint8Array(
+    NAMESPACE.length + segments.reduce((length, segment) => length + 4 + segment.length, 0)
+  );
+  input.set(NAMESPACE);
+  const view = new DataView(input.buffer);
+  let offset = NAMESPACE.length;
+  for (const segment of segments) {
+    view.setUint32(offset, segment.length, true);
+    offset += 4;
+    input.set(segment, offset);
+    offset += segment.length;
+  }
+  const bytes = blake3(input).slice(0, 16);
+  bytes[6] = (bytes[6] ?? 0) & 15 | 128;
+  bytes[8] = (bytes[8] ?? 0) & 63 | 128;
+  return Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join(
+    ""
+  );
+}
+function isAnimationTargetId(value) {
+  return typeof value === "string" && TARGET_ID_PATTERN.test(value);
+}
+
+export {
+  deriveAnimationTargetId,
+  isAnimationTargetId
+};
+//# sourceMappingURL=chunk-DMXAQUPI.mjs.map

package/dist/chunk-DMXAQUPI.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/target-id.ts"],"sourcesContent":["import type { AnimationTargetIdValue } from '@forgeax/engine-types';\nimport { blake3 } from '@noble/hashes/blake3.js';\n\nconst NAMESPACE = Uint8Array.of(\n  0x31,\n  0x79,\n  0xf5,\n  0x19,\n  0xd9,\n  0x27,\n  0x4f,\n  0xf2,\n  0xb5,\n  0x96,\n  0x6f,\n  0xd0,\n  0x77,\n  0x02,\n  0x39,\n  0x11,\n);\nconst TARGET_ID_PATTERN = /^[0-9a-f]{32}$/;\nconst textEncoder = new TextEncoder();\n\nexport function deriveAnimationTargetId(path: readonly string[]): AnimationTargetIdValue {\n  const segments = path.map((segment) => textEncoder.encode(segment));\n  const input = new Uint8Array(\n    NAMESPACE.length + segments.reduce((length, segment) => length + 4 + segment.length, 0),\n  );\n  input.set(NAMESPACE);\n\n  const view = new DataView(input.buffer);\n  let offset = NAMESPACE.length;\n  for (const segment of segments) {\n    view.setUint32(offset, segment.length, true);\n    offset += 4;\n    input.set(segment, offset);\n    offset += segment.length;\n  }\n\n  const bytes = blake3(input).slice(0, 16);\n  bytes[6] = ((bytes[6] ?? 0) & 0x0f) | 0x80;\n  bytes[8] = ((bytes[8] ?? 0) & 0x3f) | 0x80;\n  return Array.from(bytes, (byte) => byte.toString(16).padStart(2, '0')).join(\n    '',\n  ) as AnimationTargetIdValue;\n}\n\nexport function isAnimationTargetId(value: unknown): value is AnimationTargetIdValue {\n  return typeof value === 'string' && TARGET_ID_PATTERN.test(value);\n}\n"],"mappings":";AACA,SAAS,cAAc;AAEvB,IAAM,YAAY,WAAW;AAAA,EAC3B;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;AACA,IAAM,oBAAoB;AAC1B,IAAM,cAAc,IAAI,YAAY;AAE7B,SAAS,wBAAwB,MAAiD;AACvF,QAAM,WAAW,KAAK,IAAI,CAAC,YAAY,YAAY,OAAO,OAAO,CAAC;AAClE,QAAM,QAAQ,IAAI;AAAA,IAChB,UAAU,SAAS,SAAS,OAAO,CAAC,QAAQ,YAAY,SAAS,IAAI,QAAQ,QAAQ,CAAC;AAAA,EACxF;AACA,QAAM,IAAI,SAAS;AAEnB,QAAM,OAAO,IAAI,SAAS,MAAM,MAAM;AACtC,MAAI,SAAS,UAAU;AACvB,aAAW,WAAW,UAAU;AAC9B,SAAK,UAAU,QAAQ,QAAQ,QAAQ,IAAI;AAC3C,cAAU;AACV,UAAM,IAAI,SAAS,MAAM;AACzB,cAAU,QAAQ;AAAA,EACpB;AAEA,QAAM,QAAQ,OAAO,KAAK,EAAE,MAAM,GAAG,EAAE;AACvC,QAAM,CAAC,KAAM,MAAM,CAAC,KAAK,KAAK,KAAQ;AACtC,QAAM,CAAC,KAAM,MAAM,CAAC,KAAK,KAAK,KAAQ;AACtC,SAAO,MAAM,KAAK,OAAO,CAAC,SAAS,KAAK,SAAS,EAAE,EAAE,SAAS,GAAG,GAAG,CAAC,EAAE;AAAA,IACrE;AAAA,EACF;AACF;AAEO,SAAS,oBAAoB,OAAiD;AACnF,SAAO,OAAO,UAAU,YAAY,kBAAkB,KAAK,KAAK;AAClE;","names":[]}

package/dist/errors.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Structured error for an empty graph (zero nodes).
+ *
+ *   - `.code = 'animation-graph-empty'`
+ *   - `.expected` -- a graph declares at least one node
+ *   - `.hint` -- add at least one clip/blend/add node before returning the root
+ */
+export declare class AnimationGraphEmptyError extends Error {
+    readonly code: "animation-graph-empty";
+    readonly expected: string;
+    readonly hint: string;
+    constructor();
+}
+/** Detail for `'animation-graph-node-out-of-range'`. */
+export interface AnimationGraphNodeOutOfRangeDetail {
+    /** Index of the node holding the offending reference, or the graph root. */
+    readonly node: number;
+    /** The out-of-range reference value that was encountered. */
+    readonly ref: number;
+    /** Total node count -- valid refs live in `[0, nodeCount)`. */
+    readonly nodeCount: number;
+}
+/**
+ * Structured error for a node reference that points outside `[0, nodeCount)`.
+ *
+ *   - `.code = 'animation-graph-node-out-of-range'`
+ *   - `.expected` -- every child/base/additive/root ref is in `[0, nodeCount)`
+ *   - `.hint` -- reference only node refs returned by the builder in this graph
+ *   - `.detail = { node, ref, nodeCount }`
+ */
+export declare class AnimationGraphNodeOutOfRangeError extends Error {
+    readonly code: "animation-graph-node-out-of-range";
+    readonly expected: string;
+    readonly hint: string;
+    readonly detail: AnimationGraphNodeOutOfRangeDetail;
+    constructor(detail: AnimationGraphNodeOutOfRangeDetail);
+}
+/** Detail for `'animation-graph-node-weight-invalid'`. */
+export interface AnimationGraphNodeWeightInvalidDetail {
+    /** Index of the node whose static weight is invalid. */
+    readonly node: number;
+    /** The offending weight value (negative or non-finite / NaN). */
+    readonly weight: number;
+}
+/**
+ * Structured error for a negative or non-finite (NaN / Infinity) static weight.
+ *
+ *   - `.code = 'animation-graph-node-weight-invalid'`
+ *   - `.expected` -- every node static weight is a finite value `>= 0`
+ *   - `.hint` -- pass a finite non-negative weight (Add layers may exceed 1)
+ *   - `.detail = { node, weight }`
+ */
+export declare class AnimationGraphNodeWeightInvalidError extends Error {
+    readonly code: "animation-graph-node-weight-invalid";
+    readonly expected: string;
+    readonly hint: string;
+    readonly detail: AnimationGraphNodeWeightInvalidDetail;
+    constructor(detail: AnimationGraphNodeWeightInvalidDetail);
+}
+/** Detail for `'animation-graph-cycle'`. */
+export interface AnimationGraphCycleDetail {
+    /** A node index that participates in the detected cycle (the back edge). */
+    readonly node: number;
+}
+/**
+ * Structured error for a cycle in the (must-be-acyclic) graph.
+ *
+ *   - `.code = 'animation-graph-cycle'`
+ *   - `.expected` -- the graph is a DAG (no node reaches itself)
+ *   - `.hint` -- remove the self/back reference so the graph is acyclic
+ *   - `.detail = { node }`
+ */
+export declare class AnimationGraphCycleError extends Error {
+    readonly code: "animation-graph-cycle";
+    readonly expected: string;
+    readonly hint: string;
+    readonly detail: AnimationGraphCycleDetail;
+    constructor(detail: AnimationGraphCycleDetail);
+}
+/** Detail for `'animation-graph-clip-missing'`. */
+export interface AnimationGraphClipMissingDetail {
+    /** Index of the clip node whose `shared<AnimationClip>` handle failed to resolve. */
+    readonly node: number;
+    /** The raw clip handle that did not resolve (never registered / rc released). */
+    readonly clip: number;
+}
+/**
+ * Structured error for a graph clip leaf whose `shared<AnimationClip>` handle
+ * cannot be resolved at evaluation time (never registered, or its refcount was
+ * released). Raised by `evaluateAnimationGraph` (M3 / w25) BEFORE any derived
+ * slot is written, so a dangling clip never leaves a dirty pose (requirements
+ * AC-11 clip-missing branch, plan §8). Unlike the construction-time
+ * {@link AnimationGraphError} shapes, this is an EVALUATION-time error: it is not
+ * part of `defineAnimationGraph`'s `Result` (topology is validated at build, clip
+ * liveness only at eval), so it stays out of the construction closed union.
+ *
+ *   - `.code = 'animation-graph-clip-missing'`
+ *   - `.expected` -- every clip node's handle resolves to a live AnimationClip
+ *   - `.hint` -- keep the clip asset registered (rc retained) while the graph
+ *     references it
+ *   - `.detail = { node, clip }`
+ */
+export declare class AnimationGraphClipMissingError extends Error {
+    readonly code: "animation-graph-clip-missing";
+    readonly expected: string;
+    readonly hint: string;
+    readonly detail: AnimationGraphClipMissingDetail;
+    constructor(detail: AnimationGraphClipMissingDetail);
+}
+/**
+ * Closed union of AnimationGraph-cluster error codes. AI users perform
+ * exhaustive `switch (err.code)` without default; TS guards completeness.
+ */
+export type AnimationGraphErrorCode = 'animation-graph-empty' | 'animation-graph-node-out-of-range' | 'animation-graph-node-weight-invalid' | 'animation-graph-cycle';
+/**
+ * Closed union of the AnimationGraph-cluster structured error classes, each
+ * carrying an `AnimationGraphErrorCode` discriminant on `.code`.
+ */
+export type AnimationGraphError = AnimationGraphEmptyError | AnimationGraphNodeOutOfRangeError | AnimationGraphNodeWeightInvalidError | AnimationGraphCycleError;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAaA;;;;;;GAMG;AACH,qBAAa,wBAAyB,SAAQ,KAAK;IACjD,QAAQ,CAAC,IAAI,EAAG,uBAAuB,CAAU;IACjD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;;CASvB;AAID,wDAAwD;AACxD,MAAM,WAAW,kCAAkC;IACjD,4EAA4E;IAC5E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,6DAA6D;IAC7D,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,+DAA+D;IAC/D,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;;;GAOG;AACH,qBAAa,iCAAkC,SAAQ,KAAK;IAC1D,QAAQ,CAAC,IAAI,EAAG,mCAAmC,CAAU;IAC7D,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,kCAAkC,CAAC;gBAExC,MAAM,EAAE,kCAAkC;CAUvD;AAID,0DAA0D;AAC1D,MAAM,WAAW,qCAAqC;IACpD,wDAAwD;IACxD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,iEAAiE;IACjE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;GAOG;AACH,qBAAa,oCAAqC,SAAQ,KAAK;IAC7D,QAAQ,CAAC,IAAI,EAAG,qCAAqC,CAAU;IAC/D,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,qCAAqC,CAAC;gBAE3C,MAAM,EAAE,qCAAqC;CAQ1D;AAID,4CAA4C;AAC5C,MAAM,WAAW,yBAAyB;IACxC,4EAA4E;IAC5E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;GAOG;AACH,qBAAa,wBAAyB,SAAQ,KAAK;IACjD,QAAQ,CAAC,IAAI,EAAG,uBAAuB,CAAU;IACjD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,yBAAyB,CAAC;gBAE/B,MAAM,EAAE,yBAAyB;CAQ9C;AAID,mDAAmD;AACnD,MAAM,WAAW,+BAA+B;IAC9C,qFAAqF;IACrF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,iFAAiF;IACjF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,8BAA+B,SAAQ,KAAK;IACvD,QAAQ,CAAC,IAAI,EAAG,8BAA8B,CAAU;IACxD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,+BAA+B,CAAC;gBAErC,MAAM,EAAE,+BAA+B;CAQpD;AAID;;;GAGG;AACH,MAAM,MAAM,uBAAuB,GAC/B,uBAAuB,GACvB,mCAAmC,GACnC,qCAAqC,GACrC,uBAAuB,CAAC;AAE5B;;;GAGG;AACH,MAAM,MAAM,mBAAmB,GAC3B,wBAAwB,GACxB,iCAAiC,GACjC,oCAAoC,GACpC,wBAAwB,CAAC"}

package/dist/graph/define-animation-graph.d.ts

@@ -0,0 +1,42 @@
+import type { AnimationGraph, AnimationGraphNode } from '@forgeax/engine-types';
+import { type Result } from '@forgeax/engine-types';
+import { type AnimationGraphError } from '../errors';
+/**
+ * Opaque reference to a node inside the graph under construction. Branded so a
+ * raw number cannot be passed where a node ref is expected without an explicit
+ * cast (the illegal-graph tests forge refs deliberately). At runtime it is the
+ * node's index in {@link AnimationGraph.nodes}.
+ */
+export type AnimationGraphNodeRef = number & {
+    readonly __animationGraphNodeRef: unique symbol;
+};
+/**
+ * Declarative builder handed to the `defineAnimationGraph` callback. Exposes
+ * exactly the three node kinds (clip / blend / add) + nesting -- no FSM /
+ * transition / mask surface is reserved (OOS-1..4, charter F4). Each method
+ * appends a node and returns its {@link AnimationGraphNodeRef}.
+ */
+export interface AnimationGraphBuilder {
+    /** Add a Clip leaf sampling `clip` with the given static `weight` (default 1). */
+    clip(clip: string, weight?: number): AnimationGraphNodeRef;
+    /** Add a Blend node (normalizing lerp) over `children` with static `weight` (default 1). */
+    blend(children: readonly AnimationGraphNodeRef[], weight?: number): AnimationGraphNodeRef;
+    /** Add an Add node (non-normalizing) stacking `additive` layers onto `base`; static `weight` default 1. */
+    add(base: AnimationGraphNodeRef, additive: readonly AnimationGraphNodeRef[], weight?: number): AnimationGraphNodeRef;
+}
+/**
+ * Enumerate the child node indices a node references: clip -> none; blend ->
+ * its children; add -> `[base, ...additive]`. Exhaustive over the closed node
+ * union (charter P3). Shared by the validator here and describeAnimationGraph.
+ */
+export declare function animationGraphNodeChildren(node: AnimationGraphNode): readonly number[];
+/**
+ * Construct an {@link AnimationGraph} declaratively. The callback receives a
+ * builder, adds clip/blend/add nodes, and returns the ref of the root node.
+ * The graph's topology is validated at construction time; on success the POD is
+ * returned in `ok(graph)` ready to be minted into a `shared<AnimationGraph>`
+ * handle (AC-02) and serialized (AC-14). On an illegal topology a structured
+ * {@link AnimationGraphError} is returned in `err(...)` (AC-11).
+ */
+export declare function defineAnimationGraph(build: (builder: AnimationGraphBuilder) => AnimationGraphNodeRef): Result<AnimationGraph, AnimationGraphError>;
+//# sourceMappingURL=define-animation-graph.d.ts.map

package/dist/graph/define-animation-graph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-animation-graph.d.ts","sourceRoot":"","sources":["../../src/graph/define-animation-graph.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAChF,OAAO,EAAW,KAAK,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,EAGL,KAAK,mBAAmB,EAGzB,MAAM,WAAW,CAAC;AAEnB;;;;;GAKG;AACH,MAAM,MAAM,qBAAqB,GAAG,MAAM,GAAG;IAC3C,QAAQ,CAAC,uBAAuB,EAAE,OAAO,MAAM,CAAC;CACjD,CAAC;AAEF;;;;;GAKG;AACH,MAAM,WAAW,qBAAqB;IACpC,kFAAkF;IAClF,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,qBAAqB,CAAC;IAC3D,4FAA4F;IAC5F,KAAK,CAAC,QAAQ,EAAE,SAAS,qBAAqB,EAAE,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,qBAAqB,CAAC;IAC1F,2GAA2G;IAC3G,GAAG,CACD,IAAI,EAAE,qBAAqB,EAC3B,QAAQ,EAAE,SAAS,qBAAqB,EAAE,EAC1C,MAAM,CAAC,EAAE,MAAM,GACd,qBAAqB,CAAC;CAC1B;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,kBAAkB,GAAG,SAAS,MAAM,EAAE,CAStF;AAqGD;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,CAAC,OAAO,EAAE,qBAAqB,KAAK,qBAAqB,GAC/D,MAAM,CAAC,cAAc,EAAE,mBAAmB,CAAC,CAM7C"}

package/dist/graph/describe-animation-graph.d.ts

@@ -0,0 +1,37 @@
+import type { AnimationGraph, AnimationGraphNode } from '@forgeax/engine-types';
+/**
+ * Machine-readable description of a single graph node: its index in the
+ * construction order, its `type` discriminant, its static `weight`, and the
+ * child node indices it references (construction order, canonical child ordering).
+ */
+export interface AnimationGraphNodeDescription {
+    /** Index of this node in {@link AnimationGraphDescription.nodes} (construction order). */
+    readonly index: number;
+    /** Node kind discriminant (clip / blend / add). */
+    readonly type: AnimationGraphNode['type'];
+    /** The node's static weight (effective weight = runtime weight x static). */
+    readonly weight: number;
+    /** Child node indices referenced by this node (clip -> []), construction order. */
+    readonly children: readonly number[];
+}
+/**
+ * Machine-readable description of an entire {@link AnimationGraph}: the ordered
+ * per-node descriptions (construction order), the root node index, and the
+ * per-node static weights (a flat projection of each node's `weight`).
+ */
+export interface AnimationGraphDescription {
+    /** Per-node descriptions, in graph POD construction order. */
+    readonly nodes: readonly AnimationGraphNodeDescription[];
+    /** Index of the graph's root (output) node, in construction order. */
+    readonly root: number;
+    /** Per-node static weights, in construction order. */
+    readonly staticWeights: readonly number[];
+}
+/**
+ * Enumerate a validated {@link AnimationGraph}'s nodes, topology, root, and
+ * per-node static weights for machine-readable introspection (AC-12). Pure and
+ * read-only -- returns a fresh description derived from the POD in construction
+ * order so described indices match runtime `nodeWeights` indices.
+ */
+export declare function describeAnimationGraph(graph: AnimationGraph): AnimationGraphDescription;
+//# sourceMappingURL=describe-animation-graph.d.ts.map

package/dist/graph/describe-animation-graph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"describe-animation-graph.d.ts","sourceRoot":"","sources":["../../src/graph/describe-animation-graph.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAGhF;;;;GAIG;AACH,MAAM,WAAW,6BAA6B;IAC5C,0FAA0F;IAC1F,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,mDAAmD;IACnD,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC,MAAM,CAAC,CAAC;IAC1C,6EAA6E;IAC7E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,mFAAmF;IACnF,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;CACtC;AAED;;;;GAIG;AACH,MAAM,WAAW,yBAAyB;IACxC,8DAA8D;IAC9D,QAAQ,CAAC,KAAK,EAAE,SAAS,6BAA6B,EAAE,CAAC;IACzD,sEAAsE;IACtE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,sDAAsD;IACtD,QAAQ,CAAC,aAAa,EAAE,SAAS,MAAM,EAAE,CAAC;CAC3C;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,cAAc,GAAG,yBAAyB,CAavF"}

package/dist/graph/serialize-animation-graph.d.ts

@@ -0,0 +1,27 @@
+import type { AnimationGraph } from '@forgeax/engine-types';
+/**
+ * Resolves a Clip leaf's durable GUID string to the form stored in Pack
+ * `refs[]`. Returns `undefined` when the GUID is unavailable, which aborts
+ * serialization.
+ * The caller supplies this so serialize stays free of AssetRegistry / World
+ * coupling; the graph already carries durable GUID strings at this boundary.
+ */
+export type ClipGuidResolver = (clip: string) => string | undefined;
+/**
+ * Output of {@link serializeAnimationGraph}: the pack `payload` object (a flat
+ * `{ nodes, root }` shape where Clip leaves reference `refs[]` by index) plus the
+ * deduped `refs[]` array of clip GUID strings.
+ */
+export interface SerializedAnimationGraph {
+    readonly payload: Record<string, unknown>;
+    readonly refs: readonly string[];
+}
+/**
+ * Serialize an {@link AnimationGraph} POD into a pack payload + refs pair. Clip
+ * leaves are rewritten from durable GUIDs to deduped `refs[]` GUID indices via
+ * `resolveClipGuid`; Blend/Add node references and `root` (all intra-graph node
+ * indices) pass through. Returns `undefined` if any durable clip GUID cannot be
+ * resolved -- an unresolvable clip means the graph cannot be persisted losslessly.
+ */
+export declare function serializeAnimationGraph(graph: AnimationGraph, resolveClipGuid?: ClipGuidResolver): SerializedAnimationGraph | undefined;
+//# sourceMappingURL=serialize-animation-graph.d.ts.map

package/dist/graph/serialize-animation-graph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serialize-animation-graph.d.ts","sourceRoot":"","sources":["../../src/graph/serialize-animation-graph.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAE5D;;;;;;GAMG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC;AAEpE;;;;GAIG;AACH,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC1C,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;CAClC;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,cAAc,EACrB,eAAe,GAAE,gBAAiC,GACjD,wBAAwB,GAAG,SAAS,CAoCtC"}

package/dist/index.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Animation graphs, players, and stable Transform targets.
+ *
+ * AI consumers should collect explicit entities, call
+ * {@link bindAnimationTargets} once, then configure the existing
+ * {@link AnimationPlayer} directly or through {@link defineAnimationGraph}.
+ * Binding failures expose stable `code`, `hint`, and `detail` fields.
+ *
+ * @see ../README.md
+ */
+export type { AnimationDiagnostic, AnimationDiagnosticCode, AnimationDiagnosticDetail, AnimationDiagnosticListener, } from './animation-diagnostic';
+export { subscribeAnimationDiagnostics } from './animation-diagnostic';
+export { AnimationPlayer } from './animation-player';
+/** Stable target identity, explicit ownership, and atomic batch binding. */
+export { AnimatedBy, AnimationTargetId, AnimationTargets, type BindAnimationTargetsErrorCode, bindAnimationTargets, } from './animation-target';
+export { animationClipContribution, animationGraphContribution } from './assets/animation-decoder';
+/** Build the existing graph-to-player slot path; this is not an animation FSM. */
+export { type AnimationGraphNodeRef, animationGraphNodeChildren, defineAnimationGraph, } from './graph/define-animation-graph';
+export { describeAnimationGraph } from './graph/describe-animation-graph';
+export { serializeAnimationGraph } from './graph/serialize-animation-graph';
+export { animationPayloadsPlugin, animationPlugin, animationRuntimePlugin } from './plugin';
+export { AnimationAssetError, type AnimationAssetErrorCode, type AnimationAssetErrorDetail, resolveAnimationAsset, } from './resolve-animation-asset';
+export { _resetAnimationWarnsForTests, ADVANCE_ANIMATION_PLAYER_SYSTEM, AdvanceAnimationPlayer, AnimationSet, advanceAnimationPlayer, registerAdvanceAnimationPlayer, } from './systems/advance-animation-player';
+export type { AnimationPayloadLookup } from './systems/evaluate-animation-graph';
+export { EvaluateAnimationGraph, evaluateAnimationGraph, } from './systems/evaluate-animation-graph';
+/** Derive or validate the canonical 32-lowercase-hex animation target wire. */
+export { deriveAnimationTargetId, isAnimationTargetId } from './target-id';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,YAAY,EACV,mBAAmB,EACnB,uBAAuB,EACvB,yBAAyB,EACzB,2BAA2B,GAC5B,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,6BAA6B,EAAE,MAAM,wBAAwB,CAAC;AACvE,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,4EAA4E;AAC5E,OAAO,EACL,UAAU,EACV,iBAAiB,EACjB,gBAAgB,EAChB,KAAK,6BAA6B,EAClC,oBAAoB,GACrB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,yBAAyB,EAAE,0BAA0B,EAAE,MAAM,4BAA4B,CAAC;AACnG,kFAAkF;AAClF,OAAO,EACL,KAAK,qBAAqB,EAC1B,0BAA0B,EAC1B,oBAAoB,GACrB,MAAM,gCAAgC,CAAC;AACxC,OAAO,EAAE,sBAAsB,EAAE,MAAM,kCAAkC,CAAC;AAC1E,OAAO,EAAE,uBAAuB,EAAE,MAAM,mCAAmC,CAAC;AAC5E,OAAO,EAAE,uBAAuB,EAAE,eAAe,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAC;AAC5F,OAAO,EACL,mBAAmB,EACnB,KAAK,uBAAuB,EAC5B,KAAK,yBAAyB,EAC9B,qBAAqB,GACtB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EACL,4BAA4B,EAC5B,+BAA+B,EAC/B,sBAAsB,EACtB,YAAY,EACZ,sBAAsB,EACtB,8BAA8B,GAC/B,MAAM,oCAAoC,CAAC;AAC5C,YAAY,EAAE,sBAAsB,EAAE,MAAM,oCAAoC,CAAC;AACjF,OAAO,EACL,sBAAsB,EACtB,sBAAsB,GACvB,MAAM,oCAAoC,CAAC;AAC5C,+EAA+E;AAC/E,OAAO,EAAE,uBAAuB,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC"}