Initial snapshot before step 6 options.js split

2026-05-22 21:05:21 +02:00
commit f8e781f0e9
26 changed files with 9741 additions and 0 deletions
@@ -0,0 +1,79 @@
+# rclone-jav
+
+Brave extension that extracts JAV IDs from the active page and checks them against your local rc-jav library via a native-messaging Python host.
+
+> **Setup:** see [`INSTALL.md`](./INSTALL.md). This file documents how it works once installed.
+
+## Architecture
+
+```
+Brave tab title (e.g. "MILK-257")
+  ─► content/background script extracts ID
+  ─► chrome.runtime.connectNative("com.rcjav.host")
+  ─► rcjav-host.bat  →  rcjav-host.py
+  ─► python rc-jav.py --search MILK-257 --basic --no-color
+  ─► result back through the port
+  ─► popup / notification / badge
+```
+
+Long-lived port: Brave keeps the host process alive while the connection is open, so subsequent lookups don't pay Python startup cost.
+
+## Triggers (all available, enable any combination in Options)
+
+| Trigger | Behavior |
+|---|---|
+| **Auto-check every page load** | Fires `chrome.tabs.onUpdated`. Badge shows hit count or `?` when no JAV ID detected. Noisy. |
+| **Auto-check on known JAV sites** | Same as above but gated by host patterns (e.g. `*.javdb.com`). |
+| **Toolbar icon popup** | Click the icon → popup can run a check on the active tab. The Scan Behavior toggle gates popup auto-check. |
+| **Right-click context menu** | "rclone-jav: check this page". Shows a desktop notification. |
+| **Keyboard shortcut (Alt+J)** | Rebind at `brave://extensions/shortcuts`. |
+
+Enable them all to compare — they don't conflict.
+
+## ID extraction
+
+Uses site adapters, URL text, and the page title plus ID normalizers. Common title forms include:
+- `MILK-257` → `MILK-257`
+- `MILK257` → `MILK-257`
+- `Some site - MILK-257 [4K]` → `MILK-257`
+
+## Search behavior
+
+By default the extension passes `--quick` to rc-jav (single-ID live `rclone lsjson --include`, ~1–2s, fresh data, no cache). Uncheck **Use --quick mode** in options to use the cache (faster on warm cache, may be stale).
+
+## Files
+
+```
+manifest.json             MV3 manifest
+background.js             service worker, native-messaging port, triggers
+content.js                page extraction, element picker, and in-page overlays
+popup.html / .css / .js   click-the-icon UI
+options.html / .js        trigger toggles + known-site patterns
+icons/                    extension icons
+host/
+  rcjav-host.py           native messaging host (length-prefixed JSON)
+  rcjav-host.bat          shim so the manifest path is stable
+  install-host.ps1        writes the manifest into Brave's NM dir
+  register-host.bat       prompts for ID, calls install-host.ps1
+  com.rcjav.host.json     generated by install-host.ps1 (UTF-8 no BOM)
+  logs/                   host logs and delete audit log
+  state/                  scan progress state
+docs/
+  INSTALL.md              setup guide
+  README.md               this file
+  EXTENSION_ID.md         extension ID stability notes
+```
+
+## Security
+
+- The host manifest's `allowed_origins` is pinned to your extension ID. Only that extension can connect.
+- No network ports opened.
+- Host only spawns `python rc-jav.py …`; no shell, no arbitrary code execution.
+
+## Troubleshooting
+
+Quick reference — full troubleshooting in [`INSTALL.md`](./INSTALL.md#troubleshooting).
+
+- Badge `?` → no JAV ID in title.
+- Badge `!` → host error. Read `host\logs\rcjav-host-stderr.log`.
+- "host unreachable" → re-run `install-host.ps1`, fully restart Brave.