/**
 * Transactional scene and component replacement for worker-owned Three.js applications.
 *
 * This module does not install Vite handlers by itself. Applications opt into replacement
 * from their own `import.meta.hot.accept()` callback, which keeps the public entrypoint
 * side-effect free and makes production tree-shaking predictable.
 *
 * @module three-blocks/hmr
 */
import { Object3D } from 'three';
export type MaybePromise<TValue> = TValue | PromiseLike<TValue>;
export type HotReplacementPhase = 'capture' | 'create' | 'restore' | 'prepare' | 'compile' | 'commit';
/** A replacement failure that leaves the previously committed object active. */
export declare class HotReplacementError extends Error {
    readonly phase: HotReplacementPhase;
    readonly causeValue: unknown;
    readonly cleanupError: unknown;
    constructor(phase: HotReplacementPhase, causeValue: unknown, cleanupError?: unknown);
}
export interface HotScene<TState = unknown> {
    /** Shallow, declared state whose compatible fields survive scene replacement. */
    readonly hot?: object;
    captureHotState?(): TState;
    restoreHotState?(state: TState): MaybePromise<void>;
    dispose(): MaybePromise<void>;
}
export type HotSceneFactory<TScene, TContext> = (context: TContext) => MaybePromise<TScene>;
export interface SceneHotReloaderOptions<TScene extends HotScene<TState>, TContext, TState = unknown> {
    readonly context: TContext;
    /** Load newly required resources before the candidate becomes visible. */
    readonly prepare?: (scene: TScene, context: TContext) => MaybePromise<void>;
    /** Compile render and compute pipelines before the atomic reference swap. */
    readonly compile?: (scene: TScene, context: TContext) => MaybePromise<void>;
    /** Atomically expose the candidate to the renderer while updates remain paused. */
    readonly commit?: (scene: TScene, previous: TScene, context: TContext) => MaybePromise<void>;
    /** Optional frame scheduler hooks. `resume` always runs after a matching `pause`. */
    readonly pause?: () => void;
    readonly resume?: () => void;
}
export interface SceneReplacementResult<TScene> {
    readonly previous: TScene;
    readonly current: TScene;
    /** Disposal occurs after commit, so a cleanup failure cannot roll back the new scene. */
    readonly cleanupError?: unknown;
}
/**
 * Transfer compatible own fields while keeping the candidate's declared shape.
 * Renamed, removed, and re-typed fields therefore keep their new-code defaults.
 */
export declare function transferDeclaredHotState(previous: HotScene, candidate: HotScene): void;
/**
 * Owns the single scene reference consumed by a render loop and serializes hot updates.
 * A candidate is prepared completely before `current` changes, so failed replacements
 * cannot expose a partially initialized scene.
 */
export declare class SceneHotReloader<TScene extends HotScene<TState>, TContext, TState = unknown> {
    #private;
    constructor(initial: TScene, options: SceneHotReloaderOptions<TScene, TContext, TState>);
    get current(): TScene;
    replace(factory: HotSceneFactory<TScene, TContext>): Promise<SceneReplacementResult<TScene>>;
}
/** State intentionally preserved automatically during component replacement. */
export interface ComponentHotSnapshot {
    readonly position: readonly [number, number, number];
    readonly quaternion: readonly [number, number, number, number];
    readonly scale: readonly [number, number, number];
    readonly visible: boolean;
    readonly layers: number;
    readonly renderOrder: number;
    readonly name: string;
}
export declare function captureComponentHotSnapshot(component: Object3D): ComponentHotSnapshot;
export declare function restoreComponentHotSnapshot(component: Object3D, snapshot: ComponentHotSnapshot): void;
/**
 * Explicit post-construction lifecycle. Class fields are initialized before `mount` runs;
 * base constructors never call an overridable lifecycle method.
 */
export declare abstract class ThreeComponent<TOptions, TContext = unknown, THotState = unknown> extends Object3D {
    abstract mount(context: TContext, options: TOptions): MaybePromise<void>;
    abstract dispose(): MaybePromise<void>;
    captureHotState?(): THotState;
    restoreHotState?(state: THotState): MaybePromise<void>;
}
export type ThreeComponentClass<TOptions, TContext, THotState, TComponent extends ThreeComponent<TOptions, TContext, THotState> = ThreeComponent<TOptions, TContext, THotState>> = new () => TComponent;
export interface ComponentMountRequest<TOptions, TContext, THotState, TComponent extends ThreeComponent<TOptions, TContext, THotState>> {
    readonly key: string;
    readonly Component: ThreeComponentClass<TOptions, TContext, THotState, TComponent>;
    readonly parent: Object3D;
    readonly context: TContext;
    readonly options: TOptions;
    readonly index?: number;
}
export interface ComponentReplacementResult<TComponent extends Object3D> {
    readonly previous: Object3D;
    readonly current: TComponent;
    readonly cleanupError?: unknown;
}
export interface ComponentHotOperationContext {
    readonly key: string;
    readonly context: unknown;
    readonly options: unknown;
}
export interface ComponentHotRegistryOptions {
    readonly pause?: () => void;
    readonly resume?: () => void;
    /** Await newly required resources while the previous component remains mounted. */
    readonly prepare?: (component: Object3D, operation: ComponentHotOperationContext) => MaybePromise<void>;
    /** Compile candidate pipelines before the parent/registry transaction commits. */
    readonly compile?: (component: Object3D, operation: ComponentHotOperationContext) => MaybePromise<void>;
}
/** Transactional registry used by component-level `import.meta.hot.accept()` handlers. */
export declare class ComponentHotRegistry {
    #private;
    constructor(options?: ComponentHotRegistryOptions);
    has(key: string): boolean;
    get(key: string): Object3D | undefined;
    mount<TOptions, TContext, THotState, TComponent extends ThreeComponent<TOptions, TContext, THotState>>(request: ComponentMountRequest<TOptions, TContext, THotState, TComponent>): Promise<TComponent>;
    replace<TOptions, TContext, THotState, TComponent extends ThreeComponent<TOptions, TContext, THotState>>(key: string, Component: ThreeComponentClass<TOptions, TContext, THotState, TComponent>): Promise<ComponentReplacementResult<TComponent>>;
    dispose(key: string): Promise<boolean>;
    disposeAll(): Promise<void>;
}
export declare function createSceneHotReloader<TScene extends HotScene<TState>, TContext, TState = unknown>(initial: TScene, options: SceneHotReloaderOptions<TScene, TContext, TState>): SceneHotReloader<TScene, TContext, TState>;
export declare function createComponentHotRegistry(options?: ComponentHotRegistryOptions): ComponentHotRegistry;