@workflow-manager/runner 0.6.0 → 0.7.0

package/README.md

@@ -78,7 +78,7 @@ Use `wfm doctor` to inspect host adapter setup and `wfm doctor <workflow>` to va
 
 During `wfm run`, the CLI starts a local attach API on `127.0.0.1`. Use `--port <n>` to bind a fixed port or omit it to let the OS choose one. The CLI prints the attach base URL and bearer token before execution starts.
 
-By default, `wfm run` now prints live workflow progress to stderr with the current step, elapsed workflow time, and remaining step count. Pass `--verbose` to stream per-step agent output chunks and execution status updates while the workflow is running. When a human approval is required in an interactive terminal, the CLI now prints an approval summary and prompts for approve or cancel inline.
+By default, `wfm run` now prints live workflow progress to stderr with the current step, elapsed workflow time, and remaining step count. Pass `--verbose` to stream per-step agent output chunks and execution status updates while the workflow is running. When a human approval is required in an interactive terminal, the CLI now prints an approval summary and prompts for approve or cancel inline. Pass `--ui` for a full-screen terminal UI with a live step list and per-step activity pane instead (falls back to standard output when stdin/stdout aren't an interactive terminal); see `doc/guide/terminal-ui.md`.
 
 Runner API endpoints include:
 

package/dist/cliRunRenderer.js

@@ -1,56 +1,4 @@
-function isTerminalStatus(status) {
-    return status === "succeeded" || status === "failed" || status === "cancelled";
-}
-function formatCount(value, singular, plural) {
-    return `${value} ${value === 1 ? singular : plural}`;
-}
-function formatDurationMs(value) {
-    if (!Number.isFinite(value) || value < 0) {
-        return "0s";
-    }
-    if (value < 1000) {
-        return `${Math.max(0, Math.round(value))}ms`;
-    }
-    const seconds = value / 1000;
-    if (seconds < 60) {
-        return `${seconds.toFixed(seconds < 10 ? 1 : 0)}s`;
-    }
-    const minutes = Math.floor(seconds / 60);
-    const remainingSeconds = Math.round(seconds % 60);
-    return `${minutes}m ${remainingSeconds}s`;
-}
-function elapsedFrom(iso) {
-    if (!iso) {
-        return "0s";
-    }
-    const startedAt = Date.parse(iso);
-    if (Number.isNaN(startedAt)) {
-        return "0s";
-    }
-    return formatDurationMs(Date.now() - startedAt);
-}
-function splitLines(value) {
-    const normalized = value.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
-    const parts = normalized.split("\n");
-    const remainder = parts.pop() ?? "";
-    return { lines: parts, remainder };
-}
-function describeAgentStatus(status) {
-    switch (status) {
-        case "running":
-            return "started";
-        case "succeeded":
-            return "succeeded";
-        case "failed":
-            return "failed";
-        case "waiting_for_approval":
-            return "waiting for approval";
-        case "cancelled":
-            return "cancelled";
-        default:
-            return status.replace(/_/g, " ");
-    }
-}
+import { describeAgentStatus, elapsedFrom, formatCount, isTerminalStatus, splitLines, stepLabel, } from "./runFormat.js";
 export class CliRunRenderer {
     verbose;
     stream;
@@ -281,6 +229,3 @@ export class CliRunRenderer {
         this.stream.write(`${line}\n`);
     }
 }
-function stepLabel(step) {
-    return step.title ?? step.objective ?? step.key;
-}

package/dist/index.js

@@ -7,6 +7,7 @@ import { spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import matter from "gray-matter";
 import { CliRunRenderer } from "./cliRunRenderer.js";
+import { TuiRunRenderer } from "./tui/tuiRunRenderer.js";
 import { startRunnerApiServer } from "./runnerApi.js";
 import { RunnerSessionStore } from "./runnerSession.js";
 import { parseWorkflowFile, validateWorkflow } from "./parser.js";
@@ -55,7 +56,7 @@ function usage() {
         row("scaffold [path]", "Write a starter workflow file"),
         row("validate <file>", "Check a workflow for errors"),
         row("doctor [file]", "Check host setup; with a file, preflight it"),
-        row("run <file>", "Run a workflow with live progress"),
+        row("run <file>", "Run a workflow with live progress (--ui for full-screen)"),
         "",
         "Control a running workflow",
         row("approve", "Approve a step waiting for review"),
@@ -688,6 +689,7 @@ async function cmdRun(filePath) {
     let runnerServer;
     let sessionStore;
     let liveRenderer;
+    let tuiRenderer;
     try {
         workflow = parseWorkflowFile(resolvedPath);
         const errors = validateWorkflow(workflow);
@@ -729,57 +731,78 @@ async function cmdRun(filePath) {
             console.error("--port must be an integer between 0 and 65535");
             return 1;
         }
+        const wantUi = hasFlag("--ui");
+        const useTui = wantUi && process.stdout.isTTY === true && process.stdin.isTTY === true;
+        if (wantUi && !useTui) {
+            process.stderr.write("⚠ --ui requires an interactive terminal; falling back to standard output\n");
+        }
         sessionStore = new RunnerSessionStore({
             runId,
             workflow,
             objective: objective ?? workflow.title,
             objectives: workflow.objectives ?? [],
         });
-        liveRenderer = new CliRunRenderer({
-            workflow,
-            verbose: hasFlag("--verbose"),
-        });
+        if (!useTui) {
+            liveRenderer = new CliRunRenderer({
+                workflow,
+                verbose: hasFlag("--verbose"),
+            });
+        }
         runnerServer = await startRunnerApiServer(sessionStore, requestedPort);
         const session = sessionStore.sessionInfo();
-        process.stderr.write(`Attach API: ${session.baseUrl} (token ${session.attachToken})\n`);
+        if (!useTui) {
+            process.stderr.write(`Attach API: ${session.baseUrl} (token ${session.attachToken})\n`);
+        }
+        if (useTui) {
+            tuiRenderer = new TuiRunRenderer({
+                workflow,
+                session: sessionStore,
+                attachUrl: session.baseUrl,
+                attachToken: session.attachToken,
+            });
+            tuiRenderer.start();
+        }
         const result = await runWorkflow(workflow, {
             runId,
             objective,
             input,
             confirmations,
             autoConfirmAll: hasFlag("--auto-confirm-all"),
-            interactive: process.stdin.isTTY,
+            interactive: useTui ? false : process.stdin.isTTY,
             workflowFilePath: resolvedPath,
-            approvalPrompt: async (request) => {
-                liveRenderer?.pauseHeartbeat();
-                try {
-                    const decision = await promptForApprovalDecision(request.stepKey, request.reason, request.validation ?? "external", request.preview ?? null, "cli", request.signal);
-                    if (!decision) {
+            approvalPrompt: useTui
+                ? undefined
+                : async (request) => {
+                    liveRenderer?.pauseHeartbeat();
+                    try {
+                        const decision = await promptForApprovalDecision(request.stepKey, request.reason, request.validation ?? "external", request.preview ?? null, "cli", request.signal);
+                        if (!decision) {
+                            return null;
+                        }
+                        const metadata = {
+                            actor: decision.actor,
+                            note: decision.note,
+                            source: decision.source,
+                        };
+                        const outcome = decision.decision === "cancelled"
+                            ? sessionStore?.cancel(request.stepKey, metadata)
+                            : request.validation === "external"
+                                ? sessionStore?.resume(request.stepKey, metadata)
+                                : sessionStore?.approve(request.stepKey, metadata);
+                        if (outcome && !outcome.ok) {
+                            process.stderr.write(`Could not apply terminal decision for ${request.stepKey}: ${outcome.reason ?? "unknown error"}\n`);
+                        }
                         return null;
                     }
-                    const metadata = {
-                        actor: decision.actor,
-                        note: decision.note,
-                        source: decision.source,
-                    };
-                    const outcome = decision.decision === "cancelled"
-                        ? sessionStore?.cancel(request.stepKey, metadata)
-                        : request.validation === "external"
-                            ? sessionStore?.resume(request.stepKey, metadata)
-                            : sessionStore?.approve(request.stepKey, metadata);
-                    if (outcome && !outcome.ok) {
-                        process.stderr.write(`Could not apply terminal decision for ${request.stepKey}: ${outcome.reason ?? "unknown error"}\n`);
+                    finally {
+                        liveRenderer?.resumeHeartbeat();
                     }
-                    return null;
-                }
-                finally {
-                    liveRenderer?.resumeHeartbeat();
-                }
-            },
-            observer: combineRunObservers(sessionStore, liveRenderer),
+                },
+            observer: combineRunObservers(sessionStore, useTui ? tuiRenderer : liveRenderer),
             controller: sessionStore,
         });
-        liveRenderer.close();
+        tuiRenderer?.stop();
+        liveRenderer?.close();
         if (hasFlag("--json")) {
             console.log(JSON.stringify({ session: sessionStore.sessionInfo(), ...result }, null, 2));
         }
@@ -807,6 +830,7 @@ async function cmdRun(filePath) {
         return result.status === "succeeded" ? 0 : 2;
     }
     catch (err) {
+        tuiRenderer?.stop();
         liveRenderer?.close();
         console.error(`Run error: ${err.message}`);
         if (workflow) {
@@ -820,6 +844,7 @@ async function cmdRun(filePath) {
         return 1;
     }
     finally {
+        tuiRenderer?.stop();
         liveRenderer?.close();
         await runnerServer?.close().catch(() => undefined);
     }

package/dist/manPage.d.ts

@@ -1 +1 @@
-export declare const MAN_PAGE_SOURCE = ".TH WFM 1 \"April 2026\" \"@workflow-manager/runner\" \"User Commands\"\n.SH NAME\nwfm \\- run markdown or json workflows from the CLI\n.SH SYNOPSIS\n.B wfm\n.I command\n[options]\n.SH DESCRIPTION\nwfm parses a workflow definition file, validates it, and executes\nit with deterministic in-memory orchestration.\n\nWorkflow files can be Markdown with YAML frontmatter or JSON.\n.SH COMMANDS\n.TP\n.B doctor [workflow.md|workflow.json] [--json]\nInspect host adapter setup, LLM access keys, and current adapter implementation status. When a workflow path is provided, also validate schema and runtime requirements without executing steps.\n.TP\n.B skill list\nList the agent skills bundled with the npm package.\n.TP\n.B skill install [name ...] [--agent claude|opencode] [--global] [--dir path] [--all] [--force]\nInstall bundled agent skills into an agent skill directory. Defaults to the workflow-manager-cli skill and the project-level Claude Code directory (./.claude/skills). Existing skills are not overwritten unless --force is passed.\n.TP\n.B scaffold [path] [--format markdown|json]\nCreate a starter workflow file. Format defaults to markdown unless the output\npath ends in .json.\n.TP\n.B validate <workflow.md|workflow.json>\nValidate workflow structure and report schema errors.\n.TP\n.B run <workflow.md|workflow.json> [--input input.json] [--objective text] [--confirm list] [--auto-confirm-all] [--port number] [--verbose] [--json]\nRun the workflow with live CLI progress and optional JSON output.\n.TP\n.B approve [--url value] [--token value] [--run-id value] [--step value] [--actor value] [--note text]\nApprove the current waiting runner step through the local attach API.\n.TP\n.B resume [--url value] [--token value] [--run-id value] [--step value] [--actor value] [--note text]\nAlias for approve, intended for external resume flows.\n.TP\n.B cancel [--url value] [--token value] [--run-id value] [--step value] [--actor value] [--note text]\nCancel the current waiting runner step through the local attach API.\n.TP\n.B auth <login|whoami|logout> [--token value]\nManage remote registry authentication for CLI publish and pull flows.\n.TP\n.B publish <workflow.md|workflow.json> [--slug slug] [--title text] [--description text] [--visibility public|private] [--version label] [--tag a,b] [--draft]\nPublish a validated local workflow to the remote registry.\n.TP\n.B pull <owner/slug> [--version label] [--output path]\nDownload a remote workflow and write it to a local file.\n.TP\n.B search [query]\nSearch public workflows from the remote registry.\n.TP\n.B remote info <owner/slug>\nShow metadata and source information for a remote workflow.\n.TP\n.B man\nOpen this man page.\n.TP\n.B --version, -v, version\nPrint the installed wfm version and exit.\n.SH RUN OPTIONS\n.TP\n.B --input <path>\nJSON file merged into global workflow input state.\n.TP\n.B --objective <text>\nOverride the default run objective.\n.TP\n.B --confirm <stepA,stepB:human,...>\nProvide explicit confirmations for steps that require validation.\n.TP\n.B --auto-confirm-all\nBypass confirmation gating for all steps.\n.TP\n.B --port <number>\nBind the local attach API to a specific port. If omitted, the OS assigns a free port on 127.0.0.1.\n.TP\n.B --verbose\nStream per-step agent output and execution updates to stderr while the workflow runs.\n.TP\n.B --json\nPrint the final run result as JSON on stdout while keeping live progress on stderr.\n.TP\nHuman approval steps in an interactive terminal show an inline review prompt so they can be approved or cancelled without a separate HTTP client.\n.TP\n.B --url <value>\nRunner attach API base URL for approve, resume, or cancel commands.\n.TP\n.B --token <value>\nRunner attach API bearer token for approve, resume, or cancel commands.\n.TP\n.B --run-id <value>\nRunner id to control. If omitted, the CLI reads it from /session.\n.TP\n.B --step <value>\nOptional step key when controlling a specific waiting step.\n.TP\n.B --actor <value>\nActor name recorded in approval audit events.\n.TP\n.B --note <text>\nOptional approval or cancellation note recorded in the event payload.\n.SH EXAMPLES\n.TP\nValidate markdown workflow:\n.B wfm validate ./example-workflow.md\n.TP\nValidate json workflow:\n.B wfm validate ./example-workflow.json\n.TP\nScaffold json workflow file:\n.B wfm scaffold ./new-workflow.json --format json\n.TP\nAuthenticate with a CLI token:\n.B wfm auth login --token wm_exampletoken\n.TP\nPublish a workflow:\n.B wfm publish ./example-workflow.json --visibility public --tag example,automation\n.TP\nPull a remote workflow:\n.B wfm pull alice/remote-bunny --output ./remote-bunny.json\n.TP\nSearch the remote registry:\n.B wfm search bunny\n.TP\nRun with explicit confirmations:\n.B wfm run ./example-workflow.json --confirm discover:human,qa_gate:human\n.TP\nInspect host setup:\n.B wfm doctor\n.TP\nCheck a workflow before running it:\n.B wfm doctor ./example-workflow.json\n.TP\nInstall the bundled CLI skill for Claude Code:\n.B wfm skill install\n.TP\nInstall every bundled skill globally:\n.B wfm skill install --all --global\n.SH FILES\n.TP\n.B man/wfm.1\nThe manual page source shipped with this repository.\n.SH EXIT STATUS\n.TP\n.B 0\nSuccessful command execution.\n.TP\n.B 1\nValidation or runtime error.\n.TP\n.B 2\nRun completed in non-success terminal status.\n";
+export declare const MAN_PAGE_SOURCE = ".TH WFM 1 \"April 2026\" \"@workflow-manager/runner\" \"User Commands\"\n.SH NAME\nwfm \\- run markdown or json workflows from the CLI\n.SH SYNOPSIS\n.B wfm\n.I command\n[options]\n.SH DESCRIPTION\nwfm parses a workflow definition file, validates it, and executes\nit with deterministic in-memory orchestration.\n\nWorkflow files can be Markdown with YAML frontmatter or JSON.\n.SH COMMANDS\n.TP\n.B doctor [workflow.md|workflow.json] [--json]\nInspect host adapter setup, LLM access keys, and current adapter implementation status. When a workflow path is provided, also validate schema and runtime requirements without executing steps.\n.TP\n.B skill list\nList the agent skills bundled with the npm package.\n.TP\n.B skill install [name ...] [--agent claude|opencode] [--global] [--dir path] [--all] [--force]\nInstall bundled agent skills into an agent skill directory. Defaults to the workflow-manager-cli skill and the project-level Claude Code directory (./.claude/skills). Existing skills are not overwritten unless --force is passed.\n.TP\n.B scaffold [path] [--format markdown|json]\nCreate a starter workflow file. Format defaults to markdown unless the output\npath ends in .json.\n.TP\n.B validate <workflow.md|workflow.json>\nValidate workflow structure and report schema errors.\n.TP\n.B run <workflow.md|workflow.json> [--input input.json] [--objective text] [--confirm list] [--auto-confirm-all] [--port number] [--verbose] [--json] [--ui]\nRun the workflow with live CLI progress and optional JSON output.\n.TP\n.B approve [--url value] [--token value] [--run-id value] [--step value] [--actor value] [--note text]\nApprove the current waiting runner step through the local attach API.\n.TP\n.B resume [--url value] [--token value] [--run-id value] [--step value] [--actor value] [--note text]\nAlias for approve, intended for external resume flows.\n.TP\n.B cancel [--url value] [--token value] [--run-id value] [--step value] [--actor value] [--note text]\nCancel the current waiting runner step through the local attach API.\n.TP\n.B auth <login|whoami|logout> [--token value]\nManage remote registry authentication for CLI publish and pull flows.\n.TP\n.B publish <workflow.md|workflow.json> [--slug slug] [--title text] [--description text] [--visibility public|private] [--version label] [--tag a,b] [--draft]\nPublish a validated local workflow to the remote registry.\n.TP\n.B pull <owner/slug> [--version label] [--output path]\nDownload a remote workflow and write it to a local file.\n.TP\n.B search [query]\nSearch public workflows from the remote registry.\n.TP\n.B remote info <owner/slug>\nShow metadata and source information for a remote workflow.\n.TP\n.B man\nOpen this man page.\n.TP\n.B --version, -v, version\nPrint the installed wfm version and exit.\n.SH RUN OPTIONS\n.TP\n.B --input <path>\nJSON file merged into global workflow input state.\n.TP\n.B --objective <text>\nOverride the default run objective.\n.TP\n.B --confirm <stepA,stepB:human,...>\nProvide explicit confirmations for steps that require validation.\n.TP\n.B --auto-confirm-all\nBypass confirmation gating for all steps.\n.TP\n.B --port <number>\nBind the local attach API to a specific port. If omitted, the OS assigns a free port on 127.0.0.1.\n.TP\n.B --verbose\nStream per-step agent output and execution updates to stderr while the workflow runs.\n.TP\n.B --json\nPrint the final run result as JSON on stdout while keeping live progress on stderr.\n.TP\n.B --ui\nFull-screen terminal UI (requires a TTY; falls back to standard output).\n.TP\nHuman approval steps in an interactive terminal show an inline review prompt so they can be approved or cancelled without a separate HTTP client.\n.TP\n.B --url <value>\nRunner attach API base URL for approve, resume, or cancel commands.\n.TP\n.B --token <value>\nRunner attach API bearer token for approve, resume, or cancel commands.\n.TP\n.B --run-id <value>\nRunner id to control. If omitted, the CLI reads it from /session.\n.TP\n.B --step <value>\nOptional step key when controlling a specific waiting step.\n.TP\n.B --actor <value>\nActor name recorded in approval audit events.\n.TP\n.B --note <text>\nOptional approval or cancellation note recorded in the event payload.\n.SH EXAMPLES\n.TP\nValidate markdown workflow:\n.B wfm validate ./example-workflow.md\n.TP\nValidate json workflow:\n.B wfm validate ./example-workflow.json\n.TP\nScaffold json workflow file:\n.B wfm scaffold ./new-workflow.json --format json\n.TP\nAuthenticate with a CLI token:\n.B wfm auth login --token wm_exampletoken\n.TP\nPublish a workflow:\n.B wfm publish ./example-workflow.json --visibility public --tag example,automation\n.TP\nPull a remote workflow:\n.B wfm pull alice/remote-bunny --output ./remote-bunny.json\n.TP\nSearch the remote registry:\n.B wfm search bunny\n.TP\nRun with explicit confirmations:\n.B wfm run ./example-workflow.json --confirm discover:human,qa_gate:human\n.TP\nInspect host setup:\n.B wfm doctor\n.TP\nCheck a workflow before running it:\n.B wfm doctor ./example-workflow.json\n.TP\nInstall the bundled CLI skill for Claude Code:\n.B wfm skill install\n.TP\nInstall every bundled skill globally:\n.B wfm skill install --all --global\n.SH FILES\n.TP\n.B man/wfm.1\nThe manual page source shipped with this repository.\n.SH EXIT STATUS\n.TP\n.B 0\nSuccessful command execution.\n.TP\n.B 1\nValidation or runtime error.\n.TP\n.B 2\nRun completed in non-success terminal status.\n";

package/dist/manPage.js

@@ -28,7 +28,7 @@ path ends in .json.
 .B validate <workflow.md|workflow.json>
 Validate workflow structure and report schema errors.
 .TP
-.B run <workflow.md|workflow.json> [--input input.json] [--objective text] [--confirm list] [--auto-confirm-all] [--port number] [--verbose] [--json]
+.B run <workflow.md|workflow.json> [--input input.json] [--objective text] [--confirm list] [--auto-confirm-all] [--port number] [--verbose] [--json] [--ui]
 Run the workflow with live CLI progress and optional JSON output.
 .TP
 .B approve [--url value] [--token value] [--run-id value] [--step value] [--actor value] [--note text]
@@ -83,6 +83,9 @@ Stream per-step agent output and execution updates to stderr while the workflow
 .B --json
 Print the final run result as JSON on stdout while keeping live progress on stderr.
 .TP
+.B --ui
+Full-screen terminal UI (requires a TTY; falls back to standard output).
+.TP
 Human approval steps in an interactive terminal show an inline review prompt so they can be approved or cancelled without a separate HTTP client.
 .TP
 .B --url <value>

package/dist/runFormat.d.ts

@@ -0,0 +1,11 @@
+import type { StepDefinition, StepRunStatus, WorkflowRunStatus } from "./types.js";
+export declare function isTerminalStatus(status: WorkflowRunStatus): boolean;
+export declare function formatCount(value: number, singular: string, plural: string): string;
+export declare function formatDurationMs(value: number): string;
+export declare function elapsedFrom(iso: string | null, now?: number): string;
+export declare function splitLines(value: string): {
+    lines: string[];
+    remainder: string;
+};
+export declare function describeAgentStatus(status: StepRunStatus): string;
+export declare function stepLabel(step: StepDefinition): string;

package/dist/runFormat.js

@@ -0,0 +1,56 @@
+export function isTerminalStatus(status) {
+    return status === "succeeded" || status === "failed" || status === "cancelled";
+}
+export function formatCount(value, singular, plural) {
+    return `${value} ${value === 1 ? singular : plural}`;
+}
+export function formatDurationMs(value) {
+    if (!Number.isFinite(value) || value < 0) {
+        return "0s";
+    }
+    if (value < 1000) {
+        return `${Math.max(0, Math.round(value))}ms`;
+    }
+    const seconds = value / 1000;
+    if (seconds < 60) {
+        return `${seconds.toFixed(seconds < 10 ? 1 : 0)}s`;
+    }
+    const minutes = Math.floor(seconds / 60);
+    const remainingSeconds = Math.round(seconds % 60);
+    return `${minutes}m ${remainingSeconds}s`;
+}
+export function elapsedFrom(iso, now = Date.now()) {
+    if (!iso) {
+        return "0s";
+    }
+    const startedAt = Date.parse(iso);
+    if (Number.isNaN(startedAt)) {
+        return "0s";
+    }
+    return formatDurationMs(now - startedAt);
+}
+export function splitLines(value) {
+    const normalized = value.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+    const parts = normalized.split("\n");
+    const remainder = parts.pop() ?? "";
+    return { lines: parts, remainder };
+}
+export function describeAgentStatus(status) {
+    switch (status) {
+        case "running":
+            return "started";
+        case "succeeded":
+            return "succeeded";
+        case "failed":
+            return "failed";
+        case "waiting_for_approval":
+            return "waiting for approval";
+        case "cancelled":
+            return "cancelled";
+        default:
+            return status.replace(/_/g, " ");
+    }
+}
+export function stepLabel(step) {
+    return step.title ?? step.objective ?? step.key;
+}

package/dist/tui/ansi.d.ts

@@ -0,0 +1,23 @@
+export declare const ALT_SCREEN_ENTER = "\u001B[?1049h";
+export declare const ALT_SCREEN_LEAVE = "\u001B[?1049l";
+export declare const CURSOR_HIDE = "\u001B[?25l";
+export declare const CURSOR_SHOW = "\u001B[?25h";
+export declare const CURSOR_HOME = "\u001B[H";
+export declare const CLEAR_SCREEN = "\u001B[2J";
+export declare const CLEAR_LINE_END = "\u001B[K";
+export declare function stripAnsi(text: string): string;
+/** ANSI-aware column count (per code unit; see module comment). */
+export declare function visibleWidth(text: string): number;
+/**
+ * Truncates `text` to at most `width` visible columns, appending `ellipsis`
+ * when truncation happens. ANSI escape sequences are copied through intact
+ * (never split) and do not count toward the width. If any escape sequence
+ * was emitted before the cut, a style reset is appended so styling does not
+ * bleed past the truncated text.
+ *
+ * Invariant: visibleWidth(result) <= width. When `width` is smaller than the
+ * ellipsis itself, a slice of the ellipsis is returned to keep the invariant.
+ */
+export declare function truncateVisible(text: string, width: number, ellipsis?: string): string;
+/** Right-pads `text` with spaces up to `width` visible columns (no-op when already wider). */
+export declare function padVisible(text: string, width: number): string;

package/dist/tui/ansi.js

@@ -0,0 +1,102 @@
+// Escape-code constants and ANSI-aware string math for the TUI renderer.
+// Pure string helpers only: no I/O, no terminal capability detection.
+//
+// Width is counted per UTF-16 code unit after stripping ANSI CSI sequences.
+// Grapheme clusters and East Asian wide characters are intentionally not
+// handled (no grapheme lib); this is acceptable for the status/log text the
+// TUI renders and keeps these helpers dependency-free.
+export const ALT_SCREEN_ENTER = "\x1b[?1049h";
+export const ALT_SCREEN_LEAVE = "\x1b[?1049l";
+export const CURSOR_HIDE = "\x1b[?25l";
+export const CURSOR_SHOW = "\x1b[?25h";
+export const CURSOR_HOME = "\x1b[H";
+export const CLEAR_SCREEN = "\x1b[2J";
+export const CLEAR_LINE_END = "\x1b[K";
+const ESC = "\x1b";
+const STYLE_RESET = "\x1b[0m";
+/**
+ * Returns the length of the ANSI CSI escape sequence starting at `start`,
+ * or 0 when `start` does not begin a well-formed CSI sequence.
+ *
+ * CSI grammar: ESC `[` then parameter/intermediate bytes (0x20-0x3f)
+ * terminated by a final byte (0x40-0x7e).
+ */
+function escapeSequenceLength(text, start) {
+    if (text[start] !== ESC || text[start + 1] !== "[") {
+        return 0;
+    }
+    let index = start + 2;
+    while (index < text.length) {
+        const code = text.charCodeAt(index);
+        if (code >= 0x40 && code <= 0x7e) {
+            return index - start + 1;
+        }
+        if (code < 0x20 || code > 0x3f) {
+            return 0;
+        }
+        index += 1;
+    }
+    return 0;
+}
+export function stripAnsi(text) {
+    let out = "";
+    let index = 0;
+    while (index < text.length) {
+        const skip = escapeSequenceLength(text, index);
+        if (skip > 0) {
+            index += skip;
+            continue;
+        }
+        out += text[index];
+        index += 1;
+    }
+    return out;
+}
+/** ANSI-aware column count (per code unit; see module comment). */
+export function visibleWidth(text) {
+    return stripAnsi(text).length;
+}
+/**
+ * Truncates `text` to at most `width` visible columns, appending `ellipsis`
+ * when truncation happens. ANSI escape sequences are copied through intact
+ * (never split) and do not count toward the width. If any escape sequence
+ * was emitted before the cut, a style reset is appended so styling does not
+ * bleed past the truncated text.
+ *
+ * Invariant: visibleWidth(result) <= width. When `width` is smaller than the
+ * ellipsis itself, a slice of the ellipsis is returned to keep the invariant.
+ */
+export function truncateVisible(text, width, ellipsis = "…") {
+    if (visibleWidth(text) <= width) {
+        return text;
+    }
+    if (width <= 0) {
+        return "";
+    }
+    if (width < ellipsis.length) {
+        return ellipsis.slice(0, width);
+    }
+    const budget = width - ellipsis.length;
+    let out = "";
+    let visible = 0;
+    let sawEscape = false;
+    let index = 0;
+    while (index < text.length && visible < budget) {
+        const skip = escapeSequenceLength(text, index);
+        if (skip > 0) {
+            out += text.slice(index, index + skip);
+            sawEscape = true;
+            index += skip;
+            continue;
+        }
+        out += text[index];
+        visible += 1;
+        index += 1;
+    }
+    return out + ellipsis + (sawEscape ? STYLE_RESET : "");
+}
+/** Right-pads `text` with spaces up to `width` visible columns (no-op when already wider). */
+export function padVisible(text, width) {
+    const missing = width - visibleWidth(text);
+    return missing > 0 ? text + " ".repeat(missing) : text;
+}

package/dist/tui/layout.d.ts

@@ -0,0 +1,18 @@
+import type { RunSnapshot, StepDetailSnapshot } from "../types.js";
+import type { TuiLogStore } from "./logStore.js";
+import type { Theme } from "./theme.js";
+export interface TuiFrameState {
+    snapshot: RunSnapshot | null;
+    stepDetails: Map<string, StepDetailSnapshot>;
+    logs: TuiLogStore;
+    selectedStepKey: string | null;
+    follow: boolean;
+    attachUrl: string;
+    attachToken: string;
+    statusMessage?: string | null;
+    width: number;
+    height: number;
+    now: number;
+    theme: Theme;
+}
+export declare function renderFrame(state: TuiFrameState): string[];