@norskvideo/ctl-dev-kit 0.2.106 → 0.2.108

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"),
+      },
+    },
+  },
+});

package/create-product/cli.ts

@@ -5,6 +5,7 @@
 // so the bin runs under bun (the fleet's only runtime).
 import { existsSync, readdirSync } from "node:fs";
 import { parseArgs } from "node:util";
+import { createDemo, type DemoFeature } from "../create-demo/create-demo.ts";
 import { createDashboard } from "../dashboard/create-dashboard.ts";
 import { writeDashboardManifest } from "../dashboard/manifest.ts";
 import { createProduct, type ProductFeature, type ProductShape, type StudioLibrary } from "./create-product.ts";
@@ -13,6 +14,8 @@ const SHAPES: ProductShape[] = ["backend-turnkey", "turnkey"];
 
 const USAGE = `Usage:
   ctl-dev-kit create-product --name <name> [options] <dir>
+  ctl-dev-kit create-demo --name <name> [--with dashboard,components] [--user <user>] <dir>
+                                                    a customer demo: a Studio working dir installed into norsk-ctl
   ctl-dev-kit create-dashboard --name <name> <dir>   a fleet dashboard norsk-mgr hosts (a live runtime list)
   ctl-dev-kit dashboard-manifest <src> <dist>   write <dist>/dashboard.json from a fleet dashboard's calls
 
@@ -57,9 +60,13 @@ export function main(argv: string[]): void {
     newDashboard(rest);
     return;
   }
+  if (command === "create-demo") {
+    newDemo(rest);
+    return;
+  }
   if (command !== "create-product") {
     fail(
-      `unknown command ${JSON.stringify(command ?? "")} — the commands are create-product, create-dashboard and dashboard-manifest.`,
+      `unknown command ${JSON.stringify(command ?? "")} — the commands are create-product, create-demo, create-dashboard and dashboard-manifest.`,
     );
   }
   const { values, positionals } = parseArgs({
@@ -172,3 +179,34 @@ Next steps (also in its README):
   3. norsk-mgr dashboard register ${values.name} && norsk-mgr dashboard upload ${values.name} dashboard.tar
 `);
 }
+
+function newDemo(args: string[]): void {
+  const { values, positionals } = parseArgs({
+    args,
+    allowPositionals: true,
+    options: { name: { type: "string" }, with: { type: "string" }, user: { type: "string" } },
+  });
+  const dir = positionals[0];
+  if (!dir) fail("missing <dir>.");
+  if (!values.name) fail("missing --name.");
+  if (existsSync(dir) && readdirSync(dir).length > 0) fail(`${dir} exists and is not empty — refusing to overwrite.`);
+  const withFeatures = values.with
+    ?.split(",")
+    .map((f) => f.trim())
+    .filter(Boolean) as DemoFeature[] | undefined;
+  let files: string[];
+  try {
+    ({ files } = createDemo({ dir, name: values.name, user: values.user ?? process.env.USER ?? "me", withFeatures }));
+  } catch (err) {
+    fail(err instanceof Error ? err.message : String(err));
+  }
+  console.log(`Generated ${files.length} files into ${dir}.
+
+Next steps (also in the generated CLAUDE.md):
+  1. cd ${dir} && git init
+  2. cp ctl/site.example.env ctl/site.env && cp ctl/studio.example.env ctl/studio.env   # then fill them in
+  3. ctl/install.sh                     # build, stage the working dir, launch instance ${values.name} in norsk-ctl
+  4. scripts/test-feed.sh up            # a test picture into the SRT input
+  5. Replace the starter workflow in workdir/studio-save-files/${values.name}/ and ctl/push.sh after each change.
+`);
+}

package/create-product/features/components.ts

@@ -608,7 +608,10 @@ export function exampleSidecar(args: ExampleArgs): WorkflowComponent<ExampleConf
 `;
 }
 
-export function componentsFiles(ctx: ShapeContext): GeneratedFile[] {
+/** The components/ workspace alone — its build chain and the example node,
+ *  without the product glue componentsFiles adds. create-demo uses this: a demo
+ *  has no backend or shared/, and its build copies lib/ into the working dir. */
+export function componentsWorkspaceFiles(ctx: ShapeContext): GeneratedFile[] {
   return [
     { path: "components/package.json", content: packageJson(ctx) },
     { path: "components/tsconfig.json", content: TSCONFIG },
@@ -621,6 +624,12 @@ export function componentsFiles(ctx: ShapeContext): GeneratedFile[] {
     { path: "components/src/library/example/types.source.yaml", content: EXAMPLE_TYPES_YAML },
     { path: "components/src/library/example/info.ts", content: exampleInfoTs(ctx) },
     { path: "components/src/library/example/runtime.ts", content: EXAMPLE_RUNTIME_TS },
+  ];
+}
+
+export function componentsFiles(ctx: ShapeContext): GeneratedFile[] {
+  return [
+    ...componentsWorkspaceFiles(ctx),
     { path: "backend/src/lib/components.ts", content: BACKEND_LIB_COMPONENTS_TS },
     { path: "shared/src/workflow/example-config.ts", content: exampleConfigTs(ctx) },
   ];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@norskvideo/ctl-dev-kit",
-  "version": "0.2.106",
+  "version": "0.2.108",
   "type": "module",
   "exports": {
     "./create-product": "./create-product/create-product.ts",