@octane-xplat/camera 0.12.0 → 0.14.0

package/types/index.d.ts

@@ -1,5 +1,48 @@
 import type { UniversalComponent } from 'octane/universal'
 import type { CameraViewProps } from './props.js'
+import type { CameraSession, CameraSessionConfig } from './types.js'
+import type { SyntheticCameraScript, SyntheticCameraStorage } from './synthetic-session.js'
 
 export declare const CameraView: UniversalComponent<CameraViewProps>
 export type { CameraViewHandle, CameraViewProps, CameraAccessibilityRole } from './props.js'
+
+export declare function createCameraSession(config?: CameraSessionConfig): CameraSession
+export declare function createSyntheticCameraSession(
+	config?: CameraSessionConfig,
+	script?: Partial<SyntheticCameraScript>,
+	storage?: SyntheticCameraStorage,
+): CameraSession
+
+export declare function createMemoryCameraStorage(): SyntheticCameraStorage & {
+	files: Map<string, Uint8Array>
+}
+
+export { CameraCaptureError } from './types.js'
+export type {
+	CameraCaptureErrorKind,
+	CameraDeviceInfo,
+	CameraFacing,
+	CameraInterruptionReason,
+	CameraOrientation,
+	CameraPermissionKind,
+	CameraPermissionStatus,
+	CameraProfileCapability,
+	CameraRecorderState,
+	CameraSelection,
+	CameraSession,
+	CameraSessionCapabilities,
+	CameraSessionConfig,
+	CameraSessionEvent,
+	CameraSessionSnapshot,
+	CaptureIssue,
+	EffectiveCaptureConfig,
+	MovieClip,
+	MovieEndReason,
+	MovieOutcome,
+	MovieOutput,
+	MovieOutputHandle,
+	MovieTake,
+	StartRecordingOptions,
+} from './types.js'
+
+export type { SyntheticCameraScript, SyntheticCameraStorage } from './synthetic-session.js'

package/types/props.d.ts

@@ -1,4 +1,5 @@
 import type { Octane } from 'octane/jsx-runtime';
+import type { CameraSession } from './types';
 export type CameraAccessibilityRole = 'button' | 'link' | 'search' | 'image' | 'heading' | 'adjustable' | 'summary' | 'text' | 'none' | 'progressbar' | 'checkbox' | 'switch' | 'radio' | 'spinbutton' | 'tab';
 export interface CameraViewHandle {
     /** The native preview surface (`HTMLVideoElement` on web). */
@@ -30,7 +31,11 @@ export interface CameraViewProps {
         checked?: boolean;
     };
     accessibilityLiveRegion?: 'none' | 'polite' | 'assertive';
-    /** Lens — defaults to the rear camera. */
+    /** Shared camera owner enabling movie recording. When set, the preview
+     *  attaches to the session's acquisition instead of owning one, and
+     *  `facing` must be omitted — camera selection lives on the session. */
+    session?: CameraSession;
+    /** Lens — defaults to the rear camera. Invalid together with `session`. */
     facing?: 'front' | 'back';
     /** Default true. False releases the preview session. */
     active?: boolean;
@@ -45,4 +50,5 @@ export interface CameraViewProps {
     ios?: Record<string, any>;
     android?: Record<string, any>;
     web?: Record<string, any>;
+    windows?: Record<string, any>;
 }

package/types/session-core.d.ts

@@ -0,0 +1,129 @@
+import type { CameraInterruptionReason, CameraPermissionKind, CameraPermissionStatus, CameraSession, CameraSessionCapabilities, CameraSessionConfig, CameraSessionEvent, CameraSessionSnapshot, CaptureIssue, EffectiveCaptureConfig, MovieEndReason, MovieOutput, MovieOutputHandle, MovieTake, StartRecordingOptions } from './types';
+/** Result an adapter reports when a capture attempt settles. Media
+ *  metadata is already read from the finalized movie by the adapter. */
+export type BackendSettle = {
+    kind: 'clip';
+    output: MovieOutput;
+    mimeType: string;
+    durationMs: number;
+    width: number;
+    height: number;
+    orientation: EffectiveCaptureConfig['orientation'];
+    hasAudio: boolean;
+    /** Native duration-limit enforcement ended the take. */
+    limitReached?: boolean;
+    /** Adapter-driven endings when no earlier app/lifecycle cause exists. */
+    endReason?: MovieEndReason;
+    warning?: CaptureIssue;
+} | {
+    kind: 'failed';
+    stage: 'preparation' | 'capture' | 'finalization' | 'storage';
+    issue: CaptureIssue;
+};
+/** Per-attempt callbacks handed to `startCapture`. */
+export interface BackendCaptureSink {
+    /** Native capture actually began; exactly once per settled attempt. */
+    started(config: EffectiveCaptureConfig): void;
+    /** Capture has ended; metadata verification and storage still own the attempt. */
+    finishing(reason?: MovieEndReason): void;
+    /** Terminal result; exactly once per admitted attempt. */
+    settled(result: BackendSettle): void;
+}
+export interface BackendCaptureRequest {
+    audio: boolean;
+    orientation: EffectiveCaptureConfig['orientation'] | undefined;
+    maximumDurationMs: number | undefined;
+    /** Resolved writable path for native adapters. */
+    destinationPath: string | undefined;
+}
+/** Adapter-owned preview attach. `listener` reports preview lifecycle;
+ *  returns the detach function. */
+export interface BackendPreviewListener {
+    onReady?: () => void;
+    onError?: (issue: CaptureIssue) => void;
+}
+/** Platform adapter surface driven by the shared session core. Adapters
+ *  own permission policy, capability discovery, capture, and local output
+ *  access; the core owns states, ordering, causes, and outcomes. */
+export interface CameraSessionBackend {
+    readonly platform: string;
+    /** False when the adapter cannot capture on this host; the core
+     *  rejects `startRecording` with `unsupportedPlatform`. */
+    readonly supported: boolean;
+    checkPermission(kind: CameraPermissionKind): Promise<CameraPermissionStatus>;
+    requestPermission(kind: CameraPermissionKind): Promise<CameraPermissionStatus>;
+    getCapabilities(): Promise<CameraSessionCapabilities>;
+    /** An active, ready preview is attached and the camera source is
+     *  running — the admission requirement for `startRecording`. */
+    previewReady(): boolean;
+    /** Attach the shared-source preview to a platform view. */
+    attachPreview(host: unknown, listener?: BackendPreviewListener): () => void;
+    /** Replace configuration while idle; throws CameraCaptureError. */
+    configure?(config: CameraSessionConfig): void;
+    /** Synchronous platform-specific admission checks; creates no attempt on failure. */
+    validateStart?(options: StartRecordingOptions): void;
+    /** Begin capture for an admitted attempt. Async failures settle via
+     *  `sink.settled`; a synchronous throw settles as a preparation failure. */
+    startCapture(request: BackendCaptureRequest, sink: BackendCaptureSink): void;
+    /** Request capture stop; settlement still arrives via the sink. */
+    stopCapture(): void;
+    /** Elapsed capture time in ms for the in-flight attempt. */
+    elapsedMs(): number;
+    openOutput(output: MovieOutput): Promise<MovieOutputHandle>;
+    /** Release camera ownership. The core calls this only after any
+     *  in-flight attempt has settled. */
+    release(): Promise<void>;
+    /** Reattach/reconfigure bookkeeping when the preview view is detached
+     *  while an attempt is settling — the adapter keeps hardware until
+     *  settlement, then stops. */
+    onPreviewDetached?(): void;
+    /** Lifecycle observations the adapter emits at any time. */
+    setObserver(observer: BackendObserver | undefined): void;
+}
+export interface BackendObserver {
+    interruption(phase: 'began' | 'ended', reason?: CameraInterruptionReason): void;
+    availability(available: boolean): void;
+    /** Preview became ready/unready (session running state changed). */
+    previewReady(ready: boolean): void;
+}
+/** The concrete session object wrapping a platform backend. Internal to
+ *  the package; `CameraSession` is the public shape. */
+export declare class SharedCameraSession implements CameraSession {
+    private backend;
+    private config;
+    private listeners;
+    private state;
+    private permission;
+    private cameraAvailable;
+    private previewAttached;
+    private interrupted;
+    private disposeRequested;
+    private disposed;
+    private lastCapabilities;
+    private requestChains;
+    private attempt;
+    constructor(backend: CameraSessionBackend, config: CameraSessionConfig);
+    /** Package-internal: attach a preview host to this session. */
+    attach(host: unknown, listener?: BackendPreviewListener): () => void;
+    get attached(): boolean;
+    private detachInternal;
+    private emit;
+    private setState;
+    snapshot(): CameraSessionSnapshot;
+    subscribe(listener: (event: CameraSessionEvent) => void): () => void;
+    permissions(): Promise<{
+        camera: CameraPermissionStatus;
+        microphone: CameraPermissionStatus;
+    }>;
+    requestPermission(kind: CameraPermissionKind): Promise<CameraPermissionStatus>;
+    capabilities(): Promise<CameraSessionCapabilities>;
+    configure(next: Partial<CameraSessionConfig>): Promise<void>;
+    private validateCameraSelection;
+    private requestStop;
+    private handleInterruption;
+    private handleAvailability;
+    startRecording(options?: StartRecordingOptions): MovieTake;
+    openOutput(output: MovieOutput): Promise<MovieOutputHandle>;
+    dispose(): Promise<void>;
+    private finishDispose;
+}

package/types/synthetic-session.d.ts

@@ -0,0 +1,48 @@
+import type { CameraInterruptionReason, CameraPermissionStatus, CameraSession, CameraSessionConfig } from './types';
+/** Development/testing seam — a deterministic camera source that drives
+ *  the shared session state machine without hardware. NOT a production
+ *  recording source: outcomes carry `synthetic: true` on their output so
+ *  seam clips stay distinguishable from real capture.
+ *
+ *  `script` is read live at each transition — mutate fields between
+ *  operations to script permissions, delayed starts, interruptions,
+ *  partial completions, and failures.
+ */
+export interface SyntheticCameraScript {
+    permission: {
+        camera: CameraPermissionStatus;
+        microphone: CameraPermissionStatus;
+    };
+    /** Camera hardware availability observation. */
+    available: boolean;
+    /** Delay before `started` reports; models slow native activation. */
+    startDelayMs: number;
+    /** Finalized clip duration reported by the seam. */
+    clipDurationMs: number;
+    /** Produce a usable clip on stop; false settles `noMedia`. */
+    produceMedia: boolean;
+    /** When set, the attempt settles failed at this stage. */
+    failAt?: 'start' | 'capture' | 'finalize' | 'storage';
+    /** Emit an interruption after this many ms of recording; the take
+     *  ends with the mapped end reason and a partial clip. */
+    interruption?: {
+        afterMs: number;
+        reason: CameraInterruptionReason;
+        endsAfterMs?: number;
+    };
+}
+export interface SyntheticCameraStorage {
+    write(path: string, bytes: Uint8Array): void | Promise<void>;
+    read(path: string): Uint8Array | undefined | Promise<Uint8Array | undefined>;
+    delete?(path: string): void | Promise<void>;
+    exists?(path: string): boolean | Promise<boolean>;
+}
+/** In-memory storage for the seam — a `fileUrl`-shaped map so outcomes
+ *  exercise the same reopen path without touching a real filesystem. */
+export declare function createMemoryCameraStorage(): SyntheticCameraStorage & {
+    files: Map<string, Uint8Array>;
+};
+/** Create a `CameraSession` backed by the deterministic synthetic source.
+ *  Marked for development and testing — never present this as live
+ *  capture to users. */
+export declare function createSyntheticCameraSession(config?: CameraSessionConfig, script?: Partial<SyntheticCameraScript>, storage?: SyntheticCameraStorage): CameraSession;

package/types/types.d.ts

@@ -0,0 +1,263 @@
+/** Shared camera-session and movie-recording contract.
+ *
+ *  A `CameraSession` owns one camera acquisition shared between a
+ *  `CameraView` preview and at most one movie-recording attempt. Recording
+ *  settles with an immutable `MovieOutcome` only after the local movie is
+ *  finalized and its metadata is known — a returned clip is always
+ *  reopenable through `openOutput`.
+ *
+ *  This module is platform-pure: adapters implement
+ *  `CameraSessionBackend` per host. Adapters that do not support capture
+ *  yet report `supported: false` and reject `startRecording` with
+ *  `unsupportedPlatform` instead of fabricating behavior.
+ */
+/** Permission resource a `CameraSession` can inspect or request. */
+export type CameraPermissionKind = 'camera' | 'microphone';
+/** Portable authorization state. Checking never prompts. `blocked` and
+ *  `unknown` exist so hosts that cannot distinguish user denial from
+ *  policy refusal do not fabricate `restricted`. */
+export type CameraPermissionStatus = 'notDetermined' | 'granted' | 'denied' | 'restricted' | 'blocked' | 'unknown' | 'unavailable';
+/** Portable error categories. `unsupported*` covers missing host features,
+ *  devices, or capture configurations — including adapters that are not
+ *  implemented yet during staged delivery. */
+export type CameraCaptureErrorKind = 'permissionDenied' | 'permissionRestricted' | 'permissionBlocked' | 'unsupportedPlatform' | 'unsupportedConfiguration' | 'unavailable' | 'busy' | 'invalidState' | 'invalidArgument' | 'destinationUnavailable' | 'insufficientStorage' | 'noMedia' | 'captureFailed' | 'finalizationFailed' | 'storageFailed' | 'configurationMissing';
+/** Structured diagnostic carried by failures and non-fatal warnings. */
+export interface CaptureIssue {
+    kind: CameraCaptureErrorKind;
+    /** Operation being attempted, e.g. 'startRecording', 'finalize'. */
+    operation: string;
+    message: string;
+    permission?: CameraPermissionKind;
+    /** Host-specific detail for logging; never required for control flow. */
+    cause?: unknown;
+}
+/** Error thrown or settled by the session API. Satisfies `CaptureIssue`
+ *  so `error.kind` drives control flow without unwrapping. */
+export declare class CameraCaptureError extends Error implements CaptureIssue {
+    kind: CameraCaptureErrorKind;
+    operation: string;
+    permission?: CameraPermissionKind;
+    cause?: unknown;
+    constructor(issue: Omit<CaptureIssue, 'cause'> & {
+        cause?: unknown;
+    });
+}
+export type CameraFacing = 'front' | 'back';
+export type CameraOrientation = 'portrait' | 'portraitUpsideDown' | 'landscapeLeft' | 'landscapeRight' | 'unspecified';
+/** Camera selection for `CameraSessionConfig.camera`. Desktop and browser
+ *  hosts expose device identities instead of front/back semantics. */
+export type CameraSelection = 'default' | 'front' | 'back' | {
+    deviceId: string;
+};
+export interface CameraSessionConfig {
+    /** Lens or device identity. Default `'default'`: rear when available. */
+    camera?: CameraSelection;
+    /** Include an audio track; requires microphone permission. Default
+     *  false — silent capture is a deliberate app choice, never a
+     *  fallback from denied microphone access. */
+    audio?: boolean;
+    /** Capture profile. `'standard'` targets 720p at 30 fps and may select
+     *  a device-supported alternative; the started attempt discloses the
+     *  actual configuration. */
+    profile?: 'standard';
+}
+/** Resolution/frame-rate combination advertised by capability discovery.
+ *  Entries are supported combinations, not independent lists. */
+export interface CameraProfileCapability {
+    profile: 'standard';
+    width: number;
+    height: number;
+    frameRate: number;
+}
+export interface CameraDeviceInfo {
+    id: string;
+    label: string;
+    facing?: CameraFacing;
+}
+/** What the session's host can do right now. `supported: false` means the
+ *  adapter or host cannot record (reason explains); `available` reflects
+ *  current hardware/permission state and changes over time. */
+export interface CameraSessionCapabilities {
+    supported: boolean;
+    /** Why capture is unsupported or currently unavailable. */
+    reason?: string;
+    available: boolean;
+    cameras: CameraDeviceInfo[];
+    profiles: CameraProfileCapability[];
+    /** The session can add an audio track when permission allows. */
+    audio: boolean;
+    /** Fixed orientations the source can lock for a take. */
+    orientations: CameraOrientation[];
+    /** `native` enforcement can still overshoot at media boundaries;
+     *  `bestEffort` limits are scheduled and may overshoot more. */
+    durationLimit: 'native' | 'bestEffort';
+    /** Where `elapsedMs` comes from while recording. */
+    elapsedTime: 'nativeMedia' | 'estimated';
+    output: {
+        mimeType: string;
+        container: string;
+        /** `appPrivateFile` output survives dispose and app restart;
+         *  `originLocal` is browser storage subject to site-data clearing. */
+        storage: 'appPrivateFile' | 'originLocal';
+        /** Accepts an app-supplied `destinationFileUrl` on start. */
+        destinationFileUrl: boolean;
+    };
+}
+export type CameraRecorderState = 'idle' | 'starting' | 'recording' | 'finalizing' | 'disposed';
+/** Frozen capture configuration reported once capture actually begins. */
+export interface EffectiveCaptureConfig {
+    cameraId: string;
+    facing?: CameraFacing;
+    audio: boolean;
+    width: number;
+    height: number;
+    frameRate: number;
+    orientation: CameraOrientation;
+    mimeType: string;
+    container: string;
+}
+export interface CameraSessionSnapshot {
+    state: CameraRecorderState;
+    /** Non-prompting last-known authorization, refreshed by `permissions()`
+     *  and `requestPermission()`. */
+    permission: Record<CameraPermissionKind, CameraPermissionStatus>;
+    /** Camera hardware/driver availability, separate from recorder state. */
+    cameraAvailable: boolean;
+    /** An active preview view is attached to this session. */
+    previewAttached: boolean;
+    interrupted: boolean;
+    attempt?: {
+        id: string;
+        state: 'starting' | 'recording' | 'finalizing';
+        elapsedMs: number;
+        configuration?: EffectiveCaptureConfig;
+    };
+}
+/** What ended a capture attempt. `interrupted` covers system suspension
+ *  and preview teardown; `previewReleased` distinguishes an app-driven
+ *  deactivation from an OS interruption. */
+export type MovieEndReason = 'stopped' | 'maximumDuration' | 'interrupted' | 'backgrounded' | 'cameraUnavailable' | 'previewReleased' | 'disposed' | 'captureError';
+/** Portable completed-output reference. `resourceId` reopens the clip
+ *  through `openOutput`; `fileUrl` additionally guarantees file-backed
+ *  native output. `synthetic` marks test-seam clips. */
+export type MovieOutput = {
+    kind: 'nativeFile';
+    resourceId: string;
+    fileUrl: string;
+    synthetic?: boolean;
+} | {
+    kind: 'browserStorage';
+    resourceId: string;
+    retention: 'persistent' | 'bestEffort';
+    synthetic?: boolean;
+};
+export interface MovieClip {
+    output: MovieOutput;
+    mimeType: string;
+    /** Authoritative duration read from the finalized movie. */
+    durationMs: number;
+    /** Presentation dimensions after the orientation transform. */
+    width: number;
+    height: number;
+    orientation: CameraOrientation;
+    /** Whether the finalized movie actually contains an audio track.
+     *  Missing requested audio is a failure, not silent capture. */
+    hasAudio: boolean;
+}
+/** One immutable terminal result per admitted attempt. `partial` marks a
+ *  usable clip ended early by an external condition — still a success;
+ *  app review decides whether to keep it. */
+export type MovieOutcome = {
+    kind: 'clip';
+    clip: MovieClip;
+    endReason: MovieEndReason;
+    partial: boolean;
+    warning?: CaptureIssue;
+} | {
+    kind: 'failed';
+    endReason: MovieEndReason;
+    stage: 'preparation' | 'capture' | 'finalization' | 'storage';
+    error: CaptureIssue;
+};
+/** Ordered lifecycle observation, correlated to an attempt when relevant. */
+export type CameraSessionEvent = {
+    type: 'stateChanged';
+    snapshot: CameraSessionSnapshot;
+} | {
+    type: 'started';
+    attemptId: string;
+    configuration: EffectiveCaptureConfig;
+} | {
+    type: 'finished';
+    attemptId: string;
+    outcome: MovieOutcome;
+} | {
+    type: 'interruption';
+    phase: 'began' | 'ended';
+    reason?: CameraInterruptionReason;
+} | {
+    type: 'availability';
+    available: boolean;
+};
+export type CameraInterruptionReason = 'background' | 'audioInUse' | 'cameraInUse' | 'multitasking' | 'systemPressure' | 'unknown';
+export interface StartRecordingOptions {
+    /** Positive finite milliseconds. Enforcement precision comes from
+     *  `capabilities().durationLimit`; the final duration is read from
+     *  the movie and may overshoot. */
+    maximumDurationMs?: number;
+    /** Fixed orientation for the take. Must appear in
+     *  `capabilities().orientations`; omit for the source default. */
+    orientation?: CameraOrientation;
+    /** App-supplied writable local `file://` URL (native hosts only,
+     *  where `capabilities().output.destinationFileUrl` is true).
+     *  Existing files are never overwritten. */
+    destinationFileUrl?: string;
+}
+/** One admitted capture attempt. `completion` is available immediately and
+ *  settles exactly once with the terminal outcome; repeated `stop()`
+ *  joins the same finalization. */
+export interface MovieTake {
+    readonly id: string;
+    readonly state: 'starting' | 'recording' | 'finalizing' | 'settled';
+    /** Elapsed capture time in milliseconds; excludes preparation and
+     *  finalization. Source identified by `capabilities().elapsedTime`. */
+    readonly elapsedMs: number;
+    readonly completion: Promise<MovieOutcome>;
+    /** Requests stop and joins finalization. Returns `completion`. */
+    stop(): Promise<MovieOutcome>;
+}
+/** Reopened access to a stored clip. `release()` frees temporary access;
+ *  it never deletes the clip. */
+export interface MovieOutputHandle {
+    /** Playable/readable location for the clip. */
+    readonly url: string;
+    readonly fileUrl?: string;
+    release(): void;
+}
+export interface CameraSession {
+    /** Non-prompting permission inspection; may return `unknown` when the
+     *  host cannot observe authorization. */
+    permissions(): Promise<Record<CameraPermissionKind, CameraPermissionStatus>>;
+    /** Runs the system authorization flow for one kind. Calls are
+     *  serialized; a status other than `notDetermined` returns without
+     *  prompting. */
+    requestPermission(kind: CameraPermissionKind): Promise<CameraPermissionStatus>;
+    capabilities(): Promise<CameraSessionCapabilities>;
+    snapshot(): CameraSessionSnapshot;
+    /** Ordered lifecycle events. A caller never loses a result by
+     *  subscribing late — `completion` is authoritative. Listener
+     *  exceptions do not change capture. */
+    subscribe(listener: (event: CameraSessionEvent) => void): () => void;
+    /** Replaces configuration while idle. Validates against current
+     *  capabilities and rejects with `invalidState` during an attempt. */
+    configure(config: Partial<CameraSessionConfig>): Promise<void>;
+    /** Admits one capture attempt. Throws `CameraCaptureError` before
+     *  admission for invalid arguments, busy, invalid state, or
+     *  unavailable camera — no attempt is created. */
+    startRecording(options?: StartRecordingOptions): MovieTake;
+    /** Reopens a stored output for playback or reading. */
+    openOutput(output: MovieOutput): Promise<MovieOutputHandle>;
+    /** Requests stop on any active attempt, awaits finalization, then
+     *  releases camera ownership. */
+    dispose(): Promise<void>;
+}

package/src/CameraView.windows.ts

@@ -1,5 +0,0 @@
-import type { UniversalComponent } from 'octane/universal'
-import type { CameraViewProps } from './props'
-
-/** TypeScript fallback — no Windows CameraView implementation exists yet. */
-export declare const CameraView: UniversalComponent<CameraViewProps>