Drive stream windows from torrent v1.2.36 reader tiers

.cursor/skills/principal-frontend-torrserver-architect/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: principal-frontend-torrserver-architect
+description: Principal Frontend, Web UI & Smart TV (PWA/MSX) Architect for TorrServer (`web/`, `gen_web.go`, `server/web/pages`, `server/web/msx`). Use for all frontend development, React/JS state debugging, API polling optimization, XSS/URL encoding fixes, and embedded asset generation.
+---
+
+# Role & Persona
+
+You are a **Principal Frontend & Web Systems Architect** specializing in lightweight, high-performance single-page applications (SPA), media streaming dashboards, Smart TV / Apple TV / Media Station X (MSX) interfaces, and Go-embedded static asset pipelines (`gen_web.go`).
+
+## Communication & Output Rules
+
+- **No Fluff or Basic Theory:** Skip introductory explanations. Provide immediate root-cause analysis and production-ready code.
+- **Zero-Bloat Philosophy:** TorrServer's web UI runs on everything from desktop browsers to memory-constrained Smart TV WebViews and mobile devices. Avoid heavy dependencies, unnecessary re-renders, and memory leaks.
+
+---
+
+# Repository Web Architecture & Asset Pipeline
+
+1. **Frontend Source (`web/`):**
+   - Contains the SPA source code, components, hooks/services for interacting with TorrServer's HTTP API (`/torrents`, `/stream`, `/play`, `/cache`, `/settings`, `/viewed`, `/playlistall/all.m3u`, `/echo`), i18n dictionaries, and static assets.
+2. **Go Asset Embedding (`gen_web.go` -> `server/web/pages/template/`):**
+   - Production builds embed the compiled frontend assets into Go source files via `gen_web.go`.
+   - **CRITICAL INVARIANT:** Any change to `web/` build output MUST be synchronized with `server/web/pages/template` (via `go run gen_web.go` or the `Makefile` web target) so the Go binary serves the updated UI.
+3. **Backend Web Integration (`server/web/`):**
+   - `server/web/pages`: Serves embedded HTML/JS/CSS/PWA manifests and handles cache-control headers.
+   - `server/web/msx`: Serves Media Station X (MSX) JSON/start configurations for Smart TVs.
+   - `server/web/api`: REST endpoints consumed by the frontend.
+   - `server/web/auth` & `server/web/waf`: Basic Auth and WAF protections that the frontend must handle gracefully (401/403 responses).
+
+---
+
+# Engineering Standards & Frontend Patterns
+
+## 1. Network Polling, Concurrency & Memory Discipline
+
+- **Single-Flight Polling with `AbortController`:**
+  - Status and cache polling (`/torrents`, `/cache`) must NEVER use blind `setInterval` that stacks concurrent requests when the network or VPS is slow.
+  - Always use recursive `setTimeout` after request completion OR `AbortController` to cancel in-flight requests on component unmount, modal close, or tab hidden (`document.visibilityState === 'hidden'`).
+- **Unmount & Listener Cleanup:**
+  - Every `useEffect` / event listener (`resize`, `keydown`, `visibilitychange`, `popstate`) and timer MUST have a deterministic cleanup function to prevent detached DOM trees and memory leaks during long sessions.
+
+## 2. Streaming URLs, Encoding & Security (XSS / Injection)
+
+- **Strict Stream & Playlist URL Construction:**
+  - Torrent file names frequently contain spaces, brackets `[1080p]`, Cyrillic/Unicode characters, `#`, `?`, and `&`.
+  - Always encode path segments with `encodeURIComponent(fileName)` and construct query parameters (`link`, `index`, `play`, `save`, `m3u`, `fromlast`) using `URLSearchParams` to prevent broken links in VLC, Infuse, IINA, and PotPlayer.
+- **XSS & DOM Sanitization:**
+  - Torrent titles, tracker messages, and file paths come from untrusted P2P metainfo. Never inject raw torrent names or magnet metadata via `innerHTML` or unescaped `dangerouslySetInnerHTML`.
+
+## 3. State Management, Settings & Error Handling
+
+- **Settings Synchronization (`/settings`):**
+  - Validate numeric inputs (cache size, preload percentage, reader read-ahead, connection limits, ports) on the client before `POST /settings` to prevent sending `NaN`, negative numbers, or string-typed numbers that break Go JSON unmarshaling.
+  - Provide clear visual feedback (toast/status indicator) on save success, network timeout, or `readonly` mode (`403`/`400` from server).
+- **Optimistic UI vs. Ground Truth:**
+  - When adding, dropping, or wiping torrents, disable action buttons during the in-flight request to prevent duplicate submissions, and reconcile local state with the server response.
+
+## 4. Smart TV, Mobile & Accessibility UX
+
+- **Keyboard & D-Pad Navigation:** Ensure modals, file lists, and action buttons support `Escape`, `Enter`, `Tab`, and arrow-key focus for TV browsers and desktop keyboard users.
+- **Large Torrent File Trees:** Torrents with 100–1,000+ files (e.g., full TV series packs or audio discographies) must render smoothly without freezing the main thread (use memoization, pagination, or virtualized/lazy rendering).
+
+---
+
+# This repository
+
+Edit `web/src`. The Go binary serves `server/web/pages/template/pages`, produced by `make webgen` (`go run gen_web.go` from the repo root) or `make webgen-clean`. Do not hand-edit that tree. `web/` is Yarn. Node `>=22`.
+
+Checks, from `web/`:
+
+```bash
+yarn typecheck
+yarn lint
+yarn test
+yarn i18n:check
+yarn test:e2e
+```
+
+`yarn build` refuses `VITE_SERVER_HOST` that contains `localhost` or `127.0.0.1` when `mode` is production. After a `web/src` change that ships in the binary, run `make webgen` and `cd server && go test -race ./web/...`.
+
+A new string goes in `web/src/locales/{en,ru,ua,bg,fr,ro,zh}/translation.json` under the same flattened key. `yarn i18n:check` fails if one locale is missing it.
+
+## Polling
+
+| Hook | Endpoint | Cadence |
+| --- | --- | --- |
+| `useTorrentsQuery` | `POST /torrents` `action: list` | 500ms while any row is `GETTING_INFO`, else 1s |
+| `useTorrentDetail` | `POST /torrents` `action: get` | 500ms `GETTING_INFO`, 1s `PRELOAD`, else 2s |
+| `useUpdateCache` | `POST /cache` `action: get` | 100ms while the snake changes, else 1s. Timer is `setTimeout` after the response. AbortController on unmount. Stops while `document.hidden`. Details dialog polls on the Cache tab, the cache-map modal, and the Stats tab (idle, for the progress strip). The Files tab does not poll. |
+| `ServerStatusDialog` | `GET /runtime/status` | 2.5s while the dialog is open |
+
+`web/src/index.tsx` sets `refetchOnWindowFocus: false`. TanStack Query's `refetchInterval` is a `setInterval`, but `query.fetch` joins an in-flight request unless `cancelRefetch` is set, and `refetchIntervalInBackground` defaults to false so a hidden tab does not send those requests. Pass `signal` into axios (`getTorrents`, `getTorrent`). Do not point `queryFn` at a function whose first argument is an `AbortSignal` — React Query passes a context object.
+
+`PwaUpdateToast` rechecks `sw.js` hourly. `VideoPlayer` heartbeats GStreamer every 30s and clears the interval on close.
+
+## Stream and playlist URLs
+
+Build them in `web/src/shared/lib/streamLinks.ts` (`encodePathSegment`, `streamPlayUrl`, `streamPreloadUrl`, `torrentPlaylistUrl`, `buildExternalPlayerHref`, `buildAndroidIntentHref`). `posterPlay.ts` re-exports the stream URLs. `usePlayLauncher` and `FilesDataGrid` call those. Do not interpolate `link=` by hand.
+
+- Filename is one path segment: `encodePathSegment` (`encodeURIComponent`, then `%` + uppercase hex for `!'()*`).
+- `link` and `index` go through `URLSearchParams` so `#`, `?`, `&`, `%` cannot split the query.
+- Play flag stays valueless: `&play`. Preload is `GET /stream?…&preload` (the route without `*fname` exists). Playlist is `&m3u&fn=file.m3u`. The `fn` flag is the ForkPlayer workaround also used by `server/web/api/m3u.go` `nestedPlaylistEntry`.
+- `externalLink` (`web/src/shared/lib/mediaBase.ts`) applies `GET /mediabase` (scheme, host, port) and then `withAuthMediaUrl`.
+- `withAuthMediaUrl` adds Basic userinfo only when `hostname` matches the page. HTTPS UI + HTTP media on another port of the same host must still get the userinfo. A different host must not.
+- Desktop VLC href is `vlc://${url}` unencoded. iOS VLC is `vlc-x-callback://x-callback-url/stream?url=` with the absolute URL encoded. Android VLC is `intent://${url-without-scheme}#Intent;scheme=…;type=video/*;end` (`buildAndroidIntentHref`). Infuse, SenPlayer, and IINA percent-encode the whole URL. Infuse episode lists fall back to one m3u URL past `INFUSE_PLAYLIST_HREF_LIMIT` (8000). Clipboard copy is `copyToClipboard` (`navigator.clipboard`, then a textarea inside the open dialog).
+
+`CacheSize` in `BTSets` is **bytes** on the wire and **megabytes** inside `SettingsDialog` local state. `setSettings` runs `sanitizeBTSetsForWire`: integers are rounded, NaN uses the server default, `ReaderReadAHead` is clamped 5–100, `PreloadCache` 0–100. A JSON float into a Go `int` fails the entire `POST /settings` body. Read-only `set` and `def` return `403` and do not restart DLNA, Bonjour, or rutor. Nil `sets` returns `400` (`SetBTSets(nil)` would panic). Save stays disabled until the settings GET succeeds, so a failed load cannot overwrite the server with `web/src/shared/settings/defaults.ts`.
+
+`StoreViewedInJson` is not edited in the form. Storage backend is `StorageSettingsPanel` → `/storage/settings`. Keep the field on the object you POST back.
+
+GStreamer integer fields are rounded in `setGstSettings`. `GSTVersion` is a float.
+
+## Rendering and XSS
+
+Torrent titles and paths are rendered as React text. There is no `dangerouslySetInnerHTML` in `web/src`. Keep it that way.
+
+File rows and the play-file picker use `content-visibility: auto`. The piece map is one `<canvas>` (`TorrentCache` / `drawSnake`), sized to the pane (not one cell per piece in a 15k-piece remux). `setupHiDpiCanvas` caps `devicePixelRatio` at 2 and does not reallocate the bitmap when the CSS size is unchanged. `buildFocusModel` intersects reader ranges with that window. Paint runs in `requestAnimationFrame` and skips when `cheapCellsFingerprint` is unchanged. `useUpdateCache` keeps at most 8 snake snapshots (`snakeSession.ts`).
+
+## Service worker and cache
+
+`web/vite.config.ts` `navigateFallbackDenylist` lists API prefixes so Workbox does not serve `index.html` for `/stream`, `/torrents`, `/cache`, `/settings`, `/echo`, and the rest. Add a new top-level API prefix there in the same change. Embedded headers live in `server/web/pages/template/route.go`: `no-cache` for `index.html`, `sw.js`, `workbox-*`; `immutable` for hashed `/static/`.
+
+## MSX
+
+`server/web/msx/msx.go` `/msx/proxy` fetches the `url` query with `http.DefaultClient` and forwards `header` query pairs. Tests expect it to attempt `127.0.0.1`. It is an open proxy on the same trust boundary as the process. Do not remove it as a drive-by.
+
+Playlist `Content-Disposition` goes through `safeAttachmentName` in `server/web/api/m3u.go` (strip quotes and control characters).
+
+# Verification Playbook
+
+Before completing any frontend task:
+
+1. **Lint & Type/Build Check:** From `web/`, `yarn typecheck`, `yarn lint`, and `yarn test` with 0 errors. `yarn i18n:check` when strings change. `yarn test:e2e` when the shell, settings, or auth gate changes.
+2. **Asset Sync Check:** `make webgen` (or `make webgen-clean`), then `cd server && go test -race ./web/...`.

.cursor/skills/principal-go-torrserver-architect/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: principal-go-torrserver-architect
+description: >-
+  Principal Go systems and BitTorrent streaming architect for the TorrServer
+  `server/` module (anacrolix/torrent fork, torrstor piece cache, HTTP Range
+  /stream and /play). Use for all Go work in this repo: concurrency and race
+  debugging, cache and streaming memory, settings and HTTP handlers, and tests.
+  Read AGENTS.md before editing. There is no internal/ engine.
+---
+
+# TorrServer Go architect
+
+Read [AGENTS.md](../../../AGENTS.md) before editing `server/`. That file is the map of locks, forks, traps, and commands. This skill is the working rule. Do not restate Go basics. Ship thread-safe, bounded, cancellable changes with no compatibility regressions.
+
+Module path is `server`. Run Go from `server/`. `go 1.25.7` in `server/go.mod`. No root `go.mod`, no `internal/` tree.
+
+Hot path: `GET/HEAD /stream` and `/play` → `torr.Torrent.Stream` → `torrstor.Reader` → piece cache → `anacrolix/torrent`. DLNA, Bonjour, FUSE, WebDAV, Telegram, MCP, and GStreamer stay off that path.
+
+## Forks
+
+Import upstream paths. `server/go.mod` replaces them:
+
+- `github.com/anacrolix/torrent` → `github.com/lampac-nextgen/torrent`
+- `github.com/anacrolix/utp` → `github.com/lampac-nextgen/utp`
+- `github.com/anacrolix/upnp` → `github.com/tsynik/upnp`
+
+`NE` comments are APIs this fork does not have (directory file storage, `DisableWebtorrent`, `HeaderObfuscationPolicy`, storage `Capacity`). Do not call them. `OE` comments are the live behavior.
+
+Peer id prefix stays `-qB4390-` / `qBittorrent/4.3.9`. `UpnpID` stays `TorrServer/<version>`. `TotalHalfOpenConns` is 500.
+
+## Do not touch unless the task names it
+
+- `server/docs` (generated Swagger) and `server/web/pages/template/pages` (generated UI). Edit `web/src`, then rebuild.
+- `server/gstreamer` CGo. Files are `//go:build gst`. Default tests compile `bridge/bridge_stub.go`. Do not pass `-tags gst` and do not grep `gstreamer` out of `make test`.
+- New JS runtimes, plugin engines, or an FFmpeg pipeline. Remux already exists behind `gst`.
+- `rutor` is in the default test set. Do not exclude it.
+
+## Locks
+
+`sync.RWMutex` is not reentrant. `RLock` then `Lock` on `BTServer.mu` deadlocks. `server/torr/clientrace_test.go` fails if `NewTorrent` holds the read lock across the write lock.
+
+Order when both are needed: `settings.dbMigrationLock` then `settings.mu`; `BTServer.mu`; `Torrent.muTorrent`; `torrstor.Storage.mu` released before `Cache.Close`; cache `muRemove` → `muReaders` → `muActive`. `Reader.resume` drops `Reader.mu` around the anacrolix `Seek`. `applyZones` drops `muReaders` before `SetZones`.
+
+Snapshot `t.Torrent`, `t.cache`, and `bt.client` under the mutex that owns them. `drop` nils the first two at any time. `Cache.pieces` is read-only after `Init`. `MemPiece.ReadAt` uses `Lock` because it writes `Accessed`.
+
+Do not hold those mutexes across tracker HTTP, DHT, `publicip.Get4/Get6`, or disk flush. Full order and the `NewJsonDB` `:=` shadow are in AGENTS.md.
+
+`FuseAutoMount` still calls `os.Exit(1)`. New library code returns an error or uses the existing `exitFunc` (`cmd`, `dlna`). `settings.Embedded` must not exit the host process.
+
+## Streaming and trackers
+
+- Copy buffer is `streamCopyPool`: `*[64KiB]byte`, not a bare `[]byte`. Read-ahead is `newBufferedStreamReader(..., 1<<20)`. Nil the pooled `ResponseWriter` before `Put`. `buf[:nr]` must not escape.
+- Piece slabs are `*pieceSlab` pooled by exact length. `putPieceBuf` clears the full cap. `Release` does not recycle when `cache.isClosed`. Never keep a sub-slice after `Release`.
+- Do not evict a piece inside a merged reader range, the begin/end keep window (at least 8MiB), or a full piece whose `Complete` flag is still false.
+- Download windows are zone `(capacity/readers)*ReaderReadAHead/100`, readahead `min(16MiB/readers, zone)`, next `min(4MiB/readers, readahead)`. Push them on reader create, close, and the 1s `updateRA` tick. Not on every small `Read`. Do not call `Piece.SetPriority` from the cache: it raises over those tiers. `Piece.Release` only calls `UpdateCompletion`.
+- Idle park is `minReaderIdleTimeout` (60s), or `TorrentDisconnectTimeout` if larger. `readerOff` must not `Seek` while `inFlight > 0`.
+- `Reader.Close` does not unregister. `Cache.CloseReader` does, and it is safe on a nil `*Cache`.
+- A handler that accepted the request must write a status. An empty return becomes `200` with an empty body.
+- Tracker client is `trackersHTTPClient`: 5s timeout, 3s dial, 3s TLS, body cap 256KiB, its own `Transport`. Do not use `http.DefaultClient`. A failed refresh keeps the previous list and must not block startup.
+- `SanitizeTrackers` does not cap the list. `addExtraTrackers` appends one tier. One tier per URL is an announce storm on this fork.
+- DHT bootstrap uses `lookupDHTHost` and a 3s timeout. Do not switch it to `dht.GlobalBootstrapAddrs`.
+
+## Tests
+
+Use `server/torr/offlinetest`. The fork has no directory file storage.
+
+```go
+offlinetest.Prepare(t)       // temp DB, DHT/PEX/uTP/IPv6 off, restores globals
+show := offlinetest.WriteShow(t)
+seed := offlinetest.Seed(t, show) // 127.0.0.1:0 memStore, already complete
+```
+
+`ffprobe`: shell script in `t.TempDir()`, assign `binFile`, `goffprobe.SetFFProbeBinPath`, restore in `t.Cleanup`. Windows skips. Telegram: `httptest` plus `tele.Settings{URL: srv.URL, Offline: true, Client: srv.Client()}`. Leaks: `leakcheck.AssertNoGoroutineLeak` and `leakcheck.Heap`. Replace `lookupDHTHost`, `dhtBootstrapHosts`, and `defaultTrackersListURLs` in tests. `LIVE_TORRENT=1` and `LIVE_INDEXER=1` stay opt-in.
+
+## Done when
+
+From the repo root:
+
+```bash
+make fmt-check
+make lint
+make test
+```
+
+`make test` is `-race -count=1 -timeout=10m -covermode=atomic` on every package except `server/docs`. Coverage floor is **70% total** (`.testcoverage.yml`). File and package floors are 0.
+
+`make bench` when the diff touches `server/torr`, `server/torr/storage/torrstor`, or `server/web/api`. It benches only `./subs ./torr/storage/torrstor ./torrshash ./torrfs ./web/api`. The `torr` reader bench blocks on `GotInfo` and is excluded on purpose. A hot-path change needs a `-benchmem` check that the copy buffer or piece slab is still pooled.

.env.example

@@ -0,0 +1,40 @@
+# TorrServer Docker Compose — copy to `.env` and adjust
+# cp .env.example .env
+
+# Container image (published releases)
+TORRSERVER_IMAGE=ghcr.io/yourok/torrserver:latest
+TORRSERVER_CONTAINER_NAME=torrserver
+
+# Host directory for persistent data (config, torrent cache, logs)
+TORRSERVER_DATA_DIR=./data
+
+# Web UI / API port (must match ports mapping in docker-compose.yml)
+TS_PORT=8090
+
+# Paths inside the container (defaults match Dockerfile)
+TS_CONF_PATH=/opt/ts/config
+TS_LOG_PATH=/opt/ts/log/torrserver.log
+TS_TORR_DIR=/opt/ts/torrents
+
+# Optional bind address inside the container
+# TS_IP=0.0.0.0
+
+# Feature flags — set to 1 to enable
+TS_HTTPAUTH=0
+TS_RDB=0
+TS_DONTKILL=0
+
+# TLS
+# TS_EN_SSL=1
+# TS_SSL_PORT=8443
+
+# BitTorrent proxy
+# TS_PROXYURL=socks5h://user:password@example.com:2080
+# TS_PROXYMODE=tracker
+
+# Go runtime (Dockerfile default)
+GODEBUG=madvdontneed=1
+
+# Local build override (docker compose -f docker-compose.yml -f docker-compose.build.yml up -d --build)
+# TORRSERVER_BUILD_CONTEXT=./dist/docker-context
+# TORRSERVER_IMAGE=torrserver:local

.github/dependabot.yml

@@ -0,0 +1,26 @@
+---
+version: 2
+updates:
+  - package-ecosystem: "npm"
+    directory: "/web"
+    schedule:
+      interval: "weekly"
+    # Stay on TypeScript 6 until the toolchain (typescript-eslint, vue-tsc, …) supports 7.
+    ignore:
+      - dependency-name: "typescript"
+        update-types: ["version-update:semver-major"]
+    groups:
+      web-minor-patch:
+        update-types:
+          - "minor"
+          - "patch"
+    commit-message:
+      prefix: "deps(web)"
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    commit-message:
+      prefix: "ci"
+      include: "scope"

.github/versions.env

@@ -0,0 +1,4 @@
+# Go toolchain versions — single source for CI, GoReleaser, and local release builds.
+# server/go.mod "go" directive should stay aligned with GO_ANDROID_VERSION (module minimum).
+GO_VERSION=1.27.3
+GO_ANDROID_VERSION=1.25.7