@scarlett-player/gestures 1.8.0 → 1.9.0

package/README.md

@@ -0,0 +1,80 @@
+# @scarlett-player/gestures
+
+Touch gestures for [Scarlett Player](https://scarlettplayer.com). Double-tap the right of the picture to jump forward, the left to jump back, keep tapping to go further, and single-tap to toggle the controls. Gestures are gated on `pointerType === 'touch'`, so a mouse or pen never triggers any of them and desktop behaviour is unchanged.
+
+## Installation
+
+```bash
+pnpm add @scarlett-player/core @scarlett-player/gestures
+```
+
+`@scarlett-player/core` is a peer dependency. `@scarlett-player/ui` is optional: tap-to-toggle needs it, double-tap seeking does not.
+
+## Usage
+
+```ts
+import { createPlayer } from '@scarlett-player/core';
+import { uiPlugin } from '@scarlett-player/ui';
+import { createGesturesPlugin } from '@scarlett-player/gestures';
+
+const player = await createPlayer({
+  container: '#player',
+  src: 'https://example.com/video.m3u8',
+  plugins: [uiPlugin(), createGesturesPlugin({ seekSeconds: 10 })],
+});
+```
+
+## Configuration
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `enabled` | `boolean \| 'auto'` | `'auto'` | `'auto'` installs the gesture surface when `matchMedia('(any-pointer: coarse)')` matches, so a touchscreen laptop counts. `true` forces it, `false` disables the plugin. No user agent sniffing |
+| `seekSeconds` | `number` | `10` | Seconds moved per seek step |
+| `doubleTapWindowMs` | `number` | `275` | Second tap within this window makes a double tap |
+| `accumulationWindowMs` | `number` | `650` | A further tap in the same zone within this window extends the seek |
+| `zones` | `{ left?, right? }` | `{ left: 0.33, right: 0.33 }` | Fractions of the width given to each seek zone. The middle is inert on purpose |
+| `slopPx` | `number` | `10` | Movement in CSS pixels that turns a tap into a drag and cancels it |
+| `feedback` | `boolean` | `true` | Show the zone highlight and cumulative seconds label |
+| `haptics` | `boolean` | `true` | `navigator.vibrate(10)` on each seek step where supported. iOS Safari ignores it |
+| `tapToToggleControls` | `boolean` | `true` | Let a single tap show or hide the controls |
+
+## Behaviour
+
+- Not installed for audio: when `mediaType` is `'audio'` at init the plugin stays inactive.
+- Seeking is refused while Chromecast or AirPlay is active, on live streams with no seekable range, and on VOD until a finite duration is known.
+- On live DVR a seek is clamped to the seekable range. A forward tap at the live edge announces "Already at the live edge" instead of showing a ripple.
+- Each tap in a run adds `seekSeconds`; the label shows the cumulative total. A tap in the opposite zone ends the run rather than reversing it, and a drag or a second finger cancels it.
+- A single tap shows hidden controls immediately. Hiding waits out `doubleTapWindowMs` so a seek is never preceded by the controls blinking away, and nothing hides while paused.
+- The surface never calls `preventDefault` or `stopPropagation`, so document-level click handlers (menus closing, for example) still fire.
+
+The plugin exposes `ownsTapInteraction()`, which the UI package checks before running its own show-controls logic on touch. It returns `true` while the plugin is active and `tapToToggleControls` is on.
+
+## Events
+
+| Event | Payload | When |
+|---|---|---|
+| `gesture:tap` | `{ zone }` | A single tap landed. `zone` is `'left'`, `'middle'` or `'right'` |
+| `gesture:seek` | `{ direction, seconds, cumulative }` | A seek step moved the playhead. `direction` is `'forward'` or `'backward'` |
+
+Each seek step also emits the core `playback:seeking` event with the target time.
+
+## CSS
+
+Styles are injected once per document in a `<style id="sp-gestures-styles">`. There are no CSS custom properties.
+
+| Class | Element |
+|---|---|
+| `.sp-gestures` | The surface. Absolutely positioned at `z-index: 6`, leaving the bottom 64px to the progress and control bars |
+| `.sp-gestures__zone` | One seek zone, `--left` or `--right`, sized from `zones`. `--active` while feedback is showing |
+| `.sp-gestures__label` | The cumulative seconds label inside a zone |
+| `.sp-gestures__live` | Visually hidden polite live region carrying the announcement |
+
+The zone transition is disabled under `prefers-reduced-motion: reduce`.
+
+## Lower level exports
+
+`createRecognizer`, `zoneFor` and `DEFAULT_RECOGNIZER_OPTIONS` expose the pure tap state machine, and `GestureOverlay` the DOM surface, for hosts that want to build their own handling on top.
+
+## License
+
+MIT

package/dist/index.cjs

@@ -178,6 +178,7 @@ function createRecognizer(options = {}) {
 }
 
 // src/overlay.ts
+var import_core = require("@scarlett-player/core");
 var STYLE_ID = "sp-gestures-styles";
 var styles = `
 .sp-gestures {
@@ -250,7 +251,7 @@ var GestureOverlay = class {
   constructor(container, options) {
     this.container = container;
     this.options = options;
-    this.styleEl = null;
+    this.releaseStyles = null;
     this.hideTimer = null;
     this.pointerHandler = (event) => {
       if (event.pointerType !== "touch") return;
@@ -325,8 +326,8 @@ var GestureOverlay = class {
     this.el.removeEventListener("pointerup", this.pointerHandler);
     this.el.removeEventListener("pointercancel", this.pointerHandler);
     this.el.remove();
-    this.styleEl?.remove();
-    this.styleEl = null;
+    this.releaseStyles?.();
+    this.releaseStyles = null;
   }
   /** Exposed for tests and for hosts that want to inspect the surface. */
   getElement() {
@@ -341,17 +342,19 @@ var GestureOverlay = class {
     zone.appendChild(label);
     return { zone, label };
   }
+  /**
+   * Claim the shared gesture stylesheet.
+   *
+   * Reference-counted: two players on one page share the sheet, and destroying
+   * either used to take it away from the other.
+   */
   injectStyles() {
-    if (document.getElementById(STYLE_ID)) return;
-    this.styleEl = document.createElement("style");
-    this.styleEl.id = STYLE_ID;
-    this.styleEl.textContent = styles;
-    document.head.appendChild(this.styleEl);
+    this.releaseStyles = (0, import_core.injectSharedStyles)(STYLE_ID, styles);
   }
 };
 
 // src/version.ts
-var PKG_VERSION = true ? "1.7.1" : "0.0.0-dev";
+var PKG_VERSION = true ? "1.9.0" : "0.0.0-dev";
 
 // src/index.ts
 function hasCoarsePointer() {

package/dist/index.d.cts

@@ -201,7 +201,7 @@ declare class GestureOverlay {
     private zones;
     private labels;
     private live;
-    private styleEl;
+    private releaseStyles;
     private hideTimer;
     private readonly pointerHandler;
     constructor(container: HTMLElement, options: OverlayOptions);
@@ -220,6 +220,12 @@ declare class GestureOverlay {
     /** Exposed for tests and for hosts that want to inspect the surface. */
     getElement(): HTMLElement;
     private createZone;
+    /**
+     * Claim the shared gesture stylesheet.
+     *
+     * Reference-counted: two players on one page share the sheet, and destroying
+     * either used to take it away from the other.
+     */
     private injectStyles;
 }
 

package/dist/index.d.ts

@@ -201,7 +201,7 @@ declare class GestureOverlay {
     private zones;
     private labels;
     private live;
-    private styleEl;
+    private releaseStyles;
     private hideTimer;
     private readonly pointerHandler;
     constructor(container: HTMLElement, options: OverlayOptions);
@@ -220,6 +220,12 @@ declare class GestureOverlay {
     /** Exposed for tests and for hosts that want to inspect the surface. */
     getElement(): HTMLElement;
     private createZone;
+    /**
+     * Claim the shared gesture stylesheet.
+     *
+     * Reference-counted: two players on one page share the sheet, and destroying
+     * either used to take it away from the other.
+     */
     private injectStyles;
 }
 

package/dist/index.js

@@ -147,6 +147,7 @@ function createRecognizer(options = {}) {
 }
 
 // src/overlay.ts
+import { injectSharedStyles } from "@scarlett-player/core";
 var STYLE_ID = "sp-gestures-styles";
 var styles = `
 .sp-gestures {
@@ -219,7 +220,7 @@ var GestureOverlay = class {
   constructor(container, options) {
     this.container = container;
     this.options = options;
-    this.styleEl = null;
+    this.releaseStyles = null;
     this.hideTimer = null;
     this.pointerHandler = (event) => {
       if (event.pointerType !== "touch") return;
@@ -294,8 +295,8 @@ var GestureOverlay = class {
     this.el.removeEventListener("pointerup", this.pointerHandler);
     this.el.removeEventListener("pointercancel", this.pointerHandler);
     this.el.remove();
-    this.styleEl?.remove();
-    this.styleEl = null;
+    this.releaseStyles?.();
+    this.releaseStyles = null;
   }
   /** Exposed for tests and for hosts that want to inspect the surface. */
   getElement() {
@@ -310,17 +311,19 @@ var GestureOverlay = class {
     zone.appendChild(label);
     return { zone, label };
   }
+  /**
+   * Claim the shared gesture stylesheet.
+   *
+   * Reference-counted: two players on one page share the sheet, and destroying
+   * either used to take it away from the other.
+   */
   injectStyles() {
-    if (document.getElementById(STYLE_ID)) return;
-    this.styleEl = document.createElement("style");
-    this.styleEl.id = STYLE_ID;
-    this.styleEl.textContent = styles;
-    document.head.appendChild(this.styleEl);
+    this.releaseStyles = injectSharedStyles(STYLE_ID, styles);
   }
 };
 
 // src/version.ts
-var PKG_VERSION = true ? "1.7.1" : "0.0.0-dev";
+var PKG_VERSION = true ? "1.9.0" : "0.0.0-dev";
 
 // src/index.ts
 function hasCoarsePointer() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scarlett-player/gestures",
-  "version": "1.8.0",
+  "version": "1.9.0",
   "description": "Gestures Plugin for Scarlett Player - double-tap seek zones and tap to toggle controls",
   "type": "module",
   "main": "dist/index.cjs",
@@ -22,7 +22,7 @@
     "dist"
   ],
   "peerDependencies": {
-    "@scarlett-player/core": "^1.7.0"
+    "@scarlett-player/core": "^1.8.0"
   },
   "devDependencies": {
     "@vitest/coverage-v8": "^1.6.0",
@@ -30,7 +30,7 @@
     "tsup": "^8.5.1",
     "typescript": "^5.3.0",
     "vitest": "^1.6.0",
-    "@scarlett-player/core": "1.8.0"
+    "@scarlett-player/core": "1.9.0"
   },
   "keywords": [
     "video",