@bytevion/cli 0.2.0 → 0.4.0

package/dist/lib/friendly.js

@@ -0,0 +1,86 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.friendlyError = friendlyError;
+exports.renderErrorPanel = renderErrorPanel;
+const picocolors_1 = __importDefault(require("picocolors"));
+// Translates a ByteError (HTTP status + BYTE_* / provider detail code) into plain
+// language a first-time user can act on: what happened, why, and the exact next
+// command. The goal is that no error ever leaves someone stuck.
+function friendlyError(err) {
+    const code = (err.code || '').toUpperCase();
+    const status = err.status;
+    const byCode = {
+        BYTE_AUTH_REQUIRED: {
+            issue: 'You are not signed in yet.',
+            why: 'This command needs your Byte account.',
+            next: 'byte login',
+        },
+        BYTE_KEY_REQUIRED: {
+            issue: 'This profile has no Byte API key.',
+            why: 'Requests run through a Byte key so every optimization applies automatically.',
+            next: 'byte keys create',
+        },
+        BYTE_API_OFFLINE: {
+            issue: 'Could not reach the Byte service.',
+            why: 'You may be offline, or the base URL is pointed somewhere unexpected.',
+            next: 'byte doctor',
+        },
+        BYTE_MODEL_FETCH_FAILED: {
+            issue: 'Your provider was saved, but its model list could not be loaded.',
+            why: 'The provider URL or key looks unreachable right now — your connection is still saved.',
+            next: 'byte providers test',
+        },
+        BYTE_DEVICE_DENIED: {
+            issue: 'Sign-in was declined in the browser.',
+            why: 'The device approval was rejected or closed.',
+            next: 'byte login',
+        },
+        BYTE_DEVICE_EXPIRED: {
+            issue: 'The sign-in code expired.',
+            why: 'It was not approved in time.',
+            next: 'byte login',
+        },
+    };
+    if (byCode[code])
+        return byCode[code];
+    if (status === 0) {
+        return { issue: 'Could not reach the Byte service.', why: 'You may be offline.', next: 'byte doctor' };
+    }
+    if (status === 401 || status === 403) {
+        return { issue: 'Your session or key was rejected.', why: 'It may have expired, been revoked, or be missing a scope.', next: 'byte login' };
+    }
+    if (status === 404) {
+        return {
+            issue: 'That route or model was not found.',
+            why: 'The model may not be wired to your key, or the surface (e.g. /v1/messages) is not enabled for it.',
+            next: 'byte doctor',
+        };
+    }
+    if (status === 429) {
+        return { issue: 'Rate limit reached.', why: 'Too many requests landed in a short window.', next: 'wait a few seconds, then retry' };
+    }
+    if (status && status >= 500) {
+        return {
+            issue: 'The service hit an error finishing your request.',
+            why: 'This is on the Byte side, not your input — your key and provider are fine.',
+            next: 'byte doctor   (then retry shortly)',
+        };
+    }
+    return { issue: err.message || 'Something went wrong.', why: `Error code: ${err.code}`, next: 'byte doctor' };
+}
+// A compact, left-accent error panel. picocolors auto-disables under NO_COLOR, so this
+// degrades to clean monochrome text in plain terminals.
+function renderErrorPanel(f) {
+    const bar = picocolors_1.default.red('▌');
+    const lines = [
+        `${bar} ${picocolors_1.default.bold(picocolors_1.default.red('Byte hit a problem'))}`,
+        `${bar} ${f.issue}`,
+        `${bar}`,
+        `${bar} ${picocolors_1.default.dim('Why ')}  ${f.why}`,
+        `${bar} ${picocolors_1.default.dim('Next')}  ${picocolors_1.default.cyan(f.next)}`,
+    ];
+    return `\n${lines.join('\n')}\n`;
+}

package/dist/lib/home.d.ts

@@ -0,0 +1,16 @@
+import { ByteApi } from './api';
+export declare function wordmark(): string;
+export interface HomeData {
+    email?: string;
+    org?: string;
+    providers?: number;
+    models?: number;
+    byteKey?: string;
+    gateway?: 'healthy' | 'down' | 'unknown';
+    savingsSeries: number[];
+    savedTotal: number;
+    tokensTotal: number;
+    hitRate?: number;
+}
+export declare function loadHomeData(api: ByteApi, byteKey: string | undefined, fallbackId: string): Promise<HomeData>;
+export declare function renderHome(data: HomeData, signedIn: boolean): string;

package/dist/lib/home.js

@@ -0,0 +1,97 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.wordmark = wordmark;
+exports.loadHomeData = loadHomeData;
+exports.renderHome = renderHome;
+const picocolors_1 = __importDefault(require("picocolors"));
+const output_1 = require("./output");
+const ANSI = /\x1b\[[0-9;]*m/g;
+const visLen = (s) => s.replace(ANSI, '').length;
+const plainMode = () => Boolean(process.env.NO_COLOR) || process.env.BYTE_PLAIN === '1';
+// Cyan→blue gradient wordmark. picocolors has no true gradient, so we step the letters
+// across a cyan→blue ramp — a recognizable Byte signature that degrades to plain text.
+function wordmark() {
+    const mark = `${picocolors_1.default.dim('›')}${picocolors_1.default.bold(picocolors_1.default.cyanBright('b'))}${picocolors_1.default.dim('_')}`;
+    if (plainMode())
+        return `${mark} BYTE`;
+    const ramp = [picocolors_1.default.cyanBright, picocolors_1.default.cyan, picocolors_1.default.blue, picocolors_1.default.blueBright];
+    const name = 'BYTE'
+        .split('')
+        .map((ch, i) => picocolors_1.default.bold(ramp[i % ramp.length](ch)))
+        .join('');
+    return `${mark}  ${name}`;
+}
+function box(lines, pad = 2) {
+    const inner = Math.max(...lines.map(visLen));
+    const horiz = '─'.repeat(inner + pad * 2);
+    const body = lines.map((l) => `${picocolors_1.default.dim('│')}${' '.repeat(pad)}${l}${' '.repeat(inner - visLen(l) + pad)}${picocolors_1.default.dim('│')}`);
+    return [picocolors_1.default.dim(`╭${horiz}╮`), ...body, picocolors_1.default.dim(`╰${horiz}╯`)].join('\n');
+}
+function withTimeout(p, ms) {
+    return new Promise((resolve) => {
+        const timer = setTimeout(() => resolve(undefined), ms);
+        if (typeof timer.unref === 'function')
+            timer.unref();
+        p.then((v) => {
+            clearTimeout(timer);
+            resolve(v);
+        }, () => {
+            clearTimeout(timer);
+            resolve(undefined);
+        });
+    });
+}
+// Fetches everything bare `byte` shows, in parallel, each guarded by a short timeout so a
+// slow or unreachable service never blocks the home screen — missing cells just render dim.
+async function loadHomeData(api, byteKey, fallbackId) {
+    const [me, provs, usage, health] = await Promise.all([
+        withTimeout(api.me(), 4000),
+        withTimeout(api.providersList(), 4000),
+        withTimeout(api.usage('day'), 4000),
+        withTimeout(api.health(), 3000),
+    ]);
+    const conns = provs?.connections ?? (Array.isArray(provs) ? provs : []);
+    const models = conns.reduce((a, c) => a + (Number(c.models ?? c.model_count ?? 0) || 0), 0);
+    const series = usage?.series ?? [];
+    const num = (v) => {
+        const n = typeof v === 'number' ? v : Number(v);
+        return Number.isFinite(n) ? n : 0;
+    };
+    const requests = series.reduce((a, p) => a + num(p.requests), 0);
+    const cached = series.reduce((a, p) => a + num(p.cached), 0);
+    return {
+        email: me?.user?.email,
+        org: me?.org?.name ?? me?.user?.org_name,
+        providers: conns.length || undefined,
+        models: models || undefined,
+        byteKey,
+        gateway: health ? (health.status === 'ok' || health.ok ? 'healthy' : 'down') : 'unknown',
+        savingsSeries: series.map((p) => num(p.savings_usd)),
+        savedTotal: series.reduce((a, p) => a + num(p.savings_usd), 0),
+        tokensTotal: series.reduce((a, p) => a + num(p.tokens_in) + num(p.tokens_out), 0),
+        hitRate: requests > 0 ? cached / requests : undefined,
+    };
+}
+function renderHome(data, signedIn) {
+    const dim = picocolors_1.default.dim;
+    const label = (s) => dim(s.padEnd(10));
+    const dash = dim('—');
+    const gatewayDot = data.gateway === 'healthy' ? `${picocolors_1.default.green('●')} healthy` : data.gateway === 'down' ? `${picocolors_1.default.red('●')} unreachable` : dim('● unknown');
+    const lines = [
+        `${wordmark()}${' '.repeat(6)}${dim('optimization gateway')}`,
+        '',
+        `${label('Account')}${signedIn ? `${data.email ?? 'you'}${data.org ? `  ${dim('·')}  ${data.org}` : ''}` : picocolors_1.default.yellow('not signed in')}`,
+        `${label('Providers')}${data.providers ? `${data.providers} connected${data.models ? `  ${dim('·')}  ${data.models} models` : ''}` : dash}`,
+        `${label('Byte key')}${data.byteKey ? picocolors_1.default.cyan((0, output_1.maskKey)(data.byteKey)) : dash}`,
+        `${label('Gateway')}${gatewayDot}`,
+    ];
+    if (data.savingsSeries.some((v) => v > 0) || data.savedTotal > 0) {
+        const spark = (0, output_1.sparkline)(data.savingsSeries, plainMode());
+        const summary = `${picocolors_1.default.green((0, output_1.fmtUsd)(data.savedTotal))} saved  ${dim('·')}  ${(0, output_1.fmtNum)(data.tokensTotal)} tokens${data.hitRate !== undefined ? `  ${dim('·')}  ${(0, output_1.pct)(data.hitRate)} cache hits` : ''}`;
+        lines.push('', `${label('7-day')}${picocolors_1.default.cyan(spark)}  ${summary}`);
+    }
+    return box(lines);
+}

package/dist/lib/output.d.ts

@@ -2,3 +2,6 @@ export declare function renderTable(head: string[], rows: Array<Array<string | n
 export declare function maskKey(value: string | undefined): string;
 export declare function fmtUsd(value: unknown): string;
 export declare function pct(value: unknown): string;
+export declare function fmtNum(value: unknown): string;
+export declare function fmtBucket(value: unknown): string;
+export declare function sparkline(values: number[], plain?: boolean): string;

package/dist/lib/output.js

@@ -7,6 +7,9 @@ exports.renderTable = renderTable;
 exports.maskKey = maskKey;
 exports.fmtUsd = fmtUsd;
 exports.pct = pct;
+exports.fmtNum = fmtNum;
+exports.fmtBucket = fmtBucket;
+exports.sparkline = sparkline;
 const cli_table3_1 = __importDefault(require("cli-table3"));
 function renderTable(head, rows) {
     const table = new cli_table3_1.default({ head });
@@ -35,3 +38,43 @@ function pct(value) {
     const scaled = n <= 1 ? n * 100 : n;
     return `${scaled.toFixed(1)}%`;
 }
+// 1234 -> "1.2K", 1_500_000 -> "1.5M". Keeps small counts exact.
+function fmtNum(value) {
+    const n = typeof value === 'number' ? value : Number(value);
+    if (!Number.isFinite(n))
+        return '-';
+    const abs = Math.abs(n);
+    if (abs >= 1_000_000)
+        return `${(n / 1_000_000).toFixed(1)}M`;
+    if (abs >= 1_000)
+        return `${(n / 1_000).toFixed(1)}K`;
+    return String(Math.round(n));
+}
+const MONTHS = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
+// "2026-05-30" -> "May 30"; "2026-05-30T14:00:00Z" -> "May 30 14:00".
+function fmtBucket(value) {
+    if (typeof value !== 'string' || !value)
+        return '-';
+    const m = value.match(/^(\d{4})-(\d{2})-(\d{2})(?:T(\d{2}):)?/);
+    if (!m)
+        return value;
+    const mon = MONTHS[Number(m[2]) - 1] ?? m[2];
+    const day = String(Number(m[3]));
+    return m[4] ? `${mon} ${day} ${m[4]}:00` : `${mon} ${day}`;
+}
+// Unicode block sparkline with an ASCII fallback for legacy terminals (NO_COLOR/conhost).
+function sparkline(values, plain = false) {
+    const nums = values.map((v) => (Number.isFinite(v) ? v : 0));
+    if (!nums.length)
+        return '';
+    const ramp = plain ? '.:-=+*#'.split('') : '▁▂▃▄▅▆▇█'.split('');
+    const max = Math.max(...nums);
+    const min = Math.min(...nums);
+    const span = max - min || 1;
+    return nums
+        .map((v) => {
+        const idx = Math.round(((v - min) / span) * (ramp.length - 1));
+        return ramp[Math.max(0, Math.min(ramp.length - 1, idx))];
+    })
+        .join('');
+}

package/dist/lib/presets.d.ts

@@ -0,0 +1,9 @@
+export interface PresetCard {
+    value: string;
+    label: string;
+    hint: string;
+    blurb: string;
+}
+export declare const PRESET_CARDS: PresetCard[];
+export declare const PRESET_VALUES: string[];
+export declare function presetCard(value: string): PresetCard | undefined;

package/dist/lib/presets.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PRESET_VALUES = exports.PRESET_CARDS = void 0;
+exports.presetCard = presetCard;
+exports.PRESET_CARDS = [
+    {
+        value: 'maximum',
+        label: 'Maximum — everything on (recommended)',
+        hint: 'best savings + quality',
+        blurb: 'Every production-safe optimization runs on every request: full caching, compression, routing, and quality guards.',
+    },
+    {
+        value: 'max_savings',
+        label: 'Maximum savings',
+        hint: 'cheapest',
+        blurb: 'Leans hardest on caching, compression, and cheaper routing to cut spend the most.',
+    },
+    {
+        value: 'balanced',
+        label: 'Balanced',
+        hint: 'savings + speed',
+        blurb: 'A middle ground: strong savings without the deepest latency-adding passes.',
+    },
+    {
+        value: 'lowest_latency',
+        label: 'Lowest latency',
+        hint: 'fastest',
+        blurb: 'Skips the heavier passes so responses come back as fast as possible.',
+    },
+    {
+        value: 'reliability_first',
+        label: 'Reliability first',
+        hint: 'most robust',
+        blurb: 'Prioritizes verification, repair, and fallbacks over maximum savings.',
+    },
+];
+exports.PRESET_VALUES = exports.PRESET_CARDS.map((c) => c.value);
+function presetCard(value) {
+    return exports.PRESET_CARDS.find((c) => c.value === value);
+}

package/dist/lib/tui.d.ts

@@ -0,0 +1,105 @@
+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;
+};
+export declare function useInk(opts?: {
+    json?: boolean;
+}): boolean;
+export declare function computeAscii(): boolean;
+export declare function renderHomeIsland(props: HomeIslandProps): Promise<HomeResult>;
+export declare function renderWizardIsland(props: WizardIslandProps): Promise<WizardResult>;

package/dist/lib/tui.gate.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/lib/tui.gate.test.js

@@ -0,0 +1,96 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const strict_1 = __importDefault(require("node:assert/strict"));
+const node_test_1 = require("node:test");
+const tui_1 = require("./tui");
+// Snapshot the process knobs useInk reads so each case can set a clean world and restore it.
+const saved = {
+    stdinTTY: process.stdin.isTTY,
+    stdoutTTY: process.stdout.isTTY,
+    columns: process.stdout.columns,
+    env: { ...process.env },
+};
+function setWorld(opts) {
+    Object.defineProperty(process.stdin, 'isTTY', { value: opts.stdin ?? true, configurable: true });
+    Object.defineProperty(process.stdout, 'isTTY', { value: opts.stdout ?? true, configurable: true });
+    Object.defineProperty(process.stdout, 'columns', { value: opts.columns ?? 120, configurable: true });
+    // Clear the opt-out / CI / color env that useInk inspects, then apply overrides.
+    for (const k of ['NO_COLOR', 'CI', 'BYTE_PLAIN', 'BYTE_TUI', 'BYTE_NO_MENU'])
+        delete process.env[k];
+    for (const [k, v] of Object.entries(opts.env ?? {})) {
+        if (v === undefined)
+            delete process.env[k];
+        else
+            process.env[k] = v;
+    }
+}
+(0, node_test_1.afterEach)(() => {
+    Object.defineProperty(process.stdin, 'isTTY', { value: saved.stdinTTY, configurable: true });
+    Object.defineProperty(process.stdout, 'isTTY', { value: saved.stdoutTTY, configurable: true });
+    Object.defineProperty(process.stdout, 'columns', { value: saved.columns, configurable: true });
+    for (const k of Object.keys(process.env))
+        if (!(k in saved.env))
+            delete process.env[k];
+    Object.assign(process.env, saved.env);
+});
+(0, node_test_1.test)('useInk true on a wide, color-capable TTY with no opt-out', () => {
+    setWorld({ stdin: true, stdout: true, columns: 120 });
+    strict_1.default.equal((0, tui_1.useInk)(), true);
+});
+(0, node_test_1.test)('useInk false when stdout is not a TTY (piped)', () => {
+    setWorld({ stdout: false });
+    strict_1.default.equal((0, tui_1.useInk)(), false);
+});
+(0, node_test_1.test)('useInk false when stdin is not a TTY', () => {
+    setWorld({ stdin: false });
+    strict_1.default.equal((0, tui_1.useInk)(), false);
+});
+(0, node_test_1.test)('useInk false under CI', () => {
+    setWorld({ env: { CI: '1' } });
+    strict_1.default.equal((0, tui_1.useInk)(), false);
+});
+(0, node_test_1.test)('useInk false under NO_COLOR', () => {
+    setWorld({ env: { NO_COLOR: '1' } });
+    strict_1.default.equal((0, tui_1.useInk)(), false);
+});
+(0, node_test_1.test)('useInk false when the window is narrower than 80 columns', () => {
+    setWorld({ columns: 70 });
+    strict_1.default.equal((0, tui_1.useInk)(), false);
+});
+(0, node_test_1.test)('useInk false with BYTE_PLAIN=1, BYTE_TUI=0, or BYTE_NO_MENU=1', () => {
+    setWorld({ env: { BYTE_PLAIN: '1' } });
+    strict_1.default.equal((0, tui_1.useInk)(), false);
+    setWorld({ env: { BYTE_TUI: '0' } });
+    strict_1.default.equal((0, tui_1.useInk)(), false);
+    setWorld({ env: { BYTE_NO_MENU: '1' } });
+    strict_1.default.equal((0, tui_1.useInk)(), false);
+});
+(0, node_test_1.test)('useInk false when the JSON flag is set even on a good TTY', () => {
+    setWorld({});
+    strict_1.default.equal((0, tui_1.useInk)({ json: true }), false);
+});
+(0, node_test_1.test)('computeAscii true on bare win32 (no Windows Terminal / WSL)', () => {
+    const savedPlatform = Object.getOwnPropertyDescriptor(process, 'platform');
+    Object.defineProperty(process, 'platform', { value: 'win32', configurable: true });
+    delete process.env.WT_SESSION;
+    delete process.env.WSL_DISTRO_NAME;
+    delete process.env.TERM;
+    strict_1.default.equal((0, tui_1.computeAscii)(), true);
+    // Windows Terminal sets WT_SESSION → unicode is safe.
+    process.env.WT_SESSION = '1';
+    strict_1.default.equal((0, tui_1.computeAscii)(), false);
+    delete process.env.WT_SESSION;
+    Object.defineProperty(process, 'platform', savedPlatform);
+});
+(0, node_test_1.test)('computeAscii true on a dumb terminal regardless of platform', () => {
+    const savedPlatform = Object.getOwnPropertyDescriptor(process, 'platform');
+    Object.defineProperty(process, 'platform', { value: 'linux', configurable: true });
+    process.env.TERM = 'dumb';
+    strict_1.default.equal((0, tui_1.computeAscii)(), true);
+    delete process.env.TERM;
+    strict_1.default.equal((0, tui_1.computeAscii)(), false);
+    Object.defineProperty(process, 'platform', savedPlatform);
+});

package/dist/lib/tui.js

@@ -0,0 +1,62 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useInk = useInk;
+exports.computeAscii = computeAscii;
+exports.renderHomeIsland = renderHomeIsland;
+exports.renderWizardIsland = renderWizardIsland;
+const node_path_1 = __importDefault(require("node:path"));
+const node_url_1 = require("node:url");
+// CJS→ESM bridge for the Ink island. This file stays under src/lib (CommonJS) and is the ONLY
+// thing the commands touch; the island itself lives under src/tui and is compiled separately to
+// ESM (dist/tui). Like src/lib/ui.ts, a plain import() would be down-levelled to require() and
+// blow up on ESM-only Ink, so we hide it behind `new Function`. Every entry point is
+// fallback-first: ANY failure resolves to {status:'fallback'} and the caller drops to clack.
+const importESM = new Function('s', 'return import(s)');
+// Resolve the island entry as an absolute file:// URL off this module's location. Both the
+// CJS bridge (dist/lib/tui.js) and the island (dist/tui/index.js) live under dist/, so step up
+// one level. pathToFileURL is MANDATORY on Windows — a bare path makes dynamic import throw
+// ERR_UNSUPPORTED_ESM_URL_SCHEME.
+function islandUrl() {
+    return (0, node_url_1.pathToFileURL)(node_path_1.default.join(__dirname, '..', 'tui', 'index.js')).href;
+}
+// Gate: the Ink UI only takes over when we have a real, wide-enough, color-capable TTY on both
+// ends and nobody opted out. Any miss (pipe, CI, narrow window, NO_COLOR, BYTE_PLAIN, the JSON
+// flag) returns false and the caller stays on the existing clack path. Mirrors lib/tty.ts.
+function useInk(opts) {
+    return (Boolean(process.stdin.isTTY) &&
+        Boolean(process.stdout.isTTY) &&
+        (process.stdout.columns ?? 0) >= 80 &&
+        !process.env.NO_COLOR &&
+        !process.env.CI &&
+        process.env.BYTE_PLAIN !== '1' &&
+        process.env.BYTE_TUI !== '0' &&
+        process.env.BYTE_NO_MENU !== '1' &&
+        !opts?.json);
+}
+// Drop to 7-bit glyphs on legacy Windows consoles (conhost without Windows Terminal / WSL) and
+// dumb terminals, where unicode block glyphs render as mojibake.
+function computeAscii() {
+    return ((process.platform === 'win32' && !process.env.WT_SESSION && !process.env.WSL_DISTRO_NAME) ||
+        process.env.TERM === 'dumb');
+}
+async function renderHomeIsland(props) {
+    try {
+        const mod = await importESM(islandUrl());
+        return (await mod.renderHome(props));
+    }
+    catch {
+        return { status: 'fallback' };
+    }
+}
+async function renderWizardIsland(props) {
+    try {
+        const mod = await importESM(islandUrl());
+        return (await mod.renderWizard(props));
+    }
+    catch {
+        return { status: 'fallback' };
+    }
+}

package/dist/lib/ui.js

@@ -32,8 +32,20 @@ exports.theme = {
     muted: (s) => picocolors_1.default.dim(s),
     bold: (s) => picocolors_1.default.bold(s),
 };
+// The Byte signature: a `›b_` prompt glyph and a cyan→blue gradient wordmark. picocolors
+// has no true gradient, so the letters step across a cyan→blue ramp; degrades to plain
+// text under NO_COLOR/BYTE_PLAIN. Kept in sync with the home dashboard wordmark.
 function banner() {
-    return `${picocolors_1.default.dim('>')}${picocolors_1.default.bold(picocolors_1.default.cyan('b'))}${picocolors_1.default.dim('_')}  ${picocolors_1.default.bold('Byte')}`;
+    const plain = Boolean(process.env.NO_COLOR) || process.env.BYTE_PLAIN === '1';
+    const mark = `${picocolors_1.default.dim('›')}${picocolors_1.default.bold(picocolors_1.default.cyanBright('b'))}${picocolors_1.default.dim('_')}`;
+    if (plain)
+        return `${mark} BYTE`;
+    const ramp = [picocolors_1.default.cyanBright, picocolors_1.default.cyan, picocolors_1.default.blue, picocolors_1.default.blueBright];
+    const name = 'BYTE'
+        .split('')
+        .map((ch, i) => picocolors_1.default.bold(ramp[i % ramp.length](ch)))
+        .join('');
+    return `${mark}  ${name}`;
 }
 function guard(value, c) {
     if (c.isCancel(value)) {

package/dist/tui/__tests__/home.render.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tui/__tests__/home.render.test.js

@@ -0,0 +1,59 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { render } from 'ink-testing-library';
+import { Home } from '../components/Home.js';
+// Strip ANSI so assertions match the visible text regardless of the per-char gradient coloring
+// (the gradient inserts color codes between letters, so "BYTE" is only contiguous once stripped).
+const ANSI = /\[[0-9;]*m/g;
+const plain = (s) => (s ?? '').replace(ANSI, '');
+const data = {
+    email: 'founder@byte.co',
+    org: 'Bytevion',
+    providers: 2,
+    models: 14,
+    byteKeyMasked: 'byte_sk_live_abcd...wxyz',
+    gateway: 'healthy',
+    savingsSeries: [1, 3, 2, 6, 4, 8, 5],
+    savedTotal: 12.5,
+    tokensTotal: 1_200_000,
+    hitRate: 0.42,
+};
+test('Home (unicode) renders brand, identity, masked key, gateway dot, and sparkline', () => {
+    const { lastFrame, unmount } = render(_jsx(Home, { signedIn: true, data: data, ascii: false, plainColor: false, version: "0.3.0", onDone: () => { } }));
+    const out = plain(lastFrame());
+    unmount();
+    assert.match(out, /BYTE/); // gradient wordmark (contiguous after stripping ANSI)
+    assert.match(out, /optimization gateway/);
+    assert.match(out, /founder@byte\.co/);
+    assert.match(out, /Bytevion/);
+    assert.match(out, /2 connected/);
+    assert.match(out, /14 models/);
+    assert.match(out, /byte_sk_live_abcd\.\.\.wxyz/);
+    assert.ok(out.includes('●'), 'gateway dot glyph present');
+    assert.match(out, /healthy/);
+    // unicode block sparkline ramp
+    assert.ok(/[▁▂▃▄▅▆▇█]/.test(out), 'unicode sparkline present');
+    assert.match(out, /saved/);
+    assert.match(out, /Set up Byte/); // quick-actions menu
+});
+test('Home (ascii) swaps glyphs: classic dot + ascii sparkline, still shows the key', () => {
+    const { lastFrame, unmount } = render(_jsx(Home, { signedIn: true, data: data, ascii: true, plainColor: true, version: "0.3.0", onDone: () => { } }));
+    const out = plain(lastFrame());
+    unmount();
+    assert.match(out, /BYTE/);
+    assert.match(out, /byte_sk_live_abcd\.\.\.wxyz/);
+    assert.match(out, /healthy/);
+    // ascii gateway dot + ascii sparkline ramp; no unicode block glyphs
+    assert.ok(out.includes('[*]'), 'ascii gateway glyph present');
+    assert.ok(!/[▁▂▃▄▅▆▇█●]/.test(out), 'no unicode glyphs in ascii mode');
+    assert.ok(/[.:\-=+*#]/.test(out), 'ascii sparkline ramp present');
+});
+test('Home signed-out shows "not signed in" and a Sign in action', () => {
+    const signedOut = { gateway: 'unknown', savingsSeries: [], savedTotal: 0, tokensTotal: 0 };
+    const { lastFrame, unmount } = render(_jsx(Home, { signedIn: false, data: signedOut, ascii: false, plainColor: false, version: "0.3.0", onDone: () => { } }));
+    const out = plain(lastFrame());
+    unmount();
+    assert.match(out, /not signed in/);
+    assert.match(out, /Sign in/);
+});

package/dist/tui/__tests__/state.test.d.ts

@@ -0,0 +1 @@
+export {};