Metadata-Version: 2.5
Name: remandochka
Version: 0.0.8
Summary: RM (ReMandochka) — Высокопроизводительная библиотека хукинга, обхода защит ART/R8 и KDL v2 рантайма для плагинов exteraGram
Author: swagnonher
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# RM (ReMandochka) v0.0.8 — Библиотека хукинга, обхода защит ART/R8, UI и KDL v2 рантайма
### (PyPI: `remandochka` | Python import: `import rm` или `import remandochka`)

**ReMandochka (RM)** — высокопроизводительная инструментальная библиотека для разработчиков плагинов **exteraGram**, решающая проблемы с защитами, барьерами Android Runtime (ART), компилятора R8, предоставляющая архитектурный каркас UI компонентов, декларативный DSL построитель настроек на KDL/Python с поддержкой Custom View, встроенный ультра-быстрый парсер документов **KDL v2 (2.0.0)** и безопасную Java-рефлексию.

- **PyPI**: `remandochka` (установка: `pip install remandochka`).
- **Сборщик**: Hatchling (PEP 621 / `pyproject.toml`).
- **Архитектура**: 1 единственный `__init__.py` на всю библиотеку без лишнего бойлерплейта.
- **Производительность**: оптимизирована под мульти-плагинный сценарий (кэширование дескрипторов полей, JNI-классов, версий, memoization KDL, мультиплексирование хуков).
- **Импорт в плагинах**: `import rm` или `import remandochka`.

---

## ⚡ Структура библиотеки (`src/`)

- **`remandochka.core`**:
  - `rm.parse_kdl(text)` / `rm.dumps_kdl(doc)`: моментальный парсер KDL 2.0.0 (~100 микросекунд с LRU-кэшем).
  - `rm.is_dev_mode()`, `rm.dev_log(plugin, msg)`: Zero Log Spam логирование (TTL-кэшировано).
  - `rm.get_app_version()`: автоопределение версии клиента Telegram / exteraGram.
  - `rm.get_field()`, `rm.set_field()`, `rm.get_java_class()`: безопасная Java-рефлексия с кэшированием `Field` и JNI-классов.
- **`remandochka.bypass`**:
  - `rm.Bypass(plugin)`: фасад управления хуками с защитой от дублирования и безопасной выгрузкой плагинов.
  - `@bypass.hook("ClassName", "methodName")`: декоратор для классов `MethodHook` или функций.
  - Внешняя база правил: `remandochka/resources/rules.jsonl`.
- **`remandochka.ui`**:
  - **`settings`**: `build_settings(kdl_text, context=self)` — моментальная сборка настроек exteraGram из KDL с поддержкой Custom View.
  - **`views`**: `View`, `SheetView`, `DialogView`, `PanelView`.
  - **`cells`**: `Cell`, `HeaderCell`, `TextCell`, `ButtonCell`, `SwitchCell`, `SelectorCell`, `InputCell`, `DividerCell`, `CustomCell` с методами `.to_setting()` и `.to_kdl()`.
  - **`fragment`**: `BaseFragment`, `SettingsFragment` (с методом `.load_kdl()`), `TabFragment`.
  - **`layout`**: `LinearLayout`, `FrameLayout`, `ScrollLayout`, `StackLayout`.
  - **`components`**: `BadgeComponent`, `AvatarComponent`, `ProgressBarComponent`, `SearchBarComponent`, `DividerComponent`, `IconComponent`, `ActionSheetComponent`.

---

## 🛠️ Декларативные настройки плагина на чистом KDL

Плагин может полностью описать свои настройки на чистом KDL — библиотека автоматически преобразует их в нативные элементы exteraGram, привяжет коллбэки и внедрит Custom View:

```python
from base_plugin import BasePlugin
import rm

class MyPlugin(BasePlugin):
    def create_settings(self):
        # Вся конфигурация экрана настроек в 1 вызов KDL!
        return rm.build_settings("""
            header "Основные параметры"
            switch key="enabled" text="Включить плагин" default=#true subtext="Активирует фоновую работу" icon="msg_permissions" on_change="on_toggle"
            input key="api_key" text="API Токен" default="" hint="Вставьте секретный ключ" icon="msg_link"
            selector key="quality" text="Качество" default=1 icon="msg_media" {
                item "720p"
                item "1080p"
                item "4K"
            }
            divider text="Интерфейс"
            // ОБЯЗАТЕЛЬНО С КАСТОМОМ: встраивает произвольный нативный View плагина!
            custom key="banner" view="create_banner_widget"
            divider
            button text="Проверить соединение" icon="msg_retry" action="on_test_connection"
        """, context=self)

    def on_toggle(self, val: bool):
        rm.dev_log(self, f"Переключатель: {val}")

    def on_test_connection(self, view=None):
        rm.dev_log(self, "Тест соединения вызван!")

    def create_banner_widget(self, context=None):
        # Возвращает любой нативный Android View
        return my_native_android_view
```

---

## 🛡️ Модуль обхода блокировок ART/R8 (`rm.Bypass`)

```python
from base_plugin import BasePlugin, MethodHook
import rm

class MyPlugin(BasePlugin):
    def on_plugin_load(self):
        self.bypass = rm.Bypass(self)

        @self.bypass.hook("InstallPluginBottomSheet", "<init>")
        class CtorHook(MethodHook):
            def before_hooked_method(self, param):
                # param.args[2] — PluginInstallParams
                param.args[2].setTrusted(True)

            def after_hooked_method(self, param):
                sheet = param.thisObject # живой экземпляр шторки

        @self.bypass.hook("InstallPluginBottomSheet", "applyButtonState")
        class ButtonHook(MethodHook):
            def after_hooked_method(self, param):
                sheet = param.thisObject
                # кастомизация кнопки

        self.bypass.install()

    def on_plugin_unload(self):
        self.bypass.uninstall()
```

---

## 📁 Пример готового плагина

В папке `examples/sample_plugin/` расположен рабочий пример:
- `metainfo.json`: манифест плагина с зависимостью `remandochka 0.0.7`.
- `main.py`: реализация `create_settings` через KDL, перехвата хуков и `Custom View`.
- `settings.kdl`: внешняя KDL-декларация всех элементов настроек.

---

## 🔇 Интеллектуальное логирование (Zero Log Spam)

Библиотека не засоряет логи приложения:
* Логи выводятся **ТОЛЬКО** тогда, когда в настройках плагин-системы включен **Режим разработчика (`rm.is_dev_mode() == True`)**.
* При выключенном режиме разработчика библиотека работает в режиме **полной тишины**.

---

## 📦 Спецификация для плагинов exteraGram

- В файлах `.plugin`:
  ```python
  __requirements__ = ["remandochka 0.0.8"]
  ```
- В архивах `.elyx` (`metainfo.json`):
  ```json
  "requirements": "remandochka 0.0.8"
  ```
