demuxe 0.3.0-beta.3

package/docs/PLAYER-COMPONENT.md

@@ -0,0 +1,247 @@
+# Optional player component
+
+This is the target contract; qualification is recorded separately. Import
+`definePlayerElement` from `demuxe/player` and call it once (repeat calls with the
+same implementation are harmless). Core import does not import UI or register a
+tag. SSR imports are safe; registration and construction require a browser.
+
+`<demuxe-player controls asset-base="/assets/demuxe/" poster="/preview.jpg">`
+creates one Player on connection. ready resolves with that core; player exposes it
+read-only after initialization. open, close, destroy and playback conveniences
+delegate to it. The component contains no route selector or playback scheduler.
+
+src is a remote URL. Changing it cancels a previous pending source open; only the
+latest accepted change wins. Removing src closes media. Programmatic open accepts
+all core source types. autoplay requests play only after acceptance and reports
+normal browser policy rejection without fallback. muted reflects configured mute;
+controls toggles controls and closes open settings/stats overlays when disabled;
+poster is an idle/loading preview. asset-base is fixed
+after initialization and rejects changes. Set it before connection. Pre-upgrade
+properties are replayed on upgrade. Boolean attributes follow HTML presence rules.
+
+A microtask grace period preserves playback during synchronous DOM moves. Actual
+removal aborts work and destroys the owned core; reconnect waits for that cleanup
+before creating the next core. Explicit destroy is terminal, including reinsertion.
+ready waits for connection; destroy before connection rejects it.
+
+The open shadow root includes stage, controls, settings and status parts, CSS
+public Demuxe theme variables, and before-controls /
+after-controls slots. Labels can be overridden before or after connection.
+Controls use semantic buttons/ranges/selects, visible focus, scoped keyboard
+shortcuts, local drag preview, and an aria-live status that excludes time updates.
+Settings restore focus on close. Fullscreen requests the component container in
+the user gesture, keeping controls and subtitles together. PiP/casting are not
+qualified. Loading, live windows and errors use core state only.
+
+Forwarded core events are dispatched once with unchanged detail, bubbles:false;
+listen directly on the element. No event-name aliases are generated. Component
+lifecycle failures use error with a structured operation-scoped detail.
+
+## Multiple files and queue
+
+The component's media picker accepts multiple files. Selecting or dropping files
+adds them in the supplied order, preserving duplicate filenames. If nothing is
+queued, the first item opens; otherwise files append without interrupting playback.
+The initial item follows `autoplay` (paused by default).
+
+The folder menu shows the queue, with the current item highlighted. Select a file
+to switch, remove individual items, or use **Clear queue** to stop and release all
+queued sources. Removing the current item opens the next available item, or the
+previous one if it was last. If that replacement fails, the removed media is
+closed and the remaining queue stays available for retry or selection. Removing
+other items leaves playback untouched.
+
+Previous/next buttons and an item count appear beside the timeline controls when
+there is more than one item. Manual changes preserve play/pause intent; an explicit
+play or pause during loading overrides the intent captured when switching. Reaching
+the end advances and plays the next file; the final item stops without looping.
+An opening failure stops on that item and uses the existing error/retry UI;
+it does not silently skip through the queue.
+
+`element.open(source)`, `src` changes, and URL submissions replace the queue with
+one source. `close()`, destruction and actual disconnection clear the queue and
+release its file references. Synchronous DOM moves keep it. No queued item is
+preloaded, and all opens delegate to the same core `Player`.
+
+`showSourceControls = false` hides and disables queue management along with file
+input. Previous/next playback controls still work. `allowFileDrop` independently
+controls file drops. Files in a batch are treated as media; use the separate
+subtitle picker to attach subtitles.
+
+The queue is built-in UI state, not a second core playback API. Applications
+needing their own playlist policies can use the core `Player` and manage sources
+themselves.
+
+## Customization
+
+```html
+<demuxe-player
+  controls
+  title="Movie Night"
+  asset-base="/assets/demuxe/">
+</demuxe-player>
+```
+
+The standard HTML `title` property/attribute updates the displayed title live.
+`titleMode` (also `title-mode`) has four policies:
+
+* `auto` (default): a nonempty custom `title`, otherwise the accepted source
+  filename, otherwise nothing.
+* `custom`: only `title`; an empty string hides it.
+* `source`: only the accepted source filename, even when a custom title exists.
+* `none`: hide the title.
+
+Local files use `File.name`. HTTP(S)/file URLs, including remote source
+descriptors, use the decoded final pathname filename only. Origins, credentials,
+query strings and fragments are excluded. Directory URLs, ArrayBuffers, opaque
+URLs such as blob/data URLs, and unnamed sources show nothing. Source titles
+track successful `element.open()` / `src` opens and clear when that source closes
+or is replaced through the core; applications opening directly through
+`element.player` should manage a custom title. Titles are plain text and truncate
+visually to fit the player.
+
+```ts
+const element = document.querySelector("demuxe-player");
+element.titleMode = "source";
+```
+
+For an embedded app, disable utility UI while retaining playback controls:
+
+```ts
+element.showSourceControls = false;
+element.showDiagnostics = false;
+element.allowFileDrop = false;
+await element.open(source); // The host application owns source selection.
+```
+
+These three properties default to `true` and update live. Source controls include
+the empty-state opener, folder menu, URL form and local media/subtitle pickers.
+Disabling them closes their menu and disables the input handlers. Programmatic
+`open()` and `addSubtitle()`, plus existing subtitle track selection, still work.
+Disabling diagnostics closes its overlay; `element.player.diagnostics` remains
+available. Disabling file drop leaves browser drag/drop defaults alone. Drop
+handling is independent of source-control visibility: disable both when the host
+owns all source input. Focus moves to the stage if a focused utility is disabled.
+These options are JavaScript properties, not HTML boolean attributes.
+
+`seekStep` defaults to 10 seconds and accepts a positive finite number. It
+controls both seek buttons, their default accessible labels/numerals, and J/L.
+Arrow keys retain their five-second steps. Explicit localized `labels.back` and
+`labels.forward` override the default labels; keep them consistent with your step.
+`controlsAutoHideDelay` defaults to 2800 milliseconds; zero disables inactivity
+hiding, and positive values up to 2147483647 set the delay. Changing it restarts
+the timer. Playing with the play button/shortcut still hides controls immediately;
+screen taps still toggle visibility. Invalid numeric property values throw
+`INVALID_ARGUMENT`.
+
+For entirely custom controls, import `Player` from `demuxe` and build your own
+layout. The optional component delegates to that same core and adds no playback
+modes or routing policy.
+
+```js
+import {definePlayerElement} from 'demuxe/player';
+definePlayerElement();
+const element = document.querySelector('demuxe-player');
+element.labels = {play: 'Lire', pause: 'Pause', settings: 'Réglages'};
+const core = await element.ready;
+const unsubscribe = core.subscribe(state => console.log(state.status));
+await element.open(file, {signal: controller.signal});
+// Later: await element.close() to reuse, or await element.destroy() to finish.
+```
+
+Methods also include play, pause, seek, setVolume, setMuted, setPlaybackRate,
+selectAudioTrack, selectSubtitleTrack and addSubtitle. Advanced font, filter,
+tone-mapping and source policy methods are available through the read-only player
+reference. Replacing that reference is unsupported. Use a new element for a
+new asset-base; the old one must finish cleanup first. An asset-base attribute
+change after initialization is reverted and reports INVALID_ARGUMENT.
+
+```css
+demuxe-player {
+  --demuxe-background: #121318;
+  --demuxe-stage-background: #090a10;
+  --demuxe-foreground: #f2f1f7;
+  --demuxe-muted-foreground: #bbb8ca;
+  --demuxe-panel-background: #20212a;
+  --demuxe-control-background: #30313e;
+  --demuxe-overlay-background: #171824bb;
+  --demuxe-accent: #b7a0ff;
+  --demuxe-border: #393941;
+  --demuxe-radius: 16px;
+}
+demuxe-player::part(controls) { padding-inline: 20px; }
+demuxe-player::part(title) { font-weight: 600; }
+demuxe-player::part(timeline) { height: 32px; }
+```
+
+For a light skin, set the same surface variables to light colors, foregrounds to
+dark colors, and `color-scheme: light` on the element for native form controls.
+All public theme names use `--demuxe-*`; there are no legacy branding aliases.
+
+Stable parts: container, stage, controls, settings, error, status, title, topbar,
+transport, timeline, volume. The volume part wraps the mute button and slider. Limited slots:
+before-controls, after-controls and source-actions. The source-actions slot adds
+host-owned buttons to the source menu; activating a button closes the menu and
+focuses the stage. The playground uses it for its example media. Shadow IDs/classes are implementation details.
+Air controls overlay the video: an open-media action at the top, a large unboxed
+play/pause icon between backward/forward seek buttons (ten seconds by default) at the center,
+and a thin full-width timeline with elapsed and total times at opposite ends.
+Seek buttons clamp to available seek ranges and disable while an operation is
+pending or no seek window exists. Volume shares the timestamp row below the
+timeline; settings and fullscreen sit at the top right. The gear opens compact playback settings; the folder opens file/URL
+inputs and subtitle upload separately. The eye toggles a live session diagnostics
+text overlay that remains visible when playback controls hide. The overlay is
+scrollable and keyboard-focusable; navigation keys scroll it, and Escape closes
+it and returns focus to the eye. Top-right icons
+use motion on hover and a stronger accent stroke when active. Buffering displays
+a small central ring even with hidden controls. Timeline shading uses reported
+buffered ranges (currently Native only); unavailable ranges are not estimated.
+Control sizes and compact layouts follow the player container width, including
+small embeds in wide browser windows. Pointer controls retain 36px targets and
+coarse-pointer devices use 44px targets. On narrow players, opening a menu hides
+the central controls to avoid overlap. Play hides controls immediately; mouse
+movement reveals them, and inactivity fades them out. Leaving the player with
+the mouse also hides controls while playing (not while paused), unless a menu,
+pending operation, timeline drag, or keyboard-visible focus needs them. Losing
+focus alone does not hide controls; touch input keeps its existing tap behavior. Seeking with hidden
+controls briefly shows only the timeline and times, for 800 ms after completion. Tapping the video toggles controls
+in playing or paused playback. Clicking outside a menu dismisses it without
+stealing focus; Escape returns focus to its trigger. Hiding controls preserves
+focus on the stage; keyboard navigation reveals controls. Keyboard shortcuts apply to
+focus inside the component; inputs keep their native keys, and buttons retain
+Space/Enter activation, except top-right icons reserve Space for playback
+and use Enter for activation. Playback keys: Space/K, arrows, J/L, M, C, brackets, digits,
+Home/End, F and ?. Inputs, selects, editable content and modified keys
+retain their normal handling. C uses the core's subtitle visibility setting;
+it does not select a different language. Scrubbing previews locally; release
+commits one seek. Settings are an accessible disclosure and restore trigger focus.
+
+Local file/subtitle pickers are available in settings; opening files never uploads
+them. File drop and a URL form (File, HLS, DASH, and live input)
+are also built into the component. File selection, URL submission, and file drop
+focus the stage so Space controls playback; the public close() method closes media. The component contains no example media, engine selector,
+raw filters or memory metrics. The playground keeps automatic engine selection
+enabled and shows a compact engine/media summary below the player. A live stream with no known seek window shows LIVE
+and disables the finite seek control. Browser fullscreen denial produces a message;
+no fake fullscreen, PiP or casting fallback is applied.
+
+Experimental playback optimizations use the existing Player owner and do not add
+public modes or automatic component controls. See [the integration stage](OPTIMIZATION-INTEGRATION.md)
+for constructor flags, scalar gain, and current qualification limits.
+
+The programmatic Player option `experimentalAudioAdaptation: 'flac'` is an explicit
+Native trial gate. No new component attribute or automatic route is introduced.
+See [the FLAC qualification report](OPTIMIZATION-FLAC.md) for required optional assets,
+track/fidelity limits and unsupported subtitle combinations.
+
+
+## Optional playback processing
+
+The component delegates playback, subtitle selection and visibility to its core
+Player; it owns no separate optimization route or audio graph. Applications using
+an explicitly configured core can call `setAudioGain` repeatedly without replacing
+the video session. Ordinary component volume/mute controls retain their existing
+meaning. The component fullscreen container includes subtitle canvases. Native
+ASS and adaptation require explicit core constructor options and optional assets;
+there are no new component attributes or silently enabled experimental defaults.
+See [core options and restrictions](PUBLIC-API.md#experimental-playback-optimizations).

package/docs/PUBLIC-API-VALIDATION.md

@@ -0,0 +1,163 @@
+# Public API and component qualification
+
+Implementation baseline: working files matched demo-source 8bb451b while main was
+f9a8f9c. No branch was merged or published. The pre-change source snapshot is
+build/public-api-baseline/source-before.tar.gz. Historical results and failed
+artifacts are retained.
+
+## Milestone status
+
+| Milestone | Implementation | Qualification boundary |
+| --- | --- | --- |
+| M0 | Public contract, component contract, migration notes | Source-reviewed against current transaction/engine owners |
+| M1 | Immutable snapshots, subscriptions, typed events, media geometry/tracks, capabilities | Real Native/Hybrid/Software tests; unknown/live-window mappings have separate adapter-injection evidence |
+| M2 | Additive commands, stable IDs, cancellation, close/reopen, idempotent teardown, structured/redacted errors | Real rollback, stale-event, mute, track transition, seek and cleanup checks |
+| M3 | Same-origin runtime base, verified copy CLI, static and bundled entry points, SSR-safe imports | Exact archives installed into independent static and esbuild apps at two runtime paths |
+| M4 | Optional custom element and migrated playground, same core | Two independent instances, source changes, removal/reconnect and actual fullscreen |
+| M5 | Keyboard, semantic controls, accessible names, focus restoration, live announcements, styling hooks | Chrome/Firefox keyboard and accessibility-tree checks; manual screen-reader and physical touch sessions remain open |
+| M6 | Tests, examples, package evidence, overhead samples | Local candidate qualification only; clean three-engine builds, Safari/mobile, physical output and release gates remain open |
+
+Archive-specific qualification is generated **after** assembly, alongside the
+archive as qualification.json. An embedded copy of this document describes the
+build-time status; it cannot contain its own archive hash. Consult the accompanying
+record and the repository results for final pass/fail status and test hashes.
+
+## Reproducible commands
+
+```sh
+npm run build
+node --test tests/public-api-state.mjs
+node tests/public-api.mjs
+BROWSER=firefox node tests/public-api.mjs
+node tests/player-component.mjs
+BROWSER=firefox node tests/player-component.mjs
+node tests/autoplay-policy.mjs
+BROWSER=firefox node tests/autoplay-policy.mjs
+node tests/player-api.mjs
+node scripts/media-server.mjs # separate terminal; synthetic origins 4180/4181
+node --test tests/range-reader-deadline.mjs tests/range-reader.mjs \
+  tests/audio-worklet.mjs tests/resource-loader.mjs tests/streaming-expansion.mjs \
+  tests/remux-buffering.mjs tests/video-codec-config.mjs \
+  tests/retained-codec-worker.mjs tests/native-selection.mjs
+ONLY='Live,External,HLS,Finite DASH,Audio device' node tests/compatibility-expansion.mjs
+node tests/player-ui-overhead.mjs
+npm install --prefix build/public-api-tooling --no-audit --no-fund esbuild@0.28.2
+python3 scripts/package-beta.py --output build/public-api-release-candidate
+BETA_ARCHIVE=build/public-api-release-candidate/demuxe-0.3.0-beta.3.tgz node --test tests/copy-assets.mjs
+BETA_ARCHIVE=build/public-api-release-candidate/demuxe-0.3.0-beta.3.tgz node tests/public-api-consumer.mjs
+BETA_ARCHIVE=build/public-api-release-candidate/demuxe-0.3.0-beta.3.tgz BROWSER=firefox node tests/public-api-consumer.mjs
+BETA_ARCHIVE=build/public-api-release-candidate/demuxe-0.3.0-beta.3.tgz node tests/beta-streaming.mjs
+BETA_ARCHIVE=build/public-api-release-candidate/demuxe-0.3.0-beta.3.tgz BROWSER=firefox node tests/beta-streaming.mjs
+```
+
+Results go to timestamped results/public-api/, results/player-component/,
+results/public-api-consumer/, results/beta/ and existing regression directories.
+The archive tests record SHA-256, browser version, consumer root and case results.
+The esbuild application imports only shipped package entry points and copies its
+runtime via the shipped command. No repository-specific browser code is needed.
+
+## Interpreting evidence
+
+The prior 21-case API suite, 73 reader/routing/audio unit checks and focused HLS,
+DASH, subtitle/font and audio-device regressions passed during this work. New
+normalized-state and component suites exercise real engines, while explicitly
+labeled adapter injection tests cover unknown metadata and live-window mapping.
+They do not certify every live demuxer or codec. Browser isolation and missing
+assets are tested as distinct errors. Missing assets must be rejected at the HTTP
+origin because worker fetch interception differs across automation engines.
+
+Autoplay checks must not run evaluation polling while the initial play request
+is pending: automation evaluation can grant transient activation. Chrome rejected
+Native and Hybrid and resumed after a click. Firefox rejected Native but allowed
+the Web Audio Hybrid path in the observed environment; that difference is not
+reported as a codec failure or an invented autoplay rejection.
+
+The UI adds no engine polling. The short overhead harness compares the same
+example.mp4, mode and 1920×1080 output for four seconds, using browser main-thread
+ScriptDuration. Those samples describe UI/event work only, not full engine CPU,
+real-time output quality, sustained playback or a performance improvement.
+
+The in-app browser plugin could not connect because an installed module was
+missing. Qualification used standalone real Chrome/Firefox automation. No manual
+VoiceOver/NVDA session, physical touch, Safari, PiP, casting, physical HDR/surround
+fidelity or independent clean build of all three engines is claimed. GPL/source
+obligations and the release gate in RELEASE.md remain intact. The public Pages
+site has not been updated by this work.
+
+## Archive-specific record
+
+The final archive hash and exact result paths are recorded after assembly in the
+accompanying qualification.json and in the working repository's final report.
+This embedded build-time statement deliberately contains no self-referential
+archive hash. Earlier candidates, failures and their evidence remain preserved.
+
+
+## Final local candidate — 2026-09-12
+
+Artifact: `build/public-api-release-candidate/demuxe-0.3.0-beta.3.tgz` (17,845,779 bytes).
+
+SHA-256: `2b7d99731bb05c33d8d24648550fafda90c4ad13968d2dbbdb777ef48421bb4a`.
+
+The package assembled alongside `build/pages-api-release-candidate` is byte-identical.
+Every packaged manifest entry was verified. Generated core/component files match the
+working implementation; all three shipped Wasm binaries match the previous Pages
+manifest. These are existing engine binaries, not newly qualified clean engine builds.
+The final report is external to the archive to avoid a self-referential archive hash.
+
+| Suite | Chrome 152.0.7977.83 | Firefox 146.0.1 | Evidence scope |
+| --- | --- | --- | --- |
+| Normalized core | 14/14 | 14/14 | Current core source hashes |
+| Component | 14/14 | 14/14 | Current component source hashes, including release of retry sources |
+| Clean static and esbuild consumers | 8/8 | 8/8 | Exact archive; two runtime bases, all three modes, SSR/types/import isolation |
+| Streaming/seek | 6/6 | 6/6 | Exact archive; packet integrity, absolute deadline, cleanup |
+| Local Pages assembly | 8/8 | 8/8 | Matching packaged runtime manifest; no public deployment |
+| Autoplay policy | 2/2 | 2/2 | Recorded browser policy behavior, including Firefox allowing Hybrid |
+
+Additional checks: 4 asset-copy tests, 5 pure state/error tests, 73 existing unit
+checks, 21 existing API cases and 7 focused compatibility cases passed. The actual
+`npx --offline demuxe copy-assets npx-runtime` command copied 96 verified assets
+from a clean installation of this archive. Exact paths, result hashes, CLI output,
+source/build-material archive hashes and qualification boundaries are recorded in
+`build/public-api-release-candidate/qualification.json`.
+
+A Pages harness failure is retained at
+`results/pages/firefox-2026-09-12T14-06-43.067Z/result.json`.
+The harness could mistake the previous source's idle operation state for completion
+of the asynchronously fetched example. The final harness explicitly waits for a
+new accepted source identity. This test-only correction does not change package
+bytes. Historical candidates and failures remain preserved.
+
+Four-second matched playback samples measured core/component main-thread script
+work of 4.027/6.377 ms (Native), 44.603/57.464 ms (Hybrid), and 19.553/32.696 ms
+(Software). Notification counts were equal within each pair: 19, 129 and 129.
+These earlier short samples are not engine CPU or sustained performance claims.
+
+The implementation is complete for the stated scope. M5's manual screen-reader
+and physical touch gate and M6's broader browser/clean-engine/release gates remain
+open as listed above. No commit, push, merge or publication was performed.
+
+
+## Review corrections — 2026-09-12
+
+The candidate above is historical and predates three review corrections: external
+subtitle identities no longer alias their per-file stream indices; unrecovered
+fatal mpv end-file events populate the structured session error before notification;
+and caller cancellation is detached at source acceptance, before subscribers run.
+Instance close/destroy retain their internal cancellation authority.
+
+`tests/public-api.mjs` now includes real two-attachment selection and cross-mode
+retention, fatal-event adapter injection for each public mode, and synchronous
+abort-at-sourcechange checks in Native and Software. The existing pre-acceptance
+cancellation, rollback, stale-event and bounded-close checks remain in that suite.
+`tests/public-api-state.mjs` additionally checks external/embedded ID separation.
+New timestamped results and a separate review-fix archive preserve the previous
+candidate and its evidence. The review does not change the release gates above.
+
+Review-fix validation: Chrome 152.0.7977.83 and Firefox 146.0.1 each passed
+20 normalized API cases and 8 clean static/bundled consumer cases. The 6 state
+unit tests and TypeScript build passed. The archive is
+`build/public-api-review-fixes/demuxe-0.3.0-beta.3.tgz`, SHA-256
+`806b07a4c7fc7df8c96781cc69b0f0fa77984f062ec0a51bf8ab0caef700bc42`. Its manifest hashes and generated runtime
+match the working build; the Wasm engines are unchanged. Detailed result hashes
+are in the accompanying `qualification.json`. Broader historical suites were
+not rerun for these targeted core corrections.

package/docs/PUBLIC-API.md

@@ -0,0 +1,245 @@
+# Public API contract
+
+Contract for the public API milestone work. Implementation and qualification are
+tracked separately in PUBLIC-API-VALIDATION.md; this document is not test evidence.
+The baseline is demo-source 8bb451b, present in the working tree on main f9a8f9c.
+
+Player is the sole playback owner. It owns its video/canvas surface, bounded
+source adapters, routing, synchronization, recovery and teardown. There are
+exactly three modes: native, hybrid, software. UI and core imports are separate.
+No arbitrary mpv command interface is exposed.
+
+## Compatibility and additions
+
+Existing: ready, open(File | ArrayBuffer), openRemote, play, pause, seek,
+volume(0–100), rate(0.5–2), selectTrack with backend IDs, subtitleVisible,
+addSubtitle, addTextTrack, addFont, setMode, setAutomaticSelection, filter and
+tone-mapping methods, resize, destroy, properties, diagnostics, mpv events,
+modechange and selectionchange.
+
+Additions: state, subscribe, mediaInfo, typed high-level events, feature
+availability, open(string | URL | RemoteSource), AbortSignal open options,
+setVolume(0–1), setMuted, setPlaybackRate, stable public track selections, close,
+assetBase. These are additive; legacy volume and rate units do not change.
+
+## State and events
+
+state is a deeply frozen snapshot. Its identity remains unchanged until a value
+changes. subscribe(listener) calls the listener immediately and returns an
+idempotent unsubscribe. Updates happen before subscribers and high-level events.
+Ordinary backend property bursts are coalesced in a microtask, with no new worker
+polling. Subscribers must not throw; observer failures do not change playback.
+
+status describes observed idle/paused/playing/buffering/ended/error state;
+playbackIntent describes requested play/pause independently. pendingOperation has
+an increasing instance-local ID and opening/seeking/switching/closing kind.
+activeMode is null without accepted media. Legacy mode remains the configured
+route while idle. Candidate events never replace accepted state. Failed
+replacement reports an operation error and preserves a working session.
+
+Seconds are used throughout. Unknown duration and ranges are null; [] means
+known empty. Byte-cache statistics are never converted into buffered time.
+Native ranges use the browser timeline translated out of remux bias. mpv
+buffered time is unknown; seek ranges use observed demuxer seekable ranges for
+live sources, and confirmed demuxer seekability plus duration for VOD. An unknown
+live window disables a finite seek slider. mediaInfo includes display geometry,
+source rotation when reported, display aspect and selected streams; absent
+metadata stays null. No UI needs mpv property names.
+
+High-level event detail contains the committed state. Source acceptance emits
+sourcechange; subsequent changed fields emit durationchange, trackschange,
+capabilitieschange, volumechange, ratechange and timeupdate. play expresses
+accepted play intent; playing requires observed playback progress, waiting
+observed starvation, pause observed pause, ended EOF. seeking precedes the
+backend seek; seeked occurs only after native seeked or mpv presentation settles.
+statechange follows snapshot publication. modechange retains loading/ready/failed
+candidate phases and selectionchange retains route-attempt detail.
+
+## Completion, cancellation and ownership
+
+open resolves after an accepted paused session loads and its initial output is
+ready. File references are retained; ArrayBuffers are copied and limited to
+32 MiB. Remote options are copied. open accepts {signal}; abort before acceptance
+cancels inspection/candidate work and preserves the previous usable session.
+Abort after acceptance has no effect. Caller-owned text-track URLs remain alive
+until close/source replacement. Fonts have existing bounded instance budgets.
+
+play resolves when the backend accepts playback, not at the first time update.
+Call from a user gesture; resume is initiated in that gesture when no operation
+is pending. Autoplay denial is AUTOPLAY_BLOCKED and never triggers codec fallback.
+pause resolves at observed pause. seek resolves after output settles; it does not
+interrupt active packet reads. There are at most 32 pending core operations.
+Controls preview scrubbing locally and submit a seek on release.
+
+close aborts older queued/in-flight operations, disposes media-specific resources
+and attachments, and leaves a reusable idle instance. It retains configured
+volume/mute/rate, mode policy, filters, tone mapping, output policy and bounded
+fonts. destroy is terminal and idempotent, cancels work, disposes all instance
+resources and removes owned DOM. Pending promises reject predictably. Await
+cleanup before discarding the owner.
+
+Stable track IDs are scoped to a source generation and mapped to backend IDs.
+Source stream indices preserve identity across routes where reported. External
+subtitle files use a separate attachment namespace: their demuxers can share the
+same stream index. Replaying the retained attachments preserves their track IDs. Identity
+that exists only within a backend cannot be guessed across Native/mpv routes;
+explicit selection causes an unsupported-transition rejection. New source IDs
+invalidate previous IDs. null means disabled; 'auto' delegates initial selection.
+Legacy selectTrack retains its documented backend-ID contract.
+
+Errors are PlayerError with code, operationId, operation, scope, retryable and
+redacted message. Session errors alone populate state.error. Failed controls or
+replacement errors are operation-scoped. Codes: INVALID_ARGUMENT, ABORTED,
+AUTOPLAY_BLOCKED, SOURCE_PERMISSION, SOURCE_CHANGED, NETWORK_TIMEOUT,
+UNSUPPORTED_MEDIA, UNSUPPORTED_TIMELINE, UNSUPPORTED_FEATURE, ASSET_LOAD_FAILED, ISOLATION_REQUIRED,
+DECODE_FAILED. Normal events/diagnostics redact authorization fields, URL userinfo,
+queries and fragments; raw mpv properties remain an advanced inspection surface.
+
+## Using normalized state
+
+```ts
+const player = new Player(host, {assetBase: '/assets/demuxe/'});
+const unsubscribe = player.subscribe(state => {
+  render({
+    status: state.status,
+    seconds: state.currentTime,
+    duration: state.duration,
+    seekWindow: state.seekable,
+    audio: state.audioTracks,
+    subtitles: state.subtitleTracks,
+    aspect: state.mediaInfo.aspectRatio,
+    seek: state.capabilities.features.seek,
+  });
+});
+await player.open(file, {signal});
+await player.selectSubtitleTrack(player.state.subtitleTracks[0]?.id ?? null);
+await player.setVolume(.75);
+await player.setMuted(true);
+await player.close();
+unsubscribe();
+await player.destroy();
+```
+
+state.volume is normalized 0–1, configured independently from mute. Legacy
+properties.volume still reflects backend 0–100 output, including zero while
+muted. subtitlesVisible exposes the retained visibility setting independently
+from the selected subtitle identity. player.capabilities includes legacy booleans,
+deployment flags and feature availability; the same object is in the snapshot.
+Feature availability describes request/route eligibility, not a guarantee that
+an untested codec, asset or output device will work. Source-specific timeline and
+track availability remain unknown until established.
+
+The core emits structured operation errors for failed queued controls, while
+synchronous legacy argument validation throws PlayerError. Rejected opens due
+to invalid arguments or a signal already canceled may reject without an event;
+callers must catch returned promises. Observer exceptions are reported through
+the browser's error reporting and cannot veto a committed session. Close reserves
+one teardown slot beyond the 32 ordinary pending-operation limit, so a full queue
+cannot prevent cleanup. Browser resume requests initiated during another queued
+operation may require a fresh user gesture when that operation completes.
+
+Native exposes display dimensions; source rotation/codec metadata can remain null
+when the browser does not report them. Its selected video entry is an opaque
+source-scoped identity and does not imply a browser video-track switching API.
+Live mpv seek windows use the demuxer's reported cached seekable timestamps; a
+byte cache alone never creates a buffered-time claim. High-level time/state
+notifications reuse backend events; only existing seek/presentation settlement
+and engine health mechanisms retain their preexisting polling.
+
+## Experimental playback optimizations
+
+`experimentalBufferedNativeSeeks` and `experimentalHybridAudioFilters` are opt-in
+constructor options, both false by default. Hybrid currently admits only scalar
+`volume=N` / `lavfi=[volume=N]` attenuation for N in [0, 1]. Other filters retain
+Software routing or explicit-mode rejection.
+
+`audioGain` (default 1) and `setAudioGain(value)` request experimental scalar
+attenuation in [0, 1]. All three modes use a dedicated, lazy Web Audio gain stage.
+The setter updates that stage in place, preserving the engine, source, position,
+and pause intent. Hybrid/Software gain follows the mpv PCM output without changing
+the user audio filter chain. Ordinary volume and mute remain separate. Unity on a
+fresh player allocates no gain stage; restoration retains an existing stage.
+Transactional replacement is reserved for backends without an in-place gain method.
+Diagnostics expose `plan` and `audioGain`; feature capabilities include `audioGain`.
+See [current qualification and limitations](OPTIMIZATION-COMPLETION.md).
+
+### Experimental selected-audio FLAC preparation
+
+`experimentalAudioAdaptation: 'flac'` enables explicit Native trials after ordinary
+Native/direct or packet-copy audio is unsuitable. It does not enable automatic
+adaptation. The optional separately built preparation assets must be packaged.
+The tested subset is integer PCM16/24 mono/stereo at 44.1/48 kHz; unsupported
+precision/layouts reject instead of quantizing, downmixing or resampling. Video
+packets are copied. No Opus permission is implied. It supports the separately
+requested `audioGain` operation and external Native ASS, including their combination.
+Long unequal tails have a separate qualified experimental FLAC path for desktop
+Chrome, H264 and PCM16/24. It preserves the final video image while longer audio
+continues, and silence after shorter audio ends. Distant seeks regenerate bounded
+real preroll. Firefox rejects this Native timeline with `UNSUPPORTED_TIMELINE`;
+use an eligible mpv route. On Firefox, a distant seek after video EOF can
+recover from Hybrid through Software, with the failed seek disclosed in diagnostics.
+Use Software explicitly when continuous ASS behavior through a Firefox video-EOF
+audio tail is required; that Hybrid combination is not qualified.
+Opus long tails remain unsupported. See the
+[current qualification and reproductions](../results/optimization-final/README.md).
+
+### Automatic lossless adaptation policy
+
+```js
+const player = new Player(container, {automaticAudioAdaptation: 'lossless'});
+await player.open(file);
+```
+
+This optional policy permits Native FLAC only for inspected local Matroska with
+H264 up to 1080p and selected 48 kHz PCM16/24 mono/stereo audio, with established
+selected-track starts and ends within 50 ms. Original direct/copy playback remains
+preferred. Unsupported sources retain eligible Hybrid/Software alternatives;
+explicit modes remain authoritative. Selecting a different audio track repeats
+admission while preserving its source identity and user intent. External Native
+ASS and gain use their existing options and must form a supported complete plan.
+
+This does not enable Opus, resampling, downmixing, embedded Native subtitles,
+remote automatic adaptation or streaming adaptation. FLAC preserves admitted
+integer decoded samples; it does not restore an earlier lossy recording.
+Diagnostics disclose rejected alternatives and the accepted transformation.
+
+### Experimental Native ASS/SSA
+
+Set `experimentalNativeASS: true` to use external ASS/SSA with Native direct,
+remux or qualified FLAC playback. Use the existing `addSubtitle(file)`,
+`addFont(file)`, `selectSubtitleTrack(id)` and `subtitleVisible(value)` methods.
+Fonts added before opening avoid a later transactional font refresh. Attachments
+are source-scoped and reset on opening a new source. Source-scoped external IDs
+follow attachment order across Native and mpv; they are distinct from embedded
+stream indices. Other subtitle formats and embedded ASS still require mpv.
+
+Install the optional libass assets using the package asset-copy command from a
+package built with `--ass-build`. This feature requires cross-origin isolation.
+Use container fullscreen; video-only fullscreen, PiP and casting cannot carry the
+external overlay. Native PiP/remote-playback controls are disabled for this plan.
+See [current coverage and limits](OPTIMIZATION-COMPLETION.md).
+
+### Experimental selected-audio Opus preparation
+
+`experimentalAudioAdaptation: 'opus'` requires `allowLossyAudio: true` and explicit
+Native mode. It is a separate profile, never a fallback from failed FLAC. The
+qualified input subset is copied H.264 video with selected PCM16/24 mono/stereo at
+48 kHz. Other sample rates/layouts/codecs reject; permission to encode lossily does
+not authorize resampling or downmixing. Original compressed audio remains preferred
+when it can be copied. Opus+gain is supported; Opus+Native ASS is not admitted.
+The matching optional preparation engine includes the pinned FFmpeg Opus encoder.
+No sample-exact claim applies to Opus. See the current coverage document for delay,
+padding, timestamp and marker tests and the unresolved long-tail limit.
+
+### Complete-plan admission diagnostics
+
+`diagnostics.plan` identifies the accepted internal plan without adding a public
+mode. `diagnostics.planAdmission` lists finite candidates with `eligible`, typed
+rejection `code`, and `reason`. Eligibility is permission to attempt the plan;
+actual codec preparation and meaningful startup output must still succeed.
+Automatic routing retains Native copy, authorized qualified Native FLAC, eligible Hybrid, then Software. It
+uses requested effects, source inspection, selected tracks, transport constraints
+and browser prerequisites. The experimental adaptation option remains explicit-only;
+automatic FLAC uses the separate lossless policy above. Route ranking
+does not use prototype benchmark percentages. Explicit mode selection remains
+authoritative. In-place gain updates refresh plan diagnostics without rerouting.