@lovelace_lol/embody 0.0.12 → 0.0.14

package/dist/three/annotations/types.d.ts

@@ -180,9 +180,8 @@ export interface CharacterRegistry {
     defaultCharacter?: string;
 }
 export type AUPresetType = string;
-export type DPthreeRegion = AnnotationAnchoredRegion;
-export type DPthreeCharacterConfig = AnnotationCharacterConfig;
-export type DPthreeRegistry = CharacterRegistry;
+export type AnnotationRegion = AnnotationAnchoredRegion;
+export type AnnotationRegistry = CharacterRegistry;
 /**
  * Camera state for save/restore
  */
@@ -191,16 +190,16 @@ export interface CameraState {
     target: [number, number, number];
 }
 /**
- * Configuration for DPthreeCameraController
+ * Configuration for ThreeAnnotationController
  */
-export interface DPthreeCameraControllerConfig {
+export interface ThreeAnnotationControllerConfig {
     /** Optional selection override; otherwise selecting a region focuses the camera. */
     onRegionSelect?: (name: string) => void;
     /** Optional host profile intake; defaults to Embody preset resolution. */
     resolveCharacterConfig?: (config: AnnotationCharacterConfig) => AnnotationCharacterConfig | Promise<AnnotationCharacterConfig>;
     /** The Three.js camera to control */
     camera: THREE.PerspectiveCamera;
-    /** DOM element for OrbitControls (usually the canvas or its container) */
+    /** DOM element for Rust camera gestures (usually the canvas or its container) */
     domElement: HTMLElement;
     /** The Three.js scene */
     scene: THREE.Scene;
@@ -258,5 +257,5 @@ export type RegionChangeCallback = (regionName: string) => void;
  * Callback for character change events
  */
 export type CharacterChangeCallback = (config: CharacterConfig) => void;
-export type DPthreeRegionChangeCallback = RegionChangeCallback;
-export type DPthreeCharacterChangeCallback = CharacterChangeCallback;
+export type AnnotationRegionChangeCallback = RegionChangeCallback;
+export type AnnotationCharacterChangeCallback = CharacterChangeCallback;

package/dist/three/authoring.d.ts

@@ -75,7 +75,7 @@ export declare function analyzeModel(options: {
     preset?: Types.Profile;
     suggestCorrections?: boolean;
 }): Promise<Types.ModelAnalysisReport>;
-export declare function validateMappings(meshes: unknown[], skeleton: unknown, profile: Types.Profile, options?: Record<string, unknown>): Types.ValidationResult;
+export declare function validateMappings(meshes: unknown[], skeleton: unknown, profile: Partial<Types.Profile>, options?: Record<string, unknown>): Types.ValidationResult;
 export declare function validateHumanoidCharacterization(model: Object3D, profile: Types.Profile): Types.HumanoidCharacterizationResolution;
 export declare function normalizeHairColorAppearance(value: Types.HairColorAppearance | string, fallback?: Types.HairColorAppearance): Types.HairColorAppearance;
 export declare const getHumanoidSkeletonTemplate: (id: string) => Types.HumanoidSkeletonTemplate | null;

package/dist/three/characterHost.d.ts

@@ -2,12 +2,16 @@ import type { Camera, Scene } from 'three';
 import { Embody } from './character';
 import type { RustEmbodyHostConfig } from './character';
 import type { CharacterModelLoadOptions, CharacterModelLoadResult, CharacterModelTransform } from './model';
-import type { CharacterSceneBackend, CharacterSceneRenderer, CharacterSceneRenderingController, DefaultCharacterSceneAsyncOptions, ReadyDefaultCharacterScene } from './scene';
+import type { CharacterSceneBackend, CharacterSceneConfiguration, CharacterSceneRenderer, CharacterSceneRenderingController, DefaultCharacterSceneAsyncOptions, ReadyDefaultCharacterScene } from './scene';
+import { ThreeAnnotationController } from './annotations/ThreeAnnotationController';
+import type { AnnotationCharacterConfig, ThreeAnnotationControllerConfig } from './annotations/types';
 import type { Profile } from './authoringTypes';
 export interface CharacterHostCharacterOptions extends CharacterModelTransform {
     modelUrl: string;
     presetType?: string;
-    profile?: Profile;
+    profile?: Partial<Profile>;
+    annotationConfig?: AnnotationCharacterConfig;
+    scene?: CharacterSceneConfiguration;
 }
 export interface CharacterHostExternalScene {
     scene: Scene;
@@ -17,7 +21,22 @@ export interface CharacterHostExternalScene {
     camera: Camera;
     mountCanvas?: boolean;
     manageResize?: boolean;
+    setSceneSettings?: (settings: CharacterSceneConfiguration) => void;
 }
+export type CharacterHostModelLoader = (modelUrl: string, options: CharacterModelLoadOptions & {
+    signal: AbortSignal;
+}) => Promise<CharacterModelLoadResult>;
+export type CharacterHostPreparation = CharacterModelLoadResult & {
+    engine: Embody;
+    character: CharacterHostCharacterOptions;
+    signal: AbortSignal;
+};
+export type CharacterHostReady = CharacterHostPreparation & {
+    scene: Scene;
+    camera: Camera;
+    cameraController: ThreeAnnotationController | null;
+    rendering: CharacterSceneRenderingController | null;
+};
 export interface CharacterHostOptions {
     signal?: AbortSignal;
     container: HTMLElement;
@@ -26,23 +45,32 @@ export interface CharacterHostOptions {
     scene?: Omit<DefaultCharacterSceneAsyncOptions, 'signal'>;
     external?: CharacterHostExternalScene;
     loader?: CharacterModelLoadOptions;
+    /** Storage authorization and byte caching remain with the application. */
+    loadModel?: CharacterHostModelLoader;
+    /** Replays authored mesh edits through the bound engine before GPU preparation. */
+    prepareCharacter?: (context: CharacterHostPreparation) => void | Promise<void>;
+    onCharacterReady?: (context: CharacterHostReady) => void | Promise<void>;
+    /** Default true for compatibility. Editors can retain clips in a lazy catalog. */
+    registerEmbeddedAnimations?: boolean;
+    camera?: Omit<Partial<ThreeAnnotationControllerConfig>, 'scene' | 'camera' | 'renderer' | 'rendering' | 'domElement'>;
     autoStart?: boolean;
     renderLoop?: boolean;
     autoFrame?: boolean;
 }
-export interface CharacterHost extends Omit<CharacterModelLoadResult, 'gltf'> {
+export interface CharacterHost extends CharacterModelLoadResult {
     engine: Embody;
     scene: Scene;
     readonly renderer: CharacterSceneRenderer | null;
     readonly backend: CharacterSceneBackend | null;
     readonly rendering: CharacterSceneRenderingController | null;
     camera: Camera;
+    cameraController: ThreeAnnotationController | null;
     lighting: ReadyDefaultCharacterScene['lighting'] | null;
     ownsScene: boolean;
     container: HTMLElement;
-    setCharacter(character: CharacterHostCharacterOptions, loader?: CharacterModelLoadOptions): Promise<void>;
+    setCharacter(character: CharacterHostCharacterOptions, loader?: CharacterModelLoadOptions, signal?: AbortSignal): Promise<void>;
     resize(): void;
     dispose(): Promise<void>;
 }
-/** Acquire a character and bind it to the existing Three rendering integration. */
+/** Acquire, prepare and reveal a character using the existing native render owner. */
 export declare function createCharacterHost(options: CharacterHostOptions): Promise<CharacterHost>;

package/dist/three/characterTexturePalette.d.ts

@@ -0,0 +1,6 @@
+import * as THREE from 'three';
+import type { SceneInkBackgroundPalette } from './sceneInkBackground';
+/** Reuse the finished palette on character switches without resampling textures. */
+export declare function readCachedCharacterPalette(cacheKey: string): SceneInkBackgroundPalette | null;
+export declare function resolveCharacterMaterialPalette(model: THREE.Object3D, cacheKey: string): SceneInkBackgroundPalette | null;
+export declare function resolveCharacterTexturePalette(model: THREE.Object3D, cacheKey: string): Promise<SceneInkBackgroundPalette | null>;

package/dist/three/editor/SkeletonOverlay.d.ts

@@ -0,0 +1,128 @@
+import * as THREE from 'three';
+export interface BoneTreeNode {
+    name: string;
+    depth: number;
+    parent: string | null;
+    children: string[];
+    isMapped: boolean;
+    /** Semantic key if this bone is mapped (e.g., 'HEAD', 'JAW') */
+    semanticKey: string | null;
+    /** Full semantic-key set for tree badge rendering when a row resolves multiple mappings */
+    semanticKeys?: string[];
+    /** Live reference to the Three.js bone object */
+    boneObject: THREE.Bone;
+}
+export interface SkeletonOverlayOptions {
+    opacityScale?: number;
+    focusSelectedBone?: boolean;
+}
+type OverlayAxisKey = 'pitch' | 'yaw' | 'roll';
+export type SkeletonOverlayAxisKey = OverlayAxisKey;
+type SkeletonOverlayRotationChannel = 'rx' | 'ry' | 'rz';
+export interface AxisGizmoPointerData {
+    axis: SkeletonOverlayAxisKey;
+    channel: SkeletonOverlayRotationChannel;
+    boneName: string;
+    point: THREE.Vector3;
+    origin: THREE.Vector3;
+    quaternion: THREE.Quaternion;
+}
+export declare function resolveSkeletonOverlayStartBoneName(root: THREE.Object3D): string | null;
+export declare class SkeletonOverlay {
+    private scene;
+    private group;
+    private visualizations;
+    private boneTree;
+    private mappedBoneNames;
+    private semanticKeyMap;
+    private boneLookup;
+    private sharedGeometry;
+    private mappedMaterial;
+    private unmappedMaterial;
+    private highlightMaterial;
+    private selectedMaterial;
+    private contextMaterial;
+    private mutedMaterial;
+    private axisRingGeometry;
+    private axisRingHitGeometry;
+    private axisCenterGeometry;
+    private pitchRingMaterial;
+    private yawRingMaterial;
+    private rollRingMaterial;
+    private axisHitMaterial;
+    private axisCenterMaterial;
+    private axisGizmoGroup;
+    private axisGizmoMeshes;
+    private axisGizmoHitMeshes;
+    private sentinelMesh;
+    private highlightedBone;
+    private selectedBone;
+    private activeAxis;
+    private opacityScale;
+    private focusSelectedBone;
+    private visibilityAlpha;
+    private visibilityTarget;
+    private visibilityLastFrameAt;
+    constructor(scene: THREE.Scene, mappedBoneNames: Set<string>, semanticKeyMap: Map<string, string>, options?: SkeletonOverlayOptions);
+    /**
+     * Build the skeleton visualization from a scene root.
+     * Traverses to find all THREE.Bone instances and creates octahedral meshes.
+     */
+    loadSkeleton(root: THREE.Object3D): void;
+    private createBoneMesh;
+    /** Called each frame via onBeforeRender. Updates all bone mesh transforms. */
+    private update;
+    private syncVisibilityOpacity;
+    private syncGroupVisibility;
+    private advanceVisibility;
+    private resolveSelectedBoneObject;
+    private resolveBoneRelativeAxisGizmoRadius;
+    private resolveScreenSpaceAxisGizmoRadius;
+    private resolveAxisGizmoRadius;
+    private updateAxisGizmoAppearance;
+    private updateAxisGizmo;
+    private applyAxisRingChannel;
+    private syncAxisGizmoChannels;
+    private getSelectedBonePointerData;
+    private getAxisPlaneNormal;
+    getBoneTree(): BoneTreeNode[];
+    setVisible(visible: boolean): void;
+    isVisible(): boolean;
+    setHighlighted(boneName: string | null): void;
+    setSelected(boneName: string | null): void;
+    setActiveAxis(axis: OverlayAxisKey | null): void;
+    /** Get world position and rotation for a bone by name */
+    getBoneTransform(boneName: string): {
+        position: [number, number, number];
+        rotation: [number, number, number];
+    } | null;
+    pickBone(clientX: number, clientY: number, camera: THREE.Camera, domElement: HTMLElement): string | null;
+    pickAxisGizmo(clientX: number, clientY: number, camera: THREE.Camera, domElement: HTMLElement): AxisGizmoPointerData | null;
+    projectPointerToAxisPlane(clientX: number, clientY: number, camera: THREE.Camera, domElement: HTMLElement, axis: SkeletonOverlayAxisKey): AxisGizmoPointerData | null;
+    private isSelectedContextBone;
+    private resolveBoneMaterial;
+    private refreshBoneMaterials;
+    private clear;
+    dispose(): void;
+}
+export declare function collectSkeletonBones(root: THREE.Object3D): THREE.Bone[];
+/**
+ * Find the model root from a scene by locating the first bone
+ * and walking up to the top-level scene child.
+ */
+export declare function findModelRoot(scene: THREE.Scene): THREE.Object3D | null;
+/**
+ * Build a set of mapped bone names and a semantic key lookup
+ * from an engine's profile configuration.
+ */
+export declare function buildMappedBoneInfo(profile: {
+    boneNodes?: Record<string, string>;
+    bonePrefix?: string;
+    boneSuffix?: string;
+    suffixPattern?: string;
+}, actualBoneNames?: Iterable<string>): {
+    mappedNames: Set<string>;
+    semanticKeyMap: Map<string, string>;
+    semanticKeysMap: Map<string, string[]>;
+};
+export {};

package/dist/three/editor/morphVertexPreview.d.ts

@@ -0,0 +1,35 @@
+import * as THREE from 'three';
+export interface MorphVertexPreviewOptions {
+    threshold?: number;
+    maxPoints?: number;
+}
+export interface MorphVertexPreviewSample {
+    indices: Uint32Array;
+    intensities: Float32Array;
+}
+export interface MorphVertexPreviewRenderData {
+    positions: Float32Array;
+    colors: Float32Array;
+    pointCount: number;
+    meshCount: number;
+}
+export declare function resolveMorphPreviewMeshes(root: THREE.Object3D, morphName: string, meshNames?: string[]): THREE.Mesh[];
+export declare function buildMorphVertexPreviewSample(mesh: THREE.Mesh, morphName: string, options?: MorphVertexPreviewOptions): MorphVertexPreviewSample | null;
+export declare function buildMorphVertexPreviewRenderData(meshes: THREE.Mesh[], morphName: string, cache: Map<string, MorphVertexPreviewSample>, options?: MorphVertexPreviewOptions): MorphVertexPreviewRenderData | null;
+/** Editor overlay sampled by the existing Three render loop, without a separate frame timer. */
+export declare class MorphVertexPreview {
+    private readonly scene;
+    private readonly options;
+    private readonly cache;
+    private points;
+    private active;
+    private disposed;
+    private unbindRender;
+    constructor(scene: THREE.Scene, options?: MorphVertexPreviewOptions);
+    show(morphName: string, meshNames?: string[]): void;
+    hide(): void;
+    dispose(): void;
+    private createPoints;
+    private update;
+    private updateAttribute;
+}

package/dist/three/index.d.ts

@@ -169,3 +169,5 @@ export declare class ThreeFrameApplier {
 export declare const collectMorphMeshes: (root: Object3D) => Mesh<import("three").BufferGeometry<import("three").NormalBufferAttributes, import("three").BufferGeometryEventMap>, Material<import("three").MaterialEventMap> | Material<import("three").MaterialEventMap>[], import("three").Object3DEventMap>[];
 export * from './model';
 export * from './scene';
+export * from './editor/SkeletonOverlay';
+export * from './editor/morphVertexPreview';

package/dist/three/modelMorphLayout.d.ts

@@ -0,0 +1,13 @@
+import * as THREE from 'three';
+declare const THREE_RENDERED_MORPH_SEMANTICS: readonly ["position", "normal", "color"];
+type ThreeRenderedMorphSemantic = typeof THREE_RENDERED_MORPH_SEMANTICS[number];
+export interface CharacterMorphLayoutRepair {
+    meshName: string;
+    paddedChannels: Partial<Record<ThreeRenderedMorphSemantic, number>>;
+    removedEmptyChannels: ThreeRenderedMorphSemantic[];
+    paddedInfluences: number;
+}
+/** Repair recoverable channel holes before Three.js builds its morph texture. */
+export declare function normalizeRenderableCharacterMorphAttributes(model: THREE.Object3D): CharacterMorphLayoutRepair[];
+export declare function assertRenderableCharacterMorphAttributes(model: THREE.Object3D): void;
+export {};

package/dist/three/scene.d.ts

@@ -126,6 +126,10 @@ export type DefaultCharacterSceneOptions = {
     shadowPlane?: boolean;
     manageResize?: boolean;
 };
+/** Saved per-character appearance; renderer preference and DOM ownership stay separate. */
+export type CharacterSceneConfiguration = Pick<DefaultCharacterSceneOptions, 'type' | 'cameraFov' | 'shadows' | 'lightingPreset' | 'lighting' | 'shadowPlane'> & {
+    background?: string | number | null;
+};
 export type DefaultCharacterSceneAsyncOptions = DefaultCharacterSceneOptions & {
     /** Auto (default) tries native WebGPU initialization, then falls back to WebGL. */
     renderer?: CharacterSceneRendererPreference;
@@ -149,6 +153,7 @@ type CharacterScene<R extends CharacterSceneRenderer> = {
     sceneType: CharacterSceneTypeId;
     ownsScene: true;
     resize: () => void;
+    setSceneSettings: (settings: CharacterSceneConfiguration) => void;
     dispose: () => void;
 };
 export type DefaultCharacterScene = CharacterScene<WebGLRenderer>;

package/dist/three/sceneInkBackground.d.ts

@@ -0,0 +1,11 @@
+import * as THREE from 'three';
+export type SceneInkBackgroundPalette = readonly [
+    THREE.ColorRepresentation,
+    THREE.ColorRepresentation,
+    THREE.ColorRepresentation
+];
+export type SceneInkBackground = {
+    setPalette: (palette?: SceneInkBackgroundPalette | null) => void;
+    dispose: () => void;
+};
+export declare function createSceneInkBackground(onBackgroundChange?: (background: string) => void): SceneInkBackground;

package/dist/three/sceneInkBackgroundStyle.d.ts

@@ -0,0 +1,5 @@
+export declare const SCENE_INK_BASE_COLOR = "#29333b";
+export declare const SCENE_INK_BASE_GRADIENT = "radial-gradient(ellipse at 50% 42%, #46535c 0%, #35414a 42%, #29333b 76%, #252e35 100%)";
+export type SceneInkCssPalette = readonly [string, string, string];
+export declare function createSceneInkBackgroundCss(palette?: SceneInkCssPalette): string;
+export declare const DEFAULT_SCENE_INK_BACKGROUND: string;