@lovelace_lol/embody 0.0.7 → 0.0.8

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

@@ -0,0 +1,157 @@
+import { Vector3, type Object3D } from 'three';
+import { type EmbodyCore } from '@lovelace_lol/embody/wasm';
+import type { AnnotationCharacterConfig, AnnotationLaterality, BoneResolutionProfile, Region } from './types';
+export { initEmbodyCore } from '@lovelace_lol/embody/wasm';
+export type { AnnotationLaterality, BoneResolutionProfile } from './types';
+type Point = {
+    x: number;
+    y: number;
+    z: number;
+};
+type Rotation = Point & {
+    w: number;
+};
+type Bounds = {
+    center: Point;
+    size: Point;
+};
+/** Typed, allocation-only bridge to the canonical Rust camera and marker algorithms. */
+export declare class RustAnnotationCameraCore {
+    private readonly core;
+    constructor(core: EmbodyCore);
+    static create(): Promise<RustAnnotationCameraCore>;
+    normalizeCameraAngle(angle: number): number;
+    worldDirectionForCameraAngle(q: Rotation | undefined, angle: number): Point;
+    resolveFocusCameraDirection(q: Rotation | undefined, effectiveAngle: number, cameraAngle?: number, angleSpace?: string): Point;
+    resolveAutoCloseupAngle(offset: number, focusSize: Point, modelSize: Point): number | undefined;
+    focusPaddingFactor(size: number, closeUp: number, zoom: number, fullBody: number): number;
+    solveFocusFraming(o: {
+        focusBounds?: Bounds;
+        modelBounds?: Bounds | null;
+        modelQuaternion?: Rotation;
+        fovDegrees: number;
+        aspect: number;
+        minDistance: number;
+        closeUpPaddingFactor: number;
+        zoomPaddingFactor: number;
+        fullBodyPaddingFactor: number;
+        overridePadding?: number;
+        cameraAngle?: number;
+        angleSpace?: string;
+    }): {
+        position: Point;
+        target: Point;
+        distance: number;
+    };
+    solveFullBodyFraming(o: {
+        boxMin: Point;
+        boxMax: Point;
+        modelQuaternion?: Rotation;
+        fovDegrees: number;
+        aspect: number;
+        minDistance: number;
+        fullBodyPaddingFactor: number;
+        overridePadding?: number;
+        cameraAngle?: number;
+        angleSpace?: string;
+    }): {
+        position: Point;
+        target: Point;
+        distance: number;
+    };
+    passesMarkerCameraAngleGate(o: {
+        markerAngle?: number;
+        currentCameraAngle?: number;
+        rangeDegrees?: number;
+    }): boolean;
+    shouldShowMarker(o: {
+        hiddenChild: boolean;
+        solo: 'none' | 'soloed' | 'other-soloed';
+        markerAngle?: number;
+        currentCameraAngle?: number;
+    }): boolean;
+    resolveViewportConstrainedLineScale(o: {
+        startClip: ArrayLike<number>;
+        endClip: ArrayLike<number>;
+        safeX: number;
+        safeY: number;
+        minLengthRatio?: number;
+    }): {
+        visible: boolean;
+        lineScale: number;
+    };
+    resolveViewportSafeBounds(o: {
+        labelScaleX: number;
+        labelScaleY: number;
+        projectionXScale: number;
+        projectionYScale: number;
+        viewportWidth: number;
+        viewportHeight: number;
+        edgePaddingPx?: number;
+    }): {
+        safeX: number;
+        safeY: number;
+    };
+    sampleMarkerBezierCurve(start: Point, end: Point, segments?: number): Float32Array<ArrayBufferLike>;
+    sampleMarkerArcCurve(start: Point, end: Point, segments?: number): Float32Array<ArrayBufferLike>;
+    markerVisibilityAnimationFactors(visible: boolean, t: number): {
+        itemOpacityFactor: number;
+        labelScaleFactor: number;
+        lineOpacityFactor: number;
+    };
+    separateOverlappingMarkerEndpoints(o: {
+        starts: ArrayLike<number>;
+        ends: ArrayLike<number>;
+        modelCenter: Point;
+        modelHeight: number;
+    }): Float32Array<ArrayBufferLike>;
+    createCameraFlight(start: Point, startTarget: Point, end: Point, endTarget: Point, duration: number): {
+        sample(elapsed: number): {
+            position: Point;
+            target: Point;
+            done: boolean;
+        };
+        readonly durationMs: number;
+        dispose(): void;
+    };
+    createCameraOrbit(center: Point, radius: number, height: number, duration: number): {
+        sample(elapsed: number): {
+            position: Point;
+            target: Point;
+            done: boolean;
+        };
+        readonly durationMs: number;
+        dispose(): void;
+    };
+}
+export declare const createRustAnnotationCameraCore: () => Promise<RustAnnotationCameraCore>;
+/** Resolve only annotation/profile inputs, preserving host-only data by reference. */
+export declare function resolveAnnotationCharacterConfig<T extends AnnotationCharacterConfig>(config: T): Promise<T>;
+export declare function resolveBoneNames(names: string[] | undefined, profile?: BoneResolutionProfile | null): string[];
+export declare function fuzzyNameMatch(objectName: string, targetName: string, suffixPattern?: string): boolean;
+export declare function getDefaultAnnotationLaterality(): AnnotationLaterality;
+export declare function getSemanticHorizontalSignForSide(side: 'left' | 'right', laterality: AnnotationLaterality): 1 | -1;
+export declare function getSemanticHorizontalSign(name: string, laterality: AnnotationLaterality): 1 | -1 | null;
+export declare function resolveRegionCameraAngle(region: Region, laterality: AnnotationLaterality): number | undefined;
+export declare function resolveRegionVisibilityCameraAngle(region: Region, laterality: AnnotationLaterality): number | undefined;
+export declare function toWorldDirection(model: Object3D | null, local: Vector3): Vector3;
+export declare function getWorldDirectionForCameraAngle(model: Object3D | null, angle: number): Vector3;
+export declare function getModelLocalOrbitAngle(model: Object3D | null, center: Vector3, position: Vector3): number;
+export declare function passesMarkerCameraAngleGate(o: {
+    markerAngle?: number;
+    currentCameraAngle?: number;
+    rangeDegrees?: number;
+}): boolean;
+/** Reduce scene objects to a world-space annotation anchor; numeric camera math stays in Rust. */
+export declare function resolveFaceCenter(model: Object3D, region: Region, profile?: BoneResolutionProfile | null): {
+    center: Vector3;
+    method: string;
+    debugInfo: string[];
+    headBonePosition?: undefined;
+} | {
+    center: Vector3;
+    headBonePosition: Vector3 | undefined;
+    method: string;
+    debugInfo: string[];
+};
+export declare function detectAnnotationLaterality(model: Object3D | null, regions: Region[], profile: BoneResolutionProfile | null): AnnotationLaterality;

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

@@ -0,0 +1,18 @@
+export type AnimationFrameTask = (now: number) => boolean;
+/**
+ * Runs multiple short UI animation tasks from one requestAnimationFrame loop.
+ *
+ * Tasks return true while they need another frame and false when complete.
+ */
+export declare class AnimationFrameTaskScheduler {
+    private frameId;
+    private readonly tasks;
+    get size(): number;
+    has(key: string): boolean;
+    schedule(key: string, task: AnimationFrameTask, runImmediately?: boolean): void;
+    cancel(key: string): void;
+    cancelAll(): void;
+    private requestFrame;
+    private readonly tick;
+    private cancelFrameIfIdle;
+}

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

@@ -0,0 +1,16 @@
+import type { AnnotationAnchoredRegion, AnnotationMarkerAnchor, Region } from './types';
+export type MarkerAnchorProjectionMode = 'legacy' | 'project' | 'skip';
+export interface ResolvedMarkerAnchorRegion {
+    region: AnnotationAnchoredRegion;
+    anchor: AnnotationMarkerAnchor | null;
+    source: 'legacy-region' | 'marker-anchor';
+    projection: MarkerAnchorProjectionMode;
+    useLegacyRegionSemantics: boolean;
+}
+/**
+ * Convert explicit marker-anchor intent into the legacy region target fields
+ * that the current marker renderers understand.
+ */
+export declare function resolveMarkerAnchorRegion(region: Region): ResolvedMarkerAnchorRegion;
+export declare function shouldUseFaceCenterForMarkerAnchor(resolved: ResolvedMarkerAnchorRegion): boolean;
+export declare function shouldProjectMarkerAnchorToSurface(resolved: ResolvedMarkerAnchorRegion, legacyDefault: boolean): boolean;

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

@@ -0,0 +1,5 @@
+import { type RustAnnotationCameraCore } from './adapter';
+/** Share the stateless Rust math adapter across cameras and markers. */
+export declare function getAnnotationCameraCore(): Promise<RustAnnotationCameraCore>;
+/** Synchronous render-loop math is available after the owning load awaits initialization. */
+export declare function requireAnnotationCameraCore(): RustAnnotationCameraCore;

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

@@ -0,0 +1,7 @@
+import type { BoneResolutionProfile } from './adapter';
+/**
+ * Embody serializes bone-resolution inputs into Wasm. Passing a complete
+ * character profile also serializes authored vertex deltas and saved clips
+ * for every annotation lookup, even though the resolver cannot use them.
+ */
+export declare function boneResolutionProfile(profile: BoneResolutionProfile | null | undefined): BoneResolutionProfile | null;

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

@@ -0,0 +1,20 @@
+export { DPthree, CameraController, Markers3D, MarkersHTML, Controls } from './DPthree';
+export type { DPthreeConfig, CharacterValidationResult, ValidationCategory, ValidationItem } from './DPthree';
+export { DPthreeCameraController } from './DPthreeCameraController';
+export type { MarkerStateSnapshot } from './DPthreeCameraController';
+export { DPthree3DMarkers } from './DPthree3DMarkers';
+export { DPthreeHTMLMarkers } from './DPthreeHTMLMarkers';
+export { DPthreeMarkers } from './DPthreeMarkers';
+export { CameraDOMControls, RUNTIME_ANNOTATION_REGION_PREFIX, filterCameraViewRegions, isRuntimeAnnotationRegionName, buildRegionDisplayOptions } from './DOMControls';
+export type { DOMControlRegion, DOMControlsConfig } from './DOMControls';
+export { resolveMarkerAnchorRegion, shouldProjectMarkerAnchorToSurface, shouldUseFaceCenterForMarkerAnchor } from './annotationAnchorModel';
+export type { MarkerAnchorProjectionMode, ResolvedMarkerAnchorRegion } from './annotationAnchorModel';
+export { getRuntimeAnnotationSide, getRuntimeAUMorphAnchorPoint, getRuntimeAUMeshSideOffset } from './runtimeAnnotationSidePreview';
+export { createMarkerVisibilityLifecycle, createMarkerLifecycleRevealOptions, DEFAULT_MARKER_AUTO_HIDE_MS } from './markerVisibilityLifecycle';
+export type { MarkerLifecycleRevealOptions, MarkerLifecycleRevealSource } from './markerVisibilityLifecycle';
+export { createRuntimeAnnotationPreviewLifecycle, DEFAULT_PREVIEW_AUTO_CLEAR_MS } from './runtimeAnnotationPreview';
+export type { RuntimeAnnotationPreviewLifecycleOptions } from './runtimeAnnotationPreview';
+export { inferRuntimeAnnotationPreviewSide, pickContinuumAnnotationAuId } from './runtimeAnnotationPreviewSide';
+export { boneResolutionProfile } from './boneResolutionProfile';
+export { resolveAnnotationCharacterConfig, RustAnnotationCameraCore, createRustAnnotationCameraCore, getDefaultAnnotationLaterality, getSemanticHorizontalSignForSide, getSemanticHorizontalSign, resolveRegionCameraAngle, resolveRegionVisibilityCameraAngle, toWorldDirection, getWorldDirectionForCameraAngle, getModelLocalOrbitAngle, passesMarkerCameraAngleGate, resolveFaceCenter, detectAnnotationLaterality, } from './adapter';
+export type { AnnotationCharacterConfig, AnnotationAnchorPoint, AnnotationMarkerAnchor, AnnotationMarkerAnchorType, AnnotationFocusTarget, AnnotationAnchoredRegion, RuntimeAnnotationMetadata, RuntimeAnnotationOptions, RuntimeAnnotationRegionSummary, RuntimeAnnotationSide, RuntimeAnnotationTargetType, CameraState, FocusPosition, DPthreeCameraControllerConfig, RegionChangeCallback, CharacterChangeCallback, DPthreeRegion, DPthreeCharacterConfig, DPthreeRegistry, DPthreeRegionChangeCallback, DPthreeCharacterChangeCallback, LineStyle, LineCurve, NamedDirection, LineConfig, MarkerStyleOverrides, ExpandAnimation, ExpandedRegionState, FallbackConfig, MarkerGroup, Region, MarkerStyle, BoneResolutionProfile, AnnotationLaterality, } from './types';

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

@@ -0,0 +1,2 @@
+/** Continue in a task after paint, rather than in the animation-frame microtask. */
+export declare function waitForCharacterLoadPaint(): Promise<void>;

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

@@ -0,0 +1,11 @@
+import type * as THREE from 'three';
+/**
+ * Keep Three's native per-mesh raycast, including skinning, morphs and material
+ * sides. Yield between meshes once a slice is spent; one mesh is indivisible.
+ * A null result means the owning model/region load was replaced or disposed.
+ */
+export declare function intersectMeshesInSlices(raycaster: THREE.Raycaster, meshes: readonly THREE.Mesh[], options: {
+    isCurrent: () => boolean;
+    yieldToPaint: () => Promise<void>;
+    now?: () => number;
+}): Promise<THREE.Intersection[] | null>;

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

@@ -0,0 +1,21 @@
+import type { DPthreeCameraController } from './DPthreeCameraController';
+import type { MarkerStyle } from './types';
+export declare const DEFAULT_MARKER_AUTO_HIDE_MS = 5000;
+export type MarkerLifecycleRevealOptions = {
+    durationMs?: number;
+    markerStyle?: MarkerStyle;
+    revealDelayMs?: number;
+};
+export type MarkerLifecycleRevealSource = {
+    markerStyle?: MarkerStyle;
+    playIntroOnLoad?: boolean;
+};
+type MarkerLifecycleController = Pick<DPthreeCameraController, 'setMarkersVisible' | 'setMarkerStyle'>;
+export declare function createMarkerLifecycleRevealOptions(config: MarkerLifecycleRevealSource | null | undefined): MarkerLifecycleRevealOptions;
+export declare function createMarkerVisibilityLifecycle(getController: () => MarkerLifecycleController | null, defaultDurationMs?: number): {
+    setManualVisibility(visible: boolean): void;
+    prepareForCharacterLoad(): void;
+    showForCharacterLoad(options?: MarkerLifecycleRevealOptions): void;
+    dispose(): void;
+};
+export {};

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

@@ -0,0 +1,6 @@
+import * as THREE from 'three';
+import type { CharacterSceneRenderer } from '../scene';
+/** Three collects visible surfaces before yielding; no shared mutations span the await. */
+export declare function compileModelForRender(renderer: CharacterSceneRenderer, scene: THREE.Scene, camera: THREE.Camera, model: THREE.Object3D): Promise<unknown>;
+/** One complete scene draw initializes native geometry/textures and real shadow variants. */
+export declare function drawModelForRender(renderer: CharacterSceneRenderer, scene: THREE.Scene, camera: THREE.Camera, model: THREE.Object3D): () => void;

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

@@ -0,0 +1,15 @@
+export declare const DEFAULT_PREVIEW_AUTO_CLEAR_MS = 1200;
+export interface RuntimeAnnotationPreviewLifecycleOptions {
+    getDisabled?: () => boolean;
+    getAutoClearMs?: () => number | undefined;
+    onPreviewStart?: () => void;
+    onPreviewEnd?: () => void;
+}
+/** Framework-independent annotation preview lifetime; hosts supply input events. */
+export declare function createRuntimeAnnotationPreviewLifecycle(options: RuntimeAnnotationPreviewLifecycleOptions): {
+    start(forceRefresh?: boolean): void;
+    end: () => void;
+    scheduleEnd: () => void;
+    isActive: () => boolean;
+    dispose: () => void;
+};

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

@@ -0,0 +1,10 @@
+import type { RuntimeAnnotationSide } from './types';
+export declare function inferRuntimeAnnotationPreviewSide(auId: number, profile: {
+    auToMorphs?: unknown;
+    auToBones?: unknown;
+} | null | undefined): RuntimeAnnotationSide | undefined;
+/**
+ * Pick which continuum AU to annotate. While a drag gesture is sticky, keep
+ * the original side so crossing 0 does not rebuild runtime markers mid-drag.
+ */
+export declare function pickContinuumAnnotationAuId(value: number, negId: number, posId: number, stickyId: number | null): number;

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

@@ -0,0 +1,5 @@
+import * as THREE from 'three';
+import type { AnnotationAnchoredRegion, RuntimeAnnotationSide } from './types';
+export declare function getRuntimeAnnotationSide(region: AnnotationAnchoredRegion): RuntimeAnnotationSide | null;
+export declare function getRuntimeAUMorphAnchorPoint(region: AnnotationAnchoredRegion, mesh: THREE.Mesh): THREE.Vector3 | null;
+export declare function getRuntimeAUMeshSideOffset(region: AnnotationAnchoredRegion, sideSign: number, modelSize: THREE.Vector3): THREE.Vector3 | null;

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

@@ -0,0 +1,262 @@
+import type * as THREE from 'three';
+import type { CharacterSceneRenderer, CharacterSceneRenderingController } from '../scene';
+export type LineStyle = 'solid' | 'dashed' | 'dotted';
+export type LineCurve = 'straight' | 'bezier' | 'arc';
+export type NamedDirection = 'radial' | 'camera' | 'up' | 'down' | 'left' | 'right' | 'forward' | 'backward';
+export interface LineConfig {
+    style?: LineStyle;
+    curve?: LineCurve;
+    arrowHead?: boolean;
+    thickness?: number;
+    length?: number;
+}
+export interface MarkerStyleOverrides {
+    markerColor?: number;
+    markerRadius?: number;
+    lineColor?: number;
+    labelColor?: string;
+    labelBackground?: string;
+    labelFontSize?: number;
+    opacity?: number;
+    lineDirection?: NamedDirection | {
+        x: number;
+        y: number;
+        z: number;
+    };
+    line?: LineConfig;
+}
+export type ExpandAnimation = 'outward' | 'staggered';
+export interface ExpandedRegionState {
+    regionName: string;
+    isExpanded: boolean;
+    children: string[];
+}
+export interface FallbackConfig {
+    fallbackMarker?: string;
+    clickBehavior?: 'fit-all' | 'rotate';
+}
+export interface MarkerGroup {
+    groupId: string;
+    regions: string[];
+    fallback?: FallbackConfig;
+}
+export interface Region {
+    name: string;
+    bones?: string[];
+    meshes?: string[];
+    objects?: string[];
+    paddingFactor?: number;
+    cameraAngle?: number;
+    cameraOffset?: {
+        x?: number;
+        y?: number;
+        z?: number;
+    };
+    parent?: string;
+    children?: string[];
+    expandAnimation?: ExpandAnimation;
+    style?: MarkerStyleOverrides;
+    groupId?: string;
+    isFallback?: boolean;
+    customPosition?: {
+        x: number;
+        y: number;
+        z: number;
+    };
+}
+export type MarkerStyle = 'html' | '3d';
+export interface AnnotationAnchorPoint {
+    x: number;
+    y: number;
+    z: number;
+}
+export type AnnotationMarkerAnchorType = 'region' | 'point' | 'bone' | 'mesh' | 'object' | 'face-center';
+/**
+ * Explicit marker-anchor intent for annotation regions.
+ *
+ * Shared renderer-adapter contract for authored and runtime annotation regions.
+ */
+export interface AnnotationMarkerAnchor {
+    type: AnnotationMarkerAnchorType;
+    bones?: string[];
+    meshes?: string[];
+    objects?: string[];
+    position?: AnnotationAnchorPoint;
+    /**
+     * Whether 3D markers should raycast from the resolved anchor toward the
+     * visible model surface before drawing the marker sphere.
+     */
+    projectToSurface?: boolean;
+}
+export interface AnnotationFocusTarget {
+    type: 'region' | 'point' | 'bone' | 'mesh' | 'object' | 'face-center';
+    bones?: string[];
+    meshes?: string[];
+    objects?: string[];
+    position?: AnnotationAnchorPoint;
+    paddingFactor?: number;
+    cameraAngle?: number;
+}
+export type RuntimeAnnotationTargetType = 'bone' | 'au';
+export type RuntimeAnnotationSide = 'left' | 'right' | 'center';
+export interface RuntimeAnnotationMetadata {
+    targetType: RuntimeAnnotationTargetType;
+    target: string;
+    boneName?: string;
+    meshName?: string;
+    morphNames?: string[];
+    side?: RuntimeAnnotationSide;
+}
+export interface RuntimeAnnotationOptions {
+    label?: string;
+    markerColor?: number;
+    lineColor?: number;
+    markerRadius?: number;
+    labelColor?: string;
+    labelBackground?: string;
+    labelFontSize?: number;
+    opacity?: number;
+    paddingFactor?: number;
+    cameraAngle?: number;
+    projectToSurface?: boolean;
+    maxTargets?: number;
+    targetPreference?: 'bone' | 'mesh';
+    targetSide?: RuntimeAnnotationSide;
+    replaceExisting?: boolean;
+}
+export interface RuntimeAnnotationRegionSummary {
+    name: string;
+    label: string;
+    targetType: RuntimeAnnotationTargetType;
+    target: string;
+    bones: string[];
+    meshes?: string[];
+    morphs?: string[];
+    side?: RuntimeAnnotationSide;
+}
+export type AnnotationAnchoredRegion = Region & {
+    label?: string;
+    markerAnchor?: AnnotationMarkerAnchor;
+    focusTarget?: AnnotationFocusTarget;
+    runtimeAnnotation?: RuntimeAnnotationMetadata;
+};
+export interface BoneResolutionProfile {
+    bonePrefix?: string;
+    boneSuffix?: string;
+    boneNodes?: Record<string, string>;
+    suffixPattern?: string;
+}
+export interface AnnotationLaterality {
+    leftSideX: 1 | -1;
+    confidence: number;
+    evidence: string[];
+}
+/** Structural runtime input; host storage, authoring and agency fields are not owned here. */
+export interface AnnotationCharacterConfig extends BoneResolutionProfile {
+    characterId: string;
+    characterName?: string;
+    modelPath?: string;
+    regions?: AnnotationAnchoredRegion[];
+    annotationRegions?: AnnotationAnchoredRegion[];
+    markerStyle?: MarkerStyle;
+    playIntroOnLoad?: boolean;
+    defaultRegion?: string;
+    disabledRegions?: string[];
+    profilePresetId?: string;
+    presetId?: string;
+    baseProfileId?: string;
+    auPresetType?: string;
+    profile?: Record<string, unknown>;
+    auToMorphs?: Record<string, unknown>;
+    auToBones?: Record<string, unknown>;
+    morphToMesh?: Record<string, string[]>;
+    markerGroups?: MarkerGroup[];
+    lineDefaults?: LineConfig;
+    markerDefaults?: Partial<MarkerStyleOverrides>;
+}
+export type CharacterConfig = AnnotationCharacterConfig;
+export interface CharacterRegistry {
+    characters: AnnotationCharacterConfig[];
+    defaultCharacter?: string;
+}
+export type AUPresetType = string;
+export type DPthreeRegion = AnnotationAnchoredRegion;
+export type DPthreeCharacterConfig = AnnotationCharacterConfig;
+export type DPthreeRegistry = CharacterRegistry;
+/**
+ * Camera state for save/restore
+ */
+export interface CameraState {
+    position: [number, number, number];
+    target: [number, number, number];
+}
+/**
+ * Configuration for DPthreeCameraController
+ */
+export interface DPthreeCameraControllerConfig {
+    /** Optional selection override; otherwise selecting a region focuses the camera. */
+    onRegionSelect?: (name: string) => void;
+    /** Optional host profile intake; defaults to Embody preset resolution. */
+    resolveCharacterConfig?: (config: AnnotationCharacterConfig) => AnnotationCharacterConfig | Promise<AnnotationCharacterConfig>;
+    /** The Three.js camera to control */
+    camera: THREE.PerspectiveCamera;
+    /** DOM element for OrbitControls (usually the canvas or its container) */
+    domElement: HTMLElement;
+    /** The Three.js scene */
+    scene: THREE.Scene;
+    /** The Three.js renderer - if provided, camera controller manages the render loop */
+    renderer?: CharacterSceneRenderer;
+    /** Owns live backend replacement; pass the matching scene/camera and stable container. */
+    rendering?: CharacterSceneRenderingController;
+    /**
+     * Optional render callback used when the controller owns the render loop.
+     * Allows overlay passes to render after the main character scene. Pending
+     * asynchronous callbacks skip subsequent frames instead of overlapping.
+     */
+    renderFrame?: (renderer: CharacterSceneRenderer, scene: THREE.Scene, camera: THREE.PerspectiveCamera) => void | Promise<void>;
+    /** Rendering failure stops this controller's loop; the host owns recovery. */
+    onRenderError?: (error: Error) => void;
+    /**
+     * Optional resize callback used when renderer sizing is owned by a higher-level
+     * scene manager with its own pixel-ratio policy.
+     */
+    resizeRenderer?: (renderer: CharacterSceneRenderer, width: number, height: number) => void;
+    /** Enable damping/inertia. Default: true */
+    enableDamping?: boolean;
+    /** Damping factor. Default: 0.05 */
+    dampingFactor?: number;
+    /** Minimum zoom distance. Default: 0.5 */
+    minDistance?: number;
+    /** Maximum zoom distance. Default: 10 */
+    maxDistance?: number;
+    /** Default transition duration in ms. Default: 800 */
+    transitionDuration?: number;
+    /** Default padding factor. Default: 1.5 */
+    zoomPaddingFactor?: number;
+    /** Padding for small targets (eyes, mouth). Default: 1.2 */
+    closeUpPaddingFactor?: number;
+    /** Padding for full body view. Default: 2.0 */
+    fullBodyPaddingFactor?: number;
+    /** Show built-in annotation selector. Default: true */
+    showDOMControls?: boolean;
+    /** Container for DOM controls. Default: domElement */
+    controlsContainer?: HTMLElement;
+}
+/**
+ * Calculated focus position for camera animation
+ */
+export interface FocusPosition {
+    position: THREE.Vector3;
+    target: THREE.Vector3;
+    distance: number;
+}
+/**
+ * Callback for region change events
+ */
+export type RegionChangeCallback = (regionName: string) => void;
+/**
+ * Callback for character change events
+ */
+export type CharacterChangeCallback = (config: CharacterConfig) => void;
+export type DPthreeRegionChangeCallback = RegionChangeCallback;
+export type DPthreeCharacterChangeCallback = CharacterChangeCallback;