@trillboards/cli 0.1.0 → 0.1.1

package/dist/pty-wrapper.js

@@ -0,0 +1,245 @@
+/**
+ * The `trillboards code` PTY wrapper core.
+ *
+ * Spawns the real coding agent under a pseudo-terminal we own, and passes bytes
+ * through verbatim in both directions — so the agent (Claude Code / Codex / …) runs
+ * byte-for-byte normally (alt-screen, raw mode, resize, paste all flow through). We
+ * only TEE the agent's output into the dead-time detector; when the agent starts
+ * "thinking", we play an ad on a side surface, and tear it down when it resumes.
+ *
+ * This is the I/O glue — the decision logic (dead-time, capability, render commands,
+ * fetch) all lives in unit-tested pure modules. Never lets ad logic break the agent.
+ */
+import { spawn as childSpawn } from 'node:child_process';
+import { createRequire } from 'node:module';
+import { DeadTimeDetector } from './dead-time.js';
+import { renderCreative } from './render-runner.js';
+// node-pty is an OPTIONAL native dependency: it ships prebuilds for darwin/win32 only —
+// no Linux prebuild — so a plain `npm i -g @trillboards/cli` would FAIL the C++ rebuild on
+// Linux/Docker/Codespaces/WSL without python3+make+g++. It now lives in
+// `optionalDependencies`, so a failed build is non-fatal (the package still installs and
+// every other command works), and we LAZY-require it here (ESM → createRequire) so merely
+// importing this module never throws. `trillboards code` checks isPtyAvailable() and
+// degrades to a transparent passthrough (runAgentPassthrough) when it's absent.
+const _require = createRequire(import.meta.url);
+let _ptySpawn;
+function loadPtySpawn() {
+    if (_ptySpawn !== undefined)
+        return _ptySpawn;
+    try {
+        _ptySpawn = _require('node-pty').spawn;
+    }
+    catch {
+        _ptySpawn = null;
+    }
+    return _ptySpawn;
+}
+/** True iff the optional node-pty native module loaded — i.e. `code` can ad-wrap. */
+export function isPtyAvailable() {
+    return loadPtySpawn() !== null;
+}
+const HEARTBEAT_MS = 30_000;
+const TICK_MS = 250;
+/** Minimum on-screen time before a play-and-count completion is reported as billable. */
+const MIN_PLAY_MS = 1000;
+/**
+ * Run the agent under a PTY and serve ads into its dead-time. Resolves with the
+ * agent's exit code. Restores the terminal + tears down all timers/renders on exit.
+ */
+export function runWrappedAgent(agent, agentArgs, deps) {
+    return new Promise((resolve) => {
+        const renderCtx = { caps: deps.caps, inTmux: Boolean(process.env.TMUX), platform: process.platform };
+        let lastShownAt = 0;
+        let currentRender = null;
+        let currentCreative = null;
+        // When the ad actually became visible (render assigned) — NOT the dead-time
+        // entry. Creative fetch + render take non-trivial time; measuring play time
+        // from here avoids reporting a completion for an ad shown < MIN_PLAY_MS (codex).
+        let renderStartedAt = 0;
+        const closeRender = () => {
+            // Capture before clearing so the completion fires for the ad that was just shown.
+            const shownCreative = currentRender ? currentCreative : null;
+            const shownMs = currentRender ? Date.now() - renderStartedAt : 0;
+            if (currentRender) {
+                try {
+                    currentRender.close();
+                }
+                catch {
+                    /* ignore */
+                }
+                currentRender = null;
+            }
+            currentCreative = null;
+            // Play-and-count: the ad was displayed through this dead-time window and is
+            // now torn down. Fire the server-signed completion beacon (the billable
+            // agent_direct signal) iff it was on screen long enough to count as a play.
+            if (shownCreative && shownMs >= MIN_PLAY_MS) {
+                void deps.reportCompletion(shownCreative).catch(() => { });
+            }
+        };
+        const onDeadTimeEnter = () => {
+            const now = Date.now();
+            if (now - lastShownAt < deps.intervalMs)
+                return; // frequency cap
+            lastShownAt = now;
+            // Fire-and-forget: fetch + render + report must never block the agent.
+            void (async () => {
+                let creative = null;
+                try {
+                    creative = await deps.fetchCreative(deps.capabilitiesParam);
+                }
+                catch {
+                    return;
+                }
+                if (!creative)
+                    return;
+                let handle = null;
+                try {
+                    handle = renderCreative(creative, renderCtx);
+                }
+                catch {
+                    return;
+                }
+                // Nothing rendered (no surface for this creative) → never report an unshown ad.
+                if (!handle)
+                    return;
+                currentRender = handle;
+                currentCreative = creative;
+                renderStartedAt = Date.now(); // ad is now visible — billable play clock starts here
+                try {
+                    await deps.reportImpression(creative);
+                }
+                catch {
+                    /* ignore */
+                }
+            })();
+        };
+        const detector = new DeadTimeDetector({ onEnter: onDeadTimeEnter, onExit: closeRender }, { spinnerStartMs: 300, spinnerStopMs: 1500 });
+        const ptySpawn = loadPtySpawn();
+        if (!ptySpawn) {
+            // node-pty unavailable (e.g. a Linux install with no compiler) — run the agent
+            // verbatim, un-wrapped, so the developer is NEVER blocked. (code.ts gates on
+            // isPtyAvailable() to print guidance first; this is the belt-and-suspenders.)
+            runAgentPassthrough(agent, agentArgs).then(resolve, () => resolve(1));
+            return;
+        }
+        const cols = process.stdout.columns || 80;
+        const rows = process.stdout.rows || 24;
+        const term = ptySpawn(agent, agentArgs, {
+            name: process.env.TERM || 'xterm-256color',
+            cols,
+            rows,
+            cwd: process.cwd(),
+            env: process.env,
+        });
+        // ── agent output → our stdout + the dead-time detector ──
+        term.onData((data) => {
+            try {
+                process.stdout.write(data);
+            }
+            catch {
+                /* ignore */
+            }
+            detector.feed(data);
+        });
+        // ── our stdin (raw) → the agent; a keystroke also ends dead-time ──
+        const stdin = process.stdin;
+        if (stdin.isTTY) {
+            try {
+                stdin.setRawMode(true);
+            }
+            catch {
+                /* ignore */
+            }
+        }
+        stdin.resume();
+        const onStdin = (data) => {
+            try {
+                term.write(data.toString('utf8'));
+            }
+            catch {
+                /* ignore */
+            }
+            detector.onUserInput();
+        };
+        stdin.on('data', onStdin);
+        // ── resize passthrough (the kernel won't propagate it to the pty) ──
+        const onResize = () => {
+            try {
+                term.resize(process.stdout.columns || cols, process.stdout.rows || rows);
+            }
+            catch {
+                /* ignore */
+            }
+        };
+        process.stdout.on('resize', onResize);
+        const tick = setInterval(() => detector.tick(), TICK_MS);
+        const beat = setInterval(() => {
+            void deps.heartbeat().catch(() => { });
+        }, HEARTBEAT_MS);
+        void deps.heartbeat().catch(() => { }); // immediate first heartbeat → online for serving
+        let settled = false;
+        const cleanup = () => {
+            if (settled)
+                return;
+            settled = true;
+            clearInterval(tick);
+            clearInterval(beat);
+            closeRender();
+            stdin.removeListener('data', onStdin);
+            process.stdout.removeListener('resize', onResize);
+            try {
+                if (stdin.isTTY)
+                    stdin.setRawMode(false);
+            }
+            catch {
+                /* ignore */
+            }
+            stdin.pause();
+        };
+        term.onExit(({ exitCode }) => {
+            cleanup();
+            resolve(exitCode ?? 0);
+        });
+        // If the parent is asked to quit, take the agent down with us.
+        const onSig = () => {
+            try {
+                term.kill();
+            }
+            catch {
+                /* ignore */
+            }
+        };
+        process.on('SIGINT', onSig);
+        process.on('SIGTERM', onSig);
+    });
+}
+/**
+ * Run the agent verbatim with inherited stdio (NO ad-wrapping). The graceful fallback
+ * when node-pty is unavailable — the developer's coding agent works exactly as normal;
+ * they just don't earn from `code` here (they can run `trillboards ads enable`, the text
+ * hook, which needs no native deps and works in every terminal). Resolves with the
+ * agent's exit code.
+ */
+export function runAgentPassthrough(agent, agentArgs) {
+    return new Promise((resolve) => {
+        const child = childSpawn(agent, agentArgs, { stdio: 'inherit', env: process.env });
+        const onSig = () => {
+            try {
+                child.kill();
+            }
+            catch {
+                /* ignore */
+            }
+        };
+        process.on('SIGINT', onSig);
+        process.on('SIGTERM', onSig);
+        const settle = (code) => {
+            process.removeListener('SIGINT', onSig);
+            process.removeListener('SIGTERM', onSig);
+            resolve(code);
+        };
+        child.on('exit', (code) => settle(code ?? 0));
+        child.on('error', () => settle(127)); // command-not-found etc.
+    });
+}

package/dist/render-runner.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Render-runner: the I/O half of the render adapters. Given a creative + the host
+ * context, it spawns the actual player (mpv in a tmux split pane, timg for an image,
+ * a text line in a tmux split, or a spawned mpv window) and returns a handle to tear
+ * it down when dead-time ends. The command *construction* lives in render.ts (pure,
+ * unit-tested); this file only does process spawning, so it stays thin + best-effort.
+ *
+ * IMPORTANT: returns `null` when nothing was actually rendered (no surface for this
+ * creative). The caller MUST skip impression reporting on null — never report an ad
+ * that wasn't shown.
+ */
+import type { VirtualScreenCreative } from './ads-client.js';
+import type { SurfaceCapabilities } from './capability.js';
+export interface RenderHandle {
+    /** Tear down the render (kill the tmux pane / mpv window) if it's still up. */
+    close(): void;
+}
+export interface RenderContext {
+    caps: SurfaceCapabilities;
+    inTmux: boolean;
+    platform: NodeJS.Platform;
+}
+/** Play a video creative; returns a handle, or null if it couldn't render. */
+export declare function renderVideo(url: string, ctx: RenderContext): RenderHandle | null;
+/** Show an image creative inline (tmux split running timg). Null when no tmux surface. */
+export declare function renderImage(url: string, ctx: RenderContext): RenderHandle | null;
+/** Show a one-line text creative in a tmux split. Null when no tmux surface. */
+export declare function renderText(creative: VirtualScreenCreative, ctx: RenderContext): RenderHandle | null;
+/**
+ * Surface a programmatic (Leg A) fill. In tmux: a clickable OSC-8 link to the hosted IMA
+ * player in a non-modal split pane (the dev clicks; the runner kills the pane when dead-time
+ * ends). Outside tmux (VS Code / Cursor / plain): open the player in the default browser —
+ * the webview IS the Leg A surface. Either way the player runs the served VAST through the
+ * Google IMA SDK (the exact path the screen app uses) and bills via the wrap's signed
+ * vast_event pixels, independent of this handle's lifetime. Null only when the creative
+ * carries no playable IMA player URL.
+ */
+export declare function renderProgrammatic(creative: VirtualScreenCreative, ctx: RenderContext): RenderHandle | null;
+/**
+ * Dispatch a creative to the right renderer. Returns a handle, or NULL when nothing
+ * was rendered (the caller must then skip the impression report).
+ *
+ * Leg A (programmatic) takes precedence: a real-CPM VAST fill outranks the direct/house
+ * creative the same fetch may carry. A creative with an `imaPlayerUrl` is Leg A or nothing
+ * — we never fall through to a Leg B render for it, so the completion path stays
+ * unambiguous (Leg A bills via vast_event, Leg B via the agent_direct beacon).
+ */
+export declare function renderCreative(creative: VirtualScreenCreative, ctx: RenderContext): RenderHandle | null;

package/dist/render-runner.js

@@ -0,0 +1,151 @@
+/**
+ * Render-runner: the I/O half of the render adapters. Given a creative + the host
+ * context, it spawns the actual player (mpv in a tmux split pane, timg for an image,
+ * a text line in a tmux split, or a spawned mpv window) and returns a handle to tear
+ * it down when dead-time ends. The command *construction* lives in render.ts (pure,
+ * unit-tested); this file only does process spawning, so it stays thin + best-effort.
+ *
+ * IMPORTANT: returns `null` when nothing was actually rendered (no surface for this
+ * creative). The caller MUST skip impression reporting on null — never report an ad
+ * that wasn't shown.
+ */
+import { spawn } from 'node:child_process';
+import { buildImagePlayback, planProgrammaticPlayback, planVideoPlayback, renderTextLine, shellQuote } from './render.js';
+function killTmuxPane(paneId) {
+    const id = paneId.trim();
+    if (!id)
+        return;
+    try {
+        spawn('tmux', ['kill-pane', '-t', id], { stdio: 'ignore' }).on('error', () => { });
+    }
+    catch {
+        /* ignore */
+    }
+}
+/** Spawn a tmux split pane running `innerCmd`; returns a handle that kills the pane. */
+function tmuxSplitPane(innerCmd, sizePct) {
+    let paneId = '';
+    const child = spawn('tmux', ['split-window', '-d', '-P', '-F', '#{pane_id}', '-l', `${sizePct}%`, innerCmd], {
+        stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    child.stdout?.on('data', (d) => {
+        paneId += d.toString();
+    });
+    child.on('error', () => { });
+    return { close: () => killTmuxPane(paneId) };
+}
+/** Play a video creative; returns a handle, or null if it couldn't render. */
+export function renderVideo(url, ctx) {
+    try {
+        const plan = planVideoPlayback(url, { inTmux: ctx.inTmux, videoCapable: ctx.caps.video, platform: ctx.platform });
+        if (plan.strategy === 'tmux-pane') {
+            let paneId = '';
+            const child = spawn(plan.spec.bin, plan.spec.args, { stdio: ['ignore', 'pipe', 'ignore'] });
+            child.stdout?.on('data', (d) => {
+                paneId += d.toString();
+            });
+            child.on('error', () => { });
+            return { close: () => killTmuxPane(paneId) };
+        }
+        // spawn-window: detached mpv window (VS Code / Cursor / no-tmux).
+        const child = spawn(plan.spec.bin, plan.spec.args, { detached: true, stdio: 'ignore' });
+        child.on('error', () => { });
+        child.unref();
+        return {
+            close() {
+                try {
+                    if (child.pid)
+                        child.kill();
+                }
+                catch {
+                    /* ignore */
+                }
+            },
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/** Show an image creative inline (tmux split running timg). Null when no tmux surface. */
+export function renderImage(url, ctx) {
+    try {
+        if (!ctx.inTmux || !ctx.caps.image)
+            return null;
+        const spec = buildImagePlayback(url);
+        const inner = `${spec.bin} ${spec.args.map((a) => (a === url ? shellQuote(a) : a)).join(' ')}; sleep 6`;
+        return tmuxSplitPane(inner, 30);
+    }
+    catch {
+        return null;
+    }
+}
+/** Show a one-line text creative in a tmux split. Null when no tmux surface. */
+export function renderText(creative, ctx) {
+    try {
+        if (!ctx.inTmux || !ctx.caps.text)
+            return null;
+        const line = renderTextLine(creative);
+        if (!line)
+            return null;
+        // printf the styled line (incl. OSC-8) into the split, then hold it briefly.
+        const inner = `printf '%s\\n' ${shellQuote(line)}; sleep 8`;
+        return tmuxSplitPane(inner, 12);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Surface a programmatic (Leg A) fill. In tmux: a clickable OSC-8 link to the hosted IMA
+ * player in a non-modal split pane (the dev clicks; the runner kills the pane when dead-time
+ * ends). Outside tmux (VS Code / Cursor / plain): open the player in the default browser —
+ * the webview IS the Leg A surface. Either way the player runs the served VAST through the
+ * Google IMA SDK (the exact path the screen app uses) and bills via the wrap's signed
+ * vast_event pixels, independent of this handle's lifetime. Null only when the creative
+ * carries no playable IMA player URL.
+ */
+export function renderProgrammatic(creative, ctx) {
+    try {
+        const plan = planProgrammaticPlayback(creative, { inTmux: ctx.inTmux, platform: ctx.platform });
+        if (!plan)
+            return null;
+        if (plan.strategy === 'tmux-link' && plan.line) {
+            const inner = `printf '%s\\n' ${shellQuote(plan.line)}; sleep 60`;
+            return tmuxSplitPane(inner, 18);
+        }
+        if (plan.strategy === 'open-url' && plan.spec) {
+            // No tmux (VS Code/Cursor/plain): open the hosted IMA player in the default browser.
+            // The tab outlives this dead-time and the IMA player bills via vast_event on its own,
+            // so close() is a no-op — we never need to (and can't) tear down the user's tab.
+            const child = spawn(plan.spec.bin, plan.spec.args, { detached: true, stdio: 'ignore' });
+            child.on('error', () => { });
+            child.unref();
+            return { close: () => { } };
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Dispatch a creative to the right renderer. Returns a handle, or NULL when nothing
+ * was rendered (the caller must then skip the impression report).
+ *
+ * Leg A (programmatic) takes precedence: a real-CPM VAST fill outranks the direct/house
+ * creative the same fetch may carry. A creative with an `imaPlayerUrl` is Leg A or nothing
+ * — we never fall through to a Leg B render for it, so the completion path stays
+ * unambiguous (Leg A bills via vast_event, Leg B via the agent_direct beacon).
+ */
+export function renderCreative(creative, ctx) {
+    if (creative.imaPlayerUrl)
+        return renderProgrammatic(creative, ctx);
+    if (creative.mediaType === 'video' && creative.mediaUrl)
+        return renderVideo(creative.mediaUrl, ctx);
+    if (creative.mediaType === 'image' && creative.mediaUrl)
+        return renderImage(creative.mediaUrl, ctx);
+    if (creative.mediaType === 'text')
+        return renderText(creative, ctx);
+    return null;
+}

package/dist/render.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Render adapters for the `trillboards code` wrapper (pure command builders).
+ *
+ * Given the chosen creative + the surface capabilities, render it during dead-time:
+ *   video → mpv in a non-modal tmux split pane where the terminal supports it,
+ *           else a spawned mpv window (VS Code/Cursor/unknown)
+ *   image → timg / kitten icat inline
+ *   text  → an OSC-8 sponsor line written to the wrapper's own output
+ *
+ * The command BUILDERS are pure (return {bin,args}) so they're unit-tested; the
+ * actual spawning lives in render-runner.ts.
+ */
+import type { VirtualScreenCreative } from './ads-client.js';
+/** The render adapters operate on the canonical creative shape from ads-client. */
+export type RenderableCreative = VirtualScreenCreative;
+export interface SpawnSpec {
+    bin: string;
+    args: string[];
+}
+/** POSIX single-quote a string for safe interpolation into a shell command. */
+export declare function shellQuote(s: string): string;
+/**
+ * Build the command to play a video in a NON-MODAL tmux split pane. `-d` keeps focus
+ * (and keystrokes) on the agent's pane — the ad plays beside it without stealing
+ * input; the pane auto-closes when mpv reaches EOF. Each tmux pane is its own grid,
+ * so the agent never repaints over the video. Requires `set -g allow-passthrough on`.
+ * `-P -F '#{pane_id}'` prints the new pane id so the runner can kill it early.
+ */
+export declare function buildTmuxPaneVideo(url: string, sizePct?: number): SpawnSpec;
+/** Build the command to play a video in mpv's OWN window (fallback: VS Code/Cursor/no-tmux). */
+export declare function buildSpawnWindowVideo(url: string, platform?: NodeJS.Platform): SpawnSpec;
+/** Build the inline-image command (timg auto-detects kitty/iTerm2/sixel). */
+export declare function buildImagePlayback(url: string): SpawnSpec;
+/**
+ * Build the OS command to open a URL in the user's default browser — the Leg A webview
+ * surface (VS Code / Cursor / any no-tmux terminal). This is where AdX/IMA legitimately
+ * runs (a real DOM), and it mirrors how a Leg B video spawns its own window off-tmux.
+ */
+export declare function buildOpenUrl(url: string, platform?: NodeJS.Platform): SpawnSpec;
+/** The plain-text sponsor line (reuses the shipped `buildSponsorMessage`). */
+export declare function renderTextLine(creative: RenderableCreative): string | null;
+/**
+ * The programmatic (Leg A) line: sanctioned disclosure + an OSC-8 clickable link to the
+ * hosted IMA player, plus the raw URL as a fallback for terminals without OSC-8. Clicking
+ * opens the player in a browser/webview, which runs the served VAST via the Google IMA SDK
+ * (the same path the screen app uses) and bills via the wrap's signed vast_event pixels.
+ * Returns null when the creative carries no playable IMA player URL.
+ */
+export declare function renderProgrammaticLine(creative: RenderableCreative): string | null;
+export interface ProgrammaticStrategy {
+    strategy: 'tmux-link' | 'open-url';
+    /** 'tmux-link': the styled OSC-8 line to print in a non-modal pane. */
+    line?: string;
+    /** 'open-url': the OS command that opens the hosted IMA player in the default browser. */
+    spec?: SpawnSpec;
+}
+/**
+ * Decide HOW to surface a Leg A (programmatic) fill: a clickable OSC-8 link in a non-modal
+ * tmux pane when we're in tmux, else open the hosted IMA player in the default browser.
+ * The no-tmux branch is the VS Code / Cursor / plain-terminal "webview" surface — opening a
+ * browser is the only way to run AdX/IMA there (it needs a real DOM), and it mirrors how a
+ * Leg B video spawns its own window off-tmux. So a programmatic fill is ALWAYS renderable
+ * on some surface — never dropped just because there's no tmux (the bug Codex flagged).
+ * Null only when the creative carries no playable IMA player URL.
+ */
+export declare function planProgrammaticPlayback(creative: RenderableCreative, env: {
+    inTmux: boolean;
+    platform?: NodeJS.Platform;
+}): ProgrammaticStrategy | null;
+export interface VideoStrategy {
+    strategy: 'tmux-pane' | 'spawn-window';
+    spec: SpawnSpec;
+}
+/**
+ * Decide HOW to play a video for this surface: a non-modal tmux split pane when we're
+ * in tmux on a video-capable terminal, else a spawned mpv window.
+ */
+export declare function planVideoPlayback(url: string, opts: {
+    inTmux: boolean;
+    videoCapable: boolean;
+    platform?: NodeJS.Platform;
+}): VideoStrategy;

package/dist/render.js

@@ -0,0 +1,124 @@
+/**
+ * Render adapters for the `trillboards code` wrapper (pure command builders).
+ *
+ * Given the chosen creative + the surface capabilities, render it during dead-time:
+ *   video → mpv in a non-modal tmux split pane where the terminal supports it,
+ *           else a spawned mpv window (VS Code/Cursor/unknown)
+ *   image → timg / kitten icat inline
+ *   text  → an OSC-8 sponsor line written to the wrapper's own output
+ *
+ * The command BUILDERS are pure (return {bin,args}) so they're unit-tested; the
+ * actual spawning lives in render-runner.ts.
+ */
+import { buildSponsorMessage } from './agent-hook.js';
+import { colorize, osc8 } from './format-helpers.js';
+/** Sanctioned, disclosed copy for the programmatic (Leg A) video link shown in dead-time. */
+const SANCTIONED_PROGRAMMATIC_LINE = 'Sponsored — your idle agent earned you a paid impression. Tap to play the video ad:';
+/** mpv flags that make `--vo=kitty` play smoothly (Ghostty needs shm+really-quiet). */
+const MPV_TERMINAL_FLAGS = [
+    '--vo=kitty',
+    '--vo-kitty-use-shm=yes',
+    '--profile=sw-fast',
+    '--really-quiet',
+    '--no-input-default-bindings',
+    '--loop=no',
+];
+/** POSIX single-quote a string for safe interpolation into a shell command. */
+export function shellQuote(s) {
+    return `'${s.replace(/'/g, `'\\''`)}'`;
+}
+/**
+ * Build the command to play a video in a NON-MODAL tmux split pane. `-d` keeps focus
+ * (and keystrokes) on the agent's pane — the ad plays beside it without stealing
+ * input; the pane auto-closes when mpv reaches EOF. Each tmux pane is its own grid,
+ * so the agent never repaints over the video. Requires `set -g allow-passthrough on`.
+ * `-P -F '#{pane_id}'` prints the new pane id so the runner can kill it early.
+ */
+export function buildTmuxPaneVideo(url, sizePct = 35) {
+    const inner = `mpv ${MPV_TERMINAL_FLAGS.join(' ')} ${shellQuote(url)}`;
+    return {
+        bin: 'tmux',
+        args: ['split-window', '-d', '-P', '-F', '#{pane_id}', '-l', `${sizePct}%`, inner],
+    };
+}
+/** Build the command to play a video in mpv's OWN window (fallback: VS Code/Cursor/no-tmux). */
+export function buildSpawnWindowVideo(url, platform = process.platform) {
+    if (platform === 'darwin')
+        return { bin: 'open', args: ['-na', 'mpv', '--args', url] };
+    if (platform === 'win32')
+        return { bin: 'mpv', args: [url] };
+    // Linux/other: mpv opens its own window via the default VO.
+    return { bin: 'mpv', args: [url] };
+}
+/** Build the inline-image command (timg auto-detects kitty/iTerm2/sixel). */
+export function buildImagePlayback(url) {
+    // timg auto-selects the best inline-graphics protocol; -g bounds the cell box.
+    return { bin: 'timg', args: ['-g', '60x30', '--upscale', url] };
+}
+/**
+ * Build the OS command to open a URL in the user's default browser — the Leg A webview
+ * surface (VS Code / Cursor / any no-tmux terminal). This is where AdX/IMA legitimately
+ * runs (a real DOM), and it mirrors how a Leg B video spawns its own window off-tmux.
+ */
+export function buildOpenUrl(url, platform = process.platform) {
+    if (platform === 'darwin')
+        return { bin: 'open', args: [url] };
+    if (platform === 'win32')
+        return { bin: 'cmd', args: ['/c', 'start', '', url] };
+    // Linux/other: xdg-open routes to the registered default browser.
+    return { bin: 'xdg-open', args: [url] };
+}
+/** The plain-text sponsor line (reuses the shipped `buildSponsorMessage`). */
+export function renderTextLine(creative) {
+    const ad = {
+        adId: creative.adId,
+        name: creative.name,
+        description: creative.description,
+        campaignLink: creative.campaignLink,
+        variantName: creative.variantName,
+    };
+    return buildSponsorMessage(ad);
+}
+/**
+ * The programmatic (Leg A) line: sanctioned disclosure + an OSC-8 clickable link to the
+ * hosted IMA player, plus the raw URL as a fallback for terminals without OSC-8. Clicking
+ * opens the player in a browser/webview, which runs the served VAST via the Google IMA SDK
+ * (the same path the screen app uses) and bills via the wrap's signed vast_event pixels.
+ * Returns null when the creative carries no playable IMA player URL.
+ */
+export function renderProgrammaticLine(creative) {
+    if (!creative.imaPlayerUrl)
+        return null;
+    const link = osc8(creative.imaPlayerUrl, colorize('▶ Play sponsored video', 'green'));
+    return `${colorize(SANCTIONED_PROGRAMMATIC_LINE, 'bold')}\n  ${link}\n  ${colorize(creative.imaPlayerUrl, 'dim')}`;
+}
+/**
+ * Decide HOW to surface a Leg A (programmatic) fill: a clickable OSC-8 link in a non-modal
+ * tmux pane when we're in tmux, else open the hosted IMA player in the default browser.
+ * The no-tmux branch is the VS Code / Cursor / plain-terminal "webview" surface — opening a
+ * browser is the only way to run AdX/IMA there (it needs a real DOM), and it mirrors how a
+ * Leg B video spawns its own window off-tmux. So a programmatic fill is ALWAYS renderable
+ * on some surface — never dropped just because there's no tmux (the bug Codex flagged).
+ * Null only when the creative carries no playable IMA player URL.
+ */
+export function planProgrammaticPlayback(creative, env) {
+    if (!creative.imaPlayerUrl)
+        return null;
+    if (env.inTmux) {
+        const line = renderProgrammaticLine(creative);
+        if (!line)
+            return null;
+        return { strategy: 'tmux-link', line };
+    }
+    return { strategy: 'open-url', spec: buildOpenUrl(creative.imaPlayerUrl, env.platform ?? process.platform) };
+}
+/**
+ * Decide HOW to play a video for this surface: a non-modal tmux split pane when we're
+ * in tmux on a video-capable terminal, else a spawned mpv window.
+ */
+export function planVideoPlayback(url, opts) {
+    if (opts.inTmux && opts.videoCapable) {
+        return { strategy: 'tmux-pane', spec: buildTmuxPaneVideo(url) };
+    }
+    return { strategy: 'spawn-window', spec: buildSpawnWindowVideo(url, opts.platform) };
+}