phimpal-tv 0.2.0

package/README.md

@@ -0,0 +1,113 @@
+# phimpal-tv
+
+D-pad navigation for [phimpal.com](https://phimpal.com/) on a Samsung TV, shipped as a
+**TizenBrew site-modification module**. The Samsung browser's pointer is replaced by
+block-to-block navigation with the remote: focus rings, a card popup, a control-bar mode
+and a preview-based seek that never stutters the stream.
+
+| File | Role |
+|---|---|
+| `phimpal-tv.user.js` | **The source.** Desktop test build (Tampermonkey), keyboard stands in for the remote |
+| `mod.js` | Generated TV build injected by TizenBrew — do not edit by hand |
+| `build.js` | Derives `mod.js` from the userscript (`npm run build`) |
+| `package.json` | TizenBrew manifest |
+| `SPECS.md` | Site analysis, key map, mode state machine, algorithms |
+
+## Remote keys
+
+| Button | Everywhere | On the player |
+|---|---|---|
+| ↑ ↓ ← → | move the focus ring between blocks | ←/→ open the seek cursor, ↓ the control bar |
+| OK | open the focused item | fullscreen, then play/pause; commits a seek |
+| Return | back / close a menu / exit fullscreen | |
+| Play/Pause | direct **Xem** on a focused card | play/pause |
+| Ch ▲ / ▼ | previous / next row | ±5 min in the seek cursor |
+
+Volume, Home and the app shortcuts stay with the TV. Colour keys are not used —
+on the Frame's remote they only exist behind the `123` keypad.
+
+Two behaviours worth knowing:
+
+- **Seeking never jumps immediately.** ←/→ move a preview cursor along the red timeline
+  with the site's own thumbnail; the step accelerates (10 s → 30 s → 1 min → 5 min).
+  OK commits, Return cancels — nothing is re-buffered until you confirm.
+- **Cards open their popup on focus**, exactly like the mouse hover: OK opens the title
+  page, ↓ then OK plays straight away.
+
+## Install on the TV
+
+1. **Install TizenBrew** on the Frame — follow the
+   [official guide](https://github.com/reisxd/TizenBrew/blob/main/docs/README.md)
+   (developer mode + TizenBrew Installer). Nothing here works without it.
+
+2. **Publish this module to npm** — TizenBrew installs modules as npm packages:
+
+   ```bash
+   cd phimpal-tizen
+   npm run build          # regenerates mod.js from the userscript
+   npm login
+   npm publish --access public
+   ```
+
+   The package name is `phimpal-tv` (change `name` in `package.json` if it is taken,
+   e.g. `@yourname/phimpal-tv`).
+
+3. **Add it in TizenBrew** → module manager → add an NPM module → type the package name
+   → launch it. TizenBrew opens `https://phimpal.com/`, injects `mod.js` and registers
+   the media/channel keys listed in `package.json`.
+
+4. **First run: log in.** The site is account-gated. Focus the email field, press OK, and
+   the TV's on-screen keyboard appears; Return leaves the field. The session cookie
+   persists in the webview, so this is a one-time chore.
+
+### Updating
+
+Bump `version` in `package.json`, `npm run build`, `npm publish`, then update the module
+in TizenBrew.
+
+## Desktop testing (before touching the TV)
+
+Install `phimpal-tv.user.js` in Violentmonkey/Tampermonkey and open phimpal.com. The
+keyboard emulates the remote:
+
+| Keyboard | Remote |
+|---|---|
+| Arrows / Enter | D-pad / OK |
+| Esc or Backspace | Return |
+| Space | Play/Pause |
+| PageUp / PageDown | Ch ▲ / ▼ |
+
+A badge in the top-right shows the current mode and the last key code. In the TV build
+the badge is off; enable it on the TV by running `localStorage['tv-debug'] = '1'` once
+(TizenBrew's dev console) and reloading.
+
+## What the TV build changes
+
+`build.js` only flips a few switches, so both builds share one engine:
+
+- keyboard emulation off — only real remote codes are accepted;
+- the debug badge is off unless `tv-debug` is set;
+- the pointer is hidden;
+- the keys from `package.json` are also registered defensively if the Tizen API is reachable.
+
+Three TV-specific behaviours live in the engine itself:
+
+- **Return on the home page is not swallowed**, so TizenBrew can close the module.
+  Anywhere else it means back / close.
+- **Fullscreen has a fallback**: if the webview refuses `requestFullscreen`, the player is
+  stretched over the viewport with CSS instead (header and footer hidden).
+- **Hover menus are forced visible.** The avatar menu is mounted on `mouseenter` but the
+  site fades it in only while the element really matches `:hover`, which never happens
+  with a remote — so the module reveals it itself.
+
+## Known limits
+
+- The per-track timing button (clock icon) in the subtitle panel is not reachable with the
+  D-pad: it sits inside a track row and would trap horizontal moves.
+- The hero row auto-rotates; if it moves under the focus, the focus jumps to the first
+  visible card of that row.
+- Selectors follow the site. Svelte's hashed classes are never used, but a redesign of the
+  cards, the carousels or the player would need a pass over `SPECS.md`.
+- Tizen's WebKit is older than desktop Chrome; the engine sticks to ES5-compatible syntax
+  in spirit but does use `const`/arrow functions/template literals, which Tizen 5.5+
+  (2020 Frame and newer) supports. For a 2017–2019 set, transpile before publishing.

package/SPECS.md

@@ -0,0 +1,342 @@
+# phimpal-tv — Navigation specs
+
+Remote-friendly (D-pad) navigation layer for https://phimpal.com, to be shipped
+as a TizenBrew *mod* module for a Samsung The Frame TV. Phase 1 is a userscript
+tested on a desktop browser with the keyboard emulating the remote.
+
+## 1. Target site facts (inspected 2026-09-04)
+
+| Item | Finding |
+|---|---|
+| Framework | SvelteKit SPA, Tailwind v4 + Skeleton UI, `<html class="dark">` |
+| Auth | Login required (`/` → `/auth/login`). Cookie session, persists in the webview. |
+| Routing | Client-side, except the play link (`data-sveltekit-reload`) which is a full page load `/api/play/:id` → 302 → `/watch/:id` |
+| Class names | `svelte-xxxx` hashes change per build → never used. Only Tailwind utilities, ARIA, hrefs and Video.js classes. |
+| Player | Video.js v8 (`.video-js`, `el.player` API), same-origin `<video class="vjs-tech">`, HLS blob, no iframe. Plugins: `videojs-hotkeys`, `vjs-seek-buttons` (±5 s). Autoplays windowed under a 64 px fixed header. |
+
+### Pages
+
+| Page | Route | Blocks |
+|---|---|---|
+| Home | `/` | fixed header (logo, `/top`, `/browse?type=movie`, `/browse?type=show`, `/faq`, `/search`, avatar menu); filter `<select>`s; N horizontal carousels of cards |
+| Browse / Top | `/browse?…`, `/top` | filters + card grid/carousels |
+| Search | `/search` | one `input.input` (autofocus) + result cards |
+| Title (movie) | `/title/:slug~:id` | `a[href^="/api/play/"]` "XEM PHIM", bookmark button, year/country/genre links, cast carousel, trailer, similar titles |
+| Title (show) | same | `<select>` season, `<select>` episode, "Xem" button, "Đã xem" toggle, rest as movie |
+| Watch | `/watch/:id` | Video.js player, control bar buttons, "Kích hoạt VIP mode", "Tab Song ngữ", comment form ("Gửi"), back-link to title |
+
+### Card anatomy (`div.group.relative`)
+
+```
+div.group
+ ├─ a[href^="/title/"] .group-hover:invisible      ← poster (visible)
+ └─ div.hidden.group-hover:block  (-m-5, z-10)      ← popup, display:none until :hover
+     ├─ a[href^="/title/"]  backdrop image
+     ├─ a[href^="/title/"]  title + synopsis
+     └─ a[href^="/api/play/"] "Xem"                  ← direct to watch page
+```
+
+Mouse semantics to reproduce: click anywhere on the card → title page;
+click "Xem" → watch page.
+
+### Carousel anatomy
+
+```
+div.container            ← ONE container for all rows of the page
+ └─ div.overflow-x-clip  ← one per row
+     └─ div.relative
+         ├─ div.flex[style*="--item-w"][style*="translateX"]   ← track, paginated by translateX
+         │   └─ div.shrink-0 > div.group  (× N, most off-screen)
+         └─ div.absolute (arrows)
+             ├─ button[aria-label="Previous"]  (opacity-0 on first page)
+             └─ button[aria-label="Next"]
+```
+
+`overflow-x: clip` → `scrollIntoView` is useless. Paging is done by clicking
+Previous / Next **found inside the row's own `.overflow-x-clip`** (searching the
+shared container would always hit the first row's arrows). A page shifts by
+`visible − 1` cards, so pages overlap by one card. Hero row ("Phim đề cử")
+auto-rotates on a timer.
+
+### Subtitle panel (custom Video.js plugin)
+
+The control-bar button `.vjs-subtitle-manager-btn` toggles
+`.vjs-subtitle-panel.is-open`, an absolutely-positioned panel inside `.video-js`:
+
+```
+.vjs-subtitle-panel.is-open
+ ├─ .vjs-sp-header > .vjs-sp-tabs > .vjs-sp-tab[data-tab=single|dual|filters]
+ ├─ .vjs-sp-body
+ │   ├─ .vjs-sp-pane[data-pane=single].active > #vjs-single-list > .vjs-sp-track-item
+ │   │                                              (.selected marks the active track,
+ │   │                                               .vjs-sp-shift-btn = timing offset)
+ │   ├─ .vjs-sp-pane[data-pane=dual]  > .vjs-sp-dual-grid > 2 × .vjs-sp-track-list
+ │   └─ .vjs-sp-pane[data-pane=filters] > .vjs-sp-filter-row > .vjs-sp-topbottom-label
+ └─ .vjs-sp-footer > .vjs-sp-caption-btn ("Cài đặt")
+```
+
+Everything is plain `<div>` with no ARIA and no `tabindex`, so the parts are
+listed explicitly in `SP_CAND`. Escape does **not** close the panel: closing
+means clicking the control-bar button again (or clicking outside). Picking a
+track in the single pane closes the panel by itself. The panel animates its
+opacity, so the entry point polls until its items are measurable.
+
+### Header avatar menu (hover-driven)
+
+`header button[aria-haspopup="menu"]` opens `div[role="menu"][aria-label="Options"]`
+(fixed, z-9999) on **mouseenter** and closes it on **mouseleave** of the trigger
+or the menu; `click()` does nothing. The script fakes the mouse: focus on the
+trigger → synthetic `mouseenter`; leaving → synthetic `mouseleave`. The bookmark
+menu on title pages is a Zag/Skeleton menu (`[data-scope=menu]`), click-driven,
+closed with Escape — handled by the generic dialog path.
+
+### Focusable noise to ignore
+
+On the home page: 497 focusables, 341 invisible. Sources: popup links (3 per
+card), off-screen carousel items, mobile-only header/drawer duplicates
+(`md:hidden`, `aside.-translate-x-full`), carousel arrows and dots.
+
+## 2. Input
+
+### Physical remote (Samsung Smart Remote, The Frame)
+
+| Key | Tizen keyCode | Registered? |
+|---|---|---|
+| ← ↑ → ↓ | 37 38 39 40 | default |
+| Select (OK) | 13 | default |
+| Return (Back) | 10009 | default |
+| Play/Pause | 10252 | must `tizen.tvinputdevice.registerKey('MediaPlayPause')` |
+| Channel ▲ / ▼ | 427 / 428 | must register `ChannelUp` / `ChannelDown` |
+
+Not usable: volume (TV level), Home/Power/Ambient/app shortcuts (system),
+color keys and digits (only via the `123` virtual keypad → rejected).
+
+### Keyboard emulation (phase 1, desktop)
+
+| Keyboard | Emulates |
+|---|---|
+| Arrow keys | D-pad |
+| Enter | OK |
+| Escape | Back |
+| Space | Play/Pause |
+| PageUp / PageDown | Channel ▲ / ▼ |
+
+Every other key is ignored by the script (passes through). Mouse is untouched.
+
+## 3. Modes
+
+```
+NAV      – a page block is focused; D-pad moves focus geometrically
+CARD     – a card is focused, its popup is open (sub-state of NAV)
+PLAYER   – on /watch, the video is the focused block; D-pad drives playback
+SEEK     – scrubbing: a preview cursor moves on the progress bar, OK commits
+BAR      – on /watch, focus is inside the Video.js control bar (sub-state of NAV)
+```
+
+A small badge (top-right, 2 s fade) shows the mode after each change, plus the
+last key code (phase 1 debug only).
+
+## 4. Key map
+
+### NAV (all pages)
+
+| Key | Action |
+|---|---|
+| ← ↑ → ↓ | move focus to the nearest visible block in that direction (horizontal moves stay on the same line; the fixed header is only a target when nothing else is above) |
+| → / ← at the edge of a carousel page | click the row's Next / Previous, then focus the first / last newly visible card |
+| focus lands on a hover-menu trigger (avatar) | menu opens; **↓ / OK** enter it, **Back** closes it, ← → ↑ close it and move on |
+| OK | `click()` the focused element (`<a>`, `<button>`); `<select>`/`<input>` → native focus so the TV keyboard/picker opens |
+| Back | if a `<select>`/`<input>` is active → blur; else `history.back()`; on `/` → do nothing (let TizenBrew handle exit) |
+| Play/Pause | ignored |
+| Ch ▲ / ▼ | focus the first card of the previous / next carousel row |
+
+### CARD (card focused)
+
+| Key | Action |
+|---|---|
+| focus enters | add `.tv-focus` on `div.group` → popup opens (CSS below); highlight = whole popup |
+| OK | go to title page (click the poster link) |
+| ↓ | move sub-focus to "Xem" (if not already); ↓ again → leave the card downwards |
+| ↑ | from "Xem" → back to card body; from card body → leave upwards |
+| ← → | neighbouring card (popup closes, new one opens) |
+| Play/Pause | click "Xem" → watch page |
+| focus leaves | remove `.tv-focus` |
+
+### Watch page
+
+Landing state: **PLAYER** mode, windowed, autoplaying. Player element gets the
+focus ring.
+
+| Key | PLAYER (windowed or fullscreen) |
+|---|---|
+| OK | not fullscreen → `player.requestFullscreen()`; fullscreen → play/pause |
+| Play/Pause | play/pause (any mode) |
+| ← / → | enter **SEEK** (scrub) mode — no jump happens yet |
+| Ch ▲ / ▼ | enter **SEEK** with a ±5 min step |
+| ↑ | windowed: leave the player upwards → **NAV** on the header links (↓ from there re-enters PLAYER); fullscreen: no-op |
+| ↓ | show controls and enter **BAR** mode on the play button |
+| Back | fullscreen → exit fullscreen (stay PLAYER); windowed → `history.back()` (title page) |
+
+| Key | BAR (control bar focused) |
+|---|---|
+| ← → | move across visible `.vjs-control-bar` buttons (skip `.vjs-hidden`, `.vjs-disabled`, progress bar) |
+| OK | click; a `.vjs-menu` (speed) or the subtitle panel becomes the navigation scope |
+| ↑ | back to PLAYER |
+| ↓ | windowed only → NAV on the page buttons below the player; fullscreen → no-op |
+| Back | if a vjs menu is open → close it; else → PLAYER |
+| Play/Pause | play/pause |
+
+### SEEK (scrub) mode
+
+The stream re-buffers slowly, so a keypress must never move playback. `←`/`→`
+in PLAYER (or OK on the progress bar in BAR) enter SEEK: a pending position is
+tracked in `S.seekTo` while the video keeps playing untouched.
+
+The preview is the site's own: a synthetic `mouseover` + `mousemove` on
+`.vjs-progress-control` at the matching x makes its thumbnail sprite
+(`assets.phimzoo.com/thumb/<id>.jpg`) appear and follow. `.vjs-mouse-display` is
+CSS-gated on real `:hover`, so its time tooltip stays hidden; the script draws
+its own caret + time label (`#tv-seek`) instead. `mouseout` + `mouseleave` hide
+the thumbnail again.
+
+| Key | SEEK |
+|---|---|
+| ← / → | move the cursor; step accelerates while pressing: 10 s → 30 s → 60 s → 5 min (resets after 800 ms or on direction change) |
+| Ch ▲ / ▼ | ±5 min |
+| OK | commit: `player.currentTime(seekTo)`, resume if it was playing, back to **PLAYER** |
+| Back / ↑ | cancel, back to **PLAYER** (playback never moved) |
+| ↓ | cancel, back to **BAR** |
+| Play/Pause | play/pause, stays in SEEK |
+
+Fallback: if `duration()` is unknown or infinite (live), arrows revert to the
+old immediate ±10 s seek.
+
+| Key | Subtitle panel (scope, entered from the `Phụ đề` bar button) |
+|---|---|
+| focus enters | lands on the currently selected track (or the first entry of the active pane) |
+| ← ↑ → ↓ | move between tabs, track entries, the two bilingual columns, filter toggles and `Cài đặt` |
+| OK on a tab | switch pane, focus its first entry |
+| OK on a track / filter | apply it; if the panel closes itself, focus returns to the `Phụ đề` button in **BAR** |
+| Back | close the panel (clicks the bar button) and return to **BAR** |
+
+| Key | NAV below player (windowed) |
+|---|---|
+| ↑ from the top row | → BAR |
+| OK on the player block | → PLAYER |
+| Back | `history.back()` |
+
+Every key in PLAYER/BAR calls `player.userActive(true)` first so the control
+bar is visible while interacting.
+
+## 5. Spatial navigation algorithm
+
+Candidates = `a[href], button, select, input, textarea, [tabindex]:not([tabindex="-1"]), .video-js`
+filtered by:
+
+1. `getBoundingClientRect()` width & height > 0
+2. computed `visibility != hidden`, `opacity > 0`, `pointer-events != none`
+3. no ancestor with `display:none`
+4. rect intersects the viewport (with 1 px tolerance) — kills off-screen carousel items
+5. not inside `header` when the header is translated off (`translate-y-*` ≠ 0)
+6. exclusions: carousel `Previous/Next/Go to page` buttons, `aside` drawer, `.md\:hidden` duplicates, `.vjs-hidden`, hover-popup links (collapsed into the card block)
+
+Dedupe: any candidate inside `div.group` collapses to the group → one block per card.
+
+Direction scoring from the focused rect `F` to candidate `C`:
+
+```
+must be strictly in direction (C.left >= F.right - overlapTol for →, etc.)
+primary   = distance along the axis
+secondary = misalignment perpendicular (centre-to-centre), weighted ×2
+score     = primary + 2 * secondary
+```
+
+Ties broken by DOM order. If no candidate in that direction and the focused
+block is in a carousel → try paging. If still nothing → stay (no wrap).
+
+Focus memory: per carousel row, remember the last focused card so ↑/↓ across
+rows returns to it (Netflix behaviour). Per URL, remember the last block so
+Back restores it.
+
+## 6. Rendering
+
+Injected CSS (`<style id="tv-nav-style">`):
+
+```css
+.tv-focus-ring { outline: 4px solid #fff; outline-offset: 3px; border-radius: 10px;
+                 box-shadow: 0 0 0 8px rgba(0,0,0,.6); z-index: 20; position: relative; }
+.group.tv-focus > .group-hover\:invisible { visibility: hidden !important; }
+.group.tv-focus .group-hover\:block      { display: block !important; }
+.tv-focus .tv-sub-focus                  { outline: 3px solid #fff; outline-offset: 2px; }
+.video-js.tv-focus-ring                  { outline-offset: -4px; }
+#tv-badge { position: fixed; top: 12px; right: 12px; z-index: 99999; font: 14px/1 monospace;
+            padding: 6px 10px; background: rgba(0,0,0,.7); color: #fff; border-radius: 6px;
+            pointer-events: none; transition: opacity .3s; }
+body.tv-mode { cursor: none; }
+```
+
+Focused element also receives `scrollIntoView({block:'center'})` (vertical
+only; horizontal handled by carousel paging).
+
+## 7. Lifecycle
+
+1. On load: inject CSS + badge, patch `history.pushState/replaceState`, listen
+   `popstate`, start a `MutationObserver` on `body` (debounced 150 ms) to
+   re-validate the focused element (if removed → refocus nearest / first block).
+2. Route handler on every URL change:
+   - `/watch/*` → wait for `.video-js` (poll 100 ms, max 10 s) → PLAYER mode.
+   - `/search` → focus the input (native), Back blurs.
+   - otherwise → NAV, restore per-URL memory or focus first card (fallback: first block).
+3. Keydown listener on `window` with `capture: true`; handled keys →
+   `preventDefault()` + `stopPropagation()` so `videojs-hotkeys` and Svelte
+   handlers do not double-act.
+
+## 8. Phase 2 — TizenBrew packaging
+
+A TizenBrew *site modification* module is a plain npm package whose
+`package.json` carries a flat manifest (per the
+[module docs](https://github.com/reisxd/TizenBrew/blob/main/docs/MODULES.md)):
+
+```json
+{
+  "packageType": "mods",
+  "appName": "PhimPal TV",
+  "websiteURL": "https://phimpal.com/",
+  "main": "mod.js",
+  "keys": ["MediaPlayPause", "MediaPlay", "MediaPause", "ChannelUp", "ChannelDown"]
+}
+```
+
+TizenBrew opens `websiteURL`, injects `main` into the page and registers `keys`
+through the TVInputDevice API. Modules are installed by npm package name in the
+module manager, so publishing to npm is the delivery step.
+
+`build.js` derives `mod.js` from `phimpal-tv.user.js` (the single source):
+it strips the userscript header and flips three flags — `keyboardEmulation`
+off, `debug` behind `localStorage['tv-debug']`, `hideCursor` on — then prepends
+a defensive `tizen.tvinputdevice.registerKey` loop and re-checks the bundle
+(required symbols present, no leftover header, parses).
+
+### TV-specific behaviour in the engine
+
+| Concern | Resolution |
+|---|---|
+| Leaving the module | Return on `/` is **not** consumed, so TizenBrew handles the exit. Elsewhere it means back / close a scope. |
+| Fullscreen | `requestFullscreen` first; if it throws, rejects, or nothing happened after 400 ms, `.tv-fs` stretches the player over the viewport (header/footer hidden). `isFs()` covers both, so the key map is unchanged. |
+| Hover menus without a pointer | The avatar menu mounts on `mouseenter` but the site fades it in only while the node truly matches `:hover`. The module waits for the node and applies `.tv-force-visible` (`opacity/visibility/pointer-events !important`). Note the 150 ms fade: read state after ~500 ms, not immediately. |
+| Pointer | `cursor: none` everywhere in the TV build. |
+
+### Verified on the built module (browser pane, Tizen key codes only)
+
+Keyboard codes ignored; 37/38/39/40/13 navigate; 10009 backs out; 10252
+toggles playback; 427/428 step the seek cursor by 5 min; the CSS fullscreen
+fallback fills the viewport and Return leaves it; Return from `/watch/:id`
+lands on the title page (the `/api/play/` redirect does not stay in history);
+Return on `/` is passed through to the platform.
+
+### Still unverified (needs the real TV)
+
+HLS playback in the Tizen webview (Video.js uses MSE, expected to work),
+whether `requestFullscreen` is accepted there or the fallback kicks in, cookie
+persistence for the login across TizenBrew restarts, and remote key repeat
+timing (the seek acceleration window is tuned at 800 ms).