@norskvideo/ctl-test-harness 0.1.21 → 0.1.22

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/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";

package/demo/panes.d.ts

@@ -0,0 +1,81 @@
+import type { DemoDaemonPolicy, DemoMode, DemoSpec } from "./spec.js";
+export type DemoUi = "zellij" | "tmux" | "none";
+export interface DemoPane {
+    name: string;
+    /** Directory the pane starts in. */
+    cwd: string;
+    /** One shell line. `run`: a long-running process; `gate`: waits for
+     *  something, then acts; `shell`: an interactive shell (command ignored).
+     *  Every kind lands in a shell when its command exits, so a pane is never a
+     *  dead box. */
+    kind: "run" | "gate" | "shell";
+    command: string;
+    /** The flake ref whose dev shell the command runs under (`.#dev`, `.`). */
+    flake?: string;
+}
+export interface PaneLayout {
+    session: string;
+    tab: string;
+    panes: DemoPane[];
+}
+/** The stamp `dev-loop up` touches once the workdir is exported (the Studio
+ *  pane waits for it) and the pump script it writes (the sources pane runs
+ *  it on Enter). Both live in the workdir so a re-export replaces them. */
+export declare const DEV_LOOP_STAMP = ".dev-loop-exported";
+export declare const DEV_LOOP_SOURCES = ".dev-loop-sources";
+export declare const DEFAULT_STANDALONE_STUDIO_PORT = 8000;
+export declare const INSTANCE_LABEL = "norsk-ctl.instance";
+export declare const MEDIA_ROLE_LABEL = "norsk-ctl.role=media";
+/** POSIX single-quoting: safe for any bytes but a NUL. */
+export declare function shellQuote(s: string): string;
+/** The bash line a pane runs, before any nix wrapping. */
+export declare function paneShellLine(pane: DemoPane): string;
+/** The pane's process: `nix develop <flake> --command bash -c <line>` when
+ *  the pane names a flake, else bash alone. */
+export declare function paneArgv(pane: DemoPane): string[];
+/** `paneArgv` as one shell-quoted line (tmux, none). */
+export declare function paneCommandLine(pane: DemoPane): string;
+export interface DemoPaneOptions {
+    cwd: string;
+    slug: string;
+    mode: DemoMode;
+    daemon: DemoDaemonPolicy;
+    publicHost?: string;
+    /** The product's dev shell; `.#dev` is what every product flake names. */
+    flake?: string;
+}
+/** `demo ui`: the gate pane holds `demo up`, a logs pane follows the
+ *  instance's media container (found by label, so both container naming
+ *  schemes work), and a shell in the product's dev shell. */
+export declare function demoPaneList(_spec: DemoSpec, o: DemoPaneOptions): DemoPane[];
+export interface StandaloneDirs {
+    norskDir: string;
+    studioDir: string;
+    workdir: string;
+}
+/** Where the engine, Studio and the exported workdir live: the environment
+ *  (NORSK_DIR, STUDIO_DIR, TO — this developer's box), else the spec (the
+ *  repo's convention), else `~/dev/norsk`, `~/dev/norsk-studio`,
+ *  `~/dev/<slug>-standalone` (what probe-demo-zellij assumed). */
+export declare function standaloneDirs(spec: DemoSpec, slug: string, env?: Record<string, string | undefined>): StandaloneDirs;
+export interface DevLoopPaneOptions extends StandaloneDirs {
+    cwd: string;
+    slug: string;
+    publicHost?: string;
+    flake?: string;
+    /** The exported workdir's Studio port (export-workdir's default). */
+    studioPort?: number;
+}
+/** `dev-loop ui`: the engine and Studio from their checkouts, the gate pane
+ *  holding `dev-loop up`, the sources pane running the driver's resolved pump
+ *  script on Enter, and a shell. Studio waits for the export stamp, sources
+ *  the exported env, and — with a public host — advertises the MoQ preview
+ *  there and drops the localhost-only cert Studio would otherwise reuse on
+ *  remaining validity alone (probe-demo-zellij:142-149). */
+export declare function devLoopPaneList(_spec: DemoSpec, o: DevLoopPaneOptions): DemoPane[];
+export declare function renderLayout(layout: PaneLayout, ui: DemoUi): string;
+/** Open the rendered layout: zellij's client blocks until detach and the
+ *  session is deleted after it (a trailing line, not a trap: the panes'
+ *  processes get SIGHUP, which the driver's hold treats as a release); tmux's
+ *  script attaches and returns on detach; none prints. */
+export declare function launchLayout(ui: DemoUi, rendered: string, layout: PaneLayout): number;

package/demo/panes.js

@@ -0,0 +1,236 @@
+// The multiplexer front-end (05-demo s4 "front-end 2", s7 step 3). The pane
+// list is the contract; zellij (a kdl layout), tmux (a script) and none (the
+// commands, to paste) are renderers of it. Every pane runs `nix develop
+// <flake> --command ...` so the launcher itself never needs a nix shell —
+// which dissolves the awk-vs-bun problem probe-demo-zellij documented.
+//
+// Ordering never lives here: the gate pane runs `demo up` / `dev-loop up`,
+// and the driver sequences everything. The other panes only wait for what the
+// driver leaves on disk (the export stamp, the resolved pump script).
+import { spawnSync } from "node:child_process";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+/** The stamp `dev-loop up` touches once the workdir is exported (the Studio
+ *  pane waits for it) and the pump script it writes (the sources pane runs
+ *  it on Enter). Both live in the workdir so a re-export replaces them. */
+export const DEV_LOOP_STAMP = ".dev-loop-exported";
+export const DEV_LOOP_SOURCES = ".dev-loop-sources";
+export const DEFAULT_STANDALONE_STUDIO_PORT = 8000;
+export const INSTANCE_LABEL = "norsk-ctl.instance";
+export const MEDIA_ROLE_LABEL = "norsk-ctl.role=media";
+/** POSIX single-quoting: safe for any bytes but a NUL. */
+export function shellQuote(s) {
+    return `'${s.replaceAll("'", `'\\''`)}'`;
+}
+/** The bash line a pane runs, before any nix wrapping. */
+export function paneShellLine(pane) {
+    const shell = `exec \${SHELL:-bash}`;
+    return pane.kind === "shell" ? shell : `${pane.command}; ${shell}`;
+}
+/** The pane's process: `nix develop <flake> --command bash -c <line>` when
+ *  the pane names a flake, else bash alone. */
+export function paneArgv(pane) {
+    const line = paneShellLine(pane);
+    return pane.flake ? ["nix", "develop", pane.flake, "--command", "bash", "-c", line] : ["bash", "-c", line];
+}
+/** `paneArgv` as one shell-quoted line (tmux, none). */
+export function paneCommandLine(pane) {
+    return paneArgv(pane)
+        .map((a) => (/^[A-Za-z0-9_./#=:-]+$/.test(a) ? a : shellQuote(a)))
+        .join(" ");
+}
+const DEV_FLAKE = ".#dev";
+/** `demo ui`: the gate pane holds `demo up`, a logs pane follows the
+ *  instance's media container (found by label, so both container naming
+ *  schemes work), and a shell in the product's dev shell. */
+export function demoPaneList(_spec, o) {
+    const flake = o.flake ?? DEV_FLAKE;
+    const instanceId = `demo-${o.slug}`;
+    const up = ["bun run demo -- up", "--mode", o.mode];
+    if (o.daemon === "reuse")
+        up.push("--daemon", "reuse");
+    if (o.publicHost)
+        up.push("--public-host", o.publicHost);
+    const find = `docker ps -q -f label=${INSTANCE_LABEL}=${instanceId} -f label=${MEDIA_ROLE_LABEL}`;
+    return [
+        { name: "demo", kind: "gate", cwd: o.cwd, flake, command: up.join(" ") },
+        {
+            name: "logs",
+            kind: "gate",
+            cwd: o.cwd,
+            command: `echo "waiting for instance ${instanceId} ..."; until [ -n "$(${find})" ]; do sleep 1; done; docker logs -f "$(${find})"`,
+        },
+        { name: "shell", kind: "shell", cwd: o.cwd, flake, command: "" },
+    ];
+}
+function expandWith(path, home) {
+    if (path === "~")
+        return home;
+    if (path.startsWith("~/"))
+        return join(home, path.slice(2));
+    return path;
+}
+/** Where the engine, Studio and the exported workdir live: the environment
+ *  (NORSK_DIR, STUDIO_DIR, TO — this developer's box), else the spec (the
+ *  repo's convention), else `~/dev/norsk`, `~/dev/norsk-studio`,
+ *  `~/dev/<slug>-standalone` (what probe-demo-zellij assumed). */
+export function standaloneDirs(spec, slug, env = process.env) {
+    const home = env.HOME ?? "~";
+    const pick = (envKey, fromSpec, fallback) => expandWith(env[envKey] || fromSpec || fallback, home);
+    return {
+        norskDir: pick("NORSK_DIR", spec.standalone?.norskDir, "~/dev/norsk"),
+        studioDir: pick("STUDIO_DIR", spec.standalone?.studioDir, "~/dev/norsk-studio"),
+        workdir: pick("TO", spec.standalone?.workdir, `~/dev/${slug}-standalone`),
+    };
+}
+/** `dev-loop ui`: the engine and Studio from their checkouts, the gate pane
+ *  holding `dev-loop up`, the sources pane running the driver's resolved pump
+ *  script on Enter, and a shell. Studio waits for the export stamp, sources
+ *  the exported env, and — with a public host — advertises the MoQ preview
+ *  there and drops the localhost-only cert Studio would otherwise reuse on
+ *  remaining validity alone (probe-demo-zellij:142-149). */
+export function devLoopPaneList(_spec, o) {
+    const flake = o.flake ?? DEV_FLAKE;
+    const studioPort = o.studioPort ?? DEFAULT_STANDALONE_STUDIO_PORT;
+    const stamp = join(o.workdir, DEV_LOOP_STAMP);
+    const sources = join(o.workdir, DEV_LOOP_SOURCES);
+    const up = ["bun run dev-loop -- up"];
+    if (o.publicHost)
+        up.push("--public-host", o.publicHost);
+    const wait = `until [ -f ${stamp} ]; do sleep 1; done`;
+    const studio = [`echo "waiting for ${o.workdir} to be exported ..."`, wait, `. ${o.workdir}/env`];
+    if (o.publicHost) {
+        studio.push(`export PUBLIC_URL_PREFIX=http://${o.publicHost}:${studioPort}`, `rm -rf ${o.workdir}/data/moq-certs`, `echo "MoQ preview advertised as http://${o.publicHost}:${studioPort}; cert regenerating to cover ${o.publicHost}"`);
+    }
+    studio.push("npm run server-dev");
+    return [
+        { name: "norsk", kind: "run", cwd: o.norskDir, flake: ".", command: "make media-shell" },
+        { name: "dev-loop", kind: "gate", cwd: o.cwd, flake, command: up.join(" ") },
+        { name: "studio", kind: "gate", cwd: o.studioDir, flake: ".", command: studio.join("; ") },
+        {
+            name: "sources",
+            kind: "gate",
+            cwd: o.cwd,
+            flake,
+            command: `${wait}; cat ${sources}; echo "press Enter to start the sources"; read -r; bash ${sources}`,
+        },
+        { name: "shell", kind: "shell", cwd: o.cwd, flake, command: "" },
+    ];
+}
+function kdlString(s) {
+    return `"${s.replaceAll("\\", "\\\\").replaceAll('"', '\\"')}"`;
+}
+function kdlPane(pane, indent) {
+    const [command, ...args] = paneArgv(pane);
+    return [
+        `${indent}pane name=${kdlString(pane.name)} cwd=${kdlString(pane.cwd)} command=${kdlString(command)} {`,
+        `${indent}    args ${args.map(kdlString).join(" ")}`,
+        `${indent}}`,
+    ].join("\n");
+}
+/** Two columns, the first half of the list on the left — as probe's layout
+ *  did (things that run on the left, things that wait on the right). The tab
+ *  and status bars are declared so the keybinding help is always present. */
+function renderZellij(layout) {
+    const half = Math.ceil(layout.panes.length / 2);
+    const column = (panes) => [
+        `            pane split_direction="horizontal" {`,
+        ...panes.map((p) => kdlPane(p, "                ")),
+        "            }",
+    ].join("\n");
+    return `${[
+        "// rendered by ctl-demo --ui zellij; the pane list is the contract, this file is a view of it",
+        "layout {",
+        "    default_tab_template {",
+        "        pane size=1 borderless=true {",
+        '            plugin location="zellij:tab-bar"',
+        "        }",
+        "        children",
+        "        pane size=2 borderless=true {",
+        '            plugin location="zellij:status-bar"',
+        "        }",
+        "    }",
+        `    tab name=${kdlString(layout.tab)} {`,
+        `        pane split_direction="vertical" {`,
+        column(layout.panes.slice(0, half)),
+        column(layout.panes.slice(half)),
+        "        }",
+        "    }",
+        "}",
+    ].join("\n")}\n`;
+}
+function renderTmux(layout) {
+    const s = shellQuote(layout.session);
+    const lines = [
+        "#!/usr/bin/env bash",
+        "# rendered by ctl-demo --ui tmux; the pane list is the contract, this file is a view of it",
+        "set -euo pipefail",
+        "export NIXPKGS_ALLOW_INSECURE=1 NIXPKGS_ALLOW_UNFREE=1",
+        `s=${s}`,
+        `tmux kill-session -t "$s" 2>/dev/null || true`,
+    ];
+    layout.panes.forEach((pane, i) => {
+        const line = shellQuote(paneCommandLine(pane));
+        if (i === 0) {
+            lines.push(`tmux new-session -d -s "$s" -n ${shellQuote(layout.tab)} -c ${shellQuote(pane.cwd)} ${line}`);
+        }
+        else {
+            lines.push(`tmux split-window -t "$s:0" -c ${shellQuote(pane.cwd)} ${line}`);
+        }
+        lines.push(`tmux select-pane -t "$s:0.${i}" -T ${shellQuote(pane.name)}`);
+    });
+    lines.push(`tmux set-option -t "$s" pane-border-status top`, `tmux select-layout -t "$s:0" tiled`, `tmux select-pane -t "$s:0.0"`, `tmux attach -t "$s"`);
+    return `${lines.join("\n")}\n`;
+}
+function renderNone(layout) {
+    const out = [
+        `# ${layout.session}: one shell per block, in this order (rendered by ctl-demo --ui none)`,
+        "export NIXPKGS_ALLOW_INSECURE=1 NIXPKGS_ALLOW_UNFREE=1",
+    ];
+    for (const pane of layout.panes) {
+        out.push("", `# ${pane.name}`, `cd ${shellQuote(pane.cwd)}`, paneCommandLine(pane));
+    }
+    return `${out.join("\n")}\n`;
+}
+export function renderLayout(layout, ui) {
+    switch (ui) {
+        case "zellij":
+            return renderZellij(layout);
+        case "tmux":
+            return renderTmux(layout);
+        case "none":
+            return renderNone(layout);
+    }
+}
+/** Open the rendered layout: zellij's client blocks until detach and the
+ *  session is deleted after it (a trailing line, not a trap: the panes'
+ *  processes get SIGHUP, which the driver's hold treats as a release); tmux's
+ *  script attaches and returns on detach; none prints. */
+export function launchLayout(ui, rendered, layout) {
+    if (ui === "none") {
+        process.stdout.write(rendered);
+        return 0;
+    }
+    const dir = mkdtempSync(join(tmpdir(), "ctl-demo-ui-"));
+    const env = { ...process.env, NIXPKGS_ALLOW_INSECURE: "1", NIXPKGS_ALLOW_UNFREE: "1" };
+    try {
+        if (ui === "tmux") {
+            const script = join(dir, `${layout.session}.tmux.sh`);
+            writeFileSync(script, rendered);
+            return spawnSync("bash", [script], { stdio: "inherit", env }).status ?? 1;
+        }
+        const kdl = join(dir, `${layout.session}.kdl`);
+        writeFileSync(kdl, rendered);
+        spawnSync("zellij", ["delete-session", "--force", layout.session], { stdio: "ignore" });
+        const r = spawnSync("zellij", ["--new-session-with-layout", kdl, "--session", layout.session], {
+            stdio: "inherit",
+            env,
+        });
+        spawnSync("zellij", ["delete-session", "--force", layout.session], { stdio: "ignore" });
+        return r.status ?? 1;
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+}

package/demo/run.d.ts

@@ -3,7 +3,7 @@ import { ensureRunnerOnNetwork } from "../container-net.js";
 import { type DaemonProcess, type StartDaemonOptions } from "../daemon.js";
 import { type BaseHarnessPorts } from "../harness-config.js";
 import { type SourceHandle, type SrtPumpTarget } from "../source-pump.js";
-import type { DemoDaemonPolicy, DemoIngest, DemoMode, DemoSpec } from "./spec.js";
+import type { DemoDaemonPolicy, DemoIngest, DemoMode, DemoSpec, DemoTemplate } from "./spec.js";
 export interface CliResult {
     stdout: string;
     stderr: string;
@@ -17,6 +17,9 @@ export interface ProcessHandle {
 /** What `up` records so `down` (or a refused second `up`) can find the run. */
 export interface DemoState {
     product: string;
+    /** Absent on a demo's record; `dev-loop` on the standalone tier's, which
+     *  lives beside it under its own file so the two never mistake each other. */
+    kind?: DemoStateKind;
     storeDir: string;
     daemonPort: number;
     instanceId?: string;
@@ -25,11 +28,15 @@ export interface DemoState {
     daemon?: DemoDaemonPolicy;
     /** Extra containers `up` started, for `down` to remove. */
     extras?: string[];
+    /** dev-loop: the exported workdir and the template it exported, for `refresh`. */
+    workdir?: string;
+    templateName?: string;
 }
+export type DemoStateKind = "demo" | "dev-loop";
 export interface DemoStateStore {
-    read(product: string): DemoState | null;
+    read(product: string, kind?: DemoStateKind): DemoState | null;
     write(state: DemoState): void;
-    remove(product: string): void;
+    remove(product: string, kind?: DemoStateKind): void;
 }
 export interface DemoDeps {
     licenseFile(): string;
@@ -37,6 +44,8 @@ export interface DemoDeps {
     /** The developer's real store, for `--daemon reuse`. */
     realStoreDir(): string;
     writeFile(path: string, contents: string): void;
+    /** Remove a file if present (the dev-loop's export stamp). */
+    removeFile(path: string): void;
     /** File contents, or null when unreadable (compose.yml, manifest.seed.json,
      *  config.yaml, proxy-secret). */
     readFile(path: string): string | null;
@@ -108,6 +117,9 @@ export interface DemoRunOptions {
     /** Releases an `up` hold. */
     abort?: AbortSignal;
     timeouts?: DemoTimeouts;
+    /** The hostname other machines reach this box by: every printed URL uses
+     *  it, and a private daemon is initialised with it as its publicHost. */
+    publicHost?: string;
 }
 export interface DemoRunResult {
     instanceId: string;
@@ -176,6 +188,84 @@ export declare function fileStateStore(cwd: string): DemoStateStore;
  *  own), falling back to the pid alone if it is not a group leader. */
 export declare function killGroup(pid: number): void;
 export declare function defaultDemoDeps(cwd: string): DemoDeps;
+export interface SessionOptions {
+    mode: DemoMode;
+    daemon: DemoDaemonPolicy;
+    daemonPort?: number;
+    timeouts?: DemoTimeouts;
+    publicHost?: string;
+    /** Private: attach to an existing private store (a recorded run) instead of making one. */
+    storeDir?: string;
+}
+/** The pieces of a run that `runDemo`, `runExportCheck` and the dev-loop
+ *  share: the daemon (private on its band, or the developer's), the dev
+ *  backend on the driver's port, the registration, and the template (built
+ *  or chosen). */
+export declare class DemoSession {
+    readonly spec: DemoSpec;
+    readonly slug: string;
+    readonly cwd: string;
+    readonly deps: DemoDeps;
+    readonly mode: DemoMode;
+    readonly policy: DemoDaemonPolicy;
+    readonly ports: DemoPorts;
+    readonly storeDir: string;
+    /** The host every printed URL names. */
+    readonly host: string;
+    readonly publicHost: string | undefined;
+    /** Scheme + authority of the daemon's proxy, for `proxy` URLs. */
+    readonly proxyBase: string;
+    daemon: DaemonProcess | null;
+    dev: ProcessHandle | null;
+    extras: string[];
+    private readonly timeouts;
+    constructor(spec: DemoSpec, slug: string, cwd: string, deps: DemoDeps, opts: SessionOptions);
+    get devUrl(): string;
+    templateDir(name: string): string;
+    /** What the real daemon's proxy demands on `/api/*`; absent on a private daemon. */
+    proxySecret(): string | undefined;
+    cli: (argv: string[], opts?: {
+        output?: "json" | "yaml";
+    }) => Promise<CliResult>;
+    cliOk: (argv: string[], opts?: {
+        output?: "json" | "yaml";
+    }) => Promise<CliResult>;
+    /** Private: init a virgin store and start a daemon on the band. Reuse: the
+     *  developer's daemon must already answer. */
+    attachDaemon(): Promise<void>;
+    startDev(): Promise<void>;
+    /** The reuse policy's mandatory sequence: `product add` refuses an existing
+     *  name and stored templates are immutable, so the instance, every template
+     *  the product publishes (plus the spec's built one), the product and its
+     *  control-plane container all go first. Each step tolerates absence. */
+    resetRegistration(instanceId: string): Promise<void>;
+    register(opts: {
+        licence: boolean;
+    }): Promise<void>;
+    /** The template to launch: built from the spec's input, or a name the
+     *  product publishes (its first default when the spec names none). */
+    resolveTemplate(t?: DemoTemplate | undefined): Promise<string>;
+    /** Funke's iterate.sh pin guard for every product: the stored compose must
+     *  pin what manifest.seed.json declares. Image mode, and any reuse — a
+     *  private dev-mode daemon renders the template fresh from source, so there
+     *  is nothing stale to catch there. */
+    pinGuard(templateName: string): Promise<void>;
+    /** name -> stringified default, from `template show`. */
+    declaredParams(templateName: string): Promise<Map<string, string | undefined>>;
+    startExtras(instanceId: string): void;
+    stopExtras(): void;
+    waitRunning(instanceId: string): Promise<void>;
+    instanceListed(instanceId: string): Promise<boolean>;
+    ingestPorts(instanceId: string): Promise<IngestPortRow[]>;
+    gateTimeout(ms: number | undefined): number;
+    /** Tear down in reverse: sources, instance, then — private only — the
+     *  daemon (with its proxy), the dev backend, the store. Reuse leaves the
+     *  developer's daemon, store and registration as they are. */
+    teardown(opts: {
+        instances: string[];
+        handles: SourceHandle[];
+    }): Promise<void>;
+}
 export declare function runDemo(spec: DemoSpec, opts: DemoRunOptions, deps?: DemoDeps): Promise<DemoRunResult>;
 export interface ExportCheckOptions {
     cwd: string;
@@ -190,5 +280,8 @@ export interface ExportCheckOptions {
 export declare function runExportCheck(spec: DemoSpec, opts: ExportCheckOptions, deps?: DemoDeps): Promise<{
     exportDir: string;
 }>;
+/** `template export-workdir` with the spec's live-source links and params,
+ *  then the check that rotted (05-demo s1): every symlink resolves. */
+export declare function exportStandaloneWorkdir(s: DemoSession, templateName: string, to: string): Promise<void>;
 /** `demo down`: tear down the run `up` recorded, from any shell. */
 export declare function demoDown(product: string, deps?: DemoDeps): Promise<void>;

package/demo/run.js

@@ -196,11 +196,11 @@ export function findBrokenSymlinks(dir) {
  *  consumer's repo, where `down` from another shell can find it. */
 export function fileStateStore(cwd) {
     const dir = join(cwd, "test-temp", "demo");
-    const path = (product) => join(dir, `${product}.json`);
+    const path = (product, kind) => join(dir, `${product}${kind === "dev-loop" ? ".dev-loop" : ""}.json`);
     return {
-        read: (product) => {
+        read: (product, kind) => {
             try {
-                return JSON.parse(readFileSync(path(product), "utf8"));
+                return JSON.parse(readFileSync(path(product, kind), "utf8"));
             }
             catch {
                 return null;
@@ -208,9 +208,9 @@ export function fileStateStore(cwd) {
         },
         write: (state) => {
             mkdirSync(dir, { recursive: true });
-            writeFileSync(path(state.product), `${JSON.stringify(state, null, 2)}\n`);
+            writeFileSync(path(state.product, state.kind), `${JSON.stringify(state, null, 2)}\n`);
         },
-        remove: (product) => rmSync(path(product), { force: true }),
+        remove: (product, kind) => rmSync(path(product, kind), { force: true }),
     };
 }
 /** SIGTERM a process group (a pid startProcess spawned detached leads its
@@ -237,6 +237,7 @@ export function defaultDemoDeps(cwd) {
         storeDir: (slug) => makeStoreDir(`norsk-demo-${slug}-`),
         realStoreDir: () => process.env.NORSK_CTL_STORE_DIR ?? join(homedir(), ".norsk-ctl"),
         writeFile: (path, contents) => writeFileSync(path, contents),
+        removeFile: (path) => rmSync(path, { force: true }),
         readFile: (path) => {
             try {
                 return readFileSync(path, "utf8");
@@ -326,10 +327,11 @@ export function defaultDemoDeps(cwd) {
         log: (line) => console.log(`[demo] ${line}`),
     };
 }
-/** The pieces of a run that both `runDemo` and `runExportCheck` share: the
- *  daemon (private on its band, or the developer's), the dev backend on the
- *  driver's port, the registration, and the template (built or chosen). */
-class DemoSession {
+/** The pieces of a run that `runDemo`, `runExportCheck` and the dev-loop
+ *  share: the daemon (private on its band, or the developer's), the dev
+ *  backend on the driver's port, the registration, and the template (built
+ *  or chosen). */
+export class DemoSession {
     spec;
     slug;
     cwd;
@@ -338,6 +340,9 @@ class DemoSession {
     policy;
     ports;
     storeDir;
+    /** The host every printed URL names. */
+    host;
+    publicHost;
     /** Scheme + authority of the daemon's proxy, for `proxy` URLs. */
     proxyBase;
     daemon = null;
@@ -351,7 +356,9 @@ class DemoSession {
         this.deps = deps;
         this.mode = opts.mode;
         this.policy = opts.daemon;
-        const host = process.env.NORSK_TEST_HOST ?? "localhost";
+        this.publicHost = opts.publicHost;
+        const host = opts.publicHost ?? process.env.NORSK_TEST_HOST ?? "localhost";
+        this.host = host;
         if (opts.daemon === "reuse") {
             const daemonPort = opts.daemonPort ?? (Number(process.env.NORSK_CTL_PORT) || DEFAULT_DAEMON_PORT);
             this.storeDir = deps.realStoreDir();
@@ -361,7 +368,7 @@ class DemoSession {
         }
         else {
             this.ports = demoPorts(slug);
-            this.storeDir = deps.storeDir(slug);
+            this.storeDir = opts.storeDir ?? deps.storeDir(slug);
             // The private daemon is initialised without a cert source, so its proxy
             // speaks plain http (seen live: https:// gave 000, http:// served the page).
             this.proxyBase = `http://${host}:${this.ports.proxyPort}`;
@@ -416,6 +423,7 @@ class DemoSession {
             String(this.ports.proxyPort),
             "--no-http-redirect",
             "--no-start-server",
+            ...(this.publicHost ? ["--public-host", this.publicHost] : []),
         ]);
         const started = this.deps.startDaemon(this.storeDir, { port: this.ports.daemonPort, seedConfig: false });
         this.daemon = started.daemon;
@@ -473,8 +481,7 @@ class DemoSession {
     }
     /** The template to launch: built from the spec's input, or a name the
      *  product publishes (its first default when the spec names none). */
-    async resolveTemplate() {
-        const t = this.spec.template;
+    async resolveTemplate(t = this.spec.template) {
         if (t && "build" in t) {
             const name = t.build.name ?? `${this.spec.product}-demo`;
             let inputPath;
@@ -633,13 +640,13 @@ class DemoSession {
     }
 }
 function urlResolver(o) {
-    const host = process.env.NORSK_TEST_HOST ?? "localhost";
+    const host = o.host;
     const mode = netReachMode();
     return (ref) => {
         if ("url" in ref)
             return ref.url;
         if ("control" in ref)
-            return `http://localhost:${o.ports.backendPort}${ref.control}`;
+            return `http://${host}:${o.ports.backendPort}${ref.control}`;
         if ("proxy" in ref)
             return `${o.proxyBase}${ref.proxy.replaceAll("{id}", o.instanceId)}`;
         return `${studioBaseFrom({ instanceId: o.instanceId, studioHostPort: o.studioHostPort }, host, mode)}${ref.studio}`;
@@ -729,6 +736,7 @@ export async function runDemo(spec, opts, deps = defaultDemoDeps(opts.cwd)) {
         daemon: policy,
         ...(opts.daemonPort !== undefined ? { daemonPort: opts.daemonPort } : {}),
         ...(opts.timeouts !== undefined ? { timeouts: opts.timeouts } : {}),
+        ...(opts.publicHost !== undefined ? { publicHost: opts.publicHost } : {}),
     });
     if (opts.action === "up") {
         await refuseIfUp(spec, s, deps);
@@ -808,7 +816,7 @@ export async function runDemo(spec, opts, deps = defaultDemoDeps(opts.cwd)) {
         }));
         const ctx = {
             ...launchCtx,
-            url: urlResolver({ instanceId, ports: s.ports, studioHostPort, proxyBase: s.proxyBase }),
+            url: urlResolver({ instanceId, ports: s.ports, studioHostPort, proxyBase: s.proxyBase, host: s.host }),
             fetch: deps.fetch,
         };
         // Sources first: a gate such as "the switcher is composing" or "the probe
@@ -882,19 +890,7 @@ export async function runExportCheck(spec, opts, deps = defaultDemoDeps(opts.cwd
         await s.startDev();
         await s.register({ licence: false });
         const templateName = await s.resolveTemplate();
-        const argv = ["template", "export-workdir", templateName, "--to", exportDir];
-        for (const [k, v] of Object.entries(spec.standalone?.params ?? {}))
-            argv.push("--param", `${k}=${v}`);
-        for (const [pkg, path] of Object.entries(spec.standalone?.links ?? {})) {
-            argv.push("--link-component", `${pkg}=${resolve(opts.cwd, path)}`);
-        }
-        if (spec.standalone?.dashboards)
-            argv.push("--link-dashboards", resolve(opts.cwd, spec.standalone.dashboards));
-        await s.cliOk(argv);
-        const broken = deps.brokenSymlinks(exportDir);
-        if (broken.length) {
-            throw new Error(`exported workdir has ${broken.length} broken symlink(s):\n  ${broken.join("\n  ")}`);
-        }
+        await exportStandaloneWorkdir(s, templateName, exportDir);
         deps.log(`export ok: ${templateName} -> ${exportDir}, every symlink resolves`);
     }
     catch (e) {
@@ -905,6 +901,24 @@ export async function runExportCheck(spec, opts, deps = defaultDemoDeps(opts.cwd
         throw journeyError;
     return { exportDir };
 }
+/** `template export-workdir` with the spec's live-source links and params,
+ *  then the check that rotted (05-demo s1): every symlink resolves. */
+export async function exportStandaloneWorkdir(s, templateName, to) {
+    const { spec, cwd, deps } = s;
+    const argv = ["template", "export-workdir", templateName, "--to", to];
+    for (const [k, v] of Object.entries(spec.standalone?.params ?? {}))
+        argv.push("--param", `${k}=${v}`);
+    for (const [pkg, path] of Object.entries(spec.standalone?.links ?? {})) {
+        argv.push("--link-component", `${pkg}=${resolve(cwd, path)}`);
+    }
+    if (spec.standalone?.dashboards)
+        argv.push("--link-dashboards", resolve(cwd, spec.standalone.dashboards));
+    await s.cliOk(argv);
+    const broken = deps.brokenSymlinks(to);
+    if (broken.length) {
+        throw new Error(`exported workdir has ${broken.length} broken symlink(s):\n  ${broken.join("\n  ")}`);
+    }
+}
 /** `demo down`: tear down the run `up` recorded, from any shell. */
 export async function demoDown(product, deps = defaultDemoDeps(process.cwd())) {
     const state = deps.state.read(product);

package/demo/spec.d.ts

@@ -138,12 +138,22 @@ export interface DemoSpec {
     /** Runs once every gate holds. */
     after?: (ctx: DemoContext) => Promise<void>;
     open?: DemoOpen[];
-    /** The standalone tier's live-source links, for `--mode standalone`. Paths
-     *  are relative to the repo root. */
+    /** The standalone tier (`dev-loop`, `check --mode standalone --export-only`):
+     *  the live-source links (paths relative to the repo root) and, for the full
+     *  tier, where the engine and Studio checkouts and the exported workdir live
+     *  (absolute or `~`-rooted; NORSK_DIR / STUDIO_DIR / TO in the environment
+     *  override them, the conventional `~/dev/...` paths apply when neither says). */
     standalone?: {
         links?: Record<string, string>;
         dashboards?: string;
         params?: Record<string, string | number>;
+        norskDir?: string;
+        studioDir?: string;
+        workdir?: string;
+        /** The template the dev-loop builds when it is not the demo's (probe:
+         *  the standalone form assumes the box's side-loads, the demo form is
+         *  portable). The export gate keeps the demo's, CI-portable. */
+        template?: DemoTemplate;
     };
 }
 export declare const DemoSpecSchema: z.ZodType<DemoSpec>;

package/demo/spec.js

@@ -38,6 +38,21 @@ const relativePath = z
     .string()
     .min(1)
     .refine((p) => !isAbsolute(p) && !p.startsWith("~"), { message: "must be a relative path inside the repo" });
+const homePath = z
+    .string()
+    .min(1)
+    .refine((p) => isAbsolute(p) || p === "~" || p.startsWith("~/"), {
+    message: "must be an absolute or ~-rooted path (a checkout outside the repo)",
+});
+const Template = z.union([
+    z.strictObject({ name: z.string().min(1) }),
+    z.strictObject({
+        build: z.strictObject({
+            name: z.string().min(1).optional(),
+            input: z.union([z.string().min(1), z.record(z.string(), z.unknown())]),
+        }),
+    }),
+]);
 export const DemoSpecSchema = z
     .strictObject({
     product: z.string().min(1),
@@ -47,17 +62,7 @@ export const DemoSpecSchema = z
         readyPath: z.string().startsWith("/").optional(),
     }),
     image: z.string().min(1).optional(),
-    template: z
-        .union([
-        z.strictObject({ name: z.string().min(1) }),
-        z.strictObject({
-            build: z.strictObject({
-                name: z.string().min(1).optional(),
-                input: z.union([z.string().min(1), z.record(z.string(), z.unknown())]),
-            }),
-        }),
-    ])
-        .optional(),
+    template: Template.optional(),
     launch: z
         .strictObject({
         hardware: z.enum(["nvidia", "none"]).optional(),
@@ -105,6 +110,10 @@ export const DemoSpecSchema = z
         links: z.record(z.string().min(1), relativePath).optional(),
         dashboards: relativePath.optional(),
         params: Params.optional(),
+        norskDir: homePath.optional(),
+        studioDir: homePath.optional(),
+        workdir: homePath.optional(),
+        template: Template.optional(),
     })
         .optional(),
 })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@norskvideo/ctl-test-harness",
-  "version": "0.1.21",
+  "version": "0.1.22",
   "type": "module",
   "exports": {
     ".": {
@@ -59,7 +59,8 @@
   "main": "./index.js",
   "types": "./index.d.ts",
   "bin": {
-    "ctl-demo": "./demo/cli.js"
+    "ctl-demo": "./demo/cli.js",
+    "ctl-dev-loop": "./demo/dev-loop-cli.js"
   },
   "dependencies": {
     "@norskvideo/ctl-sdk": "^0.1.0",