import { AssetReference } from "../../engine/engine_addressables.js";
import { type NeedleXREventArgs, NeedleXRSession } from "../../engine/engine_xr.js";
import { WebXRButtonFactory } from "../../engine/webcomponents/WebXRButtons.js";
import { Behaviour } from "../Component.js";
import { XRControllerModel } from "./controllers/XRControllerModel.js";
import { XRControllerMovement } from "./controllers/XRControllerMovement.js";
import { WebARSessionRoot } from "./WebARSessionRoot.js";
/**
 * Use the [WebXR](https://engine.needle.tools/docs/api/WebXR) component to enable VR and AR on **iOS and Android** in your scene. VisionOS support is also provided via QuickLook USDZ export.
 *
 * The WebXR component is a simple to use wrapper around the {@link NeedleXRSession} API and adds some additional features like creating buttons for AR, VR, enabling default movement behaviour ({@link XRControllerMovement}) and controller rendering ({@link XRControllerModel}), as well as handling AR placement and Quicklook USDZ export.
 *
 * ![](https://cloud.needle.tools/-/media/gcj_YoSns8FivafQRiCiOQ.gif)
 *
 *
 * @example Enable VR and AR support using code
 * ```ts
 * import { onStart, WebXR } from "@needle-tools/engine";
 * onStart(context => {
 *    const webxr = context.scene.addComponent(WebXR, { createVRButton: true, createARButton: true });
 * });
 * ```
 *
 * @example Customize VR movement
 * ```ts
 * import { onStart, WebXR } from "@needle-tools/engine";
 * onStart(context => {
 *   const webxr = context.scene.addComponent(WebXR, { createVRButton: true });
 *   const movement = webxr.setDefaultMovementEnabled(true);
 *   if (movement) {
 *    movement.enableTeleport = false; // disable teleport, only use smooth locomotion
 *    movement.smoothMovementSpeed = 2; // increase speed
 *    // NOTE: you can also disable default movement and write your own movement component (or derive and extend the {@link XRControllerMovement} class)
 *  }
 * });
 * ```
 *
 *
 * @example Start AR session with placement reticle and touch to place and adjust the scene
 * ```ts
 * import { onStart, WebXR } from "@needle-tools/engine";
 * onStart(context => {
 *  const webxr = context.scene.addComponent(WebXR);
 *  webxr.autoPlace = false; // disable auto placement, we want the user to tap to place the scene
 *  webxr.usePlacementReticle = true; // show the placement reticle to help the user find surfaces to place the scene
 *  webxr.usePlacementAdjustment = true; // allow the user to adjust the position, rotation and scale of the scene with touch after placing
 *  webxr.arScale = 2; // set the initial scale of the scene in AR. Larger values make the scene appear smaller in AR.
 *  webxr.enterAR(); // start AR session
 * });
 *
 * @summary WebXR Component for VR and AR support
 * @category XR
 * @group Components
 * @see {@link NeedleXRSession} for low-level XR API
 * @see {@link XRControllerMovement} for VR locomotion
 * @see {@link WebARSessionRoot} for AR session configuration and an AR content placement event
 * @see {@link Avatar} for networked user avatars
 * @see {@link screenshot2} for taking screenshots in XR (including AR camera feed compositing)
 * @link https://engine.needle.tools/docs/xr.html
 * @link https://engine.needle.tools/samples/?overlay=samples&tag=xr
 * @link https://engine.needle.tools/samples/collaborative-sandbox
 */
export declare class WebXR extends Behaviour {
    /**
     * When enabled, a button will be automatically added to {@link NeedleMenu} that allows users to enter VR mode.
     */
    createVRButton: boolean;
    /**
     * When enabled, a button will be automatically added to {@link NeedleMenu} that allows users to enter AR mode.
     */
    createARButton: boolean;
    /**
     * When enabled, a button to send the experience to an Oculus Quest will be shown if the current device does not support VR.
     * This helps direct users to compatible devices for optimal VR experiences.
     */
    createSendToQuestButton: boolean;
    /**
     * When enabled, a QR code will be generated and displayed on desktop devices to allow easy opening of the experience on mobile devices.
     */
    createQRCode: boolean;
    /**
     * When enabled, default movement controls will be automatically added to the scene when entering VR.
     * This includes teleportation and smooth locomotion options for VR controllers.
     */
    useDefaultControls: boolean;
    /**
     * When enabled, 3D models representing the user's VR controllers will be automatically created and rendered in the scene.
     */
    showControllerModels: boolean;
    /**
     * When enabled, 3D models representing the user's hands will be automatically created and rendered when hand tracking is available.
     */
    showHandModels: boolean;
    /**
     * When enabled, a reticle will be displayed to help place the scene in AR. The user must tap on a detected surface to position the scene.
     */
    usePlacementReticle: boolean;
    /**
     * Optional custom 3D object to use as the AR placement reticle instead of the default one.
     */
    customARPlacementReticle?: AssetReference;
    /**
     * When enabled, users can adjust the position, rotation, and scale of the AR scene with one or two fingers after initial placement.
     */
    usePlacementAdjustment: boolean;
    /**
     * Determines the scale of the user relative to the scene in AR. Larger values make the 3D content appear smaller.
     * Only applies when `usePlacementReticle` is enabled.
     */
    arScale: number;
    /**
     * When enabled, an XRAnchor will be created for the AR scene and its position will be regularly updated to match the anchor.
     * This can help with spatial persistence in AR experiences.
     * @experimental
     */
    useXRAnchor: boolean;
    /**
     * When enabled, the scene will be automatically placed as soon as a suitable surface is detected in AR,
     * without requiring the user to tap to confirm placement.
     */
    autoPlace: boolean;
    /**
     * When enabled, the AR session root center will be automatically adjusted to place the center of the scene.
     * This helps ensure the scene is properly aligned with detected surfaces.
     *
     * **Note**: This option overrides the placement of the {@link WebARSessionRoot} component if both are used.
     */
    autoCenter: boolean;
    /**
     * When enabled, a USDZExporter component will be automatically added to the scene if none is found.
     * This allows iOS and visionOS devices to view 3D content using Apple's AR QuickLook.
     */
    useQuicklookExport: boolean;
    /**
     * When enabled, the 'depth-sensing' WebXR feature will be requested to provide real-time depth occlusion.
     * Currently only supported on Oculus Quest devices.
     * @see https://developer.mozilla.org/en-US/docs/Web/API/XRDepthInformation
     * @experimental
     */
    useDepthSensing: boolean;
    /**
     * When enabled, a {@link SpatialGrabRaycaster} will be added or enabled in the scene,
     * allowing users to interact with objects at a distance in VR/AR.
     * @default true
     */
    useSpatialGrab: boolean;
    /**
     * Specifies the avatar representation that will be created when entering a WebXR session.
     * Can be a reference to a 3D model or a boolean to use the default avatar.
     */
    defaultAvatar?: AssetReference | boolean;
    private _playerSync?;
    /** these components were created by the WebXR component on session start and will be cleaned up again in session end */
    private readonly _createdComponentsInSession;
    private _usdzExporter?;
    static activeWebXRComponent: WebXR | null;
    /**
     * Initializes the WebXR component by obtaining the XR sync object for this context.
     * @internal
     */
    awake(): void;
    /**
     * Sets up the WebXR component when it's enabled. Checks for HTTPS connection,
     * sets up USDZ export if enabled, creates UI buttons, and configures avatar settings.
     * @internal
     */
    onEnable(): void;
    /**
     * Cleans up resources when the component is disabled.
     * Destroys the USDZ exporter if one was created and removes UI buttons.
     * @internal
     */
    onDisable(): void;
    /**
     * Checks if WebXR is supported and offers an appropriate session.
     * This is used to show the WebXR session joining prompt in browsers that support it.
     * @returns A Promise that resolves to true if a session was offered, false otherwise
     */
    private handleOfferSession;
    /** the currently active webxr input session */
    get session(): NeedleXRSession | null;
    /** immersive-vr or immersive-ar */
    get sessionMode(): XRSessionMode | null;
    /** While AR: this will return the currently active WebARSessionRoot component.
     * You can also query this component in your scene with `findObjectOfType(WebARSessionRoot)`
     */
    get arSessionRoot(): WebARSessionRoot | null;
    /** Call to start an WebVR session.
     *
     * This is a shorthand for `NeedleXRSession.start("immersive-vr", init, this.context)`
    */
    enterVR(init?: XRSessionInit): Promise<NeedleXRSession | null>;
    /** Call to start an WebAR session
     *
     * This is a shorthand for `NeedleXRSession.start("immersive-ar", init, this.context)`
    */
    enterAR(init?: XRSessionInit): Promise<NeedleXRSession | null>;
    /** Call to end a WebXR (AR or VR) session.
     *
     * This is a shorthand for `NeedleXRSession.stop()`
     */
    exitXR(): void;
    private _exitXRMenuButton?;
    private _previousXRState;
    private _spatialGrabRaycaster?;
    private _activeWebARSessionRoot;
    private get isActiveWebXR();
    /**
     * Called before entering a WebXR session. Sets up optional features like depth sensing, if needed.
     * @param _mode The XR session mode being requested (immersive-ar or immersive-vr)
     * @param args The XRSessionInit object that will be passed to the WebXR API
     * @internal
     */
    onBeforeXR(_mode: XRSessionMode, args: XRSessionInit): void;
    /**
     * Called when a WebXR session begins. Sets up the scene for XR by configuring controllers,
     * AR placement, and other features based on component settings.
     * @param args Event arguments containing information about the started XR session
     * @internal
     */
    onEnterXR(args: NeedleXREventArgs): Promise<void>;
    /**
     * Called every frame during an active WebXR session.
     * Updates components that depend on the current XR state.
     * @param _args Event arguments containing information about the current XR session frame
     * @internal
     */
    onUpdateXR(_args: NeedleXREventArgs): void;
    /**
     * Called when a WebXR session ends. Restores pre-session state,
     * removes temporary components, and cleans up resources.
     * @param _ Event arguments containing information about the ended XR session
     * @internal
     */
    onLeaveXR(_: NeedleXREventArgs): void;
    /** Call to enable or disable default controller behaviour */
    setDefaultMovementEnabled(enabled: boolean): XRControllerMovement | null;
    /** Call to enable or disable default controller rendering */
    setDefaultControllerRenderingEnabled(enabled: boolean): XRControllerModel | null;
    /**
     * Creates and instantiates the user's avatar representation in the WebXR session.
     * @param xr The active session
     */
    protected createLocalAvatar(xr: NeedleXRSession): Promise<void>;
    /**
     * Event handler called when a player avatar is spawned.
     * Ensures the avatar has the necessary Avatar component.
     * @param instance The spawned avatar 3D object
     */
    private onAvatarSpawned;
    /** @deprecated use {@link getButtonsFactory} or directly access {@link WebXRButtonFactory.getOrCreate} */
    getButtonsContainer(): WebXRButtonFactory;
    /**
     * Returns the WebXR button factory, creating one if it doesn't exist.
     * Use this to access and modify WebXR UI buttons.
     * @returns The WebXRButtonFactory instance
     */
    getButtonsFactory(): WebXRButtonFactory;
    /**
     * Reference to the WebXR button factory used by this component.
     */
    private _buttonFactory?;
    /**
     * Creates and sets up UI elements for WebXR interaction based on component settings
     * and device capabilities. Handles creating AR, VR, QuickLook buttons and utility buttons like QR codes.
     */
    private handleCreatingHTML;
    /**
     * Storage for UI buttons created by this component.
     */
    private readonly _buttons;
    /**
     * Adds a button to the UI with the specified priority.
     * @param button The HTML element to add
     * @param priority The button's priority value (lower numbers appear first)
     */
    private addButton;
    /**
     * Removes all buttons created by this component from the UI.
     */
    private removeButtons;
}