@norskvideo/ctl-test-harness 0.1.21 → 0.1.23

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}`;
@@ -414,8 +421,15 @@ class DemoSession {
             join(this.storeDir, "norsk-runtime"),
             "--proxy-port",
             String(this.ports.proxyPort),
+            // A throwaway daemon on a banded port has nothing to protect, and its
+            // /instance/<id>/... routes (the visualiser a gate reads, the `open`
+            // URLs) must answer without a session: with oauth on, the compose gate
+            // read the sign-in page as "0 frames" for 180s (playout CI, 2026-08-29).
+            "--proxy-auth",
+            "none",
             "--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 +487,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 +646,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 +742,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 +822,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 +896,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 +907,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>;