@ceralive/cerastream 2026.7.4 → 2026.7.5

package/dist/constants.d.ts

@@ -8,7 +8,7 @@ export declare const PROTOCOL_VERSION: "cerastream-ipc/1";
  * additive-only within protocol major `cerastream-ipc/1` (ADR-0002 §4); this value
  * only moves when the wire schema itself does, in lockstep across both languages.
  */
-export declare const SCHEMA_VERSION: "0.10.0";
+export declare const SCHEMA_VERSION: "0.11.0";
 /** Runtime dir holding both control + preview sockets. systemd `RuntimeDirectory=cerastream`. */
 export declare const DEFAULT_IPC_DIR: "/run/cerastream";
 /** Env override for the IPC dir (tests/dev). Defaults to {@link DEFAULT_IPC_DIR}. */
@@ -63,7 +63,7 @@ export declare const PROFILE_CATALOG_VERSION: "1.0.0";
  * ignores the field) never applies a semantic the caller assumed. Mirrors the
  * Rust `ENGINE_FEATURES`.
  */
-export declare const ENGINE_FEATURES: readonly ["video-passthrough"];
+export declare const ENGINE_FEATURES: readonly ["video-passthrough", "input-mode"];
 /** Engine binary name (systemd-owned; CeraUI never spawns it — ADR-0005). */
 export declare const CERASTREAM_BIN: "cerastream";
 export declare const DEFAULT_MIN_BITRATE = 300;

package/dist/constants.js

@@ -11,7 +11,7 @@ export const PROTOCOL_VERSION = "cerastream-ipc/1";
  * additive-only within protocol major `cerastream-ipc/1` (ADR-0002 §4); this value
  * only moves when the wire schema itself does, in lockstep across both languages.
  */
-export const SCHEMA_VERSION = "0.10.0";
+export const SCHEMA_VERSION = "0.11.0";
 /** Runtime dir holding both control + preview sockets. systemd `RuntimeDirectory=cerastream`. */
 export const DEFAULT_IPC_DIR = "/run/cerastream";
 /** Env override for the IPC dir (tests/dev). Defaults to {@link DEFAULT_IPC_DIR}. */
@@ -72,7 +72,7 @@ export const PROFILE_CATALOG_VERSION = "1.0.0";
  * ignores the field) never applies a semantic the caller assumed. Mirrors the
  * Rust `ENGINE_FEATURES`.
  */
-export const ENGINE_FEATURES = ["video-passthrough"];
+export const ENGINE_FEATURES = ["video-passthrough", "input-mode"];
 /** Engine binary name (systemd-owned; CeraUI never spawns it — ADR-0005). */
 export const CERASTREAM_BIN = "cerastream";
 // ---- config defaults (mirror ceracoder, the engine being replaced) ----

package/dist/errors.d.ts

@@ -88,8 +88,21 @@ export declare const processErrorCodeSchema: z.ZodEnum<{
     pipeline_stall: "pipeline_stall";
     srt_connect_failed: "srt_connect_failed";
     srt_connection_lost: "srt_connection_lost";
+    capture_unrecoverable: "capture_unrecoverable";
 }>;
 export type ProcessErrorCode = z.infer<typeof processErrorCodeSchema>;
+/**
+ * Why a capture device became `capture_unrecoverable` — the `reason` field of the
+ * `error` event. Mirrors the Rust `CaptureUnrecoverableReason`.
+ */
+export declare const captureUnrecoverableReasonSchema: z.ZodEnum<{
+    node_absent_reprobe_disabled: "node_absent_reprobe_disabled";
+    reprobe_no_reenumeration: "reprobe_no_reenumeration";
+    reprobe_identity_changed: "reprobe_identity_changed";
+    reprobe_node_still_absent: "reprobe_node_still_absent";
+    reprobe_unavailable: "reprobe_unavailable";
+}>;
+export type CaptureUnrecoverableReason = z.infer<typeof captureUnrecoverableReasonSchema>;
 /** Origin of a Tier 2 runtime error (the notification channel CeraUI routes on). */
 export declare const processErrorSourceSchema: z.ZodEnum<{
     srtla: "srtla";

package/dist/errors.js

@@ -124,6 +124,21 @@ export const processErrorCodeSchema = z.enum([
     "pipeline_stall",
     "srt_connect_failed",
     "srt_connection_lost",
+    // TERMINAL, unlike capture_video_error: the device is still on the bus but the
+    // engine has exhausted recovery, so a UI that keeps showing "reconnecting"
+    // would be lying. Always carries a captureUnrecoverableReasonSchema `reason`.
+    "capture_unrecoverable",
+]);
+/**
+ * Why a capture device became `capture_unrecoverable` — the `reason` field of the
+ * `error` event. Mirrors the Rust `CaptureUnrecoverableReason`.
+ */
+export const captureUnrecoverableReasonSchema = z.enum([
+    "node_absent_reprobe_disabled",
+    "reprobe_no_reenumeration",
+    "reprobe_identity_changed",
+    "reprobe_node_still_absent",
+    "reprobe_unavailable",
 ]);
 /** Origin of a Tier 2 runtime error (the notification channel CeraUI routes on). */
 export const processErrorSourceSchema = z.enum(["srtla", "engine"]);

package/dist/events.d.ts

@@ -115,6 +115,25 @@ export declare const deviceEventSchema: z.ZodObject<{
             test: "test";
             network: "network";
         }>>;
+        modes: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            media_type: z.ZodString;
+            pipeline_kind: z.ZodEnum<{
+                audio: "audio";
+                hdmi: "hdmi";
+                uvc_h264: "uvc_h264";
+                uvc_h265: "uvc_h265";
+                mjpeg: "mjpeg";
+                camlink: "camlink";
+                test: "test";
+                network: "network";
+            }>;
+            caps: z.ZodArray<z.ZodObject<{
+                width: z.ZodOptional<z.ZodNumber>;
+                height: z.ZodOptional<z.ZodNumber>;
+                framerate: z.ZodOptional<z.ZodString>;
+                media_type: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>>;
         alsa_card_id: z.ZodOptional<z.ZodString>;
         product_name: z.ZodOptional<z.ZodString>;
         transport: z.ZodOptional<z.ZodEnum<{
@@ -164,12 +183,14 @@ export declare const runtimeErrorEventSchema: z.ZodObject<{
         pipeline_stall: "pipeline_stall";
         srt_connect_failed: "srt_connect_failed";
         srt_connection_lost: "srt_connection_lost";
+        capture_unrecoverable: "capture_unrecoverable";
     }>;
     source: z.ZodEnum<{
         srtla: "srtla";
         engine: "engine";
     }>;
     reason: z.ZodOptional<z.ZodString>;
+    selected: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;
 /** Payload of a {@link runtimeErrorEventSchema} event. */
 export type RuntimeErrorEvent = z.infer<typeof runtimeErrorEventSchema>;
@@ -312,6 +333,25 @@ export declare const eventParamsSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
             test: "test";
             network: "network";
         }>>;
+        modes: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            media_type: z.ZodString;
+            pipeline_kind: z.ZodEnum<{
+                audio: "audio";
+                hdmi: "hdmi";
+                uvc_h264: "uvc_h264";
+                uvc_h265: "uvc_h265";
+                mjpeg: "mjpeg";
+                camlink: "camlink";
+                test: "test";
+                network: "network";
+            }>;
+            caps: z.ZodArray<z.ZodObject<{
+                width: z.ZodOptional<z.ZodNumber>;
+                height: z.ZodOptional<z.ZodNumber>;
+                framerate: z.ZodOptional<z.ZodString>;
+                media_type: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>>;
         alsa_card_id: z.ZodOptional<z.ZodString>;
         product_name: z.ZodOptional<z.ZodString>;
         transport: z.ZodOptional<z.ZodEnum<{
@@ -346,12 +386,14 @@ export declare const eventParamsSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         pipeline_stall: "pipeline_stall";
         srt_connect_failed: "srt_connect_failed";
         srt_connection_lost: "srt_connection_lost";
+        capture_unrecoverable: "capture_unrecoverable";
     }>;
     source: z.ZodEnum<{
         srtla: "srtla";
         engine: "engine";
     }>;
     reason: z.ZodOptional<z.ZodString>;
+    selected: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"preview">;
     seq: z.ZodNumber;
@@ -468,6 +510,25 @@ export declare const cerastreamEventSchema: z.ZodObject<{
                 test: "test";
                 network: "network";
             }>>;
+            modes: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                media_type: z.ZodString;
+                pipeline_kind: z.ZodEnum<{
+                    audio: "audio";
+                    hdmi: "hdmi";
+                    uvc_h264: "uvc_h264";
+                    uvc_h265: "uvc_h265";
+                    mjpeg: "mjpeg";
+                    camlink: "camlink";
+                    test: "test";
+                    network: "network";
+                }>;
+                caps: z.ZodArray<z.ZodObject<{
+                    width: z.ZodOptional<z.ZodNumber>;
+                    height: z.ZodOptional<z.ZodNumber>;
+                    framerate: z.ZodOptional<z.ZodString>;
+                    media_type: z.ZodOptional<z.ZodString>;
+                }, z.core.$strip>>;
+            }, z.core.$strip>>>;
             alsa_card_id: z.ZodOptional<z.ZodString>;
             product_name: z.ZodOptional<z.ZodString>;
             transport: z.ZodOptional<z.ZodEnum<{
@@ -502,12 +563,14 @@ export declare const cerastreamEventSchema: z.ZodObject<{
             pipeline_stall: "pipeline_stall";
             srt_connect_failed: "srt_connect_failed";
             srt_connection_lost: "srt_connection_lost";
+            capture_unrecoverable: "capture_unrecoverable";
         }>;
         source: z.ZodEnum<{
             srtla: "srtla";
             engine: "engine";
         }>;
         reason: z.ZodOptional<z.ZodString>;
+        selected: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"preview">;
         seq: z.ZodNumber;
@@ -630,6 +693,25 @@ export declare const eventSchemas: {
                 test: "test";
                 network: "network";
             }>>;
+            modes: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                media_type: z.ZodString;
+                pipeline_kind: z.ZodEnum<{
+                    audio: "audio";
+                    hdmi: "hdmi";
+                    uvc_h264: "uvc_h264";
+                    uvc_h265: "uvc_h265";
+                    mjpeg: "mjpeg";
+                    camlink: "camlink";
+                    test: "test";
+                    network: "network";
+                }>;
+                caps: z.ZodArray<z.ZodObject<{
+                    width: z.ZodOptional<z.ZodNumber>;
+                    height: z.ZodOptional<z.ZodNumber>;
+                    framerate: z.ZodOptional<z.ZodString>;
+                    media_type: z.ZodOptional<z.ZodString>;
+                }, z.core.$strip>>;
+            }, z.core.$strip>>>;
             alsa_card_id: z.ZodOptional<z.ZodString>;
             product_name: z.ZodOptional<z.ZodString>;
             transport: z.ZodOptional<z.ZodEnum<{
@@ -667,12 +749,14 @@ export declare const eventSchemas: {
             pipeline_stall: "pipeline_stall";
             srt_connect_failed: "srt_connect_failed";
             srt_connection_lost: "srt_connection_lost";
+            capture_unrecoverable: "capture_unrecoverable";
         }>;
         source: z.ZodEnum<{
             srtla: "srtla";
             engine: "engine";
         }>;
         reason: z.ZodOptional<z.ZodString>;
+        selected: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>;
     readonly preview: z.ZodObject<{
         type: z.ZodLiteral<"preview">;

package/dist/events.js

@@ -93,6 +93,7 @@ export const runtimeErrorEventSchema = z.object({
     code: processErrorCodeSchema, // Tier 2 (errors.ts)
     source: processErrorSourceSchema,
     reason: z.string().optional(), // structured replacement for the stderr <reason>
+    selected: z.boolean().optional(), // additive (0.11.0): the degraded input is the operator's OWN selection, so the stream will not move itself and only they can pick another — a materially different operator response than a degraded non-selected input, and one to branch on rather than string-match. Absent ⇒ false
 });
 /** `preview` event — a preview-session lifecycle/phase change. */
 export const previewEventSchema = z.object({

package/dist/messages.d.ts

@@ -42,6 +42,16 @@ export declare const startParamsSchema: z.ZodObject<{
         force: "force";
         off: "off";
     }>>;
+    input_mode: z.ZodOptional<z.ZodEnum<{
+        audio: "audio";
+        hdmi: "hdmi";
+        uvc_h264: "uvc_h264";
+        uvc_h265: "uvc_h265";
+        mjpeg: "mjpeg";
+        camlink: "camlink";
+        test: "test";
+        network: "network";
+    }>>;
 }, z.core.$strip>;
 export type StartParams = z.infer<typeof startParamsSchema>;
 export declare const startResultSchema: z.ZodObject<{
@@ -193,6 +203,25 @@ export declare const listDevicesResultSchema: z.ZodObject<{
             test: "test";
             network: "network";
         }>>;
+        modes: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            media_type: z.ZodString;
+            pipeline_kind: z.ZodEnum<{
+                audio: "audio";
+                hdmi: "hdmi";
+                uvc_h264: "uvc_h264";
+                uvc_h265: "uvc_h265";
+                mjpeg: "mjpeg";
+                camlink: "camlink";
+                test: "test";
+                network: "network";
+            }>;
+            caps: z.ZodArray<z.ZodObject<{
+                width: z.ZodOptional<z.ZodNumber>;
+                height: z.ZodOptional<z.ZodNumber>;
+                framerate: z.ZodOptional<z.ZodString>;
+                media_type: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>>;
         alsa_card_id: z.ZodOptional<z.ZodString>;
         product_name: z.ZodOptional<z.ZodString>;
         transport: z.ZodOptional<z.ZodEnum<{
@@ -389,6 +418,16 @@ export declare const changeConfigParamsSchema: z.ZodObject<{
         h265: "h265";
     }>>;
     input_id: z.ZodOptional<z.ZodString>;
+    input_mode: z.ZodOptional<z.ZodEnum<{
+        audio: "audio";
+        hdmi: "hdmi";
+        uvc_h264: "uvc_h264";
+        uvc_h265: "uvc_h265";
+        mjpeg: "mjpeg";
+        camlink: "camlink";
+        test: "test";
+        network: "network";
+    }>>;
 }, z.core.$strip>;
 export type ChangeConfigParams = z.infer<typeof changeConfigParamsSchema>;
 export declare const changeConfigResultSchema: z.ZodObject<{
@@ -480,6 +519,16 @@ export declare const requestSchemas: {
                 force: "force";
                 off: "off";
             }>>;
+            input_mode: z.ZodOptional<z.ZodEnum<{
+                audio: "audio";
+                hdmi: "hdmi";
+                uvc_h264: "uvc_h264";
+                uvc_h265: "uvc_h265";
+                mjpeg: "mjpeg";
+                camlink: "camlink";
+                test: "test";
+                network: "network";
+            }>>;
         }, z.core.$strip>;
         readonly result: z.ZodObject<{
             session_id: z.ZodString;
@@ -614,6 +663,25 @@ export declare const requestSchemas: {
                     test: "test";
                     network: "network";
                 }>>;
+                modes: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                    media_type: z.ZodString;
+                    pipeline_kind: z.ZodEnum<{
+                        audio: "audio";
+                        hdmi: "hdmi";
+                        uvc_h264: "uvc_h264";
+                        uvc_h265: "uvc_h265";
+                        mjpeg: "mjpeg";
+                        camlink: "camlink";
+                        test: "test";
+                        network: "network";
+                    }>;
+                    caps: z.ZodArray<z.ZodObject<{
+                        width: z.ZodOptional<z.ZodNumber>;
+                        height: z.ZodOptional<z.ZodNumber>;
+                        framerate: z.ZodOptional<z.ZodString>;
+                        media_type: z.ZodOptional<z.ZodString>;
+                    }, z.core.$strip>>;
+                }, z.core.$strip>>>;
                 alsa_card_id: z.ZodOptional<z.ZodString>;
                 product_name: z.ZodOptional<z.ZodString>;
                 transport: z.ZodOptional<z.ZodEnum<{

package/dist/messages.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { AUDIO_DELAY_MAX_MS } from "./constants.js";
 import { helloParamsSchema, helloResultSchema, } from "./envelope.js";
-import { balancerAlgorithmSchema, bitrateControlSchema, captureDeviceSchema, cerastreamConfigSchema, configChangePhaseSchema, inputModeSchema, mediaClassSchema, previewTierSchema, streamStateSchema, videoCodecSchema, } from "./types.js";
+import { balancerAlgorithmSchema, bitrateControlSchema, captureDeviceKindSchema, captureDeviceSchema, cerastreamConfigSchema, configChangePhaseSchema, inputModeSchema, mediaClassSchema, previewTierSchema, streamStateSchema, videoCodecSchema, } from "./types.js";
 // The eight v1 control methods (schema.md "v1 messages"). Each is matched
 // byte-for-byte to schema.md: the JSON shape on the wire is the contract.
 // ---- 1. start ----
@@ -207,6 +207,13 @@ export const changeConfigParamsSchema = z
     framerate: z.number().optional(),
     codec: videoCodecSchema.optional(),
     input_id: z.string().optional(),
+    // Switching a LIVE device between a libuvc family (uvc_h264/uvc_h265) and
+    // the v4l2 mjpeg family is NOT a plain rebuild: libuvc detaches uvcvideo, so
+    // the /dev/videoN node the mjpeg leg needs does not exist until the hold is
+    // released — and it then returns asynchronously, possibly renumbered. The
+    // engine runs a release → re-enumeration-barrier → open transaction and
+    // rolls back honestly (reason: mode_barrier_timeout) if the barrier expires.
+    input_mode: captureDeviceKindSchema.optional(),
 })
     .refine((delta) => Object.keys(delta).length > 0, {
     message: "change-config delta must carry at least one field",

package/dist/types.d.ts

@@ -164,6 +164,16 @@ export declare const cerastreamConfigSchema: z.ZodObject<{
         force: "force";
         off: "off";
     }>>;
+    input_mode: z.ZodOptional<z.ZodEnum<{
+        audio: "audio";
+        hdmi: "hdmi";
+        uvc_h264: "uvc_h264";
+        uvc_h265: "uvc_h265";
+        mjpeg: "mjpeg";
+        camlink: "camlink";
+        test: "test";
+        network: "network";
+    }>>;
 }, z.core.$strip>;
 export type CerastreamConfig = z.infer<typeof cerastreamConfigSchema>;
 export type PartialCerastreamConfig = z.input<typeof cerastreamConfigSchema>;
@@ -180,6 +190,26 @@ export declare const captureCapSchema: z.ZodObject<{
     media_type: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type CaptureCap = z.infer<typeof captureCapSchema>;
+export declare const captureModeSchema: z.ZodObject<{
+    media_type: z.ZodString;
+    pipeline_kind: z.ZodEnum<{
+        audio: "audio";
+        hdmi: "hdmi";
+        uvc_h264: "uvc_h264";
+        uvc_h265: "uvc_h265";
+        mjpeg: "mjpeg";
+        camlink: "camlink";
+        test: "test";
+        network: "network";
+    }>;
+    caps: z.ZodArray<z.ZodObject<{
+        width: z.ZodOptional<z.ZodNumber>;
+        height: z.ZodOptional<z.ZodNumber>;
+        framerate: z.ZodOptional<z.ZodString>;
+        media_type: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type CaptureMode = z.infer<typeof captureModeSchema>;
 export declare const captureDeviceSchema: z.ZodObject<{
     input_id: z.ZodString;
     device_path: z.ZodString;
@@ -204,6 +234,25 @@ export declare const captureDeviceSchema: z.ZodObject<{
         test: "test";
         network: "network";
     }>>;
+    modes: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        media_type: z.ZodString;
+        pipeline_kind: z.ZodEnum<{
+            audio: "audio";
+            hdmi: "hdmi";
+            uvc_h264: "uvc_h264";
+            uvc_h265: "uvc_h265";
+            mjpeg: "mjpeg";
+            camlink: "camlink";
+            test: "test";
+            network: "network";
+        }>;
+        caps: z.ZodArray<z.ZodObject<{
+            width: z.ZodOptional<z.ZodNumber>;
+            height: z.ZodOptional<z.ZodNumber>;
+            framerate: z.ZodOptional<z.ZodString>;
+            media_type: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>>;
     alsa_card_id: z.ZodOptional<z.ZodString>;
     product_name: z.ZodOptional<z.ZodString>;
     transport: z.ZodOptional<z.ZodEnum<{

package/dist/types.js

@@ -129,6 +129,7 @@ export const cerastreamConfigSchema = z.object({
     framerate: z.number().optional(), // additive (0.4.0): fps as a number, e.g. 29.97
     audio: audioConfigSchema.optional(), // additive (0.4.0): audio device/codec/signed delay
     video_passthrough: videoPassthroughSchema.optional(), // additive (0.5.0): auto|force|off; absent ⇒ auto
+    input_mode: captureDeviceKindSchema.optional(), // additive (0.11.0): which MODE family of the selected device to capture in, naming a list-devices modes[].pipeline_kind. Absent ⇒ the engine's precedence pick (h265 → h264 → mjpeg → raw). The ONLY way to reach the non-precedence family of a dual-format camera; a family the device does not expose is a typed cerastream.params.invalid, never a silent fallback
 });
 // convenience defaults for building a config client-side
 export const DEFAULT_BITRATE_CONFIG = {
@@ -144,13 +145,33 @@ export const captureCapSchema = z.object({
     framerate: z.string().optional(), // e.g. "30/1"
     media_type: z.string().optional(), // e.g. "video/x-h265"; additive, absent on legacy producers
 });
+// One startable capture MODE family of a device (0.11.0, additive).
+//
+// A capture device is not necessarily one format family: the DJI Osmo Pocket 3
+// exposes H.264 AND MJPEG on the SAME /dev/video1 node (selection is a
+// VIDIOC_S_FMT pixelformat choice, not a different node). The scalar
+// captureDevice.kind can only name ONE family, so before this contract a
+// dual-format camera was classified uvc_h264 by precedence and its MJPEG ladder
+// was unreachable — visible, but impossible to start.
+//
+// pipeline_kind is exactly what a caller echoes back as start.input_mode to drive
+// the device in this family. caps is the ladder for THIS family ALONE, never the
+// device-wide union: on the Osmo, H.264 offers 4K at 60/50/48 fps while MJPEG
+// tops out at 30, so a merged list would advertise 4K60 MJPEG — a mode the device
+// cannot deliver.
+export const captureModeSchema = z.object({
+    media_type: z.string(), // e.g. "image/jpeg"
+    pipeline_kind: captureDeviceKindSchema, // the value start.input_mode takes to select this mode
+    caps: z.array(captureCapSchema), // the {w × h × framerate} ladder for THIS media type only
+});
 export const captureDeviceSchema = z.object({
     input_id: z.string(), // stable id used by switch-input
     device_path: z.string(), // e.g. /dev/video0 (dedup key)
     display_name: z.string(),
     media_class: mediaClassSchema,
     caps: z.array(captureCapSchema).optional(),
-    kind: captureDeviceKindSchema.optional(), // additive (0.4.0): engine-typed device family; absent on legacy producers
+    kind: captureDeviceKindSchema.optional(), // additive (0.4.0): engine-typed device family; absent on legacy producers. A dual-format device reports its HIGHEST-PRECEDENCE family here; the full set is `modes`
+    modes: z.array(captureModeSchema).optional(), // additive (0.11.0): every startable mode family, each with its OWN caps ladder; absent on legacy producers, on audio rows, and on a device with no probed caps. When present it ALWAYS contains the family named by `kind`, first
     alsa_card_id: z.string().optional(), // additive: ALSA card id for media_class:audio devices only; absent on video + legacy producers
     product_name: z.string().optional(), // additive (Todo 20): real product name, deduped with a #N suffix when shared; absent ⇒ use display_name
     transport: deviceTransportSchema.optional(), // additive (Todo 20): how the device is attached; absent on legacy producers

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ceralive/cerastream",
-  "version": "2026.7.4",
+  "version": "2026.7.5",
   "description": "Type-safe TypeScript schema + IPC client for the cerastream streaming engine (JSON-RPC 2.0 / NDJSON over a Unix domain socket).",
   "type": "module",
   "main": "dist/index.js",