docs(react): clarify usePlayer typed vs untyped store access (#1663)

packages/react/src/player/context.tsx

@@ -45,12 +45,20 @@ export function usePlayerContext(): PlayerContextValue {
 /**
  * Access the player store from within a Player Provider.
  *
+ * This standalone hook has no knowledge of your configured features, so it
+ * returns an untyped `UnknownStore` whose state properties are typed as
+ * `unknown`. For typed access, use the `usePlayer` returned by `createPlayer()`,
+ * or pass a premade selector to recover the type from its return value.
+ *
  * @label Without Selector
  */
 export function usePlayer(): UnknownStore;
 /**
  * Select a value from the player store. Re-renders when the selected value changes.
  *
+ * The selector receives `UnknownState`, so an inline selector returns `unknown`.
+ * Pass a premade selector (e.g. `selectPlayback`) to get a typed result.
+ *
  * @label With Selector
  * @param selector - Derives a value from the player store state.
  */

site/src/content/docs/reference/use-player.mdx

@@ -15,7 +15,16 @@ import SelectorDemoReact from "@/components/docs/demos/use-player/react/css/Sele
 import selectorReactTsx from "@/components/docs/demos/use-player/react/css/Selector.tsx?raw";
 import selectorReactCss from "@/components/docs/demos/use-player/react/css/Selector.css?raw";
 
-`Player.usePlayer` gives you access to the player store from any component within a `Player.Provider`. It has two overloads — without arguments for direct store access, or with a selector for reactive state subscriptions. `Player.usePlayer` is typed to the features you passed to <DocsLink slug="reference/create-player">`createPlayer`</DocsLink>. It's also available as a standalone import (`import { usePlayer } from '@videojs/react'`), but the standalone version returns an untyped store.
+`Player.usePlayer` (from <DocsLink slug="reference/create-player">`createPlayer`</DocsLink>) gives you access to the player store from any component within a `Player.Provider`. It's typed to the features you passed to `createPlayer`, and has two overloads — without arguments for direct store access, or with a selector for reactive state subscriptions.
+
+`usePlayer` is also available as a standalone import (`import { usePlayer } from '@videojs/react'`), but the standalone version returns an untyped `UnknownStore`. Pass a premade selector to recover typing:
+
+```tsx
+import { usePlayer, selectPlayback } from '@videojs/react';
+
+usePlayer();               // UnknownStore (state: unknown)
+usePlayer(selectPlayback); // PlaybackState | undefined
+```
 
 ## Examples