# Architecture

How StreamXR is built today, for people and AI agents changing the code. Read this before
changing structure. The *why* behind the big decisions is in
[docs/decisions/](docs/decisions/), what changed when is in [CHANGELOG.md](CHANGELOG.md),
and the code rules are in [CONTRIBUTING.md](CONTRIBUTING.md). What's been learned about
YouTube and the hardware, the interface's design choices and the open questions are in
[docs/](docs/) (youtube.md, hardware.md, design-choices.md, known-issues.md).

StreamXR is a Manifest V3 browser extension that plays a website's own `<video>` in a
SteamVR headset through WebXR: 360° and VR180 videos as a sphere around you, regular videos
on a cinema screen, with a floating control panel worked by laser pointers. It has no
build step and one vendored library (Google's Material Color Utilities, `third_party/`, for
the Material 3 palettes): the repo folder is the extension.

## Three layers

1. **Shell** (site-agnostic), in two parts. It never names a site and never reads a page;
   it only knows the provider interface.
   - **Core** (`src/core/`): the VR interface any VR browser feature could use, and the
     future core of BrowseXR ([docs/Future-Plans.md](docs/Future-Plans.md)): controllers
     and input, the lasers, the controls panel, the layout with its toolbars, and the five panel styles,
     the keyboard, the Laser / Keyboard / Language settings, translations, storage, the
     site registry.
   - **StreamXR** (`src/streamxr/`): the video player built on the core: the WebXR session
     and its frame loop, the media source, rendering (video sphere, cinema screen, pause
     overlay), the video formats, the 2D Cinema settings, the "Watch in VR" popup, and the
     page-world entry point.
2. **Provider** (`src/sites/<site>/page/provider/`, one per site): the middle layer. It
   answers the shell's questions ("what's playing?", "fill this panel", "this was clicked")
   by calling the site files, and turns site data into the shell's generic shapes (cards,
   tabs, pills, text, rows, "now playing").
3. **Site files** (`src/sites/<site>/page/`, e.g. `youtube-*.js`): the only code that reads,
   clicks or requests anything from the site. They expose what the site offers and don't
   know the shell exists.

**The rule:** features flow shell ← provider ← site. A shell file never gets a
site-specific field or check; when a site needs something new, add a generic option (a
model field, a card flag, a slot, a provider hook) and let the provider fill it.

Supported sites: **YouTube** (`src/sites/youtube/`).

## Two JavaScript worlds

A content script runs in one of two worlds on the site's page, which can only talk through
DOM events carrying JSON strings (`src/core/shared/bridge.js`):

- **Page world** (`"world": "MAIN"`; `src/core/page/`, `src/streamxr/page/`,
  `src/sites/<site>/page/`): the site's own context. WebXR sees the headset here and the
  site's player lives here. All VR rendering happens here.
- **Isolated world** (`src/streamxr/ui/`, `src/sites/<site>/ui/`): the extension's sandbox. The
  page button and the popup live here, because a site's Trusted Types policy (YouTube's)
  blocks `innerHTML` in the page world.

There are no ES modules (content scripts can't be modules). Every file is
`(function (ns) { ... })(globalThis.__streamxr = globalThis.__streamxr || {});` and adds
one piece to that namespace (each world has its own copy); `manifest.json` loads the files
in dependency order. The manifest has **one pair of `content_scripts` entries per site**
(page world + isolated world), matched to the site's host, listing the core's files first,
then StreamXR's, then the site's (and StreamXR's `main.js` last). Chrome keeps sites apart
by page, so supporting another site needs no build step.

**Shared files:** Chrome runs a given script file at most once per page even when two
entries list it, so the isolated world can't load the `shared/` folders (`src/core/shared/`,
`src/streamxr/shared/`). It loads generated copies in each one's `ui/shared/`; after
editing a `shared/` folder, run `node tools/sync-shared.js` (it also checks the manifest for
that mistake).

## Folder map

```
manifest.json                  load order for both worlds, one pair of entries per site; the icons (icons/), also
                               as the toolbar `action` (no popup: it only gives a pinned icon and its tooltip)
src/core/                      THE CORE (shell, part 1): the VR interface, site-agnostic
  shared/                      used by BOTH worlds (page loads these; ui loads copies)
    bridge.js                  event names + send/on/ask helpers (JSON-string payloads)
    i18n.js                    translations: t(key) in the interface language (or the browser's)
    strings-en.js              the core's words in English (strings-<lang>.js: other languages)
    controls.js                what each controller input does (single source of truth)
  ui/shared/                   GENERATED copies of core/shared/ (tools/sync-shared.js)
  page/                        page world
    math3d.js                  mat4 / vector helpers, head yaw
    pose-smoother.js           steadies the laser's pose against hand tremor (One Euro filter)
    gl-utils.js                shader programs, VAOs, buffers, textures
    storage.js                 remembered settings (streamxr.* in localStorage)
    sites.js                   the site registry: each site registers its provider; current()
    frame-clock.js             waits that keep time in VR (ticked by the frame loop)
    diagnostics.js             WebXR checks + headset clues + controller reports (Details)
    input.js                   controller state -> actions, via controls.js
    controllers/
      config.js                fit offsets, colours, button->part map, icon placement  <- tune here
      icons.js                 icon artwork: Material Symbols on M3E tonal buttons, in the colour theme (canvas 2D)
      models.js                GENERATED controller meshes (tools/controller-models/)
      model-pass.js            draws the meshes
      icon-pass.js             draws the floating icons
      controllers.js           per-hand pose, press highlights, stick tilt; runs both passes
    vr-panel/
      config.js                layout distance and text size, panel sizes, auto-hide, laser look  <- tune here
      tokens.js                design tokens: colours by Material 3 role, the site's theme, glass
      glyphs.js                the M3E loading indicator (`spinner`), textMiddle
      symbols.js               Material Symbols icons (Rounded; outlined + filled) as Path2D outlines
      panel-ui.js              the controls panel: layout, drawing, hit testing
      styles/                  the chevron panels' five styles + shared pieces
        kit.js                 generic card, images, badge registry, the M3 tabs (drawTabs, headerTabs), the M3 button, the hover ring, regionAt (hit tests; small controls reach out to 56 dp), createStrip (a row that slides sideways when the laser nears its end)
        grid.js                tabs, pills, text field, card grid, paging (Catalog + Profile)
        thread.js              a threaded comment list (Info's Comments, Profile's opened post)
        chat.js                a live chat list (Info's 'chat' content): rows with inline pictures, cards, a pinned banner
        info.js / catalog.js / queue.js / profile.js / options.js
      orbiters-ui.js           the side toolbars (upright M3E floating toolbars on the Safe Zone line), the pill (Settings) and the search bar; a side toolbar has a grab bar on its video side (moves its whole side)
      popups-ui.js             the controls panel's floating menus and the dialog (raised in front: Android XR's popup and dialog levels)
      motion.js                hover / press easing (M3E springs): one tracker per panel canvas; the opening springs (panels without bounce)
      laser-options.js         the Laser settings tab: steadiness (the shell's own)
      appearance-options.js    the Appearance settings tab: the colour theme, the glass look on / off and its tint, the panel size, vibration on / off (the shell's own)
      fade-options.js          the Auto-hide settings tab: how long the controls panel, toolbars, search bar, controllers and lasers wait before hiding / fading, and the "Auto-hide while paused" switch
      safe-zone.js             the Safe Zone: where the layout goes, as shares of the headset's field of view (measured from the eyes' projections); its outline
      safe-zone-options.js     the Safe zone settings tab: width, height, centre (the shell's own)
      keyboard-options.js      the Keyboard settings tab: style and language (or yours), and the layout keyboard.js draws
      language-options.js      the Language settings tab: the interface language (or the browser's)
      hover-card-ui.js         floating card (Previous / Next hover in a list)
      keyboard.js              the in-VR keyboard: keys (layout from keyboard-options.js), Shift, symbols, grab bar
      panel-pass.js            draws a panel in the world; the glass: the video behind it, blurred (from the renderer's backdrop())
      laser-pass.js            draws laser beams + hit dot
      vr-panel.js              the layout around the Safe Zone, laser hits, clicks, scrubbing, auto-hide; builds the
                               panels, toolbars and pill from the site's registry
src/streamxr/                  STREAMXR (shell, part 2): the video player on the core
  shared/                      used by BOTH worlds
    strings-en.js              StreamXR's words in English: formats, popup, starting VR, 2D Cinema
    formats.js                 the video formats (names, projection); detection is the provider's
  ui/shared/                   GENERATED copies of streamxr/shared/ (tools/sync-shared.js)
  page/                        page world
    media-source.js            where the frames come from: the site's <video>, followed when swapped
    video-sphere.js            the video sphere renderer (360°, 180°, cubemap)
    cinema-screen.js           flat/curved screen for regular videos (rounded corners, the edge-colour glow); picks sphere vs screen per format
    cinema-options.js          the 2D Cinema settings tab
    pause-overlay.js           dims the video, pause symbol, buffering loading indicator
    captions-overlay.js        the site's caption lines drawn in VR (over the 2D screen's bottom, or below your view)
    xr-session.js              one VR session: setup + per-frame loop (takes a provider)
    main.js                    page-world entry: picks the site's provider (sites.js), answers the popup
  ui/                          isolated world
    goggles-icon.js            the VR headset icon (Material Symbols' Head Mounted Device) for the VR buttons and popup
    panel.js                   "Watch in VR" popup (format picker, Enter VR, help, Details)
    popup.css                  its styles (Material 3; colours from the site's palette, asked of the page world)
src/sites/youtube/             YOUTUBE
  page/
    youtube-data.js            plumbing: text helpers, watch-page data, /youtubei/v1 requests,
                               video/playlist item readers
    youtube-player.js          the #movie_player API: playback, quality, speed, volume, captions,
                               audio tracks, loop/autoplay, playlist, live, storyboards, ads
    youtube-page.js            the watch page: Up Next, details, Subscribe/Like/Dislike, navigation
    youtube-content.js         metadata, description, chapters, heatmap, end screen, cards,
                               playlist, comments, transcript, search
    youtube-channel.js         any channel by id: header, tabs (sortable), playlists, shows ...
    youtube-home.js            Home feed + topic chips, Explore feeds, menu, search suggestions
    youtube-subscriptions.js   Subscriptions feed, Manage list, Subscribe/Unsubscribe, the bell
    youtube-chat.js            a live stream's chat: its views, the chat page, polling, items -> plain messages
    provider/
      provider.js              the provider (interface at its top); registers YouTube in sites.js
      panels.js                the panel registry (each panel's zone, style, size, controller)
      extras.js                the controls panel's Captions and Save buttons and Jump ahead at the seek bar's end (the shell's "extras": left, right, seek), premiumMark() (the Diamond)
      strings-en.js            the YouTube panels' words in English (strings-<lang>.js: other languages)
      cards.js, badges.js      YouTube items -> generic cards; the ✓ / ♪ badges
      upnext.js, browse.js (Explore and You), search.js, channel.js, description.js, comments-panel.js, settings.js, live-chat.js
                               one controller per panel (comments.js: the comment threads, used by
                               the Comments panel and a Channel post)
  ui/
    site.js                    the site's name and brand colour for the popup (until the palette arrives)
    player-button.js, button.css   the VR button in YouTube's player controls
    topbar-button.js           the VR button in YouTube's top bar (next to "+ Create"), on every page
    skip-helper.js             talks to the optional Skip Helper extension
    main.js                    isolated-world entry: keeps the button in the page
icons/                         the extension's icons, 16-128 px (tools/icons/make-icons.html)
skip-helper/                   SEPARATE optional extension: presses YouTube's Skip ad button
third_party/material-symbols/  the Material Symbols license (Apache 2.0), for symbols.js
third_party/material-color-utilities/   Google's Material Color Utilities (Apache 2.0), wrapped as a plain
                               script (ns.materialColor): makes the Material 3 palettes (tokens.js)
tools/sync-shared.js           shared/ -> ui/shared/ copies (core and streamxr), manifest checks
tools/icons/make-icons.html    draws the extension icons (icons/, skip-helper/icons/) from Material Symbols
tools/controller-models/       dev-only: rebuilds models.js from Valve's CAD (see README)
docs/
  youtube.md                   the YouTube modules + what's been learned about YouTube
  hardware.md                  the Steam Frame and its controllers in Chrome
  design-choices.md            how the interface is meant to look and behave
  known-issues.md              unverified, quirky, tried and dropped
  Future-Plans.md              BrowseXR prep: what's done, what's left, what it would break
  Materials-Redesign.md        the planned Material Design 3 + glass redesign
  features/                    backlogs: what YouTube offers that VR doesn't use yet
  decisions/                   why the big decisions were made
```

## A VR session

1. The site's page button (isolated world) opens the popup (`src/streamxr/ui/panel.js`). It asks
   the page world over the bridge for the video info, the provider's detected format, the
   site's Material 3 palette (its colours) and
   the WebXR diagnostics, and shows a format picker, the passthrough switch (greyed out
   unless the browser offers `immersive-ar`) and **Enter VR**.
2. **Enter VR** sends `ENTER` inside the click (WebXR needs the user gesture). StreamXR's
   `main.js` takes the provider of the site this page belongs to (`ns.sites.current()`,
   registered by the site's `provider.js`) and calls `xrSession.start(provider, fmt, listener)`.
3. `xr-session.js` asks for an `immersive-ar` session if passthrough was chosen and is
   offered (else `immersive-vr`; a see-through session clears to transparent), applies the
   provider's theme, opens `provider.session()`, builds the
   video view (`video-sphere.js` or `cinema-screen.js` by format), the pause overlay, the
   controller models and the VR panel, then runs the frame loop:
   - follow the media source (`media-source.js`: the site's `<video>`, which can be swapped
     when another video opens) and upload a frame only when there is a new one;
   - poll the controllers (`input.js` with the bindings in `controls.js`);
   - ads (if the provider has `ad()`): show them on the cinema screen, then switch back and
     re-detect the format;
   - recenter when asked; re-detect the format after `provider.onNavigate`;
   - `panel.update(...)`, then draw: video, pause overlay (paused / `provider.buffering()`),
     panels, controller models, lasers.
4. The panel's `actions` are the provider session's plus the shell's own (recenter, exit,
   setFormat, setDistance, setCurve); its `state()` is the session's plus the format and the
   cinema screen settings (`viewSettings`).

The stick: left/right is ±10 s, but while the laser is on a panel with page arrows it turns
pages (`panel.stickPage`), and on a scrolling area up/down scrolls (`panel.stickScrolls`);
the controller icon changes to match (`panel.iconSwaps`).

## The provider

The interface is written at the top of `src/sites/youtube/page/provider/provider.js`, which
is the source of truth. In short:

- **Site level:** `name`, `theme` (`{ accent, accentPressed, dark }`), `themes` (optional:
  `[{ id, label, theme }]`, the colour themes offered in Settings → Appearance, the first the
  default; `appearance-options.js` applies the chosen one), `video()`, `info()`,
  `detectFormat(info?)` -> `{ fmt, isSpatial }`, `isPaused()`, `toggle()`, `seek(s)`,
  `buffering()`, `onNavigate(fn)` -> `stop()`, `session()`.
- **A session:**
  - `actions`: those the shell calls (`toggle`, `seekBy`, `seekTo`, `goLive`, `setQuality`,
    `setSpeed`, `setVolume`, `setMuted`, `storyboard`, `skipAd`, `previousVideo`,
    `nextVideo`), plus whatever the site's own panel controllers use.
  - `state()`, polled every frame: `title`, `nowPlaying`, `time`, `duration`, `live`,
    `paused`, `quality` (`{ current, currentLabel, levels: [{ id, label }] }`), `speed`,
    `speeds`, `volume`, `chapters`, `ad`, plus what the site's panels read.
  - `ad()` (optional): the ad playing now, or null.
  - `site`: `{ name, panels (the registry), onControl(id, panel) }`.
- Optional features simply aren't provided: ads, live streams, the storyboard preview,
  chapters, a queue, action buttons. Quality, speed and volume are not optional yet (the
  controls panel always shows those buttons).

**`nowPlaying`** is what the controls panel draws under the title (`panel-ui.js` documents
it): `info` (coloured pieces on one line, e.g. views · date, then the playlist),
`creator` (`{ name, badge, stats }`, a button with id `creator`), `actions` (right-aligned
buttons: `pill`s with a look and label, or thumbs `icon`s with a count; ids `action:<id>`;
a `hidden` one keeps its place), and `queue` (Previous / Next with their hover cards).
Controls the shell doesn't handle itself (`title`, `creator`, `action:<id>`) go to
`site.onControl(id, panel)`, where `panel(id)` gives a chevron panel's controller.

## Cardinal Direction panels

The site's panels are laid out around the **Safe Zone** (`safe-zone.js`; the part of your
view the video keeps; docs/Spatial-Layout.md), each in a **zone** its registration names:
`left` and `right` (outside the zone's side edges, one open per side, remembered; each side
has an upright toolbar, `orbiters-ui.js`, standing on the zone's line over the panel's
inner edge, its names growing outward), or `controls` (a popup rising from a pill on the
controls panel's top edge, e.g. Settings), or `top` (a search bar above the zone, its
suggestions dropping into it, and the panel in the zone's middle while its controller's
`model()` says `open`; it also returns the bar's field as `bar`). The controls panel sits
under the zone; a panel asking for keys (`typeInto`) brings up the in-VR keyboard. Each
panel is a **style** (how it looks) filled by a site's **controller** (what it shows).

### The registry

A site lists its panels (YouTube: `provider/panels.js`, which documents the interfaces):

```js
{ id, zone: 'left' | 'right' | 'controls' | 'top',
  label, icon,                            // icon: a Material Symbols name (symbols.js)
  style: 'info' | 'catalog' | 'queue' | 'profile' | 'options',
  size: 'wide' | 'tall' | 'standard',     // vr-panel/config.js `sizes`
  overrides: { slots: { ... } },          // optional: the style's slots
  default: true,                          // optional: open the first time (on its side)
  available: st => bool,                  // optional (side panels): offered only while true
                                          //   (asked every frame; its toolbar button hides meanwhile)
  autoOpen: true,                         // optional: opens whenever it becomes available (not
                                          //   remembered); the panel it replaced comes back after
  stays: true,                            // optional: doesn't fade with the rest while you watch
  create(host) -> controller }
```

YouTube's Live chat uses all three (`available` while a live stream with a chat plays):
`vr-panel.js` `refreshAvailable` hides its toolbar button (`orbiters-ui.js` `setHidden`, the
bar shrinking and laid out again) and keeps a `stays` panel drawn and updated while the panels
are hidden.

- `host`: `{ actions, style, perPage, open(), close(), isOpen(), closeMenu(), openMenu(control), panel(id), confirm(d), typeInto(on, opts) }`
  (`opts.emojis`: the panel's own emojis, `[{ text, image, label }]`, first on the keyboard's emoji pages);
  `confirm(d)` asks in the shell's dialog (`{ title, text (up to four lines), confirm, cancel
  (null: no cancel button, a dialog that only informs), danger }` -> a Promise
  of true / false); the site's `onControl(id, panel, shell)` gets the same as `shell.confirm`.
- Menus on side panels: `host.openMenu(control)` (e.g. `'action:bell'`) opens a floating menu
  above that control, 32 dp in front, like the controls panel's (the style needs `rectOf(id)`;
  Profile has it). While it's up, `vr-panel.js` asks the controller's `menu(control)` each frame
  (`{ items: [{ id, text, on, disabled, icons }], note, stay }`, `null` closes it); a choice
  arrives as `{ type: 'menu', value: item id, menu: control }`. The menu's id is
  `'p:<panel>|<control>'` and its items `'pi:<index>'` (`panelMenu`). `host.panel(id)` is another
  panel's controller (the You panel opens a channel in the Channel panel with it).
- Typing: a panel with a text field calls `host.typeInto(true)` to get the keys (and
  `false` to give them back). One panel types at a time: when another asks, the one that had
  the keys is sent `Escape` (as for a click on nothing) and should stop typing. While it's shown, each key reaches its controller as
  `{ type: 'key', value }`: a character (or an emoji, or a panel emoji's `text`, from the
  keyboard's 😀 pages), `Backspace`, `Enter` or `Escape`. The keys come
  from the in-VR keyboard (`vr-panel/keyboard.js`; the `keyboard` binding swaps it with
  the controls panel in `vr-panel.js`: it hangs from the controls panel's top edge, sharing
  its pose) and from the computer's
  keyboard (kept from the page meanwhile, so YouTube's shortcuts don't fire).
- `controller`: `model(frame)` -> `{ model, key }` (while shown; redrawn only when `key`,
  the hover or the loaded images change), `event(ev)`, and optionally `tick(frame)` (every
  frame), `afterDraw()`, `opened()`, plus anything the site's `onControl` calls.
- Sizes (canvas px, `config.js` `sizes`): `wide` panels all take the height a Catalog trims
  itself to (900 px wide), `tall` is 900 x 1100, `standard` is the controls panel's width
  (1024). Every canvas is shown at the same density (`config.js` `layout.pxPerDegree`, at
  `layout.distance`).

`vr-panel.js` builds everything from the registry: the layout, the toolbars and the pill, hit testing, events,
stick paging and scrolling, slider dragging, redraw keys and image loading. A panel
control's id there is `<panel id>|<style id>`.

### The five styles

| Style | YouTube panel | Draws |
|---|---|---|
| **Info** (`info.js`) | Description, Comments, Live chat | header tabs; each tab one content kind: `text` (rich text, links), `paged` (rows in two columns: chapters), `rows` (scrolling, current row followed: transcript), `thread` (pills, count, rows with children and "show more": comments), `chat` (chat.js: a pinned banner, messages with inline pictures and coloured cards, following the newest or paused with a "jump to newest" button; optionally a message field with Send, reaction buttons and a Support button, an XP pill and a ranked Top fans list: live chat), `message` (optional loading indicator) |
| **Catalog** (`catalog.js`) | Explore, You, Search | title, source tabs, filter pills (tabs and left-aligned pills slide when they don't fit: kit.js createStrip) or a note or a text field with its button (and a suggestions list dropping down from it), card grid, paging; trims its height to its cards |
| **Queue** (`queue.js`) | Up Next | title or tabs, paging in the header, 3 x 2 cards, a "current" card |
| **Profile** (`profile.js`) | Channel | banner, picture, name + badge, stats line, one action button (looks: primary / secondary / danger / busy) and an optional round icon button beside it (the bell), tabs (shrinking to fit beside the pills), pills, a search button (searching: a back button and a text field in place of the tabs), card grid, paging, or one featured card, or a scrolling body: a text `page` (paragraphs, then label / value facts), a `feed` of posts (picture, author, text, pictures, a card, a poll with result bars, buttons with icons and counts), or one opened `post` with a back button and its comments (thread.js) |
| **Options** (`options.js`) | Settings | tabs (with icons); up to 3 rows (name with its hint under it; at the right: a switch, a slider with a Default button and end captions, a ‹ value › stepper, or a button; faded) or a 4 x 4 choice grid with "More" paging |

Each style file's header lists its model and control ids. Every style returns
`{ canvas, aspect, draw(model, ui), hitTest(u, v), has(id), imagesReady(), perPage }`;
Info and Profile add `scrollAt`, `maxScroll`, `shownScroll`, `pxPerV`, Options adds `sliderFraction`.

**Standard events:** a style's control ids are `<type>:<value>` and reach the controller
as `{ type, value, fraction? }`. Types: `tab`, `pill`, `item`, `page`, `action`,
`featured`, `post`, `vote`, `back`, `link`, `row`, `time`, `children`, `more`, `newest`, `react`, `send`, `support`, `fans`, `fansBack`, `switch`, `slider`, `default`,
`choice`, `prev`, `next`, `button`, `field`, `clear`, `submit`, `suggest`, plus `scroll` (from dragging or the stick), `key` (typing), a slot's own ids, and the names a provider gives a post's buttons (YouTube: `postlike`, `postdislike`, `postcomments`).

**The generic card** (`kit.js`), used by every card grid and the hover card:
`{ title, thumb, corner, flags: [{ text, bg, fg, dot, matchWidth }], lines: [{ text, badge }], current, progress, fit, inert }`.
The provider turns site items into cards (YouTube: `provider/cards.js`, with its 2D / 180° /
360°, LIVE, Mix, Playlist, Short and "Now playing" flags).

**Badges** are a registry: `kit.registerBadge(name, draw, extra)`; YouTube registers ✓
(verified) and ♪ (artist).

### Extending a style

A site changes a style only through **slots** the style declares, passed as
`overrides.slots` in the registration; the style keeps control of layout, hit testing,
scrolling and redraws. Today there is one slot: Info's `threadFooter` (YouTube draws its
comment rows' 👍 / 👎 / ❤ footer with it, `provider/comments.js`). Two guardrails:

1. **Data before overrides.** Anything that can be said as data (a line, a flag, a label, a
   colour) is a model field the provider fills; a slot is only for genuinely different
   drawing.
2. **One level only.** A site customises the shell's style, never another site's. If two
   sites want the same thing, it becomes an option of the style.

When a site needs a new slot, add it to the style (with a default that draws today's look)
and document it in the style's header.

## Theme, storage, the popup

- **Design tokens** (`vr-panel/tokens.js`, `ns.vrTokens`): every colour the panels draw is a
  Material 3 colour role, `color.<role>` (`primary`, `surface`, `onSurface`,
  `onSurfaceVariant`, `outline`, `tertiary` ...; today's in-between greys as neutral tones
  `n90` ... `n13`), or `alpha(role, a)` for translucent layers. Drawing files import them as
  `TC` / `TA` and read them while drawing (never at load), and never write a colour
  themselves. A provider's `theme` (`{ accent, accentPressed, dark, custom }`) is applied
  when VR starts (`apply`); `custom` adds the site's own roles (YouTube's card flags).
  Card flags give colours as role specs (`'surface/0.75'`), drawn through `resolve`.
  `m3` is the Material 3 palette (every M3 role, dark scheme), made when VR starts from the
  provider's `theme.seed` by Material Color Utilities (`scheme(seed, variant)`, ~0.4 ms;
  the theme also picks the variant, `scheme`, and role pairs to `swap`), else M3's
  baseline, plus our roles `brand` / `onBrand` (the site's exact accent) and `hoverRing`.
  Restyled components (so far the controls panel, `panel-ui.js`) draw from `m3` (`P`,
  `PA(role, a)`), with M3 type roles (`font(role)`) and corner sizes (`shape`); `glass`
  holds the planned glass look's settings (tint 0.62). See
  [docs/Materials-Redesign.md](docs/Materials-Redesign.md).
- **Storage** (`storage.js`, `ns.storage`): remembered settings in the site's localStorage
  under `streamxr.*` (values saved under the older names, `streamvr.*` and `ytvr.*`, move
  over when first read).
- **Site registry** (`core/page/sites.js`, `ns.sites`): each site's `provider.js` calls
  `ns.sites.register({ id, name, hosts, provider })`; StreamXR's `main.js` asks
  `ns.sites.current()` for the page it runs on. Page world only (the isolated world's site
  files are listed per site in the manifest).
- **The popup** (`src/streamxr/ui/panel.js`) gets the site's name and dark colour from
  `src/sites/<site>/ui/site.js` (`ns.site`).
- **Words** (`core/shared/i18n.js`, `ns.i18n`): nothing shown to the user is written in the
  code; it's `ns.i18n.t('key', { vars })`, looked up in string tables, one per part: the
  core's (`src/core/shared/strings-<lang>.js`), StreamXR's (`src/streamxr/shared/
  strings-<lang>.js`; both in both worlds: the popup uses them), and each site's
  (`src/sites/<site>/page/provider/strings-<lang>.js`, keys starting with the site, e.g.
  `yt.`). English (`-en`) is complete; another language may leave keys out (they show in
  English: language, then its base, then English). A text can have plural forms
  (`{ one, other, ... }`, picked by `vars.n`). The language is the browser's unless one is
  chosen in Settings → Language (`localStorage` `streamxr.language`, read by both worlds;
  the global reset clears it). Text is asked for at draw time, never kept in constants built
  at load, so a language change shows at once; `ns.i18n.version()` is in every redraw key.
  A registry `label` can be a function for the same reason. What the site writes itself
  (titles, view counts, its filter chips) isn't translated, and readers that match the
  site's own words (e.g. YouTube's "All" chip, "Joined") keep matching them as they are.
  Adding a language: CONTRIBUTING.md, "Translating".

## Where to make common changes

- **YouTube changed its page or data:** the `youtube-*.js` file that reads it.
- **A new YouTube feature in a panel:** the panel's controller in `provider/`; if the style
  can't show it yet, add a generic option to the style first.
- **A new chevron panel:** a controller + a registry entry in `provider/panels.js`, built on
  one of the five styles.
- **New controller action:** a binding in `src/core/shared/controls.js`, its handler in
  `xr-session.js` (the input handler), optionally an icon (Material Symbols names) in `controllers/icons.js`
  and a placement in `controllers/config.js`. The help line updates itself. A binding with
  `hold: seconds` fires once after that long held (input.js `holds()` feeds the countdown
  ring drawn over its part's icon).
- **A new adjustable setting:** give its module a `reset()` and call it from `resetAll` in
  `xr-session.js` (the global reset), and forget its stored value with `ns.storage.remove`.
- **A colour on a panel:** a role from `vr-panel/tokens.js` (`TC.<role>`, `TA(role, a)`),
  never a literal; a missing role goes into tokens.js under its M3 name.
- **New words on screen:** a key in the English table of the part that draws it
  (`src/core/shared/strings-en.js`, `src/streamxr/shared/strings-en.js`, or the site's
  `provider/strings-en.js`) and `ns.i18n.t(key)` where it's drawn. Never a literal in the code.
- **New video format:** `src/streamxr/shared/formats.js` (label, projection), the renderer in
  `video-sphere.js` or `cinema-screen.js`, detection in each provider's `detectFormat`.
- **Tuning numbers:** `vr-panel/config.js`, `controllers/config.js`, `SETTINGS` in
  `cinema-screen.js` and `pause-overlay.js`.
- **Another headset:** see the README's "Adding a headset".

## Adding a site

1. Check the site's video can be drawn at all (see "Known limits": DRM).
2. `src/sites/<site>/page/`: the site files, and a `provider/` with `provider.js` (the
   interface above, ending with `ns.sites.register({ id, name, hosts, provider })`), its
   panels (`panels.js` + one controller each, on the five styles) and its string tables.
3. `src/sites/<site>/ui/`: `site.js` (name, colours), the page button and its CSS, and
   `main.js` (keeps the button in the page).
4. `manifest.json`: the host in `host_permissions`, and a pair of `content_scripts` entries
   for it (copy YouTube's pair: core files, then StreamXR's, then the site's, then
   `src/streamxr/page/main.js` last).
5. Never change the shell for one site: add a generic option, slot or provider hook.

## Gotchas

- In VR, don't wait with `setTimeout`: while you're in the headset Chrome can treat the
  page as hidden and run its timers late (about once a second, after five minutes once a
  minute). Search suggestions waited on a 150 ms timer and never showed in the headset
  (0.44.0). Use `ns.frameClock.sleep(ms)` / `after(ms, fn)` (`frame-clock.js`, ticked by
  the VR frame loop; also what `youtubeData.sleep` uses), or a controller's `tick(frame)`.
- Chrome injects a given script file only once per page across `content_scripts` entries:
  hence the generated `ui/shared/` copies (core's and StreamXR's) for the isolated world.
- Shader uniforms shared between a vertex and a fragment shader must use the same precision,
  or the program fails to link.
- When blending overlays, keep the destination alpha intact:
  `blendFuncSeparate(..., ZERO, ONE)`.
- Images drawn on panel canvases must load with `crossOrigin='anonymous'` (and the server
  must allow it), or the canvas can no longer be uploaded as a WebGL texture.
- WebXR's `requestSession` must be called inside the user's click (the popup sends `ENTER`
  synchronously from its click handler).
- Each panel is redrawn only when its controller's key, the hover or the loaded images
  change: anything a panel shows must be in its key, or the panel won't update.
- Site-specific gotchas (YouTube's data, player and ads) are in [docs/youtube.md](docs/youtube.md).

## Known limits

- **DRM.** Netflix, HBO Max, Disney+ and most paid services protect video with Widevine.
  Chrome won't copy protected frames into WebGL (black or an error), and every video is
  drawn through WebGL, so those services can't be supported unless that changes.
- WebXR needs the page's permissions policy to allow `xr-spatial-tracking`; a site can
  block it (`diagnostics.js` reports it).
- Sites' player APIs are private and change; a provider may have to click the site's own
  buttons (as `youtube-page.js` does). YouTube's text matching assumes English.
- Desktop Firefox has no WebXR, so the VR part can't run there yet; browser-specific code
  is kept to `src/sites/youtube/ui/skip-helper.js` and `skip-helper/`.
- There are no automated tests in the repo. The maintainer tests in a headset; refactors of
  drawing code are checked by rendering the canvases from mock data before and after and
  comparing them pixel for pixel.