/** operation error の phase(taxonomy)。 */ type WcsIoErrorPhase = "probe" | "start" | "execute" | "decode" | "commit" | "dispose"; /** serializable な error info(non-cloneable な cause とは分離。DevTools / remote へは info のみ)。 */ interface WcsIoErrorInfo { readonly code: string; readonly phase: WcsIoErrorPhase; readonly recoverable: boolean; readonly capabilityId?: string; readonly message: string; } /** * Observation semantics of a `properties` entry. * * "state" — current value. A snapshot may cache it, and equality-based dedupe is safe. * "event" — occurrence. Repeated identical payloads are distinct occurrences; never dedupe. * "handle" — live / opaque resource with its own lifecycle (e.g. MediaStream). Not * snapshot-safe and not necessarily serializable; consumers need an explicit * ref / callback surface rather than a value slot. */ type WcBindableSemantics = "state" | "event" | "handle"; interface IWcBindableProperty { readonly name: string; readonly event: string; readonly getter?: (event: Event) => any; /** * Optional, additive, forward-compatible. An absent value means **unspecified**, NOT * "state": a reader that finds no `semantics` MUST keep the behavior it had before this * field existed (deliver the update as-is; do not start deduping, caching or serializing * on assumption). Only an explicit value licenses a reader to change its handling. */ readonly semantics?: WcBindableSemantics; } interface IWcBindableInput { readonly name: string; readonly attribute?: string; } interface IWcBindableCommand { readonly name: string; readonly async?: boolean; } interface IWcBindable { readonly protocol: "wc-bindable"; /** Integer protocol version. All versions >= 1 are core-compatible. */ readonly version: number; readonly properties: readonly IWcBindableProperty[]; readonly inputs?: readonly IWcBindableInput[]; readonly commands?: readonly IWcBindableCommand[]; } interface ITagNames { readonly camera: string; readonly recorder: string; } interface IWritableTagNames { camera?: string; recorder?: string; } interface IConfig { readonly tagNames: ITagNames; } interface IWritableConfig { tagNames?: IWritableTagNames; } /** * Permission state for camera / microphone, mirroring the Permissions API * `PermissionState` plus `"unsupported"` for environments without * `navigator.permissions` (or where the `camera` / `microphone` descriptor * cannot be queried, e.g. Firefox). */ type MediaPermissionState = "prompt" | "granted" | "denied" | "unsupported"; type FacingMode = "user" | "environment"; /** * Normalized getUserMedia / MediaRecorder failure. `name` mirrors the DOMException * name (`"NotAllowedError"`, `"NotFoundError"`, `"NotReadableError"`, * `"OverconstrainedError"`, …); `"unsupported"` is surfaced when the API is absent * or the context is insecure. */ interface WcsMediaErrorDetail { name: string; message: string; } /** * Settable camera constraints (Shell attributes). `audio` opts microphone in; * `facingMode` / `deviceId` / `width` / `height` shape the requested track. */ interface CameraConstraints { audio?: boolean; facingMode?: FacingMode; deviceId?: string; width?: number; height?: number; } /** * Structured-clone-friendly snapshot of a `MediaDeviceInfo` (video inputs). The * live device objects are exposed as plain copies so the list flows through data * binding as a value. */ interface MediaDeviceSnapshot { deviceId: string; label: string; groupId: string; kind: string; } /** * Value types for CameraCore (headless) — the observable state properties. * * Note: the live `MediaStream` is intentionally NOT here. It is a non-serializable * live handle and never flows through reactive state — it is published only via * the `wcs-camera:stream-ready` event for the direct element→element channel. * See docs/camera-recorder-tag-design.md §1. */ interface WcsCameraCoreValues { active: boolean; permission: MediaPermissionState; audioPermission: MediaPermissionState | null; deviceId: string | null; devices: MediaDeviceSnapshot[]; error: WcsMediaErrorDetail | null; /** Serializable Phase 6 failure taxonomy derived from `error`, or null. */ errorInfo: WcsIoErrorInfo | null; } type WcsCameraValues = WcsCameraCoreValues; interface WcsCameraInputs { audio: boolean; facingMode: FacingMode; deviceId: string; width: number; height: number; /** Acquire the camera automatically on connect (otherwise wait for `start()`). */ autostart: boolean; /** Do not suspend the stream when the page is hidden (set while recording). */ keepAlive: boolean; } interface WcsCameraCoreCommands { start(): void; stop(): void; switchCamera(): void; } type WcsCameraCommands = WcsCameraCoreCommands; /** * Per-recording parameters accepted by `start()`, mirroring the settable fields * of `MediaRecorder`. */ interface RecorderOptions { mimeType?: string; /** Emit `dataavailable` chunks on this interval (ms). Omit to receive one Blob on stop. */ timeslice?: number; audioBitsPerSecond?: number; videoBitsPerSecond?: number; } /** Detail of the `wcs-recorder:recorded` event — the assembled clip. */ interface WcsRecordedDetail { blob: Blob; objectURL: string; mimeType: string; duration: number; } /** * Value types for RecorderCore (headless) — the observable state properties. * `blob` is structured-clone-friendly (a settled value, unlike MediaStream) so it * may flow through state. `objectURL` is a string with a revoke lifecycle the Core * manages. */ interface WcsRecorderCoreValues { recording: boolean; paused: boolean; /** * Recorded length in ms, **finalized at stop/pause** — there is no live ticking * during recording (no internal timer). It stays 0 from start() until the first * pause() or stop(). For a live elapsed display, drive your own client-side timer * off the `recording` flag. */ duration: number; mimeType: string; /** * The last assembled clip — **retained across a new recording**. start() does NOT * clear `blob` / `objectURL`; they hold the previous clip until the next one is * assembled at stop() (the old object URL is revoked then, atomically). So while a * 2nd recording is in flight, `recording` is true *and* these still expose the prior * clip — intentional, so a "download last clip" affordance never goes briefly empty. */ blob: Blob | null; objectURL: string | null; error: WcsMediaErrorDetail | null; /** Serializable Phase 6 failure taxonomy derived from `error`, or null. */ errorInfo: WcsIoErrorInfo | null; } type WcsRecorderValues = WcsRecorderCoreValues; interface WcsRecorderInputs { mimeType: string; timeslice: number; audioBitsPerSecond: number; videoBitsPerSecond: number; } interface WcsRecorderCoreCommands { attachStream(stream: MediaStream): void; start(options?: RecorderOptions): void; stop(): void; pause(): void; resume(): void; } interface WcsRecorderCommands { /** Borrow a stream for recording — the direct-channel sink (`command.attachStream`). */ attachStream(stream: MediaStream): void; start(): void; stop(): void; pause(): void; resume(): void; } declare function bootstrapCamera(userConfig?: IWritableConfig, registry?: CustomElementRegistry): void; declare function getConfig(): IConfig; /** * Headless camera-capture primitive. Wraps getUserMedia + the Permissions API and * exposes a `MediaStream` through the wc-bindable protocol — but the live stream is * NEVER published as a reactive value. It is a non-serializable live handle: it * flows out only via the `wcs-camera:stream-ready` event so a consumer (the preview * `