@lovelace_lol/embody 0.0.7 → 0.0.9

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 {};