@needle-tools/engine 5.1.8 → 5.1.9

package/dist/needle-engine.d.ts

@@ -116,15 +116,17 @@ import { XRHandSpace } from 'three';
 
 export declare const $componentName: unique symbol;
 
+/* Excluded from this release type: $iNNlsg */
+
 export declare const $physicsKey: unique symbol;
 
+/* Excluded from this release type: _$qxlHFE */
+
 export declare class __Ignore {
 }
 
 export declare function __internalNotifyObjectDestroyed(obj: Object3D): void;
 
-/* Excluded from this release type: __sKHtRdk */
-
 /** Data describing the accessible semantics for a 3D object or component. */
 declare type AccessibilityData = {
     /** ARIA role (e.g. `"button"`, `"img"`, `"region"`). */
@@ -4119,8 +4121,9 @@ declare abstract class Component implements IComponent, EventTarget, Partial<INe
      * Use to modify session initialization parameters
      * @param mode The XR session mode being requested
      * @param args The session initialization parameters that can be modified
+     * @returns void, or a promise that is awaited before the session is requested (e.g. to load assets)
      */
-    onBeforeXR?(mode: XRSessionMode, args: XRSessionInit): void;
+    onBeforeXR?(mode: XRSessionMode, args: XRSessionInit): void | Promise<void>;
     /**
      * Called when this component joins an XR session or becomes active in a running session
      * @param args Event data for the XR session
@@ -9052,8 +9055,8 @@ export declare type INeedleXRSession = NeedleXRSession;
 export declare interface INeedleXRSessionEventReceiver extends Pick<IComponent, "destroyed"> {
     get activeAndEnabled(): boolean;
     supportsXR?(mode: XRSessionMode): boolean;
-    /** Called before requesting a XR session */
-    onBeforeXR?(mode: XRSessionMode, args: XRSessionInit): void;
+    /** Called before requesting a XR session. May return a promise that is awaited before requesting. */
+    onBeforeXR?(mode: XRSessionMode, args: XRSessionInit): void | Promise<void>;
     onEnterXR?(args: NeedleXREventArgs): void;
     onUpdateXR?(args: NeedleXREventArgs): void;
     onLeaveXR?(args: NeedleXREventArgs): void;
@@ -10455,6 +10458,8 @@ export declare interface IWatch {
     dispose(): any;
 }
 
+/* Excluded from this release type: _iXmRJVD */
+
 export declare interface IXRRig extends Pick<IComponent, "gameObject"> {
     isXRRig(): boolean;
     get isActive(): boolean;
@@ -11155,8 +11160,6 @@ declare class LowPassFilter {
     reset(value?: number): void;
 }
 
-/* Excluded from this release type: LuMYUbW */
-
 declare type MagicSkyboxName = "studio" | "blurred-skybox" | "quicklook-ar" | "quicklook";
 
 export declare class MainModule {
@@ -12956,6 +12959,11 @@ export declare class NeedleXRSession implements INeedleXRSession {
     readonly session: XRSession;
     /** XR Session Mode: AR or VR */
     readonly mode: XRSessionMode;
+    /** The framebuffer scale factor this session was started with. On this
+     * version the engine never requests a custom scale, so it is always 1 —
+     * the property exists so session-resolution handling (e.g. the App Clip
+     * canvas scaling) reads one authoritative value. */
+    readonly appliedFramebufferScaleFactor: number;
     /**
      * The XRSession interface's read-only interactionMode property describes the best space (according to the user agent) for the application to draw an interactive UI for the current session.
      * @link https://developer.mozilla.org/en-US/docs/Web/API/XRSession/interactionMode
@@ -23551,8 +23559,6 @@ export declare class OrbitControls extends Component implements ICameraControlle
          private updateDarkness;
      }
 
-     /* Excluded from this release type: _VIq */
-
      /**
       * Action to show or hide an object.
       * Use together with a {@link TapGestureTrigger} to show or hide objects when tapped or clicked.
@@ -24493,22 +24499,22 @@ export declare class OrbitControls extends Component implements ICameraControlle
           * **Tip:** Add all your markers upfront. In WebXR mode they all work simultaneously.
           * In QuickLook mode, the first (primary) marker is used.
           *
-          * @param image The marker configuration to add
-          * @param asPrimary Set to true to make this the primary marker (for QuickLook fallback)
+          * @param image The marker configuration - either a plain options object or a {@link WebXRImageTrackingModel}.
+          *              Set `asPrimary: true` to make this the primary marker (for QuickLook fallback).
           *
           * @example
           * ```ts
-          * // Super simple - works across all platforms
-          * const marker = new WebXRImageTrackingModel({
+          * // Super simple - just pass the marker url and the object to show
+          * imageTracking.addImage({
           *   url: "https://mysite.com/poster.png",
-          *   widthInMeters: 0.42, // A3 poster width
-          *   object: cool3DModel
+          *   object: cool3DModel,
+          *   widthInMeters: 0.42, // A3 poster width (optional, defaults to 0.25)
           * });
-          * imageTracking.addImage(marker);
           * // That's it! Needle does the rest.
           * ```
           */
-         addImage(image: WebXRImageTrackingModel, asPrimary?: boolean): void;
+         addImage(options: WebXRImageTrackingOptions): void;
+         addImage(model: WebXRImageTrackingModel): void;
          /**
           * Your list of markers to track. Add as many as you need!
           *
@@ -24544,9 +24550,13 @@ export declare class OrbitControls extends Component implements ICameraControlle
          /* Excluded from this release type: awake */
          /* Excluded from this release type: onEnable */
          /* Excluded from this release type: onDisable */
+         private onInvalidImageSizeDetected;
          private onBeforeUSDZExport;
          /* Excluded from this release type: onBeforeXR */
          /* Excluded from this release type: onEnterXR */
+         /** Late-registers this component's marker images into an already running session
+          * via the NeedleGo polyfill's runtime hook. See {@link onEnterXR}. */
+         private registerImagesWithRunningSession;
          /* Excluded from this release type: onLeaveXR */
          private readonly imageToObjectMap;
          private readonly currentImages;
@@ -24598,14 +24608,7 @@ export declare class OrbitControls extends Component implements ICameraControlle
           * @param params.imageDoesNotMove Enable for static markers (floor/wall mounted) to improve tracking stability
           * @param params.hideWhenTrackingIsLost If true, hides the object when tracking is lost; if false, leaves it at the last known position
           */
-         constructor(params: {
-             url: string;
-             widthInMeters: number; /** Object to track */
-             object: AssetReference | Object3D;
-             createObjectInstance?: boolean;
-             imageDoesNotMove?: boolean;
-             hideWhenTrackingIsLost?: boolean;
-         });
+         constructor(params: Omit<WebXRImageTrackingOptions, "asPrimary">);
          /**
           * URL to the marker image to track.
           * **Important:** Use images with high contrast and unique features to improve tracking quality.
@@ -24680,6 +24683,27 @@ export declare class OrbitControls extends Component implements ICameraControlle
          getNameFromUrl(): string | null;
      }
 
+     /**
+      * Options for adding a trackable image marker via {@link WebXRImageTracking.addImage}.
+      * A convenience shape that also accepts a plain {@link Object3D} for `object`.
+      */
+     export declare interface WebXRImageTrackingOptions {
+         /** URL to the marker image to track. Use high-contrast images with unique features for reliable tracking. */
+         url?: string;
+         /** The 3D object (or {@link AssetReference}) to display when the marker is detected. */
+         object: AssetReference | Object3D;
+         /** Physical width of the printed marker in meters. Must match the real marker size. @default 0.25 */
+         widthInMeters?: number;
+         /** Create a new instance of the object for each detection. @default false */
+         createObjectInstance?: boolean;
+         /** Enable for static markers (walls/floor) to improve tracking stability. @default false */
+         imageDoesNotMove?: boolean;
+         /** Hide the object when tracking is lost. @default true */
+         hideWhenTrackingIsLost?: boolean;
+         /** Make this the primary marker (used in QuickLook fallback mode). @default false */
+         asPrimary?: boolean;
+     }
+
      /**
       * [WebXRPlaneTracking](https://engine.needle.tools/docs/api/WebXRPlaneTracking) tracks planes and meshes in the real world when in immersive-ar (e.g. on Oculus Quest).
       * @category XR