vidstack · mihar-22 · Sep 2, 2026 · Sep 2, 2026 · Sep 2, 2026 · Sep 2, 2026
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -0,0 +1,47 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      # Formatting (oxfmt) and linting (oxlint) through Vite+.
+      - run: pnpm check
+      - run: pnpm typecheck
+      - run: pnpm coverage
+      - uses: actions/upload-artifact@v4
+        with:
+          name: coverage
+          path: coverage
+          if-no-files-found: ignore
+      - run: pnpm exec playwright install --with-deps chromium firefox webkit
+      # Includes the visual suite: its Linux Chromium baselines are committed (re-record them with
+      # record-baselines.yml after an intentional rendering change).
+      - run: pnpm vp test --run --project browser
+        env:
+          BROWSERS: chromium,firefox,webkit
+      - run: pnpm build
+      - run: pnpm size
+      # `pnpm docs` is forwarded to npm's built-in `docs` (opens a browser); run the script.
+      - run: pnpm run docs
+      - uses: actions/upload-artifact@v4
+        with:
+          name: api-docs
+          path: docs/api
+      - uses: actions/upload-artifact@v4
+        if: failure()
+        with:
+          name: vitest-attachments
+          path: .vitest-attachments
+          if-no-files-found: ignore
diff --git a/.github/workflows/record-baselines.yml b/.github/workflows/record-baselines.yml
@@ -0,0 +1,30 @@
+name: Record visual baselines
+
+# Records the Chromium screenshot baselines on Linux (the CI platform) and uploads them as an
+# artifact. Trigger manually after an intentional rendering change, then:
+#
+#   gh run download <run-id> -n visual-baselines -D tests/browser/__screenshots__
+#
+# and commit the result. Baselines are per browser and platform, so the macOS ones recorded locally
+# stay untouched.
+on:
+  workflow_dispatch:
+
+jobs:
+  record:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm exec playwright install --with-deps chromium
+      - run: pnpm vp test --run --project browser tests/browser/visual.test.ts --update
+      - uses: actions/upload-artifact@v4
+        with:
+          name: visual-baselines
+          path: tests/browser/__screenshots__/visual.test.ts/*-linux.png
+          if-no-files-found: error
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -0,0 +1,38 @@
+name: Release
+
+# Publishes to npm with provenance when a version tag is pushed. Requires the `NPM_TOKEN` secret
+# (or configure npm trusted publishing for this repository and drop the token).
+on:
+  push:
+    tags: ['v*']
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+          registry-url: https://registry.npmjs.org
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm check
+      - run: pnpm typecheck
+      - run: pnpm test:unit
+      - run: pnpm build
+      - run: pnpm size
+      - run: pnpm changelog
+      - run: npm publish --provenance --access public --tag ${{ contains(github.ref_name, '-') && 'next' || 'latest' }}
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+      - uses: softprops/action-gh-release@v2
+        with:
+          body_path: CHANGELOG.md
+          generate_release_notes: true
diff --git a/.gitignore b/.gitignore
@@ -11,3 +11,8 @@ yarn-debug.log*
 yarn-error.log*
 pnpm-debug.log*
 
+
+.vitest-attachments/
+
+docs/api/
+coverage/
diff --git a/.prettierrc.cjs b/.prettierrc.cjs
diff --git a/.sandbox/index.html b/.sandbox/index.html
@@ -1,42 +1,91 @@
+<!doctype html>
 <html>
   <head>
-    <title>Media Captions</title>
+    <title>Media Captions Sandbox</title>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <link rel="icon" type="image/png" sizes="32x32" href="/sandbox/favicon-32x32.png" />
     <link rel="stylesheet" href="/styles/captions.css" />
     <link rel="stylesheet" href="/styles/regions.css" />
-    <script type="module" src="/sandbox/main.ts"></script>
+    <script type="module" src="/.sandbox/main.ts"></script>
     <style>
       body {
         margin: 0;
-        width: 100vw;
-        height: 100vh;
+        min-height: 100vh;
         display: flex;
         flex-direction: column;
         align-items: center;
         justify-content: center;
-        box-sizing: border-box;
+        gap: 24px;
+        background: #111;
+        color: #eee;
+        font-family: system-ui, sans-serif;
       }
 
       .viewport {
         position: relative;
         width: 960px;
         height: 540px;
-        background-color: #dcdcdc;
+        overflow: hidden;
+        border-radius: 8px;
+        background: linear-gradient(160deg, #4a5a7a 0%, #2b3550 45%, #151826 100%);
         box-sizing: border-box;
       }
 
-      #current-time {
-        margin-top: 48px;
+      .viewport.small {
+        width: 464px;
+        height: 261px;
+      }
+
+      .grid {
+        display: grid;
+        grid-template-columns: repeat(2, 464px);
+        gap: 16px;
+      }
+
+      .grid [data-part='captions'] {
+        --cue-font-size: 9cqh;
+      }
+
+      .label {
+        position: absolute;
+        top: 12px;
+        left: 12px;
+        padding: 4px 8px;
+        font-size: 13px;
+        border-radius: 4px;
+        background: rgba(0, 0, 0, 0.55);
+        pointer-events: none;
+        z-index: 2;
+      }
+
+      .controls {
+        display: flex;
+        gap: 12px;
+        align-items: center;
+      }
+
+      .controls a {
+        color: #9cc4ff;
+      }
+
+      /* Karaoke styling for the demo: sung words are highlighted. */
+      [data-part='timed'][data-past] {
+        color: #ffd166;
+      }
+
+      [data-part='timed'][data-future] {
+        opacity: 0.6;
       }
     </style>
   </head>
   <body>
-    <div class="viewport">
-      <div id="overlay"></div>
+    <div id="root"></div>
+    <div class="controls">
+      <label>
+        Time
+        <input id="current-time" type="number" value="3" step="0.5" style="width: 80px" />
+      </label>
+      <span id="links"></span>
     </div>
-
-    <input id="current-time" type="number" value="0" />
   </body>
 </html>
diff --git a/.sandbox/launch.js b/.sandbox/launch.js
@@ -1,23 +1,3 @@
 import { execSync } from 'child_process';
-import fs from 'fs';
-import path from 'path';
 
-const SANDBOX_TEMPLATE = path.resolve(process.cwd(), '.sandbox'),
-  SANDBOX_DIR = path.resolve(process.cwd(), 'sandbox'),
-  IGNORED_FILES = new Set(['launch.js']);
-
-// Copy files from .sandbox template directory to sandbox.
-if (!fs.existsSync(SANDBOX_DIR)) {
-  fs.mkdirSync(SANDBOX_DIR);
-  const files = fs.readdirSync(SANDBOX_TEMPLATE);
-  for (const file of files) {
-    if (IGNORED_FILES.has(file)) continue;
-    const from = path.resolve(SANDBOX_TEMPLATE, file);
-    const to = path.resolve(SANDBOX_DIR, file);
-    fs.writeFileSync(to, fs.readFileSync(from, 'utf-8'));
-  }
-}
-
-execSync('vite --open=/sandbox/index.html --port=3100 --host', {
-  stdio: 'inherit',
-});
+execSync('vp dev --open=/.sandbox/index.html --port=3100 --host', { stdio: 'inherit' });