@wonderlandengine/ar-provider-zappar 1.1.0 → 1.2.0

package/dist/src/face-tracking-mode-zappar.js

@@ -123,7 +123,8 @@ export class FaceTracking_Zappar extends TrackingMode {
         const mirrorPoses = pipeline.cameraFrameUserFacing();
         const viewNear = this._view?.near;
         const viewFar = this._view?.far;
-        const projectionMatrix = Zappar.projectionMatrixFromCameraModel(pipeline.cameraModel(), this.component.engine.canvas.width, this.component.engine.canvas.height, typeof viewNear === 'number' ? viewNear : undefined, typeof viewFar === 'number' ? viewFar : undefined);
+        const [cameraDataWidth, cameraDataHeight] = pipeline.cameraDataSize();
+        const projectionMatrix = Zappar.projectionMatrixFromCameraModelAndSize(pipeline.cameraModel(), cameraDataWidth, cameraDataHeight, this.component.engine.canvas.width, this.component.engine.canvas.height, typeof viewNear === 'number' ? viewNear : undefined, typeof viewFar === 'number' ? viewFar : undefined);
         if (this._view) {
             this._setProjectionMatrixWithEngineRemap(projectionMatrix);
         }
@@ -305,8 +306,7 @@ export class FaceTracking_Zappar extends TrackingMode {
             }
             return;
         }
-        if (typeof engineAny.wasm?._wl_view_component_remapProjectionMatrix ===
-            'function') {
+        if (typeof engineAny.wasm?._wl_view_component_remapProjectionMatrix === 'function') {
             const ndcDepthIsZeroToOne = false;
             engineAny.wasm._wl_view_component_remapProjectionMatrix(view._id, engineAny.isReverseZEnabled, ndcDepthIsZeroToOne);
             if (debugWindow.__WLE_ZAPPAR_DEBUG__) {

package/dist/src/hit-test-location-zappar.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Hit-test reticle backed by Zappar plane anchors from `WorldTracker`
+ * (requires `@zappar/zappar >= 4.x`).
+ *
+ * Each frame the component casts a ray from the centre of `camera` into the
+ * set of planes detected by {@link ZapparProvider}'s `WorldTracker` and moves
+ * the owning object to the closest intersection point.  A {@link MeshComponent}
+ * on the same object is shown while a valid hit is found and hidden otherwise.
+ *
+ * This is the Zappar equivalent of:
+ * - `hit-test-location-root`  (WebXR Device API hit-test)
+ * - `hit-test-location-xr8`   (8th Wall SLAM + XY-plane intersection)
+ *
+ * **Setup**
+ * 1. Attach this component to the reticle object (which should have a
+ *    {@link MeshComponent} for visual feedback).
+ * 2. Set the `camera` property to the scene object that carries
+ *    {@link ARSLAMCamera}.
+ * 3. The `SpawnMeshOnReticle` component works alongside this component –
+ *    tapping the screen (or selecting on WebXR) will spawn content at this
+ *    object's position.
+ *
+ * **Coordinate spaces**
+ * Zappar plane poses are expressed in Zappar world space.  The WLE camera
+ * object's transform is driven directly from the Zappar camera pose matrix
+ * (via `WorldTracking_Zappar`), so `camera.getPositionWorld()` and
+ * `camera.getForwardWorld()` are already in the same coordinate space as the
+ * plane poses.  No additional transform is required.
+ */
+import { Component, Object as WLEObject } from '@wonderlandengine/api';
+export declare class HitTestLocationZappar extends Component {
+    static TypeName: string;
+    /** The scene object that carries the {@link ARSLAMCamera} component. */
+    camera: WLEObject;
+    private _provider;
+    private _mesh;
+    private readonly _camPos;
+    private readonly _camFwd;
+    private readonly _planeNormal;
+    private readonly _planeOrigin;
+    private readonly _toOrigin;
+    private readonly _hitPoint;
+    start(): void;
+    update(): void;
+    private readonly _onSessionStart;
+    private readonly _onSessionEnd;
+}

package/dist/src/hit-test-location-zappar.js

@@ -0,0 +1,155 @@
+/**
+ * Hit-test reticle backed by Zappar plane anchors from `WorldTracker`
+ * (requires `@zappar/zappar >= 4.x`).
+ *
+ * Each frame the component casts a ray from the centre of `camera` into the
+ * set of planes detected by {@link ZapparProvider}'s `WorldTracker` and moves
+ * the owning object to the closest intersection point.  A {@link MeshComponent}
+ * on the same object is shown while a valid hit is found and hidden otherwise.
+ *
+ * This is the Zappar equivalent of:
+ * - `hit-test-location-root`  (WebXR Device API hit-test)
+ * - `hit-test-location-xr8`   (8th Wall SLAM + XY-plane intersection)
+ *
+ * **Setup**
+ * 1. Attach this component to the reticle object (which should have a
+ *    {@link MeshComponent} for visual feedback).
+ * 2. Set the `camera` property to the scene object that carries
+ *    {@link ARSLAMCamera}.
+ * 3. The `SpawnMeshOnReticle` component works alongside this component –
+ *    tapping the screen (or selecting on WebXR) will spawn content at this
+ *    object's position.
+ *
+ * **Coordinate spaces**
+ * Zappar plane poses are expressed in Zappar world space.  The WLE camera
+ * object's transform is driven directly from the Zappar camera pose matrix
+ * (via `WorldTracking_Zappar`), so `camera.getPositionWorld()` and
+ * `camera.getForwardWorld()` are already in the same coordinate space as the
+ * plane poses.  No additional transform is required.
+ */
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { Component, MeshComponent } from '@wonderlandengine/api';
+import { property } from '@wonderlandengine/api/decorators.js';
+import { vec3 } from 'gl-matrix';
+import { ARSession } from '@wonderlandengine/ar-tracking';
+import { ZapparProvider } from './zappar-provider.js';
+export class HitTestLocationZappar extends Component {
+    static TypeName = 'hit-test-location-zappar';
+    /** The scene object that carries the {@link ARSLAMCamera} component. */
+    camera;
+    _provider = null;
+    _mesh = null;
+    // Pre-allocated scratch buffers to avoid GC pressure in the update loop.
+    _camPos = new Float32Array(3);
+    _camFwd = new Float32Array(3);
+    _planeNormal = vec3.create();
+    _planeOrigin = vec3.create();
+    _toOrigin = vec3.create();
+    _hitPoint = vec3.create();
+    start() {
+        const arSession = ARSession.getSessionForEngine(this.engine);
+        arSession.onSessionStart.add(this._onSessionStart);
+        arSession.onSessionEnd.add(this._onSessionEnd);
+        this._mesh = this.object.getComponent(MeshComponent) ?? null;
+        if (this._mesh)
+            this._mesh.active = false;
+        // Deactivate update loop until a valid Zappar session starts.
+        this.active = false;
+    }
+    update() {
+        const provider = this._provider;
+        if (!provider)
+            return;
+        if (!this.camera) {
+            console.warn(`[${this.type}] 'camera' property is not set.`);
+            return;
+        }
+        const worldTracker = provider.worldTracker;
+        if (!worldTracker || worldTracker.planes.size === 0) {
+            if (this._mesh)
+                this._mesh.active = false;
+            return;
+        }
+        const cameraPose = provider.slamCameraPoseMatrix;
+        if (!cameraPose) {
+            if (this._mesh)
+                this._mesh.active = false;
+            return;
+        }
+        // -------------------------------------------------------------------
+        // Ray definition in WLE / Zappar world space.
+        // The camera's world transform has already been set from the Zappar
+        // camera pose so these values are directly comparable to plane poses.
+        // -------------------------------------------------------------------
+        this.camera.getPositionWorld(this._camPos);
+        this.camera.getForwardWorld(this._camFwd);
+        let closestT = Infinity;
+        let hitFound = false;
+        for (const plane of worldTracker.planes.values()) {
+            // plane.pose() returns a column-major 4×4 matrix in Zappar world space.
+            const planeMat = plane.pose(cameraPose);
+            // Column 1 = local Y-axis = surface normal for horizontal planes.
+            this._planeNormal[0] = planeMat[4];
+            this._planeNormal[1] = planeMat[5];
+            this._planeNormal[2] = planeMat[6];
+            // Column 3 = translation = a point on the plane.
+            this._planeOrigin[0] = planeMat[12];
+            this._planeOrigin[1] = planeMat[13];
+            this._planeOrigin[2] = planeMat[14];
+            // Ray–plane intersection: t = dot(planeOrigin - camPos, N) / dot(D, N)
+            const denom = vec3.dot(this._camFwd, this._planeNormal);
+            // Skip planes that are nearly parallel to the ray.
+            if (Math.abs(denom) < 1e-6)
+                continue;
+            vec3.sub(this._toOrigin, this._planeOrigin, this._camPos);
+            const t = vec3.dot(this._toOrigin, this._planeNormal) / denom;
+            // Only accept intersections in front of the camera and closer than
+            // the best so far.
+            if (t > 1e-3 && t < closestT) {
+                closestT = t;
+                vec3.scaleAndAdd(this._hitPoint, this._camPos, this._camFwd, t);
+                hitFound = true;
+            }
+        }
+        if (hitFound) {
+            this.object.setPositionWorld(this._hitPoint);
+            if (this._mesh)
+                this._mesh.active = true;
+        }
+        else {
+            if (this._mesh)
+                this._mesh.active = false;
+        }
+    }
+    _onSessionStart = (provider) => {
+        if (!(provider instanceof ZapparProvider))
+            return;
+        this._provider = provider;
+        const wt = provider.enableWorldTracker();
+        if (!wt) {
+            // @zappar/zappar < 4.x or WorldTracker unavailable – degrade
+            // gracefully rather than throwing.
+            console.warn(`[${this.type}] Zappar WorldTracker (plane anchors) is not` +
+                ' available in the installed SDK version. Upgrade' +
+                ' @zappar/zappar to >= 4.x to enable plane-based hit tests.');
+            return;
+        }
+        this.active = true;
+    };
+    _onSessionEnd = (provider) => {
+        if (provider !== this._provider)
+            return;
+        this._provider = null;
+        this.active = false;
+        if (this._mesh)
+            this._mesh.active = false;
+    };
+}
+__decorate([
+    property.object()
+], HitTestLocationZappar.prototype, "camera", void 0);

package/dist/src/image-tracking-mode-zappar.d.ts

@@ -20,6 +20,10 @@ export declare class ImageTracking_Zappar extends TrackingMode implements ImageT
     readonly onImageFound: Emitter<[event: ImageTrackedEvent]>;
     readonly onImageUpdate: Emitter<[event: ImageTrackedEvent]>;
     readonly onImageLost: Emitter<[event: ImageTrackedEvent]>;
+    registerTarget(source: string | ArrayBuffer, options: {
+        name: string;
+        physicalWidthInMeters?: number;
+    }): Promise<void>;
     init(): void;
     startSession(): void;
     endSession(): void;

package/dist/src/image-tracking-mode-zappar.js

@@ -21,6 +21,9 @@ export class ImageTracking_Zappar extends TrackingMode {
     onImageFound = new Emitter();
     onImageUpdate = new Emitter();
     onImageLost = new Emitter();
+    async registerTarget(source, options) {
+        await this.provider.registerImageTarget(source, options);
+    }
     init() {
         this._view = this.component.object.getComponent('view') ?? undefined;
         const provider = this.provider;
@@ -50,7 +53,8 @@ export class ImageTracking_Zappar extends TrackingMode {
         const pipeline = provider.getPipeline();
         const viewNear = this._view?.near;
         const viewFar = this._view?.far;
-        const projectionMatrix = Zappar.projectionMatrixFromCameraModel(pipeline.cameraModel(), this.component.engine.canvas.width, this.component.engine.canvas.height, typeof viewNear === 'number' ? viewNear : undefined, typeof viewFar === 'number' ? viewFar : undefined);
+        const [cameraDataWidth, cameraDataHeight] = pipeline.cameraDataSize();
+        const projectionMatrix = Zappar.projectionMatrixFromCameraModelAndSize(pipeline.cameraModel(), cameraDataWidth, cameraDataHeight, this.component.engine.canvas.width, this.component.engine.canvas.height, typeof viewNear === 'number' ? viewNear : undefined, typeof viewFar === 'number' ? viewFar : undefined);
         if (this._view) {
             this._setProjectionMatrixWithEngineRemap(projectionMatrix);
         }

package/dist/src/world-tracking-mode-zappar.d.ts

@@ -1,6 +1,6 @@
 /// <reference path="../../src/types/global.d.ts" />
 import { Component } from '@wonderlandengine/api';
-import { TrackingMode } from '@wonderlandengine/ar-tracking';
+import { HitTestResult, TrackingMode } from '@wonderlandengine/ar-tracking';
 import { ZapparProvider } from './zappar-provider.js';
 /**
  * SLAM tracking implementation backed by Zappar.
@@ -14,4 +14,10 @@ export declare class WorldTracking_Zappar extends TrackingMode {
     getCameraTransformWorld(): ArrayLike<number> | null;
     getCameraProjectionMatrix(out: Float32Array): boolean;
     update(): void;
+    setupHitTest(): Promise<void>;
+    /**
+     * Cast a ray from the camera through the screen centre and return the closest
+     * intersection with any of the Zappar-detected plane anchors.
+     */
+    getHitTestResult(): HitTestResult | null;
 }

package/dist/src/world-tracking-mode-zappar.js

@@ -45,4 +45,54 @@ export class WorldTracking_Zappar extends TrackingMode {
         // Wonderland stores transforms as dual quaternions (8 floats): [rotation quat, translation dual part].
         quat2.fromMat4(this._cameraTransform, pose);
     }
+    async setupHitTest() {
+        const provider = this.provider;
+        const tracker = provider.enableWorldTracker();
+        if (!tracker) {
+            console.warn('[WorldTracking_Zappar] World tracker (plane detection) is not available. ' +
+                'Ensure @zappar/zappar >= 4.x is installed.');
+        }
+    }
+    /**
+     * Cast a ray from the camera through the screen centre and return the closest
+     * intersection with any of the Zappar-detected plane anchors.
+     */
+    getHitTestResult() {
+        const provider = this.provider;
+        const worldTracker = provider.worldTracker;
+        if (!worldTracker)
+            return null;
+        const cameraPose = provider.slamCameraPoseMatrix;
+        if (!cameraPose)
+            return null;
+        // Camera position and forward vector in world space.
+        const cam = this.component.object;
+        const pos = cam.getPositionWorld(new Array(3));
+        const fwd = cam.getForwardWorld(new Array(3));
+        let closestT = Infinity;
+        let hit = null;
+        for (const plane of worldTracker.planes.values()) {
+            // pose() returns a column-major 4×4 matrix.
+            // Column 1 (elements [4,5,6]) = plane normal; column 3 (elements [12,13,14]) = plane origin.
+            const m = plane.pose(cameraPose);
+            const nx = m[4], ny = m[5], nz = m[6];
+            const ox = m[12], oy = m[13], oz = m[14];
+            const denom = fwd[0] * nx + fwd[1] * ny + fwd[2] * nz;
+            // Skip planes nearly parallel to the ray.
+            if (Math.abs(denom) < 1e-6)
+                continue;
+            const t = ((ox - pos[0]) * nx + (oy - pos[1]) * ny + (oz - pos[2]) * nz) / denom;
+            if (t <= 0 || t >= closestT)
+                continue;
+            closestT = t;
+            hit = {
+                position: {
+                    x: pos[0] + fwd[0] * t,
+                    y: pos[1] + fwd[1] * t,
+                    z: pos[2] + fwd[2] * t,
+                },
+            };
+        }
+        return hit;
+    }
 }

package/dist/src/zappar-provider.d.ts

@@ -6,6 +6,33 @@ import { ARProvider, ARSession, ITrackingMode, ImageScanningEvent, TrackingType
 import { loadZappar } from './zappar-module.js';
 import type { FaceMesh, FaceTracker, ImageTracker, Pipeline } from '@zappar/zappar';
 type ZapparImageTargetType = 'flat' | 'cylindrical' | 'conical';
+/** A single detected horizontal plane produced by {@link ZapparWorldTracker}. */
+export interface ZapparPlaneAnchor {
+    /** Pose matrix of this plane in world space. */
+    pose(cameraPose: Float32Array): Float32Array;
+    /** Ordered 2-D boundary vertices on the plane surface. */
+    readonly polygon: ReadonlyArray<readonly [number, number]>;
+    /** Increments each time `polygon` is updated. */
+    readonly polygonVersion: number;
+}
+/**
+ * Minimal interface for the Zappar `WorldTracker` class available in
+ * `@zappar/zappar >= 4.x`.  Only the API surface used by this package is
+ * declared here.
+ */
+export interface ZapparWorldTracker {
+    enabled: boolean;
+    horizontalPlaneDetectionEnabled: boolean;
+    verticalPlaneDetectionEnabled: boolean;
+    /** Map of all currently detected plane anchors keyed by their ID. */
+    readonly planes: ReadonlyMap<string, ZapparPlaneAnchor>;
+    readonly worldAnchor: {
+        pose(cameraPose: Float32Array): Float32Array;
+    };
+    readonly groundAnchor: {
+        pose(cameraPose: Float32Array): Float32Array;
+    };
+}
 export interface ZapparImageTargetOptions {
     name: string;
     type?: ZapparImageTargetType;
@@ -41,9 +68,19 @@ export declare class ZapparProvider extends ARProvider {
     private _cameraSourceUserFacing;
     private _imageTargetDescriptors;
     private readonly _imageTargetsChanged;
+    private _worldTracker;
+    /** Set to `true` when a component requests world-tracker before the session starts. */
+    private _worldTrackerRequested;
     private cameraStarted;
     private hasInitializedAnchor;
     private _anchorWarmupFramesRemaining;
+    /**
+     * When `true`, {@link updateTracking} keeps calling
+     * `setAnchorPoseFromCameraOffset` every frame so the world anchor
+     * continuously follows the camera centre. Set via
+     * {@link startUserPlacement}; cleared by {@link placeInstantAnchor}.
+     */
+    private _userPlacementMode;
     private preRenderRegistered;
     private _slamStateValid;
     private readonly _slamProjectionMatrix;
@@ -104,6 +141,29 @@ export declare class ZapparProvider extends ARProvider {
     getImageScanningEvent(): ImageScanningEvent;
     getImageTargetDescriptors(): ReadonlyArray<ZapparImageTargetDescriptor>;
     getImageTargetDescriptor(index: number): ZapparImageTargetDescriptor | undefined;
+    /**
+     * Access the active {@link ZapparWorldTracker} instance, or `null` when
+     * plane tracking has not been requested or is unavailable.
+     *
+     * The instance is only non-null once {@link enableWorldTracker} has been
+     * called **and** an AR session is running.
+     */
+    get worldTracker(): ZapparWorldTracker | null;
+    /**
+     * Opt in to Zappar plane tracking via the `WorldTracker` API introduced in
+     * `@zappar/zappar >= 4.x`.
+     *
+     * Call this once (e.g. from a component's `start()` hook) before or after
+     * a session starts.  If the installed SDK does not expose `WorldTracker`
+     * (i.e. < 4.x) a warning is logged and the method returns `null`.
+     *
+     * The tracker is disabled again when the session ends and re-enabled on
+     * the next `startSession()` call.
+     *
+     * @returns The {@link ZapparWorldTracker} instance, or `null` on failure.
+     */
+    enableWorldTracker(): ZapparWorldTracker | null;
+    private _createWorldTracker;
     private ensureCameraRunning;
     private onVisibilityChange;
     private onPreRender;
@@ -114,6 +174,26 @@ export declare class ZapparProvider extends ARProvider {
     /** Latest anchor pose matrix (valid only if {@link hasSlamTrackingState} is true). */
     get slamAnchorPoseMatrix(): Readonly<mat4> | null;
     get hasSlamTrackingState(): boolean;
+    /**
+     * `true` while the instant world anchor is being continuously repositioned
+     * in front of the camera (either during warmup or during user-placement
+     * mode). `false` once the anchor has been locked.
+     */
+    get isPlacingInstantAnchor(): boolean;
+    /**
+     * Enter user-placement mode: the instant world anchor tracks 5 m in front
+     * of the camera every frame until {@link placeInstantAnchor} is called.
+     *
+     * Typically called by a placement-UI component immediately after session
+     * start so the user can choose where to lock the world origin.
+     */
+    startUserPlacement(): void;
+    /**
+     * Lock the instant world anchor at its current position and exit placement
+     * mode. After this call {@link isPlacingInstantAnchor} returns `false` and
+     * the anchor no longer follows the camera.
+     */
+    placeInstantAnchor(): void;
     get slamFrameNumber(): number;
     private bindVideoTextureForSkyMaterial;
     updateTracking(): void;

package/dist/src/zappar-provider.js

@@ -28,9 +28,19 @@ export class ZapparProvider extends ARProvider {
     _cameraSourceUserFacing = null;
     _imageTargetDescriptors = [];
     _imageTargetsChanged = new Emitter();
+    _worldTracker = null;
+    /** Set to `true` when a component requests world-tracker before the session starts. */
+    _worldTrackerRequested = false;
     cameraStarted = false;
     hasInitializedAnchor = false;
     _anchorWarmupFramesRemaining = 0;
+    /**
+     * When `true`, {@link updateTracking} keeps calling
+     * `setAnchorPoseFromCameraOffset` every frame so the world anchor
+     * continuously follows the camera centre. Set via
+     * {@link startUserPlacement}; cleared by {@link placeInstantAnchor}.
+     */
+    _userPlacementMode = false;
     preRenderRegistered = false;
     _slamStateValid = false;
     _slamProjectionMatrix = new Float32Array(16);
@@ -113,6 +123,7 @@ export class ZapparProvider extends ARProvider {
         this.ensurePipeline();
         this.ensureCameraSourcePreference();
         await this.ensureCameraRunning();
+        this.ensurePreRenderRegistered();
         this.startZapparDebugLogging();
         if (this._faceTracker) {
             this._faceTracker.enabled = true;
@@ -126,6 +137,15 @@ export class ZapparProvider extends ARProvider {
         if (this.instantTracker) {
             this.instantTracker.enabled = true;
         }
+        // Create the WorldTracker if it was requested before the session started.
+        if (this._worldTrackerRequested && !this._worldTracker) {
+            this._createWorldTracker();
+            this._worldTrackerRequested = false;
+        }
+        else if (this._worldTracker) {
+            // Re-enable a pre-existing WorldTracker from a previous session.
+            this._worldTracker.enabled = true;
+        }
     }
     ensurePreRenderRegistered() {
         if (!this.preRenderRegistered) {
@@ -205,7 +225,7 @@ export class ZapparProvider extends ARProvider {
             if (debugWorker) {
                 console.log('[ZapparProvider] Creating CV worker:', workerUrl);
             }
-            const worker = new Worker(workerUrl);
+            const worker = new Worker(workerUrl, { type: 'module' });
             // Keep a reference for debugging / inspection.
             ZapparProvider._cvWorker = worker;
             if (typeof window !== 'undefined') {
@@ -284,7 +304,6 @@ export class ZapparProvider extends ARProvider {
     }
     ensurePipeline() {
         if (this.pipeline) {
-            this.ensurePreRenderRegistered();
             return;
         }
         if (!this._zappar) {
@@ -312,7 +331,6 @@ export class ZapparProvider extends ARProvider {
         }
         this.ensureCameraSourcePreference();
         this.instantTracker = new Zappar.InstantWorldTracker(pipeline);
-        this.ensurePreRenderRegistered();
     }
     ensureCameraSourcePreference() {
         if (!this.pipeline || !this._zappar) {
@@ -400,6 +418,12 @@ export class ZapparProvider extends ARProvider {
         if (!options.name) {
             throw new Error('Image target registration requires a name.');
         }
+        // Deduplicate: if a descriptor with the same name is already registered,
+        // skip loading to avoid double-loading the same .zpt file when multiple
+        // scene components share the same imageId target.
+        if (this._imageTargetDescriptors.some((d) => d.name === options.name)) {
+            return;
+        }
         // Allow registering targets before an AR session starts.
         // This is useful so image targets are known for ImageScanningEvent
         // and so apps can prefetch/prepare targets without requesting camera access.
@@ -479,6 +503,60 @@ export class ZapparProvider extends ARProvider {
     getImageTargetDescriptor(index) {
         return this._imageTargetDescriptors[index];
     }
+    // -----------------------------------------------------------------------
+    // World tracking / plane anchors (Zappar SDK >= 4.x)
+    // -----------------------------------------------------------------------
+    /**
+     * Access the active {@link ZapparWorldTracker} instance, or `null` when
+     * plane tracking has not been requested or is unavailable.
+     *
+     * The instance is only non-null once {@link enableWorldTracker} has been
+     * called **and** an AR session is running.
+     */
+    get worldTracker() {
+        return this._worldTracker;
+    }
+    /**
+     * Opt in to Zappar plane tracking via the `WorldTracker` API introduced in
+     * `@zappar/zappar >= 4.x`.
+     *
+     * Call this once (e.g. from a component's `start()` hook) before or after
+     * a session starts.  If the installed SDK does not expose `WorldTracker`
+     * (i.e. < 4.x) a warning is logged and the method returns `null`.
+     *
+     * The tracker is disabled again when the session ends and re-enabled on
+     * the next `startSession()` call.
+     *
+     * @returns The {@link ZapparWorldTracker} instance, or `null` on failure.
+     */
+    enableWorldTracker() {
+        if (this._worldTracker) {
+            this._worldTracker.enabled = true;
+            return this._worldTracker;
+        }
+        if (this.pipeline && this._zappar) {
+            return this._createWorldTracker();
+        }
+        // Session not yet started – remember the request.
+        this._worldTrackerRequested = true;
+        return null;
+    }
+    _createWorldTracker() {
+        if (!this.pipeline || !this._zappar)
+            return null;
+        // WorldTracker is only available in @zappar/zappar >= 4.x.
+        const ZapparAny = this._zappar;
+        if (typeof ZapparAny['WorldTracker'] !== 'function') {
+            console.warn('[ZapparProvider] WorldTracker not available in the installed' +
+                ' version of @zappar/zappar. Upgrade to >= 4.x to enable plane tracking.');
+            return null;
+        }
+        const TrackerCtor = ZapparAny['WorldTracker'];
+        this._worldTracker = new TrackerCtor(this.pipeline);
+        this._worldTracker.enabled = true;
+        this._worldTracker.horizontalPlaneDetectionEnabled = true;
+        return this._worldTracker;
+    }
     async ensureCameraRunning() {
         if (!this.cameraSource || this.cameraStarted)
             return;
@@ -572,6 +650,33 @@ export class ZapparProvider extends ARProvider {
     get hasSlamTrackingState() {
         return this._slamStateValid;
     }
+    /**
+     * `true` while the instant world anchor is being continuously repositioned
+     * in front of the camera (either during warmup or during user-placement
+     * mode). `false` once the anchor has been locked.
+     */
+    get isPlacingInstantAnchor() {
+        return this._userPlacementMode || this._anchorWarmupFramesRemaining > 0;
+    }
+    /**
+     * Enter user-placement mode: the instant world anchor tracks 5 m in front
+     * of the camera every frame until {@link placeInstantAnchor} is called.
+     *
+     * Typically called by a placement-UI component immediately after session
+     * start so the user can choose where to lock the world origin.
+     */
+    startUserPlacement() {
+        this._userPlacementMode = true;
+    }
+    /**
+     * Lock the instant world anchor at its current position and exit placement
+     * mode. After this call {@link isPlacingInstantAnchor} returns `false` and
+     * the anchor no longer follows the camera.
+     */
+    placeInstantAnchor() {
+        this._userPlacementMode = false;
+        this._anchorWarmupFramesRemaining = 0;
+    }
     get slamFrameNumber() {
         return this._slamFrameNumber;
     }
@@ -660,13 +765,14 @@ export class ZapparProvider extends ARProvider {
         // Let Zappar continuously refine a stable surface point briefly, then lock.
         // If we lock immediately at startup, we can end up with effectively 3DoF behavior.
         // If we *never* lock, the origin follows the camera and the camera appears frozen.
-        if (this._anchorWarmupFramesRemaining > 0) {
-            this.instantTracker.setAnchorPoseFromCameraOffset(0, 0, -5);
-            this._anchorWarmupFramesRemaining--;
-            this.hasInitializedAnchor = true;
-        }
-        else if (!this.hasInitializedAnchor) {
+        // _userPlacementMode keeps the anchor updating beyond the warmup window until the
+        // user explicitly confirms placement via placeInstantAnchor().
+        if (this._anchorWarmupFramesRemaining > 0 ||
+            this._userPlacementMode ||
+            !this.hasInitializedAnchor) {
             this.instantTracker.setAnchorPoseFromCameraOffset(0, 0, -5);
+            if (this._anchorWarmupFramesRemaining > 0)
+                this._anchorWarmupFramesRemaining--;
             this.hasInitializedAnchor = true;
         }
         // Use the active view's near/far when available; incorrect near/far can make tracking feel
@@ -676,7 +782,8 @@ export class ZapparProvider extends ARProvider {
             return;
         const zNear = activeView.near;
         const zFar = activeView.far;
-        const projectionMatrix = Zappar.projectionMatrixFromCameraModel(this.pipeline.cameraModel(), this.engine.canvas.width, this.engine.canvas.height, zNear, zFar);
+        const [cameraDataWidth, cameraDataHeight] = this.pipeline.cameraDataSize();
+        const projectionMatrix = Zappar.projectionMatrixFromCameraModelAndSize(this.pipeline.cameraModel(), cameraDataWidth, cameraDataHeight, this.engine.canvas.width, this.engine.canvas.height, zNear, zFar);
         let origin;
         let cameraPoseMatrix;
         // Match zappar-threejs `CameraPoseMode` behavior.
@@ -829,6 +936,9 @@ export class ZapparProvider extends ARProvider {
         if (this.instantTracker) {
             this.instantTracker.enabled = false;
         }
+        if (this._worldTracker) {
+            this._worldTracker.enabled = false;
+        }
         if (this._xrSession) {
             try {
                 await this._xrSession.end();
@@ -840,6 +950,7 @@ export class ZapparProvider extends ARProvider {
         }
         this.hasInitializedAnchor = false;
         this._anchorWarmupFramesRemaining = 0;
+        this._userPlacementMode = false;
         this._slamStateValid = false;
         this.onSessionEnd.notify(this);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@wonderlandengine/ar-provider-zappar",
-    "version": "1.1.0",
+    "version": "1.2.0",
     "description": "Wonderland Engine AR tracking provider based on Zappar",
     "main": "dist/index.js",
     "type": "module",
@@ -37,11 +37,11 @@
     },
     "peerDependencies": {
         "@wonderlandengine/api": "^1.0.0",
-        "@wonderlandengine/ar-tracking": "^1.0.0",
+        "@wonderlandengine/ar-tracking": "^1.2.0",
         "@wonderlandengine/components": "^1.0.0"
     },
     "dependencies": {
-        "@zappar/zappar": "^2.2.7",
+        "@zappar/zappar": "^4.3.0",
         "gl-matrix": "^3.4.3"
     }
 }

package/scripts/postinstall.mjs

@@ -2,6 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import {createRequire} from 'node:module';
 import {fileURLToPath} from 'node:url';
+import {execSync} from 'node:child_process';
 
 const require = createRequire(import.meta.url);
 const __filename = fileURLToPath(import.meta.url);
@@ -108,51 +109,111 @@ function main() {
     const projectRoot = resolveProjectRoot();
     const outDir = path.resolve(projectRoot, 'static', 'zappar-cv');
 
-    const workerSource =
-        findFirstFile(umdDir, (name) => name === 'zappar.worker.js') ??
-        findFirstFile(umdDir, (name) => name === 'zappar-cv.worker.js') ??
-        findFirstFile(zapparRoot, (name) => name === 'zappar.worker.js') ??
-        findFirstFile(zapparRoot, (name) => name === 'zappar-cv.worker.js') ??
-        null;
-
-    if (!workerSource) {
-        warn('Could not locate Zappar worker under', umdDir);
-        warn('Zappar root:', zapparRoot);
-        return;
-    }
+    // -------------------------------------------------------------------------
+    // Detect package layout.
+    // @zappar/zappar < 4.x ships a pre-bundled UMD worker in `umd/`.
+    // @zappar/zappar >= 4.x ships only unbundled ESM; the worker must be bundled
+    // from `@zappar/zappar-cv/lib/worker.js` using esbuild.
+    // -------------------------------------------------------------------------
+    const isLegacyLayout = fs.existsSync(umdDir);
+
+    if (isLegacyLayout) {
+        // ---- Legacy (< 4.x) path ----
+        const workerSource =
+            findFirstFile(umdDir, (name) => name === 'zappar.worker.js') ??
+            findFirstFile(umdDir, (name) => name === 'zappar-cv.worker.js') ??
+            findFirstFile(zapparRoot, (name) => name === 'zappar.worker.js') ??
+            findFirstFile(zapparRoot, (name) => name === 'zappar-cv.worker.js') ??
+            null;
+
+        if (!workerSource) {
+            warn('Could not locate Zappar worker under', umdDir);
+            warn('Zappar root:', zapparRoot);
+            return;
+        }
 
-    const wasmCandidates = listFiles(umdDir)
-        .filter((e) => e.isFile() && e.name.endsWith('.wasm'))
-        .map((e) => path.join(umdDir, e.name));
+        const wasmCandidates = listFiles(umdDir)
+            .filter((e) => e.isFile() && e.name.endsWith('.wasm'))
+            .map((e) => path.join(umdDir, e.name));
 
-    let wasmSource = wasmCandidates.length === 1 ? wasmCandidates[0] : null;
-    wasmSource = wasmSource ?? findWasmFromWorker(workerSource, umdDir);
-    wasmSource = wasmSource ?? (wasmCandidates.length > 0 ? wasmCandidates[0] : null);
+        let wasmSource = wasmCandidates.length === 1 ? wasmCandidates[0] : null;
+        wasmSource = wasmSource ?? findWasmFromWorker(workerSource, umdDir);
+        wasmSource = wasmSource ?? (wasmCandidates.length > 0 ? wasmCandidates[0] : null);
 
-    if (!wasmSource) {
-        warn('Could not locate Zappar wasm under', umdDir);
-        warn('Worker found at:', workerSource);
-        return;
-    }
+        if (!wasmSource) {
+            warn('Could not locate Zappar wasm under', umdDir);
+            warn('Worker found at:', workerSource);
+            return;
+        }
 
-    fs.mkdirSync(outDir, {recursive: true});
+        fs.mkdirSync(outDir, {recursive: true});
 
-    const workerDest = path.join(outDir, 'zappar-cv.worker.js');
-    copyOrThrow(workerSource, workerDest);
+        const workerDest = path.join(outDir, 'zappar-cv.worker.js');
+        copyOrThrow(workerSource, workerDest);
 
-    const wasmBasename = path.basename(wasmSource);
-    const wasmDest = path.join(outDir, wasmBasename);
-    copyOrThrow(wasmSource, wasmDest);
+        const wasmBasename = path.basename(wasmSource);
+        const wasmDest = path.join(outDir, wasmBasename);
+        copyOrThrow(wasmSource, wasmDest);
+        safeLinkOrCopy(wasmDest, path.join(outDir, 'zappar-cv.wasm'));
+        // Also copy wasm to static root so the bundled worker can find it at /zappar-cv.wasm.
+        copyOrThrow(wasmSource, path.join(path.dirname(outDir), 'zappar-cv.wasm'));
 
-    // Create a stable alias that the Wonderland provider code points at.
-    safeLinkOrCopy(wasmDest, path.join(outDir, 'zappar-cv.wasm'));
+        for (const entry of listFiles(umdDir)) {
+            if (!entry.isFile()) continue;
+            if (!entry.name.endsWith('.zbin')) continue;
+            copyOrThrow(path.join(umdDir, entry.name), path.join(outDir, entry.name));
+        }
+    } else {
+        // ---- Modern (>= 4.x) path ----
+        // Bundle the worker entry from @zappar/zappar-cv/lib/worker.js with esbuild.
+        const workerEntry = path.join(zapparCvLibDir, 'worker.js');
+        if (!fs.existsSync(workerEntry)) {
+            warn('Could not find worker entry at', workerEntry);
+            warn('Skipping worker bundling.');
+            return;
+        }
 
-    // Optional: copy any Zappar binary blobs shipped alongside the wasm.
-    // (Harmless if unused; avoids runtime 404s if Zappar expects them.)
-    for (const entry of listFiles(umdDir)) {
-        if (!entry.isFile()) continue;
-        if (!entry.name.endsWith('.zbin')) continue;
-        copyOrThrow(path.join(umdDir, entry.name), path.join(outDir, entry.name));
+        fs.mkdirSync(outDir, {recursive: true});
+
+        const workerDest = path.join(outDir, 'zappar-cv.worker.js');
+
+        // Try esbuild; it may be installed locally in the consumer project or globally.
+        const esbuildPaths = [
+            // consumer project's own node_modules (most reliable)
+            path.resolve(projectRoot, 'node_modules', '.bin', 'esbuild'),
+            path.resolve(projectRoot, 'node_modules', '.bin', 'esbuild.cmd'),
+            // provider package's own node_modules (if esbuild is a devDep there)
+            path.resolve(__dirname, '..', 'node_modules', '.bin', 'esbuild'),
+            path.resolve(__dirname, '..', 'node_modules', '.bin', 'esbuild.cmd'),
+        ];
+        const esbuildBin = esbuildPaths.find((p) => fs.existsSync(p));
+
+        if (!esbuildBin) {
+            warn('esbuild not found — cannot bundle worker for @zappar/zappar >= 4.x.');
+            warn('Add esbuild as a devDependency in your project and re-run npm install.');
+            return;
+        }
+
+        log('Bundling Zappar CV worker with esbuild…');
+        try {
+            execSync(
+                `"${esbuildBin}" "${workerEntry}" --bundle --format=esm --platform=browser --outfile="${workerDest}"`,
+                {stdio: 'inherit'}
+            );
+        } catch (e) {
+            warn('esbuild failed to bundle the Zappar CV worker:', e.message ?? e);
+            return;
+        }
+
+        // Copy the wasm file next to the worker so relative URL resolution works.
+        const wasmSrc = path.join(zapparCvLibDir, 'zappar-cv.wasm');
+        if (!fs.existsSync(wasmSrc)) {
+            warn('Could not find zappar-cv.wasm at', wasmSrc);
+        } else {
+            copyOrThrow(wasmSrc, path.join(outDir, 'zappar-cv.wasm'));
+            // Also copy wasm to static root so the bundled worker can find it at /zappar-cv.wasm.
+            copyOrThrow(wasmSrc, path.join(path.dirname(outDir), 'zappar-cv.wasm'));
+        }
     }
 
     // Required for face tracking defaults (FaceTracker.loadDefaultModel / FaceMesh.loadDefault*).
@@ -174,6 +235,27 @@ function main() {
     }
 
     log('Copied Zappar CV assets into', outDir);
+
+    // -------------------------------------------------------------------------
+    // Patch @zappar/zappar-cv/lib/profile.js: the file guards on
+    // `typeof window !== "undefined"` but then accesses `window.location`
+    // unconditionally. In the WLE editor's bundler context `window` is shimmed
+    // but `window.location` is undefined, crashing the component parse pass.
+    // Replace the bare access with optional chaining so it safely returns
+    // undefined rather than throwing.
+    // -------------------------------------------------------------------------
+    const profilePath = path.join(zapparCvRoot, 'lib', 'profile.js');
+    if (fs.existsSync(profilePath)) {
+        let profileSrc = fs.readFileSync(profilePath, 'utf8');
+        const patched = profileSrc.replaceAll(
+            'window.location.href',
+            'window.location?.href?'
+        );
+        if (patched !== profileSrc) {
+            fs.writeFileSync(profilePath, patched, 'utf8');
+            log('Patched @zappar/zappar-cv/lib/profile.js (window.location guard)');
+        }
+    }
 }
 
 try {