@norskvideo/ctl-dev-kit 0.2.107 → 0.2.109

package/create-demo/template/dashboard/dashboard/src/hooks/useAlerts.ts

@@ -0,0 +1,98 @@
+import { useEffect, useState } from "react";
+import type { EnvResponse } from "../api/types";
+import type { StatusTone } from "../components/StatusPill";
+
+// Studio's per-component alert. Emitted by `setAlert(id, {level, message})`
+// in the runtime; polled from `<apiBasePath>/<componentId>/alerts`. Cleared
+// entries drop out of the endpoint response, so an empty array means the
+// component is currently healthy (from Studio's own POV).
+export interface Alert {
+  level: "error" | "warning" | "info";
+  message: string;
+  startMs?: number;
+}
+
+const POLL_INTERVAL_MS = 3_000;
+
+// Polls Studio's alerts endpoint for a single component. Returns the current
+// alert array plus a `loaded` flag distinguishing "no alerts, healthy" from
+// "haven't fetched yet". Reset on componentId / env change.
+export function useAlerts(componentId: string | null, env: EnvResponse | null): { alerts: Alert[]; loaded: boolean } {
+  const [alerts, setAlerts] = useState<Alert[]>([]);
+  const [loaded, setLoaded] = useState(false);
+
+  useEffect(() => {
+    if (!componentId || !env) return;
+    setLoaded(false);
+    setAlerts([]);
+    let cancelled = false;
+    const url = `${env.apiBasePath}/${componentId}/alerts`;
+    const poll = async () => {
+      try {
+        const res = await fetch(url, { credentials: "include" });
+        if (!res.ok) return;
+        const json = (await res.json()) as Alert[];
+        if (cancelled) return;
+        setAlerts(Array.isArray(json) ? json : []);
+        setLoaded(true);
+      } catch {
+        // Silent — proxy hiccups, transient errors. Stale alerts stay
+        // visible until the next poll succeeds.
+      }
+    };
+    void poll();
+    const timer = setInterval(poll, POLL_INTERVAL_MS);
+    return () => {
+      cancelled = true;
+      clearInterval(timer);
+    };
+  }, [componentId, env]);
+
+  return { alerts, loaded };
+}
+
+// Derive a StatusPill tone from an alert list. Errors dominate warnings;
+// warnings dominate the healthy case. When the endpoint hasn't answered
+// yet, callers should fall back to the "unknown" tone via the second arg.
+export function toneFromAlerts(alerts: Alert[], loaded: boolean, fallbackTone: StatusTone = "unknown"): StatusTone {
+  if (!loaded) return fallbackTone;
+  if (alerts.some((a) => a.level === "error")) return "error";
+  if (alerts.some((a) => a.level === "warning")) return "ready";
+  return "live";
+}
+
+// Rewrite Studio's internal alert messages into copy that doesn't require
+// knowing what a "component" is. Studio phrases everything in terms of the
+// producing/consuming component; we recast for the operator reading the
+// dashboard. Optional `context` lets callers narrow to a role-specific
+// noun ("source", "camera", etc.).
+export function humanizeAlert(
+  message: string,
+  context?: { subject?: string; kind?: "input" | "output" | "session" },
+): string {
+  const subject = context?.subject ?? "This source";
+  if (/receiving no data/i.test(message)) {
+    return context?.kind === "input" ? "No data arriving from upstream" : `${subject}: nothing arriving yet`;
+  }
+  if (/sending no data/i.test(message)) {
+    return context?.kind === "output" ? "Not producing output yet" : `${subject}: not producing output yet`;
+  }
+  if (/no active connections/i.test(message)) return "No active connection";
+  return message.replace(/^This component /i, "");
+}
+
+// Short label for the pill based on alert state. `livedLabel` and
+// `errorLabel` let callers customise per row-type (e.g. "3 streams" vs
+// "Publishing").
+export function labelFromAlerts(
+  alerts: Alert[],
+  loaded: boolean,
+  labels: { live: string; warning?: string; error?: string; unknown?: string },
+): string {
+  if (!loaded) return labels.unknown ?? "Connecting";
+  const errorCount = alerts.filter((a) => a.level === "error").length;
+  if (errorCount > 0) return labels.error ?? `${errorCount} error${errorCount === 1 ? "" : "s"}`;
+  const warningCount = alerts.filter((a) => a.level === "warning").length;
+  if (warningCount > 0) return labels.warning ?? "Warning";
+  return labels.live;
+}

package/create-demo/template/dashboard/dashboard/src/hooks/useDiscovery.ts

@@ -0,0 +1,88 @@
+import { useEffect, useRef, useState } from "react";
+import type { ComponentsResponse, EnvResponse, WorkflowComponentDescriptor } from "../api/types";
+
+interface UseDiscoveryResult {
+  components: WorkflowComponentDescriptor[];
+  error: string | null;
+  loading: boolean;
+  attempts: number;
+  nextRetryMs: number | null;
+}
+
+// Bounded-exponential-backoff poller of `<apiBasePath>/components`. Studio
+// returns 503 with `{error: "Workflow is not running yet"}` until the
+// workflow boots; we keep polling until the response is 200 with a non-empty
+// `components` array. Once we have it, we exit the loop and the component
+// stays mounted regardless of later disconnects — the per-component WS hooks own
+// their own reconnect.
+const INITIAL_DELAY_MS = 500;
+const MAX_DELAY_MS = 5000;
+
+export function useDiscovery(env: EnvResponse | null): UseDiscoveryResult {
+  const [components, setComponents] = useState<WorkflowComponentDescriptor[]>([]);
+  const [error, setError] = useState<string | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [attempts, setAttempts] = useState(0);
+  const [nextRetryMs, setNextRetryMs] = useState<number | null>(null);
+  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  useEffect(() => {
+    if (!env) return;
+    let cancelled = false;
+    let delay = INITIAL_DELAY_MS;
+    let attempt = 0;
+
+    const tick = async () => {
+      attempt += 1;
+      if (cancelled) return;
+      setAttempts(attempt);
+      try {
+        const res = await fetch(`${env.apiBasePath}/components`);
+        if (res.status === 503) {
+          // Workflow not yet running — bounded retry.
+          scheduleRetry();
+          return;
+        }
+        if (!res.ok) {
+          throw new Error(`HTTP ${res.status}`);
+        }
+        const body = (await res.json()) as ComponentsResponse;
+        if (!body.components || body.components.length === 0) {
+          // Empty surface — keep polling.
+          scheduleRetry();
+          return;
+        }
+        if (cancelled) return;
+        setComponents(body.components);
+        setError(null);
+        setLoading(false);
+        setNextRetryMs(null);
+      } catch (err) {
+        if (cancelled) return;
+        setError(err instanceof Error ? err.message : String(err));
+        scheduleRetry();
+      }
+    };
+
+    const scheduleRetry = () => {
+      if (cancelled) return;
+      setNextRetryMs(delay);
+      timerRef.current = setTimeout(() => {
+        delay = Math.min(delay * 2, MAX_DELAY_MS);
+        void tick();
+      }, delay);
+    };
+
+    void tick();
+
+    return () => {
+      cancelled = true;
+      if (timerRef.current) {
+        clearTimeout(timerRef.current);
+        timerRef.current = null;
+      }
+    };
+  }, [env]);
+
+  return { components, error, loading, attempts, nextRetryMs };
+}

package/create-demo/template/dashboard/dashboard/src/hooks/useEnv.ts

@@ -0,0 +1,53 @@
+import { useEffect, useState } from "react";
+import type { EnvResponse } from "../api/types";
+
+interface UseEnvResult {
+  env: EnvResponse | null;
+  error: string | null;
+  loading: boolean;
+}
+
+// Resolves the dashboard's bound `env` endpoint. Studio serves
+// `/dashboard/<workflowName>/env` and returns `{studioUrlPrefix, apiBasePath, wsBasePath}`.
+// We fetch via a relative URL so the bundle works under arbitrary
+// `studioUrlPrefix` deployments.
+export function useEnv(): UseEnvResult {
+  const [env, setEnv] = useState<EnvResponse | null>(null);
+  const [error, setError] = useState<string | null>(null);
+  const [loading, setLoading] = useState(true);
+
+  useEffect(() => {
+    let cancelled = false;
+
+    (async () => {
+      try {
+        const res = await fetch("./env");
+        if (!res.ok) {
+          throw new Error(`env returned HTTP ${res.status}`);
+        }
+        const body = (await res.json()) as Partial<EnvResponse>;
+        if (!body.wsBasePath || !body.apiBasePath) {
+          throw new Error("env response missing wsBasePath/apiBasePath");
+        }
+        if (cancelled) return;
+        setEnv({
+          studioUrlPrefix: body.studioUrlPrefix ?? "",
+          apiBasePath: body.apiBasePath,
+          wsBasePath: body.wsBasePath,
+          note: body.note,
+        });
+        setLoading(false);
+      } catch (err) {
+        if (cancelled) return;
+        setError(err instanceof Error ? err.message : String(err));
+        setLoading(false);
+      }
+    })();
+
+    return () => {
+      cancelled = true;
+    };
+  }, []);
+
+  return { env, error, loading };
+}

package/create-demo/template/dashboard/dashboard/src/hooks/useLiveComponent.ts

@@ -0,0 +1,249 @@
+import type * as React from "react";
+import { useEffect, useReducer, useRef } from "react";
+import type { EnvResponse } from "../api/types";
+
+// Inbound WS frame shapes — server → client. Studio's public WS
+// (`<wsBasePath>/<id>/ws`) emits exactly these.
+type IncomingMessage =
+  | { type: "initial-state"; state: unknown }
+  | { type: "state-update"; state: unknown }
+  | { type: "event"; event: unknown }
+  | { type: "alert"; alert: unknown }
+  | { type: "error"; message: string };
+
+interface LiveComponentState<S, C = unknown> {
+  state: S | null;
+  config: C | null;
+  connected: boolean;
+  hasInitialState: boolean;
+  lastError: string | null;
+  disconnected: boolean;
+}
+
+type Action<S, C> =
+  | { type: "CONNECT" }
+  | { type: "DISCONNECT" }
+  | { type: "INIT"; state: S }
+  | { type: "UPDATE"; state: S }
+  | { type: "EVENT"; event: unknown }
+  | { type: "ALERT"; alert: unknown }
+  | { type: "ERROR"; message: string }
+  | { type: "CONFIG"; config: C };
+
+function reducer<S, C>(state: LiveComponentState<S, C>, action: Action<S, C>): LiveComponentState<S, C> {
+  switch (action.type) {
+    case "CONNECT":
+      return { ...state, connected: true, disconnected: false, lastError: null };
+    case "DISCONNECT":
+      return { ...state, connected: false, disconnected: true };
+    case "INIT":
+      return { ...state, state: action.state, hasInitialState: true };
+    case "UPDATE":
+      return { ...state, state: action.state };
+    case "EVENT":
+      // Events go to the onEvent callback, not into this state.
+      return state;
+    case "ALERT":
+      return state;
+    case "ERROR":
+      return { ...state, lastError: action.message };
+    case "CONFIG":
+      return { ...state, config: action.config };
+    default:
+      return state;
+  }
+}
+
+export interface UseLiveComponentResult<S, C = unknown> {
+  state: S | null;
+  config: C | null;
+  connected: boolean;
+  hasInitialState: boolean;
+  lastError: string | null;
+  sendCommand: (cmd: unknown) => void;
+}
+
+interface UseLiveComponentOptions<C> {
+  componentId: string;
+  env: EnvResponse | null;
+  // Optional initial config to seed the reducer. The discovery payload does
+  // not carry config; callers may supply a known default (e.g. one known
+  // from the workflow YAML), or leave null and render a loading state until
+  // state arrives.
+  initialConfig?: C | null;
+  // Optional callback fired whenever an `event` WS frame arrives. Studio
+  // broadcasts many state transitions as events (see e.g. videoCompose's
+  // `layout-changed`, `resolved-layout-changed`) without necessarily
+  // following up with a `state-update` snapshot. Consumers that need those
+  // deltas to drive local rendering should implement `onEvent` to reduce
+  // events into their own state — the hook itself keeps `EVENT` as a
+  // no-op in the reducer so no policy about event shapes leaks in.
+  //
+  // The callback identity is captured in a ref, so passing a fresh function
+  // per render does NOT trigger a WS reconnect.
+  onEvent?: (evt: unknown) => void;
+}
+
+const RECONNECT_INITIAL_MS = 500;
+const RECONNECT_MAX_MS = 10_000;
+
+// Extracted for direct unit testing without a live WebSocket. Exported under
+// a __-prefixed alias so consumers don't reach for it as public API.
+export function __handleIncomingFrame<S>(
+  parsed: IncomingMessage,
+  dispatch: (action: Action<S, unknown>) => void,
+  onEventRef: { current: ((evt: unknown) => void) | null | undefined },
+): void {
+  switch (parsed.type) {
+    case "initial-state":
+      dispatch({ type: "INIT", state: parsed.state as S });
+      break;
+    case "state-update":
+      dispatch({ type: "UPDATE", state: parsed.state as S });
+      break;
+    case "event":
+      dispatch({ type: "EVENT", event: parsed.event });
+      onEventRef.current?.(parsed.event);
+      break;
+    case "alert":
+      dispatch({ type: "ALERT", alert: parsed.alert });
+      break;
+    case "error":
+      dispatch({ type: "ERROR", message: parsed.message });
+      break;
+    default:
+      break;
+  }
+}
+
+export function useLiveComponent<S, C = unknown>(opts: UseLiveComponentOptions<C>): UseLiveComponentResult<S, C> {
+  const { componentId, env, initialConfig = null, onEvent } = opts;
+
+  // Capture the callback in a ref so the WS `useEffect`'s dep array can stay
+  // `[componentId, env]` — otherwise every parent re-render with a fresh
+  // callback identity would tear down + reconnect the socket.
+  const onEventRef = useRef<UseLiveComponentOptions<C>["onEvent"]>(onEvent);
+  onEventRef.current = onEvent;
+
+  const [state, dispatch] = useReducer(reducer as React.Reducer<LiveComponentState<S, C>, Action<S, C>>, {
+    state: null,
+    config: initialConfig,
+    connected: false,
+    hasInitialState: false,
+    lastError: null,
+    disconnected: false,
+  });
+
+  const wsRef = useRef<WebSocket | null>(null);
+  const reconnectTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const reconnectDelayRef = useRef<number>(RECONNECT_INITIAL_MS);
+
+  // Refresh seeded config if caller changes the prop.
+  useEffect(() => {
+    if (initialConfig) {
+      dispatch({ type: "CONFIG", config: initialConfig });
+    }
+  }, [initialConfig]);
+
+  useEffect(() => {
+    if (!env) return;
+    let cancelled = false;
+
+    const connect = () => {
+      if (cancelled) return;
+
+      // Compose the absolute WS URL relative to window.location. `env.wsBasePath`
+      // is path-only (e.g. `/live`). Honour the page's protocol — `wss:` when
+      // served over HTTPS.
+      const proto = window.location.protocol === "https:" ? "wss:" : "ws:";
+      const url = `${proto}//${window.location.host}${env.wsBasePath}/${componentId}/ws`;
+
+      let ws: WebSocket;
+      try {
+        ws = new WebSocket(url);
+      } catch (err) {
+        dispatch({ type: "ERROR", message: err instanceof Error ? err.message : String(err) });
+        scheduleReconnect();
+        return;
+      }
+      wsRef.current = ws;
+
+      ws.onopen = () => {
+        if (cancelled) return;
+        reconnectDelayRef.current = RECONNECT_INITIAL_MS;
+        dispatch({ type: "CONNECT" });
+      };
+
+      ws.onmessage = (event: MessageEvent) => {
+        if (cancelled) return;
+        let parsed: IncomingMessage;
+        try {
+          parsed = JSON.parse(typeof event.data === "string" ? event.data : "") as IncomingMessage;
+        } catch (err) {
+          dispatch({ type: "ERROR", message: `bad frame: ${err instanceof Error ? err.message : String(err)}` });
+          return;
+        }
+
+        __handleIncomingFrame<S>(parsed, dispatch as (a: Action<S, unknown>) => void, onEventRef);
+      };
+
+      ws.onerror = () => {
+        // The error event surface is opaque; rely on onclose to drive
+        // reconnect.
+        dispatch({ type: "ERROR", message: "websocket error" });
+      };
+
+      ws.onclose = () => {
+        if (cancelled) return;
+        wsRef.current = null;
+        dispatch({ type: "DISCONNECT" });
+        scheduleReconnect();
+      };
+    };
+
+    const scheduleReconnect = () => {
+      if (cancelled) return;
+      const delay = reconnectDelayRef.current;
+      reconnectDelayRef.current = Math.min(delay * 2, RECONNECT_MAX_MS);
+      reconnectTimerRef.current = setTimeout(() => {
+        connect();
+      }, delay);
+    };
+
+    connect();
+
+    return () => {
+      cancelled = true;
+      if (reconnectTimerRef.current) {
+        clearTimeout(reconnectTimerRef.current);
+        reconnectTimerRef.current = null;
+      }
+      if (wsRef.current) {
+        try {
+          wsRef.current.close();
+        } catch {
+          // ignore
+        }
+        wsRef.current = null;
+      }
+    };
+  }, [componentId, env]);
+
+  const sendCommand = (cmd: unknown) => {
+    const ws = wsRef.current;
+    if (!ws || ws.readyState !== WebSocket.OPEN) {
+      console.warn(`useLiveComponent[${componentId}]: dropping command — socket not open`);
+      return;
+    }
+    ws.send(JSON.stringify({ type: "command", command: cmd }));
+  };
+
+  return {
+    state: state.state,
+    config: state.config,
+    connected: state.connected,
+    hasInitialState: state.hasInitialState,
+    lastError: state.lastError,
+    sendCommand,
+  };
+}

package/create-demo/template/dashboard/dashboard/src/lib/workflow.ts

@@ -0,0 +1,11 @@
+// The one place the dashboard learns the workflow's shape. Component ids here
+// must match workdir/studio-save-files/__DEMO__/__DEMO__.yaml; when the
+// workflow changes, change it here too.
+
+export const WORKFLOW = {
+  // input.srt-listener: the camera or encoder feeding the demo.
+  input: { id: "srt_in", label: "SRT in" },
+
+  // output.preview in image mode: a still of the program, refreshed.
+  preview: { id: "preview" },
+} as const;

package/create-demo/template/dashboard/dashboard/src/main.tsx

@@ -0,0 +1,12 @@
+import { StrictMode } from "react";
+import { createRoot } from "react-dom/client";
+import { App } from "./App";
+import "./styles.css";
+
+const root = document.getElementById("root");
+if (!root) throw new Error("index.html has no #root");
+createRoot(root).render(
+  <StrictMode>
+    <App />
+  </StrictMode>,
+);

package/create-demo/template/dashboard/dashboard/src/styles.css

@@ -0,0 +1,84 @@
+:root {
+  color-scheme: dark;
+  font-family: system-ui, sans-serif;
+  background: #0b0d10;
+  color: #e5e7eb;
+}
+
+body {
+  margin: 0;
+}
+
+.page {
+  max-width: 1100px;
+  margin: 0 auto;
+  padding: 24px 16px;
+}
+
+h1 {
+  font-size: 20px;
+  margin: 0 0 16px;
+}
+
+h2 {
+  font-size: 14px;
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  color: #9ca3af;
+}
+
+.preview {
+  display: block;
+  width: 100%;
+  aspect-ratio: 16 / 9;
+  object-fit: contain;
+  background: #000;
+  border-radius: 6px;
+}
+
+.preview-empty {
+  display: grid;
+  place-items: center;
+  color: #9ca3af;
+}
+
+.components {
+  list-style: none;
+  padding: 0;
+  margin: 0;
+}
+
+.components li {
+  padding: 8px 0;
+  border-bottom: 1px solid #1f2937;
+}
+
+.component-name {
+  font-weight: 600;
+}
+
+.component-type {
+  margin-left: 8px;
+  color: #6b7280;
+  font-size: 12px;
+}
+
+.component-state {
+  margin: 6px 0 0;
+  font-size: 11px;
+  color: #9ca3af;
+}
+
+.component-state pre {
+  white-space: pre-wrap;
+}
+
+.status-pill {
+  display: inline-block;
+  margin-left: 8px;
+  padding: 2px 6px;
+  border-radius: 4px;
+  font-size: 10px;
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+}

package/create-demo/template/dashboard/dashboard/src/vite-env.d.ts

@@ -0,0 +1 @@
+/// <reference types="vite/client" />

package/create-demo/template/dashboard/dashboard/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "useDefineForClassFields": true,
+    "lib": ["ESNext", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "allowImportingTsExtensions": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "react-jsx",
+    "noEmit": true
+  },
+  "include": ["src"]
+}

package/create-demo/template/dashboard/dashboard/vite.config.ts

@@ -0,0 +1,35 @@
+import { resolve } from "node:path";
+import react from "@vitejs/plugin-react";
+import { defineConfig } from "vite";
+
+// Studio serves the build from studio-save-files/__DEMO__/dashboards/ at
+// /dashboard/__DEMO__/, so asset paths are relative. One page per HTML entry
+// under build.rollupOptions.input; add a page by adding an entry.
+//
+// `bun run dev` proxies Studio's routes to STUDIO_URL, so the pages can be
+// worked on against a running workflow. It must be a Studio reachable without
+// the sign-in proxy in front.
+const studio = process.env.STUDIO_URL ?? "http://localhost:8000";
+const toStudio = { target: studio, changeOrigin: true, secure: false, ws: true };
+
+export default defineConfig({
+  base: "./",
+  plugins: [react()],
+  resolve: { dedupe: ["react", "react-dom"] },
+  server: {
+    port: 5175,
+    proxy: {
+      "/env": { ...toStudio, rewrite: () => "/dashboard/__DEMO__/env" },
+      "/live": toStudio,
+    },
+  },
+  build: {
+    outDir: "dist",
+    emptyOutDir: true,
+    rollupOptions: {
+      input: {
+        index: resolve(__dirname, "index.html"),
+      },
+    },
+  },
+});