@norskvideo/ctl-dev-kit 0.2.107 → 0.2.109

package/create-demo/template/core/README.md.tmpl

@@ -0,0 +1,74 @@
+# __DEMO__
+
+<!-- The customer's handover document. Replace every TODO before handover; the
+     CLAUDE.md "Handover" list says what this needs to cover. -->
+
+TODO: one paragraph on what this demo does and who it is for.
+
+## What is in it
+
+| Path       | What it is                                                                                 |
+| ---------- | ------------------------------------------------------------------------------------------ |
+| `workdir/` | The Norsk Studio working directory: the workflow, and what Studio serves and loads with it |
+| `ctl/`     | The scripts that install it into norsk-ctl and update it                                   |
+| `scripts/` | Building it, and a test feed                                                               |
+<!-- if:dashboard -->
+| `dashboard/` | The operator dashboard |
+<!-- end:dashboard -->
+<!-- if:components -->
+| `components/` | This demo's own Studio components |
+<!-- end:components -->
+
+## Installing
+
+It runs under norsk-ctl, on this machine or another one over ssh.
+
+1. Install norsk-ctl on the machine, and have the norsk-studio licence there.
+2. Copy `ctl/site.example.env` to `ctl/site.env` and fill it in: where it runs, where the working
+   dir goes, the licence path, the ports to publish.
+3. Copy `ctl/studio.example.env` to `ctl/studio.env` and fill in the site's settings.
+4. Run `ctl/install.sh`. It prints the Studio URL when it is up.
+
+Building needs bun on the machine you run the scripts from.
+
+## Using it
+
+TODO: the URLs, and what the operator does on each page.
+
+- `scripts/test-feed.sh up` sends a test picture into the SRT input; `down` stops it.
+
+## The workflow
+
+TODO: each block in `workdir/studio-save-files/__DEMO__/__DEMO__.yaml`, in signal
+order: what it is for and the settings that matter.
+
+## Changing it
+
+- Edit the workflow YAML, then `ctl/push.sh`. It rebuilds, copies the working dir over and relaunches.
+- To change it in Studio's editor, `ctl/mode.sh editor`; `ctl/mode.sh document` puts it back to
+  running on start. Saving from the editor drops the YAML's comments, so copy changes back by hand.
+- Site settings (ports, passphrases, destinations) live in `ctl/studio.env`, as
+  `<COMPONENT_ID>_<FIELD>=value`.
+<!-- if:dashboard -->
+- The dashboard is in `dashboard/`; `src/lib/workflow.ts` names the components it shows.
+<!-- end:dashboard -->
+<!-- if:components -->
+- Custom components are in `components/src/library/`, one directory each.
+<!-- end:components -->
+
+## Limits
+
+TODO: what this demo does not do, and what a production build would add.
+
+There is no access control beyond norsk-ctl's own sign-in.
+
+## Versions
+
+TODO: the norsk-ctl, Studio and Norsk versions this was shown on
+(`norsk-ctl instance describe __DEMO__`).
+
+## Taking it out of norsk-ctl
+
+`norsk-ctl instance export __DEMO__ --to <dir>` writes a docker compose bundle that runs
+without norsk-ctl, with a `HANDOVER.md` of its own. Run it under its own project name, and put
+a reverse proxy in front of Studio: the bundle has none.

package/create-demo/template/core/ctl/install.sh

@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+# First install of the demo into norsk-ctl: here, or on DEMO_HOST over ssh
+# (see ctl/site.env). Builds, stages workdir/ at WORKDIR, and launches it as
+# instance __DEMO__ from the studio-dev template. ctl/push.sh updates it after.
+#
+#   ctl/install.sh [--no-build]
+source "$(dirname "$0")/lib.sh"
+load_site
+
+if ctl instance exists "$DEMO" >/dev/null 2>&1; then
+  die "instance $DEMO already exists: ctl/push.sh updates it"
+fi
+if [[ "${1:-}" != --no-build ]]; then "$ROOT/scripts/build.sh"; fi
+
+ensure_template
+sync_workdir
+write_overrides "$(current_mode)"
+
+ports=()
+for port in $HOST_PORTS; do ports+=(--host-ports "$port"); done
+ctl instance launch-template "$DEMO" --template studio-dev \
+  --param "INSTANCE_NAME=$DEMO" --param GLOBAL_MOQ_PREVIEW_WEBTRANSPORTPORT=auto \
+  --working-directory "$WORKDIR" --overrides "$WORKDIR/ctl-overrides.yml" \
+  --network-mode "$NETWORK_MODE" "${ports[@]}" >/dev/null
+
+wait_ready
+print_urls

package/create-demo/template/core/ctl/lib.sh

@@ -0,0 +1,146 @@
+#!/usr/bin/env bash
+# Shared by install.sh, push.sh and mode.sh: the site's settings, how to reach
+# the machine the demo runs on, and the overrides file norsk-ctl launches
+# Studio with. Sourced, not run.
+set -euo pipefail
+
+DEMO=__DEMO__
+CTL_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="$(dirname "$CTL_DIR")"
+
+die() {
+  echo "error: $*" >&2
+  exit 1
+}
+
+# ctl/site.env, with the defaults for anything it leaves unset.
+load_site() {
+  [[ -f "$CTL_DIR/site.env" ]] || die "no ctl/site.env: copy ctl/site.example.env to it and fill it in"
+  set -a
+  # shellcheck source=/dev/null
+  source "$CTL_DIR/site.env"
+  set +a
+  DEMO_HOST="${DEMO_HOST:-}"
+  WORKDIR="${WORKDIR:-/srv/$DEMO}"
+  NETWORK_MODE="${NETWORK_MODE:-docker}"
+  RUN_AS="${RUN_AS-norsk}"
+  NORSK_CTL="${NORSK_CTL:-norsk-ctl}"
+  HOST_PORTS="${HOST_PORTS:-}"
+  LICENSE_FILE="${LICENSE_FILE:-}"
+}
+
+quote() {
+  local out=() arg
+  for arg in "$@"; do out+=("$(printf '%q' "$arg")"); done
+  echo "${out[*]}"
+}
+
+# Run a shell command line on the target: over ssh when DEMO_HOST is set, here
+# otherwise. stdin passes through either way.
+on_target() {
+  if [[ -n "$DEMO_HOST" ]]; then ssh "$DEMO_HOST" "$*"; else bash -c "$*"; fi
+}
+
+# "sudo " when the working dir belongs to another user (RUN_AS), else nothing.
+target_sudo() {
+  if [[ -n "$RUN_AS" ]]; then echo "sudo "; fi
+}
+
+# norsk-ctl on the target, as the user its daemon runs as.
+ctl() {
+  local cmd
+  cmd="$NORSK_CTL $(quote "$@")"
+  if [[ -n "$RUN_AS" ]]; then cmd="sudo -u $(quote "$RUN_AS") -H $cmd"; fi
+  on_target "$cmd"
+}
+
+current_mode() {
+  cat "$CTL_DIR/.mode" 2>/dev/null || echo document
+}
+
+yaml_quote() {
+  local s="${1//\'/\'\'}"
+  printf "'%s'" "$s"
+}
+
+# The compose override norsk-ctl merges over the studio service, for a mode:
+#   document  Studio runs acme.yaml on start (the demo as shown)
+#   editor    Studio opens on the editor with nothing running (for changing it)
+# NODE_CONFIG names every library, the custom components included, because a
+# norsk-ctl older than the library fix lets this list replace the one it
+# writes. ctl/studio.env lines are Studio environment overrides, <ID>_<FIELD>.
+overrides_yaml() {
+  local mode="$1" libs server line
+  [[ "$mode" == document || "$mode" == editor ]] || die "unknown mode '$mode': document or editor"
+  libs='"@norskvideo/norsk-studio-built-ins","@norskvideo/norsk-studio-beta"'
+  if [[ -d "$ROOT/components" ]]; then libs="$libs,\"@$DEMO/library\""; fi
+  server="\"library\":[$libs]"
+  if [[ "$mode" == document ]]; then server="\"document\":\"$DEMO.yaml\",$server"; fi
+  echo "services:"
+  echo "  studio:"
+  echo "    environment:"
+  echo "      NODE_CONFIG: $(yaml_quote "{\"server\":{$server}}")"
+  if [[ -f "$CTL_DIR/studio.env" ]]; then
+    while IFS= read -r line || [[ -n "$line" ]]; do
+      [[ -z "${line// /}" || "$line" == \#* ]] && continue
+      echo "      ${line%%=*}: $(yaml_quote "${line#*=}")"
+    done <"$CTL_DIR/studio.env"
+  fi
+}
+
+write_overrides() {
+  overrides_yaml "$1" | on_target "$(target_sudo)tee $(quote "$WORKDIR/ctl-overrides.yml") >/dev/null"
+}
+
+# Copy workdir/ to WORKDIR on the target, owned by RUN_AS. Nothing already
+# there is deleted (Studio keeps its own files in it), except inside the two
+# build outputs, where a stale file would still be served or loaded.
+sync_workdir() {
+  local dest="$WORKDIR" rsync=(rsync) opts=(-a) sub
+  on_target "$(target_sudo)mkdir -p $(quote "$WORKDIR")"
+  if [[ -n "$RUN_AS" ]]; then
+    opts+=("--chown=$RUN_AS:$RUN_AS")
+    if [[ -n "$DEMO_HOST" ]]; then opts+=(--rsync-path="sudo rsync"); else rsync=(sudo rsync); fi
+  fi
+  if [[ -n "$DEMO_HOST" ]]; then dest="$DEMO_HOST:$WORKDIR"; fi
+  "${rsync[@]}" "${opts[@]}" --exclude logs --exclude .norsk --exclude moq-certs --exclude ctl-overrides.yml \
+    "$ROOT/workdir/" "$dest/"
+  for sub in "studio-save-files/$DEMO/dashboards" components; do
+    if [[ -d "$ROOT/workdir/$sub" ]]; then
+      "${rsync[@]}" "${opts[@]}" --delete "$ROOT/workdir/$sub/" "$dest/$sub/"
+    fi
+  done
+}
+
+# The studio-dev product template, added from the licence when it is missing.
+ensure_template() {
+  if ctl template list 2>/dev/null | grep -q "name: studio-dev"; then return; fi
+  [[ -n "$LICENSE_FILE" ]] || die "norsk-ctl has no studio-dev template: set LICENSE_FILE in ctl/site.env"
+  ctl product add --license-file "$LICENSE_FILE" --product norsk-studio >/dev/null
+}
+
+describe_field() {
+  ctl instance describe "$DEMO" -o json 2>/dev/null | bun -e '
+    const text = await Bun.stdin.text();
+    let v = JSON.parse(text.slice(text.indexOf("{")));
+    for (const key of process.argv[1].split(".")) v = v?.[key];
+    console.log(v ?? "");
+  ' "$1"
+}
+
+wait_ready() {
+  local i
+  for ((i = 0; i < 90; i++)); do
+    if [[ "$(describe_field runtimeScreen.ready 2>/dev/null)" == true ]]; then return 0; fi
+    sleep 2
+  done
+  die "$DEMO did not come up within 3 minutes: see norsk-ctl instance describe $DEMO"
+}
+
+print_urls() {
+  local studio
+  studio="$(describe_field runtimeScreen.href)"
+  echo "Studio:    $studio"
+  if [[ -d "$ROOT/dashboard" ]]; then echo "Dashboard: ${studio}dashboard/$DEMO/"; fi
+  echo "Mode:      $(current_mode)"
+}

package/create-demo/template/core/ctl/mode.sh

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+# Switch the installed demo between its two modes, and relaunch it:
+#   document  Studio runs the workflow on start: the demo as it is shown.
+#             The editor's Stop button is hidden in this mode.
+#   editor    Studio opens on the editor with nothing running, to change it.
+#
+#   ctl/mode.sh document|editor
+source "$(dirname "$0")/lib.sh"
+load_site
+
+mode="${1:-}"
+overrides_yaml "$mode" >/dev/null
+ctl instance exists "$DEMO" >/dev/null 2>&1 || die "no instance $DEMO yet: run ctl/install.sh first"
+
+echo "$mode" >"$CTL_DIR/.mode"
+write_overrides "$mode"
+ctl instance relaunch "$DEMO" >/dev/null
+wait_ready
+print_urls

package/create-demo/template/core/ctl/push.sh

@@ -0,0 +1,16 @@
+#!/usr/bin/env bash
+# Push a change to the installed demo: build, sync workdir/ to WORKDIR, rewrite
+# the overrides from ctl/studio.env, relaunch, and wait until Studio is up.
+#
+#   ctl/push.sh [--no-build]
+source "$(dirname "$0")/lib.sh"
+load_site
+
+ctl instance exists "$DEMO" >/dev/null 2>&1 || die "no instance $DEMO yet: run ctl/install.sh first"
+if [[ "${1:-}" != --no-build ]]; then "$ROOT/scripts/build.sh"; fi
+
+sync_workdir
+write_overrides "$(current_mode)"
+ctl instance relaunch "$DEMO" >/dev/null
+wait_ready
+print_urls

package/create-demo/template/core/ctl/site.example.env

@@ -0,0 +1,30 @@
+# Where and how this demo runs under norsk-ctl. Copy to ctl/site.env (which
+# is gitignored) and fill it in; ctl/install.sh, push.sh and mode.sh read it.
+
+# The machine norsk-ctl runs on: user@host over ssh, or empty for this one.
+DEMO_HOST=
+
+# Where the working dir is staged on that machine. It must be a path the
+# norsk-ctl user can reach: a directory under someone's home usually is not.
+WORKDIR=/srv/__DEMO__
+
+# The user the norsk-ctl daemon runs as: the working dir is owned by it and
+# norsk-ctl is run as it (via sudo). Empty runs both as the ssh/local user.
+RUN_AS=norsk
+
+# The norsk-ctl command on that machine.
+NORSK_CTL=norsk-ctl
+
+# A path on that machine to the norsk-studio licence, used once to add the
+# studio-dev product template if norsk-ctl does not have it yet.
+LICENSE_FILE=
+
+# docker (norsk-ctl's default) or hybrid. hybrid puts media on the host
+# network: needed when a viewer receives WebRTC media (WHEP, WHIP) directly.
+NETWORK_MODE=docker
+
+# Ingest ports to publish on the host, space separated, HOST[:CONTAINER][/udp].
+# Everything else is allocated by norsk-ctl; pin a port only when a sender or
+# a firewall outside the box must agree on it. 5001/udp is the SRT input
+# (srt_in in the workflow); change both together.
+HOST_PORTS="5001/udp"

package/create-demo/template/core/ctl/studio.example.env

@@ -0,0 +1,12 @@
+# Site settings for the workflow. Copy to ctl/studio.env (which is gitignored).
+#
+# Each line is a Studio environment override, <COMPONENT_ID>_<FIELD>=value:
+# it replaces that field of that component in the workflow YAML at launch, for
+# any field the component declares overridable. This is where ports,
+# passphrases and destinations go, so the YAML carries no site's values and no
+# secrets. ctl/push.sh writes these into the overrides norsk-ctl launches with.
+#
+# A port changed here must be changed in HOST_PORTS (ctl/site.env) too.
+
+# SRT_IN_PORT=5001
+# SRT_IN_PASSPHRASE=

package/create-demo/template/core/gitignore

@@ -0,0 +1,18 @@
+# The site's settings: copied from the .example files, never committed.
+ctl/site.env
+ctl/studio.env
+ctl/.mode
+
+node_modules/
+
+# Build output, rebuilt by scripts/build.sh.
+dashboard/dist/
+components/lib/
+components/src/**/_gen/
+workdir/studio-save-files/*/dashboards/
+workdir/components/
+
+# What Studio writes into its working dir while it runs.
+workdir/logs/
+workdir/.norsk/
+workdir/moq-certs/

package/create-demo/template/core/scripts/build.sh

@@ -0,0 +1,30 @@
+#!/usr/bin/env bash
+# Build what this demo adds to Studio, into workdir/ where Studio finds it:
+#   dashboard/   -> workdir/studio-save-files/__DEMO__/dashboards/  served at /dashboard/__DEMO__/
+#   components/  -> workdir/components/@__DEMO__/library/          loaded as a Studio library
+# A demo without either has nothing to build.
+set -euo pipefail
+root="$(cd "$(dirname "$0")/.." && pwd)"
+
+install_to() {
+  local from="$1" dest="$2"
+  rm -rf "$dest"
+  mkdir -p "$dest"
+  cp -r "$from/." "$dest/"
+  echo "installed ${dest#"$root"/}"
+}
+
+if [[ -d "$root/dashboard" ]]; then
+  # vite 8 needs util.parseEnv, which bun 1.1 does not have.
+  if ! bun -e 'if (typeof require("node:util").parseEnv !== "function") process.exit(1)' 2>/dev/null; then
+    echo "error: bun $(bun --version) is too old to build the dashboard (vite 8 needs util.parseEnv): run bun upgrade" >&2
+    exit 1
+  fi
+  (cd "$root/dashboard" && bun install >/dev/null && bun run build)
+  install_to "$root/dashboard/dist" "$root/workdir/studio-save-files/__DEMO__/dashboards"
+fi
+
+if [[ -d "$root/components" ]]; then
+  (cd "$root/components" && bun install >/dev/null && bun run build)
+  install_to "$root/components/lib/library" "$root/workdir/components/@__DEMO__/library"
+fi

package/create-demo/template/core/scripts/test-feed.sh

@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+# A labelled test picture with a tone, sent into the SRT input (srt_in), so the
+# demo has something to show without a camera. Runs ffmpeg in docker.
+#
+#   scripts/test-feed.sh up|down
+#
+# FEED_HOST is where the demo runs (default this machine); the port is
+# SRT_IN_PORT from ctl/studio.env, else the workflow's 5001.
+set -euo pipefail
+root="$(cd "$(dirname "$0")/.." && pwd)"
+
+# A setting from ctl/studio.env, or nothing: an unset one is not an error.
+studio_env() { grep -E "^$1=" "$root/ctl/studio.env" 2>/dev/null | cut -d= -f2- || true; }
+
+host="${FEED_HOST:-127.0.0.1}"
+port="$(studio_env SRT_IN_PORT)"
+port="${port:-5001}"
+passphrase="$(studio_env SRT_IN_PASSPHRASE)"
+image="${FFMPEG_IMAGE:-linuxserver/ffmpeg:8.0.1}"
+name="__DEMO__-test-feed"
+
+case "${1:-up}" in
+  up)
+    url="srt://${host}:${port}?mode=caller&latency=200000"
+    if [[ -n "$passphrase" ]]; then url="${url}&passphrase=${passphrase}"; fi
+    docker rm -f "$name" >/dev/null 2>&1 || true
+    docker run -d --restart unless-stopped --name "$name" --network host "$image" \
+      -hide_banner -loglevel warning -re \
+      -f lavfi -i "testsrc2=size=1280x720:rate=25" \
+      -f lavfi -i "sine=frequency=440:sample_rate=48000" \
+      -vf "drawtext=text='__DEMO__  %{localtime\:%T}':fontcolor=white:fontsize=64:x=40:y=40" \
+      -c:v libx264 -preset veryfast -tune zerolatency -g 50 -b:v 3M -pix_fmt yuv420p \
+      -c:a aac -b:a 128k -ac 2 \
+      -f mpegts "$url" >/dev/null
+    echo "test feed -> ${host}:${port}"
+    ;;
+  down)
+    docker rm -f "$name" >/dev/null 2>&1 && echo "test feed stopped" || true
+    ;;
+  *)
+    echo "usage: $0 up|down" >&2
+    exit 2
+    ;;
+esac

package/create-demo/template/dashboard/dashboard/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <link rel="icon" href="data:," />
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>__DEMO__</title>
+</head>
+<body>
+  <div id="root"></div>
+  <script type="module" src="/src/main.tsx"></script>
+</body>
+</html>

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

@@ -0,0 +1,22 @@
+{
+  "name": "__DEMO__-dashboard",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc --noEmit && vite build",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.0.10",
+    "@types/react-dom": "^19.0.3",
+    "@vitejs/plugin-react": "^6.0.1",
+    "typescript": "^5.7.2",
+    "vite": "^8.0.0"
+  }
+}

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

@@ -0,0 +1,61 @@
+import type { EnvResponse, WorkflowComponentDescriptor } from "./api/types";
+import { ImagePreview } from "./components/ImagePreview";
+import { StatusPill } from "./components/StatusPill";
+import { labelFromAlerts, toneFromAlerts, useAlerts } from "./hooks/useAlerts";
+import { useDiscovery } from "./hooks/useDiscovery";
+import { useEnv } from "./hooks/useEnv";
+import { useLiveComponent } from "./hooks/useLiveComponent";
+import { WORKFLOW } from "./lib/workflow";
+
+// The starter page: the program preview, and every running component with its
+// health and live state. Replace it with what the operator actually needs; the
+// hooks are the parts to keep.
+export function App() {
+  const { env, error } = useEnv();
+  const { components, loading } = useDiscovery(env);
+
+  if (error) return <main className="page">Cannot reach Studio: {error}</main>;
+  return (
+    <main className="page">
+      <header>
+        <h1>__DEMO__</h1>
+      </header>
+      <ImagePreview componentId={WORKFLOW.preview.id} env={env} />
+      <section>
+        <h2>Components</h2>
+        {loading ? (
+          <p>Waiting for the workflow to start</p>
+        ) : (
+          <ul className="components">
+            {components.map((c) => (
+              <ComponentRow key={c.componentId} component={c} env={env} />
+            ))}
+          </ul>
+        )}
+      </section>
+    </main>
+  );
+}
+
+function ComponentRow({ component, env }: { component: WorkflowComponentDescriptor; env: EnvResponse | null }) {
+  const { alerts, loaded } = useAlerts(component.componentId, env);
+  return (
+    <li>
+      <span className="component-name">{component.displayName ?? component.componentId}</span>
+      <span className="component-type">{component.componentType}</span>
+      <StatusPill tone={toneFromAlerts(alerts, loaded)} label={labelFromAlerts(alerts, loaded, { live: "OK" })} />
+      {component.capabilities.hasState && <LiveState componentId={component.componentId} env={env} />}
+    </li>
+  );
+}
+
+function LiveState({ componentId, env }: { componentId: string; env: EnvResponse | null }) {
+  const { state } = useLiveComponent<unknown>({ componentId, env });
+  if (state === null) return null;
+  return (
+    <details className="component-state">
+      <summary>State</summary>
+      <pre>{JSON.stringify(state, null, 2)}</pre>
+    </details>
+  );
+}

package/create-demo/template/dashboard/dashboard/src/api/types.ts

@@ -0,0 +1,38 @@
+// What the dashboard reads from Studio. The discovery response is the
+// workflow's `<apiBasePath>/components` endpoint, which returns each running
+// component's type and capabilities only: its config and state arrive over the
+// component's websocket (see useLiveComponent).
+
+export interface EnvResponse {
+  studioUrlPrefix: string;
+  apiBasePath: string;
+  wsBasePath: string;
+  note?: string;
+}
+
+export interface ComponentCapabilities {
+  hasHttp: boolean;
+  hasWebSocket: boolean;
+  hasViews: boolean;
+  hasState: boolean;
+}
+
+export interface WorkflowComponentDescriptor {
+  componentId: string;
+  componentType: string;
+  displayName?: string;
+  capabilities: ComponentCapabilities;
+}
+
+export interface ComponentsResponse {
+  components: WorkflowComponentDescriptor[];
+  totalComponents: number;
+}
+
+// `output.preview`'s state. `url` depends on the preview mode: a JPEG URL in
+// image mode, a WHEP endpoint in webrtc mode, a WebTransport base URL in moq.
+export interface PreviewState {
+  url?: string;
+  previewMode?: string;
+  [k: string]: unknown;
+}

package/create-demo/template/dashboard/dashboard/src/components/ImagePreview.tsx

@@ -0,0 +1,23 @@
+import { useCallback, useState } from "react";
+import type { EnvResponse, PreviewState } from "../api/types";
+import { useLiveComponent } from "../hooks/useLiveComponent";
+
+// The program as a still from an `output.preview` in image mode. Its state
+// carries the first JPEG's URL, and each newer one arrives as a `url-published`
+// event, about once a second. No player and no media ports, so it works in
+// norsk-ctl's docker network mode. For live video, see the CLAUDE.md
+// "Dashboard" notes.
+export function ImagePreview({ componentId, env }: { componentId: string; env: EnvResponse | null }) {
+  const [published, setPublished] = useState<string | null>(null);
+  const onEvent = useCallback((evt: unknown) => {
+    const e = evt as { type?: string; url?: unknown };
+    if (e.type === "url-published" && typeof e.url === "string") setPublished(e.url);
+  }, []);
+  const { state, connected } = useLiveComponent<PreviewState>({ componentId, env, onEvent });
+
+  const url = published ?? (typeof state?.url === "string" && state.url.length > 0 ? state.url : null);
+  if (!url) {
+    return <div className="preview preview-empty">{connected ? "Waiting for a picture" : "Connecting"}</div>;
+  }
+  return <img className="preview" src={url} alt="Program preview" />;
+}

package/create-demo/template/dashboard/dashboard/src/components/StatusPill.tsx

@@ -0,0 +1,65 @@
+// A status pill. Six tones aligned with what Studio's per-component /alerts
+// endpoint reports.
+// A component's tone is derived from its live alerts list:
+//
+//   live    — no alerts (Studio considers this component healthy)
+//   ready   — warning-level alerts only (e.g. "no active connections")
+//   waiting — expected upstream not yet reached (config-derived)
+//   idle    — configured but off / disabled (config-derived)
+//   error   — any error-level alert (e.g. "receiving no data")
+//   unknown — Studio's state doesn't expose the signal we'd need
+//
+// Card headers may add a matching border-left accent via `toneAccentColor`.
+
+export type StatusTone = "live" | "ready" | "waiting" | "idle" | "error" | "unknown";
+
+interface StatusPillProps {
+  tone: StatusTone;
+  label: string;
+}
+
+const PALETTE: Record<StatusTone, { background: string; color: string; border: string }> = {
+  live: {
+    background: "rgba(34, 197, 94, 0.20)",
+    color: "rgb(134, 239, 172)",
+    border: "1px solid rgba(34, 197, 94, 0.55)",
+  },
+  ready: {
+    background: "rgba(59, 130, 246, 0.20)",
+    color: "rgb(147, 197, 253)",
+    border: "1px solid rgba(59, 130, 246, 0.55)",
+  },
+  waiting: {
+    background: "rgba(234, 179, 8, 0.20)",
+    color: "rgb(253, 224, 71)",
+    border: "1px solid rgba(234, 179, 8, 0.55)",
+  },
+  idle: {
+    background: "rgba(107, 114, 128, 0.20)",
+    color: "rgb(209, 213, 219)",
+    border: "1px solid rgba(107, 114, 128, 0.55)",
+  },
+  error: {
+    background: "rgba(239, 68, 68, 0.20)",
+    color: "rgb(252, 165, 165)",
+    border: "1px solid rgba(239, 68, 68, 0.55)",
+  },
+  unknown: {
+    background: "rgba(107, 114, 128, 0.08)",
+    color: "rgb(156, 163, 175)",
+    border: "1px dashed rgba(107, 114, 128, 0.55)",
+  },
+};
+
+export function StatusPill({ tone, label }: StatusPillProps) {
+  return (
+    <span className="status-pill" style={PALETTE[tone]} data-tone={tone}>
+      {label}
+    </span>
+  );
+}
+
+// For card border-left accents matching a section's aggregate status.
+export function toneAccentColor(tone: StatusTone): string {
+  return PALETTE[tone].border.replace("1px solid ", "").replace("1px dashed ", "");
+}