@optique/core 1.3.0-dev.2524 → 1.3.0-dev.2530

package/dist/message.js

@@ -1,4 +1,6 @@
+import { messageRenderers } from "./message-registry.js";
 import { getDisplayWidth } from "./displaywidth.js";
+import { formatTerminalTerm, fragmentTokens, serializeTokens } from "./terminal-internal.js";
 
 //#region src/message.ts
 /**
@@ -294,11 +296,30 @@ function valueSet(values$1, fallbackOrOptions) {
 	return result;
 }
 function formatMessage(msg, options = {}) {
+	return renderMessage(msg, options, {});
+}
+/**
+* Creates a message formatter using a snapshot of the supplied theme.
+* @param theme Semantic leaf formatters and annotation styles.
+* @returns A reusable message formatter.
+* @throws {TypeError} If initialWidth is not a finite integer.
+* @throws {RangeError} If initialWidth is negative or a color is invalid.
+* @since 1.3.0
+*/
+function createMessageFormatter(theme) {
+	const snapshot = { ...theme };
+	const formatter = (msg, options = {}) => renderMessage(msg, options, snapshot);
+	messageRenderers.set(formatter, (msg, options, ambient) => renderMessage(msg, options, snapshot, ambient));
+	return formatter;
+}
+function renderMessage(msg, options, theme, ambient) {
+	const initialWidth = options.initialWidth ?? 0;
+	if (!Number.isFinite(initialWidth) || !Number.isInteger(initialWidth)) throw new TypeError("Initial width must be a finite integer.");
+	if (initialWidth < 0) throw new RangeError("Initial width must be nonnegative.");
 	const colorConfig = options.colors ?? false;
 	const useColors = typeof colorConfig === "boolean" ? colorConfig : true;
 	const resetSuffix = typeof colorConfig === "object" ? colorConfig.resetSuffix ?? "" : "";
 	const useQuotes = options.quotes ?? true;
-	const resetSequence = `\x1b[0m${resetSuffix}`;
 	function* stream() {
 		const wordPattern = /\s*\S+\s*/g;
 		let prevWasLineBreak = false;
@@ -314,7 +335,8 @@ function formatMessage(msg, options = {}) {
 							const breakText = isAfterLineBreak && paragraphIndex === 1 ? "\n" : "\n\n";
 							yield {
 								text: breakText,
-								width: -1
+								width: -1,
+								scopes: []
 							};
 						}
 						const paragraph = paragraphs[paragraphIndex].replace(/\n/g, " ");
@@ -324,7 +346,8 @@ function formatMessage(msg, options = {}) {
 							if (match == null) break;
 							yield {
 								text: match[0],
-								width: getDisplayWidth(match[0])
+								width: getDisplayWidth(match[0]),
+								scopes: []
 							};
 						}
 					}
@@ -332,7 +355,8 @@ function formatMessage(msg, options = {}) {
 					const normalizedText = rawText.replace(/\n/g, " ");
 					if (normalizedText.trim() === "" && normalizedText.length > 0) yield {
 						text: " ",
-						width: 1
+						width: 1,
+						scopes: []
 					};
 					else {
 						wordPattern.lastIndex = 0;
@@ -341,105 +365,44 @@ function formatMessage(msg, options = {}) {
 							if (match == null) break;
 							yield {
 								text: match[0],
-								width: getDisplayWidth(match[0])
+								width: getDisplayWidth(match[0]),
+								scopes: []
 							};
 						}
 					}
 				}
-			} else if (term.type === "optionName") {
-				const name = useQuotes ? `\`${term.optionName}\`` : term.optionName;
-				yield {
-					text: useColors ? `\x1b[3m${name}${resetSequence}` : name,
-					width: getDisplayWidth(name)
-				};
-			} else if (term.type === "optionNames") {
-				const names = term.optionNames.map((name) => useQuotes ? `\`${name}\`` : name);
-				let i = 0;
-				for (const name of names) {
-					if (i > 0) yield {
-						text: "/",
-						width: 1
-					};
-					yield {
-						text: useColors ? `\x1b[3m${name}${resetSequence}` : name,
-						width: getDisplayWidth(name)
-					};
-					i++;
-				}
-			} else if (term.type === "metavar") {
-				const metavar$1 = useQuotes ? `\`${term.metavar}\`` : term.metavar;
-				yield {
-					text: useColors ? `\x1b[1m${metavar$1}${resetSequence}` : metavar$1,
-					width: getDisplayWidth(metavar$1)
-				};
-			} else if (term.type === "value") {
-				const value$1 = useQuotes ? `${JSON.stringify(term.value)}` : term.value;
-				yield {
-					text: useColors ? `\x1b[32m${value$1}${resetSequence}` : value$1,
-					width: getDisplayWidth(value$1)
-				};
-			} else if (term.type === "values") for (let i = 0; i < term.values.length; i++) {
-				if (i > 0) yield {
-					text: " ",
-					width: 1
-				};
-				const value$1 = useQuotes ? JSON.stringify(term.values[i]) : term.values[i];
-				yield {
-					text: useColors ? i <= 0 ? `\x1b[32m${value$1}` : i + 1 >= term.values.length ? `${value$1}${resetSequence}` : value$1 : value$1,
-					width: getDisplayWidth(value$1)
-				};
-			}
-			else if (term.type === "envVar") {
-				const envVar$1 = useQuotes ? `\`${term.envVar}\`` : term.envVar;
-				yield {
-					text: useColors ? `\x1b[1;4m${envVar$1}${resetSequence}` : envVar$1,
-					width: getDisplayWidth(envVar$1)
-				};
-			} else if (term.type === "commandLine") {
-				const cmd = useQuotes ? `\`${term.commandLine}\`` : term.commandLine;
-				yield {
-					text: useColors ? `\x1b[36m${cmd}${resetSequence}` : cmd,
-					width: getDisplayWidth(cmd)
-				};
 			} else if (term.type === "lineBreak") {
 				yield {
 					text: "\n",
-					width: -1
+					width: -1,
+					scopes: []
 				};
 				prevWasLineBreak = true;
-			} else if (term.type === "url") {
-				const urlString = term.url.href;
-				const displayText = useQuotes ? `<${urlString}>` : urlString;
-				if (useColors) {
-					const hyperlink = `\x1b]8;;${urlString}\x1b\\${displayText}\x1b]8;;\x1b\\${resetSuffix}`;
-					yield {
-						text: hyperlink,
-						width: getDisplayWidth(displayText)
-					};
-				} else yield {
-					text: displayText,
-					width: getDisplayWidth(displayText)
-				};
-			} else throw new TypeError(`Invalid MessageTerm type: ${term["type"]}.`);
+			} else yield* fragmentTokens(formatTerminalTerm(term, theme, useQuotes));
 		}
 	}
-	let output = "";
-	let totalWidth = options.startWidth ?? 0;
-	for (const { text: text$1, width } of stream()) {
-		if (width === -1) {
-			output += text$1;
+	const tokens = [];
+	let totalWidth = initialWidth;
+	for (const token of stream()) {
+		if (token.width === -1) {
+			tokens.push(token);
 			totalWidth = 0;
 			continue;
 		}
-		if (options.maxWidth != null && totalWidth > 0 && totalWidth + width > options.maxWidth) {
-			output += "\n";
+		if (options.maxWidth != null && totalWidth > 0 && totalWidth + token.width > options.maxWidth) {
+			tokens.push({
+				text: "\n",
+				width: -1,
+				scopes: []
+			});
 			totalWidth = 0;
 		}
-		output += text$1;
-		totalWidth += width;
+		tokens.push(token);
+		totalWidth += token.width;
 	}
-	return output;
+	return serializeTokens(tokens, useColors, ambient == null ? resetSuffix : "", ambient);
 }
+messageRenderers.set(formatMessage, (msg, options, ambient) => renderMessage(msg, options, {}, ambient));
 
 //#endregion
-export { cloneMessage, cloneMessageTerm, commandLine, envVar, formatMessage, lineBreak, link, message, metavar, optionName, optionNames, text, url, value, valueSet, values };
+export { cloneMessage, cloneMessageTerm, commandLine, createMessageFormatter, envVar, formatMessage, lineBreak, link, message, metavar, optionName, optionNames, text, url, value, valueSet, values };

package/dist/terminal-internal.cjs

@@ -0,0 +1,259 @@
+const require_displaywidth = require('./displaywidth.cjs');
+const require_terminal = require('./terminal.cjs');
+
+//#region src/terminal-internal.ts
+function terminalText(text) {
+	return {
+		type: "text",
+		text
+	};
+}
+function formatTerminalTerm(term, theme = {}, quotes = false, usage) {
+	const quote = (s) => quotes ? `\`${s}\`` : s;
+	let text;
+	switch (term.type) {
+		case "text": return terminalText(term.text);
+		case "lineBreak": throw new TypeError("Hard breaks must be rendered at the message level.");
+		case "optionName":
+			text = quote(term.optionName);
+			break;
+		case "optionNames":
+			text = term.optionNames.map(quote).join("/");
+			break;
+		case "metavar":
+			text = quote(term.metavar);
+			break;
+		case "value":
+			text = quotes ? JSON.stringify(term.value) : term.value;
+			break;
+		case "values":
+			text = term.values.map((v) => quotes ? JSON.stringify(v) : v).join(" ");
+			break;
+		case "envVar":
+			text = quote(term.envVar);
+			break;
+		case "commandLine":
+			text = quote(term.commandLine);
+			break;
+		case "url":
+			text = quotes ? `<${term.url.href}>` : term.url.href;
+			break;
+		case "programName":
+			text = term.programName;
+			break;
+		case "label":
+		case "errorLabel":
+			text = term.label;
+			break;
+		case "syntaxPunctuation":
+			text = term.punctuation;
+			break;
+		default: throw new TypeError(`Invalid MessageTerm type: ${term["type"]}.`);
+	}
+	const ctx = {
+		quotes,
+		text,
+		usage,
+		format: (child) => formatTerminalTerm(child, theme, quotes, usage)
+	};
+	switch (term.type) {
+		case "optionName": return (theme.optionName ?? require_terminal.defaultTerminalTheme.optionName)(term, ctx);
+		case "optionNames": return (theme.optionNames ?? require_terminal.defaultTerminalTheme.optionNames)(term, ctx);
+		case "metavar": return (theme.metavar ?? require_terminal.defaultTerminalTheme.metavar)(term, ctx);
+		case "value": return (theme.value ?? require_terminal.defaultTerminalTheme.value)(term, ctx);
+		case "values": return (theme.values ?? require_terminal.defaultTerminalTheme.values)(term, ctx);
+		case "envVar": return (theme.envVar ?? require_terminal.defaultTerminalTheme.envVar)(term, ctx);
+		case "commandLine": return (theme.commandLine ?? require_terminal.defaultTerminalTheme.commandLine)(term, ctx);
+		case "url": return (theme.url ?? require_terminal.defaultTerminalTheme.url)(term, ctx);
+		case "programName": return (theme.programName ?? require_terminal.defaultTerminalTheme.programName)(term, ctx);
+		case "label": return (theme.label ?? require_terminal.defaultTerminalTheme.label)(term, ctx);
+		case "syntaxPunctuation": return (theme.syntaxPunctuation ?? require_terminal.defaultTerminalTheme.syntaxPunctuation)(term, ctx);
+		case "errorLabel": return (theme.errorLabel ?? require_terminal.defaultTerminalTheme.errorLabel)(term, ctx);
+	}
+}
+const colorNames = [
+	"black",
+	"red",
+	"green",
+	"yellow",
+	"blue",
+	"magenta",
+	"cyan",
+	"white",
+	"brightBlack",
+	"brightRed",
+	"brightGreen",
+	"brightYellow",
+	"brightBlue",
+	"brightMagenta",
+	"brightCyan",
+	"brightWhite"
+];
+function colorCode(color, background) {
+	const channel = (n) => {
+		if (!Number.isInteger(n) || n < 0 || n > 255) throw new RangeError("Terminal color channels must be integers from 0 to 255.");
+		return n;
+	};
+	if (typeof color === "string") {
+		const i = colorNames.indexOf(color);
+		if (i < 0) throw new RangeError("Unknown terminal color.");
+		return String((background ? 40 : 30) + (i >= 8 ? 60 + i - 8 : i));
+	}
+	const prefix = background ? 48 : 38;
+	if ("index" in color) return `${prefix};5;${channel(color.index)}`;
+	return `${prefix};2;${color.map(channel).join(";")}`;
+}
+function styleCode(style) {
+	const codes = [];
+	if (style.bold) codes.push(1);
+	if (style.dim) codes.push(2);
+	if (style.italic) codes.push(3);
+	if (style.underline) codes.push(4);
+	if (style.foreground != null) codes.push(colorCode(style.foreground, false));
+	if (style.background != null) codes.push(colorCode(style.background, true));
+	return codes.length ? `\x1b[${codes.join(";")}m` : "";
+}
+function sameStyle(a, b) {
+	return a.bold === b.bold && a.dim === b.dim && a.italic === b.italic && a.underline === b.underline && JSON.stringify(a.foreground) === JSON.stringify(b.foreground) && JSON.stringify(a.background) === JSON.stringify(b.background);
+}
+function* fragmentTokens(fragment, scopes = [], inherited = {}) {
+	if (fragment.type === "text") {
+		yield {
+			text: fragment.text,
+			width: require_displaywidth.getDisplayWidth(fragment.text),
+			scopes
+		};
+		return;
+	}
+	let next = scopes;
+	let style = inherited;
+	if (fragment.type === "style") {
+		styleCode(fragment.style);
+		style = {
+			...inherited,
+			...fragment.style
+		};
+		if (!sameStyle(style, inherited)) next = [...scopes, {
+			kind: "style",
+			style: fragment.style
+		}];
+	} else if (fragment.type === "link") next = [...scopes, {
+		kind: "link",
+		href: fragment.href
+	}];
+	for (const child of fragment.children) yield* fragmentTokens(child, next, style);
+}
+function serializeTokens(tokens, colors = false, resetSuffix = "", ambient = {}) {
+	let output = "";
+	let active = [];
+	function transition(next) {
+		let common = 0;
+		while (common < active.length && common < next.length && active[common] === next[common]) common++;
+		const surviving = active.slice(0, common);
+		const restored = surviving.reduce((style, scope) => ({
+			...style,
+			...scope.style
+		}), ambient);
+		let reset = false;
+		let closedLink = false;
+		for (let i = active.length - 1; i >= common; i--) if (active[i].kind === "link") {
+			output += `\x1b]8;;\x1b\\${resetSuffix}${styleCode(restored)}`;
+			closedLink = true;
+		} else reset = true;
+		active = surviving;
+		if (closedLink) {
+			const parentLink = active.findLast((scope) => scope.kind === "link");
+			if (parentLink != null) output += `\x1b]8;;${parentLink.href}\x1b\\`;
+		}
+		if (reset) output += "\x1B[0m" + resetSuffix + styleCode(restored);
+		for (const scope of next.slice(common)) {
+			if (scope.kind === "link") output += `\x1b]8;;${scope.href}\x1b\\`;
+			else if (scope.style) if (Object.values(scope.style).includes(false)) {
+				const inherited = active.reduce((s, x) => ({
+					...s,
+					...x.style
+				}), ambient);
+				output += "\x1B[0m" + resetSuffix + styleCode({
+					...inherited,
+					...scope.style
+				});
+			} else output += styleCode(scope.style);
+			active = [...active, scope];
+		}
+	}
+	const items = [...tokens];
+	for (let i = 0; i < items.length; i++) {
+		const token = items[i];
+		if (colors && token.width === -1) {
+			const next = items.slice(i + 1).find((t) => t.width !== -1)?.scopes ?? [];
+			let common = 0;
+			while (common < active.length && common < next.length && active[common] === next[common]) common++;
+			transition(active.slice(0, common));
+		} else if (colors) transition(token.scopes);
+		output += token.text;
+	}
+	if (colors) transition([]);
+	return output;
+}
+/**
+* Serializes one semantic leaf for a terminal surface outside a message.
+* @param term The semantic leaf to render.
+* @param theme Optional overrides for the default terminal theme.
+* @param colors Whether to emit styles and hyperlinks.
+* @param usage The leaf's usage context, when applicable.
+* @param ambient The style surrounding the rendered leaf.
+* @returns The leaf's styled or plain representation.
+* @throws {TypeError} If the term is a hard break or has an unknown type.
+* @throws {RangeError} If a color channel or palette index is invalid.
+* @since 1.3.0
+* @internal
+*/
+function renderTerminalTerm(term, theme, colors, usage, ambient) {
+	return serializeTokens(fragmentTokens(formatTerminalTerm(term, theme, false, usage)), colors, "", ambient);
+}
+/** Memoizes semantic leaves for one layout pass, including measurement. */
+function cacheTerminalTheme(theme = {}) {
+	function cache(formatter) {
+		const fragments = /* @__PURE__ */ new Map();
+		return (term, context) => {
+			const key = JSON.stringify([
+				term,
+				context.quotes,
+				context.usage
+			]);
+			let fragment = fragments.get(key);
+			if (fragment == null) {
+				fragment = formatter(term, context);
+				fragments.set(key, fragment);
+			}
+			return fragment;
+		};
+	}
+	return {
+		optionName: cache(theme.optionName ?? require_terminal.defaultTerminalTheme.optionName),
+		optionNames: cache(theme.optionNames ?? require_terminal.defaultTerminalTheme.optionNames),
+		metavar: cache(theme.metavar ?? require_terminal.defaultTerminalTheme.metavar),
+		value: cache(theme.value ?? require_terminal.defaultTerminalTheme.value),
+		values: cache(theme.values ?? require_terminal.defaultTerminalTheme.values),
+		envVar: cache(theme.envVar ?? require_terminal.defaultTerminalTheme.envVar),
+		commandLine: cache(theme.commandLine ?? require_terminal.defaultTerminalTheme.commandLine),
+		url: cache(theme.url ?? require_terminal.defaultTerminalTheme.url),
+		programName: cache(theme.programName ?? require_terminal.defaultTerminalTheme.programName),
+		label: cache(theme.label ?? require_terminal.defaultTerminalTheme.label),
+		syntaxPunctuation: cache(theme.syntaxPunctuation ?? require_terminal.defaultTerminalTheme.syntaxPunctuation),
+		errorLabel: cache(theme.errorLabel ?? require_terminal.defaultTerminalTheme.errorLabel),
+		annotationStyles: theme.annotationStyles == null ? void 0 : {
+			default: theme.annotationStyles.default == null ? void 0 : { ...theme.annotationStyles.default },
+			choices: theme.annotationStyles.choices == null ? void 0 : { ...theme.annotationStyles.choices }
+		}
+	};
+}
+
+//#endregion
+exports.cacheTerminalTheme = cacheTerminalTheme;
+exports.formatTerminalTerm = formatTerminalTerm;
+exports.fragmentTokens = fragmentTokens;
+exports.renderTerminalTerm = renderTerminalTerm;
+exports.serializeTokens = serializeTokens;
+exports.styleCode = styleCode;
+exports.terminalText = terminalText;

package/dist/terminal-internal.d.cts

@@ -0,0 +1,36 @@
+import { TerminalFormatContext, TerminalFragment, TerminalStyle, TerminalTerm, TerminalTheme } from "./terminal.cjs";
+
+//#region src/terminal-internal.d.ts
+interface Scope {
+  readonly kind: "style" | "link";
+  readonly style?: TerminalStyle;
+  readonly href?: string;
+}
+interface TerminalToken {
+  readonly text: string;
+  readonly width: number;
+  readonly scopes: readonly Scope[];
+}
+declare function terminalText(text: string): TerminalFragment;
+declare function formatTerminalTerm(term: TerminalTerm, theme?: TerminalTheme, quotes?: boolean, usage?: TerminalFormatContext["usage"]): TerminalFragment;
+declare function styleCode(style: TerminalStyle): string;
+declare function fragmentTokens(fragment: TerminalFragment, scopes?: readonly Scope[], inherited?: TerminalStyle): Generator<TerminalToken>;
+declare function serializeTokens(tokens: Iterable<TerminalToken>, colors?: boolean, resetSuffix?: string, ambient?: TerminalStyle): string;
+/**
+ * Serializes one semantic leaf for a terminal surface outside a message.
+ * @param term The semantic leaf to render.
+ * @param theme Optional overrides for the default terminal theme.
+ * @param colors Whether to emit styles and hyperlinks.
+ * @param usage The leaf's usage context, when applicable.
+ * @param ambient The style surrounding the rendered leaf.
+ * @returns The leaf's styled or plain representation.
+ * @throws {TypeError} If the term is a hard break or has an unknown type.
+ * @throws {RangeError} If a color channel or palette index is invalid.
+ * @since 1.3.0
+ * @internal
+ */
+declare function renderTerminalTerm(term: TerminalTerm, theme?: TerminalTheme, colors?: boolean, usage?: TerminalFormatContext["usage"], ambient?: TerminalStyle): string;
+/** Memoizes semantic leaves for one layout pass, including measurement. */
+declare function cacheTerminalTheme(theme?: TerminalTheme): TerminalTheme;
+//#endregion
+export { Scope, TerminalToken, cacheTerminalTheme, formatTerminalTerm, fragmentTokens, renderTerminalTerm, serializeTokens, styleCode, terminalText };

package/dist/terminal-internal.d.ts

@@ -0,0 +1,36 @@
+import { TerminalFormatContext, TerminalFragment, TerminalStyle, TerminalTerm, TerminalTheme } from "./terminal.js";
+
+//#region src/terminal-internal.d.ts
+interface Scope {
+  readonly kind: "style" | "link";
+  readonly style?: TerminalStyle;
+  readonly href?: string;
+}
+interface TerminalToken {
+  readonly text: string;
+  readonly width: number;
+  readonly scopes: readonly Scope[];
+}
+declare function terminalText(text: string): TerminalFragment;
+declare function formatTerminalTerm(term: TerminalTerm, theme?: TerminalTheme, quotes?: boolean, usage?: TerminalFormatContext["usage"]): TerminalFragment;
+declare function styleCode(style: TerminalStyle): string;
+declare function fragmentTokens(fragment: TerminalFragment, scopes?: readonly Scope[], inherited?: TerminalStyle): Generator<TerminalToken>;
+declare function serializeTokens(tokens: Iterable<TerminalToken>, colors?: boolean, resetSuffix?: string, ambient?: TerminalStyle): string;
+/**
+ * Serializes one semantic leaf for a terminal surface outside a message.
+ * @param term The semantic leaf to render.
+ * @param theme Optional overrides for the default terminal theme.
+ * @param colors Whether to emit styles and hyperlinks.
+ * @param usage The leaf's usage context, when applicable.
+ * @param ambient The style surrounding the rendered leaf.
+ * @returns The leaf's styled or plain representation.
+ * @throws {TypeError} If the term is a hard break or has an unknown type.
+ * @throws {RangeError} If a color channel or palette index is invalid.
+ * @since 1.3.0
+ * @internal
+ */
+declare function renderTerminalTerm(term: TerminalTerm, theme?: TerminalTheme, colors?: boolean, usage?: TerminalFormatContext["usage"], ambient?: TerminalStyle): string;
+/** Memoizes semantic leaves for one layout pass, including measurement. */
+declare function cacheTerminalTheme(theme?: TerminalTheme): TerminalTheme;
+//#endregion
+export { Scope, TerminalToken, cacheTerminalTheme, formatTerminalTerm, fragmentTokens, renderTerminalTerm, serializeTokens, styleCode, terminalText };