@vyonio/player 0.2.0 → 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

@@ -66,6 +66,79 @@ 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