@raidiant/notifai 0.2.1 → 0.4.0

package/dist/ui/banner.d.ts

@@ -0,0 +1,22 @@
+export type BannerSize = 'block' | 'ascii' | 'word';
+export declare function bannerSize(columns?: number): BannerSize;
+/** The wordmark as rendered lines, gradient included. */
+export declare function bannerLines(columns?: number): string[];
+/**
+ * Reveal the wordmark one row at a time.
+ *
+ * Deliberately brief and deliberately skippable: this runs before someone can
+ * do anything, so it may not become a wait. It is skipped entirely when output
+ * is not a TTY, when `NOTIFAI_NO_ANIMATION` is set, and under `CI`.
+ */
+export declare function printBanner(options?: {
+    animate?: boolean;
+    env?: NodeJS.ProcessEnv;
+    write?: (line: string) => void;
+}): Promise<void>;
+/**
+ * One line of orientation under the wordmark — and it must stay one line.
+ * Wrapped onto two it stops reading as a subtitle and starts reading as the
+ * first paragraph of something, so a narrow terminal gets the version alone.
+ */
+export declare function tagline(version: string, columns?: number): string;

package/dist/ui/banner.js

@@ -0,0 +1,87 @@
+/**
+ * The wordmark shown when a human opens the interactive app.
+ *
+ * Three tiers, chosen by what the terminal can actually render rather than by
+ * what looks best in a screenshot: box-drawing blocks when the terminal is wide
+ * and Unicode-capable, a pure-ASCII form that survives anywhere, and a plain
+ * word when neither fits. A banner that wraps is worse than no banner, so the
+ * width check is not optional.
+ *
+ * The art is embedded rather than rendered at run time. It is one fixed word
+ * that will never change, and shipping a font engine to redraw a constant on
+ * every launch would cost every install — including the agents that never see
+ * it — for no benefit.
+ */
+import { gradientBlock, style, terminalWidth, unicode } from './theme.js';
+/** ANSI Shadow. 50 columns, 6 rows. */
+const BLOCK = [
+    '███╗   ██╗ ██████╗ ████████╗██╗███████╗ █████╗ ██╗',
+    '████╗  ██║██╔═══██╗╚══██╔══╝██║██╔════╝██╔══██╗██║',
+    '██╔██╗ ██║██║   ██║   ██║   ██║█████╗  ███████║██║',
+    '██║╚██╗██║██║   ██║   ██║   ██║██╔══╝  ██╔══██║██║',
+    '██║ ╚████║╚██████╔╝   ██║   ██║██║     ██║  ██║██║',
+    '╚═╝  ╚═══╝ ╚═════╝    ╚═╝   ╚═╝╚═╝     ╚═╝  ╚═╝╚═╝',
+];
+/** Pure ASCII. 34 columns, 4 rows — safe on any terminal, any code page. */
+const ASCII = [
+    '  _  _  ___ _____ ___ ___ _   ___ ',
+    ' | \\| |/ _ \\_   _|_ _| __/_\\ |_ _|',
+    ' | .` | (_) || |  | || _/ _ \\ | | ',
+    ' |_|\\_|\\___/ |_| |___|_/_/ \\_\\___|',
+];
+export function bannerSize(columns = terminalWidth()) {
+    if (unicode && columns >= 54)
+        return 'block';
+    if (columns >= 38)
+        return 'ascii';
+    return 'word';
+}
+/** The wordmark as rendered lines, gradient included. */
+export function bannerLines(columns = terminalWidth()) {
+    switch (bannerSize(columns)) {
+        case 'block':
+            return gradientBlock(BLOCK);
+        case 'ascii':
+            return gradientBlock(ASCII);
+        case 'word':
+            return gradientBlock(['N O T I F A I']);
+    }
+}
+/**
+ * Reveal the wordmark one row at a time.
+ *
+ * Deliberately brief and deliberately skippable: this runs before someone can
+ * do anything, so it may not become a wait. It is skipped entirely when output
+ * is not a TTY, when `NOTIFAI_NO_ANIMATION` is set, and under `CI`.
+ */
+export async function printBanner(options = {}) {
+    const env = options.env ?? process.env;
+    const write = options.write ?? ((line) => process.stdout.write(`${line}\n`));
+    const lines = bannerLines();
+    const animate = options.animate !== false &&
+        process.stdout.isTTY === true &&
+        (env['NOTIFAI_NO_ANIMATION'] ?? '') === '' &&
+        (env['CI'] ?? '') === '';
+    write('');
+    for (const line of lines) {
+        // Two columns, matching the tagline and the status card beneath it. Flush
+        // left, the wordmark reads as a separate thing sitting above the app.
+        write(`  ${line}`);
+        if (animate)
+            await new Promise((resolve) => setTimeout(resolve, 26));
+    }
+    write('');
+}
+/**
+ * One line of orientation under the wordmark — and it must stay one line.
+ * Wrapped onto two it stops reading as a subtitle and starts reading as the
+ * first paragraph of something, so a narrow terminal gets the version alone.
+ */
+export function tagline(version, columns = terminalWidth()) {
+    const full = 'Native notifications for agents and local programs';
+    // Two leading columns of indent, two trailing for the version.
+    return columns >= full.length + 12
+        ? `${style.dim(full)}  ${style.dim(`v${version}`)}`
+        : style.dim(`v${version}`);
+}
+//# sourceMappingURL=banner.js.map

package/dist/ui/banner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"banner.js","sourceRoot":"","sources":["../../src/ui/banner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EAAE,aAAa,EAAE,KAAK,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,YAAY,CAAA;AAEzE,uCAAuC;AACvC,MAAM,KAAK,GAAG;IACZ,oDAAoD;IACpD,oDAAoD;IACpD,oDAAoD;IACpD,oDAAoD;IACpD,oDAAoD;IACpD,oDAAoD;CACrD,CAAA;AAED,4EAA4E;AAC5E,MAAM,KAAK,GAAG;IACZ,oCAAoC;IACpC,uCAAuC;IACvC,qCAAqC;IACrC,wCAAwC;CACzC,CAAA;AAID,MAAM,UAAU,UAAU,CAAC,OAAO,GAAG,aAAa,EAAE;IAClD,IAAI,OAAO,IAAI,OAAO,IAAI,EAAE;QAAE,OAAO,OAAO,CAAA;IAC5C,IAAI,OAAO,IAAI,EAAE;QAAE,OAAO,OAAO,CAAA;IACjC,OAAO,MAAM,CAAA;AACf,CAAC;AAED,yDAAyD;AACzD,MAAM,UAAU,WAAW,CAAC,OAAO,GAAG,aAAa,EAAE;IACnD,QAAQ,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;QAC5B,KAAK,OAAO;YACV,OAAO,aAAa,CAAC,KAAK,CAAC,CAAA;QAC7B,KAAK,OAAO;YACV,OAAO,aAAa,CAAC,KAAK,CAAC,CAAA;QAC7B,KAAK,MAAM;YACT,OAAO,aAAa,CAAC,CAAC,eAAe,CAAC,CAAC,CAAA;IAC3C,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,UAA0F,EAAE;IAE5F,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,CAAA;IACtC,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,CAAC,CAAC,IAAY,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,IAAI,IAAI,CAAC,CAAC,CAAA;IACpF,MAAM,KAAK,GAAG,WAAW,EAAE,CAAA;IAC3B,MAAM,OAAO,GACX,OAAO,CAAC,OAAO,KAAK,KAAK;QACzB,OAAO,CAAC,MAAM,CAAC,KAAK,KAAK,IAAI;QAC7B,CAAC,GAAG,CAAC,sBAAsB,CAAC,IAAI,EAAE,CAAC,KAAK,EAAE;QAC1C,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,KAAK,EAAE,CAAA;IAE1B,KAAK,CAAC,EAAE,CAAC,CAAA;IACT,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,0EAA0E;QAC1E,sEAAsE;QACtE,KAAK,CAAC,KAAK,IAAI,EAAE,CAAC,CAAA;QAClB,IAAI,OAAO;YAAE,MAAM,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAA;IACtE,CAAC;IACD,KAAK,CAAC,EAAE,CAAC,CAAA;AACX,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,OAAO,CAAC,OAAe,EAAE,OAAO,GAAG,aAAa,EAAE;IAChE,MAAM,IAAI,GAAG,oDAAoD,CAAA;IACjE,+DAA+D;IAC/D,OAAO,OAAO,IAAI,IAAI,CAAC,MAAM,GAAG,EAAE;QAChC,CAAC,CAAC,GAAG,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,KAAK,CAAC,GAAG,CAAC,IAAI,OAAO,EAAE,CAAC,EAAE;QACnD,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,OAAO,EAAE,CAAC,CAAA;AAC9B,CAAC"}

package/dist/ui/config-view.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Rendering for the configuration surfaces a person reads.
+ *
+ * The agent-facing shapes are untouched and live elsewhere: `--json` is the
+ * contract, and the flat `key = value` form stays exactly as it was for
+ * anything that is not a terminal. What is new is only what a human sees.
+ */
+import { type CliConfig, type ConfigKey } from '../config.js';
+/**
+ * The full settings listing, grouped and explained.
+ *
+ * Each key gets its name (what you type), its value (what is in force), where
+ * that value came from, and one line on what it does. The name leads rather
+ * than the friendly label because the next thing a reader does with it is type
+ * it into `config set`.
+ */
+export declare function renderConfigList(config: CliConfig, options?: {
+    showAdvanced?: boolean;
+}): string[];
+/**
+ * Everything about one key, for someone who has asked about it specifically.
+ *
+ * This is the payoff of the listing above staying terse: the reader arrives
+ * here already knowing which key they care about, so the full paragraph, the
+ * legal values, and the layer the current value came from can all be spent on
+ * that one key.
+ */
+export declare function renderConfigExplain(key: ConfigKey, config: CliConfig): string[];
+/** The flat form, unchanged, for anything that is not a person at a terminal. */
+export declare function renderConfigPlain(config: CliConfig, explain: boolean): string[];
+/** Longest visible line, for callers that need to size a rule or a box. */
+export declare function widestLine(lines: readonly string[]): number;

package/dist/ui/config-view.js

@@ -0,0 +1,108 @@
+/**
+ * Rendering for the configuration surfaces a person reads.
+ *
+ * The agent-facing shapes are untouched and live elsewhere: `--json` is the
+ * contract, and the flat `key = value` form stays exactly as it was for
+ * anything that is not a terminal. What is new is only what a human sees.
+ */
+import { CONFIG_KEYS } from '../config.js';
+import { CONFIG_GROUPS, acceptedValues, configInfo, configKeysByGroup, describeSource, formatValue, } from '../config-schema.js';
+import { glyph, pad, style, terminalWidth, width, wrap } from './theme.js';
+/**
+ * The full settings listing, grouped and explained.
+ *
+ * Each key gets its name (what you type), its value (what is in force), where
+ * that value came from, and one line on what it does. The name leads rather
+ * than the friendly label because the next thing a reader does with it is type
+ * it into `config set`.
+ */
+export function renderConfigList(config, options = {}) {
+    const columns = terminalWidth();
+    const lines = [];
+    const nameWidth = Math.max(...CONFIG_KEYS.map((key) => key.length));
+    const SUMMARY_INDENT = '      ';
+    for (const group of CONFIG_GROUPS) {
+        const keys = configKeysByGroup(group.id).filter((info) => options.showAdvanced === true || info.advanced !== true);
+        if (keys.length === 0)
+            continue;
+        lines.push('');
+        lines.push(style.heading(group.title));
+        for (const line of wrap(group.blurb, columns - 2))
+            lines.push(style.dim(`  ${line}`));
+        lines.push('');
+        for (const info of keys) {
+            const entry = config[info.key];
+            const source = describeSource(entry.source);
+            const value = formatValue(info.key, entry.value);
+            const isSet = source.label !== 'default';
+            // The provenance mark is only drawn when there is provenance to show;
+            // an empty dim segment still emits escape codes, so a `trimEnd` on the
+            // finished string cannot remove it.
+            const provenance = isSet ? `  ${style.dim(`${glyph.bullet} ${source.label}`)}` : '';
+            lines.push(`  ${style.code(pad(info.key, nameWidth))}  ` +
+                `${isSet ? style.value(value) : style.unset(value)}${provenance}`);
+            for (const line of wrap(info.summary, columns - SUMMARY_INDENT.length)) {
+                lines.push(style.dim(`${SUMMARY_INDENT}${line}`));
+            }
+        }
+    }
+    lines.push('');
+    lines.push(style.dim(`${glyph.arrow} ${style.code('notifai config explain <key>')} for what one of these means and how to change it.`));
+    return lines;
+}
+/**
+ * Everything about one key, for someone who has asked about it specifically.
+ *
+ * This is the payoff of the listing above staying terse: the reader arrives
+ * here already knowing which key they care about, so the full paragraph, the
+ * legal values, and the layer the current value came from can all be spent on
+ * that one key.
+ */
+export function renderConfigExplain(key, config) {
+    const info = configInfo(key);
+    const entry = config[key];
+    const source = describeSource(entry.source);
+    const columns = terminalWidth();
+    const lines = [];
+    lines.push('');
+    lines.push(`${style.code(key)}  ${style.dim(glyph.bullet)}  ${style.heading(info.label)}`);
+    lines.push('');
+    for (const paragraph of info.detail.split('\n\n')) {
+        for (const line of wrap(paragraph, columns - 2))
+            lines.push(`  ${line}`);
+        lines.push('');
+    }
+    const valueLabel = formatValue(key, entry.value);
+    lines.push(`  ${style.dim(pad('Now', 10))}${style.value(valueLabel)}  ${style.dim(`${glyph.bullet} ${source.label}`)}`);
+    if (source.path !== null)
+        lines.push(`  ${style.dim(pad('', 10))}${style.dim(source.path)}`);
+    lines.push(`  ${style.dim(pad('Accepts', 10))}${acceptedValues(key)}`);
+    if (info.choices !== undefined && info.choiceHints !== undefined) {
+        lines.push('');
+        for (const choice of info.choices) {
+            const hint = info.choiceHints[choice];
+            lines.push(`  ${style.dim(pad('', 10))}${style.code(pad(choice, 14))}${style.dim(hint ?? '')}`.trimEnd());
+        }
+    }
+    lines.push('');
+    const example = info.example ?? (info.choices?.[0] ?? 'value');
+    lines.push(`  ${style.dim('Change it')} ${style.code(`notifai config set ${key} ${example}`)}`);
+    if (entry.source !== 'default' && entry.source !== 'flag') {
+        lines.push(`  ${style.dim('Inherit it')} ${style.code(`notifai config unset ${key}`)}`);
+    }
+    lines.push('');
+    return lines;
+}
+/** The flat form, unchanged, for anything that is not a person at a terminal. */
+export function renderConfigPlain(config, explain) {
+    return CONFIG_KEYS.map((key) => {
+        const entry = config[key];
+        const provenance = explain ? `  [${entry.source}]` : '';
+        return `${key} = ${JSON.stringify(entry.value)}${provenance}`;
+    });
+}
+/** Longest visible line, for callers that need to size a rule or a box. */
+export function widestLine(lines) {
+    return Math.max(0, ...lines.map((line) => width(line)));
+}
+//# sourceMappingURL=config-view.js.map

package/dist/ui/config-view.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-view.js","sourceRoot":"","sources":["../../src/ui/config-view.ts"],"names":[],"mappings":"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"}

package/dist/ui/help.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Help that answers "what can I do here", not "what strings does argv accept".
+ *
+ * The old help listed seventeen commands in one flat column, with the two a new
+ * user needs (`init`, `login`) sitting between a platform capability dump and
+ * an entry point marked "Internal:". Everything was equally prominent, which is
+ * the same as nothing being prominent.
+ *
+ * Grouping and colour are Commander's own (`commandsGroup`, `optionsGroup`, and
+ * the `styleX` hooks it calls when the output has colours); this module only
+ * supplies the palette and the group vocabulary. Commander turns its styling
+ * off by itself when the output is not a terminal, so piped help stays plain
+ * without a second code path.
+ */
+import { type HelpConfiguration } from 'commander';
+/**
+ * Group headings, in the order a reader meets them.
+ *
+ * Ordering is by who needs it and when: first run, then daily use, then the
+ * commands agents drive, then the things touched once or never. Commander
+ * renders groups in first-use order, so these constants are also the layout.
+ */
+export declare const GROUP: {
+    readonly start: "Getting started:";
+    readonly daily: "Everyday:";
+    readonly agent: "For agents and scripts:";
+    readonly advanced: "Account and wiring:";
+    readonly help: "Help:";
+};
+/** Option groups for `send`, which carries thirty flags. */
+export declare const SEND_GROUP: {
+    readonly content: "What it says:";
+    readonly routing: "Where it goes:";
+    readonly presentation: "How it arrives:";
+    readonly reply: "Asking for an answer:";
+    readonly advanced: "Advanced:";
+};
+export declare const helpConfiguration: HelpConfiguration;
+/**
+ * Footer for the root help.
+ *
+ * Its whole job is to make the interactive app discoverable, because someone
+ * reading a wall of flags has already demonstrated they did not know it was
+ * there.
+ */
+export declare function rootHelpFooter(): string;

package/dist/ui/help.js

@@ -0,0 +1,105 @@
+/**
+ * Help that answers "what can I do here", not "what strings does argv accept".
+ *
+ * The old help listed seventeen commands in one flat column, with the two a new
+ * user needs (`init`, `login`) sitting between a platform capability dump and
+ * an entry point marked "Internal:". Everything was equally prominent, which is
+ * the same as nothing being prominent.
+ *
+ * Grouping and colour are Commander's own (`commandsGroup`, `optionsGroup`, and
+ * the `styleX` hooks it calls when the output has colours); this module only
+ * supplies the palette and the group vocabulary. Commander turns its styling
+ * off by itself when the output is not a terminal, so piped help stays plain
+ * without a second code path.
+ */
+import { Help } from 'commander';
+import { glyph, style } from './theme.js';
+/**
+ * Group headings, in the order a reader meets them.
+ *
+ * Ordering is by who needs it and when: first run, then daily use, then the
+ * commands agents drive, then the things touched once or never. Commander
+ * renders groups in first-use order, so these constants are also the layout.
+ */
+export const GROUP = {
+    start: 'Getting started:',
+    daily: 'Everyday:',
+    agent: 'For agents and scripts:',
+    advanced: 'Account and wiring:',
+    help: 'Help:',
+};
+/** Option groups for `send`, which carries thirty flags. */
+export const SEND_GROUP = {
+    content: 'What it says:',
+    routing: 'Where it goes:',
+    presentation: 'How it arrives:',
+    reply: 'Asking for an answer:',
+    advanced: 'Advanced:',
+};
+/** Group order, independent of the order commands happen to be registered in. */
+const GROUP_ORDER = [
+    GROUP.start,
+    GROUP.daily,
+    GROUP.agent,
+    GROUP.advanced,
+    GROUP.help,
+];
+function groupRank(heading) {
+    const index = GROUP_ORDER.indexOf(heading);
+    // Anything not named above keeps its position relative to its peers, because
+    // the sort is stable — which is what lets the same override run over option
+    // groups without needing to know their headings.
+    return index === -1 ? GROUP_ORDER.length : index;
+}
+export const helpConfiguration = {
+    // Groups already carry the intended order; alphabetising would scatter the
+    // dependency between `login` and everything that needs a credential.
+    sortSubcommands: false,
+    sortOptions: false,
+    showGlobalOptions: false,
+    /**
+     * Commander seeds group order from the raw registration order, which ties
+     * how the help reads to where a `program.command(…)` block happens to sit in
+     * the file — move one and the help silently reorders. Sorting the finished
+     * grouping makes `GROUP_ORDER` the single place that decision is made.
+     *
+     * The same override runs over option groups, whose headings are not in
+     * `GROUP_ORDER` at all. They all rank equal, and `sort` is stable, so they
+     * keep the order they were declared in.
+     */
+    groupItems(unsortedItems, visibleItems, getGroup) {
+        // `.call` cannot carry the method's own generic through, so the signature
+        // is restated once here instead of widening every caller to
+        // `Command | Option`.
+        const base = Help.prototype.groupItems;
+        const grouped = base.call(this, unsortedItems, visibleItems, getGroup);
+        return new Map([...grouped.entries()].sort((a, b) => groupRank(a[0]) - groupRank(b[0])));
+    },
+    styleTitle: (title) => style.heading(title),
+    styleCommandText: (text) => style.accent(text),
+    styleSubcommandTerm: (text) => style.code(text),
+    styleOptionTerm: (text) => style.code(text),
+    styleArgumentTerm: (text) => style.code(text),
+    styleDescriptionText: (text) => text,
+    styleUsage: (text) => text,
+};
+/**
+ * Footer for the root help.
+ *
+ * Its whole job is to make the interactive app discoverable, because someone
+ * reading a wall of flags has already demonstrated they did not know it was
+ * there.
+ */
+export function rootHelpFooter() {
+    const lines = [
+        '',
+        style.heading('Start here'),
+        `  ${style.code('notifai')}              ${style.dim(`${glyph.arrow} the interactive app: status, settings, devices, test sends`)}`,
+        `  ${style.code('notifai init')}         ${style.dim(`${glyph.arrow} set this project up, step by step`)}`,
+        '',
+        style.dim(`Every command takes ${style.code('--help')}. Machine-readable output: ${style.code('--json')}.`),
+        style.dim(`Settings are explained by ${style.code('notifai config show')} and ${style.code('notifai config explain <key>')}.`),
+    ];
+    return lines.join('\n');
+}
+//# sourceMappingURL=help.js.map

package/dist/ui/help.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"help.js","sourceRoot":"","sources":["../../src/ui/help.ts"],"names":[],"mappings":"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"}

package/dist/ui/theme.d.ts

@@ -0,0 +1,108 @@
+/** True when the terminal can render the box-drawing and status glyphs below. */
+export declare const unicode: boolean;
+/** True when 24-bit colour is available, which the banner gradient needs. */
+export declare function supportsTrueColor(env?: NodeJS.ProcessEnv): boolean;
+export declare const color: import("picocolors/types.js").Colors & {
+    createColors: (enabled?: boolean) => import("picocolors/types.js").Colors;
+};
+/**
+ * Brand ramp, shared with the companion app icon: pink → coral → rose →
+ * magenta. Used for the wordmark and for accenting the surfaces a human sees.
+ */
+export declare const BRAND_RAMP: readonly ["#FF9EC0", "#FF816B", "#EC5A73", "#B84E93"];
+/**
+ * Sample the brand ramp at `t` in [0, 1]. Multi-stop so the gradient keeps the
+ * icon's coral midtones instead of washing straight from pink to magenta.
+ */
+export declare function rampAt(t: number, ramp?: readonly string[]): string;
+/**
+ * Paint `text` across the brand ramp, one escape per character.
+ *
+ * Falls back to a single flat brand colour without truecolor, and to the bare
+ * string with colour off — a gradient is the most decorative thing this CLI
+ * does, so it must also be the first thing to degrade quietly.
+ */
+export declare function gradient(text: string, ramp?: readonly string[]): string;
+/**
+ * Paint each line of a block so the gradient runs left-to-right across the
+ * whole block rather than restarting per line. The wordmark is one image, and
+ * per-line gradients make it read as several.
+ */
+export declare function gradientBlock(lines: readonly string[], ramp?: readonly string[]): string[];
+export declare const style: {
+    /** A heading that opens a section. */
+    readonly heading: (text: string) => string;
+    /** The brand voice — command names, the product name, the selected thing. */
+    readonly accent: (text: string) => string;
+    /** Secondary text: hints, provenance, units, defaults. */
+    readonly dim: (text: string) => string;
+    /** Something the reader can type. */
+    readonly code: (text: string) => string;
+    readonly ok: (text: string) => string;
+    readonly warn: (text: string) => string;
+    readonly bad: (text: string) => string;
+    /** A value as it currently stands. */
+    readonly value: (text: string) => string;
+    /** A value that is not set, or is inherited rather than chosen. */
+    readonly unset: (text: string) => string;
+};
+/**
+ * Status marks. The glyph and the colour say the same thing twice on purpose;
+ * either alone is enough to read the line.
+ */
+export declare const glyph: {
+    readonly ok: "●" | "*";
+    readonly warn: "!" | "▲";
+    readonly bad: "✕" | "x";
+    readonly pending: "○" | "o";
+    readonly bullet: "•" | "-";
+    readonly arrow: "→" | "->";
+    readonly chevron: "›" | ">";
+    readonly bar: "│" | "|";
+};
+export type Tone = 'ok' | 'warn' | 'bad' | 'pending';
+/** A coloured glyph for a tone; the caller supplies the words. */
+export declare function mark(tone: Tone): string;
+/** Visible width, ignoring ANSI escapes, for alignment maths. */
+export declare function width(text: string): number;
+/** Pad to `size` using visible width, so colour never breaks a column. */
+export declare function pad(text: string, size: number): string;
+/**
+ * Usable terminal width: the real one, capped so paragraphs do not run to 200
+ * characters on a maximised window.
+ *
+ * No lower clamp. Raising a narrow terminal to a comfortable minimum sounds
+ * harmless and is not — every box drawn to that invented width overflows the
+ * real one and wraps, which looks far worse than a cramped box that fits.
+ */
+export declare function terminalWidth(fallback?: number): number;
+/**
+ * A titled box around `rows`.
+ *
+ * Hand-drawn rather than delegated, because the obvious library call sizes
+ * itself from `process.stdout.columns` and divides by it — a pty that reports
+ * zero columns (some CI runners, some `script` invocations) makes the padding
+ * negative and throws, taking the whole screen down with it. A status card is
+ * decoration; it may degrade, but it must never be what crashes the app.
+ *
+ * Rows are measured with `width`, so colour inside them does not skew the
+ * border, and anything too wide for the terminal is clipped rather than
+ * wrapped — a status line that wraps stops being a status line.
+ */
+export declare function card(title: string, rows: readonly string[], columns?: number): string[];
+/**
+ * Truncate to a visible width, carrying escape sequences through untouched.
+ *
+ * Counting only printable characters is the whole point: slicing a coloured
+ * string by `String.length` cuts through an escape sequence and spills raw
+ * `[38;2` into the terminal.
+ */
+export declare function clip(text: string, limit: number): string;
+/**
+ * Wrap `text` to `columns`, returning bare lines.
+ *
+ * Indentation is the caller's, deliberately: an earlier version indented
+ * continuation lines itself, callers indented every line as well, and each
+ * wrapped paragraph stepped further right down the page.
+ */
+export declare function wrap(text: string, columns: number): string[];