@wonderlandengine/ar-provider-zappar 1.0.0 → 1.1.0

package/README.md

@@ -19,6 +19,14 @@ This package depends on `@zappar/zappar`; make sure your bundler is configured
 to serve the `zcv.wasm` asset as described in the
 [Zappar installation guide](https://docs.zap.works/universal-ar/javascript/getting-started/installation/).
 
+For Wonderland Editor publishing and image-target training workflows, see the
+companion package
+[`@wonderlandengine/zappar-publish-plugin`](https://www.npmjs.com/package/@wonderlandengine/zappar-publish-plugin).
+
+> **Note:** The provider currently keeps tracking active but does not draw the
+> Zappar camera feed to the Wonderland canvas. If you require a background
+> video, composite it manually in your application.
+
 ## Supported Tracking Modes
 
 The Zappar provider implements SLAM, face tracking, and image tracking. These
@@ -26,9 +34,9 @@ map to the standard Wonderland Engine components supplied by
 `@wonderlandengine/ar-tracking` (`ARSLAMCamera`, `ARFaceTrackingCamera`, and
 `ARImageTrackingCamera`).
 
--   Face tracking loads Zappar's default model and mesh. Attachment points that
-    have no exact landmark are approximated to the closest available Zappar
-    landmark.
+- Face tracking loads Zappar's default model and mesh. Attachment points that
+  have no exact landmark are approximated to the closest available Zappar
+  landmark.
 
 ## Recording a Zappar Sequence (Camera + Motion)
 
@@ -65,8 +73,8 @@ URL.revokeObjectURL(a.href);
 
 Notes:
 
--   Sequence recording captures camera + IMU, so it’s best done on a mobile device.
--   You can replay sequences using Zappar’s `SequenceSource` API (preferred over MP4 replay for correct tracking).
+- Sequence recording captures camera + IMU, so it’s best done on a mobile device.
+- You can replay sequences using Zappar’s `SequenceSource` API (preferred over MP4 replay for correct tracking).
 
 ### Registering Image Targets
 
@@ -93,3 +101,10 @@ await provider.registerImageTarget('/static/targets/poster.zpt', posterTarget);
 
 Once registered, the provider emits image scanning and tracking events via
 `ARImageTrackingCamera`.
+
+## Related Packages
+
+- [`@wonderlandengine/ar-tracking`](https://www.npmjs.com/package/@wonderlandengine/ar-tracking)
+  Core AR abstractions and camera components.
+- [`@wonderlandengine/zappar-publish-plugin`](https://www.npmjs.com/package/@wonderlandengine/zappar-publish-plugin)
+  Wonderland Editor plugin for ZapWorks upload/publish and target training.

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

@@ -1,5 +1,8 @@
 import { Emitter } from '@wonderlandengine/api';
-import { FaceFoundEvent, FaceLoadingEvent, FaceLostEvent, FaceTrackingMode, TrackingMode } from '@wonderlandengine/ar-tracking';
+import { FaceAttachmentPoint, FaceFoundEvent, FaceLoadingEvent, FaceLostEvent, FaceTrackingMode, TrackingMode } from '@wonderlandengine/ar-tracking';
+type AttachmentMapping = Partial<Record<FaceAttachmentPoint, string>>;
+export declare const AttachmentLandmarkKeys: AttachmentMapping;
+export declare function buildFaceLoadingEventFromMesh(maxDetections: number, verticesArray: ArrayLike<number>, indicesArray: ArrayLike<number>, uvsArray: ArrayLike<number>): FaceLoadingEvent;
 export declare class FaceTracking_Zappar extends TrackingMode implements FaceTrackingMode {
     private _zappar;
     private _view?;
@@ -19,6 +22,7 @@ export declare class FaceTracking_Zappar extends TrackingMode implements FaceTra
     private readonly _scratchPosition;
     private readonly _scratchRotation;
     private readonly _scratchScale;
+    private readonly _providerRotation;
     private _loadingEvent;
     readonly onFaceScanning: Emitter<[event: FaceLoadingEvent]>;
     readonly onFaceLoading: Emitter<[event: FaceLoadingEvent]>;
@@ -36,5 +40,7 @@ export declare class FaceTracking_Zappar extends TrackingMode implements FaceTra
     private _handleAnchorNotVisible;
     private _buildFaceEvent;
     private _applyCameraPose;
+    private _setProjectionMatrixWithEngineRemap;
     private _anchorNumericId;
 }
+export {};

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

@@ -1,7 +1,7 @@
 import { Emitter } from '@wonderlandengine/api';
 import { FaceAttachmentPoint, TrackingMode, } from '@wonderlandengine/ar-tracking';
 import { mat4, quat, vec3 } from 'gl-matrix';
-const AttachmentLandmarkKeys = {
+export const AttachmentLandmarkKeys = {
     [FaceAttachmentPoint.Forehead]: 'NOSE_BRIDGE',
     [FaceAttachmentPoint.EyeOuterCornerLeft]: 'EYE_LEFT',
     [FaceAttachmentPoint.EyeOuterCornerRight]: 'EYE_RIGHT',
@@ -27,6 +27,39 @@ const AttachmentLandmarkKeys = {
     [FaceAttachmentPoint.Chin]: 'CHIN',
 };
 const AttachmentList = Object.values(FaceAttachmentPoint);
+const FACE_LOCAL_Y_180 = quat.fromValues(0, 1, 0, 0);
+function convertFaceLocalVectorToProviderSpace(x, y, z) {
+    // Zappar face-local basis differs from our provider contract by a 180° yaw.
+    return { x: -x, y, z: -z };
+}
+function convertFaceLocalRotationToProviderSpace(rotation) {
+    // If local coordinates are rotated by C, then world rotation must become R' = R * C
+    // to preserve world-space geometry.
+    const out = quat.create();
+    quat.multiply(out, rotation, FACE_LOCAL_Y_180);
+    quat.normalize(out, out);
+    return out;
+}
+export function buildFaceLoadingEventFromMesh(maxDetections, verticesArray, indicesArray, uvsArray) {
+    const indices = [];
+    for (let i = 0; i < indicesArray.length; i += 3) {
+        indices.push({
+            a: indicesArray[i],
+            b: indicesArray[i + 2],
+            c: indicesArray[i + 1],
+        });
+    }
+    const uvs = [];
+    for (let i = 0; i < uvsArray.length; i += 2) {
+        uvs.push({ u: 1 - uvsArray[i], v: 1 - uvsArray[i + 1] });
+    }
+    return {
+        maxDetections,
+        pointsPerDetection: verticesArray.length / 3,
+        indices: indices,
+        uvs: uvs,
+    };
+}
 export class FaceTracking_Zappar extends TrackingMode {
     _zappar = null;
     _view;
@@ -46,6 +79,7 @@ export class FaceTracking_Zappar extends TrackingMode {
     _scratchPosition = vec3.create();
     _scratchRotation = quat.create();
     _scratchScale = vec3.create();
+    _providerRotation = quat.create();
     _loadingEvent = null;
     onFaceScanning = new Emitter();
     onFaceLoading = new Emitter();
@@ -54,6 +88,15 @@ export class FaceTracking_Zappar extends TrackingMode {
     onFaceLost = new Emitter();
     init() {
         this._view = this.component.object.getComponent('view') ?? undefined;
+        const provider = this.provider;
+        const faceComponent = this.component;
+        if (typeof faceComponent.cameraDirection === 'number') {
+            // ARFaceTrackingCamera enum is ['front', 'back']
+            provider.setPreferredCameraUserFacing(faceComponent.cameraDirection === 0);
+        }
+        else {
+            provider.setPreferredCameraUserFacing(true);
+        }
         const input = this.component.object.getComponent('input');
         if (input) {
             input.active = false;
@@ -77,14 +120,17 @@ export class FaceTracking_Zappar extends TrackingMode {
             return;
         const provider = this.provider;
         const pipeline = provider.getPipeline();
-        const projectionMatrix = Zappar.projectionMatrixFromCameraModel(pipeline.cameraModel(), this.component.engine.canvas.width, this.component.engine.canvas.height);
+        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);
         if (this._view) {
-            this._view.projectionMatrix.set(projectionMatrix);
+            this._setProjectionMatrixWithEngineRemap(projectionMatrix);
         }
         const cameraPose = pipeline.cameraPoseDefault();
         this._applyCameraPose(cameraPose);
         for (const anchor of this._faceTracker.visible) {
-            const event = this._buildFaceEvent(anchor);
+            const event = this._buildFaceEvent(anchor, mirrorPoses);
             this.onFaceUpdate.notify(event);
         }
     }
@@ -133,91 +179,66 @@ export class FaceTracking_Zappar extends TrackingMode {
         if (!this._faceTracker || !this._faceMesh) {
             return null;
         }
-        const indicesArray = this._faceMesh.indices;
-        const uvsArray = this._faceMesh.uvs;
-        const verticesArray = this._faceMesh.vertices;
-        const indices = [];
-        for (let i = 0; i < indicesArray.length; i += 3) {
-            indices.push({
-                a: indicesArray[i],
-                b: indicesArray[i + 1],
-                c: indicesArray[i + 2],
-            });
-        }
-        const uvs = [];
-        for (let i = 0; i < uvsArray.length; i += 2) {
-            uvs.push({ u: uvsArray[i], v: uvsArray[i + 1] });
-        }
-        return {
-            maxDetections: this._faceTracker.maxFaces,
-            pointsPerDetection: verticesArray.length / 3,
-            indices: indices,
-            uvs: uvs,
-        };
+        return buildFaceLoadingEventFromMesh(this._faceTracker.maxFaces, this._faceMesh.vertices, this._faceMesh.indices, this._faceMesh.uvs);
     }
     _handleAnchorVisible = (anchor) => {
         if (!this._resourcesReady) {
             return;
         }
-        const event = this._buildFaceEvent(anchor);
+        const provider = this.provider;
+        const pipeline = provider.getPipeline();
+        const mirrorPoses = pipeline.cameraFrameUserFacing();
+        const event = this._buildFaceEvent(anchor, mirrorPoses);
         this.onFaceFound.notify(event);
     };
     _handleAnchorNotVisible = (anchor) => {
         const id = this._anchorNumericId(anchor.id);
         this.onFaceLost.notify({ id });
     };
-    _buildFaceEvent(anchor) {
+    _buildFaceEvent(anchor, mirrorPoses) {
         const provider = this.provider;
         const pipeline = provider.getPipeline();
         const cameraPose = pipeline.cameraPoseDefault();
-        const anchorPose = anchor.pose(cameraPose, false);
+        const anchorPose = anchor.pose(cameraPose, mirrorPoses);
         mat4.copy(this._scratchMatrix, anchorPose);
         mat4.getTranslation(this._scratchPosition, this._scratchMatrix);
         mat4.getRotation(this._scratchRotation, this._scratchMatrix);
         mat4.getScaling(this._scratchScale, this._scratchMatrix);
+        quat.copy(this._providerRotation, convertFaceLocalRotationToProviderSpace(this._scratchRotation));
+        this._scratchScale[0] = Math.abs(this._scratchScale[0]);
+        this._scratchScale[1] = Math.abs(this._scratchScale[1]);
+        this._scratchScale[2] = Math.abs(this._scratchScale[2]);
         const scale = (this._scratchScale[0] + this._scratchScale[1] + this._scratchScale[2]) / 3;
         const anchorPosition = {
             x: this._scratchPosition[0],
             y: this._scratchPosition[1],
             z: this._scratchPosition[2],
         };
-        this._faceMesh.updateFromFaceAnchor(anchor, false);
+        this._faceMesh.updateFromFaceAnchor(anchor, mirrorPoses);
         const verticesArray = this._faceMesh.vertices;
         const normalsArray = this._faceMesh.normals;
         const vertices = [];
         for (let i = 0; i < verticesArray.length; i += 3) {
-            vertices.push({
-                x: verticesArray[i],
-                y: verticesArray[i + 1],
-                z: verticesArray[i + 2],
-            });
+            vertices.push(convertFaceLocalVectorToProviderSpace(verticesArray[i], verticesArray[i + 1], verticesArray[i + 2]));
         }
         const normals = [];
         for (let i = 0; i < normalsArray.length; i += 3) {
-            normals.push({
-                x: normalsArray[i],
-                y: normalsArray[i + 1],
-                z: normalsArray[i + 2],
-            });
+            normals.push(convertFaceLocalVectorToProviderSpace(normalsArray[i], normalsArray[i + 1], normalsArray[i + 2]));
         }
         const attachmentPoints = {};
         for (const attachment of AttachmentList) {
             const landmark = this._landmarks.get(attachment);
             if (landmark) {
-                landmark.updateFromFaceAnchor(anchor, false);
+                landmark.updateFromFaceAnchor(anchor, mirrorPoses);
                 mat4.copy(this._scratchMatrix, landmark.pose);
                 mat4.getTranslation(this._scratchPosition, this._scratchMatrix);
                 attachmentPoints[attachment] = {
-                    position: {
-                        x: this._scratchPosition[0],
-                        y: this._scratchPosition[1],
-                        z: this._scratchPosition[2],
-                    },
+                    position: convertFaceLocalVectorToProviderSpace(this._scratchPosition[0], this._scratchPosition[1], this._scratchPosition[2]),
                 };
             }
             else {
                 attachmentPoints[attachment] = {
-                    position: { ...anchorPosition },
+                    position: convertFaceLocalVectorToProviderSpace(0, 0, 0),
                 };
             }
         }
@@ -230,10 +251,10 @@ export class FaceTracking_Zappar extends TrackingMode {
             transform: {
                 position: { ...anchorPosition },
                 rotation: {
-                    x: this._scratchRotation[0],
-                    y: this._scratchRotation[1],
-                    z: this._scratchRotation[2],
-                    w: this._scratchRotation[3],
+                    x: this._providerRotation[0],
+                    y: this._providerRotation[1],
+                    z: this._providerRotation[2],
+                    w: this._providerRotation[3],
                 },
                 scale,
                 scaledWidth: this._scratchScale[0],
@@ -250,6 +271,64 @@ export class FaceTracking_Zappar extends TrackingMode {
         this.component.object.setPositionWorld(this._cameraPosition);
         this.component.object.setRotationWorld(this._cameraRotation);
     }
+    _setProjectionMatrixWithEngineRemap(matrix) {
+        const debugWindow = globalThis;
+        const view = this._view;
+        if (!view) {
+            if (debugWindow.__WLE_ZAPPAR_DEBUG__) {
+                debugWindow.__WLE_ZAPPAR_LAST_PROJECTION_REMAP__ = {
+                    mode: 'face',
+                    viewId: null,
+                    reverseZ: false,
+                    status: 'skipped',
+                    reason: 'no-view',
+                };
+            }
+            return;
+        }
+        if (typeof view._setProjectionMatrix === 'function') {
+            view._setProjectionMatrix(matrix);
+        }
+        else {
+            view.projectionMatrix.set(matrix);
+        }
+        const engineAny = this.component.engine;
+        if (typeof view._id !== 'number') {
+            if (debugWindow.__WLE_ZAPPAR_DEBUG__) {
+                debugWindow.__WLE_ZAPPAR_LAST_PROJECTION_REMAP__ = {
+                    mode: 'face',
+                    viewId: null,
+                    reverseZ: engineAny.isReverseZEnabled,
+                    status: 'skipped',
+                    reason: 'missing-view-id',
+                };
+            }
+            return;
+        }
+        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__) {
+                debugWindow.__WLE_ZAPPAR_LAST_PROJECTION_REMAP__ = {
+                    mode: 'face',
+                    viewId: view._id,
+                    reverseZ: engineAny.isReverseZEnabled,
+                    status: 'applied',
+                };
+            }
+            return;
+        }
+        if (debugWindow.__WLE_ZAPPAR_DEBUG__) {
+            debugWindow.__WLE_ZAPPAR_LAST_PROJECTION_REMAP__ = {
+                mode: 'face',
+                viewId: view._id,
+                reverseZ: engineAny.isReverseZEnabled,
+                status: 'skipped',
+                reason: 'missing-wasm-remap-function',
+            };
+        }
+    }
     _anchorNumericId(anchorId) {
         let id = this._anchorNumericIds.get(anchorId);
         if (id === undefined) {

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

@@ -32,4 +32,5 @@ export declare class ImageTracking_Zappar extends TrackingMode implements ImageT
     private _buildImageEvent;
     private _guessDescriptor;
     private _applyCameraPose;
+    private _setProjectionMatrixWithEngineRemap;
 }

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

@@ -23,6 +23,8 @@ export class ImageTracking_Zappar extends TrackingMode {
     onImageLost = new Emitter();
     init() {
         this._view = this.component.object.getComponent('view') ?? undefined;
+        const provider = this.provider;
+        provider.setPreferredCameraUserFacing(false);
         const input = this.component.object.getComponent('input');
         if (input) {
             input.active = false;
@@ -46,9 +48,11 @@ export class ImageTracking_Zappar extends TrackingMode {
             return;
         const provider = this.provider;
         const pipeline = provider.getPipeline();
-        const projectionMatrix = Zappar.projectionMatrixFromCameraModel(pipeline.cameraModel(), this.component.engine.canvas.width, this.component.engine.canvas.height);
+        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);
         if (this._view) {
-            this._view.projectionMatrix.set(projectionMatrix);
+            this._setProjectionMatrixWithEngineRemap(projectionMatrix);
         }
         const cameraPose = pipeline.cameraPoseDefault();
         this._applyCameraPose(cameraPose);
@@ -170,4 +174,61 @@ export class ImageTracking_Zappar extends TrackingMode {
         this.component.object.setPositionWorld(this._cameraPosition);
         this.component.object.setRotationWorld(this._cameraRotation);
     }
+    _setProjectionMatrixWithEngineRemap(matrix) {
+        const debugWindow = globalThis;
+        const view = this._view;
+        if (!view) {
+            if (debugWindow.__WLE_ZAPPAR_DEBUG__) {
+                debugWindow.__WLE_ZAPPAR_LAST_PROJECTION_REMAP__ = {
+                    mode: 'image',
+                    viewId: null,
+                    reverseZ: false,
+                    status: 'skipped',
+                    reason: 'no-view',
+                };
+            }
+            return;
+        }
+        if (typeof view._setProjectionMatrix === 'function') {
+            view._setProjectionMatrix(matrix);
+        }
+        else {
+            view.projectionMatrix.set(matrix);
+        }
+        const engineAny = this.component.engine;
+        if (typeof view._id !== 'number') {
+            if (debugWindow.__WLE_ZAPPAR_DEBUG__) {
+                debugWindow.__WLE_ZAPPAR_LAST_PROJECTION_REMAP__ = {
+                    mode: 'image',
+                    viewId: null,
+                    reverseZ: engineAny.isReverseZEnabled,
+                    status: 'skipped',
+                    reason: 'missing-view-id',
+                };
+            }
+            return;
+        }
+        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__) {
+                debugWindow.__WLE_ZAPPAR_LAST_PROJECTION_REMAP__ = {
+                    mode: 'image',
+                    viewId: view._id,
+                    reverseZ: engineAny.isReverseZEnabled,
+                    status: 'applied',
+                };
+            }
+            return;
+        }
+        if (debugWindow.__WLE_ZAPPAR_DEBUG__) {
+            debugWindow.__WLE_ZAPPAR_LAST_PROJECTION_REMAP__ = {
+                mode: 'image',
+                viewId: view._id,
+                reverseZ: engineAny.isReverseZEnabled,
+                status: 'skipped',
+                reason: 'missing-wasm-remap-function',
+            };
+        }
+    }
 }

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

@@ -10,6 +10,8 @@ export class WorldTracking_Zappar extends TrackingMode {
         super(provider, component);
     }
     init() {
+        const provider = this.provider;
+        provider.setPreferredCameraUserFacing(false);
         const input = this.component.object.getComponent('input');
         if (input) {
             // Camera pose will be driven by the AR tracking implementation.

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

@@ -37,6 +37,8 @@ export declare class ZapparProvider extends ARProvider {
     private _faceMesh;
     private _faceResourcesPromise;
     private _imageTracker;
+    private _preferredCameraUserFacing;
+    private _cameraSourceUserFacing;
     private _imageTargetDescriptors;
     private readonly _imageTargetsChanged;
     private cameraStarted;
@@ -66,14 +68,23 @@ export declare class ZapparProvider extends ARProvider {
     private readonly _debugLastSampleAnchorPosition;
     private _zapparDebugLogIntervalId;
     private _preRenderErrorLogged;
+    private get isVerboseDebugLoggingEnabled();
     static Name: string;
     get name(): string;
     get supportsInstantTracking(): boolean;
     get onImageTargetsChanged(): Emitter<void[]>;
     get xrSession(): XRSession | null;
+    /**
+     * Hint camera facing preference for the next/active session.
+     * - `true`: user/front camera
+     * - `false`: rear/back camera
+     * - `null`: Zappar default
+     */
+    setPreferredCameraUserFacing(userFacing: boolean | null): void;
     static registerTrackingProviderWithARSession(arSession: ARSession): ZapparProvider;
     private constructor();
     startSession(): Promise<void>;
+    private ensurePreRenderRegistered;
     private startZapparDebugLogging;
     private stopZapparDebugLogging;
     private ensureZapparLoaded;
@@ -81,6 +92,7 @@ export declare class ZapparProvider extends ARProvider {
     ensureZapparNamespace(): Promise<Awaited<ReturnType<typeof loadZappar>>>;
     private configureCvWorkerIfNeeded;
     private ensurePipeline;
+    private ensureCameraSourcePreference;
     getPipeline(): Pipeline;
     ensureFaceResources(): Promise<void>;
     getFaceTracker(): FaceTracker;

package/dist/src/zappar-provider.js

@@ -24,6 +24,8 @@ export class ZapparProvider extends ARProvider {
     _faceMesh = null;
     _faceResourcesPromise = null;
     _imageTracker = null;
+    _preferredCameraUserFacing = null;
+    _cameraSourceUserFacing = null;
     _imageTargetDescriptors = [];
     _imageTargetsChanged = new Emitter();
     cameraStarted = false;
@@ -53,6 +55,14 @@ export class ZapparProvider extends ARProvider {
     _debugLastSampleAnchorPosition = vec3.create();
     _zapparDebugLogIntervalId = null;
     _preRenderErrorLogged = false;
+    get isVerboseDebugLoggingEnabled() {
+        if (typeof window === 'undefined') {
+            return false;
+        }
+        const debugWindow = window;
+        return (debugWindow.__WLE_ZAPPAR_DEBUG__ === true ||
+            debugWindow.__ZAPPAR_WORKER_DEBUG__ === true);
+    }
     static Name = 'Zappar';
     get name() {
         return ZapparProvider.Name;
@@ -66,6 +76,15 @@ export class ZapparProvider extends ARProvider {
     get xrSession() {
         return this._xrSession;
     }
+    /**
+     * Hint camera facing preference for the next/active session.
+     * - `true`: user/front camera
+     * - `false`: rear/back camera
+     * - `null`: Zappar default
+     */
+    setPreferredCameraUserFacing(userFacing) {
+        this._preferredCameraUserFacing = userFacing;
+    }
     static registerTrackingProviderWithARSession(arSession) {
         const provider = new ZapparProvider(arSession.engine);
         arSession.registerTrackingProvider(provider);
@@ -78,10 +97,9 @@ export class ZapparProvider extends ARProvider {
         }
         engine.onXRSessionStart.add((session) => {
             this._xrSession = session;
-            this.onSessionStart.notify(this);
         });
         engine.onXRSessionEnd.add(() => {
-            this.onSessionEnd.notify(this);
+            this._xrSession = null;
         });
     }
     async startSession() {
@@ -93,8 +111,15 @@ export class ZapparProvider extends ARProvider {
         await this.ensureZapparLoaded();
         await this._zappar.loadedPromise();
         this.ensurePipeline();
+        this.ensureCameraSourcePreference();
         await this.ensureCameraRunning();
         this.startZapparDebugLogging();
+        if (this._faceTracker) {
+            this._faceTracker.enabled = true;
+        }
+        if (this._imageTracker) {
+            this._imageTracker.enabled = true;
+        }
         // For instant tracking providers, we should emit session start here.
         // (Unlike WebXR, there is no XRSessionStart event.)
         this.onSessionStart.notify(this);
@@ -102,9 +127,18 @@ export class ZapparProvider extends ARProvider {
             this.instantTracker.enabled = true;
         }
     }
+    ensurePreRenderRegistered() {
+        if (!this.preRenderRegistered) {
+            this.engine.scene.onPreRender.add(this.onPreRender);
+            this.preRenderRegistered = true;
+        }
+    }
     startZapparDebugLogging() {
         if (this._zapparDebugLogIntervalId !== null)
             return;
+        if (!this.isVerboseDebugLoggingEnabled) {
+            return;
+        }
         const canAccessWindow = typeof window !== 'undefined' &&
             typeof window.setInterval ===
                 'function';
@@ -157,9 +191,7 @@ export class ZapparProvider extends ARProvider {
         // Hard-coded paths for local development
         const workerUrl = './zappar-cv/zappar-cv.worker.js';
         const wasmUrl = './zappar-cv/zappar-cv.wasm';
-        const debugWorker = typeof window !== 'undefined' &&
-            window
-                .__ZAPPAR_WORKER_DEBUG__;
+        const debugWorker = this.isVerboseDebugLoggingEnabled;
         if (debugWorker) {
             console.log('[ZapparProvider] configureCvWorkerIfNeeded()', {
                 workerUrl,
@@ -188,21 +220,23 @@ export class ZapparProvider extends ARProvider {
             const resolvedWasmUrl = typeof window !== 'undefined'
                 ? new URL(wasmUrl, window.location.href).toString()
                 : wasmUrl;
-            console.log('[ZapparProvider] CV worker created', {
-                workerUrl,
-                resolvedWorkerUrl,
-                wasmUrl,
-                resolvedWasmUrl,
-            });
+            if (debugWorker) {
+                console.log('[ZapparProvider] CV worker created', {
+                    workerUrl,
+                    resolvedWorkerUrl,
+                    wasmUrl,
+                    resolvedWasmUrl,
+                });
+            }
             let workerMessagesSeen = 0;
             worker.addEventListener('message', (event) => {
                 workerMessagesSeen++;
-                if (workerMessagesSeen === 1) {
+                if (workerMessagesSeen === 1 && debugWorker) {
                     console.log('[ZapparProvider] CV worker first message received', event.data);
                     return;
                 }
                 // Keep a couple more messages for context, but avoid spamming.
-                if (workerMessagesSeen <= 5) {
+                if (debugWorker && workerMessagesSeen <= 5) {
                     console.log('[ZapparProvider] CV worker message', {
                         index: workerMessagesSeen,
                         data: event.data,
@@ -249,8 +283,10 @@ export class ZapparProvider extends ARProvider {
         }
     }
     ensurePipeline() {
-        if (this.pipeline)
+        if (this.pipeline) {
+            this.ensurePreRenderRegistered();
             return;
+        }
         if (!this._zappar) {
             throw new Error('Zappar is not loaded yet. Call startSession() first.');
         }
@@ -270,15 +306,27 @@ export class ZapparProvider extends ARProvider {
             globalThis.ZapparPipeline = pipeline;
         }
         if (typeof window !== 'undefined') {
-            console.log('[ZapparProvider] Using device camera source');
+            if (this.isVerboseDebugLoggingEnabled) {
+                console.log('[ZapparProvider] Using device camera source');
+            }
         }
-        const deviceId = Zappar.cameraDefaultDeviceID();
-        this.cameraSource = new Zappar.CameraSource(pipeline, deviceId);
+        this.ensureCameraSourcePreference();
         this.instantTracker = new Zappar.InstantWorldTracker(pipeline);
-        if (!this.preRenderRegistered) {
-            this.engine.scene.onPreRender.add(this.onPreRender);
-            this.preRenderRegistered = true;
+        this.ensurePreRenderRegistered();
+    }
+    ensureCameraSourcePreference() {
+        if (!this.pipeline || !this._zappar) {
+            return;
         }
+        const desiredUserFacing = this._preferredCameraUserFacing;
+        if (this.cameraSource && this._cameraSourceUserFacing === desiredUserFacing) {
+            return;
+        }
+        const deviceId = desiredUserFacing === null
+            ? this._zappar.cameraDefaultDeviceID()
+            : this._zappar.cameraDefaultDeviceID(desiredUserFacing);
+        this.cameraSource = new this._zappar.CameraSource(this.pipeline, deviceId);
+        this._cameraSourceUserFacing = desiredUserFacing;
     }
     getPipeline() {
         if (!this.pipeline) {
@@ -477,15 +525,13 @@ export class ZapparProvider extends ARProvider {
         if (previousUnpackBuffer)
             gl.bindBuffer(gl.PIXEL_UNPACK_BUFFER, null);
         try {
-            // Mirror Zappar THREE.js update order:
-            // - tracking: processGL() -> frameUpdate()
-            // - texture upload: cameraFrameUploadGL() is performed separately (cameraTexture.ts)
+            // Keep GL update order consistent with the non-GL path:
+            // process tracking input, upload camera frame texture, then update frame state.
             this.pipeline.processGL();
+            this.pipeline.cameraFrameUploadGL();
             this.pipeline.frameUpdate();
             // Update SLAM state every frame (one loop in the provider).
             this.updateTracking();
-            // Upload the latest camera frame to a WebGL texture (for background rendering).
-            this.pipeline.cameraFrameUploadGL();
             // Bind the Zappar camera texture for Wonderland's sky material.
             // Wonderland Engine will handle drawing; we only ensure that:
             // - `videoTexture` sampler uniform points to the last texture unit

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@wonderlandengine/ar-provider-zappar",
-    "version": "1.0.0",
+    "version": "1.1.0",
     "description": "Wonderland Engine AR tracking provider based on Zappar",
     "main": "dist/index.js",
     "type": "module",
@@ -32,7 +32,7 @@
         "scripts/**/*.mjs"
     ],
     "devDependencies": {
-        "prettier": "^2.8.4",
+        "prettier": "^3.5.3",
         "typescript": "^4.9.5"
     },
     "peerDependencies": {

package/scripts/postinstall.mjs

@@ -1,184 +1,184 @@
-import fs from 'node:fs';
-import path from 'node:path';
-import {createRequire} from 'node:module';
-import {fileURLToPath} from 'node:url';
-
-const require = createRequire(import.meta.url);
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
-
-const logPrefix = '[ar-provider-zappar:postinstall]';
-
-function log(...args) {
-    // Keep output minimal but actionable.
-    console.log(logPrefix, ...args);
-}
-
-function warn(...args) {
-    console.warn(logPrefix, ...args);
-}
-
-function copyOrThrow(src, dest) {
-    fs.mkdirSync(path.dirname(dest), {recursive: true});
-    fs.copyFileSync(src, dest);
-}
-
-function safeLinkOrCopy(src, dest) {
-    fs.mkdirSync(path.dirname(dest), {recursive: true});
-    try {
-        if (fs.existsSync(dest)) fs.unlinkSync(dest);
-        fs.linkSync(src, dest);
-    } catch {
-        try {
-            if (fs.existsSync(dest)) fs.unlinkSync(dest);
-        } catch {
-            // ignore
-        }
-        fs.copyFileSync(src, dest);
-    }
-}
-
-function listFiles(dir) {
-    try {
-        return fs.readdirSync(dir, {withFileTypes: true});
-    } catch {
-        return [];
-    }
-}
-
-function findFirstFile(dir, predicate) {
-    for (const entry of listFiles(dir)) {
-        if (!entry.isFile()) continue;
-        if (predicate(entry.name)) return path.join(dir, entry.name);
-    }
-    return null;
-}
-
-function findWasmFromWorker(workerPath, umdDir) {
-    try {
-        const src = fs.readFileSync(workerPath, 'utf8');
-        const match = src.match(/["']([^"']+\.wasm)["']/);
-        if (!match) return null;
-
-        const candidate = path.resolve(umdDir, match[1]);
-        const relative = path.relative(umdDir, candidate);
-
-        // Ensure we never resolve outside the umd directory.
-        if (relative.startsWith('..') || path.isAbsolute(relative)) return null;
-
-        return fs.existsSync(candidate) ? candidate : null;
-    } catch {
-        return null;
-    }
-}
-
-function resolveZapparRoot() {
-    const providerRoot = path.resolve(__dirname, '..');
-    const zapparPackageJson = require.resolve('@zappar/zappar/package.json', {
-        paths: [providerRoot],
-    });
-    return path.dirname(zapparPackageJson);
-}
-
-function resolveZapparCvRoot() {
-    const providerRoot = path.resolve(__dirname, '..');
-    const zapparCvPackageJson = require.resolve('@zappar/zappar-cv/package.json', {
-        paths: [providerRoot],
-    });
-    return path.dirname(zapparCvPackageJson);
-}
-
-function resolveProjectRoot() {
-    // INIT_CWD is set by npm/yarn/pnpm for lifecycle scripts and points at the
-    // consumer project that triggered the install.
-    const initCwd = process.env.INIT_CWD;
-    if (initCwd && initCwd.trim()) return path.resolve(initCwd);
-
-    // Fallback (best effort): current working directory.
-    return process.cwd();
-}
-
-function main() {
-    const zapparRoot = resolveZapparRoot();
-    const umdDir = path.join(zapparRoot, 'umd');
-
-    const zapparCvRoot = resolveZapparCvRoot();
-    const zapparCvLibDir = path.join(zapparCvRoot, 'lib');
-
-    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;
-    }
-
-    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);
-
-    if (!wasmSource) {
-        warn('Could not locate Zappar wasm under', umdDir);
-        warn('Worker found at:', workerSource);
-        return;
-    }
-
-    fs.mkdirSync(outDir, {recursive: true});
-
-    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);
-
-    // Create a stable alias that the Wonderland provider code points at.
-    safeLinkOrCopy(wasmDest, path.join(outDir, 'zappar-cv.wasm'));
-
-    // 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));
-    }
-
-    // Required for face tracking defaults (FaceTracker.loadDefaultModel / FaceMesh.loadDefault*).
-    // These ship in @zappar/zappar-cv/lib but are fetched at runtime unless staged.
-    const requiredFaceModelFiles = [
-        'face_tracking_model.zbin',
-        'face_mesh_face_model.zbin',
-    ];
-
-    for (const filename of requiredFaceModelFiles) {
-        const src = path.join(zapparCvLibDir, filename);
-        const dest = path.join(outDir, filename);
-        if (!fs.existsSync(src)) {
-            warn('Could not locate required Zappar face model:', filename);
-            warn('Looked under:', zapparCvLibDir);
-            continue;
-        }
-        copyOrThrow(src, dest);
-    }
-
-    log('Copied Zappar CV assets into', outDir);
-}
-
-try {
-    main();
-} catch (e) {
-    // Postinstall should not hard-fail the whole install; consumers can still override.
-    warn('Failed to stage Zappar CV assets:', e);
-}
+import fs from 'node:fs';
+import path from 'node:path';
+import {createRequire} from 'node:module';
+import {fileURLToPath} from 'node:url';
+
+const require = createRequire(import.meta.url);
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const logPrefix = '[ar-provider-zappar:postinstall]';
+
+function log(...args) {
+    // Keep output minimal but actionable.
+    console.log(logPrefix, ...args);
+}
+
+function warn(...args) {
+    console.warn(logPrefix, ...args);
+}
+
+function copyOrThrow(src, dest) {
+    fs.mkdirSync(path.dirname(dest), {recursive: true});
+    fs.copyFileSync(src, dest);
+}
+
+function safeLinkOrCopy(src, dest) {
+    fs.mkdirSync(path.dirname(dest), {recursive: true});
+    try {
+        if (fs.existsSync(dest)) fs.unlinkSync(dest);
+        fs.linkSync(src, dest);
+    } catch {
+        try {
+            if (fs.existsSync(dest)) fs.unlinkSync(dest);
+        } catch {
+            // ignore
+        }
+        fs.copyFileSync(src, dest);
+    }
+}
+
+function listFiles(dir) {
+    try {
+        return fs.readdirSync(dir, {withFileTypes: true});
+    } catch {
+        return [];
+    }
+}
+
+function findFirstFile(dir, predicate) {
+    for (const entry of listFiles(dir)) {
+        if (!entry.isFile()) continue;
+        if (predicate(entry.name)) return path.join(dir, entry.name);
+    }
+    return null;
+}
+
+function findWasmFromWorker(workerPath, umdDir) {
+    try {
+        const src = fs.readFileSync(workerPath, 'utf8');
+        const match = src.match(/["']([^"']+\.wasm)["']/);
+        if (!match) return null;
+
+        const candidate = path.resolve(umdDir, match[1]);
+        const relative = path.relative(umdDir, candidate);
+
+        // Ensure we never resolve outside the umd directory.
+        if (relative.startsWith('..') || path.isAbsolute(relative)) return null;
+
+        return fs.existsSync(candidate) ? candidate : null;
+    } catch {
+        return null;
+    }
+}
+
+function resolveZapparRoot() {
+    const providerRoot = path.resolve(__dirname, '..');
+    const zapparPackageJson = require.resolve('@zappar/zappar/package.json', {
+        paths: [providerRoot],
+    });
+    return path.dirname(zapparPackageJson);
+}
+
+function resolveZapparCvRoot() {
+    const providerRoot = path.resolve(__dirname, '..');
+    const zapparCvPackageJson = require.resolve('@zappar/zappar-cv/package.json', {
+        paths: [providerRoot],
+    });
+    return path.dirname(zapparCvPackageJson);
+}
+
+function resolveProjectRoot() {
+    // INIT_CWD is set by npm/yarn/pnpm for lifecycle scripts and points at the
+    // consumer project that triggered the install.
+    const initCwd = process.env.INIT_CWD;
+    if (initCwd && initCwd.trim()) return path.resolve(initCwd);
+
+    // Fallback (best effort): current working directory.
+    return process.cwd();
+}
+
+function main() {
+    const zapparRoot = resolveZapparRoot();
+    const umdDir = path.join(zapparRoot, 'umd');
+
+    const zapparCvRoot = resolveZapparCvRoot();
+    const zapparCvLibDir = path.join(zapparCvRoot, 'lib');
+
+    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;
+    }
+
+    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);
+
+    if (!wasmSource) {
+        warn('Could not locate Zappar wasm under', umdDir);
+        warn('Worker found at:', workerSource);
+        return;
+    }
+
+    fs.mkdirSync(outDir, {recursive: true});
+
+    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);
+
+    // Create a stable alias that the Wonderland provider code points at.
+    safeLinkOrCopy(wasmDest, path.join(outDir, 'zappar-cv.wasm'));
+
+    // 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));
+    }
+
+    // Required for face tracking defaults (FaceTracker.loadDefaultModel / FaceMesh.loadDefault*).
+    // These ship in @zappar/zappar-cv/lib but are fetched at runtime unless staged.
+    const requiredFaceModelFiles = [
+        'face_tracking_model.zbin',
+        'face_mesh_face_model.zbin',
+    ];
+
+    for (const filename of requiredFaceModelFiles) {
+        const src = path.join(zapparCvLibDir, filename);
+        const dest = path.join(outDir, filename);
+        if (!fs.existsSync(src)) {
+            warn('Could not locate required Zappar face model:', filename);
+            warn('Looked under:', zapparCvLibDir);
+            continue;
+        }
+        copyOrThrow(src, dest);
+    }
+
+    log('Copied Zappar CV assets into', outDir);
+}
+
+try {
+    main();
+} catch (e) {
+    // Postinstall should not hard-fail the whole install; consumers can still override.
+    warn('Failed to stage Zappar CV assets:', e);
+}