@runa-cmd/help 0.1.0

package/dist/primitives/table.d.ts

@@ -0,0 +1,19 @@
+import type { Block } from '../types.js';
+/** Options for table() */
+export interface TableOptions {
+    /**
+     * Cell padding [vertical, horizontal] (default: [0, 2]).
+     * Horizontal padding is applied as right-padding between columns.
+     */
+    padding?: [number, number];
+    /** Optional header row (rendered with bold if styles available) */
+    headers?: string[];
+}
+/**
+ * Render rows as a table with auto-sized columns.
+ *
+ * @param rows - 2D array of cell content
+ * @param opts - Table options
+ */
+export declare function table(rows: Block[][], opts?: TableOptions): Block;
+//# sourceMappingURL=table.d.ts.map

package/dist/primitives/table.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"table.d.ts","sourceRoot":"","sources":["../../src/primitives/table.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAEzC,0BAA0B;AAC1B,MAAM,WAAW,YAAY;IAC5B;;;OAGG;IACH,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC3B,mEAAmE;IACnE,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB;AAED;;;;;GAKG;AACH,wBAAgB,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,EAAE,IAAI,GAAE,YAAiB,GAAG,KAAK,CAwCrE"}

package/dist/primitives/table.js

@@ -0,0 +1,50 @@
+/**
+ * @runa-cmd/help — table() primitive
+ *
+ * Renders a 2D array of strings/Blocks as aligned columns.
+ * No grid lines by default — uses padding-based layout.
+ */
+import { visibleWidth } from '../ansi/codes.js';
+/**
+ * Render rows as a table with auto-sized columns.
+ *
+ * @param rows - 2D array of cell content
+ * @param opts - Table options
+ */
+export function table(rows, opts = {}) {
+    const [_vPad, hPad] = opts.padding ?? [0, 2];
+    if (rows.length === 0 && !opts.headers)
+        return '';
+    // Combine headers + rows for column width calculation
+    const allRows = opts.headers ? [opts.headers, ...rows] : rows;
+    // Find max number of columns
+    const numCols = allRows.reduce((max, row) => Math.max(max, row.length), 0);
+    // Calculate max visible width per column
+    const colWidths = Array.from({ length: numCols }, () => 0);
+    for (const row of allRows) {
+        for (let col = 0; col < row.length; col++) {
+            colWidths[col] = Math.max(colWidths[col], visibleWidth(row[col]));
+        }
+    }
+    // Render each row
+    const separator = ' '.repeat(hPad);
+    const resultLines = [];
+    for (const row of allRows) {
+        const cells = [];
+        for (let col = 0; col < numCols; col++) {
+            const cell = row[col] ?? '';
+            if (col < numCols - 1) {
+                // Pad to column width (using visible width to account for ANSI)
+                const padNeeded = colWidths[col] - visibleWidth(cell);
+                cells.push(cell + ' '.repeat(Math.max(0, padNeeded)));
+            }
+            else {
+                // Last column — no trailing padding
+                cells.push(cell);
+            }
+        }
+        resultLines.push(cells.join(separator));
+    }
+    return resultLines.join('\n');
+}
+//# sourceMappingURL=table.js.map

package/dist/primitives/table.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"table.js","sourceRoot":"","sources":["../../src/primitives/table.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAchD;;;;;GAKG;AACH,MAAM,UAAU,KAAK,CAAC,IAAe,EAAE,OAAqB,EAAE;IAC7D,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,GAAG,IAAI,CAAC,OAAO,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAE7C,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO;QAAE,OAAO,EAAE,CAAC;IAElD,sDAAsD;IACtD,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAE9D,6BAA6B;IAC7B,MAAM,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC;IAE3E,yCAAyC;IACzC,MAAM,SAAS,GAAa,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC;IACrE,KAAK,MAAM,GAAG,IAAI,OAAO,EAAE,CAAC;QAC3B,KAAK,IAAI,GAAG,GAAG,CAAC,EAAE,GAAG,GAAG,GAAG,CAAC,MAAM,EAAE,GAAG,EAAE,EAAE,CAAC;YAC3C,SAAS,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,YAAY,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QACnE,CAAC;IACF,CAAC;IAED,kBAAkB;IAClB,MAAM,SAAS,GAAG,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACnC,MAAM,WAAW,GAAa,EAAE,CAAC;IAEjC,KAAK,MAAM,GAAG,IAAI,OAAO,EAAE,CAAC;QAC3B,MAAM,KAAK,GAAa,EAAE,CAAC;QAC3B,KAAK,IAAI,GAAG,GAAG,CAAC,EAAE,GAAG,GAAG,OAAO,EAAE,GAAG,EAAE,EAAE,CAAC;YACxC,MAAM,IAAI,GAAG,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC;YAC5B,IAAI,GAAG,GAAG,OAAO,GAAG,CAAC,EAAE,CAAC;gBACvB,gEAAgE;gBAChE,MAAM,SAAS,GAAG,SAAS,CAAC,GAAG,CAAC,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;gBACtD,KAAK,CAAC,IAAI,CAAC,IAAI,GAAG,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC;YACvD,CAAC;iBAAM,CAAC;gBACP,oCAAoC;gBACpC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAClB,CAAC;QACF,CAAC;QACD,WAAW,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC;IACzC,CAAC;IAED,OAAO,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC/B,CAAC"}

package/dist/primitives/wrap.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Word-wrap text to fit within a given width.
+ *
+ * - Splits on spaces, re-joins lines under width limit
+ * - Respects existing newlines (each \n starts a new line)
+ * - Force-breaks words longer than width
+ * - Returns an array of lines (no trailing newline)
+ */
+export declare function wrapText(text: string, width: number): string[];
+//# sourceMappingURL=wrap.d.ts.map

package/dist/primitives/wrap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wrap.d.ts","sourceRoot":"","sources":["../../src/primitives/wrap.ts"],"names":[],"mappings":"AAQA;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAyD9D"}

package/dist/primitives/wrap.js

@@ -0,0 +1,69 @@
+/**
+ * @runa-cmd/help — wrapText() internal utility
+ *
+ * Word-wraps text to a given width. Used internally by box and columns.
+ * NOT exported at package root.
+ */
+import { visibleWidth } from '../ansi/codes.js';
+/**
+ * Word-wrap text to fit within a given width.
+ *
+ * - Splits on spaces, re-joins lines under width limit
+ * - Respects existing newlines (each \n starts a new line)
+ * - Force-breaks words longer than width
+ * - Returns an array of lines (no trailing newline)
+ */
+export function wrapText(text, width) {
+    if (width <= 0)
+        return [text];
+    const result = [];
+    const paragraphs = text.split('\n');
+    for (const paragraph of paragraphs) {
+        if (paragraph === '') {
+            result.push('');
+            continue;
+        }
+        const words = paragraph.split(/\s+/);
+        let currentLine = '';
+        for (const word of words) {
+            const wordWidth = visibleWidth(word);
+            // Force-break words longer than width
+            if (wordWidth > width) {
+                // Flush current line if not empty
+                if (currentLine) {
+                    result.push(currentLine);
+                    currentLine = '';
+                }
+                // Break the long word into chunks
+                let remaining = word;
+                while (remaining.length > width) {
+                    result.push(remaining.slice(0, width));
+                    remaining = remaining.slice(width);
+                }
+                if (remaining) {
+                    currentLine = remaining;
+                }
+                continue;
+            }
+            if (!currentLine) {
+                // First word on line
+                currentLine = word;
+            }
+            else if (visibleWidth(currentLine) + 1 + wordWidth <= width) {
+                // Fits with a space
+                currentLine += ` ${word}`;
+            }
+            else {
+                // Doesn't fit — flush and start new line
+                result.push(currentLine);
+                currentLine = word;
+            }
+        }
+        // Flush last line of paragraph
+        if (currentLine) {
+            result.push(currentLine);
+        }
+    }
+    return result;
+}
+//# sourceMappingURL=wrap.js.map

package/dist/primitives/wrap.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wrap.js","sourceRoot":"","sources":["../../src/primitives/wrap.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAEhD;;;;;;;GAOG;AACH,MAAM,UAAU,QAAQ,CAAC,IAAY,EAAE,KAAa;IACnD,IAAI,KAAK,IAAI,CAAC;QAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IAE9B,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,MAAM,UAAU,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAEpC,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;QACpC,IAAI,SAAS,KAAK,EAAE,EAAE,CAAC;YACtB,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YAChB,SAAS;QACV,CAAC;QAED,MAAM,KAAK,GAAG,SAAS,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QACrC,IAAI,WAAW,GAAG,EAAE,CAAC;QAErB,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YAC1B,MAAM,SAAS,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;YAErC,sCAAsC;YACtC,IAAI,SAAS,GAAG,KAAK,EAAE,CAAC;gBACvB,kCAAkC;gBAClC,IAAI,WAAW,EAAE,CAAC;oBACjB,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;oBACzB,WAAW,GAAG,EAAE,CAAC;gBAClB,CAAC;gBACD,kCAAkC;gBAClC,IAAI,SAAS,GAAG,IAAI,CAAC;gBACrB,OAAO,SAAS,CAAC,MAAM,GAAG,KAAK,EAAE,CAAC;oBACjC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC;oBACvC,SAAS,GAAG,SAAS,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;gBACpC,CAAC;gBACD,IAAI,SAAS,EAAE,CAAC;oBACf,WAAW,GAAG,SAAS,CAAC;gBACzB,CAAC;gBACD,SAAS;YACV,CAAC;YAED,IAAI,CAAC,WAAW,EAAE,CAAC;gBAClB,qBAAqB;gBACrB,WAAW,GAAG,IAAI,CAAC;YACpB,CAAC;iBAAM,IAAI,YAAY,CAAC,WAAW,CAAC,GAAG,CAAC,GAAG,SAAS,IAAI,KAAK,EAAE,CAAC;gBAC/D,oBAAoB;gBACpB,WAAW,IAAI,IAAI,IAAI,EAAE,CAAC;YAC3B,CAAC;iBAAM,CAAC;gBACP,yCAAyC;gBACzC,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;gBACzB,WAAW,GAAG,IAAI,CAAC;YACpB,CAAC;QACF,CAAC;QAED,+BAA+B;QAC/B,IAAI,WAAW,EAAE,CAAC;YACjB,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;QAC1B,CAAC;IACF,CAAC;IAED,OAAO,MAAM,CAAC;AACf,CAAC"}

package/dist/render.d.ts

@@ -0,0 +1,8 @@
+import type { RenderFnCtx } from './types.js';
+/**
+ * Default help renderer — produces formatted help output.
+ *
+ * Accepts a RenderFnCtx (same shape as the custom render function receives).
+ */
+export declare function defaultRenderer(ctx: RenderFnCtx): string;
+//# sourceMappingURL=render.d.ts.map

package/dist/render.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../src/render.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAwB,WAAW,EAAiB,MAAM,YAAY,CAAC;AAEnF;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,WAAW,GAAG,MAAM,CAkBxD"}

package/dist/render.js

@@ -0,0 +1,219 @@
+import { bold as ansiBold, fg } from './ansi/codes.js';
+import { join } from './primitives/join.js';
+import { styled } from './primitives/styled.js';
+import { table } from './primitives/table.js';
+/**
+ * Default help renderer — produces formatted help output.
+ *
+ * Accepts a RenderFnCtx (same shape as the custom render function receives).
+ */
+export function defaultRenderer(ctx) {
+    const { schema, theme } = ctx;
+    const renderCtx = { colorDepth: ctx.colorDepth, termWidth: ctx.termWidth };
+    const sections = [];
+    // Determine if this is a CLISchema (root) or CommandSchema (subcommand)
+    const isCLI = 'meta' in schema && 'commands' in schema && 'globalOptions' in schema;
+    if (isCLI) {
+        const cli = schema;
+        sections.push(...renderCLI(cli, theme, renderCtx));
+    }
+    else {
+        const cmd = schema;
+        sections.push(...renderCommand(cmd, theme, renderCtx));
+    }
+    return join.vertical(sections, { gap: 1 });
+}
+// ─── CLI Root Rendering ─────────────────────────────────────
+function renderCLI(cli, theme, ctx) {
+    const sections = [];
+    // Header
+    const name = cli.meta.name;
+    const version = cli.meta.version ? ` v${cli.meta.version}` : '';
+    sections.push(styled(`${name}${version}`, { bold: true }, ctx));
+    if (cli.meta.description) {
+        sections.push(styled(cli.meta.description, { dim: true }, ctx));
+    }
+    // Usage
+    const hasCommands = cli.commands.length > 0;
+    const usageParts = [name];
+    if (hasCommands)
+        usageParts.push('<command>');
+    usageParts.push('[options]');
+    sections.push(join.vertical([
+        sectionTitle('USAGE', theme, ctx),
+        styled(`  ${usageParts.join(' ')}`, {}, ctx),
+    ]));
+    // Commands
+    if (hasCommands) {
+        const cmdRows = cli.commands.map((cmd) => [
+            styled(cmd.name, { color: 'yellow' }, ctx),
+            cmd.description || '',
+        ]);
+        sections.push(join.vertical([sectionTitle('COMMANDS', theme, ctx), indent(table(cmdRows))]));
+    }
+    // Global Options
+    if (cli.globalOptions.length > 0) {
+        sections.push(join.vertical([
+            sectionTitle('GLOBAL OPTIONS', theme, ctx),
+            indent(renderOptionsTable(cli.globalOptions, theme, ctx)),
+        ]));
+    }
+    return sections;
+}
+// ─── Command Rendering ──────────────────────────────────────
+function renderCommand(cmd, theme, ctx) {
+    const sections = [];
+    // Header
+    const cmdPath = cmd.fullPath.join(' ');
+    sections.push(styled(cmdPath, { bold: true }, ctx));
+    if (cmd.description) {
+        sections.push(styled(cmd.description, { dim: true }, ctx));
+    }
+    // Usage
+    const usageParts = [cmdPath];
+    if (cmd.subcommands && cmd.subcommands.length > 0)
+        usageParts.push('<command>');
+    if (cmd.args.length > 0) {
+        for (const arg of cmd.args) {
+            usageParts.push(arg.required ? `<${arg.name}>` : `[${arg.name}]`);
+        }
+    }
+    usageParts.push('[options]');
+    sections.push(join.vertical([
+        sectionTitle('USAGE', theme, ctx),
+        styled(`  ${usageParts.join(' ')}`, {}, ctx),
+    ]));
+    // Arguments
+    if (cmd.args.length > 0) {
+        const argRows = cmd.args.map((arg) => renderArgRow(arg, theme, ctx));
+        sections.push(join.vertical([sectionTitle('ARGUMENTS', theme, ctx), indent(table(argRows))]));
+    }
+    // Options (grouped)
+    if (cmd.options.length > 0) {
+        sections.push(renderOptionsSection(cmd.options, theme, ctx));
+    }
+    // Subcommands
+    if (cmd.subcommands && cmd.subcommands.length > 0) {
+        const cmdRows = cmd.subcommands.map((sub) => [
+            styled(sub.name, { color: 'yellow' }, ctx),
+            sub.description || '',
+        ]);
+        sections.push(join.vertical([sectionTitle('COMMANDS', theme, ctx), indent(table(cmdRows))]));
+    }
+    return sections;
+}
+// ─── Options Rendering ──────────────────────────────────────
+function renderOptionsSection(options, theme, ctx) {
+    // Separate options by group
+    const grouped = new Map();
+    const ungrouped = [];
+    for (const opt of options) {
+        if (opt.group) {
+            const list = grouped.get(opt.group) ?? [];
+            list.push(opt);
+            grouped.set(opt.group, list);
+        }
+        else {
+            ungrouped.push(opt);
+        }
+    }
+    const parts = [];
+    // Ungrouped options first
+    if (ungrouped.length > 0) {
+        parts.push(join.vertical([
+            sectionTitle('OPTIONS', theme, ctx),
+            indent(renderOptionsTable(ungrouped, theme, ctx)),
+        ]));
+    }
+    // Each group gets its own section
+    for (const [group, opts] of grouped) {
+        parts.push(join.vertical([
+            sectionTitle(`${group.toUpperCase()} OPTIONS`, theme, ctx),
+            indent(renderOptionsTable(opts, theme, ctx)),
+        ]));
+    }
+    // If everything was grouped and there's no ungrouped section
+    if (parts.length === 0)
+        return '';
+    return join.vertical(parts, { gap: 1 });
+}
+function renderOptionsTable(options, theme, ctx) {
+    const rows = options.map((opt) => renderOptionRow(opt, theme, ctx));
+    return table(rows);
+}
+function renderOptionRow(opt, theme, ctx) {
+    // Flag column: --name, -alias
+    const flags = [];
+    if (opt.alias) {
+        for (const a of opt.alias) {
+            // Aliases may come with dash prefix ('-e', '--env') or bare ('e', 'env')
+            if (a.startsWith('--') || a.startsWith('-')) {
+                flags.push(a);
+            }
+            else {
+                flags.push(a.length === 1 ? `-${a}` : `--${a}`);
+            }
+        }
+    }
+    flags.push(`--${opt.name}`);
+    const flagStr = styled(flags.join(', '), { color: 'yellow' }, ctx);
+    // Type column
+    const typeParts = [];
+    if (opt.type === 'enum' && opt.enumValues) {
+        typeParts.push(opt.enumValues.join(' | '));
+    }
+    else if (opt.type !== 'boolean') {
+        typeParts.push(opt.type);
+    }
+    const typeStr = typeParts.length > 0 ? styled(typeParts.join(''), { dim: true }, ctx) : '';
+    // Description column
+    const descParts = [];
+    if (opt.description)
+        descParts.push(opt.description);
+    if (opt.required)
+        descParts.push(fg('(required)', theme.secondary));
+    if (opt.defaultValue !== undefined)
+        descParts.push(fg(`[default: ${String(opt.defaultValue)}]`, theme.muted));
+    if (opt.deprecated)
+        descParts.push(fg(`(deprecated: ${opt.deprecated})`, theme.warning));
+    if (opt.env)
+        descParts.push(fg(`[env: ${opt.env}]`, theme.muted));
+    return [flagStr, typeStr, descParts.join(' ')];
+}
+// ─── Argument Rendering ─────────────────────────────────────
+function renderArgRow(arg, theme, ctx) {
+    // Name column
+    const nameDisplay = arg.isVariadic ? `${arg.name}...` : arg.name;
+    const nameStr = styled(arg.required ? `<${nameDisplay}>` : `[${nameDisplay}]`, { color: 'yellow' }, ctx);
+    // Type column
+    const typeParts = [];
+    if (arg.type === 'enum' && arg.enumValues) {
+        typeParts.push(arg.enumValues.join(' | '));
+    }
+    else {
+        typeParts.push(arg.type);
+    }
+    const typeStr = styled(typeParts.join(''), { dim: true }, ctx);
+    // Description column
+    const descParts = [];
+    if (arg.description)
+        descParts.push(arg.description);
+    if (arg.required)
+        descParts.push(fg('(required)', theme.secondary));
+    if (arg.defaultValue !== undefined)
+        descParts.push(fg(`[default: ${String(arg.defaultValue)}]`, theme.muted));
+    return [nameStr, typeStr, descParts.join(' ')];
+}
+// ─── Helpers ────────────────────────────────────────────────
+function sectionTitle(title, theme, _ctx) {
+    // theme colors are already ANSI-resolved, so use fg() directly (not styled.color which re-downsamples)
+    return ansiBold(fg(title, theme.primary));
+}
+function indent(block, spaces = 2) {
+    const prefix = ' '.repeat(spaces);
+    return block
+        .split('\n')
+        .map((line) => `${prefix}${line}`)
+        .join('\n');
+}
+//# sourceMappingURL=render.js.map

package/dist/render.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.js","sourceRoot":"","sources":["../src/render.ts"],"names":[],"mappings":"AAYA,OAAO,EAAE,IAAI,IAAI,QAAQ,EAAE,EAAE,EAAE,MAAM,iBAAiB,CAAC;AACvD,OAAO,EAAE,IAAI,EAAE,MAAM,sBAAsB,CAAC;AAC5C,OAAO,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAC;AAChD,OAAO,EAAE,KAAK,EAAE,MAAM,uBAAuB,CAAC;AAG9C;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,GAAgB;IAC/C,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,GAAG,CAAC;IAC9B,MAAM,SAAS,GAAkB,EAAE,UAAU,EAAE,GAAG,CAAC,UAAU,EAAE,SAAS,EAAE,GAAG,CAAC,SAAS,EAAE,CAAC;IAE1F,MAAM,QAAQ,GAAY,EAAE,CAAC;IAE7B,wEAAwE;IACxE,MAAM,KAAK,GAAG,MAAM,IAAI,MAAM,IAAI,UAAU,IAAI,MAAM,IAAI,eAAe,IAAI,MAAM,CAAC;IAEpF,IAAI,KAAK,EAAE,CAAC;QACX,MAAM,GAAG,GAAG,MAAmB,CAAC;QAChC,QAAQ,CAAC,IAAI,CAAC,GAAG,SAAS,CAAC,GAAG,EAAE,KAAK,EAAE,SAAS,CAAC,CAAC,CAAC;IACpD,CAAC;SAAM,CAAC;QACP,MAAM,GAAG,GAAG,MAAuB,CAAC;QACpC,QAAQ,CAAC,IAAI,CAAC,GAAG,aAAa,CAAC,GAAG,EAAE,KAAK,EAAE,SAAS,CAAC,CAAC,CAAC;IACxD,CAAC;IAED,OAAO,IAAI,CAAC,QAAQ,CAAC,QAAQ,EAAE,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC;AAC5C,CAAC;AAED,+DAA+D;AAE/D,SAAS,SAAS,CAAC,GAAc,EAAE,KAAoB,EAAE,GAAkB;IAC1E,MAAM,QAAQ,GAAY,EAAE,CAAC;IAE7B,SAAS;IACT,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC;IAC3B,MAAM,OAAO,GAAG,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IAChE,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,IAAI,GAAG,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,GAAG,CAAC,CAAC,CAAC;IAEhE,IAAI,GAAG,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;QAC1B,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,WAAW,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE,GAAG,CAAC,CAAC,CAAC;IACjE,CAAC;IAED,QAAQ;IACR,MAAM,WAAW,GAAG,GAAG,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC;IAC5C,MAAM,UAAU,GAAG,CAAC,IAAI,CAAC,CAAC;IAC1B,IAAI,WAAW;QAAE,UAAU,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;IAC9C,UAAU,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;IAC7B,QAAQ,CAAC,IAAI,CACZ,IAAI,CAAC,QAAQ,CAAC;QACb,YAAY,CAAC,OAAO,EAAE,KAAK,EAAE,GAAG,CAAC;QACjC,MAAM,CAAC,KAAK,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,EAAE,EAAE,GAAG,CAAC;KAC5C,CAAC,CACF,CAAC;IAEF,WAAW;IACX,IAAI,WAAW,EAAE,CAAC;QACjB,MAAM,OAAO,GAAG,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC;YACzC,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,EAAE,GAAG,CAAC;YAC1C,GAAG,CAAC,WAAW,IAAI,EAAE;SACrB,CAAC,CAAC;QACH,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,YAAY,CAAC,UAAU,EAAE,KAAK,EAAE,GAAG,CAAC,EAAE,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC9F,CAAC;IAED,iBAAiB;IACjB,IAAI,GAAG,CAAC,aAAa,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAClC,QAAQ,CAAC,IAAI,CACZ,IAAI,CAAC,QAAQ,CAAC;YACb,YAAY,CAAC,gBAAgB,EAAE,KAAK,EAAE,GAAG,CAAC;YAC1C,MAAM,CAAC,kBAAkB,CAAC,GAAG,CAAC,aAAa,EAAE,KAAK,EAAE,GAAG,CAAC,CAAC;SACzD,CAAC,CACF,CAAC;IACH,CAAC;IAED,OAAO,QAAQ,CAAC;AACjB,CAAC;AAED,+DAA+D;AAE/D,SAAS,aAAa,CAAC,GAAkB,EAAE,KAAoB,EAAE,GAAkB;IAClF,MAAM,QAAQ,GAAY,EAAE,CAAC;IAE7B,SAAS;IACT,MAAM,OAAO,GAAG,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACvC,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,GAAG,CAAC,CAAC,CAAC;IAEpD,IAAI,GAAG,CAAC,WAAW,EAAE,CAAC;QACrB,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,WAAW,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE,GAAG,CAAC,CAAC,CAAC;IAC5D,CAAC;IAED,QAAQ;IACR,MAAM,UAAU,GAAG,CAAC,OAAO,CAAC,CAAC;IAC7B,IAAI,GAAG,CAAC,WAAW,IAAI,GAAG,CAAC,WAAW,CAAC,MAAM,GAAG,CAAC;QAAE,UAAU,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;IAChF,IAAI,GAAG,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACzB,KAAK,MAAM,GAAG,IAAI,GAAG,CAAC,IAAI,EAAE,CAAC;YAC5B,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,IAAI,GAAG,CAAC,CAAC;QACnE,CAAC;IACF,CAAC;IACD,UAAU,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;IAC7B,QAAQ,CAAC,IAAI,CACZ,IAAI,CAAC,QAAQ,CAAC;QACb,YAAY,CAAC,OAAO,EAAE,KAAK,EAAE,GAAG,CAAC;QACjC,MAAM,CAAC,KAAK,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,EAAE,EAAE,GAAG,CAAC;KAC5C,CAAC,CACF,CAAC;IAEF,YAAY;IACZ,IAAI,GAAG,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACzB,MAAM,OAAO,GAAG,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,YAAY,CAAC,GAAG,EAAE,KAAK,EAAE,GAAG,CAAC,CAAC,CAAC;QACrE,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,YAAY,CAAC,WAAW,EAAE,KAAK,EAAE,GAAG,CAAC,EAAE,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC/F,CAAC;IAED,oBAAoB;IACpB,IAAI,GAAG,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC5B,QAAQ,CAAC,IAAI,CAAC,oBAAoB,CAAC,GAAG,CAAC,OAAO,EAAE,KAAK,EAAE,GAAG,CAAC,CAAC,CAAC;IAC9D,CAAC;IAED,cAAc;IACd,IAAI,GAAG,CAAC,WAAW,IAAI,GAAG,CAAC,WAAW,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACnD,MAAM,OAAO,GAAG,GAAG,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC;YAC5C,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,EAAE,GAAG,CAAC;YAC1C,GAAG,CAAC,WAAW,IAAI,EAAE;SACrB,CAAC,CAAC;QACH,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,YAAY,CAAC,UAAU,EAAE,KAAK,EAAE,GAAG,CAAC,EAAE,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC9F,CAAC;IAED,OAAO,QAAQ,CAAC;AACjB,CAAC;AAED,+DAA+D;AAE/D,SAAS,oBAAoB,CAC5B,OAAuB,EACvB,KAAoB,EACpB,GAAkB;IAElB,4BAA4B;IAC5B,MAAM,OAAO,GAAG,IAAI,GAAG,EAA0B,CAAC;IAClD,MAAM,SAAS,GAAmB,EAAE,CAAC;IAErC,KAAK,MAAM,GAAG,IAAI,OAAO,EAAE,CAAC;QAC3B,IAAI,GAAG,CAAC,KAAK,EAAE,CAAC;YACf,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;YAC1C,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YACf,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;QAC9B,CAAC;aAAM,CAAC;YACP,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACrB,CAAC;IACF,CAAC;IAED,MAAM,KAAK,GAAY,EAAE,CAAC;IAE1B,0BAA0B;IAC1B,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC1B,KAAK,CAAC,IAAI,CACT,IAAI,CAAC,QAAQ,CAAC;YACb,YAAY,CAAC,SAAS,EAAE,KAAK,EAAE,GAAG,CAAC;YACnC,MAAM,CAAC,kBAAkB,CAAC,SAAS,EAAE,KAAK,EAAE,GAAG,CAAC,CAAC;SACjD,CAAC,CACF,CAAC;IACH,CAAC;IAED,kCAAkC;IAClC,KAAK,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,IAAI,OAAO,EAAE,CAAC;QACrC,KAAK,CAAC,IAAI,CACT,IAAI,CAAC,QAAQ,CAAC;YACb,YAAY,CAAC,GAAG,KAAK,CAAC,WAAW,EAAE,UAAU,EAAE,KAAK,EAAE,GAAG,CAAC;YAC1D,MAAM,CAAC,kBAAkB,CAAC,IAAI,EAAE,KAAK,EAAE,GAAG,CAAC,CAAC;SAC5C,CAAC,CACF,CAAC;IACH,CAAC;IAED,6DAA6D;IAC7D,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAElC,OAAO,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC;AACzC,CAAC;AAED,SAAS,kBAAkB,CAC1B,OAAuB,EACvB,KAAoB,EACpB,GAAkB;IAElB,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,eAAe,CAAC,GAAG,EAAE,KAAK,EAAE,GAAG,CAAC,CAAC,CAAC;IACpE,OAAO,KAAK,CAAC,IAAI,CAAC,CAAC;AACpB,CAAC;AAED,SAAS,eAAe,CAAC,GAAiB,EAAE,KAAoB,EAAE,GAAkB;IACnF,8BAA8B;IAC9B,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,IAAI,GAAG,CAAC,KAAK,EAAE,CAAC;QACf,KAAK,MAAM,CAAC,IAAI,GAAG,CAAC,KAAK,EAAE,CAAC;YAC3B,yEAAyE;YACzE,IAAI,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;gBAC7C,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YACf,CAAC;iBAAM,CAAC;gBACP,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;YACjD,CAAC;QACF,CAAC;IACF,CAAC;IACD,KAAK,CAAC,IAAI,CAAC,KAAK,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC;IAC5B,MAAM,OAAO,GAAG,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,EAAE,GAAG,CAAC,CAAC;IAEnE,cAAc;IACd,MAAM,SAAS,GAAa,EAAE,CAAC;IAC/B,IAAI,GAAG,CAAC,IAAI,KAAK,MAAM,IAAI,GAAG,CAAC,UAAU,EAAE,CAAC;QAC3C,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;IAC5C,CAAC;SAAM,IAAI,GAAG,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QACnC,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC1B,CAAC;IACD,MAAM,OAAO,GAAG,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAE3F,qBAAqB;IACrB,MAAM,SAAS,GAAa,EAAE,CAAC;IAC/B,IAAI,GAAG,CAAC,WAAW;QAAE,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;IACrD,IAAI,GAAG,CAAC,QAAQ;QAAE,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC,YAAY,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC;IACpE,IAAI,GAAG,CAAC,YAAY,KAAK,SAAS;QACjC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC,aAAa,MAAM,CAAC,GAAG,CAAC,YAAY,CAAC,GAAG,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC;IAC3E,IAAI,GAAG,CAAC,UAAU;QAAE,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC,gBAAgB,GAAG,CAAC,UAAU,GAAG,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC;IACzF,IAAI,GAAG,CAAC,GAAG;QAAE,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC,SAAS,GAAG,CAAC,GAAG,GAAG,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC;IAElE,OAAO,CAAC,OAAO,EAAE,OAAO,EAAE,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAChD,CAAC;AAED,+DAA+D;AAE/D,SAAS,YAAY,CAAC,GAAc,EAAE,KAAoB,EAAE,GAAkB;IAC7E,cAAc;IACd,MAAM,WAAW,GAAG,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC;IACjE,MAAM,OAAO,GAAG,MAAM,CACrB,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,WAAW,GAAG,CAAC,CAAC,CAAC,IAAI,WAAW,GAAG,EACtD,EAAE,KAAK,EAAE,QAAQ,EAAE,EACnB,GAAG,CACH,CAAC;IAEF,cAAc;IACd,MAAM,SAAS,GAAa,EAAE,CAAC;IAC/B,IAAI,GAAG,CAAC,IAAI,KAAK,MAAM,IAAI,GAAG,CAAC,UAAU,EAAE,CAAC;QAC3C,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;IAC5C,CAAC;SAAM,CAAC;QACP,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC1B,CAAC;IACD,MAAM,OAAO,GAAG,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE,GAAG,CAAC,CAAC;IAE/D,qBAAqB;IACrB,MAAM,SAAS,GAAa,EAAE,CAAC;IAC/B,IAAI,GAAG,CAAC,WAAW;QAAE,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;IACrD,IAAI,GAAG,CAAC,QAAQ;QAAE,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC,YAAY,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC;IACpE,IAAI,GAAG,CAAC,YAAY,KAAK,SAAS;QACjC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC,aAAa,MAAM,CAAC,GAAG,CAAC,YAAY,CAAC,GAAG,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC;IAE3E,OAAO,CAAC,OAAO,EAAE,OAAO,EAAE,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAChD,CAAC;AAED,+DAA+D;AAE/D,SAAS,YAAY,CAAC,KAAa,EAAE,KAAoB,EAAE,IAAmB;IAC7E,uGAAuG;IACvG,OAAO,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC;AAC3C,CAAC;AAED,SAAS,MAAM,CAAC,KAAY,EAAE,MAAM,GAAG,CAAC;IACvC,MAAM,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAClC,OAAO,KAAK;SACV,KAAK,CAAC,IAAI,CAAC;SACX,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,GAAG,MAAM,GAAG,IAAI,EAAE,CAAC;SACjC,IAAI,CAAC,IAAI,CAAC,CAAC;AACd,CAAC"}

package/dist/theme.d.ts

@@ -0,0 +1,12 @@
+import type { RenderContext, ResolvedTheme, Theme } from './types.js';
+/** Default theme colors — Lipgloss-inspired */
+export declare const defaultTheme: Theme;
+/**
+ * Merge a partial theme with defaults and downsample all colors
+ * to ANSI-ready escape strings for the current color depth.
+ *
+ * @param partial - User's partial theme override (or undefined for defaults)
+ * @param ctx - RenderContext with colorDepth for downsampling
+ */
+export declare function resolveTheme(partial: Partial<Theme> | undefined, ctx: RenderContext): ResolvedTheme;
+//# sourceMappingURL=theme.d.ts.map

package/dist/theme.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"theme.d.ts","sourceRoot":"","sources":["../src/theme.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,aAAa,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAItE,+CAA+C;AAC/C,eAAO,MAAM,YAAY,EAAE,KAO1B,CAAC;AAcF;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC3B,OAAO,EAAE,OAAO,CAAC,KAAK,CAAC,GAAG,SAAS,EACnC,GAAG,EAAE,aAAa,GAChB,aAAa,CAWf"}

package/dist/theme.js

@@ -0,0 +1,45 @@
+/**
+ * @runa-cmd/help — Theme system
+ *
+ * Provides a default theme, deep-merges partial overrides,
+ * and downsamples all colors to the terminal's color depth.
+ */
+import { downsampleColor } from './ansi/downsample.js';
+// ─── Default Theme ──────────────────────────────────────────
+/** Default theme colors — Lipgloss-inspired */
+export const defaultTheme = {
+    primary: '#7D56F4',
+    secondary: '#FF6B6B',
+    muted: 'dim',
+    error: '#FF0000',
+    warning: '#FFAA00',
+    success: '#00FF00',
+};
+// ─── Theme Resolution ───────────────────────────────────────
+/** Color keys in the Theme interface */
+const THEME_KEYS = [
+    'primary',
+    'secondary',
+    'muted',
+    'error',
+    'warning',
+    'success',
+];
+/**
+ * Merge a partial theme with defaults and downsample all colors
+ * to ANSI-ready escape strings for the current color depth.
+ *
+ * @param partial - User's partial theme override (or undefined for defaults)
+ * @param ctx - RenderContext with colorDepth for downsampling
+ */
+export function resolveTheme(partial, ctx) {
+    // Merge with defaults
+    const merged = { ...defaultTheme, ...partial };
+    // Downsample every color to an ANSI escape string
+    const resolved = {};
+    for (const key of THEME_KEYS) {
+        resolved[key] = downsampleColor(merged[key], ctx.colorDepth);
+    }
+    return resolved;
+}
+//# sourceMappingURL=theme.js.map

package/dist/theme.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"theme.js","sourceRoot":"","sources":["../src/theme.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAGvD,+DAA+D;AAE/D,+CAA+C;AAC/C,MAAM,CAAC,MAAM,YAAY,GAAU;IAClC,OAAO,EAAE,SAAS;IAClB,SAAS,EAAE,SAAS;IACpB,KAAK,EAAE,KAAK;IACZ,KAAK,EAAE,SAAS;IAChB,OAAO,EAAE,SAAS;IAClB,OAAO,EAAE,SAAS;CAClB,CAAC;AAEF,+DAA+D;AAE/D,wCAAwC;AACxC,MAAM,UAAU,GAA+B;IAC9C,SAAS;IACT,WAAW;IACX,OAAO;IACP,OAAO;IACP,SAAS;IACT,SAAS;CACT,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,UAAU,YAAY,CAC3B,OAAmC,EACnC,GAAkB;IAElB,sBAAsB;IACtB,MAAM,MAAM,GAAU,EAAE,GAAG,YAAY,EAAE,GAAG,OAAO,EAAE,CAAC;IAEtD,kDAAkD;IAClD,MAAM,QAAQ,GAAG,EAAmB,CAAC;IACrC,KAAK,MAAM,GAAG,IAAI,UAAU,EAAE,CAAC;QAC9B,QAAQ,CAAC,GAAG,CAAC,GAAG,eAAe,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,GAAG,CAAC,UAAU,CAAC,CAAC;IAC9D,CAAC;IAED,OAAO,QAAQ,CAAC;AACjB,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,60 @@
+/**
+ * @runa-cmd/help — Type definitions
+ *
+ * All TypeScript types for the help system.
+ * Schema types (CLISchema, CommandSchema, etc.) are imported from @runa-cmd/core.
+ * This is a type-only module — no runtime code.
+ */
+import type { CLISchema, CommandSchema } from '@runa-cmd/core';
+/** Everything returns a Block — just a string with optional ANSI codes */
+export type Block = string;
+/** Detected color depth of the terminal */
+export type ColorDepth = 'truecolor' | '256' | '16' | 'none';
+/** Render context passed to all primitives (auto-detected or overridden in tests) */
+export interface RenderContext {
+    colorDepth: ColorDepth;
+    termWidth: number;
+}
+/** Theme colors — all values are hex (#RRGGBB) or named ANSI attribute (e.g. 'dim') */
+export interface Theme {
+    /** Titles, borders */
+    primary: string;
+    /** Required markers, highlights */
+    secondary: string;
+    /** Descriptions, defaults */
+    muted: string;
+    /** Error messages */
+    error: string;
+    /** Warnings */
+    warning: string;
+    /** Success states */
+    success: string;
+}
+/** Theme with all colors resolved to ANSI-ready escape strings */
+export interface ResolvedTheme {
+    primary: string;
+    secondary: string;
+    muted: string;
+    error: string;
+    warning: string;
+    success: string;
+}
+/** What the custom render function receives (Layer 3) */
+export interface RenderFnCtx {
+    /** The target schema (root CLI or specific subcommand) */
+    schema: CLISchema | CommandSchema;
+    /** Resolved theme with ANSI-ready colors */
+    theme: ResolvedTheme;
+    /** Detected color depth */
+    colorDepth: ColorDepth;
+    /** Terminal width in columns */
+    termWidth: number;
+}
+/** Options for helpPlugin() */
+export interface HelpPluginOptions {
+    /** Partial theme override (merged with defaultTheme) */
+    theme?: Partial<Theme>;
+    /** Custom render function (Layer 3 — full control) */
+    render?: (ctx: RenderFnCtx) => string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAI/D,0EAA0E;AAC1E,MAAM,MAAM,KAAK,GAAG,MAAM,CAAC;AAI3B,2CAA2C;AAC3C,MAAM,MAAM,UAAU,GAAG,WAAW,GAAG,KAAK,GAAG,IAAI,GAAG,MAAM,CAAC;AAE7D,qFAAqF;AACrF,MAAM,WAAW,aAAa;IAC7B,UAAU,EAAE,UAAU,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;CAClB;AAID,uFAAuF;AACvF,MAAM,WAAW,KAAK;IACrB,sBAAsB;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,mCAAmC;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,6BAA6B;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,qBAAqB;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,eAAe;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,qBAAqB;IACrB,OAAO,EAAE,MAAM,CAAC;CAChB;AAED,kEAAkE;AAClE,MAAM,WAAW,aAAa;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;CAChB;AAID,yDAAyD;AACzD,MAAM,WAAW,WAAW;IAC3B,0DAA0D;IAC1D,MAAM,EAAE,SAAS,GAAG,aAAa,CAAC;IAClC,4CAA4C;IAC5C,KAAK,EAAE,aAAa,CAAC;IACrB,2BAA2B;IAC3B,UAAU,EAAE,UAAU,CAAC;IACvB,gCAAgC;IAChC,SAAS,EAAE,MAAM,CAAC;CAClB;AAID,+BAA+B;AAC/B,MAAM,WAAW,iBAAiB;IACjC,wDAAwD;IACxD,KAAK,CAAC,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;IACvB,sDAAsD;IACtD,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,WAAW,KAAK,MAAM,CAAC;CACtC"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@runa-cmd/help",
+  "version": "0.1.0",
+  "description": "Themeable help output for Runa CLIs with composable layout primitives.",
+  "license": "MIT",
+  "type": "module",
+  "keywords": [
+    "cli",
+    "help",
+    "ansi",
+    "terminal",
+    "layout",
+    "theme",
+    "runa"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "peerDependencies": {
+    "zod": "^4.0.0",
+    "@runa-cmd/core": "0.1.0"
+  },
+  "engines": {
+    "node": ">=18.3.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jrodrigopuca/runa-cmd.git",
+    "directory": "packages/help"
+  },
+  "homepage": "https://github.com/jrodrigopuca/runa-cmd/tree/main/packages/help#readme",
+  "bugs": {
+    "url": "https://github.com/jrodrigopuca/runa-cmd/issues"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "devDependencies": {
+    "@types/node": "^25.6.0",
+    "typescript": "^6.0.2",
+    "zod": "^4.3.6",
+    "@runa-cmd/core": "0.1.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch --preserveWatchOutput",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "biome check .",
+    "lint:fix": "biome check --write .",
+    "clean": "rm -rf dist"
+  }
+}