@vizij/render 0.1.0 → 0.1.2

package/README.md

@@ -2,7 +2,7 @@
 
 > Three.js + React renderer, scene store, and helper controllers for Vizij faces.
 
-This package exposes the `Vizij` canvas component along with hooks, stores, and GLTF helpers that power Vizij’s real-time character visualisation. It is the foundation that other packages (`@vizij/rig`, `@vizij/orchestrator-react`, etc.) build upon.
+This package exposes the `Vizij` canvas component along with hooks, stores, and GLTF helpers that power Vizij’s real-time character visualisation. It is the foundation that other packages (`@vizij/runtime-react`, etc.) build upon.
 
 ---
 
@@ -96,14 +96,14 @@ 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/rig`.
+- `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).
 
 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.
+Vizij scenes persist authoring metadata inside GLBs so third-party tools see baked animation, while Vizij runtimes retain the authored 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.
@@ -112,7 +112,7 @@ Vizij scenes persist authoring metadata inside GLBs so third-party tools see bak
 - The new `animations` field exposes `VizijAnimationClipData[]`, which maps each glTF animation channel back to Vizij animatable ids (`RobotData.features.*.value.id`). Each track provides component-aware `times`/`values` arrays so runtimes can register clips without re-parsing the GLB.
 - `extractVizijBundle(scene)` and `applyVizijBundle(scene, bundle)` (under `src/functions/vizij-bundle.ts`) let advanced tooling inspect or mutate bundles without triggering a fresh export.
 
-With this structure, authoring tools can round-trip orchestrator assets while shipping native glTF animations for viewers that do not understand Vizij.
+With this structure, authoring tools can round-trip Vizij runtime assets while shipping native glTF animations for viewers that do not understand Vizij.
 
 ---
 
@@ -132,14 +132,17 @@ pnpm --filter "@vizij/render" size
 
 ## Publishing
 
-Use the shared workflow at [`.github/workflows/publish-npm.yml`](../../.github/workflows/publish-npm.yml).
+Use the shared workflow at [`.github/workflows/publish-npm.yml`](../../../.github/workflows/publish-npm.yml).
 
 1. Align dependency versions (`three`, `@react-three/*`, `zustand`, Vizij packages) and generate a changeset:
+
    ```bash
    pnpm changeset
    pnpm version:packages
    ```
+
 2. Validate locally:
+
    ```bash
    pnpm install
    pnpm --filter "@vizij/render" build
@@ -148,13 +151,14 @@ Use the shared workflow at [`.github/workflows/publish-npm.yml`](../../.github/w
    pnpm --filter "@vizij/render" lint
    pnpm --filter "@vizij/render" exec npm pack --dry-run
    ```
-3. Tag the release as `npm-render-vX.Y.Z` and push the tag. The workflow will publish with provenance metadata.
+
+3. Merge the version bump to `main`. CI publishes any `@vizij/*` version not yet on npm (with provenance) — no release tag. See the root [README → Publishing & Versioning](../../../README.md#publishing--versioning).
 
 ---
 
 ## Related Packages
 
-- [`@vizij/rig`](../@vizij/rig/README.md) – Hooks that consume the renderer to load rigged models.
-- [`@vizij/animation-react`](../@vizij/animation-react/README.md) – React bindings that feed animation values back into the renderer.
+- [`@vizij/runtime-react`](../runtime-react/README.md) – Hooks that consume the renderer to load rigged models.
+- [`@vizij/animation-react`](../animation-react/README.md) – React bindings that feed animation values back into the renderer.
 
 Questions or contributions? Open an issue so we can keep the renderer API and docs sharp for the whole Vizij ecosystem. 🎨

package/dist/index.d.mts

@@ -227,6 +227,9 @@ interface Shape extends RenderableBase {
         roughness?: Feature;
         metalness?: Feature;
         color?: Feature;
+        emissive?: Feature;
+        emissiveIntensity?: Feature;
+        specular?: Feature;
         translation: Feature;
         rotation: Feature;
         scale?: Feature;
@@ -357,12 +360,40 @@ interface VizijBundleAnimationEntry {
         [key: string]: unknown;
     };
 }
+interface VizijSpeechConfig {
+    /** TTS voice name (e.g., "Ruth") */
+    voice?: string;
+    /** Speech mode */
+    mode?: "echo" | "conversation";
+    /** Agent name for LLM system prompt */
+    agentName?: string;
+    /** Custom system prompt (supports {{agent_name}} template) */
+    systemPrompt?: string;
+    /** Input path for avatar-speaking state (default: /speech/speaking) */
+    speakingInputPath?: string;
+    /** Input path for user-speaking state (default: /speech/user_speaking) */
+    userSpeakingInputPath?: string;
+    /** Input path for thinking state (default: /speech/thinking) */
+    thinkingInputPath?: string;
+    /** Pose group ID for viseme mapping */
+    visemeGroupId?: string;
+    /** Pose group ID for emotion mapping */
+    emotionGroupId?: string;
+    /** TTS API base URL */
+    apiBaseUrl?: string;
+    /** Auto-activate microphone when speech is ready (default: false) */
+    autoActivateMic?: boolean;
+}
 interface VizijBundleExtension {
     version: VizijBundleVersion;
     exportedAt?: string;
     graphs?: VizijBundleGraphEntry[];
     poses?: VizijBundlePoseSection | null;
     animations?: VizijBundleAnimationEntry[];
+    /**
+     * Bundle-level metadata. May include `speechConfig: VizijSpeechConfig`
+     * for configuring the STT/LLM/TTS speech pipeline.
+     */
     metadata?: Record<string, unknown>;
 }
 
@@ -571,6 +602,12 @@ declare function useVizijStoreGetter(): () => VizijData & VizijActions;
 declare class EmptyModelError extends Error {
     constructor(message: string);
 }
+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?: {
     center: RawVector2;
     size: RawVector2;
@@ -584,11 +621,12 @@ type LoadedVizijAsset = {
     animatables: Record<string, AnimatableValue>;
     bundle: VizijBundleExtension | null;
     animations: VizijAnimationClipData[];
+    scene: Group$1;
 };
 declare function loadGLTFWithBundle(url: string, namespaces: string[], aggressiveImport?: boolean, rootBounds?: {
     center: RawVector2;
     size: RawVector2;
-}): Promise<LoadedVizijAsset>;
+}, parserJsonFallback?: ParserJsonFallbackSource): Promise<LoadedVizijAsset>;
 declare function loadGLTFFromBlobWithBundle(blob: Blob, namespaces: string[], aggressiveImport?: boolean, rootBounds?: {
     center: RawVector2;
     size: RawVector2;
@@ -607,10 +645,12 @@ type ExportSceneOptions = {
     bundle?: VizijBundleExtension | null;
     animations?: AnimationClip[];
     binary?: boolean;
+    onError?: (error: Error) => void;
+    onComplete?: () => void;
 };
 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, type Ellipse, type EllipseFeature, EmptyModelError, type ExportSceneOptions, type Feature, type Group, type GroupFeature, InnerVizij, type InnerVizijProps, type LoadedVizijAsset, type Rectangle, type RectangleFeature, type RenderableBase, type RenderableFeature, type Selection, type Shape, type ShapeFeature, ShapeMaterial, type StaticFeature, type Stored, type StoredAnimatedFeature, type StoredEllipse, type StoredFeatures, type StoredGroup, type StoredRectangle, type StoredRenderable, type StoredShape, Vizij, type VizijActions, type VizijAnimationClipData, type VizijAnimationId, type VizijAnimationTrackData, type VizijBundleAnimationClip, type VizijBundleAnimationEntry, type VizijBundleAnimationKeyframe, type VizijBundleAnimationTrack, type VizijBundleExtension, type VizijBundleGraphEntry, type VizijBundleGraphKind, type VizijBundleGraphMetadata, type VizijBundlePoseSection, type VizijBundleVersion, VizijContext, type VizijData, type VizijGraphId, type VizijPoseDefinition, type VizijPoseId, type VizijPoseRigConfig, type VizijProps, VizijSlice, type VizijStore, type VizijStoreGetter, type VizijStoreSetter, type World, applyVizijBundle, createVizijStore, exportScene, extractVizijBundle, loadGLTF, loadGLTFFromBlob, loadGLTFFromBlobWithBundle, loadGLTFWithBundle, loadGltfFromBlob, useDefaultVizijStore, useFeatures, useVizijStore, useVizijStoreGetter, useVizijStoreSetter, useVizijStoreSubscription };
+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 };

package/dist/index.d.ts

@@ -227,6 +227,9 @@ interface Shape extends RenderableBase {
         roughness?: Feature;
         metalness?: Feature;
         color?: Feature;
+        emissive?: Feature;
+        emissiveIntensity?: Feature;
+        specular?: Feature;
         translation: Feature;
         rotation: Feature;
         scale?: Feature;
@@ -357,12 +360,40 @@ interface VizijBundleAnimationEntry {
         [key: string]: unknown;
     };
 }
+interface VizijSpeechConfig {
+    /** TTS voice name (e.g., "Ruth") */
+    voice?: string;
+    /** Speech mode */
+    mode?: "echo" | "conversation";
+    /** Agent name for LLM system prompt */
+    agentName?: string;
+    /** Custom system prompt (supports {{agent_name}} template) */
+    systemPrompt?: string;
+    /** Input path for avatar-speaking state (default: /speech/speaking) */
+    speakingInputPath?: string;
+    /** Input path for user-speaking state (default: /speech/user_speaking) */
+    userSpeakingInputPath?: string;
+    /** Input path for thinking state (default: /speech/thinking) */
+    thinkingInputPath?: string;
+    /** Pose group ID for viseme mapping */
+    visemeGroupId?: string;
+    /** Pose group ID for emotion mapping */
+    emotionGroupId?: string;
+    /** TTS API base URL */
+    apiBaseUrl?: string;
+    /** Auto-activate microphone when speech is ready (default: false) */
+    autoActivateMic?: boolean;
+}
 interface VizijBundleExtension {
     version: VizijBundleVersion;
     exportedAt?: string;
     graphs?: VizijBundleGraphEntry[];
     poses?: VizijBundlePoseSection | null;
     animations?: VizijBundleAnimationEntry[];
+    /**
+     * Bundle-level metadata. May include `speechConfig: VizijSpeechConfig`
+     * for configuring the STT/LLM/TTS speech pipeline.
+     */
     metadata?: Record<string, unknown>;
 }
 
@@ -571,6 +602,12 @@ declare function useVizijStoreGetter(): () => VizijData & VizijActions;
 declare class EmptyModelError extends Error {
     constructor(message: string);
 }
+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?: {
     center: RawVector2;
     size: RawVector2;
@@ -584,11 +621,12 @@ type LoadedVizijAsset = {
     animatables: Record<string, AnimatableValue>;
     bundle: VizijBundleExtension | null;
     animations: VizijAnimationClipData[];
+    scene: Group$1;
 };
 declare function loadGLTFWithBundle(url: string, namespaces: string[], aggressiveImport?: boolean, rootBounds?: {
     center: RawVector2;
     size: RawVector2;
-}): Promise<LoadedVizijAsset>;
+}, parserJsonFallback?: ParserJsonFallbackSource): Promise<LoadedVizijAsset>;
 declare function loadGLTFFromBlobWithBundle(blob: Blob, namespaces: string[], aggressiveImport?: boolean, rootBounds?: {
     center: RawVector2;
     size: RawVector2;
@@ -607,10 +645,12 @@ type ExportSceneOptions = {
     bundle?: VizijBundleExtension | null;
     animations?: AnimationClip[];
     binary?: boolean;
+    onError?: (error: Error) => void;
+    onComplete?: () => void;
 };
 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, type Ellipse, type EllipseFeature, EmptyModelError, type ExportSceneOptions, type Feature, type Group, type GroupFeature, InnerVizij, type InnerVizijProps, type LoadedVizijAsset, type Rectangle, type RectangleFeature, type RenderableBase, type RenderableFeature, type Selection, type Shape, type ShapeFeature, ShapeMaterial, type StaticFeature, type Stored, type StoredAnimatedFeature, type StoredEllipse, type StoredFeatures, type StoredGroup, type StoredRectangle, type StoredRenderable, type StoredShape, Vizij, type VizijActions, type VizijAnimationClipData, type VizijAnimationId, type VizijAnimationTrackData, type VizijBundleAnimationClip, type VizijBundleAnimationEntry, type VizijBundleAnimationKeyframe, type VizijBundleAnimationTrack, type VizijBundleExtension, type VizijBundleGraphEntry, type VizijBundleGraphKind, type VizijBundleGraphMetadata, type VizijBundlePoseSection, type VizijBundleVersion, VizijContext, type VizijData, type VizijGraphId, type VizijPoseDefinition, type VizijPoseId, type VizijPoseRigConfig, type VizijProps, VizijSlice, type VizijStore, type VizijStoreGetter, type VizijStoreSetter, type World, applyVizijBundle, createVizijStore, exportScene, extractVizijBundle, loadGLTF, loadGLTFFromBlob, loadGLTFFromBlobWithBundle, loadGLTFWithBundle, loadGltfFromBlob, useDefaultVizijStore, useFeatures, useVizijStore, useVizijStoreGetter, useVizijStoreSetter, useVizijStoreSubscription };
+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 };