@norskvideo/ctl-test-harness 0.1.20 → 0.1.22

package/compose-advancing.d.ts

@@ -0,0 +1,26 @@
+export type FetchLike = (url: string, init?: RequestInit) => Promise<Response>;
+export declare const DEFAULT_COMPOSE_NODE = "video_compose";
+/** The highest mediaIn across every node of that name; 0 when none. */
+export declare function maxNodeMediaIn(summary: unknown, node: string): number;
+/** One sample: the highest mediaIn of `node` across every root workflow under
+ *  `base` (`.../visualiser`). An unreachable visualiser reads as 0 — the
+ *  caller's second sample, not a throw, decides. */
+export declare function composeFrames(opts: {
+    fetch: FetchLike;
+    base: string;
+    node?: string;
+}): Promise<number>;
+export interface ComposeAdvancingResult {
+    advancing: boolean;
+    before: number;
+    after: number;
+    node: string;
+}
+/** Two samples `settleMs` apart: advancing when the second is above the first
+ *  and above zero — the fallback card and a stalled feed both read flat. */
+export declare function composeAdvancing(opts: {
+    fetch: FetchLike;
+    base: string;
+    node?: string;
+    settleMs?: number;
+}): Promise<ComposeAdvancingResult>;

package/compose-advancing.js

@@ -0,0 +1,61 @@
+// Is a programme really reaching the compositor? The daemon reports a source
+// "running" as soon as its ffmpeg sidecar is up, even if the SRT never
+// connected or the frames stalled; the only honest signal is the compose
+// node's own mediaIn climbing between two samples of the engine's visualiser
+// (`/visualiser/workflow` -> rootWorkflows[].wfid -> `/workflow/<wfid>/summary`
+// -> nodes[].mediaIn). Playout's scripts/ensure-sources.sh:52-64 as TypeScript
+// (05-demo s7 step 2), pure over an injected fetch so it is unit-tested and
+// reachable through whichever base the caller has: the daemon proxy's
+// `/instance/<id>/visualiser`, or `<id>-media-1:6791/visualiser` on norsk-net.
+export const DEFAULT_COMPOSE_NODE = "video_compose";
+const DEFAULT_SETTLE_MS = 6000;
+/** The highest mediaIn across every node of that name; 0 when none. */
+export function maxNodeMediaIn(summary, node) {
+    const nodes = summary?.nodes;
+    if (!Array.isArray(nodes))
+        return 0;
+    let max = 0;
+    for (const n of nodes) {
+        if (n?.name !== node)
+            continue;
+        const v = Number(n.mediaIn);
+        if (Number.isFinite(v) && v > max)
+            max = v;
+    }
+    return max;
+}
+async function getJson(fetch, url) {
+    const r = await fetch(url, { signal: AbortSignal.timeout(5000) });
+    if (!r.ok)
+        throw new Error(`GET ${url} -> ${r.status}`);
+    return r.json();
+}
+/** One sample: the highest mediaIn of `node` across every root workflow under
+ *  `base` (`.../visualiser`). An unreachable visualiser reads as 0 — the
+ *  caller's second sample, not a throw, decides. */
+export async function composeFrames(opts) {
+    const node = opts.node ?? DEFAULT_COMPOSE_NODE;
+    try {
+        const wf = (await getJson(opts.fetch, `${opts.base}/workflow`));
+        let max = 0;
+        for (const root of wf?.rootWorkflows ?? []) {
+            if (typeof root?.wfid !== "string")
+                continue;
+            const summary = await getJson(opts.fetch, `${opts.base}/workflow/${encodeURIComponent(root.wfid)}/summary`);
+            max = Math.max(max, maxNodeMediaIn(summary, node));
+        }
+        return max;
+    }
+    catch {
+        return 0;
+    }
+}
+/** Two samples `settleMs` apart: advancing when the second is above the first
+ *  and above zero — the fallback card and a stalled feed both read flat. */
+export async function composeAdvancing(opts) {
+    const node = opts.node ?? DEFAULT_COMPOSE_NODE;
+    const before = await composeFrames({ fetch: opts.fetch, base: opts.base, node });
+    await new Promise((r) => setTimeout(r, opts.settleMs ?? DEFAULT_SETTLE_MS));
+    const after = await composeFrames({ fetch: opts.fetch, base: opts.base, node });
+    return { advancing: after > before && after > 0, before, after, node };
+}

package/container-logs.d.ts

@@ -0,0 +1,48 @@
+export interface SpawnResult {
+    stdout: string;
+    stderr: string;
+    error?: Error;
+}
+export type SpawnLike = (cmd: string, args: string[], opts: {
+    encoding: "utf8";
+    timeout: number;
+}) => SpawnResult;
+/** `docker ps` argv listing "<name>\t<state>" for ONE instance's containers. */
+export declare function instanceContainersArgs(instanceId: string): string[];
+/** `docker logs` argv tailing one container. Combined stdout+stderr at the call site. */
+export declare function containerLogArgs(container: string, tail?: number): string[];
+export interface ContainerLog {
+    name: string;
+    state: string;
+    log: string;
+}
+/** Parse `docker ps --format "{{.Names}}\t{{.State}}"` output into rows. */
+export declare function parseContainerRows(psStdout: string): {
+    name: string;
+    state: string;
+}[];
+/** Pure: renders captured logs as an indented block per container. */
+export declare function formatContainerLogs(instanceId: string, entries: ContainerLog[]): string;
+/** Tail every container of one instance. Best-effort: docker unreachable is
+ *  an empty list, never a throw, so a diagnostic cannot mask what it describes. */
+export declare function collectInstanceContainerLogs(instanceId: string, tail?: number, spawn?: SpawnLike): ContainerLog[];
+/** The ready-to-print diagnostic block (empty-marker when nothing is found). */
+export declare function dumpInstanceContainerLogs(instanceId: string, tail?: number, spawn?: SpawnLike): string;
+export interface LogHit {
+    container: string;
+    line: string;
+}
+/** A string forbids a substring; a RegExp is tested per line. */
+export type LogPattern = string | RegExp;
+/** Every line, in any container of the instance, that matches a forbidden
+ *  pattern. `clean` when there are none — including when docker cannot be
+ *  reached, which is absence of evidence, not a failure of the thing probed. */
+export declare function containerLogsClean(opts: {
+    instanceId: string;
+    forbid: readonly LogPattern[];
+    tail?: number;
+    spawn?: SpawnLike;
+}): {
+    clean: boolean;
+    hits: LogHit[];
+};

package/container-logs.js

@@ -0,0 +1,101 @@
+// A launched instance's container logs, by the `norsk-ctl.instance=<id>`
+// label every per-instance container carries (norsk-ctl docker/constants.ts)
+// — so it finds them under either naming scheme (`<id>-media-1` on the
+// released ctl, `norsk-inst-<id>-media` on older ones). Lifted from funke's
+// tests/integration/support/container-logs.ts (05-demo s7 step 2): the
+// diagnostic dump, plus containerLogsClean — iterate.sh's segfault guard
+// generalised to "no forbidden line in any container of this instance".
+// Pure argv/parse/format helpers; only the two exported probes shell out,
+// through an injectable spawn.
+import { spawnSync } from "node:child_process";
+const defaultSpawn = (cmd, args, opts) => {
+    const r = spawnSync(cmd, args, opts);
+    return {
+        stdout: typeof r.stdout === "string" ? r.stdout : "",
+        stderr: typeof r.stderr === "string" ? r.stderr : "",
+        ...(r.error ? { error: r.error } : {}),
+    };
+};
+const DEFAULT_TAIL = 80;
+/** `docker ps` argv listing "<name>\t<state>" for ONE instance's containers. */
+export function instanceContainersArgs(instanceId) {
+    return ["ps", "-a", "--filter", `label=norsk-ctl.instance=${instanceId}`, "--format", "{{.Names}}\t{{.State}}"];
+}
+/** `docker logs` argv tailing one container. Combined stdout+stderr at the call site. */
+export function containerLogArgs(container, tail = DEFAULT_TAIL) {
+    return ["logs", "--tail", String(tail), container];
+}
+/** Parse `docker ps --format "{{.Names}}\t{{.State}}"` output into rows. */
+export function parseContainerRows(psStdout) {
+    return psStdout
+        .split("\n")
+        .map((l) => l.trim())
+        .filter(Boolean)
+        .map((l) => {
+        const [name, state] = l.split("\t");
+        return { name: name ?? "?", state: state ?? "?" };
+    });
+}
+/** Pure: renders captured logs as an indented block per container. */
+export function formatContainerLogs(instanceId, entries) {
+    if (entries.length === 0) {
+        return `  container logs for ${instanceId}: <none found / docker unreachable>`;
+    }
+    return entries
+        .map((e) => {
+        const body = e.log.trim() === ""
+            ? "    <empty>"
+            : e.log
+                .trimEnd()
+                .split("\n")
+                .map((l) => `    ${l}`)
+                .join("\n");
+        return `  --- ${e.name} (${e.state}) ---\n${body}`;
+    })
+        .join("\n");
+}
+/** Tail every container of one instance. Best-effort: docker unreachable is
+ *  an empty list, never a throw, so a diagnostic cannot mask what it describes. */
+export function collectInstanceContainerLogs(instanceId, tail = DEFAULT_TAIL, spawn = defaultSpawn) {
+    let rows = [];
+    try {
+        const ps = spawn("docker", instanceContainersArgs(instanceId), { encoding: "utf8", timeout: 15_000 });
+        if (ps.error)
+            return [];
+        rows = parseContainerRows(ps.stdout);
+    }
+    catch {
+        return [];
+    }
+    const entries = [];
+    for (const row of rows) {
+        let log = "";
+        try {
+            const r = spawn("docker", containerLogArgs(row.name, tail), { encoding: "utf8", timeout: 15_000 });
+            log = r.error ? "<docker logs failed>" : `${r.stdout}${r.stderr}`;
+        }
+        catch {
+            log = "<docker logs failed>";
+        }
+        entries.push({ name: row.name, state: row.state, log });
+    }
+    return entries;
+}
+/** The ready-to-print diagnostic block (empty-marker when nothing is found). */
+export function dumpInstanceContainerLogs(instanceId, tail = DEFAULT_TAIL, spawn = defaultSpawn) {
+    return formatContainerLogs(instanceId, collectInstanceContainerLogs(instanceId, tail, spawn));
+}
+const matches = (pattern, line) => typeof pattern === "string" ? line.includes(pattern) : pattern.test(line);
+/** Every line, in any container of the instance, that matches a forbidden
+ *  pattern. `clean` when there are none — including when docker cannot be
+ *  reached, which is absence of evidence, not a failure of the thing probed. */
+export function containerLogsClean(opts) {
+    const hits = [];
+    for (const entry of collectInstanceContainerLogs(opts.instanceId, opts.tail ?? DEFAULT_TAIL, opts.spawn)) {
+        for (const line of entry.log.split("\n")) {
+            if (opts.forbid.some((p) => matches(p, line)))
+                hits.push({ container: entry.name, line });
+        }
+    }
+    return { clean: hits.length === 0, hits };
+}

package/demo/cli.d.ts

@@ -1,12 +1,22 @@
 #!/usr/bin/env bun
+import { type DevLoopOptions, type DevLoopResult } from "./dev-loop.js";
+import { type DemoUi, type PaneLayout } from "./panes.js";
 import { type DemoRunOptions, type DemoRunResult, demoPorts } from "./run.js";
-import type { DemoSpec } from "./spec.js";
+import type { DemoDaemonPolicy, DemoMode, DemoSpec } from "./spec.js";
 export interface DemoArgs {
-    action: "up" | "check" | "down" | "spec";
-    mode: "dev" | "standalone";
+    /** `dev-loop <action>`: the standalone tier's verbs. */
+    devLoop: boolean;
+    action: "up" | "check" | "down" | "spec" | "ui" | "refresh";
+    /** Absent: the spec's `mode`, else dev. */
+    mode?: DemoMode | "standalone";
+    daemon: DemoDaemonPolicy;
     exportOnly: boolean;
     json: boolean;
     spec: string;
+    /** `ui` only; zellij unless said. */
+    ui?: DemoUi;
+    /** Default: PUBLIC_HOST in the environment. */
+    publicHost?: string;
 }
 export declare function parseDemoArgs(argv: string[]): DemoArgs;
 export interface ResolvedSpecView {
@@ -27,6 +37,8 @@ export interface ResolvedSpecView {
     };
     launch?: DemoSpec["launch"];
     prerequisites?: DemoSpec["prerequisites"];
+    extras: string[];
+    beforeLaunch: boolean;
     sources: Array<{
         name: string;
         asset: NonNullable<DemoSpec["sources"]>[number]["asset"];
@@ -54,6 +66,7 @@ export interface ResolvedSpecView {
 export declare function resolvedSpecView(spec: DemoSpec, opts: {
     mode: string;
     slug?: string;
+    publicHost?: string;
 }): ResolvedSpecView;
 /** Everything `demoMain` touches, injectable so the dispatch is unit-tested. */
 export interface DemoCliIo {
@@ -66,6 +79,12 @@ export interface DemoCliIo {
         exportDir: string;
     }>;
     demoDown(product: string): Promise<void>;
+    runDevLoop(spec: DemoSpec, opts: DevLoopOptions): Promise<DevLoopResult>;
+    devLoopDown(product: string): Promise<void>;
+    /** Open the multiplexer on the rendered layout; returns its exit code. */
+    launchUi(ui: DemoUi, layout: PaneLayout): number;
+    /** For the standalone dirs (NORSK_DIR, STUDIO_DIR, TO, HOME). */
+    env?: Record<string, string | undefined>;
     stdout(line: string): void;
     stderr(line: string): void;
     abort?: AbortSignal;

package/demo/cli.js

@@ -9,34 +9,80 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
 };
 // `ctl-demo`, the bin behind every product's `bun run demo` (05-demo s4):
 //
-//   demo up      [--mode dev]                       launch, print the URLs, hold; Ctrl-C tears down
-//   demo check   [--mode dev]                       the same, then tear down and exit 0/1 (what CI runs)
+//   demo up      [--mode dev|image] [--daemon private|reuse]
+//                                                   launch, print the URLs, hold; Ctrl-C tears down
+//   demo check   [--mode dev|image]                 the same, then tear down and exit 0/1 (what CI runs)
 //   demo check   --mode standalone --export-only    build + export-workdir + every symlink resolves
 //   demo down                                       tear down what `up` recorded, from any shell
 //   demo spec    [--json]                           the resolved spec: ports, template, sources, URLs
+//   demo ui      [--ui zellij|tmux|none] [...]      the same in a multiplexer: a gate pane running `demo up`,
+//                                                   the instance's logs, a shell (05-demo s4 front-end 2)
+//   demo dev-loop up|refresh|down|ui                the full standalone tier (engine + Studio from source);
+//                                                   `ctl-dev-loop <verb>` is the same under a product's `bun run dev-loop`
 //
 // The spec is `tests/demo.spec.ts` in the cwd (`--spec <path>` otherwise), a
 // TypeScript module whose default export is `defineDemo({...})`. This runs
 // under bun only: the spec is TypeScript and so is every product's dev shell.
 import { resolve } from "node:path";
+import { devLoopDown, runDevLoop } from "./dev-loop.js";
+import { demoPaneList, devLoopPaneList, launchLayout, renderLayout, standaloneDirs, } from "./panes.js";
 import { demoDown, demoPorts, demoSlug, runDemo, runExportCheck, } from "./run.js";
-const USAGE = `usage: demo <up|check|down|spec> [--mode dev|standalone] [--export-only] [--json] [--spec <path>]
+const USAGE = `usage: demo <up|check|down|spec|ui> [--mode dev|image|standalone] [--daemon private|reuse] [--export-only] [--json]
+            [--ui zellij|tmux|none] [--public-host <host>] [--spec <path>]
+       demo dev-loop <up|refresh|down|ui> [--ui zellij|tmux|none] [--public-host <host>] [--spec <path>]
 
-  up                                  launch on a private daemon, print the URLs, hold (Ctrl-C tears down)
-  check                               up, then tear down and exit 0/1 — what CI runs
+  up                                  launch, print the URLs, hold (Ctrl-C tears down)
+  check                               up, then tear down and exit 0/1 — what CI runs, always on a private daemon
   check --mode standalone --export-only
                                       build the template, export the standalone workdir, assert every symlink resolves
   down                                tear down what \`up\` recorded
   spec [--json]                       print the resolved spec without launching anything
+  ui                                  open a multiplexer: a pane running \`up\`, the instance's logs, a shell
 
+  dev-loop up                         the standalone tier: private daemon + dev backend, template built from source,
+                                      workdir exported with the live-source links (NORSK_DIR, STUDIO_DIR, TO name the
+                                      engine and Studio checkouts and the workdir); holds
+  dev-loop refresh                    rebuild + re-export against the held \`up\` (after a component or dashboard edit)
+  dev-loop down                       end the held \`up\` from any shell; the workdir stays
+  dev-loop ui                         open a multiplexer: engine, \`dev-loop up\`, Studio, the sources (on Enter), a shell
+
+  --mode dev                          run the product from source (bun run dev) and add it by URL
+  --mode image                        add the built product image — the customer path
+  --daemon private                    a throwaway daemon on its own store (default)
+  --daemon reuse                      your listening daemon and real store; the driver deletes the instance,
+                                      removes the template and product, then adds again (stored templates
+                                      are immutable by name)
+  --ui zellij|tmux|none               the multiplexer (\`none\` prints the pane commands); zellij unless said
+  --public-host <host>                the name other machines reach this box by: every URL, the daemon's
+                                      publicHost, Studio's MoQ preview (default: PUBLIC_HOST)
   --spec <path>                       the demo spec (default tests/demo.spec.ts)`;
 const DEFAULT_SPEC = "tests/demo.spec.ts";
+const DEMO_ACTIONS = ["up", "check", "down", "spec", "ui"];
+const DEV_LOOP_ACTIONS = ["up", "refresh", "down", "ui"];
 export function parseDemoArgs(argv) {
-    const [action, ...rest] = argv;
-    if (action !== "up" && action !== "check" && action !== "down" && action !== "spec") {
+    const devLoop = argv[0] === "dev-loop";
+    const [action, ...rest] = devLoop ? argv.slice(1) : argv;
+    const actions = devLoop ? DEV_LOOP_ACTIONS : DEMO_ACTIONS;
+    if (action === undefined || !actions.includes(action)) {
+        if (devLoop)
+            throw new Error(`dev-loop takes one of up|refresh|down|ui${action ? `, not '${action}'` : ""}\n${USAGE}`);
+        if (action === "refresh")
+            throw new Error(`refresh is the dev-loop's: \`dev-loop refresh\`\n${USAGE}`);
         throw new Error(action ? `unknown action '${action}'\n${USAGE}` : USAGE);
     }
-    const args = { action, mode: "dev", exportOnly: false, json: false, spec: DEFAULT_SPEC };
+    const args = {
+        devLoop,
+        action: action,
+        daemon: "private",
+        exportOnly: false,
+        json: false,
+        spec: DEFAULT_SPEC,
+    };
+    if (action === "ui")
+        args.ui = "zellij";
+    const envHost = process.env.PUBLIC_HOST;
+    if (envHost)
+        args.publicHost = envHost;
     for (let i = 0; i < rest.length; i++) {
         const flag = rest[i];
         const value = () => {
@@ -48,13 +94,18 @@ export function parseDemoArgs(argv) {
         switch (flag) {
             case "--mode": {
                 const m = value();
-                if (m === "image")
-                    throw new Error("--mode image is not yet implemented (05-demo s7 step 2); use --mode dev");
-                if (m !== "dev" && m !== "standalone")
+                if (m !== "dev" && m !== "image" && m !== "standalone")
                     throw new Error(`unknown mode '${m}'\n${USAGE}`);
                 args.mode = m;
                 break;
             }
+            case "--daemon": {
+                const d = value();
+                if (d !== "private" && d !== "reuse")
+                    throw new Error(`unknown daemon policy '${d}'\n${USAGE}`);
+                args.daemon = d;
+                break;
+            }
             case "--export-only":
                 args.exportOnly = true;
                 break;
@@ -64,16 +115,34 @@ export function parseDemoArgs(argv) {
             case "--spec":
                 args.spec = value();
                 break;
+            case "--ui": {
+                const u = value();
+                if (u !== "zellij" && u !== "tmux" && u !== "none")
+                    throw new Error(`unknown ui '${u}'\n${USAGE}`);
+                args.ui = u;
+                break;
+            }
+            case "--public-host":
+                args.publicHost = value();
+                break;
             default:
                 throw new Error(`unknown flag '${flag}'\n${USAGE}`);
         }
     }
-    if (args.mode === "standalone" && !args.exportOnly && (args.action === "up" || args.action === "check")) {
-        throw new Error("the full standalone tier (engine + Studio panes) is not yet implemented (05-demo s7 step 3); this slice has `check --mode standalone --export-only`");
+    if (args.ui !== undefined && args.action !== "ui")
+        throw new Error("--ui belongs to ui (or dev-loop ui)");
+    if (devLoop && (args.mode !== undefined || args.daemon !== "private" || args.exportOnly || args.json)) {
+        throw new Error("dev-loop takes only --ui, --public-host and --spec (no --mode, --daemon, --export-only or --json): it is always the source tier on a private daemon");
+    }
+    if (args.mode === "standalone" && !args.exportOnly && args.action !== "spec") {
+        throw new Error(`the full standalone tier is the dev-loop's: \`dev-loop ${args.action === "ui" ? "ui" : "up"}\` (this mode's headless gate is \`check --mode standalone --export-only\`)`);
     }
     if (args.exportOnly && args.mode !== "standalone") {
         throw new Error("--export-only belongs to --mode standalone");
     }
+    if (args.action === "check" && args.daemon === "reuse") {
+        throw new Error("check runs on a private daemon (it is what CI runs); to reload your own daemon use `up --daemon reuse`");
+    }
     return args;
 }
 /** `demo spec --json`: what will run, resolved as far as it can be without a
@@ -83,16 +152,17 @@ export function resolvedSpecView(spec, opts) {
     const slug = opts.slug ?? demoSlug(spec.product);
     const instanceId = `demo-${slug}`;
     const ports = demoPorts(slug);
+    const host = opts.publicHost ?? "localhost";
     const pinned = spec.launch?.params?.STUDIO_HOST_PORT;
     const studioHostPort = pinned !== undefined ? Number(pinned) : ports.studioHostPort;
     const url = (ref) => {
         if ("url" in ref)
             return ref.url;
         if ("control" in ref)
-            return `http://localhost:${ports.backendPort}${ref.control}`;
+            return `http://${host}:${ports.backendPort}${ref.control}`;
         if ("proxy" in ref)
-            return `http://localhost:${ports.proxyPort}${ref.proxy.replaceAll("{id}", instanceId)}`;
-        return `http://localhost:${studioHostPort}${ref.studio}`;
+            return `http://${host}:${ports.proxyPort}${ref.proxy.replaceAll("{id}", instanceId)}`;
+        return `http://${host}:${studioHostPort}${ref.studio}`;
     };
     const t = spec.template;
     const template = t && "build" in t
@@ -109,6 +179,8 @@ export function resolvedSpecView(spec, opts) {
         template,
         ...(spec.launch !== undefined ? { launch: spec.launch } : {}),
         ...(spec.prerequisites !== undefined ? { prerequisites: spec.prerequisites } : {}),
+        extras: (spec.extras ?? []).map((e) => e.name),
+        beforeLaunch: spec.beforeLaunch !== undefined,
         sources: (spec.sources ?? []).map((s) => ({
             name: s.name,
             asset: s.asset ?? { preset: "camera1" },
@@ -158,26 +230,60 @@ export async function demoMain(argv, io) {
         }
         return 1;
     }
+    const mode = args.mode ?? spec.mode ?? "dev";
+    const slug = demoSlug(spec.product);
+    const publicHost = args.publicHost !== undefined ? { publicHost: args.publicHost } : {};
     try {
+        if (args.devLoop) {
+            const dirs = standaloneDirs(spec, slug, io.env ?? process.env);
+            switch (args.action) {
+                case "up":
+                case "refresh":
+                    await io.runDevLoop(spec, {
+                        action: args.action,
+                        cwd: io.cwd,
+                        dirs,
+                        ...publicHost,
+                        ...(io.abort ? { abort: io.abort } : {}),
+                    });
+                    return 0;
+                case "down":
+                    await io.devLoopDown(spec.product);
+                    return 0;
+                default: {
+                    const panes = devLoopPaneList(spec, { cwd: io.cwd, slug, ...dirs, ...publicHost });
+                    return io.launchUi(args.ui ?? "zellij", { session: `${slug}-dev-loop`, tab: slug, panes });
+                }
+            }
+        }
         switch (args.action) {
             case "spec": {
-                const view = resolvedSpecView(spec, { mode: args.mode });
+                const view = resolvedSpecView(spec, { mode, ...publicHost });
                 io.stdout(args.json ? JSON.stringify(view, null, 2) : renderView(view));
                 return 0;
             }
             case "down":
                 await io.demoDown(spec.product);
                 return 0;
-            case "up":
-            case "check": {
+            case "ui": {
+                if (mode === "standalone")
+                    throw new Error("the standalone tier's multiplexer is `dev-loop ui`");
+                const panes = demoPaneList(spec, { cwd: io.cwd, slug, mode, daemon: args.daemon, ...publicHost });
+                return io.launchUi(args.ui ?? "zellij", { session: `${slug}-demo`, tab: slug, panes });
+            }
+            default: {
                 if (args.exportOnly) {
                     await io.runExportCheck(spec, { cwd: io.cwd });
                     return 0;
                 }
+                if (mode === "standalone")
+                    throw new Error("the full standalone tier is `dev-loop up`");
                 await io.runDemo(spec, {
                     action: args.action,
-                    mode: "dev",
+                    mode,
+                    daemon: args.daemon,
                     cwd: io.cwd,
+                    ...publicHost,
                     ...(io.abort ? { abort: io.abort } : {}),
                 });
                 return 0;
@@ -185,7 +291,7 @@ export async function demoMain(argv, io) {
         }
     }
     catch (e) {
-        io.stderr(`demo ${args.action} failed: ${e instanceof Error ? e.message : String(e)}`);
+        io.stderr(`${args.devLoop ? "dev-loop" : "demo"} ${args.action} failed: ${e instanceof Error ? e.message : String(e)}`);
         return 1;
     }
 }
@@ -195,6 +301,10 @@ function renderView(v) {
         `  daemon :${v.ports.daemonPort}  dev backend :${v.ports.backendPort}  proxy :${v.ports.proxyPort}  studio :${v.ports.studioHostPort}`,
         `  template ${"name" in v.template ? v.template.name : `build ${v.template.build.name}`}`,
     ];
+    if (v.image)
+        lines.push(`  image  ${v.image}`);
+    for (const e of v.extras)
+        lines.push(`  extra  ${e}`);
     for (const s of v.sources)
         lines.push(`  source ${s.name}: ${JSON.stringify(s.asset)} -> ingest ${JSON.stringify(s.ingest)}`);
     for (const g of v.ready)
@@ -216,12 +326,17 @@ export function defaultDemoCliIo() {
     const release = () => controller.abort();
     process.once("SIGINT", release);
     process.once("SIGTERM", release);
+    // A multiplexer session ending sends its panes SIGHUP: that is a release too.
+    process.once("SIGHUP", release);
     return {
         cwd: process.cwd(),
         loadSpec: loadSpecModule,
         runDemo: (spec, opts) => runDemo(spec, opts),
         runExportCheck: (spec, opts) => runExportCheck(spec, opts),
         demoDown: (product) => demoDown(product),
+        runDevLoop: (spec, opts) => runDevLoop(spec, opts),
+        devLoopDown: (product) => devLoopDown(product),
+        launchUi: (ui, layout) => launchLayout(ui, renderLayout(layout, ui), layout),
         stdout: (line) => console.log(line),
         stderr: (line) => console.error(line),
         abort: controller.signal,

package/demo/dev-loop-cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+export {};

package/demo/dev-loop-cli.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env bun
+// `ctl-dev-loop`, the bin behind a product's `bun run dev-loop`: the
+// standalone tier's verbs (`up`, `refresh`, `down`, `ui`) are `ctl-demo
+// dev-loop <verb>` under another name.
+import { defaultDemoCliIo, demoMain } from "./cli.js";
+if (import.meta.main) {
+    process.exit(await demoMain(["dev-loop", ...process.argv.slice(2)], defaultDemoCliIo()));
+}

package/demo/dev-loop.d.ts

@@ -0,0 +1,33 @@
+import type { SourceAsset } from "../source-pump.js";
+import { type StandaloneDirs } from "./panes.js";
+import { type DemoDeps, type DemoTimeouts } from "./run.js";
+import type { DemoSpec } from "./spec.js";
+export interface DevLoopOptions {
+    action: "up" | "refresh";
+    cwd: string;
+    slug?: string;
+    /** Default: `standaloneDirs(spec, slug)` — the environment, the spec, the conventions. */
+    dirs?: StandaloneDirs;
+    publicHost?: string;
+    abort?: AbortSignal;
+    timeouts?: DemoTimeouts;
+}
+export interface DevLoopResult {
+    workdir: string;
+    studioUrl: string;
+}
+export interface StandaloneSource {
+    name: string;
+    port: number;
+    streamId: string;
+    asset: SourceAsset;
+}
+/** The pump script the sources pane runs on Enter: every source in
+ *  parallel with the host's ffmpeg, into the from-source engine. A preset is
+ *  fetched into the daemon's sample-media cache if it is not there yet; a
+ *  mediaFile that is absent on this box pumps its fallback. */
+export declare function pumpScript(sources: StandaloneSource[], fileExists: (path: string) => boolean): string;
+export declare function runDevLoop(spec: DemoSpec, opts: DevLoopOptions, deps?: DemoDeps): Promise<DevLoopResult>;
+/** `dev-loop down`: end the recorded run from any shell. The workdir stays —
+ *  it is the developer's, and Studio may still be looking at it. */
+export declare function devLoopDown(product: string, deps?: DemoDeps): Promise<void>;