demuxe 0.3.0-beta.3

package/docs/RELEASE.md

@@ -0,0 +1,181 @@
+# Traceable beta release
+
+A release candidate is one archive from a clean tagged revision, built and tested
+as recorded below. A deterministic tar command alone is not an engine build test.
+One clean build of all three engines is required for this developer beta. Universal
+bit-for-bit reproducibility and the historical Linux baseline are separate claims.
+
+## Prerequisites
+
+Install native Python 3, CMake, Ninja, pkg-config, Git, curl and Node.js/npm. On the
+reference macOS host, install the pinned Python build dependencies in the checkout:
+
+```sh
+python3 -m venv build/venv
+build/venv/bin/python -m pip install meson==1.7.2 Jinja2==3.1.6 MarkupSafe==3.0.2
+npm ci
+python3 scripts/fetch-sources.py
+cp -R build/sources/emsdk build/emsdk-4.0.14
+build/emsdk-4.0.14/emsdk install 4.0.14
+build/emsdk-4.0.14/emsdk activate 4.0.14
+```
+
+The installer archive and all library archives are verified against
+`sources.lock.json`. The SDK installs the platform's 4.0.14 compiler tools. This
+macOS recipe does not claim that the historical Linux `toolchain.lock.json` is a
+macOS package lock. The new build record captures actual host tool versions and
+hashes; retain it. `prepare-beta-toolchain.py` generates absolute SDK paths and a
+fresh compiler cache, without inheriting an edited SDK configuration.
+
+For a clean build use a new checkout of the reviewed tag, e.g. a fresh clone with
+`git checkout --detach <tag>`. Install npm/Python dependencies there as above. An
+already installed SDK and verified download archive cache may be shared with that
+checkout, but never share extracted library sources, objects, prefixes or the
+Emscripten cache. Do not run `fetch-sources.py` in that checkout before `--clean`;
+use the prerequisite installation checkout to provision the SDK first.
+
+```sh
+DEMUXE_SDK=/absolute/path/to/installed/emsdk-4.0.14 \
+  bash scripts/build-beta-engines.sh --clean > build/clean-build.log 2>&1
+```
+
+Create `build/` before redirecting the log. The clean flag rejects existing engine
+outputs, extracted sources, dependency prefixes, objects or compiler cache. The
+build verifies locked archives, applies the complete patch series, builds all
+static dependencies and all three engines, and records actual configuration and
+input/output hashes in `build/beta-build.json`. Compiler file-prefix maps and
+normalized generated configuration headers use `/demuxe/` as a virtual build root;
+the npm packager rejects leaked host paths in any runtime file, including Wasm.
+Full host paths remain only in build evidence and the source companion. Inputs may not change during the
+build. Generated tracked bindings must match the tag; otherwise fix the source,
+review and make a new candidate revision.
+
+## Assemble, test and identify the same bytes
+
+Resolve the original-code license and inspect `docs/LICENSING.md` before tagging.
+Use a new version/tag for changed candidate bytes. The release packaging option
+requires a clean tagged revision, clean-build evidence, the original license and
+matching input/configuration/engine hashes. It also produces the source companion.
+
+```sh
+python3 scripts/package-beta.py --release-tag <tag> --output build/release
+BETA_ARCHIVE=/absolute/path/to/build/release/demuxe-<version>.tgz \
+  node tests/beta-consumer.mjs
+BROWSER=firefox BETA_ARCHIVE=/absolute/path/to/build/release/demuxe-<version>.tgz \
+  node tests/beta-consumer.mjs
+BETA_ARCHIVE=/absolute/path/to/build/release/demuxe-<version>.tgz \
+  node tests/beta-streaming.mjs
+BROWSER=firefox BETA_ARCHIVE=/absolute/path/to/build/release/demuxe-<version>.tgz \
+  node tests/beta-streaming.mjs
+```
+
+The browser tests require Playwright's Firefox and local Chrome, and repository
+fixtures created by the documented fixture generators. The focused streaming test
+uses `build/fixtures/playback-performance/bbb-stream.mp4` by default, or
+`STREAMING_FIXTURE` pointing to a seekable H.264/AAC MP4 longer than 500 seconds.
+It records that fixture's hash. Keep fixture-generation/source provenance with the
+results. Tests use only the extracted runtime archive, and verify all manifest
+hashes before running. Consumer results include the archive's SHA-256.
+
+Extract that same archive and run the deterministic timeout regressions against it:
+
+```sh
+mkdir -p build/release/extracted
+tar -xzf build/release/demuxe-<version>.tgz -C build/release/extracted
+RANGE_READER_MODULE="$PWD/build/release/extracted/package/web/range-reader.js" \
+  node --test tests/range-reader-deadline.mjs
+```
+
+Record result paths and archive hashes in the release verification record. Recheck
+both archive hashes immediately before distribution. Publish the tested runtime,
+matching source companion, SHA256SUMS and verification record together. Packaging
+creates a candidate; publication still requires the test results to pass and the
+actual distribution/license arrangement to be settled. Never rebuild an archive
+after testing and reuse the earlier test results for it.
+
+Use the verifier to require both complete browser suites and run the deadline tests
+against the archived reader, then write the final verification record:
+
+```sh
+python3 scripts/verify-beta-release.py \
+  --archive build/release/demuxe-<version>.tgz \
+  --source build/release/demuxe-<version>-source.tar.gz \
+  --consumer <chrome-consumer-result.json> <firefox-consumer-result.json> \
+  --streaming <chrome-streaming-result.json> <firefox-streaming-result.json> \
+  --extra <release-extra-result.json>
+```
+
+A changed runtime hash, source companion, tagged test harness, failed test, filtered
+suite, or missing browser result prevents verification. Archive assembly does not
+publish anything; distribute the verified files without running the packager again.
+
+## Optional preparation and ASS runtimes
+
+When shipping the optional runtimes, pass their verified build directories to the
+same tagged packager with `--adaptation-build <engine-directory>` and
+`--ass-build <runtime-directory>`. Keep both optional source companions and their
+hashes alongside the standard source companion. See
+[Runtime assets](RUNTIME-ASSETS.md) for the pinned builds and asset-copy contract.
+
+Run the optional matrix against the immutable tagged archive:
+
+```sh
+python3 scripts/qualify-optional-runtime.py \
+  --archive <tagged-runtime.tgz> \
+  --adaptation-build <engine-directory> \
+  --ass-build <runtime-directory> \
+  --output <fresh-qualification-directory>
+```
+
+Supply `--optional <fresh-qualification-directory>/qualification.json` to
+`verify-beta-release.py`, alongside all standard consumer, transport and extra
+results. Optional evidence from an earlier untagged archive cannot qualify a new
+release archive. Qualification preserves the documented browser and source gates;
+it does not admit Firefox Native long unequal tails or staged streaming adaptation.
+
+## Current component and npm consumer qualification
+
+After the four archive suites above, run the full additional qualification against
+that same archive. This installs into an empty project, invokes the npm executable,
+checks package metadata and imports without a DOM, records npm's pack inventory,
+and runs CLI collision/hash checks, TypeScript/static/bundled consumers, public API,
+component, and menu regressions. The UI/API test server serves runtime code strictly
+from the installed archive; only test pages and media come from the tagged source.
+
+```sh
+BETA_ARCHIVE="$PWD/build/release/demuxe-0.3.0-beta.3.tgz" node tests/release-extra.mjs
+```
+
+Pass `--extra <release-extra-result.json>` to `verify-beta-release.py`, in addition
+to its archive/source/consumer/streaming arguments. It requires all extra cases and
+checks their harness hashes against the source companion. Provision esbuild 0.28.2
+in `build/public-api-tooling` for the bundled consumer checks. Component fixtures
+use `fixtures/example.mp4`; the menu suite also runs in automated WebKit without
+claiming Safari or physical mobile qualification.
+
+## First npm publication
+
+The root `package.json` deliberately remains `private: true`. Never publish from
+the source root. Publish only the runtime archive identified by `verification.json`;
+do not rebuild or repack it after qualification. Keep the source companion,
+`SHA256SUMS`, clean build record and verification record with the public release.
+Before npm publication, make the matching source companion downloadable from the
+GitHub release for the recorded tag; the npm package alone is not that source offer.
+
+1. Confirm `npm whoami`, account publishing access/2FA, and `demuxe` name
+   availability or ownership (`npm view demuxe name version maintainers`).
+2. Check archive metadata and `SHA256SUMS` against `verification.json`.
+3. Run `npm publish ./build/release/demuxe-0.3.0-beta.3.tgz --tag beta --access public --dry-run`.
+4. Only after all verification gates pass, explicitly publish:
+
+```sh
+npm publish ./build/release/demuxe-0.3.0-beta.3.tgz --tag beta --access public
+```
+
+Do not use `latest` for this beta. After publication, install `demuxe@beta` into
+a brand-new temporary project, run `npx demuxe copy-assets public/assets/demuxe`,
+import both `demuxe` and `demuxe/player`, and smoke-test one Native direct source
+and one Hybrid/Software or Native-remux source using the installed runtime assets.
+Check `npm view demuxe@beta version dist` and download the registry tarball to
+compare its bytes/hash to the qualified archive. Once this first version exists,
+configure npm trusted publishing for the exact GitHub workflow used for later releases.

package/docs/RUNTIME-ASSETS.md

@@ -0,0 +1,127 @@
+# Runtime assets and package integration
+
+The assetBase/copy-assets interfaces are implemented in this working candidate.
+The project is not yet published to npm. Install the locally assembled archive:
+
+```sh
+npm run build
+python3 scripts/package-beta.py --output build/my-candidate
+# In a clean application:
+npm install /absolute/path/to/demuxe-0.3.0-beta.3.tgz
+npx demuxe copy-assets public/assets/demuxe
+```
+
+```js
+import {Player} from 'demuxe';
+const player = new Player(container, {assetBase:'/assets/demuxe/'});
+// Optional, separate UI entry:
+import {definePlayerElement} from 'demuxe/player';
+definePlayerElement();
+```
+
+```html
+<demuxe-player controls asset-base="/assets/demuxe/"></demuxe-player>
+```
+
+assetBase is the package runtime root containing web/, fixtures/, third_party/
+and LICENSE. Its trailing slash is normalized. It is resolved against the page
+base URL; same-origin HTTP(S) is required. The old static-directory installation
+works without assetBase when generated modules retain their package paths.
+Bundled applications should always provide assetBase. All inspector/worker entry
+points, nested workers, engine modules/Wasm, AudioWorklet and fonts follow the
+copied tree. Route-dependent loading is retained; core import and construction
+perform no engine downloads. Import during SSR is safe; construction is browser-only.
+The UI entry does not register anything until definePlayerElement is called.
+
+copy-assets validates every package manifest hash before copying runtime assets,
+font and notices. It writes demuxe-runtime.json with version and hashes. It never
+deletes destination files; unrelated collisions and symlink paths reject. Updates
+may replace only previous manifest-owned unmodified assets. Retain the generated
+manifest with the installation. Use core and runtime from the same archive; mixing
+releases or experimental presenters is unsupported. Failed copies should be rerun
+from an intact package; use a versioned destination for atomic application rollout.
+
+Serve JS/mjs as text/javascript, Wasm as application/wasm and fonts with font/ttf.
+Worker routes require a secure context and COOP: same-origin plus COEP: require-corp.
+Native direct can work without isolation. Media must satisfy CORS, range/identity
+and source allowlist requirements. CSP must permit same-origin module scripts and
+workers, Wasm compilation (wasm-unsafe-eval), same-origin worker-owner iframes,
+AudioWorklet, fonts and authorized media/connect origins. Native local/remux media
+needs media-src blob:. Component styles use a shadow style element; deployments
+with strict style-src need an appropriate hash or policy for those shipped styles.
+No consumer service worker is installed. The Pages isolation worker is demo-only.
+Arbitrary CDN worker roots, Safari/mobile, PiP/casting and physical output fidelity
+remain separate qualification gates. See LICENSING.md and RELEASE.md for source
+and clean-engine-build obligations; this integration does not close them.
+
+## Optional experimental audio preparation
+
+Local candidates built with `scripts/package-beta.py --adaptation-build <versioned-engine-dir>`
+include `web/engine-adaptation/remux.mjs`, its matching `remux.wasm`, and a hash/inputs
+manifest. The standard asset-copy CLI validates and copies them with the rest of
+the runtime. Default packages omit these assets; ordinary Native playback does not
+load them. A separately hashed `demuxe-audio-adaptation-source.tar.gz` accompanies
+that candidate. This profile follows the saved FFmpeg modernization pins and does
+not reuse the historical scratch LibAV binary. Preparation ABI 2 requires matching
+worker, JavaScript and Wasm; mixing earlier optional binaries is rejected. Release
+verification requires clean source correspondence and exact-archive optional tests;
+see [current profiles, qualification and source limitations](OPTIMIZATION-COMPLETION.md).
+Opus-enabled builds declare that profile in their manifest; Player still requires
+explicit lossy permission. No package option enables automatic adaptation.
+
+
+## Optional external Native ASS
+
+Pass `--ass-build <versioned-ass-dir>` for the pinned libass wrapper and matching
+`web/engine-ass/subtitles.mjs` / `subtitles.wasm`. The worker is lazy, and the same
+asset-copy CLI copies and verifies its manifest, default font and notices. The
+separate `demuxe-native-ass-source.tar.gz` contains wrapper/build inputs and preferred
+library sources. Both optional source companions are listed in SHA256SUMS when
+packaged together. Their presence alone is not proof of source correspondence. Packaging verifies the
+clean library/source record, and release verification requires the exact-archive
+optional matrix plus all existing clean tagged-source and standard release gates. See the current optimization coverage report.
+
+### Isolated Native ASS build
+
+`scripts/build-native-ass.py` builds only the four pinned subtitle libraries and
+links the optional worker in a fresh output directory. It verifies the input
+archives against `sources.lock.json`, uses a private Emscripten cache and prefix,
+and records commands, source/library hashes and host tool identities. Existing
+checkouts and library archives are read-only inputs; no playback engine is rebuilt.
+
+```sh
+python3 scripts/build-native-ass.py --sdk /path/to/emsdk-4.0.14 \
+  --archives /path/to/verified-downloads --meson /path/to/meson \
+  --output build/native-ass-clean
+python3 scripts/verify-native-ass-build.py build/native-ass-clean/runtime
+python3 scripts/package-beta.py --output build/optional-candidate \
+  --ass-build build/native-ass-clean/runtime
+python3 tests/native-ass-source-build.py
+```
+
+The archive directory must contain `freetype.tar.gz`, `fribidi.tar.gz`,
+`harfbuzz.tar.gz`, and `libass.tar.gz` matching the unchanged source lock. The
+builder refuses an existing output directory. Use a second fresh output to compare
+runtime and library hashes. The historical Linux toolchain lock is not evidence
+for a macOS build; the source-build record declares that distinction.
+
+For clean builds, packaging verifies the source-build record before copying assets
+and includes it and the isolated builder in the source companion. Installed asset
+tests verify the companion's preferred sources and wrapper against those hashes.
+A passing local correspondence check does not authorize release packaging; the
+existing tagged-source, full-consumer and streaming release gates still apply.
+
+## Exact-archive optional qualification
+
+Run `scripts/qualify-optional-runtime.py --archive <candidate.tgz>
+--ass-build <clean-ass/runtime> --adaptation-build <clean-preparation/engine>
+--output <fresh-directory>`. It verifies matching source builds and tests installed
+assets, consumers, automatic admission, subtitles, filters/gain, FLAC/Opus fidelity,
+lifecycle and the documented unequal-tail browser policy. Failed runs are retained.
+
+The standard `scripts/verify-beta-release.py` requires `--optional
+<qualification.json>` whenever either optional engine is packaged. It checks the
+archive, runtime inventory, required Chrome/Firefox matrix, tagged harness hashes,
+log hashes and source-companion hashes. This adds a gate; it does not replace clean
+source/tag, engine build, streaming, consumer or extra release requirements. No
+qualification script creates tags or publishes. See the current closeout evidence.