Capability model

approved

Capabilities are the composable LT functions on top of the core: chapters, captions, speed, share, and context panel today. This document defines how every capability behaves in the configuration model; each capability's own document defines what it does.

Availability and enablement

• Available means the data a capability needs exists in content (subtitle tracks make captions available; a chapters array makes chapters available). Capabilities without a data dependency (for example speed) are always available.
• Enabled means configuration allows the capability. The default rule: available implies enabled. Content that ships with chapters gets chapters without any configuration.
• Dormant means enabled but not available: the capability stays invisible and inert. No error, no placeholder.
• Disabling is always explicit configuration ("chapters": false), never data deletion. Content documents stay reusable across contexts.

The merge cascade

Configuration resolves in three layers; later wins:

1. Built-in defaults.
2. Instance configuration from the hosting page.
3. User state: volume and mute, playback rate, and captions on/off and language.

Merge semantics (full rules in the config contract): objects merge by key, arrays replace wholesale, explicit false disables, and omitted keys resolve from the built-in default. Resolution has no layout dimension; layouts omit surfaces they do not own after configuration resolves.

Defaults

All capabilities default to enabled. Capability-specific options may define their own built-in defaults, resolved identically for every layout.

User choices outlive configuration updates

An explicit user choice survives every configuration update and every visit: captions on or off and the chosen track language, playback rate, and volume with mute. The player persists that intent in the single localStorage value defined by the storage contract. Content defaults, such as a default caption track, apply only until the user has a stored choice in that area. Explicit removal still beats user preference, and user preference beats configuration and built-in defaults wherever the function exists.

Capability configuration shape

Every capability key under capabilities accepts:

• false: disabled.
• true or omitted: enabled with defaults (subject to availability).
• An object: enabled, with capability-specific options as defined in its document.

Uniformity contract

Every capability document specifies the same eight sections: purpose, behavior, surface in landscape, surface in portrait, configuration, page API hooks, edge cases, out of scope. A capability that cannot fill a section states so explicitly. The configuration section always includes an example snippet showing the capability's keys in a real configuration fragment.

Future extension points

• Named presets (predefined configurations participating in the cascade between built-in defaults and instance configuration) are anticipated but deliberately not implemented.
• New capabilities enter through a new document in the catalog plus a framework registration; the framework itself does not change per capability.