chore(root): refresh agent skills and docs (#1835)

internal/decisions/ui/captions.md

@@ -0,0 +1,49 @@
+---
+status: decided
+date: 2026-02-26
+---
+
+# Captions: Native Rendering by Default
+
+## Decision
+
+Use native browser caption rendering by default. Custom caption rendering (HTML overlay) may be offered as opt-in in the future but is not the default path.
+
+Leverage WebKit pseudo-selectors and JS-based cue repositioning (from Mux Player prior art) to position native captions around player controls.
+
+## Context
+
+Sam built custom caption rendering with `::cue` styling, `prefers-contrast: more` support, `prefers-reduced-motion` adaptation, and control-aware positioning. The question was whether Video.js 10 should use custom rendering or native captions.
+
+New FCC regulations ([closed captioning display settings rule](https://www.fcc.gov/consumer-governmental-affairs/commission-announces-effective-date-closed-captioning-display-settings-rule)) require legally covered entities to respect OS-level user preferences for caption styling. There are no Web APIs to read those OS preferences yet (privacy/security concerns are blocking standardization — see [WebKit explainer](https://github.com/WebKit/explainers/tree/main/CaptionDisplaySettings)). Custom rendering would bypass these OS preferences, creating legal compliance issues.
+
+## Alternatives Considered
+
+- **Custom HTML overlay rendering (default)** — Better styling control and cross-browser consistency, but bypasses OS-level caption preferences required by FCC regulations. Not viable as the default for users who must comply with accessibility law.
+- **Custom rendering as opt-in** — Possible future addition. Heff and Christian didn't rule it out but it would need careful documentation about compliance trade-offs. Not in scope for initial release.
+
+## Rationale
+
+- Legal compliance: entities bound by FCC rules must respect OS caption preferences, which only native rendering honors.
+- Weight: avoids the complexity of a full caption rendering pipeline.
+- Prior art: Mux Player already solved native cue repositioning via JS ([cue positioning code](https://github.com/muxinc/elements/blob/main/packages/mux-player/src/themes/gerwig/gerwig.html#L67-L90)) and WebKit pseudo-selectors ([custom-media-element sizing](https://github.com/muxinc/media-elements/blob/main/packages/custom-media-element/custom-media-element.ts#L94-L113)).
+- Styling is limited but acceptable: `video::cue` works in Chrome/Firefox, WebKit needs vendor pseudo-selectors, iOS Safari may override with system UI in fullscreen.
+
+## Positioning Approach
+
+Native cue positioning uses two techniques:
+
+1. **WebKit** — CSS via vendor pseudo-selectors (`::-webkit-media-text-track-display`) with CSS custom properties.
+2. **Cross-browser** — JS-based cue line position manipulation at runtime (Mux Player approach).
+
+A scale transform prevents captions from touching container edges.
+
+## Open Questions
+
+- Christian wants to be involved in any future custom rendering design — it straddles architectural layers with many gotchas.
+- Christian has been pushing for a "Render Region" Web API at FOMS for rendering captions outside the video region.
+- `removeTextTrack()` may be re-added to the spec.
+
+## Participants
+
+Sam, Rahim, Christian Pillsbury, Wesley Luyten, Heff

internal/decisions/ui/gestures-as-components.md

@@ -0,0 +1,59 @@
+---
+status: decided
+date: 2026-03-13
+---
+
+# Gestures Should Be UI Components
+
+## Decision
+
+Gestures (click-to-play, double-click-fullscreen, keyboard shortcuts, etc.) will be implemented as UI components, not store features.
+
+## Context
+
+Users reported that click-to-play and hotkey behavior were missing in v10. This surfaced an open design question: should gestures follow the store feature pattern (renderless behavior attached to the store/container) or the UI component pattern (declarative elements in markup)?
+
+So far in v10, anything renderless that operates on the container has been a store feature (e.g. fullscreen, PiP), while things that render content or benefit from props live as UI components. Gestures are renderless, so the answer wasn't obvious.
+
+## Alternatives Considered
+
+- **Store feature** — Gestures don't render content and operate on the container, which fits the store feature pattern. Not chosen because store features make it harder to dynamically change options at runtime, can't be conditionally rendered based on context (e.g. ad playback, device type), and would unnecessarily expose gesture concerns on the store's surface area.
+
+- **Store feature with script setup** — Similar to how fullscreen and PiP currently work. Not chosen because gestures benefit from a declarative HTML-first API without requiring JS setup, and adding more script-setup-only behaviors widens an inconsistency that we are trying to minimize.
+
+## Rationale
+
+## Why Components win for gestures
+
+1. **Dynamic configuration via props** — Component attributes/props make it straightforward to change gesture settings at runtime without reaching into store internals.
+2. **Conditional rendering** — Gesture components can be conditionally included or excluded from the DOM based on context (e.g. ad playback, device type), which is more natural than toggling a store feature flag.
+3. **Clean declarative markup** — Keeping gestures in HTML as components avoids requiring script-based setup, which is the preferred pattern for v10's HTML-first API.
+4. **No store surface area** — Gestures don't need to expose state or actions on the store (unlike fullscreen or PiP), so there's little benefit to them living there.
+5. **Event structure over focus management** — DOM event bubbling and capture on the component tree handle gesture detection without requiring deep focus assumptions, which is important for Smart TV and custom focus-management library compatibility.
+
+### When to prefer store features
+
+The general heuristic:
+
+| Criteria | → Store Feature | → UI Component |
+|---|---|---|
+| Renders content | No | Yes (or optional) |
+| Needs dynamic prop-driven settings | No | Yes |
+| Dispatches events consumed locally by framework | No | Yes |
+| Exposes state/actions on the store (e.g. `isFullscreen`) | Yes | No |
+| Renderless + operates on the container | Yes | Not necessarily |
+
+Gestures are renderless but benefit strongly from dynamic props and conditional rendering, tipping the balance toward components.
+
+### Gesture components and focus
+
+Gesture components do **not** need focus. DOM structure combined with event bubbling/capture should account for all necessary interactions. This avoids problematic focus assumptions that conflict with Smart TV environments and spatial-navigation / focus-management libraries (a known pain point from prior Media Chrome work).
+
+### Context menu
+
+The native video element context menu should remain accessible by default. Blocking it to "prevent downloads" is considered an anti-pattern; if content protection is needed, an actual DRM/streaming solution (e.g. Mux) should be used instead. We may revisit this if strong real-world use cases emerge.
+
+## Consequences
+
+- Gesture behaviors (click-to-play, double-click-fullscreen, keyboard shortcuts, etc.) will each be implemented as custom element components.
+- Fullscreen, PiP, and similar capabilities that expose store state will remain as store features, even though they currently require script setup — this inconsistency is accepted for now.