@scarlett-player/gestures 1.6.0

package/dist/index.d.cts

@@ -0,0 +1,266 @@
+import { Plugin } from '@scarlett-player/core';
+
+/**
+ * Types for the Gestures Plugin.
+ */
+/** Horizontal region of the gesture surface a pointer landed in. */
+type GestureZone = 'left' | 'middle' | 'right';
+/**
+ * A pointer event reduced to what the recognizer needs.
+ *
+ * Deliberately not a DOM event: the recognizer is a pure state machine, and
+ * every timing rule in it is testable without a browser.
+ */
+interface PointerRecord {
+    /** What happened. */
+    type: 'down' | 'move' | 'up' | 'cancel';
+    /** Horizontal position in CSS pixels, for slop measurement. */
+    x: number;
+    /** Vertical position in CSS pixels, for slop measurement. */
+    y: number;
+    /** Horizontal position as a fraction of the surface width, for zoning. */
+    fraction: number;
+    /** Pointer identity, so a second finger can be told apart from a retap. */
+    pointerId: number;
+    /** Event timestamp in milliseconds. */
+    timeStamp: number;
+}
+/** What the recognizer concluded from a stream of pointer records. */
+type RecognizerEvent = {
+    type: 'tap';
+    zone: GestureZone;
+} | {
+    type: 'double-tap';
+    zone: GestureZone;
+    count: number;
+} | {
+    type: 'accumulate';
+    zone: GestureZone;
+    count: number;
+} | {
+    type: 'cancel';
+};
+/** Recognizer tuning. */
+interface RecognizerOptions {
+    /** Milliseconds within which a second tap counts as a double tap. */
+    doubleTapWindowMs: number;
+    /** Milliseconds within which a further tap extends an active seek sequence. */
+    accumulationWindowMs: number;
+    /** Fraction of the width belonging to the left zone. */
+    leftZone: number;
+    /** Fraction of the width belonging to the right zone. */
+    rightZone: number;
+    /** Movement in CSS pixels that turns a tap into a drag and cancels it. */
+    slopPx: number;
+}
+/** Configuration for the Gestures Plugin. */
+interface GesturesPluginConfig {
+    /**
+     * Whether gestures are active.
+     *
+     * `'auto'` enables them when the device reports a coarse pointer, and every
+     * individual gesture is additionally checked for `pointerType === 'touch'`,
+     * so a touchscreen laptop works with a finger and is untouched by the mouse.
+     * Never UA sniffing.
+     *
+     * @defaultValue 'auto'
+     */
+    enabled?: boolean | 'auto';
+    /**
+     * Seconds moved per seek step.
+     *
+     * @defaultValue 10
+     */
+    seekSeconds?: number;
+    /**
+     * Milliseconds within which a second tap counts as a double tap.
+     *
+     * @defaultValue 275
+     */
+    doubleTapWindowMs?: number;
+    /**
+     * Milliseconds within which a further tap extends the current seek.
+     *
+     * @defaultValue 650
+     */
+    accumulationWindowMs?: number;
+    /**
+     * Fractions of the width given to the seek zones. The remainder in the middle
+     * is deliberately inert: a mistap in the centre of the picture should do
+     * nothing rather than jump the video.
+     *
+     * @defaultValue \{ left: 0.33, right: 0.33 \}
+     */
+    zones?: {
+        left?: number;
+        right?: number;
+    };
+    /**
+     * Movement in CSS pixels that cancels a tap.
+     *
+     * @defaultValue 10
+     */
+    slopPx?: number;
+    /**
+     * Show the ripple and seek amount.
+     *
+     * @defaultValue true
+     */
+    feedback?: boolean;
+    /**
+     * Vibrate on each seek step where the platform supports it. Android Chrome
+     * does; iOS Safari has no vibration API and silently ignores it.
+     *
+     * @defaultValue true
+     */
+    haptics?: boolean;
+    /**
+     * Let a single tap toggle the controls.
+     *
+     * @defaultValue true
+     */
+    tapToToggleControls?: boolean;
+    /** Index signature for PluginConfig compatibility */
+    [key: string]: unknown;
+}
+
+/**
+ * Gesture recognizer.
+ *
+ * A pure state machine. No DOM, no timers, no player: it consumes reduced
+ * pointer records and returns what they mean. Every timing and tolerance rule
+ * lives here so all of them are testable with plain numbers.
+ *
+ * The machine has three resting points:
+ *
+ * - idle: nothing in flight
+ * - awaiting-second: one tap landed, a second within the double-tap window
+ *   would make it a seek
+ * - accumulating: a seek is under way, and each further tap in the same zone
+ *   extends it, which is the behaviour every major player now shares
+ */
+
+declare const DEFAULT_RECOGNIZER_OPTIONS: RecognizerOptions;
+/** The recognizer's public surface. */
+interface Recognizer {
+    /** Feed one pointer record. Returns everything it concluded, in order. */
+    handle(record: PointerRecord): RecognizerEvent[];
+    /**
+     * Advance time without a pointer event, so expiry is observable.
+     *
+     * @param now - Current time in milliseconds
+     */
+    tick(now: number): RecognizerEvent[];
+    /** Drop all in-flight state, for example when the media source changed. */
+    reset(): void;
+    /** Whether a seek sequence is currently accumulating. */
+    isAccumulating(): boolean;
+}
+/**
+ * Work out which zone a horizontal position belongs to.
+ *
+ * @param fraction - Position as a fraction of the surface width
+ * @param options - Zone sizes
+ * @returns The zone
+ */
+declare function zoneFor(fraction: number, options: RecognizerOptions): GestureZone;
+/**
+ * Create a gesture recognizer.
+ *
+ * @param options - Tuning overrides
+ * @returns A recognizer instance
+ */
+declare function createRecognizer(options?: Partial<RecognizerOptions>): Recognizer;
+
+/**
+ * Gesture surface and feedback.
+ *
+ * Layering rules that matter, and why:
+ *
+ * - The surface sits above the gradient and below the control bar, so the
+ *   buttons and the progress bar keep every pixel they already own.
+ * - It never calls `preventDefault` or `stopPropagation` on a tap. The settings
+ *   and quality menus close via document-level click listeners; swallowing the
+ *   event would leave them stuck open.
+ * - Feedback elements are `pointer-events: none` and `aria-hidden`, with a
+ *   single polite live region carrying the announcement instead.
+ */
+
+/** Callbacks the overlay reports pointer activity through. */
+interface OverlayOptions {
+    /** Called for every pointer record, already reduced and normalised. */
+    onPointer: (record: PointerRecord) => void;
+    /** Whether to render ripple and text feedback. */
+    feedback: boolean;
+}
+declare class GestureOverlay {
+    private container;
+    private options;
+    private el;
+    private zones;
+    private labels;
+    private live;
+    private styleEl;
+    private hideTimer;
+    private readonly pointerHandler;
+    constructor(container: HTMLElement, options: OverlayOptions);
+    /** Size the zones to match the recognizer's split. */
+    setZoneWidths(left: number, right: number): void;
+    /**
+     * Show the cumulative seek for a zone.
+     *
+     * @param zone - Which side was tapped
+     * @param seconds - Total seconds this sequence has moved
+     */
+    showSeek(zone: GestureZone, seconds: number): void;
+    /** Announce that a forward seek was refused because the viewer is at the live edge. */
+    announceLiveEdge(): void;
+    destroy(): void;
+    /** Exposed for tests and for hosts that want to inspect the surface. */
+    getElement(): HTMLElement;
+    private createZone;
+    private injectStyles;
+}
+
+/**
+ * Gestures Plugin for Scarlett Player
+ *
+ * Double-tap the right of the picture to jump forward, the left to jump back,
+ * and keep tapping to go further. This is the interaction every phone viewer
+ * already knows from YouTube, and on a PPV stream watched mostly on phones it
+ * is the difference between scrubbing blind and landing where you meant to.
+ *
+ * Touch only, by input type rather than user agent: a mouse or pen never
+ * triggers any of it, so desktop behaviour is unchanged.
+ *
+ * @example
+ * ```ts
+ * import { createGesturesPlugin } from '@scarlett-player/gestures';
+ *
+ * const player = new ScarlettPlayer({
+ *   container: '#player',
+ *   plugins: [uiPlugin(), createGesturesPlugin({ seekSeconds: 10 })],
+ * });
+ * ```
+ */
+
+/** Public surface, including the ownership hook the UI package checks. */
+interface GesturesPlugin extends Plugin {
+    /**
+     * Whether this plugin is handling taps right now.
+     *
+     * The UI package calls this before running its own show-controls logic on a
+     * touch interaction. Structural check, no package dependency in either
+     * direction.
+     */
+    ownsTapInteraction(): boolean;
+}
+/**
+ * Create a Gestures Plugin instance.
+ *
+ * @param config - Plugin configuration
+ * @returns Gestures Plugin instance
+ */
+declare function createGesturesPlugin(config?: GesturesPluginConfig): GesturesPlugin;
+
+export { DEFAULT_RECOGNIZER_OPTIONS, GestureOverlay, type GestureZone, type GesturesPlugin, type GesturesPluginConfig, type PointerRecord, type Recognizer, type RecognizerEvent, createGesturesPlugin, createRecognizer, createGesturesPlugin as default, zoneFor };

package/dist/index.d.ts

@@ -0,0 +1,266 @@
+import { Plugin } from '@scarlett-player/core';
+
+/**
+ * Types for the Gestures Plugin.
+ */
+/** Horizontal region of the gesture surface a pointer landed in. */
+type GestureZone = 'left' | 'middle' | 'right';
+/**
+ * A pointer event reduced to what the recognizer needs.
+ *
+ * Deliberately not a DOM event: the recognizer is a pure state machine, and
+ * every timing rule in it is testable without a browser.
+ */
+interface PointerRecord {
+    /** What happened. */
+    type: 'down' | 'move' | 'up' | 'cancel';
+    /** Horizontal position in CSS pixels, for slop measurement. */
+    x: number;
+    /** Vertical position in CSS pixels, for slop measurement. */
+    y: number;
+    /** Horizontal position as a fraction of the surface width, for zoning. */
+    fraction: number;
+    /** Pointer identity, so a second finger can be told apart from a retap. */
+    pointerId: number;
+    /** Event timestamp in milliseconds. */
+    timeStamp: number;
+}
+/** What the recognizer concluded from a stream of pointer records. */
+type RecognizerEvent = {
+    type: 'tap';
+    zone: GestureZone;
+} | {
+    type: 'double-tap';
+    zone: GestureZone;
+    count: number;
+} | {
+    type: 'accumulate';
+    zone: GestureZone;
+    count: number;
+} | {
+    type: 'cancel';
+};
+/** Recognizer tuning. */
+interface RecognizerOptions {
+    /** Milliseconds within which a second tap counts as a double tap. */
+    doubleTapWindowMs: number;
+    /** Milliseconds within which a further tap extends an active seek sequence. */
+    accumulationWindowMs: number;
+    /** Fraction of the width belonging to the left zone. */
+    leftZone: number;
+    /** Fraction of the width belonging to the right zone. */
+    rightZone: number;
+    /** Movement in CSS pixels that turns a tap into a drag and cancels it. */
+    slopPx: number;
+}
+/** Configuration for the Gestures Plugin. */
+interface GesturesPluginConfig {
+    /**
+     * Whether gestures are active.
+     *
+     * `'auto'` enables them when the device reports a coarse pointer, and every
+     * individual gesture is additionally checked for `pointerType === 'touch'`,
+     * so a touchscreen laptop works with a finger and is untouched by the mouse.
+     * Never UA sniffing.
+     *
+     * @defaultValue 'auto'
+     */
+    enabled?: boolean | 'auto';
+    /**
+     * Seconds moved per seek step.
+     *
+     * @defaultValue 10
+     */
+    seekSeconds?: number;
+    /**
+     * Milliseconds within which a second tap counts as a double tap.
+     *
+     * @defaultValue 275
+     */
+    doubleTapWindowMs?: number;
+    /**
+     * Milliseconds within which a further tap extends the current seek.
+     *
+     * @defaultValue 650
+     */
+    accumulationWindowMs?: number;
+    /**
+     * Fractions of the width given to the seek zones. The remainder in the middle
+     * is deliberately inert: a mistap in the centre of the picture should do
+     * nothing rather than jump the video.
+     *
+     * @defaultValue \{ left: 0.33, right: 0.33 \}
+     */
+    zones?: {
+        left?: number;
+        right?: number;
+    };
+    /**
+     * Movement in CSS pixels that cancels a tap.
+     *
+     * @defaultValue 10
+     */
+    slopPx?: number;
+    /**
+     * Show the ripple and seek amount.
+     *
+     * @defaultValue true
+     */
+    feedback?: boolean;
+    /**
+     * Vibrate on each seek step where the platform supports it. Android Chrome
+     * does; iOS Safari has no vibration API and silently ignores it.
+     *
+     * @defaultValue true
+     */
+    haptics?: boolean;
+    /**
+     * Let a single tap toggle the controls.
+     *
+     * @defaultValue true
+     */
+    tapToToggleControls?: boolean;
+    /** Index signature for PluginConfig compatibility */
+    [key: string]: unknown;
+}
+
+/**
+ * Gesture recognizer.
+ *
+ * A pure state machine. No DOM, no timers, no player: it consumes reduced
+ * pointer records and returns what they mean. Every timing and tolerance rule
+ * lives here so all of them are testable with plain numbers.
+ *
+ * The machine has three resting points:
+ *
+ * - idle: nothing in flight
+ * - awaiting-second: one tap landed, a second within the double-tap window
+ *   would make it a seek
+ * - accumulating: a seek is under way, and each further tap in the same zone
+ *   extends it, which is the behaviour every major player now shares
+ */
+
+declare const DEFAULT_RECOGNIZER_OPTIONS: RecognizerOptions;
+/** The recognizer's public surface. */
+interface Recognizer {
+    /** Feed one pointer record. Returns everything it concluded, in order. */
+    handle(record: PointerRecord): RecognizerEvent[];
+    /**
+     * Advance time without a pointer event, so expiry is observable.
+     *
+     * @param now - Current time in milliseconds
+     */
+    tick(now: number): RecognizerEvent[];
+    /** Drop all in-flight state, for example when the media source changed. */
+    reset(): void;
+    /** Whether a seek sequence is currently accumulating. */
+    isAccumulating(): boolean;
+}
+/**
+ * Work out which zone a horizontal position belongs to.
+ *
+ * @param fraction - Position as a fraction of the surface width
+ * @param options - Zone sizes
+ * @returns The zone
+ */
+declare function zoneFor(fraction: number, options: RecognizerOptions): GestureZone;
+/**
+ * Create a gesture recognizer.
+ *
+ * @param options - Tuning overrides
+ * @returns A recognizer instance
+ */
+declare function createRecognizer(options?: Partial<RecognizerOptions>): Recognizer;
+
+/**
+ * Gesture surface and feedback.
+ *
+ * Layering rules that matter, and why:
+ *
+ * - The surface sits above the gradient and below the control bar, so the
+ *   buttons and the progress bar keep every pixel they already own.
+ * - It never calls `preventDefault` or `stopPropagation` on a tap. The settings
+ *   and quality menus close via document-level click listeners; swallowing the
+ *   event would leave them stuck open.
+ * - Feedback elements are `pointer-events: none` and `aria-hidden`, with a
+ *   single polite live region carrying the announcement instead.
+ */
+
+/** Callbacks the overlay reports pointer activity through. */
+interface OverlayOptions {
+    /** Called for every pointer record, already reduced and normalised. */
+    onPointer: (record: PointerRecord) => void;
+    /** Whether to render ripple and text feedback. */
+    feedback: boolean;
+}
+declare class GestureOverlay {
+    private container;
+    private options;
+    private el;
+    private zones;
+    private labels;
+    private live;
+    private styleEl;
+    private hideTimer;
+    private readonly pointerHandler;
+    constructor(container: HTMLElement, options: OverlayOptions);
+    /** Size the zones to match the recognizer's split. */
+    setZoneWidths(left: number, right: number): void;
+    /**
+     * Show the cumulative seek for a zone.
+     *
+     * @param zone - Which side was tapped
+     * @param seconds - Total seconds this sequence has moved
+     */
+    showSeek(zone: GestureZone, seconds: number): void;
+    /** Announce that a forward seek was refused because the viewer is at the live edge. */
+    announceLiveEdge(): void;
+    destroy(): void;
+    /** Exposed for tests and for hosts that want to inspect the surface. */
+    getElement(): HTMLElement;
+    private createZone;
+    private injectStyles;
+}
+
+/**
+ * Gestures Plugin for Scarlett Player
+ *
+ * Double-tap the right of the picture to jump forward, the left to jump back,
+ * and keep tapping to go further. This is the interaction every phone viewer
+ * already knows from YouTube, and on a PPV stream watched mostly on phones it
+ * is the difference between scrubbing blind and landing where you meant to.
+ *
+ * Touch only, by input type rather than user agent: a mouse or pen never
+ * triggers any of it, so desktop behaviour is unchanged.
+ *
+ * @example
+ * ```ts
+ * import { createGesturesPlugin } from '@scarlett-player/gestures';
+ *
+ * const player = new ScarlettPlayer({
+ *   container: '#player',
+ *   plugins: [uiPlugin(), createGesturesPlugin({ seekSeconds: 10 })],
+ * });
+ * ```
+ */
+
+/** Public surface, including the ownership hook the UI package checks. */
+interface GesturesPlugin extends Plugin {
+    /**
+     * Whether this plugin is handling taps right now.
+     *
+     * The UI package calls this before running its own show-controls logic on a
+     * touch interaction. Structural check, no package dependency in either
+     * direction.
+     */
+    ownsTapInteraction(): boolean;
+}
+/**
+ * Create a Gestures Plugin instance.
+ *
+ * @param config - Plugin configuration
+ * @returns Gestures Plugin instance
+ */
+declare function createGesturesPlugin(config?: GesturesPluginConfig): GesturesPlugin;
+
+export { DEFAULT_RECOGNIZER_OPTIONS, GestureOverlay, type GestureZone, type GesturesPlugin, type GesturesPluginConfig, type PointerRecord, type Recognizer, type RecognizerEvent, createGesturesPlugin, createRecognizer, createGesturesPlugin as default, zoneFor };