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

package/dist/index.d.cts

@@ -1,6 +1,7 @@
 import { Annotations, ParseOptions, getAnnotations } from "./internal/annotations.cjs";
 import { NonEmptyString, ensureNonEmptyString, isNonEmptyString } from "./nonempty.cjs";
-import { Message, MessageFormatOptions, MessageTerm, ValueSetOptions, commandLine, envVar, formatMessage, lineBreak, link, message, metavar, optionName, optionNames, text, value, valueSet, values } from "./message.cjs";
+import { Message, MessageFormatOptions, MessageFormatter, MessageFormatterOptions, MessageTerm, ValueSetOptions, commandLine, createMessageFormatter, envVar, formatMessage, lineBreak, link, message, metavar, optionName, optionNames, text, value, valueSet, values } from "./message.cjs";
+import { ErrorLabelTerm, LabelTerm, ProgramNameTerm, SyntaxPunctuationTerm, TerminalColor, TerminalFormatContext, TerminalFormatter, TerminalFragment, TerminalStyle, TerminalTerm, TerminalTheme, defaultTerminalTheme } from "./terminal.cjs";
 import { HiddenVisibility, OptionName, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, cloneUsage, cloneUsageTerm, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, formatUsage, formatUsageTerm, isDocHidden, isSuggestionHidden, isUsageHidden, mergeHidden, normalizeUsage } from "./usage.cjs";
 import { DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, ShowChoicesOptions, ShowDefaultOptions, cloneDocEntry, deduplicateDocEntries, deduplicateDocFragments, formatDocPage, isDocEntryHidden } from "./doc.cjs";
 import { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, CronExpression, CronExpressionForOptions, CronOptions, DeferredMap, DomainOptions, EmailOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FirstOfOptions, FloatOptions, HostnameOptions, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, KeyValueOptions, LocaleOptions, MacAddressOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, RegExpOptions, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SocketAddressOptions, SocketAddressValue, StringOptions, TransformMapping, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, biject, checkBooleanOption, checkEnumOption, choice, cidr, color, cron, domain, email, fileSize, firstOf, float, hostname, integer, ip, ipv4, ipv6, isValueParser, json, keyValue, locale, macAddress, port, portRange, regExp, semVer, socketAddress, string, transform, url, uuid } from "./valueparser.cjs";
@@ -12,4 +13,4 @@ import { ParserValuePlaceholder, SourceContext, SourceContextRequest } from "./c
 import { AnyDependencySource, CombineMode, CombinedDependencyMode, DependencyMode, DependencySource, DependencySourceInfo, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, dependency, deriveFrom, deriveFromAsync, deriveFromSync, getDependencySourceInfo, isDependencySource, isDerivedValueParser } from "./internal/dependency.cjs";
 import { CommandListMode, CommandSubConfig, ContextOptionsParam, ExtractRequiredOptions, OptionSubConfig, RunOptions, RunParserError, RunWithOptions, SubstituteParserValue, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync } from "./facade.cjs";
 import { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, FlagErrorOptions, FlagOptions, NegatableFlagErrorOptions, NegatableFlagNameList, NegatableFlagNames, NegatableFlagOptions, NegatableFlagState, OptionErrorOptions, OptionOptions, OptionState, PassThroughFormat, PassThroughOptions, argument, command, constant, fail, flag, negatableFlag, option, passThrough } from "./primitives.cjs";
-export { type Annotations, AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandListMode, CommandOptions, CommandSubConfig, ConditionalErrorOptions, ConditionalOptions, ContextOptionsParam, CronExpression, CronExpressionForOptions, CronOptions, DeferredMap, DeferredValue, DeferredValueOptions, DeferredValueSource, DependencyMode, DependencySource, DependencySourceInfo, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DetailedParseResult, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EffectfulCompletionSession, EmailOptions, ExecutionContext, ExecutionPhase, ExtractRequiredOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FirstOfOptions, FlagErrorOptions, FlagOptions, FloatOptions, FluentParser, GroupOptions, HiddenVisibility, HostnameOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, KeyValueOptions, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MacAddressOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NegatableFlagErrorOptions, NegatableFlagNameList, NegatableFlagNames, NegatableFlagOptions, NegatableFlagState, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OptionSubConfig, OrErrorOptions, OrOptions, ParseFrame, type ParseOptions, Parser, ParserContext, ParserModifiers, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, RegExpOptions, Result, RunOptions, RunParserError, RunWithOptions, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SeqOptions, ShellCompletion, ShowChoicesOptions, ShowDefaultOptions, SocketAddressOptions, SocketAddressValue, SourceContext, SourceContextRequest, StringOptions, SubstituteParserValue, Suggestion, TransformMapping, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, argument, bash, biject, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, color, command, commandLine, concat, conditional, constant, createParserContext, cron, deduplicateDocEntries, deduplicateDocFragments, deferredValue, dependency, deriveFrom, deriveFromAsync, deriveFromSync, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, fail, fileSize, firstOf, fish, flag, float, fluent, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDependencySourceInfo, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredValue, isDependencySource, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isSuggestionHidden, isUsageHidden, isValueParser, json, keyValue, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, negatableFlag, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseDetailed, parseSync, passThrough, port, portRange, pwsh, regExp, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, semVer, seq, socketAddress, string, suggest, suggestAsync, suggestSync, text, transform, tuple, url, uuid, value, valueSet, values, withDefault, zsh };
+export { type Annotations, AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandListMode, CommandOptions, CommandSubConfig, ConditionalErrorOptions, ConditionalOptions, ContextOptionsParam, CronExpression, CronExpressionForOptions, CronOptions, DeferredMap, DeferredValue, DeferredValueOptions, DeferredValueSource, DependencyMode, DependencySource, DependencySourceInfo, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DetailedParseResult, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EffectfulCompletionSession, EmailOptions, ErrorLabelTerm, ExecutionContext, ExecutionPhase, ExtractRequiredOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FirstOfOptions, FlagErrorOptions, FlagOptions, FloatOptions, FluentParser, GroupOptions, HiddenVisibility, HostnameOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, KeyValueOptions, LabelTerm, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MacAddressOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageFormatter, type MessageFormatterOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NegatableFlagErrorOptions, NegatableFlagNameList, NegatableFlagNames, NegatableFlagOptions, NegatableFlagState, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OptionSubConfig, OrErrorOptions, OrOptions, ParseFrame, type ParseOptions, Parser, ParserContext, ParserModifiers, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, ProgramNameTerm, RegExpOptions, Result, RunOptions, RunParserError, RunWithOptions, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SeqOptions, ShellCompletion, ShowChoicesOptions, ShowDefaultOptions, SocketAddressOptions, SocketAddressValue, SourceContext, SourceContextRequest, StringOptions, SubstituteParserValue, Suggestion, SyntaxPunctuationTerm, TerminalColor, TerminalFormatContext, TerminalFormatter, TerminalFragment, TerminalStyle, TerminalTerm, TerminalTheme, TransformMapping, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, argument, bash, biject, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, color, command, commandLine, concat, conditional, constant, createMessageFormatter, createParserContext, cron, deduplicateDocEntries, deduplicateDocFragments, defaultTerminalTheme, deferredValue, dependency, deriveFrom, deriveFromAsync, deriveFromSync, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, fail, fileSize, firstOf, fish, flag, float, fluent, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDependencySourceInfo, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredValue, isDependencySource, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isSuggestionHidden, isUsageHidden, isValueParser, json, keyValue, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, negatableFlag, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseDetailed, parseSync, passThrough, port, portRange, pwsh, regExp, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, semVer, seq, socketAddress, string, suggest, suggestAsync, suggestSync, text, transform, tuple, url, uuid, value, valueSet, values, withDefault, zsh };

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 import { Annotations, ParseOptions, getAnnotations } from "./internal/annotations.js";
 import { NonEmptyString, ensureNonEmptyString, isNonEmptyString } from "./nonempty.js";
-import { Message, MessageFormatOptions, MessageTerm, ValueSetOptions, commandLine, envVar, formatMessage, lineBreak, link, message, metavar, optionName, optionNames, text, value, valueSet, values } from "./message.js";
+import { Message, MessageFormatOptions, MessageFormatter, MessageFormatterOptions, MessageTerm, ValueSetOptions, commandLine, createMessageFormatter, envVar, formatMessage, lineBreak, link, message, metavar, optionName, optionNames, text, value, valueSet, values } from "./message.js";
+import { ErrorLabelTerm, LabelTerm, ProgramNameTerm, SyntaxPunctuationTerm, TerminalColor, TerminalFormatContext, TerminalFormatter, TerminalFragment, TerminalStyle, TerminalTerm, TerminalTheme, defaultTerminalTheme } from "./terminal.js";
 import { HiddenVisibility, OptionName, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, cloneUsage, cloneUsageTerm, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, formatUsage, formatUsageTerm, isDocHidden, isSuggestionHidden, isUsageHidden, mergeHidden, normalizeUsage } from "./usage.js";
 import { DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, ShowChoicesOptions, ShowDefaultOptions, cloneDocEntry, deduplicateDocEntries, deduplicateDocFragments, formatDocPage, isDocEntryHidden } from "./doc.js";
 import { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, CronExpression, CronExpressionForOptions, CronOptions, DeferredMap, DomainOptions, EmailOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FirstOfOptions, FloatOptions, HostnameOptions, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, KeyValueOptions, LocaleOptions, MacAddressOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, RegExpOptions, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SocketAddressOptions, SocketAddressValue, StringOptions, TransformMapping, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, biject, checkBooleanOption, checkEnumOption, choice, cidr, color, cron, domain, email, fileSize, firstOf, float, hostname, integer, ip, ipv4, ipv6, isValueParser, json, keyValue, locale, macAddress, port, portRange, regExp, semVer, socketAddress, string, transform, url, uuid } from "./valueparser.js";
@@ -12,4 +13,4 @@ import { ParserValuePlaceholder, SourceContext, SourceContextRequest } from "./c
 import { AnyDependencySource, CombineMode, CombinedDependencyMode, DependencyMode, DependencySource, DependencySourceInfo, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, dependency, deriveFrom, deriveFromAsync, deriveFromSync, getDependencySourceInfo, isDependencySource, isDerivedValueParser } from "./internal/dependency.js";
 import { CommandListMode, CommandSubConfig, ContextOptionsParam, ExtractRequiredOptions, OptionSubConfig, RunOptions, RunParserError, RunWithOptions, SubstituteParserValue, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync } from "./facade.js";
 import { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, FlagErrorOptions, FlagOptions, NegatableFlagErrorOptions, NegatableFlagNameList, NegatableFlagNames, NegatableFlagOptions, NegatableFlagState, OptionErrorOptions, OptionOptions, OptionState, PassThroughFormat, PassThroughOptions, argument, command, constant, fail, flag, negatableFlag, option, passThrough } from "./primitives.js";
-export { type Annotations, AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandListMode, CommandOptions, CommandSubConfig, ConditionalErrorOptions, ConditionalOptions, ContextOptionsParam, CronExpression, CronExpressionForOptions, CronOptions, DeferredMap, DeferredValue, DeferredValueOptions, DeferredValueSource, DependencyMode, DependencySource, DependencySourceInfo, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DetailedParseResult, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EffectfulCompletionSession, EmailOptions, ExecutionContext, ExecutionPhase, ExtractRequiredOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FirstOfOptions, FlagErrorOptions, FlagOptions, FloatOptions, FluentParser, GroupOptions, HiddenVisibility, HostnameOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, KeyValueOptions, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MacAddressOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NegatableFlagErrorOptions, NegatableFlagNameList, NegatableFlagNames, NegatableFlagOptions, NegatableFlagState, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OptionSubConfig, OrErrorOptions, OrOptions, ParseFrame, type ParseOptions, Parser, ParserContext, ParserModifiers, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, RegExpOptions, Result, RunOptions, RunParserError, RunWithOptions, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SeqOptions, ShellCompletion, ShowChoicesOptions, ShowDefaultOptions, SocketAddressOptions, SocketAddressValue, SourceContext, SourceContextRequest, StringOptions, SubstituteParserValue, Suggestion, TransformMapping, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, argument, bash, biject, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, color, command, commandLine, concat, conditional, constant, createParserContext, cron, deduplicateDocEntries, deduplicateDocFragments, deferredValue, dependency, deriveFrom, deriveFromAsync, deriveFromSync, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, fail, fileSize, firstOf, fish, flag, float, fluent, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDependencySourceInfo, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredValue, isDependencySource, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isSuggestionHidden, isUsageHidden, isValueParser, json, keyValue, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, negatableFlag, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseDetailed, parseSync, passThrough, port, portRange, pwsh, regExp, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, semVer, seq, socketAddress, string, suggest, suggestAsync, suggestSync, text, transform, tuple, url, uuid, value, valueSet, values, withDefault, zsh };
+export { type Annotations, AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandListMode, CommandOptions, CommandSubConfig, ConditionalErrorOptions, ConditionalOptions, ContextOptionsParam, CronExpression, CronExpressionForOptions, CronOptions, DeferredMap, DeferredValue, DeferredValueOptions, DeferredValueSource, DependencyMode, DependencySource, DependencySourceInfo, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DetailedParseResult, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EffectfulCompletionSession, EmailOptions, ErrorLabelTerm, ExecutionContext, ExecutionPhase, ExtractRequiredOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FirstOfOptions, FlagErrorOptions, FlagOptions, FloatOptions, FluentParser, GroupOptions, HiddenVisibility, HostnameOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, KeyValueOptions, LabelTerm, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MacAddressOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageFormatter, type MessageFormatterOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NegatableFlagErrorOptions, NegatableFlagNameList, NegatableFlagNames, NegatableFlagOptions, NegatableFlagState, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OptionSubConfig, OrErrorOptions, OrOptions, ParseFrame, type ParseOptions, Parser, ParserContext, ParserModifiers, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, ProgramNameTerm, RegExpOptions, Result, RunOptions, RunParserError, RunWithOptions, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SeqOptions, ShellCompletion, ShowChoicesOptions, ShowDefaultOptions, SocketAddressOptions, SocketAddressValue, SourceContext, SourceContextRequest, StringOptions, SubstituteParserValue, Suggestion, SyntaxPunctuationTerm, TerminalColor, TerminalFormatContext, TerminalFormatter, TerminalFragment, TerminalStyle, TerminalTerm, TerminalTheme, TransformMapping, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, argument, bash, biject, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, color, command, commandLine, concat, conditional, constant, createMessageFormatter, createParserContext, cron, deduplicateDocEntries, deduplicateDocFragments, defaultTerminalTheme, deferredValue, dependency, deriveFrom, deriveFromAsync, deriveFromSync, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, fail, fileSize, firstOf, fish, flag, float, fluent, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDependencySourceInfo, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredValue, isDependencySource, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isSuggestionHidden, isUsageHidden, isValueParser, json, keyValue, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, negatableFlag, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseDetailed, parseSync, passThrough, port, portRange, pwsh, regExp, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, semVer, seq, socketAddress, string, suggest, suggestAsync, suggestSync, text, transform, tuple, url, uuid, value, valueSet, values, withDefault, zsh };

package/dist/index.js

@@ -1,5 +1,6 @@
 import { getAnnotations } from "./internal/annotations.js";
-import { commandLine, envVar, formatMessage, lineBreak, link, message, metavar, optionName, optionNames, text, value, valueSet, values } from "./message.js";
+import { defaultTerminalTheme } from "./terminal.js";
+import { commandLine, createMessageFormatter, envVar, formatMessage, lineBreak, link, message, metavar, optionName, optionNames, text, value, valueSet, values } from "./message.js";
 import { cloneUsage, cloneUsageTerm, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, formatUsage, formatUsageTerm, isDocHidden, isSuggestionHidden, isUsageHidden, mergeHidden, normalizeUsage } from "./usage.js";
 import { cloneDocEntry, deduplicateDocEntries, deduplicateDocFragments, formatDocPage, isDocEntryHidden } from "./doc.js";
 import { dependency, deriveFrom, deriveFromAsync, deriveFromSync, getDependencySourceInfo, isDependencySource, isDerivedValueParser } from "./internal/dependency.js";
@@ -12,4 +13,4 @@ import { biject, checkBooleanOption, checkEnumOption, choice, cidr, color, cron,
 import { argument, command, constant, fail, flag, negatableFlag, option, passThrough } from "./primitives.js";
 import { RunParserError, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync } from "./facade.js";
 
-export { DuplicateOptionError, RunParserError, WithDefaultError, argument, bash, biject, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, color, command, commandLine, concat, conditional, constant, createParserContext, cron, deduplicateDocEntries, deduplicateDocFragments, deferredValue, dependency, deriveFrom, deriveFromAsync, deriveFromSync, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, fail, fileSize, firstOf, fish, flag, float, fluent, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDependencySourceInfo, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredValue, isDependencySource, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isSuggestionHidden, isUsageHidden, isValueParser, json, keyValue, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, negatableFlag, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseDetailed, parseSync, passThrough, port, portRange, pwsh, regExp, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, semVer, seq, socketAddress, string, suggest, suggestAsync, suggestSync, text, transform, tuple, url, uuid, value, valueSet, values, withDefault, zsh };
+export { DuplicateOptionError, RunParserError, WithDefaultError, argument, bash, biject, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, color, command, commandLine, concat, conditional, constant, createMessageFormatter, createParserContext, cron, deduplicateDocEntries, deduplicateDocFragments, defaultTerminalTheme, deferredValue, dependency, deriveFrom, deriveFromAsync, deriveFromSync, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, fail, fileSize, firstOf, fish, flag, float, fluent, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDependencySourceInfo, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredValue, isDependencySource, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isSuggestionHidden, isUsageHidden, isValueParser, json, keyValue, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, negatableFlag, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseDetailed, parseSync, passThrough, port, portRange, pwsh, regExp, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, semVer, seq, socketAddress, string, suggest, suggestAsync, suggestSync, text, transform, tuple, url, uuid, value, valueSet, values, withDefault, zsh };

package/dist/internal/terminal.cjs

@@ -0,0 +1,7 @@
+const require_displaywidth = require('../displaywidth.cjs');
+const require_terminal_internal = require('../terminal-internal.cjs');
+const require_message_renderer = require('../message-renderer.cjs');
+
+exports.getDisplayWidth = require_displaywidth.getDisplayWidth;
+exports.renderTerminalTerm = require_terminal_internal.renderTerminalTerm;
+exports.resolveMessageFormatter = require_message_renderer.resolveMessageFormatter;

package/dist/internal/terminal.d.cts

@@ -0,0 +1,4 @@
+import { getDisplayWidth } from "../displaywidth.cjs";
+import { resolveMessageFormatter } from "../message-renderer.cjs";
+import { renderTerminalTerm } from "../terminal-internal.cjs";
+export { getDisplayWidth, renderTerminalTerm, resolveMessageFormatter };

package/dist/internal/terminal.d.ts

@@ -0,0 +1,4 @@
+import { getDisplayWidth } from "../displaywidth.js";
+import { resolveMessageFormatter } from "../message-renderer.js";
+import { renderTerminalTerm } from "../terminal-internal.js";
+export { getDisplayWidth, renderTerminalTerm, resolveMessageFormatter };

package/dist/internal/terminal.js

@@ -0,0 +1,5 @@
+import { getDisplayWidth } from "../displaywidth.js";
+import { renderTerminalTerm } from "../terminal-internal.js";
+import { resolveMessageFormatter } from "../message-renderer.js";
+
+export { getDisplayWidth, renderTerminalTerm, resolveMessageFormatter };

package/dist/message-registry.cjs

@@ -0,0 +1,6 @@
+
+//#region src/message-registry.ts
+const messageRenderers = /* @__PURE__ */ new WeakMap();
+
+//#endregion
+exports.messageRenderers = messageRenderers;

package/dist/message-registry.d.cts

@@ -0,0 +1,7 @@
+import { Message, MessageFormatOptions, MessageFormatter } from "./message.cjs";
+import { TerminalStyle } from "./terminal.cjs";
+
+//#region src/message-registry.d.ts
+declare const messageRenderers: WeakMap<MessageFormatter, (message: Message, options: MessageFormatOptions, ambient?: TerminalStyle) => string>;
+//#endregion
+export { messageRenderers };

package/dist/message-registry.d.ts

@@ -0,0 +1,7 @@
+import { Message, MessageFormatOptions, MessageFormatter } from "./message.js";
+import { TerminalStyle } from "./terminal.js";
+
+//#region src/message-registry.d.ts
+declare const messageRenderers: WeakMap<MessageFormatter, (message: Message, options: MessageFormatOptions, ambient?: TerminalStyle) => string>;
+//#endregion
+export { messageRenderers };

package/dist/message-registry.js

@@ -0,0 +1,5 @@
+//#region src/message-registry.ts
+const messageRenderers = /* @__PURE__ */ new WeakMap();
+
+//#endregion
+export { messageRenderers };

package/dist/message-renderer.cjs

@@ -0,0 +1,26 @@
+const require_message_registry = require('./message-registry.cjs');
+const require_message = require('./message.cjs');
+
+//#region src/message-renderer.ts
+/**
+* Resolves a presentation surface's formatter while preserving built-in
+* ambient styling and normalizing legacy color options for custom formatters.
+* @param options The surface's explicit formatter and fallback theme.
+* @returns A formatter that accepts legacy options and an ambient style.
+* @since 1.3.0
+* @internal
+*/
+function resolveMessageFormatter(options) {
+	const formatter = options.messageFormatter ?? (options.theme == null ? require_message.formatMessage : require_message.createMessageFormatter(options.theme));
+	return (message, options$1 = {}, ambient) => {
+		const builtin = require_message_registry.messageRenderers.get(formatter);
+		if (builtin != null) return builtin(message, options$1, ambient);
+		return formatter(message, {
+			...options$1,
+			colors: typeof options$1.colors === "object" ? true : options$1.colors
+		});
+	};
+}
+
+//#endregion
+exports.resolveMessageFormatter = resolveMessageFormatter;

package/dist/message-renderer.d.cts

@@ -0,0 +1,19 @@
+import { Message, MessageFormatOptions, MessageFormatter } from "./message.cjs";
+import { TerminalStyle, TerminalTheme } from "./terminal.cjs";
+
+//#region src/message-renderer.d.ts
+
+/**
+ * Resolves a presentation surface's formatter while preserving built-in
+ * ambient styling and normalizing legacy color options for custom formatters.
+ * @param options The surface's explicit formatter and fallback theme.
+ * @returns A formatter that accepts legacy options and an ambient style.
+ * @since 1.3.0
+ * @internal
+ */
+declare function resolveMessageFormatter(options: {
+  readonly messageFormatter?: MessageFormatter;
+  readonly theme?: TerminalTheme;
+}): (message: Message, options?: MessageFormatOptions, ambient?: TerminalStyle) => string;
+//#endregion
+export { resolveMessageFormatter };

package/dist/message-renderer.d.ts

@@ -0,0 +1,19 @@
+import { Message, MessageFormatOptions, MessageFormatter } from "./message.js";
+import { TerminalStyle, TerminalTheme } from "./terminal.js";
+
+//#region src/message-renderer.d.ts
+
+/**
+ * Resolves a presentation surface's formatter while preserving built-in
+ * ambient styling and normalizing legacy color options for custom formatters.
+ * @param options The surface's explicit formatter and fallback theme.
+ * @returns A formatter that accepts legacy options and an ambient style.
+ * @since 1.3.0
+ * @internal
+ */
+declare function resolveMessageFormatter(options: {
+  readonly messageFormatter?: MessageFormatter;
+  readonly theme?: TerminalTheme;
+}): (message: Message, options?: MessageFormatOptions, ambient?: TerminalStyle) => string;
+//#endregion
+export { resolveMessageFormatter };

package/dist/message-renderer.js

@@ -0,0 +1,26 @@
+import { messageRenderers } from "./message-registry.js";
+import { createMessageFormatter, formatMessage } from "./message.js";
+
+//#region src/message-renderer.ts
+/**
+* Resolves a presentation surface's formatter while preserving built-in
+* ambient styling and normalizing legacy color options for custom formatters.
+* @param options The surface's explicit formatter and fallback theme.
+* @returns A formatter that accepts legacy options and an ambient style.
+* @since 1.3.0
+* @internal
+*/
+function resolveMessageFormatter(options) {
+	const formatter = options.messageFormatter ?? (options.theme == null ? formatMessage : createMessageFormatter(options.theme));
+	return (message, options$1 = {}, ambient) => {
+		const builtin = messageRenderers.get(formatter);
+		if (builtin != null) return builtin(message, options$1, ambient);
+		return formatter(message, {
+			...options$1,
+			colors: typeof options$1.colors === "object" ? true : options$1.colors
+		});
+	};
+}
+
+//#endregion
+export { resolveMessageFormatter };

package/dist/message.cjs

@@ -1,4 +1,6 @@
+const require_message_registry = require('./message-registry.cjs');
 const require_displaywidth = require('./displaywidth.cjs');
+const require_terminal_internal = require('./terminal-internal.cjs');
 
 //#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);
+	require_message_registry.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: require_displaywidth.getDisplayWidth(match[0])
+								width: require_displaywidth.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,110 +365,50 @@ function formatMessage(msg, options = {}) {
 							if (match == null) break;
 							yield {
 								text: match[0],
-								width: require_displaywidth.getDisplayWidth(match[0])
+								width: require_displaywidth.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: require_displaywidth.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: require_displaywidth.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: require_displaywidth.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: require_displaywidth.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 ? resetSequence : ""}` : value$1,
-					width: require_displaywidth.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: require_displaywidth.getDisplayWidth(envVar$1)
-				};
-			} else if (term.type === "commandLine") {
-				const cmd = useQuotes ? `\`${term.commandLine}\`` : term.commandLine;
-				yield {
-					text: useColors ? `\x1b[36m${cmd}${resetSequence}` : cmd,
-					width: require_displaywidth.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: require_displaywidth.getDisplayWidth(displayText)
-					};
-				} else yield {
-					text: displayText,
-					width: require_displaywidth.getDisplayWidth(displayText)
-				};
-			} else throw new TypeError(`Invalid MessageTerm type: ${term["type"]}.`);
+			} else yield* require_terminal_internal.fragmentTokens(require_terminal_internal.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 require_terminal_internal.serializeTokens(tokens, useColors, ambient == null ? resetSuffix : "", ambient);
 }
+require_message_registry.messageRenderers.set(formatMessage, (msg, options, ambient) => renderMessage(msg, options, {}, ambient));
 
 //#endregion
 exports.cloneMessage = cloneMessage;
 exports.cloneMessageTerm = cloneMessageTerm;
 exports.commandLine = commandLine;
+exports.createMessageFormatter = createMessageFormatter;
 exports.envVar = envVar;
 exports.formatMessage = formatMessage;
 exports.lineBreak = lineBreak;

package/dist/message.d.cts

@@ -1,4 +1,5 @@
 import { NonEmptyString } from "./nonempty.cjs";
+import { TerminalTheme } from "./terminal.cjs";
 
 //#region src/message.d.ts
 
@@ -376,6 +377,11 @@ declare function valueSet(values: readonly string[], fallbackOrOptions: string |
  * Options for the {@link formatMessage} function.
  */
 interface MessageFormatOptions {
+  /**
+   * Columns already occupied on the first line.
+   * @since 1.3.0
+   */
+  readonly initialWidth?: number;
   /**
    * Whether to use colors in the formatted message.  If `true`,
    * the formatted message will include ANSI escape codes for colors.
@@ -417,7 +423,31 @@ interface MessageFormatOptions {
  *              {@link MessageTerm} objects.
  * @param options Optional formatting options to customize the output.
  * @returns A formatted string representation of the message.
+ * @throws {TypeError} If initialWidth is not a finite integer.
+ * @throws {RangeError} If initialWidth is negative.
  */
 declare function formatMessage(msg: Message, options?: MessageFormatOptions): string;
+/**
+ * Options passed to an injected message formatter.
+ * @since 1.3.0
+ */
+interface MessageFormatterOptions extends Omit<MessageFormatOptions, "colors"> {
+  /** Whether to emit terminal colors and hyperlinks. */
+  readonly colors?: boolean;
+}
+/**
+ * Formats a structured message for terminal output.
+ * @since 1.3.0
+ */
+type MessageFormatter = (message: Message, options?: MessageFormatterOptions) => string;
+/**
+ * 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
+ */
+declare function createMessageFormatter(theme: TerminalTheme): MessageFormatter;
 //#endregion
-export { Message, MessageFormatOptions, MessageTerm, ValueSetOptions, cloneMessage, cloneMessageTerm, commandLine, envVar, formatMessage, lineBreak, link, message, metavar, optionName, optionNames, text, url, value, valueSet, values };
+export { Message, MessageFormatOptions, MessageFormatter, MessageFormatterOptions, MessageTerm, ValueSetOptions, cloneMessage, cloneMessageTerm, commandLine, createMessageFormatter, envVar, formatMessage, lineBreak, link, message, metavar, optionName, optionNames, text, url, value, valueSet, values };

package/dist/message.d.ts

@@ -1,4 +1,5 @@
 import { NonEmptyString } from "./nonempty.js";
+import { TerminalTheme } from "./terminal.js";
 
 //#region src/message.d.ts
 
@@ -376,6 +377,11 @@ declare function valueSet(values: readonly string[], fallbackOrOptions: string |
  * Options for the {@link formatMessage} function.
  */
 interface MessageFormatOptions {
+  /**
+   * Columns already occupied on the first line.
+   * @since 1.3.0
+   */
+  readonly initialWidth?: number;
   /**
    * Whether to use colors in the formatted message.  If `true`,
    * the formatted message will include ANSI escape codes for colors.
@@ -417,7 +423,31 @@ interface MessageFormatOptions {
  *              {@link MessageTerm} objects.
  * @param options Optional formatting options to customize the output.
  * @returns A formatted string representation of the message.
+ * @throws {TypeError} If initialWidth is not a finite integer.
+ * @throws {RangeError} If initialWidth is negative.
  */
 declare function formatMessage(msg: Message, options?: MessageFormatOptions): string;
+/**
+ * Options passed to an injected message formatter.
+ * @since 1.3.0
+ */
+interface MessageFormatterOptions extends Omit<MessageFormatOptions, "colors"> {
+  /** Whether to emit terminal colors and hyperlinks. */
+  readonly colors?: boolean;
+}
+/**
+ * Formats a structured message for terminal output.
+ * @since 1.3.0
+ */
+type MessageFormatter = (message: Message, options?: MessageFormatterOptions) => string;
+/**
+ * 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
+ */
+declare function createMessageFormatter(theme: TerminalTheme): MessageFormatter;
 //#endregion
-export { Message, MessageFormatOptions, MessageTerm, ValueSetOptions, cloneMessage, cloneMessageTerm, commandLine, envVar, formatMessage, lineBreak, link, message, metavar, optionName, optionNames, text, url, value, valueSet, values };
+export { Message, MessageFormatOptions, MessageFormatter, MessageFormatterOptions, MessageTerm, ValueSetOptions, cloneMessage, cloneMessageTerm, commandLine, createMessageFormatter, envVar, formatMessage, lineBreak, link, message, metavar, optionName, optionNames, text, url, value, valueSet, values };