cli-kiss 0.2.3 → 0.2.5

package/dist/index.d.ts

@@ -1,6 +1,5 @@
 /**
- * Opaque key identifying a registered option within a {@link ReaderArgs} instance.
- * Returned by {@link ReaderArgs.registerOption}; passed to {@link ReaderArgs.getOptionValues}.
+ * Opaque key returned by {@link ReaderArgs.registerOption}.
  */
 type ReaderOptionKey = (string | {
     __brand: "ReaderOptionKey";
@@ -8,35 +7,44 @@ type ReaderOptionKey = (string | {
     __brand: "ReaderOptionKey";
 };
 /**
- * Option registration and query interface, implemented by {@link ReaderArgs}.
- * Exposed separately from {@link ReaderPositionals} so parsers depend only on what they need.
+ * Parsing behaviour for a registered option, passed to {@link ReaderArgs.registerOption}.
+ */
+type ReaderOptionParsing = {
+    consumeShortGroup: boolean;
+    consumeNextArg: (inlined: string | null, separated: Array<string>, nextArg: string | undefined) => boolean;
+};
+/**
+ * Result of parsing an option, including its inlined value and any following separated values.
+ */
+type ReaderOptionValue = {
+    inlined: string | null;
+    separated: Array<string>;
+};
+/**
+ * Option registration/query interface. Subset of {@link ReaderArgs}.
  */
 type ReaderOptions = {
     /**
-     * Registers an option so the parser can recognise it.
+     * Registers an option; all `longs` and `shorts` share the same key.
      *
      * @param definition.longs - Long-form names (without `--`).
      * @param definition.shorts - Short-form names (without `-`).
-     * @param definition.valued - `true` if the option takes a value; `false` for flags.
+     * @param definition.parsing - Parsing behaviour.
      * @returns A {@link ReaderOptionKey} for later retrieval.
      * @throws `Error` if a name is already registered or short names overlap.
      */
     registerOption(definition: {
         longs: Array<string>;
         shorts: Array<string>;
-        valued: boolean;
+        parsing: ReaderOptionParsing;
     }): ReaderOptionKey;
     /**
-     * Returns all values collected for the option identified by `key`.
-     *
-     * @param key - Key from {@link ReaderOptions.registerOption}.
-     * @returns Raw string values, one per occurrence; empty if never provided.
-     * @throws `Error` if `key` was not registered.
+     * Returns all values collected for `key`.
      */
-    getOptionValues(key: ReaderOptionKey): Array<string>;
+    getOptionValues(key: ReaderOptionKey): Array<ReaderOptionValue>;
 };
 /**
- * Positional token consumption interface, implemented by {@link ReaderArgs}.
+ * Positional consumption interface. Subset of {@link ReaderArgs}.
  */
 type ReaderPositionals = {
     /**
@@ -64,31 +72,29 @@ declare class ReaderArgs {
     constructor(args: ReadonlyArray<string>);
     /**
      * Registers an option; all `longs` and `shorts` share the same key.
-     * Short names support stacking (e.g. `-abc`) and inline values (e.g. `-nvalue`),
-     * but must not be prefixes of one another.
+     * Short names must not be prefixes of one another.
      *
      * @param definition.longs - Long-form names (without `--`).
      * @param definition.shorts - Short-form names (without `-`).
-     * @param definition.valued - `true` if the option takes a value; `false` for flags.
+     * @param definition.parsing - Parsing behaviour.
      * @returns A {@link ReaderOptionKey} for {@link ReaderArgs.getOptionValues}.
      * @throws `Error` if any name is already registered or short names overlap.
      */
     registerOption(definition: {
         longs: Array<string>;
         shorts: Array<string>;
-        valued: boolean;
+        parsing: ReaderOptionParsing;
     }): ReaderOptionKey;
     /**
-     * Returns all values collected for the option key.
+     * Returns all values collected for `key`.
      *
      * @param key - Key from {@link ReaderArgs.registerOption}.
-     * @returns String values, one per occurrence.
+     * @returns One entry per occurrence.
      * @throws `Error` if `key` was not registered.
      */
-    getOptionValues(key: ReaderOptionKey): Array<string>;
+    getOptionValues(key: ReaderOptionKey): Array<ReaderOptionValue>;
     /**
-     * Returns the next bare positional token.
-     * Parse intervening options as side-effects.
+     * Returns the next positional token; parses intervening options as a side-effect.
      * All tokens after `--` are treated as positionals.
      *
      * @returns The next positional, or `undefined` when exhausted.
@@ -99,21 +105,21 @@ declare class ReaderArgs {
 
 /**
  * Decodes a raw CLI string into a typed value.
- * A pair of a human-readable `content` name (e.g. `"Number"`) and a `decoder` function.
+ * A pair of a human-readable `content` name and a `decoder` function.
  *
- * Built-in: {@link typeString}, {@link typeBoolean}, {@link typeNumber},
- * {@link typeInteger}, {@link typeDate}, {@link typeUrl}.
- * Composite: {@link typeOneOf}, {@link typeMapped}, {@link typeTuple}, {@link typeList}.
+ * Built-in: {@link type}, {@link typeBoolean}, {@link typeNumber},
+ * {@link typeInteger}, {@link typeDatetime}, {@link typeUrl}.
+ * Composite: {@link typeChoice}, {@link typeConverted}, {@link typeTuple}, {@link typeList}.
  *
  * @typeParam Value - Type produced by the decoder.
  */
 type Type<Value> = {
     /**
-     * Human-readable name shown in help and error messages (e.g. `"String"`, `"Number"`).
+     * Human-readable name shown in help and errors (e.g. `"name"`, `"number"`).
      */
     content: string;
     /**
-     * Converts a raw CLI string into `Value`.
+     * Decodes a raw CLI string into `Value`.
      *
      * @param input - Raw string from the command line.
      * @returns The decoded value.
@@ -122,122 +128,133 @@ type Type<Value> = {
     decoder(input: string): Value;
 };
 /**
- * Decodes `"true"` / `"yes"` → `true` and `"false"` / `"no"` → `false` (case-insensitive).
- * Used internally by {@link optionFlag} for the `--flag=<value>` syntax.
+ * Decodes a string to `boolean` (case-insensitive).
+ * Used by {@link optionFlag} for `--flag=<value>`.
  *
  * @example
  * ```ts
- * typeBoolean.decoder("yes")   // → true
- * typeBoolean.decoder("false") // → false
- * typeBoolean.decoder("1")     // throws TypoError
+ * typeBoolean("flag").decoder("true")  // → true
+ * typeBoolean("flag").decoder("yes")   // → true
+ * typeBoolean("flag").decoder("y")     // → true
+ * typeBoolean("flag").decoder("false") // → false
+ * typeBoolean("flag").decoder("no")    // → false
+ * typeBoolean("flag").decoder("n")     // → false
  * ```
  */
-declare const typeBoolean: Type<boolean>;
+declare function typeBoolean(name?: string): Type<boolean>;
 /**
- * Parses a date/time string via `Date.parse` into a `Date` object.
+ * Parses a date/time string via `Date.parse`.
  * Accepts any format supported by `Date.parse`, including ISO 8601.
  *
  * @example
  * ```ts
- * typeDate.decoder("2024-01-15") // → Date object for 2024-01-15
- * typeDate.decoder("2024-01-15T13:45:30Z") // → Date object for 2024-01-15 13:45:30 UTC
- * typeDate.decoder("not a date") // throws TypoError
+ * typeDatetime("my-datetime").decoder("2024-01-15") // → Date object for 2024-01-15
+ * typeDatetime("my-datetime").decoder("2024-01-15T13:45:30Z") // → Date object for 2024-01-15 13:45:30 UTC
+ * typeDatetime("my-datetime").decoder("not a date") // throws TypoError
  * ```
  */
-declare const typeDate: Type<Date>;
+declare function typeDatetime(name?: string): Type<Date>;
 /**
- * Parses a string into a `number` via `Number()`.
- * Accepts integers, floats, and scientific notation; `NaN` throws a {@link TypoError}.
+ * Parses a string to `number` via `Number()`; `NaN` throws {@link TypoError}.
  *
  * @example
  * ```ts
- * typeNumber.decoder("3.14")  // → 3.14
- * typeNumber.decoder("-1")    // → -1
- * typeNumber.decoder("hello") // throws TypoError
+ * typeNumber("my-number").decoder("3.14")  // → 3.14
+ * typeNumber("my-number").decoder("-1")    // → -1
+ * typeNumber("my-number").decoder("hello") // throws TypoError
  * ```
  */
-declare const typeNumber: Type<number>;
+declare function typeNumber(name?: string): Type<number>;
 /**
- * Parses an integer string into a `bigint` via `BigInt()`.
- * Floats and non-numeric strings throw a {@link TypoError}.
+ * Parses an integer string to `bigint` via `BigInt()`.
+ * Floats and non-numeric strings throw {@link TypoError}.
  *
  * @example
  * ```ts
- * typeInteger.decoder("42")   // → 42n
- * typeInteger.decoder("3.14") // throws TypoError
- * typeInteger.decoder("abc")  // throws TypoError
+ * typeInteger("my-integer").decoder("42")   // → 42n
+ * typeInteger("my-integer").decoder("3.14") // throws TypoError
+ * typeInteger("my-integer").decoder("abc")  // throws TypoError
  * ```
  */
-declare const typeInteger: Type<bigint>;
+declare function typeInteger(name?: string): Type<bigint>;
 /**
- * Parses an absolute URL string into a `URL` object.
- * Relative or malformed URLs throw a {@link TypoError}.
+ * Parses an absolute URL string to a `URL` object.
+ * Relative or malformed URLs throw {@link TypoError}.
  *
  * @example
  * ```ts
- * typeUrl.decoder("https://example.com") // → URL { href: "https://example.com/", ... }
- * typeUrl.decoder("not-a-url")           // throws TypoError
+ * typeUrl("my-url").decoder("https://example.com") // → URL { href: "https://example.com/", ... }
+ * typeUrl("my-url").decoder("not-a-url")           // throws TypoError
  * ```
  */
-declare const typeUrl: Type<URL>;
+declare function typeUrl(name?: string): Type<URL>;
 /**
- * Identity decoder — passes the raw string through unchanged.
- *
+ * A named type that accepts any string as input.
+ * @param name - Name shown in help and errors (e.g. `"my-value"`).
  * @example
  * ```ts
- * typeString.decoder("hello") // → "hello"
- * typeString.decoder("")      // → ""
+ * type("greeting").decoder("hello") // → "hello"
+ * type("greeting").decoder("")      // → ""
  * ```
  */
-declare const typeString: Type<string>;
+declare function type(name?: string): Type<string>;
 /**
- * Creates a {@link Type} by chaining `before`'s decoder with an `after` transformation.
+ * Chains `before`'s decoder with an `after` transformation.
  * `before` errors are prefixed with `"from: <content>"` for traceability.
  *
  * @typeParam Before - Intermediate type from `before.decoder`.
  * @typeParam After - Final type from `after.decoder`.
  *
- * @param before - Base decoder for the raw string.
- * @param after - Transformation applied to the decoded value.
- * @param after.content - Name for the resulting type (shown in errors).
- * @param after.decoder - Converts a `Before` value to `After`.
+ * @param name - Name shown in help and errors (e.g. `"my-value"`).
+ * @param before - Base type to decode the raw string.
+ * @param mapper - Transforms `before`'s output to the final value; errors are wrapped with context.
  * @returns A {@link Type}`<After>`.
  *
  * @example
  * ```ts
- * const typePort = typeMapped(typeNumber, {
- *   content: "Port",
- *   decoder: (n) => {
- *     if (n < 1 || n > 65535) throw new Error("Out of range");
- *     return n;
- *   },
+ * const typePort = typeConverted("port", typeNumber(), (n) => {
+ *   if (n < 1 || n > 65535) throw new Error("Out of range");
+ *   return n;
  * });
  * // "--port 8080"   →  8080
  * // "--port 99999"  →  TypoError: --port: <PORT>: Port: Out of range
  * ```
  */
-declare function typeMapped<Before, After>(before: Type<Before>, after: {
-    content: string;
-    decoder: (value: Before) => After;
-}): Type<After>;
+declare function typeConverted<Before, After>(name: string, before: Type<Before>, mapper: (value: Before) => After): Type<After>;
+/**
+ * Adds a name to a {@link Type} for clearer error messages and help text.
+ *
+ * @param name - Name to use for the type.
+ * @param type - Base type to name.
+ * @returns A {@link Type} with the given name.
+ */
+declare function typeRenamed<Value>(type: Type<Value>, name: string): Type<Value>;
+/**
+ * Creates a {@link Type} for filesystem paths with optional existence checks.
+ * @param checks - Optional checks for path existence and type (file/directory).
+ * @returns A {@link Type}`<string>` representing the path.
+ */
+declare function typePath(name?: string, checks?: {
+    checkSyncExistAs?: "file" | "directory" | "anything";
+}): Type<string>;
 /**
- * Creates a {@link Type}`<string>` accepting only a fixed set of string values.
- * Out-of-set inputs throw a {@link TypoError} listing up to 5 valid options.
+ * Creates a {@link Type}`<string>` that only accepts a fixed set of values.
+ * Out-of-set inputs throw {@link TypoError} listing up to 5 valid options.
  *
- * @param content - Name shown in help and errors (e.g. `"Environment"`).
+ * @param name - Name shown in help and errors.
  * @param values - Ordered list of accepted values.
  * @returns A {@link Type}`<string>`.
  *
  * @example
  * ```ts
- * const typeEnv = typeOneOf("Environment", ["dev", "staging", "prod"]);
+ * const typeEnv = typeChoice("environment", ["dev", "staging", "prod"]);
  * typeEnv.decoder("prod")    // → "prod"
  * typeEnv.decoder("unknown") // throws TypoError: Invalid value: "unknown" (expected one of: "dev" | "staging" | "prod")
  * ```
  */
-declare function typeOneOf<const Value extends string>(content: string, values: Array<Value>): Type<Value>;
+declare function typeChoice<const Value extends string>(name: string, values: Array<Value>, caseSensitive?: boolean): Type<Value>;
 /**
- * Splits a delimited string into a fixed-length typed tuple.
+ * Splits a delimited string into a typed tuple.
  * Each part is decoded by the corresponding element type; wrong count or decode failure throws {@link TypoError}.
  *
  * @typeParam Elements - Tuple of decoded value types (inferred from `elementTypes`).
@@ -248,7 +265,7 @@ declare function typeOneOf<const Value extends string>(content: string, values:
  *
  * @example
  * ```ts
- * const typePoint = typeTuple([typeNumber, typeNumber]);
+ * const typePoint = typeTuple([typeNumber("x"), typeNumber("y")]);
  * typePoint.decoder("3.14,2.71") // → [3.14, 2.71]
  * typePoint.decoder("1,2,3")     // → [1, 2]
  * typePoint.decoder("x,2")       // throws TypoError: at 0: Number: Unable to parse: "x"
@@ -258,7 +275,7 @@ declare function typeTuple<const Elements extends Array<any>>(elementTypes: {
     [K in keyof Elements]: Type<Elements[K]>;
 }, separator?: string): Type<Elements>;
 /**
- * Splits a delimited string into a variable-length typed array.
+ * Splits a delimited string into a typed array.
  * Each part is decoded by `elementType`; failed decodes throw {@link TypoError}.
  * Note: splitting an empty string yields one empty element — prefer {@link optionRepeatable} for a zero-default.
  *
@@ -274,282 +291,586 @@ declare function typeTuple<const Elements extends Array<any>>(elementTypes: {
  * typeNumbers.decoder("1,2,3")  // → [1, 2, 3]
  * typeNumbers.decoder("1,x,3")  // throws TypoError: at 1: Number: Unable to parse: "x"
  *
- * const typePaths = typeList(typeString, ":");
+ * const typePaths = typeList(typePath(), ":");
  * typePaths.decoder("/usr/bin:/usr/local/bin") // → ["/usr/bin", "/usr/local/bin"]
  * ```
  */
 declare function typeList<Value>(elementType: Type<Value>, separator?: string): Type<Array<Value>>;
 
 /**
- * A CLI option (flag or valued) with its parsing and usage-generation logic.
- *
- * Created with {@link optionFlag}, {@link optionSingleValue}, or
- * {@link optionRepeatable} and passed via the `options` map of {@link operation}.
- *
- * @typeParam Value - Decoded value type.
+ * Color names for terminal styling, used by {@link TypoStyle}.
+ * `dark*` = standard ANSI (30–37); `bright*` = high-intensity (90–97).
  */
-type Option<Value> = {
+type TypoColor = "darkBlack" | "darkRed" | "darkGreen" | "darkYellow" | "darkBlue" | "darkMagenta" | "darkCyan" | "darkWhite" | "brightBlack" | "brightRed" | "brightGreen" | "brightYellow" | "brightBlue" | "brightMagenta" | "brightCyan" | "brightWhite";
+/**
+ * Visual styling applied by a {@link TypoSupport} instance.
+ * All fields are optional; ignored entirely in `"none"` mode.
+ */
+type TypoStyle = {
     /**
-     * Returns metadata used to render the `Options:` section of help.
+     * Letter case.
      */
-    generateUsage(): OptionUsage;
+    case?: "upper" | "lower";
     /**
-     * Registers the option on `readerOptions` and returns an {@link OptionDecoder}.
+     * Foreground (text) color.
      */
-    registerAndMakeDecoder(readerOptions: ReaderArgs): OptionDecoder<Value>;
-};
-/**
- * Produced by {@link Option.registerAndMakeDecoder}.
- *
- * @typeParam Value - Decoded value type.
- */
-type OptionDecoder<Value> = {
+    fgColor?: TypoColor;
     /**
-     * Returns the decoded option value.
-     *
-     * @throws {@link TypoError} if decoding failed.
+     * Background color.
      */
-    getAndDecodeValue(): Value;
-};
-/**
- * Human-readable metadata for a single option, used to render the `Options:` section
- * of the help output produced by {@link usageToStyledLines}.
- */
-type OptionUsage = {
+    bgColor?: TypoColor;
     /**
-     * Long-form name without `--` (e.g. `"verbose"`).
+     * Reduced intensity.
      */
-    long: Lowercase<string>;
+    dim?: boolean;
     /**
-     * Short-form name without `-` (e.g. `"v"`).
+     * Bold.
      */
-    short: string | undefined;
+    bold?: boolean;
     /**
-     * Help text in usage.
+     * Italic.
      */
-    description: string | undefined;
+    italic?: boolean;
     /**
-     * Short note shown in parentheses.
+     * Underline.
      */
-    hint: string | undefined;
+    underline?: boolean;
     /**
-     * Value placeholder in help (e.g. `"<FILE>"`). `undefined` for flags.
+     * Strikethrough.
      */
-    label: Uppercase<string> | undefined;
+    strikethrough?: boolean;
 };
 /**
- * Creates a boolean flag option (`--verbose`, optionally `--flag=no`).
- *
- * Parsing: absent → `false`; `--flag` / `--flag=yes` → `true`; `--flag=no` → `false`;
- * specified more than once → {@link TypoError}.
- *
- * @param definition - Flag configuration.
- * @param definition.long - Long-form name (without `--`).
- * @param definition.short - Short-form name (without `-`).
- * @param definition.description - Help text.
- * @param definition.hint - Short note shown in parentheses.
- * @param definition.aliases - Additional names.
- * @param definition.default - Default when absent. Defaults to `() => false`.
- * @returns An {@link Option}`<boolean>`.
- *
- * @example
- * ```ts
- * const verboseFlag = optionFlag({
- *   long: "verbose",
- *   short: "v",
- *   description: "Enable verbose output",
- * });
- * ```
+ * Section title style. Bold dark-green.
  */
-declare function optionFlag(definition: {
-    long: Lowercase<string>;
-    short?: string;
-    description?: string;
-    hint?: string;
-    aliases?: {
-        longs?: Array<Lowercase<string>>;
-        shorts?: Array<string>;
-    };
-    default?: () => boolean;
-}): Option<boolean>;
+declare const typoStyleTitle: TypoStyle;
 /**
- * Creates an option that accepts exactly one value (e.g. `--output dist/`).
- *
- * Parsing: absent → `default()`; once → decoded with `type`; more than once → {@link TypoError}.
- * Value syntax: `--long value`, `--long=value`, `-s value`, `-s=value`, `-svalue`.
- *
- * @typeParam Value - Type produced by the decoder.
- *
- * @param definition - Option configuration.
- * @param definition.long - Long-form name (without `--`).
- * @param definition.short - Short-form name (without `-`).
- * @param definition.description - Help text.
- * @param definition.hint - Short note shown in parentheses.
- * @param definition.aliases - Additional names.
- * @param definition.label - Value placeholder in help. Defaults to uppercased `type.content`.
- * @param definition.type - Decoder for the raw string value.
- * @param definition.default - Default when absent. Throw to make the option required.
- * @returns An {@link Option}`<Value>`.
- *
- * @example
- * ```ts
- * const outputOption = optionSingleValue({
- *   long: "output",
- *   short: "o",
- *   type: typeString,
- *   label: "PATH",
- *   description: "Output directory",
- *   default: () => "dist/",
- * });
- * ```
+ * Logic/type identifier style. Bold dark-magenta.
  */
-declare function optionSingleValue<Value>(definition: {
-    long: Lowercase<string>;
-    short?: string;
-    description?: string;
-    hint?: string;
-    aliases?: {
-        longs?: Array<Lowercase<string>>;
-        shorts?: Array<string>;
-    };
-    label?: Uppercase<string>;
-    type: Type<Value>;
-    default: () => Value;
-}): Option<Value>;
+declare const typoStyleLogic: TypoStyle;
 /**
- * Creates an option that collects every occurrence into an array (e.g. `--file a.ts --file b.ts`).
- *
- * Parsing: absent → `[]`; N occurrences → array of N decoded values in order.
- * Value syntax: `--long value`, `--long=value`, `-s value`, `-s=value`, `-svalue`.
- *
- * @typeParam Value - Type produced by the decoder for each occurrence.
- *
- * @param definition - Option configuration.
- * @param definition.long - Long-form name (without `--`).
- * @param definition.short - Short-form name (without `-`).
- * @param definition.description - Help text.
- * @param definition.hint - Short note shown in parentheses.
- * @param definition.aliases - Additional names.
- * @param definition.label - Value placeholder in help. Defaults to uppercased `type.content`.
- * @param definition.type - Decoder applied to each raw string value.
- * @returns An {@link Option}`<Array<Value>>`.
- *
- * @example
- * ```ts
- * const filesOption = optionRepeatable({
- *   long: "file",
- *   short: "f",
- *   type: typeString,
- *   label: "PATH",
- *   description: "Input file (may be repeated)",
- * });
- * // Usage: my-cli --file a.ts --file b.ts  →  ["a.ts", "b.ts"]
- * ```
+ * Quoted user-input style. Bold dark-yellow.
  */
-declare function optionRepeatable<Value>(definition: {
-    long: Lowercase<string>;
-    short?: string;
-    description?: string;
-    hint?: string;
-    aliases?: {
-        longs?: Array<Lowercase<string>>;
-        shorts?: Array<string>;
-    };
-    label?: Uppercase<string>;
-    type: Type<Value>;
-}): Option<Array<Value>>;
-
+declare const typoStyleQuote: TypoStyle;
 /**
- * A bare (non-option) positional argument with its parsing and usage-generation logic.
- *
- * Created with {@link positionalRequired}, {@link positionalOptional}, or
- * {@link positionalVariadics} and passed via the `positionals` array of
- * {@link operation}, consumed in declaration order.
- *
- * @typeParam Value - Decoded value type.
+ * Error label style. Bold dark-red.
  */
-type Positional<Value> = {
+declare const typoStyleFailure: TypoStyle;
+/**
+ * Option/command name style. Bold dark-cyan.
+ */
+declare const typoStyleConstants: TypoStyle;
+/**
+ * Positional/user-input label style. Bold dark-blue.
+ */
+declare const typoStyleUserInput: TypoStyle;
+/**
+ * Strong text style. Bold.
+ */
+declare const typoStyleRegularStrong: TypoStyle;
+/**
+ * Subtle text style. Italic and dim.
+ */
+declare const typoStyleRegularWeaker: TypoStyle;
+/**
+ * Immutable styled string segment. Compose into a {@link TypoText}.
+ */
+declare class TypoString {
+    #private;
     /**
-     * Returns metadata used to render the `Positionals:` section of help.
+     * @param value - Raw text content.
+     * @param typoStyle - Style to apply when rendering. Defaults to `{}` (no style).
      */
-    generateUsage(): PositionalUsage;
+    constructor(value: string, typoStyle?: TypoStyle);
     /**
-     * Consumes the next positional token from `readerPositionals`.
-     * Returns a decoder that produces the final value.
+     * Returns the text styled by `typoSupport`.
+     *
+     * @param typoSupport - Rendering mode.
      */
-    consumeAndMakeDecoder(readerPositionals: ReaderPositionals): PositionalDecoder<Value>;
-};
+    computeStyledString(typoSupport: TypoSupport): string;
+    /**
+     * Returns the raw text.
+     */
+    getRawString(): string;
+}
 /**
- * Produced by {@link Positional.consumeAndMakeDecoder}.
- *
- * @typeParam Value - Decoded value type.
+ * Mutable sequence of {@link TypoString} segments.
  */
-type PositionalDecoder<Value> = {
+declare class TypoText {
+    #private;
     /**
-     * Returns the decoded positional value.
+     * @param segments - Initial text segments
+     */
+    constructor(...segments: Array<TypoText | Array<TypoString> | TypoString | string>);
+    /**
+     * Appends new text segment(s).
      *
-     * @throws {@link TypoError} if decoding failed.
+     * @param segment - Text segment(s) to append.
      */
-    decodeValue(): Value;
-};
-/**
- * Human-readable metadata for a single positional argument, used to render the
- * `Positionals:` section of the help output produced by {@link usageToStyledLines}.
- */
-type PositionalUsage = {
+    push(segment: TypoText | Array<TypoString> | TypoString | string): void;
     /**
-     * Help text.
+     * Renders all segments into a single styled string.
+     *
+     * @param typoSupport - Rendering mode.
+     * @returns Concatenated styled string.
      */
-    description: string | undefined;
+    computeStyledString(typoSupport: TypoSupport): string;
     /**
-     * Short note shown in parentheses.
+     * Returns the concatenated raw text.
      */
-    hint: string | undefined;
+    computeRawString(): string;
     /**
-     * Placeholder label shown in the usage line and the `Positionals:` section.
-     * Required: `<NAME>`, optional: `[NAME]`, variadic: `[NAME]...`.
+     * Returns the total raw character count.
      */
-    label: Uppercase<string>;
-};
+    computeRawLength(): number;
+}
 /**
- * Creates a required positional — missing token throws {@link TypoError}.
- * Label defaults to uppercased `type.content` in angle brackets (e.g. `<STRING>`).
- *
- * @typeParam Value - Type produced by the decoder.
- *
- * @param definition - Positional configuration.
- * @param definition.description - Help text.
- * @param definition.hint - Short note shown in parentheses.
- * @param definition.label - Label without brackets; defaults to uppercased `type.content`.
- * @param definition.type - Decoder for the raw token.
- * @returns A {@link Positional}`<Value>`.
- *
- * @example
- * ```ts
- * const namePositional = positionalRequired({
- *   type: typeString,
- *   label: "NAME",
- *   description: "The name to greet",
- * });
- * // Parses: my-cli Alice  →  "Alice"
- * ```
+ * Column-aligned grid of {@link TypoText} cells.
+ * Each column is padded to the widest cell (raw chars); the last column is not padded.
  */
-declare function positionalRequired<Value>(definition: {
-    description?: string;
-    hint?: string;
-    label?: Uppercase<string>;
-    type: Type<Value>;
-}): Positional<Value>;
+declare class TypoGrid {
+    #private;
+    constructor();
+    /**
+     * Appends a row. All rows should have the same cell count.
+     *
+     * @param cells - Ordered {@link TypoText} cells.
+     */
+    pushRow(cells: Array<TypoText>): void;
+    /**
+     * Renders as an array of styled, column-padded strings.
+     *
+     * @param typoSupport - Rendering mode.
+     * @returns Array of styled strings.
+     */
+    computeStyledLines(typoSupport: TypoSupport): Array<string>;
+}
 /**
- * Creates an optional positional — absent token falls back to `default()`.
- * Label defaults to uppercased `type.content` in square brackets (e.g. `[STRING]`).
- *
- * @typeParam Value - Type produced by the decoder (or the default).
+ * `Error` subclass with a {@link TypoText} styled message for rich terminal output.
+ * Chains `TypoError` sources after `": "`.
+ */
+declare class TypoError extends Error {
+    #private;
+    /**
+     * @param currentTypoText - Styled message for this error.
+     * @param source - Optional cause; `TypoError` chains styled text, `Error` appends `.message`, else `String()`.
+     */
+    constructor(currentTypoText: TypoText, source?: unknown);
+    /**
+     * Renders the styled message (without `"Error:"` prefix).
+     *
+     * @param typoSupport - Rendering mode.
+     * @returns Styled error string.
+     */
+    computeStyledString(typoSupport: TypoSupport): string;
+    /**
+     * Runs `thrower`; wraps any thrown error as a `TypoError` with `context()` prepended.
+     *
+     * @typeParam Value - Return type of `thrower`.
+     * @param thrower - Function to execute; result passed through on success.
+     * @param context - Produces the {@link TypoText} prepended to the caught error.
+     * @returns Value from `thrower`.
+     * @throws `TypoError` wrapping the original error with context prepended.
+     */
+    static tryWithContext<Value>(thrower: () => Value, context: () => TypoText): Value;
+}
+/**
+ * Controls ANSI terminal styling. Create via the static factory methods.
+ */
+declare class TypoSupport {
+    #private;
+    private constructor();
+    /**
+     * Plain text — no ANSI codes.
+     */
+    static none(): TypoSupport;
+    /**
+     * ANSI escape codes for color terminals.
+     */
+    static tty(): TypoSupport;
+    /**
+     * Deterministic textual styling for snapshot tests.
+     */
+    static mock(): TypoSupport;
+    /**
+     * Auto-detects styling mode from the process environment on best-effort basis.
+     */
+    static inferFromEnv(): TypoSupport;
+    /**
+     * Applies `typoStyle` to `value` according to the current mode.
+     *
+     * @param value - Raw text.
+     * @param typoStyle - Style to apply.
+     * @returns Styled string.
+     */
+    computeStyledString(value: string, typoStyle: TypoStyle): string;
+    /**
+     * Formats any thrown value as `"Error: <message>"` with {@link typoStyleFailure} on the prefix.
+     *
+     * @param error - Any thrown value.
+     * @returns Styled error string.
+     */
+    computeStyledErrorMessage(error: unknown): string;
+}
+
+/**
+ * Usage model. Produced by {@link CommandDecoder.generateUsage}, consumed by {@link usageToStyledLines}.
+ */
+type UsageCommand = {
+    /**
+     * Segments of the usage line
+     */
+    segments: Array<{
+        positional: string;
+    } | {
+        subcommand: string;
+    }>;
+    /**
+     * Command metadata.
+     */
+    information: CommandInformation;
+    /**
+     * Positionals in declaration order.
+     */
+    positionals: Array<UsagePositional>;
+    /**
+     * Subcommands, populated when none was selected.
+     */
+    subcommands: Array<UsageSubcommand>;
+    /**
+     * Options in registration order.
+     */
+    options: Array<UsageOption>;
+};
+/**
+ * Positional metadata for the `Positionals:` section of help.
+ */
+type UsagePositional = {
+    /**
+     * Help text.
+     */
+    description?: string | undefined;
+    /**
+     * Short note shown in parentheses.
+     */
+    hint?: string | undefined;
+    /**
+     * Placeholder label shown in the usage line and the `Positionals:` section.
+     */
+    label: string;
+};
+/**
+ * Entry in the `Subcommands:` section.
+ */
+type UsageSubcommand = {
+    /**
+     * Token the user types (e.g. `"deploy"`).
+     */
+    name: string;
+    /**
+     * From {@link CommandInformation.description}.
+     */
+    description?: string | undefined;
+    /**
+     * From {@link CommandInformation.hint}.
+     */
+    hint?: string | undefined;
+};
+/**
+ * Option metadata for the `Options:` section of help.
+ */
+type UsageOption = {
+    /**
+     * Short-form name without `-` (e.g. `"v"`).
+     */
+    short?: string | undefined;
+    /**
+     * Long-form name without `--` (e.g. `"verbose"`).
+     */
+    long: string;
+    /**
+     * Value placeholder in help (e.g. `"<FILE>"`).
+     */
+    label?: string | undefined;
+    /**
+     * Extra annotation appended to the option label in help.
+     */
+    annotation?: string | undefined;
+    /**
+     * Help text.
+     */
+    description?: string | undefined;
+    /**
+     * Short note shown in parentheses.
+     */
+    hint?: string | undefined;
+};
+/**
+ * Converts a {@link UsageCommand} model into an array of styled lines ready to be
+ * joined with `"\n"` and printed to the terminal.
+ *
+ * The output format is:
+ * ```
+ * Usage: <cliName> [segments...]
+ *
+ * <description> (<hint>)
+ * <detail lines...>
+ *
+ * Positionals:
+ *   <LABEL>  <description> (<hint>)
+ *
+ * Subcommands:
+ *   <name>  <description> (<hint>)
+ *
+ * Options:
+ *   -s, --long <LABEL><annotation>  <description> (<hint>)
+ *
+ * Examples:
+ *   <description>
+ *   <command line>
+ *
+ * ```
+ * Sections that have no entries are omitted. The trailing empty line is always included.
+ *
+ * Column alignment per section via {@link TypoGrid}.
+ *
+ * @param params.cliName - Program name for the usage line.
+ * @param params.usage - From {@link CommandDecoder.generateUsage}.
+ * @param params.typoSupport - Rendering mode.
+ * @returns Styled lines; includes a trailing empty string.
+ *
+ * @example
+ * ```ts
+ * const lines = usageToStyledLines({
+ *   cliName: "my-cli",
+ *   usage: commandDecoder.generateUsage(),
+ *   typoSupport: TypoSupport.tty(),
+ * });
+ * process.stdout.write(lines.join("\n"));
+ * ```
+ */
+declare function usageToStyledLines(params: {
+    cliName: string;
+    usage: UsageCommand;
+    typoSupport: TypoSupport;
+}): string[];
+
+/**
+ * A CLI option. Created with {@link optionFlag}, {@link optionSingleValue},
+ * or {@link optionRepeatable}.
+ *
+ * @typeParam Value - Decoded value type.
+ */
+type Option<Value> = {
+    /**
+     * Returns metadata for the `Options:` section.
+     */
+    generateUsage(): UsageOption;
+    /**
+     * Registers the option on `readerOptions` and returns an {@link OptionDecoder}.
+     */
+    registerAndMakeDecoder(readerOptions: ReaderArgs): OptionDecoder<Value>;
+};
+/**
+ * Produced by {@link Option.registerAndMakeDecoder}.
+ *
+ * @typeParam Value - Decoded value type.
+ */
+type OptionDecoder<Value> = {
+    /**
+     * Returns the decoded option value.
+     *
+     * @throws {@link TypoError} if decoding failed.
+     */
+    getAndDecodeValue(): Value;
+};
+/**
+ * Creates a boolean flag option (`--verbose`, optionally `--flag=no`).
+ *
+ * Parsing: absent → default value; `--flag` / `--flag=yes` → `true`; `--flag=no` → `false`;
+ * specified more than once → throws {@link TypoError}.
+ *
+ * @param definition.long - Long-form name (without `--`).
+ * @param definition.short - Short-form name (without `-`).
+ * @param definition.description - Help text.
+ * @param definition.hint - Short note shown in parentheses.
+ * @param definition.aliases - Additional names.
+ * @param definition.default - Default value when absent.
+ * @returns An {@link Option}`<boolean>`.
+ *
+ * @example
+ * ```ts
+ * const verboseFlag = optionFlag({
+ *   long: "verbose",
+ *   short: "v",
+ *   description: "Enable verbose output",
+ * });
+ * // Usage:
+ * //   my-cli  →  false
+ * //   my-cli --verbose  →  true
+ * //   my-cli --verbose=yes  →  true
+ * //   my-cli -v=no  →  false
+ * ```
+ */
+declare function optionFlag(definition: {
+    long: string;
+    short?: string;
+    description?: string;
+    hint?: string;
+    aliases?: {
+        longs?: Array<string>;
+        shorts?: Array<string>;
+    };
+    default?: boolean;
+}): Option<boolean>;
+/**
+ * Creates an option that accepts exactly one value (e.g. `--output dist/`).
+ *
+ * Parsing: absent → `defaultValue()`; once → decoded with `type`; more than once → {@link TypoError}.
+ * Value syntax: `--long value`, `--long=value`, `-s value`, `-s=value`, `-svalue`.
+ *
+ * @typeParam Value - Type produced by the decoder.
+ *
+ * @param definition.long - Long-form name (without `--`).
+ * @param definition.short - Short-form name (without `-`).
+ * @param definition.description - Help text.
+ * @param definition.hint - Short note shown in parentheses.
+ * @param definition.aliases - Additional names.
+ * @param definition.type - Decoder for the raw string value.
+ * @param definition.valueWhenNotDefined - Default value when the option is not specified at all.
+ * @param definition.valueWhenNotInlined - Default value when the option is specified without an inline value (e.g. `--option` or `-o`).
+ * @returns An {@link Option}`<Value>`.
+ *
+ * @example
+ * ```ts
+ * const outputOption = optionSingleValue({
+ *   long: "output",
+ *   short: "o",
+ *   type: typePath(),
+ *   description: "Output directory",
+ *   valueWhenNotDefined: () => "dist",
+ * });
+ * // Usage:
+ * //   my-cli  →  "dist"
+ * //   my-cli --output folder  →  "folder"
+ * //   my-cli -o folder  →  "folder"
+ * ```
+ */
+declare function optionSingleValue<Value>(definition: {
+    long: string;
+    short?: string;
+    description?: string;
+    hint?: string;
+    aliases?: {
+        longs?: Array<string>;
+        shorts?: Array<string>;
+    };
+    type: Type<Value>;
+    defaultWhenNotDefined: () => Value;
+    defaultWhenNotInlined?: () => Value;
+}): Option<Value>;
+/**
+ * Creates an option that collects every occurrence into an array (e.g. `--file a.ts --file b.ts`).
+ *
+ * Parsing: absent → `[]`; N occurrences → array of N decoded values in order.
+ * Value syntax: `--long value`, `--long=value`, `-s value`, `-s=value`, `-svalue`.
+ *
+ * @typeParam Value - Type produced by the decoder for each occurrence.
+ *
+ * @param definition.long - Long-form name (without `--`).
+ * @param definition.short - Short-form name (without `-`).
+ * @param definition.description - Help text.
+ * @param definition.hint - Short note shown in parentheses.
+ * @param definition.aliases - Additional names.
+ * @param definition.type - Decoder applied to each raw string value.
+ * @returns An {@link Option}`<Array<Value>>`.
+ *
+ * @example
+ * ```ts
+ * const filesOption = optionRepeatable({
+ *   long: "file",
+ *   short: "f",
+ *   type: typeString,
+ *   label: "PATH",
+ *   description: "Input file (may be repeated)",
+ * });
+ * // Usage: my-cli --file a.ts --file b.ts  →  ["a.ts", "b.ts"]
+ * ```
+ */
+declare function optionRepeatable<Value>(definition: {
+    long: string;
+    short?: string;
+    description?: string;
+    hint?: string;
+    aliases?: {
+        longs?: Array<string>;
+        shorts?: Array<string>;
+    };
+    type: Type<Value>;
+}): Option<Array<Value>>;
+
+/**
+ * A positional argument. Created with {@link positionalRequired}, {@link positionalOptional},
+ * or {@link positionalVariadics}.
+ *
+ * @typeParam Value - Decoded value type.
+ */
+type Positional<Value> = {
+    /**
+     * Returns metadata for the `Positionals:` section.
+     */
+    generateUsage(): UsagePositional;
+    /**
+     * Consumes the next positional token from `readerPositionals`.
+     * Returns a decoder that produces the final value.
+     */
+    consumeAndMakeDecoder(readerPositionals: ReaderPositionals): PositionalDecoder<Value>;
+};
+/**
+ * Produced by {@link Positional.consumeAndMakeDecoder}.
+ *
+ * @typeParam Value - Decoded value type.
+ */
+type PositionalDecoder<Value> = {
+    /**
+     * Returns the decoded positional value.
+     *
+     * @throws {@link TypoError} if decoding failed.
+     */
+    decodeValue(): Value;
+};
+/**
+ * Creates a required positional — missing token throws {@link TypoError}.
+ *
+ * @typeParam Value - Type produced by the decoder.
+ *
+ * @param definition.description - Help text.
+ * @param definition.hint - Short note shown in parentheses.
+ * @param definition.type - Decoder for the raw token.
+ * @returns A {@link Positional}`<Value>`.
+ *
+ * @example
+ * ```ts
+ * const namePositional = positionalRequired({
+ *   type: type("name"),
+ *   description: "The name to greet",
+ * });
+ * // Usage:
+ * //   my-cli Alice  →  "Alice"
+ * ```
+ */
+declare function positionalRequired<Value>(definition: {
+    description?: string;
+    hint?: string;
+    type: Type<Value>;
+}): Positional<Value>;
+/**
+ * Creates an optional positional — absent token falls back to `default()`.
+ *
+ * @typeParam Value - Type produced by the decoder (or the default).
  *
- * @param definition - Positional configuration.
  * @param definition.description - Help text.
  * @param definition.hint - Short note shown in parentheses.
- * @param definition.label - Label without brackets; defaults to uppercased `type.content`.
  * @param definition.type - Decoder for the raw token.
  * @param definition.default - Value when absent. Throw to make it required.
  * @returns A {@link Positional}`<Value>`.
@@ -557,52 +878,48 @@ declare function positionalRequired<Value>(definition: {
  * @example
  * ```ts
  * const greeteePositional = positionalOptional({
- *   type: typeString,
- *   label: "NAME",
+ *   type: type("name"),
  *   description: "Name to greet (default: world)",
  *   default: () => "world",
  * });
- * // my-cli         →  "world"
- * // my-cli Alice   →  "Alice"
+ * // Usage:
+ * //   my-cli  →  "world"
+ * //   my-cli Alice  →  "Alice"
  * ```
  */
 declare function positionalOptional<Value>(definition: {
     description?: string;
     hint?: string;
-    label?: Uppercase<string>;
     type: Type<Value>;
     default: () => Value;
 }): Positional<Value>;
 /**
  * Creates a variadic positional that collects zero or more remaining tokens into an array.
- * Stops at `endDelimiter` (consumed, not included). Label: `[TYPE]...` notation.
+ * Optionally stops at `endDelimiter` (consumed, not included).
  *
  * @typeParam Value - Type produced by the decoder for each token.
  *
- * @param definition - Positional configuration.
  * @param definition.endDelimiter - Sentinel token that stops collection (consumed, not included).
  * @param definition.description - Help text.
  * @param definition.hint - Short note shown in parentheses.
- * @param definition.label - Label without brackets; defaults to uppercased `type.content`.
  * @param definition.type - Decoder applied to each token.
  * @returns A {@link Positional}`<Array<Value>>`.
  *
  * @example
  * ```ts
  * const filesPositional = positionalVariadics({
- *   type: typeString,
- *   label: "FILE",
+ *   type: typePath(),
  *   description: "Files to process",
  * });
- * // my-cli a.ts b.ts c.ts  →  ["a.ts", "b.ts", "c.ts"]
- * // my-cli                  →  []
+ * // Usage:
+ * //   my-cli  →  []
+ * //   my-cli a.ts b.ts c.ts  →  ["a.ts", "b.ts", "c.ts"]
  * ```
  */
 declare function positionalVariadics<Value>(definition: {
     endDelimiter?: string;
     description?: string;
     hint?: string;
-    label?: Uppercase<string>;
     type: Type<Value>;
 }): Positional<Array<Value>>;
 
@@ -612,14 +929,23 @@ declare function positionalVariadics<Value>(definition: {
  * Created with {@link operation} and passed to {@link command},
  * {@link commandWithSubcommands}, or {@link commandChained}.
  *
- * @typeParam Context - Injected at execution time; forwarded to handlers. Use to inject dependencies.
- * @typeParam Result - Value produced on execution; typically `void` for leaf commands.
+ * @typeParam Context - Injected at execution; forwarded to handlers.
+ * @typeParam Result - Value produced on execution; typically `void`.
  */
 type Operation<Context, Result> = {
     /**
      * Returns usage metadata without consuming any arguments.
      */
-    generateUsage(): OperationUsage;
+    generateUsage(): {
+        /**
+         * Registered options.
+         */
+        options: Array<UsageOption>;
+        /**
+         * Declared positionals, in order.
+         */
+        positionals: Array<UsagePositional>;
+    };
     /**
      * Consumes args from `readerArgs` and returns an {@link OperationDecoder}.
      */
@@ -651,26 +977,10 @@ type OperationInterpreter<Context, Result> = {
      */
     executeWithContext(context: Context): Promise<Result>;
 };
-/**
- * Usage metadata produced by {@link Operation.generateUsage}.
- * Consumed when building {@link CommandUsage}.
- */
-type OperationUsage = {
-    /**
-     * Usage descriptors for all registered options.
-     */
-    options: Array<OptionUsage>;
-    /**
-     * Usage descriptors for all declared positionals, in order.
-     */
-    positionals: Array<PositionalUsage>;
-};
 /**
  * Creates an {@link Operation} from options, positionals, and an async handler.
  *
- * The `handler` receives the parent `context` and an `inputs` object with
- * `options` (keyed by the same names declared in `inputs.options`) and
- * `positionals` (a tuple in declaration order).
+ * The `handler` receives `context` and `inputs` with decoded `options` and `positionals`.
  *
  * @typeParam Context - Context type accepted by the handler.
  * @typeParam Result - Return type of the handler.
@@ -681,20 +991,20 @@ type OperationUsage = {
  * @param inputs.options - Map of keys to {@link Option} descriptors.
  * @param inputs.positionals - Ordered array of {@link Positional} descriptors.
  * @param handler - Async function implementing the command logic.
- * @returns An {@link Operation} ready to be composed into a command.
+ * @returns An {@link Operation}.
  *
  * @example
  * ```ts
  * const greetOperation = operation(
  *   {
  *     options: {
- *       loud: optionFlag({ long: "loud", description: "Print in uppercase" }),
+ *       loud: optionFlag({ long: "loud", description: "Print in uppercase", default: false }),
  *     },
  *     positionals: [
- *       positionalRequired({ type: typeString, label: "NAME", description: "Name to greet" }),
+ *       positionalRequired({ type: type("name"), description: "Name to greet" }),
  *     ],
  *   },
- *   async (_ctx, { options: { loud }, positionals: [name] }) => {
+ *   async function (_ctx, { options: { loud }, positionals: [name] }) {
  *     const message = `Hello, ${name}!`;
  *     console.log(loud ? message.toUpperCase() : message);
  *   },
@@ -716,20 +1026,18 @@ declare function operation<Context, Result, Options extends {
 }) => Promise<Result>): Operation<Context, Result>;
 
 /**
- * A CLI command — parses arguments and executes within a given context.
- * Created with {@link command}, {@link commandWithSubcommands}, or {@link commandChained}.
- * Usually passed through {@link runAndExit} to run.
+ * A CLI command. Created with {@link command}, {@link commandWithSubcommands}, or {@link commandChained}.
  *
- * @typeParam Context - Injected at execution time; forwarded to handlers. Use to inject dependencies.
- * @typeParam Result - Value produced on execution; typically `void` for leaf commands.
+ * @typeParam Context - Injected at execution; forwarded to handlers.
+ * @typeParam Result - Produced on execution; typically `void`.
  */
 type Command<Context, Result> = {
     /**
-     * Returns the command's static metadata.
+     * Returns static metadata.
      */
     getInformation(): CommandInformation;
     /**
-     * Consumes args in a `readerArgs` and returns a {@link CommandDecoder}.
+     * Registers options/positionals on `readerArgs`; returns a {@link CommandDecoder}.
      */
     consumeAndMakeDecoder(readerArgs: ReaderArgs): CommandDecoder<Context, Result>;
 };
@@ -741,10 +1049,9 @@ type Command<Context, Result> = {
  */
 type CommandDecoder<Context, Result> = {
     /**
-     * Builds the {@link CommandUsage} for the current command path.
-     * Used for `--help` and `usageOnError`.
+     * Returns {@link UsageCommand} for the current command path.
      */
-    generateUsage(): CommandUsage;
+    generateUsage(): UsageCommand;
     /**
      * Creates a ready-to-execute {@link CommandInterpreter}.
      *
@@ -755,7 +1062,7 @@ type CommandDecoder<Context, Result> = {
 /**
  * A fully parsed, decoded and ready-to-execute command.
  *
- * @typeParam Context - Caller-supplied context.
+ * @typeParam Context - Context passed to the handler.
  * @typeParam Result - Value produced on success.
  */
 type CommandInterpreter<Context, Result> = {
@@ -765,15 +1072,15 @@ type CommandInterpreter<Context, Result> = {
     executeWithContext(context: Context): Promise<Result>;
 };
 /**
- * Static metadata for a command, shown in `--help` output via {@link usageToStyledLines}.
+ * Command metadata shown in `--help` output.
  */
 type CommandInformation = {
     /**
-     * Short description shown in the usage header.
+     * Shown in the usage header.
      */
     description: string;
     /**
-     * Short note shown in parentheses (e.g. `"deprecated"`, `"experimental"`).
+     * Shown in parentheses, e.g. `"deprecated"`, `"experimental"`.
      */
     hint?: string;
     /**
@@ -781,7 +1088,7 @@ type CommandInformation = {
      */
     details?: Array<string>;
     /**
-     * Examples shown in the `Examples:` section of the usage output.
+     * Shown in the `Examples:` section.
      */
     examples?: Array<{
         /**
@@ -789,7 +1096,7 @@ type CommandInformation = {
          */
         explanation: string;
         /**
-         * Command line args to show as an example of usage.
+         * Example command args.
          */
         commandArgs: Array<string | {
             positional: string;
@@ -798,75 +1105,24 @@ type CommandInformation = {
         } | {
             option: {
                 long: string;
-                value?: string;
+                inlined?: string;
+                separated?: Array<string>;
             } | {
                 short: string;
-                value?: string;
+                inlined?: string;
+                separated?: Array<string>;
             };
         }>;
     }>;
 };
-/**
- * Full usage/help model.
- * Produced by {@link CommandDecoder.generateUsage},
- * Consumed by {@link usageToStyledLines}.
- */
-type CommandUsage = {
-    /**
-     * Segments forming the usage line
-     * (e.g. `my-cli <POSITIONAL> subcommand <ANOTHER_POSITIONAL>`).
-     */
-    segments: Array<CommandUsageSegment>;
-    /**
-     * Command's static metadata.
-     */
-    information: CommandInformation;
-    /**
-     * Positionals in declaration order.
-     */
-    positionals: Array<PositionalUsage>;
-    /**
-     * Available subcommands. Non-empty when subcommand was not specified.
-     */
-    subcommands: Array<CommandUsageSubcommand>;
-    /**
-     * Options in registration order.
-     */
-    options: Array<OptionUsage>;
-};
-/**
- * One element in the usage segment trail.
- */
-type CommandUsageSegment = {
-    positional: string;
-} | {
-    command: string;
-};
-/**
- * Subcommand entry shown in the `Subcommands:` section of the usage output.
- */
-type CommandUsageSubcommand = {
-    /**
-     * Literal token the user types (e.g. `"deploy"`).
-     */
-    name: string;
-    /**
-     * Short description from the subcommand's {@link CommandInformation}.
-     */
-    description: string | undefined;
-    /**
-     * Hint from the subcommand's {@link CommandInformation}.
-     */
-    hint: string | undefined;
-};
 /**
  * Creates a leaf command that directly executes an {@link Operation}.
  *
  * @typeParam Context - Context forwarded to the handler.
  * @typeParam Result - Value returned by the handler.
  *
- * @param information - Command metadata (description, hint, details).
- * @param operation - Defines: options, positionals, and the handler.
+ * @param information - Command metadata.
+ * @param operation - Options, positionals, and handler.
  * @returns A {@link Command}.
  *
  * @example
@@ -874,7 +1130,7 @@ type CommandUsageSubcommand = {
  * const greet = command(
  *   { description: "Greet a user" },
  *   operation(
- *     { options: {}, positionals: [positionalRequired({ type: typeString, label: "NAME" })] },
+ *     { options: {}, positionals: [positionalRequired({ type: type("name") })] },
  *     async (_ctx, { positionals: [name] }) => console.log(`Hello, ${name}!`),
  *   ),
  * );
@@ -882,17 +1138,16 @@ type CommandUsageSubcommand = {
  */
 declare function command<Context, Result>(information: CommandInformation, operation: Operation<Context, Result>): Command<Context, Result>;
 /**
- * Creates a command that runs an {@link Operation} to produce a `Payload`,
- * then dispatches to a named subcommand based on the next positional token.
+ * Creates a command that runs `operation` first, then dispatches to a named subcommand.
  *
  * @typeParam Context - Context accepted by `operation`.
  * @typeParam Payload - Output of `operation`; becomes the subcommand's context.
  * @typeParam Result - Value produced by the selected subcommand.
  *
- * @param information - Command metadata (description, hint, details).
- * @param operation - Always runs first; its output becomes the subcommand's context.
+ * @param information - Command metadata.
+ * @param operation - Runs first; output becomes the subcommand's context.
  * @param subcommands - Map of subcommand names to their {@link Command}s.
- * @returns A {@link Command} that dispatches to one of the provided subcommands.
+ * @returns A dispatching {@link Command}.
  *
  * @example
  * ```ts
@@ -907,7 +1162,7 @@ declare function command<Context, Result>(information: CommandInformation, opera
  * ```
  */
 declare function commandWithSubcommands<Context, Payload, Result>(information: CommandInformation, operation: Operation<Context, Payload>, subcommands: {
-    [subcommand: Lowercase<string>]: Command<Payload, Result>;
+    [subcommand: string]: Command<Payload, Result>;
 }): Command<Context, Result>;
 /**
  * Chains an {@link Operation} and a {@link Command}: `operation` runs first, its
@@ -917,22 +1172,10 @@ declare function commandWithSubcommands<Context, Payload, Result>(information: C
  * @typeParam Payload - Output of `operation`; becomes `subcommand`'s context.
  * @typeParam Result - Value produced by `subcommand`.
  *
- * @param information - Command metadata (description, hint, details).
- * @param operation - First stage; its output is passed as `subcommand`'s context.
- * @param subcommand - Second stage, executed after `operation`.
- * @returns A {@link Command} transparently composing the two stages.
- *
- * @example
- * ```ts
- * const authenticatedDeploy = commandChained(
- *   { description: "Authenticate then deploy" },
- *   operation(
- *     { options: { token: optionSingleValue({ long: "token", type: typeString, default: () => "" }) }, positionals: [] },
- *     async (_ctx, { options: { token } }) => ({ token }),
- *   ),
- *   command({ description: "Deploy" }, deployOperation),
- * );
- * ```
+ * @param information - Command metadata.
+ * @param operation - Runs first; output becomes `subcommand`'s context.
+ * @param subcommand - Runs after `operation`.
+ * @returns A {@link Command} composing both stages.
  */
 declare function commandChained<Context, Payload, Result>(information: CommandInformation, operation: Operation<Context, Payload>, subcommand: Command<Payload, Result>): Command<Context, Result>;
 
@@ -940,17 +1183,17 @@ declare function commandChained<Context, Payload, Result>(information: CommandIn
  * Main entry point: parses CLI arguments, executes the matched command, and exits.
  * Handles `--help`, `--version`, usage-on-error, and exit codes.
  *
- * Exit codes: `0` on success / `--help` / `--version`; `1` on parse or execution error.
+ * Exit codes:
+ *  - `0` on success / `--help` / `--version`
+ *  - `1` on parse error or execution error.
  *
- * @typeParam Context - Passed unchanged to the command handler; use to inject dependencies.
+ * @typeParam Context - Forwarded unchanged to the handler.
  *
  * @param cliName - Program name used in usage and `--version` output.
  * @param cliArgs - Raw arguments, typically `process.argv.slice(2)`.
- * @param context - Forwarded to the command handler, injected dependencies.
+ * @param context - Forwarded to the handler.
  * @param command - Root {@link Command}.
- * @param options - Optional runner configuration.
- * @param options.useTtyColors - Color mode: `true` (always), `false` (never),
- *   `"mock"` (snapshot-friendly), `undefined` (auto-detect from env).
+ * @param options.colorSetup - Configures color support; enables `--color` flag if set to `"flag"`.
  * @param options.usageOnHelp - Enables `--help` flag (default `true`).
  * @param options.usageOnError - Prints usage to stderr on parse error (default `true`).
  * @param options.buildVersion - Enables `--version`; prints `<cliName> <buildVersion>`.
@@ -961,13 +1204,13 @@ declare function commandChained<Context, Payload, Result>(information: CommandIn
  *
  * @example
  * ```ts
- * import { runAndExit, command, operation, positionalRequired, typeString } from "cli-kiss";
+ * import { runAndExit, command, operation, positionalRequired, type } from "cli-kiss";
  *
  * const greetCommand = command(
  *   { description: "Greet someone" },
  *   operation(
- *     { options: {}, positionals: [positionalRequired({ type: typeString, label: "NAME" })] },
- *     async (_ctx, { positionals: [name] }) => {
+ *     { options: {}, positionals: [positionalRequired({ type: type("name") })] },
+ *     async function (_ctx, { positionals: [name] }) {
  *       console.log(`Hello, ${name}!`);
  *     },
  *   ),
@@ -978,8 +1221,8 @@ declare function commandChained<Context, Payload, Result>(information: CommandIn
  * });
  * ```
  */
-declare function runAndExit<Context>(cliName: Lowercase<string>, cliArgs: ReadonlyArray<string>, context: Context, command: Command<Context, void>, options?: {
-    useTtyColors?: boolean | undefined | "mock";
+declare function runAndExit<Context>(cliName: string, cliArgs: ReadonlyArray<string>, context: Context, command: Command<Context, void>, options?: {
+    colorSetup?: "flag" | "env" | "always" | "never" | "mock" | undefined;
     usageOnHelp?: boolean | undefined;
     usageOnError?: boolean | undefined;
     buildVersion?: string | undefined;
@@ -987,285 +1230,4 @@ declare function runAndExit<Context>(cliName: Lowercase<string>, cliArgs: Readon
     onExit?: ((code: number) => never) | undefined;
 }): Promise<never>;
 
-/**
- * Color names for terminal styling, used by {@link TypoStyle}.
- * `dark*` = standard ANSI (30–37); `bright*` = high-intensity (90–97).
- */
-type TypoColor = "darkBlack" | "darkRed" | "darkGreen" | "darkYellow" | "darkBlue" | "darkMagenta" | "darkCyan" | "darkWhite" | "brightBlack" | "brightRed" | "brightGreen" | "brightYellow" | "brightBlue" | "brightMagenta" | "brightCyan" | "brightWhite";
-/**
- * Visual styling applied by a {@link TypoSupport} instance.
- * All fields are optional; ignored entirely in `"none"` mode.
- */
-type TypoStyle = {
-    /**
-     * Foreground (text) color.
-     */
-    fgColor?: TypoColor;
-    /**
-     * Background color.
-     */
-    bgColor?: TypoColor;
-    /**
-     * Render with reduced intensity.
-     */
-    dim?: boolean;
-    /**
-     * Render in bold.
-     */
-    bold?: boolean;
-    /**
-     * Render in italic.
-     */
-    italic?: boolean;
-    /**
-     * Render with an underline.
-     */
-    underline?: boolean;
-    /**
-     * Render with a strikethrough.
-     */
-    strikethrough?: boolean;
-};
-/**
- * Pre-defined style for section titles (e.g. `"Positionals:"`). Bold dark-green.
- */
-declare const typoStyleTitle: TypoStyle;
-/**
- * Pre-defined style for logic/type identifiers in error messages. Bold dark-magenta.
- */
-declare const typoStyleLogic: TypoStyle;
-/**
- * Pre-defined style for quoted user-supplied values in error messages. Bold dark-yellow.
- */
-declare const typoStyleQuote: TypoStyle;
-/**
- * Pre-defined style for failure/error labels (e.g. `"Error:"`). Bold dark-red.
- */
-declare const typoStyleFailure: TypoStyle;
-/**
- * Pre-defined style for CLI flag/option/command names. Bold dark-cyan.
- */
-declare const typoStyleConstants: TypoStyle;
-/**
- * Pre-defined style for positional placeholders and user-input labels. Bold dark-blue.
- */
-declare const typoStyleUserInput: TypoStyle;
-/**
- * Pre-defined style for strong regular text (e.g. command descriptions). Bold.
- */
-declare const typoStyleRegularStrong: TypoStyle;
-/**
- * Pre-defined style for subtle supplementary text (e.g. hints). Italic and dim.
- */
-declare const typoStyleRegularWeaker: TypoStyle;
-/**
- * An immutable styled string segment: a raw text value paired with a {@link TypoStyle}.
- * Compose multiple segments into a {@link TypoText}; rendering is deferred to {@link TypoString.computeStyledString}.
- */
-declare class TypoString {
-    #private;
-    /**
-     * @param value - Raw text content.
-     * @param typoStyle - Style to apply when rendering. Defaults to `{}` (no style).
-     */
-    constructor(value: string, typoStyle?: TypoStyle);
-    /**
-     * Returns the unstyled raw text content.
-     */
-    getRawString(): string;
-    /**
-     * Returns the text styled by `typoSupport`.
-     *
-     * @param typoSupport - Rendering mode.
-     */
-    computeStyledString(typoSupport: TypoSupport): string;
-}
-/**
- * A mutable sequence of {@link TypoString} segments forming a styled multi-part message.
- * Rendering is deferred to {@link TypoText.computeStyledString}.
- */
-declare class TypoText {
-    #private;
-    /**
-     * @param typoParts - Initial segments; `TypoText` is flattened, `string` is wrapped unstyled.
-     */
-    constructor(...typoParts: Array<TypoText | TypoString | string>);
-    /**
-     * Appends a {@link TypoString} segment.
-     *
-     * @param typoString - Segment to append.
-     */
-    pushString(typoString: TypoString | string): void;
-    /**
-     * Appends all segments from another {@link TypoText} (shallow copy).
-     *
-     * @param typoText - Source text.
-     */
-    pushText(typoText: TypoText | string): void;
-    /**
-     * Renders all segments into a single styled string.
-     *
-     * @param typoSupport - Rendering mode.
-     * @returns Concatenated styled string.
-     */
-    computeStyledString(typoSupport: TypoSupport): string;
-    /**
-     * Returns the concatenation of all segments' raw (unstyled) text.
-     */
-    computeRawString(): string;
-    /**
-     * Returns the total character count of the raw (unstyled) text.
-     */
-    computeRawLength(): number;
-}
-/**
- * A column-aligned grid of {@link TypoText} cells.
- * Each column is padded to the widest cell (raw chars); the last column is not padded.
- * Used by {@link usageToStyledLines} to render `Positionals:`, `Subcommands:`, and `Options:`.
- */
-declare class TypoGrid {
-    #private;
-    constructor();
-    /**
-     * Appends a row. All rows should have the same cell count for alignment to be meaningful.
-     *
-     * @param cells - Ordered {@link TypoText} cells.
-     */
-    pushRow(cells: Array<TypoText>): void;
-    /**
-     * Renders the grid as a 2-D array of styled (and column-padded) strings.
-     * Join each inner array with `""` to get a line.
-     *
-     * @param typoSupport - Rendering mode.
-     * @returns 2-D array of styled strings.
-     */
-    computeStyledGrid(typoSupport: TypoSupport): Array<Array<string>>;
-}
-/**
- * `Error` subclass with a {@link TypoText} styled message for rich terminal output.
- * Used throughout the library for parse failures (unknown option, type decode error, etc.).
- * If `source` is a `TypoError`, its styled text is chained after `": "`.
- */
-declare class TypoError extends Error {
-    #private;
-    /**
-     * @param currentTypoText - Styled message for this error.
-     * @param source - Optional cause; `TypoError` chains styled text, `Error` appends `.message`, else `String()`.
-     */
-    constructor(currentTypoText: TypoText, source?: unknown);
-    /**
-     * Renders the styled error message (without a `"Error:"` prefix).
-     *
-     * @param typoSupport - Rendering mode.
-     * @returns Styled error string.
-     */
-    computeStyledString(typoSupport: TypoSupport): string;
-    /**
-     * Runs `thrower`; on any throw wraps it as a `TypoError` with `context()` prepended.
-     * Useful for adding call-chain context (e.g. `"at 0: Number: ..."`).
-     *
-     * @typeParam Value - Return type of `thrower`.
-     * @param thrower - Function to execute; result passed through on success.
-     * @param context - Produces the {@link TypoText} prepended to the caught error.
-     * @returns Value from `thrower`.
-     * @throws `TypoError` wrapping the original error with context prepended.
-     */
-    static tryWithContext<Value>(thrower: () => Value, context: () => TypoText): Value;
-}
-/**
- * Controls ANSI terminal styling for {@link TypoString}, {@link TypoText}, and error rendering.
- * Create via {@link TypoSupport.none}, {@link TypoSupport.tty}, {@link TypoSupport.mock},
- * or {@link TypoSupport.inferFromProcess}.
- */
-declare class TypoSupport {
-    #private;
-    private constructor();
-    /**
-     * Returns a `TypoSupport` that strips all styling (plain text, no ANSI codes).
-     */
-    static none(): TypoSupport;
-    /**
-     * Returns a `TypoSupport` that applies ANSI escape codes (for color-capable terminals).
-     */
-    static tty(): TypoSupport;
-    /**
-     * Returns a `TypoSupport` with deterministic textual styling for snapshot tests.
-     * Style flags appear as suffixes: `{text}@color`, `{text}+` (bold), `{text}-` (dim),
-     * `{text}*` (italic), `{text}_` (underline), `{text}~` (strikethrough).
-     */
-    static mock(): TypoSupport;
-    /**
-     * Auto-detects styling mode from the process environment.
-     * `FORCE_COLOR=0` / `NO_COLOR` → none; `FORCE_COLOR` (truthy) / `isTTY` → tty; else → none.
-     * Falls back to none if `process` is unavailable.
-     */
-    static inferFromProcess(): TypoSupport;
-    /**
-     * Applies `typoStyle` to `value` according to the current mode.
-     *
-     * @param value - Raw text.
-     * @param typoStyle - Style to apply.
-     * @returns Styled string.
-     */
-    computeStyledString(value: string, typoStyle: TypoStyle): string;
-    /**
-     * Formats any thrown value as `"Error: <message>"` with {@link typoStyleFailure} on the prefix.
-     *
-     * @param error - Any thrown value.
-     * @returns Styled error string.
-     */
-    computeStyledErrorMessage(error: unknown): string;
-}
-
-/**
- * Converts a {@link CommandUsage} model into an array of styled lines ready to be
- * joined with `"\n"` and printed to the terminal.
- *
- * The output format is:
- * ```
- * Usage: <cliName> [segments...]
- *
- * <description> (<hint>)
- * <detail lines...>
- *
- * Positionals:
- *   <LABEL>  <description> (<hint>)
- *
- * Subcommands:
- *   <name>  <description> (<hint>)
- *
- * Options:
- *   -s, --long <LABEL>  <description> (<hint>)
- *
- * Examples:
- *   <description>
- *   <command line>
- *
- * ```
- * Sections that have no entries are omitted. The trailing empty line is always included.
- *
- * Column alignment within each section is handled by {@link TypoGrid}: the widest entry
- * in each column sets the width for the entire section.
- *
- * @param params.cliName - Program name for the usage line.
- * @param params.commandUsage - From {@link CommandDecoder.generateUsage}.
- * @param params.typoSupport - Rendering mode.
- * @returns One string per output line; trailing empty string for the blank line at the end.
- *
- * @example
- * ```ts
- * const lines = usageToStyledLines({
- *   cliName: "my-cli",
- *   commandUsage: commandDecoder.generateUsage(),
- *   typoSupport: TypoSupport.tty(),
- * });
- * process.stdout.write(lines.join("\n"));
- * ```
- */
-declare function usageToStyledLines(params: {
-    cliName: Lowercase<string>;
-    commandUsage: CommandUsage;
-    typoSupport: TypoSupport;
-}): string[];
-
-export { type Command, type CommandDecoder, type CommandInformation, type CommandInterpreter, type CommandUsage, type CommandUsageSegment, type CommandUsageSubcommand, type Operation, type OperationDecoder, type OperationInterpreter, type OperationUsage, type Option, type OptionDecoder, type OptionUsage, type Positional, type PositionalDecoder, type PositionalUsage, ReaderArgs, type ReaderOptionKey, type ReaderOptions, type ReaderPositionals, type Type, type TypoColor, TypoError, TypoGrid, TypoString, type TypoStyle, TypoSupport, TypoText, command, commandChained, commandWithSubcommands, operation, optionFlag, optionRepeatable, optionSingleValue, positionalOptional, positionalRequired, positionalVariadics, runAndExit, typeBoolean, typeDate, typeInteger, typeList, typeMapped, typeNumber, typeOneOf, typeString, typeTuple, typeUrl, typoStyleConstants, typoStyleFailure, typoStyleLogic, typoStyleQuote, typoStyleRegularStrong, typoStyleRegularWeaker, typoStyleTitle, typoStyleUserInput, usageToStyledLines };
+export { type Command, type CommandDecoder, type CommandInformation, type CommandInterpreter, type Operation, type OperationDecoder, type OperationInterpreter, type Option, type OptionDecoder, type Positional, type PositionalDecoder, ReaderArgs, type ReaderOptionKey, type ReaderOptionParsing, type ReaderOptionValue, type ReaderOptions, type ReaderPositionals, type Type, type TypoColor, TypoError, TypoGrid, TypoString, type TypoStyle, TypoSupport, TypoText, type UsageCommand, type UsageOption, type UsagePositional, type UsageSubcommand, command, commandChained, commandWithSubcommands, operation, optionFlag, optionRepeatable, optionSingleValue, positionalOptional, positionalRequired, positionalVariadics, runAndExit, type, typeBoolean, typeChoice, typeConverted, typeDatetime, typeInteger, typeList, typeNumber, typePath, typeRenamed, typeTuple, typeUrl, typoStyleConstants, typoStyleFailure, typoStyleLogic, typoStyleQuote, typoStyleRegularStrong, typoStyleRegularWeaker, typoStyleTitle, typoStyleUserInput, usageToStyledLines };