@vizij/render 0.0.3 → 0.0.5

package/README.md

@@ -23,7 +23,7 @@ This package exposes the `Vizij` canvas component along with hooks, stores, and
 
 - `Vizij` renders a fully managed `@react-three/fiber` canvas with sensible defaults for orthographic cameras and safe-area overlays.
 - A Zustand-powered store (`useVizijStore`) tracks renderables, controllers, and transient state. Hooks let you read or mutate slices without re-rendering entire scenes.
-- Utilities (`loadGLTF`, `loadGLTFBlob`, export helpers) streamline loading rigged GLTF assets and exporting scene snapshots.
+- Utilities (`loadGLTF`, `loadGLTFBlob`, export helpers) streamline loading rigged GLTF assets and exporting scene snapshots. The tuple helpers now return `[world, animatables, animations]`, where `animations` contains parsed clip metadata for any channels embedded in the GLB.
 - Controllers wrap common behaviours (e.g., pointer interaction, safe-area visualisation) so you can compose features quickly.
 
 ---
@@ -108,7 +108,8 @@ Vizij scenes persist authoring metadata inside GLBs so third-party tools see bak
 - Every renderable still carries a `RobotData` extension in `userData` describing features and animatable bindings.
 - The exporter now writes a root-level `extensions.VIZIJ_bundle` block following the schema in [`src/types/vizij-bundle.ts`](./src/types/vizij-bundle.ts). It contains rig graphs, pose configs, stored Vizij clips, and provenance hashes.
 - Use `exportScene(group, { bundle, animations })` to embed both the Vizij bundle and optional baked `THREE.AnimationClip` instances. The helper attaches the bundle only for the export call and restores the original object.
-- When loading assets, prefer `loadGLTFWithBundle` / `loadGLTFFromBlobWithBundle` to retrieve `{ world, animatables, bundle }`. The legacy tuple helpers remain available if you do not need bundle metadata.
+- When loading assets, prefer `loadGLTFWithBundle` / `loadGLTFFromBlobWithBundle` to retrieve `{ world, animatables, bundle, animations }`. The legacy tuple helpers return `[world, animatables, animations]` if you only need the renderer state.
+- The new `animations` field exposes `VizijAnimationClipData[]`, which maps each glTF animation channel back to Vizij animatable ids (`RobotData.features.*.value.id`). Each track provides component-aware `times`/`values` arrays so runtimes can register clips without re-parsing the GLB.
 - `extractVizijBundle(scene)` and `applyVizijBundle(scene, bundle)` (under `src/functions/vizij-bundle.ts`) let advanced tooling inspect or mutate bundles without triggering a fresh export.
 
 With this structure, authoring tools can round-trip orchestrator assets while shipping native glTF animations for viewers that do not understand Vizij.

package/dist/index.d.mts

@@ -1,20 +1,12 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as react from 'react';
 import { ComponentProps, ReactNode, RefObject } from 'react';
-import * as react_jsx_runtime from 'react/jsx-runtime';
 import { Canvas, ThreeEvent } from '@react-three/fiber';
 import * as zustand from 'zustand';
 import * as THREE from 'three';
 import { Mesh, Group as Group$1, BufferGeometry, ShapeGeometry, AnimationClip, Object3D } from 'three';
 import { RawValue, AnimatableValue, RawVector2 } from '@vizij/utils';
 
-declare function InnerController({ animatableId, namespace, subfield, className, }: {
-    animatableId: string;
-    namespace?: string;
-    subfield?: string;
-    className?: string;
-}): react_jsx_runtime.JSX.Element | undefined;
-declare const Controller: react.MemoExoticComponent<typeof InnerController>;
-
 interface VizijProps {
     style?: React.CSSProperties;
     className?: string;
@@ -370,6 +362,49 @@ interface VizijBundleExtension {
     metadata?: Record<string, unknown>;
 }
 
+interface VizijAnimationTrackData {
+    /** Vizij animatable id extracted from RobotData.features.*.value.id */
+    componentId: string;
+    /** Feature key (e.g. translation, chin, etc.) */
+    feature: string;
+    /** Vizij renderable id that owns the feature. */
+    renderableId: string;
+    /** glTF node index referenced by the channel. */
+    nodeIndex: number;
+    /** Optional glTF node name for debugging. */
+    nodeName?: string;
+    /** Original glTF channel path (translation, rotation, etc.). */
+    path?: string;
+    /** Optional feature component label (e.g. x, y, z) if provided by the glTF channel. */
+    component?: string;
+    /** Index within the output accessor for multi-component values. */
+    componentIndex?: number;
+    /** Numeric type reported by the Vizij animatable (number, vector3, etc.). */
+    valueType?: string;
+    /** Number of numeric entries per keyframe within `values`. */
+    valueSize: number;
+    /** Interpolation declared on the glTF sampler. */
+    interpolation?: string;
+    /** Keyframe times extracted from the GLTF animation sampler. */
+    times: number[];
+    /** Keyframe values (flattened, length === times.length * valueSize). */
+    values: number[];
+}
+interface VizijAnimationClipData {
+    /** Stable identifier derived from glTF animation name or index. */
+    id: string;
+    /** Human readable name (mirrors glTF animation name when available). */
+    name?: string;
+    /** Duration in seconds resolved from the THREE.AnimationClip. */
+    duration: number;
+    /** Raw glTF animation index in the asset. */
+    index: number;
+    /** Optional metadata copied from glTF animation extras. */
+    metadata?: Record<string, unknown>;
+    /** Extracted per-channel track data for Vizij animatables. */
+    tracks: VizijAnimationTrackData[];
+}
+
 interface VizijData {
     world: World;
     animatables: Record<string, AnimatableValue>;
@@ -525,15 +560,16 @@ declare class EmptyModelError extends Error {
 declare function loadGLTF(url: string, namespaces: string[], aggressiveImport?: boolean, rootBounds?: {
     center: RawVector2;
     size: RawVector2;
-}): Promise<[World, Record<string, AnimatableValue>]>;
+}): Promise<[World, Record<string, AnimatableValue>, VizijAnimationClipData[]]>;
 declare function loadGLTFFromBlob(blob: Blob, namespaces: string[], aggressiveImport?: boolean, rootBounds?: {
     center: RawVector2;
     size: RawVector2;
-}): Promise<[World, Record<string, AnimatableValue>]>;
+}): Promise<[World, Record<string, AnimatableValue>, VizijAnimationClipData[]]>;
 type LoadedVizijAsset = {
     world: World;
     animatables: Record<string, AnimatableValue>;
     bundle: VizijBundleExtension | null;
+    animations: VizijAnimationClipData[];
 };
 declare function loadGLTFWithBundle(url: string, namespaces: string[], aggressiveImport?: boolean, rootBounds?: {
     center: RawVector2;
@@ -563,4 +599,4 @@ declare function exportScene(data: Group$1, fileNameOrOptions?: string | ExportS
 declare function extractVizijBundle(object: Object3D, parserJson?: unknown): VizijBundleExtension | null;
 declare function applyVizijBundle(object: Object3D, bundle: VizijBundleExtension | null): () => void;
 
-export { type AnimatedFeature, Controller, type Ellipse, type EllipseFeature, EmptyModelError, type ExportSceneOptions, type Feature, type Group, type GroupFeature, InnerVizij, type InnerVizijProps, type LoadedVizijAsset, type Rectangle, type RectangleFeature, type RenderableBase, type RenderableFeature, type Selection, type Shape, type ShapeFeature, ShapeMaterial, type StaticFeature, type Stored, type StoredAnimatedFeature, type StoredEllipse, type StoredFeatures, type StoredGroup, type StoredRectangle, type StoredRenderable, type StoredShape, Vizij, type VizijActions, type VizijAnimationId, type VizijBundleAnimationClip, type VizijBundleAnimationEntry, type VizijBundleAnimationKeyframe, type VizijBundleAnimationTrack, type VizijBundleExtension, type VizijBundleGraphEntry, type VizijBundleGraphKind, type VizijBundleGraphMetadata, type VizijBundlePoseSection, type VizijBundleVersion, VizijContext, type VizijData, type VizijGraphId, type VizijPoseDefinition, type VizijPoseId, type VizijPoseRigConfig, type VizijProps, VizijSlice, type VizijStore, type VizijStoreGetter, type VizijStoreSetter, type World, applyVizijBundle, createVizijStore, exportScene, extractVizijBundle, loadGLTF, loadGLTFFromBlob, loadGLTFFromBlobWithBundle, loadGLTFWithBundle, loadGltfFromBlob, useDefaultVizijStore, useFeatures, useVizijStore, useVizijStoreGetter, useVizijStoreSetter, useVizijStoreSubscription };
+export { type AnimatedFeature, type Ellipse, type EllipseFeature, EmptyModelError, type ExportSceneOptions, type Feature, type Group, type GroupFeature, InnerVizij, type InnerVizijProps, type LoadedVizijAsset, type Rectangle, type RectangleFeature, type RenderableBase, type RenderableFeature, type Selection, type Shape, type ShapeFeature, ShapeMaterial, type StaticFeature, type Stored, type StoredAnimatedFeature, type StoredEllipse, type StoredFeatures, type StoredGroup, type StoredRectangle, type StoredRenderable, type StoredShape, Vizij, type VizijActions, type VizijAnimationClipData, type VizijAnimationId, type VizijAnimationTrackData, type VizijBundleAnimationClip, type VizijBundleAnimationEntry, type VizijBundleAnimationKeyframe, type VizijBundleAnimationTrack, type VizijBundleExtension, type VizijBundleGraphEntry, type VizijBundleGraphKind, type VizijBundleGraphMetadata, type VizijBundlePoseSection, type VizijBundleVersion, VizijContext, type VizijData, type VizijGraphId, type VizijPoseDefinition, type VizijPoseId, type VizijPoseRigConfig, type VizijProps, VizijSlice, type VizijStore, type VizijStoreGetter, type VizijStoreSetter, type World, applyVizijBundle, createVizijStore, exportScene, extractVizijBundle, loadGLTF, loadGLTFFromBlob, loadGLTFFromBlobWithBundle, loadGLTFWithBundle, loadGltfFromBlob, useDefaultVizijStore, useFeatures, useVizijStore, useVizijStoreGetter, useVizijStoreSetter, useVizijStoreSubscription };

package/dist/index.d.ts

@@ -1,20 +1,12 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as react from 'react';
 import { ComponentProps, ReactNode, RefObject } from 'react';
-import * as react_jsx_runtime from 'react/jsx-runtime';
 import { Canvas, ThreeEvent } from '@react-three/fiber';
 import * as zustand from 'zustand';
 import * as THREE from 'three';
 import { Mesh, Group as Group$1, BufferGeometry, ShapeGeometry, AnimationClip, Object3D } from 'three';
 import { RawValue, AnimatableValue, RawVector2 } from '@vizij/utils';
 
-declare function InnerController({ animatableId, namespace, subfield, className, }: {
-    animatableId: string;
-    namespace?: string;
-    subfield?: string;
-    className?: string;
-}): react_jsx_runtime.JSX.Element | undefined;
-declare const Controller: react.MemoExoticComponent<typeof InnerController>;
-
 interface VizijProps {
     style?: React.CSSProperties;
     className?: string;
@@ -370,6 +362,49 @@ interface VizijBundleExtension {
     metadata?: Record<string, unknown>;
 }
 
+interface VizijAnimationTrackData {
+    /** Vizij animatable id extracted from RobotData.features.*.value.id */
+    componentId: string;
+    /** Feature key (e.g. translation, chin, etc.) */
+    feature: string;
+    /** Vizij renderable id that owns the feature. */
+    renderableId: string;
+    /** glTF node index referenced by the channel. */
+    nodeIndex: number;
+    /** Optional glTF node name for debugging. */
+    nodeName?: string;
+    /** Original glTF channel path (translation, rotation, etc.). */
+    path?: string;
+    /** Optional feature component label (e.g. x, y, z) if provided by the glTF channel. */
+    component?: string;
+    /** Index within the output accessor for multi-component values. */
+    componentIndex?: number;
+    /** Numeric type reported by the Vizij animatable (number, vector3, etc.). */
+    valueType?: string;
+    /** Number of numeric entries per keyframe within `values`. */
+    valueSize: number;
+    /** Interpolation declared on the glTF sampler. */
+    interpolation?: string;
+    /** Keyframe times extracted from the GLTF animation sampler. */
+    times: number[];
+    /** Keyframe values (flattened, length === times.length * valueSize). */
+    values: number[];
+}
+interface VizijAnimationClipData {
+    /** Stable identifier derived from glTF animation name or index. */
+    id: string;
+    /** Human readable name (mirrors glTF animation name when available). */
+    name?: string;
+    /** Duration in seconds resolved from the THREE.AnimationClip. */
+    duration: number;
+    /** Raw glTF animation index in the asset. */
+    index: number;
+    /** Optional metadata copied from glTF animation extras. */
+    metadata?: Record<string, unknown>;
+    /** Extracted per-channel track data for Vizij animatables. */
+    tracks: VizijAnimationTrackData[];
+}
+
 interface VizijData {
     world: World;
     animatables: Record<string, AnimatableValue>;
@@ -525,15 +560,16 @@ declare class EmptyModelError extends Error {
 declare function loadGLTF(url: string, namespaces: string[], aggressiveImport?: boolean, rootBounds?: {
     center: RawVector2;
     size: RawVector2;
-}): Promise<[World, Record<string, AnimatableValue>]>;
+}): Promise<[World, Record<string, AnimatableValue>, VizijAnimationClipData[]]>;
 declare function loadGLTFFromBlob(blob: Blob, namespaces: string[], aggressiveImport?: boolean, rootBounds?: {
     center: RawVector2;
     size: RawVector2;
-}): Promise<[World, Record<string, AnimatableValue>]>;
+}): Promise<[World, Record<string, AnimatableValue>, VizijAnimationClipData[]]>;
 type LoadedVizijAsset = {
     world: World;
     animatables: Record<string, AnimatableValue>;
     bundle: VizijBundleExtension | null;
+    animations: VizijAnimationClipData[];
 };
 declare function loadGLTFWithBundle(url: string, namespaces: string[], aggressiveImport?: boolean, rootBounds?: {
     center: RawVector2;
@@ -563,4 +599,4 @@ declare function exportScene(data: Group$1, fileNameOrOptions?: string | ExportS
 declare function extractVizijBundle(object: Object3D, parserJson?: unknown): VizijBundleExtension | null;
 declare function applyVizijBundle(object: Object3D, bundle: VizijBundleExtension | null): () => void;
 
-export { type AnimatedFeature, Controller, type Ellipse, type EllipseFeature, EmptyModelError, type ExportSceneOptions, type Feature, type Group, type GroupFeature, InnerVizij, type InnerVizijProps, type LoadedVizijAsset, type Rectangle, type RectangleFeature, type RenderableBase, type RenderableFeature, type Selection, type Shape, type ShapeFeature, ShapeMaterial, type StaticFeature, type Stored, type StoredAnimatedFeature, type StoredEllipse, type StoredFeatures, type StoredGroup, type StoredRectangle, type StoredRenderable, type StoredShape, Vizij, type VizijActions, type VizijAnimationId, type VizijBundleAnimationClip, type VizijBundleAnimationEntry, type VizijBundleAnimationKeyframe, type VizijBundleAnimationTrack, type VizijBundleExtension, type VizijBundleGraphEntry, type VizijBundleGraphKind, type VizijBundleGraphMetadata, type VizijBundlePoseSection, type VizijBundleVersion, VizijContext, type VizijData, type VizijGraphId, type VizijPoseDefinition, type VizijPoseId, type VizijPoseRigConfig, type VizijProps, VizijSlice, type VizijStore, type VizijStoreGetter, type VizijStoreSetter, type World, applyVizijBundle, createVizijStore, exportScene, extractVizijBundle, loadGLTF, loadGLTFFromBlob, loadGLTFFromBlobWithBundle, loadGLTFWithBundle, loadGltfFromBlob, useDefaultVizijStore, useFeatures, useVizijStore, useVizijStoreGetter, useVizijStoreSetter, useVizijStoreSubscription };
+export { type AnimatedFeature, type Ellipse, type EllipseFeature, EmptyModelError, type ExportSceneOptions, type Feature, type Group, type GroupFeature, InnerVizij, type InnerVizijProps, type LoadedVizijAsset, type Rectangle, type RectangleFeature, type RenderableBase, type RenderableFeature, type Selection, type Shape, type ShapeFeature, ShapeMaterial, type StaticFeature, type Stored, type StoredAnimatedFeature, type StoredEllipse, type StoredFeatures, type StoredGroup, type StoredRectangle, type StoredRenderable, type StoredShape, Vizij, type VizijActions, type VizijAnimationClipData, type VizijAnimationId, type VizijAnimationTrackData, type VizijBundleAnimationClip, type VizijBundleAnimationEntry, type VizijBundleAnimationKeyframe, type VizijBundleAnimationTrack, type VizijBundleExtension, type VizijBundleGraphEntry, type VizijBundleGraphKind, type VizijBundleGraphMetadata, type VizijBundlePoseSection, type VizijBundleVersion, VizijContext, type VizijData, type VizijGraphId, type VizijPoseDefinition, type VizijPoseId, type VizijPoseRigConfig, type VizijProps, VizijSlice, type VizijStore, type VizijStoreGetter, type VizijStoreSetter, type World, applyVizijBundle, createVizijStore, exportScene, extractVizijBundle, loadGLTF, loadGLTFFromBlob, loadGLTFFromBlobWithBundle, loadGLTFWithBundle, loadGltfFromBlob, useDefaultVizijStore, useFeatures, useVizijStore, useVizijStoreGetter, useVizijStoreSetter, useVizijStoreSubscription };