@f8team/reel-core 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,846 @@
+/**
+ * Read-only view of the reactive store, handed to plugins via `PluginHost`.
+ * Plugins observe state but never mutate it directly.
+ */
+interface ReadableStore<T> {
+    /** Snapshot read. */
+    getState(): T;
+    /** Subscribe to a slice. The listener fires only when the slice changes (===). */
+    subscribe<U>(selector: (state: T) => U, listener: (value: U) => void): () => void;
+}
+/**
+ * Internal mutable store. Adapters never see this; only `createPlayer` does.
+ *
+ * @internal
+ */
+interface MutableStore<T> extends ReadableStore<T> {
+    /**
+     * Apply a partial update. Updates are coalesced inside one microtask, so
+     * multiple `setState` calls within the same tick fire one round of
+     * subscribers.
+     */
+    setState(patch: Partial<T> | ((current: T) => Partial<T>)): void;
+    /** Drop every subscriber. */
+    dispose(): void;
+}
+
+/**
+ * Reactive store with microtask-batched updates and selector subscriptions.
+ *
+ * Design goals:
+ * - **Tiny**: ~30 lines of logic, no external runtime.
+ * - **Predictable**: subscribers fire synchronously after the microtask flush.
+ *   Multiple `setState` calls in the same tick fire one round of subscribers.
+ * - **Selector-aware**: a subscriber registered with a selector only re-runs
+ *   when its selected slice changes (`Object.is` equality by default).
+ */
+
+/**
+ * Optional knobs handed to `createStore`.
+ *
+ * The generic `T` is unused at the type level today, but it locks the option
+ * shape to a specific store so future per-state hooks (e.g. `selectorOf`)
+ * stay backwards-compatible.
+ */
+interface CreateStoreOptions<_T> {
+    /**
+     * Override the global microtask scheduler (used by tests so the store
+     * can flush synchronously). Default: `queueMicrotask`.
+     */
+    scheduleFlush?: (run: () => void) => void;
+    /** Custom equality at the store level, used by `subscribe` if none is passed. */
+    isEqual?: <U>(a: U, b: U) => boolean;
+}
+
+/**
+ * Player error contract. Surfaced through the `error` event and `state.error`.
+ *
+ * Golden cases: G13 (unauthorized HLS), every error path in G1..G16.
+ */
+/** Stable error codes. The string literal IS the public contract. */
+type PlayerErrorCode = "source" | "network" | "decode" | "unauthorized" | "unsupported" | "internal";
+/**
+ * Structured player error. Adapters render the message; plugins can inspect
+ * `code`, `status`, and `retryable` to decide on retry/UI strategy.
+ */
+interface PlayerError {
+    /** Stable code. */
+    code: PlayerErrorCode;
+    /** Human-readable message. Adapters MAY localize. */
+    message: string;
+    /** Optional underlying cause (`Error`, `MediaError`, `Hls.errors.*`). */
+    cause?: unknown;
+    /** HTTP status, when the error came from an XHR (G13). */
+    status?: number;
+    /** Failing URL, when known. */
+    url?: string;
+    /** Whether the consumer can usefully retry (e.g. transient network). */
+    retryable: boolean;
+}
+
+/**
+ * Media source descriptors and related contracts.
+ *
+ * Every adapter and plugin compiles against the public types declared here.
+ * @see {@link ../../docs/spec/api-contract.md} for the frozen contract.
+ */
+/**
+ * Subtitle / captions track attached to the underlying `<video>`.
+ *
+ * Maps to a `<track kind="subtitles">` child. Default-language priority is
+ * implemented in the `subtitles` plugin (see G1, G15).
+ *
+ * Golden cases: G1 (course learning), G15 (VTT cross-origin).
+ */
+interface SubtitleTrack {
+    /** VTT URL. The BE must respond with `Access-Control-Allow-Origin: *` (G15). */
+    src: string;
+    /** BCP-47 language code (e.g. `"vi"`, `"en-US"`). */
+    srcLang: string;
+    /** Human-readable label (e.g. `"Tiếng Việt"`). */
+    label: string;
+    /** When `true`, this track wins the default-selection vote unconditionally. */
+    default?: boolean;
+}
+/**
+ * Sprite thumbnails (timeline hover preview) descriptor.
+ *
+ * The `src` URL must point to a WebVTT file whose cues map a time range to a
+ * sprite tile, e.g.:
+ *
+ * ```
+ * WEBVTT
+ *
+ * 00:00:00.000 --> 00:00:10.000
+ * sprites/00001.jpg#xywh=0,0,160,90
+ * ```
+ *
+ * Image URLs in the cue body may be absolute or relative; relative paths are
+ * resolved against the VTT URL. The `@f8team/reel-plugin-thumbnails` plugin
+ * fetches and parses the VTT, then exposes a `thumbnails:getAt(time)` command
+ * consumed by the React/Lit `SeekBar` hover preview.
+ */
+interface ThumbnailsDescriptor {
+    /** Absolute VTT URL describing sprite cues. */
+    src: string;
+    /**
+     * Send credentials when fetching the VTT (and resolved sprite images
+     * when the browser permits). Defaults to `false`.
+     */
+    withCredentials?: boolean;
+}
+/**
+ * The kind of source. `auto` lets the registry pick.
+ *
+ * - `hls` — HLS m3u8 manifest, dispatched to `hls.js` (or native on Safari).
+ * - `mp4` — Progressive MP4/WebM, dispatched to the native engine.
+ * - `youtube` — YouTube IFrame API.
+ * - `dash` — MPEG-DASH (reserved for a future dash provider).
+ * - `native` — Force the native engine even if the URL looks like HLS (G4 Safari escape).
+ * - `auto` — Detect from the URL via `looksLikeHls` / `detectSourceType`.
+ */
+type SourceType = "auto" | "hls" | "mp4" | "youtube" | "dash" | "native";
+/**
+ * Single playable source. The registry picks the right provider based on
+ * `type` and the URL.
+ *
+ * Golden cases: G1, G2, G3, G4, G5, G7, G10, G11, G14.
+ */
+interface SourceDescriptor {
+    /** Absolute or relative URL. May be a `blob:`, `data:`, or `http(s):` URL. */
+    src: string;
+    /** Optional explicit type hint. Defaults to `"auto"`. */
+    type?: SourceType;
+    /**
+     * Cookie / credentials policy for HLS XHRs.
+     *
+     * - `boolean` — sent for every request.
+     * - `(url) => boolean` — predicate (e.g. allowlist `https://api-gateway*`, see G7, G13).
+     */
+    withCredentials?: boolean | ((url: string) => boolean);
+    /** Subtitle tracks to attach (G1, G15). */
+    tracks?: SubtitleTrack[];
+    /**
+     * Sprite-thumbnails VTT descriptor for timeline hover previews. When set,
+     * the `@f8team/reel-plugin-thumbnails` plugin fetches and parses the VTT;
+     * the `Controls.SeekBar` (React) and the Lit default chrome render a tile
+     * tooltip during pointer hover.
+     */
+    thumbnails?: ThumbnailsDescriptor;
+}
+/**
+ * One quality variant exposed by the engine (HLS levels, DASH representations).
+ *
+ * Golden case: G7 (course video lesson editor).
+ */
+interface QualityLevel {
+    /** Stable identifier produced by the loader (e.g. HLS level index). */
+    id: string;
+    /** Vertical resolution in pixels (e.g. `720`). */
+    height: number;
+    /** Average bitrate in bits per second. */
+    bitrate: number;
+    /** Display label (e.g. `"720p"`, `"Auto"`). */
+    label: string;
+}
+/**
+ * Imperative loader returned by a `SourceProvider`. The core attaches a single
+ * loader at a time; switching sources detaches the previous loader before
+ * attaching the new one.
+ */
+interface SourceLoader {
+    /** Attach the source to the underlying `<video>`. Resolves on `loadedmetadata`. */
+    attach(video: HTMLVideoElement, source: SourceDescriptor): Promise<void>;
+    /** Detach the source. Called before the next `attach` and on `dispose`. */
+    detach(): void;
+    /**
+     * Optional: cancel any in-flight network work without tearing down the
+     * already-attached media element. The core calls this on rapid
+     * `setSource(A) → setSource(B)` transitions so the pending A loader can
+     * stop firing callbacks before `detach()` executes.
+     *
+     * Implementations should:
+     *   - Abort outstanding XHRs / `fetch` requests.
+     *   - Reject the pending `attach()` Promise with an `AbortError`.
+     *   - Remove any listeners whose only purpose is to resolve that Promise.
+     *
+     * `abort()` MUST be safe to call before `detach()`, after `detach()`, and
+     * multiple times. Leave actual media-element / runtime cleanup to `detach()`.
+     */
+    abort?(): void;
+    /** Optional: enumerate available quality levels (HLS, DASH). */
+    getQualities?(): QualityLevel[];
+    /** Optional: switch quality. `"auto"` re-enables ABR. */
+    setQuality?(level: QualityLevel | "auto"): void;
+}
+/**
+ * Provider that knows how to handle a class of sources (HLS, native, YouTube).
+ */
+interface SourceProvider {
+    /** Identifier used by `unregisterSource` and debug output. */
+    name: string;
+    /**
+     * Decide whether this provider can handle the given source.
+     *
+     * - `true` — definite match.
+     * - `"maybe"` — handle if no `true` match exists (used by the native fallback).
+     * - `false` — skip.
+     */
+    canHandle(source: SourceDescriptor): boolean | "maybe";
+    /** Construct a fresh loader. Called once per source attach. */
+    createLoader(): SourceLoader;
+}
+
+/**
+ * `unauthorized` event payload. Surfaced once per `source.src` for HLS XHRs
+ * that end with HTTP 401 or 403 (G13).
+ */
+interface UnauthorizedEvent {
+    /** Failing URL (manifest or segment). */
+    url: string;
+    /** Always 401 or 403. */
+    status: 401 | 403;
+    /** The source that triggered the failure. */
+    source: SourceDescriptor;
+}
+/**
+ * Built-in player events. Plugin events use the `${string}:${string}` form
+ * (e.g. `subtitles:change`, `markers:hover`); they pass through the bus
+ * untyped because plugins are loaded dynamically.
+ *
+ * Golden cases:
+ * - G1: `timeupdate` powers the 500 ms `onProgress` aggregation.
+ * - G2: `play`, `pause`, `ended` drive story progress segments.
+ * - G7: `qualitychange` fires when the lesson editor flips levels.
+ * - G13: `unauthorized` triggers the auth callback.
+ */
+interface PlayerEvents {
+    /** Source loaded; metadata and duration are now valid. */
+    ready: {
+        duration: number;
+    };
+    /** Playback started (or resumed). */
+    play: void;
+    /** Playback paused (user, programmatic, or background). */
+    pause: void;
+    /** Media ended. */
+    ended: void;
+    /**
+     * Time progress. Fires on every native `timeupdate`; plugins can throttle.
+     *
+     * - `currentTime` — wall-clock playback position.
+     * - `playedSeconds` — alias kept for parity with the legacy F8 player.
+     * - `duration` — current duration (matches `state.duration`).
+     */
+    timeupdate: {
+        currentTime: number;
+        playedSeconds: number;
+        duration: number;
+    };
+    /** Duration changed (live HLS, source switch). */
+    durationchange: {
+        duration: number;
+    };
+    /** Playback rate changed (G7). */
+    ratechange: {
+        playbackRate: number;
+    };
+    /** Volume or mute flipped. */
+    volumechange: {
+        volume: number;
+        muted: boolean;
+    };
+    /** Seek started (user or programmatic). */
+    seeking: {
+        time: number;
+    };
+    /** Seek finished. */
+    seeked: {
+        time: number;
+    };
+    /** Buffering toggled. `isBuffering=true` means stalled (`waiting`), including after a seek scrub. */
+    buffering: {
+        isBuffering: boolean;
+    };
+    /** Quality level changed. `auto=true` means ABR picked it. */
+    qualitychange: {
+        quality: QualityLevel | null;
+        auto: boolean;
+    };
+    /**
+     * User explicitly chose a rendition via `hls:setQuality` (manual height or
+     * auto when `qualityHeight` is `null`). Does **not** fire on source attach or
+     * ABR-driven switches — safe for persisting preferences without clobbering.
+     */
+    qualitypreference: {
+        qualityHeight: number | null;
+    };
+    /**
+     * Manual HLS rendition switch in flight (manual level or AUTO). Clears once
+     * hls.js reports `LEVEL_SWITCHED` for the awaited target / auto step, or after
+     * a safety timeout. Use for a transient center spinner.
+     */
+    qualityswitch: {
+        active: boolean;
+    };
+    /** Any error (transport, decode, source). */
+    error: PlayerError;
+    /** Authentication failure (G13). Fires at most once per source.src. */
+    unauthorized: UnauthorizedEvent;
+    /** Fullscreen toggled. */
+    fullscreenchange: {
+        fullscreen: boolean;
+    };
+    /** Picture-in-Picture toggled. */
+    pipchange: {
+        pip: boolean;
+    };
+}
+
+/**
+ * Lifecycle status of the player. The state machine guarantees these
+ * transitions; see `docs/spec/architecture.md` for the transition diagram.
+ */
+type PlayerStatus = "idle" | "loading" | "ready" | "playing" | "paused" | "ended" | "error";
+/** Buffered range (start/end in seconds). */
+interface BufferedRange {
+    start: number;
+    end: number;
+}
+/**
+ * Snapshot of the player's reactive state. Every adapter renders against
+ * either the snapshot (`getState()`) or a memoized selector via `subscribe`.
+ *
+ * Golden cases: G7 (qualities, playback rate), G8 (currentTime/duration drives
+ * seek bar), G13 (error.code === "unauthorized"), G14 (videoWidth/Height
+ * confirm playback started inline on iOS).
+ */
+interface PlayerState {
+    /** Lifecycle status; never overlapping. */
+    status: PlayerStatus;
+    /** Active source. `null` until `setSource` is called. */
+    source: SourceDescriptor | null;
+    /** Current playback position in seconds. */
+    currentTime: number;
+    /** Media duration in seconds. `0` while loading; `Infinity` for live HLS. */
+    duration: number;
+    /** Buffered ranges in seconds. */
+    buffered: BufferedRange[];
+    /** Playback rate (`1` is normal speed). G7 lists [0.25..1.75]. */
+    playbackRate: number;
+    /** Volume on the `[0, 1]` scale. */
+    volume: number;
+    /** Whether the underlying `<video>` is muted. */
+    muted: boolean;
+    /** Native video width (after `loadedmetadata`). */
+    videoWidth: number;
+    /** Native video height (after `loadedmetadata`). */
+    videoHeight: number;
+    /** Whether Picture-in-Picture is currently active. */
+    pip: boolean;
+    /** Whether the document/element is in fullscreen. */
+    fullscreen: boolean;
+    /** Quality levels exposed by the loader (G7). Empty for native engines. */
+    qualities: QualityLevel[];
+    /** Active quality level. `null` while ABR is auto / loader does not expose levels. */
+    activeQuality: QualityLevel | null;
+    /** Latest error, if any. Cleared on `setSource` or successful retry. */
+    error: PlayerError | null;
+}
+
+/**
+ * Disposer returned by every subscription / listener helper. Idempotent.
+ */
+type Disposer = () => void;
+/**
+ * Public Player surface. Returned by `createPlayer(options)`.
+ *
+ * Lifecycle: `createPlayer` → `attach(<video>)` → use → `detach` (optional)
+ * → `dispose`. After `dispose`, every subsequent call is a no-op (or throws,
+ * for clearly invalid use).
+ *
+ * Golden cases:
+ * - G12: `play / pause / paused / seekTo` shape-conform with `VideoPlayerHandle`.
+ * - G7: `setPlaybackRate`, `setVolume`, `setMuted`.
+ * - G8: `seekTo` accepts seconds; the React adapter additionally accepts `"00:01:23"`.
+ */
+interface Player {
+    /** Replace (or clear) the active source. */
+    setSource(source: SourceDescriptor | null): void;
+    /** Snapshot of the active source. */
+    getSource(): SourceDescriptor | null;
+    /**
+     * Re-attempt loading the current source. No-op if no source is set.
+     *
+     * Internally equivalent to `setSource(getSource())`: the state machine
+     * detaches the failed loader, clears the error, and starts a fresh
+     * `loading → ready` cycle. Use this from a "Try again" button on an
+     * error overlay.
+     *
+     * @returns `true` when retry was dispatched, `false` when there was
+     *  nothing to retry.
+     */
+    retry(): boolean;
+    /** Start playback. May reject (autoplay policy, no source, dispose). */
+    play(): Promise<void>;
+    /** Pause playback. */
+    pause(): void;
+    /** Whether the player is paused. */
+    paused(): boolean;
+    /** Seek to a time in seconds. Clamped to `[0, duration]`. */
+    seekTo(seconds: number): void;
+    /** Set playback rate. */
+    setPlaybackRate(rate: number): void;
+    /** Set volume on `[0, 1]`. */
+    setVolume(volume: number): void;
+    /** Set muted state. */
+    setMuted(muted: boolean): void;
+    /** Snapshot read of the full state. */
+    getState(): PlayerState;
+    /** Current playback position in seconds. */
+    getCurrentTime(): number;
+    /** Current duration in seconds. */
+    getDuration(): number;
+    /** Buffered ranges. */
+    getBuffered(): BufferedRange[];
+    /**
+     * Subscribe to a built-in event. Returns a disposer.
+     *
+     * Plugin events (`subtitles:change`, etc.) ride the same bus but lose
+     * type-safety because they are loaded dynamically. Plugins augment via
+     * declaration-merging if they need typed events.
+     */
+    on<K extends keyof PlayerEvents>(event: K, handler: (payload: PlayerEvents[K]) => void): Disposer;
+    /** Remove an event handler. */
+    off<K extends keyof PlayerEvents>(event: K, handler: (payload: PlayerEvents[K]) => void): void;
+    /** Subscribe to a slice of state. The listener fires only when the slice changes (===). */
+    subscribe<T>(selector: (state: PlayerState) => T, listener: (value: T) => void): Disposer;
+    /** Register a plugin after construction. */
+    use(plugin: PluginInstance): void;
+    /** Remove a plugin by name. Calls its teardown. */
+    removePlugin(name: string): void;
+    /** Shared command registry. */
+    commands: CommandRegistry;
+    /** Attach to a `<video>` element. Resolves once `loadedmetadata` fires. */
+    attach(el: HTMLVideoElement): Promise<void>;
+    /** Detach from the current `<video>` without disposing the player. */
+    detach(): void;
+    /** Dispose every resource. After this, the player is dead. */
+    dispose(): void;
+}
+
+/**
+ * Command registry shared between the player and plugins. Commands are the
+ * extension point for keyboard handlers, plugin contributions, and UI buttons.
+ */
+interface CommandRegistry {
+    /**
+     * Register a command. Returns a disposer.
+     *
+     * Commands MUST be namespaced with a `<plugin>:<verb>` form
+     * (e.g. `markers:seek`). Built-in commands use the `core:` prefix.
+     *
+     * Re-registering an identical name throws.
+     */
+    add<P = void>(name: string, handler: (payload: P) => void): () => void;
+    /** Run a command. No-op if the command does not exist (idempotent). */
+    run<P = void>(name: string, payload?: P): void;
+    /** Whether the command exists. */
+    has(name: string): boolean;
+}
+/**
+ * Plugin host handed to each plugin's `setup` function. Provides the only
+ * sanctioned ways to extend the player (controls, commands, store, events).
+ */
+interface PluginHost {
+    controls: {
+        /**
+         * Contribute a UI fragment to a slot owned by an adapter (e.g. `seekbar.overlay`,
+         * `menu.settings`). Adapters render the returned `Element` directly.
+         *
+         * Returns a disposer. Plugins SHOULD store the disposer and call it on
+         * cleanup; the player calls every disposer on `dispose`.
+         */
+        contribute(slot: string, render: () => Element): () => void;
+    };
+    /** Shared command registry. Plugins MUST namespace their commands. */
+    commands: CommandRegistry;
+    /** Read-only state. */
+    store: ReadableStore<PlayerState>;
+    /** Emit a custom plugin event. Use the `${plugin}:${verb}` namespace. */
+    emit<K extends string>(event: K, payload?: unknown): void;
+}
+/**
+ * Plugin instance. The factory pattern (`subtitles({ defaultLang })`) returns
+ * an instance.
+ */
+interface PluginInstance {
+    /** Unique name. Re-registering the same name throws. */
+    readonly name: string;
+    /**
+     * Setup hook. Called once when the plugin is registered (either via
+     * `PlayerOptions.plugins` or `player.use(...)`).
+     *
+     * Optional return value: a teardown function called on `removePlugin` or
+     * `dispose`.
+     */
+    setup(player: Player, host: PluginHost): void | (() => void);
+}
+
+/**
+ * Theme tokens. Every visible token is a CSS custom property that adapters
+ * inject via `style` or scoped CSS. Phase 1 ships the type only; Phase 1.K
+ * defines the runtime token defaults; Phase 3 ships the four shipping themes
+ * (`classroom`, `story`, `admin`, `minimal`).
+ */
+type ThemeName = "classroom" | "story" | "admin" | "minimal";
+/**
+ * Subset of overridable design tokens. Adapters merge a partial set into the
+ * defaults at runtime.
+ */
+interface ThemeTokens {
+    "color-bg"?: string;
+    "color-fg"?: string;
+    "color-accent"?: string;
+    "color-overlay"?: string;
+    "control-size"?: string;
+    "control-radius"?: string;
+    "control-gap"?: string;
+    "control-padding"?: string;
+    "focus-ring-color"?: string;
+    "focus-ring-width"?: string;
+    "seekbar-height"?: string;
+    "seekbar-buffered"?: string;
+    "seekbar-played"?: string;
+    "seekbar-knob-size"?: string;
+    "font-family"?: string;
+    "font-size-sm"?: string;
+    "font-size-md"?: string;
+    "motion-fast"?: string;
+    "motion-base"?: string;
+}
+
+/**
+ * Autoplay policy.
+ *
+ * - `off` (default) — never auto-play.
+ * - `muted` — `play()` after `attach`, with `muted = true` (browser-friendly).
+ * - `on` — attempt to play with the current `muted` state. May reject.
+ */
+type AutoplayMode = "off" | "muted" | "on";
+/**
+ * Keyboard scope.
+ *
+ * - `global` — listen on `document.body` (default — G1, G3).
+ * - `container` — listen on the player root only (G16 — embedded surfaces).
+ * - `off` — no built-in handlers (G2 story owns its own keys).
+ */
+type KeyboardScope = "global" | "container" | "off";
+/**
+ * Hooks called once per source / event. Hooks are sticky listeners — they
+ * survive across renders / state updates because they live on the player
+ * instance.
+ */
+interface PlayerHooks {
+    /**
+     * Authenticated HLS / DASH XHR ended with 401 or 403 (G13). The legacy
+     * F8 alias `onStreamUnauthorized` maps to this hook in `f8-ui`.
+     */
+    onUnauthorized?: (event: UnauthorizedEvent) => void;
+    /** Any error (transport, decode, source). */
+    onError?: (error: PlayerError) => void;
+}
+/**
+ * Options accepted by `createPlayer(options)`.
+ *
+ * Every field is optional. The player attaches with no source until
+ * `setSource` is called or `options.source` is provided.
+ */
+interface PlayerOptions {
+    /** Initial source. Omit to attach without playable media. */
+    source?: SourceDescriptor;
+    /** Autoplay policy. Defaults to `"off"`. */
+    autoplay?: AutoplayMode;
+    /** Seconds to seek to on first ready. */
+    startTime?: number;
+    /** Whether to loop on `ended`. */
+    loop?: boolean;
+    /** Initial muted state. Defaults to `false` (or `true` if autoplay is `muted`). */
+    muted?: boolean;
+    /** Initial volume on `[0, 1]`. */
+    volume?: number;
+    /** Initial playback rate. */
+    playbackRate?: number;
+    /** Poster URL — passed to `<video poster>`. */
+    poster?: string;
+    /** `<video preload>`. */
+    preload?: "auto" | "metadata" | "none";
+    /** iOS inline playback (G2, G14). Defaults to `true`. */
+    playsInline?: boolean;
+    /**
+     * `<video crossorigin>`. Defaults to `"anonymous"` (T3.5) so WebVTT tracks
+     * load with valid CORS, HLS segments can be fetched with `withCredentials`,
+     * and `<canvas drawImage(video)>` does not taint the canvas.
+     *
+     * Pass `null` explicitly to omit the attribute (rare — only for legacy
+     * embeds where the response lacks `Access-Control-Allow-Origin`).
+     */
+    crossOrigin?: "anonymous" | "use-credentials" | null;
+    /** Plugins to register synchronously at `createPlayer` time. */
+    plugins?: PluginInstance[];
+    /** Theme name or runtime token overrides. */
+    theme?: ThemeName | ThemeTokens;
+    /** Lifecycle hooks. */
+    hooks?: PlayerHooks;
+    /** Keyboard scoping. Adapters may override per-mount (G16). */
+    keyboard?: {
+        scope?: KeyboardScope;
+    };
+}
+
+/**
+ * `createPlayer(options)` — wires every piece of `@f8team/reel-core` into a
+ * single `Player`. The factory is the one and only public entry point.
+ *
+ * Responsibilities:
+ *   1. Build the reactive store seeded with the initial PlayerOptions.
+ *   2. Build the event bus, command registry, controls registry, plugin bus.
+ *   3. Register the always-on native source provider (and HLS / YouTube
+ *      providers with callbacks bound to this player's store and bus).
+ *   4. Bridge `<video>` events ⇄ the state-machine reducer.
+ *   5. Apply machine effects (attach/detach source, mediaPlay/Pause/Seek,
+ *      clearError/setError) against the live `<video>` element.
+ *   6. Expose the `Player` interface defined in
+ *      `docs/spec/api-contract.md`.
+ *
+ * Tests live next to this file and validate the external behavior; lower-level
+ * pieces (store, machine, sources, plugins, etc.) are covered by their own
+ * unit tests.
+ */
+
+/** @internal — extra knobs surfaced for tests and adapters. */
+interface CreatePlayerInternalOptions {
+    /** Override the microtask scheduler for the store. Tests use this. */
+    storeOptions?: CreateStoreOptions<PlayerState>;
+    /** Inject extra source providers (e.g. dash, in-house DRM). */
+    extraProviders?: SourceProvider[];
+}
+/**
+ * Build a fresh `Player`. Safe to construct in the browser, jsdom, or
+ * server-rendering tests (only `attach()` touches the DOM).
+ */
+declare function createPlayer(options?: PlayerOptions, internal?: CreatePlayerInternalOptions): Player;
+
+/**
+ * Identity helper used by plugin authors so editors get type narrowing
+ * on `setup` arguments without typing `as PluginInstance` at every call site.
+ *
+ * @example
+ * const subtitles = definePlugin({
+ *   name: "subtitles",
+ *   setup: (player, host) => { ... },
+ * });
+ */
+
+declare function definePlugin(spec: PluginInstance): PluginInstance;
+
+/**
+ * Apply theme tokens to an element's `style`.
+ *
+ * Adapters call this once per mount and again whenever the theme prop changes.
+ * Plugins can overlay extra tokens through the same helper.
+ */
+
+interface ApplyThemeArgs {
+    /** Theme preset name. `undefined` skips preset application. */
+    preset?: ThemeName;
+    /** Extra token overrides. Wins over the preset. */
+    overrides?: ThemeTokens;
+    /** Whether to apply the neutral defaults first. Default: `true`. */
+    applyDefaults?: boolean;
+}
+/**
+ * Resolve a final token map by layering defaults → preset → overrides.
+ */
+declare function resolveTokens(args?: ApplyThemeArgs): Partial<ThemeTokens>;
+/**
+ * Apply tokens to `element.style`. Returns a disposer that resets the
+ * variables to their previous values (useful for adapters that need to
+ * roll back on theme change).
+ */
+declare function applyTheme(element: HTMLElement, args?: ApplyThemeArgs): () => void;
+
+/**
+ * Default token values. Phase 3 ships theme CSS files (`classroom.css`,
+ * `story.css`, `admin.css`, `minimal.css`) that override these via class
+ * selectors. The defaults below are intentionally neutral so an unstyled
+ * player still looks reasonable.
+ */
+
+/**
+ * Token name → CSS custom property name. Adapters write to the variable
+ * directly so consumers can also use plain CSS to override.
+ */
+declare const TOKEN_TO_CSS_VAR: Record<keyof ThemeTokens, string>;
+/**
+ * Neutral default tokens. Adapters apply these on the player root before any
+ * theme class wins. Values use `1rem = 10px` (F8 frontends use the 62.5%
+ * font-size convention).
+ */
+declare const DEFAULT_TOKENS: Required<ThemeTokens>;
+/** Built-in theme presets. Phase 3 packages the CSS counterpart. */
+declare const THEME_PRESETS: Record<ThemeName, ThemeTokens>;
+
+/**
+ * Single shared off-screen `aria-live` region. Adapters / plugins call
+ * `announce("Subtitles on")` to push messages to assistive tech without
+ * jumping focus.
+ *
+ * The region is created lazily (so SSR-only consumers pay nothing) and
+ * polite by default. Screen readers respect rate-limit conventions, so
+ * announcements queue up and read sequentially.
+ */
+/**
+ * Announce a message to assistive tech. No-op outside the browser.
+ *
+ * Subsequent calls with the same string force a fresh DOM mutation (we
+ * blank the region for one frame) so screen readers re-read identical
+ * messages — useful for repeated state toggles like Mute on/off.
+ */
+declare function announce(message: string): void;
+
+/**
+ * Minimal focus trap helper.
+ *
+ * Used by adapters in fullscreen so Tab / Shift+Tab stays inside the player.
+ * Not a replacement for full focus-management libraries (focus-trap-react)
+ * — but enough for the player's small, well-known interactive surface.
+ */
+interface FocusTrap {
+    /** Activate the trap. Optionally focuses the first focusable. */
+    activate(opts?: {
+        focusFirst?: boolean;
+    }): void;
+    /** Deactivate. Optionally restores focus to the previously focused element. */
+    deactivate(opts?: {
+        restoreFocus?: boolean;
+    }): void;
+}
+/**
+ * Build a focus trap rooted at `container`.
+ *
+ * The trap installs a `keydown` listener and rotates focus among the
+ * descendants matching `FOCUSABLE_SELECTOR` when Tab/Shift+Tab fires near
+ * the boundary.
+ */
+declare function createFocusTrap(container: HTMLElement): FocusTrap;
+
+/**
+ * Time helpers shared by the seek bar, transcript markers (G8), and the
+ * keyboard / commands layer.
+ */
+/**
+ * Parse a time string like `"00:01:23"`, `"1:23"`, `"00:01:23.456"` to seconds.
+ * Returns `NaN` for invalid input — callers should guard.
+ *
+ * Accepted forms:
+ * - `"H:MM:SS"` / `"H:MM:SS.fff"`
+ * - `"M:SS"` / `"MM:SS"` / `"MM:SS.fff"`
+ *
+ * Anything else (including bare numbers, negative values, NaN strings) is
+ * `NaN`. Callers that want to accept numbers SHOULD test `typeof === "number"`
+ * first.
+ */
+declare function parseTime(input: string): number;
+/**
+ * Format seconds to `H:MM:SS` (when ≥ 1h) or `MM:SS` (otherwise). NaN /
+ * negative inputs are coerced to `0:00`.
+ *
+ * The ARIA-friendly verbose form (`"1 hour 2 minutes"`) is the adapter's job.
+ */
+declare function formatTime(seconds: number): string;
+/**
+ * Coerce a time-like input to seconds. Accepts numbers, formatted strings,
+ * and clamps negatives to 0.
+ *
+ * Returns `NaN` if the input cannot be coerced (so callers can refuse to
+ * call `seekTo` rather than seeking to 0 silently).
+ */
+declare function toSeconds(input: number | string): number;
+
+/**
+ * URL helpers used by the source registry to dispatch a source descriptor to
+ * the right provider. Pure string predicates — no DOM, no I/O.
+ */
+
+/**
+ * Heuristic for HLS m3u8 URLs.
+ *
+ * Accepts:
+ * - `*.m3u8` (case-insensitive) at any path/query position
+ * - `application/vnd.apple.mpegurl` MIME hints inside `?type=`
+ *
+ * Rejects:
+ * - YouTube-hosted m3u8 (handled by the YouTube provider).
+ * - Empty / non-string inputs.
+ */
+declare function looksLikeHls(input: string | undefined | null): boolean;
+/**
+ * YouTube URL recognition. Matches `youtube.com/watch?v=`, `youtu.be/<id>`,
+ * `youtube.com/embed/<id>`, and `youtube.com/shorts/<id>`.
+ */
+declare function looksLikeYouTube(input: string | undefined | null): boolean;
+/**
+ * MP4 / WebM / Ogg recognition by extension or `blob:` / `data:` schemes.
+ */
+declare function looksLikeProgressive(input: string | undefined | null): boolean;
+/**
+ * Resolve the effective `SourceType` for a descriptor.
+ *
+ * Honors an explicit non-`auto` type. For `auto`, dispatch by URL: HLS first,
+ * then YouTube, then progressive, falling back to `native` (which dispatches
+ * to the always-on native loader).
+ */
+declare function detectSourceType(source: SourceDescriptor): SourceType;
+
+export { type AutoplayMode, type BufferedRange, type CommandRegistry, DEFAULT_TOKENS, type Disposer, type KeyboardScope, type MutableStore, type Player, type PlayerError, type PlayerErrorCode, type PlayerEvents, type PlayerHooks, type PlayerOptions, type PlayerState, type PlayerStatus, type PluginHost, type PluginInstance, type QualityLevel, type ReadableStore, type SourceDescriptor, type SourceLoader, type SourceProvider, type SourceType, type SubtitleTrack, THEME_PRESETS, TOKEN_TO_CSS_VAR, type ThemeName, type ThemeTokens, type ThumbnailsDescriptor, type UnauthorizedEvent, announce, applyTheme, createFocusTrap, createPlayer, definePlugin, detectSourceType, formatTime, looksLikeHls, looksLikeProgressive, looksLikeYouTube, parseTime, resolveTokens, toSeconds };