prttprint 2.0.1__py3-none-any.whl

PRTTprint.py

@@ -0,0 +1,3915 @@
+"""
+rypy v2.0.0 — большая библиотека полезных шорткатов для CLI.
+
+Основное:
+    Цвета:        c, p, cprint, gprint, gprint3, ok, info, warn, err, debug,
+                  gradient, gradient3, hex_color, glow_print, glow_print3
+    Рамки:        section, box, banner, kv, recap, notify, notify_center,
+                  title_box, center_box, box_center, center
+    Таблицы:      table, Table (fluent), to_table, table_from_csv
+    Данные:       columns, tree, diff, chart, flatten, group_by, deep_merge,
+                  env_all, read_csv, write_csv
+    Прогресс:     progress, progress3, progress_multi, PBar, bar, bar3,
+                  bar_wave, circle_bar, spinner, live, table_live, status
+    Спиннеры:     spin, sp, spin_done, spin_fail, spinner_pause
+    Шаги:         step, task, step_run, run, run_all, do, pause, wait
+    Бары:         hp_bar, mp_bar, xp_bar, status_line, hud
+    Декорации:    rule, double_rule, dashed_rule, dots_rule,
+                  gradient_rule, rainbow_rule, wave_rule, space, clear
+    Значки:       badge, tag, sparkle_text, arrow_text
+    Анимации:     animate, glow, typewriter, wave_text, progress_glow,
+                  divider_animated, line_reveal, fade_in, flip_banner,
+                  hearts_rain, stars_rain, fireworks,
+                  rain, rain_line, rain_multi, line_effect
+    Интерактив:   ask, confirm, menu, prompt, password, copyable,
+                  wait_key, prompt_choice, confirm_or_exit,
+                  spinner_selection, Ask, wizard
+    Звуки:        sound, sound_on, sound_off, sound_list, SOUNDS (20 звуков)
+    Продвинутое:  Keyboard, Stream, Dashboard, Parser
+    Форматы:      human_size, human_time, human_delta, human_eta, human_ago,
+                  money, plural
+    Время:        timer, debug_time
+    Ретраи:       retry
+    JSON:         load_json, save_json, Store
+    Дебаг:        dbg, color_traceback
+    Shell:        run_shell
+    Игровое:      dice, chance, pick_weighted
+    Мелочи:       env, chunk, pick, uniq, first, last, clamp, slugify,
+                  is_tty, supports_unicode, visible_len
+    Утилиты:      init, bootstrap, import_all, term_width,
+                  cheatsheet, docs, test_all, new
+"""
+
+from __future__ import annotations
+
+import atexit
+import csv
+import functools
+import inspect
+import io
+import itertools
+import json
+import linecache
+import os
+import random
+import re as _re
+import shutil
+import subprocess
+import sys
+import threading
+import time
+import traceback as _tb
+
+from contextlib import contextmanager
+from datetime import datetime, timedelta
+from pathlib import Path
+from typing import Any, Callable, Iterable, Iterator
+
+try:
+    import msvcrt
+    _HAS_MSVCRT = True
+except ImportError:
+    _HAS_MSVCRT = False
+
+try:
+    import termios
+    import tty
+    _HAS_TERMIOS = True
+except ImportError:
+    _HAS_TERMIOS = False
+
+try:
+    import winsound as _winsound
+    _HAS_WINSOUND = True
+except ImportError:
+    _winsound = None
+    _HAS_WINSOUND = False
+
+__version__ = '2.0.1'
+
+__all__ = [
+    '__version__',
+    # Цвета и вывод
+    'c', 'p', 'cprint', 'gprint', 'gprint3', 'gradient', 'gradient3',
+    'hex_color', 'glow_print', 'glow_print3',
+    'ok', 'info', 'warn', 'err', 'debug', 'enable_colors',
+    'red', 'green', 'yellow', 'blue', 'magenta', 'cyan', 'white', 'gray', 'bold',
+    # Разделы и рамки
+    'section', 'box', 'banner', 'kv', 'recap', 'notify', 'notify_center',
+    'title_box', 'center_box', 'box_center', 'center',
+    # Таблицы
+    'table', 'Table', 'to_table', 'table_from_csv',
+    # Данные
+    'columns', 'tree', 'diff', 'chart',
+    'flatten', 'group_by', 'deep_merge', 'env_all',
+    'read_csv', 'write_csv',
+    # Шаги и раннеры
+    'step', 'task', 'step_run', 'run', 'run_all', 'do', 'pause', 'wait',
+    # Спиннеры
+    'spinner', 'spinner_pause', 'circle_bar', 'live', 'table_live', 'status',
+    'spin', 'sp', 'spin_done', 'spin_fail',
+    'progress', 'progress3', 'progress_multi', 'PBar', 'progress_glow',
+    'SPINNER_FRAMES', 'FANCY_PRESETS', 'CIRCLE_PRESETS',
+    'PLAIN_PRESETS', 'EMOJI_PRESETS', 'ASCII_PRESETS', 'pick_preset',
+    # Бары
+    'bar', 'bar3', 'bar_wave', 'hp_bar', 'mp_bar', 'xp_bar',
+    'status_line', 'hud',
+    # Декорации
+    'rule', 'double_rule', 'dashed_rule', 'dots_rule',
+    'gradient_rule', 'rainbow_rule', 'wave_rule',
+    'space', 'clear',
+    # Значки
+    'badge', 'tag', 'sparkle_text', 'arrow_text',
+    # Анимации
+    'animate', 'glow', 'typewriter', 'wave_text',
+    'divider_animated', 'line_reveal', 'fade_in', 'flip_banner',
+    'hearts_rain', 'stars_rain', 'fireworks',
+    'rain', 'rain_line', 'rain_multi', 'line_effect',
+    # Звуки
+    'sound', 'sound_on', 'sound_off', 'sound_list', 'SOUNDS',
+    # Логгер
+    'Log',
+    # Форматы
+    'human_size', 'human_time', 'human_delta', 'human_eta',
+    'human_ago', 'money', 'plural',
+    # Время
+    'timer', 'debug_time',
+    # Ретраи
+    'retry',
+    # JSON и хранилище
+    'load_json', 'save_json', 'Store',
+    # Дебаг
+    'dbg', 'color_traceback',
+    # Интерактив
+    'ask', 'confirm', 'menu', 'prompt', 'password', 'copyable',
+    'wait_key', 'prompt_choice', 'confirm_or_exit',
+    'spinner_selection', 'Ask', 'wizard',
+    # Продвинутое
+    'Keyboard', 'Stream', 'Dashboard', 'Parser',
+    # Shell
+    'run_shell',
+    # Игровое
+    'dice', 'chance', 'pick_weighted',
+    # Мелочи
+    'env', 'chunk', 'pick', 'uniq', 'first', 'last', 'clamp', 'slugify',
+    'is_tty', 'supports_unicode', 'visible_len',
+    # Утилиты
+    'init', 'bootstrap', 'import_all', 'term_width',
+    'cheatsheet', 'docs', 'test_all', 'new',
+]
+
+
+# ============================================================
+# 0. УТИЛИТЫ ОКРУЖЕНИЯ
+# ============================================================
+
+def term_width(default: int = 80) -> int:
+    """Ширина терминала."""
+    try:
+        return shutil.get_terminal_size((default, 24)).columns
+    except OSError:
+        return default
+
+
+try:
+    from wcwidth import wcswidth as _wcswidth
+
+    def _visible_len(s: str) -> int:
+        s = _re.sub(r'\033\[[0-9;]*m', '', s)
+        w = _wcswidth(s)
+        return w if w >= 0 else len(s)
+
+    _HAS_WCWIDTH = True
+except ImportError:
+    def _visible_len(s: str) -> int:
+        return len(_re.sub(r'\033\[[0-9;]*m', '', s))
+
+    _HAS_WCWIDTH = False
+
+
+def visible_len(s: str) -> int:
+    return _visible_len(s)
+
+
+def is_tty() -> bool:
+    return sys.stdout.isatty()
+
+
+def supports_unicode() -> bool:
+    enc = (sys.stdout.encoding or '').lower()
+    return 'utf' in enc
+
+
+# ============================================================
+# 1. ЦВЕТА
+# ============================================================
+
+_ENABLED = (
+    False if os.environ.get('NO_COLOR')
+    else True if os.environ.get('FORCE_COLOR')
+    else sys.stdout.isatty() or os.name == 'nt'
+)
+
+_RESET = '\033[0m'
+
+_NAMED = {
+    'black': 30, 'red': 31, 'green': 32, 'yellow': 33,
+    'blue': 34, 'magenta': 35, 'cyan': 36, 'white': 37,
+    'gray': 90, 'grey': 90,
+    'bright_red': 91, 'bright_green': 92, 'bright_yellow': 93,
+    'bright_blue': 94, 'bright_magenta': 95, 'bright_cyan': 96,
+}
+
+_RGB_APPROX = {
+    'black': (0, 0, 0), 'red': (255, 0, 0), 'green': (0, 128, 0),
+    'yellow': (255, 255, 0), 'blue': (0, 0, 255), 'magenta': (255, 0, 255),
+    'cyan': (0, 255, 255), 'white': (255, 255, 255),
+    'gray': (128, 128, 128), 'grey': (128, 128, 128),
+    'bright_red': (255, 85, 85), 'bright_green': (85, 255, 85),
+    'bright_yellow': (255, 255, 85), 'bright_blue': (85, 85, 255),
+    'bright_magenta': (255, 85, 255), 'bright_cyan': (85, 255, 255),
+}
+
+_STYLES = {'bold': 1, 'dim': 2, 'italic': 3, 'underline': 4,
+           'blink': 5, 'reverse': 7, 'strike': 9}
+
+_KEYWORDS = {
+    'red':    ('error', 'ошибк', 'fail', 'провал', 'не ', 'нет '),
+    'yellow': ('warn', 'предупр', 'внимание', 'осторожно'),
+    'green':  ('ok', 'успеш', 'готово', 'done', 'success', '✓'),
+    'cyan':   ('info', 'инфо', 'загруз', 'loading'),
+    'gray':   ('debug', 'отладк', 'trace'),
+}
+
+_LEVEL_STYLES = {
+    'ok':    ('✓', 'green',  'bold'),
+    'info':  ('ℹ', 'cyan',   ''),
+    'warn':  ('⚠', 'yellow', 'bold'),
+    'err':   ('✗', 'red',    'bold'),
+    'debug': ('·', 'gray',   'dim'),
+}
+
+_SPINNER_DEFAULTS = {
+    'color': 'cyan',
+    'show_time': False,
+    'preset': None,
+    'kind': 'fancy',
+    'speed': 0.08,
+}
+
+_SOUND_ENABLED = True
+
+
+def _hex_to_rgb(s: str) -> tuple[int, int, int]:
+    s = s.lstrip('#')
+    if len(s) == 3:
+        s = ''.join(ch * 2 for ch in s)
+    return int(s[0:2], 16), int(s[2:4], 16), int(s[4:6], 16)
+
+
+def _any_to_rgb(color) -> tuple[int, int, int]:
+    if isinstance(color, (tuple, list)) and len(color) == 3:
+        return tuple(int(x) for x in color)
+    if isinstance(color, str):
+        if color.startswith('#'):
+            return _hex_to_rgb(color)
+        if color in _RGB_APPROX:
+            return _RGB_APPROX[color]
+    return (255, 255, 255)
+
+
+def _to_codes(color) -> list[str]:
+    if color is None:
+        return []
+    if isinstance(color, (tuple, list)) and len(color) == 3:
+        r, g, b = color
+        return [f'38;2;{r};{g};{b}']
+    if isinstance(color, str) and color.startswith('#'):
+        r, g, b = _hex_to_rgb(color)
+        return [f'38;2;{r};{g};{b}']
+    if color in _NAMED:
+        return [str(_NAMED[color])]
+    return []
+
+
+def _bg_codes(color) -> list[str]:
+    if color is None:
+        return []
+    if isinstance(color, (tuple, list)) and len(color) == 3:
+        r, g, b = color
+        return [f'48;2;{r};{g};{b}']
+    if isinstance(color, str) and color.startswith('#'):
+        r, g, b = _hex_to_rgb(color)
+        return [f'48;2;{r};{g};{b}']
+    if color in _NAMED:
+        return [str(_NAMED[color] + 10)]
+    return []
+
+
+def c(text: Any, color=None, bg=None, *styles: str,
+      bold: bool = False, dim: bool = False,
+      italic: bool = False, underline: bool = False,
+      enabled: bool | None = None) -> str:
+    """Красит строку ANSI-кодами."""
+    on = _ENABLED if enabled is None else enabled
+    if not on:
+        return str(text)
+    codes: list[str] = []
+    for flag, code in (('bold', bold), ('dim', dim),
+                       ('italic', italic), ('underline', underline)):
+        if flag and code:
+            codes.append(str(_STYLES[flag]))
+    for s in styles:
+        if s in _STYLES:
+            codes.append(str(_STYLES[s]))
+    codes += _to_codes(color)
+    codes += _bg_codes(bg)
+    if not codes:
+        return str(text)
+    return f'\033[{";".join(codes)}m{text}{_RESET}'
+
+
+def gradient(text: str, start, end) -> str:
+    """2-цветный градиент."""
+    if not _ENABLED:
+        return text
+    r1, g1, b1 = _any_to_rgb(start)
+    r2, g2, b2 = _any_to_rgb(end)
+    n = max(len(text) - 1, 1)
+    out = []
+    for i, ch in enumerate(text):
+        t = i / n
+        r = int(r1 + (r2 - r1) * t)
+        g = int(g1 + (g2 - g1) * t)
+        b = int(b1 + (b2 - b1) * t)
+        out.append(f'\033[38;2;{r};{g};{b}m{ch}')
+    return ''.join(out) + _RESET
+
+
+def gradient3(text: str, start, middle, end) -> str:
+    """3-цветный градиент."""
+    if not _ENABLED:
+        return text
+    n = len(text)
+    if n == 0:
+        return text
+    r1, g1, b1 = _any_to_rgb(start)
+    r2, g2, b2 = _any_to_rgb(middle)
+    r3, g3, b3 = _any_to_rgb(end)
+    out = []
+    for i, ch in enumerate(text):
+        t = i / max(n - 1, 1)
+        if t <= 0.5:
+            u = t * 2
+            r = int(r1 + (r2 - r1) * u)
+            g = int(g1 + (g2 - g1) * u)
+            b = int(b1 + (b2 - b1) * u)
+        else:
+            u = (t - 0.5) * 2
+            r = int(r2 + (r3 - r2) * u)
+            g = int(g2 + (g3 - g2) * u)
+            b = int(b2 + (b3 - b2) * u)
+        out.append(f'\033[38;2;{r};{g};{b}m{ch}')
+    return ''.join(out) + _RESET
+
+
+def hex_color(hex_str: str) -> str:
+    r, g, b = _hex_to_rgb(hex_str)
+    return f'38;2;{r};{g};{b}'
+
+
+def _autocolor(msg: Any, color: str) -> str:
+    text = str(msg)
+    for kw in _KEYWORDS.get(color, ()):
+        if kw.lower() in text.lower():
+            pattern = _re.compile(_re.escape(kw), _re.IGNORECASE)
+            return pattern.sub(
+                lambda m: c(m.group(0), color, bold=True), text, count=1
+            )
+    return text
+
+
+def _emit(kind: str, msg: Any) -> None:
+    icon, color, style = _LEVEL_STYLES[kind]
+    styles = (style,) if style else ()
+    line = f'{c(icon, color, *styles)} {_autocolor(msg, color)}'
+    out = sys.stderr if kind == 'err' else sys.stdout
+    print(line, file=out)
+
+
+def ok(msg: Any) -> None:
+    _emit('ok', msg)
+    _sound('ok')
+
+
+def info(msg: Any) -> None:
+    _emit('info', msg)
+
+
+def warn(msg: Any) -> None:
+    _emit('warn', msg)
+    _sound('warning')
+
+
+def err(msg: Any) -> None:
+    _emit('err', msg)
+    _sound('error')
+
+
+def debug(msg: Any) -> None:
+    _emit('debug', msg)
+
+
+def enable_colors(flag: bool = True) -> None:
+    global _ENABLED
+    _ENABLED = flag
+
+
+atexit.register(lambda: sys.stdout.write(_RESET) if _ENABLED else None)
+
+
+# ============================================================
+# 2. PRINT С ЦВЕТОМ
+# ============================================================
+
+def p(*args, color=None, bg=None, bold=False, dim=False,
+      italic=False, underline=False, sep=' ', end='\n', flush=False) -> None:
+    text = sep.join(str(a) for a in args)
+    if color or bg or bold or dim or italic or underline:
+        text = c(text, color, bg, bold=bold, dim=dim,
+                 italic=italic, underline=underline)
+    print(text, end=end, flush=flush)
+
+
+cprint = p
+
+
+def gprint(text: str, start: str = 'red', end: str = 'blue',
+           bold=False, underline=False) -> None:
+    line = gradient(text, start, end)
+    if bold or underline:
+        line = c(line, None, bold=bold, underline=underline)
+    print(line)
+
+
+def gprint3(text: str, start='red', middle='yellow', end='green',
+            bold: bool = False, underline: bool = False) -> None:
+    line = gradient3(text, start, middle, end)
+    if bold or underline:
+        line = c(line, None, bold=bold, underline=underline)
+    print(line)
+
+
+red     = lambda s: c(s, 'red')
+green   = lambda s: c(s, 'green')
+yellow  = lambda s: c(s, 'yellow')
+blue    = lambda s: c(s, 'blue')
+magenta = lambda s: c(s, 'magenta')
+cyan    = lambda s: c(s, 'cyan')
+white   = lambda s: c(s, 'white')
+gray    = lambda s: c(s, 'gray')
+bold    = lambda s: c(s, None, bold=True)
+
+
+# ============================================================
+# 3. ЗВУКИ — 20 ВСТРОЕННЫХ ЭФФЕКТОВ
+# ============================================================
+
+SOUNDS = {
+    'click':      [(800, 30)],
+    'tick':       [(1200, 20)],
+    'type':       [(2000, 10)],
+    'toggle':     [(600, 40), (900, 40)],
+    'switch':     [(400, 50), (800, 50)],
+    'ok':         [(880, 80), (1320, 120)],
+    'success':    [(660, 100), (880, 100), (1320, 200)],
+    'done':       [(1320, 150)],
+    'notify':     [(1200, 100), (1400, 100)],
+    'message':    [(1000, 80)],
+    'error':      [(400, 200), (300, 300)],
+    'fail':       [(300, 200), (200, 400)],
+    'denied':     [(200, 150), (150, 150), (100, 300)],
+    'warning':    [(880, 150), (660, 300)],
+    'hit':        [(2000, 30), (1500, 30)],
+    'explosion':  [(100, 400)],
+    'coin':       [(1320, 50), (1760, 80)],
+    'level_up':   [(660, 100), (880, 100), (1100, 100), (1320, 300)],
+    'game_over':  [(440, 200), (330, 300), (220, 500)],
+    'beep':       [(1000, 100)],
+}
+
+
+def _play_beep(freq: int, duration_ms: int) -> None:
+    if _HAS_WINSOUND:
+        try:
+            _winsound.Beep(freq, duration_ms)
+            return
+        except (RuntimeError, ValueError):
+            pass
+    sys.stdout.write('\a')
+    sys.stdout.flush()
+
+
+def _sound(name: str, **kw) -> None:
+    if _SOUND_ENABLED:
+        sound(name, **kw)
+
+
+def sound(name: str = 'click',
+          freq: int | None = None,
+          duration: int | None = None,
+          repeat: int = 1) -> None:
+    """Проигрывает встроенный звук."""
+    if freq is not None:
+        seq = [(freq, duration or 100)]
+    else:
+        seq = SOUNDS.get(name) or [(800, 30)]
+    for _ in range(repeat):
+        for f, d in seq:
+            _play_beep(f, d)
+            time.sleep(d / 1000.0)
+
+
+def sound_off() -> None:
+    global _SOUND_ENABLED
+    _SOUND_ENABLED = False
+
+
+def sound_on() -> None:
+    global _SOUND_ENABLED
+    _SOUND_ENABLED = True
+
+
+def sound_list() -> None:
+    """Печатает список всех доступных звуков."""
+    cprint('Доступные звуки:', color='bright_cyan', bold=True)
+    space()
+    for name, seq in SOUNDS.items():
+        desc = ' → '.join(f'{f}Гц/{d}мс' for f, d in seq)
+        print(f'  {c(name, "yellow"):<24} {c(desc, "gray")}')
+
+
+# ============================================================
+# 4. РАМКИ
+# ============================================================
+
+_BOXES = {
+    'simple':   ('┌', '┬', '┐', '├', '┼', '┤', '└', '┴', '┘', '─', '│'),
+    'rounded':  ('╭', '┬', '╮', '├', '┼', '┤', '╰', '┴', '╯', '─', '│'),
+    'double':   ('╔', '╦', '╗', '╠', '╬', '╣', '╚', '╩', '╝', '═', '║'),
+    'ascii':    ('+', '+', '+', '+', '+', '+', '+', '+', '+', '-', '|'),
+    'markdown': ('|', '|', '|', '|', '|', '|', '|', '|', '|', '-', '|'),
+    'none':     ('', '', '', '', '', '', '', '', '', '', ' '),
+}
+
+
+def section(title: str = '', char: str = '═',
+            width: int | None = None, color: str = 'gray',
+            title_color: str = 'cyan') -> None:
+    width = width or min(term_width() - 2, 60)
+    line = c(char * width, color)
+    print()
+    print(line)
+    if title:
+        print(c(f'  {title}', title_color, bold=True))
+        print(line)
+
+
+def box(text: str, style: str = 'rounded', color: str = 'cyan',
+        title: str = '', padding: int = 1) -> None:
+    lines = str(text).splitlines() or ['']
+    title_line = c(f' {title} ', color, bold=True) if title else None
+    content_width = max(_visible_len(l) for l in lines)
+    if title_line:
+        content_width = max(content_width, _visible_len(title) + 2)
+    width = content_width + padding * 2
+    tl, tt, tr, ml, mm, mr, bl, bt, br, hz, vt = _BOXES.get(style, _BOXES['rounded'])
+    if title_line:
+        t_inner = _visible_len(title) + 2
+        left_seg = hz * ((width - t_inner) // 2)
+        right_seg = hz * (width - t_inner - len(left_seg))
+        print(c(tl + left_seg, color) + title_line + c(right_seg + tr, color))
+    else:
+        print(c(tl + hz * width + tr, color))
+    for line in lines:
+        pad_right = width - _visible_len(line) - padding
+        print(c(vt, color) + ' ' * padding + line + ' ' * pad_right + c(vt, color))
+    print(c(bl + hz * width + br, color))
+
+
+def banner(text: str, style: str = 'double',
+           color: str = 'cyan', text_color: str = 'bright_white') -> None:
+    width = max(_visible_len(text) + 6, 30)
+    tl, tt, tr, ml, mm, mr, bl, bt, br, hz, vt = _BOXES.get(style, _BOXES['double'])
+    print(c(tl + hz * width + tr, color))
+    print(c(vt, color) + ' ' * width + c(vt, color))
+    pad = (width - _visible_len(text)) // 2
+    rest = width - pad - _visible_len(text)
+    print(c(vt, color) + ' ' * pad + c(text, text_color, bold=True)
+          + ' ' * rest + c(vt, color))
+    print(c(vt, color) + ' ' * width + c(vt, color))
+    print(c(bl + hz * width + br, color))
+
+
+def kv(data: dict, style: str = 'rounded',
+       key_color: str = 'cyan', value_color: str | None = None,
+       boxed: bool = True) -> None:
+    if not data:
+        return
+    items = list(data.items())
+    key_w = max(_visible_len(str(k)) for k, _ in items)
+    val_w = max(_visible_len(str(v)) for _, v in items)
+    if not boxed:
+        for k, v in items:
+            val = c(str(v), value_color) if value_color else str(v)
+            print(f'{c(str(k).ljust(key_w), key_color)}  {val}')
+        return
+    tl, tt, tr, ml, mm, mr, bl, bt, br, hz, vt = _BOXES.get(style, _BOXES['rounded'])
+    print(c(tl + hz * (key_w + 2) + tt + hz * (val_w + 2) + tr, 'gray'))
+    for k, v in items:
+        val = c(str(v), value_color) if value_color else str(v)
+        pad_k = ' ' * (key_w - _visible_len(str(k)))
+        pad_v = ' ' * (val_w - _visible_len(str(v)))
+        print(c(vt, 'gray') + ' ' + c(str(k), key_color) + pad_k + ' '
+              + c(vt, 'gray') + ' ' + val + pad_v + ' ' + c(vt, 'gray'))
+    print(c(bl + hz * (key_w + 2) + bt + hz * (val_w + 2) + br, 'gray'))
+
+
+def recap(**kwargs: Any) -> None:
+    icons = {
+        'ok': ('✓', 'green'), 'passed': ('✓', 'green'),
+        'warn': ('⚠', 'yellow'), 'warnings': ('⚠', 'yellow'),
+        'errors': ('✗', 'red'), 'failed': ('✗', 'red'),
+        'skipped': ('·', 'gray'),
+        'duration': ('⏱', 'cyan'), 'time': ('⏱', 'cyan'),
+        'total': ('Σ', 'magenta'),
+    }
+    lines = []
+    for k, v in kwargs.items():
+        icon, col = icons.get(k, ('•', 'white'))
+        lines.append((icon, col, f'{v} {k.replace("_", " ")}'))
+    if not lines:
+        return
+    w = max(_visible_len(f'{i} {t}') for i, _, t in lines) + 4
+    tl, tt, tr, ml, mm, mr, bl, bt, br, hz, vt = _BOXES['rounded']
+    print(c(tl + hz * w + tr, 'gray'))
+    for icon, col, text in lines:
+        line = c(icon, col, bold=True) + ' ' + text
+        pad = ' ' * (w - _visible_len(line) - 1)
+        print(c(vt, 'gray') + ' ' + line + pad + c(vt, 'gray'))
+    print(c(bl + hz * w + br, 'gray'))
+
+
+def notify(text: str, level: str = 'info') -> None:
+    colors = {'ok': 'green', 'info': 'cyan', 'warn': 'yellow', 'err': 'red'}
+    icons = {'ok': '✓', 'info': 'ℹ', 'warn': '⚠', 'err': '✗'}
+    color = colors.get(level, 'cyan')
+    icon = icons.get(level, '•')
+    line_text = f'{icon} {text}'
+    w = _visible_len(line_text) + 4
+    tl, tt, tr, ml, mm, mr, bl, bt, br, hz, vt = _BOXES['rounded']
+    print(c(tl + hz * w + tr, color))
+    print(c(vt, color) + ' ' + c(icon, color, bold=True) + ' ' + text
+          + ' ' * (w - _visible_len(line_text) - 1) + c(vt, color))
+    print(c(bl + hz * w + br, color))
+    if level == 'ok':
+        _sound('ok')
+    elif level == 'warn':
+        _sound('warning')
+    elif level == 'err':
+        _sound('error')
+
+
+def center(text: str, width: int | None = None,
+           color: str | None = None, bold: bool = False) -> None:
+    width = width or term_width()
+    text_w = _visible_len(text)
+    pad = max(0, (width - text_w) // 2)
+    line = ' ' * pad + text
+    if color or bold:
+        line = c(line, color, bold=bold)
+    print(line)
+
+
+def center_box(text: str, style: str = 'rounded',
+               color: str = 'bright_cyan',
+               width: int | None = None) -> None:
+    width = width or min(term_width() - 2, 60)
+    inner = width - 2
+    tl, tt, tr, ml, mm, mr, bl, bt, br, hz, vt = _BOXES.get(style, _BOXES['rounded'])
+    text_w = _visible_len(text)
+    pad_left = max(0, (inner - text_w - 2) // 2)
+    pad_right = inner - pad_left - text_w - 2
+    block_pad = max(0, (term_width() - width) // 2)
+    prefix = ' ' * block_pad
+    print(prefix + c(tl + hz * inner + tr, color))
+    print(prefix + c(vt, color) + ' ' * pad_left + ' '
+          + c(text, 'bright_white', bold=True) + ' ' + ' ' * pad_right + c(vt, color))
+    print(prefix + c(bl + hz * inner + br, color))
+
+
+def box_center(lines, style: str = 'rounded',
+               color: str = 'bright_cyan',
+               text_color: str = 'bright_white',
+               padding: int = 1) -> None:
+    """Многострочная рамка по центру экрана.
+
+    Пример:
+        box_center(['Добро пожаловать!', '', 'Нажми Enter'])
+    """
+    if isinstance(lines, str):
+        lines = lines.splitlines()
+    lines = list(lines) or ['']
+    content_w = max(_visible_len(l) for l in lines)
+    width = content_w + padding * 2
+    inner = width
+    tl, tt, tr, ml, mm, mr, bl, bt, br, hz, vt = _BOXES.get(style, _BOXES['rounded'])
+    block_pad = max(0, (term_width() - width - 2) // 2)
+    prefix = ' ' * block_pad
+    print(prefix + c(tl + hz * inner + tr, color))
+    for line in lines:
+        pad_r = width - _visible_len(line) - padding
+        print(prefix + c(vt, color) + ' ' * padding
+              + c(line, text_color) + ' ' * pad_r + c(vt, color))
+    print(prefix + c(bl + hz * inner + br, color))
+
+
+def title_box(text: str, subtitle: str = '',
+              color: str = 'bright_magenta') -> None:
+    print()
+    center(f'╔{"═" * (len(text) + 4)}╗', color=color)
+    center(f'║  {text}  ║', color=color, bold=True)
+    center(f'╚{"═" * (len(text) + 4)}╝', color=color)
+    if subtitle:
+        center(subtitle, color='gray')
+    print()
+
+
+def notify_center(text: str, level: str = 'info',
+                  duration: float = 1.5) -> None:
+    """Всплывающее уведомление по центру экрана.
+
+    Пример:
+        notify_center('Файл сохранён', 'ok')
+    """
+    colors = {'ok': 'green', 'info': 'cyan', 'warn': 'yellow', 'err': 'red'}
+    icons = {'ok': '✓', 'info': 'ℹ', 'warn': '⚠', 'err': '✗'}
+    color = colors.get(level, 'cyan')
+    icon = icons.get(level, '•')
+    line_text = f'{icon} {text}'
+    w = _visible_len(line_text) + 4
+    tl, tt, tr, ml, mm, mr, bl, bt, br, hz, vt = _BOXES['rounded']
+
+    print()
+    print(c(' ' * ((term_width() - w - 2) // 2) + tl + hz * w + tr, color))
+    print(c(' ' * ((term_width() - w - 2) // 2) + vt, color)
+          + ' ' + c(icon, color, bold=True) + ' ' + text
+          + ' ' * (w - _visible_len(line_text) - 1) + c(vt, color))
+    print(c(' ' * ((term_width() - w - 2) // 2) + bl + hz * w + br, color))
+
+    if level == 'ok':
+        _sound('ok')
+    elif level == 'warn':
+        _sound('warning')
+    elif level == 'err':
+        _sound('error')
+
+    time.sleep(duration)
+    # Стираем — поднимаемся на 3 строки
+    for _ in range(3):
+        sys.stdout.write('\033[1A\033[K')
+    sys.stdout.flush()
+
+
+# ============================================================
+# 5. ТАБЛИЦЫ
+# ============================================================
+
+def _pad(text: str, width: int, align: str) -> str:
+    if align == 'right':
+        return text.rjust(width)
+    if align == 'center':
+        return text.center(width)
+    return text.ljust(width)
+
+
+def table(rows: Iterable[dict],
+          headers: list[str] | None = None,
+          *,
+          style: str = 'rounded',
+          align: str | dict = 'left',
+          colors: dict | None = None,
+          highlight: Callable[[dict], bool] | None = None,
+          formatters: dict | None = None,
+          max_width: int | None = None,
+          auto_width: bool = False,
+          footer: dict | None = None,
+          padding: int = 1,
+          _return: bool = False) -> str | None:
+    """Печатает таблицу из списка словарей."""
+    rows = list(rows)
+    if not rows:
+        msg = c('(пусто)', 'gray')
+        if _return:
+            return msg
+        print(msg)
+        return msg
+    if headers is None:
+        headers = list(rows[0].keys())
+    colors = colors or {}
+    head_color = colors.get('header', 'cyan')
+    border_color = colors.get('border', 'gray')
+    zebra_color = colors.get('zebra')
+    highlight_color = colors.get('highlight', 'yellow')
+    footer_color = colors.get('footer', 'bright_white')
+    formatters = formatters or {}
+    if isinstance(align, str):
+        align = {h: align for h in headers}
+    if auto_width and max_width is None:
+        avail = term_width() - (len(headers) * 2 + 4)
+        max_width = max(6, avail // max(1, len(headers)))
+
+    def fmt_cell(h: str, v: Any) -> str:
+        s = formatters[h](v) if h in formatters else ('' if v is None else str(v))
+        if max_width and _visible_len(s) > max_width:
+            s = s[:max_width - 1] + '…'
+        return s
+
+    body = [{h: fmt_cell(h, r.get(h, '')) for h in headers} for r in rows]
+    widths = {h: _visible_len(str(h)) for h in headers}
+    for r in body:
+        for h in headers:
+            widths[h] = max(widths[h], _visible_len(r[h]))
+    if footer:
+        for h in headers:
+            if h in footer:
+                widths[h] = max(widths[h], _visible_len(str(footer[h])))
+
+    tl, tt, tr, ml, mm, mr, bl, bt, br, hz, vt = _BOXES.get(style, _BOXES['rounded'])
+
+    def hline(left, mid, right):
+        parts = [hz * (widths[h] + padding * 2) for h in headers]
+        return c(left + mid.join(parts) + right, border_color)
+
+    out = [hline(tl, tt, tr)]
+    head_cells = [
+        ' ' * padding + c(_pad(str(h), widths[h], 'center'), head_color, bold=True)
+        + ' ' * padding
+        for h in headers
+    ]
+    out.append(c(vt, border_color) + c(vt, border_color).join(head_cells)
+               + c(vt, border_color))
+    if style not in ('markdown', 'none'):
+        out.append(hline(ml, mm, mr))
+    elif style == 'markdown':
+        out.append('|' + '|'.join('-' * (widths[h] + padding * 2) for h in headers) + '|')
+    for idx, (r, row_orig) in enumerate(zip(body, rows)):
+        is_hi = highlight and highlight(row_orig)
+        cells = []
+        for h in headers:
+            cell = _pad(r[h], widths[h], align.get(h, 'left'))
+            cell = ' ' * padding + cell + ' ' * padding
+            if is_hi:
+                cell = c(cell, highlight_color, bold=True)
+            elif zebra_color and idx % 2 == 1:
+                cell = c(cell, zebra_color)
+            cells.append(cell)
+        out.append(c(vt, border_color) + c(vt, border_color).join(cells)
+                   + c(vt, border_color))
+    if footer:
+        out.append(hline(ml, mm, mr))
+        cells = [
+            ' ' * padding + c(_pad(str(footer.get(h, '')), widths[h],
+                                    align.get(h, 'left')), footer_color, bold=True)
+            + ' ' * padding
+            for h in headers
+        ]
+        out.append(c(vt, border_color) + c(vt, border_color).join(cells)
+                   + c(vt, border_color))
+    out.append(hline(bl, bt, br))
+    text = '\n'.join(out)
+    if _return:
+        return text
+    print(text)
+    return text
+
+
+class Table:
+    """Fluent-обёртка над table().
+
+    Пример:
+        Table(users) \\
+            .style('double') \\
+            .align('age', 'center') \\
+            .format('score', lambda v: f'{v:,}') \\
+            .highlight(lambda r: r['score'] > 1000) \\
+            .footer({'name': 'Итого', 'score': 5000}) \\
+            .show()
+    """
+    def __init__(self, rows: list[dict]):
+        self._rows = list(rows)
+        self._style = 'rounded'
+        self._align: dict = {}
+        self._colors: dict = {}
+        self._highlight = None
+        self._formatters: dict = {}
+        self._footer = None
+        self._max_width = None
+        self._auto_width = False
+
+    def style(self, s: str) -> 'Table':
+        self._style = s
+        return self
+
+    def align(self, column: str, align: str) -> 'Table':
+        self._align[column] = align
+        return self
+
+    def color(self, key: str, color: str) -> 'Table':
+        self._colors[key] = color
+        return self
+
+    def format(self, column: str, fn: Callable) -> 'Table':
+        self._formatters[column] = fn
+        return self
+
+    def highlight(self, fn: Callable) -> 'Table':
+        self._highlight = fn
+        return self
+
+    def footer(self, data: dict) -> 'Table':
+        self._footer = data
+        return self
+
+    def max_width(self, n: int) -> 'Table':
+        self._max_width = n
+        return self
+
+    def auto_width(self, flag: bool = True) -> 'Table':
+        self._auto_width = flag
+        return self
+
+    def show(self) -> str:
+        return table(
+            self._rows,
+            style=self._style,
+            align=self._align or 'left',
+            colors=self._colors,
+            highlight=self._highlight,
+            formatters=self._formatters,
+            footer=self._footer,
+            max_width=self._max_width,
+            auto_width=self._auto_width,
+        )
+
+    # Алиас
+    def render(self) -> str:
+        return self.show()
+
+
+def to_table(data: dict) -> list[dict]:
+    return [{'key': k, 'value': v} for k, v in data.items()]
+
+
+def table_from_csv(path: str, **kwargs) -> str | None:
+    """Печатает CSV-файл как таблицу.
+
+    Пример:
+        table_from_csv('users.csv', style='double')
+    """
+    rows = read_csv(path)
+    if not rows:
+        warn(f'Файл {path} пуст')
+        return None
+    return table(rows, **kwargs)
+
+
+# ============================================================
+# 6. ДАННЫЕ
+# ============================================================
+
+def columns(items: list, gap: int = 2, color: str | None = None,
+            indent: int = 0) -> None:
+    if not items:
+        return
+    items = [str(i) for i in items]
+    max_w = max(_visible_len(i) for i in items)
+    cell = max_w + gap
+    width = term_width() - indent
+    n_cols = max(1, width // cell)
+    n_rows = (len(items) + n_cols - 1) // n_cols
+    prefix = ' ' * indent
+    for row in range(n_rows):
+        parts = []
+        for col in range(n_cols):
+            idx = col * n_rows + row
+            if idx >= len(items):
+                continue
+            item = items[idx]
+            pad = ' ' * (cell - _visible_len(item))
+            parts.append((c(item, color) if color else item) + pad)
+        print(prefix + ''.join(parts).rstrip())
+
+
+def tree(data: dict, prefix: str = '', color: str = 'cyan',
+         branch_color: str = 'gray') -> None:
+    items = list(data.items())
+    for i, (name, child) in enumerate(items):
+        last = i == len(items) - 1
+        branch = '└── ' if last else '├── '
+        print(prefix + c(branch, branch_color) + c(str(name), color))
+        if isinstance(child, dict):
+            tree(child, prefix + ('    ' if last else '│   '), color, branch_color)
+
+
+def diff(a: dict, b: dict, arrow: str = '→') -> None:
+    for k in sorted(set(a) | set(b), key=str):
+        va = a.get(k, '<нет>')
+        vb = b.get(k, '<нет>')
+        if va == vb:
+            print(f'  {c(str(k), "gray")}: {c(str(va), "gray")}')
+        else:
+            print(f'  {c(str(k), "yellow")}: '
+                  f'{c(str(va), "red")} {c(arrow, "gray")} {c(str(vb), "green")}')
+
+
+_SPARK_CHARS = '▁▂▃▄▅▆▇█'
+
+
+def chart(values: list[float], label: str = '', color: str = 'cyan') -> None:
+    if not values:
+        return
+    lo, hi = min(values), max(values)
+    span = hi - lo or 1
+    chars = []
+    for v in values:
+        idx = int((v - lo) / span * (len(_SPARK_CHARS) - 1))
+        chars.append(_SPARK_CHARS[max(0, min(len(_SPARK_CHARS) - 1, idx))])
+    prefix = c(f'{label:<8}', 'gray') if label else ''
+    print(prefix + c(''.join(chars), color))
+
+
+def flatten(nested):
+    for item in nested:
+        if isinstance(item, (list, tuple, set)):
+            yield from flatten(item)
+        else:
+            yield item
+
+
+def group_by(items: Iterable, key: Callable) -> dict:
+    from collections import defaultdict
+    result = defaultdict(list)
+    for item in items:
+        result[key(item)].append(item)
+    return dict(result)
+
+
+def deep_merge(a: dict, b: dict) -> dict:
+    result = dict(a)
+    for k, v in b.items():
+        if k in result and isinstance(result[k], dict) and isinstance(v, dict):
+            result[k] = deep_merge(result[k], v)
+        else:
+            result[k] = v
+    return result
+
+
+def env_all(prefix: str = '') -> dict:
+    return {k[len(prefix):]: v for k, v in os.environ.items() if k.startswith(prefix)}
+
+
+def read_csv(path: str) -> list[dict]:
+    with open(path, encoding='utf-8', newline='') as f:
+        return list(csv.DictReader(f))
+
+
+def write_csv(path: str, rows: list[dict]) -> Path:
+    if not rows:
+        Path(path).write_text('', encoding='utf-8')
+        return Path(path)
+    p = Path(path)
+    p.parent.mkdir(parents=True, exist_ok=True)
+    with open(p, 'w', encoding='utf-8', newline='') as f:
+        w = csv.DictWriter(f, fieldnames=list(rows[0].keys()))
+        w.writeheader()
+        w.writerows(rows)
+    return p
+
+
+# ============================================================
+# 7. ПРЕСЕТЫ СПИННЕРА
+# ============================================================
+
+SPINNER_FRAMES = {
+    'dots':        '⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏' * 3,
+    'dots_dense':  '⣾⣽⣻⢿⡿⣟⣯⣷' * 3,
+    'smooth':      '⠁⠂⠄⡀⢀⠠⠐⠈' * 3,
+    'smooth_wave': ('⠁⠂⠄⡀⢀⠠⠐⠈'
+                    '⠘⠚⠒⠓⠋⠉⠑⠈'
+                    '⠙⠚⠖⠦⠤⠠⠒⠊'),
+    'pulse':       '⣀⣄⣤⣦⣶⣷⣿⣷⣶' * 3,
+    'bars':        '▁▂▃▄▅▆▇████▇▆▅▄▃▂▁' * 2,
+    'grow':        '▏▎▍▌▋▊▉██▉▊▋▌▍▎' * 2,
+    'circle':      '◐◓◑◒' * 6,
+    'circle_thin': '◜◠◝◞◡◟' * 4,
+    'circle_dot':  '◜◝◞◟' * 6,
+    'clock':       '◴◷◶◵' * 6,
+    'breathe':     '◜◝◞◟' * 6,
+    'gauge':       '○◔◑◕●◕◑◔' * 3,
+    'radar':       '◜◠◝◞◡◟◜◠◝◞◡◟' * 2,
+    'compass':     '←↖↑↗→↘↓↙' * 3,
+    'arrow':       '←↖↑↗→↘↓↙' * 3,
+    'arrows':      '↻↺' * 12,
+    'arrows_bold': '⟲⟳' * 12,
+    'arrows_dash': '⬅⬉⬆⬈➡⬊⬇⬋',
+    'arrows_dbl':  '⇐⇑⇒⇓' * 6,
+    'moon':        '🌑🌒🌓🌔🌕🌖🌗🌘' * 3,
+    'moon_rev':    '🌘🌗🌖🌕🌔🌓🌒🌑' * 3,
+    'earth':       '🌍🌎🌏' * 8,
+    'clock_emoji': '🕐🕑🕒🕓🕔🕕🕖🕗🕘🕙🕚🕛',
+    'clock_half':  '🕜🕝🕞🕟🕠🕡🕢🕣🕤🕥🕦🕧',
+    'weather':     '☀🌤⛅🌥☁🌦🌧⛈' * 3,
+    'star':        '·✧✦✩✪✫✬✭✮✯',
+    'hearts':      '♡♥' * 12,
+    'music':       '♪♫' * 12,
+    'traffic':     '🔴🟡🟢🟡' * 6,
+    'hourglass':   '⏳⌛' * 12,
+    'fire':        '🔥 ',
+    'sparkle':     '✨ ',
+    'rocket':      '🚀 ',
+    'gem':         '💎 ',
+    'diamond_e':   '💠 ',
+    'crystal':     '🔮 ',
+    'atom':        '⚛ ',
+    'gear':        '⚙ ',
+    'lightning':   '⚡ ',
+    'braille1':    '⠁⠂⠄⡀⢀⠠⠐⠈' * 3,
+    'braille3':    '⠁⠉⠙⠚⠒⠂⠒⠲⠴⠤⠄⠤⠦⠖⠚⠒',
+    'braille5':    '⢄⢂⢁⡁⡈⡐⡠⣀⣀' * 3,
+    'braille7':    '⡀⡄⡆⡇⣇⣧⣷⣿⣿' * 3,
+    'blocks1':     '▁▂▃▄▅▆▇█▇▆▅▄▃▂' * 2,
+    'blocks2':     '▏▎▍▌▋▊▉█▉▊▋▌▍▎' * 2,
+    'blocks3':     '░▒▓█▓▒░' * 4,
+    'diamond':     '◇◈◆◈◇' * 5,
+    'tri':         '◢◣◤◥' * 6,
+    'line':        '|/-\\' * 6,
+    'ascii_dots':  '.oO@*' * 5,
+    'ascii_light': '=+*#%@' * 4,
+    'wave':        '▁▂▃▄▅▆▇█▇▆▅▄▃▂▁' * 2,
+    'sine':        '▁▂▄▆█▆▄▂▁' * 3,
+}
+
+FANCY_PRESETS = [
+    'dots_dense', 'smooth', 'smooth_wave', 'pulse',
+    'circle', 'circle_thin', 'circle_dot', 'clock',
+    'breathe', 'moon', 'arrow', 'radar', 'gauge',
+    'wave', 'sine', 'sparkle',
+]
+
+CIRCLE_PRESETS = ['circle', 'circle_thin', 'circle_dot', 'clock',
+                  'breathe', 'gauge', 'radar', 'compass']
+
+PLAIN_PRESETS = ['dots', 'dots_dense', 'smooth', 'smooth_wave',
+                 'pulse', 'bars', 'grow', 'line', 'arrow']
+
+EMOJI_PRESETS = ['moon', 'moon_rev', 'earth', 'clock_emoji', 'clock_half',
+                 'weather', 'star', 'hearts', 'music', 'traffic',
+                 'hourglass', 'fire', 'sparkle', 'rocket', 'gem', 'crystal']
+
+ASCII_PRESETS = ['line', 'ascii_dots', 'ascii_light', 'braille1', 'braille3']
+
+_random_preset: str | None = None
+
+
+def pick_preset(kind: str = 'fancy') -> str:
+    pools = {
+        'fancy': FANCY_PRESETS, 'circle': CIRCLE_PRESETS,
+        'plain': PLAIN_PRESETS, 'emoji': EMOJI_PRESETS,
+        'ascii': ASCII_PRESETS, 'any': list(SPINNER_FRAMES.keys()),
+    }
+    return random.choice(pools.get(kind, FANCY_PRESETS))
+
+
+# ============================================================
+# 8. ПЛАНИРОВЩИК КАДРОВ
+# ============================================================
+
+def _frame_scheduler(stop: threading.Event, speed: float,
+                     render_fn: Callable):
+    next_tick = time.perf_counter()
+    while not stop.is_set():
+        render_fn()
+        next_tick += speed
+        while True:
+            delta = next_tick - time.perf_counter()
+            if delta <= 0:
+                next_tick = time.perf_counter()
+                break
+            if delta > 0.002:
+                time.sleep(delta - 0.001)
+
+
+# ============================================================
+# 9. WITH-БЛОК SPINNER
+# ============================================================
+
+class _SpinnerCtx:
+    """Контекст спиннера с методами pause/resume."""
+    def __init__(self, stop_event, paused_event):
+        self._stop = stop_event
+        self._paused = paused_event
+
+    def pause(self):
+        """Пауза анимации."""
+        self._paused.set()
+
+    def resume(self):
+        """Продолжить."""
+        self._paused.clear()
+
+
+@contextmanager
+def spinner(text: str = 'Загрузка', preset: str | None = None,
+            kind: str | None = None, frames: str | None = None,
+            color: str | None = None, speed: float | None = None,
+            done: str = '✓', done_color: str = 'green',
+            keep: bool = True, show_time: bool | None = None,
+            random_preset: bool = True):
+    """Универсальная крутилка. Возвращает ctx с .pause() и .resume()."""
+    global _random_preset
+
+    color = color if color is not None else _SPINNER_DEFAULTS['color']
+    speed = speed if speed is not None else _SPINNER_DEFAULTS['speed']
+    show_time = show_time if show_time is not None else _SPINNER_DEFAULTS['show_time']
+    kind = kind if kind is not None else _SPINNER_DEFAULTS['kind']
+    if preset is None:
+        preset = _SPINNER_DEFAULTS['preset']
+
+    if frames is None:
+        if preset is None:
+            if random_preset:
+                if _random_preset is None:
+                    _random_preset = pick_preset(kind)
+                preset = _random_preset
+            else:
+                preset = pick_preset(kind)
+        frames = SPINNER_FRAMES.get(preset, SPINNER_FRAMES['dots_dense'])
+
+    stop = threading.Event()
+    paused = threading.Event()
+    ctx = _SpinnerCtx(stop, paused)
+    start = time.time()
+    frame_iter = itertools.cycle(frames)
+
+    def render():
+        if paused.is_set():
+            return
+        try:
+            ch = next(frame_iter)
+        except StopIteration:
+            return
+        suffix = ' ' + c(f'{time.time() - start:.1f}s', 'gray') if show_time else ''
+        sys.stdout.write(f'\r{c(ch, color)} {text}{suffix}\033[K')
+        sys.stdout.flush()
+
+    th = threading.Thread(target=_frame_scheduler,
+                          args=(stop, speed, render), daemon=True)
+    th.start()
+    error = False
+    try:
+        yield ctx
+    except Exception:
+        error = True
+        raise
+    finally:
+        stop.set()
+        th.join()
+        elapsed = time.time() - start
+        clear = ' ' * (_visible_len(text) + 14)
+        if keep:
+            icon = c('✗', 'red', bold=True) if error else c(done, done_color, bold=True)
+            time_str = c(f' ({elapsed:.1f}s)', 'gray') if show_time else ''
+            sys.stdout.write(f'\r{clear}\r{icon} {text}{time_str}\n')
+        else:
+            sys.stdout.write(f'\r{clear}\r')
+        sys.stdout.flush()
+
+
+# Алиас для явного использования
+spinner_pause = None   # будет подменён ниже функцией
+
+
+def spinner_pause(paused: bool = True) -> None:
+    """Глобальный флаг паузы — не используется.
+    Используй `with spinner('X') as s: s.pause()`.
+    """
+    warn('spinner_pause() устарел. Используй: with spinner(...) as s: s.pause()')
+
+
+# ============================================================
+# 10. СПИННЕР ЧЕРЕЗ F-СТРОКУ
+# ============================================================
+
+_FSPIN_STOP = threading.Event()
+_FSPIN_THREAD: threading.Thread | None = None
+_FSPIN_LINE = ''
+_FSPIN_COLOR = 'cyan'
+_FSPIN_PRESET: str | None = None
+
+
+def _fspin_loop():
+    frames = SPINNER_FRAMES.get(_FSPIN_PRESET or 'dots_dense',
+                                 SPINNER_FRAMES['dots_dense'])
+    next_tick = time.perf_counter()
+    for ch in itertools.cycle(frames):
+        if _FSPIN_STOP.is_set():
+            break
+        text = f'{c(ch, _FSPIN_COLOR)} {_FSPIN_LINE}'
+        sys.stdout.write(f'\r{text}\033[K')
+        sys.stdout.flush()
+        next_tick += _SPINNER_DEFAULTS['speed']
+        while True:
+            delta = next_tick - time.perf_counter()
+            if delta <= 0:
+                next_tick = time.perf_counter()
+                break
+            if delta > 0.002:
+                time.sleep(delta - 0.001)
+
+
+def _fspin_start(text: str, color: str | None = None,
+                 preset: str | None = None):
+    global _FSPIN_THREAD, _FSPIN_STOP, _FSPIN_LINE, _FSPIN_COLOR, _FSPIN_PRESET
+    if _FSPIN_THREAD and _FSPIN_THREAD.is_alive():
+        _FSPIN_STOP.set()
+        _FSPIN_THREAD.join()
+    _FSPIN_STOP = threading.Event()
+    _FSPIN_LINE = text
+    _FSPIN_COLOR = color if color is not None else _SPINNER_DEFAULTS['color']
+    _FSPIN_PRESET = preset or _SPINNER_DEFAULTS['preset'] or 'dots_dense'
+    _FSPIN_THREAD = threading.Thread(target=_fspin_loop, daemon=True)
+    _FSPIN_THREAD.start()
+
+
+def _fspin_finish(icon: str, icon_color: str, text: str = '',
+                  duration: float | None = None):
+    global _FSPIN_THREAD, _FSPIN_LINE
+    if _FSPIN_THREAD and _FSPIN_THREAD.is_alive():
+        _FSPIN_STOP.set()
+        _FSPIN_THREAD.join()
+    line = text or _FSPIN_LINE
+    dt = f' {c(f"({duration:.2f}s)", "gray")}' if duration is not None else ''
+    sys.stdout.write(f'\r\033[K{c(icon, icon_color, bold=True)} {line}{dt}\n')
+    sys.stdout.flush()
+    _FSPIN_LINE = ''
+
+
+def spin(text: str = '', color: str | None = None,
+         preset: str | None = None) -> str:
+    """Спиннер через f-строку."""
+    _fspin_start(text, color, preset)
+    return ''
+
+
+sp = spin
+
+
+def spin_done(done: str = '✓', color: str = 'green',
+              newline: bool = True) -> None:
+    global _FSPIN_THREAD, _FSPIN_LINE
+    if not _FSPIN_THREAD or not _FSPIN_THREAD.is_alive():
+        return
+    _FSPIN_STOP.set()
+    _FSPIN_THREAD.join()
+    icon = c(done, color, bold=True)
+    sys.stdout.write(f'\r\033[K{icon} {_FSPIN_LINE}')
+    if newline:
+        sys.stdout.write('\n')
+    sys.stdout.flush()
+    _FSPIN_LINE = ''
+
+
+def spin_fail(msg: str = '', color: str = 'red',
+              newline: bool = True) -> None:
+    global _FSPIN_THREAD, _FSPIN_LINE
+    if not _FSPIN_THREAD or not _FSPIN_THREAD.is_alive():
+        return
+    _FSPIN_STOP.set()
+    _FSPIN_THREAD.join()
+    icon = c('✗', color, bold=True)
+    text = _FSPIN_LINE
+    if msg:
+        text = f'{text} — {msg}' if text else msg
+    sys.stdout.write(f'\r\033[K{icon} {text}')
+    if newline:
+        sys.stdout.write('\n')
+    sys.stdout.flush()
+    _FSPIN_LINE = ''
+
+
+# ============================================================
+# 11. STEP_RUN / DO / PAUSE / WAIT
+# ============================================================
+
+def step_run(*tasks, label: str | None = None,
+             color: str | None = None,
+             show_time: bool | None = None,
+             stop_on_error: bool = True,
+             raise_on_error: bool = False):
+    """Универсальный раннер с крутилкой."""
+    color = color if color is not None else _SPINNER_DEFAULTS['color']
+    show_time = show_time if show_time is not None else _SPINNER_DEFAULTS['show_time']
+
+    steps: list[tuple[str, Callable | None, tuple]] = []
+    if not tasks:
+        steps = [('', None, ())]
+    else:
+        i = 0
+        while i < len(tasks):
+            item = tasks[i]
+            if isinstance(item, (list, tuple)):
+                lbl = str(item[0]) if item else ''
+                fn = item[1] if len(item) > 1 and callable(item[1]) else None
+                steps.append((lbl, fn, ()))
+                i += 1
+            elif callable(item):
+                steps.append((label or getattr(item, '__name__', 'running'),
+                              item, ()))
+                i += 1
+            else:
+                lbl = str(item)
+                if i + 1 < len(tasks):
+                    nxt = tasks[i + 1]
+                    if callable(nxt) and not isinstance(nxt, str):
+                        fn = nxt
+                        args = []
+                        j = i + 2
+                        while j < len(tasks) and not callable(tasks[j]) and \
+                                not isinstance(tasks[j], (list, tuple)):
+                            if j + 1 < len(tasks) and callable(tasks[j + 1]) and \
+                                    isinstance(tasks[j], str):
+                                break
+                            args.append(tasks[j])
+                            j += 1
+                        steps.append((lbl, fn, tuple(args)))
+                        i = j
+                        continue
+                steps.append((lbl, None, ()))
+                i += 1
+
+    results = []
+    for text, fn, args in steps:
+        display = text or (getattr(fn, '__name__', '') if fn else '')
+        if label and text:
+            display = f'{label} {text}'
+        start = time.perf_counter()
+        _fspin_start(display, color)
+        try:
+            if fn is None:
+                result = None
+            else:
+                result = fn(*args)
+            dt = time.perf_counter() - start
+            _fspin_finish('✓', 'green', display, dt if show_time else None)
+            results.append(result)
+        except Exception as e:
+            dt = time.perf_counter() - start
+            _fspin_finish('✗', 'red',
+                          f'{display} — {type(e).__name__}: {e}',
+                          dt if show_time else None)
+            if stop_on_error:
+                if raise_on_error:
+                    raise
+                return results if len(results) > 1 else (results[0] if results else None)
+            results.append(e)
+    if len(results) == 1:
+        return results[0]
+    return results
+
+
+def run(label: str, fn: Callable, *args, **kwargs):
+    return step_run(label, fn, *args, **kwargs)
+
+
+def run_all(*pairs, **kwargs):
+    return step_run(*pairs, **kwargs)
+
+
+def do(text: str, fn: Callable, *args, **kwargs):
+    return step_run(text, fn, *args, **kwargs)
+
+
+def pause(text: str = 'Пауза', seconds: float = 1.0):
+    step_run(text, time.sleep, seconds)
+
+
+def wait(seconds: float = 1.0, text: str = '') -> None:
+    """Простой отсчёт с обновляющейся строкой.
+
+    Пример:
+        wait(5, 'Подождите')     # печатает «Подождите... 5с»
+    """
+    label = text or 'Ждём'
+    start = time.time()
+    end = start + seconds
+    while True:
+        left = end - time.time()
+        if left <= 0:
+            break
+        sys.stdout.write(
+            f'\r{c("⏱", "cyan")} {label}... {c(f"{left:5.1f}с", "yellow")}\033[K'
+        )
+        sys.stdout.flush()
+        time.sleep(0.1)
+    sys.stdout.write(
+        f'\r{c("✓", "green", bold=True)} {label} ({seconds:g}с)\n'
+    )
+    sys.stdout.flush()
+    _sound('done')
+
+
+def step(n: int, text: str, ok_: bool = True) -> None:
+    icon = c('✓', 'green', bold=True) if ok_ else c('✗', 'red', bold=True)
+    print(f'{c(f"[{n}]", "cyan")} {text} {icon}')
+
+
+def task(n: int, total: int, text: str, ok_: bool = True,
+         color: str = 'cyan') -> None:
+    icon = c('✓', 'green', bold=True) if ok_ else c('✗', 'red', bold=True)
+    print(f'{c(f"[{n}/{total}]", color, dim=True)} {text} {icon}')
+
+
+# ============================================================
+# 12. ПРОГРЕСС И БАРЫ
+# ============================================================
+
+class circle_bar:
+    STEPS = ['○', '◔', '◑', '◕', '●']
+
+    def __init__(self, total: int, prefix: str = '', width: int = 10,
+                 color: str = 'cyan', bg_color: str = 'gray'):
+        self.total, self.prefix, self.width = total, prefix, width
+        self.color, self.bg_color = color, bg_color
+        self.start = time.time()
+        self._last_len = 0
+
+    def _ring(self, pct: float) -> str:
+        filled_exact = pct * self.width
+        filled = int(filled_exact)
+        frac = filled_exact - filled
+        partial = min(int(frac * (len(self.STEPS) - 1)), len(self.STEPS) - 1)
+        parts = []
+        for i in range(self.width):
+            if i < filled:
+                parts.append(c('●', self.color))
+            elif i == filled and frac > 0:
+                parts.append(c(self.STEPS[partial], self.color))
+            else:
+                parts.append(c('○', self.bg_color))
+        return ''.join(parts)
+
+    def update(self, n: int, suffix: str = '') -> None:
+        pct = n / self.total
+        elapsed = time.time() - self.start
+        eta = (elapsed / n) * (self.total - n) if n else 0
+        line = f'{self.prefix} [{self._ring(pct)}] {n}/{self.total} {pct*100:5.1f}%'
+        if eta and n < self.total:
+            line += f' ETA {human_time(eta, short=True):>6}'
+        if suffix:
+            line += f' {suffix}'
+        pad = max(0, self._last_len - _visible_len(line))
+        sys.stdout.write('\r' + line + ' ' * pad)
+        sys.stdout.flush()
+        self._last_len = _visible_len(line)
+
+    def close(self) -> None:
+        sys.stdout.write('\n')
+        sys.stdout.flush()
+
+
+def progress(iterable: Iterable, total: int | None = None,
+             prefix: str = '', width: int = 30,
+             show_eta: bool = True) -> Iterator:
+    items = list(iterable) if total is None else iterable
+    total = total or len(items)
+    start = time.time()
+    for i, item in enumerate(items, 1):
+        yield item
+        done = int(width * i / total)
+        pct = 100 * i / total
+        elapsed = time.time() - start
+        eta = (elapsed / i) * (total - i) if i else 0
+        bar = '█' * done + '░' * (width - done)
+        tail = f'{pct:5.1f}%'
+        if show_eta:
+            tail += f' ETA {human_time(eta, short=True):>6}'
+        sys.stdout.write(f'\r{prefix} [{bar}] {i}/{total} {tail}\033[K')
+        sys.stdout.flush()
+    print()
+
+
+def progress3(iterable: Iterable, total: int | None = None,
+              prefix: str = '', width: int = 30,
+              colors: tuple = ('red', 'yellow', 'green'),
+              show_eta: bool = True) -> Iterator:
+    """Прогресс-бар с 3-цветной заливкой."""
+    items = list(iterable) if total is None else iterable
+    total = total or len(items)
+    start = time.time()
+    r1, g1, b1 = _any_to_rgb(colors[0])
+    r2, g2, b2 = _any_to_rgb(colors[1])
+    r3, g3, b3 = _any_to_rgb(colors[2])
+
+    for i, item in enumerate(items, 1):
+        yield item
+        done = int(width * i / total)
+        pct = 100 * i / total
+        elapsed = time.time() - start
+        eta = (elapsed / i) * (total - i) if i else 0
+
+        parts = []
+        for k in range(width):
+            if k < done:
+                t = k / max(width - 1, 1)
+                if t <= 0.5:
+                    u = t * 2
+                    r = int(r1 + (r2 - r1) * u)
+                    g = int(g1 + (g2 - g1) * u)
+                    b = int(b1 + (b2 - b1) * u)
+                else:
+                    u = (t - 0.5) * 2
+                    r = int(r2 + (r3 - r2) * u)
+                    g = int(g2 + (g3 - g2) * u)
+                    b = int(b2 + (b3 - b2) * u)
+                parts.append(f'\033[38;2;{r};{g};{b}m█')
+            else:
+                parts.append('░')
+        bar = ''.join(parts) + _RESET
+
+        tail = f'{pct:5.1f}%'
+        if show_eta:
+            tail += f' ETA {human_time(eta, short=True):>6}'
+        sys.stdout.write(f'\r{prefix} [{bar}] {i}/{total} {tail}\033[K')
+        sys.stdout.flush()
+    print()
+
+
+def progress_multi(labels: list[str], width: int = 30) -> '_ProgressMulti':
+    """Параллельные прогресс-бары (как в docker compose up).
+
+    Пример:
+        with progress_multi(['Скачивание', 'Распаковка', 'Индексация']) as pm:
+            for i in range(1, 101):
+                pm.update('Скачивание', i)
+                pm.update('Распаковка', i // 2)
+                time.sleep(0.02)
+    """
+    return _ProgressMulti(labels, width)
+
+
+class _ProgressMulti:
+    def __init__(self, labels: list[str], width: int = 30):
+        self.labels = list(labels)
+        self.width = width
+        self.values = {l: 0 for l in labels}
+        self.total = {l: 100 for l in labels}
+        self._lines = 0
+        self._start = time.time()
+
+    def update(self, label: str, value: float, total: float | None = None):
+        if label not in self.labels:
+            return
+        self.values[label] = value
+        if total is not None:
+            self.total[label] = total
+        self._render()
+
+    def _render(self):
+        # Стираем предыдущий рендер
+        if self._lines:
+            sys.stdout.write(f'\033[{self._lines}A')
+            for _ in range(self._lines):
+                sys.stdout.write('\033[K\n')
+            sys.stdout.write(f'\033[{self._lines}A')
+
+        for label in self.labels:
+            val = self.values[label]
+            tot = self.total[label] or 1
+            pct = val / tot
+            done = int(self.width * pct)
+            bar = c('█' * done, 'bright_cyan') + c('░' * (self.width - done), 'gray')
+            line = f'{label:<15} [{bar}] {val:>5.0f}/{tot:<5.0f} {pct*100:5.1f}%'
+            sys.stdout.write(line + '\033[K\n')
+        self._lines = len(self.labels)
+        sys.stdout.flush()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args):
+        self._render()
+
+
+class PBar:
+    def __init__(self, total: int, prefix: str = '', width: int = 30,
+                 show_eta: bool = True):
+        self.total, self.prefix, self.width = total, prefix, width
+        self.show_eta = show_eta
+        self.start = time.time()
+
+    def update(self, n: int, suffix: str = '') -> None:
+        done = int(self.width * n / self.total)
+        pct = 100 * n / self.total
+        elapsed = time.time() - self.start
+        eta = (elapsed / n) * (self.total - n) if n else 0
+        bar = '█' * done + '░' * (self.width - done)
+        tail = f'{pct:5.1f}%'
+        if self.show_eta:
+            tail += f' ETA {human_time(eta, short=True):>6}'
+        line = f'{self.prefix} [{bar}] {n}/{self.total} {tail}'
+        if suffix:
+            line += f' {suffix}'
+        sys.stdout.write('\r' + line + '\033[K')
+        sys.stdout.flush()
+
+    def close(self) -> None:
+        sys.stdout.write('\n')
+        sys.stdout.flush()
+
+
+def progress_glow(iterable, prefix: str = '', width: int = 30,
+                  colors: list[str] | None = None):
+    colors = colors or ['cyan', 'bright_cyan', 'bright_blue',
+                        'magenta', 'bright_magenta']
+    items = list(iterable)
+    total = len(items)
+    start = time.time()
+    for i, item in enumerate(items, 1):
+        yield item
+        done = int(width * i / total)
+        pct = 100 * i / total
+        elapsed = time.time() - start
+        eta = (elapsed / i) * (total - i) if i else 0
+        col = colors[(i // 2) % len(colors)]
+        bar = c('█' * done, col) + c('░' * (width - done), 'gray')
+        tail = f'{pct:5.1f}% ETA {human_time(eta, short=True):>6}'
+        sys.stdout.write(f'\r{prefix} [{bar}] {i}/{total} {tail}\033[K')
+        sys.stdout.flush()
+    print()
+
+
+@contextmanager
+def live(prefix: str = '', preset: str | None = None,
+         kind: str | None = None, speed: float | None = None,
+         color: str | None = None, keep: bool = True,
+         done: str = '✓', done_color: str = 'green'):
+    kind = kind if kind is not None else _SPINNER_DEFAULTS['kind']
+    speed = speed if speed is not None else _SPINNER_DEFAULTS['speed']
+    color = color if color is not None else _SPINNER_DEFAULTS['color']
+    if preset is None:
+        preset = _SPINNER_DEFAULTS['preset'] or _random_preset or pick_preset(kind)
+    frames = SPINNER_FRAMES.get(preset, SPINNER_FRAMES['dots_dense'])
+
+    stop = threading.Event()
+    state = {'text': prefix}
+    lock = threading.Lock()
+    frame_iter = itertools.cycle(frames)
+
+    def render():
+        with lock:
+            text = state['text']
+        try:
+            ch = next(frame_iter)
+        except StopIteration:
+            return
+        sys.stdout.write(f'\r{c(ch, color)} {text}\033[K')
+        sys.stdout.flush()
+
+    class _Ctx:
+        def set(self, text: str):
+            with lock:
+                state['text'] = text
+
+    th = threading.Thread(target=_frame_scheduler,
+                          args=(stop, speed, render), daemon=True)
+    th.start()
+    try:
+        yield _Ctx()
+    finally:
+        stop.set()
+        th.join()
+        with lock:
+            text = state['text']
+        clear = ' ' * (_visible_len(text) + 4)
+        sys.stdout.write(f'\r{clear}\r{c(done, done_color, bold=True)} {text}\n')
+        sys.stdout.flush()
+
+
+class _LiveTable:
+    def __init__(self, headers, style='rounded'):
+        self.headers = headers
+        self.style = style
+        self.rows = []
+        self._lock = threading.Lock()
+        self._lines = 0
+
+    def add(self, row):
+        with self._lock:
+            self.rows.append(list(row))
+
+    def clear(self):
+        with self._lock:
+            self.rows.clear()
+
+    def render(self):
+        with self._lock:
+            rows = list(self.rows)
+        data = [dict(zip(self.headers, r)) for r in rows] or \
+               [{h: '' for h in self.headers}]
+        if self._lines:
+            sys.stdout.write(f'\033[{self._lines}A')
+            for _ in range(self._lines):
+                sys.stdout.write('\033[K\n')
+            sys.stdout.write(f'\033[{self._lines}A')
+        buf = io.StringIO()
+        old = sys.stdout
+        sys.stdout = buf
+        try:
+            table(data, style=self.style, headers=self.headers, _return=False)
+        finally:
+            sys.stdout = old
+        out = buf.getvalue()
+        self._lines = out.count('\n')
+        sys.stdout.write(out)
+        sys.stdout.flush()
+
+
+@contextmanager
+def table_live(headers: list[str], style: str = 'rounded',
+               refresh: float = 0.3):
+    t = _LiveTable(headers, style)
+    stop = threading.Event()
+    next_tick = time.perf_counter()
+
+    def loop():
+        nonlocal next_tick
+        while not stop.is_set():
+            t.render()
+            next_tick += refresh
+            delta = next_tick - time.perf_counter()
+            if delta > 0:
+                time.sleep(delta)
+            else:
+                next_tick = time.perf_counter()
+
+    th = threading.Thread(target=loop, daemon=True)
+    th.start()
+    try:
+        yield t
+    finally:
+        stop.set()
+        th.join()
+        t.render()
+
+
+@contextmanager
+def status(text: str, color: str = 'cyan', interval: float = 0.15,
+           icon: str = '●'):
+    stop = threading.Event()
+    state = {'text': text}
+    sys.stdout.write('\n')
+    sys.stdout.flush()
+
+    def render():
+        line = c(f'{icon} {state["text"]}', color)
+        sys.stdout.write(f'\033[1A\r\033[K{line}\033[1B\r')
+        sys.stdout.flush()
+
+    th = threading.Thread(target=_frame_scheduler,
+                          args=(stop, interval, render), daemon=True)
+    th.start()
+    try:
+        yield
+    finally:
+        stop.set()
+        th.join()
+        sys.stdout.write('\033[1A\r\033[K')
+        sys.stdout.flush()
+
+
+# ============================================================
+# 13. БАРЫ И HUD
+# ============================================================
+
+def bar(value: float, max_value: float, width: int = 20,
+        color: str = 'green', empty_color: str = 'gray',
+        filled: str = '█', empty: str = '░') -> str:
+    if max_value <= 0:
+        return c(empty * width, empty_color)
+    ratio = max(0, min(1, value / max_value))
+    n = int(ratio * width)
+    return c(filled * n, color) + c(empty * (width - n), empty_color)
+
+
+def bar3(value: float, max_value: float, width: int = 20,
+         start: str = 'red', middle: str = 'yellow', end: str = 'green',
+         empty_color: str = 'gray',
+         filled: str = '█', empty: str = '░') -> str:
+    """3-цветный градиентный бар."""
+    if max_value <= 0:
+        return c(empty * width, empty_color)
+    ratio = max(0, min(1, value / max_value))
+    n_filled = int(ratio * width)
+    r1, g1, b1 = _any_to_rgb(start)
+    r2, g2, b2 = _any_to_rgb(middle)
+    r3, g3, b3 = _any_to_rgb(end)
+    parts = []
+    for i in range(width):
+        if i < n_filled:
+            t = i / max(width - 1, 1)
+            if t <= 0.5:
+                u = t * 2
+                r = int(r1 + (r2 - r1) * u)
+                g = int(g1 + (g2 - g1) * u)
+                b = int(b1 + (b2 - b1) * u)
+            else:
+                u = (t - 0.5) * 2
+                r = int(r2 + (r3 - r2) * u)
+                g = int(g2 + (g3 - g2) * u)
+                b = int(b2 + (b3 - b2) * u)
+            parts.append(f'\033[38;2;{r};{g};{b}m{filled}')
+        else:
+            parts.append(c(empty, empty_color))
+    return ''.join(parts) + _RESET
+
+
+def hp_bar(value: float, max_value: float, width: int = 20) -> str:
+    if max_value <= 0:
+        return c('░' * width, 'gray')
+    pct = value / max_value
+    if pct > 0.6:
+        col = 'green'
+    elif pct > 0.3:
+        col = 'yellow'
+    elif pct > 0.1:
+        col = 'bright_yellow'
+    else:
+        col = 'bright_red'
+    return bar(value, max_value, width, col)
+
+
+def mp_bar(value: float, max_value: float, width: int = 20) -> str:
+    return bar(value, max_value, width, 'bright_blue', 'gray')
+
+
+def xp_bar(value: float, max_value: float, width: int = 20) -> str:
+    return bar(value, max_value, width, 'bright_yellow', 'gray')
+
+
+def status_line(items: dict, sep: str = '   ',
+                colors: dict | None = None) -> None:
+    colors = colors or {}
+    parts = []
+    for k, v in items.items():
+        key_color = colors.get(k, 'cyan')
+        parts.append(f'{c(k, key_color)}: {c(v, "bright_white")}')
+    print(sep.join(parts))
+
+
+def hud(items: dict, width: int = 15, sep: str = '  ') -> None:
+    parts = []
+    for key, val in items.items():
+        if isinstance(val, (tuple, list)) and len(val) == 2:
+            v, m = val
+            if key.upper() == 'HP':
+                b = hp_bar(v, m, width)
+            elif key.upper() == 'MP':
+                b = mp_bar(v, m, width)
+            elif key.upper() == 'XP':
+                b = xp_bar(v, m, width)
+            else:
+                b = bar(v, m, width, 'cyan')
+            label = c(f'{key}', 'bright_cyan', bold=True)
+            val_text = c(f'{v}/{m}', 'gray')
+            parts.append(f'{label} [{b}] {val_text}')
+        else:
+            label = c(f'{key}', 'bright_cyan', bold=True)
+            parts.append(f'{label}: {c(val, "bright_white")}')
+    print(sep.join(parts))
+
+
+class _BarWave:
+    """Анимированный бар с бегущей волной."""
+    def __init__(self, total: int, prefix: str = '', width: int = 30,
+                 color: str = 'bright_cyan'):
+        self.total = total
+        self.prefix = prefix
+        self.width = width
+        self.color = color
+        self.start = time.time()
+        self._last = 0
+        self._phase = 0
+
+    def update(self, n: int, suffix: str = '') -> None:
+        pct = n / self.total
+        done = int(self.width * pct)
+        # Волна света проходит по заполненной части
+        wave_pos = self._phase % (done or 1)
+        parts = []
+        for i in range(self.width):
+            if i < done:
+                if abs(i - wave_pos) <= 2:
+                    parts.append(c('█', 'bright_white'))
+                else:
+                    parts.append(c('█', self.color))
+            else:
+                parts.append(c('░', 'gray'))
+        bar = ''.join(parts)
+        elapsed = time.time() - self.start
+        eta = (elapsed / n) * (self.total - n) if n else 0
+        line = f'{self.prefix} [{bar}] {n}/{self.total} {pct*100:5.1f}% ETA {human_time(eta, short=True):>6}'
+        if suffix:
+            line += f' {suffix}'
+        pad = max(0, self._last - _visible_len(line))
+        sys.stdout.write('\r' + line + ' ' * pad)
+        sys.stdout.flush()
+        self._last = _visible_len(line)
+        self._phase += 1
+
+    def close(self) -> None:
+        sys.stdout.write('\n')
+        sys.stdout.flush()
+
+
+def bar_wave(total: int, prefix: str = '', width: int = 30,
+             color: str = 'bright_cyan') -> _BarWave:
+    """Возвращает анимированный бар с бегущей волной.
+
+    Пример:
+        bar = bar_wave(100, prefix='Загрузка')
+        for i in range(1, 101):
+            bar.update(i); time.sleep(0.03)
+        bar.close()
+    """
+    return _BarWave(total, prefix, width, color)
+
+
+# ============================================================
+# 14. ДЕКОРАЦИИ
+# ============================================================
+
+def rule(char: str = '─', color: str = 'gray', width: int | None = None) -> None:
+    width = width or term_width() - 2
+    print(c(char * width, color))
+
+
+def double_rule(color: str = 'bright_cyan', width: int | None = None) -> None:
+    rule('═', color, width)
+
+
+def dashed_rule(color: str = 'gray', width: int | None = None) -> None:
+    rule('╌', color, width)
+
+
+def dots_rule(color: str = 'gray', width: int | None = None) -> None:
+    rule('·', color, width)
+
+
+def gradient_rule(width: int | None = None) -> None:
+    width = width or term_width() - 2
+    print(gradient('█' * width, 'red', 'blue'))
+
+
+def rainbow_rule(width: int | None = None) -> None:
+    width = width or term_width() - 2
+    colors = ['red', 'bright_red', 'yellow', 'bright_yellow',
+              'green', 'bright_green', 'cyan', 'bright_cyan',
+              'blue', 'bright_blue', 'magenta', 'bright_magenta']
+    chunk_size = max(1, width // len(colors))
+    print(''.join(c('█' * chunk_size, col) for col in colors))
+
+
+def wave_rule(color: str = 'bright_cyan', width: int | None = None) -> None:
+    width = width or term_width() - 2
+    print(c('〜' * (width // 2), color))
+
+
+def space(n: int = 1) -> None:
+    print('\n' * n, end='')
+
+
+def clear() -> None:
+    os.system('cls' if os.name == 'nt' else 'clear')
+
+
+# ============================================================
+# 15. ЗНАЧКИ
+# ============================================================
+
+def badge(text: str, color: str = 'bright_cyan', bg: str = 'black') -> str:
+    return c(f' {text} ', color, bg=bg, bold=True)
+
+
+def tag(text: str, color: str = 'cyan') -> str:
+    return c(f'[{text}]', color, bold=True)
+
+
+def sparkle_text(text: str, color: str = 'bright_yellow') -> str:
+    return f'{c("✨", color)} {c(text, "bright_white", bold=True)} {c("✨", color)}'
+
+
+def arrow_text(text: str, color: str = 'bright_cyan') -> str:
+    return f'{c("▶", color)} {text}'
+
+
+# ============================================================
+# 16. АНИМАЦИИ
+# ============================================================
+
+def animate(text: str, duration: float = 2.0,
+            frames: str | None = None,
+            color: str = 'bright_cyan',
+            speed: float = 0.08) -> None:
+    if frames is None:
+        frames = SPINNER_FRAMES['dots_dense']
+    end = time.time() + duration
+    next_tick = time.perf_counter()
+    for ch in itertools.cycle(frames):
+        if time.time() >= end:
+            break
+        sys.stdout.write(f'\r{c(ch, color)} {text}\033[K')
+        sys.stdout.flush()
+        next_tick += speed
+        while True:
+            delta = next_tick - time.perf_counter()
+            if delta <= 0:
+                next_tick = time.perf_counter()
+                break
+            if delta > 0.002:
+                time.sleep(delta - 0.001)
+    sys.stdout.write(f'\r\033[K{c("✓", "green", bold=True)} {text}\n')
+    sys.stdout.flush()
+
+
+def glow(text: str, colors: list[str] | None = None,
+         cycles: int = 3, speed: float = 0.05) -> None:
+    colors = colors or ['red', 'bright_red', 'yellow', 'bright_yellow',
+                        'green', 'bright_green', 'cyan', 'bright_cyan',
+                        'blue', 'bright_blue', 'magenta', 'bright_magenta']
+    n = len(colors)
+    for _ in range(cycles * n):
+        sys.stdout.write('\r')
+        for i, ch in enumerate(text):
+            col = colors[(i + _) % n]
+            sys.stdout.write(c(ch, col, bold=True))
+        sys.stdout.flush()
+        time.sleep(speed)
+    sys.stdout.write('\r')
+    sys.stdout.write(c(text, 'bright_yellow', bold=True))
+    sys.stdout.write('\n')
+    sys.stdout.flush()
+
+
+def glow_print(text: str, start: str = 'cyan', end: str = 'magenta',
+               duration: float = 1.5, speed: float = 0.04,
+               final: str | None = None, final_color: str | None = None,
+               newline: bool = True) -> None:
+    n = len(text)
+    if n == 0:
+        return
+    r1, g1, b1 = _any_to_rgb(start)
+    r2, g2, b2 = _any_to_rgb(end)
+    end_time = time.time() + duration
+    frame = 0
+    next_tick = time.perf_counter()
+    while time.time() < end_time:
+        phase = (frame % 48) / 48.0
+        sys.stdout.write('\r')
+        for i, ch in enumerate(text):
+            t = (i / max(n - 1, 1) + phase) % 1.0
+            t = t * 2 if t <= 0.5 else (1 - t) * 2
+            r = int(r1 + (r2 - r1) * t)
+            g = int(g1 + (g2 - g1) * t)
+            b = int(b1 + (b2 - b1) * t)
+            sys.stdout.write(f'\033[38;2;{r};{g};{b}m{ch}')
+        sys.stdout.write('\033[0m')
+        sys.stdout.flush()
+        frame += 1
+        next_tick += speed
+        while True:
+            delta = next_tick - time.perf_counter()
+            if delta <= 0:
+                next_tick = time.perf_counter()
+                break
+            if delta > 0.002:
+                time.sleep(delta - 0.001)
+    sys.stdout.write('\r\033[K')
+    if final is not None:
+        sys.stdout.write(c(f'✓ {final}', final_color or 'bright_green', bold=True))
+    else:
+        sys.stdout.write(c(text, end, bold=True))
+    if newline:
+        sys.stdout.write('\n')
+    sys.stdout.flush()
+
+
+def glow_print3(text: str, start: str = 'cyan', middle: str = 'magenta',
+                end: str = 'yellow', duration: float = 1.5,
+                speed: float = 0.04, final: str | None = None,
+                final_color: str | None = None,
+                newline: bool = True) -> None:
+    n = len(text)
+    if n == 0:
+        return
+    r1, g1, b1 = _any_to_rgb(start)
+    r2, g2, b2 = _any_to_rgb(middle)
+    r3, g3, b3 = _any_to_rgb(end)
+    end_time = time.time() + duration
+    frame = 0
+    next_tick = time.perf_counter()
+    while time.time() < end_time:
+        phase = (frame % 48) / 48.0
+        sys.stdout.write('\r')
+        for i, ch in enumerate(text):
+            t = (i / max(n - 1, 1) + phase) % 1.0
+            t = t * 2 if t <= 0.5 else (1 - t) * 2
+            if t <= 0.5:
+                u = t * 2
+                r = int(r1 + (r2 - r1) * u)
+                g = int(g1 + (g2 - g1) * u)
+                b = int(b1 + (b2 - b1) * u)
+            else:
+                u = (t - 0.5) * 2
+                r = int(r2 + (r3 - r2) * u)
+                g = int(g2 + (g3 - g2) * u)
+                b = int(b2 + (b3 - b2) * u)
+            sys.stdout.write(f'\033[38;2;{r};{g};{b}m{ch}')
+        sys.stdout.write('\033[0m')
+        sys.stdout.flush()
+        frame += 1
+        next_tick += speed
+        while True:
+            delta = next_tick - time.perf_counter()
+            if delta <= 0:
+                next_tick = time.perf_counter()
+                break
+            if delta > 0.002:
+                time.sleep(delta - 0.001)
+    sys.stdout.write('\r\033[K')
+    if final is not None:
+        sys.stdout.write(c(f'✓ {final}', final_color or 'bright_green', bold=True))
+    else:
+        sys.stdout.write(gradient3(text, start, middle, end))
+    if newline:
+        sys.stdout.write('\n')
+    sys.stdout.flush()
+
+
+def typewriter(text: str, delay: float = 0.03,
+               color: str = 'bright_white') -> None:
+    for ch in text:
+        sys.stdout.write(c(ch, color))
+        sys.stdout.flush()
+        time.sleep(delay)
+    print()
+
+
+def wave_text(text: str, delay: float = 0.02) -> None:
+    for ch in text:
+        sys.stdout.write(c(ch, 'bright_cyan'))
+        sys.stdout.flush()
+        time.sleep(delay)
+    print()
+
+
+def divider_animated(duration: float = 0.5,
+                     color: str = 'bright_cyan',
+                     char: str = '─') -> None:
+    width = term_width() - 2
+    for _ in range(width):
+        sys.stdout.write(c(char, color))
+        sys.stdout.flush()
+        time.sleep(duration / width)
+    print()
+
+
+def line_reveal(text: str, color: str = 'bright_white',
+                delay: float = 0.02) -> None:
+    for ch in text:
+        sys.stdout.write(c(ch, color))
+        sys.stdout.flush()
+        time.sleep(delay)
+    print()
+
+
+def fade_in(text: str, color: str = 'bright_white') -> None:
+    parts = 4
+    step = max(1, len(text) // parts)
+    for i in range(0, len(text), step):
+        sys.stdout.write(c(text[i:i + step], color))
+        sys.stdout.flush()
+        time.sleep(0.08)
+    print()
+
+
+def flip_banner(text: str, color: str = 'bright_magenta') -> None:
+    frames = ['─', '═', '━', '▬']
+    for fr in frames:
+        sys.stdout.write('\r')
+        sys.stdout.write(c(fr * (len(text) + 4), color))
+        sys.stdout.flush()
+        time.sleep(0.1)
+    print()
+    center(f'{c("★", "bright_yellow")} {c(text, color, bold=True)} '
+           f'{c("★", "bright_yellow")}')
+    for fr in reversed(frames):
+        sys.stdout.write('\r')
+        sys.stdout.write(c(fr * (len(text) + 4), color))
+        sys.stdout.flush()
+        time.sleep(0.1)
+    print()
+
+
+def hearts_rain(count: int = 10, delay: float = 0.05) -> None:
+    for _ in range(count):
+        sys.stdout.write(c(random.choice('❤♥♡'),
+                           random.choice(['red', 'bright_red',
+                                          'magenta', 'bright_magenta'])))
+        sys.stdout.flush()
+        time.sleep(delay)
+    print()
+
+
+def stars_rain(count: int = 15, delay: float = 0.05) -> None:
+    for _ in range(count):
+        sys.stdout.write(c(random.choice('★☆✦✧✩✪✫'), 'bright_yellow'))
+        sys.stdout.flush()
+        time.sleep(delay)
+    print()
+
+
+def fireworks(times: int = 3) -> None:
+    for _ in range(times):
+        spark = random.choice(['✨', '💥', '🎆', '🎇', '⭐'])
+        color = random.choice(['red', 'yellow', 'green', 'cyan',
+                               'magenta', 'bright_red'])
+        sys.stdout.write(c(spark, color, bold=True))
+        sys.stdout.flush()
+        time.sleep(0.15)
+    print()
+    _sound('hit')
+
+
+def rain(chars: str = '★☆✦✧✩✪✫', count: int = 20,
+         duration: float = 2.0, color: str = 'bright_yellow',
+         speed: float = 0.06, height: int = 8) -> None:
+    width = min(term_width() - 1, 70)
+    if width < 5 or count < 1 or height < 1:
+        return
+    end_time = time.time() + duration
+    next_tick = time.perf_counter()
+    drops = [{'x': random.randint(0, width - 1),
+              'y': random.uniform(0, height),
+              'ch': random.choice(chars),
+              'speed': random.uniform(0.6, 1.4)} for _ in range(count)]
+    sys.stdout.write('\n' * height)
+    sys.stdout.write(f'\033[{height}A')
+    sys.stdout.flush()
+    try:
+        while time.time() < end_time:
+            for d in drops:
+                y_int = int(d['y'])
+                if 0 <= y_int < height:
+                    sys.stdout.write(f'\033[{height}A')
+                    if y_int > 0:
+                        sys.stdout.write(f'\033[{y_int}B')
+                    sys.stdout.write('\r')
+                    if d['x'] > 0:
+                        sys.stdout.write(f'\033[{d["x"]}C')
+                    sys.stdout.write(c(d['ch'], color, bold=True))
+                    sys.stdout.write('\r')
+                    sys.stdout.write(f'\033[{height}A')
+                    if y_int > 0:
+                        sys.stdout.write(f'\033[{y_int}B')
+                d['y'] += d['speed']
+                if d['y'] >= height:
+                    d['x'] = random.randint(0, width - 1)
+                    d['y'] = 0
+                    d['ch'] = random.choice(chars)
+                    d['speed'] = random.uniform(0.6, 1.4)
+            sys.stdout.write(f'\033[{height}A')
+            sys.stdout.write(f'\033[{height}B')
+            sys.stdout.flush()
+            next_tick += speed
+            while True:
+                delta = next_tick - time.perf_counter()
+                if delta <= 0:
+                    next_tick = time.perf_counter()
+                    break
+                if delta > 0.002:
+                    time.sleep(delta - 0.001)
+    finally:
+        sys.stdout.write(f'\033[{height}A')
+        for _ in range(height):
+            sys.stdout.write('\033[K\n')
+        sys.stdout.write(f'\033[{height}A')
+        sys.stdout.flush()
+
+
+def rain_line(chars: str = '★☆✦✧✩✪✫', width: int = 40,
+              cycles: int = 3, color: str = 'bright_yellow',
+              speed: float = 0.04, tail: int = 4) -> None:
+    if width < 5 or cycles < 1:
+        return
+    for _ in range(cycles):
+        for pos in range(width + tail):
+            sys.stdout.write('\r')
+            for x in range(width):
+                if x == pos:
+                    sys.stdout.write(c(random.choice(chars),
+                                       'bright_white', bold=True))
+                elif 0 < pos - x <= tail:
+                    shade = tail - (pos - x)
+                    col = color if shade > tail // 2 else 'gray'
+                    sys.stdout.write(c(random.choice(chars), col))
+                else:
+                    sys.stdout.write(' ')
+            sys.stdout.write('\033[K')
+            sys.stdout.flush()
+            time.sleep(speed)
+    sys.stdout.write('\r' + ' ' * width + '\r')
+    sys.stdout.flush()
+
+
+def rain_multi(chars: str = '★☆✦✧✩✪✫', cols: int = 8,
+               height: int = 5, duration: float = 2.0,
+               color: str = 'bright_yellow', speed: float = 0.1) -> None:
+    if cols < 1 or height < 1:
+        return
+    col_width = max(2, term_width() // (cols + 1))
+    grid = [[random.choice(chars) for _ in range(cols)]
+            for _ in range(height)]
+    for _ in range(height):
+        sys.stdout.write(' ' * (col_width * cols) + '\n')
+    sys.stdout.write(f'\033[{height}A')
+    end_time = time.time() + duration
+    next_tick = time.perf_counter()
+    try:
+        while time.time() < end_time:
+            for r in range(height):
+                sys.stdout.write('\r')
+                for c_idx in range(cols):
+                    sys.stdout.write(c(grid[r][c_idx], color) +
+                                     ' ' * (col_width - 1))
+                sys.stdout.write('\033[K\n')
+            sys.stdout.write(f'\033[{height}A')
+            sys.stdout.flush()
+            new_row = [random.choice(chars) for _ in range(cols)]
+            grid = [new_row] + grid[:-1]
+            next_tick += speed
+            while True:
+                delta = next_tick - time.perf_counter()
+                if delta <= 0:
+                    next_tick = time.perf_counter()
+                    break
+                if delta > 0.002:
+                    time.sleep(delta - 0.001)
+    finally:
+        for _ in range(height):
+            sys.stdout.write('\033[1A\r\033[K')
+        sys.stdout.write('\r\033[K')
+        sys.stdout.flush()
+
+
+def line_effect(text: str, effect: str = 'type') -> None:
+    if effect == 'type':
+        typewriter(text)
+    elif effect == 'fade':
+        fade_in(text)
+    elif effect == 'glow':
+        glow(text)
+    elif effect == 'reveal':
+        line_reveal(text)
+    else:
+        print(text)
+
+
+# ============================================================
+# 17. ИНТЕРАКТИВ
+# ============================================================
+
+def ask(prompt_text: str, default: str = '') -> str:
+    return input(f'{prompt_text} [{default}]: ').strip() or default
+
+
+def confirm(prompt_text: str, default: bool = False) -> bool:
+    suffix = 'Y/n' if default else 'y/N'
+    ans = input(f'{prompt_text} [{suffix}]: ').strip().lower()
+    if not ans:
+        return default
+    return ans in ('y', 'yes', 'д', 'да')
+
+
+def menu(items: list[str], prompt_text: str = 'Выбор', title: str = ''):
+    if title:
+        print(c(f'\n{title}', 'cyan', bold=True))
+    for i, item in enumerate(items, 1):
+        print(f'  {c(i, "cyan")}. {item}')
+    try:
+        ans = input(f'{prompt_text}: ').strip()
+        if not ans:
+            return None
+        idx = int(ans)
+        if 1 <= idx <= len(items):
+            return idx - 1
+    except (ValueError, EOFError):
+        pass
+    return None
+
+
+def prompt(label: str, default: str = '', arrow: str = '❯',
+           color: str = 'green') -> str:
+    hint = f' [{default}]' if default else ''
+    text = input(f'{c(arrow, color, bold=True)} {label}{c(hint, "gray")}: ')
+    return text.strip() or default
+
+
+def password(prompt_text: str = 'Пароль', icon: str = '🔒',
+             color: str = 'yellow') -> str:
+    import getpass
+    return getpass.getpass(f'{c(icon, color)} {prompt_text}: ')
+
+
+def copyable(text: str, label: str = '', clipboard: bool = False) -> None:
+    if label:
+        print(f'{c(label, "gray")}: {c(text, "cyan", bold=True)}')
+    else:
+        print(c(text, 'cyan', bold=True))
+    if clipboard:
+        try:
+            import pyperclip
+            pyperclip.copy(text)
+            ok('скопировано в буфер')
+        except ImportError:
+            info('для копирования: pip install pyperclip')
+
+
+def wait_key(prompt_text: str = 'Нажми любую клавишу...') -> str:
+    print(c(prompt_text, 'gray'), end=' ', flush=True)
+    if os.name == 'nt' and _HAS_MSVCRT:
+        ch = msvcrt.getch().decode('utf-8', errors='ignore')
+        print()
+        return ch
+    elif _HAS_TERMIOS:
+        fd = sys.stdin.fileno()
+        old = termios.tcgetattr(fd)
+        try:
+            tty.setraw(fd)
+            ch = sys.stdin.read(1)
+        finally:
+            termios.tcsetattr(fd, termios.TCSADRAIN, old)
+        print()
+        return ch
+    else:
+        return input()
+
+
+def prompt_choice(prompt_text: str, choices: list,
+                  default: Any = None) -> Any:
+    for i, item in enumerate(choices, 1):
+        print(f'  {c(i, "cyan")}. {item}')
+    while True:
+        ans = input(f'{c("❯", "green", bold=True)} {prompt_text}: ').strip()
+        if not ans and default is not None:
+            return default
+        try:
+            idx = int(ans) - 1
+            if 0 <= idx < len(choices):
+                return choices[idx]
+        except ValueError:
+            pass
+        warn(f'Введи число от 1 до {len(choices)}')
+
+
+def confirm_or_exit(prompt_text: str, code: int = 0) -> None:
+    if not confirm(prompt_text, default=False):
+        warn('Отменено пользователем')
+        sys.exit(code)
+
+
+# ============================================================
+# 18. SPINNER_SELECTION — меню со стрелками
+# ============================================================
+
+def spinner_selection(prompt_text: str = 'Выбор',
+                      items: list[str] | None = None,
+                      default: int = 0,
+                      color: str = 'bright_cyan') -> int | None:
+    """Меню выбора стрелками ↑↓ + Enter.
+
+    Пример:
+        idx = spinner_selection('Что делаем?', ['Создать', 'Открыть', 'Выход'])
+    """
+    if not items:
+        items = ['Да', 'Нет']
+    if not (os.name == 'nt' and _HAS_MSVCRT) and not _HAS_TERMIOS:
+        # Fallback: обычный menu
+        return menu(items, prompt_text)
+
+    current = default
+    n = len(items)
+
+    def render():
+        for i, item in enumerate(items):
+            marker = '❯' if i == current else ' '
+            line = f' {c(marker, "green", bold=True)} '
+            if i == current:
+                line += c(item, color, bold=True, bg='black')
+            else:
+                line += c(item, 'gray')
+            sys.stdout.write('\033[K' + line + '\n')
+        sys.stdout.write(f'\033[{n}A')
+
+    print(c(prompt_text, 'bright_white', bold=True))
+    for _ in range(n):
+        sys.stdout.write('\n')
+    sys.stdout.write(f'\033[{n}A')
+    sys.stdout.flush()
+    render()
+
+    try:
+        while True:
+            key = _read_key()
+            if key in ('up', 'k'):
+                current = (current - 1) % n
+                _sound('tick')
+            elif key in ('down', 'j'):
+                current = (current + 1) % n
+                _sound('tick')
+            elif key == 'enter':
+                _sound('click')
+                sys.stdout.write(f'\033[{n}B')
+                sys.stdout.flush()
+                return current
+            elif key == 'esc':
+                sys.stdout.write(f'\033[{n}B')
+                sys.stdout.flush()
+                return None
+            render()
+    except KeyboardInterrupt:
+        sys.stdout.write(f'\033[{n}B')
+        sys.stdout.flush()
+        return None
+
+
+def _read_key() -> str:
+    """Читает одну клавишу. Возвращает 'up', 'down', 'enter', 'esc', или сам символ."""
+    if os.name == 'nt' and _HAS_MSVCRT:
+        ch = msvcrt.getch()
+        if ch in (b'\x00', b'\xe0'):
+            ch2 = msvcrt.getch()
+            if ch2 == b'H':
+                return 'up'
+            if ch2 == b'P':
+                return 'down'
+            return 'other'
+        if ch == b'\r':
+            return 'enter'
+        if ch == b'\x1b':
+            return 'esc'
+        try:
+            return ch.decode('utf-8', errors='ignore').lower()
+        except Exception:
+            return ''
+    elif _HAS_TERMIOS:
+        fd = sys.stdin.fileno()
+        old = termios.tcgetattr(fd)
+        try:
+            tty.setraw(fd)
+            ch = sys.stdin.read(1)
+            if ch == '\x1b':
+                ch2 = sys.stdin.read(1)
+                if ch2 == '[':
+                    ch3 = sys.stdin.read(1)
+                    if ch3 == 'A':
+                        return 'up'
+                    if ch3 == 'B':
+                        return 'down'
+                return 'esc'
+            if ch == '\r' or ch == '\n':
+                return 'enter'
+            return ch.lower()
+        finally:
+            termios.tcsetattr(fd, termios.TCSADRAIN, old)
+    return ''
+
+
+# ============================================================
+# 19. ASK — цепочка вопросов
+# ============================================================
+
+class Ask:
+    """Цепочка вопросов. Fluent API.
+
+    Пример:
+        answers = (Ask()
+            .text('Имя', default='Аня')
+            .choice('Класс', ['Воин', 'Маг', 'Вор'])
+            .confirm('Начать?', default=True)
+            .number('Возраст', min=1, max=120)
+            .run())
+    """
+    def __init__(self):
+        self._steps: list[tuple] = []
+
+    def text(self, label: str, default: str = '') -> 'Ask':
+        self._steps.append(('text', label, default))
+        return self
+
+    def choice(self, label: str, options: list, default: int = 0) -> 'Ask':
+        self._steps.append(('choice', label, options, default))
+        return self
+
+    def confirm(self, label: str, default: bool = False) -> 'Ask':
+        self._steps.append(('confirm', label, default))
+        return self
+
+    def number(self, label: str, default: int = 0,
+               min: int | None = None, max: int | None = None) -> 'Ask':
+        self._steps.append(('number', label, default, min, max))
+        return self
+
+    def password(self, label: str = 'Пароль') -> 'Ask':
+        self._steps.append(('password', label))
+        return self
+
+    def run(self) -> dict:
+        result = {}
+        for step in self._steps:
+            kind = step[0]
+            label = step[1]
+            if kind == 'text':
+                result[label] = ask(label, step[2])
+            elif kind == 'choice':
+                options, default = step[2], step[3]
+                result[label] = prompt_choice(label, options, options[default])
+            elif kind == 'confirm':
+                result[label] = confirm(label, step[2])
+            elif kind == 'number':
+                default, lo, hi = step[2], step[3], step[4]
+                while True:
+                    raw = ask(label, str(default))
+                    try:
+                        val = int(raw)
+                        if lo is not None and val < lo:
+                            warn(f'Минимум {lo}')
+                            continue
+                        if hi is not None and val > hi:
+                            warn(f'Максимум {hi}')
+                            continue
+                        result[label] = val
+                        break
+                    except ValueError:
+                        warn('Введи число')
+            elif kind == 'password':
+                result[label] = password(label)
+        return result
+
+
+# ============================================================
+# 20. WIZARD — пошаговый мастер
+# ============================================================
+
+def wizard(steps: list[tuple], title: str = 'Мастер настройки') -> dict:
+    """Пошаговый мастер настройки.
+
+    steps — список (label, kind, options_dict):
+        kind = 'text' | 'choice' | 'confirm' | 'number'
+
+    Пример:
+        wizard([
+            ('Имя', 'text', {'default': 'Аня'}),
+            ('Email', 'text', {}),
+            ('Возраст', 'number', {'min': 18}),
+            ('Подписка', 'confirm', {'default': True}),
+        ])
+    """
+    result = {}
+    total = len(steps)
+    for i, (label, kind, opts) in enumerate(steps, 1):
+        section(f'[{i}/{total}] {label}')
+        opts = opts or {}
+        if kind == 'text':
+            result[label] = ask(label, opts.get('default', ''))
+        elif kind == 'choice':
+            options = opts.get('options', [])
+            result[label] = prompt_choice(label, options)
+        elif kind == 'confirm':
+            result[label] = confirm(label, opts.get('default', False))
+        elif kind == 'number':
+            while True:
+                raw = ask(label, str(opts.get('default', 0)))
+                try:
+                    val = int(raw)
+                    if 'min' in opts and val < opts['min']:
+                        warn(f'Минимум {opts["min"]}'); continue
+                    if 'max' in opts and val > opts['max']:
+                        warn(f'Максимум {opts["max"]}'); continue
+                    result[label] = val
+                    break
+                except ValueError:
+                    warn('Введи число')
+        space()
+    ok(f'{title}: завершено')
+    return result
+
+
+# ============================================================
+# 21. ПРОДВИНУТОЕ: Keyboard, Stream, Dashboard, Parser
+# ============================================================
+
+class Keyboard:
+    """Глобальный обработчик клавиш (в отдельном потоке).
+
+    Пример:
+        kb = Keyboard()
+        kb.on('q', lambda: exit_game())
+        kb.start()
+        ...
+        kb.stop()
+    """
+    def __init__(self):
+        self._handlers: dict[str, Callable] = {}
+        self._stop = threading.Event()
+        self._thread: threading.Thread | None = None
+
+    def on(self, key: str, handler: Callable) -> 'Keyboard':
+        self._handlers[key] = handler
+        return self
+
+    def start(self) -> None:
+        if self._thread and self._thread.is_alive():
+            return
+        self._stop.clear()
+        self._thread = threading.Thread(target=self._loop, daemon=True)
+        self._thread.start()
+
+    def stop(self) -> None:
+        self._stop.set()
+        if self._thread:
+            self._thread.join(timeout=1)
+
+    def _loop(self) -> None:
+        while not self._stop.is_set():
+            key = _read_key()
+            if not key:
+                time.sleep(0.02)
+                continue
+            handler = self._handlers.get(key)
+            if handler:
+                try:
+                    handler()
+                except Exception:
+                    pass
+
+
+class Stream:
+    """Обработка потока с обновляемой строкой статуса.
+
+    Пример:
+        with Stream('Чтение логов') as s:
+            for line in open('app.log'):
+                s.update(line.rstrip())
+                if 'ERROR' in line:
+                    s.warn(line.rstrip())
+    """
+    def __init__(self, label: str = 'Обработка'):
+        self.label = label
+        self._lock = threading.Lock()
+        self._current = ''
+        self._stop = threading.Event()
+        self._thread: threading.Thread | None = None
+        self._count = 0
+
+    def __enter__(self):
+        self._thread = threading.Thread(target=self._loop, daemon=True)
+        self._thread.start()
+        return self
+
+    def __exit__(self, *args):
+        self._stop.set()
+        if self._thread:
+            self._thread.join(timeout=0.5)
+        sys.stdout.write('\r\033[K')
+        sys.stdout.flush()
+
+    def _loop(self):
+        frames = '⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏'
+        frame_iter = itertools.cycle(frames)
+        while not self._stop.is_set():
+            with self._lock:
+                cur = self._current
+            ch = next(frame_iter)
+            line = f'{c(ch, "bright_cyan")} {self.label}: {cur}  [{self._count}]'
+            sys.stdout.write(f'\r{line}\033[K')
+            sys.stdout.flush()
+            time.sleep(0.08)
+
+    def update(self, text: str):
+        with self._lock:
+            self._current = text
+        self._count += 1
+
+    def warn(self, text: str):
+        sys.stdout.write('\r\033[K')
+        warn(text)
+        self._count += 1
+
+
+class Dashboard:
+    """Многопанельный мониторинг.
+
+    Пример:
+        with Dashboard(refresh=0.5) as db:
+            db.panel('CPU', lambda: chart([random.random() for _ in range(20)]))
+            db.panel('RAM', lambda: chart([random.random() for _ in range(20)]))
+            time.sleep(5)
+    """
+    def __init__(self, refresh: float = 0.5):
+        self.refresh = refresh
+        self.panels: list[tuple[str, Callable]] = []
+        self._stop = threading.Event()
+        self._thread: threading.Thread | None = None
+        self._lines = 0
+
+    def panel(self, name: str, fn: Callable) -> 'Dashboard':
+        self.panels.append((name, fn))
+        return self
+
+    def __enter__(self):
+        self._thread = threading.Thread(target=self._loop, daemon=True)
+        self._thread.start()
+        return self
+
+    def __exit__(self, *args):
+        self._stop.set()
+        if self._thread:
+            self._thread.join(timeout=0.5)
+        print()
+
+    def _loop(self):
+        next_tick = time.perf_counter()
+        while not self._stop.is_set():
+            self._render()
+            next_tick += self.refresh
+            delta = next_tick - time.perf_counter()
+            if delta > 0:
+                time.sleep(delta)
+            else:
+                next_tick = time.perf_counter()
+
+    def _render(self):
+        if self._lines:
+            sys.stdout.write(f'\033[{self._lines}A')
+            for _ in range(self._lines):
+                sys.stdout.write('\033[K\n')
+            sys.stdout.write(f'\033[{self._lines}A')
+
+        out_lines = 0
+        for name, fn in self.panels:
+            sys.stdout.write(c(f'▶ {name}', 'bright_cyan', bold=True) + '\n')
+            out_lines += 1
+            buf = io.StringIO()
+            old = sys.stdout
+            sys.stdout = buf
+            try:
+                fn()
+            finally:
+                sys.stdout = old
+            content = buf.getvalue()
+            for line in content.splitlines():
+                sys.stdout.write(line + '\033[K\n')
+                out_lines += 1
+            sys.stdout.write('\033[K\n')
+            out_lines += 1
+        self._lines = out_lines
+        sys.stdout.flush()
+
+
+class Parser:
+    """Простой парсер CLI-аргументов.
+
+    Пример:
+        cli = Parser('mytool')
+        cli.flag('--verbose', '-v', help='Подробный вывод')
+        cli.option('--output', '-o', default='out.txt')
+        cli.command('build', handler=lambda a: print('build'))
+        cli.command('run', handler=lambda a: print('run'))
+        args = cli.parse()
+    """
+    def __init__(self, name: str = 'app'):
+        self.name = name
+        self.flags: list[tuple] = []
+        self.options: list[tuple] = []
+        self.commands: dict[str, Callable] = {}
+
+    def flag(self, *names: str, help: str = '') -> 'Parser':
+        self.flags.append((names, help))
+        return self
+
+    def option(self, *names: str, default=None, help: str = '') -> 'Parser':
+        self.options.append((names, default, help))
+        return self
+
+    def command(self, name: str, handler: Callable) -> 'Parser':
+        self.commands[name] = handler
+        return self
+
+    def parse(self, argv: list[str] | None = None) -> dict:
+        argv = list(argv if argv is not None else sys.argv[1:])
+        result: dict = {'flags': set(), 'options': {}, 'positional': [],
+                        'command': None}
+
+        i = 0
+        while i < len(argv):
+            arg = argv[i]
+            matched = False
+            for names, _ in self.flags:
+                if arg in names:
+                    result['flags'].add(names[0].lstrip('-'))
+                    matched = True
+                    break
+            if matched:
+                i += 1
+                continue
+            for names, default, _ in self.options:
+                if arg in names:
+                    key = names[0].lstrip('-')
+                    if i + 1 < len(argv):
+                        result['options'][key] = argv[i + 1]
+                        i += 2
+                    else:
+                        result['options'][key] = True
+                        i += 1
+                    matched = True
+                    break
+                if '=' in arg and arg.split('=')[0] in names:
+                    key = names[0].lstrip('-')
+                    result['options'][key] = arg.split('=', 1)[1]
+                    matched = True
+                    i += 1
+                    break
+            if matched:
+                continue
+            if arg in self.commands:
+                result['command'] = arg
+                if arg in self.commands:
+                    self.commands[arg](result)
+                i += 1
+            else:
+                result['positional'].append(arg)
+                i += 1
+        return result
+
+
+# ============================================================
+# 22. ЛОГГЕР
+# ============================================================
+
+class Log:
+    """Логгер с ротацией."""
+    _LEVELS = {'DEBUG': 10, 'INFO': 20, 'WARN': 30, 'ERROR': 40}
+
+    def __init__(self, name='app', log_dir='logs', console=True,
+                 level='INFO', colorize=True,
+                 max_size: str | int | None = None,
+                 backups: int = 5):
+        self.name, self.console = name, console
+        self.level = level.upper()
+        self.colorize = colorize
+        self.dir = Path(log_dir)
+        self.dir.mkdir(parents=True, exist_ok=True)
+        self.max_size = self._parse_size(max_size) if max_size else None
+        self.backups = backups
+
+    @staticmethod
+    def _parse_size(size) -> int:
+        if isinstance(size, int):
+            return size
+        s = str(size).strip().upper()
+        for unit, mult in [('GB', 1024**3), ('MB', 1024**2),
+                           ('KB', 1024), ('B', 1)]:
+            if s.endswith(unit):
+                return int(float(s[:-len(unit)]) * mult)
+        return int(s)
+
+    def _file(self) -> Path:
+        return self.dir / f'{self.name}_{datetime.now():%Y-%m-%d}.log'
+
+    def _rotate_if_needed(self) -> None:
+        if not self.max_size:
+            return
+        f = self._file()
+        if not f.exists() or f.stat().st_size < self.max_size:
+            return
+        # Сдвигаем backup'ы
+        for i in range(self.backups - 1, 0, -1):
+            old = f.with_suffix(f'.{i}.log')
+            new = f.with_suffix(f'.{i + 1}.log')
+            if old.exists():
+                if new.exists():
+                    new.unlink()
+                old.rename(new)
+        first = f.with_suffix('.1.log')
+        if first.exists():
+            first.unlink()
+        f.rename(first)
+
+    def _write(self, level: str, msg: Any) -> None:
+        if self._LEVELS[level] < self._LEVELS.get(self.level, 20):
+            return
+        self._rotate_if_needed()
+        ts = datetime.now().strftime('%Y-%m-%d %H:%M:%S')
+        line = f'{ts} [{level:<5}] {msg}'
+        with open(self._file(), 'a', encoding='utf-8') as f:
+            f.write(line + '\n')
+        if self.console:
+            if self.colorize:
+                colors = {'DEBUG': 'gray', 'INFO': 'cyan',
+                          'WARN': 'yellow', 'ERROR': 'red'}
+                print(c(line, colors.get(level, 'white')))
+            else:
+                print(line)
+
+    def debug(self, msg): self._write('DEBUG', msg)
+    def info(self, msg):  self._write('INFO', msg)
+    def warn(self, msg):  self._write('WARN', msg)
+    def error(self, msg): self._write('ERROR', msg)
+
+
+# ============================================================
+# 23. ФОРМАТЫ
+# ============================================================
+
+def human_size(n: float) -> str:
+    n = float(n)
+    for unit in ('B', 'KB', 'MB', 'GB', 'TB'):
+        if abs(n) < 1024:
+            return f'{n:.1f} {unit}'
+        n /= 1024
+    return f'{n:.1f} PB'
+
+
+_PLURALS_RU = {
+    'day': ('день', 'дня', 'дней'), 'hour': ('час', 'часа', 'часов'),
+    'minute': ('минута', 'минуты', 'минут'),
+    'second': ('секунда', 'секунды', 'секунд'), 'ms': ('мс', 'мс', 'мс'),
+}
+_PLURALS_EN = {
+    'day': ('day', 'days'), 'hour': ('hour', 'hours'),
+    'minute': ('minute', 'minutes'), 'second': ('second', 'seconds'),
+    'ms': ('ms', 'ms'),
+}
+_UNITS_SHORT = {
+    'ru': {'day': 'д', 'hour': 'ч', 'minute': 'м', 'second': 'с', 'ms': 'мс'},
+    'en': {'day': 'd', 'hour': 'h', 'minute': 'm', 'second': 's', 'ms': 'ms'},
+}
+
+
+def _plural(n: int, forms: tuple, lang: str) -> str:
+    if lang == 'en':
+        return forms[1] if n != 1 else forms[0]
+    n = abs(n) % 100
+    if 11 <= n <= 19:
+        return forms[2]
+    n %= 10
+    if n == 1: return forms[0]
+    if 2 <= n <= 4: return forms[1]
+    return forms[2]
+
+
+def plural(n: int, one: str, few: str, many: str) -> str:
+    return _plural(n, (one, few, many), 'ru')
+
+
+def human_time(seconds: float, *, lang: str = 'ru',
+               short: bool = False, parts: int | None = None) -> str:
+    neg = seconds < 0
+    seconds = abs(float(seconds))
+    if seconds < 1:
+        ms = int(round(seconds * 1000))
+        if short:
+            text = f'{ms}{_UNITS_SHORT[lang]["ms"]}'
+        else:
+            word = _plural(ms, (_PLURALS_RU if lang == 'ru' else _PLURALS_EN)['ms'], lang)
+            text = f'{ms} {word}'
+        return f'{text} назад' if neg else text
+    total = int(seconds)
+    days, total = divmod(total, 86400)
+    hours, total = divmod(total, 3600)
+    minutes, secs = divmod(total, 60)
+    units = [('day', days), ('hour', hours), ('minute', minutes), ('second', secs)]
+    result = []
+    for name, val in units:
+        if val == 0 and not result and name != 'second':
+            continue
+        if val or (name == 'second' and not result):
+            if short:
+                result.append(f'{val}{_UNITS_SHORT[lang][name]}')
+            else:
+                word = _plural(val, (_PLURALS_RU if lang == 'ru' else _PLURALS_EN)[name], lang)
+                result.append(f'{val} {word}')
+        if parts and len(result) >= parts:
+            break
+    if not result:
+        result = [f'0{_UNITS_SHORT[lang]["second"]}'] if short else \
+                 [f'0 {_plural(0, (_PLURALS_RU if lang == "ru" else _PLURALS_EN)["second"], lang)}']
+    text = ' '.join(result)
+    return f'{text} назад' if neg else text
+
+
+def human_delta(a: datetime, b: datetime, **kw) -> str:
+    return human_time((b - a).total_seconds(), **kw)
+
+
+def human_eta(elapsed: float, done: int, total: int, **kw) -> str:
+    if done == 0:
+        return '...'
+    speed = done / elapsed
+    return '~' + human_time((total - done) / speed if speed else 0, parts=2, **kw)
+
+
+def human_ago(dt: datetime | str) -> str:
+    if isinstance(dt, str):
+        dt = datetime.fromisoformat(dt)
+    s = int((datetime.now() - dt).total_seconds())
+    if s < 60:     return 'только что'
+    if s < 3600:   return f'{s // 60} мин назад'
+    if s < 86400:  return f'{s // 3600} ч назад'
+    if s < 604800: return f'{s // 86400} дн назад'
+    return dt.strftime('%d.%m.%Y')
+
+
+def money(n: float, currency: str = '₽') -> str:
+    return f'{n:,.0f} {currency}'.replace(',', ' ')
+
+
+# ============================================================
+# 24. ТАЙМЕР / РЕТРАИ
+# ============================================================
+
+@contextmanager
+def timer(label: str = '', show: bool = True):
+    start = time.perf_counter()
+    box_ = {'elapsed': 0.0}
+    try:
+        yield box_
+    finally:
+        box_['elapsed'] = time.perf_counter() - start
+        if show:
+            info(f'{label}: {box_["elapsed"]:.3f}s')
+
+
+def retry(times: int = 3, delay: float = 1.0, backoff: float = 2.0,
+          exceptions: tuple = (Exception,),
+          on_retry: Callable[[int, Exception], None] | None = None,
+          raise_last: bool = True, default: Any = None):
+    def deco(func):
+        @functools.wraps(func)
+        def wrapper(*args, **kw):
+            wait_ = delay
+            last = None
+            for attempt in range(1, times + 1):
+                try:
+                    return func(*args, **kw)
+                except exceptions as e:
+                    last = e
+                    if attempt == times:
+                        break
+                    if on_retry:
+                        on_retry(attempt, e)
+                    time.sleep(wait_)
+                    wait_ *= backoff
+            if raise_last and last is not None:
+                raise last
+            return default
+        return wrapper
+    return deco
+
+
+def debug_time(func):
+    @functools.wraps(func)
+    def wrapper(*args, **kwargs):
+        t0 = time.perf_counter()
+        try:
+            return func(*args, **kwargs)
+        finally:
+            dt = time.perf_counter() - t0
+            print(c(f'[t] {func.__name__}: {dt:.3f}s', 'gray'))
+    return wrapper
+
+
+# ============================================================
+# 25. JSON / STORE
+# ============================================================
+
+def load_json(path, default=None):
+    p_ = Path(path)
+    if not p_.exists():
+        return default
+    try:
+        return json.loads(p_.read_text(encoding='utf-8'))
+    except (json.JSONDecodeError, OSError):
+        return default
+
+
+def save_json(path, data, indent=2, ensure_ascii=False) -> Path:
+    p_ = Path(path)
+    p_.parent.mkdir(parents=True, exist_ok=True)
+    p_.write_text(
+        json.dumps(data, ensure_ascii=ensure_ascii, indent=indent, default=str),
+        encoding='utf-8',
+    )
+    return p_
+
+
+class Store:
+    def __init__(self, path='store.json'):
+        self.path = Path(path)
+        self.data = load_json(self.path, default={}) or {}
+        self._history: dict[str, list] = {}
+
+    def save(self): save_json(self.path, self.data)
+    def get(self, key, default=None): return self.data.get(key, default)
+
+    def set(self, key, value):
+        self.data[key] = value
+        self._history.setdefault(key, []).append(value)
+        self.save()
+        return value
+
+    def delete(self, key):
+        self.data.pop(key, None)
+        self.save()
+
+    def update(self, **kw):
+        self.data.update(kw)
+        self.save()
+        return self.data
+
+    def keys(self): return list(self.data.keys())
+
+    def clear(self):
+        self.data.clear()
+        self.save()
+
+    def history(self, key: str) -> list:
+        return list(self._history.get(key, []))
+
+    def __contains__(self, key): return key in self.data
+    def __getitem__(self, key): return self.data[key]
+    def __setitem__(self, key, value): self.set(key, value)
+    def __repr__(self): return f'Store({self.path!s}, {len(self.data)} keys)'
+
+
+# ============================================================
+# 26. ДЕБАГ
+# ============================================================
+
+def _fmt_val(v: Any, max_len: int = 120) -> str:
+    if isinstance(v, str):
+        s = repr(v)
+        return c(s if len(s) <= max_len else s[:max_len - 1] + '…', 'green')
+    if isinstance(v, bool):
+        return c(str(v), 'bright_yellow')
+    if isinstance(v, (int, float)):
+        return c(str(v), 'bright_cyan')
+    if v is None:
+        return c('None', 'gray')
+    if isinstance(v, (list, tuple, set, dict)):
+        s = repr(v)
+        return c(s if len(s) <= max_len else s[:max_len - 1] + '…', 'bright_magenta')
+    return c(repr(v)[:max_len], 'bright_white')
+
+
+class _Dbg:
+    def __init__(self, color='magenta'):
+        self.color = color
+
+    def __call__(self, *args, **kwargs):
+        frame = inspect.currentframe().f_back
+        info = inspect.getframeinfo(frame)
+        filename = os.path.basename(info.filename)
+        line = info.lineno
+        src = linecache.getline(info.filename, line).strip()
+        exprs = self._extract_exprs(src)
+        parts = []
+        for i, val in enumerate(args):
+            name = exprs[i] if i < len(exprs) else f'arg{i}'
+            parts.append(f'{c(name, self.color)}={_fmt_val(val)}')
+        for k, v in kwargs.items():
+            parts.append(f'{c(k, self.color)}={_fmt_val(v)}')
+        loc = c(f'{filename}:{line}', 'gray')
+        print(f'{c("🐛", self.color)} {loc}  ' + ', '.join(parts))
+
+    @staticmethod
+    def _extract_exprs(src: str) -> list[str]:
+        m = _re.search(r'\bdbg\s*\((.*)\)', src)
+        if not m:
+            return []
+        inner = m.group(1)
+        parts, depth, cur = [], 0, ''
+        for ch in inner:
+            if ch in '([{':
+                depth += 1
+            elif ch in ')]}':
+                depth -= 1
+            if ch == ',' and depth == 0:
+                parts.append(cur.strip())
+                cur = ''
+            else:
+                cur += ch
+        if cur.strip():
+            parts.append(cur.strip())
+        return parts
+
+    def trace(self):
+        stack = inspect.stack()
+        if len(stack) > 1:
+            caller = stack[1]
+            print(c(f'↳ {caller.function}() в '
+                    f'{os.path.basename(caller.filename)}:{caller.lineno}',
+                    self.color))
+
+    def stack(self, limit=10):
+        stack = inspect.stack()[1:limit + 1]
+        print(c(f'📚 стек ({len(stack)}):', self.color, bold=True))
+        for i, fr in enumerate(stack):
+            prefix = '  └─' if i else '  ┌─'
+            print(f'{c(prefix, "gray")} {fr.function}() '
+                  f'{c(f"{os.path.basename(fr.filename)}:{fr.lineno}", "gray")}')
+
+    def watch(self, func):
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):
+            name = c(func.__name__, self.color, bold=True)
+            sig = ', '.join([_fmt_val(a) for a in args] +
+                            [f'{k}={_fmt_val(v)}' for k, v in kwargs.items()])
+            print(f'→ {name}({sig})')
+            t0 = time.perf_counter()
+            try:
+                result = func(*args, **kwargs)
+            except Exception as e:
+                dt = (time.perf_counter() - t0) * 1000
+                print(f'← {name} ✗ {c(type(e).__name__, "red")}: {e} '
+                      f'{c(f"({dt:.1f}ms)", "gray")}')
+                raise
+            dt = (time.perf_counter() - t0) * 1000
+            print(f'← {name} = {_fmt_val(result)} {c(f"({dt:.1f}ms)", "gray")}')
+            return result
+        return wrapper
+
+    def breakpoint(self):
+        print(c('⏸  breakpoint', 'yellow', bold=True))
+        import pdb
+        pdb.set_trace()
+
+
+dbg = _Dbg()
+
+
+def color_traceback(exc: BaseException | None = None):
+    if exc is None:
+        exc = sys.exc_info()[1]
+    if exc is None:
+        print(c('Нет активного исключения', 'yellow'))
+        return
+    print(c(f'\n✗ {type(exc).__name__}: {exc}', 'red', bold=True))
+    for frame in _tb.extract_tb(exc.__traceback__):
+        loc = f'{os.path.basename(frame.filename)}:{frame.lineno}'
+        print(f'  {c("в", "gray")} {c(frame.name, "cyan")}() {c(loc, "gray")}')
+        if frame.line:
+            print(f'      {c(frame.line.strip(), "bright_white")}')
+    print()
+
+
+# ============================================================
+# 27. SHELL
+# ============================================================
+
+def run_shell(cmd: str, check: bool = True,
+              spinner_text: str | None = None) -> int:
+    text = spinner_text if spinner_text is not None else cmd
+    start = time.time()
+    _fspin_start(text, _SPINNER_DEFAULTS['color'])
+    try:
+        rc = subprocess.call(cmd, shell=True)
+    finally:
+        dt = time.time() - start
+        _fspin_finish('✓' if rc == 0 else '✗',
+                      'green' if rc == 0 else 'red',
+                      text, dt)
+    if check and rc != 0:
+        err(f'Команда завершилась с кодом {rc}')
+    return rc
+
+
+# ============================================================
+# 28. ИГРОВОЕ
+# ============================================================
+
+def dice(n: int = 1, sides: int = 6) -> int:
+    return sum(random.randint(1, sides) for _ in range(n))
+
+
+def chance(p: float) -> bool:
+    return random.random() < p
+
+
+def pick_weighted(items: list) -> Any:
+    if not items:
+        return None
+    values = [it[0] for it in items]
+    weights = [it[1] for it in items]
+    return random.choices(values, weights=weights, k=1)[0]
+
+
+# ============================================================
+# 29. МЕЛОЧИ
+# ============================================================
+
+def env(name: str, default: Any = None, cast: Callable = str) -> Any:
+    val = os.environ.get(name)
+    if val is None:
+        return default
+    try:
+        return cast(val)
+    except (ValueError, TypeError):
+        return default
+
+
+def chunk(seq: list, size: int) -> Iterator[list]:
+    for i in range(0, len(seq), size):
+        yield seq[i:i + size]
+
+
+def pick(data: dict, path, default: Any = None) -> Any:
+    keys = path.split('.') if isinstance(path, str) else path
+    cur = data
+    for k in keys:
+        if isinstance(cur, dict) and k in cur:
+            cur = cur[k]
+        else:
+            return default
+    return cur
+
+
+def uniq(seq: Iterable) -> list:
+    return list(dict.fromkeys(seq))
+
+
+def first(seq: Iterable, default=None, pred=None):
+    return next((x for x in seq if pred is None or pred(x)), default)
+
+
+def last(seq: Iterable, default=None, pred=None):
+    return next((x for x in reversed(list(seq)) if pred is None or pred(x)), default)
+
+
+def clamp(value: float, lo: float, hi: float) -> float:
+    return max(lo, min(value, hi))
+
+
+def slugify(text: str) -> str:
+    import unicodedata
+    text = unicodedata.normalize('NFKD', text)
+    text = text.encode('ascii', 'ignore').decode('ascii').lower()
+    return _re.sub(r'[^a-z0-9]+', '-', text).strip('-')
+
+
+# ============================================================
+# 30. ИНИЦИАЛИЗАЦИЯ
+# ============================================================
+
+def init(colors: bool = True, wcwidth_hint: bool = True,
+         spinner_color: str | None = None,
+         spinner_show_time: bool | None = None,
+         spinner_preset: str | None = None,
+         spinner_kind: str | None = None,
+         spinner_speed: float | None = None,
+         level_styles: dict | None = None,
+         sounds: bool = True) -> None:
+    """Инициализирует rypy и задаёт дефолты."""
+    enable_colors(colors)
+    if not sounds:
+        sound_off()
+    if spinner_color is not None:
+        _SPINNER_DEFAULTS['color'] = spinner_color
+    if spinner_show_time is not None:
+        _SPINNER_DEFAULTS['show_time'] = spinner_show_time
+    if spinner_preset is not None:
+        _SPINNER_DEFAULTS['preset'] = spinner_preset
+    if spinner_kind is not None:
+        _SPINNER_DEFAULTS['kind'] = spinner_kind
+    if spinner_speed is not None:
+        _SPINNER_DEFAULTS['speed'] = spinner_speed
+    if level_styles:
+        _LEVEL_STYLES.update(level_styles)
+    if wcwidth_hint and not _HAS_WCWIDTH and colors and _ENABLED:
+        print(c('ℹ rypy: pip install wcwidth для таблиц с эмодзи', 'gray'))
+
+
+def bootstrap(app_name: str = '', **kwargs) -> None:
+    init(**kwargs)
+    if app_name:
+        banner(app_name)
+
+
+def import_all(namespace: dict | None = None) -> None:
+    if namespace is None:
+        namespace = inspect.currentframe().f_back.f_globals
+    for name in __all__:
+        namespace[name] = globals()[name]
+
+
+# ============================================================
+# 31. CHEATSHEET — УМНАЯ ШПАРГАЛКА
+# ============================================================
+
+_CHEATSHEET = {
+    'colors': ('Цвета и градиенты', [
+        ("ok / info / warn / err / debug", "ok('готово'); err('упало')"),
+        ("c(text, color, bold=True)", "c('ошибка', 'red', bold=True)"),
+        ("gprint(text, start, end)", "gprint('GRADIENT', 'red', 'blue')"),
+        ("gprint3(text, s, m, e)", "gprint3('X', 'red', 'yellow', 'green')"),
+        ("glow_print(text, duration=1.5)", "glow_print('★ ПРИВЕТ ★')"),
+        ("glow_print3(text, s, m, e, duration=1.5)", "glow_print3('★', 'red', 'yellow', 'green')"),
+        ("gradient / gradient3", "print(gradient('X', 'red', 'blue'))"),
+        ("hex_color('#ff8800')", "c('X', hex_color('#ff8800'))"),
+    ]),
+    'spinner': ('Спиннеры', [
+        ("with spinner(text, preset=..)", "with spinner('Загрузка', preset='circle'): ..."),
+        ("spin / spin_done / spin_fail", "print(f'{spin(\"X\")}', end=''); spin_done()"),
+        ("step_run(text, fn, ...)", "step_run('A', f1, 'B', f2)"),
+        ("do(text, fn) / pause(text, sec)", "do('Считаю', sum, [1,2,3]); pause('Ждём', 2)"),
+        ("spinner_pause через with", "with spinner('X') as s: s.pause(); s.resume()"),
+        ("SSPINNER_FRAMES.keys()", "list(SPINNER_FRAMES.keys())  # 55+ пресетов"),
+        ("pick_preset(kind)", "pick_preset('circle')"),
+    ]),
+    'bars': ('Прогресс и бары', [
+        ("progress(iter, prefix=..)", "for x in progress(range(100), prefix='X'): ..."),
+        ("progress3(iter, colors=..)", "for x in progress3(range(100)): ..."),
+        ("progress_multi([labels])", "with progress_multi(['A', 'B']) as pm: pm.update('A', 50)"),
+        ("PBar(total).update(n)", "bar = PBar(100); bar.update(50); bar.close()"),
+        ("bar_wave(total, prefix=..)", "b = bar_wave(100); b.update(50); b.close()"),
+        ("bar(v, max, width, color)", "print(f'[{bar(75, 100, 20, \"green\")}]')"),
+        ("bar3(v, max, s, m, e)", "print(bar3(75, 100, 20, 'red', 'yellow', 'green'))"),
+        ("hp_bar / mp_bar / xp_bar", "print(hp_bar(75, 100)); print(mp_bar(30, 50))"),
+        ("hud({'HP': (75, 100)})", "hud({'HP': (75, 100), 'MP': (30, 50)})"),
+    ]),
+    'tables': ('Таблицы', [
+        ("table(rows, style='rounded')", "table(users, style='double')"),
+        ("Table(rows).style().show()", "Table(users).style('double').show()"),
+        ("table_from_csv(path)", "table_from_csv('users.csv')"),
+        ("highlight / formatters", "table(users, highlight=lambda r: r['age']>30)"),
+        ("footer={'Итого': 100}", "table(rows, footer={'name': 'Итого', 'score': 5000})"),
+    ]),
+    'sound': ('Звуки', [
+        ("sound(name)", "sound('ok'); sound('error'); sound('level_up')"),
+        ("sound(freq, duration)", "sound(freq=880, duration=200)"),
+        ("sound_list()", "sound_list()  # 20 встроенных звуков"),
+        ("sound_on / sound_off", "sound_off()  # отключить все звуки"),
+    ]),
+    'input': ('Интерактив', [
+        ("ask(label, default)", "name = ask('Имя', 'Аня')"),
+        ("confirm(label, default)", "if confirm('Точно?', default=False): ..."),
+        ("prompt(label, default)", "x = prompt('Значение')"),
+        ("password()", "pwd = password('Пароль')"),
+        ("spinner_selection(prompt, items)", "idx = spinner_selection('Выбор?', ['A', 'B'])"),
+        ("Ask().text().choice().run()", "Ask().text('Имя').confirm('OK?').run()"),
+        ("wizard([(label, kind, opts)])", "wizard([('Имя', 'text', {}), ('Возраст', 'number', {'min':18})])"),
+    ]),
+    'frames': ('Рамки и декор', [
+        ("box(text, style, color, title)", "box('Готово!', color='green', title='OK')"),
+        ("banner(text)", "banner('MY APP', style='double')"),
+        ("kv({'key': 'value'})", "kv({'Хост': 'localhost', 'Порт': 5432})"),
+        ("center(text) / box_center([...])", "center('Привет', color='cyan')"),
+        ("notify_center(text, level)", "notify_center('Сохранено', 'ok')"),
+        ("section(title)", "section('Раздел 1')"),
+        ("rule / double_rule / rainbow_rule", "double_rule(); rainbow_rule()"),
+    ]),
+    'animations': ('Анимации', [
+        ("typewriter(text, delay)", "typewriter('Привет', 0.03)"),
+        ("animate(text, duration)", "animate('Загрузка', 2)"),
+        ("glow(text, colors, cycles)", "glow('ЗАГРУЗКА')"),
+        ("rain / rain_line / rain_multi", "rain('★', 20, 2); rain_multi('★', 8, 5, 2)"),
+        ("stars_rain / hearts_rain / fireworks", "stars_rain(10); fireworks(3)"),
+        ("divider_animated / line_reveal / fade_in", "divider_animated(0.5)"),
+    ]),
+    'data': ('Данные', [
+        ("tree({nested: dict})", "tree({'src': {'main.py': None}})"),
+        ("diff(dict_a, dict_b)", "diff({'a':1}, {'a':2, 'b':3})"),
+        ("chart(values, label)", "chart([1,3,5,8,6], 'CPU')"),
+        ("columns(items)", "columns(['a','b','c','d'])"),
+        ("flatten / uniq / chunk", "uniq([1,2,1,3]); list(chunk(list(range(10)), 3))"),
+        ("pick(data, 'a.b.c')", "pick({'a': {'b': 42}}, 'a.b')"),
+    ]),
+    'advanced': ('Продвинутое', [
+        ("Keyboard()", "kb = Keyboard(); kb.on('q', quit); kb.start()"),
+        ("Stream(label)", "with Stream('Читаю') as s: s.update('строка 1')"),
+        ("Dashboard(refresh=0.5)", "with Dashboard() as db: db.panel('CPU', fn)"),
+        ("Parser('name')", "cli = Parser(); cli.flag('--v'); cli.parse()"),
+        ("Log(name, max_size='10MB')", "log = Log('app', max_size='10MB', backups=5)"),
+    ]),
+    'misc': ('Мелочи', [
+        ("human_time / human_size / money", "human_time(3725); money(1234567)"),
+        ("timer('label')", "with timer('блок'): ..."),
+        ("retry(times, delay)", "@retry(3, 1.0); def fetch(): ..."),
+        ("dbg(x, y)", "dbg(a, b['c'])  # с именами"),
+        ("env('NAME', default, cast)", "port = env('PORT', 8080, int)"),
+        ("dice(n, sides) / chance(p)", "dmg = dice(2, 6); if chance(0.3): ..."),
+        ("slugify(text) / clamp(v, lo, hi)", "slugify('Привет!'); clamp(150, 0, 100)"),
+    ]),
+}
+
+
+def cheatsheet(section_name: str | None = None,
+               search: str | None = None) -> None:
+    """Печатает шпаргалку по всей библиотеке.
+
+    Примеры:
+        cheatsheet()                    # все разделы
+        cheatsheet('spinner')           # только спиннеры
+        cheatsheet(search='table')      # поиск по всем разделам
+    """
+    if section_name and section_name in _CHEATSHEET:
+        title, items = _CHEATSHEET[section_name]
+        _print_cheat_section(title, items)
+        return
+
+    if search:
+        q = search.lower()
+        for key, (title, items) in _CHEATSHEET.items():
+            hits = [(k, v) for k, v in items if q in k.lower() or q in v.lower()]
+            if hits:
+                _print_cheat_section(title, hits)
+        return
+
+    # Всё
+    print()
+    banner(f'RYPY v{__version__} — шпаргалка',
+           style='double', color='bright_magenta')
+    print()
+    cprint('Разделы:', color='gray')
+    for key, (title, _) in _CHEATSHEET.items():
+        print(f'  {c(key, "yellow"):<15} — {title}')
+    print()
+    cprint('Используй: cheatsheet("spinner") или cheatsheet(search="table")',
+           color='gray')
+    print()
+
+
+def _print_cheat_section(title: str, items: list) -> None:
+    print()
+    cprint(f'▶ {title}', color='bright_cyan', bold=True)
+    print(c('─' * min(term_width() - 2, 60), 'gray'))
+    for name, example in items:
+        print(f'  {c(name, "yellow")}')
+        print(f'      {c(example, "gray")}')
+    print()
+
+
+def docs(path: str | None = None, fmt: str = 'md') -> str | None:
+    """Генерирует документацию по всей библиотеке.
+
+    Примеры:
+        docs()                    # печатает markdown в stdout
+        docs('rypy.md')           # пишет в файл
+    """
+    lines = [f'# rypy v{__version__}', '',
+             'Библиотека шорткатов для CLI.', '']
+    for key, (title, items) in _CHEATSHEET.items():
+        lines.append(f'## {title}')
+        lines.append('')
+        for name, example in items:
+            lines.append(f'### `{name}`')
+            lines.append('')
+            lines.append('```python')
+            lines.append(example)
+            lines.append('```')
+            lines.append('')
+    text = '\n'.join(lines)
+    if path:
+        Path(path).write_text(text, encoding='utf-8')
+        ok(f'Документация записана в {path}')
+        return None
+    print(text)
+    return text
+
+
+def test_all() -> None:
+    """Smoke-тест всех ключевых функций. Печатает ✓/✗ на каждую."""
+    tests = [
+        ('c', lambda: c('X', 'red') and True),
+        ('ok', lambda: ok('test') or True),
+        ('gradient', lambda: gradient('X', 'red', 'blue') and True),
+        ('gradient3', lambda: gradient3('X', 'red', 'yellow', 'green') and True),
+        ('bar', lambda: bar(5, 10, 10, 'green') and True),
+        ('bar3', lambda: bar3(5, 10, 10) and True),
+        ('hp_bar', lambda: hp_bar(50, 100) and True),
+        ('human_time', lambda: human_time(3725) and True),
+        ('human_size', lambda: human_size(1536) and True),
+        ('money', lambda: money(1234567) and True),
+        ('plural', lambda: plural(5, 'a', 'b', 'c') and True),
+        ('chunk', lambda: list(chunk([1, 2, 3], 2)) == [[1, 2], [3]]),
+        ('pick', lambda: pick({'a': {'b': 1}}, 'a.b') == 1),
+        ('uniq', lambda: uniq([1, 1, 2]) == [1, 2]),
+        ('slugify', lambda: slugify('Привет!') == 'privet'),
+        ('clamp', lambda: clamp(150, 0, 100) == 100),
+        ('flatten', lambda: list(flatten([1, [2, 3]])) == [1, 2, 3]),
+        ('dice', lambda: 1 <= dice(1, 6) <= 6),
+        ('chance', lambda: chance(1.0) is True),
+        ('sound', lambda: True),  # только проверка, что не падает
+    ]
+    section('Smoke-тест rypy')
+    passed = 0
+    for name, fn in tests:
+        try:
+            result = fn()
+            if result:
+                print(f'  {c("✓", "green")} {name}')
+                passed += 1
+            else:
+                print(f'  {c("✗", "red")} {name} — вернул False')
+        except Exception as e:
+            print(f'  {c("✗", "red")} {name} — {type(e).__name__}: {e}')
+    space()
+    if passed == len(tests):
+        ok(f'Все {passed} тестов прошли')
+    else:
+        warn(f'Пройдено {passed}/{len(tests)}')
+
+
+def new(project_name: str = 'myproject',
+        path: str | None = None) -> Path:
+    """Создаёт скелет нового проекта.
+
+    Пример:
+        new('myapp')       # создаст папку myapp/ с main.py и rypy.py
+    """
+    base = Path(path or '.').resolve() / project_name
+    base.mkdir(parents=True, exist_ok=True)
+
+    # main.py
+    main_py = base / 'main.py'
+    main_py.write_text(
+        f'"""\n{project_name} — CLI на rypy.\n"""\n'
+        f'from rypy import *\n\n'
+        f'bootstrap("{project_name.upper()}")\n\n\n'
+        f'def main():\n'
+        f'    ok("Готово")\n\n\n'
+        f'if __name__ == "__main__":\n'
+        f'    main()\n',
+        encoding='utf-8',
+    )
+
+    # requirements.txt
+    (base / 'requirements.txt').write_text('wcwidth\n', encoding='utf-8')
+
+    # .gitignore
+    (base / '.gitignore').write_text(
+        '__pycache__/\n*.pyc\n.venv/\nlogs/\n*.log\nstore.json\n',
+        encoding='utf-8',
+    )
+
+    # README.md
+    (base / 'README.md').write_text(
+        f'# {project_name}\n\nCLI на [rypy](https://github.com/).\n\n'
+        f'## Запуск\n\n```bash\npython main.py\n```\n',
+        encoding='utf-8',
+    )
+
+    ok(f'Проект создан: {base}')
+    info(f'Скопируй rypy.py в {base}/')
+    info(f'Затем: cd {base} && python main.py')
+    return base
+
+
+# ============================================================
+# 32. ТОЧКА ВХОДА
+# ============================================================
+
+if __name__ == '__main__':
+    init()
+    banner(f'RYPY v{__version__}')
+    cprint(f'  {_CHEATSHEET["colors"][0]}', color='gray')
+    print()
+    cprint('Всё работает. Используй:', color='gray')
+    print(f'  {c("cheatsheet()", "yellow")}     — шпаргалка')
+    print(f'  {c("test_all()", "yellow")}       — smoke-тест')
+    print(f'  {c("sound_list()", "yellow")}     — все звуки')
+    print(f'  {c("docs()", "yellow")}           — markdown-документация')
+    print(f'  {c("new(\"myapp\")", "yellow")}     — создать проект')
+    print()
+    ok(f'rypy v{__version__} загружен')