---

name: rfc description: >- Write and review RFCs for Video.js 10. Use for design documents, architecture decisions, API proposals, and UI component specifications. Triggers: "write RFC", "create RFC", "design doc", "review rfc", "component spec", "architecture proposal".

RFC

Write Request for Comments (RFC) documents for Video.js 10.

Reference Material

When to Write an RFC

Write an RFC for:

• Major API changes or new APIs
• Architectural decisions affecting multiple packages
• Design patterns used across the codebase
• UI component specifications

Skip the RFC for:

• Bug fixes
• Small features in one package
• Implementation details
• Documentation updates

See rfc/README.md for status lifecycle, branch workflow, and relationship to implementation plans.

Principles

1. Start with the Problem

Every RFC begins with the pain we're solving. A first-time reader needs context before solutions make sense.

Copy## Problem

Two concerns, one player:

1. **Media** — play, pause, volume. Owned by `<video>`.
2. **Container** — fullscreen, keyboard. Owned by the UI wrapper.

Different targets, different lifecycles. But users want one API.

2. Human-Readable

RFCs are for humans, not machines. Write for someone joining the project tomorrow.

• Explain "why" before "what"
• Define terms on first use
• Link to existing code instead of duplicating

3. Concise with Good Flow

Every sentence earns its place. Cut ruthlessly.

Copy// ❌ Verbose
In order to ensure that the user is able to interact with the player
in a consistent manner across different platforms, we need to...

// ✅ Direct
Users expect one API. We expose two stores internally, one API externally.

4. Progressive Disclosure

Start high-level, reveal complexity gradually:

1. Problem — What pain exists?
2. Solution overview — How do we solve it?
3. Quick start — Show it working
4. Details — API surface, architecture
5. Rationale — Why these choices?

5. Code Illustrates Ideas

Code examples show concepts, not implementation details:

Copy// ✅ Illustrates the concept
const player = usePlayer();
player.paused; // state
player.play(); // request

// ❌ Implementation detail
function usePlayer() {
const store = useContext(PlayerContext);
const [, forceUpdate] = useReducer(x => x + 1, 0);
// ... 50 more lines
}

6. Unpack Chronologically

Introduce concepts in the order a reader needs them. Don't reference something before explaining it.

Copy// ❌ References unexplained concept
PlayerTarget includes a reference to the media proxy.

// ✅ Explains first, then uses
Media features observe `<video>`. Player features need access to media state.
PlayerTarget includes a media proxy for this coordination.

7. Examine Existing Code

Before writing, explore relevant parts of the codebase. Link to existing patterns rather than duplicating.

CopyBased on the existing `SnapshotController` pattern. See `packages/store/src/snapshot.ts`.

8. Track Key Decisions

Record every significant design decision in decisions.md. Include alternatives considered. When a decision evolves, update the existing entry — don't append a new one.

Copy// ❌ Appending creates confusion

### Flat API Shape (v1)

State and requests on same object.

### Flat API Shape (v2)

Actually, we added namespaces...

// ✅ Update in place, include alternatives

### Flat API Shape

**Decision:** State and requests on same object, no namespaces.

**Alternatives:**

- `.state`/`.request` namespaces — explicit but verbose
- Separate hooks (`usePlayerState`, `usePlayerActions`) — familiar but splits concerns

**Rationale:** Less nesting, proxy tracks at property level. Runtime duplicate detection catches collisions.

Checklist

Before finalizing an RFC:

• Problem before solution — context first
• Concepts explained before referenced
• Code illustrates ideas, not implementation
• Minimal examples — only show what's different, {/* ... */} for the rest
• Scannable — lists and whitespace, not walls of text
• Single source of truth — explain once, link elsewhere
• Decisions have alternatives and rationale
• Decisions updated in place, not appended
• Examples match current proposal
• Focused scope — future work in Open Questions
• Multi-file if 3+ distinct concepts
• Frontmatter has status: draft

Process

1. Explore — Read relevant code, understand current patterns
2. Choose type — Feature RFC or Component RFC?
3. Choose structure — Single or multi-file?
4. Draft — Start with problem, build progressively
5. Cut — Remove anything that doesn't earn its place
6. Link — Reference existing code, related RFCs
7. Review — Check against checklist

Related