@ceralive/cerastream 2026.7.5 → 2026.8.0

package/dist/events.js

@@ -1,6 +1,6 @@
-import { z } from "zod";
-import { processErrorCodeSchema, processErrorSourceSchema, } from "./errors.js";
-import { captureDeviceSchema, configChangePhaseSchema, inputModeSchema, mediaClassSchema, streamStateSchema, } from "./types.js";
+import { z } from 'zod';
+import { processErrorCodeSchema, processErrorSourceSchema } from './errors.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:
 // { type, seq, … }. `type` discriminates; `seq` is a per-type monotonic counter.
@@ -25,6 +25,28 @@ export const activeEncodeSchema = z.object({
     frames_emitted: z.number().int().nonnegative().optional(), // 0.7.0: monotonic egress-buffer counter; advances across status heartbeats while frames flow
     pipeline_playing: z.boolean().optional(), // 0.7.0: pipeline is in GStreamer PLAYING (false during an in-process reconnect)
 });
+/**
+ * What this session's PREVIEW branch is actually encoding with (additive),
+ * reported on the `status` event as `preview_encoder_realized`. A separate
+ * realized fact from {@link activeEncodeSchema}, which describes the EGRESS
+ * encode — the two are different graph branches and are independently absent.
+ *
+ * Present only while a session has a preview branch spliced into its graph (the
+ * branch exists for the life of the session even while its valve is closed).
+ * ABSENT means "no preview branch, or a legacy emitter" — which is NOT
+ * `mode: "software"` (a branch exists and encodes in software) and NOT
+ * `preview.preview_hw_capability === false` (the board publishes no preview
+ * encoder at all). Those three states must never be defaulted into each other.
+ *
+ * `mode` is the ACTIVE mode. The REQUESTED mode is deliberately not an engine
+ * fact: it lives in CeraUI's persisted config.
+ */
+export const previewEncoderRealizedSchema = z.object({
+    selected_element: z.string().optional(), // the element the platform's HAL descriptor publishes; absent ⇒ this board publishes none
+    realized_element: z.string(), // the element actually built into the preview branch, e.g. "x264enc"/"mpph264enc"
+    mode: previewEncodeModeSchema, // the encoder family actually realized — never the request
+    fallback_reason: previewEncodeFallbackSchema.optional(), // why a hardware request is in software; absent is the normal case
+});
 /**
  * `status` event — stream state change + heartbeat. The trailing fields are
  * additive: the `buffering*` / `spooled_bytes` / `data_headroom_bytes` /
@@ -33,10 +55,12 @@ export const activeEncodeSchema = z.object({
  * `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.
+ * legacy emitter or a bare state-only heartbeat; `preview_encoder_realized`
+ * reports the PREVIEW branch's own encoder and is absent when the session has no
+ * preview branch.
  */
 export const statusEventSchema = z.object({
-    type: z.literal("status"),
+    type: z.literal('status'),
     seq,
     state: streamStateSchema,
     streaming: z.boolean(),
@@ -47,6 +71,7 @@ export const statusEventSchema = z.object({
     data_headroom_bytes: z.number().int().nonnegative().optional(),
     disk_warning: z.boolean().optional(),
     active_encode: activeEncodeSchema.optional(),
+    preview_encoder_realized: previewEncoderRealizedSchema.optional(),
 });
 /**
  * `switch` event — active input changed (manual or failover). `media_class` is
@@ -54,7 +79,7 @@ export const statusEventSchema = z.object({
  * `"audio"`.
  */
 export const switchEventSchema = z.object({
-    type: z.literal("switch"),
+    type: z.literal('switch'),
     seq,
     active_input: z.string(),
     mode: inputModeSchema,
@@ -63,21 +88,21 @@ export const switchEventSchema = z.object({
 });
 /** `device` event — a GstDeviceMonitor hotplug add/remove. */
 export const deviceEventSchema = z.object({
-    type: z.literal("device"),
+    type: z.literal('device'),
     seq,
-    change: z.enum(["added", "removed"]),
+    change: z.enum(['added', 'removed']),
     device: captureDeviceSchema,
 });
 /** `bitrate` event — the adaptive controller adjusted the encode bitrate. */
 export const bitrateEventSchema = z.object({
-    type: z.literal("bitrate"),
+    type: z.literal('bitrate'),
     seq,
     current_bitrate: z.number().int(),
     max_bitrate: z.number().int(),
 });
 /** `srt-stats` event — periodic SRT transport telemetry. */
 export const srtStatsEventSchema = z.object({
-    type: z.literal("srt-stats"),
+    type: z.literal('srt-stats'),
     seq,
     rtt_ms: z.number(),
     send_buffer: z.number().int(),
@@ -88,7 +113,7 @@ export const srtStatsEventSchema = z.object({
  * code; the engine reports facts and CeraUI decides what to surface.
  */
 export const runtimeErrorEventSchema = z.object({
-    type: z.literal("error"),
+    type: z.literal('error'),
     seq,
     code: processErrorCodeSchema, // Tier 2 (errors.ts)
     source: processErrorSourceSchema,
@@ -97,7 +122,7 @@ export const runtimeErrorEventSchema = z.object({
 });
 /** `preview` event — a preview-session lifecycle/phase change. */
 export const previewEventSchema = z.object({
-    type: z.literal("preview"),
+    type: z.literal('preview'),
     seq,
     session_id: z.string(),
     phase: z.string(),
@@ -113,12 +138,12 @@ export const previewEventSchema = z.object({
  * Independent of the preview-scoped `audio-level` WebSocket frame.
  */
 export const audioLevelEventSchema = z.object({
-    type: z.literal("audio-level"),
+    type: z.literal('audio-level'),
     seq,
     source: z
         .object({
         identity: z.string().optional(), // reboot-stable device id (Todo 20 stable_id)
-        owner: z.enum(["sidecar", "streaming"]),
+        owner: z.enum(['sidecar', 'streaming']),
     })
         .optional(),
     channels: z.number().int().nonnegative().optional(),
@@ -126,7 +151,7 @@ export const audioLevelEventSchema = z.object({
     peak_db: z.array(z.number()).optional(),
     floor_db: z.number().optional(),
     unavailable: z.literal(true).optional(),
-    reason: z.enum(["device_busy", "no_device", "mode_none", "handoff"]).optional(),
+    reason: z.enum(['device_busy', 'no_device', 'mode_none', 'handoff']).optional(),
 });
 /**
  * `config-change` event — one phase of a `change-config` transaction (0.10.0,
@@ -137,14 +162,14 @@ export const audioLevelEventSchema = z.object({
  * actually advancing", never merely "PLAYING".
  */
 export const configChangeEventSchema = z.object({
-    type: z.literal("config-change"),
+    type: z.literal('config-change'),
     seq,
     attempt_id: z.string(),
     phase: configChangePhaseSchema,
     reason: z.string().optional(), // absent on applying/applied; "teardown_timeout" marks the supervisor escalation
 });
 /** Discriminated union of every v1 event payload (the inner `params`). */
-export const eventParamsSchema = z.discriminatedUnion("type", [
+export const eventParamsSchema = z.discriminatedUnion('type', [
     statusEventSchema,
     switchEventSchema,
     deviceEventSchema,
@@ -157,23 +182,23 @@ export const eventParamsSchema = z.discriminatedUnion("type", [
 ]);
 /** Full event envelope: { jsonrpc, method:"event", params } with typed params. */
 export const cerastreamEventSchema = z.object({
-    jsonrpc: z.literal("2.0"),
-    method: z.literal("event"),
+    jsonrpc: z.literal('2.0'),
+    method: z.literal('event'),
     params: eventParamsSchema,
 });
 /** The nine event topics (schema.md "Events" table) — count-assertion source.
  * `audio-level` (Todo 21) and `config-change` (Todo 9) are additive and appended
  * last, preserving the order of every prior topic. */
 export const EVENT_TOPICS = [
-    "status",
-    "switch",
-    "device",
-    "bitrate",
-    "srt-stats",
-    "error",
-    "preview",
-    "audio-level",
-    "config-change",
+    'status',
+    'switch',
+    'device',
+    'bitrate',
+    'srt-stats',
+    'error',
+    'preview',
+    'audio-level',
+    'config-change',
 ];
 /** topic → payload Zod schema. Tests assert every topic is represented here. */
 export const eventSchemas = {
@@ -181,9 +206,9 @@ export const eventSchemas = {
     switch: switchEventSchema,
     device: deviceEventSchema,
     bitrate: bitrateEventSchema,
-    "srt-stats": srtStatsEventSchema,
+    'srt-stats': srtStatsEventSchema,
     error: runtimeErrorEventSchema,
     preview: previewEventSchema,
-    "audio-level": audioLevelEventSchema,
-    "config-change": configChangeEventSchema,
+    'audio-level': audioLevelEventSchema,
+    'config-change': configChangeEventSchema,
 };

package/dist/index.d.ts

@@ -1,9 +1,9 @@
-export * from "./constants.js";
-export * from "./errors.js";
-export * from "./envelope.js";
-export * from "./types.js";
-export * from "./messages.js";
-export * from "./events.js";
-export * from "./paths.js";
-export * from "./config.js";
-export * from "./client.js";
+export * from './client.js';
+export * from './config.js';
+export * from './constants.js';
+export * from './envelope.js';
+export * from './errors.js';
+export * from './events.js';
+export * from './messages.js';
+export * from './paths.js';
+export * from './types.js';

package/dist/index.js

@@ -2,12 +2,12 @@
 // Rust streaming engine. The Zod schemas + types are the frozen public contract
 // (ADR-0002 / schema.md); the client drives that contract over a Bun-native
 // NDJSON/UDS transport (Task 31).
-export * from "./constants.js";
-export * from "./errors.js";
-export * from "./envelope.js";
-export * from "./types.js";
-export * from "./messages.js";
-export * from "./events.js";
-export * from "./paths.js";
-export * from "./config.js";
-export * from "./client.js";
+export * from './client.js';
+export * from './config.js';
+export * from './constants.js';
+export * from './envelope.js';
+export * from './errors.js';
+export * from './events.js';
+export * from './messages.js';
+export * from './paths.js';
+export * from './types.js';