@norskvideo/ctl-dev-kit 0.2.107 → 0.2.109

package/conventions/DESIGN.family.md

@@ -0,0 +1,73 @@
+<!-- BEGIN ctl-shared-design v1 -->
+<!--
+  This block is the SHARED family design core for Norsk operator consoles,
+  single-sourced in @norskvideo/ctl-dev-kit (conventions/DESIGN.family.md). It
+  is copied verbatim into every product dashboard's DESIGN.md
+  (dashboards/<name>/DESIGN.md) between these fenced markers, and the drift
+  gate fails CI if a copy diverges. Do NOT hand-edit a copy: edit the dev-kit
+  source and re-sync. The console's own north star, accent, components and
+  product rules live OUTSIDE the markers and are yours to own.
+-->
+
+## Family rules (shared by every Norsk operator console — do not edit in place)
+
+An operator moving between consoles (a commentary gallery, a playout desk) must
+read on-air, health and interaction identically. These rules and the shared
+palette below hold on every console. The operator-UI principles behind them live
+in norsk-studio `docs/operator-ui-principles.md`; change a principle there first,
+then here.
+
+### Shared palette
+
+Status and neutral tokens are the same on every console. Each console's
+frontmatter `colors:` must carry exactly these values (the drift gate checks);
+its `accent` tokens are its own.
+
+| Token     | Value     | Role                                                        |
+| --------- | --------- | ----------------------------------------------------------- |
+| `live`    | `#ff4557` | On-Air Red: live / on air. The only colour allowed to glow. |
+| `ok`      | `#35d29a` | Healthy.                                                    |
+| `warn`    | `#f4b63f` | At risk.                                                    |
+| `crit`    | `#ff7a4d` | Failed.                                                     |
+| `bg`      | `#0d1014` | Background.                                                 |
+| `panel`   | `#141a21` | Panel tone 1.                                               |
+| `panel-2` | `#1a2129` | Panel tone 2.                                               |
+| `panel-3` | `#202932` | Panel tone 3.                                               |
+| `line`    | `#262f3b` | Hairline border.                                            |
+| `ink`     | `#e8edf3` | Primary text.                                               |
+| `ink-mut` | `#9aa6b5` | Secondary text.                                             |
+| `ink-dim` | `#8794a3` | Tertiary text; still clears 4.5:1.                          |
+
+### Family named rules
+
+**The Reserved Accent Rule.** The console's accent means _interactive_. Status
+never borrows it: health, metering and channel state live entirely in the
+red/green/amber/coral system. If a swatch of the accent is not clickable or a
+focus state, it is wrong.
+
+**The One Glow Rule.** Only On-Air Red is allowed a glow (`box-shadow` bloom),
+and it sits on the console's on-air programme view. Everything else is flat. A
+glow anywhere else dilutes the one signal that must never be missed.
+
+**The Tabular Rule.** Any column or readout of numbers (timecode, durations,
+countdowns, meter scales, dB, ports) is `font-variant-numeric: tabular-nums`, so
+digits never jitter as they tick.
+
+**The Flat-By-Default Rule.** New surfaces get a tone step and a 1px border.
+Reach for `box-shadow` only for the On-Air glow or the focus ring; never to lift
+a card.
+
+**The Immediate-PGM, Honest-OUT Rule.** Show an operator's decision the moment
+it is decided, and keep a separate, true view of what is going out. A desk that
+cuts or takes programme carries two labelled views: **PGM**, which changes the
+instant a cut or take is committed, using a preview the desk already has; and
+**OUT**, the real encoded output with graphics and everything else applied
+downstream, whose transport lag is labelled as expected rather than styled as a
+fault. Only a committed decision is immediate: a guarded action changes nothing
+on PGM until it is confirmed, and a load or a source still arriving shows its
+pending state. Never simulate downstream processing in PGM; OUT is the authority
+on what aired. When both views are present, the ON AIR pill and the One Glow sit
+on PGM, following the gallery tally convention. A desk with only one programme
+view shows the true output and labels its lag.
+
+<!-- END ctl-shared-design v1 -->

package/conventions/check-drift.ts

@@ -5,6 +5,9 @@
 //     tsconfig.base.json, the .gitignore core block, scripts/demo (only a
 //     product with tests/demo.spec.ts is asked for it), publish-docs-site.yml
 //     (only a repo with a docs site may carry it, and never a turnkey)
+//   - verbatim marker block + palette: each dashboards/*/DESIGN.md embeds the
+//     DESIGN.family.md block, and its frontmatter colors: carry that block's
+//     shared palette (no DESIGN.md, no requirement)
 //   - masked per-repo line: checks.yml, bump.yml, publish-docs.yml and the
 //     other dispatching workflows (`product:` key)
 //   - retired: upgrade-latest.yml, sync-dev-kit.yml, sync-ctl-packages.yml,
@@ -255,6 +258,97 @@ function coreProblem(claude: string, canonicalCore: string): string | undefined
   return `CLAUDE.md fenced core has drifted from @norskvideo/ctl-dev-kit conventions/CLAUDE.core.md (${firstDiffLine(region, canonicalCore.trimEnd())}). ${RESYNC}`;
 }
 
+// Each operator console's dashboards/<name>/DESIGN.md embeds the family design
+// block verbatim between these markers, and its frontmatter `colors:` must carry
+// the shared palette that block's table defines. The table is the one source of
+// the expected values, so editing DESIGN.family.md is the only change needed.
+export const DESIGN_BEGIN = "<!-- BEGIN ctl-shared-design v1 -->";
+export const DESIGN_END = "<!-- END ctl-shared-design v1 -->";
+const DESIGN_SOURCE = "@norskvideo/ctl-dev-kit conventions/DESIGN.family.md";
+
+export function designDocs(repoRoot: string): string[] {
+  const dir = join(repoRoot, "dashboards");
+  if (!existsSync(dir) || !statSync(dir).isDirectory()) return [];
+  return readdirSync(dir, { withFileTypes: true })
+    .filter((d) => d.isDirectory() && existsSync(join(dir, d.name, "DESIGN.md")))
+    .map((d) => `dashboards/${d.name}/DESIGN.md`)
+    .sort();
+}
+
+const PALETTE_ROW = /^\|\s*`([a-z0-9-]+)`\s*\|\s*`([^`]+)`\s*\|/gm;
+
+export function sharedPalette(canonicalDesign: string): Map<string, string> {
+  return new Map([...canonicalDesign.matchAll(PALETTE_ROW)].map((m) => [m[1] as string, m[2] as string]));
+}
+
+const unquote = (v: string): string => {
+  const m = /^(["'])(.*)\1(\s+#.*)?$/.exec(v);
+  return m ? (m[2] as string) : v;
+};
+
+// Just enough YAML for a flat `colors:` map in the leading frontmatter: no
+// dependency, since this script ships to products and runs from node_modules.
+export function frontmatterColors(text: string): Map<string, string> | undefined {
+  const lines = text.split("\n");
+  if (lines[0]?.trim() !== "---") return undefined;
+  const close = lines.findIndex((l, i) => i > 0 && l.trim() === "---");
+  if (close === -1) return undefined;
+  const start = lines.findIndex((l, i) => i < close && /^colors:\s*$/.test(l));
+  if (start === -1) return undefined;
+  const colors = new Map<string, string>();
+  for (const line of lines.slice(start + 1, close)) {
+    if (line.trim() === "") continue;
+    if (!/^\s/.test(line)) break;
+    const m = /^\s+([A-Za-z0-9_-]+):\s*(.*?)\s*$/.exec(line);
+    if (m) colors.set(m[1] as string, unquote(m[2] as string));
+  }
+  return colors;
+}
+
+function designBlockProblem(rel: string, text: string, canonicalDesign: string): string | undefined {
+  if (text.includes(canonicalDesign.trimEnd())) return undefined;
+  const begin = text.indexOf(DESIGN_BEGIN);
+  const end = text.indexOf(DESIGN_END);
+  if (begin === -1 || end === -1 || end < begin) {
+    return `${rel} is missing the '${DESIGN_BEGIN}' / '${DESIGN_END}' marker block. Copy conventions/DESIGN.family.md from @norskvideo/ctl-dev-kit verbatim between the markers.`;
+  }
+  const region = text.slice(begin, end + DESIGN_END.length);
+  return `${rel} fenced family design block has drifted from ${DESIGN_SOURCE} (${firstDiffLine(region, canonicalDesign.trimEnd())}). ${RESYNC}`;
+}
+
+function paletteProblems(rel: string, text: string, canonicalDesign: string): string[] {
+  const expected = sharedPalette(canonicalDesign);
+  if (expected.size === 0) throw new Error("canonical DESIGN.family.md has no shared palette table");
+  const colors = frontmatterColors(text);
+  if (colors === undefined) {
+    return [
+      `${rel} has no frontmatter colors: map; it must carry the shared palette tokens (${[...expected.keys()].join(", ")}) from ${DESIGN_SOURCE}.`,
+    ];
+  }
+  const problems: string[] = [];
+  for (const [token, want] of expected) {
+    const got = colors.get(token);
+    if (got === undefined || got === "") {
+      problems.push(
+        `${rel} frontmatter colors: has no \`${token}\` — the shared palette in ${DESIGN_SOURCE} sets it to ${JSON.stringify(want)}.`,
+      );
+    } else if (got.toLowerCase() !== want.toLowerCase()) {
+      problems.push(
+        `${rel} frontmatter colors.${token} is ${JSON.stringify(got)}, but the shared palette in ${DESIGN_SOURCE} sets it to ${JSON.stringify(want)}. Status and neutral tokens are the family's; only accent tokens are the console's own.`,
+      );
+    }
+  }
+  return problems;
+}
+
+export function designProblems(repoRoot: string, canonicalDesign: string): string[] {
+  return designDocs(repoRoot).flatMap((rel) => {
+    const text = readFileSync(join(repoRoot, rel), "utf8");
+    const block = designBlockProblem(rel, text, canonicalDesign);
+    return [...(block ? [block] : []), ...paletteProblems(rel, text, canonicalDesign)];
+  });
+}
+
 export interface CanonicalBytes {
   core: string;
   /** build/flake.nix — the starter flake a Studio product begins from, and what
@@ -316,6 +410,10 @@ export interface CanonicalBytes {
    *  pins step has no Studio pair or manifest.seed.json, and bumps the norsk
    *  family off the SDK nightly. Optional for the same reason as flakeSdkApp. */
   bumpSdkApp?: string;
+  /** conventions/DESIGN.family.md -- the family design block each
+   *  dashboards/<name>/DESIGN.md embeds between DESIGN_BEGIN/DESIGN_END, whose
+   *  palette table its frontmatter colors: must match. */
+  design: string;
 }
 
 export const SERVER_KIT_COPIES = [
@@ -927,6 +1025,7 @@ export function checkDrift(repoRoot: string, canonical: CanonicalBytes, opts: Ch
   for (const p of productLogsProblems(repoRoot)) push(p);
   for (const p of bunVersionProblems(repoRoot, canonical.ctlShell)) push(p);
   for (const p of ctlPinProblems(repoRoot)) push(p);
+  for (const p of designProblems(repoRoot, canonical.design)) push(p);
 
   return { ok: problems.length === 0, problems };
 }
@@ -958,6 +1057,7 @@ if (import.meta.main) {
     flakeSdkApp: readFileSync(join(import.meta.dir, "..", "build", "flake.sdk-app.nix"), "utf8"),
     checksSdkApp: readFileSync(join(import.meta.dir, "checks.sdk-app.yml"), "utf8"),
     bumpSdkApp: readFileSync(join(import.meta.dir, "bump.sdk-app.yml"), "utf8"),
+    design: readFileSync(join(import.meta.dir, "DESIGN.family.md"), "utf8"),
   };
   const report = checkDrift(repoRoot, canonical, {
     repoName: resolveRepoName(repoRoot),

package/conventions/sync-drift.ts

@@ -15,7 +15,8 @@
 //                                                       sync-ctl-packages) are DELETED
 //   - nix/ctl-shell.nix                              -> overwrite with canonical (created if absent)
 //   - flake.nix (legacy verbatim copy only)          -> the starter, repo's floating ctl pin kept
-//   - marker-block (CLAUDE core, dprint, .gitignore) -> replace the shared block, keep the rest
+//   - marker-block (CLAUDE core, dprint, .gitignore, -> replace the shared block, keep the rest
+//     dashboards/*/DESIGN.md family block)            (DESIGN.md: appended where absent)
 //   - publish-docs-site.yml                          -> verbatim; CREATED where the repo has a
 //                                                       docs site and is not a turnkey
 // Structural per-repo files (root tsconfig.json, deployment/build-image.sh,
@@ -37,8 +38,11 @@ import {
   CTL_SHELL_PATH,
   CTL_VERSION_LINE,
   carriesIntegrationMarker,
+  DESIGN_BEGIN,
+  DESIGN_END,
   DOCS_SITE_DIR,
   DOCS_SITE_WORKFLOW,
+  designDocs,
   END,
   GITIGNORE_BEGIN,
   GITIGNORE_END,
@@ -285,6 +289,20 @@ function syncClaude(repoRoot: string, core: string, r: SyncReport): void {
   writeIfChanged(path, out, "CLAUDE.md", r.written);
 }
 
+// dashboards/<name>/DESIGN.md: the family design block is fenced like the CLAUDE
+// core; a console that has none yet gets it appended. The frontmatter palette is
+// the product's to fix (the gate names each token), so it is never rewritten.
+function syncDesign(repoRoot: string, design: string, r: SyncReport): void {
+  for (const rel of designDocs(repoRoot)) {
+    const path = join(repoRoot, rel);
+    const existing = readFileSync(path, "utf8");
+    const out =
+      replaceMarkerBlock(existing, DESIGN_BEGIN, DESIGN_END, design) ??
+      `${existing.replace(/\n*$/, "\n\n")}${design.trimEnd()}\n`;
+    writeIfChanged(path, out, rel, r.written);
+  }
+}
+
 // .gitignore: the shared block is marker-delimited; repo-specific ignores live
 // outside it. Replace the block, or prepend it if the repo has none yet (the
 // one-time migration case).
@@ -489,6 +507,7 @@ export function syncDrift(
   syncPackageManager(repoRoot, canonical.ctlShell, r);
   syncFlake(repoRoot, flakeCanon, r);
   syncClaude(repoRoot, canonical.core, r);
+  syncDesign(repoRoot, canonical.design, r);
   syncGitignore(repoRoot, canonical.gitignoreCore, r);
   syncDprint(repoRoot, canonical.dprint, r);
   syncDemoShim(repoRoot, canonical.demoShim, r);
@@ -528,6 +547,7 @@ if (import.meta.main) {
     flakeSdkApp: readFileSync(join(dir, "..", "build", "flake.sdk-app.nix"), "utf8"),
     checksSdkApp: readFileSync(join(dir, "checks.sdk-app.yml"), "utf8"),
     bumpSdkApp: readFileSync(join(dir, "bump.sdk-app.yml"), "utf8"),
+    design: readFileSync(join(dir, "DESIGN.family.md"), "utf8"),
   };
   const report = syncDrift(repoRoot, canonical, resolveShape(repoRoot), { repoName: resolveRepoName(repoRoot) });
   if (report.written.length === 0) {

package/create-demo/create-demo.ts

@@ -0,0 +1,191 @@
+// `ctl-dev-kit create-demo` — renders a new customer demo repo: a Studio
+// working directory, the scripts that install it into norsk-ctl, and the docs
+// that make every demo look the same. Unlike create-product, the output is
+// copied once and then owned by the customer: there is no drift gate, no CI and
+// no canonical bytes to stay in step with.
+//
+// The files live under template/ as real files, with `__DEMO__` where the demo's
+// name goes, so they can be read and edited as what they are:
+//   template/core/       every demo
+//   template/<feature>/  added by --with <feature>
+// Markdown is kept as `<name>.md.tmpl` and emitted as `<name>.md`: as a .md the
+// repo's formatter would rewrite it (`__DEMO__` becomes bold, and the feature
+// markers split its tables). It may carry `<!-- if:<feature> -->` ...
+// `<!-- end:<feature> -->` blocks, kept when that feature is on and dropped
+// when it is off. `gitignore` is emitted as `.gitignore`: npm drops a
+// .gitignore from a published package.
+//
+// The components feature is not a template: it is create-product's components/
+// workspace (its build chain and example node), without the product glue.
+import { mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join, relative } from "node:path";
+import { type GeneratedFile, shapeContext } from "../create-product/create-product.ts";
+import { componentsWorkspaceFiles, EXAMPLE_IDENTIFIER } from "../create-product/features/components.ts";
+
+// - dashboard   an operator dashboard, built into the workflow's dashboards/
+//               and served by Studio at /dashboard/<name>/
+// - components  this demo's own Studio nodes, built into the working dir's
+//               components/, where norsk-ctl finds and mounts them
+export type DemoFeature = "dashboard" | "components";
+
+const ALL_FEATURES: readonly DemoFeature[] = ["dashboard", "components"];
+
+export interface CreateDemoOptions {
+  /** The demo's name: its workflow, its norsk-ctl instance and its library scope. */
+  name: string;
+  /** Whose `.ai/<user>/tasks/` the seeded task file goes in. */
+  user: string;
+  withFeatures?: DemoFeature[];
+}
+
+const TOKEN = "__DEMO__";
+const TEMPLATE_DIR = join(import.meta.dir, "template");
+
+function resolveFeatures(names: DemoFeature[] | undefined): Set<DemoFeature> {
+  for (const name of names ?? []) {
+    if (!ALL_FEATURES.includes(name)) {
+      throw new Error(`unknown feature ${JSON.stringify(name)} in --with — features: ${ALL_FEATURES.join(", ")}.`);
+    }
+  }
+  return new Set(names ?? []);
+}
+
+function* walk(dir: string): Generator<string> {
+  for (const entry of readdirSync(dir).sort()) {
+    const full = join(dir, entry);
+    if (statSync(full).isDirectory()) yield* walk(full);
+    else yield full;
+  }
+}
+
+function featureBlocks(text: string, features: ReadonlySet<DemoFeature>): string {
+  return text.replace(/^<!-- if:(\w+) -->\n([\s\S]*?)^<!-- end:\1 -->\n/gm, (_, feature: DemoFeature, body: string) =>
+    features.has(feature) ? body : "",
+  );
+}
+
+function templateFiles(layer: string, name: string, features: ReadonlySet<DemoFeature>): GeneratedFile[] {
+  const root = join(TEMPLATE_DIR, layer);
+  return [...walk(root)].map((full) => {
+    const rel = relative(root, full);
+    const markdown = rel.endsWith(".md.tmpl");
+    const emitted = rel === "gitignore" ? ".gitignore" : markdown ? rel.slice(0, -".tmpl".length) : rel;
+    const raw = readFileSync(full, "utf8");
+    const path = emitted.replaceAll(TOKEN, name);
+    const content = (markdown ? featureBlocks(raw, features) : raw).replaceAll(TOKEN, name);
+    return { path, content, executable: /^(ctl|scripts)\/.*\.sh$/.test(path) };
+  });
+}
+
+function workflowYaml(name: string, features: ReadonlySet<DemoFeature>): string {
+  const example = features.has("components")
+    ? `
+  # The placeholder from components/: it carries no media, publishes a heartbeat
+  # and serves /status. Delete it, and components/src/library/example/, once a
+  # real component exists.
+  - type: ${EXAMPLE_IDENTIFIER}
+    config:
+      id: example
+      displayName: Example
+      heartbeatMs: 1000
+    subscriptions: []
+`
+    : "";
+  const exampleLayout = features.has("components") ? "  - { id: example, x: 480, y: 300 }\n" : "";
+  return `# ${name}: the starter workflow.
+#
+# srt_in ─► preview
+#
+# srt_in is an SRT listener for a camera or an encoder to send to
+# (scripts/test-feed.sh sends a test picture). preview is a still of its
+# picture, which Studio's editor and the dashboard show. Replace this with the
+# demo's real graph, keeping the comments and the __layout block in step.
+#
+# Site settings (ports, passphrases, destinations) are not set here: they come
+# from ctl/studio.env as Studio environment overrides, <ID>_<FIELD>.
+components:
+  - type: input.srt-listener
+    config:
+      id: srt_in
+      displayName: SRT In
+      # Published on the host by HOST_PORTS in ctl/site.env; change both together.
+      port: 5001
+      host: 0.0.0.0
+      sourceNames: permissive
+      streamIds: [camera]
+    subscriptions: []
+  - type: output.preview
+    config:
+      id: preview
+      displayName: Preview
+      # A JPEG, refreshed: it needs no media ports, so it works in norsk-ctl's
+      # docker network mode. moq mode gives live video the same way.
+      previewMode: image
+      showPreview: true
+    subscriptions:
+      - source: srt_in
+        streams: { type: take-first-stream, filter: [{ media: video }] }
+${example}__layout:
+  - { id: srt_in, x: 0, y: 0 }
+  - { id: preview, x: 480, y: 0 }
+${exampleLayout}`;
+}
+
+function taskFile(name: string, features: ReadonlySet<DemoFeature>): string {
+  const withs = features.size > 0 ? ` --with ${[...features].join(",")}` : "";
+  return `# ${name} demo
+
+**Started:** generated by \`ctl-dev-kit create-demo --name ${name}${withs}\`.
+
+## STATUS (current)
+
+Scaffold only: the starter workflow (SRT in, image preview) installs and runs.
+Nothing demo-specific is built yet.
+
+### Open / not done
+- TODO: what the customer asked to see.
+
+## Brief
+
+TODO: who the customer is, what the demo must show, when and where it is shown,
+and what they take away afterwards.
+
+## Decisions
+
+| Decision | Status | Outcome |
+|---|---|---|
+
+## Log
+`;
+}
+
+export function planDemo(opts: CreateDemoOptions): GeneratedFile[] {
+  // An instance id, a workflow file name and an npm scope all at once.
+  if (!/^[a-z][a-z0-9-]{0,39}$/.test(opts.name)) {
+    throw new Error(
+      `invalid demo name ${JSON.stringify(opts.name)} — a lowercase letter, then lowercase letters, digits and hyphens; 1-40 chars (it names the norsk-ctl instance, the workflow and the components' npm scope).`,
+    );
+  }
+  const features = resolveFeatures(opts.withFeatures);
+  const { name } = opts;
+  const files = [
+    ...templateFiles("core", name, features),
+    { path: `workdir/studio-save-files/${name}/${name}.yaml`, content: workflowYaml(name, features) },
+    { path: `.ai/${opts.user}/tasks/${name}-demo.md`, content: taskFile(name, features) },
+  ];
+  if (features.has("dashboard")) files.push(...templateFiles("dashboard", name, features));
+  if (features.has("components")) {
+    files.push(...componentsWorkspaceFiles(shapeContext({ dir: "", name, shape: "backend-turnkey" })));
+  }
+  return files;
+}
+
+export function createDemo(opts: CreateDemoOptions & { dir: string }): { files: string[] } {
+  const plan = planDemo(opts);
+  for (const file of plan) {
+    const path = join(opts.dir, file.path);
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, file.content, { mode: file.executable ? 0o755 : 0o644 });
+  }
+  return { files: plan.map((f) => f.path) };
+}

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

@@ -0,0 +1,158 @@
+# __DEMO__: a Norsk Studio demo
+
+This repo is a customer demo: a Studio workflow, plus what it needs around it,
+built by us, shown to the customer, then handed over for them to develop. It is
+not a product: there is no CI, no drift gate and no test tiers, and after
+handover the customer owns every file in it. Keep it small enough that someone
+new to Norsk can read the whole thing.
+
+It was generated by `ctl-dev-kit create-demo`, so its layout matches every other
+demo. Keep to it: anyone in the team should be able to pick this up and find
+things where they expect.
+
+## Layout
+
+| Path                                               | What it is                                                                                                 |
+| -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| `workdir/`                                         | The Studio working directory, staged as-is on the box and mounted at `/data`                               |
+| `workdir/studio-save-files/__DEMO__/__DEMO__.yaml` | The workflow. Hand-edited and commented; the `__layout` block places nodes in the editor                   |
+| `ctl/`                                             | Installing into norsk-ctl: `install.sh`, `push.sh`, `mode.sh`, the shared `lib.sh` and the site's settings |
+| `scripts/build.sh`                                 | Builds what the demo adds to Studio into `workdir/`                                                        |
+| `scripts/test-feed.sh`                             | `up`/`down` a test picture into the SRT input                                                              |
+<!-- if:dashboard -->
+| `dashboard/` | The operator dashboard, a vite app Studio serves at `/dashboard/__DEMO__/` |
+<!-- end:dashboard -->
+<!-- if:components -->
+| `components/` | This demo's own Studio nodes, the `@__DEMO__/library` library |
+<!-- end:components -->
+| `README.md` | The customer's handover document. Keep it true as the demo changes |
+| `.ai/<user>/tasks/` | Task files: what was asked, what was decided, what is left |
+
+## How it runs
+
+norsk-ctl is the only run path, here and on the customer's box. ctl provides
+TLS, ports and Studio's config, so this repo has no compose file, proxy or certs.
+The demo is one instance, `__DEMO__`, launched from the `studio-dev` product
+template with `workdir/` as its working directory.
+
+1. `cp ctl/site.example.env ctl/site.env` and `cp ctl/studio.example.env ctl/studio.env`, then fill them in.
+   `site.env` says where the demo runs (here, or `DEMO_HOST=user@box`); `studio.env` holds the workflow's
+   site settings.
+2. `ctl/install.sh` the first time. It builds, stages `workdir/` at `WORKDIR` owned by the norsk-ctl
+   user, and launches the instance.
+3. `ctl/push.sh` after every change. It builds, syncs, relaunches and waits until Studio is up.
+4. `ctl/mode.sh editor` to change the workflow in Studio's editor; `ctl/mode.sh document` to put it back
+   to running on start.
+5. `scripts/test-feed.sh up` for a picture without a camera.
+
+The scripts print the Studio URL. The same scripts serve a local norsk-ctl and
+the customer's box, so what is shown is what was tested.
+
+A customer who wants the demo out of norsk-ctl uses
+`norsk-ctl instance export __DEMO__ --to <dir>`, which writes a compose bundle
+with its own `HANDOVER.md`. It refuses a different compose project name (`-p`),
+and it has no proxy: the deployer supplies `NORSK_PUBLIC_BASE_URL` and a
+reverse proxy for `/instance/__DEMO__/studio`.
+
+## Working rules
+
+- **The YAML is the source.** Edit `__DEMO__.yaml` by hand, keep its comments,
+  and keep `__layout` in step when nodes are added. Saving from Studio's editor
+  strips comments and `__layout`; if a change was made there, copy the shape
+  back by hand rather than committing the editor's file.
+- **Site settings are not in the YAML.** Ports, passphrases and destinations go
+  in `ctl/studio.env` as `<COMPONENT_ID>_<FIELD>=value`, for fields the
+  component declares overridable. A `${VAR}` in a YAML value fails validation.
+- **Component ids are an interface.** The dashboard, `studio.env` and the README
+  all name them. Rename one everywhere or not at all.
+- **Ports:** let norsk-ctl allocate them. Pin one in `HOST_PORTS` only when a
+  sender or a firewall outside the box must agree on it. On a shared box, never
+  stop another instance's containers.
+- **Push, then check.** After `ctl/push.sh`, open the URL it prints and look:
+  a relaunch that came up is not a workflow that works.
+- **The README is the handover.** When something changes what the customer
+  sees or does, change the README in the same commit.
+
+## Gotchas
+
+- Under norsk-ctl the working dir must be owned by the norsk-ctl user, and on a
+  path it can reach: `/srv/__DEMO__`, not a home directory.
+- `STUDIO_DOCUMENT` does nothing under norsk-ctl, which writes Studio's config
+  itself. The document comes from `NODE_CONFIG` in the overrides, which is what
+  `ctl/mode.sh` switches.
+- `NODE_CONFIG` replaces the library list norsk-ctl writes, so the overrides
+  name every library. `ctl/lib.sh` does this; keep it if you edit it.
+- A fixed document hides the editor's Stop button. Use `ctl/mode.sh editor`.
+- Studio's `/api/files` refuses to overwrite: a write is DELETE then POST.
+- Put a `processor.smartSourceSwitch` with a fallback after inputs, or a source
+  dropping resets HLS. Silence-fill audio that comes and goes, so nothing
+  renegotiates.
+- A WHEP return carries one audio stream; WHIP clients should DELETE the
+  session on pagehide.
+- WebRTC media (WHEP, WHIP) to a viewer needs `NETWORK_MODE=hybrid`. MoQ and
+  image previews work in docker mode.
+- The microphone and MoQ/WebTransport need HTTPS. norsk-ctl serves HTTPS.
+- Studio's COOP header stops a Studio-served page painting in a
+  `processor.browserOverlay`: use `--disable-features=CrossOriginOpenerPolicy`
+  in `customCefArgs`, or a `file:///data/...` URL.
+- Headless browser tests need Debian's chromium: Playwright's own build has no
+  H.264.
+
+<!-- if:dashboard -->
+
+## Dashboard
+
+`dashboard/` is a vite + React app with one page per HTML entry. `scripts/build.sh`
+builds it into `workdir/studio-save-files/__DEMO__/dashboards/`, and Studio serves
+that at `/dashboard/__DEMO__/` beside the workflow. A top-level
+`workdir/dashboards/` is not served.
+
+- `src/lib/workflow.ts` is the one place the dashboard names component ids.
+  Keep it in step with the YAML.
+- Each page fetches `./env` for `apiBasePath` and `wsBasePath`, so it works
+  under any URL prefix. Never hard-code `/live` or a host.
+- The hooks are the dashboard's whole Studio API:
+  - `useEnv`: the env.
+  - `useDiscovery`: the running components, polled until the workflow is up.
+  - `useLiveComponent`: a component's state over its websocket, with
+    reconnect, and `sendCommand`.
+  - `useAlerts`: a component's alerts, polled.
+- The starter preview is `output.preview` in image mode: a JPEG URL in the
+  component's state. For live video, switch the preview to `moq` mode and use a
+  MoQ player; livemode and eurovision have one (`moq-player.tsx`).
+- `bun run dev` serves the pages with Studio's routes proxied to `STUDIO_URL`,
+  which must be a Studio reachable without the sign-in proxy in front.
+<!-- end:dashboard -->
+<!-- if:components -->
+
+## Custom components
+
+`components/` is this demo's own Studio library, `@__DEMO__/library`, with one
+placeholder node, `output.example`. `scripts/build.sh` builds it and copies
+`lib/library/` to `workdir/components/@__DEMO__/library/`. norsk-ctl finds
+packages under the working dir's `components/` and mounts them, and the
+overrides name the library, so Studio loads it.
+
+- A component is a directory under `src/library/` with `info.ts` (design time:
+  config form, subscriptions), `runtime.ts` (the media nodes and routes) and
+  `types.source.yaml` (the schema; `_gen/types.ts` is generated from it). Adding
+  one is adding a directory: `index.ts` registers every one it finds.
+- The build order is load-bearing: codegen, then tsc to CommonJS, then
+  `copy-yamls.ts`, which writes `types.yaml` beside each runtime and a browser
+  bundle of `info.ts`. That bundle must not import react or `@norskvideo/*` as
+  bare specifiers; `info-client-externals.test.ts` checks it.
+- Publish a component's state from its constructor: Studio refuses websocket
+  connections while a state is undefined.
+- Keep the pure logic in sibling modules, testable with `bun test` and no Studio.
+- Delete `example/` (and its node in the YAML) once a real component exists.
+<!-- end:components -->
+
+## Handover
+
+Before the customer takes it:
+
+- The README is complete: install, URLs, the workflow block by block, how to
+  change it, what it does not do, versions, and how to take it out of norsk-ctl.
+- `ctl/site.example.env` and `ctl/studio.example.env` describe every setting.
+- The task file says what was shown and what is left.
+- Nothing in the repo is a site's secret.