@trillboards/cli 0.1.0 → 0.1.3

package/dist/pty-wrapper.d.ts

@@ -0,0 +1,88 @@
+/**
+ * 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.
+ *
+ * ── REFUSED: rendering the ad INSIDE the agent's own grid ──────────────────────
+ *
+ * There was a standing proposal to make this wrapper draw the ad in the coding
+ * agent's own terminal instead of on a side surface, by same-length byte-patching
+ * the agent binary and re-signing it with `codesign`, or by `DYLD_INSERT_LIBRARIES`
+ * interposing its write path. Both are technically achievable. Neither is being
+ * built, and the reason belongs here rather than in a tracking list, because this
+ * `onData` tee is exactly the code it would replace.
+ *
+ * 1. IT BREAKS THE THING IT INJECTS INTO. Patching a vendor's binary invalidates
+ *    that vendor's code signature. Re-signing it with OUR certificate makes us the
+ *    attesting party for someone else's software, and on macOS a re-signed binary
+ *    loses the notarization and the entitlements the original shipped with. A
+ *    DYLD interpose is the same trespass at runtime: it puts our code inside a
+ *    process the user trusts with their source tree and their credentials. An ad
+ *    surface is not a good enough reason to hold either of those.
+ *
+ * 2. THE FAIL-OPEN PROMISE CANNOT BE KEPT. Everything else here is safe because
+ *    it is ADDITIVE — `onData` copies bytes, it never rewrites them, so a bug in
+ *    ad logic cannot corrupt the agent's display. A compositor that reserves rows
+ *    inside the agent's grid has to rewrite cursor and scroll-region sequences it
+ *    does not own, and there is no version of that which degrades to "the agent
+ *    looks normal". "Behind a flag, fail-open" describes a fallback this design
+ *    does not have.
+ *
+ * The refusal rests on 1 and 2, which are properties of the technique itself.
+ *
+ * RETRACTED — "it would ship to nobody". An earlier version of this note gave a
+ * third reason: that `@trillboards/cli` was stuck at 0.1.1 and the whole Leg A
+ * surface was unpublished. That is FALSE, and it is recorded here because it is
+ * an easy thing to re-derive wrongly from `publish-cli.yml`'s skip-if-published
+ * branch. npm's `gitHead` for 0.1.1 is `01696a57`, that commit IS an ancestor of
+ * `production`, and there are ZERO commits to `trillboards-cli/` after it — so
+ * the published tarball is current and Leg A has been installable since
+ * 2026-06-21. Do not repeat the claim, and do not weigh distribution as an
+ * argument here at all: it would not save this design if it were true, and it is
+ * not true.
+ *
+ * If this is ever revisited, the prerequisite is a way to render inside another
+ * process that does not forge that process's signature and can genuinely fail
+ * open — not a better patching technique, and not a distribution milestone.
+ */
+import type { VirtualScreenCreative } from './ads-client.js';
+import type { SurfaceCapabilities } from './capability.js';
+/** True iff the optional node-pty native module loaded — i.e. `code` can ad-wrap. */
+export declare function isPtyAvailable(): boolean;
+export interface WrapperDeps {
+    caps: SurfaceCapabilities;
+    capabilitiesParam: string;
+    /** Fetch the best creative for our surface (returns null on no-fill). */
+    fetchCreative: (capabilitiesParam: string) => Promise<VirtualScreenCreative | null>;
+    /** Report the impression (best-effort telemetry; the wrapper never blocks on it). */
+    reportImpression: (creative: VirtualScreenCreative) => Promise<unknown>;
+    /**
+     * Fire the server-signed completion beacon when an ad finishes playing
+     * (play-and-count; the billable agent_direct signal). Best-effort, non-blocking.
+     */
+    reportCompletion: (creative: VirtualScreenCreative) => Promise<unknown>;
+    /** Keep the virtual screen online for serving/billing. */
+    heartbeat: () => Promise<unknown>;
+    /** Minimum gap between ads (frequency cap). */
+    intervalMs: number;
+}
+/**
+ * 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 declare function runWrappedAgent(agent: string, agentArgs: string[], deps: WrapperDeps): Promise<number>;
+/**
+ * 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 declare function runAgentPassthrough(agent: string, agentArgs: string[]): Promise<number>;

package/dist/pty-wrapper.js

@@ -0,0 +1,287 @@
+/**
+ * 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.
+ *
+ * ── REFUSED: rendering the ad INSIDE the agent's own grid ──────────────────────
+ *
+ * There was a standing proposal to make this wrapper draw the ad in the coding
+ * agent's own terminal instead of on a side surface, by same-length byte-patching
+ * the agent binary and re-signing it with `codesign`, or by `DYLD_INSERT_LIBRARIES`
+ * interposing its write path. Both are technically achievable. Neither is being
+ * built, and the reason belongs here rather than in a tracking list, because this
+ * `onData` tee is exactly the code it would replace.
+ *
+ * 1. IT BREAKS THE THING IT INJECTS INTO. Patching a vendor's binary invalidates
+ *    that vendor's code signature. Re-signing it with OUR certificate makes us the
+ *    attesting party for someone else's software, and on macOS a re-signed binary
+ *    loses the notarization and the entitlements the original shipped with. A
+ *    DYLD interpose is the same trespass at runtime: it puts our code inside a
+ *    process the user trusts with their source tree and their credentials. An ad
+ *    surface is not a good enough reason to hold either of those.
+ *
+ * 2. THE FAIL-OPEN PROMISE CANNOT BE KEPT. Everything else here is safe because
+ *    it is ADDITIVE — `onData` copies bytes, it never rewrites them, so a bug in
+ *    ad logic cannot corrupt the agent's display. A compositor that reserves rows
+ *    inside the agent's grid has to rewrite cursor and scroll-region sequences it
+ *    does not own, and there is no version of that which degrades to "the agent
+ *    looks normal". "Behind a flag, fail-open" describes a fallback this design
+ *    does not have.
+ *
+ * The refusal rests on 1 and 2, which are properties of the technique itself.
+ *
+ * RETRACTED — "it would ship to nobody". An earlier version of this note gave a
+ * third reason: that `@trillboards/cli` was stuck at 0.1.1 and the whole Leg A
+ * surface was unpublished. That is FALSE, and it is recorded here because it is
+ * an easy thing to re-derive wrongly from `publish-cli.yml`'s skip-if-published
+ * branch. npm's `gitHead` for 0.1.1 is `01696a57`, that commit IS an ancestor of
+ * `production`, and there are ZERO commits to `trillboards-cli/` after it — so
+ * the published tarball is current and Leg A has been installable since
+ * 2026-06-21. Do not repeat the claim, and do not weigh distribution as an
+ * argument here at all: it would not save this design if it were true, and it is
+ * not true.
+ *
+ * If this is ever revisited, the prerequisite is a way to render inside another
+ * process that does not forge that process's signature and can genuinely fail
+ * open — not a better patching technique, and not a distribution milestone.
+ */
+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;