@ceralive/cerastream 2026.9.5 → 2026.9.6

package/README.md

@@ -86,6 +86,15 @@ systemd-owned service — the client connects to it and never spawns it.
 
 ## Versioning
 
+Version **2026.9.6 / schema 0.18.0** adds
+`client.listSwitchTargets()` and optional `active_encode.switch_targets`.
+Targets are `{input_id, kind: "capture"|"synthetic"|"network"}`; the query returns
+`{session_id?, active_input?, switch_targets: [...]}`. They describe built live
+legs, not idle capabilities; passthrough/composition explicitly return `[]`.
+Import `SessionSwitchTarget` and `ListSwitchTargetsResult` from this package,
+never shadow the wire types. Re-query before switching and handle refusal; the
+snapshot does not reserve a leg. Release/publish must happen before consumption.
+
 Two independent version axes. The **wire-schema version** (`PROTOCOL_VERSION` +
 `SCHEMA_VERSION`) is pinned cross-language with the engine and is additive-only
 within `cerastream-ipc/1`. The **npm package version** is CalVer

package/dist/client.d.ts

@@ -1,6 +1,7 @@
 import { type HelloResult } from './envelope.js';
 import { type EventParams } from './events.js';
 import { type ChangeConfigParams, type ChangeConfigResult, type GetCapabilitiesResult, type ListDevicesParams, type ListDevicesResult, type PreviewSessionParams, type PreviewSessionResult, type ReloadConfigParams, type ReloadConfigResult, type RequestKeyframeResult, type SetBitrateParams, type SetBitrateResult, type SetEdidProfileParams, type SetEdidProfileResult, type StartParams, type StartResult, type StopParams, type StopResult, type SubscribeEventsParams, type SubscribeEventsResult, type SwitchInputParams, type SwitchInputResult } from './messages.js';
+import { type ListSwitchTargetsResult } from './session-switch.js';
 /** Options for {@link connect}. All optional — `connect({})` is valid. */
 export interface ConnectOptions {
     /** Control socket path override. Defaults to the resolved /run/cerastream/control.sock. */
@@ -82,6 +83,7 @@ export interface CerastreamClient {
      * @throws {CerastreamRpcError} when the input id is unknown.
      */
     switchInput(params: SwitchInputParams): Promise<SwitchInputResult>;
+    listSwitchTargets(): Promise<ListSwitchTargetsResult>;
     /**
      * Enumerate capture devices (GstDeviceMonitor, de-duped by device path).
      * @param params Optional media-class filter.

package/dist/client.js

@@ -5,6 +5,7 @@ import { CerastreamConnectionError, CerastreamRpcError, CerastreamTimeoutError,
 import { eventParamsSchema } from './events.js';
 import { changeConfigParamsSchema, changeConfigResultSchema, getCapabilitiesResultSchema, requestKeyframeResultSchema, requestSchemas, setEdidProfileResultSchema, } from './messages.js';
 import { controlSocketPath } from './paths.js';
+import { listSwitchTargetsResultSchema } from './session-switch.js';
 import { LineSocket } from './transport.js';
 const DEFAULTS = {
     requestTimeoutMs: 10_000,
@@ -82,6 +83,9 @@ class ClientImpl {
     listDevices(params) {
         return this.call('list-devices', params);
     }
+    async listSwitchTargets() {
+        return listSwitchTargetsResultSchema.parse(await this.rawRequest('list-switch-targets', {}));
+    }
     async getCapabilities() {
         return getCapabilitiesResultSchema.parse(await this.rawRequest('get-capabilities', undefined));
     }

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.17.0';
+export declare const SCHEMA_VERSION: '0.18.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}. */

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.17.0';
+export const SCHEMA_VERSION = '0.18.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}. */

package/dist/events.d.ts

@@ -11,6 +11,14 @@ export declare const activeEncodeSchema: z.ZodObject<{
     resolution: z.ZodString;
     framerate: z.ZodNumber;
     active_input: z.ZodOptional<z.ZodString>;
+    switch_targets: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        input_id: z.ZodString;
+        kind: z.ZodEnum<{
+            capture: "capture";
+            network: "network";
+            synthetic: "synthetic";
+        }>;
+    }, z.core.$strip>>>;
     decoder: z.ZodOptional<z.ZodString>;
     input_codec: z.ZodOptional<z.ZodString>;
     passthrough: z.ZodOptional<z.ZodBoolean>;
@@ -84,6 +92,14 @@ export declare const statusEventSchema: z.ZodObject<{
         resolution: z.ZodString;
         framerate: z.ZodNumber;
         active_input: z.ZodOptional<z.ZodString>;
+        switch_targets: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            input_id: z.ZodString;
+            kind: z.ZodEnum<{
+                capture: "capture";
+                network: "network";
+                synthetic: "synthetic";
+            }>;
+        }, z.core.$strip>>>;
         decoder: z.ZodOptional<z.ZodString>;
         input_codec: z.ZodOptional<z.ZodString>;
         passthrough: z.ZodOptional<z.ZodBoolean>;
@@ -342,6 +358,14 @@ export declare const eventParamsSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         resolution: z.ZodString;
         framerate: z.ZodNumber;
         active_input: z.ZodOptional<z.ZodString>;
+        switch_targets: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            input_id: z.ZodString;
+            kind: z.ZodEnum<{
+                capture: "capture";
+                network: "network";
+                synthetic: "synthetic";
+            }>;
+        }, z.core.$strip>>>;
         decoder: z.ZodOptional<z.ZodString>;
         input_codec: z.ZodOptional<z.ZodString>;
         passthrough: z.ZodOptional<z.ZodBoolean>;
@@ -547,6 +571,14 @@ export declare const cerastreamEventSchema: z.ZodObject<{
             resolution: z.ZodString;
             framerate: z.ZodNumber;
             active_input: z.ZodOptional<z.ZodString>;
+            switch_targets: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                input_id: z.ZodString;
+                kind: z.ZodEnum<{
+                    capture: "capture";
+                    network: "network";
+                    synthetic: "synthetic";
+                }>;
+            }, z.core.$strip>>>;
             decoder: z.ZodOptional<z.ZodString>;
             input_codec: z.ZodOptional<z.ZodString>;
             passthrough: z.ZodOptional<z.ZodBoolean>;
@@ -756,6 +788,14 @@ export declare const eventSchemas: {
             resolution: z.ZodString;
             framerate: z.ZodNumber;
             active_input: z.ZodOptional<z.ZodString>;
+            switch_targets: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                input_id: z.ZodString;
+                kind: z.ZodEnum<{
+                    capture: "capture";
+                    network: "network";
+                    synthetic: "synthetic";
+                }>;
+            }, z.core.$strip>>>;
             decoder: z.ZodOptional<z.ZodString>;
             input_codec: z.ZodOptional<z.ZodString>;
             passthrough: z.ZodOptional<z.ZodBoolean>;

package/dist/events.js

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import { captureCauseSchema, processErrorCodeSchema, processErrorSourceSchema } from './errors.js';
+import { sessionSwitchTargetSchema } from './session-switch.js';
 import { captureDeviceSchema, configChangePhaseSchema, inputModeSchema, mediaClassSchema, previewEncodeFallbackSchema, previewEncodeModeSchema, streamStateSchema, } from './types.js';
 // Server → client `event` notifications, delivered after `subscribe-events`
 // (schema.md "Events"). Each event is the inner `params` of an rpcEventSchema:
@@ -17,6 +18,7 @@ export const activeEncodeSchema = z.object({
     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
+    switch_targets: z.array(sessionSwitchTargetSchema).optional(),
     decoder: z.string().optional(), // runtime-selected decode element when transcoding
     input_codec: z.string().optional(), // incoming pre-decode codec token: "h264"/"h265"/"mjpeg"
     passthrough: z.boolean().optional(), // 0.5.0: true when a same-codec passthrough graph is live (no decode/re-encode)

package/dist/index.d.ts

@@ -6,4 +6,5 @@ export * from './errors.js';
 export * from './events.js';
 export * from './messages.js';
 export * from './paths.js';
+export * from './session-switch.js';
 export * from './types.js';

package/dist/index.js

@@ -10,4 +10,5 @@ export * from './errors.js';
 export * from './events.js';
 export * from './messages.js';
 export * from './paths.js';
+export * from './session-switch.js';
 export * from './types.js';

package/dist/session-switch.d.ts

@@ -0,0 +1,33 @@
+import { z } from 'zod';
+/** Already-built program-switch legs, not the idle source catalog. */
+export declare const sessionSwitchTargetKindSchema: z.ZodEnum<{
+    capture: "capture";
+    network: "network";
+    synthetic: "synthetic";
+}>;
+export type SessionSwitchTargetKind = z.infer<typeof sessionSwitchTargetKindSchema>;
+export declare const sessionSwitchTargetSchema: z.ZodObject<{
+    input_id: z.ZodString;
+    kind: z.ZodEnum<{
+        capture: "capture";
+        network: "network";
+        synthetic: "synthetic";
+    }>;
+}, z.core.$strip>;
+export type SessionSwitchTarget = z.infer<typeof sessionSwitchTargetSchema>;
+export declare const listSwitchTargetsParamsSchema: z.ZodObject<{}, z.core.$strip>;
+export type ListSwitchTargetsParams = z.infer<typeof listSwitchTargetsParamsSchema>;
+/** A snapshot, not a reservation; re-query before dispatch and handle switch refusal. */
+export declare const listSwitchTargetsResultSchema: z.ZodObject<{
+    session_id: z.ZodOptional<z.ZodString>;
+    active_input: z.ZodOptional<z.ZodString>;
+    switch_targets: z.ZodArray<z.ZodObject<{
+        input_id: z.ZodString;
+        kind: z.ZodEnum<{
+            capture: "capture";
+            network: "network";
+            synthetic: "synthetic";
+        }>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type ListSwitchTargetsResult = z.infer<typeof listSwitchTargetsResultSchema>;

package/dist/session-switch.js

@@ -0,0 +1,14 @@
+import { z } from 'zod';
+/** Already-built program-switch legs, not the idle source catalog. */
+export const sessionSwitchTargetKindSchema = z.enum(['capture', 'synthetic', 'network']);
+export const sessionSwitchTargetSchema = z.object({
+    input_id: z.string(),
+    kind: sessionSwitchTargetKindSchema,
+});
+export const listSwitchTargetsParamsSchema = z.object({});
+/** A snapshot, not a reservation; re-query before dispatch and handle switch refusal. */
+export const listSwitchTargetsResultSchema = z.object({
+    session_id: z.string().optional(),
+    active_input: z.string().optional(),
+    switch_targets: z.array(sessionSwitchTargetSchema),
+});

package/package.json

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