@flighthq/webcam 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from './webcam';
+export * from './webcamStream';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,gBAAgB,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export * from './webcam';
+export * from './webcamStream';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,gBAAgB,CAAC"}

package/dist/webcam.d.ts

@@ -0,0 +1,9 @@
+import type { WebcamBackend, WebcamCaptureOptions, WebcamPhoto, WebcamVideo } from '@flighthq/types';
+export declare function createWebWebcamBackend(): WebcamBackend;
+export declare function getWebcamBackend(): WebcamBackend;
+export declare function recordWebcamVideo(options?: Readonly<WebcamCaptureOptions>): Promise<WebcamVideo | null>;
+export declare function requestWebcamPermission(): Promise<boolean>;
+export declare function selectWebcamImage(options?: Readonly<WebcamCaptureOptions>): Promise<WebcamPhoto | null>;
+export declare function setWebcamBackend(backend: WebcamBackend | null): void;
+export declare function takeWebcamPhoto(options?: Readonly<WebcamCaptureOptions>): Promise<WebcamPhoto | null>;
+//# sourceMappingURL=webcam.d.ts.map

package/dist/webcam.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webcam.d.ts","sourceRoot":"","sources":["../src/webcam.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,oBAAoB,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAKrG,wBAAgB,sBAAsB,IAAI,aAAa,CAsFtD;AAGD,wBAAgB,gBAAgB,IAAI,aAAa,CAGhD;AAGD,wBAAgB,iBAAiB,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,oBAAoB,CAAC,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAEvG;AAGD,wBAAgB,uBAAuB,IAAI,OAAO,CAAC,OAAO,CAAC,CAE1D;AAGD,wBAAgB,iBAAiB,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,oBAAoB,CAAC,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAEvG;AAGD,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,aAAa,GAAG,IAAI,GAAG,IAAI,CAEpE;AAGD,wBAAgB,eAAe,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,oBAAoB,CAAC,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAErG"}

package/dist/webcam.js

@@ -0,0 +1,125 @@
+// Builds the default web backend over a transient <input type="file">. capture resolves to null when
+// the document is absent (jsdom), the user cancels, or the file cannot be read — capture is not
+// guaranteed. Real pixel dimensions are not decoded; width/height resolve to 0.
+export function createWebWebcamBackend() {
+    return {
+        capture(options) {
+            return new Promise((resolve) => {
+                if (typeof document === 'undefined' || typeof document.createElement !== 'function') {
+                    resolve(null);
+                    return;
+                }
+                try {
+                    const input = document.createElement('input');
+                    input.type = 'file';
+                    input.accept = 'image/*';
+                    if (options.source === 'camera')
+                        input.capture = 'environment';
+                    input.onchange = () => {
+                        const file = input.files?.[0] ?? null;
+                        if (file === null) {
+                            resolve(null);
+                            return;
+                        }
+                        const reader = new FileReader();
+                        reader.onload = () => {
+                            resolve({
+                                dataUrl: typeof reader.result === 'string' ? reader.result : '',
+                                width: 0,
+                                height: 0,
+                                format: file.type,
+                            });
+                        };
+                        reader.onerror = () => resolve(null);
+                        reader.readAsDataURL(file);
+                    };
+                    input.click();
+                }
+                catch {
+                    resolve(null);
+                }
+            });
+        },
+        captureVideo(options) {
+            return new Promise((resolve) => {
+                if (typeof document === 'undefined' || typeof document.createElement !== 'function') {
+                    resolve(null);
+                    return;
+                }
+                try {
+                    const input = document.createElement('input');
+                    input.type = 'file';
+                    input.accept = 'video/*';
+                    if (options.source === 'camera')
+                        input.capture = 'environment';
+                    input.onchange = () => {
+                        const file = input.files?.[0] ?? null;
+                        if (file === null) {
+                            resolve(null);
+                            return;
+                        }
+                        const reader = new FileReader();
+                        reader.onload = () => {
+                            resolve({
+                                dataUrl: typeof reader.result === 'string' ? reader.result : '',
+                                // The web file input cannot decode the clip; native hosts report a real duration.
+                                duration: 0,
+                                format: file.type,
+                            });
+                        };
+                        reader.onerror = () => resolve(null);
+                        reader.readAsDataURL(file);
+                    };
+                    input.click();
+                }
+                catch {
+                    resolve(null);
+                }
+            });
+        },
+        async requestPermission() {
+            // The Permissions API only reports state; it does not prompt. A native host performs a real
+            // permission request. Returns false when the API is absent (jsdom, older browsers) or denied.
+            if (typeof navigator === 'undefined')
+                return false;
+            try {
+                const permissions = navigator.permissions;
+                if (permissions === undefined || typeof permissions.query !== 'function')
+                    return false;
+                const status = await permissions.query({ name: 'camera' });
+                return status.state === 'granted';
+            }
+            catch {
+                return false;
+            }
+        },
+    };
+}
+// The active camera backend, or a lazily-created web default. There is always a backend.
+export function getWebcamBackend() {
+    if (_backend === null)
+        _backend = createWebWebcamBackend();
+    return _backend;
+}
+// Records a video from the device camera. Resolves null when cancelled, denied, or unavailable.
+export function recordWebcamVideo(options) {
+    return getWebcamBackend().captureVideo({ ...options, source: 'camera' });
+}
+// Requests camera access permission. Resolves false when denied or when the host cannot prompt.
+export function requestWebcamPermission() {
+    return getWebcamBackend().requestPermission();
+}
+// Picks an existing image from the photo library. Resolves null when cancelled or unavailable.
+export function selectWebcamImage(options) {
+    return getWebcamBackend().capture({ ...options, source: 'photos' });
+}
+// Installs a native host camera backend; pass null to fall back to the web default.
+export function setWebcamBackend(backend) {
+    _backend = backend;
+}
+// Captures a photo from the device camera. Resolves null when cancelled, denied, or unavailable.
+export function takeWebcamPhoto(options) {
+    return getWebcamBackend().capture({ ...options, source: 'camera' });
+}
+let _backend = null;
+//# sourceMappingURL=webcam.js.map

package/dist/webcam.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"webcam.js","sourceRoot":"","sources":["../src/webcam.ts"],"names":[],"mappings":"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"}

package/dist/webcamStream.d.ts

@@ -0,0 +1,17 @@
+import type { EntityRuntime, WebcamFacingMode, WebcamStream } from '@flighthq/types';
+export interface WebcamStreamRuntime extends EntityRuntime {
+    binding: null;
+    mediaStream: MediaStream | null;
+    videoElement: HTMLVideoElement | null;
+}
+export declare function createWebcamStreamEntity(data: {
+    active: boolean;
+    deviceId: string;
+    facingMode: WebcamFacingMode | null;
+    frameRate: number;
+    height: number;
+    id: string;
+    width: number;
+}): WebcamStream;
+export declare function getWebcamStreamRuntime(stream: Readonly<WebcamStream>): WebcamStreamRuntime | null;
+//# sourceMappingURL=webcamStream.d.ts.map

package/dist/webcamStream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webcamStream.d.ts","sourceRoot":"","sources":["../src/webcamStream.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAGrF,MAAM,WAAW,mBAAoB,SAAQ,aAAa;IACxD,OAAO,EAAE,IAAI,CAAC;IAEd,WAAW,EAAE,WAAW,GAAG,IAAI,CAAC;IAChC,YAAY,EAAE,gBAAgB,GAAG,IAAI,CAAC;CACvC;AAKD,wBAAgB,wBAAwB,CAAC,IAAI,EAAE;IAC7C,MAAM,EAAE,OAAO,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,gBAAgB,GAAG,IAAI,CAAC;IACpC,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;CACf,GAAG,YAAY,CAoBf;AAGD,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,QAAQ,CAAC,YAAY,CAAC,GAAG,mBAAmB,GAAG,IAAI,CAIjG"}

package/dist/webcamStream.js

@@ -0,0 +1,34 @@
+import { createEntity } from '@flighthq/entity';
+import { EntityRuntimeKey } from '@flighthq/types';
+// Allocates a WebcamStream entity with an attached runtime slot holding the MediaStream.
+// The fields in data become the entity's public fields; the runtime is initialized with a
+// placeholder MediaStream that is replaced immediately by the caller.
+export function createWebcamStreamEntity(data) {
+    const stream = createEntity({
+        active: data.active,
+        deviceId: data.deviceId,
+        facingMode: data.facingMode,
+        frameRate: data.frameRate,
+        height: data.height,
+        id: data.id,
+        width: data.width,
+    });
+    // Initialize with null; the caller overwrites rt.mediaStream once a live stream is acquired. Using
+    // null (not new MediaStream()) avoids depending on MediaStream in environments that lack it (jsdom
+    // without the media API).
+    const rt = {
+        binding: null,
+        mediaStream: null,
+        videoElement: null,
+    };
+    stream[EntityRuntimeKey] = rt;
+    return stream;
+}
+// Returns the WebcamStreamRuntime attached to stream, or null when stream has no runtime.
+export function getWebcamStreamRuntime(stream) {
+    const rt = stream[EntityRuntimeKey];
+    if (rt === undefined || rt === null)
+        return null;
+    return rt;
+}
+//# sourceMappingURL=webcamStream.js.map

package/dist/webcamStream.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"webcamStream.js","sourceRoot":"","sources":["../src/webcamStream.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAEhD,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AASnD,yFAAyF;AACzF,0FAA0F;AAC1F,sEAAsE;AACtE,MAAM,UAAU,wBAAwB,CAAC,IAQxC;IACC,MAAM,MAAM,GAAG,YAAY,CAAC;QAC1B,MAAM,EAAE,IAAI,CAAC,MAAM;QACnB,QAAQ,EAAE,IAAI,CAAC,QAAQ;QACvB,UAAU,EAAE,IAAI,CAAC,UAAU;QAC3B,SAAS,EAAE,IAAI,CAAC,SAAS;QACzB,MAAM,EAAE,IAAI,CAAC,MAAM;QACnB,EAAE,EAAE,IAAI,CAAC,EAAE;QACX,KAAK,EAAE,IAAI,CAAC,KAAK;KAClB,CAAC,CAAC;IACH,mGAAmG;IACnG,mGAAmG;IACnG,0BAA0B;IAC1B,MAAM,EAAE,GAAwB;QAC9B,OAAO,EAAE,IAAI;QACb,WAAW,EAAE,IAAI;QACjB,YAAY,EAAE,IAAI;KACnB,CAAC;IACF,MAAM,CAAC,gBAAgB,CAAC,GAAG,EAAE,CAAC;IAC9B,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,0FAA0F;AAC1F,MAAM,UAAU,sBAAsB,CAAC,MAA8B;IACnE,MAAM,EAAE,GAAG,MAAM,CAAC,gBAAgB,CAAC,CAAC;IACpC,IAAI,EAAE,KAAK,SAAS,IAAI,EAAE,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IACjD,OAAO,EAAyB,CAAC;AACnC,CAAC"}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@flighthq/webcam",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src/**/*.test.ts",
+    "!dist/**/*.test.js",
+    "!dist/**/*.test.d.ts",
+    "!dist/**/*.test.js.map",
+    "!dist/**/*.test.d.ts.map"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "clean": "tsc -b --clean",
+    "test": "vitest run --config vitest.config.ts",
+    "test:watch": "vitest --watch --config vitest.config.ts",
+    "prepack": "npm run clean && npm run clean:dist && npm run build",
+    "clean:dist": "tsx ../../scripts/clean-package-dist.ts"
+  },
+  "dependencies": {
+    "@flighthq/entity": "0.1.0",
+    "@flighthq/types": "0.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.0"
+  },
+  "description": "Webcam capture and photo picking over a swappable web/native backend",
+  "sideEffects": false
+}

package/src/webcam.test.ts

@@ -0,0 +1,103 @@
+import type { WebcamBackend, WebcamCaptureOptions } from '@flighthq/types';
+
+import {
+  createWebWebcamBackend,
+  getWebcamBackend,
+  recordWebcamVideo,
+  requestWebcamPermission,
+  selectWebcamImage,
+  setWebcamBackend,
+  takeWebcamPhoto,
+} from './webcam';
+
+function fakeBackend(): WebcamBackend & { lastOptions: WebcamCaptureOptions | null } {
+  return {
+    lastOptions: null,
+    async capture(options) {
+      this.lastOptions = { ...options };
+      return { dataUrl: 'data:image/png;base64,xx', width: 0, height: 0, format: 'image/png' };
+    },
+    async captureVideo(options) {
+      this.lastOptions = { ...options };
+      return { dataUrl: 'data:video/mp4;base64,xx', duration: 0, format: 'video/mp4' };
+    },
+    async requestPermission() {
+      return true;
+    },
+  };
+}
+
+afterEach(() => setWebcamBackend(null));
+
+describe('createWebWebcamBackend', () => {
+  it('returns a backend whose capture yields a Promise without throwing synchronously', () => {
+    const backend = createWebWebcamBackend();
+    expect(backend.capture({}) instanceof Promise).toBe(true);
+  });
+});
+
+describe('getWebcamBackend', () => {
+  it('falls back to a web backend', () => {
+    expect(getWebcamBackend()).not.toBeNull();
+  });
+
+  it('returns the registered backend', () => {
+    const backend = fakeBackend();
+    setWebcamBackend(backend);
+    expect(getWebcamBackend()).toBe(backend);
+  });
+});
+
+describe('recordWebcamVideo', () => {
+  it('captures video with the camera source', async () => {
+    const backend = fakeBackend();
+    setWebcamBackend(backend);
+    const video = await recordWebcamVideo({ maxDurationMs: 5000 });
+    expect(video).not.toBeNull();
+    expect(backend.lastOptions).toEqual({ maxDurationMs: 5000, source: 'camera' });
+  });
+
+  it('returns a Promise from the web backend without throwing', () => {
+    const backend = createWebWebcamBackend();
+    expect(backend.captureVideo({}) instanceof Promise).toBe(true);
+  });
+});
+
+describe('requestWebcamPermission', () => {
+  it('delegates to the active backend', async () => {
+    setWebcamBackend(fakeBackend());
+    expect(await requestWebcamPermission()).toBe(true);
+  });
+
+  it('returns a boolean from the web backend without throwing', async () => {
+    expect(typeof (await requestWebcamPermission())).toBe('boolean');
+  });
+});
+
+describe('selectWebcamImage', () => {
+  it('captures with the photos source', async () => {
+    const backend = fakeBackend();
+    setWebcamBackend(backend);
+    const photo = await selectWebcamImage({ quality: 0.5 });
+    expect(photo).not.toBeNull();
+    expect(backend.lastOptions).toEqual({ quality: 0.5, source: 'photos' });
+  });
+});
+
+describe('setWebcamBackend', () => {
+  it('clears back to the web fallback when passed null', () => {
+    setWebcamBackend(fakeBackend());
+    setWebcamBackend(null);
+    expect(getWebcamBackend()).not.toBeNull();
+  });
+});
+
+describe('takeWebcamPhoto', () => {
+  it('captures with the camera source', async () => {
+    const backend = fakeBackend();
+    setWebcamBackend(backend);
+    const photo = await takeWebcamPhoto({ allowEditing: true });
+    expect(photo).not.toBeNull();
+    expect(backend.lastOptions).toEqual({ allowEditing: true, source: 'camera' });
+  });
+});

package/src/webcamStream.test.ts

@@ -0,0 +1,86 @@
+import type { WebcamStream } from '@flighthq/types';
+import { EntityRuntimeKey } from '@flighthq/types';
+
+import { createWebcamStreamEntity, getWebcamStreamRuntime } from './webcamStream';
+
+describe('createWebcamStreamEntity', () => {
+  it('creates a WebcamStream with the correct public fields', () => {
+    const stream = createWebcamStreamEntity({
+      active: true,
+      deviceId: 'device-1',
+      facingMode: 'environment',
+      frameRate: 30,
+      height: 480,
+      id: 'stream-123',
+      width: 640,
+    });
+    expect(stream.active).toBe(true);
+    expect(stream.deviceId).toBe('device-1');
+    expect(stream.facingMode).toBe('environment');
+    expect(stream.frameRate).toBe(30);
+    expect(stream.height).toBe(480);
+    expect(stream.id).toBe('stream-123');
+    expect(stream.width).toBe(640);
+  });
+
+  it('attaches a runtime slot to the entity', () => {
+    const stream = createWebcamStreamEntity({
+      active: true,
+      deviceId: '',
+      facingMode: null,
+      frameRate: 0,
+      height: 0,
+      id: 'x',
+      width: 0,
+    });
+    expect(stream[EntityRuntimeKey]).not.toBeUndefined();
+  });
+
+  it('runtime slot is initialized (mediaStream placeholder is present)', () => {
+    const stream = createWebcamStreamEntity({
+      active: false,
+      deviceId: '',
+      facingMode: null,
+      frameRate: 0,
+      height: 0,
+      id: 'x',
+      width: 0,
+    });
+    const rt = getWebcamStreamRuntime(stream);
+    expect(rt).not.toBeNull();
+    // mediaStream starts null; the caller attaches a live stream before use.
+    expect(rt?.mediaStream).toBeNull();
+    expect(rt?.videoElement).toBeNull();
+  });
+});
+
+describe('getWebcamStreamRuntime', () => {
+  it('returns null for a stream without a runtime', () => {
+    const stream = {
+      active: true,
+      deviceId: '',
+      facingMode: null,
+      frameRate: 0,
+      height: 0,
+      id: 'x',
+      width: 0,
+      [EntityRuntimeKey]: undefined,
+    } as WebcamStream;
+    expect(getWebcamStreamRuntime(stream)).toBeNull();
+  });
+
+  it('returns the runtime for a stream created by createWebcamStreamEntity', () => {
+    const stream = createWebcamStreamEntity({
+      active: true,
+      deviceId: 'dev',
+      facingMode: 'user',
+      frameRate: 60,
+      height: 720,
+      id: 'stream-rt',
+      width: 1280,
+    });
+    const rt = getWebcamStreamRuntime(stream);
+    expect(rt).not.toBeNull();
+    expect(rt?.videoElement).toBeNull();
+  });
+});