# vt/ - Scoped View Transitions, cross-browser project

Multi-engine tracking page for `Element.startViewTransition()` (CSS View
Transitions Module Level 2). Lives at
<https://static.januschka.com/vt/> and links out to one sampler per
engine. This file is the contract the three tower threads share so any
of them can refresh its sampler in isolation.

## Project layout

```
vt/
  index.html      # the overview page (3 cards + status table)
  AGENTS.md      # this file
  chromium/       # Chromium baseline sampler
    index.html    # dark-theme page, mirrors firefox/i-2075158 structure
    before-*.png  # captures from this folder's own build
    after-*.png   # same build, with any applied patch (empty for a pure baseline)
```

The Firefox and WebKit samplers stay where they are:

- `/firefox/i-2075158/` tracks Bugzilla 2075158 (Phabricator stack not uploaded yet)
- `/webkit/i-pr81741/` tracks GitHub PR 81741

`vt/index.html` just pulls their current scores and screenshots by link;
it does not duplicate their assets.

## Spec, suite, scope

- Spec: <https://drafts.csswg.org/css-view-transitions-2/>
- WPT suite: `css/css-view-transitions/scoped` (93 tests at the time of
  writing; always re-check with `wpt run` locally).
- All three samplers run against the SAME suite so the scores are
  directly comparable. If the suite grows, bump the denominator on every
  card in `vt/index.html` in the same commit.

The feature in one line: `element.startViewTransition(update)` snapshots
the given element's subtree, lets `update` mutate the DOM, then
cross-fades between old and new snapshots. `view-transition-name` on
nested elements resolves per scope, and several scopes can animate in
parallel.

## Nested-clip video pair (shown on vt/index.html)

In addition to the four static cases below, every engine produces a
**before/after video pair of the nested-clip demo**. This is the clip
that `vt/index.html` embeds under "Nested clip demo, per engine", so
the overview page can show real motion side-by-side across all three
engines.

- source demo (Firefox): `/firefox/i-2075158/nested-clip.html` - copy
  or port it when adding a new engine; the scenario is: a scope with a
  visible clip region, an ancestor with `overflow: hidden`, the scope
  element morphs/flies to a position outside its own clip but inside the
  ancestor's
- file names expected by `vt/index.html`:
  - Firefox: `/firefox/i-2075158/vtg-clip-before.{webm,mp4}` and
    `vtg-clip-after.{webm,mp4}` (~10 s each)
  - WebKit: `/webkit/i-pr81741/before2.{webm,mp4}` and
    `after2.{webm,mp4}` (~1.5 s each; longer is fine)
  - Chromium: `/vt/chromium/nested-clip-before.{webm,mp4}` and
    `nested-clip-after.{webm,mp4}`
- encode both `webm` (VP9) and `mp4` (H.264); Safari needs the mp4
- same viewport/crop before and after; `autoplay loop muted playsinline`
  is already in the markup, so keep clips short (under ~12 s) and
  seamless

When an engine's path or filename changes, update the `<source>` tags
in `vt/index.html` in the same commit - this is the main reason the
overview page exists and it must not rot.

## Four canonical scenarios

Every engine's sampler must have these four `.case` blocks, in this
order, with these ids (so Rendered / Before / After images line up):

1. `case-list` - reorder a 3-item list with
   `view-transition-name` per row
2. `case-image` - swap two `<img>` sources inside a scoped element
3. `case-nested` - a scoped element that itself contains named
   descendants (checks per-scope name resolution)
4. `case-clip` - transition inside a `clip-path`/`overflow: hidden`
   region to show scope isolation

Each case has three tabs: `Rendered` (live HTML the reader runs),
`Before` (PNG from unpatched/baseline build), `After` (PNG from the same
build with the patch; for Chromium baseline, `Before` and `After` are
identical).

## Updating an engine's sampler

From the matching tower thread, the prompt pattern is:

> read `~/my-host/static-files/vt/AGENTS.md` and refresh the <engine>
> sampler with current state

The thread then:

1. Rebuilds the engine at the tip of its tracked branch/PR.
2. Runs the scoped WPT suite, records `passed/total`.
3. Recaptures `before-*.png` (unpatched) and `after-*.png` (with patch)
   for the four canonical cases, using identical viewport/crop.
4. Recaptures the **nested-clip video pair** at the paths listed above
   (webm + mp4), same viewport before and after.
5. Edits its own sampler `index.html`:
   - header meta line: revision/commit, suite score, date
   - the stat cards near the top
   - replaces only the PNGs/videos that actually changed
6. Updates `/vt/index.html` in the same commit:
   - the engine's stat card `.num` (`NN/93`)
   - the engine's row in the "Status table" (score + Updated YYYY-MM)
   - the `<source>` paths under "Nested clip demo, per engine" if any
     filename or folder moved
7. Rsyncs/commits according to the normal static-files flow (never
   `git add -a`; add changed files explicitly).

Do not touch another engine's sampler from this prompt. Each thread
only owns its own folder and its own row in `vt/index.html`.

## Capture conventions (so the three engines look like one project)

- Viewport: 800x600, DSF 1
- Crop: each case captured at its natural size, cropped identically with
  `magick shot.png -crop WxH+0+0 +repage case.png`
- Filenames: `before-<case-id>.png`, `after-<case-id>.png`
- Dark theme from `../AGENTS.md`; do not invent a per-page palette

Per-engine capture details (headless flag, screenshot tool) live in
`/firefox/AGENTS.md`, `/webkit/AGENTS.md`, and `/AGENTS.md` (Chromium
`--screenshot`). Those files are the source of truth for each engine's
mechanics; this file is only the cross-engine contract.

## The Chromium sampler

Chromium already ships `document.startViewTransition()` and is actively
implementing `Element.startViewTransition()`; the baseline here is
"whatever main currently does". There is no patch to toggle, so:

- `before-*.png` = `chromium/src@main` content_shell captures
- `after-*.png` = copies of the before captures (keep the three-tab
  layout working); re-shoot both when a shipping CL lands

When a real Chromium CL for scoped VT is being tracked, swap this
folder to a proper `i-<issueid>/` sampler under the top-level
`static-files/` and keep `vt/index.html` pointing at it.

## Score bookkeeping

The number shown on each card in `vt/index.html` is
`passed_scoped_tests / 93`. If you bump the Firefox card, also check the
WebKit one and vice versa - the Firefox page used to say WebKit was at
83/93 while WebKit itself was at 87/93; drift like that is what this
overview page exists to kill.

## Do NOT

- Change another engine's sampler from the wrong thread.
- Edit the suite denominator in only one place.
- Inline a logo; use `/firefox/firefox-logo.png`,
  `/webkit/webkit-logo.png`, and the Wikimedia Chromium logo already
  referenced in `vt/index.html`.
- `git add -a`; add only the files you actually changed.
