@lewishowles/cli-style 0.10.0 → 0.12.0

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 ## Unreleased
 
+## 0.12.0 - 2026-08-20
+
+### Added
+
+- Added `labelledLine(label, message, options)`, a general icon/label/message renderer with a configurable tone. `hint()` now delegates to it instead of duplicating its own rendering, with unchanged output for existing callers.
+- `row()` now wraps long values within the available row width (64 columns by default), instead of overflowing the line. Override with `wrapWidth`, or disable with `wrap: false`.
+
+## 0.11.0 - 2026-07-24
+
+### Added
+
+- Added a spinner/loading indicator for long-running JavaScript tasks: `ui.spinner.run(text, fn)` wraps a single async call, and `ui.spinner(text)` returns a handle (`update`, `succeed`, `fail`, `stop`) for cases that don't fit one call. Output always goes to stderr, animates only on an interactive terminal, and falls back to a static start/result line under CI, plain, JSON, or agent profiles. JavaScript-only; not available through the Bash, Python, or Swift adapters.
+
 ## 0.10.0 - 2026-07-20
 
 ### Added

package/README.md

@@ -582,6 +582,31 @@ const reporter = createReporter({
 });
 ```
 
+## Spinner
+
+Use a spinner when a JavaScript script runs a long task and needs progress feedback. Spinner output always goes to stderr, so piped or JSON stdout stays clean. On a non-interactive target (CI, plain, JSON, agent profiles, or non-TTY stdout) it prints a static start line and result line instead of animating.
+
+```js
+import { createCliStyle } from "@lewishowles/cli-style";
+
+const ui = createCliStyle();
+
+await ui.spinner.run("Building", async () => {
+	await runBuild();
+});
+```
+
+For cases that don't fit one awaited call, use the manual handle:
+
+```js
+const spinner = ui.spinner("Building");
+
+spinner.update("Building (2/3)");
+spinner.succeed("Build complete");
+```
+
+Only one spinner can be active at a time; starting a second while one is running throws.
+
 ## Options and flags
 
 ### JavaScript options

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@lewishowles/cli-style",
-	"version": "0.10.0",
+	"version": "0.12.0",
 	"description": "Shared terminal output styles for Lewis Howles tools, diagnostics, and package CLIs.",
 	"license": "MIT",
 	"repository": {
@@ -32,14 +32,14 @@
 		"check": "vp check --fix",
 		"cli-style:gallery": "bun ./bin/cli-style.js gallery",
 		"package:binary": "scripts/package-binary.sh",
-		"prepare": "vp config",
+		"prepare": "vp config --no-agent",
 		"smoke:binary": "./dist/bin/cli-style render status --plain < tests/fixtures/render/status-success.json",
 		"test:unit": "bun test"
 	},
 	"devDependencies": {
 		"@stylistic/eslint-plugin": "^5.10.0",
-		"vite": "npm:@voidzero-dev/vite-plus-core@0.2.1",
-		"vite-plus": "0.2.1"
+		"vite": "npm:@voidzero-dev/vite-plus-core@0.2.8",
+		"vite-plus": "0.2.8"
 	},
 	"engines": {
 		"node": ">=20"

package/src/catalogue/renderer-catalogue.js

@@ -25,11 +25,18 @@ export const rendererCatalogue = [
 	["empty-state", "primitive", "emptyState", ["detail", "title"], undefined],
 	["error-block", "primitive", "errorBlock", ["lines", "title"], undefined],
 	["hint", "primitive", "hint", ["message"], undefined],
+	[
+		"labelled-line",
+		"primitive",
+		"labelledLine",
+		["icon", "label", "message", "wrap", "wrapWidth"],
+		undefined,
+	],
 	["next-step-block", "pattern", "nextStepBlock", ["next", "reason"], "next-step-block"],
 	["panel", "primitive", "panel", ["lines", "title", "tone"], undefined],
 	["progress-bar", "primitive", "progressBar", ["max", "value"], undefined],
-	["row", "primitive", "row", ["label", "value"], undefined],
-	["row-group", "primitive", "rowGroup", ["rows"], undefined],
+	["row", "primitive", "row", ["label", "value", "wrap", "wrapWidth"], undefined],
+	["row-group", "primitive", "rowGroup", ["rows", "wrap", "wrapWidth"], undefined],
 	["sparkline", "primitive", "sparkline", ["values"], "sparkline"],
 	["span", "primitive", "span", ["tone", "value"], undefined],
 	["status", "primitive", "status", ["detail", "type"], undefined],

package/src/cli/render-command.js

@@ -11,6 +11,7 @@ import { barChart } from "../primitives/bar-chart.js";
 import { chip } from "../primitives/chip.js";
 import { divider } from "../primitives/divider.js";
 import { emptyState, errorBlock, hint } from "../primitives/feedback.js";
+import { labelledLine } from "../primitives/labelled-line.js";
 import { panel } from "../primitives/panel.js";
 import { progressBar } from "../primitives/progress-bar.js";
 import { row } from "../primitives/row.js";
@@ -62,6 +63,11 @@ const renderers = {
 			...input,
 			...options,
 		}),
+	"labelled-line": (input, options) =>
+		labelledLine(input.label, input.message, {
+			...input,
+			...options,
+		}),
 	"next-step-block": (input, options) => nextStepBlock(input, options),
 	panel: (input, options) =>
 		panel({

package/src/create-cli-style.js

@@ -1,5 +1,6 @@
 import { resolveProfile } from "./capability/resolve-profile.js";
 import { resolveTerminalCapabilities } from "./capability/terminal.js";
+import { runSpinner, spinner as startSpinner } from "./interactive/spinner.js";
 import { profiles } from "./profiles/profiles.js";
 import { createReporter } from "./reporters/create-reporter.js";
 
@@ -23,6 +24,18 @@ export function createCliStyle(options = {}) {
 	applyExplicitOption(resolvedOptions, options, "unicode");
 	applyExplicitOption(resolvedOptions, options, "width");
 
+	const spinner = (text, spinnerOptions = {}) =>
+		startSpinner(text, {
+			...resolvedOptions,
+			...spinnerOptions,
+		});
+
+	spinner.run = (text, fn, spinnerOptions = {}) =>
+		runSpinner(text, fn, {
+			...resolvedOptions,
+			...spinnerOptions,
+		});
+
 	return {
 		options: resolvedOptions,
 		print: (value) => {
@@ -33,6 +46,7 @@ export function createCliStyle(options = {}) {
 				...resolvedOptions,
 				...reporterOptions,
 			}),
+		spinner,
 		write: (value) => {
 			process.stdout.write(value);
 		},

package/src/formatters/wrap.js

@@ -0,0 +1,220 @@
+// Width used when a caller doesn't provide one.
+const defaultWrapWidth = 64;
+const escapeCharacter = String.fromCharCode(27);
+const bellCharacter = String.fromCharCode(7);
+
+// Matches ANSI CSI and OSC escape sequences so they can be measured as zero-width.
+const ansiEscapePattern = new RegExp(
+	`${escapeCharacter}(?:\\[[0-?]*[ -/]*[@-~]|\\][^${bellCharacter}]*(?:${bellCharacter}|${escapeCharacter}\\\\))`,
+	"gu",
+);
+
+/**
+ * Wrap text to a maximum visible width, treating ANSI escape sequences as zero-width.
+ *
+ * @param  {string}  text
+ *     Text to wrap.
+ * @param  {number}  width
+ *     Maximum visible width per line.
+ * @returns  {string[]}
+ *     Wrapped lines.
+ */
+export function wrapText(text, width = defaultWrapWidth) {
+	const wrapWidth = resolveWrapWidth(width);
+	const tokens = tokenise(String(text));
+	const lines = [];
+
+	let line = [];
+
+	for (const token of tokens) {
+		if (token.value === "\n") {
+			lines.push(renderTokens(line));
+			line = [];
+			continue;
+		}
+
+		line.push(token);
+
+		while (visibleWidth(line) > wrapWidth) {
+			const whitespaceIndex = findLastWhitespace(line);
+
+			if (whitespaceIndex > 0) {
+				const left = line.slice(0, whitespaceIndex);
+
+				lines.push(renderTokens(left));
+				line = trimLeadingWhitespace(line.slice(whitespaceIndex + 1));
+				continue;
+			}
+
+			const splitIndex = findHardSplitIndex(line, wrapWidth);
+
+			lines.push(renderTokens(line.slice(0, splitIndex)));
+			line = line.slice(splitIndex);
+		}
+	}
+
+	lines.push(renderTokens(line));
+
+	return lines;
+}
+
+/**
+ * Resolve a usable wrap width, falling back to the default for invalid input.
+ *
+ * @param  {number}  width
+ *     Requested wrap width.
+ * @returns  {number}
+ *     Whole-number wrap width of at least 1.
+ */
+function resolveWrapWidth(width) {
+	const numericWidth = Number(width);
+
+	if (!Number.isFinite(numericWidth) || numericWidth < 1) {
+		return defaultWrapWidth;
+	}
+
+	return Math.floor(numericWidth);
+}
+
+/**
+ * Split text into visible characters and ANSI escape sequences.
+ *
+ * @param  {string}  text
+ *     Text to tokenise.
+ * @returns  {object[]}
+ *     Tokens, each with a `value` and its `visibleWidth`.
+ */
+function tokenise(text) {
+	const tokens = [];
+
+	let textStart = 0;
+
+	for (const match of text.matchAll(ansiEscapePattern)) {
+		appendTextTokens(tokens, text.slice(textStart, match.index));
+		tokens.push({
+			value: match[0],
+			visibleWidth: 0,
+		});
+		textStart = match.index + match[0].length;
+	}
+
+	appendTextTokens(tokens, text.slice(textStart));
+
+	return tokens;
+}
+
+/**
+ * Append one token per character of plain text to a token list.
+ *
+ * @param  {object[]}  tokens
+ *     Token list to append to.
+ * @param  {string}  text
+ *     Plain text, with no ANSI escape sequences.
+ * @returns  {void}
+ */
+function appendTextTokens(tokens, text) {
+	for (const value of text) {
+		tokens.push({
+			value,
+			visibleWidth: value === "\n" ? 0 : 1,
+		});
+	}
+}
+
+/**
+ * Sum the visible width of a list of tokens.
+ *
+ * @param  {object[]}  tokens
+ *     Tokens to measure.
+ * @returns  {number}
+ *     Total visible width.
+ */
+function visibleWidth(tokens) {
+	return tokens.reduce((width, token) => width + token.visibleWidth, 0);
+}
+
+/**
+ * Find the index of the last whitespace token, to break a line at a word boundary.
+ *
+ * @param  {object[]}  tokens
+ *     Tokens to search.
+ * @returns  {number}
+ *     Index of the last whitespace token, or -1 when none is found.
+ */
+function findLastWhitespace(tokens) {
+	for (let index = tokens.length - 1; index >= 0; index -= 1) {
+		const token = tokens[index];
+
+		if (token.visibleWidth === 1 && /\s/u.test(token.value)) {
+			return index;
+		}
+	}
+
+	return -1;
+}
+
+/**
+ * Find the index to split at when a line has no whitespace to break on.
+ *
+ * @param  {object[]}  tokens
+ *     Tokens to search.
+ * @param  {number}  width
+ *     Maximum visible width for the first segment.
+ * @returns  {number}
+ *     Index at which to split the tokens.
+ */
+function findHardSplitIndex(tokens, width) {
+	let currentWidth = 0;
+
+	for (let index = 0; index < tokens.length; index += 1) {
+		currentWidth += tokens[index].visibleWidth;
+
+		if (currentWidth >= width) {
+			return index + 1;
+		}
+	}
+
+	return tokens.length;
+}
+
+/**
+ * Remove leading whitespace tokens from a wrapped continuation line.
+ *
+ * @param  {object[]}  tokens
+ *     Tokens to trim.
+ * @returns  {object[]}
+ *     Tokens with leading whitespace removed.
+ */
+function trimLeadingWhitespace(tokens) {
+	const trimmedTokens = [];
+
+	let hasVisibleText = false;
+
+	for (const token of tokens) {
+		if (token.visibleWidth === 0) {
+			trimmedTokens.push(token);
+			continue;
+		}
+
+		if (!hasVisibleText && /\s/u.test(token.value)) {
+			continue;
+		}
+
+		hasVisibleText = true;
+		trimmedTokens.push(token);
+	}
+
+	return trimmedTokens;
+}
+
+/**
+ * Join a list of tokens back into a string.
+ *
+ * @param  {object[]}  tokens
+ *     Tokens to render.
+ * @returns  {string}
+ *     Rendered text.
+ */
+function renderTokens(tokens) {
+	return tokens.map((token) => token.value).join("");
+}

package/src/gallery/render-gallery.js

@@ -8,10 +8,12 @@ import { diffBlock } from "../patterns/diff-block.js";
 import { nextStepBlock } from "../patterns/next-step-block.js";
 import { taskSummary } from "../patterns/task-summary.js";
 import { stripAnsi } from "../formatters/ansi.js";
+import { renderSpinnerFrame } from "../interactive/spinner.js";
 import { barChart } from "../primitives/bar-chart.js";
 import { chip } from "../primitives/chip.js";
 import { divider } from "../primitives/divider.js";
 import { emptyState, errorBlock, hint } from "../primitives/feedback.js";
+import { labelledLine } from "../primitives/labelled-line.js";
 import { panel } from "../primitives/panel.js";
 import { progressBar } from "../primitives/progress-bar.js";
 import { row } from "../primitives/row.js";
@@ -131,6 +133,7 @@ export const galleryFixtures = [
 	"next-step-block",
 	"diff-block",
 	"sparkline",
+	"spinner",
 ];
 
 /**
@@ -183,11 +186,7 @@ function renderVariant(variant, options, request) {
 	const sections = [];
 
 	if (request.fixture !== undefined) {
-		sections.push(
-			request.fixture === "sparkline"
-				? renderSparklineFixture(resolvedVariant.options)
-				: renderPatterns(resolvedVariant.options, request.fixture),
-		);
+		sections.push(renderFocusedFixture(request.fixture, resolvedVariant.options));
 	} else {
 		if (request.section === undefined || request.section === "primitives") {
 			sections.push(renderPrimitives(resolvedVariant.options));
@@ -676,6 +675,40 @@ function renderSparklineFixture(options) {
 	return ["Sparkline", frameExample(renderSparklineExample(options), options)].join("\n");
 }
 
+/**
+ * Render the focused spinner fixture.
+ *
+ * @param  {object}  options
+ *     Rendering options.
+ * @returns  {string}
+ *     Framed spinner fixture output.
+ */
+function renderSpinnerFixture(options) {
+	return ["Spinner", frameExample(renderSpinnerExample(options), options)].join("\n");
+}
+
+/**
+ * Render one fixture selected through `--fixture`.
+ *
+ * @param  {string}  fixture
+ *     Requested fixture name.
+ * @param  {object}  options
+ *     Rendering options.
+ * @returns  {string}
+ *     Framed fixture output.
+ */
+function renderFocusedFixture(fixture, options) {
+	if (fixture === "sparkline") {
+		return renderSparklineFixture(options);
+	}
+
+	if (fixture === "spinner") {
+		return renderSpinnerFixture(options);
+	}
+
+	return renderPatterns(options, fixture);
+}
+
 /**
  * Add gallery-only framing around one rendered example.
  *
@@ -719,6 +752,9 @@ function renderPrimitives(options) {
 		"Progress bars",
 		...renderProgressExamples(options),
 		"",
+		"Spinner",
+		renderSpinnerExample(options),
+		"",
 		"Bar charts",
 		renderBarChartExample(options),
 		"",
@@ -736,6 +772,11 @@ function renderPrimitives(options) {
 		"",
 		"Feedback",
 		hint(`Run ${span("npm run docs:readme", "info", options)}`, options),
+		labelledLine("Notice", "Reusable labelled output", {
+			...options,
+			icon: "!",
+			tone: "warning",
+		}),
 		emptyState("No results", "tone: muted", options),
 		errorBlock("Failed", ["tone: danger"], {
 			...options,
@@ -773,6 +814,23 @@ function renderPrimitives(options) {
 			labelWidth: 8,
 			result: resultTypes.FAILED,
 		}),
+		row(
+			"Description",
+			"This value wraps at the default width so long diagnostic details remain readable in a terminal.",
+			{
+				...options,
+				labelWidth: 11,
+			},
+		),
+		row(
+			"Raw output",
+			"This long value keeps its original line because wrapping is disabled for raw output.",
+			{
+				...options,
+				labelWidth: 11,
+				wrap: false,
+			},
+		),
 		"",
 		"Row groups",
 		rowGroup({
@@ -795,6 +853,10 @@ function renderPrimitives(options) {
 					result: resultTypes.FAILED,
 					value: "is 22.3 KB, above the 12.0 KB budget",
 				},
+				{
+					label: "Description",
+					value: "This group value inherits the default wrapping used by each row in the group.",
+				},
 			],
 		}),
 	].join("\n");
@@ -912,6 +974,26 @@ function renderSparklineExample(options) {
 		.join("\n");
 }
 
+/**
+ * Render static loading, success, and fail frames for the spinner primitive.
+ *
+ * The gallery shows fixed snapshots rather than a live animation, so no timer is started.
+ *
+ * @param  {object}  options
+ *     Rendering options.
+ * @returns  {string}
+ *     Spinner state examples.
+ */
+function renderSpinnerExample(options) {
+	const label = "Running task";
+
+	return [
+		renderSpinnerFrame(label, 0, options),
+		status(resultTypes.SUCCESS, "", { ...options, label }),
+		status(resultTypes.FAILED, "", { ...options, label }),
+	].join("\n");
+}
+
 /**
  * Render common progress values and tones.
  *

package/src/index.js

@@ -29,6 +29,7 @@ export {
 
 export { background, foreground, stripAnsi, style } from "./formatters/ansi.js";
 export { defaultWidth, minimumWidth, normaliseWidth } from "./formatters/width.js";
+export { renderSpinnerFrame, runSpinner, spinner } from "./interactive/spinner.js";
 export { agentTranscript } from "./patterns/agent-transcript.js";
 export { auditFinding } from "./patterns/audit-finding.js";
 export { commandResult } from "./patterns/command-result.js";
@@ -42,6 +43,7 @@ export { barChart } from "./primitives/bar-chart.js";
 export { chip } from "./primitives/chip.js";
 export { divider } from "./primitives/divider.js";
 export { emptyState, errorBlock, hint } from "./primitives/feedback.js";
+export { labelledLine } from "./primitives/labelled-line.js";
 export { panel } from "./primitives/panel.js";
 export { progressBar } from "./primitives/progress-bar.js";
 export { row } from "./primitives/row.js";

package/src/interactive/spinner.js

@@ -0,0 +1,335 @@
+import { foreground } from "../formatters/ansi.js";
+import { profiles } from "../profiles/profiles.js";
+import { status } from "../primitives/status.js";
+import { resultTypes } from "../theme/results.js";
+
+// Frame glyphs cycled while a spinner is animating.
+const unicodeFrames = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+const asciiFrames = ["-", "\\", "|", "/"];
+
+// Time between animated frame redraws.
+const frameIntervalMs = 80;
+
+// Built from a character code, rather than a string escape, so the control byte stays visible in diffs.
+const escapeCharacter = String.fromCharCode(27);
+
+// ANSI cursor and line-clear sequences used only on an interactive TTY.
+const hideCursor = `${escapeCharacter}[?25l`;
+const showCursor = `${escapeCharacter}[?25h`;
+const clearLine = `\r${escapeCharacter}[2K`;
+
+// Profiles that always use the static, non-animated spinner output.
+const nonInteractiveProfiles = new Set([
+	profiles.AGENT,
+	profiles.CI,
+	profiles.JSON,
+	profiles.PLAIN,
+]);
+
+// Spinner currently writing output; only one may be active at a time.
+let runningSpinner = null;
+
+// Whether the process-exit cleanup listener has been registered.
+let cleanupRegistered = false;
+
+/**
+ * Start a spinner and return a manual handle for advanced lifecycle control.
+ *
+ * @param  {string}  text
+ *     Initial spinner text.
+ * @param  {object}  options
+ *     Rendering and capability options.
+ * @param  {boolean}  options.colour
+ *     Whether ANSI colour should be applied.
+ * @param  {boolean}  options.isTty
+ *     Whether stdout is an interactive terminal.
+ * @param  {string}  options.profile
+ *     Resolved output profile.
+ * @param  {object}  options.stream
+ *     Writable stream the spinner writes to. Defaults to `process.stderr`.
+ * @param  {boolean}  options.unicode
+ *     Whether Unicode symbols should be used.
+ * @returns  {object}
+ *     Handle with `update`, `succeed`, `fail`, and `stop` methods.
+ */
+export function spinner(text, options = {}) {
+	if (runningSpinner !== null) {
+		throw new Error("A spinner is already active; stop it before starting another.");
+	}
+
+	const state = {
+		active: true,
+		frameIndex: 0,
+		interactive: isInteractive(options),
+		options,
+		stream: options.stream ?? process.stderr,
+		text,
+		timer: null,
+	};
+
+	runningSpinner = state;
+	registerCleanup();
+	startSpinnerState(state);
+
+	return {
+		fail: (finalText) => finishSpinnerState(state, resultTypes.FAILED, finalText),
+		stop: () => stopSpinnerState(state),
+		succeed: (finalText) => finishSpinnerState(state, resultTypes.SUCCESS, finalText),
+		update: (nextText) => updateSpinnerState(state, nextText),
+	};
+}
+
+/**
+ * Run an async task behind a spinner, resolving or rejecting it unchanged.
+ *
+ * @param  {string}  text
+ *     Spinner text shown while the task runs.
+ * @param  {Function}  fn
+ *     Async task to run.
+ * @param  {object}  options
+ *     Rendering and capability options, forwarded to `spinner()`.
+ * @returns  {Promise<*>}
+ *     Resolved value of `fn`, or its rejection rethrown after cleanup.
+ */
+export async function runSpinner(text, fn, options = {}) {
+	const handle = spinner(text, options);
+
+	try {
+		const result = await fn();
+
+		handle.succeed();
+
+		return result;
+	} catch (error) {
+		handle.fail();
+
+		throw error;
+	} finally {
+		handle.stop();
+	}
+}
+
+/**
+ * Render one animated spinner frame without starting a timer.
+ *
+ * @param  {string}  text
+ *     Spinner text to show alongside the frame glyph.
+ * @param  {number}  frameIndex
+ *     Frame position to render.
+ * @param  {object}  options
+ *     Rendering options.
+ * @param  {boolean}  options.colour
+ *     Whether ANSI colour should be applied.
+ * @param  {boolean}  options.unicode
+ *     Whether Unicode symbols should be used.
+ * @returns  {string}
+ *     Rendered frame line.
+ */
+export function renderSpinnerFrame(text, frameIndex, options = {}) {
+	const frames = options.unicode === false ? asciiFrames : unicodeFrames;
+	const glyph = frames[frameIndex % frames.length];
+	const colouredGlyph = foreground(glyph, "info", options);
+
+	return `${colouredGlyph} ${text}`;
+}
+
+/**
+ * Determine whether a spinner should animate on the current output target.
+ *
+ * @param  {object}  options
+ *     Rendering and capability options.
+ * @returns  {boolean}
+ *     Whether the spinner can animate.
+ */
+function isInteractive(options) {
+	return options.isTty === true && !nonInteractiveProfiles.has(options.profile);
+}
+
+/**
+ * Write the initial spinner output for a state, starting the frame timer when interactive.
+ *
+ * @param  {object}  state
+ *     Spinner state to start.
+ * @returns  {void}
+ */
+function startSpinnerState(state) {
+	if (!state.interactive) {
+		state.stream.write(
+			`${status(resultTypes.INFO, "", { ...state.options, label: state.text })}\n`,
+		);
+
+		return;
+	}
+
+	state.stream.write(hideCursor);
+	renderFrame(state);
+
+	state.timer = setInterval(() => tickSpinnerState(state), frameIntervalMs);
+	state.timer.unref?.();
+}
+
+/**
+ * Advance and redraw the animated frame for a state.
+ *
+ * @param  {object}  state
+ *     Spinner state to advance.
+ * @returns  {void}
+ */
+function tickSpinnerState(state) {
+	state.frameIndex += 1;
+
+	renderFrame(state);
+}
+
+/**
+ * Redraw the current animated frame in place.
+ *
+ * @param  {object}  state
+ *     Spinner state to render.
+ * @returns  {void}
+ */
+function renderFrame(state) {
+	state.stream.write(
+		`${clearLine}${renderSpinnerFrame(state.text, state.frameIndex, state.options)}`,
+	);
+}
+
+/**
+ * Update the text shown by an active spinner.
+ *
+ * @param  {object}  state
+ *     Spinner state to update.
+ * @param  {string}  nextText
+ *     Replacement spinner text.
+ * @returns  {void}
+ */
+function updateSpinnerState(state, nextText) {
+	if (!state.active) {
+		return;
+	}
+
+	state.text = nextText;
+
+	if (state.interactive) {
+		renderFrame(state);
+	}
+}
+
+/**
+ * Stop a spinner without printing a result line.
+ *
+ * @param  {object}  state
+ *     Spinner state to stop.
+ * @returns  {void}
+ */
+function stopSpinnerState(state) {
+	if (!state.active) {
+		return;
+	}
+
+	state.active = false;
+	clearSpinnerTimer(state);
+
+	if (state.interactive) {
+		state.stream.write(`${clearLine}${showCursor}`);
+	}
+
+	if (runningSpinner === state) {
+		runningSpinner = null;
+	}
+}
+
+/**
+ * Stop a spinner and print a success or fail result line.
+ *
+ * @param  {object}  state
+ *     Spinner state to finish.
+ * @param  {string}  resultType
+ *     Result type to display, from `resultTypes`.
+ * @param  {string}  finalText
+ *     Optional replacement text for the result line.
+ * @returns  {void}
+ */
+function finishSpinnerState(state, resultType, finalText) {
+	if (!state.active) {
+		return;
+	}
+
+	state.active = false;
+	clearSpinnerTimer(state);
+
+	const label = finalText ?? state.text;
+	const line = status(resultType, "", { ...state.options, label });
+
+	if (state.interactive) {
+		state.stream.write(`${clearLine}${showCursor}${line}\n`);
+	} else {
+		state.stream.write(`${line}\n`);
+	}
+
+	if (runningSpinner === state) {
+		runningSpinner = null;
+	}
+}
+
+/**
+ * Clear an active state's frame timer, when one exists.
+ *
+ * @param  {object}  state
+ *     Spinner state to clear.
+ * @returns  {void}
+ */
+function clearSpinnerTimer(state) {
+	if (state.timer !== null) {
+		clearInterval(state.timer);
+		state.timer = null;
+	}
+}
+
+/**
+ * Restore the cursor for an active, interactive spinner, stop its frame timer, and clear the
+ * running reference.
+ *
+ * @returns  {void}
+ */
+function restoreRunningSpinner() {
+	if (runningSpinner !== null) {
+		clearSpinnerTimer(runningSpinner);
+
+		if (runningSpinner.interactive) {
+			runningSpinner.stream.write(`${clearLine}${showCursor}`);
+		}
+	}
+
+	runningSpinner = null;
+}
+
+/**
+ * Restore the cursor on SIGINT, then re-raise the signal so the process still terminates with
+ * Node's default SIGINT exit code. A listener that did not re-raise would silently replace that
+ * default termination, leaving the process running whenever other work still holds the event loop
+ * open.
+ *
+ * @returns  {void}
+ */
+function handleSpinnerSigint() {
+	restoreRunningSpinner();
+	process.removeListener("SIGINT", handleSpinnerSigint);
+	process.kill(process.pid, "SIGINT");
+}
+
+/**
+ * Register process-exit and SIGINT listeners, once, that restore the cursor for an interrupted spinner.
+ *
+ * @returns  {void}
+ */
+function registerCleanup() {
+	if (cleanupRegistered) {
+		return;
+	}
+
+	cleanupRegistered = true;
+
+	process.on("exit", restoreRunningSpinner);
+	process.on("SIGINT", handleSpinnerSigint);
+}

package/src/primitives/feedback.js

@@ -1,5 +1,6 @@
 import { foreground, style } from "../formatters/ansi.js";
 import { getResultSymbol, resultTypes } from "../theme/results.js";
+import { labelledLine } from "./labelled-line.js";
 import { panel } from "./panel.js";
 
 /**
@@ -15,15 +16,11 @@ import { panel } from "./panel.js";
  *     Rendered hint.
  */
 export function hint(message = "", options = {}) {
-	const prefix = "i Hint:";
-
-	if (options.colour !== true) {
-		return `${prefix} ${message}`;
-	}
-
-	const renderedPrefix = style(foreground(prefix, "info", options), "bold", options);
-
-	return `${renderedPrefix} ${message}`;
+	return labelledLine("Hint", message, {
+		icon: "i",
+		tone: "info",
+		...options,
+	});
 }
 
 /**

package/src/primitives/labelled-line.js

@@ -0,0 +1,134 @@
+import { foreground, style } from "../formatters/ansi.js";
+import { wrapText } from "../formatters/wrap.js";
+
+// Falls back to the informational tone when no colour token is given.
+const defaultColour = "info";
+
+// Sits between the colon-terminated prefix and the message.
+const messageSeparator = " ";
+
+/**
+ * Render an icon, label, and message as one wrapped line.
+ *
+ * @param  {string}  label
+ *     Label shown before the message; omit for an unlabelled line.
+ * @param  {string}  message
+ *     Message text.
+ * @param  {object}  options
+ *     Rendering options.
+ * @param  {boolean}  options.colour
+ *     Whether ANSI colour should be applied.
+ * @param  {string}  options.icon
+ *     Optional icon shown before the label.
+ * @param  {string}  options.tone
+ *     Colour token for the icon and label when colour is enabled; defaults to "info".
+ * @param  {number}  options.width
+ *     Total line width; the message width is this minus the label and separator.
+ * @param  {boolean}  options.wrap
+ *     Set to false to keep the message on one line instead of wrapping it.
+ * @param  {number}  options.wrapWidth
+ *     Column width at which the message wraps onto a new line.
+ * @returns  {string}
+ *     Rendered labelled line.
+ */
+export function labelledLine(label = "", message = "", options = {}) {
+	const prefixText = createPrefix(label, options);
+	const prefix = renderPrefix(prefixText, options);
+	const messageText = String(message);
+
+	if (prefix === "") {
+		return messageText;
+	}
+
+	if (options.wrap === false) {
+		return `${prefix}${messageSeparator}${messageText}`;
+	}
+
+	const wrapWidth = resolveWrapWidth(prefixText, options);
+	const messageLines = wrapText(messageText, wrapWidth);
+	const continuationIndent = " ".repeat(prefixText.length + messageSeparator.length);
+	const wrappedMessage = messageLines.join(`\n${continuationIndent}`);
+
+	return `${prefix}${messageSeparator}${wrappedMessage}`;
+}
+
+/**
+ * Colour the icon/label prefix, sized from its plain-text length so the
+ * continuation indent lines up whether or not colour is applied.
+ *
+ * @param  {string}  prefix
+ *     Plain-text icon and label prefix.
+ * @param  {object}  options
+ *     Rendering options.
+ * @returns  {string}
+ *     Prefix, coloured when requested.
+ */
+function renderPrefix(prefix, options) {
+	if (prefix === "") {
+		return prefix;
+	}
+
+	if (options.colour !== true) {
+		return prefix;
+	}
+
+	const colouredPrefix = foreground(prefix, resolveColour(options), options);
+
+	return style(colouredPrefix, "bold", options);
+}
+
+/**
+ * Build the plain-text icon and label prefix.
+ *
+ * @param  {string}  label
+ *     Label text.
+ * @param  {object}  options
+ *     Rendering options.
+ * @returns  {string}
+ *     Icon and label joined with a colon and space, or an empty string when both are empty.
+ */
+function createPrefix(label, options) {
+	const labelText = String(label);
+	const icon = typeof options.icon === "string" ? options.icon : "";
+	const labelPart = labelText === "" ? "" : `${labelText}:`;
+
+	return [icon, labelPart].filter((part) => part !== "").join(" ");
+}
+
+/**
+ * Pick the prefix's colour token.
+ *
+ * @param  {object}  options
+ *     Rendering options.
+ * @returns  {string}
+ *     Colour token, defaulting to "info" when no tone is given.
+ */
+function resolveColour(options) {
+	if (typeof options.tone === "string" && options.tone !== "") {
+		return options.tone;
+	}
+
+	return defaultColour;
+}
+
+/**
+ * Work out how wide the message can be before it wraps.
+ *
+ * @param  {string}  prefix
+ *     Plain-text icon and label prefix, used to size the continuation indent.
+ * @param  {object}  options
+ *     Rendering options.
+ * @returns  {number|undefined}
+ *     Explicit or derived wrap width, or undefined to use wrapText's own default.
+ */
+function resolveWrapWidth(prefix, options) {
+	if (options.wrapWidth !== undefined) {
+		return options.wrapWidth;
+	}
+
+	if (Number.isFinite(options.width)) {
+		return Math.max(1, options.width - prefix.length - messageSeparator.length);
+	}
+
+	return undefined;
+}

package/src/primitives/row.js

@@ -1,4 +1,5 @@
 import { foreground } from "../formatters/ansi.js";
+import { wrapText } from "../formatters/wrap.js";
 import { getResultSymbol, getResultToken } from "../theme/results.js";
 
 // Row labels use the same subdued tone as table headers by default.
@@ -7,6 +8,9 @@ const defaultLabelColour = "muted";
 // Rows use a compact gap that still reads cleanly in plain terminals.
 const defaultSeparator = "  ";
 
+// Keeps a wrapped value within a typical narrow terminal column.
+const defaultWrapWidth = 64;
+
 /**
  * Render a labelled value row.
  *
@@ -28,6 +32,12 @@ const defaultSeparator = "  ";
  *     Text between label and value.
  * @param  {string}  options.valueColour
  *     Optional colour token for the value.
+ * @param  {number}  options.width
+ *     Total row width used to calculate the available value width.
+ * @param  {boolean}  options.wrap
+ *     Set to false to keep the value on one line instead of wrapping it.
+ * @param  {number}  options.wrapWidth
+ *     Column width at which a value wraps onto a new line.
  * @returns  {string}
  *     Rendered row.
  */
@@ -45,7 +55,22 @@ export function row(label, value = "", options = {}) {
 	const renderedValue = renderValue(value, options);
 	const separator = options.separator ?? defaultSeparator;
 
-	return `${renderedLabel}${separator}${renderedValue}`;
+	if (options.wrap === false) {
+		return `${renderedLabel}${separator}${renderedValue}`;
+	}
+
+	const wrapWidth =
+		options.wrapWidth ??
+		(Number.isFinite(options.width)
+			? Math.max(1, options.width - labelWidth - separator.length)
+			: defaultWrapWidth);
+
+	const valueLines = wrapText(value, wrapWidth);
+	const continuationIndent = " ".repeat(labelWidth + separator.length);
+	const renderedValueLines = valueLines.map((line) => renderValue(line, options));
+	const wrappedValue = renderedValueLines.join(`\n${continuationIndent}`);
+
+	return `${renderedLabel}${separator}${wrappedValue}`;
 }
 
 /**