✨ [Story player] Re-emit captions state to host page

[michaeldegori]

✨ [Story player] Re-emit captions state to host page

Summary

Adds <amp-story-player> re-emit of caption-state changes so host pages embedding an amp-story can listen for caption toggles, mirroring the existing amp-story-muted-state event.

Why

The player already bridges muted-state from the embedded story to the host element:

// src/amp-story-player/amp-story-player-impl.js
onMutedStateUpdate_(muted) {
  this.element_.dispatchEvent(
    createCustomEvent(this.win_, 'amp-story-muted-state', {muted})
  );
}

Caption-state is a parallel user-toggleable media state in the story (now also analytics-traced as of the captions-analytics PR), but the player does not re-emit it. Host pages embedding an amp-story can't observe caption toggles. This PR adds that bridge.

Changes

src/amp-story-player/amp-story-player-impl.js — four small additions mirroring the muted-state plumbing:

1. New enum entry CAPTIONS_STATE: 'CAPTIONS_STATE' in STORY_MESSAGE_STATE_TYPE_ENUM.
2. New messaging.sendRequest('onDocumentState', ...) subscription on handshake, next to the muted-state one.
3. New case in the onDocumentStateUpdate_ switch, routing inbound CAPTIONS_STATE messages.
4. New handler onCaptionsStateUpdate_(captions) that dispatches an amp-story-captions-state CustomEvent on the player element with {captions} detail.

docs/spec/amp-story-player.md — documents the new event in the same voice as amp-story-muted-state.

test/unit/test-amp-story-player.js — two new tests covering the on/off dispatch, mirroring the existing muted-state tests verbatim.

Public API shape

player.addEventListener('amp-story-captions-state', (event) => {
  console.log('captions on?', event.detail.captions);
});

Naming notes

• Event name amp-story-captions-state matches the amp-story-muted-state precedent.
• Detail key captions (not captionsState) matches the muted-state external API which drops the _STATE suffix (MUTED_STATE → event.detail.muted). The internal store key in amp-story is captionsState, but the external event surface keeps parity with muted.
• Enum value CAPTIONS_STATE matches MUTED_STATE style.

Out of scope (intentional follow-up)

This PR is story → host re-emit only. It does not add a host → story push direction analogous to updateMutedState_ / player.mute() / player.unmute() (lines 1472-1478 + 279-280 in amp-story-player-impl.js). The receiving side already exists in amp-story (the store accepts setDocumentState for CAPTIONS_STATE), so an updateCaptionsState_ + player.toggleCaptions() follow-up is mechanical if reviewers want it; my use case is host-side observation only, so I kept the diff minimal. Happy to add the push side in a separate PR.

Test plan

• npx eslint clean on touched files
• amp unit --files=test/unit/test-amp-story-player.js — 2 new tests pass; 84 of 85 tests green (the one failure, revert navigation animation after transition ends, is a pre-existing flake on clean upstream/main unrelated to this diff — verified by stashing the changes and rerunning)
• Manual smoke against a host page with an amp-story-captions-state listener

[michaeldegori]

Superseded by upstream PR ampproject#40506.