Address review: add fpsLimit, simplify options, reword cameraFacing doc

- VideoSourceInput gains optional fpsLimit, passed to createVideoSource.
- Pass options object directly (createVideoSource defaults undefined fields).
- Reword cameraFacing doc per review.

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

Author: gsasson-sc

src/internal/sourceUtils.test.ts

@@ -348,7 +348,19 @@ describe("sourceUtils", () => {
       videoElement.dispatchEvent(new Event("canplay"));
       await promise;
 
-      expect(mockCreateVideoSource).toHaveBeenCalledWith(videoElement, undefined);
+      // createVideoSource is always called with an options object; trackingData is just undefined here.
+      const options = mockCreateVideoSource.mock.calls[0]?.[1];
+      expect(options?.trackingData).toBeUndefined();
+    });
+
+    it("should pass fpsLimit through", async () => {
+      const source = { kind: "video" as const, url: "https://example.com/video.mp4", fpsLimit: 30 };
+
+      const promise = createCameraKitSource(source);
+      videoElement.dispatchEvent(new Event("canplay"));
+      await promise;
+
+      expect(mockCreateVideoSource.mock.calls[0]?.[1]?.fpsLimit).toBe(30);
     });
 
     it("should pass cameraFacing through as cameraType", async () => {

src/internal/sourceUtils.ts

@@ -45,6 +45,7 @@ export async function createCameraKitSource(source: SourceInput): Promise<Source
       autoplay: source.autoplay,
       trackingDataUrl: source.trackingDataUrl,
       cameraFacing: source.cameraFacing,
+      fpsLimit: source.fpsLimit,
     });
   } else if (source.kind === "image") {
     return createCameraKitImageSource({
@@ -112,11 +113,13 @@ function createCameraKitVideoSource({
   autoplay,
   trackingDataUrl,
   cameraFacing,
+  fpsLimit,
 }: {
   videoUrl: string;
   autoplay?: boolean;
   trackingDataUrl?: string;
   cameraFacing?: CameraFacing;
+  fpsLimit?: number;
 }) {
   return new Promise<SourceApplication>((res, rej) => {
     autoplay = autoplay ?? true;
@@ -138,12 +141,8 @@ 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, videoSourceOptions),
+            cameraKitSource: createVideoSource(videoInput, { trackingData, cameraType: cameraFacing, fpsLimit }),
             transform: Transform2D.Identity,
             inputSize: [videoInput.videoWidth, videoInput.videoHeight],
             initializedSourceInput: {

src/types.ts

@@ -56,11 +56,16 @@ export type VideoSourceInput = {
    */
   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.
+   * Front/rear camera semantic the video should be treated as. Passed to CameraKit as `cameraType`,
+   * which affects Lens feature behavior such as surface tracking. Defaults to "user".
+   * "user" is front-facing; "environment" is rear-facing.
    */
   cameraFacing?: CameraFacing;
+  /**
+   * Optional cap on frames per second processed from the video. Passed to `createVideoSource` as
+   * `fpsLimit`. Defaults to the video's native frame rate when omitted.
+   */
+  fpsLimit?: number;
 };
 export type ImageSourceInput = { kind: "image"; url: string };