From 89594292d46fbb1a752867dd9b33b20b81eb27ad Mon Sep 17 00:00:00 2001 From: Darius Cepulis Date: Fri, 24 Apr 2026 14:29:24 -0500 Subject: [PATCH] docs(root): fix stale references and document sandbox workflow (#1464) Co-authored-by: Claude --- CLAUDE.md | 18 +++++--- CONTRIBUTING.md | 88 ++++++++++++++++++++++++++++-------- README.md | 4 +- apps/sandbox/README.md | 68 +++++++++++++++++----------- internal/decisions/README.md | 66 +++++++++++++++++++++++++++ internal/design/README.md | 1 + package.json | 2 +- packages/cli/README.md | 63 ++++++++++++++++++++++++++ packages/skins/README.md | 17 +++++++ 9 files changed, 272 insertions(+), 55 deletions(-) create mode 100644 internal/decisions/README.md create mode 100644 packages/cli/README.md create mode 100644 packages/skins/README.md diff --git a/CLAUDE.md b/CLAUDE.md index 4b91f64c..72bfeb94 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -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`. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 532cf47c..83a1cdea 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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 # 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 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 `//`. 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 ` | 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 ` | 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 diff --git a/README.md b/README.md index 7db2bcc3..439a33df 100644 --- a/README.md +++ b/README.md @@ -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. diff --git a/apps/sandbox/README.md b/apps/sandbox/README.md index 2f1b34cd..3f397305 100644 --- a/apps/sandbox/README.md +++ b/apps/sandbox/README.md @@ -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 `//`. 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. diff --git a/internal/decisions/README.md b/internal/decisions/README.md new file mode 100644 index 00000000..9f98366d --- /dev/null +++ b/internal/decisions/README.md @@ -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 diff --git a/internal/design/README.md b/internal/design/README.md index 3b4572f9..2591b274 100644 --- a/internal/design/README.md +++ b/internal/design/README.md @@ -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 diff --git a/package.json b/package.json index 6912ebbb..8eb4e78c 100644 --- a/package.json +++ b/package.json @@ -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", diff --git a/packages/cli/README.md b/packages/cli/README.md new file mode 100644 index 00000000..0b29eb55 --- /dev/null +++ b/packages/cli/README.md @@ -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 diff --git a/packages/skins/README.md b/packages/skins/README.md new file mode 100644 index 00000000..40002314 --- /dev/null +++ b/packages/skins/README.md @@ -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)