server.py

#!/usr/bin/env python3
"""
BookHaven 3D — единый сервер.

ОДИН порт обслуживает и статику (HTML/CSS/JS), и API (состояние,
книги, звуки, ударения для диктора) — фронтенд ходит по
относительным путям на тот же origin, без кросс-доменных запросов.

Использование:
    python3 server.py                     # 8080; занят — 8081…8099 (авто)
    python3 server.py --port 9000         # точный порт (занят = ошибка)
    python3 server.py --port 0           # свободный порт выбирает ОС
    python3 server.py --host 127.0.0.1    # только локально (для обёрток)
    python3 server.py --quiet            # без логов запросов

Порт, на котором приложение видно СНАРУЖИ, может быть любым
(Docker -p 9000:8080, обратный прокси): фронтенд ходит по
относительным путям на тот же origin — серверу не нужно знать,
на каком порту его видит пользователь.
"""

import argparse
import json
import os
import re
import sys
import time
from datetime import datetime
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer, SimpleHTTPRequestHandler
from pathlib import Path

# ---- Пути: статика vs пользовательские данные ----
# В PyInstaller (собранный .app/.exe) __file__ указывает на ВРЕМЕННУЮ
# распаковку (sys._MEIPASS), где лежат статические файлы (css/js/lib/...).
# Пользовательские данные (books/, data/) туда класть НЕЛЬЗЯ — они
# пропадут при каждом запуске. Поэтому:
#   STATIC_ROOT — откуда раздаём статику (в PyInstaller — _MEIPASS);
#   DATA_ROOT   — где живут книги и state.json (рядом с приложением).
if getattr(sys, 'frozen', False):
    # Собранный бинарник (PyInstaller)
    STATIC_ROOT = Path(getattr(sys, '_MEIPASS', Path(__file__).parent))
    # Данные — рядом с исполняемым файлом (не во временной распаковке)
    DATA_ROOT = Path(sys.executable).resolve().parent
else:
    # Обычный запуск из исходников: всё в одном каталоге
    STATIC_ROOT = Path(__file__).parent
    DATA_ROOT = STATIC_ROOT

DATA_FILE = DATA_ROOT / 'data' / 'state.json'
BOOKS_DIR = DATA_ROOT / 'books'
SOUNDS_DIR = STATIC_ROOT / 'sounds'
STRESS_DICT_FILE = STATIC_ROOT / 'lib' / 'stress_dict.json.gz'

# Порт по умолчанию и сколько запасных пробовать, если он занят
# (8080 занят у пользователя — встанем на 8081, и так до 8099).
DEFAULT_PORT = 8080
PORT_FALLBACK_ATTEMPTS = 20

# Максимальный размер тела запроса (байт). Книга целиком (FB2 ~5-10 МБ)
# вписывается в лимит с запасом; всё, что больше, — отвергаем, чтобы
# запрос не выедал память сервера.
MAX_BODY_BYTES = 64 * 1024 * 1024

# Разрешённые расширения файлов книг (точка в нижнем регистре)
BOOK_EXTS = ('.fb2', '.txt', '.epub')

# Разрешённые расширения звуковых файлов перелистывания
SOUND_EXTS = ('.mp3', '.ogg', '.wav', '.m4a', '.aac')

# ---------- Словарь ударений (для диктора) ----------
# Загружается лениво при первом запросе /tts/stress.
# Формат: слово -> слово с '+' после ударной гласной («зам+ок»).
_STRESS = {'dict': None, 'loaded': False}


def load_stress_dict():
    """Загружает словарь ударений из lib/stress_dict.json.gz (один раз)."""
    if _STRESS['loaded']:
        return _STRESS['dict']
    _STRESS['loaded'] = True
    if not STRESS_DICT_FILE.exists():
        log(f'Словарь ударений не найден: {STRESS_DICT_FILE}')
        return None
    import gzip
    try:
        with gzip.open(STRESS_DICT_FILE, 'rt', encoding='utf-8') as f:
            data = json.load(f)
        _STRESS['dict'] = data.get('accents', {})
        log(f"Словарь ударений загружен: {len(_STRESS['dict'])} словоформ")
    except Exception as e:
        log(f'Ошибка загрузки словаря ударений: {e}')
    return _STRESS['dict']

QUIET = False  # --quiet отключает логирование


def safe_book_id(book_id):
    """Валидирует id книги (имя файла без расширения).

    Разрешаем только «безопасные» символы имени файла: буквы, цифры,
    дефис, подчёркивание, пробел, скобки и кириллицу. Запрещаем
    '/', '\\', '..' и прочие спецсимволы — это закрывает path traversal
    через id книги (GET /books/<id>/text, DELETE /books/<id> и т.д.).
    """
    if not book_id or not isinstance(book_id, str):
        return None
    if book_id in ('.', '..'):
        return None
    if any(sep in book_id for sep in ('/', '\\', '\x00')):
        return None
    # Управляющие символы и слишком длинные имена — мимо
    if len(book_id) > 255 or any(ord(c) < 32 for c in book_id):
        return None
    return book_id


def sanitize_filename(name):
    """Очищает имя файла, приходящее от клиента (originalName).

    1) Берём только последнюю компоненту пути (срезает ../ и подкаталоги);
    2) запрещаем точку/двоеточие в начале (скрытые файлы, Windows-устройства);
    3) вырезаем управляющие символы.
    Возвращает безопасное имя или None, если после очистки ничего не осталось.
    """
    if not name or not isinstance(name, str):
        return None
    # Только basename — «../evil» → «evil», «a/b» → «b»
    name = name.replace('\\', '/').split('/')[-1]
    if not name or name in ('.', '..'):
        return None
    if name[0] in ('.', ' '):  # без скрытых файлов и ведущих пробелов
        return None
    # Управляющие символы — вырезаем
    name = ''.join(c for c in name if ord(c) >= 32)
    name = name.strip()
    if not name or len(name) > 255:
        return None
    return name


def now_str():
    return datetime.now().strftime('%Y-%m-%d %H:%M:%S')


def log(msg):
    """Диагностика и логи запросов — глушится флагом --quiet."""
    if not QUIET:
        print(f'[{now_str()}] {msg}', flush=True)


def announce(msg):
    """Стартовая информация и критические ошибки.

    Печатается ВСЕГДА, даже с --quiet: --quiet задуман как «без логов
    запросов», а не «полное молчание». Пользователь обязан видеть, на
    каком порту открылось приложение, и почему оно не открылось.
    """
    print(f'[{now_str()}] {msg}', flush=True)


def ensure_store():
    DATA_FILE.parent.mkdir(parents=True, exist_ok=True)
    if not DATA_FILE.exists():
        DATA_FILE.write_text(json.dumps({'books': []}, ensure_ascii=False), encoding='utf-8')


def ensure_books_dir():
    BOOKS_DIR.mkdir(parents=True, exist_ok=True)


def load_state():
    ensure_store()
    state = json.loads(DATA_FILE.read_text(encoding='utf-8'))
    # Штамп обновления (мс, как Date.now() в браузере): по нему клиенты
    # понимают, чьё состояние свежее. Старым state.json без штампа — 0.
    if not isinstance(state.get('updatedAt'), (int, float)):
        state['updatedAt'] = 0
    return state


def save_state(state):
    ensure_store()
    # Штамп ставит СЕРВЕР, а не клиент: клиентские часы могут врать.
    # Если во входящем состоянии штамп есть и он старше текущего в файле —
    # это запись устаревшей копии (вкладка открыта давно и не видела чужих
    # изменений) — отвергаем, чтобы не затирать чужие настройки.
    incoming = state.get('updatedAt')
    if isinstance(incoming, (int, float)):
        current = load_state().get('updatedAt', 0)
        if incoming < current:
            return False   # устаревшее состояние — не сохраняем
    state['updatedAt'] = int(time.time() * 1000)
    DATA_FILE.write_text(json.dumps(state, ensure_ascii=False, indent=2), encoding='utf-8')
    return True


# ---------- Утилиты для FB2 ----------

def parse_fb2_meta(fb2_text):
    """Извлекает title/author из XML FB2 (без внешних зависимостей)."""
    import xml.etree.ElementTree as ET
    try:
        root = ET.fromstring(fb2_text)
    except ET.ParseError:
        return {'title': 'Без названия', 'author': 'Неизвестный автор'}

    # Определяем namespace (если есть) для корректного поиска
    ns = ''
    if root.tag.startswith('{'):
        ns = root.tag.split('}')[0] + '}'

    def find_text(path):
        # С namespace префикс нужен на каждом уровне пути
        if ns:
            path = '/'.join(f'{ns}{part}' for part in path.split('/'))
        el = root.find(path)
        if el is not None and el.text:
            return el.text.strip()
        return ''

    title = find_text('description/title-info/book-title')
    first = find_text('description/title-info/author/first-name')
    last = find_text('description/title-info/author/last-name')
    author = ' '.join(filter(None, [last, first])) or 'Неизвестный автор'

    return {
        'title': title or 'Без названия',
        'author': author,
    }


def parse_fb2_blocks(fb2_text):
    """Извлекает блоки текста из FB2.
    Правила форматирования:
    - <section> начинает новую страницу (блок 'pagebreak')
    - <title> → заголовок (тип 'chapter'), текст берётся ОДИН раз
    - <p> внутри <title> не дублируется
    - <p> → абзац, <subtitle>/<epigraph>/<poem>/<cite> → свои типы
    """
    import xml.etree.ElementTree as ET
    try:
        root = ET.fromstring(fb2_text)
    except ET.ParseError:
        return []

    def tag(el):
        return el.tag.split('}')[-1]

    def text_of(el):
        return ' '.join(t for t in el.itertext() if t and t.strip()).strip()

    XLINK_HREF = '{http://www.w3.org/1999/xlink}href'

    def inline_text(el):
        """Текст с сохранением сносок: <a type="note" href="#id">[1]</a>
        заменяется маркером \\uE000id\\uE001[1]\\uE002 — фронтенд сделает его
        кликабельной ссылкой с подсказкой. Обычный текст — как в text_of."""
        parts = []

        def walk(node):
            if tag(node) == 'a' and node.attrib.get('type') == 'note':
                href = node.attrib.get(XLINK_HREF, '')
                note_id = href[1:] if href.startswith('#') else ''
                inner = ' '.join(t for t in node.itertext() if t and t.strip()).strip()
                if note_id:
                    parts.append(f'\uE000{note_id}\uE001{inner}\uE002')
                elif inner:
                    parts.append(inner)
                return
            if node.text and node.text.strip():
                parts.append(node.text.strip())
            for child in node:
                walk(child)
                if child.tail and child.tail.strip():
                    parts.append(child.tail.strip())

        walk(el)
        # Склеиваем: маркер сноски приклеивается к предыдущему слову без
        # пробела («…Сигишоары…[1]»), остальное — через пробел.
        result = ''
        for p in parts:
            if p.startswith('\uE000'):
                result += p
            elif result:
                result += ' ' + p
            else:
                result = p
        return result

    def poem_text(poem_el):
        """Собирает текст стихотворения: <v> = строка, <stanza> = строфа.
        Строки внутри строфы соединяются переносом, строфы — пустой строкой.
        Если <stanza> нет — прямые <v> дети считаются строками."""
        lines = []
        stanzas = [c for c in poem_el if tag(c) == 'stanza']
        if stanzas:
            for stanza in stanzas:
                stanza_lines = [inline_text(v) for v in stanza if tag(v) == 'v']
                stanza_lines = [s for s in stanza_lines if s]
                if stanza_lines:
                    lines.append('\n'.join(stanza_lines))
            return '\n\n'.join(lines)
        # Нет <stanza> — прямые <v> дети
        for v in poem_el:
            if tag(v) == 'v':
                txt = inline_text(v)
                if txt:
                    lines.append(txt)
        return '\n'.join(lines)

    def rich_text_of(el):
        """Текст с сохранением переносов строк (для poem/epigraph/cite).
        <poem> разбирается по строкам; <epigraph>/<cite> — по детям,
        где <poem>/<epigraph>/<cite> рекурсивны, остальное — text_of."""
        t = tag(el)
        if t == 'poem':
            return poem_text(el)
        if t in ('epigraph', 'cite'):
            parts = []
            for child in el:
                ct = tag(child)
                if ct in ('poem', 'epigraph', 'cite'):
                    txt = rich_text_of(child)
                else:
                    txt = inline_text(child)
                if txt:
                    parts.append(txt)
            return '\n\n'.join(parts)
        return text_of(el)

    blocks = []

    def add_child(child):
        """Разбирает один элемент секции и возвращает True, если он обработан."""
        t = tag(child)
        if t == 'title':
            txt = text_of(child)
            if txt:
                blocks.append({'type': 'chapter', 'text': txt})
            return True
        if t == 'p':
            txt = inline_text(child)
            if txt:
                blocks.append({'type': 'paragraph', 'text': txt})
            return True
        if t == 'subtitle':
            txt = text_of(child)
            if txt:
                blocks.append({'type': 'subtitle', 'text': txt})
            return True
        if t == 'epigraph':
            txt = rich_text_of(child)
            if txt:
                blocks.append({'type': 'epigraph', 'text': txt})
            return True
        if t == 'poem':
            txt = poem_text(child)
            if txt:
                blocks.append({'type': 'poem', 'text': txt})
            return True
        if t == 'cite':
            txt = rich_text_of(child)
            if txt:
                blocks.append({'type': 'cite', 'text': txt})
            return True
        if t == 'image':
            # Картинка в теле книги: <image xlink:href="#name"/>
            href = child.attrib.get('{http://www.w3.org/1999/xlink}href', '')
            if href.startswith('#'):
                blocks.append({'type': 'image', 'src': href[1:]})
            return True
        return False

    def walk_container(container, start_new_page):
        """Проходит по детям контейнера (body/section)."""
        for child in container:
            if tag(child) == 'section':
                blocks.append({'type': 'pagebreak'})
                walk_container(child, False)
            elif tag(child) == 'empty-line':
                continue
            elif not add_child(child):
                # Неизвестный тег с вложенными элементами — обходим рекурсивно
                walk_container(child, False)

    # Берём основное тело книги (первый <body> с учётом namespace)
    body = next((el for el in root.iter() if tag(el) == 'body'), None)
    if body is None:
        return blocks

    walk_container(body, True)

    # ---- Примечания (сноски) ----
    # Стандартно лежат в отдельном <body name="notes">: заголовок + секции
    # <section id="n_1">. Добавляем их блоками в конец книги, чтобы на них
    # можно было перейти по клику на сноску (как по оглавлению).
    notes_body = next(
        (el for el in root.iter() if tag(el) == 'body' and el.attrib.get('name') == 'notes'),
        None,
    )
    if notes_body is not None:
        def collect_paras(el, out):
            """Собирает абзацы секции, пропуская поддерево <title> (номер
            сноски уже извлечён отдельно)."""
            for c in el:
                ct = tag(c)
                if ct == 'title' or ct == 'empty-line':
                    continue
                if ct == 'p':
                    t = inline_text(c)
                    if t:
                        out.append(t)
                elif ct in ('subtitle', 'v'):
                    t = text_of(c)
                    if t:
                        out.append(t)
                else:
                    collect_paras(c, out)

        for child in notes_body:
            ct = tag(child)
            if ct == 'title':
                # Заголовок раздела «Примечания» — как глава (попадёт в оглавление)
                txt = text_of(child)
                if txt:
                    blocks.append({'type': 'chapter', 'text': txt})
            elif ct == 'section':
                note_id = child.attrib.get('id', '')
                title_el = next((c for c in child if tag(c) == 'title'), None)
                title_txt = text_of(title_el) if title_el is not None else ''
                paras = []
                collect_paras(child, paras)
                body_txt = '\n\n'.join(paras)
                if title_txt and body_txt:
                    sep = '' if title_txt.endswith(('.', '!', '?', ':')) else '.'
                    full = f'{title_txt}{sep} {body_txt}'
                else:
                    full = body_txt or title_txt
                if full:
                    block = {'type': 'note', 'text': full}
                    if note_id:
                        block['noteId'] = note_id
                    blocks.append(block)
            elif ct == 'p':
                txt = inline_text(child)
                if txt:
                    blocks.append({'type': 'paragraph', 'text': txt})

    return blocks


def parse_fb2_cover(fb2_text):
    """Возвращает имя (id) бинарного файла обложки из <coverpage>, или None.

    Обложка в FB2: <coverpage><image xlink:href="#respub.jpg"/></coverpage>,
    а сами данные — в <binary id="respub.jpg" content-type="image/jpeg">base64</binary>.
    """
    import xml.etree.ElementTree as ET
    try:
        root = ET.fromstring(fb2_text)
    except ET.ParseError:
        return None

    def tag(el):
        return el.tag.split('}')[-1]

    for el in root.iter():
        if tag(el) == 'coverpage':
            for child in el:
                if tag(child) == 'image':
                    href = child.attrib.get('{http://www.w3.org/1999/xlink}href', '')
                    if href.startswith('#'):
                        return href[1:]
    return None


def find_fb2_binary(fb2_text, name):
    """Находит <binary id="name"> в FB2 и возвращает (bytes, content_type) или None.

    Данные в FB2 хранятся в base64 внутри <binary>.
    """
    import xml.etree.ElementTree as ET
    import base64
    try:
        root = ET.fromstring(fb2_text)
    except ET.ParseError:
        return None

    def tag(el):
        return el.tag.split('}')[-1]

    for el in root.iter():
        if tag(el) == 'binary' and el.attrib.get('id') == name:
            content_type = el.attrib.get('content-type', 'application/octet-stream')
            data = el.text or ''
            try:
                return base64.b64decode(data), content_type
            except Exception:
                return None
    return None


class APIHandler(BaseHTTPRequestHandler):
    """Обработчик API для сохранения/загрузки состояния и управления книгами."""

    def _read_json_body(self):
        """Читает тело POST-запроса целиком и парсит JSON.

        Возвращает (payload_dict, None) при успехе или (None, error_dict).
        read(n) может вернуть МЕНЬШЕ n байт, если соединение оборвалось
        (таймаут на клиенте, обрыв сети) — поэтому читаем циклом до конца.
        """
        try:
            length = int(self.headers.get('Content-Length', '0'))
        except ValueError:
            return None, {'error': 'Некорректный Content-Length'}
        if length <= 0:
            return {}, None
        if length > MAX_BODY_BYTES:
            return None, {'error': f'Тело запроса слишком большое (лимит {MAX_BODY_BYTES // (1024 * 1024)} МБ)'}

        try:
            data = b''
            remaining = length
            while remaining > 0:
                chunk = self.rfile.read(remaining)
                if not chunk:
                    # Соединение оборвано раньше, чем пришли все байты
                    return None, {'error': 'Тело запроса оборвано (не хватает данных)'}
                data += chunk
                remaining -= len(chunk)
        except OSError:
            # Клиент разорвал соединение (таймаут, обрыв сети)
            return None, {'error': 'Соединение разорвано'}

        try:
            text = data.decode('utf-8')
        except UnicodeDecodeError:
            return None, {'error': 'Тело запроса повреждено (не UTF-8)'}

        try:
            return json.loads(text), None
        except json.JSONDecodeError:
            return None, {'error': 'Invalid JSON'}

    def do_OPTIONS(self):
        self.send_response(200)
        self.send_header('Access-Control-Allow-Origin', '*')
        self.send_header('Access-Control-Allow-Methods', 'GET, POST, DELETE, OPTIONS')
        self.send_header('Access-Control-Allow-Headers', 'Content-Type')
        self.end_headers()

    def do_GET(self):
        from urllib.parse import unquote
        path = self.path.split('?', 1)[0]   # срезаем query-string

        if path == '/state':
            self._send_json(load_state())
        elif path == '/books':
            self._list_books()
        elif path == '/sounds':
            self._list_sounds()
        elif path.startswith('/books/') and path.endswith('/text'):
            book_id = unquote(path.split('/')[-2])
            self._get_book_text(book_id)
        elif path.startswith('/books/') and path.endswith('/meta'):
            book_id = unquote(path.split('/')[-2])
            self._get_book_meta(book_id)
        elif path.startswith('/books/') and path.endswith('/cover'):
            book_id = unquote(path.split('/')[-2])
            self._get_book_cover(book_id)
        elif path.startswith('/books/') and '/image/' in path:
            # /books/<id>/image/<name> — картинка из тела книги
            parts = path.split('/')
            book_id = unquote(parts[2])
            img_name = unquote(parts[4])
            self._get_book_image(book_id, img_name)
        else:
            self._send_json({'error': 'Not found'}, status=404)

    def do_POST(self):
        from urllib.parse import unquote
        path = self.path.split('?', 1)[0]   # срезаем query-string

        if path == '/state':
            self._save_state()
        elif path == '/books':
            self._save_book()
        elif path == '/tts/stress':
            self._tts_stress()
        elif path == '/tts':
            # edge-tts на сервере не реализован (во фронтенде — только каркас
            # с фолбэком на Web Speech). Честный 501 вместо молчаливого
            # проваливания в сохранение состояния.
            self._send_json({'error': 'TTS engine not implemented'}, status=501)
        elif path.startswith('/books/') and path.endswith('/meta'):
            book_id = unquote(path.split('/')[-2])
            self._update_book_meta(book_id)
        else:
            self._send_json({'error': 'Not found'}, status=404)

    def _save_state(self):
        """Сохраняет глобальное состояние (POST /state)."""
        payload, err = self._read_json_body()
        if err:
            self._send_json(err, status=400)
            return
        try:
            saved = save_state(payload)
        except OSError as e:
            self._send_json({'error': 'Не удалось сохранить состояние', 'detail': str(e)}, status=500)
            return
        if not saved:
            # Устаревший штамп: на сервере уже новее состояние (его записал
            # другой браузер). Отдаём актуальное — клиент подтянется.
            self._send_json({'ok': False, 'stale': True, 'state': load_state()})
            return
        # Отдаём новый штамп: иначе клиент запомнит старый из localStorage
        # и его следующий persist будет отвергнут как stale (настройки
        # «откатывались» к серверным после второго сохранения подряд).
        self._send_json({'ok': True, 'updatedAt': load_state().get('updatedAt', 0)})

    def do_DELETE(self):
        from urllib.parse import unquote
        path = self.path.split('?', 1)[0]   # срезаем query-string
        if path.startswith('/books/'):
            book_id = unquote(path.split('/')[-1])
            self._delete_book(book_id)
        else:
            self._send_json({'error': 'Not found'}, status=404)

    def _tts_stress(self):
        """Размечает текст ударениями для диктора.

        POST { text } -> { text: 'слова с + после ударной гласной' }
        Словарь: слово -> 'зам+ок'. Плюс после гласной превращается
        в комбинируемый акут (U+0301) — голос macOS/Google читает
        ударение правильно. Слова не из словаря — без разметки."""
        payload, err = self._read_json_body()
        if err:
            self._send_json(err, status=400)
            return
        text = (payload or {}).get('text', '')
        if not text or not isinstance(text, str):
            self._send_json({'text': ''})
            return

        accents = load_stress_dict()
        if not accents:
            self._send_json({'text': text})
            return

        import re
        vowels = 'аеёиоуыэюя'

        def stress_word(m):
            word = m.group(0)
            lower = word.lower()
            stressed = accents.get(lower)
            if not stressed or '+' not in stressed:
                return word
            # Формат словаря: '+' стоит ПЕРЕД ударной гласной («з+амок»).
            # Переносим на исходное слово с сохранением регистра.
            # Длина может отличаться (ё→е и пр.) — идём по гласным.
            src_v = [i for i, c in enumerate(word) if c.lower() in vowels]
            dst_v = [i for i, c in enumerate(stressed) if c in vowels]
            if len(src_v) != len(dst_v):
                return word
            # Ударная гласная в stressed — первая гласная ПОСЛЕ '+'
            plus_pos = stressed.index('+')
            accent_idx = None
            for k, i in enumerate(dst_v):
                if i > plus_pos:
                    accent_idx = k
                    break
            if accent_idx is None or accent_idx >= len(src_v):
                return word
            pos = src_v[accent_idx]
            return word[:pos + 1] + '\u0301' + word[pos + 1:]

        result = re.sub(r'[А-Яа-яЁё]+', stress_word, text)
        self._send_json({'text': result})

    def _list_sounds(self):
        """Список звуковых файлов перелистывания из папки sounds/.
        Фронтенд выбирает из них случайный при каждом флипе — новые файлы
        подхватываются автоматически, без правок кода."""
        names = []
        if SOUNDS_DIR.is_dir():
            for item in sorted(SOUNDS_DIR.iterdir()):
                if item.is_file() and item.suffix.lower() in SOUND_EXTS:
                    names.append(item.name)
        self._send_json({'sounds': names})

    def _list_books(self):
        """Возвращает список книг из папки books/ (без текста — только метаданные)."""
        ensure_books_dir()
        books = []

        for item in sorted(BOOKS_DIR.iterdir()):
            if not item.is_file() or item.suffix.lower() not in BOOK_EXTS:
                continue

            stem = item.stem
            # Метаданные — из sidecar <stem>.meta.json (если есть), иначе из файла
            sidecar = BOOKS_DIR / f"{stem}.meta.json"
            if sidecar.exists():
                try:
                    meta = json.loads(sidecar.read_text(encoding='utf-8'))
                    meta['id'] = stem
                    meta['format'] = meta.get('format', item.suffix.lstrip('.'))
                    meta.setdefault('progress', 0)
                    meta.setdefault('bookmarks', [])
                    meta.setdefault('palette', [])
                     # hasCover: если в meta.json нет — вычисляем из FB2 (старые книги)
                    if 'hasCover' not in meta and item.suffix.lower() == '.fb2':
                        meta['hasCover'] = parse_fb2_cover(item.read_text(encoding='utf-8')) is not None
                    books.append(meta)
                    continue
                except Exception:
                    pass

            # Нет sidecar — формируем базовые метаданные из файла
            try:
                if item.suffix.lower() == '.fb2':
                    fb2_text = item.read_text(encoding='utf-8')
                    fb2_meta = parse_fb2_meta(fb2_text)
                    meta = {
                         'id': stem, 'format': 'fb2',
                         'title': fb2_meta['title'], 'author': fb2_meta['author'],
                         'progress': 0, 'bookmarks': [], 'palette': [],
                         'hasCover': parse_fb2_cover(fb2_text) is not None,
                    }
                else:
                    meta = {
                        'id': stem, 'format': item.suffix.lstrip('.'),
                        'title': stem, 'author': 'Неизвестный автор',
                        'progress': 0, 'bookmarks': [], 'palette': [],
                    }
                books.append(meta)
            except Exception as e:
                log(f'ERROR GET /books: не удалось разобрать книгу {item.name}: {e}')

        # Диагностика: имена с суффиксом « (N)» — вероятные дубликаты
        dup_ids = [b['id'] for b in books if re.search(r' \(\d+\)$', b['id'])]
        if dup_ids:
            log(f'WARN GET /books: возможные дубликаты книг: {", ".join(dup_ids)}')
        log(f'GET /books: найдено книг — {len(books)}')
        self._send_json({'books': books})

    def _get_book_meta(self, book_id):
        """Возвращает метаданные книги (из sidecar meta.json)."""
        book_id = safe_book_id(book_id)
        if book_id is None:
            self._send_json({'error': 'Invalid book id'}, status=400)
            return
        meta_file = self._find_book_meta_file(book_id)

        if not meta_file or not meta_file.exists():
            self._send_json({'error': 'Book not found'}, status=404)
            return

        meta = json.loads(meta_file.read_text(encoding='utf-8'))
        meta['id'] = book_id
        self._send_json(meta)

    def _get_book_text(self, book_id):
        """Возвращает полный текст книги (FB2 парсится на лету)."""
        book_id = safe_book_id(book_id)
        if book_id is None:
            self._send_json({'error': 'Invalid book id'}, status=400)
            return
        content_file = self._find_book_content_file(book_id)

        if content_file is None:
            self._send_json({'error': 'Book not found'}, status=404)
            return

        if content_file.suffix.lower() == '.fb2':
            # Парсим FB2 на лету — отдаём структурированные блоки
            blocks = parse_fb2_blocks(content_file.read_text(encoding='utf-8'))
            self._send_json({'blocks': blocks, 'format': 'fb2'})
        else:
            # TXT — обычный текст. Бинарный EPUB (не сконвертированный в txt
            # клиентом) прочитать как UTF-8 нельзя — честно отвечаем ошибкой.
            try:
                text = content_file.read_text(encoding='utf-8')
            except UnicodeDecodeError:
                self._send_json({'error': 'Файл книги не является текстовым (бинарный EPUB?)'}, status=422)
                return
            self._send_json({'text': text})

    def _get_book_cover(self, book_id):
        """Отдаёт обложку книги (из <coverpage> FB2) как картинку."""
        book_id = safe_book_id(book_id)
        if book_id is None:
            self._send_json({'error': 'Invalid book id'}, status=400)
            return
        content_file = self._find_book_content_file(book_id)
        if content_file is None or content_file.suffix.lower() != '.fb2':
            self._send_json({'error': 'No cover'}, status=404)
            return

        fb2_text = content_file.read_text(encoding='utf-8')
        cover_name = parse_fb2_cover(fb2_text)
        if not cover_name:
            self._send_json({'error': 'No cover'}, status=404)
            return

        result = find_fb2_binary(fb2_text, cover_name)
        if not result:
            self._send_json({'error': 'No cover data'}, status=404)
            return

        data, content_type = result
        self._send_binary(data, content_type)

    def _get_book_image(self, book_id, img_name):
        """Отдаёт картинку из тела книги (по id <binary>)."""
        book_id = safe_book_id(book_id)
        img_name = safe_book_id(img_name)
        if book_id is None or img_name is None:
            self._send_json({'error': 'Invalid request'}, status=400)
            return
        content_file = self._find_book_content_file(book_id)
        if content_file is None or content_file.suffix.lower() != '.fb2':
            self._send_json({'error': 'Not found'}, status=404)
            return

        fb2_text = content_file.read_text(encoding='utf-8')
        result = find_fb2_binary(fb2_text, img_name)
        if not result:
            self._send_json({'error': 'Image not found'}, status=404)
            return

        data, content_type = result
        self._send_binary(data, content_type)

    def _send_binary(self, data, content_type):
        """Отдаёт бинарные данные (картинку) с правильным Content-Type."""
        try:
            self.send_response(200)
            self.send_header('Content-Type', content_type)
            self.send_header('Content-Length', str(len(data)))
            self.send_header('Access-Control-Allow-Origin', '*')
            self.send_header('Cache-Control', 'public, max-age=86400')
            self.end_headers()
            self.wfile.write(data)
        except OSError:
            pass    # Клиент уже закрыл соединение
    def _save_book(self):
        """Сохраняет книгу в папку books/ (сохраняем оригинальный FB2)."""
        book, err = self._read_json_body()
        if err:
            self._send_json(err, status=400)
            return

        format_ = book.get('format', 'txt')
        if format_ not in ('fb2', 'txt', 'epub'):
            format_ = 'txt'
        ext = '.fb2' if format_ == 'fb2' else '.txt'

         # Имя файла = оригинальное имя книги (без потери), при конфликте — суффикс.
         # sanitize_filename срезает пути (../) и опасные имена — защита от
         # записи файла за пределы books/.
        original_name = sanitize_filename(book.get('originalName')) or sanitize_filename(book.get('title')) or f'book{ext}'

         # Запрос без originalName — подозрительно: такую книгу могла отправить
         # миграция из state.json, а имя файла построено из title → возможный дубликат
        if not book.get('originalName'):
            log(f'WARN POST /books: запрос БЕЗ originalName, имя «{original_name}» построено из title — возможен дубликат!')

        if not original_name.lower().endswith(ext):
            original_name += ext

        # Финальная проверка: файл обязан оказаться внутри books/
        content_file, stem = self._unique_file(BOOKS_DIR, original_name)
        try:
            content_file.resolve().relative_to(BOOKS_DIR.resolve())
        except ValueError:
            self._send_json({'error': 'Недопустимое имя файла'}, status=400)
            return

         # Логируем конфликт имён — так видно момент создания дубликата
        ip = self.client_address[0] if self.client_address else '?'
        if content_file.name != original_name:
            log(f'WARN POST /books {ip}: имя «{original_name}» уже занято — создан дубликат «{content_file.name}»')
        else:
            log(f'POST /books {ip}: сохраняю «{content_file.name}»')

         # Сохраняем контент прямо в books/ (без подпапок)
        if format_ == 'fb2' and book.get('fb2_content'):
            content_file.write_text(book['fb2_content'], encoding='utf-8')
        else:
            content_file.write_text(book.get('text', ''), encoding='utf-8')

        book_id = stem   # id книги = имя файла без расширения

         # Базовые метаданные — сервер сам извлекает title/author из FB2,
         # для остальных форматов берём из payload
        meta = {
             'title': book.get('title', 'Без названия'),
             'author': book.get('author', 'Неизвестный автор'),
             'format': format_,
             'progress': book.get('progress', 0),
             'palette': book.get('palette', []),
             'bookmarks': book.get('bookmarks', []),
             'anchor': book.get('anchor'),
        }

        if format_ == 'fb2' and book.get('fb2_content'):
             # Метаданные извлекаем на сервере из оригинального файла
            fb2_meta = parse_fb2_meta(book['fb2_content'])
            meta['title'] = fb2_meta['title']
            meta['author'] = fb2_meta['author']
             # Есть ли обложка в файле — чтобы библиотека показывала картинку
            meta['hasCover'] = parse_fb2_cover(book['fb2_content']) is not None

         # Метаданные — sidecar файл рядом с книгой: <stem>.meta.json
        meta_file = BOOKS_DIR / f"{book_id}.meta.json"
        meta_file.write_text(json.dumps(meta, ensure_ascii=False, indent=2), encoding='utf-8')

        self._send_json({'ok': True, 'id': book_id, 'meta': meta, 'fileName': content_file.name})

    def _unique_file(self, directory, filename):
        """Возвращает (путь_файла, stem) с уникальным именем:
        если файл уже есть — добавляет ' (2)', ' (3)' и т.д."""
        stem = Path(filename).stem
        ext = Path(filename).suffix
        candidate = directory / filename
        i = 2
        while candidate.exists():
            candidate = directory / f"{stem} ({i}){ext}"
            i += 1
        return candidate, candidate.stem

    def _update_book_meta(self, book_id):
        """Обновляет прогресс/закладки книги в её meta.json.

        Синхронизация между браузерами:
        - позиция (progress/anchor) принимается только если incoming-штамп
          positionUpdatedAt не старше сохранённого (последний двигал страницу —
          тот и прав);
        - закладки ОБЪЕДИНЯЮТСЯ по id: новые добавляются, изменённые обновляются,
          а удалённые не resurrect'ятся благодаря списку-надгробиям
          deletedBookmarksIds (id закладок, которые клиент когда-то удалил).
        """
        from urllib.parse import unquote
        book_id = safe_book_id(unquote(book_id))
        if book_id is None:
            self._send_json({'error': 'Invalid book id'}, status=400)
            return

        payload, err = self._read_json_body()
        if err:
            self._send_json(err, status=400)
            return

        # Ищем meta.json книги — папка или рядом с прямым .fb2 файлом
        meta_file = self._find_book_meta_file(book_id)

        if not meta_file or not meta_file.exists():
            self._send_json({'error': 'Book not found'}, status=404)
            return

        # Читаем текущие метаданные
        try:
            meta = json.loads(meta_file.read_text(encoding='utf-8'))
        except Exception:
            meta = {}

        # ---- Позиция чтения: только свежее затирает свежее ----
        incoming_pos = payload.get('positionUpdatedAt')
        if isinstance(incoming_pos, (int, float)):
            current_pos = meta.get('positionUpdatedAt', 0) or 0
            if incoming_pos >= current_pos:
                for key in ('progress', 'anchor'):
                    if key in payload:
                        meta[key] = payload[key]
                meta['positionUpdatedAt'] = int(time.time() * 1000)
            # иначе: входящая позиция устарела — не трогаем progress/anchor
        else:
            # Штампа нет (старый клиент) — пишем как раньше
            for key in ('progress', 'anchor'):
                if key in payload:
                    meta[key] = payload[key]

        # ---- Закладки: merge по id + надгробия удалённых ----
        if 'bookmarks' in payload:
            incoming_bms = payload.get('bookmarks')
            if isinstance(incoming_bms, list):
                # Надгробия: id удалённых закладок (накапливаются, чтобы
                # другой браузер с устаревшей копией не воскресил закладку)
                tombstones = set(meta.get('deletedBookmarksIds', []) or [])
                if isinstance(payload.get('deletedBookmarksIds'), list):
                    tombstones.update(str(i) for i in payload['deletedBookmarksIds'] if i)

                merged = {}
                for b in meta.get('bookmarks', []) or []:
                    if isinstance(b, dict) and b.get('id'):
                        merged[str(b['id'])] = b
                for b in incoming_bms:
                    if isinstance(b, dict) and b.get('id'):
                        bid = str(b['id'])
                        if bid in tombstones:
                            continue   # удалена в другом браузере — не воскресаем
                        merged[bid] = b
                # Убираем из результата те, что в надгробиях
                bookmarks = [b for bid, b in merged.items() if bid not in tombstones]
                # Сортировка по blockId (как на клиенте) для стабильности
                bookmarks.sort(key=lambda b: (b.get('anchor', {}) or {}).get('blockId') or '')
                meta['bookmarks'] = bookmarks
                meta['deletedBookmarksIds'] = sorted(tombstones)

        for key in ('title', 'author'):
            if key in payload:
                meta[key] = payload[key]

        # Самовосстановление: если title/author потерялись (старый баг
        # перезаписи meta.json) — извлекаем заново из FB2-файла книги
        if not meta.get('title') or not meta.get('author'):
            content = self._find_book_content_file(book_id)
            if content is not None and content.suffix == '.fb2':
                try:
                    fb2_meta = parse_fb2_meta(content.read_text(encoding='utf-8'))
                    if not meta.get('title'):
                        meta['title'] = fb2_meta['title']
                    if not meta.get('author'):
                        meta['author'] = fb2_meta['author']
                    log(f'META self-heal «{book_id}»: title/author восстановлены из FB2')
                except Exception as e:
                    log(f'WARN self-heal «{book_id}»: {e}')

        meta_file.write_text(json.dumps(meta, ensure_ascii=False, indent=2), encoding='utf-8')
        self._send_json({'ok': True, 'meta': meta})

    def _find_book_content_file(self, book_id):
        """Находит файл книги в books/ по id (имени без расширения)."""
        for ext in ('.fb2', '.txt', '.epub'):
            f = BOOKS_DIR / f"{book_id}{ext}"
            if f.exists():
                return f
        return None

    def _find_book_meta_file(self, book_id):
        """Находит sidecar <id>.meta.json рядом с файлом книги.
           Если его нет — создаёт базовый из содержимого книги."""
        content_file = self._find_book_content_file(book_id)
        if content_file is None:
            return None

        meta_file = BOOKS_DIR / f"{book_id}.meta.json"
        if meta_file.exists():
            return meta_file

        # Создаём базовый meta.json
        base = {'format': content_file.suffix.lstrip('.'), 'progress': 0,
                'bookmarks': [], 'anchor': None}
        if content_file.suffix.lower() == '.fb2':
            fb2_meta = parse_fb2_meta(content_file.read_text(encoding='utf-8'))
            base.update({'title': fb2_meta['title'], 'author': fb2_meta['author']})
        else:
            base.update({'title': book_id, 'author': 'Неизвестный автор'})
        meta_file.write_text(json.dumps(base, ensure_ascii=False, indent=2), encoding='utf-8')
        return meta_file

    def _delete_book(self, book_id):
        """Удаляет файл книги и sidecar meta.json из папки books/."""
        book_id = safe_book_id(book_id)
        if book_id is None:
            self._send_json({'error': 'Invalid book id'}, status=400)
            return
        content_file = self._find_book_content_file(book_id)
        if content_file is None:
            self._send_json({'error': 'Book not found'}, status=404)
            return

        content_file.unlink()
        sidecar = BOOKS_DIR / f"{book_id}.meta.json"
        if sidecar.exists():
            sidecar.unlink()
        ip = self.client_address[0] if self.client_address else '?'
        log(f'DELETE /books {ip}: удалена книга «{book_id}» ({content_file.name})')
        self._send_json({'ok': True})

    def _send_json(self, data, status=200):
        try:
            self.send_response(status)
            self.send_header('Content-Type', 'application/json; charset=utf-8')
            self.send_header('Access-Control-Allow-Origin', '*')
            self.end_headers()
            self.wfile.write(json.dumps(data, ensure_ascii=False).encode('utf-8'))
        except OSError:
            pass  # Клиент уже закрыл соединение — отвечать некому

    def log_message(self, format, *args):
        """Печатаем каждый запрос к API в терминал (метод, путь, код, IP)."""
        if QUIET:
            return
        ip = self.client_address[0] if self.client_address else '?'
        try:
            line = format % args if args else format
        except Exception:
            line = format
        print(f'[{now_str()}] {ip} {line}', flush=True)


class StaticHandler(SimpleHTTPRequestHandler):
    """Статический файловый сервер с правильными MIME-типами.

    Отдаёт ТОЛЬКО публичную часть проекта: index.html, css/, js/, lib/,
    assets/, book.svg. Серверный код (server.py), данные (data/),
    метаданные книг (books/) и .git наружу не отдаются.
    """

    # Префиксы путей, которые можно отдавать наружу
    PUBLIC_PREFIXES = ('css/', 'js/', 'lib/', 'assets/', 'sounds/')
    # Точечные файлы в корне, которые можно отдавать
    PUBLIC_ROOT_FILES = {'index.html', 'book.svg', 'favicon.ico'}

    def __init__(self, *args, **kwargs):
        super().__init__(*args, directory=str(STATIC_ROOT), **kwargs)

    def translate_path(self, path):
        """Пропускает только публичные пути; остальное — 404.
        Вызывается из do_GET/do_HEAD для каждого запроса."""
        import urllib.parse
        # Срезаем query-string и нормализуем: '/js/main.js?v=1' → 'js/main.js'
        rel = urllib.parse.urlsplit(path).path.lstrip('/')
        rel = urllib.parse.unquote(rel)
        # Корень сайта ('/') — это index.html
        if rel == '':
            rel = 'index.html'
        allowed = (
            rel in self.PUBLIC_ROOT_FILES
            or any(rel.startswith(p) for p in self.PUBLIC_PREFIXES)
        )
        if not allowed:
            return str(STATIC_ROOT / '__forbidden__')  # несуществующий путь → 404
        return super().translate_path(path)

    def end_headers(self):
        # Кэширование для статики
        if self.path.endswith(('.css', '.js', '.woff2', '.png', '.jpg', '.mp3', '.ogg', '.wav', '.m4a')):
            self.send_header('Cache-Control', 'public, max-age=3600')
        else:
            self.send_header('Cache-Control', 'no-cache')
        super().end_headers()

    def log_message(self, format, *args):
        # Статика шумная — логируем только ошибки (404 и т.п.)
        if QUIET:
            return
        try:
            status = int(args[1]) if len(args) > 1 else 0
        except Exception:
            status = 0
        if status >= 400:
            ip = self.client_address[0] if self.client_address else '?'
            try:
                line = format % args if args else format
            except Exception:
                line = format
            print(f'[{now_str()}] {ip} {line}', flush=True)


def is_api_path(path):
    """True, если путь обслуживает API (а не статику).

    Точные совпадения: /state, /books, /sounds, /tts.
    Префиксы: /books/... (текст, метаданные, обложки) и /tts/... (stress).
    ВАЖНО: /sounds/<файл> — НЕ API: это сами звуковые файлы перелистывания,
    их отдаёт статика из папки sounds/.
    """
    if not path:
        return False
    p = path.split('?', 1)[0]   # query-string не влияет на маршрутизацию
    if p in ('/state', '/books', '/sounds', '/tts'):
        return True
    return p.startswith('/books/') or p.startswith('/tts/')


class UnifiedHandler(APIHandler, StaticHandler):
    """Единый обработчик: ОДИН порт — и API, и статика.

    Маршрутизация по пути: /state, /books..., /tts... и точный /sounds
    обслуживает логика APIHandler; всё остальное — статика (StaticHandler).
    Фронтенд ходит по относительным путям на тот же origin — никаких
    кросс-доменных запросов и второго порта.

    Наследование (MRO): API-методы (_send_json, работа с книгами) — из
    APIHandler; раздача файлов и защита путей (translate_path) — из
    StaticHandler.
    """

    def do_GET(self):
        if is_api_path(self.path):
            APIHandler.do_GET(self)
        else:
            StaticHandler.do_GET(self)

    def do_POST(self):
        if is_api_path(self.path):
            APIHandler.do_POST(self)
        else:
            # POST в статический путь — не бывает: честный 404
            self._send_json({'error': 'Not found'}, status=404)

    def do_DELETE(self):
        if is_api_path(self.path):
            APIHandler.do_DELETE(self)
        else:
            self._send_json({'error': 'Not found'}, status=404)

    def end_headers(self):
        # Кэш-заголовки — только для статики: API-ответы управляют ими сами
        # (например, _send_binary ставит свой Cache-Control обложкам), и
        # второй заголовок от статики им только мешал бы.
        if is_api_path(self.path):
            BaseHTTPRequestHandler.end_headers(self)
        else:
            StaticHandler.end_headers(self)

    def log_message(self, format, *args):
        # API-запросы логируем все (они содержательные), статику — только ошибки
        if is_api_path(self.path):
            APIHandler.log_message(self, format, *args)
        else:
            StaticHandler.log_message(self, format, *args)


def local_ip():
    """Локальный IP машины — для подсказки «как открыть с телефона»."""
    try:
        import socket
        s = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
        s.connect(('8.8.8.8', 80))   # UDP: пакеты не уходят, адрес не важен
        ip = s.getsockname()[0]
        s.close()
        return ip
    except Exception:
        return '127.0.0.1'


def bind_server(host, port, allow_fallback):
    """Создаёт сервер на host:port. Возвращает (server, фактический_порт)
    или (None, None), если заняты все кандидаты.

    - port == 0: ОС сама выбирает свободный порт — занят быть не может;
    - allow_fallback: если port занят, пробуем port+1, port+2, …
      (локальный запуск: 8080 занят — встанем на 8081);
    - без fallback: только точный port — так нужно Docker, где healthcheck
      и маппинг портов рассчитаны на конкретный порт.
    """
    if port == 0:
        candidates = [0]
    elif allow_fallback:
        candidates = [port + i for i in range(PORT_FALLBACK_ATTEMPTS)]
    else:
        candidates = [port]

    for candidate in candidates:
        try:
            server = ThreadingHTTPServer((host, candidate), UnifiedHandler)
            # server_address[1] — фактический порт (важно при port=0)
            return server, server.server_address[1]
        except OSError:
            continue   # порт занят — пробуем следующего кандидата
    return None, None


def main():
    parser = argparse.ArgumentParser(description='BookHaven 3D — единый сервер (статика + API на одном порту)')
    parser.add_argument('--port', type=int, default=None,
                        help=f'порт сервера; без флага — {DEFAULT_PORT}, а если занят — '
                             f'{DEFAULT_PORT + 1}…{DEFAULT_PORT + PORT_FALLBACK_ATTEMPTS - 1}; '
                             '0 — свободный порт выбирает ОС. '
                             'Явный порт точен: занят = ошибка (так нужно Docker)')
    parser.add_argument('--host', default='0.0.0.0',
                        help='Адрес: 0.0.0.0 — доступ с других устройств в сети, '
                             '127.0.0.1 — только локально (для десктоп-обёрток)')
    parser.add_argument('--quiet', action='store_true', help='Не выводить логи запросов в терминал')
    args = parser.parse_args()

    global QUIET
    QUIET = args.quiet

    announce(f'BookHaven 3D — запуск сервера (pid {os.getpid()})')

    # Явный --port — точное попадание: Docker и скрипты рассчитывают на
    # конкретный порт (healthcheck, маппинг -p 9000:8080). Без --port —
    # дефолт с запасными: у пользователя 8080 может быть занят.
    requested = DEFAULT_PORT if args.port is None else args.port
    server, port = bind_server(args.host, requested, allow_fallback=args.port is None)

    if server is None:
        if args.port is None:
            announce(f'ОШИБКА: порты {requested}–{requested + PORT_FALLBACK_ATTEMPTS - 1} на {args.host} заняты.')
        else:
            announce(f'ОШИБКА: порт {requested} на {args.host} занят (порт указан явно — запасные не пробуем).')
        announce('Похоже, там уже работает другое приложение (или копия этого сервера).')
        announce('Укажите свободный порт:  python3 server.py --port 9000   (или --port 0 — выберет ОС)')
        raise SystemExit(1)

    if requested == 0:
        announce(f'ОС выделила свободный порт: {port}')
    elif port != requested:
        announce(f'Порт {requested} занят — открываюсь на следующем свободном: {port}')

    # Подсказка для открытия: снаружи — IP машины, локально — 127.0.0.1
    shown = '127.0.0.1' if args.host in ('127.0.0.1', 'localhost') else local_ip()
    announce(f'  Приложение: http://{shown}:{port}  (локально: http://127.0.0.1:{port})')
    announce('Готово. Нажмите Ctrl+C для остановки.')

    try:
        server.serve_forever()
    except KeyboardInterrupt:
        announce('Остановка сервера...')
        server.shutdown()
        announce('Готово.')


if __name__ == '__main__':
    main()