feat(site): add util reference pipeline for hooks, controllers, mixins, selectors, and utilities

Introduces a convention-based auto-discovery system that generates API reference
documentation for non-component exports: React hooks, HTML controllers/mixins,
factory functions, selectors, contexts, and utilities.

The builder scans package entry points, classifies exports by naming convention
(`use*`, `*Controller`, `create*`, `select*`) or `@public` JSDoc tag, extracts
type information via typescript-api-extractor and raw TS AST, and outputs JSON
consumed by new Astro components (`UtilReference`, `UtilParamsTable`,
`UtilReturnTable`).

Key design decisions:
- Framework-agnostic entries (selectors, createSelector) omit the `frameworks`
  JSON field, meaning they apply to all frameworks
- Framework-specific entries (hooks → react, controllers → html) get
  `frameworks: ['react']` or `frameworks: ['html']`
- Slug collisions use the actual framework prefix (not hardcoded `html-`)
- Discovery casts a wide net; only exports with both generated JSON AND a
  manually-created MDX page appear in the docs
- Controller extraction handles both overload declarations and single
  constructors with a body

Also renames ApiReference → ComponentReference to disambiguate from the new
UtilReference, adds interactive demos for key utils, and updates the sidebar
with Selectors, Hooks & Utilities, and Controllers & Mixins sections.

Closes #466

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: decepulis

.claude/skills/api-reference/SKILL.md

@@ -1,24 +1,25 @@
 ---
 name: api-reference
 description: >-
-  Scaffold API reference documentation for Video.js 10 components. Validates
-  the api-docs-builder output, checks design docs and linked PRs for context,
-  creates the MDX reference page with anatomy, prose sections, demos, and the
-  ApiReference component. Triggers: "api reference", "reference page",
-  "scaffold api docs", "add api docs", "component reference".
+  Scaffold API reference documentation for Video.js 10 components and utility
+  APIs. Validates the api-docs-builder output, checks design docs and linked
+  PRs for context, creates the MDX reference page with anatomy, prose sections,
+  demos, and the ComponentReference/UtilReference component. Triggers: "api
+  reference", "reference page", "scaffold api docs", "add api docs",
+  "component reference", "util reference", "hook reference".
 ---
 
 # API Reference
 
-Scaffold a complete API reference page for a Video.js 10 component.
+Scaffold a complete API reference page for a Video.js 10 component or utility API.
 
 ## Usage
 
 ```
-/api-reference [component-name]
+/api-reference [name]
 ```
 
-- `component-name` (optional): kebab-case component name (e.g., `play-button`). If omitted, will prompt.
+- `name` (optional): kebab-case component name (e.g., `play-button`) or util name (e.g., `use-player`). If omitted, will prompt.
 
 ## Arguments
 
@@ -31,14 +32,15 @@ Load these files based on task:
 | Need | Load |
 |------|------|
 | Builder naming conventions | `references/builder-conventions.md` |
+| Util conventions | `references/util-conventions.md` |
 | MDX page structure | `references/mdx-structure.md` |
 | Demo file patterns | `references/demo-patterns.md` |
 | Component libraries reference | `docs` skill → `references/component-libraries.md` |
 | Component patterns | `component` skill |
 | Accessibility | `aria` skill |
 | Design docs | `internal/design/` |
 
-## Your Tasks
+## Component Reference Workflow
 
 ### Step 1: Gather context
 
@@ -54,7 +56,7 @@ Accept component name as argument (kebab-case).
 ### Step 2: Validate api-docs-builder compatibility
 
 1. Run `pnpm -F site api-docs` and check for errors
-2. Read the generated JSON at `site/src/content/generated-api-reference/{name}.json`
+2. Read the generated JSON at `site/src/content/generated-component-reference/{name}.json`
 3. Verify the JSON has expected sections (props, state, dataAttributes, platforms.html.tagName)
 4. For multi-part: verify each part appears in `parts` with correct names
 
@@ -88,9 +90,36 @@ Load `references/mdx-structure.md` for the full structure template.
 
 1. Create `site/src/content/docs/reference/{name}.mdx`
 2. Add to sidebar in `site/src/docs.config.ts` (alphabetically within Components section)
-3. Structure: frontmatter → imports → Anatomy → prose sections → Examples → `<ApiReference />`
+3. Structure: frontmatter → imports → Anatomy → prose sections → Examples → `<ComponentReference />`
 4. Run `pnpm dev` from root and verify the page renders in both HTML and React framework modes
 
+## Util Reference Workflow
+
+For hooks, controllers, mixins, factories, and utilities. Load `references/util-conventions.md` for full details.
+
+### Step 1: Ensure auto-discovery can find the util
+
+1. The util must be exported from one of the scanned package index files (`packages/react/src/index.ts`, `packages/html/src/index.ts`, or the store subpath indexes)
+2. Add JSDoc with a description to the source export
+3. If the export doesn't match a naming convention (`use*`, `*Controller`, `create*`), add `@public` to its JSDoc
+
+Load `references/util-conventions.md` for the full inclusion and classification rules.
+
+### Step 2: Generate and validate JSON
+
+1. Run `pnpm -F site api-docs` and check for errors
+2. Read the generated JSON at `site/src/content/generated-util-reference/{slug}.json`
+3. Verify it has the expected overloads, parameters, and return value
+
+### Step 3: Create MDX page
+
+1. Create `site/src/content/docs/reference/{slug}.mdx`
+2. Structure: frontmatter → `import UtilReference` → `## Import` → `## Usage` → `<UtilReference util="..." />`
+3. Add to sidebar in `site/src/docs.config.ts`:
+   - React utils → "Hooks & Utilities" section (`frameworks: ['react']`)
+   - HTML utils → "Controllers & Mixins" section (`frameworks: ['html']`)
+4. Run `pnpm dev` and verify the page renders correctly
+
 ## Related Skills
 
 | Need | Use |

.claude/skills/api-reference/references/builder-conventions.md

@@ -76,10 +76,13 @@ The builder fails silently for many issues — data just won't appear in the JSO
 # Generate JSON
 pnpm -F site api-docs
 
-# Check output
-cat site/src/content/generated-api-reference/{name}.json
+# Check component output
+cat site/src/content/generated-component-reference/{name}.json
+
+# Check util output
+cat site/src/content/generated-util-reference/{slug}.json
 
 # Verify schema
-# The builder validates against ComponentApiReferenceSchema before writing.
+# The builder validates against ComponentReferenceSchema / UtilReferenceSchema before writing.
 # Schema errors are logged as errors and cause exit code 1.
 ```

.claude/skills/api-reference/references/mdx-structure.md

@@ -2,7 +2,9 @@
 
 Structure and conventions for API reference MDX pages at `site/src/content/docs/reference/`.
 
-## Frontmatter
+## Component Pages
+
+### Frontmatter
 
 ```yaml
 ---
@@ -17,7 +19,7 @@ description: A button component for muting and unmuting audio playback
 - `frameworkTitle.html`: The `static tagName` from the HTML element file
 - `description`: One-line description of the component
 
-## Page Structure
+### Page Structure
 
 ```
 frontmatter
@@ -29,7 +31,7 @@ imports (React demos, HTML demos)
 ## Examples
 ### BasicUsage
 ### [Additional demos]
-<ApiReference component="{PascalCase}" />
+<ComponentReference component="{PascalCase}" />
 ```
 
 ## Imports Section
@@ -185,19 +187,115 @@ Key details:
 - React source tabs: `App.tsx`, `App.css`
 - HTML source tabs: `index.html`, `index.css`, `index.ts`
 
-## ApiReference Component
+### ComponentReference Component
 
 Always the last element in the file:
 
 ```mdx
-<ApiReference component="MuteButton" />
+<ComponentReference component="MuteButton" />
 ```
 
 The component auto-renders Props, State, Data Attributes for single-part and all Parts for multi-part.
 
+### Required Astro Component Imports
+
+Every component reference MDX needs these at the top of the imports:
+
+```mdx
+import ComponentReference from "@/components/docs/api-reference/ComponentReference.astro";
+import FrameworkCase from "@/components/docs/FrameworkCase.astro";
+import StyleCase from "@/components/docs/StyleCase.astro";
+import Demo from "@/components/docs/demos/Demo.astro";
+```
+
+---
+
+## Util Pages
+
+Util pages document React hooks/utilities and HTML controllers/mixins. They are simpler than component pages — no demos, no anatomy.
+
+### Frontmatter
+
+```yaml
+---
+title: usePlayer
+description: Hook to access the player store from within a Player Provider
+---
+```
+
+- `title`: The exported function/class name (e.g., `usePlayer`, `PlayerController`)
+- No `frameworkTitle` — util pages are framework-specific
+- `description`: One-line description
+
+### Page Structure
+
+```
+frontmatter
+import UtilReference
+## Import
+## Usage
+<UtilReference util="{Name}" />
+```
+
+### Import Section
+
+Show the import statement for the util:
+
+```mdx
+## Import
+
+\`\`\`tsx
+import { usePlayer } from '@videojs/react';
+\`\`\`
+```
+
+### Usage Section
+
+Explain usage patterns with code examples. For multi-overload utils, document each overload:
+
+```mdx
+## Usage
+
+`usePlayer` has two overloads:
+
+**Store access (no subscription)** -- returns the store instance.
+
+\`\`\`tsx
+const store = usePlayer();
+\`\`\`
+
+**Selector-based subscription** -- returns selected state.
+
+\`\`\`tsx
+const paused = usePlayer((s) => s.paused);
+\`\`\`
+```
+
+### UtilReference Component
+
+Always the last element in the file:
+
+```mdx
+<UtilReference util="usePlayer" />
+```
+
+The component auto-renders Parameters and Return Value tables. For multi-overload utils, it renders each overload with its own sections.
+
+### Required Import
+
+```mdx
+import UtilReference from "@/components/docs/api-reference/UtilReference.astro";
+```
+
+---
+
 ## Sidebar Entry
 
-Add to `site/src/docs.config.ts` in the Components section, alphabetically:
+Add to `site/src/docs.config.ts` in the appropriate section, alphabetically:
+
+- **Components** — UI component reference pages
+- **Hooks & Utilities** (`frameworks: ['react']`) — React hooks and utilities
+- **Controllers & Mixins** (`frameworks: ['html']`) — HTML controllers and mixins
 
 ```ts
 {
@@ -212,14 +310,3 @@ Add to `site/src/docs.config.ts` in the Components section, alphabetically:
   ],
 },
 ```
-
-## Required Astro Component Imports
-
-Every reference MDX needs these at the top of the imports:
-
-```mdx
-import ApiReference from "@/components/docs/api-reference/ApiReference.astro";
-import FrameworkCase from "@/components/docs/FrameworkCase.astro";
-import StyleCase from "@/components/docs/StyleCase.astro";
-import Demo from "@/components/docs/demos/Demo.astro";
-```