@vizij/render 0.1.2 → 1.0.1

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. The tuple helpers now return `[world, animatables, animations]`, where `animations` contains parsed clip metadata for any channels embedded in the GLB.
+- The loader (`loadGLTF`, `loadGLTFFromBlob` and their `WithBundle` forms) turns a rigged GLB into the world model; `buildSceneGraph` and `exportScene` turn the world model back into GLB bytes. Both run in Node as well as in a browser. The tuple helpers 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.
 
 ---
@@ -96,8 +96,8 @@ The store tracks world graph entries, controllers, debug overlays, and renderabl
 ## Controllers & Helpers
 
 - Controllers under `src/controllers` encapsulate input handling, camera logic, and other behaviours. Compose them with your own React components.
-- `loadGLTF` / `loadGLTFBlob` simplify loading rig assets and extract animatable metadata used by `@vizij/runtime-react`.
-- `export` helpers produce snapshots of the current scene (useful for tooling or exporting frames).
+- `loadGLTF` / `loadGLTFFromBlob` load rig assets and extract the animatable metadata used by `@vizij/runtime-react`. A blob is parsed in memory, with nothing fetched.
+- `buildSceneGraph(world, animatables, rootId)` builds the three.js graph of a world element with no renderer, and `exportScene(root, { bundle, animations })` encodes a graph as GLB bytes. Saving or uploading the bytes is the caller's job.
 
 All exports are re-exported through `src/index.tsx`, so a simple `import { loadGLTF } from "@vizij/render"` works.
 
@@ -107,7 +107,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.
+- Use `exportScene(root, { bundle, animations })` to embed both the Vizij bundle and optional baked `THREE.AnimationClip` instances; it resolves to the GLB as an `ArrayBuffer`. The helper attaches the bundle only for the export call and restores the original object.
+- A graph from `buildSceneGraph` carries each element's authored values: node translation, rotation and scale, morph weights and material factors equal the `RobotData` defaults written beside them, not a runtime pose.
 - 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.

package/dist/index.d.mts

@@ -2,49 +2,11 @@ import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as react from 'react';
 import { CSSProperties, ComponentProps, ReactNode, RefObject, MouseEvent } from 'react';
 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 { BufferGeometry, ShapeGeometry, ToneMapping, Group as Group$1, Mesh, AnimationClip, Object3D } from 'three';
+import * as zustand from 'zustand';
 import { RawValue, AnimatableValue, RawVector2 } from '@vizij/utils';
 
-interface VizijProps {
-    style?: CSSProperties;
-    className?: string;
-    rootId: string;
-    namespace?: string;
-    showSafeArea?: boolean;
-    showSelectionGlow?: boolean;
-    onPointerMissed?: ComponentProps<typeof Canvas>["onPointerMissed"];
-}
-/**
- * Renders the Vizij component.
- *
- * @param style - The style object for the Vizij component.
- *
- * @param className - The CSS class name for the Vizij component
- *
- * @param rootId - The root identifier for the Vizij component.
- *
- * @param namespace - The namespace for the Vizij component
- *
- * @param showSafeArea - Whether to show the safe area.
- *
- * @returns The rendered ReactNode.
- */
-declare function Vizij({ style, className, rootId, namespace, showSafeArea, showSelectionGlow, onPointerMissed, }: VizijProps): ReactNode;
-interface InnerVizijProps {
-    rootId: string;
-    namespace: string;
-    container?: {
-        width: number;
-        height: number;
-        resolution: number;
-    };
-    showSafeArea?: boolean;
-    showSelectionGlow?: boolean;
-}
-declare function InnerVizij({ rootId, namespace, container, showSafeArea, showSelectionGlow, }: InnerVizijProps): react_jsx_runtime.JSX.Element;
-
 /**
  * A wrapping type to reference an attribute that is animatable.
  *
@@ -92,7 +54,6 @@ interface RenderableBase {
     name: string;
     tags: string[];
     type: string;
-    refs: Record<string, RefObject<any>>;
     features: Record<string, Feature>;
 }
 
@@ -109,19 +70,17 @@ interface Stored<T extends Omit<RenderableBase, "refs">> {
 type StoredRenderable = Stored<RenderableBase>;
 
 /**
- * An object for creating hierarchies/bodies
+ * An object for creating rectangles
  *
- * @param id - The id of the ellipse
- * @param name - The name of the ellipse
- * @param tags - The tags of the ellipse
+ * @param id - The id of the rectangle
+ * @param name - The name of the rectangle
+ * @param tags - The tags of the rectangle
  * @param type - Type flag
- * @param refs - The reference to the group[s] in the scene, for each namespace
- * @param features - The features of the ellipse (translation, rotation, and scale)
- * @param children - The children of the ellipse (list of ids for other bodies or shapes)
+ * @param features - The features of the rectangle (translation, rotation, and scale)
+ * @param children - The children of the rectangle (list of ids for other bodies or shapes)
  */
-interface Ellipse extends RenderableBase {
-    type: "ellipse";
-    refs: Record<string, RefObject<Mesh>>;
+interface Rectangle extends RenderableBase {
+    type: "rectangle";
     features: {
         height: Feature;
         width: Feature;
@@ -130,28 +89,27 @@ interface Ellipse extends RenderableBase {
         fillColor?: Feature;
         strokeColor?: Feature;
         strokeWidth?: Feature;
+        strokeRadius?: Feature;
         strokeOffset?: Feature;
         translation: Feature;
         rotation: Feature;
     };
 }
-type EllipseFeature = keyof Ellipse["features"];
-type StoredEllipse = Stored<Ellipse>;
+type RectangleFeature = keyof Rectangle["features"];
+type StoredRectangle = Stored<Rectangle>;
 
 /**
- * An object for creating rectangles
+ * An object for creating hierarchies/bodies
  *
- * @param id - The id of the rectangle
- * @param name - The name of the rectangle
- * @param tags - The tags of the rectangle
+ * @param id - The id of the ellipse
+ * @param name - The name of the ellipse
+ * @param tags - The tags of the ellipse
  * @param type - Type flag
- * @param refs - The reference to the group[s] in the scene, for each namespace
- * @param features - The features of the rectangle (translation, rotation, and scale)
- * @param children - The children of the rectangle (list of ids for other bodies or shapes)
+ * @param features - The features of the ellipse (translation, rotation, and scale)
+ * @param children - The children of the ellipse (list of ids for other bodies or shapes)
  */
-interface Rectangle extends RenderableBase {
-    type: "rectangle";
-    refs: Record<string, RefObject<Mesh>>;
+interface Ellipse extends RenderableBase {
+    type: "ellipse";
     features: {
         height: Feature;
         width: Feature;
@@ -160,14 +118,13 @@ interface Rectangle extends RenderableBase {
         fillColor?: Feature;
         strokeColor?: Feature;
         strokeWidth?: Feature;
-        strokeRadius?: Feature;
         strokeOffset?: Feature;
         translation: Feature;
         rotation: Feature;
     };
 }
-type RectangleFeature = keyof Rectangle["features"];
-type StoredRectangle = Stored<Rectangle>;
+type EllipseFeature = keyof Ellipse["features"];
+type StoredEllipse = Stored<Ellipse>;
 
 /**
  * An object for creating hierarchies/groups
@@ -176,14 +133,12 @@ type StoredRectangle = Stored<Rectangle>;
  * @param name - The name of the group
  * @param tags - The tags of the group
  * @param type - Type flag
- * @param refs - The reference to the group[s] in the vizij, for each namespace
  * @param features - The features of the group (translation, rotation, and scale)
  * @param root - Whether the group is a root node
  * @param children - The children of the group (list of ids for other groups or shapes)
  */
 interface Group extends RenderableBase {
     type: "group";
-    refs: Record<string, RefObject<Group$1>>;
     root: boolean;
     features: {
         translation: Feature;
@@ -209,7 +164,6 @@ type StoredGroup = Stored<Group>;
  * @property name - Human-readable name for the shape
  * @property tags - List of tags for categorizing and filtering
  * @property type - Always "shape"
- * @property refs - Map of React refs to Three.js Mesh objects
  * @property features - Visual and transformation properties that can be animated
  * @property material - The type of Three.js material to use for rendering
  * @property geometry - The Three.js geometry defining the shape's structure
@@ -220,7 +174,6 @@ type StoredGroup = Stored<Group>;
  */
 interface Shape extends RenderableBase {
     type: "shape";
-    refs: Record<string, RefObject<Mesh>>;
     features: {
         shininess?: Feature;
         opacity?: Feature;
@@ -255,8 +208,6 @@ declare enum ShapeMaterial {
 type ShapeFeature = keyof Shape["features"];
 type StoredShape = Stored<Omit<Shape, "geometry">>;
 
-type World = Record<string, Group | Ellipse | Rectangle | Shape>;
-
 type RenderableFeature = GroupFeature | EllipseFeature;
 
 /**
@@ -279,6 +230,57 @@ interface Selection {
     };
 }
 
+type World = Record<string, Group | Ellipse | Rectangle | Shape>;
+
+/**
+ * Vizij-level tone-mapping selection.
+ *
+ * This is a stable, serializable string enum rather than a raw three.js
+ * constant so it can be persisted in the `VIZIJ_bundle` extension and round-trip
+ * through import/export without leaking three's numeric enum values into stored
+ * data.
+ *
+ * - `"none"` — no tone mapping. Values are written to the framebuffer as-is and
+ *   clip at 1.0. This matches plain web/canvas rendering and is the historical
+ *   vizij default (chosen so studio colors match the canvas).
+ * - `"agx"` — AgX, Blender 4.x's default view transform. Compresses
+ *   over-1.0 emissive into soft, slightly-desaturated color; matches faces
+ *   authored/exported from Blender.
+ * - `"aces"` — ACES Filmic, a punchier cinematic curve.
+ * - `"neutral"` — Khronos PBR Neutral, a mild curve that preserves hue/saturation
+ *   while taming highlights.
+ */
+type ToneMappingMode = "none" | "agx" | "aces" | "neutral";
+/**
+ * The set of supported tone-mapping modes, in display order. Useful for
+ * building selection UIs.
+ */
+declare const TONE_MAPPING_MODES: ToneMappingMode[];
+/**
+ * Human-readable labels for each tone-mapping mode.
+ */
+declare const TONE_MAPPING_LABELS: Record<ToneMappingMode, string>;
+/**
+ * The default tone-mapping mode used when a face/scene has not specified one.
+ * `"none"` preserves the historical web-matching behavior.
+ */
+declare const DEFAULT_TONE_MAPPING_MODE: ToneMappingMode;
+/**
+ * Type guard: is `value` a valid {@link ToneMappingMode}?
+ */
+declare function isToneMappingMode(value: unknown): value is ToneMappingMode;
+/**
+ * Resolve a {@link ToneMappingMode} (or an unknown/undefined stored value) to
+ * the corresponding three.js tone-mapping constant. Falls back to
+ * {@link DEFAULT_TONE_MAPPING_MODE} for missing/invalid input.
+ */
+declare function resolveToneMapping(mode: unknown): ToneMapping;
+/**
+ * Normalize an unknown/stored value into a valid {@link ToneMappingMode},
+ * falling back to {@link DEFAULT_TONE_MAPPING_MODE}.
+ */
+declare function normalizeToneMappingMode(value: unknown): ToneMappingMode;
+
 type VizijBundleVersion = 1;
 type VizijBundleGraphKind = "rig" | "pose" | "pose-driver" | "animation-bridge" | "low-level" | string;
 type VizijPoseId = string;
@@ -291,6 +293,40 @@ interface VizijBundleGraphMetadata {
     exportedAt?: string;
     [key: string]: unknown;
 }
+/**
+ * One path in a profile, with its type and constraints — arora's `KeyInfo`
+ * shape, so a profile round-trips through the descriptor the runtime already
+ * speaks.
+ */
+interface VizijProfileKey {
+    path: string;
+    kind?: string;
+    value_type?: string;
+    min?: number;
+    max?: number;
+    default_value?: unknown;
+    /** Standard metadata: the FACS action unit, ARKit blendshape, and tier. */
+    meta?: {
+        au?: number;
+        arkit?: string;
+        tier?: string;
+    };
+}
+/**
+ * A profile the face declares it speaks: a set of paths and their types — the
+ * vocabulary its graphs are authored against.
+ *
+ * A profile is names and types, not a graph, so it sits beside `graphs` rather
+ * than inside it. Declaring it on the asset is what lets a reader know which
+ * vocabulary to hold the face to.
+ */
+interface VizijBundleProfile {
+    id: string;
+    version: string;
+    title?: string;
+    description?: string;
+    keys: VizijProfileKey[];
+}
 interface VizijBundleGraphEntry {
     id: VizijGraphId;
     kind: VizijBundleGraphKind;
@@ -360,6 +396,19 @@ interface VizijBundleAnimationEntry {
         [key: string]: unknown;
     };
 }
+type VizijStarredKind = "driver" | "pose";
+/**
+ * A starred reference collected into the "Starred" control surface. Points at a
+ * real driver (standard-input id) or pose (pose id) by stable id so both the
+ * source panel and the Starred panel render the same underlying object.
+ */
+interface VizijStarredItem {
+    kind: VizijStarredKind;
+    id: string;
+}
+interface VizijBundleStarredSection {
+    items: VizijStarredItem[];
+}
 interface VizijSpeechConfig {
     /** TTS voice name (e.g., "Ruth") */
     voice?: string;
@@ -388,8 +437,22 @@ interface VizijBundleExtension {
     version: VizijBundleVersion;
     exportedAt?: string;
     graphs?: VizijBundleGraphEntry[];
+    /** The profiles this face declares it speaks (see {@link VizijBundleProfile}). */
+    profiles?: VizijBundleProfile[];
     poses?: VizijBundlePoseSection | null;
     animations?: VizijBundleAnimationEntry[];
+    /**
+     * Scene-level view transform this face should be rendered with. Travels with
+     * the asset so a face authored in Blender (which typically wants `"agx"`)
+     * renders consistently wherever it is loaded. Omitted/unknown falls back to
+     * the renderer default (`"none"` — web match).
+     */
+    toneMapping?: ToneMappingMode;
+    /**
+     * Designer-curated set of starred drivers/poses (the "Starred" control
+     * surface). References real functionality by stable id.
+     */
+    starred?: VizijBundleStarredSection | null;
     /**
      * Bundle-level metadata. May include `speechConfig: VizijSpeechConfig`
      * for configuring the STT/LLM/TTS speech pipeline.
@@ -440,8 +503,59 @@ interface VizijAnimationClipData {
     tracks: VizijAnimationTrackData[];
 }
 
+interface VizijProps {
+    style?: CSSProperties;
+    className?: string;
+    rootId: string;
+    namespace?: string;
+    showSafeArea?: boolean;
+    showSelectionGlow?: boolean;
+    /**
+     * View-transform applied by the WebGL renderer. Defaults to `"none"`
+     * (no tone mapping — matches plain web/canvas rendering). Faces authored in
+     * Blender typically want `"agx"` to compress over-driven emissive. Applied
+     * reactively, so it can be changed at runtime without remounting the canvas.
+     */
+    toneMapping?: ToneMappingMode;
+    onPointerMissed?: ComponentProps<typeof Canvas>["onPointerMissed"];
+}
+/**
+ * Renders the Vizij component.
+ *
+ * @param style - The style object for the Vizij component.
+ *
+ * @param className - The CSS class name for the Vizij component
+ *
+ * @param rootId - The root identifier for the Vizij component.
+ *
+ * @param namespace - The namespace for the Vizij component
+ *
+ * @param showSafeArea - Whether to show the safe area.
+ *
+ * @returns The rendered ReactNode.
+ */
+declare function Vizij({ style, className, rootId, namespace, showSafeArea, showSelectionGlow, toneMapping, onPointerMissed, }: VizijProps): ReactNode;
+interface InnerVizijProps {
+    rootId: string;
+    namespace: string;
+    container?: {
+        width: number;
+        height: number;
+        resolution: number;
+    };
+    showSafeArea?: boolean;
+    showSelectionGlow?: boolean;
+    toneMapping?: ToneMappingMode;
+}
+declare function InnerVizij({ rootId, namespace, container, showSafeArea, showSelectionGlow, toneMapping, }: InnerVizijProps): react_jsx_runtime.JSX.Element;
+
 interface VizijData {
     world: World;
+    /**
+     * The mounted three.js object of each world element, by element id and then
+     * namespace. It lives beside `world` so that the world stays plain data.
+     */
+    refs: Record<string, Record<string, RefObject<Group$1 | Mesh | null>>>;
     animatables: Record<string, AnimatableValue>;
     values: Map<string, RawValue | undefined>;
     renderHit: boolean;
@@ -484,7 +598,7 @@ interface VizijActions {
     setChildren: (id: string, children: string[]) => void;
     setGeometry: (id: string, geometry: THREE.BufferGeometry) => void;
     setMaterial: (id: string, material: string) => void;
-    setReference: (id: string, namespace: string, object: RefObject<Group$1 | Mesh>) => void;
+    setReference: (id: string, namespace: string, object: RefObject<Group$1 | Mesh | null>) => void;
     createGroup: (root: boolean) => void;
     createAnimatable: (elementId: string, featureName: string, value: Partial<AnimatableValue>) => void;
     createStatic: (elementId: string, featureName: string, value: RawValue) => void;
@@ -494,6 +608,7 @@ type VizijStoreGetter = () => VizijData & VizijActions;
 
 declare const VizijSlice: (set: VizijStoreSetter, get: VizijStoreGetter) => {
     world: {};
+    refs: {};
     animatables: {};
     values: Map<any, any>;
     renderHit: boolean;
@@ -537,7 +652,7 @@ declare const VizijSlice: (set: VizijStoreSetter, get: VizijStoreGetter) => {
     setVizij: (scene: World, animatables: Record<string, AnimatableValue>) => void;
     addWorldElements(world: World, animatables: Record<string, AnimatableValue>, replace?: boolean): void;
     setPreferences: (preferences: Partial<VizijData["preferences"]>) => void;
-    setReference: (id: string, namespace: string, ref: RefObject<Group$1 | Mesh>) => void;
+    setReference: (id: string, namespace: string, ref: RefObject<Group$1 | Mesh | null>) => void;
 };
 declare const useDefaultVizijStore: zustand.UseBoundStore<Omit<zustand.StoreApi<VizijData & VizijActions>, "subscribe"> & {
     subscribe: {
@@ -604,15 +719,14 @@ declare class EmptyModelError extends Error {
 }
 type ParserJsonFallbackSource = {
     url?: string;
-    blob?: Blob;
     arrayBuffer?: ArrayBuffer;
 };
 declare function parseGlbJsonChunk(buffer: ArrayBuffer): unknown | undefined;
-declare function loadGLTF(url: string, namespaces: string[], aggressiveImport?: boolean, rootBounds?: {
+declare function loadGLTF(url: string, aggressiveImport?: boolean, rootBounds?: {
     center: RawVector2;
     size: RawVector2;
 }): Promise<[World, Record<string, AnimatableValue>, VizijAnimationClipData[]]>;
-declare function loadGLTFFromBlob(blob: Blob, namespaces: string[], aggressiveImport?: boolean, rootBounds?: {
+declare function loadGLTFFromBlob(blob: Blob, aggressiveImport?: boolean, rootBounds?: {
     center: RawVector2;
     size: RawVector2;
 }): Promise<[World, Record<string, AnimatableValue>, VizijAnimationClipData[]]>;
@@ -623,34 +737,121 @@ type LoadedVizijAsset = {
     animations: VizijAnimationClipData[];
     scene: Group$1;
 };
-declare function loadGLTFWithBundle(url: string, namespaces: string[], aggressiveImport?: boolean, rootBounds?: {
+declare function loadGLTFWithBundle(url: string, aggressiveImport?: boolean, rootBounds?: {
     center: RawVector2;
     size: RawVector2;
 }, parserJsonFallback?: ParserJsonFallbackSource): Promise<LoadedVizijAsset>;
-declare function loadGLTFFromBlobWithBundle(blob: Blob, namespaces: string[], aggressiveImport?: boolean, rootBounds?: {
+/**
+ * Load a GLB or self-contained glTF from `blob`.
+ *
+ * The bytes are read into memory and parsed there; nothing is fetched, so this
+ * runs the same in a browser and in Node.
+ */
+declare function loadGLTFFromBlobWithBundle(blob: Blob, 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.
- *
- * @param blob - The Blob containing the GLTF data.
- * @returns A Promise that resolves with the THREE.Scene containing the loaded model.
- */
-declare const loadGltfFromBlob: (blob: Blob, namespaces: string[]) => Promise<[World, Record<string, AnimatableValue>]>;
+declare function deriveRootBounds(group: Group$1): {
+    center: RawVector2;
+    size: RawVector2;
+} | null;
 
 type ExportSceneOptions = {
-    fileName?: string;
+    /** Written into the GLB as the `VIZIJ_bundle` extension of the root node. */
     bundle?: VizijBundleExtension | null;
+    /** Baked clips, written as glTF animations. */
     animations?: AnimationClip[];
-    binary?: boolean;
-    onError?: (error: Error) => void;
-    onComplete?: () => void;
 };
-declare function exportScene(data: Group$1, fileNameOrOptions?: string | ExportSceneOptions): void;
+/**
+ * Rewrite a GLB's JSON chunk in place.
+ *
+ * `mutate` returns whether it changed anything; when it did not, the original
+ * buffer is handed back untouched rather than re-encoded. Any malformed input
+ * — wrong magic, missing JSON chunk, unparseable payload — returns the buffer
+ * as-is, since a patch is never worth corrupting an export over.
+ *
+ * Exists so a caller can amend an already-exported GLB instead of exporting
+ * twice: `GLTFExporter` is the expensive part, and running it again to change
+ * a few bytes of metadata froze the UI thread on real assets.
+ */
+declare function patchGlbJson(buffer: ArrayBuffer, mutate: (json: Record<string, unknown>) => boolean): ArrayBuffer;
+/**
+ * Merge `metadata` into the `VIZIJ_bundle` extension already written into
+ * `glb`, wherever it landed — the exporter attaches it to a node, but a
+ * root-level extension is read back too, so both are handled.
+ */
+declare function patchVizijBundleMetadata(glb: ArrayBuffer, metadata: Record<string, unknown>): ArrayBuffer;
+/**
+ * Encode `root` and its descendants as a GLB.
+ *
+ * Every node is written with its local translation, rotation and scale, every
+ * mesh with its morph weights, and each object's `userData` as glTF
+ * extensions and extras, which is where `RobotData` travels. A root that is
+ * not a `Scene` is cloned into one, so the caller's graph is left as it was.
+ *
+ * Only textures need a DOM; a scene without images encodes in Node.
+ */
+declare function exportScene(root: THREE.Object3D, options?: ExportSceneOptions): Promise<ArrayBuffer>;
+
+/**
+ * Build the three.js graph of the world element `rootId` and its descendants,
+ * for `exportScene`.
+ *
+ * Each group becomes a `THREE.Group` and each shape a `THREE.Mesh` carrying a
+ * copy of its geometry and a material of its kind, as the renderer mounts
+ * them, with the element's `RobotData` in `userData`. No renderer is involved,
+ * so this runs in Node.
+ *
+ * Every feature takes its authored value: a static feature its value, an
+ * animated one its animatable's `default` in `animatables`. Node translation,
+ * rotation and scale, morph weights and material factors in the exported file
+ * are therefore the same numbers as the `RobotData` defaults, never a runtime
+ * pose. A caller that wants other values in the file passes them as the
+ * defaults of `animatables`.
+ *
+ * Throws when an element is missing from `world`, when an animated feature
+ * names an animatable missing from `animatables`, and for ellipse and
+ * rectangle elements, which have no exported form.
+ */
+declare function buildSceneGraph(world: World, animatables: Record<string, AnimatableValue>, rootId: string): THREE.Object3D;
 
 declare function extractVizijBundle(object: Object3D, parserJson?: unknown): VizijBundleExtension | null;
 declare function applyVizijBundle(object: Object3D, bundle: VizijBundleExtension | null): () => void;
 
-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 VizijSpeechConfig, type VizijStore, type VizijStoreGetter, type VizijStoreSetter, type World, applyVizijBundle, createVizijStore, exportScene, extractVizijBundle, loadGLTF, loadGLTFFromBlob, loadGLTFFromBlobWithBundle, loadGLTFWithBundle, loadGltfFromBlob, parseGlbJsonChunk, useDefaultVizijStore, useFeatures, useVizijStore, useVizijStoreGetter, useVizijStoreSetter, useVizijStoreSubscription };
+/**
+ * Canonical morph-target key derivation.
+ *
+ * Morph feature keys are part of the animation binding contract: a propsrig
+ * input path is built from `(elementName, featureKey, component)`, and for a
+ * morph the feature key is derived from the morph's name. Import (building
+ * animatables from geometry) and animation channel resolution must therefore
+ * agree exactly, so both use the helpers here rather than re-deriving the rule.
+ *
+ * Note the slug is normalized twice on the path route: keys produced here are
+ * later passed through `normalizeStandardRigGroup` when the propsrig path is
+ * built, which independently lowercases and collapses separators. Casing here
+ * is therefore not load-bearing for path resolution — but it *is* the stored
+ * feature key on the renderable (and in exported `RobotData`), so changing it
+ * still changes the shape of authored data. Unit tests pin the rule directly;
+ * the corpus test cannot see a casing change because of the double pass.
+ */
+/**
+ * Allocates the feature key for a single morph target, deduplicating against
+ * keys already handed out for the same mesh.
+ *
+ * `used` is mutated: callers iterating a mesh's morph targets must share one
+ * set so collisions resolve deterministically in iteration order.
+ */
+declare function sanitizeMorphKey(name: string, fallbackIndex: number, used: Set<string>): string;
+/**
+ * Derives feature keys for a mesh's morph targets in order, applying the same
+ * dedupe sequence `sanitizeMorphKey` applies during import.
+ *
+ * Pass morph names in the mesh's own target order (glTF
+ * `meshes[].extras.targetNames`, or `morphTargetDictionary` insertion order)
+ * so the result matches the keys import produced for that mesh.
+ */
+declare function deriveMorphFeatureKeys(names: ReadonlyArray<string>): string[];
+
+export { type AnimatedFeature, DEFAULT_TONE_MAPPING_MODE, 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, TONE_MAPPING_LABELS, TONE_MAPPING_MODES, type ToneMappingMode, 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 VizijBundleProfile, type VizijBundleStarredSection, type VizijBundleVersion, VizijContext, type VizijData, type VizijGraphId, type VizijPoseDefinition, type VizijPoseId, type VizijPoseRigConfig, type VizijProfileKey, type VizijProps, VizijSlice, type VizijSpeechConfig, type VizijStarredItem, type VizijStarredKind, type VizijStore, type VizijStoreGetter, type VizijStoreSetter, type World, applyVizijBundle, buildSceneGraph, createVizijStore, deriveMorphFeatureKeys, deriveRootBounds, exportScene, extractVizijBundle, isToneMappingMode, loadGLTF, loadGLTFFromBlob, loadGLTFFromBlobWithBundle, loadGLTFWithBundle, normalizeToneMappingMode, parseGlbJsonChunk, patchGlbJson, patchVizijBundleMetadata, resolveToneMapping, sanitizeMorphKey, useDefaultVizijStore, useFeatures, useVizijStore, useVizijStoreGetter, useVizijStoreSetter, useVizijStoreSubscription };