@michaelrwalker/stagehand 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,176 @@
+export type Awaitable<T> = T | Promise<T>;
+/** Flattens intersections so hover tooltips show a real object shape. */
+export type Prettify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+/**
+ * Context after a step contributes `Out`. A step that returns nothing leaves
+ * the context untouched; later keys win over earlier ones.
+ */
+export type Merge<Ctx, Out> = [Out] extends [void] ? Ctx : [Out] extends [undefined] ? Ctx : Prettify<Omit<Ctx, keyof Out> & Out>;
+export type StepStatus = "pending" | "running" | "success" | "failed" | "skipped" | "rolling-back" | "rolled-back" | "rollback-failed";
+export type PhaseStatus = "pending" | "running" | "success" | "failed" | "skipped";
+export type RunStatus = "pending" | "running" | "success" | "failed" | "aborted";
+export interface ProgressHandle {
+    /** Set the absolute value, optionally relabelling the bar. */
+    update(value: number, label?: string): void;
+    /** Advance by `by` (default 1). */
+    increment(by?: number): void;
+    setTotal(total: number): void;
+    setLabel(label: string): void;
+    /** Fill the bar and stop showing it as in-flight. */
+    done(): void;
+    readonly value: number;
+    readonly total: number;
+}
+export interface TaskHandle {
+    /** Move a pending task into the running state (spinner). */
+    start(text?: string): void;
+    /** Rename the task in place. */
+    label(text: string): void;
+    succeed(text?: string): void;
+    fail(text?: string): void;
+    skip(text?: string): void;
+}
+export interface TaskListHandle<K extends string> {
+    readonly tasks: Record<K, TaskHandle>;
+    get(key: K): TaskHandle;
+}
+/** Everything a handler gets: accumulated data plus the live terminal. */
+export interface StepContext<In, Ctx> {
+    /** The input the script was run with. */
+    readonly input: In;
+    /** Data produced by every step that has already succeeded. */
+    readonly ctx: Ctx;
+    /** Aborts on timeout, on Ctrl-C, or when `run` is cancelled. */
+    readonly signal: AbortSignal;
+    /** 1 on the first try, 2 on the first retry, and so on. */
+    readonly attempt: number;
+    readonly phase: string;
+    readonly step: string;
+    /** Permanent line, printed above the live frame and kept in scrollback. */
+    log(message: string): void;
+    info(message: string): void;
+    warn(message: string): void;
+    error(message: string): void;
+    success(message: string): void;
+    /** Transient one-liner shown beside the step. Replaced on each call. */
+    status(message: string): void;
+    /** Attach a progress bar to this step. */
+    progress(options: {
+        total: number;
+        label?: string;
+        value?: number;
+    }): ProgressHandle;
+    /** Attach a single checklist item nested under this step. */
+    task(label: string): TaskHandle;
+    /** Attach a whole checklist at once, keyed for typed lookup. */
+    tasks<const K extends readonly string[]>(labels: K): TaskListHandle<K[number]>;
+}
+export interface RollbackContext<In, Ctx, Out> {
+    readonly input: In;
+    /** Context as it stood when the failure happened. */
+    readonly ctx: Ctx;
+    /** Exactly what this step's handler returned. */
+    readonly output: Out;
+    /** The error that triggered the unwind. */
+    readonly error: unknown;
+    readonly signal: AbortSignal;
+    readonly phase: string;
+    readonly step: string;
+    log(message: string): void;
+    status(message: string): void;
+    progress(options: {
+        total: number;
+        label?: string;
+        value?: number;
+    }): ProgressHandle;
+}
+export interface RetryPolicy {
+    attempts: number;
+    /** Fixed delay in ms, or a function of the attempt just failed (1-based). */
+    delayMs?: number | ((attempt: number) => number);
+    /** Return false to stop retrying this particular error. */
+    retryIf?: (error: unknown, attempt: number) => boolean;
+}
+export interface StepDef<In, Ctx, Out> {
+    name: string;
+    description?: string;
+    /**
+     * The work. Whatever object it resolves to is merged into `ctx` and becomes
+     * visible — and typed — for every later step.
+     */
+    handler: (context: StepContext<In, Ctx>) => Awaitable<Out>;
+    /**
+     * Compensation. Runs when a *later* step fails, in reverse order, after this
+     * step has already succeeded.
+     */
+    rollback?: (context: RollbackContext<In, Ctx, Out>) => Awaitable<void>;
+    /** Skip the step (and its rollback) when this resolves falsy. */
+    when?: (context: {
+        input: In;
+        ctx: Ctx;
+    }) => Awaitable<boolean>;
+    retry?: RetryPolicy;
+    timeoutMs?: number;
+}
+export interface PhaseOptions<In = unknown, Ctx = unknown> {
+    description?: string;
+    /** Skip every step in the phase when this resolves falsy. */
+    when?: (context: {
+        input: In;
+        ctx: Ctx;
+    }) => Awaitable<boolean>;
+}
+export interface ScriptOptions {
+    name?: string;
+    description?: string;
+    /**
+     * `all` (default) unwinds every completed step across the whole script.
+     * `phase` unwinds only the phase that failed. `none` leaves state as-is.
+     */
+    rollback?: "all" | "phase" | "none";
+    /** Throw instead of returning a failed result. Default false. */
+    throwOnError?: boolean;
+    /** Force the plain, non-animated renderer (useful in CI). Default: auto. */
+    plain?: boolean;
+    /** Suppress all output. */
+    silent?: boolean;
+    /** Rollback on SIGINT/SIGTERM. Default true. */
+    handleSignals?: boolean;
+}
+export interface StepReport {
+    phase: string;
+    name: string;
+    status: StepStatus;
+    durationMs: number;
+    attempts: number;
+    error?: unknown;
+}
+export interface RollbackReport {
+    phase: string;
+    step: string;
+    ok: boolean;
+    error?: unknown;
+}
+export type RunResult<Ctx> = {
+    ok: true;
+    status: "success";
+    ctx: Prettify<Ctx>;
+    durationMs: number;
+    steps: StepReport[];
+} | {
+    ok: false;
+    status: "failed" | "aborted";
+    error: unknown;
+    failedAt: {
+        phase: string;
+        step: string;
+    } | null;
+    /** Partial context: everything the steps that did succeed produced. */
+    ctx: Partial<Prettify<Ctx>>;
+    durationMs: number;
+    steps: StepReport[];
+    rollbacks: RollbackReport[];
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/dist/ui/ansi.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Minimal ANSI toolkit. No dependencies, no global mutation of the stream.
+ */
+export declare function isColorEnabled(): boolean;
+export declare function setColorEnabled(value: boolean): void;
+export type Styler = (input: string) => string;
+export declare const bold: Styler;
+export declare const dim: Styler;
+export declare const italic: Styler;
+export declare const underline: Styler;
+export declare const inverse: Styler;
+/** 256-colour foreground. Degrades to plain text when colour is off. */
+export declare function fg(code: number): Styler;
+/** 256-colour background. */
+export declare function bg(code: number): Styler;
+export declare const cursor: {
+    hide: string;
+    show: string;
+    up: (n: number) => string;
+    toStart: string;
+    eraseDown: string;
+};
+export declare function stripAnsi(input: string): string;
+/**
+ * Terminal cell width. Handles the wide-character ranges that actually turn up
+ * in CLI output (CJK, emoji) and treats combining marks as zero-width.
+ */
+export declare function stringWidth(input: string): number;
+/**
+ * Truncate to a visible width while keeping escape sequences intact, so a
+ * clipped line never leaks colour into the rest of the frame.
+ */
+export declare function truncate(input: string, max: number): string;
+/**
+ * Word-wrap to a visible width, returning plain lines.
+ *
+ * Errors must never be clipped — the useful half of a message like npm's 403
+ * lives at the end of the line. Callers style each returned line themselves,
+ * which sidesteps splitting an escape sequence across a break.
+ */
+export declare function wrapText(input: string, width: number): string[];
+export declare function padEnd(input: string, target: number): string;
+//# sourceMappingURL=ansi.d.ts.map

package/dist/ui/ansi.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ansi.d.ts","sourceRoot":"","sources":["../../src/ui/ansi.ts"],"names":[],"mappings":"AAAA;;GAEG;AAeH,wBAAgB,cAAc,IAAI,OAAO,CAExC;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAEpD;AAED,MAAM,MAAM,MAAM,GAAG,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC;AAM/C,eAAO,MAAM,IAAI,QAAiC,CAAC;AACnD,eAAO,MAAM,GAAG,QAAiC,CAAC;AAClD,eAAO,MAAM,MAAM,QAAiC,CAAC;AACrD,eAAO,MAAM,SAAS,QAAiC,CAAC;AACxD,eAAO,MAAM,OAAO,QAAiC,CAAC;AAEtD,wEAAwE;AACxE,wBAAgB,EAAE,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEvC;AAED,6BAA6B;AAC7B,wBAAgB,EAAE,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEvC;AAED,eAAO,MAAM,MAAM;;;YAGT,MAAM,KAAG,MAAM;;;CAGxB,CAAC;AAEF,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE/C;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAWjD;AAiBD;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CA4B3D;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAwC/D;AAED,wBAAgB,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAG5D"}

package/dist/ui/ansi.js

@@ -0,0 +1,166 @@
+/**
+ * Minimal ANSI toolkit. No dependencies, no global mutation of the stream.
+ */
+const ESC = "[";
+const ANSI_PATTERN = /\[[0-9;]*m/g;
+function detectColor() {
+    const env = process.env;
+    if (env.NO_COLOR !== undefined && env.NO_COLOR !== "")
+        return false;
+    if (env.FORCE_COLOR !== undefined)
+        return env.FORCE_COLOR !== "0";
+    if (env.TERM === "dumb")
+        return false;
+    return Boolean(process.stdout.isTTY);
+}
+let colorEnabled = detectColor();
+export function isColorEnabled() {
+    return colorEnabled;
+}
+export function setColorEnabled(value) {
+    colorEnabled = value;
+}
+function style(open, close) {
+    return (input) => (colorEnabled ? open + input + close : input);
+}
+export const bold = style(`${ESC}1m`, `${ESC}22m`);
+export const dim = style(`${ESC}2m`, `${ESC}22m`);
+export const italic = style(`${ESC}3m`, `${ESC}23m`);
+export const underline = style(`${ESC}4m`, `${ESC}24m`);
+export const inverse = style(`${ESC}7m`, `${ESC}27m`);
+/** 256-colour foreground. Degrades to plain text when colour is off. */
+export function fg(code) {
+    return style(`${ESC}38;5;${code}m`, `${ESC}39m`);
+}
+/** 256-colour background. */
+export function bg(code) {
+    return style(`${ESC}48;5;${code}m`, `${ESC}49m`);
+}
+export const cursor = {
+    hide: `${ESC}?25l`,
+    show: `${ESC}?25h`,
+    up: (n) => (n > 0 ? `${ESC}${n}A` : ""),
+    toStart: `${ESC}G`,
+    eraseDown: `${ESC}0J`,
+};
+export function stripAnsi(input) {
+    return input.replace(ANSI_PATTERN, "");
+}
+/**
+ * Terminal cell width. Handles the wide-character ranges that actually turn up
+ * in CLI output (CJK, emoji) and treats combining marks as zero-width.
+ */
+export function stringWidth(input) {
+    let total = 0;
+    for (const char of stripAnsi(input)) {
+        const cp = char.codePointAt(0);
+        if (cp === undefined)
+            continue;
+        if (cp === 0x200d)
+            continue; // zero-width joiner
+        if (cp >= 0x0300 && cp <= 0x036f)
+            continue; // combining diacriticals
+        if (cp >= 0xfe00 && cp <= 0xfe0f)
+            continue; // variation selectors
+        total += isWide(cp) ? 2 : 1;
+    }
+    return total;
+}
+function isWide(cp) {
+    return ((cp >= 0x1100 && cp <= 0x115f) ||
+        (cp >= 0x2e80 && cp <= 0xa4cf && cp !== 0x303f) ||
+        (cp >= 0xac00 && cp <= 0xd7a3) ||
+        (cp >= 0xf900 && cp <= 0xfaff) ||
+        (cp >= 0xfe30 && cp <= 0xfe6f) ||
+        (cp >= 0xff00 && cp <= 0xff60) ||
+        (cp >= 0xffe0 && cp <= 0xffe6) ||
+        (cp >= 0x1f300 && cp <= 0x1f64f) ||
+        (cp >= 0x1f900 && cp <= 0x1f9ff) ||
+        (cp >= 0x20000 && cp <= 0x3fffd));
+}
+/**
+ * Truncate to a visible width while keeping escape sequences intact, so a
+ * clipped line never leaks colour into the rest of the frame.
+ */
+export function truncate(input, max) {
+    if (max <= 0)
+        return "";
+    if (stringWidth(input) <= max)
+        return input;
+    let out = "";
+    let visible = 0;
+    let sawEscape = false;
+    let index = 0;
+    while (index < input.length) {
+        if (input.startsWith("[", index)) {
+            const end = input.indexOf("m", index);
+            if (end !== -1) {
+                out += input.slice(index, end + 1);
+                sawEscape = true;
+                index = end + 1;
+                continue;
+            }
+        }
+        const char = String.fromCodePoint(input.codePointAt(index));
+        const w = stringWidth(char);
+        if (visible + w > max - 1)
+            break;
+        out += char;
+        visible += w;
+        index += char.length;
+    }
+    return out + "…" + (sawEscape && colorEnabled ? `${ESC}0m` : "");
+}
+/**
+ * Word-wrap to a visible width, returning plain lines.
+ *
+ * Errors must never be clipped — the useful half of a message like npm's 403
+ * lives at the end of the line. Callers style each returned line themselves,
+ * which sidesteps splitting an escape sequence across a break.
+ */
+export function wrapText(input, width) {
+    if (width <= 1)
+        return [stripAnsi(input)];
+    const lines = [];
+    let current = "";
+    const push = () => {
+        if (current !== "")
+            lines.push(current);
+        current = "";
+    };
+    for (const word of stripAnsi(input).split(/\s+/).filter(Boolean)) {
+        let token = word;
+        // A single token wider than the line (a URL, a stack frame) is hard-broken.
+        while (stringWidth(token) > width) {
+            push();
+            let head = "";
+            let index = 0;
+            while (index < token.length && stringWidth(head) < width) {
+                const char = String.fromCodePoint(token.codePointAt(index));
+                if (stringWidth(head) + stringWidth(char) > width)
+                    break;
+                head += char;
+                index += char.length;
+            }
+            lines.push(head);
+            token = token.slice(index);
+        }
+        if (token === "")
+            continue;
+        if (current === "")
+            current = token;
+        else if (stringWidth(current) + 1 + stringWidth(token) <= width)
+            current += ` ${token}`;
+        else {
+            push();
+            current = token;
+        }
+    }
+    push();
+    return lines.length > 0 ? lines : [""];
+}
+export function padEnd(input, target) {
+    const gap = target - stringWidth(input);
+    return gap > 0 ? input + " ".repeat(gap) : input;
+}
+//# sourceMappingURL=ansi.js.map

package/dist/ui/ansi.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ansi.js","sourceRoot":"","sources":["../../src/ui/ansi.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,GAAG,GAAG,IAAI,CAAC;AACjB,MAAM,YAAY,GAAG,cAAc,CAAC;AAEpC,SAAS,WAAW;IAClB,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC;IACxB,IAAI,GAAG,CAAC,QAAQ,KAAK,SAAS,IAAI,GAAG,CAAC,QAAQ,KAAK,EAAE;QAAE,OAAO,KAAK,CAAC;IACpE,IAAI,GAAG,CAAC,WAAW,KAAK,SAAS;QAAE,OAAO,GAAG,CAAC,WAAW,KAAK,GAAG,CAAC;IAClE,IAAI,GAAG,CAAC,IAAI,KAAK,MAAM;QAAE,OAAO,KAAK,CAAC;IACtC,OAAO,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AACvC,CAAC;AAED,IAAI,YAAY,GAAG,WAAW,EAAE,CAAC;AAEjC,MAAM,UAAU,cAAc;IAC5B,OAAO,YAAY,CAAC;AACtB,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,KAAc;IAC5C,YAAY,GAAG,KAAK,CAAC;AACvB,CAAC;AAID,SAAS,KAAK,CAAC,IAAY,EAAE,KAAa;IACxC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,IAAI,GAAG,KAAK,GAAG,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;AAClE,CAAC;AAED,MAAM,CAAC,MAAM,IAAI,GAAG,KAAK,CAAC,GAAG,GAAG,IAAI,EAAE,GAAG,GAAG,KAAK,CAAC,CAAC;AACnD,MAAM,CAAC,MAAM,GAAG,GAAG,KAAK,CAAC,GAAG,GAAG,IAAI,EAAE,GAAG,GAAG,KAAK,CAAC,CAAC;AAClD,MAAM,CAAC,MAAM,MAAM,GAAG,KAAK,CAAC,GAAG,GAAG,IAAI,EAAE,GAAG,GAAG,KAAK,CAAC,CAAC;AACrD,MAAM,CAAC,MAAM,SAAS,GAAG,KAAK,CAAC,GAAG,GAAG,IAAI,EAAE,GAAG,GAAG,KAAK,CAAC,CAAC;AACxD,MAAM,CAAC,MAAM,OAAO,GAAG,KAAK,CAAC,GAAG,GAAG,IAAI,EAAE,GAAG,GAAG,KAAK,CAAC,CAAC;AAEtD,wEAAwE;AACxE,MAAM,UAAU,EAAE,CAAC,IAAY;IAC7B,OAAO,KAAK,CAAC,GAAG,GAAG,QAAQ,IAAI,GAAG,EAAE,GAAG,GAAG,KAAK,CAAC,CAAC;AACnD,CAAC;AAED,6BAA6B;AAC7B,MAAM,UAAU,EAAE,CAAC,IAAY;IAC7B,OAAO,KAAK,CAAC,GAAG,GAAG,QAAQ,IAAI,GAAG,EAAE,GAAG,GAAG,KAAK,CAAC,CAAC;AACnD,CAAC;AAED,MAAM,CAAC,MAAM,MAAM,GAAG;IACpB,IAAI,EAAE,GAAG,GAAG,MAAM;IAClB,IAAI,EAAE,GAAG,GAAG,MAAM;IAClB,EAAE,EAAE,CAAC,CAAS,EAAU,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;IACvD,OAAO,EAAE,GAAG,GAAG,GAAG;IAClB,SAAS,EAAE,GAAG,GAAG,IAAI;CACtB,CAAC;AAEF,MAAM,UAAU,SAAS,CAAC,KAAa;IACrC,OAAO,KAAK,CAAC,OAAO,CAAC,YAAY,EAAE,EAAE,CAAC,CAAC;AACzC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,KAAa;IACvC,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,KAAK,MAAM,IAAI,IAAI,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC;QACpC,MAAM,EAAE,GAAG,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;QAC/B,IAAI,EAAE,KAAK,SAAS;YAAE,SAAS;QAC/B,IAAI,EAAE,KAAK,MAAM;YAAE,SAAS,CAAC,oBAAoB;QACjD,IAAI,EAAE,IAAI,MAAM,IAAI,EAAE,IAAI,MAAM;YAAE,SAAS,CAAC,yBAAyB;QACrE,IAAI,EAAE,IAAI,MAAM,IAAI,EAAE,IAAI,MAAM;YAAE,SAAS,CAAC,sBAAsB;QAClE,KAAK,IAAI,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC9B,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,MAAM,CAAC,EAAU;IACxB,OAAO,CACL,CAAC,EAAE,IAAI,MAAM,IAAI,EAAE,IAAI,MAAM,CAAC;QAC9B,CAAC,EAAE,IAAI,MAAM,IAAI,EAAE,IAAI,MAAM,IAAI,EAAE,KAAK,MAAM,CAAC;QAC/C,CAAC,EAAE,IAAI,MAAM,IAAI,EAAE,IAAI,MAAM,CAAC;QAC9B,CAAC,EAAE,IAAI,MAAM,IAAI,EAAE,IAAI,MAAM,CAAC;QAC9B,CAAC,EAAE,IAAI,MAAM,IAAI,EAAE,IAAI,MAAM,CAAC;QAC9B,CAAC,EAAE,IAAI,MAAM,IAAI,EAAE,IAAI,MAAM,CAAC;QAC9B,CAAC,EAAE,IAAI,MAAM,IAAI,EAAE,IAAI,MAAM,CAAC;QAC9B,CAAC,EAAE,IAAI,OAAO,IAAI,EAAE,IAAI,OAAO,CAAC;QAChC,CAAC,EAAE,IAAI,OAAO,IAAI,EAAE,IAAI,OAAO,CAAC;QAChC,CAAC,EAAE,IAAI,OAAO,IAAI,EAAE,IAAI,OAAO,CAAC,CACjC,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,QAAQ,CAAC,KAAa,EAAE,GAAW;IACjD,IAAI,GAAG,IAAI,CAAC;QAAE,OAAO,EAAE,CAAC;IACxB,IAAI,WAAW,CAAC,KAAK,CAAC,IAAI,GAAG;QAAE,OAAO,KAAK,CAAC;IAE5C,IAAI,GAAG,GAAG,EAAE,CAAC;IACb,IAAI,OAAO,GAAG,CAAC,CAAC;IAChB,IAAI,SAAS,GAAG,KAAK,CAAC;IACtB,IAAI,KAAK,GAAG,CAAC,CAAC;IAEd,OAAO,KAAK,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC;QAC5B,IAAI,KAAK,CAAC,UAAU,CAAC,IAAI,EAAE,KAAK,CAAC,EAAE,CAAC;YAClC,MAAM,GAAG,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;YACtC,IAAI,GAAG,KAAK,CAAC,CAAC,EAAE,CAAC;gBACf,GAAG,IAAI,KAAK,CAAC,KAAK,CAAC,KAAK,EAAE,GAAG,GAAG,CAAC,CAAC,CAAC;gBACnC,SAAS,GAAG,IAAI,CAAC;gBACjB,KAAK,GAAG,GAAG,GAAG,CAAC,CAAC;gBAChB,SAAS;YACX,CAAC;QACH,CAAC;QACD,MAAM,IAAI,GAAG,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,WAAW,CAAC,KAAK,CAAW,CAAC,CAAC;QACtE,MAAM,CAAC,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC;QAC5B,IAAI,OAAO,GAAG,CAAC,GAAG,GAAG,GAAG,CAAC;YAAE,MAAM;QACjC,GAAG,IAAI,IAAI,CAAC;QACZ,OAAO,IAAI,CAAC,CAAC;QACb,KAAK,IAAI,IAAI,CAAC,MAAM,CAAC;IACvB,CAAC;IAED,OAAO,GAAG,GAAG,GAAG,GAAG,CAAC,SAAS,IAAI,YAAY,CAAC,CAAC,CAAC,GAAG,GAAG,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;AACnE,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,QAAQ,CAAC,KAAa,EAAE,KAAa;IACnD,IAAI,KAAK,IAAI,CAAC;QAAE,OAAO,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC;IAE1C,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,IAAI,OAAO,GAAG,EAAE,CAAC;IAEjB,MAAM,IAAI,GAAG,GAAS,EAAE;QACtB,IAAI,OAAO,KAAK,EAAE;YAAE,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACxC,OAAO,GAAG,EAAE,CAAC;IACf,CAAC,CAAC;IAEF,KAAK,MAAM,IAAI,IAAI,SAAS,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC;QACjE,IAAI,KAAK,GAAG,IAAI,CAAC;QAEjB,4EAA4E;QAC5E,OAAO,WAAW,CAAC,KAAK,CAAC,GAAG,KAAK,EAAE,CAAC;YAClC,IAAI,EAAE,CAAC;YACP,IAAI,IAAI,GAAG,EAAE,CAAC;YACd,IAAI,KAAK,GAAG,CAAC,CAAC;YACd,OAAO,KAAK,GAAG,KAAK,CAAC,MAAM,IAAI,WAAW,CAAC,IAAI,CAAC,GAAG,KAAK,EAAE,CAAC;gBACzD,MAAM,IAAI,GAAG,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,WAAW,CAAC,KAAK,CAAW,CAAC,CAAC;gBACtE,IAAI,WAAW,CAAC,IAAI,CAAC,GAAG,WAAW,CAAC,IAAI,CAAC,GAAG,KAAK;oBAAE,MAAM;gBACzD,IAAI,IAAI,IAAI,CAAC;gBACb,KAAK,IAAI,IAAI,CAAC,MAAM,CAAC;YACvB,CAAC;YACD,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACjB,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QAC7B,CAAC;QAED,IAAI,KAAK,KAAK,EAAE;YAAE,SAAS;QAC3B,IAAI,OAAO,KAAK,EAAE;YAAE,OAAO,GAAG,KAAK,CAAC;aAC/B,IAAI,WAAW,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,WAAW,CAAC,KAAK,CAAC,IAAI,KAAK;YAAE,OAAO,IAAI,IAAI,KAAK,EAAE,CAAC;aACnF,CAAC;YACJ,IAAI,EAAE,CAAC;YACP,OAAO,GAAG,KAAK,CAAC;QAClB,CAAC;IACH,CAAC;IAED,IAAI,EAAE,CAAC;IACP,OAAO,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;AACzC,CAAC;AAED,MAAM,UAAU,MAAM,CAAC,KAAa,EAAE,MAAc;IAClD,MAAM,GAAG,GAAG,MAAM,GAAG,WAAW,CAAC,KAAK,CAAC,CAAC;IACxC,OAAO,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,GAAG,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;AACnD,CAAC"}

package/dist/ui/frame.d.ts

@@ -0,0 +1,27 @@
+import { type ProgressState, type RunState } from "../state.js";
+export type LogLevel = "log" | "info" | "warn" | "error" | "success";
+export interface LogEntry {
+    level: LogLevel;
+    message: string;
+}
+export declare function renderBar(progress: ProgressState, width?: number): string;
+export declare function renderHeader(state: RunState): string[];
+/**
+ * Lines the live region may occupy without the terminal scrolling under it.
+ *
+ * The hard limit is the viewport height; the margin covers the one extra line
+ * a permanent log write costs when the region is already at full height.
+ */
+export declare function bodyBudget(): number;
+/**
+ * The live body, guaranteed to fit `bodyBudget()`.
+ *
+ * This guarantee is load-bearing, not cosmetic: the renderer repaints by moving
+ * the cursor up N lines, so a frame taller than the viewport scrolls its own
+ * top off screen and every repaint appends a copy instead of overwriting. Four
+ * progressively stronger reductions are tried, and the result is clamped.
+ */
+export declare function renderBody(state: RunState, tick: number, now: number, fit?: boolean): string[];
+export declare function renderSummary(state: RunState, now: number): string[];
+export declare function renderLogEntry(entry: LogEntry): string;
+//# sourceMappingURL=frame.d.ts.map

package/dist/ui/frame.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frame.d.ts","sourceRoot":"","sources":["../../src/ui/frame.ts"],"names":[],"mappings":"AAEA,OAAO,EAOL,KAAK,aAAa,EAClB,KAAK,QAAQ,EAGd,MAAM,aAAa,CAAC;AAOrB,MAAM,MAAM,QAAQ,GAAG,KAAK,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC;AAErE,MAAM,WAAW,QAAQ;IACvB,KAAK,EAAE,QAAQ,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;CACjB;AA8DD,wBAAgB,SAAS,CAAC,QAAQ,EAAE,aAAa,EAAE,KAAK,SAAK,GAAG,MAAM,CAoBrE;AAwHD,wBAAgB,YAAY,CAAC,KAAK,EAAE,QAAQ,GAAG,MAAM,EAAE,CAOtD;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,IAAI,MAAM,CAEnC;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,UAAO,GAAG,MAAM,EAAE,CA2C3F;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CAgDpE;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,QAAQ,GAAG,MAAM,CAkBtD"}