feat(site): add util reference pipeline (#537)

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

packages/html/src/player/context.ts

@@ -10,4 +10,9 @@ export type PlayerContext<Store extends PlayerStore = AnyPlayerStore> = Context<
   PlayerContextValue<Store>
 >;
 
+/**
+ * The default player context instance for consuming the player store in controllers.
+ *
+ * @public
+ */
 export const playerContext = createContext<PlayerContextValue, typeof PLAYER_CONTEXT_KEY>(PLAYER_CONTEXT_KEY);

packages/html/src/player/create-player.ts

@@ -67,11 +67,26 @@ export interface CreatePlayerResult<Store extends PlayerStore> {
  *   #playback = new PlayerController(this, context, selectPlayback);
  * }
  * ```
+ *
+ * @label Video
+ * @param config - Player configuration with features.
  */
 export function createPlayer(config: CreatePlayerConfig<VideoFeatures>): CreatePlayerResult<VideoPlayerStore>;
 
+/**
+ * Creates a player factory for audio media.
+ *
+ * @label Audio
+ * @param config - Player configuration with features.
+ */
 export function createPlayer(config: CreatePlayerConfig<AudioFeatures>): CreatePlayerResult<AudioPlayerStore>;
 
+/**
+ * Creates a player factory with custom features.
+ *
+ * @label Generic
+ * @param config - Player configuration with features.
+ */
 export function createPlayer<const Features extends AnyPlayerFeature[]>(
   config: CreatePlayerConfig<Features>
 ): CreatePlayerResult<PlayerStore<Features>>;

packages/html/src/player/player-controller.ts

@@ -38,7 +38,18 @@ export class PlayerController<Store extends PlayerStore, Result = Store> impleme
   #consumer: ContextConsumer<PlayerContext<Store>, PlayerControllerHost>;
   #store: StoreController<Store, Result> | null = null;
 
+  /**
+   * @label Without Selector
+   * @param host - The host element that owns this controller.
+   * @param context - Player context to resolve the store from.
+   */
   constructor(host: PlayerControllerHost, context: PlayerContext<Store>);
+  /**
+   * @label With Selector
+   * @param host - The host element that owns this controller.
+   * @param context - Player context to resolve the store from.
+   * @param selector - Derives a value from the player store state.
+   */
   constructor(
     host: PlayerControllerHost,
     context: PlayerContext<Store>,

packages/html/src/player/player-mixin.ts

@@ -16,6 +16,9 @@ export type PlayerMixin<Store extends PlayerStore> = <Class extends MediaElement
  * Creates a mixin that combines provider and container functionality.
  *
  * Use for a complete player element that owns the store and attaches media.
+ *
+ * @param context - Player context for descendant consumption.
+ * @param factory - Factory function that creates a store instance.
  */
 export function createPlayerMixin<Store extends PlayerStore>(
   context: PlayerContext<Store>,

packages/html/src/store/container-mixin.ts

@@ -9,6 +9,11 @@ export type ContainerMixin<Store extends PlayerStore> = <Class extends MediaElem
   BaseClass: Class
 ) => Class & PlayerConsumerConstructor<Store>;
 
+/**
+ * Create a mixin that consumes player context and auto-attaches media elements.
+ *
+ * @param context - Player context to consume from an ancestor provider.
+ */
 export function createContainerMixin<Store extends PlayerStore>(context: PlayerContext<Store>): ContainerMixin<Store> {
   return <Class extends MediaElementConstructor>(BaseClass: Class) => {
     class PlayerContainerElement extends BaseClass implements PlayerConsumer<Store>, MediaContainer {

packages/html/src/store/provider-mixin.ts

@@ -9,6 +9,12 @@ export type ProviderMixin<Store extends PlayerStore> = <Class extends MediaEleme
   BaseClass: Class
 ) => Class & PlayerProviderConstructor<Store>;
 
+/**
+ * Create a mixin that provides player context to descendant elements.
+ *
+ * @param context - Player context to provide to descendants.
+ * @param factory - Factory function that creates a store instance.
+ */
 export function createProviderMixin<Store extends PlayerStore>(
   context: PlayerContext<Store>,
   factory: () => Store