@ceralive/cerastream 2026.6.2 → 2026.7.0

package/dist/client.d.ts

@@ -28,31 +28,80 @@ export interface Subscription {
 /**
  * Bidirectional JSON-RPC 2.0 control client for cerastream. One method per v1
  * request plus the handshake. Server-push events arrive via `subscribeEvents`.
+ *
+ * Every request method rejects with a {@link CerastreamRpcError} when the engine
+ * returns a typed error, a {@link CerastreamTimeoutError} when no reply arrives
+ * within the per-request timeout, or a {@link CerastreamConnectionError} when the
+ * control socket is not open.
  */
 export interface CerastreamClient {
     /** Negotiated handshake result (protocol + schema/engine versions). */
     readonly hello: HelloResult;
-    /** Start the streaming pipeline (encode → bond → SRT). */
+    /**
+     * Start the streaming pipeline (encode → bond → SRT).
+     * @param params Unified engine config (pipeline, SRT, bitrate, input).
+     * @returns The new session id and initial stream state.
+     * @throws {CerastreamRpcError} when params are invalid or already streaming.
+     */
     start(params: StartParams): Promise<StartResult>;
-    /** Stop the streaming pipeline. Idempotent. Stops the pipeline, NOT the OS process. */
+    /**
+     * Stop the streaming pipeline. Idempotent. Stops the pipeline, NOT the OS process.
+     * @param params Optional stop reason recorded by the engine.
+     * @returns The stream state after the stop (`idle`).
+     */
     stop(params?: StopParams): Promise<StopResult>;
-    /** Hot-reload engine config (replaces SIGHUP). Returns the applied config. */
+    /**
+     * Hot-reload engine config (replaces SIGHUP).
+     * @param params Partial bitrate/SRT/audio fields to update.
+     * @returns The post-clamp values actually applied.
+     * @throws {CerastreamRpcError} when a field is out of range (e.g. audio delay).
+     */
     reloadConfig(params: ReloadConfigParams): Promise<ReloadConfigResult>;
-    /** Hot-adjust max bitrate while streaming. Returns the post-clamp applied value. */
+    /**
+     * Hot-adjust max bitrate while streaming.
+     * @param params The new bitrate ceiling, in kbps.
+     * @returns The post-clamp applied bitrate.
+     * @throws {CerastreamRpcError} when the value is out of the configured range.
+     */
     setBitrate(params: SetBitrateParams): Promise<SetBitrateResult>;
-    /** Switch the active capture source (manual) or hand selection to failover (auto). */
+    /**
+     * Switch the active capture source (manual) or hand selection to failover (auto).
+     * @param params The target input id and switch mode.
+     * @returns The input now active and the mode in effect.
+     * @throws {CerastreamRpcError} when the input id is unknown.
+     */
     switchInput(params: SwitchInputParams): Promise<SwitchInputResult>;
-    /** Enumerate capture devices (GstDeviceMonitor, de-duped by device path). */
+    /**
+     * Enumerate capture devices (GstDeviceMonitor, de-duped by device path).
+     * @param params Optional media-class filter.
+     * @returns The discovered capture devices.
+     */
     listDevices(params?: ListDevicesParams): Promise<ListDevicesResult>;
-    /** Subscribe to the live event stream; `handler` fires for each pushed event. */
+    /**
+     * Subscribe to the live event stream; `handler` fires for each pushed event.
+     * @param params The topics to subscribe to (absent ⇒ all topics).
+     * @param handler Invoked for every matching server-pushed event.
+     * @returns A {@link Subscription} whose `close()` stops delivery.
+     */
     subscribeEvents(params: SubscribeEventsParams, handler: EventHandler): Promise<Subscription>;
-    /** Control a local preview session (WebCodecs binary tier / WebRTC signaling). */
+    /**
+     * Control a local preview session (WebCodecs binary tier / WebRTC signaling).
+     * @param params The session action (start/stop/signal) and its fields.
+     * @returns The session id, tier, and how to reach the preview media.
+     * @throws {CerastreamRpcError} when the requested tier is unavailable.
+     */
     previewSession(params: PreviewSessionParams): Promise<PreviewSessionResult>;
-    /** Close the control connection. Never respawns the engine (ADR-0005). */
+    /**
+     * Close the control connection. Never respawns the engine (ADR-0005).
+     * @returns A promise that resolves once the socket is closed.
+     */
     close(): Promise<void>;
 }
 /**
  * Connect to the cerastream control socket, run the mandatory `hello`
  * handshake, and return a {@link CerastreamClient}.
+ * @param options Optional socket path, client name, timeout, and reconnect knobs.
+ * @returns A connected, handshaked {@link CerastreamClient}.
+ * @throws {CerastreamConnectionError} when the control socket cannot be reached.
  */
 export declare function connect(options?: ConnectOptions): Promise<CerastreamClient>;

package/dist/client.js

@@ -266,6 +266,9 @@ function sleep(ms) {
 /**
  * Connect to the cerastream control socket, run the mandatory `hello`
  * handshake, and return a {@link CerastreamClient}.
+ * @param options Optional socket path, client name, timeout, and reconnect knobs.
+ * @returns A connected, handshaked {@link CerastreamClient}.
+ * @throws {CerastreamConnectionError} when the control socket cannot be reached.
  */
 export async function connect(options) {
     const client = new ClientImpl(options ?? {});

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.3.0";
+export declare const SCHEMA_VERSION: "0.4.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}. */
@@ -25,6 +25,37 @@ export declare const PREVIEW_SOCKET_PATH: "/run/cerastream/preview.sock";
 export declare const MAX_LINE_BYTES: number;
 /** Upper bound (ms) for `reload-config.audio.delay_ms`. Mirrors the Rust `AUDIO_DELAY_MAX_MS` and CeraUI's `AUDIO_DELAY_MAX`. */
 export declare const AUDIO_DELAY_MAX_MS = 2000;
+/**
+ * SRT receive-latency capability range (ms) reported by `get-capabilities`
+ * (`latency_range`). Latency is a CONTINUOUS control wired to `SRTO_LATENCY`,
+ * applied on (re)connect; CeraUI renders these as the slider's min/default/max.
+ * `MAX` is the device-recommended ceiling; a receiver may advertise a lower cap.
+ * Mirror the Rust `LATENCY_MIN_MS` / `LATENCY_DEFAULT_MS` / `LATENCY_MAX_MS`.
+ */
+export declare const LATENCY_MIN_MS = 100;
+export declare const LATENCY_DEFAULT_MS = 1500;
+export declare const LATENCY_MAX_MS = 5000;
+/**
+ * Recommended SRT FEC sender full-config string for `srtConfig.fec`. The sender
+ * defines the complete matrix (staircase 10×10, ARQ on-request); a CeraLive
+ * receiver sets just `fec` and adopts it (one-sided negotiation). The device
+ * applies it to `SRTO_PACKETFILTER` ONLY against a known FEC-capable receiver.
+ * Mirrors the Rust `DEFAULT_FEC_CONFIG`.
+ */
+export declare const DEFAULT_FEC_CONFIG: "fec,layout:staircase,rows:10,cols:10,arq:onreq";
+/**
+ * The v1 SRT receive-profile catalog: the preset ids `get-capabilities`
+ * advertises in `supported_profiles`. A profile is a named preset CeraUI expands
+ * to an SRT/bitrate config; the resolver and the Stream Tuning card read this list
+ * to gate which presets the device offers. Mirrors the Rust `SUPPORTED_PROFILES`.
+ */
+export declare const SUPPORTED_PROFILES: readonly ["balanced", "low-latency", "resilient", "classic", "low-latency-fec"];
+/**
+ * Version of the profile catalog {@link SUPPORTED_PROFILES} comes from (semver),
+ * echoed by `get-capabilities` as `profile_catalog_version`. Bumped when the preset
+ * set or any preset's meaning changes. Mirrors the Rust `PROFILE_CATALOG_VERSION`.
+ */
+export declare const PROFILE_CATALOG_VERSION: "1.0.0";
 /** 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.3.0";
+export const SCHEMA_VERSION = "0.4.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}. */
@@ -28,6 +28,43 @@ export const PREVIEW_SOCKET_PATH = "/run/cerastream/preview.sock";
 export const MAX_LINE_BYTES = 1024 * 1024; // 1 MiB
 /** Upper bound (ms) for `reload-config.audio.delay_ms`. Mirrors the Rust `AUDIO_DELAY_MAX_MS` and CeraUI's `AUDIO_DELAY_MAX`. */
 export const AUDIO_DELAY_MAX_MS = 2000;
+/**
+ * SRT receive-latency capability range (ms) reported by `get-capabilities`
+ * (`latency_range`). Latency is a CONTINUOUS control wired to `SRTO_LATENCY`,
+ * applied on (re)connect; CeraUI renders these as the slider's min/default/max.
+ * `MAX` is the device-recommended ceiling; a receiver may advertise a lower cap.
+ * Mirror the Rust `LATENCY_MIN_MS` / `LATENCY_DEFAULT_MS` / `LATENCY_MAX_MS`.
+ */
+export const LATENCY_MIN_MS = 100;
+export const LATENCY_DEFAULT_MS = 1500;
+export const LATENCY_MAX_MS = 5000;
+/**
+ * Recommended SRT FEC sender full-config string for `srtConfig.fec`. The sender
+ * defines the complete matrix (staircase 10×10, ARQ on-request); a CeraLive
+ * receiver sets just `fec` and adopts it (one-sided negotiation). The device
+ * applies it to `SRTO_PACKETFILTER` ONLY against a known FEC-capable receiver.
+ * Mirrors the Rust `DEFAULT_FEC_CONFIG`.
+ */
+export const DEFAULT_FEC_CONFIG = "fec,layout:staircase,rows:10,cols:10,arq:onreq";
+/**
+ * The v1 SRT receive-profile catalog: the preset ids `get-capabilities`
+ * advertises in `supported_profiles`. A profile is a named preset CeraUI expands
+ * to an SRT/bitrate config; the resolver and the Stream Tuning card read this list
+ * to gate which presets the device offers. Mirrors the Rust `SUPPORTED_PROFILES`.
+ */
+export const SUPPORTED_PROFILES = [
+    "balanced",
+    "low-latency",
+    "resilient",
+    "classic",
+    "low-latency-fec",
+];
+/**
+ * Version of the profile catalog {@link SUPPORTED_PROFILES} comes from (semver),
+ * echoed by `get-capabilities` as `profile_catalog_version`. Bumped when the preset
+ * set or any preset's meaning changes. Mirrors the Rust `PROFILE_CATALOG_VERSION`.
+ */
+export const PROFILE_CATALOG_VERSION = "1.0.0";
 /** 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/events.d.ts

@@ -1,4 +1,29 @@
 import { z } from "zod";
+/**
+ * The engine's RESOLVED runtime encode state (0.4.0, additive), reported on the
+ * `status` event as `active_encode`. Engine = reporter of record: this is the
+ * encode actually running (realized graph), not the requested params. `decoder`
+ * names the runtime-selected decode element for a compressed capture. Absent on a
+ * legacy emitter or a bare state-only heartbeat.
+ */
+export declare const activeEncodeSchema: z.ZodObject<{
+    codec: z.ZodString;
+    resolution: z.ZodString;
+    framerate: z.ZodNumber;
+    active_input: z.ZodOptional<z.ZodString>;
+    decoder: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type ActiveEncode = z.infer<typeof activeEncodeSchema>;
+/**
+ * `status` event — stream state change + heartbeat. The trailing fields are
+ * additive: the `buffering*` / `spooled_bytes` / `data_headroom_bytes` /
+ * `disk_warning` egress-spool telemetry (Task 32) is absent on a plain heartbeat
+ * and present only on a spool engage/drain transition or disk-usage warning;
+ * `active_profile` (srt-receive-profiles) reports the profile/config the stream is
+ * running under and is absent on a legacy emitter or a bare state-only heartbeat;
+ * `active_encode` (0.4.0) reports the resolved runtime encode and is absent on a
+ * legacy emitter or a bare state-only heartbeat.
+ */
 export declare const statusEventSchema: z.ZodObject<{
     type: z.ZodLiteral<"status">;
     seq: z.ZodNumber;
@@ -10,8 +35,26 @@ export declare const statusEventSchema: z.ZodObject<{
     }>;
     streaming: z.ZodBoolean;
     active_input: z.ZodOptional<z.ZodString>;
+    active_profile: z.ZodOptional<z.ZodString>;
+    buffering: z.ZodOptional<z.ZodBoolean>;
+    spooled_bytes: z.ZodOptional<z.ZodNumber>;
+    data_headroom_bytes: z.ZodOptional<z.ZodNumber>;
+    disk_warning: z.ZodOptional<z.ZodBoolean>;
+    active_encode: z.ZodOptional<z.ZodObject<{
+        codec: z.ZodString;
+        resolution: z.ZodString;
+        framerate: z.ZodNumber;
+        active_input: z.ZodOptional<z.ZodString>;
+        decoder: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
+/** Payload of a {@link statusEventSchema} event. */
 export type StatusEvent = z.infer<typeof statusEventSchema>;
+/**
+ * `switch` event — active input changed (manual or failover). `media_class` is
+ * additive (absent on legacy video-only emitters); `switch-audio` sets it to
+ * `"audio"`.
+ */
 export declare const switchEventSchema: z.ZodObject<{
     type: z.ZodLiteral<"switch">;
     seq: z.ZodNumber;
@@ -26,7 +69,9 @@ export declare const switchEventSchema: z.ZodObject<{
         audio: "audio";
     }>>;
 }, z.core.$strip>;
+/** Payload of a {@link switchEventSchema} event. */
 export type SwitchEvent = z.infer<typeof switchEventSchema>;
+/** `device` event — a GstDeviceMonitor hotplug add/remove. */
 export declare const deviceEventSchema: z.ZodObject<{
     type: z.ZodLiteral<"device">;
     seq: z.ZodNumber;
@@ -48,16 +93,30 @@ export declare const deviceEventSchema: z.ZodObject<{
             framerate: z.ZodOptional<z.ZodString>;
             media_type: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>>;
+        kind: 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>;
 }, z.core.$strip>;
+/** Payload of a {@link deviceEventSchema} event. */
 export type DeviceEvent = z.infer<typeof deviceEventSchema>;
+/** `bitrate` event — the adaptive controller adjusted the encode bitrate. */
 export declare const bitrateEventSchema: z.ZodObject<{
     type: z.ZodLiteral<"bitrate">;
     seq: z.ZodNumber;
     current_bitrate: z.ZodNumber;
     max_bitrate: z.ZodNumber;
 }, z.core.$strip>;
+/** Payload of a {@link bitrateEventSchema} event. */
 export type BitrateEvent = z.infer<typeof bitrateEventSchema>;
+/** `srt-stats` event — periodic SRT transport telemetry. */
 export declare const srtStatsEventSchema: z.ZodObject<{
     type: z.ZodLiteral<"srt-stats">;
     seq: z.ZodNumber;
@@ -65,7 +124,12 @@ export declare const srtStatsEventSchema: z.ZodObject<{
     send_buffer: z.ZodNumber;
     pkt_loss: z.ZodNumber;
 }, z.core.$strip>;
+/** Payload of a {@link srtStatsEventSchema} event. */
 export type SrtStatsEvent = z.infer<typeof srtStatsEventSchema>;
+/**
+ * `error` event — a runtime error (replaces stderr scraping). Carries a Tier-2
+ * code; the engine reports facts and CeraUI decides what to surface.
+ */
 export declare const runtimeErrorEventSchema: z.ZodObject<{
     type: z.ZodLiteral<"error">;
     seq: z.ZodNumber;
@@ -84,13 +148,16 @@ export declare const runtimeErrorEventSchema: z.ZodObject<{
     }>;
     reason: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
+/** Payload of a {@link runtimeErrorEventSchema} event. */
 export type RuntimeErrorEvent = z.infer<typeof runtimeErrorEventSchema>;
+/** `preview` event — a preview-session lifecycle/phase change. */
 export declare const previewEventSchema: z.ZodObject<{
     type: z.ZodLiteral<"preview">;
     seq: z.ZodNumber;
     session_id: z.ZodString;
     phase: z.ZodString;
 }, z.core.$strip>;
+/** Payload of a {@link previewEventSchema} event. */
 export type PreviewEvent = z.infer<typeof previewEventSchema>;
 /** Discriminated union of every v1 event payload (the inner `params`). */
 export declare const eventParamsSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -104,6 +171,18 @@ export declare const eventParamsSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     }>;
     streaming: z.ZodBoolean;
     active_input: z.ZodOptional<z.ZodString>;
+    active_profile: z.ZodOptional<z.ZodString>;
+    buffering: z.ZodOptional<z.ZodBoolean>;
+    spooled_bytes: z.ZodOptional<z.ZodNumber>;
+    data_headroom_bytes: z.ZodOptional<z.ZodNumber>;
+    disk_warning: z.ZodOptional<z.ZodBoolean>;
+    active_encode: z.ZodOptional<z.ZodObject<{
+        codec: z.ZodString;
+        resolution: z.ZodString;
+        framerate: z.ZodNumber;
+        active_input: z.ZodOptional<z.ZodString>;
+        decoder: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"switch">;
     seq: z.ZodNumber;
@@ -138,6 +217,16 @@ export declare const eventParamsSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
             framerate: z.ZodOptional<z.ZodString>;
             media_type: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>>;
+        kind: 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>;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"bitrate">;
@@ -189,6 +278,18 @@ export declare const cerastreamEventSchema: z.ZodObject<{
         }>;
         streaming: z.ZodBoolean;
         active_input: z.ZodOptional<z.ZodString>;
+        active_profile: z.ZodOptional<z.ZodString>;
+        buffering: z.ZodOptional<z.ZodBoolean>;
+        spooled_bytes: z.ZodOptional<z.ZodNumber>;
+        data_headroom_bytes: z.ZodOptional<z.ZodNumber>;
+        disk_warning: z.ZodOptional<z.ZodBoolean>;
+        active_encode: z.ZodOptional<z.ZodObject<{
+            codec: z.ZodString;
+            resolution: z.ZodString;
+            framerate: z.ZodNumber;
+            active_input: z.ZodOptional<z.ZodString>;
+            decoder: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"switch">;
         seq: z.ZodNumber;
@@ -223,6 +324,16 @@ export declare const cerastreamEventSchema: z.ZodObject<{
                 framerate: z.ZodOptional<z.ZodString>;
                 media_type: z.ZodOptional<z.ZodString>;
             }, z.core.$strip>>>;
+            kind: 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>;
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"bitrate">;
@@ -276,6 +387,18 @@ export declare const eventSchemas: {
         }>;
         streaming: z.ZodBoolean;
         active_input: z.ZodOptional<z.ZodString>;
+        active_profile: z.ZodOptional<z.ZodString>;
+        buffering: z.ZodOptional<z.ZodBoolean>;
+        spooled_bytes: z.ZodOptional<z.ZodNumber>;
+        data_headroom_bytes: z.ZodOptional<z.ZodNumber>;
+        disk_warning: z.ZodOptional<z.ZodBoolean>;
+        active_encode: z.ZodOptional<z.ZodObject<{
+            codec: z.ZodString;
+            resolution: z.ZodString;
+            framerate: z.ZodNumber;
+            active_input: z.ZodOptional<z.ZodString>;
+            decoder: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
     }, z.core.$strip>;
     readonly switch: z.ZodObject<{
         type: z.ZodLiteral<"switch">;
@@ -312,6 +435,16 @@ export declare const eventSchemas: {
                 framerate: z.ZodOptional<z.ZodString>;
                 media_type: z.ZodOptional<z.ZodString>;
             }, z.core.$strip>>>;
+            kind: 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>;
     }, z.core.$strip>;
     readonly bitrate: z.ZodObject<{

package/dist/events.js

@@ -5,16 +5,48 @@ import { captureDeviceSchema, inputModeSchema, mediaClassSchema, streamStateSche
 // (schema.md "Events"). Each event is the inner `params` of an rpcEventSchema:
 // { type, seq, … }. `type` discriminates; `seq` is a per-type monotonic counter.
 const seq = z.number().int().nonnegative();
-// status — stream state change + heartbeat
+/**
+ * The engine's RESOLVED runtime encode state (0.4.0, additive), reported on the
+ * `status` event as `active_encode`. Engine = reporter of record: this is the
+ * encode actually running (realized graph), not the requested params. `decoder`
+ * names the runtime-selected decode element for a compressed capture. Absent on a
+ * legacy emitter or a bare state-only heartbeat.
+ */
+export const activeEncodeSchema = z.object({
+    codec: z.string(), // egress codec actually encoding, e.g. "h264"/"h265"
+    resolution: z.string(), // "WxH" pixels in effect, e.g. "1920x1080"
+    framerate: z.number(), // fps in effect, e.g. 29.97
+    active_input: z.string().optional(), // active input id feeding the encode
+    decoder: z.string().optional(), // runtime-selected decode element when transcoding
+});
+/**
+ * `status` event — stream state change + heartbeat. The trailing fields are
+ * additive: the `buffering*` / `spooled_bytes` / `data_headroom_bytes` /
+ * `disk_warning` egress-spool telemetry (Task 32) is absent on a plain heartbeat
+ * and present only on a spool engage/drain transition or disk-usage warning;
+ * `active_profile` (srt-receive-profiles) reports the profile/config the stream is
+ * running under and is absent on a legacy emitter or a bare state-only heartbeat;
+ * `active_encode` (0.4.0) reports the resolved runtime encode and is absent on a
+ * legacy emitter or a bare state-only heartbeat.
+ */
 export const statusEventSchema = z.object({
     type: z.literal("status"),
     seq,
     state: streamStateSchema,
     streaming: z.boolean(),
     active_input: z.string().optional(),
+    active_profile: z.string().optional(),
+    buffering: z.boolean().optional(),
+    spooled_bytes: z.number().int().nonnegative().optional(),
+    data_headroom_bytes: z.number().int().nonnegative().optional(),
+    disk_warning: z.boolean().optional(),
+    active_encode: activeEncodeSchema.optional(),
 });
-// switch — active input changed (manual or failover). media_class is additive
-// (absent on legacy video-only emitters); switch-audio sets it to "audio".
+/**
+ * `switch` event — active input changed (manual or failover). `media_class` is
+ * additive (absent on legacy video-only emitters); `switch-audio` sets it to
+ * `"audio"`.
+ */
 export const switchEventSchema = z.object({
     type: z.literal("switch"),
     seq,
@@ -23,21 +55,21 @@ export const switchEventSchema = z.object({
     reason: z.string().optional(),
     media_class: mediaClassSchema.optional(),
 });
-// device — GstDeviceMonitor hotplug
+/** `device` event — a GstDeviceMonitor hotplug add/remove. */
 export const deviceEventSchema = z.object({
     type: z.literal("device"),
     seq,
     change: z.enum(["added", "removed"]),
     device: captureDeviceSchema,
 });
-// bitrate — adaptive controller adjusted encode bitrate
+/** `bitrate` event — the adaptive controller adjusted the encode bitrate. */
 export const bitrateEventSchema = z.object({
     type: z.literal("bitrate"),
     seq,
     current_bitrate: z.number().int(),
     max_bitrate: z.number().int(),
 });
-// srt-stats — periodic transport stats
+/** `srt-stats` event — periodic SRT transport telemetry. */
 export const srtStatsEventSchema = z.object({
     type: z.literal("srt-stats"),
     seq,
@@ -45,8 +77,10 @@ export const srtStatsEventSchema = z.object({
     send_buffer: z.number().int(),
     pkt_loss: z.number(),
 });
-// error — runtime error (replaces stderr scraping). Tier 2 code; engine reports
-// facts, CeraUI decides what to show (suppressIfSrtlaNotified is a client policy).
+/**
+ * `error` event — a runtime error (replaces stderr scraping). Carries a Tier-2
+ * code; the engine reports facts and CeraUI decides what to surface.
+ */
 export const runtimeErrorEventSchema = z.object({
     type: z.literal("error"),
     seq,
@@ -54,7 +88,7 @@ export const runtimeErrorEventSchema = z.object({
     source: processErrorSourceSchema,
     reason: z.string().optional(), // structured replacement for the stderr <reason>
 });
-// preview — preview session lifecycle
+/** `preview` event — a preview-session lifecycle/phase change. */
 export const previewEventSchema = z.object({
     type: z.literal("preview"),
     seq,

package/dist/messages.d.ts

@@ -6,7 +6,10 @@ export declare const startParamsSchema: z.ZodObject<{
         port: z.ZodNumber;
         streamid: z.ZodOptional<z.ZodString>;
         latency_ms: z.ZodNumber;
+        latency_max_ms: z.ZodOptional<z.ZodNumber>;
         reduced_packet_size: z.ZodOptional<z.ZodBoolean>;
+        fec: z.ZodOptional<z.ZodString>;
+        receiver_supports_fec: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>;
     bitrate: z.ZodObject<{
         min_bitrate: z.ZodNumber;
@@ -18,6 +21,17 @@ export declare const startParamsSchema: z.ZodObject<{
         }>>;
     }, z.core.$strip>;
     input_id: z.ZodOptional<z.ZodString>;
+    codec: z.ZodOptional<z.ZodEnum<{
+        h264: "h264";
+        h265: "h265";
+    }>>;
+    resolution: z.ZodOptional<z.ZodString>;
+    framerate: z.ZodOptional<z.ZodNumber>;
+    audio: z.ZodOptional<z.ZodObject<{
+        device: z.ZodOptional<z.ZodString>;
+        codec: z.ZodOptional<z.ZodString>;
+        delay_ms: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 export type StartParams = z.infer<typeof startParamsSchema>;
 export declare const startResultSchema: z.ZodObject<{
@@ -58,6 +72,7 @@ export declare const reloadConfigParamsSchema: z.ZodObject<{
     }, z.core.$strip>>;
     audio: z.ZodOptional<z.ZodObject<{
         delay_ms: z.ZodOptional<z.ZodNumber>;
+        delay_ms_signed: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export type ReloadConfigParams = z.infer<typeof reloadConfigParamsSchema>;
@@ -77,6 +92,7 @@ export declare const reloadConfigResultSchema: z.ZodObject<{
         }, z.core.$strip>>;
         audio: z.ZodOptional<z.ZodObject<{
             delay_ms: z.ZodOptional<z.ZodNumber>;
+            delay_ms_signed: z.ZodOptional<z.ZodNumber>;
         }, z.core.$strip>>;
     }, z.core.$strip>;
 }, z.core.$strip>;
@@ -145,15 +161,25 @@ export declare const listDevicesResultSchema: z.ZodObject<{
             framerate: z.ZodOptional<z.ZodString>;
             media_type: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>>;
+        kind: 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>>;
 }, z.core.$strip>;
 export type ListDevicesResult = z.infer<typeof listDevicesResultSchema>;
 export declare const eventTopicSchema: z.ZodEnum<{
     error: "error";
+    device: "device";
     bitrate: "bitrate";
     status: "status";
     switch: "switch";
-    device: "device";
     "srt-stats": "srt-stats";
     preview: "preview";
 }>;
@@ -161,10 +187,10 @@ export type EventTopic = z.infer<typeof eventTopicSchema>;
 export declare const subscribeEventsParamsSchema: z.ZodObject<{
     topics: z.ZodOptional<z.ZodArray<z.ZodEnum<{
         error: "error";
+        device: "device";
         bitrate: "bitrate";
         status: "status";
         switch: "switch";
-        device: "device";
         "srt-stats": "srt-stats";
         preview: "preview";
     }>>>;
@@ -173,10 +199,10 @@ export type SubscribeEventsParams = z.infer<typeof subscribeEventsParamsSchema>;
 export declare const subscribeEventsResultSchema: z.ZodObject<{
     subscribed: z.ZodArray<z.ZodEnum<{
         error: "error";
+        device: "device";
         bitrate: "bitrate";
         status: "status";
         switch: "switch";
-        device: "device";
         "srt-stats": "srt-stats";
         preview: "preview";
     }>>;
@@ -228,6 +254,12 @@ export declare const bitrateRangeCapsSchema: z.ZodObject<{
     unit: z.ZodString;
 }, z.core.$strip>;
 export type BitrateRangeCaps = z.infer<typeof bitrateRangeCapsSchema>;
+export declare const latencyRangeCapsSchema: z.ZodObject<{
+    min: z.ZodNumber;
+    default: z.ZodNumber;
+    max: z.ZodNumber;
+}, z.core.$strip>;
+export type LatencyRangeCaps = z.infer<typeof latencyRangeCapsSchema>;
 export declare const encoderCapsSchema: z.ZodObject<{
     codecs: z.ZodArray<z.ZodString>;
     bitrate_range: z.ZodObject<{
@@ -243,6 +275,12 @@ export declare const platformCapsSchema: z.ZodObject<{
     max_resolution: z.ZodString;
 }, z.core.$strip>;
 export type PlatformCaps = z.infer<typeof platformCapsSchema>;
+export declare const previewAvailabilitySchema: z.ZodObject<{
+    enabled: z.ZodBoolean;
+    port: z.ZodOptional<z.ZodNumber>;
+    bound: z.ZodBoolean;
+}, z.core.$strip>;
+export type PreviewAvailability = z.infer<typeof previewAvailabilitySchema>;
 export declare const getCapabilitiesResultSchema: z.ZodObject<{
     platform: z.ZodObject<{
         supports_h265: z.ZodBoolean;
@@ -266,6 +304,19 @@ export declare const getCapabilitiesResultSchema: z.ZodObject<{
         default_framerate: z.ZodNumber;
     }, z.core.$strip>>;
     audio_live_switch: z.ZodOptional<z.ZodBoolean>;
+    latency_range: z.ZodOptional<z.ZodObject<{
+        min: z.ZodNumber;
+        default: z.ZodNumber;
+        max: z.ZodNumber;
+    }, z.core.$strip>>;
+    fec_capable: z.ZodOptional<z.ZodBoolean>;
+    supported_profiles: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    profile_catalog_version: z.ZodOptional<z.ZodString>;
+    preview: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodBoolean;
+        port: z.ZodOptional<z.ZodNumber>;
+        bound: z.ZodBoolean;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 export type GetCapabilitiesResult = z.infer<typeof getCapabilitiesResultSchema>;
 /** The eight v1 control methods (the literal JSON-RPC `method` strings). */
@@ -296,7 +347,10 @@ export declare const requestSchemas: {
                 port: z.ZodNumber;
                 streamid: z.ZodOptional<z.ZodString>;
                 latency_ms: z.ZodNumber;
+                latency_max_ms: z.ZodOptional<z.ZodNumber>;
                 reduced_packet_size: z.ZodOptional<z.ZodBoolean>;
+                fec: z.ZodOptional<z.ZodString>;
+                receiver_supports_fec: z.ZodOptional<z.ZodBoolean>;
             }, z.core.$strip>;
             bitrate: z.ZodObject<{
                 min_bitrate: z.ZodNumber;
@@ -308,6 +362,17 @@ export declare const requestSchemas: {
                 }>>;
             }, z.core.$strip>;
             input_id: z.ZodOptional<z.ZodString>;
+            codec: z.ZodOptional<z.ZodEnum<{
+                h264: "h264";
+                h265: "h265";
+            }>>;
+            resolution: z.ZodOptional<z.ZodString>;
+            framerate: z.ZodOptional<z.ZodNumber>;
+            audio: z.ZodOptional<z.ZodObject<{
+                device: z.ZodOptional<z.ZodString>;
+                codec: z.ZodOptional<z.ZodString>;
+                delay_ms: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strip>>;
         }, z.core.$strip>;
         readonly result: z.ZodObject<{
             session_id: z.ZodString;
@@ -348,6 +413,7 @@ export declare const requestSchemas: {
             }, z.core.$strip>>;
             audio: z.ZodOptional<z.ZodObject<{
                 delay_ms: z.ZodOptional<z.ZodNumber>;
+                delay_ms_signed: z.ZodOptional<z.ZodNumber>;
             }, z.core.$strip>>;
         }, z.core.$strip>;
         readonly result: z.ZodObject<{
@@ -366,6 +432,7 @@ export declare const requestSchemas: {
                 }, z.core.$strip>>;
                 audio: z.ZodOptional<z.ZodObject<{
                     delay_ms: z.ZodOptional<z.ZodNumber>;
+                    delay_ms_signed: z.ZodOptional<z.ZodNumber>;
                 }, z.core.$strip>>;
             }, z.core.$strip>;
         }, z.core.$strip>;
@@ -418,6 +485,16 @@ export declare const requestSchemas: {
                     framerate: z.ZodOptional<z.ZodString>;
                     media_type: z.ZodOptional<z.ZodString>;
                 }, z.core.$strip>>>;
+                kind: 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>>;
         }, z.core.$strip>;
     };
@@ -425,10 +502,10 @@ export declare const requestSchemas: {
         readonly params: z.ZodObject<{
             topics: z.ZodOptional<z.ZodArray<z.ZodEnum<{
                 error: "error";
+                device: "device";
                 bitrate: "bitrate";
                 status: "status";
                 switch: "switch";
-                device: "device";
                 "srt-stats": "srt-stats";
                 preview: "preview";
             }>>>;
@@ -436,10 +513,10 @@ export declare const requestSchemas: {
         readonly result: z.ZodObject<{
             subscribed: z.ZodArray<z.ZodEnum<{
                 error: "error";
+                device: "device";
                 bitrate: "bitrate";
                 status: "status";
                 switch: "switch";
-                device: "device";
                 "srt-stats": "srt-stats";
                 preview: "preview";
             }>>;

package/dist/messages.js

@@ -37,7 +37,8 @@ export const reloadConfigParamsSchema = z.object({
         .optional(),
     audio: z
         .object({
-        delay_ms: z.number().int().min(0).max(AUDIO_DELAY_MAX_MS).optional(),
+        delay_ms: z.number().int().min(0).max(AUDIO_DELAY_MAX_MS).optional(), // legacy unsigned; kept for 0.3.0 callers
+        delay_ms_signed: z.number().int().optional(), // signed sibling; clamped at apply, so unbounded
     })
         .optional(),
 });
@@ -138,6 +139,13 @@ export const bitrateRangeCapsSchema = z.object({
     max: z.number().int(),
     unit: z.string(), // "bps" or "kbps"
 });
+// SRT receive-latency range (ms) for the device-side latency slider. Continuous
+// control (not discrete buckets): min/default/max bounds rendered by CeraUI.
+export const latencyRangeCapsSchema = z.object({
+    min: z.number().int(),
+    default: z.number().int(),
+    max: z.number().int(),
+});
 export const encoderCapsSchema = z.object({
     codecs: z.array(z.string()),
     bitrate_range: bitrateRangeCapsSchema,
@@ -147,11 +155,23 @@ export const platformCapsSchema = z.object({
     hardware_accelerated: z.boolean(),
     max_resolution: z.string(),
 });
+// Preview-server availability (0.4.0, additive). Lets the UI tell an unbound /
+// port-conflicted preview (enabled:true, bound:false) from a down engine.
+export const previewAvailabilitySchema = z.object({
+    enabled: z.boolean(),
+    port: z.number().int().min(1).max(65535).optional(), // present when a listener is (or would be) bound
+    bound: z.boolean(),
+});
 export const getCapabilitiesResultSchema = z.object({
     platform: platformCapsSchema,
     encoder: encoderCapsSchema,
     sources: z.array(videoSourceCapSchema),
     audio_live_switch: z.boolean().optional(),
+    latency_range: latencyRangeCapsSchema.optional(),
+    fec_capable: z.boolean().optional(), // engine can encode FEC on egress (SRTO_PACKETFILTER)
+    supported_profiles: z.array(z.string()).optional(), // SRT receive presets the device offers
+    profile_catalog_version: z.string().optional(), // semver of the supported_profiles catalog
+    preview: previewAvailabilitySchema.optional(), // preview-server availability (unbound vs down)
 });
 // ---- method registry (count-assertion source of truth) ----
 /** The eight v1 control methods (the literal JSON-RPC `method` strings). */

package/dist/transport.d.ts

@@ -18,9 +18,18 @@ export declare class LineSocket {
     private handlers;
     private closed;
     constructor(socketPath: string);
-    /** Connect to the socket and start framing. Rejects on a connect failure. */
+    /**
+     * Connect to the socket and start framing.
+     * @param handlers Line + close callbacks the client installs.
+     * @returns A promise that resolves once connected.
+     * @throws when the underlying `Bun.connect` fails (surfaced to the caller).
+     */
     open(handlers: LineSocketHandlers): Promise<void>;
-    /** Write one NDJSON line (the trailing newline is added here). */
+    /**
+     * Write one NDJSON line (the trailing newline is added here).
+     * @param line One compact JSON value, without a trailing newline.
+     * @throws {Error} when the socket is already closed or not open.
+     */
     send(line: string): void;
     /** Close the connection. Idempotent; does not fire {@link LineSocketHandlers.onClose}. */
     close(): void;

package/dist/transport.js

@@ -14,7 +14,12 @@ export class LineSocket {
     constructor(socketPath) {
         this.socketPath = socketPath;
     }
-    /** Connect to the socket and start framing. Rejects on a connect failure. */
+    /**
+     * Connect to the socket and start framing.
+     * @param handlers Line + close callbacks the client installs.
+     * @returns A promise that resolves once connected.
+     * @throws when the underlying `Bun.connect` fails (surfaced to the caller).
+     */
     async open(handlers) {
         this.handlers = handlers;
         this.socket = await Bun.connect({
@@ -27,7 +32,11 @@ export class LineSocket {
             },
         });
     }
-    /** Write one NDJSON line (the trailing newline is added here). */
+    /**
+     * Write one NDJSON line (the trailing newline is added here).
+     * @param line One compact JSON value, without a trailing newline.
+     * @throws {Error} when the socket is already closed or not open.
+     */
     send(line) {
         if (this.closed || !this.socket) {
             throw new Error("LineSocket.send: socket is not open");

package/dist/types.d.ts

@@ -27,13 +27,32 @@ export declare const previewTierSchema: z.ZodEnum<{
     webrtc: "webrtc";
 }>;
 export type PreviewTier = z.infer<typeof previewTierSchema>;
+export declare const videoCodecSchema: z.ZodEnum<{
+    h264: "h264";
+    h265: "h265";
+}>;
+export type VideoCodec = z.infer<typeof videoCodecSchema>;
+export declare const captureDeviceKindSchema: z.ZodEnum<{
+    audio: "audio";
+    hdmi: "hdmi";
+    uvc_h264: "uvc_h264";
+    uvc_h265: "uvc_h265";
+    mjpeg: "mjpeg";
+    camlink: "camlink";
+    test: "test";
+    network: "network";
+}>;
+export type CaptureDeviceKind = z.infer<typeof captureDeviceKindSchema>;
 /** SRT transport config. Mirrors schema.md `start.srt` exactly. */
 export declare const srtConfigSchema: z.ZodObject<{
     host: z.ZodString;
     port: z.ZodNumber;
     streamid: z.ZodOptional<z.ZodString>;
     latency_ms: z.ZodNumber;
+    latency_max_ms: z.ZodOptional<z.ZodNumber>;
     reduced_packet_size: z.ZodOptional<z.ZodBoolean>;
+    fec: z.ZodOptional<z.ZodString>;
+    receiver_supports_fec: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;
 export type SrtConfig = z.infer<typeof srtConfigSchema>;
 /** Bitrate / balancer config. Mirrors schema.md `start.bitrate` exactly. */
@@ -47,6 +66,19 @@ export declare const bitrateConfigSchema: z.ZodObject<{
     }>>;
 }, z.core.$strip>;
 export type BitrateConfig = z.infer<typeof bitrateConfigSchema>;
+/**
+ * Audio config section of the unified engine config (0.4.0, additive). Every
+ * field is optional, so a legacy caller omits the whole `audio` section and a
+ * 0.3.0 engine ignores it. `delay_ms` is signed from birth (positive = audio
+ * later, negative = earlier); it is clamped to ±AUDIO_DELAY_MAX_MS when applied,
+ * never rejected — so the schema does NOT bound it.
+ */
+export declare const audioConfigSchema: z.ZodObject<{
+    device: z.ZodOptional<z.ZodString>;
+    codec: z.ZodOptional<z.ZodString>;
+    delay_ms: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type AudioConfig = z.infer<typeof audioConfigSchema>;
 /**
  * Unified cerastream engine config — the complete shape needed to `start` a
  * stream and the canonical persisted profile. `start` params ARE this config
@@ -60,7 +92,10 @@ export declare const cerastreamConfigSchema: z.ZodObject<{
         port: z.ZodNumber;
         streamid: z.ZodOptional<z.ZodString>;
         latency_ms: z.ZodNumber;
+        latency_max_ms: z.ZodOptional<z.ZodNumber>;
         reduced_packet_size: z.ZodOptional<z.ZodBoolean>;
+        fec: z.ZodOptional<z.ZodString>;
+        receiver_supports_fec: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>;
     bitrate: z.ZodObject<{
         min_bitrate: z.ZodNumber;
@@ -72,6 +107,17 @@ export declare const cerastreamConfigSchema: z.ZodObject<{
         }>>;
     }, z.core.$strip>;
     input_id: z.ZodOptional<z.ZodString>;
+    codec: z.ZodOptional<z.ZodEnum<{
+        h264: "h264";
+        h265: "h265";
+    }>>;
+    resolution: z.ZodOptional<z.ZodString>;
+    framerate: z.ZodOptional<z.ZodNumber>;
+    audio: z.ZodOptional<z.ZodObject<{
+        device: z.ZodOptional<z.ZodString>;
+        codec: z.ZodOptional<z.ZodString>;
+        delay_ms: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 export type CerastreamConfig = z.infer<typeof cerastreamConfigSchema>;
 export type PartialCerastreamConfig = z.input<typeof cerastreamConfigSchema>;
@@ -102,6 +148,16 @@ export declare const captureDeviceSchema: z.ZodObject<{
         framerate: z.ZodOptional<z.ZodString>;
         media_type: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>>;
+    kind: 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 CaptureDevice = z.infer<typeof captureDeviceSchema>;
 export declare const srtStatsSchema: z.ZodObject<{

package/dist/types.js

@@ -14,20 +14,63 @@ export const inputModeSchema = z.enum(["manual", "auto"]);
 export const balancerAlgorithmSchema = z.enum(["adaptive", "fixed", "aimd"]);
 export const mediaClassSchema = z.enum(["video", "audio"]);
 export const previewTierSchema = z.enum(["webcodecs", "webrtc"]);
+// Requested egress video codec (0.4.0, additive). Absent ⇒ the engine picks its
+// platform default. Wire values are the codec id strings the encoder caps also
+// advertise ("h264"/"h265") — never an encoder element name.
+export const videoCodecSchema = z.enum(["h264", "h265"]);
+// Engine-typed capture-device family (0.4.0, additive). CeraUI groups a device
+// by the engine's resolved kind (a UVC/USB dongle is uvc_h264/mjpeg, never
+// mislabeled HDMI). Absent ⇒ CeraUI falls back to a bus/name heuristic.
+export const captureDeviceKindSchema = z.enum([
+    "hdmi",
+    "uvc_h264",
+    "uvc_h265",
+    "mjpeg",
+    "camlink",
+    "audio",
+    "test",
+    "network",
+]);
 // ---- config sub-schemas (canonical; reused by `start` + the unified config) ----
 /** SRT transport config. Mirrors schema.md `start.srt` exactly. */
 export const srtConfigSchema = z.object({
     host: z.string(),
     port: z.number().int().min(1).max(65535),
     streamid: z.string().optional(),
+    // Continuous device-side latency wired to SRTO_LATENCY, applied on (re)connect.
     latency_ms: z.number().int().min(100).max(10_000),
+    // Receiver-advertised ceiling; latency_ms is clamped to it. Additive/optional.
+    latency_max_ms: z.number().int().min(100).max(10_000).optional(),
     reduced_packet_size: z.boolean().optional(),
+    // SRT FEC packet-filter config (sender full config). Wired to SRTO_PACKETFILTER
+    // on (re)connect, but ONLY when receiver_supports_fec is true (G2). Additive.
+    fec: z.string().optional(),
+    // Receiver affirmatively known FEC-capable; gates `fec`. Additive (default off).
+    receiver_supports_fec: z.boolean().optional(),
 });
 /** Bitrate / balancer config. Mirrors schema.md `start.bitrate` exactly. */
-export const bitrateConfigSchema = z.object({
+export const bitrateConfigSchema = z
+    .object({
     min_bitrate: z.number().int().min(1),
     max_bitrate: z.number().int().min(1),
     balancer: balancerAlgorithmSchema.default(DEFAULT_BALANCER),
+})
+    // Mirrors the Rust dispatch guard: an inverted range can't drive the balancer.
+    .refine((b) => b.min_bitrate <= b.max_bitrate, {
+    message: "min_bitrate must not exceed max_bitrate",
+    path: ["min_bitrate"],
+});
+/**
+ * Audio config section of the unified engine config (0.4.0, additive). Every
+ * field is optional, so a legacy caller omits the whole `audio` section and a
+ * 0.3.0 engine ignores it. `delay_ms` is signed from birth (positive = audio
+ * later, negative = earlier); it is clamped to ±AUDIO_DELAY_MAX_MS when applied,
+ * never rejected — so the schema does NOT bound it.
+ */
+export const audioConfigSchema = z.object({
+    device: z.string().optional(), // ALSA capture device id; absent ⇒ test-tone fallback
+    codec: z.string().optional(), // audio encoder codec id (e.g. "aac", "opus")
+    delay_ms: z.number().int().optional(), // signed A/V-sync delay (clamped at apply)
 });
 /**
  * Unified cerastream engine config — the complete shape needed to `start` a
@@ -40,6 +83,10 @@ export const cerastreamConfigSchema = z.object({
     srt: srtConfigSchema,
     bitrate: bitrateConfigSchema,
     input_id: z.string().optional(), // initial active input; defaults to primary
+    codec: videoCodecSchema.optional(), // additive (0.4.0): egress codec; absent ⇒ platform default
+    resolution: z.string().optional(), // additive (0.4.0): "WxH" pixel form (never a UI token)
+    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
 });
 // convenience defaults for building a config client-side
 export const DEFAULT_BITRATE_CONFIG = {
@@ -61,6 +108,7 @@ export const captureDeviceSchema = z.object({
     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
 });
 // ---- transport telemetry (srt-stats event payload) ----
 export const srtStatsSchema = z.object({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ceralive/cerastream",
-  "version": "2026.6.2",
+  "version": "2026.7.0",
   "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",