@lovelace_lol/embody 0.0.7 → 0.0.8

package/dist/three/gaze.d.ts

@@ -0,0 +1,122 @@
+import type { Object3D } from 'three';
+import type { ThreeModelReferencePose } from './reference-pose';
+type Point = {
+    x: number;
+    y: number;
+    z: number;
+};
+type Rotation = Point & {
+    w: number;
+};
+type Target = {
+    x: number;
+    y: number;
+    z?: number;
+};
+type Flags = {
+    eyesEnabled?: boolean;
+    headEnabled?: boolean;
+};
+export type ThreeGazeFocusOptions = {
+    /** Reuse the import reference when constructing the constraint during playback. */
+    referencePose?: ThreeModelReferencePose;
+};
+export type ThreeGazeFocusRequest = Flags & {
+    worldTarget: Point;
+    /** Aggregate FACS bearing normalized against full head + eye capacities. */
+    target: Target;
+    headTarget?: Target;
+    eyeIntensity?: number;
+    headIntensity?: number;
+};
+export type ThreeGazeFocusControls = {
+    eyeYaw?: number;
+    eyePitch?: number;
+    headYaw?: number;
+    headPitch?: number;
+    headRoll?: number;
+    /** Animation-sampled contributions in [0, 1], overriding request values. */
+    eyeIntensity?: number;
+    headIntensity?: number;
+};
+export type ThreeGazeFocusDiagnostic = {
+    target: Point;
+    eyes: Array<{
+        name: string;
+        origin: Point;
+        direction: Point;
+        errorDegrees: number;
+        limited: boolean;
+    }>;
+    headLimited: boolean;
+    missingHead: boolean;
+    missingEyes: boolean;
+};
+/**
+ * A renderer constraint, driven by Animation's existing motor controls. It owns
+ * no clock, camera, target-selection policy, or event loop. Call restore before
+ * evaluating the mixer (and before changing bindings), then apply afterwards.
+ * Keeping the evaluated base pose separate prevents corrections feeding back
+ * through Three's unchanged-property optimization on paused/constant clips.
+ *
+ * Optional profile.gazeCalibration.{head,leftEye,rightEye}.opticalAxis supplies
+ * a bone-local optical direction. Otherwise signed yaw/pitch bindings determine
+ * it: CC4's eye rz/negative-rx axes yield -Y; head ry/negative-rx yield +Z.
+ */
+export declare class ThreeGazeFocus {
+    private model;
+    private profile;
+    private head?;
+    private eyes;
+    private saved;
+    private references;
+    private limits;
+    constructor(model: Object3D, profile: any, options?: ThreeGazeFocusOptions);
+    private name;
+    private binding;
+    private capacity;
+    private joint;
+    restore(): void;
+    private controlLimits;
+    private angles;
+    private ratio;
+    private degrees;
+    private direction;
+    private ray;
+    /** Seed motor clips from the rendered bearing when enabling pose constraints. */
+    readControlState(options?: Flags & {
+        worldTarget?: Point;
+        headIntensity?: number;
+        eyeIntensity?: number;
+        headBaseQuaternion?: Rotation;
+        eyeBaseQuaternions?: Record<string, Rotation>;
+    }): {
+        target: {
+            x: number;
+            y: number;
+            z: number;
+        } | undefined;
+        eyeTarget: {
+            x: number;
+            y: number;
+            z: number;
+        };
+        headTarget: {
+            x: number;
+            y: number;
+            z: number;
+        };
+        headRoll: number;
+        headSeedLimited: boolean;
+        eyeSeedLimited: boolean;
+    };
+    private origin;
+    private rotation;
+    private referenceParent;
+    private jointPose;
+    private solveJoint;
+    private contributedPose;
+    private solve;
+    apply(request: ThreeGazeFocusRequest, controls: ThreeGazeFocusControls): ThreeGazeFocusDiagnostic;
+}
+export {};

package/dist/three/index.d.ts

@@ -0,0 +1,147 @@
+import { AnimationClip } from 'three';
+export * from './annotations/index';
+import type { ThreeModelReferencePose } from './reference-pose';
+export { captureModelReferencePose, bindModelReferencePose, extendModelReferencePose } from './reference-pose';
+export type { ThreeModelReferencePose, ThreeReferencePoseNode } from './reference-pose';
+import type { Material, Mesh, Object3D } from 'three';
+export { ThreeGazeFocus } from './gaze';
+export type { ThreeGazeFocusOptions, ThreeGazeFocusRequest, ThreeGazeFocusControls, ThreeGazeFocusDiagnostic } from './gaze';
+export declare const THREE_BLENDING_MODES: {
+    readonly Normal: 1;
+    readonly Additive: 2;
+    readonly Subtractive: 3;
+    readonly Multiply: 4;
+    readonly None: 0;
+};
+type BoneEntry = {
+    obj: Object3D;
+    basePos: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    baseQuat: ReturnType<Object3D['quaternion']['clone']>;
+    baseEuler: {
+        x: number;
+        y: number;
+        z: number;
+        order: string;
+    };
+};
+type MorphTargetInput = {
+    meshName: string;
+    name: string;
+    relative?: boolean;
+    position: ArrayLike<number>;
+    normal?: ArrayLike<number>;
+    tangent?: ArrayLike<number>;
+    color?: ArrayLike<number>;
+};
+type AddMorphTargetOptions = {
+    forceGeometryReplacement?: boolean;
+    replace?: boolean;
+    resetInfluence?: boolean;
+};
+export type ThreeModelInspection = {
+    descriptor: Record<string, unknown>;
+    meshByName: Map<string, Mesh>;
+    allMeshes: Mesh[];
+    morphMeshes: Mesh[];
+    bones: Record<string, BoneEntry>;
+    meshBindings: Map<number, Mesh>;
+    morphBindings: Map<number, {
+        mesh: Mesh;
+        index: number;
+    }>;
+    boneBindings: Map<number, Object3D>;
+    objectBindings: Map<number, Object3D>;
+};
+export declare class ThreeModelInspector {
+    inspectModel(model: Object3D, options?: {
+        meshes?: Mesh[];
+        profile?: any;
+        /** Explicit reference captured before playback; omitted keeps legacy current-pose inspection. */
+        referencePose?: ThreeModelReferencePose;
+    }): ThreeModelInspection;
+}
+export type ClipIRTrack = {
+    id?: number;
+    channelId?: number;
+    target: {
+        kind?: string;
+        meshId?: number;
+        morphTargetId?: number;
+        boneId?: number;
+        objectId?: number;
+        property?: string;
+    };
+    valueType: string;
+    times: number[];
+    values: number[];
+    interpolation?: string;
+    /** Replace the first sample with the bound property's current value. */
+    inheritStart?: boolean;
+    sourceName?: string;
+};
+export type ClipIR = {
+    name: string;
+    durationSeconds?: number;
+    tracks: ClipIRTrack[];
+};
+/**
+ * Convert host-neutral ClipIR (concrete morph/bone tracks) into a Three.js
+ * AnimationClip. The host AnimationMixer owns playback and lerping.
+ *
+ * Inherited starts are captured from the current scene during this call. Cache
+ * the ClipIR and call this again immediately before each play/replay, including
+ * utterance replacement. Reusing a returned AnimationClip retains its old start.
+ * The source ClipIR is never modified. A delayed inherited first key holds the
+ * captured pose until that timestamp, matching ordinary Three track sampling.
+ */
+export declare function createAnimationClipFromClipIR(clip: ClipIR, inspection: ThreeModelInspection): AnimationClip;
+export declare function serializeAnimationClips(model: Object3D, clips: readonly AnimationClip[], inspection: ThreeModelInspection): {
+    name: string;
+    durationSeconds: number;
+    channels: {
+        id: number;
+        kind: string;
+        name: string;
+    }[];
+    tracks: Record<string, unknown>[];
+}[];
+type MaterialConfig = {
+    renderOrder?: number;
+    transparent?: boolean;
+    opacity?: number;
+    depthWrite?: boolean;
+    depthTest?: boolean;
+    blending?: keyof typeof THREE_BLENDING_MODES;
+};
+export declare class ThreeFrameApplier {
+    private meshes;
+    private morphs;
+    private bones;
+    private objects;
+    private originalEmissive;
+    setBindings(inspection: ThreeModelInspection): void;
+    applyPackedMorphFrameDelta(values: ArrayLike<number>, stride?: number): void;
+    applyPackedBoneFrameDelta(values: ArrayLike<number>, stride?: number): void;
+    applySceneFrame(frame: string | Record<string, any>): void;
+    applyMeshMaterialConfigs(root: Object3D, configs: Record<string, {
+        visible?: boolean;
+        material?: MaterialConfig;
+    }>): void;
+    getMeshMaterialConfig(root: Object3D, name: string): null;
+    setMeshMaterialConfig(root: Object3D, name: string, config: MaterialConfig): void;
+    setMeshVisible(root: Object3D, name: string, visible: boolean): void;
+    highlightMesh(root: Object3D, name: string | null, color?: number, intensity?: number): void;
+    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>;
+    private applyMorphTargetToStage;
+    private applyMaterial;
+    private visitMesh;
+}
+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';

package/dist/three/model.d.ts

@@ -0,0 +1,31 @@
+import type { AnimationClip, Mesh, Object3D, Scene } from 'three';
+import type { GLTF } from 'three/examples/jsm/loaders/GLTFLoader.js';
+export type CharacterModelLoadResult = {
+    model: Object3D;
+    meshes: Mesh[];
+    animations: AnimationClip[];
+    gltf: GLTF | null;
+};
+export type CharacterModelLoadOptions = {
+    onProgress?: (progress: number) => void;
+    castShadows?: boolean;
+    dracoDecoderPath?: string;
+};
+export type CharacterModelTransform = {
+    modelOffset?: {
+        x?: number;
+        y?: number;
+        z?: number;
+    };
+    modelRotation?: {
+        x?: number;
+        y?: number;
+        z?: number;
+    };
+    modelScale?: number;
+    modelGroundClearance?: number;
+};
+export declare function applyCharacterModelTransform(model: Object3D, value?: CharacterModelTransform): void;
+export declare function disposeCharacterModel(scene: Scene | null, model: Object3D): void;
+export declare function loadCharacterModel(url: string, options?: CharacterModelLoadOptions): Promise<CharacterModelLoadResult>;
+export declare function parseCharacterModel(data: ArrayBuffer, resourcePath?: string, options?: CharacterModelLoadOptions): Promise<CharacterModelLoadResult>;

package/dist/three/modelSkinning.d.ts

@@ -0,0 +1,3 @@
+import type { Object3D } from 'three';
+/** Keep joint indices compatible with both native WebGPU and WebGL skinning. */
+export declare function prepareModelSkinning(model: Object3D): () => void;

package/dist/three/reference-pose.d.ts

@@ -0,0 +1,73 @@
+import type { Object3D } from 'three';
+type ReferenceVector3 = Readonly<{
+    x: number;
+    y: number;
+    z: number;
+}>;
+type ReferenceQuaternion = Readonly<{
+    x: number;
+    y: number;
+    z: number;
+    w: number;
+}>;
+export type ThreeReferencePoseNode = Readonly<{
+    /** Child-index path relative to the captured model. The model itself has path ''. */
+    path: string;
+    parentPath: string | null;
+    name: string;
+    type: string;
+    isBone: boolean;
+    rotationOrder: Object3D['rotation']['order'];
+    /** Authored Euler values for automatic TRS, including rotations beyond one turn. */
+    rotationEuler?: ReferenceVector3;
+    childCount: number;
+    /** For manual matrices, this is a decomposition; matrices remain authoritative for shear. */
+    transform: Readonly<{
+        position: ReferenceVector3;
+        rotation: ReferenceQuaternion;
+        scale: ReferenceVector3;
+    }>;
+    /** Column-major local and world matrices, including shear and non-bone ancestors. */
+    localMatrix: readonly number[];
+    worldMatrix: readonly number[];
+    worldPosition: ReferenceVector3;
+    /** Optional morph baseline captured independently from later live influences. */
+    morphInfluences?: readonly number[];
+}>;
+export type ThreeModelReferencePose = Readonly<{
+    version: 1;
+    /** Captured transform above the model root; identity for an unparented model. */
+    parentWorldMatrix: readonly number[];
+    nodes: readonly ThreeReferencePoseNode[];
+}>;
+/**
+ * Explicitly capture the authored reference pose before starting animation.
+ * This does not infer a skin bind pose or animation frame zero: it snapshots the
+ * transforms supplied by the caller, without updating or otherwise mutating the scene.
+ * World matrices are calculated from the full ancestor chain's local transforms,
+ * not potentially stale matrixWorld values. All returned data is deeply frozen and
+ * JSON-serializable; no object, UUID, or live transform references are retained.
+ * Existing morph influences are copied as an optional baseline. Non-finite data
+ * or manual matrices with a zero-length basis axis/non-finite TRS decomposition throw.
+ */
+export declare function captureModelReferencePose(model: Object3D): ThreeModelReferencePose;
+/**
+ * Explicitly extend a reference after appending children, such as a generated
+ * skeleton. Existing structural paths, names, kinds and child order must match;
+ * removing or inserting before an existing child is incompatible. Existing
+ * captured data remains unchanged except child counts. Newly appended subtrees
+ * use their current local transforms beneath the CAPTURED parent world matrix,
+ * so playback and later scene placement never become the old rig's reference.
+ * Returns a new deeply frozen snapshot without mutating the model or previous
+ * data. Identical sibling swaps cannot be distinguished by structural identity.
+ */
+export declare function extendModelReferencePose(model: Object3D, previous: ThreeModelReferencePose): ThreeModelReferencePose;
+/**
+ * Resolve captured data against an identically structured model, including a fresh
+ * clone/load with new UUIDs. Names, types, bone flags, and child ordering must match;
+ * duplicate names are distinguished by structural path, never name lookup.
+ * Current transforms and the model's external scene parent are deliberately ignored.
+ * An incompatible hierarchy throws before a binding map is returned.
+ */
+export declare function bindModelReferencePose(model: Object3D, referencePose: ThreeModelReferencePose): ReadonlyMap<Object3D, ThreeReferencePoseNode>;
+export {};

package/dist/three/scene.d.ts

@@ -0,0 +1,253 @@
+import { Mesh, PerspectiveCamera, PlaneGeometry, Scene, ShadowMaterial, WebGLRenderer } from 'three';
+import type { ColorRepresentation, Texture } from 'three';
+import type { WebGPURenderer } from 'three/webgpu';
+export type DefaultCharacterLightingSettings = {
+    envMapEnabled: boolean;
+    environmentIntensity: number;
+    environmentBlur: number;
+    exposure: number;
+    ambientIntensity: number;
+    keyIntensity: number;
+    fillIntensity: number;
+    rimIntensity: number;
+    shadowOpacity: number;
+};
+export declare const DEFAULT_CHARACTER_LIGHTING_PRESETS: {
+    readonly cleanStudio: {
+        readonly id: "cleanStudio";
+        readonly label: "Soft Studio";
+        readonly settings: {
+            readonly envMapEnabled: true;
+            readonly environmentIntensity: 0.24;
+            readonly environmentBlur: 0.04;
+            readonly exposure: 1.08;
+            readonly ambientIntensity: 0.32;
+            readonly keyIntensity: 0.52;
+            readonly fillIntensity: 0.18;
+            readonly rimIntensity: 0.08;
+            readonly shadowOpacity: 0.22;
+        };
+    };
+    readonly softFill: {
+        readonly id: "softFill";
+        readonly label: "Soft Fill";
+        readonly settings: {
+            readonly envMapEnabled: true;
+            readonly environmentIntensity: 0.3;
+            readonly environmentBlur: 0.04;
+            readonly exposure: 1.1;
+            readonly ambientIntensity: 0.38;
+            readonly keyIntensity: 0.44;
+            readonly fillIntensity: 0.24;
+            readonly rimIntensity: 0.1;
+            readonly shadowOpacity: 0.18;
+        };
+    };
+    readonly inspection: {
+        readonly id: "inspection";
+        readonly label: "Inspection";
+        readonly settings: {
+            readonly envMapEnabled: true;
+            readonly environmentIntensity: 0.45;
+            readonly environmentBlur: 0.035;
+            readonly exposure: 1.18;
+            readonly ambientIntensity: 0.48;
+            readonly keyIntensity: 0.58;
+            readonly fillIntensity: 0.32;
+            readonly rimIntensity: 0.14;
+            readonly shadowOpacity: 0.12;
+        };
+    };
+    readonly contrast: {
+        readonly id: "contrast";
+        readonly label: "Contrast";
+        readonly settings: {
+            readonly envMapEnabled: true;
+            readonly environmentIntensity: 0.2;
+            readonly environmentBlur: 0.035;
+            readonly exposure: 1.08;
+            readonly ambientIntensity: 0.25;
+            readonly keyIntensity: 0.7;
+            readonly fillIntensity: 0.12;
+            readonly rimIntensity: 0.22;
+            readonly shadowOpacity: 0.28;
+        };
+    };
+};
+export type DefaultCharacterLightingPresetId = keyof typeof DEFAULT_CHARACTER_LIGHTING_PRESETS;
+export declare const DEFAULT_CHARACTER_LIGHTING_PRESET_ID: DefaultCharacterLightingPresetId;
+export declare const DEFAULT_CHARACTER_LIGHTING_PRESET_IDS: DefaultCharacterLightingPresetId[];
+export declare const DEFAULT_CHARACTER_LIGHTING_SETTINGS: DefaultCharacterLightingSettings;
+export declare const CHARACTER_SCENE_TYPES: {
+    readonly studio: {
+        readonly id: "studio";
+        readonly label: "Studio";
+        readonly description: "Transparent background, soft studio lighting, ground shadow.";
+        readonly background: null;
+        readonly lightingPreset: "cleanStudio";
+        readonly shadowPlane: true;
+    };
+    readonly showcase: {
+        readonly id: "showcase";
+        readonly label: "Showcase";
+        readonly description: "Dark backdrop with contrasty key/rim lighting for presentation shots.";
+        readonly background: 1053206;
+        readonly lightingPreset: "contrast";
+        readonly shadowPlane: true;
+    };
+    readonly inspection: {
+        readonly id: "inspection";
+        readonly label: "Inspection";
+        readonly description: "Bright, even lighting on a light backdrop for close-up review.";
+        readonly background: 15264493;
+        readonly lightingPreset: "inspection";
+        readonly shadowPlane: true;
+    };
+    readonly void: {
+        readonly id: "void";
+        readonly label: "Void";
+        readonly description: "Transparent background, soft fill lighting, no ground shadow.";
+        readonly background: null;
+        readonly lightingPreset: "softFill";
+        readonly shadowPlane: false;
+    };
+};
+export type CharacterSceneTypeId = keyof typeof CHARACTER_SCENE_TYPES;
+export declare const CHARACTER_SCENE_TYPE_IDS: CharacterSceneTypeId[];
+export declare const DEFAULT_CHARACTER_SCENE_TYPE_ID: CharacterSceneTypeId;
+export type DefaultCharacterSceneOptions = {
+    type?: CharacterSceneTypeId;
+    background?: ColorRepresentation | null;
+    cameraFov?: number;
+    pixelRatioCap?: number;
+    shadows?: boolean;
+    lightingPreset?: DefaultCharacterLightingPresetId;
+    lighting?: Partial<DefaultCharacterLightingSettings>;
+    shadowPlane?: boolean;
+    manageResize?: boolean;
+};
+export type DefaultCharacterSceneAsyncOptions = DefaultCharacterSceneOptions & {
+    /** Auto (default) tries native WebGPU initialization, then falls back to WebGL. */
+    renderer?: CharacterSceneRendererPreference;
+    /** Persistent settings take precedence over the legacy renderer option. */
+    rendering?: Partial<CharacterSceneRenderingSettings>;
+    /** Cancels construction, not ownership of a successfully returned scene. */
+    signal?: AbortSignal;
+    /** Compatibility notification; rendering snapshots also expose device loss. */
+    onDeviceLost?: (error: Error) => void;
+};
+export type CharacterSceneRenderer = WebGLRenderer | WebGPURenderer;
+export type CharacterSceneBackend = 'webgl' | 'webgpu';
+export type CharacterSceneRendererPreference = 'auto' | CharacterSceneBackend;
+type CharacterScene<R extends CharacterSceneRenderer> = {
+    container: HTMLElement;
+    scene: Scene;
+    renderer: R;
+    camera: PerspectiveCamera;
+    lighting: ReturnType<typeof createDefaultCharacterLighting>;
+    shadowPlane: ReturnType<typeof createShadowPlane> | null;
+    sceneType: CharacterSceneTypeId;
+    ownsScene: true;
+    resize: () => void;
+    dispose: () => void;
+};
+export type DefaultCharacterScene = CharacterScene<WebGLRenderer>;
+export type CharacterSceneRenderingSettings = {
+    preference: CharacterSceneRendererPreference;
+};
+export type CharacterSceneRenderingStatus = 'initializing' | 'switching' | 'ready' | 'error' | 'lost' | 'disposed';
+export type CharacterSceneRenderingSnapshot = {
+    readonly settings: CharacterSceneRenderingSettings;
+    readonly status: CharacterSceneRenderingStatus;
+    readonly error: Error | null;
+} & ({
+    readonly backend: 'webgl';
+    readonly renderer: WebGLRenderer;
+} | {
+    readonly backend: 'webgpu';
+    readonly renderer: WebGPURenderer;
+} | {
+    readonly backend: null;
+    readonly renderer: null;
+});
+export type CharacterSceneRendererLease = {
+    readonly renderer: CharacterSceneRenderer;
+    release(): void;
+};
+export interface CharacterSceneRenderingController {
+    getSettings(): CharacterSceneRenderingSettings;
+    getSnapshot(): CharacterSceneRenderingSnapshot;
+    setSettings(patch: Partial<CharacterSceneRenderingSettings>): Promise<CharacterSceneRenderingSnapshot>;
+    subscribe(listener: (snapshot: CharacterSceneRenderingSnapshot) => void): () => void;
+    /** Borrow for capture/readback; release in finally. Unavailable during switching/loss. */
+    acquireRenderer(): CharacterSceneRendererLease;
+    /** Drain borrowed work, then synchronously detach/free caller-owned resources, even after loss/disposal. */
+    releaseSceneResources(release: () => void): Promise<void>;
+}
+export type DefaultCharacterSceneRuntimeOptions = DefaultCharacterSceneAsyncOptions;
+export type DefaultCharacterSceneRuntime = Omit<CharacterScene<CharacterSceneRenderer>, 'renderer' | 'dispose'> & {
+    readonly renderer: CharacterSceneRenderer | null;
+    readonly backend: CharacterSceneBackend | null;
+    dispose(): Promise<void>;
+    readonly rendering: CharacterSceneRenderingController;
+    readonly ready: Promise<CharacterSceneRenderingSnapshot>;
+};
+export type ReadyDefaultCharacterScene = ((Omit<DefaultCharacterScene, 'dispose'> & {
+    readonly backend: 'webgl';
+}) | (Omit<CharacterScene<WebGPURenderer>, 'dispose'> & {
+    readonly backend: 'webgpu';
+})) & {
+    readonly rendering: CharacterSceneRenderingController;
+    dispose(): Promise<void>;
+};
+export declare const normalizeDefaultCharacterLightingSettings: (value: unknown) => DefaultCharacterLightingSettings | null;
+export declare function createShadowPlane(scene: Scene, options?: {
+    size?: number;
+    opacity?: number;
+    yPosition?: number;
+}): Mesh<PlaneGeometry, ShadowMaterial, import("three").Object3DEventMap>;
+export declare function createDefaultCharacterLighting(scene: Scene, renderer: WebGLRenderer, initial?: Partial<DefaultCharacterLightingSettings>): {
+    getSettings: () => {
+        envMapEnabled: boolean;
+        environmentIntensity: number;
+        environmentBlur: number;
+        exposure: number;
+        ambientIntensity: number;
+        keyIntensity: number;
+        fillIntensity: number;
+        rimIntensity: number;
+        shadowOpacity: number;
+    };
+    getEnvironmentTexture: () => Texture | null;
+    setSettings: (patch: Partial<DefaultCharacterLightingSettings>) => {
+        envMapEnabled: boolean;
+        environmentIntensity: number;
+        environmentBlur: number;
+        exposure: number;
+        ambientIntensity: number;
+        keyIntensity: number;
+        fillIntensity: number;
+        rimIntensity: number;
+        shadowOpacity: number;
+    };
+    setPreset: (id: DefaultCharacterLightingPresetId) => {
+        envMapEnabled: boolean;
+        environmentIntensity: number;
+        environmentBlur: number;
+        exposure: number;
+        ambientIntensity: number;
+        keyIntensity: number;
+        fillIntensity: number;
+        rimIntensity: number;
+        shadowOpacity: number;
+    };
+    subscribe: (listener: (value: DefaultCharacterLightingSettings) => void) => () => void;
+    dispose: () => void;
+};
+/** The existing synchronous WebGL path; it does not wait for shader compilation. */
+export declare function createDefaultCharacterScene(container: HTMLElement, options?: DefaultCharacterSceneOptions): DefaultCharacterScene;
+/** Stable scene ownership, including a recoverable initial renderer failure. */
+export declare function createDefaultCharacterSceneRuntime(container: HTMLElement, options?: DefaultCharacterSceneRuntimeOptions): DefaultCharacterSceneRuntime;
+/** Compatibility factory: failure releases all owned resources. Use the runtime factory for initial retry. */
+export declare function createDefaultCharacterSceneAsync(container: HTMLElement, options?: DefaultCharacterSceneAsyncOptions): Promise<ReadyDefaultCharacterScene>;
+export {};

package/dist/three/sceneRenderingBinding.d.ts

@@ -0,0 +1,22 @@
+import type { PerspectiveCamera, Scene } from 'three';
+import type { CharacterSceneRenderer, CharacterSceneRenderingController } from './scene';
+/** Adapter-private binding. Applications pass config.rendering to the camera controller. */
+export type SceneRenderingBinding = {
+    suspend(): Promise<void>;
+    prepare(renderer: CharacterSceneRenderer): Promise<void>;
+    commit(renderer: CharacterSceneRenderer): Promise<void>;
+    onError(error: unknown): void;
+};
+type Owner = {
+    scene: Scene;
+    camera: PerspectiveCamera;
+    binding: SceneRenderingBinding | null;
+    disposed: boolean;
+    drain: Promise<void> | null;
+    settled: () => Promise<unknown> | null;
+    reportFailure: (error: unknown, renderer?: CharacterSceneRenderer | null) => void;
+};
+export declare function registerSceneRendering(controller: CharacterSceneRenderingController, scene: Scene, camera: PerspectiveCamera, settled: () => Promise<unknown> | null, reportFailure: (error: unknown, renderer?: CharacterSceneRenderer | null) => void): Owner;
+export declare function bindSceneRendering(controller: CharacterSceneRenderingController, scene: Scene, camera: PerspectiveCamera, binding: SceneRenderingBinding): () => Promise<undefined> | null;
+export declare function reportSceneRenderingFailure(controller: CharacterSceneRenderingController, error: unknown, renderer?: CharacterSceneRenderer | null): void;
+export {};