feat(video): support cameraFacing on VideoSourceInput

Add optional `cameraFacing` ("user" | "environment") to VideoSourceInput,
passed to `createVideoSource` as `cameraType`. The camera type propagates to
the lens (DeviceCamera front/back-facing) and engine tracking, so back-facing
/ world video sources can be flagged correctly. Defaults to "user" (front).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: gsasson-sc

src/internal/sourceUtils.test.ts

@@ -351,6 +351,43 @@ describe("sourceUtils", () => {
       expect(mockCreateVideoSource).toHaveBeenCalledWith(videoElement, undefined);
     });
 
+    it("should pass cameraFacing through as cameraType", async () => {
+      const source = {
+        kind: "video" as const,
+        url: "https://example.com/video.mp4",
+        cameraFacing: "environment" as const,
+      };
+
+      const promise = createCameraKitSource(source);
+      videoElement.dispatchEvent(new Event("canplay"));
+      await promise;
+
+      expect(mockCreateVideoSource).toHaveBeenCalledWith(videoElement, { cameraType: "environment" });
+    });
+
+    it("should combine cameraFacing and tracking data", async () => {
+      const buffer = new ArrayBuffer(8);
+      (globalThis as { fetch?: typeof fetch }).fetch = jest
+        .fn()
+        .mockResolvedValue({ ok: true, arrayBuffer: () => Promise.resolve(buffer) }) as typeof fetch;
+
+      const source = {
+        kind: "video" as const,
+        url: "https://example.com/video.mp4",
+        trackingDataUrl: "https://example.com/clip.td",
+        cameraFacing: "environment" as const,
+      };
+
+      const promise = createCameraKitSource(source);
+      videoElement.dispatchEvent(new Event("canplay"));
+      await promise;
+
+      expect(mockCreateVideoSource).toHaveBeenCalledWith(videoElement, {
+        trackingData: buffer,
+        cameraType: "environment",
+      });
+    });
+
     it("should reject when tracking data fails to load", async () => {
       (globalThis as { fetch?: typeof fetch }).fetch = jest
         .fn()

src/internal/sourceUtils.ts

@@ -44,6 +44,7 @@ export async function createCameraKitSource(source: SourceInput): Promise<Source
       videoUrl: source.url,
       autoplay: source.autoplay,
       trackingDataUrl: source.trackingDataUrl,
+      cameraFacing: source.cameraFacing,
     });
   } else if (source.kind === "image") {
     return createCameraKitImageSource({
@@ -110,10 +111,12 @@ function createCameraKitVideoSource({
   videoUrl,
   autoplay,
   trackingDataUrl,
+  cameraFacing,
 }: {
   videoUrl: string;
   autoplay?: boolean;
   trackingDataUrl?: string;
+  cameraFacing?: CameraFacing;
 }) {
   return new Promise<SourceApplication>((res, rej) => {
     autoplay = autoplay ?? true;
@@ -135,8 +138,12 @@ function createCameraKitVideoSource({
           // before any playback has started, so there is no orphaned playing video to clean up.
           const trackingData = trackingDataUrl ? await fetchTrackingData(trackingDataUrl) : undefined;
           if (autoplay) await videoInput.play();
+          const videoSourceOptions =
+            trackingData || cameraFacing
+              ? { ...(trackingData ? { trackingData } : {}), ...(cameraFacing ? { cameraType: cameraFacing } : {}) }
+              : undefined;
           res({
-            cameraKitSource: createVideoSource(videoInput, trackingData ? { trackingData } : undefined),
+            cameraKitSource: createVideoSource(videoInput, videoSourceOptions),
             transform: Transform2D.Identity,
             inputSize: [videoInput.videoWidth, videoInput.videoHeight],
             initializedSourceInput: {

src/types.ts

@@ -55,6 +55,12 @@ export type VideoSourceInput = {
    * previewing world-facing lenses from a recorded environment.
    */
   trackingDataUrl?: string;
+  /**
+   * Camera the video should be treated as coming from. Passed to `createVideoSource` as `cameraType`,
+   * which surfaces to the lens (e.g. front/back-facing behavior) and engine tracking. Defaults to
+   * `"user"` (front). Set `"environment"` for back-facing / world content. `"user"` ↔ front, `"environment"` ↔ back.
+   */
+  cameraFacing?: CameraFacing;
 };
 export type ImageSourceInput = { kind: "image"; url: string };