@norskvideo/ctl-sdk 0.1.7 → 0.1.9

package/components/ShotBar.d.ts

@@ -0,0 +1,25 @@
+import type { DerivedShot, ResolvedShot, TakeCommand, Transition } from "@norskvideo/ctl-foundation/browser";
+import { type ReactNode } from "react";
+export interface ShotBarProps {
+    /** Shots already derived from the manifest + live room by the consumer. */
+    shots: DerivedShot[];
+    /** The shot currently on air, if known — highlights its card. */
+    pgmShotId?: string | null;
+    /** The shot currently in preview, if the product runs a preview bus. */
+    pvwShotId?: string | null;
+    /** Origin for resolving relative graphic paths. Defaults to `location.origin`. */
+    origin?: string;
+    /** Default transition applied to takes. */
+    transition?: Transition;
+    /** Show the editable graphic-URL field on graphic-bearing cards (default true). */
+    editableGraphics?: boolean;
+    /** Send the assembled commands to air. The consumer owns the WebSocket. */
+    onTake: (commands: TakeCommand[], shot: ResolvedShot) => void;
+    /** Optional preview bus — omit to hide the Preview control. */
+    onPreview?: (commands: TakeCommand[], shot: ResolvedShot) => void;
+    /** Drop-in program monitor (e.g. a WHEP player). */
+    renderProgramMonitor?: () => ReactNode;
+    /** Drop-in preview monitor. */
+    renderPreviewMonitor?: () => ReactNode;
+}
+export declare function ShotBar({ shots, pgmShotId, pvwShotId, origin, transition, editableGraphics, onTake, onPreview, renderProgramMonitor, renderPreviewMonitor, }: ShotBarProps): import("react").JSX.Element;

package/components/ShotBar.js

@@ -0,0 +1,62 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useMemo, useState } from "react";
+import { hideReasonLabel, prepareTake } from "./shot-bar-view-model.js";
+import { useUIPrimitives } from "./ui-primitives.js";
+function defaultOrigin() {
+    return typeof location !== "undefined" ? location.origin : "";
+}
+const FAMILY_BADGE = { geometry: "Geometry", graphic: "Graphic" };
+export function ShotBar({ shots, pgmShotId, pvwShotId, origin, transition, editableGraphics = true, onTake, onPreview, renderProgramMonitor, renderPreviewMonitor, }) {
+    const { Button, Input } = useUIPrimitives();
+    const resolvedOrigin = origin ?? defaultOrigin();
+    const firstReady = shots.find((s) => s.status === "ready")?.id ?? null;
+    const [selectedId, setSelectedId] = useState(firstReady);
+    const [editedUrls, setEditedUrls] = useState({});
+    const selected = shots.find((s) => s.id === selectedId && s.status === "ready");
+    const commands = useMemo(() => selected ? prepareTake(selected, { origin: resolvedOrigin, editedUrl: editedUrls[selected.id], transition }) : [], [selected, resolvedOrigin, editedUrls, transition]);
+    return (_jsxs("div", { className: "flex flex-col gap-4 text-zinc-100", children: [_jsxs("div", { className: "grid grid-cols-2 gap-3", children: [_jsx(Monitor, { label: "Preview", tone: "pvw", shot: findLabel(shots, pvwShotId), render: renderPreviewMonitor }), _jsx(Monitor, { label: "On Air", tone: "pgm", shot: findLabel(shots, pgmShotId), render: renderProgramMonitor })] }), _jsx("div", { className: "flex gap-3 overflow-x-auto pb-1", children: shots.map((shot) => (_jsx(ShotCard, { shot: shot, selected: shot.id === selectedId, onAir: shot.id === pgmShotId, config: shot.status === "ready" ? shot.config : undefined, onSelect: () => shot.status === "ready" && setSelectedId(shot.id) }, shot.id))) }), selected ? (_jsxs("div", { className: "flex flex-col gap-3 rounded-lg border border-zinc-800 bg-zinc-900/60 p-3", children: [_jsxs("div", { className: "flex items-center justify-between gap-3", children: [_jsx("div", { className: "text-sm font-medium", children: selected.label }), _jsxs("div", { className: "flex gap-2", children: [onPreview ? (_jsx(Button, { variant: "ghost", size: "sm", onClick: () => onPreview(commands, selected), children: "Preview" })) : null, _jsx(Button, { variant: "primary", size: "sm", onClick: () => onTake(commands, selected), children: "Take" })] })] }), editableGraphics && selected.graphicUrl !== undefined ? (_jsxs("div", { className: "flex flex-col gap-1 text-xs text-zinc-400", children: [_jsx("label", { htmlFor: "shotbar-graphic-url", children: "Graphic page" }), _jsx(Input, { id: "shotbar-graphic-url", type: "text", value: editedUrls[selected.id] ?? selected.graphicUrl, placeholder: selected.graphicUrl, onChange: (e) => setEditedUrls((prev) => ({ ...prev, [selected.id]: e.target.value })) })] })) : null, _jsx("pre", { className: "max-h-40 overflow-auto rounded bg-zinc-950 p-2 font-mono text-[11px] leading-relaxed text-zinc-400", children: JSON.stringify(commands, null, 2) })] })) : (_jsx("div", { className: "rounded-lg border border-dashed border-zinc-800 p-4 text-center text-sm text-zinc-500", children: "No shot selected \u2014 pick an available shot above." }))] }));
+}
+function findLabel(shots, id) {
+    if (!id)
+        return null;
+    return shots.find((s) => s.id === id)?.label ?? null;
+}
+function Monitor({ label, tone, shot, render, }) {
+    const ring = tone === "pgm" ? "border-red-600/70" : "border-emerald-600/70";
+    const chip = tone === "pgm" ? "bg-red-600 text-white" : "bg-emerald-600 text-white";
+    return (_jsxs("div", { className: `relative overflow-hidden rounded-lg border-2 ${ring} bg-black`, children: [_jsx("span", { className: `absolute left-2 top-2 z-10 rounded px-1.5 py-0.5 text-[10px] font-semibold ${chip}`, children: label }), _jsx("div", { className: "flex aspect-video items-center justify-center", children: render ? render() : _jsx("span", { className: "text-xs text-zinc-500", children: shot ?? "—" }) })] }));
+}
+function ShotCard({ shot, selected, onAir, config, onSelect, }) {
+    const hidden = shot.status === "hidden";
+    const border = onAir ? "border-red-600" : selected ? "border-sky-500" : "border-zinc-800 hover:border-zinc-600";
+    return (_jsxs("button", { type: "button", onClick: onSelect, disabled: hidden, title: hidden ? hideReasonLabel(shot.reason) : shot.label, className: `flex w-40 shrink-0 flex-col gap-2 rounded-lg border ${border} bg-zinc-900 p-2 text-left transition-colors disabled:cursor-not-allowed disabled:opacity-40`, children: [_jsx(ShotThumbnail, { preset: shot.status === "ready" ? shot.preset : "fullscreen", config: config }), _jsxs("div", { className: "flex items-center justify-between gap-1", children: [_jsx("span", { className: "truncate text-xs font-medium text-zinc-100", children: shot.label }), shot.status === "ready" ? (_jsx("span", { className: "shrink-0 rounded bg-zinc-800 px-1 text-[9px] uppercase tracking-wide text-zinc-400", children: FAMILY_BADGE[shot.family] })) : null] }), hidden ? (_jsx("span", { className: "text-[10px] leading-tight text-amber-500/80", children: hideReasonLabel(shot.reason) })) : null] }));
+}
+// A truthful 16:9 schematic of what the preset does — programme fill plus the
+// preset's overlay/box geometry, read from config where it's positional.
+function ShotThumbnail({ preset, config }) {
+    const c = (config ?? {});
+    const pct = (v, of) => `${Math.max(0, Math.min(100, (v / of) * 100))}%`;
+    const prog = _jsx("div", { className: "absolute inset-0 bg-sky-700/50" });
+    let overlay = null;
+    if (preset === "pip") {
+        overlay = (_jsx("div", { className: "absolute rounded-sm bg-amber-400/80", style: { right: "8%", bottom: "10%", width: pct(c.width ?? 384, 1920), height: pct(c.height ?? 270, 1080) } }));
+    }
+    else if (preset === "lbar") {
+        overlay = (_jsx("div", { className: "absolute rounded-sm bg-sky-700/70 ring-1 ring-sky-300/40", style: {
+                left: pct(c.videoX ?? 480, 1920),
+                top: pct(c.videoY ?? 0, 1080),
+                width: pct(c.videoWidth ?? 1440, 1920),
+                height: pct(c.videoHeight ?? 810, 1080),
+            } }));
+    }
+    else if (preset === "side-by-side") {
+        return (_jsxs("div", { className: "relative aspect-video w-full overflow-hidden rounded bg-zinc-950", children: [_jsx("div", { className: "absolute inset-y-0 left-0 w-1/2 bg-sky-700/50" }), _jsx("div", { className: "absolute inset-y-0 right-0 w-1/2 bg-emerald-700/50" })] }));
+    }
+    else if (preset === "quarters") {
+        return (_jsxs("div", { className: "relative grid aspect-video w-full grid-cols-2 grid-rows-2 gap-px overflow-hidden rounded bg-zinc-700", children: [_jsx("div", { className: "bg-sky-700/50" }), _jsx("div", { className: "bg-emerald-700/50" }), _jsx("div", { className: "bg-violet-700/50" }), _jsx("div", { className: "bg-amber-700/50" })] }));
+    }
+    else if (preset === "overlay" || preset === "lower-third") {
+        overlay = _jsx("div", { className: "absolute inset-x-[6%] bottom-[8%] h-[22%] rounded-sm bg-amber-400/80" });
+    }
+    return (_jsxs("div", { className: "relative aspect-video w-full overflow-hidden rounded bg-zinc-950", children: [prog, overlay] }));
+}

package/components/index.d.ts

@@ -1,3 +1,5 @@
 export { ProductIframe, type ProductIframeHandle, type SubmitResult } from "./ProductIframe.js";
 export { ProductTemplateBuildForm, type ProductTemplateBuildOutcome, type ProductTemplateBuildRequest, } from "./ProductTemplateBuildForm.js";
+export { ShotBar, type ShotBarProps } from "./ShotBar.js";
+export { hideReasonLabel, type PrepareTakeOptions, prepareTake, resolveGraphicUrl, } from "./shot-bar-view-model.js";
 export { type ButtonProps, type ButtonSize, type ButtonVariant, type InputProps, type LabelProps, type UIPrimitives, UIPrimitivesProvider, useUIPrimitives, } from "./ui-primitives.js";

package/components/index.js

@@ -1,3 +1,5 @@
 export { ProductIframe } from "./ProductIframe.js";
 export { ProductTemplateBuildForm, } from "./ProductTemplateBuildForm.js";
+export { ShotBar } from "./ShotBar.js";
+export { hideReasonLabel, prepareTake, resolveGraphicUrl, } from "./shot-bar-view-model.js";
 export { UIPrimitivesProvider, useUIPrimitives, } from "./ui-primitives.js";

package/components/shot-bar-view-model.d.ts

@@ -0,0 +1,24 @@
+import { type HideReason, type ResolvedShot, type TakeCommand, type Transition } from "@norskvideo/ctl-foundation/browser";
+/** Operator-facing text for why a shot can't be taken right now. */
+export declare function hideReasonLabel(reason: HideReason): string;
+/**
+ * Resolve a shot's graphic page to an absolute URL for `change-url`. Manifests
+ * ship relative paths (`/overlays/lbar.html`) so they're host-independent; the
+ * engine's `input.browser` needs an absolute http(s) URL. Absolute inputs pass
+ * through untouched, so an operator-typed full URL is honoured as-is.
+ */
+export declare function resolveGraphicUrl(url: string, origin: string): string;
+export interface PrepareTakeOptions {
+    /** Origin to resolve a relative graphic path against (usually `location.origin`). */
+    origin: string;
+    /** Operator-edited graphic URL from the card, if they changed it. */
+    editedUrl?: string;
+    transition?: Transition;
+    configOverride?: Record<string, unknown>;
+}
+/**
+ * Assemble the exact `TakeCommand[]` for a shot: pick the graphic URL (edited
+ * over manifest), resolve it to absolute, and hand `buildTake` the right opts.
+ * The result is what the consumer sends over its component WebSocket, in order.
+ */
+export declare function prepareTake(shot: ResolvedShot, opts: PrepareTakeOptions): TakeCommand[];

package/components/shot-bar-view-model.js

@@ -0,0 +1,59 @@
+// Pure view-model for the Shot Bar — the testable logic behind `ShotBar.tsx`,
+// kept React-free so it can be unit-tested without a DOM (the SDK ships no
+// render harness). The component stays a thin presentational shell over these.
+import { buildTake, } from "@norskvideo/ctl-foundation/browser";
+/** Operator-facing text for why a shot can't be taken right now. */
+export function hideReasonLabel(reason) {
+    switch (reason) {
+        case "no-compose":
+            return "No compositor in this channel";
+        case "no-programme":
+            return "Waiting for programme";
+        case "no-overlay-layer":
+            return "No graphics overlay layer";
+        case "no-commentator-on-camera":
+            return "No commentator on camera";
+        case "commentator-count-mismatch":
+            return "Doesn't fit the commentators on camera";
+        case "no-contributor":
+            return "No contributor connected";
+        case "graphic-shot-missing-url":
+            return "No graphic page configured";
+        default:
+            // Unknown reason from an untyped boundary — show something honest rather
+            // than crash the whole bar.
+            return "Unavailable";
+    }
+}
+/**
+ * Resolve a shot's graphic page to an absolute URL for `change-url`. Manifests
+ * ship relative paths (`/overlays/lbar.html`) so they're host-independent; the
+ * engine's `input.browser` needs an absolute http(s) URL. Absolute inputs pass
+ * through untouched, so an operator-typed full URL is honoured as-is.
+ */
+export function resolveGraphicUrl(url, origin) {
+    if (/^https?:\/\//i.test(url))
+        return url;
+    try {
+        return new URL(url, origin).toString();
+    }
+    catch {
+        // origin unusable (e.g. empty in a non-browser context) — return the raw
+        // value rather than throwing; the caller/engine will reject a bad URL.
+        return url;
+    }
+}
+/**
+ * Assemble the exact `TakeCommand[]` for a shot: pick the graphic URL (edited
+ * over manifest), resolve it to absolute, and hand `buildTake` the right opts.
+ * The result is what the consumer sends over its component WebSocket, in order.
+ */
+export function prepareTake(shot, opts) {
+    const rawUrl = opts.editedUrl ?? shot.graphicUrl;
+    const graphicUrl = rawUrl ? resolveGraphicUrl(rawUrl, opts.origin) : undefined;
+    return buildTake(shot, {
+        ...(graphicUrl ? { graphicUrl } : {}),
+        ...(opts.transition ? { transition: opts.transition } : {}),
+        ...(opts.configOverride ? { configOverride: opts.configOverride } : {}),
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@norskvideo/ctl-sdk",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "type": "module",
   "exports": {
     ".": {

package/product-service.d.ts

@@ -79,6 +79,21 @@ export interface ProductServiceOptions {
     containerOps?: ProductContainerOps;
 }
 export declare class ProductService {
+    /**
+     * Serialises every mutation. `add` decides on a store read — which host port
+     * is free, whether the name is taken — and only commits after starting a
+     * container, waiting for it, fetching its manifest and probing it. That gap
+     * cannot move inside the store's `update` callback: the callback is sync,
+     * and a registration cannot be written under its name before `fetchManifest`
+     * supplies the name. Two concurrent adds therefore allocated the same host
+     * port and both stored under one name.
+     *
+     * This is a lock in a different module from the data it protects, which is
+     * ordinarily the shape to avoid — accepted here because the invariant spans
+     * side effects (a running container, an allocated port) the store cannot
+     * see. See ADR-0008.
+     */
+    private readonly mutations;
     private readonly store;
     private readonly allocatePort;
     private readonly importProductTemplateBytes?;
@@ -92,8 +107,11 @@ export declare class ProductService {
      *  the dev URL — registered no longer implies running. */
     isRunning(reg: ProductRegistration): Promise<boolean>;
     add(spec: ProductSpec, opts?: AddProductOpts): Promise<AddProductResult>;
+    private addSerialised;
     remove(name: string): Promise<void>;
+    private removeSerialised;
     reload(name: string): Promise<ProductRegistration>;
+    private reloadSerialised;
     /** Stop every running container-kind product and clear its tracked
      *  containerId (model B: the daemon owns container lifecycle, so it reaps
      *  the control planes it started). Dev-kind products are externally owned —
@@ -102,6 +120,7 @@ export declare class ProductService {
      *  Best-effort per product — a failing `docker rm` is logged, never thrown,
      *  so one stubborn container can't block a clean shutdown. */
     stopAll(): Promise<void>;
+    private stopAllSerialised;
     /** Relaunch every container-kind product recorded in the store, refreshing
      *  its containerId (model B: called once at daemon boot to re-create the
      *  control planes stopped on the previous shutdown). Dev-kind products are
@@ -109,6 +128,7 @@ export declare class ProductService {
      *  come up is logged and left with its containerId cleared, so isRunning()
      *  reports it down rather than pointing at a container that never started. */
     restoreAll(): Promise<void>;
+    private restoreAllSerialised;
     /** Stop (if still present) and relaunch a single container-kind product,
      *  recording the fresh containerId. Used by the health monitor to recover a
      *  product that has failed its liveness probe. Unlike restoreAll this is not
@@ -117,4 +137,5 @@ export declare class ProductService {
      *  persisted before the readiness wait, so even a timed-out restart leaves a
      *  tracked container the next restart can reap rather than orphan. */
     restart(name: string): Promise<void>;
+    private restartSerialised;
 }

package/product-service.js

@@ -1,5 +1,5 @@
 import { readFile } from "node:fs/promises";
-import { logger } from "@norskvideo/ctl-foundation";
+import { logger, Mutex } from "@norskvideo/ctl-foundation";
 import { validateDevUrl } from "./dev-url.js";
 import { dockerRename, dockerRm, dockerRun, productContainerName } from "./docker-runner.js";
 import { resolveLicenseFile } from "./license-registration.js";
@@ -31,6 +31,21 @@ const defaultContainerOps = {
     waitForReady,
 };
 export class ProductService {
+    /**
+     * Serialises every mutation. `add` decides on a store read — which host port
+     * is free, whether the name is taken — and only commits after starting a
+     * container, waiting for it, fetching its manifest and probing it. That gap
+     * cannot move inside the store's `update` callback: the callback is sync,
+     * and a registration cannot be written under its name before `fetchManifest`
+     * supplies the name. Two concurrent adds therefore allocated the same host
+     * port and both stored under one name.
+     *
+     * This is a lock in a different module from the data it protects, which is
+     * ordinarily the shape to avoid — accepted here because the invariant spans
+     * side effects (a running container, an allocated port) the store cannot
+     * see. See ADR-0008.
+     */
+    mutations = new Mutex();
     store;
     allocatePort;
     importProductTemplateBytes;
@@ -57,6 +72,9 @@ export class ProductService {
         return this.isDevUrlAlive(specBaseUrl(reg.spec));
     }
     async add(spec, opts = {}) {
+        return this.mutations.run(() => this.addSerialised(spec, opts));
+    }
+    async addSerialised(spec, opts) {
         const existing = this.store.read();
         let baseUrl;
         let port;
@@ -222,6 +240,9 @@ export class ProductService {
         return { registration, warnings };
     }
     async remove(name) {
+        return this.mutations.run(() => this.removeSerialised(name));
+    }
+    async removeSerialised(name) {
         const existing = this.store.read();
         const target = existing.find((p) => p.name === name);
         if (!target)
@@ -232,6 +253,9 @@ export class ProductService {
         logger.info(`Product '${name}' removed`);
     }
     async reload(name) {
+        return this.mutations.run(() => this.reloadSerialised(name));
+    }
+    async reloadSerialised(name) {
         const existing = this.store.read();
         const target = existing.find((p) => p.name === name);
         if (!target)
@@ -254,6 +278,9 @@ export class ProductService {
      *  Best-effort per product — a failing `docker rm` is logged, never thrown,
      *  so one stubborn container can't block a clean shutdown. */
     async stopAll() {
+        return this.mutations.run(() => this.stopAllSerialised());
+    }
+    async stopAllSerialised() {
         const toStop = this.store.read().filter((p) => p.spec.kind === "container" && p.containerId !== undefined);
         if (toStop.length === 0)
             return;
@@ -276,6 +303,9 @@ export class ProductService {
      *  come up is logged and left with its containerId cleared, so isRunning()
      *  reports it down rather than pointing at a container that never started. */
     async restoreAll() {
+        return this.mutations.run(() => this.restoreAllSerialised());
+    }
+    async restoreAllSerialised() {
         const toRestore = this.store.read().filter((p) => p.spec.kind === "container");
         if (toRestore.length === 0)
             return;
@@ -308,6 +338,9 @@ export class ProductService {
      *  persisted before the readiness wait, so even a timed-out restart leaves a
      *  tracked container the next restart can reap rather than orphan. */
     async restart(name) {
+        return this.mutations.run(() => this.restartSerialised(name));
+    }
+    async restartSerialised(name) {
         const target = this.store.read().find((p) => p.name === name);
         if (!target)
             throw new ProductError("NOT_FOUND", `product '${name}' not registered`);