@vizij/animation-react 0.0.1

package/dist/index.d.cts

@@ -0,0 +1,123 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+import { StoredAnimation, Config, OutputsWithDerivatives, Value as Value$1, Inputs, InstanceUpdate, AnimationInfo, PlayerInfo, InstanceInfo, BakingConfig, BakedAnimationData, BakedAnimationBundle, listAnimationFixtures, loadAnimationFixture, loadAnimationJson, resolveAnimationPath } from '@vizij/animation-wasm';
+export { listAnimationFixtures, loadAnimationFixture, loadAnimationJson, resolveAnimationPath } from '@vizij/animation-wasm';
+import { NormalizedTransform } from '@vizij/value-json';
+
+type Value = Value$1;
+type InstanceSpec = {
+    playerName: string;
+    /** Which animation index in `animations` array to attach; defaults to 0 */
+    animIndex?: number;
+    /** Optional raw InstanceCfg JSON; pass-through to engine.addInstance */
+    cfg?: unknown;
+};
+type AnimationProviderProps = {
+    children: ReactNode;
+    /** One or more StoredAnimation objects to load on mount (and when identity changes) */
+    animations: StoredAnimation[] | StoredAnimation;
+    /**
+     * Instances to create on mount. If omitted, a single player "default" with the 0th animation is created.
+     * Example: [{ playerName: "demo", animIndex: 0 }]
+     */
+    instances?: InstanceSpec[];
+    /**
+     * Optional: Prebind resolver mapping canonical target paths to keys.
+     * Return string | number | null/undefined. Numbers will be coerced to string in the WASM layer.
+     */
+    prebind?: (path: string) => string | number | null | undefined;
+    /** Start an internal RAF loop that calls engine.update(dt) each frame */
+    autostart?: boolean;
+    /** Throttle UI notifications (Hz). Default: notify every frame while autostarting */
+    updateHz?: number;
+    /** Optional engine configuration for Engine constructor. Changing this re-initializes the Engine. */
+    engineConfig?: Config;
+    /** Optional callback to receive raw Outputs each update (includes events and derivatives). */
+    onOutputs?: (out: OutputsWithDerivatives) => void;
+};
+type AnimationContextValue = {
+    ready: boolean;
+    /** Subscribe to changes for a given resolved target key; returns unsubscribe */
+    subscribeToKey: (key: string, cb: () => void) => () => void;
+    /** Snapshot accessor for latest Value of a given resolved target key */
+    getKeySnapshot: (key: string) => Value | undefined;
+    /** Subscribe to derivative changes for a resolved target key */
+    subscribeToDerivativeKey: (key: string, cb: () => void) => () => void;
+    /** Snapshot accessor for latest derivative of a given resolved target key */
+    getKeyDerivativeSnapshot: (key: string) => Value | undefined;
+    /** Subscribe to per-player key changes */
+    subscribeToPlayerKey: (player: string | number, key: string, cb: () => void) => () => void;
+    /** Snapshot accessor for per-player key */
+    getPlayerKeySnapshot: (player: string | number, key: string) => Value | undefined;
+    /** Subscribe to per-player derivative changes */
+    subscribeToPlayerDerivative: (player: string | number, key: string, cb: () => void) => () => void;
+    /** Snapshot accessor for per-player derivatives */
+    getPlayerDerivativeSnapshot: (player: string | number, key: string) => Value | undefined;
+    /** Get latest values grouped by player name */
+    getLatestValuesByPlayer: () => Record<string, Record<string, Value>>;
+    /** Get latest derivatives grouped by player name */
+    getLatestDerivativesByPlayer: () => Record<string, Record<string, Value>>;
+    /** Manual step; useful when autostart=false */
+    step: (dt: number, inputs?: Inputs) => void;
+    /** Reload animations and instances at runtime */
+    reload: (animations: StoredAnimation[] | StoredAnimation, instances?: InstanceSpec[]) => void;
+    /** Append one or more animations without resetting existing state; returns new AnimIds (numbers) */
+    addAnimations: (animations: StoredAnimation[] | StoredAnimation) => number[];
+    /** Ensure a player exists with this name; returns PlayerId (number) */
+    addPlayer: (name: string) => number;
+    /** Add one or more instances to players; resolves animation by index or explicit id */
+    addInstances: (specs: {
+        playerName: string;
+        animIndexOrId: number;
+        cfg?: unknown;
+    }[]) => {
+        playerName: string;
+        instId: number;
+    }[];
+    /** Get instance ids for a given player (local cache; prefer listInstances for engine truth) */
+    getInstances: (playerName: string) => number[];
+    /** Apply instance-level updates immediately */
+    updateInstances: (updates: InstanceUpdate[]) => void;
+    /** Enumerate engine state (authoritative) */
+    listAnimations: () => AnimationInfo[];
+    listPlayers: () => PlayerInfo[];
+    listInstances: (player: string | number) => InstanceInfo[];
+    /** Keys currently associated with a player's instances */
+    listPlayerKeys: (player: string | number) => string[];
+    /** Removals */
+    removePlayer: (player: string | number) => boolean;
+    removeInstances: (specs: {
+        playerName: string;
+        instId: number;
+    }[]) => {
+        playerName: string;
+        instId: number;
+    }[];
+    unloadAnimations: (animIds: number[]) => number[];
+    /** Baking helpers */
+    bakeAnimation: (animIndexOrId: number, cfg?: BakingConfig) => BakedAnimationData | null;
+    bakeAnimationWithDerivatives: (animIndexOrId: number, cfg?: BakingConfig) => BakedAnimationBundle | null;
+    /** Optional: expose player name to id mapping for controls */
+    players: Record<string, number>;
+};
+
+declare function AnimationProvider({ children, animations, instances, prebind, autostart, updateHz, engineConfig, onOutputs, }: AnimationProviderProps): react_jsx_runtime.JSX.Element;
+
+declare function useAnimation(): AnimationContextValue;
+
+declare function useAnimTarget(key?: string): Value | undefined;
+
+declare function useAnimDerivative(key?: string): Value | undefined;
+
+declare function valueAsNumber(v: Value | undefined): number | undefined;
+declare function valueAsNumericArray(v: Value | undefined, fallback?: number): number[] | undefined;
+declare function valueAsTransform(v: Value | undefined): NormalizedTransform | undefined;
+
+declare const samples: {
+    readonly list: typeof listAnimationFixtures;
+    readonly load: typeof loadAnimationFixture;
+    readonly loadJson: typeof loadAnimationJson;
+    readonly resolvePath: typeof resolveAnimationPath;
+};
+
+export { AnimationProvider, type Value, samples, useAnimDerivative, useAnimTarget, useAnimation, valueAsNumber, valueAsNumericArray, valueAsTransform };

package/dist/index.d.ts

@@ -0,0 +1,123 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+import { StoredAnimation, Config, OutputsWithDerivatives, Value as Value$1, Inputs, InstanceUpdate, AnimationInfo, PlayerInfo, InstanceInfo, BakingConfig, BakedAnimationData, BakedAnimationBundle, listAnimationFixtures, loadAnimationFixture, loadAnimationJson, resolveAnimationPath } from '@vizij/animation-wasm';
+export { listAnimationFixtures, loadAnimationFixture, loadAnimationJson, resolveAnimationPath } from '@vizij/animation-wasm';
+import { NormalizedTransform } from '@vizij/value-json';
+
+type Value = Value$1;
+type InstanceSpec = {
+    playerName: string;
+    /** Which animation index in `animations` array to attach; defaults to 0 */
+    animIndex?: number;
+    /** Optional raw InstanceCfg JSON; pass-through to engine.addInstance */
+    cfg?: unknown;
+};
+type AnimationProviderProps = {
+    children: ReactNode;
+    /** One or more StoredAnimation objects to load on mount (and when identity changes) */
+    animations: StoredAnimation[] | StoredAnimation;
+    /**
+     * Instances to create on mount. If omitted, a single player "default" with the 0th animation is created.
+     * Example: [{ playerName: "demo", animIndex: 0 }]
+     */
+    instances?: InstanceSpec[];
+    /**
+     * Optional: Prebind resolver mapping canonical target paths to keys.
+     * Return string | number | null/undefined. Numbers will be coerced to string in the WASM layer.
+     */
+    prebind?: (path: string) => string | number | null | undefined;
+    /** Start an internal RAF loop that calls engine.update(dt) each frame */
+    autostart?: boolean;
+    /** Throttle UI notifications (Hz). Default: notify every frame while autostarting */
+    updateHz?: number;
+    /** Optional engine configuration for Engine constructor. Changing this re-initializes the Engine. */
+    engineConfig?: Config;
+    /** Optional callback to receive raw Outputs each update (includes events and derivatives). */
+    onOutputs?: (out: OutputsWithDerivatives) => void;
+};
+type AnimationContextValue = {
+    ready: boolean;
+    /** Subscribe to changes for a given resolved target key; returns unsubscribe */
+    subscribeToKey: (key: string, cb: () => void) => () => void;
+    /** Snapshot accessor for latest Value of a given resolved target key */
+    getKeySnapshot: (key: string) => Value | undefined;
+    /** Subscribe to derivative changes for a resolved target key */
+    subscribeToDerivativeKey: (key: string, cb: () => void) => () => void;
+    /** Snapshot accessor for latest derivative of a given resolved target key */
+    getKeyDerivativeSnapshot: (key: string) => Value | undefined;
+    /** Subscribe to per-player key changes */
+    subscribeToPlayerKey: (player: string | number, key: string, cb: () => void) => () => void;
+    /** Snapshot accessor for per-player key */
+    getPlayerKeySnapshot: (player: string | number, key: string) => Value | undefined;
+    /** Subscribe to per-player derivative changes */
+    subscribeToPlayerDerivative: (player: string | number, key: string, cb: () => void) => () => void;
+    /** Snapshot accessor for per-player derivatives */
+    getPlayerDerivativeSnapshot: (player: string | number, key: string) => Value | undefined;
+    /** Get latest values grouped by player name */
+    getLatestValuesByPlayer: () => Record<string, Record<string, Value>>;
+    /** Get latest derivatives grouped by player name */
+    getLatestDerivativesByPlayer: () => Record<string, Record<string, Value>>;
+    /** Manual step; useful when autostart=false */
+    step: (dt: number, inputs?: Inputs) => void;
+    /** Reload animations and instances at runtime */
+    reload: (animations: StoredAnimation[] | StoredAnimation, instances?: InstanceSpec[]) => void;
+    /** Append one or more animations without resetting existing state; returns new AnimIds (numbers) */
+    addAnimations: (animations: StoredAnimation[] | StoredAnimation) => number[];
+    /** Ensure a player exists with this name; returns PlayerId (number) */
+    addPlayer: (name: string) => number;
+    /** Add one or more instances to players; resolves animation by index or explicit id */
+    addInstances: (specs: {
+        playerName: string;
+        animIndexOrId: number;
+        cfg?: unknown;
+    }[]) => {
+        playerName: string;
+        instId: number;
+    }[];
+    /** Get instance ids for a given player (local cache; prefer listInstances for engine truth) */
+    getInstances: (playerName: string) => number[];
+    /** Apply instance-level updates immediately */
+    updateInstances: (updates: InstanceUpdate[]) => void;
+    /** Enumerate engine state (authoritative) */
+    listAnimations: () => AnimationInfo[];
+    listPlayers: () => PlayerInfo[];
+    listInstances: (player: string | number) => InstanceInfo[];
+    /** Keys currently associated with a player's instances */
+    listPlayerKeys: (player: string | number) => string[];
+    /** Removals */
+    removePlayer: (player: string | number) => boolean;
+    removeInstances: (specs: {
+        playerName: string;
+        instId: number;
+    }[]) => {
+        playerName: string;
+        instId: number;
+    }[];
+    unloadAnimations: (animIds: number[]) => number[];
+    /** Baking helpers */
+    bakeAnimation: (animIndexOrId: number, cfg?: BakingConfig) => BakedAnimationData | null;
+    bakeAnimationWithDerivatives: (animIndexOrId: number, cfg?: BakingConfig) => BakedAnimationBundle | null;
+    /** Optional: expose player name to id mapping for controls */
+    players: Record<string, number>;
+};
+
+declare function AnimationProvider({ children, animations, instances, prebind, autostart, updateHz, engineConfig, onOutputs, }: AnimationProviderProps): react_jsx_runtime.JSX.Element;
+
+declare function useAnimation(): AnimationContextValue;
+
+declare function useAnimTarget(key?: string): Value | undefined;
+
+declare function useAnimDerivative(key?: string): Value | undefined;
+
+declare function valueAsNumber(v: Value | undefined): number | undefined;
+declare function valueAsNumericArray(v: Value | undefined, fallback?: number): number[] | undefined;
+declare function valueAsTransform(v: Value | undefined): NormalizedTransform | undefined;
+
+declare const samples: {
+    readonly list: typeof listAnimationFixtures;
+    readonly load: typeof loadAnimationFixture;
+    readonly loadJson: typeof loadAnimationJson;
+    readonly resolvePath: typeof resolveAnimationPath;
+};
+
+export { AnimationProvider, type Value, samples, useAnimDerivative, useAnimTarget, useAnimation, valueAsNumber, valueAsNumericArray, valueAsTransform };