@vyonio/player 0.0.0-stage → 0.2.1

package/CHANGELOG.md

@@ -0,0 +1,38 @@
+# Changelog
+
+## 0.2.1 — 2026-10-15
+
+### Fixed
+
+- Prefer standard or WebKit element fullscreen when available, then native video
+  fullscreen on supported iOS video elements, retaining Plyr's CSS fallback.
+- Request fullscreen synchronously from an explicit user action. Opening,
+  metadata, playing and autoplay do not enter fullscreen automatically.
+- Recover from unsupported or rejected fullscreen entry; restore inline controls
+  on exit and clean up listeners and fullscreen state on destroy/remount.
+  Delayed WebKit exit and element entry completing after teardown are covered.
+- Respect disabled or omitted fullscreen controls, including keyboard and
+  double-click actions.
+- Remove the unconditional 192px mount minimum. Preserve explicit host sizing
+  even when SDK CSS loads last, intrinsic sizing for width-only hosts, source
+  aspect ratios, letterboxing, and responsive controls without remounting.
+
+### Validation and limitations
+
+- 196 unit/release-script tests and 36 offline browser regression tests passed.
+  Browser tests use real Plyr and the built SDK stylesheet in headless Chrome;
+  fullscreen capability APIs are simulated. All five requested viewport widths
+  (320, 375, 390, 844 and 1400px), rotation, and lifecycle races are covered.
+- Build and independent tarball consumer installation/type-check/build passed.
+- Physical iPhone fullscreen with a supported protected video is **not verified**.
+  Apple iPhone Simulator was not used. This release does not claim FairPlay/DRM
+  device certification. Native fullscreen uses system controls and cannot render
+  HTML badges, the popularity histogram or custom HTML overlays.
+
+### Consumer migration
+
+Upgrade the locked `@vyonio/player` dependency to `0.2.1`. Remove the Rails
+`nativeVideoFullscreen()` click-interception helper and its lifecycle wiring.
+After verifying sizing with the released package, remove the SDK-specific
+`min-height: 0` workaround. Keep application container sizing, modal scrolling
+and course-navigation fixes.

package/README.md

@@ -1,3 +1,347 @@
-# Temporary Holding Version
+# @vyonio/player
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Shaka Player engine with Plyr chrome for Vyonio DRM video playback. Plyr styles and the control-icon SVG sprite ship with the package, so playback does not depend on the Plyr CDN or require it in the host's Content Security Policy. If Plyr fails to initialize, the player falls back to native `<video controls>`.
+
+> **Release availability:** source checkouts can be ahead of npm. Check available
+> versions with `npm view @vyonio/player versions`. For an unpublished checkout,
+> use `npm run verify:package` or a local `npm pack` tarball. Customer setup is in
+> the [public npm guide](https://developers.vyonio.com/npm-player/) and
+> [shared backend guide](https://developers.vyonio.com/protected-playback/).
+
+## Installation
+
+```bash
+npm install @vyonio/player
+```
+
+The ESM package bundles Shaka and Plyr and exports TypeScript declarations.
+Import `@vyonio/player/style.css` once in your application. The default API is
+`https://api.vyonio.com`; set `apiBase` only when using another environment.
+
+For a clean repository checkout, first run `npm ci --prefix packages/player`,
+then `npm ci --prefix <app>` for each app you use (`client`, `course`, `player`,
+`dash`). App build and dev scripts build the shared package before starting;
+they do not install dependencies. Run `npm --prefix packages/player run verify:package` to pack, install, type-check, and build an independent consumer.
+`npm pack` runs the library build through `prepack`. Local verification prepares
+a release artifact; publishing npm and hosted artifacts is a separate step.
+
+## Usage
+
+### Public video
+
+```js
+import { VyonioPlayer } from '@vyonio/player';
+import '@vyonio/player/style.css';
+
+const { player, destroy } = await VyonioPlayer.mount(element, {
+  apiBase: 'http://localhost:3000',
+  embedUuid: '550e8400-e29b-41d4-a716-446655440000',
+  autoplay: false,
+  muted: false,
+  loop: false,
+  controls: true,
+  controlItems: ['play-large', 'play', 'progress', 'current-time', 'fullscreen'],
+  settingsItems: ['quality'],
+  language: 'cs',
+  accentColor: '#7c3aed',
+  badge: {
+    text: 'AI-assisted',
+    position: 'top-right',
+    style: 'accent'
+  },
+  startSeconds: 0
+});
+```
+
+The optional playback settings are intended for hosted embeds as well as
+direct integrations. Browsers generally require `muted: true` when autoplay is
+enabled. A rejected autoplay attempt leaves the player ready for manual play.
+`controlItems` accepts Plyr control names and is ignored when `controls` is
+false. `settingsItems` accepts `quality` and `speed`; it defaults to
+`['quality']`, so playback speed is opt-in. An empty array removes the settings
+menu, and unavailable quality choices hide automatically. `language` accepts
+`en` and `cs` and defaults to English. Unsupported languages fall back to
+English. `accentColor` accepts only a six-digit hex color. Badge text is rendered
+as plain text inside Plyr's fullscreen container and is limited to 64
+characters; positions are the four corners and styles are `dark`, `light`, or
+`accent`.
+
+### Fullscreen and responsive hosts
+
+Fullscreen uses element fullscreen when the mounted video's document supports
+it, then native video fullscreen (`fullscreen.iosNative`) when available, and
+Plyr's full-window CSS fallback otherwise. Entry happens only on an explicit
+fullscreen action; mounting, metadata, playing and autoplay do not request it.
+If native entry fails, the existing CSS fallback remains usable. Exiting keeps
+inline playback and controls available. `controls: false` or a `controlItems`
+list without `fullscreen` also disables keyboard and double-click entry.
+Consumers do not need a click interceptor on Plyr's private DOM selectors.
+
+Native iPhone fullscreen uses system video controls. HTML badges, the popularity
+histogram and other HTML overlays are not rendered in that system view; custom
+quality/settings UI is available again after returning inline. Do not depend on
+HTML badges for mandatory watermarking. See [Plyr's fullscreen options](https://github.com/sampotts/plyr#options)
+and [Apple's native video API](https://developer.apple.com/documentation/webkitjs/htmlvideoelement/1633500-webkitenterfullscreen).
+
+The mount fills a sized host, including heights below 192px, with no minimum
+height override required. Host rules win over SDK size defaults even when the
+SDK stylesheet is loaded last. A width-only host uses the video's intrinsic
+aspect ratio once metadata is available (16:9 before that). Media uses
+`object-fit: contain`, so differing host/media ratios produce intentional
+letterboxing. Resizing and orientation changes do not require a remount.
+
+```css
+/* Choose a host size appropriate to your layout. */
+.video-slot {
+  width: 100%;
+  aspect-ratio: 16 / 9;
+  border-radius: 0.75rem;
+  overflow: hidden;
+}
+```
+
+### Verify fullscreen and sizing changes
+
+```sh
+# From packages/player, with Node 22.12+ and installed dependencies:
+npm test
+# Uses installed Google Chrome. To provision it when absent:
+# npx playwright install chrome
+npm run test:browser
+npm run verify:package
+```
+
+Browser regressions build and load the shipped `dist/style.css` after host CSS
+with real Plyr markup. They cover direct/nested 16:9 hosts at viewport widths
+320, 375, 390, 844 and 1400px, explicit 120px height, width-only hosts, metadata
+aspect-ratio changes, portrait/landscape resizing, visible usable controls,
+capability selection, synchronous entry, fallback, exit and teardown races.
+They block non-local requests and need no live token/media/DRM/analytics/payment
+services. Browser fullscreen APIs are simulated; desktop mobile emulation does
+not establish that native iPhone fullscreen or protected playback works.
+
+Device acceptance remains outstanding: verify on a **physical iPhone** using a supported
+protected video: open/play stays inline; tapping fullscreen opens system video
+fullscreen; exit restores inline video and working controls; repeat entry,
+rotation, closing while fullscreen, source switching and remounting work.
+Record device/iOS/Safari versions and the protected asset/DRM mode without
+recording secrets. Physical iPhone verification has **not** been completed in
+this change.
+
+See the shipped [changelog](./CHANGELOG.md) for the 0.2.1 fixes and known
+verification limits. The 0.2.1 patch follows the [repository release procedure](https://gitlab.com/buildio/playground/vyonio.com/-/blob/main/docs/player-release.md);
+0.2.0 remains immutable. Package version files and the `player-v0.2.1` tag are
+recorded by that procedure only after publication and registry verification.
+
+After upgrading the Rails consumer's locked dependency to 0.2.1, remove
+`nativeVideoFullscreen()` and its lifecycle wiring, then remove its SDK-specific
+`min-height: 0` workaround after sizing is verified against the released package.
+Keep normal container sizing, modal scrolling and course-navigation fixes in
+the application.
+
+### Popularity histogram
+
+Pass equal-duration popularity buckets to render a YouTube-like engagement
+curve above the seek bar (white top stroke, fade-to-transparent fill). The
+overlay is non-interactive and only appears while the progress control is
+hovered or scrubbed:
+
+```js
+await VyonioPlayer.mount(element, {
+  apiBase: 'http://localhost:3000',
+  embedUuid: '550e8400-e29b-41d4-a716-446655440000',
+  popularityHistogram: {
+    buckets: [12, 18, 31, 24, 15]
+  }
+});
+```
+
+Each bucket spans an equal portion of the video duration, and heights are
+normalized against the largest value. The player also accepts the same array
+from `popularity_histogram.buckets` in the playback descriptor when a backend
+provides it. Explicit mount-option buckets take precedence. The current Vyonio
+Platform descriptor does not supply popularity buckets; aggregation and API
+delivery are a separate backend feature.
+
+HTML badges stay visible in normal Plyr fullscreen, but cannot be guaranteed in
+native video fallback, Picture in Picture, AirPlay, casting, or downloaded
+media. Use a burned-in watermark for compliance-critical or tamper-resistant
+marking.
+
+Fetches the video descriptor from `{apiBase}/v1/embed/{embedUuid}`, attaches a `<video>` element with Plyr controls (or native controls on Plyr failure), configures Widevine DRM, and loads the DASH manifest. Safari/FairPlay is scaffolded and throws until Apple FPS credentials are deployed.
+
+The returned handle also exposes media controls used by the hosted iframe API:
+
+```js
+const handle = await VyonioPlayer.mount(element, options);
+
+await handle.play();
+handle.pause();
+handle.seek(30);
+handle.setMuted(true);
+console.log(handle.getState());
+```
+
+`seek(seconds)` accepts a nonnegative finite number and clamps it to the known
+duration. `getState()` returns `currentTime`, `duration`, `paused`, `ended`, and
+`muted`. The underlying `HTMLVideoElement` is available as `mediaElement` for
+advanced event handling.
+
+If the descriptor includes a `telemetry` endpoint and signed context, the
+player automatically emits batched `start`, `heartbeat`, `pause`, `seek`,
+`end`, `leave`, and `error` events. Telemetry is best-effort: failures and an
+absent telemetry descriptor never interrupt playback. Pipeline credentials are
+held by the Platform API and are never exposed to the browser.
+
+Every mounted player uses a fresh random session UUID. Heartbeat, pause, end,
+and leave events close continuous watched spans with millisecond start/end,
+duration, watched time, buffering time, and playback rate. A seek closes the
+preceding span and records only its origin and destination, so skipped content
+is not counted as watched. Telemetry contains no user/member ID, stable device
+ID, fingerprint, page/referrer URL, or cross-session cookie.
+
+### Protected video (playback JWT)
+
+For a same-origin customer endpoint:
+
+```js
+const handle = await VyonioPlayer.mount(element, {
+  embedUuid: 'your-embed-uuid',
+  tokenEndpoint: '/api/playback-token',
+  tokenHeaders: { 'X-CSRF-Token': csrfToken }
+});
+```
+
+The endpoint receives `POST` JSON `{ embedUuid }` with same-origin credentials
+and must authenticate the viewer and recheck entitlement on every request.
+Return JSON `{ token, expires_in: 600 }` with `Cache-Control: no-store`.
+Keep the Vyonio API key only on your server. Customers never need Vyonio's JWT signing secret.
+`tokenEndpoint` and `getPlaybackToken` are mutually exclusive. Endpoint URLs
+must be same-origin; `tokenHeaders` cannot include Authorization. Token
+acquisition times out after 15 seconds and rejects with `PlaybackTokenError`
+(`PLAYBACK_TOKEN_FAILED` or `PLAYBACK_TOKEN_TIMEOUT`).
+
+Pass `tokenEndpoint` or `getPlaybackToken` to attach a short-lived playback JWT before the descriptor fetch. The player:
+
+- Sends `Authorization: Bearer <token>` on the descriptor request and all Shaka network requests (via a request filter)
+- Appends `access_token=<token>` to the DASH manifest URL (for AirPlay / devices that cannot send headers)
+- Replaces `access_token` on subsequent platform manifest, segment, and license request URLs after each token refresh
+- Schedules automatic refresh from the JWT `exp` claim, **120 seconds before expiry**
+- Starts refresh scheduling only after the manifest loads successfully
+- On refresh failure, marks the mount and video elements with `data-state="error"`, emits a `vyonio-player-error` event from the mount element, calls optional `onError`, then destroys the player and removes the video element
+
+```js
+const { player, destroy } = await VyonioPlayer.mount(element, {
+  apiBase: 'http://localhost:3000',
+  embedUuid: '550e8400-e29b-41d4-a716-446655440000',
+  onError: ({ code, message, error }) => {
+    // code is PLAYBACK_AUTH_REFRESH_FAILED for token refresh failures.
+    showPlaybackError(message);
+  },
+  getPlaybackToken: async () => {
+    const res = await fetch('/api/playback-token', {
+      method: 'POST',
+      credentials: 'same-origin',
+      cache: 'no-store',
+      redirect: 'error',
+      headers: { 'Content-Type': 'application/json', 'X-CSRF-Token': csrfToken },
+      body: JSON.stringify({ embedUuid: '550e8400-e29b-41d4-a716-446655440000' })
+    });
+    if (!res.ok) throw new Error(`Token mint failed: ${res.status}`);
+    const { token } = await res.json();
+    return token;
+  }
+});
+```
+
+The `vyonio-player-error` event is a `CustomEvent` with the same `{ code, message, error }` object in `event.detail`. This lets applications surface an authentication or entitlement error even when they do not provide `onError`.
+
+When both authentication options are omitted, behavior matches the public path (no Bearer header, no manifest query param, no refresh timer).
+
+## Playback descriptor: captions and chapters
+
+The embed descriptor (`GET {apiBase}/v1/embed/{embedUuid}`) may include:
+
+```json
+{
+  "captions": [
+    {
+      "language": "cs",
+      "label": "Čeština",
+      "kind": "subtitles",
+      "vtt_url": "https://media.example/caption_tracks/1/vtt",
+      "default": true
+    }
+  ],
+  "chapters": [
+    { "title": "Intro", "start_seconds": 0 },
+    { "title": "Main", "start_seconds": 42 }
+  ]
+}
+```
+
+- **`captions`**: optional array of sidecar WebVTT tracks. Each entry supplies `language`, `label`, `kind` (`subtitles` or `captions`), authenticated `vtt_url`, and optional `default` (boolean). When `getPlaybackToken` is used, the player appends `access_token` to each `vtt_url` the same way it does for the DASH manifest.
+- **`chapters`**: optional array of chapter cues with `title` and `start_seconds`. The player builds an in-memory chapters WebVTT track for Plyr's chapter menu; cue end times are the next chapter start or video duration.
+
+When either field is absent or empty, the corresponding Plyr control stays idle.
+
+## Tests
+
+```bash
+npm test
+```
+
+## React and SSR
+
+The browser engine uses DOM globals. Import `@vyonio/player` dynamically inside
+a client effect; do not import the engine in a server-evaluated module. Import
+the CSS once through your framework's supported global CSS entry. Cancel stale
+mounts, destroy their late handles, and call `destroy()` on cleanup. The
+[public npm guide](https://developers.vyonio.com/npm-player/#react-and-server-rendering)
+contains the complete lifecycle example.
+
+See the [runnable customer example](../../examples/protected-playback/README.md)
+for the same-origin `{ embedUuid }` request, CSRF `tokenHeaders`, server-only key,
+current entitlement checks, and Node/PHP host replacement points. Its login is
+local demonstration authentication, not a production identity system. Protected
+access can be used with clear or DRM media; this package preserves your existing
+account DRM configuration and does not provision FairPlay.
+
+## Maintainer releases
+
+From the repository root, use Node 22.12+ and your own npm account with Vyonio
+publish access. Commit package changes first, leave the Git index empty, and sign
+in once with `npm login`. Use a named branch with Git `user.name`/`user.email`
+configured and no merge/rebase in progress.
+
+```sh
+# First publication of the existing package version:
+npm --prefix packages/player run release -- current --dry-run
+npm --prefix packages/player run release -- current
+
+# Later bug-fix release:
+npm --prefix packages/player run release -- patch --dry-run
+npm --prefix packages/player run release -- patch
+```
+
+Choose `minor` for a feature release or `major` for breaking changes. These commands
+accept stable versions only; prereleases need a separately reviewed release.
+The command builds a temporary copy of tracked package source, installs locked
+dependencies, runs all package tests, and verifies the tarball in an independent
+TypeScript/browser consumer. A real release asks for confirmation and uses npm's
+normal login/2FA flow. Only that verified tarball is published. It then checks
+registry integrity and installs the exact version from npm.
+
+Dry runs, cancellation and failed preparation leave your working version files
+unchanged, and create no commits or tags. After publication and registry
+installation verification, a bumped release commits only the manifest and
+lockfile, then creates an annotated `player-vX.Y.Z` tag on that exact commit.
+`current` tags the existing matching-version commit without adding an empty
+commit. The annotation records the npm artifact integrity. Existing local/origin
+tags are never overwritten. Unrelated unstaged work stays outside the release
+commit; any staged work blocks release.
+
+Review the local release commit and tag, then push them through your normal Git
+workflow. The command does not push tags or deploy hosted/docs assets. Read the
+[release runbook](../../docs/player-release.md) for first-release setup, Git/tag
+recovery and post-release documentation.