@lovelace_lol/embody 0.0.15 → 0.0.16

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

@@ -1,5 +1,6 @@
 import * as THREE from 'three';
 import type { NativeAnnotationRuntime } from './runtime';
+export { readAttribute } from './morphGeometry';
 type Bounds = {
     min: number[];
     max: number[];
@@ -20,25 +21,26 @@ export interface AnnotationModelObservation {
         morphNames: string[];
     }[];
 }
-export declare function readAttribute(attribute: THREE.BufferAttribute | THREE.InterleavedBufferAttribute): Float32Array;
 /** Stable native handle table. No region matching or anchor policy lives here. */
 export declare class AnnotationModelObserver {
     readonly model: THREE.Object3D;
     readonly objects: Map<number, THREE.Object3D<THREE.Object3DEventMap>>;
     readonly meshes: THREE.Mesh[];
     private readonly ids;
+    private morphGeneration;
+    private morphObservations;
+    private readonly morphGeometry;
+    private readonly vertex;
     constructor(model: THREE.Object3D);
     id(object: THREE.Object3D): number | undefined;
+    private updateWorldMatrices;
     capture(): AnnotationModelObservation;
     observe(runtime: NativeAnnotationRuntime): void;
     transforms(runtime: NativeAnnotationRuntime): Float32Array;
-    morphAnchors(runtime: NativeAnnotationRuntime): Record<string, {
-        x: number;
-        y: number;
-        z: number;
-    }>;
+    private prepareMorphAnchors;
+    /** Transport only: Rust owns the vertex selection, weights and live anchor. */
+    observeMorphAnchors(runtime: NativeAnnotationRuntime): void;
     /** Rust selects influenced vertices; Three evaluates the current native pose. */
     observeFocus(runtime: NativeAnnotationRuntime, request: unknown): void;
 }
 export declare function observeAnnotationModel(model: THREE.Object3D): AnnotationModelObservation;
-export {};

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

@@ -0,0 +1,19 @@
+import * as THREE from 'three';
+type Attribute = THREE.BufferAttribute | THREE.InterleavedBufferAttribute;
+export declare function readAttribute(attribute: Attribute): Float32Array;
+export declare function readMorphGeometry(mesh: THREE.Mesh, names: string[]): {
+    base: Float32Array;
+    morphs: Float32Array;
+    relative: boolean;
+} | null;
+export declare function updateAnnotationWorldMatrices(model: THREE.Object3D): void;
+export declare function sampleMorphVertices(mesh: THREE.Mesh, indices: ArrayLike<number>, samples: Float32Array, vertex?: THREE.Vector3): void;
+/** Native identities/versions only. Rust decides whether this observation
+ * invalidates an attachment and which geometry/vertices are needed next. */
+export declare class MorphGeometryObservation {
+    revision: number;
+    namesJson: string;
+    private signature;
+    observe(mesh: THREE.Mesh): void;
+}
+export {};

package/dist/three/authoring.d.ts

@@ -9,52 +9,52 @@ 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>;
 export declare const mergeCharacterRegionsByName: (base?: Region[], override?: Region[]) => Region[];
-export declare const getMeshNamesForAUProfile: (profile: Types.Profile, auId: number) => string[];
+export declare const getMeshNamesForAUProfile: (profile: Partial<Types.Profile>, auId: number) => string[];
 /** Resolve routing and legacy mesh aliases once for an editor inventory. */
 export declare const resolveMorphMeshSelections: (profile: Partial<Pick<Types.Profile, "morphToMesh" | "visemeMeshCategory">>, categories: string[], availableNames: string[]) => Record<string, Types.MorphMeshSelection>;
 export declare const getHumanoidSpecification: () => Types.HumanoidSpecification;
-export declare const setAUMorphTargets: (profile: Types.Profile, auId: number, side: "left" | "right" | "center", targets: Types.MorphTargetRef[]) => Types.Profile;
-export declare const setHumanoidRoleBinding: (profile: Types.Profile, role: Types.VRMHumanoidRole, boneName: string | null) => Types.Profile;
-export declare const resolveHumanoidCharacterization: (profile: Types.Profile) => Types.HumanoidCharacterizationResolution;
-export declare const hasLeftRightMorphs: (profile: Types.Profile, auId: number) => boolean;
-export declare const isMixedAU: (profile: Types.Profile, auId: number) => boolean;
+export declare const setAUMorphTargets: (profile: Types.ProfileInput, auId: number, side: "left" | "right" | "center", targets: Types.MorphTargetRef[]) => Partial<Types.Profile> & Pick<Types.Profile, "auToMorphs">;
+export declare const setHumanoidRoleBinding: (profile: Types.ProfileInput, role: Types.VRMHumanoidRole, boneName: string | null) => Partial<Types.Profile>;
+export declare const resolveHumanoidCharacterization: (profile: Partial<Types.Profile>) => Types.HumanoidCharacterizationResolution;
+export declare const hasLeftRightMorphs: (profile: Partial<Types.Profile>, auId: number) => boolean;
+export declare const isMixedAU: (profile: Partial<Types.Profile>, auId: number) => boolean;
 export declare const resolveVisemeProfile: (profile: Partial<Types.Profile>) => Types.ResolvedVisemeProfile;
 export declare const isMaxDegreesOnlyAxisBindingUpdate: (update: Types.BoneAxisBindingUpdate) => boolean;
-export declare const findNodeKeyForBone: (boneName: string, profile: Types.Profile | null) => string | null;
+export declare const findNodeKeyForBone: (boneName: string, profile: Partial<Types.Profile> | null) => string | null;
 export declare const ensureBoneNodeKey: (profile: Types.Profile, boneName: string) => {
     nodeKey: string;
     boneNodes: Record<string, string>;
 };
-export declare const ensureBilateralBoneNodeKeys: (profile: Types.Profile, leftBoneName: string, rightBoneName: string) => Types.Profile;
+export declare const ensureBilateralBoneNodeKeys: (profile: Types.ProfileInput, leftBoneName: string, rightBoneName: string) => Partial<Types.Profile>;
 export declare const resolveBoneNameForNodeKey: (profile: Types.Profile, nodeKey: string) => string | null;
 export declare const stripConfiguredBoneAffixes: (profile: Pick<Types.Profile, "bonePrefix" | "boneSuffix"> | null | undefined, boneName: string) => string;
 export declare const inferChiralBoneNamePair: (boneNames: string[], selectedBoneName: string) => Types.ChiralBoneNamePair | null;
 export declare const formatAxisLabel: (axis: Types.BoneAxisKey) => string;
 export declare const formatAxisDirectionLabel: (axis: Types.BoneAxisKey, direction: Types.BoneAxisDirection) => string;
 export declare const getAxisFromChannel: (channel?: string) => Types.BoneAxisKey | null;
-export declare const getBoneAxisBindingState: (profile: Types.Profile, boneName: string, axis: Types.BoneAxisKey) => Types.BoneAxisBindingState | null;
+export declare const getBoneAxisBindingState: (profile: Partial<Types.Profile>, boneName: string, axis: Types.BoneAxisKey) => Types.BoneAxisBindingState | null;
 export declare const resolveBoneAxisChannel: (profile: Types.Profile, boneName: string, axis: Types.BoneAxisKey) => Types.RotationChannel;
-export declare const getBilateralAxisBindingState: (profile: Types.Profile, boneName: string, axis: Types.BoneAxisKey) => Types.BilateralAxisBindingState | null;
-export declare const getAUBoneBindingState: (profile: Types.Profile, auId: number) => Types.AUBoneBindingState;
+export declare const getBilateralAxisBindingState: (profile: Partial<Types.Profile>, boneName: string, axis: Types.BoneAxisKey) => Types.BilateralAxisBindingState | null;
+export declare const getAUBoneBindingState: (profile: Partial<Types.Profile>, auId: number) => Types.AUBoneBindingState;
 /** Resolve a panel's bone links without repeatedly serializing its full character. */
 export declare const getAUBoneBindingStates: (profile: Partial<Pick<Types.Profile, "auToBones" | "boneNodes" | "bonePrefix" | "boneSuffix" | "suffixPattern" | "compositeRotations" | "continuumPairs" | "humanoidCharacterization">>, auIds: readonly number[]) => Record<number, Types.AUBoneBindingState>;
 export declare const inferEyeControlScope: (profile: Pick<Types.Profile, "auToBones">, binding: Pick<Types.BoneAxisBindingState, "nodeKey" | "negativeAuId" | "positiveAuId">) => Types.BoneControlScope | null;
 export declare const inferEyeControlFamily: (binding: Pick<Types.BoneAxisBindingState, "nodeKey" | "axis">) => Types.BoneControlFamily | null;
-export declare const applyBoneAxisBindingUpdate: (profile: Types.Profile, boneName: string, axis: Types.BoneAxisKey, update: Types.BoneAxisBindingUpdate) => Types.Profile;
-export declare const applyBilateralAxisBindingUpdate: (profile: Types.Profile, boneName: string, axis: Types.BoneAxisKey, scope: Types.BilateralBoneAxisScope, update: Types.BoneAxisBindingUpdate) => Types.Profile;
+export declare const applyBoneAxisBindingUpdate: (profile: Types.ProfileInput, boneName: string, axis: Types.BoneAxisKey, update: Types.BoneAxisBindingUpdate) => Partial<Types.Profile>;
+export declare const applyBilateralAxisBindingUpdate: (profile: Types.ProfileInput, boneName: string, axis: Types.BoneAxisKey, scope: Types.BilateralBoneAxisScope, update: Types.BoneAxisBindingUpdate) => Partial<Types.Profile>;
 export declare const applyAUBoneBindingUpdate: (profile: Types.Profile, auId: number, update: {
     boneName: string | null;
     axis: Types.BoneAxisKey;
     direction: Types.BoneAxisDirection;
     maxDegrees: number | null;
 }) => Types.Profile;
-export declare const createBoneAxisAu: (profile: Types.Profile, boneName: string, axis: Types.BoneAxisKey, direction: Types.BoneAxisDirection, options?: {
+export declare const createBoneAxisAu: (profile: Types.ProfileInput, boneName: string, axis: Types.BoneAxisKey, direction: Types.BoneAxisDirection, options?: {
     name?: string;
 }) => Types.CreatedBoneAxisAu;
-export declare const createBilateralBoneAxisAu: (profile: Types.Profile, boneName: string, axis: Types.BoneAxisKey, scope: Types.BilateralBoneAxisScope, direction: Types.BoneAxisDirection, options?: {
+export declare const createBilateralBoneAxisAu: (profile: Types.ProfileInput, boneName: string, axis: Types.BoneAxisKey, scope: Types.BilateralBoneAxisScope, direction: Types.BoneAxisDirection, options?: {
     name?: string;
 }) => Types.CreatedBoneAxisAu;
-export declare const buildBoneAuOptions: (profile: Types.Profile) => Array<{
+export declare const buildBoneAuOptions: (profile: Partial<Types.Profile>) => Array<{
     value: string;
     label: string;
     detail?: string;
@@ -64,7 +64,7 @@ export declare const classifyAuAsJointControl: (profile: Types.Profile, auId: nu
     boneName?: string | null;
     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 const resolveContinuumDisplayLabel: (profile: Partial<Pick<Types.Profile, "continuumPairs" | "continuumLabels" | "auInfo" | "boneNodes" | "bonePrefix" | "boneSuffix">>, negativeAuId: number, positiveAuId: number) => string;
 export declare function extractModelData(model: Object3D, meshes?: Mesh[], animations?: AnimationClip[]): Types.ModelData;
 export declare function analyzeModel(options: {
     source: {
@@ -80,7 +80,7 @@ export declare function analyzeModel(options: {
     suggestCorrections?: boolean;
 }): Promise<Types.ModelAnalysisReport>;
 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 validateHumanoidCharacterization(model: Object3D, profile: Partial<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;
 export declare function getHumanoidSkeletonTemplateBoneNames(template?: Types.HumanoidSkeletonTemplate): string[];

package/dist/three/authoringTypes.d.ts

@@ -25,7 +25,7 @@ export interface MorphMeshSelection {
     resolvedNames: string[];
     unresolvedNames: string[];
 }
-export type MeshCategory = 'body' | 'eye' | 'eyeOcclusion' | 'tearLine' | 'teeth' | 'tongue' | 'hair' | 'eyebrow' | 'cornea' | 'eyelash';
+export type MeshCategory = 'body' | 'eye' | 'eyeOcclusion' | 'tearLine' | 'teeth' | 'tongue' | 'hair' | 'eyebrow' | 'cornea' | 'eyelash' | 'other';
 export type BlendingMode = 'Normal' | 'Additive' | 'Subtractive' | 'Multiply' | 'None';
 export interface MorphTargetsBySide {
     left: MorphTargetRef[];
@@ -123,6 +123,8 @@ export interface MeshMaterialSettings {
     depthTest?: boolean;
     blending?: BlendingMode;
 }
+/** Current values read from a native mesh and its first material. */
+export type ThreeResolvedMaterialConfig = Required<MeshMaterialSettings>;
 export interface MeshInfo {
     name?: string;
     visible?: boolean;
@@ -259,6 +261,8 @@ export interface Profile {
     hairPhysics?: HairPhysicsProfileConfig;
     humanoidCharacterization?: HumanoidCharacterization;
 }
+/** Intake accepts app metadata while keeping the profile's known keys explicit. */
+export type ProfileInput = Partial<Profile> | (Partial<Profile> & Record<string, unknown>);
 export interface ProfileRuntimeConfig extends Partial<Profile> {
     profilePresetId?: PresetType;
     presetId?: PresetType;
@@ -297,6 +301,22 @@ export type CharacterConfig = CharacterProfile & {
     modelPath: string;
     regions: Region[];
 };
+export type AnimationSource = string;
+export type BakedClipChannel = 'face' | 'body' | 'scene' | 'custom';
+/** Rust's clip catalog describes which native channels can be played. */
+export interface BakedClipChannelInfo {
+    channel: BakedClipChannel;
+    trackCount: number;
+    playable: boolean;
+    blendMode?: 'replace' | 'additive';
+}
+export interface AnimationClipInfo {
+    name: string;
+    duration: number;
+    trackCount: number;
+    source: AnimationSource;
+    channels: BakedClipChannelInfo[];
+}
 export interface HairColorAppearance {
     name: string;
     baseColor: string;
@@ -310,9 +330,23 @@ export interface HairAppearanceState {
     outlineColor: string;
     outlineOpacity: number;
 }
-export interface HairPhysicsRuntimeConfig {
+export interface HairPhysicsRuntimeConfig extends Omit<HairPhysicsProfileConfig, 'direction' | 'morphTargets'> {
     enabled: boolean;
-    [key: string]: any;
+    direction?: {
+        yawSign?: number;
+        pitchSign?: number;
+    } | null;
+    /** Runtime normalization accepts authored records and returns names/weights. */
+    morphTargets?: {
+        swayLeft?: string | HairMorphTargetMapping | null;
+        swayRight?: string | HairMorphTargetMapping | null;
+        swayFront?: string | HairMorphTargetMapping | null;
+        fluffRight?: string | HairMorphTargetMapping | null;
+        fluffBottom?: string | HairMorphTargetMapping | null;
+        headUp?: Record<string, number | HairMorphTargetValueMapping | null> | null;
+        headDown?: Record<string, number | HairMorphTargetValueMapping | null> | null;
+    } | null;
+    [extension: string]: unknown;
 }
 export type HairPhysicsRuntimeConfigUpdate = Partial<HairPhysicsRuntimeConfig>;
 export interface TransitionHandle {
@@ -392,7 +426,7 @@ export interface ChiralBoneNamePair {
 }
 export interface CreatedBoneAxisAu {
     auId: number;
-    profile: Profile;
+    profile: Partial<Profile>;
 }
 export interface BoneInfo {
     name: string;

package/dist/three/character.d.ts

@@ -4,17 +4,31 @@ import type { AUDescriptor } from '@lovelace_lol/embody/wasm';
 import { ThreeFrameApplier } from './index';
 import type { ThreeModelInspection } from './index';
 import type { ThreeModelReferencePose } from './reference-pose';
+import type { VrmAnimationFile, VrmAnimationInfo, VrmAnimationUnits } from './vrm-animation';
 import type { ThreeNativePlaybackEvent } from './nativePlayback';
+import type { AnimationClipInfo, HairAppearanceState, HairColorAppearance, HairPhysicsRuntimeConfig, HairPhysicsRuntimeConfigUpdate, MeshInfo, Profile, ProfileInput, ThreeResolvedMaterialConfig } from './authoringTypes';
 type JsonObject = Record<string, any>;
 export type RustEmbodyHostConfig = {
     profileMode?: 'preset' | 'profile';
     presetId?: string;
     presetType?: string;
-    profile?: JsonObject;
+    profile?: ProfileInput;
     meshes?: Mesh[];
     referencePose?: ThreeModelReferencePose;
 };
 export type CharacterPlaybackOptions = JsonObject;
+/** Semantic AU values keyed by numeric AU id. */
+export type CharacterAUState = {
+    live: Record<string, number>;
+    animated: Record<string, number>;
+    total: Record<string, number>;
+    unreadable: string[];
+};
+export type CharacterAUGoalMeasurement = {
+    distance: number;
+    reversal: boolean;
+    current: Record<string, number>;
+};
 export type CharacterPlaybackEvent = ThreeNativePlaybackEvent & {
     actionId: string;
     clipName: string;
@@ -69,10 +83,12 @@ export declare class Embody {
     private readonly profileMode;
     private readonly preset;
     private readonly sources;
+    private readonly vrmAnimations;
     private readonly playbacks;
     private readonly current;
     private playDepth;
     private readonly pendingEvents;
+    private readonly pendingReleases;
     private bindingGeneration;
     private disposed;
     private rendering;
@@ -80,6 +96,7 @@ export declare class Embody {
     private nextLiveTarget;
     private readonly liveTargets;
     private readonly hairObjects;
+    private hairHeadObservation?;
     private hairConfig;
     private hairAppearance;
     constructor(config?: RustEmbodyHostConfig);
@@ -98,12 +115,13 @@ export declare class Embody {
     private bind;
     bindModel(meshes?: Mesh[]): void;
     extendReferencePose(): ThreeModelReferencePose;
-    setProfile(value: JsonObject): void;
-    getProfile(): JsonObject;
+    setProfile(value: ProfileInput): void;
+    getProfile(): Partial<Profile>;
     getProfileMode(): 'preset' | 'profile';
     getPresetId(): string | null;
     supportsPreset(value?: string): boolean;
     private onPlaybackEvent;
+    private flushPendingPlaybackEvents;
     private compile;
     private restValues;
     private materialize;
@@ -113,10 +131,17 @@ export declare class Embody {
     private handle;
     private forget;
     private updatePlayback;
+    supportsVrmAnimation(): boolean;
+    convertMixamoFbxToVrmAnimations(bytes: ArrayBuffer, options: VrmAnimationUnits): VrmAnimationFile[];
+    getVrmAnimationInfo(bytes: Uint8Array): VrmAnimationInfo;
+    /** Registers a source; Animation owns the later playback request. */
+    registerVrmAnimation(name: string, bytes: Uint8Array, options: VrmAnimationUnits): void;
+    /** Stale editor cleanup must not remove a later same-name native source. */
+    releaseVrmAnimation(name: string): void;
     registerAnimationClips(clips: AnimationClip[]): void;
     loadAnimationClips(clips: AnimationClip[]): void;
     removeAnimationClip(name: string): boolean;
-    getAnimationClips(): any[];
+    getAnimationClips(): AnimationClipInfo[];
     playAnimation(name: string, options?: CharacterPlaybackOptions): CharacterPlaybackHandle;
     private build;
     buildClip(name: string, curves: JsonObject, options?: CharacterPlaybackOptions): CharacterPlaybackHandle;
@@ -136,6 +161,7 @@ export declare class Embody {
     cleanupSnippet(name: string): void;
     crossfadeTo(name: string, seconds: number, options?: CharacterPlaybackOptions): CharacterPlaybackHandle;
     stopAnimation(name: string): void;
+    /** Stop every caller playback. Live setter targets and hair actions keep running. */
     stopAllAnimations(): void;
     pauseAnimation(name: string): void;
     resumeAnimation(name: string): void;
@@ -167,6 +193,24 @@ export declare class Embody {
     getAUDescriptors(): AUDescriptor[];
     setContinuum(negative: number, positive: number, value: number, balance?: number): void;
     getContinuum(negative: number, positive: number): number;
+    /**
+     * One clip slot's own semantic AU contribution right now (`{auId: value}`),
+     * evaluated in Rust at the native action's time and effective weight.
+     * Null when the slot is not playing or was not an AU-curve clip.
+     */
+    readAUContribution(name: string): Record<string, number> | null;
+    /**
+     * On-demand AU state: live control values, active AU-curve clip
+     * contributions and their sum. Baked/native and typed clips cannot be
+     * inverted to AU values and are listed as `unreadable`, never estimated.
+     */
+    readAUState(): CharacterAUState;
+    /**
+     * Distance from a slot's current contribution to AU destinations, measured
+     * along profile continuum pairs, and whether it reverses unfinished travel.
+     * A slot that is not playing is at zero. Callers choose any timing policy.
+     */
+    measureAUGoal(name: string, destinations: Record<string, number>): CharacterAUGoalMeasurement;
     transitionAU(id: number, value: number, durationMs?: number, balance?: number): CharacterTransitionHandle;
     setViseme(index: number, value: number, jawScale?: number): void;
     getViseme(index: number): number;
@@ -189,12 +233,12 @@ export declare class Embody {
     addMorphTarget(target: Parameters<ThreeFrameApplier['addMorphTarget']>[1], options?: Parameters<ThreeFrameApplier['addMorphTarget']>[2]): number;
     addMorphTargets(targets: Parameters<ThreeFrameApplier['addMorphTargets']>[1], options?: Parameters<ThreeFrameApplier['addMorphTargets']>[2]): Record<string, number>;
     private meshCategory;
-    getMeshList(): JsonObject[];
+    getMeshList(): MeshInfo[];
     getBones(): ThreeModelInspection['bones'];
     private meshProfile;
     setMeshVisible(name: string, visible: boolean): void;
     highlightMesh(name: string | null, color?: number, value?: number): void;
-    getMeshMaterialConfig(name: string): Record<string, unknown> | null;
+    getMeshMaterialConfig(name: string): ThreeResolvedMaterialConfig | null;
     setMeshMaterialConfig(name: string, value: Parameters<ThreeFrameApplier['setMeshMaterialConfig']>[2]): void;
     registerHairObjects(objects: Object3D[]): {
         name: string;
@@ -203,10 +247,10 @@ export declare class Embody {
     }[];
     getRegisteredHairObjects(): Object3D[];
     getHairMorphTargets(name?: string): string[];
-    getHairAppearance(): JsonObject;
+    getHairAppearance(): HairAppearanceState;
     private setHairAppearance;
-    setHairColor(value: string | JsonObject): void;
-    setEyebrowColor(value: string | JsonObject): void;
+    setHairColor(value: string | Partial<HairColorAppearance>): void;
+    setEyebrowColor(value: string | Partial<HairColorAppearance>): void;
     setHairBaseColor(value: string): void;
     setEyebrowBaseColor(value: string): void;
     setHairGlow(color: string, value: number): void;
@@ -216,15 +260,15 @@ export declare class Embody {
         color?: string;
         opacity?: number;
     }): void;
-    private restartHair;
+    private hairClipOptions;
+    private bindHairHead;
+    private sampleHairResponse;
     setHairPhysicsEnabled(value: boolean): void;
     isHairPhysicsEnabled(): boolean;
-    setHairPhysicsConfig(value: JsonObject): void;
-    getHairPhysicsConfig(): JsonObject;
+    setHairPhysicsConfig(value: HairPhysicsRuntimeConfigUpdate): void;
+    getHairPhysicsConfig(): Partial<HairPhysicsRuntimeConfig>;
     validateHairMorphTargets(): string[];
     applyHairStateToObject(name: string, state: JsonObject): void;
-    private authoredHeadMotion;
-    private setHairGravity;
     playHairImpulse(horizontal: number, vertical: number): CharacterPlaybackHandle | undefined;
     start(): void;
     stop(): void;

package/dist/three/index.d.ts

@@ -1,10 +1,13 @@
+import type { MeshHighlightFrame } from '../wasm/highlighting';
 import { AnimationClip } from 'three';
 export * from './annotations/index';
+export * from './vrm-animation';
 export * from './authoring';
 export * from './character';
 export * from './characterHost';
 export { renderScenePlayback, createScenePlaybackFrame } from './playbackRendering';
 import type { ThreeModelReferencePose } from './reference-pose';
+import type { MeshMaterialSettings, ThreeResolvedMaterialConfig } from './authoringTypes';
 export { captureModelReferencePose, bindModelReferencePose, extendModelReferencePose } from './reference-pose';
 export type { ThreeModelReferencePose, ThreeReferencePoseNode } from './reference-pose';
 export { ThreeNativePlaybackConnector } from './nativePlayback';
@@ -133,20 +136,13 @@ export declare function serializeAnimationClips(model: Object3D, clips: readonly
     }[];
     tracks: ClipIRTrack[];
 }[];
-type MaterialConfig = {
-    renderOrder?: number;
-    transparent?: boolean;
-    opacity?: number;
-    depthWrite?: boolean;
-    depthTest?: boolean;
-    blending?: keyof typeof THREE_BLENDING_MODES;
-};
+type MaterialConfig = MeshMaterialSettings;
 export declare class ThreeFrameApplier {
     private meshes;
     private morphs;
     private bones;
     private objects;
-    private originalEmissive;
+    private highlighted;
     setBindings(inspection: ThreeModelInspection): void;
     applyPackedMorphFrameDelta(values: ArrayLike<number>, stride?: number): void;
     applyPackedBoneFrameDelta(values: ArrayLike<number>, stride?: number): void;
@@ -155,10 +151,14 @@ export declare class ThreeFrameApplier {
         visible?: boolean;
         material?: MaterialConfig;
     }>): void;
-    getMeshMaterialConfig(root: Object3D, name: string): null;
+    getMeshMaterialConfig(root: Object3D, name: string): ThreeResolvedMaterialConfig | null;
     setMeshMaterialConfig(root: Object3D, name: string, config: MaterialConfig): void;
+    private applyHighlightedMeshMaterial;
     setMeshVisible(root: Object3D, name: string, visible: boolean): void;
-    highlightMesh(root: Object3D, name: string | null, color?: number, intensity?: number): void;
+    /** Apply a complete Rust snapshot. Only native resources and ID bindings live here. */
+    applyMeshHighlightFrame(frame: MeshHighlightFrame): void;
+    clearMeshHighlights(): void;
+    private clearMeshHighlight;
     applyHairAppearance(meshes: readonly Mesh[], appearance: any): void;
     addMorphTarget(root: Object3D, target: MorphTargetInput, options?: AddMorphTargetOptions): number;
     addMorphTargets(root: Object3D, targets: readonly MorphTargetInput[], options?: AddMorphTargetOptions): Record<string, number>;
@@ -169,5 +169,6 @@ 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 './scenery';
 export * from './editor/SkeletonOverlay';
 export * from './editor/morphVertexPreview';

package/dist/three/model.d.ts

@@ -6,7 +6,9 @@ export type CharacterModelLoadResult = {
     animations: AnimationClip[];
     gltf: GLTF | null;
 };
+export type CharacterModelFormat = 'gltf' | 'fbx';
 export type CharacterModelLoadOptions = {
+    format?: CharacterModelFormat;
     onProgress?: (progress: number) => void;
     castShadows?: boolean;
     dracoDecoderPath?: string;

package/dist/three/nativePlayback.d.ts

@@ -57,6 +57,8 @@ export type ThreeNativePlaybackBinding = {
     inspection: ThreeModelInspection;
     /** Optional existing native mixer. Otherwise the connector owns one. */
     mixer?: AnimationMixer;
+    /** Apply renderer effects using the existing scene clock; never starts a loop. */
+    onFrame?: (deltaSeconds: number) => void;
 };
 /**
  * Execute validated Rust commands on the native mixer. There is no
@@ -83,10 +85,13 @@ export declare class ThreeNativePlaybackConnector {
     private disposed;
     private readonly onError?;
     private readonly onRelease?;
+    private readonly afterSample?;
     constructor(session: NativePlaybackSession, binding: ThreeNativePlaybackBinding & {
         onError?: (error: Error) => void;
         onRelease?: (handle: string) => void;
+        afterSample?: (deltaSeconds: number) => void;
     });
+    private readonly afterFrame;
     /** Prepare bindings first; old actions are released before the new binding is exposed. */
     rebind(modelKey: string, profileKey: string, binding?: ThreeNativePlaybackBinding): void;
     play(clip: ClipIR, options?: ThreeNativePlaybackOptions): string;
@@ -105,6 +110,7 @@ export declare class ThreeNativePlaybackConnector {
     replaceClip(handle: string, clip: AnimationClip): void;
     /** Native state for the owning adapter; never exposed through Polymer. */
     getAction(handle: string): AnimationAction | undefined;
+    private readonly sampleResponse;
     /** Deliver native completion after the borrowed mixer has finished sampling. */
     flushEvents(): void;
     subscribe(listener: (event: ThreeNativePlaybackEvent) => void): () => void;

package/dist/three/playbackRendering.d.ts

@@ -1,7 +1,7 @@
 import { Timer } from 'three';
 import type { AnimationMixer, Object3D } from 'three';
 /** Register native playback with the existing scene renderer; never starts a loop. */
-export declare function bindPlaybackRendering(model: Object3D, mixer: AnimationMixer, afterFrame: () => void): {
+export declare function bindPlaybackRendering(model: Object3D, mixer: AnimationMixer, afterFrame: (deltaSeconds: number) => void, afterSample?: (deltaSeconds: number) => void): {
     setEnabled(enabled: boolean): void;
     dispose(): void;
 };

package/dist/three/scene.d.ts

@@ -186,6 +186,8 @@ export interface CharacterSceneRenderingController {
     subscribe(listener: (snapshot: CharacterSceneRenderingSnapshot) => void): () => void;
     /** Borrow for capture/readback; release in finally. Unavailable during switching/loss. */
     acquireRenderer(): CharacterSceneRendererLease;
+    /** Wait for queued scene work, then atomically borrow the active renderer. Release in finally. */
+    acquireRendererAsync(): Promise<CharacterSceneRendererLease>;
     /** Drain borrowed work, then synchronously detach/free caller-owned resources, even after loss/disposal. */
     releaseSceneResources(release: () => void): Promise<void>;
 }

package/dist/three/sceneBackground.d.ts

@@ -0,0 +1,11 @@
+import { type Scene } from 'three';
+/** Character settings update the inherited background even while scenery covers it. */
+export declare function setSceneBaseBackground(scene: Scene, value: Scene['background']): void;
+/** One scenery owner per scene prevents competing capture-and-restore cleanups. */
+export declare function acquireSceneBackground(scene: Scene, onSceneDispose: () => void): {
+    set(value: Scene["background"], intensity: number, rotationDegrees: number): void;
+    clear(): void;
+    dispose(): void;
+};
+/** Called by the scene's existing lifetime; the renderer owns its async drain. */
+export declare function disposeSceneBackground(scene: Scene): void;

package/dist/three/scenery.d.ts

@@ -0,0 +1,46 @@
+import type { Scene } from 'three';
+import type { CharacterSceneRenderingController } from './scene';
+/** World coordinates in the scene's native units (Y up for default character scenes). */
+export type SceneSceneryPosition = {
+    x: number;
+    y: number;
+    z: number;
+};
+export type SceneSceneryInstance = {
+    instanceId: string;
+    assetId: string;
+    position: SceneSceneryPosition;
+};
+export type SceneScenerySkybox = {
+    kind: 'skybox' | 'backdrop' | 'color';
+    assetId: string | null;
+    /** Six-digit #rrggbb, also used by the generated sky when assetId is null. */
+    color: string;
+    intensity: number;
+    /** Y-axis degrees. Applies to equirectangular skyboxes. */
+    rotation: number;
+};
+export type SceneSceneryLayout = {
+    skybox: SceneScenerySkybox | null;
+    instances: readonly SceneSceneryInstance[];
+};
+export type SceneSceneryAsset = {
+    bytes: ArrayBuffer;
+    contentType: string;
+};
+export type SceneSceneryRendererOptions = {
+    scene: Scene;
+    /** The scene's existing controller. Omit only for an externally managed scene. */
+    rendering?: CharacterSceneRenderingController | null;
+    /** Storage authorization, caching and asset identities remain with the caller. */
+    loadAsset(assetId: string, signal: AbortSignal): Promise<SceneSceneryAsset>;
+    onError?: (message: string) => void;
+};
+export type SceneSceneryRenderer = {
+    /** Validates and copies the entire layout before changing the current selection. */
+    update(layout: SceneSceneryLayout | null): void;
+    /** Cancels loads, drains borrowed rendering work, and releases only scenery. */
+    dispose(): Promise<void>;
+};
+/** Native scene resources only: no storage, character selection, mixer or render loop. */
+export declare function createSceneSceneryRenderer(options: SceneSceneryRendererOptions): SceneSceneryRenderer;