@ceralive/cerastream 2026.7.5 → 2026.8.0

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, captureDeviceKindSchema, captureDeviceSchema, cerastreamConfigSchema, configChangePhaseSchema, inputModeSchema, mediaClassSchema, previewTierSchema, streamStateSchema, videoCodecSchema, } from "./types.js";
+import { z } from 'zod';
+import { AUDIO_DELAY_MAX_MS } from './constants.js';
+import { helloParamsSchema, helloResultSchema } from './envelope.js';
+import { balancerAlgorithmSchema, bitrateControlSchema, captureDeviceKindSchema, captureDeviceSchema, cerastreamConfigSchema, configChangePhaseSchema, inputModeSchema, mediaClassSchema, previewEncodeModeSchema, 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 ----
@@ -45,6 +45,12 @@ export const reloadConfigParamsSchema = z.object({
         meter_device: z.string().nullable().optional(),
     })
         .optional(),
+    // Absent leaves the engine's current preview-encoder selection unchanged. This
+    // belongs on `reload-config` rather than `change-config`: the preview encoder is
+    // fixed when a session graph is built, so it takes effect on the NEXT stream
+    // session, and routing it through the transactional method would restart a live
+    // stream to change a preview setting.
+    preview_encode: previewEncodeModeSchema.optional(),
 });
 export const reloadConfigResultSchema = z.object({
     applied: reloadConfigParamsSchema, // post-clamp values actually applied
@@ -67,7 +73,7 @@ export const setBitrateResultSchema = z.object({
 // ---- 5. switch-input ----
 export const switchInputParamsSchema = z.object({
     input_id: z.string(), // device/input identifier from list-devices
-    mode: inputModeSchema.default("manual"),
+    mode: inputModeSchema.default('manual'),
 });
 export const switchInputResultSchema = z.object({
     active_input: z.string(),
@@ -96,15 +102,15 @@ export const listDevicesResultSchema = z.object({
 });
 // ---- 7. subscribe-events ----
 export const eventTopicSchema = z.enum([
-    "status",
-    "switch",
-    "device",
-    "bitrate",
-    "srt-stats",
-    "error",
-    "preview",
-    "audio-level",
-    "config-change",
+    'status',
+    'switch',
+    'device',
+    'bitrate',
+    'srt-stats',
+    'error',
+    'preview',
+    'audio-level',
+    'config-change',
 ]);
 export const subscribeEventsParamsSchema = z.object({
     topics: z.array(eventTopicSchema).optional(), // default: all topics
@@ -113,14 +119,14 @@ export const subscribeEventsResultSchema = z.object({
     subscribed: z.array(eventTopicSchema),
 });
 // ---- 8. preview-session ----
-export const previewSessionParamsSchema = z.discriminatedUnion("action", [
+export const previewSessionParamsSchema = z.discriminatedUnion('action', [
     z.object({
-        action: z.literal("start"),
+        action: z.literal('start'),
         tier: previewTierSchema,
     }),
-    z.object({ action: z.literal("stop"), session_id: z.string() }),
+    z.object({ action: z.literal('stop'), session_id: z.string() }),
     z.object({
-        action: z.literal("signal"), // webrtc only
+        action: z.literal('signal'), // webrtc only
         session_id: z.string(),
         sdp: z.string().optional(),
         ice: z.unknown().optional(),
@@ -129,12 +135,12 @@ export const previewSessionParamsSchema = z.discriminatedUnion("action", [
 export const previewSessionResultSchema = z.object({
     session_id: z.string(),
     tier: previewTierSchema,
-    transport: z.discriminatedUnion("kind", [
+    transport: z.discriminatedUnion('kind', [
         z.object({
-            kind: z.literal("uds-binary"),
-            socket: z.literal("/run/cerastream/preview.sock"),
+            kind: z.literal('uds-binary'),
+            socket: z.literal('/run/cerastream/preview.sock'),
         }),
-        z.object({ kind: z.literal("webrtc"), sdp: z.string().optional() }),
+        z.object({ kind: z.literal('webrtc'), sdp: z.string().optional() }),
     ]),
 });
 // ---- 9. get-capabilities ----
@@ -170,8 +176,8 @@ export const platformCapsSchema = z.object({
     max_resolution: z.string(),
     // additive: the engine's resolved hardware kind and how it was resolved.
     // Optional so a pre-field engine (which omits both) still parses.
-    hardware_kind: z.enum(["rk3588", "jetson", "n100", "generic"]).optional(),
-    source: z.enum(["detected", "override"]).optional(),
+    hardware_kind: z.enum(['rk3588', 'jetson', 'n100', 'generic']).optional(),
+    source: z.enum(['detected', 'override']).optional(),
 });
 // Preview-server availability (0.4.0, additive). Lets the UI tell an unbound /
 // port-conflicted preview (enabled:true, bound:false) from a down engine.
@@ -179,6 +185,15 @@ 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(),
+    // Whether this PLATFORM publishes a hardware preview encoder at all — the fact
+    // that decides whether a hardware-preview toggle may be offered. It rides the
+    // capability fetch rather than stream status because a consumer reads
+    // capabilities while IDLE, which is exactly when the operator picks the setting.
+    // Three readings, none interchangeable: absent ⇒ legacy engine, capability
+    // UNKNOWN (never assume false); false ⇒ this board publishes none, hide the
+    // toggle; true ⇒ it does. Independent of whether any session is realizing it
+    // (`status.preview_encoder_realized`).
+    preview_hw_capability: z.boolean().optional(),
 });
 export const getCapabilitiesResultSchema = z.object({
     platform: platformCapsSchema,
@@ -216,7 +231,7 @@ export const changeConfigParamsSchema = z
     input_mode: captureDeviceKindSchema.optional(),
 })
     .refine((delta) => Object.keys(delta).length > 0, {
-    message: "change-config delta must carry at least one field",
+    message: 'change-config delta must carry at least one field',
 });
 // `Ok` for every phase the transaction actually reached — INCLUDING
 // `rollback_failed`, an honest terminal outcome rather than an RPC fault. A
@@ -235,18 +250,18 @@ export const changeConfigResultSchema = z.object({
  * refuses to build a second session that would race it. Mirrors the Rust
  * `REASON_TEARDOWN_TIMEOUT`; consumers render it distinctly.
  */
-export const REASON_TEARDOWN_TIMEOUT = "teardown_timeout";
+export const REASON_TEARDOWN_TIMEOUT = 'teardown_timeout';
 // ---- method registry (count-assertion source of truth) ----
 /** The eight v1 control methods (the literal JSON-RPC `method` strings). */
 export const V1_METHODS = [
-    "start",
-    "stop",
-    "reload-config",
-    "set-bitrate",
-    "switch-input",
-    "list-devices",
-    "subscribe-events",
-    "preview-session",
+    'start',
+    'stop',
+    'reload-config',
+    'set-bitrate',
+    'switch-input',
+    'list-devices',
+    'subscribe-events',
+    'preview-session',
 ];
 /**
  * method → { params, result } Zod schema pair. `hello` is the handshake; the
@@ -257,27 +272,27 @@ export const requestSchemas = {
     hello: { params: helloParamsSchema, result: helloResultSchema },
     start: { params: startParamsSchema, result: startResultSchema },
     stop: { params: stopParamsSchema, result: stopResultSchema },
-    "reload-config": {
+    'reload-config': {
         params: reloadConfigParamsSchema,
         result: reloadConfigResultSchema,
     },
-    "set-bitrate": {
+    'set-bitrate': {
         params: setBitrateParamsSchema,
         result: setBitrateResultSchema,
     },
-    "switch-input": {
+    'switch-input': {
         params: switchInputParamsSchema,
         result: switchInputResultSchema,
     },
-    "list-devices": {
+    'list-devices': {
         params: listDevicesParamsSchema,
         result: listDevicesResultSchema,
     },
-    "subscribe-events": {
+    'subscribe-events': {
         params: subscribeEventsParamsSchema,
         result: subscribeEventsResultSchema,
     },
-    "preview-session": {
+    'preview-session': {
         params: previewSessionParamsSchema,
         result: previewSessionResultSchema,
     },

package/dist/paths.d.ts

@@ -1,4 +1,4 @@
-import { CONTROL_SOCKET_NAME, DEFAULT_IPC_DIR, PREVIEW_SOCKET_NAME } from "./constants.js";
+import { CONTROL_SOCKET_NAME, DEFAULT_IPC_DIR, PREVIEW_SOCKET_NAME } from './constants.js';
 /** Resolve the IPC runtime dir: explicit override → {@link IPC_DIR_ENV} → default. */
 export declare function resolveIpcDir(override?: string): string;
 /** Resolve the control-plane socket path within the (possibly overridden) IPC dir. */
@@ -11,4 +11,4 @@ export declare function previewSocketPath(dir?: string): string;
  * `/usr/bin/cerastream` → the bare name (let PATH decide).
  */
 export declare function getCerastreamExec(execPath?: string): string;
-export { DEFAULT_IPC_DIR, CONTROL_SOCKET_NAME, PREVIEW_SOCKET_NAME };
+export { CONTROL_SOCKET_NAME, DEFAULT_IPC_DIR, PREVIEW_SOCKET_NAME };

package/dist/paths.js

@@ -1,7 +1,7 @@
-import { execSync } from "node:child_process";
-import { existsSync, statSync } from "node:fs";
-import { join } from "node:path";
-import { CERASTREAM_BIN, CONTROL_SOCKET_NAME, DEFAULT_IPC_DIR, IPC_DIR_ENV, PREVIEW_SOCKET_NAME, } from "./constants.js";
+import { execSync } from 'node:child_process';
+import { existsSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { CERASTREAM_BIN, CONTROL_SOCKET_NAME, DEFAULT_IPC_DIR, IPC_DIR_ENV, PREVIEW_SOCKET_NAME, } from './constants.js';
 // Socket-path + engine-exec helpers (ADR-0002 §3). They resolve the runtime IPC
 // dir from the CERASTREAM_IPC_DIR override (then the explicit arg), defaulting to
 // /run/cerastream. cerastream is a systemd-owned service (ADR-0005) — CeraUI
@@ -34,9 +34,7 @@ export function getCerastreamExec(execPath) {
         const inDir = join(execPath, CERASTREAM_BIN);
         if (isFile(inDir))
             return inDir;
-        return execPath.endsWith(CERASTREAM_BIN)
-            ? execPath
-            : join(execPath, CERASTREAM_BIN);
+        return execPath.endsWith(CERASTREAM_BIN) ? execPath : join(execPath, CERASTREAM_BIN);
     }
     const onPath = findInPath(CERASTREAM_BIN);
     if (onPath)
@@ -57,10 +55,10 @@ function isFile(p) {
 function findInPath(name) {
     try {
         const out = execSync(`command -v ${name}`, {
-            encoding: "utf-8",
-            stdio: ["pipe", "pipe", "pipe"],
+            encoding: 'utf-8',
+            stdio: ['pipe', 'pipe', 'pipe'],
         }).trim();
-        const first = out.split("\n")[0]?.trim();
+        const first = out.split('\n')[0]?.trim();
         if (first && existsSync(first))
             return first;
     }
@@ -69,4 +67,4 @@ function findInPath(name) {
     }
     return undefined;
 }
-export { DEFAULT_IPC_DIR, CONTROL_SOCKET_NAME, PREVIEW_SOCKET_NAME };
+export { CONTROL_SOCKET_NAME, DEFAULT_IPC_DIR, PREVIEW_SOCKET_NAME };

package/dist/transport.js

@@ -1,4 +1,4 @@
-import { MAX_LINE_BYTES } from "./constants.js";
+import { MAX_LINE_BYTES } from './constants.js';
 /**
  * A single Unix-socket connection that frames bytes into NDJSON lines. Construct,
  * `open()` (rejects if the socket can't be reached), `send()` lines, `close()`
@@ -7,7 +7,7 @@ import { MAX_LINE_BYTES } from "./constants.js";
 export class LineSocket {
     socketPath;
     socket;
-    buffer = "";
+    buffer = '';
     bufferedBytes = 0;
     handlers;
     closed = false;
@@ -39,7 +39,7 @@ export class LineSocket {
      */
     send(line) {
         if (this.closed || !this.socket) {
-            throw new Error("LineSocket.send: socket is not open");
+            throw new Error('LineSocket.send: socket is not open');
         }
         this.socket.write(`${line}\n`);
         this.socket.flush();
@@ -61,9 +61,9 @@ export class LineSocket {
     onData(chunk) {
         if (this.closed)
             return;
-        this.buffer += chunk.toString("utf8");
+        this.buffer += chunk.toString('utf8');
         this.bufferedBytes += chunk.byteLength;
-        let nl = this.buffer.indexOf("\n");
+        let nl = this.buffer.indexOf('\n');
         if (nl === -1) {
             // No complete line yet — guard the unbounded-line case (fatal framing error).
             if (this.bufferedBytes > MAX_LINE_BYTES) {
@@ -80,9 +80,9 @@ export class LineSocket {
             }
             if (line.length > 0)
                 this.handlers?.onLine(line);
-            nl = this.buffer.indexOf("\n");
+            nl = this.buffer.indexOf('\n');
         }
-        this.bufferedBytes = Buffer.byteLength(this.buffer, "utf8");
+        this.bufferedBytes = Buffer.byteLength(this.buffer, 'utf8');
     }
     fail(err) {
         this.fireClose(err);

package/dist/types.d.ts

@@ -1,25 +1,25 @@
-import { z } from "zod";
+import { z } from 'zod';
 export declare const streamStateSchema: z.ZodEnum<{
     idle: "idle";
     starting: "starting";
-    streaming: "streaming";
     stopping: "stopping";
+    streaming: "streaming";
 }>;
 export type StreamState = z.infer<typeof streamStateSchema>;
 export declare const inputModeSchema: z.ZodEnum<{
-    manual: "manual";
     auto: "auto";
+    manual: "manual";
 }>;
 export type InputMode = z.infer<typeof inputModeSchema>;
 export declare const balancerAlgorithmSchema: z.ZodEnum<{
     adaptive: "adaptive";
-    fixed: "fixed";
     aimd: "aimd";
+    fixed: "fixed";
 }>;
 export type BalancerAlgorithm = z.infer<typeof balancerAlgorithmSchema>;
 export declare const mediaClassSchema: z.ZodEnum<{
-    video: "video";
     audio: "audio";
+    video: "video";
 }>;
 export type MediaClass = z.infer<typeof mediaClassSchema>;
 export declare const previewTierSchema: z.ZodEnum<{
@@ -27,6 +27,18 @@ export declare const previewTierSchema: z.ZodEnum<{
     webrtc: "webrtc";
 }>;
 export type PreviewTier = z.infer<typeof previewTierSchema>;
+export declare const previewEncodeModeSchema: z.ZodEnum<{
+    hardware: "hardware";
+    software: "software";
+}>;
+export type PreviewEncodeMode = z.infer<typeof previewEncodeModeSchema>;
+export declare const previewEncodeFallbackSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    code: z.ZodLiteral<"factory-missing">;
+}, z.core.$strip>, z.ZodObject<{
+    code: z.ZodLiteral<"property-failure">;
+    property: z.ZodString;
+}, z.core.$strip>], "code">;
+export type PreviewEncodeFallback = z.infer<typeof previewEncodeFallbackSchema>;
 export declare const videoCodecSchema: z.ZodEnum<{
     h264: "h264";
     h265: "h265";
@@ -45,25 +57,25 @@ export declare const bitrateControlSchema: z.ZodEnum<{
 export type BitrateControl = z.infer<typeof bitrateControlSchema>;
 export declare const captureDeviceKindSchema: z.ZodEnum<{
     audio: "audio";
+    camlink: "camlink";
     hdmi: "hdmi";
-    uvc_h264: "uvc_h264";
-    uvc_h265: "uvc_h265";
     mjpeg: "mjpeg";
-    camlink: "camlink";
-    test: "test";
     network: "network";
+    test: "test";
+    uvc_h264: "uvc_h264";
+    uvc_h265: "uvc_h265";
 }>;
 export type CaptureDeviceKind = z.infer<typeof captureDeviceKindSchema>;
 export declare const deviceTransportSchema: z.ZodEnum<{
-    hdmi: "hdmi";
-    usb: "usb";
     bluetooth: "bluetooth";
+    hdmi: "hdmi";
     onboard: "onboard";
+    usb: "usb";
 }>;
 export type DeviceTransport = z.infer<typeof deviceTransportSchema>;
 export declare const configChangePhaseSchema: z.ZodEnum<{
-    applying: "applying";
     applied: "applied";
+    applying: "applying";
     reverted: "reverted";
     rollback_failed: "rollback_failed";
 }>;
@@ -86,8 +98,8 @@ export declare const bitrateConfigSchema: z.ZodObject<{
     max_bitrate: z.ZodNumber;
     balancer: z.ZodDefault<z.ZodEnum<{
         adaptive: "adaptive";
-        fixed: "fixed";
         aimd: "aimd";
+        fixed: "fixed";
     }>>;
 }, z.core.$strip>;
 export type BitrateConfig = z.infer<typeof bitrateConfigSchema>;
@@ -100,15 +112,15 @@ export type BitrateConfig = z.infer<typeof bitrateConfigSchema>;
  */
 export declare const audioModeSchema: z.ZodEnum<{
     default: "default";
-    none: "none";
     device: "device";
+    none: "none";
 }>;
 export type AudioMode = z.infer<typeof audioModeSchema>;
 export declare const audioConfigSchema: z.ZodObject<{
     mode: z.ZodOptional<z.ZodEnum<{
         default: "default";
-        none: "none";
         device: "device";
+        none: "none";
     }>>;
     device: z.ZodOptional<z.ZodString>;
     codec: z.ZodOptional<z.ZodString>;
@@ -138,8 +150,8 @@ export declare const cerastreamConfigSchema: z.ZodObject<{
         max_bitrate: z.ZodNumber;
         balancer: z.ZodDefault<z.ZodEnum<{
             adaptive: "adaptive";
-            fixed: "fixed";
             aimd: "aimd";
+            fixed: "fixed";
         }>>;
     }, z.core.$strip>;
     input_id: z.ZodOptional<z.ZodString>;
@@ -152,8 +164,8 @@ export declare const cerastreamConfigSchema: z.ZodObject<{
     audio: z.ZodOptional<z.ZodObject<{
         mode: z.ZodOptional<z.ZodEnum<{
             default: "default";
-            none: "none";
             device: "device";
+            none: "none";
         }>>;
         device: z.ZodOptional<z.ZodString>;
         codec: z.ZodOptional<z.ZodString>;
@@ -166,13 +178,13 @@ export declare const cerastreamConfigSchema: z.ZodObject<{
     }>>;
     input_mode: z.ZodOptional<z.ZodEnum<{
         audio: "audio";
+        camlink: "camlink";
         hdmi: "hdmi";
-        uvc_h264: "uvc_h264";
-        uvc_h265: "uvc_h265";
         mjpeg: "mjpeg";
-        camlink: "camlink";
-        test: "test";
         network: "network";
+        test: "test";
+        uvc_h264: "uvc_h264";
+        uvc_h265: "uvc_h265";
     }>>;
 }, z.core.$strip>;
 export type CerastreamConfig = z.infer<typeof cerastreamConfigSchema>;
@@ -194,13 +206,13 @@ export declare const captureModeSchema: z.ZodObject<{
     media_type: z.ZodString;
     pipeline_kind: z.ZodEnum<{
         audio: "audio";
+        camlink: "camlink";
         hdmi: "hdmi";
-        uvc_h264: "uvc_h264";
-        uvc_h265: "uvc_h265";
         mjpeg: "mjpeg";
-        camlink: "camlink";
-        test: "test";
         network: "network";
+        test: "test";
+        uvc_h264: "uvc_h264";
+        uvc_h265: "uvc_h265";
     }>;
     caps: z.ZodArray<z.ZodObject<{
         width: z.ZodOptional<z.ZodNumber>;
@@ -215,8 +227,8 @@ export declare const captureDeviceSchema: z.ZodObject<{
     device_path: z.ZodString;
     display_name: z.ZodString;
     media_class: z.ZodEnum<{
-        video: "video";
         audio: "audio";
+        video: "video";
     }>;
     caps: z.ZodOptional<z.ZodArray<z.ZodObject<{
         width: z.ZodOptional<z.ZodNumber>;
@@ -226,25 +238,25 @@ export declare const captureDeviceSchema: z.ZodObject<{
     }, z.core.$strip>>>;
     kind: z.ZodOptional<z.ZodEnum<{
         audio: "audio";
+        camlink: "camlink";
         hdmi: "hdmi";
-        uvc_h264: "uvc_h264";
-        uvc_h265: "uvc_h265";
         mjpeg: "mjpeg";
-        camlink: "camlink";
-        test: "test";
         network: "network";
+        test: "test";
+        uvc_h264: "uvc_h264";
+        uvc_h265: "uvc_h265";
     }>>;
     modes: z.ZodOptional<z.ZodArray<z.ZodObject<{
         media_type: z.ZodString;
         pipeline_kind: z.ZodEnum<{
             audio: "audio";
+            camlink: "camlink";
             hdmi: "hdmi";
-            uvc_h264: "uvc_h264";
-            uvc_h265: "uvc_h265";
             mjpeg: "mjpeg";
-            camlink: "camlink";
-            test: "test";
             network: "network";
+            test: "test";
+            uvc_h264: "uvc_h264";
+            uvc_h265: "uvc_h265";
         }>;
         caps: z.ZodArray<z.ZodObject<{
             width: z.ZodOptional<z.ZodNumber>;
@@ -256,10 +268,10 @@ export declare const captureDeviceSchema: z.ZodObject<{
     alsa_card_id: z.ZodOptional<z.ZodString>;
     product_name: z.ZodOptional<z.ZodString>;
     transport: z.ZodOptional<z.ZodEnum<{
-        hdmi: "hdmi";
-        usb: "usb";
         bluetooth: "bluetooth";
+        hdmi: "hdmi";
         onboard: "onboard";
+        usb: "usb";
     }>>;
     stable_id: z.ZodOptional<z.ZodString>;
     physical_group_id: z.ZodOptional<z.ZodString>;

package/dist/types.js

@@ -1,57 +1,63 @@
-import { z } from "zod";
-import { DEFAULT_BALANCER, DEFAULT_MAX_BITRATE, DEFAULT_MIN_BITRATE, DEFAULT_SRT_LATENCY, } from "./constants.js";
+import { z } from 'zod';
+import { DEFAULT_BALANCER, DEFAULT_MAX_BITRATE, DEFAULT_MIN_BITRATE, DEFAULT_SRT_LATENCY, } from './constants.js';
 // Shared domain enums + the unified engine config. Field names are domain-level
 // (snake_case, matching the ceracoder config convention) — never engine
 // internals (schema.md "Conventions").
-export const streamStateSchema = z.enum([
-    "idle",
-    "starting",
-    "streaming",
-    "stopping",
-]);
-export const inputModeSchema = z.enum(["manual", "auto"]);
+export const streamStateSchema = z.enum(['idle', 'starting', 'streaming', 'stopping']);
+export const inputModeSchema = z.enum(['manual', 'auto']);
 // re-used from ceracoder (schema.md §"v1 messages" shared fragments)
-export const balancerAlgorithmSchema = z.enum(["adaptive", "fixed", "aimd"]);
-export const mediaClassSchema = z.enum(["video", "audio"]);
-export const previewTierSchema = z.enum(["webcodecs", "webrtc"]);
+export const balancerAlgorithmSchema = z.enum(['adaptive', 'fixed', 'aimd']);
+export const mediaClassSchema = z.enum(['video', 'audio']);
+export const previewTierSchema = z.enum(['webcodecs', 'webrtc']);
+// Which encoder the LIVE preview branch uses. Set through `reload-config`
+// (additive) and reported back as the ACTIVE mode on stream status. Applies to
+// the NEXT stream session: the preview encoder is fixed when a session graph is
+// built, so this never swaps an encoder mid-stream.
+export const previewEncodeModeSchema = z.enum(['software', 'hardware']);
+// Why a `hardware` preview request is encoding in software anyway — a tagged
+// union so a consumer branches on `code` and still receives the detail a code
+// carries. `property-failure` names the property the element refused, which is
+// the difference between "hardware preview is broken" and "this image's encoder
+// plugin does not take `rc-mode`". ABSENT is the normal case (software was
+// chosen, hardware was delivered, or the board never offered the toggle) — there
+// is deliberately no `{code:"none"}` sentinel.
+export const previewEncodeFallbackSchema = z.discriminatedUnion('code', [
+    z.object({ code: z.literal('factory-missing') }),
+    z.object({ code: z.literal('property-failure'), property: z.string() }),
+]);
 // 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"]);
+export const videoCodecSchema = z.enum(['h264', 'h265']);
 // Same-codec passthrough policy (0.5.0, additive). Absent ⇒ "auto". "auto" =
 // passthrough only when adaptive bitrate is inactive and eligibility holds;
 // "force" = passthrough whenever eligible (typed start failure otherwise);
 // "off" = always transcode. See schema.md and the engine's layer-C matrix.
-export const videoPassthroughSchema = z.enum(["auto", "force", "off"]);
+export const videoPassthroughSchema = z.enum(['auto', 'force', 'off']);
 // Which surface owns the running bitrate, reported additively on a set-bitrate /
 // reload-config response (0.5.0). "encoder" = applied; "source-fixed" = a
 // passthrough graph fixes the bitrate at the source, so the request was NOT
 // applied (paired with reason "passthrough").
-export const bitrateControlSchema = z.enum(["encoder", "source-fixed"]);
+export const bitrateControlSchema = z.enum(['encoder', 'source-fixed']);
 // 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",
+    'hdmi',
+    'uvc_h264',
+    'uvc_h265',
+    'mjpeg',
+    'camlink',
+    'audio',
+    'test',
+    'network',
 ]);
 // How a capture device is physically attached (Todo 20, additive). The transport
 // tag CeraUI renders beside the product name (e.g. "RØDE NT-USB · USB"). Distinct
 // from captureDeviceKind: an HDMI-to-USB dongle is kind:uvc_h264 but transport:usb,
 // while the SoC's dedicated HDMI-RX port is transport:hdmi. Absent on a legacy
 // producer or when no hint identifies a transport.
-export const deviceTransportSchema = z.enum([
-    "usb",
-    "hdmi",
-    "bluetooth",
-    "onboard",
-]);
+export const deviceTransportSchema = z.enum(['usb', 'hdmi', 'bluetooth', 'onboard']);
 // Phase of one `change-config` transaction (0.10.0, additive). `applying` is
 // published once at entry, then exactly ONE terminal phase for the same
 // attempt_id: `applied` (the new config satisfied the outcome gate),
@@ -59,10 +65,10 @@ export const deviceTransportSchema = z.enum([
 // `rollback_failed` (no rollback was possible, or the one attempt also failed —
 // the engine is idle, which is the truthful terminal state).
 export const configChangePhaseSchema = z.enum([
-    "applying",
-    "applied",
-    "reverted",
-    "rollback_failed",
+    'applying',
+    'applied',
+    'reverted',
+    'rollback_failed',
 ]);
 // ---- config sub-schemas (canonical; reused by `start` + the unified config) ----
 /** SRT transport config. Mirrors schema.md `start.srt` exactly. */
@@ -90,8 +96,8 @@ export const bitrateConfigSchema = z
 })
     // 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"],
+    message: 'min_bitrate must not exceed max_bitrate',
+    path: ['min_bitrate'],
 });
 /**
  * Audio config section of the unified engine config (0.4.0, additive). Every
@@ -106,7 +112,7 @@ export const bitrateConfigSchema = z
 // leg (requires `device`). Absent ⇒ legacy inference from `device`/source kind,
 // so a pre-0.6.0 caller keeps working. Replaces leaking pseudo-source strings
 // (e.g. "No audio") into `device`.
-export const audioModeSchema = z.enum(["none", "default", "device"]);
+export const audioModeSchema = z.enum(['none', 'default', 'device']);
 export const audioConfigSchema = z.object({
     mode: audioModeSchema.optional(),
     device: z.string().optional(), // ALSA capture device id; absent ⇒ test-tone fallback