@norskvideo/ctl-test-harness 0.1.21 → 0.1.23

package/compose-advancing.d.ts

@@ -2,9 +2,19 @@ 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;
+export interface ComposeSample {
+    frames: number;
+    /** Why the sample is 0 when it is: the visualiser was unreachable, and how. */
+    error?: string;
+}
 /** 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. */
+ *  `base` (`.../visualiser`). An unreachable visualiser reads as 0 with the
+ *  reason beside it — the caller's second sample, not a throw, decides. */
+export declare function composeSample(opts: {
+    fetch: FetchLike;
+    base: string;
+    node?: string;
+}): Promise<ComposeSample>;
 export declare function composeFrames(opts: {
     fetch: FetchLike;
     base: string;
@@ -15,6 +25,8 @@ export interface ComposeAdvancingResult {
     before: number;
     after: number;
     node: string;
+    /** Set when a sample could not read the visualiser at all. */
+    error?: 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. */

package/compose-advancing.js

@@ -28,12 +28,18 @@ 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();
+    const text = await r.text();
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new Error(`GET ${url} -> ${r.status}, not JSON (a sign-in page? the route needs no auth): ${text.slice(0, 80)}`);
+    }
 }
 /** 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) {
+ *  `base` (`.../visualiser`). An unreachable visualiser reads as 0 with the
+ *  reason beside it — the caller's second sample, not a throw, decides. */
+export async function composeSample(opts) {
     const node = opts.node ?? DEFAULT_COMPOSE_NODE;
     try {
         const wf = (await getJson(opts.fetch, `${opts.base}/workflow`));
@@ -44,18 +50,28 @@ export async function composeFrames(opts) {
             const summary = await getJson(opts.fetch, `${opts.base}/workflow/${encodeURIComponent(root.wfid)}/summary`);
             max = Math.max(max, maxNodeMediaIn(summary, node));
         }
-        return max;
+        return { frames: max };
     }
-    catch {
-        return 0;
+    catch (e) {
+        return { frames: 0, error: e instanceof Error ? e.message : String(e) };
     }
 }
+export async function composeFrames(opts) {
+    return (await composeSample(opts)).frames;
+}
 /** 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 });
+    const before = await composeSample({ 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 };
+    const after = await composeSample({ fetch: opts.fetch, base: opts.base, node });
+    const error = after.error ?? before.error;
+    return {
+        advancing: after.frames > before.frames && after.frames > 0,
+        before: before.frames,
+        after: after.frames,
+        node,
+        ...(error !== undefined ? { error } : {}),
+    };
 }

package/demo/cli.d.ts

@@ -1,14 +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 { DemoDaemonPolicy, DemoMode, DemoSpec } from "./spec.js";
 export interface DemoArgs {
-    action: "up" | "check" | "down" | "spec";
+    /** `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 {
@@ -58,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 {
@@ -70,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

@@ -15,13 +15,21 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
 //   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|image|standalone] [--daemon private|reuse] [--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, 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
@@ -29,6 +37,14 @@ const USAGE = `usage: demo <up|check|down|spec> [--mode dev|image|standalone] [-
                                       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
@@ -36,14 +52,37 @@ const USAGE = `usage: demo <up|check|down|spec> [--mode dev|image|standalone] [-
   --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, daemon: "private", 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 = () => {
@@ -76,12 +115,27 @@ 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");
@@ -98,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
@@ -176,30 +231,59 @@ 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 });
+                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 not yet implemented (05-demo s7 step 3)");
-                }
+                if (mode === "standalone")
+                    throw new Error("the full standalone tier is `dev-loop up`");
                 await io.runDemo(spec, {
                     action: args.action,
                     mode,
                     daemon: args.daemon,
                     cwd: io.cwd,
+                    ...publicHost,
                     ...(io.abort ? { abort: io.abort } : {}),
                 });
                 return 0;
@@ -207,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;
     }
 }
@@ -242,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>;

package/demo/dev-loop.js

@@ -0,0 +1,205 @@
+// The full standalone tier (05-demo s7 step 3): probe's `refresh-standalone`
+// and the sequencing half of `probe-demo-zellij`, for every product. The
+// engine and Studio run from their checkouts (the `dev-loop ui` panes); this
+// driver owns the rest — a private daemon, the dev backend on the driver's
+// port, the template built from source, the workdir exported with the
+// live-source links, the pump script resolved from the template's ports, and
+// the stamp the Studio pane waits for. `up` holds so `refresh` can re-export
+// against the same daemon and backend; `down` tears them down and leaves the
+// developer's workdir where it is.
+import { join } from "node:path";
+import { DEFAULT_STANDALONE_STUDIO_PORT, DEV_LOOP_SOURCES, DEV_LOOP_STAMP, standaloneDirs, } from "./panes.js";
+import { DemoSession, defaultDemoDeps, demoSlug, exportStandaloneWorkdir, resolveIngestPort, } from "./run.js";
+/** The daemon's built-in presets and where it caches them (norsk-ctl
+ *  backend/src/docker/constants.ts: SOURCE_PRESETS, S3_MEDIA_BASE); the
+ *  standalone tier pumps from the same files with the host's ffmpeg. */
+const SAMPLE_MEDIA_BASE = "https://s3.eu-west-1.amazonaws.com/norsk.video/media-examples/data";
+const SAMPLE_MEDIA_FILES = { camera1: "action.mp4", camera2: "wildlife.ts" };
+const SAMPLE_MEDIA_DIR = "$HOME/.norsk-ctl/sample-media";
+function generated(pattern) {
+    const video = pattern === "bars" ? "smptebars=size=1280x720:rate=25" : "testsrc=size=1280x720:rate=25";
+    return `ffmpeg -hide_banner -loglevel warning -re -f lavfi -i "${video}" -f lavfi -i "sine=frequency=440:sample_rate=48000" -c:v libx264 -preset veryfast -tune zerolatency -g 50 -c:a aac`;
+}
+function pumpLines(asset, target) {
+    if ("mediaFile" in asset) {
+        return [
+            `ffmpeg -hide_banner -loglevel warning -re -stream_loop -1 -i "${asset.mediaFile}" -c copy -f mpegts "${target}" &`,
+        ];
+    }
+    if ("generate" in asset)
+        return [`${generated(asset.generate)} -f mpegts "${target}" &`];
+    const file = SAMPLE_MEDIA_FILES[asset.preset];
+    if (!file)
+        throw new Error(`unknown preset '${asset.preset}'; the daemon's presets are ${Object.keys(SAMPLE_MEDIA_FILES).join(", ")}`);
+    return [
+        `f="${SAMPLE_MEDIA_DIR}/${file}"; [ -f "$f" ] || curl -fL --create-dirs -o "$f" "${SAMPLE_MEDIA_BASE}/${file}"`,
+        `ffmpeg -hide_banner -loglevel warning -re -stream_loop -1 -i "$f" -c copy -f mpegts "${target}" &`,
+    ];
+}
+/** 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 function pumpScript(sources, fileExists) {
+    const lines = [
+        "#!/usr/bin/env bash",
+        "# written by dev-loop up: the demo's sources, pumped from this box into the from-source engine",
+        "set -uo pipefail",
+    ];
+    for (const s of sources) {
+        const target = `srt://127.0.0.1:${s.port}?streamid=${s.streamId}`;
+        const asset = "mediaFile" in s.asset && !fileExists(s.asset.mediaFile) ? s.asset.fallback : s.asset;
+        const via = "mediaFile" in s.asset && !fileExists(s.asset.mediaFile) ? ` (${s.asset.mediaFile} is not on this box)` : "";
+        lines.push("", `# ${s.name}: ${JSON.stringify(asset)} -> ${target}${via}`, ...pumpLines(asset, target));
+    }
+    lines.push("", "wait");
+    return `${lines.join("\n")}\n`;
+}
+function standalonePort(ingest, t) {
+    if ("label" in ingest) {
+        throw new Error(`ingest label '${ingest.label}' — the standalone tier has no instance to resolve a label against; name the template parameter (ingest: { param })`);
+    }
+    if ("port" in ingest)
+        return ingest.port;
+    return resolveIngestPort(ingest, [], t);
+}
+/** The standalone tier's template: its own when the spec gives one, else the demo's. */
+function loopTemplate(spec) {
+    return spec.standalone?.template ?? spec.template;
+}
+function studioPortOf(envText) {
+    const m = /^export PORT='?(\d+)/m.exec(envText ?? "");
+    return m ? Number(m[1]) : DEFAULT_STANDALONE_STUDIO_PORT;
+}
+/** Build (or reload) the template, export the workdir, write the pump script
+ *  and finally the stamp — the order the panes rely on. */
+async function exportLoop(s, templateName, workdir, refresh) {
+    const { spec, deps } = s;
+    deps.removeFile(join(workdir, DEV_LOOP_STAMP));
+    if (refresh) {
+        const t = loopTemplate(spec);
+        if (t && "build" in t)
+            await s.resolveTemplate(t);
+        else
+            await s.cliOk(["product", "reload", spec.product]);
+    }
+    await exportStandaloneWorkdir(s, templateName, workdir);
+    const declared = await s.declaredParams(templateName);
+    const t = { declared, overrides: spec.standalone?.params ?? {} };
+    const sources = (spec.sources ?? []).map((src) => {
+        const asset = src.asset ?? { preset: "camera1" };
+        return { name: src.name, port: standalonePort(src.ingest, t), streamId: src.streamId ?? src.name, asset };
+    });
+    deps.writeFile(join(workdir, DEV_LOOP_SOURCES), pumpScript(sources, deps.fileExists));
+    deps.writeFile(join(workdir, DEV_LOOP_STAMP), `${new Date().toISOString()}\n`);
+    return studioPortOf(deps.readFile(join(workdir, "env")));
+}
+function describeLoop(s, dirs, studioPort) {
+    const { spec } = s;
+    const url = `http://${s.host}:${studioPort}`;
+    return [
+        `${spec.product} standalone workdir exported to ${dirs.workdir} (template from the dev backend on :${s.ports.backendPort})`,
+        `  engine   cd ${dirs.norskDir} && nix develop --command make media-shell`,
+        `  studio   cd ${dirs.studioDir} && (. ${dirs.workdir}/env && npm run server-dev)   -> ${url}`,
+        `  sources  bash ${join(dirs.workdir, DEV_LOOP_SOURCES)}   (into the engine, when the workflow is running)`,
+        `  after a shared/ edit: restart this (the dev backend does not watch shared/); a dashboard edit needs only a browser refresh`,
+    ];
+}
+async function refuseIfUp(spec, deps) {
+    const prev = deps.state.read(spec.product, "dev-loop");
+    if (!prev)
+        return;
+    if (await deps.daemonAnswers(prev.daemonPort)) {
+        throw new Error(`dev-loop '${spec.product}' is already up (daemon :${prev.daemonPort}, workdir ${prev.workdir}) — \`dev-loop refresh\` re-exports it, \`dev-loop down\` ends it`);
+    }
+    deps.log(`forgetting a stale dev-loop record of a run on :${prev.daemonPort} (nothing of it is left)`);
+    deps.state.remove(spec.product, "dev-loop");
+}
+export async function runDevLoop(spec, opts, deps = defaultDemoDeps(opts.cwd)) {
+    const slug = opts.slug ?? demoSlug(spec.product);
+    const dirs = opts.dirs ?? standaloneDirs(spec, slug);
+    const common = {
+        mode: "dev",
+        daemon: "private",
+        ...(opts.timeouts !== undefined ? { timeouts: opts.timeouts } : {}),
+        ...(opts.publicHost !== undefined ? { publicHost: opts.publicHost } : {}),
+    };
+    if (opts.action === "refresh") {
+        const state = deps.state.read(spec.product, "dev-loop");
+        if (!state || !(await deps.daemonAnswers(state.daemonPort)) || !state.templateName) {
+            throw new Error(`dev-loop '${spec.product}' is not up — run \`dev-loop up\` first (it holds; refresh from another pane)`);
+        }
+        const s = new DemoSession(spec, slug, opts.cwd, deps, { ...common, storeDir: state.storeDir });
+        const workdir = state.workdir ?? dirs.workdir;
+        const studioPort = await exportLoop(s, state.templateName, workdir, true);
+        for (const line of describeLoop(s, { ...dirs, workdir }, studioPort))
+            deps.log(line);
+        deps.log("refreshed — reload the workflow in Studio");
+        return { workdir, studioUrl: `http://${s.host}:${studioPort}` };
+    }
+    await refuseIfUp(spec, deps);
+    const s = new DemoSession(spec, slug, opts.cwd, deps, common);
+    let recorded = false;
+    let result;
+    let journeyError;
+    try {
+        await s.attachDaemon();
+        await s.startDev();
+        await s.register({ licence: false });
+        const templateName = await s.resolveTemplate(loopTemplate(spec));
+        const studioPort = await exportLoop(s, templateName, dirs.workdir, false);
+        for (const line of describeLoop(s, dirs, studioPort))
+            deps.log(line);
+        result = { workdir: dirs.workdir, studioUrl: `http://${s.host}:${studioPort}` };
+        const state = {
+            product: spec.product,
+            kind: "dev-loop",
+            storeDir: s.storeDir,
+            daemonPort: s.ports.daemonPort,
+            workdir: dirs.workdir,
+            templateName,
+            ...(s.dev?.pid !== undefined ? { devPid: s.dev.pid } : {}),
+        };
+        deps.state.write(state);
+        recorded = true;
+        deps.log("holding — Ctrl-C (or `dev-loop down` from another shell) ends it; `dev-loop refresh` re-exports");
+        await deps.hold(opts.abort);
+    }
+    catch (e) {
+        journeyError = e;
+    }
+    await s.teardown({ instances: [], handles: [] });
+    if (recorded)
+        deps.state.remove(spec.product, "dev-loop");
+    if (journeyError !== undefined)
+        throw journeyError;
+    return result;
+}
+/** `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 async function devLoopDown(product, deps = defaultDemoDeps(process.cwd())) {
+    const state = deps.state.read(product, "dev-loop");
+    if (!state) {
+        deps.log(`nothing recorded as up for the ${product} dev-loop`);
+        return;
+    }
+    const cli = (argv) => deps.cli(state.storeDir, ["--port", String(state.daemonPort), ...argv]);
+    try {
+        await deps.cleanup({
+            deleteInstance: (id) => cli(["instance", "delete", id, "--purge"]),
+            stopDaemon: () => cli(["shutdown"]),
+            instances: [],
+            daemon: null,
+            storeDir: state.storeDir,
+            containers: [],
+        });
+    }
+    catch (e) {
+        deps.log(`cleanup: ${e instanceof Error ? e.message : String(e)}; nuking the store as root`);
+    }
+    if (state.devPid !== undefined)
+        deps.killPid?.(state.devPid);
+    deps.nukeStoreAsRoot(state.storeDir);
+    deps.state.remove(product, "dev-loop");
+    deps.log(`${product} dev-loop torn down (the workdir ${state.workdir ?? ""} is untouched)`);
+}

package/demo/gates.js

@@ -48,7 +48,9 @@ export function composeAdvancingGate(opts = {}) {
                 node,
                 ...(opts.settleMs !== undefined ? { settleMs: opts.settleMs } : {}),
             });
-            if (!r.advancing)
+            if (r.error)
+                ctx.log(`visualiser unreachable at ${base}: ${r.error}`);
+            else if (!r.advancing)
                 ctx.log(`${node} not advancing yet (${r.before} -> ${r.after})`);
             return r.advancing;
         },

package/demo/index.d.ts

@@ -1,7 +1,11 @@
 export type { DemoArgs, DemoCliIo, ResolvedSpecView } from "./cli.js";
 export { defaultDemoCliIo, demoMain, parseDemoArgs, resolvedSpecView } from "./cli.js";
+export type { DevLoopOptions, DevLoopResult, StandaloneSource } from "./dev-loop.js";
+export { devLoopDown, pumpScript, runDevLoop } from "./dev-loop.js";
 export { composeAdvancingGate, DemoGateFailure, logsCleanGate } from "./gates.js";
-export type { CliResult, DemoDeps, DemoPorts, DemoRunOptions, DemoRunResult, DemoState, DemoStateStore, DemoTimeouts, ExportCheckOptions, IngestPortRow, PinMismatch, ProcessHandle, TemplateParams, } from "./run.js";
-export { checkTemplatePins, defaultDemoDeps, demoDown, demoPorts, demoSlug, expandHome, fileStateStore, findBrokenSymlinks, killGroup, resolveIngestPort, runDemo, runExportCheck, } from "./run.js";
+export type { DemoPane, DemoPaneOptions, DemoUi, DevLoopPaneOptions, PaneLayout, StandaloneDirs } from "./panes.js";
+export { DEV_LOOP_SOURCES, DEV_LOOP_STAMP, demoPaneList, devLoopPaneList, launchLayout, paneArgv, paneCommandLine, paneShellLine, renderLayout, shellQuote, standaloneDirs, } from "./panes.js";
+export type { CliResult, DemoDeps, DemoPorts, DemoRunOptions, DemoRunResult, DemoState, DemoStateKind, DemoStateStore, DemoTimeouts, ExportCheckOptions, IngestPortRow, PinMismatch, ProcessHandle, TemplateParams, } from "./run.js";
+export { checkTemplatePins, defaultDemoDeps, demoDown, demoPorts, demoSlug, expandHome, exportStandaloneWorkdir, fileStateStore, findBrokenSymlinks, killGroup, resolveIngestPort, runDemo, runExportCheck, } from "./run.js";
 export type { DemoContext, DemoDaemonPolicy, DemoExtra, DemoIngest, DemoLaunchContext, DemoMode, DemoOpen, DemoReady, DemoSource, DemoSpec, DemoTemplate, DemoUrl, } from "./spec.js";
 export { DemoSpecSchema, defineDemo, formatSpecIssues } from "./spec.js";

package/demo/index.js

@@ -1,4 +1,6 @@
 export { defaultDemoCliIo, demoMain, parseDemoArgs, resolvedSpecView } from "./cli.js";
+export { devLoopDown, pumpScript, runDevLoop } from "./dev-loop.js";
 export { composeAdvancingGate, DemoGateFailure, logsCleanGate } from "./gates.js";
-export { checkTemplatePins, defaultDemoDeps, demoDown, demoPorts, demoSlug, expandHome, fileStateStore, findBrokenSymlinks, killGroup, resolveIngestPort, runDemo, runExportCheck, } from "./run.js";
+export { DEV_LOOP_SOURCES, DEV_LOOP_STAMP, demoPaneList, devLoopPaneList, launchLayout, paneArgv, paneCommandLine, paneShellLine, renderLayout, shellQuote, standaloneDirs, } from "./panes.js";
+export { checkTemplatePins, defaultDemoDeps, demoDown, demoPorts, demoSlug, expandHome, exportStandaloneWorkdir, fileStateStore, findBrokenSymlinks, killGroup, resolveIngestPort, runDemo, runExportCheck, } from "./run.js";
 export { DemoSpecSchema, defineDemo, formatSpecIssues } from "./spec.js";