@promptctl/rich-js 0.18.1 → 0.19.0

package/dist/renderables/progress.d.ts

@@ -1,8 +1,13 @@
 /**
  * Progress — displays continuously updated progress bars.
  */
-import { Segment } from "../core/segment.js";
+import type { Segment } from "../core/segment.js";
+import { RichText } from "../core/text.js";
 import { Console } from "../core/console.js";
+import type { Style } from "../core/style.js";
+import { ProgressBar } from "./progressBar.js";
+import { type Clock } from "../core/clock.js";
+import { type ColumnOptions } from "./table.js";
 import type { Renderable, RenderOptions } from "../core/protocol.js";
 export interface TaskOptions {
     total?: number;
@@ -16,45 +21,122 @@ export interface TaskUpdateOptions {
     visible?: boolean;
     refresh?: boolean;
 }
-interface Task {
+export interface Task {
     id: number;
     description: string;
     total: number | undefined;
     completed: number;
-    started: boolean;
     visible: boolean;
-    startTime: number;
-    elapsed: number;
+    /** When the task started, in seconds on its `Progress`'s clock; undefined until it has. */
+    startTime: number | undefined;
+    /**
+     * Rich's `Task.elapsed`: seconds since the task started, as of the frame
+     * being drawn — `Progress` reads its clock once a frame and hands columns
+     * the result, so no column reads a clock. Undefined until the task starts.
+     */
+    elapsed: number | undefined;
+    /**
+     * Rich's `Task.finished_time`: the elapsed time the first time an update
+     * finds a started task at its total, kept from then on, so a finished task
+     * stays finished however its count moves after.
+     */
+    finishedTime: number | undefined;
+    /**
+     * Rich's `Task.speed`: steps a second over the updates that moved the task
+     * in the `SPEED_ESTIMATE_PERIOD` before its latest update — measured back from
+     * that update, not from now, so a task that stops being updated keeps the
+     * speed it had. Undefined until the task has started and two such updates lie
+     * apart in time.
+     */
+    speed: number | undefined;
 }
-export interface ProgressColumn extends Renderable {
-    render(options: RenderOptions, task?: Task): Iterable<Segment>;
+/**
+ * One cell of a `Progress` row, made for the task on that row. Not a
+ * `Renderable`: a column has nothing to draw without a task, as the
+ * reference's `ProgressColumn` is a callable of one. What it returns is the
+ * cell's content, which the progress grid lays out like any table cell's —
+ * width, wrapping and justify are decided once, in the cell, as Rich's
+ * `make_tasks_table` decides them. [LAW:single-enforcer]
+ */
+export interface ProgressColumn {
+    /**
+     * The grid column this one is laid out in, Rich's `get_table_column()`:
+     * whether its cell may wrap, how it justifies, its share of the width.
+     */
+    readonly tableColumn: ColumnOptions;
+    render(task: Task): Renderable;
 }
 export declare class TextColumn implements ProgressColumn {
     readonly format: string;
+    /** Text is cut, never wrapped, as Rich's `TextColumn` defaults to `Column(no_wrap=True)`. */
+    readonly tableColumn: ColumnOptions;
     constructor(format?: string);
-    render(options: RenderOptions, task?: Task): Iterable<Segment>;
+    render(task: Task): RichText;
 }
 export declare class BarColumn implements ProgressColumn {
     readonly barWidth: number;
+    readonly tableColumn: ColumnOptions;
     constructor(barWidth?: number);
-    render(_options: RenderOptions, task?: Task): Iterable<Segment>;
+    render(task: Task): ProgressBar;
 }
+/**
+ * Rich's `{task.percentage:>3.0f}%`: the percentage right-aligned in three
+ * cells, so the column is four wide from 0% to 100% and the row does not
+ * shift as it counts. A task with no total shows nothing, Rich's
+ * `text_format_no_percentage`.
+ */
 export declare class TaskProgressColumn implements ProgressColumn {
-    render(options: RenderOptions, task?: Task): Iterable<Segment>;
+    /** A `TextColumn` in Rich, and laid out as one. */
+    readonly tableColumn: ColumnOptions;
+    render(task: Task): RichText;
+}
+export interface TimeRemainingColumnOptions {
+    /**
+     * Once the task is finished, draw the time it took, styled
+     * `progress.elapsed`, in place of the zero left to go: Rich's
+     * `elapsed_when_finished`. Defaults to false.
+     */
+    elapsedWhenFinished?: boolean;
 }
 export declare class TimeRemainingColumn implements ProgressColumn {
-    render(options: RenderOptions, task?: Task): Iterable<Segment>;
+    readonly tableColumn: ColumnOptions;
+    readonly elapsedWhenFinished: boolean;
+    constructor(options?: TimeRemainingColumnOptions);
+    render(task: Task): RichText;
 }
 export declare class TimeElapsedColumn implements ProgressColumn {
-    render(options: RenderOptions, task?: Task): Iterable<Segment>;
+    readonly tableColumn: ColumnOptions;
+    render(task: Task): RichText;
+}
+export interface SpinnerColumnOptions {
+    /** The frame's style. Defaults to `progress.spinner`, a name its console's theme resolves. */
+    style?: string | Style;
+    /** Multiplies the spinner's frame rate. Defaults to 1. */
+    speed?: number;
+    /** Drawn in place of the frame once the task reaches its total; a string is markup. Defaults to `" "`. */
+    finishedText?: string | RichText;
 }
 export declare class SpinnerColumn implements ProgressColumn {
+    readonly tableColumn: ColumnOptions;
     private _spinner;
-    constructor(spinnerName?: string);
-    render(options: RenderOptions, _task?: Task): Iterable<Segment>;
+    private _finishedText;
+    constructor(spinnerName?: string, options?: SpinnerColumnOptions);
+    render(task: Task): Renderable;
+}
+export interface MofNCompleteColumnOptions {
+    /** Drawn between the two counts: Rich's `separator`. Defaults to `"/"`. */
+    separator?: string;
 }
+/**
+ * Rich's `MofNCompleteColumn`: both counts as whole numbers, the completed one
+ * padded to the total's width so the column holds still as it counts up to its
+ * total, styled `progress.download`.
+ */
 export declare class MofNCompleteColumn implements ProgressColumn {
-    render(_options: RenderOptions, task?: Task): Iterable<Segment>;
+    readonly tableColumn: ColumnOptions;
+    readonly separator: string;
+    constructor(options?: MofNCompleteColumnOptions);
+    render(task: Task): RichText;
 }
 export interface ProgressOptions {
     refreshPerSecond?: number;
@@ -62,6 +144,11 @@ export interface ProgressOptions {
     transient?: boolean;
     expand?: boolean;
     console?: Console;
+    /**
+     * What tasks are timed by and frames are drawn on, Rich's `get_time`;
+     * defaults to the platform's monotonic clock. Handed on to the `Live`.
+     */
+    clock?: Clock;
 }
 export declare class Progress implements Renderable {
     private _columns;
@@ -69,9 +156,11 @@ export declare class Progress implements Renderable {
     private _nextId;
     private _live;
     private _console;
+    private readonly _clock;
     readonly expand: boolean;
     constructor(...columns: (ProgressColumn | ProgressOptions)[]);
     get console(): Console;
+    /** Rich's `Progress.finished`: every task finished, and so true with none. */
     get finished(): boolean;
     static getDefaultColumns(): ProgressColumn[];
     addTask(description: string, options?: TaskOptions): number;
@@ -87,4 +176,3 @@ export declare function track<T>(iterable: Iterable<T>, options?: {
     total?: number;
     console?: Console;
 }): Iterable<T>;
-export {};

package/dist/renderables/progress.js

@@ -1,100 +1,215 @@
 /**
  * Progress — displays continuously updated progress bars.
  */
-import { Segment } from "../core/segment.js";
 import { RichText } from "../core/text.js";
 import { Console } from "../core/console.js";
-import { escape as escapeMarkup } from "../core/markup.js";
-import { embeddedText } from "./embed.js";
+import { escape as escapeMarkup, readStr, renderStr } from "../core/markup.js";
 import { ProgressBar } from "./progressBar.js";
 import { Spinner } from "./spinner.js";
 import { Live } from "./live.js";
+import { systemClock } from "../core/clock.js";
 import { Table } from "./table.js";
-import { getStyle } from "../core/protocol.js";
+/**
+ * Rich's defaults for `speed_estimate_period` and its sample deque's
+ * `maxlen`: an update forgets samples older than the period, and the newest
+ * thousand are all a task keeps.
+ */
+const SPEED_ESTIMATE_PERIOD = 30;
+const MAX_SAMPLES = 1000;
+/**
+ * Rich's `Progress.update` bookkeeping on its sample deque, in place: drop the
+ * samples older than the period as of `now`, then add this update's if it
+ * moved the task forward, keeping the newest `MAX_SAMPLES`. The samples are in
+ * time order, so the stale ones are a prefix.
+ */
+function recordSample(samples, now, moved) {
+    const firstFresh = samples.findIndex((sample) => sample.timestamp >= now - SPEED_ESTIMATE_PERIOD);
+    samples.splice(0, firstFresh === -1 ? samples.length : firstFresh);
+    if (moved > 0)
+        samples.push({ timestamp: now, completed: moved });
+    samples.splice(0, samples.length - MAX_SAMPLES);
+}
+/**
+ * Rich's `Task.speed` over a started task's samples: everything moved after
+ * the first sample, over the time from the first to the last. No samples, or
+ * none apart in time, is no speed.
+ */
+function sampleSpeed(samples) {
+    const span = (samples.at(-1)?.timestamp ?? 0) - (samples[0]?.timestamp ?? 0);
+    if (span === 0)
+        return undefined;
+    return samples.slice(1).reduce((sum, sample) => sum + sample.completed, 0) / span;
+}
+/**
+ * A count as a task takes it in. [LAW:single-enforcer] `addTask` and
+ * `updateTask` are where counts enter, so a NaN or an Infinity is refused there,
+ * with the caller's stack, rather than drawn as `NaN%` by one column and thrown
+ * on a refresh tick by another.
+ */
+function finiteCount(field, value) {
+    if (!Number.isFinite(value))
+        throw new RangeError(`progress task ${field} must be a finite number, got ${value}`);
+    return value;
+}
+/** Rich's `Task.finished`. [LAW:one-source-of-truth] The one predicate every reader of "finished" asks. */
+function finished(task) {
+    return task.finishedTime !== undefined;
+}
 export class TextColumn {
     format;
+    /** Text is cut, never wrapped, as Rich's `TextColumn` defaults to `Column(no_wrap=True)`. */
+    tableColumn = { noWrap: true };
     constructor(format) {
         this.format = format ?? "{task.description}";
     }
-    *render(options, task) {
+    render(task) {
         // [LAW:single-enforcer] Format strings flow through the markup parser so
         // tags like `[progress.description]` become Style spans, not literal text.
         // Task descriptions are escaped first to prevent injection of stray tags.
-        const description = escapeMarkup(task?.description ?? "");
+        const description = escapeMarkup(task.description);
         // Use a callback so `$&`/`$1`/`$$` in the task description aren't
         // reinterpreted by String.replace as replacement patterns.
         const formatted = this.format.replace(/\{task\.description\}/g, () => description);
-        // [LAW:single-enforcer] A column is a row fragment, the same as any
-        // embedded text.
-        yield* embeddedText(formatted).render(options);
+        // Markup whatever the console says, and never highlighted: Rich's
+        // `TextColumn` reads its format as markup on its own `markup=True` and
+        // highlights only with a highlighter it was given, not the console's.
+        return renderStr(formatted, { markup: true });
     }
 }
 export class BarColumn {
     barWidth;
+    tableColumn = {};
     constructor(barWidth) {
         this.barWidth = barWidth ?? 40;
     }
-    *render(_options, task) {
-        const bar = new ProgressBar({
-            total: task?.total ?? 100,
-            completed: task?.completed ?? 0,
+    render(task) {
+        return new ProgressBar({
+            total: task.total ?? 100,
+            completed: task.completed,
             width: this.barWidth,
         });
-        yield* bar.render(_options);
     }
 }
+/**
+ * Rich's `{task.percentage:>3.0f}%`: the percentage right-aligned in three
+ * cells, so the column is four wide from 0% to 100% and the row does not
+ * shift as it counts. A task with no total shows nothing, Rich's
+ * `text_format_no_percentage`.
+ */
 export class TaskProgressColumn {
-    *render(options, task) {
-        const percent = task && task.total
-            ? Math.min(100, Math.round((task.completed / task.total) * 100))
-            : 0;
-        yield new Segment(`${percent}%`, getStyle(options, "progress.percentage"));
+    /** A `TextColumn` in Rich, and laid out as one. */
+    tableColumn = { noWrap: true };
+    render(task) {
+        const text = task.total === undefined ? "" : `${String(roundHalfEven(percentage(task))).padStart(3)}%`;
+        return new RichText(text, { style: "progress.percentage" });
     }
 }
+/** Rich's `Task.percentage`: 0 without a total, and clamped to [0, 100]. */
+function percentage(task) {
+    return task.total ? Math.min(100, Math.max(0, (task.completed / task.total) * 100)) : 0;
+}
+/**
+ * Python's `format(x, ".0f")`: the nearest integer to the double's exact
+ * value, a tie going to the even one. `Math.round` is exact too but sends a
+ * tie up, so only a tie is corrected.
+ */
+function roundHalfEven(x) {
+    const up = Math.round(x);
+    return up - x === 0.5 && up % 2 !== 0 ? up - 1 : up;
+}
 export class TimeRemainingColumn {
-    *render(options, task) {
-        const style = getStyle(options, "progress.remaining");
-        if (!task || !task.total || !task.started || task.completed <= 0) {
-            yield new Segment("-:--:--", style);
-            return;
-        }
-        const elapsed = (Date.now() - task.startTime) / 1000;
-        const rate = task.completed / elapsed;
-        const remaining = (task.total - task.completed) / rate;
-        yield new Segment(formatTime(remaining), style);
+    tableColumn = {};
+    elapsedWhenFinished;
+    constructor(options) {
+        this.elapsedWhenFinished = options?.elapsedWhenFinished ?? false;
+    }
+    render(task) {
+        const took = this.elapsedWhenFinished && finished(task) ? task.finishedTime : undefined;
+        const time = took ?? timeRemaining(task);
+        const style = took === undefined ? "progress.remaining" : "progress.elapsed";
+        // A task with no total has no time to estimate, and Rich draws its cell empty.
+        return new RichText(task.total === undefined ? "" : clockFace(time), { style });
     }
 }
+/**
+ * Rich's `Task.time_remaining`: nothing left once the task is finished,
+ * however long ago that was, unknown until it has a speed against a total,
+ * and otherwise whole seconds, rounded up.
+ */
+function timeRemaining(task) {
+    if (finished(task))
+        return 0;
+    if (!task.speed || task.total === undefined)
+        return undefined;
+    return Math.ceil((task.total - task.completed) / task.speed);
+}
 export class TimeElapsedColumn {
-    *render(options, task) {
-        const style = getStyle(options, "progress.elapsed");
-        if (!task || !task.started) {
-            yield new Segment("0:00:00", style);
-            return;
-        }
-        const elapsed = (Date.now() - task.startTime) / 1000;
-        yield new Segment(formatTime(elapsed), style);
+    tableColumn = {};
+    render(task) {
+        // Rich's `finished_time if finished else elapsed`: a finished task's clock
+        // holds where it stopped, and one never started has no time to show.
+        const time = finished(task) ? task.finishedTime : task.elapsed;
+        return new RichText(clockFace(time), { style: "progress.elapsed" });
     }
 }
+/** A time as the time columns draw it, `-:--:--` when there is none to draw. */
+function clockFace(seconds) {
+    return seconds === undefined ? "-:--:--" : formatTime(seconds);
+}
 export class SpinnerColumn {
+    tableColumn = {};
     _spinner;
-    constructor(spinnerName) {
-        this._spinner = new Spinner(spinnerName);
+    _finishedText;
+    constructor(spinnerName, options) {
+        this._spinner = new Spinner(spinnerName, "", {
+            style: options?.style ?? "progress.spinner",
+            speed: options?.speed,
+        });
+        // Markup whatever the console says, as Rich's `Text.from_markup`. A
+        // `RichText` is copied, since the caller still holds it.
+        const finishedText = options?.finishedText ?? " ";
+        this._finishedText = typeof finishedText === "string" ? readStr(finishedText, true) : finishedText.copy();
     }
-    *render(options, _task) {
-        yield* this._spinner.render(options);
+    render(task) {
+        return finished(task) ? this._finishedText : this._spinner;
     }
 }
+/**
+ * Rich's `MofNCompleteColumn`: both counts as whole numbers, the completed one
+ * padded to the total's width so the column holds still as it counts up to its
+ * total, styled `progress.download`.
+ */
 export class MofNCompleteColumn {
-    *render(_options, task) {
-        const completed = task?.completed ?? 0;
-        const total = task?.total ?? "?";
-        yield new Segment(`${completed}/${total}`);
+    tableColumn = {};
+    separator;
+    constructor(options) {
+        this.separator = options?.separator ?? "/";
+    }
+    render(task) {
+        const total = task.total === undefined ? "?" : wholeNumber(task.total);
+        const completed = wholeNumber(task.completed).padStart(total.length);
+        return new RichText(`${completed}${this.separator}${total}`, { style: "progress.download" });
     }
 }
+/**
+ * Python's `str(int(x))`: truncated toward zero and written out in full,
+ * never in exponent form. `Progress` admits only finite counts, so `BigInt`
+ * has nothing here to refuse.
+ */
+function wholeNumber(x) {
+    return BigInt(Math.trunc(x)).toString();
+}
+/**
+ * Rich's clock face: `int()` the seconds, then Python's floor `divmod` by 60
+ * twice, so a negative estimate — a task past its total — reads as Rich's
+ * does, `-3` as `-1:59:57`.
+ */
 function formatTime(seconds) {
-    const h = Math.floor(seconds / 3600);
-    const m = Math.floor((seconds % 3600) / 60);
-    const s = Math.floor(seconds % 60);
+    const whole = Math.trunc(seconds);
+    const minutes = Math.floor(whole / 60);
+    const h = Math.floor(minutes / 60);
+    const m = minutes - h * 60;
+    const s = whole - minutes * 60;
     return `${h}:${String(m).padStart(2, "0")}:${String(s).padStart(2, "0")}`;
 }
 export class Progress {
@@ -103,6 +218,7 @@ export class Progress {
     _nextId;
     _live;
     _console;
+    _clock;
     expand;
     constructor(...columns) {
         // Last arg might be options
@@ -122,10 +238,12 @@ export class Progress {
         this._columns = cols;
         this._tasks = new Map();
         this._nextId = 1;
-        this._console = opts.console ?? new Console({ forceTerminal: true });
+        this._console = opts.console ?? new Console();
         this.expand = opts.expand ?? false;
+        this._clock = opts.clock ?? systemClock();
         this._live = new Live(this, {
             console: this._console,
+            clock: this._clock,
             refreshPerSecond: opts.refreshPerSecond ?? 10,
             autoRefresh: opts.autoRefresh,
             transient: opts.transient,
@@ -134,13 +252,9 @@ export class Progress {
     get console() {
         return this._console;
     }
+    /** Rich's `Progress.finished`: every task finished, and so true with none. */
     get finished() {
-        for (const task of this._tasks.values()) {
-            if (!task.started || (task.total !== undefined && task.completed < task.total)) {
-                return false;
-            }
-        }
-        return this._tasks.size > 0;
+        return [...this._tasks.values()].every(finished);
     }
     static getDefaultColumns() {
         return [
@@ -155,12 +269,12 @@ export class Progress {
         const task = {
             id,
             description,
-            total: options?.total,
+            total: options?.total === undefined ? undefined : finiteCount("total", options.total),
             completed: 0,
-            started: options?.start !== false,
             visible: options?.visible !== false,
-            startTime: Date.now(),
-            elapsed: 0,
+            startTime: options?.start === false ? undefined : this._clock.now(),
+            finishedTime: undefined,
+            samples: [],
         };
         this._tasks.set(id, task);
         return id;
@@ -169,24 +283,32 @@ export class Progress {
         const task = this._tasks.get(taskId);
         if (!task)
             return;
-        if (options.completed !== undefined)
-            task.completed = options.completed;
-        if (options.advance !== undefined)
-            task.completed += options.advance;
+        // Rich's order, `completed` then `advance`, checked whole before any field
+        // is written, so a refused update leaves the task as it was.
+        const advance = finiteCount("advance", options.advance ?? 0);
+        const completed = finiteCount("completed", (options.completed ?? task.completed) + advance);
+        const now = this._clock.now();
+        recordSample(task.samples, now, completed - task.completed);
+        task.completed = completed;
         if (options.description !== undefined)
             task.description = options.description;
         if (options.visible !== undefined)
             task.visible = options.visible;
+        if (!finished(task) &&
+            task.startTime !== undefined &&
+            task.total !== undefined &&
+            task.completed >= task.total) {
+            task.finishedTime = now - task.startTime;
+        }
         if (options.refresh) {
             this._live.update(this, { refresh: true });
         }
     }
     startTask(taskId) {
         const task = this._tasks.get(taskId);
-        if (task) {
-            task.started = true;
-            task.startTime = Date.now();
-        }
+        // Rich's `start_task`: a task already running keeps the time it started.
+        if (task)
+            task.startTime ??= this._clock.now();
     }
     start() {
         this._live.start();
@@ -198,23 +320,25 @@ export class Progress {
         this._live.refresh();
     }
     *render(options) {
+        // Rich's `make_tasks_table`: each column laid out as it says.
         const table = Table.grid({ expand: this.expand });
-        for (const _col of this._columns) {
-            table.addColumn();
+        for (const col of this._columns) {
+            table.addColumn(undefined, col.tableColumn);
         }
-        for (const task of this._tasks.values()) {
-            if (!task.visible)
+        // [LAW:effects-at-boundaries] One read of the clock a frame, handed to
+        // every column as the task's `elapsed`.
+        const now = this._clock.now();
+        for (const { samples, ...state } of this._tasks.values()) {
+            if (!state.visible)
                 continue;
-            const cells = this._columns.map((col) => {
-                const segs = [...col.render(options, task)];
-                // Build a RichText that preserves segment styles as spans
-                const text = new RichText("", { end: "" });
-                for (const seg of segs) {
-                    text.append(seg.text, seg.style);
-                }
-                return text;
-            });
-            table.addRow(...cells);
+            const { startTime } = state;
+            const started = startTime !== undefined;
+            const task = {
+                ...state,
+                elapsed: started ? now - startTime : undefined,
+                speed: started ? sampleSpeed(samples) : undefined,
+            };
+            table.addRow(...this._columns.map((col) => col.render(task)));
         }
         yield* table.render(options);
     }

package/dist/renderables/progressBar.d.ts

@@ -22,9 +22,9 @@ export declare class ProgressBar implements Renderable, Measurable {
     readonly completeStyle: string | Style;
     readonly finishedStyle: string | Style;
     constructor(options?: ProgressBarOptions);
-    get percentComplete(): number;
     render(options: RenderOptions): Iterable<Segment>;
-    measure(_options: RenderOptions): {
+    /** A width given is the bar's exact width, as Rich measures it; one left open fills what it is offered, down to 4. */
+    measure(options: RenderOptions): {
         minimum: number;
         maximum: number;
     };

package/dist/renderables/progressBar.js

@@ -1,11 +1,14 @@
 /**
  * ProgressBar — a visual progress bar rendered with block characters.
  */
+import { cellCount } from "../core/cells.js";
 import { Segment } from "../core/segment.js";
 import { NULL_STYLE } from "../core/style.js";
 import { drawable, getStyle } from "../core/protocol.js";
 const BAR = "━";
 const ASCII_BAR = "-";
+const HALF_BAR_RIGHT = "╸";
+const HALF_BAR_LEFT = "╺";
 export class ProgressBar {
     total;
     completed;
@@ -23,31 +26,39 @@ export class ProgressBar {
         this.completeStyle = options?.completeStyle ?? "bar.complete";
         this.finishedStyle = options?.finishedStyle ?? "bar.finished";
     }
-    get percentComplete() {
-        if (this.total <= 0)
-            return 0;
-        return Math.min(1, Math.max(0, this.completed / this.total));
-    }
     *render(options) {
-        const barWidth = this.width ?? Math.min(40, options.maxWidth);
-        const percent = this.percentComplete;
-        const isFinished = percent >= 1;
-        const filledWidth = Math.round(barWidth * percent);
-        const emptyWidth = barWidth - filledWidth;
+        // Never wider than offered, as Rich's `min(self.width or max_width, max_width)`.
+        // [LAW:parse-dont-validate] parsed as a cell count, so a negative width draws nothing, as Python's `"━" * -2` is "".
+        const width = cellCount(Math.min(this.width || options.maxWidth, options.maxWidth));
+        // Rich 9d8f9a3 `__rich_console__`: the fill is counted in half cells, and
+        // a total of zero is a bar already full.
+        const completed = Math.min(this.total, Math.max(0, this.completed));
+        const completeHalves = this.total ? Math.trunc((width * 2 * completed) / this.total) : width * 2;
+        const barCount = Math.floor(completeHalves / 2);
+        const halfBarCount = completeHalves % 2;
+        const isFinished = this.completed >= this.total;
         const fill = getStyle(options, isFinished ? this.finishedStyle : this.completeStyle);
         const back = getStyle(options, this.style);
         const fillStyle = fill.isNull ? undefined : fill;
-        const bgStyle = back.isNull ? undefined : back;
+        const backStyle = back.isNull ? undefined : back;
         const bar = drawable(options, BAR, ASCII_BAR);
-        if (filledWidth > 0) {
-            yield new Segment(bar.repeat(filledWidth), fillStyle);
-        }
-        if (emptyWidth > 0) {
-            yield new Segment(bar.repeat(emptyWidth), bgStyle);
+        if (barCount)
+            yield new Segment(bar.repeat(barCount), fillStyle);
+        if (halfBarCount)
+            yield new Segment(drawable(options, HALF_BAR_RIGHT, " "), fillStyle);
+        // The back is drawn in colour alone, so an output with none leaves it blank.
+        if (options.colorSystem === null)
+            return;
+        let remaining = width - barCount - halfBarCount;
+        if (remaining && !halfBarCount && barCount) {
+            yield new Segment(drawable(options, HALF_BAR_LEFT, " "), backStyle);
+            remaining -= 1;
         }
+        if (remaining)
+            yield new Segment(bar.repeat(remaining), backStyle);
     }
-    measure(_options) {
-        const w = this.width ?? 40;
-        return { minimum: 4, maximum: w };
+    /** A width given is the bar's exact width, as Rich measures it; one left open fills what it is offered, down to 4. */
+    measure(options) {
+        return this.width === undefined ? { minimum: 4, maximum: options.maxWidth } : { minimum: this.width, maximum: this.width };
     }
 }