zoriya/v10
1
0
Fork 0
mirror of https://github.com/zoriya/v10.git synced 2026-08-04 21:27:10 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs(root): fix stale references and document sandbox workflow (#1464)

Browse Source 
Co-authored-by: Claude <noreply@anthropic.com>
This commit is contained in:
Darius Cepulis
2026-04-24 14:29:24 -05:00
committed by GitHub
co-authored by Claude
parent b9349375cb
commit 89594292d4
9 changed files with 272 additions and 55 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CLAUDE.md
+12 -6
View File
@@ -21,7 +21,9 @@ Refer to **[`CONTRIBUTING.md`](./CONTRIBUTING.md)** for setup, development, and
| `packages/html` | Web player—DOM/Browser‑specific implementation. |
| `packages/react` | React player—adapts core state to React components. |
| `packages/react-native` | React Native player (planned, not yet implemented). |
| `packages/cli` | `@videojs/cli` — CLI for reading docs, and more in the future. |
| `apps/sandbox` | Vite‑based dev playground (private, not published). |
| `apps/e2e` | Playwright end‑to‑end and visual snapshot tests (private). |
| `site/` | Astro‑based docs and website. |
### Dependency Hierarchy
@@ -54,6 +56,7 @@ react-native ← React Native player (planned, not yet implemented)
utils ← element
utils ← store ← core ← html / react
utils ← spf ← core
icons, skins → html / react
```
## Workspace
@@ -518,11 +521,12 @@ export type FeatureAvailability = 'available' | 'unavailable' | 'unsupported';
## Design Documents
| Location | Purpose |
| ------------------ | ---------------------------------------------------------- |
| `internal/design/` | Decisions you own — document for posterity |
| `rfc/` | Proposals needing buy-in — get alignment before committing |
| `.claude/plans/` | Implementation notes, AI-agent context, working drafts |
| Location | Purpose |
| --------------------- | ---------------------------------------------------------- |
| `internal/design/` | Architecture specs and feature designs you own |
| `internal/decisions/` | ADR-style records of single tactical decisions |
| `rfc/` | Proposals needing buy-in — get alignment before committing |
| `.claude/plans/` | Implementation notes, AI-agent context, working drafts |
### Design Doc vs RFC
@@ -532,7 +536,9 @@ export type FeatureAvailability = 'available' | 'unavailable' | 'unsupported';
| **Approval** | None needed | Needs buy-in from others |
| **Purpose** | Document for posterity | Get alignment first |
**Design Docs** — Decisions you own. Write one when making significant decisions in your area, choosing between approaches, or documenting architecture others will build on. See `internal/design/README.md`.
**Design Docs** — Architecture specs and feature designs in your area. Longer-form, status ranges from `draft` → `decided` → `implemented` → `superseded`. See `internal/design/README.md`.
**Decisions** — ADR-style records of a single tactical decision: what was chosen, why, what was ruled out. Short, always `decided`, often cross-reference each other. See `internal/decisions/README.md`.
**RFCs** — Cross-team alignment. Write one when the decision affects multiple areas, changes shared API surface, or is hard to reverse. See `rfc/README.md`.
CONTRIBUTING.md
+69 -19
View File
@@ -36,7 +36,7 @@ You’ll need the following installed:
```sh
git clone https://github.com/{your-github-username}/v10.git
cd vjs-10
cd v10
git remote add upstream git@github.com:videojs/v10.git
git fetch upstream
@@ -84,10 +84,13 @@ pnpm dev
This will run the entire workspace in developer mode, meaning all applications (examples and website) will also be started on their respective ports.
```sh
# Run the documentation site
pnpm dev:site
pnpm dev:site # just the documentation site
pnpm dev:packages # just the library packages (no apps)
pnpm dev:sandbox # just the sandbox playground
```
See [Manual Testing with the Sandbox](#-manual-testing-with-the-sandbox) for how to use the sandbox to exercise player changes in the browser.
Sometimes you may want to do (non-dev) builds, say, to validate the full build process or evaluate production artifacts.
```sh
@@ -113,12 +116,24 @@ For the bulk of our core code, we use [Biome](https://biomejs.dev). Between IDE
To ensure your code follows our lint rules with:
```sh
pnpm lint
pnpm lint:fix
pnpm lint # check the whole workspace
pnpm lint:fix # check and auto-fix the whole workspace
pnpm lint:fix:file <file> # check and auto-fix a single file
```
Pre‑commit hooks automatically lint staged files via **simple-git-hooks** and **lint‑staged**.
### 🔎 Typechecking
We use TypeScript project references for fast, incremental typechecking across the workspace:
```sh
pnpm typecheck
```
> [!TIP]
> Typecheck runs against built `.d.ts` files. If you add or change exported types in a package, run `pnpm -F <pkg> build` first so the new declarations are emitted before typechecking.
### 🧪 Testing
We use [Vitest](https://vitest.dev) for unit testing.
@@ -163,6 +178,35 @@ pnpm test:e2e:vite # Chromium only (fast feedback)
> [!TIP]
> Snapshot baselines are checked into git. When you update them, review the PNG diffs in your PR to make sure the visual changes are intentional.
### 🏖 Manual Testing with the Sandbox
The sandbox (`apps/sandbox/`) is a Vite playground for manually exercising player changes in a browser. The root URL renders an interactive shell — a navbar with dropdowns for platform, preset, skin, styling, and source — that previews the selected combination in an iframe. One-off templates outside the main matrix are reachable by navigating directly to `/<template-name>/`. See `apps/sandbox/templates/` for the full list.
```sh
pnpm dev:sandbox # sandbox + workspace package watch
pnpm dev # also runs the docs site
```
Sandbox code lives in two parallel directories:
- **`apps/sandbox/templates/`** — source of truth, checked into git.
- **`apps/sandbox/src/`** — your scratch copy, fully gitignored.
On `pnpm dev:sandbox`, `setup.ts` copies any file from `templates/` that doesn't already exist in `src/`. Existing files in `src/` are never overwritten, so your local changes persist across restarts.
> [!IMPORTANT]
> Because `src/` is gitignored, edits you make there will not appear in `git status`. When you want to promote a sandbox change into the repo, run `pnpm -F @videojs/sandbox sync` — it shows a diff of every changed file and prompts before copying `src/` → `templates/`. To throw away local edits and restore from templates, run `pnpm -F @videojs/sandbox reset`.
See [`apps/sandbox/README.md`](./apps/sandbox/README.md) for the full model, including the `app/` shell, the `@app/*` alias for shared code, and how to add a new sandbox entry point.
### ✅ Workspace Consistency
Before opening a PR, run the workspace consistency check to catch common mistakes (CI coverage, scope mismatches, broken define imports, etc.):
```sh
pnpm check:workspace
```
### 📦 Dependencies
To add a dependency to a specific package, you can use [`pnpm` filtering][pnpm-filtering] from the workspace root:
@@ -190,25 +234,31 @@ Video.js 10 includes tooling for AI-assisted development with [Claude Code](http
### Slash Commands
| Command | Purpose |
| ---------------- | ------------------------------------- |
| `/commit-pr` | Commit changes and create/update a PR |
| `/review-branch` | Review changes in the current branch |
| `/gh-issue <n>` | Analyze an issue and generate a plan |
| Command | Purpose |
| ---------------- | ------------------------------------------------- |
| `/commit-pr` | Commit changes and create/update a PR |
| `/review-branch` | Review changes in the current branch |
| `/gh-issue <n>` | Analyze an issue and generate a plan |
| `/create-issue` | Create a GitHub issue following repo conventions |
| `/claude-update` | Update `CLAUDE.md` and skills for new patterns |
| `/create-skill` | Scaffold a new skill |
### Skills
Domain-specific knowledge lives in `.claude/skills/`:
Domain-specific knowledge lives in `.claude/skills/`. A few of the most-used skills:
| Skill | Use When |
| ----------- | --------------------------------------- |
| `api` | Designing APIs, reviewing architecture |
| `component` | Building UI components |
| `aria` | Accessibility implementation and review |
| `docs` | Writing documentation |
| `git` | Commit messages, PR conventions |
| Skill | Use When |
| --------------- | -------------------------------------------------------- |
| `api` | Designing APIs, reviewing architecture |
| `component` | Building HTML or React components |
| `aria` | Accessibility implementation and review |
| `docs` | Writing concept guides, how-tos, and READMEs |
| `api-reference` | Scaffolding component/util reference pages |
| `design` | Writing internal Design Docs |
| `rfc` | Writing RFCs for proposals that need buy-in |
| `git` | Commit messages, PR conventions |
See [`.claude/skills/README.md`](./.claude/skills/README.md) for workflow mappings.
See [`.claude/skills/README.md`](./.claude/skills/README.md) for the full list and workflow mappings.
### Maintaining AI Docs
README.md
+2 -2
View File
@@ -17,8 +17,8 @@ Video.js v10 is close to stable. Try it out in real projects and share your feed
## Timeline
- **Technical Preview (Complete):** Initial showcase for Demuxed.
- **Alpha (Jan–Feb 2026):** [See milestone](https://github.com/videojs/v10/milestone/3)
- **Beta (Mar 2026):** [See milestone](https://github.com/videojs/v10/milestone/1)
- **Alpha (Complete):** [See milestone](https://github.com/videojs/v10/milestone/3)
- **Beta (Complete):** [See milestone](https://github.com/videojs/v10/milestone/1)
- **GA (Mid 2026):** [See milestone](https://github.com/videojs/v10/milestone/6) ← WIP
- **Video.js (End of 2026):** Video.js core/contrib parity and supported plugins migrated.
apps/sandbox/README.md
+41 -27
View File
@@ -1,45 +1,51 @@
# @videojs/sandbox
Vite-based playground for testing and developing Video.js 10 integrations. Each sandbox is a standalone entry point that demonstrates a different platform or scenario.
## Sandboxes
| Name | Description |
| ------------------- | -------------------------------------- |
| `core` | Framework-agnostic core API |
| `html` | HTML player with skin switching |
| `html-background` | Full-screen background video (HTML) |
| `html-tailwind` | HTML player styled with Tailwind CSS |
| `react` | React player with skin switching |
| `react-tailwind` | React player styled with Tailwind CSS |
| `react-background` | Full-screen background video (React) |
Vite-based playground for testing and developing Video.js 10 integrations. Each sandbox is a standalone entry point that demonstrates a different platform, media engine, or scenario.
## Getting started
```bash
# From the repo root
pnpm dev
# Or just the sandbox
pnpm -F sandbox dev
pnpm dev:sandbox # sandbox + workspace package watch
pnpm dev # also runs the docs site
```
This runs `setup.ts` first, which mirrors any missing files from `templates/` into `src/`, then starts the Vite dev server. Open the root URL to see links to all sandboxes.
Open the printed URL. The root route renders an interactive shell — a navbar with dropdowns for platform (HTML, React, CDN), preset (`video`, `hls-video`, `audio`, etc.), skin, styling (CSS or Tailwind), and source — that previews the selected combination in an iframe. Use the **Open** button to pop the preview out into its own tab.
The shell covers the main combinatorial matrix. One-off templates not in that matrix (e.g. `firefox-mse-repro`, `spf-segment-loading`, `simple-hls-html`) are reachable by navigating directly to `/<template-name>/`. See `apps/sandbox/templates/` for the full list.
## How it works
The package has two parallel directories:
Three directories participate:
- **`templates/`** — Checked into git. The source of truth for each sandbox's starting point.
- **`src/`** — Gitignored (except `index.html`). Your working copy where you freely edit, experiment, and break things.
- **`app/`** — The React-rendered shell served at `/`, plus shared helpers that sandboxes import via the `@app/*` alias. Checked into git.
- **`templates/`** — The source of truth for each sandbox. One subdirectory per entry point, each containing its own `index.html` and `main.ts` / `main.tsx`. Checked into git.
- **`src/`** — Your working copy where you freely edit, experiment, and break things. Fully gitignored (`src/*`).
On `pnpm dev`, `setup.ts` copies any file from `templates/` that doesn't already exist in `src/`. Existing files in `src/` are never overwritten, so your local changes are preserved across restarts.
On `pnpm dev:sandbox`, `scripts/setup.ts` mirrors every file from `templates/` into `src/` that doesn't already exist there. Existing files in `src/` are never overwritten, so your local changes persist across restarts.
Vite discovers sandbox entries by scanning `src/*` for subdirectories that contain an `index.html` — no manual registration is needed.
> [!NOTE]
> `src/index.html` is generated by the `serve-app-shell` Vite plugin on every dev/build — don't edit it by hand.
### Sharing code with `@app/*`
Templates can import shared helpers from the `app/` directory via the `@app` alias:
```ts
import '@app/styles.css';
import { SOURCES } from '@app/shared/sources';
```
See `templates/html-video/main.ts` for a minimal reference, or `templates/react-video/main.tsx` for a React one.
## Syncing changes back to templates
When you've made improvements in `src/` that should become the new baseline:
```bash
pnpm -F sandbox sync
pnpm -F @videojs/sandbox sync
```
This shows a colored diff of every changed file, then prompts for confirmation before copying `src/` changes into `templates/`. Files that only exist in `templates/` are left untouched.
@@ -47,12 +53,20 @@ This shows a colored diff of every changed file, then prompts for confirmation b
Sync when:
- You've fixed a bug or improved a sandbox and want to preserve it for others.
- You're preparing a commit — templates are what gets checked in.
- You're preparing a commit — `templates/` is what gets checked in.
## Resetting your sandbox
To throw away your local `src/` edits and restore from `templates/`:
```bash
pnpm -F @videojs/sandbox reset
```
This previews every change first and prompts before doing anything. It overwrites modified files, deletes files that exist only in `src/`, and restores any missing template files. **Cannot be undone**, so commit or `sync` anything you want to keep first.
## Adding a new sandbox
1. Create a directory in `templates/` (e.g. `templates/my-feature/`).
2. Add an `index.html` entry point and a `main.ts` or `main.tsx`.
3. Add a link to your sandbox in `templates/index.html`.
4. Register the entry in `vite.config.ts` under `rollupOptions.input`.
5. Run `pnpm dev` — `setup.ts` mirrors the new template into `src/` automatically.
2. Add an `index.html` entry point and a `main.ts` or `main.tsx`. Import shared helpers from `@app/*` as needed.
3. Run `pnpm dev:sandbox` — `setup.ts` mirrors the new template into `src/`, and Vite picks it up automatically.
internal/decisions/README.md
+66
View File
@@ -0,0 +1,66 @@
# Decisions
ADR-style records of single tactical decisions.
## What Belongs Here
A decision doc captures **one specific choice**: what was decided, why, and what was ruled out. Keep them short and focused — usually one page.
Write one when:
- You picked one approach over another and want the reasoning on record.
- A decision depends on or supersedes an earlier one (link across docs).
- You want future contributors to understand why the code is the way it is.
## Decisions vs Design Docs
Use a **design doc** (`internal/design/`) when you're specifying architecture, a feature, or a subsystem — forward-looking, often longer, status ranges from `draft` → `decided` → `implemented` → `superseded`.
Use a **decision doc** here when you're recording a single trade-off within that work — short, always `status: decided`.
A design doc often spawns several decision docs as implementation choices get made.
## Format
```markdown
---
status: decided
date: 2026-01-27
---
# Title
## Decision
What you decided. Be direct.
## Context
Why this came up. What problem triggered the decision. Link related decisions.
## Alternatives Considered
- **Option A** — Why not chosen
- **Option B** — Why not chosen
## Rationale
Why this choice wins. Keep concise.
```
## File Naming
Lowercase with hyphens, name after the subject of the decision:
```
captions.md
gestures-as-components.md
provider-attach.md
```
## See Also
- [Design Docs](/internal/design/README.md) — Architecture specs and feature designs
- [RFCs](/rfc/README.md) — Proposals needing buy-in
- [Plans](/.claude/plans/README.md) — Implementation notes
- [CLAUDE.md](/CLAUDE.md#design-documents) — How these relate
internal/design/README.md
+1
View File
@@ -76,6 +76,7 @@ skin-theming.md
## See Also
- [Decisions](/internal/decisions/README.md) — ADR-style single-decision records
- [RFCs](/rfc/README.md) — Proposals needing buy-in
- [Plans](/.claude/plans/README.md) — Implementation details
- [CLAUDE.md](/CLAUDE.md#design-documents) — How these relate
package.json
+1 -1
View File
@@ -8,7 +8,7 @@
"license": "Apache-2.0",
"repository": {
"type": "git",
"url": "https://github.com/videojs/vjs-10-monorepo.git"
"url": "https://github.com/videojs/v10.git"
},
"engines": {
"node": ">=22.19.0",
packages/cli/README.md
+63
View File
@@ -0,0 +1,63 @@
# @videojs/cli
[![package-badge]][package]
> **⚠️ Beta** Experimental adoption in real projects.
The Video.js 10 CLI. Read documentation from your terminal and generate installation snippets tailored to your setup (framework, preset, skin, media engine, package manager).
## Install
Run without installing:
```bash
npx @videojs/cli --help
```
Or install globally:
```bash
npm install -g @videojs/cli
videojs --help
```
> Scripts below use `videojs` for brevity — substitute `npx @videojs/cli` if you don't install globally.
## Examples
Read a doc page:
```bash
videojs docs concepts/overview
```
Generate a framework-specific installation snippet interactively:
```bash
videojs docs how-to/installation \
--framework react \
--preset video \
--skin default \
--media hls \
--install-method pnpm \
--source-url https://example.com/video.m3u8
```
For full usage, run `videojs --help`, `videojs docs --help`, or `videojs config --help`.
## Community
If you need help with anything related to Video.js 10, or if you'd like to casually chat with other
members:
- [Join Discord Server][discord]
- [See GitHub Discussions][gh-discussions]
## License
[Apache-2.0](./LICENSE)
[package]: https://www.npmjs.com/package/@videojs/cli
[package-badge]: https://img.shields.io/npm/v/@videojs/cli?label=@videojs/cli
[discord]: https://discord.gg/JBqHh485uF
[gh-discussions]: https://github.com/videojs/v10/discussions
packages/skins/README.md
+17
View File
@@ -0,0 +1,17 @@
# @videojs/skins
> **Internal package — do not install directly.**
Shared skin CSS and Tailwind classname tokens for Video.js 10. Consumed by [`@videojs/html`](../html) and [`@videojs/react`](../react), which re-export the skins you actually use in an app.
The package is private (`"private": true` in `package.json`) and is not published to npm.
## Structure
- `src/default/` — default skin tokens and CSS.
- `src/minimal/` — minimal skin tokens and CSS.
- `src/shared/` — tokens shared between skins.
## License
[Apache-2.0](../../LICENSE)