@ceralive/cerastream 2026.6.0-rc.1

package/dist/messages.d.ts

@@ -0,0 +1,394 @@
+import { z } from "zod";
+export declare const startParamsSchema: z.ZodObject<{
+    pipeline: z.ZodString;
+    srt: z.ZodObject<{
+        host: z.ZodString;
+        port: z.ZodNumber;
+        streamid: z.ZodOptional<z.ZodString>;
+        latency_ms: z.ZodNumber;
+        reduced_packet_size: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>;
+    bitrate: z.ZodObject<{
+        min_bitrate: z.ZodNumber;
+        max_bitrate: z.ZodNumber;
+        balancer: z.ZodDefault<z.ZodEnum<{
+            adaptive: "adaptive";
+            fixed: "fixed";
+            aimd: "aimd";
+        }>>;
+    }, z.core.$strip>;
+    input_id: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type StartParams = z.infer<typeof startParamsSchema>;
+export declare const startResultSchema: z.ZodObject<{
+    session_id: z.ZodString;
+    state: z.ZodEnum<{
+        idle: "idle";
+        starting: "starting";
+        streaming: "streaming";
+        stopping: "stopping";
+    }>;
+}, z.core.$strip>;
+export type StartResult = z.infer<typeof startResultSchema>;
+export declare const stopParamsSchema: z.ZodOptional<z.ZodObject<{
+    reason: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>>;
+export type StopParams = z.infer<typeof stopParamsSchema>;
+export declare const stopResultSchema: z.ZodObject<{
+    state: z.ZodEnum<{
+        idle: "idle";
+        starting: "starting";
+        streaming: "streaming";
+        stopping: "stopping";
+    }>;
+}, z.core.$strip>;
+export type StopResult = z.infer<typeof stopResultSchema>;
+export declare const reloadConfigParamsSchema: z.ZodObject<{
+    bitrate: z.ZodOptional<z.ZodObject<{
+        min_bitrate: z.ZodOptional<z.ZodNumber>;
+        max_bitrate: z.ZodOptional<z.ZodNumber>;
+        balancer: z.ZodOptional<z.ZodEnum<{
+            adaptive: "adaptive";
+            fixed: "fixed";
+            aimd: "aimd";
+        }>>;
+    }, z.core.$strip>>;
+    srt: z.ZodOptional<z.ZodObject<{
+        latency_ms: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type ReloadConfigParams = z.infer<typeof reloadConfigParamsSchema>;
+export declare const reloadConfigResultSchema: z.ZodObject<{
+    applied: z.ZodObject<{
+        bitrate: z.ZodOptional<z.ZodObject<{
+            min_bitrate: z.ZodOptional<z.ZodNumber>;
+            max_bitrate: z.ZodOptional<z.ZodNumber>;
+            balancer: z.ZodOptional<z.ZodEnum<{
+                adaptive: "adaptive";
+                fixed: "fixed";
+                aimd: "aimd";
+            }>>;
+        }, z.core.$strip>>;
+        srt: z.ZodOptional<z.ZodObject<{
+            latency_ms: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type ReloadConfigResult = z.infer<typeof reloadConfigResultSchema>;
+export declare const setBitrateParamsSchema: z.ZodObject<{
+    max_bitrate: z.ZodNumber;
+}, z.core.$strip>;
+export type SetBitrateParams = z.infer<typeof setBitrateParamsSchema>;
+export declare const setBitrateResultSchema: z.ZodObject<{
+    applied: z.ZodObject<{
+        max_bitrate: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type SetBitrateResult = z.infer<typeof setBitrateResultSchema>;
+export declare const switchInputParamsSchema: z.ZodObject<{
+    input_id: z.ZodString;
+    mode: z.ZodDefault<z.ZodEnum<{
+        manual: "manual";
+        auto: "auto";
+    }>>;
+}, z.core.$strip>;
+export type SwitchInputParams = z.infer<typeof switchInputParamsSchema>;
+export declare const switchInputResultSchema: z.ZodObject<{
+    active_input: z.ZodString;
+    mode: z.ZodEnum<{
+        manual: "manual";
+        auto: "auto";
+    }>;
+}, z.core.$strip>;
+export type SwitchInputResult = z.infer<typeof switchInputResultSchema>;
+export declare const listDevicesParamsSchema: z.ZodOptional<z.ZodObject<{
+    media_class: z.ZodOptional<z.ZodEnum<{
+        video: "video";
+        audio: "audio";
+    }>>;
+}, z.core.$strip>>;
+export type ListDevicesParams = z.infer<typeof listDevicesParamsSchema>;
+export declare const listDevicesResultSchema: z.ZodObject<{
+    devices: z.ZodArray<z.ZodObject<{
+        input_id: z.ZodString;
+        device_path: z.ZodString;
+        display_name: z.ZodString;
+        media_class: z.ZodEnum<{
+            video: "video";
+            audio: "audio";
+        }>;
+        caps: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            width: z.ZodOptional<z.ZodNumber>;
+            height: z.ZodOptional<z.ZodNumber>;
+            framerate: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type ListDevicesResult = z.infer<typeof listDevicesResultSchema>;
+export declare const eventTopicSchema: z.ZodEnum<{
+    error: "error";
+    bitrate: "bitrate";
+    status: "status";
+    switch: "switch";
+    device: "device";
+    "srt-stats": "srt-stats";
+    preview: "preview";
+}>;
+export type EventTopic = z.infer<typeof eventTopicSchema>;
+export declare const subscribeEventsParamsSchema: z.ZodObject<{
+    topics: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        error: "error";
+        bitrate: "bitrate";
+        status: "status";
+        switch: "switch";
+        device: "device";
+        "srt-stats": "srt-stats";
+        preview: "preview";
+    }>>>;
+}, z.core.$strip>;
+export type SubscribeEventsParams = z.infer<typeof subscribeEventsParamsSchema>;
+export declare const subscribeEventsResultSchema: z.ZodObject<{
+    subscribed: z.ZodArray<z.ZodEnum<{
+        error: "error";
+        bitrate: "bitrate";
+        status: "status";
+        switch: "switch";
+        device: "device";
+        "srt-stats": "srt-stats";
+        preview: "preview";
+    }>>;
+}, z.core.$strip>;
+export type SubscribeEventsResult = z.infer<typeof subscribeEventsResultSchema>;
+export declare const previewSessionParamsSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    action: z.ZodLiteral<"start">;
+    tier: z.ZodEnum<{
+        webcodecs: "webcodecs";
+        webrtc: "webrtc";
+    }>;
+}, z.core.$strip>, z.ZodObject<{
+    action: z.ZodLiteral<"stop">;
+    session_id: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    action: z.ZodLiteral<"signal">;
+    session_id: z.ZodString;
+    sdp: z.ZodOptional<z.ZodString>;
+    ice: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$strip>], "action">;
+export type PreviewSessionParams = z.infer<typeof previewSessionParamsSchema>;
+export declare const previewSessionResultSchema: z.ZodObject<{
+    session_id: z.ZodString;
+    tier: z.ZodEnum<{
+        webcodecs: "webcodecs";
+        webrtc: "webrtc";
+    }>;
+    transport: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"uds-binary">;
+        socket: z.ZodLiteral<"/run/cerastream/preview.sock">;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"webrtc">;
+        sdp: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>], "kind">;
+}, z.core.$strip>;
+export type PreviewSessionResult = z.infer<typeof previewSessionResultSchema>;
+/** The eight v1 control methods (the literal JSON-RPC `method` strings). */
+export declare const V1_METHODS: readonly ["start", "stop", "reload-config", "set-bitrate", "switch-input", "list-devices", "subscribe-events", "preview-session"];
+export type V1Method = (typeof V1_METHODS)[number];
+/**
+ * method → { params, result } Zod schema pair. `hello` is the handshake; the
+ * eight in {@link V1_METHODS} are the v1 control surface. Tests assert every
+ * ADR-0002 message is represented here.
+ */
+export declare const requestSchemas: {
+    readonly hello: {
+        readonly params: z.ZodObject<{
+            protocol: z.ZodLiteral<"cerastream-ipc/1">;
+            client: z.ZodString;
+        }, z.core.$strip>;
+        readonly result: z.ZodObject<{
+            protocol: z.ZodLiteral<"cerastream-ipc/1">;
+            schema_version: z.ZodString;
+            engine_version: z.ZodString;
+        }, z.core.$strip>;
+    };
+    readonly start: {
+        readonly params: z.ZodObject<{
+            pipeline: z.ZodString;
+            srt: z.ZodObject<{
+                host: z.ZodString;
+                port: z.ZodNumber;
+                streamid: z.ZodOptional<z.ZodString>;
+                latency_ms: z.ZodNumber;
+                reduced_packet_size: z.ZodOptional<z.ZodBoolean>;
+            }, z.core.$strip>;
+            bitrate: z.ZodObject<{
+                min_bitrate: z.ZodNumber;
+                max_bitrate: z.ZodNumber;
+                balancer: z.ZodDefault<z.ZodEnum<{
+                    adaptive: "adaptive";
+                    fixed: "fixed";
+                    aimd: "aimd";
+                }>>;
+            }, z.core.$strip>;
+            input_id: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>;
+        readonly result: z.ZodObject<{
+            session_id: z.ZodString;
+            state: z.ZodEnum<{
+                idle: "idle";
+                starting: "starting";
+                streaming: "streaming";
+                stopping: "stopping";
+            }>;
+        }, z.core.$strip>;
+    };
+    readonly stop: {
+        readonly params: z.ZodOptional<z.ZodObject<{
+            reason: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        readonly result: z.ZodObject<{
+            state: z.ZodEnum<{
+                idle: "idle";
+                starting: "starting";
+                streaming: "streaming";
+                stopping: "stopping";
+            }>;
+        }, z.core.$strip>;
+    };
+    readonly "reload-config": {
+        readonly params: z.ZodObject<{
+            bitrate: z.ZodOptional<z.ZodObject<{
+                min_bitrate: z.ZodOptional<z.ZodNumber>;
+                max_bitrate: z.ZodOptional<z.ZodNumber>;
+                balancer: z.ZodOptional<z.ZodEnum<{
+                    adaptive: "adaptive";
+                    fixed: "fixed";
+                    aimd: "aimd";
+                }>>;
+            }, z.core.$strip>>;
+            srt: z.ZodOptional<z.ZodObject<{
+                latency_ms: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>;
+        readonly result: z.ZodObject<{
+            applied: z.ZodObject<{
+                bitrate: z.ZodOptional<z.ZodObject<{
+                    min_bitrate: z.ZodOptional<z.ZodNumber>;
+                    max_bitrate: z.ZodOptional<z.ZodNumber>;
+                    balancer: z.ZodOptional<z.ZodEnum<{
+                        adaptive: "adaptive";
+                        fixed: "fixed";
+                        aimd: "aimd";
+                    }>>;
+                }, z.core.$strip>>;
+                srt: z.ZodOptional<z.ZodObject<{
+                    latency_ms: z.ZodOptional<z.ZodNumber>;
+                }, z.core.$strip>>;
+            }, z.core.$strip>;
+        }, z.core.$strip>;
+    };
+    readonly "set-bitrate": {
+        readonly params: z.ZodObject<{
+            max_bitrate: z.ZodNumber;
+        }, z.core.$strip>;
+        readonly result: z.ZodObject<{
+            applied: z.ZodObject<{
+                max_bitrate: z.ZodNumber;
+            }, z.core.$strip>;
+        }, z.core.$strip>;
+    };
+    readonly "switch-input": {
+        readonly params: z.ZodObject<{
+            input_id: z.ZodString;
+            mode: z.ZodDefault<z.ZodEnum<{
+                manual: "manual";
+                auto: "auto";
+            }>>;
+        }, z.core.$strip>;
+        readonly result: z.ZodObject<{
+            active_input: z.ZodString;
+            mode: z.ZodEnum<{
+                manual: "manual";
+                auto: "auto";
+            }>;
+        }, z.core.$strip>;
+    };
+    readonly "list-devices": {
+        readonly params: z.ZodOptional<z.ZodObject<{
+            media_class: z.ZodOptional<z.ZodEnum<{
+                video: "video";
+                audio: "audio";
+            }>>;
+        }, z.core.$strip>>;
+        readonly result: z.ZodObject<{
+            devices: z.ZodArray<z.ZodObject<{
+                input_id: z.ZodString;
+                device_path: z.ZodString;
+                display_name: z.ZodString;
+                media_class: z.ZodEnum<{
+                    video: "video";
+                    audio: "audio";
+                }>;
+                caps: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                    width: z.ZodOptional<z.ZodNumber>;
+                    height: z.ZodOptional<z.ZodNumber>;
+                    framerate: z.ZodOptional<z.ZodString>;
+                }, z.core.$strip>>>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>;
+    };
+    readonly "subscribe-events": {
+        readonly params: z.ZodObject<{
+            topics: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+                error: "error";
+                bitrate: "bitrate";
+                status: "status";
+                switch: "switch";
+                device: "device";
+                "srt-stats": "srt-stats";
+                preview: "preview";
+            }>>>;
+        }, z.core.$strip>;
+        readonly result: z.ZodObject<{
+            subscribed: z.ZodArray<z.ZodEnum<{
+                error: "error";
+                bitrate: "bitrate";
+                status: "status";
+                switch: "switch";
+                device: "device";
+                "srt-stats": "srt-stats";
+                preview: "preview";
+            }>>;
+        }, z.core.$strip>;
+    };
+    readonly "preview-session": {
+        readonly params: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            action: z.ZodLiteral<"start">;
+            tier: z.ZodEnum<{
+                webcodecs: "webcodecs";
+                webrtc: "webrtc";
+            }>;
+        }, z.core.$strip>, z.ZodObject<{
+            action: z.ZodLiteral<"stop">;
+            session_id: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            action: z.ZodLiteral<"signal">;
+            session_id: z.ZodString;
+            sdp: z.ZodOptional<z.ZodString>;
+            ice: z.ZodOptional<z.ZodUnknown>;
+        }, z.core.$strip>], "action">;
+        readonly result: z.ZodObject<{
+            session_id: z.ZodString;
+            tier: z.ZodEnum<{
+                webcodecs: "webcodecs";
+                webrtc: "webrtc";
+            }>;
+            transport: z.ZodDiscriminatedUnion<[z.ZodObject<{
+                kind: z.ZodLiteral<"uds-binary">;
+                socket: z.ZodLiteral<"/run/cerastream/preview.sock">;
+            }, z.core.$strip>, z.ZodObject<{
+                kind: z.ZodLiteral<"webrtc">;
+                sdp: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>], "kind">;
+        }, z.core.$strip>;
+    };
+};

package/dist/messages.js

@@ -0,0 +1,152 @@
+import { z } from "zod";
+import { helloParamsSchema, helloResultSchema, } from "./envelope.js";
+import { balancerAlgorithmSchema, captureDeviceSchema, cerastreamConfigSchema, inputModeSchema, mediaClassSchema, previewTierSchema, streamStateSchema, } 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 ----
+// `start` params ARE the unified engine config, so the wire shape and the
+// persisted profile can never drift (see types.cerastreamConfigSchema).
+export const startParamsSchema = cerastreamConfigSchema;
+export const startResultSchema = z.object({
+    session_id: z.string(),
+    state: streamStateSchema, // "starting" | "streaming"
+});
+// ---- 2. stop ----
+export const stopParamsSchema = z
+    .object({
+    reason: z.string().optional(),
+})
+    .optional();
+export const stopResultSchema = z.object({
+    state: streamStateSchema, // "idle"
+});
+// ---- 3. reload-config (replaces SIGHUP) ----
+export const reloadConfigParamsSchema = z.object({
+    bitrate: z
+        .object({
+        min_bitrate: z.number().int().min(1).optional(),
+        max_bitrate: z.number().int().min(1).optional(),
+        balancer: balancerAlgorithmSchema.optional(),
+    })
+        .optional(),
+    srt: z
+        .object({
+        latency_ms: z.number().int().min(100).max(10_000).optional(),
+    })
+        .optional(),
+});
+export const reloadConfigResultSchema = z.object({
+    applied: reloadConfigParamsSchema, // post-clamp values actually applied
+});
+// ---- 4. set-bitrate ----
+export const setBitrateParamsSchema = z.object({
+    max_bitrate: z.number().int().min(1), // kbps
+});
+export const setBitrateResultSchema = z.object({
+    applied: z.object({ max_bitrate: z.number().int() }),
+});
+// ---- 5. switch-input ----
+export const switchInputParamsSchema = z.object({
+    input_id: z.string(), // device/input identifier from list-devices
+    mode: inputModeSchema.default("manual"),
+});
+export const switchInputResultSchema = z.object({
+    active_input: z.string(),
+    mode: inputModeSchema,
+});
+// ---- 6. list-devices ----
+export const listDevicesParamsSchema = z
+    .object({
+    media_class: mediaClassSchema.optional(),
+})
+    .optional();
+export const listDevicesResultSchema = z.object({
+    devices: z.array(captureDeviceSchema),
+});
+// ---- 7. subscribe-events ----
+export const eventTopicSchema = z.enum([
+    "status",
+    "switch",
+    "device",
+    "bitrate",
+    "srt-stats",
+    "error",
+    "preview",
+]);
+export const subscribeEventsParamsSchema = z.object({
+    topics: z.array(eventTopicSchema).optional(), // default: all topics
+});
+export const subscribeEventsResultSchema = z.object({
+    subscribed: z.array(eventTopicSchema),
+});
+// ---- 8. preview-session ----
+export const previewSessionParamsSchema = z.discriminatedUnion("action", [
+    z.object({
+        action: z.literal("start"),
+        tier: previewTierSchema,
+    }),
+    z.object({ action: z.literal("stop"), session_id: z.string() }),
+    z.object({
+        action: z.literal("signal"), // webrtc only
+        session_id: z.string(),
+        sdp: z.string().optional(),
+        ice: z.unknown().optional(),
+    }),
+]);
+export const previewSessionResultSchema = z.object({
+    session_id: z.string(),
+    tier: previewTierSchema,
+    transport: z.discriminatedUnion("kind", [
+        z.object({
+            kind: z.literal("uds-binary"),
+            socket: z.literal("/run/cerastream/preview.sock"),
+        }),
+        z.object({ kind: z.literal("webrtc"), sdp: z.string().optional() }),
+    ]),
+});
+// ---- 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",
+];
+/**
+ * method → { params, result } Zod schema pair. `hello` is the handshake; the
+ * eight in {@link V1_METHODS} are the v1 control surface. Tests assert every
+ * ADR-0002 message is represented here.
+ */
+export const requestSchemas = {
+    hello: { params: helloParamsSchema, result: helloResultSchema },
+    start: { params: startParamsSchema, result: startResultSchema },
+    stop: { params: stopParamsSchema, result: stopResultSchema },
+    "reload-config": {
+        params: reloadConfigParamsSchema,
+        result: reloadConfigResultSchema,
+    },
+    "set-bitrate": {
+        params: setBitrateParamsSchema,
+        result: setBitrateResultSchema,
+    },
+    "switch-input": {
+        params: switchInputParamsSchema,
+        result: switchInputResultSchema,
+    },
+    "list-devices": {
+        params: listDevicesParamsSchema,
+        result: listDevicesResultSchema,
+    },
+    "subscribe-events": {
+        params: subscribeEventsParamsSchema,
+        result: subscribeEventsResultSchema,
+    },
+    "preview-session": {
+        params: previewSessionParamsSchema,
+        result: previewSessionResultSchema,
+    },
+};

package/dist/paths.d.ts

@@ -0,0 +1,14 @@
+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. */
+export declare function controlSocketPath(dir?: string): string;
+/** Resolve the binary preview socket path within the (possibly overridden) IPC dir. */
+export declare function previewSocketPath(dir?: string): string;
+/**
+ * Resolve the cerastream engine executable path. Resolution order: an explicit
+ * file path → a directory containing the binary → `which cerastream` →
+ * `/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 };

package/dist/paths.js

@@ -0,0 +1,72 @@
+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
+// connects to these sockets, it never spawns the engine, so getCerastreamExec
+// exists only for parity/tooling.
+/** Resolve the IPC runtime dir: explicit override → {@link IPC_DIR_ENV} → default. */
+export function resolveIpcDir(override) {
+    if (override)
+        return override;
+    const fromEnv = process.env[IPC_DIR_ENV];
+    return fromEnv && fromEnv.length > 0 ? fromEnv : DEFAULT_IPC_DIR;
+}
+/** Resolve the control-plane socket path within the (possibly overridden) IPC dir. */
+export function controlSocketPath(dir) {
+    return join(resolveIpcDir(dir), CONTROL_SOCKET_NAME);
+}
+/** Resolve the binary preview socket path within the (possibly overridden) IPC dir. */
+export function previewSocketPath(dir) {
+    return join(resolveIpcDir(dir), PREVIEW_SOCKET_NAME);
+}
+/**
+ * Resolve the cerastream engine executable path. Resolution order: an explicit
+ * file path → a directory containing the binary → `which cerastream` →
+ * `/usr/bin/cerastream` → the bare name (let PATH decide).
+ */
+export function getCerastreamExec(execPath) {
+    if (execPath) {
+        if (isFile(execPath))
+            return execPath;
+        const inDir = join(execPath, CERASTREAM_BIN);
+        if (isFile(inDir))
+            return inDir;
+        return execPath.endsWith(CERASTREAM_BIN)
+            ? execPath
+            : join(execPath, CERASTREAM_BIN);
+    }
+    const onPath = findInPath(CERASTREAM_BIN);
+    if (onPath)
+        return onPath;
+    const systemPath = `/usr/bin/${CERASTREAM_BIN}`;
+    if (existsSync(systemPath))
+        return systemPath;
+    return CERASTREAM_BIN;
+}
+function isFile(p) {
+    try {
+        return statSync(p).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+function findInPath(name) {
+    try {
+        const out = execSync(`command -v ${name}`, {
+            encoding: "utf-8",
+            stdio: ["pipe", "pipe", "pipe"],
+        }).trim();
+        const first = out.split("\n")[0]?.trim();
+        if (first && existsSync(first))
+            return first;
+    }
+    catch {
+        // not found on PATH
+    }
+    return undefined;
+}
+export { DEFAULT_IPC_DIR, CONTROL_SOCKET_NAME, PREVIEW_SOCKET_NAME };

package/dist/transport.d.ts

@@ -0,0 +1,30 @@
+/** Lifecycle + data callbacks the client installs on a {@link LineSocket}. */
+export interface LineSocketHandlers {
+    /** One decoded NDJSON line (newline stripped). */
+    onLine(line: string): void;
+    /** The socket closed. `err` is set for an error/framing close, absent for EOF. */
+    onClose(err?: Error): void;
+}
+/**
+ * A single Unix-socket connection that frames bytes into NDJSON lines. Construct,
+ * `open()` (rejects if the socket can't be reached), `send()` lines, `close()`
+ * when done. Not reusable across reconnects — the client makes a new one.
+ */
+export declare class LineSocket {
+    private readonly socketPath;
+    private socket;
+    private buffer;
+    private bufferedBytes;
+    private handlers;
+    private closed;
+    constructor(socketPath: string);
+    /** Connect to the socket and start framing. Rejects on a connect failure. */
+    open(handlers: LineSocketHandlers): Promise<void>;
+    /** Write one NDJSON line (the trailing newline is added here). */
+    send(line: string): void;
+    /** Close the connection. Idempotent; does not fire {@link LineSocketHandlers.onClose}. */
+    close(): void;
+    private onData;
+    private fail;
+    private fireClose;
+}