import { Camera, Object3D, Raycaster, WebGLRenderer } from 'three';

type TargetFingerprint = {
    tag: string;
    attributes?: Record<string, string>;
    heading?: string;
    text?: string;
};

type AnnotationRevealStep = {
    triggerSelector: string;
    targetSelector?: string;
    label: string;
};
type AnnotationRevealRecipe = {
    steps: AnnotationRevealStep[];
    location: string[];
};
type ReactSourceLocation = {
    fileName: string;
    lineNumber: number;
    columnNumber?: number;
};
/** Coordinates refer to the original image, not its responsive DOM rectangle. */
type ImageObjectContext = {
    src: string;
    alt: string;
    width: number;
    height: number;
    box: {
        x: number;
        y: number;
        width: number;
        height: number;
    };
    normalizedBox: {
        x: number;
        y: number;
        width: number;
        height: number;
    };
};
/** Coordinates refer to the decoded video frame, not its responsive DOM box. */
type VideoObjectContext = {
    src: string;
    width: number;
    height: number;
    duration: number;
    currentTime: number;
    normalizedBox: {
        x: number;
        y: number;
        width: number;
        height: number;
    };
    box: {
        x: number;
        y: number;
        width: number;
        height: number;
    };
    trackStart: number;
    trackEnd: number;
};
type ElementInfo = {
    targetFingerprint?: TargetFingerprint;
    selector: string;
    tagName: string;
    /** Adapter-owned semantic name for a non-DOM subject. */
    subjectLabel?: string;
    id?: string;
    className?: string;
    textContent?: string;
    dataAttributes?: Record<string, string>;
    reactComponent?: string;
    reactComponentPath?: string[];
    reactSource?: ReactSourceLocation;
    imageObject?: ImageObjectContext;
    videoObject?: VideoObjectContext;
    /** The real DOM surface, rather than the subject's hidden projection. */
    sourceElement?: ElementInfo;
    context?: string;
    revealRecipe?: AnnotationRevealRecipe;
};

type PopmeltSubjectBounds = {
    left: number;
    top: number;
    width: number;
    height: number;
};
type PopmeltSubjectTrackingAnchor = {
    /** Horizontal position normalized within the subject bounds. */
    x: number;
    /** Vertical position normalized within the subject bounds. */
    y: number;
};
type PopmeltSubjectOutlinePoint = {
    /** Horizontal position normalized within the subject bounds. */
    x: number;
    /** Vertical position normalized within the subject bounds. */
    y: number;
};
type PopmeltSubject = {
    key: string;
    label: string;
    bounds: PopmeltSubjectBounds;
    /** Viewport bounds of the renderer surface that owns this subject. */
    surfaceBounds?: PopmeltSubjectBounds;
    context?: string;
    data?: Record<string, string>;
    /** Live owning surface; never serialized or included in model context. */
    sourceElement?: Element;
    imageObject?: ImageObjectContext;
    videoObject?: VideoObjectContext;
    /** Optional provider-neutral foreground anchors used by motion tracking. */
    trackingAnchors?: readonly PopmeltSubjectTrackingAnchor[];
    /** Optional provider-neutral contour normalized within the subject bounds. */
    outline?: readonly PopmeltSubjectOutlinePoint[];
};
type PopmeltSurfaceSnapshot = {
    element: HTMLCanvasElement;
    dataUrl: string;
};
type PopmeltSubjectCreationSession = {
    key: string;
    update(clientPoint: {
        x: number;
        y: number;
    }): PopmeltSubject | null;
    commit(): PopmeltSubject | null;
    cancel(): void;
};
/**
 * Minimal renderer boundary for non-DOM subjects. The adapter owns hit testing,
 * durable keys, and viewport projection; Popmelt owns annotations and threads.
 */
type PopmeltSubjectAdapter = {
    id: string;
    /** Surface ownership; an explicit image adapter replaces Core's default. */
    surfaceKind?: 'image' | 'video';
    /** Resolve once the adapter's persisted subject index is available. */
    whenReady?(): Promise<void>;
    /** Notify Core when asynchronous perception changes hit-testable subjects. */
    subscribe?(listener: () => void): () => void;
    /** Ordered hit candidates, innermost/most-specific first. */
    hitTestAll?(clientPoint: {
        x: number;
        y: number;
    }): readonly PopmeltSubject[];
    hitTest(clientPoint: {
        x: number;
        y: number;
    }): PopmeltSubject | null;
    resolve(key: string): PopmeltSubject | null;
    /** Recreate a missing durable subject from annotation-captured context. */
    restoreSubject?(key: string, elementInfo: ElementInfo): PopmeltSubject | null;
    /** Optional clean subject crop, without Popmelt's overlay. */
    captureSubject?(key: string): Blob | null | Promise<Blob | null>;
    /** Optional bitmap capture for renderer surfaces that DOM cloning cannot read. */
    captureSurfaces?(): readonly PopmeltSurfaceSnapshot[] | Promise<readonly PopmeltSurfaceSnapshot[]>;
    /** Begin a context-aware subject-creation gesture at a viewport point. */
    beginCreate?(clientPoint: {
        x: number;
        y: number;
    }): PopmeltSubjectCreationSession | null;
    /** Rename a subject without changing its durable key. */
    renameSubject?(key: string, label: string): PopmeltSubject | null;
    /** Replace a subject's viewport bounds, projected back into adapter space. */
    updateSubjectBounds?(key: string, bounds: PopmeltSubjectBounds): PopmeltSubject | null;
    /** Replace optional foreground anchors normalized within subject bounds. */
    updateSubjectTrackingAnchors?(key: string, anchors: readonly PopmeltSubjectTrackingAnchor[]): PopmeltSubject | null;
    /** Promote a transient perception candidate into a durable subject. */
    promoteSubject?(key: string): PopmeltSubject | null;
    /** Remove a user-created subject or hide an adapter-owned subject. */
    removeSubject?(key: string): void;
};

type ThreeSubjectAdapterOptions = {
    /** Unique adapter identity when a page owns more than one Three.js surface. */
    id?: string;
    canvas: HTMLCanvasElement;
    camera: Camera;
    scene: Object3D;
    raycaster?: Raycaster;
    /** Select a meaningful parent from the raw intersected render object. */
    select?: (object: Object3D) => Object3D | null;
    /** Override durable identity. Explicit application IDs are preferred. */
    key?: (object: Object3D) => string | null | undefined;
    label?: (object: Object3D) => string;
    /** Add application-specific provenance or source hints to the model context. */
    describe?: (object: Object3D) => Record<string, string | undefined>;
    /** Capture the renderer's current frame for DOM-cloned screenshots. */
    captureFrame?: () => string | null | Promise<string | null>;
};
/**
 * Read the renderer's visible frame without requiring preserveDrawingBuffer.
 * Rendering and reading synchronously preserves the application's real output
 * pipeline while the previous render target and XR state are restored afterward.
 */
declare function captureThreeRendererFrame(renderer: WebGLRenderer, scene: Object3D, camera: Camera): string | null;
/** Stable while the scene's semantic hierarchy remains stable across reloads. */
declare function threeObjectPath(object: Object3D): string;
/**
 * Collapses glTF material primitives such as `Object649_normal_0` onto their
 * named parent `Object649`. Apps opt into this policy through `select` so raw
 * mesh targeting remains available when material-level annotation is useful.
 */
declare function selectThreeNamedPrimitiveParent(object: Object3D): Object3D;
declare function createThreeSubjectAdapter(options: ThreeSubjectAdapterOptions): PopmeltSubjectAdapter;

export { type ThreeSubjectAdapterOptions, captureThreeRendererFrame, createThreeSubjectAdapter, selectThreeNamedPrimitiveParent, threeObjectPath };