@vizij/render 1.0.1 → 3.0.0

package/dist/index.d.ts

@@ -1,12 +1,140 @@
-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 THREE from 'three';
-import { BufferGeometry, ShapeGeometry, ToneMapping, Group as Group$1, Mesh, AnimationClip, Object3D } from 'three';
+import { CSSProperties, ReactNode } from 'react';
+import { MountOptions, InitProgress, ToneMapping, Fit, Bounds, Pick } from '@vizij/runtime';
 import * as zustand from 'zustand';
+import * as THREE from 'three';
+import { BufferGeometry, ShapeGeometry, Group as Group$1, Object3D, AnimationClip } from 'three';
 import { RawValue, AnimatableValue, RawVector2 } from '@vizij/utils';
 
+/**
+ * Resolves with the page's canvas once `<VizijCanvas>` has mounted it, which
+ * `loadVizij` requires; rejects if mounting failed.
+ */
+declare function canvasMounted(): Promise<HTMLCanvasElement>;
+interface VizijCanvasProps {
+    /** `mount`'s options: every face's defaults. Read on the page's first
+     * mount; the App keeps them for the page's lifetime. */
+    options?: MountOptions;
+    /** Replace the default style — fixed over the page, pointer events off —
+     * of the element the canvas fills. A page that takes picks gives it
+     * pointer events. */
+    className?: string;
+    style?: CSSProperties;
+}
+/**
+ * The page's one canvas, which every `<Vizij>` slot draws on.
+ *
+ * Its first mount runs `@vizij/runtime`'s `mount`; a second `<VizijCanvas>`,
+ * a remount or React StrictMode's second effect shows the same canvas and
+ * App. While it is shown, one animation frame loop places each slot's face
+ * over the slot and hands each pick to the slot it names: `placeVizij` and
+ * `drainPicks` are page-wide, so they have one caller.
+ *
+ * By default the canvas is fixed over the page with pointer events off, so
+ * faces draw wherever their slots lie and the page's own UI keeps the
+ * pointer. Content that must draw over the faces stacks above the canvas.
+ */
+declare function VizijCanvas({ options, className, style, }: VizijCanvasProps): ReactNode;
+
+/**
+ * A face's own stages on its way to being drawn, as whoever loads it reports
+ * them (`setVizijProgress`): its GLB's bytes arriving (`total` is `null`
+ * when the length is unknown), `loadVizij`, then its first frame. `failed`
+ * ends the load.
+ */
+type VizijProgress = {
+    stage: "fetch";
+    loaded: number;
+    total: number | null;
+} | {
+    stage: "load";
+} | {
+    stage: "draw";
+} | {
+    stage: "failed";
+    error: Error;
+};
+/**
+ * Where a face's slot is on its way to showing the face: the runtime's
+ * stages (`@vizij/runtime`'s `onInitProgress` until `init()` resolves, then
+ * `mount`, the page's App being built), then the face's own.
+ */
+type LoadingStage = Exclude<InitProgress, {
+    stage: "ready";
+}> | {
+    stage: "mount";
+} | VizijProgress;
+/**
+ * Report face `vizijId`'s own stage, for the loading view of its slot
+ * (`<Vizij>`). `@vizij/runtime-react`'s provider reports its faces; a page
+ * that loads a face with `loadVizij` itself reports it the same way. `null`
+ * says no face is loaded under the id any more: its slot shows the loading
+ * view again until a face under the id is drawn.
+ *
+ * Whatever is reported, a slot hides its loading view once its face has been
+ * drawn (`ready(vizijId)`), and keeps it hidden through reloads, whose
+ * previous scene draws until the new one is ready.
+ */
+declare function setVizijProgress(vizijId: string, progress: VizijProgress | null): void;
+
+/** A slot's loading view, as `<Vizij>`'s `loading` render prop receives it. */
+interface VizijLoading {
+    stage: LoadingStage;
+    /** The stage in words: "Downloading the runtime: 3.1 of 9.8 MB". */
+    label: string;
+    /** How much of the stage is done, from 0 to 1, for the stages that count
+     * bytes against a known total; `null` (indeterminate) for the others. */
+    fraction: number | null;
+}
+
+interface VizijProps {
+    /** The face this slot shows: the id it is loaded under (`loadVizij`). */
+    vizijId: string;
+    /** Size and place the slot; the face draws over its border box. */
+    className?: string;
+    style?: CSSProperties;
+    /** The face's tone-mapping curve; `none` when absent. */
+    toneMapping?: ToneMapping;
+    /** How the framed bounds fit the slot; the canvas's `options.fit` when
+     * absent. */
+    fit?: Fit;
+    /** Magnification after the fit; the canvas's `options.zoom` when absent. */
+    zoom?: number | [number, number];
+    /** The world rectangle the face's camera frames, in place of the GLB's
+     * authored `rootBounds`. */
+    bounds?: Bounds;
+    /** Outline the framed bounds over the face. */
+    showSafeArea?: boolean;
+    /** The elements whose outlines glow, by the ids their RobotData declares.
+     * Absent, the slot leaves the face's selection as it is. */
+    selection?: string[];
+    /** A press on the face: the element under the pointer, or `null` for a
+     * press that hit none. Picks need pointer events on the canvas. */
+    onPick?: (pick: Pick) => void;
+    /** The image of the default loading view, in place of Vizij's logo,
+     * which `@vizij/render` ships; `null` for none. */
+    loadingImage?: ReactNode;
+    /** The slot's own loading view, in place of the default: called with the
+     * stage, its label and its fraction while the face is not drawn. `null`
+     * shows none. */
+    loading?: ((loading: VizijLoading) => ReactNode) | null;
+}
+/**
+ * Where face `vizijId` draws on the page's canvas (`<VizijCanvas>`): a
+ * `<div>` the canvas's frame loop places the face over, following it as the
+ * page scrolls and lays out. It renders no canvas of its own. One slot shows
+ * a face at a time.
+ *
+ * The element carries `data-vizij-id`, and `data-vizij-ready` — `"true"`
+ * once the face's scene shows its device's pose (`ready(vizijId)`).
+ *
+ * Until its face is first drawn, the slot shows a loading view over its
+ * border box: the runtime's stages, then the face's (`setVizijProgress`).
+ * The view is a DOM overlay in the slot: under a canvas laid over the page,
+ * it shows wherever the canvas draws nothing.
+ */
+declare function Vizij({ vizijId, className, style, toneMapping, fit, zoom, bounds, showSafeArea, selection, onPick, loadingImage, loading, }: VizijProps): ReactNode;
+
 /**
  * A wrapping type to reference an attribute that is animatable.
  *
@@ -48,6 +176,24 @@ interface StoredAnimatedFeature {
  * @param value - The id of the {@link AnimatableValue} used to populate this value if animated, or the value {@link RawValue} if static.
  */
 type Feature = AnimatedFeature | StaticFeature;
+/**
+ * A compound feature in its per-axis form: one feature per component, named
+ * `<feature>.<axis>` (`translation.x`, `rotation.r`, `color.g`), each a
+ * number. Semio Studio writes its faces this way. An element may carry a
+ * compound feature whole, per axis, or both; a component named per axis
+ * stands over that component of the whole value.
+ */
+type PerAxisFeatures<Name extends string, Axis extends string> = {
+    [Key in `${Name}.${Axis}`]?: Feature;
+};
+/** The components of a translation or a scale. */
+type VectorAxis = "x" | "y" | "z";
+/** The components of a rotation: roll, pitch and yaw, the euler's x, y and z. */
+type RotationAxis = "r" | "p" | "y";
+/** The components of a colour. */
+type ColorAxis = "r" | "g" | "b";
+/** An element's translation, rotation and scale, per axis. */
+type PerAxisTransformFeatures = PerAxisFeatures<"translation", VectorAxis> & PerAxisFeatures<"rotation", RotationAxis> & PerAxisFeatures<"scale", VectorAxis>;
 
 interface RenderableBase {
     id: string;
@@ -70,17 +216,17 @@ interface Stored<T extends Omit<RenderableBase, "refs">> {
 type StoredRenderable = Stored<RenderableBase>;
 
 /**
- * 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 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";
+interface Ellipse extends RenderableBase {
+    type: "ellipse";
     features: {
         height: Feature;
         width: Feature;
@@ -89,27 +235,26 @@ interface Rectangle extends RenderableBase {
         fillColor?: Feature;
         strokeColor?: Feature;
         strokeWidth?: Feature;
-        strokeRadius?: Feature;
         strokeOffset?: Feature;
-        translation: Feature;
-        rotation: Feature;
-    };
+        translation?: Feature;
+        rotation?: Feature;
+    } & PerAxisFeatures<"translation", VectorAxis> & PerAxisFeatures<"rotation", RotationAxis> & PerAxisFeatures<"fillColor", ColorAxis> & PerAxisFeatures<"strokeColor", ColorAxis>;
 }
-type RectangleFeature = keyof Rectangle["features"];
-type StoredRectangle = Stored<Rectangle>;
+type EllipseFeature = keyof Ellipse["features"];
+type StoredEllipse = Stored<Ellipse>;
 
 /**
- * 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 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";
+interface Rectangle extends RenderableBase {
+    type: "rectangle";
     features: {
         height: Feature;
         width: Feature;
@@ -118,13 +263,14 @@ interface Ellipse extends RenderableBase {
         fillColor?: Feature;
         strokeColor?: Feature;
         strokeWidth?: Feature;
+        strokeRadius?: Feature;
         strokeOffset?: Feature;
-        translation: Feature;
-        rotation: Feature;
-    };
+        translation?: Feature;
+        rotation?: Feature;
+    } & PerAxisFeatures<"translation", VectorAxis> & PerAxisFeatures<"rotation", RotationAxis> & PerAxisFeatures<"fillColor", ColorAxis> & PerAxisFeatures<"strokeColor", ColorAxis>;
 }
-type EllipseFeature = keyof Ellipse["features"];
-type StoredEllipse = Stored<Ellipse>;
+type RectangleFeature = keyof Rectangle["features"];
+type StoredRectangle = Stored<Rectangle>;
 
 /**
  * An object for creating hierarchies/groups
@@ -140,11 +286,12 @@ type StoredEllipse = Stored<Ellipse>;
 interface Group extends RenderableBase {
     type: "group";
     root: boolean;
+    /** Translation and rotation, each whole or per axis. */
     features: {
-        translation: Feature;
-        rotation: Feature;
+        translation?: Feature;
+        rotation?: Feature;
         scale?: Feature;
-    };
+    } & PerAxisTransformFeatures;
     rootBounds?: {
         center: RawVector2;
         size: RawVector2;
@@ -183,10 +330,10 @@ interface Shape extends RenderableBase {
         emissive?: Feature;
         emissiveIntensity?: Feature;
         specular?: Feature;
-        translation: Feature;
-        rotation: Feature;
+        translation?: Feature;
+        rotation?: Feature;
         scale?: Feature;
-    };
+    } & PerAxisTransformFeatures & PerAxisFeatures<"color", ColorAxis> & PerAxisFeatures<"emissive", ColorAxis> & PerAxisFeatures<"specular", ColorAxis>;
     material: ShapeMaterial;
     geometry: BufferGeometry | ShapeGeometry;
     morphTargets?: string[];
@@ -208,6 +355,8 @@ 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;
 
 /**
@@ -230,27 +379,20 @@ 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.
+ * A face's tone-mapping curve, as a bundle stores it and the view applies it
+ * (`@vizij/runtime`'s `ToneMapping`):
+ *
+ * - `"none"` — no curve: colors as shaded, clipped at 1.0, as plain web
+ *   rendering shows them. The default.
+ * - `"agx"` — AgX, Blender 4.x's default view transform: over-1.0 emissive
+ *   compressed into soft, slightly desaturated color, as faces authored in
+ *   Blender expect.
  * - `"aces"` — ACES Filmic, a punchier cinematic curve.
- * - `"neutral"` — Khronos PBR Neutral, a mild curve that preserves hue/saturation
- *   while taming highlights.
+ * - `"neutral"` — Khronos PBR Neutral, a mild curve that keeps hue and
+ *   saturation while taming highlights.
  */
-type ToneMappingMode = "none" | "agx" | "aces" | "neutral";
+type ToneMappingMode = ToneMapping;
 /**
  * The set of supported tone-mapping modes, in display order. Useful for
  * building selection UIs.
@@ -260,21 +402,12 @@ 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.
- */
+/** The tone-mapping mode of a face that specifies none. */
 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}.
@@ -503,68 +636,14 @@ 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;
     preferences: {
         damping: boolean;
     };
     elementSelection: Selection[];
-    hoveredElement: Selection | null;
-    slotConfig: Record<string, string>;
 }
 interface VizijActions {
     setValue: (id: string, namespace: string, value: RawValue | ((current: RawValue | undefined) => RawValue | undefined)) => void;
@@ -575,15 +654,9 @@ interface VizijActions {
     }>) => void;
     setWorldElementName: (id: string, value: string) => void;
     setVizij: (scene: World, animatables: Record<string, AnimatableValue>) => void;
-    setSlot: (parentId: string, parentNamespace: string, childId: string, childNamespace: string) => void;
-    setSlots: (slots: Record<string, string>, replace?: boolean) => void;
-    clearSlot: (parentId: string, parentNamespace: string) => void;
     addWorldElements: (world: World, animatables: Record<string, AnimatableValue>, replace?: boolean) => void;
     setPreferences: (preferences: Partial<VizijData["preferences"]>) => void;
-    getExportableBodies: (filterIds?: string[]) => Group$1[];
     updateElementSelection: (selection: Selection, chain: string[]) => void;
-    setHoveredElement: (selection: Selection | null) => void;
-    onElementClick: (selection: Selection, chain: string[], event: ThreeEvent<MouseEvent>) => void;
     clearSelection: () => void;
     setOrigin: (id: string, origin: {
         translation?: THREE.Vector3;
@@ -598,7 +671,6 @@ 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 | null>) => void;
     createGroup: (root: boolean) => void;
     createAnimatable: (elementId: string, featureName: string, value: Partial<AnimatableValue>) => void;
     createStatic: (elementId: string, featureName: string, value: RawValue) => void;
@@ -606,23 +678,16 @@ interface VizijActions {
 type VizijStoreSetter = (partial: (VizijData & VizijActions) | Partial<VizijData & VizijActions> | ((state: VizijData & VizijActions) => (VizijData & VizijActions) | Partial<VizijData & VizijActions>), replace?: false | undefined) => void;
 type VizijStoreGetter = () => VizijData & VizijActions;
 
-declare const VizijSlice: (set: VizijStoreSetter, get: VizijStoreGetter) => {
+declare const VizijSlice: (set: VizijStoreSetter, _get: VizijStoreGetter) => {
     world: {};
-    refs: {};
     animatables: {};
     values: Map<any, any>;
-    renderHit: boolean;
     preferences: {
         damping: boolean;
     };
     elementSelection: never[];
-    hoveredElement: null;
-    slotConfig: {};
     clearSelection: () => void;
     updateElementSelection: (selection: Selection, _chain: string[]) => void;
-    setHoveredElement: (selection: Selection | null) => void;
-    onElementClick: (selection: Selection, _chain: string[], event: ThreeEvent<MouseEvent>) => void;
-    getExportableBodies: (filterIds?: string[]) => THREE.Group<THREE.Object3DEventMap>[];
     setGeometry: (id: string, geometry: THREE.BufferGeometry) => void;
     setValue: (id: string, namespace: string, value: RawValue | ((current: RawValue | undefined) => RawValue | undefined)) => void;
     setValues: (writes?: Array<{
@@ -646,13 +711,9 @@ declare const VizijSlice: (set: VizijStoreSetter, get: VizijStoreGetter) => {
     createAnimatable: (elementId: string, featureName: string, value: Partial<AnimatableValue>) => void;
     createStatic: (elementId: string, featureName: string, value: RawValue) => void;
     setAnimatableValue: (id: string, value: AnimatableValue) => void;
-    setSlot: (parentId: string, parentNamespace: string, childId: string, childNamespace: string) => void;
-    setSlots: (slots: Record<string, string>, replace?: boolean) => void;
-    clearSlot: (parentId: string, parentNamespace: string) => void;
     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 | null>) => void;
 };
 declare const useDefaultVizijStore: zustand.UseBoundStore<Omit<zustand.StoreApi<VizijData & VizijActions>, "subscribe"> & {
     subscribe: {
@@ -688,25 +749,6 @@ declare function useVizijStore<T>(selector: (state: VizijData & VizijActions) =>
 
 declare function useVizijStoreSubscription<T>(selector: (state: VizijData & VizijActions) => T, listener: (state: T) => void): void;
 
-/**
- * Custom React hook to manage and subscribe to feature values.
- *
- * @param namespace - The namespace for the features.
- * @param features - A record of feature objects keyed by their IDs.
- * @param callbacks - A record of callback functions keyed by feature IDs.
- * @param debugInfo - Optional debug information to log in case of errors.
- *
- * @throws [Error] If the SceneContext store is not found.
- *
- * @returns [void]
- *
- * This hook sets up subscriptions to feature values and invokes the provided callbacks when the values change.
- * It handles both animated and non-animated features. For animated features, it subscribes to the animatable value
- * in the store and invokes the callback whenever the value changes. For non-animated features, it immediately
- * invokes the callback with the feature's value.
- */
-declare function useFeatures(namespace: string, features: Record<string, Feature>, callbacks: Record<string, (current: RawValue) => void>, debugInfo?: any): void;
-
 declare function useVizijStoreSetter(): {
     (partial: (VizijData & VizijActions) | Partial<VizijData & VizijActions> | ((state: VizijData & VizijActions) => (VizijData & VizijActions) | Partial<VizijData & VizijActions>), replace?: false): void;
     (state: (VizijData & VizijActions) | ((state: VizijData & VizijActions) => VizijData & VizijActions), replace: true): void;
@@ -714,9 +756,15 @@ declare function useVizijStoreSetter(): {
 
 declare function useVizijStoreGetter(): () => VizijData & VizijActions;
 
+/**
+ * The error a load ends with when the GLB holds no face: no element carries
+ * `RobotData`, and the aggressive import finds no mesh, ellipse or rectangle
+ * to make one from.
+ */
 declare class EmptyModelError extends Error {
     constructor(message: string);
 }
+
 type ParserJsonFallbackSource = {
     url?: string;
     arrayBuffer?: ArrayBuffer;
@@ -752,7 +800,11 @@ declare function loadGLTFFromBlobWithBundle(blob: Blob, aggressiveImport?: boole
     size: RawVector2;
 }): Promise<LoadedVizijAsset>;
 
-declare function deriveRootBounds(group: Group$1): {
+/**
+ * The bounds of everything under `group` in the XY plane: its meshes, and its
+ * `ellipse` and `rectangle` elements' shapes. `null` when it holds neither.
+ */
+declare function deriveRootBounds(group: Object3D): {
     center: RawVector2;
     size: RawVector2;
 } | null;
@@ -794,6 +846,64 @@ declare function patchVizijBundleMetadata(glb: ArrayBuffer, metadata: Record<str
  */
 declare function exportScene(root: THREE.Object3D, options?: ExportSceneOptions): Promise<ArrayBuffer>;
 
+/** A glTF-animatable node property, under three.js's property name. */
+type ExportAnimationProperty = "position" | "quaternion" | "scale" | "morphTargetInfluences";
+/** One node property's keys, to export as a glTF animation channel. */
+interface ExportAnimationTrack {
+    /**
+     * The property-binding path: `<node>.<property>`, or
+     * `<node>.morphTargetInfluences[<morph target name>]`.
+     */
+    name: string;
+    property: ExportAnimationProperty;
+    /** The name of the node the track drives. */
+    elementName: string;
+    /** Key times, in seconds, ascending. */
+    times: number[];
+    /** Flattened key values, `times.length * stride` of them. */
+    values: number[];
+    /** Values per key: 3 for a position or scale, 4 for a quaternion, 1 for a morph weight. */
+    stride: number;
+}
+interface ExportAnimationIssue {
+    trackName: string;
+    reason: "node-not-found" | "morph-target-not-found" | "bad-stride";
+    detail?: string;
+}
+/**
+ * What a track binds against: the export root and its descendants, found by
+ * name. The graph `buildSceneGraph` returns is one.
+ */
+interface ExportAnimationRoot {
+    name: string;
+    traverse: (callback: (child: ExportAnimationRoot) => void) => void;
+    morphTargetDictionary?: Record<string, number>;
+}
+interface ExportAnimationResult {
+    /** For `exportScene({ animations })`; `null` when no track binds. */
+    animation: AnimationClip | null;
+    /** The tracks left out, each with why. */
+    issues: ExportAnimationIssue[];
+}
+/**
+ * An animation for `exportScene`, from baked tracks, each checked against the
+ * tree it will be exported with.
+ *
+ * The exporter drops a whole animation when one track fails to bind, and
+ * throws when a morph target name is missing from the mesh's
+ * `morphTargetDictionary`. So each track is bound here first, by node name
+ * (`exportScene` clones a root that is not a `Scene`, which keeps names and
+ * changes uuids), and a track that would not bind is left out and reported.
+ */
+declare function createExportAnimation(options: {
+    name: string;
+    /** In seconds. */
+    duration: number;
+    tracks: ReadonlyArray<ExportAnimationTrack>;
+    /** The tree the animation will be exported with. */
+    root: ExportAnimationRoot;
+}): ExportAnimationResult;
+
 /**
  * Build the three.js graph of the world element `rootId` and its descendants,
  * for `exportScene`.
@@ -803,6 +913,12 @@ declare function exportScene(root: THREE.Object3D, options?: ExportSceneOptions)
  * them, with the element's `RobotData` in `userData`. No renderer is involved,
  * so this runs in Node.
  *
+ * A compound feature — translation, rotation, scale, a colour — is read whole,
+ * per axis (`translation.x`, `rotation.r`, `color.g`: Semio Studio's form),
+ * or both, a component given per axis standing over the whole value's. A
+ * rotation is an euler `{ x, y, z }` or, as Studio names it, `{ r, p, y }`
+ * (roll, pitch, yaw), applied in ZYX order.
+ *
  * 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
@@ -810,9 +926,14 @@ declare function exportScene(root: THREE.Object3D, options?: ExportSceneOptions)
  * 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.
+ * An ellipse or a rectangle becomes a node with no mesh: its RobotData —
+ * `type`, `width`, `height`, `fillColor`, `fillOpacity` among its features —
+ * is what the Bevy view draws it from (a unit circle or square scaled by the
+ * width and height, filled with the colour and opacity). The node carries its
+ * translation and rotation, and the width and height as its scale on X and Y.
+ *
+ * Throws when an element is missing from `world`, and when an animated
+ * feature names an animatable missing from `animatables`.
  */
 declare function buildSceneGraph(world: World, animatables: Record<string, AnimatableValue>, rootId: string): THREE.Object3D;
 
@@ -854,4 +975,4 @@ declare function sanitizeMorphKey(name: string, fallbackIndex: number, used: Set
  */
 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 };
+export { type AnimatedFeature, type ColorAxis, DEFAULT_TONE_MAPPING_MODE, type Ellipse, type EllipseFeature, EmptyModelError, type ExportAnimationIssue, type ExportAnimationProperty, type ExportAnimationResult, type ExportAnimationRoot, type ExportAnimationTrack, type ExportSceneOptions, type Feature, type Group, type GroupFeature, type LoadedVizijAsset, type LoadingStage, type PerAxisFeatures, type PerAxisTransformFeatures, type Rectangle, type RectangleFeature, type RenderableBase, type RenderableFeature, type RotationAxis, 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, type VectorAxis, 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, VizijCanvas, type VizijCanvasProps, VizijContext, type VizijData, type VizijGraphId, type VizijLoading, type VizijPoseDefinition, type VizijPoseId, type VizijPoseRigConfig, type VizijProfileKey, type VizijProgress, type VizijProps, VizijSlice, type VizijSpeechConfig, type VizijStarredItem, type VizijStarredKind, type VizijStore, type VizijStoreGetter, type VizijStoreSetter, type World, applyVizijBundle, buildSceneGraph, canvasMounted, createExportAnimation, createVizijStore, deriveMorphFeatureKeys, deriveRootBounds, exportScene, extractVizijBundle, isToneMappingMode, loadGLTF, loadGLTFFromBlob, loadGLTFFromBlobWithBundle, loadGLTFWithBundle, normalizeToneMappingMode, parseGlbJsonChunk, patchGlbJson, patchVizijBundleMetadata, sanitizeMorphKey, setVizijProgress, useDefaultVizijStore, useVizijStore, useVizijStoreGetter, useVizijStoreSetter, useVizijStoreSubscription };