@zakmandhro/bunti 0.1.5 → 0.2.0

package/dist/icons.d.ts

@@ -1,21 +1,442 @@
 /**
  * Bunti Icon Engine
  * Purely tactical: Nerd Fonts or ASCII fallbacks.
+ *
+ * Two tiers of names resolve through icon()/getIcon():
+ *   1. The curated ICON_MAP below (89 short names with ASCII fallbacks).
+ *   2. A runtime registry filled via register()/registerAll() — most notably
+ *      by `import '@zakmandhro/bunti/icons-full'`, which installs the full
+ *      Nerd Fonts v3.4.0 glyph set (~10.7k names like 'fa-rocket').
  */
-import type { TerminalCapabilities } from './detect';
+import type { IconName } from './data/nf-names';
+import { type TerminalCapabilities, type TerminalProfile } from './detect';
+/** An icon's Nerd Font glyph plus its plain-terminal ASCII stand-in. */
 export interface IconDefinition {
+    /** Nerd Font glyph (private-use-area codepoint). */
     nf: string;
+    /** Single-char ASCII fallback for non-NF terminals. */
     ascii: string;
 }
+declare const CURATED_ICONS: {
+    add: {
+        nf: string;
+        ascii: string;
+    };
+    'arrow-left': {
+        nf: string;
+        ascii: string;
+    };
+    'arrow-right': {
+        nf: string;
+        ascii: string;
+    };
+    bars: {
+        nf: string;
+        ascii: string;
+    };
+    bell: {
+        nf: string;
+        ascii: string;
+    };
+    branch: {
+        nf: string;
+        ascii: string;
+    };
+    bullet: {
+        nf: string;
+        ascii: string;
+    };
+    bun: {
+        nf: string;
+        ascii: string;
+    };
+    bunti: {
+        nf: string;
+        ascii: string;
+    };
+    check: {
+        nf: string;
+        ascii: string;
+    };
+    checkbox: {
+        nf: string;
+        ascii: string;
+    };
+    'checkbox-check': {
+        nf: string;
+        ascii: string;
+    };
+    'chevron-down': {
+        nf: string;
+        ascii: string;
+    };
+    'chevron-left': {
+        nf: string;
+        ascii: string;
+    };
+    'chevron-right': {
+        nf: string;
+        ascii: string;
+    };
+    close: {
+        nf: string;
+        ascii: string;
+    };
+    cloud: {
+        nf: string;
+        ascii: string;
+    };
+    code: {
+        nf: string;
+        ascii: string;
+    };
+    commit: {
+        nf: string;
+        ascii: string;
+    };
+    copy: {
+        nf: string;
+        ascii: string;
+    };
+    cpu: {
+        nf: string;
+        ascii: string;
+    };
+    database: {
+        nf: string;
+        ascii: string;
+    };
+    desktop: {
+        nf: string;
+        ascii: string;
+    };
+    disk: {
+        nf: string;
+        ascii: string;
+    };
+    download: {
+        nf: string;
+        ascii: string;
+    };
+    'draft-pr': {
+        nf: string;
+        ascii: string;
+    };
+    edit: {
+        nf: string;
+        ascii: string;
+    };
+    error: {
+        nf: string;
+        ascii: string;
+    };
+    exit: {
+        nf: string;
+        ascii: string;
+    };
+    external: {
+        nf: string;
+        ascii: string;
+    };
+    eye: {
+        nf: string;
+        ascii: string;
+    };
+    'eye-off': {
+        nf: string;
+        ascii: string;
+    };
+    file: {
+        nf: string;
+        ascii: string;
+    };
+    folder: {
+        nf: string;
+        ascii: string;
+    };
+    'folder-open': {
+        nf: string;
+        ascii: string;
+    };
+    fork: {
+        nf: string;
+        ascii: string;
+    };
+    gear: {
+        nf: string;
+        ascii: string;
+    };
+    git: {
+        nf: string;
+        ascii: string;
+    };
+    grid: {
+        nf: string;
+        ascii: string;
+    };
+    heart: {
+        nf: string;
+        ascii: string;
+    };
+    'help-circle': {
+        nf: string;
+        ascii: string;
+    };
+    home: {
+        nf: string;
+        ascii: string;
+    };
+    image: {
+        nf: string;
+        ascii: string;
+    };
+    info: {
+        nf: string;
+        ascii: string;
+    };
+    issue: {
+        nf: string;
+        ascii: string;
+    };
+    json: {
+        nf: string;
+        ascii: string;
+    };
+    laptop: {
+        nf: string;
+        ascii: string;
+    };
+    list: {
+        nf: string;
+        ascii: string;
+    };
+    loading: {
+        nf: string;
+        ascii: string;
+    };
+    lock: {
+        nf: string;
+        ascii: string;
+    };
+    mail: {
+        nf: string;
+        ascii: string;
+    };
+    markdown: {
+        nf: string;
+        ascii: string;
+    };
+    maximize: {
+        nf: string;
+        ascii: string;
+    };
+    memory: {
+        nf: string;
+        ascii: string;
+    };
+    menu: {
+        nf: string;
+        ascii: string;
+    };
+    merge: {
+        nf: string;
+        ascii: string;
+    };
+    minimize: {
+        nf: string;
+        ascii: string;
+    };
+    network: {
+        nf: string;
+        ascii: string;
+    };
+    node: {
+        nf: string;
+        ascii: string;
+    };
+    pause: {
+        nf: string;
+        ascii: string;
+    };
+    pencil: {
+        nf: string;
+        ascii: string;
+    };
+    planet: {
+        nf: string;
+        ascii: string;
+    };
+    play: {
+        nf: string;
+        ascii: string;
+    };
+    'plus-circle': {
+        nf: string;
+        ascii: string;
+    };
+    pr: {
+        nf: string;
+        ascii: string;
+    };
+    refresh: {
+        nf: string;
+        ascii: string;
+    };
+    remove: {
+        nf: string;
+        ascii: string;
+    };
+    repo: {
+        nf: string;
+        ascii: string;
+    };
+    robot: {
+        nf: string;
+        ascii: string;
+    };
+    rocket: {
+        nf: string;
+        ascii: string;
+    };
+    satellite: {
+        nf: string;
+        ascii: string;
+    };
+    save: {
+        nf: string;
+        ascii: string;
+    };
+    search: {
+        nf: string;
+        ascii: string;
+    };
+    send: {
+        nf: string;
+        ascii: string;
+    };
+    server: {
+        nf: string;
+        ascii: string;
+    };
+    settings: {
+        nf: string;
+        ascii: string;
+    };
+    'staggered-bars': {
+        nf: string;
+        ascii: string;
+    };
+    star: {
+        nf: string;
+        ascii: string;
+    };
+    stop: {
+        nf: string;
+        ascii: string;
+    };
+    success: {
+        nf: string;
+        ascii: string;
+    };
+    tag: {
+        nf: string;
+        ascii: string;
+    };
+    terminal: {
+        nf: string;
+        ascii: string;
+    };
+    trash: {
+        nf: string;
+        ascii: string;
+    };
+    user: {
+        nf: string;
+        ascii: string;
+    };
+    warning: {
+        nf: string;
+        ascii: string;
+    };
+    wizard: {
+        nf: string;
+        ascii: string;
+    };
+    yaml: {
+        nf: string;
+        ascii: string;
+    };
+    zap: {
+        nf: string;
+        ascii: string;
+    };
+};
+/** Short names of the curated, width-audited icon set. */
+export type CuratedIconName = keyof typeof CURATED_ICONS;
+/**
+ * Any icon name Bunti can resolve: curated short names, full Nerd Fonts
+ * names (available after `import '@zakmandhro/bunti/icons-full'`), or
+ * custom names added via register(). Arbitrary strings stay assignable.
+ */
+export type BuntiIconName = CuratedIconName | IconName | (string & Record<never, never>);
+/** The curated icon table: 89 width-audited names with ASCII fallbacks. */
 export declare const ICON_MAP: Record<string, IconDefinition>;
+/**
+ * Emoji-to-icon-name swaps applied automatically to drawn text (emoji
+ * render at unreliable widths across terminals; their NF twins are
+ * width-audited). Set `raw: true` on a cell to bypass.
+ */
 export declare const EMOJI_MAP: Record<string, string>;
+/**
+ * Swaps known emoji in a string for their width-audited Nerd Font icons
+ * (see EMOJI_MAP). Applied automatically by draw calls; no-op on the
+ * ASCII tier.
+ */
 export declare function replaceEmojis(text: string): string;
+/**
+ * Initializes the icon tier from terminal detection.
+ *
+ * - `init({ nerdFont })` forces the tier explicitly (always wins).
+ * - `init({ profile })` derives it from a pre-detected TerminalProfile
+ *   (render() passes the per-screen profile here).
+ * - `init()` runs env detection itself via `identifyTerminal()`.
+ *
+ * 'yes' / 'assumed-yes' policies map to Nerd Font glyphs; everything else
+ * falls back to the ASCII tier. Until init() is called the module defaults
+ * to Nerd Font glyphs (back-compat for direct icon() usage).
+ */
 export declare function init(options?: {
     nerdFont?: boolean;
+    profile?: TerminalProfile;
 }): Promise<TerminalCapabilities>;
-export declare function getIcon(name: string, caps: TerminalCapabilities): string;
-export declare function icon(name: string): string;
-export declare function nerd(name: string): string;
-export declare function register(_name: string, _glyph: string): void;
+/**
+ * Registers a runtime icon. Accepts a bare Nerd Font glyph, or a full
+ * definition with an ASCII fallback for `init({ nerdFont: false })` tiers
+ * (bare glyphs fall back to '*' in the ASCII tier).
+ */
+export declare function register(name: string, glyphOrDef: string | IconDefinition): void;
+/** Bulk-registers name -> glyph pairs (used by the icons-full subpath). */
+export declare function registerAll(glyphs: Record<string, string>): void;
+/** @internal Test hook: unresolved names buffered so far. */
+export declare function __iconMisses(): string[];
+/**
+ * Resolves an icon name. Resolution order:
+ *   1. Curated ICON_MAP (short names, keeps ASCII fallbacks + aliases).
+ *   2. Runtime registry (register()/registerAll(), e.g. the icons-full
+ *      pack). A leading 'nf-' is stripped: 'nf-fa-rocket' === 'fa-rocket'.
+ *   3. '' — the miss is buffered and reported once on process exit.
+ */
+export declare function getIcon(name: BuntiIconName, caps: TerminalCapabilities): string;
+/**
+ * Resolves an icon name to a glyph on the active tier (Nerd Font glyph,
+ * or ASCII fallback on plain terminals). Unknown names render as '' and
+ * are reported once on process exit with a nearest-name hint.
+ * @example text(`${icon('rocket')} Launch`);
+ */
+export declare function icon(name: BuntiIconName): string;
+/** Returns the Nerd Font glyph for a name regardless of the active tier. */
+export declare function nerd(name: BuntiIconName): string;
+/** Picks the given Nerd Font char on the NF tier, else the fallback. */
 export declare function nerdIcon(nfChar: string, fallback: string): string;
+export {};
 //# sourceMappingURL=icons.d.ts.map

package/dist/icons.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"icons.d.ts","sourceRoot":"","sources":["../src/icons.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,UAAU,CAAC;AAErD,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;CACf;AAED,eAAO,MAAM,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAyFnD,CAAC;AAEF,eAAO,MAAM,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAkC5C,CAAC;AAuBF,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAoBlD;AAED,wBAAsB,IAAI,CAAC,OAAO,CAAC,EAAE;IACnC,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAGhC;AAED,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,oBAAoB,GAAG,MAAM,CAIxE;AAED,wBAAgB,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEzC;AAED,wBAAgB,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEzC;AAED,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAG;AAEhE,wBAAgB,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEjE"}
+{"version":3,"file":"icons.d.ts","sourceRoot":"","sources":["../src/icons.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EAEL,KAAK,oBAAoB,EACzB,KAAK,eAAe,EACrB,MAAM,UAAU,CAAC;AAOlB,wEAAwE;AACxE,MAAM,WAAW,cAAc;IAC7B,oDAAoD;IACpD,EAAE,EAAE,MAAM,CAAC;IACX,uDAAuD;IACvD,KAAK,EAAE,MAAM,CAAC;CACf;AAED,QAAA,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAyFuB,CAAC;AAE3C,0DAA0D;AAC1D,MAAM,MAAM,eAAe,GAAG,MAAM,OAAO,aAAa,CAAC;AAEzD;;;;GAIG;AACH,MAAM,MAAM,aAAa,GACrB,eAAe,GACf,QAAQ,GACR,CAAC,MAAM,GAAG,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC;AAEpC,2EAA2E;AAC3E,eAAO,MAAM,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAiB,CAAC;AAEtE;;;;GAIG;AACH,eAAO,MAAM,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAkC5C,CAAC;AAuBF;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAoBlD;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,IAAI,CAAC,OAAO,CAAC,EAAE;IACnC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,OAAO,CAAC,EAAE,eAAe,CAAC;CAC3B,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAUhC;AAgBD;;;;GAIG;AACH,wBAAgB,QAAQ,CACtB,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,MAAM,GAAG,cAAc,GAClC,IAAI,CAON;AAED,2EAA2E;AAC3E,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAIhE;AAgDD,6DAA6D;AAC7D,wBAAgB,YAAY,IAAI,MAAM,EAAE,CAEvC;AAED;;;;;;GAMG;AACH,wBAAgB,OAAO,CACrB,IAAI,EAAE,aAAa,EACnB,IAAI,EAAE,oBAAoB,GACzB,MAAM,CAaR;AAED;;;;;GAKG;AACH,wBAAgB,IAAI,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM,CAEhD;AAED,4EAA4E;AAC5E,wBAAgB,IAAI,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM,CAOhD;AAED,wEAAwE;AACxE,wBAAgB,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEjE"}

package/dist/icons.js

@@ -1,16 +1,18 @@
-export const ICON_MAP = {
+import { identifyTerminal, } from './detect';
+import { hintsSuppressed, nearestMatch, registerHintFlusher, } from './diagnostics';
+const CURATED_ICONS = {
     add: { nf: '\uf067', ascii: '+' },
     'arrow-left': { nf: '\uf060', ascii: '<' },
     'arrow-right': { nf: '\uf061', ascii: '>' },
-    bars: { nf: '\uf0c9', ascii: '≡' },
+    bars: { nf: '\uf0c9', ascii: '=' },
     bell: { nf: '\uf0f3', ascii: '!' },
     branch: { nf: '\uf418', ascii: '*' },
-    bullet: { nf: '\uf111', ascii: '•' },
+    bullet: { nf: '\uf111', ascii: '*' },
     bun: { nf: '\ue76f', ascii: 'B' },
     bunti: { nf: '\u{f0065}', ascii: '@' },
     check: { nf: '\uf00c', ascii: 'v' },
-    checkbox: { nf: '\uf0c8', ascii: '[ ]' },
-    'checkbox-check': { nf: '\uf14a', ascii: '[x]' },
+    checkbox: { nf: '\uf0c8', ascii: '#' },
+    'checkbox-check': { nf: '\uf14a', ascii: 'X' },
     'chevron-down': { nf: '\uf078', ascii: 'v' },
     'chevron-left': { nf: '\uf053', ascii: '<' },
     'chevron-right': { nf: '\uf054', ascii: '>' },
@@ -53,16 +55,16 @@ export const ICON_MAP = {
     markdown: { nf: '\uf48a', ascii: 'M' },
     maximize: { nf: '\uf0c8', ascii: '^' },
     memory: { nf: '\uf0c7', ascii: 'M' },
-    menu: { nf: '\uf0c9', ascii: '≡' },
+    menu: { nf: '\uf0c9', ascii: '=' },
     merge: { nf: '\uf419', ascii: '>' },
     minimize: { nf: '\u{f10fe}', ascii: 'v' },
     network: { nf: '\uf0ac', ascii: 'N' },
     node: { nf: '\ue718', ascii: 'N' },
     pause: { nf: '\uf04c', ascii: '|' },
     pencil: { nf: '\uf044', ascii: 'e' },
-    planet: { nf: '\ue22e', ascii: '㊀' },
+    planet: { nf: '\ue22e', ascii: 'O' },
     play: { nf: '\uf04b', ascii: '>' },
-    'plus-circle': { nf: '\uea60', ascii: '(+)' },
+    'plus-circle': { nf: '\uea60', ascii: '+' },
     pr: { nf: '\uf41d', ascii: '!' },
     refresh: { nf: '\uf021', ascii: 'R' },
     remove: { nf: '\uf068', ascii: '-' },
@@ -75,7 +77,7 @@ export const ICON_MAP = {
     send: { nf: '\uec0f', ascii: '>' },
     server: { nf: '\uf233', ascii: 'S' },
     settings: { nf: '\uf013', ascii: '*' },
-    'staggered-bars': { nf: '\u{ee19}', ascii: '≡' },
+    'staggered-bars': { nf: '\u{ee19}', ascii: '=' },
     star: { nf: '\uf005', ascii: '*' },
     stop: { nf: '\uf04d', ascii: 'X' },
     success: { nf: '\uf00c', ascii: 'v' },
@@ -88,6 +90,13 @@ export const ICON_MAP = {
     yaml: { nf: '\ue6a8', ascii: 'Y' },
     zap: { nf: '\uf0e7', ascii: 'z' },
 };
+/** The curated icon table: 89 width-audited names with ASCII fallbacks. */
+export const ICON_MAP = CURATED_ICONS;
+/**
+ * Emoji-to-icon-name swaps applied automatically to drawn text (emoji
+ * render at unreliable widths across terminals; their NF twins are
+ * width-audited). Set `raw: true` on a cell to bypass.
+ */
 export const EMOJI_MAP = {
     '🌿': 'branch',
     '📥': 'pr',
@@ -140,6 +149,11 @@ function getEmojiPattern() {
     }
     return emojiPattern;
 }
+/**
+ * Swaps known emoji in a string for their width-audited Nerd Font icons
+ * (see EMOJI_MAP). Applied automatically by draw calls; no-op on the
+ * ASCII tier.
+ */
 export function replaceEmojis(text) {
     if (!text)
         return '';
@@ -161,24 +175,139 @@ export function replaceEmojis(text) {
         return name ? getIcon(name, cachedCaps) : match;
     });
 }
+/**
+ * Initializes the icon tier from terminal detection.
+ *
+ * - `init({ nerdFont })` forces the tier explicitly (always wins).
+ * - `init({ profile })` derives it from a pre-detected TerminalProfile
+ *   (render() passes the per-screen profile here).
+ * - `init()` runs env detection itself via `identifyTerminal()`.
+ *
+ * 'yes' / 'assumed-yes' policies map to Nerd Font glyphs; everything else
+ * falls back to the ASCII tier. Until init() is called the module defaults
+ * to Nerd Font glyphs (back-compat for direct icon() usage).
+ */
 export async function init(options) {
-    if (options?.nerdFont !== undefined)
+    if (options?.nerdFont !== undefined) {
         cachedCaps.nerdFont = options.nerdFont;
+        return cachedCaps;
+    }
+    const profile = options?.profile ?? identifyTerminal();
+    cachedCaps.nerdFont =
+        profile.nerdFont === 'yes' || profile.nerdFont === 'assumed-yes';
+    cachedCaps.glyphProtocol = profile.app === 'ghostty';
     return cachedCaps;
 }
+// --- Runtime icon registry (tier 2) ---
+// Consulted after the curated ICON_MAP. The icons-full subpath bulk-loads
+// every Nerd Fonts glyph here; apps can also register their own icons.
+const registryNf = new Map();
+const registryAscii = new Map();
+/** ASCII-tier stand-in for registered icons without an explicit fallback. */
+const REGISTRY_ASCII_FALLBACK = '*';
+function stripNfPrefix(name) {
+    return name.startsWith('nf-') ? name.slice(3) : name;
+}
+/**
+ * Registers a runtime icon. Accepts a bare Nerd Font glyph, or a full
+ * definition with an ASCII fallback for `init({ nerdFont: false })` tiers
+ * (bare glyphs fall back to '*' in the ASCII tier).
+ */
+export function register(name, glyphOrDef) {
+    if (typeof glyphOrDef === 'string') {
+        registryNf.set(name, glyphOrDef);
+    }
+    else {
+        registryNf.set(name, glyphOrDef.nf);
+        registryAscii.set(name, glyphOrDef.ascii);
+    }
+}
+/** Bulk-registers name -> glyph pairs (used by the icons-full subpath). */
+export function registerAll(glyphs) {
+    for (const name in glyphs) {
+        registryNf.set(name, glyphs[name]);
+    }
+}
+// --- Unknown-name diagnostics ---
+// Misses are buffered in a Set and drained through the shared diagnostics
+// exit flush (src/diagnostics.ts), so warnings never tear an active frame
+// mid-render and every dev hint arrives in one block on process exit.
+const missedNames = new Set();
+let flusherRegistered = false;
+function recordMiss(name) {
+    if (hintsSuppressed())
+        return;
+    missedNames.add(name);
+    if (!flusherRegistered) {
+        flusherRegistered = true;
+        registerHintFlusher(drainIconHintLines);
+    }
+}
+function* iconNameCandidates() {
+    yield* Object.keys(ICON_MAP);
+    yield* registryNf.keys();
+}
+function nearestIconName(name) {
+    return nearestMatch(stripNfPrefix(name), iconNameCandidates());
+}
+/** Drains buffered misses into hint lines (called by the exit flush). */
+function drainIconHintLines() {
+    if (missedNames.size === 0)
+        return [];
+    const lines = [];
+    for (const name of missedNames) {
+        const hint = nearestIconName(name);
+        lines.push(`unknown icon '${name}' rendered as ''` +
+            `${hint ? ` (did you mean '${hint}'?)` : ''}`);
+    }
+    if (registryNf.size === 0) {
+        lines.push("tip: import '@zakmandhro/bunti/icons-full' to enable all ~10.7k Nerd Font icons by name");
+    }
+    missedNames.clear();
+    return lines;
+}
+/** @internal Test hook: unresolved names buffered so far. */
+export function __iconMisses() {
+    return [...missedNames];
+}
+/**
+ * Resolves an icon name. Resolution order:
+ *   1. Curated ICON_MAP (short names, keeps ASCII fallbacks + aliases).
+ *   2. Runtime registry (register()/registerAll(), e.g. the icons-full
+ *      pack). A leading 'nf-' is stripped: 'nf-fa-rocket' === 'fa-rocket'.
+ *   3. '' — the miss is buffered and reported once on process exit.
+ */
 export function getIcon(name, caps) {
     const def = ICON_MAP[name];
-    if (!def)
-        return '';
-    return caps.nerdFont ? def.nf : def.ascii;
+    if (def)
+        return caps.nerdFont ? def.nf : def.ascii;
+    const key = registryNf.has(name) ? name : stripNfPrefix(name);
+    const nf = registryNf.get(key);
+    if (nf !== undefined) {
+        if (caps.nerdFont)
+            return nf;
+        return registryAscii.get(key) ?? REGISTRY_ASCII_FALLBACK;
+    }
+    recordMiss(name);
+    return '';
 }
+/**
+ * Resolves an icon name to a glyph on the active tier (Nerd Font glyph,
+ * or ASCII fallback on plain terminals). Unknown names render as '' and
+ * are reported once on process exit with a nearest-name hint.
+ * @example text(`${icon('rocket')} Launch`);
+ */
 export function icon(name) {
     return getIcon(name, cachedCaps);
 }
+/** Returns the Nerd Font glyph for a name regardless of the active tier. */
 export function nerd(name) {
-    return ICON_MAP[name]?.nf || '';
+    return (ICON_MAP[name]?.nf ??
+        registryNf.get(name) ??
+        registryNf.get(stripNfPrefix(name)) ??
+        '');
 }
-export function register(_name, _glyph) { }
+/** Picks the given Nerd Font char on the NF tier, else the fallback. */
 export function nerdIcon(nfChar, fallback) {
     return cachedCaps.nerdFont ? nfChar : fallback;
 }