@amplitude/wizard 1.0.0-beta.2 → 1.0.0

package/dist/src/ui/tui/screens/SlackScreen.js

@@ -1,6 +1,6 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 /**
- * SlackScreen — Amplitude Slack integration setup.
+ * SlackScreen — Amplitude Slack integration setup (v2).
  *
  * Guides the user to connect their Slack workspace to Amplitude.
  * Since the OAuth handshake happens in the browser (Amplitude Settings),
@@ -10,12 +10,12 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
  * Region-aware: EU users need the "Amplitude - EU" Slack app.
  */
 import { Box, Text } from 'ink';
-import { useState, useEffect } from 'react';
-import { useSyncExternalStore } from 'react';
+import { useState, useEffect, useRef } from 'react';
 import { SlackOutcome } from '../store.js';
+import { useWizardStore } from '../hooks/useWizardStore.js';
 import { ConfirmationInput } from '../primitives/index.js';
-import { Colors } from '../styles.js';
-import { fetchAmplitudeUser } from '../../../lib/api.js';
+import { Colors, Icons } from '../styles.js';
+import { fetchSlackInstallUrl, fetchSlackConnectionStatus, } from '../../../lib/api.js';
 import { OUTBOUND_URLS } from '../../../lib/constants.js';
 import { logToFile } from '../../../utils/debug.js';
 import opn from 'opn';
@@ -38,50 +38,75 @@ const markDone = (store, outcome, standalone, onComplete) => {
     }
 };
 export const SlackScreen = ({ store, standalone = false, onComplete, }) => {
-    useSyncExternalStore((cb) => store.subscribe(cb), () => store.getSnapshot());
+    useWizardStore(store);
     const [phase, setPhase] = useState(Phase.Prompt);
-    const [resolvedOrgName, setResolvedOrgName] = useState(store.session.selectedOrgName);
+    const timerRef = useRef(null);
+    // Clear any pending timer on unmount
+    useEffect(() => {
+        return () => {
+            if (timerRef.current !== null)
+                clearTimeout(timerRef.current);
+        };
+    }, []);
     const region = store.session.region ?? 'us';
     const isEu = region === 'eu';
     const appName = isEu ? 'Amplitude - EU' : 'Amplitude';
-    // Fetch org name from the API if it wasn't populated during the SUSI flow
-    // (e.g. returning users, or the standalone `slack` command).
+    // Check if Slack is already connected on mount — auto-complete if so.
     useEffect(() => {
-        logToFile(`[SlackScreen] selectedOrgName=${store.session.selectedOrgName ?? ''} credentials=${store.session.credentials ? 'present' : 'null'} region=${region}`);
-        if (resolvedOrgName) {
-            logToFile(`[SlackScreen] using existing orgName=${resolvedOrgName}`);
-            return;
-        }
+        let cancelled = false;
         const credentials = store.session.credentials;
-        if (!credentials) {
-            logToFile(`[SlackScreen] no credentials — falling back to base URL`);
-            return;
+        const orgId = store.session.selectedOrgId;
+        logToFile(`[SlackScreen] selectedOrgName=${store.session.selectedOrgName ?? ''} credentials=${credentials ? 'present' : 'null'} region=${region}`);
+        // Thunder uses access_token (Hydra-validated), not id_token.
+        const accessToken = credentials?.accessToken;
+        if (accessToken && orgId) {
+            void fetchSlackConnectionStatus(accessToken, region, orgId).then((isConnected) => {
+                if (cancelled)
+                    return;
+                logToFile(`[SlackScreen] slackConnectionStatus=${isConnected}`);
+                if (isConnected) {
+                    setPhase(Phase.Done);
+                    timerRef.current = setTimeout(() => {
+                        if (!cancelled) {
+                            markDone(store, SlackOutcome.Configured, standalone, onComplete);
+                        }
+                    }, 1500);
+                }
+            });
         }
-        logToFile(`[SlackScreen] fetching org name via API`);
-        void fetchAmplitudeUser(credentials.idToken ?? credentials.accessToken, region)
-            .then((info) => {
-            const name = info.orgs[0]?.name ?? null;
-            logToFile(`[SlackScreen] API returned orgs=${JSON.stringify(info.orgs.map((o) => o.name))} using=${name}`);
-            setResolvedOrgName(name);
-        })
-            .catch((err) => {
-            logToFile(`[SlackScreen] API fetch failed: ${err instanceof Error ? err.message : String(err)}`);
-        });
+        return () => {
+            cancelled = true;
+        };
     }, []);
-    const settingsUrl = OUTBOUND_URLS.slackSettings((region ?? 'us'), store.session.selectedOrgId, resolvedOrgName);
+    const zone = (region ?? 'us');
+    const settingsUrl = OUTBOUND_URLS.slackSettings(zone, store.session.selectedOrgId);
+    const [openedUrl, setOpenedUrl] = useState(settingsUrl);
     const handleConnect = () => {
         setPhase(Phase.Opening);
-        opn(settingsUrl, { wait: false }).catch(() => {
-            /* fire-and-forget */
-        });
-        setTimeout(() => setPhase(Phase.Waiting), 800);
+        const credentials = store.session.credentials;
+        const orgId = store.session.selectedOrgId;
+        // Thunder uses access_token (Hydra-validated), not id_token.
+        const accessToken = credentials?.accessToken;
+        // Try the direct Slack OAuth URL first; fall back to settings page.
+        const open = (url) => {
+            setOpenedUrl(url);
+            logToFile(`[SlackScreen] opening ${url === settingsUrl ? 'settings fallback' : 'direct Slack OAuth URL'}`);
+            opn(url, { wait: false }).catch(() => { });
+            timerRef.current = setTimeout(() => setPhase(Phase.Waiting), 800);
+        };
+        if (accessToken && orgId) {
+            void fetchSlackInstallUrl(accessToken, zone, orgId, settingsUrl).then((directUrl) => open(directUrl ?? settingsUrl));
+        }
+        else {
+            open(settingsUrl);
+        }
     };
     const handleSkip = () => {
         markDone(store, SlackOutcome.Skipped, standalone, onComplete);
     };
     const handleDone = () => {
         setPhase(Phase.Done);
-        setTimeout(() => markDone(store, SlackOutcome.Configured, standalone, onComplete), 1500);
+        timerRef.current = setTimeout(() => markDone(store, SlackOutcome.Configured, standalone, onComplete), 1500);
     };
-    return (_jsxs(Box, { flexDirection: "column", flexGrow: 1, children: [_jsx(Text, { bold: true, color: Colors.accent, children: "Slack Integration" }), _jsxs(Box, { marginTop: 1, flexDirection: "column", children: [_jsx(Text, { color: Colors.muted, children: "Connect Amplitude to Slack for chart previews, dashboard sharing," }), _jsx(Text, { color: Colors.muted, children: "and real-time tracking plan notifications." }), isEu && (_jsx(Box, { marginTop: 1, children: _jsx(Text, { color: "yellow", children: "EU region: install the \"Amplitude - EU\" app from the Slack App Directory." }) })), phase === Phase.Prompt && (_jsx(Box, { marginTop: 1, children: _jsx(ConfirmationInput, { message: `Open Amplitude Settings to connect the "${appName}" Slack app?`, confirmLabel: "Open settings", cancelLabel: "Skip for now", onConfirm: handleConnect, onCancel: handleSkip }) })), phase === Phase.Opening && (_jsx(Text, { color: Colors.muted, children: "Opening browser..." })), phase === Phase.Waiting && (_jsxs(Box, { flexDirection: "column", marginTop: 1, children: [_jsxs(Text, { children: ["Browser opened to ", _jsx(Text, { color: "cyan", children: settingsUrl })] }), _jsx(Text, { color: Colors.muted, children: "Go to Settings > Personal Settings > Profile and click \"Connect to Slack\"." }), _jsx(Box, { marginTop: 1, children: _jsx(ConfirmationInput, { message: "Connected to Slack?", confirmLabel: "Yes, connected", cancelLabel: "Skip for now", onConfirm: handleDone, onCancel: handleSkip }) })] })), phase === Phase.Done && (_jsx(Box, { flexDirection: "column", marginTop: 1, children: _jsxs(Text, { color: "green", bold: true, children: ['\u2714', " Slack connected! You'll get chart previews and notifications in Slack."] }) }))] })] }));
+    return (_jsxs(Box, { flexDirection: "column", flexGrow: 1, children: [_jsx(Text, { bold: true, color: Colors.accent, children: "Slack Integration" }), _jsxs(Box, { marginTop: 1, flexDirection: "column", children: [_jsx(Text, { color: Colors.secondary, children: "Connect Amplitude to Slack for chart previews, dashboard sharing," }), _jsx(Text, { color: Colors.secondary, children: "and real-time tracking plan notifications." }), isEu && (_jsx(Box, { marginTop: 1, children: _jsx(Text, { color: Colors.warning, children: "EU region: install the \"Amplitude - EU\" app from the Slack App Directory." }) })), phase === Phase.Prompt && (_jsx(Box, { marginTop: 1, children: _jsx(ConfirmationInput, { message: `Connect the "${appName}" Slack app to your workspace?`, confirmLabel: "Connect", cancelLabel: "Skip for now", onConfirm: handleConnect, onCancel: handleSkip }) })), phase === Phase.Opening && (_jsxs(Text, { color: Colors.active, children: ["Opening browser", Icons.ellipsis] })), phase === Phase.Waiting && (_jsxs(Box, { flexDirection: "column", marginTop: 1, children: [openedUrl === settingsUrl ? (_jsxs(_Fragment, { children: [_jsxs(Text, { color: Colors.body, children: ["Browser opened to", ' ', _jsx(Text, { color: Colors.accent, children: settingsUrl })] }), _jsxs(Text, { color: Colors.secondary, children: ["Go to Settings ", Icons.chevronRight, " Personal Settings", ' ', Icons.chevronRight, " Profile and click \"Connect to Slack\"."] }), _jsxs(Text, { color: Colors.muted, children: ["Docs:", ' ', _jsx(Text, { color: Colors.accent, children: "https://amplitude.com/docs/analytics/integrate-slack" })] })] })) : (_jsxs(_Fragment, { children: [_jsxs(Text, { color: Colors.body, children: ["Browser opened to ", _jsx(Text, { color: Colors.accent, children: "Slack" }), " for authorization."] }), _jsxs(Text, { color: Colors.secondary, children: ["Authorize the ", appName, " app in Slack to complete the connection."] }), _jsxs(Text, { color: Colors.muted, children: ["Docs:", ' ', _jsx(Text, { color: Colors.accent, children: "https://amplitude.com/docs/analytics/integrate-slack" })] })] })), _jsx(Box, { marginTop: 1, children: _jsx(ConfirmationInput, { message: "Connected to Slack?", confirmLabel: "Yes, connected", cancelLabel: "Skip for now", onConfirm: handleDone, onCancel: handleSkip }) })] })), phase === Phase.Done && (_jsx(Box, { flexDirection: "column", marginTop: 1, children: _jsxs(Text, { color: Colors.success, bold: true, children: [Icons.checkmark, " Slack connected! You'll get chart previews and notifications in Slack."] }) }))] })] }));
 };

package/dist/src/ui/tui/session-constants.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Inline copies of runtime constants from wizard-session.ts.
+ *
+ * tsx has an ESM/CJS dual-loading bug: when a module is first loaded as CJS
+ * (e.g. via a top-level import chain) and then loaded again via dynamic
+ * import() as ESM, named exports using the `as const` + same-name type
+ * pattern fail to resolve. This file provides the TUI layer with its own
+ * copies so it never needs runtime imports from wizard-session.ts.
+ *
+ * IMPORTANT: keep these in sync with src/lib/wizard-session.ts.
+ */
+export declare const RunPhase: {
+    readonly Idle: "idle";
+    readonly Running: "running";
+    readonly Completed: "completed";
+    readonly Error: "error";
+};
+export type RunPhase = (typeof RunPhase)[keyof typeof RunPhase];
+export declare const AdditionalFeature: {
+    readonly LLM: "llm";
+};
+export type AdditionalFeature = (typeof AdditionalFeature)[keyof typeof AdditionalFeature];
+export declare const ADDITIONAL_FEATURE_LABELS: Record<AdditionalFeature, string>;
+export declare const McpOutcome: {
+    readonly NoClients: "no_clients";
+    readonly Skipped: "skipped";
+    readonly Installed: "installed";
+    readonly Failed: "failed";
+};
+export type McpOutcome = (typeof McpOutcome)[keyof typeof McpOutcome];
+export declare const SlackOutcome: {
+    readonly Skipped: "skipped";
+    readonly Configured: "configured";
+};
+export type SlackOutcome = (typeof SlackOutcome)[keyof typeof SlackOutcome];
+export declare const OutroKind: {
+    readonly Success: "success";
+    readonly Error: "error";
+    readonly Cancel: "cancel";
+};
+export type OutroKind = (typeof OutroKind)[keyof typeof OutroKind];

package/dist/src/ui/tui/session-constants.js

@@ -0,0 +1,38 @@
+/**
+ * Inline copies of runtime constants from wizard-session.ts.
+ *
+ * tsx has an ESM/CJS dual-loading bug: when a module is first loaded as CJS
+ * (e.g. via a top-level import chain) and then loaded again via dynamic
+ * import() as ESM, named exports using the `as const` + same-name type
+ * pattern fail to resolve. This file provides the TUI layer with its own
+ * copies so it never needs runtime imports from wizard-session.ts.
+ *
+ * IMPORTANT: keep these in sync with src/lib/wizard-session.ts.
+ */
+export const RunPhase = {
+    Idle: 'idle',
+    Running: 'running',
+    Completed: 'completed',
+    Error: 'error',
+};
+export const AdditionalFeature = {
+    LLM: 'llm',
+};
+export const ADDITIONAL_FEATURE_LABELS = {
+    [AdditionalFeature.LLM]: 'LLM analytics',
+};
+export const McpOutcome = {
+    NoClients: 'no_clients',
+    Skipped: 'skipped',
+    Installed: 'installed',
+    Failed: 'failed',
+};
+export const SlackOutcome = {
+    Skipped: 'skipped',
+    Configured: 'configured',
+};
+export const OutroKind = {
+    Success: 'success',
+    Error: 'error',
+    Cancel: 'cancel',
+};

package/dist/src/ui/tui/start-tui.d.ts

@@ -1,5 +1,7 @@
 /**
- * start-tui.ts — Sets up the Ink TUI renderer and InkUI.
+ * start-tui.ts — Sets up the Ink TUI renderer.
+ *
+ * Uses Amplitude brand colors for terminal theming.
  */
 import { WizardStore, Flow } from './store.js';
 import type { WizardSession } from '../../lib/wizard-session.js';

package/dist/src/ui/tui/start-tui.js

@@ -1,5 +1,7 @@
 /**
- * start-tui.ts — Sets up the Ink TUI renderer and InkUI.
+ * start-tui.ts — Sets up the Ink TUI renderer.
+ *
+ * Uses Amplitude brand colors for terminal theming.
  */
 import { render } from 'ink';
 import { createElement } from 'react';
@@ -7,22 +9,22 @@ import { WizardStore, Flow } from './store.js';
 import { InkUI } from './ink-ui.js';
 import { setUI } from '../index.js';
 import { App } from './App.js';
+import { Brand } from './styles.js';
 // ANSI escape sequences
 const RESET_ATTRS = '\x1b[0m';
 const CLEAR_SCREEN = '\x1b[2J';
 const CURSOR_HOME = '\x1b[H';
 const BG_BLACK = '\x1b[48;2;0;0;0m';
-// OSC 10/11: set terminal foreground/background colors (ignored by unsupporting terminals)
-const OSC_FG_BRIGHT = '\x1b]10;#f4f4ff\x07';
-const OSC_BG_DARK = '\x1b]11;#0d0d16\x07';
+// OSC 10/11: set terminal foreground/background to Amplitude brand colors
+const OSC_FG = `\x1b]10;${Brand.gray10}\x07`;
+const OSC_BG = `\x1b]11;${Brand.gray100}\x07`;
 // OSC 110/111: reset to user defaults
 const OSC_FG_RESET = '\x1b]110;\x07';
 const OSC_BG_RESET = '\x1b]111;\x07';
-/** Set foreground bright + background near-black, clear screen, cursor to top-left. */
-const FORCE_DARK = OSC_FG_BRIGHT + OSC_BG_DARK + BG_BLACK + CLEAR_SCREEN + CURSOR_HOME;
+/** Set foreground + background to brand colors, clear screen. */
+const FORCE_DARK = OSC_FG + OSC_BG + BG_BLACK + CLEAR_SCREEN + CURSOR_HOME;
 export function startTUI(version, flow = Flow.Wizard, initialSession) {
-    // Force dark background regardless of terminal theme.
-    // The UI adapts to whatever size the terminal already is.
+    // Apply brand terminal theme
     process.stdout.write(FORCE_DARK);
     const store = new WizardStore(flow);
     store.version = version;
@@ -32,8 +34,10 @@ export function startTUI(version, flow = Flow.Wizard, initialSession) {
     // Swap in the InkUI
     const inkUI = new InkUI(store);
     setUI(inkUI);
-    // Render the Ink app
-    const { unmount: inkUnmount } = render(createElement(App, { store }));
+    // Render the App — exitOnCtrlC lets Ink translate Ctrl+C into process.exit()
+    const { unmount: inkUnmount } = render(createElement(App, { store }), {
+        exitOnCtrlC: true,
+    });
     // Reset terminal colors on exit
     const cleanup = () => {
         process.stdout.write(OSC_FG_RESET + OSC_BG_RESET + RESET_ATTRS + CLEAR_SCREEN + CURSOR_HOME);

package/dist/src/ui/tui/store.d.ts

@@ -10,7 +10,8 @@
  * explicit setters so emitChange() is always called.
  */
 import { TaskStatus, type EventPlanDecision } from '../wizard-ui.js';
-import { type WizardSession, type OutroData, type DiscoveredFeature, AdditionalFeature, McpOutcome, SlackOutcome, RunPhase } from '../../lib/wizard-session.js';
+import { type WizardSession, type OutroData, type DiscoveredFeature } from '../../lib/wizard-session.js';
+import { AdditionalFeature, McpOutcome, SlackOutcome, RunPhase } from './session-constants.js';
 import { WizardRouter, type ScreenName, Screen, Overlay, Flow } from './router.js';
 export { TaskStatus, Screen, Overlay, Flow, RunPhase, McpOutcome, SlackOutcome, };
 export type { ScreenName, OutroData, WizardSession };

package/dist/src/ui/tui/store.js

@@ -11,10 +11,12 @@
  */
 import { atom, map } from 'nanostores';
 import { TaskStatus } from '../wizard-ui.js';
-import { AdditionalFeature, McpOutcome, SlackOutcome, RunPhase, buildSession, } from '../../lib/wizard-session.js';
+import { buildSession, } from '../../lib/wizard-session.js';
+import { AdditionalFeature, McpOutcome, SlackOutcome, RunPhase, } from './session-constants.js';
 import { WizardRouter, Screen, Overlay, Flow, } from './router.js';
 import { analytics, sessionPropertiesCompact } from '../../utils/analytics.js';
-import { FLAG_LLM_ANALYTICS } from '../../lib/feature-flags.js';
+// Inlined to avoid tsx ESM resolution bug with dynamic import().
+const FLAG_LLM_ANALYTICS = 'wizard-llm-analytics';
 export { TaskStatus, Screen, Overlay, Flow, RunPhase, McpOutcome, SlackOutcome, };
 export class WizardStore {
     // ── Internal nanostore atoms ─────────────────────────────────────
@@ -63,6 +65,7 @@ export class WizardStore {
     }
     set session(value) {
         this.$session.set(value);
+        this.emitChange();
     }
     get commandMode() {
         return this.$commandMode.get();
@@ -153,6 +156,19 @@ export class WizardStore {
     setRegion(region) {
         this.$session.setKey('region', region);
         this.$session.setKey('regionForced', false);
+        // Persist region to project-level ampli.json so next run uses the right zone.
+        // Only writes if OrgId/WorkspaceId already exist (otherwise writeAmpliConfig
+        // would create a partial config).
+        const session = this.$session.get();
+        if (session.selectedOrgId && session.selectedWorkspaceId) {
+            void import('../../lib/ampli-config.js').then(({ writeAmpliConfig }) => {
+                writeAmpliConfig(session.installDir, {
+                    OrgId: session.selectedOrgId,
+                    WorkspaceId: session.selectedWorkspaceId,
+                    Zone: region,
+                });
+            });
+        }
         this.emitChange();
     }
     /** Force the RegionSelect screen to re-appear (/region command). */
@@ -360,9 +376,13 @@ export class WizardStore {
         this.$session.setKey('selectedOrgName', org.name);
         this.$session.setKey('selectedWorkspaceId', workspace.id);
         this.$session.setKey('selectedWorkspaceName', workspace.name);
-        // Write ampli.json to the project directory
+        // Write ampli.json to the project directory.
+        // Use session.region (user-confirmed) over pendingAuthCloudRegion (auto-detected)
+        // so that /region changes are respected.
         void import('../../lib/ampli-config.js').then(({ writeAmpliConfig }) => {
-            const zone = this.$session.get().pendingAuthCloudRegion ?? 'us';
+            const zone = this.$session.get().region ??
+                this.$session.get().pendingAuthCloudRegion ??
+                'us';
             writeAmpliConfig(installDir, {
                 OrgId: org.id,
                 WorkspaceId: workspace.id,
@@ -403,7 +423,10 @@ export class WizardStore {
     }
     addDiscoveredFeature(feature) {
         if (!this.session.discoveredFeatures.includes(feature)) {
-            this.session.discoveredFeatures.push(feature);
+            this.$session.setKey('discoveredFeatures', [
+                ...this.session.discoveredFeatures,
+                feature,
+            ]);
             this.emitChange();
         }
     }
@@ -421,11 +444,14 @@ export class WizardStore {
             }
         }
         if (!this.session.additionalFeatureQueue.includes(feature)) {
-            this.session.additionalFeatureQueue.push(feature);
+            this.$session.setKey('additionalFeatureQueue', [
+                ...this.session.additionalFeatureQueue,
+                feature,
+            ]);
         }
         // Feature-specific flags
         if (feature === AdditionalFeature.LLM) {
-            this.session.llmOptIn = true;
+            this.$session.setKey('llmOptIn', true);
         }
         analytics.wizardCapture('Feature Enabled', { feature });
         this.emitChange();

package/dist/src/ui/tui/styles.d.ts

@@ -1,6 +1,80 @@
 /**
- * Shared style constants for TUI layout primitives.
+ * Design tokens — Amplitude brand palette + modern TUI primitives.
+ *
+ * Colors sourced from brand.amplitude.com/creative/color.
+ * Optimised for dark terminal backgrounds (Gray 100 base).
  */
+export declare const Brand: {
+    readonly darkBlue: "#001A4F";
+    readonly blue: "#1E61F0";
+    readonly blueOnDark: "#4083FF";
+    readonly lilac: "#6980FF";
+    readonly violet: "#A373FF";
+    readonly pink: "#FF7D78";
+    readonly amber: "#F59E0B";
+    readonly red: "#F23845";
+    readonly gray100: "#13171A";
+    readonly gray90: "#242A2E";
+    readonly gray80: "#373D42";
+    readonly gray70: "#50565B";
+    readonly gray60: "#697077";
+    readonly gray50: "#868D95";
+    readonly gray40: "#9FA5AD";
+    readonly gray30: "#B9BFC7";
+    readonly gray20: "#D5D9E0";
+    readonly gray10: "#F2F4F8";
+    readonly success: "#34D399";
+    readonly white: "#FFFFFF";
+};
+export declare const Colors: {
+    readonly heading: "#F2F4F8";
+    readonly body: "#B9BFC7";
+    readonly secondary: "#868D95";
+    readonly muted: "#697077";
+    readonly disabled: "#50565B";
+    readonly accent: "#4083FF";
+    readonly accentSecondary: "#6980FF";
+    readonly active: "#A373FF";
+    readonly success: "#34D399";
+    readonly error: "#F23845";
+    readonly warning: "#F59E0B";
+    readonly background: "#13171A";
+    readonly surface: "#242A2E";
+    readonly border: "#373D42";
+    readonly primary: "#4083FF";
+};
+export declare const Icons: {
+    readonly checkmark: "✓";
+    readonly cross: "✗";
+    readonly bullet: "●";
+    readonly bulletOpen: "○";
+    readonly bulletHalf: "◐";
+    readonly squareFilled: "◼";
+    readonly squareOpen: "◻";
+    readonly chevronRight: "›";
+    readonly arrowRight: "→";
+    readonly triangleRight: "▶";
+    readonly triangleSmallRight: "▸";
+    readonly diamond: "◆";
+    readonly diamondOpen: "◇";
+    readonly bar: "│";
+    readonly dash: "─";
+    readonly warning: "⚠";
+    readonly prompt: "❯";
+    readonly dot: "·";
+    readonly ellipsis: "…";
+};
+export declare const SPINNER_FRAMES: readonly ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+export declare const SPINNER_INTERVAL = 200;
+export declare const Layout: {
+    readonly minWidth: 60;
+    readonly maxWidth: 120;
+    readonly paddingX: 2;
+    readonly stepperHeight: 1;
+    readonly headerHeight: 1;
+    readonly hintBarHeight: 1;
+    readonly separatorChar: "─";
+};
 export declare enum HAlign {
     Left = "flex-start",
     Center = "center",
@@ -11,21 +85,3 @@ export declare enum VAlign {
     Center = "center",
     Bottom = "flex-end"
 }
-export declare const Colors: {
-    readonly primary: "#1e61f0";
-    readonly accent: "#1e61f0";
-    readonly success: "green";
-    readonly error: "red";
-    readonly muted: "#cccccc";
-};
-export declare const Icons: {
-    readonly diamond: "◆";
-    readonly diamondOpen: "◇";
-    readonly check: "✔";
-    readonly warning: "⚠";
-    readonly squareFilled: "◼";
-    readonly squareOpen: "◻";
-    readonly triangleRight: "▶";
-    readonly triangleSmallRight: "▸";
-    readonly bullet: "•";
-};

package/dist/src/ui/tui/styles.js

@@ -1,6 +1,106 @@
 /**
- * Shared style constants for TUI layout primitives.
+ * Design tokens — Amplitude brand palette + modern TUI primitives.
+ *
+ * Colors sourced from brand.amplitude.com/creative/color.
+ * Optimised for dark terminal backgrounds (Gray 100 base).
  */
+// ── Amplitude brand palette ──────────────────────────────────────────
+export const Brand = {
+    darkBlue: '#001A4F',
+    blue: '#1E61F0',
+    blueOnDark: '#4083FF', // primary accent on dark backgrounds
+    lilac: '#6980FF', // secondary accent, completed states
+    violet: '#A373FF', // in-progress, active highlights
+    pink: '#FF7D78', // decorative only
+    amber: '#F59E0B', // warnings — visually distinct from red
+    red: '#F23845', // errors only
+    gray100: '#13171A', // terminal background
+    gray90: '#242A2E', // card/surface
+    gray80: '#373D42', // borders, dividers
+    gray70: '#50565B', // disabled text
+    gray60: '#697077', // muted text
+    gray50: '#868D95', // secondary text
+    gray40: '#9FA5AD', // body text
+    gray30: '#B9BFC7', // primary text
+    gray20: '#D5D9E0', // emphasized text
+    gray10: '#F2F4F8', // headings, bright text
+    success: '#34D399', // emerald-400 — completion
+    white: '#FFFFFF',
+};
+// ── Semantic color aliases ───────────────────────────────────────────
+export const Colors = {
+    // Text hierarchy (4 levels)
+    heading: Brand.gray10,
+    body: Brand.gray30,
+    secondary: Brand.gray50,
+    muted: Brand.gray60,
+    disabled: Brand.gray70,
+    // Interactive
+    accent: Brand.blueOnDark,
+    accentSecondary: Brand.lilac,
+    active: Brand.violet,
+    // Status
+    success: Brand.success,
+    error: Brand.red,
+    warning: Brand.amber,
+    // Surfaces
+    background: Brand.gray100,
+    surface: Brand.gray90,
+    border: Brand.gray80,
+    // Legacy compat — screens that import Colors.primary
+    primary: Brand.blueOnDark,
+};
+// ── Icons — modern unicode glyphs ───────────────────────────────────
+export const Icons = {
+    // Progress states
+    checkmark: '✓',
+    cross: '✗',
+    bullet: '●',
+    bulletOpen: '○',
+    bulletHalf: '◐',
+    squareFilled: '◼',
+    squareOpen: '◻',
+    // Navigation
+    chevronRight: '›',
+    arrowRight: '→',
+    triangleRight: '▶',
+    triangleSmallRight: '▸',
+    // Decorative
+    diamond: '◆',
+    diamondOpen: '◇',
+    bar: '│',
+    dash: '─',
+    warning: '⚠',
+    // Indicators
+    prompt: '❯',
+    dot: '·',
+    ellipsis: '…',
+};
+// ── Braille spinner frames ──────────────────────────────────────────
+export const SPINNER_FRAMES = [
+    '⠋',
+    '⠙',
+    '⠹',
+    '⠸',
+    '⠼',
+    '⠴',
+    '⠦',
+    '⠧',
+    '⠇',
+    '⠏',
+];
+export const SPINNER_INTERVAL = 200;
+// ── Layout constants ────────────────────────────────────────────────
+export const Layout = {
+    minWidth: 60,
+    maxWidth: 120,
+    paddingX: 2,
+    stepperHeight: 1,
+    headerHeight: 1,
+    hintBarHeight: 1,
+    separatorChar: '─',
+};
+// ── Alignment ────────────────────────────────────────────────────────
 export var HAlign;
 (function (HAlign) {
     HAlign["Left"] = "flex-start";
@@ -13,21 +113,3 @@ export var VAlign;
     VAlign["Center"] = "center";
     VAlign["Bottom"] = "flex-end";
 })(VAlign || (VAlign = {}));
-export const Colors = {
-    primary: '#1e61f0',
-    accent: '#1e61f0',
-    success: 'green',
-    error: 'red',
-    muted: '#cccccc',
-};
-export const Icons = {
-    diamond: '\u25C6',
-    diamondOpen: '\u25C7',
-    check: '\u2714',
-    warning: '\u26A0',
-    squareFilled: '\u25FC',
-    squareOpen: '\u25FB',
-    triangleRight: '\u25B6',
-    triangleSmallRight: '\u25B8',
-    bullet: '\u2022',
-};

package/dist/src/ui/tui/utils/classify-error.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Error classification for user-facing error messages.
+ *
+ * Transforms cryptic network errors and API failures into
+ * actionable messages with suggestions and docs links.
+ */
+export interface ClassifiedError {
+    message: string;
+    suggestion: string;
+    docsUrl?: string;
+    retryable: boolean;
+}
+/** Classify a caught error into a user-friendly message. */
+export declare function classifyError(err: unknown): ClassifiedError;