streamer45
diff --git a/‎.agents/skills/testing-compositor-ui/SKILL.md‎
Lines changed: 51 additions & 0 deletions b/‎.agents/skills/testing-compositor-ui/SKILL.md‎
Lines changed: 51 additions & 0 deletions
diff --git a/‎.github/workflows/e2e.yml‎
Lines changed: 3 additions & 0 deletions b/‎.github/workflows/e2e.yml‎
Lines changed: 3 additions & 0 deletions
diff --git a/‎.github/workflows/skit.yml‎
Lines changed: 9 additions & 0 deletions b/‎.github/workflows/skit.yml‎
Lines changed: 9 additions & 0 deletions
diff --git a/‎AGENTS.md‎
Lines changed: 105 additions & 0 deletions b/‎AGENTS.md‎
Lines changed: 105 additions & 0 deletions
@@ -0,0 +1,51 @@
+<!--
+SPDX-FileCopyrightText: © 2025 StreamKit Contributors
+
+SPDX-License-Identifier: MPL-2.0
+-->
+
+# Testing the Video Compositor UI
+
+## Overview
+The video compositor node (`video::compositor`) has a visual canvas in the Design view where layers (input video, text overlays, image overlays) can be positioned, resized, and configured.
+
+## Setup
+1. Start backend: `SK_SERVER__MOQ_GATEWAY_URL=http://127.0.0.1:4545/moq SK_SERVER__ADDRESS=127.0.0.1:4545 just skit`
+2. Start UI: `just ui`
+3. Navigate to `http://localhost:3045/design`
+
+## Loading a Compositor Pipeline
+- The easiest way to get a compositor node on the canvas is to load a pre-built sample
+- Click the **Samples** tab in the left sidebar
+- Click **"Video Compositor (MoQ Stream)"** to load a pipeline with a compositor node and two colorbars inputs
+- Another option: **"Webcam PiP (MoQ Stream)"** includes a compositor with a text overlay already configured
+- Drag-and-drop from the Nodes library is difficult with browser automation; prefer loading samples
+
+## Adding Text Overlays
+- The compositor node has a **Layers** panel with an **"Add"** button
+- The Add button may be offscreen in the node; use JavaScript `scrollIntoView()` + `click()` to interact with it
+- Click **Add > Text** to add a text overlay
+- The new text layer appears in the Layers list and on the canvas with a dashed bounding box
+
+## Configuring Text Overlays
+- Click a text layer in the Layers list to select it
+- The inspector panel shows:
+  - **Content**: textarea for the text string
+  - **Size**: number input for font size (in pixels)
+  - **Font**: dropdown with DejaVu font variants
+  - **Color**: color picker
+  - **Opacity**: slider
+  - **Rotation**: preset buttons (0/90/180/270) and slider
+  - **Mirror**: horizontal/vertical toggle buttons
+- Use JavaScript `nativeInputValueSetter` + dispatching `input`/`change` events for React-controlled inputs
+
+## Key Behavior to Verify
+- Text should be aligned to the **top-left** of its bounding box (matching backend rendering from origin 0,0)
+- Font size should be proportional to the bounding box (no double-scaling from CSS transform)
+- The `CanvasInner` component applies `transform: scale(scale)` via CSS, so overlay content should use raw pixel values
+- Bounding box should auto-expand height to fit text content
+
+## Relevant Files
+- `ui/src/components/CompositorCanvas.tsx` — Main canvas component with overlay rendering
+- `ui/src/hooks/useCompositorLayers.ts` — Layer state management hook
+- `crates/nodes/src/video/compositor/overlay.rs` — Backend text rendering (uses fontdue)
@@ -46,6 +46,9 @@ jobs:
 
       - uses: Swatinem/rust-cache@v2
 
+      - name: Install system dependencies (libvpx for VP9 video support)
+        run: sudo apt-get update && sudo apt-get install -y libvpx-dev
+
       - name: Build skit (debug)
         run: cargo build -p streamkit-server --bin skit
 
 
@@ -36,6 +36,9 @@ jobs:
           bun install --frozen-lockfile
           bun run build
 
+      - name: Install system dependencies (libvpx for VP9 video support)
+        run: sudo apt-get update && sudo apt-get install -y libvpx-dev
+
       - name: Install Rust toolchain
         uses: dtolnay/rust-toolchain@master
         with:
@@ -89,6 +92,9 @@ jobs:
           bun install --frozen-lockfile
           bun run build
 
+      - name: Install system dependencies (libvpx for VP9 video support)
+        run: sudo apt-get update && sudo apt-get install -y libvpx-dev
+
       - name: Install Rust toolchain
         uses: dtolnay/rust-toolchain@master
         with:
@@ -129,6 +135,9 @@ jobs:
           bun install --frozen-lockfile
           bun run build
 
+      - name: Install system dependencies (libvpx for VP9 video support)
+        run: sudo apt-get update && sudo apt-get install -y libvpx-dev
+
       - name: Install Rust toolchain
         uses: dtolnay/rust-toolchain@master
         with:
 
@@ -27,6 +27,111 @@ Agent-assisted contributions are welcome, but should be **supervised** and **rev
 - Follow `CONTRIBUTING.md` (DCO sign-off, Conventional Commits, SPDX headers where applicable).
 - **Linting discipline**: Do not blindly suppress lint warnings or errors with ignore/exception rules. Instead, consider refactoring or improving the code to address the underlying issue. If an exception is truly necessary, it **must** include a comment explaining the rationale.
 
+## Running E2E tests
+
+End-to-end tests live in `e2e/` and use Playwright (Chromium, headless).
+
+1. **Build the UI** and **start the server** in one terminal:
+
+   ```bash
+   just build-ui && SK_SERVER__MOQ_GATEWAY_URL=http://127.0.0.1:4545/moq SK_SERVER__ADDRESS=127.0.0.1:4545 just skit
+   ```
+
+2. **Run the tests** in a second terminal:
+
+   ```bash
+   just e2e-external http://localhost:4545
+   ```
+
+### Headless-browser pitfalls
+
+- Playwright runs headless Chromium with a default 1280×720 viewport.
+  Elements rendered below the fold are **not visible** to
+  `IntersectionObserver`. If a test relies on an element being observed
+  (e.g. the `<canvas>` used by the MoQ video renderer), scroll it into
+  view first:
+
+  ```ts
+  const canvas = page.locator('canvas');
+  await canvas.scrollIntoViewIfNeeded();
+  ```
+
+- The `@moq/watch` `Video.Renderer` enables the `Video.Decoder` (and
+  therefore the `video/data` MoQ subscription) **only** when the canvas is
+  intersecting. Forgetting to scroll will result in a permanently black
+  canvas.
+
+## Render performance profiling
+
+StreamKit ships a two-layer profiling infrastructure for detecting render
+regressions — particularly **cascade re-renders** where a slider interaction
+(opacity, rotation) triggers expensive re-renders in unrelated memoized
+components (`UnifiedLayerList`, `OpacityControl`, `RotationControl`, etc.).
+
+### When to use this
+
+- **After touching compositor hooks or components** (`useCompositorLayers`,
+  `CompositorNode`, or any `React.memo`'d sub-component): run the perf tests
+  to verify you haven't broken memoization barriers.
+- **When optimising render performance**: use the baseline comparison to
+  measure before/after render counts and durations.
+- **In CI**: Layer 1 tests run automatically via `just perf-ui` and will fail
+  if render counts regress beyond the 2σ threshold stored in the baseline.
+
+### Layer 1 — Component-level regression tests (Vitest)
+
+Fast, deterministic tests that measure hook/component render counts in
+happy-dom. No browser required.
+
+```bash
+just perf-ui          # runs all *.perf.test.* files
+```
+
+Key files:
+
+| File | Purpose |
+|------|---------|
+| `ui/src/test/perf/measure.ts` | `measureRenders()` (components) and `measureHookRenders()` (hooks) |
+| `ui/src/test/perf/compare.ts` | Baseline read/write, 2σ comparison, report formatting |
+| `ui/src/hooks/useCompositorLayers.render-perf.test.ts` | Cascade re-render regression tests |
+| `perf-baselines.json` (repo root) | Baseline snapshot — committed to track regressions over time |
+
+**Cascade detection pattern**: the render-perf tests simulate rapid slider
+drags (20 ticks of opacity/rotation) and assert that total render count stays
+within a budget (currently ≤ 30). If callback references become unstable
+(e.g. `layers` array in deps instead of `selectedLayerKind`), React.memo
+barriers break and the render count will blow past the budget, failing the
+test.
+
+### Layer 2 — Interaction-level profiling (Playwright + React.Profiler)
+
+Real-browser profiling for dev builds. Components wrapped with
+`React.Profiler` push metrics to `window.__PERF_DATA__` which Playwright
+tests can read via `page.evaluate()`.
+
+```bash
+just perf-e2e         # requires: just skit + just ui (dev server at :3045)
+```
+
+Key files:
+
+| File | Purpose |
+|------|---------|
+| `ui/src/perf/profiler.ts` | Dev-only `PerfProfiler` wrapper + `window.__PERF_DATA__` store |
+| `e2e/tests/perf-helpers.ts` | `capturePerfData()` / `resetPerfData()` Playwright utilities |
+| `e2e/tests/compositor-perf.spec.ts` | E2E test: creates PiP session, drags all sliders, asserts render budget |
+
+Use Layer 2 when you need real paint/layout timing or want to profile
+interactions end-to-end with actual browser rendering.
+
+### Updating the baseline
+
+Run `just perf-ui` — the last test in the render-perf suite writes a fresh
+`perf-baselines.json` (gated behind `UPDATE_PERF_BASELINE=1`, which the
+`test:perf` script sets automatically). Regular `just test-ui` runs compare
+against the baseline but never overwrite it. Commit the updated baseline
+alongside your changes so future runs compare against the new numbers.
+
 ## Docker notes
 
 - Official images are built from `Dockerfile` (CPU) and `Dockerfile.gpu` (GPU-tagged) via `.github/workflows/docker.yml`.