feat: support Miruro provider tracks, proxies, and native embeds

docs/miruro-playback-handoff.md

@@ -11,10 +11,12 @@ Tubular launches native episode URLs. Terebi resolves fresh direct sources and i
 - **Tubular:** catalog/detail browsing, actual returned episode selection, collections, private reporting sessions, cleanup and watched-state decisions.
 - **Terebi:** episode-URL validation, fresh source resolution, headers/subtitles, titles, optional timeline bands, stable-identity resume and progress reporting.
 
-Native source resolution discovers validated direct Japanese `ssub`/`sub` providers at runtime, preferring soft subtitles per provider. **Playback → Miruro** and the gear menu offer independent **Video Host** / **Caption Provider** choices; optional `[miruro]` config strings `video_provider` and `caption_provider` set startup preferences (empty means Automatic). Missing/unsupported preferences fall back to Sun then returned order for video; captions prefer the chosen video's provider, then Sun and returned order. Dub is not an automatic fallback. Iframe/proxy/HLS-rewriting providers, cookies, impersonation and protection-bypass machinery remain unsupported.
+Native resolution retains actual `provider:track` choices (`ssub`, `sub`, `dub`) and discovers captions independently of video eligibility. **Playback → Miruro** and the gear menu offer independent **Video Host** / **Caption Provider** choices. Optional `[miruro]` config strings `video_provider` and `caption_provider` accept a bare provider preference or an exact choice such as `bee:ssub`; empty means Automatic. Automatic video prefers Japanese Sun, then provider order and each provider's variant order. Dub is selectable explicitly, never an automatic language fallback. A dub-only failed automatic open retains the catalog so its choices remain accessible.
 Host changes resolve fresh sources and preserve acknowledged position and playing/paused intent; caption changes retain their own provider/server headers and do not reopen video. Caption language is retained when available, and explicit Off survives provider changes. Choices made in menus are session-only. Native source menus are disabled during opening, pending seeks and casting.
 
-Provider-selection verification: resolver, configuration, CLI and metadata checks passed; app/CLI builds passed. Local native HLS/VTT playback exercised independent caption headers, in-place caption changes, missing-host fallback, paused/playing host changes, failed-fetch retention and rejection of late results after close. Existing mixed queues, report isolation and subtitle timing checks passed. A live probe found only Sun as a supported native video/caption provider for the sampled episode, with nine VTT tracks; other providers' live playback and visible menu/subtitle verification are not claimed.
+Provider-selection verification: resolver/configuration checks and the app/CLI build passed. Local native HLS/VTT smoke covered proxy encoding and already-proxied nested manifests, provider query/segment-origin rules, rejection of foreign loopback keys, independent caption headers, caption changes after prepared playback, paused/playing host switches, failure retention, stale results, and interactive dub-only selection. Live native video/audio, default captions, measured-duration metadata and acknowledged forward/backward subtitle seeks passed for `bee:ssub`, `hop:ssub`, `bun:ssub`, `bun:dub` and `sun:sub` on the sampled episode. These are headless model checks, not visible menu/subtitle or perceived A/V-sync sign-off.
+
+Final live rerun: the optional metadata endpoint stopped supplying usable enrichment, so the existing complete URL smoke and standalone live metadata check failed their metadata assertion after provider video had decoded. A separate native `PlayerModel` smoke, using the supported absent-enrichment outcome, then passed actual video/audio, default captions and both acknowledged cue seeks for all five choices listed above. The original metadata assertion was not removed or weakened; upstream metadata availability remains a live-service limitation.
 
 ## Launch contract
 
@@ -118,10 +120,22 @@ External source-document producers must preserve selected direct stream URLs and
 
 `identity.provider` is the catalog namespace `miruro`, not the stream provider `sun`. Titles, slugs and expiring CDN URLs are not identity. Tubular no longer projects source documents.
 
-## Propagation and subtitle behavior
+## Native provider transport
 
-- Stream headers reach the master, nested variants, media segments, AES-128 keys and fMP4 init resources. Relative references use native HLS resolution. Existing query tokens are preserved; Terebi does not invent query inheritance or provider-specific URL rewrites.
-- Resolved media requests must stay on the initial stream's origin: scheme, host and effective port. **All media redirects, including same-origin redirects, are rejected before a second request.** This conservative policy prevents FFmpeg from forwarding supplied private headers to another destination. Cross-origin HLS resources are not supported in this contract.
+Terebi, not Tubular, prepares provider-specific playback. Bee/Hop object-valued proxies are preserved. Proxy bases and the public URL codec are read from Miruro's deployment environment; playlists, captions and resources use their distinct proxy routes. Already-proxied manifest references are decoded before applying provider rules, avoiding double wrapping. Enabled playlist query overrides apply to nested playlists; a truthy `skip` first tries without `token`, then the original token on request failure. Segment-origin rewriting applies to segments and `EXT-X-MAP`, not AES keys.
+
+MegaPlay iframe sources used by Bun are extracted without executing JavaScript or opening a browser. Terebi reads the embed's declared source endpoint and deployed public AES/HMAC codec constants, decrypts source/segment references, and handles the provider's token and selected-CDN prefix rules. The fixed public MegaPlay Referer accompanies its media requests. Other embed hosts are not treated as playable native streams.
+
+Iframe captions may duplicate a same-track parent's exact returned resource set. Only when those complete subtitle records match and the iframe has no request headers does Terebi reuse that parent's caption headers/proxy; Bun remains the selected caption provider. This is a native integration policy, not general inheritance of video configuration. Different resources never receive the parent's request context.
+
+Prepared playback uses a capability-token loopback relay retained by the current source, including across in-place caption changes and Cast preparation. Native decoding receives no upstream headers. Supplied private headers remain source-origin-bound; foreign destinations are checked against resolved private/local addresses, while the embed's fixed public headers have media-wide scope. Redirects are rejected. Manifests are bounded to 2 MiB, individual resources to 64 MiB, request concurrency to eight, route count to 32,768 and nesting depth to twelve. Resources are buffered individually, never downloaded as a complete episode; oversized resources fail closed. After an embed body is transformed, range offsets and `Content-Range` describe the transformed representation.
+
+Protocol references: [Miruro watch client](https://barelystarted.miruro.tv/_app/immutable/nodes/11.CUef647B.js), [deployment environment](https://barelystarted.miruro.tv/), [MegaPlay source bootstrap](https://megaplay.buzz/videojs/lib/e1-player.min.js?v=3.19), [MegaPlay resource transforms](https://megaplay.buzz/videojs/lib/newclient.min.js?v=4.23). Deployment changes can invalidate native extraction; errors redact source details.
+
+## Direct source-document propagation and subtitle behavior
+
+- The unchanged external version-1 source-document path supplies direct URLs, without native provider requirements. Stream headers reach the master, nested variants, media segments, AES-128 keys and fMP4 init resources. Relative references use native HLS resolution; existing query tokens are preserved without invented inheritance or rewrites.
+- Direct source-document media requests stay on the initial stream's origin: scheme, host and effective port. **All media redirects, including same-origin redirects, are rejected before a second request.** The provider relay described above is a separate internal preparation path, not an extension of this external file format.
 - Sun serves MPEG-TS segments as `.jpg` / `image/jpeg`. Resolved playback probes actual media content instead of enforcing filename-extension matching; it does not change the URLs. HTTP(S)-only, origin and redirect restrictions remain in force.
 - External VTT classification uses explicit format and content, not filename extension or MIME type. `.jpeg` subtitle URLs work. Labels/languages appear in the captions menu; the declared default is selected, and the user can choose Off or another track.
 - Cues follow acknowledged player position, including seeking backwards. Zero-duration cues are permanently inactive rather than invalidating the track. Rendering is plain text; WebVTT CSS, positioning and typographic styling are not applied.
@@ -200,9 +214,11 @@ Explicit live native URL smoke (contacts Miruro and media/subtitle resources):
 ```sh
 .build/miruro-metadata-check --live 'https://barelystarted.miruro.tv/watch/OERe_a0YS4h-DlsBDOeXwX7HOO6316tw/episode?ep=1'
 .build/resolved-playback-check 'https://barelystarted.miruro.tv/watch/OERe_a0YS4h-DlsBDOeXwX7HOO6316tw/episode?ep=1'
+.build/resolved-playback-check 'https://barelystarted.miruro.tv/watch/OERe_a0YS4h-DlsBDOeXwX7HOO6316tw/episode?ep=1' --provider=bun:ssub
 ```
 
 URL smoke expects a fixture episode with available title, bands and default subtitles. It checks native decode and acknowledged subtitle/seek state, not visual appearance or perceived A/V synchronization. Tubular's catalog probe does not run Terebi or retrieve sources.
+The optional `--provider=provider:track` exercises that exact live choice; use `bee:ssub`, `hop:ssub`, `bun:ssub`, `sun:sub`, or an explicitly dubbed choice such as `bun:dub`. Live checks can emit redacted FFmpeg warnings/errors while still passing; they assert actual decoded state and cue timing, not the absence of diagnostics.
 
 Metadata implementation verification (2026-10-22): protocol/security/bounds checks, lifecycle replacement/A-B-A stale results/duration changes, stream resolver and CLI checks passed. The live placeholder resolved the descriptive title “The Apothecary Diaries Season 3 — Episode 1: Locusts,” opening 63.313–153.237 seconds and ending 1335.252–1425.384 seconds; native video/audio advanced, measured-duration bands appeared in model state, and default VTT plus forward/backward acknowledged cue seeks passed. FFmpeg emitted redacted diagnostics during this successful run; no visual synchronization or visible-band sign-off is claimed.
 
@@ -214,7 +230,7 @@ Segment-skip verification (2026-10-22): local HLS/VTT playback exercised late me
 
 - Confirm title readability and gapped slider segments in normal/compact controls, buffer/playhead visibility and subtitle alignment in the visible app using Tubular's real launch path. Offscreen native rasterization at compact/normal widths confirmed all four interval-boundary gaps remain clear even with full buffer coverage.
 - Tubular collection launches, retained-report recovery and watched decisions remain its acceptance responsibility; this implementation changes no collection or progress schema.
-- Media redirects/cross-origin HLS resources remain unsupported. Native URL launches resolve fresh; externally supplied source documents must be refreshed by their producer. Automatic expired-source refresh is not implemented.
-- Other providers' proxies/HLS rewrites, iframe providers, downloads, thumbnails, automatic skipping, embedded captions and additional external-subtitle formats remain out of scope.
+- Media redirects remain unsupported; external direct source documents also retain their same-origin restriction. Native URL launches resolve fresh; externally supplied source documents must be refreshed by their producer. Automatic expired-source refresh is not implemented.
+- Embed extraction is currently MegaPlay-specific. Downloads, thumbnails, automatic skipping, embedded captions and additional external-subtitle formats remain out of scope.
 
 The implementation and this handoff are local; no remote publication or Tubular issue/comment update was performed.