@lewishowles/cli-style 0.17.0 → 0.17.1

package/CHANGELOG.md

@@ -1,6 +1,23 @@
 # Changelog
 
-## Unreleased
+## 0.17.1 - 2026-10-20
+
+### Changed
+
+- The package now depends on `get-east-asian-width` to measure wide characters.
+
+### Fixed
+
+- Spans, chips, status lines and empty states now keep their own colour, weight and chip background after caller-coloured text.
+- Labelled lines now keep their bold prefix and tone colour after a caller-coloured icon or label.
+- Panels now keep their background, text colour and bold title to the end of a line that holds coloured text.
+- Panels now fill every line to the panel width when it holds coloured text or wide characters.
+- Text wrapping now measures coloured text, wide characters, and joined emoji by the columns they fill. It keeps joined emoji and accented letters whole, and wraps before a wide character would pass the limit.
+- `stripAnsi()` now removes terminal hyperlinks and other terminal control sequences as well as colours.
+- Tables now line up columns when values contain coloured or wide text.
+- Tables now cut overflowing cells by visible columns while keeping colours and terminal links.
+- Rows, row groups and labelled lines now line up when labels contain coloured or wide text.
+- Dividers and bar charts now line up when labels contain coloured or wide text.
 
 ## 0.17.0 - 2026-10-03
 

package/adapters/python/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "lewishowles-cli-style"
-version = "0.17.0"
+version = "0.17.1"
 description = "Python adapter for the shared cli-style binary."
 authors = [{ name = "Lewis Howles" }]
 license = { text = "MIT" }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@lewishowles/cli-style",
-	"version": "0.17.0",
+	"version": "0.17.1",
 	"description": "Shared terminal output styles for Lewis Howles tools, diagnostics, and package CLIs.",
 	"license": "MIT",
 	"repository": {
@@ -38,6 +38,9 @@
 		"smoke:binary": "./dist/bin/cli-style render status --plain < tests/fixtures/render/status-success.json",
 		"test:unit": "bun test"
 	},
+	"dependencies": {
+		"get-east-asian-width": "^1.7.0"
+	},
 	"devDependencies": {
 		"@stylistic/eslint-plugin": "^5.10.0",
 		"vite": "npm:@voidzero-dev/vite-plus-core@0.2.8",

package/src/formatters/ansi.js

@@ -1,11 +1,42 @@
+import { eastAsianWidth } from "get-east-asian-width";
+
 import { resolveColourValue } from "../theme/colours.js";
 
 // ANSI reset sequence used after coloured output.
 const reset = "\u001b[0m";
 
-// Matches simple SGR ANSI sequences used by this package.
+// The escape character that starts every ANSI sequence.
 const escapeCharacter = String.fromCharCode(27);
-const ansiPattern = new RegExp(`${escapeCharacter}\\[[\\d;]*m`, "gu");
+
+// The bell character that can end an OSC sequence, such as a terminal hyperlink.
+const bellCharacter = String.fromCharCode(7);
+
+// Matches ANSI CSI sequences, such as colours, and OSC sequences, such as hyperlinks, which take up no columns on screen.
+export const ansiPattern = new RegExp(
+	`${escapeCharacter}(?:\\[[0-?]*[ -/]*[@-~]|\\][^${bellCharacter}${escapeCharacter}]*(?:${bellCharacter}|${escapeCharacter}\\\\))`,
+	"gu",
+);
+
+// Matches the same sequences as a captured group, so splitting text on it keeps each sequence as its own piece.
+const ansiSplitPattern = new RegExp(`(${ansiPattern.source})`, "u");
+
+// Matches a terminal link sequence and captures its address, which is empty when the sequence ends a link.
+const hyperlinkPattern = new RegExp(
+	`^${escapeCharacter}\\]8;[^;]*;([^${bellCharacter}${escapeCharacter}]*)`,
+	"u",
+);
+
+// The sequences that clear every colour and text style at once.
+const clearStyleCodes = [reset, "\u001b[m"];
+
+// Splits text into the characters people see, so a joined emoji or an accented letter counts as one.
+const graphemeSegmenter = new Intl.Segmenter(undefined, { granularity: "grapheme" });
+
+// Matches emoji presentation characters or the selector that requests emoji presentation.
+const emojiPattern = /[\p{Emoji_Presentation}\uFE0F]/u;
+
+// Matches a cluster made only of combining marks or invisible characters, such as a lone joiner, which take no columns.
+const zeroWidthPattern = /^[\p{Mark}\p{Default_Ignorable_Code_Point}]+$/u;
 
 // ANSI style sequences supported before primitive renderers exist.
 const styleCodes = {
@@ -73,6 +104,36 @@ export function style(value, style, options = {}) {
 	return `${styleCode}${value}${reset}`;
 }
 
+/**
+ * Switch the given styles back on after every full reset inside text, so an outer style
+ * carries on past coloured text placed inside it. Coloured text ends with a full reset,
+ * written as `\u001b[0m` or the shorter `\u001b[m`, which would otherwise turn the outer
+ * style off as well.
+ *
+ * @param  {string}  value
+ *     Text that may hold coloured parts.
+ * @param  {string[]}  stylesToRestore
+ *     The styles to switch back on, each rendered on an empty string, such as
+ *     `style("", "bold", options)`. An empty entry adds nothing.
+ * @returns  {string}
+ *     The text with the styles switched back on after each full reset.
+ */
+export function restoreStyles(value, stylesToRestore) {
+	// The codes that turn the styles on, with each closing reset cut off.
+	const openingCodes = stylesToRestore
+		.map((styleToRestore) => styleToRestore.slice(0, -reset.length))
+		.join("");
+
+	// The text with the styles switched back on after each reset form handled so far.
+	let restoredValue = value;
+
+	for (const clearStyleCode of clearStyleCodes) {
+		restoredValue = restoredValue.replaceAll(clearStyleCode, `${clearStyleCode}${openingCodes}`);
+	}
+
+	return restoredValue;
+}
+
 /**
  * Remove ANSI escape sequences from text.
  *
@@ -85,6 +146,130 @@ export function stripAnsi(value) {
 	return value.replace(ansiPattern, "");
 }
 
+/**
+ * Count the terminal columns that text fills on screen. ANSI sequences take no
+ * columns, and East Asian wide characters and emoji take two.
+ *
+ * @param  {string}  value
+ *     The text to measure, which may contain ANSI sequences.
+ * @returns  {number}
+ *     The number of columns the text fills.
+ */
+export function visibleWidth(value) {
+	let width = 0;
+
+	for (const { segment } of graphemeSegmenter.segment(stripAnsi(value))) {
+		if (zeroWidthPattern.test(segment)) {
+			continue;
+		}
+
+		if (eastAsianWidth(segment.codePointAt(0)) === 2 || emojiPattern.test(segment)) {
+			width += 2;
+			continue;
+		}
+
+		width += 1;
+	}
+
+	return width;
+}
+
+/**
+ * Add trailing spaces until text fills a number of terminal columns. Colour
+ * codes take no space and wide characters take two, so coloured and wide text
+ * pads to the same width as plain text.
+ *
+ * @param  {string}  value
+ *     The text to pad, which may contain ANSI colour codes.
+ * @param  {number}  width
+ *     The number of columns the text should fill.
+ * @returns  {string}
+ *     The padded text, or the text unchanged when it already fills the width.
+ */
+export function padVisible(value, width) {
+	return value + " ".repeat(Math.max(0, width - visibleWidth(value)));
+}
+
+/**
+ * Split text at a terminal column without breaking a colour code, a link or a
+ * character. A character that would cross the column, such as a two-column 界
+ * at the edge, starts the remaining text instead.
+ *
+ * When the cut falls inside coloured or linked text, the first piece ends by
+ * closing the colour and the link, and the remaining text starts by reopening
+ * them, so each piece can be printed on a line of its own.
+ *
+ * @param  {string}  value
+ *     The text to split, which may contain ANSI colour codes and terminal links.
+ * @param  {number}  width
+ *     The most columns the first piece may fill.
+ * @returns  {{ head: string, tail: string }}
+ *     The first piece and the remaining text, which is empty when the whole
+ *     value fits.
+ */
+export function sliceVisible(value, width) {
+	// Splitting on a captured pattern puts plain text at even indexes and ANSI sequences at odd ones.
+	const parts = value.split(ansiSplitPattern);
+
+	// The link open at the current position, with the sequences that close and reopen it.
+	let activeLink = null;
+	// The colour and style codes in effect at the current position, in the order they were set.
+	let activeStyles = [];
+	// The columns filled so far.
+	let columns = 0;
+	// The position in the original value reached so far.
+	let cursor = 0;
+
+	for (const [index, part] of parts.entries()) {
+		if (index % 2 === 0) {
+			for (const { segment } of graphemeSegmenter.segment(part)) {
+				const segmentWidth = visibleWidth(segment);
+
+				if (columns + segmentWidth > width) {
+					const head =
+						value.slice(0, cursor) +
+						(activeLink?.closer ?? "") +
+						(activeStyles.length > 0 ? reset : "");
+
+					const tail = activeStyles.join("") + (activeLink?.opener ?? "") + value.slice(cursor);
+
+					return { head, tail };
+				}
+
+				columns += segmentWidth;
+				cursor += segment.length;
+			}
+
+			continue;
+		}
+
+		if (clearStyleCodes.includes(part)) {
+			activeStyles = [];
+		} else if (part.startsWith(`${escapeCharacter}[`) && part.endsWith("m")) {
+			activeStyles.push(part);
+		}
+
+		const hyperlink = part.match(hyperlinkPattern);
+
+		if (hyperlink !== null) {
+			// The closing sequence ends the same way as the opening one, with a bell or an escape and backslash.
+			const terminator = part.endsWith(bellCharacter) ? bellCharacter : `${escapeCharacter}\\`;
+
+			activeLink =
+				hyperlink[1] === ""
+					? null
+					: {
+							closer: `${escapeCharacter}]8;;${terminator}`,
+							opener: part,
+						};
+		}
+
+		cursor += part.length;
+	}
+
+	return { head: value, tail: "" };
+}
+
 /**
  * Wrap text in ANSI colour codes.
  *

package/src/formatters/wrap.js

@@ -1,13 +1,14 @@
+import { ansiPattern, visibleWidth } from "./ansi.js";
+
 // 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",
-);
+// Splits text into the characters people see, so wrapping never breaks a joined emoji apart.
+const graphemeSegmenter = new Intl.Segmenter(undefined, { granularity: "grapheme" });
+
+// Line breaks end the current wrapped line and take no columns. Windows CR+LF arrives from the
+// segmenter as one character.
+const lineBreaks = new Set(["\n", "\r\n"]);
 
 /**
  * Wrap text to a maximum visible width, treating ANSI escape sequences as zero-width.
@@ -27,7 +28,7 @@ export function wrapText(text, width = defaultWrapWidth) {
 	let line = [];
 
 	for (const token of tokens) {
-		if (token.value === "\n") {
+		if (lineBreaks.has(token.value)) {
 			lines.push(renderTokens(line));
 			line = [];
 			continue;
@@ -35,7 +36,7 @@ export function wrapText(text, width = defaultWrapWidth) {
 
 		line.push(token);
 
-		while (visibleWidth(line) > wrapWidth) {
+		while (tokensWidth(line) > wrapWidth) {
 			const whitespaceIndex = findLastWhitespace(line);
 
 			if (whitespaceIndex > 0) {
@@ -77,7 +78,7 @@ function resolveWrapWidth(width) {
 }
 
 /**
- * Split text into visible characters and ANSI escape sequences.
+ * Split text into the characters people see and ANSI escape sequences.
  *
  * @param  {string}  text
  *     Text to tokenise.
@@ -89,7 +90,7 @@ function tokenise(text) {
 
 	let textStart = 0;
 
-	for (const match of text.matchAll(ansiEscapePattern)) {
+	for (const match of text.matchAll(ansiPattern)) {
 		appendTextTokens(tokens, text.slice(textStart, match.index));
 		tokens.push({
 			value: match[0],
@@ -104,7 +105,9 @@ function tokenise(text) {
 }
 
 /**
- * Append one token per character of plain text to a token list.
+ * Append one token per visible character of plain text to a token list, keeping
+ * joined emoji and accented letters whole. Line breaks, including Windows CR+LF,
+ * take no columns.
  *
  * @param  {object[]}  tokens
  *     Token list to append to.
@@ -113,10 +116,10 @@ function tokenise(text) {
  * @returns  {void}
  */
 function appendTextTokens(tokens, text) {
-	for (const value of text) {
+	for (const { segment: value } of graphemeSegmenter.segment(text)) {
 		tokens.push({
 			value,
-			visibleWidth: value === "\n" ? 0 : 1,
+			visibleWidth: lineBreaks.has(value) ? 0 : visibleWidth(value),
 		});
 	}
 }
@@ -129,7 +132,7 @@ function appendTextTokens(tokens, text) {
  * @returns  {number}
  *     Total visible width.
  */
-function visibleWidth(tokens) {
+function tokensWidth(tokens) {
 	return tokens.reduce((width, token) => width + token.visibleWidth, 0);
 }
 
@@ -155,6 +158,7 @@ function findLastWhitespace(tokens) {
 
 /**
  * Find the index to split at when a line has no whitespace to break on.
+ * A single character wider than the limit stays whole on its own line.
  *
  * @param  {object[]}  tokens
  *     Tokens to search.
@@ -167,11 +171,13 @@ function findHardSplitIndex(tokens, width) {
 	let currentWidth = 0;
 
 	for (let index = 0; index < tokens.length; index += 1) {
-		currentWidth += tokens[index].visibleWidth;
+		const nextWidth = currentWidth + tokens[index].visibleWidth;
 
-		if (currentWidth >= width) {
-			return index + 1;
+		if (nextWidth > width && currentWidth > 0) {
+			return index;
 		}
+
+		currentWidth = nextWidth;
 	}
 
 	return tokens.length;

package/src/gallery/render-gallery.js

@@ -8,7 +8,7 @@ import { diffBlock } from "../patterns/diff-block.js";
 import { nextStepBlock } from "../patterns/next-step-block.js";
 import { quoteBlock } from "../patterns/quote-block.js";
 import { taskSummary } from "../patterns/task-summary.js";
-import { stripAnsi } from "../formatters/ansi.js";
+import { foreground, sliceVisible, visibleWidth } from "../formatters/ansi.js";
 import { renderSpinnerFrame } from "../interactive/spinner.js";
 import { barChart } from "../primitives/bar-chart.js";
 import { bulletList } from "../primitives/bullet-list.js";
@@ -303,27 +303,26 @@ function clampGalleryOutput(output, width) {
 }
 
 /**
- * Truncate one line to a visible width.
+ * Cut one gallery line to the gallery width, measured in screen columns.
  *
  * @param  {string}  line
- *     Output line.
+ *     The output line, which may contain colour codes and wide characters.
  * @param  {number}  width
- *     Requested visible width.
+ *     The most columns the line may fill.
  * @returns  {string}
- *     Truncated line.
+ *     The line unchanged when it fits, or cut with a trailing `~` that marks
+ *     the cut. Colour codes and links stay whole and are closed before the `~`.
  */
 function clampLine(line, width) {
-	const plainLine = stripAnsi(line);
-
-	if (plainLine.length <= width) {
+	if (visibleWidth(line) <= width) {
 		return line;
 	}
 
 	if (width <= 1) {
-		return plainLine.slice(0, width);
+		return sliceVisible(line, width).head;
 	}
 
-	return `${plainLine.slice(0, width - 1)}~`;
+	return `${sliceVisible(line, width - 1).head}~`;
 }
 
 /**
@@ -760,9 +759,21 @@ function renderPrimitives(options) {
 		"",
 		"Chips",
 		renderChipExamples(options),
+		chip(`${foreground("coloured", "danger", options)} label`, "success", options),
 		"",
 		"Statuses",
 		...renderStatusExamples(options),
+		status(resultTypes.SUCCESS, "caller-coloured label", {
+			...options,
+			label: `${foreground("Coloured", "danger", options)} status`,
+		}),
+		"",
+		"Dividers",
+		divider({
+			...options,
+			dividerWidth: 32,
+			label: foreground("界面", "info", options),
+		}),
 		"",
 		"Panels",
 		...renderPanelExamples(options),
@@ -804,6 +815,15 @@ function renderPrimitives(options) {
 			icon: "!",
 			tone: "warning",
 		}),
+		labelledLine(
+			foreground("界面", "info", options),
+			"Coloured wide labels keep wrapped text aligned.",
+			{
+				...options,
+				icon: foreground("界", "warning", options),
+				width: 32,
+			},
+		),
 		emptyState("No results", "tone: muted", options),
 		errorBlock("Failed", ["tone: danger"], {
 			...options,
@@ -836,6 +856,16 @@ function renderPrimitives(options) {
 			...options,
 			labelWidth: 8,
 		}),
+		row(
+			foreground("界面", "info", options),
+			"Coloured wide labels and separators align wrapped text.",
+			{
+				...options,
+				labelWidth: 8,
+				separator: foreground(" => ", "warning", options),
+				width: 36,
+			},
+		),
 		row("Bundle", "is 22.3 KB, above the 12.0 KB budget", {
 			...options,
 			labelWidth: 8,
@@ -879,6 +909,10 @@ function renderPrimitives(options) {
 					label: "Checks",
 					value: "type-check, unit, build",
 				},
+				{
+					label: foreground("界面", "info", options),
+					value: "Coloured wide labels share the value column",
+				},
 				{
 					label: "Bundle",
 					result: resultTypes.FAILED,
@@ -904,6 +938,10 @@ function renderPrimitives(options) {
 function renderBulletListExamples(options) {
 	return [
 		bulletList(["Install dependencies", "Run the unit tests", "Review the output"], options),
+		bulletList([foreground("界面 item wraps beside its bullet", "info", options)], {
+			...options,
+			width: 18,
+		}),
 		bulletList(["This item wraps so continuation lines stay aligned with the item text."], {
 			...options,
 			width: 40,
@@ -959,6 +997,10 @@ function renderTableExample(options) {
 				check: "unit",
 				result: "warning",
 			},
+			{
+				check: "界面",
+				result: foreground("passed", "success", options),
+			},
 		],
 	});
 }
@@ -990,7 +1032,7 @@ function renderOverflowTableExample(options, overflow) {
 		],
 		rows: [
 			{
-				detail: "packages/cli-style/src/primitives/table.js",
+				detail: foreground("界面/packages/cli-style/src/primitives/table.js", "success", options),
 				source: "Table",
 			},
 		],
@@ -1009,6 +1051,10 @@ function renderBarChartExample(options) {
 	return barChart({
 		...options,
 		rows: [
+			{
+				label: foreground("界面", "info", options),
+				value: 8,
+			},
 			{
 				label: "positive",
 				value: 10,
@@ -1115,7 +1161,7 @@ function renderProgressExamples(options) {
 }
 
 /**
- * Render all panel tone examples.
+ * Render one panel for each tone, then a panel holding coloured output.
  *
  * @param  {object}  options
  *     Rendering options.
@@ -1123,7 +1169,8 @@ function renderProgressExamples(options) {
  *     Panel examples.
  */
 function renderPanelExamples(options) {
-	return panelToneExamples.map((tone) =>
+	// One panel for each tone.
+	const toneExamples = panelToneExamples.map((tone) =>
 		panel({
 			...options,
 			lines: [`tone: ${tone}`],
@@ -1131,6 +1178,25 @@ function renderPanelExamples(options) {
 			tone,
 		}),
 	);
+
+	// A panel holding a coloured status line and coloured values, to show the panel
+	// background carrying on after them.
+	const nestedStylesExample = panel({
+		...options,
+		lines: [
+			status(resultTypes.SUCCESS, "Checks passed", options),
+			rowGroup({
+				...options,
+				rows: [
+					{ label: "Source", value: "main", valueColour: "success" },
+					{ label: "Checks", value: "unit", valueColour: "success" },
+				],
+			}),
+		],
+		title: "Nested styles",
+	});
+
+	return [...toneExamples, nestedStylesExample];
 }
 
 /**

package/src/primitives/bar-chart.js

@@ -1,4 +1,4 @@
-import { foreground } from "../formatters/ansi.js";
+import { foreground, padVisible, visibleWidth } from "../formatters/ansi.js";
 import { chartColours } from "../theme/colours.js";
 
 // Chart bars use the same compact default width as progress bars.
@@ -27,7 +27,7 @@ export function barChart(options = {}) {
 		return "";
 	}
 
-	const labelWidth = Math.max(...rows.map((row) => row.label.length));
+	const labelWidth = Math.max(...rows.map((row) => visibleWidth(row.label)));
 	const maximum = Math.max(...rows.map((row) => Math.abs(row.value)), 1);
 	const width = normaliseWidth(options.barWidth);
 
@@ -93,7 +93,7 @@ function renderRow(row, labelWidth, maximum, width, options) {
 	const barWidth = Math.round((Math.abs(row.value) / maximum) * width);
 	const symbol = options.unicode === false ? "#" : "█";
 	const bar = symbol.repeat(barWidth).padEnd(width, " ");
-	const label = row.label.padEnd(labelWidth, " ");
+	const label = padVisible(row.label, labelWidth);
 
 	if (options.colour !== true) {
 		return `${label}  ${bar} ${row.value}`;

package/src/primitives/chip.js

@@ -1,4 +1,4 @@
-import { background, foreground, style } from "../formatters/ansi.js";
+import { background, foreground, restoreStyles, style } from "../formatters/ansi.js";
 import { chipColours } from "../theme/colours.js";
 
 // Chip style used when the requested tone is not configured.
@@ -25,7 +25,15 @@ export function chip(label, tone = fallbackTone, options = {}) {
 		return `[${label}]`;
 	}
 
-	const paddedLabel = ` ${label} `;
+	// The label with the chip's fill, bold and tone switched back on after any coloured text,
+	// so the rest of the chip keeps its look.
+	const restoredLabel = restoreStyles(label, [
+		background("", token.background, options),
+		style("", "bold", options),
+		foreground("", token.foreground, options),
+	]);
+
+	const paddedLabel = ` ${restoredLabel} `;
 	const colouredLabel = foreground(paddedLabel, token.foreground, options);
 	const boldLabel = style(colouredLabel, "bold", options);
 

package/src/primitives/divider.js

@@ -1,4 +1,4 @@
-import { foreground } from "../formatters/ansi.js";
+import { foreground, visibleWidth } from "../formatters/ansi.js";
 
 // Dividers use enough width to read as a section break in compact output.
 const defaultWidth = 40;
@@ -33,7 +33,7 @@ export function divider(options = {}) {
 	const character = options.character ?? defaultCharacter;
 	const label = options.label ?? "";
 	const width = options.dividerWidth ?? defaultWidth;
-	const lineWidth = Math.max(width - label.length - labelGap(label), 0);
+	const lineWidth = Math.max(width - visibleWidth(label) - labelGap(label), 0);
 	const line = character.repeat(lineWidth);
 	const output = label === "" ? line : `${label} ${line}`;
 

package/src/primitives/feedback.js

@@ -1,4 +1,4 @@
-import { foreground, style } from "../formatters/ansi.js";
+import { foreground, restoreStyles, style } from "../formatters/ansi.js";
 import { getResultSymbol, resultTypes } from "../theme/results.js";
 import { labelledLine } from "./labelled-line.js";
 import { panel } from "./panel.js";
@@ -48,7 +48,13 @@ export function emptyState(title = "No results", detail = "", options = {}) {
 		return `${prefix}${detailText}`;
 	}
 
-	const renderedPrefix = style(foreground(prefix, "muted", options), "bold", options);
+	// The prefix with its bold and muted tone switched back on after a coloured title.
+	const restoredPrefix = restoreStyles(prefix, [
+		style("", "bold", options),
+		foreground("", "muted", options),
+	]);
+
+	const renderedPrefix = style(foreground(restoredPrefix, "muted", options), "bold", options);
 
 	return `${renderedPrefix}${detailText}`;
 }

package/src/primitives/labelled-line.js

@@ -1,4 +1,4 @@
-import { foreground, style } from "../formatters/ansi.js";
+import { foreground, restoreStyles, style, visibleWidth } from "../formatters/ansi.js";
 import { wrapText } from "../formatters/wrap.js";
 
 // Falls back to the informational tone when no colour token is given.
@@ -44,20 +44,19 @@ export function labelledLine(label = "", message = "", options = {}) {
 		return `${prefix}${messageSeparator}${messageText}`;
 	}
 
-	const wrapWidth = resolveWrapWidth(prefixText, options);
+	const wrapWidth = resolveWrapWidth(prefix, options);
 	const messageLines = wrapText(messageText, wrapWidth);
-	const continuationIndent = " ".repeat(prefixText.length + messageSeparator.length);
+	const continuationIndent = " ".repeat(visibleWidth(prefix) + visibleWidth(messageSeparator));
 	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.
+ * Colour the icon and label prefix in the line's tone when colour is on.
  *
  * @param  {string}  prefix
- *     Plain-text icon and label prefix.
+ *     Icon and label prefix. The icon or label may already hold colour.
  * @param  {object}  options
  *     Rendering options.
  * @returns  {string}
@@ -72,13 +71,24 @@ function renderPrefix(prefix, options) {
 		return prefix;
 	}
 
-	const colouredPrefix = foreground(prefix, resolveColour(options), options);
+	// The caller's tone, or "info" when none is given.
+	const tone = resolveColour(options);
+
+	// The prefix with bold and the line's colour switched back on after a coloured icon or
+	// label, so the rest of the prefix keeps them.
+	const restoredPrefix = restoreStyles(prefix, [
+		style("", "bold", options),
+		foreground("", tone, options),
+	]);
+
+	// The whole prefix in the line's colour, ready to be made bold.
+	const colouredPrefix = foreground(restoredPrefix, tone, options);
 
 	return style(colouredPrefix, "bold", options);
 }
 
 /**
- * Build the plain-text icon and label prefix.
+ * Build the icon and label prefix. The icon or label may already hold colour.
  *
  * @param  {string}  label
  *     Label text.
@@ -115,7 +125,7 @@ function resolveColour(options) {
  * 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.
+ *     The icon and label prefix as it will be printed, including any colour.
  * @param  {object}  options
  *     Rendering options.
  * @returns  {number|undefined}
@@ -127,7 +137,7 @@ function resolveWrapWidth(prefix, options) {
 	}
 
 	if (Number.isFinite(options.width)) {
-		return Math.max(1, options.width - prefix.length - messageSeparator.length);
+		return Math.max(1, options.width - visibleWidth(prefix) - visibleWidth(messageSeparator));
 	}
 
 	return undefined;

package/src/primitives/panel.js

@@ -1,4 +1,4 @@
-import { background, foreground, style } from "../formatters/ansi.js";
+import { background, foreground, restoreStyles, style, visibleWidth } from "../formatters/ansi.js";
 import { wrapText } from "../formatters/wrap.js";
 import { profiles } from "../profiles/profiles.js";
 import { panelColours } from "../theme/colours.js";
@@ -64,23 +64,38 @@ export function panel(options = {}) {
  * @param  {object}  options
  *     Rendering options.
  * @returns  {string[]}
- *     The panel lines, each exactly `width` columns wide.
+ *     The panel lines, each exactly `width` columns wide, unless a wide character
+ *     does not fit in a panel at its minimum width.
  */
 function renderLine(line, width, isTitle, options) {
 	const accent = options.unicode === false ? "|" : "▌";
 	const contentWidth = width - 5;
+	// Whether this line is drawn with ANSI colour.
+	const useColour = options.colour === true;
 
 	return wrapText(line, contentWidth).map((visibleLine) => {
-		const content = `  ${visibleLine.padEnd(contentWidth, " ")}  `;
+		// Spaces that fill the line to the content width on screen. A wide character can
+		// overflow a very narrow panel, so the count never drops below zero.
+		const padding = " ".repeat(Math.max(0, contentWidth - visibleWidth(visibleLine)));
+		// The line with its inner margins, ready for the panel colours.
+		const content = `  ${visibleLine}${padding}  `;
 
-		if (options.colour !== true) {
+		if (!useColour) {
 			return `${accent}${content}`;
 		}
 
 		const renderedAccent = renderPanelColour(accent, options);
 
+		// The content with the panel colours switched back on after each reset inside it, so
+		// the panel background carries on to the right edge.
+		const restoredContent = restoreStyles(content, [
+			background("", panelColours.background, options),
+			foreground("", panelColours.body, options),
+			isTitle ? style("", "bold", options) : "",
+		]);
+
 		const renderedContent = foreground(
-			background(content, panelColours.background, options),
+			background(restoredContent, panelColours.background, options),
 			panelColours.body,
 			options,
 		);

package/src/primitives/row-group.js

@@ -1,3 +1,4 @@
+import { visibleWidth } from "../formatters/ansi.js";
 import { getResultSymbol } from "../theme/results.js";
 import { row } from "./row.js";
 
@@ -21,7 +22,7 @@ export function rowGroup(options = {}) {
 	}
 
 	const labelWidth = Math.max(
-		...rows.map((entry) => displayedLabelLength(entry, options)),
+		...rows.map((entry) => displayedLabelWidth(entry, options)),
 		options.labelWidth ?? 0,
 	);
 
@@ -59,18 +60,19 @@ function normaliseRows(rows) {
 }
 
 /**
- * Return the visible width of a row label.
+ * Count the columns a row's label fills, including its result symbol when it
+ * has one.
  *
  * @param  {object}  entry
  *     Row entry.
  * @param  {object}  options
  *     Group rendering options.
  * @returns  {number}
- *     Displayed label length.
+ *     The number of terminal columns the label takes up.
  */
-function displayedLabelLength(entry, options) {
+function displayedLabelWidth(entry, options) {
 	if (typeof entry.result !== "string" || entry.result === "") {
-		return entry.label.length;
+		return visibleWidth(entry.label);
 	}
 
 	const entryOptions = {
@@ -80,5 +82,5 @@ function displayedLabelLength(entry, options) {
 
 	const symbol = getResultSymbol(entry.result, entryOptions);
 
-	return [symbol, entry.label].join(" ").length;
+	return visibleWidth([symbol, entry.label].join(" "));
 }

package/src/primitives/row.js

@@ -1,4 +1,4 @@
-import { foreground } from "../formatters/ansi.js";
+import { foreground, padVisible, visibleWidth } from "../formatters/ansi.js";
 import { wrapText } from "../formatters/wrap.js";
 import { getResultSymbol, getResultToken } from "../theme/results.js";
 
@@ -49,8 +49,8 @@ const minimumWrapWidth = 10;
 export function row(label, value = "", options = {}) {
 	const resultToken = resolveResultToken(options);
 	const displayLabel = renderDisplayLabel(label, resultToken, options);
-	const labelWidth = Math.max(displayLabel.length, options.labelWidth ?? 0);
-	const labelText = displayLabel.padEnd(labelWidth, " ");
+	const labelWidth = Math.max(visibleWidth(displayLabel), options.labelWidth ?? 0);
+	const labelText = padVisible(displayLabel, labelWidth);
 	const renderedLabel = renderLabel(labelText, options);
 
 	if (value === "") {
@@ -66,7 +66,7 @@ export function row(label, value = "", options = {}) {
 	}
 
 	const availableWrapWidth = Number.isFinite(options.width)
-		? options.width - labelWidth - separator.length
+		? options.width - labelWidth - visibleWidth(separator)
 		: defaultWrapWidth;
 
 	const hasExplicitWrapWidth = options.wrapWidth !== undefined && options.wrapWidth !== null;
@@ -78,7 +78,7 @@ export function row(label, value = "", options = {}) {
 	const wrapWidth = options.wrapWidth ?? availableWrapWidth;
 
 	const valueLines = wrapText(value, wrapWidth);
-	const continuationIndent = " ".repeat(labelWidth + separator.length);
+	const continuationIndent = " ".repeat(labelWidth + visibleWidth(separator));
 	const renderedValueLines = valueLines.map((line) => renderValue(line, options));
 	const wrappedValue = renderedValueLines.join(`\n${continuationIndent}`);
 

package/src/primitives/span.js

@@ -1,4 +1,4 @@
-import { foreground, style } from "../formatters/ansi.js";
+import { foreground, restoreStyles, style } from "../formatters/ansi.js";
 
 // Inline spans use the same informational tone as hints by default.
 const defaultTone = "info";
@@ -27,7 +27,16 @@ export function span(value = "", tone = defaultTone, options = {}) {
 		return value;
 	}
 
-	const renderedValue = foreground(value, tone, options);
+	// The text weight, bold unless the options ask for another.
+	const weight = options.weight ?? defaultWeight;
 
-	return style(renderedValue, options.weight ?? defaultWeight, options);
+	// The text with the span's weight and tone switched back on after any coloured text.
+	const restoredValue = restoreStyles(value, [
+		style("", weight, options),
+		foreground("", tone, options),
+	]);
+
+	const renderedValue = foreground(restoredValue, tone, options);
+
+	return style(renderedValue, weight, options);
 }

package/src/primitives/status.js

@@ -1,4 +1,4 @@
-import { foreground, style } from "../formatters/ansi.js";
+import { foreground, restoreStyles, style } from "../formatters/ansi.js";
 import { getResultSymbol, getResultToken, resultTypes } from "../theme/results.js";
 
 /**
@@ -33,7 +33,13 @@ export function status(resultType = resultTypes.UNKNOWN, detail = "", options =
 		return `${prefix}${detailText}`;
 	}
 
-	const colouredPrefix = foreground(prefix, token.tone, options);
+	// The prefix with its bold and tone switched back on after a coloured label.
+	const restoredPrefix = restoreStyles(prefix, [
+		style("", "bold", options),
+		foreground("", token.tone, options),
+	]);
+
+	const colouredPrefix = foreground(restoredPrefix, token.tone, options);
 	const boldPrefix = style(colouredPrefix, "bold", options);
 
 	return `${boldPrefix}${detailText}`;

package/src/primitives/table.js

@@ -1,4 +1,4 @@
-import { foreground } from "../formatters/ansi.js";
+import { foreground, padVisible, sliceVisible, visibleWidth } from "../formatters/ansi.js";
 import { defaultWidth, minimumWidth, normaliseWidth } from "../formatters/width.js";
 import { tableColours } from "../theme/colours.js";
 
@@ -112,8 +112,8 @@ function normaliseRows(rows) {
 function columnWidths(columns, rows) {
 	return columns.map((column) => {
 		const naturalWidth = Math.max(
-			column.label.length,
-			...rows.map((row) => cellValue(row[column.key]).length),
+			visibleWidth(column.label),
+			...rows.map((row) => visibleWidth(cellValue(row[column.key]))),
 		);
 
 		const maxWidth = columnMaxWidth(column);
@@ -151,24 +151,38 @@ function columnMaxWidth(column) {
  * @param  {number}  width
  *     Column width.
  * @returns  {string[]}
- *     Lines the cell renders as; truncated to one line with a trailing
- *     ellipsis unless the column's overflow is 'wrap'.
+ *     Lines the cell renders as, each no wider on screen than the column
+ *     unless one character is wider than the whole column. A value that does
+ *     not fit is cut to one line with a trailing ellipsis, or split across
+ *     lines when the column's overflow is 'wrap'. Coloured text keeps its
+ *     colour on every line.
  */
 function columnLines(value, column, width) {
-	if (value.length <= width) {
+	if (visibleWidth(value) <= width) {
 		return [value];
 	}
 
 	if (column.overflow === "wrap") {
-		return Array.from(
-			{
-				length: Math.ceil(value.length / width),
-			},
-			(_, index) => value.slice(index * width, (index + 1) * width),
-		);
+		const lines = [];
+
+		let remaining = value;
+
+		while (remaining !== "") {
+			let { head, tail } = sliceVisible(remaining, width);
+
+			if (visibleWidth(head) === 0 && tail !== "") {
+				// In a one-column cell, a two-column character gets a line of its own so wrapping always moves forward.
+				({ head, tail } = sliceVisible(remaining, 2));
+			}
+
+			lines.push(head);
+			remaining = tail;
+		}
+
+		return lines;
 	}
 
-	return [`${value.slice(0, width - 1)}…`];
+	return [`${sliceVisible(value, width - 1).head}…`];
 }
 
 /**
@@ -242,7 +256,7 @@ function renderTable(columns, rows, widths, options) {
  *     Padded column text.
  */
 function padColumn(value, width, index, columnCount) {
-	return index === columnCount - 1 ? value : value.padEnd(width, " ");
+	return index === columnCount - 1 ? value : padVisible(value, width);
 }
 
 /**
@@ -258,13 +272,13 @@ function padColumn(value, width, index, columnCount) {
  *     Rendered key/value blocks.
  */
 function renderBlocks(columns, rows, options) {
-	const labelWidth = Math.max(...columns.map((column) => column.label.length));
+	const labelWidth = Math.max(...columns.map((column) => visibleWidth(column.label)));
 
 	return rows
 		.map((row) =>
 			columns
 				.map((column) => {
-					const label = renderHeader(column.label.padEnd(labelWidth, " "), options);
+					const label = renderHeader(padVisible(column.label, labelWidth), options);
 					const value = renderCell(cellValue(row[column.key]), 0, options);
 
 					return `${label}${columnSeparator}${value}`;