@lovelace_lol/embody 0.0.11 → 0.0.13

package/dist/three/authoring.d.ts

@@ -4,7 +4,7 @@ import type { Region } from './annotations/types';
 import type * as Types from './authoringTypes';
 export * from './authoringTypes';
 export { resolveBoneNames, fuzzyNameMatch } from './annotations/adapter';
-export { DEFAULT_AXIS_TO_CHANNEL, DEFAULT_BONE_MAX_DEGREES, JOINT_CONTROL_SECTION, VISEME_KEYS, HAIR_COLOR_PRESETS, DEFAULT_HAIR_COLOR_APPEARANCE, HUMANOID_SKELETON_TEMPLATES, CC4_HUMANOID_SKELETON_TEMPLATE, } from '@lovelace_lol/embody/wasm';
+export { DEFAULT_AXIS_TO_CHANNEL, DEFAULT_BONE_MAX_DEGREES, JOINT_CONTROL_SECTION, VISEME_KEYS, HAIR_COLOR_PRESETS, DEFAULT_HAIR_COLOR_APPEARANCE, getAUDescriptors, LEGACY_BODY_CONTROL_AUS, HUMANOID_SKELETON_TEMPLATES, CC4_HUMANOID_SKELETON_TEMPLATE, } from '@lovelace_lol/embody/wasm';
 export declare const getPreset: (id: Types.PresetType) => Types.Profile;
 export declare const extendCharacterConfigWithPreset: <T extends Types.ProfileRuntimeConfig>(config: T) => T;
 export declare const extractProfileOverrides: (config: Types.ProfileRuntimeConfig) => Partial<Types.Profile>;
@@ -61,7 +61,6 @@ export declare const classifyAuAsJointControl: (profile: Types.Profile, auId: nu
     nodeKey?: string | null;
 }) => Types.Profile;
 export declare const resolveContinuumDisplayLabel: (profile: Pick<Types.Profile, "continuumPairs" | "continuumLabels" | "auInfo" | "boneNodes" | "bonePrefix" | "boneSuffix">, negativeAuId: number, positiveAuId: number) => string;
-export declare function getBodyControls(profile: Types.Profile, model?: Object3D): Types.BodyControlDescriptor[];
 export declare function extractModelData(model: Object3D, meshes?: Mesh[], animations?: AnimationClip[]): Types.ModelData;
 export declare function analyzeModel(options: {
     source: {
@@ -76,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;
@@ -93,3 +92,4 @@ export declare function extractHumanoidSkeletonTemplateFromModel(model: Object3D
     sourceAsset?: string;
     sourceSkinName?: string;
 }): Types.HumanoidSkeletonTemplate;
+export type { AUDescriptor } from '@lovelace_lol/embody/wasm';

package/dist/three/authoringTypes.d.ts

@@ -207,95 +207,6 @@ export interface HumanoidCharacterizationResolution {
     warnings: string[];
     valid: boolean;
 }
-/** Semantic body actions reuse the AU bone/morph evaluator. VRM names identify targets. */
-export interface BodyControlDefinition {
-    label: string;
-    section: string;
-    auId: number;
-    negativeAuId?: number | null;
-    bilateral: boolean;
-    roles: VRMHumanoidRole[];
-    order?: number;
-}
-export interface BodyControlDescriptor {
-    id: string;
-    label: string;
-    section: string;
-    auId: number;
-    negativeAuId: number | null;
-    auIds: number[];
-    bilateral: boolean;
-    roles: VRMHumanoidRole[];
-    order: number;
-    boneBindings: Array<BoneBinding & {
-        auId: number;
-        boneName: string;
-    }>;
-    morphBindings: MorphTargetsBySide;
-    meshNames: string[];
-    hasBones: boolean;
-    hasMorphs: boolean;
-    isMixed: boolean;
-    available: boolean;
-    diagnostics: string[];
-}
-/** Pose values are normalized authored action amounts, never world Euler angles. */
-export interface SemanticPoseChannel {
-    intensity: number;
-    /** -1 = character's left, 0 = both, +1 = character's right. */
-    balance?: number;
-    /** Morph contribution only; bone activation remains intensity. Defaults to profile. */
-    morphStrength?: number;
-}
-export interface SemanticPose {
-    version: 1;
-    controls: Array<{
-        controlId: string;
-        positive?: SemanticPoseChannel;
-        negative?: SemanticPoseChannel;
-    }>;
-}
-export interface SemanticPoseDirection {
-    auId: number;
-    label: string;
-    available: boolean;
-    availableSides?: Array<'left' | 'right' | 'center'>;
-    hasBones: boolean;
-    hasMorphs: boolean;
-    morphStrength: number;
-}
-export interface SemanticPoseControl {
-    id: string;
-    label: string;
-    section: string;
-    roles: string[];
-    bilateral: boolean;
-    boneNames: string[];
-    morphNames: string[];
-    positive: SemanticPoseDirection;
-    negative?: SemanticPoseDirection;
-}
-export interface SemanticAnimation {
-    version: 1;
-    durationSeconds: number;
-    tracks: Array<{
-        controlId: string;
-        direction: 'positive' | 'negative';
-        balance?: number;
-        morphStrength?: number;
-        keyframes: Array<{
-            time: number;
-            intensity: number;
-        }>;
-    }>;
-}
-export interface SemanticAnimationOptions extends Record<string, unknown> {
-    faceCurves?: Record<string, Array<{
-        time: number;
-        intensity: number;
-        inherit?: boolean;
-    }>>;
-}
 export interface Profile {
     name?: string;
     animalType?: string;
@@ -340,8 +251,6 @@ export interface Profile {
     disabledRegions?: string[];
     hairPhysics?: HairPhysicsProfileConfig;
     humanoidCharacterization?: HumanoidCharacterization;
-    /** Authored overrides may patch individual fields; null removes a preset control. */
-    bodyControls?: Record<string, Partial<BodyControlDefinition> | null>;
 }
 export interface ProfileRuntimeConfig extends Partial<Profile> {
     profilePresetId?: PresetType;

package/dist/three/character.d.ts

@@ -1,5 +1,6 @@
 import { AnimationClip } from 'three';
 import type { Mesh, Object3D } from 'three';
+import type { AUDescriptor } from '@lovelace_lol/embody/wasm';
 import { ThreeFrameApplier } from './index';
 import type { ThreeModelInspection } from './index';
 import type { ThreeModelReferencePose } from './reference-pose';
@@ -122,7 +123,6 @@ export declare class Embody {
     snippetToClip(name: string, curves: JsonObject, options?: CharacterPlaybackOptions): CharacterPlaybackHandle;
     buildTypedClip(name: string, channels: any[], options?: CharacterPlaybackOptions): CharacterPlaybackHandle;
     typedSnippetToClip(name: string, channels: any[], options?: CharacterPlaybackOptions): CharacterPlaybackHandle;
-    semanticAnimationToClip(name: string, animation: JsonObject, options?: CharacterPlaybackOptions): CharacterPlaybackHandle;
     playSnippet(snippet: string | {
         name: string;
         curves: JsonObject;
@@ -164,13 +164,7 @@ export declare class Embody {
     setAU(id: number, value: number, balance?: number): void;
     getAU(id: number): number;
     getAUBalance(id: number): number;
-    getBodyControls(): any[];
-    getSemanticPoseCatalog(): any[];
-    captureSemanticPose(): JsonObject;
-    validateSemanticPose(pose: JsonObject): JsonObject;
-    applySemanticPose(pose: JsonObject): void;
-    validateSemanticAnimation(animation: JsonObject, options?: JsonObject): void;
-    resetBodyControls(): void;
+    getAUDescriptors(): AUDescriptor[];
     setContinuum(negative: number, positive: number, value: number, balance?: number): void;
     getContinuum(negative: number, positive: number): number;
     transitionAU(id: number, value: number, durationMs?: number, balance?: number): CharacterTransitionHandle;

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 { DPthreeCameraController } from './annotations/DPthreeCameraController';
+import type { AnnotationCharacterConfig, DPthreeCameraControllerConfig } 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: DPthreeCameraController | 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<DPthreeCameraControllerConfig>, '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: DPthreeCameraController | 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;