# @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, media engine, or scenario.

## Getting started

```bash
# From the repo root
pnpm dev:sandbox             # sandbox + workspace package watch
pnpm dev                     # also runs the docs site
```

Open the printed URL. The root route renders an interactive shell — a navbar with dropdowns for platform (HTML, React, CDN), preset (`video`, `hlsjs-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.

**Language** is in **Player settings** (gear icon) for every preset (HTML, React, and CDN). **CDN** registers copy through `@videojs/html/cdn/i18n` (the same registry as the CDN player bundle), not source `@videojs/html/i18n`. After pulling template changes, restart `pnpm dev:sandbox` so `scripts/setup.ts` refreshes `src/` from `templates/`.

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

Three directories participate:

- **`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:sandbox`, `scripts/setup.ts` mirrors new files from `templates/` into `src/` and overwrites `src/` files that differ from `templates/`. Edits made only in `src/` are replaced on the next dev start — use `sync` to copy them into `templates/` first.

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 @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.

Sync when:

- You've fixed a bug or improved a sandbox and want to preserve it for others.
- 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`. 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.
