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

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

packages/store/src/core/selector.ts

@@ -19,6 +19,8 @@ const stateContext: StateContext<unknown> = {
  * const selectPlayback = createSelector(playbackSlice);
  * selectPlayback(store.state); // { paused, play, pause, ... } | undefined
  * ```
+ *
+ * @param slice - The feature slice to create a selector for.
  */
 export function createSelector<S extends AnySlice>(slice: S): (state: object) => InferSliceState<S> | undefined {
   const initialState = slice.state(stateContext);

packages/store/src/html/controllers/snapshot-controller.ts

@@ -25,7 +25,18 @@ export class SnapshotController<T extends object, R = T> implements ReactiveCont
   #cached: R | undefined;
   #unsubscribe = noop;
 
+  /**
+   * @label Without Selector
+   * @param host - The host element that owns this controller.
+   * @param state - The State container to subscribe to.
+   */
   constructor(host: ReactiveControllerHost, state: State<T>);
+  /**
+   * @label With Selector
+   * @param host - The host element that owns this controller.
+   * @param state - The State container to subscribe to.
+   * @param selector - Derives a value from the state.
+   */
   constructor(host: ReactiveControllerHost, state: State<T>, selector: Selector<T, R>);
   constructor(host: ReactiveControllerHost, state: State<T>, selector?: Selector<T, R>) {
     this.#host = host;

packages/store/src/html/controllers/store-controller.ts

@@ -45,7 +45,18 @@ export class StoreController<Store extends AnyStore, Result = Store> implements
 
   #snapshot: SnapshotController<object, Result> | null = null;
 
+  /**
+   * @label Without Selector
+   * @param host - The host element that owns this controller.
+   * @param source - Store instance or context to resolve the store from.
+   */
   constructor(host: StoreControllerHost, source: StoreSource<Store>);
+  /**
+   * @label With Selector
+   * @param host - The host element that owns this controller.
+   * @param source - Store instance or context to resolve the store from.
+   * @param selector - Derives a value from the store state.
+   */
   constructor(
     host: StoreControllerHost,
     source: StoreSource<Store>,

packages/store/src/html/controllers/subscription-controller.ts

@@ -42,6 +42,11 @@ export class SubscriptionController<Store extends AnyStore, Value> implements Re
 
   #unsubscribe = noop;
 
+  /**
+   * @param host - The host element that owns this controller.
+   * @param source - Store instance or context to resolve the store from.
+   * @param config - Subscription and value extraction configuration.
+   */
   constructor(
     host: SubscriptionControllerHost,
     source: StoreSource<Store>,

packages/store/src/react/hooks/use-selector.ts

@@ -3,7 +3,16 @@ import { type Comparator, type Selector, shallowEqual } from '../../core/shallow
 
 export type { Comparator, Selector };
 
-/** Subscribe to derived state with customizable equality check. */
+/**
+ * Subscribe to derived state with customizable equality check.
+ *
+ * Low-level hook used internally by `useStore` and `useSnapshot`.
+ *
+ * @param subscribe - Subscribe function that returns an unsubscribe callback.
+ * @param getSnapshot - Returns the current snapshot value.
+ * @param selector - Derives a value from the snapshot.
+ * @param isEqual - Custom equality function. Defaults to `shallowEqual`.
+ */
 export function useSelector<S, R>(
   subscribe: (cb: () => void) => () => void,
   getSnapshot: () => S,

packages/store/src/react/hooks/use-snapshot.ts

@@ -2,9 +2,23 @@ import { identity } from '@videojs/utils/function';
 import type { State } from '../../core/state';
 import { type Comparator, type Selector, useSelector } from './use-selector';
 
-/** Subscribe to a State container's current value. */
+/**
+ * Subscribe to a State container's current value.
+ *
+ * @param state - The State container to subscribe to.
+ * @param selector - Derives a value from state.
+ * @param isEqual - Custom equality function. Defaults to `shallowEqual`.
+ */
+/** @label Without Selector */
 export function useSnapshot<T extends object>(state: State<T>): T;
 
+/**
+ * Select a value from state. Re-renders when the selected value changes.
+ *
+ * @label With Selector
+ * @param selector - Derives a value from state.
+ * @param isEqual - Custom equality function. Defaults to `shallowEqual`.
+ */
 export function useSnapshot<T extends object, R>(state: State<T>, selector: Selector<T, R>, isEqual?: Comparator<R>): R;
 
 export function useSnapshot(state: State<object>, selector?: Selector<any, any>, isEqual?: Comparator<any>) {

packages/store/src/react/hooks/use-store.ts

@@ -24,8 +24,16 @@ const noopSubscribe = () => noop;
  * }
  * ```
  */
+/** @label Without Selector */
 export function useStore<S extends AnyStore>(store: S): S;
 
+/**
+ * Select a value from the store. Re-renders when the selected value changes (shallowEqual).
+ *
+ * @label With Selector
+ * @param selector - Derives a value from the store state.
+ * @param isEqual - Custom equality function. Defaults to `shallowEqual`.
+ */
 export function useStore<S extends AnyStore, R>(
   store: S,
   selector: Selector<InferStoreState<S>, R>,