@lewishowles/cli-style 0.15.0 → 0.17.0

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 ## Unreleased
 
+## 0.17.0 - 2026-10-03
+
+### Added
+
+- Added `quoteBlock()` (`quote-block` for `cli-style render`, `quote_block()` in Python, and `CliStyle.quoteBlock` in Swift) to show another program's output with a visible marker and optional heading.
+- Python `row()` and `row_group()`, and Swift `CliStyle.row` and `CliStyle.rowGroup`, can now wrap long values with the `wrap` and `wrap_width` options (`wrapWidth` in Swift). The row group functions also accept colour and separator defaults, which each row can override.
+
+## 0.16.0 - 2026-09-21
+
+### Breaking changes
+
+- BREAKING: Removed the `panelWidth` option from `panel()` and the `panel` renderer. Use `width` instead.
+- BREAKING: Panels now honour the requested total `width`, raise widths below 6 to the minimum usable width, and wrap long lines to fit.
+
+### Fixed
+
+- An explicit JSON `width` now takes precedence over the terminal width for width-aware renderers, so piped output stays within the caller's requested bounds.
+
 ## 0.15.0 - 2026-09-20
 
 ### Added

package/README.md

@@ -63,6 +63,8 @@ The package contains `bin/cli-style` and `adapters/`.
 
 All renderers return text. JavaScript imports functions directly. CLI, Bash, Python, and Swift integrations pass JSON-compatible data to a named renderer.
 
+Callers add any blank lines around rendered blocks. Renderers return strings without a trailing newline, and the CLI ends its output with one newline.
+
 ### JavaScript
 
 Create the `ui` instance at the CLI entrypoint, then pass `ui.options` to renderers. That keeps flag, environment, stream, colour, Unicode, and width detection in one place.
@@ -86,6 +88,10 @@ ui.print(output);
 
 Renderer methods return strings. `ui.print()`, `ui.write()`, and CLI commands handle stdout and stderr.
 
+For `render` commands, width follows this priority: JSON payload `width`, `--width`,
+`stdout.columns`, positive `COLUMNS`, then `80`, so piped output stays within the caller's requested
+size when the payload supplies a width.
+
 ### CLI render
 
 Use `cli-style render <renderer>` when a script needs rendered text from JSON input:
@@ -276,6 +282,7 @@ Renderer names are stable for `cli-style render`, `cli_style_render`, and Python
 | `empty-state`         | `emptyState(title, detail, options)`  | Use `cli_style_render`               | Use `render("empty-state", ...)`   | Use `CliStyle.render`                  | Empty result message.                                           |
 | `error-block`         | `errorBlock(title, lines, options)`   | Use `cli_style_render`               | Use `render("error-block", ...)`   | Use `CliStyle.render`                  | Structured error block.                                         |
 | `diff-block`          | `diffBlock(diff, options)`            | Use `cli_style_render`               | Use `render("diff-block", ...)`    | Use `CliStyle.render`                  | Structured added, removed, context, and header lines.           |
+| `quote-block`         | `quoteBlock(quote, options)`          | Use `cli_style_render`               | `quote_block(lines, title, width)` | `CliStyle.quoteBlock(...)`             | Output lines with a left marker and optional heading.           |
 
 Use `render("<renderer>", data, ...)` (Python) or `CliStyle.render(_:data:options:)` (Swift) for aggregate patterns (`diagnostic-report`, `agent-transcript`, `compact-data-table`) or any renderer with multi-item fields.
 
@@ -313,6 +320,8 @@ Use these shapes with `cli-style render`, `cli_style_render`, or Python `render(
 - `result`: optional result type for a symbol and tone
 - `labelWidth`: optional minimum label width
 - `labelColour`, `valueColour`, `separator`: optional presentation overrides
+- `wrap`: set to `false` to keep the value on one line
+- `wrapWidth`: optional value width when wrapping is enabled
 
 ### `row-group`
 
@@ -333,7 +342,10 @@ Use these shapes with `cli-style render`, `cli_style_render`, or Python `render(
 
 - `rows`: labelled values to align and render
 - `labelWidth`: optional minimum width for every label
-- Per-row fields match `row`, including `label`, `value`, `result`, `labelColour`, `valueColour`, and `separator`
+- `labelColour`, `valueColour`, `separator`: optional defaults for every row
+- `wrap`: set to `false` to keep every value on one line
+- `wrapWidth`: optional value width when wrapping is enabled
+- Each row takes the same fields as `row`. Row options other than `labelWidth` override the group defaults
 
 ### `bullet-list`
 
@@ -383,19 +395,19 @@ Pre-render a `span` when only part of the hint needs emphasis.
 
 ### Structured primitives
 
-| Renderer        | Main fields                            |
-| --------------- | -------------------------------------- |
-| `divider`       | `label`, `dividerWidth`, `character`   |
-| `chip`          | `label`, `tone`                        |
-| `panel`         | `title`, `lines`, `tone`, `panelWidth` |
-| `table`         | `columns`, `rows`, `width`             |
-| `progress-bar`  | `value`, `max`, `barWidth`, `tone`     |
-| `bar-chart`     | `rows`, `barWidth`                     |
-| `sparkline`     | `values`, `label`, `tone`, `width`     |
-| `step`          | `label`, `state`                       |
-| `step-progress` | `steps`, `current`                     |
-| `empty-state`   | `title`, `detail`                      |
-| `error-block`   | `title`, `lines`                       |
+| Renderer        | Main fields                          |
+| --------------- | ------------------------------------ |
+| `divider`       | `label`, `dividerWidth`, `character` |
+| `chip`          | `label`, `tone`                      |
+| `panel`         | `title`, `lines`, `tone`, `width`    |
+| `table`         | `columns`, `rows`, `width`           |
+| `progress-bar`  | `value`, `max`, `barWidth`, `tone`   |
+| `bar-chart`     | `rows`, `barWidth`                   |
+| `sparkline`     | `values`, `label`, `tone`, `width`   |
+| `step`          | `label`, `state`                     |
+| `step-progress` | `steps`, `current`                   |
+| `empty-state`   | `title`, `detail`                    |
+| `error-block`   | `title`, `lines`                     |
 
 For visual examples, run `cli-style gallery --section primitives`.
 
@@ -443,6 +455,19 @@ Patterns are built-in composite renderers for common report shapes. They use the
 | `next-step-block`     | `nextStepBlock(nextStep, options)`          | Next-step guidance.                   | `title`, `next`, `reason`, `commands`, `alternatives`                                |
 | `compact-data-table`  | `compactDataTable(data, options)`           | Titled compact data table.            | `title`, `summary`, `columns`, `rows`                                                |
 | `diff-block`          | `diffBlock(diff, options)`                  | Structured diff presentation.         | `title`, `path`, `lines`                                                             |
+| `quote-block`         | `quoteBlock(quote, options)`                | Quoted output with a visible marker.  | `lines`, `title`, `width`                                                            |
+
+### `quote-block`
+
+Pass output lines with an optional title and total width. Long lines wrap with a marker beside every continuation line, and empty lines are kept. The marker is `│`, or `|` when Unicode is off, and it is muted when colour is enabled. Plain and CI output always use an uncoloured `|`. ANSI colour codes in the title and lines are removed. The `json` profile returns the input unchanged.
+
+```js
+quoteBlock({
+	lines: ["The command returned this explanation.", "A second output line."],
+	title: "Command output",
+	width: 48,
+});
+```
 
 ### `diff-block`
 

package/adapters/python/README.md

@@ -22,6 +22,20 @@ print(render("status", {"type": "success", "label": "Build passed"}))
 
 If the `cli-style` binary is not available, `render()` returns sorted plain `key: value` text by default. Pass `raise_on_missing=True` to raise `CliStyleNotFoundError` instead.
 
+Use `row()` for one labelled value or `row_group()` to align several values. Both accept `wrap=False` to keep values on one line and `wrap_width` to set the width used when wrapping. `row_group()` also accepts `label_colour`, `value_colour`, and `separator` as defaults for its rows:
+
+```python
+from cli_style import row_group
+
+print(row_group(
+    [{"label": "Command", "value": "python -m pip install lewishowles-cli-style"}],
+    wrap=False,
+    label_colour="muted",
+))
+```
+
+Each row has `label`, `value`, and an optional `result`. It can override the group defaults with `label_colour`, `value_colour`, `separator`, `wrap`, or `wrap_width`. The JavaScript spellings, such as `labelColour` and `wrapWidth`, also work in row dictionaries. Callers add any blank lines around rendered blocks. Python `render()` removes trailing newlines from rendered strings.
+
 ## More information
 
 - [Repository](https://github.com/lewishowles/cli-style)

package/adapters/python/cli_style/__init__.py

@@ -19,6 +19,7 @@ from ._wrappers import (
 	next_step_block,
 	panel,
 	progress_bar,
+	quote_block,
 	row,
 	row_group,
 	sparkline,
@@ -59,6 +60,7 @@ __all__ = [
 	"next_step_block",
 	"panel",
 	"progress_bar",
+	"quote_block",
 	"render",
 	"resolve_binary",
 	"row",

package/adapters/python/cli_style/_wrappers.py

@@ -6,6 +6,22 @@ from typing import Any
 
 from .core import render
 
+
+def _camel_case_row(row: Any) -> Any:
+	"""Return a copy of a row with Python option names, such as label_colour, renamed to the camelCase names the renderer reads. Keys already in camelCase are kept, and a value that is not a dictionary is returned unchanged for the renderer to filter."""
+	if not isinstance(row, dict):
+		return row
+
+	converted_row = {}
+
+	for key, value in row.items():
+		parts = key.split("_")
+		camel_case_key = parts[0] + "".join(part.capitalize() for part in parts[1:])
+		converted_row[camel_case_key] = value
+
+	return converted_row
+
+
 def agent_transcript(
 	entries: list[dict[str, Any]] | None = None,
 	title: str | None = None,
@@ -297,7 +313,7 @@ def panel(
 	lines: list[str] | None = None,
 	title: str | None = None,
 	tone: str = "info",
-	panel_width: int | float | None = None,
+	width: int | float | None = None,
 	**kwargs: Any,
 ) -> str:
 	"""Return panel output; extra keyword arguments go to render()."""
@@ -308,8 +324,8 @@ def panel(
 
 	if title is not None:
 		data["title"] = title
-	if panel_width is not None:
-		data["panelWidth"] = panel_width
+	if width is not None:
+		data["width"] = width
 
 	return render("panel", data, **kwargs)
 
@@ -334,6 +350,25 @@ def progress_bar(
 	return render("progress-bar", data, **kwargs)
 
 
+def quote_block(
+	lines: list[str] | None = None,
+	title: str | None = None,
+	width: int | float | None = None,
+	**kwargs: Any,
+) -> str:
+	"""Return quote-block output; extra keyword arguments go to render()."""
+	data = {
+		"lines": [] if lines is None else lines,
+	}
+
+	if title is not None:
+		data["title"] = title
+	if width is not None:
+		data["width"] = width
+
+	return render("quote-block", data, **kwargs)
+
+
 def row(
 	label: str,
 	value: str,
@@ -342,6 +377,8 @@ def row(
 	label_colour: str | None = None,
 	value_colour: str | None = None,
 	separator: str | None = None,
+	wrap: bool = True,
+	wrap_width: int | float | None = None,
 	**kwargs: Any,
 ) -> str:
 	"""Return row output; extra keyword arguments go to render()."""
@@ -349,6 +386,7 @@ def row(
 		"label": label,
 		"value": value,
 		"result": result,
+		"wrap": wrap,
 	}
 
 	if label_width is not None:
@@ -359,6 +397,8 @@ def row(
 		data["valueColour"] = value_colour
 	if separator is not None:
 		data["separator"] = separator
+	if wrap_width is not None:
+		data["wrapWidth"] = wrap_width
 
 	return render("row", data, **kwargs)
 
@@ -366,15 +406,29 @@ def row(
 def row_group(
 	rows: list[dict[str, Any]],
 	label_width: int | float | None = None,
+	label_colour: str | None = None,
+	value_colour: str | None = None,
+	separator: str | None = None,
+	wrap: bool = True,
+	wrap_width: int | float | None = None,
 	**kwargs: Any,
 ) -> str:
 	"""Return row-group output; extra keyword arguments go to render()."""
 	data = {
-		"rows": rows,
+		"rows": [_camel_case_row(row) for row in rows],
+		"wrap": wrap,
 	}
 
 	if label_width is not None:
 		data["labelWidth"] = label_width
+	if label_colour is not None:
+		data["labelColour"] = label_colour
+	if value_colour is not None:
+		data["valueColour"] = value_colour
+	if separator is not None:
+		data["separator"] = separator
+	if wrap_width is not None:
+		data["wrapWidth"] = wrap_width
 
 	return render("row-group", data, **kwargs)
 

package/adapters/python/pyproject.toml

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

package/adapters/swift/Sources/CliStyle/Wrappers.swift

@@ -341,7 +341,7 @@ extension CliStyle {
 		lines: [String]? = nil,
 		title: String? = nil,
 		tone: String = "info",
-		panelWidth: Int? = nil,
+		width: Int? = nil,
 		options: CliStyleOptions = .init()
 	) throws -> String {
 		var data: [String: Any] = [
@@ -352,8 +352,8 @@ extension CliStyle {
 		if let title = title {
 			data["title"] = title
 		}
-		if let panelWidth = panelWidth {
-			data["panelWidth"] = panelWidth
+		if let width = width {
+			data["width"] = width
 		}
 
 		return try render("panel", data: data, options: options)
@@ -382,6 +382,29 @@ extension CliStyle {
 		return try render("progress-bar", data: data, options: options)
 	}
 
+	/**
+	 * Return quote-block output from the cli-style binary; `options` sets the profile, width, and binary.
+	 */
+	public static func quoteBlock(
+		lines: [String]? = nil,
+		title: String? = nil,
+		width: Int? = nil,
+		options: CliStyleOptions = .init()
+	) throws -> String {
+		var data: [String: Any] = [
+			"lines": lines ?? [],
+		]
+
+		if let title = title {
+			data["title"] = title
+		}
+		if let width = width {
+			data["width"] = width
+		}
+
+		return try render("quote-block", data: data, options: options)
+	}
+
 	/**
 	 * Return row output from the cli-style binary; `options` sets the profile, width, and binary.
 	 */
@@ -393,12 +416,15 @@ extension CliStyle {
 		labelColour: String? = nil,
 		valueColour: String? = nil,
 		separator: String? = nil,
+		wrap: Bool = true,
+		wrapWidth: Int? = nil,
 		options: CliStyleOptions = .init()
 	) throws -> String {
 		var data: [String: Any] = [
 			"label": label,
 			"value": value,
 			"result": result,
+			"wrap": wrap,
 		]
 
 		if let labelWidth = labelWidth {
@@ -413,6 +439,9 @@ extension CliStyle {
 		if let separator = separator {
 			data["separator"] = separator
 		}
+		if let wrapWidth = wrapWidth {
+			data["wrapWidth"] = wrapWidth
+		}
 
 		return try render("row", data: data, options: options)
 	}
@@ -423,15 +452,33 @@ extension CliStyle {
 	public static func rowGroup(
 		rows: [[String: Any]],
 		labelWidth: Int? = nil,
+		labelColour: String? = nil,
+		valueColour: String? = nil,
+		separator: String? = nil,
+		wrap: Bool = true,
+		wrapWidth: Int? = nil,
 		options: CliStyleOptions = .init()
 	) throws -> String {
 		var data: [String: Any] = [
 			"rows": rows,
+			"wrap": wrap,
 		]
 
 		if let labelWidth = labelWidth {
 			data["labelWidth"] = labelWidth
 		}
+		if let labelColour = labelColour {
+			data["labelColour"] = labelColour
+		}
+		if let valueColour = valueColour {
+			data["valueColour"] = valueColour
+		}
+		if let separator = separator {
+			data["separator"] = separator
+		}
+		if let wrapWidth = wrapWidth {
+			data["wrapWidth"] = wrapWidth
+		}
 
 		return try render("row-group", data: data, options: options)
 	}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@lewishowles/cli-style",
-	"version": "0.15.0",
+	"version": "0.17.0",
 	"description": "Shared terminal output styles for Lewis Howles tools, diagnostics, and package CLIs.",
 	"license": "MIT",
 	"repository": {

package/scripts/generate-adapters.js

@@ -235,10 +235,15 @@ function renderWrapper(renderer) {
 		(parameter) => !isRequiredParameter(parameter) && parameter.default === null,
 	);
 
-	const payloadLines = payloadParameters.map(
-		(parameter) =>
-			`\t\t${JSON.stringify(parameter.name)}: ${renderPayloadValue(parameter, descriptor)},`,
-	);
+	const payloadLines = payloadParameters.map((parameter) => {
+		const isRowGroupRows = renderer.name === "row-group" && parameter.name === "rows";
+
+		const payloadValue = isRowGroupRows
+			? "[_camel_case_row(row) for row in rows]"
+			: renderPayloadValue(parameter, descriptor);
+
+		return `\t\t${JSON.stringify(parameter.name)}: ${payloadValue},`;
+	});
 
 	const nullablePayloadLines = nullableParameters.flatMap((parameter) => {
 		const name = descriptor.parameterName(parameter);
@@ -279,6 +284,22 @@ function renderWrappers() {
 		"",
 		"from .core import render",
 		"",
+		"",
+		"def _camel_case_row(row: Any) -> Any:",
+		'\t"""Return a copy of a row with Python option names, such as label_colour, renamed to the camelCase names the renderer reads. Keys already in camelCase are kept, and a value that is not a dictionary is returned unchanged for the renderer to filter."""',
+		"\tif not isinstance(row, dict):",
+		"\t\treturn row",
+		"",
+		"\tconverted_row = {}",
+		"",
+		"\tfor key, value in row.items():",
+		'\t\tparts = key.split("_")',
+		'\t\tcamel_case_key = parts[0] + "".join(part.capitalize() for part in parts[1:])',
+		"\t\tconverted_row[camel_case_key] = value",
+		"",
+		"\treturn converted_row",
+		"",
+		"",
 		wrappers,
 		"",
 	].join("\n");

package/src/capability/terminal.js

@@ -29,7 +29,7 @@ export function resolveTerminalCapabilities(options = {}) {
 	const isCi = env.CI === "true" || env.CI === "1";
 	const isDumb = env.TERM === "dumb";
 	const forceColour = env.FORCE_COLOR !== undefined && env.FORCE_COLOR !== "0";
-	const width = resolveWidth(stdout.columns);
+	const width = resolveWidth(stdout.columns, env.COLUMNS);
 	const usesPlain = argv.includes("--plain");
 
 	const colour = resolveColour({
@@ -189,16 +189,25 @@ function resolveUnicode(options) {
 }
 
 /**
- * Resolve terminal width with a stable fallback.
+ * Resolve the terminal width from the output stream, then `COLUMNS`, then a fixed fallback.
  *
- * @param  {number}  width
- *     Stream-reported column count.
+ * @param  {number}  streamWidth
+ *     The column count the output stream reports when it is a terminal.
+ * @param  {string}  columns
+ *     The `COLUMNS` environment value, used when the stream reports no width, such as when
+ *     output is piped. Anything other than a positive whole number is ignored.
  * @returns  {number}
  *     Usable terminal width.
  */
-function resolveWidth(width) {
-	if (Number.isInteger(width) && width > 0) {
-		return width;
+function resolveWidth(streamWidth, columns) {
+	if (Number.isInteger(streamWidth) && streamWidth > 0) {
+		return streamWidth;
+	}
+
+	const environmentWidth = Number(columns);
+
+	if (Number.isInteger(environmentWidth) && environmentWidth > 0) {
+		return environmentWidth;
 	}
 
 	return defaultWidth;

package/src/catalogue/renderer-catalogue.js

@@ -595,7 +595,7 @@ const rendererDefinitions = [
 				default: "info",
 			},
 			{
-				name: "panelWidth",
+				name: "width",
 				type: "number",
 				required: false,
 				default: null,
@@ -635,6 +635,32 @@ const rendererDefinitions = [
 		],
 		fixture: undefined,
 	},
+	{
+		name: "quote-block",
+		category: "pattern",
+		api: "quoteBlock",
+		params: [
+			{
+				name: "lines",
+				type: "string[]",
+				required: false,
+				default: [],
+			},
+			{
+				name: "title",
+				type: "string",
+				required: false,
+				default: null,
+			},
+			{
+				name: "width",
+				type: "number",
+				required: false,
+				default: null,
+			},
+		],
+		fixture: "quote-block",
+	},
 	{
 		name: "row",
 		category: "primitive",
@@ -689,14 +715,12 @@ const rendererDefinitions = [
 				type: "boolean",
 				required: false,
 				default: true,
-				adapterOmit: true,
 			},
 			{
 				name: "wrapWidth",
 				type: "number",
 				required: false,
 				default: null,
-				adapterOmit: true,
 			},
 		],
 		fixture: undefined,
@@ -719,19 +743,35 @@ const rendererDefinitions = [
 				required: false,
 				default: null,
 			},
+			{
+				name: "labelColour",
+				type: "string",
+				required: false,
+				default: null,
+			},
+			{
+				name: "valueColour",
+				type: "string",
+				required: false,
+				default: null,
+			},
+			{
+				name: "separator",
+				type: "string",
+				required: false,
+				default: null,
+			},
 			{
 				name: "wrap",
 				type: "boolean",
 				required: false,
 				default: true,
-				adapterOmit: true,
 			},
 			{
 				name: "wrapWidth",
 				type: "number",
 				required: false,
 				default: null,
-				adapterOmit: true,
 			},
 		],
 		fixture: undefined,

package/src/cli/render-command.js

@@ -6,6 +6,7 @@ import { confirmationResult } from "../patterns/confirmation-result.js";
 import { diagnosticReport } from "../patterns/diagnostic-report.js";
 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 { barChart } from "../primitives/bar-chart.js";
 import { bulletList } from "../primitives/bullet-list.js";
@@ -38,6 +39,7 @@ const renderers = {
 		bulletList(input.items, {
 			...input,
 			...options,
+			width: input.width ?? options.width,
 		}),
 	chip: (input, options) =>
 		chip(input.label, input.tone, {
@@ -63,6 +65,7 @@ const renderers = {
 		errorBlock(input.title, input.lines, {
 			...input,
 			...options,
+			width: input.width ?? options.width,
 		}),
 	hint: (input, options) =>
 		hint(input.message, {
@@ -73,12 +76,15 @@ const renderers = {
 		labelledLine(input.label, input.message, {
 			...input,
 			...options,
+			width: input.width ?? options.width,
 		}),
 	"next-step-block": (input, options) => nextStepBlock(input, options),
+	"quote-block": (input, options) => quoteBlock(input, options),
 	panel: (input, options) =>
 		panel({
 			...input,
 			...options,
+			width: input.width ?? options.width,
 		}),
 	"progress-bar": (input, options) =>
 		progressBar({
@@ -89,16 +95,19 @@ const renderers = {
 		row(input.label, input.value, {
 			...input,
 			...options,
+			width: input.width ?? options.width,
 		}),
 	"row-group": (input, options) =>
 		rowGroup({
 			...input,
 			...options,
+			width: input.width ?? options.width,
 		}),
 	sparkline: (input, options) =>
 		sparkline({
 			...input,
 			...options,
+			width: input.width ?? options.width,
 		}),
 	span: (input, options) =>
 		span(input.value, input.tone, {
@@ -124,6 +133,7 @@ const renderers = {
 		table({
 			...input,
 			...options,
+			width: input.width ?? options.width,
 		}),
 	"task-summary": (input, options) => taskSummary(input, options),
 };

package/src/gallery/render-gallery.js

@@ -6,6 +6,7 @@ import { confirmationResult } from "../patterns/confirmation-result.js";
 import { diagnosticReport } from "../patterns/diagnostic-report.js";
 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 { renderSpinnerFrame } from "../interactive/spinner.js";
@@ -133,6 +134,7 @@ export const galleryFixtures = [
 	"confirmation-result",
 	"next-step-block",
 	"diff-block",
+	"quote-block",
 	"sparkline",
 	"spinner",
 ];
@@ -280,7 +282,6 @@ function galleryWidthOptions(width) {
 	return {
 		barWidth: Math.max(width - 18, 1),
 		dividerWidth: width,
-		panelWidth: width,
 	};
 }
 
@@ -601,6 +602,19 @@ function renderPatterns(options, fixture) {
 		"diagnostic-report": ["Diagnostic report", report],
 		"diff-block": ["Diff block", diff],
 		"next-step-block": ["Next-step block", nextStep],
+		"quote-block": [
+			"Quote block",
+			quoteBlock(
+				{
+					lines: [
+						"A command can return a long explanation that wraps while the marker stays beside each continuation line.",
+						"A second line keeps the same marker.",
+					],
+					title: "Command output",
+				},
+				options,
+			),
+		],
 		reporter: ["Reporter", reporterOutput],
 		"task-summary": ["Task summary", summary],
 	};
@@ -636,6 +650,9 @@ function renderPatterns(options, fixture) {
 		"Diff block",
 		frameExample(diff, options),
 		"",
+		"Quote block",
+		frameExample(fixtures["quote-block"][1], options),
+		"",
 		"Compact data table",
 		frameExample(compactTable, options),
 		"",
@@ -790,7 +807,7 @@ function renderPrimitives(options) {
 		emptyState("No results", "tone: muted", options),
 		errorBlock("Failed", ["tone: danger"], {
 			...options,
-			panelWidth: 40,
+			width: 40,
 		}),
 		"",
 		"Steps",

package/src/index.js

@@ -38,6 +38,7 @@ export { confirmationResult } from "./patterns/confirmation-result.js";
 export { diagnosticReport } from "./patterns/diagnostic-report.js";
 export { diffBlock } from "./patterns/diff-block.js";
 export { nextStepBlock } from "./patterns/next-step-block.js";
+export { quoteBlock } from "./patterns/quote-block.js";
 export { taskSummary } from "./patterns/task-summary.js";
 export { barChart } from "./primitives/bar-chart.js";
 export { bulletList } from "./primitives/bullet-list.js";

package/src/patterns/quote-block.js

@@ -0,0 +1,70 @@
+import { foreground, stripAnsi } from "../formatters/ansi.js";
+import { wrapText } from "../formatters/wrap.js";
+import { profiles } from "../profiles/profiles.js";
+import { isNonEmptyString, isRecord, renderSection } from "./helpers.js";
+
+// The total width, including the marker and its space, used when no width is given.
+const defaultWidth = 66;
+
+/**
+ * Render another program's output with a marker beside each line, under an optional heading.
+ *
+ * @param  {object}  quote
+ *     Quoted output to show.
+ * @param  {string[]}  quote.lines
+ *     Output lines, including any blank lines to preserve.
+ * @param  {string}  quote.title
+ *     Optional heading above the output.
+ * @param  {number}  quote.width
+ *     Optional total width, including the marker and its space.
+ * @param  {object}  options
+ *     Rendering options, such as the profile, Unicode support, and a fallback width.
+ * @returns  {object|string}
+ *     The quote unchanged for the json profile. Otherwise the marked lines as one string,
+ *     or an empty string when there are no lines to show.
+ */
+export function quoteBlock(quote, options = {}) {
+	if (options.profile === profiles.JSON) {
+		return quote;
+	}
+
+	if (!isRecord(quote) || !Array.isArray(quote.lines)) {
+		return "";
+	}
+
+	// Lines that are not strings are skipped so one bad entry does not hide the rest.
+	const lines = quote.lines.filter((line) => typeof line === "string");
+
+	if (lines.length === 0) {
+		return "";
+	}
+
+	// The width from the quote wins over the options, and an invalid width falls back to the default.
+	const requestedWidth = quote.width ?? options.width ?? defaultWidth;
+
+	const width =
+		Number.isInteger(requestedWidth) && requestedWidth > 0 ? requestedWidth : defaultWidth;
+
+	// The room left for text once the marker and its space are drawn.
+	const contentWidth = Math.max(width - 2, 1);
+
+	// Plain and CI output are written for logs and searches, so they get no colour and the ASCII marker.
+	const isPlainOutput = options.profile === profiles.CI || options.profile === profiles.PLAIN;
+
+	// The ASCII marker is also used whenever Unicode is off.
+	const marker = options.unicode === false || isPlainOutput ? "|" : "│";
+
+	// The marker is muted wherever colour is allowed.
+	const renderedMarker = isPlainOutput ? marker : foreground(marker, "muted", options);
+
+	// Each wrapped part gets its own marker, so continuation lines stay visibly quoted.
+	const renderedLines = lines.flatMap((line) =>
+		wrapText(stripAnsi(line), contentWidth).map((part) => `${renderedMarker} ${part}`),
+	);
+
+	if (!isNonEmptyString(quote.title)) {
+		return renderedLines.join("\n");
+	}
+
+	return renderSection(stripAnsi(quote.title), renderedLines, options, false);
+}

package/src/primitives/panel.js

@@ -1,10 +1,14 @@
 import { background, foreground, style } from "../formatters/ansi.js";
+import { wrapText } from "../formatters/wrap.js";
 import { profiles } from "../profiles/profiles.js";
 import { panelColours } from "../theme/colours.js";
 
-// Panels use a stable width so grouped output aligns across a report.
+// The width used when no width is given, such as a direct library call outside a terminal.
 const defaultWidth = 40;
 
+// The narrowest panel that still leaves one column for content beside the accent and padding.
+const minimumWidth = 6;
+
 // Info is the neutral semantic accent for grouped explanatory content.
 const defaultTone = "info";
 
@@ -17,8 +21,9 @@ const defaultTone = "info";
  *     Whether ANSI colour should be applied.
  * @param  {string[]}  options.lines
  *     Content lines to render.
- * @param  {number}  options.panelWidth
- *     Total panel width.
+ * @param  {number}  options.width
+ *     Total panel width, including the accent and padding. Widths below 6 are raised to 6,
+ *     which leaves room for one character of content. Longer lines wrap to fit.
  * @param  {string}  options.profile
  *     Active output profile.
  * @param  {string}  options.title
@@ -37,18 +42,18 @@ export function panel(options = {}) {
 		return [...(options.title === undefined ? [] : [options.title]), ...lines].join("\n");
 	}
 
-	const width = Math.max(options.panelWidth ?? defaultWidth, 4);
+	const width = Math.max(options.width ?? defaultWidth, minimumWidth);
 	const panelLines = ["", ...(options.title === undefined ? [] : [options.title]), ...lines, ""];
 
 	return panelLines
-		.map((line, index) =>
+		.flatMap((line, index) =>
 			renderLine(line, width, index === 1 && options.title !== undefined, options),
 		)
 		.join("\n");
 }
 
 /**
- * Render one fixed-width panel line.
+ * Render one content line, wrapped across as many panel lines as it needs.
  *
  * @param  {string}  line
  *     Content line.
@@ -58,28 +63,30 @@ export function panel(options = {}) {
  *     Whether the line is the panel title.
  * @param  {object}  options
  *     Rendering options.
- * @returns  {string}
- *     Rendered content line.
+ * @returns  {string[]}
+ *     The panel lines, each exactly `width` columns wide.
  */
 function renderLine(line, width, isTitle, options) {
 	const accent = options.unicode === false ? "|" : "▌";
 	const contentWidth = width - 5;
-	const visibleLine = line.slice(0, contentWidth);
-	const content = `  ${visibleLine.padEnd(contentWidth, " ")}  `;
 
-	if (options.colour !== true) {
-		return `${accent}${content}`;
-	}
+	return wrapText(line, contentWidth).map((visibleLine) => {
+		const content = `  ${visibleLine.padEnd(contentWidth, " ")}  `;
+
+		if (options.colour !== true) {
+			return `${accent}${content}`;
+		}
 
-	const renderedAccent = renderPanelColour(accent, options);
+		const renderedAccent = renderPanelColour(accent, options);
 
-	const renderedContent = foreground(
-		background(content, panelColours.background, options),
-		panelColours.body,
-		options,
-	);
+		const renderedContent = foreground(
+			background(content, panelColours.background, options),
+			panelColours.body,
+			options,
+		);
 
-	return `${renderedAccent}${isTitle ? style(renderedContent, "bold", options) : renderedContent}`;
+		return `${renderedAccent}${isTitle ? style(renderedContent, "bold", options) : renderedContent}`;
+	});
 }
 
 /**