From eb96b4c9f28a269f49f3f8ee9980dc8d1d5f746e Mon Sep 17 00:00:00 2001 From: 4gray <4gray@users.noreply.github.com> Date: Sat, 5 Sep 2026 23:58:24 +0200 Subject: [PATCH] feat(website): turn the screenshot showcase into a channel switcher (#1540) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * feat(website): turn the screenshot showcase into a channel switcher Second landing redesign PR. "See it in action" was a tab strip in a dashed frame showing one screenshot inside a drawn window chrome that duplicated the chrome already in the shot. It is now a channel list: number, screen name and one line about what the screen is for on the left, a single frame on the right, and a caption linking to the matching feature page. - Channels advance on their own with a progress hairline under the active row; hovering, focusing or scrolling the block out of view pauses it and `prefers-reduced-motion` disables autoplay entirely. - A brief on-screen "CH 03" badge confirms every switch. - Arrow keys, Home and End move between channels; the list is a proper vertical tablist with roving tabindex, panels carry `aria-hidden`. - Six screens: Dashboard, Live TV, Program guide, Movies & series, Downloads, Settings. Same files from `public/screenshots`; the add-playlist shot is replaced by the movie detail and the download manager. - On phones the screen comes first and the list follows. Co-Authored-By: Claude Fable 5.1 * test(website): cover the channel switcher, keep focus pausing after mouseleave Hover and focus now pause autoplay independently: clicking a channel focused it, but moving the pointer away resumed the timer and seven seconds later the selection moved under a still-focused tab. New `website-screenshot-showcase.test.mjs` (in the website test target): a structural half over the built HTML (vertical tablist, roving tabindex, one aria-hidden panel per channel) and a browser half that serves the build and drives it in Chromium — autoplay advances, hover pauses, click + mouseleave keeps the pause while focused, arrow/Home/End keys move selection, focus, panel, caption and badge together, blur resumes, and `prefers-reduced-motion` disables autoplay. The browser half falls back to the system Chrome channel and skips when no Chromium exists, so the structural checks run everywhere. Co-Authored-By: Claude Fable 5.1 * perf(website): lazy-load every showcase screenshot The block sits below the hero and the feature grid, so an eager first frame only competed with above-the-fold assets for visitors who never scroll to it. Native look-ahead loading brings it in well before the switcher is on screen. Co-Authored-By: Claude Fable 5.1 * test(website): share the browser harness, fail in CI without Chromium `website-browser-support.mjs` owns the loopback static server and the Chromium launcher for the website browser tests. The server resolves every request against the build root and answers 404 for anything that escapes it (CodeQL js/path-injection on the previous inline copy). The launcher tries the Playwright download, then the system Chrome and Chromium channels; when none launches it returns null locally so the structural half still runs, and throws under `CI` so the interaction assertions can never turn into a silent skip on the runner. Co-Authored-By: Claude Fable 5.1 * perf(website): defer inactive showcase frames, document the browser tests The six frames are stacked with opacity, so native lazy loading treated all of them as near-viewport and fetched every screenshot at once. Only the first frame now ships with a `src`; the switcher assigns it from `data-src` when a channel is shown and preloads the one after it, so at most two frames are ever in flight. The showcase test asserts the markup and the runtime behaviour. The website README now describes the browser-dependent suites, the shared harness, and the skip-locally / fail-in-CI rule. Co-Authored-By: Claude Fable 5.1 * docs(website): describe only the suite this PR adds Co-Authored-By: Claude Fable 5.1 * fix(website): resume the switcher from where it paused, keep DOM order on phones The dwell clock now stops while the switcher is hovered or focused and the pause time is added back on resume, so the progress hairline continues from its frozen position instead of snapping to zero and granting a fresh seven seconds. The test asserts the resume. On phones the list stays before the screen in the DOM and on screen (tabs before their panels, focus order equals reading order); it hides the per-channel descriptions and the keyboard hint there so the screen stays close instead of being reordered with `order-first`. Co-Authored-By: Claude Fable 5.1 * fix(website): never crop a showcase frame The screen box stretches to the channel list's row height, and with `object-cover` a wide screenshot lost its right side just above the `lg` breakpoint. Frames are now contained on a dark stage (a letterbox, as on a TV), and the per-channel descriptions are hidden between `lg` and `xl` so the row stays close to the frame's own height. Co-Authored-By: Claude Fable 5.1 * fix(website): pause the switcher dwell while offscreen instead of resetting it Leaving the viewport is now a pause like hover and focus: the frame loop stops, the progress hairline keeps its width, and the clock resumes from the same mark when the block scrolls back in. Only a channel change resets the dwell. The interaction test scrolls away and back to assert it. Co-Authored-By: Claude Fable 5.1 * perf(website): no next-frame prefetch when reduced motion disables autoplay Co-Authored-By: Claude Fable 5.1 * feat(website): persistent pause control for the channel switcher Hover and focus only pause while they last, which is no use to touch or screen-reader visitors, so the list footer now carries a Pause/Resume toggle (`aria-pressed`, full `aria-label`) that keeps autoplay stopped until pressed again (WCAG 2.2.2). It is removed under reduced motion, where nothing advances. The interaction test now waits for the seven-second rollover and checks that tab, panel, caption, badge and the preloaded frame all move to channel 02, and that the toggle holds through mouseleave and blur. Co-Authored-By: Claude Fable 5.1 * fix(website): keep the tablist to its tabs, no successor prefetch when autoplay is off The channel list's header and the Pause/Resume control sat inside the `role="tablist"` container; the tablist now wraps only the six tabs so assistive technology reads the toggle as an ordinary button beside the list. `show()` preloads the next frame only while autoplay can reach it (neither reduced motion nor the toggle has stopped it). Tests assert both. Co-Authored-By: Claude Fable 5.1 * fix(website): preload the successor when auto-advance resumes A channel picked while the switcher is paused deliberately skips its successor; resuming now fetches that frame so the next automatic switch does not land on a blank screen. The interaction test covers pause → manual selection → resume. Co-Authored-By: Claude Fable 5.1 * fix(website): Resume restarts autoplay at once; same-channel progress in the test The transient hover/focus pauses now watch only the channel list and the screen. The footer with the Pause/Resume control is not one of those regions, so after pressing Resume — with the pointer and the focus still on the button — autoplay visibly restarts instead of waiting for the visitor to leave the whole block. The interaction test compares progress within one channel (a paused Movies before and after Resume) rather than across channels, which could fail on a slow runner, and asserts that autoplay runs while the toggle keeps focus and hover. Co-Authored-By: Claude Fable 5.1 * perf(website): one scheduler for the switcher, no frames while paused Every pause reason (hover, focus, the toggle, leaving the viewport) now goes through a single `sync()`: the animation-frame loop runs only while the block is visible and nothing pauses it, and is cancelled otherwise, so a switcher left paused schedules no frames at all. The dwell clock still resumes from where it froze, and the successor frame is fetched only when the loop actually starts — so scrolling away and back under a persistent pause loads nothing. Tests count scheduled frames while paused and cover pause → manual selection → offscreen → return. Co-Authored-By: Claude Fable 5.1 * fix(website): a channel picked while paused gets its full dwell after Resume `show()` reset the pause mark, so the time a visitor spent paused after picking a channel counted toward that channel's dwell and Resume could advance immediately. When the loop is not running the new channel now starts out paused at that moment. The interaction test asserts the progress is still near zero right after Resume. Co-Authored-By: Claude Fable 5.1 * fix(website): follow reduced-motion changes and hidden tabs in the switcher The reduced-motion preference is read from a live MediaQueryList: when it changes while the page is open the scheduler stops or restarts and the Pause/Resume control is hidden or shown (it is hidden, not removed, for that reason). A hidden document counts as a pause too — background tabs throttle animation frames while the clock keeps running, so without it the first frame back would skip a channel. The interaction test flips both at runtime. Co-Authored-By: Claude Fable 5.1 * fix(website): plain action button for the switcher pause, no manual animations under reduced motion `aria-pressed` on a button whose name changes between "Pause auto-advance" and "Resume auto-advance" announced the wrong thing; the control is now an ordinary action button whose name says what pressing it does next. The OSD slide and the panel fade get `motion-reduce:transition-none`, so a manual selection under reduced motion moves nothing. Co-Authored-By: Claude Fable 5.1 --------- Co-authored-by: Claude Fable 5.1 --- apps/website/README.md | 11 + apps/website/project.json | 2 +- .../src/components/ScreenshotShowcase.astro | 433 ++++++++++++++---- tools/testing/website-browser-support.mjs | 101 ++++ .../website-screenshot-showcase.test.mjs | 265 +++++++++++ 5 files changed, 722 insertions(+), 90 deletions(-) create mode 100644 tools/testing/website-browser-support.mjs create mode 100644 tools/testing/website-screenshot-showcase.test.mjs diff --git a/apps/website/README.md b/apps/website/README.md index 179730d51..ee25690f4 100644 --- a/apps/website/README.md +++ b/apps/website/README.md @@ -64,6 +64,17 @@ resolved version. canonicals, direct asset links, JSON-LD, cross-links and sitemap entries without depending on a specific version. +`tools/testing/website-screenshot-showcase.test.mjs` drives the built site in +a real browser: the home page channel switcher (autoplay, hover/focus pausing, +keyboard navigation, deferred frame sources). It relies on +`tools/testing/website-browser-support.mjs`, which serves `dist/apps/website` +on a loopback port and launches Chromium from the Playwright download or, +failing that, the system Chrome/Chromium channel. Without any Chromium the +browser half is **skipped locally** (the structural checks still run) and +**fails in CI**, so a green local run only proves the interactions when a +browser was found — run `pnpm exec playwright install chromium` once if the +skip shows up in your output. + ## Guides Evergreen how-to posts live in the blog collection next to release notes diff --git a/apps/website/project.json b/apps/website/project.json index ba1b4c4fd..560b68091 100644 --- a/apps/website/project.json +++ b/apps/website/project.json @@ -18,7 +18,7 @@ "executor": "nx:run-commands", "dependsOn": ["build"], "options": { - "command": "node --test tools/testing/website-giscus-comments.test.mjs tools/testing/website-download-pages.test.mjs tools/testing/website-guides.test.mjs tools/testing/website-feature-pages.test.mjs tools/testing/website-compare-pages.test.mjs tools/testing/website-blog-tags.test.mjs" + "command": "node --test tools/testing/website-giscus-comments.test.mjs tools/testing/website-download-pages.test.mjs tools/testing/website-guides.test.mjs tools/testing/website-feature-pages.test.mjs tools/testing/website-compare-pages.test.mjs tools/testing/website-blog-tags.test.mjs tools/testing/website-screenshot-showcase.test.mjs" } }, "serve": { diff --git a/apps/website/src/components/ScreenshotShowcase.astro b/apps/website/src/components/ScreenshotShowcase.astro index 5d387c3d5..87e43a1ce 100644 --- a/apps/website/src/components/ScreenshotShowcase.astro +++ b/apps/website/src/components/ScreenshotShowcase.astro @@ -1,159 +1,414 @@ --- -const tabs = [ +/** + * "Flip through the app": the screenshot showcase as a channel switcher. + * + * The list on the left is the channel list of a TV player — number, name, + * one line about what the screen is for — and the screen on the right shows + * the selected shot. Channels advance on their own (a progress hairline runs + * under the active row) until the visitor hovers, focuses or scrolls the block + * out of view; `prefers-reduced-motion` turns autoplay off entirely. Arrow keys + * move between channels like a remote. + * + * Only the first frame ships with a `src`; the inactive panels sit stacked + * under it with opacity 0, so native lazy loading would fetch all six at + * once. The script assigns `src` from `data-src` when a channel is shown and + * preloads the one after it, so at most two frames are in flight. + * + * The list precedes the screen in the DOM at every breakpoint (tabs before + * their panels, focus order equals reading order); on phones the list simply + * hides the per-channel descriptions and the keyboard hint so the screen + * stays close. + * + * Hover and focus only pause while they last, which is no use to a touch or + * screen-reader visitor, so the list footer carries a "Pause auto-advance" + * toggle that stays paused until pressed again (WCAG 2.2.2). It is removed + * under reduced motion, where there is nothing to pause. The transient pauses + * watch the channel list and the screen only, so pressing Resume restarts + * autoplay at once even though the button keeps the pointer and the focus. + */ +const channels = [ { id: 'dashboard', label: 'Dashboard', + description: 'Continue watching, recent channels and favorites across every source.', image: '/iptvnator/screenshots/dashboard-with-content.webp', - alt: 'Dashboard with recently watched content and global favorites', + alt: 'Dashboard with continue watching, recently watched and global favorites', width: 2072, height: 1602, + link: { href: '/iptvnator/features/', label: 'Every feature' }, }, { id: 'live-tv', label: 'Live TV', + description: 'Channel list with the current program, the player and the EPG timeline side by side.', image: '/iptvnator/screenshots/screenshot-player.webp', - alt: 'Live channels with the inline player and EPG', + alt: 'Live channels with the inline player and the program timeline', width: 2442, height: 1806, + link: { href: '/iptvnator/features/m3u-player/', label: 'M3U playlist player' }, }, { id: 'epg', - label: 'EPG Guide', + label: 'Program guide', + description: 'A multi-channel grid with a now-line you can scrub through the day.', image: '/iptvnator/screenshots/multi-epg-view.webp', alt: 'Multi-channel electronic program guide', width: 2180, height: 1448, + link: { href: '/iptvnator/features/epg/', label: 'TV guide (EPG)' }, + }, + { + id: 'movies', + label: 'Movies & series', + description: 'Detail pages with cast, seasons and the position you stopped at.', + image: '/iptvnator/screenshots/vod-details.webp', + alt: 'Movie detail page with poster, cast and play button', + width: 2260, + height: 1490, + link: { href: '/iptvnator/features/xtream-codes-player/', label: 'Xtream Codes player' }, + }, + { + id: 'downloads', + label: 'Downloads', + description: 'Offline library, download queue and live-TV recordings in one place.', + image: '/iptvnator/screenshots/download-manager.webp', + alt: 'Download manager with an offline library and a queue', + width: 2500, + height: 1602, + link: { href: '/iptvnator/blog/v0-23-release-notes/', label: 'Download manager notes' }, }, { id: 'settings', label: 'Settings', + description: 'Player engine, EPG, TMDB metadata, remote control and backup.', image: '/iptvnator/screenshots/settings.webp', alt: 'Application settings in the dark theme', width: 2500, height: 1602, + link: { href: '/iptvnator/features/remote-control/', label: 'Phone remote control' }, }, - { - id: 'add-playlist', - label: 'Add Playlist', - image: '/iptvnator/screenshots/add-playlist.webp', - alt: 'Add playlist dialog for M3U, Xtream, and Stalker sources', - width: 2260, - height: 1490, - }, -]; +] as const; + +const pad = (n: number) => String(n).padStart(2, '0'); ---
- -
- - Interface - -

- See it in action -

-

- A clean, intuitive interface designed for the best viewing experience. +

+
+ + Interface + +

+ Flip through the app +

+
+

+ Six screens, one player. Pick a channel or let it run.

-
- -
+
+ +
+
+ Channels + {pad(channels.length)} +
+
{ - tabs.map((tab, i) => ( + channels.map((channel, i) => ( )) } +
+
+ + +
- -
+ +
{ - tabs.map((tab, i) => ( + channels.map((channel, i) => (
-
- -
- - -
-
-
- - - -
- {tab.label} -
- {tab.alt} -
-
+ {channel.alt}
)) } + + + + + +
+
+ {channels[0].label} + +
+ + {channels[0].link.label} → + +
- + + diff --git a/tools/testing/website-browser-support.mjs b/tools/testing/website-browser-support.mjs new file mode 100644 index 000000000..f37f33a4f --- /dev/null +++ b/tools/testing/website-browser-support.mjs @@ -0,0 +1,101 @@ +import { createReadStream, existsSync, statSync } from 'node:fs'; +import { createServer } from 'node:http'; +import { extname, resolve, sep } from 'node:path'; +import { fileURLToPath } from 'node:url'; + +/** + * Shared plumbing for the website tests that drive the built site in a real + * browser: a loopback static server for `dist/apps/website` mounted under the + * GitHub Pages base path, and a Chromium launcher. + * + * The server only ever hands out files below the build directory: the + * requested path is resolved against the root and anything that escapes it is + * answered with 404. Only local tests talk to it, but the guard keeps the + * helper honest and static analysis quiet. + * + * Chromium comes from the Playwright download when one exists, otherwise from + * the system Chrome/Chromium channel (GitHub's Ubuntu runners ship Google + * Chrome). In CI a missing browser is a failure, never a silent skip, so the + * interaction assertions cannot rot unnoticed; locally the caller may skip. + */ + +export const distRoot = fileURLToPath(new URL('../../dist/apps/website/', import.meta.url)); +export const BASE_PATH = '/iptvnator'; + +const MIME = { + '.html': 'text/html', + '.css': 'text/css', + '.js': 'text/javascript', + '.webp': 'image/webp', + '.png': 'image/png', + '.svg': 'image/svg+xml', + '.ico': 'image/x-icon', + '.xml': 'text/xml', +}; + +/** Maps a request URL to a file below `distRoot`, or `null` when it escapes the root. */ +export function resolveDistFile(url) { + let pathname; + try { + pathname = decodeURIComponent(new URL(url, 'http://localhost').pathname); + } catch { + return null; + } + if (pathname.startsWith(BASE_PATH)) { + pathname = pathname.slice(BASE_PATH.length) || '/'; + } + const root = resolve(distRoot); + const candidate = resolve(root, `.${pathname}`); + if (candidate !== root && !candidate.startsWith(root + sep)) { + return null; + } + const file = existsSync(candidate) && statSync(candidate).isDirectory() ? resolve(candidate, 'index.html') : candidate; + return existsSync(file) ? file : null; +} + +/** Serves the build on a random loopback port; resolves to `{ server, origin }`. */ +export function serveDist() { + const server = createServer((req, res) => { + const file = resolveDistFile(req.url ?? '/'); + if (!file) { + res.statusCode = 404; + res.end('not found'); + return; + } + res.setHeader('content-type', MIME[extname(file)] ?? 'application/octet-stream'); + createReadStream(file).pipe(res); + }); + return new Promise((done) => + server.listen(0, '127.0.0.1', () => done({ server, origin: `http://127.0.0.1:${server.address().port}` })), + ); +} + +/** + * Launches Chromium, trying the Playwright download first and the system + * channels next. Returns `null` when none is available — except in CI, where + * that is thrown as an error so the browser half of a test cannot be skipped. + */ +export async function launchBrowser() { + let playwright; + try { + playwright = await import('@playwright/test'); + } catch (error) { + return unavailable(`@playwright/test is not installed: ${error instanceof Error ? error.message : String(error)}`); + } + const attempts = []; + for (const options of [{}, { channel: 'chrome' }, { channel: 'chromium' }]) { + try { + return await playwright.chromium.launch(options); + } catch (error) { + attempts.push(`${JSON.stringify(options)}: ${error instanceof Error ? error.message.split('\n')[0] : String(error)}`); + } + } + return unavailable(`no Chromium could be launched (${attempts.join('; ')})`); +} + +function unavailable(reason) { + if (process.env.CI) { + throw new Error(`Website browser tests must run in CI, but ${reason}`); + } + return null; +} diff --git a/tools/testing/website-screenshot-showcase.test.mjs b/tools/testing/website-screenshot-showcase.test.mjs new file mode 100644 index 000000000..1b09e6763 --- /dev/null +++ b/tools/testing/website-screenshot-showcase.test.mjs @@ -0,0 +1,265 @@ +import { readFile } from 'node:fs/promises'; +import { join } from 'node:path'; +import { test } from 'node:test'; +import assert from 'node:assert/strict'; +import { BASE_PATH as BASE, distRoot, launchBrowser, serveDist } from './website-browser-support.mjs'; + +/** + * The home page "Flip through the app" channel switcher. + * + * The structural half reads the built HTML: a vertical tablist with one + * selected channel, roving tabindex, and a panel per channel. The + * interaction half serves the build over HTTP and drives it in Chromium: + * autoplay advances, hover and focus pause independently, arrow keys move + * the selection together with the panel, caption and on-screen badge, and + * `prefers-reduced-motion` turns autoplay off. Without a Chromium the browser + * half is skipped locally and fails in CI (see website-browser-support.mjs). + */ + +const CHANNELS = ['dashboard', 'live-tv', 'epg', 'movies', 'downloads', 'settings']; + +test('showcase markup: a vertical tablist with one selected channel and a panel each', async () => { + const html = await readFile(join(distRoot, 'index.html'), 'utf8'); + assert.match(html, /
]*aria-orientation="vertical"/); + + const tabs = [...html.matchAll(/]*role="tab"[^>]*>/g)].map((m) => m[0]); + assert.equal(tabs.length, CHANNELS.length, 'one tab per channel'); + for (const [i, tab] of tabs.entries()) { + assert.match(tab, new RegExp(`data-channel="${CHANNELS[i]}"`)); + assert.match(tab, new RegExp(`aria-controls="screen-panel-${CHANNELS[i]}"`)); + assert.match(tab, new RegExp(`aria-selected="${i === 0 ? 'true' : 'false'}"`)); + assert.match(tab, new RegExp(`tabindex="${i === 0 ? '0' : '-1'}"`)); + } + + const panels = [...html.matchAll(/]*role="tabpanel"[^>]*>/g)].map((m) => m[0]); + assert.equal(panels.length, CHANNELS.length, 'one panel per channel'); + for (const [i, panel] of panels.entries()) { + assert.match(panel, new RegExp(`id="screen-panel-${CHANNELS[i]}"`)); + assert.match(panel, new RegExp(`aria-labelledby="screen-tab-${CHANNELS[i]}"`)); + assert.match(panel, new RegExp(`aria-hidden="${i === 0 ? 'false' : 'true'}"`)); + } + assert.match(html, /href="\/iptvnator\/features\/epg\/"/, 'captions link into the feature pages'); + const toggleTag = html.match(/]*data-autoplay-toggle[^>]*>/)?.[0]; + assert.ok(toggleTag && /aria-label="Pause auto-advance"/.test(toggleTag), 'a persistent pause control ships in the markup'); + assert.doesNotMatch(toggleTag, /aria-pressed/, 'the control is an action button, not a toggle with a changing name'); + assert.match(html, /channel-osd[^"]*motion-reduce:transition-none/, 'the OSD slide is off under reduced motion'); + assert.match(html, /channel-panel[^"]*motion-reduce:transition-none/, 'the panel fade is off under reduced motion'); + const tablist = html.match(/
/)?.[0]; + assert.ok(tablist, 'tablist element'); + assert.equal((tablist.match(/