@henryavila/blink-tui 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,2429 @@
+import React from 'react';
+import { BoxProps } from 'ink';
+
+/**
+ * blink palettes — the raw colour layer (LAYER 1 of the theming contract).
+ *
+ * A palette is 26 raw colours. It is the **only** thing a theme changes; every
+ * semantic token (`--fg`, `--accent`, `--state-ok`, `--domain-*`, …) maps a
+ * *role* onto one of these slots, and that role→slot grammar is identical for
+ * every theme (see `tokens.ts`). Components never reach for a palette colour;
+ * they consume {@link SemanticTokens}.
+ *
+ * Hex values are a 1:1 port of the `[data-theme]` blocks in the design system's
+ * `colors_and_type.css`. This is the one file allowed to carry raw hex (the
+ * contract checker enforces that).
+ *
+ * Slots run darkest → lightest for surfaces / overlays / text, then the 14
+ * accent hues. Adding a theme = add one palette here and one entry in
+ * `theme.ts` — every component and screen inherits it for free.
+ */
+/** A raw palette colour name — the 26 Catppuccin-shaped slots. */
+type PaletteColor = 'crust' | 'mantle' | 'base' | 'surface0' | 'surface1' | 'surface2' | 'overlay0' | 'overlay1' | 'overlay2' | 'subtext0' | 'subtext1' | 'text' | 'rosewater' | 'flamingo' | 'pink' | 'mauve' | 'red' | 'maroon' | 'peach' | 'yellow' | 'green' | 'teal' | 'sky' | 'sapphire' | 'blue' | 'lavender';
+/** The raw palette shape: every colour name mapped to a hex string. */
+type Palette = Record<PaletteColor, string>;
+/** The slot order — darkest→lightest surfaces, then text tiers, then 14 hues. */
+declare const PALETTE_SLOTS: readonly PaletteColor[];
+/**
+ * neutral — Catppuccin Mocha. blink's calm dark base palette. `contrast`
+ * (neutral+) and `vivid` reuse this exact palette and differ only in how the
+ * intent layer spends it (see `theme.ts`).
+ */
+declare const neutral: Palette;
+/** nord — frost & polar night · cool, low-chroma. */
+declare const nord: Palette;
+/** gruvbox — retro · warm & earthy. */
+declare const gruvbox: Palette;
+/**
+ * tokyonight — saturated indigo night, deepened: a darker canvas so the bright
+ * indigo text & accents pop harder. blink's default theme.
+ */
+declare const tokyonight: Palette;
+/** latte — Catppuccin Latte · the light theme (same roles, inverted luminance). */
+declare const latte: Palette;
+/** Every named base palette, keyed by id — used by the theme registry. */
+declare const palettes: {
+    readonly neutral: Palette;
+    readonly nord: Palette;
+    readonly gruvbox: Palette;
+    readonly tokyonight: Palette;
+    readonly latte: Palette;
+};
+/**
+ * Catppuccin Mocha — kept as a named export for back-compat. Identical to
+ * {@link neutral}; it is the escape hatch for the rare one-off hue.
+ */
+declare const catppuccinMocha: Palette;
+
+/**
+ * Semantic tokens — the layer components actually consume (LAYER 2 of the
+ * theming contract).
+ *
+ * A 1:1 port of the intent `--*` custom properties in the design system's
+ * `colors_and_type.css`. Each token maps a *role* ("focus", "an error", "a
+ * postgres row") onto a palette slot. This grammar is **identical for every
+ * theme** — only the palette underneath it changes — which is what lets a
+ * component recolour for free when the surface theme flips. A component never
+ * sees a palette name and has no colour prop.
+ *
+ * In a terminal there is no CSS background; `bg*` tokens are applied via Ink's
+ * `backgroundColor` prop (used sparingly — selection fills, inverse hotkeys)
+ * and `fg*` tokens via `color`.
+ */
+interface SemanticTokens {
+    bg: string;
+    bgElevated: string;
+    bgSunken: string;
+    bgPanel: string;
+    bgSelected: string;
+    bgFocused: string;
+    bgInverse: string;
+    fg: string;
+    fgMuted: string;
+    fgDim: string;
+    fgFaint: string;
+    fgDisabled: string;
+    fgInverse: string;
+    border: string;
+    borderFocus: string;
+    borderStrong: string;
+    accent: string;
+    accentAlt: string;
+    link: string;
+    highlight: string;
+    stateOk: string;
+    stateErr: string;
+    stateWarn: string;
+    statePending: string;
+    stateDrift: string;
+    stateInfo: string;
+    domainBlue: string;
+    domainAzure: string;
+    domainCyan: string;
+    domainGreen: string;
+    domainRed: string;
+    domainAmber: string;
+    domainYellow: string;
+    domainViolet: string;
+    domainNeutral: string;
+}
+/**
+ * Build the default intent mapping for a palette. This is LAYER 2 of the
+ * contract — the role→slot grammar that never moves between themes. A theme is
+ * just `buildTokens(itsPalette)`, optionally with a few intent overrides layered
+ * on top (see `theme.ts`).
+ */
+declare function buildTokens(p: Palette): SemanticTokens;
+/** Catppuccin Mocha (neutral) semantic tokens — kept as a named export. */
+declare const mochaTokens: SemanticTokens;
+
+/** Dark or light surface — drives a theme picker's grouping, nothing else. */
+type ThemeMode = 'dark' | 'light';
+/**
+ * A blink theme bundles a raw {@link Palette} with its {@link SemanticTokens}
+ * mapping plus picker metadata. The colour scheme is a property of the terminal
+ * *surface*, exactly like a real terminal emulator: a component emits a semantic
+ * role and the surface decides the pixels. Switching themes re-renders every
+ * component from the new tokens — a component cannot diverge because it owns no
+ * colour. The surface is owned in exactly one place (the `ThemeProvider`).
+ */
+interface Theme {
+    /** Stable id, e.g. `"tokyonight"`. */
+    id: string;
+    /** Human label for a picker, e.g. `"tokyo night"`. */
+    label: string;
+    /** Dark or light. */
+    mode: ThemeMode;
+    /** One-line description for a picker. */
+    blurb: string;
+    /** Raw palette (escape hatch for one-off hues). */
+    palette: Palette;
+    /** Role-mapped tokens — what components consume. */
+    tokens: SemanticTokens;
+    /** @deprecated alias of {@link id}, kept for back-compat. */
+    name: string;
+}
+/** Just the picker-facing fields of a {@link Theme}. */
+type ThemeMeta = Pick<Theme, 'id' | 'label' | 'mode' | 'blurb'>;
+/** neutral — Catppuccin Mocha · the calm dark default palette. */
+declare const mocha: Theme;
+/** blink's default theme — `tokyonight`. Used when no theme is selected. */
+declare const defaultTheme: Theme;
+/** Resolve a theme by id (falls back to {@link defaultTheme} for an unknown id). */
+declare function getTheme(id: string): Theme;
+/** True if a theme id is registered. */
+declare function hasTheme(id: string): boolean;
+/** Every registered theme, in picker order. */
+declare function allThemes(): Theme[];
+/** Picker-facing metadata for every theme, in order. */
+declare function listThemes(): ThemeMeta[];
+/** A runtime theme definition — mirrors the design system's `registerTheme()`. */
+interface ThemeDefinition {
+    /** Stable id (required). */
+    id: string;
+    /** Picker label. Defaults to `id`. */
+    label?: string;
+    /** Dark or light. Defaults to `'dark'`. */
+    mode?: ThemeMode;
+    /** One-line picker description. */
+    blurb?: string;
+    /** Base theme id to inherit the palette from. Defaults to `'neutral'`. */
+    extends?: string;
+    /** Palette slots to override — only list what you change; the rest inherit. */
+    palette?: Partial<Palette>;
+    /** Intent-token overrides (the "vivid"/"neutral+" trick). */
+    intent?: Partial<SemanticTokens>;
+}
+/**
+ * Register (or replace) a theme at runtime, from an app's own code — no
+ * framework edits, mirroring `registerGlyphs`. Only list the slots you want to
+ * change; everything else inherits from `extends` (default `neutral`), so a
+ * handful of accent overrides is already a complete theme:
+ *
+ * ```ts
+ * registerTheme({
+ *   id: 'dracula', label: 'dracula', blurb: 'classic purple dark',
+ *   extends: 'neutral',
+ *   // hex strings for just the slots you change — the rest inherit from `extends`
+ *   palette: { base, surface1, text, lavender, red, green },
+ * });
+ * // then drive it through the ThemeProvider / useThemeControls().setTheme('dracula')
+ * ```
+ *
+ * Returns the assembled {@link Theme}. Unlike the web engine there is no global
+ * "current theme" to `select` — the active theme is owned by the surface (the
+ * `ThemeProvider`); switch with `useThemeControls().setTheme(id)`.
+ */
+declare function registerTheme(def: ThemeDefinition): Theme;
+
+/**
+ * The three rendering modes every blink glyph supports.
+ *
+ * - `nerd`    — full Nerd Font vocabulary, incl. private-use domain logos.
+ * - `unicode` — safe Unicode glyphs (✓ ✗ ◯ …); domain glyphs degrade to text.
+ * - `ascii`   — `[x] [!] [ ]` etc. for CI, `TERM=dumb`, and fontless terminals.
+ *
+ * An app never breaks: if the font is missing, the worst case is text-shaped
+ * fallbacks, never tofu boxes (□). Resolved once at startup by
+ * `detectIconSet()` and carried in the theme context.
+ */
+type IconSet = 'nerd' | 'unicode' | 'ascii';
+/**
+ * A glyph's colour, expressed as **intent** — a semantic token key, never a raw
+ * hue. A domain glyph paints through a hue family (`'domainBlue'`,
+ * `'domainGreen'`, …) so it keeps its relative identity *and* recolours with the
+ * active theme. State / nav contract glyphs leave this unset — their colour
+ * comes from the state-intent map, not the glyph entry.
+ */
+type GlyphColor = keyof SemanticTokens;
+/** A single glyph's three rendering variants, plus an optional owned colour. */
+interface GlyphVariants {
+    nerd: string;
+    unicode: string;
+    ascii: string;
+    /**
+     * The colour this glyph renders in, owned at registration (the "intent, not
+     * style" rule for domain glyphs) and given as a {@link SemanticTokens} key.
+     * Components resolve it through the active theme via `glyphColor(name)` and
+     * fall back to a muted token when absent.
+     */
+    color?: GlyphColor;
+}
+
+/**
+ * What every blink app reads from context: the active {@link Theme}, the
+ * resolved {@link IconSet}, and the controls to switch theme. The theme is the
+ * one mutable piece of the surface — exactly like a terminal emulator's scheme.
+ * The icon set is decided once at boot.
+ */
+interface BlinkContextValue {
+    theme: Theme;
+    iconSet: IconSet;
+    /** Switch the active theme by id or by a {@link Theme} object. */
+    setTheme: (theme: string | Theme) => void;
+    /** Every registered theme's picker metadata, in order. */
+    themes: ThemeMeta[];
+}
+interface ThemeProviderProps {
+    /**
+     * The initial theme — a {@link Theme} object or a registered theme id. When
+     * omitted, blink starts on its default (`tokyonight`). Components read the
+     * *active* theme, which a picker can switch via `useThemeControls()`.
+     */
+    theme?: Theme | string;
+    /** @deprecated alias of {@link theme} when passing an id. */
+    initialTheme?: string;
+    /**
+     * Resolved icon set. Pass the result of `detectIconSet()` (awaited at boot).
+     * Defaults to `'unicode'` — the safe mode that renders everywhere.
+     */
+    iconSet?: IconSet;
+    children: React.ReactNode;
+}
+/**
+ * Wrap a blink app once, at the root, above `<App/>` — the surface that owns the
+ * colour scheme:
+ *
+ * ```tsx
+ * const iconSet = await detectIconSet();
+ * render(
+ *   <ThemeProvider iconSet={iconSet} theme="tokyonight">
+ *     <App />
+ *   </ThemeProvider>
+ * );
+ * ```
+ *
+ * The provider holds the active theme in state; a theme picker calls
+ * `useThemeControls().setTheme(id)` and the whole tree recolours from the new
+ * tokens. No component sets, reads, or branches on the theme — consistency is
+ * structural, not a matter of discipline.
+ */
+declare function ThemeProvider({ theme, initialTheme, iconSet, children, }: ThemeProviderProps): React.ReactElement;
+/** Full context: `{ theme, iconSet, setTheme, themes }`. */
+declare function useBlink$1(): BlinkContextValue;
+/** The active theme. */
+declare function useTheme(): Theme;
+/** Just the semantic tokens — the common case in components. */
+declare function useTokens(): SemanticTokens;
+/** The resolved icon set (`'nerd' | 'unicode' | 'ascii'`). */
+declare function useIconSet(): IconSet;
+/** The theme switch + list — what a theme picker drives. */
+interface ThemeControls {
+    /** The active theme. */
+    theme: Theme;
+    /** The active theme's id. */
+    themeId: string;
+    /** Switch theme by id or {@link Theme}. */
+    setTheme: (theme: string | Theme) => void;
+    /** Every registered theme's metadata, in picker order. */
+    themes: ThemeMeta[];
+}
+/**
+ * The theme controls for a picker — the TUI analogue of the design system's
+ * `BlinkTheme.setTheme / getTheme / THEMES`. The picker is the *only* place that
+ * should switch the theme; ordinary components just read {@link useTokens}.
+ */
+declare function useThemeControls(): ThemeControls;
+
+/** Tier 1 · COMMON_DOMAINS — the dev-tool domains most TUIs reuse. */
+declare const COMMON_DOMAINS: {
+    database: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainNeutral";
+    };
+    mysql: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainAzure";
+    };
+    postgresql: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainBlue";
+    };
+    redis: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainRed";
+    };
+    docker: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainCyan";
+    };
+    github: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainNeutral";
+    };
+    git: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainAmber";
+    };
+    ssh: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainYellow";
+    };
+    nodejs: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainGreen";
+    };
+    php: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainViolet";
+    };
+    python: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainYellow";
+    };
+    vim: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainGreen";
+    };
+    apple: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainNeutral";
+    };
+    linux: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainYellow";
+    };
+    ubuntu: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainAmber";
+    };
+    font: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainNeutral";
+    };
+    ai: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "accent";
+    };
+    bolt: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainAmber";
+    };
+};
+/** A domain name from the {@link COMMON_DOMAINS} (Tier 1) pack. */
+type CommonDomainName = keyof typeof COMMON_DOMAINS;
+/** languages — programming languages / runtimes. */
+declare const LANGUAGES: {
+    javascript: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainYellow";
+    };
+    typescript: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainBlue";
+    };
+    python: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainYellow";
+    };
+    php: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainViolet";
+    };
+    ruby: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainRed";
+    };
+    rust: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainAmber";
+    };
+    go: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainCyan";
+    };
+    java: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainAmber";
+    };
+    nodejs: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainGreen";
+    };
+    cpp: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainBlue";
+    };
+    c: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainBlue";
+    };
+    csharp: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainViolet";
+    };
+    html: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainAmber";
+    };
+    css: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainBlue";
+    };
+    react: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainCyan";
+    };
+    vue: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainGreen";
+    };
+};
+/** databases — engines & stores. */
+declare const DATABASES: {
+    database: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainNeutral";
+    };
+    postgresql: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainBlue";
+    };
+    mysql: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainAzure";
+    };
+    mariadb: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainAzure";
+    };
+    redis: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainRed";
+    };
+    mongodb: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainGreen";
+    };
+    sqlite: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainBlue";
+    };
+};
+/** cloud — cloud / devops / infra. */
+declare const CLOUD: {
+    aws: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainAmber";
+    };
+    cloud: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainCyan";
+    };
+    server: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainNeutral";
+    };
+    docker: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainCyan";
+    };
+    kubernetes: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainBlue";
+    };
+    nginx: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainGreen";
+    };
+};
+/** editors — editors / IDEs. */
+declare const EDITORS: {
+    vim: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainGreen";
+    };
+    neovim: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainGreen";
+    };
+    vscode: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainBlue";
+    };
+    sublime: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainAmber";
+    };
+    emacs: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainViolet";
+    };
+};
+/** os — operating systems / distros. */
+declare const OS: {
+    apple: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainNeutral";
+    };
+    linux: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainYellow";
+    };
+    ubuntu: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainAmber";
+    };
+    debian: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainRed";
+    };
+    arch: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainBlue";
+    };
+    fedora: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainBlue";
+    };
+    windows: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainCyan";
+    };
+    android: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainGreen";
+    };
+};
+/** companies — brands / vendors. */
+declare const COMPANIES: {
+    github: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainNeutral";
+    };
+    gitlab: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainAmber";
+    };
+    bitbucket: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainBlue";
+    };
+    google: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainBlue";
+    };
+    microsoft: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainCyan";
+    };
+    apple: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainNeutral";
+    };
+    slack: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainViolet";
+    };
+    npm: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainRed";
+    };
+    git: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainAmber";
+    };
+    claude: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "accent";
+    };
+};
+/** frameworks — web / app frameworks. */
+declare const FRAMEWORKS: {
+    react: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainCyan";
+    };
+    vue: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainGreen";
+    };
+    angular: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainRed";
+    };
+    svelte: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainAmber";
+    };
+    laravel: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainRed";
+    };
+    django: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainGreen";
+    };
+    rails: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainRed";
+    };
+    dotnet: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainViolet";
+    };
+    bootstrap: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainViolet";
+    };
+    jquery: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainBlue";
+    };
+};
+/** files — files & formats. */
+declare const FILES: {
+    file: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainNeutral";
+    };
+    folder: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainBlue";
+    };
+    folder_open: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainBlue";
+    };
+    json: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainYellow";
+    };
+    yaml: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainAmber";
+    };
+    markdown: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainNeutral";
+    };
+    pdf: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainRed";
+    };
+    image: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainGreen";
+    };
+    archive: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainAmber";
+    };
+    lock: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainYellow";
+    };
+};
+/** social — social & messaging brands. */
+declare const SOCIAL: {
+    slack: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainViolet";
+    };
+    discord: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainBlue";
+    };
+    telegram: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainCyan";
+    };
+    twitter: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainCyan";
+    };
+    youtube: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainRed";
+    };
+    linkedin: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainBlue";
+    };
+    reddit: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainAmber";
+    };
+    mastodon: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainViolet";
+    };
+};
+/** actions — generic UI action glyphs (not in the Tier 0 contract). */
+declare const ACTIONS: {
+    search: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainNeutral";
+    };
+    filter: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainNeutral";
+    };
+    settings: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainNeutral";
+    };
+    trash: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "stateErr";
+    };
+    download: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainBlue";
+    };
+    upload: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainBlue";
+    };
+    refresh: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "stateInfo";
+    };
+    edit: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainNeutral";
+    };
+    bell: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainYellow";
+    };
+    link: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "link";
+    };
+};
+/**
+ * system — general-purpose system / OS / UI domain glyphs.
+ *
+ * The recurring "thing" glyphs that aren't a brand (→ {@link COMPANIES}), an
+ * action verb (→ {@link ACTIONS}), or a file format (→ {@link FILES}): a
+ * terminal, a globe, a home, a key, an envelope. Every `nerd` codepoint is a
+ * classic Font Awesome value; each carries a width-1 `unicode` fallback
+ * (verified via `string-width`) so it never tofus on a non–Nerd-Font terminal.
+ */
+declare const SYSTEM: {
+    terminal: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainGreen";
+    };
+    code: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainBlue";
+    };
+    globe: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainCyan";
+    };
+    home: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainNeutral";
+    };
+    key: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainYellow";
+    };
+    mail: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainBlue";
+    };
+    phone: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainGreen";
+    };
+    package: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainAmber";
+    };
+    sync: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainCyan";
+    };
+    text: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainNeutral";
+    };
+    tools: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainNeutral";
+    };
+};
+/** packages — package managers. */
+declare const PACKAGES: {
+    npm: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainRed";
+    };
+    yarn: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainBlue";
+    };
+    cargo: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainAmber";
+    };
+    pip: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainYellow";
+    };
+    composer: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainYellow";
+    };
+    homebrew: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainYellow";
+    };
+    apt: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainRed";
+    };
+};
+/**
+ * devinfra — recurring local dev-infrastructure tools. These show up often
+ * enough as raw `nf()` registrations in apps to earn CURATED entries (the bar
+ * for Tier 2). `laravel` is promoted from {@link FRAMEWORKS} and `valet` aliases
+ * its glyph; `code-server` aliases the vscode family from {@link EDITORS}. The
+ * genuine newcomers — tailscale / syncthing / mosh — carry safe `{ unicode,
+ * ascii }` fallbacks so they never tofu without a Nerd Font; their `nerd`
+ * codepoint is left empty (a curator must verify it) and the glyph degrades to
+ * its unicode form until then.
+ *
+ * PRIME DIRECTIVE still holds: this pack is OPT-IN content, registered by no app
+ * automatically. A one-app-only glyph stays in that app — these are here because
+ * they recur, not to make every app carry them.
+ *
+ * Two single-cell divergences from the design system, for the same reason as
+ * {@link COMMON_DOMAINS} `bolt` (see also `glyphs/glyphs.ts`): the DS unicode
+ * fallbacks `⚡` (ngrok) and `✉` (mailpit) are emoji-presentation and
+ * double-wide — they break the one-glyph-one-cell grid in unicode mode. blink
+ * substitutes the width-1 `↯` and `⊠`; `string-width` is the arbiter.
+ */
+declare const DEVINFRA: {
+    laravel: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainRed";
+    };
+    valet: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainRed";
+    };
+    'code-server': {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainBlue";
+    };
+    ngrok: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainAmber";
+    };
+    mailpit: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainAmber";
+    };
+    tailscale: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainCyan";
+    };
+    syncthing: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainViolet";
+    };
+    mosh: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+        color: "domainAmber";
+    };
+};
+/** Tier-2 pack directory — used by pickers / docs to label & iterate packs. */
+declare const GLYPH_PACKS: Record<string, Record<string, GlyphVariants>>;
+
+/**
+ * Tier 3 — the raw Nerd Font index (the escape hatch).
+ *
+ * A flat map of canonical Nerd Font names → codepoint (hex string), following
+ * the upstream `glyphnames.json` convention (source-prefixed: `fa-`, `dev-`,
+ * `seti-`, `pl-`, …). It carries **no curation**: no unicode/ascii fallback, no
+ * semantic colour. `nf(name)` returns the Nerd Font char only; on a non–Nerd-Font
+ * terminal it has nothing to degrade to. Use it as a deliberate escape hatch —
+ *
+ * ```ts
+ * nf('fa-rocket');                              // → the glyph, or '' if unknown
+ * registerGlyphs({ deploy: { nf: 'fa-rocket' } }); // muted, ascii derived
+ * ```
+ *
+ * — and for anything an app shows often, promote it to a curated Tier 1/2 entry
+ * (give it a colour + fallbacks) instead of leaning on the raw index.
+ *
+ * Shipped here is a **verified seed** (~130 of the most-used glyphs). The full
+ * production index (~10k) is generated from upstream `glyphnames.json`; merge it
+ * at boot with {@link registerNerdIndex} so the bundle stays lean (the seed
+ * always wins — nothing curated is clobbered).
+ */
+/** name → hex codepoint. Mutable so a generated full index can be merged in. */
+declare const NERD_INDEX: Record<string, string>;
+/** Source prefixes in the seed → human label (for a glyph picker's filter). */
+declare const NERD_INDEX_SOURCES: Record<string, string>;
+/**
+ * Merge a generated full index into {@link NERD_INDEX}. The seed always wins, so
+ * curated entries are never clobbered; keys starting with `_` (e.g. `_meta`) are
+ * skipped. This is the Node-side analogue of the web engine's lazy fetch — the
+ * app loads the generated `glyph-index.json` (~10k) and hands it over once at boot.
+ */
+declare function registerNerdIndex(full: Record<string, string>): void;
+/**
+ * Resolve a raw codepoint to a char — by index name (`'dev-laravel'`) or by a
+ * bare hex codepoint (`'e73f'`). Returns `''` for an unknown name (never throws,
+ * never tofu-by-surprise on lookup).
+ */
+declare function nfChar(nameOrHex: string | null | undefined): string;
+/** `nf('fa-rocket')` → the Nerd Font char (nerd-only, no fallback), or `''`. */
+declare function nf(name: string): string;
+/** True if a raw index name is known. */
+declare function nfHas(name: string): boolean;
+
+/**
+ * The blink glyph ENGINE — the Tier 0 contract (state · nav · box · spinner ·
+ * blocks) plus the extensible registry that powers Tiers 1–3.
+ *
+ * ─ Fonts vs. registry ─ The *drawing* of every Nerd Font glyph already lives in
+ * the user's terminal **font** (CaskaydiaMono ships ~10k icons in the Private
+ * Use Area); printing a codepoint is enough. What blink owns is the **registry**:
+ * the map from a semantic NAME to a glyph plus its curated `{ unicode, ascii }`
+ * fallbacks and its semantic `color` (a {@link SemanticTokens} key). Those three
+ * are curation — they can't be auto-derived for 10k icons — which is why blink
+ * *degrades* a glyph (nerd → unicode → ascii) rather than rendering tofu.
+ *
+ * ─ Contract vs. content ─ Tier 0 (this file) is the contract: it appears in
+ * every blink app and never changes, so it's the only thing seeded into the
+ * registry at import. Domain glyphs (Tiers 1–3) are CONTENT: the app opts in via
+ * {@link registerGlyphs} (`packs.ts`) or the raw index (`nerdIndex.ts`, `nf()`).
+ * blink core ships **zero** domain glyphs registered.
+ */
+declare const stateGlyphs: {
+    check: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+    };
+    cross: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+    };
+    circle: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+    };
+    half: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+    };
+    checkboxOn: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+    };
+    checkboxOff: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+    };
+    checkboxLock: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+    };
+    warn: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+    };
+    rerun: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+    };
+};
+/** Navigation glyphs — focus carets, expand chevrons, relation arrows. */
+declare const navGlyphs: {
+    focus: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+    };
+    collapsed: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+    };
+    expanded: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+    };
+    depends: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+    };
+    flow: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+    };
+    back: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+    };
+    moreAbove: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+    };
+    moreBelow: {
+        nerd: string;
+        unicode: string;
+        ascii: string;
+    };
+};
+/** Built-in glyph names — the contract set, before any app registrations. */
+type BuiltinGlyphName = keyof typeof stateGlyphs | keyof typeof navGlyphs;
+/** A raw glyph with no curated colour renders muted — neutral, never semantic. */
+declare const DEFAULT_GLYPH_COLOR: GlyphColor;
+/** A registered glyph with no curated unicode fallback degrades to this mark. */
+declare const DEFAULT_UNICODE = "\u25C6";
+/** `deriveAscii('postgresql')` → `'[po]'` — used when an entry omits an ascii fallback. */
+declare function deriveAscii(name: string): string;
+/**
+ * What {@link registerGlyphs} accepts per entry — three shapes, all coexisting:
+ *   - verbose : `{ nerd:'', unicode:'◆', ascii:'[la]', color:'domainRed' }`
+ *   - easy    : `{ nf:'dev-laravel', color:'domainRed' }`  ← codepoint from the index
+ *   - raw cp  : `{ cp:'e73f', color:'domainRed' }`         ← codepoint from hex
+ *   - string  : `''`                                  ← nerd only, all defaults
+ * Anything omitted is filled in: `unicode → ◆`, `ascii → derived`, `color → muted`.
+ */
+type GlyphInput = string | (Partial<GlyphVariants> & {
+    nf?: string;
+    cp?: string;
+});
+/**
+ * Register app-domain glyphs (or override built-ins). Call once at startup,
+ * before the first render. Accepts one or more maps — later wins — so an app can
+ * take a pack then override the few entries it cares about. Each entry's `color`
+ * is owned here, at REGISTRATION, never per render site, so a row says "this is a
+ * postgres row", not "paint this blue":
+ *
+ * ```ts
+ * registerGlyphs(COMMON_DOMAINS);                       // Tier 1 pack
+ * registerGlyphs(LANGUAGES, DATABASES);                 // many Tier 2 packs
+ * registerGlyphs({ deploy: { nf: 'fa-rocket' } });      // easy form, from the index
+ * registerGlyphs({ database: { color: 'domainCyan' } }); // override one
+ * ```
+ */
+declare function registerGlyphs(...maps: Array<Record<string, GlyphInput> | undefined>): void;
+/** Single-entry convenience for {@link registerGlyphs}. */
+declare function registerGlyph(name: string, entry: GlyphInput): void;
+/** True if a glyph name is registered. */
+declare function hasGlyph(name: string): boolean;
+/** Every registered glyph name, sorted — for pickers & tests. */
+declare function registeredNames(): string[];
+/**
+ * Resolve a glyph name to a string for the given icon set, with the
+ * `nerd → unicode → ascii` fallback. Unknown names return the name itself (so a
+ * typo or an unregistered domain renders visibly as text rather than tofu).
+ * Prefer the {@link useGlyph} hook inside components — it reads the icon set from
+ * context.
+ */
+declare function glyph(name: string, set: IconSet): string;
+/**
+ * The colour a registered glyph renders in — a {@link SemanticTokens} key, owned
+ * at registration. Resolve it through the active theme: `tokens[glyphColor(name)
+ * ?? 'fgMuted']`. Returns `undefined` for an unregistered name or a contract
+ * glyph (whose colour comes from the state-intent map, not the entry).
+ */
+declare function glyphColor(name: string): GlyphColor | undefined;
+/** A resolved intent: a glyph NAME (resolve via {@link glyph}) + a colour token key. */
+interface StateIntent {
+    /** Registry glyph name — resolve with `useGlyph()` / `glyph(name, set)`. */
+    glyph: string;
+    /** Semantic token key for the colour — read `tokens[token]`. */
+    token: keyof SemanticTokens;
+}
+/** Row / detail status intents → glyph + colour. The house mapping, central. */
+declare const stateIntents: {
+    installed: {
+        glyph: string;
+        token: "stateOk";
+    };
+    ok: {
+        glyph: string;
+        token: "stateOk";
+    };
+    done: {
+        glyph: string;
+        token: "stateOk";
+    };
+    missing: {
+        glyph: string;
+        token: "stateErr";
+    };
+    error: {
+        glyph: string;
+        token: "stateErr";
+    };
+    err: {
+        glyph: string;
+        token: "stateErr";
+    };
+    failed: {
+        glyph: string;
+        token: "stateErr";
+    };
+    drift: {
+        glyph: string;
+        token: "stateDrift";
+    };
+    partial: {
+        glyph: string;
+        token: "stateDrift";
+    };
+    warn: {
+        glyph: string;
+        token: "stateWarn";
+    };
+    idempotent: {
+        glyph: string;
+        token: "stateInfo";
+    };
+    pending: {
+        glyph: string;
+        token: "statePending";
+    };
+    info: {
+        glyph: string;
+        token: "stateInfo";
+    };
+};
+/** A semantic state name the framework knows how to draw. */
+type StateName = keyof typeof stateIntents;
+/** Resolve a state intent name to its glyph + colour token, or `null` if unknown. */
+declare function stateGlyph(name: string): StateIntent | null;
+/** Selection intents → checkbox glyph + colour. `locked` is selected + non-toggle. */
+declare const selectionIntents: {
+    selected: {
+        glyph: string;
+        token: "accent";
+    };
+    unselected: {
+        glyph: string;
+        token: "fgDim";
+    };
+    locked: {
+        glyph: string;
+        token: "fgMuted";
+    };
+};
+/** A selection intent name. */
+type SelectionName = keyof typeof selectionIntents;
+/** A complete set of box-drawing characters for one border style. */
+interface BoxChars {
+    tl: string;
+    tr: string;
+    bl: string;
+    br: string;
+    h: string;
+    v: string;
+}
+/**
+ * blink's border styles. The house style is **single-line, rounded** corners;
+ * `single` (square) is a legacy opt-out. There is **no double-line border** — it
+ * reads dated, and focus / modals are signalled by colour, not a heavier line.
+ * `ascii` is the fontless fallback (`+ - |`).
+ */
+declare const boxStyles: {
+    single: {
+        tl: string;
+        tr: string;
+        bl: string;
+        br: string;
+        h: string;
+        v: string;
+    };
+    rounded: {
+        tl: string;
+        tr: string;
+        bl: string;
+        br: string;
+        h: string;
+        v: string;
+    };
+    ascii: {
+        tl: string;
+        tr: string;
+        bl: string;
+        br: string;
+        h: string;
+        v: string;
+    };
+};
+type BoxStyleName = 'single' | 'rounded';
+/**
+ * Pick the right box characters for a style + icon set. In `ascii` mode every
+ * style collapses to the ASCII set (`+ - |`); rounded corners aren't ASCII-safe.
+ */
+declare function boxChars(style: BoxStyleName, set: IconSet): BoxChars;
+/** Spinner frames per icon set. Braille for nerd/unicode, classic for ascii. */
+declare const spinnerFrames: {
+    readonly braille: readonly ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+    readonly ascii: readonly ["|", "/", "-", "\\"];
+};
+/** Frames for the given icon set. */
+declare function spinnerFor(set: IconSet): readonly string[];
+/** Block-shade ramp — the only "gradient" the contract allows. */
+declare const blocks: {
+    readonly full: "█";
+    readonly dark: "▓";
+    readonly medium: "▒";
+    readonly light: "░";
+    readonly cursor: "▎";
+};
+/**
+ * Horizontal eighth-block ramp — the sub-cell material for a determinate
+ * {@link ProgressBar}. Indexed by eighths filled (`0` = empty, `8` = a full
+ * cell `█`). Left-to-right partials, the same family as {@link blocks}.
+ */
+declare const blocksH: readonly [" ", "▏", "▎", "▍", "▌", "▋", "▊", "▉", "█"];
+
+/**
+ * Returns a resolver bound to the icon set in context, so components don't have
+ * to thread `iconSet` everywhere:
+ *
+ * ```tsx
+ * const g = useGlyph();
+ * <Text color={tokens.stateOk}>{g('check')}</Text>
+ * ```
+ */
+declare function useGlyph(): (name: string) => string;
+
+interface DetectOptions {
+    /**
+     * Path to a JSON file holding `{ "iconSet": "nerd" | "unicode" | "ascii" }`.
+     * Defaults to `~/.config/blink/preferences.json`. This is the per-user
+     * answer saved by a first-run probe (apps own the probe UI).
+     */
+    configPath?: string;
+    /**
+     * Absolute paths to "a Nerd Font is installed" marker files. If any exists,
+     * detection resolves to `nerd`. Apps pass their own markers (e.g. a font
+     * bundle's install receipt) — blink ships none, staying agnostic.
+     */
+    markerFiles?: string[];
+    /** Override `process.env` (testing). */
+    env?: NodeJS.ProcessEnv;
+}
+/**
+ * Resolve which {@link IconSet} to render with, once, at app startup.
+ *
+ * The cascade (first match wins):
+ *   1. hard env override — `BLINK_ICON_SET`, or `BLINK_NERD_FONT=1|0`, `BLINK_ASCII=1`
+ *   2. saved per-user preference — `configPath`
+ *   3. app-state marker — a font bundle's install receipt (`markerFiles`)
+ *   4. terminal hints — `WT_SESSION`, `ITERM_PROFILE`, `TERM_PROGRAM`, …
+ *   5. CI / dumb terminals → `ascii`
+ *   6. safe default → `unicode`
+ *
+ * Never throws and never blocks: a blink app always gets a usable icon set.
+ */
+declare function detectIconSet(opts?: DetectOptions): Promise<IconSet>;
+
+/**
+ * Terminal cell width of a string, used to pin {@link List} columns and to drop
+ * {@link Footer} chips that don't fit — so the character grid stays aligned (the
+ * contract's "strict character-cell grid").
+ *
+ * Delegates to the same `string-width` Ink uses for its own layout, so the
+ * widths computed here always agree with how Ink sizes its boxes — including
+ * the wide glyphs in the palette (`⚠`, `☑` measure two cells) and the
+ * multi-char `ascii` fallbacks (`[x]` measures three). Hand-rolling this drifts
+ * from Ink and makes fixed-width cells truncate or misalign.
+ *
+ * Caveat: a terminal configured with "ambiguous = wide" (common in CJK locales)
+ * may render some glyphs wider than string-width reports; that's a terminal
+ * setting no layout-time measurement can see.
+ */
+declare function cellWidth(str: string): number;
+
+interface Dimensions {
+    columns: number;
+    rows: number;
+}
+/**
+ * The live terminal size in character cells, updating on `SIGWINCH` (resize).
+ *
+ * blink's design target is 100×30; the mobile-mosh fallback is 60×20. Layouts
+ * read this to switch between the full multi-pane view and a stacked one.
+ * Falls back to 80×24 when the stream isn't a TTY (pipes, CI).
+ *
+ * Tip: size your root box to `rows - 1`, not `rows`. An output exactly as tall
+ * as the terminal makes Ink redraw with a full-screen clear every render
+ * (visible flicker on each keypress); one spare line keeps it on the smooth
+ * incremental path.
+ */
+declare function useStdoutDimensions(): Dimensions;
+
+/**
+ * The cursor blink — blink's one sanctioned text animation.
+ *
+ * Returns a boolean that toggles at `hz` (default 1 Hz) with `step-end` timing:
+ * fully on for half the period, fully off for the other half. No fade, by
+ * contract. Pass `active=false` to hold it visible (e.g. an unfocused input).
+ *
+ * ```tsx
+ * const on = useBlink();
+ * <Text>{value}{on ? '▎' : ' '}</Text>
+ * ```
+ */
+declare function useBlink(active?: boolean, hz?: number): boolean;
+
+interface SpinnerOptions {
+    /** Advance only while true. Defaults to true. */
+    active?: boolean;
+    /** Frame interval in ms. Defaults to 80 (the contract's spinner cadence). */
+    intervalMs?: number;
+}
+/**
+ * A monotonically-increasing frame counter for spinners, advancing every
+ * `intervalMs` (default 80 ms) while `active`. The caller picks the glyph:
+ *
+ * ```tsx
+ * const frame = useSpinnerFrame({ active: syncing });
+ * const frames = spinnerFor(iconSet);
+ * <Text color={tokens.stateInfo}>{frames[frame % frames.length]}</Text>
+ * ```
+ *
+ * Returns a counter rather than a glyph so it's icon-set agnostic and trivially
+ * testable. Resets to 0 whenever it goes inactive.
+ */
+declare function useSpinnerFrame(opts?: SpinnerOptions): number;
+
+interface UseListWindowOptions {
+    /** Total number of rows. */
+    rowCount: number;
+    /** Index of the focused row; `null` / `< 0` = no focus-follow (window holds). */
+    focusedIndex: number | null;
+    /** Max rows the viewport renders, INCLUDING any marker rows. */
+    height: number;
+    /**
+     * Context rows kept between the caret and the edge before the window scrolls.
+     * Default `0` → the caret may reach the last content row, and moving past it
+     * scrolls the window by one (vim `scrolloff=0`).
+     */
+    scrolloff?: number;
+    /**
+     * Reserve a chrome row for the `▴`/`▾` "N more" marker on an overflowing side.
+     * Default `true`. When `false`, the window still scrolls but clips silently.
+     */
+    overflowMarkers?: boolean;
+}
+interface ListWindow {
+    /** First visible CONTENT row index (inclusive). Slice with `rows.slice(start, end)`. */
+    start: number;
+    /** One past the last visible content row. */
+    end: number;
+    /** Rows hidden above / below the window (0 = none). Drive the markers off these. */
+    aboveCount: number;
+    belowCount: number;
+}
+/**
+ * Pure windowing math: given the previous window start, where does the window
+ * sit now so it (a) fits `height`, (b) contains `focusedIndex`, and (c) reserves
+ * a chrome row for each overflow marker that shows? Exported for unit tests and
+ * for callers windowing something other than {@link useListWindow}.
+ *
+ * Markers are **separate chrome rows**, not overlays: `content + markers` always
+ * equals `height`, so the window never exceeds its container, and `aboveCount` /
+ * `belowCount` are the exact hidden-row counts (no off-by-one against a marker).
+ * The caret is always inside the content band, so the focused row is never
+ * hidden behind a "N more".
+ *
+ * Marker reservation and the window position are mutually dependent (a marker
+ * costs a content row, which can move the window, which can flip a marker), so
+ * the start is settled over a few passes, then the markers are finalised from
+ * the settled start so the returned values are always self-consistent.
+ *
+ * One consequence: the *single* step where a marker first appears shifts the
+ * window by two rows (the new marker claims a content row, so the band shrinks
+ * by one as focus moves by one). Every other step is a smooth 1/row scroll —
+ * the steady-state behaviour. The alternative (markers overlaying edge rows)
+ * keeps 1/row but muddies the hidden-row counts; clean counts win here.
+ */
+declare function computeWindow(prevStart: number, rowCount: number, focusedIndex: number | null, height: number, scrolloff?: number, overflowMarkers?: boolean): ListWindow;
+/**
+ * Headless windowing for a fixed-height viewport over a flat row array — the
+ * engine behind a windowed {@link List}, and reusable on its own for any
+ * keyboard-paged list.
+ *
+ * It owns the window **offset** across renders (view-state, like a scroll
+ * position — *not* the focus/selection state the contract reserves for the app)
+ * and re-derives the window each render to keep `focusedIndex` visible. The hook
+ * never sees a keystroke: the app moves `focusedIndex`, the window follows. With
+ * `scrolloff = 0` the caret travels to the edge of the viewport and only then
+ * does the window scroll.
+ *
+ * ```tsx
+ * const win = useListWindow({ rowCount: rows.length, focusedIndex, height: 20 });
+ * const visible = rows.slice(win.start, win.end);
+ * ```
+ */
+declare function useListWindow(opts: UseListWindowOptions): ListWindow;
+
+interface UseListNavigationOptions {
+    /** Ordered row ids. */
+    ids: string[];
+    /** Controlled focus. Omit to let the hook own it (seeded to the first id). */
+    focusedId?: string | null;
+    onFocusChange?: (id: string) => void;
+    /** Wrap first↔last instead of clamping at the ends. Default false. */
+    wrap?: boolean;
+}
+interface ListNavigation {
+    focusedId: string | null;
+    /** Index of `focusedId` in `ids` (`-1` when none) — feed to {@link useListWindow}. */
+    focusedIndex: number;
+    focusNext: () => void;
+    focusPrev: () => void;
+    focusFirst: () => void;
+    focusLast: () => void;
+    focusTo: (id: string) => void;
+}
+/**
+ * Headless focus movement for a list — clamp/wrap at the ends, next/prev/first/
+ * last/seek. Exposes **intent methods**, never a baked-in key handler: the app
+ * owns `useInput` and maps its own keys (`j/k`, arrows, …) to these, so blink
+ * never embeds one app's keymap. Separate from {@link useListSelection} because
+ * focus movement is generic to any list, including read-only menus that never
+ * select.
+ *
+ * ```tsx
+ * const nav = useListNavigation({ ids });
+ * useInput((_, key) => {
+ *   if (key.downArrow) nav.focusNext();
+ *   if (key.upArrow) nav.focusPrev();
+ * });
+ * <List rows={rows} focusedId={nav.focusedId} height={20} />
+ * ```
+ */
+declare function useListNavigation(opts: UseListNavigationOptions): ListNavigation;
+
+type SelectionMode = 'single' | 'multi';
+interface UseListSelectionOptions {
+    /** The selectable row ids (used for bounds only; selection is by id). */
+    ids: string[];
+    /** `'single'` keeps exactly one selected; `'multi'` toggles a subset. */
+    mode: SelectionMode;
+    /** multi/single: minimum that must stay selected — deselecting below is blocked. */
+    min?: number;
+    /** multi: maximum selectable — selecting above is blocked. */
+    max?: number;
+    /** Initially selected ids. */
+    initial?: Iterable<string>;
+    onChange?: (selected: Set<string>) => void;
+}
+interface ListSelection {
+    /** Feed straight to `<List selectedIds={...} />`. */
+    selectedIds: Set<string>;
+    isSelected: (id: string) => boolean;
+    /** Toggle `id`. Returns `false` when blocked by `min`/`max` (and sets `blocked`). */
+    toggle: (id: string) => boolean;
+    /** Single-select: make `id` the only selected row. */
+    selectOnly: (id: string) => void;
+    /** Clear all (blocked when `min` would be violated). */
+    clear: () => void;
+    /** True when the last operation was blocked by `min`/`max` — render as `Input.error`. */
+    blocked: boolean;
+}
+/**
+ * Headless selection logic for a list — the toggle, the single-select
+ * invariant, and the min/max guards that every consumer otherwise hand-rolls.
+ * It owns the selected `Set`; the **app still owns the keys** and renders the
+ * existing presentational {@link List}. Pair with {@link useListNavigation} for
+ * the cursor; this hook is only about *what is selected*.
+ *
+ * ```tsx
+ * const sel = useListSelection({ ids, mode: 'multi', min: 1 });
+ * useInput((input) => { if (input === ' ' && focusedId) sel.toggle(focusedId); });
+ * <List rows={rows} selectedIds={sel.selectedIds} focusedId={focusedId} />
+ * ```
+ */
+declare function useListSelection(opts: UseListSelectionOptions): ListSelection;
+
+/**
+ * Pane emphasis, by PURPOSE — the consumer declares what a pane *means*, blink
+ * draws it. There is exactly one border shape in the house style (single-line,
+ * rounded), so tone never changes the geometry, only the colour:
+ *
+ * - `resting` — a pane at rest (muted border).
+ * - `focus`   — the focused pane (border + title recoloured lavender).
+ * - `error`   — an error / destructive pane (border + title red).
+ */
+type PaneTone = 'resting' | 'focus' | 'error';
+/**
+ * Legacy border treatments. Kept only so older call sites keep working while
+ * they migrate to {@link PaneTone}. `'double'` is gone from the house style and
+ * now renders as the rounded default; `'square'` is the one legacy shape opt-out.
+ * @deprecated pass `tone` instead.
+ */
+type PaneVariant = 'default' | 'rounded' | 'square' | 'double' | 'error';
+interface PaneProps {
+    /** Title shown inside the top border: `╭─ title ──────╮`. Keep ≤ 18 chars. */
+    title?: string;
+    /**
+     * Semantic emphasis. The framework owns the border colour, the title colour,
+     * and the (always rounded) shape. Default `'resting'`.
+     */
+    tone?: PaneTone;
+    /**
+     * @deprecated use `tone="focus"`. A focused pane gets the lavender border.
+     * Kept as a back-compat alias; `tone` wins when both are set.
+     */
+    focused?: boolean;
+    /**
+     * @deprecated use `tone`. `'error'` ⇒ `tone="error"`, `'square'` ⇒ the legacy
+     * square shape; every other value falls through to the rounded house style.
+     */
+    variant?: PaneVariant;
+    /** Flex grow factor (default 1 — panes fill available space). */
+    flexGrow?: number;
+    /** Flex basis (e.g. `'56%'`). */
+    flexBasis?: BoxProps['flexBasis'];
+    /** Fixed width in cells. */
+    width?: BoxProps['width'];
+    /** Fixed height in cells. */
+    height?: BoxProps['height'];
+    /** Minimum height in cells. */
+    minHeight?: BoxProps['minHeight'];
+    children?: React.ReactNode;
+}
+/**
+ * A box-drawn rectangle with an optional title in the top border — the
+ * analogue of a "card" in blink (panes don't lift, shadow, or change shape).
+ *
+ * Borders are real box-drawing glyphs. Ink's native border renders the
+ * full-height left/right sides and the bottom edge; the top edge is drawn by
+ * hand so the title can sit *inside* it. The two halves share a width, so they
+ * join into one continuous frame. Focus and elevation are signalled by **border
+ * colour** alone — the shape is identical across tones, so the layout never
+ * shifts when a pane gains or loses focus.
+ */
+declare function Pane({ title, tone, focused, variant, flexGrow, flexBasis, width, height, minHeight, children, }: PaneProps): React.ReactElement;
+
+/**
+ * One row's worth of data — declared as **intent**, never style. A row says what
+ * it MEANS (`state="installed"`, `selected`, `domain="postgresql"`) and the
+ * framework resolves the glyph and its colour from the house tokens. The
+ * consumer never passes a raw glyph or a raw colour. (The focus caret is the one
+ * exception — it is chrome, not data.)
+ */
+interface ListRowData {
+    /** Stable identity, used for focus/selection lookups and React keys. */
+    id: string;
+    /** The row's primary text, in `fg` (or `fgDim` when `muted`). */
+    label: string;
+    /**
+     * Semantic status name → the framework draws its glyph + colour:
+     * `installed | ok | done | missing | error | drift | partial | idempotent |
+     * pending | warn | info`. See `stateGlyph()`.
+     */
+    state?: string;
+    /** Selection intent → `☑ / ☐`. Presence of the field (even `false`) opts the row into the checkbox column. */
+    selected?: boolean;
+    /** Required, non-toggle (implies selected) → `▣`. */
+    locked?: boolean;
+    /** A **registered** domain glyph name → the glyph + its colour, owned at registration. */
+    domain?: string;
+    /** Right-aligned consequence / aside text (content), in `fgDim`. */
+    meta?: string;
+    /** De-emphasise the whole row (e.g. a disabled / required label). */
+    muted?: boolean;
+}
+interface ListRowProps {
+    row: ListRowData;
+    /** Carries the `►` caret + `bgFocused` fill. Wins over `selected`. */
+    focused?: boolean;
+    /** Draws the `bgSelected` fill (only when not also focused). */
+    selected?: boolean;
+    /**
+     * Which intent columns this row reserves, and their fixed cell widths, so the
+     * glyph columns line up down the whole list. `List` computes these from the
+     * widest cell in each column; a standalone `ListRow` derives them from itself.
+     */
+    showCheckbox?: boolean;
+    showState?: boolean;
+    showDomain?: boolean;
+    caretWidth?: number;
+    checkboxWidth?: number;
+    stateWidth?: number;
+    domainWidth?: number;
+}
+interface ListProps {
+    rows: ListRowData[];
+    /** Id of the row that holds the nav caret. */
+    focusedId?: string | null;
+    /** Ids drawn with the selection fill. */
+    selectedIds?: Set<string>;
+    /**
+     * Max rows to render, including any overflow-marker rows. Omit to render every
+     * row. When set and `rows` exceeds it, List shows a window that always contains
+     * `focusedId` and scrolls as focus nears an edge — keyboard-paged, never
+     * mouse-scrolled (see the contract).
+     */
+    height?: number;
+    /** Context rows kept before the window scrolls. Default 0 (scroll at the edge). */
+    scrolloff?: number;
+    /** Draw `▴ N more` / `▾ N more` on overflowing sides. Default true. */
+    overflowMarkers?: boolean;
+}
+/**
+ * A single list row — a caret column, then the optional intent columns
+ * (checkbox · state · domain), the label, then the meta pushed right. The
+ * focused row fills with `bgFocused`; a selected-but-unfocused row fills with
+ * `bgSelected`. No hover, by contract.
+ *
+ * Each intent column is a **fixed-width cell** (truncating, never wrapping), so
+ * labels stay column-aligned no matter how wide a row's glyph (or its multi-char
+ * `ascii`/`unicode` fallback) renders. The glyph and its colour are resolved
+ * here from the row's intent — the consumer hands over meaning, not pixels.
+ */
+declare function ListRow({ row, focused, selected, showCheckbox, showState, showDomain, caretWidth, checkboxWidth, stateWidth, domainWidth, }: ListRowProps): React.ReactElement;
+/**
+ * A vertical stack of {@link ListRow}s — blink's plain list. Exactly one row may
+ * be focused (`focusedId`); any number may be selection-filled (`selectedIds`).
+ * Rows are pure **intent** ({@link ListRowData}); the list resolves the glyphs.
+ *
+ * List sizes the caret / checkbox / state / domain columns to the widest cell
+ * across all rows and passes those widths down, so every row shares one grid —
+ * the fix for ragged columns when glyphs fall back to variable-width text.
+ */
+declare function List({ rows, focusedId, selectedIds, height, scrolloff, overflowMarkers, }: ListProps): React.ReactElement;
+
+interface HeaderProps {
+    /**
+     * Leading accent mark. Defaults to the blink cursor block `▎`. Pass a node
+     * (e.g. a blinking `<Cursor />`) for the live mark, or a string for a static
+     * one; `null` drops the mark entirely.
+     */
+    mark?: React.ReactNode;
+    /** Screen title, in `fg`. */
+    title: string;
+    /** Optional aside, rendered `· subtitle` in `fgMuted`. */
+    subtitle?: string;
+    /** Optional node flush-right — status, counts, a delta summary. */
+    right?: React.ReactNode;
+}
+/**
+ * The one-row status bar that tops a blink screen: a lavender mark, a title
+ * (with an optional `· subtitle`), and a right-aligned status slot. It recurs on
+ * every wizard / app screen — the brand chrome — so it is a primitive, not
+ * per-app code. One line, never wraps; the subtitle truncates first.
+ */
+declare function Header({ mark, title, subtitle, right, }: HeaderProps): React.ReactElement;
+
+/** One term/value row. Carries intent (`state`, `muted`) — never a raw glyph or colour. */
+interface DescriptionItem {
+    /** The label in the gutter (`fgDim`). Omit for a full-width value line. */
+    term?: string;
+    /** The value text. */
+    value: string;
+    /**
+     * A semantic status name → the framework draws its glyph + colour before the
+     * value (`installed`, `missing`, `drift`, `pending`, …). See `stateGlyph()`.
+     */
+    state?: string;
+    /** De-emphasise the value (e.g. a description line) → rendered in `fgMuted`. */
+    muted?: boolean;
+}
+interface DescriptionListProps {
+    /** The rows. */
+    items?: DescriptionItem[];
+    /** Term-column width in cells. Default 10. */
+    gutter?: number;
+}
+/**
+ * A key/value block aligned to a character gutter — the generic shape behind any
+ * detail pane or summary screen. The complement to {@link List}: List is a
+ * vertical menu of peers, DescriptionList is the attributes of one thing.
+ *
+ * INTENT, NOT STYLE: a row may carry a semantic `state` (→ framework glyph +
+ * colour) and a `muted` flag (→ de-emphasised value); it never takes a raw glyph
+ * or a raw colour. Term-less rows render as a full-width value line.
+ */
+declare function DescriptionList({ items, gutter, }: DescriptionListProps): React.ReactElement;
+
+interface LogViewProps {
+    /** The full line buffer. LogView renders only the tail that fits `height`. */
+    lines: string[];
+    /** Viewport height in rows, including an overflow-marker row when one shows. */
+    height: number;
+    /** Follow the newest line (default). `false` freezes the window as lines append. */
+    follow?: boolean;
+    /** Wrap long lines to the viewport width (default) vs truncate them. */
+    wrap?: boolean;
+    /** Viewport width in cells. Omit to measure the rendered box (Ink `measureElement`). */
+    width?: number;
+}
+/**
+ * A bottom-anchored, height-bounded viewport over an ever-growing line stream —
+ * subprocess output, a build log, a chat transcript. The newest lines stay
+ * pinned to the bottom; older lines fall off the top with a dim `▴ N more`
+ * marker. The mirror of a windowed {@link List}: that one follows a *focused*
+ * row, this one follows the *tail*.
+ *
+ * Unlike Ink's `<Static>` (append-only scrollback that grows past the screen),
+ * LogView is a fixed region. The app owns the subprocess and feeds `lines`;
+ * LogView only renders the tail — the window advancing on new data is content
+ * re-render, not motion, under the one-animation contract.
+ *
+ * When `wrap` is on, a logical line spans `ceil(width / cellWidth)` visual rows,
+ * so the tail is counted in **visual rows**, not array entries — which needs a
+ * width. Pass `width` (it's known inside a sized `Pane`); otherwise LogView
+ * measures its own box, approximating for the first frame.
+ */
+declare function LogView({ lines, height, follow, wrap, width, }: LogViewProps): React.ReactElement;
+
+/** One hotkey: a key chip plus its terse description. */
+interface HotkeyDef {
+    /** The key, lowercased: `'tab'`, `'enter'`, `'q'`, `'/'`, `'?'`. */
+    k: string;
+    /** Terse lowercase label for what the key does (`'switch pane'`). */
+    desc: string;
+}
+interface FooterProps {
+    /** Hotkeys, laid left-to-right with a 3-cell gap between them. */
+    keys?: HotkeyDef[];
+    /** Optional status node, flush-right in faint text (e.g. `'6 of 8'`). */
+    right?: React.ReactNode;
+    /**
+     * Cells of breathing room above the bar. House default is `1` so the footer
+     * never butts up against the content above it; pass `0` to pin it flush.
+     */
+    marginTop?: number;
+}
+/**
+ * The always-visible hotkey bar pinned to the bottom row. A single sunken-fill
+ * line: hotkeys flush-left (3-cell gaps), an optional status node flush-right
+ * in faint text. Never wraps — the bar is one cell tall by contract.
+ *
+ * When the chips + status don't fit the terminal width, whole chips are dropped
+ * from the right rather than clipped mid-word (a chip reading `he` or a `q` with
+ * no label is worse than one fewer key). Apps should order `keys` by importance.
+ *
+ * Ink's `<Box>` has no fill (only `<Text>` takes `backgroundColor`), and a
+ * terminal cell can't layer — every cell is one glyph with one fg + one bg. So
+ * the solid sunken bar of the design system is built by making the *gaps and
+ * padding themselves* background-carrying spaces inside a single `<Text>`, with
+ * the inverse key chips nested as `<Text>` that override the bg. That paints the
+ * whole row edge-to-edge rather than only the cells under the glyphs.
+ *
+ * A measurable (string) `right` is flush-right with an exact space fill. An
+ * unmeasurable React-node `right` falls back to the flex layout below (its
+ * middle gap stays unfilled), since the fill width can't be computed.
+ */
+declare function Footer({ keys, right, marginTop }: FooterProps): React.ReactElement;
+
+interface CursorProps {
+    /** Blink while true (default), hold solid while false. */
+    active?: boolean;
+    /** Block colour. Defaults to `tokens.fg`. */
+    color?: string;
+}
+/**
+ * The blink caret — a `▎` block that toggles at 1 Hz with step-end timing,
+ * blink's one sanctioned text animation. The "off" frame is a single space, so
+ * the caret occupies a stable cell and never nudges the line around it.
+ */
+declare function Cursor({ active, color }: CursorProps): React.ReactElement;
+interface InputProps {
+    /** Title shown inside the top border. Keep ≤ 18 chars. */
+    title?: string;
+    /** Current field value. The app owns key handling; this is presentational. */
+    value?: string;
+    /** Hint shown in `fgDisabled` while the value is empty. */
+    placeholder?: string;
+    /** Focused fields round their border and trail a live cursor. */
+    focused?: boolean;
+    /** Error message — promotes the border to red and shows a line below. */
+    error?: string;
+}
+/**
+ * A single-line text field: a {@link Pane} wrapping one row of value (or
+ * placeholder), with a {@link Cursor} trailing while focused. Value-driven and
+ * presentational — the app feeds `value` and owns the keys.
+ *
+ * INTENT, NOT STYLE: the consumer never picks a border treatment; the field
+ * derives its pane `tone` from its own state — `error` → red, `focused` →
+ * lavender, otherwise resting. An error also prints a `✗ message` line below.
+ */
+declare function Input({ title, value, placeholder, focused, error, }: InputProps): React.ReactElement;
+
+/** One footer action: a key chip plus its label. */
+interface DialogAction {
+    /** The hotkey shown in the chip, e.g. `'y'`. */
+    key: string;
+    /** What the key does, e.g. `'delete'`. */
+    label: string;
+    /** The default/confirming action — renders its chip in inverse-accent. */
+    primary?: boolean;
+}
+/** Dialog emphasis, by purpose. `'default'` is a focused (lavender) modal. */
+type DialogTone = 'default' | 'error';
+interface DialogProps {
+    /** Shown inside the top border. Keep ≤ 18 chars (it nests in the frame). */
+    title: string;
+    /**
+     * Semantic emphasis: `'default'` is a focused (lavender) modal, `'error'`
+     * recolours it red. The consumer never picks the shape — it is always the
+     * rounded house pane.
+     */
+    tone?: DialogTone;
+    /** Body rows, one `<Text>` line each — the convenience for plain-text bodies. */
+    lines?: string[];
+    /** Rich body (a `List`, glyph rows, a small form). Wins over `lines` when both given. */
+    children?: React.ReactNode;
+    /** Footer actions, laid out left-to-right with a 2-cell gap. */
+    actions?: DialogAction[];
+    /** Fixed dialog width in cells. */
+    width?: number;
+}
+/**
+ * A centred modal — the analogue of a "confirm" overlay in blink. There is no
+ * backdrop, blur, or fade; Ink has no absolute positioning or z-index, so the
+ * app renders `<Dialog/>` as a *full-screen replacement layer* instead of a
+ * floating panel — it simply replaces focus.
+ *
+ * The frame is a fixed-width rounded {@link Pane}: lavender (focus tone) by
+ * default, red for `tone="error"` — elevation is colour, never a heavier line.
+ * The body is a blank line, the supplied `lines`, another blank line, then the
+ * actions row. The primary action's key chip renders in inverse-accent video;
+ * the rest sit muted.
+ */
+declare function Dialog({ title, tone, lines, children, actions, width, }: DialogProps): React.ReactElement;
+
+/** Notice severity — the only thing the consumer expresses. */
+type BannerTone = 'info' | 'success' | 'warn';
+interface BannerProps {
+    /** Rich body. Wins over `text` when both are given. */
+    children?: React.ReactNode;
+    /** Plain-text body, the common case. */
+    text?: string;
+    /** Intent — the framework picks the leading glyph + its colour. Default `'info'`. */
+    tone?: BannerTone;
+}
+/**
+ * A one-line, non-blocking notice in the content flow — "auto-selected X",
+ * "saved", "3 items skipped". The middle ground between the blocking
+ * {@link Dialog} and the persistent `Footer`: it acknowledges a side effect
+ * without stealing focus.
+ *
+ * INTENT, NOT STYLE: the consumer picks a `tone`; the framework owns the leading
+ * glyph and the colour. Per the contract, semantic colour lives on the glyph —
+ * the message text stays calm (`fgMuted`). Purely presentational: no timer, no
+ * auto-dismiss (the app mounts/unmounts it, keeping the one-animation contract
+ * clean).
+ */
+declare function Banner({ children, text, tone }: BannerProps): React.ReactElement;
+
+interface SpinnerProps {
+    /** Advance the spinner. When false, the first frame is shown statically. Defaults to true. */
+    active?: boolean;
+    /** Override the glyph colour. Defaults to the info state token. */
+    color?: string;
+    /** Frame interval in ms. Defaults to 80 (the contract's spinner cadence). */
+    intervalMs?: number;
+}
+/**
+ * A one-cell animated spinner — braille for nerd/unicode, classic `| / - \` for
+ * ascii. Frames advance every `intervalMs` while `active`; when inactive it
+ * rests on frame 0 with no timer running.
+ *
+ * The frame counter comes from {@link useSpinnerFrame} and the glyph table from
+ * {@link spinnerFor}, so the component stays icon-set agnostic — context decides
+ * which alphabet renders.
+ */
+declare function Spinner({ active, color, intervalMs }: SpinnerProps): React.ReactElement;
+
+interface ProgressBarProps {
+    /** Progress in `0..1` (clamped). */
+    value: number;
+    /** Bar length in cells. */
+    width: number;
+    /** Filled colour. Defaults to `tokens.accent`. */
+    color?: string;
+    /** Track (empty rail) colour. Defaults to `tokens.border` (surface1), matching the design system's `bar-rest`. */
+    trackColor?: string;
+    /** Append a `  NN%` readout in `fgDim` after the bar. Defaults to `true`, matching the design system. */
+    showPercent?: boolean;
+}
+/**
+ * A determinate progress bar built from the horizontal eighth-block ramp
+ * ({@link blocksH}) — the complement to the indeterminate {@link Spinner}. The
+ * fractional cell renders to one of eight partials for sub-cell precision.
+ *
+ * The empty remainder is a visible `░` rail in the track colour (the design
+ * system's `[████░░░░]` treatment), not blank space — so the bar always reads
+ * as a bar, full or not.
+ *
+ * The `ascii` icon set has no partials, so it degrades to whole `#` cells (the
+ * fractional eighth is dropped) over a blank track, like every other glyph that
+ * falls back.
+ */
+declare function ProgressBar({ value, width, color, trackColor, showPercent }: ProgressBarProps): React.ReactElement;
+
+/**
+ * The states a {@link ProgressList} line can be in — the execution vocabulary of
+ * any apply / migrate / sync / build. Each maps to **intent**, never style: the
+ * framework owns the glyph (or the live spinner) and its semantic colour.
+ *
+ * - `pending` — queued, not started (`◯`, dim).
+ * - `running` — executing now → the one sanctioned animation, a {@link Spinner}.
+ * - `ok` / `done` — finished cleanly (`✓`, green).
+ * - `failed` / `error` — finished badly (`✗`, red).
+ * - `waiting` — blocked on a *manual* action and may stay so indefinitely
+ *   (`◐`, warn). It reads apart from `running` so a step paused on, say, a device
+ *   pairing is legible. (The pause prompt itself is an app `Dialog`, not a
+ *   primitive.)
+ * - `skipped` — deliberately not run (`◌`, disabled).
+ */
+type ProgressState = 'pending' | 'running' | 'ok' | 'done' | 'failed' | 'error' | 'waiting' | 'skipped';
+/** One step / task in a {@link ProgressList}. Intent only — no glyph, no colour. */
+interface ProgressItem {
+    /** Stable identity, used for the active-line lookup and React keys. */
+    id: string;
+    /** The step's primary text. */
+    label: string;
+    /** A **registered** domain glyph name → its glyph + owned colour (optional column). */
+    domain?: string;
+    /** Execution status → the framework draws the glyph / spinner + colour. */
+    state: ProgressState;
+    /** Right-aligned aside (elapsed time, hint, count …), in `fgDim`. */
+    meta?: string;
+}
+interface ProgressListProps {
+    /** The steps, in execution order. */
+    items: ProgressItem[];
+    /** Id of the active (executing) line — fills with `bgFocused`, kept in view. */
+    activeId?: string | null;
+    /**
+     * Max lines to render, including any overflow-marker rows. Omit to render every
+     * line. When set and `items` exceeds it, the window always contains `activeId`
+     * and follows it as it advances — keyboard-paged, like {@link List}.
+     */
+    height?: number;
+    /** Draw `▴ N more` / `▾ N more` on overflowing sides. Default true. */
+    overflowMarkers?: boolean;
+    /**
+     * Advance the running line's spinner. Defaults to true; pass `false` for a
+     * static frame (snapshots / non-interactive renders), matching every other
+     * blink motion.
+     */
+    animate?: boolean;
+}
+/**
+ * A list of steps that transition through {@link ProgressState}s, with a live
+ * {@link Spinner} on the running line — the universal apply / migrate / sync /
+ * build view. The complement to {@link ProgressBar}: the bar is the aggregate
+ * (compose one above this), this is the per-line detail.
+ *
+ * INTENT, NOT STYLE: a line carries a `state` (and an optional `domain` name);
+ * the framework owns the glyph (or the spinner), its colour, the label tier, the
+ * active-line fill, and the `▴/▾` overflow chrome. The consumer never passes a
+ * glyph or a colour. The list windows to keep the active line in view, exactly
+ * like {@link List}, since a queue is usually taller than its pane.
+ */
+declare function ProgressList({ items, activeId, height, overflowMarkers, animate, }: ProgressListProps): React.ReactElement;
+
+/**
+ * Form — a vertical set of LABELLED fields, each a control of a known `kind`,
+ * navigated by keyboard and validated by declared constraints. The universal
+ * "options / config screen" primitive (git config, tokens, versions, flags).
+ * Without it every app re-derives checkbox / radio / toggle from the raw
+ * SELECTION glyphs — exactly the divergence blink exists to avoid.
+ *
+ * INTENT, NOT STYLE: a field declares its `kind`; blink owns the glyph, the
+ * colour, the focus fill, the required marker, and the error line. The consumer
+ * never passes a glyph or a colour. `text` / `secret` reuse {@link Input} (the
+ * `▎` cursor, placeholder, error, focus border); Form is the layer above it.
+ */
+/** The control a field renders — the ONLY look prop. */
+type FieldKind = 'text' | 'secret' | 'toggle' | 'select' | 'multiselect';
+/** A choice for a `select` / `multiselect` — a bare id, or an id with a label. */
+type ChoiceInput = string | {
+    id: string;
+    label?: string;
+};
+/** A resolved choice (id + display label). */
+interface ResolvedChoice {
+    id: string;
+    label: string;
+}
+/** One field in a {@link Form}. */
+interface FieldSpec {
+    /** Stable key into the values object. */
+    name: string;
+    /** Which control to draw — the only look prop. */
+    kind: FieldKind;
+    /** The label above the control. */
+    label: string;
+    /** Required → a warn `*` marker and an empty-value error. */
+    required?: boolean;
+    /** Placeholder for `text` / `secret`, shown while empty. */
+    placeholder?: string;
+    /** Choices for `select` / `multiselect`. */
+    choices?: ChoiceInput[];
+    /** Derive choices from another field's current value (its selected ids). */
+    optionsFrom?: string;
+    /** `multiselect` lower bound — Form refuses to deselect below it. */
+    min?: number;
+    /** `multiselect` upper bound — Form refuses to select above it. */
+    max?: number;
+}
+/** A single field's value: a string (text/secret/select), a set of ids (multiselect), or a flag (toggle). */
+type FieldValue = string | string[] | boolean | undefined;
+/** The form's value map, keyed by field name. */
+type FormValues = Record<string, FieldValue>;
+/** Validation result — `ok` plus a per-field message map. */
+interface FormValidation {
+    ok: boolean;
+    errors: Record<string, string>;
+}
+/** A keyboard focus stop. text/secret/toggle = one per field; select/multiselect = one per choice. */
+interface FocusStop {
+    /** `name` for single-stop fields, `name::choiceId` for choice fields. */
+    id: string;
+    name: string;
+    kind: FieldKind;
+    choiceId: string | null;
+}
+/**
+ * `optionsFrom` resolves the choices of a select/multiselect from another
+ * field's current value (its selected ids); otherwise normalises the field's
+ * own `choices` to `{ id, label }`.
+ */
+declare function resolveChoices(field: FieldSpec, values?: FormValues): ResolvedChoice[];
+/**
+ * Ordered focus stops. text/secret/toggle yield one stop (`id = name`);
+ * select/multiselect yield one stop PER choice (`id = name::choiceId`), so nav
+ * moves linearly choice → choice → next field.
+ */
+declare function buildStops(fields: FieldSpec[], values?: FormValues): FocusStop[];
+/**
+ * Validate `required` (any kind) and `multiselect` `min`. Pure — used by
+ * {@link useFormNavigation}'s `commit()` and renderable directly into a {@link Form}.
+ */
+declare function validateForm(fields: FieldSpec[], values?: FormValues): FormValidation;
+/** What {@link useFormNavigation} returns — the intents the app wires keys to. */
+interface FormNavigation {
+    /** Current focus-stop id (`name` or `name::choiceId`), or null when empty. */
+    focusId: string | null;
+    /** The current focus stop. */
+    focusStop: FocusStop | null;
+    /** All stops, in order. */
+    stops: FocusStop[];
+    /** Move to the next / previous control (linear). */
+    next: () => void;
+    prev: () => void;
+    /** Jump focus to a field by name. */
+    focusField: (name: string) => void;
+    /** `␣` on the focused control — toggles a flag / selects a choice (honouring min/max). */
+    toggle: () => void;
+    /** Edit a `text` / `secret` field's value. */
+    setText: (name: string, str: string) => void;
+    /** Validate the current values. */
+    commit: () => FormValidation;
+}
+/**
+ * Headless navigation for a {@link Form} — the app owns the keys and calls these
+ * intents; NO Form component reads a key (the rest of blink works the same way).
+ * `onChange(nextValues)` receives every value edit.
+ *
+ * ```tsx
+ * const nav = useFormNavigation({ fields, values, onChange: setValues });
+ * useInput((input, key) => {
+ *   if (key.downArrow) nav.next();
+ *   else if (key.upArrow) nav.prev();
+ *   else if (input === ' ') nav.toggle();
+ * });
+ * return <Form fields={fields} values={values} focusId={nav.focusId} errors={errors} />;
+ * ```
+ */
+declare function useFormNavigation({ fields, values, onChange, }: {
+    fields: FieldSpec[];
+    values?: FormValues;
+    onChange?: (next: FormValues) => void;
+}): FormNavigation;
+interface FormProps {
+    /** The fields, top to bottom. */
+    fields: FieldSpec[];
+    /** Current values, keyed by field name. */
+    values?: FormValues;
+    /** The focused stop id (from {@link useFormNavigation}'s `focusId`). */
+    focusId?: string | null;
+    /** Per-field error messages (e.g. from {@link validateForm}). */
+    errors?: Record<string, string>;
+}
+/**
+ * Render-only: `fields` + `values` + `focusId` (+ `errors`) in; glyphs, colours,
+ * the focus fill, required markers, and error lines out. Reads no keys — pair it
+ * with {@link useFormNavigation} and the app's `useInput`.
+ */
+declare function Form({ fields, values, focusId, errors }: FormProps): React.ReactElement;
+
+export { ACTIONS, Banner, type BannerProps, type BannerTone, type BlinkContextValue, type BoxChars, type BoxStyleName, type BuiltinGlyphName, CLOUD, COMMON_DOMAINS, COMPANIES, type ChoiceInput, type CommonDomainName, Cursor, type CursorProps, DATABASES, DEFAULT_GLYPH_COLOR, DEFAULT_UNICODE, DEVINFRA, type DescriptionItem, DescriptionList, type DescriptionListProps, type DetectOptions, Dialog, type DialogAction, type DialogProps, type DialogTone, type Dimensions, EDITORS, FILES, FRAMEWORKS, type FieldKind, type FieldSpec, type FieldValue, type FocusStop, Footer, type FooterProps, Form, type FormNavigation, type FormProps, type FormValidation, type FormValues, GLYPH_PACKS, type GlyphColor, type GlyphInput, type GlyphVariants, Header, type HeaderProps, type HotkeyDef, type IconSet, Input, type InputProps, LANGUAGES, List, type ListNavigation, type ListProps, ListRow, type ListRowData, type ListRowProps, type ListSelection, type ListWindow, LogView, type LogViewProps, NERD_INDEX, NERD_INDEX_SOURCES, OS, PACKAGES, PALETTE_SLOTS, type Palette, type PaletteColor, Pane, type PaneProps, type PaneTone, type PaneVariant, ProgressBar, type ProgressBarProps, type ProgressItem, ProgressList, type ProgressListProps, type ProgressState, type ResolvedChoice, SOCIAL, SYSTEM, type SelectionMode, type SelectionName, type SemanticTokens, Spinner, type SpinnerOptions, type SpinnerProps, type StateIntent, type StateName, type Theme, type ThemeControls, type ThemeDefinition, type ThemeMeta, type ThemeMode, ThemeProvider, type ThemeProviderProps, type UseListNavigationOptions, type UseListSelectionOptions, type UseListWindowOptions, allThemes, blocks, blocksH, boxChars, boxStyles, buildStops, buildTokens, catppuccinMocha, cellWidth, computeWindow, defaultTheme, deriveAscii, detectIconSet, getTheme, glyph, glyphColor, gruvbox, hasGlyph, hasTheme, latte, listThemes, mocha, mochaTokens, navGlyphs, neutral, nf, nfChar, nfHas, nord, palettes, registerGlyph, registerGlyphs, registerNerdIndex, registerTheme, registeredNames, resolveChoices, selectionIntents, spinnerFor, spinnerFrames, stateGlyph, stateGlyphs, stateIntents, tokyonight, useBlink, useBlink$1 as useBlinkContext, useFormNavigation, useGlyph, useIconSet, useListNavigation, useListSelection, useListWindow, useSpinnerFrame, useStdoutDimensions, useTheme, useThemeControls, useTokens, validateForm };