@vizij/render 0.0.2 → 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 };

package/dist/index.js

@@ -37,10 +37,14 @@ __export(index_exports, {
   Vizij: () => Vizij,
   VizijContext: () => VizijContext,
   VizijSlice: () => VizijSlice,
+  applyVizijBundle: () => applyVizijBundle,
   createVizijStore: () => createVizijStore,
   exportScene: () => exportScene,
+  extractVizijBundle: () => extractVizijBundle,
   loadGLTF: () => loadGLTF,
   loadGLTFFromBlob: () => loadGLTFFromBlob,
+  loadGLTFFromBlobWithBundle: () => loadGLTFFromBlobWithBundle,
+  loadGLTFWithBundle: () => loadGLTFWithBundle,
   loadGltfFromBlob: () => loadGltfFromBlob,
   useDefaultVizijStore: () => useDefaultVizijStore,
   useFeatures: () => useFeatures,
@@ -2521,7 +2525,9 @@ function traverseThree(group, namespaces, aggressiveImport = false, rootBounds)
   });
   const useRobotData = !aggressiveImport || hasRobotData;
   if (useRobotData) {
-    group.traverse((child) => {
+    const stack = [group];
+    while (stack.length > 0) {
+      const child = stack.pop();
       if (child.userData?.gltfExtensions?.RobotData) {
         const data = child.userData.gltfExtensions.RobotData;
         applyStoredRenderableNames(child, data);
@@ -2590,7 +2596,10 @@ function traverseThree(group, namespaces, aggressiveImport = false, rootBounds)
             throw new Error(`Unhandled type`);
         }
       }
-    });
+      if (child.children) {
+        stack.push(...child.children);
+      }
+    }
   } else {
     const derivedRootBounds = rootBounds ?? deriveRootBounds(group);
     if (!derivedRootBounds) {
@@ -2758,6 +2767,106 @@ function deriveRootBounds(group) {
   };
 }
 
+// src/functions/vizij-bundle.ts
+var BUNDLE_KEYS = ["VIZIJ_bundle"];
+function cloneBundle(value) {
+  return JSON.parse(JSON.stringify(value));
+}
+function readExtensionValue(extensionContainer) {
+  for (const key of BUNDLE_KEYS) {
+    if (extensionContainer && Object.prototype.hasOwnProperty.call(extensionContainer, key)) {
+      const value = extensionContainer[key];
+      if (value && typeof value === "object") {
+        return { key, value };
+      }
+    }
+  }
+  return null;
+}
+function searchObjectForBundle(object) {
+  const stack = [object];
+  while (stack.length > 0) {
+    const current = stack.pop();
+    const extensions = current?.userData?.gltfExtensions ?? current?.userData?.extensions ?? null;
+    if (extensions && typeof extensions === "object") {
+      const match = readExtensionValue(extensions);
+      if (match) {
+        return cloneBundle(match.value);
+      }
+    }
+    if (current.children && current.children.length > 0) {
+      stack.push(...current.children);
+    }
+  }
+  return null;
+}
+function searchParserJsonForBundle(parserJson) {
+  if (!parserJson || typeof parserJson !== "object") {
+    return null;
+  }
+  const nodes = Array.isArray(parserJson.nodes) ? parserJson.nodes : [];
+  for (const node of nodes) {
+    const extensions = node && typeof node === "object" ? node.extensions : null;
+    if (extensions && typeof extensions === "object") {
+      const match = readExtensionValue(extensions);
+      if (match) {
+        return cloneBundle(match.value);
+      }
+    }
+  }
+  const scenes = Array.isArray(parserJson.scenes) ? parserJson.scenes : [];
+  for (const scene of scenes) {
+    const extensions = scene && typeof scene === "object" ? scene.extensions : null;
+    if (extensions && typeof extensions === "object") {
+      const match = readExtensionValue(extensions);
+      if (match) {
+        return cloneBundle(match.value);
+      }
+    }
+  }
+  return null;
+}
+function extractVizijBundle(object, parserJson) {
+  const fromObject = searchObjectForBundle(object);
+  if (fromObject) {
+    return fromObject;
+  }
+  const fromParser = searchParserJsonForBundle(parserJson);
+  if (fromParser) {
+    return fromParser;
+  }
+  return null;
+}
+function applyVizijBundle(object, bundle) {
+  const userData = object.userData && typeof object.userData === "object" ? object.userData : {};
+  const originalExtensions = userData.gltfExtensions;
+  let applied = false;
+  if (bundle) {
+    userData.gltfExtensions = {
+      ...originalExtensions ?? {},
+      VIZIJ_bundle: bundle
+    };
+    object.userData = userData;
+    applied = true;
+  }
+  return () => {
+    if (!applied) {
+      return;
+    }
+    if (originalExtensions) {
+      userData.gltfExtensions = originalExtensions;
+    } else {
+      if (userData.gltfExtensions) {
+        delete userData.gltfExtensions;
+      }
+      if (Object.keys(userData).length === 0) {
+        delete object.userData;
+      }
+    }
+    applied = false;
+  };
+}
+
 // src/functions/load-gltf.ts
 THREE5.Object3D.DEFAULT_UP.set(0, 0, 1);
 var EmptyModelError = class extends Error {
@@ -2771,24 +2880,27 @@ async function loadGLTF(url, namespaces, aggressiveImport = false, rootBounds) {
   modelLoader.setDRACOLoader(new import_three_stdlib.DRACOLoader());
   const modelData = await modelLoader.loadAsync(url);
   const actualizedNamespaces = namespaces.length > 0 ? namespaces : ["default"];
-  return traverseThree(
+  const asset = parseScene(
     modelData.scene,
     actualizedNamespaces,
     aggressiveImport,
-    rootBounds
+    rootBounds,
+    modelData?.parser?.json
   );
+  return [asset.world, asset.animatables];
 }
 async function loadGLTFFromBlob(blob, namespaces, aggressiveImport = false, rootBounds) {
   const actualizedNamespaces = namespaces.length > 0 ? namespaces : ["default"];
   if (typeof URL !== "undefined" && typeof URL.createObjectURL === "function") {
     const objectUrl = URL.createObjectURL(blob);
     try {
-      return await loadGLTF(
+      const asset = await loadGLTFWithBundle(
         objectUrl,
         actualizedNamespaces,
         aggressiveImport,
         rootBounds
       );
+      return [asset.world, asset.animatables];
     } finally {
       URL.revokeObjectURL(objectUrl);
     }
@@ -2802,14 +2914,83 @@ async function loadGLTFFromBlob(blob, namespaces, aggressiveImport = false, root
       "",
       (gltf) => {
         try {
-          resolve(
-            traverseThree(
-              gltf.scene,
-              actualizedNamespaces,
-              aggressiveImport,
-              rootBounds
-            )
+          const asset = parseScene(
+            gltf.scene,
+            actualizedNamespaces,
+            aggressiveImport,
+            rootBounds,
+            gltf?.parser?.json
           );
+          resolve([asset.world, asset.animatables]);
+        } catch (error) {
+          if (error instanceof Error) {
+            reject(error);
+          } else {
+            reject(new Error(String(error)));
+          }
+        }
+      },
+      (error) => {
+        reject(new Error(`Error loading GLTF: ${error.message}`));
+      }
+    );
+  });
+}
+function parseScene(scene, namespaces, aggressiveImport, rootBounds, parserJson) {
+  const [world, animatables] = traverseThree(
+    scene,
+    namespaces,
+    aggressiveImport,
+    rootBounds
+  );
+  const bundle = extractVizijBundle(scene, parserJson);
+  return { world, animatables, bundle };
+}
+async function loadGLTFWithBundle(url, namespaces, aggressiveImport = false, rootBounds) {
+  const modelLoader = new import_three_stdlib.GLTFLoader();
+  modelLoader.setDRACOLoader(new import_three_stdlib.DRACOLoader());
+  const modelData = await modelLoader.loadAsync(url);
+  const actualizedNamespaces = namespaces.length > 0 ? namespaces : ["default"];
+  return parseScene(
+    modelData.scene,
+    actualizedNamespaces,
+    aggressiveImport,
+    rootBounds,
+    modelData?.parser?.json
+  );
+}
+async function loadGLTFFromBlobWithBundle(blob, namespaces, aggressiveImport = false, rootBounds) {
+  const actualizedNamespaces = namespaces.length > 0 ? namespaces : ["default"];
+  if (typeof URL !== "undefined" && typeof URL.createObjectURL === "function") {
+    const objectUrl = URL.createObjectURL(blob);
+    try {
+      return await loadGLTFWithBundle(
+        objectUrl,
+        actualizedNamespaces,
+        aggressiveImport,
+        rootBounds
+      );
+    } finally {
+      URL.revokeObjectURL(objectUrl);
+    }
+  }
+  const arrayBuffer = typeof blob.arrayBuffer === "function" ? await blob.arrayBuffer() : await new Response(blob).arrayBuffer();
+  return new Promise((resolve, reject) => {
+    const loader = new import_three_stdlib.GLTFLoader();
+    loader.setDRACOLoader(new import_three_stdlib.DRACOLoader());
+    loader.parse(
+      arrayBuffer,
+      "",
+      (gltf) => {
+        try {
+          const asset = parseScene(
+            gltf.scene,
+            actualizedNamespaces,
+            aggressiveImport,
+            rootBounds,
+            gltf?.parser?.json
+          );
+          resolve(asset);
         } catch (error) {
           if (error instanceof Error) {
             reject(error);
@@ -2858,7 +3039,11 @@ var loadGltfFromBlob = (blob, namespaces) => {
 var import_three_stdlib3 = require("three-stdlib");
 var THREE6 = __toESM(require("three"));
 THREE6.Object3D.DEFAULT_UP.set(0, 0, 1);
-function exportScene(data, fileName = "scene.glb") {
+function exportScene(data, fileNameOrOptions = "scene.glb") {
+  const options = typeof fileNameOrOptions === "string" ? { fileName: fileNameOrOptions } : fileNameOrOptions ?? {};
+  const fileName = options.fileName ?? "scene.glb";
+  const animationClips = Array.isArray(options.animations) ? options.animations.filter(Boolean) : [];
+  const shouldAttachBundle = Boolean(options.bundle);
   const exporter = new import_three_stdlib3.GLTFExporter();
   exporter.register(() => ({
     writeMesh(mesh, meshDef) {
@@ -2868,34 +3053,48 @@ function exportScene(data, fileName = "scene.glb") {
       }
     }
   }));
-  exporter.parse(
-    data,
-    (gltf) => {
-      if (!(gltf instanceof ArrayBuffer)) {
-        throw new Error("Failed to export scene!");
-      }
-      const link = document.createElement("a");
-      link.href = URL.createObjectURL(
-        new Blob([gltf], {
-          type: "application/octet-stream"
-        })
-      );
-      const trimmed = fileName.trim();
-      const safeFileName = trimmed.length > 0 ? trimmed : "scene.glb";
-      const downloadName = safeFileName.toLowerCase().endsWith(".glb") ? safeFileName : `${safeFileName}.glb`;
-      link.download = downloadName;
-      link.click();
-      URL.revokeObjectURL(link.href);
-    },
-    () => {
-    },
-    {
-      trs: true,
-      onlyVisible: false,
-      binary: true,
-      includeCustomExtensions: true
-    }
-  );
+  const detachBundle = shouldAttachBundle && options.bundle ? applyVizijBundle(data, options.bundle) : () => {
+  };
+  const binary = options.binary ?? true;
+  const exporterOptions = {
+    trs: true,
+    onlyVisible: false,
+    binary,
+    includeCustomExtensions: true
+  };
+  if (animationClips.length > 0) {
+    exporterOptions.animations = animationClips;
+  }
+  try {
+    exporter.parse(
+      data,
+      (gltf) => {
+        detachBundle();
+        if (!(gltf instanceof ArrayBuffer)) {
+          throw new Error("Failed to export scene!");
+        }
+        const link = document.createElement("a");
+        link.href = URL.createObjectURL(
+          new Blob([gltf], {
+            type: "application/octet-stream"
+          })
+        );
+        const trimmed = fileName.trim();
+        const safeFileName = trimmed.length > 0 ? trimmed : "scene.glb";
+        const downloadName = safeFileName.toLowerCase().endsWith(".glb") ? safeFileName : `${safeFileName}.glb`;
+        link.download = downloadName;
+        link.click();
+        URL.revokeObjectURL(link.href);
+      },
+      () => {
+        detachBundle();
+      },
+      exporterOptions
+    );
+  } catch (error) {
+    detachBundle();
+    throw error;
+  }
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
@@ -2906,10 +3105,14 @@ function exportScene(data, fileName = "scene.glb") {
   Vizij,
   VizijContext,
   VizijSlice,
+  applyVizijBundle,
   createVizijStore,
   exportScene,
+  extractVizijBundle,
   loadGLTF,
   loadGLTFFromBlob,
+  loadGLTFFromBlobWithBundle,
+  loadGLTFWithBundle,
   loadGltfFromBlob,
   useDefaultVizijStore,
   useFeatures,

package/dist/index.mjs

@@ -2526,7 +2526,9 @@ function traverseThree(group, namespaces, aggressiveImport = false, rootBounds)
   });
   const useRobotData = !aggressiveImport || hasRobotData;
   if (useRobotData) {
-    group.traverse((child) => {
+    const stack = [group];
+    while (stack.length > 0) {
+      const child = stack.pop();
       if (child.userData?.gltfExtensions?.RobotData) {
         const data = child.userData.gltfExtensions.RobotData;
         applyStoredRenderableNames(child, data);
@@ -2595,7 +2597,10 @@ function traverseThree(group, namespaces, aggressiveImport = false, rootBounds)
             throw new Error(`Unhandled type`);
         }
       }
-    });
+      if (child.children) {
+        stack.push(...child.children);
+      }
+    }
   } else {
     const derivedRootBounds = rootBounds ?? deriveRootBounds(group);
     if (!derivedRootBounds) {
@@ -2763,6 +2768,106 @@ function deriveRootBounds(group) {
   };
 }
 
+// src/functions/vizij-bundle.ts
+var BUNDLE_KEYS = ["VIZIJ_bundle"];
+function cloneBundle(value) {
+  return JSON.parse(JSON.stringify(value));
+}
+function readExtensionValue(extensionContainer) {
+  for (const key of BUNDLE_KEYS) {
+    if (extensionContainer && Object.prototype.hasOwnProperty.call(extensionContainer, key)) {
+      const value = extensionContainer[key];
+      if (value && typeof value === "object") {
+        return { key, value };
+      }
+    }
+  }
+  return null;
+}
+function searchObjectForBundle(object) {
+  const stack = [object];
+  while (stack.length > 0) {
+    const current = stack.pop();
+    const extensions = current?.userData?.gltfExtensions ?? current?.userData?.extensions ?? null;
+    if (extensions && typeof extensions === "object") {
+      const match = readExtensionValue(extensions);
+      if (match) {
+        return cloneBundle(match.value);
+      }
+    }
+    if (current.children && current.children.length > 0) {
+      stack.push(...current.children);
+    }
+  }
+  return null;
+}
+function searchParserJsonForBundle(parserJson) {
+  if (!parserJson || typeof parserJson !== "object") {
+    return null;
+  }
+  const nodes = Array.isArray(parserJson.nodes) ? parserJson.nodes : [];
+  for (const node of nodes) {
+    const extensions = node && typeof node === "object" ? node.extensions : null;
+    if (extensions && typeof extensions === "object") {
+      const match = readExtensionValue(extensions);
+      if (match) {
+        return cloneBundle(match.value);
+      }
+    }
+  }
+  const scenes = Array.isArray(parserJson.scenes) ? parserJson.scenes : [];
+  for (const scene of scenes) {
+    const extensions = scene && typeof scene === "object" ? scene.extensions : null;
+    if (extensions && typeof extensions === "object") {
+      const match = readExtensionValue(extensions);
+      if (match) {
+        return cloneBundle(match.value);
+      }
+    }
+  }
+  return null;
+}
+function extractVizijBundle(object, parserJson) {
+  const fromObject = searchObjectForBundle(object);
+  if (fromObject) {
+    return fromObject;
+  }
+  const fromParser = searchParserJsonForBundle(parserJson);
+  if (fromParser) {
+    return fromParser;
+  }
+  return null;
+}
+function applyVizijBundle(object, bundle) {
+  const userData = object.userData && typeof object.userData === "object" ? object.userData : {};
+  const originalExtensions = userData.gltfExtensions;
+  let applied = false;
+  if (bundle) {
+    userData.gltfExtensions = {
+      ...originalExtensions ?? {},
+      VIZIJ_bundle: bundle
+    };
+    object.userData = userData;
+    applied = true;
+  }
+  return () => {
+    if (!applied) {
+      return;
+    }
+    if (originalExtensions) {
+      userData.gltfExtensions = originalExtensions;
+    } else {
+      if (userData.gltfExtensions) {
+        delete userData.gltfExtensions;
+      }
+      if (Object.keys(userData).length === 0) {
+        delete object.userData;
+      }
+    }
+    applied = false;
+  };
+}
+
 // src/functions/load-gltf.ts
 THREE5.Object3D.DEFAULT_UP.set(0, 0, 1);
 var EmptyModelError = class extends Error {
@@ -2776,24 +2881,27 @@ async function loadGLTF(url, namespaces, aggressiveImport = false, rootBounds) {
   modelLoader.setDRACOLoader(new DRACOLoader());
   const modelData = await modelLoader.loadAsync(url);
   const actualizedNamespaces = namespaces.length > 0 ? namespaces : ["default"];
-  return traverseThree(
+  const asset = parseScene(
     modelData.scene,
     actualizedNamespaces,
     aggressiveImport,
-    rootBounds
+    rootBounds,
+    modelData?.parser?.json
   );
+  return [asset.world, asset.animatables];
 }
 async function loadGLTFFromBlob(blob, namespaces, aggressiveImport = false, rootBounds) {
   const actualizedNamespaces = namespaces.length > 0 ? namespaces : ["default"];
   if (typeof URL !== "undefined" && typeof URL.createObjectURL === "function") {
     const objectUrl = URL.createObjectURL(blob);
     try {
-      return await loadGLTF(
+      const asset = await loadGLTFWithBundle(
         objectUrl,
         actualizedNamespaces,
         aggressiveImport,
         rootBounds
       );
+      return [asset.world, asset.animatables];
     } finally {
       URL.revokeObjectURL(objectUrl);
     }
@@ -2807,14 +2915,83 @@ async function loadGLTFFromBlob(blob, namespaces, aggressiveImport = false, root
       "",
       (gltf) => {
         try {
-          resolve(
-            traverseThree(
-              gltf.scene,
-              actualizedNamespaces,
-              aggressiveImport,
-              rootBounds
-            )
+          const asset = parseScene(
+            gltf.scene,
+            actualizedNamespaces,
+            aggressiveImport,
+            rootBounds,
+            gltf?.parser?.json
           );
+          resolve([asset.world, asset.animatables]);
+        } catch (error) {
+          if (error instanceof Error) {
+            reject(error);
+          } else {
+            reject(new Error(String(error)));
+          }
+        }
+      },
+      (error) => {
+        reject(new Error(`Error loading GLTF: ${error.message}`));
+      }
+    );
+  });
+}
+function parseScene(scene, namespaces, aggressiveImport, rootBounds, parserJson) {
+  const [world, animatables] = traverseThree(
+    scene,
+    namespaces,
+    aggressiveImport,
+    rootBounds
+  );
+  const bundle = extractVizijBundle(scene, parserJson);
+  return { world, animatables, bundle };
+}
+async function loadGLTFWithBundle(url, namespaces, aggressiveImport = false, rootBounds) {
+  const modelLoader = new GLTFLoader();
+  modelLoader.setDRACOLoader(new DRACOLoader());
+  const modelData = await modelLoader.loadAsync(url);
+  const actualizedNamespaces = namespaces.length > 0 ? namespaces : ["default"];
+  return parseScene(
+    modelData.scene,
+    actualizedNamespaces,
+    aggressiveImport,
+    rootBounds,
+    modelData?.parser?.json
+  );
+}
+async function loadGLTFFromBlobWithBundle(blob, namespaces, aggressiveImport = false, rootBounds) {
+  const actualizedNamespaces = namespaces.length > 0 ? namespaces : ["default"];
+  if (typeof URL !== "undefined" && typeof URL.createObjectURL === "function") {
+    const objectUrl = URL.createObjectURL(blob);
+    try {
+      return await loadGLTFWithBundle(
+        objectUrl,
+        actualizedNamespaces,
+        aggressiveImport,
+        rootBounds
+      );
+    } finally {
+      URL.revokeObjectURL(objectUrl);
+    }
+  }
+  const arrayBuffer = typeof blob.arrayBuffer === "function" ? await blob.arrayBuffer() : await new Response(blob).arrayBuffer();
+  return new Promise((resolve, reject) => {
+    const loader = new GLTFLoader();
+    loader.setDRACOLoader(new DRACOLoader());
+    loader.parse(
+      arrayBuffer,
+      "",
+      (gltf) => {
+        try {
+          const asset = parseScene(
+            gltf.scene,
+            actualizedNamespaces,
+            aggressiveImport,
+            rootBounds,
+            gltf?.parser?.json
+          );
+          resolve(asset);
         } catch (error) {
           if (error instanceof Error) {
             reject(error);
@@ -2863,7 +3040,11 @@ var loadGltfFromBlob = (blob, namespaces) => {
 import { GLTFExporter } from "three-stdlib";
 import * as THREE6 from "three";
 THREE6.Object3D.DEFAULT_UP.set(0, 0, 1);
-function exportScene(data, fileName = "scene.glb") {
+function exportScene(data, fileNameOrOptions = "scene.glb") {
+  const options = typeof fileNameOrOptions === "string" ? { fileName: fileNameOrOptions } : fileNameOrOptions ?? {};
+  const fileName = options.fileName ?? "scene.glb";
+  const animationClips = Array.isArray(options.animations) ? options.animations.filter(Boolean) : [];
+  const shouldAttachBundle = Boolean(options.bundle);
   const exporter = new GLTFExporter();
   exporter.register(() => ({
     writeMesh(mesh, meshDef) {
@@ -2873,34 +3054,48 @@ function exportScene(data, fileName = "scene.glb") {
       }
     }
   }));
-  exporter.parse(
-    data,
-    (gltf) => {
-      if (!(gltf instanceof ArrayBuffer)) {
-        throw new Error("Failed to export scene!");
-      }
-      const link = document.createElement("a");
-      link.href = URL.createObjectURL(
-        new Blob([gltf], {
-          type: "application/octet-stream"
-        })
-      );
-      const trimmed = fileName.trim();
-      const safeFileName = trimmed.length > 0 ? trimmed : "scene.glb";
-      const downloadName = safeFileName.toLowerCase().endsWith(".glb") ? safeFileName : `${safeFileName}.glb`;
-      link.download = downloadName;
-      link.click();
-      URL.revokeObjectURL(link.href);
-    },
-    () => {
-    },
-    {
-      trs: true,
-      onlyVisible: false,
-      binary: true,
-      includeCustomExtensions: true
-    }
-  );
+  const detachBundle = shouldAttachBundle && options.bundle ? applyVizijBundle(data, options.bundle) : () => {
+  };
+  const binary = options.binary ?? true;
+  const exporterOptions = {
+    trs: true,
+    onlyVisible: false,
+    binary,
+    includeCustomExtensions: true
+  };
+  if (animationClips.length > 0) {
+    exporterOptions.animations = animationClips;
+  }
+  try {
+    exporter.parse(
+      data,
+      (gltf) => {
+        detachBundle();
+        if (!(gltf instanceof ArrayBuffer)) {
+          throw new Error("Failed to export scene!");
+        }
+        const link = document.createElement("a");
+        link.href = URL.createObjectURL(
+          new Blob([gltf], {
+            type: "application/octet-stream"
+          })
+        );
+        const trimmed = fileName.trim();
+        const safeFileName = trimmed.length > 0 ? trimmed : "scene.glb";
+        const downloadName = safeFileName.toLowerCase().endsWith(".glb") ? safeFileName : `${safeFileName}.glb`;
+        link.download = downloadName;
+        link.click();
+        URL.revokeObjectURL(link.href);
+      },
+      () => {
+        detachBundle();
+      },
+      exporterOptions
+    );
+  } catch (error) {
+    detachBundle();
+    throw error;
+  }
 }
 export {
   Controller,
@@ -2910,10 +3105,14 @@ export {
   Vizij,
   VizijContext,
   VizijSlice,
+  applyVizijBundle,
   createVizijStore,
   exportScene,
+  extractVizijBundle,
   loadGLTF,
   loadGLTFFromBlob,
+  loadGLTFFromBlobWithBundle,
+  loadGLTFWithBundle,
   loadGltfFromBlob,
   useDefaultVizijStore,
   useFeatures,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@vizij/render",
   "description": "Higher-level visualization and interaction components for robot and ai faces.",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",
@@ -31,7 +31,7 @@
     "lint:fix": "pnpm --filter \"$npm_package_name\" exec eslint --ext .js,.jsx,.ts,.tsx --fix -- .",
     "prettier:check": "prettier --check .",
     "prettier:write": "prettier --write .",
-    "test": "vitest --run --passWithNoTests",
+    "test": "node --loader ./tests/node-ts-loader.mjs --test tests/*.node-test.mjs",
     "clean": "rm -rf dist .turbo coverage tsconfig.tsbuildinfo",
     "reset": "rm -rf node_modules",
     "reset:hard": "pnpm run reset && rm -f pnpm-lock.yaml package-lock.json yarn.lock",
@@ -72,8 +72,7 @@
     "zustand": "^5.0.2",
     "tsup": "^8.0.1",
     "typescript": "^5.5.0",
-    "prettier": "^3.4.2",
-    "vitest": "^3.2.4"
+    "prettier": "^3.4.2"
   },
   "size-limit": [
     {