@bytevion/cli 0.3.0 → 0.4.0

package/dist/tui/components/ProviderStep.js

@@ -0,0 +1,159 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Box, Text } from 'ink';
+import TextInput from 'ink-text-input';
+import Spinner from 'ink-spinner';
+import React from 'react';
+import { glyphs, tones } from '../theme.js';
+import { Picker } from './Picker.js';
+// Provider connection step. Walks: choose a provider (searchable) → optional base-URL for
+// custom/advanced presets → masked API key (live non-empty validation) → spinner while the port
+// runs → on success hand back the models; on a saved-but-no-models result, drop into a
+// retry/keep/skip recovery picker so a failed import never passes as a clean success.
+export function ProviderStep({ presets, ports, ascii, plainColor, busy, error, onConnected, onSkip, onBusy, onError, }) {
+    const g = glyphs(ascii);
+    const tone = tones(plainColor);
+    const [phase, setPhase] = React.useState('pick');
+    const [preset, setPreset] = React.useState();
+    const [baseUrl, setBaseUrl] = React.useState('');
+    const [apiKey, setApiKey] = React.useState('');
+    const [keyTouched, setKeyTouched] = React.useState(false);
+    const [recover, setRecover] = React.useState();
+    const items = React.useMemo(() => [
+        ...presets.map((p) => ({ value: p.id, label: p.label, hint: p.advanced ? 'advanced' : p.custom ? 'custom' : undefined })),
+        { value: '__skip__', label: 'Skip — connect a provider later' },
+    ], [presets]);
+    const beginConnect = React.useCallback(async (chosen, url, key) => {
+        setPhase('connecting');
+        onBusy(true);
+        try {
+            const res = await ports.connectProvider({
+                id: chosen.id,
+                label: chosen.label,
+                baseUrl: url || chosen.base_url || undefined,
+                apiKey: key,
+                mode: chosen.gateway_mode,
+            });
+            if (res.status === 'connected' && res.models.length) {
+                // Enable the first imported model right away so the gateway can route without a
+                // follow-up BYTE_ALIAS_NOT_CONFIGURED on the first run.
+                const first = res.models[0];
+                if (first?.id)
+                    await ports.enableModel(first.id).catch(() => undefined);
+                onConnected({ status: 'connected', models: res.models, connId: res.connId });
+            }
+            else if (res.status === 'failed') {
+                setRecover({ message: res.error || 'Could not save the provider connection.', connId: res.connId });
+                setPhase('recover');
+                onBusy(false);
+            }
+            else {
+                // saved (or connected w/o models): offer recovery rather than claiming success.
+                setRecover({ message: res.error || 'Saved, but its models could not be loaded.', connId: res.connId });
+                setPhase('recover');
+                onBusy(false);
+            }
+        }
+        catch (err) {
+            setRecover({ message: err?.message ?? String(err) });
+            setPhase('recover');
+            onBusy(false);
+        }
+    }, [ports, onBusy, onConnected]);
+    const onPickProvider = (value) => {
+        if (value === '__skip__') {
+            onSkip();
+            return;
+        }
+        const p = presets.find((x) => x.id === value);
+        if (!p)
+            return;
+        setPreset(p);
+        setApiKey('');
+        setKeyTouched(false);
+        setBaseUrl(p.base_url || '');
+        if (p.custom || !p.base_url)
+            setPhase('baseUrl');
+        else
+            setPhase('apiKey');
+    };
+    const retryWithKey = React.useCallback(async (connId, key) => {
+        setPhase('connecting');
+        onBusy(true);
+        try {
+            const res = await ports.rotateAndTest(connId, key);
+            if (res.models.length) {
+                const first = res.models[0];
+                if (first?.id)
+                    await ports.enableModel(first.id).catch(() => undefined);
+                onConnected({ status: 'connected', models: res.models, connId });
+            }
+            else {
+                setRecover({ message: res.error || 'Still no models returned.', connId });
+                setPhase('recover');
+                onBusy(false);
+            }
+        }
+        catch (err) {
+            setRecover({ message: err?.message ?? String(err), connId });
+            setPhase('recover');
+            onBusy(false);
+        }
+    }, [ports, onBusy, onConnected]);
+    // ---- render per phase ----
+    if (phase === 'pick') {
+        return (_jsxs(Box, { flexDirection: "column", children: [_jsx(Text, { color: tone.accent, bold: true, children: "Connect a provider" }), _jsx(Text, { color: tone.muted, children: "Bring your own key \u2014 Byte routes through it. Type to filter." }), _jsx(Box, { marginTop: 1, children: _jsx(Picker, { items: items, onSelect: onPickProvider, ascii: ascii, plainColor: plainColor, search: true, searchLabel: "Provider" }) }), error ? _jsx(Text, { color: tone.bad, children: `${g.bullet} ${error}` }) : null] }));
+    }
+    if (phase === 'baseUrl' && preset) {
+        const valid = baseUrl.trim().startsWith('http');
+        return (_jsxs(Box, { flexDirection: "column", children: [_jsx(Text, { color: tone.accent, bold: true, children: `${preset.label} — base URL` }), preset.note ? _jsx(Text, { color: tone.warn, children: `${g.bullet} ${preset.note}` }) : null, _jsxs(Box, { marginTop: 1, flexDirection: "row", children: [_jsxs(Text, { color: tone.accent, children: [g.arrow, " "] }), _jsx(TextInput, { value: baseUrl, onChange: setBaseUrl, placeholder: "https://api.example.com/v1", onSubmit: () => {
+                                if (valid)
+                                    setPhase('apiKey');
+                            } })] }), !valid ? _jsx(Text, { color: tone.muted, children: "Must be a URL (starts with http)" }) : _jsx(Text, { color: tone.muted, children: "Enter to continue" })] }));
+    }
+    if (phase === 'apiKey' && preset) {
+        const valid = apiKey.trim().length > 0;
+        return (_jsxs(Box, { flexDirection: "column", children: [_jsx(Text, { color: tone.accent, bold: true, children: `${preset.label} — API key` }), preset.note ? _jsx(Text, { color: tone.warn, children: `${g.bullet} ${preset.note}` }) : null, _jsxs(Box, { marginTop: 1, flexDirection: "row", children: [_jsxs(Text, { color: tone.accent, children: [g.arrow, " "] }), _jsx(TextInput, { value: apiKey, mask: "\u2022", onChange: (v) => {
+                                setApiKey(v);
+                                setKeyTouched(true);
+                            }, placeholder: "paste your key", onSubmit: () => {
+                                if (valid)
+                                    void beginConnect(preset, baseUrl, apiKey);
+                            } })] }), keyTouched && !valid ? _jsx(Text, { color: tone.bad, children: "Required" }) : _jsx(Text, { color: tone.muted, children: "Enter to connect" })] }));
+    }
+    if (phase === 'connecting' || busy) {
+        return (_jsxs(Box, { flexDirection: "row", children: [_jsx(Text, { color: tone.accent, children: _jsx(Spinner, { type: ascii ? 'line' : 'dots' }) }), _jsx(Text, { children: ` Connecting ${preset?.label ?? 'provider'}…` })] }));
+    }
+    // recover: saved but no models, or a hard failure — let the user retry the key, keep it, or skip.
+    if (phase === 'recover' && recover) {
+        const canRetry = recover.connId !== undefined;
+        return (_jsx(RecoverPhase, { message: recover.message, label: preset?.label ?? 'Provider', canRetry: canRetry, ascii: ascii, plainColor: plainColor, onRetry: (key) => recover.connId !== undefined && retryWithKey(recover.connId, key), onKeep: () => onConnected({ status: 'saved', models: [], connId: recover.connId }), onSkip: onSkip }));
+    }
+    return _jsx(Text, { color: tone.muted, children: "\u2026" });
+}
+// The retry/keep/skip recovery UI, with an inline masked key re-entry when "retry" is chosen.
+function RecoverPhase({ message, label, canRetry, ascii, plainColor, onRetry, onKeep, onSkip, }) {
+    const g = glyphs(ascii);
+    const tone = tones(plainColor);
+    const [mode, setMode] = React.useState('choose');
+    const [key, setKey] = React.useState('');
+    const options = [
+        ...(canRetry ? [{ value: 'retry', label: 'Re-enter the key and retry' }] : []),
+        { value: 'keep', label: 'Keep it — I will pick a model later' },
+        { value: 'skip', label: 'Skip the provider for now' },
+    ];
+    if (mode === 'retryKey') {
+        const valid = key.trim().length > 0;
+        return (_jsxs(Box, { flexDirection: "column", children: [_jsx(Text, { color: tone.accent, bold: true, children: `${label} — API key` }), _jsxs(Box, { marginTop: 1, flexDirection: "row", children: [_jsxs(Text, { color: tone.accent, children: [g.arrow, " "] }), _jsx(TextInput, { value: key, mask: "\u2022", onChange: setKey, placeholder: "paste your key", onSubmit: () => {
+                                if (valid)
+                                    onRetry(key);
+                            } })] }), !valid ? _jsx(Text, { color: tone.bad, children: "Required" }) : _jsx(Text, { color: tone.muted, children: "Enter to retry" })] }));
+    }
+    return (_jsxs(Box, { flexDirection: "column", children: [_jsx(Text, { color: tone.warn, children: `${g.bullet} ${message}` }), _jsx(Box, { marginTop: 1, children: _jsx(Picker, { items: options, ascii: ascii, plainColor: plainColor, onSelect: (v) => {
+                        if (v === 'retry')
+                            setMode('retryKey');
+                        else if (v === 'keep')
+                            onKeep();
+                        else
+                            onSkip();
+                    } }) })] }));
+}

package/dist/tui/components/Stepper.d.ts

@@ -0,0 +1,9 @@
+import React from 'react';
+import type { Step } from '../state.js';
+interface StepperProps {
+    current: Step;
+    ascii: boolean;
+    plainColor: boolean;
+}
+export declare function Stepper({ current, ascii, plainColor }: StepperProps): React.ReactElement;
+export {};

package/dist/tui/components/Stepper.js

@@ -0,0 +1,29 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Box, Text } from 'ink';
+import { glyphs, tones } from '../theme.js';
+// Ordered labels for the visible wizard steps. 'welcome' is the entry and 'done' the exit, so
+// the progress dots track the seven meaningful stops in between (welcome folds into the first).
+const ORDER = [
+    { step: 'welcome', label: 'Start' },
+    { step: 'signin', label: 'Sign in' },
+    { step: 'provider', label: 'Provider' },
+    { step: 'model', label: 'Model' },
+    { step: 'key', label: 'Key' },
+    { step: 'preset', label: 'Mode' },
+    { step: 'integrate', label: 'Connect' },
+    { step: 'done', label: 'Done' },
+];
+// Horizontal 8-step tracker: completed steps get a filled tone-ok glyph, the active step a
+// bright accent glyph + label, upcoming steps a muted empty glyph. Connectors are dim dividers.
+export function Stepper({ current, ascii, plainColor }) {
+    const g = glyphs(ascii);
+    const tone = tones(plainColor);
+    const activeIdx = ORDER.findIndex((o) => o.step === current);
+    return (_jsx(Box, { flexDirection: "row", alignItems: "center", children: ORDER.map((o, i) => {
+            const done = i < activeIdx;
+            const active = i === activeIdx;
+            const color = done ? tone.ok : active ? tone.accent : tone.muted;
+            const dot = done ? g.check : active ? g.filled : g.empty;
+            return (_jsxs(Box, { flexDirection: "row", alignItems: "center", children: [_jsx(Text, { color: color, bold: active, children: dot }), _jsx(Text, { children: " " }), _jsx(Text, { color: color, bold: active, dimColor: !active && !done, children: o.label }), i < ORDER.length - 1 ? _jsx(Text, { color: tone.muted, children: `  ${g.divider}  ` }) : null] }, o.step));
+        }) }));
+}

package/dist/tui/contract.d.ts

@@ -0,0 +1,99 @@
+export interface HomeData {
+    email?: string;
+    org?: string;
+    providers?: number;
+    models?: number;
+    byteKeyMasked?: string;
+    gateway: 'healthy' | 'down' | 'unknown';
+    savingsSeries: number[];
+    savedTotal: number;
+    tokensTotal: number;
+    hitRate?: number;
+}
+export interface HomeIslandProps {
+    signedIn: boolean;
+    data: HomeData;
+    plainColor: boolean;
+    ascii: boolean;
+    version: string;
+}
+export type HomeResult = {
+    status: 'fallback';
+} | {
+    status: 'exit';
+} | {
+    status: 'action';
+    commandId: string;
+    argv: string[];
+};
+export interface WizardPorts {
+    signIn(): Promise<{
+        email?: string;
+    }>;
+    listProviders(): Promise<any[]>;
+    connectProvider(a: {
+        id: string;
+        label: string;
+        baseUrl?: string;
+        apiKey: string;
+        mode: string;
+    }): Promise<{
+        status: 'connected' | 'saved' | 'failed';
+        models: any[];
+        connId?: number;
+        error?: string;
+    }>;
+    rotateAndTest(connId: number, apiKey: string): Promise<{
+        models: any[];
+        error?: string;
+    }>;
+    enableModel(id: number): Promise<void>;
+    createByteKey(name: string, preset: string): Promise<{
+        key: string;
+    }>;
+    applyPreset(preset: string): Promise<void>;
+}
+export interface ProviderPresetDTO {
+    id: string;
+    label: string;
+    base_url: string;
+    gateway_mode: string;
+    advanced?: boolean;
+    custom?: boolean;
+    note?: string;
+}
+export interface PresetCardDTO {
+    value: string;
+    label: string;
+    hint: string;
+    blurb: string;
+}
+export interface WizardIslandProps {
+    plainColor: boolean;
+    ascii: boolean;
+    version: string;
+    initial: {
+        signedIn: boolean;
+        email?: string;
+        byteKey?: string;
+    };
+    ports: WizardPorts;
+    providerPresets: ProviderPresetDTO[];
+    presetCards: PresetCardDTO[];
+}
+export interface WizardSummary {
+    profile?: string;
+    model?: string;
+    provider: 'connected' | 'saved' | 'skipped' | 'failed';
+    preset: string;
+    byteKeyCreated: boolean;
+    connect?: string;
+}
+export type WizardResult = {
+    status: 'fallback';
+} | {
+    status: 'cancelled';
+} | {
+    status: 'done';
+    summary: WizardSummary;
+};

package/dist/tui/contract.js

@@ -0,0 +1,5 @@
+// The ONLY types that cross the CJS↔ESM boundary. Zero react/ink imports so this file can
+// be referenced from both the CommonJS CLI and the ESM Ink island without dragging the UI
+// runtime into the control path. Keep these structural — the bridge in src/lib/tui.ts mirrors
+// them so neither side has to import the other across the build boundary.
+export {};

package/dist/tui/index.d.ts

@@ -0,0 +1,3 @@
+import type { HomeIslandProps, HomeResult, WizardIslandProps, WizardResult } from './contract.js';
+export declare function renderHome(props: HomeIslandProps): Promise<HomeResult>;
+export declare function renderWizard(props: WizardIslandProps): Promise<WizardResult>;

package/dist/tui/index.js

@@ -0,0 +1,78 @@
+import { render } from 'ink';
+import React from 'react';
+import { App } from './components/App.js';
+import { Home } from './components/Home.js';
+// ESM island entry. The CJS bridge (src/lib/tui.ts) dynamic-imports this and calls renderHome /
+// renderWizard. Each mounts an Ink root, resolves the result Promise when the component reports
+// done/exit/cancel, then ALWAYS unmounts and restores the cursor in a finally so we never leave
+// the terminal in raw mode or with a hidden cursor — even if rendering throws.
+const SHOW_CURSOR = '\x1b[?25h';
+export async function renderHome(props) {
+    let settled = false;
+    let resolve;
+    const done = new Promise((res) => {
+        resolve = (r) => {
+            if (!settled) {
+                settled = true;
+                res(r);
+            }
+        };
+    });
+    const instance = render(React.createElement(Home, {
+        signedIn: props.signedIn,
+        data: props.data,
+        ascii: props.ascii,
+        plainColor: props.plainColor,
+        version: props.version,
+        onDone: resolve,
+    }), { exitOnCtrlC: false });
+    try {
+        // If Ink exits on its own (e.g. an unexpected unmount), fall back rather than hang.
+        instance.waitUntilExit().then(() => resolve({ status: 'exit' }), () => resolve({ status: 'fallback' }));
+        return await done;
+    }
+    finally {
+        instance.unmount();
+        try {
+            process.stdout.write(SHOW_CURSOR);
+        }
+        catch {
+            /* stream may be closed */
+        }
+    }
+}
+export async function renderWizard(props) {
+    let settled = false;
+    let resolve;
+    const done = new Promise((res) => {
+        resolve = (r) => {
+            if (!settled) {
+                settled = true;
+                res(r);
+            }
+        };
+    });
+    const instance = render(React.createElement(App, {
+        plainColor: props.plainColor,
+        ascii: props.ascii,
+        version: props.version,
+        initial: props.initial,
+        ports: props.ports,
+        providerPresets: props.providerPresets,
+        presetCards: props.presetCards,
+        onDone: resolve,
+    }), { exitOnCtrlC: false });
+    try {
+        instance.waitUntilExit().then(() => resolve({ status: 'cancelled' }), () => resolve({ status: 'fallback' }));
+        return await done;
+    }
+    finally {
+        instance.unmount();
+        try {
+            process.stdout.write(SHOW_CURSOR);
+        }
+        catch {
+            /* stream may be closed */
+        }
+    }
+}

package/dist/tui/package.json

@@ -0,0 +1 @@
+{"type":"module"}

package/dist/tui/state.d.ts

@@ -0,0 +1,77 @@
+import type { WizardSummary } from './contract.js';
+export type Step = 'welcome' | 'signin' | 'provider' | 'model' | 'key' | 'preset' | 'integrate' | 'done';
+export declare const STEPS: Step[];
+export type ProviderStatus = 'connected' | 'saved' | 'skipped' | 'failed' | 'pending';
+export interface State {
+    step: Step;
+    busy: boolean;
+    error?: {
+        from: Step;
+        message: string;
+    };
+    signedIn: boolean;
+    email?: string;
+    providerChoice?: string;
+    baseUrl?: string;
+    providerStatus: ProviderStatus;
+    connId?: number;
+    models: any[];
+    model?: string;
+    preset: string;
+    byteKey?: string;
+    byteKeyRevealed: boolean;
+    connect?: string;
+}
+export interface Initial {
+    signedIn: boolean;
+    email?: string;
+    byteKey?: string;
+}
+export declare function initialState(initial: Initial): State;
+export type Action = {
+    type: 'NEXT';
+} | {
+    type: 'BUSY';
+    busy: boolean;
+} | {
+    type: 'ERROR';
+    from: Step;
+    message: string;
+} | {
+    type: 'CLEAR_ERROR';
+} | {
+    type: 'SIGNED_IN';
+    email?: string;
+} | {
+    type: 'PICK_PROVIDER';
+    id: string;
+    baseUrl?: string;
+} | {
+    type: 'PROVIDER_RESULT';
+    status: 'connected' | 'saved' | 'failed';
+    models: any[];
+    connId?: number;
+} | {
+    type: 'PROVIDER_SKIP';
+} | {
+    type: 'PROVIDER_RETRY';
+} | {
+    type: 'PICK_MODEL';
+    model: string;
+} | {
+    type: 'KEY_CREATED';
+    key: string;
+} | {
+    type: 'REVEAL_KEY';
+} | {
+    type: 'PICK_PRESET';
+    preset: string;
+} | {
+    type: 'PICK_CONNECT';
+    connect?: string;
+} | {
+    type: 'GOTO';
+    step: Step;
+};
+export declare function reducer(state: State, action: Action): State;
+export declare function selectSummary(state: State): WizardSummary;

package/dist/tui/state.js

@@ -0,0 +1,84 @@
+// Pure wizard state machine. No react, no ink, no Date.now / Math.random — every transition
+// is a deterministic function of (state, action) so the whole flow is unit-testable without a
+// terminal. The App component owns the side effects (calling ports) and dispatches results
+// back in here. Errors are NON-FATAL: an ERROR action records what broke and keeps the current
+// step mounted so the user can retry, never unwinding the wizard.
+export const STEPS = ['welcome', 'signin', 'provider', 'model', 'key', 'preset', 'integrate', 'done'];
+export function initialState(initial) {
+    return {
+        step: 'welcome',
+        busy: false,
+        signedIn: initial.signedIn,
+        email: initial.email,
+        providerStatus: 'pending',
+        models: [],
+        preset: 'maximum',
+        byteKey: initial.byteKey,
+        byteKeyRevealed: false,
+    };
+}
+function advance(step) {
+    const i = STEPS.indexOf(step);
+    return i >= 0 && i < STEPS.length - 1 ? STEPS[i + 1] : step;
+}
+export function reducer(state, action) {
+    switch (action.type) {
+        case 'BUSY':
+            return { ...state, busy: action.busy };
+        // Non-fatal: surface the message, drop the busy flag, stay on the same step.
+        case 'ERROR':
+            return { ...state, busy: false, error: { from: action.from, message: action.message } };
+        case 'CLEAR_ERROR':
+            return { ...state, error: undefined };
+        case 'NEXT':
+            return { ...state, step: advance(state.step), error: undefined };
+        case 'GOTO':
+            return { ...state, step: action.step, error: undefined };
+        case 'SIGNED_IN':
+            return { ...state, busy: false, signedIn: true, email: action.email ?? state.email, error: undefined, step: 'provider' };
+        case 'PICK_PROVIDER':
+            return { ...state, providerChoice: action.id, baseUrl: action.baseUrl, error: undefined };
+        case 'PROVIDER_RESULT': {
+            const models = action.models ?? [];
+            // Connected with models → go pick one. Saved/connected without models → skip the model
+            // step and move on; the summary will say "saved" so we never over-claim success.
+            const next = action.status === 'connected' && models.length ? 'model' : 'key';
+            return {
+                ...state,
+                busy: false,
+                error: undefined,
+                providerStatus: action.status,
+                models,
+                connId: action.connId,
+                step: next,
+            };
+        }
+        case 'PROVIDER_SKIP':
+            return { ...state, busy: false, error: undefined, providerStatus: 'skipped', models: [], step: 'key' };
+        // Stay on the provider step so the key entry remounts for another attempt.
+        case 'PROVIDER_RETRY':
+            return { ...state, busy: false, error: undefined, providerStatus: 'pending', step: 'provider' };
+        case 'PICK_MODEL':
+            return { ...state, model: action.model, error: undefined, step: 'key' };
+        case 'KEY_CREATED':
+            return { ...state, busy: false, byteKey: action.key, byteKeyRevealed: true, error: undefined };
+        case 'REVEAL_KEY':
+            return { ...state, byteKeyRevealed: true };
+        case 'PICK_PRESET':
+            return { ...state, preset: action.preset, error: undefined, step: 'integrate' };
+        case 'PICK_CONNECT':
+            return { ...state, connect: action.connect, error: undefined, step: 'done' };
+        default:
+            return state;
+    }
+}
+export function selectSummary(state) {
+    const provider = state.providerStatus === 'pending' ? 'skipped' : state.providerStatus;
+    return {
+        model: state.model,
+        provider,
+        preset: state.preset,
+        byteKeyCreated: Boolean(state.byteKey),
+        connect: state.connect && state.connect !== 'skip' ? state.connect : undefined,
+    };
+}

package/dist/tui/theme.d.ts

@@ -0,0 +1,23 @@
+export declare function hex(t: number): string;
+export declare function gradient(count: number): string[];
+export interface Glyphs {
+    filled: string;
+    check: string;
+    empty: string;
+    arrow: string;
+    bullet: string;
+    border: 'round' | 'classic';
+    spark: string[];
+    brand: string[];
+    divider: string;
+}
+export declare function glyphs(ascii: boolean): Glyphs;
+export interface Tone {
+    accent: string | undefined;
+    ok: string | undefined;
+    warn: string | undefined;
+    bad: string | undefined;
+    muted: string | undefined;
+    brandMid: string | undefined;
+}
+export declare function tones(plainColor: boolean): Tone;

package/dist/tui/theme.js

@@ -0,0 +1,49 @@
+// Byte's terminal palette. The signature is a cyan→blue per-character gradient (no library
+// does true gradients in a terminal, so we interpolate the RGB ramp ourselves and hand Ink a
+// hex per glyph). Everything degrades cleanly: under plainColor the colors collapse to a
+// single accent, under ascii the unicode glyph sets swap for 7-bit equivalents.
+const A = [0x22, 0xd3, 0xee]; // cyan-300  #22d3ee
+const B = [0x3b, 0x82, 0xf6]; // blue-500  #3b82f6
+// Interpolate a single channel/color t∈[0,1] across the cyan→blue ramp → "#rrggbb".
+export function hex(t) {
+    const clamped = t < 0 ? 0 : t > 1 ? 1 : t;
+    return ('#' +
+        A.map((a, i) => Math.round(a + (B[i] - a) * clamped).toString(16).padStart(2, '0')).join(''));
+}
+// Spread N glyphs evenly across the gradient. A single glyph sits at the cyan end.
+export function gradient(count) {
+    if (count <= 1)
+        return [hex(0)];
+    return Array.from({ length: count }, (_, i) => hex(i / (count - 1)));
+}
+const UNICODE = {
+    filled: '●',
+    check: '✓',
+    empty: '○',
+    arrow: '›',
+    bullet: '•',
+    border: 'round',
+    spark: ['▁', '▂', '▃', '▄', '▅', '▆', '▇', '█'],
+    brand: ['›', 'b', '_'],
+    divider: '─',
+};
+const ASCII = {
+    filled: '[*]',
+    check: '[x]',
+    empty: '[ ]',
+    arrow: '>',
+    bullet: '-',
+    border: 'classic',
+    spark: ['.', ':', '-', '=', '+', '*', '#'],
+    brand: ['>', 'b', '_'],
+    divider: '-',
+};
+export function glyphs(ascii) {
+    return ascii ? ASCII : UNICODE;
+}
+export function tones(plainColor) {
+    if (plainColor) {
+        return { accent: undefined, ok: undefined, warn: undefined, bad: undefined, muted: 'gray', brandMid: undefined };
+    }
+    return { accent: 'cyan', ok: 'green', warn: 'yellow', bad: 'red', muted: 'gray', brandMid: hex(0.5) };
+}