@vizij/render 0.0.1 → 0.0.3

package/README.md

@@ -101,6 +101,18 @@ The store tracks world graph entries, controllers, debug overlays, and renderabl
 
 All exports are re-exported through `src/index.tsx`, so a simple `import { loadGLTF } from "@vizij/render"` works.
 
+### Dual-format Vizij bundles
+
+Vizij scenes persist authoring metadata inside GLBs so third-party tools see baked animation, while Vizij runtimes retain orchestrator graphs and clips.
+
+- 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.
+- `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.
+
 ---
 
 ## Development & Testing

package/dist/index.d.mts

@@ -4,7 +4,7 @@ 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 } 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, }: {
@@ -282,6 +282,94 @@ interface Selection {
     };
 }
 
+type VizijBundleVersion = 1;
+type VizijBundleGraphKind = "rig" | "pose" | "pose-driver" | "animation-bridge" | "low-level" | string;
+type VizijPoseId = string;
+type VizijAnimationId = string;
+type VizijGraphId = string;
+interface VizijBundleGraphMetadata {
+    hash?: string;
+    source?: string;
+    kind?: VizijBundleGraphKind;
+    exportedAt?: string;
+    [key: string]: unknown;
+}
+interface VizijBundleGraphEntry {
+    id: VizijGraphId;
+    kind: VizijBundleGraphKind;
+    spec: Record<string, unknown>;
+    label?: string;
+    metadata?: VizijBundleGraphMetadata;
+}
+interface VizijPoseDefinition {
+    id: VizijPoseId;
+    name?: string;
+    description?: string;
+    values: Record<string, number | undefined>;
+}
+interface VizijPoseRigConfig {
+    version: number;
+    faceId?: string | null;
+    title?: string;
+    description?: string;
+    neutralInputs: Record<string, number>;
+    poses: VizijPoseDefinition[];
+    metadata?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+interface VizijBundlePoseSection {
+    config: VizijPoseRigConfig;
+    metadata?: {
+        hash?: string;
+        exportedAt?: string;
+        [key: string]: unknown;
+    };
+}
+interface VizijBundleAnimationKeyframe {
+    time: number;
+    value: number;
+    easing?: "linear" | "easeIn" | "easeOut" | "easeInOut" | string;
+    inTangent?: number | null;
+    outTangent?: number | null;
+    [key: string]: unknown;
+}
+interface VizijBundleAnimationTrack {
+    channel: string;
+    keyframes: VizijBundleAnimationKeyframe[];
+    interpolation?: "step" | "linear" | "cubic" | string;
+    [key: string]: unknown;
+}
+interface VizijBundleAnimationClip {
+    id: VizijAnimationId;
+    name?: string;
+    duration?: number;
+    tracks: VizijBundleAnimationTrack[];
+    metadata?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+interface VizijBundleAnimationEntry {
+    id: VizijAnimationId;
+    clip: VizijBundleAnimationClip;
+    metadata?: {
+        hash?: string;
+        sampleRateHz?: number;
+        rigGraphHash?: string;
+        poseGraphHash?: string | null;
+        bakedClipIndex?: number | null;
+        tolerance?: number;
+        exportedAt?: string;
+        [key: string]: unknown;
+    };
+}
+interface VizijBundleExtension {
+    version: VizijBundleVersion;
+    exportedAt?: string;
+    graphs?: VizijBundleGraphEntry[];
+    poses?: VizijBundlePoseSection | null;
+    animations?: VizijBundleAnimationEntry[];
+    metadata?: Record<string, unknown>;
+}
+
 interface VizijData {
     world: World;
     animatables: Record<string, AnimatableValue>;
@@ -442,6 +530,19 @@ declare function loadGLTFFromBlob(blob: Blob, namespaces: string[], aggressiveIm
     center: RawVector2;
     size: RawVector2;
 }): Promise<[World, Record<string, AnimatableValue>]>;
+type LoadedVizijAsset = {
+    world: World;
+    animatables: Record<string, AnimatableValue>;
+    bundle: VizijBundleExtension | null;
+};
+declare function loadGLTFWithBundle(url: string, namespaces: string[], aggressiveImport?: boolean, rootBounds?: {
+    center: RawVector2;
+    size: RawVector2;
+}): Promise<LoadedVizijAsset>;
+declare function loadGLTFFromBlobWithBundle(blob: Blob, namespaces: string[], aggressiveImport?: boolean, rootBounds?: {
+    center: RawVector2;
+    size: RawVector2;
+}): Promise<LoadedVizijAsset>;
 
 /**
  * Loads a GLTF model from a Blob and returns the Three.js scene containing the model.
@@ -451,6 +552,15 @@ declare function loadGLTFFromBlob(blob: Blob, namespaces: string[], aggressiveIm
  */
 declare const loadGltfFromBlob: (blob: Blob, namespaces: string[]) => Promise<[World, Record<string, AnimatableValue>]>;
 
-declare function exportScene(data: Group$1, fileName?: string): void;
+type ExportSceneOptions = {
+    fileName?: string;
+    bundle?: VizijBundleExtension | null;
+    animations?: AnimationClip[];
+    binary?: boolean;
+};
+declare function exportScene(data: Group$1, fileNameOrOptions?: string | ExportSceneOptions): void;
+
+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 Feature, type Group, type GroupFeature, InnerVizij, type InnerVizijProps, 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, VizijContext, type VizijData, type VizijProps, VizijSlice, type VizijStore, type VizijStoreGetter, type VizijStoreSetter, type World, createVizijStore, exportScene, loadGLTF, loadGLTFFromBlob, loadGltfFromBlob, useDefaultVizijStore, useFeatures, useVizijStore, useVizijStoreGetter, useVizijStoreSetter, useVizijStoreSubscription };
+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 };

package/dist/index.d.ts

@@ -4,7 +4,7 @@ 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 } 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, }: {
@@ -282,6 +282,94 @@ interface Selection {
     };
 }
 
+type VizijBundleVersion = 1;
+type VizijBundleGraphKind = "rig" | "pose" | "pose-driver" | "animation-bridge" | "low-level" | string;
+type VizijPoseId = string;
+type VizijAnimationId = string;
+type VizijGraphId = string;
+interface VizijBundleGraphMetadata {
+    hash?: string;
+    source?: string;
+    kind?: VizijBundleGraphKind;
+    exportedAt?: string;
+    [key: string]: unknown;
+}
+interface VizijBundleGraphEntry {
+    id: VizijGraphId;
+    kind: VizijBundleGraphKind;
+    spec: Record<string, unknown>;
+    label?: string;
+    metadata?: VizijBundleGraphMetadata;
+}
+interface VizijPoseDefinition {
+    id: VizijPoseId;
+    name?: string;
+    description?: string;
+    values: Record<string, number | undefined>;
+}
+interface VizijPoseRigConfig {
+    version: number;
+    faceId?: string | null;
+    title?: string;
+    description?: string;
+    neutralInputs: Record<string, number>;
+    poses: VizijPoseDefinition[];
+    metadata?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+interface VizijBundlePoseSection {
+    config: VizijPoseRigConfig;
+    metadata?: {
+        hash?: string;
+        exportedAt?: string;
+        [key: string]: unknown;
+    };
+}
+interface VizijBundleAnimationKeyframe {
+    time: number;
+    value: number;
+    easing?: "linear" | "easeIn" | "easeOut" | "easeInOut" | string;
+    inTangent?: number | null;
+    outTangent?: number | null;
+    [key: string]: unknown;
+}
+interface VizijBundleAnimationTrack {
+    channel: string;
+    keyframes: VizijBundleAnimationKeyframe[];
+    interpolation?: "step" | "linear" | "cubic" | string;
+    [key: string]: unknown;
+}
+interface VizijBundleAnimationClip {
+    id: VizijAnimationId;
+    name?: string;
+    duration?: number;
+    tracks: VizijBundleAnimationTrack[];
+    metadata?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+interface VizijBundleAnimationEntry {
+    id: VizijAnimationId;
+    clip: VizijBundleAnimationClip;
+    metadata?: {
+        hash?: string;
+        sampleRateHz?: number;
+        rigGraphHash?: string;
+        poseGraphHash?: string | null;
+        bakedClipIndex?: number | null;
+        tolerance?: number;
+        exportedAt?: string;
+        [key: string]: unknown;
+    };
+}
+interface VizijBundleExtension {
+    version: VizijBundleVersion;
+    exportedAt?: string;
+    graphs?: VizijBundleGraphEntry[];
+    poses?: VizijBundlePoseSection | null;
+    animations?: VizijBundleAnimationEntry[];
+    metadata?: Record<string, unknown>;
+}
+
 interface VizijData {
     world: World;
     animatables: Record<string, AnimatableValue>;
@@ -442,6 +530,19 @@ declare function loadGLTFFromBlob(blob: Blob, namespaces: string[], aggressiveIm
     center: RawVector2;
     size: RawVector2;
 }): Promise<[World, Record<string, AnimatableValue>]>;
+type LoadedVizijAsset = {
+    world: World;
+    animatables: Record<string, AnimatableValue>;
+    bundle: VizijBundleExtension | null;
+};
+declare function loadGLTFWithBundle(url: string, namespaces: string[], aggressiveImport?: boolean, rootBounds?: {
+    center: RawVector2;
+    size: RawVector2;
+}): Promise<LoadedVizijAsset>;
+declare function loadGLTFFromBlobWithBundle(blob: Blob, namespaces: string[], aggressiveImport?: boolean, rootBounds?: {
+    center: RawVector2;
+    size: RawVector2;
+}): Promise<LoadedVizijAsset>;
 
 /**
  * Loads a GLTF model from a Blob and returns the Three.js scene containing the model.
@@ -451,6 +552,15 @@ declare function loadGLTFFromBlob(blob: Blob, namespaces: string[], aggressiveIm
  */
 declare const loadGltfFromBlob: (blob: Blob, namespaces: string[]) => Promise<[World, Record<string, AnimatableValue>]>;
 
-declare function exportScene(data: Group$1, fileName?: string): void;
+type ExportSceneOptions = {
+    fileName?: string;
+    bundle?: VizijBundleExtension | null;
+    animations?: AnimationClip[];
+    binary?: boolean;
+};
+declare function exportScene(data: Group$1, fileNameOrOptions?: string | ExportSceneOptions): void;
+
+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 Feature, type Group, type GroupFeature, InnerVizij, type InnerVizijProps, 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, VizijContext, type VizijData, type VizijProps, VizijSlice, type VizijStore, type VizijStoreGetter, type VizijStoreSetter, type World, createVizijStore, exportScene, loadGLTF, loadGLTFFromBlob, loadGltfFromBlob, useDefaultVizijStore, useFeatures, useVizijStore, useVizijStoreGetter, useVizijStoreSetter, useVizijStoreSubscription };
+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 };