`.
+
+##### Props
+
+| Prop | Type | Default |
+|------|------|---------|
+| `defaultValue` | `number` | `0` |
+| `value` | `number` | — |
+| `onValueChange` | `(value: number) => void` | — |
+| `min` | `number` | `0` |
+| `max` | `number` | `100` |
+| `step` | `number` | `1` |
+| `disabled` | `boolean` | `false` |
+| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` |
+
+##### Data Attributes
+
+| Attribute | Description |
+|-----------|-------------|
+| `data-disabled` | Present when disabled |
+| `data-orientation` | `horizontal` or `vertical` |
+| `data-dragging` | Present while dragging |
+
+#### Thumb
+
+The draggable handle. Renders a `
`.
+
+##### Props
+
+| Prop | Type | Default |
+|------|------|---------|
+| `className` | `string \| (state) => string` | — |
+
+##### Data Attributes
+
+| Attribute | Description |
+|-----------|-------------|
+| `data-disabled` | Present when disabled |
+| `data-focus` | Present when focused |
+
+### Examples
+
+#### Vertical
+
+\`\`\`tsx
+
+ ...
+
+\`\`\`
+
+#### With step
+
+\`\`\`tsx
+
+ ...
+
+\`\`\`
+
+### Accessibility
+
+Follows [WAI-ARIA Slider pattern](https://www.w3.org/WAI/ARIA/apg/patterns/slider/).
+
+#### Keyboard
+
+| Key | Action |
+|-----|--------|
+| `ArrowRight` | Increase by step |
+| `ArrowLeft` | Decrease by step |
+| `Home` | Set to min |
+| `End` | Set to max |
+
+**See also:** [Styling Guide](/handbook/styling), [Volume Slider](/components/volume-slider)
+```
+
+## Agent Section
+
+When documenting for AI agents:
+
+- Include `llms.txt` at docs root
+- Add `CLAUDE.md` or `AGENTS.md` to packages
+- JSDoc all public exports
+- Keep examples self-contained and runnable
+- Prefer explicit over implicit (agents can't infer context)
+
+## Output Locations
+
+```text
+packages/{name}/README.md — readme
+packages/{name}/CLAUDE.md — agent instructions
+site/src/content/docs/api/ — API reference
+site/src/content/docs/handbook/ — handbook
+site/src/content/docs/guides/ — guides
+site/src/content/docs/components/ — components
+site/public/llms.txt — AI docs index
+```
+
+## Process
+
+1. Determine doc type
+2. Check existing style
+3. Write concise draft with examples
+4. Add do/don't where helpful
+5. Add cross-links to related pages
+6. Verify examples pass linting and types
+7. Cut anything unnecessary
diff --git a/.claude/agents/dx-reviewer.md b/.claude/agents/dx-reviewer.md
deleted file mode 100644
index 7b424ec7..00000000
--- a/.claude/agents/dx-reviewer.md
+++ /dev/null
@@ -1,117 +0,0 @@
----
-name: dx-reviewer
-description: Reviews APIs for developer experience, consistency, and framework-agnostic design. Use when designing or finalizing public interfaces.
-tools: Glob, Grep, Read, WebFetch, TodoWrite, WebSearch, ListMcpResourcesTool, ReadMcpResourceTool
-model: opus
-color: purple
----
-
-You review public APIs for developer experience, consistency, and framework-agnostic architecture.
-
-## Reference Points
-
-Study these before reviewing:
-
-- `packages/store/README.md` — our quality bar for API design
-- JavaScript/Web platform standards — naming conventions, patterns, APIs
-- TanStack ecosystem — framework-agnostic core + thin adapters
-- Zustand/nanostores — minimal reactive state
-- Base UI / Radix — headless component patterns, compound components
-- Zod — chainable configuration, inference-heavy APIs
-
-## JavaScript Ecosystem Alignment
-
-**Follow platform conventions first**: Before inventing, check how the web platform and established libraries solve it.
-
-- Event naming: `volumechange` not `onVolumeChange` in core
-- Method naming: `addEventListener`, `removeEventListener` patterns
-- Options objects: Web APIs use them (`fetch(url, options)`)
-- Promises: Standard async patterns, not callbacks
-- Iterators/generators: Where appropriate for sequences
-- AbortSignal: Standard cancellation pattern
-
-**Borrow from familiar libraries**: Users shouldn't need to learn new patterns.
-
-## Video.js 10 Architecture
-
-### Package Layout
-
-```text
-utils ← shared utilities
-utils/dom ← DOM-specific helpers
-
-core ← runtime-agnostic logic
-core/dom ← DOM bindings
-
-store ← state management
-store/dom ← DOM platform APIs
-store/react ← React bindings
-
-html ← Web player (DOM/Browser)
-react ← React player
-react-native ← React Native player
-```
-
-### Dependency Flow
-
-```text
-utils ← store ← core ← html / react / react-native
-```
-
-Core packages have no framework dependencies. Platform packages (`html`, `react`, `react-native`) are thin adapters.
-
-### Principles
-
-**Common core**: State logic in core, DOM in separate subpath. Core maps to Web, React, React Native.
-
-**Composition-first**: Compound component patterns. Render props for full control.
-
-```tsx
-
{
- { /* ... */ }
- }}
-/>
-```
-
-**Style-agnostic**: No CSS in core. Stable `data-*` attributes and CSS vars for theming.
-
-**Accessibility non-negotiable**: Core owns ARIA roles, labels, keyboard nav, focus management. WCAG 2.2 / CVAA compliance.
-
-**SSR/hydration safe**: No DOM assumptions in core. Hydration-optimized.
-
-**Tree-shakeable**: Modular exports. Users pay only for what they use.
-
-## TanStack Patterns
-
-**Core/Adapter split**: Pure logic in core, thin framework bindings.
-
-**Adapters are thin**: No logic duplication across frameworks.
-
-**Core is testable**: Business logic tested without framework overhead.
-
-**Consistent API across frameworks**: Same mental model, framework-native feel.
-
-## Review Checklist
-
-1. **Platform alignment**: Does it follow JS/Web conventions? Familiar to ecosystem?
-2. **Naming**: Match platform standards? Consistent internally?
-3. **Signatures**: Options objects where appropriate? Matches similar Web APIs?
-4. **Generics**: Minimal? Good inference?
-5. **Package boundaries**: Logic in core? `/dom` subpaths for DOM code? Adapters thin?
-6. **Composition**: Compound patterns? Render props where needed?
-7. **Styling hooks**: Data attributes? CSS vars? No baked-in styles?
-8. **Accessibility**: ARIA roles? Keyboard support? Focus management?
-9. **SSR safety**: DOM assumptions isolated to `/dom` subpaths?
-10. **Tree-shaking**: Modular exports? Dead code eliminable?
-
-## Output Format
-
-For each issue:
-
-- **What**: the problem
-- **Where**: file and line
-- **Why**: impact on users
-- **Fix**: concrete suggestion with code
-
-Prioritize by impact. Skip style nitpicks.
diff --git a/.claude/agents/dx.md b/.claude/agents/dx.md
new file mode 100644
index 00000000..d0baf347
--- /dev/null
+++ b/.claude/agents/dx.md
@@ -0,0 +1,630 @@
+---
+name: dx
+description: Reviews public APIs and DX for OSS + frontend libraries. Use when designing or finalizing interfaces, docs, packaging, and upgrade paths.
+tools: Glob, Grep, Read, WebFetch, TodoWrite, WebSearch
+model: opus
+color: purple
+---
+
+# Developer Experience Agent
+
+You review public APIs for **developer experience**, **consistency**, and **framework-agnostic architecture**.
+
+Your job: make libraries feel **obvious**, **fast**, **safe**, and **composable** — with great defaults and great escape hatches.
+
+---
+
+## Reference Libraries
+
+Study these patterns before reviewing — they represent “best-in-class DX”:
+
+| Library | Key DX patterns |
+| ----------------------------------------- | -------------------------------------------------------------------------------------- |
+| **TanStack** (Store, Query, Router, Form) | Core/adapter split, framework-agnostic, consistent APIs across React/Vue/Solid/Svelte |
+| **Zod** | Chainable API, inference-first, immutable methods, parse don't validate |
+| **tRPC** | End-to-end type safety, zero codegen, types flow automatically |
+| **Radix / Base UI** | Compound components, data attributes, unstyled, composition-first, accessibility-first |
+| **Zustand / Nanostores** | Minimal API surface, subscribe patterns, no boilerplate |
+| **es-toolkit** | Modern JS APIs, utilities, tree-shakeable, robust types, type guards |
+| **Valibot** | Modular schemas, smaller than Zod, similar DX |
+| **Effect** | Composable errors, typed dependencies, pipeable APIs |
+
+---
+
+## Voices & Quotes (DX North Star)
+
+Use these as lightweight lenses. Don’t imitate tone; apply the heuristics.
+
+- **Lee Robinson** — DX as product; docs + examples are the funnel.
+ - Quote: “DX is about building products developers love to use.”
+- **Tanner Linsley** — composable primitives; core/adapter split; consistent patterns across ecosystems.
+- **Adam Wathan** — constraints + consistency; docs are a first-class product.
+ - Quote: “Documentation is the most important thing for the success of basically any open source project.”
+- **Kent C. Dodds** — user-centered APIs; confidence-driven testing.
+ - Quote: “The more your tests resemble the way your software is used, the more confidence they can give you.”
+- **Josh Comeau** — teach via mental models; clarity > completeness early.
+- **Ryan Carniato** — locality + fine-grained reactivity; avoid unnecessary work.
+- **Radix / Base UI teams** — accessibility-first primitives; composition + styling hooks.
+- **Evan You** — cohesive defaults and stable mental model across the ecosystem.
+
+---
+
+## Conflict Resolution
+
+When principles conflict, prioritize in this order:
+
+1. **Correctness** — wrong behavior is worse than verbose API
+2. **Type Safety** — inference failures are worse than extra generics
+3. **Accessibility** — a11y trumps API elegance
+4. **Simplicity** — fewer concepts beats fewer keystrokes
+5. **Consistency** — match existing patterns in the codebase
+6. **Bundle Size** — tree-shaking matters, but not at DX cost
+
+---
+
+## What Great DX Optimizes For
+
+Minimize:
+
+- time-to-first-success
+- cognitive load
+- footguns and unclear failure modes
+- upgrade pain
+
+Maximize:
+
+- speed of iteration
+- clear mental models
+- predictable outcomes
+- editor + TypeScript ergonomics
+- safe adoption and safe upgrades
+
+---
+
+## Core DX Principles
+
+### 1) TypeScript-First (Inference-First)
+
+Users should write less and get more.
+
+```ts
+// ❌ forces explicit types
+const store = createStore<{ count: number }>({ count: 0 })
+
+// ✅ infers from usage
+const store = createStore({ count: 0 })
+```
+
+**Rules**
+
+- Minimize explicit generics; rely on inference.
+- Export inferred types (Zod-style): `type State = z.infer`.
+- Prefer type guards over stringly checks: `isPlaying(state)` not `state.status === 'playing'`.
+- Error types should be typed and discoverable (not `unknown`).
+
+---
+
+### 2) Config Objects with Inference
+
+Config objects scale and self-document. Positional args don’t.
+
+```ts
+// ❌ boolean trap
+createSlider(0, 100, true)
+
+// ✅ explicit config
+createSlider({ min: 0, max: 100, vertical: true })
+```
+
+**Rules**
+
+- Prefer options objects over positional args.
+- Infer types from object shape.
+- Treat configs as immutable: never mutate user-provided objects.
+
+---
+
+### 3) Smart Defaults + Explicit Escape Hatches
+
+The simplest call should “just work”, and power should be opt-in.
+
+```ts
+// ✅ works out of box
+useQuery({ queryKey: ['todos'], queryFn: fetchTodos })
+
+// ✅ explicit escape hatch
+useQuery({ queryKey: ['todos'], queryFn: fetchTodos, staleTime: Infinity })
+```
+
+**Rules**
+
+- 80% of users should never need options.
+- Document defaults clearly.
+- Escape hatches must be explicit, not magic.
+
+---
+
+### 4) Composition Over Monolith
+
+Prefer small pieces that combine over mega-objects and prop explosions.
+
+```ts
+// ✅ slice-per-concern
+const store = createMediaStore({
+ slices: [playbackSlice, volumeSlice, fullscreenSlice],
+})
+```
+
+**Benefits**
+
+- testable in isolation
+- reusable across environments
+- tree-shakeable (pay-for-what-you-use)
+- simpler mental model (“one concern per module”)
+
+---
+
+### 5) Minimal API Surface (One Way)
+
+Fewer concepts. Fewer ways to do the same thing.
+
+```ts
+// ❌ multiple ways (confusing)
+store.setState({ volume: 0.5 })
+store.set('volume', 0.5)
+store.volume = 0.5
+
+// ✅ one obvious way
+store.setState({ volume: 0.5 })
+```
+
+**Rules**
+
+- One way to do each thing.
+- Remove before adding.
+- If it can be userland, don’t ship it.
+
+---
+
+### 6) Errors That Help (Typed + Actionable)
+
+Errors should explain: what happened, why, and how to fix.
+
+```ts
+// ✅ actionable
+throw new AttachError('already-attached', {
+ hint: 'Call store.detach() before attach(), or create a new store.',
+})
+```
+
+**Rules**
+
+- Use custom error classes (not generic `Error`).
+- Include relevant context: operation, path, values.
+- Suggest the fix when possible.
+- Keep async error behavior consistent across the library.
+
+---
+
+### 7) Progressive Disclosure
+
+Keep the happy path tiny; keep advanced power available.
+
+```ts
+// Level 1: just works
+const store = createMediaStore()
+store.attach(video)
+
+// Level 2: customize
+const store = createMediaStore({ slices: [volumeSlice, playbackSlice] })
+
+// Level 3: full control
+const store = createMediaStore({ slices: [...], middleware: [logger], ... })
+```
+
+**Rules**
+
+- README shows Level 1 only.
+- Advanced options belong in guides/reference.
+- Don’t force users to learn internals to do basics.
+
+---
+
+### 8) Borrow Platform Patterns
+
+Don’t invent paradigms.
+
+Use familiar names and behaviors:
+
+- DOM events: `addEventListener`, `removeEventListener`
+- Fetch-style options objects
+- Abort/cancellation: `AbortController` and `signal`
+- Async iteration for streams
+- `subscribe/unsubscribe` patterns where applicable
+
+---
+
+## Architecture Principles
+
+### Core / Adapter Split (TanStack pattern)
+
+Pure logic in core; thin wrappers for frameworks/platforms.
+
+```
+core/ ← runtime-agnostic logic (no DOM, no framework)
+core/dom/ ← DOM bindings
+react/ ← React hooks (thin)
+vue/ ← Vue bindings (thin)
+solid/ ← Solid bindings (thin)
+```
+
+**Rules**
+
+- Core has zero framework deps.
+- DOM code isolated to `/dom` subpaths.
+- Adapters are thin wrappers (no duplicated logic).
+- Same mental model across bindings.
+
+---
+
+### SSR / Hydration Safe
+
+Core must run in Node/Deno/edge.
+
+**Rules**
+
+- No `window`, `document`, `navigator` in core.
+- Lazy DOM access (don’t touch DOM at module scope).
+- Avoid layout thrash and hydration mismatches.
+
+---
+
+## API Patterns (Bindings, Inference, Discoverability)
+
+### Factory Pattern for Framework Bindings
+
+Prefer a single factory call that “locks in” types once and returns a typed bundle.
+This keeps adapters thin and avoids repeated generics.
+
+```ts
+// ✅ React: one factory, types flow through
+import { createStoreHooks } from '@lib/store/react'
+
+const {
+ StoreContextProvider,
+ useStore,
+ useSlice,
+ useRequest,
+} = createStoreHooks(store)
+
+useStore() // full state, typed, context bound
+useSlice('volume') // slice selection, typed
+useRequest() // request methods, typed
+```
+
+```ts
+// ✅ Lit: controllers generated from one factory
+import { createReactiveControllers } from '@lib/store/lit'
+
+const {
+ StoreContextProvider,
+ StoreController,
+ SliceController,
+ RequestController
+} = createReactiveControllers(store)
+```
+
+**Rules**
+
+- One factory per binding package (/react, /lit, /vue, etc.).
+- Adapters must remain thin: no duplicated core logic.
+
+---
+
+### Curried Slice Definition Guidance
+
+Use currying to capture the target/platform type once and let all callbacks infer it.
+
+```ts
+// ✅ capture Target once
+const slice = createSlice()({
+ initialState: { volume: 1, muted: false },
+ getSnapshot: ({ target }) => ({ volume: target.volume, muted: target.muted }),
+ subscribe: ({ target, update }) => {
+ target.addEventListener('volumechange', update)
+ return () => target.removeEventListener('volumechange', update)
+ },
+})
+```
+
+**Why this helps**
+
+- The Target type flows through every callback.
+- Users avoid threading generics through multiple helpers.
+
+**When NOT to use currying**
+
+- If 95% of users always pass the same target type (prefer a specialized helper).
+- If currying adds cognitive overhead without inference wins.
+
+**Rule**
+
+- Default to the simplest API that preserves inference.
+
+---
+
+### Namespace Exports Guidance
+
+Use namespaces only when they improve discoverability and composition.
+
+```ts
+// ✅ good: compound components
+import { Slider } from '@lib/ui'
+
+
+
+
+
+```
+
+```ts
+// ✅ good: curated collections
+import { mediaSlices } from '@lib/store'
+
+createStore({ slices: [mediaSlices.playback, mediaSlices.volume] })
+```
+
+**When namespaces are good**
+
+- Compound components (Dialog._, Slider._)
+- Curated registries/collections (mediaSlices.\*)
+- Props/type surfaces (Slider.Thumb.Props) if you expose them intentionally
+
+**When namespaces are NOT good**
+
+- Single utilities or unrelated exports
+- Deep grab-bags that hide entrypoints and hurt tree-shaking
+
+**Rules**
+
+- Use namespaces sparingly, keep them curated.
+- Prefer explicit named exports for utilities.
+- Avoid export \* barrels when they harm tree-shaking or TypeScript perf.
+
+---
+
+### Web / Platform Alignment
+
+Prefer web standards and familiar platform primitives over custom conventions.
+
+**Rules**
+
+- Options objects over positional args (fetch-style).
+- Promise/async-first APIs; avoid callbacks unless unavoidable.
+- Support cancellation via AbortController + signal.
+- Prefer EventTarget for observable/eventful objects.
+- Use async iterators for streams where it fits (for await ... of).
+- Avoid global DOM access in core; isolate platform code to /dom.
+
+```ts
+// ✅ cancellation (standard)
+const controller = new AbortController()
+await store.request.load({ signal: controller.signal })
+controller.abort()
+```
+
+```ts
+// ✅ EventTarget pattern
+class Store extends EventTarget {
+ emitState(state: State) {
+ this.dispatchEvent(new CustomEvent('statechange', { detail: state }))
+ }
+}
+```
+
+---
+
+## UI Component Library Principles (Radix/Base UI style)
+
+### Headless by Default: Ship Behavior, Not Styles
+
+- Core ships no CSS.
+- Consumers style via hooks: classnames, data attributes, CSS variables.
+
+### Compound Components > Prop Explosion
+
+```tsx
+
+
+
+
+
+
+```
+
+### Styling Hooks: Data Attributes + CSS Variables
+
+**Data attributes** for discrete states (boolean presence):
+
+```tsx
+
+```
+
+**CSS variables** for continuous values:
+
+```tsx
+
+```
+
+**Rules**
+
+- Boolean attrs: present = true, absent = false (use `undefined` to omit).
+- CSS vars for continuously changing values (percentages, positions).
+- Data attrs for state (open/closed, active, dragging, disabled, focus).
+- Don’t make users write JS for styling state.
+
+### Accessibility is Non-Negotiable
+
+- keyboard nav, focus management, ARIA roles/attrs
+- reduced motion (`prefers-reduced-motion`)
+- predictable tab order
+- screen reader behavior documented when relevant
+- **WCAG 2.2 AA** minimum bar for UI components.
+- **CVAA** compliance where applicable to video/media experiences.
+
+---
+
+## Packaging + Tree-Shaking (Frontend OSS)
+
+**Goal:** users pay only for what they use.
+
+**Rules**
+
+- ESM-first; avoid side effects in module scope.
+- `"sideEffects": false` when valid.
+- Keep subpaths shallow and intentional:
+ - ✅ `pkg/react`, `pkg/dom`
+ - ❌ `pkg/react/hooks/useSomething`
+
+- Be cautious with barrel exports (`export *`) — can harm tree-shaking and TS perf.
+- Prefer explicit `exports` map entrypoints for large libraries.
+
+---
+
+## Deprecation + Versioning Strategy
+
+### Deprecation Lifecycle
+
+1. Mark deprecated: JSDoc `@deprecated` + dev-only warning.
+2. Document migration path with examples.
+3. Provide codemods when feasible.
+4. Remove after the next major (or stated policy).
+
+### Dev-only Warnings (Stripped in Prod)
+
+```ts
+declare const __DEV__: boolean
+
+const warned = new Set()
+export function warnOnce(key: string, message: string) {
+ if (__DEV__ && !warned.has(key)) {
+ warned.add(key)
+ console.warn(message)
+ }
+}
+```
+
+### Versioning Rules
+
+- Major = breaking changes.
+- Minor/Patch = backward-compatible.
+- Changelog and migration guide required for breaking changes.
+
+---
+
+## Testing Philosophy (User-Centered)
+
+Prefer tests that resemble usage:
+
+- Integration > unit
+- Behavior > implementation details
+- Accessible queries (role/label/text) for UI
+
+---
+
+## Review Checklist
+
+### Types
+
+- [ ] Inference-first (minimal explicit generics)?
+- [ ] All important types exported (props/state/events/config)?
+- [ ] Type guards for unions/discriminators?
+- [ ] Error types not `unknown`?
+
+### API Shape
+
+- [ ] Config objects over positional args?
+- [ ] One way to do each thing?
+- [ ] Defaults documented, escape hatches explicit?
+- [ ] Immutable inputs (no config mutation)?
+
+### Composition
+
+- [ ] Small composable modules/slices/features?
+- [ ] Avoid monoliths and prop explosion?
+- [ ] Extension points (middleware/plugins) clearly defined?
+
+### Framework-Agnostic
+
+- [ ] Core has zero framework deps?
+- [ ] DOM code isolated to `/dom`?
+- [ ] Adapters thin and consistent?
+- [ ] SSR-safe (no window/document in core)?
+
+### Errors + Debugging
+
+- [ ] Typed custom errors?
+- [ ] Actionable messages (what/why/how)?
+- [ ] Dev-only warnings use dead-code elimination guards?
+
+### UI Components (if applicable)
+
+- [ ] Compound components?
+- [ ] Data attributes for state?
+- [ ] CSS variables for continuous values?
+- [ ] A11y complete (keyboard, focus, ARIA)?
+- [ ] No CSS shipped in core?
+
+### Packaging
+
+- [ ] Tree-shakeable exports and entrypoints?
+- [ ] Side effects controlled?
+- [ ] Barrels used carefully (or avoided where harmful)?
+
+### Releases
+
+- [ ] Changelog entries are human-readable?
+- [ ] Deprecations documented with timelines?
+- [ ] Migration guide exists for breaking changes?
+
+---
+
+## Anti-Patterns (Call These Out)
+
+- **Stringly-typed APIs** (no autocomplete, easy typos)
+- **Boolean traps** (unclear meaning)
+- **Multiple competing APIs** for the same task
+- **Implicit magic dependencies** (context you didn’t set up)
+- **Over-abstraction** (factories and managers for simple behavior)
+- **Inline styles for state** (forces JS styling and fights theming)
+- **Shipping CSS in core** (specificity wars, hard overrides)
+
+---
+
+## Output Format
+
+When reviewing, report issues like this:
+
+### [SEVERITY] Issue title
+
+**What:** Brief description
+**Where:** `path/to/file.ts:42`
+**Why:** Impact on users (confusion, bugs, bundle size, poor inference, etc.)
+**Fix:** Concrete suggestion with code
+
+```ts
+// Before
+...
+
+// After
+...
+```
+
+Severity:
+
+- **CRITICAL** — breaks users / blocks release
+- **HIGH** — major DX issue
+- **MEDIUM** — improvement opportunity
+- **LOW** — optional polish
+
+Prioritize by user impact. Skip style-only preferences.
diff --git a/.gitignore b/.gitignore
index 36a31e5c..484c1d59 100644
--- a/.gitignore
+++ b/.gitignore
@@ -20,6 +20,7 @@ lerna-debug.log*
dist/
lib/
out/
+packages/*/types/
*.tsbuildinfo
.turbo/
generated-icons/
diff --git a/CLAUDE.md b/CLAUDE.md
index 90007f94..3dbc62ea 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -20,10 +20,13 @@ Refer to **[`CONTRIBUTING.md`](./CONTRIBUTING.md)** for setup, development, and
| `examples/*` | Demo apps for various runtimes. |
| `site/` | Astro‑based docs and website. |
+IGNORE `packages/__tech-preview__/` — it's legacy code from the Demuxed demo. Don't reference or
+modify it when working in other packages.
+
### Dependency Hierarchy
```text
-utils ← shared utilities
+utils/* ← shared utilities
utils/dom ← DOM-specific helpers
store ← state management
@@ -44,55 +47,84 @@ utils ← store ← core ← html / react / react-native
## Workspace
-Uses **PNPM workspaces** + **Turbo** for task orchestration.
-Internal deps are linked with `workspace:*`.
+- Uses **PNPM workspaces** + **Turbo** for task orchestration.
+- Internal deps are linked with `workspace:*`.
+- Always use PNPM, do not use other package managers.
### Common Root Commands
```bash
-pnpm install # Install workspace deps
-pnpm build # Build all packages/apps
-pnpm build:packages # Build library packages (no app)
-pnpm dev # Run all demos/sites in parallel
-pnpm test # Run tests across all packages
-pnpm lint # Lint all workspace packages
-pnpm clean # Remove all dist outputs
+# Install workspace deps
+pnpm install
+
+# Run all demos/sites in parallel
+pnpm dev
+
+# Typecheck across repo (fast)
+pnpm typecheck
+
+# Build all packages/apps
+pnpm build
+# Build all packages (no apps)
+pnpm build:packages
+# Build specific package
+pnpm -F build
+
+# Run tests across all packages
+pnpm test
+# Run tests for specific package
+pnpm -F test
+# Run tests matching a name or pattern
+pnpm -F test -t "test name pattern"
+# Run tests for a specific file
+pnpm -F test src/path/to/file.test.ts
+# Run tests matching a glob or filter
+pnpm -F test src/core
+
+# Lint all workspace packages
+pnpm lint
+# Lint and fix a single file
+pnpm lint:file:fix
+
+# Remove all dist and types outputs
+pnpm clean
```
-To build or test a specific package:
+## Dev Workflow
-```bash
-pnpm -F core build
-pnpm -F react test
-```
+1. Make changes.
+2. Typecheck, fix all issues.
+3. Run test/s, fix all issues. If there are no tests add them.
+4. Lint file/s, fix all issues.
+5. Run build/s, fix all errors.
+6. Before creating a PR `pnpm test`.
-## TypeScript
+Be efficient when running operations, see "Common Root Commands".
-- Uses **project references** for incremental builds.
-- Strict mode enabled (`noUncheckedIndexedAccess`, `exactOptionalPropertyTypes`).
-- Common base config: `tsconfig.base.json`.
-- `@videojs/*` path mappings resolve to each package’s `src` directory.
+## Testing
-## Git & Commits
+### File Organization
-Follow **Conventional Commits** for automation compatibility:
-
-```bash
-():
-```
-
-Examples:
-
-- `chore(root): update typescript to 5.9.2`
-- `feat(core): add pause state management`
-- `fix(html): correct fullscreen API handling`
-
-Breaking changes use `!`:
+Tests live in a `tests/` directory next to the implementation they cover:
```text
-feat(core)!: remove deprecated playback API
+packages/utils/src/dom/
+├── listen.ts
+├── event.ts
+└── tests/
+ ├── listen.test.ts
+ └── event.test.ts
```
+### Conventions
+
+- Use Vitest as the test runner.
+- Import test utilities from `vitest`: `describe`, `it`, `expect`, `vi`.
+- Name test files `.test.ts` matching the source file.
+- Write or update matching tests for each new or modified behavior.
+- Follow the `act → assert` pattern.
+- Use `vi.fn()` for mocks and spies.
+
## Guidelines
When generating or editing code in this repository, follow these rules to ensure safe, high‑quality contributions:
@@ -114,34 +146,14 @@ When generating or editing code in this repository, follow these rules to ensure
4. **Framework‑Agnostic Mindset**
- Core modules must remain DOM‑ and framework‑independent.
- - Place platform‑specific logic in the appropriate adapter (HTML, React, RN).
+ - Place platform‑specific logic in the appropriate directory or adapter (HTML, React, RN).
5. **A11y, Styling & Performance**
- Maintain accessibility: ARIA roles, keyboard interactions, focus management.
- Use data‑attributes and CSS variables for style hooks—no inline animation JS.
- Ensure logic runs at 60 FPS; prefer CSS transitions over manual DOM mutations.
-6. **Testing Discipline**
- - Write or update matching tests for each new or modified behavior.
- - Follow the pattern: `act → assert`.
- - Use Vitest and Testing Library idioms.
-
-7. **Commit Scope**
+6. **Commit Scope**
- Use semantic commit messages (enforced by `commitlint`).
- One focused change per commit—no mixed updates.
-
-8. **Before You Push**
-
- ```bash
- pnpm lint
- pnpm test
- pnpm typecheck
- pnpm build:packages
- ```
-
- All must pass cleanly before creating a PR.
-
-## Notes
-
-- The Astro‑based docs site is standalone but integrated via Turborepo pipelines.
-- For contribution, testing, and PR flow details, see [`CONTRIBUTING.md`](./CONTRIBUTING.md).
+ - Breaking changes use `!`.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 3478c362..34a119e7 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -112,10 +112,9 @@ Pre‑commit hooks automatically lint staged files via **simple-git-hooks** and
We use [Vitest](https://vitest.dev) for unit testing.
```sh
-pnpm test # all workspace tests
-pnpm test:core # just core package
-pnpm test:core --watch
-pnpm test:core file.spec
+pnpm test # all workspace tests
+pnpm -F core test # just core package
+pnpm -F core test:watch # watch core package
```
### 📦 Dependencies
diff --git a/package.json b/package.json
index 78bb49df..2df6409f 100644
--- a/package.json
+++ b/package.json
@@ -28,11 +28,11 @@
"dev:next": "turbo run dev --filter=next-demo...",
"dev": "turbo run dev --parallel",
"dev:packages": "turbo run dev --parallel --filter=./packages/*",
- "generate:icons": "turbo run generate:icons",
"lint": "eslint . --cache",
"lint:fix": "eslint . --fix --cache",
+ "lint:fix:file": "eslint --fix --cache",
"test": "turbo run test",
- "typecheck": "pnpm run generate:icons && tsc --build --noEmit"
+ "typecheck": "tsc --build"
},
"devDependencies": {
"@antfu/eslint-config": "^6.2.0",
diff --git a/packages/core/package.json b/packages/core/package.json
index e6e02ddc..068b6d8f 100644
--- a/packages/core/package.json
+++ b/packages/core/package.json
@@ -31,7 +31,7 @@
"build:watch": "tsdown --watch --silent",
"dev": "pnpm run build:watch",
"test": "echo \"No tests yet\"",
- "clean": "rm -rf dist"
+ "clean": "rm -rf dist types"
},
"dependencies": {
"@videojs/utils": "workspace:*"
diff --git a/packages/core/src/index.ts b/packages/core/src/core/index.ts
similarity index 100%
rename from packages/core/src/index.ts
rename to packages/core/src/core/index.ts
diff --git a/packages/core/src/dom/index.ts b/packages/core/src/dom/index.ts
index e69de29b..cb0ff5c3 100644
--- a/packages/core/src/dom/index.ts
+++ b/packages/core/src/dom/index.ts
@@ -0,0 +1 @@
+export {};
diff --git a/packages/core/src/dom/tsconfig.json b/packages/core/src/dom/tsconfig.json
index fdae4c67..7525a101 100644
--- a/packages/core/src/dom/tsconfig.json
+++ b/packages/core/src/dom/tsconfig.json
@@ -1,8 +1,10 @@
{
- "extends": "../../tsconfig.json",
+ "extends": "../../../../tsconfig.base.json",
"compilerOptions": {
"composite": true,
- "lib": ["ES2020", "DOM", "DOM.Iterable"]
+ "lib": ["ES2020", "DOM", "DOM.Iterable"],
+ "declarationDir": "../../types/dom"
},
+ "references": [{ "path": "../.." }],
"include": ["./**/*.ts"]
}
diff --git a/packages/core/tsconfig.build.json b/packages/core/tsconfig.build.json
deleted file mode 100644
index fc8520e7..00000000
--- a/packages/core/tsconfig.build.json
+++ /dev/null
@@ -1,3 +0,0 @@
-{
- "extends": "./tsconfig.json"
-}
diff --git a/packages/core/tsconfig.json b/packages/core/tsconfig.json
index f8b1218c..41391597 100644
--- a/packages/core/tsconfig.json
+++ b/packages/core/tsconfig.json
@@ -1,13 +1,9 @@
{
"extends": "../../tsconfig.base.json",
"compilerOptions": {
- "lib": ["ES2020"],
- "baseUrl": ".",
- "paths": {
- "@/*": ["src/*"]
- }
+ "composite": true,
+ "declarationDir": "types"
},
- "references": [{ "path": "./src/dom" }],
- "include": ["src"],
- "exclude": ["src/dom"]
+ "references": [{ "path": "../utils" }, { "path": "../store" }],
+ "include": ["src/core/**/*.ts"]
}
diff --git a/packages/core/tsdown.config.ts b/packages/core/tsdown.config.ts
index 6ac667da..654c46e3 100644
--- a/packages/core/tsdown.config.ts
+++ b/packages/core/tsdown.config.ts
@@ -2,7 +2,7 @@ import { defineConfig } from 'tsdown';
export default defineConfig({
entry: {
- index: './src/index.ts',
+ index: './src/core/index.ts',
dom: './src/dom/index.ts',
},
platform: 'neutral',
@@ -10,7 +10,7 @@ export default defineConfig({
sourcemap: true,
clean: true,
alias: {
- '@': new URL('./src', import.meta.url).pathname,
+ '@': new URL('./src/core', import.meta.url).pathname,
},
dts: {
oxc: true,
diff --git a/packages/html/package.json b/packages/html/package.json
index 14bc9fdd..c04741da 100644
--- a/packages/html/package.json
+++ b/packages/html/package.json
@@ -29,7 +29,7 @@
"build:watch": "tsdown --watch --silent",
"dev": "pnpm run build:watch",
"test": "echo \"No tests yet\"",
- "clean": "rm -rf dist"
+ "clean": "rm -rf dist types"
},
"dependencies": {
"@videojs/core": "workspace:*",
diff --git a/packages/html/tsconfig.build.json b/packages/html/tsconfig.build.json
deleted file mode 100644
index b90fc83e..00000000
--- a/packages/html/tsconfig.build.json
+++ /dev/null
@@ -1,4 +0,0 @@
-{
- "extends": "./tsconfig.json",
- "include": ["src"]
-}
diff --git a/packages/html/tsconfig.json b/packages/html/tsconfig.json
index 91cf2438..4bb47b9d 100644
--- a/packages/html/tsconfig.json
+++ b/packages/html/tsconfig.json
@@ -5,7 +5,8 @@
"baseUrl": ".",
"paths": {
"@/*": ["src/*"]
- }
+ },
+ "declarationDir": "types"
},
"include": ["src"]
}
diff --git a/packages/react/package.json b/packages/react/package.json
index 49e9add8..6c671590 100644
--- a/packages/react/package.json
+++ b/packages/react/package.json
@@ -29,7 +29,7 @@
"build:watch": "tsdown --watch ./src",
"dev": "pnpm run build:watch",
"test": "echo \"No tests yet\"",
- "clean": "rm -rf dist"
+ "clean": "rm -rf dist types"
},
"peerDependencies": {
"react": ">=16.8.0"
diff --git a/packages/react/tsconfig.build.json b/packages/react/tsconfig.build.json
deleted file mode 100644
index b90fc83e..00000000
--- a/packages/react/tsconfig.build.json
+++ /dev/null
@@ -1,4 +0,0 @@
-{
- "extends": "./tsconfig.json",
- "include": ["src"]
-}
diff --git a/packages/react/tsconfig.json b/packages/react/tsconfig.json
index f1157ea6..5a3a8afc 100644
--- a/packages/react/tsconfig.json
+++ b/packages/react/tsconfig.json
@@ -7,7 +7,8 @@
"baseUrl": ".",
"paths": {
"@/*": ["src/*"]
- }
+ },
+ "declarationDir": "types"
},
"include": ["src"]
}
diff --git a/packages/store/README.md b/packages/store/README.md
index 3fd0b4be..2870e744 100644
--- a/packages/store/README.md
+++ b/packages/store/README.md
@@ -211,27 +211,30 @@ const unsubscribe = store.subscribe((state) => {
console.log('State changed:', state);
});
-// Subscribe with selector
+// Single value - only fires when volume changes
store.subscribe(
- (state) => state.volume,
- (volume) => console.log('Volume:', volume)
+ s => s.volume,
+ volume => console.log('Volume:', volume)
);
-```
-### Keyed Subscriptions
+// Multiple values - auto-optimized with key-based subscription
+store.subscribe(
+ s => ({ volume: s.volume, muted: s.muted }),
+ ({ volume, muted }) => updateAudioUI(volume, muted)
+);
-Subscribe to specific keys for high-frequency updates:
+// Derived value
+store.subscribe(
+ s => Math.round(s.volume * 100),
+ percent => console.log(`${percent}%`)
+);
-```ts
-// Only fires when currentTime changes
-store.subscribe(['currentTime'], (state) => {
- updatedTime(state.currentTime);
-});
-
-// Multiple keys
-store.subscribe(['volume', 'muted'], (state) => {
- updatedVolume(state.volume, state.muted);
-});
+// Custom equality function
+store.subscribe(
+ s => s.playlist,
+ playlist => renderPlaylist(playlist),
+ { equalityFn: shallowEqual }
+);
```
Slices can push partial updates to avoid full syncs:
@@ -440,7 +443,7 @@ const store = createStore({
],
queue: createQueue({
// Default scheduler for requests without schedule
- scheduler: (flush) => queueMicrotask(flush),
+ scheduler: flush => queueMicrotask(flush),
// Lifecycle hooks
onDispatch: (request) => {
@@ -462,8 +465,12 @@ const store = createStore({
```ts
const queue = store.queue; // accessed on the store
-queue.queued; // requests waiting to execute
-queue.pending; // requests currently executing
+queue.queued; // object of requests waiting to execute
+queue.pending; // object of requests currently executing
+
+// Check if a task is pending or queued
+queue.isPending('playback'); // true if currently executing
+queue.isQueued('seek'); // true if waiting to execute
queue.dequeue('seek'); // remove from queue without executing
queue.clear(); // clear all queued
@@ -568,7 +575,7 @@ const store = createStore({
slices: [
/* ... */
],
- state: (initial) => new VueStateAdapter(initial),
+ state: initial => new VueStateAdapter(initial),
});
```
diff --git a/packages/store/package.json b/packages/store/package.json
index 92b94fb9..72f1517c 100644
--- a/packages/store/package.json
+++ b/packages/store/package.json
@@ -39,14 +39,18 @@
"build": "tsdown",
"build:watch": "tsdown --watch --silent",
"dev": "pnpm run build:watch",
- "test": "vitest --run",
+ "test": "vitest run",
"test:watch": "vitest",
- "clean": "rm -rf dist"
+ "clean": "rm -rf dist types"
},
"peerDependencies": {
+ "@lit/context": "^1.1.0",
"@lit/reactive-element": "^2.0.0"
},
"peerDependenciesMeta": {
+ "@lit/context": {
+ "optional": true
+ },
"@lit/reactive-element": {
"optional": true
}
@@ -55,6 +59,7 @@
"@videojs/utils": "workspace:*"
},
"devDependencies": {
+ "@lit/context": "^1.1.6",
"@lit/reactive-element": "^2.1.0",
"tsdown": "^0.15.9",
"typescript": "^5.9.3",
diff --git a/packages/store/src/errors.ts b/packages/store/src/core/errors.ts
similarity index 100%
rename from packages/store/src/errors.ts
rename to packages/store/src/core/errors.ts
diff --git a/packages/store/src/guard.ts b/packages/store/src/core/guard.ts
similarity index 79%
rename from packages/store/src/guard.ts
rename to packages/store/src/core/guard.ts
index 5dddbcbd..e32f1cb1 100644
--- a/packages/store/src/guard.ts
+++ b/packages/store/src/core/guard.ts
@@ -1,4 +1,5 @@
-import { isBoolean } from '@videojs/utils';
+import { isBoolean } from '@videojs/utils/predicate';
+
import { StoreError } from './errors';
/**
@@ -10,17 +11,12 @@ import { StoreError } from './errors';
* - Promise resolves falsy → cancel
* - Promise rejects → cancel
*/
-export type Guard = (ctx: {
- target: Target;
- signal: AbortSignal;
-}) => boolean | Promise;
+export type Guard = (ctx: { target: Target; signal: AbortSignal }) => boolean | Promise;
/**
* Combine guards: All must pass (truthy).
*/
-export function all(
- ...guards: Guard[]
-): Guard {
+export function all(...guards: Guard[]): Guard {
return async (ctx) => {
for (const guard of guards) {
const result = await guard(ctx);
@@ -34,9 +30,7 @@ export function all(
/**
* Combine guards: Any must pass (first truthy wins).
*/
-export function any(
- ...guards: Guard[]
-): Guard {
+export function any(...guards: Guard[]): Guard {
return (ctx) => {
const results = guards.map(g => g(ctx));
@@ -64,11 +58,7 @@ export function any(
/**
* Add timeout to a guard.
*/
-export function timeout(
- guard: Guard,
- ms: number,
- name = 'guard',
-): Guard {
+export function timeout(guard: Guard, ms: number, name = 'guard'): Guard {
return async (ctx) => {
const result = guard(ctx);
diff --git a/packages/store/src/index.ts b/packages/store/src/core/index.ts
similarity index 100%
rename from packages/store/src/index.ts
rename to packages/store/src/core/index.ts
diff --git a/packages/store/src/queue.ts b/packages/store/src/core/queue.ts
similarity index 64%
rename from packages/store/src/queue.ts
rename to packages/store/src/core/queue.ts
index 3176b6d0..266698a6 100644
--- a/packages/store/src/queue.ts
+++ b/packages/store/src/core/queue.ts
@@ -1,5 +1,7 @@
import type { Request, RequestMeta } from './request';
-import { isFunction, isUndefined } from '@videojs/utils';
+
+import { isFunction, isUndefined } from '@videojs/utils/predicate';
+
import { StoreError } from './errors';
// ----------------------------------------
@@ -8,6 +10,8 @@ import { StoreError } from './errors';
export type TaskKey = T & (string | symbol);
+export type EnsureTaskKey = T extends string | symbol ? T : never;
+
/**
* A task scheduler controls when a task flushes.
*
@@ -19,7 +23,7 @@ export type TaskScheduler = (flush: () => void) => (() => void) | void;
* Map of task key -> input/output types.
*/
export type TaskRecord = {
- [K in TaskKey]: Request
+ [K in TaskKey]: Request;
};
/**
@@ -35,10 +39,7 @@ export type EnsureTaskRecord = T extends TaskRecord ? T : never;
/**
* Pending task info.
*/
-export interface PendingTask<
- Key extends TaskKey = TaskKey,
- Input = unknown,
-> {
+export interface PendingTask {
id: symbol;
name: string;
key: Key;
@@ -51,21 +52,27 @@ export interface PendingTask<
/**
* Context passed to task handler.
*/
-export interface TaskContext<
- Input = unknown,
-> {
+export interface TaskContext {
input: Input;
signal: AbortSignal;
}
+/**
+ * Task to enqueue.
+ */
+export interface QueueTask {
+ name: string;
+ key: Key;
+ input?: Input;
+ meta?: RequestMeta | null;
+ schedule?: TaskScheduler | undefined;
+ handler: (ctx: TaskContext) => Promise