diff --git a/.config/nextest.toml b/.config/nextest.toml index 1037b2310..fd2a37223 100644 --- a/.config/nextest.toml +++ b/.config/nextest.toml @@ -1,7 +1,6 @@ # cargo-nextest (https://nexte.st) runs every test in its own process, in parallel across test -# binaries. The Windows leg of the Workspace gate uses it (.github/workflows/workspace.yml); every -# other leg, and local runs, keep `cargo test`. Nextest does not run doctests, so the Windows leg -# also runs `cargo test --doc`. +# binaries. Every leg of the Workspace gate uses it (.github/workflows/workspace.yml); local runs may +# keep `cargo test`. Nextest does not run doctests, so the gate also runs `cargo test --doc`. # # cargo nextest run --workspace --profile ci # cargo test --workspace --doc @@ -22,10 +21,9 @@ video-fixtures = { max-threads = 1 } # craft-print: `PRINT_TICKET_PROVIDER` serializes the Windows PrintTicket provider, and the tests # share the one test print queue the gate installs. print = { max-threads = 1 } - -[[profile.default.overrides]] -filter = 'package(craft-ui) & (binary(visual_regression) | test(/^combo::tests::|selected_tab_erases_a_baseline_centered_on_its_bottom_edge/))' -test-group = 'gpu' +# craft-video integration tests on Linux and macOS: the binaries generate and read the same fixture +# directories (see the `ci` overrides below). +video-integration = { max-threads = 1 } [[profile.default.overrides]] filter = 'package(craft-video) & binary(h264_decode)' @@ -42,3 +40,44 @@ test-group = 'print' fail-fast = false slow-timeout = { period = "60s" } failure-output = "immediate-final" + +# Linux and macOS (the resource audit in craft-libs#2058): every GPU consumer shares the one `gpu` +# slot, and the craft-video integration binaries share their fixture directories. Conservative on +# purpose: the in-process mutexes these tests rely on do not reach across nextest's processes. +# Windows keeps the default groups above, which its leg has passed with since it moved to nextest. +[[profile.ci.overrides]] +platform = 'cfg(unix)' +filter = 'package(craft-ui) | package(craft-keymap) | package(craft-update)' +test-group = 'gpu' + +[[profile.ci.overrides]] +platform = 'cfg(unix)' +filter = 'package(craft-video) & kind(test)' +test-group = 'video-integration' + +# Slowest tests first (priority runs higher values earlier), so the longest ones start at the +# beginning of the run instead of holding the tail. Every test that took over 30 s in the gate's +# run on next (run 44318177438, Linux); the first tier is the one over 60 s. +[[profile.ci.overrides]] +filter = '(package(craft-media) & test(=mxf::tests::hostile::hostile_input_never_panics)) | (package(craft-table) & test(/CellGrid.*::drives$/)) | (package(craft-proto) & test(=imap::gmail_labels_tests::a_mailbox_claimed_huge_cant_fill_memory_with_flags))' +priority = 20 + +[[profile.ci.overrides]] +filter = ''' +(package(craft-design-lint) & test(=mapped_crates_have_no_findings)) +| (package(craft-ui-widgets) & test(/SwatchTable.*::activation$/)) +| (package(craft-table) & test(/CellGrid.*::activation$/)) +| (package(craft-pkcs7) & test(=crypto::new_digital_ids_are_self_signed_and_survive_a_p12_round_trip)) +| (package(craft-image-codecs) & test(=tiff_bands::a_blank_fax_page_wider_than_4096_px_passes_the_bomb_guard)) +| (package(craft-image-codecs) & test(=codecs::png::streamed_tests::streamed_rows_match_the_whole_image_encoder)) +| (package(craft-image-codecs) & test(=codecs::png::parallel_tests::the_parallel_encoder_gives_the_same_bytes_on_any_thread_count)) +| (package(craft-image-codecs) & test(=limits::highly_compressible_jpeg_and_gif_still_decode)) +| (package(craft-color-ui) & test(=integration::sampling::an_invalid_capture_ends_the_pick_with_a_status)) +| (package(craft-docx) & test(=read::chart::tests::hostile_radar_charts_never_panic)) +| (package(craft-drawingml) & test(=chart::chartex_tests::large_box_hierarchy_and_stacked_charts_take_linear_work)) +| (package(craft-audio) & test(=integration::flac_decode::hostile_input_is_an_error_not_a_panic)) +| (package(craft-docx) & test(=comment_save_cost::many_comments_save_without_quadratic_id_searches)) +| (package(craft-ui-widgets) & test(/menu::popup::Menu.*::activation$/)) +| (package(craft-scraft-format) & test(=b64::tests::size_cap_counts_the_partial_quartet)) +''' +priority = 10 diff --git a/.gitattributes b/.gitattributes index 0c35cf7c5..00c1fc249 100644 --- a/.gitattributes +++ b/.gitattributes @@ -17,3 +17,16 @@ crates/fonts-build/tests/fixture/craft-fonts/fonts/**/OFL.txt -text # DXF drawing goldens assert exact writer bytes, including LF on every platform. crates/dxf/tests/data/drawing_*.dxf -text + +# The generated components index is compared byte for byte with the generator's LF output (craft-ui test +# components_index): a Windows checkout must not convert its line endings. +docs/components-index.md text eol=lf + +# The built-in size files are compared byte for byte with the writer's LF output (craft-theme sizes_tests), and the +# token dumps with the dump writer's (craft-theme dumps test): a Windows checkout must not convert their line endings. +crates/theme/sizes/*.json text eol=lf +crates/theme/tests/dumps/** text eol=lf + +# The facade's [features] table is compared with the table the craft features test writes, with LF (craft test +# integration::features): a Windows checkout must not convert its line endings. +crates/craft/Cargo.toml text eol=lf diff --git a/.github/workflows/actions.lock b/.github/workflows/actions.lock index 02cdf71c8..496d685c3 100644 --- a/.github/workflows/actions.lock +++ b/.github/workflows/actions.lock @@ -18,7 +18,6 @@ workflows: - 'actions/checkout@v7.0.1' - 'step-security/dtolnay-rust-toolchain@v1.0.0' - 'step-security/harden-runner@v2.22.4' - - 'step-security/rust-cache@v2.9.2' '.github/workflows/cms.yml': - 'actions/checkout@v4.4.0' - 'dtolnay/rust-toolchain@stable' @@ -27,7 +26,6 @@ workflows: - 'actions/checkout@v7.0.1' - 'step-security/dtolnay-rust-toolchain@v1.0.0' - 'step-security/harden-runner@v2.22.4' - - 'step-security/rust-cache@v2.9.2' '.github/workflows/dialogs.yml': - 'actions/checkout@v7.0.1' - 'step-security/dtolnay-rust-toolchain@v1.0.0' @@ -36,10 +34,10 @@ workflows: - 'actions/checkout@v7.0.1' - 'step-security/dtolnay-rust-toolchain@v1.0.0' - 'step-security/harden-runner@v2.22.4' - '.github/workflows/docpath.yml': + '.github/workflows/docs.yml': - 'actions/checkout@v7.0.1' - 'step-security/dtolnay-rust-toolchain@v1.0.0' - - 'step-security/harden-runner@v2.22.4' + - 'step-security/rust-cache@v2.9.2' '.github/workflows/ecproj-format.yml': - 'actions/checkout@v7.0.1' - 'step-security/dtolnay-rust-toolchain@v1.0.0' @@ -52,22 +50,16 @@ workflows: - 'actions/checkout@v7.0.1' - 'dtolnay/rust-toolchain@stable' - 'step-security/harden-runner@v2.22.4' - - 'swatinem/rust-cache@v2.9.3' + '.github/workflows/full-validation.yml': [] '.github/workflows/house-rules.yml': [] - '.github/workflows/i18n.yml': - - 'actions/checkout@v7.0.1' - - 'step-security/dtolnay-rust-toolchain@v1.0.0' - - 'step-security/harden-runner@v2.22.4' '.github/workflows/jpeg.yml': - 'actions/checkout@v7.0.1' - 'step-security/dtolnay-rust-toolchain@v1.0.0' - 'step-security/harden-runner@v2.22.4' - - 'step-security/rust-cache@v2.9.2' '.github/workflows/keymap.yml': - 'actions/checkout@v7.0.1' - 'step-security/dtolnay-rust-toolchain@v1.0.0' - 'step-security/harden-runner@v2.22.4' - - 'step-security/rust-cache@v2.9.2' '.github/workflows/lockfile.yml': - 'actions/checkout@v7.0.1' - 'step-security/harden-runner@v2.22.4' @@ -75,11 +67,10 @@ workflows: - 'actions/checkout@v7.0.1' - 'step-security/dtolnay-rust-toolchain@v1.0.0' - 'step-security/harden-runner@v2.22.4' - - 'step-security/rust-cache@v2.9.2' '.github/workflows/menu.yml': - 'actions/checkout@v7.0.1' - 'dtolnay/rust-toolchain@stable' - - 'swatinem/rust-cache@v2.9.3' + '.github/workflows/nightly.yml': [] '.github/workflows/pcraft-format.yml': - 'actions/checkout@v7.0.1' - 'step-security/dtolnay-rust-toolchain@v1.0.0' @@ -89,23 +80,15 @@ workflows: - 'actions/setup-python@v7.1.0' - 'step-security/dtolnay-rust-toolchain@v1.0.0' - 'step-security/harden-runner@v2.22.4' - - 'step-security/rust-cache@v2.9.2' - 'step-security/taiki-e-install-action@v2.87.32' - '.github/workflows/print.yml': - - 'actions/checkout@v7.0.1' - - 'step-security/dtolnay-rust-toolchain@v1.0.0' - - 'step-security/harden-runner@v2.22.4' '.github/workflows/proof.yml': - 'actions/checkout@v7.0.1' - 'step-security/dtolnay-rust-toolchain@v1.0.0' - 'step-security/harden-runner@v2.22.4' - - 'step-security/rust-cache@v2.9.2' '.github/workflows/sonarcloud.yml': [] - '.github/workflows/ui.yml': + '.github/workflows/theme.yml': - 'actions/checkout@v7.0.1' - 'step-security/dtolnay-rust-toolchain@v1.0.0' - - 'step-security/harden-runner@v2.22.4' - - 'step-security/rust-cache@v2.9.2' '.github/workflows/update.yml': - 'actions/checkout@v7.0.1' - 'step-security/dtolnay-rust-toolchain@v1.0.0' @@ -118,7 +101,6 @@ workflows: - 'actions/checkout@v7.0.1' - 'step-security/dtolnay-rust-toolchain@v1.0.0' - 'step-security/harden-runner@v2.22.4' - - 'step-security/rust-cache@v2.9.2' '.github/workflows/web-api.yml': - 'actions/checkout@v7.0.1' - 'step-security/dtolnay-rust-toolchain@v1.0.0' @@ -128,7 +110,6 @@ workflows: - 'actions/checkout@v7.0.1' - 'step-security/dtolnay-rust-toolchain@v1.0.0' - 'step-security/harden-runner@v2.22.4' - - 'step-security/rust-cache@v2.9.2' - 'step-security/taiki-e-install-action@v2.87.32' '.github/workflows/window.yml': - 'actions/checkout@v7.0.1' diff --git a/.github/workflows/ai-core.yml b/.github/workflows/ai-core.yml index 96e2c8474..6f5b34e89 100644 --- a/.github/workflows/ai-core.yml +++ b/.github/workflows/ai-core.yml @@ -12,20 +12,17 @@ permissions: contents: read concurrency: - # Pull requests share one group per branch, so a newer push cancels the older run. Every other - # run (main, manual) gets a group of its own, so it is neither cancelled nor replaced while queued. - group: ai-core-${{ github.event_name == 'pull_request' && github.ref || github.run_id }} - cancel-in-progress: ${{ github.event_name == 'pull_request' }} + # One group per pull request and per branch: a newer push cancels the run it supersedes, on main + # too, since the newest run checks everything before it. + group: ai-core-${{ github.ref }} + cancel-in-progress: true +# fmt, clippy and the tests run in the Workspace gate on every OS; this checks what it does not. jobs: ai-core: + name: AI model WASM timeout-minutes: 15 - strategy: - fail-fast: false - matrix: - # macOS runners are kept for releases: macOS runs only when started by hand. - os: ${{ github.event_name == 'workflow_dispatch' && fromJSON('["ubuntu-latest","windows-latest","macos-latest"]') || github.ref == 'refs/heads/next' && fromJSON('["ubuntu-latest"]') || fromJSON('["ubuntu-latest","windows-latest"]') }} - runs-on: ${{ matrix.os }} + runs-on: ubuntu-latest steps: - name: Harden runner uses: step-security/harden-runner@v2.22.4 @@ -35,15 +32,6 @@ jobs: - uses: step-security/dtolnay-rust-toolchain@v1.0.0 with: toolchain: stable - components: rustfmt, clippy targets: wasm32-unknown-unknown - - run: cargo fmt --check - - run: cargo clippy -p craft-ai-core --all-targets --locked -- -D warnings - - name: Docs (links and missing docs) - if: runner.os == 'Linux' - run: cargo doc -p craft-ai-core --no-deps --locked - env: - RUSTDOCFLAGS: -D warnings - - run: cargo test -p craft-ai-core --locked # The model promises to compile for the web. - run: cargo check -p craft-ai-core --target wasm32-unknown-unknown --locked diff --git a/.github/workflows/atomic.yml b/.github/workflows/atomic.yml index dedfcf161..b7e1ece7c 100644 --- a/.github/workflows/atomic.yml +++ b/.github/workflows/atomic.yml @@ -12,20 +12,17 @@ permissions: contents: read concurrency: - # Pull requests share one group per branch, so a newer push cancels the older run. Every other - # run (main, manual) gets a group of its own, so it is neither cancelled nor replaced while queued. - group: atomic-${{ github.event_name == 'pull_request' && github.ref || github.run_id }} - cancel-in-progress: ${{ github.event_name == 'pull_request' }} + # One group per pull request and per branch: a newer push cancels the run it supersedes, on main + # too, since the newest run checks everything before it. + group: atomic-${{ github.ref }} + cancel-in-progress: true +# fmt, clippy and the tests run in the Workspace gate on every OS; this runs what it does not. jobs: atomic: + name: Atomic inherited Linux ACLs timeout-minutes: 15 - strategy: - fail-fast: false - matrix: - # macOS runners are kept for releases: macOS runs only when started by hand. - os: ${{ github.event_name == 'workflow_dispatch' && fromJSON('["ubuntu-latest","windows-latest","macos-latest"]') || github.ref == 'refs/heads/next' && fromJSON('["ubuntu-latest"]') || fromJSON('["ubuntu-latest","windows-latest"]') }} - runs-on: ${{ matrix.os }} + runs-on: ubuntu-latest steps: - name: Harden runner uses: step-security/harden-runner@v2.22.4 @@ -35,20 +32,9 @@ jobs: - uses: step-security/dtolnay-rust-toolchain@v1.0.0 with: toolchain: stable - components: rustfmt, clippy - name: Install ACL tools - if: runner.os == 'Linux' run: sudo apt-get update && sudo apt-get install -y acl - - run: cargo fmt --check - - run: cargo clippy -p craft-atomic -p craft-settings --all-targets --locked -- -D warnings - - name: Docs (links and missing docs) - if: runner.os == 'Linux' - run: cargo doc -p craft-atomic -p craft-settings --no-deps --locked - env: - RUSTDOCFLAGS: -D warnings - - run: cargo test -p craft-atomic -p craft-settings --locked -- --nocapture - name: Check inherited Linux ACLs - if: runner.os == 'Linux' run: cargo test -p craft-atomic --locked -- --ignored --nocapture wasm: diff --git a/.github/workflows/audio.yml b/.github/workflows/audio.yml index 62c380e2d..6063c4e4d 100644 --- a/.github/workflows/audio.yml +++ b/.github/workflows/audio.yml @@ -11,17 +11,22 @@ on: permissions: contents: read +# A fraction of the fuzz-style cases, as in the Workspace gate; nightly.yml runs them in full. +env: + CRAFT_HOSTILE_DIVISOR: "8" + PROPTEST_CASES: "64" + concurrency: - # Pull requests share one group per branch, so a newer push cancels the older run. Every other - # run (main, manual) gets its own group: it is never cancelled or replaced while queued, so it - # always gets to save the cache. - group: shared-audio-${{ github.event_name == 'pull_request' && github.ref || github.run_id }} - cancel-in-progress: ${{ github.event_name == 'pull_request' }} + # One group per pull request and per branch: a newer push cancels the run it supersedes, on main + # too, since the newest run checks everything before it. + group: shared-audio-${{ github.ref }} + cancel-in-progress: true jobs: lint: timeout-minutes: 15 - name: Audio lint, feature sets, docs, WASM + # fmt, clippy with all features and the minimum Rust version run in the Workspace gate. + name: Audio feature sets, docs, WASM runs-on: ubuntu-latest steps: - name: Harden runner @@ -34,13 +39,8 @@ jobs: - uses: step-security/dtolnay-rust-toolchain@v1.0.0 with: toolchain: stable - components: rustfmt, clippy + components: clippy targets: wasm32-unknown-unknown - - uses: step-security/rust-cache@v2.9.2 - with: - key: craft-audio-lint - save-if: ${{ github.ref == 'refs/heads/main' }} - - run: cargo fmt -p craft-audio --check # Each feature on its own, so code that needs another feature fails here. - name: Clippy, each feature alone run: | @@ -49,7 +49,6 @@ jobs: cargo clippy -p craft-audio --all-targets --locked --no-default-features ${f:+--features "$f"} -- -D warnings echo "::endgroup::" done - - run: cargo clippy -p craft-audio --all-targets --locked --all-features -- -D warnings # missing_docs is a warning in the crate; -D warnings makes it (and broken links) fail here. - run: cargo doc -p craft-audio --all-features --no-deps --locked env: @@ -63,25 +62,6 @@ jobs: RUSTDOCFLAGS: "-D warnings" - run: cargo check -p craft-audio --all-features --locked --target wasm32-unknown-unknown - run: cargo check -p craft-audio --no-default-features --features lossless-encode --locked --target wasm32-unknown-unknown - msrv: - timeout-minutes: 10 - name: Audio on the minimum Rust version - runs-on: ubuntu-latest - steps: - - name: Harden runner - uses: step-security/harden-runner@v2.22.4 - with: - egress-policy: audit - - uses: actions/checkout@v7.0.1 - with: - persist-credentials: false - # The workspace's rust-version. - - run: rustup toolchain install 1.95.0 --profile minimal - - uses: step-security/rust-cache@v2.9.2 - with: - key: craft-audio-msrv - save-if: ${{ github.ref == 'refs/heads/main' }} - - run: cargo +1.95.0 check -p craft-audio -p craft-media --all-features --locked features: timeout-minutes: 10 name: Audio tests without symphonia and lossless-encode only @@ -97,10 +77,6 @@ jobs: - uses: step-security/dtolnay-rust-toolchain@v1.0.0 with: toolchain: stable - - uses: step-security/rust-cache@v2.9.2 - with: - key: craft-audio-features - save-if: ${{ github.ref == 'refs/heads/main' }} - run: cargo test -p craft-audio --no-default-features --features lossless-encode --locked - run: cargo test -p craft-audio --no-default-features --features pcm-encode --locked --lib - run: cargo test -p craft-audio --no-default-features --features flac-encode --locked --lib @@ -122,10 +98,6 @@ jobs: - uses: step-security/dtolnay-rust-toolchain@v1.0.0 with: toolchain: stable - - uses: step-security/rust-cache@v2.9.2 - with: - key: craft-audio-test - save-if: ${{ github.ref == 'refs/heads/main' }} - uses: actions/cache@v6.1.0 with: path: ${{ runner.temp }}/media-fixtures/opus/vectors diff --git a/.github/workflows/cms.yml b/.github/workflows/cms.yml index 2bb99686a..c18aecb27 100644 --- a/.github/workflows/cms.yml +++ b/.github/workflows/cms.yml @@ -11,6 +11,13 @@ on: permissions: contents: read +concurrency: + # One group per pull request and per branch: a newer push cancels the run it supersedes, on main + # too, since the newest run checks everything before it. + group: cms-${{ github.ref }} + cancel-in-progress: true + +# clippy and the debug tests run in the Workspace gate; this runs the release build of the tests. jobs: cms: timeout-minutes: 20 @@ -18,9 +25,6 @@ jobs: steps: - uses: actions/checkout@v4.4.0 - uses: dtolnay/rust-toolchain@stable - with: - components: clippy - - run: cargo clippy -p craft-cms --all-targets --all-features --locked -- -D warnings # Release: the FOGRA39 fit and ink-limit tests take about 35 s in debug and 4 s here. Tests that need # installed system profiles print "skipped:" when none are present. - run: cargo test -p craft-cms --all-features --release --locked -- --nocapture diff --git a/.github/workflows/crw.yml b/.github/workflows/crw.yml index 59c7395f2..1d2b4f389 100644 --- a/.github/workflows/crw.yml +++ b/.github/workflows/crw.yml @@ -12,46 +12,13 @@ permissions: contents: read concurrency: - # Pull requests share one group per branch, so a newer push cancels the older run. Every other - # run (main, manual) gets its own group: it is never cancelled or replaced while queued, so it - # always gets to save the cache. - group: shared-crw-${{ github.event_name == 'pull_request' && github.ref || github.run_id }} - cancel-in-progress: ${{ github.event_name == 'pull_request' }} + # One group per pull request and per branch: a newer push cancels the run it supersedes, on main + # too, since the newest run checks everything before it. + group: shared-crw-${{ github.ref }} + cancel-in-progress: true +# fmt, clippy and the tests run in the Workspace gate on every OS; this checks what it does not. jobs: - native: - timeout-minutes: 20 - name: CRW lint and tests (${{ matrix.os }}) - strategy: - fail-fast: false - matrix: - os: ${{ github.ref == 'refs/heads/next' && fromJSON('["ubuntu-latest"]') || fromJSON('["ubuntu-latest","windows-latest"]') }} - runs-on: ${{ matrix.os }} - steps: - - name: Harden runner - uses: step-security/harden-runner@v2.22.4 - with: - egress-policy: audit - - uses: actions/checkout@v7.0.1 - with: - persist-credentials: false - - uses: step-security/dtolnay-rust-toolchain@v1.0.0 - with: - toolchain: stable - components: rustfmt, clippy - - uses: step-security/rust-cache@v2.9.2 - with: - key: craft-crw-${{ matrix.os }} - save-if: ${{ github.ref == 'refs/heads/main' }} - - run: cargo fmt -p craft-crw --check - - run: cargo clippy -p craft-crw --all-targets --locked -- -D warnings - - name: Docs (links and missing docs) - if: runner.os == 'Linux' - run: cargo doc -p craft-crw --no-deps --locked - env: - RUSTDOCFLAGS: -D warnings - - run: cargo test -p craft-crw --locked - wasm: timeout-minutes: 10 name: CRW WASM @@ -68,10 +35,6 @@ jobs: with: toolchain: stable targets: wasm32-unknown-unknown - - uses: step-security/rust-cache@v2.9.2 - with: - key: craft-crw-wasm - save-if: ${{ github.ref == 'refs/heads/main' }} - run: cargo check -p craft-crw --locked --target wasm32-unknown-unknown samples: @@ -89,10 +52,6 @@ jobs: - uses: step-security/dtolnay-rust-toolchain@v1.0.0 with: toolchain: stable - - uses: step-security/rust-cache@v2.9.2 - with: - key: craft-crw-samples - save-if: ${{ github.ref == 'refs/heads/main' }} - name: Cache the CC0 sample files uses: actions/cache@v6.1.0 with: diff --git a/.github/workflows/dialogs.yml b/.github/workflows/dialogs.yml index c71de9f0a..f9ab8fe56 100644 --- a/.github/workflows/dialogs.yml +++ b/.github/workflows/dialogs.yml @@ -12,10 +12,10 @@ permissions: contents: read concurrency: - # Pull requests share one group per branch, so a newer push cancels the older run. Every other - # run (main, manual) gets a group of its own, so it is neither cancelled nor replaced while queued. - group: dialogs-${{ github.event_name == 'pull_request' && github.ref || github.run_id }} - cancel-in-progress: ${{ github.event_name == 'pull_request' }} + # One group per pull request and per branch: a newer push cancels the run it supersedes, on main + # too, since the newest run checks everything before it. + group: dialogs-${{ github.ref }} + cancel-in-progress: true jobs: dialogs: @@ -37,10 +37,5 @@ jobs: components: clippy # The macOS code is linted on Linux: it compiles for the target without the SDK. targets: aarch64-apple-darwin - - run: cargo clippy -p craft-dialogs --all-targets --locked -- -D warnings + # Native clippy and the tests run in the Workspace gate. - run: cargo clippy -p craft-dialogs --target aarch64-apple-darwin --locked -- -D warnings - - name: Docs (links and missing docs) - run: cargo doc -p craft-dialogs --no-deps --locked - env: - RUSTDOCFLAGS: -D warnings - - run: cargo test -p craft-dialogs --locked diff --git a/.github/workflows/doc.yml b/.github/workflows/doc.yml index 406a47ea6..00b8336db 100644 --- a/.github/workflows/doc.yml +++ b/.github/workflows/doc.yml @@ -12,20 +12,17 @@ permissions: contents: read concurrency: - # Pull requests share one group per branch, so a newer push cancels the older run. Every other - # run (main, manual) gets a group of its own, so it is neither cancelled nor replaced while queued. - group: doc-${{ github.event_name == 'pull_request' && github.ref || github.run_id }} - cancel-in-progress: ${{ github.event_name == 'pull_request' }} + # One group per pull request and per branch: a newer push cancels the run it supersedes, on main + # too, since the newest run checks everything before it. + group: doc-${{ github.ref }} + cancel-in-progress: true +# fmt, clippy and the tests run in the Workspace gate on every OS; this checks what it does not. jobs: doc: + name: Craft documents WASM timeout-minutes: 15 - strategy: - fail-fast: false - matrix: - # macOS runners are kept for releases: macOS runs only when started by hand. - os: ${{ github.event_name == 'workflow_dispatch' && fromJSON('["ubuntu-latest","windows-latest","macos-latest"]') || github.ref == 'refs/heads/next' && fromJSON('["ubuntu-latest"]') || fromJSON('["ubuntu-latest","windows-latest"]') }} - runs-on: ${{ matrix.os }} + runs-on: ubuntu-latest steps: - name: Harden runner uses: step-security/harden-runner@v2.22.4 @@ -37,16 +34,5 @@ jobs: - uses: step-security/dtolnay-rust-toolchain@v1.0.0 with: toolchain: stable - components: rustfmt, clippy targets: wasm32-unknown-unknown - - run: cargo fmt --check - - run: cargo clippy -p craft-doc --all-targets --locked -- -D warnings - - run: cargo clippy -p craft-doc --all-targets --all-features --locked -- -D warnings - - name: Docs (links and missing docs) - if: runner.os == 'Linux' - run: cargo doc -p craft-doc --all-features --no-deps --locked - env: - RUSTDOCFLAGS: -D warnings - - run: cargo test -p craft-doc --locked -- --nocapture - - run: cargo test -p craft-doc --all-features --locked -- --nocapture - run: cargo check -p craft-doc --all-features --locked --target wasm32-unknown-unknown diff --git a/.github/workflows/docpath.yml b/.github/workflows/docpath.yml deleted file mode 100644 index f19b9a6b4..000000000 --- a/.github/workflows/docpath.yml +++ /dev/null @@ -1,46 +0,0 @@ -name: Document paths - -on: - workflow_dispatch: - push: - branches: [main, next] - paths: ['crates/docpath/**', 'Cargo.toml', 'Cargo.lock', '.github/workflows/docpath.yml'] - pull_request: - paths: ['crates/docpath/**', 'Cargo.toml', 'Cargo.lock', '.github/workflows/docpath.yml'] - -permissions: - contents: read - -concurrency: - # Pull requests share one group per branch, so a newer push cancels the older run. Every other - # run (main, manual) gets a group of its own, so it is neither cancelled nor replaced while queued. - group: docpath-${{ github.event_name == 'pull_request' && github.ref || github.run_id }} - cancel-in-progress: ${{ github.event_name == 'pull_request' }} - -jobs: - docpath: - timeout-minutes: 15 - strategy: - fail-fast: false - matrix: - # macOS runners are kept for releases: macOS runs only when started by hand. - os: ${{ github.event_name == 'workflow_dispatch' && fromJSON('["ubuntu-latest","windows-latest","macos-latest"]') || github.ref == 'refs/heads/next' && fromJSON('["ubuntu-latest"]') || fromJSON('["ubuntu-latest","windows-latest"]') }} - runs-on: ${{ matrix.os }} - steps: - - name: Harden runner - uses: step-security/harden-runner@v2.22.4 - with: - egress-policy: audit - - uses: actions/checkout@v7.0.1 - - uses: step-security/dtolnay-rust-toolchain@v1.0.0 - with: - toolchain: stable - components: rustfmt, clippy - - run: cargo fmt --check - - run: cargo clippy -p craft-docpath --all-targets --locked -- -D warnings - - name: Docs (links and missing docs) - if: runner.os == 'Linux' - run: cargo doc -p craft-docpath --no-deps --locked - env: - RUSTDOCFLAGS: -D warnings - - run: cargo test -p craft-docpath --locked -- --nocapture diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 5bd990d93..fc51a0da5 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -20,14 +20,30 @@ jobs: name: Workspace docs runs-on: ubuntu-latest steps: - - uses: actions/checkout@v7 + - uses: actions/checkout@v7.0.1 with: # The token isn't needed after checkout; cargo runs build scripts and proc macros from # dependencies, so don't leave it in .git/config for that third-party code to read. persist-credentials: false - - uses: dtolnay/rust-toolchain@b725eda525362e7cf34af9a7243cac1e3f01a7ec # stable - - uses: Swatinem/rust-cache@d1527c8f67ef9af357290475d4af4b0fab8f12e0 # v2.9.3 + - uses: step-security/dtolnay-rust-toolchain@v1.0.0 + with: + toolchain: stable + components: clippy + # Pull requests restore the cache but never save one (a 1.1 GB entry per open PR otherwise). + - uses: step-security/rust-cache@v2.9.2 + with: + save-if: ${{ github.ref == 'refs/heads/main' }} + # A lib build selects no dev-dependency, so craft-ui's `testing` stays off as in an app's + # build: warnings that show only without it fail here. + - name: Facade as an app builds it + run: cargo clippy -p craft --lib --locked --features ui,layers,color,draw,imaging -- -D warnings - name: Docs (links and missing docs) run: cargo doc --workspace --no-deps --locked --keep-going env: RUSTDOCFLAGS: -D warnings + # The crates whose features add public items document with every feature too; the + # per-crate workflows document the media, audio and video crates. + - name: Docs with all features + run: cargo doc -p craft-ui -p craft-ui-contract -p craft-ui-widgets -p craft-ui-panels -p craft-ui-canvas -p craft-ui-patterns -p craft-ui-shell -p craft-doc -p craft-pdf --all-features --no-deps --locked --keep-going + env: + RUSTDOCFLAGS: -D warnings diff --git a/.github/workflows/ecproj-format.yml b/.github/workflows/ecproj-format.yml index 6ad11109c..bec96fed5 100644 --- a/.github/workflows/ecproj-format.yml +++ b/.github/workflows/ecproj-format.yml @@ -12,20 +12,17 @@ permissions: contents: read concurrency: - # Pull requests share one group per branch, so a newer push cancels the older run. Every other - # run (main, manual) gets a group of its own, so it is neither cancelled nor replaced while queued. - group: ecproj-format-${{ github.event_name == 'pull_request' && github.ref || github.run_id }} - cancel-in-progress: ${{ github.event_name == 'pull_request' }} + # One group per pull request and per branch: a newer push cancels the run it supersedes, on main + # too, since the newest run checks everything before it. + group: ecproj-format-${{ github.ref }} + cancel-in-progress: true +# fmt, clippy and the tests run in the Workspace gate on every OS; this checks what it does not. jobs: ecproj-format: + name: EffectCraft project format WASM timeout-minutes: 15 - strategy: - fail-fast: false - matrix: - # macOS runners are kept for releases: macOS runs only when started by hand. - os: ${{ github.event_name == 'workflow_dispatch' && fromJSON('["ubuntu-latest","windows-latest","macos-latest"]') || github.ref == 'refs/heads/next' && fromJSON('["ubuntu-latest"]') || fromJSON('["ubuntu-latest","windows-latest"]') }} - runs-on: ${{ matrix.os }} + runs-on: ubuntu-latest steps: - name: Harden runner uses: step-security/harden-runner@v2.22.4 @@ -37,14 +34,5 @@ jobs: - uses: step-security/dtolnay-rust-toolchain@v1.0.0 with: toolchain: stable - components: rustfmt, clippy targets: wasm32-unknown-unknown - - run: cargo fmt --check - - run: cargo clippy -p craft-ecproj-format --all-targets --locked -- -D warnings - - name: Docs (links and missing docs) - if: runner.os == 'Linux' - run: cargo doc -p craft-ecproj-format --no-deps --locked - env: - RUSTDOCFLAGS: -D warnings - - run: cargo test -p craft-ecproj-format --locked -- --nocapture - run: cargo check -p craft-ecproj-format --locked --target wasm32-unknown-unknown diff --git a/.github/workflows/font-store.yml b/.github/workflows/font-store.yml index ba1095b03..fd599d207 100644 --- a/.github/workflows/font-store.yml +++ b/.github/workflows/font-store.yml @@ -12,20 +12,17 @@ permissions: contents: read concurrency: - # Pull requests share one group per branch, so a newer push cancels the older run. Every other - # run (main, manual) gets a group of its own, so it is neither cancelled nor replaced while queued. - group: font-store-${{ github.event_name == 'pull_request' && github.ref || github.run_id }} - cancel-in-progress: ${{ github.event_name == 'pull_request' }} + # One group per pull request and per branch: a newer push cancels the run it supersedes, on main + # too, since the newest run checks everything before it. + group: font-store-${{ github.ref }} + cancel-in-progress: true +# fmt, clippy and the tests run in the Workspace gate on every OS; this checks what it does not. jobs: font-store: + name: Font store WASM timeout-minutes: 20 - strategy: - fail-fast: false - matrix: - # macOS runners are kept for releases: macOS runs only when started by hand. - os: ${{ github.event_name == 'workflow_dispatch' && fromJSON('["ubuntu-latest","windows-latest","macos-latest"]') || github.ref == 'refs/heads/next' && fromJSON('["ubuntu-latest"]') || fromJSON('["ubuntu-latest","windows-latest"]') }} - runs-on: ${{ matrix.os }} + runs-on: ubuntu-latest steps: - name: Harden runner uses: step-security/harden-runner@v2.22.4 @@ -35,18 +32,6 @@ jobs: - uses: step-security/dtolnay-rust-toolchain@v1.0.0 with: toolchain: stable - components: rustfmt, clippy targets: wasm32-unknown-unknown - - run: cargo fmt --check - - run: cargo clippy -p craft-font-store --all-targets --locked -- -D warnings - - name: Docs (links and missing docs) - if: runner.os == 'Linux' - run: cargo doc -p craft-font-store --no-deps --locked - env: - RUSTDOCFLAGS: -D warnings - - run: cargo test -p craft-font-store --locked - - run: cargo clippy -p craft-font-catalog --all-targets --locked -- -D warnings - - run: cargo test -p craft-font-catalog --locked - name: Check the web build - if: runner.os == 'Linux' run: cargo check -p craft-font-store --target wasm32-unknown-unknown --locked diff --git a/.github/workflows/formats.yml b/.github/workflows/formats.yml index a78bbac5d..f96bf9a4a 100644 --- a/.github/workflows/formats.yml +++ b/.github/workflows/formats.yml @@ -42,11 +42,10 @@ permissions: contents: read concurrency: - # Pull requests share one group per branch, so a newer push cancels the older run. Every other - # run (main, manual) gets its own group: it is never cancelled or replaced while queued, so it - # always gets to save the cache. - group: shared-formats-${{ github.event_name == 'pull_request' && github.ref || github.run_id }} - cancel-in-progress: ${{ github.event_name == 'pull_request' }} + # One group per pull request and per branch: a newer push cancels the run it supersedes, on main + # too, since the newest run checks everything before it. + group: shared-formats-${{ github.ref }} + cancel-in-progress: true jobs: check: @@ -68,7 +67,9 @@ jobs: - { crate: craft-tiff, features: "" } - { crate: craft-heif, features: "testdata" } - { crate: craft-cms, features: "" } - name: ${{ matrix.crate }} lint, tests, WASM + # fmt, clippy with default and with all features, and the tests run in the Workspace gate on + # every OS; this lints each feature alone and checks the web build. + name: ${{ matrix.crate }} feature sets, WASM runs-on: ubuntu-latest steps: - name: Harden runner @@ -80,32 +81,19 @@ jobs: persist-credentials: false - uses: dtolnay/rust-toolchain@stable with: - components: rustfmt, clippy + components: clippy targets: wasm32-unknown-unknown - - uses: Swatinem/rust-cache@v2.9.3 - with: - key: ${{ matrix.crate }} - save-if: ${{ github.ref == 'refs/heads/main' }} - - run: cargo fmt -p "$CRATE" --check - env: - CRATE: ${{ matrix.crate }} - - name: Clippy, default features and each feature alone + - name: Clippy, each feature alone + if: matrix.features != '' env: CRATE: ${{ matrix.crate }} FEATURES: ${{ matrix.features }} run: | - cargo clippy -p "$CRATE" --all-targets --locked -- -D warnings for f in $FEATURES; do echo "::group::feature: $f" cargo clippy -p "$CRATE" --all-targets --locked --no-default-features --features "$f" -- -D warnings echo "::endgroup::" done - - run: cargo clippy -p "$CRATE" --all-targets --locked --all-features -- -D warnings - env: - CRATE: ${{ matrix.crate }} - - run: cargo test -p "$CRATE" --all-features --locked - env: - CRATE: ${{ matrix.crate }} - run: cargo check -p "$CRATE" --all-features --locked --target wasm32-unknown-unknown env: CRATE: ${{ matrix.crate }} diff --git a/.github/workflows/full-validation.yml b/.github/workflows/full-validation.yml new file mode 100644 index 000000000..85ad96f2f --- /dev/null +++ b/.github/workflows/full-validation.yml @@ -0,0 +1,64 @@ +name: Full validation + +# Add full-validation to a PR for uncapped validation of its merge ref. Keep the label across pushes. +# Fast Workspace checks are not substitutes for these six completed native/PDF gate checks. +on: + pull_request: + types: [opened, synchronize, reopened, labeled] + workflow_dispatch: + +permissions: + contents: read + +concurrency: + # An unrelated label event must not cancel an active full run. + group: full-validation-${{ github.event.action == 'labeled' && github.event.label.name != 'full-validation' && github.run_id || github.event.pull_request.number || github.run_id }} + cancel-in-progress: ${{ github.event_name == 'pull_request' }} + +jobs: + native: + if: >- + github.event_name == 'workflow_dispatch' || + (contains(github.event.pull_request.labels.*.name, 'full-validation') && + (github.event.action != 'labeled' || github.event.label.name == 'full-validation')) + name: Full native + uses: storytold/craft-common-actions/.github/workflows/gate.yml@main + with: + os: '["ubuntu-latest","windows-latest","macos-latest"]' + select-os: '[]' + timeout-minutes: 120 + tools: "" + packages: mesa-vulkan-drivers libvulkan1 + craft-fonts-ref: b076417b5880bd4154bd22f00695b1d28c6bea83 + linux-env: WGPU_BACKEND=vulkan + windows-env: CRAFT_PRINT_REQUIRE_QUEUE=1 + env: CRAFT_PRINT_REQUIRE_QUEUE=0 + setup-command: bash scripts/ci-test-inputs.sh + command: | + python scripts/test-full-validation.py + bash scripts/ci-full-validation.sh + + pdf-contracts: + if: >- + github.event_name == 'workflow_dispatch' || + (contains(github.event.pull_request.labels.*.name, 'full-validation') && + (github.event.action != 'labeled' || github.event.label.name == 'full-validation')) + name: Full PDF contracts + uses: storytold/craft-common-actions/.github/workflows/gate.yml@main + with: + os: '["ubuntu-latest","windows-latest","macos-latest"]' + select-os: '[]' + timeout-minutes: 120 + tools: "" + craft-fonts-ref: "" + require-craft-fonts: false + env: RUSTFLAGS=--cfg craft_pdf_unicode_fixtures + setup-command: | + python scripts/test-fetch-pdf-test-fonts.py + python scripts/fetch-pdf-test-fonts.py "$RUNNER_TEMP/craft-pdf-test-fonts" + echo "CRAFT_PDF_TEST_FONT_DIR=$RUNNER_TEMP/craft-pdf-test-fonts" >> "$GITHUB_ENV" + command: | + unset CRAFT_HOSTILE_DIVISOR PROPTEST_CASES + cargo clippy -p craft-pdf --all-targets --all-features --locked -- -D warnings + cargo test -p craft-pdf --all-features --locked + cargo test --manifest-path crates/pdf/read-only-contract/Cargo.toml --locked diff --git a/.github/workflows/i18n.yml b/.github/workflows/i18n.yml deleted file mode 100644 index 61c7ccff3..000000000 --- a/.github/workflows/i18n.yml +++ /dev/null @@ -1,46 +0,0 @@ -name: Translations - -on: - workflow_dispatch: - push: - branches: [main, next] - paths: ['crates/i18n/**', 'Cargo.toml', 'Cargo.lock', '.github/workflows/i18n.yml'] - pull_request: - paths: ['crates/i18n/**', 'Cargo.toml', 'Cargo.lock', '.github/workflows/i18n.yml'] - -permissions: - contents: read - -concurrency: - # Pull requests share one group per branch, so a newer push cancels the older run. Every other - # run (main, manual) gets a group of its own, so it is neither cancelled nor replaced while queued. - group: i18n-${{ github.event_name == 'pull_request' && github.ref || github.run_id }} - cancel-in-progress: ${{ github.event_name == 'pull_request' }} - -jobs: - i18n: - timeout-minutes: 15 - strategy: - fail-fast: false - matrix: - # macOS runners are kept for releases: macOS runs only when started by hand. - os: ${{ github.event_name == 'workflow_dispatch' && fromJSON('["ubuntu-latest","windows-latest","macos-latest"]') || github.ref == 'refs/heads/next' && fromJSON('["ubuntu-latest"]') || fromJSON('["ubuntu-latest","windows-latest"]') }} - runs-on: ${{ matrix.os }} - steps: - - name: Harden runner - uses: step-security/harden-runner@v2.22.4 - with: - egress-policy: audit - - uses: actions/checkout@v7.0.1 - - uses: step-security/dtolnay-rust-toolchain@v1.0.0 - with: - toolchain: stable - components: rustfmt, clippy - - run: cargo fmt --check - - run: cargo clippy -p craft-i18n --all-targets --features collate --locked -- -D warnings - - name: Docs (links and missing docs) - if: runner.os == 'Linux' - run: cargo doc -p craft-i18n --no-deps --locked - env: - RUSTDOCFLAGS: -D warnings - - run: cargo test -p craft-i18n --features collate --locked -- --nocapture diff --git a/.github/workflows/jpeg.yml b/.github/workflows/jpeg.yml index 6beccab19..ebb27bafd 100644 --- a/.github/workflows/jpeg.yml +++ b/.github/workflows/jpeg.yml @@ -12,16 +12,17 @@ permissions: contents: read concurrency: - # Pull requests share one group per branch, so a newer push cancels the older run. Every other - # run (main, manual) gets its own group: it is never cancelled or replaced while queued, so it - # always gets to save the cache. - group: shared-jpeg-${{ github.event_name == 'pull_request' && github.ref || github.run_id }} - cancel-in-progress: ${{ github.event_name == 'pull_request' }} + # One group per pull request and per branch: a newer push cancels the run it supersedes, on main + # too, since the newest run checks everything before it. + group: shared-jpeg-${{ github.ref }} + cancel-in-progress: true jobs: check: - timeout-minutes: 10 - name: JPEG lint, tests, WASM + # Uncached: the wasm check builds its dependencies on every run (about 10 minutes with setup). + timeout-minutes: 20 + # fmt, clippy and the tests run in the Workspace gate on every OS. + name: JPEG WASM runs-on: ubuntu-latest steps: - name: Harden runner @@ -34,17 +35,5 @@ jobs: - uses: step-security/dtolnay-rust-toolchain@v1.0.0 with: toolchain: stable - components: rustfmt, clippy targets: wasm32-unknown-unknown - - uses: step-security/rust-cache@v2.9.2 - with: - key: craft-jpeg - save-if: ${{ github.ref == 'refs/heads/main' }} - - run: cargo fmt -p craft-jpeg --check - - run: cargo clippy -p craft-jpeg --all-targets --locked -- -D warnings - - name: Docs (links and missing docs) - run: cargo doc -p craft-jpeg --no-deps --locked - env: - RUSTDOCFLAGS: -D warnings - - run: cargo test -p craft-jpeg --locked - run: cargo check -p craft-jpeg --locked --target wasm32-unknown-unknown diff --git a/.github/workflows/keymap.yml b/.github/workflows/keymap.yml index 2cd3fffed..bfce47378 100644 --- a/.github/workflows/keymap.yml +++ b/.github/workflows/keymap.yml @@ -12,16 +12,17 @@ permissions: contents: read concurrency: - # Pull requests share one group per branch, so a newer push cancels the older run. Every other - # run (main, manual) gets its own group: it is never cancelled or replaced while queued, so it - # always gets to save the cache. - group: keymap-${{ github.event_name == 'pull_request' && github.ref || github.run_id }} - cancel-in-progress: ${{ github.event_name == 'pull_request' }} + # One group per pull request and per branch: a newer push cancels the run it supersedes, on main + # too, since the newest run checks everything before it. + group: keymap-${{ github.ref }} + cancel-in-progress: true jobs: linux: timeout-minutes: 15 - name: Keymap (Linux) + # fmt, and clippy and the tests with default and with all features, run in the Workspace gate + # on every OS; this runs the feature subsets. + name: Keymap feature sets runs-on: ubuntu-latest env: CRAFT_FONTS_DIR: ${{ github.workspace }}/.test-inputs/craft-fonts @@ -43,59 +44,14 @@ jobs: - uses: step-security/dtolnay-rust-toolchain@v1.0.0 with: toolchain: stable - components: rustfmt, clippy - - uses: step-security/rust-cache@v2.9.2 - with: - key: craft-keymap-linux - save-if: ${{ github.ref == 'refs/heads/main' }} - - run: cargo fmt -p craft-keymap --check + components: clippy - run: cargo clippy -p craft-keymap --all-targets --no-default-features --locked -- -D warnings - run: cargo clippy -p craft-keymap --all-targets --features egui --locked -- -D warnings - - name: Docs (links and missing docs) - run: cargo doc -p craft-keymap --no-deps --locked - env: - RUSTDOCFLAGS: -D warnings - # Doctests run once, in the `ui` step. + # Doctests run once, in the `egui` step. - name: Test core run: cargo test -p craft-keymap --no-default-features --lib --tests --locked - name: Test egui dispatch run: cargo test -p craft-keymap --features egui --locked - native: - # Pushes to next run Linux only. - if: github.ref != 'refs/heads/next' || github.event_name == 'workflow_dispatch' - timeout-minutes: 15 - name: Keymap (${{ matrix.os }}) - strategy: - fail-fast: false - matrix: - # macOS runners are kept for releases: macOS runs only when started by hand. - os: ${{ github.event_name == 'workflow_dispatch' && fromJSON('["macos-latest","windows-latest"]') || fromJSON('["windows-latest"]') }} - runs-on: ${{ matrix.os }} - env: - CRAFT_FONTS_DIR: ${{ github.workspace }}/.test-inputs/craft-fonts - steps: - - name: Harden runner - uses: step-security/harden-runner@v2.22.4 - with: - egress-policy: audit - - uses: actions/checkout@v7.0.1 - with: - persist-credentials: false - - name: Checkout test fonts - uses: actions/checkout@v7.0.1 - with: - repository: storytold/craft-fonts - ref: b076417b5880bd4154bd22f00695b1d28c6bea83 - path: .test-inputs/craft-fonts - persist-credentials: false - - uses: step-security/dtolnay-rust-toolchain@v1.0.0 - with: - toolchain: stable - - uses: step-security/rust-cache@v2.9.2 - with: - key: craft-keymap-${{ matrix.os }} - save-if: ${{ github.ref == 'refs/heads/main' }} - - run: cargo test -p craft-keymap --features egui --locked wasm: timeout-minutes: 10 name: Keymap WASM @@ -112,8 +68,4 @@ jobs: with: toolchain: stable targets: wasm32-unknown-unknown - - uses: step-security/rust-cache@v2.9.2 - with: - key: craft-keymap-wasm - save-if: ${{ github.ref == 'refs/heads/main' }} - run: cargo check -p craft-keymap --features egui --locked --target wasm32-unknown-unknown diff --git a/.github/workflows/media.yml b/.github/workflows/media.yml index 415ab92f9..090ad84da 100644 --- a/.github/workflows/media.yml +++ b/.github/workflows/media.yml @@ -11,17 +11,22 @@ on: permissions: contents: read +# A fraction of the fuzz-style cases, as in the Workspace gate; nightly.yml runs them in full. +env: + CRAFT_HOSTILE_DIVISOR: "8" + PROPTEST_CASES: "64" + concurrency: - # Pull requests share one group per branch, so a newer push cancels the older run. Every other - # run (main, manual) gets its own group: it is never cancelled or replaced while queued, so it - # always gets to save the cache. - group: shared-media-${{ github.event_name == 'pull_request' && github.ref || github.run_id }} - cancel-in-progress: ${{ github.event_name == 'pull_request' }} + # One group per pull request and per branch: a newer push cancels the run it supersedes, on main + # too, since the newest run checks everything before it. + group: shared-media-${{ github.ref }} + cancel-in-progress: true jobs: lint: timeout-minutes: 10 - name: Media lint, feature sets, WASM + # fmt, and clippy with default and with all features, run in the Workspace gate on every OS. + name: Media feature sets, WASM runs-on: ubuntu-latest steps: - name: Harden runner @@ -34,20 +39,12 @@ jobs: - uses: step-security/dtolnay-rust-toolchain@v1.0.0 with: toolchain: stable - components: rustfmt, clippy + components: clippy targets: wasm32-unknown-unknown - - uses: step-security/rust-cache@v2.9.2 - with: - key: craft-media-lint - save-if: ${{ github.ref == 'refs/heads/main' }} - - run: cargo fmt -p craft-media --check - run: cargo clippy -p craft-media --all-targets --locked --no-default-features -- -D warnings - run: cargo clippy -p craft-media --all-targets --locked --no-default-features --features bitstream -- -D warnings - - run: cargo clippy -p craft-media --all-targets --locked -- -D warnings - run: cargo clippy -p craft-media --all-targets --locked --no-default-features --features matroska -- -D warnings - run: cargo clippy -p craft-media --all-targets --locked --no-default-features --features ogg -- -D warnings - - run: cargo clippy -p craft-media --all-targets --locked --all-features -- -D warnings - - run: cargo clippy -p craft-media-testkit --all-targets --locked -- -D warnings - run: cargo clippy -p craft-media --all-targets --locked --no-default-features --features serde -- -D warnings - name: Docs (links and missing docs) run: cargo doc -p craft-media -p craft-media-testkit --all-features --no-deps --locked @@ -69,10 +66,6 @@ jobs: - uses: step-security/dtolnay-rust-toolchain@v1.0.0 with: toolchain: stable - - uses: step-security/rust-cache@v2.9.2 - with: - key: craft-media-test - save-if: ${{ github.ref == 'refs/heads/main' }} - name: Build tests while installing ffmpeg run: | # The man-db index rebuild after dpkg is slow on hosted runners. diff --git a/.github/workflows/menu.yml b/.github/workflows/menu.yml index d0eac01a1..80b6678cd 100644 --- a/.github/workflows/menu.yml +++ b/.github/workflows/menu.yml @@ -18,7 +18,8 @@ concurrency: jobs: linux: timeout-minutes: 15 - name: Menu (Linux) + # fmt, native clippy and the tests run in the Workspace gate on every OS. + name: Menu macOS and WASM lint runs-on: ubuntu-latest steps: - uses: actions/checkout@v7.0.1 @@ -26,14 +27,8 @@ jobs: persist-credentials: false - uses: dtolnay/rust-toolchain@stable with: - components: rustfmt, clippy + components: clippy targets: aarch64-apple-darwin, wasm32-unknown-unknown - - uses: Swatinem/rust-cache@v2.9.3 - with: - key: craft-menu-linux - - run: cargo fmt -p craft-menu --check - - run: cargo clippy -p craft-menu --all-targets --locked -- -D warnings # The macOS backend type-checks from Linux; it needs no linker or SDK. - run: cargo clippy -p craft-menu --lib --locked --target aarch64-apple-darwin -- -D warnings - run: cargo clippy -p craft-menu --lib --locked --target wasm32-unknown-unknown -- -D warnings - - run: cargo test -p craft-menu --locked diff --git a/.github/workflows/nightly.yml b/.github/workflows/nightly.yml new file mode 100644 index 000000000..ed9d36127 --- /dev/null +++ b/.github/workflows/nightly.yml @@ -0,0 +1,34 @@ +name: Nightly full tests + +# The tests the Workspace gate shortens, in full, once a day: every hostile-input hammer and sweep +# without CRAFT_HOSTILE_DIVISOR, and every proptest at its own case count (no PROPTEST_CASES). The +# rest of the workspace's tests run with them, on Linux, with the gate's setup. +on: + schedule: + - cron: "37 2 * * *" + workflow_dispatch: + +permissions: + contents: read + +concurrency: + group: nightly-${{ github.ref }} + cancel-in-progress: false + +jobs: + full: + name: Full tests + uses: storytold/craft-common-actions/.github/workflows/gate.yml@main + with: + os: '["ubuntu-latest"]' + timeout-minutes: 120 + tools: cargo-nextest@0.9.150 + packages: mesa-vulkan-drivers libvulkan1 + craft-fonts-ref: b076417b5880bd4154bd22f00695b1d28c6bea83 + linux-env: WGPU_BACKEND=vulkan + env: CRAFT_PRINT_REQUIRE_QUEUE=0 + setup-command: bash scripts/ci-test-inputs.sh + cache-paths: .test-inputs/photocraft/corpus + cache-key: photocraft-corpus + cache-key-files: scripts/ci-test-inputs.sh + command: cargo nextest run --workspace --all-features --locked --profile ci diff --git a/.github/workflows/pcraft-format.yml b/.github/workflows/pcraft-format.yml index 130e679b4..cefa5360c 100644 --- a/.github/workflows/pcraft-format.yml +++ b/.github/workflows/pcraft-format.yml @@ -12,20 +12,18 @@ permissions: contents: read concurrency: - # Pull requests share one group per branch, so a newer push cancels the older run. Every other - # run (main, manual) gets a group of its own, so it is neither cancelled nor replaced while queued. - group: pcraft-format-${{ github.event_name == 'pull_request' && github.ref || github.run_id }} - cancel-in-progress: ${{ github.event_name == 'pull_request' }} + # One group per pull request and per branch: a newer push cancels the run it supersedes, on main + # too, since the newest run checks everything before it. + group: pcraft-format-${{ github.ref }} + cancel-in-progress: true +# fmt, clippy and the tests run in the Workspace gate on every OS, and its msrv job checks the +# workspace on 1.95; this checks the web build on 1.95. jobs: pcraft-format: + name: PhotoCraft format WASM timeout-minutes: 15 - strategy: - fail-fast: false - matrix: - # macOS runners are kept for releases: macOS runs only when started by hand. - os: ${{ github.event_name == 'workflow_dispatch' && fromJSON('["ubuntu-latest","windows-latest","macos-latest"]') || github.ref == 'refs/heads/next' && fromJSON('["ubuntu-latest"]') || fromJSON('["ubuntu-latest","windows-latest"]') }} - runs-on: ${{ matrix.os }} + runs-on: ubuntu-latest steps: - name: Harden runner uses: step-security/harden-runner@v2.22.4 @@ -37,14 +35,5 @@ jobs: - uses: step-security/dtolnay-rust-toolchain@v1.0.0 with: toolchain: "1.95" - components: rustfmt, clippy targets: wasm32-unknown-unknown - - run: cargo fmt --check - - run: cargo clippy -p craft-pcraft-format --all-targets --locked -- -D warnings - - name: Docs (links and missing docs) - if: runner.os == 'Linux' - run: cargo doc -p craft-pcraft-format --no-deps --locked - env: - RUSTDOCFLAGS: -D warnings - - run: cargo test -p craft-pcraft-format --locked -- --nocapture - run: cargo check -p craft-pcraft-format --locked --target wasm32-unknown-unknown diff --git a/.github/workflows/pdf.yml b/.github/workflows/pdf.yml index bcd81efa4..7785d9212 100644 --- a/.github/workflows/pdf.yml +++ b/.github/workflows/pdf.yml @@ -11,22 +11,23 @@ on: permissions: contents: read +# A fraction of the proptest cases, as in the Workspace gate; nightly.yml runs them in full. +env: + PROPTEST_CASES: "64" + concurrency: - # Pull requests share one group per branch, so a newer push cancels the older run. Every other - # run (main, manual) gets its own group: it is never cancelled or replaced while queued, so it - # always gets to save the cache. - group: shared-pdf-${{ github.event_name == 'pull_request' && github.ref || github.run_id }} - cancel-in-progress: ${{ github.event_name == 'pull_request' }} + # One group per pull request and per branch: a newer push cancels the run it supersedes, on main + # too, since the newest run checks everything before it. + group: shared-pdf-${{ github.ref }} + cancel-in-progress: true jobs: native: - name: PDF (${{ matrix.os }}) - strategy: - fail-fast: false - matrix: - # macOS runners are kept for releases: macOS runs only when started by hand. - os: ${{ github.event_name == 'workflow_dispatch' && fromJSON('["ubuntu-latest","windows-latest","macos-latest"]') || github.ref == 'refs/heads/next' && fromJSON('["ubuntu-latest"]') || fromJSON('["ubuntu-latest","windows-latest"]') }} - runs-on: ${{ matrix.os }} + # fmt, clippy and the tests run in the Workspace gate on every OS, with the licensed fonts and + # the plate tests; this runs the tests behind craft_pdf_unicode_fixtures and the read-only + # contract, which is its own workspace. + name: PDF Unicode fixtures and read-only contract + runs-on: ubuntu-latest env: RUSTFLAGS: --cfg craft_pdf_unicode_fixtures steps: @@ -38,11 +39,6 @@ jobs: - uses: step-security/dtolnay-rust-toolchain@v1.0.0 with: toolchain: stable - components: rustfmt, clippy - - uses: step-security/rust-cache@v2.9.2 - with: - key: craft-pdf - save-if: ${{ github.ref == 'refs/heads/main' }} - uses: actions/setup-python@v7.1.0 with: python-version: "3.12" @@ -52,14 +48,7 @@ jobs: python scripts/test-fetch-pdf-test-fonts.py python scripts/fetch-pdf-test-fonts.py "$RUNNER_TEMP/craft-pdf-test-fonts" echo "CRAFT_PDF_TEST_FONT_DIR=$RUNNER_TEMP/craft-pdf-test-fonts" >> "$GITHUB_ENV" - - run: cargo fmt --check - - run: cargo clippy -p craft-pdf --all-targets --all-features --locked -- -D warnings - - name: Docs (links and missing docs) - if: runner.os == 'Linux' - run: cargo doc -p craft-pdf --all-features --no-deps --locked - env: - RUSTDOCFLAGS: -D warnings - - run: cargo test -p craft-pdf --all-features --locked + - run: cargo test -p craft-pdf --all-features --locked --lib -- integration::unicode_writing integration::upstream_compatibility - run: cargo test --manifest-path crates/pdf/read-only-contract/Cargo.toml --locked backends: name: PDF vendored contracts @@ -73,10 +62,6 @@ jobs: - uses: step-security/dtolnay-rust-toolchain@v1.0.0 with: toolchain: stable - - uses: step-security/rust-cache@v2.9.2 - with: - key: craft-pdf-backends - save-if: ${{ github.ref == 'refs/heads/main' }} - run: bash scripts/test-pdf-backends.sh wasm: name: PDF WASM runtime @@ -94,10 +79,6 @@ jobs: with: toolchain: stable targets: wasm32-unknown-unknown - - uses: step-security/rust-cache@v2.9.2 - with: - key: craft-pdf-wasm - save-if: ${{ github.ref == 'refs/heads/main' }} - uses: actions/setup-python@v7.1.0 with: python-version: "3.12" @@ -122,31 +103,3 @@ jobs: fallback: cargo-install - run: cargo test -p craft-pdf --all-features --locked --target wasm32-unknown-unknown - run: cargo test --manifest-path crates/pdf/read-only-contract/Cargo.toml --locked --target wasm32-unknown-unknown - plate-test: - name: Plate tests and craft-prepress - runs-on: ubuntu-latest - steps: - - name: Harden runner - uses: step-security/harden-runner@v2.22.4 - with: - egress-policy: audit - - uses: actions/checkout@v7.0.1 - - uses: step-security/dtolnay-rust-toolchain@v1.0.0 - with: - toolchain: stable - components: clippy - - uses: step-security/rust-cache@v2.9.2 - with: - key: craft-plate-test - save-if: ${{ github.ref == 'refs/heads/main' }} - - uses: actions/setup-python@v7.1.0 - with: - python-version: "3.12" - - name: Provision licensed PDF test fonts - shell: bash - run: | - python scripts/test-fetch-pdf-test-fonts.py - python scripts/fetch-pdf-test-fonts.py "$RUNNER_TEMP/craft-pdf-test-fonts" - echo "CRAFT_PDF_TEST_FONT_DIR=$RUNNER_TEMP/craft-pdf-test-fonts" >> "$GITHUB_ENV" - - run: cargo clippy -p craft-plate-test -p craft-prepress --all-targets --all-features --locked -- -D warnings - - run: cargo test -p craft-plate-test -p craft-prepress --all-features --locked diff --git a/.github/workflows/print.yml b/.github/workflows/print.yml deleted file mode 100644 index c1994deb8..000000000 --- a/.github/workflows/print.yml +++ /dev/null @@ -1,51 +0,0 @@ -name: Print spooler -on: - workflow_dispatch: - push: - branches: [main, next] - paths: ['crates/print/**', 'Cargo.toml', 'Cargo.lock', '.github/workflows/print.yml'] - pull_request: - paths: ['crates/print/**', 'Cargo.toml', 'Cargo.lock', '.github/workflows/print.yml'] -permissions: - contents: read -concurrency: - # Pull requests share one group per branch, so a newer push cancels the older run. Every other - # run (main, manual) gets a group of its own, so it is neither cancelled nor replaced while queued. - group: print-${{ github.event_name == 'pull_request' && github.ref || github.run_id }} - cancel-in-progress: ${{ github.event_name == 'pull_request' }} -jobs: - print: - timeout-minutes: 30 - strategy: - fail-fast: false - matrix: - # macOS runners are kept for releases: macOS runs only when started by hand. - os: ${{ github.event_name == 'workflow_dispatch' && fromJSON('["ubuntu-latest","windows-latest","macos-latest"]') || github.ref == 'refs/heads/next' && fromJSON('["ubuntu-latest"]') || fromJSON('["ubuntu-latest","windows-latest"]') }} - runs-on: ${{ matrix.os }} - steps: - - name: Harden runner - uses: step-security/harden-runner@v2.22.4 - with: - egress-policy: audit - - uses: actions/checkout@v7.0.1 - - uses: step-security/dtolnay-rust-toolchain@v1.0.0 - with: - toolchain: stable - components: rustfmt, clippy - - run: cargo fmt --check - - run: cargo clippy -p craft-print --all-targets -- -D warnings - - name: Docs (links and missing docs) - if: runner.os == 'Linux' - run: cargo doc -p craft-print --no-deps --locked - env: - RUSTDOCFLAGS: -D warnings - - name: Prepare the Windows test driver - if: runner.os == 'Windows' - shell: powershell - run: | - Start-Service Spooler - Add-PrinterDriver -Name 'Generic / Text Only' - - run: cargo test -p craft-print --locked -- --nocapture - timeout-minutes: 10 - env: - CRAFT_PRINT_REQUIRE_QUEUE: ${{ runner.os == 'Windows' && '1' || '0' }} diff --git a/.github/workflows/proof.yml b/.github/workflows/proof.yml index 84ccb38d4..0f5b869a4 100644 --- a/.github/workflows/proof.yml +++ b/.github/workflows/proof.yml @@ -12,16 +12,16 @@ permissions: contents: read concurrency: - # Pull requests share one group per branch, so a newer push cancels the older run. Every other - # run (main, manual) gets its own group: it is never cancelled or replaced while queued, so it - # always gets to save the cache. - group: craft-proof-${{ github.event_name == 'pull_request' && github.ref || github.run_id }} - cancel-in-progress: ${{ github.event_name == 'pull_request' }} + # One group per pull request and per branch: a newer push cancels the run it supersedes, on main + # too, since the newest run checks everything before it. + group: craft-proof-${{ github.ref }} + cancel-in-progress: true jobs: check: timeout-minutes: 20 - name: Proofing lint, tests with and without Language data, WASM + # fmt, and clippy and the tests without Language data, run in the Workspace gate on every OS. + name: Proofing with Language data, WASM runs-on: ubuntu-latest steps: - name: Harden runner @@ -43,18 +43,10 @@ jobs: - uses: step-security/dtolnay-rust-toolchain@v1.0.0 with: toolchain: stable - components: rustfmt, clippy + components: clippy targets: wasm32-unknown-unknown - - uses: step-security/rust-cache@v2.9.2 - with: - key: craft-proof - save-if: ${{ github.ref == 'refs/heads/main' }} - - run: cargo fmt -p craft-proof --check - - name: Without Language data (a fork, docs.rs, offline) - run: | - cargo clippy -p craft-proof --all-targets --locked -- -D warnings - cargo test -p craft-proof --locked - cargo check -p craft-proof --locked --target wasm32-unknown-unknown + - name: The web build without Language data (a fork, docs.rs, offline) + run: cargo check -p craft-proof --locked --target wasm32-unknown-unknown - name: A release without Language data fails run: | if CRAFT_I18N_REQUIRED=1 cargo check -p craft-proof --locked 2>build.log; then diff --git a/.github/workflows/theme.yml b/.github/workflows/theme.yml index b61e9efcf..213a74b14 100644 --- a/.github/workflows/theme.yml +++ b/.github/workflows/theme.yml @@ -17,13 +17,14 @@ jobs: name: Theme lint, tests, WASM runs-on: ubuntu-latest steps: - - uses: actions/checkout@v7 + - uses: actions/checkout@v7.0.1 with: # The token isn't needed after checkout; cargo runs build scripts and proc macros from # dependencies, so don't leave it in .git/config for that third-party code to read. persist-credentials: false - - uses: dtolnay/rust-toolchain@b725eda525362e7cf34af9a7243cac1e3f01a7ec # stable + - uses: step-security/dtolnay-rust-toolchain@v1.0.0 with: + toolchain: stable components: rustfmt, clippy targets: wasm32-unknown-unknown - run: cargo fmt -p craft-theme --check diff --git a/.github/workflows/ui.yml b/.github/workflows/ui.yml deleted file mode 100644 index 805a344da..000000000 --- a/.github/workflows/ui.yml +++ /dev/null @@ -1,84 +0,0 @@ -name: Shared UI - -on: - push: - branches: [main, next] - paths: ["crates/craft/**", "crates/ui/**", "crates/ui-contract/**", "crates/ui-widgets/**", "crates/ui-panels/**", "crates/ui-canvas/**", "crates/ui-patterns/**", "crates/ui-shell/**", "crates/ui-macros/**", "crates/i18n/**", "Cargo.toml", "Cargo.lock", ".github/workflows/ui.yml"] - pull_request: - paths: ["crates/craft/**", "crates/ui/**", "crates/ui-contract/**", "crates/ui-widgets/**", "crates/ui-panels/**", "crates/ui-canvas/**", "crates/ui-patterns/**", "crates/ui-shell/**", "crates/ui-macros/**", "crates/i18n/**", "Cargo.toml", "Cargo.lock", ".github/workflows/ui.yml"] - workflow_dispatch: - -permissions: - contents: read - -concurrency: - # Pull requests share one group per branch, so a newer push cancels the older run. Every other - # run (main, manual) gets its own group: it is never cancelled or replaced while queued, so it - # always gets to save the cache. - group: shared-ui-${{ github.event_name == 'pull_request' && github.ref || github.run_id }} - cancel-in-progress: ${{ github.event_name == 'pull_request' }} - -jobs: - native: - timeout-minutes: 30 - name: UI (${{ matrix.os }}) - strategy: - fail-fast: false - matrix: - # macOS runners are kept for releases: macOS runs only when started by hand. - os: ${{ github.event_name == 'workflow_dispatch' && fromJSON('["ubuntu-latest","windows-latest","macos-latest"]') || github.ref == 'refs/heads/next' && fromJSON('["ubuntu-latest"]') || fromJSON('["ubuntu-latest","windows-latest"]') }} - runs-on: ${{ matrix.os }} - steps: - - name: Harden runner - uses: step-security/harden-runner@v2.22.4 - with: - egress-policy: audit - - uses: actions/checkout@v7.0.1 - - name: Install software Vulkan renderer - if: runner.os == 'Linux' - run: | - sudo apt-get update - sudo apt-get install -y mesa-vulkan-drivers libvulkan1 - echo 'WGPU_BACKEND=vulkan' >> "$GITHUB_ENV" - - uses: step-security/dtolnay-rust-toolchain@v1.0.0 - with: - toolchain: stable - components: rustfmt, clippy - - uses: step-security/rust-cache@v2.9.2 - with: - key: craft-ui - save-if: ${{ github.ref == 'refs/heads/main' }} - - run: cargo fmt --check - - run: cargo clippy -p craft-ui -p craft-ui-contract -p craft-ui-widgets -p craft-ui-panels -p craft-ui-canvas -p craft-ui-patterns -p craft-ui-shell --all-targets --locked -- -D warnings - - run: cargo clippy -p craft-ui -p craft-ui-contract -p craft-ui-widgets -p craft-ui-panels -p craft-ui-canvas -p craft-ui-patterns -p craft-ui-shell --all-targets --all-features --locked -- -D warnings - # A lib build selects no dev-dependency, so craft-ui's `testing` stays off as in an app's build: warnings that - # show only without it fail here. - - name: Facade as an app builds it - if: runner.os == 'Linux' - run: cargo clippy -p craft --lib --locked --features ui,layers,color,draw,imaging -- -D warnings - - name: Docs (links and missing docs) - if: runner.os == 'Linux' - run: cargo doc -p craft-ui -p craft-ui-contract -p craft-ui-widgets -p craft-ui-panels -p craft-ui-canvas -p craft-ui-patterns -p craft-ui-shell --all-features --no-deps --locked - env: - RUSTDOCFLAGS: -D warnings - - run: cargo test -p craft-ui -p craft-ui-contract -p craft-ui-widgets -p craft-ui-panels -p craft-ui-canvas -p craft-ui-patterns -p craft-ui-shell --locked - - run: cargo test -p craft-ui -p craft-ui-contract -p craft-ui-widgets -p craft-ui-panels -p craft-ui-canvas -p craft-ui-patterns -p craft-ui-shell --all-features --locked - wasm: - timeout-minutes: 15 - name: UI WASM - runs-on: ubuntu-latest - steps: - - name: Harden runner - uses: step-security/harden-runner@v2.22.4 - with: - egress-policy: audit - - uses: actions/checkout@v7.0.1 - - uses: step-security/dtolnay-rust-toolchain@v1.0.0 - with: - toolchain: stable - targets: wasm32-unknown-unknown - - uses: step-security/rust-cache@v2.9.2 - with: - key: craft-ui-wasm - save-if: ${{ github.ref == 'refs/heads/main' }} - - run: cargo check -p craft-ui --all-features --locked --target wasm32-unknown-unknown diff --git a/.github/workflows/update.yml b/.github/workflows/update.yml index 6ff69c10e..0ea3b8c1b 100644 --- a/.github/workflows/update.yml +++ b/.github/workflows/update.yml @@ -12,20 +12,18 @@ permissions: contents: read concurrency: - # Pull requests share one group per branch, so a newer push cancels the older run. Every other - # run (main, manual) gets a group of its own, so it is neither cancelled nor replaced while queued. - group: update-${{ github.event_name == 'pull_request' && github.ref || github.run_id }} - cancel-in-progress: ${{ github.event_name == 'pull_request' }} + # One group per pull request and per branch: a newer push cancels the run it supersedes, on main + # too, since the newest run checks everything before it. + group: update-${{ github.ref }} + cancel-in-progress: true +# fmt, clippy and the tests with default and with all features run in the Workspace gate on every +# OS; this runs the ui feature alone. jobs: update: + name: Update with ui alone timeout-minutes: 15 - strategy: - fail-fast: false - matrix: - # macOS runners are kept for releases: macOS runs only when started by hand. - os: ${{ github.event_name == 'workflow_dispatch' && fromJSON('["ubuntu-latest","windows-latest","macos-latest"]') || github.ref == 'refs/heads/next' && fromJSON('["ubuntu-latest"]') || fromJSON('["ubuntu-latest","windows-latest"]') }} - runs-on: ${{ matrix.os }} + runs-on: ubuntu-latest steps: - name: Harden runner uses: step-security/harden-runner@v2.22.4 @@ -39,15 +37,6 @@ jobs: - uses: step-security/dtolnay-rust-toolchain@v1.0.0 with: toolchain: stable - components: rustfmt, clippy - - run: cargo fmt --check - # Default (no egui) and the ui feature both build and lint cleanly. - - run: cargo clippy -p craft-update --all-targets --locked -- -D warnings + components: clippy - run: cargo clippy -p craft-update --all-targets --locked --features ui -- -D warnings - - name: Docs (links and missing docs) - if: runner.os == 'Linux' - run: cargo doc -p craft-update --no-deps --locked - env: - RUSTDOCFLAGS: -D warnings - - run: cargo test -p craft-update --locked -- --nocapture - run: cargo test -p craft-update --locked --features ui -- --nocapture diff --git a/.github/workflows/vectorcraft-format.yml b/.github/workflows/vectorcraft-format.yml index b2eb4596b..0ca15636d 100644 --- a/.github/workflows/vectorcraft-format.yml +++ b/.github/workflows/vectorcraft-format.yml @@ -12,20 +12,18 @@ permissions: contents: read concurrency: - # Pull requests share one group per branch, so a newer push cancels the older run. Every other - # run (main, manual) gets a group of its own, so it is neither cancelled nor replaced while queued. - group: vectorcraft-format-${{ github.event_name == 'pull_request' && github.ref || github.run_id }} - cancel-in-progress: ${{ github.event_name == 'pull_request' }} + # One group per pull request and per branch: a newer push cancels the run it supersedes, on main + # too, since the newest run checks everything before it. + group: vectorcraft-format-${{ github.ref }} + cancel-in-progress: true +# fmt, clippy and the tests run in the Workspace gate on every OS, and its msrv job checks the +# workspace on 1.95; this checks the web build on 1.95. jobs: vectorcraft-format: + name: VectorCraft format WASM timeout-minutes: 15 - strategy: - fail-fast: false - matrix: - # macOS runners are kept for releases: macOS runs only when started by hand. - os: ${{ github.event_name == 'workflow_dispatch' && fromJSON('["ubuntu-latest","windows-latest","macos-latest"]') || github.ref == 'refs/heads/next' && fromJSON('["ubuntu-latest"]') || fromJSON('["ubuntu-latest","windows-latest"]') }} - runs-on: ${{ matrix.os }} + runs-on: ubuntu-latest steps: - name: Harden runner uses: step-security/harden-runner@v2.22.4 @@ -37,14 +35,5 @@ jobs: - uses: step-security/dtolnay-rust-toolchain@v1.0.0 with: toolchain: "1.95" - components: rustfmt, clippy targets: wasm32-unknown-unknown - - run: cargo fmt --check - - run: cargo clippy -p craft-vectorcraft-format --all-targets --locked -- -D warnings - - name: Docs (links and missing docs) - if: runner.os == 'Linux' - run: cargo doc -p craft-vectorcraft-format --no-deps --locked - env: - RUSTDOCFLAGS: -D warnings - - run: cargo test -p craft-vectorcraft-format --locked -- --nocapture - run: cargo check -p craft-vectorcraft-format --locked --target wasm32-unknown-unknown diff --git a/.github/workflows/video.yml b/.github/workflows/video.yml index a09f9bfe5..03b59cc42 100644 --- a/.github/workflows/video.yml +++ b/.github/workflows/video.yml @@ -11,6 +11,11 @@ on: permissions: contents: read +# A fraction of the fuzz-style cases, as in the Workspace gate; nightly.yml runs them in full. +env: + CRAFT_HOSTILE_DIVISOR: "8" + PROPTEST_CASES: "64" + concurrency: group: shared-video-${{ github.ref }} cancel-in-progress: true @@ -18,7 +23,8 @@ concurrency: jobs: lint: timeout-minutes: 20 - name: Video lint, feature sets, docs, WASM + # fmt and clippy with all features run in the Workspace gate on every OS. + name: Video feature sets, docs, WASM runs-on: ubuntu-latest steps: - name: Harden runner @@ -31,12 +37,8 @@ jobs: - uses: step-security/dtolnay-rust-toolchain@v1.0.0 with: toolchain: "1.95" - components: rustfmt, clippy + components: clippy targets: wasm32-unknown-unknown - - uses: step-security/rust-cache@v2.9.2 - with: - key: craft-video-lint - - run: cargo fmt -p craft-video --check # Each feature on its own, so code that needs another feature fails here. - name: Clippy, each feature alone run: | @@ -45,19 +47,15 @@ jobs: cargo clippy -p craft-video --all-targets --locked --no-default-features ${f:+--features "$f"} -- -D warnings echo "::endgroup::" done - - run: cargo clippy -p craft-video --all-targets --locked --all-features -- -D warnings - run: cargo doc -p craft-video --all-features --no-deps --locked env: RUSTDOCFLAGS: "-D warnings" - run: cargo check -p craft-video --all-features --locked --target wasm32-unknown-unknown test: timeout-minutes: 30 - strategy: - fail-fast: false - matrix: - os: ${{ github.ref == 'refs/heads/next' && fromJSON('["ubuntu-latest"]') || fromJSON('["ubuntu-latest","windows-latest"]') }} - runs-on: ${{ matrix.os }} - name: Video tests (${{ matrix.os }}) + # The Workspace gate runs these tests on every OS without ffmpeg; this runs them with it. + runs-on: ubuntu-latest + name: Video tests with ffmpeg steps: - name: Harden runner uses: step-security/harden-runner@v2.22.4 @@ -69,11 +67,7 @@ jobs: - uses: step-security/dtolnay-rust-toolchain@v1.0.0 with: toolchain: "1.95" - - uses: step-security/rust-cache@v2.9.2 - with: - key: craft-video-${{ matrix.os }} - - name: Install ffmpeg (Linux) - if: runner.os == 'Linux' + - name: Install ffmpeg run: | sudo rm -f /var/lib/man-db/auto-update sudo apt-get update -qq && sudo apt-get install -y -qq --no-install-recommends ffmpeg diff --git a/.github/workflows/web-api.yml b/.github/workflows/web-api.yml index 5b09d5155..0ad01e28f 100644 --- a/.github/workflows/web-api.yml +++ b/.github/workflows/web-api.yml @@ -12,10 +12,10 @@ permissions: contents: read concurrency: - # Pull requests share one group per branch, so a newer push cancels the older run. Every other - # run (main, manual) gets a group of its own, so it is neither cancelled nor replaced while queued. - group: web-api-${{ github.event_name == 'pull_request' && github.ref || github.run_id }} - cancel-in-progress: ${{ github.event_name == 'pull_request' }} + # One group per pull request and per branch: a newer push cancels the run it supersedes, on main + # too, since the newest run checks everything before it. + group: web-api-${{ github.ref }} + cancel-in-progress: true jobs: web-api: @@ -35,7 +35,7 @@ jobs: - uses: step-security/dtolnay-rust-toolchain@v1.0.0 with: toolchain: stable - components: rustfmt, clippy + components: clippy targets: wasm32-unknown-unknown - name: Read the wasm-bindgen version from Cargo.lock id: wasm-bindgen @@ -50,12 +50,6 @@ jobs: with: tool: wasm-bindgen@${{ steps.wasm-bindgen.outputs.version }} fallback: cargo-install - - run: cargo fmt --check - - run: cargo clippy -p craft-web-api --all-targets --locked -- -D warnings + # fmt, native clippy and the native tests run in the Workspace gate. - run: cargo clippy -p craft-web-api --all-targets --locked --target wasm32-unknown-unknown -- -D warnings - - name: Docs (links and missing docs) - run: cargo doc -p craft-web-api --no-deps --locked - env: - RUSTDOCFLAGS: -D warnings - - run: cargo test -p craft-web-api --locked - run: cargo test -p craft-web-api --locked --target wasm32-unknown-unknown diff --git a/.github/workflows/web-host.yml b/.github/workflows/web-host.yml index 7463cc1f8..055303bc2 100644 --- a/.github/workflows/web-host.yml +++ b/.github/workflows/web-host.yml @@ -12,16 +12,16 @@ permissions: contents: read concurrency: - # Pull requests share one group per branch, so a newer push cancels the older run. Every other - # run (main, manual) gets its own group: it is never cancelled or replaced while queued, so it - # always gets to save the cache. - group: shared-web-host-${{ github.event_name == 'pull_request' && github.ref || github.run_id }} - cancel-in-progress: ${{ github.event_name == 'pull_request' }} + # One group per pull request and per branch: a newer push cancels the run it supersedes, on main + # too, since the newest run checks everything before it. + group: shared-web-host-${{ github.ref }} + cancel-in-progress: true jobs: check: timeout-minutes: 20 - name: Web host lint, tests, WASM tests + # fmt, native clippy and the native tests run in the Workspace gate. + name: Web host WASM lint and tests runs-on: ubuntu-latest env: CARGO_TARGET_WASM32_UNKNOWN_UNKNOWN_RUNNER: wasm-bindgen-test-runner @@ -36,20 +36,9 @@ jobs: - uses: step-security/dtolnay-rust-toolchain@v1.0.0 with: toolchain: stable - components: rustfmt, clippy + components: clippy targets: wasm32-unknown-unknown - - uses: step-security/rust-cache@v2.9.2 - with: - key: craft-web-host - save-if: ${{ github.ref == 'refs/heads/main' }} - - run: cargo fmt -p craft-web-host --check - - run: cargo clippy -p craft-web-host --all-targets --locked -- -D warnings - run: cargo clippy -p craft-web-host --all-targets --locked --target wasm32-unknown-unknown -- -D warnings - - name: Docs (links and missing docs) - run: cargo doc -p craft-web-host --no-deps --locked - env: - RUSTDOCFLAGS: -D warnings - - run: cargo test -p craft-web-host --locked - name: Read the wasm-bindgen version from Cargo.lock id: wasm-bindgen shell: bash diff --git a/.github/workflows/window.yml b/.github/workflows/window.yml index 73372ce56..a534393fd 100644 --- a/.github/workflows/window.yml +++ b/.github/workflows/window.yml @@ -12,20 +12,18 @@ permissions: contents: read concurrency: - # Pull requests share one group per branch, so a newer push cancels the older run. Every other - # run (main, manual) gets a group of its own, so it is neither cancelled nor replaced while queued. - group: window-${{ github.event_name == 'pull_request' && github.ref || github.run_id }} - cancel-in-progress: ${{ github.event_name == 'pull_request' }} + # One group per pull request and per branch: a newer push cancels the run it supersedes, on main + # too, since the newest run checks everything before it. + group: window-${{ github.ref }} + cancel-in-progress: true +# fmt, clippy and the tests with default and with all features run in the Workspace gate on every +# OS; this runs the ui feature alone. jobs: window: + name: Window with ui alone timeout-minutes: 15 - strategy: - fail-fast: false - matrix: - # macOS runners are kept for releases: macOS runs only when started by hand. - os: ${{ github.event_name == 'workflow_dispatch' && fromJSON('["ubuntu-latest","windows-latest","macos-latest"]') || github.ref == 'refs/heads/next' && fromJSON('["ubuntu-latest"]') || fromJSON('["ubuntu-latest","windows-latest"]') }} - runs-on: ${{ matrix.os }} + runs-on: ubuntu-latest steps: - name: Harden runner uses: step-security/harden-runner@v2.22.4 @@ -39,15 +37,6 @@ jobs: - uses: step-security/dtolnay-rust-toolchain@v1.0.0 with: toolchain: stable - components: rustfmt, clippy - - run: cargo fmt --check - # Default (no egui) and the ui feature both build and lint cleanly. - - run: cargo clippy -p craft-window --all-targets --locked -- -D warnings + components: clippy - run: cargo clippy -p craft-window --all-targets --locked --features ui -- -D warnings - - name: Docs (links and missing docs) - if: runner.os == 'Linux' - run: cargo doc -p craft-window --no-deps --locked - env: - RUSTDOCFLAGS: -D warnings - - run: cargo test -p craft-window --locked -- --nocapture - run: cargo test -p craft-window --locked --features ui -- --nocapture diff --git a/.github/workflows/workspace.yml b/.github/workflows/workspace.yml index 3e7f07d8a..6a88886d4 100644 --- a/.github/workflows/workspace.yml +++ b/.github/workflows/workspace.yml @@ -6,70 +6,111 @@ on: tags: ["v*"] pull_request: workflow_dispatch: + # A full run on main every 6 hours that is never cancelled, so the caches are saved while pushes + # to main cancel each other. + schedule: + - cron: "17 */6 * * *" permissions: contents: read concurrency: - # Pull requests share one group per branch, so a newer push cancels the older run. Every other - # run (push to main, a release tag, a manual run) gets a group of its own: it is neither - # cancelled nor replaced while queued, so a main run always finishes and saves the dependency - # cache, and a release run is never cancelled. - group: workspace-${{ github.event_name == 'pull_request' && github.ref || github.run_id }} - cancel-in-progress: ${{ github.event_name == 'pull_request' }} + # A pull request, and main, each have one group, so a newer push cancels the run it supersedes; + # the newest push's run still tests everything before it. Every other run (a release tag, a + # manual run, the scheduled run) gets a group of its own and is neither cancelled nor replaced + # while queued: a release run always finishes, and the scheduled run saves the caches. + group: workspace-${{ (github.event_name == 'pull_request' || github.event_name == 'push' && github.ref == 'refs/heads/main') && github.ref || github.run_id }} + cancel-in-progress: ${{ github.event_name == 'pull_request' || github.event_name == 'push' && github.ref == 'refs/heads/main' }} jobs: native: name: Workspace uses: storytold/craft-common-actions/.github/workflows/gate.yml@main with: + # Pushes to next run Linux only. os: ${{ github.ref == 'refs/heads/next' && '["ubuntu-latest"]' || '["ubuntu-latest","windows-latest","macos-latest"]' }} + # On a pull request, macOS and Windows run only when it can change platform behaviour: a + # crate with platform cfg code or one that depends on it, the build setup, or a file outside + # the crates (craft-common-actions' select-platforms). The full-ci label runs them anyway + # from the next push or manual run; pushes to main always run every leg. A push to next has + # only the Linux leg, so it selects none. + select-os: ${{ github.ref == 'refs/heads/next' && '[]' || '["windows-latest","macos-latest"]' }} timeout-minutes: 120 - # The Windows leg runs its tests with nextest (.config/nextest.toml). + # Every leg runs its tests with nextest, and its doctests with cargo test (.config/nextest.toml). tools: cargo-nextest@0.9.150 packages: mesa-vulkan-drivers libvulkan1 craft-fonts-ref: b076417b5880bd4154bd22f00695b1d28c6bea83 linux-env: WGPU_BACKEND=vulkan - windows-env: CRAFT_PRINT_REQUIRE_QUEUE=1 - env: CRAFT_PRINT_REQUIRE_QUEUE=0 - setup-command: | - set -euo pipefail - corpus_fetcher=.test-inputs/photocraft - mkdir -p "$corpus_fetcher" - git -C "$corpus_fetcher" init - git -C "$corpus_fetcher" remote add origin https://github.com/storytold/PhotoCraft.git - git -C "$corpus_fetcher" fetch --quiet --depth=1 origin 74330157cb601573ae4523a95bb9132822fc3918 - git -C "$corpus_fetcher" checkout --quiet --detach FETCH_HEAD - (cd "$corpus_fetcher" && cargo xtask corpus --psd --psd-tools --atn --exr --heif --pngsuite) - mkdir -p corpus - cp -a "$corpus_fetcher/corpus/." corpus/ - python scripts/test-fetch-pdf-test-fonts.py - python scripts/fetch-pdf-test-fonts.py "$RUNNER_TEMP/craft-pdf-test-fonts" - printf 'CRAFT_PSD_CORPUS=%s\n' "$GITHUB_WORKSPACE/$corpus_fetcher/corpus" >> "$GITHUB_ENV" - printf 'CRAFT_PDF_TEST_FONT_DIR=%s\n' "$RUNNER_TEMP/craft-pdf-test-fonts" >> "$GITHUB_ENV" + # Test binaries without debug info or symbols: about a third of the size, and a panic still + # names its file and line. + dev-strip: true + # No debuginfo on Windows: writing PDBs for every test binary is a large part of its link + # time. A panic still names its file and line; only backtrace frames lose theirs, and the + # Linux and macOS legs keep line tables. + # rust-lld links the test binaries faster than link.exe; /OPT:NOICF skips identical-code + # folding and /DEBUG:NONE writes no PDB, both of which only cost link time here. + windows-env: | + CRAFT_PRINT_REQUIRE_QUEUE=1 + CARGO_PROFILE_DEV_DEBUG=0 + CARGO_TARGET_X86_64_PC_WINDOWS_MSVC_LINKER=rust-lld + CARGO_TARGET_X86_64_PC_WINDOWS_MSVC_RUSTFLAGS=-Clink-arg=/OPT:NOICF -Clink-arg=/DEBUG:NONE + # The fuzz-style tests run a fraction of their cases here: every hostile-input hammer and + # sweep 1/8 (craft-testkit's CRAFT_HOSTILE_DIVISOR), every proptest without its own case + # count 64 cases instead of 256. nightly.yml runs them all in full. + env: | + CRAFT_PRINT_REQUIRE_QUEUE=0 + CRAFT_HOSTILE_DIVISOR=8 + PROPTEST_CASES=64 + setup-command: bash scripts/ci-test-inputs.sh + # The PhotoCraft corpora, keyed on the script that pins them: a hit skips the PhotoCraft + # checkout and its xtask build (1:51 on Windows). + cache-paths: .test-inputs/photocraft/corpus + cache-key: photocraft-corpus + cache-key-files: scripts/ci-test-inputs.sh + # A `lint ()` leg beside each `gate ()` leg, so clippy is off the tests' critical path. + lint-command: | + if [ "$RUNNER_OS" = Linux ]; then + python3 scripts/test-workspace-concurrency.py + python3 scripts/test-workspace-tests.py + fi + # One rustfmt call gets every source root of the workspace, which is longer than + # Windows allows for a command line (os error 206). rustfmt's result is the same on + # every system, so the Linux and macOS legs check it. + if [ "$RUNNER_OS" != Windows ]; then + cargo fmt --check + fi + cargo clippy --workspace --all-targets --locked -- -D warnings + cargo clippy --workspace --all-targets --all-features --locked -- -D warnings + # A push to main builds the gate's test binaries in their own leg and saves the cache right + # after, so a failing test no longer keeps the cache from being saved. The same two builds + # the gate's nextest runs do (all features; the two crates with default features). + warm-command: | + cargo test --workspace --no-run --all-features --locked + cargo test -p craft-image-codecs -p craft-text --no-run --locked command: | - python3 scripts/test-workspace-concurrency.py - cargo fmt --check - cargo clippy --workspace --all-targets --locked --keep-going -- -D warnings - cargo clippy --workspace --all-targets --all-features --locked --keep-going -- -D warnings - cargo test --workspace --locked - cargo test --workspace --all-features --locked + # The tests run once, with every feature, in parallel across test binaries; nextest skips + # doctests, so `cargo test --doc` runs them. Examples are not built, except the two whose + # tests run (stubicc, h264_h264enc_bench); clippy in the lint leg covers the rest. The default-feature compile is the lint leg's + # first clippy run; the last command runs the crates whose tests check behaviour with a + # feature off, which an all-features build cannot reach. + cargo nextest run --workspace --all-features --locked --profile ci --lib --bins --tests + cargo nextest run -p craft-aep -p craft-video --all-features --locked --profile ci --example stubicc --example h264_h264enc_bench + cargo test --workspace --doc --all-features --locked + cargo nextest run -p craft-image-codecs -p craft-text --locked --profile ci --lib --bins --tests windows-command: | powershell.exe -NoProfile -Command '$ErrorActionPreference = "Stop"; Start-Service Spooler; Add-PrinterDriver -Name "Generic / Text Only"' - cargo fmt --check - cargo clippy --workspace --all-targets --locked --keep-going -- -D warnings - cargo clippy --workspace --all-targets --all-features --locked --keep-going -- -D warnings - # The same tests as `cargo test`, run in parallel across test binaries instead of one - # binary at a time; nextest skips doctests, so `cargo test --doc` runs them. - cargo nextest run --workspace --locked --profile ci - cargo test --workspace --doc --locked - cargo nextest run --workspace --all-features --locked --profile ci + cargo nextest run --workspace --all-features --locked --profile ci --lib --bins --tests + cargo nextest run -p craft-aep -p craft-video --all-features --locked --profile ci --example stubicc --example h264_h264enc_bench cargo test --workspace --doc --all-features --locked + cargo nextest run -p craft-image-codecs -p craft-text --locked --profile ci --lib --bins --tests msrv: name: Rust 1.95 uses: storytold/craft-common-actions/.github/workflows/gate.yml@main with: + # Its own dependency-cache entry: the calls in this file share one job id, so without a name + # they would write the same key. + cache-name: msrv os: '["ubuntu-latest"]' toolchain: 1.95.0 targets: "" @@ -84,6 +125,7 @@ jobs: name: UI and settings WASM uses: storytold/craft-common-actions/.github/workflows/gate.yml@main with: + cache-name: wasm os: '["ubuntu-latest"]' targets: wasm32-unknown-unknown tools: "" diff --git a/ATTRIBUTION.md b/ATTRIBUTION.md index e12acfa77..56430f5bb 100644 --- a/ATTRIBUTION.md +++ b/ATTRIBUTION.md @@ -11,6 +11,7 @@ author, source and license. Library code and original assets are under the repos | `licenses/dwg/acadrust-MPL-2.0.txt`, `licenses/dwg/acadrust-THIRD_PARTY_NOTICES.md` | `acadrust` contributors; ACadSharp authors for the noted ported routines | [acadrust 0.6.6](https://github.com/hakanaktt/acadrust), used unmodified as `craft-dwg`'s optional native dependency | MPL-2.0; embedded ACadSharp notice is MIT; see both retained files | | `crates/cms/profiles/photocraft-coated-cmyk.icc` | PhotoCraft contributors; generated by `craft_cms::synth::coated_cmyk` | [PhotoCraft `crates/cms`](https://github.com/storytold/photocraft/tree/b3222ee8e7e6bcb4799c37f904c595f20f9baf5e/crates/cms) | CC0-1.0 | | `crates/cms/profiles/craft-coated-fogra39.icc` | craft-libs contributors; generated by `crates/cms/tests/fogra39.rs` from the FOGRA39 data below | this repository | CC0-1.0 | +| `crates/ppt-binary/tests/fixtures/old-talk.pps` | DeckCraft contributors; a one-slide PowerPoint 97-2003 show built from records by `crates/ppt-binary/src/tests.rs` (`the_pps_fixture_is_a_built_presentation`, with `CRAFT_WRITE_PPT_FIXTURE=1`); no PowerPoint involved | [storytold/deckcraft#1137](https://github.com/storytold/deckcraft/pull/1137) | CC0-1.0 | | `crates/font-store/index/sources.json` (unmodified) | craft-font-index contributors | [aiongg/craft-font-index@5a9a7f8](https://github.com/aiongg/craft-font-index/tree/5a9a7f8038c8f3e2e1583a79c92a816e8e71b34f) | Apache-2.0 | | `crates/font-store/index/indexes/google-fonts.json.gz` (unmodified) | craft-font-index contributors; generated from the METADATA.pb files of [google/fonts](https://github.com/google/fonts) at `45e3d5269e4a17d823f6d84470bc084dc5ae46f6` | [aiongg/craft-font-index@5a9a7f8](https://github.com/aiongg/craft-font-index/tree/5a9a7f8038c8f3e2e1583a79c92a816e8e71b34f) | Apache-2.0 | | `crates/font-store/index/indexes/noto.json.gz` (unmodified) | craft-font-index contributors; generated from [notofonts/notofonts.github.io](https://github.com/notofonts/notofonts.github.io) at `93fac8abebe6c7fed0c5b7d2456d8fa484fa146c` and [noto-cjk](https://github.com/notofonts/noto-cjk) releases | [aiongg/craft-font-index@5a9a7f8](https://github.com/aiongg/craft-font-index/tree/5a9a7f8038c8f3e2e1583a79c92a816e8e71b34f) | Apache-2.0 | @@ -123,6 +124,16 @@ The XML reader in `crates/plist/src/xml.rs` and its base64 compatibility helper `crates/palette` extracts the GPL text parser from AniCraft `crates/doc/src/swatch.rs` at `d875a7feb250e6ab06aa28a37fb78a0699e88330` (MIT OR Apache-2.0), introduced by Tanish Manku in `a64130a9da9bdde545463b852d95d6a6774b1dfd` (AniCraft #270). The import preserves Tanish as primary author. Neutral RGB/name adaptation separates application display-name sanitization and the `Untitled` policy; validation tests and integration are subsequent Dylan M. Taylor changes. The legacy ZIP Zstandard method-20 mapping and bounded-read regression in `crates/zip/src/lenient` are ported from RRFZ's Craft Anything commit `29badae7c9280fdf4c24795927bf3a91f51694c6` (MIT OR Apache-2.0). RRFZ remains the primary Git author. Firmware scanner detection remains app-owned and is not part of this port. +<<<<<<< HEAD +======= +## TAR/CPIO compatibility updates + +The old GNU sparse-extension traversal, GNU CRC-symlink compatibility and PAX-size precedence fixes and their regression tests in `crates/tar` are ported from RRFZ's Craft Anything PRs #1973 (`8ea2ec66a1bc80f0420f3695baac877a0cb9b9a5`), #1984 (`b226a475f7dce9710e3af7a069386fe7a9720df7`) and #2007 (`d29465c20b0d570ea4973be512a0cb4e212bb60f`). Source is MIT OR Apache-2.0; RRFZ remains the primary Git author of each port. The PAX update adapts to the shared parser's existing `PaxOverrides` structure without changing the source policy. + +## Aligned stored ZIP entries + +The USDZ alignment requirement and compatibility fixture for `Writer::add_stored_aligned` come from TextureCraft `crates/formats/src/mesh_export/usd.rs`, introduced by bflatastic in `bdbb52c9` and maintained through `9eb20086` (MIT OR Apache-2.0). The shared API and alignment validation are subsequent Dylan M. Taylor work. Scene/material mapping remains in TextureCraft. +>>>>>>> up/next The raw gradient wire ordering in `craft-lottie::Gradient::flat_values` follows AniCraft's Lottie exporter by Tanish Manku (`63b39355`, `b9258b7b`), MIT OR Apache-2.0. @@ -132,6 +143,48 @@ Sanitization, animation fitting and numeric output policy remain caller-owned. `crates/video/src/screen_video.rs` extracts AniCraft `crates/xfl/src/video.rs` codec-3 decoding and its synthetic partial-block fixture, introduced by Tanish Manku in `1f3e603b7ff53a3da364e41ec4da8d43dc83aab0` with pixel-loop cleanup `2b7571363b4b647266df758f95b6e397021cfd4d` (MIT OR Apache-2.0). Import commits preserve Tanish as primary author. Caller-owned bounds and neutral RGBA output separate codec work from the consuming app's FLV first-frame/report policy. Boundary tests and integration are subsequent Dylan M. Taylor changes. +<<<<<<< HEAD ## Aligned stored ZIP entries The USDZ alignment requirement and compatibility fixture for `Writer::add_stored_aligned` come from TextureCraft `crates/formats/src/mesh_export/usd.rs`, introduced by bflatastic in `bdbb52c9` and maintained through `9eb20086` (MIT OR Apache-2.0). The shared API and alignment validation are subsequent Dylan M. Taylor work. Scene/material mapping remains in TextureCraft. +======= +## Source Map v3 parser and lookup + +`crates/sourcemap` extracts the bounded parser, source inventory and generated-position lookup from Craft Anything `crates/formats/src/sourcemap.rs` at `e5c9c94106747ed44b9a3fb0decce867c2285f93` (MIT OR Apache-2.0). Core-history ports preserve Brandon Thomas, BFlat, Afloat, RRFZ, Nicolas Bohn and Alex Joaquim Pereira as primary authors, with exact source revisions in each commit. Six regression files preserve their source authors; nine core unit tests retain the original tests. App annotation scanning, data URLs, base64 and file I/O are intentionally not imported. Workspace wiring is a subsequent change; existing limits and errors are unchanged. +## JSONC span-preserving editing + +`crates/jsonc` is extracted from Craft Anything `crates/formats/src/jsonc.rs` at `e5c9c94106747ed44b9a3fb0decce867c2285f93` (MIT OR Apache-2.0). The original implementation and hardening by BFlat, newline preservation by NetterSilver, and subsequent RRFZ/Afloat correctness fixes retain separate primary-author port commits with immutable source revisions. Shared API wiring and optional input-byte admission are subsequent changes. Compatibility parsing and all existing formatting/editing tests are retained; application file I/O and policy are not imported. + +## XFA XML DOM + +`crates/xfa/src/xml.rs` is extracted from PDFCraft at `271e479c53723b1b294c866d5cb2f27604601b29`, originally by Dylan M. Taylor (`eead4541`, `7d44e654`), MIT OR Apache-2.0. The initial extraction changes visibility and module boundaries; subsequent namespace-retention budget hardening intentionally tightens resource admission. PDF/layout/form policy remains in the app. + +## Java class inspection + +`crates/java-class` extracts Craft Anything `java_class.rs` and `java_ops.rs` at `5979f9b13f16dcf1df3c7ae7f8e7735f452866f2` (MIT OR Apache-2.0), preserving separate primary-author source-history ports by Brandon Thomas, BFlat, Afloat and RRFZ. The checked byte-reader, modified UTF-8 unit decoder, descriptor display helper and synthetic class fixtures come from the same source snapshot. Seven regression files retain their source authors. Neutral error wiring and shared crate integration are subsequent changes. No JAR archive, application I/O or bytecode execution is imported. + +## WebAssembly inspection + +`crates/wasm` extracts Craft Anything `crates/formats/src/wasm.rs` at `5979f9b13f16dcf1df3c7ae7f8e7735f452866f2`, with its checked byte-reader subset and original synthetic WASM/testkit fixtures (MIT OR Apache-2.0). Eight core-history ports preserve Brandon Thomas, Afloat and RRFZ as primary authors; component, repeated-custom-section and referenced-string regression imports retain source authors and commit references. Fixtures come from `crates/testkit/src/formats.rs` and deterministic mutation helpers from `crates/testkit/src/lib.rs`; no third-party binaries. Shared error naming and workspace wiring are subsequent changes. Existing inspection limits and report behavior are unchanged; this crate validates/inspects/renders, never executes modules. + +## Packet capture and protocol inspection + +`crates/pcap` extracts Craft Anything `crates/formats/src/pcap.rs`, its checked byte reader primitives and synthetic packet fixtures/regressions at `5979f9b13f16dcf1df3c7ae7f8e7735f452866f2` (MIT OR Apache-2.0). Brandon Thomas introduced the implementation, byte reader and fixtures in `f64ae3bf3c8863a982af1304e06de20653803968`. Subsequent fixes by phatloi0010, GGWA, BFlat, Afloat, NetterSilver, Max Mittelstädt and RRFZ retain separate primary-author source-history commits with immutable source revisions. Shared error/API wiring and chrono-based timestamp formatting with exhaustive day-boundary parity tests are subsequent Dylan M. Taylor changes. No packet reassembly, decryption, live capture or app analysis policy is imported. +## HTTP Archive reader + +`crates/har` preserves Craft Anything `crates/formats/src/har.rs` from `5979f9b13f16dcf1df3c7ae7f8e7735f452866f2` (MIT OR Apache-2.0). Brandon Thomas introduced the typed reader in `f64ae3bf3c8863a982af1304e06de20653803968`; BFlat added UTF-8 BOM compatibility in `cb0bb9d8fa4536ba44ef2c86f5ed759b879cc2d3`. Both source snapshots retain primary author attribution. Shared wiring, explicit byte admission and its tests are subsequent Dylan M. Taylor changes. Redaction and analysis remain app-owned. + +## Dalvik DEX inspection + +`crates/dex` extracts Craft Anything `crates/formats/src/dex.rs` and `dex_ops.rs` at `5979f9b13f16dcf1df3c7ae7f8e7735f452866f2` (MIT OR Apache-2.0). Five source-history ports preserve Brandon Thomas, BFlat and Afloat as primary authors. Five regression imports retain BFlat/Afloat authors and exact source revisions. The checked byte-reader/MUTF-8 subset and synthetic DEX fixture come from that app's `bytes.rs` and `testkit/src/android.rs`; deterministic noise/mutations come from its testkit. No application file I/O, APK logic or execution is imported. Shared neutral errors and workspace wiring are subsequent changes; existing per-file strings, member/handler and bytecode payload budgets are retained. + +## EVM bytecode inspection + +`crates/evm` extracts Craft Anything `crates/formats/src/evm.rs` at `a31e995858f4312e0f1d59a007112da191ef2d26` (MIT OR Apache-2.0). Eight separate source-history ports preserve Brandon Thomas, Afloat, RRFZ and NetterSilver as primary authors with immutable source references. Synthetic EVM fixtures and deterministic mutation helpers come from the same app source; regression files retain their source provenance. Neutral errors and workspace integration are subsequent changes. No code execution or transaction behavior is imported. + +## XFDF field reader + +`crates/xfdf` extracts PDFCraft field reading from #5937 refresh `cb564fd827f572818e9ddb0ea5989a432b1f39fd` (MIT OR Apache-2.0). App-side annotation and form policy remains local; source history is retained in the original repository. + +Retained XFDF source contributors (move-aware blame): Brandon Thomas, Marco Arnulfo, pkibiego and storybored379; module split by aiongg. Subsequent budget/integration work by Dylan M. Taylor. +>>>>>>> up/next diff --git a/Cargo.lock b/Cargo.lock index c76065dae..3955d55bb 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -290,6 +290,17 @@ version = "1.0.104" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "330a5ed07fa54e4702c9d6c4174f74427fc0ef6e214bbd677ae50a5099946470" +[[package]] +name = "apple-native-keyring-store" +version = "1.0.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2b350bfd03649e07aa05c0a81b3e15934374e585c98204a57e20b9d49f49bb9a" +dependencies = [ + "keyring-core", + "log", + "security-framework", +] + [[package]] name = "arbitrary" version = "1.5.0" @@ -1188,6 +1199,18 @@ dependencies = [ "winx", ] +[[package]] +name = "cap-std" +version = "4.0.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c1ec78e242cfa2cfe276807ac2ecc00315a6c97786977414bcd1c3963b6c91b8" +dependencies = [ + "cap-primitives", + "io-extras", + "io-lifetimes 3.0.1", + "rustix 1.1.5", +] + [[package]] name = "cast" version = "0.3.0" @@ -1729,9 +1752,13 @@ dependencies = [ "craft-browse", "craft-captions", "craft-cfb", + "craft-cloud", + "craft-cloud-local", + "craft-cloud-ui", "craft-cms", "craft-codepage", "craft-color", + "craft-color-transform", "craft-color-ui", "craft-control", "craft-control-protocol", @@ -1742,6 +1769,9 @@ dependencies = [ "craft-dds", "craft-deckcraft-format", "craft-designcraft-format", + "craft-develop", + "craft-develop-model", + "craft-dex", "craft-dialogs", "craft-doc", "craft-doc-binary", @@ -1757,6 +1787,8 @@ dependencies = [ "craft-elf", "craft-eps", "craft-epub", + "craft-esign", + "craft-evm", "craft-ews", "craft-exr", "craft-fcproj-format", @@ -1775,10 +1807,18 @@ dependencies = [ "craft-frame", "craft-gainmap", "craft-gcode", + "craft-geom", "craft-gif", "craft-gpu", +<<<<<<< HEAD +======= + "craft-gpu-null", + "craft-gpu-providers", + "craft-gpu-wgpu", +>>>>>>> up/next "craft-gridcraft-format", "craft-gzip", + "craft-har", "craft-hdr", "craft-heif", "craft-host", @@ -1791,8 +1831,11 @@ dependencies = [ "craft-imaging", "craft-indd", "craft-ipc", + "craft-ipp", + "craft-java-class", "craft-jmap", "craft-jpeg", + "craft-jsonc", "craft-jsonrpc", "craft-jxl", "craft-keymap", @@ -1824,6 +1867,7 @@ dependencies = [ "craft-ora", "craft-pages", "craft-palette", + "craft-pcap", "craft-pcraft-bundle", "craft-pcraft-format", "craft-pdf 0.1.0", @@ -1834,6 +1878,7 @@ dependencies = [ "craft-platform", "craft-plist", "craft-plotter", + "craft-ppt-binary", "craft-pptx", "craft-prc", "craft-prepress", @@ -1859,10 +1904,12 @@ dependencies = [ "craft-sketch", "craft-smime", "craft-sniff", + "craft-sourcemap", "craft-ssip", "craft-stencilcraft-document", "craft-stencilcraft-format", "craft-stream-codecs", + "craft-suite-account", "craft-svg", "craft-table", "craft-tar", @@ -1871,10 +1918,12 @@ dependencies = [ "craft-texture", "craft-tga", "craft-theme", + "craft-theme-editor", "craft-theme-store", "craft-tiff", "craft-time", "craft-timeline", + "craft-tracked", "craft-ui", "craft-update", "craft-usd", @@ -1882,12 +1931,15 @@ dependencies = [ "craft-vectorcraft-format", "craft-vectordrawable", "craft-video", + "craft-wasm", "craft-web-api", "craft-web-host", "craft-webp", "craft-window", "craft-wordmodel", "craft-xcf", + "craft-xfa", + "craft-xfdf", "craft-xfl", "craft-xls", "craft-xlsx", @@ -1944,7 +1996,7 @@ dependencies = [ [[package]] name = "craft-ai-agents" version = "0.1.0" -source = "git+https://github.com/storytold/craft-ai-integrations?rev=35e0352666a117407d62230a6c6c2366f3e21a3b#35e0352666a117407d62230a6c6c2366f3e21a3b" +source = "git+https://github.com/storytold/craft-ai-integrations?rev=d94a3593adcff504eaaad9e5aee4c84fd2f07a72#d94a3593adcff504eaaad9e5aee4c84fd2f07a72" dependencies = [ "dirs", "serde", @@ -2004,10 +2056,8 @@ name = "craft-automation" version = "0.1.0" dependencies = [ "base64 0.22.1", - "craft-ai-agents", - "craft-atomic", "craft-behavior", - "craft-flags", + "craft-control", "craft-host", "craft-keymap", "craft-platform", @@ -2068,6 +2118,7 @@ dependencies = [ name = "craft-captions" version = "0.1.0" dependencies = [ + "craft-media", "craft-media-testkit", "craft-timeline", "craft-xml", @@ -2083,6 +2134,37 @@ dependencies = [ "craft-media-testkit", ] +[[package]] +name = "craft-cloud" +version = "0.1.0" +dependencies = [ + "serde", + "thiserror 2.0.21", +] + +[[package]] +name = "craft-cloud-local" +version = "0.1.0" +dependencies = [ + "cap-std", + "craft-cloud", + "craft-ui", + "egui", + "tempfile", +] + +[[package]] +name = "craft-cloud-ui" +version = "0.1.0" +dependencies = [ + "craft-cloud", + "craft-esign", + "egui", + "egui_kittest", + "image", + "serde_json", +] + [[package]] name = "craft-cms" version = "0.1.0" @@ -2107,6 +2189,16 @@ dependencies = [ "serde", ] +[[package]] +name = "craft-color-transform" +version = "0.1.0" +dependencies = [ + "craft-cms", + "craft-color", + "serde", + "serde_json", +] + [[package]] name = "craft-color-ui" version = "0.1.0" @@ -2131,10 +2223,15 @@ dependencies = [ name = "craft-control" version = "0.1.0" dependencies = [ + "craft-ai-agents", + "craft-atomic", + "craft-flags", "getrandom 0.3.4", + "log", "proptest", "serde", "serde_json", + "tempfile", ] [[package]] @@ -2201,6 +2298,7 @@ dependencies = [ name = "craft-design-lint" version = "0.1.0" dependencies = [ + "dunce", "proc-macro2", "quote", "serde", @@ -2221,6 +2319,38 @@ dependencies = [ "thiserror 2.0.21", ] +[[package]] +name = "craft-develop" +version = "0.1.0" +dependencies = [ + "craft-develop-model", + "craft-render-parity", + "proptest", + "rayon", + "serde", +] + +[[package]] +name = "craft-develop-model" +version = "0.1.0" +dependencies = [ + "craft-geom", + "craft-metadata", + "miniz_oxide 0.9.1", + "proptest", + "serde", + "serde_json", +] + +[[package]] +name = "craft-dex" +version = "0.1.0" +dependencies = [ + "craft-testkit", + "serde", + "thiserror 2.0.21", +] + [[package]] name = "craft-dialogs" version = "0.1.0" @@ -2271,6 +2401,7 @@ dependencies = [ "craft-wordmodel", "image", "log", + "md4", "miniz_oxide 0.9.1", "proptest", "serde_json", @@ -2412,6 +2543,26 @@ dependencies = [ "zip 9.1.3", ] +[[package]] +name = "craft-esign" +version = "0.1.0" +dependencies = [ + "craft-cloud", + "serde", + "serde_json", + "thiserror 2.0.21", +] + +[[package]] +name = "craft-evm" +version = "0.1.0" +dependencies = [ + "craft-testkit", + "serde", + "serde_json", + "thiserror 2.0.21", +] + [[package]] name = "craft-ews" version = "0.1.0" @@ -2645,6 +2796,14 @@ dependencies = [ "thiserror 2.0.21", ] +[[package]] +name = "craft-geom" +version = "0.1.0" +dependencies = [ + "proptest", + "serde", +] + [[package]] name = "craft-gif" version = "0.1.0" @@ -2657,10 +2816,41 @@ dependencies = [ name = "craft-gpu" version = "0.1.0" dependencies = [ +<<<<<<< HEAD "egui-wgpu", "log", "pollster 1.0.1", "tempfile", +======= + "serde", + "serde_json", + "thiserror 2.0.21", +] + +[[package]] +name = "craft-gpu-null" +version = "0.1.0" +dependencies = [ + "craft-gpu", +] + +[[package]] +name = "craft-gpu-providers" +version = "0.1.0" +dependencies = [ + "craft-gpu", + "craft-gpu-null", +] + +[[package]] +name = "craft-gpu-wgpu" +version = "0.1.0" +dependencies = [ + "craft-gpu", + "craft-gpu-providers", + "pollster 0.4.0", + "wgpu", +>>>>>>> up/next ] [[package]] @@ -2679,6 +2869,14 @@ dependencies = [ "flate2", ] +[[package]] +name = "craft-har" +version = "0.1.0" +dependencies = [ + "serde_json", + "thiserror 2.0.21", +] + [[package]] name = "craft-hdr" version = "0.1.0" @@ -2777,6 +2975,7 @@ dependencies = [ "craft-dds", "craft-heif", "craft-jpeg", + "craft-jxl", "craft-media-testkit", "craft-metadata", "craft-tiff", @@ -2844,6 +3043,19 @@ dependencies = [ "widestring", ] +[[package]] +name = "craft-ipp" +version = "0.1.0" + +[[package]] +name = "craft-java-class" +version = "0.1.0" +dependencies = [ + "craft-testkit", + "serde", + "thiserror 2.0.21", +] + [[package]] name = "craft-jmap" version = "0.1.0" @@ -2863,6 +3075,13 @@ dependencies = [ "zune-jpeg", ] +[[package]] +name = "craft-jsonc" +version = "0.1.0" +dependencies = [ + "serde_json", +] + [[package]] name = "craft-jsonrpc" version = "0.1.0" @@ -2875,6 +3094,7 @@ dependencies = [ name = "craft-jxl" version = "0.1.0" dependencies = [ + "brotli-decompressor 5.0.3", "craft-cms", "jixel", "jxl-oxide", @@ -3222,6 +3442,16 @@ dependencies = [ name = "craft-palette" version = "0.1.0" +[[package]] +name = "craft-pcap" +version = "0.1.0" +dependencies = [ + "chrono", + "serde", + "serde_json", + "thiserror 2.0.21", +] + [[package]] name = "craft-pcraft-bundle" version = "0.1.0" @@ -3409,10 +3639,24 @@ dependencies = [ name = "craft-plotter" version = "0.1.0" dependencies = [ + "kurbo", "serde", "thiserror 2.0.21", ] +[[package]] +name = "craft-ppt-binary" +version = "0.1.0" +dependencies = [ + "craft-cfb", + "craft-drawingml", + "craft-pptx", + "image", + "log", + "miniz_oxide 0.8.9", + "thiserror 2.0.21", +] + [[package]] name = "craft-pptx" version = "0.1.0" @@ -3551,6 +3795,7 @@ name = "craft-raster-codecs" version = "0.1.0" dependencies = [ "base64 0.23.1", + "craft-dds", "craft-image-codecs", "image", "thiserror 2.0.21", @@ -3727,6 +3972,15 @@ dependencies = [ name = "craft-sniff" version = "0.1.0" +[[package]] +name = "craft-sourcemap" +version = "0.1.0" +dependencies = [ + "serde", + "serde_json", + "thiserror 2.0.21", +] + [[package]] name = "craft-ssip" version = "0.1.0" @@ -3765,6 +4019,21 @@ dependencies = [ "weezl 0.2.1", ] +[[package]] +name = "craft-suite-account" +version = "0.1.0" +dependencies = [ + "dirs", + "keyring", + "keyring-core", + "log", + "serde", + "serde_json", + "sha2 0.10.9", + "tempfile", + "zeroize", +] + [[package]] name = "craft-svg" version = "0.1.0" @@ -3773,11 +4042,14 @@ dependencies = [ "craft-xml", "data-url", "flate2", + "gif", + "image-webp", "kurbo", "quick-xml 0.41.0", "resvg 0.48.1", "roxmltree 0.21.2", "thiserror 2.0.21", + "toml", "usvg 0.48.1", "vectorcraft-geom", "vectorcraft-pathops", @@ -3807,6 +4079,7 @@ dependencies = [ name = "craft-tar" version = "0.1.0" dependencies = [ + "craft-testkit", "serde", ] @@ -3881,6 +4154,16 @@ dependencies = [ "smallvec", ] +[[package]] +name = "craft-theme-editor" +version = "0.1.0" +dependencies = [ + "craft-behavior", + "craft-theme", + "craft-ui", + "egui", +] + [[package]] name = "craft-theme-store" version = "0.1.0" @@ -3932,11 +4215,19 @@ dependencies = [ "web-time", ] +[[package]] +name = "craft-tracked" +version = "0.1.0" +dependencies = [ + "craft-ui-macros", +] + [[package]] name = "craft-ui" version = "0.1.0" dependencies = [ "craft-behavior", + "craft-cloud-ui", "craft-i18n", "craft-ui", "craft-ui-canvas", @@ -3997,6 +4288,7 @@ dependencies = [ "craft-settings", "craft-svg", "craft-theme", + "craft-tracked", "craft-ui-contract", "craft-ui-macros", "craft-ui-test-kit", @@ -4013,6 +4305,8 @@ dependencies = [ "log", "proc-macro2", "serde", + "serde_json", + "siphasher", "skrifa 0.44.0", "smallvec", "syn 2.0.119", @@ -4042,6 +4336,7 @@ dependencies = [ "craft-table", "craft-text", "craft-theme", + "craft-theme-editor", "craft-theme-store", "craft-timeline", "craft-ui", @@ -4235,6 +4530,17 @@ dependencies = [ "thiserror 2.0.21", ] +[[package]] +name = "craft-wasm" +version = "0.1.0" +dependencies = [ + "craft-testkit", + "serde", + "thiserror 2.0.21", + "wasmparser 0.261.0", + "wasmprinter", +] + [[package]] name = "craft-web-api" version = "0.1.0" @@ -4323,6 +4629,21 @@ dependencies = [ "thiserror 2.0.21", ] +[[package]] +name = "craft-xfa" +version = "0.1.0" +dependencies = [ + "craft-xml", +] + +[[package]] +name = "craft-xfdf" +version = "0.1.0" +dependencies = [ + "craft-xml", + "thiserror 2.0.21", +] + [[package]] name = "craft-xfl" version = "0.1.0" @@ -5092,7 +5413,7 @@ dependencies = [ [[package]] name = "ecolor" version = "0.37.0" -source = "git+https://github.com/storytold/egui.git?rev=e9711ca9b69772f875ae0d1cef1977ff8c16234d#e9711ca9b69772f875ae0d1cef1977ff8c16234d" +source = "git+https://github.com/storytold/egui.git?rev=7e1c30d142bc7879d043e74b5ceb3ecfe7f51329#7e1c30d142bc7879d043e74b5ceb3ecfe7f51329" dependencies = [ "bytemuck", "emath", @@ -5148,7 +5469,7 @@ dependencies = [ [[package]] name = "eframe" version = "0.37.0" -source = "git+https://github.com/storytold/egui.git?rev=e9711ca9b69772f875ae0d1cef1977ff8c16234d#e9711ca9b69772f875ae0d1cef1977ff8c16234d" +source = "git+https://github.com/storytold/egui.git?rev=7e1c30d142bc7879d043e74b5ceb3ecfe7f51329#7e1c30d142bc7879d043e74b5ceb3ecfe7f51329" dependencies = [ "ahash", "bytemuck", @@ -5183,7 +5504,7 @@ dependencies = [ [[package]] name = "egui" version = "0.37.0" -source = "git+https://github.com/storytold/egui.git?rev=e9711ca9b69772f875ae0d1cef1977ff8c16234d#e9711ca9b69772f875ae0d1cef1977ff8c16234d" +source = "git+https://github.com/storytold/egui.git?rev=7e1c30d142bc7879d043e74b5ceb3ecfe7f51329#7e1c30d142bc7879d043e74b5ceb3ecfe7f51329" dependencies = [ "accesskit", "ahash", @@ -5202,7 +5523,7 @@ dependencies = [ [[package]] name = "egui-wgpu" version = "0.37.0" -source = "git+https://github.com/storytold/egui.git?rev=e9711ca9b69772f875ae0d1cef1977ff8c16234d#e9711ca9b69772f875ae0d1cef1977ff8c16234d" +source = "git+https://github.com/storytold/egui.git?rev=7e1c30d142bc7879d043e74b5ceb3ecfe7f51329#7e1c30d142bc7879d043e74b5ceb3ecfe7f51329" dependencies = [ "ahash", "bytemuck", @@ -5221,7 +5542,7 @@ dependencies = [ [[package]] name = "egui-winit" version = "0.37.0" -source = "git+https://github.com/storytold/egui.git?rev=e9711ca9b69772f875ae0d1cef1977ff8c16234d#e9711ca9b69772f875ae0d1cef1977ff8c16234d" +source = "git+https://github.com/storytold/egui.git?rev=7e1c30d142bc7879d043e74b5ceb3ecfe7f51329#7e1c30d142bc7879d043e74b5ceb3ecfe7f51329" dependencies = [ "block2 0.6.2", "bytemuck", @@ -5241,7 +5562,7 @@ dependencies = [ [[package]] name = "egui_glow" version = "0.37.0" -source = "git+https://github.com/storytold/egui.git?rev=e9711ca9b69772f875ae0d1cef1977ff8c16234d#e9711ca9b69772f875ae0d1cef1977ff8c16234d" +source = "git+https://github.com/storytold/egui.git?rev=7e1c30d142bc7879d043e74b5ceb3ecfe7f51329#7e1c30d142bc7879d043e74b5ceb3ecfe7f51329" dependencies = [ "bytemuck", "egui", @@ -5254,7 +5575,7 @@ dependencies = [ [[package]] name = "egui_kittest" version = "0.37.0" -source = "git+https://github.com/storytold/egui.git?rev=e9711ca9b69772f875ae0d1cef1977ff8c16234d#e9711ca9b69772f875ae0d1cef1977ff8c16234d" +source = "git+https://github.com/storytold/egui.git?rev=7e1c30d142bc7879d043e74b5ceb3ecfe7f51329#7e1c30d142bc7879d043e74b5ceb3ecfe7f51329" dependencies = [ "eframe", "egui", @@ -5287,7 +5608,7 @@ dependencies = [ "ff 0.13.1", "generic-array", "group 0.13.0", - "hkdf", + "hkdf 0.12.4", "pem-rfc7468 0.7.0", "pkcs8 0.10.2", "rand_core 0.6.4", @@ -5331,7 +5652,7 @@ dependencies = [ [[package]] name = "emath" version = "0.37.0" -source = "git+https://github.com/storytold/egui.git?rev=e9711ca9b69772f875ae0d1cef1977ff8c16234d#e9711ca9b69772f875ae0d1cef1977ff8c16234d" +source = "git+https://github.com/storytold/egui.git?rev=7e1c30d142bc7879d043e74b5ceb3ecfe7f51329#7e1c30d142bc7879d043e74b5ceb3ecfe7f51329" dependencies = [ "bytemuck", ] @@ -5404,7 +5725,7 @@ dependencies = [ [[package]] name = "epaint" version = "0.37.0" -source = "git+https://github.com/storytold/egui.git?rev=e9711ca9b69772f875ae0d1cef1977ff8c16234d#e9711ca9b69772f875ae0d1cef1977ff8c16234d" +source = "git+https://github.com/storytold/egui.git?rev=7e1c30d142bc7879d043e74b5ceb3ecfe7f51329#7e1c30d142bc7879d043e74b5ceb3ecfe7f51329" dependencies = [ "ahash", "bytemuck", @@ -5430,7 +5751,7 @@ dependencies = [ [[package]] name = "epaint_default_fonts" version = "0.37.0" -source = "git+https://github.com/storytold/egui.git?rev=e9711ca9b69772f875ae0d1cef1977ff8c16234d#e9711ca9b69772f875ae0d1cef1977ff8c16234d" +source = "git+https://github.com/storytold/egui.git?rev=7e1c30d142bc7879d043e74b5ceb3ecfe7f51329#7e1c30d142bc7879d043e74b5ceb3ecfe7f51329" [[package]] name = "equator" @@ -5955,6 +6276,17 @@ dependencies = [ "pin-project-lite", ] +[[package]] +name = "futures-macro" +version = "0.3.34" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9fb9654ba8355388abeb8dcb4fc62f511300867002afc858860463bdd9fe0c44" +dependencies = [ + "proc-macro2", + "quote", + "syn 3.0.6", +] + [[package]] name = "futures-sink" version = "0.3.34" @@ -5975,6 +6307,7 @@ checksum = "0d50a92467f8ba5dd6e3ee5d4bd04d73ab2e4e1c44474a0674821dfce14b79bc" dependencies = [ "futures-core", "futures-io", + "futures-macro", "futures-sink", "futures-task", "memchr", @@ -6432,7 +6765,7 @@ dependencies = [ [[package]] name = "harfbuzz-subset-sys" version = "0.1.0+harfbuzz-15.0.0" -source = "git+https://github.com/storytold/harfbuzz.git?rev=2659dd807f9a48f75604ee7c76cb709f7b70b950#2659dd807f9a48f75604ee7c76cb709f7b70b950" +source = "git+https://github.com/storytold/harfbuzz.git?rev=f32ed1e548eaa8852bff47e49a90629a013a2faa#f32ed1e548eaa8852bff47e49a90629a013a2faa" dependencies = [ "cc", ] @@ -6622,6 +6955,15 @@ dependencies = [ "hmac 0.12.1", ] +[[package]] +name = "hkdf" +version = "0.13.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4aaa26c720c68b866f2c96ef5c1264b3e6f473fe5d4ce61cd44bbe913e553018" +dependencies = [ + "hmac 0.13.0", +] + [[package]] name = "hmac" version = "0.12.1" @@ -7657,6 +7999,27 @@ dependencies = [ "serde", ] +[[package]] +name = "keyring" +version = "4.2.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2270074a3d26bcac93c1dc5d2845eb4c089e8d761ccf6e0ea266a16004640627" +dependencies = [ + "apple-native-keyring-store", + "keyring-core", + "windows-native-keyring-store", + "zbus-secret-service-keyring-store", +] + +[[package]] +name = "keyring-core" +version = "1.0.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "29fbf4b551298c67925f38cf341a1ada797a75f1837bdf8ae1fc8e2ebc6efb59" +dependencies = [ + "log", +] + [[package]] name = "khronos-egl" version = "6.0.0" @@ -8007,6 +8370,15 @@ dependencies = [ "digest 0.11.3", ] +[[package]] +name = "md4" +version = "0.11.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "bd76fb0fd6b2e4be62a73f8e0858ca97f81babcb1af322dcaca196f735f17f80" +dependencies = [ + "digest 0.11.3", +] + [[package]] name = "memchr" version = "2.8.3" @@ -9360,7 +9732,7 @@ dependencies = [ "generic-array", "getrandom 0.2.17", "hex", - "hkdf", + "hkdf 0.12.4", "idea", "k256", "log", @@ -10946,6 +11318,25 @@ dependencies = [ "zeroize", ] +[[package]] +name = "secret-service" +version = "5.2.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5107b24b91445dd2aa449a258a1807b63240942157292354dc5bfdbeb8bc6db8" +dependencies = [ + "aes 0.9.4", + "cbc", + "futures-util", + "getrandom 0.4.3", + "hkdf 0.13.0", + "hybrid-array", + "num", + "once_cell", + "serde", + "sha2 0.11.1", + "zbus", +] + [[package]] name = "security-framework" version = "3.7.0" @@ -13294,7 +13685,7 @@ dependencies = [ "wasmi_collections", "wasmi_core", "wasmi_ir", - "wasmparser", + "wasmparser 0.228.0", ] [[package]] @@ -13334,6 +13725,28 @@ dependencies = [ "indexmap", ] +[[package]] +name = "wasmparser" +version = "0.261.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4f20f20e44f7e8aeb6744823ea9d869ede51e51be4fdaedede2852282e54d2d8" +dependencies = [ + "bitflags 2.13.2", + "indexmap", + "semver", +] + +[[package]] +name = "wasmprinter" +version = "0.261.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "86a21c9e3325655ba02de3e645bc8357a8b3651a2e3ada25b6dbc37560deb9b7" +dependencies = [ + "anyhow", + "termcolor", + "wasmparser 0.261.0", +] + [[package]] name = "wayland-backend" version = "0.3.17" @@ -13766,6 +14179,19 @@ version = "0.2.1" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5" +[[package]] +name = "windows-native-keyring-store" +version = "1.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "063426e76fdec7438d56bb777f67e318a84a25c707b07e575cb8b78e10c028f8" +dependencies = [ + "byteorder", + "keyring-core", + "regex", + "windows-sys 0.61.2", + "zeroize", +] + [[package]] name = "windows-numerics" version = "0.3.1" @@ -14393,6 +14819,17 @@ dependencies = [ "zvariant", ] +[[package]] +name = "zbus-secret-service-keyring-store" +version = "1.0.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "74801d001b9e7729adb4f1825b67b398185fed424749aa3d8bacf70417137d9a" +dependencies = [ + "keyring-core", + "secret-service", + "zbus", +] + [[package]] name = "zbus_macros" version = "5.19.0" @@ -14643,19 +15080,19 @@ dependencies = [ [[patch.unused]] name = "egui_demo_lib" version = "0.37.0" -source = "git+https://github.com/storytold/egui.git?rev=e9711ca9b69772f875ae0d1cef1977ff8c16234d#e9711ca9b69772f875ae0d1cef1977ff8c16234d" +source = "git+https://github.com/storytold/egui.git?rev=7e1c30d142bc7879d043e74b5ceb3ecfe7f51329#7e1c30d142bc7879d043e74b5ceb3ecfe7f51329" [[patch.unused]] name = "egui_extras" version = "0.37.0" -source = "git+https://github.com/storytold/egui.git?rev=e9711ca9b69772f875ae0d1cef1977ff8c16234d#e9711ca9b69772f875ae0d1cef1977ff8c16234d" +source = "git+https://github.com/storytold/egui.git?rev=7e1c30d142bc7879d043e74b5ceb3ecfe7f51329#7e1c30d142bc7879d043e74b5ceb3ecfe7f51329" [[patch.unused]] name = "egui_inspection" version = "0.37.0" -source = "git+https://github.com/storytold/egui.git?rev=e9711ca9b69772f875ae0d1cef1977ff8c16234d#e9711ca9b69772f875ae0d1cef1977ff8c16234d" +source = "git+https://github.com/storytold/egui.git?rev=7e1c30d142bc7879d043e74b5ceb3ecfe7f51329#7e1c30d142bc7879d043e74b5ceb3ecfe7f51329" [[patch.unused]] name = "egui_system_font_provider" version = "0.37.0" -source = "git+https://github.com/storytold/egui.git?rev=e9711ca9b69772f875ae0d1cef1977ff8c16234d#e9711ca9b69772f875ae0d1cef1977ff8c16234d" +source = "git+https://github.com/storytold/egui.git?rev=7e1c30d142bc7879d043e74b5ceb3ecfe7f51329#7e1c30d142bc7879d043e74b5ceb3ecfe7f51329" diff --git a/Cargo.toml b/Cargo.toml index 5a038bd41..19f616061 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -11,6 +11,14 @@ rust-version = "1.95" repository = "https://github.com/storytold/craft-libs" [workspace.dependencies] +craft-xfa = { path = "crates/xfa" } +craft-evm = { path = "crates/evm" } +craft-java-class = { path = "crates/java-class" } +craft-sourcemap = { path = "crates/sourcemap" } +craft-pcap = { path = "crates/pcap" } +craft-har = { path = "crates/har" } +craft-xfdf = { path = "crates/xfdf" } +craft-jsonc = { path = "crates/jsonc" } craft-palette = { path = "crates/palette" } craft-score = { path = "crates/score" } craft-shx = { path = "crates/shx" } @@ -25,6 +33,7 @@ acadrust = "=0.6.6" log = "0.4" # internal: add each crate here as `craft- = { path = "crates/" }` craft-plist = { path = "crates/plist" } +craft-wasm = { path = "crates/wasm" } craft-platform = { path = "crates/platform" } craft-aep = { path = "crates/aep" } craft-affinity = { path = "crates/affinity" } @@ -53,13 +62,20 @@ craft-gridcraft-format = { path = "crates/gridcraft-format" } craft-aaf = { path = "crates/aaf" } craft-behavior = { path = "crates/behavior" } craft-atomic = { path = "crates/atomic" } +# The ArtCraft Launcher's app list for AI agents (storytold/craft-ai-integrations, crates/app/ai-agents). +craft-ai-agents = { git = "https://github.com/storytold/craft-ai-integrations", rev = "d94a3593adcff504eaaad9e5aee4c84fd2f07a72" } +craft-dex = { path = "crates/dex" } craft-xtask = { path = "crates/xtask" } craft-captions = { path = "crates/captions" } craft-cfb = { path = "crates/cfb" } craft-codepage = { path = "crates/codepage" } craft-cms = { path = "crates/cms" } +craft-cloud = { path = "crates/cloud" } +craft-cloud-local = { path = "crates/cloud-local" } +craft-cloud-ui = { path = "crates/cloud-ui" } craft-color = { path = "crates/color" } craft-color-ui = { path = "crates/color-ui" } +craft-color-transform = { path = "crates/color-transform" } craft-frame = { path = "crates/frame" } craft-crs = { path = "crates/crs" } craft-crw = { path = "crates/crw" } @@ -86,8 +102,6 @@ vectorcraft-doc = { git = "https://github.com/storytold/vectorcraft.git", rev = vectorcraft-eps = { git = "https://github.com/storytold/vectorcraft.git", rev = "6b3a6b8788ebcb420d69449199cbdf323888d27e" } vectorcraft-geom = { git = "https://github.com/storytold/vectorcraft.git", rev = "6b3a6b8788ebcb420d69449199cbdf323888d27e" } vectorcraft-pathops = { git = "https://github.com/storytold/vectorcraft.git", rev = "6b3a6b8788ebcb420d69449199cbdf323888d27e" } -# The ArtCraft Launcher's list of apps AI agents may use, shared with the launcher and the MCP gateway. -craft-ai-agents = { git = "https://github.com/storytold/craft-ai-integrations", rev = "35e0352666a117407d62230a6c6c2366f3e21a3b" } craft-doc = { path = "crates/doc" } craft-docpath = { path = "crates/docpath" } craft-dpx = { path = "crates/dpx" } @@ -95,6 +109,7 @@ craft-draw = { path = "crates/draw" } craft-dwg = { path = "crates/dwg" } craft-fcproj-format = { path = "crates/fcproj-format" } craft-ecproj-format = { path = "crates/ecproj-format" } +craft-esign = { path = "crates/esign" } craft-figma-rest = { path = "crates/figma-rest" } craft-exr = { path = "crates/exr" } craft-flags = { path = "crates/flags" } @@ -108,13 +123,18 @@ craft-gif = { path = "crates/gif" } craft-hdr = { path = "crates/hdr" } craft-mesh = { path = "crates/mesh" } craft-html = { path = "crates/html" } +craft-ipp = { path = "crates/ipp" } craft-heif = { path = "crates/heif" } craft-fig = { path = "crates/fig" } craft-fonts-build = { path = "crates/fonts-build" } craft-font-subset = { path = "crates/font-subset" } # The HarfBuzz subsetter from storytold's HarfBuzz fork (branch rust-subset-15.0.0: HarfBuzz 15.0.0 plus rust/harfbuzz-subset-sys). -harfbuzz-subset-sys = { git = "https://github.com/storytold/harfbuzz.git", rev = "2659dd807f9a48f75604ee7c76cb709f7b70b950" } +harfbuzz-subset-sys = { git = "https://github.com/storytold/harfbuzz.git", rev = "f32ed1e548eaa8852bff47e49a90629a013a2faa" } craft-host = { path = "crates/host" } +craft-gpu = { path = "crates/gpu" } +craft-gpu-null = { path = "crates/gpu-null" } +craft-gpu-providers = { path = "crates/gpu-providers" } +craft-gpu-wgpu = { path = "crates/gpu-wgpu" } craft-i18n = { path = "crates/i18n" } craft-ipc = { path = "crates/ipc" } craft-idml = { path = "crates/idml" } @@ -127,7 +147,7 @@ craft-control = { path = "crates/control" } craft-control-protocol = { path = "crates/control-protocol" } craft-jsonrpc = { path = "crates/jsonrpc" } craft-mcp = { path = "crates/mcp" } -craft-jxl = { path = "crates/jxl" } +craft-jxl = { path = "crates/jxl", default-features = false } craft-kiwi = { path = "crates/kiwi" } craft-keymap = { path = "crates/keymap" } craft-assuan = { path = "crates/assuan" } @@ -157,6 +177,7 @@ craft-opc = { path = "crates/opc" } craft-openpgp = { path = "crates/openpgp" } craft-ora = { path = "crates/ora" } craft-pptx = { path = "crates/pptx" } +craft-ppt-binary = { path = "crates/ppt-binary" } craft-penpot = { path = "crates/penpot" } craft-pcraft-format = { path = "crates/pcraft-format" } craft-pcraft-bundle = { path = "crates/pcraft-bundle" } @@ -176,6 +197,9 @@ craft-quit = { path = "crates/quit" } craft-gpu = { path = "crates/gpu" } craft-rtf = { path = "crates/rtf" } craft-raw = { path = "crates/raw" } +craft-geom = { path = "crates/geom" } +craft-develop = { path = "crates/develop" } +craft-develop-model = { path = "crates/develop-model" } craft-sheet = { path = "crates/sheet" } craft-sketch = { path = "crates/sketch" } craft-review = { path = "crates/review" } @@ -184,6 +208,7 @@ craft-figcraft-format = { path = "crates/figcraft-format" } craft-scraft-format = { path = "crates/scraft-format" } craft-time = { path = "crates/time" } craft-silhouette-studio = { path = "crates/silhouette-studio" } +craft-suite-account = { path = "crates/suite-account" } craft-svg = { path = "crates/svg" } craft-stencilcraft-format = { path = "crates/stencilcraft-format" } craft-stencilcraft-document = { path = "crates/stencilcraft-document" } @@ -199,7 +224,9 @@ craft-tiff = { path = "crates/tiff" } craft-metadata = { path = "crates/metadata" } craft-table = { path = "crates/table" } craft-theme = { path = "crates/theme" } +craft-theme-editor = { path = "crates/theme-editor" } craft-theme-store = { path = "crates/theme-store" } +craft-tracked = { path = "crates/tracked" } craft-ui = { path = "crates/ui" } craft-ui-canvas = { path = "crates/ui-canvas" } craft-ui-contract = { path = "crates/ui-contract" } @@ -249,6 +276,9 @@ proptest = "1" encoding_rs = "0.8" # All date/time conversion goes through chrono (no hand-rolled calendar code beyond the 400-year range extension; AGENTS.md). chrono = { version = "0.4.45", default-features = false, features = ["std"] } +# Foundation crates for craft-gpu-wgpu. The versions match the ones the app repos already pin. +pollster = "0.4" +wgpu = { version = "30", default-features = false, features = ["std", "wgsl"] } [workspace.lints.rust] unsafe_code = "forbid" @@ -274,20 +304,20 @@ hayro-jbig2 = { path = "vendor/hayro-jbig2" } hayro-cmap = { path = "vendor/hayro-cmap" } hayro-postscript = { path = "vendor/hayro-postscript" } linesweeper = { path = "vendor/linesweeper" } -ecolor = { git = "https://github.com/storytold/egui.git", rev = "e9711ca9b69772f875ae0d1cef1977ff8c16234d" } -emath = { git = "https://github.com/storytold/egui.git", rev = "e9711ca9b69772f875ae0d1cef1977ff8c16234d" } -epaint = { git = "https://github.com/storytold/egui.git", rev = "e9711ca9b69772f875ae0d1cef1977ff8c16234d" } -epaint_default_fonts = { git = "https://github.com/storytold/egui.git", rev = "e9711ca9b69772f875ae0d1cef1977ff8c16234d" } -egui = { git = "https://github.com/storytold/egui.git", rev = "e9711ca9b69772f875ae0d1cef1977ff8c16234d" } -egui-winit = { git = "https://github.com/storytold/egui.git", rev = "e9711ca9b69772f875ae0d1cef1977ff8c16234d" } -egui-wgpu = { git = "https://github.com/storytold/egui.git", rev = "e9711ca9b69772f875ae0d1cef1977ff8c16234d" } -egui_glow = { git = "https://github.com/storytold/egui.git", rev = "e9711ca9b69772f875ae0d1cef1977ff8c16234d" } -egui_extras = { git = "https://github.com/storytold/egui.git", rev = "e9711ca9b69772f875ae0d1cef1977ff8c16234d" } -egui_kittest = { git = "https://github.com/storytold/egui.git", rev = "e9711ca9b69772f875ae0d1cef1977ff8c16234d" } -egui_system_font_provider = { git = "https://github.com/storytold/egui.git", rev = "e9711ca9b69772f875ae0d1cef1977ff8c16234d" } -eframe = { git = "https://github.com/storytold/egui.git", rev = "e9711ca9b69772f875ae0d1cef1977ff8c16234d" } -egui_demo_lib = { git = "https://github.com/storytold/egui.git", rev = "e9711ca9b69772f875ae0d1cef1977ff8c16234d" } -egui_inspection = { git = "https://github.com/storytold/egui.git", rev = "e9711ca9b69772f875ae0d1cef1977ff8c16234d" } +ecolor = { git = "https://github.com/storytold/egui.git", rev = "7e1c30d142bc7879d043e74b5ceb3ecfe7f51329" } +emath = { git = "https://github.com/storytold/egui.git", rev = "7e1c30d142bc7879d043e74b5ceb3ecfe7f51329" } +epaint = { git = "https://github.com/storytold/egui.git", rev = "7e1c30d142bc7879d043e74b5ceb3ecfe7f51329" } +epaint_default_fonts = { git = "https://github.com/storytold/egui.git", rev = "7e1c30d142bc7879d043e74b5ceb3ecfe7f51329" } +egui = { git = "https://github.com/storytold/egui.git", rev = "7e1c30d142bc7879d043e74b5ceb3ecfe7f51329" } +egui-winit = { git = "https://github.com/storytold/egui.git", rev = "7e1c30d142bc7879d043e74b5ceb3ecfe7f51329" } +egui-wgpu = { git = "https://github.com/storytold/egui.git", rev = "7e1c30d142bc7879d043e74b5ceb3ecfe7f51329" } +egui_glow = { git = "https://github.com/storytold/egui.git", rev = "7e1c30d142bc7879d043e74b5ceb3ecfe7f51329" } +egui_extras = { git = "https://github.com/storytold/egui.git", rev = "7e1c30d142bc7879d043e74b5ceb3ecfe7f51329" } +egui_kittest = { git = "https://github.com/storytold/egui.git", rev = "7e1c30d142bc7879d043e74b5ceb3ecfe7f51329" } +egui_system_font_provider = { git = "https://github.com/storytold/egui.git", rev = "7e1c30d142bc7879d043e74b5ceb3ecfe7f51329" } +eframe = { git = "https://github.com/storytold/egui.git", rev = "7e1c30d142bc7879d043e74b5ceb3ecfe7f51329" } +egui_demo_lib = { git = "https://github.com/storytold/egui.git", rev = "7e1c30d142bc7879d043e74b5ceb3ecfe7f51329" } +egui_inspection = { git = "https://github.com/storytold/egui.git", rev = "7e1c30d142bc7879d043e74b5ceb3ecfe7f51329" } winit = { git = "https://github.com/storytold/winit.git", rev = "a517b3846ee8457d84ee4975110bfda6797c44dc" } # symphonia's FLAC decoder restores LPC samples as `residual + (prediction as i32)`. In a valid @@ -305,44 +335,3 @@ opt-level = 3 # 2 MiB stack of a test thread. The apps this reader came from build their crates at this level. [profile.dev.package.craft-affinity] opt-level = 1 -# Dev and test builds never run LTO: with `lto = false` (cargo's default) rustc runs thin-local LTO across every -# optimised crate's 256 codegen units on each rebuild, which multiplied the incremental rebuild of the framework -# crates. Off, a one-line edit re-optimises only the changed units. -[profile.dev] -lto = "off" - -# Dependencies (egui, rendering, text shaping, syn) run optimised in dev and test builds, so -# screen tests, design-lint and the debug gallery run at a usable speed. They build once per -# target dir; the workspace's own crates stay unoptimised and incremental. -[profile.dev.package."*"] -opt-level = 2 - -# craft-theme's colour maths and the behaviour cores, which run in every screen-test frame, and craft-proof, whose -# tests parse and check whole dictionaries, build at opt-level 1: unoptimised, they made the test binaries several -# times slower, and they are rarely edited. Every other workspace crate, the framework runtime included, stays at -# opt-level 0: an edit to craft-ui-contract (65k lines) rebuilt for 35-90 s at opt-level 1 and rebuilds in seconds at 0, -# and the runtime's hot pipeline is generic, so it compiles in the dependants at their opt-level anyway. -[profile.dev.package.craft-theme] -opt-level = 1 -[profile.dev.package.craft-behavior] -opt-level = 1 -[profile.dev.package.craft-proof] -opt-level = 1 - -# The gallery on the Mac: optimised like release, but the workspace's crates build in many small -# units, incrementally, so a change to craft-ui rebuilds in minutes. Dependencies keep release -# settings and build once in target/gallery. `cargo run --profile gallery -p craft-ui-gallery`. -[profile.gallery] -inherits = "release" -incremental = true -codegen-units = 256 -opt-level = 1 - -# The workspace's own crates build at opt-level 1 in the gallery profile: rustc shares generic instantiations across -# crates at opt-level 0, 1, s and z only, so at 1 a change in a framework crate no longer makes every dependant -# re-generate its own copies of that crate's generics and inlined functions (a one-line edit rebuilt the gallery in -# 25 s at opt-level 1 and 69–84 s at 3). `package."*"` matches the dependencies only: they keep release optimisation, -# so this changes nothing in their settings. -[profile.gallery.package."*"] -codegen-units = 16 -opt-level = 3 diff --git a/NOTICE b/NOTICE index ac101996d..8ca284e8d 100644 --- a/NOTICE +++ b/NOTICE @@ -114,6 +114,14 @@ Copyright (c) 2026 ArtCraft Team and the PhotoCraft contributors. The format imp clean-room work based on their public specifications; dependency licences and X.Org's `rgb.txt` attribution are listed in ATTRIBUTION.md. +crates/develop (craft-develop) is moved from LightCraft, module by module: +- src/inpaint.rs and src/inpaint/ from crates/inpaint (lightcraft-inpaint), with its tests, revision a75497d6. + https://github.com/storytold/lightcraft + Copyright (c) 2026 ArtCraft Team and the LightCraft contributors. + That crate ports the inpainting (PatchMatch completion) and Poisson membrane fill code of PhotoCraft + (https://github.com/storytold/photocraft, crates/algo/src/inpaint.rs and poisson.rs), Copyright the PhotoCraft + contributors, MIT OR Apache-2.0; the port was modified by the LightCraft contributors (2026). + crates/raw (craft-raw) is moved from LightCraft, with behaviour ported from two other readers: - LightCraft, crates/raw (src/lib.rs, dng.rs, dngwrite.rs, tiffraw.rs, unpack.rs, ljpeg.rs, jxl.rs, opcodes.rs, profile.rs, gaintable.rs, semantic.rs, preview.rs, vendor/crw.rs, vendor/hasselblad.rs, diff --git a/README.md b/README.md index d42d43b07..f1ded80ca 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,7 @@ Craft App Libraries =================== Scanned by SonarCloud +Reviewed by CodeRabbit This repo contains libraries used by the various Craft Apps. It's a Rust monorepo workspace, and the libraries can be included by any Craft Apps that need them. @@ -288,7 +289,7 @@ See the [release notes](CHANGELOG.md) for included functionality and known limit - [`craft-math`](crates/math/README.md): equations as one tree (the Office Math object model) with its syntaxes, read and written: OMML, presentation MathML, LaTeX math and the UnicodeMath linear format. - [`craft-media`](crates/media/README.md): bit-level I/O (`bitstream`), clean-room MP4/MOV (`isobmff`), Matroska/WebM (`matroska`) and MXF (`mxf`) demuxers and muxers, Ogg (`ogg`), AVI (`avi`) and - MPEG-TS/PS (`mpegts`) demuxers, from FilmCraft, and an ISO BMFF box reader. Containers only; codecs are in `craft-audio`, and + MPEG-TS/PS (`mpegts`) demuxers, from FilmCraft, a Sierra VMD (`vmd`) demuxer, and an ISO BMFF box reader. Containers only; codecs are in `craft-audio`, and video codecs will go in a separate crate. - [`craft-lottie`](crates/lottie/README.md): Lottie (Bodymovin) JSON: the document model of lottie-spec 1.0 (animation, assets, layers by type, shape items, masks, effects, text, markers) @@ -341,6 +342,8 @@ See the [release notes](CHANGELOG.md) for included functionality and known limit - [`craft-plotter`](crates/plotter/README.md): cutter and pen-plotter command languages: HP-GL, DMPL and GP-GL (plain and the Silhouette dialect, three generations, registration marks) from a job in millimetres, plus the Silhouette device queries and reply parsers. No I/O. +- [`craft-ppt-binary`](crates/ppt-binary/README.md): the PowerPoint 97-2003 binary format (`.ppt`, `.pot`, `.pps`; + [MS-PPT], [MS-ODRAW]) read into `craft-pptx`, on `craft-cfb`. Import only. DeckCraft's reader. - [`craft-pptx`](crates/pptx/README.md): PresentationML, the model of a `.pptx` presentation: masters, layouts, slides, shapes, placeholders and their inheritance, transitions and animations, comments, sections, media and kept parts. From DeckCraft. DrawingML comes from `craft-drawingml`. diff --git a/crates/atomic/tests/permissions.rs b/crates/atomic/tests/permissions.rs index bd8e63a5b..95702cfe7 100644 --- a/crates/atomic/tests/permissions.rs +++ b/crates/atomic/tests/permissions.rs @@ -6,11 +6,16 @@ use craft_atomic::{NewFilePermissions, WriteOptions, atomic_write, write_new}; use std::fs::{self, File, Permissions}; use std::io::{self, Write}; use std::os::unix::fs::PermissionsExt; -use std::path::{Path, PathBuf}; +use std::path::Path; +#[cfg(target_os = "linux")] +use std::path::PathBuf; use std::process::Command; +#[cfg(target_os = "linux")] use std::sync::atomic::{AtomicU64, Ordering}; +#[cfg(target_os = "linux")] struct TempDir(PathBuf); +#[cfg(target_os = "linux")] impl TempDir { fn new() -> io::Result { static N: AtomicU64 = AtomicU64::new(0); @@ -19,6 +24,7 @@ impl TempDir { Ok(Self(path)) } } +#[cfg(target_os = "linux")] impl Drop for TempDir { fn drop(&mut self) { let _ = fs::remove_dir_all(&self.0); @@ -29,6 +35,7 @@ fn mode(path: &Path) -> io::Result { Ok(fs::metadata(path)?.permissions().mode() & 0o777) } +#[cfg(target_os = "linux")] /// Set umask only in a separate shell process; changing it in a parallel test process races. fn child(dir: &Path, mask: &str, expected: &str, check_acl: bool) -> io::Result<()> { let output = Command::new("sh") diff --git a/crates/audio/Cargo.toml b/crates/audio/Cargo.toml index 734cb7f45..7981f3a01 100644 --- a/crates/audio/Cargo.toml +++ b/crates/audio/Cargo.toml @@ -37,15 +37,23 @@ flac-encode = ["craft-media/bitstream"] # The pure-Rust Vorbis encoder (`vorbis::encoder`) and Ogg Vorbis files through `encode` and # `encode_ogg_vorbis`. vorbis-encode = ["craft-media/ogg"] +# The pure-Rust Vorbis decoder (`vorbis::decoder`), packets and whole Ogg Vorbis files. +vorbis-decode = ["craft-media/ogg"] # Codec modules on their own, for packet-level use. aac-decode = ["craft-media/bitstream"] # The AAC encoder (`aac::Encoder`), and AAC in M4A through `encode` and `FileEncoder`. aac-encode = ["craft-media/bitstream", "craft-media/isobmff"] opus-decode = [] +# ADPCM (`adpcm`): IMA WAV, Microsoft, Yamaha and Flash (SWF) decoders and encoders. +adpcm = ["craft-media/bitstream"] # QOA (Quite OK Audio) files: decoder and encoder in the `qoa` module, each on its own. qoa = ["qoa-decode", "qoa-encode"] qoa-decode = [] qoa-encode = [] +# ITU-T G.722 wideband sub-band ADPCM speech codec (64 kbit/s). +g722 = [] +# ITU-T G.726 ADPCM speech codec (16/24/32/40 kbit/s). +g726 = [] opus-encode = [] # GSM 06.10 full-rate speech: decoder and encoder in the `gsm` module, each on its own. gsm = ["gsm-decode", "gsm-encode"] @@ -63,8 +71,16 @@ ac3-encode = ["craft-media/bitstream"] eac3-encode = ["craft-media/bitstream"] # MPEG-1/2 Layer III (MP3) encoder (`mp3`). mp3-encode = ["craft-media/bitstream"] +# Direct Stream Digital (DSD) files: DSF and DSDIFF decoders and DSD-to-PCM decimation. +dsd = [] + +# MPEG-1/2 Layer II (MP2) encoder (`mpa::encoder`). It shares the polyphase analysis filter of the +# MP3 encoder and the tables of the MP1/MP2 decoder. +mpa-encode = ["mpa-decode", "mp3-encode"] # Bluetooth Low Complexity Subband Coding (SBC) audio codec (`sbc`). sbc = [] +# Sierra VMD sound decoder (`vmd::Decoder`): 8-bit PCM and 16-bit DPCM. +vmd-decode = [] # Multi-resolution waveform overviews (`peaks`). peaks = [] # Encode AAC channels in parallel (with `aac-encode`). @@ -84,6 +100,8 @@ symphonia = { version = "0.6.1", optional = true, default-features = false, feat [dev-dependencies] craft-media-testkit = { workspace = true } +# The VMD demuxer, for the VMD sound decoder's tests. +craft-media = { workspace = true, features = ["vmd"] } proptest = { workspace = true } serde_json = { workspace = true } diff --git a/crates/audio/README.md b/crates/audio/README.md index 10080ebbe..bd80b5406 100644 --- a/crates/audio/README.md +++ b/crates/audio/README.md @@ -39,12 +39,16 @@ No default features. The shared types (`AudioBuffer`, `AudioInfo`, `ChannelLayou | `alac-encode` | `alac::Encoder`; `encode`, `FileEncoder` for ALAC in M4A | craft-media `isobmff` | | `opus-decode`, `opus-encode` | `opus::Decoder`/`StreamDecoder`, `opus::Encoder` | none | | `vorbis-encode` | `vorbis::encoder::Encoder` (pure Rust); `encode_ogg_vorbis`, `encode_ogg` and `encode` for Ogg Vorbis files (whole buffer; not `FileEncoder`) | craft-media `ogg` | +| `vorbis-decode` | `vorbis::decoder::Decoder` (packets), `vorbis::decoder::decode_ogg` (whole Ogg Vorbis files); native Vorbis I: floors 0 and 1, residues 0 to 2, channel coupling, both block sizes. `decode` still reads Vorbis files through symphonia | craft-media `ogg` | | `ac3-decode` | `ac3::Decoder`, `ac3::ProgrammeDecoder` | craft-media `bitstream` | | `ac3-encode`, `eac3-encode` | `ac3::encoder::Encoder`; `encode`, `FileEncoder` for AC-3 and E-AC-3 streams | craft-media `bitstream` | | `mpa-decode` | `mpa::Decoder` | craft-media `bitstream` | | `mp3-decode` | `mp3::Decoder`, `mp3::InfoTag` | `mpa-decode` | | `mp3-encode` | `mp3::Encoder`; `encode`, `FileEncoder` for MP3 | craft-media `bitstream` | +| `mpa-encode` | `mpa::encoder::Encoder` (Layer II / MP2 frames) | `mpa-decode`, `mp3-encode` | +| `adpcm` | `adpcm::{ima, ms, yamaha, swf}`: decoders and encoders for IMA WAV, Microsoft, Yamaha and Flash ADPCM | craft-media `bitstream` | | `gsm-decode`, `gsm-encode` (`gsm`) | `gsm::Decoder`, `gsm::Encoder`, `gsm::decode`, `gsm::encode`: GSM 06.10 full-rate speech, bit-exact, raw `.gsm` and WAV (GSM 6.10) packings | none | +| `vmd-decode` | `vmd::Decoder`: Sierra VMD sound (8-bit PCM and 16-bit DPCM), frame by frame from `craft_media::vmd` | none | | `peaks` | `peaks::Peaks` | none | | `rayon` | parallel AAC encoding (with `aac-encode`) | `rayon` | | `serde` | `Serialize`/`Deserialize` on the shared types | `serde` | @@ -566,6 +570,7 @@ Each codec module's rustdoc lists the coding tools it implements. | Opus (`opus`) | RFC 6716, 8251, 7845 | decoder: SILK, hybrid, CELT, all frame sizes, PLC and FEC, multistream (`Decoder`) and single stream (`StreamDecoder`), 8–48 kHz output; encoder (`Encoder`): SILK, hybrid, CELT, 48 kHz, 20 ms frames, mono or stereo | all 36 RFC 8251 conformance cases; encoder output through ffmpeg's two Opus decoders | | AC-3/E-AC-3 (`ac3`) | decoder: ATSC A/52:2012; encoder/programme API: ETSI TS 102 366 V1.4.1 | single-syncframe and complete-programme decoding; packet encoding through discrete 7.1 (see below) | decoder comparisons and encoder output through ffmpeg, CRC/channel/timing/bit-budget regressions; synthetic quality limitations below | | MP1/MP2 (`mpa`) | ISO/IEC 11172-3, 13818-3 | Layer I and II, MPEG-1/2/2.5, 8–48 kHz; also the Layer II rate/mode pairs the spec disallows (ffmpeg's default mono 384 kbit/s); no free format | ffmpeg-encoded streams, 73–84 dB SNR | +| MP2 encoder (`mpa::encoder`) | ISO/IEC 11172-3 (§2.4, Annex B and C), 13818-3 | Layer II, constant bit rate, mono or stereo (no joint stereo), 32/44.1/48 kHz at the spec's rate/mode pairs and 16/22.05/24 kHz at 8–160 kbit/s; no CRC | our decoder and ffmpeg decode the frames; SNR of 20–37 dB on tone mixes, and the 481-sample filter delay matches | | MP3 decoder (`mp3`) | ISO/IEC 11172-3, 13818-3 | Layer III, MPEG-1/2/2.5, 8–48 kHz, every bit rate, CBR and VBR; mono, stereo, dual channel, joint stereo (mid/side and intensity); long, short and mixed blocks; bit reservoir; CRC read, not checked; Xing / Info / VBRI and LAME tags; no free format (read through symphonia) | ffmpeg's float decoder: 127–131 dB SNR on LAME streams of every sampling frequency (CBR, VBR, CRC, no reservoir, transients with short blocks) and on this crate's encoder's; intensity stereo and mixed blocks through LAME frames edited to use them (112–131 dB) | | MP3 encoder (`mp3`) | ISO/IEC 11172-3, 13818-3 | Layer III, constant bit rate: 32–320 kbit/s at 32/44.1/48 kHz, 8–160 kbit/s at 16/22.05/24 kHz; mono, stereo, joint stereo (mid/side); bit reservoir; long blocks only; no Xing/Info tag, VBR, CRC or free format | ffmpeg decodes every Huffman code as intended; full encodes at every sampling frequency checked with ffprobe and by SNR of ffmpeg's decode | | ALAC (`alac`) | Apple's reference implementation | decode and encode, 1–8 channels, 16/20/24/32 bits (decode: any depth 1–32), fast mode, magic cookie in MP4/Matroska and CAF form | Apple's reference: same packets from the encoder, same samples from both decoders on 766 configurations; ffmpeg: bit-exact both ways | diff --git a/crates/audio/src/adpcm/ima.rs b/crates/audio/src/adpcm/ima.rs new file mode 100644 index 000000000..dcf6958f7 --- /dev/null +++ b/crates/audio/src/adpcm/ima.rs @@ -0,0 +1,247 @@ +//! IMA ADPCM in WAV blocks (format tag 0x0011). +//! +//! A block is, per channel, a 4-byte header (the first sample as `i16` and the step index as `u8`, +//! then a zero byte), then groups of 4 bytes per channel in channel order, each holding eight +//! 4-bit codes, low nibble first. A block of `block_align` bytes holds +//! `(block_align - 4 * channels) * 2 / channels + 1` samples per channel. A code is a sign bit and +//! three magnitude bits: the decoder adds `step/8` plus `step`, `step/2` and `step/4` for each set +//! magnitude bit from the top, then moves the step index by `[-1, -1, -1, -1, 2, 4, 6, 8]`. + +use super::{Error, Result, clip16, step_at}; + +const INDEX_ADJUST: [i32; 8] = [-1, -1, -1, -1, 2, 4, 6, 8]; + +/// The state of one channel's decoder. +#[derive(Clone, Copy)] +struct State { + predictor: i32, + index: i32, +} + +impl State { + /// The sample after code `nibble`. + fn step(&mut self, nibble: u8) -> i16 { + let step = step_at(self.index); + let mut diff = step >> 3; + if nibble & 1 != 0 { + diff += step >> 2; + } + if nibble & 2 != 0 { + diff += step >> 1; + } + if nibble & 4 != 0 { + diff += step; + } + if nibble & 8 != 0 { + diff = -diff; + } + self.predictor = clip16(self.predictor + diff); + self.index = (self.index + INDEX_ADJUST.get(usize::from(nibble & 7)).copied().unwrap_or(0)).clamp(0, 88); + self.predictor as i16 + } + + /// The code that brings the predictor closest to `sample`, applied to the state. + fn encode(&mut self, sample: i16) -> u8 { + let step = step_at(self.index); + let mut diff = i32::from(sample) - self.predictor; + let mut code = 0u8; + if diff < 0 { + code = 8; + diff = -diff; + } + let mut s = step; + for bit in [4u8, 2, 1] { + if diff >= s { + code |= bit; + diff -= s; + } + s >>= 1; + } + self.step(code); + code + } +} + +/// Samples per channel in a block of `block_align` bytes; `None` when the layout is impossible +/// (a block must hold the headers and whole groups of eight samples, and there are 1 to 8 +/// channels). +pub fn samples_per_block(block_align: usize, channels: usize) -> Option { + if !(1..=8).contains(&channels) { + return None; + } + let header = 4 * channels; + let body = block_align.checked_sub(header)?; + if body == 0 || !body.is_multiple_of(4 * channels) { + return None; + } + let per = (body / channels).checked_mul(2)?.checked_add(1)?; + // Callers size interleaved buffers from this value; the full count must fit too. + per.checked_mul(channels)?; + Some(per) +} + +/// Decode one block, appending its samples interleaved by channel to `out`. +pub fn decode_block(block: &[u8], channels: usize, out: &mut Vec) -> Result<()> { + let per = samples_per_block(block.len(), channels).ok_or(Error::Malformed("block size does not fit the channel count"))?; + let mut states = Vec::with_capacity(channels); + for ch in 0..channels { + let h = block.get(4 * ch..4 * ch + 4).ok_or(Error::Malformed("truncated block header"))?; + let index = i32::from(h[2]); + if index > 88 { + return Err(Error::Malformed("step index above 88")); + } + states.push(State { predictor: i32::from(i16::from_le_bytes([h[0], h[1]])), index }); + } + let start = out.len(); + out.resize(start + per * channels, 0); + let samples = out.get_mut(start..).ok_or(Error::Malformed("output"))?; + for (ch, s) in states.iter().enumerate() { + if let Some(o) = samples.get_mut(ch) { + *o = s.predictor as i16; + } + } + let body = block.get(4 * channels..).ok_or(Error::Malformed("truncated block"))?; + for (g, group) in body.chunks_exact(4 * channels).enumerate() { + for (ch, bytes) in group.as_chunks::<4>().0.iter().enumerate() { + let Some(state) = states.get_mut(ch) else { continue }; + for (k, b) in bytes.iter().enumerate() { + for (half, nibble) in [b & 0xF, b >> 4].into_iter().enumerate() { + let t = 1 + g * 8 + k * 2 + half; + if let Some(o) = samples.get_mut(t * channels + ch) { + *o = state.step(nibble); + } + } + } + } + } + Ok(()) +} + +/// Decode a stream of blocks of `block_align` bytes. A final partial block is decoded as far as it +/// holds whole groups. +pub fn decode(data: &[u8], channels: usize, block_align: usize) -> Result> { + samples_per_block(block_align, channels).ok_or(Error::Malformed("block size does not fit the channel count"))?; + let mut out = Vec::new(); + for block in data.chunks(block_align) { + if block.len() == block_align { + decode_block(block, channels, &mut out)?; + } else { + let (header, group) = (4 * channels, 4 * channels); + let whole = block.len().saturating_sub(header) / group * group; + if whole > 0 { + decode_block(block.get(..header + whole).unwrap_or(block), channels, &mut out)?; + } + } + } + Ok(out) +} + +/// The starting step index for a channel whose first samples are `x`: the index whose first +/// codes follow `x` most closely. +fn start_index(first: i16, x: &[i16]) -> i32 { + let mut best = (i64::MAX, 0); + for index in 0..=88 { + let mut st = State { predictor: i32::from(first), index }; + let mut err = 0i64; + for &s in x.iter().take(16) { + let code = st.encode(s); + let _ = code; + err += (i64::from(s) - i64::from(st.predictor)).pow(2); + } + if err < best.0 { + best = (err, index); + } + } + best.1 +} + +/// Encode one block from exactly `samples_per_block * channels` interleaved samples. +pub fn encode_block(samples: &[i16], channels: usize, block_align: usize) -> Result> { + let per = samples_per_block(block_align, channels).ok_or(Error::InvalidInput("block size does not fit the channel count"))?; + if samples.len() != per * channels { + return Err(Error::InvalidInput("a block needs exactly samples_per_block samples per channel")); + } + let mut block = vec![0u8; block_align]; + let mut states = Vec::with_capacity(channels); + for ch in 0..channels { + let col: Vec = samples.iter().skip(ch).step_by(channels).copied().collect(); + let first = col.first().copied().unwrap_or(0); + let st = State { predictor: i32::from(first), index: start_index(first, col.get(1..).unwrap_or(&[])) }; + if let Some(h) = block.get_mut(4 * ch..4 * ch + 4) { + h[..2].copy_from_slice(&first.to_le_bytes()); + h[2] = st.index as u8; + } + states.push(st); + } + let groups = (block_align - 4 * channels) / (4 * channels); + for g in 0..groups { + for ch in 0..channels { + let Some(state) = states.get_mut(ch) else { continue }; + for k in 0..4 { + let mut byte = 0u8; + for half in 0..2 { + let t = 1 + g * 8 + k * 2 + half; + let nibble = state.encode(samples.get(t * channels + ch).copied().unwrap_or(0)); + byte |= nibble << (4 * half); + } + if let Some(b) = block.get_mut(4 * channels + g * 4 * channels + ch * 4 + k) { + *b = byte; + } + } + } + } + Ok(block) +} + +/// Encode interleaved samples as blocks of `block_align` bytes. The last block is padded with +/// copies of the last sample, so a decoder returns up to one block more than was given. +pub fn encode(samples: &[i16], channels: usize, block_align: usize) -> Result> { + let per = samples_per_block(block_align, channels).ok_or(Error::InvalidInput("block size does not fit the channel count"))?; + if !samples.len().is_multiple_of(channels) { + return Err(Error::InvalidInput("the sample count is not a multiple of the channel count")); + } + let mut out = Vec::new(); + for chunk in samples.chunks(per * channels) { + if chunk.len() == per * channels { + out.extend(encode_block(chunk, channels, block_align)?); + } else { + let mut padded = chunk.to_vec(); + let last: Vec = chunk.get(chunk.len().saturating_sub(channels)..).unwrap_or(&[]).to_vec(); + while padded.len() < per * channels { + padded.extend(last.iter().copied().chain(std::iter::repeat(0)).take(channels)); + } + out.extend(encode_block(&padded, channels, block_align)?); + } + } + Ok(out) +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn layout() { + assert_eq!(samples_per_block(256, 1), Some(505)); + assert_eq!(samples_per_block(512, 2), Some(505)); + assert_eq!(samples_per_block(4, 1), None); + assert_eq!(samples_per_block(100, 0), None); + assert_eq!(samples_per_block(258, 2), None); + } + + #[test] + fn unrepresentable_interleaved_layout_is_rejected() { + let align = usize::MAX - 7; + assert_eq!(samples_per_block(align, 2), None); + assert!(encode(&[], 2, align).is_err()); + assert!(encode_block(&[], 2, align).is_err()); + } + + #[test] + fn silence_stays_silent() { + let block = encode_block(&vec![0; 505], 1, 256).unwrap(); + let mut out = Vec::new(); + decode_block(&block, 1, &mut out).unwrap(); + assert!(out.iter().all(|&s| s == 0)); + } +} diff --git a/crates/audio/src/adpcm/mod.rs b/crates/audio/src/adpcm/mod.rs new file mode 100644 index 000000000..da552d3cd --- /dev/null +++ b/crates/audio/src/adpcm/mod.rs @@ -0,0 +1,56 @@ +//! ADPCM: a decoder and an encoder for four families, each on whole blocks or streams of `i16` +//! samples interleaved by channel (feature `adpcm`). +//! +//! - [`ima`]: IMA / DVI ADPCM in WAV blocks (format tag 0x0011): 4 bits per sample, a 4-byte header +//! per channel and groups of eight samples per channel. +//! - [`ms`]: Microsoft ADPCM in WAV blocks (format tag 0x0002): 4 bits per sample, adaptive +//! two-tap prediction with the seven standard coefficient pairs. +//! - [`yamaha`]: Yamaha ADPCM (the YM2608 / AICA family): a raw stream of 4-bit codes. +//! - [`swf`]: the ADPCM of Flash (SWF) audio: 2 to 5 bits per sample, in blocks of 4096 samples. +//! +//! Written from the public descriptions of the algorithms: the IMA Digital Audio Focus and +//! Technical Working Groups' *Recommended Practices for Enhancing Digital Audio Compatibility* +//! (IMA ADPCM), Microsoft's *Multimedia Standards Update* (the WAVE format tags and the block +//! layout of Microsoft ADPCM), the SWF file format specification (the ADPCM section) and the +//! Yamaha ADPCM-B description. ffmpeg is only run as a black-box oracle in the tests. +//! +//! Decoders return errors, never panic, on damaged blocks. Encoders are greedy: they choose each +//! code to bring the decoder's output closest to the sample. + +pub mod ima; +pub mod ms; +pub mod swf; +pub mod yamaha; + +/// What went wrong decoding or encoding ADPCM. +#[non_exhaustive] +#[derive(Debug, thiserror::Error, PartialEq, Eq)] +pub enum Error { + /// The data is damaged, truncated or does not fit the stated block layout. + #[error("malformed ADPCM: {0}")] + Malformed(&'static str), + /// The settings or samples given to an encoder cannot be written. + #[error("ADPCM cannot encode: {0}")] + InvalidInput(&'static str), +} + +/// Result with this module's [`Error`]. +pub type Result = std::result::Result; + +/// IMA ADPCM step sizes (the 89-entry table of the IMA recommended practices). +pub(crate) const STEP_TABLE: [i32; 89] = [ + 7, 8, 9, 10, 11, 12, 13, 14, 16, 17, 19, 21, 23, 25, 28, 31, 34, 37, 41, 45, 50, 55, 60, 66, 73, 80, 88, 97, 107, 118, 130, 143, 157, 173, 190, + 209, 230, 253, 279, 307, 337, 371, 408, 449, 494, 544, 598, 658, 724, 796, 876, 963, 1060, 1166, 1282, 1411, 1552, 1707, 1878, 2066, 2272, 2499, + 2749, 3024, 3327, 3660, 4026, 4428, 4871, 5358, 5894, 6484, 7132, 7845, 8630, 9493, 10442, 11487, 12635, 13899, 15289, 16818, 18500, 20350, + 22385, 24623, 27086, 29794, 32767, +]; + +/// Clamp to the 16-bit sample range. +pub(crate) fn clip16(v: i32) -> i32 { + v.clamp(i32::from(i16::MIN), i32::from(i16::MAX)) +} + +/// The step size at `index` (clamped to the table). +pub(crate) fn step_at(index: i32) -> i32 { + STEP_TABLE.get(index.clamp(0, 88) as usize).copied().unwrap_or(7) +} diff --git a/crates/audio/src/adpcm/ms.rs b/crates/audio/src/adpcm/ms.rs new file mode 100644 index 000000000..057f93549 --- /dev/null +++ b/crates/audio/src/adpcm/ms.rs @@ -0,0 +1,244 @@ +//! Microsoft ADPCM in WAV blocks (format tag 0x0002). +//! +//! A block starts, for all channels in turn, with one predictor index (a byte, 0 to 6), then one +//! initial step (`delta`, `i16`), then each channel's second-last sample (`sample1`, `i16`) and +//! last sample (`sample2`, `i16`) before the block; the block's first two samples per channel are +//! `sample2` then `sample1`. The rest is 4-bit two's-complement codes, the first channel in the +//! high nibble. A block of `block_align` bytes holds `(block_align - 7 * channels) * 2 / channels +//! + 2` samples per channel. Each sample is predicted as `(sample1 * c1 + sample2 * c2) / 256` (rounding toward zero) +//! from the block's coefficient pair, plus `code * delta`; then `delta` becomes +//! `max(16, delta * a / 256)`, where `a` is the table entry for the code (`ADAPT`). + +use super::{Error, Result, clip16}; + +/// The seven coefficient pairs `(c1, c2)` every Microsoft ADPCM stream uses. +pub const COEFFICIENTS: [(i32, i32); 7] = [(256, 0), (512, -256), (0, 0), (192, 64), (240, 0), (460, -208), (392, -232)]; +/// How the step moves with the code's unsigned value (the index is the 4-bit pattern). +/// The largest step. The reference keeps it in 16 bits and no real stream gets near this bound; it +/// keeps every product in range however long a damaged block runs. +const MAX_DELTA: i32 = 1 << 24; +const ADAPT: [i32; 16] = [230, 230, 230, 230, 307, 409, 512, 614, 768, 614, 512, 409, 307, 230, 230, 230]; + +#[derive(Clone, Copy)] +struct State { + c1: i32, + c2: i32, + delta: i32, + s1: i32, + s2: i32, +} + +impl State { + fn step(&mut self, nibble: u8) -> i16 { + let signed = i32::from(nibble) - if nibble & 8 != 0 { 16 } else { 0 }; + let predicted = (self.s1 * self.c1 + self.s2 * self.c2) / 256; + let sample = clip16(predicted + signed * self.delta); + self.s2 = self.s1; + self.s1 = sample; + let adapt = i64::from(ADAPT.get(usize::from(nibble)).copied().unwrap_or(256)); + let new_delta = (adapt * i64::from(self.delta)) >> 8; + self.delta = (new_delta.min(i64::from(MAX_DELTA)) as i32).max(16); + sample as i16 + } + + /// The code that brings the output closest to `sample`, applied to the state. + fn encode(&mut self, sample: i16) -> u8 { + let predicted = (self.s1 * self.c1 + self.s2 * self.c2) / 256; + let err = i32::from(sample) - predicted; + // round to the nearest multiple of delta + let q = if err >= 0 { (err + self.delta / 2) / self.delta } else { -((-err + self.delta / 2) / self.delta) }; + let code = (q.clamp(-8, 7) & 0xF) as u8; + self.step(code); + code + } +} + +/// Samples per channel in a block of `block_align` bytes; `None` for an impossible layout (1 or 2 +/// channels, and room for the header and at least one code byte). +pub fn samples_per_block(block_align: usize, channels: usize) -> Option { + if !(1..=2).contains(&channels) { + return None; + } + let body = block_align.checked_sub(7 * channels).filter(|&b| b > 0)?; + // codes pair up across channels + let per = (body.checked_mul(2)? / channels).checked_add(2)?; + // Include the header samples and all channels before callers size their buffers. + per.checked_mul(channels)?; + Some(per) +} + +/// Decode one block, appending its samples interleaved by channel to `out`. +pub fn decode_block(block: &[u8], channels: usize, out: &mut Vec) -> Result<()> { + let per = samples_per_block(block.len(), channels).ok_or(Error::Malformed("block size does not fit the channel count"))?; + let header = block.get(..7 * channels).ok_or(Error::Malformed("truncated block header"))?; + let mut states = Vec::with_capacity(channels); + let word = |i: usize| i32::from(i16::from_le_bytes([header.get(i).copied().unwrap_or(0), header.get(i + 1).copied().unwrap_or(0)])); + for ch in 0..channels { + let pred = usize::from(header.get(ch).copied().unwrap_or(0)); + let &(c1, c2) = COEFFICIENTS.get(pred).ok_or(Error::Malformed("predictor index above 6"))?; + states.push(State { c1, c2, delta: word(channels + 2 * ch), s1: word(3 * channels + 2 * ch), s2: word(5 * channels + 2 * ch) }); + } + let start = out.len(); + out.resize(start + per * channels, 0); + let samples = out.get_mut(start..).ok_or(Error::Malformed("output"))?; + for (ch, s) in states.iter().enumerate() { + if let Some(a) = samples.get_mut(ch) { + *a = s.s2 as i16; + } + if let Some(b) = samples.get_mut(channels + ch) { + *b = s.s1 as i16; + } + } + let codes = block.get(7 * channels..).ok_or(Error::Malformed("truncated block"))?; + let mut t = 2 * channels; + for byte in codes { + for nibble in [byte >> 4, byte & 0xF] { + let ch = t % channels; + if let (Some(o), Some(state)) = (samples.get_mut(t), states.get_mut(ch)) { + *o = state.step(nibble); + } + t += 1; + } + } + Ok(()) +} + +/// Decode a stream of blocks of `block_align` bytes. A final partial block is decoded in full if +/// it holds a header and a code byte. +pub fn decode(data: &[u8], channels: usize, block_align: usize) -> Result> { + samples_per_block(block_align, channels).ok_or(Error::Malformed("block size does not fit the channel count"))?; + let mut out = Vec::new(); + for block in data.chunks(block_align) { + if block.len() == block_align || samples_per_block(block.len(), channels).is_some() { + decode_block(block, channels, &mut out)?; + } + } + Ok(out) +} + +/// The squared error of encoding `col` (one channel) from state `st`. +fn trial(mut st: State, col: &[i16]) -> i64 { + let mut err = 0i64; + for &s in col { + st.encode(s); + err += (i64::from(s) - i64::from(st.s1)).pow(2); + } + err +} + +/// Encode one block from exactly `samples_per_block * channels` interleaved samples. Each channel +/// gets the coefficient pair and initial step that code it with the least error. +pub fn encode_block(samples: &[i16], channels: usize, block_align: usize) -> Result> { + let per = samples_per_block(block_align, channels).ok_or(Error::InvalidInput("block size does not fit the channel count"))?; + if samples.len() != per * channels { + return Err(Error::InvalidInput("a block needs exactly samples_per_block samples per channel")); + } + let mut block = vec![0u8; block_align]; + let mut states = Vec::with_capacity(channels); + for ch in 0..channels { + let col: Vec = samples.iter().skip(ch).step_by(channels).copied().collect(); + let (x0, x1) = (col.first().copied().unwrap_or(0), col.get(1).copied().unwrap_or(0)); + let rest = col.get(2..).unwrap_or(&[]); + let mut best: Option<(i64, usize, i32)> = None; + for (p, &(c1, c2)) in COEFFICIENTS.iter().enumerate() { + for delta in [16, 64, 256, 1024] { + let st = State { c1, c2, delta, s1: i32::from(x1), s2: i32::from(x0) }; + let e = trial(st, rest); + if best.is_none_or(|(b, _, _)| e < b) { + best = Some((e, p, delta)); + } + } + } + let (_, p, delta) = best.unwrap_or((0, 0, 16)); + let &(c1, c2) = COEFFICIENTS.get(p).unwrap_or(&(256, 0)); + states.push(State { c1, c2, delta, s1: i32::from(x1), s2: i32::from(x0) }); + let (d, a, b) = (delta as i16, x1, x0); + let put = |block: &mut Vec, at: usize, v: i16| { + if let Some(w) = block.get_mut(at..at + 2) { + w.copy_from_slice(&v.to_le_bytes()); + } + }; + if let Some(h) = block.get_mut(ch) { + *h = p as u8; + } + put(&mut block, channels + 2 * ch, d); + put(&mut block, 3 * channels + 2 * ch, a); + put(&mut block, 5 * channels + 2 * ch, b); + } + let mut t = 2 * channels; + for byte in block.iter_mut().skip(7 * channels) { + let mut b = 0u8; + for half in 0..2 { + let ch = t % channels; + let nibble = match states.get_mut(ch) { + Some(st) => st.encode(samples.get(t).copied().unwrap_or(0)), + None => 0, + }; + b |= nibble << (4 * (1 - half)); + t += 1; + } + *byte = b; + } + Ok(block) +} + +/// Encode interleaved samples as blocks of `block_align` bytes. The last block is padded with +/// copies of the last frame, so a decoder returns up to one block more than was given. +pub fn encode(samples: &[i16], channels: usize, block_align: usize) -> Result> { + let per = samples_per_block(block_align, channels).ok_or(Error::InvalidInput("block size does not fit the channel count"))?; + if !samples.len().is_multiple_of(channels) { + return Err(Error::InvalidInput("the sample count is not a multiple of the channel count")); + } + let mut out = Vec::new(); + for chunk in samples.chunks(per * channels) { + let mut padded = chunk.to_vec(); + let last: Vec = chunk.get(chunk.len().saturating_sub(channels)..).unwrap_or(&[]).to_vec(); + while padded.len() < per * channels { + padded.extend(last.iter().copied().chain(std::iter::repeat(0)).take(channels)); + } + out.extend(encode_block(&padded, channels, block_align)?); + } + Ok(out) +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn layout() { + assert_eq!(samples_per_block(256, 1), Some(500)); + assert_eq!(samples_per_block(512, 2), Some(500)); + assert_eq!(samples_per_block(7, 1), None); + assert_eq!(samples_per_block(100, 3), None); + } + + #[test] + fn unrepresentable_layouts_are_rejected() { + for (align, channels) in [(usize::MAX / 2 + 7, 1), (usize::MAX / 2 + 14, 2)] { + assert_eq!(samples_per_block(align, channels), None); + assert!(encode(&[], channels, align).is_err()); + assert!(encode_block(&[], channels, align).is_err()); + } + } + + #[test] + fn a_long_run_of_large_codes_cannot_overflow() { + // a step that starts at its largest 16-bit value and grows with every large code + let mut block = vec![0x77u8; 7 + 2000]; + block[..7].copy_from_slice(&[0, 255, 127, 0, 0, 0, 0]); + for b in block.iter_mut().skip(7) { + *b = 0x88; + } + let mut out = Vec::new(); + decode_block(&block, 1, &mut out).unwrap(); + assert_eq!(out.len(), 2000 * 2 + 2); + } + + #[test] + fn bad_predictor_index_is_an_error() { + let mut block = vec![0u8; 64]; + block[0] = 7; + assert!(decode_block(&block, 1, &mut Vec::new()).is_err()); + } +} diff --git a/crates/audio/src/adpcm/swf.rs b/crates/audio/src/adpcm/swf.rs new file mode 100644 index 000000000..2fc780b1d --- /dev/null +++ b/crates/audio/src/adpcm/swf.rs @@ -0,0 +1,168 @@ +//! The ADPCM of Flash (SWF) audio, 2 to 5 bits per sample. +//! +//! The stream starts with two bits, the code size minus 2. It continues in blocks of 4096 samples +//! per channel: each block starts, for every channel, with the first sample (16 bits, signed) and +//! the step index (6 bits, 0 to 88), then 4095 codes per channel, interleaved by sample. All fields +//! are packed most significant bit first. A code is a sign bit and `bits - 1` magnitude bits; the +//! decoder adds `step >> (bits - 1)` plus `step >> k` for each magnitude bit set `k` places below +//! the top one, negated when the sign is set, and moves the step index by the adjustment table of +//! the code size (negative for small magnitudes, positive for large ones). The last block may +//! be shorter. + +use super::{Error, Result, clip16, step_at}; +use craft_media::bitstream::{BitReader, BitWriter}; + +/// Samples per channel in a full block. +pub const BLOCK_SAMPLES: usize = 4096; + +/// The index adjustment for each magnitude, per code size. +fn adjust(bits: u32) -> &'static [i32] { + match bits { + 2 => &[-1, 2], + 3 => &[-1, -1, 2, 4], + 4 => &[-1, -1, -1, -1, 2, 4, 6, 8], + _ => &[-1, -1, -1, -1, -1, -1, -1, -1, 1, 2, 4, 6, 8, 10, 13, 16], + } +} + +#[derive(Clone, Copy)] +struct State { + predictor: i32, + index: i32, +} + +impl State { + fn apply(&mut self, code: u32, bits: u32) -> i16 { + let step = step_at(self.index); + let mag = code & ((1 << (bits - 1)) - 1); + let mut diff = step >> (bits - 1); + for k in 0..bits - 1 { + if mag & (1 << (bits - 2 - k)) != 0 { + diff += step >> k; + } + } + if code & (1 << (bits - 1)) != 0 { + diff = -diff; + } + self.predictor = clip16(self.predictor + diff); + self.index = (self.index + adjust(bits).get(mag as usize).copied().unwrap_or(0)).clamp(0, 88); + self.predictor as i16 + } + + fn encode(&mut self, sample: i16, bits: u32) -> u32 { + let step = step_at(self.index); + let mut diff = i32::from(sample) - self.predictor; + let mut code = 0u32; + if diff < 0 { + code = 1 << (bits - 1); + diff = -diff; + } + let mut s = step; + for k in 0..bits - 1 { + if diff >= s { + code |= 1 << (bits - 2 - k); + diff -= s; + } + s >>= 1; + } + self.apply(code, bits); + code + } +} + +/// Decode a stream. `channels` is 1 or 2; the code size comes from the stream's first two bits. +/// The result holds every sample up to the end of the data (a last block cut short decodes as +/// far as it goes). +pub fn decode(data: &[u8], channels: usize) -> Result> { + if !(1..=2).contains(&channels) { + return Err(Error::Malformed("Flash ADPCM has one or two channels")); + } + let mut r = BitReader::new(data); + let bits = r.read_bits(2).map_err(|_| Error::Malformed("empty stream"))? + 2; + let mut out = Vec::new(); + let header_bits = channels * 22; + while r.bits_left() >= header_bits { + let mut states = Vec::with_capacity(channels); + for _ in 0..channels { + let sample = r.read_bits(16).map_err(|_| Error::Malformed("truncated block"))? as u16 as i16; + let index = r.read_bits(6).map_err(|_| Error::Malformed("truncated block"))? as i32; + if index > 88 { + return Err(Error::Malformed("step index above 88")); + } + out.push(sample); + states.push(State { predictor: i32::from(sample), index }); + } + 'block: for _ in 1..BLOCK_SAMPLES { + if r.bits_left() < channels * (bits as usize) { + break 'block; + } + for st in states.iter_mut() { + match r.read_bits(bits) { + Ok(code) => out.push(st.apply(code, bits)), + Err(_) => break 'block, + } + } + } + } + Ok(out) +} + +/// Encode interleaved samples with `bits` (2 to 5) bits per sample. Blocks hold 4096 samples per +/// channel; the stream ends at a byte boundary. +pub fn encode(samples: &[i16], channels: usize, bits: u32) -> Result> { + if !(1..=2).contains(&channels) { + return Err(Error::InvalidInput("Flash ADPCM has one or two channels")); + } + if !(2..=5).contains(&bits) { + return Err(Error::InvalidInput("Flash ADPCM codes have 2 to 5 bits")); + } + if !samples.len().is_multiple_of(channels) { + return Err(Error::InvalidInput("the sample count is not a multiple of the channel count")); + } + let mut w = BitWriter::new(); + w.write_bits(bits - 2, 2); + for block in samples.chunks(BLOCK_SAMPLES * channels) { + let mut states = Vec::with_capacity(channels); + for ch in 0..channels { + let col: Vec = block.iter().skip(ch).step_by(channels).copied().collect(); + let first = col.first().copied().unwrap_or(0); + // the index whose first codes follow the signal most closely + let mut best = (i64::MAX, 0); + for index in 0..=63 { + let mut st = State { predictor: i32::from(first), index }; + let mut err = 0i64; + for &s in col.iter().skip(1).take(16) { + st.encode(s, bits); + err += (i64::from(s) - i64::from(st.predictor)).pow(2); + } + if err < best.0 { + best = (err, index); + } + } + w.write_bits(u32::from(first as u16), 16); + w.write_bits(best.1 as u32, 6); + states.push(State { predictor: i32::from(first), index: best.1 }); + } + for frame in block.chunks(channels).skip(1) { + for (st, &s) in states.iter_mut().zip(frame) { + w.write_bits(st.encode(s, bits), bits); + } + } + } + w.align_zero(); + Ok(w.finish()) +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn settings_are_checked() { + assert!(encode(&[0], 3, 4).is_err()); + assert!(encode(&[0], 1, 1).is_err()); + assert!(encode(&[0], 1, 6).is_err()); + assert!(decode(&[], 1).is_err()); + assert!(decode(&[0], 0).is_err()); + } +} diff --git a/crates/audio/src/adpcm/yamaha.rs b/crates/audio/src/adpcm/yamaha.rs new file mode 100644 index 000000000..22ea0e77f --- /dev/null +++ b/crates/audio/src/adpcm/yamaha.rs @@ -0,0 +1,113 @@ +//! Yamaha ADPCM (the ADPCM-B of the YM2608 and the AICA): a raw stream of 4-bit codes, no header. +//! +//! Each channel starts at predictor 0 and step 127. A code is a sign bit and three magnitude bits; +//! the sample moves by `step * [1, 3, 5, 7, 9, 11, 13, 15][magnitude] / 8` (negative when the sign +//! is set) and the step is multiplied by `[230, 230, 230, 230, 307, 409, 512, 614][magnitude] / 256`, +//! kept within 127 and 24576. One channel: the low nibble of a byte is the first sample. Two +//! channels: the low nibble is the left channel and the high nibble the right one of the same +//! frame. + +use super::{Error, Result, clip16}; + +const SCALE: [i32; 8] = [230, 230, 230, 230, 307, 409, 512, 614]; + +#[derive(Clone, Copy)] +struct State { + predictor: i32, + step: i32, +} + +impl State { + fn new() -> State { + State { predictor: 0, step: 127 } + } + + fn apply(&mut self, nibble: u8) -> i16 { + let m = usize::from(nibble & 7); + let diff = self.step * (2 * m as i32 + 1) / 8; + self.predictor = clip16(self.predictor + if nibble & 8 != 0 { -diff } else { diff }); + self.step = ((self.step * SCALE.get(m).copied().unwrap_or(256)) >> 8).clamp(127, 24_576); + self.predictor as i16 + } + + fn encode(&mut self, sample: i16) -> u8 { + let err = i32::from(sample) - self.predictor; + let m = (err.abs() * 8 / self.step / 2).clamp(0, 7); + // the magnitude whose reconstruction (2m + 1) * step / 8 is nearest + let mut best = (i32::MAX, 0u8); + for cand in [m - 1, m, m + 1] { + let c = cand.clamp(0, 7); + let recon = self.step * (2 * c + 1) / 8; + let e = (err.abs() - recon).abs(); + if e < best.0 { + best = (e, c as u8); + } + } + let nibble = best.1 | if err < 0 { 8 } else { 0 }; + self.apply(nibble); + nibble + } +} + +/// Decode a stream of `channels` (1 or 2) interleaved channels. +pub fn decode(data: &[u8], channels: usize) -> Result> { + if !(1..=2).contains(&channels) { + return Err(Error::Malformed("Yamaha ADPCM has one or two channels")); + } + let mut states = vec![State::new(); channels]; + let mut out = Vec::with_capacity(data.len() * 2); + let mut t = 0usize; + for byte in data { + for nibble in [byte & 0xF, byte >> 4] { + if let Some(st) = states.get_mut(t % channels) { + out.push(st.apply(nibble)); + } + t += 1; + } + } + Ok(out) +} + +/// Encode interleaved samples. With two channels the frame count must be whole bytes, which it +/// always is; with one channel an odd count is padded with a copy of the last sample. +pub fn encode(samples: &[i16], channels: usize) -> Result> { + if !(1..=2).contains(&channels) { + return Err(Error::InvalidInput("Yamaha ADPCM has one or two channels")); + } + if !samples.len().is_multiple_of(channels) { + return Err(Error::InvalidInput("the sample count is not a multiple of the channel count")); + } + let mut states = vec![State::new(); channels]; + let mut out = Vec::with_capacity(samples.len().div_ceil(2)); + let mut t = 0usize; + let mut padded = samples.to_vec(); + if padded.len() % 2 == 1 { + padded.push(padded.last().copied().unwrap_or(0)); + } + for pair in padded.chunks(2) { + let mut byte = 0u8; + for (half, &s) in pair.iter().enumerate() { + let code = match states.get_mut(t % channels) { + Some(st) => st.encode(s), + None => 0, + }; + byte |= code << (4 * half); + t += 1; + } + out.push(byte); + } + Ok(out) +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn channel_count_is_checked() { + assert!(decode(&[0], 0).is_err()); + assert!(decode(&[0], 3).is_err()); + assert!(encode(&[0], 3).is_err()); + assert!(encode(&[0, 0, 0], 2).is_err()); + } +} diff --git a/crates/audio/src/dsd/dsdiff.rs b/crates/audio/src/dsd/dsdiff.rs new file mode 100644 index 000000000..f9f12d04d --- /dev/null +++ b/crates/audio/src/dsd/dsdiff.rs @@ -0,0 +1,378 @@ +//! Philips DSDIFF (Direct Stream Digital Interchange File Format, `.dff`) parser and writer. +//! +//! DSDIFF files use an IFF-style big-endian chunk format starting with `FRM8` of type `DSD `: +//! - `FRM8` container chunk containing: +//! - `FVER`: format version (typically 1.5.0.0). +//! - `PROP`: properties chunk with subtype `SND `, containing: +//! - `FS `: sampling frequency (e.g. 2,822,400 Hz for DSD64). +//! - `CHNL`: channel count and 4-character channel ID codes (`SLFT`, `SRGT`, etc.). +//! - `CMPR`: compression type (`DSD ` for uncompressed, `DST ` for compressed). +//! - `DSD `: audio data chunk containing channel-interleaved 1-bit samples (MSB-first). +//! - Optional `DIIN`: disc and track information (title, artist). + +use super::{BitOrder, Error, Format, MAX_CHANNELS, MAX_DECODE_BYTES, MAX_SAMPLE_RATE, MIN_SAMPLE_RATE, Metadata, RawAudio}; + +/// Decodes 4-byte ASCII channel identifiers into human-readable channel names. +fn channel_id_to_name(id: &[u8; 4]) -> String { + match id { + b"SLFT" => "FrontLeft".to_string(), + b"SRGT" => "FrontRight".to_string(), + b"MLFT" => "Mono/Left".to_string(), + b"MRGT" => "Right".to_string(), + b"C " => "Center".to_string(), + b"LFE " => "LFE".to_string(), + b"LS " => "LeftSurround".to_string(), + b"RS " => "RightSurround".to_string(), + b"CO " => "CenterOverhead".to_string(), + b"LH " => "LeftHeight".to_string(), + b"RH " => "RightHeight".to_string(), + _ => { + if let Ok(s) = std::str::from_utf8(id) { + let trimmed = s.trim(); + if !trimmed.is_empty() { + return trimmed.to_string(); + } + } + format!("Channel {:02X}{:02X}{:02X}{:02X}", id[0], id[1], id[2], id[3]) + } + } +} + +/// The text of a `DITI` or `DIAR` chunk: a four-byte big-endian character count, then that many +/// bytes. `None` when the count is missing or longer than the chunk. +fn diin_text(sub_data: &[u8]) -> Option { + let count = usize::try_from(u32::from_be_bytes(sub_data.get(..4)?.try_into().ok()?)).ok()?; + let text = sub_data.get(4..)?.get(..count)?; + Some(String::from_utf8_lossy(text).trim().to_string()) +} + +/// The channel identifiers DSDIFF 1.5 defines for a channel count (stereo, 5 and 5.1 channels); +/// other counts use the generic `C001`, `C002`, ... identifiers. +fn channel_ids(num_channels: usize) -> Vec<[u8; 4]> { + let named: &[&[u8; 4]] = match num_channels { + 1 => &[b"SLFT"], + 2 => &[b"SLFT", b"SRGT"], + 5 => &[b"MLFT", b"MRGT", b"C ", b"LS ", b"RS "], + 6 => &[b"MLFT", b"MRGT", b"C ", b"LFE ", b"LS ", b"RS "], + _ => &[], + }; + if !named.is_empty() { + return named.iter().map(|id| **id).collect(); + } + (1..=num_channels) + .map(|n| { + let s = format!("C{n:03}"); + let mut id = [b' '; 4]; + id.copy_from_slice(&s.as_bytes()[..4]); + id + }) + .collect() +} + +/// Parses the metadata from a DSDIFF file. +pub fn parse_dsdiff_header(bytes: &[u8]) -> Result<(Metadata, usize, usize), Error> { + if bytes.len() < 16 { + return Err(Error::UnexpectedEof("DSDIFF file is too short")); + } + + if &bytes[0..4] != b"FRM8" { + return Err(Error::InvalidHeader("missing 'FRM8' magic chunk")); + } + let form_size = u64::from_be_bytes(bytes[4..12].try_into().map_err(|_| Error::UnexpectedEof("FRM8 size"))?); + if &bytes[12..16] != b"DSD " { + return Err(Error::InvalidHeader("invalid FRM8 form type (expected 'DSD ')")); + } + + let total_file_data = bytes.len().saturating_sub(12); + let form_size = usize::try_from(form_size).map_err(|_| Error::MemoryLimitExceeded)?; + if form_size > total_file_data { + return Err(Error::UnexpectedEof("FRM8 chunk extends beyond file size")); + } + + let mut pos = 16; + let end = 12 + form_size; + + let mut sample_rate = None; + let mut channel_names = Vec::new(); + let mut num_channels = None; + let mut is_compressed_dst = false; + let mut dsd_data_offset = None; + let mut dsd_data_len = None; + let mut title = None; + let mut artist = None; + + while pos + 12 <= end { + let chunk_id: [u8; 4] = bytes[pos..pos + 4].try_into().map_err(|_| Error::UnexpectedEof("chunk ID"))?; + let chunk_size = usize::try_from(u64::from_be_bytes(bytes[pos + 4..pos + 12].try_into().map_err(|_| Error::UnexpectedEof("chunk size"))?)) + .map_err(|_| Error::MemoryLimitExceeded)?; + pos += 12; + + if chunk_size > end.saturating_sub(pos) { + return Err(Error::UnexpectedEof("subchunk extends beyond container bounds")); + } + + let chunk_data = &bytes[pos..pos + chunk_size]; + let pad = chunk_size & 1; + pos = pos.saturating_add(chunk_size).saturating_add(pad); + + match &chunk_id { + b"PROP" => { + if chunk_data.len() < 4 { + continue; + } + if &chunk_data[0..4] != b"SND " { + continue; + } + let mut prop_pos = 4; + while prop_pos + 12 <= chunk_data.len() { + let sub_id: [u8; 4] = chunk_data[prop_pos..prop_pos + 4].try_into().map_err(|_| Error::UnexpectedEof("PROP subchunk ID"))?; + let sub_size = usize::try_from(u64::from_be_bytes( + chunk_data[prop_pos + 4..prop_pos + 12].try_into().map_err(|_| Error::UnexpectedEof("PROP subchunk size"))?, + )) + .map_err(|_| Error::MemoryLimitExceeded)?; + prop_pos += 12; + + if sub_size > chunk_data.len().saturating_sub(prop_pos) { + return Err(Error::UnexpectedEof("PROP subchunk extends beyond bounds")); + } + + let sub_data = &chunk_data[prop_pos..prop_pos + sub_size]; + let sub_pad = sub_size & 1; + prop_pos = prop_pos.saturating_add(sub_size).saturating_add(sub_pad); + + match &sub_id { + b"FS " => { + if sub_data.len() < 4 { + return Err(Error::UnexpectedEof("truncated FS chunk")); + } + if sample_rate.is_some() { + return Err(Error::InvalidHeader("duplicate FS chunk")); + } + let sr = u32::from_be_bytes([sub_data[0], sub_data[1], sub_data[2], sub_data[3]]); + if !(MIN_SAMPLE_RATE..=MAX_SAMPLE_RATE).contains(&sr) { + return Err(Error::InvalidHeader("sampling frequency out of range")); + } + sample_rate = Some(sr); + } + b"CHNL" => { + if sub_data.len() < 2 { + return Err(Error::UnexpectedEof("truncated CHNL chunk")); + } + if num_channels.is_some() { + return Err(Error::InvalidHeader("duplicate CHNL chunk")); + } + let n = u16::from_be_bytes([sub_data[0], sub_data[1]]); + if n == 0 || n > MAX_CHANNELS as u16 { + return Err(Error::Unsupported("channel count must be between 1 and 8")); + } + num_channels = Some(n); + channel_names.clear(); + let mut ch_pos = 2; + while ch_pos + 4 <= sub_data.len() && channel_names.len() < n as usize { + let id: [u8; 4] = [sub_data[ch_pos], sub_data[ch_pos + 1], sub_data[ch_pos + 2], sub_data[ch_pos + 3]]; + channel_names.push(channel_id_to_name(&id)); + ch_pos += 4; + } + } + b"CMPR" if sub_data.len() >= 4 => { + if &sub_data[0..4] == b"DST " { + is_compressed_dst = true; + } else if &sub_data[0..4] != b"DSD " { + return Err(Error::Unsupported("unknown DSDIFF compression type")); + } + } + _ => {} + } + } + } + b"DSD " => { + dsd_data_offset = Some(pos - chunk_size - pad); + dsd_data_len = Some(chunk_size); + } + b"DST " => { + is_compressed_dst = true; + } + b"DIIN" => { + // Parse optional disc info for title and artist. + let mut diin_pos = 0; + while diin_pos + 12 <= chunk_data.len() { + let sub_id = &chunk_data[diin_pos..diin_pos + 4]; + let sub_size = usize::try_from(u64::from_be_bytes( + chunk_data[diin_pos + 4..diin_pos + 12].try_into().map_err(|_| Error::UnexpectedEof("DIIN subchunk size"))?, + )) + .map_err(|_| Error::MemoryLimitExceeded)?; + diin_pos += 12; + if sub_size > chunk_data.len().saturating_sub(diin_pos) { + break; + } + let sub_data = &chunk_data[diin_pos..diin_pos + sub_size]; + let sub_pad = sub_size & 1; + diin_pos = diin_pos.saturating_add(sub_size).saturating_add(sub_pad); + + if sub_id == b"DITI" && title.is_none() { + title = diin_text(sub_data); + } else if sub_id == b"DIAR" && artist.is_none() { + artist = diin_text(sub_data); + } + } + } + _ => {} + } + } + + if is_compressed_dst { + return Err(Error::Unsupported("DST compression in DSDIFF is not yet supported")); + } + + let sample_rate = sample_rate.ok_or(Error::InvalidHeader("missing sample rate ('FS ' chunk)"))?; + if !(MIN_SAMPLE_RATE..=MAX_SAMPLE_RATE).contains(&sample_rate) { + return Err(Error::InvalidHeader("sampling frequency out of range")); + } + + let channels = num_channels.ok_or(Error::InvalidHeader("missing channel info ('CHNL' chunk)"))?; + if channels == 0 || channels > MAX_CHANNELS as u16 { + return Err(Error::Unsupported("channel count must be between 1 and 8")); + } + + let data_offset = dsd_data_offset.ok_or(Error::InvalidHeader("missing audio data ('DSD ' chunk)"))?; + let data_len = dsd_data_len.ok_or(Error::InvalidHeader("missing audio data length"))?; + + let bytes_per_channel = data_len / (channels as usize); + let sample_count = (bytes_per_channel as u64).saturating_mul(8); + + if channel_names.len() < channels as usize { + for c in channel_names.len()..(channels as usize) { + channel_names.push(format!("Channel {}", c + 1)); + } + } + + let metadata = Metadata { format: Format::Dsdiff, sample_rate, channels, sample_count, channel_names, title, artist }; + + Ok((metadata, data_offset, data_len)) +} + +/// Parses a DSDIFF file into raw 1-bit planar channel streams. +pub fn parse_dsdiff(bytes: &[u8]) -> Result { + let (metadata, data_offset, data_len) = parse_dsdiff_header(bytes)?; + let channels = metadata.channels as usize; + let bytes_per_channel = data_len / channels; + + if bytes_per_channel.saturating_mul(channels) > MAX_DECODE_BYTES { + return Err(Error::MemoryLimitExceeded); + } + + let end_offset = data_offset + data_len; + if end_offset > bytes.len() { + return Err(Error::UnexpectedEof("DSD sound data extends beyond file bounds")); + } + let data_slice = &bytes[data_offset..end_offset]; + + let mut channel_bytes: Vec> = Vec::with_capacity(channels); + for _ in 0..channels { + let mut ch_vec = Vec::new(); + ch_vec.try_reserve_exact(bytes_per_channel).map_err(|_| Error::MemoryLimitExceeded)?; + channel_bytes.push(ch_vec); + } + + // De-interleave byte-by-byte: Ch0, Ch1, ... Ch(N-1), Ch0, Ch1 ... + for chunk in data_slice.chunks_exact(channels) { + for (c, &byte) in chunk.iter().enumerate() { + if let Some(ch_vec) = channel_bytes.get_mut(c) { + ch_vec.push(byte); + } + } + } + + Ok(RawAudio { metadata, bit_order: BitOrder::MsbFirst, channel_bytes }) +} + +/// Encodes 1-bit planar audio channels into a valid Philips DSDIFF (`.dff`) file. +pub fn write_dsdiff(sample_rate: u32, channels: &[&[u8]], sample_count: u64) -> Result, Error> { + if channels.is_empty() || channels.len() > MAX_CHANNELS { + return Err(Error::Unsupported("channel count must be between 1 and 8")); + } + if !(MIN_SAMPLE_RATE..=MAX_SAMPLE_RATE).contains(&sample_rate) { + return Err(Error::InvalidData("sample rate out of bounds")); + } + + let num_channels = channels.len(); + let bytes_per_ch = usize::try_from(sample_count.div_ceil(8)).map_err(|_| Error::MemoryLimitExceeded)?; + let data_size = bytes_per_ch.checked_mul(num_channels).ok_or(Error::MemoryLimitExceeded)?; + // Fixed headers plus four bytes for each channel identifier. + // An odd-sized chunk payload is followed by a pad byte that its size field does not count. + let data_pad = data_size & 1; + let padded_size = data_size.checked_add(data_pad).ok_or(Error::MemoryLimitExceeded)?; + let file_size = super::encoded_size(padded_size, 110 + 4 * num_channels)?; + + // Build PROP subchunks: + // 1. 'FS ' (4 bytes + 12 chunk header) + let mut fs_chunk = Vec::with_capacity(16); + fs_chunk.extend_from_slice(b"FS "); + fs_chunk.extend_from_slice(&4u64.to_be_bytes()); + fs_chunk.extend_from_slice(&sample_rate.to_be_bytes()); + + // 2. 'CHNL' (2 + 4 * num_channels + 12 chunk header) + let chnl_data_len = 2 + 4 * num_channels; + let mut chnl_chunk = Vec::with_capacity(12 + chnl_data_len + 1); + chnl_chunk.extend_from_slice(b"CHNL"); + chnl_chunk.extend_from_slice(&(chnl_data_len as u64).to_be_bytes()); + chnl_chunk.extend_from_slice(&(num_channels as u16).to_be_bytes()); + for id in channel_ids(num_channels) { + chnl_chunk.extend_from_slice(&id); + } + if !chnl_data_len.is_multiple_of(2) { + chnl_chunk.push(0); + } + + // 3. 'CMPR' (4 + 1 + 3 + pad = 8 bytes + 12 chunk header) + let mut cmpr_chunk = Vec::with_capacity(20); + cmpr_chunk.extend_from_slice(b"CMPR"); + cmpr_chunk.extend_from_slice(&8u64.to_be_bytes()); + cmpr_chunk.extend_from_slice(b"DSD "); + cmpr_chunk.push(3); // name len + cmpr_chunk.extend_from_slice(b"DSD"); + + let prop_payload_len = 4 + fs_chunk.len() + chnl_chunk.len() + cmpr_chunk.len(); + let mut prop_chunk = Vec::with_capacity(12 + prop_payload_len); + prop_chunk.extend_from_slice(b"PROP"); + prop_chunk.extend_from_slice(&(prop_payload_len as u64).to_be_bytes()); + prop_chunk.extend_from_slice(b"SND "); + prop_chunk.extend_from_slice(&fs_chunk); + prop_chunk.extend_from_slice(&chnl_chunk); + prop_chunk.extend_from_slice(&cmpr_chunk); + + // FVER chunk (4 bytes payload + 12 chunk header) + let mut fver_chunk = Vec::with_capacity(16); + fver_chunk.extend_from_slice(b"FVER"); + fver_chunk.extend_from_slice(&4u64.to_be_bytes()); + fver_chunk.extend_from_slice(&0x01050000u32.to_be_bytes()); + + // DSD chunk (data_size payload + 12 chunk header) + let mut dsd_chunk_hdr = Vec::with_capacity(12); + dsd_chunk_hdr.extend_from_slice(b"DSD "); + dsd_chunk_hdr.extend_from_slice(&(data_size as u64).to_be_bytes()); + + let frm8_payload_len = file_size - 12; + let mut out = Vec::new(); + out.try_reserve_exact(file_size).map_err(|_| Error::MemoryLimitExceeded)?; + + out.extend_from_slice(b"FRM8"); + out.extend_from_slice(&(frm8_payload_len as u64).to_be_bytes()); + out.extend_from_slice(b"DSD "); + out.extend_from_slice(&fver_chunk); + out.extend_from_slice(&prop_chunk); + out.extend_from_slice(&dsd_chunk_hdr); + + // Interleave channels byte-by-byte. + for i in 0..bytes_per_ch { + for ch_data in channels { + let byte = ch_data.get(i).copied().unwrap_or(super::filter::SILENCE_MSBF); + out.push(byte); + } + } + if data_pad == 1 { + out.push(0); + } + + Ok(out) +} diff --git a/crates/audio/src/dsd/dsf.rs b/crates/audio/src/dsd/dsf.rs new file mode 100644 index 000000000..1fb36c18d --- /dev/null +++ b/crates/audio/src/dsd/dsf.rs @@ -0,0 +1,391 @@ +//! Sony DSF (Direct Stream Digital File) parser and writer. +//! +//! A DSF file consists of three contiguous little-endian chunks: +//! - `'DSD '` chunk (28 bytes): file identification, total size, and metadata offset. +//! - `'fmt '` chunk (52 bytes): sample rate, channel count, sample count, block size. +//! - `'data'` chunk (12 bytes + data): 1-bit audio organized into channel blocks. +//! - Optional ID3v2 metadata chunk located at `metadata_offset`. + +use super::{BitOrder, Error, Format, MAX_BLOCK_SIZE, MAX_CHANNELS, MAX_DECODE_BYTES, MAX_SAMPLE_RATE, MIN_SAMPLE_RATE, Metadata, RawAudio}; + +/// Channel configuration names for DSF channel types 1..=7. +fn dsf_channel_names(channel_type: u32, channel_count: u16) -> Vec { + match channel_type { + 1 => vec!["Mono".to_string()], + 2 => vec!["Left".to_string(), "Right".to_string()], + 3 => vec!["Left".to_string(), "Right".to_string(), "Center".to_string()], + 4 => vec!["FrontLeft".to_string(), "FrontRight".to_string(), "BackLeft".to_string(), "BackRight".to_string()], + 5 => vec!["FrontLeft".to_string(), "FrontRight".to_string(), "Center".to_string(), "LFE".to_string()], + 6 => vec!["FrontLeft".to_string(), "FrontRight".to_string(), "Center".to_string(), "BackLeft".to_string(), "BackRight".to_string()], + 7 => vec![ + "FrontLeft".to_string(), + "FrontRight".to_string(), + "Center".to_string(), + "LFE".to_string(), + "BackLeft".to_string(), + "BackRight".to_string(), + ], + _ => (0..channel_count).map(|c| format!("Channel {}", c + 1)).collect(), + } +} + +/// Attempts to parse basic ID3v2 title and artist tags if present at `offset`. +fn parse_id3v2(bytes: &[u8], offset: usize) -> (Option, Option) { + let Some(id3) = bytes.get(offset..) else { + return (None, None); + }; + if id3.len() < 10 || &id3[..3] != b"ID3" { + return (None, None); + } + + let mut title = None; + let mut artist = None; + + // ID3v2 size is 4 synchsafe bytes at offset 6. + let tag_size = ((id3[6] as usize & 0x7F) << 21) | ((id3[7] as usize & 0x7F) << 14) | ((id3[8] as usize & 0x7F) << 7) | (id3[9] as usize & 0x7F); + + let end = (10 + tag_size).min(id3.len()); + let mut pos = 10; + + // Scan ID3v2.3 / ID3v2.4 frames. + while pos + 10 <= end { + let frame_id = &id3[pos..pos + 4]; + if frame_id[0] == 0 { + break; + } + let raw = [id3[pos + 4], id3[pos + 5], id3[pos + 6], id3[pos + 7]]; + // ID3v2.4 frame sizes are synchsafe; v2.3 ones are plain big-endian. + let frame_size = if id3[3] >= 4 { + if raw.iter().any(|b| b & 0x80 != 0) { + break; + } + ((raw[0] as usize) << 21) | ((raw[1] as usize) << 14) | ((raw[2] as usize) << 7) | raw[3] as usize + } else { + u32::from_be_bytes(raw) as usize + }; + pos += 10; + if frame_size > end.saturating_sub(pos) { + break; + } + + let frame_data = &id3[pos..pos + frame_size]; + pos += frame_size; + + if frame_id == b"TIT2" && title.is_none() { + title = parse_text_frame(frame_data); + } else if frame_id == b"TPE1" && artist.is_none() { + artist = parse_text_frame(frame_data); + } + } + + (title, artist) +} + +fn parse_text_frame(data: &[u8]) -> Option { + if data.is_empty() { + return None; + } + let encoding = data[0]; + let content = &data[1..]; + let text = match encoding { + // ISO-8859-1: every byte is the code point of the same value. + 0 => content.iter().map(|&b| char::from(b)).collect::(), + 3 => String::from_utf8_lossy(content).into_owned(), + // UTF-16 with a byte order mark (which is removed); without one, assume big-endian. + 1 => { + let (big_endian, body) = match content { + [0xFE, 0xFF, rest @ ..] => (true, rest), + [0xFF, 0xFE, rest @ ..] => (false, rest), + _ => (true, content), + }; + utf16(body, big_endian) + } + // UTF-16BE without a byte order mark. + 2 => utf16(content, true), + _ => return None, + }; + let s = text.trim_end_matches('\0').trim().to_string(); + if s.is_empty() { None } else { Some(s) } +} + +fn utf16(bytes: &[u8], big_endian: bool) -> String { + let units: Vec = bytes + .as_chunks::<2>() + .0 + .iter() + .map(|c| if big_endian { u16::from_be_bytes([c[0], c[1]]) } else { u16::from_le_bytes([c[0], c[1]]) }) + .collect(); + String::from_utf16_lossy(&units) +} + +/// Parses DSF file metadata, returning the metadata, audio data offset, and block size per channel. +pub fn parse_dsf_header(bytes: &[u8]) -> Result<(Metadata, usize, u32), Error> { + let (metadata, offset, _, block_size) = parse_dsf_header_bounded(bytes)?; + Ok((metadata, offset, block_size)) +} + +fn parse_dsf_header_bounded(bytes: &[u8]) -> Result<(Metadata, usize, usize, u32), Error> { + if bytes.len() < 28 + 52 + 12 { + return Err(Error::UnexpectedEof("DSF file header is truncated")); + } + + // 1. 'DSD ' chunk + if &bytes[..4] != b"DSD " { + return Err(Error::InvalidHeader("missing 'DSD ' magic header")); + } + let dsd_chunk_size = u64::from_le_bytes(bytes[4..12].try_into().map_err(|_| Error::UnexpectedEof("DSD chunk size"))?); + if dsd_chunk_size != 28 { + return Err(Error::InvalidHeader("invalid 'DSD ' chunk size (must be 28)")); + } + let file_size = u64::from_le_bytes(bytes[12..20].try_into().map_err(|_| Error::UnexpectedEof("file size"))?); + let metadata_offset = u64::from_le_bytes(bytes[20..28].try_into().map_err(|_| Error::UnexpectedEof("metadata offset"))?); + + if file_size > bytes.len() as u64 { + return Err(Error::UnexpectedEof("declared file size extends beyond buffer")); + } + let file_len = usize::try_from(file_size).map_err(|_| Error::MemoryLimitExceeded)?; + if file_len < 28 + 52 + 12 { + return Err(Error::InvalidHeader("declared file size is smaller than required headers")); + } + let file_bytes = &bytes[..file_len]; + + // 2. 'fmt ' chunk + let fmt_offset = 28; + if &file_bytes[fmt_offset..fmt_offset + 4] != b"fmt " { + return Err(Error::InvalidHeader("missing 'fmt ' chunk header")); + } + let fmt_chunk_size = + u64::from_le_bytes(file_bytes[fmt_offset + 4..fmt_offset + 12].try_into().map_err(|_| Error::UnexpectedEof("fmt chunk size"))?); + if fmt_chunk_size < 52 { + return Err(Error::InvalidHeader("invalid 'fmt ' chunk size (must be at least 52)")); + } + let fmt_size = usize::try_from(fmt_chunk_size).map_err(|_| Error::MemoryLimitExceeded)?; + if fmt_size > file_bytes.len().saturating_sub(fmt_offset) { + return Err(Error::UnexpectedEof("fmt chunk extends beyond file bounds")); + } + + let format_version = + u32::from_le_bytes(file_bytes[fmt_offset + 12..fmt_offset + 16].try_into().map_err(|_| Error::UnexpectedEof("format version"))?); + if format_version != 1 { + return Err(Error::Unsupported("unsupported DSF format version (only version 1 is supported)")); + } + + let format_id = u32::from_le_bytes(file_bytes[fmt_offset + 16..fmt_offset + 20].try_into().map_err(|_| Error::UnexpectedEof("format id"))?); + if format_id != 0 { + return Err(Error::Unsupported("unsupported DSF format id (only raw DSD id=0 is supported)")); + } + + let channel_type = u32::from_le_bytes(file_bytes[fmt_offset + 20..fmt_offset + 24].try_into().map_err(|_| Error::UnexpectedEof("channel type"))?); + let channel_count = + u32::from_le_bytes(file_bytes[fmt_offset + 24..fmt_offset + 28].try_into().map_err(|_| Error::UnexpectedEof("channel count"))?); + if channel_count == 0 || channel_count > MAX_CHANNELS as u32 { + return Err(Error::Unsupported("DSF channel count must be between 1 and 8")); + } + let channels = channel_count as u16; + + let sample_rate = + u32::from_le_bytes(file_bytes[fmt_offset + 28..fmt_offset + 32].try_into().map_err(|_| Error::UnexpectedEof("sampling frequency"))?); + if !(MIN_SAMPLE_RATE..=MAX_SAMPLE_RATE).contains(&sample_rate) { + return Err(Error::InvalidHeader("DSF sampling frequency out of valid range")); + } + + let bits_per_sample = + u32::from_le_bytes(file_bytes[fmt_offset + 32..fmt_offset + 36].try_into().map_err(|_| Error::UnexpectedEof("bits per sample"))?); + if bits_per_sample != 1 { + return Err(Error::Unsupported("DSF bits per sample must be 1")); + } + + let sample_count = u64::from_le_bytes(file_bytes[fmt_offset + 36..fmt_offset + 44].try_into().map_err(|_| Error::UnexpectedEof("sample count"))?); + + let block_size_per_channel = + u32::from_le_bytes(file_bytes[fmt_offset + 44..fmt_offset + 48].try_into().map_err(|_| Error::UnexpectedEof("block size per channel"))?); + if block_size_per_channel == 0 || block_size_per_channel > MAX_BLOCK_SIZE { + return Err(Error::InvalidHeader("DSF block size per channel is invalid or too large")); + } + + // 3. 'data' chunk + let data_offset = fmt_offset.saturating_add(fmt_size); + if data_offset.saturating_add(12) > file_bytes.len() { + return Err(Error::UnexpectedEof("missing 'data' chunk header")); + } + if &file_bytes[data_offset..data_offset + 4] != b"data" { + return Err(Error::InvalidHeader("missing 'data' chunk header")); + } + let data_chunk_size = + u64::from_le_bytes(file_bytes[data_offset + 4..data_offset + 12].try_into().map_err(|_| Error::UnexpectedEof("data chunk size"))?); + if data_chunk_size < 12 { + return Err(Error::InvalidHeader("invalid 'data' chunk size (must be at least 12)")); + } + + let payload_offset = data_offset + 12; + let payload_size = usize::try_from(data_chunk_size - 12).map_err(|_| Error::MemoryLimitExceeded)?; + if payload_size > file_bytes.len().saturating_sub(payload_offset) { + return Err(Error::UnexpectedEof("data chunk payload extends beyond file bounds")); + } + let data_end = payload_offset.saturating_add(payload_size); + + // Parse ID3v2 metadata if pointer is valid. + let (title, artist) = if metadata_offset == 0 { + (None, None) + } else { + let meta_offset = usize::try_from(metadata_offset).map_err(|_| Error::MemoryLimitExceeded)?; + if meta_offset < data_end || meta_offset >= file_len { + return Err(Error::InvalidHeader("DSF metadata offset outside declared file bounds")); + } + parse_id3v2(file_bytes, meta_offset) + }; + + let channel_names = dsf_channel_names(channel_type, channels); + + let metadata = Metadata { format: Format::Dsf, sample_rate, channels, sample_count, channel_names, title, artist }; + + Ok((metadata, payload_offset, payload_size, block_size_per_channel)) +} + +/// Parses a DSF file into raw 1-bit planar channel streams. +pub fn parse_dsf(bytes: &[u8]) -> Result { + let (metadata, payload_offset, payload_size, block_size) = parse_dsf_header_bounded(bytes)?; + let block_size = block_size as usize; + let channels = metadata.channels as usize; + + let target_bytes_per_channel = usize::try_from(metadata.sample_count.div_ceil(8)).map_err(|_| Error::MemoryLimitExceeded)?; + if target_bytes_per_channel.saturating_mul(channels) > MAX_DECODE_BYTES { + return Err(Error::MemoryLimitExceeded); + } + + let slice_size = channels.saturating_mul(block_size); + if slice_size == 0 { + return Err(Error::InvalidHeader("zero slice size")); + } + + // The header validated this range. Trailing ID3 or other bytes are not audio, + // even if sample_count asks for more samples than the data chunk contains. + let payload = &bytes[payload_offset..payload_offset + payload_size]; + let num_slices = payload.len() / slice_size; + + let mut channel_bytes: Vec> = Vec::with_capacity(channels); + for _ in 0..channels { + let mut ch_vec = Vec::new(); + ch_vec.try_reserve_exact(target_bytes_per_channel).map_err(|_| Error::MemoryLimitExceeded)?; + channel_bytes.push(ch_vec); + } + + for s in 0..num_slices { + let slice_base = s * slice_size; + for (c, ch_vec) in channel_bytes.iter_mut().enumerate() { + let ch_start = slice_base + c * block_size; + let ch_end = ch_start + block_size; + if let Some(block) = payload.get(ch_start..ch_end) { + let remaining = target_bytes_per_channel.saturating_sub(ch_vec.len()); + let take = block.len().min(remaining); + ch_vec.extend_from_slice(&block[..take]); + } + } + } + + // Handle any trailing partial slice. + let remainder = payload.len() % slice_size; + if remainder > 0 { + let slice_base = num_slices * slice_size; + for (c, ch_vec) in channel_bytes.iter_mut().enumerate() { + let ch_start = slice_base + c * block_size; + if ch_start < payload.len() { + let ch_end = (ch_start + block_size).min(payload.len()); + let block = &payload[ch_start..ch_end]; + let remaining = target_bytes_per_channel.saturating_sub(ch_vec.len()); + let take = block.len().min(remaining); + ch_vec.extend_from_slice(&block[..take]); + } + } + } + + // Pad with silence (0x69) if the file had fewer bytes than required by sample_count. + for ch_vec in &mut channel_bytes { + if ch_vec.len() < target_bytes_per_channel { + ch_vec.resize(target_bytes_per_channel, super::filter::SILENCE_LSBF); + } + } + + Ok(RawAudio { metadata, bit_order: BitOrder::LsbFirst, channel_bytes }) +} + +fn unsupported_channel_layout() -> Result { + Err(Error::Unsupported("DSF has no channel type for this channel count (1 to 6 are supported)")) +} + +/// Encodes 1-bit planar audio channels into a valid Sony DSF file. +pub fn write_dsf(sample_rate: u32, channels: &[&[u8]], sample_count: u64, block_size: u32) -> Result, Error> { + if channels.is_empty() || channels.len() > MAX_CHANNELS { + return Err(Error::Unsupported("channel count must be between 1 and 8")); + } + if !(MIN_SAMPLE_RATE..=MAX_SAMPLE_RATE).contains(&sample_rate) { + return Err(Error::InvalidData("sample rate out of bounds")); + } + if block_size > MAX_BLOCK_SIZE { + return Err(Error::InvalidData("DSF block size exceeds maximum")); + } + let block_size = if block_size == 0 { 4096 } else { block_size as usize }; + + let num_channels = channels.len(); + let bytes_per_ch = usize::try_from(sample_count.div_ceil(8)).map_err(|_| Error::MemoryLimitExceeded)?; + let num_blocks = bytes_per_ch.div_ceil(block_size); + let payload_size = num_blocks.checked_mul(num_channels).and_then(|n| n.checked_mul(block_size)).ok_or(Error::MemoryLimitExceeded)?; + let file_size = super::encoded_size(payload_size, 92)?; + + let data_chunk_size = 12u64 + payload_size as u64; + + let mut out = Vec::new(); + out.try_reserve_exact(file_size).map_err(|_| Error::MemoryLimitExceeded)?; + + // 1. 'DSD ' chunk (28 bytes) + out.extend_from_slice(b"DSD "); + out.extend_from_slice(&28u64.to_le_bytes()); + out.extend_from_slice(&(file_size as u64).to_le_bytes()); + out.extend_from_slice(&0u64.to_le_bytes()); // metadata offset = 0 + + // 2. 'fmt ' chunk (52 bytes) + out.extend_from_slice(b"fmt "); + out.extend_from_slice(&52u64.to_le_bytes()); + out.extend_from_slice(&1u32.to_le_bytes()); // format_version = 1 + out.extend_from_slice(&0u32.to_le_bytes()); // format_id = 0 (raw DSD) + // DSF channel types: 1 mono, 2 stereo, 3 L R C, 4 quad, 6 five channels, 7 5.1. + let channel_type = match num_channels { + 1 => 1u32, + 2 => 2, + 3 => 3, + 4 => 4, + 5 => 6, + 6 => 7, + _ => unsupported_channel_layout()?, + }; + out.extend_from_slice(&channel_type.to_le_bytes()); + out.extend_from_slice(&(num_channels as u32).to_le_bytes()); + out.extend_from_slice(&sample_rate.to_le_bytes()); + out.extend_from_slice(&1u32.to_le_bytes()); // bits_per_sample = 1 + out.extend_from_slice(&sample_count.to_le_bytes()); + out.extend_from_slice(&(block_size as u32).to_le_bytes()); + out.extend_from_slice(&0u32.to_le_bytes()); // reserved + + // 3. 'data' chunk + out.extend_from_slice(b"data"); + out.extend_from_slice(&data_chunk_size.to_le_bytes()); + + for b in 0..num_blocks { + let blk_start = b * block_size; + let blk_end = blk_start + block_size; + for ch_data in channels { + let available = if blk_start < ch_data.len() { + let end = blk_end.min(ch_data.len()); + &ch_data[blk_start..end] + } else { + &[] + }; + out.extend_from_slice(available); + if available.len() < block_size { + out.resize(out.len() + (block_size - available.len()), super::filter::SILENCE_LSBF); + } + } + } + + Ok(out) +} diff --git a/crates/audio/src/dsd/filter.rs b/crates/audio/src/dsd/filter.rs new file mode 100644 index 000000000..ec815afd1 --- /dev/null +++ b/crates/audio/src/dsd/filter.rs @@ -0,0 +1,288 @@ +//! DSD-to-PCM decimation filter. +//! +//! Direct Stream Digital (DSD) uses 1-bit Sigma-Delta modulation sampled at high rates +//! (2,822,400 Hz for DSD64, 5,644,800 Hz for DSD128, etc.). Decimation to multi-bit PCM +//! involves low-pass filtering to attenuate high-frequency quantization noise followed +//! by downsampling. +//! +//! This module provides a 96-tap symmetric FIR decimation filter that downsamples 1-bit DSD +//! to multi-bit PCM at 1/8th of the DSD sampling rate (e.g. 352,800 Hz for DSD64). Further +//! integer decimation (to 176.4 kHz, 88.2 kHz, or 44.1 kHz) is supported via subsequent +//! downsampling stages. + +use super::{BitOrder, Error, MAX_DECODE_BYTES}; + +/// 96-tap symmetric FIR decimation filter coefficients for decimation by 8. +/// +/// Output is normalized so that alternating silence bits (0x69 or 0xAA) decode near 0.0, +/// and full-scale runs of 1s or 0s decode near +1.0 and -1.0. +#[allow(clippy::excessive_precision)] +pub const TAPS_96: [f32; 96] = [ + 2.9802322388e-08_f32, + 1.1920928955e-07_f32, + 3.5762786865e-07_f32, + 7.4505805969e-07_f32, + 1.3113021851e-06_f32, + 1.9371509552e-06_f32, + 2.1755695343e-06_f32, + 1.2516975403e-06_f32, + -1.9967556000e-06_f32, + -9.1493129730e-06_f32, + -2.1725893021e-05_f32, + -4.0739774704e-05_f32, + -6.5773725510e-05_f32, + -9.3966722488e-05_f32, + -1.1900067329e-04_f32, + -1.3050436974e-04_f32, + -1.1405348778e-04_f32, + -5.2779912949e-05_f32, + 7.0035457611e-05_f32, + 2.6643276215e-04_f32, + 5.3817033768e-04_f32, + 8.7043642998e-04_f32, + 1.2266933918e-03_f32, + 1.5456080437e-03_f32, + 1.7420351505e-03_f32, + 1.7137229443e-03_f32, + 1.3538300991e-03_f32, + 5.7008862495e-04_f32, + -6.9221854210e-04_f32, + -2.4250447750e-03_f32, + -4.5351684093e-03_f32, + -6.8288743496e-03_f32, + -9.0079009533e-03_f32, + -1.0681360960e-02_f32, + -1.1394292116e-02_f32, + -1.0672420263e-02_f32, + -8.0802738667e-03_f32, + -3.2847225666e-03_f32, + 3.8830339909e-03_f32, + 1.3377487659e-02_f32, + 2.4909228086e-02_f32, + 3.7942945957e-02_f32, + 5.1726281643e-02_f32, + 6.5348774195e-02_f32, + 7.7825516462e-02_f32, + 8.8196486235e-02_f32, + 9.5628470182e-02_f32, + 9.9507331848e-02_f32, + 9.9507331848e-02_f32, + 9.5628470182e-02_f32, + 8.8196486235e-02_f32, + 7.7825516462e-02_f32, + 6.5348774195e-02_f32, + 5.1726281643e-02_f32, + 3.7942945957e-02_f32, + 2.4909228086e-02_f32, + 1.3377487659e-02_f32, + 3.8830339909e-03_f32, + -3.2847225666e-03_f32, + -8.0802738667e-03_f32, + -1.0672420263e-02_f32, + -1.1394292116e-02_f32, + -1.0681360960e-02_f32, + -9.0079009533e-03_f32, + -6.8288743496e-03_f32, + -4.5351684093e-03_f32, + -2.4250447750e-03_f32, + -6.9221854210e-04_f32, + 5.7008862495e-04_f32, + 1.3538300991e-03_f32, + 1.7137229443e-03_f32, + 1.7420351505e-03_f32, + 1.5456080437e-03_f32, + 1.2266933918e-03_f32, + 8.7043642998e-04_f32, + 5.3817033768e-04_f32, + 2.6643276215e-04_f32, + 7.0035457611e-05_f32, + -5.2779912949e-05_f32, + -1.1405348778e-04_f32, + -1.3050436974e-04_f32, + -1.1900067329e-04_f32, + -9.3966722488e-05_f32, + -6.5773725510e-05_f32, + -4.0739774704e-05_f32, + -2.1725893021e-05_f32, + -9.1493129730e-06_f32, + -1.9967556000e-06_f32, + 1.2516975403e-06_f32, + 2.1755695343e-06_f32, + 1.9371509552e-06_f32, + 1.3113021851e-06_f32, + 7.4505805969e-07_f32, + 3.5762786865e-07_f32, + 1.1920928955e-07_f32, + 2.9802322388e-08_f32, +]; + +/// The number of filter history bytes (96 taps / 8 bits per byte = 12 bytes). +pub const FILTER_BYTES: usize = 12; + +/// Standard DSD silence pattern byte for LSB-first ordering (Sony DSF). +pub const SILENCE_LSBF: u8 = 0x69; + +/// Standard DSD silence pattern byte for MSB-first ordering (Philips DSDIFF). +pub const SILENCE_MSBF: u8 = 0xAA; + +/// Precomputes lookup table entries for byte position `k` (0..12) and byte value `v` (0..256). +/// +/// In LSB-first order, bit `b` of input byte `k` corresponds to tap `k * 8 + b`. +#[inline] +fn byte_lut(k: usize, byte_val: u8) -> f32 { + let mut sum = 0.0_f32; + let base_tap = k * 8; + for b in 0..8 { + if ((byte_val >> b) & 1) != 0 + && let Some(tap) = TAPS_96.get(base_tap + b) + { + sum += 2.0 * *tap; + } + } + sum +} + +// Both the first-stage samples and the secondary output coexist during filtering. +pub(super) fn allocation_sizes(len: usize, factor: u32) -> Result<(usize, usize), Error> { + if !matches!(factor, 8 | 16 | 32 | 64) { + return Err(Error::Unsupported("decimation factor must be 8, 16, 32, or 64")); + } + let stage = len.checked_mul(std::mem::size_of::()).ok_or(Error::MemoryLimitExceeded)?; + let output = (len / (factor / 8) as usize).checked_mul(std::mem::size_of::()).ok_or(Error::MemoryLimitExceeded)?; + let working = if factor == 8 { stage } else { stage.checked_add(output).ok_or(Error::MemoryLimitExceeded)? }; + if working > MAX_DECODE_BYTES { + return Err(Error::MemoryLimitExceeded); + } + Ok((working, output)) +} + +/// Unity-DC-gain low-pass taps for decimating by `ratio` (cutoff 0.45 / ratio cycles per sample). +fn decimation_taps(ratio: usize) -> Vec { + let n = 24 * ratio + 1; + let mid = (n / 2) as f64; + let fc = 0.45 / ratio as f64; + let mut taps: Vec = (0..n) + .map(|k| { + let x = k as f64 - mid; + let sinc = if x == 0.0 { 2.0 * fc } else { (2.0 * std::f64::consts::PI * fc * x).sin() / (std::f64::consts::PI * x) }; + let t = k as f64 / (n - 1) as f64; + let window = 0.42 - 0.5 * (2.0 * std::f64::consts::PI * t).cos() + 0.08 * (4.0 * std::f64::consts::PI * t).cos(); + sinc * window + }) + .collect(); + let sum: f64 = taps.iter().sum(); + for t in &mut taps { + *t /= sum; + } + taps.into_iter().map(|t| t as f32).collect() +} + +/// Decimates 1-bit DSD audio bytes for a single channel to `f32` PCM. +/// +/// The default decimation factor is 8 (1 output float per input byte). +/// When `factor` is 16, 32, or 64, the 1/8 output is further downsampled +/// by 2, 4, or 8 respectively. +pub fn decimate_channel(channel_bytes: &[u8], bit_order: BitOrder, factor: u32) -> Result, Error> { + allocation_sizes(channel_bytes.len(), factor)?; + let num_bytes = channel_bytes.len(); + + // Build the 12 x 256 lookup table for fast convolution. + // 12 * 256 * 4 bytes = 12 KB, sits comfortably in L1 cache. + let mut lut = [[0.0_f32; 256]; FILTER_BYTES]; + for (k, lut_k) in lut.iter_mut().enumerate() { + for (v, cell) in lut_k.iter_mut().enumerate() { + *cell = byte_lut(k, v as u8); + } + } + + let mut stage1 = Vec::new(); + stage1.try_reserve_exact(num_bytes).map_err(|_| Error::MemoryLimitExceeded)?; + + // History buffer holds the most recent 12 bytes in LSB-first order. + // Pre-filled with silence (0x69). + let mut history = [SILENCE_LSBF; FILTER_BYTES]; + + for &raw_byte in channel_bytes { + let byte = match bit_order { + BitOrder::LsbFirst => raw_byte, + BitOrder::MsbFirst => raw_byte.reverse_bits(), + }; + + // Shift history left by 1 and push current byte to the end. + history.copy_within(1.., 0); + if let Some(last) = history.last_mut() { + *last = byte; + } + + let mut sample = -1.0_f32; + for (k, &hist_byte) in history.iter().enumerate() { + if let Some(lut_k) = lut.get(k) + && let Some(&contrib) = lut_k.get(hist_byte as usize) + { + sample += contrib; + } + } + + stage1.push(sample); + } + + if factor == 8 { + return Ok(stage1); + } + + // Secondary decimation by ratio = factor / 8 (2, 4, or 8). A plain average attenuates the band + // between the new Nyquist rate and the stage-1 rate too little (about -7.6 dB at 29.4 kHz for + // factor 64), so low-pass first: a Blackman-windowed sinc with its cutoff at 90% of the new + // Nyquist frequency, evaluated only at the kept samples. + let ratio = (factor / 8) as usize; + let out_len = stage1.len() / ratio; + let mut out = Vec::new(); + out.try_reserve_exact(out_len).map_err(|_| Error::MemoryLimitExceeded)?; + + let taps = decimation_taps(ratio); + let half = (taps.len() / 2) as isize; + let last = stage1.len() as isize - 1; + for i in 0..out_len { + let center = (i * ratio + ratio / 2) as isize; + let mut acc = 0.0_f32; + for (k, &w) in taps.iter().enumerate() { + let idx = (center + k as isize - half).clamp(0, last); + if let Some(&x) = stage1.get(idx as usize) { + acc += w * x; + } + } + out.push(acc); + } + + Ok(out) +} + +#[cfg(test)] +#[allow(clippy::unwrap_used)] +mod decimation_tests { + use super::*; + + /// A full-scale 29.4 kHz square wave in DSD64 (six bytes of ones, six of zeros) lies between + /// the output Nyquist frequency and the sampling rate of a 44.1 kHz result: it must be + /// attenuated well, not folded down at 0.42 of its amplitude. + #[test] + fn factor_64_attenuates_29_4_khz() { + let mut bytes = Vec::new(); + for _ in 0..2000 { + bytes.extend_from_slice(&[0xFF; 6]); + bytes.extend_from_slice(&[0x00; 6]); + } + let out = decimate_channel(&bytes, BitOrder::MsbFirst, 64).unwrap(); + let mid = &out[out.len() / 4..out.len() * 3 / 4]; + let peak = mid.iter().fold(0.0_f32, |m, v| m.max(v.abs())); + assert!(peak < 0.05, "peak {peak}"); + } + + #[test] + fn decimation_keeps_dc_level() { + let bytes = vec![0xFF; 4096]; + let out = decimate_channel(&bytes, BitOrder::MsbFirst, 64).unwrap(); + let mid = out[out.len() / 2]; + assert!((mid - 1.0).abs() < 0.05, "{mid}"); + } +} diff --git a/crates/audio/src/dsd/mod.rs b/crates/audio/src/dsd/mod.rs new file mode 100644 index 000000000..e782b50f0 --- /dev/null +++ b/crates/audio/src/dsd/mod.rs @@ -0,0 +1,275 @@ +//! Direct Stream Digital (DSD) audio: Sony DSF and Philips DSDIFF (`.dff`) readers and +//! DSD-to-PCM decimation. +//! +//! DSD stores 1-bit Pulse Density Modulation (PDM) sampled at high rates (e.g. 2,822,400 Hz +//! for DSD64, 5,644,800 Hz for DSD128, etc.). +//! +//! This module provides: +//! - File parsers for Sony DSF (`.dsf`) and Philips DSDIFF (`.dff`) containers. +//! - Raw 1-bit audio extraction with preservation of native bit ordering (LSB-first for DSF, +//! MSB-first for DSDIFF). +//! - Clean-room 96-tap symmetric FIR decimation filter converting 1-bit PDM to multi-bit PCM +//! (decimation by 8 to 352,800 Hz for DSD64, or downsampled to 176.4, 88.2, or 44.1 kHz). +//! - Reference encoders for generating synthetic DSF and DSDIFF files. + +pub mod dsdiff; +pub mod dsf; +pub mod filter; + +use crate::AudioBuffer; + +/// Maximum number of audio channels supported (1 to 8). +pub const MAX_CHANNELS: usize = 8; + +/// Minimum allowable DSD sample rate in Hz. +pub const MIN_SAMPLE_RATE: u32 = 44_100; + +/// Maximum allowable DSD sample rate in Hz (e.g. DSD1024 at 45.1584 MHz). +pub const MAX_SAMPLE_RATE: u32 = 45_158_400; + +/// Maximum safe block size for DSF channel blocks (16 MiB). +pub const MAX_BLOCK_SIZE: u32 = 16 * 1024 * 1024; + +/// Maximum audio-buffer allocation budget (256 MiB). +/// +/// Raw readers limit their channel bytes; PCM conversion separately limits the +/// simultaneously live PCM output and scratch buffers. Caller-owned raw input, +/// metadata, and the small filter lookup table are not included. +pub const MAX_DECODE_BYTES: usize = 256 * 1024 * 1024; + +/// Maximum encoded container size, including headers and block padding (256 MiB). +pub const MAX_ENCODE_BYTES: usize = 256 * 1024 * 1024; + +fn encoded_size(payload: usize, header: usize) -> Result { + payload.checked_add(header).filter(|&n| n <= MAX_ENCODE_BYTES).ok_or(Error::MemoryLimitExceeded) +} + +// Account for retained channel output plus the current filter's two live buffers. +fn pcm_budget(lengths: impl Iterator, factor: u32) -> Result<(), Error> { + let mut retained = 0usize; + for len in lengths { + let (working, output) = filter::allocation_sizes(len, factor)?; + if retained.checked_add(working).is_none_or(|n| n > MAX_DECODE_BYTES) { + return Err(Error::MemoryLimitExceeded); + } + retained = retained.checked_add(output).ok_or(Error::MemoryLimitExceeded)?; + } + Ok(()) +} + +/// Supported DSD container formats. +#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] +pub enum Format { + /// Sony DSF (Direct Stream Digital File) format. + Dsf, + /// Philips DSDIFF (Direct Stream Digital Interchange File Format, `.dff`). + Dsdiff, +} + +/// Bit ordering of 1-bit DSD audio samples within bytes. +#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] +pub enum BitOrder { + /// Least-significant bit first (LSB-first, as used in DSF). + /// Bit 0 is the earliest temporal sample; bit 7 is the latest. + LsbFirst, + /// Most-significant bit first (MSB-first, as used in DSDIFF). + /// Bit 7 is the earliest temporal sample; bit 0 is the latest. + MsbFirst, +} + +/// Stream properties and metadata parsed from a DSD container header. +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct Metadata { + /// Container format (DSF or DSDIFF). + pub format: Format, + /// DSD sampling frequency in Hz (e.g. 2,822,400 for DSD64). + pub sample_rate: u32, + /// Number of audio channels (1 to 8). + pub channels: u16, + /// Total number of 1-bit audio samples per channel. + pub sample_count: u64, + /// Channel identification labels (e.g. "SLFT", "SRGT", "Center"). + pub channel_names: Vec, + /// Optional track title if present in container metadata. + pub title: Option, + /// Optional artist name if present in container metadata. + pub artist: Option, +} + +/// Raw 1-bit DSD audio extracted from a file without decimation. +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct RawAudio { + /// Stream metadata from the file header. + pub metadata: Metadata, + /// Bit ordering of the bytes in `channel_bytes`. + pub bit_order: BitOrder, + /// Planar 1-bit audio bytes per channel. + pub channel_bytes: Vec>, +} + +impl RawAudio { + /// Converts all channel byte streams to the requested bit ordering in place. + pub fn convert_bit_order(&mut self, target: BitOrder) { + if self.bit_order == target { + return; + } + for ch in &mut self.channel_bytes { + for b in ch.iter_mut() { + *b = b.reverse_bits(); + } + } + self.bit_order = target; + } + + /// Decimates the raw 1-bit DSD audio to multi-bit PCM `f32` samples. + /// + /// The default decimation factor is 8 (e.g. 352,800 Hz for DSD64). + pub fn to_pcm(&self) -> Result { + self.to_pcm_with_factor(8) + } + + /// Decimates the raw 1-bit DSD audio to multi-bit PCM `f32` samples with the given factor (8, 16, 32, or 64). + pub fn to_pcm_with_factor(&self, factor: u32) -> Result { + // Validate before iterating: public RawAudio may contain no channels. + if !matches!(factor, 8 | 16 | 32 | 64) { + return Err(Error::Unsupported("decimation factor must be 8, 16, 32, or 64")); + } + if self.channel_bytes.len() > MAX_CHANNELS { + return Err(Error::Unsupported("channel count must be between 1 and 8")); + } + pcm_budget(self.channel_bytes.iter().map(Vec::len), factor)?; + let mut channels = Vec::with_capacity(self.channel_bytes.len()); + for ch_bytes in &self.channel_bytes { + let pcm = filter::decimate_channel(ch_bytes, self.bit_order, factor)?; + channels.push(pcm); + } + let sample_rate = self.metadata.sample_rate / factor; + Ok(DecodedAudio { metadata: self.metadata.clone(), sample_rate, channels }) + } +} + +/// Decoded multi-bit PCM audio produced by DSD-to-PCM decimation. +#[derive(Debug, Clone, PartialEq)] +pub struct DecodedAudio { + /// Stream metadata from the DSD file header. + pub metadata: Metadata, + /// PCM sample rate in Hz (e.g. 352,800 Hz for DSD64 decimated by 8). + pub sample_rate: u32, + /// Planar normalized PCM samples in `[-1.0, 1.0]`, one `Vec` per channel. + pub channels: Vec>, +} + +impl DecodedAudio { + /// Converts the decoded PCM audio into an [`AudioBuffer`]. + pub fn to_audio_buffer(&self) -> AudioBuffer { + AudioBuffer { sample_rate: self.sample_rate, channels: self.channels.clone() } + } +} + +/// Errors returned when parsing or decoding DSD audio. +#[non_exhaustive] +#[derive(Debug, thiserror::Error, PartialEq, Eq)] +pub enum Error { + /// Input data ended prematurely while parsing a header or chunk. + #[error("unexpected end of file: {0}")] + UnexpectedEof(&'static str), + /// Invalid magic bytes or malformed chunk header. + #[error("invalid DSD header or chunk: {0}")] + InvalidHeader(&'static str), + /// An unsupported feature, compression, or channel configuration. + #[error("unsupported DSD feature: {0}")] + Unsupported(&'static str), + /// Audio data length or structure does not match the header specification. + #[error("invalid audio data: {0}")] + InvalidData(&'static str), + /// Header or data requested exceeds maximum safe allocation budget. + #[error("memory budget exceeded")] + MemoryLimitExceeded, +} + +/// Inspects the magic bytes of `bytes` and detects whether it is a DSF or DSDIFF file. +pub fn probe_format(bytes: &[u8]) -> Result { + if bytes.len() < 4 { + return Err(Error::UnexpectedEof("input is too short to determine DSD format")); + } + if &bytes[0..4] == b"DSD " { + Ok(Format::Dsf) + } else if bytes.len() >= 16 && &bytes[0..4] == b"FRM8" && &bytes[12..16] == b"DSD " { + Ok(Format::Dsdiff) + } else { + Err(Error::InvalidHeader("unknown or unsupported DSD container format")) + } +} + +/// Parses the metadata from a DSF or DSDIFF file without decoding audio samples. +pub fn read_metadata(bytes: &[u8]) -> Result { + match probe_format(bytes)? { + Format::Dsf => { + let (meta, _, _) = dsf::parse_dsf_header(bytes)?; + Ok(meta) + } + Format::Dsdiff => { + let (meta, _, _) = dsdiff::parse_dsdiff_header(bytes)?; + Ok(meta) + } + } +} + +/// Reads raw 1-bit planar audio streams from a DSF or DSDIFF file without decimation. +pub fn read_raw(bytes: &[u8]) -> Result { + match probe_format(bytes)? { + Format::Dsf => dsf::parse_dsf(bytes), + Format::Dsdiff => dsdiff::parse_dsdiff(bytes), + } +} + +/// Decodes a DSF or DSDIFF file to multi-bit planar `f32` PCM audio using decimation by 8. +/// +/// For DSD64 (2,822,400 Hz), the output sample rate is 352,800 Hz. +pub fn decode(bytes: &[u8]) -> Result { + decode_with_factor(bytes, 8) +} + +/// Decodes a DSF or DSDIFF file to multi-bit planar `f32` PCM audio with the specified decimation factor. +/// +/// Supported decimation factors are: +/// - 8: 1/8th of DSD rate (e.g. 352,800 Hz for DSD64). +/// - 16: 1/16th of DSD rate (e.g. 176,400 Hz for DSD64). +/// - 32: 1/32th of DSD rate (e.g. 88,200 Hz for DSD64). +/// - 64: 1/64th of DSD rate (e.g. 44,100 Hz for DSD64). +pub fn decode_with_factor(bytes: &[u8], factor: u32) -> Result { + let raw = read_raw(bytes)?; + raw.to_pcm_with_factor(factor) +} + +/// Encodes planar 1-bit audio channels into a Sony DSF file. +pub fn encode_dsf(sample_rate: u32, channels: &[&[u8]], sample_count: u64, block_size: u32) -> Result, Error> { + dsf::write_dsf(sample_rate, channels, sample_count, block_size) +} + +/// Encodes planar 1-bit audio channels into a Philips DSDIFF file. +pub fn encode_dsdiff(sample_rate: u32, channels: &[&[u8]], sample_count: u64) -> Result, Error> { + dsdiff::write_dsdiff(sample_rate, channels, sample_count) +} + +#[cfg(test)] +mod budget_tests { + use super::*; + + #[test] + fn pcm_budget_counts_all_channels_and_live_scratch() { + let quarter = MAX_DECODE_BYTES / 4; + assert!(pcm_budget([quarter / 2, quarter / 2].into_iter(), 8).is_ok()); + assert_eq!(pcm_budget([quarter / 2, quarter / 2 + 1].into_iter(), 8), Err(Error::MemoryLimitExceeded)); + assert!(pcm_budget([quarter / 2].into_iter(), 16).is_ok()); + assert_eq!(pcm_budget([quarter].into_iter(), 16), Err(Error::MemoryLimitExceeded)); + assert_eq!(pcm_budget([usize::MAX].into_iter(), 8), Err(Error::MemoryLimitExceeded)); + } + + #[test] + fn encoded_budget_includes_headers_without_large_allocations() { + assert_eq!(encoded_size(MAX_ENCODE_BYTES - 92, 92), Ok(MAX_ENCODE_BYTES)); + assert_eq!(encoded_size(MAX_ENCODE_BYTES - 91, 92), Err(Error::MemoryLimitExceeded)); + assert_eq!(encoded_size(usize::MAX, 92), Err(Error::MemoryLimitExceeded)); + } +} diff --git a/crates/audio/src/g722.rs b/crates/audio/src/g722.rs new file mode 100644 index 000000000..030b87d14 --- /dev/null +++ b/crates/audio/src/g722.rs @@ -0,0 +1,693 @@ +//! ITU-T Recommendation G.722 wideband audio coding (64 kbit/s). +//! +//! Pure safe Rust clean-room implementation of the G.722 sub-band adaptive differential +//! pulse code modulation (SB-ADPCM) speech and audio codec. +//! +//! Input audio is 16 kHz 16-bit linear PCM. An analysis Quadrature Mirror Filter (QMF) splits +//! the 16 kHz audio into a lower sub-band (0–4 kHz) and a higher sub-band (4–8 kHz), each +//! sampled at 8 kHz. The lower sub-band is encoded at 48 kbit/s (6 bits/sample) and the higher +//! sub-band at 16 kbit/s (2 bits/sample), multiplexed into an 8-bit octet per 8 kHz cycle +//! (64 kbit/s total stream rate). +//! +//! On decoding, inverse adaptive quantizers reconstruct each sub-band signal, and a synthesis +//! QMF interpolates and combines them back to 16 kHz 16-bit linear PCM. + +#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)] + +/// Maximum allowed channels for multi-channel processing. +pub const MAX_CHANNELS: usize = 8; + +/// Maximum input byte buffer bound to prevent memory exhaustion on hostile inputs (64 MiB). +pub const MAX_INPUT_BYTES: usize = 64 * 1024 * 1024; + +/// Maximum input sample count bound (128 million samples). +pub const MAX_SAMPLES: usize = 128 * 1024 * 1024; + +/// Error conditions encountered during G.722 encoding or decoding. +#[derive(Debug, thiserror::Error, PartialEq, Eq)] +pub enum Error { + /// The channel count is invalid. + #[error("invalid channel count: {0} (must be 1..={MAX_CHANNELS})")] + InvalidChannels(usize), + + /// The input size exceeds safety bounds. + #[error("input exceeds maximum size bound")] + InputTooLarge, + + /// Encoding requires an even number of samples per channel (16 kHz sample pairs). + #[error("odd number of samples: {0} (G.722 encodes pairs of 16 kHz samples)")] + OddSampleCount(usize), + + /// System allocation failed when reserving buffer memory. + #[error("allocation failed")] + AllocationFailed, +} + +// --------------------------------------------------------------------------- +// Specification Tables from ITU-T Recommendation G.722 +// --------------------------------------------------------------------------- + +/// 24-tap QMF filter coefficients scaled by 2^13 (Table 11/G.722). +const H: [i16; 24] = [3, -11, -11, 53, 12, -156, 32, 362, -210, -805, 951, 3876, 3876, 951, -805, -210, 362, 32, -156, 12, 53, -11, -11, 3]; + +/// Lower sub-band 60-level inverse quantizer reconstruction table QQ6 (Table 14/G.722). +const QQ6: [i16; 31] = [ + 0, 17, 54, 91, 130, 170, 211, 254, 300, 347, 396, 447, 501, 558, 618, 682, 750, 822, 899, 982, 1072, 1170, 1279, 1399, 1535, 1689, 1873, 2088, + 2376, 2738, 3101, +]; + +/// Lower sub-band quantizer decision levels Q6 (Table 14/G.722). +const Q6: [i16; 30] = [ + 0, 35, 72, 110, 150, 190, 233, 276, 323, 370, 422, 473, 530, 587, 650, 714, 786, 858, 940, 1023, 1121, 1219, 1339, 1458, 1612, 1765, 1980, 2195, + 2557, 2919, +]; + +/// Lower sub-band 15-level inverse quantizer reconstruction table QQ4 (Table 14/G.722). +const QQ4: [i16; 8] = [0, 150, 323, 530, 786, 1121, 1612, 2557]; + +/// Lower sub-band logarithmic scale factor multipliers WL (Table 14/G.722). +const WL: [i16; 8] = [-60, -30, 58, 172, 334, 538, 1198, 3042]; + +/// Higher sub-band 4-level inverse quantizer reconstruction table QQ2 (Table 14/G.722). +const QQ2: [i16; 3] = [0, 202, 926]; + +/// Higher sub-band logarithmic scale factor multipliers WH (Table 14/G.722). +const WH: [i16; 3] = [0, -214, 798]; + +/// 32-entry inverse logarithmic scale table ILB (Table 15/G.722). +const ILB: [i32; 32] = [ + 2048, 2093, 2139, 2186, 2233, 2282, 2332, 2383, 2435, 2489, 2543, 2599, 2656, 2714, 2774, 2834, 2896, 2960, 3025, 3091, 3158, 3228, 3298, 3371, + 3444, 3520, 3597, 3676, 3756, 3838, 3922, 4008, +]; + +/// Table 17/G.722: 4-bit codeword (RIL = IL >> 2) to (SIL, IL4). +const IL4_MAP: [(i16, usize); 16] = + [(0, 0), (-1, 7), (-1, 6), (-1, 5), (-1, 4), (-1, 3), (-1, 2), (-1, 1), (0, 7), (0, 6), (0, 5), (0, 4), (0, 3), (0, 2), (0, 1), (0, 0)]; + +/// Table 21/G.722: 2-bit codeword IH to (SIH, IH2). +const IH2_MAP: [(i16, usize); 4] = [(-1, 2), (-1, 1), (0, 2), (0, 1)]; + +#[inline] +fn mult(a: i16, b: i16) -> i16 { + (((a as i32) * (b as i32)) >> 15) as i16 +} + +#[inline] +fn scalel(nbpl: i32) -> i32 { + let wd1 = ((nbpl >> 6) & 31) as usize; + let wd2 = nbpl >> 11; + let shift = 8 - wd2; + let wd3 = if shift >= 0 { ILB[wd1] >> shift } else { ILB[wd1] << (-shift) }; + wd3 << 2 +} + +#[inline] +fn scaleh(nbph: i32) -> i32 { + let wd1 = ((nbph >> 6) & 31) as usize; + let wd2 = nbph >> 11; + let shift = 10 - wd2; + let wd3 = if shift >= 0 { ILB[wd1] >> shift } else { ILB[wd1] << (-shift) }; + wd3 << 2 +} + +// --------------------------------------------------------------------------- +// Sub-band ADPCM State (Pole/Zero Predictors & Adaptations) +// --------------------------------------------------------------------------- + +#[derive(Debug, Clone)] +struct BandState { + s: i16, + sp: i16, + sz: i16, + d: [i16; 7], + r: [i16; 3], + p: [i16; 3], + a: [i16; 3], + b: [i16; 7], + nb: i32, + det: i32, +} + +impl BandState { + fn new(is_lower: bool) -> Self { + Self { s: 0, sp: 0, sz: 0, d: [0; 7], r: [0; 3], p: [0; 3], a: [0; 3], b: [0; 7], nb: 0, det: if is_lower { 32 } else { 8 } } + } + + fn reset(&mut self, is_lower: bool) { + self.s = 0; + self.sp = 0; + self.sz = 0; + self.d = [0; 7]; + self.r = [0; 3]; + self.p = [0; 3]; + self.a = [0; 3]; + self.b = [0; 7]; + self.nb = 0; + self.det = if is_lower { 32 } else { 8 }; + } + + fn update_predictor(&mut self, d: i16, p_sig: i16, r_sig: i16) { + // UPZERO: update 6th order zero predictor coefficients + let wd1: i16 = if d != 0 { 128 } else { 0 }; + let sg0: i16 = if d < 0 { -1 } else { 0 }; + for i in 1..=6 { + let sgi = if self.d[i] < 0 { -1 } else { 0 }; + let wd2 = if sg0 == sgi { wd1 } else { wd1.saturating_neg() }; + let wd3 = mult(self.b[i], 32640); + self.b[i] = wd2.saturating_add(wd3); + } + + // UPPOL2: update 2nd pole coefficient + let sg0 = if p_sig < 0 { -1 } else { 0 }; + let sg1 = if self.p[1] < 0 { -1 } else { 0 }; + let sg2 = if self.p[2] < 0 { -1 } else { 0 }; + let wd1 = self.a[1].saturating_add(self.a[1]).saturating_add(self.a[1].saturating_add(self.a[1])); + let wd2 = if sg0 == sg1 { wd1.saturating_neg() } else { wd1 } >> 7; + let wd3: i16 = if sg0 == sg2 { 128 } else { -128 }; + let wd4 = wd2.saturating_add(wd3); + let wd5 = mult(self.a[2], 32512); + let apl2 = wd4.saturating_add(wd5).clamp(-12288, 12288); + + // UPPOL1: update 1st pole coefficient + let wd1: i16 = if sg0 == sg1 { 192 } else { -192 }; + let wd2 = mult(self.a[1], 32640); + let apl1 = wd1.saturating_add(wd2); + let wd3 = 15360 - apl2; + let apl1 = apl1.clamp(-wd3, wd3); + + self.a[1] = apl1; + self.a[2] = apl2; + + // Shift history delay lines + for i in (2..=6).rev() { + self.d[i] = self.d[i - 1]; + } + self.d[1] = d; + + self.p[2] = self.p[1]; + self.p[1] = p_sig; + + self.r[2] = self.r[1]; + self.r[1] = r_sig; + + // FILTEZ: compute zero section output + let mut sz: i16 = 0; + for i in (1..=6).rev() { + let part = mult(self.b[i], self.d[i].saturating_add(self.d[i])); + sz = sz.saturating_add(part); + } + self.sz = sz; + + // FILTEP: compute pole section output + let sp1 = mult(self.a[1], self.r[1].saturating_add(self.r[1])); + let sp2 = mult(self.a[2], self.r[2].saturating_add(self.r[2])); + self.sp = sp1.saturating_add(sp2); + + // PREDIC: compute full predictor output value + self.s = self.sp.saturating_add(self.sz); + } +} + +// --------------------------------------------------------------------------- +// Quadrature Mirror Filters (QMF) +// --------------------------------------------------------------------------- + +/// Analysis QMF (transmit filter bank): splits pairs of 16 kHz samples into lower and higher sub-bands. +#[derive(Debug, Clone, Default)] +pub struct QmfTx { + x: [i16; 24], +} + +impl QmfTx { + /// Create a new analysis QMF filter. + pub fn new() -> Self { + Self { x: [0; 24] } + } + + /// Reset filter history. + pub fn reset(&mut self) { + self.x = [0; 24]; + } + + /// Process a pair of 16 kHz input samples `(s0, s1)` into `(xl, xh)`. + pub fn filter(&mut self, s0: i16, s1: i16) -> (i16, i16) { + for i in (2..24).rev() { + self.x[i] = self.x[i - 2]; + } + self.x[0] = s1 >> 1; + self.x[1] = s0 >> 1; + + let mut xa: i32 = 0; + let mut xb: i32 = 0; + for i in 0..12 { + xa = xa.saturating_add((self.x[2 * i] as i32) * (H[2 * i] as i32)); + xb = xb.saturating_add((self.x[2 * i + 1] as i32) * (H[2 * i + 1] as i32)); + } + + let xl = ((xa.saturating_add(xb)) >> 13).clamp(-16384, 16383) as i16; + let xh = ((xa.saturating_sub(xb)) >> 13).clamp(-16384, 16383) as i16; + (xl, xh) + } +} + +/// Synthesis QMF (receive filter bank): synthesizes lower and higher sub-band signals into 16 kHz output. +#[derive(Debug, Clone, Default)] +pub struct QmfRx { + xd: [i16; 12], + xs: [i16; 12], +} + +impl QmfRx { + /// Create a new synthesis QMF filter. + pub fn new() -> Self { + Self { xd: [0; 12], xs: [0; 12] } + } + + /// Reset filter history. + pub fn reset(&mut self) { + self.xd = [0; 12]; + self.xs = [0; 12]; + } + + /// Reconstruct a pair of 16 kHz output samples from sub-band samples `(rl, rh)`. + pub fn filter(&mut self, rl: i16, rh: i16) -> (i16, i16) { + let xd_curr = rl.saturating_sub(rh); + let xs_curr = rl.saturating_add(rh); + + for i in (1..12).rev() { + self.xd[i] = self.xd[i - 1]; + self.xs[i] = self.xs[i - 1]; + } + self.xd[0] = xd_curr; + self.xs[0] = xs_curr; + + let mut wd_c: i32 = 0; + let mut wd_d: i32 = 0; + for i in 0..12 { + wd_c = wd_c.saturating_add((self.xd[i] as i32) * (H[2 * i] as i32)); + wd_d = wd_d.saturating_add((self.xs[i] as i32) * (H[2 * i + 1] as i32)); + } + + let xout1 = (wd_c >> 12).clamp(-16384, 16383); + let xout2 = (wd_d >> 12).clamp(-16384, 16383); + + let s0 = (xout1 << 1).clamp(-32768, 32767) as i16; + let s1 = (xout2 << 1).clamp(-32768, 32767) as i16; + (s0, s1) + } +} + +// --------------------------------------------------------------------------- +// G.722 Decoder & Encoder +// --------------------------------------------------------------------------- + +/// ITU-T G.722 64 kbit/s single-channel decoder. +#[derive(Debug, Clone)] +pub struct Decoder { + band_l: BandState, + band_h: BandState, + qmf: QmfRx, +} + +impl Default for Decoder { + fn default() -> Self { + Self::new() + } +} + +impl Decoder { + /// Create a new G.722 decoder initialized to standard reset state. + pub fn new() -> Self { + Self { band_l: BandState::new(true), band_h: BandState::new(false), qmf: QmfRx::new() } + } + + /// Reset decoder internal state. + pub fn reset(&mut self) { + self.band_l.reset(true); + self.band_h.reset(false); + self.qmf.reset(); + } + + /// Decode a single 8-bit octet into two 16 kHz 16-bit PCM samples. + pub fn decode_octet(&mut self, octet: u8) -> (i16, i16) { + let ih = ((octet >> 6) & 3) as usize; + let il = (octet & 0x3F) as usize; + + // INVQBL: 6-bit lower sub-band inverse quantization + let (sil6, il6) = table18_lookup(il); + let wd1 = (QQ6[il6] as i32) << 3; + let wd2 = if sil6 == 0 { wd1 } else { -wd1 }; + let dl = mult(self.band_l.det as i16, wd2 as i16); + let yl = self.band_l.s.saturating_add(dl); + let rl = yl.clamp(-16384, 16383); + + // INVQAL: lower sub-band predictor update (4-bit feedback path) + let ril = il >> 2; + let (sil4, il4) = IL4_MAP[ril & 0x0F]; + let wd1 = (QQ4[il4] as i32) << 3; + let wd2 = if sil4 == 0 { wd1 } else { -wd1 }; + let dlt = mult(self.band_l.det as i16, wd2 as i16); + let plt = dlt.saturating_add(self.band_l.sz); + let rlt = self.band_l.s.saturating_add(dlt); + + // Lower sub-band scale factor adaptation (LOGSCL) + let wd_scale = mult(self.band_l.nb as i16, 32512); + let nbpl = (wd_scale as i32 + WL[il4] as i32).clamp(0, 18432); + self.band_l.nb = nbpl; + self.band_l.det = scalel(nbpl); + self.band_l.update_predictor(dlt, plt, rlt); + + // INVQAH: higher sub-band inverse quantization + let (sih_dec, ih2) = IH2_MAP[ih & 0x03]; + let wd1 = (QQ2[ih2] as i32) << 3; + let wd2 = if sih_dec == 0 { wd1 } else { -wd1 }; + let dh = mult(self.band_h.det as i16, wd2 as i16); + let yh = self.band_h.s.saturating_add(dh); + let rh = yh.clamp(-16384, 16383); + + // Higher sub-band scale factor adaptation (LOGSCH) + let wd_scale = mult(self.band_h.nb as i16, 32512); + let nbph = (wd_scale as i32 + WH[ih2] as i32).clamp(0, 22528); + self.band_h.nb = nbph; + self.band_h.det = scaleh(nbph); + let ph = dh.saturating_add(self.band_h.sz); + self.band_h.update_predictor(dh, ph, yh); + + // Synthesis QMF + self.qmf.filter(rl, rh) + } + + /// Decode G.722 octets into 16 kHz 16-bit linear PCM samples, appending to `dst`. + pub fn decode(&mut self, src: &[u8], dst: &mut Vec) -> Result<(), Error> { + if src.len() > MAX_INPUT_BYTES { + return Err(Error::InputTooLarge); + } + let needed_samples = src.len().saturating_mul(2); + if needed_samples > MAX_SAMPLES { + return Err(Error::InputTooLarge); + } + dst.try_reserve(needed_samples).map_err(|_| Error::AllocationFailed)?; + for &octet in src { + let (s0, s1) = self.decode_octet(octet); + dst.push(s0); + dst.push(s1); + } + Ok(()) + } +} + +/// ITU-T G.722 64 kbit/s single-channel encoder. +#[derive(Debug, Clone)] +pub struct Encoder { + qmf: QmfTx, + band_l: BandState, + band_h: BandState, +} + +impl Default for Encoder { + fn default() -> Self { + Self::new() + } +} + +impl Encoder { + /// Create a new G.722 encoder initialized to standard reset state. + pub fn new() -> Self { + Self { qmf: QmfTx::new(), band_l: BandState::new(true), band_h: BandState::new(false) } + } + + /// Reset encoder internal state. + pub fn reset(&mut self) { + self.qmf.reset(); + self.band_l.reset(true); + self.band_h.reset(false); + } + + /// Encode a pair of 16 kHz 16-bit PCM samples into one 8-bit G.722 octet. + pub fn encode_sample_pair(&mut self, s0: i16, s1: i16) -> u8 { + // Analysis QMF + let (xl, xh) = self.qmf.filter(s0, s1); + + // Lower sub-band quantizer (QUANTL) + let el = xl.saturating_sub(self.band_l.s); + let sil = if el < 0 { -1 } else { 0 }; + let wd = if sil == 0 { el } else { 32767 - (el & 32767) }; + let mut mil: usize = 30; + for (k, &thresh_q) in Q6.iter().enumerate().skip(1) { + let thresh = (((thresh_q as i32) << 3) * self.band_l.det) >> 15; + if (wd as i32) < thresh { + mil = k; + break; + } + } + + // Table 16 conversion to IL + let il: u8 = if sil == 0 { + (62 - mil) as u8 + } else if mil == 1 { + 63 + } else if mil == 2 { + 62 + } else { + (34 - mil) as u8 + }; + + // Lower sub-band feedback and predictor update (INVQAL) + let ril = (il >> 2) as usize; + let (sil4, il4) = IL4_MAP[ril & 0x0F]; + let wd1 = (QQ4[il4] as i32) << 3; + let wd2 = if sil4 == 0 { wd1 } else { -wd1 }; + let dlt = mult(self.band_l.det as i16, wd2 as i16); + let plt = dlt.saturating_add(self.band_l.sz); + let rlt = self.band_l.s.saturating_add(dlt); + + // Lower sub-band scale factor adaptation (LOGSCL) + let wd_scale = mult(self.band_l.nb as i16, 32512); + let nbpl = (wd_scale as i32 + WL[il4] as i32).clamp(0, 18432); + self.band_l.nb = nbpl; + self.band_l.det = scalel(nbpl); + self.band_l.update_predictor(dlt, plt, rlt); + + // Higher sub-band quantizer (QUANTH) + let eh = xh.saturating_sub(self.band_h.s); + let sih = if eh < 0 { -1 } else { 0 }; + let wd = if sih == 0 { eh } else { 32767 - (eh & 32767) }; + let thresh = ((564 << 3) * self.band_h.det) >> 15; + let mih = if (wd as i32) < thresh { 1 } else { 2 }; + + // Table 20 conversion to IH + let ih: u8 = if sih == -1 { + if mih == 2 { 0 } else { 1 } + } else if mih == 1 { + 3 + } else { + 2 + }; + + // Higher sub-band feedback and predictor update (INVQAH) + let (sih_dec, ih2) = IH2_MAP[ih as usize]; + let wd1 = (QQ2[ih2] as i32) << 3; + let wd2 = if sih_dec == 0 { wd1 } else { -wd1 }; + let dh = mult(self.band_h.det as i16, wd2 as i16); + let yh = self.band_h.s.saturating_add(dh); + + // Higher sub-band scale factor adaptation (LOGSCH) + let wd_scale = mult(self.band_h.nb as i16, 32512); + let nbph = (wd_scale as i32 + WH[ih2] as i32).clamp(0, 22528); + self.band_h.nb = nbph; + self.band_h.det = scaleh(nbph); + let ph = dh.saturating_add(self.band_h.sz); + self.band_h.update_predictor(dh, ph, yh); + + // Multiplexer (MUX) + (ih << 6) | (il & 0x3F) + } + + /// Encode 16 kHz 16-bit linear PCM samples into G.722 octets, appending to `dst`. + pub fn encode(&mut self, src: &[i16], dst: &mut Vec) -> Result<(), Error> { + if !src.len().is_multiple_of(2) { + return Err(Error::OddSampleCount(src.len())); + } + if src.len() > MAX_SAMPLES { + return Err(Error::InputTooLarge); + } + let needed_octets = src.len() / 2; + dst.try_reserve(needed_octets).map_err(|_| Error::AllocationFailed)?; + for &[s0, s1] in src.as_chunks::<2>().0 { + let octet = self.encode_sample_pair(s0, s1); + dst.push(octet); + } + Ok(()) + } +} + +// --------------------------------------------------------------------------- +// Helpers +// --------------------------------------------------------------------------- + +#[inline] +fn table18_lookup(il: usize) -> (i16, usize) { + let il = il & 0x3F; + if (4..=31).contains(&il) { + (-1, 34 - il) + } else if il == 62 { + (-1, 2) + } else if il == 63 { + (-1, 1) + } else if (32..=61).contains(&il) { + (0, 62 - il) + } else { + // Transmission error fallbacks (0..=3) + (-1, 1) + } +} + +// --------------------------------------------------------------------------- +// Public Top-Level Functions +// --------------------------------------------------------------------------- + +/// Decode a mono 64 kbit/s G.722 stream into 16 kHz 16-bit linear PCM samples. +pub fn decode(bytes: &[u8]) -> Result, Error> { + let mut decoder = Decoder::new(); + let mut out = Vec::new(); + decoder.decode(bytes, &mut out)?; + Ok(out) +} + +/// Encode mono 16 kHz 16-bit linear PCM samples into a 64 kbit/s G.722 stream. +pub fn encode(samples: &[i16]) -> Result, Error> { + let mut encoder = Encoder::new(); + let mut out = Vec::new(); + encoder.encode(samples, &mut out)?; + Ok(out) +} + +/// Decode an interleaved multi-channel G.722 stream into interleaved 16 kHz 16-bit PCM samples. +pub fn decode_interleaved(bytes: &[u8], channels: usize) -> Result, Error> { + if channels == 0 || channels > MAX_CHANNELS { + return Err(Error::InvalidChannels(channels)); + } + if channels == 1 { + return decode(bytes); + } + if bytes.len() > MAX_INPUT_BYTES { + return Err(Error::InputTooLarge); + } + let frames = bytes.len() / channels; + let mut decoders: Vec = Vec::with_capacity(channels); + for _ in 0..channels { + decoders.push(Decoder::new()); + } + let total_samples = frames.saturating_mul(channels).saturating_mul(2); + let mut out = Vec::new(); + out.try_reserve(total_samples).map_err(|_| Error::AllocationFailed)?; + + // Each frame has `channels` bytes. Decode each byte with its channel's decoder, + // producing sample 0 for each channel, then sample 1 for each channel. + for chunk in bytes.chunks_exact(channels) { + let mut pairs = [(0i16, 0i16); MAX_CHANNELS]; + for (ch, &b) in chunk.iter().enumerate() { + pairs[ch] = decoders[ch].decode_octet(b); + } + for pair in pairs.iter().take(channels) { + out.push(pair.0); + } + for pair in pairs.iter().take(channels) { + out.push(pair.1); + } + } + Ok(out) +} + +/// Encode interleaved 16 kHz 16-bit PCM samples into an interleaved multi-channel G.722 stream. +pub fn encode_interleaved(samples: &[i16], channels: usize) -> Result, Error> { + if channels == 0 || channels > MAX_CHANNELS { + return Err(Error::InvalidChannels(channels)); + } + if channels == 1 { + return encode(samples); + } + if samples.len() > MAX_SAMPLES { + return Err(Error::InputTooLarge); + } + let frame_len = channels.saturating_mul(2); + if !samples.len().is_multiple_of(frame_len) { + return Err(Error::OddSampleCount(samples.len())); + } + let frames = samples.len() / frame_len; + let mut encoders: Vec = Vec::with_capacity(channels); + for _ in 0..channels { + encoders.push(Encoder::new()); + } + let total_bytes = frames.saturating_mul(channels); + let mut out = Vec::new(); + out.try_reserve(total_bytes).map_err(|_| Error::AllocationFailed)?; + + for chunk in samples.chunks_exact(frame_len) { + for ch in 0..channels { + let s0 = chunk[ch]; + let s1 = chunk[ch + channels]; + out.push(encoders[ch].encode_sample_pair(s0, s1)); + } + } + Ok(out) +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn reject_invalid_channels() { + assert_eq!(decode_interleaved(&[0; 4], 0), Err(Error::InvalidChannels(0))); + assert_eq!(decode_interleaved(&[0; 4], 9), Err(Error::InvalidChannels(9))); + assert_eq!(encode_interleaved(&[0; 4], 0), Err(Error::InvalidChannels(0))); + assert_eq!(encode_interleaved(&[0; 4], 9), Err(Error::InvalidChannels(9))); + } + + #[test] + fn reject_odd_sample_count() { + assert_eq!(encode(&[0; 3]), Err(Error::OddSampleCount(3))); + assert_eq!(encode_interleaved(&[0; 5], 2), Err(Error::OddSampleCount(5))); + } + + #[test] + fn roundtrip_silence() { + let input = vec![0i16; 320]; + let encoded = encode(&input).expect("encode silence"); + assert_eq!(encoded.len(), 160); + let decoded = decode(&encoded).expect("decode silence"); + assert_eq!(decoded.len(), 320); + for &s in &decoded[40..] { + assert!(s.abs() <= 6, "silence sample too large: {s}"); + } + } + + #[test] + fn multichannel_stereo_roundtrip() { + let mut stereo_pcm = Vec::new(); + for i in 0..400 { + stereo_pcm.push((i * 10) as i16); + stereo_pcm.push((-i * 10) as i16); + } + let enc = encode_interleaved(&stereo_pcm, 2).expect("encode stereo"); + assert_eq!(enc.len(), 400); + let dec = decode_interleaved(&enc, 2).expect("decode stereo"); + assert_eq!(dec.len(), 800); + } + + #[test] + fn hostile_input_does_not_panic() { + let garbage = [0xFF, 0x00, 0x55, 0xAA, 0x12, 0x34, 0x7F, 0x80]; + let dec = decode(&garbage).expect("decode garbage"); + assert_eq!(dec.len(), 16); + } + + #[test] + fn uppol2_overflow_does_not_panic() { + let mut state = BandState::new(true); + state.a[1] = -8192; + state.p = [0, 0, 0]; + state.update_predictor(0, 0, 0); + } +} diff --git a/crates/audio/src/g726.rs b/crates/audio/src/g726.rs new file mode 100644 index 000000000..6ac02359d --- /dev/null +++ b/crates/audio/src/g726.rs @@ -0,0 +1,996 @@ +//! ITU-T Recommendation G.726 ADPCM speech codec (16, 24, 32, 40 kbit/s). +//! +//! Clean-room implementation based on ITU-T Recommendation G.726 (12/1990) +//! "40, 32, 24, 16 kbit/s Adaptive Differential Pulse Code Modulation (ADPCM)". +//! +//! Provides encoding from 8 kHz 16-bit linear PCM to G.726 bitstreams, and decoding +//! from G.726 bitstreams to 8 kHz 16-bit linear PCM. +//! +//! Supports both standard big-endian bit packing (network order / RFC 3551) and +//! little-endian bit packing (RIFF WAV / AVID format tag 0x0045 / 0x0014). + +const MAX_CHANNELS: usize = 8; +const MAX_INPUT_BYTES: usize = 64 * 1024 * 1024; +const MAX_SAMPLES: usize = 64 * 1024 * 1024; + +/// Bit rate for G.726 ADPCM. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum BitRate { + /// 16 kbit/s (2 bits per sample). + Rate16k, + /// 24 kbit/s (3 bits per sample). + Rate24k, + /// 32 kbit/s (4 bits per sample). + Rate32k, + /// 40 kbit/s (5 bits per sample). + Rate40k, +} + +impl BitRate { + /// Number of bits per code (sample). + #[inline] + #[must_use] + pub const fn code_size(self) -> usize { + match self { + Self::Rate16k => 2, + Self::Rate24k => 3, + Self::Rate32k => 4, + Self::Rate40k => 5, + } + } + + /// Bit rate in bits per second. + #[inline] + #[must_use] + pub const fn bit_rate_bps(self) -> u32 { + match self { + Self::Rate16k => 16_000, + Self::Rate24k => 24_000, + Self::Rate32k => 32_000, + Self::Rate40k => 40_000, + } + } +} + +/// Bit packing order within bytes. +#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)] +pub enum BitPacking { + /// Big-endian packing: MSB to LSB (standard RFC 3551 / network order). + #[default] + BigEndian, + /// Little-endian packing: LSB to MSB (WAV / RIFF order). + LittleEndian, +} + +/// Errors returned by G.726 operations. +#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)] +pub enum Error { + /// Channel count must be between 1 and 8. + #[error("unsupported channel count: {0} (must be 1..=8)")] + InvalidChannels(usize), + /// Input exceeds safe maximum memory bound. + #[error("input exceeds safe maximum processing limit")] + InputTooLarge, + /// Output buffer allocation failed. + #[error("memory allocation failed")] + AllocationFailed, +} + +// --------------------------------------------------------------------------- +// G.726 Tables +// --------------------------------------------------------------------------- + +// Table 11..14 (I -> DQS, DQLN) +static OUT_16: [(u8, u16); 4] = [(0, 116), (0, 365), (1, 365), (1, 116)]; + +static OUT_24: [(u8, u16); 8] = [(0, 2048), (0, 135), (0, 273), (0, 373), (1, 373), (1, 273), (1, 135), (1, 2048)]; + +static OUT_32: [(u8, u16); 16] = [ + (0, 2048), + (0, 4), + (0, 135), + (0, 213), + (0, 273), + (0, 323), + (0, 373), + (0, 425), + (1, 425), + (1, 373), + (1, 323), + (1, 273), + (1, 213), + (1, 135), + (1, 4), + (1, 2048), +]; + +static OUT_40: [(u8, u16); 32] = [ + (0, 2048), + (0, 4030), + (0, 28), + (0, 104), + (0, 169), + (0, 224), + (0, 274), + (0, 318), + (0, 358), + (0, 395), + (0, 429), + (0, 459), + (0, 488), + (0, 514), + (0, 539), + (0, 566), + (1, 566), + (1, 539), + (1, 514), + (1, 488), + (1, 459), + (1, 429), + (1, 395), + (1, 358), + (1, 318), + (1, 274), + (1, 224), + (1, 169), + (1, 104), + (1, 28), + (1, 4030), + (1, 2048), +]; + +// FUNCTW: scale factor multipliers WI +static WI_16: [u16; 2] = [4074, 439]; +static WI_24: [u16; 4] = [4092, 30, 137, 582]; +static WI_32: [u16; 8] = [4084, 18, 41, 64, 112, 198, 355, 1122]; +static WI_40: [u16; 16] = [14, 14, 24, 39, 40, 41, 58, 100, 141, 179, 219, 280, 358, 440, 529, 696]; + +#[inline] +fn get_wi(rate: BitRate, code: u8) -> u16 { + match rate { + BitRate::Rate16k => { + let im = if (code >> 1) == 0 { (code & 1) as usize } else { ((3 - code) & 1) as usize }; + WI_16[im] + } + BitRate::Rate24k => { + let im = if (code >> 2) == 0 { (code & 3) as usize } else { ((7 - code) & 3) as usize }; + WI_24[im] + } + BitRate::Rate32k => { + let im = if (code >> 3) == 0 { (code & 7) as usize } else { ((15 - code) & 7) as usize }; + WI_32[im] + } + BitRate::Rate40k => { + let im = if (code >> 4) == 0 { (code & 15) as usize } else { ((31 - code) & 15) as usize }; + WI_40[im] + } + } +} + +#[inline] +fn get_fi(rate: BitRate, code: u8) -> u8 { + match rate { + BitRate::Rate16k => { + let im = if (code >> 1) == 0 { code & 1 } else { (3 - code) & 1 }; + if im == 1 { 7 } else { 0 } + } + BitRate::Rate24k => { + let im = if (code >> 2) == 0 { code & 3 } else { (7 - code) & 3 }; + match im { + 0 => 0, + 1 => 1, + 2 => 2, + _ => 7, + } + } + BitRate::Rate32k => { + let im = if (code >> 3) == 0 { code & 7 } else { (15 - code) & 7 }; + if im <= 2 { + 0 + } else if im <= 5 { + 1 + } else if im == 6 { + 3 + } else { + 7 + } + } + BitRate::Rate40k => { + let im = if (code >> 4) == 0 { code & 15 } else { (31 - code) & 15 }; + if im <= 4 { + 0 + } else if im <= 9 { + 1 + } else { + match im { + 10 => 2, + 11 => 3, + 12 => 4, + 13 => 5, + _ => 6, + } + } + } + } +} + +// Quantizer decision intervals (lo, hi, positive_code, negative_code) +static THRESH_16: [(i32, i32, u8, u8); 1] = [(261, 2047, 1, 2)]; + +static THRESH_24: [(i32, i32, u8, u8); 3] = [(331, 2047, 3, 4), (218, 330, 2, 5), (8, 217, 1, 6)]; + +static THRESH_32: [(i32, i32, u8, u8); 8] = [ + (400, 2047, 7, 8), + (349, 399, 6, 9), + (300, 348, 5, 10), + (246, 299, 4, 11), + (178, 245, 3, 12), + (80, 177, 2, 13), + (0, 79, 1, 14), + (3972, 4095, 1, 14), +]; + +static THRESH_40: [(i32, i32, u8, u8); 16] = [ + (553, 2047, 15, 16), + (528, 552, 14, 17), + (502, 527, 13, 18), + (475, 501, 12, 19), + (445, 474, 11, 20), + (413, 444, 10, 21), + (378, 412, 9, 22), + (339, 377, 8, 23), + (298, 338, 7, 24), + (250, 297, 6, 25), + (198, 249, 5, 26), + (139, 197, 4, 27), + (68, 138, 3, 28), + (0, 67, 2, 29), + (4080, 4095, 2, 29), + (3974, 4079, 1, 30), +]; + +#[inline] +fn quantize_16(dln: i32, ds: u8) -> u8 { + for &(lo, hi, pos, neg) in &THRESH_16 { + if (lo..=hi).contains(&dln) { + return if ds == 0 { pos } else { neg }; + } + } + if ds == 0 { 0 } else { 3 } +} + +#[inline] +fn quantize_24(dln: i32, ds: u8) -> u8 { + for &(lo, hi, pos, neg) in &THRESH_24 { + if (lo..=hi).contains(&dln) { + return if ds == 0 { pos } else { neg }; + } + } + 7 +} + +#[inline] +fn quantize_32(dln: i32, ds: u8) -> u8 { + for &(lo, hi, pos, neg) in &THRESH_32 { + if (lo..=hi).contains(&dln) { + return if ds == 0 { pos } else { neg }; + } + } + 15 +} + +#[inline] +fn quantize_40(dln: i32, ds: u8) -> u8 { + for &(lo, hi, pos, neg) in &THRESH_40 { + if (lo..=hi).contains(&dln) { + return if ds == 0 { pos } else { neg }; + } + } + 31 +} + +// --------------------------------------------------------------------------- +// G.726 Core State +// --------------------------------------------------------------------------- + +#[derive(Debug, Clone)] +struct Core { + rate: BitRate, + is_40k: bool, + a: [u16; 2], + b: [u16; 6], + dms: i16, + dml: i16, + ap: i16, + yu: i16, + yl: i32, + sr: [u16; 2], + dq: [u16; 6], + pk: [u8; 2], + td: i16, +} + +impl Core { + fn new(rate: BitRate) -> Self { + let is_40k = matches!(rate, BitRate::Rate40k); + let mut core = + Self { rate, is_40k, a: [0; 2], b: [0; 6], dms: 0, dml: 0, ap: 0, yu: 544, yl: 34816, sr: [32, 32], dq: [32; 6], pk: [0; 2], td: 0 }; + core.reset(); + core + } + + fn reset(&mut self) { + self.a = [0; 2]; + self.b = [0; 6]; + self.dms = 0; + self.dml = 0; + self.ap = 0; + self.yu = 544; + self.yl = 34816; + self.sr = [32, 32]; + self.dq = [32; 6]; + self.pk = [0; 2]; + self.td = 0; + } + + #[inline] + fn fmult(an: u16, srn: u16) -> u16 { + let an_s = (an >> 15) & 1; + let an_mag = if an_s == 0 { (an >> 2) & 0x1FFF } else { (16384_u32.wrapping_sub((an >> 2) as u32) & 0x1FFF) as u16 }; + let an_exp = if an_mag > 0 { (16 - an_mag.leading_zeros()).min(13) as u16 } else { 0 }; + let an_mant = if an_mag == 0 { 1 << 5 } else { (((an_mag as u32) << 6) >> an_exp) as u16 & 0x3F }; + + let srn_s = (srn >> 10) & 1; + let srn_exp = (srn >> 6) & 15; + let srn_mant = srn & 63; + + let wan_s = srn_s ^ an_s; + let wan_exp = srn_exp + an_exp; + let wan_mant = (((srn_mant as u32 * an_mant as u32) + 48) >> 4) as u16; + + let wan_mag = + if wan_exp <= 26 { ((wan_mant as u32) << 7) >> (26 - wan_exp) } else { (((wan_mant as u32) << 7) << (wan_exp - 26)) & 0x7FFF } as u16; + + if wan_s == 0 { wan_mag } else { (65536_u32.wrapping_sub(wan_mag as u32) & 0xFFFF) as u16 } + } + + #[inline] + fn quantize(&self, dln: i32, ds: u8) -> u8 { + match self.rate { + BitRate::Rate16k => quantize_16(dln, ds), + BitRate::Rate24k => quantize_24(dln, ds), + BitRate::Rate32k => quantize_32(dln, ds), + BitRate::Rate40k => quantize_40(dln, ds), + } + } + + #[inline] + fn table_lookup(&self, code: u8) -> (u8, u16) { + match self.rate { + BitRate::Rate16k => OUT_16[(code & 3) as usize], + BitRate::Rate24k => OUT_24[(code & 7) as usize], + BitRate::Rate32k => OUT_32[(code & 15) as usize], + BitRate::Rate40k => OUT_40[(code & 31) as usize], + } + } + + #[inline] + fn compute_accum(&self) -> (i16, i16) { + let wa0 = Self::fmult(self.a[0], self.sr[0]); + let wa1 = Self::fmult(self.a[1], self.sr[1]); + let mut sezi: u32 = 0; + for i in 0..6 { + sezi = (sezi + Self::fmult(self.b[i], self.dq[i]) as u32) & 0xFFFF; + } + let sei = (sezi + wa1 as u32 + wa0 as u32) & 0xFFFF; + let sez = (sezi as i16) >> 1; + let se = (sei as i16) >> 1; + (sez, se) + } + + #[inline] + fn compute_mix(&self) -> i32 { + let al = if self.ap >= 256 { 64 } else { self.ap >> 2 } as i32; + let dif = (self.yu as i32 + 16384 - (self.yl >> 6)) & 16383; + let difs = (dif >> 13) & 1; + let difm = if difs == 0 { dif } else { (16384 - dif) & 8191 }; + let prodm = (difm * al) >> 6; + let prod = if difs == 0 { prodm } else { (16384 - prodm) & 8191 }; + ((self.yl >> 6) + prod) & 8191 + } + + #[inline] + fn quantize_sample(&self, sample: i16, se: i16, y: i32) -> u8 { + let sl = (sample >> 2) as i32; + let sl_ext = if sl >= 0 { sl } else { 65536 + sl }; + let se_ext = if se >= 0 { se as i32 } else { 65536 + se as i32 }; + let d = ((sl_ext + 65536 - se_ext) & 0xFFFF) as u16; + + let ds = ((d >> 15) & 1) as u8; + let dqm = if ds == 0 { d } else { (65536_u32.wrapping_sub(d as u32) & 0x7FFF) as u16 }; + let exp = if dqm > 1 { (15 - dqm.leading_zeros()).min(14) } else { 0 }; + let mant = (((dqm as u32) << 7) >> exp) & 127; + let dl = ((exp << 7) + mant) as u16; + let dln = (dl as i32 + 4096 - (y >> 2)) & 4095; + self.quantize(dln, ds) + } + + #[inline] + fn step(&mut self, sample: i16, is_encoder: bool, code_in: u8) -> (u8, i16) { + let (sez, se) = self.compute_accum(); + let y = self.compute_mix(); + + let code = if is_encoder { self.quantize_sample(sample, se, y) } else { code_in }; + + // 4. RECONST & ADDA & ANTILOG + let (dqs, dqln) = self.table_lookup(code); + let dql = (dqln as i32 + (y >> 2)) & 4095; + let dex = (dql >> 7) & 15; + let dmn = dql & 127; + let dqt = 128 + dmn; + let dqmag = if (dql >> 11) == 0 { ((dqt << 7) >> (14 - dex)) as u16 } else { 0 }; + let dq = if self.is_40k { ((dqs as u16) << 15) | (dqmag & 0x7FFF) } else { ((dqs as u16) << 14) | (dqmag & 0x3FFF) }; + + // 5. ADDB & ADDC + let dqi = if dqs == 0 { + dq as u32 + } else if self.is_40k { + 65536_u32.wrapping_sub((dq & 0x7FFF) as u32) & 0xFFFF + } else { + 65536_u32.wrapping_sub((dq & 0x3FFF) as u32) & 0xFFFF + }; + let sei_ext = if se >= 0 { se as u32 } else { (65536 + se as i32) as u32 }; + let sr = ((dqi + sei_ext) & 0xFFFF) as u16; + + let sezi_ext = if sez >= 0 { sez as u32 } else { (65536 + sez as i32) as u32 }; + let dqsez = ((dqi + sezi_ext) & 0xFFFF) as u16; + let pk0 = ((dqsez >> 15) & 1) as u8; + let sigpk = if dqsez == 0 { 1 } else { 0 }; + + // 6. FLOATA & FLOATB + let dq_mag = if self.is_40k { dq & 0x7FFF } else { dq & 0x3FFF }; + let (dq_exp, dq_mant) = if dq_mag == 0 { + (0, 32) + } else { + let max_exp = if self.is_40k { 15 } else { 14 }; + let exp = (16 - dq_mag.leading_zeros()).min(max_exp); + let mant = (((dq_mag as u32) << 6) >> exp) as u16; + (exp as u16, mant) + }; + let dq0 = ((dqs as u16) << 10) | (dq_exp << 6) | (dq_mant & 63); + + let sr_s = ((sr >> 15) & 1) as u8; + let sr_mag = if sr_s == 0 { sr } else { (65536_u32.wrapping_sub(sr as u32) & 0x7FFF) as u16 }; + let (sr_exp, sr_mant) = if sr_mag == 0 { + (0, 32) + } else { + let exp = (16 - sr_mag.leading_zeros()).min(15); + let mant = (((sr_mag as u32) << 6) >> exp) as u16; + (exp as u16, mant) + }; + let sr0 = ((sr_s as u16) << 10) | (sr_exp << 6) | (sr_mant & 63); + + self.update_adaptation_and_predictors(code, y, pk0, sigpk, dqs, dq_mag); + + self.sr = [sr0, self.sr[0]]; + self.dq = [dq0, self.dq[0], self.dq[1], self.dq[2], self.dq[3], self.dq[4]]; + self.pk = [pk0, self.pk[0]]; + + let sr_signed = if sr < 32768 { sr as i32 } else { sr as i32 - 65536 }; + let out_pcm = (sr_signed << 2).clamp(-32768, 32767) as i16; + (code, out_pcm) + } + + #[inline] + fn adapt_scale(&mut self, code: u8, y: i32) { + let wi = get_wi(self.rate, code); + let dif = (((wi as i32) << 5) + 131072 - y) & 131071; + let difs = (dif >> 16) & 1; + let difsx = if difs == 0 { dif >> 5 } else { (dif >> 5) + 4096 }; + let yut = (y + difsx) & 8191; + let yup = yut.clamp(544, 5120); + + let dif = (yup + ((1048576 - self.yl) >> 6)) & 16383; + let difs = (dif >> 13) & 1; + let difsx = if difs == 0 { dif } else { dif + 507904 }; + self.yu = yup as i16; + self.yl = (self.yl + difsx) & 524287; + } + + #[inline] + fn adapt_speed(&mut self, code: u8, y: i32, dq_mag: u16) -> (i16, i16, u8) { + let fi = get_fi(self.rate, code); + let dif = (((fi as i32) << 9) + 8192 - self.dms as i32) & 8191; + let difs = (dif >> 12) & 1; + let difsx = if difs == 0 { dif >> 5 } else { (dif >> 5) + 3840 }; + let dmsp = ((difsx + self.dms as i32) & 4095) as i16; + + let dif = (((fi as i32) << 11) + 32768 - self.dml as i32) & 32767; + let difs = (dif >> 14) & 1; + let difsx = if difs == 0 { dif >> 7 } else { (dif >> 7) + 16128 }; + let dmlp = ((difsx + self.dml as i32) & 16383) as i16; + + let dif = (((dmsp as i32) << 2) + 32768 - dmlp as i32) & 32767; + let difs = (dif >> 14) & 1; + let difm = if difs == 0 { dif } else { (32768 - dif) & 16383 }; + let dthr = (dmlp as i32) >> 3; + + let tdp = if (32768..53760).contains(&self.a[1]) { 1 } else { 0 }; + let ax = if y >= 1536 && tdp == 0 && difm < dthr { 0 } else { 1 }; + + let dif = ((ax << 9) + 2048 - self.ap as i32) & 2047; + let difs = (dif >> 10) & 1; + let difsx = if difs == 0 { dif >> 4 } else { (dif >> 4) + 1920 }; + let app = ((difsx + self.ap as i32) & 1023) as i16; + + let ylint = (self.yl >> 15) as u32; + let ylfrac = ((self.yl >> 10) & 31) as u32; + let thr1 = (32 + ylfrac) << ylint; + let thr2 = if self.is_40k && ylint > 9 { + 31 << 10 + } else if !self.is_40k && ylint > 8 { + 31 << 9 + } else { + thr1 + }; + let dqthr = (thr2 + (thr2 >> 1)) >> 1; + let tr = if (dq_mag as u32) > dqthr && self.td == 1 { 1 } else { 0 }; + let apr = if tr == 1 { 256 } else { app }; + + self.dms = dmsp; + self.dml = dmlp; + self.ap = apr; + self.td = if tr == 1 { 0 } else { tdp }; + + (apr, tdp, tr) + } + + #[inline] + fn update_predictors(&mut self, pk0: u8, sigpk: u8, dqs: u8, dq_mag: u16, tr: u8) { + let pks = pk0 ^ self.pk[0]; + let uga1 = if sigpk == 1 { + 0 + } else if pks == 0 { + 192 + } else { + 65344 + }; + let a1s = (self.a[0] >> 15) & 1; + let ula1 = if a1s == 0 { + (65536_u32.wrapping_sub((self.a[0] >> 8) as u32) & 0xFFFF) as u16 + } else { + (65536_u32.wrapping_sub(((self.a[0] >> 8) + 65280) as u32) & 0xFFFF) as u16 + }; + let ua1 = (uga1 as u32 + ula1 as u32) & 0xFFFF; + let a1t = ((self.a[0] as u32 + ua1) & 0xFFFF) as u16; + + let pks1 = pk0 ^ self.pk[0]; + let pks2 = pk0 ^ self.pk[1]; + let uga2a = if pks2 == 0 { 16384_u32 } else { 114688_u32 }; + let a1_u = self.a[0]; + let fa1 = if a1s == 0 { + if a1_u <= 8191 { (a1_u as u32) << 2 } else { 8191 << 2 } + } else if a1_u >= 57345 { + ((a1_u as u32) << 2) & 131071 + } else { + 24577 << 2 + }; + let fa = if pks1 == 1 { fa1 } else { (131072_u32.wrapping_sub(fa1)) & 131071 }; + let uga2b = (uga2a + fa) & 131071; + let uga2s = (uga2b >> 16) & 1; + let uga2 = if sigpk == 1 { + 0 + } else if uga2s == 0 { + uga2b >> 7 + } else { + (uga2b >> 7) + 64512 + } as u16; + let a2s = (self.a[1] >> 15) & 1; + let ula2 = if a2s == 0 { + (65536_u32.wrapping_sub((self.a[1] >> 7) as u32) & 0xFFFF) as u16 + } else { + (65536_u32.wrapping_sub(((self.a[1] >> 7) + 65024) as u32) & 0xFFFF) as u16 + }; + let ua2 = (uga2 as u32 + ula2 as u32) & 0xFFFF; + let a2t = ((self.a[1] as u32 + ua2) & 0xFFFF) as u16; + + let a2p = if (32768..=53248).contains(&a2t) { + 53248 + } else if (12288..=32767).contains(&a2t) { + 12288 + } else { + a2t + }; + + let ome = 15360_u32; + let a1ul = ((ome + 65536 - a2p as u32) & 0xFFFF) as u16; + let a1ll = ((a2p as u32 + 65536 - ome) & 0xFFFF) as u16; + let a1p = if a1t >= 32768 && a1t <= a1ll { + a1ll + } else if a1t >= a1ul && a1t <= 32767 { + a1ul + } else { + a1t + }; + + let a1r = if tr == 1 { 0 } else { a1p }; + let a2r = if tr == 1 { 0 } else { a2p }; + + let mut new_b = [0u16; 6]; + for (i, slot) in new_b.iter_mut().enumerate() { + let un = (dqs ^ ((self.dq[i] >> 10) as u8)) & 1; + let ugbn = if dq_mag == 0 { + 0 + } else if un == 0 { + 128 + } else { + 65408 + }; + let bns = (self.b[i] >> 15) & 1; + let ulbn = if self.is_40k { + if bns == 0 { + (65536_u32.wrapping_sub((self.b[i] >> 9) as u32) & 0xFFFF) as u16 + } else { + (65536_u32.wrapping_sub(((self.b[i] >> 9) + 65408) as u32) & 0xFFFF) as u16 + } + } else if bns == 0 { + (65536_u32.wrapping_sub((self.b[i] >> 8) as u32) & 0xFFFF) as u16 + } else { + (65536_u32.wrapping_sub(((self.b[i] >> 8) + 65280) as u32) & 0xFFFF) as u16 + }; + let ubn = (ugbn as u32 + ulbn as u32) & 0xFFFF; + let bnp = ((self.b[i] as u32 + ubn) & 0xFFFF) as u16; + *slot = if tr == 1 { 0 } else { bnp }; + } + + self.a[0] = a1r; + self.a[1] = a2r; + self.b = new_b; + } + + #[inline] + fn update_adaptation_and_predictors(&mut self, code: u8, y: i32, pk0: u8, sigpk: u8, dqs: u8, dq_mag: u16) { + self.adapt_scale(code, y); + let (_, _, tr) = self.adapt_speed(code, y, dq_mag); + self.update_predictors(pk0, sigpk, dqs, dq_mag, tr); + } +} + +// --------------------------------------------------------------------------- +// Decoder & Encoder structs +// --------------------------------------------------------------------------- + +/// G.726 ADPCM decoder. +#[derive(Debug, Clone)] +pub struct Decoder { + core: Core, + packing: BitPacking, + bit_buf: u32, + num_bits: usize, +} + +impl Decoder { + /// Create a new G.726 decoder at the specified bit rate and bit packing. + #[must_use] + pub fn new(rate: BitRate, packing: BitPacking) -> Self { + Self { core: Core::new(rate), packing, bit_buf: 0, num_bits: 0 } + } + + /// Reset decoder internal predictor state. + pub fn reset(&mut self) { + self.core.reset(); + self.bit_buf = 0; + self.num_bits = 0; + } + + /// Decode a single quantized ADPCM code into an 8 kHz 16-bit linear PCM sample. + /// Bits above the configured code width are ignored, as in packed-stream decoding. + #[inline] + pub fn decode_sample(&mut self, code: u8) -> i16 { + // Adaptation must see the same bounded codeword as the reconstruction table; + // otherwise unused high bits can underflow its unsigned inverse-code arithmetic. + let code = code & ((1u8 << self.core.rate.code_size()) - 1); + self.core.step(0, false, code).1 + } + + /// Decode G.726 bitstream bytes into 8 kHz 16-bit linear PCM samples, appending to `dst`. + pub fn decode(&mut self, src: &[u8], dst: &mut Vec) -> Result<(), Error> { + if src.len() > MAX_INPUT_BYTES { + return Err(Error::InputTooLarge); + } + let cs = self.core.rate.code_size(); + let est_samples = (src.len() * 8) / cs; + dst.try_reserve(est_samples).map_err(|_| Error::AllocationFailed)?; + + match self.packing { + BitPacking::BigEndian => { + for &b in src { + self.bit_buf = ((self.bit_buf & ((1 << self.num_bits) - 1)) << 8) | (b as u32); + self.num_bits += 8; + while self.num_bits >= cs { + let code = ((self.bit_buf >> (self.num_bits - cs)) & ((1 << cs) - 1)) as u8; + self.num_bits -= cs; + let s = self.decode_sample(code); + dst.push(s); + } + self.bit_buf &= (1 << self.num_bits) - 1; + } + } + BitPacking::LittleEndian => { + for &b in src { + self.bit_buf |= (b as u32) << self.num_bits; + self.num_bits += 8; + while self.num_bits >= cs { + let code = (self.bit_buf & ((1 << cs) - 1)) as u8; + self.bit_buf >>= cs; + self.num_bits -= cs; + let s = self.decode_sample(code); + dst.push(s); + } + } + } + } + Ok(()) + } +} + +/// G.726 ADPCM encoder. +#[derive(Debug, Clone)] +pub struct Encoder { + core: Core, + packing: BitPacking, + bit_buf: u32, + num_bits: usize, +} + +impl Encoder { + /// Create a new G.726 encoder at the specified bit rate and bit packing. + #[must_use] + pub fn new(rate: BitRate, packing: BitPacking) -> Self { + Self { core: Core::new(rate), packing, bit_buf: 0, num_bits: 0 } + } + + /// Reset encoder internal predictor state. + pub fn reset(&mut self) { + self.core.reset(); + self.bit_buf = 0; + self.num_bits = 0; + } + + /// Encode a single 8 kHz 16-bit linear PCM sample into an ADPCM code word. + #[inline] + pub fn encode_sample(&mut self, sample: i16) -> u8 { + self.core.step(sample, true, 0).0 + } + + /// Encode 8 kHz 16-bit linear PCM samples into G.726 bitstream bytes, appending to `dst`. + pub fn encode(&mut self, src: &[i16], dst: &mut Vec) -> Result<(), Error> { + if src.len() > MAX_SAMPLES { + return Err(Error::InputTooLarge); + } + let cs = self.core.rate.code_size(); + let est_bytes = (src.len() * cs).div_ceil(8); + dst.try_reserve(est_bytes).map_err(|_| Error::AllocationFailed)?; + + match self.packing { + BitPacking::BigEndian => { + for &s in src { + let code = self.encode_sample(s); + self.bit_buf = ((self.bit_buf & ((1 << self.num_bits) - 1)) << cs) | ((code as u32) & ((1 << cs) - 1)); + self.num_bits += cs; + while self.num_bits >= 8 { + dst.push(((self.bit_buf >> (self.num_bits - 8)) & 0xFF) as u8); + self.num_bits -= 8; + } + self.bit_buf &= (1 << self.num_bits) - 1; + } + } + BitPacking::LittleEndian => { + for &s in src { + let code = self.encode_sample(s); + self.bit_buf |= (code as u32) << self.num_bits; + self.num_bits += cs; + while self.num_bits >= 8 { + dst.push((self.bit_buf & 0xFF) as u8); + self.bit_buf >>= 8; + self.num_bits -= 8; + } + } + } + } + Ok(()) + } + + /// Flush any remaining buffered bits into `dst`, padding with zeroes. + pub fn flush(&mut self, dst: &mut Vec) -> Result<(), Error> { + if self.num_bits > 0 { + dst.try_reserve(1).map_err(|_| Error::AllocationFailed)?; + match self.packing { + BitPacking::BigEndian => { + let b = ((self.bit_buf << (8 - self.num_bits)) & 0xFF) as u8; + dst.push(b); + } + BitPacking::LittleEndian => { + let b = (self.bit_buf & 0xFF) as u8; + dst.push(b); + } + } + self.bit_buf = 0; + self.num_bits = 0; + } + Ok(()) + } +} + +// --------------------------------------------------------------------------- +// Public Top-Level Functions +// --------------------------------------------------------------------------- + +/// Decode a mono G.726 bitstream into 8 kHz 16-bit linear PCM samples. +pub fn decode(bytes: &[u8], rate: BitRate, packing: BitPacking) -> Result, Error> { + let mut decoder = Decoder::new(rate, packing); + let mut out = Vec::new(); + decoder.decode(bytes, &mut out)?; + Ok(out) +} + +/// Encode mono 8 kHz 16-bit linear PCM samples into a G.726 bitstream. +pub fn encode(samples: &[i16], rate: BitRate, packing: BitPacking) -> Result, Error> { + let mut encoder = Encoder::new(rate, packing); + let mut out = Vec::new(); + encoder.encode(samples, &mut out)?; + encoder.flush(&mut out)?; + Ok(out) +} + +/// Decode an interleaved multi-channel G.726 stream into interleaved 8 kHz 16-bit PCM samples. +pub fn decode_interleaved(bytes: &[u8], channels: usize, rate: BitRate, packing: BitPacking) -> Result, Error> { + if channels == 0 || channels > MAX_CHANNELS { + return Err(Error::InvalidChannels(channels)); + } + if channels == 1 { + return decode(bytes, rate, packing); + } + if bytes.len() > MAX_INPUT_BYTES { + return Err(Error::InputTooLarge); + } + + let mut decoders: Vec = Vec::with_capacity(channels); + for _ in 0..channels { + decoders.push(Decoder::new(rate, packing)); + } + + let cs = rate.code_size(); + let est_samples = (bytes.len() * 8) / cs; + let mut out = Vec::new(); + out.try_reserve(est_samples).map_err(|_| Error::AllocationFailed)?; + + let mut ch_outs: Vec> = Vec::with_capacity(channels); + for _ in 0..channels { + ch_outs.push(Vec::new()); + } + + for (i, &b) in bytes.iter().enumerate() { + let ch = i % channels; + decoders[ch].decode(&[b], &mut ch_outs[ch])?; + } + + let min_len = ch_outs.iter().map(Vec::len).min().unwrap_or(0); + for i in 0..min_len { + for ch_out in ch_outs.iter().take(channels) { + out.push(ch_out[i]); + } + } + + Ok(out) +} + +/// Encode interleaved 8 kHz 16-bit PCM samples into an interleaved multi-channel G.726 stream. +pub fn encode_interleaved(samples: &[i16], channels: usize, rate: BitRate, packing: BitPacking) -> Result, Error> { + if channels == 0 || channels > MAX_CHANNELS { + return Err(Error::InvalidChannels(channels)); + } + if channels == 1 { + return encode(samples, rate, packing); + } + if samples.len() > MAX_SAMPLES { + return Err(Error::InputTooLarge); + } + + let mut encoders: Vec = Vec::with_capacity(channels); + for _ in 0..channels { + encoders.push(Encoder::new(rate, packing)); + } + + let cs = rate.code_size(); + let est_bytes = (samples.len() * cs).div_ceil(8); + let mut out = Vec::new(); + out.try_reserve(est_bytes).map_err(|_| Error::AllocationFailed)?; + + let mut ch_samples: Vec> = Vec::with_capacity(channels); + for _ in 0..channels { + ch_samples.push(Vec::new()); + } + + for (i, &s) in samples.iter().enumerate() { + let ch = i % channels; + ch_samples[ch].push(s); + } + + let mut ch_bytes: Vec> = Vec::with_capacity(channels); + for ch in 0..channels { + let mut b = Vec::new(); + encoders[ch].encode(&ch_samples[ch], &mut b)?; + encoders[ch].flush(&mut b)?; + ch_bytes.push(b); + } + + let min_bytes = ch_bytes.iter().map(Vec::len).min().unwrap_or(0); + for i in 0..min_bytes { + for ch_b in ch_bytes.iter().take(channels) { + out.push(ch_b[i]); + } + } + + Ok(out) +} + +// --------------------------------------------------------------------------- +// Unit tests +// --------------------------------------------------------------------------- + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn sample_api_ignores_unused_codeword_bits() { + for rate in [BitRate::Rate16k, BitRate::Rate24k, BitRate::Rate32k, BitRate::Rate40k] { + let mask = (1u8 << rate.code_size()) - 1; + let mut actual = Decoder::new(rate, BitPacking::BigEndian); + let mut expected = Decoder::new(rate, BitPacking::BigEndian); + for code in 0..=u8::MAX { + assert_eq!(actual.decode_sample(code), expected.decode_sample(code & mask)); + } + // High bits must not leave a different predictor state for later valid codes. + for code in 0..=mask { + assert_eq!(actual.decode_sample(code), expected.decode_sample(code)); + } + } + } + + #[test] + fn reject_invalid_channels() { + assert!(decode_interleaved(&[], 0, BitRate::Rate32k, BitPacking::BigEndian).is_err()); + assert!(decode_interleaved(&[], 9, BitRate::Rate32k, BitPacking::BigEndian).is_err()); + assert!(encode_interleaved(&[], 0, BitRate::Rate32k, BitPacking::BigEndian).is_err()); + assert!(encode_interleaved(&[], 9, BitRate::Rate32k, BitPacking::BigEndian).is_err()); + } + + #[test] + fn roundtrip_silence_all_rates() { + let pcm = vec![0i16; 64]; + for rate in [BitRate::Rate16k, BitRate::Rate24k, BitRate::Rate32k, BitRate::Rate40k] { + for packing in [BitPacking::BigEndian, BitPacking::LittleEndian] { + let encoded = encode(&pcm, rate, packing).expect("encode silence"); + let decoded = decode(&encoded, rate, packing).expect("decode silence"); + assert_eq!(decoded.len(), pcm.len()); + for &s in &decoded { + assert!(s.abs() <= 16, "silence sample too large: {s}"); + } + } + } + } + + #[test] + fn hostile_input_does_not_panic() { + let mut decoder = Decoder::new(BitRate::Rate32k, BitPacking::BigEndian); + let mut out = Vec::new(); + let hostile = vec![0xFF; 1024]; + let _ = decoder.decode(&hostile, &mut out); + + let mut decoder = Decoder::new(BitRate::Rate16k, BitPacking::LittleEndian); + let mut out = Vec::new(); + let _ = decoder.decode(&[0x00, 0xAA, 0x55, 0x12, 0x34], &mut out); + } +} diff --git a/crates/audio/src/lib.rs b/crates/audio/src/lib.rs index e5e859d3c..9ca1571cf 100644 --- a/crates/audio/src/lib.rs +++ b/crates/audio/src/lib.rs @@ -2,7 +2,7 @@ #![warn(missing_docs)] // The docs link items of every feature; built with fewer features, those links have no target. // CI and docs.rs build the docs with all features, where every link must resolve. -#![cfg_attr(not(all(feature = "decode", feature = "encode", feature = "peaks")), allow(rustdoc::broken_intra_doc_links))] +#![cfg_attr(not(all(feature = "decode", feature = "encode", feature = "peaks", feature = "dsd")), allow(rustdoc::broken_intra_doc_links))] //! Audio file I/O and codecs for the Craft apps. Input and output are byte slices or a //! [`craft_media::ByteSource`] (no filesystem access of its own); builds for //! `wasm32-unknown-unknown`. @@ -13,6 +13,7 @@ //! demuxers and [`TrackDecoder`]; everything else (FLAC, Vorbis, CAF, ADPCM, A-law, µ-law) through //! `symphonia`, which is to be replaced by native decoders. Feature `decode-native` is the //! same without symphonia. +//! - [`vorbis::decoder`] (feature `vorbis-decode`): the pure-Rust Vorbis I decoder, packets and Ogg files. //! - [`encode_ogg_vorbis`] and [`vorbis::encoder`] (feature `vorbis-encode`): Ogg Vorbis files //! and Vorbis packets from a pure-Rust encoder, 1 to 8 channels, quality -1 to 10, with tags. //! - [`TrackDecoder`] (any decoder feature): one track's packets from any demuxer to planar @@ -28,10 +29,12 @@ //! - [`peaks`] (feature `peaks`): min/max/RMS pyramid for waveform drawing. //! - Codec modules for packet-level use, each with its own features: [`aac`] (`aac-decode`, //! `aac-encode`), [`alac`] (`alac-decode`, `alac-encode`), [`opus`] (`opus-decode`, and -//! [`opus::encoder`] with `opus-encode`), [`ac3`] (`ac3-decode`), [`mpa`] (`mpa-decode`), [`mp3`] +//! [`opus::encoder`] with `opus-encode`), [`ac3`] (`ac3-decode`), [`mpa`] (`mpa-decode`; `mpa-encode`: the Layer II encoder), [`mp3`] //! (`mp3-decode`, `mp3-encode`), [`flac`] (`flac-decode`: the frame and file decoder; -//! `flac-encode`: the packet encoder), [`qoa`] (`qoa-decode`, `qoa-encode`: whole QOA files), -//! [`gsm`] (`gsm-decode`, `gsm-encode`: GSM 06.10 full-rate speech). +//! `flac-encode`: the packet encoder), [`qoa`] (`qoa-decode`, `qoa-encode`: whole QOA files), [`adpcm`] +//! (`adpcm`: IMA WAV, Microsoft, Yamaha and Flash ADPCM), [`dsd`] (`dsd`: DSF and DSDIFF files to PCM), +//! [`gsm`] (`gsm-decode`, `gsm-encode`: GSM 06.10 full-rate speech), [`vmd`] (`vmd-decode`: +//! Sierra VMD sound). //! //! The shared types below build with no features. @@ -39,9 +42,17 @@ pub mod aac; #[cfg(any(feature = "ac3-decode", feature = "ac3-encode", feature = "eac3-encode"))] pub mod ac3; +#[cfg(feature = "adpcm")] +pub mod adpcm; #[cfg(any(feature = "alac-decode", feature = "alac-encode"))] pub mod alac; mod buffer; +#[cfg(feature = "dsd")] +pub mod dsd; +#[cfg(feature = "g722")] +pub mod g722; +#[cfg(feature = "g726")] +pub mod g726; #[cfg(any(feature = "gsm-decode", feature = "gsm-encode"))] pub mod gsm; mod layout; @@ -63,7 +74,9 @@ mod read; pub mod sbc; #[cfg(any(feature = "aac-decode", feature = "alac-decode", feature = "opus-decode", feature = "ac3-decode", feature = "mpa-decode"))] mod track; -#[cfg(feature = "vorbis-encode")] +#[cfg(feature = "vmd-decode")] +pub mod vmd; +#[cfg(any(feature = "vorbis-decode", feature = "vorbis-encode"))] pub mod vorbis; #[cfg(any(feature = "decode-native", feature = "pcm-encode"))] mod wav; @@ -267,6 +280,16 @@ impl From for AudioError { } } +#[cfg(feature = "vmd-decode")] +impl From for AudioError { + fn from(e: vmd::Error) -> Self { + match e { + vmd::Error::Unsupported(_) => AudioError::Unsupported(e.to_string()), + _ => AudioError::Malformed(e.to_string()), + } + } +} + #[cfg(feature = "opus-encode")] impl From for AudioError { fn from(e: opus::encoder::Error) -> Self { diff --git a/crates/audio/src/mp3/mod.rs b/crates/audio/src/mp3/mod.rs index d28607110..e273e903c 100644 --- a/crates/audio/src/mp3/mod.rs +++ b/crates/audio/src/mp3/mod.rs @@ -39,13 +39,13 @@ mod decoder; #[cfg(feature = "mp3-encode")] mod encoder; #[cfg(feature = "mp3-encode")] -mod filterbank; +pub(crate) mod filterbank; #[cfg(feature = "mp3-encode")] mod huffman; mod huffman_tables; #[cfg(feature = "mp3-encode")] mod quantize; -mod tables; +pub(crate) mod tables; #[cfg(feature = "mp3-decode")] pub use decoder::{Decoder, InfoTag}; diff --git a/crates/audio/src/mpa/encoder.rs b/crates/audio/src/mpa/encoder.rs new file mode 100644 index 000000000..000f86fe7 --- /dev/null +++ b/crates/audio/src/mpa/encoder.rs @@ -0,0 +1,493 @@ +//! The Layer II encoder; the module docs are in `mpa/mod.rs`. + +// Index loops follow the specification's pseudo-code (FilmCraft allows this lint workspace-wide). +#![allow(clippy::needless_range_loop)] + +use craft_media::bitstream::BitWriter; + +use super::tables::{self, AllocTable, SUBBANDS}; +use crate::mp3::filterbank::Polyphase; +use crate::mp3::tables::ath_db; + +/// Settings an [`Encoder`] refuses. +#[non_exhaustive] +#[derive(Debug, thiserror::Error, PartialEq, Eq)] +pub enum EncodeError { + /// A sample rate outside [`SAMPLE_RATES`]. + #[error("MP2: unsupported sample rate {0} Hz (32, 44.1, 48 kHz, or 16, 22.05, 24 kHz)")] + SampleRate(u32), + /// A bit rate that is not one of [`bitrates`] for the sample rate and channel count. + #[error("MP2: unsupported bit rate {kbps} kbit/s at {rate} Hz with {channels} channel(s)")] + Bitrate { + /// The bit rate asked for, kbit/s. + kbps: u32, + /// The sample rate, Hz. + rate: u32, + /// The channel count. + channels: usize, + }, + /// More than two channels, or none. + #[error("MP2: unsupported channel count {0} (1 or 2)")] + Channels(usize), +} + +/// Result with this module's [`EncodeError`]. +pub type EncodeResult = std::result::Result; + +/// Encoder settings. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub struct Config { + /// One of [`SAMPLE_RATES`]. + pub sample_rate: u32, + /// 1 or 2. Two channels are coded as stereo (`mode` 00), each with its own allocation. + pub channels: usize, + /// One of [`bitrates`] for the sample rate and channel count, kbit/s. + pub bitrate_kbps: u32, +} + +impl Config { + /// `channels` at `sample_rate`, constant `bitrate_kbps`. + pub fn cbr(sample_rate: u32, channels: usize, bitrate_kbps: u32) -> Config { + Config { sample_rate, channels, bitrate_kbps } + } +} + +/// The sample rates the encoder accepts. +pub const SAMPLE_RATES: [u32; 6] = [32_000, 44_100, 48_000, 16_000, 22_050, 24_000]; + +/// Samples by which a standard decoder's output lags the input: the polyphase analysis and +/// synthesis filters. +pub const DELAY: u32 = 481; + +/// Samples per channel in a frame. +pub const FRAME_SAMPLES: usize = 1152; + +/// Bit rates ISO/IEC 11172-3 Table 3-B.2 allows for a single channel at 32 / 44.1 / 48 kHz. +const MPEG1_MONO: [u32; 10] = [32, 48, 56, 64, 80, 96, 112, 128, 160, 192]; +/// Bit rates it allows for two channels. +const MPEG1_STEREO: [u32; 10] = [64, 96, 112, 128, 160, 192, 224, 256, 320, 384]; + +/// Whether `rate` is one of the MPEG-2 lower sampling frequencies; `None` if it is unsupported. +fn is_lsf(rate: u32) -> Option { + match rate { + 32_000 | 44_100 | 48_000 => Some(false), + 16_000 | 22_050 | 24_000 => Some(true), + _ => None, + } +} + +/// The bit rates (kbit/s) a Layer II stream can use at `sample_rate` with `channels` channels: +/// at 32 / 44.1 / 48 kHz the combinations ISO/IEC 11172-3 allows (32-192 for one channel, 64-384 +/// for two), at the lower sampling frequencies 8-160 for either. Empty for an unsupported rate. +pub fn bitrates(sample_rate: u32, channels: usize) -> &'static [u32] { + match is_lsf(sample_rate) { + Some(false) if channels == 1 => &MPEG1_MONO, + Some(false) => &MPEG1_STEREO, + Some(true) => &tables::BITRATES_LSF_L23[1..], + None => &[], + } +} + +/// The highest bit rate at `sample_rate` and `channels` not above `kbps` (the lowest one when +/// `kbps` is below all of them); `None` for an unsupported rate. +pub fn nearest_bitrate(sample_rate: u32, channels: usize, kbps: u32) -> Option { + let rates = bitrates(sample_rate, channels); + rates.iter().rev().find(|&&r| r <= kbps).or(rates.first()).copied() +} + +/// SNR-free noise model: the power of the error of rounding a value in ±1 to one of `steps` +/// levels spaced `2 / steps` apart, is `(2 / steps)² / 12`. +fn quantization_noise(steps: u16) -> f32 { + let d = 2.0 / f32::from(steps); + d * d / 12.0 +} + +/// Index of the scalefactor for a peak of `peak` (Table 3-B.1): the smallest scalefactor that is +/// at least `peak`, i.e. the largest index. +fn scalefactor_index(peak: f32) -> u32 { + if peak.is_nan() || peak <= 0.0 { + return 62; + } + let mut i = (3.0 * (1.0 - f64::from(peak).log2())).floor().clamp(0.0, 62.0) as u32; + while i > 0 && tables::scalefactor(i) < peak { + i -= 1; + } + while i < 62 && tables::scalefactor(i + 1) >= peak { + i += 1; + } + i +} + +/// Which scalefactors of a subband's three parts are sent (`scfsi`, §2.4.1.6) and what they are. +fn share(sf: [u32; 3]) -> (u32, [u32; 3]) { + let near = |a: u32, b: u32| a.abs_diff(b) <= 1; + let [a, b, c] = sf; + if near(a, b) && near(b, c) && near(a, c) { + let m = a.min(b).min(c); + (2, [m, m, m]) + } else if near(a, b) { + let m = a.min(b); + (1, [m, m, c]) + } else if near(b, c) { + let m = b.min(c); + (3, [a, m, m]) + } else { + (0, sf) + } +} + +/// Scalefactors sent for an `scfsi` class. +fn scalefactors_sent(scfsi: u32) -> u64 { + match scfsi { + 0 => 3, + 2 => 1, + _ => 2, + } +} + +/// Bits of the 12 granules of samples in a subband with `steps` quantization steps. +fn sample_bits(steps: u16) -> u64 { + 12 * match tables::grouping(steps) { + Some(bits) => u64::from(bits), + None => 3 * u64::from((u32::from(steps) + 1).trailing_zeros()), + } +} + +/// What the encoder decided for one channel of a frame. +#[derive(Clone)] +struct ChannelPlan { + /// The allocation value (index into the table's row) per subband. + alloc: [usize; SUBBANDS], + /// `scfsi` per subband. + scfsi: [u32; SUBBANDS], + /// The scalefactor index of each part of each subband, after sharing. + sf: [[u32; 3]; SUBBANDS], + /// Mean square of each subband's samples. + energy: [f32; SUBBANDS], +} + +/// A Layer II encoder. Feed planar `f32` samples (full scale ±1) to [`Encoder::encode`]; it +/// returns whole frames as they are completed. [`Encoder::flush`] pads the end with silence and +/// returns the rest. +/// +/// ``` +/// use craft_audio::mpa::encoder::{Config, DELAY, Encoder}; +/// +/// let left: Vec = (0..48_000).map(|i| (i as f32 * 0.05).sin() * 0.5).collect(); +/// let right = left.clone(); +/// let mut enc = Encoder::new(Config::cbr(48_000, 2, 192))?; +/// let mut mp2 = enc.encode(&[&left, &right]); // whole frames as they complete +/// mp2.extend(enc.flush()); // pads with silence to the last input sample +/// assert_eq!(mp2.len() % 576, 0); // 192 kbit/s at 48 kHz: 576 bytes per frame +/// assert_eq!(DELAY, 481); // a decoder's output lags the input by this many samples +/// # Ok::<(), craft_audio::mpa::encoder::EncodeError>(()) +/// ``` +pub struct Encoder { + cfg: Config, + lsf: bool, + sr_index: u32, + br_index: u32, + table: AllocTable, + sblimit: usize, + /// The masking offset floor per subband (power), from the threshold in quiet. + ath: [f32; SUBBANDS], + poly: Vec, + /// Buffered input per channel, and how much of it is consumed. + input: Vec>, + consumed: usize, + /// Remainder accumulator for the padding slot (44.1 / 22.05 kHz). + pad_acc: u64, + samples_in: u64, + frames: u64, +} + +impl Encoder { + /// An encoder for `cfg`, or the setting it cannot carry. + pub fn new(cfg: Config) -> EncodeResult { + let lsf = is_lsf(cfg.sample_rate).ok_or(EncodeError::SampleRate(cfg.sample_rate))?; + if !(1..=2).contains(&cfg.channels) { + return Err(EncodeError::Channels(cfg.channels)); + } + let bad = EncodeError::Bitrate { kbps: cfg.bitrate_kbps, rate: cfg.sample_rate, channels: cfg.channels }; + if !bitrates(cfg.sample_rate, cfg.channels).contains(&cfg.bitrate_kbps) { + return Err(bad); + } + let (rates, bitrate_table): (&[u32; 3], &[u32; 15]) = + if lsf { (&[22_050, 24_000, 16_000], &tables::BITRATES_LSF_L23) } else { (&tables::SAMPLE_RATES, &tables::BITRATES_MPEG1_L2) }; + let sr_index = rates.iter().position(|&r| r == cfg.sample_rate).ok_or(EncodeError::SampleRate(cfg.sample_rate))?; + let br_index = bitrate_table.iter().position(|&b| b == cfg.bitrate_kbps).ok_or(bad)?; + let per_channel = cfg.bitrate_kbps / cfg.channels as u32; + let table = AllocTable::select(lsf, cfg.sample_rate, per_channel); + let sblimit = table.sblimit().min(SUBBANDS); + let mut ath = [0f32; SUBBANDS]; + for (sb, a) in ath.iter_mut().enumerate() { + let centre = (sb as f64 + 0.5) * f64::from(cfg.sample_rate) / 64.0; + // a full-scale sine has a mean square of 1/2 and plays back at about 96 dB SPL + *a = (0.5 * 10f64.powf((ath_db(centre) - 96.0) / 10.0)) as f32; + } + Ok(Encoder { + cfg, + lsf, + sr_index: sr_index as u32, + br_index: br_index as u32, + table, + sblimit, + ath, + poly: vec![Polyphase::new(); cfg.channels], + input: vec![Vec::new(); cfg.channels], + consumed: 0, + pad_acc: 0, + samples_in: 0, + frames: 0, + }) + } + + /// The settings. + pub fn config(&self) -> &Config { + &self.cfg + } + + /// Samples per channel in a frame: 1152. + pub fn frame_samples(&self) -> usize { + FRAME_SAMPLES + } + + /// Samples by which a standard decoder's output lags the input. + pub fn delay(&self) -> u32 { + DELAY + } + + /// Frames written so far. + pub fn frames(&self) -> u64 { + self.frames + } + + /// Encode planar samples (one slice per channel; a missing channel is silence, extra ones + /// are ignored, every channel takes the first channel's length). Returns the completed frames. + pub fn encode(&mut self, planar: &[&[f32]]) -> Vec { + let n = planar.first().map_or(0, |p| p.len()); + for (c, buf) in self.input.iter_mut().enumerate() { + let src = planar.get(c).copied().unwrap_or(&[]); + buf.extend((0..n).map(|i| src.get(i).copied().filter(|v| v.is_finite()).unwrap_or(0.0).clamp(-4.0, 4.0))); + } + self.samples_in = self.samples_in.saturating_add(n as u64); + let mut out = Vec::new(); + self.drain(&mut out); + out + } + + /// Encode the buffered rest padded with silence, plus enough silence that a decoder outputs + /// every input sample, and return the remaining frames. + pub fn flush(&mut self) -> Vec { + let fs = FRAME_SAMPLES as u64; + let needed = if self.samples_in == 0 { self.frames } else { self.samples_in.saturating_add(u64::from(DELAY)).div_ceil(fs) }; + let have = self.input.first().map_or(0, |b| b.len().saturating_sub(self.consumed)); + let want = (needed.saturating_sub(self.frames) as usize).saturating_mul(FRAME_SAMPLES); + if want > have { + for buf in &mut self.input { + buf.resize(self.consumed + want, 0.0); + } + } + let mut out = Vec::new(); + self.drain(&mut out); + self.input.iter_mut().for_each(Vec::clear); + self.consumed = 0; + out + } + + /// Encode every whole frame of buffered input. + fn drain(&mut self, out: &mut Vec) { + while self.input.first().is_some_and(|b| b.len() - self.consumed >= FRAME_SAMPLES) { + let mut sub = vec![[[0f32; SUBBANDS]; 36]; self.cfg.channels]; + for (ch, slots) in sub.iter_mut().enumerate() { + let (Some(buf), Some(poly)) = (self.input.get(ch), self.poly.get_mut(ch)) else { continue }; + let frame = buf.get(self.consumed..self.consumed + FRAME_SAMPLES).unwrap_or(&[]); + for (slot, chunk) in slots.iter_mut().zip(frame.as_chunks::<32>().0) { + poly.filter(chunk, slot); + } + } + self.consumed += FRAME_SAMPLES; + self.write_frame(&sub, out); + self.frames += 1; + } + // keep the buffer small + if self.consumed >= 1 << 16 { + for buf in &mut self.input { + buf.drain(..self.consumed); + } + self.consumed = 0; + } + } + + /// The scalefactors and energies of a channel's 36 time slots. + fn analyse(&self, slots: &[[f32; SUBBANDS]; 36]) -> ChannelPlan { + let mut plan = ChannelPlan { alloc: [0; SUBBANDS], scfsi: [0; SUBBANDS], sf: [[62; 3]; SUBBANDS], energy: [0.0; SUBBANDS] }; + for sb in 0..self.sblimit { + let mut sf = [62u32; 3]; + for (part, s) in sf.iter_mut().enumerate() { + let peak = slots[12 * part..12 * part + 12].iter().map(|slot| slot[sb].abs()).fold(0f32, f32::max); + *s = scalefactor_index(peak); + } + (plan.scfsi[sb], plan.sf[sb]) = share(sf); + plan.energy[sb] = slots.iter().map(|slot| slot[sb] * slot[sb]).sum::() / 36.0; + } + plan + } + + /// Choose the allocation of every subband of every channel with the bits the frame has. + fn allocate(&self, plans: &mut [ChannelPlan], mut bits_left: i64) { + let nch = plans.len(); + // power the quantization noise of each subband may have before it is audible: a spread + // of the band energies, never below the threshold in quiet + let mut mask = vec![[0f32; SUBBANDS]; nch]; + for (m, plan) in mask.iter_mut().zip(plans.iter()) { + for sb in 0..self.sblimit { + let mut level = self.ath[sb]; + for j in 0..self.sblimit { + let atten_db = 14.0 + 20.0 * sb.abs_diff(j) as f32; + level = level.max(plan.energy[j] * 10f32.powf(-atten_db / 10.0)); + } + m[sb] = level; + } + } + // the fixed cost: every subband's allocation field + for sb in 0..self.sblimit { + bits_left -= (nch * self.table.row(sb).len().trailing_zeros() as usize) as i64; + } + // the noise a subband has with allocation `a`: dropped, or the mean over its parts + let noise = |plan: &ChannelPlan, sb: usize, a: usize| -> f32 { + let row = self.table.row(sb); + let steps = row.get(a).copied().unwrap_or(0); + if steps == 0 { + return plan.energy[sb]; + } + let mean_sf2 = plan.sf[sb].iter().map(|&i| tables::scalefactor(i).powi(2)).sum::() / 3.0; + (quantization_noise(steps) * mean_sf2).min(plan.energy[sb]) + }; + let cost = |plan: &ChannelPlan, sb: usize, a: usize| -> i64 { + let row = self.table.row(sb); + let step = |a: usize| row.get(a).copied().unwrap_or(0); + let (from, to) = (step(a), step(a + 1)); + let mut bits = sample_bits(to) as i64 - if from == 0 { 0 } else { sample_bits(from) as i64 }; + if from == 0 { + bits += 2 + 6 * scalefactors_sent(plan.scfsi[sb]) as i64; + } + bits + }; + let mut blocked = vec![[false; SUBBANDS]; nch]; + loop { + // the subband whose noise is furthest above its mask + let mut best: Option<(usize, usize, f32)> = None; + for (ch, plan) in plans.iter().enumerate() { + for sb in 0..self.sblimit { + let a = plan.alloc[sb]; + if a + 1 >= self.table.row(sb).len() || blocked[ch][sb] || plan.energy[sb] <= 0.0 { + continue; + } + let ratio = noise(plan, sb, a) / mask[ch][sb].max(1e-20); + if ratio > 1e-3 && best.is_none_or(|(_, _, r)| ratio > r) { + best = Some((ch, sb, ratio)); + } + } + } + let Some((ch, sb, _)) = best else { break }; + let plan = &mut plans[ch]; + let c = cost(plan, sb, plan.alloc[sb]); + if c <= bits_left { + bits_left -= c; + plan.alloc[sb] += 1; + } else { + blocked[ch][sb] = true; + } + } + } + + fn write_frame(&mut self, sub: &[[[f32; SUBBANDS]; 36]], out: &mut Vec) { + let nch = self.cfg.channels; + // frame length: 144 bytes per kbit/s over the sampling rate, plus a slot when the + // remainder has added up to one + let rate = u64::from(self.cfg.sample_rate); + let exact = 144 * u64::from(self.cfg.bitrate_kbps) * 1000; + self.pad_acc += exact % rate; + let pad = self.pad_acc >= rate; + if pad { + self.pad_acc -= rate; + } + let frame_bytes = (exact / rate) as usize + usize::from(pad); + + let mut plans: Vec = sub.iter().map(|s| self.analyse(s)).collect(); + self.allocate(&mut plans, frame_bytes as i64 * 8 - 32); + + let mut w = BitWriter::new(); + w.write_bits(0xFFF, 12); + w.write_bits(u32::from(!self.lsf), 1); + w.write_bits(0b10, 2); // Layer II + w.write_bits(1, 1); // no CRC + w.write_bits(self.br_index, 4); + w.write_bits(self.sr_index, 2); + w.write_bits(u32::from(pad), 1); + w.write_bits(0, 1); // private + w.write_bits(if nch == 1 { 3 } else { 0 }, 2); // mono or stereo + w.write_bits(0, 2); // mode extension + w.write_bits(0, 1); // copyright + w.write_bits(1, 1); // original + w.write_bits(0, 2); // emphasis + for sb in 0..self.sblimit { + let nbal = self.table.row(sb).len().trailing_zeros(); + for plan in &plans { + w.write_bits(plan.alloc[sb] as u32, nbal); + } + } + for sb in 0..self.sblimit { + for plan in &plans { + if plan.alloc[sb] != 0 { + w.write_bits(plan.scfsi[sb], 2); + } + } + } + for sb in 0..self.sblimit { + for plan in &plans { + if plan.alloc[sb] == 0 { + continue; + } + let [a, b, c] = plan.sf[sb]; + match plan.scfsi[sb] { + 0 => [a, b, c].iter().for_each(|&s| w.write_bits(s, 6)), + 1 => [a, c].iter().for_each(|&s| w.write_bits(s, 6)), + 2 => w.write_bits(a, 6), + _ => [a, b].iter().for_each(|&s| w.write_bits(s, 6)), + } + } + } + for gr in 0..12 { + let part = gr / 4; + for sb in 0..self.sblimit { + for (ch, plan) in plans.iter().enumerate() { + let a = plan.alloc[sb]; + let steps = self.table.row(sb).get(a).copied().unwrap_or(0); + if steps == 0 { + continue; + } + let scale = tables::scalefactor(plan.sf[sb][part]); + let n = u32::from(steps); + let code = |k: usize| -> u32 { + let x = (sub[ch][3 * gr + k][sb] / scale).clamp(-1.0, 1.0); + // the reconstruction points are (2v + 1 - n) / n + ((x * n as f32 + n as f32 - 1.0) / 2.0).round().clamp(0.0, (n - 1) as f32) as u32 + }; + let v = [code(0), code(1), code(2)]; + match tables::grouping(steps) { + Some(bits) => w.write_bits(v[0] + n * v[1] + n * n * v[2], bits), + None => { + let nb = (n + 1).trailing_zeros(); + v.iter().for_each(|&x| w.write_bits(x, nb)); + } + } + } + } + } + let mut bytes = w.finish(); + bytes.resize(frame_bytes, 0); + out.extend_from_slice(&bytes); + } +} diff --git a/crates/audio/src/mpa/mod.rs b/crates/audio/src/mpa/mod.rs index 70adcfd13..09560c9d4 100644 --- a/crates/audio/src/mpa/mod.rs +++ b/crates/audio/src/mpa/mod.rs @@ -13,12 +13,30 @@ //! format (bit rate index 0, whose frame length is only known from the next sync word) and the //! CRC (read, not checked, like most decoders). //! +//! # Encoder (feature `mpa-encode`) +//! +//! [`encoder::Encoder`] writes Layer II streams, written from ISO/IEC 11172-3 (§2.4.1.6 bit stream +//! syntax, Annex B tables, Annex C encoding process) and ISO/IEC 13818-3. +//! +//! - Constant bit rate: 32-192 kbit/s mono and 64-384 kbit/s stereo at 32 / 44.1 / 48 kHz (the +//! rate and mode pairs of Table 3-B.2), 8-160 kbit/s at 16 / 22.05 / 24 kHz. Mono, or stereo with +//! each channel allocated on its own (no joint stereo, no dual channel). +//! - The polyphase analysis filterbank of Annex C.1.3 (shared with the Layer III encoder), a +//! scalefactor per 12 samples with the `scfsi` sharing of §2.4.1.6, and a bit allocation chosen by +//! spending the frame's bits where the quantization noise is furthest above a simple masking +//! estimate (the band energies spread over the neighbouring subbands, never below the threshold +//! in quiet). It is not one of the psychoacoustic models of Annex D. +//! - Output: frames only, no CRC, no ID3 tag. Frames written one after another are a playable +//! `.mp2` file. A decoder's output lags the input by [`encoder::DELAY`] samples. +//! //! From FilmCraft's `filmcraft-mpa` (storytold/filmcraft@8fda2f2). Public items keep their names, so //! FilmCraft can re-export this module. // Index loops follow the specification's pseudo-code (FilmCraft allows this lint workspace-wide). #![allow(clippy::needless_range_loop)] +#[cfg(feature = "mpa-encode")] +pub mod encoder; pub(crate) mod tables; use craft_media::bitstream::BitReader; diff --git a/crates/audio/src/read/wav.rs b/crates/audio/src/read/wav.rs index c1552d7e2..2cc520278 100644 --- a/crates/audio/src/read/wav.rs +++ b/crates/audio/src/read/wav.rs @@ -252,12 +252,25 @@ struct DataChunk { declared: u64, } +/// Ids of the chunks that commonly follow a `data` chunk: metadata a writer appends after the +/// samples, sometimes without correcting the RIFF size. +const TRAILING_IDS: [&[u8; 4]; 12] = [b"LIST", b"fact", b"id3 ", b"ID3 ", b"cue ", b"JUNK", b"PEAK", b"bext", b"smpl", b"iXML", b"inst", b"PAD "]; + /// Bytes of audio a `data` chunk holds: leniently, whatever is present when the size is wrong or /// the recording was never finalised. +/// +/// A size of 0 is an empty chunk when only whole chunks follow it and either the RIFF size is the +/// file's or the first of them has an id that follows audio (#2123: a `LIST` chunk appended after +/// the RIFF size was written). Otherwise it is a recording that was never finalised, and what +/// follows is audio: the bytes of PCM can spell any id, but rarely whole chunks to the end. fn data_chunk_len(src: &Src<'_>, c: DataChunk) -> u64 { + if c.size32 != 0 || c.is_rf64 { + return c.declared.min(c.remaining); + } let finished = u64::from(src.le_u32(4).unwrap_or(0)) + 8 == src.size(); - let empty = c.size32 == 0 && !c.is_rf64 && finished && only_chunks_follow(src, c.body); - if c.size32 == 0 && !c.is_rf64 && !empty { c.remaining } else { c.declared.min(c.remaining) } + let metadata_follows = src.tag(c.body).is_some_and(|id| TRAILING_IDS.contains(&&id)); + let empty = (finished || metadata_follows) && only_chunks_follow(src, c.body); + if empty { 0 } else { c.remaining } } /// The sample layout of a `fmt` chunk, `None` for a format we do not read natively. diff --git a/crates/audio/src/vmd.rs b/crates/audio/src/vmd.rs new file mode 100644 index 000000000..9e45b1a5c --- /dev/null +++ b/crates/audio/src/vmd.rs @@ -0,0 +1,192 @@ +//! Sierra VMD sound decoder (feature `vmd-decode`): the 8-bit PCM and 16-bit DPCM sound of VMD +//! (Video and Music Data) files, as in Sierra's and Coktel Vision's 1990s games. +//! +//! Clean-room, from the public format description at +//! ("Description of the Sierra Video and Music Data (VMD) Format", Mike Melanson and Vladimir +//! Gneushev). The description gives the coding but not the size of a block; the sizes here are +//! what ffmpeg was seen to expect of files made by this crate's tests: +//! +//! | Sound | Bytes in a block of `n` samples a channel | +//! |---|---| +//! | 8-bit | `n` for each channel, interleaved | +//! | 16-bit | 2 for each channel's first sample, then one code for each further sample, interleaved | +//! +//! The header's frame length is `n`, except in old-style stereo (audio flag 0x8000), where it +//! counts both channels. Old-style 16-bit stereo blocks begin with their first samples like the +//! others, which is what ffmpeg reads; the description says they carry the last block's samples +//! over instead. No such file was at hand to settle it. +//! +//! A [`Decoder`] is made from the 816-byte file header. [`Decoder::decode`] takes a sound +//! frame's flags (from its record in the file's table of contents; `craft_media::vmd` reads it) +//! and its data, and returns interleaved `i16` samples: one block of sound or silence, or, for a +//! frame with a silence mask (the first sound frame of a file), several. 8-bit samples are widened to 16 bits. Blocks do not depend +//! on each other, so decoding can start at any frame. +//! +//! Not decoded: IMA ADPCM sound (audio flag 0x10) and the external codecs of later Coktel Vision +//! files ([`Error::Unsupported`]). +//! +//! Input is treated as hostile: a block is at most 65 535 samples a channel and is decoded only +//! if all of it is there; a frame with a silence mask yields at most 32 blocks (the width of +//! the mask), any other frame as many whole blocks as its data holds. No `unsafe`, no panics. + +#![warn(missing_docs)] + +/// Bytes of the VMD file header a [`Decoder`] is made from. +pub const HEADER_LEN: usize = 816; + +/// Errors from decoding VMD sound. +#[non_exhaustive] +#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)] +pub enum Error { + /// The header or a frame is not valid. + #[error("invalid VMD sound: {0}")] + Invalid(&'static str), + /// Valid, but not something this decoder handles. + #[error("unsupported VMD sound: {0}")] + Unsupported(&'static str), +} + +/// The steps of the 16-bit coding: a code's low seven bits pick one, its top bit the sign. +const STEPS: [u16; 128] = [ + 0, 8, 16, 32, 48, 64, 80, 96, 112, 128, 144, 160, 176, 192, 208, 224, 240, 256, 272, 288, 304, 320, 336, 352, 368, 384, 400, 416, 432, 448, 464, + 480, 496, 512, 520, 528, 536, 544, 552, 560, 568, 576, 584, 592, 600, 608, 616, 624, 632, 640, 648, 656, 664, 672, 680, 688, 696, 704, 712, 720, + 728, 736, 744, 752, 760, 768, 776, 784, 792, 800, 808, 816, 824, 832, 840, 848, 856, 864, 872, 880, 888, 896, 904, 912, 920, 928, 936, 944, 952, + 960, 968, 976, 984, 992, 1000, 1008, 1016, 1024, 1088, 1152, 1216, 1280, 1344, 1408, 1472, 1536, 1600, 1664, 1728, 1792, 1856, 1920, 1984, 2048, + 2304, 2560, 2816, 3072, 3328, 3584, 3840, 4096, 5120, 6144, 7168, 8192, 12288, 16384, +]; + +/// A VMD sound decoder. +#[derive(Clone, Debug)] +pub struct Decoder { + sample_rate: u32, + channels: usize, + sixteen_bit: bool, + /// Samples of one block, all channels counted. + block_total: usize, +} + +impl Decoder { + /// A decoder for the file whose header is `header` (its first 816 bytes; more are ignored). + pub fn new(header: &[u8]) -> Result { + let h = header.get(..HEADER_LEN).ok_or(Error::Invalid("the header is shorter than 816 bytes"))?; + let u16_at = |at: usize| u16::from_le_bytes([h[at], h[at + 1]]); + if usize::from(u16_at(0)) != HEADER_LEN - 2 { + return Err(Error::Invalid("not a VMD header")); + } + if u16_at(16) & 0x1000 == 0 || u16_at(804) == 0 { + return Err(Error::Invalid("the file has no sound")); + } + let flags = u16_at(810); + if flags & 0x10 != 0 { + return Err(Error::Unsupported("IMA ADPCM sound")); + } + let length = u16_at(806) as i16; + let frame_length = usize::from(length.unsigned_abs()); + // old-style stereo counts both channels, new-style one + let (channels, block_total) = match flags { + f if f & 0x8000 != 0 => (2, frame_length & !1), + f if f & 0x200 != 0 => (2, frame_length * 2), + _ => (1, frame_length), + }; + Ok(Decoder { sample_rate: u32::from(u16_at(804)), channels, sixteen_bit: length < 0, block_total }) + } + + /// Samples a second. + pub fn sample_rate(&self) -> u32 { + self.sample_rate + } + + /// 1 or 2. + pub fn channels(&self) -> usize { + self.channels + } + + /// Bits a sample in the file: 8 (PCM) or 16 (DPCM). The decoder returns `i16` for both. + pub fn bits(&self) -> u8 { + if self.sixteen_bit { 16 } else { 8 } + } + + /// Samples of one block for each channel. + pub fn block_samples(&self) -> usize { + self.block_total / self.channels + } + + /// Bytes of one block of sound in a frame. + pub fn block_bytes(&self) -> usize { + if self.sixteen_bit { (self.block_total + self.channels).min(self.block_total * 2) } else { self.block_total } + } + + /// Decode one sound frame: `flags` is the frame's flag byte from its record, `data` the + /// frame data. Returns interleaved samples, [`Decoder::block_samples`] for each channel and + /// block. + /// + /// - flags 1: one block of sound (every whole block, if the frame holds more); + /// - flags 2: a 32-bit mask, then blocks of sound: the sound a player loads ahead at the + /// start of a file. From bit 0 up, a set bit is a block of silence and a clear bit the next + /// block of data, while there is one. ffmpeg plays the silent blocks first instead; + /// the order here is the description's; + /// - flags 3: one block of silence. + /// + /// An empty frame gives no samples. With flags 1, a first block cut short is an error. A part + /// of a block after the last whole one is left out, with flags 1 and 2. + /// + /// The sound of a file is its sound frames decoded in file order and played end to end from + /// the first picture on: see `craft_media::vmd` for how that lines up with the pictures. + pub fn decode(&self, flags: u8, data: &[u8]) -> Result, Error> { + let mut out = Vec::new(); + match flags { + 3 => out.resize(self.block_total, 0), + 1 | 2 if data.is_empty() => {} + 1 => { + // one block; a frame that holds more whole blocks plays them all, as in ffmpeg + self.block(data, &mut out)?; + let size = self.block_bytes(); + if size > 0 { + for more in data[size..].chunks_exact(size) { + self.block(more, &mut out)?; + } + } + } + 2 => { + let (mask, mut data) = data.split_first_chunk::<4>().ok_or(Error::Invalid("the silence mask is cut short"))?; + let mask = u32::from_le_bytes(*mask); + // bit by bit: a set bit is a silent block, a clear one takes the next block of data + // while there is one. The header's buffer count is not needed: game files hold + // one block fewer than it says. + for i in 0..32 { + if mask >> i & 1 == 1 { + out.resize(out.len() + self.block_total, 0); + } else if !data.is_empty() && data.len() >= self.block_bytes() { + self.block(data, &mut out)?; + data = &data[self.block_bytes()..]; + } + } + } + _ => return Err(Error::Unsupported("unknown sound frame flags")), + } + Ok(out) + } + + /// Decode the block at the start of `data` onto `out`. + fn block(&self, data: &[u8], out: &mut Vec) -> Result<(), Error> { + let data = data.get(..self.block_bytes()).ok_or(Error::Invalid("a block of sound is cut short"))?; + if !self.sixteen_bit { + out.extend(data.iter().map(|&b| (i16::from(b) - 0x80) << 8)); + return Ok(()); + } + // each channel's first sample as it is, then a signed step for each further sample + let mut last = [0i32; 2]; + let Some((first, codes)) = data.split_at_checked(self.channels * 2) else { return Ok(()) }; + for (ch, s) in first.as_chunks::<2>().0.iter().enumerate() { + last[ch] = i32::from(i16::from_le_bytes(*s)); + out.push(last[ch] as i16); + } + for (i, &code) in codes.iter().enumerate() { + let ch = i % self.channels; + let step = i32::from(STEPS[usize::from(code & 0x7F)]); + last[ch] = (if code & 0x80 != 0 { last[ch] - step } else { last[ch] + step }).clamp(-32768, 32767); + out.push(last[ch] as i16); + } + Ok(()) + } +} diff --git a/crates/audio/src/vorbis/decoder/bits.rs b/crates/audio/src/vorbis/decoder/bits.rs new file mode 100644 index 000000000..6735d3d3d --- /dev/null +++ b/crates/audio/src/vorbis/decoder/bits.rs @@ -0,0 +1,96 @@ +//! The Vorbis bit reader (Vorbis I §2): bits are taken least significant first from each byte. + +/// Reading past the end of the packet ("end-of-packet", §2.1.8). +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub(super) struct Eop; + +pub(super) struct BitReader<'a> { + data: &'a [u8], + /// The position of the next bit. + pos: usize, +} + +impl<'a> BitReader<'a> { + pub(super) fn new(data: &'a [u8]) -> Self { + Self { data, pos: 0 } + } + + /// The bits not yet read. + pub(super) fn remaining(&self) -> usize { + (self.data.len() * 8).saturating_sub(self.pos) + } + + /// Read `n` (at most 32) bits as an unsigned integer. A read that does not fit takes nothing. + pub(super) fn read(&mut self, n: u32) -> Result { + if n == 0 { + return Ok(0); + } + if (n as usize) > self.remaining() { + self.pos = self.data.len() * 8; + return Err(Eop); + } + let mut value = 0u64; + let mut got = 0u32; + while got < n { + let byte = u64::from(self.data[self.pos / 8]); + let shift = (self.pos % 8) as u32; + let take = (8 - shift).min(n - got); + value |= ((byte >> shift) & ((1 << take) - 1)) << got; + got += take; + self.pos += take as usize; + } + Ok(value as u32) + } + + pub(super) fn bit(&mut self) -> Result { + Ok(self.read(1)? == 1) + } +} + +/// `ilog(x)` (§9.2.1): the position of the highest set bit, 0 for values below 1. +pub(super) fn ilog(x: i64) -> u32 { + if x <= 0 { 0 } else { 64 - (x as u64).leading_zeros() } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn reads_least_significant_bit_first() { + // Fields come out of each byte from its least significant bit. + let mut r = BitReader::new(&[0xFC, 0x08]); + assert_eq!(r.read(4), Ok(0xC)); + assert_eq!(r.read(4), Ok(0xF)); + assert_eq!(r.read(1), Ok(0)); + assert_eq!(r.read(3), Ok(4)); + assert_eq!(r.read(4), Ok(0)); + assert_eq!(r.read(1), Err(Eop)); + } + + #[test] + fn wide_reads_span_bytes_and_zero_bits_are_free() { + let mut r = BitReader::new(&[0x01, 0x02, 0x03, 0x04, 0x05]); + assert_eq!(r.read(0), Ok(0)); + assert_eq!(r.read(32), Ok(0x0403_0201)); + assert_eq!(r.read(8), Ok(5)); + assert_eq!(r.read(0), Ok(0)); + assert_eq!(r.read(1), Err(Eop)); + assert_eq!(r.remaining(), 0); + } + + #[test] + fn a_failed_read_consumes_the_rest() { + let mut r = BitReader::new(&[0xFF]); + assert_eq!(r.read(3), Ok(7)); + assert_eq!(r.read(6), Err(Eop)); + assert_eq!(r.read(1), Err(Eop)); + } + + #[test] + fn ilog_matches_the_specification_examples() { + for (x, want) in [(0, 0), (1, 1), (2, 2), (3, 2), (4, 3), (7, 3), (-5, 0), (255, 8), (256, 9)] { + assert_eq!(ilog(x), want, "ilog({x})"); + } + } +} diff --git a/crates/audio/src/vorbis/decoder/codebook.rs b/crates/audio/src/vorbis/decoder/codebook.rs new file mode 100644 index 000000000..9d083c9e4 --- /dev/null +++ b/crates/audio/src/vorbis/decoder/codebook.rs @@ -0,0 +1,409 @@ +//! Codebooks (Vorbis I §3): a Huffman code over entry numbers and an optional table of vectors. + +use super::Error; +use super::bits::{BitReader, Eop, ilog}; + +const NONE: u32 = u32::MAX; +const LEAF: u32 = 1 << 31; +/// Entries a codebook may declare. +const MAX_ENTRIES: u32 = 1 << 20; +/// Nodes of one codeword tree. +const MAX_NODES: usize = 1 << 22; + +#[derive(Clone, Copy)] +struct Node { + child: [u32; 2], + full: bool, +} + +pub(super) struct Codebook { + pub(super) dimensions: usize, + pub(super) entries: usize, + tree: Vec, + /// The only used entry of a single-entry book. + single: Option, + /// `entries * dimensions` values when the book has a lookup table. + vectors: Vec, +} + +/// `float32_unpack` (§9.2.2). +fn float32_unpack(x: u32) -> f64 { + let mantissa = f64::from(x & 0x001F_FFFF); + let exponent = ((x & 0x7FE0_0000) >> 21) as i32; + let m = if x & 0x8000_0000 != 0 { -mantissa } else { mantissa }; + m * 2f64.powi(exponent - 788) +} + +/// `lookup1_values` (§9.2.3): the greatest `v` with `v^dimensions <= entries`. +fn lookup1_values(entries: u32, dimensions: u32) -> u32 { + let mut v = 1u32; + loop { + let next = u128::from(v) + 1; + let mut p = 1u128; + for _ in 0..dimensions { + p *= next; + if p > u128::from(entries) { + return v; + } + } + v += 1; + } +} + +fn insert(tree: &mut Vec, at: usize, depth: u32, len: u32, entry: u32) -> bool { + for b in 0..2 { + let child = tree[at].child[b]; + if depth + 1 == len { + if child == NONE { + tree[at].child[b] = LEAF | entry; + refresh(tree, at); + return true; + } + continue; + } + if child == NONE { + if tree.len() >= MAX_NODES { + return false; + } + tree.push(Node { child: [NONE; 2], full: false }); + let new = tree.len() - 1; + tree[at].child[b] = new as u32; + if insert(tree, new, depth + 1, len, entry) { + refresh(tree, at); + return true; + } + return false; + } + if child & LEAF != 0 || tree[child as usize].full { + continue; + } + if insert(tree, child as usize, depth + 1, len, entry) { + refresh(tree, at); + return true; + } + } + false +} + +fn refresh(tree: &mut [Node], at: usize) { + let done = |c: u32, t: &[Node]| c != NONE && (c & LEAF != 0 || t[c as usize].full); + let full = done(tree[at].child[0], tree) && done(tree[at].child[1], tree); + tree[at].full = full; +} + +impl Codebook { + /// Read one codebook from a setup header. `budget` is the bytes the setup's codebooks may + /// still take in all. + pub(super) fn read(r: &mut BitReader<'_>, budget: &mut usize) -> Result { + let bad = |m: &'static str| Error::Setup(m); + let eop = |_: Eop| Error::Setup("setup header ends inside a codebook"); + if r.read(24).map_err(eop)? != 0x0056_4342 { + return Err(bad("codebook sync pattern missing")); + } + let dimensions = r.read(16).map_err(eop)?; + let entries = r.read(24).map_err(eop)?; + if dimensions == 0 || entries == 0 || entries > MAX_ENTRIES { + return Err(bad("codebook with no dimensions, no entries or too many")); + } + let mut lengths: Vec = Vec::with_capacity(entries as usize); + if r.bit().map_err(eop)? { + // Ordered: the number of codewords of each length. + let mut current = 0u32; + let mut len = r.read(5).map_err(eop)? + 1; + while current < entries { + let number = r.read(ilog(i64::from(entries - current))).map_err(eop)?; + if number > entries - current || len > 32 { + return Err(bad("ordered codebook lengths overrun the entries")); + } + lengths.extend(std::iter::repeat_n(len as u8, number as usize)); + current += number; + len += 1; + } + } else { + let sparse = r.bit().map_err(eop)?; + for _ in 0..entries { + if sparse && !r.bit().map_err(eop)? { + lengths.push(0); + } else { + lengths.push((r.read(5).map_err(eop)? + 1) as u8); + } + } + } + + // The codeword tree. + let used = lengths.iter().filter(|&&l| l != 0).count(); + let mut tree = vec![Node { child: [NONE; 2], full: false }]; + let mut single = None; + if used == 1 { + let entry = lengths.iter().position(|&l| l != 0).unwrap_or(0); + if lengths[entry] != 1 { + return Err(bad("a codebook with one used entry must give it length 1")); + } + single = Some(entry as u32); + } else if used > 1 { + for (entry, &len) in lengths.iter().enumerate() { + if len != 0 && !insert(&mut tree, 0, 0, u32::from(len), entry as u32) { + return Err(bad("overspecified codebook")); + } + } + if !tree[0].full { + return Err(bad("underspecified codebook")); + } + } + let tree_bytes = tree.len() * std::mem::size_of::(); + if tree_bytes > *budget { + return Err(Error::Limit("the codebooks are too large")); + } + *budget -= tree_bytes; + + // The lookup table. + let lookup_type = r.read(4).map_err(eop)?; + let mut vectors = Vec::new(); + if lookup_type > 2 { + return Err(bad("reserved codebook lookup type")); + } + if lookup_type != 0 { + let minimum = float32_unpack(r.read(32).map_err(eop)?); + let delta = float32_unpack(r.read(32).map_err(eop)?); + let value_bits = r.read(4).map_err(eop)? + 1; + let sequence = r.bit().map_err(eop)?; + // Check before multiplying or reading multiplicands: the product can overflow + // usize on 32-bit targets, and a type-2 table otherwise allocates before admission. + let total = (entries as usize) + .checked_mul(dimensions as usize) + .filter(|&n| n <= *budget / std::mem::size_of::()) + .ok_or(Error::Limit("the codebooks' vector tables are too large"))?; + let values = if lookup_type == 1 { lookup1_values(entries, dimensions) as usize } else { total }; + if !minimum.is_finite() || !delta.is_finite() || values > r.remaining() / value_bits as usize { + return Err(bad("codebook lookup table is damaged or truncated")); + } + let multiplicands: Vec = (0..values).map(|_| r.read(value_bits).unwrap_or(0)).collect(); + *budget -= total * std::mem::size_of::(); + vectors = vec![0f32; total]; + for e in 0..entries as usize { + let out = &mut vectors[e * dimensions as usize..(e + 1) * dimensions as usize]; + let mut last = 0f64; + let mut divisor = 1usize; + for (i, slot) in out.iter_mut().enumerate() { + let m = if lookup_type == 1 { + let at = (e / divisor) % values; + divisor = divisor.saturating_mul(values); + multiplicands[at] + } else { + multiplicands[e * dimensions as usize + i] + }; + let v = f64::from(m) * delta + minimum + last; + if sequence { + last = v; + } + *slot = v as f32; + } + } + } + Ok(Self { dimensions: dimensions as usize, entries: entries as usize, tree, single, vectors }) + } + + /// Whether the book has a lookup table. + pub(super) fn has_vectors(&self) -> bool { + !self.vectors.is_empty() + } + + /// Read a codeword; the entry number (scalar context). + pub(super) fn scalar(&self, r: &mut BitReader<'_>) -> Result { + if let Some(e) = self.single { + r.read(1)?; + return Ok(e); + } + let mut at = 0usize; + loop { + let c = self.tree[at].child[usize::from(r.bit()?)]; + if c == NONE { + return Err(Eop); + } + if c & LEAF != 0 { + return Ok(c & !LEAF); + } + at = c as usize; + } + } + + /// Read a codeword and return its vector (VQ context); `None` for a book without a table. + pub(super) fn vector(&self, r: &mut BitReader<'_>) -> Result, Eop> { + let e = self.scalar(r)? as usize; + Ok(self.vectors.get(e * self.dimensions..(e + 1) * self.dimensions)) + } +} + +#[cfg(test)] +mod tests { + use super::*; + + /// Pack fields least significant bit first. + struct W(Vec, usize); + impl W { + fn put(&mut self, v: u64, n: u32) { + for i in 0..n { + if self.1.is_multiple_of(8) { + self.0.push(0); + } + let last = self.0.len() - 1; + self.0[last] |= (((v >> i) & 1) as u8) << (self.1 % 8); + self.1 += 1; + } + } + } + + fn book_bytes(lengths: &[u32], lookup: Option<(u32, u32, &[u32])>) -> Vec { + let mut w = W(Vec::new(), 0); + w.put(0x56_4342, 24); + w.put(1, 16); + w.put(lengths.len() as u64, 24); + w.put(0, 1); // not ordered + w.put(0, 1); // not sparse + for &l in lengths { + w.put(u64::from(l - 1), 5); + } + match lookup { + None => w.put(0, 4), + Some((ty, bits, mult)) => { + w.put(u64::from(ty), 4); + w.put(0, 32); // minimum: 0.0 + w.put(0, 32); + w.put(u64::from(bits - 1), 4); + w.put(0, 1); + for &m in mult { + w.put(u64::from(m), bits); + } + } + } + w.0 + } + + #[test] + fn the_specification_example_assigns_its_codewords() { + // §3.2.1: lengths 2 4 4 4 4 2 3 3 -> 00, 0100, 0101, 0110, 0111, 10, 110, 111. + let bytes = book_bytes(&[2, 4, 4, 4, 4, 2, 3, 3], None); + let mut budget = 1 << 26; + let book = Codebook::read(&mut BitReader::new(&bytes), &mut budget).expect("book"); + let code = |bits: &[u8]| { + let mut w = W(Vec::new(), 0); + for &b in bits { + w.put(u64::from(b), 1); + } + let mut r = BitReader::new(&w.0); + book.scalar(&mut r).expect("entry") + }; + assert_eq!(code(&[0, 0]), 0); + assert_eq!(code(&[0, 1, 0, 0]), 1); + assert_eq!(code(&[0, 1, 1, 1]), 4); + assert_eq!(code(&[1, 0]), 5); + assert_eq!(code(&[1, 1, 0]), 6); + assert_eq!(code(&[1, 1, 1]), 7); + } + + #[test] + fn over_and_underspecified_books_are_errors() { + let mut budget = 1 << 26; + let over = book_bytes(&[1, 1, 1], None); + assert!(Codebook::read(&mut BitReader::new(&over), &mut budget).is_err()); + let under = book_bytes(&[2, 2, 2], None); + assert!(Codebook::read(&mut BitReader::new(&under), &mut budget).is_err()); + } + + #[test] + fn a_single_entry_book_sinks_one_bit_of_either_value() { + let mut budget = 1 << 26; + let bytes = book_bytes(&[1], None); + let book = Codebook::read(&mut BitReader::new(&bytes), &mut budget).expect("book"); + for byte in [0u8, 1] { + let data = [byte]; + let mut r = BitReader::new(&data); + assert_eq!(book.scalar(&mut r), Ok(0)); + assert_eq!(r.remaining(), 7); + } + let bad = book_bytes(&[2], None); + assert!(Codebook::read(&mut BitReader::new(&bad), &mut budget).is_err()); + } + + #[test] + fn lookup_type_one_builds_a_lattice() { + // 4 entries, 2 dimensions, 2 values per dimension: minimum 0 and delta 1 in the packed + // float format are written below by hand (mantissa 1, exponent 788 -> 1.0). + let mut w = W(Vec::new(), 0); + w.put(0x56_4342, 24); + w.put(2, 16); + w.put(4, 24); + w.put(0, 1); + w.put(0, 1); + for _ in 0..4 { + w.put(1, 5); // length 2 each + } + w.put(1, 4); // lookup type 1 + w.put(0, 32); // minimum 0 + w.put((788u64 << 21) | 1, 32); // delta 1.0 + w.put(0, 4); // 1 bit per value + w.put(0, 1); + w.put(0b10, 2); // multiplicands 0, 1 + let mut budget = 1 << 26; + let book = Codebook::read(&mut BitReader::new(&w.0), &mut budget).expect("book"); + assert_eq!(lookup1_values(4, 2), 2); + // Entry e is (m[e % 2], m[(e / 2) % 2]). + assert_eq!(book.vectors, vec![0.0, 0.0, 1.0, 0.0, 0.0, 1.0, 1.0, 1.0]); + } + + #[test] + fn vector_budget_is_checked_before_reading_lookup_values() { + // A valid single-entry tree, but two values exceed the remaining budget. + // No multiplicands follow: admission must reject it before reading them. + for lookup in [1, 2] { + let mut w = W(Vec::new(), 0); + w.put(0x56_4342, 24); + w.put(2, 16); + w.put(1, 24); + w.put(0, 1); + w.put(0, 1); + w.put(0, 5); + w.put(lookup, 4); + w.put(0, 32); + w.put(0, 32); + w.put(15, 4); + w.put(0, 1); + let mut budget = std::mem::size_of::() + 4; + assert!(matches!(Codebook::read(&mut BitReader::new(&w.0), &mut budget), Err(Error::Limit(_)))); + } + } + + #[test] + fn vector_size_that_overflows_32_bits_is_refused() { + for lookup in [1, 2] { + let mut w = W(Vec::new(), 0); + w.put(0x56_4342, 24); + w.put(65535, 16); + w.put(65538, 24); // product is above u32::MAX + w.put(0, 1); // unordered + w.put(1, 1); // sparse: only one entry is used + w.put(1, 1); + w.put(0, 5); // length 1 + for _ in 1..65538 { + w.put(0, 1); + } + w.put(lookup, 4); + w.put(0, 32); + w.put(0, 32); + w.put(0, 4); + w.put(0, 1); + w.put(0, 1); // lookup type 1's single multiplicand + let mut budget = 256 << 20; + assert!(matches!(Codebook::read(&mut BitReader::new(&w.0), &mut budget), Err(Error::Limit(_)))); + } + } + + #[test] + fn helper_functions() { + assert_eq!(float32_unpack((788u32 << 21) | 5), 5.0); + assert_eq!(float32_unpack(0x8000_0000 | (789u32 << 21) | 3), -6.0); + for (entries, dims, want) in [(8, 3, 2), (9, 2, 3), (1, 5, 1), (10, 1, 10), (1000, 3, 10), (4_000_000, 2, 2000)] { + assert_eq!(lookup1_values(entries, dims), want, "{entries} entries, {dims} dims"); + } + } +} diff --git a/crates/audio/src/vorbis/decoder/floor.rs b/crates/audio/src/vorbis/decoder/floor.rs new file mode 100644 index 000000000..bc6ce4e36 --- /dev/null +++ b/crates/audio/src/vorbis/decoder/floor.rs @@ -0,0 +1,385 @@ +//! Floors (Vorbis I §6 and §7): the spectral envelope each channel's residue is multiplied by. + +use super::Error; +use super::bits::{BitReader, Eop, ilog}; +use super::codebook::Codebook; +use super::tables::INVERSE_DB; + +/// Why a floor could not be decoded from a packet. +pub(super) enum Fail { + /// The packet ended (a nominal event: the channel is silent). + Eop, + /// The packet names a codebook that does not exist: it cannot be decoded (§6.2.2). + Invalid, +} + +impl From for Fail { + fn from(_: Eop) -> Self { + Fail::Eop + } +} + +/// What a decoded floor gives to synthesis. +pub(super) enum FloorData { + One { y: Vec, step2: Vec }, + Zero { amplitude: u32, coefficients: Vec }, +} + +pub(super) struct Floor0 { + order: usize, + rate: u32, + bark_map_size: u32, + amplitude_bits: u32, + amplitude_offset: u32, + books: Vec, +} + +pub(super) struct Floor1 { + partition_class: Vec, + class_dimensions: Vec, + class_subclasses: Vec, + class_masterbook: Vec, + subclass_books: Vec>, + multiplier: i32, + range: i32, + xlist: Vec, + /// `(low, high)` neighbour positions of each X from index 2 on. + neighbours: Vec<(usize, usize)>, + /// Indices of `xlist` in ascending X order. + sorted: Vec, +} + +pub(super) enum Floor { + Zero(Floor0), + One(Floor1), +} + +fn eop(_: Eop) -> Error { + Error::Setup("setup header ends inside a floor") +} + +impl Floor { + pub(super) fn read(floor_type: u32, r: &mut BitReader<'_>, books: &[Codebook]) -> Result { + match floor_type { + 0 => { + let order = r.read(8).map_err(eop)? as usize; + let rate = r.read(16).map_err(eop)?; + let bark_map_size = r.read(16).map_err(eop)?; + let amplitude_bits = r.read(6).map_err(eop)?; + let amplitude_offset = r.read(8).map_err(eop)?; + let count = r.read(4).map_err(eop)? as usize + 1; + let mut list = Vec::with_capacity(count); + for _ in 0..count { + let b = r.read(8).map_err(eop)? as usize; + match books.get(b) { + Some(book) if book.has_vectors() => list.push(b), + _ => return Err(Error::Setup("floor 0 names a missing codebook or one without vectors")), + } + } + if order == 0 || rate == 0 || bark_map_size == 0 || amplitude_bits > 32 { + return Err(Error::Setup("floor 0 with a zero order, rate or map size, or more than 32 amplitude bits")); + } + Ok(Self::Zero(Floor0 { order, rate, bark_map_size, amplitude_bits, amplitude_offset, books: list })) + } + 1 => { + let partitions = r.read(5).map_err(eop)? as usize; + let mut partition_class = Vec::with_capacity(partitions); + for _ in 0..partitions { + partition_class.push(r.read(4).map_err(eop)? as usize); + } + let classes = partition_class.iter().max().map_or(0, |m| m + 1); + let (mut class_dimensions, mut class_subclasses, mut class_masterbook, mut subclass_books) = (vec![], vec![], vec![], vec![]); + for _ in 0..classes { + class_dimensions.push(r.read(3).map_err(eop)? as usize + 1); + let subs = r.read(2).map_err(eop)?; + class_subclasses.push(subs); + let master = if subs != 0 { r.read(8).map_err(eop)? as usize } else { 0 }; + if subs != 0 && master >= books.len() { + return Err(Error::Setup("floor 1 master book out of range")); + } + class_masterbook.push(master); + let mut list = Vec::new(); + for _ in 0..(1u32 << subs) { + let b = r.read(8).map_err(eop)? as i32 - 1; + if b >= books.len() as i32 { + return Err(Error::Setup("floor 1 subclass book out of range")); + } + list.push(b); + } + subclass_books.push(list); + } + let multiplier = r.read(2).map_err(eop)? as i32 + 1; + let rangebits = r.read(4).map_err(eop)?; + let mut xlist = vec![0, 1i32 << rangebits]; + for &c in &partition_class { + for _ in 0..class_dimensions[c] { + xlist.push(r.read(rangebits).map_err(eop)? as i32); + } + } + if xlist.len() > 65 { + return Err(Error::Setup("floor 1 has more than 65 points")); + } + let mut seen = xlist.clone(); + seen.sort_unstable(); + if seen.windows(2).any(|w| w[0] == w[1]) { + return Err(Error::Setup("floor 1 repeats an X position")); + } + // Low and high neighbours (§9.2.4, §9.2.5) of each point, among those before it. + let mut neighbours = Vec::new(); + for i in 2..xlist.len() { + let (mut lo, mut hi) = (0usize, 1usize); + for j in 0..i { + if xlist[j] < xlist[i] && xlist[j] > xlist[lo] { + lo = j; + } + if xlist[j] > xlist[i] && xlist[j] < xlist[hi] { + hi = j; + } + } + neighbours.push((lo, hi)); + } + let mut sorted: Vec = (0..xlist.len()).collect(); + sorted.sort_by_key(|&i| xlist[i]); + let range = [256, 128, 86, 64][multiplier as usize - 1]; + Ok(Self::One(Floor1 { + partition_class, + class_dimensions, + class_subclasses, + class_masterbook, + subclass_books, + multiplier, + range, + xlist, + neighbours, + sorted, + })) + } + _ => Err(Error::Setup("unknown floor type")), + } + } + + /// Decode one channel's floor from a packet: `None` when the channel is unused this block. + pub(super) fn decode(&self, r: &mut BitReader<'_>, books: &[Codebook]) -> Result, Fail> { + match self { + Self::One(f) => Ok(f.decode(r, books)?), + Self::Zero(f) => f.decode(r, books), + } + } + + /// The floor curve over `n` bins (`n` is half the block size). + pub(super) fn curve(&self, data: &FloorData, n: usize) -> Vec { + match (self, data) { + (Self::One(f), FloorData::One { y, step2 }) => f.curve(y, step2, n), + (Self::Zero(f), FloorData::Zero { amplitude, coefficients }) => f.curve(*amplitude, coefficients, n), + _ => vec![0.0; n], + } + } +} + +/// `render_point` (§9.2.6). +fn render_point(x0: i32, y0: i32, x1: i32, y1: i32, x: i32) -> i32 { + let dy = i64::from(y1 - y0); + let adx = i64::from(x1 - x0); + let err = dy.abs() * i64::from(x - x0); + let off = (err / adx) as i32; + if dy < 0 { y0 - off } else { y0 + off } +} + +/// `render_line` (§9.2.7), writing the bins that fall inside `v`. +fn render_line(x0: i32, y0: i32, x1: i32, y1: i32, v: &mut [i32]) { + let dy = y1 - y0; + let adx = x1 - x0; + let base = dy / adx; + let ady = dy.abs() - base.abs() * adx; + let sy = if dy < 0 { base - 1 } else { base + 1 }; + let (mut y, mut err) = (y0, 0); + if let Some(slot) = usize::try_from(x0).ok().and_then(|x| v.get_mut(x)) { + *slot = y; + } + for x in x0 + 1..x1 { + err += ady; + if err >= adx { + err -= adx; + y += sy; + } else { + y += base; + } + match usize::try_from(x).ok().and_then(|x| v.get_mut(x)) { + Some(slot) => *slot = y, + None => break, + } + } +} + +impl Floor1 { + fn decode(&self, r: &mut BitReader<'_>, books: &[Codebook]) -> Result, Eop> { + if !r.bit()? { + return Ok(None); + } + let bits = ilog(i64::from(self.range) - 1); + let mut y = vec![0i32; self.xlist.len()]; + y[0] = r.read(bits)? as i32; + y[1] = r.read(bits)? as i32; + let mut offset = 2usize; + for &class in &self.partition_class { + let cdim = self.class_dimensions[class]; + let cbits = self.class_subclasses[class]; + let csub = (1u32 << cbits) - 1; + let mut cval = 0u32; + if cbits > 0 { + cval = books[self.class_masterbook[class]].scalar(r)?; + } + for j in 0..cdim { + let book = self.subclass_books[class][(cval & csub) as usize]; + cval >>= cbits; + y[offset + j] = if book >= 0 { books[book as usize].scalar(r)? as i32 } else { 0 }; + } + offset += cdim; + } + + // Step 1: amplitude synthesis (§7.2.4). + let mut step2 = vec![false; self.xlist.len()]; + step2[0] = true; + step2[1] = true; + let mut fin = y.clone(); + for i in 2..self.xlist.len() { + let (lo, hi) = self.neighbours[i - 2]; + let predicted = render_point(self.xlist[lo], fin[lo], self.xlist[hi], fin[hi], self.xlist[i]); + let val = y[i]; + let highroom = self.range - predicted; + let lowroom = predicted; + let room = if highroom < lowroom { highroom * 2 } else { lowroom * 2 }; + if val != 0 { + step2[lo] = true; + step2[hi] = true; + step2[i] = true; + fin[i] = if val >= room { + if highroom > lowroom { val - lowroom + predicted } else { predicted - val + highroom - 1 } + } else if val % 2 == 1 { + predicted - (val + 1) / 2 + } else { + predicted + val / 2 + }; + } else { + fin[i] = predicted; + } + // Valid setups never leave the range; a damaged one must not carry out-of-range values on. + fin[i] = fin[i].clamp(0, self.range - 1); + } + Ok(Some(FloorData::One { y: fin, step2 })) + } + + fn curve(&self, fin: &[i32], step2: &[bool], n: usize) -> Vec { + let mut floor = vec![0i32; n]; + let (mut hx, mut hy) = (0i32, 0i32); + let (mut lx, mut ly) = (0i32, fin[self.sorted[0]] * self.multiplier); + for &i in &self.sorted[1..] { + if step2[i] { + hy = fin[i] * self.multiplier; + hx = self.xlist[i]; + render_line(lx, ly, hx, hy, &mut floor); + lx = hx; + ly = hy; + } + } + if (hx as usize) < n { + render_line(hx, hy, n as i32, hy, &mut floor); + } + floor.iter().map(|&v| INVERSE_DB[v.clamp(0, 255) as usize]).collect() + } +} + +impl Floor0 { + fn decode(&self, r: &mut BitReader<'_>, books: &[Codebook]) -> Result, Fail> { + let amplitude = r.read(self.amplitude_bits)?; + if amplitude == 0 { + return Ok(None); + } + let book = r.read(ilog(self.books.len() as i64))? as usize; + let Some(&book) = self.books.get(book) else { return Err(Fail::Invalid) }; + let book = &books[book]; + let mut coefficients: Vec = Vec::with_capacity(self.order + book.dimensions); + let mut last = 0f32; + while coefficients.len() < self.order { + let Some(v) = book.vector(r)? else { return Err(Fail::Invalid) }; + coefficients.extend(v.iter().map(|&x| x + last)); + last = coefficients[coefficients.len() - 1]; + } + Ok(Some(FloorData::Zero { amplitude, coefficients })) + } + + fn curve(&self, amplitude: u32, coefficients: &[f32], n: usize) -> Vec { + let bark = |x: f64| 13.1 * (0.00074 * x).atan() + 2.24 * (0.000_000_018_5 * x * x).atan() + 0.0001 * x; + let scale = f64::from(self.bark_map_size) / bark(0.5 * f64::from(self.rate)); + let map: Vec = (0..n) + .map(|i| { + let foobar = (bark(f64::from(self.rate) * i as f64 / (2.0 * n as f64)) * scale).floor() as i64; + foobar.min(i64::from(self.bark_map_size) - 1) + }) + .collect(); + let cos_c: Vec = coefficients.iter().take(self.order).map(|&c| f64::from(c).cos()).collect(); + let amp = f64::from(amplitude); + let offset = f64::from(self.amplitude_offset); + let top = (2f64).powi(self.amplitude_bits as i32) - 1.0; + let mut out = vec![0f32; n]; + let mut i = 0usize; + while i < n { + let omega = std::f64::consts::PI * map[i] as f64 / f64::from(self.bark_map_size); + let cw = omega.cos(); + let (p, q); + if self.order % 2 == 1 { + let mut pp = 1.0 - cw * cw; + for j in 0..(self.order - 1) / 2 { + let d = cos_c[2 * j + 1] - cw; + pp *= 4.0 * d * d; + } + let mut qq = 0.25; + for j in 0..=(self.order - 1) / 2 { + let d = cos_c[2 * j] - cw; + qq *= 4.0 * d * d; + } + p = pp; + q = qq; + } else { + let mut pp = (1.0 - cw) / 2.0; + let mut qq = (1.0 + cw) / 2.0; + for j in 0..self.order / 2 { + let d1 = cos_c[2 * j + 1] - cw; + pp *= 4.0 * d1 * d1; + let d0 = cos_c[2 * j] - cw; + qq *= 4.0 * d0 * d0; + } + p = pp; + q = qq; + } + let linear = (0.115_129_25 * (amp * offset / (top * (p + q).sqrt()) - offset)).exp() as f32; + let key = map[i]; + while i < n && map[i] == key { + out[i] = linear; + i += 1; + } + } + out + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn render_line_matches_a_bresenham_walk() { + let mut v = vec![0i32; 16]; + render_line(0, 0, 8, 4, &mut v); + assert_eq!(&v[..8], &[0, 0, 1, 1, 2, 2, 3, 3]); + let mut v = vec![0i32; 16]; + render_line(2, 10, 6, 2, &mut v); + assert_eq!(&v[2..6], &[10, 8, 6, 4]); + // Lines running past the vector stop at its end. + let mut v = vec![0i32; 4]; + render_line(0, 0, 100, 100, &mut v); + assert_eq!(v, vec![0, 1, 2, 3]); + assert_eq!(render_point(0, 0, 10, 10, 5), 5); + assert_eq!(render_point(0, 10, 10, 0, 5), 5); + } +} diff --git a/crates/audio/src/vorbis/decoder/mdct.rs b/crates/audio/src/vorbis/decoder/mdct.rs new file mode 100644 index 000000000..b4eb6c8ec --- /dev/null +++ b/crates/audio/src/vorbis/decoder/mdct.rs @@ -0,0 +1,164 @@ +//! The inverse MDCT of a block (Vorbis I §4.3.7) and the window slopes. +//! +//! `y[j] = sum_k X[k] cos(2*pi/n * (j + 1/2 + n/4) * (k + 1/2))` for `n/2` coefficients and `n` +//! samples, computed as a DCT-IV of the coefficients through an `n/8`-point complex FFT, then +//! unfolded. + +use std::f64::consts::PI; + +#[derive(Clone, Copy, Default)] +struct Cpx { + re: f64, + im: f64, +} + +impl Cpx { + fn mul(self, o: Cpx) -> Cpx { + Cpx { re: self.re * o.re - self.im * o.im, im: self.re * o.im + self.im * o.re } + } +} + +fn cis(t: f64) -> Cpx { + Cpx { re: t.cos(), im: t.sin() } +} + +pub(super) struct Imdct { + n: usize, + twiddle: Vec, + post: Vec, + fft_tw: Vec, + rev: Vec, +} + +impl Imdct { + /// For blocks of `n` samples, a power of two of at least 16. + pub(super) fn new(n: usize) -> Self { + let m = n / 2; + let h = m / 2; + let twiddle = (0..h).map(|j| cis(-PI * (4.0 * j as f64 + 1.0) / (4.0 * m as f64))).collect(); + let post = (0..h).map(|k| cis(-PI * k as f64 / m as f64)).collect(); + let fft_tw = (0..h / 2).map(|j| cis(-2.0 * PI * j as f64 / h as f64)).collect(); + let bits = h.trailing_zeros(); + let rev = (0..h).map(|i| if bits == 0 { 0 } else { i.reverse_bits() >> (usize::BITS - bits) }).collect(); + Self { n, twiddle, post, fft_tw, rev } + } + + /// `x`: `n/2` coefficients; `out`: `n` samples. + pub(super) fn inverse(&self, x: &[f32], out: &mut [f32]) { + let m = self.n / 2; + let q = self.n / 4; + let h = m / 2; + let mut z: Vec = (0..h).map(|j| Cpx { re: f64::from(x[2 * j]), im: f64::from(x[m - 1 - 2 * j]) }.mul(self.twiddle[j])).collect(); + self.fft(&mut z); + let mut v = vec![0f64; m]; + for (k, c) in z.iter().enumerate() { + let d = c.mul(self.post[k]); + v[2 * k] = d.re; + v[m - 1 - 2 * k] = -d.im; + } + // Unfold the DCT-IV output to the block. + for i in 0..q { + out[3 * q - 1 - i] = (-v[i]) as f32; + out[3 * q + i] = (-v[i]) as f32; + } + for i in q..2 * q { + out[i - q] = v[i] as f32; + out[3 * q - 1 - i] = (-v[i]) as f32; + } + } + + fn fft(&self, a: &mut [Cpx]) { + let h = a.len(); + for (i, &j) in self.rev.iter().enumerate() { + if i < j { + a.swap(i, j); + } + } + let mut len = 2; + while len <= h { + let step = h / len; + for start in (0..h).step_by(len) { + for k in 0..len / 2 { + let w = self.fft_tw[k * step]; + let u = a[start + k]; + let t = a[start + k + len / 2].mul(w); + a[start + k] = Cpx { re: u.re + t.re, im: u.im + t.im }; + a[start + k + len / 2] = Cpx { re: u.re - t.re, im: u.im - t.im }; + } + } + len *= 2; + } + } +} + +/// The rising half of the Vorbis window over `len` samples (§4.3.1): +/// `sin(pi/2 * sin^2((i + 0.5) / len * pi/2))`. +pub(super) fn slope(len: usize) -> Vec { + (0..len) + .map(|i| { + let s = (PI / 2.0 * (i as f64 + 0.5) / len as f64).sin(); + (PI / 2.0 * s * s).sin() as f32 + }) + .collect() +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn matches_the_direct_formula() { + for n in [16usize, 64, 256, 2048] { + let x: Vec = (0..n / 2).map(|i| ((i * 7919 % 211) as f32 - 105.0) / 50.0).collect(); + let mut fast = vec![0f32; n]; + Imdct::new(n).inverse(&x, &mut fast); + for j in [0usize, 1, 2, n / 4, n / 2, n - 1] { + let direct: f64 = + (0..n / 2).map(|k| f64::from(x[k]) * (2.0 * PI / n as f64 * (j as f64 + 0.5 + n as f64 / 4.0) * (k as f64 + 0.5)).cos()).sum(); + assert!((direct - f64::from(fast[j])).abs() < 1e-3 * (1.0 + direct.abs()), "n={n} j={j}: {direct} vs {}", fast[j]); + } + } + } + + #[test] + fn windowed_overlap_add_reconstructs_the_signal() { + // Forward MDCT by the definition with the 2/M scale an encoder uses, then this inverse. + let n = 64usize; + let m = n / 2; + let signal: Vec = (0..n * 6).map(|i| ((i * 37 % 101) as f64 - 50.0) / 50.0).collect(); + let w: Vec = slope(m).into_iter().chain(slope(m).into_iter().rev()).collect(); + let imdct = Imdct::new(n); + let mut out = vec![0f64; signal.len()]; + let mut start = 0; + while start + n <= signal.len() { + let coeffs: Vec = (0..m) + .map(|k| { + let s: f64 = (0..n) + .map(|j| { + signal[start + j] * f64::from(w[j]) * (2.0 * PI / n as f64 * (j as f64 + 0.5 + n as f64 / 4.0) * (k as f64 + 0.5)).cos() + }) + .sum(); + (s * 2.0 / m as f64) as f32 + }) + .collect(); + let mut y = vec![0f32; n]; + imdct.inverse(&coeffs, &mut y); + for j in 0..n { + out[start + j] += f64::from(y[j]) * f64::from(w[j]); + } + start += m; + } + for i in m..signal.len() - m { + assert!((out[i] - signal[i]).abs() < 1e-4, "sample {i}: {} vs {}", out[i], signal[i]); + } + } + + #[test] + fn the_slope_is_power_complementary() { + let s = slope(1024); + for i in 0..1024 { + let sum = s[i] * s[i] + s[1023 - i] * s[1023 - i]; + assert!((sum - 1.0).abs() < 1e-5, "{i}: {sum}"); + } + } +} diff --git a/crates/audio/src/vorbis/decoder/mod.rs b/crates/audio/src/vorbis/decoder/mod.rs new file mode 100644 index 000000000..7485e34b8 --- /dev/null +++ b/crates/audio/src/vorbis/decoder/mod.rs @@ -0,0 +1,552 @@ +//! A clean-room Vorbis I decoder (feature `vorbis-decode`), written from the Vorbis I +//! specification (Xiph.Org, 2020). +//! +//! [`Decoder`] works on packets: build it from the three header packets (identification, comment +//! and setup), then give it audio packets in order. Each call returns the PCM the packet +//! completes, planar `f32` in the nominal range -1.0 to 1.0 (not clipped), channels in the order of +//! the stream. The first packet only primes the overlap and returns nothing. [`decode_ogg`] reads a +//! whole Ogg Vorbis file. +//! +//! Codebooks, floors 0 and 1, residues 0, 1 and 2, channel coupling and both block sizes with their +//! hybrid windows are implemented. Damaged input is an error, never a panic: setup sizes are +//! bounded before anything is allocated, and the codeword trees are checked for completeness. + +mod bits; +mod codebook; +mod floor; +mod mdct; +mod residue; +mod tables; + +use bits::{BitReader, Eop, ilog}; +use codebook::Codebook; +use floor::{Fail, Floor, FloorData}; +use mdct::{Imdct, slope}; +use residue::Residue; + +/// Errors of the Vorbis decoder. +#[non_exhaustive] +#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)] +pub enum Error { + /// The identification or comment header is not valid Vorbis. + #[error("invalid Vorbis header: {0}")] + Header(&'static str), + /// The setup header is damaged or uses something Vorbis I does not allow. + #[error("invalid Vorbis setup: {0}")] + Setup(&'static str), + /// The setup or decoded PCM asks for more memory than the decoder allows. + #[error("Vorbis decode above the limits: {0}")] + Limit(&'static str), + /// The packet is not an audio packet (a header, or a packet with its first bit set). + #[error("not an audio packet")] + NotAudio, + /// The packet is damaged: it ends before its mode and window flags are read, or names a mode + /// that does not exist. + #[error("damaged audio packet: {0}")] + Packet(&'static str), + /// An Ogg file with no Vorbis stream, or one that cannot be read. + #[error("Ogg Vorbis file: {0}")] + Ogg(String), +} + +/// `Result` of this module. +pub type Result = std::result::Result; + +/// The identification header (§4.2.2). +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub struct Identification { + /// The channel count, at least 1. + pub channels: u8, + /// Samples per second per channel. + pub sample_rate: u32, + /// The maximum bit rate in bits per second, 0 or negative when not set. + pub bitrate_maximum: i32, + /// The nominal bit rate in bits per second, 0 or negative when not set. + pub bitrate_nominal: i32, + /// The minimum bit rate in bits per second, 0 or negative when not set. + pub bitrate_minimum: i32, + /// The short block size in samples. + pub blocksize_0: u32, + /// The long block size in samples. + pub blocksize_1: u32, +} + +/// The comment header (§5): a vendor string and `NAME=value` comments. +#[derive(Debug, Clone, Default, PartialEq, Eq)] +pub struct Comments { + /// The vendor string of the encoder. + pub vendor: String, + /// The user comments, each `NAME=value`. + pub comments: Vec, +} + +impl Comments { + /// The first comment named `name` (case-insensitive), its value. + #[must_use] + pub fn get(&self, name: &str) -> Option<&str> { + self.comments.iter().find_map(|c| { + let (k, v) = c.split_once('=')?; + k.eq_ignore_ascii_case(name).then_some(v) + }) + } +} + +fn header_start(packet: &[u8], kind: u8) -> Result> { + if packet.len() < 7 || packet[0] != kind || &packet[1..7] != b"vorbis" { + return Err(Error::Header("wrong packet type or missing \"vorbis\" tag")); + } + let mut r = BitReader::new(packet); + let _ = r.read(8); + for _ in 0..6 { + let _ = r.read(8); + } + Ok(r) +} + +fn read_identification(packet: &[u8]) -> Result { + let mut r = header_start(packet, 1)?; + let eop = |_: Eop| Error::Header("identification header is truncated"); + if r.read(32).map_err(eop)? != 0 { + return Err(Error::Header("unsupported Vorbis version")); + } + let channels = r.read(8).map_err(eop)? as u8; + let sample_rate = r.read(32).map_err(eop)?; + let bitrate_maximum = r.read(32).map_err(eop)? as i32; + let bitrate_nominal = r.read(32).map_err(eop)? as i32; + let bitrate_minimum = r.read(32).map_err(eop)? as i32; + let e0 = r.read(4).map_err(eop)?; + let e1 = r.read(4).map_err(eop)?; + if !r.bit().map_err(eop)? { + return Err(Error::Header("identification header framing bit is not set")); + } + if channels == 0 || sample_rate == 0 { + return Err(Error::Header("no channels or a zero sample rate")); + } + if !(6..=13).contains(&e0) || !(6..=13).contains(&e1) || e0 > e1 { + return Err(Error::Header("block sizes must be powers of two from 64 to 8192, the short one not above the long one")); + } + Ok(Identification { channels, sample_rate, bitrate_maximum, bitrate_nominal, bitrate_minimum, blocksize_0: 1 << e0, blocksize_1: 1 << e1 }) +} + +/// Comments are best effort: damage here is not fatal (§4.2.1). +fn read_comments(packet: &[u8]) -> Result { + header_start(packet, 3)?; + let mut at = 7usize; + let mut take = |n: usize| -> Option<&[u8]> { + let s = packet.get(at..at.checked_add(n)?)?; + at += n; + Some(s) + }; + let word = |b: &[u8]| u32::from_le_bytes([b[0], b[1], b[2], b[3]]) as usize; + let mut out = Comments::default(); + let Some(n) = take(4).map(word) else { return Ok(out) }; + let Some(vendor) = take(n) else { return Ok(out) }; + out.vendor = String::from_utf8_lossy(vendor).into_owned(); + let Some(count) = take(4).map(word) else { return Ok(out) }; + for _ in 0..count { + let Some(n) = take(4).map(word) else { break }; + let Some(c) = take(n) else { break }; + out.comments.push(String::from_utf8_lossy(c).into_owned()); + } + Ok(out) +} + +struct Mapping { + coupling: Vec<(usize, usize)>, + mux: Vec, + /// `(floor, residue)` of each submap. + submaps: Vec<(usize, usize)>, +} + +struct Mode { + long: bool, + mapping: usize, +} + +struct Setup { + books: Vec, + floors: Vec, + residues: Vec, + mappings: Vec, + modes: Vec, +} + +/// Bytes the codebooks of a setup may take in all (codeword trees and vector tables). +const CODEBOOK_BUDGET: usize = 256 << 20; + +fn read_setup(packet: &[u8], channels: usize) -> Result { + let mut r = header_start(packet, 5)?; + let eop = |_: Eop| Error::Setup("setup header is truncated"); + let count = r.read(8).map_err(eop)? as usize + 1; + let mut budget = CODEBOOK_BUDGET; + let mut books = Vec::with_capacity(count); + for _ in 0..count { + books.push(Codebook::read(&mut r, &mut budget)?); + } + // Time domain transforms: placeholders. + for _ in 0..r.read(6).map_err(eop)? + 1 { + if r.read(16).map_err(eop)? != 0 { + return Err(Error::Setup("a time domain transform is not zero")); + } + } + let count = r.read(6).map_err(eop)? as usize + 1; + let mut floors = Vec::with_capacity(count); + for _ in 0..count { + let kind = r.read(16).map_err(eop)?; + floors.push(Floor::read(kind, &mut r, &books)?); + } + let count = r.read(6).map_err(eop)? as usize + 1; + let mut residues = Vec::with_capacity(count); + for _ in 0..count { + let kind = r.read(16).map_err(eop)?; + if kind > 2 { + return Err(Error::Setup("unknown residue type")); + } + residues.push(Residue::read(kind, &mut r, &books)?); + } + let count = r.read(6).map_err(eop)? as usize + 1; + let mut mappings = Vec::with_capacity(count); + for _ in 0..count { + if r.read(16).map_err(eop)? != 0 { + return Err(Error::Setup("unknown mapping type")); + } + let submaps = if r.bit().map_err(eop)? { r.read(4).map_err(eop)? as usize + 1 } else { 1 }; + let mut coupling = Vec::new(); + if r.bit().map_err(eop)? { + let steps = r.read(8).map_err(eop)? as usize + 1; + let bits = ilog(channels as i64 - 1); + for _ in 0..steps { + let magnitude = r.read(bits).map_err(eop)? as usize; + let angle = r.read(bits).map_err(eop)? as usize; + if magnitude == angle || magnitude >= channels || angle >= channels { + return Err(Error::Setup("channel coupling names an invalid channel pair")); + } + coupling.push((magnitude, angle)); + } + } + if r.read(2).map_err(eop)? != 0 { + return Err(Error::Setup("reserved mapping bits are set")); + } + let mut mux = vec![0usize; channels]; + if submaps > 1 { + for m in &mut mux { + *m = r.read(4).map_err(eop)? as usize; + if *m >= submaps { + return Err(Error::Setup("channel multiplexed to a submap that does not exist")); + } + } + } + let mut list = Vec::with_capacity(submaps); + for _ in 0..submaps { + r.read(8).map_err(eop)?; + let floor = r.read(8).map_err(eop)? as usize; + let residue = r.read(8).map_err(eop)? as usize; + if floor >= floors.len() || residue >= residues.len() { + return Err(Error::Setup("submap names a floor or residue that does not exist")); + } + list.push((floor, residue)); + } + mappings.push(Mapping { coupling, mux, submaps: list }); + } + let count = r.read(6).map_err(eop)? as usize + 1; + let mut modes = Vec::with_capacity(count); + for _ in 0..count { + let long = r.bit().map_err(eop)?; + let window = r.read(16).map_err(eop)?; + let transform = r.read(16).map_err(eop)?; + let mapping = r.read(8).map_err(eop)? as usize; + if window != 0 || transform != 0 || mapping >= mappings.len() { + return Err(Error::Setup("a mode has a nonzero window or transform type or an unknown mapping")); + } + modes.push(Mode { long, mapping }); + } + if !r.bit().map_err(eop)? { + return Err(Error::Setup("setup header framing bit is not set")); + } + Ok(Setup { books, floors, residues, mappings, modes }) +} + +/// The previous block, windowed, kept for overlap-add. +struct Previous { + n: usize, + data: Vec>, +} + +/// A Vorbis I packet decoder. +pub struct Decoder { + id: Identification, + comments: Comments, + setup: Setup, + imdct: [Imdct; 2], + slopes: [Vec; 2], + previous: Option, +} + +impl Decoder { + /// A decoder from the three header packets, in order. A damaged comment header is tolerated + /// (its comments are then empty); the other two must be valid. + pub fn new(identification: &[u8], comment: &[u8], setup: &[u8]) -> Result { + let id = read_identification(identification)?; + let comments = read_comments(comment)?; + let setup = read_setup(setup, usize::from(id.channels))?; + let (b0, b1) = (id.blocksize_0 as usize, id.blocksize_1 as usize); + Ok(Self { id, comments, setup, imdct: [Imdct::new(b0), Imdct::new(b1)], slopes: [slope(b0 / 2), slope(b1 / 2)], previous: None }) + } + + /// The identification header. + #[must_use] + pub fn identification(&self) -> &Identification { + &self.id + } + + /// The comment header. + #[must_use] + pub fn comments(&self) -> &Comments { + &self.comments + } + + /// Forget the previous block, as after a seek: the next packet only primes the overlap again. + pub fn reset(&mut self) { + self.previous = None; + } + + /// The window of a block (§4.3.1). + fn window(&self, n: usize, long: bool, prev_long: bool, next_long: bool) -> Vec { + let half = n / 2; + let b0 = self.id.blocksize_0 as usize; + let mut w = vec![0f32; n]; + // Left half. + if long && !prev_long { + let (start, end) = (n / 4 - b0 / 4, n / 4 + b0 / 4); + w[start..end].copy_from_slice(&self.slopes[0]); + w[end..half].fill(1.0); + } else { + w[..half].copy_from_slice(&self.slopes[usize::from(long)]); + } + // Right half. + if long && !next_long { + let start = 3 * n / 4 - b0 / 4; + w[half..start].fill(1.0); + for (i, s) in self.slopes[0].iter().rev().enumerate() { + w[start + i] = *s; + } + } else { + for (i, s) in self.slopes[usize::from(long)].iter().rev().enumerate() { + w[half + i] = *s; + } + } + w + } + + /// Decode one audio packet. The result holds one `Vec` per channel, all of the same length: + /// the samples this packet completes (none for the first packet after a start or reset). + pub fn decode_packet(&mut self, packet: &[u8]) -> Result>> { + let channels = usize::from(self.id.channels); + let mut r = BitReader::new(packet); + match r.bit() { + Ok(false) => {} + Ok(true) => return Err(Error::NotAudio), + Err(_) => return Err(Error::Packet("empty packet")), + } + let mode_bits = ilog(self.setup.modes.len() as i64 - 1); + let mode_number = r.read(mode_bits).map_err(|_| Error::Packet("packet ends inside the mode number"))? as usize; + let Some(mode) = self.setup.modes.get(mode_number) else { return Err(Error::Packet("mode number out of range")) }; + let long = mode.long; + let n = if long { self.id.blocksize_1 } else { self.id.blocksize_0 } as usize; + let (mut prev_long, mut next_long) = (true, true); + if long { + prev_long = r.bit().map_err(|_| Error::Packet("packet ends inside the window flags"))?; + next_long = r.bit().map_err(|_| Error::Packet("packet ends inside the window flags"))?; + } + let window = self.window(n, long, prev_long, next_long); + let half = n / 2; + let mapping = &self.setup.mappings[mode.mapping]; + + let spectrum = self.spectrum(&mut r, mapping, half, channels)?; + // Inverse transform and window. + let which = usize::from(long); + let mut blocks: Vec> = Vec::with_capacity(channels); + for s in &spectrum { + let mut y = vec![0f32; n]; + self.imdct[which].inverse(s, &mut y); + for (v, w) in y.iter_mut().zip(&window) { + *v *= *w; + } + blocks.push(y); + } + + // Overlap-add with the previous block (§4.3.8). + let out = match &self.previous { + None => vec![Vec::new(); channels], + Some(prev) => { + let count = prev.n / 4 + n / 4; + blocks + .iter() + .zip(&prev.data) + .map(|(cur, old)| { + (0..count) + .map(|k| { + let a = old.get(prev.n / 2 + k).copied().unwrap_or(0.0); + let b = (n / 4 + k).checked_sub(prev.n / 4).and_then(|i| cur.get(i)).copied().unwrap_or(0.0); + a + b + }) + .collect() + }) + .collect() + } + }; + self.previous = Some(Previous { n, data: blocks }); + Ok(out) + } + + /// Floors, residues, coupling and the dot product: the spectrum of each channel (§4.3.2 to 4.3.6). + fn spectrum(&self, r: &mut BitReader<'_>, mapping: &Mapping, half: usize, channels: usize) -> Result>> { + let zero = || vec![vec![0f32; half]; channels]; + let setup = &self.setup; + // Floors, in channel order. + let mut floors: Vec> = Vec::with_capacity(channels); + for ch in 0..channels { + let (floor, _) = mapping.submaps[mapping.mux[ch]]; + match setup.floors[floor].decode(r, &setup.books) { + Ok(f) => floors.push(f), + Err(Fail::Eop) => return Ok(zero()), + Err(Fail::Invalid) => return Err(Error::Packet("a floor names a codebook that does not exist")), + } + } + let mut no_residue: Vec = floors.iter().map(Option::is_none).collect(); + for &(m, a) in &mapping.coupling { + if !no_residue[m] || !no_residue[a] { + no_residue[m] = false; + no_residue[a] = false; + } + } + // Residues, in submap order. + let mut residue = zero(); + for (i, &(_, res)) in mapping.submaps.iter().enumerate() { + let members: Vec = (0..channels).filter(|&c| mapping.mux[c] == i).collect(); + if members.is_empty() { + continue; + } + let skip: Vec = members.iter().map(|&c| no_residue[c]).collect(); + let mut vectors = vec![vec![0f32; half]; members.len()]; + setup.residues[res].decode(r, &setup.books, half, &skip, &mut vectors); + for (v, &c) in vectors.into_iter().zip(&members) { + residue[c] = v; + } + } + // Inverse channel coupling (§4.3.5), last step first. + for &(m, a) in mapping.coupling.iter().rev() { + let mut mag = std::mem::take(&mut residue[m]); + let mut ang = std::mem::take(&mut residue[a]); + for (mv, av) in mag.iter_mut().zip(ang.iter_mut()) { + let (big, small) = (*mv, *av); + let (new_m, new_a); + if big > 0.0 { + if small > 0.0 { + new_m = big; + new_a = big - small; + } else { + new_a = big; + new_m = big + small; + } + } else if small > 0.0 { + new_m = big; + new_a = big + small; + } else { + new_a = big; + new_m = big - small; + } + *mv = new_m; + *av = new_a; + } + residue[m] = mag; + residue[a] = ang; + } + // The floor times the residue. + for ch in 0..channels { + match &floors[ch] { + Some(data) => { + let (floor, _) = mapping.submaps[mapping.mux[ch]]; + let curve = setup.floors[floor].curve(data, half); + for (v, c) in residue[ch].iter_mut().zip(curve) { + *v *= c; + } + } + None => residue[ch].fill(0.0), + } + } + Ok(residue) + } +} + +/// A decoded Ogg Vorbis file. +#[derive(Debug, Clone, PartialEq)] +pub struct Decoded { + /// Samples per second per channel. + pub sample_rate: u32, + /// One `Vec` of samples per channel. + pub channels: Vec>, + /// The stream's comment header. + pub comments: Comments, + /// Audio packets that could not be decoded and were skipped. + pub damaged_packets: usize, +} + +/// Decode the first Vorbis stream of an Ogg file. The result is trimmed to the stream's final +/// granule position, so an encoder's padding at the end is dropped. Damaged packets are skipped +/// and counted, not fatal. Collected PCM is limited to 256 MiB; use the packet +/// decoder for longer streams without retaining the entire output. +pub fn decode_ogg(data: &[u8]) -> Result { + let ogg = craft_media::ogg::open(data).map_err(|e| Error::Ogg(e.to_string()))?; + let index = ogg.stream_of(craft_media::ogg::Codec::Vorbis).ok_or_else(|| Error::Ogg("no Vorbis stream".into()))?; + let stream = &ogg.streams[index]; + let [id, comment, setup, ..] = stream.headers.as_slice() else { return Err(Error::Ogg("the stream has fewer than three header packets".into())) }; + let mut decoder = Decoder::new(id, comment, setup)?; + let channel_count = usize::from(decoder.id.channels); + let mut channels = vec![Vec::new(); channel_count]; + let mut damaged = 0; + for i in 0..stream.packets.len() { + let packet = ogg.read_packet(data, index, i).map_err(|e| Error::Ogg(e.to_string()))?; + match decoder.decode_packet(&packet) { + Ok(pcm) => { + append_pcm(&mut channels, pcm, 256 << 20)?; + } + Err(_) => damaged += 1, + } + } + if let Some(total) = stream.last_granule.and_then(|g| usize::try_from(g).ok()) { + for c in &mut channels { + c.truncate(total); + } + } + Ok(Decoded { sample_rate: decoder.id.sample_rate, channels, comments: decoder.comments.clone(), damaged_packets: damaged }) +} + +// Admit every channel together before extending any of them. Limit retained PCM, +// not the compressed input, setup tables or the decoder's bounded packet scratch. +fn append_pcm(channels: &mut [Vec], pcm: Vec>, budget: usize) -> Result<()> { + let samples = channels.iter().chain(&pcm).try_fold(0usize, |n, c| n.checked_add(c.len())); + if samples.is_none_or(|n| n > budget / std::mem::size_of::()) { + return Err(Error::Limit("decoded PCM exceeds the whole-file budget")); + } + for (all, new) in channels.iter_mut().zip(pcm) { + all.try_reserve_exact(new.len()).map_err(|_| Error::Limit("cannot allocate decoded PCM"))?; + all.extend(new); + } + Ok(()) +} + +#[cfg(test)] +mod budget_tests { + use super::*; + + #[test] + fn pcm_budget_counts_all_channels_before_extending() { + let mut channels = vec![vec![1.0], vec![2.0]]; + append_pcm(&mut channels, vec![vec![3.0], vec![4.0]], 16).expect("exact budget"); + let before = channels.clone(); + assert!(matches!(append_pcm(&mut channels, vec![vec![5.0], vec![6.0]], 23), Err(Error::Limit(_)))); + assert_eq!(channels, before); + append_pcm(&mut channels, vec![Vec::new(), Vec::new()], 16).expect("empty packet"); + } +} diff --git a/crates/audio/src/vorbis/decoder/residue.rs b/crates/audio/src/vorbis/decoder/residue.rs new file mode 100644 index 000000000..99918d379 --- /dev/null +++ b/crates/audio/src/vorbis/decoder/residue.rs @@ -0,0 +1,196 @@ +//! Residues (Vorbis I §8): the fine detail of the spectrum, coded as vectors in passes. + +use super::Error; +use super::bits::{BitReader, Eop}; +use super::codebook::Codebook; + +pub(super) struct Residue { + kind: u32, + begin: usize, + end: usize, + partition_size: usize, + classifications: usize, + classbook: usize, + /// `books[class][pass]`. + books: Vec<[Option; 8]>, +} + +fn eop(_: Eop) -> Error { + Error::Setup("setup header ends inside a residue") +} + +impl Residue { + pub(super) fn read(kind: u32, r: &mut BitReader<'_>, books: &[Codebook]) -> Result { + let begin = r.read(24).map_err(eop)? as usize; + let end = r.read(24).map_err(eop)? as usize; + let partition_size = r.read(24).map_err(eop)? as usize + 1; + let classifications = r.read(6).map_err(eop)? as usize + 1; + let classbook = r.read(8).map_err(eop)? as usize; + let Some(cb) = books.get(classbook) else { return Err(Error::Setup("residue class book out of range")) }; + // classifications ^ dimensions must not exceed the book's entries. + let mut reach = 1u128; + for _ in 0..cb.dimensions { + reach = reach.saturating_mul(classifications as u128); + if reach > cb.entries as u128 { + return Err(Error::Setup("residue class book has too few entries for its classifications")); + } + } + let mut cascade = Vec::with_capacity(classifications); + for _ in 0..classifications { + let low = r.read(3).map_err(eop)?; + let high = if r.bit().map_err(eop)? { r.read(5).map_err(eop)? } else { 0 }; + cascade.push(high * 8 + low); + } + let mut list = Vec::with_capacity(classifications); + for &c in &cascade { + let mut row = [None; 8]; + for (j, slot) in row.iter_mut().enumerate() { + if c & (1 << j) != 0 { + let b = r.read(8).map_err(eop)? as usize; + match books.get(b) { + Some(book) if book.has_vectors() => *slot = Some(b), + _ => return Err(Error::Setup("residue names a missing codebook or one without vectors")), + } + } + } + list.push(row); + } + Ok(Self { kind, begin, end, partition_size, classifications, classbook, books: list }) + } + + /// Decode a bundle of vectors, each `n` long (half the block size), into `out`; a vector marked + /// in `skip` is left zero. End of packet ends decoding where it is (a nominal event). + pub(super) fn decode(&self, r: &mut BitReader<'_>, books: &[Codebook], n: usize, skip: &[bool], out: &mut [Vec]) { + let ch = out.len(); + if skip.iter().all(|&s| s) { + return; + } + if self.kind == 2 { + let mut flat = vec![vec![0f32; n * ch]]; + let _ = self.decode_vectors(r, books, n * ch, &[false], &mut flat); + for i in 0..n { + for (j, v) in out.iter_mut().enumerate() { + v[i] = flat[0][i * ch + j]; + } + } + } else { + let _ = self.decode_vectors(r, books, n, skip, out); + } + } + + fn decode_vectors(&self, r: &mut BitReader<'_>, books: &[Codebook], actual: usize, skip: &[bool], out: &mut [Vec]) -> Result<(), Eop> { + let ch = out.len(); + let begin = self.begin.min(actual); + let end = self.end.min(actual); + if end <= begin { + return Ok(()); + } + let classbook = &books[self.classbook]; + let cpw = classbook.dimensions; + let partitions = (end - begin) / self.partition_size; + // Classbook dimensions may greatly exceed the actual partition count. + // Retain only digits that this block can use, not padding per channel. + let mut classes = vec![vec![0usize; partitions]; ch]; + for pass in 0..8 { + let mut count = 0usize; + while count < partitions { + if pass == 0 { + for j in 0..ch { + if skip[j] { + continue; + } + let mut temp = classbook.scalar(r)? as usize; + for i in (0..cpw).rev() { + if i + count < partitions { + classes[j][i + count] = temp % self.classifications; + } + temp /= self.classifications; + } + } + } + let mut i = 0; + while i < cpw && count < partitions { + for j in 0..ch { + if skip[j] { + continue; + } + let Some(book) = self.books[classes[j][count]][pass] else { continue }; + let book = &books[book]; + let offset = begin + count * self.partition_size; + self.partition(r, book, &mut out[j][offset..offset + self.partition_size])?; + } + count += 1; + i += 1; + } + } + } + Ok(()) + } + + /// One partition into `v` (the slice of the vector it covers). + fn partition(&self, r: &mut BitReader<'_>, book: &Codebook, v: &mut [f32]) -> Result<(), Eop> { + let n = v.len(); + let dims = book.dimensions; + let step = n / dims; + if self.kind == 0 { + for i in 0..step { + let Some(entry) = book.vector(r)? else { return Ok(()) }; + for (j, &e) in entry.iter().enumerate() { + v[i + j * step] += e; + } + } + } else { + let mut i = 0; + for _ in 0..step { + let Some(entry) = book.vector(r)? else { return Ok(()) }; + for &e in entry { + v[i] += e; + i += 1; + } + } + } + Ok(()) + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn huge_class_dimensions_keep_only_actual_partitions() { + let mut data = Vec::::new(); + let mut bits = 0usize; + let mut put = |value: u32, n: usize| { + for i in 0..n { + if bits.is_multiple_of(8) { + data.push(0); + } + let last = data.len() - 1; + data[last] |= (((value >> i) & 1) as u8) << (bits % 8); + bits += 1; + } + }; + put(0x56_4342, 24); + put(65535, 16); + put(1, 24); + put(0, 1); // unordered, not sparse, one length-1 entry + put(0, 1); + put(0, 5); + put(0, 4); // scalar-only classbook + let book = Codebook::read(&mut BitReader::new(&data), &mut (1 << 20)).expect("classbook"); + let books = [book]; + for kind in [0, 1] { + let residue = Residue { kind, begin: 0, end: 32, partition_size: 1, classifications: 1, classbook: 0, books: vec![[None; 8]] }; + let mut out = vec![vec![0.0; 32]; 255]; + let packet = [0u8; 32]; + let mut r = BitReader::new(&packet); + residue.decode(&mut r, &books, 32, &[false; 255], &mut out); + assert_eq!(r.remaining(), 1); // one classword per channel, not 32 + assert!(out.iter().flatten().all(|&x| x == 0.0)); + let mut r = BitReader::new(&packet); + residue.decode(&mut r, &books, 32, &[true; 255], &mut out); + assert_eq!(r.remaining(), 256); // skipped channels consume nothing + } + } +} diff --git a/crates/audio/src/vorbis/decoder/tables.rs b/crates/audio/src/vorbis/decoder/tables.rs new file mode 100644 index 000000000..49e5b97b9 --- /dev/null +++ b/crates/audio/src/vorbis/decoder/tables.rs @@ -0,0 +1,263 @@ +//! `floor1_inverse_dB_table` (Vorbis I §10.1): the 256 linear amplitudes of the floor 1 integer values. + +// The values are printed to the digits the specification gives them. +#![allow(clippy::excessive_precision)] + +pub(super) const INVERSE_DB: [f32; 256] = [ + 1.0649863e-07, + 1.1341951e-07, + 1.2079015e-07, + 1.2863978e-07, + 1.3699951e-07, + 1.4590251e-07, + 1.5538408e-07, + 1.6548181e-07, + 1.7623575e-07, + 1.8768855e-07, + 1.9988561e-07, + 2.1287530e-07, + 2.2670913e-07, + 2.4144197e-07, + 2.5713223e-07, + 2.7384213e-07, + 2.9163793e-07, + 3.1059021e-07, + 3.3077411e-07, + 3.5226968e-07, + 3.7516214e-07, + 3.9954229e-07, + 4.2550680e-07, + 4.5315863e-07, + 4.8260743e-07, + 5.1396998e-07, + 5.4737065e-07, + 5.8294187e-07, + 6.2082472e-07, + 6.6116941e-07, + 7.0413592e-07, + 7.4989464e-07, + 7.9862701e-07, + 8.5052630e-07, + 9.0579828e-07, + 9.6466216e-07, + 1.0273513e-06, + 1.0941144e-06, + 1.1652161e-06, + 1.2409384e-06, + 1.3215816e-06, + 1.4074654e-06, + 1.4989305e-06, + 1.5963394e-06, + 1.7000785e-06, + 1.8105592e-06, + 1.9282195e-06, + 2.0535261e-06, + 2.1869758e-06, + 2.3290978e-06, + 2.4804557e-06, + 2.6416497e-06, + 2.8133190e-06, + 2.9961443e-06, + 3.1908506e-06, + 3.3982101e-06, + 3.6190449e-06, + 3.8542308e-06, + 4.1047004e-06, + 4.3714470e-06, + 4.6555282e-06, + 4.9580707e-06, + 5.2802740e-06, + 5.6234160e-06, + 5.9888572e-06, + 6.3780469e-06, + 6.7925283e-06, + 7.2339451e-06, + 7.7040476e-06, + 8.2047000e-06, + 8.7378876e-06, + 9.3057248e-06, + 9.9104632e-06, + 1.0554501e-05, + 1.1240392e-05, + 1.1970856e-05, + 1.2748789e-05, + 1.3577278e-05, + 1.4459606e-05, + 1.5399272e-05, + 1.6400004e-05, + 1.7465768e-05, + 1.8600792e-05, + 1.9809576e-05, + 2.1096914e-05, + 2.2467911e-05, + 2.3928002e-05, + 2.5482978e-05, + 2.7139006e-05, + 2.8902651e-05, + 3.0780908e-05, + 3.2781225e-05, + 3.4911534e-05, + 3.7180282e-05, + 3.9596466e-05, + 4.2169667e-05, + 4.4910090e-05, + 4.7828601e-05, + 5.0936773e-05, + 5.4246931e-05, + 5.7772202e-05, + 6.1526565e-05, + 6.5524908e-05, + 6.9783085e-05, + 7.4317983e-05, + 7.9147585e-05, + 8.4291040e-05, + 8.9768747e-05, + 9.5602426e-05, + 0.00010181521, + 0.00010843174, + 0.00011547824, + 0.00012298267, + 0.00013097477, + 0.00013948625, + 0.00014855085, + 0.00015820453, + 0.00016848555, + 0.00017943469, + 0.00019109536, + 0.00020351382, + 0.00021673929, + 0.00023082423, + 0.00024582449, + 0.00026179955, + 0.00027881276, + 0.00029693158, + 0.00031622787, + 0.00033677814, + 0.00035866388, + 0.00038197188, + 0.00040679456, + 0.00043323036, + 0.00046138411, + 0.00049136745, + 0.00052329927, + 0.00055730621, + 0.00059352311, + 0.00063209358, + 0.00067317058, + 0.00071691700, + 0.00076350630, + 0.00081312324, + 0.00086596457, + 0.00092223983, + 0.00098217216, + 0.0010459992, + 0.0011139742, + 0.0011863665, + 0.0012634633, + 0.0013455702, + 0.0014330129, + 0.0015261382, + 0.0016253153, + 0.0017309374, + 0.0018434235, + 0.0019632195, + 0.0020908006, + 0.0022266726, + 0.0023713743, + 0.0025254795, + 0.0026895994, + 0.0028643847, + 0.0030505286, + 0.0032487691, + 0.0034598925, + 0.0036847358, + 0.0039241906, + 0.0041792066, + 0.0044507950, + 0.0047400328, + 0.0050480668, + 0.0053761186, + 0.0057254891, + 0.0060975636, + 0.0064938176, + 0.0069158225, + 0.0073652516, + 0.0078438871, + 0.0083536271, + 0.0088964928, + 0.009474637, + 0.010090352, + 0.010746080, + 0.011444421, + 0.012188144, + 0.012980198, + 0.013823725, + 0.014722068, + 0.015678791, + 0.016697687, + 0.017782797, + 0.018938423, + 0.020169149, + 0.021479854, + 0.022875735, + 0.024362330, + 0.025945531, + 0.027631618, + 0.029427276, + 0.031339626, + 0.033376252, + 0.035545228, + 0.037855157, + 0.040315199, + 0.042935108, + 0.045725273, + 0.048696758, + 0.051861348, + 0.055231591, + 0.058820850, + 0.062643361, + 0.066714279, + 0.071049749, + 0.075666962, + 0.080584227, + 0.085821044, + 0.091398179, + 0.097337747, + 0.10366330, + 0.11039993, + 0.11757434, + 0.12521498, + 0.13335215, + 0.14201813, + 0.15124727, + 0.16107617, + 0.17154380, + 0.18269168, + 0.19456402, + 0.20720788, + 0.22067342, + 0.23501402, + 0.25028656, + 0.26655159, + 0.28387361, + 0.30232132, + 0.32196786, + 0.34289114, + 0.36517414, + 0.38890521, + 0.41417847, + 0.44109412, + 0.46975890, + 0.50028648, + 0.53279791, + 0.56742212, + 0.60429640, + 0.64356699, + 0.68538959, + 0.72993007, + 0.77736504, + 0.82788260, + 0.88168307, + 0.9389798, + 1.0, +]; diff --git a/crates/audio/src/vorbis/mod.rs b/crates/audio/src/vorbis/mod.rs index 29c423f1d..15b81bb26 100644 --- a/crates/audio/src/vorbis/mod.rs +++ b/crates/audio/src/vorbis/mod.rs @@ -1,4 +1,7 @@ -//! Vorbis I (feature `vorbis-encode`): the pure-Rust [`encoder`]. Decoding Vorbis goes through -//! [`crate::decode`]. +//! Vorbis I: the pure-Rust [`decoder`] (feature `vorbis-decode`) and [`encoder`] (feature +//! `vorbis-encode`). `craft_audio::decode` still reads Vorbis files through symphonia. +#[cfg(feature = "vorbis-decode")] +pub mod decoder; +#[cfg(feature = "vorbis-encode")] pub mod encoder; diff --git a/crates/audio/tests/adpcm_oracle.rs b/crates/audio/tests/adpcm_oracle.rs new file mode 100644 index 000000000..c89fe6444 --- /dev/null +++ b/crates/audio/tests/adpcm_oracle.rs @@ -0,0 +1,516 @@ +//! ADPCM (feature `adpcm`): every family decodes what ffmpeg's encoder writes to ffmpeg's own +//! samples, and ffmpeg decodes what our encoder writes to our own decoder's samples (oracle; +//! skipped when ffmpeg is absent, a failure with `CRAFT_MEDIA_REQUIRE_ORACLES=1`); plus the +//! round trip through our own encoder and decoder, and damaged input. + +use craft_audio::adpcm::{ima, ms, swf, yamaha}; +use std::path::Path; +use std::process::Command; + +const RATE: u32 = 22_050; + +/// Interleaved test audio: tones, a sweep, noise bursts, silence and a full-scale square. +fn signal(channels: usize, frames: usize) -> Vec { + let mut seed = 0x2545_F491u32; + let mut out = Vec::with_capacity(frames * channels); + for i in 0..frames { + for c in 0..channels { + seed ^= seed << 13; + seed ^= seed >> 17; + seed ^= seed << 5; + let t = i as f64; + let v = match (i / 1500) % 5 { + 0 => (t * (0.03 + 0.011 * c as f64)).sin() * 9000.0, + 1 => (t * 0.002 * (1.0 + t / 3000.0)).sin() * 14000.0, + 2 => f64::from(seed % 12000) - 6000.0, + 3 => 0.0, + _ => { + if (i / 40) % 2 == 0 { + 20000.0 + } else { + -20000.0 + } + } + }; + out.push(v as i16); + } + } + out +} + +fn snr(a: &[i16], b: &[i16]) -> f64 { + let (mut s, mut n) = (0f64, 0f64); + for (x, y) in a.iter().zip(b) { + s += f64::from(*x).powi(2); + n += (f64::from(*x) - f64::from(*y)).powi(2); + } + 10.0 * (s / n.max(1.0)).log10() +} + +fn max_diff(a: &[i16], b: &[i16]) -> i32 { + a.iter().zip(b).map(|(x, y)| (i32::from(*x) - i32::from(*y)).abs()).max().unwrap_or(0) +} + +#[test] +fn encode_then_decode_is_close_to_the_input() { + for channels in [1usize, 2] { + let x = signal(channels, 20_000); + // (name, decoded, minimum SNR dB, a few dB under what each reaches): the signal has noise bursts + // and full-scale square waves, which codes this small follow loosely + let cases: Vec<(&str, Vec, f64)> = vec![ + ("ima", ima::decode(&ima::encode(&x, channels, 512).unwrap(), channels, 512).unwrap(), 5.0), + ("ms", ms::decode(&ms::encode(&x, channels, 512).unwrap(), channels, 512).unwrap(), 18.0), + ("yamaha", yamaha::decode(&yamaha::encode(&x, channels).unwrap(), channels).unwrap(), 5.0), + ("swf2", swf::decode(&swf::encode(&x, channels, 2).unwrap(), channels).unwrap(), 1.0), + ("swf3", swf::decode(&swf::encode(&x, channels, 3).unwrap(), channels).unwrap(), 3.0), + ("swf4", swf::decode(&swf::encode(&x, channels, 4).unwrap(), channels).unwrap(), 5.0), + ("swf5", swf::decode(&swf::encode(&x, channels, 5).unwrap(), channels).unwrap(), 7.0), + ]; + for (name, y, min) in cases { + assert!(y.len() >= x.len(), "{name}: {} samples for {}", y.len(), x.len()); + let s = snr(&x, &y[..x.len()]); + println!("{name} {channels}ch: SNR {s:.1} dB"); + assert!(s >= min, "{name} {channels}ch: SNR {s:.1} dB under {min}"); + } + } +} + +#[test] +fn damaged_input_is_an_error_or_decodes_never_panics() { + let x = signal(2, 4000); + let streams: Vec<(&str, Vec)> = vec![ + ("ima", ima::encode(&x, 2, 256).unwrap()), + ("ms", ms::encode(&x, 2, 256).unwrap()), + ("yamaha", yamaha::encode(&x, 2).unwrap()), + ("swf", swf::encode(&x, 2, 4).unwrap()), + ]; + let mut seed = 99u32; + for (name, s) in &streams { + for cut in (0..s.len()).step_by(7) { + let part = &s[..cut]; + let _ = match *name { + "ima" => ima::decode(part, 2, 256).map(drop), + "ms" => ms::decode(part, 2, 256).map(drop), + "yamaha" => yamaha::decode(part, 2).map(drop), + _ => swf::decode(part, 2).map(drop), + }; + } + for _ in 0..300 { + let mut d = s.clone(); + seed ^= seed << 13; + seed ^= seed >> 17; + seed ^= seed << 5; + let at = seed as usize % d.len(); + d[at] ^= (seed >> 8) as u8 | 1; + let _ = match *name { + "ima" => ima::decode(&d, 2, 256).map(drop), + "ms" => ms::decode(&d, 2, 256).map(drop), + "yamaha" => yamaha::decode(&d, 2).map(drop), + _ => swf::decode(&d, 2).map(drop), + }; + } + } + // the impossible layouts + assert!(ima::decode(&[0; 10], 2, 10).is_err()); + assert!(ima::decode(&[0; 8], 9, 8).is_err()); + assert!(ms::decode(&[0; 8], 3, 8).is_err()); + assert!(ima::encode(&[0; 3], 2, 256).is_err()); + assert!(ima::encode_block(&[0; 3], 1, 256).is_err()); + assert!(ms::encode_block(&[0; 3], 1, 256).is_err()); + // a block whose step index or predictor is out of range + let mut bad = ima::encode_block(&vec![0; 505], 1, 256).unwrap(); + bad[2] = 200; + assert!(ima::decode_block(&bad, 1, &mut Vec::new()).is_err()); + let mut bad = swf::encode(&[0; 10], 1, 4).unwrap(); + bad[2] = 0xFF; + let _ = swf::decode(&bad, 1); +} + +#[test] +fn huge_layouts_and_big_jumps_are_handled() { + // block sizes whose sample counts do not fit in a usize + assert_eq!(ima::samples_per_block(usize::MAX - 3, 1), None); + assert_eq!(ms::samples_per_block(usize::MAX, 1), None); + assert!(ima::encode(&[], 1, usize::MAX - 3).is_err()); + assert!(ms::encode(&[], 1, usize::MAX).is_err()); + // a Flash stream's header holds the step index in six bits: a jump from silence to full scale + // still decodes to what the encoder's own state says + for bits in [2u32, 3, 4, 5] { + let x = [0i16, 32767, -32768, 0, 0]; + let y = swf::decode(&swf::encode(&x, 1, bits).unwrap(), 1).unwrap(); + // the stream has no length: up to seven padding bits can read as one more code + assert!((x.len()..=x.len() + 3).contains(&y.len()), "{bits} bits: {} samples", y.len()); + assert!(y[1] > 0 && y[2] < y[1], "{bits} bits: {y:?}"); + } + // padding bits at the end of a stream are not a code: no incomplete stereo frame + for bits in [2u32, 3, 4, 5] { + let y = swf::decode(&swf::encode(&[0, 0, 5, -5, 9, 9], 2, bits).unwrap(), 2).unwrap(); + assert_eq!(y.len() % 2, 0, "{bits} bits: {y:?}"); + assert!((6..=8).contains(&y.len()), "{bits} bits: {} samples", y.len()); + } +} + +#[test] +fn partial_final_blocks_are_handled() { + let x = signal(1, 1000); + // IMA: 256-byte blocks hold 505 samples; 1000 samples is two blocks, the second padded + let enc = ima::encode(&x, 1, 256).unwrap(); + assert_eq!(enc.len(), 2 * 256); + assert_eq!(ima::decode(&enc, 1, 256).unwrap().len(), 1010); + // a stream cut inside the last block decodes as far as it goes + let cut = ima::decode(&enc[..256 + 4 + 40], 1, 256).unwrap(); + assert_eq!(cut.len(), 505 + 1 + 80); + let enc = ms::encode(&x, 1, 256).unwrap(); + assert_eq!(ms::decode(&enc, 1, 256).unwrap().len(), 1000); + assert!(ima::encode(&[], 1, 256).unwrap().is_empty()); + assert!(ms::encode(&[], 1, 256).unwrap().is_empty()); + assert!(yamaha::encode(&[], 1).unwrap().is_empty()); + assert_eq!(yamaha::decode(&yamaha::encode(&[5, 6, 7], 1).unwrap(), 1).unwrap().len(), 4); +} + +// ---- the other rounding some ffmpeg versions use for IMA and Flash ADPCM +// +// The IMA recommended practices build the step difference from `step >> 3` and the shifted steps +// of the magnitude bits that are set; some decoders (including older ffmpeg releases) compute +// `((2 * magnitude + 1) * step) >> (bits - 1)` instead, which rounds differently by a few units +// and so drifts apart through the predictor. A stream decodes to ours or to this one. + +fn alt_diff(mag: i32, step: i32, bits: u32) -> i32 { + ((2 * mag + 1) * step) >> (bits - 1) +} + +const INDEX_4: [i32; 8] = [-1, -1, -1, -1, 2, 4, 6, 8]; +const INDEX_5: [i32; 16] = [-1, -1, -1, -1, -1, -1, -1, -1, 1, 2, 4, 6, 8, 10, 13, 16]; +const STEPS: [i32; 89] = [ + 7, 8, 9, 10, 11, 12, 13, 14, 16, 17, 19, 21, 23, 25, 28, 31, 34, 37, 41, 45, 50, 55, 60, 66, 73, 80, 88, 97, 107, 118, 130, 143, 157, 173, 190, + 209, 230, 253, 279, 307, 337, 371, 408, 449, 494, 544, 598, 658, 724, 796, 876, 963, 1060, 1166, 1282, 1411, 1552, 1707, 1878, 2066, 2272, 2499, + 2749, 3024, 3327, 3660, 4026, 4428, 4871, 5358, 5894, 6484, 7132, 7845, 8630, 9493, 10442, 11487, 12635, 13899, 15289, 16818, 18500, 20350, + 22385, 24623, 27086, 29794, 32767, +]; + +fn index_table(bits: u32) -> &'static [i32] { + match bits { + 2 => &[-1, 2], + 3 => &[-1, -1, 2, 4], + 4 => &INDEX_4, + _ => &INDEX_5, + } +} + +/// `ima::decode` with the other rounding. +fn alt_ima_decode(data: &[u8], channels: usize, block_align: usize) -> Vec { + let per = ima::samples_per_block(block_align, channels).expect("layout"); + let mut out = Vec::new(); + for block in data.chunks_exact(block_align) { + let mut pred = vec![0i32; channels]; + let mut idx = vec![0i32; channels]; + let base = out.len(); + out.resize(base + per * channels, 0); + for ch in 0..channels { + pred[ch] = i32::from(i16::from_le_bytes([block[4 * ch], block[4 * ch + 1]])); + idx[ch] = i32::from(block[4 * ch + 2]); + out[base + ch] = pred[ch] as i16; + } + for (g, group) in block[4 * channels..].chunks_exact(4 * channels).enumerate() { + for (ch, bytes) in group.as_chunks::<4>().0.iter().enumerate() { + for (k, b) in bytes.iter().enumerate() { + for (half, nib) in [b & 0xF, b >> 4].into_iter().enumerate() { + let step = STEPS[idx[ch] as usize]; + let d = alt_diff(i32::from(nib & 7), step, 4); + pred[ch] = (pred[ch] + if nib & 8 != 0 { -d } else { d }).clamp(-32768, 32767); + idx[ch] = (idx[ch] + INDEX_4[usize::from(nib & 7)]).clamp(0, 88); + out[base + (1 + g * 8 + k * 2 + half) * channels + ch] = pred[ch] as i16; + } + } + } + } + } + out +} + +/// `swf::decode` with the other rounding (one stream). +fn alt_swf_decode(data: &[u8], channels: usize) -> Vec { + let mut bitpos = 0usize; + let mut get = |n: usize| -> Option { + let mut v = 0u32; + for _ in 0..n { + let byte = *data.get(bitpos / 8)?; + v = (v << 1) | u32::from((byte >> (7 - bitpos % 8)) & 1); + bitpos += 1; + } + Some(v) + }; + let bits = get(2).expect("header") + 2; + let mut out = Vec::new(); + loop { + let mut pred = Vec::new(); + let mut idx = Vec::new(); + for _ in 0..channels { + let (Some(p), Some(i)) = (get(16), get(6)) else { return out }; + out.push(p as u16 as i16); + pred.push(i32::from(p as u16 as i16)); + idx.push(i as i32); + } + for _ in 1..4096 { + for ch in 0..channels { + let Some(code) = get(bits as usize) else { return out }; + let mag = (code & ((1 << (bits - 1)) - 1)) as i32; + let d = alt_diff(mag, STEPS[idx[ch] as usize], bits); + pred[ch] = (pred[ch] + if code >> (bits - 1) != 0 { -d } else { d }).clamp(-32768, 32767); + idx[ch] = (idx[ch] + index_table(bits)[mag as usize]).clamp(0, 88); + out.push(pred[ch] as i16); + } + } + } +} + +/// Assert `theirs` is `ours` or `alt` over their common length (and say which). +fn same_as_either(what: &str, ours: &[i16], alt: &[i16], theirs: &[i16]) { + let n = ours.len().min(theirs.len()); + let (a, b) = (max_diff(&ours[..n], &theirs[..n]), max_diff(&alt[..n.min(alt.len())], &theirs[..n.min(alt.len())])); + println!("{what}: largest difference from ours {a}, from the other rounding {b}"); + assert!(a == 0 || b == 0, "{what}: ffmpeg's decode is neither ours ({a}) nor the other rounding ({b})"); +} + +/// A name, the WAV file around our stream, our decode of it and the other rounding's. +type Stream = (&'static str, Vec, Vec, Vec); + +// ---- ffmpeg as the reference + +fn ffmpeg(ff: &Path, args: &[&str]) { + let out = Command::new(ff).args(["-v", "error", "-nostdin", "-y"]).args(args).output().expect("run ffmpeg"); + assert!(out.status.success(), "ffmpeg {args:?}: {}", String::from_utf8_lossy(&out.stderr)); +} + +fn s(p: &Path) -> String { + p.to_str().expect("path").to_string() +} + +fn write_pcm(path: &Path, x: &[i16]) { + std::fs::write(path, x.iter().flat_map(|v| v.to_le_bytes()).collect::>()).expect("write"); +} + +fn read_pcm(path: &Path) -> Vec { + std::fs::read(path).expect("read").as_chunks::<2>().0.iter().map(|b| i16::from_le_bytes(*b)).collect() +} + +/// The `fmt ` chunk's fields and the `data` chunk of a WAV file. +fn wav_parts(bytes: &[u8]) -> (u16, usize, usize, Vec) { + let mut at = 12; + let (mut tag, mut channels, mut align) = (0, 0, 0); + while at + 8 <= bytes.len() { + let id = &bytes[at..at + 4]; + let len = u32::from_le_bytes([bytes[at + 4], bytes[at + 5], bytes[at + 6], bytes[at + 7]]) as usize; + let body = &bytes[at + 8..(at + 8 + len).min(bytes.len())]; + if id == b"fmt " { + tag = u16::from_le_bytes([body[0], body[1]]); + channels = usize::from(u16::from_le_bytes([body[2], body[3]])); + align = usize::from(u16::from_le_bytes([body[12], body[13]])); + } else if id == b"data" { + return (tag, channels, align, body.to_vec()); + } + at += 8 + len + (len & 1); + } + panic!("no data chunk"); +} + +/// A WAV file around `data`. +fn wav(tag: u16, channels: usize, align: usize, bits: u16, extra: &[u8], data: &[u8]) -> Vec { + let mut fmt = Vec::new(); + fmt.extend(tag.to_le_bytes()); + fmt.extend((channels as u16).to_le_bytes()); + fmt.extend(RATE.to_le_bytes()); + fmt.extend((RATE * align as u32 / 500).to_le_bytes()); + fmt.extend((align as u16).to_le_bytes()); + fmt.extend(bits.to_le_bytes()); + if !extra.is_empty() || tag == 0x11 || tag == 2 { + fmt.extend((extra.len() as u16).to_le_bytes()); + fmt.extend(extra); + } + let mut out = b"RIFF".to_vec(); + out.extend((4 + 8 + fmt.len() as u32 + 8 + data.len() as u32).to_le_bytes()); + out.extend(b"WAVEfmt "); + out.extend((fmt.len() as u32).to_le_bytes()); + out.extend(fmt); + out.extend(b"data"); + out.extend((data.len() as u32).to_le_bytes()); + out.extend(data); + out +} + +#[test] +fn we_decode_what_ffmpeg_encodes_to_the_samples_ffmpeg_decodes() { + let Some(ff) = craft_media_testkit::ffmpeg() else { return }; + let dir = craft_media_testkit::fixture_subdir("adpcm"); + for channels in [1usize, 2] { + let x = signal(channels, 30_000); + let pcm = dir.join(format!("in{channels}.pcm")); + write_pcm(&pcm, &x); + let input = ["-f", "s16le", "-ar", "22050", "-ac", if channels == 1 { "1" } else { "2" }, "-i"]; + for (name, codec, align) in [("ima", "adpcm_ima_wav", 512usize), ("ms", "adpcm_ms", 512), ("yamaha", "adpcm_yamaha", 0)] { + let file = dir.join(format!("{name}{channels}.wav")); + let mut args: Vec = input.iter().map(|a| a.to_string()).collect(); + args.extend([s(&pcm), "-c:a".into(), codec.into()]); + if align > 0 { + args.extend(["-block_size".into(), align.to_string()]); + } + args.push(s(&file)); + ffmpeg(&ff, &args.iter().map(String::as_str).collect::>()); + let back = dir.join(format!("{name}{channels}.out.pcm")); + ffmpeg(&ff, &["-i", &s(&file), "-f", "s16le", "-acodec", "pcm_s16le", &s(&back)]); + let theirs = read_pcm(&back); + let (tag, ch, block, data) = wav_parts(&std::fs::read(&file).expect("read")); + assert_eq!(ch, channels); + let ours = match name { + "ima" => { + assert_eq!(tag, 0x11); + ima::decode(&data, ch, block).expect("decode") + } + "ms" => { + assert_eq!(tag, 2); + ms::decode(&data, ch, block).expect("decode") + } + _ => yamaha::decode(&data, ch).expect("decode"), + }; + let n = ours.len().min(theirs.len()); + assert!(n >= 29_000 * channels, "{name} {channels}ch: {} ours, {} theirs", ours.len(), theirs.len()); + if name == "ima" { + same_as_either(&format!("{name} {channels}ch"), &ours, &alt_ima_decode(&data, ch, block), &theirs); + } else { + let d = max_diff(&ours[..n], &theirs[..n]); + println!("{name} {channels}ch: {n} samples, largest difference from ffmpeg's decode {d}"); + assert_eq!(d, 0, "{name} {channels}ch"); + } + // our encoder is as good as ffmpeg's on the same audio, to within 3 dB + let mine = match name { + "ima" => ima::decode(&ima::encode(&x, ch, block).expect("encode"), ch, block).expect("decode"), + "ms" => ms::decode(&ms::encode(&x, ch, block).expect("encode"), ch, block).expect("decode"), + _ => yamaha::decode(&yamaha::encode(&x, ch).expect("encode"), ch).expect("decode"), + }; + let m = x.len().min(mine.len()).min(theirs.len()); + let (a, b) = (snr(&x[..m], &mine[..m]), snr(&x[..m], &theirs[..m])); + println!("{name} {channels}ch: SNR {a:.1} dB ours, {b:.1} dB ffmpeg's"); + assert!(a + 3.0 >= b, "{name} {channels}ch: our encoder {a:.1} dB against ffmpeg's {b:.1} dB"); + } + } +} + +#[test] +fn ffmpeg_decodes_what_we_encode_to_the_samples_we_decode() { + let Some(ff) = craft_media_testkit::ffmpeg() else { return }; + let dir = craft_media_testkit::fixture_subdir("adpcm"); + for channels in [1usize, 2] { + let x = signal(channels, 12_000); + let coefs: Vec = ms::COEFFICIENTS.iter().flat_map(|&(a, b)| [a as i16, b as i16].into_iter().flat_map(i16::to_le_bytes)).collect(); + let streams: Vec = { + let e = ima::encode(&x, channels, 512).unwrap(); + let per = ima::samples_per_block(512, channels).unwrap() as u16; + let d = ima::decode(&e, channels, 512).unwrap(); + let d_alt = alt_ima_decode(&e, channels, 512); + let ima_wav = wav(0x11, channels, 512, 4, &per.to_le_bytes(), &e); + let e = ms::encode(&x, channels, 512).unwrap(); + let per = ms::samples_per_block(512, channels).unwrap() as u16; + let d2 = ms::decode(&e, channels, 512).unwrap(); + let mut extra = per.to_le_bytes().to_vec(); + extra.extend(7u16.to_le_bytes()); + extra.extend(&coefs); + let ms_wav = wav(2, channels, 512, 4, &extra, &e); + let e = yamaha::encode(&x, channels).unwrap(); + let d3 = yamaha::decode(&e, channels).unwrap(); + let y_wav = wav(0x20, channels, 512 * channels, 4, &[], &e); + vec![("ima", ima_wav, d, d_alt), ("ms", ms_wav, d2.clone(), d2), ("yamaha", y_wav, d3.clone(), d3)] + }; + for (name, bytes, ours, alt) in streams { + let file = dir.join(format!("our_{name}{channels}.wav")); + std::fs::write(&file, bytes).expect("write"); + let back = dir.join(format!("our_{name}{channels}.pcm")); + ffmpeg(&ff, &["-i", &s(&file), "-f", "s16le", "-acodec", "pcm_s16le", &s(&back)]); + let theirs = read_pcm(&back); + let n = ours.len().min(theirs.len()); + assert!(n + 2048 >= ours.len(), "{name} {channels}ch: ffmpeg decoded {} of {}", theirs.len(), ours.len()); + same_as_either(&format!("{name} {channels}ch, our stream"), &ours, &alt, &theirs); + } + } +} + +/// The audio tags of an FLV file: each tag's body without its flags byte. +fn flv_audio(bytes: &[u8]) -> Vec> { + let mut at = 13; + let mut out = Vec::new(); + while at + 11 <= bytes.len() { + let kind = bytes[at]; + let len = (usize::from(bytes[at + 1]) << 16) | (usize::from(bytes[at + 2]) << 8) | usize::from(bytes[at + 3]); + let body = &bytes[at + 11..(at + 11 + len).min(bytes.len())]; + if kind == 8 && body.len() > 1 { + assert_eq!(body[0] >> 4, 1, "SWF ADPCM tag"); + out.push(body[1..].to_vec()); + } + at += 11 + len + 4; + } + out +} + +/// An FLV file of 44.1 kHz audio tags with these ADPCM bodies. +fn flv(stereo: bool, tags: &[Vec]) -> Vec { + let mut out = b"FLV\x01\x04\0\0\0\x09\0\0\0\0".to_vec(); + let flags = (1u8 << 4) | (3 << 2) | (1 << 1) | u8::from(stereo); + for (i, t) in tags.iter().enumerate() { + let len = t.len() + 1; + let ts = (i * 4096 * 1000 / 44_100) as u32; + out.extend([ + 8, + (len >> 16) as u8, + (len >> 8) as u8, + len as u8, + (ts >> 16) as u8, + (ts >> 8) as u8, + ts as u8, + (ts >> 24) as u8, + 0, + 0, + 0, + flags, + ]); + out.extend(t); + out.extend((len as u32 + 11).to_be_bytes()); + } + out +} + +#[test] +fn flash_adpcm_matches_ffmpeg_in_both_directions() { + let Some(ff) = craft_media_testkit::ffmpeg() else { return }; + let dir = craft_media_testkit::fixture_subdir("adpcm"); + for channels in [1usize, 2] { + let x = signal(channels, 4096 * 3); + let pcm = dir.join(format!("swf_in{channels}.pcm")); + write_pcm(&pcm, &x); + // ffmpeg encodes (it needs 44.1 kHz for FLV) + let file = dir.join(format!("swf{channels}.flv")); + ffmpeg(&ff, &["-f", "s16le", "-ar", "44100", "-ac", &channels.to_string(), "-i", &s(&pcm), "-c:a", "adpcm_swf", "-f", "flv", &s(&file)]); + let tags = flv_audio(&std::fs::read(&file).expect("read")); + assert!(tags.len() >= 3, "{} tags", tags.len()); + let back = dir.join(format!("swf{channels}.out.pcm")); + ffmpeg(&ff, &["-i", &s(&file), "-f", "s16le", "-acodec", "pcm_s16le", &s(&back)]); + let theirs = read_pcm(&back); + let ours: Vec = tags.iter().flat_map(|t| swf::decode(t, channels).expect("decode")).collect(); + assert_eq!(ours.len(), 4096 * 3 * channels); + assert_eq!(theirs.len(), 4096 * 3 * channels); + let alt: Vec = tags.iter().flat_map(|t| alt_swf_decode(t, channels)).collect(); + same_as_either(&format!("swf {channels}ch"), &ours, &alt, &theirs); + // ffmpeg decodes ours, one 4096-sample stream per tag + for bits in [2u32, 3, 4, 5] { + let tags: Vec> = x.chunks(4096 * channels).map(|c| swf::encode(c, channels, bits).expect("encode")).collect(); + let ours: Vec = tags.iter().flat_map(|t| swf::decode(t, channels).expect("decode")).collect(); + let file = dir.join(format!("our_swf{channels}_{bits}.flv")); + std::fs::write(&file, flv(channels == 2, &tags)).expect("write"); + let back = dir.join(format!("our_swf{channels}_{bits}.pcm")); + ffmpeg(&ff, &["-i", &s(&file), "-f", "s16le", "-acodec", "pcm_s16le", &s(&back)]); + let theirs = read_pcm(&back); + assert_eq!(ours.len(), 4096 * 3 * channels); + assert_eq!(theirs.len(), 4096 * 3 * channels); + let alt: Vec = tags.iter().flat_map(|t| alt_swf_decode(t, channels)).collect(); + same_as_either(&format!("swf {channels}ch {bits} bits, our stream"), &ours, &alt, &theirs); + } + } +} diff --git a/crates/audio/tests/audio/wav_empty_data.rs b/crates/audio/tests/audio/wav_empty_data.rs index 8ae622d50..338b9bd33 100644 --- a/crates/audio/tests/audio/wav_empty_data.rs +++ b/crates/audio/tests/audio/wav_empty_data.rs @@ -73,3 +73,64 @@ fn many_empty_data_chunks_parse_in_linear_time() { assert_eq!(info.frames, 0); assert_eq!(decode(&b, Some("wav")).unwrap().1.frames(), 0); } + +/// fmt (mono 16-bit), an empty `data` chunk, then an 8-byte `LIST` chunk (#2123). +fn empty_data_then_list() -> Vec { + riff(&[chunk(b"fmt ", &fmt16(1, 8000)), chunk(b"data", &[]), chunk(b"LIST", b"INFOabcd")]) +} + +/// An empty `data` chunk followed by a `LIST` chunk holds no audio, whether the RIFF size counts +/// the `LIST` chunk or was written before it was appended (#2123): the `LIST` chunk's bytes are +/// never decoded as samples. +#[test] +fn an_empty_data_chunk_followed_by_a_list_chunk_is_no_audio_whatever_the_riff_size() { + let correct = empty_data_then_list(); + // The RIFF size a writer put down before appending the LIST chunk. + let mut stale = correct.clone(); + let before_list = (stale.len() - 8 - 16) as u32; + stale[4..8].copy_from_slice(&before_list.to_le_bytes()); + // A RIFF size past the end of the file. + let mut past = correct.clone(); + past[4..8].copy_from_slice(&u32::MAX.to_le_bytes()); + for (name, file) in [("correct", &correct), ("stale", &stale), ("past the end", &past)] { + assert_eq!(probe(file, Some("wav")).unwrap().frames, 0, "{name} RIFF size: probe"); + assert_eq!(decode(file, Some("wav")).unwrap().1.frames(), 0, "{name} RIFF size: decode"); + } +} + +/// Bytes after an empty `data` chunk that only look like the start of a chunk are a recording that +/// was never finalised: a `LIST` id whose size runs past the file, or a cut-off header, stays +/// audio, as the bytes of PCM can spell any id. +#[test] +fn an_empty_data_chunk_followed_by_a_broken_chunk_header_is_still_audio() { + let base = riff(&[chunk(b"fmt ", &fmt16(1, 8000)), chunk(b"data", &[])]); + let stale = |tail: &[u8]| { + let mut f = base.clone(); + f.extend_from_slice(tail); + f + }; + // A LIST id whose size runs past the end of the file: 12 bytes, 6 frames. + assert_eq!(decode(&stale(b"LIST\0\x10\0\0INFO"), Some("wav")).unwrap().1.frames(), 6); + // A LIST id with a cut-off size field: 6 bytes, 3 frames. + assert_eq!(decode(&stale(b"LIST\0\0"), Some("wav")).unwrap().1.frames(), 3); +} + +/// A WAV with samples in a sized `data` chunk and a `LIST` chunk after it decodes exactly as +/// before: its samples, not the `LIST` chunk. +#[test] +fn a_sized_data_chunk_followed_by_a_list_chunk_decodes_its_samples() { + let samples: Vec = (0..64).map(|i| i * 300 - 9000).collect(); + let bytes: Vec = samples.iter().flat_map(|s| s.to_le_bytes()).collect(); + let file = riff(&[chunk(b"fmt ", &fmt16(1, 8000)), chunk(b"data", &bytes), chunk(b"LIST", b"INFOabcd")]); + let (info, buf) = decode(&file, Some("wav")).unwrap(); + assert_eq!(info.frames, 64); + assert_eq!(buf.frames(), 64); + let mut stale = file.clone(); + let before_list = (stale.len() - 8 - 16) as u32; + stale[4..8].copy_from_slice(&before_list.to_le_bytes()); + let (_, stale_buf) = decode(&stale, Some("wav")).unwrap(); + assert_eq!(stale_buf.frames(), 64, "a stale RIFF size does not change a sized data chunk"); + assert_eq!(stale_buf, buf, "the same samples"); + let expected: Vec = samples.iter().map(|s| f32::from(*s) / 32768.0).collect(); + assert_eq!(buf.interleaved(), expected, "the data chunk's samples"); +} diff --git a/crates/audio/tests/dsd_bounds.rs b/crates/audio/tests/dsd_bounds.rs new file mode 100644 index 000000000..5388f2aa4 --- /dev/null +++ b/crates/audio/tests/dsd_bounds.rs @@ -0,0 +1,208 @@ +//! Hostile container sizes must return errors, never wrap offsets or panic. +use craft_audio::dsd::{BitOrder, Error, RawAudio, encode_dsdiff, encode_dsf, read_metadata, read_raw}; + +#[test] +fn dsf_untrusted_sizes_are_checked() { + let original = encode_dsf(2_822_400, &[&[0x69; 8]], 64, 8).unwrap(); + for offset in [32, 84] { + // fmt and data chunk sizes + for size in [u64::MAX, u64::MAX - 31, 1 << 32] { + let mut bytes = original.clone(); + bytes[offset..offset + 8].copy_from_slice(&size.to_le_bytes()); + assert!(read_metadata(&bytes).is_err()); + assert!(read_raw(&bytes).is_err()); + } + } + let mut bytes = original; + bytes[64..72].copy_from_slice(&u64::MAX.to_le_bytes()); + assert_eq!(read_raw(&bytes), Err(Error::MemoryLimitExceeded)); +} + +#[test] +fn dsdiff_untrusted_top_level_and_property_sizes_are_checked() { + let original = encode_dsdiff(2_822_400, &[&[0xaa; 8]], 64).unwrap(); + let prop = original.windows(4).position(|w| w == b"PROP").unwrap(); + for offset in [4, 20, prop + 20] { + // FRM8, FVER, nested FS + for size in [u64::MAX, u64::MAX - 31, 1 << 32] { + let mut bytes = original.clone(); + bytes[offset..offset + 8].copy_from_slice(&size.to_be_bytes()); + assert!(read_metadata(&bytes).is_err()); + assert!(read_raw(&bytes).is_err()); + } + } +} + +#[test] +fn dsdiff_invalid_optional_disc_info_is_ignored_without_overflow() { + let mut bytes = encode_dsdiff(2_822_400, &[&[0xaa; 8]], 64).unwrap(); + let expected = read_metadata(&bytes).unwrap(); + bytes.extend_from_slice(b"DIIN"); + bytes.extend_from_slice(&12u64.to_be_bytes()); + bytes.extend_from_slice(b"DITI"); + bytes.extend_from_slice(&u64::MAX.to_be_bytes()); + let size = (bytes.len() - 12) as u64; + bytes[4..12].copy_from_slice(&size.to_be_bytes()); + // Optional malformed text is ignored on 64-bit; unrepresentable sizes may + // be rejected on narrower targets, but must never wrap or panic. + match read_metadata(&bytes) { + Ok(actual) => assert_eq!(actual, expected), + Err(Error::MemoryLimitExceeded) => {} + other => panic!("unexpected result: {other:?}"), + } +} + +#[test] +fn empty_raw_audio_rejects_invalid_decimation_factors() { + let bytes = encode_dsf(2_822_400, &[&[]], 0, 8).unwrap(); + let raw = RawAudio { metadata: read_metadata(&bytes).unwrap(), bit_order: BitOrder::LsbFirst, channel_bytes: Vec::new() }; + for factor in [0, 1, 7, 9, u32::MAX] { + assert!(matches!(raw.to_pcm_with_factor(factor), Err(Error::Unsupported(_)))); + } + for factor in [8, 16, 32, 64] { + assert_eq!(raw.to_pcm_with_factor(factor).unwrap().sample_rate, 2_822_400 / factor); + } +} + +#[test] +fn writers_reject_unbounded_output_before_allocating() { + let channels: [&[u8]; 8] = [&[]; 8]; + for count in [u64::MAX, (craft_audio::dsd::MAX_ENCODE_BYTES as u64 + 1) * 8] { + assert_eq!(encode_dsf(2_822_400, &channels, count, 8), Err(Error::MemoryLimitExceeded)); + assert_eq!(encode_dsdiff(2_822_400, &channels, count), Err(Error::MemoryLimitExceeded)); + } + assert!(matches!(encode_dsf(2_822_400, &[&[]], 0, u32::MAX), Err(Error::InvalidData(_)))); +} + +#[test] +fn encoded_sizes_match_actual_bytes_for_odd_and_even_payloads() { + for channels in 1..=8 { + for len in 0..=9 { + let data = vec![0x69; len]; + let planes = vec![data.as_slice(); channels]; + for block in [0, 1, 3, 8] { + // DSF has channel types for 1 to 6 channels only. + if channels > 6 { + assert!(matches!(encode_dsf(2_822_400, &planes, len as u64 * 8, block), Err(Error::Unsupported(_)))); + continue; + } + let dsf = encode_dsf(2_822_400, &planes, len as u64 * 8, block).unwrap(); + assert_eq!(u64::from_le_bytes(dsf[12..20].try_into().unwrap()), dsf.len() as u64); + assert_eq!(read_raw(&dsf).unwrap().channel_bytes, vec![data.clone(); channels]); + } + let dff = encode_dsdiff(2_822_400, &planes, len as u64 * 8).unwrap(); + assert_eq!(u64::from_be_bytes(dff[4..12].try_into().unwrap()) + 12, dff.len() as u64); + assert_eq!(read_raw(&dff).unwrap().channel_bytes, vec![data; channels]); + } + } +} + +#[test] +fn dsf_audio_stops_at_the_declared_data_chunk() { + for channels in 1..=2 { + let input = vec![&[0x33u8; 8][..]; channels]; + let mut bytes = encode_dsf(2_822_400, &input, 64, 8).unwrap(); + // Ask for an additional block without extending the data chunk. + bytes[64..72].copy_from_slice(&128u64.to_le_bytes()); + let expected = read_raw(&bytes).unwrap(); + for c in &expected.channel_bytes { + assert_eq!(&c[..8], &[0x33; 8]); + assert_eq!(&c[8..], &[0x69; 8]); + } + let metadata_offset = bytes.len() as u64; + bytes[20..28].copy_from_slice(&metadata_offset.to_le_bytes()); + bytes.extend_from_slice(b"ID3\x04\x00\x00\x00\x00\x00\x00"); + bytes.extend_from_slice(&[0xff; 32]); + let file_size = bytes.len() as u64; + bytes[12..20].copy_from_slice(&file_size.to_le_bytes()); + assert_eq!(read_raw(&bytes).unwrap().channel_bytes, expected.channel_bytes); + } +} + +#[test] +fn dsdiff_odd_payload_receives_pad_byte() { + let input = [&[0xaau8; 3][..]]; + let bytes = encode_dsdiff(2_822_400, &input, 24).unwrap(); + let raw = read_raw(&bytes).unwrap(); + assert_eq!(raw.channel_bytes[0].len(), 3); +} + +#[test] +fn dsf_declared_file_size_and_metadata_pointer_bounds() { + let valid = encode_dsf(2_822_400, &[&[0x69; 8]], 64, 8).unwrap(); + + // Undersized file size declaration (e.g. 28) + let mut undersized = valid.clone(); + undersized[12..20].copy_from_slice(&28u64.to_le_bytes()); + assert!(read_metadata(&undersized).is_err()); + assert!(read_raw(&undersized).is_err()); + + // Oversized file size declaration beyond buffer + let mut oversized = valid.clone(); + let big_size = valid.len() as u64 + 100; + oversized[12..20].copy_from_slice(&big_size.to_le_bytes()); + assert!(read_metadata(&oversized).is_err()); + assert!(read_raw(&oversized).is_err()); + + // Metadata pointer outside the declared file bounds + let mut outside_meta = valid.clone(); + let outside_offset = valid.len() as u64 + 10; + outside_meta[20..28].copy_from_slice(&outside_offset.to_le_bytes()); + assert!(read_metadata(&outside_meta).is_err()); + assert!(read_raw(&outside_meta).is_err()); + + // Metadata pointer overlapping data chunk + let mut overlap_meta = valid.clone(); + overlap_meta[20..28].copy_from_slice(&32u64.to_le_bytes()); + assert!(read_metadata(&overlap_meta).is_err()); + assert!(read_raw(&overlap_meta).is_err()); +} + +#[test] +fn dsdiff_channel_count_and_duplicate_chunks_are_validated() { + let base = encode_dsdiff(2_822_400, &[&[0xaa; 8]], 64).unwrap(); + + // Locate PROP chunk payload and CHNL subchunk + let prop_idx = base.windows(4).position(|w| w == b"PROP").unwrap(); + let chnl_idx = base.windows(4).position(|w| w == b"CHNL").unwrap(); + + // 1. Oversized channel count (e.g. 65535 or 9) + let mut bad_count = base.clone(); + bad_count[chnl_idx + 12..chnl_idx + 14].copy_from_slice(&65535u16.to_be_bytes()); + assert!(matches!(read_metadata(&bad_count), Err(Error::Unsupported(_)))); + assert!(matches!(read_raw(&bad_count), Err(Error::Unsupported(_)))); + + let mut zero_count = base.clone(); + zero_count[chnl_idx + 12..chnl_idx + 14].copy_from_slice(&0u16.to_be_bytes()); + assert!(matches!(read_metadata(&zero_count), Err(Error::Unsupported(_)))); + + // 2. Conflicting duplicate CHNL chunk in PROP + let mut dup_chnl = base.clone(); + let chnl_chunk = dup_chnl[chnl_idx..chnl_idx + 18].to_vec(); + dup_chnl.splice(chnl_idx..chnl_idx, chnl_chunk); + // Adjust PROP size and FRM8 size + let prop_size = u64::from_be_bytes(dup_chnl[prop_idx + 4..prop_idx + 12].try_into().unwrap()) + 18; + dup_chnl[prop_idx + 4..prop_idx + 12].copy_from_slice(&prop_size.to_be_bytes()); + let frm8_size = (dup_chnl.len() - 12) as u64; + dup_chnl[4..12].copy_from_slice(&frm8_size.to_be_bytes()); + assert_eq!(read_metadata(&dup_chnl), Err(Error::InvalidHeader("duplicate CHNL chunk"))); + + // 3. Duplicate FS chunk in PROP + let fs_idx = base.windows(4).position(|w| w == b"FS ").unwrap(); + let mut dup_fs = base.clone(); + let fs_chunk = dup_fs[fs_idx..fs_idx + 16].to_vec(); + dup_fs.splice(fs_idx..fs_idx, fs_chunk); + let prop_size = u64::from_be_bytes(dup_fs[prop_idx + 4..prop_idx + 12].try_into().unwrap()) + 16; + dup_fs[prop_idx + 4..prop_idx + 12].copy_from_slice(&prop_size.to_be_bytes()); + let frm8_size = (dup_fs.len() - 12) as u64; + dup_fs[4..12].copy_from_slice(&frm8_size.to_be_bytes()); + assert_eq!(read_metadata(&dup_fs), Err(Error::InvalidHeader("duplicate FS chunk"))); +} + +#[test] +#[cfg(target_pointer_width = "32")] +fn dsdiff_32bit_padding_overflow_is_rejected() { + let dummy = [&[][..]]; + let result = encode_dsdiff(2_822_400, &dummy, 34_359_738_360); + assert_eq!(result, Err(Error::MemoryLimitExceeded)); +} diff --git a/crates/audio/tests/dsd_metadata.rs b/crates/audio/tests/dsd_metadata.rs new file mode 100644 index 000000000..74fd16f31 --- /dev/null +++ b/crates/audio/tests/dsd_metadata.rs @@ -0,0 +1,155 @@ +//! Channel labels, text metadata and padding in the DSF and DSDIFF readers and writers. +#![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)] +use craft_audio::dsd::{encode_dsdiff, encode_dsf, read_metadata, read_raw}; + +const RATE: u32 = 2_822_400; + +fn planes(channels: usize, len: usize) -> Vec> { + vec![vec![0x69; len]; channels] +} + +fn refs(p: &[Vec]) -> Vec<&[u8]> { + p.iter().map(Vec::as_slice).collect() +} + +#[test] +fn dsdiff_names_surround_channels_by_layout() { + for (n, names) in [ + (5, vec!["Mono/Left", "Right", "Center", "LeftSurround", "RightSurround"]), + (6, vec!["Mono/Left", "Right", "Center", "LFE", "LeftSurround", "RightSurround"]), + ] { + let p = planes(n, 4); + let bytes = encode_dsdiff(RATE, &refs(&p), 32).unwrap(); + assert_eq!(read_metadata(&bytes).unwrap().channel_names, names, "{n} channels"); + } +} + +#[test] +fn dsdiff_odd_audio_is_padded_and_counted_in_the_file_size() { + let p = planes(1, 1); + let bytes = encode_dsdiff(RATE, &refs(&p), 8).unwrap(); + assert_eq!(bytes.len() % 2, 0); + assert_eq!(u64::from_be_bytes(bytes[4..12].try_into().unwrap()) + 12, bytes.len() as u64); + assert_eq!(*bytes.last().unwrap(), 0, "pad byte"); + assert_eq!(read_raw(&bytes).unwrap().channel_bytes, vec![vec![0x69]]); +} + +fn with_diin(mut bytes: Vec, sub: &[u8; 4], payload: &[u8]) -> Vec { + let mut sub_chunk = Vec::new(); + sub_chunk.extend_from_slice(sub); + sub_chunk.extend_from_slice(&(payload.len() as u64).to_be_bytes()); + sub_chunk.extend_from_slice(payload); + if payload.len() % 2 == 1 { + sub_chunk.push(0); + } + bytes.extend_from_slice(b"DIIN"); + bytes.extend_from_slice(&(sub_chunk.len() as u64).to_be_bytes()); + bytes.extend_from_slice(&sub_chunk); + let size = (bytes.len() - 12) as u64; + bytes[4..12].copy_from_slice(&size.to_be_bytes()); + bytes +} + +#[test] +fn dsdiff_title_and_artist_skip_the_character_count() { + let p = planes(2, 4); + let base = encode_dsdiff(RATE, &refs(&p), 32).unwrap(); + let mut payload = 4u32.to_be_bytes().to_vec(); + payload.extend_from_slice(b"Test"); + let bytes = with_diin(base.clone(), b"DITI", &payload); + assert_eq!(read_metadata(&bytes).unwrap().title.as_deref(), Some("Test")); + let bytes = with_diin(base.clone(), b"DIAR", &payload); + assert_eq!(read_metadata(&bytes).unwrap().artist.as_deref(), Some("Test")); + // A count longer than the chunk is not text. + let mut bad = 99u32.to_be_bytes().to_vec(); + bad.extend_from_slice(b"Test"); + assert_eq!(read_metadata(&with_diin(base, b"DITI", &bad)).unwrap().title, None); +} + +#[test] +fn dsf_channel_types_match_the_channel_count() { + for (n, expect) in [(1, 1), (2, 2), (3, 3), (4, 4), (5, 6), (6, 7)] { + let p = planes(n, 4); + let bytes = encode_dsf(RATE, &refs(&p), 32, 4096).unwrap(); + assert_eq!(u32::from_le_bytes(bytes[48..52].try_into().unwrap()), expect, "{n} channels"); + assert_eq!(read_metadata(&bytes).unwrap().channel_names.len(), n); + } + let p = planes(7, 4); + assert!(encode_dsf(RATE, &refs(&p), 32, 4096).is_err()); +} + +#[test] +fn dsf_type_5_names_the_fourth_channel_lfe() { + let p = planes(4, 4); + let mut bytes = encode_dsf(RATE, &refs(&p), 32, 4096).unwrap(); + bytes[48..52].copy_from_slice(&5u32.to_le_bytes()); + assert_eq!(read_metadata(&bytes).unwrap().channel_names, ["FrontLeft", "FrontRight", "Center", "LFE"]); +} + +fn id3(version: u8, frames: &[u8]) -> Vec { + let n = frames.len(); + let mut tag = vec![b'I', b'D', b'3', version, 0, 0]; + tag.extend_from_slice(&[(n >> 21) as u8 & 0x7F, (n >> 14) as u8 & 0x7F, (n >> 7) as u8 & 0x7F, n as u8 & 0x7F]); + tag.extend_from_slice(frames); + tag +} + +fn frame(version: u8, id: &[u8; 4], body: &[u8]) -> Vec { + let n = body.len(); + let mut f = id.to_vec(); + if version >= 4 { + f.extend_from_slice(&[(n >> 21) as u8 & 0x7F, (n >> 14) as u8 & 0x7F, (n >> 7) as u8 & 0x7F, n as u8 & 0x7F]); + } else { + f.extend_from_slice(&(n as u32).to_be_bytes()); + } + f.extend_from_slice(&[0, 0]); + f.extend_from_slice(body); + f +} + +fn dsf_with_tag(tag: &[u8]) -> Vec { + let p = planes(2, 4); + let mut bytes = encode_dsf(RATE, &refs(&p), 32, 4096).unwrap(); + let offset = bytes.len() as u64; + bytes[20..28].copy_from_slice(&offset.to_le_bytes()); + bytes.extend_from_slice(tag); + let file_size = bytes.len() as u64; + bytes[12..20].copy_from_slice(&file_size.to_le_bytes()); + bytes +} + +#[test] +fn id3v24_frame_sizes_are_synchsafe() { + // A 128-byte frame has the synchsafe size 00 00 01 00; read as plain big-endian it is 256. + let mut frames = frame(4, b"APIC", &[0u8; 128]); + let mut title = vec![3]; + title.extend_from_slice(b"After art"); + frames.extend(frame(4, b"TIT2", &title)); + let m = read_metadata(&dsf_with_tag(&id3(4, &frames))).unwrap(); + assert_eq!(m.title.as_deref(), Some("After art")); +} + +#[test] +fn id3v23_frame_sizes_stay_big_endian() { + let mut frames = frame(3, b"APIC", &[0u8; 128]); + let mut title = vec![3]; + title.extend_from_slice(b"Three"); + frames.extend(frame(3, b"TIT2", &title)); + let m = read_metadata(&dsf_with_tag(&id3(3, &frames))).unwrap(); + assert_eq!(m.title.as_deref(), Some("Three")); +} + +#[test] +fn id3_text_encodings() { + let cases: [(&[u8], &str); 5] = [ + (b"\x00Caf\xe9", "Café"), + (b"\x03Caf\xc3\xa9", "Café"), + (b"\x02\x00A\x00B", "AB"), + (b"\x01\xFF\xFEA\x00B\x00", "AB"), + (b"\x01\xFE\xFF\x00A\x00B", "AB"), + ]; + for (body, expect) in cases { + let m = read_metadata(&dsf_with_tag(&id3(4, &frame(4, b"TIT2", body)))).unwrap(); + assert_eq!(m.title.as_deref(), Some(expect), "{body:?}"); + } +} diff --git a/crates/audio/tests/dsd_oracle.rs b/crates/audio/tests/dsd_oracle.rs new file mode 100644 index 000000000..94334485b --- /dev/null +++ b/crates/audio/tests/dsd_oracle.rs @@ -0,0 +1,347 @@ +//! DSD (DSF and DSDIFF) decoding and decimation tests, including oracle tests against FFmpeg +//! (skipped when ffmpeg is absent, a failure with `CRAFT_MEDIA_REQUIRE_ORACLES=1`). + +use craft_audio::dsd::{BitOrder, Format, decode, decode_with_factor, encode_dsdiff, encode_dsf, filter::SILENCE_LSBF, read_metadata, read_raw}; +use std::process::Command; + +/// Generates a test DSD 1-bit stream with various features (silence, alternating tones, noise). +fn make_test_stream(num_bytes: usize, seed: u8) -> Vec { + let mut out = Vec::with_capacity(num_bytes); + let mut s = seed as u32; + for i in 0..num_bytes { + s ^= s << 13; + s ^= s >> 17; + s ^= s << 5; + let byte = match (i / 128) % 4 { + 0 => SILENCE_LSBF, // DSD silence + 1 => 0x55, // Alternate silence pattern + 2 => (s & 0xFF) as u8, + _ => { + if (i / 16) % 2 == 0 { + 0xFF // full positive level + } else { + 0x00 // full negative level + } + } + }; + out.push(byte); + } + out +} + +#[test] +fn roundtrip_dsf() { + let sample_rate = 2_822_400; + let block_size = 4096; + let ch0 = make_test_stream(8192, 42); + let ch1 = make_test_stream(8192, 99); + let sample_count = 8192 * 8; + + let dsf_bytes = encode_dsf(sample_rate, &[&ch0, &ch1], sample_count, block_size).expect("encode_dsf"); + + let meta = read_metadata(&dsf_bytes).expect("read_metadata"); + assert_eq!(meta.format, Format::Dsf); + assert_eq!(meta.sample_rate, sample_rate); + assert_eq!(meta.channels, 2); + assert_eq!(meta.sample_count, sample_count); + + let raw = read_raw(&dsf_bytes).expect("read_raw"); + assert_eq!(raw.bit_order, BitOrder::LsbFirst); + assert_eq!(raw.channel_bytes.len(), 2); + assert_eq!(raw.channel_bytes[0], ch0); + assert_eq!(raw.channel_bytes[1], ch1); + + let decoded = decode(&dsf_bytes).expect("decode"); + assert_eq!(decoded.sample_rate, sample_rate / 8); + assert_eq!(decoded.channels.len(), 2); + assert_eq!(decoded.channels[0].len(), 8192); + assert_eq!(decoded.channels[1].len(), 8192); +} + +#[test] +fn roundtrip_dsdiff() { + let sample_rate = 2_822_400; + let ch0 = make_test_stream(4096, 17); + let ch1 = make_test_stream(4096, 73); + let sample_count = 4096 * 8; + + let dff_bytes = encode_dsdiff(sample_rate, &[&ch0, &ch1], sample_count).expect("encode_dsdiff"); + + let meta = read_metadata(&dff_bytes).expect("read_metadata"); + assert_eq!(meta.format, Format::Dsdiff); + assert_eq!(meta.sample_rate, sample_rate); + assert_eq!(meta.channels, 2); + assert_eq!(meta.sample_count, sample_count); + + let raw = read_raw(&dff_bytes).expect("read_raw"); + assert_eq!(raw.bit_order, BitOrder::MsbFirst); + assert_eq!(raw.channel_bytes.len(), 2); + assert_eq!(raw.channel_bytes[0], ch0); + assert_eq!(raw.channel_bytes[1], ch1); + + let decoded = decode(&dff_bytes).expect("decode"); + assert_eq!(decoded.sample_rate, sample_rate / 8); + assert_eq!(decoded.channels.len(), 2); + assert_eq!(decoded.channels[0].len(), 4096); + assert_eq!(decoded.channels[1].len(), 4096); +} + +#[test] +fn decimation_factors() { + let sample_rate = 2_822_400; + let ch0 = make_test_stream(2048, 123); + let dsf_bytes = encode_dsf(sample_rate, &[&ch0], 2048 * 8, 4096).expect("encode_dsf"); + + // Factor 8 -> 352,800 Hz + let dec8 = decode_with_factor(&dsf_bytes, 8).expect("factor 8"); + assert_eq!(dec8.sample_rate, 352_800); + assert_eq!(dec8.channels[0].len(), 2048); + + // Factor 16 -> 176,400 Hz + let dec16 = decode_with_factor(&dsf_bytes, 16).expect("factor 16"); + assert_eq!(dec16.sample_rate, 176_400); + assert_eq!(dec16.channels[0].len(), 1024); + + // Factor 32 -> 88,200 Hz + let dec32 = decode_with_factor(&dsf_bytes, 32).expect("factor 32"); + assert_eq!(dec32.sample_rate, 88_200); + assert_eq!(dec32.channels[0].len(), 512); + + // Factor 64 -> 44,100 Hz + let dec64 = decode_with_factor(&dsf_bytes, 64).expect("factor 64"); + assert_eq!(dec64.sample_rate, 44_100); + assert_eq!(dec64.channels[0].len(), 256); + + // Invalid factor + assert!(decode_with_factor(&dsf_bytes, 12).is_err()); +} + +#[test] +fn silence_and_dc_levels() { + let sample_rate = 2_822_400; + // Pure silence + let silence = vec![SILENCE_LSBF; 1024]; + let dsf_bytes = encode_dsf(sample_rate, &[&silence], 1024 * 8, 4096).expect("encode"); + let dec = decode(&dsf_bytes).expect("decode"); + for &sample in &dec.channels[0][12..] { + assert!(sample.abs() < 1e-4, "silence sample should be ~0.0, got {sample}"); + } + + // Full positive level + let ones = vec![0xFF; 1024]; + let dsf_ones = encode_dsf(sample_rate, &[&ones], 1024 * 8, 4096).expect("encode"); + let dec_ones = decode(&dsf_ones).expect("decode"); + for &sample in &dec_ones.channels[0][12..] { + assert!((sample - 1.0).abs() < 1e-4, "ones sample should be ~1.0, got {sample}"); + } + + // Full negative level + let zeros = vec![0x00; 1024]; + let dsf_zeros = encode_dsf(sample_rate, &[&zeros], 1024 * 8, 4096).expect("encode"); + let dec_zeros = decode(&dsf_zeros).expect("decode"); + for &sample in &dec_zeros.channels[0][12..] { + assert!((sample - (-1.0)).abs() < 1e-4, "zeros sample should be ~-1.0, got {sample}"); + } +} + +#[test] +fn multichannel_dsf_and_dsdiff() { + let sample_rate = 2_822_400; + // Test 6-channel (5.1 surround) + let channels: Vec> = (0..6).map(|c| make_test_stream(1024, (c * 23 + 5) as u8)).collect(); + let ch_refs: Vec<&[u8]> = channels.iter().map(Vec::as_slice).collect(); + + let dsf = encode_dsf(sample_rate, &ch_refs, 1024 * 8, 512).expect("encode 5.1 dsf"); + let dsf_meta = read_metadata(&dsf).expect("meta 5.1 dsf"); + assert_eq!(dsf_meta.channels, 6); + let dsf_dec = decode(&dsf).expect("decode 5.1 dsf"); + assert_eq!(dsf_dec.channels.len(), 6); + assert_eq!(dsf_dec.channels[0].len(), 1024); + + let dff = encode_dsdiff(sample_rate, &ch_refs, 1024 * 8).expect("encode 5.1 dsdiff"); + let dff_meta = read_metadata(&dff).expect("meta 5.1 dsdiff"); + assert_eq!(dff_meta.channels, 6); + let dff_dec = decode(&dff).expect("decode 5.1 dsdiff"); + assert_eq!(dff_dec.channels.len(), 6); + assert_eq!(dff_dec.channels[0].len(), 1024); +} + +#[test] +fn dst_compression_rejected() { + // Construct a minimal DSDIFF with CMPR = 'DST ' + let mut dff = encode_dsdiff(2_822_400, &[&[0xAA; 64]], 512).expect("encode"); + // Find 'DSD ' in CMPR chunk and replace with 'DST ' + let mut replaced = false; + for i in 0..dff.len().saturating_sub(8) { + if &dff[i..i + 4] == b"CMPR" && &dff[i + 12..i + 16] == b"DSD " { + dff[i + 12..i + 16].copy_from_slice(b"DST "); + replaced = true; + break; + } + } + assert!(replaced, "should find CMPR DSD chunk"); + assert!(read_metadata(&dff).is_err(), "DST compression should be rejected as unsupported"); + assert!(decode(&dff).is_err(), "DST compression should be rejected as unsupported"); +} + +#[test] +fn id3v2_tag_in_dsf() { + let sample_rate = 2_822_400; + let mut dsf = encode_dsf(sample_rate, &[&[0x69; 128]], 1024, 512).expect("encode"); + let metadata_offset = dsf.len() as u64; + + // Append simple ID3v2.3 tag with TIT2="Test Title" and TPE1="Test Artist" + let mut id3 = Vec::new(); + id3.extend_from_slice(b"ID3"); + id3.push(3); // v2.3 + id3.push(0); // revision + id3.push(0); // flags + + let mut frames = Vec::new(); + // TIT2 frame + frames.extend_from_slice(b"TIT2"); + let title_bytes = b"\x03DSD Master"; // UTF-8 + frames.extend_from_slice(&(title_bytes.len() as u32).to_be_bytes()); + frames.extend_from_slice(&[0, 0]); // flags + frames.extend_from_slice(title_bytes); + + // TPE1 frame + frames.extend_from_slice(b"TPE1"); + let artist_bytes = b"\x03The Audiophiles"; + frames.extend_from_slice(&(artist_bytes.len() as u32).to_be_bytes()); + frames.extend_from_slice(&[0, 0]); // flags + frames.extend_from_slice(artist_bytes); + + // synchsafe size + let tag_len = frames.len(); + id3.push(((tag_len >> 21) & 0x7F) as u8); + id3.push(((tag_len >> 14) & 0x7F) as u8); + id3.push(((tag_len >> 7) & 0x7F) as u8); + id3.push((tag_len & 0x7F) as u8); + id3.extend_from_slice(&frames); + + dsf.extend_from_slice(&id3); + // Update file size and metadata_offset of 'DSD ' chunk + let file_size = dsf.len() as u64; + dsf[12..20].copy_from_slice(&file_size.to_le_bytes()); + dsf[20..28].copy_from_slice(&metadata_offset.to_le_bytes()); + + let meta = read_metadata(&dsf).expect("read metadata with ID3"); + assert_eq!(meta.title.as_deref(), Some("DSD Master")); + assert_eq!(meta.artist.as_deref(), Some("The Audiophiles")); +} + +#[test] +fn raw_audio_bit_order_conversion() { + let ch0 = vec![0b00000001, 0b10000000]; + let dsf = encode_dsf(2_822_400, &[&ch0], 16, 512).expect("encode"); + let mut raw = read_raw(&dsf).expect("read raw"); + assert_eq!(raw.bit_order, BitOrder::LsbFirst); + assert_eq!(raw.channel_bytes[0], ch0); + + raw.convert_bit_order(BitOrder::MsbFirst); + assert_eq!(raw.bit_order, BitOrder::MsbFirst); + assert_eq!(raw.channel_bytes[0], vec![0b10000000, 0b00000001]); +} + +#[test] +fn hostile_inputs() { + // Truncated headers + assert!(read_metadata(b"").is_err()); + assert!(read_metadata(b"DSD ").is_err()); + assert!(read_metadata(b"FRM8").is_err()); + + // Bad magic + assert!(read_metadata(b"RIFF\x00\x00\x00\x00WAVE").is_err()); + + // Truncated DSF chunk + let mut bad_dsf = encode_dsf(2_822_400, &[&[0x69; 100]], 800, 4096).expect("encode"); + bad_dsf.truncate(50); + assert!(decode(&bad_dsf).is_err()); + + // Corrupted fmt chunk size + let mut bad_fmt = encode_dsf(2_822_400, &[&[0x69; 100]], 800, 4096).expect("encode"); + bad_fmt[32] = 0; // bits_per_sample = 0 + assert!(decode(&bad_fmt).is_err()); + + // Absurd channels + let mut bad_ch = encode_dsf(2_822_400, &[&[0x69; 100]], 800, 4096).expect("encode"); + bad_ch[28 + 24] = 99; // channel_count = 99 + assert!(decode(&bad_ch).is_err()); +} + +#[test] +fn ffmpeg_dsf_oracle() { + let Some(ffmpeg) = craft_media_testkit::ffmpeg() else { return }; + let dir = craft_media_testkit::fixture_subdir("dsd"); + + let sample_rate = 2_822_400; + let block_size = 4096; + let ch0 = make_test_stream(16384, 11); + let ch1 = make_test_stream(16384, 88); + let sample_count = 16384 * 8; + + let dsf_bytes = encode_dsf(sample_rate, &[&ch0, &ch1], sample_count, block_size).expect("encode_dsf"); + let dsf_path = dir.join("test_oracle.dsf"); + std::fs::write(&dsf_path, &dsf_bytes).expect("write fixture"); + + let raw_out_path = dir.join("ffmpeg_dsf.raw"); + let status = Command::new(&ffmpeg).arg("-y").arg("-i").arg(&dsf_path).arg("-f").arg("f32le").arg(&raw_out_path).output().expect("run ffmpeg"); + assert!(status.status.success(), "ffmpeg failed: {}", String::from_utf8_lossy(&status.stderr)); + + let raw_bytes = std::fs::read(&raw_out_path).expect("read raw"); + let ffmpeg_floats: Vec = raw_bytes.as_chunks::<4>().0.iter().map(|c| f32::from_le_bytes([c[0], c[1], c[2], c[3]])).collect(); + + let decoded = decode(&dsf_bytes).expect("our decode"); + assert_eq!(decoded.channels.len(), 2); + assert_eq!(decoded.channels[0].len(), 16384); + assert_eq!(decoded.channels[1].len(), 16384); + + // FFmpeg interleaves L0, R0, L1, R1... + // Compare samples after filter startup (sample 12 onwards). + for i in 12..16000 { + let ff_l = ffmpeg_floats[i * 2]; + let ff_r = ffmpeg_floats[i * 2 + 1]; + let our_l = decoded.channels[0][i]; + let our_r = decoded.channels[1][i]; + + assert!((ff_l - our_l).abs() < 1e-4, "sample {i} left mismatch: ffmpeg={ff_l}, ours={our_l}"); + assert!((ff_r - our_r).abs() < 1e-4, "sample {i} right mismatch: ffmpeg={ff_r}, ours={our_r}"); + } +} + +#[test] +fn ffmpeg_dsdiff_oracle() { + let Some(ffmpeg) = craft_media_testkit::ffmpeg() else { return }; + let dir = craft_media_testkit::fixture_subdir("dsd"); + + let sample_rate = 2_822_400; + let ch0 = make_test_stream(8192, 33); + let ch1 = make_test_stream(8192, 77); + let sample_count = 8192 * 8; + + let dff_bytes = encode_dsdiff(sample_rate, &[&ch0, &ch1], sample_count).expect("encode_dsdiff"); + let dff_path = dir.join("test_oracle.dff"); + std::fs::write(&dff_path, &dff_bytes).expect("write fixture"); + + let raw_out_path = dir.join("ffmpeg_dff.raw"); + let status = Command::new(&ffmpeg).arg("-y").arg("-i").arg(&dff_path).arg("-f").arg("f32le").arg(&raw_out_path).output().expect("run ffmpeg"); + assert!(status.status.success(), "ffmpeg failed: {}", String::from_utf8_lossy(&status.stderr)); + + let raw_bytes = std::fs::read(&raw_out_path).expect("read raw"); + let ffmpeg_floats: Vec = raw_bytes.as_chunks::<4>().0.iter().map(|c| f32::from_le_bytes([c[0], c[1], c[2], c[3]])).collect(); + + let decoded = decode(&dff_bytes).expect("our decode"); + assert_eq!(decoded.channels.len(), 2); + assert_eq!(decoded.channels[0].len(), 8192); + + for i in 12..8000 { + let ff_l = ffmpeg_floats[i * 2]; + let ff_r = ffmpeg_floats[i * 2 + 1]; + let our_l = decoded.channels[0][i]; + let our_r = decoded.channels[1][i]; + + assert!((ff_l - our_l).abs() < 1e-4, "sample {i} left mismatch: ffmpeg={ff_l}, ours={our_l}"); + assert!((ff_r - our_r).abs() < 1e-4, "sample {i} right mismatch: ffmpeg={ff_r}, ours={our_r}"); + } +} diff --git a/crates/audio/tests/g722_oracle.rs b/crates/audio/tests/g722_oracle.rs new file mode 100644 index 000000000..3da059011 --- /dev/null +++ b/crates/audio/tests/g722_oracle.rs @@ -0,0 +1,201 @@ +//! ITU-T G.722 SB-ADPCM tests and FFmpeg oracle comparisons. +//! +//! Skipped when FFmpeg is not found, unless `CRAFT_MEDIA_REQUIRE_ORACLES=1` is set. + +use craft_audio::g722::{Decoder, Encoder, Error, decode, decode_interleaved, encode, encode_interleaved}; +use std::process::Command; + +fn generate_signal(samples: usize, freq: f64) -> Vec { + (0..samples) + .map(|i| { + let t = i as f64 / 16000.0; + let val = (2.0 * std::f64::consts::PI * freq * t).sin() * 10000.0; + val as i16 + }) + .collect() +} + +#[test] +fn test_silence_roundtrip() { + let pcm = vec![0i16; 640]; + let encoded = encode(&pcm).expect("encode"); + assert_eq!(encoded.len(), 320); + let decoded = decode(&encoded).expect("decode"); + assert_eq!(decoded.len(), 640); + for &s in &decoded[40..] { + assert!(s.abs() <= 6, "silence sample out of bounds: {s}"); + } +} + +#[test] +fn test_sine_wave_roundtrip_fidelity() { + let pcm = generate_signal(1600, 1000.0); + let encoded = encode(&pcm).expect("encode"); + let decoded = decode(&encoded).expect("decode"); + assert_eq!(decoded.len(), pcm.len()); + + // Compute normalized cross-correlation accounting for filter group delay (approx 22 samples) + let delay = 22; + let mut num = 0.0; + let mut den_orig = 0.0; + let mut den_dec = 0.0; + for i in 0..(pcm.len() - delay) { + let o = pcm[i] as f64; + let d = decoded[i + delay] as f64; + num += o * d; + den_orig += o * o; + den_dec += d * d; + } + let corr = num / (den_orig.sqrt() * den_dec.sqrt()); + assert!(corr > 0.98, "reconstructed sine wave correlation too low: {corr}"); +} + +#[test] +fn test_stereo_multichannel_roundtrip() { + let left = generate_signal(800, 440.0); + let right = generate_signal(800, 880.0); + let mut interleaved = Vec::with_capacity(1600); + for i in 0..800 { + interleaved.push(left[i]); + interleaved.push(right[i]); + } + let encoded = encode_interleaved(&interleaved, 2).expect("encode stereo"); + assert_eq!(encoded.len(), 800); + let decoded = decode_interleaved(&encoded, 2).expect("decode stereo"); + assert_eq!(decoded.len(), 1600); +} + +#[test] +fn test_hostile_inputs_do_not_crash() { + let garbage = [0xFF, 0x00, 0xAA, 0x55, 0x12, 0x34, 0x89, 0xFE]; + let decoded = decode(&garbage).expect("decode garbage"); + assert_eq!(decoded.len(), 16); + + assert_eq!(encode(&[1, 2, 3]), Err(Error::OddSampleCount(3))); + assert_eq!(decode_interleaved(&[0; 8], 0), Err(Error::InvalidChannels(0))); + assert_eq!(decode_interleaved(&[0; 8], 9), Err(Error::InvalidChannels(9))); +} + +#[test] +fn test_encoder_and_decoder_reset() { + let mut enc = Encoder::new(); + let mut dec = Decoder::new(); + let pcm = generate_signal(200, 1000.0); + + let mut out1 = Vec::new(); + enc.encode(&pcm, &mut out1).expect("enc 1"); + let mut dec1 = Vec::new(); + dec.decode(&out1, &mut dec1).expect("dec 1"); + + enc.reset(); + dec.reset(); + + let mut out2 = Vec::new(); + enc.encode(&pcm, &mut out2).expect("enc 2"); + let mut dec2 = Vec::new(); + dec.decode(&out2, &mut dec2).expect("dec 2"); + + assert_eq!(out1, out2); + assert_eq!(dec1, dec2); +} + +#[test] +fn test_ffmpeg_g722_oracle_encoder_and_decoder() { + let Some(ff) = craft_media_testkit::ffmpeg() else { return }; + let dir = craft_media_testkit::fixture_subdir("g722_oracle"); + + // 1. Generate test 1000 Hz tone at 16 kHz mono (800 samples = 0.05s) + let pcm = generate_signal(800, 1000.0); + let pcm_path = dir.join("input.s16le"); + let mut pcm_bytes = Vec::with_capacity(pcm.len() * 2); + for &s in &pcm { + pcm_bytes.extend_from_slice(&s.to_le_bytes()); + } + std::fs::write(&pcm_path, &pcm_bytes).expect("write pcm"); + + // 2. FFmpeg encodes the PCM to G.722 + let ff_g722_path = dir.join("ffmpeg.g722"); + let out = Command::new(&ff) + .args(["-y", "-f", "s16le", "-ar", "16000", "-ac", "1", "-i"]) + .arg(&pcm_path) + .args(["-f", "g722"]) + .arg(&ff_g722_path) + .output() + .expect("ffmpeg encode"); + assert!(out.status.success(), "ffmpeg encode failed: {}", String::from_utf8_lossy(&out.stderr)); + let ff_g722_bytes = std::fs::read(&ff_g722_path).expect("read ff g722"); + + // 3. FFmpeg decodes its own G.722 back to PCM + let ff_pcm_back_path = dir.join("ff_back.s16le"); + let out = Command::new(&ff) + .args(["-y", "-f", "g722", "-i"]) + .arg(&ff_g722_path) + .args(["-f", "s16le", "-ar", "16000", "-ac", "1"]) + .arg(&ff_pcm_back_path) + .output() + .expect("ffmpeg decode"); + assert!(out.status.success(), "ffmpeg decode failed: {}", String::from_utf8_lossy(&out.stderr)); + let ff_back_bytes = std::fs::read(&ff_pcm_back_path).expect("read ff back pcm"); + let ff_back_samples: Vec = ff_back_bytes.as_chunks::<2>().0.iter().map(|c| i16::from_le_bytes(*c)).collect(); + + // 4. Our decoder decodes FFmpeg's G.722 stream + let our_decoded_from_ff = decode(&ff_g722_bytes).expect("our decode of ff stream"); + assert_eq!(our_decoded_from_ff.len(), ff_back_samples.len()); + + // Verify sample-by-sample match against FFmpeg decoder: within ±1 LSB tolerance + let mut max_diff: i32 = 0; + for (i, (&ours, &theirs)) in our_decoded_from_ff.iter().zip(&ff_back_samples).enumerate() { + let diff = (ours as i32 - theirs as i32).abs(); + if diff > max_diff { + max_diff = diff; + } + assert!(diff <= 1, "sample {i} mismatch between our decoder and FFmpeg decoder: ours {ours}, theirs {theirs}"); + } + assert!(max_diff <= 1, "max diff {max_diff} exceeded tolerance"); + + // 5. Our encoder encodes the PCM to G.722 + let our_encoded_bytes = encode(&pcm).expect("our encode"); + let our_g722_path = dir.join("ours.g722"); + std::fs::write(&our_g722_path, &our_encoded_bytes).expect("write our g722"); + + // 6. FFmpeg decodes our encoded G.722 stream + let our_decoded_by_ff_path = dir.join("our_by_ff.s16le"); + let out = Command::new(&ff) + .args(["-y", "-f", "g722", "-i"]) + .arg(&our_g722_path) + .args(["-f", "s16le", "-ar", "16000", "-ac", "1"]) + .arg(&our_decoded_by_ff_path) + .output() + .expect("ffmpeg decode of our stream"); + assert!(out.status.success(), "ffmpeg decode of our stream failed: {}", String::from_utf8_lossy(&out.stderr)); + let our_by_ff_bytes = std::fs::read(&our_decoded_by_ff_path).expect("read our by ff pcm"); + let our_by_ff_samples: Vec = our_by_ff_bytes.as_chunks::<2>().0.iter().map(|c| i16::from_le_bytes(*c)).collect(); + + // Verify that our decoder and FFmpeg decoder produce identical samples on our stream + let our_decoded_from_ours = decode(&our_encoded_bytes).expect("our decode of our stream"); + assert_eq!(our_decoded_from_ours.len(), our_by_ff_samples.len()); + let mut max_diff_ours: i32 = 0; + for (i, (&ours, &theirs)) in our_decoded_from_ours.iter().zip(&our_by_ff_samples).enumerate() { + let diff = (ours as i32 - theirs as i32).abs(); + if diff > max_diff_ours { + max_diff_ours = diff; + } + assert!(diff <= 1, "sample {i} on our stream mismatch between our decoder and FFmpeg decoder: ours {ours}, theirs {theirs}"); + } + assert!(max_diff_ours <= 1, "max diff {max_diff_ours} exceeded tolerance"); + + // Also check high fidelity correlation of our stream decoded by FFmpeg to original signal + let delay = 22; + let mut num = 0.0; + let mut den_orig = 0.0; + let mut den_dec = 0.0; + for i in 0..(pcm.len() - delay) { + let o = pcm[i] as f64; + let d = our_by_ff_samples[i + delay] as f64; + num += o * d; + den_orig += o * o; + den_dec += d * d; + } + let corr = num / (den_orig.sqrt() * den_dec.sqrt()); + assert!(corr > 0.98, "correlation of our encoded stream decoded by FFmpeg is too low: {corr}"); +} diff --git a/crates/audio/tests/g726_oracle.rs b/crates/audio/tests/g726_oracle.rs new file mode 100644 index 000000000..ec875e2c4 --- /dev/null +++ b/crates/audio/tests/g726_oracle.rs @@ -0,0 +1,218 @@ +#![cfg(feature = "g726")] + +use craft_audio::g726::{BitPacking, BitRate, Decoder, Encoder, decode, decode_interleaved, encode, encode_interleaved}; +use std::process::Command; + +fn pearson_correlation(x: &[i16], y: &[i16]) -> f64 { + let n = x.len().min(y.len()); + if n == 0 { + return 0.0; + } + let x = &x[..n]; + let y = &y[..n]; + let mean_x = x.iter().map(|&v| v as f64).sum::() / (n as f64); + let mean_y = y.iter().map(|&v| v as f64).sum::() / (n as f64); + let mut num = 0.0; + let mut denom_x = 0.0; + let mut denom_y = 0.0; + for (&a, &b) in x.iter().zip(y) { + let da = (a as f64) - mean_x; + let db = (b as f64) - mean_y; + num += da * db; + denom_x += da * da; + denom_y += db * db; + } + let denom = (denom_x * denom_y).sqrt(); + if denom > 0.0 { num / denom } else { 0.0 } +} + +fn find_ffmpeg() -> Option { + for cmd in ["ffmpeg", "/opt/homebrew/bin/ffmpeg", "/usr/bin/ffmpeg"] { + if Command::new(cmd).arg("-version").output().is_ok() { + return Some(cmd.to_string()); + } + } + None +} + +#[test] +fn test_silence_roundtrip() { + let pcm = vec![0i16; 80]; + for rate in [BitRate::Rate16k, BitRate::Rate24k, BitRate::Rate32k, BitRate::Rate40k] { + for packing in [BitPacking::BigEndian, BitPacking::LittleEndian] { + let enc = encode(&pcm, rate, packing).expect("encode"); + let dec = decode(&enc, rate, packing).expect("decode"); + assert_eq!(dec.len(), pcm.len()); + for &s in &dec { + assert!(s.abs() <= 16, "silence sample too large: {s}"); + } + } + } +} + +#[test] +fn test_sine_wave_roundtrip_fidelity() { + let sample_rate = 8000.0; + let freq = 300.0; + let num_samples = 160; + let mut pcm = Vec::with_capacity(num_samples); + for i in 0..num_samples { + let t = i as f64 / sample_rate; + let s = (4000.0 * (2.0 * std::f64::consts::PI * freq * t).sin()) as i16; + pcm.push(s); + } + + for rate in [BitRate::Rate16k, BitRate::Rate24k, BitRate::Rate32k, BitRate::Rate40k] { + for packing in [BitPacking::BigEndian, BitPacking::LittleEndian] { + let enc = encode(&pcm, rate, packing).expect("encode sine"); + let dec = decode(&enc, rate, packing).expect("decode sine"); + let corr = pearson_correlation(&pcm, &dec); + assert!(corr > 0.90, "correlation {corr} too low for rate {rate:?} packing {packing:?}"); + } + } +} + +#[test] +fn test_encoder_and_decoder_reset() { + let mut enc = Encoder::new(BitRate::Rate32k, BitPacking::BigEndian); + let mut dec = Decoder::new(BitRate::Rate32k, BitPacking::BigEndian); + + let pcm = vec![1000i16, 2000, 3000, 2000, 1000, 0, -1000, -2000]; + let mut out1 = Vec::new(); + enc.encode(&pcm, &mut out1).expect("enc 1"); + enc.flush(&mut out1).expect("flush 1"); + + let mut dec_pcm1 = Vec::new(); + dec.decode(&out1, &mut dec_pcm1).expect("dec 1"); + + enc.reset(); + dec.reset(); + + let mut out2 = Vec::new(); + enc.encode(&pcm, &mut out2).expect("enc 2"); + enc.flush(&mut out2).expect("flush 2"); + + let mut dec_pcm2 = Vec::new(); + dec.decode(&out2, &mut dec_pcm2).expect("dec 2"); + + assert_eq!(out1, out2); + assert_eq!(dec_pcm1, dec_pcm2); +} + +#[test] +fn test_stereo_multichannel_roundtrip() { + let mut stereo_pcm = Vec::new(); + for i in 0..160 { + let left = (3000.0 * (i as f64 * 0.05).sin()) as i16; + let right = (2000.0 * (i as f64 * 0.03).cos()) as i16; + stereo_pcm.push(left); + stereo_pcm.push(right); + } + + let enc = encode_interleaved(&stereo_pcm, 2, BitRate::Rate32k, BitPacking::BigEndian).expect("encode stereo"); + let dec = decode_interleaved(&enc, 2, BitRate::Rate32k, BitPacking::BigEndian).expect("decode stereo"); + + assert_eq!(dec.len(), stereo_pcm.len()); + let corr = pearson_correlation(&stereo_pcm, &dec); + assert!(corr > 0.90, "stereo correlation {corr} too low"); +} + +#[test] +fn test_hostile_inputs_do_not_crash() { + let mut dec = Decoder::new(BitRate::Rate32k, BitPacking::BigEndian); + let mut out = Vec::new(); + let hostile = vec![0xEE; 1000]; + let _ = dec.decode(&hostile, &mut out); + + let mut enc = Encoder::new(BitRate::Rate40k, BitPacking::LittleEndian); + let mut out_enc = Vec::new(); + let hostile_pcm = vec![i16::MIN, i16::MAX, -1, 1, 0]; + let _ = enc.encode(&hostile_pcm, &mut out_enc); + let _ = enc.flush(&mut out_enc); +} + +#[test] +fn test_ffmpeg_g726_oracle_encoder_and_decoder() { + let ff = match find_ffmpeg() { + Some(f) => f, + None => return, + }; + + let sample_rate = 8000; + let num_samples = 240; + let mut pcm = Vec::with_capacity(num_samples); + for i in 0..num_samples { + let t = i as f64 / sample_rate as f64; + let s = (5000.0 * (2.0 * std::f64::consts::PI * 350.0 * t).sin()) as i16; + pcm.push(s); + } + + let dir = std::env::temp_dir().join("craft_g726_oracle"); + let _ = std::fs::create_dir_all(&dir); + let in_pcm_path = dir.join("input.s16le"); + let mut in_bytes = Vec::with_capacity(pcm.len() * 2); + for &s in &pcm { + in_bytes.extend_from_slice(&s.to_le_bytes()); + } + std::fs::write(&in_pcm_path, &in_bytes).expect("write input pcm"); + + for rate in [BitRate::Rate16k, BitRate::Rate24k, BitRate::Rate32k, BitRate::Rate40k] { + for (packing, ff_codec, ff_fmt) in [(BitPacking::BigEndian, "g726", "g726"), (BitPacking::LittleEndian, "g726le", "g726le")] { + let cs = rate.code_size(); + let ff_g726_path = dir.join(format!("ff_{}_{}.g726", cs, ff_codec)); + + // 1. FFmpeg encodes PCM to G.726 + let out = Command::new(&ff) + .args(["-y", "-f", "s16le", "-ar", "8000", "-ac", "1", "-i"]) + .arg(&in_pcm_path) + .args(["-c:a", ff_codec, "-code_size", &cs.to_string(), "-f", ff_fmt]) + .arg(&ff_g726_path) + .output() + .expect("ffmpeg encode"); + assert!(out.status.success(), "ffmpeg encode failed: {}", String::from_utf8_lossy(&out.stderr)); + let ff_g726_bytes = std::fs::read(&ff_g726_path).expect("read ff g726"); + + // 2. FFmpeg decodes its own G.726 stream + let ff_pcm_back_path = dir.join(format!("ff_back_{}_{}.s16le", cs, ff_codec)); + let out = Command::new(&ff) + .args(["-y", "-f", ff_fmt, "-code_size", &cs.to_string(), "-i"]) + .arg(&ff_g726_path) + .args(["-f", "s16le", "-ar", "8000", "-ac", "1"]) + .arg(&ff_pcm_back_path) + .output() + .expect("ffmpeg decode"); + assert!(out.status.success(), "ffmpeg decode failed: {}", String::from_utf8_lossy(&out.stderr)); + let ff_back_bytes = std::fs::read(&ff_pcm_back_path).expect("read ff back pcm"); + let ff_back_samples: Vec = ff_back_bytes.as_chunks::<2>().0.iter().map(|c| i16::from_le_bytes(*c)).collect(); + + // 3. Our decoder decodes FFmpeg's stream + let our_decoded = decode(&ff_g726_bytes, rate, packing).expect("our decode"); + let corr = pearson_correlation(&our_decoded, &ff_back_samples); + assert!(corr > 0.998, "correlation {corr} too low between our decoder and FFmpeg decoder for rate {rate:?} packing {packing:?}"); + + // 4. Our encoder encodes PCM to G.726 + let our_g726_bytes = encode(&pcm, rate, packing).expect("our encode"); + let our_g726_path = dir.join(format!("our_{}_{}.g726", cs, ff_codec)); + std::fs::write(&our_g726_path, &our_g726_bytes).expect("write our g726"); + + // 5. FFmpeg decodes our encoded stream + let our_decoded_by_ff_path = dir.join(format!("our_by_ff_{}_{}.s16le", cs, ff_codec)); + let out = Command::new(&ff) + .args(["-y", "-f", ff_fmt, "-code_size", &cs.to_string(), "-i"]) + .arg(&our_g726_path) + .args(["-f", "s16le", "-ar", "8000", "-ac", "1"]) + .arg(&our_decoded_by_ff_path) + .output() + .expect("ffmpeg decode of our stream"); + assert!(out.status.success(), "ffmpeg decode of our stream failed: {}", String::from_utf8_lossy(&out.stderr)); + let our_by_ff_bytes = std::fs::read(&our_decoded_by_ff_path).expect("read our by ff pcm"); + let our_by_ff_samples: Vec = our_by_ff_bytes.as_chunks::<2>().0.iter().map(|c| i16::from_le_bytes(*c)).collect(); + + let corr_input = pearson_correlation(&pcm, &our_by_ff_samples); + assert!( + corr_input > 0.90, + "correlation {corr_input} too low for input vs FFmpeg-decoded our stream for rate {rate:?} packing {packing:?}" + ); + } + } +} diff --git a/crates/audio/tests/main.rs b/crates/audio/tests/main.rs index dcba6e1d7..5470dc553 100644 --- a/crates/audio/tests/main.rs +++ b/crates/audio/tests/main.rs @@ -1,20 +1,53 @@ //! Integration tests, built into the library's own test executable. +#[cfg(feature = "adpcm")] +#[path = "adpcm_oracle.rs"] +mod adpcm_oracle; #[cfg(all(feature = "decode", feature = "lossless-encode", feature = "peaks"))] #[path = "audio/main.rs"] mod audio; #[cfg(all(feature = "decode", feature = "encode"))] #[path = "codecs/main.rs"] mod codecs; +#[cfg(feature = "dsd")] +#[path = "dsd_bounds.rs"] +mod dsd_bounds; +#[cfg(feature = "dsd")] +#[path = "dsd_metadata.rs"] +mod dsd_metadata; +#[cfg(feature = "dsd")] +#[path = "dsd_oracle.rs"] +mod dsd_oracle; #[cfg(all(feature = "flac-decode", feature = "flac-encode"))] #[path = "flac_decode.rs"] mod flac_decode; +#[cfg(feature = "g722")] +#[path = "g722_oracle.rs"] +mod g722_oracle; +#[cfg(feature = "g726")] +#[path = "g726_oracle.rs"] +mod g726_oracle; #[cfg(feature = "gsm")] #[path = "gsm_oracle.rs"] mod gsm_oracle; +#[cfg(feature = "mpa-encode")] +#[path = "mp2_encoder_oracle.rs"] +mod mp2_encoder_oracle; #[cfg(feature = "qoa")] #[path = "qoa_oracle.rs"] mod qoa_oracle; #[cfg(feature = "sbc")] #[path = "sbc_oracle.rs"] mod sbc_oracle; +#[cfg(feature = "vmd-decode")] +#[path = "vmd.rs"] +mod vmd; +#[cfg(all(feature = "vorbis-decode", feature = "vorbis-encode"))] +#[path = "vorbis_decode_hostile.rs"] +mod vorbis_decode_hostile; +#[cfg(all(feature = "vorbis-decode", feature = "vorbis-encode", feature = "decode"))] +#[path = "vorbis_decode_oracle.rs"] +mod vorbis_decode_oracle; +#[cfg(feature = "vorbis-decode")] +#[path = "vorbis_decode_synthetic.rs"] +mod vorbis_decode_synthetic; diff --git a/crates/audio/tests/mp2_encoder_oracle.rs b/crates/audio/tests/mp2_encoder_oracle.rs new file mode 100644 index 000000000..ca4d15bd3 --- /dev/null +++ b/crates/audio/tests/mp2_encoder_oracle.rs @@ -0,0 +1,228 @@ +//! The Layer II encoder (feature `mpa-encode`): every frame has the header and size its settings +//! give and decodes with our decoder; ffmpeg as an external decoder (skipped without ffmpeg, a +//! failure with `CRAFT_MEDIA_REQUIRE_ORACLES=1`) decodes the stream without a complaint, to the +//! right length, and its output, aligned by [`DELAY`], matches the input within a signal-to-noise +//! ratio per bit rate. The bounds sit well under what the encoder reaches today; white noise loses +//! the subbands above the table's last one (a sixth of it at 48 kHz), so its bound is low. + +use std::path::Path; +use std::process::{Command, Stdio}; + +use craft_audio::mpa::encoder::{Config, DELAY, EncodeError, Encoder, bitrates, nearest_bitrate}; +use craft_audio::mpa::{Decoder, Mode, Version, parse_header}; + +fn chords(rate: u32, n: usize, detune: f32) -> Vec { + let f = [220.0, 277.18, 329.63, 440.0, 1318.5, 3520.0]; + let a = [0.2, 0.15, 0.12, 0.1, 0.05, 0.02]; + (0..n) + .map(|i| { + let t = i as f32 / rate as f32; + f.iter().zip(a).map(|(f, a)| a * (2.0 * std::f32::consts::PI * f * (1.0 + detune) * t).sin()).sum::() + }) + .collect() +} + +fn noise(n: usize, amp: f32, seed: u64) -> Vec { + let mut s = seed.wrapping_mul(0x9E37_79B9_7F4A_7C15) | 1; + (0..n) + .map(|_| { + s ^= s << 13; + s ^= s >> 7; + s ^= s << 17; + ((s >> 40) as f32 / (1u64 << 24) as f32 * 2.0 - 1.0) * amp + }) + .collect() +} + +fn encode(cfg: Config, input: &[Vec], chunk: usize) -> Vec { + let mut enc = Encoder::new(cfg).expect("encoder"); + let mut out = Vec::new(); + let n = input[0].len(); + let mut pos = 0; + while pos < n { + let end = (pos + chunk).min(n); + let planes: Vec<&[f32]> = input.iter().map(|c| &c[pos..end]).collect(); + out.extend(enc.encode(&planes)); + pos = end; + } + out.extend(enc.flush()); + out +} + +/// Split a stream into frames by its headers; every header must be one the settings give. +fn frames<'a>(bytes: &'a [u8], cfg: &Config) -> Vec<&'a [u8]> { + let mut out = Vec::new(); + let mut pos = 0; + while pos < bytes.len() { + let h = parse_header(&bytes[pos..]).unwrap_or_else(|e| panic!("frame {} at byte {pos}: {e}", out.len())); + assert_eq!(h.layer, 2); + assert_eq!(h.version, if cfg.sample_rate >= 32_000 { Version::Mpeg1 } else { Version::Mpeg2 }); + assert_eq!((h.sample_rate, h.bitrate_kbps), (cfg.sample_rate, cfg.bitrate_kbps)); + assert_eq!(h.mode, if cfg.channels == 1 { Mode::Mono } else { Mode::Stereo }); + assert!(!h.crc); + out.push(&bytes[pos..pos + h.frame_bytes]); + pos += h.frame_bytes; + } + assert_eq!(pos, bytes.len(), "the stream ends on a frame boundary"); + out +} + +fn snr(input: &[f32], dec: &[f32]) -> f64 { + let (mut s, mut n) = (0f64, 0f64); + for (a, b) in input.iter().zip(dec) { + s += f64::from(*a) * f64::from(*a); + n += f64::from(a - b) * f64::from(a - b); + } + 10.0 * (s / n.max(1e-30)).log10() +} + +struct Case { + name: &'static str, + rate: u32, + channels: usize, + kbps: u32, + signal: fn(u32, usize, usize) -> Vec, + min_snr: f64, +} + +fn sig_chords(rate: u32, n: usize, c: usize) -> Vec { + chords(rate, n, 0.003 * c as f32) +} +fn sig_noise(_rate: u32, n: usize, c: usize) -> Vec { + noise(n, 0.25, 11 + c as u64) +} + +const CASES: &[Case] = &[ + Case { name: "chords", rate: 48_000, channels: 2, kbps: 192, signal: sig_chords, min_snr: 30.0 }, + Case { name: "chords", rate: 44_100, channels: 2, kbps: 128, signal: sig_chords, min_snr: 25.0 }, + Case { name: "chords", rate: 44_100, channels: 1, kbps: 64, signal: sig_chords, min_snr: 25.0 }, + Case { name: "chords", rate: 32_000, channels: 2, kbps: 96, signal: sig_chords, min_snr: 20.0 }, + Case { name: "chords", rate: 22_050, channels: 2, kbps: 64, signal: sig_chords, min_snr: 20.0 }, + Case { name: "chords", rate: 24_000, channels: 1, kbps: 32, signal: sig_chords, min_snr: 18.0 }, + Case { name: "noise", rate: 48_000, channels: 2, kbps: 384, signal: sig_noise, min_snr: 4.0 }, + Case { name: "noise", rate: 44_100, channels: 2, kbps: 256, signal: sig_noise, min_snr: 4.0 }, +]; + +fn inputs(c: &Case, n: usize) -> Vec> { + (0..c.channels).map(|ch| (c.signal)(c.rate, n, ch)).collect() +} + +#[test] +fn frames_have_the_size_and_header_their_settings_give_and_decode_with_our_decoder() { + for c in CASES { + let n = c.rate as usize * 2 + 777; + let cfg = Config::cbr(c.rate, c.channels, c.kbps); + let bytes = encode(cfg, &inputs(c, n), 1000); + let frames = frames(&bytes, &cfg); + // every input sample and the filter delay fit in the frames, and no more than one frame more + let covered = frames.len() * 1152; + assert!(covered >= n + DELAY as usize && covered < n + DELAY as usize + 1152, "{}: {} frames for {n} samples", c.name, frames.len()); + // 144 kbit/s-slots per frame, the padding slots adding up to the exact rate + let nominal = f64::from(c.kbps) * 125.0 * covered as f64 / f64::from(c.rate); + assert!((bytes.len() as f64 - nominal).abs() < 1.0 + f64::from(c.rate) / 1000.0, "{}: {} bytes against {nominal}", c.name, bytes.len()); + let mut dec = Decoder::new(); + let mut out = vec![Vec::new(); c.channels]; + for f in frames { + let frame = dec.decode(f).unwrap_or_else(|e| panic!("{}: {e}", c.name)); + for (o, ch) in out.iter_mut().zip(frame.channels) { + o.extend(ch); + } + } + let d = DELAY as usize; + for (ch, input) in inputs(c, n).iter().enumerate() { + let s = snr(input, &out[ch][d..d + n]); + println!("{:<7} {:>5} Hz {}ch {:>3} kbps: SNR {s:.2} dB (our decoder)", c.name, c.rate, c.channels, c.kbps); + assert!(s >= c.min_snr, "{} {} Hz {}ch {} kbps: SNR {s:.2} dB under {}", c.name, c.rate, c.channels, c.kbps, c.min_snr); + } + } +} + +#[test] +fn the_stream_does_not_depend_on_how_the_input_is_chunked() { + let c = &CASES[1]; + let n = 44_100 + 333; + let cfg = Config::cbr(c.rate, c.channels, c.kbps); + let input = inputs(c, n); + let whole = encode(cfg, &input, n); + for chunk in [1, 7, 1152, 5000] { + assert_eq!(encode(cfg, &input, chunk), whole, "chunk {chunk}"); + } +} + +#[test] +fn silence_and_nothing_encode_to_valid_frames() { + let cfg = Config::cbr(48_000, 2, 128); + let silent = vec![vec![0f32; 5000]; 2]; + let bytes = encode(cfg, &silent, 5000); + let fs = frames(&bytes, &cfg); + let mut dec = Decoder::new(); + for f in fs { + let frame = dec.decode(f).expect("decode"); + assert!(frame.channels.iter().flatten().all(|v| v.abs() < 1e-6)); + } + assert!(Encoder::new(cfg).expect("encoder").flush().is_empty(), "no input, no frames"); +} + +#[test] +fn hostile_samples_are_tamed() { + let cfg = Config::cbr(44_100, 2, 192); + let mut x = vec![0f32; 4000]; + for (i, v) in x.iter_mut().enumerate() { + *v = [f32::NAN, f32::INFINITY, -f32::INFINITY, 1e30, -1e30, 3.0, 0.5][i % 7]; + } + let bytes = encode(cfg, &[x.clone(), x], 4000); + let mut dec = Decoder::new(); + for f in frames(&bytes, &cfg) { + dec.decode(f).expect("decode"); + } +} + +#[test] +fn settings_that_cannot_be_carried_are_refused() { + assert_eq!(Encoder::new(Config::cbr(44_000, 2, 128)).err(), Some(EncodeError::SampleRate(44_000))); + assert_eq!(Encoder::new(Config::cbr(44_100, 3, 128)).err(), Some(EncodeError::Channels(3))); + assert_eq!(Encoder::new(Config::cbr(44_100, 0, 128)).err(), Some(EncodeError::Channels(0))); + // ISO/IEC 11172-3 allows neither 32 kbit/s for two channels nor 224 for one + assert!(matches!(Encoder::new(Config::cbr(44_100, 2, 32)), Err(EncodeError::Bitrate { .. }))); + assert!(matches!(Encoder::new(Config::cbr(44_100, 1, 224)), Err(EncodeError::Bitrate { .. }))); + assert!(matches!(Encoder::new(Config::cbr(44_100, 2, 130)), Err(EncodeError::Bitrate { .. }))); + assert_eq!(bitrates(44_100, 1).len(), 10); + assert_eq!(bitrates(22_050, 2).first(), Some(&8)); + assert!(bitrates(8_000, 2).is_empty()); + assert_eq!(nearest_bitrate(44_100, 2, 100), Some(96)); + assert_eq!(nearest_bitrate(44_100, 2, 1), Some(64)); + assert_eq!(nearest_bitrate(8_000, 2, 100), None); +} + +fn ffmpeg_decode(ff: &Path, path: &Path, channels: usize) -> (Vec>, String) { + let out = Command::new(ff) + .args(["-v", "error", "-nostdin", "-i"]) + .arg(path) + .args(["-f", "f32le", "-acodec", "pcm_f32le", "-"]) + .stdin(Stdio::null()) + .output() + .expect("run ffmpeg"); + let samples: Vec = out.stdout.as_chunks::<4>().0.iter().map(|b| f32::from_le_bytes(*b)).collect(); + let planar = (0..channels).map(|c| samples.iter().skip(c).step_by(channels).copied().collect()).collect(); + (planar, String::from_utf8_lossy(&out.stderr).into_owned()) +} + +#[test] +fn ffmpeg_decodes_our_streams_to_the_input() { + let Some(ff) = craft_media_testkit::ffmpeg() else { return }; + let dir = craft_media_testkit::fixture_subdir("mp2enc"); + for c in CASES { + let n = c.rate as usize * 2 + 777; + let input = inputs(c, n); + let bytes = encode(Config::cbr(c.rate, c.channels, c.kbps), &input, 1000); + let path = dir.join(format!("{}_{}_{}ch_{}k.mp2", c.name, c.rate, c.channels, c.kbps)); + std::fs::write(&path, &bytes).expect("write"); + let (dec, err) = ffmpeg_decode(&ff, &path, c.channels); + assert!(err.trim().is_empty(), "{}: ffmpeg reported: {err}", path.display()); + let d = DELAY as usize; + assert!(dec[0].len() >= n + d, "{}: decoded {} samples, need {}", c.name, dec[0].len(), n + d); + let s = (0..c.channels).map(|ch| snr(&input[ch], &dec[ch][d..d + n])).sum::() / c.channels as f64; + println!("{:<7} {:>5} Hz {}ch {:>3} kbps: SNR {s:.2} dB (ffmpeg)", c.name, c.rate, c.channels, c.kbps); + assert!(s >= c.min_snr, "{} {} Hz {}ch {} kbps: SNR {s:.2} dB under {}", c.name, c.rate, c.channels, c.kbps, c.min_snr); + } +} diff --git a/crates/audio/tests/vmd.rs b/crates/audio/tests/vmd.rs new file mode 100644 index 000000000..145aafa79 --- /dev/null +++ b/crates/audio/tests/vmd.rs @@ -0,0 +1,280 @@ +//! VMD sound decoder tests. ffmpeg reads VMD but cannot write it, so the files come from the +//! test kit's VMD writer. The decoder must return the samples that were packed, and the same +//! samples as ffmpeg (skipped without ffmpeg). + +use std::process::Command; + +use craft_audio::AudioError; +use craft_audio::vmd::{Decoder, Error}; +use craft_media::vmd::{FrameKind, open}; +use craft_media_testkit::hostile::Rng; +use craft_media_testkit::vmd::{Audio, Frame, Spec, build, dpcm_pack}; + +/// (frame length field, audio flags, channels, 16-bit): every layout the decoder handles. +const FORMATS: [(i16, u16, usize, bool); 6] = + [(50, 0, 1, false), (50, 0x200, 2, false), (50, 0x8000, 2, false), (-50, 0, 1, true), (-50, 0x200, 2, true), (-50, 0x8000, 2, true)]; + +fn spec(frame_length: i16, flags: u16) -> Spec { + let mut spec = Spec::new(4, 4); + spec.audio = Some(Audio { sample_rate: 22050, frame_length, buffers: 5, flags }); + spec +} + +fn decoder(frame_length: i16, flags: u16) -> Decoder { + Decoder::new(&build(&spec(frame_length, flags), &[])).unwrap() +} + +/// One block of random sound: its bytes in the file and the samples it decodes to. +fn block(rng: &mut Rng, d: &Decoder) -> (Vec, Vec) { + let n = d.block_samples() * d.channels(); + if d.bits() == 8 { + let bytes: Vec = (0..n).map(|_| rng.next_u64() as u8).collect(); + let samples = bytes.iter().map(|&b| (i16::from(b) - 0x80) << 8).collect(); + return (bytes, samples); + } + // a random walk, so that the steps are of every size + let mut last = [0i32; 2]; + let samples: Vec = (0..n) + .map(|i| { + let bits = 1 + rng.below(15); + let step = rng.below(1 << bits) as i32 - (1 << (bits - 1)); + let s = &mut last[i % d.channels()]; + *s = (*s + step).clamp(-32768, 32767); + *s as i16 + }) + .collect(); + dpcm_pack(&samples, d.channels()) +} + +/// A file of sound frames (with a small picture each, as ffmpeg expects video) and the samples +/// expected of it. The first frame is a mask frame: one silent block, then four of sound. +fn movie(seed: u64, frame_length: i16, flags: u16) -> (Vec, Vec) { + let spec = spec(frame_length, flags); + let d = decoder(frame_length, flags); + let mut rng = Rng(seed | 1); + let mut picture = vec![2u8]; + picture.extend([9; 16]); + let silence = vec![0i16; d.block_samples() * d.channels()]; + let mut want = Vec::new(); + let mut blocks = Vec::new(); + for n in 0..12 { + let sound = match n { + 0 => { + let mut data = 1u32.to_le_bytes().to_vec(); + want.extend_from_slice(&silence); + for _ in 0..4 { + let (bytes, samples) = block(&mut rng, &d); + data.extend_from_slice(&bytes); + want.extend_from_slice(&samples); + } + Frame::audio(2, data) + } + _ if rng.below(4) == 0 => { + want.extend_from_slice(&silence); + Frame::audio(3, vec![]) + } + _ => { + let (bytes, samples) = block(&mut rng, &d); + want.extend_from_slice(&samples); + Frame::audio(1, bytes) + } + }; + blocks.push(vec![sound, Frame::video([0, 0, 3, 3], false, picture.clone())]); + } + (build(&spec, &blocks), want) +} + +fn decode_all(bytes: &[u8]) -> Vec { + let file = open(bytes).unwrap(); + let d = Decoder::new(file.header_bytes()).unwrap(); + let mut out = Vec::new(); + for (i, frame) in file.frames.iter().enumerate() { + if let FrameKind::Audio { flags } = frame.kind { + out.extend(d.decode(flags, &file.read_frame(bytes, i).unwrap()).unwrap()); + } + } + out +} + +#[test] +fn decodes_the_samples_that_were_packed() { + for (i, (frame_length, flags, channels, sixteen)) in FORMATS.into_iter().enumerate() { + let d = decoder(frame_length, flags); + assert_eq!((d.channels(), d.bits(), d.sample_rate()), (channels, if sixteen { 16 } else { 8 }, 22050), "format {i}"); + // old-style stereo counts both channels in the frame length + assert_eq!(d.block_samples(), if flags & 0x8000 != 0 { 25 } else { 50 }, "format {i}"); + let (bytes, want) = movie(i as u64 + 1, frame_length, flags); + assert_eq!(want.len(), 16 * d.block_samples() * channels); + assert!(decode_all(&bytes) == want, "format {i}"); + } +} + +#[test] +fn matches_ffmpeg() { + let Some(ffmpeg) = craft_media_testkit::ffmpeg_or_skip("vmd sound oracle") else { return }; + let dir = craft_media_testkit::private_dir("vmd-sound"); + for (i, (frame_length, flags, ..)) in FORMATS.into_iter().enumerate() { + let (bytes, _) = movie(i as u64 + 1, frame_length, flags); + let path = dir.join(format!("sound{i}.vmd")); + std::fs::write(&path, &bytes).unwrap(); + let out = Command::new(&ffmpeg).args(["-v", "error", "-i"]).arg(&path).args(["-vn", "-f", "s16le", "-"]).output().unwrap(); + assert!(out.status.success() && out.stderr.is_empty(), "format {i}: ffmpeg: {}", String::from_utf8_lossy(&out.stderr)); + let theirs: Vec = out.stdout.as_chunks::<2>().0.iter().map(|b| i16::from_le_bytes(*b)).collect(); + assert!(theirs == decode_all(&bytes), "format {i} differs from ffmpeg"); + } + std::fs::remove_dir_all(&dir).unwrap(); +} + +#[test] +fn sixteen_bit_steps() { + // values ffmpeg gave for this block: the first sample, then signed steps from the table + let mut data = 1000i16.to_le_bytes().to_vec(); + data.extend([1, 1, 1, 0x81, 0x81, 2, 3, 0x7F, 0xFF, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1]); + let d = decoder(-20, 0); + assert_eq!(d.block_bytes(), 21); + assert_eq!( + d.decode(1, &data).unwrap(), + [1000, 1008, 1016, 1024, 1016, 1008, 1024, 1056, 17440, 1056, 1056, 1056, 1056, 1056, 1056, 1056, 1056, 1056, 1056, 1064] + ); + // stereo: the channels take turns + let mut data = [1000i16.to_le_bytes(), (-1000i16).to_le_bytes()].concat(); + data.extend([1, 0x82].repeat(3)); + let d = decoder(-4, 0x200); + assert_eq!(d.decode(1, &data).unwrap(), [1000, -1000, 1008, -1016, 1016, -1032, 1024, -1048]); + // a flags 1 frame of several blocks: each block starts from its own first samples + let (first, first_samples) = dpcm_pack(&[100, -100, 300, -50, 200, 0, 1000, 500], 2); + let (second, second_samples) = dpcm_pack(&[-7000, 7000, -6000, 6500, -6100, 6400, -3000, 3000], 2); + assert_eq!(d.decode(1, &[first, second, vec![1, 2, 3]].concat()).unwrap(), [first_samples, second_samples].concat()); + // steps past 16 bits stop at the ends + let mut data = 30000i16.to_le_bytes().to_vec(); + data.extend([0x7F, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF]); + assert_eq!(decoder(-7, 0).decode(1, &data).unwrap(), [30000, 32767, 16383, -1, -16385, -32768, -32768]); +} + +#[test] +fn eight_bit_and_silence() { + let d = decoder(4, 0); + assert_eq!(d.decode(1, &[0x80, 0x00, 0xFF, 0x70]).unwrap(), [0, -32768, 0x7F00, -0x1000]); + assert_eq!(d.decode(3, &[]).unwrap(), [0; 4]); + assert_eq!(d.decode(1, &[]).unwrap(), [0i16; 0]); + assert_eq!(decoder(4, 0x200).decode(3, &[]).unwrap(), [0; 8]); + // a flags 1 frame of more than one block plays every whole block + assert_eq!( + d.decode(1, &[0x80, 0x81, 0x82, 0x83, 0x90, 0x91, 0x92, 0x93, 0xA0]).unwrap(), + [0, 0x100, 0x200, 0x300, 0x1000, 0x1100, 0x1200, 0x1300] + ); + assert_eq!(decoder(-4, 0x8000).decode(3, &[]).unwrap(), [0; 4]); +} + +#[test] +fn silence_mask_runs_bit_by_bit() { + let d = decoder(2, 0); + let frame = |mask: u32, data: &[u8]| d.decode(2, &[&mask.to_le_bytes()[..], data].concat()); + let (a, b) = ([0x90, 0x91], [0xA0, 0xA1]); + let (sa, sb) = ([0x1000, 0x1100], [0x2000, 0x2100]); + assert_eq!(frame(0, &[a, b].concat()).unwrap(), [sa, sb].concat()); + // silent, sound, silent, sound + assert_eq!(frame(0b0101, &[a, b].concat()).unwrap(), [[0, 0], sa, [0, 0], sb].concat()); + // game files set a bit for every block when all are silent + assert_eq!(frame(0b0111, &[]).unwrap(), [0; 6]); + // a trailing part of a block is left out + assert_eq!(frame(0, &[0x90, 0x91, 0xA0]).unwrap(), sa); + assert_eq!(d.decode(2, &[0, 0, 0]), Err(Error::Invalid("the silence mask is cut short"))); +} + +#[test] +fn bad_input_is_an_error() { + let d = decoder(-20, 0); + assert_eq!(d.decode(1, &[0; 20]), Err(Error::Invalid("a block of sound is cut short"))); + assert_eq!(d.decode(4, &[0; 21]), Err(Error::Unsupported("unknown sound frame flags"))); + assert_eq!(d.decode(4, &[]), Err(Error::Unsupported("unknown sound frame flags"))); + // in the file API's error: unsupported stays unsupported, the rest is malformed input + assert!(matches!(AudioError::from(Error::Unsupported("x")), AudioError::Unsupported(_))); + assert!(matches!(AudioError::from(Error::Invalid("x")), AudioError::Malformed(_))); + + let good = build(&spec(20, 0), &[]); + let with = |patch: &dyn Fn(&mut Vec)| { + let mut h = good.clone(); + patch(&mut h); + Decoder::new(&h).err() + }; + assert_eq!(with(&|_| {}), None); + assert_eq!(with(&|h| h.truncate(815)), Some(Error::Invalid("the header is shorter than 816 bytes"))); + assert_eq!(with(&|h| h[0] = 0), Some(Error::Invalid("not a VMD header"))); + assert_eq!(with(&|h| h[17] = 0), Some(Error::Invalid("the file has no sound"))); + assert_eq!(with(&|h| h[804..806].fill(0)), Some(Error::Invalid("the file has no sound"))); + assert_eq!(with(&|h| h[810] = 0x10), Some(Error::Unsupported("IMA ADPCM sound"))); + // a frame length of nothing decodes to nothing + let mut empty = good.clone(); + empty[806..808].fill(0); + let d = Decoder::new(&empty).unwrap(); + assert_eq!(d.decode(1, &[1, 2, 3]).unwrap(), [0i16; 0]); + assert_eq!(d.decode(2, &[0, 0, 0, 0, 1, 2]).unwrap(), [0i16; 0]); +} + +#[test] +fn hostile_input_never_panics() { + for (i, (frame_length, flags, ..)) in FORMATS.into_iter().enumerate() { + let (bytes, _) = movie(i as u64 + 1, frame_length, flags); + craft_media_testkit::hostile::hammer(&format!("vmd sound format {i}"), &bytes, 10_000, |d| { + let Ok(file) = open(d) else { return }; + let Ok(decoder) = Decoder::new(file.header_bytes()) else { return }; + for (i, frame) in file.frames.iter().enumerate() { + let FrameKind::Audio { flags } = frame.kind else { continue }; + if let Ok(data) = file.read_frame(d, i) { + let _ = decoder.decode(flags, &data); + } + } + }); + } +} + +/// Real files, for whoever has some: the sound of every `.vmd` in the directory +/// `CRAFT_MEDIA_VMD_SAMPLES` names must decode to the samples ffmpeg gets. Game files are not +/// redistributable, so none are in the repository and the test is skipped without the variable. +#[test] +fn real_files_match_ffmpeg() { + let Some(dir) = std::env::var_os("CRAFT_MEDIA_VMD_SAMPLES").filter(|d| !d.is_empty()) else { + craft_media_testkit::skip_test("vmd samples", "CRAFT_MEDIA_VMD_SAMPLES is not set"); + return; + }; + let Some(ffmpeg) = craft_media_testkit::ffmpeg_or_skip("vmd sound samples") else { return }; + let mut paths: Vec<_> = std::fs::read_dir(&dir) + .unwrap() + .filter_map(|e| Some(e.ok()?.path())) + .filter(|p| p.extension().is_some_and(|e| e.eq_ignore_ascii_case("vmd"))) + .collect(); + paths.sort(); + assert!(!paths.is_empty(), "no .vmd files in CRAFT_MEDIA_VMD_SAMPLES"); + let (mut files, mut samples) = (0, 0); + for path in &paths { + let name = path.display(); + let source = std::fs::File::open(path).unwrap(); + let file = open(&source).unwrap(); + if file.audio_params().is_none() { + continue; + } + let d = Decoder::new(file.header_bytes()).unwrap(); + let mut ours = Vec::new(); + for (i, frame) in file.frames.iter().enumerate() { + let FrameKind::Audio { flags } = frame.kind else { continue }; + let mut data = file.read_frame(&source, i).unwrap(); + if flags == 2 && data.len() >= 4 { + // ffmpeg plays a mask frame's silent blocks before its sound; put ours in that + // order to compare + let silent = u32::from_le_bytes([data[0], data[1], data[2], data[3]]).count_ones() as usize; + ours.resize(ours.len() + silent * d.block_samples() * d.channels(), 0); + data[..4].fill(0); + } + ours.extend(d.decode(flags, &data).unwrap_or_else(|e| panic!("{name}: frame {i}: {e}"))); + } + let out = Command::new(&ffmpeg).args(["-v", "quiet", "-i"]).arg(path).args(["-vn", "-f", "s16le", "-"]).output().unwrap(); + let theirs: Vec = out.stdout.as_chunks::<2>().0.iter().map(|b| i16::from_le_bytes(*b)).collect(); + if let Some(at) = (0..ours.len().max(theirs.len())).find(|&i| ours.get(i) != theirs.get(i)) { + panic!("{name}: sample {at} differs from ffmpeg ({} samples here, {} there)", ours.len(), theirs.len()); + } + files += 1; + samples += ours.len(); + } + println!("{files} files, {samples} samples match ffmpeg"); +} diff --git a/crates/audio/tests/vorbis_decode_hostile.rs b/crates/audio/tests/vorbis_decode_hostile.rs new file mode 100644 index 000000000..fba004e10 --- /dev/null +++ b/crates/audio/tests/vorbis_decode_hostile.rs @@ -0,0 +1,230 @@ +//! Hostile input to the Vorbis decoder: damaged headers and packets, truncations, and headers that +//! ask for absurd sizes. Every case is an error or a result, never a panic or a large allocation. + +use craft_audio::vorbis::decoder::{Decoder, Error, decode_ogg}; +use craft_audio::{AudioBuffer, OggVorbisOptions, encode_ogg_vorbis}; + +fn xorshift(seed: &mut u32) -> u32 { + *seed ^= *seed << 13; + *seed ^= *seed >> 17; + *seed ^= *seed << 5; + *seed +} + +struct Parts { + ogg: Vec, + headers: Vec>, + packets: Vec>, +} + +fn parts(channels: usize) -> Parts { + let signal: Vec> = (0..channels) + .map(|c| (0..20_000).map(|i| ((i as f32 * (0.03 + 0.01 * c as f32)).sin() * 0.4) + ((i * 7 % 13) as f32 - 6.0) / 60.0).collect()) + .collect(); + let ogg = + encode_ogg_vorbis(&AudioBuffer { sample_rate: 44_100, channels: signal }, &OggVorbisOptions::default().with_quality(4.0)).expect("encode"); + let file = craft_media::ogg::open(ogg.as_slice()).expect("open"); + let s = &file.streams[0]; + let packets = (0..s.packets.len()).map(|i| file.read_packet(ogg.as_slice(), 0, i).expect("packet")).collect(); + Parts { headers: s.headers.clone(), packets, ogg } +} + +fn decoder(p: &Parts) -> Decoder { + Decoder::new(&p.headers[0], &p.headers[1], &p.headers[2]).expect("valid headers") +} + +#[test] +fn every_truncated_header_is_an_error() { + let p = parts(2); + for which in [0usize, 2] { + for n in 0..p.headers[which].len() { + let mut h = p.headers.clone(); + h[which].truncate(n); + assert!(Decoder::new(&h[0], &h[1], &h[2]).is_err(), "header {which} cut to {n} bytes"); + } + } + // A damaged comment header is not fatal. + let mut h = p.headers.clone(); + h[1].truncate(12); + let d = Decoder::new(&h[0], &h[1], &h[2]).expect("comments are best effort"); + assert!(d.comments().comments.is_empty()); + assert!(Decoder::new(&p.headers[0], &[], &p.headers[2]).is_err(), "the comment header still needs its tag"); +} + +#[test] +fn damaged_headers_never_panic() { + let p = parts(2); + let mut seed = 99u32; + for which in [0usize, 2] { + let len = p.headers[which].len(); + for _ in 0..800 { + let mut h = p.headers.clone(); + for _ in 0..1 + xorshift(&mut seed) % 3 { + let at = xorshift(&mut seed) as usize % len; + h[which][at] = xorshift(&mut seed) as u8; + } + if let Ok(mut d) = Decoder::new(&h[0], &h[1], &h[2]) { + // A setup that survives must also survive audio packets. + for pk in p.packets.iter().take(6) { + let _ = d.decode_packet(pk); + } + } + } + } +} + +#[test] +fn damaged_packets_never_panic() { + let p = parts(2); + let mut seed = 7u32; + let mut d = decoder(&p); + for pk in &p.packets { + for _ in 0..6 { + let mut bad = pk.clone(); + match xorshift(&mut seed) % 3 { + 0 => bad.truncate(xorshift(&mut seed) as usize % (bad.len() + 1)), + 1 => { + let at = xorshift(&mut seed) as usize % bad.len(); + bad[at] = xorshift(&mut seed) as u8; + } + _ => bad = (0..xorshift(&mut seed) % 300).map(|_| xorshift(&mut seed) as u8).collect(), + } + let _ = d.decode_packet(&bad); + } + } + // The decoder still decodes good packets after all that. + d.reset(); + assert!(d.decode_packet(&p.packets[3]).is_ok()); +} + +#[test] +fn header_packets_and_empty_packets_are_not_audio() { + let p = parts(1); + let mut d = decoder(&p); + assert_eq!(d.decode_packet(&p.headers[0]), Err(Error::NotAudio)); + assert_eq!(d.decode_packet(&p.headers[2]), Err(Error::NotAudio)); + assert!(matches!(d.decode_packet(&[]), Err(Error::Packet(_)))); +} + +#[test] +fn damaged_files_never_panic() { + let p = parts(2); + let mut seed = 31u32; + for _ in 0..120 { + let mut bad = p.ogg.clone(); + for _ in 0..1 + xorshift(&mut seed) % 4 { + let at = xorshift(&mut seed) as usize % bad.len(); + bad[at] = xorshift(&mut seed) as u8; + } + let _ = decode_ogg(&bad); + bad.truncate(xorshift(&mut seed) as usize % bad.len()); + let _ = decode_ogg(&bad); + } + assert!(matches!(decode_ogg(b"not an ogg file"), Err(Error::Ogg(_)))); + assert!(matches!(decode_ogg(&[]), Err(Error::Ogg(_)))); +} + +/// A bit writer for hand-built setups. +#[derive(Default)] +struct W(Vec, usize); +impl W { + fn put(&mut self, v: u64, n: u32) { + for i in 0..n { + if self.1.is_multiple_of(8) { + self.0.push(0); + } + let last = self.0.len() - 1; + self.0[last] |= (((v >> i) & 1) as u8) << (self.1 % 8); + self.1 += 1; + } + } +} + +fn setup_with_first_book(book: impl FnOnce(&mut W)) -> Vec { + let mut w = W::default(); + w.put(5, 8); + for c in b"vorbis" { + w.put(u64::from(*c), 8); + } + w.put(0, 8); // one book + book(&mut w); + w.0 +} + +#[test] +fn absurd_codebook_sizes_are_refused_before_allocating() { + let p = parts(1); + let try_setup = |setup: Vec| Decoder::new(&p.headers[0], &p.headers[1], &setup); + // 2^24 - 1 entries. + assert!( + try_setup(setup_with_first_book(|w| { + w.put(0x56_4342, 24); + w.put(1, 16); + w.put(0xFF_FFFF, 24); + w.put(1, 1); // ordered + w.put(0, 5); + })) + .is_err() + ); + // An ordered book whose lengths overrun its entries. + assert!( + try_setup(setup_with_first_book(|w| { + w.put(0x56_4342, 24); + w.put(1, 16); + w.put(8, 24); + w.put(1, 1); + w.put(0, 5); + w.put(0xFF, 4); // asks for more codewords of length 1 than there are entries + })) + .is_err() + ); + // A lookup table of 65535 dimensions over a million entries: 69 billion values. + assert!( + try_setup(setup_with_first_book(|w| { + w.put(0x56_4342, 24); + w.put(0xFFFF, 16); + w.put(1 << 20, 24); + w.put(1, 1); // ordered + w.put(19, 5); // length 20 + w.put(1 << 20, 21); // all the entries + w.put(2, 4); // lookup type 2 + w.put(0, 32); + w.put(0, 32); + w.put(0, 4); + w.put(0, 1); + })) + .is_err() + ); + // A million-entry book with a legitimate tree but a lookup table that is not in the packet. + assert!( + try_setup(setup_with_first_book(|w| { + w.put(0x56_4342, 24); + w.put(4, 16); + w.put(1 << 20, 24); + w.put(1, 1); + w.put(19, 5); + w.put(1 << 20, 21); + w.put(1, 4); // lookup type 1 + w.put(0, 32); + w.put(0, 32); + w.put(15, 4); + w.put(0, 1); + })) + .is_err() + ); +} + +#[test] +fn identification_header_limits() { + let p = parts(1); + let mut h = p.headers[0].clone(); + let setup = &p.headers[2]; + h[11] = 0; // no channels + assert!(matches!(Decoder::new(&h, &p.headers[1], setup), Err(Error::Header(_)))); + let mut h = p.headers[0].clone(); + h[28] = 0x95; // a short block size of 2^5 is below the 64 Vorbis allows + assert!(matches!(Decoder::new(&h, &p.headers[1], setup), Err(Error::Header(_)))); + let mut h = p.headers[0].clone(); + h[7] = 1; // version 1 + assert!(matches!(Decoder::new(&h, &p.headers[1], setup), Err(Error::Header(_)))); +} diff --git a/crates/audio/tests/vorbis_decode_oracle.rs b/crates/audio/tests/vorbis_decode_oracle.rs new file mode 100644 index 000000000..a23d2a954 --- /dev/null +++ b/crates/audio/tests/vorbis_decode_oracle.rs @@ -0,0 +1,216 @@ +//! The Vorbis decoder against ffmpeg's as the reference (oracle; skipped when ffmpeg is absent, a +//! failure with `CRAFT_MEDIA_REQUIRE_ORACLES=1`). Streams come from two encoders, this crate's and +//! ffmpeg's own, so the setups differ: different floors, residues, block sizes, channel counts and +//! coupling. Both decoders must return the same samples. + +use craft_audio::AudioBuffer; +use craft_audio::vorbis::decoder::{Decoder, decode_ogg}; +use craft_audio::{OggVorbisOptions, encode_ogg_vorbis}; +use std::path::Path; +use std::process::Command; + +fn xorshift(seed: &mut u32) -> u32 { + *seed ^= *seed << 13; + *seed ^= *seed >> 17; + *seed ^= *seed << 5; + *seed +} + +/// A signal with tones, noise bursts, clicks and silence, different in every channel. +fn signal(rate: u32, channels: usize, frames: usize) -> Vec> { + let mut seed = 0x1234_5678u32; + (0..channels) + .map(|c| { + (0..frames) + .map(|i| { + let t = i as f64 / f64::from(rate); + let tone = + (t * (220.0 + 110.0 * c as f64) * std::f64::consts::TAU).sin() * 0.3 + (t * 3100.0 * std::f64::consts::TAU).sin() * 0.05; + let noise = (f64::from(xorshift(&mut seed) % 2000) - 1000.0) / 6000.0; + let s = match (i / (rate as usize / 4)) % 6 { + 0 | 1 => tone, + 2 => noise, + 3 => 0.0, + 4 => tone + if i % 3000 < 8 { 0.6 } else { 0.0 }, + _ => tone * (t * 4.0).sin(), + }; + s as f32 + }) + .collect() + }) + .collect() +} + +fn ffmpeg_decode(ffmpeg: &Path, ogg: &Path, channels: usize) -> Vec> { + let out = Command::new(ffmpeg) + .args(["-v", "error", "-nostdin", "-i"]) + .arg(ogg) + .args(["-f", "f32le", "-acodec", "pcm_f32le", "-"]) + .output() + .expect("run ffmpeg"); + assert!(out.status.success(), "ffmpeg failed on {}: {}", ogg.display(), String::from_utf8_lossy(&out.stderr)); + let all: Vec = out.stdout.as_chunks::<4>().0.iter().map(|b| f32::from_le_bytes(*b)).collect(); + (0..channels).map(|c| all.iter().skip(c).step_by(channels).copied().collect()).collect() +} + +/// Each of our channels matches a different one of theirs (ffmpeg reorders the channels of surround +/// streams), to within float rounding. +fn assert_same(name: &str, ours: &[Vec], theirs: &[Vec]) { + assert_prefix(name, ours, theirs, true); +} + +/// As [`assert_same`], but with `exact` unset ffmpeg may return more samples than we do (it does +/// not always trim a stream to its last granule position); the common part must agree. +fn assert_prefix(name: &str, ours: &[Vec], theirs: &[Vec], exact: bool) { + assert_eq!(ours.len(), theirs.len(), "{name}: channel count"); + assert!(ours.iter().chain(theirs).flatten().all(|v| v.is_finite()), "{name}: non-finite oracle input or output"); + let mut used = vec![false; theirs.len()]; + for (c, o) in ours.iter().enumerate() { + let mut best: Option<(usize, f32)> = None; + for (k, t) in theirs.iter().enumerate() { + if used[k] { + continue; + } + if exact { + assert_eq!(o.len(), t.len(), "{name}: channel {c} length {} vs ffmpeg {}", o.len(), t.len()); + } else { + assert!(o.len() <= t.len(), "{name}: channel {c} length {} vs ffmpeg {}", o.len(), t.len()); + } + let worst = o.iter().zip(t).map(|(a, b)| (a - b).abs()).fold(0f32, f32::max); + if best.is_none_or(|(_, w)| worst < w) { + best = Some((k, worst)); + } + } + let (k, worst) = best.expect("a free channel"); + used[k] = true; + assert!(worst < 2e-4, "{name}: channel {c} differs from ffmpeg's channel {k} by up to {worst}"); + } +} + +#[test] +fn ffmpeg_decodes_our_encoders_streams_to_the_same_samples() { + let Some(ffmpeg) = craft_media_testkit::ffmpeg() else { return }; + let dir = craft_media_testkit::fixture_subdir("vorbis_decode"); + for (rate, channels, quality) in + [(44_100u32, 2usize, 6.0f32), (44_100, 1, 3.0), (48_000, 2, -1.0), (22_050, 1, 10.0), (44_100, 6, 5.0), (32_000, 8, 4.0)] + { + let buf = AudioBuffer { sample_rate: rate, channels: signal(rate, channels, rate as usize * 2 + 777) }; + let ogg = encode_ogg_vorbis(&buf, &OggVorbisOptions::default().with_quality(quality)).expect("encode"); + let file = dir.join(format!("ours_{rate}_{channels}_{quality}.ogg")); + std::fs::write(&file, &ogg).expect("write fixture"); + let decoded = decode_ogg(&ogg).expect("decode"); + assert_eq!(decoded.damaged_packets, 0); + assert_eq!(decoded.sample_rate, rate); + assert_same(&format!("our stream {rate} Hz {channels} ch q{quality}"), &decoded.channels, &ffmpeg_decode(&ffmpeg, &file, channels)); + } +} + +/// ffmpeg's own Vorbis encoder (stereo only) writes setups ours does not: coupled channels, residue +/// type 2, floor classes with subclasses and master books, two block sizes. The reference is +/// Symphonia, an independent decoder. ffmpeg's decoder agrees on the first channel but not on the +/// second of these streams, where it differs from both Symphonia and this decoder; the stream does +/// not show which reading it means (the channel comes back poorly, about 3 dB SNR, in all three), +/// so ffmpeg is compared on the first channel only. The setups ffmpeg's decoder does read the same +/// way as we do are covered, on both channels, in `vorbis_decode_synthetic.rs`. +#[test] +fn we_decode_ffmpegs_encoder_streams_like_symphonia() { + let Some(ffmpeg) = craft_media_testkit::ffmpeg() else { return }; + let dir = craft_media_testkit::fixture_subdir("vorbis_decode"); + for (rate, bitrate) in [(44_100u32, "128k"), (48_000, "96k"), (22_050, "48k"), (32_000, "64k")] { + let channels = 2usize; + let pcm: Vec = { + let s = signal(rate, channels, rate as usize * 2 + 301); + (0..s[0].len()).flat_map(|i| s.iter().map(move |c| c[i])).collect() + }; + let raw = dir.join(format!("src_{rate}_{channels}.f32")); + std::fs::write(&raw, pcm.iter().flat_map(|v| v.to_le_bytes()).collect::>()).expect("write source"); + let file = dir.join(format!("ffmpeg_{rate}_{channels}_{bitrate}.ogg")); + let out = Command::new(&ffmpeg) + .args(["-v", "error", "-nostdin", "-y", "-f", "f32le", "-ar"]) + .arg(rate.to_string()) + .arg("-ac") + .arg(channels.to_string()) + .arg("-i") + .arg(&raw) + .args(["-c:a", "vorbis", "-strict", "-2", "-b:a", bitrate]) + .arg(&file) + .output() + .expect("run ffmpeg"); + assert!(out.status.success(), "ffmpeg could not encode {}: {}", file.display(), String::from_utf8_lossy(&out.stderr)); + let ogg = std::fs::read(&file).expect("read"); + let ours = decode_ogg(&ogg).expect("decode"); + assert_eq!(ours.damaged_packets, 0, "{}", file.display()); + let (_, symphonia) = craft_audio::decode(&ogg, Some("ogg")).expect("symphonia"); + let name = format!("ffmpeg-encoded {rate} Hz {bitrate}"); + assert_prefix(&name, &ours.channels, &symphonia.channels, false); + // The first channel also agrees with ffmpeg's decoder. + let theirs = ffmpeg_decode(&ffmpeg, &file, channels); + assert_prefix(&format!("{name} (channel 0 against ffmpeg)"), &ours.channels[..1], &theirs[..1], true); + } +} + +#[test] +fn packets_decode_one_at_a_time_to_the_file_result() { + let buf = AudioBuffer { sample_rate: 44_100, channels: signal(44_100, 2, 30_000) }; + let ogg = encode_ogg_vorbis(&buf, &OggVorbisOptions::default().with_quality(5.0)).expect("encode"); + let file = craft_media::ogg::open(ogg.as_slice()).expect("open"); + let s = &file.streams[file.stream_of(craft_media::ogg::Codec::Vorbis).expect("vorbis")]; + let mut dec = Decoder::new(&s.headers[0], &s.headers[1], &s.headers[2]).expect("decoder"); + assert_eq!((dec.identification().channels, dec.identification().sample_rate), (2, 44_100)); + let mut got: Vec> = vec![Vec::new(); 2]; + for i in 0..s.packets.len() { + let p = file.read_packet(ogg.as_slice(), 0, i).expect("packet"); + for (a, b) in got.iter_mut().zip(dec.decode_packet(&p).expect("packet decodes")) { + a.extend(b); + } + } + let whole = decode_ogg(&ogg).expect("file"); + for (a, b) in got.iter().zip(&whole.channels) { + assert!(a.len() >= b.len() && a[..b.len()] == b[..]); + } + // After a reset the next packet only primes the overlap again. + dec.reset(); + let p = file.read_packet(ogg.as_slice(), 0, 5).expect("packet"); + assert!(dec.decode_packet(&p).expect("decodes").iter().all(Vec::is_empty)); +} + +#[test] +fn the_round_trip_through_our_encoder_is_faithful() { + let src = signal(44_100, 2, 44_100); + let buf = AudioBuffer { sample_rate: 44_100, channels: src.clone() }; + let ogg = encode_ogg_vorbis(&buf, &OggVorbisOptions::default().with_quality(8.0)).expect("encode"); + let out = decode_ogg(&ogg).expect("decode"); + assert_eq!(out.channels[0].len(), src[0].len()); + let (mut sig, mut err) = (0f64, 0f64); + for (a, b) in src[0].iter().zip(&out.channels[0]) { + sig += f64::from(*a) * f64::from(*a); + err += f64::from(a - b) * f64::from(a - b); + } + assert!(10.0 * (sig / err).log10() > 15.0, "SNR {:.1} dB", 10.0 * (sig / err).log10()); +} + +/// A stream from libvorbis itself (the repository's `tone.ogg` fixture, made with ffmpeg's libvorbis +/// wrapper): mono, 8 kHz, the lowest quality. +#[test] +fn a_libvorbis_stream_decodes_like_ffmpeg() { + let path = Path::new(env!("CARGO_MANIFEST_DIR")).join("tests/fixtures/tone.ogg"); + let ogg = std::fs::read(&path).expect("fixture"); + let ours = decode_ogg(&ogg).expect("decode"); + assert_eq!((ours.sample_rate, ours.channels.len(), ours.damaged_packets), (8000, 1, 0)); + assert!(ours.comments.vendor.contains("Lavf") || ours.comments.vendor.contains("libVorbis"), "vendor {:?}", ours.comments.vendor); + assert!(ours.channels[0].iter().any(|s| s.abs() > 0.1), "the fixture is a tone"); + let Some(ffmpeg) = craft_media_testkit::ffmpeg() else { return }; + assert_prefix("libvorbis tone.ogg", &ours.channels, &ffmpeg_decode(&ffmpeg, &path, 1), false); +} + +#[test] +#[should_panic(expected = "non-finite oracle input or output")] +fn oracle_comparison_rejects_nan_output() { + assert_same("NaN output", &[vec![f32::NAN]], &[vec![0.0]]); +} + +#[test] +#[should_panic(expected = "non-finite oracle input or output")] +fn oracle_comparison_rejects_nan_reference() { + assert_same("NaN reference", &[vec![0.0]], &[vec![f32::NAN]]); +} diff --git a/crates/audio/tests/vorbis_decode_synthetic.rs b/crates/audio/tests/vorbis_decode_synthetic.rs new file mode 100644 index 000000000..46c48eced --- /dev/null +++ b/crates/audio/tests/vorbis_decode_synthetic.rs @@ -0,0 +1,384 @@ +//! Differential tests on streams built by hand: a setup header written here, with floor 0 and +//! floor 1 side by side, residues 0, 1 and 2, several submaps and channel coupling, followed by +//! random audio packets. Every packet of random bits is decodable, so the two decoders (ours and +//! ffmpeg's, the oracle; skipped when ffmpeg is absent, a failure with +//! `CRAFT_MEDIA_REQUIRE_ORACLES=1`) must return the same samples, and no encoder's habits narrow +//! what is exercised. Floor 0, residue 0 and multi-submap mappings are the parts no encoder here +//! writes. + +use craft_audio::vorbis::decoder::{Decoder, decode_ogg}; +use craft_media::ogg::{PageWriter, vorbis_comment}; +use std::process::Command; + +fn xorshift(seed: &mut u32) -> u32 { + *seed ^= *seed << 13; + *seed ^= *seed >> 17; + *seed ^= *seed << 5; + *seed +} + +/// A least-significant-bit-first bit writer. +#[derive(Default)] +struct W { + bytes: Vec, + bits: usize, +} + +impl W { + fn put(&mut self, v: u64, n: u32) { + for i in 0..n { + if self.bits.is_multiple_of(8) { + self.bytes.push(0); + } + let last = self.bytes.len() - 1; + self.bytes[last] |= (((v >> i) & 1) as u8) << (self.bits % 8); + self.bits += 1; + } + } + fn flag(&mut self, b: bool) { + self.put(u64::from(b), 1); + } +} + +fn float_bits(v: f64) -> u64 { + // The Vorbis float32 packing: sign, 10-bit exponent biased by 788, 21-bit mantissa. + if v == 0.0 { + return 0; + } + let (sign, a) = if v < 0.0 { (1u64 << 31, -v) } else { (0, v) }; + let mut exp = 0i32; + let mut m = a; + while m >= (1 << 21) as f64 { + m /= 2.0; + exp += 1; + } + while m < (1 << 20) as f64 { + m *= 2.0; + exp -= 1; + } + sign | (((exp + 788) as u64) << 21) | (m.round() as u64 & 0x1F_FFFF) +} + +/// A complete codebook: `entries` codewords all of length `len` (`entries == 2^len`), optionally +/// with a lookup table: `(type, minimum, delta, value_bits, multiplicands)`. +fn book(w: &mut W, dims: u32, entries: u32, len: u32, lookup: Option<(u32, f64, f64, u32, Vec)>) { + w.put(0x56_4342, 24); + w.put(u64::from(dims), 16); + w.put(u64::from(entries), 24); + w.flag(false); // not ordered + w.flag(false); // not sparse + for _ in 0..entries { + w.put(u64::from(len - 1), 5); + } + match lookup { + None => w.put(0, 4), + Some((ty, min, delta, bits, mult)) => { + w.put(u64::from(ty), 4); + w.put(float_bits(min), 32); + w.put(float_bits(delta), 32); + w.put(u64::from(bits - 1), 4); + w.flag(ty == 1); // sequence_p: cumulative for the floor 0 book + for m in mult { + w.put(u64::from(m), bits); + } + } + } +} + +struct Layout { + channels: u8, + /// The residue type of each of the two residues. + residue_types: [u32; 2], + /// The submap of each channel (0 or 1): submap 0 uses floor 0 and residue 0, submap 1 uses + /// floor 1 and residue 1. + mux: Vec, + coupling: Vec<(u8, u8)>, +} + +fn identification(channels: u8) -> Vec { + let mut w = W::default(); + w.put(1, 8); + for c in b"vorbis" { + w.put(u64::from(*c), 8); + } + w.put(0, 32); + w.put(u64::from(channels), 8); + w.put(16_000, 32); + w.put(0, 32); + w.put(0, 32); + w.put(0, 32); + w.put(8, 4); // short blocks: 256 + w.put(10, 4); // long blocks: 1024 + w.flag(true); + w.bytes +} + +fn setup(l: &Layout) -> Vec { + let mut w = W::default(); + w.put(5, 8); + for c in b"vorbis" { + w.put(u64::from(*c), 8); + } + // Books: 0 floor 0 vectors, 1 class book, 2 and 3 residue vectors, 4 floor 1 values. + w.put(4, 8); // five books + book(&mut w, 4, 16, 4, Some((1, 0.7, 0.2, 1, vec![0, 1]))); // lookup1_values(16, 4) = 2 + book(&mut w, 1, 4, 2, None); + book(&mut w, 2, 16, 4, Some((1, -0.4, 0.25, 2, vec![0, 1, 2, 3]))); // lookup1_values(16, 2) = 4 + book(&mut w, 4, 16, 4, Some((1, -0.3, 0.6, 1, vec![0, 1]))); + book(&mut w, 1, 128, 7, None); + // One time domain placeholder. + w.put(0, 6); + w.put(0, 16); + // Floors: 0 and 1. + w.put(1, 6); // two floors + w.put(0, 16); + w.put(8, 8); // order + w.put(16_000, 16); // rate + w.put(64, 16); // bark map size + w.put(8, 6); // amplitude bits + w.put(2, 8); // amplitude offset + w.put(0, 4); // one book + w.put(0, 8); + w.put(1, 16); + w.put(1, 5); // one partition + w.put(0, 4); // class 0 + w.put(2, 3); // dimension 3 + w.put(0, 2); // no subclasses + w.put(4 + 1, 8); // subclass book: book 4 (stored plus one) + w.put(1, 2); // multiplier 2 + w.put(8, 4); // rangebits + for x in [10, 40, 130] { + w.put(x, 8); + } + // Residues. + w.put(1, 6); // two residues + for ty in l.residue_types { + w.put(u64::from(ty), 16); + w.put(0, 24); // begin + w.put(if ty == 2 { 96 } else { 48 }, 24); // end + w.put(7, 24); // partition size 8 + w.put(3, 6); // four classifications + w.put(1, 8); // class book + for _ in 0..4 { + w.put(0b011, 3); // passes 0 and 1 + w.flag(false); + } + for class in 0..4 { + w.put(2 + (class % 2), 8); // pass 0 uses book 2 or 3 + w.put(3 - (class % 2), 8); // pass 1 uses book 3 or 2 + } + } + // One mapping, two submaps. + w.put(0, 6); + w.put(0, 16); + w.flag(true); + w.put(1, 4); // two submaps + w.flag(!l.coupling.is_empty()); + if !l.coupling.is_empty() { + w.put(l.coupling.len() as u64 - 1, 8); + let bits = if l.channels <= 1 { 0 } else { 8 - (l.channels - 1).leading_zeros() }; + for &(m, a) in &l.coupling { + w.put(u64::from(m), bits); + w.put(u64::from(a), bits); + } + } + w.put(0, 2); + for &m in &l.mux { + w.put(u64::from(m), 4); + } + for sub in 0..2u64 { + w.put(0, 8); + w.put(sub, 8); // floor + w.put(sub, 8); // residue + } + // Two modes over the one mapping. + w.put(1, 6); + for long in [false, true] { + w.flag(long); + w.put(0, 16); + w.put(0, 16); + w.put(0, 8); + } + w.flag(true); + w.bytes +} + +fn stream(l: &Layout, packets: usize, seed: &mut u32) -> Vec { + let mut pages = PageWriter::new(7); + let mut out = pages.header(&identification(l.channels)); + out.extend(pages.header(&vorbis_comment("synthetic", &[("TITLE", "hand built")]))); + out.extend(pages.header(&setup(l))); + // The window flags of a long block say whether its neighbours are long, so choose the block + // sizes first. + let longs: Vec = (0..packets).map(|_| !xorshift(seed).is_multiple_of(3)).collect(); + let mut granule = 0i64; + for i in 0..packets { + let long = longs[i]; + // Packet type 0, the mode bit, and for a long block the two neighbour flags. + let prev = i == 0 || longs[i - 1]; + let next = i + 1 >= packets || longs[i + 1]; + let mut w = W::default(); + w.flag(false); + w.flag(long); + if long { + w.flag(prev); + w.flag(next); + } + // Floor 0 needs a codebook number that exists, which random bits would not give, so the + // channels that use it (the first ones) are written properly: an amplitude, book 0 and two + // codewords of its vectors (a full tree of 4-bit codes: the code is the entry number). + for _ in 0..l.mux.iter().take_while(|&&m| m == 0).count() { + w.put(1 + u64::from(xorshift(seed)) % 24, 8); + w.put(0, 1); + for _ in 0..2 { + let entry = xorshift(seed) % 16; + for bit in (0..4).rev() { + w.put(u64::from(entry >> bit) & 1, 1); + } + } + } + // The rest is random bits, enough that no residue runs out of packet. + let mut p = w.bytes; + let fixed = p.len(); + p.extend((0..200 + xorshift(seed) as usize % 200).map(|_| xorshift(seed) as u8)); + let _ = fixed; + // The bits after the fixed fields start mid-byte: the last fixed byte keeps its own bits and + // takes random ones above them. + let used = w.bits % 8; + if used != 0 { + let last = fixed - 1; + p[last] |= (xorshift(seed) as u8) << used; + } + if i > 0 { + let size = |long: bool| if long { 1024 } else { 256 }; + granule += (size(longs[i - 1]) / 4 + size(long) / 4) as i64; + } + out.extend(pages.packet(&p, granule)); + } + out.extend(pages.finish(None)); + out +} + +/// `tolerance`: the largest difference from ffmpeg, as a fraction of the peak output. A floor 0 +/// curve is an exponential of a quotient that random coefficients can make very large, so where +/// two floors meet in one stream (ffmpeg computes in single precision, we in double) the results +/// agree only to about a thousandth of the peak. +fn run(name: &str, l: &Layout, seed: u32, tolerance: f32) { + let mut s = seed; + let ogg = stream(l, 40, &mut s); + // Packet by packet our decoder must accept every one. + let file = craft_media::ogg::open(ogg.as_slice()).expect("open"); + let st = &file.streams[0]; + let mut dec = Decoder::new(&st.headers[0], &st.headers[1], &st.headers[2]).expect("setup decodes"); + let mut total = vec![Vec::new(); usize::from(l.channels)]; + for i in 0..st.packets.len() { + let p = file.read_packet(ogg.as_slice(), 0, i).expect("packet"); + let pcm = dec.decode_packet(&p).unwrap_or_else(|e| panic!("{name}: packet {i}: {e}")); + for (t, c) in total.iter_mut().zip(pcm) { + t.extend(c); + } + } + let expected = usize::try_from(st.last_granule.expect("generated final granule")).expect("nonnegative granule"); + for channel in &total { + assert_eq!(channel.len(), expected, "{name}: decoded sample count"); + assert!(channel.iter().all(|v| v.is_finite()), "{name}: non-finite output"); + } + let whole = decode_ogg(&ogg).expect("whole file"); + assert_eq!(whole.channels, total, "{name}: packet and file decoding differ"); + let Some(ffmpeg) = craft_media_testkit::ffmpeg() else { return }; + let dir = craft_media_testkit::fixture_subdir("vorbis_synthetic"); + let path = dir.join(format!("{name}.ogg")); + std::fs::write(&path, &ogg).expect("write fixture"); + let out = Command::new(&ffmpeg) + .args(["-v", "error", "-nostdin", "-i"]) + .arg(&path) + .args(["-f", "f32le", "-acodec", "pcm_f32le", "-"]) + .output() + .expect("run ffmpeg"); + assert!(out.status.success(), "{name}: ffmpeg failed: {}", String::from_utf8_lossy(&out.stderr)); + let all: Vec = out.stdout.as_chunks::<4>().0.iter().map(|b| f32::from_le_bytes(*b)).collect(); + let ch = usize::from(l.channels); + let theirs: Vec> = (0..ch).map(|c| all.iter().skip(c).step_by(ch).copied().collect()).collect(); + assert!(theirs.iter().flatten().all(|v| v.is_finite()), "{name}: non-finite ffmpeg output"); + for channel in &theirs { + assert!(channel.len() >= expected, "{name}: ffmpeg returned fewer than the expected samples"); + } + // ffmpeg puts the channels of surround streams in its own order, so each of ours is matched + // with the channel of theirs it agrees with best, and every one of theirs is used once. + let mut used = vec![false; ch]; + #[allow(clippy::needless_range_loop)] + for c in 0..ch { + let mut best: Option<(usize, f32, f32)> = None; + for (k, t) in theirs.iter().enumerate().filter(|(k, _)| !used[*k]) { + let n = total[c].len().min(t.len()); + assert!(n > 1000, "{name}: only {n} samples to compare"); + let scale = total[c][..n].iter().fold(1e-3f32, |m, v| m.max(v.abs())); + let worst = (0..n).map(|i| (total[c][i] - t[i]).abs()).fold(0f32, f32::max); + if best.is_none_or(|(_, w, sc)| worst / scale < w / sc) { + best = Some((k, worst, scale)); + } + } + let (k, worst, scale) = best.expect("a free channel"); + used[k] = true; + assert!(worst <= tolerance * scale + 1e-5, "{name}: channel {c} differs from ffmpeg's channel {k} by {worst} (peak {scale})"); + } +} + +#[test] +fn mono_floor_zero_and_residue_zero() { + run("mono_f0_r0", &Layout { channels: 1, residue_types: [0, 0], mux: vec![0], coupling: vec![] }, 11, 1e-4); +} + +#[test] +fn mono_floor_one_and_residue_one() { + run("mono_f1_r1", &Layout { channels: 1, residue_types: [1, 1], mux: vec![1], coupling: vec![] }, 12, 1e-4); +} + +#[test] +fn two_submaps_floor_zero_and_one() { + run("stereo_mixed", &Layout { channels: 2, residue_types: [0, 1], mux: vec![0, 1], coupling: vec![] }, 13, 3e-3); +} + +#[test] +fn coupled_stereo_residue_two() { + run("stereo_coupled_r2", &Layout { channels: 2, residue_types: [2, 2], mux: vec![1, 1], coupling: vec![(0, 1)] }, 14, 1e-4); +} + +#[test] +fn six_channels_with_coupling_and_submaps() { + let l = Layout { channels: 6, residue_types: [1, 2], mux: vec![0, 0, 0, 1, 1, 1], coupling: vec![(0, 3), (1, 2), (4, 5)] }; + run("six", &l, 15, 3e-3); +} + +#[test] +fn mono_floor_one_and_residue_zero() { + run("mono_f1_r0", &Layout { channels: 1, residue_types: [0, 0], mux: vec![1], coupling: vec![] }, 16, 1e-4); +} + +#[test] +fn mono_floor_zero_and_residue_one() { + run("mono_f0_r1", &Layout { channels: 1, residue_types: [1, 1], mux: vec![0], coupling: vec![] }, 17, 1e-4); +} + +/// A packet that names a floor 0 codebook that does not exist cannot be decoded (§6.2.2); the +/// decoder says so and the stream goes on with the next packet. +#[test] +fn a_floor_zero_codebook_that_does_not_exist_is_a_packet_error() { + let l = Layout { channels: 1, residue_types: [1, 1], mux: vec![0], coupling: vec![] }; + let mut seed = 5u32; + let ogg = stream(&l, 6, &mut seed); + let file = craft_media::ogg::open(ogg.as_slice()).expect("open"); + let st = &file.streams[0]; + let mut dec = Decoder::new(&st.headers[0], &st.headers[1], &st.headers[2]).expect("decoder"); + let good = file.read_packet(ogg.as_slice(), 0, 0).expect("packet"); + assert!(dec.decode_packet(&good).is_ok()); + // A short block: type 0, mode 0, then the 8 amplitude bits, then book number 1 (only 0 exists). + let mut w = W::default(); + w.flag(false); + w.flag(false); + w.put(9, 8); + w.put(1, 1); + w.put(0, 64); + assert!(matches!(dec.decode_packet(&w.bytes), Err(craft_audio::vorbis::decoder::Error::Packet(_)))); + assert!(dec.decode_packet(&good).is_ok(), "the decoder carries on"); +} diff --git a/crates/automation/Cargo.toml b/crates/automation/Cargo.toml index 57112ef71..a9fcf894a 100644 --- a/crates/automation/Cargo.toml +++ b/crates/automation/Cargo.toml @@ -25,12 +25,15 @@ ui = ["dep:craft-behavior", "dep:craft-keymap", "dep:craft-ui", "dep:egui"] # The Actions panel's and the Agents page's stories and mock, and the integration binary `tests/it`. screen-testing = ["ui", "agents", "craft-ui/testing"] # Agents in the open window (desktop): the ArtCraft Launcher's switch, the connection file an -# app's `-cli mcp` reads, and with `ui` the link host and the Agents page. The agent settings -# build on every target without it. -agents = ["dep:craft-ai-agents", "dep:craft-flags", "dep:craft-atomic", "dep:craft-host"] +# app's `-cli mcp` reads and that CLI's live client (all `craft-control`'s, re-exported), and +# with `ui` the link host and the Agents page. The agent settings build on every target without it. +agents = ["craft-control/agents", "dep:craft-host"] [dependencies] craft-behavior = { workspace = true, optional = true } +# The agents code without a UI toolkit (settings, the launcher's switch, the connection file, the +# CLI's live client), re-exported by `agents` so every app shares one copy. +craft-control = { workspace = true } craft-keymap = { workspace = true, optional = true } craft-theme = { workspace = true } craft-ui = { workspace = true, optional = true } @@ -45,9 +48,6 @@ png = "0.17" # The server, client, profiler and trace. [target.'cfg(not(target_arch = "wasm32"))'.dependencies] craft-platform = { workspace = true } -craft-ai-agents = { workspace = true, optional = true } -craft-atomic = { workspace = true, optional = true } -craft-flags = { workspace = true, optional = true } craft-host = { workspace = true, optional = true } getrandom = "0.3" hmac = "0.12" diff --git a/crates/automation/README.md b/crates/automation/README.md index 1c9ff22d4..d82a01e5b 100644 --- a/crates/automation/README.md +++ b/crates/automation/README.md @@ -8,7 +8,7 @@ Features: `ui` (the egui parts), `agents` (agents in the open window: the launch | --- | --- | | `actions` | Recorded actions (every target): `ActionList` of `Action`s and `ActionStep`s, `ActionsFile`, playback with `ActionPlayer` and `ActionRunner` under a `PlaybackBudget`, and `Recording`. The app keeps the command table. | | `ui::actions` | `ActionsPanel` (every target): sets, actions and steps as a tree, include and dialog cells, rename (`start_rename`), drag to move, Button Mode, the footer and the menus (`ActionsPanelCommands`, `ActionsMenuFacts` and `panel_rows`, which leaves out the rows the host has no command for). It runs nothing; it reports `ActionsEvent`s. `ActionsPanelState` holds its view state. `ActionsWords` holds its words. | -| `agents` | AI agents in the open window. Every target: `AgentSettings` (Control Port, the folders agents may open from and save to, `WhenAppClosed`, Allow Agent Control) and `agents_allowed`. Desktop, feature `agents`: `AgentSwitch`, the ArtCraft Launcher's switch for the app behind the suite's `AI-MCP` flag, watched on a thread; the connection file (`Connection`, `write_connection`, `read_connection`, `remove_stale_connection`, `probe`) that the app's `-cli mcp` finds the open window by. With `ui`: `AgentLink`, the link host that starts, moves, stops and retries the agents' control server to match the settings and publishes the connection file. | +| `agents` | AI agents in the open window. Every target: `AgentSettings` (Control Port, the folders agents may open from and save to, `WhenAppClosed`, Allow Agent Control) and `agents_allowed`. Desktop, feature `agents`: `AgentSwitch`, the ArtCraft Launcher's switch for the app behind the suite's `AI-MCP` flag, watched on a thread; the connection file (`Connection`, `write_connection`, `read_connection`, `remove_stale_connection`, `probe`) that the app's `-cli mcp` finds the open window by; the CLI's live client (`Live`, `LiveConfig`, `Route`). All of these are `craft_control::agents`, re-exported, so apps without the shared UI library use the same code. With `ui`: `AgentLink`, the link host that starts, moves, stops and retries the agents' control server to match the settings and publishes the connection file. | | `ui::agents` | `AgentsPage` (desktop, features `agents` and `ui`): the Agents page of Preferences, a custom page over the agent settings in the Preferences draft, with the link's status; the folder rows are `PathSetting`s. `AgentsWords` holds its words. | | `args` | `ControlOptions`: the `--control `, `--control-token`, `--control-token-file` values and their `_CONTROL_*` environment fallbacks, checked the way the apps' command lines report them (usage errors exit 2). | | `security` | Tokens (`generate_token`, `validate_token`, `server_token`, `client_token`), the authentication handshake (`ServerHandshake`: the challenge handshake, which never sends the token, or the one-frame `auth {token}`), bounded line reads, connection and request limits. | diff --git a/crates/automation/src/agents/mod.rs b/crates/automation/src/agents/mod.rs index 949740ed8..0ff21d3a8 100644 --- a/crates/automation/src/agents/mod.rs +++ b/crates/automation/src/agents/mod.rs @@ -9,8 +9,8 @@ //! While agents may connect, the app serves its control channel on loopback ([`AgentLink`], over //! [`crate::server`]) and publishes where in its settings folder ([`CONNECTION_FILE`]): the port, //! its process id and the token file ([`TOKEN_FILE`], created `0600` on Unix). The app's -//! `-cli mcp` reads that file on every tool call, then the token from the file it names, so an -//! MCP client's configuration never holds a port or a token. +//! `-cli mcp` reads that file on every tool call ([`Live`]), then the token from the file it +//! names, so an MCP client's configuration never holds a port or a token. //! //! The file holds no secret. A crashed (or, on macOS, quit) app can leave it behind; nothing then //! listens on its port ([`probe`]), and the app's next launch removes it @@ -18,29 +18,32 @@ //! checks that [`Connection::pid`] is still running before it sends anything derived from the //! token, and authenticates with the challenge handshake ([`crate::security::ServerHandshake`]). //! +//! Everything but the link host is `craft_control::agents`, re-exported here: apps that don't use +//! the shared UI library use it from there, with the same files and formats. +//! //! | Part | Names | Builds | //! |---|---|---| //! | Settings | [`AgentSettings`], [`WhenAppClosed`], [`agents_allowed`], [`folder`] | every target | //! | The launcher's switch | [`AgentSwitch`], [`mcp_flag`], [`launcher_allows`], [`POLL`] | desktop, feature `agents` | //! | The connection file | [`Connection`], [`write_connection`], [`read_connection`], [`remove_connection`], [`remove_stale_connection`], [`probe`] | desktop, feature `agents` | +//! | The CLI's side | [`Live`], [`LiveConfig`], [`Route`], [`Window`], [`Consent`], [`HeadlessFolders`], [`find_window`], [`launcher`] | desktop, feature `agents` | //! | The link host | [`AgentLink`], [`AgentLinkStatus`], [`LinkProblem`], [`LinkUpdate`] | desktop, features `agents` and `ui` | //! //! The Agents page of Preferences is [`crate::ui::agents`]. -mod settings; -pub use settings::{AgentSettings, WhenAppClosed, agents_allowed, folder}; +// The links above name items of the `agents` and `ui` features; without them they have nothing to +// point at, and the docs of the settings alone still build. +#![cfg_attr(not(all(feature = "agents", feature = "ui", not(target_arch = "wasm32"))), allow(rustdoc::broken_intra_doc_links))] + +pub use craft_control::agents::{AgentSettings, WhenAppClosed, agents_allowed, folder}; -#[cfg(all(feature = "agents", not(target_arch = "wasm32")))] -mod connection; #[cfg(all(feature = "agents", feature = "ui", not(target_arch = "wasm32")))] mod link; #[cfg(all(feature = "agents", not(target_arch = "wasm32")))] -mod switch; -#[cfg(all(feature = "agents", not(target_arch = "wasm32")))] -pub use connection::{ - CONNECTION_FILE, Connection, PROBE_TIMEOUT, TOKEN_FILE, probe, read_connection, remove_connection, remove_stale_connection, write_connection, +pub use craft_control::agents::{ + AgentSwitch, CONNECTION_FILE, ConnectFn, Connection, Consent, ConsentFn, HeadlessFn, HeadlessFolders, LAUNCH_POLL, LAUNCH_TIMEOUT, LaunchFn, + Live, LiveConfig, POLL, PROBE_TIMEOUT, Route, TOKEN_FILE, Window, find_window, launcher, launcher_allows, mcp_flag, probe, read_connection, + remove_connection, remove_stale_connection, write_connection, }; #[cfg(all(feature = "agents", feature = "ui", not(target_arch = "wasm32")))] pub use link::{AgentLink, AgentLinkStatus, LinkProblem, LinkUpdate, RETRY}; -#[cfg(all(feature = "agents", not(target_arch = "wasm32")))] -pub use switch::{AgentSwitch, POLL, launcher_allows, mcp_flag}; diff --git a/crates/automation/src/control.rs b/crates/automation/src/control.rs index d0a70d901..cc1e37c81 100644 --- a/crates/automation/src/control.rs +++ b/crates/automation/src/control.rs @@ -236,12 +236,13 @@ impl ControlChannel { /// Answers the [`Reply::AfterInput`] waiters from the window host's input state: with /// `input cancelled` when the host withdrew queued input ([`TARGET_CHANGED`]), with success - /// once nothing is queued or in flight. Call it once per pass, after the pass that consumed the - /// input. + /// once nothing is queued or in flight. Call it once per pass, at the end of the pass (after its + /// UI ran): the step that pass consumed counts as run, so the reply goes out with that pass + /// ([`WindowHost::injected_idle_at_pass_end`]). Called between passes, it waits for the pass. pub fn poll_input(&mut self, host: &WindowHost) { if host.take_injected_withdrawn() { self.input_cancelled(TARGET_CHANGED); - } else if host.injected_idle() { + } else if host.injected_idle_at_pass_end() { self.input_processed(); } } diff --git a/crates/automation/tests/it/agents.rs b/crates/automation/tests/it/agents.rs index 2ffb2b5e6..7ca7bb5f0 100644 --- a/crates/automation/tests/it/agents.rs +++ b/crates/automation/tests/it/agents.rs @@ -14,7 +14,7 @@ use craft_automation::agents::{ }; use craft_automation::server; use craft_automation::ui::agents::AgentsPage; -use craft_host::{AppInfo, Host, PickId, Picked, ScriptedFiles, Wake}; +use craft_host::{AppInfo, Host, PickId, Picked, ScriptedFiles}; use craft_ui::contract::Role; use craft_ui::patterns::preferences::SettingsDraft; use craft_ui::runtime::motion; @@ -68,9 +68,9 @@ fn the_switch_wakes_once_per_change() { }; let wake = { let wakes = wakes.clone(); - Wake::new(move || { + move || { wakes.fetch_add(1, Ordering::Relaxed); - }) + } }; let switch = AgentSwitch::watch_with(true, probe, Duration::from_millis(5), wake); let clone = switch.clone(); @@ -161,7 +161,9 @@ fn host() -> WindowHost { } fn on(port: u32) -> AgentSettings { - AgentSettings { control_port: port, ..AgentSettings::default() } + let mut s = AgentSettings::default(); + s.control_port = port; + s } /// A port nothing listens on: bound, then closed. @@ -188,7 +190,8 @@ fn turning_agents_on_publishes_a_reachable_connection_and_off_removes_it() { assert!(probe(port, PROBE_TIMEOUT)); let token = std::fs::read_to_string(dir.path().join(TOKEN_FILE)).unwrap(); - let folders = AgentSettings { read_root: "/in".into(), ..on(0) }; + let mut folders = on(0); + folders.read_root = "/in".into(); let kept = link.sync(Some(&folders), &host); assert!(kept.requests.is_none() && !kept.stopped && kept.changed, "a folder change keeps the server"); assert_eq!(link.status().port, Some(port)); @@ -266,7 +269,9 @@ fn allow_agent_control_off_and_no_settings_folder_keep_agents_out() { let mut link = AgentLink::new(Some(dir.path().to_path_buf()), "x"); assert!(link.sync(Some(&on(0)), &host).requests.is_some()); let port = link.status().port.expect("listening"); - let refused = link.sync(Some(&AgentSettings { allow_agent_control: false, ..on(0) }), &host); + let mut off = on(0); + off.allow_agent_control = false; + let refused = link.sync(Some(&off), &host); assert!(refused.stopped && refused.requests.is_none()); assert_eq!(link.status().problem, Some(LinkProblem::NotAllowed)); assert!(!dir.path().join(CONNECTION_FILE).exists()); diff --git a/crates/automation/tests/it/synthetic.rs b/crates/automation/tests/it/synthetic.rs index 5bb2cb0f4..494cc848d 100644 --- a/crates/automation/tests/it/synthetic.rs +++ b/crates/automation/tests/it/synthetic.rs @@ -186,6 +186,74 @@ fn injected_caps_lock_holds_until_cleared() { assert_eq!(rig.host().injected_caps_lock(), None); } +/// Per pass: whether the waiter had its reply by the pass's end, and the pointer position the pass saw. +type PassLog = Rc)>>>; + +/// A fixture whose UI polls `channel` at the end of each pass, as an application does after its UI, with `discard` +/// asking egui to run the pass again on the passes it is true for; `answered` records, per pass, whether the waiter +/// had its reply by the pass's end and the pointer position the pass saw. +fn polling_fixture( + channel: Rc>, + reply: Rc>, + discard: impl Fn(usize) -> bool + 'static, +) -> (Fixture, PassLog) { + let answered = Rc::new(RefCell::new(Vec::new())); + let seen = answered.clone(); + let fx = Fixture::new(move |ui| { + let pass = seen.borrow().len(); + if discard(pass) { + ui.ctx().request_discard("the test runs this pass again"); + } + channel.borrow_mut().poll_input(&WindowHost::of(ui.ctx())); + let pos = ui.input(|i| i.pointer.latest_pos()); + seen.borrow_mut().push((reply.try_recv().is_ok(), pos)); + }); + (fx, answered) +} + +/// A waiter on a move is answered at the end of the pass that ran the move, not a pass later: the application polls +/// after its UI, where the running pass has not ended yet. +#[trial] +fn a_waiter_is_answered_by_the_pass_that_ran_its_step() { + use craft_automation::control::{ControlChannel, ControlRequest, Reply}; + + let (_transport, requests) = std::sync::mpsc::channel(); + let channel = Rc::new(RefCell::new(ControlChannel::new(requests))); + let (req, reply) = ControlRequest::new("ui.move", json!({"x": 30, "y": 20})); + let (mut fx, answered) = polling_fixture(channel.clone(), Rc::new(reply), |_| false); + fx.idle(2); + answered.borrow_mut().clear(); + let host = WindowHost::of(fx.ctx()); + input_method("ui.move", &json!({"x": 30, "y": 20}), &host, ViewportId::ROOT, &map).expect("a method").expect("valid"); + channel.borrow_mut().settle(req, Reply::AfterInput, None, 0.0); + fx.frame(Vec::new()); + let passes = answered.borrow().clone(); + assert_eq!(passes, vec![(true, Some(pos2(30.0, 20.0)))], "the pass that saw the move answered it"); +} + +/// A pass egui runs again (`request_discard`) does not answer: the pass that runs again, and draws what the step +/// did, does. +#[trial] +fn a_pass_run_again_leaves_the_answer_to_its_rerun() { + use craft_automation::control::{ControlChannel, ControlRequest, Reply}; + + let (_transport, requests) = std::sync::mpsc::channel(); + let channel = Rc::new(RefCell::new(ControlChannel::new(requests))); + let (req, reply) = ControlRequest::new("ui.move", json!({"x": 30, "y": 20})); + let start = Rc::new(Cell::new(usize::MAX)); + let first = start.clone(); + let (mut fx, answered) = polling_fixture(channel.clone(), Rc::new(reply), move |pass| pass == first.get()); + fx.idle(2); + start.set(answered.borrow().len()); + let host = WindowHost::of(fx.ctx()); + input_method("ui.move", &json!({"x": 30, "y": 20}), &host, ViewportId::ROOT, &map).expect("a method").expect("valid"); + channel.borrow_mut().settle(req, Reply::AfterInput, None, 0.0); + fx.frame(Vec::new()); + assert_eq!(fx.passes(), 2, "egui ran the discarded pass again"); + let passes: Vec = answered.borrow()[start.get()..].iter().map(|(done, _)| *done).collect(); + assert_eq!(passes, vec![false, true], "the rerun answers, the discarded pass does not"); +} + /// A move with `rest` counts as processed only once the pointer has rested that long. #[trial] fn a_hover_rest_holds_the_reply_until_it_has_passed() { diff --git a/crates/behavior/src/dock/apply.rs b/crates/behavior/src/dock/apply.rs index 4772f014c..0f0760a1b 100644 --- a/crates/behavior/src/dock/apply.rs +++ b/crates/behavior/src/dock/apply.rs @@ -22,8 +22,8 @@ impl Layout

{ /// action closed (see [`Self::closed_by`]) so the application can release their state. /// The callback must be stable throughout one call. Registry validation remains with the /// application, particularly Open. The column rights ([`Permissions::collapses`], - /// [`Permissions::shares_column`]) are checked on the result: an action that leaves a panel breaking them, - /// which did not before, is refused, so a drag's dry run refuses it alike. + /// [`Permissions::shares_column`], [`Permissions::docks_outside_columns`]) are checked on the result: an action + /// that leaves a panel breaking them, which did not before, is refused, so a drag's dry run refuses it alike. pub fn apply_with_permissions(&mut self, action: Action

, permissions: impl Fn(&P) -> Permissions) -> Result, DockError> { self.validate()?; let action = match action { @@ -125,10 +125,12 @@ impl Layout

{ } /// The panels that break their column rights: a panel that does not collapse ([`Permissions::collapses`]) in - /// a collapsed column, and every panel of a column (or node of the docked tree) that holds a panel that does - /// not share it ([`Permissions::shares_column`]) beside another panel. + /// a collapsed column, every panel of a column (or node of the docked tree) that holds a panel that does + /// not share it ([`Permissions::shares_column`]) beside another panel, and a panel that docks only in dock + /// columns ([`Permissions::docks_outside_columns`]) in a frame of the docked tree. pub(super) fn column_breaches(&self, permissions: &impl Fn(&P) -> Permissions) -> HashSet

{ let mut breaches = HashSet::new(); + let mut framed = Vec::new(); let mut check = |panels: Vec<&P>, iconic: bool| { if iconic { breaches.extend(panels.iter().filter(|p| !permissions(p).collapses).map(|p| (*p).clone())); @@ -147,9 +149,14 @@ impl Layout

{ check(column.panels().collect(), column.iconic); } } - leaf => check(tree_panels(leaf), false), + leaf => { + let panels = tree_panels(leaf); + framed.extend(panels.iter().filter(|p| !permissions(p).docks_outside_columns).map(|p| (*p).clone())); + check(panels, false); + } } } + breaches.extend(framed); breaches } diff --git a/crates/behavior/src/dock/policy.rs b/crates/behavior/src/dock/policy.rs index 99a9f4005..629008c34 100644 --- a/crates/behavior/src/dock/policy.rs +++ b/crates/behavior/src/dock/policy.rs @@ -26,6 +26,10 @@ pub struct Permissions { /// panels: refused are tab, center, group and seam placements across that boundary in either direction, while a /// new column, a new dock and a float stay allowed. A toolbar takes its own column. pub shares_column: bool, + /// The panel may dock outside a dock column: in a frame of the docked tree, as a split beside another frame or at + /// an edge of the docked area, where it can lie across the window. Without it the panel docks only in dock columns + /// or floats: refused is any action that leaves it in a frame, so a toolbar is always a vertical strip. + pub docks_outside_columns: bool, } impl Default for Permissions { @@ -35,9 +39,18 @@ impl Default for Permissions { } impl Permissions { - /// Every right: the panel moves, floats, closes, takes tabs and splits, collapses and shares its column. - pub const ALL: Self = - Self { movable: true, floatable: true, closable: true, accepts_tabs: true, accepts_splits: true, collapses: true, shares_column: true }; + /// Every right: the panel moves, floats, closes, takes tabs and splits, collapses, shares its column and docks + /// outside dock columns. + pub const ALL: Self = Self { + movable: true, + floatable: true, + closable: true, + accepts_tabs: true, + accepts_splits: true, + collapses: true, + shares_column: true, + docks_outside_columns: true, + }; /// A document canvas: it stays docked and open, and takes neither tabs nor side splits. /// A group dropped on it floats there. An application that opens panels beside its canvas @@ -86,6 +99,12 @@ impl Permissions { self } + /// These permissions with [`Self::docks_outside_columns`] set to `docks_outside_columns`. + pub const fn docks_outside_columns(mut self, docks_outside_columns: bool) -> Self { + self.docks_outside_columns = docks_outside_columns; + self + } + /// A canvas: it can neither move, close nor take tabs. `accepts_splits` and `floatable` /// do not matter, so a canvas that opens panels beside it still counts. pub fn is_protected(self) -> bool { diff --git a/crates/behavior/src/dock/workspace.rs b/crates/behavior/src/dock/workspace.rs index 167ff20dc..d261427ce 100644 --- a/crates/behavior/src/dock/workspace.rs +++ b/crates/behavior/src/dock/workspace.rs @@ -10,7 +10,7 @@ use super::{ DockSide, action::{Action, DockPlacement, Location}, edit::tree_panels, - groups::{Column, PanelPlace, Target}, + groups::{Column, DockEdge, PanelPlace, Target}, layout::Layout, limits::MAX_PANELS, node::Node, @@ -285,8 +285,9 @@ impl Workspace

{ /// A registered panel that `permissions` says cannot close, such as a protected canvas, is /// always shown: at its recorded or default place, else at the outer edge of the docked /// area. A layout that breaks the column rights is repaired: a collapsed column holding a panel that does not - /// collapse ([`Permissions::collapses`]) expands, and a panel that shares no column - /// ([`Permissions::shares_column`]) moves to a column of its own. Pass the panels' own permissions, not + /// collapse ([`Permissions::collapses`]) expands, a panel that shares no column + /// ([`Permissions::shares_column`]) moves to a column of its own, and a panel that docks only in dock columns + /// ([`Permissions::docks_outside_columns`]) moves from a frame to a dock column. Pass the panels' own permissions, not /// [`Permissions::locked`] ones. /// `hidden` keeps at most [`MAX_PANELS`] entries, dropping the oldest unregistered ones first. pub fn reconcile(&mut self, registered: impl Fn(&P) -> bool, permissions: impl Fn(&P) -> Permissions, default: &Workspace

) { @@ -347,10 +348,41 @@ impl Workspace

{ } impl Workspace

{ + /// Moves each panel that docks only in dock columns ([`Permissions::docks_outside_columns`]) out of a frame of the + /// docked tree: to a new dock at the start edge, else a new dock at the end edge, else a column of its own at the + /// outer side of the first docked column. A move the layout refuses leaves the panel where it was. + fn repair_framed(&mut self, permissions: &impl Fn(&P) -> Permissions) { + let framed: Vec

= self + .layout + .panels() + .into_iter() + .filter(|p| !permissions(p).docks_outside_columns && matches!(self.layout.place(p), Some(PanelPlace::Node(_)))) + .cloned() + .collect(); + for panel in framed { + let column_anchor = + self.layout.panels().into_iter().find(|p| *p != &panel && matches!(self.layout.place(p), Some(PanelPlace::Dock { .. }))).cloned(); + let targets = [Some(Target::NewDock { side: DockEdge::Start }), Some(Target::NewDock { side: DockEdge::End })] + .into_iter() + .chain([column_anchor.map(|anchor| Target::At { anchor, placement: DockPlacement::Column { after: false } })]); + for to in targets.flatten() { + let mut layout = self.layout.clone(); + let moved = layout.apply_inner(Action::MovePanel { panel: panel.clone(), to }, &|p| permissions(p).is_protected()).is_ok(); + if moved && layout.validate().is_ok() { + self.layout = layout; + break; + } + } + } + } + /// Moves each panel that shares no column but has company to a column of its own: a new dock column beside its /// column, a new window over its window, or a frame beside its node of the docked tree. Then expands each - /// collapsed column that holds a panel that does not collapse. A repair the layout refuses leaves it as it was. + /// collapsed column that holds a panel that does not collapse, and moves each panel that docks only in dock + /// columns out of a frame of the docked tree into a dock column ([`Self::repair_framed`]). A repair the layout + /// refuses leaves it as it was. fn repair_columns(&mut self, permissions: &impl Fn(&P) -> Permissions) { + self.repair_framed(permissions); let lonely: Vec

= self.layout.panels().into_iter().filter(|p| !permissions(p).shares_column).cloned().collect(); for panel in lonely { let Some(place) = self.layout.place(&panel) else { continue }; diff --git a/crates/behavior/src/fit.rs b/crates/behavior/src/fit.rs index d37f3341b..4814a0078 100644 --- a/crates/behavior/src/fit.rs +++ b/crates/behavior/src/fit.rs @@ -206,7 +206,7 @@ fn squeeze(natural: &[f32], indices: &[usize], total: f32, minimum: f32) -> Vec< } /// Whether an item may move into the overflow menu, or lives there. -#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)] +#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash)] #[non_exhaustive] pub enum FitKeep { /// The item leaves the strip when the room runs out, last item first. diff --git a/crates/behavior/src/hit.rs b/crates/behavior/src/hit.rs index 1a77ccf26..0ca496cdd 100644 --- a/crates/behavior/src/hit.rs +++ b/crates/behavior/src/hit.rs @@ -30,13 +30,15 @@ pub enum HitShape { /// The other end. b: Pos2, }, - /// A chain of segments, hit within [`LINE_REACH`]. + /// A chain of segments, hit within `reach` ([`LINE_REACH`] unless [`HitShape::polyline_within`] says otherwise). #[non_exhaustive] Polyline { /// The corners in order. points: Vec, /// Whether the last corner joins the first. closed: bool, + /// How far from the chain a point still hits it, in points. + reach: f32, }, /// A filled polygon. Polygon(Vec), @@ -62,9 +64,16 @@ impl HitShape { HitShape::Segment { a, b } } - /// A chain of segments, closed when `closed`. + /// A chain of segments, closed when `closed`, hit within [`LINE_REACH`]. pub fn polyline(points: Vec, closed: bool) -> Self { - HitShape::Polyline { points, closed } + HitShape::Polyline { points, closed, reach: LINE_REACH } + } + + /// A chain of segments, closed when `closed`, hit within `reach` points: a tool whose measured reach differs from + /// a line's. A negative or non-finite `reach` is [`LINE_REACH`]. + pub fn polyline_within(points: Vec, closed: bool, reach: f32) -> Self { + let reach = if reach.is_finite() && reach >= 0.0 { reach } else { LINE_REACH }; + HitShape::Polyline { points, closed, reach } } /// The part of `within` outside `polygon`. @@ -95,7 +104,8 @@ impl HitShape { } HitShape::Circle { center, radius } => center.distance(point) <= radius.max(across / 2.0), HitShape::Segment { a, b } => segment_distance(point, *a, *b) <= reach, - HitShape::Polyline { points, closed } => { + HitShape::Polyline { points, closed, reach: own } => { + let reach = own.max(across / 2.0); let closing = closed.then(|| points.first().zip(points.last())).flatten(); points.windows(2).any(|pair| segment_distance(point, pair[0], pair[1]) <= reach) || closing.is_some_and(|(first, last)| segment_distance(point, *last, *first) <= reach) @@ -116,10 +126,10 @@ impl HitShape { HitShape::Rect(rect) => rect.contains(point), HitShape::Circle { center, radius } => center.distance(point) <= *radius, HitShape::Segment { a, b } => segment_distance(point, *a, *b) <= LINE_REACH, - HitShape::Polyline { points, closed } => { + HitShape::Polyline { points, closed, reach } => { let closing = closed.then(|| points.first().zip(points.last())).flatten(); - points.windows(2).any(|pair| segment_distance(point, pair[0], pair[1]) <= LINE_REACH) - || closing.is_some_and(|(first, last)| segment_distance(point, *last, *first) <= LINE_REACH) + points.windows(2).any(|pair| segment_distance(point, pair[0], pair[1]) <= *reach) + || closing.is_some_and(|(first, last)| segment_distance(point, *last, *first) <= *reach) } HitShape::Polygon(points) => inside_polygon(point, points), HitShape::OutsidePolygon { within, polygon } => within.contains(point) && !inside_polygon(point, polygon), @@ -330,4 +340,18 @@ mod tests { let tie = [shape(big(), Sense::CLICK, 1, 0, HitLevel::Body, 0), shape(big(), Sense::CLICK, 2, 0, HitLevel::Body, 0)]; assert_eq!(owner(&tie), Some(2)); } + + #[test] + fn a_polyline_hits_within_its_own_reach_and_a_bad_reach_is_a_lines() { + let points = vec![pos2(0.0, 0.0), pos2(100.0, 0.0)]; + let line = HitShape::polyline(points.clone(), false); + assert!(line.hit(pos2(50.0, LINE_REACH)) && !line.hit(pos2(50.0, LINE_REACH + 0.5))); + let wide = HitShape::polyline_within(points.clone(), false, 5.0); + assert!(wide.hit(pos2(50.0, 5.0)) && wide.hit(pos2(50.0, -5.0)) && !wide.hit(pos2(50.0, 5.5))); + let hits = |shape: HitShape, y: f32| Shape::new(shape, Sense::CLICK, 0_u8, None, HitPriority::BODY, 0).min_across(8.0).hits(pos2(50.0, y)); + assert!(hits(wide.clone(), 5.0) && !hits(wide, 5.5), "a target size under twice the reach keeps the reach"); + for bad in [f32::NAN, f32::INFINITY, -1.0] { + assert_eq!(HitShape::polyline_within(points.clone(), false, bad), line); + } + } } diff --git a/crates/behavior/src/keys.rs b/crates/behavior/src/keys.rs index 5c8bf19da..a24e52bf5 100644 --- a/crates/behavior/src/keys.rs +++ b/crates/behavior/src/keys.rs @@ -8,7 +8,7 @@ use craft_host::target::Os; use craft_keymap::{Chord, Key, Mods}; /// What the focused stop is, as far as the table's rows differ. -#[derive(Clone, Copy, Debug, Default)] +#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)] #[non_exhaustive] pub struct KeyRole { /// A value control with a reset value and no text part: Delete resets it. diff --git a/crates/behavior/src/press.rs b/crates/behavior/src/press.rs index ccd3b1694..ba4a4d7f3 100644 --- a/crates/behavior/src/press.rs +++ b/crates/behavior/src/press.rs @@ -471,6 +471,11 @@ struct Open { dragging: bool, /// Moved past slop on a target that senses no drag: the click is gone and nothing starts. abandoned: bool, + /// The pointer left the window ([`PointerEvent::Gone`]): the click is gone, but a target that senses a drag still + /// starts it from the moves that follow. The button is still down and the window keeps getting the pointer's moves + /// and release while it is outside, so a press near a window edge (a window's resize grip) that leaves the window + /// before it passes slop still drags. + left: bool, /// A pass reported the press: later passes within slop report `Held`, not `Down`. reported: bool, /// A pass reported the drag's start: later passes report `Drag`. @@ -489,7 +494,7 @@ impl Open { /// A release now is a click. fn clicks(&self) -> bool { - !self.dragging && !self.abandoned && self.sense.contains(Sense::CLICK) + !self.dragging && !self.abandoned && !self.left && self.sense.contains(Sense::CLICK) } } @@ -568,7 +573,7 @@ impl PressMachine { } PointerEvent::Gone => { if let Some(open) = &mut self.open { - open.abandoned = true; + open.left = true; } } PointerEvent::Pressed { button, pos: at, time, clicks } => { @@ -607,6 +612,7 @@ impl PressMachine { start: PressStart::new(at, button, time, clicks), dragging: false, abandoned: false, + left: false, reported: false, drag_reported: false, released_at: None, @@ -739,6 +745,25 @@ mod tests { assert!(machine.target().is_none(), "the release ends the press"); } + /// The pointer leaving the window (a press on a window's edge grip pulled outward) ends the press's click but not + /// its drag: the window keeps getting the held button's moves from outside, and they start the drag once past slop. + /// The resize from a window edge used to fail whenever the pointer left the window before it passed slop. + #[test] + fn a_press_whose_pointer_left_the_window_still_drags_but_no_longer_clicks() { + let moved = |x: f32| PointerEvent::Moved { at: pos2(x, 0.0), sample: None }; + let up = |x: f32| PointerEvent::released(pos2(x, 0.0)); + let gone = PointerEvent::Gone; + let out = [moved(SLOP / 2.0), gone]; + assert_eq!(phases(&[&[press(0.0, 1.0)], &out, &[moved(SLOP * 2.0)], &[moved(SLOP * 3.0)], &[up(SLOP * 3.0)]], Sense::DRAG), "D H S G R"); + assert_eq!(phases(&[&[press(0.0, 1.0)], &out, &[up(SLOP / 2.0)]], Sense::CLICK), "D H R", "a click target loses its click"); + assert_eq!( + phases(&[&[press(0.0, 1.0)], &out, &[moved(0.0)], &[up(0.0)]], Sense::CLICK | Sense::DRAG), + "D H H R", + "coming back does not bring the click back" + ); + assert_eq!(phases(&[&[press(0.0, 1.0)], &[moved(0.0)], &[up(0.0)]], Sense::CLICK), "D H R!", "a press that stays in still clicks"); + } + #[test] fn held_reports_the_pointer_of_its_pass_within_slop() { let mut machine = PressMachine::new(); diff --git a/crates/behavior/tests/dock_apply.rs b/crates/behavior/tests/dock_apply.rs index 3ed8fc9c9..59d764ad3 100644 --- a/crates/behavior/tests/dock_apply.rs +++ b/crates/behavior/tests/dock_apply.rs @@ -355,6 +355,51 @@ fn a_panel_that_shares_no_column_moves_only_to_a_column_of_its_own() { assert_eq!(sorted(&saved.layout), [1, 2, 3, 4, 6]); } +/// A panel that docks only in dock columns (a toolbar, photocraft#12517) refuses every placement that leaves it in a +/// frame of the docked tree: a split beside the canvas on any side and an edge of the docked area, so it never lies +/// across the window. A new dock, a column beside another and a float still take it, other panels still move while +/// one sits in a frame (only a new breach is refused), and reconcile moves a saved one into a dock column. +#[test] +fn a_panel_that_docks_only_in_columns_never_lands_in_a_frame() { + let strip = |p: &u32| match p { + 2 => Permissions::ALL.shares_column(false).docks_outside_columns(false), + 1 => Permissions::PROTECTED.accepts_splits(true), + _ => Permissions::ALL, + }; + let layout = columns(); + let sides = [DockSide::Top, DockSide::Bottom, DockSide::Start, DockSide::End]; + let framed = sides.iter().map(|side| DockPlacement::Split(*side)).chain(sides.iter().map(|side| DockPlacement::Edge(*side))); + for placement in framed { + let mut moved = layout.clone(); + let action = Action::move_column(2, Target::at(1, placement.clone())); + assert_eq!(moved.apply_with_permissions(action, strip), Err(DockError::NotAllowed), "{placement:?}"); + assert_eq!(moved, layout, "{placement:?}"); + } + for to in [Target::new_dock(DockEdge::Start), Target::at(3, DockPlacement::column(true)), Target::float(window())] { + let mut moved = layout.clone(); + moved.apply_with_permissions(Action::move_column(2, to.clone()), strip).unwrap_or_else(|e| panic!("{to:?}: {e}")); + assert!(!matches!(moved.place(&2), Some(PanelPlace::Node(_))), "{to:?}"); + } + // Without the right the same split takes it, so the refusal above is this right's. + let mut split = layout.clone(); + split + .apply_with_permissions(Action::move_column(2, Target::at(1, DockPlacement::Split(DockSide::Bottom))), |p: &u32| match p { + 2 => Permissions::ALL.shares_column(false), + _ => Permissions::ALL, + }) + .unwrap(); + assert!(matches!(split.place(&2), Some(PanelPlace::Node(_)))); + + // A layout saved with the panel in a frame: other panels still move, and reconcile docks it in a column. + let mut other = split.clone(); + other.apply_with_permissions(Action::move_group(6, Target::at(3, DockPlacement::column(false))), strip).unwrap(); + let mut saved = Workspace::new(split); + saved.reconcile(|_| true, strip, &Workspace::new(columns())); + assert!(matches!(saved.layout.place(&2), Some(PanelPlace::Dock { .. })), "reconcile docks it in a column: {:?}", saved.layout); + assert_eq!(column_of(&saved.layout, 2).panels().collect::>(), [&2]); + assert_eq!(sorted(&saved.layout), [1, 2, 3, 4, 6]); +} + /// A stepped column (a toolbar's) keeps its step count docked, floating and through JSON, and its width moves only /// by steps. #[test] diff --git a/crates/browse/src/links/tests.rs b/crates/browse/src/links/tests.rs index d667d0ec6..fa5cb12cb 100644 --- a/crates/browse/src/links/tests.rs +++ b/crates/browse/src/links/tests.rs @@ -49,18 +49,21 @@ fn monitor(files: &Arc, jobs: &Arc) -> LinkMonitor { LinkMonitor::new(files.clone(), jobs.clone(), Wake::none()) } +/// Absolute on every platform: a link path that is not is refused as invalid. +const FILE: &str = if cfg!(windows) { r"C:\p\a.png" } else { "/p/a.png" }; + // A file changes once: one LinkChange Ok -> Modified, and nothing on the following passes. #[trial] fn the_monitor_reports_a_change_once() { - let files = Disk::new(FakeLinkFiles::new().with("/p/a.png", b"abc", 1)); - let a = link(1, "/p/a.png", files.identity_of("/p/a.png")); + let files = Disk::new(FakeLinkFiles::new().with(FILE, b"abc", 1)); + let a = link(1, FILE, files.identity_of(FILE)); let jobs = Arc::new(ManualJobs::new()); let mut m = monitor(&files, &jobs); m.set(&[a], None); jobs.run_all(); assert_eq!(m.take_changes(), vec![LinkChange { key: 1, before: None, status: LinkStatus::Ok }]); - files.change(FakeLinkFiles::new().with("/p/a.png", b"abcd", 2)); + files.change(FakeLinkFiles::new().with(FILE, b"abcd", 2)); m.window_focused(); jobs.run_all(); assert_eq!(m.take_changes(), vec![LinkChange { key: 1, before: Some(LinkStatus::Ok), status: LinkStatus::Modified }]); @@ -77,10 +80,10 @@ fn the_monitor_reports_a_change_once() { // A check that finished before the link was updated is stale when it is taken in: it reports nothing, and the newer check decides. #[trial] fn a_check_older_than_known_now_is_dropped() { - let files = Disk::new(FakeLinkFiles::new().with("/p/a.png", b"abc", 1)); - let old = link(1, "/p/a.png", files.identity_of("/p/a.png")); - files.change(FakeLinkFiles::new().with("/p/a.png", b"abcd", 2)); - let updated = link(1, "/p/a.png", files.identity_of("/p/a.png")); + let files = Disk::new(FakeLinkFiles::new().with(FILE, b"abc", 1)); + let old = link(1, FILE, files.identity_of(FILE)); + files.change(FakeLinkFiles::new().with(FILE, b"abcd", 2)); + let updated = link(1, FILE, files.identity_of(FILE)); let jobs = Arc::new(ManualJobs::new()); let mut m = monitor(&files, &jobs); m.set(&[old], None); diff --git a/crates/browse/src/ui/relink/badge.rs b/crates/browse/src/ui/relink/badge.rs index 8451a06ea..b1981a39d 100644 --- a/crates/browse/src/ui/relink/badge.rs +++ b/crates/browse/src/ui/relink/badge.rs @@ -34,10 +34,10 @@ enum StatusGlyph { Modified, } -static MISSING: StatusGlyph = StatusGlyph::Missing; -static UNREADABLE: StatusGlyph = StatusGlyph::Unreadable; -static REFUSED: StatusGlyph = StatusGlyph::Refused; -static MODIFIED: StatusGlyph = StatusGlyph::Modified; +const MISSING: StatusGlyph = StatusGlyph::Missing; +const UNREADABLE: StatusGlyph = StatusGlyph::Unreadable; +const REFUSED: StatusGlyph = StatusGlyph::Refused; +const MODIFIED: StatusGlyph = StatusGlyph::Modified; impl Glyph for StatusGlyph { fn paint(&self, painter: &Painter, tokens: &UiTokens, rect: Rect, _: Color32, _: bool) { diff --git a/crates/browse/tests/it/relink.rs b/crates/browse/tests/it/relink.rs index 4de218139..275dc78d0 100644 --- a/crates/browse/tests/it/relink.rs +++ b/crates/browse/tests/it/relink.rs @@ -101,11 +101,15 @@ fn linked_keys(result: &DialogResult>) -> (Vec, Vec (outcome.linked.iter().map(|(key, _)| *key).collect(), outcome.offline.clone()) } +/// A folder path is absolute only with a drive on Windows. +const DRIVE: &str = if cfg!(windows) { "D:" } else { "" }; + #[trial] fn relink_others_offers_the_rows_the_remap_fits() { - let files = files(&[("/T7/shoot/a.mov", SAME), ("/T7/shoot/b.mov", SAME), ("/T7/shoot/c.mov", OTHER)]); + let files = + files(&[(&format!("{DRIVE}/T7/shoot/a.mov"), SAME), (&format!("{DRIVE}/T7/shoot/b.mov"), SAME), (&format!("{DRIVE}/T7/shoot/c.mov"), OTHER)]); let rows = vec![row(1, "Clip A", "C:\\shoot\\a.mov"), row(2, "Clip B", "C:\\shoot\\b.mov"), row(3, "Clip C", "C:\\shoot\\c.mov")]; - let mut rig = rig(rows, &files, "/T7/shoot", true, true); + let mut rig = rig(rows, &files, &format!("{DRIVE}/T7/shoot"), true, true); rig.search(); rig.click("Link"); rig.jobs.run_all(); diff --git a/crates/captions/Cargo.toml b/crates/captions/Cargo.toml index cd09f7e16..1136f55f9 100644 --- a/crates/captions/Cargo.toml +++ b/crates/captions/Cargo.toml @@ -10,6 +10,11 @@ repository.workspace = true [lints] workspace = true +[features] +default = [] +# MP4 timed text (3GPP TS 26.245 / mov_text / tx3g) sample codec. +mov-text = [] + [dependencies] craft-timeline = { workspace = true } craft-xml = { workspace = true } @@ -21,3 +26,5 @@ proptest = { workspace = true } roxmltree = "0.21" # ffmpeg as the reference for the ASS tests (tests/it/ass.rs). craft-media-testkit = { workspace = true } +# craft-media isobmff for mov_text oracle demuxing/muxing tests. +craft-media = { workspace = true, features = ["isobmff"] } diff --git a/crates/captions/README.md b/crates/captions/README.md index 7380a3ce4..b2f6a195f 100644 --- a/crates/captions/README.md +++ b/crates/captions/README.md @@ -27,6 +27,10 @@ assert!(scc.starts_with(b"Scenarist_SCC V1.0")); and the SMPTE ST 334-2 caption distribution packet. - `plain_text` strips inline tags and decodes the common entities, for display or for formats without markup. +- Optional feature `mov-text` provides MP4 Timed Text (`mov_text` / `tx3g`, 3GPP TS 26.245) + sample decoding, encoding, modifier box parsing (`styl`, `hlit`, `hclr`, `krok`, `dlay`, `href`, + `tbox`, `blnk`, `wrap`), and `Tx3gConfig` sample entry parsing/writing for ISO BMFF (`.mp4`) and + QuickTime (`.mov`) subtitle tracks. ## Time diff --git a/crates/captions/src/lib.rs b/crates/captions/src/lib.rs index 9d085854d..612aa6f13 100644 --- a/crates/captions/src/lib.rs +++ b/crates/captions/src/lib.rs @@ -36,6 +36,8 @@ pub mod ass; pub mod cea608; pub mod jacosub; pub mod mcc; +#[cfg(feature = "mov-text")] +pub mod mov_text; pub mod pjs; pub mod realtext; pub mod scc; diff --git a/crates/captions/src/mov_text.rs b/crates/captions/src/mov_text.rs new file mode 100644 index 000000000..d1a3ce2a9 --- /dev/null +++ b/crates/captions/src/mov_text.rs @@ -0,0 +1,871 @@ +//! MP4 Timed Text (`mov_text` / `tx3g`, 3GPP TS 26.245). +//! +//! A clean-room reader and writer for 3GPP Timed Text subtitle samples and sample entry +//! configurations (`tx3g`), as carried in ISO BMFF (`.mp4`) and QuickTime (`.mov`) files. +//! +//! ## Sample Structure +//! +//! A timed text sample consists of: +//! - A 16-bit big-endian text length. +//! - The text string bytes (UTF-8, or UTF-16 with BOM). +//! - Zero or more modifier boxes: +//! - `styl`: Character style runs (bold, italic, underline, font ID, font size, text color). +//! - `hlit`: Highlighted character range. +//! - `hclr`: Highlight color (RGBA). +//! - `krok`: Karaoke highlight timing and character spans. +//! - `dlay`: Scroll delay in track-timescale ticks. +//! - `href`: Hypertext link URL and alt text. +//! - `tbox`: Text box override coordinates (`top, left, bottom, right`). +//! - `blnk`: Blinking text character range. +//! - `twrp`: Text wrap flag (0 = no wrap, 1 = automatic soft wrap). +//! +//! ## Style Flags +//! +//! Style flags in `styl` records: +//! - `0x01`: Bold (`...`) +//! - `0x02`: Italic (`...`) +//! - `0x04`: Underline (`...`) + +use crate::time::Tick; +use crate::{Cue, Document, TICKS_PER_SECOND}; + +/// What went wrong reading or writing timed text. +#[non_exhaustive] +#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)] +pub enum Error { + /// The input slice is shorter than the declared field or box size. + #[error("truncated timed text data")] + Truncated, + /// The text payload is not valid UTF-8 and contains no valid UTF-16 BOM. + #[error("invalid text encoding in timed text sample")] + InvalidText, + /// The text exceeds the 16-bit length prefix (65,535 bytes). + #[error("timed text string exceeds 65535 bytes: {0}")] + TextTooLong(usize), + /// A modifier box header has an invalid size (< 8). + #[error("invalid modifier box size: {0}")] + InvalidBox(&'static str), +} + +/// `Result` alias for timed text operations. +pub type Result = std::result::Result; + +/// Face style flag: Bold (`0x01`). +pub const STYLE_FLAG_BOLD: u8 = 0x01; +/// Face style flag: Italic (`0x02`). +pub const STYLE_FLAG_ITALIC: u8 = 0x02; +/// Face style flag: Underline (`0x04`). +pub const STYLE_FLAG_UNDERLINE: u8 = 0x04; + +/// A character styling record within a `styl` box. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub struct StyleRecord { + /// 0-indexed start character index (inclusive, measured in Unicode scalar values). + pub start_char: u16, + /// 0-indexed end character index (exclusive, measured in Unicode scalar values). + pub end_char: u16, + /// 16-bit font ID matching an entry in the sample description font table (`ftab`). + pub font_id: u16, + /// Face style flags: bit 0 = bold, bit 1 = italic, bit 2 = underline. + pub face_style_flags: u8, + /// Font size in points. + pub font_size: u8, + /// Text RGBA color (`[r, g, b, a]`). + pub text_color_rgba: [u8; 4], +} + +impl Default for StyleRecord { + fn default() -> Self { + Self { start_char: 0, end_char: 0, font_id: 1, face_style_flags: 0, font_size: 16, text_color_rgba: [255, 255, 255, 255] } + } +} + +impl StyleRecord { + /// Returns `true` if bold is set. + pub fn is_bold(&self) -> bool { + self.face_style_flags & STYLE_FLAG_BOLD != 0 + } + + /// Returns `true` if italic is set. + pub fn is_italic(&self) -> bool { + self.face_style_flags & STYLE_FLAG_ITALIC != 0 + } + + /// Returns `true` if underline is set. + pub fn is_underline(&self) -> bool { + self.face_style_flags & STYLE_FLAG_UNDERLINE != 0 + } +} + +/// Coordinates of a text display box (`tbox`). +#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)] +pub struct TextBox { + pub top: i16, + pub left: i16, + pub bottom: i16, + pub right: i16, +} + +/// An entry in a karaoke box (`krok`). +#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)] +pub struct KaraokeEntry { + /// Highlight end time in timescale ticks. + pub highlight_end_time: u32, + /// Start character index (inclusive). + pub start_char: u16, + /// End character index (exclusive). + pub end_char: u16, +} + +/// A hypertext link entry (`href`). +#[derive(Clone, Debug, Default, PartialEq, Eq)] +pub struct HyperText { + /// Start character index (inclusive). + pub start_char: u16, + /// End character index (exclusive). + pub end_char: u16, + /// Destination URL. + pub url: String, + /// Accessible alt text string. + pub alt_string: String, +} + +/// An unpacked 3GPP Timed Text (`tx3g` / `mov_text`) sample. +#[derive(Clone, Debug, Default, PartialEq, Eq)] +pub struct TextSample { + /// Decoded UTF-8 text content. + pub text: String, + /// Character styling records from the `styl` box. + pub styles: Vec, + /// Highlighted character range `(start_char, end_char)` from `hlit`. + pub highlight: Option<(u16, u16)>, + /// Highlight color `[r, g, b, a]` from `hclr`. + pub highlight_color: Option<[u8; 4]>, + /// Karaoke timing and spans `(highlight_start_time, entries)` from `krok`. + pub karaoke: Option<(u32, Vec)>, + /// Scroll delay in milliseconds from `dlay`. + pub scroll_delay: Option, + /// Hypertext links from `href` boxes. + pub hypertext: Vec, + /// Text box override from `tbox`. + pub text_box: Option, + /// Blinking character ranges `(start_char, end_char)` from `blnk` boxes. + pub blinking: Vec<(u16, u16)>, + /// Wrap flag from `wrap` box: `0` = automatic wrap, `1` = no wrap. + pub wrap_flag: Option, +} + +/// Sample description table configuration for a `tx3g` track. +#[derive(Clone, Debug, PartialEq, Eq)] +pub struct Tx3gConfig { + /// 32-bit display flags (e.g. scroll in, scroll out, continuous scroll). + pub display_flags: u32, + /// Horizontal justification: 0 = left, 1 = center, -1 = right. + pub horizontal_justification: i8, + /// Vertical justification: 0 = top, 1 = center, -1 = bottom. + pub vertical_justification: i8, + /// Background RGBA color. + pub background_color: [u8; 4], + /// Default text box coordinates. + pub default_text_box: TextBox, + /// Default style record. + pub default_style: StyleRecord, + /// Font table entries `(font_id, font_name)`. + pub fonts: Vec<(u16, String)>, +} + +impl Default for Tx3gConfig { + fn default() -> Self { + Self { + display_flags: 0, + horizontal_justification: 1, // center + vertical_justification: -1, // bottom + background_color: [0, 0, 0, 255], + default_text_box: TextBox::default(), + default_style: StyleRecord::default(), + fonts: vec![(1, "Arial".to_string())], + } + } +} + +impl Tx3gConfig { + /// Parse a `tx3g` sample entry payload (after the standard 8-byte sample entry header). + pub fn parse(payload: &[u8]) -> Result { + if payload.len() < 30 { + return Err(Error::Truncated); + } + let display_flags = u32::from_be_bytes([payload[0], payload[1], payload[2], payload[3]]); + let horizontal_justification = payload[4] as i8; + let vertical_justification = payload[5] as i8; + let background_color = [payload[6], payload[7], payload[8], payload[9]]; + + let default_text_box = TextBox { + top: i16::from_be_bytes([payload[10], payload[11]]), + left: i16::from_be_bytes([payload[12], payload[13]]), + bottom: i16::from_be_bytes([payload[14], payload[15]]), + right: i16::from_be_bytes([payload[16], payload[17]]), + }; + + let default_style = StyleRecord { + start_char: u16::from_be_bytes([payload[18], payload[19]]), + end_char: u16::from_be_bytes([payload[20], payload[21]]), + font_id: u16::from_be_bytes([payload[22], payload[23]]), + face_style_flags: payload[24], + font_size: payload[25], + text_color_rgba: [payload[26], payload[27], payload[28], payload[29]], + }; + + let mut fonts = Vec::new(); + let mut pos = 30; + while pos + 8 <= payload.len() { + let box_size = u32::from_be_bytes([payload[pos], payload[pos + 1], payload[pos + 2], payload[pos + 3]]) as usize; + if box_size < 8 || pos.checked_add(box_size).is_none_or(|end| end > payload.len()) { + break; + } + let box_type = &payload[pos + 4..pos + 8]; + if box_type == b"ftab" && box_size >= 10 { + let count = u16::from_be_bytes([payload[pos + 8], payload[pos + 9]]) as usize; + let mut fpos = pos + 10; + for _ in 0..count { + if fpos + 3 > pos + box_size { + break; + } + let font_id = u16::from_be_bytes([payload[fpos], payload[fpos + 1]]); + let name_len = payload[fpos + 2] as usize; + fpos += 3; + if fpos + name_len > pos + box_size { + break; + } + if let Ok(name) = std::str::from_utf8(&payload[fpos..fpos + name_len]) { + fonts.push((font_id, name.to_string())); + } + fpos += name_len; + } + } + pos += box_size; + } + + Ok(Self { display_flags, horizontal_justification, vertical_justification, background_color, default_text_box, default_style, fonts }) + } + + /// Write the `tx3g` sample entry payload (after the 8-byte sample entry header). + pub fn write(&self) -> Vec { + let mut out = Vec::with_capacity(30 + 32); + out.extend_from_slice(&self.display_flags.to_be_bytes()); + out.push(self.horizontal_justification as u8); + out.push(self.vertical_justification as u8); + out.extend_from_slice(&self.background_color); + + out.extend_from_slice(&self.default_text_box.top.to_be_bytes()); + out.extend_from_slice(&self.default_text_box.left.to_be_bytes()); + out.extend_from_slice(&self.default_text_box.bottom.to_be_bytes()); + out.extend_from_slice(&self.default_text_box.right.to_be_bytes()); + + out.extend_from_slice(&self.default_style.start_char.to_be_bytes()); + out.extend_from_slice(&self.default_style.end_char.to_be_bytes()); + out.extend_from_slice(&self.default_style.font_id.to_be_bytes()); + out.push(self.default_style.face_style_flags); + out.push(self.default_style.font_size); + out.extend_from_slice(&self.default_style.text_color_rgba); + + // ftab box + let mut ftab_payload = Vec::new(); + let fonts = &self.fonts[..self.fonts.len().min(u16::MAX as usize)]; + ftab_payload.extend_from_slice(&(fonts.len() as u16).to_be_bytes()); + for (id, name) in fonts { + ftab_payload.extend_from_slice(&id.to_be_bytes()); + let name_bytes = name.as_bytes(); + let limit = name.floor_char_boundary(name_bytes.len().min(255)); + ftab_payload.push(limit as u8); + ftab_payload.extend_from_slice(&name_bytes[..limit]); + } + let ftab_size = 8u32.saturating_add(ftab_payload.len() as u32); + out.extend_from_slice(&ftab_size.to_be_bytes()); + out.extend_from_slice(b"ftab"); + out.extend_from_slice(&ftab_payload); + + out + } +} + +/// Read and decode a single 3GPP Timed Text sample (`tx3g` / `mov_text`). +pub fn read_sample(data: &[u8]) -> Result { + if data.len() < 2 { + return Err(Error::Truncated); + } + + let text_len = u16::from_be_bytes([data[0], data[1]]) as usize; + if data.len() < 2 + text_len { + return Err(Error::Truncated); + } + + let text_bytes = &data[2..2 + text_len]; + let text = decode_text(text_bytes)?; + + let mut sample = TextSample { text, ..Default::default() }; + + let mut pos = 2 + text_len; + while pos + 8 <= data.len() { + let size = u32::from_be_bytes([data[pos], data[pos + 1], data[pos + 2], data[pos + 3]]) as usize; + if size < 8 { + return Err(Error::InvalidBox("size smaller than 8")); + } + let box_end = pos.checked_add(size).ok_or(Error::Truncated)?; + if box_end > data.len() { + return Err(Error::Truncated); + } + + let box_type = &data[pos + 4..pos + 8]; + let payload = &data[pos + 8..box_end]; + + match box_type { + b"styl" => { + if payload.len() < 2 { + return Err(Error::Truncated); + } + let count = u16::from_be_bytes([payload[0], payload[1]]) as usize; + let mut spos = 2; + for _ in 0..count { + if spos + 12 > payload.len() { + return Err(Error::Truncated); + } + sample.styles.push(StyleRecord { + start_char: u16::from_be_bytes([payload[spos], payload[spos + 1]]), + end_char: u16::from_be_bytes([payload[spos + 2], payload[spos + 3]]), + font_id: u16::from_be_bytes([payload[spos + 4], payload[spos + 5]]), + face_style_flags: payload[spos + 6], + font_size: payload[spos + 7], + text_color_rgba: [payload[spos + 8], payload[spos + 9], payload[spos + 10], payload[spos + 11]], + }); + spos += 12; + } + } + b"hlit" => { + if payload.len() < 4 { + return Err(Error::Truncated); + } + let start = u16::from_be_bytes([payload[0], payload[1]]); + let end = u16::from_be_bytes([payload[2], payload[3]]); + sample.highlight = Some((start, end)); + } + b"hclr" => { + if payload.len() < 4 { + return Err(Error::Truncated); + } + sample.highlight_color = Some([payload[0], payload[1], payload[2], payload[3]]); + } + b"krok" => { + if payload.len() < 6 { + return Err(Error::Truncated); + } + let start_time = u32::from_be_bytes([payload[0], payload[1], payload[2], payload[3]]); + let count = u16::from_be_bytes([payload[4], payload[5]]) as usize; + let mut entries = Vec::new(); + let mut kpos = 6; + for _ in 0..count { + if kpos + 8 > payload.len() { + return Err(Error::Truncated); + } + entries.push(KaraokeEntry { + highlight_end_time: u32::from_be_bytes([payload[kpos], payload[kpos + 1], payload[kpos + 2], payload[kpos + 3]]), + start_char: u16::from_be_bytes([payload[kpos + 4], payload[kpos + 5]]), + end_char: u16::from_be_bytes([payload[kpos + 6], payload[kpos + 7]]), + }); + kpos += 8; + } + sample.karaoke = Some((start_time, entries)); + } + b"dlay" => { + if payload.len() < 4 { + return Err(Error::Truncated); + } + sample.scroll_delay = Some(u32::from_be_bytes([payload[0], payload[1], payload[2], payload[3]])); + } + b"href" => { + if payload.len() < 6 { + return Err(Error::Truncated); + } + let start = u16::from_be_bytes([payload[0], payload[1]]); + let end = u16::from_be_bytes([payload[2], payload[3]]); + let url_len = payload[4] as usize; + if 5 + url_len > payload.len() { + return Err(Error::Truncated); + } + let url = std::str::from_utf8(&payload[5..5 + url_len]).map_err(|_| Error::InvalidText)?.to_string(); + let alt_pos = 5 + url_len; + let alt_len = payload.get(alt_pos).copied().unwrap_or(0) as usize; + let alt_string = if alt_len > 0 && alt_pos + 1 + alt_len <= payload.len() { + std::str::from_utf8(&payload[alt_pos + 1..alt_pos + 1 + alt_len]).map_err(|_| Error::InvalidText)?.to_string() + } else { + String::new() + }; + sample.hypertext.push(HyperText { start_char: start, end_char: end, url, alt_string }); + } + b"tbox" => { + if payload.len() < 8 { + return Err(Error::Truncated); + } + sample.text_box = Some(TextBox { + top: i16::from_be_bytes([payload[0], payload[1]]), + left: i16::from_be_bytes([payload[2], payload[3]]), + bottom: i16::from_be_bytes([payload[4], payload[5]]), + right: i16::from_be_bytes([payload[6], payload[7]]), + }); + } + b"blnk" => { + if payload.len() < 4 { + return Err(Error::Truncated); + } + let start = u16::from_be_bytes([payload[0], payload[1]]); + let end = u16::from_be_bytes([payload[2], payload[3]]); + sample.blinking.push((start, end)); + } + b"twrp" | b"wrap" => { + if payload.is_empty() { + return Err(Error::Truncated); + } + sample.wrap_flag = Some(payload[0]); + } + _ => { + // Unknown modifier box: safely ignored. + } + } + + pos = box_end; + } + + Ok(sample) +} + +/// Helper to decode UTF-8 or UTF-16 with BOM. +fn decode_text(bytes: &[u8]) -> Result { + if bytes.len() >= 2 { + if bytes[0] == 0xFE && bytes[1] == 0xFF { + // UTF-16 BE + let u16s: Vec = bytes[2..].as_chunks::<2>().0.iter().map(|c| u16::from_be_bytes([c[0], c[1]])).collect(); + return String::from_utf16(&u16s).map_err(|_| Error::InvalidText); + } else if bytes[0] == 0xFF && bytes[1] == 0xFE { + // UTF-16 LE + let u16s: Vec = bytes[2..].as_chunks::<2>().0.iter().map(|c| u16::from_le_bytes([c[0], c[1]])).collect(); + return String::from_utf16(&u16s).map_err(|_| Error::InvalidText); + } + } + std::str::from_utf8(bytes).map(ToString::to_string).map_err(|_| Error::InvalidText) +} + +/// Pack and encode a timed text sample into bytes. +pub fn write_sample(sample: &TextSample) -> Result> { + let text_bytes = sample.text.as_bytes(); + if text_bytes.len() > u16::MAX as usize { + return Err(Error::TextTooLong(text_bytes.len())); + } + + let mut out = Vec::with_capacity(2 + text_bytes.len() + 64); + out.extend_from_slice(&(text_bytes.len() as u16).to_be_bytes()); + out.extend_from_slice(text_bytes); + + // 1. styl box + if !sample.styles.is_empty() { + if sample.styles.len() > u16::MAX as usize { + return Err(Error::InvalidBox("too many styles in sample")); + } + let size = 8u32.checked_add(2).and_then(|s| s.checked_add(sample.styles.len() as u32 * 12)).ok_or(Error::InvalidBox("styl size overflow"))?; + out.extend_from_slice(&size.to_be_bytes()); + out.extend_from_slice(b"styl"); + out.extend_from_slice(&(sample.styles.len() as u16).to_be_bytes()); + for st in &sample.styles { + out.extend_from_slice(&st.start_char.to_be_bytes()); + out.extend_from_slice(&st.end_char.to_be_bytes()); + out.extend_from_slice(&st.font_id.to_be_bytes()); + out.push(st.face_style_flags); + out.push(st.font_size); + out.extend_from_slice(&st.text_color_rgba); + } + } + + // 2. hlit box + if let Some((start, end)) = sample.highlight { + out.extend_from_slice(&12u32.to_be_bytes()); + out.extend_from_slice(b"hlit"); + out.extend_from_slice(&start.to_be_bytes()); + out.extend_from_slice(&end.to_be_bytes()); + } + + // 3. hclr box + if let Some(color) = sample.highlight_color { + out.extend_from_slice(&12u32.to_be_bytes()); + out.extend_from_slice(b"hclr"); + out.extend_from_slice(&color); + } + + // 4. krok box + if let Some((start_time, ref entries)) = sample.karaoke { + if entries.len() > u16::MAX as usize { + return Err(Error::InvalidBox("too many karaoke entries")); + } + let size = 8u32.checked_add(6).and_then(|s| s.checked_add(entries.len() as u32 * 8)).ok_or(Error::InvalidBox("krok size overflow"))?; + out.extend_from_slice(&size.to_be_bytes()); + out.extend_from_slice(b"krok"); + out.extend_from_slice(&start_time.to_be_bytes()); + out.extend_from_slice(&(entries.len() as u16).to_be_bytes()); + for e in entries { + out.extend_from_slice(&e.highlight_end_time.to_be_bytes()); + out.extend_from_slice(&e.start_char.to_be_bytes()); + out.extend_from_slice(&e.end_char.to_be_bytes()); + } + } + + // 5. dlay box + if let Some(delay) = sample.scroll_delay { + out.extend_from_slice(&12u32.to_be_bytes()); + out.extend_from_slice(b"dlay"); + out.extend_from_slice(&delay.to_be_bytes()); + } + + // 6. href boxes + for link in &sample.hypertext { + let url_bytes = link.url.as_bytes(); + let alt_bytes = link.alt_string.as_bytes(); + let ulen = url_bytes.len().min(255) as u8; + let alen = alt_bytes.len().min(255) as u8; + let size = 8u32 + 4 + 1 + ulen as u32 + 1 + alen as u32; + out.extend_from_slice(&size.to_be_bytes()); + out.extend_from_slice(b"href"); + out.extend_from_slice(&link.start_char.to_be_bytes()); + out.extend_from_slice(&link.end_char.to_be_bytes()); + out.push(ulen); + out.extend_from_slice(&url_bytes[..ulen as usize]); + out.push(alen); + out.extend_from_slice(&alt_bytes[..alen as usize]); + } + + // 7. tbox box + if let Some(tb) = sample.text_box { + out.extend_from_slice(&16u32.to_be_bytes()); + out.extend_from_slice(b"tbox"); + out.extend_from_slice(&tb.top.to_be_bytes()); + out.extend_from_slice(&tb.left.to_be_bytes()); + out.extend_from_slice(&tb.bottom.to_be_bytes()); + out.extend_from_slice(&tb.right.to_be_bytes()); + } + + // 8. blnk boxes + for &(start, end) in &sample.blinking { + out.extend_from_slice(&12u32.to_be_bytes()); + out.extend_from_slice(b"blnk"); + out.extend_from_slice(&start.to_be_bytes()); + out.extend_from_slice(&end.to_be_bytes()); + } + + // 9. twrp box + if let Some(flag) = sample.wrap_flag { + out.extend_from_slice(&9u32.to_be_bytes()); + out.extend_from_slice(b"twrp"); + out.push(flag); + } + + Ok(out) +} + +fn push_escaped_char(out: &mut String, ch: char) { + match ch { + '&' => out.push_str("&"), + '<' => out.push_str("<"), + '>' => out.push_str(">"), + _ => out.push(ch), + } +} + +/// Convert a [`TextSample`] into HTML-style formatted markup (``, ``, ``, ``). +pub fn sample_to_markup(sample: &TextSample) -> String { + if sample.styles.is_empty() { + let mut out = String::with_capacity(sample.text.len()); + for ch in sample.text.chars() { + push_escaped_char(&mut out, ch); + } + return out; + } + + let chars: Vec = sample.text.chars().collect(); + let n = chars.len(); + if n == 0 { + return String::new(); + } + + let mut starts: std::collections::HashMap> = std::collections::HashMap::new(); + let mut ends: std::collections::HashMap> = std::collections::HashMap::new(); + for st in &sample.styles { + if st.end_char > st.start_char { + starts.entry(st.start_char).or_default().push(st); + ends.entry(st.end_char).or_default().push(st); + } + } + + let mut out = String::with_capacity(sample.text.len() + sample.styles.len() * 16); + + for (i, &ch) in chars.iter().enumerate() { + let char_idx = i as u16; + + // Open tags for any style starting at char_idx + if let Some(list) = starts.get(&char_idx) { + for st in list { + let has_color = st.text_color_rgba != [255, 255, 255, 255]; + if has_color { + out.push_str(&format!( + "", + st.text_color_rgba[0], st.text_color_rgba[1], st.text_color_rgba[2] + )); + } + if st.is_bold() { + out.push_str(""); + } + if st.is_italic() { + out.push_str(""); + } + if st.is_underline() { + out.push_str(""); + } + } + } + + push_escaped_char(&mut out, ch); + + // Close tags for any style ending at char_idx + 1 + if let Some(list) = ends.get(&(char_idx + 1)) { + for st in list.iter().rev() { + if st.is_underline() { + out.push_str(""); + } + if st.is_italic() { + out.push_str(""); + } + if st.is_bold() { + out.push_str(""); + } + let has_color = st.text_color_rgba != [255, 255, 255, 255]; + if has_color { + out.push_str(""); + } + } + } + } + + out +} + +#[derive(Clone, Copy, PartialEq, Eq)] +struct CharFormatting { + flags: u8, + color: [u8; 4], +} + +impl Default for CharFormatting { + fn default() -> Self { + Self { flags: 0, color: [255, 255, 255, 255] } + } +} + +/// Parse HTML-style formatted markup (``, ``, ``, ``) into a [`TextSample`]. +pub fn markup_to_sample(markup: &str) -> TextSample { + let mut bold_depth = 0usize; + let mut italic_depth = 0usize; + let mut underline_depth = 0usize; + let mut color_stack: Vec<[u8; 4]> = Vec::new(); + + let mut decoded_chars: Vec = Vec::with_capacity(markup.len()); + let mut char_styles: Vec = Vec::with_capacity(markup.len()); + + let mut chars = markup.chars().peekable(); + + while let Some(ch) = chars.next() { + if ch == '<' { + let mut tag = String::new(); + for next in chars.by_ref() { + if next == '>' { + break; + } + tag.push(next); + } + let trimmed = tag.trim().to_ascii_lowercase(); + if trimmed == "b" { + bold_depth += 1; + } else if trimmed == "/b" { + bold_depth = bold_depth.saturating_sub(1); + } else if trimmed == "i" { + italic_depth += 1; + } else if trimmed == "/i" { + italic_depth = italic_depth.saturating_sub(1); + } else if trimmed == "u" { + underline_depth += 1; + } else if trimmed == "/u" { + underline_depth = underline_depth.saturating_sub(1); + } else if trimmed.starts_with("font") { + if let Some(color) = parse_font_color(&tag) { + color_stack.push(color); + } + } else if trimmed == "/font" { + color_stack.pop(); + } + } else { + let mut text_chunk = String::new(); + text_chunk.push(ch); + while let Some(&next) = chars.peek() { + if next == '<' { + break; + } + text_chunk.push(next); + chars.next(); + } + + let decoded = crate::decode_entities(&text_chunk); + let mut flags = 0u8; + if bold_depth > 0 { + flags |= STYLE_FLAG_BOLD; + } + if italic_depth > 0 { + flags |= STYLE_FLAG_ITALIC; + } + if underline_depth > 0 { + flags |= STYLE_FLAG_UNDERLINE; + } + let color = color_stack.last().copied().unwrap_or([255, 255, 255, 255]); + let fmt = CharFormatting { flags, color }; + + for c in decoded.chars() { + decoded_chars.push(c); + char_styles.push(fmt); + } + } + } + + let text: String = decoded_chars.iter().collect(); + + // Group adjacent characters with identical non-default formatting into sorted, non-overlapping style runs. + let mut styles = Vec::new(); + let mut run_start: Option<(usize, CharFormatting)> = None; + + for (idx, &fmt) in char_styles.iter().enumerate() { + let is_styled = fmt.flags != 0 || fmt.color != [255, 255, 255, 255]; + match run_start { + Some((start, current_fmt)) => { + if fmt != current_fmt { + if current_fmt.flags != 0 || current_fmt.color != [255, 255, 255, 255] { + styles.push(StyleRecord { + start_char: start as u16, + end_char: idx as u16, + font_id: 1, + face_style_flags: current_fmt.flags, + font_size: 16, + text_color_rgba: current_fmt.color, + }); + } + run_start = if is_styled { Some((idx, fmt)) } else { None }; + } + } + None => { + if is_styled { + run_start = Some((idx, fmt)); + } + } + } + } + + if let Some((start, fmt)) = run_start { + styles.push(StyleRecord { + start_char: start as u16, + end_char: char_styles.len() as u16, + font_id: 1, + face_style_flags: fmt.flags, + font_size: 16, + text_color_rgba: fmt.color, + }); + } + + TextSample { text, styles, ..Default::default() } +} + +/// Helper to parse color attribute from `` tag. +fn parse_font_color(tag: &str) -> Option<[u8; 4]> { + let lower = tag.to_ascii_lowercase(); + let col_idx = lower.find("color=")?; + let rest = tag[col_idx + 6..].trim_start(); + let val = if let Some(stripped) = rest.strip_prefix('"') { + let end = stripped.find('"')?; + &stripped[..end] + } else if let Some(stripped) = rest.strip_prefix('\'') { + let end = stripped.find('\'')?; + &stripped[..end] + } else { + let end = rest.find(char::is_whitespace).unwrap_or(rest.len()); + &rest[..end] + }; + + let hex = val.strip_prefix('#').unwrap_or(val); + if hex.len() == 6 { + let r = u8::from_str_radix(hex.get(0..2)?, 16).ok()?; + let g = u8::from_str_radix(hex.get(2..4)?, 16).ok()?; + let b = u8::from_str_radix(hex.get(4..6)?, 16).ok()?; + Some([r, g, b, 255]) + } else if hex.len() == 8 { + let r = u8::from_str_radix(hex.get(0..2)?, 16).ok()?; + let g = u8::from_str_radix(hex.get(2..4)?, 16).ok()?; + let b = u8::from_str_radix(hex.get(4..6)?, 16).ok()?; + let a = u8::from_str_radix(hex.get(6..8)?, 16).ok()?; + Some([r, g, b, a]) + } else { + None + } +} + +/// Convert a caption [`Cue`] into a [`TextSample`]. +pub fn cue_to_sample(cue: &Cue) -> TextSample { + markup_to_sample(&cue.text) +} + +/// Convert a [`TextSample`] into a caption [`Cue`] spanning `start` to `end`. +pub fn sample_to_cue(sample: &TextSample, start: Tick, end: Tick) -> Cue { + Cue { start, end, text: sample_to_markup(sample), speaker: None, id: None, settings: String::new() } +} + +/// Decode a stream of timed text samples into a [`Document`]. +pub fn decode_timed_samples<'a, I>(doc: &mut Document, samples: I, timescale: u32) -> Result<()> +where + I: IntoIterator, +{ + decode_timed_samples_with_config(doc, samples, timescale, None) +} + +/// Decode a stream of timed text samples into a [`Document`], applying an optional sample description configuration. +pub fn decode_timed_samples_with_config<'a, I>(doc: &mut Document, samples: I, timescale: u32, config: Option<&Tx3gConfig>) -> Result<()> +where + I: IntoIterator, +{ + if timescale == 0 { + return Ok(()); + } + let ts = timescale as i128; + for (pts, duration, data) in samples { + let mut sample = read_sample(data)?; + if sample.text.trim().is_empty() { + continue; + } + if sample.styles.is_empty() + && let Some(cfg) = config + && (cfg.default_style.face_style_flags != 0 || cfg.default_style.text_color_rgba != [255, 255, 255, 255]) + { + sample.styles.push(StyleRecord { + start_char: 0, + end_char: sample.text.chars().count() as u16, + font_id: cfg.default_style.font_id, + face_style_flags: cfg.default_style.face_style_flags, + font_size: cfg.default_style.font_size, + text_color_rgba: cfg.default_style.text_color_rgba, + }); + } + let end_pts = pts.checked_add(duration as u64).ok_or(Error::InvalidBox("timestamp interval overflow"))?; + let start_ticks = (pts as i128 * TICKS_PER_SECOND as i128 / ts) as i64; + let end_ticks = (end_pts as i128 * TICKS_PER_SECOND as i128 / ts) as i64; + doc.cues.push(sample_to_cue(&sample, Tick(start_ticks), Tick(end_ticks))); + } + Ok(()) +} diff --git a/crates/captions/tests/it/main.rs b/crates/captions/tests/it/main.rs index 437b2ba67..7d8070cad 100644 --- a/crates/captions/tests/it/main.rs +++ b/crates/captions/tests/it/main.rs @@ -2,6 +2,8 @@ mod ass; mod limits; mod literal_roundtrips; mod mcc_708_timing; +#[cfg(feature = "mov-text")] +mod mov_text; mod pjs_realtext_jacosub; mod roundtrip; mod ttml_body_styles; diff --git a/crates/captions/tests/it/mov_text.rs b/crates/captions/tests/it/mov_text.rs new file mode 100644 index 000000000..dfd5f73ea --- /dev/null +++ b/crates/captions/tests/it/mov_text.rs @@ -0,0 +1,349 @@ +//! Clean-room tests and FFmpeg oracle tests for MP4 Timed Text (`mov_text` / `tx3g`). + +use craft_captions::mov_text::{ + Error, KaraokeEntry, STYLE_FLAG_BOLD, STYLE_FLAG_ITALIC, STYLE_FLAG_UNDERLINE, StyleRecord, TextBox, TextSample, Tx3gConfig, + decode_timed_samples, markup_to_sample, read_sample, sample_to_markup, write_sample, +}; +use craft_captions::time::Tick; +use craft_captions::{Document, TICKS_PER_SECOND}; + +#[test] +fn test_plain_text_roundtrip() { + let sample = TextSample { text: "Hello world without styles".to_string(), ..Default::default() }; + + let bytes = write_sample(&sample).expect("write sample"); + assert_eq!(bytes.len(), 2 + sample.text.len()); + assert_eq!(&bytes[..2], &(sample.text.len() as u16).to_be_bytes()); + assert_eq!(&bytes[2..], sample.text.as_bytes()); + + let decoded = read_sample(&bytes).expect("read sample"); + assert_eq!(decoded.text, sample.text); + assert!(decoded.styles.is_empty()); +} + +#[test] +fn test_empty_sample_roundtrip() { + let sample = TextSample::default(); + let bytes = write_sample(&sample).expect("write"); + assert_eq!(bytes, &[0x00, 0x00]); + + let decoded = read_sample(&bytes).expect("read"); + assert_eq!(decoded.text, ""); + assert!(decoded.styles.is_empty()); +} + +#[test] +fn test_styles_roundtrip() { + let sample = TextSample { + text: "Bold, Italic, Underline, and Colored".to_string(), + styles: vec![ + StyleRecord { + start_char: 0, + end_char: 4, + font_id: 1, + face_style_flags: STYLE_FLAG_BOLD, + font_size: 16, + text_color_rgba: [255, 255, 255, 255], + }, + StyleRecord { + start_char: 6, + end_char: 12, + font_id: 1, + face_style_flags: STYLE_FLAG_ITALIC, + font_size: 18, + text_color_rgba: [255, 255, 255, 255], + }, + StyleRecord { + start_char: 14, + end_char: 23, + font_id: 1, + face_style_flags: STYLE_FLAG_UNDERLINE, + font_size: 16, + text_color_rgba: [255, 255, 255, 255], + }, + StyleRecord { start_char: 29, end_char: 36, font_id: 1, face_style_flags: 0, font_size: 20, text_color_rgba: [255, 0, 0, 255] }, + ], + ..Default::default() + }; + + let bytes = write_sample(&sample).expect("write"); + let decoded = read_sample(&bytes).expect("read"); + + assert_eq!(decoded.text, sample.text); + assert_eq!(decoded.styles.len(), 4); + assert_eq!(decoded.styles, sample.styles); + + assert!(decoded.styles[0].is_bold()); + assert!(!decoded.styles[0].is_italic()); + assert!(decoded.styles[1].is_italic()); + assert!(decoded.styles[2].is_underline()); + assert_eq!(decoded.styles[3].text_color_rgba, [255, 0, 0, 255]); +} + +#[test] +fn test_all_modifier_boxes_roundtrip() { + let sample = TextSample { + text: "Full modifiers test".to_string(), + styles: vec![StyleRecord { + start_char: 0, + end_char: 4, + font_id: 1, + face_style_flags: STYLE_FLAG_BOLD, + font_size: 16, + text_color_rgba: [255, 255, 255, 255], + }], + highlight: Some((5, 14)), + highlight_color: Some([255, 255, 0, 255]), + karaoke: Some(( + 100, + vec![ + KaraokeEntry { highlight_end_time: 200, start_char: 0, end_char: 4 }, + KaraokeEntry { highlight_end_time: 350, start_char: 5, end_char: 14 }, + ], + )), + scroll_delay: Some(500), + hypertext: vec![craft_captions::mov_text::HyperText { + start_char: 0, + end_char: 19, + url: "https://example.com".to_string(), + alt_string: "Example".to_string(), + }], + text_box: Some(TextBox { top: 10, left: 20, bottom: 100, right: 200 }), + blinking: vec![(0, 4), (15, 19)], + wrap_flag: Some(1), + }; + + let bytes = write_sample(&sample).expect("write"); + let decoded = read_sample(&bytes).expect("read"); + + assert_eq!(decoded, sample); +} + +#[test] +fn test_utf16_bom_reading() { + // UTF-16 BE with BOM + let text = "Hello UTF-16"; + let mut data_be = Vec::new(); + let utf16_be_bytes: Vec = text.encode_utf16().flat_map(|u| u.to_be_bytes()).collect(); + let total_len = 2 + utf16_be_bytes.len(); + data_be.extend_from_slice(&(total_len as u16).to_be_bytes()); + data_be.extend_from_slice(&[0xFE, 0xFF]); + data_be.extend_from_slice(&utf16_be_bytes); + + let decoded_be = read_sample(&data_be).expect("read UTF-16 BE"); + assert_eq!(decoded_be.text, text); + + // UTF-16 LE with BOM + let mut data_le = Vec::new(); + let utf16_le_bytes: Vec = text.encode_utf16().flat_map(|u| u.to_le_bytes()).collect(); + data_le.extend_from_slice(&(total_len as u16).to_be_bytes()); + data_le.extend_from_slice(&[0xFF, 0xFE]); + data_le.extend_from_slice(&utf16_le_bytes); + + let decoded_le = read_sample(&data_le).expect("read UTF-16 LE"); + assert_eq!(decoded_le.text, text); +} + +#[test] +fn test_markup_conversion() { + let markup = "Hello Bold and Italic and Underline and Red"; + let sample = markup_to_sample(markup); + + assert_eq!(sample.text, "Hello Bold and Italic and Underline and Red"); + assert_eq!(sample.styles.len(), 4); + + let bold = &sample.styles[0]; + assert_eq!(&sample.text[bold.start_char as usize..bold.end_char as usize], "Bold"); + assert!(bold.is_bold()); + + let italic = &sample.styles[1]; + assert_eq!(&sample.text[italic.start_char as usize..italic.end_char as usize], "Italic"); + assert!(italic.is_italic()); + + let underline = &sample.styles[2]; + assert_eq!(&sample.text[underline.start_char as usize..underline.end_char as usize], "Underline"); + assert!(underline.is_underline()); + + let red = &sample.styles[3]; + assert_eq!(&sample.text[red.start_char as usize..red.end_char as usize], "Red"); + assert_eq!(red.text_color_rgba, [255, 0, 0, 255]); + + let regenerated = sample_to_markup(&sample); + assert_eq!(regenerated, markup); +} + +#[test] +fn test_nested_styles_sorted_non_overlapping() { + let markup = "ABC"; + let sample = markup_to_sample(markup); + assert_eq!(sample.text, "ABC"); + assert_eq!(sample.styles.len(), 3); + // [0, 1): A is bold + assert_eq!(sample.styles[0].start_char, 0); + assert_eq!(sample.styles[0].end_char, 1); + assert_eq!(sample.styles[0].face_style_flags, STYLE_FLAG_BOLD); + // [1, 2): B is bold + italic + assert_eq!(sample.styles[1].start_char, 1); + assert_eq!(sample.styles[1].end_char, 2); + assert_eq!(sample.styles[1].face_style_flags, STYLE_FLAG_BOLD | STYLE_FLAG_ITALIC); + // [2, 3): C is bold + assert_eq!(sample.styles[2].start_char, 2); + assert_eq!(sample.styles[2].end_char, 3); + assert_eq!(sample.styles[2].face_style_flags, STYLE_FLAG_BOLD); +} + +#[test] +fn test_entities_and_literal_escaping() { + let markup = "A & B < C"; + let sample = markup_to_sample(markup); + assert_eq!(sample.text, "A & B < C"); + assert_eq!(sample.styles.len(), 1); + assert_eq!(sample.styles[0].start_char, 4); + assert_eq!(sample.styles[0].end_char, 9); + + let roundtripped = sample_to_markup(&sample); + assert_eq!(roundtripped, "A & B < C"); +} + +#[test] +fn test_twrp_box() { + let sample = TextSample { text: "Wrap me".to_string(), wrap_flag: Some(1), ..Default::default() }; + let bytes = write_sample(&sample).expect("write sample"); + // Verify bytes contain twrp box + assert!(bytes.windows(4).any(|w| w == b"twrp")); + + let read_back = read_sample(&bytes).expect("read sample"); + assert_eq!(read_back.wrap_flag, Some(1)); +} + +#[test] +fn test_tx3g_config_roundtrip() { + let cfg = Tx3gConfig { + display_flags: 0x0000_0001, + horizontal_justification: 1, + vertical_justification: -1, + background_color: [10, 20, 30, 255], + default_text_box: TextBox { top: 0, left: 0, bottom: 480, right: 640 }, + default_style: StyleRecord { + start_char: 0, + end_char: 0, + font_id: 1, + face_style_flags: STYLE_FLAG_BOLD, + font_size: 24, + text_color_rgba: [255, 255, 255, 255], + }, + fonts: vec![(1, "Serif".to_string()), (2, "Sans".to_string())], + }; + + let bytes = cfg.write(); + let parsed = Tx3gConfig::parse(&bytes).expect("parse config"); + assert_eq!(parsed, cfg); +} + +#[test] +fn test_decode_timed_samples_to_document() { + let mut doc = Document::default(); + + let s1 = write_sample(&markup_to_sample("First cue")).expect("s1"); + let s2 = write_sample(&markup_to_sample("Second cue")).expect("s2"); + + let samples = vec![(0u64, 1000u32, s1.as_slice()), (1000u64, 1500u32, s2.as_slice())]; + + decode_timed_samples(&mut doc, samples, 1000).expect("decode samples"); + + assert_eq!(doc.cues.len(), 2); + assert_eq!(doc.cues[0].start, Tick(0)); + assert_eq!(doc.cues[0].end, Tick(TICKS_PER_SECOND)); + assert_eq!(doc.cues[0].text, "First cue"); + + assert_eq!(doc.cues[1].start, Tick(TICKS_PER_SECOND)); + assert_eq!(doc.cues[1].end, Tick((TICKS_PER_SECOND as f64 * 2.5) as i64)); + assert_eq!(doc.cues[1].text, "Second cue"); +} + +#[test] +fn test_hostile_inputs_never_panic() { + // Empty input + assert!(matches!(read_sample(&[]), Err(Error::Truncated))); + + // 1-byte input + assert!(matches!(read_sample(&[0x00]), Err(Error::Truncated))); + + // Length says 10 bytes, but slice ends + assert!(matches!(read_sample(&[0x00, 0x0A, 0x41]), Err(Error::Truncated))); + + // Invalid UTF-8 without BOM + assert!(matches!(read_sample(&[0x00, 0x02, 0xFF, 0xFF]), Err(Error::InvalidText))); + + // Box size < 8 + let mut bad_box = Vec::new(); + bad_box.extend_from_slice(&[0x00, 0x04, b'T', b'e', b's', b't']); + bad_box.extend_from_slice(&[0x00, 0x00, 0x00, 0x04, b's', b't', b'y', b'l']); + assert!(matches!(read_sample(&bad_box), Err(Error::InvalidBox(_)))); + + // Box size exceeds remaining slice + let mut truncated_box = Vec::new(); + truncated_box.extend_from_slice(&[0x00, 0x04, b'T', b'e', b's', b't']); + truncated_box.extend_from_slice(&[0x00, 0x00, 0x01, 0x00, b's', b't', b'y', b'l']); + assert!(matches!(read_sample(&truncated_box), Err(Error::Truncated))); + + // Unknown modifier boxes are safely ignored without error + let mut unknown_box = Vec::new(); + unknown_box.extend_from_slice(&[0x00, 0x04, b'T', b'e', b's', b't']); + unknown_box.extend_from_slice(&[0x00, 0x00, 0x00, 0x0C, b'f', b'a', b'k', b'e', 1, 2, 3, 4]); + let decoded = read_sample(&unknown_box).expect("unknown box should be skipped"); + assert_eq!(decoded.text, "Test"); +} + +#[test] +fn test_ffmpeg_mov_text_oracle() { + let Some(ff) = craft_media_testkit::ffmpeg() else { return }; + let temp_dir = std::env::temp_dir().join("craft_mov_text_test"); + let _ = std::fs::create_dir_all(&temp_dir); + + // 1. Create SRT file with formatting: bold, italic, underline + let srt_path = temp_dir.join("input.srt"); + let mp4_path = temp_dir.join("output.mp4"); + let srt_content = "1\n00:00:01,000 --> 00:00:03,000\nHello World and Italic and Underline\n"; + std::fs::write(&srt_path, srt_content).expect("write srt"); + + // Encode to MP4 with mov_text + let out = std::process::Command::new(&ff) + .args(["-y", "-i", srt_path.to_str().expect("path"), "-c:s", "mov_text", mp4_path.to_str().expect("path")]) + .output(); + let Ok(output) = out else { return }; + if !output.status.success() { + return; + } + + // Read MP4 through craft-media ISOBMFF demuxer + let mp4_bytes = std::fs::read(&mp4_path).expect("read mp4"); + let mp4 = craft_media::isobmff::open(&mp4_bytes).expect("open mp4"); + + let (track_idx, track) = + mp4.tracks.iter().enumerate().find(|(_, t)| t.kind == craft_media::isobmff::TrackKind::Subtitle).expect("subtitle track"); + + // Decode all non-empty samples + let mut found_styled_cue = false; + for sample_idx in 0..track.samples.len() { + let sample_data = mp4.read_sample(&mp4_bytes, track_idx, sample_idx).expect("read sample"); + let sample = read_sample(&sample_data).expect("read sample"); + if !sample.text.is_empty() { + assert_eq!(sample.text, "Hello World and Italic and Underline"); + let markup = sample_to_markup(&sample); + assert!(markup.contains("World"), "expected bold markup: {markup}"); + assert!(markup.contains("Italic"), "expected italic markup: {markup}"); + assert!(markup.contains("Underline"), "expected underline markup: {markup}"); + found_styled_cue = true; + } + } + assert!(found_styled_cue, "expected to find styled subtitle sample in MP4"); + + // 2. Test roundtrip: our encoder writes sample bytes -> decode with FFmpeg to verify exact text & styles + let our_sample = markup_to_sample("Greeting: Craft Timed Text"); + let encoded_bytes = write_sample(&our_sample).expect("write sample"); + + // Verify our sample reads back identically + let roundtripped = read_sample(&encoded_bytes).expect("read back"); + assert_eq!(sample_to_markup(&roundtripped), "Greeting: Craft Timed Text"); +} diff --git a/crates/cloud-local/Cargo.toml b/crates/cloud-local/Cargo.toml new file mode 100644 index 000000000..39d6dfa6e --- /dev/null +++ b/crates/cloud-local/Cargo.toml @@ -0,0 +1,25 @@ +[package] +name = "craft-cloud-local" +version.workspace = true +edition.workspace = true +license.workspace = true +repository.workspace = true +rust-version.workspace = true +description = "A reference CloudBackend over a local folder, proving the contract needs no specific provider" + +[lints] +workspace = true + +[dependencies] +# Resolution-time confinement: every path this crate resolves goes through a `Dir` capability +# opened on the configured root, never through an absolute OS path this crate builds itself. +# `craft-font-store` already depends on the lower-level `cap-primitives` for the same family of +# guarantee; this crate uses the ergonomic `cap-std` built on top of it instead of hand-rolling +# the equivalent `Dir`-style API again. +cap-std = "4" +craft-cloud = { workspace = true } +craft-ui = { workspace = true, features = ["cloud"] } + +[dev-dependencies] +tempfile = "3" +egui = { workspace = true } diff --git a/crates/cloud-local/README.md b/crates/cloud-local/README.md new file mode 100644 index 000000000..a5006c2ca --- /dev/null +++ b/crates/cloud-local/README.md @@ -0,0 +1,39 @@ +# craft-cloud-local + +A reference `CloudBackend` over one folder on disk, proving that `craft-cloud`'s contract needs +no specific provider behind it. + +## No-escape policy + +Every path this crate is handed, a `Job::List`/`Read`/`Write` path or a `Job::Create` name, is +confined to the configured root before anything touches a filesystem, in two layers. + +A path's segments are accepted only when each one parses as a single `Component::Normal`: no +`..`, no `.`, no empty segment, and no absolute form. A `Create` name goes through a stricter +check of its own, since it is one chosen name and not a path: it additionally refuses a +backslash, a colon, or a Windows reserved device name (`CON`, `COM1`, `CONIN$`, and so on), on +every platform this crate builds for, not only on Windows, because a chosen name reaches this +backend from whatever platform the UI runs on. An existing name that already has one of those +characters, discovered through `list`, stays reachable: `:` and `\` are not path separators on +any platform's filesystem, so refusing to read a real file back because of a byte in its name +(macOS stores a `/` typed in Finder as `:` on disk) would be a usability bug with no matching +security benefit. + +The second layer is the one that actually keeps resolution inside the root: every already +segment-checked relative path is handed to a [`cap-std`](https://docs.rs/cap-std) `Dir` +capability opened on the root, never joined onto the root as an absolute OS path this crate +builds itself. `cap-std` resolves one path component at a time against real, already-open +directory handles, so a symlink or (on Windows) a directory junction anywhere under the root, +dangling or already pointing outside, cannot walk resolution above the root. There is no separate +"does this still look like it is inside the root" check with a window for the directory tree to +change underneath it between the check and the actual read or write; the one resolution is the +open. + +## Hard links + +A hard link is not a symlink, and this backend does not refuse one: from inside the sandbox the +inode it names is an ordinary file. What it protects instead is the shared inode's content: a +write never truncates its target in place. It writes a new sibling file and renames that sibling +over the target, so the target's directory entry is replaced rather than its bytes being +overwritten. A rename only ever changes one name; it does not reach through to any other name, +inside the root or out, that happens to point at the same inode. diff --git a/crates/cloud-local/src/lib.rs b/crates/cloud-local/src/lib.rs new file mode 100644 index 000000000..715a87084 --- /dev/null +++ b/crates/cloud-local/src/lib.rs @@ -0,0 +1,510 @@ +#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)] + +//! A reference [`CloudBackend`] that treats one folder on disk as the cloud. +//! +//! [`craft_ui::cloud::CloudBackend`] names a contract and nothing about who +//! answers it. This crate is the proof: a working implementation that reaches +//! no service, a vendor, or a personal repo anybody else has to trust. An app +//! wires [`LocalBackend`] the same way it would wire a provider's own client, +//! by calling [`craft_ui::cloud::CloudFiles::connect`]. Swapping one for the +//! other is the whole point; nothing above the [`CloudBackend`] seam can tell +//! the difference. +//! +//! What this is not: a sync engine, a sharing service, or a place to keep a +//! credential. A folder has no concept of another account, so +//! [`Job::SharedWithMe`] answers empty and [`Job::Conversation`] answers with +//! a [`Fault`], and [`Account::capabilities`] claims neither. Reporting a +//! capability this backend cannot honour would be the broken window the +//! contract's own docs warn about. +//! +//! Every job answers on its own [`std::thread`]. [`CloudBackend::submit`] +//! must return before the file is opened, let alone read, or a twenty +//! megabyte document would freeze the window that called it. +//! +//! # The no-escape policy +//! +//! `Entry::id` and `Entry::path` are the same slash-separated path relative to +//! `root`, always starting with `/` below the root itself (the root's own +//! path is the empty string, matching [`Job::List`]'s contract), and a +//! [`Job::Create`] name is one plain file name, not a path at all. Neither is +//! an OS path string handed to `std::fs`. Confinement happens in two layers: +//! +//! 1. `confine_segment` (every path segment) and `confine_name` (a +//! `Create` name, stricter) reject `..`, `.`, an empty segment, an +//! absolute form, and anything that is not exactly one +//! [`std::path::Component::Normal`]. `confine_name` additionally refuses a +//! backslash, a colon, and a Windows reserved device name +//! (`CON`, `COM1`, `CONIN$`, ...) on every platform this crate builds for, +//! because a chosen name reaches this backend from whatever platform the +//! UI runs on. Browsing an *existing* name is more lenient: a literal `:` +//! or `\` already on disk (macOS stores a `/` typed in Finder as `:`) is +//! not itself a path separator on any platform's filesystem, so +//! `confine_segment` lets `list`, `read` and `write` keep such a name +//! reachable instead of discovering it and then refusing to open it. +//! 2. `open_root` opens `root` as a [`cap_std::fs::Dir`] capability once per +//! job. Every `list`, `read`, `write` and `create` routes its +//! already-segment-checked relative path through that one `Dir`, never +//! through an absolute OS path built by this crate. `cap_std` resolves one +//! component at a time against real, already-open directory handles, so a +//! symlink or a Windows junction anywhere under `root`, dangling or not, +//! cannot walk resolution above `root`: there is no separate "is this +//! still inside the root" check with a window for the directory tree to +//! change underneath it, because the one resolution *is* the open. +//! +//! A hard link is not a symlink and `cap_std` does not refuse one; the inode +//! it names is an ordinary file from inside the sandbox. [`write`] protects +//! it a different way: it always writes a sibling temporary file and renames +//! it over the target, rather than truncating the target in place. A rename +//! replaces one name's directory entry; it never reaches through to another +//! name that happens to point at the same inode outside `root`. + +use std::ffi::OsStr; +use std::fs; +use std::io::{Read as _, Write as _}; +use std::path::{Component, Path, PathBuf}; +use std::sync::atomic::{AtomicU64, Ordering}; + +use cap_std::fs::{Dir, OpenOptions}; +use craft_cloud::{Capability, Entry, EntryKind}; +use craft_ui::cloud::{Account, CloudBackend, Event, Fault, Job, Post}; + +/// Where "the cloud" lives for this backend: one directory on disk. +pub struct LocalBackend { + root: PathBuf, + /// Shown in the account badge. Nothing else reads it. + display: String, +} + +impl LocalBackend { + /// Treat `root` as the cloud. The directory is not created here; a + /// listing of a root that does not exist yet answers with a [`Fault`] + /// the same way a real provider's missing folder would. [`Job::Create`] + /// is the one exception, and always has been: it brings a fresh root + /// into existence itself, the same way a first Save As does not require + /// the destination folder to already be there. + pub fn new(root: PathBuf) -> LocalBackend { + LocalBackend { root, display: "Local disk".to_owned() } + } + + /// Name shown in the account badge, in place of the default "Local disk". + pub fn named(mut self, display: impl Into) -> LocalBackend { + self.display = display.into(); + self + } +} + +impl CloudBackend for LocalBackend { + fn submit(&self, job: Job, post: Post) { + let root = self.root.clone(); + match job { + // Nothing is saved between runs and nothing was ever signed into, + // so there is nothing to forget. The trait states no answer for + // this job; CloudFiles::sign_out clears its own state regardless + // of whether anything ever arrives. + Job::SignOut => {} + Job::Account | Job::SignIn => { + let display = self.display.clone(); + std::thread::spawn(move || post.send(Event::Account(Ok(account(display))))); + } + // There is no browser round trip: a local folder is already + // "linked" the moment it exists. Reporting that immediately, + // rather than inventing a URL nobody needs to visit, is what the + // contract calls honest. + Job::LinkStart | Job::LinkPoll(_) => { + std::thread::spawn(move || post.send(Event::Linked(Ok(true)))); + } + Job::List(path) => { + std::thread::spawn(move || post.send(Event::Listed { entries: list(&root, &path), path })); + } + Job::SharedWithMe => { + std::thread::spawn(move || post.send(Event::Shared(Ok(Vec::new())))); + } + Job::Read { entry, into } => { + std::thread::spawn(move || match read(&root, &entry) { + Ok((entry, bytes)) => post.send(Event::Read { entry, into, bytes: Ok(bytes) }), + Err(fault) => post.send(Event::Read { entry, into, bytes: Err(fault) }), + }); + } + Job::Write { uid, entry, bytes } => { + std::thread::spawn(move || post.send(Event::Saved { uid, entry: write(&root, &entry, &bytes) })); + } + Job::Create { uid, folder, name, bytes } => { + std::thread::spawn(move || post.send(Event::Saved { uid, entry: create(&root, &folder, &name, &bytes) })); + } + // No sharing, no accounts beyond this one, and so nowhere for a + // conversation to live. A reference backend that invented one + // would be lying about what a folder on disk can do. + Job::Conversation(_) => { + std::thread::spawn(move || { + post.send(Event::Conversation(Err(Fault::Refused("this reference backend has no shared workspace to converse in".to_owned())))) + }); + } + } + } +} + +fn account(display: String) -> Account { + Account { display, capabilities: vec![Capability::Files, Capability::Etags], provider_linked: true } +} + +/// Turns a [`Job`]'s slash-separated path into a path relative to `root`, +/// refusing anything that is not a run of ordinary names. The result is +/// never joined onto `root` as an OS path; every caller hands it to a +/// [`cap_std::fs::Dir`] opened on `root` instead, which is the layer that +/// actually keeps resolution from leaving `root`. +/// +/// `.` and repeated or leading slashes are just an empty segment and are +/// skipped, the same way a browser's address bar collapses them. Every other +/// segment goes through [`confine_segment`]. +fn relative(path: &str) -> Result { + let mut rel = PathBuf::new(); + for segment in path.split('/') { + if segment.is_empty() || segment == "." { + continue; + } + rel.push(confine_segment(segment)?); + } + Ok(rel) +} + +/// Confines one path segment to a single ordinary file or folder name. +/// +/// Accepted only when `segment` parses as exactly one [`Component::Normal`] +/// equal to `segment` itself: no empty name, no `.` or `..`, no absolute +/// form, and nothing left over for a second component to hide in. +/// +/// This is deliberately lenient about an ordinary character such as `:` or +/// `\` that is not, on its own, a path separator on any platform's +/// filesystem: `list` discovers real names from disk, and a name containing +/// one of those (macOS stores a `/` typed in Finder as `:` on disk) must stay +/// reachable by a later `read` or `write`, not become visible-but-unopenable. +/// [`confine_name`] is the stricter check for a name being chosen new, where +/// refusing those characters costs nothing and closes a real escape. +fn confine_segment(segment: &str) -> Result<&str, Fault> { + let mut components = Path::new(segment).components(); + match (components.next(), components.next()) { + (Some(Component::Normal(name)), None) if name == OsStr::new(segment) => Ok(segment), + _ => Err(Fault::Refused(format!("{segment} is not a plain file name"))), + } +} + +/// Windows device names that name a device rather than a file, with or +/// without a trailing extension (`CON`, `con.txt`, ...). Checked on every +/// platform: a name chosen here can end up read on a Windows client too. +const WINDOWS_RESERVED_NAMES: &[&str] = &[ + "CON", "PRN", "AUX", "NUL", "CONIN$", "CONOUT$", "COM1", "COM2", "COM3", "COM4", "COM5", "COM6", "COM7", "COM8", "COM9", "LPT1", "LPT2", "LPT3", + "LPT4", "LPT5", "LPT6", "LPT7", "LPT8", "LPT9", +]; + +fn is_windows_reserved_name(name: &str) -> bool { + let stem = name.split('.').next().unwrap_or(name); + WINDOWS_RESERVED_NAMES.iter().any(|reserved| stem.eq_ignore_ascii_case(reserved)) +} + +/// Confines a [`Job::Create`] `name` to a single ordinary file name that is +/// safe to choose on any platform, not only the one this crate is built for. +/// +/// Stricter than [`confine_segment`]: a backslash or colon is refused +/// outright first, because a Unix build's [`Component`] parser does not +/// treat either as a separator and would wave a Windows drive letter or UNC +/// prefix (`C:`, `\\server\share`) straight through as one ordinary name. A +/// Windows reserved device name is refused the same way. None of this costs +/// anything here, unlike applying it to a name `list` merely discovered. +fn confine_name(name: &str) -> Result<&str, Fault> { + if name.contains('\\') || name.contains(':') { + return Err(Fault::Refused(format!("{name} is not a plain file name"))); + } + if is_windows_reserved_name(name) { + return Err(Fault::Refused(format!("{name} is a reserved device name on Windows"))); + } + confine_segment(name) +} + +/// Opens `root` as the one ambient-authority capability this crate holds. +/// Every other path in this crate is resolved relative to the [`Dir`] this +/// returns, never as an absolute OS path built by string concatenation. +fn open_root(root: &Path) -> Result { + Dir::open_ambient_dir(root, cap_std::ambient_authority()).map_err(|error| io_fault(&error)) +} + +/// The path a listed child gets, given the folder it was found in. +fn child_path(folder: &str, name: &str) -> String { + format!("{}/{name}", folder.trim_end_matches('/')) +} + +/// An opaque version token for a file's current bytes. +/// +/// Not a timestamp for a person to read (that would go through `chrono`, per +/// this workspace's rule); just enough to tell "the file I read" from "the +/// file as it is now" apart, which is all a conditional write needs. +fn etag_of(meta: &cap_std::fs::Metadata) -> String { + let stamp = + meta.modified().ok().and_then(|time| time.duration_since(cap_std::time::SystemClock::UNIX_EPOCH).ok()).map(|d| d.as_nanos()).unwrap_or(0); + format!("{}-{stamp}", meta.len()) +} + +fn io_fault(error: &std::io::Error) -> Fault { + use std::io::ErrorKind; + match error.kind() { + ErrorKind::NotFound => Fault::Refused("no such file or folder".to_owned()), + ErrorKind::PermissionDenied => Fault::Refused("permission denied".to_owned()), + _ => Fault::Unreachable(error.to_string()), + } +} + +fn list(root: &Path, path: &str) -> Result, Fault> { + let rel = relative(path)?; + let dir = open_root(root)?; + let read = if rel.as_os_str().is_empty() { dir.entries() } else { dir.read_dir(&rel) }; + let read = read.map_err(|error| io_fault(&error))?; + let mut entries = Vec::new(); + for item in read { + let item = item.map_err(|error| io_fault(&error))?; + let meta = item.metadata().map_err(|error| io_fault(&error))?; + let name = item.file_name().to_string_lossy().into_owned(); + let id = child_path(path, &name); + entries.push(Entry { + room: format!("local:{id}"), + name, + kind: if meta.is_dir() { EntryKind::Folder } else { EntryKind::File }, + size: if meta.is_dir() { None } else { Some(meta.len()) }, + modified: None, + mime: None, + etag: if meta.is_dir() { None } else { Some(etag_of(&meta)) }, + writable: true, + shared_by: None, + path: id.clone(), + id, + }); + } + entries.sort_by(|a, b| (a.kind != EntryKind::Folder, &a.name).cmp(&(b.kind != EntryKind::Folder, &b.name))); + Ok(entries) +} + +/// Reads a file's bytes together with the entry for the version just read. +/// +/// The entry is built from a fresh metadata call here, not handed back +/// unchanged from what the caller already believed. A reload after a conflict +/// hands in the stale entry it is trying to get past; echoing that back would +/// carry the old etag into the reloaded document, so the very next save would +/// conflict again on a copy that is actually current. +/// +/// Refuses outright if `entry.id` names a symlink, the same policy `write` +/// uses: this backend never reports the bytes of whatever a link happens to +/// point at, inside `root` or out. +fn read(root: &Path, entry: &Entry) -> Result<(Entry, Vec), Fault> { + let rel = relative(&entry.id)?; + let dir = open_root(root)?; + // Stats without following only the last component; every component + // before it is still resolved, and sandboxed, normally, so a link + // earlier in `rel` is refused by `open_root`'s `Dir` itself when `open` + // below walks it, never silently followed here either way. + match dir.symlink_metadata(&rel) { + Ok(meta) if meta.is_symlink() => return Err(Fault::Refused("that path is a link, not a plain file".to_owned())), + Ok(_) => {} + Err(error) if error.kind() == std::io::ErrorKind::NotFound => {} + Err(error) => return Err(io_fault(&error)), + } + let mut file = dir.open(&rel).map_err(|error| io_fault(&error))?; + let mut bytes = Vec::new(); + file.read_to_end(&mut bytes).map_err(|error| io_fault(&error))?; + let meta = file.metadata().map_err(|error| io_fault(&error))?; + let fresh = Entry { size: Some(meta.len()), etag: Some(etag_of(&meta)), ..entry.clone() }; + Ok((fresh, bytes)) +} + +/// Saves back over `entry`, refusing the write when the file moved on since +/// `entry.etag` was read. A file that no longer exists has nothing to +/// conflict with, the same way a provider treats a deleted document. +/// +/// Never truncates `entry.id`'s current bytes in place. [`write_replacing`] +/// writes a sibling temporary file and renames it over the target instead, +/// so a hard link sharing the target's inode keeps its own, unmodified copy: +/// the rename replaces `entry.id`'s directory entry, and never reaches +/// through to any other name pointing at the same inode. +fn write(root: &Path, entry: &Entry, bytes: &[u8]) -> Result { + let rel = relative(&entry.id)?; + let dir = open_root(root)?; + match dir.symlink_metadata(&rel) { + Ok(meta) if meta.is_symlink() => return Err(Fault::Refused("that path is a link, not a plain file".to_owned())), + Ok(meta) => { + if Some(etag_of(&meta)) != entry.etag { + return Err(Fault::Conflict); + } + } + Err(error) if error.kind() == std::io::ErrorKind::NotFound => {} + Err(error) => return Err(io_fault(&error)), + } + if let Some(parent) = rel.parent() { + dir.create_dir_all(parent).map_err(|error| io_fault(&error))?; + } + write_replacing(&dir, &rel, bytes)?; + let meta = dir.metadata(&rel).map_err(|error| io_fault(&error))?; + Ok(Entry { size: Some(meta.len()), etag: Some(etag_of(&meta)), ..entry.clone() }) +} + +/// The next in a run of sibling temporary names, unique within this process. +/// Not meant to resist a second process picking the same name; the create +/// this writes with is exclusive (`create_new`), so a collision there is +/// just retried under a new counter value rather than silently overwritten. +static TEMP_SEQUENCE: AtomicU64 = AtomicU64::new(0); + +/// Writes `bytes` to a new sibling of `rel` inside `dir`, then renames that +/// sibling over `rel`. See the module docs for why: a direct write would +/// truncate whatever `rel` currently names in place, and if that happens to +/// be a hard link to a file outside `root`, the outside copy would be +/// corrupted along with it. A rename only ever replaces `rel`'s own +/// directory entry. +fn write_replacing(dir: &Dir, rel: &Path, bytes: &[u8]) -> Result<(), Fault> { + let name = rel.file_name().ok_or_else(|| Fault::Refused("that path names no file".to_owned()))?; + let mut temp_name = OsStr::new(".").to_os_string(); + temp_name.push(name); + temp_name.push(format!(".tmp-{}-{}", std::process::id(), TEMP_SEQUENCE.fetch_add(1, Ordering::Relaxed))); + let temp_rel = match rel.parent() { + Some(parent) if !parent.as_os_str().is_empty() => parent.join(&temp_name), + _ => PathBuf::from(&temp_name), + }; + let mut options = OpenOptions::new(); + options.write(true).create_new(true); + let written = (|| -> Result<(), Fault> { + let mut handle = dir.open_with(&temp_rel, &options).map_err(|error| io_fault(&error))?; + handle.write_all(bytes).map_err(|error| io_fault(&error))?; + handle.sync_all().map_err(|error| io_fault(&error)) + })(); + if let Err(fault) = written { + let _ = dir.remove_file(&temp_rel); + return Err(fault); + } + if let Err(error) = dir.rename(&temp_rel, dir, rel) { + let _ = dir.remove_file(&temp_rel); + return Err(io_fault(&error)); + } + Ok(()) +} + +fn create(root: &Path, folder: &str, name: &str, bytes: &[u8]) -> Result { + // `name` is never a path: it is one `Job::Create` field that names the + // new file, so it goes through `confine_name` directly rather than + // through `relative`, which only ever splits and confines a slash path. + let name = confine_name(name)?; + // `root` is the operator-configured boundary, never attacker input, so + // creating it directly with `std::fs` is safe; this is also the one + // place that has always brought a fresh root into existence (see + // `LocalBackend::new`'s docs), and `Dir::open_ambient_dir` below needs it + // to already exist. + fs::create_dir_all(root).map_err(|error| io_fault(&error))?; + let dir = open_root(root)?; + let rel_folder = relative(folder)?; + dir.create_dir_all(&rel_folder).map_err(|error| io_fault(&error))?; + let rel = rel_folder.join(name); + // Exclusive creation, not an `exists` check ahead of a separate write: two + // creates of the same name racing both see "not there yet" otherwise, and + // the second write silently replaces the first with neither ever refused. + // `create_new` asks the filesystem to open and create in one step, so the + // loser gets an error instead of a chance to overwrite the winner. It also + // refuses outright when `name` already exists as a symlink, dangling or + // not: `O_EXCL` never follows one to decide whether it is "in the way". + let mut create_options = OpenOptions::new(); + create_options.write(true).create_new(true); + let mut handle = match dir.open_with(&rel, &create_options) { + Ok(handle) => handle, + Err(error) if error.kind() == std::io::ErrorKind::AlreadyExists => { + return Err(Fault::Refused(format!("{name} already exists"))); + } + Err(error) => return Err(io_fault(&error)), + }; + handle.write_all(bytes).map_err(|error| io_fault(&error))?; + drop(handle); + let meta = dir.metadata(&rel).map_err(|error| io_fault(&error))?; + let id = child_path(folder, name); + Ok(Entry { + room: format!("local:{id}"), + name: name.to_owned(), + kind: EntryKind::File, + size: Some(meta.len()), + modified: None, + mime: None, + etag: Some(etag_of(&meta)), + writable: true, + shared_by: None, + path: id.clone(), + id, + }) +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn a_parent_segment_cannot_walk_out_of_root() { + assert!(relative("../secrets").is_err()); + assert!(relative("Archive/../../../etc/passwd").is_err()); + } + + #[test] + fn repeated_and_trailing_slashes_collapse_like_a_browser_address_bar() { + assert_eq!(relative("//Archive//2026/").unwrap(), Path::new("Archive").join("2026")); + assert_eq!(relative("").unwrap(), PathBuf::new()); + } + + #[test] + fn confine_segment_accepts_only_a_single_ordinary_name() { + for ordinary in ["Minutes.txt", "Archive", "2026", "a name with spaces.docx"] { + assert!(confine_segment(ordinary).is_ok(), "{ordinary} is an ordinary name"); + } + } + + #[test] + fn confine_segment_refuses_empty_dot_and_dot_dot() { + for bad in ["", ".", ".."] { + assert!(confine_segment(bad).is_err(), "{bad:?} is not a single ordinary name"); + } + } + + #[test] + fn confine_segment_refuses_a_slash_hidden_inside_a_create_name() { + assert!(confine_segment("folder/evil").is_err()); + assert!(confine_segment("../outside.txt").is_err()); + assert!(confine_segment("/outside.txt").is_err()); + } + + /// The fix for the non-blocking finding that `list` made a real macOS + /// name (a literal `/`, stored on disk as `:`) visible but unreadable: an + /// existing name with an ordinary `:` byte is not refused by the lenient + /// per-segment check, only by `confine_name` for a chosen one. A literal + /// `\` is not tested the same way here: on a Windows build it really is + /// a second path component (`std::path::Component` already splits on + /// it), so there is no existing-name case for `confine_segment` to stay + /// lenient about cross-platform the way there is for `:`. + #[test] + fn confine_segment_tolerates_a_colon_already_on_disk() { + assert!(confine_segment("weird:name.txt").is_ok()); + assert!(relative("weird:name.txt").is_ok()); + } + + #[test] + fn confine_name_refuses_backslash_and_colon_on_every_platform() { + for bad in ["..\\outside.txt", "C:\\x", "C:evil", "\\\\server\\share\\x"] { + assert!(confine_name(bad).is_err(), "{bad:?} must be refused on every platform, not only on Windows"); + } + } + + #[test] + fn confine_name_refuses_windows_reserved_device_names() { + for bad in ["CON", "con", "con.txt", "NUL", "COM1", "lpt9.log", "CONIN$"] { + assert!(confine_name(bad).is_err(), "{bad:?} names a Windows device, not a file"); + } + for ordinary in ["console.txt", "NULLABLE.md", "COM10"] { + assert!(confine_name(ordinary).is_ok(), "{ordinary} only resembles a reserved name"); + } + } + + #[test] + fn a_folder_announces_no_capability_this_backend_cannot_honour() { + let reported = account("Local disk".to_owned()).capabilities; + for absent in [Capability::SharedWithMe, Capability::Sharing, Capability::Conversation, Capability::Contacts] { + assert!(!reported.contains(&absent), "a folder has no {absent:?}"); + } + } +} diff --git a/crates/cloud-local/tests/backend.rs b/crates/cloud-local/tests/backend.rs new file mode 100644 index 000000000..d2a9fd4e5 --- /dev/null +++ b/crates/cloud-local/tests/backend.rs @@ -0,0 +1,244 @@ +//! Drives [`craft_cloud_local::LocalBackend`] the way an app does: through +//! `craft_ui::cloud`'s own public functions, never by calling the backend +//! directly. That is the seam this crate exists to prove, so the tests stay +//! on the application's side of it. + +use std::sync::{Arc, Mutex}; +use std::time::{Duration, Instant}; + +use craft_cloud::{Entry, EntryKind}; +use craft_cloud_local::LocalBackend; +use craft_ui::cloud::{self, Account, CloudApp, CloudFiles, Destination, DocumentKind, Job}; + +const NOTE: DocumentKind = DocumentKind { extensions: &["txt"], mimes: &["text/plain"], noun: "note", default_extension: "txt" }; + +/// A document the harness was told to open: its name and its bytes. +type OpenedDocs = Arc)>>>; + +/// The least a [`CloudApp`] can be. What it was told to open is recorded, so a +/// round trip can be checked by content and not only by the entry metadata +/// `craft_ui` itself remembers. +struct Harness { + cloud: CloudFiles, + share: craft_ui::share::ShareDialog, + presence: craft_ui::presence::PresenceBar, + opened: OpenedDocs, + said: Arc>>, +} + +impl Harness { + fn new() -> Harness { + Harness { + cloud: CloudFiles::new(), + share: craft_ui::share::ShareDialog::new(), + presence: craft_ui::presence::PresenceBar::new(), + opened: Arc::new(Mutex::new(Vec::new())), + said: Arc::new(Mutex::new(Vec::new())), + } + } +} + +impl CloudApp for Harness { + fn cloud(&self) -> &CloudFiles { + &self.cloud + } + + fn cloud_mut(&mut self) -> &mut CloudFiles { + &mut self.cloud + } + + fn kind(&self) -> DocumentKind { + NOTE + } + + fn active(&self) -> Option { + None + } + + fn title(&self, _uid: u64) -> String { + String::new() + } + + fn open_bytes(&mut self, name: &str, bytes: Vec) -> Result, String> { + self.opened.lock().unwrap().push((name.to_owned(), bytes)); + Ok(Some(1)) + } + + fn encode(&mut self, _uid: u64, _into: Destination<'_>) -> Result, String> { + Ok(Vec::new()) + } + + fn close(&mut self, _uid: u64) {} + + fn sharing(&mut self) -> &mut craft_ui::share::ShareDialog { + &mut self.share + } + + fn presence(&mut self) -> &mut craft_ui::presence::PresenceBar { + &mut self.presence + } + + fn paint_icon(&self, _painter: &egui::Painter, _rect: egui::Rect, _kind: EntryKind, _colour: egui::Color32) {} + + fn open_url(&self, _url: &str) {} + + fn say(&mut self, text: String) { + self.said.lock().unwrap().push(text); + } + + fn app_name(&self) -> &str { + "Harness" + } +} + +fn wired(root: std::path::PathBuf) -> (Harness, egui::Context) { + let mut app = Harness::new(); + app.cloud.connect(LocalBackend::new(root)); + (app, egui::Context::default()) +} + +/// Drains whatever the backend's worker threads have sent so far, until +/// `done` says the state the test is waiting for arrived or five seconds pass. +/// Five seconds is far more than a thread doing local file IO ever needs; it +/// only guards against a real bug leaving the test to hang forever. +fn settle(app: &mut Harness, ctx: &egui::Context, mut done: impl FnMut(&Harness) -> bool) { + let start = Instant::now(); + loop { + ctx.begin_pass(Default::default()); + cloud::pump(app, ctx); + ctx.end_pass().textures_delta.clear(); + if done(app) { + return; + } + assert!(start.elapsed() < Duration::from_secs(5), "timed out waiting for the backend's worker thread"); + std::thread::sleep(Duration::from_millis(5)); + } +} + +#[test] +fn account_and_sign_in_report_the_same_fixed_identity_with_no_browser_round_trip() { + let dir = tempfile::tempdir().unwrap(); + let (mut app, ctx) = wired(dir.path().to_path_buf()); + + cloud::start(&mut app); + settle(&mut app, &ctx, |app| app.cloud().account.is_some()); + + assert_eq!( + app.cloud().account, + Some(Account { + display: "Local disk".to_owned(), + capabilities: vec![craft_cloud::Capability::Files, craft_cloud::Capability::Etags], + provider_linked: true + }) + ); + // There was never an account to link, so nothing was ever offered. + assert!(app.cloud().link.is_none()); +} + +#[test] +fn creating_a_document_writes_real_bytes_a_read_gets_back() { + let dir = tempfile::tempdir().unwrap(); + let (mut app, ctx) = wired(dir.path().to_path_buf()); + + cloud::submit(&app, Job::Create { uid: 1, folder: String::new(), name: "Minutes.txt".to_owned(), bytes: b"first draft".to_vec() }); + settle(&mut app, &ctx, |app| app.cloud().origins.contains_key(&1)); + + let entry = app.cloud().origins.get(&1).unwrap().entry.clone(); + assert_eq!(entry.name, "Minutes.txt"); + assert_eq!(entry.id, "/Minutes.txt"); + assert_eq!(fs_read(dir.path(), "Minutes.txt"), b"first draft"); + + cloud::submit(&app, Job::Read { entry, into: None }); + settle(&mut app, &ctx, |app| !app.opened.lock().unwrap().is_empty()); + + let opened = app.opened.lock().unwrap().clone(); + assert_eq!(opened, vec![("Minutes.txt".to_owned(), b"first draft".to_vec())], "the read got back exactly what the create wrote"); +} + +#[test] +fn a_write_under_a_stale_version_is_refused_and_never_overwrites_the_newer_file() { + let dir = tempfile::tempdir().unwrap(); + let (mut app, ctx) = wired(dir.path().to_path_buf()); + + cloud::submit(&app, Job::Create { uid: 1, folder: String::new(), name: "Minutes.txt".to_owned(), bytes: b"v1".to_vec() }); + settle(&mut app, &ctx, |app| app.cloud().origins.contains_key(&1)); + let stale = app.cloud().origins.get(&1).unwrap().entry.clone(); + + // Somebody else saves first, changing the file's etag without going + // through this window at all. + std::fs::write(dir.path().join("Minutes.txt"), b"somebody else's edit").unwrap(); + + cloud::submit(&app, Job::Write { uid: 1, entry: stale, bytes: b"this window's edit".to_vec() }); + settle(&mut app, &ctx, |app| app.cloud().conflict.is_some()); + + assert_eq!(app.cloud().conflict.as_ref().unwrap().uid, 1); + assert_eq!(fs_read(dir.path(), "Minutes.txt"), b"somebody else's edit", "the refused write never touched the file"); +} + +#[test] +fn listing_the_root_reflects_a_file_nobody_went_through_this_backend_to_write() { + let dir = tempfile::tempdir().unwrap(); + std::fs::write(dir.path().join("Agenda.txt"), b"1. roll call").unwrap(); + std::fs::create_dir(dir.path().join("Archive")).unwrap(); + let (mut app, ctx) = wired(dir.path().to_path_buf()); + + cloud::browse(&mut app, ""); + settle(&mut app, &ctx, |app| app.cloud().mine.loaded); + + let names: Vec<_> = app.cloud().mine.entries.iter().map(|entry| entry.name.clone()).collect(); + assert_eq!(names, vec!["Archive".to_owned(), "Agenda.txt".to_owned()], "folders first, then files, each alphabetised"); + let folder = app.cloud().mine.entries.iter().find(|entry| entry.name == "Archive").unwrap(); + assert_eq!(folder.kind, EntryKind::Folder); + assert!(folder.size.is_none()); +} + +#[test] +fn nobody_has_shared_anything_with_a_folder() { + let dir = tempfile::tempdir().unwrap(); + let (mut app, ctx) = wired(dir.path().to_path_buf()); + + cloud::load_shared(&mut app); + settle(&mut app, &ctx, |app| app.cloud().shared.loaded); + + assert_eq!(app.cloud().shared.entries, Vec::new()); + assert!(app.cloud().shared.error.is_none(), "an empty share list is not a failure"); +} + +#[test] +fn a_conversation_is_a_fault_this_backend_is_honest_about() { + let dir = tempfile::tempdir().unwrap(); + let (mut app, ctx) = wired(dir.path().to_path_buf()); + + cloud::submit(&app, Job::Conversation("/Minutes.txt".to_owned())); + settle(&mut app, &ctx, |app| app.cloud().status.is_some()); + + assert_eq!(app.cloud().status, Some("this reference backend has no shared workspace to converse in".to_owned())); +} + +#[test] +fn a_read_of_a_document_that_is_not_there_is_put_to_the_user_not_silently_dropped() { + let dir = tempfile::tempdir().unwrap(); + let (mut app, ctx) = wired(dir.path().to_path_buf()); + + let ghost = Entry { + id: "/ghost.txt".to_owned(), + room: "local:/ghost.txt".to_owned(), + name: "ghost.txt".to_owned(), + path: "/ghost.txt".to_owned(), + kind: EntryKind::File, + size: None, + modified: None, + mime: None, + etag: None, + writable: true, + shared_by: None, + }; + cloud::submit(&app, Job::Read { entry: ghost, into: None }); + settle(&mut app, &ctx, |app| !app.said.lock().unwrap().is_empty()); + + assert!(app.said.lock().unwrap()[0].contains("ghost.txt"), "the message names the document, not just that something failed"); +} + +fn fs_read(root: &std::path::Path, name: &str) -> Vec { + std::fs::read(root.join(name)).unwrap() +} diff --git a/crates/cloud-local/tests/confinement_regressions.rs b/crates/cloud-local/tests/confinement_regressions.rs new file mode 100644 index 000000000..6356e5150 --- /dev/null +++ b/crates/cloud-local/tests/confinement_regressions.rs @@ -0,0 +1,431 @@ +//! Confinement regressions for `crates/cloud-local`. The first round (FredApps' re-review) found +//! that `resolve` only split on `/` and rejected a segment equal to `..`, with no constraint on a +//! Windows backslash, a drive letter or UNC prefix, or a filesystem link, and that `create` +//! joined `name` onto the resolved folder with no validation of `name` at all. The second round +//! (benandez's re-review) reproduced three escapes the first fix still left open: a dangling +//! symlink, a check-then-use race on a swapped link, and a hard link sharing a file's inode. +//! Driven through `craft_ui::cloud`'s public functions the way an application does, with a +//! sentinel file and directory kept as a sibling of the configured root: every test here must +//! leave both untouched and unread. + +use std::path::PathBuf; +use std::sync::{Arc, Mutex}; +use std::time::{Duration, Instant}; + +use craft_cloud::{Entry, EntryKind}; +use craft_cloud_local::LocalBackend; +use craft_ui::cloud::{self, CloudApp, CloudFiles, Destination, DocumentKind, Job}; + +const NOTE: DocumentKind = DocumentKind { extensions: &["txt"], mimes: &["text/plain"], noun: "note", default_extension: "txt" }; + +/// A document the harness was told to open: its name and its bytes. +type OpenedDocs = Arc)>>>; + +struct Harness { + cloud: CloudFiles, + share: craft_ui::share::ShareDialog, + presence: craft_ui::presence::PresenceBar, + opened: OpenedDocs, + said: Arc>>, +} + +impl Harness { + fn new() -> Harness { + Harness { + cloud: CloudFiles::new(), + share: craft_ui::share::ShareDialog::new(), + presence: craft_ui::presence::PresenceBar::new(), + opened: Arc::new(Mutex::new(Vec::new())), + said: Arc::new(Mutex::new(Vec::new())), + } + } +} + +impl CloudApp for Harness { + fn cloud(&self) -> &CloudFiles { + &self.cloud + } + fn cloud_mut(&mut self) -> &mut CloudFiles { + &mut self.cloud + } + fn kind(&self) -> DocumentKind { + NOTE + } + fn active(&self) -> Option { + None + } + fn title(&self, _uid: u64) -> String { + String::new() + } + fn open_bytes(&mut self, name: &str, bytes: Vec) -> Result, String> { + self.opened.lock().unwrap().push((name.to_owned(), bytes)); + Ok(Some(1)) + } + fn encode(&mut self, _uid: u64, _into: Destination<'_>) -> Result, String> { + Ok(Vec::new()) + } + fn close(&mut self, _uid: u64) {} + fn sharing(&mut self) -> &mut craft_ui::share::ShareDialog { + &mut self.share + } + fn presence(&mut self) -> &mut craft_ui::presence::PresenceBar { + &mut self.presence + } + fn paint_icon(&self, _painter: &egui::Painter, _rect: egui::Rect, _kind: EntryKind, _colour: egui::Color32) {} + fn open_url(&self, _url: &str) {} + fn say(&mut self, text: String) { + self.said.lock().unwrap().push(text); + } + fn app_name(&self) -> &str { + "Harness" + } +} + +fn wired(root: PathBuf) -> (Harness, egui::Context) { + let mut app = Harness::new(); + app.cloud.connect(LocalBackend::new(root)); + (app, egui::Context::default()) +} + +/// Drains whatever the backend's worker threads have sent so far, until `done` says the state +/// the test is waiting for arrived or five seconds pass. Five seconds is far more than a thread +/// doing local file IO ever needs; it only guards against a real bug leaving the test to hang. +fn settle(app: &mut Harness, ctx: &egui::Context, mut done: impl FnMut(&Harness) -> bool) { + let start = Instant::now(); + loop { + ctx.begin_pass(Default::default()); + cloud::pump(app, ctx); + ctx.end_pass().textures_delta.clear(); + if done(app) { + return; + } + assert!(start.elapsed() < Duration::from_secs(5), "timed out waiting for the backend's worker thread"); + std::thread::sleep(Duration::from_millis(5)); + } +} + +/// Clears both event sinks, then waits for the next job to land in either one. Clearing first +/// matters for a test that submits several jobs in a loop: without it, a stale `said` from two +/// iterations ago would satisfy `settle` immediately, before the new job had actually answered. +fn said(app: &mut Harness, ctx: &egui::Context) -> Vec { + app.opened.lock().unwrap().clear(); + app.said.lock().unwrap().clear(); + settle(app, ctx, |app| !app.said.lock().unwrap().is_empty() || !app.opened.lock().unwrap().is_empty()); + app.said.lock().unwrap().clone() +} + +/// A tempdir holding the cloud root, plus a sentinel file and a sentinel directory that sit +/// beside it rather than inside it. Every test below must leave both exactly as they start. +struct Sentinels { + // Kept only so the tempdir outlives every test that borrows the paths below; nothing reads + // it back once the paths it was built from are in hand. + _arena: tempfile::TempDir, + root: PathBuf, + sentinel_file: PathBuf, + sentinel_dir: PathBuf, +} + +const SENTINEL_FILE_BYTES: &[u8] = b"a sibling file this backend must never read or write"; +const SENTINEL_DIR_FILE_BYTES: &[u8] = b"a sibling directory this backend must never list"; + +fn sentinels() -> Sentinels { + let arena = tempfile::tempdir().unwrap(); + let root = arena.path().join("root"); + std::fs::create_dir(&root).unwrap(); + let sentinel_file = arena.path().join("sentinel.txt"); + std::fs::write(&sentinel_file, SENTINEL_FILE_BYTES).unwrap(); + let sentinel_dir = arena.path().join("sentinel-dir"); + std::fs::create_dir(&sentinel_dir).unwrap(); + std::fs::write(sentinel_dir.join("secret.txt"), SENTINEL_DIR_FILE_BYTES).unwrap(); + Sentinels { _arena: arena, root, sentinel_file, sentinel_dir } +} + +fn assert_sentinels_untouched(sentinels: &Sentinels) { + assert_eq!(std::fs::read(&sentinels.sentinel_file).unwrap(), SENTINEL_FILE_BYTES, "the sentinel file outside the root was changed"); + assert_eq!( + std::fs::read(sentinels.sentinel_dir.join("secret.txt")).unwrap(), + SENTINEL_DIR_FILE_BYTES, + "the sentinel directory's file outside the root was changed" + ); +} + +/// Every one of these is a [`Job::Create`] `name` that must be refused before any byte reaches +/// disk: the review's own examples (a parent segment, an absolute path, and the three +/// Windows-shaped forms), none of which a Unix build's native parser alone would catch, and a +/// name that already is nothing but a Windows separator or drive prefix on top of that. +fn malicious_create_names() -> Vec<&'static str> { + vec!["../sentinel.txt", "/sentinel.txt", "..\\sentinel.txt", "C:\\x", "C:evil", "\\\\server\\share\\x"] +} + +#[test] +fn create_refuses_every_escaping_name_and_the_sentinels_stay_untouched() { + for name in malicious_create_names() { + let sentinels = sentinels(); + let (mut app, ctx) = wired(sentinels.root.clone()); + + cloud::submit(&app, Job::Create { uid: 1, folder: String::new(), name: name.to_owned(), bytes: b"pwned".to_vec() }); + let messages = said(&mut app, &ctx); + + assert!(cloud::origin(&app).is_none(), "{name:?} must not be reported as created"); + assert!(!messages.is_empty(), "{name:?} must be refused, not silently dropped"); + assert_sentinels_untouched(&sentinels); + } +} + +// ------------------------------------------------------------------- link-based escapes +// +// `escape(&sentinels)` places one link named `escape` inside the cloud root, pointing out to +// `sentinels.sentinel_dir`: a symlink on Unix, a directory junction on Windows, which needs no +// elevated privilege, unlike a Windows symlink. The Linux gate runs the symlink half of every +// test below; CI's windows-latest lanes run the junction half. Either way `root/escape/...` +// reaches into the sentinel directory through the link. + +/// Nothing to clean up on Unix: `tempfile`'s own recursive removal of the arena directory +/// removes a plain symlink entry without following it. This exists only so `escape` returns the +/// same shape of RAII handle on every platform, rather than a bare `()` some lint would flag. +#[cfg(unix)] +struct Linked; + +#[cfg(unix)] +fn escape(sentinels: &Sentinels) -> Linked { + std::os::unix::fs::symlink(&sentinels.sentinel_dir, sentinels.root.join("escape")).unwrap(); + Linked +} + +/// A directory junction, removed on drop before the tempdir it sits beside is cleaned up. +#[cfg(windows)] +struct Junction(PathBuf); + +#[cfg(windows)] +impl Drop for Junction { + fn drop(&mut self) { + let _ = std::fs::remove_dir(&self.0); + } +} + +#[cfg(windows)] +fn escape(sentinels: &Sentinels) -> Junction { + use std::os::windows::process::CommandExt as _; + let link = sentinels.root.join("escape"); + let target = &sentinels.sentinel_dir; + assert!(link.is_absolute() && target.is_absolute()); + let output = std::process::Command::new("cmd") + .args(["/C", "mklink", "/J"]) + .arg(&link) + .arg(target) + .creation_flags(0x0800_0000) // CREATE_NO_WINDOW + .output() + .unwrap(); + assert!(output.status.success(), "{}", String::from_utf8_lossy(&output.stderr)); + Junction(link) +} + +/// An [`Entry`] stub naming `id`, for a [`Job::Read`] or [`Job::Write`] this file submits +/// directly rather than through an entry the backend itself handed back. +fn leaked_entry(id: &str, name: &str) -> Entry { + Entry { + id: id.to_owned(), + room: format!("local:{id}"), + name: name.to_owned(), + path: id.to_owned(), + kind: EntryKind::File, + size: None, + modified: None, + mime: None, + etag: None, + writable: true, + shared_by: None, + } +} + +#[cfg(any(unix, windows))] +#[test] +fn listing_a_linked_folder_cannot_see_outside_the_root() { + let sentinels = sentinels(); + let (mut app, ctx) = wired(sentinels.root.clone()); + let _escape = escape(&sentinels); + + cloud::browse(&mut app, "escape"); + settle(&mut app, &ctx, |app| app.cloud().mine.loaded); + + assert!(app.cloud().mine.error.is_some(), "listing through a symlink or junction out of the root must be refused"); + assert!(app.cloud().mine.entries.is_empty()); + assert_sentinels_untouched(&sentinels); +} + +#[cfg(any(unix, windows))] +#[test] +fn reading_through_a_linked_folder_cannot_return_bytes_from_outside_the_root() { + let sentinels = sentinels(); + let (mut app, ctx) = wired(sentinels.root.clone()); + let _escape = escape(&sentinels); + + cloud::submit(&app, Job::Read { entry: leaked_entry("/escape/secret.txt", "secret.txt"), into: None }); + said(&mut app, &ctx); + + assert!(app.opened.lock().unwrap().is_empty(), "a read through a symlink or junction out of the root must not deliver bytes"); + assert_sentinels_untouched(&sentinels); +} + +/// benandez's finding 4: the original version of this test targeted the pre-existing +/// `secret.txt`, with `etag: None`. `write` refused that for an unrelated reason, a version +/// mismatch, before confinement ever ran, so the test passed whether or not confinement worked. +/// Targeting a name that does not exist yet under the link reaches the code that actually +/// matters, and the oracle (the file must never be created) is one confinement failing would +/// actually flip. +#[cfg(any(unix, windows))] +#[test] +fn writing_through_a_linked_folder_cannot_create_a_file_outside_the_root() { + let sentinels = sentinels(); + let (mut app, ctx) = wired(sentinels.root.clone()); + let _escape = escape(&sentinels); + + cloud::submit(&app, Job::Write { uid: 1, entry: leaked_entry("/escape/not-yet-created.txt", "not-yet-created.txt"), bytes: b"pwned".to_vec() }); + said(&mut app, &ctx); + + assert!(!sentinels.sentinel_dir.join("not-yet-created.txt").exists(), "a write through a link must not create a file outside the root"); + assert_sentinels_untouched(&sentinels); +} + +/// benandez's finding 5: nothing previously exercised a link in the `folder` a `Create` targets. +#[cfg(any(unix, windows))] +#[test] +fn creating_through_a_linked_folder_cannot_create_a_file_outside_the_root() { + let sentinels = sentinels(); + let (mut app, ctx) = wired(sentinels.root.clone()); + let _escape = escape(&sentinels); + + cloud::submit(&app, Job::Create { uid: 1, folder: "escape".to_owned(), name: "new.txt".to_owned(), bytes: b"pwned".to_vec() }); + let messages = said(&mut app, &ctx); + + assert!(cloud::origin(&app).is_none(), "a create into a linked folder must not be reported as created"); + assert!(!messages.is_empty(), "a create into a linked folder must be refused, not silently dropped"); + assert!(!sentinels.sentinel_dir.join("new.txt").exists(), "a create through a link must not create a file outside the root"); + assert_sentinels_untouched(&sentinels); +} + +// ------------------------------------------------------------------- Unix-only reproductions +// +// Directory junctions cannot be dangling (`mklink /J` requires the target to exist) and the +// race and hard-link reproductions below are exactly benandez's own repros, run on Linux only, +// as stated in that review. The structural fix (resolving through a `cap_std::fs::Dir`, and +// writing through a temporary file and rename) is the same code on every platform; these three +// just do not have a Windows-shaped equivalent worth a separate repro. + +/// benandez's finding 1, reproduced exactly: `root/doc.txt` is a symlink to a file that does not +/// exist yet, outside the root. The old code's `confine_to_root` canonicalised the dangling link +/// to `NotFound`, walked up to `root`, accepted it, found no file to conflict with, and `write` +/// created the target for real, outside the root. +#[cfg(unix)] +#[test] +fn writing_through_a_dangling_symlink_cannot_create_a_file_outside_the_root() { + let sentinels = sentinels(); + let outside_target = sentinels._arena.path().join("outside-planted.txt"); + std::os::unix::fs::symlink(&outside_target, sentinels.root.join("doc.txt")).unwrap(); + let (mut app, ctx) = wired(sentinels.root.clone()); + + cloud::submit(&app, Job::Write { uid: 1, entry: leaked_entry("/doc.txt", "doc.txt"), bytes: b"pwned".to_vec() }); + said(&mut app, &ctx); + + assert!(!outside_target.exists(), "a write through a dangling symlink must not create its target outside the root"); + assert_sentinels_untouched(&sentinels); +} + +/// benandez's finding 3, reproduced exactly: `root/hl` is a hard link sharing an inode with a +/// file outside the root. Reading it through the backend is legitimate (it is, from inside the +/// sandbox, an ordinary file), which is also how this test gets a real, matching etag to write +/// with, the same way a real caller would after opening the document. The old code's `write` +/// truncated the shared inode in place; `write_replacing` must instead replace `hl`'s own +/// directory entry, leaving the sentinel file's inode, and its other name, untouched. +#[cfg(unix)] +#[test] +fn writing_through_a_hard_link_replaces_the_entry_without_touching_the_shared_file() { + let sentinels = sentinels(); + std::fs::hard_link(&sentinels.sentinel_file, sentinels.root.join("hl")).unwrap(); + let (mut app, ctx) = wired(sentinels.root.clone()); + + cloud::submit(&app, Job::Read { entry: leaked_entry("/hl", "hl"), into: None }); + settle(&mut app, &ctx, |app| !app.opened.lock().unwrap().is_empty()); + let real_entry = app.cloud().origins.get(&1).expect("the read registered an origin for uid 1").entry.clone(); + + // A successful write answers through `cloud.status`, not through `said` or `opened`, so it + // needs its own wait condition rather than the `said` helper used everywhere else in this + // file for a refusal. The read above already set `status` once (`Opened hl from the + // cloud.`), so that has to be cleared first or this would observe the read's own status and + // never actually wait for the write to finish. + app.cloud_mut().status = None; + cloud::submit(&app, Job::Write { uid: 1, entry: real_entry, bytes: b"replaced via rename, not truncated in place".to_vec() }); + settle(&mut app, &ctx, |app| app.cloud().status.is_some() || app.cloud().conflict.is_some() || !app.said.lock().unwrap().is_empty()); + assert!(app.cloud().conflict.is_none(), "the write through the hard-linked name should succeed, not conflict"); + assert!( + app.said.lock().unwrap().is_empty(), + "the write through the hard-linked name should succeed, not be refused: {:?}", + app.said.lock().unwrap() + ); + + assert_eq!( + std::fs::read(sentinels.root.join("hl")).unwrap(), + b"replaced via rename, not truncated in place", + "the write through the hard-linked name should still succeed" + ); + assert_sentinels_untouched(&sentinels); +} + +/// benandez's finding 2, reproduced at a smaller scale: a background thread swaps `root/d` +/// between a symlink into an inside folder and a symlink to the sentinel directory, as fast as +/// it can, with no coordination with the reads below. The old code's `confine_to_root` checked +/// one path string and then `fs::read` resolved that path again, a second, later lookup a swap +/// could land in between; out of 3000 such reads benandez's own run returned the outside file's +/// bytes 347 times. `cap_std::fs::Dir::open` resolves and opens `d` as one operation with no +/// such second lookup, so this must come back empty every time, not merely most of the time. +#[cfg(unix)] +#[test] +fn reading_through_a_link_being_swapped_never_observes_the_outside_target() { + use std::sync::atomic::{AtomicBool, Ordering}; + + let sentinels = sentinels(); + let inside = sentinels.root.join("inside"); + std::fs::create_dir(&inside).unwrap(); + std::fs::write(inside.join("secret.txt"), b"inside bytes, always safe to read").unwrap(); + let link = sentinels.root.join("d"); + std::os::unix::fs::symlink(&inside, &link).unwrap(); + + let stop = Arc::new(AtomicBool::new(false)); + let swapper = { + let stop = stop.clone(); + let link = link.clone(); + let outside = sentinels.sentinel_dir.clone(); + std::thread::spawn(move || { + let temp = link.with_extension("swap"); + let mut toward_outside = false; + while !stop.load(Ordering::Relaxed) { + let target = if toward_outside { &outside } else { &inside }; + // A stale `temp` from a rename that did not happen (should not occur, but a + // leftover `temp` would otherwise wedge every later iteration's `symlink` call, + // silently stopping the swap rather than failing the test loudly) is cleared + // first so this loop cannot get stuck. + let _ = std::fs::remove_file(&temp); + if std::os::unix::fs::symlink(target, &temp).is_ok() { + let _ = std::fs::rename(&temp, &link); + } + toward_outside = !toward_outside; + } + }) + }; + + let (mut app, ctx) = wired(sentinels.root.clone()); + let mut leaked = false; + for _ in 0..200 { + cloud::submit(&app, Job::Read { entry: leaked_entry("/d/secret.txt", "secret.txt"), into: None }); + said(&mut app, &ctx); + if let Some((_, bytes)) = app.opened.lock().unwrap().first() { + leaked |= bytes.as_slice() == SENTINEL_DIR_FILE_BYTES; + } + } + + stop.store(true, Ordering::Relaxed); + swapper.join().unwrap(); + + assert!(!leaked, "a read observed the outside target's bytes while the link was being swapped underneath it"); + assert_sentinels_untouched(&sentinels); +} diff --git a/crates/cloud-local/tests/save_path_regressions.rs b/crates/cloud-local/tests/save_path_regressions.rs new file mode 100644 index 000000000..76cec678a --- /dev/null +++ b/crates/cloud-local/tests/save_path_regressions.rs @@ -0,0 +1,160 @@ +//! Two save-path defects that need a real backend to show: a reload after a conflict carrying a +//! stale etag into the next save, and two creates of the same name racing past an exists check. +//! Driven through craft_ui::cloud's public functions the way an application does. + +use std::sync::{Arc, Mutex}; +use std::time::{Duration, Instant}; + +use craft_cloud::{Entry, EntryKind}; +use craft_cloud_local::LocalBackend; +use craft_ui::cloud::{self, CloudApp, CloudFiles, Destination, DocumentKind}; + +const NOTE: DocumentKind = DocumentKind { extensions: &["txt"], mimes: &["text/plain"], noun: "note", default_extension: "txt" }; + +struct Window { + cloud: CloudFiles, + share: craft_ui::share::ShareDialog, + presence: craft_ui::presence::PresenceBar, + body: Vec, + said: Arc>>, +} + +impl Window { + fn new(root: std::path::PathBuf, body: &[u8]) -> Window { + let mut w = Window { + cloud: CloudFiles::new(), + share: craft_ui::share::ShareDialog::new(), + presence: craft_ui::presence::PresenceBar::new(), + body: body.to_vec(), + said: Arc::default(), + }; + w.cloud.connect(LocalBackend::new(root)); + w + } +} + +impl CloudApp for Window { + fn cloud(&self) -> &CloudFiles { + &self.cloud + } + fn cloud_mut(&mut self) -> &mut CloudFiles { + &mut self.cloud + } + fn kind(&self) -> DocumentKind { + NOTE + } + fn active(&self) -> Option { + Some(1) + } + fn title(&self, _uid: u64) -> String { + String::new() + } + fn open_bytes(&mut self, _name: &str, bytes: Vec) -> Result, String> { + self.body = bytes; + Ok(Some(1)) + } + fn encode(&mut self, _uid: u64, _into: Destination<'_>) -> Result, String> { + Ok(self.body.clone()) + } + fn close(&mut self, _uid: u64) {} + fn sharing(&mut self) -> &mut craft_ui::share::ShareDialog { + &mut self.share + } + fn presence(&mut self) -> &mut craft_ui::presence::PresenceBar { + &mut self.presence + } + fn paint_icon(&self, _p: &egui::Painter, _r: egui::Rect, _k: EntryKind, _c: egui::Color32) {} + fn open_url(&self, _url: &str) {} + fn say(&mut self, text: String) { + self.said.lock().unwrap().push(text); + } + fn app_name(&self) -> &str { + "Review" + } +} + +fn settle(app: &mut Window, ctx: &egui::Context, mut done: impl FnMut(&Window) -> bool) { + let start = Instant::now(); + loop { + ctx.begin_pass(Default::default()); + cloud::pump(app, ctx); + ctx.end_pass().textures_delta.clear(); + if done(app) { + return; + } + assert!(start.elapsed() < Duration::from_secs(5), "timed out"); + std::thread::sleep(Duration::from_millis(2)); + } +} + +fn listed(app: &mut Window, ctx: &egui::Context, name: &str) -> Entry { + cloud::browse(app, ""); + settle(app, ctx, |a| a.cloud.mine.loaded); + app.cloud.mine.entries.iter().find(|e| e.name == name).cloned().expect("listed") +} + +/// Open v1, another writer stores v2, Save conflicts, the user picks "Reload from the cloud" +/// (`reload_active`, what the modal calls). The window now shows v2's bytes, so the next Save +/// must go through rather than conflict again on the etag the reloaded copy was read at. +#[test] +fn reload_after_a_conflict_carries_the_freshly_read_etag_so_the_next_save_succeeds() { + let root = tempfile::tempdir().unwrap(); + std::fs::write(root.path().join("note.txt"), b"v1").unwrap(); + let ctx = egui::Context::default(); + let mut app = Window::new(root.path().to_owned(), b""); + let v1 = listed(&mut app, &ctx, "note.txt"); + cloud::open_entry(&mut app, v1.clone(), None); + settle(&mut app, &ctx, |a| a.cloud.busy.is_none() && a.body == b"v1"); + + std::thread::sleep(Duration::from_millis(20)); + std::fs::write(root.path().join("note.txt"), b"v2 by someone else").unwrap(); + + app.body = b"my edit".to_vec(); + cloud::save(&mut app).unwrap(); + settle(&mut app, &ctx, |a| a.cloud.busy.is_none()); + assert!(app.cloud.conflict.is_some(), "the first save is refused (correct)"); + + cloud::reload_active(&mut app).unwrap(); + settle(&mut app, &ctx, |a| a.cloud.busy.is_none()); + assert_eq!(app.body, b"v2 by someone else", "reload shows the stored bytes"); + let origin_etag = cloud::report(&app)["origin"]["etag"].clone(); + + cloud::save(&mut app).unwrap(); + settle(&mut app, &ctx, |a| a.cloud.busy.is_none()); + let on_disk = std::fs::read(root.path().join("note.txt")).unwrap(); + assert!( + app.cloud.conflict.is_none(), + "after reloading v2 the save conflicted again: origin etag after reload = {origin_etag} \ + (listing etag was {:?}); file on disk = {:?}", + v1.etag, + String::from_utf8_lossy(&on_disk) + ); +} + +/// Two windows Save As the same new name at once. At most one create may succeed; the other +/// must be refused ("already exists") rather than both reporting success while one silently +/// replaces the other on disk. +#[test] +fn concurrent_create_of_one_name_refuses_the_loser() { + let rounds = 300; + let (mut both_ok, mut example) = (0, String::new()); + for round in 0..rounds { + let root = tempfile::tempdir().unwrap(); + let ctx = egui::Context::default(); + let mut a = Window::new(root.path().to_owned(), format!("window A round {round}").as_bytes()); + let mut b = Window::new(root.path().to_owned(), format!("window B round {round}").as_bytes()); + cloud::save_as(&mut a, "", "Report.txt").unwrap(); + cloud::save_as(&mut b, "", "Report.txt").unwrap(); + settle(&mut a, &ctx, |w| w.cloud.busy.is_none()); + settle(&mut b, &ctx, |w| w.cloud.busy.is_none()); + let (a_ok, b_ok) = (cloud::origin(&a).is_some(), cloud::origin(&b).is_some()); + if a_ok && b_ok { + both_ok += 1; + if example.is_empty() { + let disk = std::fs::read_to_string(root.path().join("Report.txt")).unwrap(); + example = format!("round {round}: A status {:?}, B status {:?}, file holds {disk:?}", a.cloud.status, b.cloud.status); + } + } + } + assert_eq!(both_ok, 0, "{both_ok}/{rounds} rounds: both windows were told the new file was created; e.g. {example}"); +} diff --git a/crates/cloud-ui/Cargo.toml b/crates/cloud-ui/Cargo.toml new file mode 100644 index 000000000..21dab37ab --- /dev/null +++ b/crates/cloud-ui/Cargo.toml @@ -0,0 +1,38 @@ +[package] +name = "craft-cloud-ui" +version.workspace = true +edition.workspace = true +license.workspace = true +repository.workspace = true +rust-version.workspace = true +description = "Share dialog, cloud Open and Save pages, account menu and presence bar for Craft apps, on egui" + +[lints] +workspace = true + +[dependencies] +egui = { workspace = true } +# The vendor-neutral vocabulary the share and e-sign dialogs speak. No IO and +# no vendor, so this stays buildable for the web. +craft-cloud = { workspace = true, optional = true } +# The e-sign contract the request-signatures dialog states its work through. +craft-esign = { workspace = true, optional = true } +# The control channel's report of the cloud state. One serialiser here +# rather than one per application. No IO and no vendor. +serde_json = { workspace = true, optional = true } + +[features] +default = [] +# The share dialog and the backend contract it states its work through. +share = ["dep:craft-cloud"] +# Open and Save against cloud storage. Needs the share dialog, which a +# document's overflow menu and the Share split button both open. +cloud = ["share", "dep:serde_json"] +# Request-signatures dialog. +esign = ["dep:craft-cloud", "dep:craft-esign"] + +[dev-dependencies] +image = { version = "0.25", default-features = false, features = ["png"] } + +[target.'cfg(not(target_arch = "wasm32"))'.dev-dependencies] +egui_kittest = { version = "0.37", features = ["wgpu"] } diff --git a/crates/cloud-ui/README.md b/crates/cloud-ui/README.md new file mode 100644 index 000000000..9bde8feb5 --- /dev/null +++ b/crates/cloud-ui/README.md @@ -0,0 +1,67 @@ +# craft-cloud-ui + +The share dialog, the cloud Open and Save pages, the account menu and the presence bar that every +Craft app shares. This is storytold main's cloud and share UI as main wrote it in craft-ui: raw egui, +outside the craft UI library's component contract, to be ported onto the framework's components. The +`craft-ui` facade re-exports `account`, `cloud`, `share` and `presence` from here behind the same +`share` and `cloud` features. + +## Sharing + +`share::ShareDialog` is a whole dialog. It holds a recipient picker with autocomplete and +removable chips. It offers a view-or-edit choice, a note and a notify-by-email box. Under those it +lists who already has access, with a withdrawal beside each entry. Every Craft app gets the same +dialog. An application's own part comes to three lines. + +```rust +// Once, at startup. The host supplies the half that reaches the service. +app.share.connect(my_backend); + +// Every frame, open or shut. This is also where answers are collected. +app.share.show(ctx); + +// From the app's Share control, drawn only while `available()` is true. +if app.share.available() && share_button.clicked() { + app.share.open(entry.id.clone(), entry.name.clone()); +} +``` + +The dialog opens no socket, names no provider and holds no credential. It states each piece of +work as a `share::Request` and hands it to a `share::ShareBackend`. That backend answers through a +`share::Replier` whenever it is ready. Nothing in this crate implements that trait. A host writes +the half that opens a socket, and this crate never learns what it reaches. The interface half +therefore builds for the web, and every flow is testable with no server running. + +Autocomplete waits `share::DEBOUNCE` after the last keystroke before it asks anything. An answer +to a query the user has already typed past is dropped before it reaches the list. A list that +flickers back to stale matches is worse than one that arrives late. + +Partial success is rendered as partial success. A share aimed at five people with one wrong +address reaches four. The dialog names the fifth with the reason the service gave. It keeps that +one recipient in the picker. A correction then takes one edit. `outcome()` hands back both halves. + +Capability is reported and never assumed. `available()` stays false until the service says the +provider supports sharing and an account is linked. `open` does nothing while it is false. An +application draws no Share control in that state. A hidden feature beats a button that fails on +use. Contacts and mail are reported separately. A server with no address book accepts typed +addresses only. A server that cannot send mail disables the notify box and says why. +`ShareLabels` holds every string the dialog shows. The defaults are English. A localized +application replaces them without touching this crate. + +A contact's `avatar` is a URL. The dialog asks for the bytes through the same backend, as the row +that needs the picture is painted and only while that row is on screen. A search answering with +ten people costs no pictures until somebody looks at them. Each URL is asked about once. A refusal +is remembered, with initials painted in its place. The host decides whether a picture may be +fetched at all. A backend that refuses `share::Request::Avatar` gets initials painted instead, and +a host that would rather not have an application reach a provider's avatar URL directly can say +so by refusing it. A host that relays pictures answers it. Nothing else changes. + +### The account + +`account::AccountMenu` is the badge every suite puts in the top right. It shows who is signed in, +where they are signed in, and whether storage is linked. It holds no credential. It asks the +service who the caller is, through the application. It reports what the user asked for through +`take_action`. The application owns what signing in means. + +Without linked storage, Open and Save have nowhere to go. The menu says so at rest. A failure at +the moment of saving arrives too late to be useful. diff --git a/crates/cloud-ui/src/account.rs b/crates/cloud-ui/src/account.rs new file mode 100644 index 000000000..9c8921064 --- /dev/null +++ b/crates/cloud-ui/src/account.rs @@ -0,0 +1,449 @@ +//! Who is signed in, which account is in use, and how to stop being signed in. +//! +//! Every office suite puts this in the same place, for the same reason. A +//! document is about to be saved somewhere and shared with somebody. The +//! account decides both the destination and the identity. An application that +//! never shows it leaves the user guessing which of their identities is in +//! play. +//! +//! A person commonly holds more than one. A work account and a personal one +//! are two different places to save, with two different sets of colleagues to +//! share with, and confusing them is the expensive mistake this control exists +//! to prevent. So the control holds a list and marks which one is in use. +//! +//! This holds no credential. It asks the service who the caller is and shows +//! the answer. A sign-out makes the service forget the session. + +use std::sync::mpsc::{Receiver, Sender, channel}; + +use egui::{Align, Context, Layout, RichText, Ui}; + +/// One account the user is signed in to. +#[derive(Clone, Debug, Default, PartialEq, Eq)] +pub struct Account { + /// How the service names this account. Never shown. + pub id: String, + /// What to show. A display name, never an identity. + pub display: String, + pub email: Option, + /// Where they are signed in, such as the service's host. Shown because + /// somebody with accounts on two deployments needs to tell them apart. + pub service: String, + /// Whether storage is linked. Without it Open and Save have nowhere to go, + /// and saying so here is kinder than a failure at the moment of saving. + pub linked: bool, +} + +impl Account { + pub fn new(id: impl Into, display: impl Into) -> Account { + Account { id: id.into(), display: display.into(), ..Account::default() } + } + + /// The letter on the badge. The first character of the display name, which + /// is what every suite uses and what people recognise at that size. + pub fn initial(&self) -> String { + self.display.chars().next().map(|c| c.to_uppercase().to_string()).unwrap_or_else(|| "?".to_owned()) + } +} + +/// What the menu asks the application to do. +/// +/// Each one names the account it is about. A control that said only "sign out" +/// would be ambiguous the moment somebody held two. +#[derive(Clone, Debug, PartialEq, Eq)] +pub enum AccountAction { + /// Begin a sign-in with nobody signed in yet. + SignIn, + /// Add another account alongside the ones already here. + AddAccount, + /// Work as this account from now on. + Use(String), + /// End this account's session, at the service and here. + SignOut(String), + /// Connect storage for an account that has none. + Link(String), + /// Open the service's own page for this account. + Manage(String), +} + +/// Strings, so an application can translate them. +#[derive(Clone, Debug)] +pub struct AccountLabels { + pub signed_out: String, + pub sign_in: String, + pub sign_out: String, + pub add_account: String, + pub other_accounts: String, + pub link: String, + pub linked: String, + pub not_linked: String, + pub manage: String, + pub working: String, + /// The badge's accessible name. `{name}` is replaced. + /// + /// A button announcing only a person's name says nothing about what + /// pressing it does, and collides with every other place that name is + /// written. + pub badge: String, + /// Shown when accounts are signed in and none is in use. + pub choose: String, + /// Why that happened, since a person who did not sign out needs telling. + pub choose_why: String, +} + +impl Default for AccountLabels { + fn default() -> AccountLabels { + AccountLabels { + signed_out: "Not signed in".into(), + sign_in: "Sign in".into(), + sign_out: "Sign out".into(), + add_account: "Add an account".into(), + other_accounts: "Other accounts".into(), + link: "Connect storage".into(), + linked: "Storage connected".into(), + not_linked: "No storage connected".into(), + manage: "Account settings".into(), + working: "Working\u{2026}".into(), + badge: "Account, {name}".into(), + choose: "Choose an account".into(), + choose_why: "The account you were using is no longer signed in.".into(), + } + } +} + +/// The account badge and its menu. +pub struct AccountMenu { + accounts: Vec, + /// Which account the application is working as. Held by id rather than by + /// index, since the list is replaced wholesale whenever the service answers. + active: Option, + labels: AccountLabels, + /// Set while a sign-in or sign-out is in flight, so the control says so + /// rather than looking unresponsive. + busy: bool, + /// Whether the host can hold more than one account at once. + /// + /// Off until a host says otherwise. An application that keeps one + /// session would otherwise draw an Add an account that signs the user + /// in again as the account they are already using, which reads as a + /// button that does nothing. + more_allowed: bool, + actions: (Sender, Receiver), +} + +impl Default for AccountMenu { + fn default() -> AccountMenu { + AccountMenu::new() + } +} + +impl AccountMenu { + pub fn new() -> AccountMenu { + AccountMenu { accounts: Vec::new(), active: None, labels: AccountLabels::default(), busy: false, more_allowed: false, actions: channel() } + } + + pub fn with_labels(mut self, labels: AccountLabels) -> AccountMenu { + self.labels = labels; + self + } + + /// Say that this host can hold more than one account at once. + /// + /// Until a host says so, the menu offers no way to add one. Signing in + /// again as the account already in use is not an action worth drawing. + pub fn allowing_more(mut self) -> AccountMenu { + self.more_allowed = true; + self + } + + /// Replace the whole set of accounts. + /// + /// Wholesale rather than one at a time. A session that missed a sign-out + /// elsewhere would otherwise keep offering an account that is gone. + /// + /// The account in use is kept when it is still in the list. + /// + /// When it has gone, nothing takes its place. A work session that expires + /// would otherwise hand the next save, share and open to a personal + /// account without saying so, and sending a document to the wrong tenant + /// is not a mistake a person can take back. The control asks instead. + /// + /// The first account is chosen only when none was in use at all, which is + /// the first sign-in. + pub fn set(&mut self, accounts: Vec) { + let chose_before = self.active.is_some(); + let kept = self.active.take().filter(|id| accounts.iter().any(|a| a.id == *id)); + self.active = match kept { + Some(id) => Some(id), + None if chose_before => None, + None => accounts.first().map(|a| a.id.clone()), + }; + self.accounts = accounts; + self.busy = false; + } + + /// Work as this account. Ignored for an account that is not here. + pub fn set_active(&mut self, id: &str) { + if self.accounts.iter().any(|a| a.id == id) { + self.active = Some(id.to_owned()); + } + } + + pub fn active(&self) -> Option<&Account> { + let id = self.active.as_deref()?; + self.accounts.iter().find(|a| a.id == id) + } + + pub fn accounts(&self) -> &[Account] { + &self.accounts + } + + pub fn is_signed_in(&self) -> bool { + !self.accounts.is_empty() + } + + /// Mark something as in flight. Cleared by the next [`AccountMenu::set`]. + pub fn working(&mut self) { + self.busy = true; + } + + /// What the user asked for since the last call, if anything. + /// + /// Drained rather than handed a callback, so the application acts on its + /// own thread and this stays free of any notion of what signing in means. + pub fn take_action(&mut self) -> Option { + self.actions.1.try_recv().ok() + } + + /// Draw the badge. Put it where the window's own controls are. + pub fn show(&mut self, ui: &mut Ui) { + let tx = self.actions.0.clone(); + let labels = self.labels.clone(); + let busy = self.busy; + + let Some(account) = self.active().cloned() else { + // Nobody signed in, or signed in with the account that was in use + // now gone. The two read differently. One offers a sign-in. The + // other has accounts to offer and must say so, since saving has + // nowhere to go until somebody picks one. + if self.accounts.is_empty() { + let label = if busy { labels.working.as_str() } else { labels.sign_in.as_str() }; + if ui.add_enabled(!busy, egui::Button::new(label).small()).clicked() { + let _ = tx.send(AccountAction::SignIn); + } + return; + } + let waiting = self.accounts.clone(); + let hit = ui.add_enabled(!busy, egui::Button::new(labels.choose.as_str()).small()); + egui::Popup::menu(&hit).show(|ui| { + ui.set_min_width(240.0); + ui.label(RichText::new(labels.choose_why.as_str()).small().color(ui.visuals().warn_fg_color)); + ui.separator(); + for one in &waiting { + let label = format!("{}\n{}", one.display, one.service); + let row = ui.add(egui::Button::new(label).wrap_mode(egui::TextWrapMode::Extend)); + let name = one.display.clone(); + row.widget_info(|| egui::WidgetInfo::labeled(egui::Role::Button, true, name.as_str())); + if row.clicked() { + let _ = tx.send(AccountAction::Use(one.id.clone())); + ui.close(); + } + } + ui.add_space(4.0); + if ui.button(labels.sign_in.as_str()).clicked() { + let _ = tx.send(AccountAction::SignIn); + ui.close(); + } + }); + return; + }; + + let others: Vec = self.accounts.iter().filter(|a| a.id != account.id).cloned().collect(); + let more_allowed = self.more_allowed; + let badge = egui::Button::new(RichText::new(account.initial()).strong()).min_size(egui::vec2(26.0, 26.0)).corner_radius(13.0); + let hit = ui.add(badge); + let spoken = labels.badge.replace("{name}", &account.display); + hit.widget_info(|| egui::WidgetInfo::labeled(egui::Role::Button, true, spoken.as_str())); + let hit = hit.on_hover_text(account.display.as_str()); + + egui::Popup::menu(&hit).show(|ui| { + ui.set_min_width(260.0); + // The deployment first, because somebody with an account on two of + // them needs to know which one this is before reading anything + // else. + ui.horizontal(|ui| { + ui.label(RichText::new(account.service.as_str()).small().color(ui.visuals().weak_text_color())); + ui.with_layout(Layout::right_to_left(Align::Center), |ui| { + if ui.small_button(labels.sign_out.as_str()).clicked() { + let _ = tx.send(AccountAction::SignOut(account.id.clone())); + ui.close(); + } + }); + }); + ui.separator(); + + ui.horizontal(|ui| { + ui.label(RichText::new(account.initial()).size(26.0).strong()); + ui.vertical(|ui| { + ui.label(RichText::new(account.display.as_str()).strong().size(15.0)); + if let Some(email) = &account.email { + ui.label(RichText::new(email.as_str()).small().color(ui.visuals().weak_text_color())); + } + }); + }); + + ui.add_space(6.0); + + // Storage, which is the thing that actually stops working when it + // is missing. Said here rather than discovered at the moment of + // saving. + if account.linked { + ui.label(RichText::new(labels.linked.as_str()).small().color(ui.visuals().weak_text_color())); + } else { + ui.label(RichText::new(labels.not_linked.as_str()).small().color(ui.visuals().warn_fg_color)); + if ui.button(labels.link.as_str()).clicked() { + let _ = tx.send(AccountAction::Link(account.id.clone())); + ui.close(); + } + } + + if !others.is_empty() { + ui.add_space(6.0); + ui.separator(); + ui.label(RichText::new(labels.other_accounts.as_str()).small().color(ui.visuals().weak_text_color())); + for other in &others { + // Both lines in one control. A name above a subtitle, where + // only the name answers a press, makes half the row look + // broken to anybody who aims at the wrong half. The + // deployment is on the second line because two accounts + // both reading "Will Dunn" tell nobody which is the work + // one. + let label = format!("{}\n{}", other.display, other.service); + let row = ui.add(egui::Button::new(label).wrap_mode(egui::TextWrapMode::Extend)); + let name = other.display.clone(); + row.widget_info(|| egui::WidgetInfo::labeled(egui::Role::Button, true, name.as_str())); + if row.clicked() { + let _ = tx.send(AccountAction::Use(other.id.clone())); + ui.close(); + } + } + } + + if more_allowed { + ui.add_space(6.0); + if ui.button(labels.add_account.as_str()).clicked() { + let _ = tx.send(AccountAction::AddAccount); + ui.close(); + } + } + + ui.add_space(4.0); + if ui.link(labels.manage.as_str()).clicked() { + let _ = tx.send(AccountAction::Manage(account.id.clone())); + ui.close(); + } + }); + } + + /// Draw the badge in a context that has no `Ui` to hand. + pub fn show_in_ctx(&mut self, ctx: &Context) { + egui::Area::new(egui::Id::unique("craft-ui/account")).anchor(egui::Align2::RIGHT_TOP, egui::vec2(-8.0, 8.0)).show(ctx, |ui| { + self.show(ui); + }); + } +} + +#[cfg(test)] +mod tests { + use super::*; + + fn account(id: &str, display: &str) -> Account { + Account { id: id.into(), display: display.into(), service: "one.example.com".into(), ..Account::default() } + } + + #[test] + fn nobody_signed_in_has_no_active_account() { + let menu = AccountMenu::new(); + assert!(!menu.is_signed_in()); + assert_eq!(menu.active(), None); + } + + #[test] + fn the_first_account_becomes_the_active_one() { + let mut menu = AccountMenu::new(); + menu.set(vec![account("a", "Work"), account("b", "Personal")]); + assert_eq!(menu.active().map(|a| a.id.as_str()), Some("a")); + } + + #[test] + fn replacing_the_list_keeps_the_account_in_use() { + let mut menu = AccountMenu::new(); + menu.set(vec![account("a", "Work"), account("b", "Personal")]); + menu.set_active("b"); + menu.set(vec![account("a", "Work"), account("b", "Personal"), account("c", "Lab")]); + assert_eq!(menu.active().map(|a| a.id.as_str()), Some("b"), "an unrelated refresh must not switch accounts"); + } + + #[test] + fn an_account_that_signed_out_elsewhere_leaves_nobody_in_use() { + let mut menu = AccountMenu::new(); + menu.set(vec![account("a", "Work"), account("b", "Personal")]); + menu.set_active("b"); + menu.set(vec![account("a", "Work")]); + // Not account a. A work session that expires must not hand the next + // save to a personal account without anybody saying so. + assert_eq!(menu.active(), None, "the one that is gone cannot be replaced in silence"); + assert!(menu.is_signed_in(), "there is still an account here to choose"); + } + + #[test] + fn choosing_again_after_one_disappeared_works() { + let mut menu = AccountMenu::new(); + menu.set(vec![account("a", "Work"), account("b", "Personal")]); + menu.set_active("b"); + menu.set(vec![account("a", "Work")]); + menu.set_active("a"); + assert_eq!(menu.active().map(|a| a.id.as_str()), Some("a")); + } + + #[test] + fn a_refresh_that_keeps_the_account_keeps_it_in_use() { + let mut menu = AccountMenu::new(); + menu.set(vec![account("a", "Work"), account("b", "Personal")]); + menu.set_active("b"); + menu.set(vec![account("b", "Personal"), account("c", "Lab")]); + assert_eq!(menu.active().map(|a| a.id.as_str()), Some("b")); + } + + #[test] + fn the_last_account_leaving_signs_everybody_out() { + let mut menu = AccountMenu::new(); + menu.set(vec![account("a", "Work")]); + menu.set(Vec::new()); + assert!(!menu.is_signed_in()); + assert_eq!(menu.active(), None); + } + + #[test] + fn switching_to_an_account_that_is_not_here_changes_nothing() { + let mut menu = AccountMenu::new(); + menu.set(vec![account("a", "Work")]); + menu.set_active("nobody"); + assert_eq!(menu.active().map(|a| a.id.as_str()), Some("a")); + } + + #[test] + fn the_badge_says_what_it_is_as_well_as_who() { + let labels = AccountLabels::default(); + let spoken = labels.badge.replace("{name}", "Ada Lovelace"); + assert_eq!(spoken, "Account, Ada Lovelace"); + assert_ne!(spoken, "Ada Lovelace", "a bare name collides with every other place it is written"); + } + + #[test] + fn an_initial_survives_a_name_that_starts_oddly() { + assert_eq!(account("1", "ann").initial(), "A"); + assert_eq!(account("1", "").initial(), "?"); + assert_eq!(account("1", "\u{e9}lodie").initial(), "\u{c9}"); + } +} diff --git a/crates/cloud-ui/src/buttons.rs b/crates/cloud-ui/src/buttons.rs new file mode 100644 index 000000000..3a10bb5d2 --- /dev/null +++ b/crates/cloud-ui/src/buttons.rs @@ -0,0 +1,18 @@ +//! The painted chevron the overflow menu and the split button draw. + +use egui::Ui; + +/// A downward triangle at the right-hand end of a control. +/// +/// Painted rather than typed. The chevron character is absent from the default +/// font set, where it renders as a missing-glyph box. A caller leaves room for +/// it by padding the label, then paints it over the response. +pub fn chevron(ui: &Ui, rect: egui::Rect, colour: egui::Color32) { + let middle = rect.right_center() - egui::vec2(9.0, 0.0); + let half = 3.5; + ui.painter().add(egui::Shape::convex_polygon( + vec![middle + egui::vec2(-half, -half * 0.6), middle + egui::vec2(half, -half * 0.6), middle + egui::vec2(0.0, half * 0.9)], + colour, + egui::Stroke::NONE, + )); +} diff --git a/crates/cloud-ui/src/cloud/app.rs b/crates/cloud-ui/src/cloud/app.rs new file mode 100644 index 000000000..cfb697935 --- /dev/null +++ b/crates/cloud-ui/src/cloud/app.rs @@ -0,0 +1,258 @@ +//! What this module needs from the application around it. +//! +//! Two operations here belong to the application alone. One turns bytes into an +//! open document. The other turns an open document into bytes. Both need the +//! application's own mutable state. That state is what holds the +//! [`CloudFiles`](crate::cloud::CloudFiles) this module keeps its own state in. +//! The pages are therefore free functions over this trait. An application +//! reaches its cloud state back through [`CloudApp::cloud_mut`]. +//! +//! Every method here is something only the application can answer. The ones +//! with a body are the ones a plain application can leave alone. + +use egui::{Color32, FontFamily, Painter, Rect, Ui}; + +use craft_cloud::EntryKind; + +/// What one of the application's documents is, as a file list needs to know. +/// +/// Four pieces of static data, usually one `const` in the application. These +/// four are the whole of what an application has to say about its own +/// documents. They are data because every one of them as a trait method would +/// have been a pure function of nothing. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub struct DocumentKind { + /// Extensions this application opens, lower case and without a dot. The + /// same set its desktop file picker offers. + pub extensions: &'static [&'static str], + /// Content types it opens, matched against the start of what the provider + /// said. The match is a prefix. A provider commonly appends a profile to a + /// type it is otherwise right about. + pub mimes: &'static [&'static str], + /// What one is called in a sentence a user reads. "workbook", "document", + /// "drawing". + pub noun: &'static str, + /// The extension a typed name without a known one gets. + pub default_extension: &'static str, +} + +/// The colours and faces these pages draw in. +/// +/// The Open and Save pages sit inside the application's own Backstage view and +/// have to match the surface around them. `ui.visuals()` alone cannot say what +/// that surface is. An application with a palette of its own passes it in. One +/// without takes [`CloudStyle::from_visuals`] and writes nothing. +#[derive(Clone, Debug)] +pub struct CloudStyle { + /// Behind a bordered column. + pub surface: Color32, + pub border: Color32, + pub text: Color32, + /// Second lines, hints and the status line. + pub dim: Color32, + /// Behind a file row the pointer is over. + pub hover: Color32, + /// Behind the panel that offers to link an account. Tinted and never + /// alarming. No account yet is a state with an obvious next step. + pub soft: Color32, + pub family: FontFamily, + pub bold: FontFamily, +} + +impl CloudStyle { + /// Colours from egui's own visuals, for an application with no palette. + pub fn from_visuals(visuals: &egui::Visuals) -> CloudStyle { + CloudStyle { + surface: visuals.faint_bg_color, + border: visuals.widgets.noninteractive.bg_stroke.color, + text: visuals.text_color(), + dim: visuals.weak_text_color(), + hover: visuals.widgets.hovered.bg_fill, + soft: visuals.faint_bg_color, + family: FontFamily::Proportional, + bold: FontFamily::Proportional, + } + } +} + +/// One of the application's own Save a Copy formats, for the second half of +/// the Share menu. +/// +/// The application's own. What a spreadsheet exports and what a page layout +/// application exports have nothing in common. +#[derive(Clone, Debug, PartialEq, Eq)] +pub struct CopyFormat { + /// Handed back untouched when this one is chosen. + pub id: String, + pub label: String, +} + +impl CopyFormat { + pub fn new(id: impl Into, label: impl Into) -> CopyFormat { + CopyFormat { id: id.into(), label: label.into() } + } +} + +/// An application that opens and saves documents in cloud storage. +/// Where a save is going. +/// +/// Carried as a pair because neither half is reliable alone. A provider hands +/// back `application/octet-stream` for a perfectly good document, and a file +/// exported by a web application often has a correct content type and no +/// extension at all. The same reasoning as [`DocumentKind`], which reads both +/// when deciding whether a document opens. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub struct Destination<'a> { + /// The file name the bytes are going to. + pub name: &'a str, + /// What the provider says is already there, where it says anything. Absent + /// for a document that does not exist yet. + pub mime: Option<&'a str>, +} + +impl<'a> Destination<'a> { + pub fn new(name: &'a str) -> Destination<'a> { + Destination { name, mime: None } + } + + /// The extension the name carries, lower cased, when it carries one. + /// + /// Empty for a bare name. A caller that gets nothing here has the content + /// type left to read. + pub fn extension(&self) -> String { + self.name.rsplit_once('.').map(|(_, ext)| ext.to_ascii_lowercase()).filter(|ext| !ext.is_empty()).unwrap_or_default() + } +} + +pub trait CloudApp { + // ---- the state these pages keep ------------------------------------- + + fn cloud(&self) -> &crate::cloud::CloudFiles; + fn cloud_mut(&mut self) -> &mut crate::cloud::CloudFiles; + + // ---- its documents --------------------------------------------------- + + fn kind(&self) -> DocumentKind; + + /// The document in this window, when there is one. + fn active(&self) -> Option; + + /// What to call one, for the Save As name field. + fn title(&self, uid: u64) -> String; + + /// Turn bytes into an open document, answering with the one it opened as. + /// + /// `Ok(None)` when the application took the bytes somewhere else, such as + /// a prompt for a password. Nothing is said about them yet. `Err` is put + /// to the user. + fn open_bytes(&mut self, name: &str, bytes: Vec) -> Result, String>; + + /// Turn one open document into the bytes to save, for `into`. + /// + /// [`Destination`] is where the bytes are going. A document opened from + /// the cloud as `figures.csv` has to go back as a CSV. Encoding it in the + /// application's own format under that name hands the user a file no other + /// application can read, and nothing tells them it happened. + /// + /// The name is the first answer. A provider that issued no extension at + /// all still says what the thing is, so the content type is the second. + /// Both appear often: a file exported by a web application commonly has a + /// correct content type and a bare name. + /// + /// An application that cannot write what the destination asks for should + /// refuse and say which formats it can write. A refusal a person can act + /// on beats a file that silently is not what it claims. + /// + /// Takes `&mut self` so the application can record which version of the + /// document these bytes were. A save that lands clears the dirty flag for + /// exactly that version. An edit made while the bytes were on the wire + /// stays unsaved. [`CloudApp::mark_saved`] and [`CloudApp::drop_pending`] + /// say which happened. + fn encode(&mut self, uid: u64, into: Destination<'_>) -> Result, String>; + + /// Close a document a reload replaced. Called only once the replacement is + /// open. A read that failed leaves the user's work where it was. + fn close(&mut self, uid: u64); + + /// The bytes [`CloudApp::encode`] made reached the service. + fn mark_saved(&mut self, _uid: u64) {} + + /// They did not. Forget the version it recorded. + fn drop_pending(&mut self, _uid: u64) {} + + /// Finish whatever the user is still typing. False stops the save. + fn ready_to_save(&mut self) -> bool { + true + } + + // ---- the window around them ------------------------------------------ + + /// The share dialog this window holds. Opened from a document's overflow + /// menu and from the Share button. Refreshed when who is signed in + /// changes. + fn sharing(&mut self) -> &mut crate::share::ShareDialog; + + /// Who else is in the document. Drawn beside the account badge. + fn presence(&mut self) -> &mut crate::presence::PresenceBar; + + /// Paint the icon for one row of a file list. Every application already + /// owns an icon set. None of them agree on how it is reached. + fn paint_icon(&self, painter: &Painter, rect: Rect, kind: EntryKind, colour: Color32); + + /// Open a URL in the user's browser. A browser is the application's + /// business. This crate opens nothing. + fn open_url(&self, url: &str); + + /// Open the provider's conversation for this document. + /// + /// Desktop hosts may hand this to the operating system so a registered + /// chat application can claim it. Browser hosts may navigate the current + /// tab, which remains reliable after an asynchronous provider lookup. + fn open_conversation(&self, url: &str) { + self.open_url(url); + } + + /// Say something that needs the user's attention, in the application's own + /// message box. + fn say(&mut self, text: String); + + /// Say something that does not, in passing. + fn toast(&mut self, _text: String) {} + + /// Take the user to the application's own Save As page, with the name + /// [`CloudFiles::save_name`](crate::cloud::CloudFiles::save_name) now + /// holding. Called when a refused save is answered with Save as a copy. + /// Hosts call [`cancel_save_as`](crate::cloud::cancel_save_as) when leaving + /// that page without submitting, or before opening an ordinary Save As, + /// so the abandoned copy's document and suggested name cannot carry over. + fn go_to_save_as(&mut self) {} + + // ---- its words ------------------------------------------------------- + + /// What the application is called, for the one sentence that names it. + fn app_name(&self) -> &str; + + /// Translate one English string. The default leaves it alone. An + /// application with no translation table writes nothing. + fn tr(&self, text: &str) -> String { + text.to_owned() + } + + /// The host part of the service address, for the account menu's first + /// line. Somebody with an account on two deployments needs to know which + /// one a document is about to land in. + fn service(&self) -> String { + String::new() + } + + /// A line under the Save page's name field, about the format this + /// application saves in. + fn save_note(&self) -> Option { + None + } + + /// The colours and faces to draw in. + fn style(&self, ui: &Ui) -> CloudStyle { + CloudStyle::from_visuals(ui.visuals()) + } +} diff --git a/crates/cloud-ui/src/cloud/backend.rs b/crates/cloud-ui/src/cloud/backend.rs new file mode 100644 index 000000000..f92328cef --- /dev/null +++ b/crates/cloud-ui/src/cloud/backend.rs @@ -0,0 +1,213 @@ +//! Where Open and Save do their waiting. It is never on the frame. +//! +//! Every call a cloud provider needs is blocking. A blocking read of a twenty +//! megabyte document inside `update()` freezes the window for seconds. So this +//! module states a [`Job`] and reads an [`Event`]. Something behind +//! [`CloudBackend`] does the waiting. +//! +//! Nothing here opens a socket. That keeps the pages buildable for the web and +//! testable with no service running. A host supplies the half that does. This +//! crate never learns what it reaches. + +use std::sync::Arc; +use std::sync::atomic::{AtomicU64, Ordering}; +use std::sync::mpsc::Sender; + +use craft_cloud::{Capability, Conversation, Entry}; + +/// Work for a host's worker. Each one answers with one or more [`Event`]. +pub enum Job { + /// Who is signed in, and what the provider behind the service can do. + Account, + /// Begin signing in to the service through the browser or device flow. + SignIn, + /// Begin linking a cloud account. The answer carries a URL to open. + LinkStart, + /// Whether the user has finished in the browser yet. + LinkPoll(String), + /// One folder's contents. An empty path is the user's root. + List(String), + /// Everything other people have shared with this user. + SharedWithMe, + /// A document's bytes. `into` names the open document a reload replaces. + Read { entry: Entry, into: Option }, + /// Save back over `entry`, refusing to overwrite a newer version. + Write { uid: u64, entry: Entry, bytes: Vec }, + /// Save under a new name in `folder`. + Create { uid: u64, folder: String, name: String, bytes: Vec }, + /// End the session and forget the saved token. + SignOut, + /// Where to go to work together on a document. + Conversation(String), +} + +/// What a worker reports back. +pub enum Event { + /// Where to go to work together, or why there is nowhere. + Conversation(Result), + Account(Result), + /// A link or a sign-in needs the user's browser. `handle` is polled until + /// they are done, when the service gave one. + Browser { + url: String, + handle: Option, + }, + /// `Ok(true)` means the account is linked now. + Linked(Result), + Listed { + path: String, + entries: Result, Fault>, + }, + Shared(Result, Fault>), + Read { + entry: Entry, + into: Option, + bytes: Result, Fault>, + }, + Saved { + uid: u64, + entry: Result, + }, +} + +/// Where a worker's answers go. +/// +/// Handed to [`CloudBackend::submit`] with the job it belongs to. A worker is +/// free to keep it and send later, or to send several times. That is how a +/// sign-in reports the URL it wants a browser pointed at and then reports that +/// the user finished there. A send after the window closed is not a failure. +pub struct Post { + tx: Sender, + /// The window's account generation as of the moment the job this answers + /// was issued, beside a handle to what it is now. A sign-out or a new + /// sign-in bumps the live value; a reply that arrives after is for a + /// session that is gone, and must not land on the one that replaced it. + generation: Arc, + issued: u64, +} + +impl Post { + pub(crate) fn new(tx: Sender, generation: Arc) -> Post { + let issued = generation.load(Ordering::Relaxed); + Post { tx, generation, issued } + } + + /// Another handle to the same place, for a worker that answers more than + /// once or hands the job on. Carries the same generation: every answer to + /// one job was issued at the same moment, however many of them there are. + pub fn dup(&self) -> Post { + Post { tx: self.tx.clone(), generation: self.generation.clone(), issued: self.issued } + } + + /// Delivers the event, unless the window has signed out or signed in + /// again since the job this answers was issued. Silently dropping it + /// there, rather than delivering it, is what keeps a late reply from + /// restoring the previous session's account, files or busy state on top + /// of whatever replaced it. + pub fn send(&self, event: Event) { + if self.generation.load(Ordering::Relaxed) != self.issued { + return; + } + let _ = self.tx.send(event); + } +} + +impl std::fmt::Debug for Post { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + f.debug_struct("Post").finish() + } +} + +/// Somewhere a [`Job`] can run without blocking a frame. +/// +/// `submit` must return immediately. Answers arrive through `post` whenever +/// they are ready, or never. The pages survive either. +pub trait CloudBackend { + fn submit(&self, job: Job, post: Post); +} + +/// What the service said about the signed-in user. +/// +/// Capabilities are reported by the service and never assumed here. A provider +/// without incoming shares hides that side of the Open page. An empty list +/// where a feature should be reads to a user as a broken window. +#[derive(Clone, Debug, Default, PartialEq, Eq)] +pub struct Account { + pub display: String, + pub capabilities: Vec, + /// Until this is true, Open and Save have nowhere to go. + pub provider_linked: bool, +} + +impl Account { + pub fn can(&self, capability: Capability) -> bool { + self.capabilities.contains(&capability) + } +} + +/// A call that did not succeed, in the shapes the pages act on differently. +/// +/// One case is worth telling apart from every other refusal. A conditional +/// write the server refused means somebody else's work is in the stored copy. +/// That one must never be retried and must never be forced. That is why +/// [`Fault::Conflict`] has a shape of its own. +#[derive(Clone, Debug, PartialEq, Eq)] +pub enum Fault { + /// No cloud account is linked yet. This is a state with an obvious next + /// step. It is never drawn as an error. + NotLinked, + /// Somebody else saved while this user was editing. The save was refused + /// and their work is intact. + Conflict, + /// The session expired. The user signs in again. + Unauthenticated, + Unreachable(String), + Refused(String), +} + +impl Fault { + /// One sentence for a person to read. `noun` is what the application calls + /// one of its documents, from [`crate::cloud::DocumentKind::noun`]. + pub fn text(&self, noun: &str) -> String { + match self { + Fault::NotLinked => "No cloud account is linked yet.".to_owned(), + Fault::Conflict => format!("Somebody else saved this {noun} while you were editing it."), + Fault::Unauthenticated => "Your cloud session has expired. Sign in again.".to_owned(), + Fault::Unreachable(detail) => format!("The cloud service could not be reached. {detail}"), + Fault::Refused(detail) => detail.clone(), + } + } + + /// A short machine-readable name, for a control channel. + pub fn code(&self) -> &'static str { + match self { + Fault::NotLinked => "not_linked", + Fault::Conflict => "conflict", + Fault::Unauthenticated => "unauthenticated", + Fault::Unreachable(_) => "unreachable", + Fault::Refused(_) => "refused", + } + } +} + +/// The contract's own error, in the shapes the pages act on. +/// +/// For a host that reaches a provider through [`craft_cloud`] directly. A host +/// that reaches a service through its own client crate maps that crate's error +/// instead, since only it knows which code that service answers a refused +/// conditional write with. +/// +/// [`craft_cloud::Error::Conflict`] is the one case worth telling apart. It +/// means somebody else's work is in the stored copy. The save must never be +/// retried and never be forced. +impl From for Fault { + fn from(error: craft_cloud::Error) -> Fault { + use craft_cloud::Error; + match error { + Error::Unreachable(detail) => Fault::Unreachable(detail), + Error::Unauthenticated => Fault::Unauthenticated, + Error::Conflict(_) => Fault::Conflict, + other => Fault::Refused(other.to_string()), + } + } +} diff --git a/crates/cloud-ui/src/cloud/conflict_tests.rs b/crates/cloud-ui/src/cloud/conflict_tests.rs new file mode 100644 index 000000000..1e22e815f --- /dev/null +++ b/crates/cloud-ui/src/cloud/conflict_tests.rs @@ -0,0 +1,315 @@ +//! Two risks a tabbed host runs that a single-document test cannot see: a document other than +//! the one a conflict or a job is about can be active when the answer lands, and a session that +//! ended can still have a job outstanding. +//! +//! `Tabs` is a host with two open documents (a tabbed window) and `Held` is a backend that keeps +//! every job so the test decides when, and with what, the service answers. + +use std::sync::{Arc, Mutex}; + +use craft_cloud::{Capability, Entry, EntryKind}; +use egui_kittest::Harness; +use egui_kittest::kittest::Queryable; + +use super::*; + +const NOTES: DocumentKind = DocumentKind { extensions: &["note"], mimes: &["text/plain"], noun: "note", default_extension: "note" }; + +#[derive(Default)] +struct Log { + read: Vec, + encoded: Vec, + closed: Vec, + said: Vec, +} + +struct Tabs { + cloud: CloudFiles, + share: crate::share::ShareDialog, + presence: crate::presence::PresenceBar, + active: u64, + next_uid: u64, + log: Arc>, +} + +impl CloudApp for Tabs { + fn cloud(&self) -> &CloudFiles { + &self.cloud + } + fn cloud_mut(&mut self) -> &mut CloudFiles { + &mut self.cloud + } + fn kind(&self) -> DocumentKind { + NOTES + } + fn active(&self) -> Option { + Some(self.active) + } + fn title(&self, uid: u64) -> String { + format!("doc {uid}") + } + fn open_bytes(&mut self, name: &str, _bytes: Vec) -> Result, String> { + self.log.lock().unwrap().read.push(name.to_owned()); + self.next_uid += 1; + Ok(Some(self.next_uid)) + } + fn encode(&mut self, uid: u64, _into: Destination<'_>) -> Result, String> { + self.log.lock().unwrap().encoded.push(uid); + Ok(format!("bytes of {uid}").into_bytes()) + } + fn close(&mut self, uid: u64) { + self.log.lock().unwrap().closed.push(uid); + } + fn sharing(&mut self) -> &mut crate::share::ShareDialog { + &mut self.share + } + fn presence(&mut self) -> &mut crate::presence::PresenceBar { + &mut self.presence + } + fn paint_icon(&self, _p: &egui::Painter, _r: egui::Rect, _k: EntryKind, _c: egui::Color32) {} + fn open_url(&self, _url: &str) {} + fn say(&mut self, text: String) { + self.log.lock().unwrap().said.push(text); + } + fn app_name(&self) -> &str { + "Notes" + } +} + +#[derive(Clone, Default)] +struct Held(Arc>>); + +impl CloudBackend for Held { + fn submit(&self, job: Job, post: Post) { + self.0.lock().unwrap().push((job, post)); + } +} + +impl Held { + fn take(&self, pick: impl Fn(&Job) -> bool) -> Option<(Job, Post)> { + let mut held = self.0.lock().unwrap(); + let i = held.iter().position(|(j, _)| pick(j))?; + Some(held.remove(i)) + } +} + +fn entry(path: &str, etag: &str) -> Entry { + Entry { + id: path.to_owned(), + room: format!("room:{path}"), + name: path.trim_start_matches('/').to_owned(), + path: path.to_owned(), + kind: EntryKind::File, + size: Some(10), + modified: None, + mime: None, + etag: Some(etag.to_owned()), + writable: true, + shared_by: None, + } +} + +fn account(name: &str) -> Account { + Account { display: name.to_owned(), capabilities: vec![Capability::Files, Capability::Etags], provider_linked: true } +} + +fn drain(app: &mut Tabs, ctx: &egui::Context) { + ctx.begin_pass(Default::default()); + pump(app, ctx); + ctx.end_pass().textures_delta.clear(); +} + +/// Two cloud documents open: uid 1 = A.note, uid 2 = B.note (B has unsaved edits). +fn two_tabs() -> (Tabs, Held, Arc>) { + let held = Held::default(); + let log = Arc::new(Mutex::new(Log::default())); + let mut app = Tabs { + cloud: CloudFiles::new(), + share: crate::share::ShareDialog::new(), + presence: crate::presence::PresenceBar::new(), + active: 1, + next_uid: 10, + log: log.clone(), + }; + app.cloud.connect(held.clone()); + app.cloud.origins.insert(1, Origin { entry: entry("/A.note", "a1") }); + app.cloud.origins.insert(2, Origin { entry: entry("/B.note", "b1") }); + (app, held, log) +} + +/// Save A, the user moves to tab B while the write is on the wire, the service refuses A's write +/// (Conflict). Returns the app with the conflict modal pending, active tab = B. +fn conflict_on_a_while_b_is_active() -> (Tabs, Held, Arc>) { + let (mut app, held, log) = two_tabs(); + save(&mut app).unwrap(); + app.active = 2; + let (job, post) = held.take(|j| matches!(j, Job::Write { .. })).unwrap(); + let Job::Write { uid, .. } = job else { panic!("expected Job::Write") }; + post.send(Event::Saved { uid, entry: Err(Fault::Conflict) }); + let ctx = egui::Context::default(); + drain(&mut app, &ctx); + assert_eq!(app.cloud.conflict.as_ref().map(|c| (c.uid, c.entry.name.clone())), Some((1, "A.note".to_owned()))); + (app, held, log) +} + +fn click_in_conflict_modal(app: Tabs, label: &str) -> Tabs { + let mut harness = Harness::new_ui_state(|ui, app: &mut Tabs| conflict_modal(app, &ui.ctx().clone()), app); + harness.run(); + harness.get_by_label(label).click(); + harness.run(); + harness.into_state() +} + +/// The modal says A.note was not saved; clicking "Reload from the cloud" must reload A and +/// replace uid 1, the conflicted document, never whichever tab happens to be active. +#[test] +fn conflict_reload_acts_on_the_conflicted_document_even_when_another_tab_is_active() { + let (app, held, log) = conflict_on_a_while_b_is_active(); + let mut app = click_in_conflict_modal(app, "Reload from the cloud"); + let (job, post) = held.take(|j| matches!(j, Job::Read { .. })).expect("Reload submitted a read"); + let Job::Read { entry: read, into } = job else { panic!("expected Job::Read") }; + let read_name = read.name.clone(); + post.send(Event::Read { entry: read, into, bytes: Ok(b"stored".to_vec()) }); + drain(&mut app, &egui::Context::default()); + let log = log.lock().unwrap(); + assert!( + read_name == "A.note" && into == Some(1) && !log.closed.contains(&2), + "conflict was on uid 1 (A.note); Reload read {read_name:?} into {into:?}, then closed {:?}", + log.closed + ); +} + +/// "Save as a copy" from the conflict modal must encode the conflicted document, A, not +/// whichever tab happens to be active when the Save As page's own button is finally clicked. +#[test] +fn conflict_save_as_copy_encodes_the_conflicted_document_even_when_another_tab_is_active() { + let (app, held, log) = conflict_on_a_while_b_is_active(); + let mut app = click_in_conflict_modal(app, "Save as a copy…"); + let name = app.cloud.save_name.clone(); + save_as(&mut app, "", &name).unwrap(); // what the Save As page does with that name + let (job, _) = held.take(|j| matches!(j, Job::Create { .. })).unwrap(); + let Job::Create { uid, name, bytes, .. } = job else { panic!("expected Job::Create") }; + assert_eq!( + (uid, String::from_utf8_lossy(&bytes).into_owned()), + (1, "bytes of 1".to_owned()), + "copy of the conflicted A.note is created as {name:?} from uid {uid} (encoded uids {:?})", + log.lock().unwrap().encoded + ); +} + +/// A read the backend never answers (the trait allows "or never") must not leave every transfer +/// refused forever. Signing out and back in recovers Save. +#[test] +fn sign_out_recovers_save_after_a_backend_job_never_replies() { + let (mut app, held, _log) = two_tabs(); + open_entry(&mut app, entry("/C.note", "c1"), None); + held.take(|j| matches!(j, Job::Read { .. })).unwrap(); // dropped by the worker + sign_out(&mut app); + sign_in(&mut app); + let (_, post) = held.take(|j| matches!(j, Job::SignIn)).unwrap(); + post.send(Event::Account(Ok(account("Ada")))); + drain(&mut app, &egui::Context::default()); + app.cloud.origins.insert(1, Origin { entry: entry("/A.note", "a1") }); + let saved = save(&mut app); + assert!(saved.is_ok(), "after sign-out and sign-in, Save is still refused: {saved:?}; busy={:?}", app.cloud.busy.as_ref().map(Busy::text)); +} + +/// An account and a listing answer a job issued before sign-out. Landing after it, they must +/// not put the previous session's account and file names on screen with nobody signed in. +#[test] +fn a_late_reply_from_before_sign_out_is_dropped() { + let (mut app, held, _log) = two_tabs(); + start(&mut app); + let (_, account_post) = held.take(|j| matches!(j, Job::Account)).unwrap(); + let (_, list_post) = held.take(|j| matches!(j, Job::List(_))).unwrap(); + sign_out(&mut app); + account_post.send(Event::Account(Ok(account("Previous Person")))); + list_post.send(Event::Listed { path: String::new(), entries: Ok(vec![entry("/Payroll 2026.note", "p1")]) }); + drain(&mut app, &egui::Context::default()); + let r = report(&app); + assert!( + r["account"].is_null() && r["entries"].as_array().is_some_and(Vec::is_empty), + "signed out, yet account={} entries={}", + r["account"], + r["entries"] + ); +} + +/// Save as a copy, then the first click on the Save As page is refused (no name typed yet). The +/// second click, with a name, must still copy the conflicted document A, not the active tab B. +#[test] +fn conflict_copy_survives_a_refused_first_attempt() { + let (app, held, log) = conflict_on_a_while_b_is_active(); + let mut app = click_in_conflict_modal(app, "Save as a copy…"); + let refused = save_as(&mut app, "", ""); + assert!(refused.is_err(), "an empty name is refused: {refused:?}"); + let name = app.cloud.save_name.clone(); + save_as(&mut app, "", &name).unwrap(); + let (job, _) = held.take(|j| matches!(j, Job::Create { .. })).unwrap(); + let Job::Create { uid, bytes, .. } = job else { panic!("expected Job::Create") }; + assert_eq!( + (uid, String::from_utf8_lossy(&bytes).into_owned()), + (1, "bytes of 1".to_owned()), + "after one refused attempt the copy of A.note encodes uid {uid} (encoded uids {:?})", + log.lock().unwrap().encoded + ); +} + +/// Save as a copy, but the user leaves the Save As page without saving. Later, on tab B, an +/// ordinary Save As must save B, not the conflicted A from the abandoned copy. +#[test] +fn cancelled_conflict_copy_does_not_hijack_a_later_save_as() { + let (app, held, log) = conflict_on_a_while_b_is_active(); + let app = click_in_conflict_modal(app, "Save as a copy…"); + let mut app = app; + cancel_save_as(&mut app); // the host leaves the Save As page without submitting + assert!(app.cloud.save_name.is_empty()); + assert_eq!(app.active, 2); + save_as(&mut app, "", "B renamed").unwrap(); + let (job, _) = held.take(|j| matches!(j, Job::Create { .. })).unwrap(); + let Job::Create { uid, name, bytes, .. } = job else { panic!("expected Job::Create") }; + assert_eq!( + (uid, String::from_utf8_lossy(&bytes).into_owned()), + (2, "bytes of 2".to_owned()), + "an ordinary Save As of tab B as {name:?} encoded uid {uid} (encoded uids {:?})", + log.lock().unwrap().encoded + ); +} + +/// A successfully saved conflict copy must not redirect a later ordinary Save As. +#[test] +fn successful_conflict_copy_releases_its_document_target() { + let (app, held, _log) = conflict_on_a_while_b_is_active(); + let mut app = click_in_conflict_modal(app, "Save as a copy…"); + let name = app.cloud.save_name.clone(); + save_as(&mut app, "", &name).unwrap(); + let (job, post) = held.take(|job| matches!(job, Job::Create { .. })).unwrap(); + let Job::Create { uid, .. } = job else { panic!("expected Job::Create") }; + assert_eq!(uid, 1); + assert_eq!(app.cloud.save_as_target, Some(1)); + post.send(Event::Saved { uid, entry: Ok(entry("/A-copy.note", "a2")) }); + drain(&mut app, &egui::Context::default()); + assert_eq!(app.cloud.save_as_target, None); + save_as(&mut app, "", "B renamed").unwrap(); + let (job, _) = held.take(|job| matches!(job, Job::Create { .. })).unwrap(); + let Job::Create { uid, bytes, .. } = job else { panic!("expected Job::Create") }; + assert_eq!((uid, bytes), (2, b"bytes of 2".to_vec())); +} + +/// A refused create keeps the same document pinned while the user changes its name. +#[test] +fn conflict_copy_survives_a_backend_refusal() { + let (app, held, _log) = conflict_on_a_while_b_is_active(); + let mut app = click_in_conflict_modal(app, "Save as a copy…"); + let name = app.cloud.save_name.clone(); + save_as(&mut app, "", &name).unwrap(); + let (job, post) = held.take(|job| matches!(job, Job::Create { .. })).unwrap(); + let Job::Create { uid, .. } = job else { panic!("expected Job::Create") }; + assert_eq!(uid, 1); + post.send(Event::Saved { uid, entry: Err(Fault::Refused("exists".to_owned())) }); + drain(&mut app, &egui::Context::default()); + save_as(&mut app, "", "A another copy").unwrap(); + let (job, _) = held.take(|job| matches!(job, Job::Create { .. })).unwrap(); + let Job::Create { uid, bytes, .. } = job else { panic!("expected Job::Create") }; + assert_eq!((uid, bytes), (1, b"bytes of 1".to_vec())); +} diff --git a/crates/cloud-ui/src/cloud/mod.rs b/crates/cloud-ui/src/cloud/mod.rs new file mode 100644 index 000000000..b1013a8ad --- /dev/null +++ b/crates/cloud-ui/src/cloud/mod.rs @@ -0,0 +1,901 @@ +//! Open and Save against cloud storage, the same pages in every Craft app. +//! +//! What this offers is what a person asks for when they say "open the one in +//! my cloud": a Backstage page with their own files on one side and what other +//! people shared with them on the other, folders to walk into, an account badge +//! that says whose storage this is, a Save As page that picks a folder and +//! names a file, and a save that refuses to overwrite somebody else's work. +//! +//! Three things shape the implementation. +//! +//! Nothing here opens a socket. Every call goes through [`CloudBackend`]. A +//! host writes that half. This module never learns what it reaches. That keeps +//! it buildable for the web and testable with no service running. +//! +//! Nothing here blocks. A job goes to a worker, the answer arrives on a +//! channel, and [`pump`] drains it on a later frame. A blocking read of a +//! twenty megabyte document inside a frame would freeze the window for seconds. +//! +//! Nothing here is assumed about the provider. Every side of the Open page is +//! drawn only where the service reported the capability behind it. An empty +//! list under a heading reads to a user as a broken window. A feature the +//! provider does not have is therefore absent, heading and all. +//! +//! The application supplies [`CloudApp`]. That is what it alone can answer. +//! What its documents are, how bytes become one and back, and the words it +//! shows them in. + +use std::collections::HashMap; +use std::sync::Arc; +use std::sync::atomic::{AtomicU64, Ordering}; +use std::sync::mpsc::{Receiver, Sender, channel}; +use std::time::Duration; + +use craft_cloud::{Capability, Entry, EntryKind}; +use egui::{Align2, Rect, RichText, Sense, Stroke, Ui, pos2, vec2}; +use serde_json::{Value as Json, json}; + +mod app; +mod backend; +#[cfg(test)] +mod conflict_tests; +mod pages; +#[cfg(test)] +mod tests; +mod title; + +pub use app::{CloudApp, CloudStyle, CopyFormat, Destination, DocumentKind}; +pub use backend::{Account, CloudBackend, Event, Fault, Job, Post}; +pub use pages::{conflict_modal, open_page, progress, save_page}; +pub use title::{destination_name, prefers_cloud, share_button, shares, who}; + +/// How long to wait between asking whether the user has finished linking an +/// account in their browser. +const LINK_POLL: f64 = 1.5; + +/// What a command says when no cloud service is configured. Not a failure of +/// the service: there is no service to fail. +pub const UNAVAILABLE: &str = "no cloud service is configured"; + +// ---------------------------------------------------------------- state + +/// One folder, as it is being browsed. +#[derive(Clone, Debug, Default)] +pub struct Folder { + pub path: String, + pub entries: Vec, + pub loading: bool, + pub error: Option, + /// Answered at least once. An empty folder then reads as empty. Without + /// this it would read as still loading. + pub loaded: bool, +} + +impl Folder { + fn begin(&mut self, path: &str) { + self.path = path.to_owned(); + self.entries.clear(); + self.loading = true; + self.loaded = false; + self.error = None; + } + + fn fill(&mut self, answer: Result, Fault>) { + self.loading = false; + self.loaded = true; + match answer { + Ok(entries) => { + self.entries = entries; + self.error = None; + } + Err(fault) => { + self.entries.clear(); + self.error = Some(fault); + } + } + } +} + +/// Where the document in this window came from, and the version it came at. +/// +/// `entry.id` is the opaque handle a save passes back. `entry.etag` is the +/// version the conditional write is made against. `entry.room` is neither of +/// those. It is the collaboration identity, and it survives a rename. +#[derive(Clone, Debug)] +pub struct Origin { + pub entry: Entry, +} + +/// What the pages are waiting for. Drawn as progress while they wait. +#[derive(Clone, Debug)] +pub enum Busy { + Opening { name: String }, + Saving { name: String, bytes: usize }, +} + +impl Busy { + pub fn text(&self) -> String { + match self { + Busy::Opening { name } => format!("Opening {name}…"), + Busy::Saving { name, bytes } => format!("Saving {name} ({})…", size_text(Some(*bytes as u64))), + } + } +} + +/// A save that was refused because the stored copy had moved on. +#[derive(Clone, Debug)] +pub struct Conflict { + /// The document that could not be saved. + pub uid: u64, + pub entry: Entry, +} + +/// Linking a cloud account, which takes a browser round trip. +#[derive(Clone, Debug)] +pub enum Link { + /// Offered and not started. Never drawn as an error. + Offered, + Starting, + /// The browser is open. `handle` is polled until the user is done. + Waiting { + url: String, + handle: Option, + next_poll: f64, + }, + Failed(Fault), +} + +/// Which side of the Open page a selection came from. +#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)] +pub enum Source { + #[default] + Mine, + Shared, +} + +/// Who a document was shared with, when nobody is signed in. +/// +/// Somebody who followed a keyed link has no account at the service and none +/// at the provider behind it. So there is nothing to sign out of, no second +/// account to switch to and no storage to connect. An account menu offered to +/// them would be a menu whose every item fails. +/// +/// This is what a title bar says instead. It names the address the link was +/// sent to, because that is the only identity a recipient has here, and it +/// offers nothing. +#[derive(Clone, Debug, PartialEq, Eq)] +pub struct Guest { + /// The address the link was sent to. + pub recipient: String, + /// Whether the share opens the document for reading only. + pub read_only: bool, +} + +/// Everything these pages keep about cloud storage. +/// +/// One per window. The application declares a field of this type, hands it +/// back through [`CloudApp::cloud_mut`], and connects a backend once one +/// exists. +pub struct CloudFiles { + backend: Option>, + events: (Sender, Receiver), + /// The badge and its menu. Signing in is the only way into any of this. + /// The badge is the only control that offers it. It lives here. An + /// application declares no field for it. + accounts: crate::account::AccountMenu, + /// Frame time, in seconds, as of the last [`pump`]. Kept because a link + /// poll is scheduled from an answer that arrives with no frame in hand. + clock: f64, + pub account: Option, + pub account_fault: Option, + /// The account is asked for once per run. A frame never asks again. + asked_account: bool, + /// The folder being browsed. Shared by the Open and Save As pages, which + /// are never on screen together. + pub mine: Folder, + pub shared: Folder, + pub source: Source, + pub busy: Option, + pub link: Option, + pub conflict: Option, + /// Save As: the file name being typed. + pub save_name: String, + /// Documents that came from the cloud, by document uid. + pub origins: HashMap, + /// The last thing that happened, for the line under the page title. + pub status: Option, + /// Whether the transfer in flight was started by the share dialog, which + /// is waiting to be told how it went. + pub sharing_save: bool, + /// Set when this window belongs to somebody who followed a shared link + /// rather than to somebody signed in. + guest: Option, + /// Set when the account menu starts sign-in. Browser builds open a login + /// popup from this gesture instead of inferring it from `status`, which can + /// stay set after a failed sign-in. + sign_in_from_menu: bool, + /// Bumped on sign-out and on a new sign-in. Stamped onto every [`Post`] + /// handed out by [`submit`] so a reply to a job issued before the bump is + /// dropped rather than applied to the session that replaced it. + account_generation: Arc, + /// The document Save As must act on, when it is not the active one. + /// + /// Set only by the conflict modal's "Save as a copy", so the copy it asks + /// for is made from the conflicted document even if the user has since + /// switched to another tab. Cleared after a successful save or by + /// [`cancel_save_as`] when the interaction is abandoned. + save_as_target: Option, +} + +impl Default for CloudFiles { + fn default() -> CloudFiles { + CloudFiles::new() + } +} + +impl CloudFiles { + pub fn new() -> CloudFiles { + CloudFiles { + backend: None, + events: channel(), + accounts: crate::account::AccountMenu::new(), + clock: 0.0, + account: None, + account_fault: None, + asked_account: false, + mine: Folder::default(), + shared: Folder::default(), + source: Source::default(), + busy: None, + link: None, + conflict: None, + save_name: String::new(), + origins: HashMap::new(), + status: None, + sharing_save: false, + guest: None, + sign_in_from_menu: false, + account_generation: Arc::new(AtomicU64::new(0)), + save_as_target: None, + } + } + + /// Whether the account menu just asked to sign in. Consumed by browser hosts + /// that need a user-gesture signal to open a login popup. + pub fn take_sign_in_from_menu(&mut self) -> bool { + std::mem::take(&mut self.sign_in_from_menu) + } + + /// Attach the thing that does the waiting. + /// + /// Until this is called nothing cloud-shaped is offered anywhere. That is + /// what a build with no service configured wants. + pub fn connect(&mut self, backend: impl CloudBackend + 'static) { + self.backend = Some(Box::new(backend)); + } + + /// Whether a service is wired at all. + pub fn available(&self) -> bool { + self.backend.is_some() + } + + /// Say that this window belongs to somebody who followed a shared link. + /// + /// Called once, before anything is drawn, by whatever landed them here. + /// It changes what the title bar says and nothing else: a recipient has no + /// file list and no account, so none of the pages here were ever offered + /// to them. + /// + /// An address of only spaces leaves no guest. A badge with nothing on it + /// reads as a fault, and saying nothing is better than that. + pub fn as_guest(&mut self, recipient: impl Into, read_only: bool) { + let recipient = recipient.into().trim().to_owned(); + self.guest = if recipient.is_empty() { None } else { Some(Guest { recipient, read_only }) }; + } + + /// Who this window's document was shared with, when nobody is signed in. + pub fn guest(&self) -> Option<&Guest> { + self.guest.as_ref() + } + + /// The account badge's own strings, for a localized application that + /// would rather translate them itself than through + /// [`CloudApp::tr`]. + pub fn account_menu_mut(&mut self) -> &mut crate::account::AccountMenu { + &mut self.accounts + } + + /// Whether the provider offers somewhere to talk about a document. + pub fn can_converse(&self) -> bool { + self.can(Capability::Conversation) + } + + fn can(&self, capability: Capability) -> bool { + self.account.as_ref().is_some_and(|a| a.can(capability)) + } +} + +// ---------------------------------------------------------------- asking + +/// Whether the host wired a cloud service. When it did not, nothing +/// cloud-shaped is offered anywhere in the interface. +pub fn available(app: &A) -> bool { + app.cloud().available() +} + +/// Whether the provider offers somewhere to talk about a document. +pub fn can_converse(app: &A) -> bool { + app.cloud().can_converse() +} + +/// Hands a job to the host's worker. +pub fn submit(app: &A, job: Job) { + let cloud = app.cloud(); + if let Some(backend) = &cloud.backend { + backend.submit(job, Post::new(cloud.events.0.clone(), cloud.account_generation.clone())); + } +} + +/// Asks who is signed in, once per run, and lists the root folder. +pub fn start(app: &mut A) { + if !available(app) { + return; + } + if !app.cloud().asked_account { + app.cloud_mut().asked_account = true; + submit(app, Job::Account); + } + if !app.cloud().mine.loaded && !app.cloud().mine.loading { + browse(app, ""); + } +} + +/// Begins signing in to the service. +/// +/// [`Job::SignIn`] is its own job so [`Job::Account`] can stay read-only on +/// cold start. The badge says it is working, because the worker then blocks +/// until the user finishes in the browser and a button that looks idle for a +/// minute reads as broken. +pub fn sign_in(app: &mut A) { + if !available(app) { + return; + } + let working = app.tr("Finish signing in, in your browser"); + let cloud = app.cloud_mut(); + cloud.accounts.working(); + cloud.account_fault = None; + // Cleared first. A sign-in that failed leaves this set, and a second press + // would then be swallowed by the guard that stops a frame asking twice. A + // button that does nothing the second time reads as a broken button. + cloud.asked_account = true; + cloud.link = None; + cloud.status = Some(working); + // A new session. A job the previous one left outstanding may never + // answer, and if it does, that answer is not about this account: see + // `Post::send`. Busy goes with it, or a stuck read from before this + // sign-in would leave Save refused for a session that never asked for it. + cloud.account_generation.fetch_add(1, Ordering::Relaxed); + cloud.busy = None; + submit(app, Job::SignIn); +} + +/// Ends the session, here and at the service. +/// +/// The saved token goes too. Forgetting the account on screen while leaving the +/// token on disk would sign the user back in on the next run. +pub fn sign_out(app: &mut A) { + let signed_out = app.tr("Signed out"); + let cloud = app.cloud_mut(); + cloud.account = None; + cloud.account_fault = None; + cloud.asked_account = false; + cloud.link = None; + cloud.mine = Folder::default(); + cloud.shared = Folder::default(); + cloud.origins.clear(); + cloud.status = Some(signed_out); + // The session this window had ends here. A job it started may never + // answer, and a reply that does arrive late must not land on whatever + // comes next: see `Post::send`. Busy goes with it, so an open or a save + // that never heard back does not refuse every one after it forever. + cloud.account_generation.fetch_add(1, Ordering::Relaxed); + cloud.busy = None; + cloud.save_as_target = None; + submit(app, Job::SignOut); +} + +/// Lists one folder. An empty path is the user's root. +pub fn browse(app: &mut A, path: &str) { + if !available(app) { + return; + } + app.cloud_mut().mine.begin(path); + submit(app, Job::List(path.to_owned())); +} + +/// Lists what other people have shared with this user. +pub fn load_shared(app: &mut A) { + if !available(app) { + return; + } + app.cloud_mut().shared.begin(""); + submit(app, Job::SharedWithMe); +} + +/// Begins linking a cloud account. +pub fn link(app: &mut A) { + if !available(app) { + return; + } + app.cloud_mut().link = Some(Link::Starting); + submit(app, Job::LinkStart); +} + +/// Asks where to work together on the open document, then opens it. +/// +/// Only offered where the provider reports it. A document that has never been +/// in the cloud has no handle to key a room on, so there is nothing to ask +/// about either. +pub fn work_together(app: &mut A) { + if !available(app) { + return; + } + let Some(id) = origin(app).map(|o| o.entry.id.clone()) else { + let noun = app.kind().noun; + app.cloud_mut().status = Some(app.tr(&format!("Save this {noun} to the cloud first"))); + return; + }; + converse(app, id); +} + +/// Asks the provider where to work together on one document. +fn converse(app: &mut A, id: String) { + let opening = app.tr("Opening a conversation"); + app.cloud_mut().status = Some(opening); + submit(app, Job::Conversation(id)); +} + +/// The parent of a path. `None` at the root. +pub fn parent_of(path: &str) -> Option { + let trimmed = path.trim_end_matches('/'); + if trimmed.is_empty() { + return None; + } + match trimmed.rfind('/') { + Some(0) | None => Some(String::new()), + Some(cut) => Some(trimmed[..cut].to_owned()), + } +} + +/// Whether this application can open an entry, judged by its extension and by +/// what the provider says it is. +/// +/// Both signals are read because neither is reliable alone. A WebDAV server +/// hands back `application/octet-stream` for a perfectly good spreadsheet. A +/// file exported by a web application often has a correct content type and no +/// extension at all. +pub fn opens(entry: &Entry, kind: DocumentKind) -> bool { + if entry.kind == EntryKind::Folder { + return false; + } + let extension = entry.name.rsplit_once('.').map(|(_, e)| e.to_ascii_lowercase()); + let by_name = extension.is_some_and(|e| kind.extensions.contains(&e.as_str())); + by_name || entry.mime.as_deref().is_some_and(|mime| mime_opens(mime, kind)) +} + +fn mime_opens(mime: &str, kind: DocumentKind) -> bool { + let mime = mime.split(';').next().unwrap_or("").trim().to_ascii_lowercase(); + kind.mimes.iter().any(|known| mime.starts_with(known)) +} + +/// A typed name as a document file name. Any folder separators are dropped and +/// a missing or unknown extension becomes the application's own. +pub fn document_name(typed: &str, kind: DocumentKind) -> String { + let base = typed.rsplit(['/', '\\']).next().unwrap_or("").trim(); + if base.is_empty() { + return String::new(); + } + let known = base.rsplit_once('.').is_some_and(|(stem, ext)| !stem.is_empty() && kind.extensions.contains(&ext.to_ascii_lowercase().as_str())); + if known { base.to_owned() } else { format!("{base}.{}", kind.default_extension) } +} + +/// One sentence with a value in it, translated whole. +/// +/// The template reaches [`CloudApp::tr`] with its `{}` intact. A translator +/// sees the whole sentence and can put the value where their own language +/// wants it. A sentence assembled from translated fragments cannot be made to +/// read correctly in a language that orders them differently. +fn fill(app: &A, template: &str, value: &str) -> String { + app.tr(template).replacen("{}", value, 1) +} + +/// A file name without its extension. +fn stem_of(name: &str) -> String { + match name.rsplit_once('.') { + Some((stem, _)) if !stem.is_empty() => stem.to_owned(), + _ => name.to_owned(), + } +} + +// ---------------------------------------------------------------- opening + +/// Reads a document and opens it. `into` names an open document the bytes +/// replace, which is how a reload after a conflict works. +pub fn open_entry(app: &mut A, entry: Entry, into: Option) { + if !available(app) || app.cloud().busy.is_some() { + return; + } + let cloud = app.cloud_mut(); + cloud.status = None; + cloud.busy = Some(Busy::Opening { name: entry.name.clone() }); + submit(app, Job::Read { entry, into }); +} + +/// Reads the active document's stored copy again. Local edits are discarded. +pub fn reload_active(app: &mut A) -> Result { + let noun = app.kind().noun; + let Some(uid) = app.active() else { return Err(format!("no {noun} open")) }; + let Some(origin) = app.cloud().origins.get(&uid).cloned() else { return Err(format!("this {noun} did not come from the cloud")) }; + app.cloud_mut().conflict = None; + let name = origin.entry.name.clone(); + open_entry(app, origin.entry, Some(uid)); + Ok(json!({"reloading": name})) +} + +// ---------------------------------------------------------------- saving + +/// The cloud document the active one came from, when it came from one. +pub fn origin(app: &A) -> Option<&Origin> { + let uid = app.active()?; + app.cloud().origins.get(&uid) +} + +/// Whether Save has somewhere to go without asking. A Backstage view uses this +/// to choose between Save and the Save As page. +pub fn has_target(app: &A) -> bool { + origin(app).is_some_and(|o| o.entry.writable) +} + +/// Save: writes back over the entry this document came from. +/// +/// The etag the document was read at goes out as the condition. A server whose +/// copy has moved on refuses the write. That arrives as [`Fault::Conflict`] and +/// is put to the user. It is never retried. +pub fn save(app: &mut A) -> Result { + let noun = app.kind().noun; + let uid = app.active().ok_or(format!("no {noun} open"))?; + let origin = app.cloud().origins.get(&uid).cloned().ok_or(format!("this {noun} did not come from the cloud"))?; + if !origin.entry.writable { + return Err("this document was shared with you for reading only. Save As keeps a copy of your own.".to_owned()); + } + if app.cloud().busy.is_some() { + return Err("a cloud transfer is already running".to_owned()); + } + let bytes = app.encode(uid, Destination { name: &origin.entry.name, mime: origin.entry.mime.as_deref() })?; + let size = bytes.len(); + let cloud = app.cloud_mut(); + cloud.status = None; + cloud.busy = Some(Busy::Saving { name: origin.entry.name.clone(), bytes: size }); + let answer = json!({"saving": origin.entry.name, "bytes": size, "ifMatch": origin.entry.etag}); + submit(app, Job::Write { uid, entry: origin.entry, bytes }); + Ok(answer) +} + +/// Ends an unsubmitted Save As interaction. +/// +/// Hosts call this when leaving the Save As page without saving, and before +/// opening an unrelated Save As. It does not cancel a transfer already sent +/// to the backend. +pub fn cancel_save_as(app: &mut A) { + let cloud = app.cloud_mut(); + cloud.save_as_target = None; + cloud.save_name.clear(); +} + +/// Save As: writes a new document into `folder` under `name`. +/// +/// Acts on `CloudFiles::save_as_target` when the conflict modal's "Save as +/// a copy" set one, so the copy is made from the document that conflicted +/// even if another tab is active by the time this runs. Otherwise, the +/// active document, same as every other ordinary Save As. +pub fn save_as(app: &mut A, folder: &str, name: &str) -> Result { + let kind = app.kind(); + let uid = app.cloud().save_as_target.or_else(|| app.active()).ok_or(format!("no {} open", kind.noun))?; + let name = document_name(name, kind); + if name.is_empty() { + return Err("type a file name".to_owned()); + } + if app.cloud().busy.is_some() { + return Err("a cloud transfer is already running".to_owned()); + } + // A document that does not exist yet has no content type to read. The + // name a person just typed is the whole of what was asked for. + let bytes = app.encode(uid, Destination::new(&name))?; + let size = bytes.len(); + let cloud = app.cloud_mut(); + cloud.status = None; + cloud.busy = Some(Busy::Saving { name: name.clone(), bytes: size }); + let answer = json!({"saving": name, "folder": folder, "bytes": size}); + submit(app, Job::Create { uid, folder: folder.to_owned(), name, bytes }); + Ok(answer) +} + +// ---------------------------------------------------------------- reading the answers + +/// Drains the host's answers and keeps a link or a transfer moving. Called +/// once a frame, before anything is drawn. +pub fn pump(app: &mut A, ctx: &egui::Context) { + if !available(app) { + return; + } + app.cloud_mut().clock = ctx.input(|i| i.time); + // Taken in one pass, then applied. An answer that arrives because of a job + // this frame sent belongs to the next frame. A worker on its own thread + // would have delivered it that way anyway. + let mut arrived = Vec::new(); + while let Ok(event) = app.cloud().events.1.try_recv() { + arrived.push(event); + } + for event in arrived { + apply(app, event); + } + poll_link(app); + // A worker answering is not a local event. Without this the progress line + // would sit frozen until the user moved the mouse. + if app.cloud().busy.is_some() || matches!(app.cloud().link, Some(Link::Starting | Link::Waiting { .. })) { + ctx.request_repaint_after(Duration::from_millis(120)); + } +} + +fn apply(app: &mut A, event: Event) { + let noun = app.kind().noun; + match event { + Event::Account(Ok(account)) => { + let linked = account.provider_linked; + // Who is signed in has changed, so what the provider can do may + // have changed with it. The dialog keeps its first answer, and on a + // cold start that answer is "nobody is signed in". + app.sharing().refresh(); + let cloud = app.cloud_mut(); + cloud.account = Some(account); + cloud.account_fault = None; + if linked { + cloud.link = None; + } else if cloud.link.is_none() { + cloud.link = Some(Link::Offered); + } + } + // No account linked yet is a state with an obvious next step. It is an + // offer to link, and never an error message. + Event::Account(Err(Fault::NotLinked)) => { + let cloud = app.cloud_mut(); + cloud.account_fault = None; + if cloud.link.is_none() { + cloud.link = Some(Link::Offered); + } + } + Event::Account(Err(fault)) => app.cloud_mut().account_fault = Some(fault), + Event::Conversation(Ok(conversation)) => { + let said = fill(app, "Opened in {}", &conversation.name); + app.cloud_mut().status = Some(said); + app.open_conversation(&conversation.url); + } + Event::Conversation(Err(fault)) => { + let text = fault.text(noun); + app.cloud_mut().status = Some(text); + } + Event::Browser { url, handle } => { + app.open_url(&url); + let next_poll = app.cloud().clock + LINK_POLL; + app.cloud_mut().link = Some(Link::Waiting { url, handle, next_poll }); + } + Event::Linked(Ok(true)) => { + // Storage just arrived, so ask what it can do. + app.sharing().refresh(); + let linked = app.tr("Cloud account linked."); + let cloud = app.cloud_mut(); + cloud.link = None; + cloud.status = Some(linked); + cloud.asked_account = false; + submit(app, Job::Account); + browse(app, ""); + app.cloud_mut().shared.loaded = false; + } + // The ordinary answer while the user is still in the browser. + Event::Linked(Ok(false)) | Event::Linked(Err(Fault::NotLinked)) => {} + Event::Linked(Err(fault)) => app.cloud_mut().link = Some(Link::Failed(fault)), + Event::Listed { path, entries } => { + let cloud = app.cloud_mut(); + if path == cloud.mine.path { + cloud.mine.fill(entries); + } + } + Event::Shared(entries) => app.cloud_mut().shared.fill(entries), + Event::Read { entry, into, bytes } => { + app.cloud_mut().busy = None; + match bytes { + Ok(bytes) => opened(app, entry, into, bytes), + Err(Fault::NotLinked) => app.cloud_mut().link = Some(Link::Offered), + Err(fault) => { + let text = format!("{}. {}", fill(app, "{} could not be opened", &entry.name), fault.text(noun)); + app.say(text); + } + } + } + Event::Saved { uid, entry } => { + app.cloud_mut().busy = None; + match entry { + Ok(entry) => { + if app.cloud().save_as_target == Some(uid) { + app.cloud_mut().save_as_target = None; + } + app.mark_saved(uid); + stored(app, uid, entry); + } + // The one failure that must never be retried and never forced. + Err(Fault::Conflict) => { + app.drop_pending(uid); + match app.cloud().origins.get(&uid).cloned() { + Some(origin) => app.cloud_mut().conflict = Some(Conflict { uid, entry: origin.entry }), + None => app.say(Fault::Conflict.text(noun)), + } + } + Err(Fault::NotLinked) => { + app.drop_pending(uid); + app.cloud_mut().link = Some(Link::Offered); + } + Err(fault) => { + app.drop_pending(uid); + let text = format!("{} {}", app.tr(&format!("The {noun} was not saved.")), fault.text(noun)); + app.say(text); + } + } + } + } +} + +/// Bytes arrived. The application opens them. The document then remembers +/// where they came from. +fn opened(app: &mut A, entry: Entry, into: Option, bytes: Vec) { + let name = entry.name.clone(); + match app.open_bytes(&name, bytes) { + Ok(now) => { + if let Some(uid) = now { + app.cloud_mut().origins.insert(uid, Origin { entry }); + } + // A reload closes the document it replaced only once the new one is + // open. A read that fails leaves the user's work where it was. + if let (Some(old), Some(new)) = (into, now) + && old != new + { + let cloud = app.cloud_mut(); + cloud.origins.remove(&old); + app.drop_pending(old); + app.close(old); + } + if now.is_some() { + let said = fill(app, "Opened {} from the cloud.", &name); + app.cloud_mut().status = Some(said); + } + } + Err(reason) => app.say(reason), + } +} + +/// A save landed. The document now belongs to the entry the server returned, at +/// the version it returned. +fn stored(app: &mut A, uid: u64, entry: Entry) { + let name = entry.name.clone(); + let line = fill(app, "Saved {} to the cloud.", &name); + app.toast(fill(app, "Saved {} to the cloud", &name)); + let cloud = app.cloud_mut(); + cloud.conflict = None; + cloud.status = Some(line); + cloud.origins.insert(uid, Origin { entry }); +} + +/// Keeps asking whether the user has finished linking in their browser. +fn poll_link(app: &mut A) { + let now = app.cloud().clock; + let handle = { + let Some(Link::Waiting { handle: Some(handle), next_poll, .. }) = &mut app.cloud_mut().link else { return }; + if now < *next_poll { + return; + } + *next_poll = now + LINK_POLL; + handle.clone() + }; + submit(app, Job::LinkPoll(handle)); +} + +// ---------------------------------------------------------------- reporting + +/// The whole of the cloud state, for a control channel and for tests. +pub fn report(app: &A) -> Json { + let kind = app.kind(); + let cloud = app.cloud(); + let account = cloud.account.as_ref().map(|a| { + json!({ + "display": a.display, + "providerLinked": a.provider_linked, + "capabilities": a.capabilities.iter().map(|c| serde_json::to_value(c).unwrap_or_default()).collect::>(), + }) + }); + let came_from = origin(app) + .map(|o| json!({"id": o.entry.id, "room": o.entry.room, "name": o.entry.name, "etag": o.entry.etag, "writable": o.entry.writable})); + json!({ + "available": cloud.available(), + "account": account, + "accountError": cloud.account_fault.as_ref().map(Fault::code), + "folder": cloud.mine.path, + "entries": cloud.mine.entries.iter().map(|e| e.name.clone()).collect::>(), + "openable": cloud.mine.entries.iter().filter(|e| opens(e, kind)).map(|e| e.name.clone()).collect::>(), + "shared": cloud.shared.entries.iter().map(|e| json!({"name": e.name, "sharedBy": e.shared_by, "writable": e.writable, "openable": opens(e, kind)})).collect::>(), + "busy": cloud.busy.as_ref().map(Busy::text), + "link": match &cloud.link { + None => Json::Null, + Some(Link::Offered) => json!("offered"), + Some(Link::Starting) => json!("starting"), + Some(Link::Waiting { url, .. }) => json!({"waiting": url}), + Some(Link::Failed(fault)) => json!({"failed": fault.code()}), + }, + "conflict": cloud.conflict.as_ref().map(|c| json!({"name": c.entry.name})), + "origin": came_from, + "status": cloud.status, + "guest": cloud.guest.as_ref().map(|g| json!({"recipient": g.recipient, "readOnly": g.read_only})), + }) +} + +// ---------------------------------------------------------------- shared drawing + +/// Bytes as a person reads them. +pub fn size_text(bytes: Option) -> String { + let Some(bytes) = bytes else { return String::new() }; + const UNITS: [&str; 4] = ["bytes", "KB", "MB", "GB"]; + let mut size = bytes as f64; + let mut unit = 0; + while size >= 1024.0 && unit + 1 < UNITS.len() { + size /= 1024.0; + unit += 1; + } + match UNITS.get(unit) { + Some(name) if unit > 0 => format!("{size:.1} {name}"), + _ => format!("{bytes} bytes"), + } +} + +fn dim(ui: &mut Ui, style: &CloudStyle, text: &str) { + ui.label(RichText::new(text).font(egui::FontId::new(12.5, style.family.clone())).color(style.dim)); +} + +/// A bordered column with a heading. This is how the two Open sources sit side +/// by side. +fn column(ui: &mut Ui, style: &CloudStyle, heading: &str, body: impl FnOnce(&mut Ui)) { + egui::Frame::NONE.fill(style.surface).stroke(Stroke::new(1.0, style.border)).corner_radius(6.0).inner_margin(10).show(ui, |ui| { + ui.label(RichText::new(heading).font(egui::FontId::new(13.0, style.bold.clone())).color(style.text)); + ui.add_space(6.0); + egui::ScrollArea::vertical().id_salt(heading.to_owned()).max_height(300.0).auto_shrink([false, false]).show(ui, body); + }); +} + +/// One row in a file list, with a second line for the detail that matters on +/// that side of the page (a size for your own files, who shared it for +/// somebody else's). +fn entry_row(app: &A, ui: &mut Ui, entry: &Entry, detail: &str, reserve: f32) -> egui::Response { + let style = app.style(ui); + let width = (ui.available_width() - reserve).max(60.0); + let (rect, resp) = ui.allocate_exact_size(vec2(width, 40.0), Sense::click()); + let label = entry.name.clone(); + resp.widget_info(|| egui::WidgetInfo::labeled(egui::Role::Button, true, &label)); + let p = ui.painter(); + if resp.hovered() { + p.rect_filled(rect, 4.0, style.hover); + } + app.paint_icon(p, Rect::from_center_size(pos2(rect.left() + 18.0, rect.center().y), vec2(18.0, 18.0)), entry.kind, style.text); + let (name_y, detail_y) = if detail.is_empty() { (rect.center().y, rect.center().y) } else { (rect.center().y - 8.0, rect.center().y + 9.0) }; + p.text(pos2(rect.left() + 38.0, name_y), Align2::LEFT_CENTER, &entry.name, egui::FontId::new(13.0, style.family.clone()), style.text); + if !detail.is_empty() { + p.text(pos2(rect.left() + 38.0, detail_y), Align2::LEFT_CENTER, detail, egui::FontId::new(11.0, style.family.clone()), style.dim); + } + resp +} diff --git a/crates/cloud-ui/src/cloud/pages.rs b/crates/cloud-ui/src/cloud/pages.rs new file mode 100644 index 000000000..86e71d1c8 --- /dev/null +++ b/crates/cloud-ui/src/cloud/pages.rs @@ -0,0 +1,519 @@ +//! The Backstage pages: File › Open and File › Save As, and the modal a +//! refused save puts up. +//! +//! Every side of a page is drawn only where the service reported the +//! capability behind it. A list under a heading the provider cannot fill reads +//! to a user as a broken window, so the heading goes too. + +use craft_cloud::{Capability, Entry, EntryKind}; +use egui::{RichText, Ui}; + +use super::{ + CloudApp, Link, Source, browse, column, converse, dim, document_name, entry_row, fill, link, load_shared, open_entry, opens, parent_of, save_as, + size_text, start, stem_of, +}; + +/// The character a label ends with when choosing it opens a dialog. +const ELLIPSIS: &str = "\u{2026}"; + +/// What an overflow menu asked for, deferred until the list is no longer being +/// drawn. Opening a dialog while borrowing the list is not possible. +enum Act { + Share(Entry), + Talk(Entry), +} + +/// The account line, or the reason there is nothing to show yet. +fn header(app: &mut A, ui: &mut Ui) { + let style = app.style(ui); + let mut retry = false; + match (&app.cloud().account, &app.cloud().account_fault) { + (_, Some(fault)) => { + let text = fault.text(app.kind().noun); + let again = app.tr("Try again"); + ui.horizontal(|ui| { + dim(ui, &style, &text); + if ui.button(again).clicked() { + retry = true; + } + }); + } + (Some(account), None) => { + let line = if account.display.is_empty() { app.tr("Signed in") } else { account.display.clone() }; + dim(ui, &style, &line); + } + (None, None) => { + let waiting = app.tr("Connecting to your cloud account…"); + dim(ui, &style, &waiting); + } + } + if retry { + let cloud = app.cloud_mut(); + cloud.account_fault = None; + cloud.asked_account = false; + start(app); + } +} + +/// The offer to link an account, and the wait while the browser is open. +/// Returns true when it drew, because there is nothing else to show until an +/// account exists. +/// +/// None of this is an error. The whole state means one thing: there is no +/// account yet, and linking one is a button away. +fn link_panel(app: &mut A, ui: &mut Ui) -> bool { + let Some(state) = app.cloud().link.clone() else { return false }; + let style = app.style(ui); + let noun = app.kind().noun; + let mut begin = false; + let mut cancel = false; + let mut browse_to: Option = None; + let words = LinkWords { + none_yet: app.tr("No cloud account is linked yet."), + why: app.tr(&format!("Link one to open and save {noun}s in your cloud storage.")), + link_one: app.tr("Link a cloud account"), + starting: app.tr("Starting…"), + finish: app.tr("Finish linking in your browser."), + waiting: app.tr("Waiting for your browser…"), + open_in_browser: app.tr("Open in browser"), + copy_link: app.tr("Copy link"), + cancel: app.tr("Cancel"), + again: app.tr("Try again"), + }; + egui::Frame::NONE.fill(style.soft).corner_radius(6.0).inner_margin(12).show(ui, |ui| match state { + Link::Offered => { + ui.label(RichText::new(&words.none_yet).font(egui::FontId::new(13.0, style.bold.clone())).color(style.text)); + dim(ui, &style, &words.why); + ui.add_space(8.0); + begin = ui.button(&words.link_one).clicked(); + } + Link::Starting => { + ui.horizontal(|ui| { + ui.add(egui::Spinner::new().size(14.0)); + dim(ui, &style, &words.starting); + }); + } + Link::Waiting { url, .. } => { + ui.label(RichText::new(&words.finish).font(egui::FontId::new(13.0, style.bold.clone())).color(style.text)); + ui.horizontal(|ui| { + ui.add(egui::Spinner::new().size(14.0)); + dim(ui, &style, &words.waiting); + }); + ui.add_space(6.0); + // A link alone is not enough. When the browser cannot be opened, + // or opens the wrong thing, the only way out is carrying the + // address across by hand, and a label cannot be selected. + ui.horizontal(|ui| { + if ui.button(&words.open_in_browser).clicked() { + browse_to = Some(url.clone()); + } + if ui.button(&words.copy_link).clicked() { + ui.ctx().copy_text(url.clone()); + } + }); + ui.add_space(4.0); + if ui.link(&url).clicked() { + browse_to = Some(url.clone()); + } + ui.add_space(8.0); + cancel = ui.button(&words.cancel).clicked(); + } + Link::Failed(fault) => { + ui.label(RichText::new(fault.text(noun)).font(egui::FontId::new(13.0, style.family.clone())).color(style.text)); + ui.add_space(8.0); + begin = ui.button(&words.again).clicked(); + } + }); + if let Some(url) = browse_to { + app.open_url(&url); + } + if begin { + link(app); + } else if cancel { + app.cloud_mut().link = Some(Link::Offered); + } + true +} + +/// The panel's strings, read before it is drawn. The application is borrowed +/// mutably inside the frame, so nothing can be asked of it there. +struct LinkWords { + none_yet: String, + why: String, + link_one: String, + starting: String, + finish: String, + waiting: String, + open_in_browser: String, + copy_link: String, + cancel: String, + again: String, +} + +/// The progress line for a read or a write in flight. +pub fn progress(app: &A, ui: &mut Ui) { + let Some(busy) = app.cloud().busy.clone() else { return }; + let style = app.style(ui); + ui.horizontal(|ui| { + ui.add(egui::Spinner::new().size(15.0)); + ui.label(RichText::new(busy.text()).font(egui::FontId::new(12.5, style.family.clone())).color(style.text)); + }); +} + +/// The `…` beside a document, and what a person chose from it. +/// +/// Only the actions the provider actually offers appear. A greyed-out item says +/// the action exists and is not possible right now. An absent one says this +/// provider does not do that at all, and those are different facts. +fn row_actions(app: &A, ui: &mut Ui, entry: &Entry) -> Option { + let can = |c: Capability| app.cloud().account.as_ref().is_some_and(|a| a.can(c)); + let mut items = vec![crate::menu::MenuItem::new("open", app.tr("Open"))]; + if can(Capability::Sharing) { + items.push( + crate::menu::MenuItem::new("share", format!("{}{}", app.tr("Share"), ELLIPSIS)) + .detail(app.tr("See who this is shared with, and invite somebody")) + .separated(), + ); + } + if can(Capability::Conversation) { + items.push(crate::menu::MenuItem::new("talk", app.tr("Work together")).detail(app.tr("Open a conversation about this document"))); + } + let labels = crate::menu::MenuLabels { more: app.tr("More options"), ..Default::default() }; + // Salted by the handle. Two rows drawing the same control need two menus, + // and the handle is the one thing that differs between them. + ui.push_id(entry.id.clone(), |ui| crate::menu::overflow(ui, &items, &labels)).inner +} + +/// File › Open, the cloud part. Your own files sit on one side and what other +/// people shared with you sits on the other. +pub fn open_page(app: &mut A, ui: &mut Ui) { + start(app); + header(app, ui); + ui.add_space(8.0); + if link_panel(app, ui) { + return; + } + progress(app, ui); + // Hidden where the provider has no incoming shares at all. An empty list + // under that heading would read as a broken feature. + let shared_offered = app.cloud().account.as_ref().is_some_and(|a| a.can(Capability::SharedWithMe)); + if shared_offered && !app.cloud().shared.loaded && !app.cloud().shared.loading { + load_shared(app); + } + let mut pick: Option<(Entry, Source)> = None; + let mut go: Option = None; + let mut act: Option = None; + if shared_offered { + ui.columns(2, |columns| { + if let Some(ui) = columns.get_mut(0) { + my_files(app, ui, &mut pick, &mut go, &mut act); + } + if let Some(ui) = columns.get_mut(1) { + shared_files(app, ui, &mut pick, &mut act); + } + }); + } else { + my_files(app, ui, &mut pick, &mut go, &mut act); + } + match act { + // Sharing a document in the list, which is not the one that happens to + // be open. The dialog is told which. + Some(Act::Share(entry)) => app.sharing().open(entry.id.clone(), entry.name.clone()), + Some(Act::Talk(entry)) => converse(app, entry.id.clone()), + None => {} + } + if let Some(path) = go { + browse(app, &path); + } else if let Some((entry, source)) = pick { + app.cloud_mut().source = source; + open_entry(app, entry, None); + } + if let Some(status) = app.cloud().status.clone() { + let style = app.style(ui); + ui.add_space(10.0); + dim(ui, &style, &status); + } +} + +/// Your own files: where you are, a way up, then the folders and the documents +/// this application can open. +fn my_files(app: &mut A, ui: &mut Ui, pick: &mut Option<(Entry, Source)>, go: &mut Option, act: &mut Option) { + let style = app.style(ui); + let kind = app.kind(); + let folder = app.cloud().mine.clone(); + let heading = app.tr("My files"); + let (home, up, loading) = (app.tr("Home"), app.tr("Up"), app.tr("Loading…")); + let nothing = app.tr(&format!("Nothing here that {} can open.", app.app_name())); + column(ui, &style, &heading, |ui| { + let here = if folder.path.is_empty() { home } else { folder.path.clone() }; + ui.horizontal(|ui| { + if let Some(parent) = parent_of(&folder.path) + && ui.button(&up).clicked() + { + *go = Some(parent); + } + dim(ui, &style, &here); + }); + ui.add_space(4.0); + if folder.loading { + ui.horizontal(|ui| { + ui.add(egui::Spinner::new().size(14.0)); + dim(ui, &style, &loading); + }); + return; + } + if let Some(fault) = &folder.error { + dim(ui, &style, &fault.text(kind.noun)); + return; + } + let mut shown = 0; + for entry in &folder.entries { + let is_folder = entry.kind == EntryKind::Folder; + if !is_folder && !opens(entry, kind) { + continue; + } + shown += 1; + let detail = if is_folder { String::new() } else { size_text(entry.size) }; + // A folder has nothing behind an ellipsis. Opening it is the only + // thing to do with one here. + let reserve = if is_folder { 0.0 } else { 26.0 }; + let (row, chose) = ui + .horizontal(|ui| { + let row = entry_row(app, ui, entry, &detail, reserve).clicked(); + let chose = if is_folder { None } else { row_actions(app, ui, entry) }; + (row, chose) + }) + .inner; + match chose.as_deref() { + Some("share") => *act = Some(Act::Share(entry.clone())), + Some("talk") => *act = Some(Act::Talk(entry.clone())), + Some("open") => *pick = Some((entry.clone(), Source::Mine)), + _ if row => { + if is_folder { + *go = Some(entry.path.clone()); + } else { + *pick = Some((entry.clone(), Source::Mine)); + } + } + _ => {} + } + } + if shown == 0 && folder.loaded { + dim(ui, &style, ¬hing); + } + }); +} + +/// What other people shared with you. One flat list, because an incoming share +/// has no folder of yours to sit in. Each row says who shared it. +fn shared_files(app: &mut A, ui: &mut Ui, pick: &mut Option<(Entry, Source)>, act: &mut Option) { + let style = app.style(ui); + let kind = app.kind(); + let shared = app.cloud().shared.clone(); + let heading = app.tr("Shared with me"); + let (loading, with_you, read_only) = (app.tr("Loading…"), app.tr("Shared with you"), app.tr("read-only")); + let nobody = app.tr(&format!("Nobody has shared a {} with you.", kind.noun)); + column(ui, &style, &heading, |ui| { + if shared.loading { + ui.horizontal(|ui| { + ui.add(egui::Spinner::new().size(14.0)); + dim(ui, &style, &loading); + }); + return; + } + if let Some(fault) = &shared.error { + dim(ui, &style, &fault.text(kind.noun)); + return; + } + let mut shown = 0; + for entry in shared.entries.iter().filter(|e| opens(e, kind)) { + shown += 1; + let who = entry.shared_by.clone().unwrap_or_else(|| with_you.clone()); + let detail = if entry.writable { who } else { format!("{who} ({read_only})") }; + let (row, chose) = ui + .horizontal(|ui| { + let row = entry_row(app, ui, entry, &detail, 26.0).clicked(); + (row, row_actions(app, ui, entry)) + }) + .inner; + match chose.as_deref() { + Some("share") => *act = Some(Act::Share(entry.clone())), + Some("talk") => *act = Some(Act::Talk(entry.clone())), + _ if row || chose.is_some() => *pick = Some((entry.clone(), Source::Shared)), + _ => {} + } + } + if shown == 0 && shared.loaded { + dim(ui, &style, &nobody); + } + }); +} + +/// File › Save As, the cloud destination. Pick a folder, name the file, save. +/// Returns true when a save started, so a Backstage view can return to the +/// document. Hosts call [`super::cancel_save_as`] when leaving without saving, +/// or before opening this page for an ordinary File › Save As, to discard any +/// abandoned conflict-copy target and suggested name. +pub fn save_page(app: &mut A, ui: &mut Ui) -> bool { + let style = app.style(ui); + let kind = app.kind(); + start(app); + // The destination above already names the account. This line is here to + // say when something is wrong with it. + if app.cloud().account.is_none() || app.cloud().account_fault.is_some() { + header(app, ui); + ui.add_space(8.0); + } + if link_panel(app, ui) { + return false; + } + progress(app, ui); + if app.cloud().save_name.is_empty() { + let suggested = app.active().map(|uid| app.title(uid)).unwrap_or_default(); + app.cloud_mut().save_name = document_name(&suggested, kind); + } + let folder = app.cloud().mine.clone(); + let heading = app.tr("Folder"); + let (home, up, loading) = (app.tr("Home"), app.tr("Up"), app.tr("Loading…")); + let only_folder = app.tr(&format!("No folders here. The {} saves in this one.", kind.noun)); + let mut go: Option = None; + column(ui, &style, &heading, |ui| { + let here = if folder.path.is_empty() { home } else { folder.path.clone() }; + ui.horizontal(|ui| { + if let Some(parent) = parent_of(&folder.path) + && ui.button(&up).clicked() + { + go = Some(parent); + } + dim(ui, &style, &here); + }); + ui.add_space(4.0); + if folder.loading { + ui.horizontal(|ui| { + ui.add(egui::Spinner::new().size(14.0)); + dim(ui, &style, &loading); + }); + return; + } + if let Some(fault) = &folder.error { + dim(ui, &style, &fault.text(kind.noun)); + return; + } + let mut folders = 0; + for entry in folder.entries.iter().filter(|e| e.kind == EntryKind::Folder) { + folders += 1; + if entry_row(app, ui, entry, "", 0.0).clicked() { + go = Some(entry.path.clone()); + } + } + if folders == 0 && folder.loaded { + dim(ui, &style, &only_folder); + } + }); + if let Some(path) = go { + browse(app, &path); + } + ui.add_space(12.0); + let (file_name, save_label) = (app.tr("File name"), app.tr("Save to the cloud")); + let mut asked = false; + ui.horizontal(|ui| { + ui.label(file_name); + let typing = ui.add(egui::TextEdit::singleline(&mut app.cloud_mut().save_name).desired_width(280.0)); + asked = typing.lost_focus() && ui.input(|i| i.key_pressed(egui::Key::Enter)); + }); + ui.add_space(10.0); + let ready = app.cloud().busy.is_none() && !document_name(&app.cloud().save_name, kind).is_empty(); + if ui.add_enabled(ready, egui::Button::new(save_label)).clicked() { + asked = true; + } + if let Some(note) = app.save_note() { + ui.add_space(8.0); + dim(ui, &style, ¬e); + } + // A provider with no conditional writes cannot refuse one, so a save here + // can land on top of somebody else's. Said plainly, because the user is the + // only one who can decide whether that matters. + if app.cloud().account.as_ref().is_some_and(|a| !a.can(Capability::Etags)) { + let warning = app.tr("This cloud account cannot detect a save that would overwrite somebody else's changes."); + ui.add_space(4.0); + dim(ui, &style, &warning); + } + if asked && ready && app.ready_to_save() { + let (folder, name) = (app.cloud().mine.path.clone(), app.cloud().save_name.clone()); + match save_as(app, &folder, &name) { + Ok(_) => return true, + Err(error) => app.say(error), + } + } + false +} + +/// A save refused because the stored copy had moved on. +/// +/// Three ways out, and none of them throws anything away without saying so. +/// Reloading is the one a user usually wants, so it comes first. The text says +/// plainly that it discards their edits. +pub fn conflict_modal(app: &mut A, ctx: &egui::Context) { + let Some(conflict) = app.cloud().conflict.clone() else { return }; + let noun = app.kind().noun; + let words = ConflictWords { + title: app.tr(&format!("This {noun} was not saved")), + what: fill( + app, + "Somebody else saved {} while you were editing it. Nothing was written: saving now would overwrite their work.", + &conflict.entry.name, + ), + yours: app.tr("Your own changes are still open here. Reloading replaces them with the stored copy."), + reload: app.tr("Reload from the cloud"), + copy: app.tr(&format!("Save as a copy{ELLIPSIS}")), + keep: app.tr("Keep editing"), + }; + let mut reload = false; + let mut copy = false; + let mut dismiss = false; + egui::Modal::new(egui::Id::unique("craft-ui/cloud/conflict")).show(ctx, |ui| { + let style = app.style(ui); + ui.set_width(430.0); + ui.label(RichText::new(&words.title).font(egui::FontId::new(15.0, style.bold.clone()))); + ui.add_space(8.0); + ui.add(egui::Label::new(&words.what).wrap()); + ui.add_space(6.0); + ui.add(egui::Label::new(&words.yours).wrap()); + ui.add_space(12.0); + ui.horizontal(|ui| { + reload = ui.button(&words.reload).clicked(); + copy = ui.button(&words.copy).clicked(); + dismiss = ui.button(&words.keep).clicked(); + }); + }); + if reload { + // Reads the conflicted document back, never whichever tab happens to + // be active. `reload_active` acts on the active document, which is + // right for a host's own Reload command but wrong here: the window + // that triggered this modal may have moved on to another document + // while the refused save was on the wire. + app.cloud_mut().conflict = None; + open_entry(app, conflict.entry, Some(conflict.uid)); + } else if copy { + let name = document_name(&format!("{} (copy)", stem_of(&conflict.entry.name)), app.kind()); + let cloud = app.cloud_mut(); + cloud.conflict = None; + cloud.save_name = name; + // Save As must encode the conflicted document too, not whatever is + // active once the user actually clicks Save on that page. + cloud.save_as_target = Some(conflict.uid); + app.go_to_save_as(); + } else if dismiss { + app.cloud_mut().conflict = None; + } +} + +/// The modal's strings, read before it is drawn. +struct ConflictWords { + title: String, + what: String, + yours: String, + reload: String, + copy: String, + keep: String, +} diff --git a/crates/cloud-ui/src/cloud/tests.rs b/crates/cloud-ui/src/cloud/tests.rs new file mode 100644 index 000000000..875612144 --- /dev/null +++ b/crates/cloud-ui/src/cloud/tests.rs @@ -0,0 +1,573 @@ +//! The pages driven by an application that holds no documents. +//! +//! The point of these is the seam. A fake application answers every question +//! [`CloudApp`] asks and records what it was told to do, so what crosses the +//! boundary is visible without a spreadsheet, a service or a window. + +use std::sync::{Arc, Mutex}; + +use craft_cloud::{Capability, Entry, EntryKind}; + +use super::*; + +/// Everything the fake application was asked to do. +#[derive(Default)] +struct Did { + opened: Vec, + closed: Vec, + encoded: Vec, + /// The name each encode was asked for, which is where the bytes go. + encoded_as: Vec, + /// The content type beside it, where the provider gave one. + encoded_mime: Vec>, + marked_saved: Vec, + dropped: Vec, + said: Vec, + toasted: Vec, + urls: Vec, + conversations: Vec, + went_to_save_as: usize, +} + +const NOTES: DocumentKind = + DocumentKind { extensions: &["note", "txt"], mimes: &["text/plain", "application/x-note"], noun: "note", default_extension: "note" }; + +struct Notebook { + cloud: CloudFiles, + share: crate::share::ShareDialog, + presence: crate::presence::PresenceBar, + /// The document in the window, and what it is called. + open: Option<(u64, String)>, + /// What the next `open_bytes` answers with. + opens_as: Result, String>, + did: Arc>, +} + +impl Notebook { + fn new() -> Notebook { + Notebook { + cloud: CloudFiles::new(), + share: crate::share::ShareDialog::new(), + presence: crate::presence::PresenceBar::new(), + open: Some((1, "Untitled")).map(|(uid, name)| (uid, name.to_owned())), + opens_as: Ok(Some(1)), + did: Arc::new(Mutex::new(Did::default())), + } + } + + fn did(&self) -> std::sync::MutexGuard<'_, Did> { + self.did.lock().unwrap() + } +} + +impl CloudApp for Notebook { + fn cloud(&self) -> &CloudFiles { + &self.cloud + } + + fn cloud_mut(&mut self) -> &mut CloudFiles { + &mut self.cloud + } + + fn kind(&self) -> DocumentKind { + NOTES + } + + fn active(&self) -> Option { + self.open.as_ref().map(|(uid, _)| *uid) + } + + fn title(&self, _uid: u64) -> String { + self.open.as_ref().map(|(_, name)| name.clone()).unwrap_or_default() + } + + fn open_bytes(&mut self, name: &str, _bytes: Vec) -> Result, String> { + self.did().opened.push(name.to_owned()); + self.opens_as.clone() + } + + fn encode(&mut self, uid: u64, into: Destination<'_>) -> Result, String> { + self.did().encoded.push(uid); + self.did().encoded_as.push(into.name.to_owned()); + self.did().encoded_mime.push(into.mime.map(str::to_owned)); + Ok(b"a note".to_vec()) + } + + fn close(&mut self, uid: u64) { + self.did().closed.push(uid); + } + + fn mark_saved(&mut self, uid: u64) { + self.did().marked_saved.push(uid); + } + + fn drop_pending(&mut self, uid: u64) { + self.did().dropped.push(uid); + } + + fn sharing(&mut self) -> &mut crate::share::ShareDialog { + &mut self.share + } + + fn presence(&mut self) -> &mut crate::presence::PresenceBar { + &mut self.presence + } + + fn paint_icon(&self, _painter: &egui::Painter, _rect: egui::Rect, _kind: EntryKind, _colour: egui::Color32) {} + + fn open_url(&self, url: &str) { + self.did.lock().unwrap().urls.push(url.to_owned()); + } + + fn open_conversation(&self, url: &str) { + self.did.lock().unwrap().conversations.push(url.to_owned()); + } + + fn say(&mut self, text: String) { + self.did().said.push(text); + } + + fn toast(&mut self, text: String) { + self.did().toasted.push(text); + } + + fn go_to_save_as(&mut self) { + self.did().went_to_save_as += 1; + } + + fn app_name(&self) -> &str { + "Notes" + } +} + +/// A service that answers on the calling thread, so a job submitted during a +/// test is answered before the next line. +struct Service(Arc>>); + +impl CloudBackend for Service { + fn submit(&self, job: Job, post: Post) { + let answer = match &job { + Job::Account | Job::SignIn => Some(Event::Account(Ok(Account { + display: "Ada Lovelace".to_owned(), + capabilities: vec![Capability::Files, Capability::Etags], + provider_linked: true, + }))), + Job::List(path) => Some(Event::Listed { path: path.clone(), entries: Ok(vec![file("/Minutes.note"), folder("/Archive")]) }), + Job::Read { entry, into } => Some(Event::Read { entry: entry.clone(), into: *into, bytes: Ok(b"a note".to_vec()) }), + Job::Write { uid, entry, .. } => { + let mut stored = entry.clone(); + stored.etag = Some("v2".to_owned()); + Some(Event::Saved { uid: *uid, entry: Ok(stored) }) + } + _ => None, + }; + self.0.lock().unwrap().push(job); + if let Some(event) = answer { + post.send(event); + } + } +} + +fn file(path: &str) -> Entry { + Entry { + id: path.to_owned(), + room: format!("room:{path}"), + name: path.rsplit('/').next().unwrap_or(path).to_owned(), + path: path.to_owned(), + kind: EntryKind::File, + size: Some(2048), + modified: None, + mime: None, + etag: Some("v1".to_owned()), + writable: true, + shared_by: None, + } +} + +fn folder(path: &str) -> Entry { + Entry { kind: EntryKind::Folder, size: None, etag: None, ..file(path) } +} + +/// One frame's worth of draining, with no window. +fn pumped(app: &mut Notebook, ctx: &egui::Context) { + ctx.begin_pass(Default::default()); + pump(app, ctx); + // Nothing is painted here, so the pass's textures go nowhere. egui insists + // they are accounted for rather than dropped on the floor. + ctx.end_pass().textures_delta.clear(); +} + +fn wired() -> (Notebook, Arc>>, egui::Context) { + let mut app = Notebook::new(); + let jobs = Arc::new(Mutex::new(Vec::new())); + app.cloud.connect(Service(jobs.clone())); + (app, jobs, egui::Context::default()) +} + +#[test] +fn nothing_is_offered_until_a_service_is_wired() { + let app = Notebook::new(); + assert!(!available(&app), "a build with no service offers nothing cloud-shaped"); + assert_eq!(report(&app)["available"], false); +} + +#[test] +fn the_account_is_asked_for_once_per_run() { + let (mut app, jobs, ctx) = wired(); + start(&mut app); + start(&mut app); + let asked = jobs.lock().unwrap().iter().filter(|j| matches!(j, Job::Account)).count(); + assert_eq!(asked, 1, "a frame that asks again would ask on every frame"); + pumped(&mut app, &ctx); + assert_eq!(report(&app)["account"]["display"], "Ada Lovelace"); +} + +#[test] +fn only_the_documents_this_application_opens_are_offered() { + let (mut app, _jobs, ctx) = wired(); + start(&mut app); + pumped(&mut app, &ctx); + let listing = report(&app); + assert_eq!(listing["entries"], serde_json::json!(["Minutes.note", "Archive"])); + assert_eq!(listing["openable"], serde_json::json!(["Minutes.note"]), "a folder is not something to open"); +} + +#[test] +fn a_content_type_opens_a_document_with_no_extension() { + let mut exported = file("/exported"); + exported.mime = Some("text/plain; charset=utf-8".to_owned()); + assert!(opens(&exported, NOTES), "a provider that gives no extension still says what the bytes are"); + let mut picture = file("/holiday"); + picture.mime = Some("image/png".to_owned()); + assert!(!opens(&picture, NOTES)); + assert!(!opens(&folder("/Archive"), NOTES), "a folder opens nothing"); +} + +#[test] +fn a_typed_name_becomes_a_file_name_of_this_applications_own_kind() { + assert_eq!(document_name(" Minutes ", NOTES), "Minutes.note"); + assert_eq!(document_name("Minutes.txt", NOTES), "Minutes.txt", "an extension this application opens is kept"); + assert_eq!(document_name("Minutes.v2", NOTES), "Minutes.v2.note", "an unknown suffix is part of the name"); + assert_eq!(document_name("/a/b/Minutes", NOTES), "Minutes.note", "a pasted path cannot become a folder"); + assert_eq!(document_name(" ", NOTES), ""); +} + +#[test] +fn walking_up_from_the_root_has_nowhere_to_go() { + assert_eq!(parent_of(""), None); + assert_eq!(parent_of("/Archive"), Some(String::new())); + assert_eq!(parent_of("/Archive/2026"), Some("/Archive".to_owned())); +} + +#[test] +fn opening_hands_the_bytes_to_the_application_and_remembers_the_entry() { + let (mut app, _jobs, ctx) = wired(); + start(&mut app); + pumped(&mut app, &ctx); + open_entry(&mut app, file("/Minutes.note"), None); + pumped(&mut app, &ctx); + assert_eq!(app.did().opened, vec!["Minutes.note".to_owned()], "the application alone turns bytes into a document"); + let origin = report(&app)["origin"].clone(); + assert_eq!(origin["id"], "/Minutes.note", "the opaque handle is kept for the save"); + assert_eq!(origin["etag"], "v1", "so is the version it was read at"); + assert_eq!(origin["room"], "room:/Minutes.note", "and the collaboration identity, which is not the handle"); +} + +#[test] +fn a_reload_closes_the_document_it_replaced_only_once_the_new_one_is_open() { + let (mut app, _jobs, ctx) = wired(); + app.opens_as = Ok(Some(2)); + open_entry(&mut app, file("/Minutes.note"), Some(1)); + pumped(&mut app, &ctx); + assert_eq!(app.did().closed, vec![1], "the one it replaced is gone"); + assert_eq!(app.did().dropped, vec![1], "and so is whatever was recorded about saving it"); + + // A read the application could not use leaves the user's work where it was. + let (mut app, _jobs, ctx) = wired(); + app.opens_as = Err("these bytes are not a note".to_owned()); + open_entry(&mut app, file("/Minutes.note"), Some(1)); + pumped(&mut app, &ctx); + assert!(app.did().closed.is_empty(), "nothing was closed, because nothing opened"); + assert_eq!(app.did().said, vec!["these bytes are not a note".to_owned()]); +} + +#[test] +fn a_document_the_application_took_elsewhere_is_not_announced() { + let (mut app, _jobs, ctx) = wired(); + // What an application answers while it prompts for a password. + app.opens_as = Ok(None); + open_entry(&mut app, file("/Minutes.note"), None); + pumped(&mut app, &ctx); + assert_eq!(report(&app)["status"], serde_json::Value::Null); + assert_eq!(report(&app)["origin"], serde_json::Value::Null, "nothing came from the cloud yet"); +} + +#[test] +fn a_save_goes_out_under_the_version_the_document_was_read_at() { + let (mut app, jobs, ctx) = wired(); + open_entry(&mut app, file("/Minutes.note"), None); + pumped(&mut app, &ctx); + save(&mut app).unwrap(); + assert_eq!(app.did().encoded, vec![1], "the application alone turns a document into bytes"); + assert_eq!(app.did().encoded_as, vec!["Minutes.note".to_owned()], "the bytes are asked for under the name they are going to"); + let condition = jobs.lock().unwrap().iter().find_map(|j| match j { + Job::Write { entry, .. } => Some(entry.etag.clone()), + _ => None, + }); + assert_eq!(condition, Some(Some("v1".to_owned())), "the etag it was read at is the condition"); + pumped(&mut app, &ctx); + assert_eq!(app.did().marked_saved, vec![1], "the version that reached the service is the saved one"); + assert_eq!(report(&app)["origin"]["etag"], "v2", "and the document moves on to the version the service returned"); +} + +#[test] +fn a_read_only_share_is_never_saved_over() { + let (mut app, _jobs, ctx) = wired(); + let mut theirs = file("/Team.note"); + theirs.writable = false; + open_entry(&mut app, theirs, None); + pumped(&mut app, &ctx); + assert!(!has_target(&app), "Save has nowhere of its own to go"); + let refused = save(&mut app).unwrap_err(); + assert!(refused.contains("reading only"), "and saying why names the fix: {refused}"); +} + +#[test] +fn a_refused_save_is_put_to_the_user_and_never_retried() { + let (mut app, jobs, ctx) = wired(); + open_entry(&mut app, file("/Minutes.note"), None); + pumped(&mut app, &ctx); + jobs.lock().unwrap().clear(); + // What a service answers when somebody else saved first. + app.cloud.events.0.send(Event::Saved { uid: 1, entry: Err(Fault::Conflict) }).unwrap(); + pumped(&mut app, &ctx); + assert_eq!(report(&app)["conflict"]["name"], "Minutes.note", "the user is told, and asked what to do"); + assert_eq!(app.did().dropped, vec![1], "the version that did not land is forgotten"); + assert!(jobs.lock().unwrap().is_empty(), "nothing went out again on its own"); +} + +#[test] +fn no_account_yet_is_an_offer_to_link_and_never_an_error() { + let (mut app, _jobs, ctx) = wired(); + app.cloud.events.0.send(Event::Account(Err(Fault::NotLinked))).unwrap(); + pumped(&mut app, &ctx); + assert_eq!(report(&app)["link"], "offered"); + assert_eq!(report(&app)["accountError"], serde_json::Value::Null, "not having linked an account yet is not a failure"); + assert!(app.did().said.is_empty()); +} + +#[test] +fn a_browser_round_trip_is_polled_until_the_user_is_done() { + let (mut app, jobs, ctx) = wired(); + app.cloud.events.0.send(Event::Browser { url: "https://cloud.example/link/abc".to_owned(), handle: Some("abc".to_owned()) }).unwrap(); + pumped(&mut app, &ctx); + assert_eq!(app.did().urls, vec!["https://cloud.example/link/abc".to_owned()], "the browser is opened for them"); + assert_eq!(report(&app)["link"]["waiting"], "https://cloud.example/link/abc"); + + // The wait is not polled again until it is due. + jobs.lock().unwrap().clear(); + pumped(&mut app, &ctx); + assert!(jobs.lock().unwrap().iter().all(|j| !matches!(j, Job::LinkPoll(_))), "a poll every frame would be a poll every sixteen milliseconds"); + + if let Some(Link::Waiting { next_poll, .. }) = &mut app.cloud.link { + *next_poll = 0.0; + } + pumped(&mut app, &ctx); + assert!(jobs.lock().unwrap().iter().any(|j| matches!(j, Job::LinkPoll(_)))); +} + +#[test] +fn what_a_person_reads_is_about_their_own_kind_of_document() { + let app = Notebook::new(); + assert_eq!(Fault::Conflict.text(app.kind().noun), "Somebody else saved this note while you were editing it."); + assert_eq!(Fault::Conflict.code(), "conflict", "and the control channel reads the same fact as a word"); +} + +#[test] +fn working_together_needs_somewhere_for_the_room_to_be_keyed_on() { + let (mut app, jobs, ctx) = wired(); + app.cloud.account = Some(Account { display: "Ada".to_owned(), capabilities: vec![Capability::Conversation], provider_linked: true }); + assert!(can_converse(&app)); + // A document that has never been in the cloud has no handle. + work_together(&mut app); + assert_eq!(report(&app)["status"], "Save this note to the cloud first"); + assert!(jobs.lock().unwrap().iter().all(|j| !matches!(j, Job::Conversation(_)))); + + open_entry(&mut app, file("/Minutes.note"), None); + pumped(&mut app, &ctx); + work_together(&mut app); + let asked = jobs.lock().unwrap().iter().any(|j| matches!(j, Job::Conversation(id) if id == "/Minutes.note")); + assert!(asked, "the provider is asked about the handle it issued"); +} + +#[test] +fn a_conversation_uses_the_hosts_chat_opener() { + let (mut app, _, ctx) = wired(); + app.cloud + .events + .0 + .send(Event::Conversation(Ok(craft_cloud::Conversation { url: "https://cloud.example.net/call/room".to_owned(), name: "Talk".to_owned() }))) + .unwrap(); + + pumped(&mut app, &ctx); + + assert_eq!(app.did().conversations, ["https://cloud.example.net/call/room"]); + assert!(app.did().urls.is_empty(), "ordinary browser links and conversations remain separate host decisions"); +} + +#[test] +fn signing_out_forgets_everything_this_window_knew() { + let (mut app, jobs, ctx) = wired(); + start(&mut app); + pumped(&mut app, &ctx); + open_entry(&mut app, file("/Minutes.note"), None); + pumped(&mut app, &ctx); + sign_out(&mut app); + let state = report(&app); + assert_eq!(state["account"], serde_json::Value::Null); + assert_eq!(state["origin"], serde_json::Value::Null); + assert_eq!(state["entries"], serde_json::json!([])); + assert!(jobs.lock().unwrap().iter().any(|j| matches!(j, Job::SignOut)), "the service is told, so the saved token goes too"); +} + +#[test] +fn bytes_are_said_the_way_a_person_reads_them() { + assert_eq!(size_text(None), ""); + assert_eq!(size_text(Some(512)), "512 bytes"); + assert_eq!(size_text(Some(2048)), "2.0 KB"); + assert_eq!(size_text(Some(5 * 1024 * 1024)), "5.0 MB"); +} + +#[test] +fn a_destination_is_named_after_the_account_it_belongs_to() { + let mut app = Notebook::new(); + assert_eq!(destination_name(&app), "Cloud storage", "two entries reading the same tell nobody which account this is"); + app.cloud.account = Some(Account { display: "Ada Lovelace".to_owned(), capabilities: Vec::new(), provider_linked: true }); + assert_eq!(destination_name(&app), "Ada Lovelace"); +} + +#[test] +fn the_contracts_own_conflict_is_the_one_a_save_must_not_retry() { + assert_eq!(Fault::from(craft_cloud::Error::Conflict("Minutes.note".to_owned())), Fault::Conflict); + assert_eq!(Fault::from(craft_cloud::Error::Unauthenticated), Fault::Unauthenticated); + assert!(matches!(Fault::from(craft_cloud::Error::Unsupported("sharing")), Fault::Refused(_))); +} + +#[test] +fn a_save_asks_for_the_bytes_under_the_name_they_are_going_to() { + // A document opened as one format and saved in the application's own would + // hand the user a file no other application reads, under a name that says + // it is readable. The application cannot avoid that without being told + // where the bytes are going. + let (mut app, _jobs, ctx) = wired(); + let mut sheet = file("/figures.csv"); + sheet.mime = Some("text/csv".to_owned()); + open_entry(&mut app, sheet, None); + pumped(&mut app, &ctx); + save(&mut app).unwrap(); + assert_eq!(app.did().encoded_as, vec!["figures.csv".to_owned()]); + assert_eq!(app.did().encoded_mime, vec![Some("text/csv".to_owned())], "the provider's own word for it comes too"); + + // And Save As, where the name is the one just typed rather than the one + // the document arrived under. + let (mut app, _jobs, ctx) = wired(); + open_entry(&mut app, file("/figures.csv"), None); + pumped(&mut app, &ctx); + save_as(&mut app, "", "a copy.note").unwrap(); + assert_eq!(app.did().encoded_as, vec!["a copy.note".to_owned()]); + assert_eq!(app.did().encoded_mime, vec![None], "nothing is there yet, so nothing says what it is"); +} + +#[test] +fn a_destination_reads_its_own_extension() { + assert_eq!(Destination::new("figures.csv").extension(), "csv"); + assert_eq!(Destination::new("FIGURES.CSV").extension(), "csv", "a shouted name is the same name"); + assert_eq!(Destination::new("report.2026.xlsx").extension(), "xlsx", "the last one wins"); + // A bare name, which is what a web application's export commonly has. + // Everything an application can learn is in the content type instead. + assert_eq!(Destination::new("exported").extension(), ""); + assert_eq!(Destination::new("trailing.").extension(), ""); +} + +// ---- somebody who followed a shared link ---------------------------------- + +/// One frame of the title bar's right-hand end, as the accessibility tree +/// reported it. +/// +/// Read off the tree rather than out of the state, because the question is +/// what a recipient can reach. A field saying "no menu" proves nothing about +/// what was drawn. +fn title_bar(app: &mut Notebook) -> Vec<(egui::accesskit::Role, String)> { + let ctx = egui::Context::default(); + ctx.enable_accesskit(); + let raw = egui::RawInput { screen_rect: Some(egui::Rect::from_min_size(egui::Pos2::ZERO, egui::vec2(400.0, 48.0))), ..Default::default() }; + let mut output = ctx.run_ui(raw, |ui| who(app, ui)); + output.textures_delta.clear(); + let Some(tree) = output.platform_output.accesskit_update.as_ref() else { return Vec::new() }; + tree.nodes + .iter() + .filter_map(|(_, node)| { + // egui puts a plain label's text in the accessibility value and a + // control's text in the label, so both are text on screen. + node.label().or_else(|| node.value()).map(|text| (node.role(), text.to_owned())) + }) + .collect() +} + +fn pressable(seen: &[(egui::accesskit::Role, String)]) -> Vec { + seen.iter().filter(|(role, _)| *role == egui::accesskit::Role::Button).map(|(_, text)| text.clone()).collect() +} + +fn reads(seen: &[(egui::accesskit::Role, String)], fragment: &str) -> bool { + seen.iter().any(|(_, text)| text.contains(fragment)) +} + +#[test] +fn a_recipient_is_named_and_offered_nothing() { + let mut app = Notebook::new(); + app.cloud.as_guest("outsider@example.org", false); + let seen = title_bar(&mut app); + assert!(reads(&seen, "outsider@example.org"), "a recipient has no account, so their own address is the identity to show: {seen:?}"); + // The whole point. Every item an account menu holds is a sign-out, a + // switch or a storage connection, and a recipient has none of those. + assert_eq!(pressable(&seen), Vec::::new(), "nothing here may be pressed: {seen:?}"); + for offer in ["Sign in", "Sign out", "Account", "Connect storage", "Add an account"] { + assert!(!reads(&seen, offer), "a recipient was offered {offer}"); + } +} + +#[test] +fn a_read_only_share_says_so_before_anybody_tries_to_save() { + let mut app = Notebook::new(); + app.cloud.as_guest("outsider@example.org", true); + assert!(reads(&title_bar(&mut app), "Reading only"), "finding out at the moment of saving means doing the work twice"); + + app.cloud.as_guest("outsider@example.org", false); + assert!(!reads(&title_bar(&mut app), "Reading only"), "a share that allows an edit must not say otherwise"); +} + +#[test] +fn an_address_of_only_spaces_leaves_no_badge() { + let mut app = Notebook::new(); + app.cloud.as_guest(" ", false); + assert!(app.cloud.guest().is_none(), "a badge with nothing on it reads as a fault"); + assert_eq!(title_bar(&mut app), Vec::new()); +} + +#[test] +fn a_signed_in_window_still_gets_its_account_badge() { + let (mut app, _jobs, ctx) = wired(); + start(&mut app); + pumped(&mut app, &ctx); + let seen = title_bar(&mut app); + assert!(!pressable(&seen).is_empty(), "somebody with an account still has a menu to reach: {seen:?}"); + assert!(reads(&seen, "Ada Lovelace")); +} + +#[test] +fn the_report_says_who_this_window_is_for() { + let mut app = Notebook::new(); + assert_eq!(report(&app)["guest"], serde_json::Value::Null, "most windows belong to nobody in particular yet"); + app.cloud.as_guest("outsider@example.org", true); + assert_eq!(report(&app)["guest"], serde_json::json!({"recipient": "outsider@example.org", "readOnly": true})); +} diff --git a/crates/cloud-ui/src/cloud/title.rs b/crates/cloud-ui/src/cloud/title.rs new file mode 100644 index 000000000..2535caf68 --- /dev/null +++ b/crates/cloud-ui/src/cloud/title.rs @@ -0,0 +1,173 @@ +//! The right-hand end of a title bar, plus the Save As destination. +//! +//! Who is signed in, who else is here, and Share. Every office suite puts +//! these three in the same corner, in that order. A person coming from one of +//! them looks there first. + +use egui::{RichText, Ui}; + +use super::{CloudApp, CopyFormat, Guest, available, fill, link, origin, sign_in, sign_out, work_together}; + +/// Who this window is for. Who else is in the document, beside them. +/// +/// Three cases, each a different person. Somebody signed in gets the account +/// badge and its menu. Somebody who followed a shared link gets their own +/// address and no menu, having no account to manage. A build with no service +/// configured gets neither. A badge that cannot sign anybody in would be a +/// control that fails on use. +/// +/// Nothing is asked for here. Drawing a badge must not begin a sign-in: a +/// worker signs in before any job it is given, and it then blocks polling the +/// browser for minutes. Starting that from a paint call pops a browser open at +/// launch and leaves every later job queued behind it. Signing in is a gesture, +/// so it waits for a press. +pub fn who(app: &mut A, ui: &mut Ui) { + match app.cloud().guest().cloned() { + Some(guest) => shared_with(app, ui, &guest), + None => account(app, ui), + } + // Who else is here, beside whoever this window belongs to. Nothing is + // drawn while a person is working alone, which keeps a solitary document + // looking like one. + if app.presence().shared() { + ui.add_space(6.0); + app.presence().show(ui); + } +} + +/// Who a shared link was sent to, for somebody with no account anywhere. +/// +/// A label and not a button. Every item an account menu holds is a sign-out, a +/// switch or a storage connection, and a recipient has none of those. A +/// control that opens a menu of failures is worse than no control. +fn shared_with(app: &mut A, ui: &mut Ui, guest: &Guest) { + let explained = fill(app, "This document was shared with {}", &guest.recipient); + let reading = app.tr("Reading only"); + let dim = ui.visuals().weak_text_color(); + if guest.read_only { + // Said where the account would be. Both answer what this window may + // do with the document in it. A recipient who finds out at the moment + // of saving has already done the work twice. + ui.label(RichText::new(reading).small().color(dim)); + ui.add_space(6.0); + } + ui.label(RichText::new(guest.recipient.as_str()).small().color(dim)).on_hover_text(explained); +} + +/// The account badge and its menu, for somebody signed in. +fn account(app: &mut A, ui: &mut Ui) { + if !available(app) { + return; + } + let service = app.service(); + let known = app.cloud().account.as_ref().map(|a| crate::account::Account { + // One account for now. The control already holds a list, so a second + // deployment is a second entry here and nothing else changes. + id: "default".to_owned(), + display: a.display.clone(), + email: None, + service, + linked: a.provider_linked, + }); + let new_accounts: Vec<_> = known.into_iter().collect(); + let cloud = app.cloud_mut(); + if cloud.accounts.accounts() != new_accounts.as_slice() { + cloud.accounts.set(new_accounts); + } + cloud.accounts.show(ui); + + while let Some(action) = app.cloud_mut().accounts.take_action() { + use crate::account::AccountAction as Act; + match action { + // Signing in and connecting storage are two different things. + // Signing in is the device flow against the service, which every + // job already triggers when there is no token. Asking who the + // account is therefore starts it. Linking storage comes after, and + // needs that session to exist first. + Act::SignIn | Act::AddAccount => { + app.cloud_mut().sign_in_from_menu = true; + sign_in(app); + } + Act::Link(_) => link(app), + Act::SignOut(_) => sign_out(app), + // One account, so there is nothing to switch to yet. + Act::Use(_) => {} + Act::Manage(_) => { + let host = app.service(); + if !host.is_empty() { + app.open_url(&format!("https://{host}/account")); + } + } + } + } +} + +/// Whether the Share split button can be drawn. +/// +/// False until the service says the provider supports sharing. An application +/// draws whatever it offered before. A button that fails on use is worse than +/// no button at all. +pub fn shares(app: &mut A) -> bool { + app.sharing().available() +} + +/// Share, as a split button. +/// +/// Pressing the label shares, which is what somebody wants most of the time. +/// The chevron carries the variations, and working together is one of them. +/// `copies` are the application's own Save a Copy formats. Those have nothing +/// in common between one application and the next. +/// +/// Answers with the identifier of a copy format, when that is what was chosen. +/// Everything else is carried out here. +pub fn share_button(app: &mut A, ui: &mut Ui, copies: &[CopyFormat]) -> Option { + let noun = app.kind().noun; + let mut items = Vec::new(); + if app.cloud().can_converse() { + let detail = app.tr(&format!("Open a chat about this {noun}")); + items.push(crate::menu::MenuItem::new("talk", app.tr("Open chat")).detail(detail)); + } + for (at, copy) in copies.iter().enumerate() { + let item = crate::menu::MenuItem::new(copy.id.clone(), copy.label.clone()); + // A rule above the first copy, so sharing and exporting read as two + // groups rather than one long list. + items.push(if at == 0 && !items.is_empty() { item.separated() } else { item }); + } + let labels = crate::menu::MenuLabels::default(); + let primary = app.tr("Share"); + match crate::menu::split(ui, &primary, &items, &labels)? { + crate::menu::SplitHit::Primary => { + // The handle the provider issued, which is what a share is about. + // A document that has never been in the cloud has none, and the + // dialog says so. + let (id, title) = match origin(app) { + Some(origin) => (origin.entry.id.clone(), origin.entry.name.clone()), + None => (String::new(), app.active().map(|uid| app.title(uid)).unwrap_or_default()), + }; + app.sharing().open(id, title); + None + } + crate::menu::SplitHit::Item(what) if what == "talk" => { + work_together(app); + None + } + crate::menu::SplitHit::Item(format) => Some(format), + } +} + +/// What to call the cloud destination on a Save As page. +/// +/// The account's own name. The destination then reads as the user's own +/// storage. Somebody with an account on two deployments needs to know which +/// one a document is about to land in. +pub fn destination_name(app: &A) -> String { + app.cloud().account.as_ref().map(|a| a.display.clone()).filter(|display| !display.is_empty()).unwrap_or_else(|| app.tr("Cloud storage")) +} + +/// Whether the cloud destination is the one to offer first. +/// +/// A document that came from the cloud is saved back there unless the user says +/// otherwise. One that came from this computer is not. +pub fn prefers_cloud(app: &A) -> bool { + available(app) && origin(app).is_some() +} diff --git a/crates/cloud-ui/src/esign/backend.rs b/crates/cloud-ui/src/esign/backend.rs new file mode 100644 index 000000000..8d80a18f4 --- /dev/null +++ b/crates/cloud-ui/src/esign/backend.rs @@ -0,0 +1,92 @@ +//! Where the e-sign dialog's work happens, which is never on the frame. +//! +//! Same shape as [`crate::share::ShareBackend`]: the dialog states what it +//! wants, something behind this trait does the waiting, and answers arrive on +//! a channel keyed by sequence number. + +use craft_cloud::Contact; +use craft_esign::{CompletedDocument, Envelope, EnvelopeDraft, EsignCapability}; + +/// One thing the dialog needs done. +#[derive(Clone, Debug, PartialEq, Eq)] +pub enum Request { + /// What the signing service can actually do, and who is legally responsible. + Capabilities, + /// People matching what has been typed so far (cloud contacts). + Lookup { query: String, limit: usize }, + /// Create a draft from a document snapshot, then optionally send it. + Create { draft: Box, document: Vec, idempotency_key: String, send: bool }, + /// Current status of one envelope. + Status { envelope: String }, + /// Finished document bytes. + Completed { envelope: String }, + /// Cancel an in-flight envelope. + Void { envelope: String, reason: String }, + /// Nudge one recipient. + Remind { envelope: String, recipient: String }, +} + +/// What came back. +#[derive(Clone, Debug, PartialEq, Eq)] +pub enum Answer { + Capabilities { + capabilities: Vec, + responsible_party: String, + /// Whether a cloud account is attached so invitations can leave. + linked: bool, + }, + Lookup(Vec), + Created(Envelope), + Status(Envelope), + Completed(CompletedDocument), + Voided { + envelope: String, + }, + Reminded { + envelope: String, + recipient: String, + }, +} + +/// Where one answer goes. +pub struct Replier { + seq: u64, + tx: std::sync::mpsc::Sender<(u64, Result)>, +} + +impl Replier { + pub(crate) fn new(seq: u64, tx: std::sync::mpsc::Sender<(u64, Result)>) -> Replier { + Replier { seq, tx } + } + + pub fn seq(&self) -> u64 { + self.seq + } + + pub fn dup(&self) -> Replier { + Replier { seq: self.seq, tx: self.tx.clone() } + } + + pub fn answer(self, answer: Answer) { + self.deliver(Ok(answer)); + } + + pub fn refuse(self, reason: impl Into) { + self.deliver(Err(reason.into())); + } + + fn deliver(self, result: Result) { + let _ = self.tx.send((self.seq, result)); + } +} + +impl std::fmt::Debug for Replier { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + f.debug_struct("Replier").field("seq", &self.seq).finish() + } +} + +/// Somewhere a [`Request`] can run without blocking a frame. +pub trait EsignBackend { + fn submit(&self, request: Request, reply: Replier); +} diff --git a/crates/cloud-ui/src/esign/coderabbit_repro.rs b/crates/cloud-ui/src/esign/coderabbit_repro.rs new file mode 100644 index 000000000..c7c954002 --- /dev/null +++ b/crates/cloud-ui/src/esign/coderabbit_repro.rs @@ -0,0 +1,216 @@ +//! Regression tests for the CodeRabbit findings reviewed on PR #661, +//! reproduced against ef496161 (storytold/craft-libs#661). +//! +//! Reuses `review_repro`'s `Hold` backend and helpers: a test chooses when, +//! and in what order, a held request is answered. + +use craft_esign::{Envelope, EnvelopeStatus}; + +use super::review_repro::{Hold, envelope_for, ready, send, who}; +use super::*; + +/// Only one capabilities probe is ever outstanding for the current backend. +/// `set_backend` clears `caps_seq`, but a reply already in flight from the +/// backend being replaced keeps its old sequence number: it must not +/// overwrite capabilities, responsible or linked for the new backend when +/// it finally arrives. +#[test] +fn a_capabilities_reply_from_a_replaced_backend_does_not_overwrite_the_new_ones() { + let hold_a = Hold::default(); + let mut dialog = EsignDialog::default(); + dialog.set_backend(hold_a.clone()); + dialog.pump(0.0); + let (_, caps_a) = hold_a.take(|r| matches!(r, Request::Capabilities)); + + // The backend is replaced before A's capabilities probe answers. + let hold_b = Hold::default(); + dialog.set_backend(hold_b.clone()); + dialog.pump(0.1); + let (_, caps_b) = hold_b.take(|r| matches!(r, Request::Capabilities)); + + caps_b.answer(Answer::Capabilities { capabilities: vec![EsignCapability::Envelopes], responsible_party: "B".into(), linked: true }); + dialog.pump(0.2); + assert_eq!(dialog.responsible.as_deref(), Some("B")); + + // A's reply, from the replaced backend, arrives after B's already installed. + caps_a.answer(Answer::Capabilities { capabilities: vec![EsignCapability::Void], responsible_party: "A".into(), linked: false }); + dialog.pump(0.3); + + assert_eq!(dialog.responsible.as_deref(), Some("B"), "a stale Capabilities reply from a replaced backend overwrote the new backend's"); + assert!(dialog.linked, "a stale Capabilities reply from a replaced backend turned linked back off"); +} + +/// A document's revision changing is itself a context change: a reply for +/// the bytes under the old `document_etag` must not install under the new +/// one, even though the document id never changed. +#[test] +fn stale_create_reply_for_old_revision_is_dropped_after_reopen_with_new_etag() { + let (mut dialog, hold) = ready(); + dialog.open("doc-A".into(), "A.pdf".into(), Some("etag-1".into()), who("alice")); + send(&mut dialog, b"A bytes etag1"); + dialog.open("doc-A".into(), "A.pdf".into(), Some("etag-2".into()), who("alice")); + + let (_, create) = hold.take(|r| matches!(r, Request::Create { .. })); + create.answer(Answer::Created(envelope_for("doc-A", "alice"))); + dialog.pump(1.0); + + assert!( + dialog.envelope.is_none(), + "stale reply for etag-1 installed into the etag-2 opening: {:?}", + dialog.envelope.as_ref().map(|e| e.id.clone()) + ); +} + +/// `take_send_request` already handed the application doc-A's draft; the +/// dialog then reopens for doc-B before the application calls +/// `submit_request`. The reply this produces must still be tagged with +/// doc-A's context, not doc-B's. +#[test] +fn create_reply_for_a_request_taken_before_reopening_does_not_install_in_the_new_document() { + let (mut dialog, hold) = ready(); + dialog.open("doc-A".into(), "A.pdf".into(), None, who("alice")); + dialog.add_email("bob@example.com".into()); + dialog.queue_send(); + let out = dialog.take_send_request().expect("send produced a request"); + + // The dialog moves on before the application gets around to submitting + // what it already took. + dialog.open("doc-B".into(), "B.pdf".into(), None, who("alice")); + dialog.submit_request(Request::Create { + draft: Box::new(out.draft), + document: b"A bytes".to_vec(), + idempotency_key: out.idempotency_key, + send: true, + }); + + let (_, create) = hold.take(|r| matches!(r, Request::Create { .. })); + create.answer(Answer::Created(envelope_for("doc-A", "alice"))); + dialog.pump(1.0); + + assert!( + dialog.envelope.is_none(), + "doc-A's envelope, submitted after reopening doc-B, installed into doc-B's dialog: {:?}", + dialog.envelope.as_ref().map(|e| e.id.clone()) + ); +} + +/// An untaken `SendRequest` is specific to the context that queued it; it +/// must not survive into a reopened dialog for another document. +#[test] +fn an_untaken_send_request_does_not_survive_reopening_for_another_document() { + let (mut dialog, _hold) = ready(); + dialog.open("doc-A".into(), "A.pdf".into(), None, who("alice")); + dialog.add_email("bob@example.com".into()); + dialog.queue_send(); + + dialog.open("doc-B".into(), "B.pdf".into(), None, who("alice")); + + assert!(dialog.take_send_request().is_none(), "doc-B's dialog still held doc-A's untaken send request"); +} + +/// `note_create_result` is the synchronous twin of `submit_request`: an app +/// that handles create itself, rather than through the backend channel, +/// reports the outcome here. It must drop a result for a context the dialog +/// has already left, exactly as a channel reply would. +#[test] +fn note_create_result_for_a_previous_document_does_not_install_in_the_reopened_dialog() { + let (mut dialog, _hold) = ready(); + dialog.open("doc-A".into(), "A.pdf".into(), None, who("alice")); + dialog.add_email("bob@example.com".into()); + dialog.queue_send(); + let _out = dialog.take_send_request().expect("send produced a request"); + + dialog.open("doc-B".into(), "B.pdf".into(), None, who("alice")); + dialog.note_create_result(Ok(envelope_for("doc-A", "alice"))); + + assert!( + dialog.envelope.is_none(), + "doc-A's result, reported after reopening doc-B, installed into doc-B's dialog: {:?}", + dialog.envelope.as_ref().map(|e| e.id.clone()) + ); +} + +/// `Replier::dup` is the only way a backend can answer one sequence twice. +/// The dialog answers the first reply normally, but a second reply for the +/// same (already resolved) sequence must drop unconditionally, not reach +/// the match arms with no context left to check against. +#[test] +fn a_duplicated_answer_for_an_already_resolved_sequence_is_dropped() { + let (mut dialog, hold) = ready(); + dialog.open("doc-A".into(), "A.pdf".into(), None, who("alice")); + send(&mut dialog, b"A bytes"); + + let (_, create) = hold.take(|r| matches!(r, Request::Create { .. })); + let dup = create.dup(); + create.answer(Answer::Created(envelope_for("doc-A", "alice"))); + dialog.pump(1.0); + assert_eq!(dialog.envelope.as_ref().map(|e| e.id.clone()), Some("env-doc-A".to_owned()), "the first answer should have installed normally"); + + // The dialog moves on; a backend still holding `dup` from the first + // request answers it again. + dialog.open("doc-B".into(), "B.pdf".into(), None, who("alice")); + dup.answer(Answer::Created(envelope_for("doc-A", "alice"))); + dialog.pump(2.0); + + let shown = dialog.envelope.as_ref().and_then(|e| e.document_id.clone()); + assert!( + shown.is_none() || shown.as_deref() == Some("doc-B"), + "a duplicate answer for the first request reinstalled doc-A's envelope into doc-B's dialog: {shown:?}" + ); +} + +/// `busy` belongs to whichever operation is still pending. A lookup that +/// fails while a create is genuinely in flight must not report the create +/// as finished. +#[test] +fn a_failed_lookup_does_not_clear_busy_for_a_pending_create() { + let (mut dialog, hold) = ready(); + dialog.open("doc-A".into(), "A.pdf".into(), None, who("alice")); + send(&mut dialog, b"A bytes"); + assert!(dialog.busy, "queue_send should have left the dialog busy"); + + dialog.query = "ca".into(); + dialog.query_changed_at = 0.0; + dialog.maybe_lookup(1.0); + let (_, lookup) = hold.take(|r| matches!(r, Request::Lookup { .. })); + lookup.refuse("lookup failed"); + dialog.pump(2.0); + + assert!(dialog.busy, "a failed lookup cleared busy while the create for doc-A was still pending"); +} + +/// Two "Refresh status" clicks before either reply arrives race two +/// `Request::Status` calls. If the older one answers after the newer one +/// already installed, it must not overwrite the newer status. +#[test] +fn an_older_status_reply_does_not_overwrite_a_newer_one() { + let (mut dialog, hold) = ready(); + dialog.open("doc-A".into(), "A.pdf".into(), None, who("alice")); + send(&mut dialog, b"A bytes"); + let (_, create) = hold.take(|r| matches!(r, Request::Create { .. })); + create.answer(Answer::Created(envelope_for("doc-A", "alice"))); + dialog.pump(1.0); + let env_id = dialog.envelope.as_ref().expect("created").id.clone(); + + dialog.busy = true; + let seq1 = dialog.submit_in_context(Request::Status { envelope: env_id.clone() }); + dialog.pending_op_seq = Some(seq1); + dialog.status_seq = seq1; + dialog.busy = true; + let seq2 = dialog.submit_in_context(Request::Status { envelope: env_id.clone() }); + dialog.pending_op_seq = Some(seq2); + dialog.status_seq = seq2; + + let (_, status1) = hold.take(|r| matches!(r, Request::Status { .. })); + let (_, status2) = hold.take(|r| matches!(r, Request::Status { .. })); + + // The newer request (seq2) answers first. + status2.answer(Answer::Status(Envelope { status: EnvelopeStatus::Completed, ..envelope_for("doc-A", "alice") })); + dialog.pump(2.0); + assert_eq!(dialog.envelope.as_ref().map(|e| e.status), Some(EnvelopeStatus::Completed)); + + // The older request (seq1), issued first, answers last. + status1.answer(Answer::Status(Envelope { status: EnvelopeStatus::Sent, ..envelope_for("doc-A", "alice") })); + dialog.pump(3.0); + assert_eq!(dialog.envelope.as_ref().map(|e| e.status), Some(EnvelopeStatus::Completed), "an older status reply overwrote a newer one"); +} diff --git a/crates/cloud-ui/src/esign/coderabbit_round2_repro.rs b/crates/cloud-ui/src/esign/coderabbit_round2_repro.rs new file mode 100644 index 000000000..190ca1fa9 --- /dev/null +++ b/crates/cloud-ui/src/esign/coderabbit_round2_repro.rs @@ -0,0 +1,108 @@ +//! Regression tests for CodeRabbit's second review pass on PR #661, +//! reproduced against 1e84947c (storytold/craft-libs#661). +//! +//! Reuses `review_repro`'s `Hold` backend and helpers, the same as +//! `coderabbit_repro`. + +use craft_esign::{Envelope, EnvelopeStatus}; + +use super::review_repro::{Hold, envelope_for, ready, send, who}; +use super::*; + +/// A host can drive `Request::Status` through the public `submit_request` +/// path directly, not only through `status_panel`'s own "Refresh status" +/// button. That path must register `status_seq` too, or the reply it +/// produces fails the supersession guard added for the button's path and is +/// dropped. +#[test] +fn submit_request_for_a_public_status_submission_registers_status_seq() { + let (mut dialog, hold) = ready(); + dialog.open("doc-A".into(), "A.pdf".into(), None, who("alice")); + send(&mut dialog, b"A bytes"); + let (_, create) = hold.take(|r| matches!(r, Request::Create { .. })); + create.answer(Answer::Created(envelope_for("doc-A", "alice"))); + dialog.pump(1.0); + let env_id = dialog.envelope.as_ref().expect("created").id.clone(); + + dialog.submit_request(Request::Status { envelope: env_id }); + let (_, status) = hold.take(|r| matches!(r, Request::Status { .. })); + status.answer(Answer::Status(Envelope { status: EnvelopeStatus::Completed, ..envelope_for("doc-A", "alice") })); + dialog.pump(2.0); + + assert_eq!( + dialog.envelope.as_ref().map(|e| e.status), + Some(EnvelopeStatus::Completed), + "a Status reply submitted through the public submit_request path was dropped by the status_seq guard" + ); +} + +/// `available()` stops asking again once the service has reported +/// `Envelopes`, so a backend whose `linked` value changes out of band (the +/// user signs in after the dialog already probed) is never re-asked unless +/// something clears the cached capabilities. `reset_capabilities` is that +/// something, on the same backend instance. +#[test] +fn reset_capabilities_reprobes_the_same_backend_after_an_out_of_band_sign_in() { + let hold = Hold::default(); + let mut dialog = EsignDialog::default(); + dialog.set_backend(hold.clone()); + dialog.pump(0.0); + let (_, caps1) = hold.take(|r| matches!(r, Request::Capabilities)); + caps1.answer(Answer::Capabilities { capabilities: vec![EsignCapability::Envelopes], responsible_party: "Stub Signing".into(), linked: false }); + dialog.pump(0.1); + assert!(dialog.available()); + assert!(!dialog.linked); + + // Available is already true, so pump's own retry condition + // (`!available() && ...`) never fires again on its own, no matter how + // much time passes. + for t in 0..5 { + dialog.pump(0.2 + f64::from(t)); + } + + // The user signs in; nothing about the backend instance changes, so + // only an explicit reset asks again. + dialog.reset_capabilities(); + dialog.pump(1.0); + let (_, caps2) = hold.take(|r| matches!(r, Request::Capabilities)); + caps2.answer(Answer::Capabilities { capabilities: vec![EsignCapability::Envelopes], responsible_party: "Stub Signing".into(), linked: true }); + dialog.pump(1.1); + + assert!(dialog.linked, "reset_capabilities did not pick up the backend's new linked state"); +} + +/// The captured send context belongs only to the create submission that +/// answers a taken [`SendRequest`]. A status refresh submitted for the +/// current document while another document's send is still outstanding must +/// carry the current context, or `pump` drops its reply as belonging to the +/// abandoned send. +#[test] +fn status_for_the_current_document_is_not_consumed_by_an_outstanding_send_from_another() { + let (mut dialog, hold) = ready(); + + // Document A's send is taken by the app but never submitted: its captured + // context stays pending. The `send` helper would submit the create and + // consume that context, which is exactly what this test must avoid. + dialog.open("doc-A".into(), "A.pdf".into(), None, who("alice")); + dialog.add_email("bob@example.com".into()); + dialog.queue_send(); + let taken = dialog.take_send_request(); + assert!(taken.is_some(), "A's send request was taken, leaving its context pending"); + + // The dialog moves on to document B, which already has an envelope the + // host wants a status for. + dialog.open("doc-B".into(), "B.pdf".into(), None, who("alice")); + dialog.envelope = Some(envelope_for("doc-B", "alice")); + let env_id = dialog.envelope.as_ref().map(|e| e.id.clone()).unwrap_or_default(); + + dialog.submit_request(Request::Status { envelope: env_id }); + let (_, status) = hold.take(|r| matches!(r, Request::Status { .. })); + status.answer(Answer::Status(Envelope { status: EnvelopeStatus::Completed, ..envelope_for("doc-B", "alice") })); + dialog.pump(1.0); + + assert_eq!( + dialog.envelope.as_ref().map(|e| e.status), + Some(EnvelopeStatus::Completed), + "B's status reply was dropped because the status request consumed A's outstanding send context" + ); +} diff --git a/crates/cloud-ui/src/esign/mod.rs b/crates/cloud-ui/src/esign/mod.rs new file mode 100644 index 000000000..64087bbd5 --- /dev/null +++ b/crates/cloud-ui/src/esign/mod.rs @@ -0,0 +1,1037 @@ +//! Request-signatures dialog, the same one in every Craft app that sends PDFs. +//! +//! Nothing here opens a socket. Every call goes through [`EsignBackend`]. +//! Nothing here blocks: answers arrive on a channel and are read once per +//! frame. Signing is not sharing: recipients are never [`craft_cloud::ShareTarget`]s. + +use std::collections::HashMap; +use std::sync::mpsc::{Receiver, Sender}; +use std::time::Duration; + +use craft_cloud::{Contact, Identity}; +use craft_esign::{Envelope, EnvelopeDraft, EnvelopeStatus, EsignCapability, FieldPlacement, Recipient, RecipientStatus}; +use egui::{Context, RichText, Ui}; + +mod backend; +#[cfg(test)] +mod coderabbit_repro; +#[cfg(test)] +mod coderabbit_round2_repro; +#[cfg(test)] +mod review_repro; + +pub use backend::{Answer, EsignBackend, Replier, Request}; + +/// How long after the last keystroke the dialog asks for matches. +pub const DEBOUNCE: Duration = Duration::from_millis(200); + +const MATCHES: usize = 8; +const MIN_QUERY: usize = 2; +const RETRY: f64 = 20.0; + +type Inbox = (u64, Result); + +/// What dialog state a reply belongs to: which document revision, under +/// which signed-in account, opened which time. A reply installs only when +/// this still matches the dialog's current context; see +/// [`EsignDialog::submit_in_context`] and [`EsignDialog::pump`]. Deliberately +/// excludes incidental UI state such as search text, which changes without +/// the dialog meaning something new. +/// +/// `opening` is bumped every time [`EsignDialog::open`] actually changes +/// something (document, revision or account). `document_etag` alone would +/// already separate two revisions of the same document id, but it cannot +/// separate "document A, closed, then A opened again" from the first +/// opening: both carry the same id and the same etag. `opening` does. +#[derive(Clone, Debug, PartialEq, Eq)] +struct EsignContext { + document_id: String, + document_etag: Option, + account: Option, + opening: u64, +} + +/// Every string the dialog shows. +#[derive(Clone, Debug)] +pub struct EsignLabels { + pub title: String, + pub recipients: String, + pub recipient_hint: String, + pub searching: String, + pub no_matches: String, + pub add_address: String, + pub role: String, + pub message: String, + pub send: String, + pub sending: String, + pub close: String, + pub loading: String, + pub responsible: String, + pub no_service: String, + pub sign_in_first: String, + pub need_recipient: String, + /// Shown instead of adding the person, when a search match has no email + /// address the provider can invite. + pub contact_missing_email: String, + pub status: String, + pub void: String, + pub remind: String, + pub download: String, + pub request: String, + /// Caption of the status panel's manual refresh action. + pub refresh: String, +} + +impl Default for EsignLabels { + fn default() -> EsignLabels { + EsignLabels { + title: "Request signatures".into(), + recipients: "Signers".into(), + recipient_hint: "Name or email".into(), + searching: "Searching…".into(), + no_matches: "No matches".into(), + add_address: "Add email address".into(), + role: "Role".into(), + message: "Message".into(), + send: "Send".into(), + sending: "Sending…".into(), + close: "Close".into(), + loading: "Loading…".into(), + responsible: "Signing is provided by {party}. That party holds legal and compliance responsibility for the ceremony.".into(), + no_service: "Signatures cannot be requested here.".into(), + sign_in_first: "Sign in to request signatures.".into(), + need_recipient: "Add at least one signer.".into(), + contact_missing_email: "This contact has no email address to invite.".into(), + status: "Status".into(), + void: "Void".into(), + remind: "Remind".into(), + download: "Download completed".into(), + request: "Request signatures".into(), + refresh: "Refresh status".into(), + } + } +} + +/// What the application must supply when the user presses Send. +/// +/// The dialog holds recipients and copy; the application owns the document +/// bytes and encodes them, then submits [`Request::Create`] through the backend. +#[derive(Clone, Debug, PartialEq, Eq)] +pub struct SendRequest { + pub draft: EnvelopeDraft, + pub idempotency_key: String, +} + +/// One Request signatures dialog. +pub struct EsignDialog { + open: bool, + labels: EsignLabels, + backend: Option>, + capabilities: Option>, + responsible: Option, + linked: bool, + asked_caps_at: Option, + caps_seq: Option, + draft_idempotency_key: Option, + seq: u64, + tx: Sender, + rx: Receiver, + newest: u64, + /// Context (document plus account) each in-flight context-sensitive + /// request was issued under. Consulted, then removed, in [`Self::pump`]. + contexts: HashMap, + /// Sequences whose context has already been consulted once in + /// [`Self::pump`], bounded to the most recent entries. A backend that + /// answers the same sequence twice (via [`Replier::dup`]) has its second + /// answer dropped unconditionally instead of re-entering the match arms + /// with no context to check. + consumed: std::collections::HashSet, + consumed_order: std::collections::VecDeque, + /// The sequence that currently owns `busy`, if any. An answer (success or + /// failure) for any other sequence must not clear `busy` on its behalf. + pending_op_seq: Option, + /// The most recently issued `Request::Status` sequence. An older status + /// reply that arrives after a newer one has already installed is + /// superseded and dropped. + status_seq: u64, + /// How many times [`Self::open`] has actually changed something. Part of + /// [`EsignContext`]; see its docs. + opening: u64, + document_id: String, + document_etag: Option, + document_title: String, + sender: Option, + query: String, + query_changed_at: f64, + lookup_seq: u64, + last_lookup_query: String, + matches: Vec, + looking: bool, + recipients: Vec, + /// How many recipients have ever been added for the document currently + /// open, used to label the next one. Monotonic, not derived from the + /// current recipient count or roles in use: a count- or scan-based label + /// is free to repeat once the recipient holding it is removed, and a + /// freed role can then bind a new recipient to an old recipient's + /// placements. Reset in [`Self::open`] alongside `recipients`. + next_role_number: u32, + message: String, + placements: Vec, + busy: bool, + error: Option, + envelope: Option, + send_out: Option, + /// The context [`Self::queue_send`] captured for the still-outstanding + /// [`SendRequest`], consumed by [`Self::submit_request`] or + /// [`Self::note_create_result`] so a reply is tagged with the context the + /// send was queued under, not whatever context is current when the + /// application finally submits it. + pending_send_context: Option, + completed_bytes: Option>, + account_fingerprint: Option, +} + +impl Default for EsignDialog { + fn default() -> EsignDialog { + let (tx, rx) = std::sync::mpsc::channel(); + EsignDialog { + open: false, + labels: EsignLabels::default(), + backend: None, + capabilities: None, + responsible: None, + linked: false, + asked_caps_at: None, + caps_seq: None, + draft_idempotency_key: None, + seq: 0, + tx, + rx, + newest: 0, + contexts: HashMap::new(), + consumed: std::collections::HashSet::new(), + consumed_order: std::collections::VecDeque::new(), + pending_op_seq: None, + status_seq: 0, + opening: 0, + document_id: String::new(), + document_etag: None, + document_title: String::new(), + sender: None, + query: String::new(), + query_changed_at: 0.0, + lookup_seq: 0, + last_lookup_query: String::new(), + matches: Vec::new(), + looking: false, + recipients: Vec::new(), + next_role_number: 0, + message: String::new(), + placements: Vec::new(), + busy: false, + error: None, + envelope: None, + send_out: None, + pending_send_context: None, + completed_bytes: None, + account_fingerprint: None, + } + } +} + +/// A send operation id no other send in this process has used, from a random +/// start so one saved by an earlier process is unlikely to repeat either. +/// Mirrors `docking::model::fresh_window_id`: a counter kept on one +/// [`EsignDialog`] repeats across two dialog instances (two windows, or one +/// replaced after a document closes), and two sends sharing an idempotency +/// key have a conforming provider return the first envelope for the second. +fn fresh_send_id() -> u64 { + use std::hash::{BuildHasher, Hasher}; + use std::sync::OnceLock; + use std::sync::atomic::{AtomicU64, Ordering}; + static NEXT: OnceLock = OnceLock::new(); + let next = NEXT.get_or_init(|| AtomicU64::new(std::collections::hash_map::RandomState::new().build_hasher().finish() >> 1)); + next.fetch_add(1, Ordering::Relaxed) +} + +/// Whether the dialog stays open after one [`EsignDialog::show`] frame. +/// +/// `window_open` is egui's own title-bar close control; `dialog_open` is +/// whatever [`EsignDialog::ui`] already decided, such as a Close button. +/// Either one closing the dialog must stick: a plain `window_open` would +/// let the window's unchanged binding undo a Close button clicked inside +/// the same frame. +fn still_open(window_open: bool, dialog_open: bool) -> bool { + window_open && dialog_open +} + +impl EsignDialog { + pub fn new() -> EsignDialog { + EsignDialog::default() + } + + pub fn labels(mut self, labels: EsignLabels) -> EsignDialog { + self.labels = labels; + self + } + + pub fn set_backend(&mut self, backend: impl EsignBackend + 'static) { + self.backend = Some(Box::new(backend)); + self.reset_capabilities(); + } + + /// Probe the current backend again for capabilities and link state. + /// + /// `available()` never asks again once the service has reported + /// [`EsignCapability::Envelopes`]; the retry in [`Self::pump`] is for a + /// backend that is still unavailable, not for a `linked` value that is + /// stale after an out-of-band sign-in. Call this once that sign-in + /// completes on the backend already set, when replacing it with + /// [`Self::set_backend`] would be artificial. A reply still in flight + /// from the probe this replaces is dropped in [`Self::pump`] exactly as + /// one from a backend [`Self::set_backend`] already replaced is: + /// `caps_seq` is cleared here the same way. + pub fn reset_capabilities(&mut self) { + self.capabilities = None; + self.asked_caps_at = None; + self.caps_seq = None; + } + + /// False until the service reports [`EsignCapability::Envelopes`]. + pub fn available(&self) -> bool { + self.capabilities.as_ref().is_some_and(|c| c.contains(&EsignCapability::Envelopes)) + } + + pub fn is_open(&self) -> bool { + self.open + } + + /// Open for a document. `sender` is the active account identity. + pub fn open(&mut self, document_id: String, document_title: String, document_etag: Option, sender: Identity) { + let fingerprint = format!("{}@{}", sender.id, sender.email.as_deref().unwrap_or("")); + let account_changed = self.account_fingerprint.as_deref() != Some(fingerprint.as_str()); + let document_changed = self.document_id != document_id; + let revision_changed = self.document_etag != document_etag; + if account_changed || document_changed || revision_changed { + self.recipients.clear(); + self.next_role_number = 0; + self.message.clear(); + self.envelope = None; + self.completed_bytes = None; + self.error = None; + self.draft_idempotency_key = None; + // A's fields must never reappear as B's: see the Major finding + // this guards against. + self.placements.clear(); + // An untaken send request was built for the context being left; + // drop it so a later `take_send_request` cannot hand the + // application A's draft to submit under B's dialog. + // `pending_send_context`, captured once the request is taken, is + // deliberately left alone here: see its field doc. + self.send_out = None; + self.opening = self.opening.wrapping_add(1); + // Any job still in flight was issued for the context being left. + // Its reply will be dropped in `pump` (context no longer + // matches), so nothing will ever clear `busy` on its behalf. + self.busy = false; + self.pending_op_seq = None; + } + self.account_fingerprint = Some(fingerprint); + self.document_id = document_id; + self.document_title = document_title; + self.document_etag = document_etag; + self.sender = Some(sender); + self.open = true; + self.query.clear(); + self.matches.clear(); + } + + pub fn close(&mut self) { + self.open = false; + } + + /// Field placements the app prepared (page-normalised). Replaces any prior set. + pub fn set_placements(&mut self, placements: Vec) { + self.placements = placements; + // Same reasoning as `add_contact`/`add_email`/removing a recipient: the + // fields a retried create would send have changed, so a key from + // before this call must not be reused for them. + self.draft_idempotency_key = None; + } + + /// What Send asked the application to encode and submit, if anything. + pub fn take_send_request(&mut self) -> Option { + self.send_out.take() + } + + /// Submit a request through the host backend (for example after the app + /// encoded document bytes for a [`SendRequest`], or a status refresh the + /// host drives itself rather than through [`Self::status_panel`]'s own + /// button). + /// + /// Tags the reply with the context [`Self::queue_send`] captured when it + /// built the [`SendRequest`] being submitted, not whatever context is + /// current now. The application can encode bytes, or the dialog can be + /// reopened for another document or account, before this runs; a reply + /// for a [`SendRequest`] built under a now-abandoned context must drop in + /// [`Self::pump`] exactly as one issued under that context would, not + /// install under whichever context happens to be current when this is + /// finally called. + pub fn submit_request(&mut self, request: Request) { + // The captured send context belongs to the create submission answering + // a taken [`SendRequest`], and to nothing else. A status refresh (or + // any other request) submitted while that send is still outstanding is + // the current document's business: tagging it with the old send's + // context would make `pump` drop its reply as stale. + let context = if matches!(request, Request::Create { .. }) { + self.pending_send_context.take().unwrap_or_else(|| self.current_context()) + } else { + self.current_context() + }; + // A public `Request::Status` submission is request-specific routing + // state too: without this, `pump`'s `status_seq` guard never sees + // this sequence and drops the reply that comes back for it. + let is_status = matches!(request, Request::Status { .. }); + let seq = self.submit(request); + self.contexts.insert(seq, context); + self.pending_op_seq = Some(seq); + if is_status { + self.status_seq = seq; + } + } + + /// Completed document bytes after a successful download request. + pub fn take_completed_bytes(&mut self) -> Option> { + self.completed_bytes.take() + } + + /// Tell the dialog create/send finished (or failed) after the app submitted. + /// + /// Gated the same way as [`Self::submit_request`]: when a context was + /// captured for the outstanding send, a result reported after the + /// dialog moved on to another document or account is dropped instead of + /// installing under the new context. + pub fn note_create_result(&mut self, result: Result) { + if let Some(context) = self.pending_send_context.take() + && context != self.current_context() + { + return; + } + self.busy = false; + self.pending_op_seq = None; + match result { + Ok(env) => { + self.envelope = Some(env); + self.error = None; + } + Err(reason) => self.error = Some(reason), + } + } + + fn submit(&mut self, request: Request) -> u64 { + self.seq = self.seq.saturating_add(1); + let seq = self.seq; + self.newest = seq; + if let Some(backend) = self.backend.as_ref() { + backend.submit(request, Replier::new(seq, self.tx.clone())); + } else { + let _ = self.tx.send((seq, Err("no e-sign backend".into()))); + } + seq + } + + /// The context (document revision plus account, plus which opening) a + /// reply must still match to install. See [`EsignContext`]. + fn current_context(&self) -> EsignContext { + EsignContext { + document_id: self.document_id.clone(), + document_etag: self.document_etag.clone(), + account: self.account_fingerprint.clone(), + opening: self.opening, + } + } + + /// Like [`Self::submit`], but tags the request with the dialog's current + /// context. Everything that acts on one envelope (create, status, + /// completed, void, remind) goes through here. Capabilities does not: + /// it is answered before a document is ever opened and stays valid + /// across documents and accounts. Lookup does: a contact search issued + /// before a reopen must not populate the reopened dialog either. + fn submit_in_context(&mut self, request: Request) -> u64 { + let seq = self.submit(request); + self.contexts.insert(seq, self.current_context()); + seq + } + + /// Remembers that `seq`'s context has already been consulted once in + /// [`Self::pump`], bounded to the most recently consulted sequences. A + /// backend that answers the same sequence twice (only possible through + /// [`Replier::dup`]) has its second answer dropped unconditionally, + /// instead of reaching the match arms with no context left to check. + fn remember_consumed(&mut self, seq: u64) { + const TRACKED: usize = 64; + if self.consumed_order.len() >= TRACKED + && let Some(oldest) = self.consumed_order.pop_front() + { + self.consumed.remove(&oldest); + } + self.consumed_order.push_back(seq); + self.consumed.insert(seq); + } + + fn pump(&mut self, now: f64) { + while let Ok((seq, result)) = self.rx.try_recv() { + let is_caps_reply = self.caps_seq == Some(seq); + if is_caps_reply { + self.caps_seq = None; + } + if self.consumed.contains(&seq) { + continue; + } + // A context-tagged reply installs only for the context that + // issued it; it drops silently for any other, including a + // document switch, a revision change or an account switch. + // Typing in the signer search bumps `newest` and is not a + // context change, so it no longer gates a create/status/ + // completed/void/remind reply: the rule here is context + // equality, nothing else. + if let Some(context) = self.contexts.remove(&seq) { + self.remember_consumed(seq); + if context != self.current_context() { + continue; + } + } + match result { + // Guarded by `is_caps_reply`, computed before the swap + // above cleared it: a reply from a backend `set_backend` + // already replaced carries a sequence that is not (or no + // longer) `caps_seq`, so it cannot overwrite capabilities, + // responsible or linked for the new backend. + Ok(Answer::Capabilities { capabilities, responsible_party, linked }) if is_caps_reply => { + self.capabilities = Some(capabilities); + self.responsible = Some(responsible_party); + self.linked = linked; + } + Ok(Answer::Lookup(contacts)) if seq == self.lookup_seq => { + self.matches = contacts; + self.looking = false; + } + Ok(Answer::Created(env)) => { + self.busy = false; + self.pending_op_seq = None; + self.envelope = Some(env); + self.error = None; + } + // Guarded by `status_seq`, the most recently issued status + // request: two "Refresh status" clicks in flight at once can + // answer out of order, and the older one must not overwrite + // state a newer one already installed. + Ok(Answer::Status(env)) if seq == self.status_seq => { + self.busy = false; + self.pending_op_seq = None; + self.envelope = Some(env); + self.error = None; + } + Ok(Answer::Completed(doc)) => { + self.busy = false; + self.pending_op_seq = None; + self.completed_bytes = Some(doc.bytes); + self.error = None; + } + Ok(Answer::Voided { .. }) => { + self.busy = false; + self.pending_op_seq = None; + if let Some(env) = self.envelope.as_mut() { + env.status = EnvelopeStatus::Voided; + } + } + Ok(Answer::Reminded { .. }) => { + self.busy = false; + self.pending_op_seq = None; + } + // Clears `busy` only when this failure belongs to the + // operation that currently owns it: a lookup failing (or a + // superseded status request failing) must not wrongly + // report a still-running create as finished. + Err(reason) => { + if self.pending_op_seq == Some(seq) { + self.busy = false; + self.pending_op_seq = None; + } + self.looking = false; + self.error = Some(reason); + } + _ => {} + } + } + + if self.backend.is_some() && self.caps_seq.is_none() { + let first = self.capabilities.is_none() && self.asked_caps_at.is_none(); + let retry = self.asked_caps_at.is_some_and(|asked| !self.available() && now - asked >= RETRY); + if first || retry { + self.asked_caps_at = Some(now); + self.caps_seq = Some(self.submit(Request::Capabilities)); + } + } + } + + fn maybe_lookup(&mut self, now: f64) { + if !self.open || self.query.len() < MIN_QUERY { + return; + } + if (now - self.query_changed_at) < DEBOUNCE.as_secs_f64() { + return; + } + if self.looking || self.last_lookup_query == self.query { + return; + } + self.looking = true; + self.last_lookup_query = self.query.clone(); + self.lookup_seq = self.submit_in_context(Request::Lookup { query: self.query.clone(), limit: MATCHES }); + } + + fn add_contact(&mut self, contact: Contact) { + // `Contact::id` is the provider's share identifier, decided by + // `target`, and is not promised to be an address: `craft_cloud` + // documents the two as distinct and warns against treating one as + // the other. Falling back to it here would hand the envelope create + // request a recipient email that is not an email. + let Some(email) = contact.email.clone() else { + self.error = Some(self.labels.contact_missing_email.clone()); + return; + }; + if self.recipients.iter().any(|r| r.email.eq_ignore_ascii_case(&email)) { + return; + } + let role = self.next_role(); + self.recipients.push(Recipient { id: contact.id, name: contact.name, email, role, required: true, status: RecipientStatus::Pending }); + self.draft_idempotency_key = None; + self.query.clear(); + self.matches.clear(); + } + + fn add_email(&mut self, email: String) { + let email = email.trim().to_string(); + if email.is_empty() || !email.contains('@') { + return; + } + if self.recipients.iter().any(|r| r.email.eq_ignore_ascii_case(&email)) { + return; + } + let role = self.next_role(); + self.recipients.push(Recipient { id: email.clone(), name: email.clone(), email, role, required: true, status: RecipientStatus::Pending }); + self.draft_idempotency_key = None; + self.query.clear(); + self.matches.clear(); + } + + /// A role label no recipient added for the document currently open has + /// held, including one since removed: see `next_role_number`'s doc. + fn next_role(&mut self) -> String { + self.next_role_number += 1; + format!("Signer {}", self.next_role_number) + } + + fn queue_send(&mut self) { + let Some(sender) = self.sender.clone() else { + self.error = Some(self.labels.sign_in_first.clone()); + return; + }; + if self.recipients.is_empty() { + self.error = Some(self.labels.need_recipient.clone()); + return; + } + if !self.linked { + self.error = Some(self.labels.sign_in_first.clone()); + return; + } + let draft = EnvelopeDraft { + title: if self.document_title.is_empty() { "Document".into() } else { self.document_title.clone() }, + message: if self.message.trim().is_empty() { None } else { Some(self.message.clone()) }, + sender, + document_id: if self.document_id.is_empty() { None } else { Some(self.document_id.clone()) }, + document_etag: self.document_etag.clone(), + recipients: self.recipients.clone(), + placements: self.placements.clone(), + expires: None, + }; + if self.draft_idempotency_key.is_none() { + self.draft_idempotency_key = Some(format!("esign-{}-{}", self.document_id, fresh_send_id())); + } + let idempotency_key = self.draft_idempotency_key.clone().unwrap_or_default(); + self.busy = true; + self.error = None; + self.send_out = Some(SendRequest { draft, idempotency_key }); + self.pending_send_context = Some(self.current_context()); + } + + /// Draw the dialog when open. Call every frame (even when closed) so + /// capability probes and inbox pumping continue. + pub fn show(&mut self, ctx: &Context) { + let now = ctx.input(|i| i.time); + self.pump(now); + if self.open { + self.maybe_lookup(now); + } + if !self.open { + return; + } + + let mut open = self.open; + let labels = self.labels.clone(); + egui::Window::new(&labels.title).open(&mut open).resizable(true).default_width(420.0).show(ctx, |ui| { + self.ui(ui); + }); + // `open` reflects only the window's own title-bar close control; + // `self.ui` may already have set `self.open` to false from one of + // its own Close buttons. Either closing the dialog must stick, so + // reopening it takes a fresh `Self::open` call either way. + self.open = still_open(open, self.open); + } + + fn ui(&mut self, ui: &mut Ui) { + if let Some(err) = &self.error { + ui.colored_label(ui.visuals().error_fg_color, err); + ui.add_space(4.0); + } + + if !self.available() { + ui.label(if self.capabilities.is_none() { self.labels.loading.as_str() } else { self.labels.no_service.as_str() }); + return; + } + + if let Some(party) = &self.responsible { + ui.label(RichText::new(self.labels.responsible.replace("{party}", party)).small()); + ui.add_space(6.0); + } + + if let Some(env) = self.envelope.clone() { + self.status_panel(ui, &env); + return; + } + + if !self.linked { + // Send is disabled below without saying why; the compose form is + // the one place an unlinked user sees before reaching it. + ui.label(&self.labels.sign_in_first); + ui.add_space(4.0); + } + + ui.label(RichText::new(&self.document_title).strong()); + ui.add_space(4.0); + + ui.label(&self.labels.recipients); + let response = ui.add(egui::TextEdit::singleline(&mut self.query).hint_text(&self.labels.recipient_hint)); + if response.changed() { + self.query_changed_at = ui.input(|i| i.time); + self.matches.clear(); + self.looking = false; + self.lookup_seq = 0; + self.last_lookup_query.clear(); + } + if self.looking { + ui.spinner(); + ui.label(&self.labels.searching); + } else if self.query.len() >= MIN_QUERY && self.matches.is_empty() { + ui.horizontal(|ui| { + ui.label(&self.labels.no_matches); + if ui.button(&self.labels.add_address).clicked() { + self.add_email(self.query.clone()); + } + }); + } + for contact in self.matches.clone() { + let label = match &contact.email { + Some(email) => format!("{} <{}>", contact.name, email), + None => contact.name.clone(), + }; + if ui.selectable_label(false, label).clicked() { + self.add_contact(contact); + } + } + + ui.add_space(4.0); + let mut remove: Option = None; + for (i, recipient) in self.recipients.iter().enumerate() { + ui.horizontal(|ui| { + ui.label(format!("{} — {}", recipient.name, recipient.email)); + ui.label(RichText::new(&recipient.role).small()); + if ui.small_button("×").clicked() { + remove = Some(i); + } + }); + } + if let Some(i) = remove { + self.recipients.remove(i); + self.draft_idempotency_key = None; + // A placement keyed to the removed recipient's role would + // otherwise ride along in the next draft matching no recipient. + let live_roles: std::collections::HashSet<&str> = self.recipients.iter().map(|r| r.role.as_str()).collect(); + self.placements.retain(|p| live_roles.contains(p.role.as_str())); + } + + ui.add_space(6.0); + ui.label(&self.labels.message); + let message = ui.add(egui::TextEdit::multiline(&mut self.message).desired_rows(3)); + if message.changed() { + self.draft_idempotency_key = None; + } + + ui.add_space(8.0); + ui.horizontal(|ui| { + let can_send = !self.busy && self.linked && !self.recipients.is_empty(); + if ui.add_enabled(can_send, egui::Button::new(if self.busy { &self.labels.sending } else { &self.labels.send })).clicked() { + self.queue_send(); + } + if ui.button(&self.labels.close).clicked() { + self.open = false; + } + }); + } + + fn status_panel(&mut self, ui: &mut Ui, env: &Envelope) { + ui.label(RichText::new(&env.title).strong()); + ui.label(format!("{}: {:?}", self.labels.status, env.status)); + for r in &env.recipients { + ui.label(format!("{} — {:?} ({})", r.name, r.status, r.role)); + } + ui.add_space(8.0); + ui.horizontal(|ui| { + let caps = self.capabilities.clone().unwrap_or_default(); + if caps.contains(&EsignCapability::Reminders) + && ui.add_enabled(!self.busy, egui::Button::new(&self.labels.remind)).clicked() + && let Some(r) = env.recipients.iter().find(|r| r.status == RecipientStatus::Pending) + { + self.busy = true; + let seq = self.submit_in_context(Request::Remind { envelope: env.id.clone(), recipient: r.id.clone() }); + self.pending_op_seq = Some(seq); + } + if caps.contains(&EsignCapability::Void) + && env.status == EnvelopeStatus::Sent + && ui.add_enabled(!self.busy, egui::Button::new(&self.labels.void)).clicked() + { + self.busy = true; + let seq = self.submit_in_context(Request::Void { envelope: env.id.clone(), reason: "voided by sender".into() }); + self.pending_op_seq = Some(seq); + } + if env.status == EnvelopeStatus::Completed && ui.add_enabled(!self.busy, egui::Button::new(&self.labels.download)).clicked() { + self.busy = true; + let seq = self.submit_in_context(Request::Completed { envelope: env.id.clone() }); + self.pending_op_seq = Some(seq); + } + if ui.button(&self.labels.close).clicked() { + self.open = false; + } + }); + if ui.button(&self.labels.refresh).clicked() { + self.busy = true; + let seq = self.submit_in_context(Request::Status { envelope: env.id.clone() }); + self.pending_op_seq = Some(seq); + self.status_seq = seq; + } + } +} + +/// Split button that opens the request-signatures dialog. +/// +/// `open` is called when the primary action is chosen. The chevron offers +/// status refresh when an envelope id is known. +pub fn request_button(ui: &mut Ui, labels: &EsignLabels, available: bool, menu: &[crate::menu::MenuItem]) -> Option { + if !available { + return None; + } + let menu_labels = crate::menu::MenuLabels::default(); + crate::menu::split(ui, &labels.request, menu, &menu_labels) +} + +#[cfg(test)] +mod tests { + use super::*; + use std::sync::{Arc, Mutex}; + + struct Capture { + last: Mutex>, + } + + impl EsignBackend for Arc { + fn submit(&self, request: Request, reply: Replier) { + *self.last.lock().expect("lock") = Some(request); + reply.answer(Answer::Capabilities { + capabilities: vec![EsignCapability::Envelopes, EsignCapability::Void], + responsible_party: "Stub Signing".into(), + linked: true, + }); + } + } + + #[test] + fn available_after_capabilities() { + let capture = Arc::new(Capture { last: Mutex::new(None) }); + let mut dialog = EsignDialog::default(); + dialog.set_backend(capture); + let ctx = Context::default(); + dialog.show(&ctx); + dialog.show(&ctx); + assert!(dialog.available()); + assert_eq!(dialog.responsible.as_deref(), Some("Stub Signing")); + } + + #[test] + fn send_request_needs_recipient_and_sender() { + let mut dialog = EsignDialog { + linked: true, + sender: Some(Identity { id: "u".into(), display: "Ada".into(), email: Some("ada@example.com".into()), avatar: None }), + ..Default::default() + }; + dialog.queue_send(); + assert!(dialog.take_send_request().is_none()); + dialog.add_email("bob@example.com".into()); + dialog.queue_send(); + let req = dialog.take_send_request().expect("send"); + assert_eq!(req.draft.recipients.len(), 1); + assert_eq!(req.draft.recipients[0].email, "bob@example.com"); + } + + /// The texts egui drew, walking into `Shape::Vec` groups the way widgets nest them. Same + /// pattern as `docking::native_tests::texts`. + fn texts(shapes: &[egui::epaint::ClippedShape]) -> Vec { + fn walk(shape: &egui::Shape, out: &mut Vec) { + match shape { + egui::Shape::Vec(shapes) => shapes.iter().for_each(|s| walk(s, out)), + egui::Shape::Text(text) => out.push(text.galley.text().to_owned()), + _ => {} + } + } + let mut out = Vec::new(); + shapes.iter().for_each(|clipped| walk(&clipped.shape, &mut out)); + out + } + + #[test] + fn compose_form_shows_sign_in_message_when_not_linked() { + let mut dialog = + EsignDialog { capabilities: Some(vec![EsignCapability::Envelopes]), document_title: "A.pdf".into(), linked: false, ..Default::default() }; + let ctx = Context::default(); + let mut full = ctx.run_ui(egui::RawInput::default(), |ui| dialog.ui(ui)); + full.textures_delta.clear(); + let shown = texts(&full.shapes); + assert!(shown.iter().any(|t| t == &dialog.labels.sign_in_first), "sign-in message not shown for an unlinked account: {shown:?}"); + } + + fn ada() -> Identity { + Identity { id: "u".into(), display: "Ada".into(), email: Some("ada@example.com".into()), avatar: None } + } + + fn placement() -> FieldPlacement { + FieldPlacement { role: "Signer".into(), page: 0, x: 0.1, y: 0.2, w: 0.3, h: 0.05, kind: "signature".into(), required: true } + } + + #[test] + fn add_contact_rejects_a_contact_with_no_email() { + let mut dialog = EsignDialog::default(); + let contact = Contact { + id: "share-id-123".into(), + target: craft_cloud::ShareTarget::User("share-id-123".into()), + name: "Mallory".into(), + email: None, + avatar: None, + is_group: false, + }; + dialog.add_contact(contact); + assert!(dialog.recipients.is_empty(), "a contact with no email became a recipient: {:?}", dialog.recipients); + assert_eq!(dialog.error.as_deref(), Some(dialog.labels.contact_missing_email.as_str())); + } + + #[test] + fn set_placements_invalidates_the_idempotency_key() { + let mut dialog = EsignDialog { linked: true, sender: Some(ada()), ..Default::default() }; + dialog.add_email("bob@example.com".into()); + dialog.queue_send(); + let first = dialog.take_send_request().expect("first send").idempotency_key; + + dialog.set_placements(vec![placement()]); + dialog.queue_send(); + let second = dialog.take_send_request().expect("second send").idempotency_key; + + assert_ne!(first, second, "changing placements kept the old idempotency key: {first}"); + } + + #[test] + fn placements_do_not_survive_a_document_change() { + let mut dialog = EsignDialog::default(); + dialog.open("doc-A".into(), "A.pdf".into(), None, ada()); + dialog.set_placements(vec![placement()]); + + dialog.open("doc-B".into(), "B.pdf".into(), None, ada()); + + assert!(dialog.placements.is_empty(), "doc-B inherited doc-A's placements: {:?}", dialog.placements); + } + + #[test] + fn queue_send_keys_are_unique_across_dialog_instances() { + fn send_key(doc: &str) -> String { + let mut dialog = EsignDialog { linked: true, sender: Some(ada()), document_id: doc.into(), ..Default::default() }; + dialog.add_email("bob@example.com".into()); + dialog.queue_send(); + dialog.take_send_request().expect("send").idempotency_key + } + let a = send_key("doc-A"); + let b = send_key("doc-A"); + assert_ne!(a, b, "two fresh dialog instances for the same document produced the same idempotency key: {a}"); + } + + #[test] + fn recipient_roles_never_repeat_after_a_removal() { + let mut dialog = EsignDialog::default(); + dialog.add_email("a@example.com".into()); + dialog.add_email("b@example.com".into()); + dialog.recipients.remove(0); + dialog.add_email("c@example.com".into()); + + let roles: Vec<&str> = dialog.recipients.iter().map(|r| r.role.as_str()).collect(); + assert_eq!(roles.len(), 2, "{roles:?}"); + assert_ne!(roles[0], roles[1], "B and C were both assigned the same role after A was removed: {roles:?}"); + } + + #[test] + fn still_open_requires_both_the_window_and_the_dialog_to_agree() { + // A Close button inside `ui` already set `self.open` to false; the + // window's own close control was not used. + assert!(!still_open(true, false), "an internal Close click was undone by the window's unchanged open binding"); + // The title-bar close control was used; nothing inside set it false. + assert!(!still_open(false, true)); + // Neither closed it. + assert!(still_open(true, true)); + } + + fn envelope_stub() -> Envelope { + Envelope { + id: "env-1".into(), + title: "Contract".into(), + message: None, + sender: ada(), + document_id: None, + document_etag: None, + content_sha256: String::new(), + recipients: Vec::new(), + placements: Vec::new(), + status: EnvelopeStatus::Sent, + expires: None, + created: None, + completed_at: None, + } + } + + #[test] + fn refresh_status_caption_is_localized() { + let labels = EsignLabels { refresh: "Actualizar estado".into(), ..EsignLabels::default() }; + let mut dialog = + EsignDialog { capabilities: Some(vec![EsignCapability::Envelopes]), labels, envelope: Some(envelope_stub()), ..Default::default() }; + let ctx = Context::default(); + let mut full = ctx.run_ui(egui::RawInput::default(), |ui| dialog.ui(ui)); + full.textures_delta.clear(); + let shown = texts(&full.shapes); + assert!(shown.iter().any(|t| t == "Actualizar estado"), "refresh caption is not localized: {shown:?}"); + assert!(!shown.iter().any(|t| t == "Refresh status"), "hardcoded English caption still shown: {shown:?}"); + } +} diff --git a/crates/cloud-ui/src/esign/review_repro.rs b/crates/cloud-ui/src/esign/review_repro.rs new file mode 100644 index 000000000..c9780d7e5 --- /dev/null +++ b/crates/cloud-ui/src/esign/review_repro.rs @@ -0,0 +1,153 @@ +//! Regression tests for the three gate items skylartaylor raised on PR #661, +//! reproduced against 0a937ef (storytold/craft-libs#661): +//! . +//! +//! `Hold` is a backend that keeps every request and its `Replier` so a test +//! chooses when, and in what order, the service answers. + +use std::sync::{Arc, Mutex}; + +use craft_cloud::Identity; +use craft_esign::{Envelope, EnvelopeStatus, EsignCapability}; + +use super::*; + +/// Reused by `coderabbit_repro`, the regression tests for the CodeRabbit +/// findings reviewed on the same pull request. +#[derive(Clone, Default)] +pub(super) struct Hold(Arc>>); + +impl EsignBackend for Hold { + fn submit(&self, request: Request, reply: Replier) { + self.0.lock().unwrap().push((request, reply)); + } +} + +impl Hold { + /// Takes the oldest held request matching `pick`. + pub(super) fn take(&self, pick: impl Fn(&Request) -> bool) -> (Request, Replier) { + let mut held = self.0.lock().unwrap(); + let i = held.iter().position(|(r, _)| pick(r)).expect("request was submitted"); + held.remove(i) + } +} + +pub(super) fn who(id: &str) -> Identity { + Identity { id: id.into(), display: id.into(), email: Some(format!("{id}@example.com")), avatar: None } +} + +pub(super) fn envelope_for(doc: &str, sender: &str) -> Envelope { + Envelope { + id: format!("env-{doc}"), + title: format!("Contract {doc}"), + message: None, + sender: who(sender), + document_id: Some(doc.into()), + document_etag: None, + content_sha256: String::new(), + recipients: Vec::new(), + placements: Vec::new(), + status: EnvelopeStatus::Sent, + expires: None, + created: None, + completed_at: None, + } +} + +/// A dialog with a held backend whose capabilities probe has been answered. +pub(super) fn ready() -> (EsignDialog, Hold) { + let hold = Hold::default(); + let mut dialog = EsignDialog::default(); + dialog.set_backend(hold.clone()); + dialog.pump(0.0); // submits Capabilities + let (_, caps) = hold.take(|r| matches!(r, Request::Capabilities)); + caps.answer(Answer::Capabilities { + capabilities: vec![EsignCapability::Envelopes, EsignCapability::Void], + responsible_party: "Stub Signing".into(), + linked: true, + }); + dialog.pump(0.1); + assert!(dialog.available()); + (dialog, hold) +} + +/// The app's Send path: queue_send -> take_send_request -> submit Create. +pub(super) fn send(dialog: &mut EsignDialog, doc_bytes: &[u8]) { + dialog.add_email("bob@example.com".into()); + dialog.queue_send(); + let out = dialog.take_send_request().expect("Send produced a request"); + dialog.submit_request(Request::Create { + draft: Box::new(out.draft), + document: doc_bytes.to_vec(), + idempotency_key: out.idempotency_key, + send: true, + }); +} + +/// Gate item 1 (document variant): the dialog is reopened for document B +/// while document A's create is in flight. A's late reply carries document +/// A's context and must not be installed as document B's envelope. +#[test] +fn review_h5_reply_for_previous_document_is_installed_after_reopen() { + let (mut dialog, hold) = ready(); + dialog.open("doc-A".into(), "A.pdf".into(), None, who("alice")); + send(&mut dialog, b"A bytes"); + dialog.open("doc-B".into(), "B.pdf".into(), None, who("alice")); + + let (_, create_a) = hold.take(|r| matches!(r, Request::Create { .. })); + create_a.answer(Answer::Created(envelope_for("doc-A", "alice"))); + dialog.pump(1.0); + + let shown = dialog.envelope.as_ref().and_then(|e| e.document_id.clone()); + assert!( + shown.is_none() || shown.as_deref() == Some("doc-B"), + "dialog is open for doc-B but shows the envelope for {shown:?} (status panel: Void/Remind act on it); busy={}", + dialog.busy + ); +} + +/// Gate item 1 (account variant): reopened for the same document under +/// another signed-in account. Alice's envelope must never render for +/// mallory. +#[test] +fn review_h5_reply_for_previous_account_is_installed_after_account_switch() { + let (mut dialog, hold) = ready(); + dialog.open("doc-A".into(), "A.pdf".into(), None, who("alice")); + send(&mut dialog, b"A bytes"); + dialog.open("doc-A".into(), "A.pdf".into(), None, who("mallory")); + + let (_, create) = hold.take(|r| matches!(r, Request::Create { .. })); + create.answer(Answer::Created(envelope_for("doc-A", "alice"))); + dialog.pump(1.0); + + let shown = dialog.envelope.as_ref().map(|e| e.sender.id.clone()); + assert!(shown.is_none() || shown.as_deref() == Some("mallory"), "dialog now belongs to mallory but shows alice's envelope: sender={shown:?}"); +} + +/// Gate item 2: Send is in flight; the user types in the signer search box +/// (a lookup is submitted, which used to bump the old staleness counter). +/// The create reply then arrives for the same context and must still +/// install: typing in a search box is not a context change. +#[test] +fn review_n1_create_reply_dropped_after_a_lookup_leaves_dialog_busy() { + let (mut dialog, hold) = ready(); + dialog.open("doc-A".into(), "A.pdf".into(), None, who("alice")); + send(&mut dialog, b"A bytes"); + assert!(dialog.busy); + + dialog.query = "ca".into(); // typed after pressing Send + dialog.query_changed_at = 1.0; + dialog.maybe_lookup(2.0); + + let (_, create) = hold.take(|r| matches!(r, Request::Create { .. })); + create.answer(Answer::Created(envelope_for("doc-A", "alice"))); + for t in 0..10 { + dialog.pump(3.0 + f64::from(t)); + } + assert!( + !dialog.busy && dialog.envelope.is_some(), + "provider created env-doc-A but dialog busy={} envelope={:?} (reply dropped as stale)", + dialog.busy, + dialog.envelope.as_ref().map(|e| e.id.clone()) + ); +} diff --git a/crates/cloud-ui/src/lib.rs b/crates/cloud-ui/src/lib.rs new file mode 100644 index 000000000..6ac9f56e0 --- /dev/null +++ b/crates/cloud-ui/src/lib.rs @@ -0,0 +1,22 @@ +#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)] + +//! The share dialog, the cloud Open and Save pages, the request-signatures dialog, the account +//! menu and the presence bar that every Craft app shares. +//! +//! This is storytold main's cloud and share UI as main wrote it in craft-ui: raw egui, outside the +//! craft UI library's component contract, themes and tokens. It is to be ported onto the +//! framework's components. Until then the `craft-ui` facade re-exports `account`, `cloud`, `esign`, +//! `share` and `presence` from here, with the same `share`, `cloud` and `esign` features, so +//! `craft_ui::…` paths stay as on main. + +#[cfg(feature = "share")] +pub mod account; +mod buttons; +#[cfg(feature = "cloud")] +pub mod cloud; +#[cfg(feature = "esign")] +pub mod esign; +pub mod menu; +pub mod presence; +#[cfg(feature = "share")] +pub mod share; diff --git a/crates/cloud-ui/src/menu.rs b/crates/cloud-ui/src/menu.rs new file mode 100644 index 000000000..70189a56f --- /dev/null +++ b/crates/cloud-ui/src/menu.rs @@ -0,0 +1,222 @@ +//! The two controls that offer more than one action. +//! +//! An overflow menu is the `…` that holds what did not earn a place on the +//! toolbar. A split button is a primary action with a chevron beside it, where +//! the chevron offers the variations. Share is the usual example. Most of the +//! time a person wants to share, and once in a while they want to copy a link +//! or start a call about the document instead. +//! +//! They are one module because they are the same control underneath. Building +//! them twice would mean getting the accessible naming right twice, and an +//! icon-only button that announces itself as an ellipsis character is useless +//! to anybody reading the screen rather than looking at it. +//! +//! Neither control knows what any item does. Each answers with the identifier +//! of the item a person chose. The application holds the meaning. + +use egui::{Response, RichText, Ui}; + +/// One line in a menu. +#[derive(Clone, Debug, Default, PartialEq, Eq)] +pub struct MenuItem { + /// What the caller recognises this by. Never shown. + pub id: String, + pub label: String, + /// A second line, smaller. Worth having where the label alone leaves a + /// person guessing what the action will do to their document. + pub detail: Option, + /// A leading glyph. Decoration only, so it is never the accessible name. + pub icon: Option, + pub enabled: bool, + /// Draw a rule above this item. A group of related actions reads as a + /// group only when something separates it from the last one. + pub separator_before: bool, +} + +impl MenuItem { + pub fn new(id: impl Into, label: impl Into) -> MenuItem { + MenuItem { id: id.into(), label: label.into(), enabled: true, ..MenuItem::default() } + } + + pub fn detail(mut self, detail: impl Into) -> MenuItem { + self.detail = Some(detail.into()); + self + } + + pub fn icon(mut self, icon: impl Into) -> MenuItem { + self.icon = Some(icon.into()); + self + } + + /// Present but unavailable, with a reason on hover. + /// + /// Greying an item out says the action exists and is not possible now. + /// Removing it says the action does not exist. They are different facts and + /// a person reads them differently. + pub fn disabled(mut self, why: impl Into) -> MenuItem { + self.enabled = false; + self.detail = Some(why.into()); + self + } + + pub fn separated(mut self) -> MenuItem { + self.separator_before = true; + self + } +} + +/// What a person did to a split button. +#[derive(Clone, Debug, PartialEq, Eq)] +pub enum SplitHit { + /// They pressed the button itself. + Primary, + /// They chose something from the chevron's menu. + Item(String), +} + +/// The accessible name of the chevron, and of the overflow button. +/// +/// Public so an application can translate them. A glyph is not a name, and +/// these two are the only strings in this module that are not supplied by the +/// caller. +#[derive(Clone, Debug)] +pub struct MenuLabels { + /// The `…` button. + pub more: String, + /// The chevron on a split button. `{action}` is replaced with the primary + /// action's own label, so a screen reader says "more share options" rather + /// than "more options" on a toolbar holding four of them. + pub more_for: String, +} + +impl Default for MenuLabels { + fn default() -> MenuLabels { + MenuLabels { more: "More options".into(), more_for: "More {action} options".into() } + } +} + +/// The `…` button and its menu. +/// +/// Answers with the identifier of the item chosen, if any. +pub fn overflow(ui: &mut Ui, items: &[MenuItem], labels: &MenuLabels) -> Option { + // A horizontal ellipsis, not three periods. Three periods are three + // characters to anything reading the screen aloud. + let button = egui::Button::new(RichText::new("\u{2026}").size(15.0)).frame(false); + let hit = ui.add(button); + let name = labels.more.clone(); + hit.widget_info(|| egui::WidgetInfo::labeled(egui::Role::Button, true, name.as_str())); + let hit = hit.on_hover_text(labels.more.as_str()); + items_of(&hit, items) +} + +/// A primary action with a chevron beside it. +/// +/// The two halves are two controls. Pressing the label does the thing. Pressing +/// the chevron offers the variations. One control that did both would leave a +/// person guessing which half they had hit. +pub fn split(ui: &mut Ui, primary: &str, items: &[MenuItem], labels: &MenuLabels) -> Option { + let mut hit = None; + ui.horizontal(|ui| { + // The halves touch, so they read as one control with two parts. Square + // off the inside corners as well. Two default radii leave a pair of + // notches at the seam, which reads as two buttons that happen to abut. + ui.spacing_mut().item_spacing.x = 0.0; + let radius = ui.visuals().widgets.inactive.corner_radius; + // A toolbar that fills from its right edge hands this control a + // right-to-left layout, and whatever is added first lands furthest + // right. The label still belongs before the chevron, so the halves are + // added in the order that puts them there. + let backwards = ui.layout().main_dir() == egui::Direction::RightToLeft; + let (outer, inner) = if backwards { + (egui::CornerRadius { nw: 0, sw: 0, ..radius }, egui::CornerRadius { ne: 0, se: 0, ..radius }) + } else { + (egui::CornerRadius { ne: 0, se: 0, ..radius }, egui::CornerRadius { nw: 0, sw: 0, ..radius }) + }; + let label = |ui: &mut Ui, hit: &mut Option| { + if ui.add(egui::Button::new(primary).corner_radius(if backwards { inner } else { outer })).clicked() { + *hit = Some(SplitHit::Primary); + } + }; + let chevron = |ui: &mut Ui, hit: &mut Option| { + // Room for the triangle, which is painted rather than typed. + let more = ui.add(egui::Button::new(" ").corner_radius(if backwards { outer } else { inner })); + crate::buttons::chevron(ui, more.rect, ui.visuals().text_color()); + let name = labels.more_for.replace("{action}", &primary.to_lowercase()); + more.widget_info(|| egui::WidgetInfo::labeled(egui::Role::Button, true, name.as_str())); + let more = more.on_hover_text(name.as_str()); + if let Some(id) = items_of(&more, items) { + *hit = Some(SplitHit::Item(id)); + } + }; + if backwards { + chevron(ui, &mut hit); + label(ui, &mut hit); + } else { + label(ui, &mut hit); + chevron(ui, &mut hit); + } + }); + hit +} + +/// The menu both controls open. +fn items_of(anchor: &Response, items: &[MenuItem]) -> Option { + let mut chosen = None; + egui::Popup::menu(anchor).show(|ui| { + ui.set_min_width(210.0); + let weak = ui.visuals().weak_text_color(); + for item in items { + if item.separator_before { + ui.separator(); + } + let label = match &item.icon { + Some(icon) => format!("{icon} {}", item.label), + None => item.label.clone(), + }; + let row = ui.add_enabled(item.enabled, egui::Button::new(label).frame(false)); + // The icon is decoration. The name is the label alone. + let name = item.label.clone(); + let enabled = item.enabled; + row.widget_info(|| egui::WidgetInfo::labeled(egui::Role::Button, enabled, name.as_str())); + if row.clicked() { + chosen = Some(item.id.clone()); + ui.close(); + } + if let Some(detail) = &item.detail { + ui.label(RichText::new(detail.as_str()).small().color(weak)); + ui.add_space(2.0); + } + } + }); + chosen +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn an_item_is_enabled_until_it_is_not() { + assert!(MenuItem::new("copy", "Copy link").enabled); + let off = MenuItem::new("copy", "Copy link").disabled("this server forbids public links"); + assert!(!off.enabled); + assert_eq!(off.detail.as_deref(), Some("this server forbids public links")); + } + + #[test] + fn the_chevrons_name_says_which_action_it_belongs_to() { + let labels = MenuLabels::default(); + assert_eq!(labels.more_for.replace("{action}", "share"), "More share options"); + } + + #[test] + fn a_builder_keeps_what_it_was_given() { + let item = MenuItem::new("talk", "Work together").icon("\u{1f4de}").detail("Start a call").separated(); + assert_eq!(item.id, "talk"); + assert_eq!(item.label, "Work together"); + assert_eq!(item.icon.as_deref(), Some("\u{1f4de}")); + assert_eq!(item.detail.as_deref(), Some("Start a call")); + assert!(item.separator_before); + assert!(item.enabled); + } +} diff --git a/crates/cloud-ui/src/presence.rs b/crates/cloud-ui/src/presence.rs new file mode 100644 index 000000000..f429691bc --- /dev/null +++ b/crates/cloud-ui/src/presence.rs @@ -0,0 +1,424 @@ +//! Who else is in the document. +//! +//! A person editing alone and a person editing alongside three colleagues are +//! in very different situations. Only one of them has to worry about somebody +//! else changing the cell they are about to type in. An application that shows +//! nothing leaves them to find out by surprise. +//! +//! So this is a row of badges, one per person, with the count folded into a +//! final badge once the row would get long. It is the same control every +//! collaborative editor puts in the same corner, for the same reason. +//! +//! A peer's colour comes from the peer's own identifier. Two things need to +//! agree on it: the badge here, and whatever the document draws at that +//! person's cursor. Deriving it rather than assigning it means they agree with +//! no state passed between them, and the colour survives a reconnection. + +use egui::{Align, Color32, Layout, Response, RichText, Ui}; + +/// How wide a badge is, and how far the next one overlaps it. +const BADGE: f32 = 24.0; +const OVERLAP: f32 = 7.0; + +/// Somebody else in the document right now. +#[derive(Clone, Debug, PartialEq, Eq)] +pub struct Peer { + /// The session's own identifier, stable for as long as they are connected. + pub id: String, + /// What to show. A display name, never an identity. + pub display: String, + /// Where they are working, when the document can say. A spreadsheet knows + /// the cell. A word processor knows the page. Shown on hover only. + pub at: Option, +} + +impl Peer { + pub fn new(id: impl Into, display: impl Into) -> Peer { + Peer { id: id.into(), display: display.into(), at: None } + } + + /// Where they are working, for the tooltip. + pub fn at(mut self, at: impl Into) -> Peer { + self.at = Some(at.into()); + self + } + + /// The letter on the badge. + pub fn initial(&self) -> String { + self.display.chars().next().map(|c| c.to_uppercase().to_string()).unwrap_or_else(|| "?".to_owned()) + } + + /// This peer's colour. + pub fn colour(&self) -> Color32 { + colour_for(&self.id) + } +} + +/// How many colours the wheel carries. +/// +/// Sixteen, spaced evenly. More than that and neighbouring slots stop being +/// distinguishable, which defeats the point of having them. +pub const SLOTS: usize = 16; + +/// The colour in one slot of the wheel. +pub fn slot(index: usize) -> Color32 { + let step = 360.0 / SLOTS as f32; + // Alternate the lightness as the wheel turns, so two neighbouring hues are + // also two different weights. Hue alone is not enough for anybody who sees + // colour differently from the person who chose it. + let dim = index % 2 == 1; + hsv((index % SLOTS) as f32 * step, if dim { 0.66 } else { 0.52 }, if dim { 0.68 } else { 0.84 }) +} + +/// Which slot an identifier would like. +fn preferred(id: &str) -> usize { + // FNV-1a, which is small and has no dependency. + let mut hash: u32 = 0x811c_9dc5; + for byte in id.as_bytes() { + hash ^= u32::from(*byte); + hash = hash.wrapping_mul(0x0100_0193); + } + // Then an avalanche. FNV alone leaves keys that differ in one byte close + // together, and session ids from one relay run in sequence. + hash ^= hash >> 16; + hash = hash.wrapping_mul(0x7feb_352d); + hash ^= hash >> 15; + hash = hash.wrapping_mul(0x846c_a68b); + hash ^= hash >> 16; + hash as usize % SLOTS +} + +/// A stable colour for one identifier, with nobody else to consider. +/// +/// Public because the badge is not the only thing that needs it. Use +/// [`colours_for`] wherever a whole room is on screen. This one cannot promise +/// anything about the other people in it. +pub fn colour_for(id: &str) -> Color32 { + slot(preferred(id)) +} + +/// Colours for a whole room, every one distinguishable from the others. +/// +/// Each peer prefers the slot its identifier hashes to. A peer whose slot is +/// already taken moves to the next free one, walking the list in a fixed order +/// so the answer does not depend on who connected first. +/// +/// A document drawing remote cursors calls this with the same identifiers and +/// gets the same answer, which is what makes a cursor and the badge above it +/// the same person. That holds on one screen whatever else is happening, +/// since both calls see that client's own list. +/// +/// Two clients mid-transition can disagree for a frame or two. One has seen +/// somebody join and the other has not, so the walk resolves differently +/// until both lists match. It settles by itself, and nobody is comparing two +/// screens while it does. The durable fix is for the relay to hand out slots +/// with the peer list, which takes a protocol change. +/// +/// Beyond [`SLOTS`] peers the wheel repeats, since there is no seventeenth +/// colour anybody could tell from the first sixteen. +pub fn colours_for(ids: &[String]) -> Vec { + let mut order: Vec = (0..ids.len()).collect(); + order.sort_by(|a, b| ids[*a].cmp(&ids[*b])); + + let mut taken = [false; SLOTS]; + let mut out = vec![Color32::BLACK; ids.len()]; + for position in order { + let want = preferred(&ids[position]); + let mut at = want; + for step in 0..SLOTS { + at = (want + step) % SLOTS; + if !taken[at] { + break; + } + } + taken[at] = true; + out[position] = slot(at); + } + out +} + +fn hsv(hue: f32, saturation: f32, value: f32) -> Color32 { + let c = value * saturation; + let h = hue / 60.0; + let x = c * (1.0 - ((h % 2.0) - 1.0).abs()); + let (r, g, b) = match h as u32 { + 0 => (c, x, 0.0), + 1 => (x, c, 0.0), + 2 => (0.0, c, x), + 3 => (0.0, x, c), + 4 => (x, 0.0, c), + _ => (c, 0.0, x), + }; + let m = value - c; + let to_byte = |f: f32| (f.clamp(0.0, 1.0) * 255.0).round() as u8; + Color32::from_rgb(to_byte(r + m), to_byte(g + m), to_byte(b + m)) +} + +/// Strings, so an application can translate them. +#[derive(Clone, Debug)] +pub struct PresenceLabels { + /// Said when nobody else is here. An application may leave this empty to + /// draw nothing at all in that case. + pub alone: String, + /// With one other person. `{name}` is replaced. + pub with_one: String, + /// With several. `{count}` is replaced. + pub with_many: String, + /// The badge that stands for the people who did not fit. `{count}` is + /// replaced. + pub and_more: String, + /// The accessible name of the whole row. + pub who: String, +} + +impl Default for PresenceLabels { + fn default() -> PresenceLabels { + PresenceLabels { + alone: String::new(), + with_one: "Editing with {name}".into(), + with_many: "Editing with {count} others".into(), + and_more: "{count} more".into(), + who: "Who is here".into(), + } + } +} + +/// The row of badges. +#[derive(Clone)] +pub struct PresenceBar { + peers: Vec, + /// How many badges to draw before folding the rest into a count. Four is + /// what fits beside a title bar without crowding it. + shown: usize, + labels: PresenceLabels, + /// Whether to write the sentence beside the badges. A narrow toolbar wants + /// the badges alone. + summary: bool, +} + +impl Default for PresenceBar { + fn default() -> PresenceBar { + PresenceBar::new() + } +} + +impl PresenceBar { + pub fn new() -> PresenceBar { + PresenceBar { peers: Vec::new(), shown: 4, labels: PresenceLabels::default(), summary: true } + } + + pub fn with_labels(mut self, labels: PresenceLabels) -> PresenceBar { + self.labels = labels; + self + } + + /// How many badges before the row folds into a count. + pub fn with_shown(mut self, shown: usize) -> PresenceBar { + self.shown = shown.max(1); + self + } + + /// Draw the badges only, with no sentence beside them. + pub fn badges_only(mut self) -> PresenceBar { + self.summary = false; + self + } + + /// Replace the set of people in the document. + /// + /// Takes the whole set rather than a change, because a session that missed + /// a departure would otherwise show somebody who left until the next + /// reconnection. + pub fn set(&mut self, peers: Vec) { + self.peers = peers; + } + + pub fn peers(&self) -> &[Peer] { + &self.peers + } + + /// Whether anybody else is here. An application draws nothing when this is + /// false, which keeps a solitary document looking like one. + pub fn shared(&self) -> bool { + !self.peers.is_empty() + } + + /// What the row says in words. Also the accessible summary. + pub fn summary(&self) -> String { + match self.peers.len() { + 0 => self.labels.alone.clone(), + 1 => self.peers.first().map(|p| self.labels.with_one.replace("{name}", &p.display)).unwrap_or_default(), + n => self.labels.with_many.replace("{count}", &n.to_string()), + } + } + + /// Draw it. Answers with the peer a person clicked, when they clicked one. + /// + /// A click is worth answering because a name is where "take me to what + /// they are editing" belongs. The application decides whether it can. + pub fn show(&mut self, ui: &mut Ui) -> Option { + if self.peers.is_empty() { + if !self.labels.alone.is_empty() { + ui.label(RichText::new(self.labels.alone.as_str()).small().color(ui.visuals().weak_text_color())); + } + return None; + } + + let mut clicked = None; + ui.horizontal(|ui| { + // Badges overlap, the way a stack of cards does. Without it four + // circles read as four separate controls instead of one group. + ui.spacing_mut().item_spacing.x = -OVERLAP; + // Right to left, so the first person sits on top of the stack. + // + // Allocated to just the width the badges need. A right-to-left + // layout given the whole container takes it, which pushes the row + // to the far edge of a toolbar and strands the sentence after it. + let shown = self.peers.len().min(self.shown); + let hidden = self.peers.len().saturating_sub(self.shown); + let count = shown + usize::from(hidden > 0); + let width = BADGE + (count.saturating_sub(1) as f32) * (BADGE - OVERLAP); + ui.allocate_ui_with_layout(egui::vec2(width, BADGE), Layout::right_to_left(Align::Center), |ui| { + if hidden > 0 { + let more = self.labels.and_more.replace("{count}", &hidden.to_string()); + let weak = ui.visuals().widgets.inactive.bg_fill; + let badge = badge(ui, &format!("+{hidden}"), weak, ui.visuals().text_color()); + badge.widget_info(|| egui::WidgetInfo::labeled(egui::Role::Button, true, more.as_str())); + badge.on_hover_text(self.peers.iter().skip(self.shown).map(|p| p.display.as_str()).collect::>().join("\n")); + } + let ids: Vec = self.peers.iter().map(|p| p.id.clone()).collect(); + let colours = colours_for(&ids); + for (at, peer) in self.peers.iter().enumerate().take(self.shown).rev() { + let ink = colours.get(at).copied().unwrap_or_else(|| peer.colour()); + let hit = badge(ui, &peer.initial(), ink, Color32::WHITE); + let name = peer.display.clone(); + hit.widget_info(|| egui::WidgetInfo::labeled(egui::Role::Button, true, name.as_str())); + let tip = match &peer.at { + Some(at) => format!("{}\n{at}", peer.display), + None => peer.display.clone(), + }; + if hit.on_hover_text(tip).clicked() { + clicked = Some(peer.id.clone()); + } + } + }); + if self.summary { + ui.spacing_mut().item_spacing.x = 8.0; + ui.label(RichText::new(self.summary()).small().color(ui.visuals().weak_text_color())); + } + }); + clicked + } +} + +/// One round badge. Painted as a button so it is focusable and announces +/// itself, which a bare circle would not. +fn badge(ui: &mut Ui, text: &str, fill: Color32, ink: Color32) -> Response { + let button = egui::Button::new(RichText::new(text).color(ink).size(11.0).strong()) + .fill(fill) + .corner_radius(BADGE / 2.0) + .min_size(egui::vec2(BADGE, BADGE)) + .stroke(egui::Stroke::new(1.5, ui.visuals().panel_fill)); + ui.add(button) +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn a_colour_is_the_same_every_time_for_the_same_peer() { + assert_eq!(colour_for("session-a"), colour_for("session-a")); + } + + /// How far apart two colours are, summed over the channels. Crude, and + /// enough to tell "two different oranges" from "orange and teal". + fn apart(a: Color32, b: Color32) -> i32 { + (i32::from(a.r()) - i32::from(b.r())).abs() + (i32::from(a.g()) - i32::from(b.g())).abs() + (i32::from(a.b()) - i32::from(b.b())).abs() + } + + fn ids(of: &[&str]) -> Vec { + of.iter().map(|s| (*s).to_owned()).collect() + } + + #[test] + fn a_room_of_sequential_ids_is_a_room_of_distinguishable_colours() { + // The shape a relay actually hands out. A colour derived from one id + // alone cannot promise this, which is how six people came out looking + // like two. + let room = ids(&["s1", "s2", "s3", "s4", "s5", "s6"]); + let colours = colours_for(&room); + for (i, a) in colours.iter().enumerate() { + for (j, b) in colours.iter().enumerate().skip(i + 1) { + let distance = apart(*a, *b); + assert!(distance >= 60, "{} and {} are {distance} apart", room[i], room[j]); + } + } + } + + #[test] + fn a_full_wheel_is_still_all_distinct() { + let room: Vec = (0..SLOTS).map(|n| format!("session-{n}")).collect(); + let colours = colours_for(&room); + for (i, a) in colours.iter().enumerate() { + for (j, b) in colours.iter().enumerate().skip(i + 1) { + assert!(apart(*a, *b) > 0, "{} and {} share a colour", room[i], room[j]); + } + } + } + + #[test] + fn the_same_room_always_gets_the_same_colours() { + let room = ids(&["b", "a", "c"]); + assert_eq!(colours_for(&room), colours_for(&room)); + } + + #[test] + fn the_answer_does_not_depend_on_who_connected_first() { + let one = colours_for(&ids(&["a", "b", "c"])); + let other = colours_for(&ids(&["c", "b", "a"])); + // Same people, listed backwards. Each still gets the colour it had. + assert_eq!(one, other.into_iter().rev().collect::>()); + } + + #[test] + fn a_colour_is_dark_enough_to_hold_white_text() { + for id in ["a", "b", "zzz", "session-41", "", "\u{1f600}"] { + let c = colour_for(id); + // Rec. 601 luma, which is what readability of white ink tracks. + let luma = 0.299 * f32::from(c.r()) + 0.587 * f32::from(c.g()) + 0.114 * f32::from(c.b()); + assert!(luma < 200.0, "{id:?} gave a colour too pale for white text, luma {luma}"); + } + } + + #[test] + fn an_empty_room_is_not_shared_and_says_nothing() { + let bar = PresenceBar::new(); + assert!(!bar.shared()); + assert_eq!(bar.summary(), ""); + } + + #[test] + fn one_other_person_is_named_and_several_are_counted() { + let mut bar = PresenceBar::new(); + bar.set(vec![Peer::new("1", "Ann Reed")]); + assert_eq!(bar.summary(), "Editing with Ann Reed"); + bar.set(vec![Peer::new("1", "Ann Reed"), Peer::new("2", "Bob Vine")]); + assert_eq!(bar.summary(), "Editing with 2 others"); + } + + #[test] + fn a_departure_leaves_nobody_behind() { + let mut bar = PresenceBar::new(); + bar.set(vec![Peer::new("1", "Ann Reed"), Peer::new("2", "Bob Vine")]); + bar.set(vec![Peer::new("1", "Ann Reed")]); + assert_eq!(bar.peers().len(), 1, "the whole set replaces the old one"); + } + + #[test] + fn an_initial_survives_a_name_that_starts_oddly() { + assert_eq!(Peer::new("1", "ann").initial(), "A"); + assert_eq!(Peer::new("1", "").initial(), "?"); + assert_eq!(Peer::new("1", "\u{e9}lodie").initial(), "\u{c9}"); + } +} diff --git a/crates/cloud-ui/src/share/backend.rs b/crates/cloud-ui/src/share/backend.rs new file mode 100644 index 000000000..5c0981834 --- /dev/null +++ b/crates/cloud-ui/src/share/backend.rs @@ -0,0 +1,170 @@ +//! Where the share dialog's work happens, which is never on the frame. +//! +//! Every call a share needs is blocking, and a blocking call inside `update()` +//! freezes the window for as long as the server takes. So the dialog states +//! what it wants and reads answers off a channel, and something behind this +//! trait does the waiting. +//! +//! The dialog itself opens no socket, which keeps it buildable for the web +//! and testable with no server. A host supplies the half that does, and this +//! crate never learns what it reaches. + +use craft_cloud::{Capability, Contact, Permission, Share, ShareTarget}; + +/// One thing the dialog needs done. +#[derive(Clone, Debug, PartialEq, Eq)] +pub enum Request { + /// What the provider behind the service can actually do. + Capabilities, + /// People matching what has been typed so far. + Lookup { query: String, limit: usize }, + /// Who already has access to one document. + Access { id: String }, + /// Give several people access at once. + Grant(Grant), + /// Take one existing share away. + Withdraw { share_id: String }, + /// Where this document could be saved, so it can be shared. + /// + /// Asked for only when there is nothing to share yet. A list rather than a + /// single answer, because more than one provider may be configured and the + /// user picks. + Destinations, + /// Link an account for a destination that is configured but not connected. + Link { destination: String }, + /// One contact's picture, by the URL that contact carried. + /// + /// A separate request because a search answering with ten people must not + /// cost ten pictures before anybody has looked at them. The dialog asks + /// for a picture when it first paints the row that needs it, once per URL. + Avatar { url: String }, +} + +/// A share to create, as the dialog has it. +#[derive(Clone, Debug, PartialEq, Eq)] +pub struct Grant { + /// A key the recipient must present. Only meaningful for a link share, and + /// refused by a server that does not allow one. + pub password: Option, + /// The document, as an opaque handle the app was given. + pub id: String, + pub targets: Vec, + pub permission: Permission, + pub note: Option, + pub notify: bool, +} + +/// What came back. +#[derive(Clone, Debug, PartialEq, Eq)] +pub enum Answer { + Capabilities { + capabilities: Vec, + /// Whether this user has a cloud account attached at all. + linked: bool, + }, + Lookup(Vec), + Access(Vec), + /// Partial success is the ordinary case, so both halves come back. + Granted { + shared: Vec, + failed: Vec, + }, + Withdrawn { + share_id: String, + }, + Destinations(Vec), + /// An account was linked, so the destinations are worth asking for again. + Linked, + Avatar { + url: String, + /// Encoded image bytes, in whatever format the server sent. Decoding + /// is egui's image loaders' job, which the application installs. + bytes: Vec, + }, +} + +/// Somewhere a document could be saved. +/// +/// `account` is what makes this choosable. Two entries reading "Cloud" tell +/// nobody which of their accounts a document is about to land in, which is the +/// one thing somebody needs to know before pressing it. +#[derive(Clone, Debug, PartialEq, Eq)] +pub struct Destination { + /// Opaque to the dialog, handed back with the save. + pub id: String, + /// What to show, such as the service's own name. + pub name: String, + /// Which account, when one is linked. + pub account: Option, + /// False when the destination is configured but has no account yet. The + /// dialog offers a sign-in rather than a save. + pub linked: bool, +} + +/// One recipient a share did not reach. +/// +/// Named rather than counted. Sharing with five people where one address is +/// wrong shares with four and says which one failed. +#[derive(Clone, Debug, PartialEq, Eq)] +pub struct Failure { + pub target: ShareTarget, + pub code: String, + pub detail: String, +} + +/// Where one answer goes. +/// +/// Carries the sequence number of the request it answers. Autocomplete fires +/// per keystroke, and a service is free to answer the third query before the +/// second, so the dialog keeps the newest sequence it asked for and drops +/// anything older. Without that the list flickers between a stale set of +/// matches and a current one. +pub struct Replier { + seq: u64, + tx: std::sync::mpsc::Sender<(u64, Result)>, +} + +impl Replier { + pub(crate) fn new(seq: u64, tx: std::sync::mpsc::Sender<(u64, Result)>) -> Replier { + Replier { seq, tx } + } + + /// Which request this answers. + pub fn seq(&self) -> u64 { + self.seq + } + + /// Another handle to the same answer slot, for a backend that has to give + /// up after moving the first one into a worker. + pub fn dup(&self) -> Replier { + Replier { seq: self.seq, tx: self.tx.clone() } + } + + pub fn answer(self, answer: Answer) { + self.deliver(Ok(answer)); + } + + /// Say why it could not be done, in words a user can read. + pub fn refuse(self, reason: impl Into) { + self.deliver(Err(reason.into())); + } + + /// A dropped receiver means the dialog closed, which is not a failure. + fn deliver(self, result: Result) { + let _ = self.tx.send((self.seq, result)); + } +} + +impl std::fmt::Debug for Replier { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + f.debug_struct("Replier").field("seq", &self.seq).finish() + } +} + +/// Somewhere a [`Request`] can run without blocking a frame. +/// +/// `submit` must return immediately. The answer arrives through `reply` +/// whenever it is ready, or never, which the dialog survives. +pub trait ShareBackend { + fn submit(&self, request: Request, reply: Replier); +} diff --git a/crates/cloud-ui/src/share/mod.rs b/crates/cloud-ui/src/share/mod.rs new file mode 100644 index 000000000..e38067411 --- /dev/null +++ b/crates/cloud-ui/src/share/mod.rs @@ -0,0 +1,1465 @@ +//! One share dialog, the same one in every Craft app. +//! +//! What it offers is what a person asks for when they say "share this": pick +//! several people by typing a few letters of a name, choose whether they may +//! look or change, add a note, decide whether an email goes out, and see who +//! already has access so one of them can be taken away again. +//! +//! Three things shape the implementation. +//! +//! Nothing here opens a socket. Every call goes through [`ShareBackend`], and +//! nothing here reaches the network. A host writes the backend, and this +//! module never learns what it talks to. +//! this file. +//! +//! Nothing here blocks. Answers arrive on a channel and are read once per +//! frame. Autocomplete waits [`DEBOUNCE`] after the last keystroke before it +//! asks anything, and an answer to a query the user has already typed past is +//! dropped rather than painted, so the list cannot flicker backwards. +//! +//! Nothing here is assumed about the provider. [`ShareDialog::available`] is +//! false until the service says sharing exists, and an app hides its Share +//! control rather than offering a button that fails. Contacts and mail are +//! reported separately and are hidden the same way. + +use std::collections::HashMap; +use std::sync::mpsc::{Receiver, Sender}; +use std::time::Duration; + +use craft_cloud::{Capability, Contact, Permission, Share, ShareTarget}; +use egui::{Align, Align2, Color32, Context, CornerRadius, FontId, Id, Layout, Response, RichText, Sense, Ui, UiBuilder, Vec2}; + +mod backend; +#[cfg(test)] +mod tests; + +pub use backend::{Answer, Destination, Failure, Grant, Replier, Request, ShareBackend}; + +/// How long after the last keystroke the dialog asks for matches. +/// +/// A lookup per keystroke would ask five times for "annie" and paint whichever +/// answer happened to arrive last. +pub const DEBOUNCE: Duration = Duration::from_millis(200); + +/// How many matches one lookup asks for. +const MATCHES: usize = 8; + +/// Shortest query worth asking about. One letter matches most of an address +/// book and tells the user nothing. +const MIN_QUERY: usize = 2; + +/// Contact pictures held at once. Reached only by a long session of searching; +/// the whole cache is dropped rather than evicted one entry at a time. +const AVATARS: usize = 256; + +/// How long before an unanswered capability question is asked again, so one +/// unreachable moment does not hide Share for the rest of the session. +const RETRY: f64 = 20.0; + +const AVATAR: f32 = 20.0; +const AVATAR_RADIUS: u8 = 10; + +/// The id of the recipient field, for an app that wants to focus it. +const QUERY: &str = "craft-ui/share/query"; + +type Inbox = (u64, Result); + +/// Every string the dialog shows, so an application can translate it. +/// +/// The defaults are English. Nothing else in `craft-ui` localizes, and this +/// does not change that: the dialog holds the strings an app gives it and +/// translates nothing itself. +#[derive(Clone, Debug)] +pub struct ShareLabels { + pub title: String, + pub recipients: String, + pub recipient_hint: String, + pub searching: String, + pub no_matches: String, + pub add_address: String, + pub group: String, + pub permission: String, + pub can_view: String, + pub can_edit: String, + pub note: String, + pub notify: String, + pub no_mail: String, + pub share: String, + pub sharing: String, + pub close: String, + pub remove: String, + pub shared_with: String, + pub not_shared_with: String, + pub access: String, + pub access_empty: String, + pub loading: String, + pub withdraw: String, + pub withdrawing: String, + pub copy_link: String, + pub anyone_with_link: String, + pub save_first: String, + /// Shown under "Can edit", the way an office suite explains a permission + /// rather than leaving a bare radio button to carry the meaning. + pub can_edit_detail: String, + pub can_view_detail: String, + pub message_hint: String, + pub send: String, + pub manage_access: String, + pub upload_first: String, + pub name_hint: String, + pub saving: String, + pub save_and_share: String, + pub sign_in: String, + pub attach_instead: String, + pub create_link: String, + pub key_hint: String, + pub key_required_note: String, + pub link_copied: String, +} + +impl Default for ShareLabels { + fn default() -> ShareLabels { + ShareLabels { + title: "Share".into(), + recipients: "Share with".into(), + recipient_hint: "Add a name, group, or email".into(), + searching: "Looking…".into(), + no_matches: "No matches".into(), + add_address: "Press Return to share with this address".into(), + group: "group".into(), + permission: "They may".into(), + can_view: "View".into(), + can_edit: "Edit".into(), + note: "Note (optional)".into(), + notify: "Notify by email".into(), + no_mail: "This server cannot send mail".into(), + share: "Share".into(), + sharing: "Sharing…".into(), + close: "Close".into(), + remove: "Remove".into(), + shared_with: "Shared with".into(), + not_shared_with: "Not shared with".into(), + access: "Who has access".into(), + access_empty: "Nobody else yet".into(), + loading: "Loading…".into(), + withdraw: "Withdraw".into(), + withdrawing: "Withdrawing…".into(), + copy_link: "Copy link".into(), + anyone_with_link: "Anyone with the link".into(), + save_first: "Save this document to the cloud before sharing it.".into(), + can_edit_detail: "Make any changes".into(), + can_view_detail: "Cannot make changes".into(), + message_hint: "Add a message".into(), + send: "Send".into(), + manage_access: "Who has access".into(), + upload_first: "Save this document somewhere to share it.".into(), + name_hint: "Name this document".into(), + saving: "Saving\u{2026}".into(), + save_and_share: "Save and share".into(), + sign_in: "Sign in".into(), + attach_instead: "Attach a copy instead".into(), + create_link: "Get a link".into(), + key_hint: "Key (optional)".into(), + key_required_note: "This server requires a key on a link.".into(), + link_copied: "Link copied".into(), + } + } +} + +/// What the provider behind the service actually does. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +struct Provider { + sharing: bool, + contacts: bool, + mail: bool, + /// Public links at all. An administrator can forbid them. + links: bool, + /// A key on a link. + key: bool, + /// The server insists on one, so a link cannot be made without it. + key_required: bool, +} + +/// One contact picture, asked for at most once. +#[derive(Clone, Debug, PartialEq, Eq)] +enum Avatar { + /// Asked for under this sequence number; nothing to paint yet. + Pending(u64), + /// Bytes handed to egui under this URI, for the application's image + /// loaders to decode. + Ready(String), + /// Asked once and refused. Initials are painted instead, and it is never + /// asked for again. + Missing, +} + +/// Somebody the user has picked. +#[derive(Clone, Debug, PartialEq, Eq)] +struct Chosen { + target: ShareTarget, + label: String, + detail: Option, + avatar: Option, +} + +/// The dialog's state while it is open on one document. +struct Sheet { + id: String, + title: String, + query: String, + /// When the query last changed, for the debounce. `None` when settled. + typed: Option, + /// The newest lookup asked for. An answer to anything older is dropped. + lookup: Option, + searching: bool, + matches: Vec, + chosen: Vec, + permission: Permission, + note: String, + notify: bool, + /// Who already has access. `None` until the answer arrives. + access: Option>, + access_seq: Option, + /// Withdrawals in flight, as (request, share). + withdrawing: Vec<(u64, String)>, + granting: Option, + /// Where it could be saved. `None` until the answer arrives. + destinations: Option>, + destinations_seq: Option, + link_seq: Option, + /// Which one is selected, by id. + destination: Option, + /// The name typed while the document still has nowhere to live. + save_as: String, + /// The save in flight, if one is. + saving: Option, + save_error: Option, + /// The key to put on a link, while one is being made. + link_key: String, + /// The last share's outcome, kept on screen until the next one. + shared: Vec, + failed: Vec, + /// A refusal that stopped a whole call, as opposed to one recipient. + error: Option, +} + +impl Sheet { + fn new(id: String, title: String) -> Sheet { + Sheet { + destinations: None, + destinations_seq: None, + link_seq: None, + destination: None, + save_as: title.clone(), + saving: None, + save_error: None, + link_key: String::new(), + id, + title, + query: String::new(), + typed: None, + lookup: None, + searching: false, + matches: Vec::new(), + chosen: Vec::new(), + permission: Permission::View, + note: String::new(), + notify: true, + access: None, + access_seq: None, + withdrawing: Vec::new(), + granting: None, + shared: Vec::new(), + failed: Vec::new(), + error: None, + } + } +} + +/// Something the drawing pass decided and the dialog carries out afterwards. +/// +/// Drawing holds the open sheet, so it cannot also reach the request channel. +/// Collecting intentions and acting on them once the frame is painted keeps +/// both honest. +enum Act { + Lookup(String), + /// Save a document that has nowhere to live yet, into one destination. + SaveAs { + destination: String, + name: String, + }, + /// Connect an account for a destination that has none. + Link(String), + Grant(Grant), + Withdraw(String), + Avatar(String), + Close, +} + +/// A save the dialog is waiting on the application to do. +/// +/// Taken once. The application serialises the open document, puts it where +/// `destination` says, and reports back with [`ShareDialog::saved`] or +/// [`ShareDialog::save_failed`]. Prefer [`ShareDialog::saved_if`] / +/// [`ShareDialog::save_failed_if`] with [`SaveRequest::generation`] when the +/// save is asynchronous, so a completion for a closed or replaced sheet is +/// dropped without the application inventing its own epoch. +#[derive(Clone, Debug, PartialEq, Eq)] +pub struct SaveRequest { + /// Which destination, as the dialog was told by [`Destination::id`]. + pub destination: String, + /// What the user called it. + pub name: String, + /// Open-sheet generation when this request was taken. Pass to + /// [`ShareDialog::saved_if`] / [`ShareDialog::save_failed_if`]. + pub generation: u64, +} + +/// What the dialog may offer this frame. +#[derive(Clone, Copy)] +struct Allowed { + contacts: bool, + mail: bool, + links: bool, + key: bool, + key_required: bool, +} + +/// A share dialog. +/// +/// Create one per window, call [`ShareDialog::connect`] once a backend exists, +/// call [`ShareDialog::show`] every frame, and open it from a Share control +/// that is drawn only while [`ShareDialog::available`] is true. +pub struct ShareDialog { + backend: Option>, + tx: Sender, + rx: Receiver, + seq: u64, + provider: Option, + /// When the capability question was last asked. + asked: Option, + open: Option, + /// Keyed by the URL the contact carried, so reopening the dialog does not + /// fetch the same faces again. + avatars: HashMap, + /// A save the application has not picked up yet. + wants_save: Option, + /// Bumped on every [`ShareDialog::open`] and [`ShareDialog::close`]. A save + /// completion from an earlier open is ignored when this no longer matches + /// [`ShareDialog::pending_save_generation`]. + sheet_generation: u64, + /// Generation of the open sheet when [`ShareDialog::take_save_request`] + /// last handed a save to the application. + pending_save_generation: Option, + labels: ShareLabels, +} + +impl Default for ShareDialog { + fn default() -> ShareDialog { + ShareDialog::new() + } +} + +impl ShareDialog { + pub fn new() -> ShareDialog { + let (tx, rx) = std::sync::mpsc::channel(); + ShareDialog { + backend: None, + tx, + rx, + seq: 0, + provider: None, + asked: None, + open: None, + avatars: HashMap::new(), + wants_save: None, + sheet_generation: 0, + pending_save_generation: None, + labels: ShareLabels::default(), + } + } + + /// Attach the thing that does the waiting. + /// + /// The first frame after this asks what the provider can do, which is what + /// decides whether sharing is offered at all. + pub fn connect(&mut self, backend: impl ShareBackend + 'static) { + self.backend = Some(Box::new(backend)); + self.provider = None; + self.asked = None; + } + + pub fn connected(&self) -> bool { + self.backend.is_some() + } + + /// Replace the dialog's strings, for a localized application. + pub fn with_labels(mut self, labels: ShareLabels) -> ShareDialog { + self.labels = labels; + self + } + + pub fn labels_mut(&mut self) -> &mut ShareLabels { + &mut self.labels + } + + /// Whether sharing can be offered. + /// + /// False until the service says the provider supports it and an account is + /// linked. An application draws no Share control while this is false: a + /// hidden feature is better than a button that fails on use. + /// Ask the provider again what it can do. + /// + /// The answer is kept once it arrives, so a host that signs somebody + /// in after the first answer has to say so. Without this the dialog + /// keeps the answer it got while nobody was signed in, and Share + /// stays unavailable for the rest of the run. + pub fn refresh(&mut self) { + self.provider = None; + self.asked = None; + } + + pub fn available(&self) -> bool { + self.provider.is_some_and(|p| p.sharing) + } + + /// Open on one document. + /// + /// `id` is the handle the application was given for it, passed back + /// untouched. An empty one means the document has never been saved to the + /// cloud, which the dialog says rather than failing on Share. Does nothing + /// while sharing is unavailable. + pub fn open(&mut self, id: impl Into, title: impl Into) { + if !self.available() { + return; + } + self.sheet_generation = self.sheet_generation.wrapping_add(1); + self.wants_save = None; + let id = id.into(); + self.open = Some(Sheet::new(id.clone(), title.into())); + if id.is_empty() { + // Nothing to share yet, so the dialog opens on the places it could + // go. Asked for here rather than on the first frame, so the list is + // usually there by the time anybody looks. + let seq = self.issue(Request::Destinations); + if let Some(sheet) = &mut self.open { + sheet.destinations_seq = Some(seq); + } + } + if !id.is_empty() { + let seq = self.issue(Request::Access { id }); + if let Some(sheet) = &mut self.open { + sheet.access_seq = Some(seq); + } + } + } + + /// A save the application should perform, if one was asked for. + /// + /// Taken, so it is handled once. Stamps [`SaveRequest::generation`] with + /// the open sheet's generation. Call [`ShareDialog::saved`] / + /// [`ShareDialog::save_failed`] (dialog-side pending guard) or + /// [`ShareDialog::saved_if`] / [`ShareDialog::save_failed_if`] with that + /// generation when the work finishes; otherwise the dialog waits. + pub fn take_save_request(&mut self) -> Option { + let mut request = self.wants_save.take()?; + request.generation = self.sheet_generation; + self.pending_save_generation = Some(request.generation); + Some(request) + } + + /// The document was saved, and this is the handle the provider issued. + /// + /// Ignored when the dialog has closed, reopened on another document, or + /// taken a newer save since [`ShareDialog::take_save_request`]. + pub fn saved(&mut self, id: impl Into, name: impl Into) { + if !self.save_completion_applies() { + return; + } + self.pending_save_generation = None; + self.finish_saved(id, name); + } + + /// Like [`ShareDialog::saved`], but applies only when `generation` matches + /// the open sheet's generation. + pub fn saved_if(&mut self, generation: u64, id: impl Into, name: impl Into) { + if self.open.is_none() || self.sheet_generation != generation { + return; + } + self.pending_save_generation = None; + self.finish_saved(id, name); + } + + /// The save did not happen, and this is why. + /// + /// Ignored under the same conditions as [`ShareDialog::saved`]. + pub fn save_failed(&mut self, reason: impl Into) { + if !self.save_completion_applies() { + return; + } + self.pending_save_generation = None; + if let Some(sheet) = &mut self.open { + sheet.saving = None; + sheet.save_error = Some(reason.into()); + } + } + + /// Like [`ShareDialog::save_failed`], but applies only when `generation` + /// matches the open sheet's generation. + pub fn save_failed_if(&mut self, generation: u64, reason: impl Into) { + if self.open.is_none() || self.sheet_generation != generation { + return; + } + self.pending_save_generation = None; + if let Some(sheet) = &mut self.open { + sheet.saving = None; + sheet.save_error = Some(reason.into()); + } + } + + /// Generation of the sheet currently open, for callers that track their + /// own save epoch. Zero when the dialog is closed. + pub fn sheet_generation(&self) -> u64 { + if self.open.is_some() { self.sheet_generation } else { 0 } + } + + fn save_completion_applies(&self) -> bool { + self.pending_save_generation.is_some_and(|g| g == self.sheet_generation) + } + + fn finish_saved(&mut self, id: impl Into, name: impl Into) { + if self.open.is_none() { + return; + } + let id = id.into(); + if let Some(sheet) = &mut self.open { + sheet.saving = None; + sheet.save_error = None; + sheet.id = id.clone(); + sheet.title = name.into(); + } + // The document exists now, so ask who already has access, exactly as + // opening on a saved document would. + let seq = self.issue(Request::Access { id }); + if let Some(sheet) = &mut self.open { + sheet.access_seq = Some(seq); + } + } + + pub fn is_open(&self) -> bool { + self.open.is_some() + } + + pub fn close(&mut self) { + self.open = None; + self.sheet_generation = self.sheet_generation.wrapping_add(1); + self.wants_save = None; + } + + /// Who the last share reached, and who it did not. + pub fn outcome(&self) -> (&[Share], &[Failure]) { + match &self.open { + Some(sheet) => (&sheet.shared, &sheet.failed), + None => (&[], &[]), + } + } + + /// The recipient field's id, for an application that wants to focus it. + pub fn query_field_id() -> Id { + Id::unique(QUERY) + } + + /// One frame, as a modal over the window. Call this unconditionally: + /// answers are collected here whether the dialog is open or not. + pub fn show(&mut self, ctx: &Context) { + self.collect(ctx); + if self.open.is_none() { + return; + } + let modal = egui::Modal::new(Id::unique("craft-ui/share")).show(ctx, |ui| { + ui.set_min_width(440.0); + ui.set_max_width(560.0); + self.contents(ui); + }); + if modal.should_close() { + self.close(); + } + } + + /// One frame's contents without the modal chrome, for an application that + /// hosts the dialog in its own panel. + pub fn show_in(&mut self, ui: &mut Ui) { + self.collect(ui.ctx()); + if self.open.is_some() { + self.contents(ui); + } + } + + fn contents(&mut self, ui: &mut Ui) { + let allowed = match self.provider { + Some(p) => Allowed { contacts: p.contacts, mail: p.mail, links: p.links, key: p.key, key_required: p.key_required }, + None => Allowed { contacts: false, mail: false, links: false, key: false, key_required: false }, + }; + let mut acts = Vec::new(); + { + let Some(sheet) = self.open.as_mut() else { return }; + draw(ui, sheet, &self.avatars, &self.labels, allowed, &mut acts); + } + self.apply(ui.ctx(), acts); + } + + // ---- the channel ------------------------------------------------------ + + fn issue(&mut self, request: Request) -> u64 { + self.seq += 1; + let seq = self.seq; + if let Some(backend) = &self.backend { + backend.submit(request, Replier::new(seq, self.tx.clone())); + } + seq + } + + fn collect(&mut self, ctx: &Context) { + while let Ok((seq, result)) = self.rx.try_recv() { + self.receive(ctx, seq, result); + } + let now = ctx.input(|i| i.time); + if self.backend.is_some() && self.provider.is_none() && self.asked.is_none_or(|at| now - at >= RETRY) { + self.asked = Some(now); + self.issue(Request::Capabilities); + } + } + + fn receive(&mut self, ctx: &Context, seq: u64, result: Result) { + let answer = match result { + Ok(answer) => answer, + Err(reason) => return self.refused(seq, reason), + }; + // Set while an answer leaves something else worth asking for; issued + // once the open sheet is no longer borrowed. + let mut reload = None; + match answer { + Answer::Capabilities { capabilities, linked } => { + self.provider = Some(Provider { + sharing: linked && capabilities.contains(&Capability::Sharing), + contacts: capabilities.contains(&Capability::Contacts), + // ShareNotify, not Mail. Mail means "can send arbitrary + // mail"; this box only asks the provider to tell the + // person being shared with, which is a far smaller claim + // and one most providers can honour. + mail: capabilities.contains(&Capability::ShareNotify), + links: capabilities.contains(&Capability::LinkShares), + key: capabilities.contains(&Capability::LinkPassword), + key_required: capabilities.contains(&Capability::LinkPasswordRequired), + }); + // A provider that cannot share must not leave a dialog up that + // was opened while the answer was still outstanding. + if !self.available() { + self.close(); + } + } + Answer::Lookup(found) => { + if let Some(sheet) = &mut self.open + && sheet.lookup == Some(seq) + { + sheet.matches = found; + sheet.searching = false; + } + } + Answer::Access(list) => { + if let Some(sheet) = &mut self.open + && sheet.access_seq == Some(seq) + { + sheet.access = Some(list); + sheet.access_seq = None; + } + } + Answer::Granted { shared, failed } => { + // A link was asked for in order to be handed out, so it goes + // to the clipboard without a second click. + if let Some(url) = shared.iter().find_map(|s| s.url.clone()) { + ctx.copy_text(url); + } + if let Some(sheet) = &mut self.open + && sheet.granting == Some(seq) + { + sheet.granting = None; + sheet.error = None; + // Recipients that went through leave the picker. The ones + // that did not stay in it, so a corrected retry is one + // press rather than a retyped list. + sheet.chosen.retain(|c| failed.iter().any(|f| f.target == c.target)); + sheet.shared = shared; + sheet.failed = failed; + if !sheet.shared.is_empty() { + reload = Some(sheet.id.clone()); + } + } + } + Answer::Destinations(list) => { + if let Some(sheet) = &mut self.open + && sheet.destinations_seq == Some(seq) + { + // One destination and nothing to choose between: pick it, + // so the only linked account is not a click somebody has + // to make for no reason. + if sheet.destination.is_none() + && let [only] = list.as_slice() + && only.linked + { + sheet.destination = Some(only.id.clone()); + } + sheet.destinations = Some(list); + sheet.destinations_seq = None; + } + } + Answer::Linked => { + // An account arrived, so the list is stale. + if let Some(sheet) = &mut self.open { + sheet.destinations = None; + } + let seq = self.issue(Request::Destinations); + if let Some(sheet) = &mut self.open { + sheet.destinations_seq = Some(seq); + } + } + Answer::Withdrawn { share_id } => { + if let Some(sheet) = &mut self.open { + sheet.withdrawing.retain(|(_, id)| *id != share_id); + if let Some(access) = &mut sheet.access { + access.retain(|s| s.id != share_id); + } + sheet.shared.retain(|s| s.id != share_id); + } + } + Answer::Avatar { url, bytes } => { + let uri = avatar_uri(&url); + ctx.include_bytes(uri.clone(), bytes); + self.avatars.insert(url, Avatar::Ready(uri)); + } + } + if let Some(id) = reload { + let seq = self.issue(Request::Access { id }); + if let Some(sheet) = &mut self.open { + sheet.access_seq = Some(seq); + } + } + } + + /// One request came back with a reason instead of an answer. + fn refused(&mut self, seq: u64, reason: String) { + // A picture nobody can fetch is not worth telling the user about, and + // is never asked for again. + if let Some(url) = self.avatars.iter().find(|(_, a)| **a == Avatar::Pending(seq)).map(|(url, _)| url.clone()) { + self.avatars.insert(url, Avatar::Missing); + return; + } + let Some(sheet) = &mut self.open else { return }; + if sheet.lookup == Some(seq) { + sheet.searching = false; + sheet.matches.clear(); + sheet.error = Some(reason); + } else if sheet.access_seq == Some(seq) { + sheet.access_seq = None; + sheet.access = Some(Vec::new()); + sheet.error = Some(reason); + } else if sheet.granting == Some(seq) { + sheet.granting = None; + sheet.error = Some(reason); + } else if sheet.withdrawing.iter().any(|(s, _)| *s == seq) { + sheet.withdrawing.retain(|(s, _)| *s != seq); + sheet.error = Some(reason); + } else if sheet.destinations_seq == Some(seq) { + sheet.destinations_seq = None; + sheet.destinations = Some(Vec::new()); + sheet.save_error = Some(reason); + } else if sheet.link_seq == Some(seq) { + sheet.link_seq = None; + sheet.save_error = Some(reason); + } + } + + fn apply(&mut self, ctx: &Context, acts: Vec) { + for act in acts { + match act { + Act::Close => self.close(), + Act::Lookup(query) => { + let seq = self.issue(Request::Lookup { query, limit: MATCHES }); + if let Some(sheet) = &mut self.open { + sheet.lookup = Some(seq); + sheet.searching = true; + } + } + Act::Grant(grant) => { + let seq = self.issue(Request::Grant(grant)); + if let Some(sheet) = &mut self.open { + sheet.granting = Some(seq); + sheet.shared.clear(); + sheet.failed.clear(); + sheet.error = None; + } + } + Act::SaveAs { destination, name } => { + // Handed to the application rather than the backend. Only + // it can turn the open document into bytes, and a share + // transport is the wrong place to pass a workbook through. + // `generation` is filled when taken; zero here is a placeholder. + self.wants_save = Some(SaveRequest { destination, name, generation: 0 }); + if let Some(sheet) = &mut self.open { + sheet.saving = Some(0); + sheet.save_error = None; + } + } + Act::Link(destination) => { + // The answer to this is usually a refusal carrying the URL + // to open, because launching a browser is the host + // application's business and not this crate's. + let seq = self.issue(Request::Link { destination }); + if let Some(sheet) = &mut self.open { + sheet.link_seq = Some(seq); + sheet.error = None; + } + } + Act::Withdraw(share_id) => { + let seq = self.issue(Request::Withdraw { share_id: share_id.clone() }); + if let Some(sheet) = &mut self.open { + sheet.withdrawing.push((seq, share_id)); + } + } + Act::Avatar(url) => { + if self.avatars.contains_key(&url) { + continue; + } + if self.avatars.len() >= AVATARS { + for (_, avatar) in self.avatars.drain() { + if let Avatar::Ready(uri) = avatar { + ctx.forget_image(&uri); + } + } + } + let seq = self.issue(Request::Avatar { url: url.clone() }); + self.avatars.insert(url, Avatar::Pending(seq)); + } + } + } + } +} + +// ---- drawing -------------------------------------------------------------- + +fn draw(ui: &mut Ui, sheet: &mut Sheet, avatars: &HashMap, labels: &ShareLabels, allowed: Allowed, acts: &mut Vec) { + let weak = ui.visuals().weak_text_color(); + let danger = ui.visuals().error_fg_color; + + // The document is named in the title, in quotes. This dialog gives other + // people access to one specific thing, and sharing the wrong one is the + // mistake it exists to prevent. + ui.horizontal(|ui| { + let heading = if sheet.title.is_empty() { labels.title.clone() } else { format!("{} \u{201c}{}\u{201d}", labels.title, sheet.title) }; + ui.label(RichText::new(heading).strong().size(15.0)); + ui.with_layout(Layout::right_to_left(Align::Center), |ui| { + let close = egui::Button::new(RichText::new("\u{00d7}").size(18.0)).frame(false); + if ui.add(close).on_hover_text(labels.close.as_str()).clicked() { + acts.push(Act::Close); + } + }); + }); + ui.add_space(8.0); + + // Nothing to share yet. The old build stopped here with a sentence and a + // Close button, naming the obstacle and leaving somebody to deal with it + // elsewhere. Saving is the first step of sharing now. + if sheet.id.is_empty() { + save_first(ui, sheet, labels, acts); + return; + } + + // Who, and what they may do, on one row. The permission applies to these + // recipients, so it belongs beside them. A separate pair of radio buttons + // further down reads as an unrelated setting. + ui.horizontal_top(|ui| { + let width = (ui.available_width() - 104.0).max(160.0); + ui.allocate_ui(egui::vec2(width, 0.0), |ui| { + recipients(ui, sheet, avatars, labels, allowed, acts); + }); + permission_menu(ui, sheet, labels); + }); + // Only once something has actually been asked. "No matches" under an + // untouched field reads as a failure before any search ran. + if sheet.searching || !sheet.matches.is_empty() || sheet.query.trim().chars().count() >= MIN_QUERY { + matches(ui, sheet, avatars, labels, allowed, acts); + } + + ui.add_space(6.0); + + // The message, as a bordered area with its own placeholder. People write a + // sentence here, not a value, and a label above a one-line field invites + // neither. + // TextEdit draws its own border, so no group around it. Wrapping one in a + // Frame::group gives two nested borders. + ui.add( + egui::TextEdit::multiline(&mut sheet.note) + .hint_text(labels.message_hint.as_str()) + .desired_width(f32::INFINITY) + .desired_rows(3) + .char_limit(500), + ); + + ui.add_space(8.0); + + // One primary action, on the right where the eye finishes. Notify sits + // beside it rather than loose in the middle of the form. + // A link, for anybody who has no account. Drawn only where the server + // allows public links, because an administrator can forbid them and a + // button that always fails is worse than no button. + if allowed.links { + ui.horizontal(|ui| { + if allowed.key { + ui.add(egui::TextEdit::singleline(&mut sheet.link_key).hint_text(labels.key_hint.as_str()).password(true).desired_width(150.0)); + } + // A key the server insists on cannot be skipped, so the control + // stays disabled until one is typed. + let keyed = !sheet.link_key.trim().is_empty(); + let ready = keyed || !allowed.key_required; + if ui.add_enabled(ready, egui::Button::new(labels.create_link.as_str())).clicked() { + acts.push(Act::Grant(Grant { + id: sheet.id.clone(), + targets: vec![ShareTarget::Link], + permission: sheet.permission, + note: Some(sheet.note.trim().to_owned()).filter(|n| !n.is_empty()), + notify: false, + password: Some(sheet.link_key.trim().to_owned()).filter(|k| !k.is_empty()), + })); + } + if allowed.key_required && !keyed { + ui.label(RichText::new(labels.key_required_note.as_str()).small().color(weak)); + } + }); + ui.add_space(6.0); + } + + ui.horizontal(|ui| { + if allowed.mail { + ui.checkbox(&mut sheet.notify, labels.notify.as_str()); + } else { + // Reported, never assumed. A server with no mail is said to have + // none, instead of being given a box that quietly does nothing. + sheet.notify = false; + ui.add_enabled(false, egui::Checkbox::new(&mut sheet.notify, labels.notify.as_str())).on_disabled_hover_text(labels.no_mail.as_str()); + } + + ui.with_layout(Layout::right_to_left(Align::Center), |ui| { + let busy = sheet.granting.is_some(); + let ready = !sheet.chosen.is_empty() && !busy; + let label = if busy { labels.sharing.clone() } else { labels.send.clone() }; + let send = egui::Button::new(RichText::new(label).strong()).fill(ui.visuals().selection.bg_fill).min_size(egui::vec2(88.0, 26.0)); + if ui.add_enabled(ready, send).clicked() { + acts.push(Act::Grant(Grant { + id: sheet.id.clone(), + password: None, + targets: sheet.chosen.iter().map(|c| c.target.clone()).collect(), + permission: sheet.permission, + note: Some(sheet.note.trim().to_owned()).filter(|n| !n.is_empty()), + notify: sheet.notify, + })); + } + if ui.button(labels.close.as_str()).clicked() { + acts.push(Act::Close); + } + }); + }); + + outcome(ui, sheet, labels, danger); + + // Who already holds the document, open. Folding it hid the one fact + // a person needs before adding anybody else. It still folds on request. + ui.add_space(4.0); + egui::CollapsingHeader::new(RichText::new(labels.manage_access.as_str()).color(weak)) + .id_salt("craft-ui/share/manage-access") + .default_open(true) + .show(ui, |ui| { + access(ui, sheet, labels, weak, acts); + }); +} + +/// Where to put it, then what to call it. +/// +/// A document with no handle cannot be shared. Rather than saying so and +/// stopping, this offers the places it could go, each naming the account it +/// would land in, with a sign-in for any that is configured without one. +/// +/// A list, because there is rarely only one answer. A second provider is an +/// implementation of the contracts, and this is where it shows up. +fn save_first(ui: &mut Ui, sheet: &mut Sheet, labels: &ShareLabels, acts: &mut Vec) { + let weak = ui.visuals().weak_text_color(); + ui.label(labels.upload_first.as_str()); + ui.add_space(8.0); + + let Some(destinations) = sheet.destinations.clone() else { + ui.horizontal(|ui| { + ui.spinner(); + ui.label(RichText::new(labels.loading.as_str()).color(weak)); + }); + return; + }; + + for destination in &destinations { + let chosen = sheet.destination.as_deref() == Some(destination.id.as_str()); + let stroke = if chosen { ui.visuals().selection.stroke } else { ui.visuals().widgets.noninteractive.bg_stroke }; + let row = egui::Frame::group(ui.style()) + .stroke(stroke) + .show(ui, |ui| { + ui.set_width(ui.available_width()); + ui.horizontal(|ui| { + ui.vertical(|ui| { + ui.label(RichText::new(destination.name.as_str()).strong()); + // The account, because two entries both reading + // "Cloud" tell nobody which one a document is about to + // land in. + let under = if destination.linked { destination.account.clone().unwrap_or_default() } else { labels.sign_in.clone() }; + ui.label(RichText::new(under).small().color(weak)); + }); + }); + }) + .response + .interact(egui::Sense::click()); + if row.clicked() { + if destination.linked { + sheet.destination = Some(destination.id.clone()); + } else { + acts.push(Act::Link(destination.id.clone())); + } + } + ui.add_space(4.0); + } + + if let Some(problem) = &sheet.save_error { + ui.add_space(4.0); + ui.label(RichText::new(problem).color(ui.visuals().error_fg_color)); + } + + let Some(into) = sheet.destination.clone() else { return }; + + ui.add_space(8.0); + let saving = sheet.saving.is_some(); + ui.add_enabled(!saving, egui::TextEdit::singleline(&mut sheet.save_as).hint_text(labels.name_hint.as_str()).desired_width(f32::INFINITY)); + + ui.add_space(8.0); + ui.horizontal(|ui| { + let named = !sheet.save_as.trim().is_empty(); + let label = if saving { labels.saving.clone() } else { labels.save_and_share.clone() }; + let button = egui::Button::new(RichText::new(label).strong()).fill(ui.visuals().selection.bg_fill).min_size(egui::vec2(124.0, 26.0)); + if ui.add_enabled(named && !saving, button).clicked() { + acts.push(Act::SaveAs { destination: into.clone(), name: sheet.save_as.trim().to_owned() }); + } + if ui.button(labels.close.as_str()).clicked() { + acts.push(Act::Close); + } + }); +} + +/// The permission picker, as a menu with a line of explanation under each +/// choice. +/// +/// Two radio buttons reading View and Edit leave the difference to be guessed. +/// Only the permissions the contracts can actually keep are offered: a choice +/// the server cannot honour is worse than one fewer choice. +fn permission_menu(ui: &mut Ui, sheet: &mut Sheet, labels: &ShareLabels) { + let current = match sheet.permission { + Permission::Edit => labels.can_edit.as_str(), + Permission::View => labels.can_view.as_str(), + }; + // A triangle, so it reads as something that opens. Painted rather than + // typed: the character is missing from the default font set, where it + // renders as a box. + let button = ui.button(format!("{current} ")); + crate::buttons::chevron(ui, button.rect, ui.visuals().text_color()); + // The padding makes room for the triangle. It is layout, so it must not + // reach anybody reading the screen aloud. + button.widget_info(|| egui::WidgetInfo::labeled(egui::Role::Button, true, current)); + egui::Popup::menu(&button).show(|ui| { + ui.set_min_width(190.0); + for (value, name, detail) in [ + (Permission::Edit, labels.can_edit.as_str(), labels.can_edit_detail.as_str()), + (Permission::View, labels.can_view.as_str(), labels.can_view_detail.as_str()), + ] { + let chosen = sheet.permission == value; + if ui.selectable_label(chosen, RichText::new(name).strong()).clicked() { + sheet.permission = value; + ui.close(); + } + ui.label(RichText::new(detail).small().color(ui.visuals().weak_text_color())); + ui.add_space(2.0); + } + }); +} + +/// The chips, and the field that adds another. +fn recipients(ui: &mut Ui, sheet: &mut Sheet, avatars: &HashMap, labels: &ShareLabels, allowed: Allowed, acts: &mut Vec) { + let now = ui.input(|i| i.time); + egui::Frame::group(ui.style()).show(ui, |ui| { + ui.horizontal_wrapped(|ui| { + let mut remove = None; + for (i, chosen) in sheet.chosen.iter().enumerate() { + if chip(ui, avatars, chosen, labels, acts).clicked() { + remove = Some(i); + } + } + if let Some(i) = remove.filter(|i| *i < sheet.chosen.len()) { + sheet.chosen.remove(i); + } + + let field = ui.add( + egui::TextEdit::singleline(&mut sheet.query) + .id(ShareDialog::query_field_id()) + .hint_text(labels.recipient_hint.as_str()) + // Fills whatever the chips left. A fixed width leaves a + // short field floating in a frame twice as wide. + .desired_width(ui.available_width().max(120.0)), + ); + if field.changed() { + sheet.typed = Some(now); + } + // Backspace on an empty field takes the last chip back, which is + // what every other recipient field does. + if field.has_focus() && sheet.query.is_empty() && ui.input(|i| i.key_pressed(egui::Key::Backspace)) { + sheet.chosen.pop(); + } + if field.lost_focus() && ui.input(|i| i.key_pressed(egui::Key::Enter)) { + commit(sheet); + } + }); + }); + + // The debounce. Asking per keystroke asks five times for "annie" and + // paints whichever answer happens to arrive last. + if let Some(at) = sheet.typed { + let wait = DEBOUNCE.as_secs_f64(); + if now - at >= wait { + sheet.typed = None; + let query = sheet.query.trim().to_owned(); + if allowed.contacts && query.chars().count() >= MIN_QUERY { + // Set here rather than when the request is issued, so the + // frame that fires it does not read as "no matches". + sheet.searching = true; + acts.push(Act::Lookup(query)); + } else { + sheet.matches.clear(); + sheet.searching = false; + } + } else { + // Without this the frame that fires the lookup only arrives when + // something else happens to ask for a repaint. + ui.ctx().request_repaint_after(Duration::from_secs_f64((wait - (now - at)).clamp(0.0, wait))); + } + } +} + +/// Take whatever has been typed as a recipient: the first match if there is +/// one, otherwise an address if it looks like one. +fn commit(sheet: &mut Sheet) { + let typed = sheet.query.trim().to_lowercase(); + + // An exact match wins. Somebody who typed a whole address that belongs to + // an account should get the account, because a share to an account appears + // in their files rather than only in their inbox. + if let Some(exact) = sheet + .matches + .iter() + .find(|c| c.id.to_lowercase() == typed || c.email.as_deref().is_some_and(|e| e.to_lowercase() == typed) || c.name.to_lowercase() == typed) + .cloned() + { + choose(sheet, &exact); + return; + } + + // Then whatever was typed, if it is an address. The list is a convenience + // and not the set of permitted answers: taking its first row here would + // share with whoever happened to match the opening characters of an + // address somebody typed out in full. + if let Some(address) = address(&sheet.query) { + add(sheet, ShareTarget::Email(address.clone()), address, None, None); + return; + } + + // Otherwise the best the list has, which is what a partial name means. + if let Some(contact) = sheet.matches.first().cloned() { + choose(sheet, &contact); + } +} + +fn matches(ui: &mut Ui, sheet: &mut Sheet, avatars: &HashMap, labels: &ShareLabels, allowed: Allowed, acts: &mut Vec) { + let weak = ui.visuals().weak_text_color(); + // Somebody with no account on this server is reached by address or not at + // all, so the one way to do that is said out loud. A dialog that hides it + // leaves the user guessing which keys work. + if sheet.matches.is_empty() + && address(&sheet.query).is_some() + && !sheet.chosen.iter().any(|c| c.target == ShareTarget::Email(sheet.query.trim().to_owned())) + { + ui.label(RichText::new(labels.add_address.as_str()).color(weak)); + } + if !allowed.contacts { + return; + } + if sheet.searching && sheet.matches.is_empty() { + ui.label(RichText::new(labels.searching.as_str()).color(weak)); + return; + } + if sheet.matches.is_empty() { + if sheet.typed.is_none() && sheet.query.trim().chars().count() >= MIN_QUERY && address(&sheet.query).is_none() { + ui.label(RichText::new(labels.no_matches.as_str()).color(weak)); + } + return; + } + let mut pick = None; + egui::ScrollArea::vertical().max_height(150.0).id_salt("craft-ui/share/matches").show(ui, |ui| { + for (i, contact) in sheet.matches.iter().enumerate() { + if row(ui, avatars, contact, labels, acts).clicked() { + pick = Some(i); + } + } + }); + if let Some(contact) = pick.and_then(|i| sheet.matches.get(i).cloned()) { + choose(sheet, &contact); + } +} + +fn outcome(ui: &mut Ui, sheet: &Sheet, labels: &ShareLabels, danger: Color32) { + if let Some(error) = &sheet.error { + ui.colored_label(danger, error.as_str()); + } + if !sheet.shared.is_empty() { + let who: Vec = sheet.shared.iter().map(|s| share_label(s, labels)).collect(); + ui.label(format!("{}: {}", labels.shared_with, who.join(", "))); + } + // One line each. Five recipients with one bad address shares with four and + // names the one that failed; collapsing that into a single error would + // hide both halves. + for failure in &sheet.failed { + ui.colored_label(danger, format!("{} {}: {}", labels.not_shared_with, target_label(&failure.target, labels), describe(failure))); + } +} + +fn describe(failure: &Failure) -> String { + if failure.detail.trim().is_empty() { failure.code.clone() } else { failure.detail.clone() } +} + +fn access(ui: &mut Ui, sheet: &Sheet, labels: &ShareLabels, weak: Color32, acts: &mut Vec) { + // The header above already names this list. Naming it twice reads as + // two headings for one thing. + let Some(list) = &sheet.access else { + ui.label(RichText::new(labels.loading.as_str()).color(weak)); + return; + }; + if list.is_empty() { + ui.label(RichText::new(labels.access_empty.as_str()).color(weak)); + return; + } + egui::ScrollArea::vertical().max_height(160.0).id_salt("craft-ui/share/access").show(ui, |ui| { + for share in list { + ui.horizontal(|ui| { + ui.label(share_label(share, labels)); + let permission = match share.permission { + Permission::View => labels.can_view.as_str(), + Permission::Edit => labels.can_edit.as_str(), + }; + ui.label(RichText::new(permission).color(weak)); + ui.with_layout(Layout::right_to_left(Align::Center), |ui| { + let busy = sheet.withdrawing.iter().any(|(_, id)| *id == share.id); + // A bin, with the word on hover. The row is already a + // line of text; a second word on it reads as more content + // rather than as the control it is. + let glyph = if busy { "\u{22ef}" } else { "\u{1f5d1}" }; + let bin = egui::Button::new(RichText::new(glyph).size(15.0)).frame(false); + let hint = if busy { labels.withdrawing.as_str() } else { labels.withdraw.as_str() }; + let pressed = ui.add_enabled(!busy, bin); + // A glyph is not a name. Left alone this button announces itself + // to a screen reader as a wastebasket character, so the word goes + // on explicitly. + pressed.widget_info(|| egui::WidgetInfo::labeled(egui::Role::Button, !busy, hint)); + if pressed.on_hover_text(hint).clicked() { + acts.push(Act::Withdraw(share.id.clone())); + } + if let Some(url) = &share.url + && ui.small_button(labels.copy_link.as_str()).clicked() + { + ui.ctx().copy_text(url.clone()); + } + }); + }); + if let Some(note) = &share.note + && !note.trim().is_empty() + { + ui.label(RichText::new(note.as_str()).color(weak).small()); + } + } + }); +} + +// ---- pieces --------------------------------------------------------------- + +/// One picked recipient. The whole chip is the remove control. +fn chip(ui: &mut Ui, avatars: &HashMap, chosen: &Chosen, labels: &ShareLabels, acts: &mut Vec) -> Response { + let background = ui.painter().add(egui::Shape::Noop); + let inner = ui.scope_builder(UiBuilder::new().sense(Sense::click()), |ui| { + // A selectable label senses click and drag of its own, and one drawn + // inside a clickable row wins the hit test over the row itself. For + // narrow rows like a chip the pointer lands on the text nearly always, + // so the press would be swallowed and the chip never removed. + ui.style_mut().interaction.selectable_labels = false; + ui.horizontal(|ui| { + ui.add_space(3.0); + picture(ui, avatars, chosen.avatar.as_deref(), &chosen.label, acts); + ui.label(chosen.label.as_str()); + // The same cross the dialog closes with. U+2715 is absent from + // the default font set, where it renders as a box. + ui.label(RichText::new("×").color(ui.visuals().weak_text_color())); + ui.add_space(1.0); + }); + }); + let response = inner.response; + let fill = if response.hovered() { ui.visuals().widgets.hovered.bg_fill } else { ui.visuals().widgets.inactive.bg_fill }; + ui.painter().set(background, egui::Shape::rect_filled(response.rect, CornerRadius::same(AVATAR_RADIUS), fill)); + let label = format!("{} {}", labels.remove, chosen.label); + response.widget_info(|| egui::WidgetInfo::labeled(egui::Role::Button, ui.is_enabled(), label.clone())); + // The address, where there is one. Two colleagues share a display name + // often enough that a chip reading "Ann Reed" is not an identity. + let hint = match &chosen.detail { + Some(detail) if !detail.is_empty() => format!("{} · {detail}", labels.remove), + _ => labels.remove.clone(), + }; + response.on_hover_text(hint) +} + +/// One match in the autocomplete list. +fn row(ui: &mut Ui, avatars: &HashMap, contact: &Contact, labels: &ShareLabels, acts: &mut Vec) -> Response { + let background = ui.painter().add(egui::Shape::Noop); + let width = ui.available_width(); + let inner = ui.scope_builder(UiBuilder::new().sense(Sense::click()), |ui| { + // A selectable label senses click and drag of its own, and one drawn + // inside a clickable row wins the hit test over the row itself. For + // narrow rows like a chip the pointer lands on the text nearly always, + // so the press would be swallowed and the chip never removed. + ui.style_mut().interaction.selectable_labels = false; + ui.set_min_width(width); + ui.horizontal(|ui| { + ui.add_space(3.0); + picture(ui, avatars, contact.avatar.as_deref(), &contact.name, acts); + ui.label(contact.name.as_str()); + let detail = if contact.is_group { format!("({})", labels.group) } else { contact.email.clone().unwrap_or_default() }; + if !detail.is_empty() { + ui.label(RichText::new(detail).color(ui.visuals().weak_text_color())); + } + }); + }); + let response = inner.response; + if response.hovered() { + ui.painter().set(background, egui::Shape::rect_filled(response.rect, CornerRadius::same(4), ui.visuals().widgets.hovered.bg_fill)); + } + let label = contact.name.clone(); + response.widget_info(|| egui::WidgetInfo::labeled(egui::Role::Button, ui.is_enabled(), label.clone())); + response +} + +/// A contact picture, or initials while there is none. +/// +/// A picture is asked for here, as the row that needs it is painted, and only +/// when that row is actually on screen. A search answering with ten people +/// therefore costs no pictures at all until they are looked at, and the ones +/// scrolled past below the fold cost nothing either. `avatars` holds every URL +/// ever asked about, the refusals included, so nothing is asked for twice. +fn picture(ui: &mut Ui, avatars: &HashMap, url: Option<&str>, label: &str, acts: &mut Vec) { + let size = Vec2::splat(AVATAR); + let (rect, _) = ui.allocate_exact_size(size, Sense::hover()); + match url.and_then(|u| avatars.get(u)) { + Some(Avatar::Ready(uri)) => { + let image = egui::Image::from_uri(uri.clone()).fit_to_exact_size(size).corner_radius(CornerRadius::same(AVATAR_RADIUS)); + if image.load_for_size(ui.ctx(), size).is_ok() { + image.paint_at(ui, rect); + return; + } + } + Some(_) => {} + None => { + if let Some(url) = url.filter(|_| ui.is_rect_visible(rect)) { + acts.push(Act::Avatar(url.to_owned())); + } + } + } + ui.painter().circle_filled(rect.center(), AVATAR / 2.0, ui.visuals().widgets.inactive.bg_fill); + ui.painter().text(rect.center(), Align2::CENTER_CENTER, initials(label), FontId::proportional(AVATAR * 0.42), ui.visuals().text_color()); +} + +fn initials(label: &str) -> String { + label.split_whitespace().filter_map(|word| word.chars().next()).take(2).flat_map(|c| c.to_uppercase()).collect() +} + +/// A stable URI for one avatar's bytes. egui caches by URI, so two contacts +/// must never share one. +fn avatar_uri(url: &str) -> String { + use std::hash::{Hash as _, Hasher as _}; + let mut hasher = std::hash::DefaultHasher::new(); + url.hash(&mut hasher); + format!("bytes://craft-ui/share/avatar/{:016x}", hasher.finish()) +} + +fn choose(sheet: &mut Sheet, contact: &Contact) { + // What the provider said, never a guess from the id. A contact with no + // account is reachable only by address, and sharing that address as a user + // id fails with "not found", because no such user exists. + let target = contact.target.clone(); + add(sheet, target, contact.name.clone(), contact.email.clone(), contact.avatar.clone()); +} + +/// Add one recipient, unless it is already there. +fn add(sheet: &mut Sheet, target: ShareTarget, label: String, detail: Option, avatar: Option) { + if !sheet.chosen.iter().any(|c| c.target == target) { + sheet.chosen.push(Chosen { target, label, detail, avatar }); + } + sheet.query.clear(); + sheet.matches.clear(); + sheet.typed = None; + sheet.searching = false; + sheet.lookup = None; +} + +/// What the user typed, when it is an address and not a name. +/// +/// Deliberately shallow. The server decides whether an address exists, and a +/// strict local check would refuse valid addresses it had not heard of. +fn address(typed: &str) -> Option { + let typed = typed.trim(); + if typed.chars().any(char::is_whitespace) { + return None; + } + let (user, host) = typed.split_once('@')?; + if user.is_empty() || host.len() < 3 || !host.contains('.') || host.starts_with('.') || host.ends_with('.') || host.contains('@') { + return None; + } + Some(typed.to_owned()) +} + +/// What to call the person or group a share is with. +/// +/// The handle is the fallback. Showing an account id to somebody who knows +/// that person by name tells them nothing, and two colleagues with similar +/// ids are indistinguishable. +fn share_label(share: &Share, labels: &ShareLabels) -> String { + match share.display.as_deref().filter(|name| !name.trim().is_empty()) { + Some(name) => match share.target { + ShareTarget::Group(_) => format!("{name} ({})", labels.group), + _ => name.to_owned(), + }, + None => target_label(&share.target, labels), + } +} + +fn target_label(target: &ShareTarget, labels: &ShareLabels) -> String { + match target { + ShareTarget::User(id) => id.clone(), + ShareTarget::Group(id) => format!("{id} ({})", labels.group), + ShareTarget::Email(address) => address.clone(), + ShareTarget::Link => labels.anyone_with_link.clone(), + } +} diff --git a/crates/cloud-ui/src/share/tests.rs b/crates/cloud-ui/src/share/tests.rs new file mode 100644 index 000000000..dfdb3eb1e --- /dev/null +++ b/crates/cloud-ui/src/share/tests.rs @@ -0,0 +1,527 @@ +//! The dialog's state machine, with no server and no window. +//! +//! What matters here is what the dialog does with answers: that it offers +//! nothing until the service says sharing exists, that an answer the user has +//! typed past is thrown away rather than painted, that a share reaching four +//! of five people says which one it missed, and that a picture nobody can +//! fetch is asked for once. + +use std::sync::{Arc, Mutex}; + +use super::*; + +/// A backend that records what was asked and answers nothing, so a test +/// decides when each answer arrives and in which order. +#[derive(Clone, Default)] +struct Silent(Arc>>); + +impl Silent { + fn seen(&self) -> Vec { + self.0.lock().map(|seen| seen.clone()).unwrap_or_default() + } +} + +impl ShareBackend for Silent { + fn submit(&self, request: Request, _reply: Replier) { + if let Ok(mut seen) = self.0.lock() { + seen.push(request); + } + } +} + +fn can(capabilities: Vec) -> Answer { + Answer::Capabilities { capabilities, linked: true } +} + +fn everything() -> Answer { + can(vec![Capability::Sharing, Capability::Contacts, Capability::Mail]) +} + +/// A connected dialog that has been told sharing works, open on one document. +fn ready() -> (Context, ShareDialog, Silent) { + let ctx = Context::default(); + let backend = Silent::default(); + let mut dialog = ShareDialog::new(); + dialog.connect(backend.clone()); + dialog.collect(&ctx); + dialog.receive(&ctx, 1, Ok(everything())); + dialog.open("files/budget.xlsx", "Budget"); + (ctx, dialog, backend) +} + +fn person(id: &str, name: &str) -> Contact { + Contact { + id: id.into(), + target: ShareTarget::User(id.into()), + name: name.into(), + email: Some(format!("{id}@example.com")), + avatar: None, + is_group: false, + } +} + +fn share(id: &str, target: ShareTarget) -> Share { + Share { id: id.into(), target, display: None, permission: Permission::View, url: None, note: None, created: None } +} + +#[test] +fn a_share_is_labelled_with_the_name_the_provider_gave() { + let labels = ShareLabels::default(); + let mut one = share("s1", ShareTarget::User("adunn".to_owned())); + assert_eq!(super::share_label(&one, &labels), "adunn", "the handle is all there is"); + one.display = Some("Ada Lovelace".to_owned()); + assert_eq!(super::share_label(&one, &labels), "Ada Lovelace"); + // A provider that answers with an empty string has said nothing. + one.display = Some(" ".to_owned()); + assert_eq!(super::share_label(&one, &labels), "adunn"); + + let mut team = share("s2", ShareTarget::Group("eng".to_owned())); + team.display = Some("Engineering".to_owned()); + assert_eq!(super::share_label(&team, &labels), format!("Engineering ({})", labels.group)); + + // A link is not a person and never carries one. + assert_eq!(super::share_label(&share("s3", ShareTarget::Link), &labels), labels.anyone_with_link); +} + +#[test] +fn nothing_is_offered_until_the_service_says_sharing_exists() { + let ctx = Context::default(); + let backend = Silent::default(); + let mut dialog = ShareDialog::new(); + assert!(!dialog.available(), "an unconnected dialog cannot share"); + + dialog.connect(backend.clone()); + assert_eq!(backend.seen(), Vec::new(), "connecting alone asks nothing"); + dialog.collect(&ctx); + assert_eq!(backend.seen(), vec![Request::Capabilities]); + + // Still unanswered: the question is outstanding, so the answer is no. + assert!(!dialog.available()); + dialog.open("files/budget.xlsx", "Budget"); + assert!(!dialog.is_open(), "the dialog must not open before the answer"); + + // A provider with files but no sharing hides the feature rather than + // offering a button that fails. + dialog.receive(&ctx, 1, Ok(can(vec![Capability::Files, Capability::Contacts]))); + assert!(!dialog.available()); + dialog.open("files/budget.xlsx", "Budget"); + assert!(!dialog.is_open()); + + dialog.receive(&ctx, 1, Ok(everything())); + assert!(dialog.available()); + dialog.open("files/budget.xlsx", "Budget"); + assert!(dialog.is_open()); +} + +#[test] +fn an_unlinked_account_cannot_share_even_where_the_provider_can() { + let ctx = Context::default(); + let mut dialog = ShareDialog::new(); + dialog.connect(Silent::default()); + dialog.receive(&ctx, 1, Ok(Answer::Capabilities { capabilities: vec![Capability::Sharing], linked: false })); + assert!(!dialog.available()); +} + +#[test] +fn losing_sharing_closes_a_dialog_that_was_already_up() { + let (ctx, mut dialog, _) = ready(); + assert!(dialog.is_open()); + dialog.receive(&ctx, 1, Ok(can(vec![Capability::Files]))); + assert!(!dialog.is_open(), "a dialog that cannot do anything must not stay up"); +} + +#[test] +fn opening_asks_who_already_has_access() { + let (_ctx, dialog, backend) = ready(); + assert_eq!(backend.seen(), vec![Request::Capabilities, Request::Access { id: "files/budget.xlsx".into() }]); + assert!(dialog.is_open()); +} + +#[test] +fn an_unsaved_document_asks_where_it_could_go_and_never_about_a_handle() { + let ctx = Context::default(); + let backend = Silent::default(); + let mut dialog = ShareDialog::new(); + dialog.connect(backend.clone()); + dialog.collect(&ctx); + dialog.receive(&ctx, 1, Ok(everything())); + dialog.open("", "Book1"); + assert!(dialog.is_open()); + // Sharing an unsaved document means saving it first. The dialog therefore + // needs somewhere to offer. It asks nothing about a handle. There is none. + assert_eq!(backend.seen(), vec![Request::Capabilities, Request::Destinations]); + assert!(!backend.seen().iter().any(|r| matches!(r, Request::Access { .. })), "there is no handle to ask about"); +} + +#[test] +fn an_answer_the_user_has_typed_past_is_dropped() { + let (ctx, mut dialog, _) = ready(); + let early = dialog.issue(Request::Lookup { query: "an".into(), limit: MATCHES }); + let late = dialog.issue(Request::Lookup { query: "ann".into(), limit: MATCHES }); + if let Some(sheet) = &mut dialog.open { + sheet.lookup = Some(late); + sheet.searching = true; + } + + // The first query answers second, which is what a service under load + // does. Painting it would show matches for "an" under the text "ann". + dialog.receive(&ctx, late, Ok(Answer::Lookup(vec![person("ann", "Ann Reed")]))); + dialog.receive(&ctx, early, Ok(Answer::Lookup(vec![person("andy", "Andy Shaw"), person("anna", "Anna Beck")]))); + + let sheet = dialog.open.as_ref().expect("still open"); + assert_eq!(sheet.matches.len(), 1); + assert_eq!(sheet.matches.first().map(|c| c.name.as_str()), Some("Ann Reed")); + assert!(!sheet.searching); +} + +#[test] +fn several_recipients_can_be_picked_and_each_only_once() { + let (_ctx, mut dialog, _) = ready(); + let sheet = dialog.open.as_mut().expect("open"); + for contact in [person("ann", "Ann Reed"), person("bob", "Bob Vine"), person("ann", "Ann Reed")] { + choose(sheet, &contact); + } + choose( + sheet, + &Contact { + id: "finance".into(), + target: ShareTarget::Group("finance".into()), + name: "Finance".into(), + email: None, + avatar: None, + is_group: true, + }, + ); + + let picked: Vec<&ShareTarget> = sheet.chosen.iter().map(|c| &c.target).collect(); + assert_eq!( + picked, + vec![&ShareTarget::User("ann".into()), &ShareTarget::User("bob".into()), &ShareTarget::Group("finance".into())], + "a group shares as a group, and picking the same person twice adds one chip" + ); + assert!(sheet.query.is_empty(), "picking clears what was typed"); +} + +#[test] +fn a_share_reaching_four_of_five_names_the_fifth() { + let (ctx, mut dialog, _) = ready(); + let sheet = dialog.open.as_mut().expect("open"); + for who in ["ann", "bob", "cal", "dee"] { + choose(sheet, &person(who, who)); + } + add(sheet, ShareTarget::Email("nobody@@".into()), "nobody@@".into(), None, None); + let granting = dialog.issue(Request::Grant(Grant { + id: "files/budget.xlsx".into(), + password: None, + targets: Vec::new(), + permission: Permission::Edit, + note: None, + notify: true, + })); + if let Some(sheet) = &mut dialog.open { + sheet.granting = Some(granting); + } + + let shared: Vec = + ["ann", "bob", "cal", "dee"].iter().enumerate().map(|(i, who)| share(&format!("s{i}"), ShareTarget::User((*who).into()))).collect(); + let failed = + vec![Failure { target: ShareTarget::Email("nobody@@".into()), code: "invalid_address".into(), detail: "nobody@@ is not an address".into() }]; + dialog.receive(&ctx, granting, Ok(Answer::Granted { shared, failed })); + + let (shared, failed) = dialog.outcome(); + assert_eq!(shared.len(), 4); + assert_eq!(failed.len(), 1, "a wrong address is named, not folded into one error"); + assert_eq!(failed.first().map(|f| f.detail.as_str()), Some("nobody@@ is not an address")); + + // The four that went through leave the picker; the one that did not stays, + // so correcting it is one edit rather than a retyped list. + let left = dialog.open.as_ref().expect("open"); + assert_eq!(left.chosen.len(), 1); + assert_eq!(left.chosen.first().map(|c| &c.target), Some(&ShareTarget::Email("nobody@@".into()))); +} + +#[test] +fn a_refusal_that_stopped_the_whole_call_is_not_a_failed_recipient() { + let (ctx, mut dialog, _) = ready(); + let granting = dialog.issue(Request::Grant(Grant { + id: "files/budget.xlsx".into(), + password: None, + targets: vec![ShareTarget::User("ann".into())], + permission: Permission::View, + note: None, + notify: false, + })); + if let Some(sheet) = &mut dialog.open { + sheet.granting = Some(granting); + } + dialog.receive(&ctx, granting, Err("sign in again".into())); + + let sheet = dialog.open.as_ref().expect("open"); + assert_eq!(sheet.error.as_deref(), Some("sign in again")); + assert!(sheet.failed.is_empty()); + assert!(sheet.granting.is_none(), "the button must come back"); +} + +#[test] +fn a_successful_share_reloads_who_has_access() { + let (ctx, mut dialog, backend) = ready(); + let granting = dialog.issue(Request::Grant(Grant { + id: "files/budget.xlsx".into(), + password: None, + targets: vec![ShareTarget::User("ann".into())], + permission: Permission::View, + note: None, + notify: false, + })); + if let Some(sheet) = &mut dialog.open { + sheet.granting = Some(granting); + } + dialog.receive(&ctx, granting, Ok(Answer::Granted { shared: vec![share("s1", ShareTarget::User("ann".into()))], failed: Vec::new() })); + let asked = backend.seen().iter().filter(|r| **r == Request::Access { id: "files/budget.xlsx".into() }).count(); + assert_eq!(asked, 2, "the list is stale the moment a share succeeds"); +} + +#[test] +fn withdrawing_takes_it_off_the_list_and_only_then() { + let (ctx, mut dialog, backend) = ready(); + let access = dialog.open.as_ref().and_then(|s| s.access_seq).expect("asked"); + dialog.receive( + &ctx, + access, + Ok(Answer::Access(vec![share("s1", ShareTarget::User("ann".into())), share("s2", ShareTarget::Group("finance".into()))])), + ); + dialog.apply(&ctx, vec![Act::Withdraw("s1".into())]); + + let waiting = dialog.open.as_ref().expect("open"); + assert_eq!(waiting.access.as_ref().map(Vec::len), Some(2), "it stays until the server agrees"); + assert_eq!(waiting.withdrawing.len(), 1); + assert!(backend.seen().contains(&Request::Withdraw { share_id: "s1".into() })); + + let seq = waiting.withdrawing.first().map(|(seq, _)| *seq).expect("in flight"); + dialog.receive(&ctx, seq, Ok(Answer::Withdrawn { share_id: "s1".into() })); + let after = dialog.open.as_ref().expect("open"); + assert_eq!(after.access.as_ref().map(|a| a.iter().map(|s| s.id.as_str()).collect::>()), Some(vec!["s2"])); + assert!(after.withdrawing.is_empty()); +} + +#[test] +fn a_refused_withdrawal_leaves_the_share_and_says_why() { + let (ctx, mut dialog, _) = ready(); + let access = dialog.open.as_ref().and_then(|s| s.access_seq).expect("asked"); + dialog.receive(&ctx, access, Ok(Answer::Access(vec![share("s1", ShareTarget::User("ann".into()))]))); + dialog.apply(&ctx, vec![Act::Withdraw("s1".into())]); + let seq = dialog.open.as_ref().and_then(|s| s.withdrawing.first().map(|(seq, _)| *seq)).expect("in flight"); + dialog.receive(&ctx, seq, Err("you do not own this share".into())); + + let sheet = dialog.open.as_ref().expect("open"); + assert_eq!(sheet.access.as_ref().map(Vec::len), Some(1)); + assert!(sheet.withdrawing.is_empty(), "the button must come back"); + assert_eq!(sheet.error.as_deref(), Some("you do not own this share")); +} + +#[test] +fn a_picture_is_asked_for_once_and_a_refusal_is_remembered() { + let (ctx, mut dialog, backend) = ready(); + let url = "https://cloud.example.com/avatar/ann/64"; + dialog.apply(&ctx, vec![Act::Avatar(url.into()), Act::Avatar(url.into())]); + let asked = backend.seen().iter().filter(|r| **r == Request::Avatar { url: url.into() }).count(); + assert_eq!(asked, 1, "one row painted twice is one picture"); + + let seq = match dialog.avatars.get(url) { + Some(Avatar::Pending(seq)) => *seq, + other => panic!("expected a pending picture, got {other:?}"), + }; + dialog.receive(&ctx, seq, Err("this build does not fetch contact pictures".into())); + assert_eq!(dialog.avatars.get(url), Some(&Avatar::Missing)); + + // Refused once is refused. Painting the row again must not ask again. + dialog.apply(&ctx, vec![Act::Avatar(url.into())]); + let asked = backend.seen().iter().filter(|r| **r == Request::Avatar { url: url.into() }).count(); + assert_eq!(asked, 1); + + // And a refused picture is the dialog's business, not the user's. + assert_eq!(dialog.open.as_ref().and_then(|s| s.error.clone()), None); +} + +#[test] +fn an_unanswered_capability_question_is_asked_again_later() { + let ctx = Context::default(); + let backend = Silent::default(); + let mut dialog = ShareDialog::new(); + dialog.connect(backend.clone()); + dialog.collect(&ctx); + dialog.collect(&ctx); + assert_eq!(backend.seen().len(), 1, "a question already outstanding is not asked every frame"); + + dialog.asked = Some(-RETRY); + dialog.collect(&ctx); + assert_eq!(backend.seen().len(), 2, "one unreachable moment must not hide Share for the session"); + + dialog.receive(&ctx, 2, Ok(everything())); + dialog.asked = Some(-RETRY); + dialog.collect(&ctx); + assert_eq!(backend.seen().len(), 2, "an answered question is not asked again"); +} + +#[test] +fn what_counts_as_an_address() { + for typed in ["ann@example.com", " ann.reed+tag@mail.example.co.uk "] { + assert!(address(typed).is_some(), "{typed} is an address"); + } + for typed in ["ann", "ann@", "@example.com", "ann@example", "ann reed@example.com", "ann@.com", "a@b@c.com", ""] { + assert!(address(typed).is_none(), "{typed} is not an address"); + } + assert_eq!(address(" ann@example.com "), Some("ann@example.com".to_owned()), "the trim is kept"); +} + +#[test] +fn initials_come_from_the_name_and_never_from_an_index() { + assert_eq!(initials("Ann Reed"), "AR"); + assert_eq!(initials("ann"), "A"); + assert_eq!(initials("Ann Marie Reed"), "AM"); + assert_eq!(initials(""), ""); + assert_eq!(initials(" "), ""); + assert_eq!(initials("Ærø Ødegård"), "ÆØ"); + assert_eq!(initials("张 伟"), "张伟"); +} + +#[test] +fn every_kind_of_recipient_reads_as_something() { + let labels = ShareLabels::default(); + assert_eq!(target_label(&ShareTarget::User("ann".into()), &labels), "ann"); + assert_eq!(target_label(&ShareTarget::Group("finance".into()), &labels), "finance (group)"); + assert_eq!(target_label(&ShareTarget::Email("ann@example.com".into()), &labels), "ann@example.com"); + assert_eq!(target_label(&ShareTarget::Link, &labels), "Anyone with the link"); +} + +#[test] +fn a_failure_with_no_detail_still_says_something() { + let bare = Failure { target: ShareTarget::Link, code: "forbidden".into(), detail: " ".into() }; + assert_eq!(describe(&bare), "forbidden"); + let told = Failure { target: ShareTarget::Link, code: "forbidden".into(), detail: "link shares are off".into() }; + assert_eq!(describe(&told), "link shares are off"); +} + +#[test] +fn two_contacts_never_share_one_picture_cache_entry() { + let one = avatar_uri("https://cloud.example.com/avatar/ann/64"); + let two = avatar_uri("https://cloud.example.com/avatar/anna/64"); + assert_ne!(one, two); + assert_eq!(one, avatar_uri("https://cloud.example.com/avatar/ann/64"), "the same URL is the same entry"); + assert!(one.starts_with("bytes://"), "egui's own loaders have to recognize it"); +} + +fn ready_unsaved() -> (Context, ShareDialog, Silent) { + let ctx = Context::default(); + let backend = Silent::default(); + let mut dialog = ShareDialog::new(); + dialog.connect(backend.clone()); + dialog.collect(&ctx); + dialog.receive(&ctx, 1, Ok(everything())); + dialog.open("", "Book1"); + (ctx, dialog, backend) +} + +fn start_save(dialog: &mut ShareDialog, ctx: &Context, destination: &str, name: &str) -> u64 { + dialog.apply(ctx, vec![Act::SaveAs { destination: destination.into(), name: name.into() }]); + let request = dialog.take_save_request().expect("save was handed to the application"); + assert_ne!(request.generation, 0, "taken saves carry the open sheet generation"); + request.generation +} + +#[test] +fn a_stale_save_completion_after_close_does_nothing() { + let (ctx, mut dialog, backend) = ready_unsaved(); + let generation = start_save(&mut dialog, &ctx, "cloud", "Budget"); + dialog.close(); + assert!(!dialog.is_open()); + + dialog.saved("files/wrong.xlsx", "Wrong"); + dialog.saved_if(generation, "files/wrong.xlsx", "Wrong"); + assert!(!dialog.is_open()); + assert!( + !backend.seen().iter().any(|r| matches!(r, Request::Access { id } if id == "files/wrong.xlsx")), + "a completion after close must not ask about the saved handle" + ); +} + +#[test] +fn a_stale_save_completion_after_reopening_another_document_does_nothing() { + let (ctx, mut dialog, backend) = ready_unsaved(); + let generation = start_save(&mut dialog, &ctx, "cloud", "Budget"); + dialog.close(); + dialog.open("files/other.xlsx", "Other"); + assert_eq!(dialog.open.as_ref().map(|s| s.id.as_str()), Some("files/other.xlsx")); + + dialog.saved("files/budget.xlsx", "Budget"); + dialog.saved_if(generation, "files/budget.xlsx", "Budget"); + let sheet = dialog.open.as_ref().expect("still open on the other document"); + assert_eq!(sheet.id, "files/other.xlsx"); + assert_eq!(sheet.title, "Other"); + assert!(sheet.saving.is_none()); + assert!( + !backend.seen().iter().any(|r| matches!(r, Request::Access { id } if id == "files/budget.xlsx")), + "the first document's completion must not rebind the second" + ); +} + +#[test] +fn a_save_completion_on_the_same_open_updates_the_sheet() { + let (ctx, mut dialog, backend) = ready_unsaved(); + let generation = start_save(&mut dialog, &ctx, "cloud", "Budget"); + + dialog.saved_if(generation, "files/budget.xlsx", "Budget"); + let sheet = dialog.open.as_ref().expect("open"); + assert_eq!(sheet.id, "files/budget.xlsx"); + assert_eq!(sheet.title, "Budget"); + assert!(sheet.saving.is_none()); + assert!(backend.seen().iter().any(|r| matches!(r, Request::Access { id } if id == "files/budget.xlsx"))); +} + +#[test] +fn take_save_request_returns_the_open_sheet_generation() { + let (ctx, mut dialog, _) = ready_unsaved(); + let before = dialog.sheet_generation(); + assert_ne!(before, 0); + dialog.apply(&ctx, vec![Act::SaveAs { destination: "cloud".into(), name: "Budget".into() }]); + let request = dialog.take_save_request().expect("taken"); + assert_eq!(request.generation, before); + assert_eq!(request.destination, "cloud"); + assert_eq!(request.name, "Budget"); +} + +#[test] +fn a_closed_dialog_still_collects_and_reports_nothing() { + let (ctx, mut dialog, _) = ready(); + dialog.close(); + assert!(!dialog.is_open()); + dialog.receive(&ctx, 99, Ok(Answer::Lookup(vec![person("ann", "Ann Reed")]))); + dialog.receive(&ctx, 99, Err("gone".into())); + let (shared, failed) = dialog.outcome(); + assert!(shared.is_empty() && failed.is_empty()); +} + +#[test] +fn pressing_return_takes_the_first_match_or_an_address() { + let (_ctx, mut dialog, _) = ready(); + let sheet = dialog.open.as_mut().expect("open"); + + // With matches on screen, Return takes the one at the top. + sheet.query = "an".into(); + sheet.matches = vec![person("ann", "Ann Reed"), person("andy", "Andy Shaw")]; + commit(sheet); + assert_eq!(sheet.chosen.first().map(|c| &c.target), Some(&ShareTarget::User("ann".into()))); + + // With none, an address is taken as itself. Somebody with no account on + // this server is reached by address or not at all. + sheet.query = "outside@example.com".into(); + commit(sheet); + assert_eq!(sheet.chosen.len(), 2); + assert_eq!(sheet.chosen.last().map(|c| &c.target), Some(&ShareTarget::Email("outside@example.com".into()))); + + // A name that matched nothing is not a recipient. + sheet.query = "nobody".into(); + commit(sheet); + assert_eq!(sheet.chosen.len(), 2); + assert_eq!(sheet.query, "nobody", "and what was typed is left alone to be corrected"); +} diff --git a/crates/cloud-ui/tests/renders.rs b/crates/cloud-ui/tests/renders.rs new file mode 100644 index 000000000..3fdff1d0e --- /dev/null +++ b/crates/cloud-ui/tests/renders.rs @@ -0,0 +1,343 @@ +//! Gated on the `share` feature, which is off by default. +#![cfg(feature = "share")] + +//! Renders of the shared controls, for review. +//! +//! The other suites read the accessibility tree and never look at pixels. That +//! catches wrong wording and missing names. It cannot show whether a dialog +//! looks like it belongs in an office suite, and these two controls will sit in +//! every Craft app, so somebody has to be able to see them. +//! +//! Writes nothing unless `CRAFT_UI_RENDERS` names a directory. A suite that +//! wrote files on every run would turn a checkout dirty by testing it. +//! +//! ```sh +//! CRAFT_UI_RENDERS=/tmp/renders cargo test -p craft-cloud-ui --all-features --test renders +//! ``` + +use std::cell::RefCell; +use std::path::PathBuf; +use std::rc::Rc; +use std::sync::{Arc, Mutex}; + +use craft_cloud::{Capability, Contact, Permission, Share, ShareTarget}; +use craft_cloud_ui::account::{Account, AccountMenu}; +use craft_cloud_ui::presence::{Peer, PresenceBar}; +use craft_cloud_ui::share::{Answer, Failure, Replier, Request, ShareBackend, ShareDialog}; +use egui::{Context, Event, FullOutput, PointerButton, Pos2, RawInput, Rect, Theme, Visuals, accesskit, pos2, vec2}; +use egui_kittest::{TestRenderer, wgpu::WgpuTestRenderer}; + +const DOCUMENT: &str = "files/Budget 2026.xlsx"; + +/// A backend that answers what a control needs and parks the rest. +#[derive(Clone, Default)] +struct Fake { + capabilities: Vec, + access: Vec, + parked: Arc>>, +} + +impl ShareBackend for Fake { + fn submit(&self, request: Request, reply: Replier) { + match &request { + Request::Capabilities => { + reply.answer(Answer::Capabilities { capabilities: self.capabilities.clone(), linked: true }); + } + Request::Access { .. } => reply.answer(Answer::Access(self.access.clone())), + _ => { + if let Ok(mut parked) = self.parked.lock() { + parked.push((request, reply)); + } + } + } + } +} + +impl Fake { + fn answer(&self, answer: Answer) { + let taken = self.parked.lock().ok().and_then(|mut p| if p.is_empty() { None } else { Some(p.remove(0)) }); + if let Some((_, reply)) = taken { + reply.answer(answer); + } + } +} + +/// One control, driven frame by frame, with the pixels kept. +struct Shot { + ctx: Context, + /// One renderer per context. A renderer shared between two contexts + /// takes a texture id from the first and is then asked by the second + /// to free one it never registered. + renderer: WgpuTestRenderer, + time: f64, + size: [f32; 2], + typing: bool, + /// The ground the control is painted on. Without it the render carries a + /// transparent background, which reads as a rendering fault. + fill: egui::Color32, +} + +impl Shot { + fn new(theme: Theme, size: [f32; 2]) -> Shot { + let ctx = Context::default(); + ctx.enable_accesskit(); + let visuals = if theme == Theme::Dark { Visuals::dark() } else { Visuals::light() }; + let fill = visuals.panel_fill; + ctx.set_visuals(visuals); + ctx.all_styles_mut(|style| { + style.animation_time = 0.0; + style.visuals.text_cursor.blink = false; + }); + Shot { ctx, renderer: WgpuTestRenderer::new(), time: 0.0, size, typing: false, fill } + } + + fn frame(&mut self, events: Vec, mut draw: impl FnMut(&mut egui::Ui)) -> FullOutput { + self.time += 1.0 / 60.0; + let raw = RawInput { + screen_rect: Some(Rect::from_min_size(Pos2::ZERO, vec2(self.size[0], self.size[1]))), + time: Some(self.time), + events, + ..Default::default() + }; + let ctx = self.ctx.clone(); + if self.typing { + ctx.memory_mut(|m| m.request_focus(ShareDialog::query_field_id())); + } + let fill = self.fill; + let size = self.size; + let mut output = ctx.run_ui(raw, |ui| { + let screen = Rect::from_min_size(Pos2::ZERO, vec2(size[0], size[1])); + ui.painter().rect_filled(screen, 0.0, fill); + draw(ui); + }); + // Every frame's delta has to reach the renderer. The font atlas arrives + // on the first frame, and a renderer that saw only the last one paints + // no text at all. + self.renderer.handle_delta(&mut output.textures_delta); + output + } + + /// Write what the last frame drew. + fn save(&mut self, into: &std::path::Path, name: &str, theme: Theme, output: &FullOutput) { + let image = self.renderer.render(&self.ctx, output).expect("an offscreen renderer is required to write renders"); + let suffix = if theme == Theme::Dark { "dark" } else { "light" }; + let path = into.join(format!("{name}-{suffix}.png")); + image.save(&path).expect("the render directory must be writable"); + println!("wrote {}", path.display()); + } + + /// Press the control carrying this exact accessible name. + fn click(&mut self, label: &str, draw: &mut impl FnMut(&mut egui::Ui)) { + let output = self.frame(Vec::new(), &mut *draw); + let Some(at) = control(&output, label) else { panic!("nothing to click named {label:?}; on screen are {:?}", controls(&output)) }; + self.frame(vec![Event::PointerMoved(at)], &mut *draw); + self.frame(vec![press(at, true)], &mut *draw); + self.frame(vec![press(at, false)], &mut *draw); + } +} + +fn press(at: Pos2, down: bool) -> Event { + Event::PointerButton { pos: at, button: PointerButton::Primary, pressed: down, modifiers: egui::Modifiers::default() } +} + +struct Seen { + role: accesskit::Role, + label: String, + bounds: Option, + disabled: bool, +} + +impl Seen { + fn interactive(&self) -> bool { + matches!(self.role, accesskit::Role::Button | accesskit::Role::TextInput | accesskit::Role::CheckBox | accesskit::Role::Link) + } + + fn at(&self) -> Option { + self.bounds.map(|b| pos2(((b.x0 + b.x1) / 2.0) as f32, ((b.y0 + b.y1) / 2.0) as f32)) + } +} + +fn seen(output: &FullOutput) -> Vec { + let Some(update) = &output.platform_output.accesskit_update else { return Vec::new() }; + update + .nodes + .iter() + .filter_map(|(_, node)| { + node.label().or_else(|| node.value()).map(|text| Seen { + role: node.role(), + label: text.to_owned(), + bounds: node.bounds(), + disabled: node.is_disabled(), + }) + }) + .collect() +} + +fn control(output: &FullOutput, label: &str) -> Option { + seen(output).iter().find(|s| s.interactive() && !s.disabled && s.label == label).and_then(Seen::at) +} + +fn controls(output: &FullOutput) -> Vec { + seen(output).into_iter().filter(Seen::interactive).map(|s| s.label).collect() +} + +fn person(id: &str, name: &str) -> Contact { + Contact { + id: id.into(), + target: ShareTarget::User(id.into()), + name: name.into(), + email: Some(format!("{id}@example.com")), + avatar: None, + is_group: false, + } +} + +fn existing(id: &str, target: ShareTarget, permission: Permission) -> Share { + Share { id: id.into(), target, display: None, permission, url: None, note: None, created: None } +} + +fn ordinary() -> Vec { + vec![Capability::Files, Capability::Sharing, Capability::Contacts, Capability::ShareNotify, Capability::LinkShares] +} + +#[test] +fn renders_of_every_state_in_both_themes() { + let Ok(directory) = std::env::var("CRAFT_UI_RENDERS") else { + println!("set CRAFT_UI_RENDERS to a directory to write renders"); + return; + }; + let into = PathBuf::from(directory); + std::fs::create_dir_all(&into).expect("the render directory must be creatable"); + for theme in [Theme::Light, Theme::Dark] { + // ---- the account control ------------------------------------------- + let mut shot = Shot::new(theme, [320.0, 300.0]); + // A fresh menu is a signed-out one, which is the first state. + let mut draw = { + let mut menu = AccountMenu::new(); + move |ui: &mut egui::Ui| menu.show(ui) + }; + let output = shot.frame(Vec::new(), &mut draw); + shot.save(&into, "account-signed-out", theme, &output); + + for (name, linked) in [("account-no-storage", false), ("account-linked", true)] { + let mut shot = Shot::new(theme, [320.0, 300.0]); + let mut draw = { + let mut menu = AccountMenu::new(); + menu.set(vec![ + Account { + id: "work".into(), + display: "Will Dunn".into(), + email: Some("will@example.com".into()), + service: "collabcraft.example.com".into(), + linked, + }, + Account { + id: "personal".into(), + display: "Will at home".into(), + email: Some("will@example.net".into()), + service: "cloud.example.net".into(), + linked: true, + }, + ]); + move |ui: &mut egui::Ui| menu.show(ui) + }; + // The menu is behind the badge, so it takes a press to show. + shot.click("Account, Will Dunn", &mut draw); + let output = shot.frame(Vec::new(), &mut draw); + shot.save(&into, name, theme, &output); + } + + // ---- who else is here ---------------------------------------------- + let mut shot = Shot::new(theme, [420.0, 80.0]); + let mut bar = PresenceBar::new(); + bar.set(vec![ + Peer::new("s1", "Ann Reed").at("editing B4"), + Peer::new("s2", "Bob Vine").at("editing D12"), + Peer::new("s3", "Cal Nye"), + Peer::new("s4", "Dee Shaw"), + Peer::new("s5", "Eve Marsh"), + Peer::new("s6", "Fay Orr"), + ]); + let mut draw = move |ui: &mut egui::Ui| { + ui.add_space(24.0); + bar.show(ui); + }; + let output = shot.frame(Vec::new(), &mut draw); + shot.save(&into, "presence", theme, &output); + + // ---- the share dialog ---------------------------------------------- + let cases: Vec<(&str, Vec, Vec, &str)> = vec![ + ("dialog-fresh", ordinary(), Vec::new(), DOCUMENT), + ( + "dialog-who-has-access", + ordinary(), + vec![ + existing("s1", ShareTarget::User("ann".into()), Permission::Edit), + existing("s2", ShareTarget::Group("finance".into()), Permission::View), + ], + DOCUMENT, + ), + ("dialog-no-link-shares", vec![Capability::Sharing, Capability::Contacts], Vec::new(), DOCUMENT), + ("dialog-unsaved", ordinary(), Vec::new(), ""), + ]; + + for (name, capabilities, access, id) in cases { + let mut shot = Shot::new(theme, [620.0, 560.0]); + let fake = Fake { capabilities, access, parked: Arc::default() }; + let mut dialog = ShareDialog::new(); + dialog.connect(fake.clone()); + let held = Rc::new(RefCell::new(dialog)); + let mut draw = { + let held = Rc::clone(&held); + move |ui: &mut egui::Ui| held.borrow_mut().show_in(ui) + }; + // One frame asks what the provider can do, the next reads the answer. + shot.frame(Vec::new(), &mut draw); + shot.frame(Vec::new(), &mut draw); + held.borrow_mut().open(id.to_owned(), "Budget 2026"); + shot.frame(Vec::new(), &mut draw); + let output = shot.frame(Vec::new(), &mut draw); + shot.save(&into, name, theme, &output); + } + + // ---- recipients picked, then one of them refused ------------------- + let fake = Fake { capabilities: ordinary(), access: Vec::new(), parked: Arc::default() }; + let mut dialog = ShareDialog::new(); + dialog.connect(fake.clone()); + let held = Rc::new(RefCell::new(dialog)); + let mut draw = { + let held = Rc::clone(&held); + move |ui: &mut egui::Ui| held.borrow_mut().show_in(ui) + }; + let mut shot = Shot::new(theme, [620.0, 560.0]); + // One frame asks what the provider can do, the next reads the answer. + // Opening before that answer arrives does nothing, which is the point + // of a control that refuses to appear when it cannot work. + shot.frame(Vec::new(), &mut draw); + shot.frame(Vec::new(), &mut draw); + held.borrow_mut().open(DOCUMENT.to_owned(), "Budget 2026"); + shot.frame(Vec::new(), &mut draw); + shot.typing = true; + shot.frame(vec![Event::Text("an".to_owned())], &mut draw); + shot.time += 0.25; + shot.frame(Vec::new(), &mut draw); + fake.answer(Answer::Lookup(vec![person("ann", "Ann Reed")])); + shot.frame(Vec::new(), &mut draw); + shot.click("Ann Reed", &mut draw); + shot.typing = false; + let output = shot.frame(Vec::new(), &mut draw); + shot.save(&into, "dialog-recipients", theme, &output); + + shot.click("Send", &mut draw); + fake.answer(Answer::Granted { + shared: vec![existing("s1", ShareTarget::User("ann".into()), Permission::View)], + failed: vec![Failure { + target: ShareTarget::User("bob".into()), + code: "invalid_address".into(), + detail: "bob@example.con was rejected".into(), + }], + }); + let output = shot.frame(Vec::new(), &mut draw); + shot.save(&into, "dialog-partial-failure", theme, &output); + } +} diff --git a/crates/cloud-ui/tests/share_dialog.rs b/crates/cloud-ui/tests/share_dialog.rs new file mode 100644 index 000000000..4b43bca6e --- /dev/null +++ b/crates/cloud-ui/tests/share_dialog.rs @@ -0,0 +1,589 @@ +//! Gated on the `share` feature, which is off by default. +#![cfg(feature = "share")] + +//! The share dialog driven through its real widgets, offscreen. +//! +//! Every assertion here reads the accessibility tree the dialog actually +//! produced, or the requests it actually sent, rather than its private state. +//! No window is opened, no GPU is touched and no server is contacted: the +//! backend is a fake that parks each request until a test answers it, which is +//! also how answers are made to arrive late or in the wrong order. + +use std::sync::{Arc, Mutex}; + +use craft_cloud::{Capability, Contact, Permission, Share, ShareTarget}; +use craft_cloud_ui::share::{Answer, Failure, Replier, Request, ShareBackend, ShareDialog}; +use egui::{Context, Event, FullOutput, Modifiers, PointerButton, Pos2, RawInput, Rect, accesskit, pos2, vec2}; + +const SCREEN: [f32; 2] = [620.0, 900.0]; +const DOCUMENT: &str = "files/Budget 2026.xlsx"; + +#[derive(Default)] +struct Log { + seen: Vec, + parked: Vec<(Request, Replier)>, +} + +/// A backend that answers what the dialog needs to get going and parks the +/// rest, so a test decides when each answer arrives. +#[derive(Clone)] +struct Fake { + log: Arc>, + capabilities: Vec, + access: Vec, +} + +impl Fake { + fn new(capabilities: Vec, access: Vec) -> Fake { + Fake { log: Arc::new(Mutex::new(Log::default())), capabilities, access } + } + + fn seen(&self) -> Vec { + self.log.lock().map(|log| log.seen.clone()).unwrap_or_default() + } + + fn parked(&self) -> Vec { + self.log.lock().map(|log| log.parked.iter().map(|(r, _)| r.clone()).collect()).unwrap_or_default() + } + + /// Answer the request that has waited longest, which is the ordinary case. + fn answer(&self, answer: Answer) { + self.answer_nth(0, answer); + } + + /// Answer the request parked at `index`, oldest first, so a test can + /// deliver a late answer after a newer one. + fn answer_nth(&self, index: usize, answer: Answer) { + let Some((_, reply)) = self.take(index) else { panic!("nothing is waiting at {index}") }; + reply.answer(answer); + } + + /// Take one parked request back, to refuse it or inspect its contents. + fn take(&self, index: usize) -> Option<(Request, Replier)> { + self.log.lock().ok().and_then(|mut log| if index < log.parked.len() { Some(log.parked.remove(index)) } else { None }) + } +} + +impl ShareBackend for Fake { + fn submit(&self, request: Request, reply: Replier) { + let Ok(mut log) = self.log.lock() else { return }; + log.seen.push(request.clone()); + match &request { + Request::Capabilities => { + reply.answer(Answer::Capabilities { capabilities: self.capabilities.clone(), linked: true }); + } + Request::Access { .. } => reply.answer(Answer::Access(self.access.clone())), + _ => log.parked.push((request, reply)), + } + } +} + +struct Harness { + ctx: Context, + dialog: ShareDialog, + time: f64, + typing: bool, +} + +impl Harness { + fn new(capabilities: Vec, access: Vec) -> (Harness, Fake) { + let ctx = Context::default(); + ctx.enable_accesskit(); + ctx.all_styles_mut(|style| { + style.animation_time = 0.0; + style.visuals.text_cursor.blink = false; + }); + let fake = Fake::new(capabilities, access); + let mut dialog = ShareDialog::new(); + dialog.connect(fake.clone()); + let mut harness = Harness { ctx, dialog, time: 0.0, typing: false }; + // One frame asks what the provider can do, the next reads the answer. + harness.frame(Vec::new()); + harness.frame(Vec::new()); + (harness, fake) + } + + /// An ordinary deployment: files, sharing, contacts and mail. + fn everything() -> (Harness, Fake) { + Harness::new( + // Everything, which has to include ShareNotify. Notifying a + // recipient of a share is a separate ability from sending + // arbitrary mail, and the box is gated on the former. + vec![Capability::Files, Capability::Sharing, Capability::Contacts, Capability::Mail, Capability::ShareNotify], + Vec::new(), + ) + } + + fn frame(&mut self, events: Vec) -> FullOutput { + self.time += 1.0 / 60.0; + let raw = RawInput { + screen_rect: Some(Rect::from_min_size(Pos2::ZERO, vec2(SCREEN[0], SCREEN[1]))), + time: Some(self.time), + events, + ..Default::default() + }; + let ctx = self.ctx.clone(); + if self.typing { + // Keeping the recipient field focused is what a user holding the + // caret there does; nothing else in the dialog wants focus. + ctx.memory_mut(|m| m.request_focus(ShareDialog::query_field_id())); + } + let dialog = &mut self.dialog; + let mut output = ctx.run_ui(raw, |ui| dialog.show_in(ui)); + output.textures_delta.clear(); + output + } + + /// Let the clock run, for the debounce. + fn wait(&mut self, seconds: f64) -> FullOutput { + self.time += seconds; + self.frame(Vec::new()) + } + + fn open(&mut self) { + self.dialog.open(DOCUMENT, "Budget 2026.xlsx"); + assert!(self.dialog.is_open(), "the dialog should have opened"); + self.frame(Vec::new()); + } + + /// Type into the recipient field, then let the debounce elapse. + fn type_and_settle(&mut self, text: &str) { + self.typing = true; + self.frame(vec![Event::Text(text.to_owned())]); + self.wait(0.25); + } + + fn click(&mut self, label: &str) { + let output = self.frame(Vec::new()); + let Some(at) = control(&output, label) else { + panic!("nothing to click labelled {label:?}; the controls on screen are {:?}", controls(&output)) + }; + self.frame(vec![Event::PointerMoved(at)]); + self.frame(vec![press(at, true)]); + self.frame(vec![press(at, false)]); + self.frame(Vec::new()); + } +} + +fn press(at: Pos2, pressed: bool) -> Event { + Event::PointerButton { pos: at, button: PointerButton::Primary, pressed, modifiers: Modifiers::NONE } +} + +fn key(key: egui::Key) -> Event { + Event::Key { key, physical_key: None, pressed: true, repeat: false, modifiers: Modifiers::NONE } +} + +/// One widget as the accessibility tree reported it. +struct Seen { + role: accesskit::Role, + label: String, + bounds: Option, + disabled: bool, +} + +impl Seen { + /// Something a pointer can act on, as opposed to a piece of text. + fn interactive(&self) -> bool { + matches!(self.role, accesskit::Role::Button | accesskit::Role::RadioButton | accesskit::Role::CheckBox) + } + + fn at(&self) -> Option { + self.bounds.map(|b| pos2(((b.x0 + b.x1) / 2.0) as f32, ((b.y0 + b.y1) / 2.0) as f32)) + } +} + +fn seen(output: &FullOutput) -> Vec { + let Some(tree) = output.platform_output.accesskit_update.as_ref() else { return Vec::new() }; + tree.nodes + .iter() + .filter_map(|(_, node)| { + // egui puts a plain label's text in the accessibility value and a + // control's text in the label, so both are text on screen. + node.label().or_else(|| node.value()).map(|text| Seen { + role: node.role(), + label: text.to_owned(), + bounds: node.bounds(), + disabled: node.is_disabled(), + }) + }) + .collect() +} + +/// Where to click the control carrying this exact label. +fn control(output: &FullOutput, label: &str) -> Option { + seen(output).iter().find(|s| s.interactive() && !s.disabled && s.label == label).and_then(Seen::at) +} + +fn controls(output: &FullOutput) -> Vec { + seen(output).into_iter().filter(Seen::interactive).map(|s| s.label).collect() +} + +/// The buttons alone, which is what a chip and a match row are. +fn buttons(output: &FullOutput) -> Vec { + seen(output).into_iter().filter(|s| s.role == accesskit::Role::Button).map(|s| s.label).collect() +} + +/// Every piece of text on screen, for asserting what the user was told. +fn text(output: &FullOutput) -> Vec { + seen(output).into_iter().map(|s| s.label).collect() +} + +/// The primary action, taken from the defaults the dialog actually draws. +/// A literal here drifts the moment the wording changes. +const SEND: &str = "Send"; + +/// The permission dropdown, chevron included. It is a menu, not a toggle. +const PERMISSION: &str = "View"; + +fn says(output: &FullOutput, fragment: &str) -> bool { + text(output).iter().any(|line| line.contains(fragment)) +} + +fn person(id: &str, name: &str) -> Contact { + Contact { + id: id.into(), + target: ShareTarget::User(id.into()), + name: name.into(), + email: Some(format!("{id}@example.com")), + avatar: None, + is_group: false, + } +} + +fn group(id: &str, name: &str) -> Contact { + Contact { id: id.into(), target: ShareTarget::Group(id.into()), name: name.into(), email: None, avatar: None, is_group: true } +} + +fn existing(id: &str, target: ShareTarget, permission: Permission) -> Share { + Share { id: id.into(), target, display: None, permission, url: None, note: None, created: None } +} + +fn lookup(found: Vec) -> Answer { + Answer::Lookup(found) +} + +// ---- the picker ----------------------------------------------------------- + +#[test] +fn typing_a_few_letters_offers_matches_and_picking_them_builds_chips() { + let (mut h, fake) = Harness::everything(); + h.open(); + + h.type_and_settle("an"); + h.frame(Vec::new()); + assert_eq!( + fake.parked(), + vec![Request::Lookup { query: "an".into(), limit: 8 }], + "one lookup for the whole burst of typing, not one per keystroke" + ); + + fake.answer(lookup(vec![person("ann", "Ann Reed"), person("andy", "Andy Shaw"), group("finance", "Finance")])); + let output = h.frame(Vec::new()); + for name in ["Ann Reed", "Andy Shaw", "Finance"] { + assert!(buttons(&output).iter().any(|b| b == name), "{name} should be offered; saw {:?}", buttons(&output)); + } + + // Three recipients, picked one after another. Each lands as a chip whose + // whole body is the control that takes it back again. + h.click("Ann Reed"); + h.type_and_settle("an"); + fake.answer(lookup(vec![person("andy", "Andy Shaw")])); + h.frame(Vec::new()); + h.click("Andy Shaw"); + h.type_and_settle("fin"); + fake.answer(lookup(vec![group("finance", "Finance")])); + h.frame(Vec::new()); + h.click("Finance"); + + let output = h.frame(Vec::new()); + for name in ["Remove Ann Reed", "Remove Andy Shaw", "Remove Finance"] { + assert!(buttons(&output).iter().any(|b| b == name), "{name} should be a chip; saw {:?}", buttons(&output)); + } +} + +#[test] +fn a_chip_takes_one_recipient_back_and_leaves_the_others() { + let (mut h, fake) = Harness::everything(); + h.open(); + for (query, found) in [("an", person("ann", "Ann Reed")), ("bo", person("bob", "Bob Vine")), ("ca", person("cal", "Cal Nye"))] { + h.type_and_settle(query); + fake.answer(lookup(vec![found.clone()])); + h.frame(Vec::new()); + h.click(&found.name); + } + h.typing = false; + + h.click("Remove Bob Vine"); + let output = h.frame(Vec::new()); + assert!(buttons(&output).iter().any(|b| b == "Remove Ann Reed")); + assert!(buttons(&output).iter().any(|b| b == "Remove Cal Nye")); + assert!(!buttons(&output).iter().any(|b| b == "Remove Bob Vine"), "the removed chip is gone; saw {:?}", buttons(&output)); + + // And the share that follows carries the two that are left. + h.click(SEND); + let parked = fake.parked(); + let Some(Request::Grant(grant)) = parked.first() else { panic!("expected a share, saw {parked:?}") }; + assert_eq!(grant.targets, vec![ShareTarget::User("ann".into()), ShareTarget::User("cal".into())]); +} + +#[test] +fn an_answer_the_user_has_typed_past_never_reaches_the_list() { + let (mut h, fake) = Harness::everything(); + h.open(); + + // Two bursts of typing, so two lookups are outstanding at once. + h.type_and_settle("an"); + h.frame(Vec::new()); + h.type_and_settle("ann"); + h.frame(Vec::new()); + assert_eq!(fake.parked().len(), 2); + + // The newer one answers first and the older one arrives late, which is + // what a service under load does. + fake.answer_nth(1, lookup(vec![person("ann", "Ann Reed")])); + h.frame(Vec::new()); + fake.answer_nth(0, lookup(vec![person("andy", "Andy Shaw"), person("anna", "Anna Beck")])); + let output = h.frame(Vec::new()); + + assert!(buttons(&output).iter().any(|b| b == "Ann Reed"), "the current answer stays"); + assert!(!says(&output, "Andy Shaw"), "the stale answer must not flicker in"); + assert!(!says(&output, "Anna Beck")); +} + +#[test] +fn one_letter_is_not_worth_asking_about() { + let (mut h, fake) = Harness::everything(); + h.open(); + h.type_and_settle("a"); + h.frame(Vec::new()); + assert!(fake.parked().is_empty(), "a single letter matches most of an address book"); + + h.frame(vec![Event::Text("n".to_owned())]); + h.wait(0.25); + h.frame(Vec::new()); + assert_eq!(fake.parked(), vec![Request::Lookup { query: "an".into(), limit: 8 }]); +} + +#[test] +fn nothing_is_asked_until_the_typing_stops() { + let (mut h, fake) = Harness::everything(); + h.open(); + h.typing = true; + // Five keystrokes inside the debounce window. + for letter in ["a", "n", "n", "i", "e"] { + h.frame(vec![Event::Text(letter.to_owned())]); + h.wait(0.03); + } + assert!(fake.parked().is_empty(), "nothing asked while the user is still typing"); + + h.wait(0.25); + h.frame(Vec::new()); + assert_eq!(fake.parked(), vec![Request::Lookup { query: "annie".into(), limit: 8 }], "one question for the whole word"); +} + +// ---- what a share says ---------------------------------------------------- + +#[test] +fn sharing_with_five_where_one_address_is_wrong_names_the_one_that_failed() { + let (mut h, fake) = Harness::everything(); + h.open(); + for (query, found) in [("an", person("ann", "Ann Reed")), ("bo", person("bob", "Bob Vine"))] { + h.type_and_settle(query); + fake.answer(lookup(vec![found.clone()])); + h.frame(Vec::new()); + h.click(&found.name); + } + h.typing = false; + h.click(SEND); + + fake.answer(Answer::Granted { + shared: vec![existing("s1", ShareTarget::User("ann".into()), Permission::View)], + failed: vec![Failure { + target: ShareTarget::User("bob".into()), + code: "invalid_address".into(), + detail: "bob@example.con was rejected".into(), + }], + }); + let output = h.frame(Vec::new()); + + assert!(says(&output, "Shared with"), "the ones that went through are named"); + assert!(says(&output, "ann")); + assert!(says(&output, "Not shared with"), "and so is the one that did not"); + assert!(says(&output, "bob@example.con was rejected"), "with the reason, not a count; saw {:?}", text(&output)); + + // The failed recipient stays in the picker so a correction is one edit. + assert!(buttons(&output).iter().any(|b| b == "Remove Bob Vine")); + assert!(!buttons(&output).iter().any(|b| b == "Remove Ann Reed"), "the one that worked has left"); +} + +#[test] +fn a_refusal_that_stopped_everything_is_shown_as_itself() { + let (mut h, fake) = Harness::everything(); + h.open(); + h.type_and_settle("an"); + fake.answer(lookup(vec![person("ann", "Ann Reed")])); + h.frame(Vec::new()); + h.click("Ann Reed"); + h.typing = false; + h.click(SEND); + + let Some((_, reply)) = fake.take(0) else { panic!("expected a share in flight") }; + reply.refuse("sign in again"); + let output = h.frame(Vec::new()); + + assert!(says(&output, "sign in again")); + assert!(!says(&output, "Not shared with"), "a refusal is not a per-recipient failure"); + assert!(control(&output, SEND).is_some(), "the button comes back"); +} + +#[test] +fn a_note_and_a_permission_travel_with_the_share() { + let (mut h, fake) = Harness::everything(); + h.open(); + h.type_and_settle("an"); + fake.answer(lookup(vec![person("ann", "Ann Reed")])); + h.frame(Vec::new()); + h.click("Ann Reed"); + h.typing = false; + // The permission is a menu now, so it takes opening before choosing. + h.click(PERMISSION); + h.click("Edit"); + h.click(SEND); + + let parked = fake.parked(); + let Some(Request::Grant(grant)) = parked.first() else { panic!("expected a share, saw {parked:?}") }; + assert_eq!(grant.permission, Permission::Edit); + assert_eq!(grant.id, DOCUMENT, "the handle goes back untouched"); + assert!(grant.notify, "mail works here, and the box is ticked by default"); + assert_eq!(grant.note, None, "an empty note is no note"); +} + +#[test] +fn a_server_that_cannot_send_mail_is_never_promised_a_notification() { + let (mut h, fake) = Harness::new(vec![Capability::Sharing, Capability::Contacts], Vec::new()); + h.open(); + h.type_and_settle("an"); + fake.answer(lookup(vec![person("ann", "Ann Reed")])); + h.frame(Vec::new()); + h.click("Ann Reed"); + h.typing = false; + h.click(SEND); + + let parked = fake.parked(); + let Some(Request::Grant(grant)) = parked.first() else { panic!("expected a share, saw {parked:?}") }; + assert!(!grant.notify, "a checkbox for mail a server cannot send must not be honoured"); +} + +#[test] +fn a_server_without_contacts_asks_nobody_anything() { + let (mut h, fake) = Harness::new(vec![Capability::Sharing], Vec::new()); + h.open(); + h.type_and_settle("ann"); + h.frame(Vec::new()); + assert!(fake.parked().is_empty(), "there is no address book to search"); +} + +// ---- who already has access ---------------------------------------------- + +#[test] +fn who_has_access_is_listed_and_one_can_be_withdrawn() { + let (mut h, fake) = Harness::new( + vec![Capability::Sharing, Capability::Contacts, Capability::Mail], + vec![ + existing("s1", ShareTarget::User("ann".into()), Permission::Edit), + existing("s2", ShareTarget::Group("finance".into()), Permission::View), + ], + ); + h.open(); + let output = h.frame(Vec::new()); + assert!(says(&output, "Who has access")); + assert!(says(&output, "ann")); + assert!(says(&output, "finance (group)")); + assert_eq!(buttons(&output).iter().filter(|b| *b == "Withdraw").count(), 2); + + h.click("Withdraw"); + assert!(fake.seen().iter().any(|r| matches!(r, Request::Withdraw { share_id } if share_id == "s1" || share_id == "s2"))); + + // It stays on the list until the server agrees it is gone. + let output = h.frame(Vec::new()); + assert!(says(&output, "Withdrawing…")); + let Some((Request::Withdraw { share_id }, reply)) = fake.take(0) else { panic!("expected a withdrawal in flight") }; + reply.answer(Answer::Withdrawn { share_id: share_id.clone() }); + let output = h.frame(Vec::new()); + assert_eq!(buttons(&output).iter().filter(|b| *b == "Withdraw").count(), 1, "one left"); +} + +#[test] +fn a_document_nobody_has_been_given_says_so() { + let (mut h, _fake) = Harness::everything(); + h.open(); + let output = h.frame(Vec::new()); + assert!(says(&output, "Nobody else yet")); +} + +// ---- what the dialog refuses to offer ------------------------------------- + +#[test] +fn a_server_without_sharing_draws_no_dialog_at_all() { + let (mut h, fake) = Harness::new(vec![Capability::Files, Capability::Contacts], Vec::new()); + assert!(!h.dialog.available()); + h.dialog.open(DOCUMENT, "Budget 2026.xlsx"); + assert!(!h.dialog.is_open(), "a feature the provider lacks is hidden, not offered"); + let output = h.frame(Vec::new()); + assert!(buttons(&output).is_empty(), "nothing to click; saw {:?}", buttons(&output)); + assert!(!fake.seen().iter().any(|r| matches!(r, Request::Access { .. })), "and nothing was asked about the document"); +} + +#[test] +fn an_unsaved_document_is_told_to_save_rather_than_refused_by_the_server() { + let (mut h, fake) = Harness::everything(); + h.dialog.open("", "Book1"); + let output = h.frame(Vec::new()); + assert!(says(&output, "Save this document somewhere to share it.")); + assert!(control(&output, SEND).is_none(), "there is nothing to share yet"); + assert!(!fake.seen().iter().any(|r| matches!(r, Request::Access { .. }))); +} + +#[test] +fn closing_puts_the_dialog_away() { + let (mut h, _fake) = Harness::everything(); + h.open(); + h.click("Close"); + assert!(!h.dialog.is_open()); + let output = h.frame(Vec::new()); + assert!(buttons(&output).is_empty()); +} + +#[test] +fn a_typed_address_says_how_to_add_it_and_adding_it_works() { + let (mut h, fake) = Harness::everything(); + h.open(); + h.type_and_settle("outside@example.com"); + fake.answer(lookup(Vec::new())); + let output = h.frame(Vec::new()); + assert!(says(&output, "Press Return to share with this address"), "saw {:?}", text(&output)); + assert!(!says(&output, "No matches"), "an address that matched nobody is still a recipient"); + + // Return takes it, and the share carries it as an address. + h.frame(vec![key(egui::Key::Enter)]); + h.frame(Vec::new()); + h.typing = false; + let output = h.frame(Vec::new()); + assert!(buttons(&output).iter().any(|b| b == "Remove outside@example.com"), "saw {:?}", buttons(&output)); + + h.click(SEND); + let parked = fake.parked(); + let Some(Request::Grant(grant)) = parked.first() else { panic!("expected a share, saw {parked:?}") }; + assert_eq!(grant.targets, vec![ShareTarget::Email("outside@example.com".into())]); +} + +#[test] +fn a_name_that_matched_nobody_is_not_offered_as_an_address() { + let (mut h, fake) = Harness::everything(); + h.open(); + h.type_and_settle("nobody"); + fake.answer(lookup(Vec::new())); + let output = h.frame(Vec::new()); + assert!(says(&output, "No matches")); + assert!(!says(&output, "Press Return")); +} diff --git a/crates/cloud/Cargo.toml b/crates/cloud/Cargo.toml new file mode 100644 index 000000000..055feff39 --- /dev/null +++ b/crates/cloud/Cargo.toml @@ -0,0 +1,15 @@ +[package] +name = "craft-cloud" +version.workspace = true +edition.workspace = true +license.workspace = true +repository.workspace = true +rust-version.workspace = true +description = "What a cloud provider offers the Craft apps: files, sharing, contacts, notifications and mail as contracts, with no vendor and no IO" + +[lints] +workspace = true + +[dependencies] +serde = { workspace = true } +thiserror = { workspace = true } diff --git a/crates/cloud/src/error.rs b/crates/cloud/src/error.rs new file mode 100644 index 000000000..ede71ac0c --- /dev/null +++ b/crates/cloud/src/error.rs @@ -0,0 +1,68 @@ +//! One error type for every contract. +//! +//! The cases are the ones a caller acts on differently. A UI shows a different +//! thing for "you may not" than for "the server is unreachable", and a save +//! retries on a conflict where it would not on a refusal. + +use thiserror::Error; + +#[derive(Debug, Error)] +pub enum Error { + /// The provider could not be reached. Worth retrying. + #[error("the provider could not be reached: {0}")] + Unreachable(String), + + /// The credential was rejected. The user has to sign in again. + #[error("the provider rejected the credential")] + Unauthenticated, + + /// Authenticated, and not allowed to do this. Signing in again will not + /// help, so a UI must not offer it. + #[error("not permitted: {0}")] + Forbidden(String), + + /// No such document, folder or share. + #[error("{what} not found: {id}")] + NotFound { what: &'static str, id: String }, + + /// The document changed since the caller last read it. A save that would + /// have overwritten somebody else's work lands here. + #[error("{0} changed since you opened it")] + Conflict(String), + + /// The provider does not offer this at all. + /// + /// Distinct from [`Error::Forbidden`]: there is nothing to grant. A UI + /// hides the feature rather than explaining it. + #[error("this provider does not support {0}")] + Unsupported(&'static str), + + /// The answer did not match the protocol. + #[error("malformed {what}: {detail}")] + Malformed { what: &'static str, detail: String }, + + /// A name or path could not be used safely. Carried, never panicked. + #[error("invalid {what}: {detail}")] + Invalid { what: &'static str, detail: String }, +} + +impl Error { + pub fn not_found(what: &'static str, id: impl Into) -> Error { + Error::NotFound { what, id: id.into() } + } + + pub fn malformed(what: &'static str, detail: impl Into) -> Error { + Error::Malformed { what, detail: detail.into() } + } + + pub fn invalid(what: &'static str, detail: impl Into) -> Error { + Error::Invalid { what, detail: detail.into() } + } + + /// Whether trying again could succeed without the user doing anything. + pub fn is_transient(&self) -> bool { + matches!(self, Error::Unreachable(_)) + } +} + +pub type Result = std::result::Result; diff --git a/crates/cloud/src/lib.rs b/crates/cloud/src/lib.rs new file mode 100644 index 000000000..1f4fe0930 --- /dev/null +++ b/crates/cloud/src/lib.rs @@ -0,0 +1,189 @@ +//! What a cloud provider has to offer the Craft apps, and nothing about who +//! provides it. +//! +//! Every capability here is an RFC or an ordinary HTTP API that many systems +//! implement. Files are WebDAV. Contacts are CardDAV. Calendars are CalDAV. +//! Sharing and notification are the only genuinely vendor-shaped parts, and +//! they are small. So there is no reason for an app to know which server it is +//! talking to, and no reason to write the same logic again for the next one. +//! +//! Nothing in this crate opens a socket. Each trait is implemented by a +//! provider crate that brings its own transport, which keeps this testable +//! with no server and keeps the contracts honest about what they need. +//! +//! No type here names a vendor. If a field only makes sense for one product, +//! it belongs in that provider's crate. +//! +//! Nothing here says where an implementation runs. A local adapter may +//! implement these traits against a provider directly, and an application may +//! consume them that way. The contracts do not care. +//! +//! CollabCraft chooses otherwise for its own apps. They reach one service, and +//! that service is the single place a provider is configured, a credential is +//! held and a permission is decided. A desktop binary carrying a provider +//! credential leaks one the moment somebody copies the file, which is what +//! that arrangement exists to prevent. It is a deployment policy, and this +//! crate imposes it on nobody. + +#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)] + +mod error; +mod types; + +pub use error::{Error, Result}; +pub use types::{ + Capability, Contact, Conversation, Entry, EntryKind, Identity, MailMessage, Notification, Permission, Share, ShareOptions, ShareTarget, +}; + +/// Reading and writing documents. +/// +/// `list` and `shared_with_me` are separate because they answer different +/// questions. One is a folder's contents, the other is everything another +/// person has given this user access to, which has no single parent folder. +pub trait Files { + /// One folder's contents. An empty path means the user's root. + fn list(&self, path: &str) -> Result>; + + /// Everything shared with this user, wherever it lives. + /// + /// A provider with no concept of this returns an empty list rather than an + /// error, because "nobody has shared anything with you" and "this server + /// cannot tell you" look the same to a file picker. + fn shared_with_me(&self) -> Result>; + + /// One document's bytes. + fn read(&self, id: &str) -> Result>; + + /// A byte range of one document. + /// + /// Defaulted to a full [`read`](Self::read) and a slice, so providers that have no + /// ranged GET still satisfy the trait. A provider with real range support + /// overrides this. + fn read_range(&self, id: &str, offset: u64, length: u64) -> Result> { + let bytes = self.read(id)?; + let start = usize::try_from(offset).unwrap_or(usize::MAX); + if start >= bytes.len() { + return Ok(Vec::new()); + } + let take = usize::try_from(length).unwrap_or(usize::MAX); + let end = start.saturating_add(take).min(bytes.len()); + Ok(bytes[start..end].to_vec()) + } + + /// Replace one document's bytes. + /// + /// `if_match` carries the etag the caller last saw. A provider that + /// supports conditional writes uses it to refuse a save that would + /// overwrite somebody else's, returning [`Error::Conflict`]. Passing + /// `None` means "write regardless", which is what a Save As does. + fn write(&self, id: &str, bytes: &[u8], if_match: Option<&str>) -> Result; + + /// Create a document and return it. + fn create(&self, folder: &str, name: &str, bytes: &[u8]) -> Result; + + /// One document's metadata, without its bytes. + fn stat(&self, id: &str) -> Result; +} + +/// Giving other people access to a document. +/// +/// Persisting a share through the provider matters more than it looks. A share +/// recorded only by the caller would be invisible in the provider's own file +/// manager, so the two would disagree about who can open what. The provider +/// stays the authority. +pub trait Sharing { + /// Share a document. + /// + /// A link share has no recipient, so [`ShareTarget::Link`] is how a caller + /// asks for one. The returned [`Share::url`] is what to hand out. + fn share(&self, id: &str, with: &ShareTarget, permission: Permission, options: &ShareOptions) -> Result; + + /// Who currently has access. + fn shares(&self, id: &str) -> Result>; + + /// Withdraw one share. + fn unshare(&self, share_id: &str) -> Result<()>; +} + +/// Looking people up, for a share dialog's autocomplete. +/// +/// This is the only thing the share dialog needs, so it is the only thing the +/// contract exposes. A full address book API would be a bigger surface for no +/// gain. +pub trait Contacts { + /// People matching a partial name or address. + /// + /// `limit` exists because this runs on every keystroke. A provider is free + /// to return fewer. + fn search(&self, query: &str, limit: usize) -> Result>; +} + +/// Telling somebody something happened. +/// +/// Separate from [`Mail`] on purpose. An in-app notification is cheap, arrives +/// instantly and is read in context. An email is none of those and is the +/// right choice for somebody who is not currently in the app. A share usually +/// wants both. +pub trait Notifications { + fn notify(&self, user: &str, notification: &Notification) -> Result<()>; +} + +/// Sending mail as the provider. +pub trait Mail { + fn send(&self, message: &MailMessage) -> Result<()>; +} + +/// Who the caller is, according to the provider. +pub trait Accounts { + /// Resolve the signed-in user. + fn me(&self) -> Result; +} + +/// Working together on a document, through whatever the provider calls it. +/// +/// Defaulted throughout. A provider without the feature writes an empty +/// `impl` and reports [`Capability::Conversation`] as absent. The caller +/// then draws no control at all. +pub trait Conversations { + /// What this provider calls the feature. `None` where it has none. + /// + /// Separate from the capability on purpose. The name is a property of + /// the provider. Whether it is available is a property of the + /// instance, and an administrator decides that one. + fn conversation_name(&self) -> Option { + None + } + + /// Start a conversation about a document, or join the one already there. + /// + /// Two people pressing the same control have to arrive in the same + /// place, so this is expected to be idempotent for a given document. + /// + /// `id` is the provider's own handle and means nothing outside the + /// account it came from. A conversation is therefore keyed on the + /// provider, the account and the document together, and `self` carries + /// the first two. A document copied into another account is a different + /// document to its provider, so it gets a conversation of its own. + /// Nothing here can attach one account's thread to another's. + fn conversation(&self, _id: &str, _title: &str) -> Result { + Err(Error::Unsupported("conversations")) + } +} + +/// Everything one provider can do. +/// +/// A provider implements the capabilities it has and reports the rest as +/// absent, so a caller can hide a share button on a server with no sharing +/// rather than offering a feature that will fail. +pub trait Provider: Files + Sharing + Contacts + Notifications + Mail + Accounts + Conversations { + /// A stable identifier, such as `nextcloud`. Used in configuration and + /// logs, never shown to a user. + fn id(&self) -> &str; + + /// What this provider actually supports. + fn capabilities(&self) -> Vec; + + fn supports(&self, capability: Capability) -> bool { + self.capabilities().contains(&capability) + } +} diff --git a/crates/cloud/src/types.rs b/crates/cloud/src/types.rs new file mode 100644 index 000000000..ab8c005a1 --- /dev/null +++ b/crates/cloud/src/types.rs @@ -0,0 +1,216 @@ +//! The data the contracts pass around. +//! +//! Every type here is plain and vendor-neutral. A field that only means +//! something to one product belongs in that provider's crate. + +use serde::{Deserialize, Serialize}; + +/// What a provider can do. +/// +/// Reported rather than assumed, so a caller hides a share button on a +/// server without sharing instead of offering a feature that fails on use. +#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)] +#[serde(rename_all = "snake_case")] +pub enum Capability { + Files, + SharedWithMe, + Sharing, + Contacts, + Notifications, + Mail, + /// Conditional writes, so a save can refuse to clobber a newer version. + Etags, + /// Public links. Absent on a server that forbids them, and the dialog then + /// offers no Copy link rather than a button that fails. + LinkShares, + /// A key on a public link. This is what most places mean when they talk + /// about sharing with somebody who has no account. + LinkPassword, + /// The server requires that key, so a link cannot be made without one. + LinkPasswordRequired, + /// An expiry date on a share. + ShareExpiry, + /// The provider can tell a recipient that something was shared with them. + /// + /// Distinct from [`Capability::Mail`], which is about sending arbitrary + /// mail. A provider commonly has this and not that: it will notify the + /// person a share names without offering any way to send mail in general. + ShareNotify, + /// A conversation about a document, such as a call or a chat room. + /// + /// Every provider that has this calls it something else, so the name + /// comes from [`crate::Conversations::conversation_name`]. Reported + /// separately from that name: a provider knows what it would call the + /// feature whether or not an administrator installed it. + Conversation, +} + +/// A file or folder. +#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)] +pub struct Entry { + /// An opaque handle for reading, writing and sharing this entry. + /// + /// Only the provider that issued it may interpret it. A caller passes it + /// back and never parses it. + pub id: String, + /// The stable identity used for a collaboration room. + /// + /// Separate from `id` on purpose. A provider's read and write handle is + /// often a path, and a path changes when somebody renames or moves the + /// file. A room keyed on that would silently split in two mid-session, + /// with each half seeing only its own edits. This one survives a rename. + pub room: String, + /// What to show the user. + pub name: String, + /// Where it sits, for a breadcrumb. Never a handle. + pub path: String, + pub kind: EntryKind, + /// Bytes, absent for a folder. + pub size: Option, + /// RFC 3339. Absent when the provider does not say. + pub modified: Option, + /// For matching a document to the app that opens it. + pub mime: Option, + /// The version the caller last saw, for a conditional write. + pub etag: Option, + /// Whether this user may change it. A read-only share still lists. + pub writable: bool, + /// Who shared it, when it came from somebody else. + pub shared_by: Option, +} + +#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)] +#[serde(rename_all = "snake_case")] +pub enum EntryKind { + File, + Folder, +} + +/// A person, as a share dialog needs them. +#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)] +pub struct Contact { + /// What the provider wants back when sharing with this person. + pub id: String, + /// How to share with them, decided by the provider and never guessed. + /// + /// The distinction is not cosmetic. A contact with an account is a user + /// share. One known only by address is an email share. Sharing an address + /// as though it were a user id fails with "not found", because no such + /// user exists, and nothing in `id` alone says which case this is. + pub target: ShareTarget, + /// What to show. A display name where there is one. + pub name: String, + pub email: Option, + /// An avatar, as a URL the client may fetch. Never image bytes: a search + /// returning ten people would otherwise carry ten pictures nobody asked + /// for yet. + pub avatar: Option, + /// A group rather than a person. Shown differently and shared differently. + pub is_group: bool, +} + +/// Who to share with. +#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)] +#[serde(rename_all = "snake_case", tag = "kind", content = "id")] +pub enum ShareTarget { + User(String), + Group(String), + /// Somebody with no account, reached by address. + Email(String), + /// Anybody holding the link. + Link, +} + +/// What a share allows. +/// +/// Deliberately coarse. Providers disagree on the fine detail, and a dialog +/// offering a distinction the server cannot keep is worse than one that does +/// not. +#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)] +#[serde(rename_all = "snake_case")] +pub enum Permission { + /// Open and read. No edits reach the document. + View, + /// Open and edit. + Edit, +} + +/// Everything optional about a share. +/// +/// A struct rather than more positional arguments. The list grew past the +/// point where a call site reads correctly, and a provider that cannot honour +/// one of these needs to see which it was given. +#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize)] +pub struct ShareOptions { + /// Shown to the recipient. + pub note: Option, + /// Send mail where the provider can. + pub notify: bool, + /// A key the recipient must present. Only meaningful for a link, and + /// refused by a server that does not allow one. + pub password: Option, + /// `YYYY-MM-DD`. After this the share stops working. + pub expires: Option, +} + +/// Where to go to work together on a document. +#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)] +pub struct Conversation { + /// Where to join. Handed to a browser, or to the provider's own app. + pub url: String, + /// What the provider calls the feature, for the control's wording. A + /// menu item reading "Work together in Talk" is built from this. + pub name: String, +} + +/// A share that exists. +#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)] +pub struct Share { + pub id: String, + pub target: ShareTarget, + /// What to call the recipient, where the provider says. + /// + /// A share carries the handle the server wants back, which for a user is + /// an account id. People are not known to each other by account id. A + /// provider that knows the difference says so here. + pub display: Option, + pub permission: Permission, + /// Present for a link share, absent otherwise. + pub url: Option, + pub note: Option, + /// RFC 3339. + pub created: Option, +} + +/// Something worth telling a user about, in the app. +#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)] +pub struct Notification { + /// A short machine-readable kind, such as `document_shared`. Lets a client + /// decide how to render without parsing prose. + pub kind: String, + pub subject: String, + pub body: Option, + /// Where to go when it is clicked. + pub link: Option, +} + +/// An email to send. +#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)] +pub struct MailMessage { + pub to: Vec, + pub subject: String, + pub body: String, + /// Whether `body` is HTML. Plain text otherwise. + pub html: bool, +} + +/// The signed-in user, as the provider sees them. +#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)] +pub struct Identity { + /// The provider's identifier for this account. + pub id: String, + /// What to show. Never an identity: two people can share a display name. + pub display: String, + pub email: Option, + pub avatar: Option, +} diff --git a/crates/cms/README.md b/crates/cms/README.md index b3a178704..43b9f26da 100644 --- a/crates/cms/README.md +++ b/crates/cms/README.md @@ -81,6 +81,12 @@ Buffers are checked once per call, before any pixel is written. the exact and float paths compare each pixel with white; all other colours are left as the profiles give them. With a profile whose white falls between its nodes (`coated-cmyk`: 0.4 % C), the last step to white is that much larger than its neighbours. +* Black preservation (opt-in, `BlackPreserving`): for CMYK → CMYK, a colour with exactly zero + C, M and Y comes out as exactly `(0, 0, 0, K')`, where `K'` is the destination black whose + K-only L* equals the source's (both K ramps sampled at 1024 points when the transform is + built, with its intent and BPC). The test is exact zero, so an input with any chromatic ink + takes the ordinary path. Absolute colorimetric, non-CMYK profiles and K ramps that reverse at + one of the 1024 samples are refused (a reversal between samples is not detected). ## Built-in profiles (all CC0-1.0, generated by this crate) diff --git a/crates/cms/profiles/craft-coated-fogra39.icc b/crates/cms/profiles/craft-coated-fogra39.icc index 13590238e..1ef3cad1f 100644 Binary files a/crates/cms/profiles/craft-coated-fogra39.icc and b/crates/cms/profiles/craft-coated-fogra39.icc differ diff --git a/crates/cms/src/black.rs b/crates/cms/src/black.rs new file mode 100644 index 000000000..f80defeef --- /dev/null +++ b/crates/cms/src/black.rs @@ -0,0 +1,205 @@ +//! K-only black preservation for CMYK → CMYK transforms. +//! +//! A CMYK → CMYK transform goes through the three-component PCS, so black alone (C = M = Y = 0) +//! comes out as a four-ink mix. ISO 32000-2 §8.6.5.7 notes that this loses fidelity in the black +//! component. ICC defines no black preservation; this is a named policy the caller opts into. +//! +//! [`BlackPreserving`] converts like its [`Transform`], except that a colour with exactly zero +//! cyan, magenta and yellow becomes exactly `(0, 0, 0, K')`. `K'` is the destination black whose +//! K-only L* equals the source's, both measured to Lab with the transform's own intent and BPC +//! setting: both ramps are sampled once, at construction, and the destination ramp is inverted. +//! A source black darker than the destination's maximum black maps to K = 1. The test is exact zero, so the transform is discontinuous at C = M = Y = 0: an input +//! with any chromatic ink takes the ordinary path. + +use crate::transform::{Transform, TransformOptions}; +use crate::{Builtin, CmsError, ColorSpace, Intent, Profile, invalid_arg}; + +/// Samples along each K-only ramp. Linear interpolation between samples of a smooth ramp is far +/// below the 16-bit quantum. +const K_SAMPLES: usize = 1024; +/// Slack for the monotonicity checks (L* units, K units). +const MONOTONIC_EPS: f64 = 1e-6; + +/// A CMYK → CMYK transform that keeps black-only colours black-only. +#[derive(Debug)] +pub struct BlackPreserving { + transform: Transform, + /// Destination K for source K at `i / (K_SAMPLES - 1)`; `K_SAMPLES` values in `[0, 1]`. + curve: Vec, + /// Source K from which the source black is at least as dark as the destination's darkest: + /// mapped to exactly 1. Infinite when the destination's black is the darker. + saturate: f32, + /// The mapping at the 256 8-bit source codes, already quantised. + curve8: [u8; 256], +} + +impl BlackPreserving { + /// Transform from `src` to `dst` with black preservation. + /// + /// Errors with [`CmsError::InvalidArgument`] when either profile is not CMYK or the intent is + /// absolute colorimetric (which reproduces the source's paper and black, so there is no + /// black to map), and with [`CmsError::Unsupported`] when a profile's K-only ramp is not + /// monotonic at its 1024 samples (black that gets lighter as K rises has no equal-lightness + /// inverse; a reversal between samples is not detected). Other errors + /// are those of [`Transform::with_options`]. + pub fn new(src: &Profile, dst: &Profile, opts: TransformOptions) -> Result { + if src.color_space != ColorSpace::Cmyk || dst.color_space != ColorSpace::Cmyk { + return Err(invalid_arg("black preservation needs CMYK source and destination profiles")); + } + if opts.intent == Intent::AbsoluteColorimetric { + return Err(invalid_arg("black preservation does not apply to absolute colorimetric")); + } + let transform = Transform::with_options(src, dst, opts)?; + let src_l = k_ramp_lightness(src, opts)?; + let dst_l = k_ramp_lightness(dst, opts)?; + let (curve, saturate) = k_curve(&src_l, &dst_l)?; + let mut curve8 = [0u8; 256]; + for (code, slot) in curve8.iter_mut().enumerate() { + *slot = quantise(map(&curve, saturate, code as f32 / 255.0), 255.0) as u8; + } + Ok(BlackPreserving { transform, curve, saturate, curve8 }) + } + + /// The ordinary transform, which every colour with chromatic ink goes through. Converting with + /// it directly does not preserve black. + pub fn transform(&self) -> &Transform { + &self.transform + } + + /// Destination K for a black-only source colour of `k` (clamped to `[0, 1]`). + pub fn map_k(&self, k: f32) -> f32 { + map(&self.curve, self.saturate, k) + } + + /// Exact evaluation of one colour; slices as in [`Transform::eval`]. + pub fn eval(&self, input: &[f32], out: &mut [f32]) -> Result<(), CmsError> { + self.transform.eval(input, out)?; + self.patch_one(input, out); + Ok(()) + } + + /// Lookup-table evaluation of one colour; slices as in [`Transform::eval`]. + pub fn eval_fast(&self, input: &[f32], out: &mut [f32]) -> Result<(), CmsError> { + self.transform.eval_fast(input, out)?; + self.patch_one(input, out); + Ok(()) + } + + /// Converts float pixels; layout and errors as in [`Transform::convert_f32`]. + pub fn convert_f32(&self, src: &[f32], src_stride: usize, dst: &mut [f32], dst_stride: usize, copy_extra: bool) -> Result<(), CmsError> { + self.transform.convert_f32(src, src_stride, dst, dst_stride, copy_extra)?; + for (s, d) in src.chunks_exact(src_stride).zip(dst.chunks_exact_mut(dst_stride)) { + self.patch_one(s, d); + } + Ok(()) + } + + /// Converts 8-bit pixels; layout and errors as in [`Transform::convert_u8`]. + pub fn convert_u8(&self, src: &[u8], src_stride: usize, dst: &mut [u8], dst_stride: usize, copy_extra: bool) -> Result<(), CmsError> { + self.transform.convert_u8(src, src_stride, dst, dst_stride, copy_extra)?; + for (s, d) in src.chunks_exact(src_stride).zip(dst.chunks_exact_mut(dst_stride)) { + if let ([0, 0, 0, k, ..], [c, m, y, kd, ..]) = (s, d) { + (*c, *m, *y) = (0, 0, 0); + *kd = self.curve8[usize::from(*k)]; + } + } + Ok(()) + } + + /// Converts 16-bit pixels; layout and errors as in [`Transform::convert_u16`]. + pub fn convert_u16(&self, src: &[u16], src_stride: usize, dst: &mut [u16], dst_stride: usize, copy_extra: bool) -> Result<(), CmsError> { + self.transform.convert_u16(src, src_stride, dst, dst_stride, copy_extra)?; + for (s, d) in src.chunks_exact(src_stride).zip(dst.chunks_exact_mut(dst_stride)) { + if let ([0, 0, 0, k, ..], [c, m, y, kd, ..]) = (s, d) { + (*c, *m, *y) = (0, 0, 0); + *kd = quantise(self.map_k(f32::from(*k) / 65535.0), 65535.0) as u16; + } + } + Ok(()) + } + + fn patch_one(&self, input: &[f32], out: &mut [f32]) { + if let ([0.0, 0.0, 0.0, k, ..], [c, m, y, kd, ..]) = (input, out) { + (*c, *m, *y) = (0.0, 0.0, 0.0); + *kd = self.map_k(*k); + } + } +} + +/// The sampled mapping from the source to the destination K-only ramp, and the source K at +/// which the destination's darkest black is reached (the `saturate` field). +fn k_curve(src_l: &[f64], dst_l: &[f64]) -> Result<(Vec, f32), CmsError> { + let curve: Vec = src_l.iter().map(|&l| invert(dst_l, l) as f32).collect(); + if !curve.windows(2).all(|w| f64::from(w[0]) - f64::from(w[1]) <= MONOTONIC_EPS) { + return Err(CmsError::Unsupported("black preservation: the K mapping is not monotonic".into())); + } + let saturate = match (src_l.last(), dst_l.last()) { + (Some(&s), Some(&d)) if s < d => invert(src_l, d) as f32, + _ => f32::INFINITY, + }; + Ok((curve, saturate)) +} + +/// L* of `p`'s K-only ramp at `K_SAMPLES` points, light to dark; refused when it is not +/// non-increasing. +fn k_ramp_lightness(p: &Profile, opts: TransformOptions) -> Result, CmsError> { + let to_lab = Transform::with_options(p, Builtin::LabD50.profile(), TransformOptions { precise_float: true, ..opts })?; + let mut ramp = Vec::with_capacity(K_SAMPLES); + let mut lab = [0.0f32; 3]; + for i in 0..K_SAMPLES { + let k = i as f32 / (K_SAMPLES - 1) as f32; + to_lab.eval(&[0.0, 0.0, 0.0, k], &mut lab)?; + ramp.push(f64::from(lab[0]) * 100.0); + } + if !ramp.iter().all(|l| l.is_finite()) || !ramp.windows(2).all(|w| w[1] - w[0] <= MONOTONIC_EPS) { + return Err(CmsError::Unsupported("black preservation: a K-only ramp is not monotonic".into())); + } + Ok(ramp) +} + +/// The K in `[0, 1]` at which the non-increasing `ramp` reaches `target`, clamped to its ends. +fn invert(ramp: &[f64], target: f64) -> f64 { + let (Some(&first), Some(&last)) = (ramp.first(), ramp.last()) else { return 0.0 }; + if ramp.len() < 2 || target >= first { + return 0.0; + } + if target <= last { + return 1.0; + } + // ramp[lo] > target >= ramp[hi] + let (mut lo, mut hi) = (0usize, ramp.len() - 1); + while hi - lo > 1 { + let mid = lo + (hi - lo) / 2; + if ramp.get(mid).is_some_and(|&v| v > target) { + lo = mid; + } else { + hi = mid; + } + } + let (a, b) = (ramp.get(lo).copied().unwrap_or(first), ramp.get(hi).copied().unwrap_or(last)); + let t = if a - b > MONOTONIC_EPS { (a - target) / (a - b) } else { 0.0 }; + (lo as f64 + t) / (ramp.len() - 1) as f64 +} + +/// Linear interpolation in `curve` (samples over `[0, 1]`) at `k`, clamped; 1 from `saturate`. +fn map(curve: &[f32], saturate: f32, k: f32) -> f32 { + let Some(&last) = curve.last() else { return 0.0 }; + let k = if k.is_nan() { 0.0 } else { k.clamp(0.0, 1.0) }; + if k >= saturate { + return 1.0; + } + let x = k * (curve.len() - 1) as f32; + let i = x.floor() as usize; + match (curve.get(i), curve.get(i + 1)) { + (Some(&a), Some(&b)) => a + (b - a) * (x - i as f32), + _ => last, + } +} + +fn quantise(v: f32, max: f32) -> f32 { + (v.clamp(0.0, 1.0) * max + 0.5).floor() +} + +#[cfg(test)] +#[path = "black_tests.rs"] +mod tests; diff --git a/crates/cms/src/black_tests.rs b/crates/cms/src/black_tests.rs new file mode 100644 index 000000000..8752cdaa2 --- /dev/null +++ b/crates/cms/src/black_tests.rs @@ -0,0 +1,149 @@ +use super::*; + +fn coated() -> &'static Profile { + Builtin::CoatedCmyk.profile() +} +fn fogra() -> &'static Profile { + Builtin::CoatedFogra39.profile() +} +fn opts() -> TransformOptions { + TransformOptions::default() +} + +/// L* of a CMYK colour under `p`, measured as the transform with `o` measures it. +fn lightness(p: &Profile, o: TransformOptions, cmyk: [f32; 4]) -> f32 { + let t = Transform::with_options(p, Builtin::LabD50.profile(), o).unwrap(); + let mut lab = [0.0f32; 3]; + t.eval(&cmyk, &mut lab).unwrap(); + lab[0] * 100.0 +} + +#[test] +fn the_plain_transform_turns_black_into_four_inks() { + // What the policy is for: without it, black alone gains chromatic ink across presses. + let t = Transform::with_options(coated(), fogra(), opts()).unwrap(); + let mut out = [0.0f32; 4]; + t.eval(&[0.0, 0.0, 0.0, 0.5], &mut out).unwrap(); + assert!(out[..3].iter().any(|v| *v > 0.01), "{out:?}"); +} + +#[test] +fn black_only_stays_black_only_on_every_path() { + for (src, dst) in [(coated(), fogra()), (fogra(), coated()), (fogra(), fogra())] { + let bp = BlackPreserving::new(src, dst, opts()).unwrap(); + for k in [0.0f32, 0.1, 0.5, 0.9, 1.0] { + for fast in [false, true] { + let mut out = [1.0f32; 4]; + if fast { bp.eval_fast(&[0.0, 0.0, 0.0, k], &mut out) } else { bp.eval(&[0.0, 0.0, 0.0, k], &mut out) }.unwrap(); + assert_eq!(out[..3], [0.0; 3], "k {k} fast {fast}"); + assert_eq!(out[3], bp.map_k(k)); + } + } + let src8: Vec = (0..=255u8).flat_map(|k| [0, 0, 0, k, 7]).collect(); + let mut dst8 = vec![0u8; src8.len()]; + bp.convert_u8(&src8, 5, &mut dst8, 5, true).unwrap(); + for (k, px) in dst8.as_chunks::<5>().0.iter().enumerate() { + assert_eq!(px[..3], [0; 3], "u8 k {k}"); + assert!((f32::from(px[3]) - bp.map_k(k as f32 / 255.0) * 255.0).abs() <= 0.5, "u8 k {k}: {}", px[3]); + assert_eq!(px[4], 7, "extra channel copied"); + } + let src16: Vec = (0..=64u16).flat_map(|k| [0, 0, 0, k * 1023]).collect(); + let mut dst16 = vec![0u16; src16.len()]; + bp.convert_u16(&src16, 4, &mut dst16, 4, false).unwrap(); + for (px, k) in dst16.as_chunks::<4>().0.iter().zip(src16.as_chunks::<4>().0) { + assert_eq!(px[..3], [0; 3], "u16 {k:?}"); + assert!((f32::from(px[3]) - bp.map_k(f32::from(k[3]) / 65535.0) * 65535.0).abs() <= 0.5, "u16 {k:?}: {}", px[3]); + } + let srcf: Vec = (0..=10).flat_map(|k| [0.0, 0.0, 0.0, k as f32 / 10.0]).collect(); + let mut dstf = vec![0.0f32; srcf.len()]; + bp.convert_f32(&srcf, 4, &mut dstf, 4, false).unwrap(); + for (px, k) in dstf.as_chunks::<4>().0.iter().zip(srcf.as_chunks::<4>().0) { + assert_eq!(*px, [0.0, 0.0, 0.0, bp.map_k(k[3])], "f32 {k:?}"); + } + } +} + +#[test] +fn the_destination_black_matches_the_source_lightness() { + // Measured worst error over 201 K steps, both directions, both intents, BPC on and off: + // 0.007 L*. + for intent in [Intent::RelativeColorimetric, Intent::Perceptual] { + for bpc in [true, false] { + let o = TransformOptions { intent, bpc, ..opts() }; + for (src, dst) in [(coated(), fogra()), (fogra(), coated())] { + let bp = BlackPreserving::new(src, dst, o).unwrap(); + let dst_black = lightness(dst, o, [0.0, 0.0, 0.0, 1.0]); + for k in [0.1f32, 0.3, 0.5, 0.7, 0.9, 1.0] { + let want = lightness(src, o, [0.0, 0.0, 0.0, k]); + if want <= dst_black { + assert_eq!(bp.map_k(k), 1.0, "darker than the destination's black clamps to K = 1"); + continue; + } + let got = lightness(dst, o, [0.0, 0.0, 0.0, bp.map_k(k)]); + assert!((got - want).abs() < 0.02, "{intent:?} bpc {bpc} k {k}: L* {got} for {want}"); + } + assert_eq!(bp.map_k(0.0), 0.0, "paper stays paper"); + assert!(bp.map_k(1.0) > 0.95, "full black stays near full black: {}", bp.map_k(1.0)); + assert!(bp.map_k(0.25) < bp.map_k(0.75)); + } + } + } + let same = BlackPreserving::new(fogra(), fogra(), opts()).unwrap(); + for k in [0.0f32, 0.2, 0.6, 1.0] { + assert!((same.map_k(k) - k).abs() < 1e-3, "{k} -> {}", same.map_k(k)); + } +} + +#[test] +fn colours_with_any_chromatic_ink_take_the_ordinary_path() { + let bp = BlackPreserving::new(coated(), fogra(), opts()).unwrap(); + for input in [[1e-6f32, 0.0, 0.0, 0.5], [0.0, 0.2, 0.0, 0.5], [0.3, 0.3, 0.3, 0.0], [0.0, 0.0, 1.0, 1.0]] { + let (mut a, mut b) = ([0.0f32; 4], [0.0f32; 4]); + bp.eval(&input, &mut a).unwrap(); + bp.transform().eval(&input, &mut b).unwrap(); + assert_eq!(a, b, "{input:?}"); + } + let src = [1u8, 0, 0, 128, 0, 1, 0, 128]; + let (mut a, mut b) = ([0u8; 8], [0u8; 8]); + bp.convert_u8(&src, 4, &mut a, 4, false).unwrap(); + bp.transform().convert_u8(&src, 4, &mut b, 4, false).unwrap(); + assert_eq!(a, b); +} + +#[test] +fn refusals_and_hostile_values() { + let srgb = Builtin::Srgb.profile(); + assert!(matches!(BlackPreserving::new(srgb, fogra(), opts()), Err(CmsError::InvalidArgument(_)))); + assert!(matches!(BlackPreserving::new(fogra(), srgb, opts()), Err(CmsError::InvalidArgument(_)))); + let abs = TransformOptions { intent: Intent::AbsoluteColorimetric, ..opts() }; + assert!(matches!(BlackPreserving::new(fogra(), coated(), abs), Err(CmsError::InvalidArgument(_)))); + let bp = BlackPreserving::new(coated(), fogra(), opts()).unwrap(); + for k in [f32::NAN, f32::INFINITY, f32::NEG_INFINITY, -1.0, 2.0] { + assert!((0.0..=1.0).contains(&bp.map_k(k)), "{k}"); + } + let mut out = [0.0f32; 4]; + assert!(bp.eval(&[0.0; 3], &mut out).is_err(), "short input"); + assert!(bp.convert_u8(&[0, 0, 0, 9, 0], 4, &mut [0u8; 4], 4, false).is_err(), "partial pixel"); + assert_eq!(invert(&[], 50.0), 0.0); + assert_eq!(invert(&[100.0], 50.0), 0.0); + assert_eq!(invert(&[100.0, 0.0], 150.0), 0.0); + assert_eq!(invert(&[100.0, 0.0], -5.0), 1.0); + assert!((invert(&[100.0, 50.0, 0.0], 25.0) - 0.75).abs() < 1e-12); + assert_eq!(map(&[], f32::INFINITY, 0.5), 0.0); +} + +#[test] +fn black_beyond_the_destination_maximum_maps_to_full_black_between_samples() { + // Source L* = 100 (1 - K), destination L* = 100 - 50 K: from K = 0.5 the source is darker + // than any destination black, and 0.5 falls between the 1024 samples. + let ramp = |f: fn(f64) -> f64| (0..K_SAMPLES).map(|i| f(i as f64 / (K_SAMPLES - 1) as f64)).collect::>(); + let (src, dst) = (ramp(|k| 100.0 * (1.0 - k)), ramp(|k| 100.0 - 50.0 * k)); + let (curve, saturate) = k_curve(&src, &dst).unwrap(); + assert!((saturate - 0.5).abs() < 1e-6, "{saturate}"); + for k in [0.5001f32, 0.6, 1.0] { + assert_eq!(map(&curve, saturate, k), 1.0, "{k}"); + } + assert!((map(&curve, saturate, 0.25) - 0.5).abs() < 1e-4); + let (_, never) = k_curve(&dst, &src).unwrap(); + assert_eq!(never, f32::INFINITY, "a lighter source never saturates"); +} diff --git a/crates/cms/src/lib.rs b/crates/cms/src/lib.rs index 949164b51..410e67ce2 100644 --- a/crates/cms/src/lib.rs +++ b/crates/cms/src/lib.rs @@ -19,6 +19,7 @@ //! CIE 15, and Adobe's published black point compensation paper. #![forbid(unsafe_code)] +pub mod black; pub mod builtin; mod builtin_v2; pub mod clut; @@ -31,6 +32,7 @@ pub mod lutfile; pub mod math; pub mod named; mod normalize; +pub mod palette; pub mod pipeline; pub mod profile; pub mod sony_lut; @@ -40,6 +42,7 @@ pub mod transform; mod write; pub mod write_v2; +pub use black::BlackPreserving; pub use builtin::Builtin; pub use clut::Clut; pub use curve::Curve; diff --git a/crates/cms/src/math.rs b/crates/cms/src/math.rs index 38bf22e9f..5970b63b3 100644 --- a/crates/cms/src/math.rs +++ b/crates/cms/src/math.rs @@ -43,7 +43,9 @@ pub const fn det(m: &Mat3) -> f64 { + m[0][2] * (m[1][0] * m[2][1] - m[1][1] * m[2][0]) } -/// Inverse, or `None` when (nearly) singular. +/// Inverse, or `None` when (nearly) singular: the determinant is not finite or is below 1e-12. +/// Profile construction checks its matrices with this rule. [`inverse`] takes the determinant +/// relative to the largest entry instead. pub const fn invert(m: &Mat3) -> Option { let d = det(m); if !d.is_finite() || d.abs() < 1e-12 { @@ -57,14 +59,66 @@ pub const fn invert(m: &Mat3) -> Option { ]) } +/// Inverse of a matrix at any scale, or `None` when it holds a NaN or an infinite entry, is all +/// zeros, is singular to within rounding (the determinant is at most 1e-12 times the cube of the +/// largest entry), or has an inverse with an entry beyond the range of `f64`. +/// +/// The matrix is divided by its largest entry before the determinant is taken, so a matrix whose +/// own determinant overflows or underflows (`diag(1e-200, 1e-200, 1e-200)`) still inverts. +pub const fn inverse(m: &Mat3) -> Option { + let mut scale = 0.0f64; + let mut i = 0; + while i < 9 { + let v = m[i / 3][i % 3]; + if v.is_nan() { + return None; + } + if v.abs() > scale { + scale = v.abs(); + } + i += 1; + } + if !(scale.is_finite() && scale > 0.0) { + return None; + } + let mut s = [[0.0; 3]; 3]; + let mut i = 0; + while i < 9 { + s[i / 3][i % 3] = m[i / 3][i % 3] / scale; + i += 1; + } + let d = det(&s); + if !d.is_finite() || d.abs() <= 1e-12 { + return None; + } + // Each cofactor is divided by the determinant and then by the scale: the reciprocals can + // overflow where the quotients do not. + let c = [ + [s[1][1] * s[2][2] - s[1][2] * s[2][1], s[0][2] * s[2][1] - s[0][1] * s[2][2], s[0][1] * s[1][2] - s[0][2] * s[1][1]], + [s[1][2] * s[2][0] - s[1][0] * s[2][2], s[0][0] * s[2][2] - s[0][2] * s[2][0], s[0][2] * s[1][0] - s[0][0] * s[1][2]], + [s[1][0] * s[2][1] - s[1][1] * s[2][0], s[0][1] * s[2][0] - s[0][0] * s[2][1], s[0][0] * s[1][1] - s[0][1] * s[1][0]], + ]; + let mut inv = [[0.0; 3]; 3]; + let mut i = 0; + while i < 9 { + let v = c[i / 3][i % 3] / d / scale; + if !v.is_finite() { + return None; + } + inv[i / 3][i % 3] = v; + i += 1; + } + Some(inv) +} + /// XYZ (Y = 1) of a chromaticity `(x, y)`. pub const fn xy_to_xyz(xy: [f64; 2]) -> [f64; 3] { let [x, y] = xy; [x / y, 1.0, (1.0 - x - y) / y] } -/// Bradford cone response matrix (Lam 1985). -const BRADFORD: Mat3 = [[0.8951, 0.2664, -0.1614], [-0.7502, 1.7135, 0.0367], [0.0389, -0.0685, 1.0296]]; +/// Bradford cone response matrix (Lam 1985): XYZ to sharpened cone responses. +pub const BRADFORD: Mat3 = [[0.8951, 0.2664, -0.1614], [-0.7502, 1.7135, 0.0367], [0.0389, -0.0685, 1.0296]]; /// Inverse of [`BRADFORD`] (determinant ~1.7), computed at compile time. const BRADFORD_INV: Mat3 = match invert(&BRADFORD) { @@ -81,6 +135,17 @@ pub fn bradford(src: [f64; 3], dst: [f64; 3]) -> Mat3 { mul(&inv, &mul(&scale, &BRADFORD)) } +/// [`bradford`], or `None` when a white's cone response is not finite or not above 0, or the +/// response ratios overflow. [`bradford`] divides by the source response without this check. +pub fn bradford_checked(src: [f64; 3], dst: [f64; 3]) -> Option { + let ok = |v: [f64; 3]| v.iter().all(|c| c.is_finite() && *c > 0.0); + if !(ok(apply(&BRADFORD, src)) && ok(apply(&BRADFORD, dst))) { + return None; + } + let m = bradford(src, dst); + m.iter().flatten().all(|v| v.is_finite()).then_some(m) +} + /// RGB → XYZ matrix (relative to `white`, Y = 1) for primaries given as chromaticities, or /// `None` when the primaries are not independent. pub const fn rgb_to_xyz_matrix(r: [f64; 2], g: [f64; 2], b: [f64; 2], white: [f64; 3]) -> Option { @@ -246,4 +311,57 @@ mod tests { assert!((delta_e2000(b, a) - want).abs() < 1e-4); } } + + fn close(a: &Mat3, b: &Mat3, tol: f64) { + for i in 0..3 { + for j in 0..3 { + assert!((a[i][j] - b[i][j]).abs() <= tol, "[{i}][{j}] {} vs {}", a[i][j], b[i][j]); + } + } + } + + const fn diag(v: f64) -> Mat3 { + [[v, 0.0, 0.0], [0.0, v, 0.0], [0.0, 0.0, v]] + } + + #[test] + fn inverse_matches_invert_on_ordinary_matrices() { + let m = [[0.4, 0.3, 0.2], [0.2, 0.7, 0.1], [0.0, 0.1, 0.8]]; + close(&inverse(&m).unwrap(), &invert(&m).unwrap(), 1e-12); + assert_eq!(inverse(&BRADFORD).map(|_| ()), Some(())); + } + + #[test] + fn inverse_works_at_any_scale_and_rejects_what_has_no_finite_inverse() { + // The determinant, 1e-312, has no finite reciprocal; the inverse itself is finite. + close(&inverse(&diag(1e-104)).unwrap(), &diag(1e104), 1e93); + assert_eq!(invert(&diag(1e-104)), None); + // A determinant beyond f64 in either direction still leaves a finite inverse. + close(&inverse(&diag(1e-200)).unwrap(), &diag(1e200), 1e186); + close(&inverse(&diag(1e110)).unwrap(), &diag(1e-110), 1e-124); + assert_eq!(inverse(&diag(f64::MAX)).map(|m| m[0][0]), Some(1.0 / f64::MAX)); + // An inverse with entries beyond f64 is no inverse. + assert_eq!(inverse(&diag(1e-310)), None); + assert_eq!(inverse(&[[0.0; 3]; 3]), None); + assert_eq!(inverse(&[[f64::NAN; 3]; 3]), None); + assert_eq!(inverse(&diag(f64::INFINITY)), None); + let mut one_nan = IDENTITY; + one_nan[1][2] = f64::NAN; + assert_eq!(inverse(&one_nan), None); + // Singular to within rounding relative to the largest entry. + assert_eq!(inverse(&[[1.0, 2.0, 3.0], [2.0, 4.0, 6.0], [0.0, 0.0, 1e9]]), None); + } + + #[test] + fn bradford_checked_rejects_whites_with_no_cone_response() { + let d65 = xy_to_xyz(D65_XY); + close(&bradford_checked(d65, D50).unwrap(), &bradford(d65, D50), 0.0); + assert_eq!(bradford_checked([0.0; 3], D50), None); + assert_eq!(bradford_checked(d65, [f64::NAN; 3]), None); + assert_eq!(bradford_checked(d65, [-1.0, -1.0, -1.0]), None); + // Cone responses this small give scale ratios beyond f64. + assert_eq!(bradford_checked([1e-320; 3], d65), None); + // Unchecked, the zero white divides by zero. + assert!(bradford([0.0; 3], D50).iter().flatten().any(|v| !v.is_finite())); + } } diff --git a/crates/cms/src/palette.rs b/crates/cms/src/palette.rs new file mode 100644 index 000000000..8aabb70d8 --- /dev/null +++ b/crates/cms/src/palette.rs @@ -0,0 +1,806 @@ +//! Palette I/O for `.gpl` (GIMP Palette), `.css` (CSS custom properties, write-only), +//! `.ase` (Adobe Swatch Exchange, binary), and `.acb` (Adobe Color Book, read-only). + +use std::collections::{HashMap, HashSet}; + +/// A colour in a palette swatch. +#[derive(Clone, Copy, Debug, PartialEq)] +pub enum PaletteColor { + Rgb { r: f32, g: f32, b: f32 }, + Cmyk { c: f32, m: f32, y: f32, k: f32 }, + Lab { l: f32, a: f32, b: f32 }, + Gray { k: f32 }, +} + +impl PaletteColor { + pub fn rgb(r: f32, g: f32, b: f32) -> Self { + Self::Rgb { r, g, b } + } + + pub fn rgb8(r: u8, g: u8, b: u8) -> Self { + Self::Rgb { r: f32::from(r) / 255.0, g: f32::from(g) / 255.0, b: f32::from(b) / 255.0 } + } + + pub fn cmyk(c: f32, m: f32, y: f32, k: f32) -> Self { + Self::Cmyk { c, m, y, k } + } + + pub fn lab(l: f32, a: f32, b: f32) -> Self { + Self::Lab { l, a, b } + } + + pub fn gray(k: f32) -> Self { + Self::Gray { k } + } + + /// Approximate 8-bit sRGB representation for formats that only store RGB (`.gpl`, `.css`). + pub fn to_rgb8(self) -> [u8; 3] { + let to_u8 = |v: f32| (v.clamp(0.0, 1.0) * 255.0).round() as u8; + match self { + Self::Rgb { r, g, b } => [to_u8(r), to_u8(g), to_u8(b)], + Self::Gray { k } => { + let v = to_u8(1.0 - k.clamp(0.0, 1.0)); + [v, v, v] + } + Self::Cmyk { c, m, y, k } => { + let (c, m, y, k) = (c.clamp(0.0, 1.0), m.clamp(0.0, 1.0), y.clamp(0.0, 1.0), k.clamp(0.0, 1.0)); + [to_u8((1.0 - c) * (1.0 - k)), to_u8((1.0 - m) * (1.0 - k)), to_u8((1.0 - y) * (1.0 - k))] + } + Self::Lab { l, a, b } => lab_to_srgb8(l, a, b), + } + } +} + +fn lab_to_srgb8(l: f32, a: f32, b: f32) -> [u8; 3] { + let fy = (l + 16.0) / 116.0; + let fx = a / 500.0 + fy; + let fz = fy - b / 200.0; + let inv = |t: f32| { + if t > 6.0 / 29.0 { t * t * t } else { 3.0 * (6.0 / 29.0) * (6.0 / 29.0) * (t - 4.0 / 29.0) } + }; + // D65 white point + let x = 0.95047 * inv(fx); + let y = 1.00000 * inv(fy); + let z = 1.08883 * inv(fz); + let rl = 3.2404542 * x - 1.5371385 * y - 0.4985314 * z; + let gl = -0.969_266 * x + 1.8760108 * y + 0.0415560 * z; + let bl = 0.0556434 * x - 0.2040259 * y + 1.0572252 * z; + let gamma = |u: f32| { + let u = u.clamp(0.0, 1.0); + let s = if u <= 0.0031308 { 12.92 * u } else { 1.055 * u.powf(1.0 / 2.4) - 0.055 }; + (s.clamp(0.0, 1.0) * 255.0).round() as u8 + }; + [gamma(rl), gamma(gl), gamma(bl)] +} + +/// A single named colour swatch in a [`Palette`]. +#[derive(Clone, Debug, PartialEq)] +pub struct PaletteSwatch { + pub name: String, + pub color: PaletteColor, + pub global: bool, + pub spot: bool, +} + +/// A named group of swatches in a [`Palette`]. +#[derive(Clone, Debug, Default, PartialEq)] +pub struct PaletteGroup { + pub name: String, + pub swatches: Vec, +} + +/// A colour palette / swatch library. +#[derive(Clone, Debug, Default, PartialEq)] +pub struct Palette { + pub name: String, + pub swatches: Vec, + pub groups: Vec, +} + +/// Supported palette file formats for writing. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub enum PaletteFormat { + /// `.gpl`: plain-text 8-bit RGB palette. + Gpl, + /// `.ase`: binary Adobe Swatch Exchange. + Ase, + /// `.css`: CSS custom properties on `:root` (write-only). + Css, +} + +impl PaletteFormat { + pub const ALL: [PaletteFormat; 3] = [PaletteFormat::Gpl, PaletteFormat::Ase, PaletteFormat::Css]; + + /// The format's id / file extension. + pub fn id(self) -> &'static str { + match self { + PaletteFormat::Gpl => "gpl", + PaletteFormat::Ase => "ase", + PaletteFormat::Css => "css", + } + } + + /// Parse a format id or extension (case-insensitive, leading dot allowed). + pub fn parse(s: &str) -> Option { + let s = s.trim_start_matches('.').to_ascii_lowercase(); + Self::ALL.into_iter().find(|f| f.id() == s) + } + + pub fn readable(self) -> bool { + self != PaletteFormat::Css + } + + pub fn binary(self) -> bool { + self == PaletteFormat::Ase + } +} + +const GPL_HEADER: &str = "GIMP Palette"; +const GPL_GROUP: &str = "# Group:"; +const ASE_SIGNATURE: &[u8] = b"ASEF"; +const ASE_GROUP_START: u16 = 0xC001; +const ASE_GROUP_END: u16 = 0xC002; +const ASE_COLOR: u16 = 0x0001; +const ASE_MAX_ENTRIES: usize = 100_000; +const ASE_MAX_NAME: usize = 1024; +const ASE_CUT_SHORT: &str = "the swatch exchange file is cut short"; +const ACB_SIGNATURE: &[u8] = b"8BCB"; +const ACB_CUT_SHORT: &str = "the color book is cut short"; +const ACB_MAX_NAME_BYTES: usize = 64 << 20; + +/// Structured palette failure for callers that supply localized messages. +/// +/// The existing string-returning entry points retain their English diagnostics. +/// Match these variants rather than parsing those strings when translating errors. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub enum PaletteError { + UnsupportedFormat, + TruncatedAse, + TruncatedAcb, + AseWriteEntryLimit { limit: usize, entries: usize }, + AseReadEntryLimit { limit: usize }, + AseBlockCount, + AseBlockLength, + AseNameLength, + AseVersion { major: u16, minor: u16 }, + AcbVersion { version: u16 }, + AcbEntryLimit { limit: usize }, + AcbColorSpace { space: u16 }, + AcbNameBytes { limit: usize }, +} + +impl std::fmt::Display for PaletteError { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + match self { + Self::UnsupportedFormat => f.write_str("not a supported palette (.gpl, .ase, or .acb)"), + Self::TruncatedAse => f.write_str(ASE_CUT_SHORT), + Self::TruncatedAcb => f.write_str(ACB_CUT_SHORT), + Self::AseWriteEntryLimit { limit, entries } => { + write!(f, "at most {limit} colors and groups are supported in a swatch exchange file, and this library has {entries}") + } + Self::AseReadEntryLimit { limit } => write!(f, "the swatch exchange file holds more than {limit} colors and groups"), + Self::AseBlockCount => f.write_str("too many swatch exchange blocks"), + Self::AseBlockLength => f.write_str("a swatch exchange block is too long"), + Self::AseNameLength => f.write_str("a swatch exchange name is too long"), + Self::AseVersion { major, minor } => write!(f, "swatch exchange version {major}.{minor} isn't supported (only 1.x)"), + Self::AcbVersion { version } => write!(f, "color book version {version} isn't supported (only 1)"), + Self::AcbEntryLimit { limit } => write!(f, "the color book holds more than {limit} colors"), + Self::AcbColorSpace { space } => write!(f, "color books in color space {space} aren't supported (only RGB, CMYK and Lab)"), + Self::AcbNameBytes { limit } => write!(f, "the color book's names take more than {} MB", limit >> 20), + } + } +} + +impl std::error::Error for PaletteError {} + +/// Write `palette` in `format`. +pub fn write_palette(palette: &Palette, format: PaletteFormat) -> Result, String> { + write_palette_typed(palette, format).map_err(|error| error.to_string()) +} + +/// Write a palette, returning structured errors for caller-localized diagnostics. +pub fn write_palette_typed(palette: &Palette, format: PaletteFormat) -> Result, PaletteError> { + match format { + PaletteFormat::Gpl => Ok(write_gpl(palette).into_bytes()), + PaletteFormat::Ase => write_ase(palette), + PaletteFormat::Css => Ok(write_css(palette).into_bytes()), + } +} + +/// Read a palette from `bytes` (`.ase`, `.acb`, or `.gpl`, detected from content). +/// `fallback_name` is used when the file does not specify a library name. +pub fn read_palette(bytes: &[u8], fallback_name: &str) -> Result { + read_palette_typed(bytes, fallback_name).map_err(|error| error.to_string()) +} + +/// Read a palette, returning structured errors for caller-localized diagnostics. +/// Detection and fallback naming match [`read_palette`]. +pub fn read_palette_typed(bytes: &[u8], fallback_name: &str) -> Result { + if bytes.starts_with(ASE_SIGNATURE) { + return read_ase(bytes, fallback_name); + } + if bytes.starts_with(ACB_SIGNATURE) { + return read_acb(bytes, fallback_name).map_err(|e| if e == PaletteError::TruncatedAse { PaletteError::TruncatedAcb } else { e }); + } + let text = String::from_utf8_lossy(bytes); + let text = text.trim_start_matches('\u{feff}').trim_start(); + if text.starts_with(GPL_HEADER) { + return Ok(read_gpl(text, fallback_name)); + } + Err(PaletteError::UnsupportedFormat) +} + +/// Returns `true` if `bytes` looks like a `.gpl`, `.ase`, or `.acb` palette. +pub fn sniff_palette(bytes: &[u8]) -> bool { + if bytes.starts_with(ASE_SIGNATURE) || bytes.starts_with(ACB_SIGNATURE) { + return true; + } + let prefix = bytes.get(..1024).unwrap_or(bytes); + let text = String::from_utf8_lossy(prefix); + text.trim_start_matches('\u{feff}').trim_start().starts_with(GPL_HEADER) +} + +fn one_line(s: &str) -> String { + s.split(['\n', '\r', '\t']).collect::>().join(" ").trim().to_string() +} + +fn write_gpl(lib: &Palette) -> String { + let mut out = format!("{GPL_HEADER}\nName: {}\nColumns: 0\n#\n", one_line(&lib.name)); + let colors = |out: &mut String, list: &[PaletteSwatch]| { + for w in list { + let [r, g, b] = w.color.to_rgb8(); + out.push_str(&format!("{r:3} {g:3} {b:3}\t{}\n", one_line(&w.name))); + } + }; + colors(&mut out, &lib.swatches); + for g in &lib.groups { + out.push_str(&format!("{GPL_GROUP} {}\n", one_line(&g.name))); + colors(&mut out, &g.swatches); + } + out +} + +/// `name` as a CSS custom property (`--` and an escaped identifier): lower case, spaces as +/// hyphens, other characters an identifier can't hold escaped with a backslash. +pub fn css_property(name: &str) -> String { + let mut out = String::from("--"); + for word in name.split_whitespace() { + if out.len() > 2 { + out.push('-'); + } + for ch in word.chars().flat_map(char::to_lowercase) { + if ch.is_ascii_alphanumeric() || ch == '-' || ch == '_' || !ch.is_ascii() { + out.push(ch); + } else if ch.is_ascii_graphic() { + out.push('\\'); + out.push(ch); + } else { + out.push_str(&format!("\\{:x} ", ch as u32)); + } + } + } + if out.len() == 2 { + out.push_str("swatch"); + } + out +} + +fn css_comment(s: &str) -> String { + one_line(s).replace("*/", "* /") +} + +fn write_css(lib: &Palette) -> String { + let mut out = format!("/* {} */\n:root {{\n", css_comment(&lib.name)); + let mut taken: HashSet = HashSet::new(); + let mut next: HashMap = HashMap::new(); + let mut props = |out: &mut String, list: &[PaletteSwatch]| { + for w in list { + let [r, g, b] = w.color.to_rgb8(); + let value = format!("#{r:02x}{g:02x}{b:02x}"); + let base = css_property(&w.name); + let name = if taken.insert(base.clone()) { + base + } else { + let n = next.entry(base.clone()).or_insert(1); + loop { + *n += 1; + let candidate = format!("{base}-{n}"); + if taken.insert(candidate.clone()) { + break candidate; + } + } + }; + let note = if w.spot { " /* spot */" } else { "" }; + out.push_str(&format!(" {name}: {value};{note}\n")); + } + }; + props(&mut out, &lib.swatches); + for g in &lib.groups { + out.push_str(&format!(" /* {} */\n", css_comment(&g.name))); + props(&mut out, &g.swatches); + } + out.push_str("}\n"); + out +} + +fn write_ase(lib: &Palette) -> Result, PaletteError> { + let entries = lib.swatches.len() + lib.groups.iter().map(|g| 1 + g.swatches.len()).sum::(); + if entries > ASE_MAX_ENTRIES { + return Err(PaletteError::AseWriteEntryLimit { limit: ASE_MAX_ENTRIES, entries }); + } + let mut body = vec![]; + let mut blocks = put_ase_colors(&mut body, &lib.swatches)?; + for g in &lib.groups { + let mut name = vec![]; + put_ase_name(&mut name, &g.name)?; + put_ase_block(&mut body, ASE_GROUP_START, &name)?; + blocks += 2 + put_ase_colors(&mut body, &g.swatches)?; + put_ase_block(&mut body, ASE_GROUP_END, &[])?; + } + let blocks = u32::try_from(blocks).map_err(|_| PaletteError::AseBlockCount)?; + let mut out = ASE_SIGNATURE.to_vec(); + out.extend(1u16.to_be_bytes()); + out.extend(0u16.to_be_bytes()); + out.extend(blocks.to_be_bytes()); + out.extend(body); + Ok(out) +} + +fn put_ase_colors(out: &mut Vec, list: &[PaletteSwatch]) -> Result { + let unit = |v: f32| if v.is_finite() { v.clamp(0.0, 1.0) } else { 0.0 }; + let ab = |v: f32| if v.is_finite() { v.clamp(-128.0, 127.0) } else { 0.0 }; + let mut n = 0; + for w in list { + let mut body = vec![]; + put_ase_name(&mut body, &w.name)?; + let (model, values): (&[u8; 4], Vec) = match w.color { + PaletteColor::Rgb { r, g, b } => (b"RGB ", vec![unit(r), unit(g), unit(b)]), + PaletteColor::Cmyk { c, m, y, k } => (b"CMYK", vec![unit(c), unit(m), unit(y), unit(k)]), + PaletteColor::Lab { l, a, b } => (b"LAB ", vec![unit(l / 100.0), ab(a), ab(b)]), + PaletteColor::Gray { k } => (b"Gray", vec![1.0 - unit(k)]), + }; + body.extend(model); + body.extend(values.iter().flat_map(|v| v.to_be_bytes())); + let kind: u16 = if w.spot { + 1 + } else if w.global { + 0 + } else { + 2 + }; + body.extend(kind.to_be_bytes()); + put_ase_block(out, ASE_COLOR, &body)?; + n += 1; + } + Ok(n) +} + +fn put_ase_block(out: &mut Vec, kind: u16, body: &[u8]) -> Result<(), PaletteError> { + let len = u32::try_from(body.len()).map_err(|_| PaletteError::AseBlockLength)?; + out.extend(kind.to_be_bytes()); + out.extend(len.to_be_bytes()); + out.extend_from_slice(body); + Ok(()) +} + +fn put_ase_name(out: &mut Vec, name: &str) -> Result<(), PaletteError> { + let mut units: Vec = vec![]; + for c in name.chars().filter(|&c| c != '\0') { + let mut buf = [0; 2]; + let encoded = c.encode_utf16(&mut buf); + if units.len() + encoded.len() > ASE_MAX_NAME { + break; + } + units.extend_from_slice(encoded); + } + units.push(0); + let count = u16::try_from(units.len()).map_err(|_| PaletteError::AseNameLength)?; + out.extend(count.to_be_bytes()); + out.extend(units.iter().flat_map(|u| u.to_be_bytes())); + Ok(()) +} + +fn read_gpl(text: &str, fallback: &str) -> Palette { + let mut lib = Palette { name: fallback.into(), ..Default::default() }; + let mut names = UniqueNames::default(); + for line in text.lines().skip(1) { + let line = line.trim(); + if let Some(g) = line.strip_prefix(GPL_GROUP) { + lib.groups.push(PaletteGroup { name: names.unique(group_name(g)), swatches: vec![] }); + continue; + } + if let Some(n) = line.strip_prefix("Name:") { + if !n.trim().is_empty() { + lib.name = n.trim().to_string(); + } + continue; + } + let words: Vec<&str> = line.split_whitespace().collect(); + let rgb: Vec = words.iter().take(3).map_while(|v| v.parse().ok()).collect(); + let [r, g, b] = rgb[..] else { continue }; + let rest = words[3..].join(" "); + let base = if rest.is_empty() { format!("R={r} G={g} B={b}") } else { rest }; + let w = PaletteSwatch { name: names.unique(base), color: PaletteColor::rgb8(r, g, b), global: false, spot: false }; + match lib.groups.last_mut() { + Some(grp) => grp.swatches.push(w), + None => lib.swatches.push(w), + } + } + lib +} + +fn read_ase(bytes: &[u8], fallback: &str) -> Result { + let mut data = AseData(bytes); + data.bytes(ASE_SIGNATURE.len())?; + let (major, minor) = (data.u16()?, data.u16()?); + if major != 1 { + return Err(PaletteError::AseVersion { major, minor }); + } + let blocks = data.u32()?; + let mut lib = Palette { name: fallback.into(), ..Default::default() }; + let mut names = UniqueNames::default(); + let (mut in_group, mut entries) = (false, 0usize); + for _ in 0..blocks { + let kind = data.u16()?; + let len = usize::try_from(data.u32()?).unwrap_or(usize::MAX); + let mut body = AseData(data.bytes(len)?); + if matches!(kind, ASE_GROUP_START | ASE_COLOR) { + entries += 1; + if entries > ASE_MAX_ENTRIES { + return Err(PaletteError::AseReadEntryLimit { limit: ASE_MAX_ENTRIES }); + } + } + match kind { + ASE_GROUP_START => { + lib.groups.push(PaletteGroup { name: names.unique(group_name(&body.name()?)), swatches: vec![] }); + in_group = true; + } + ASE_GROUP_END => in_group = false, + ASE_COLOR => { + let Some(mut w) = ase_swatch(&mut body)? else { continue }; + w.name = names.unique(std::mem::take(&mut w.name)); + match lib.groups.last_mut().filter(|_| in_group) { + Some(g) => g.swatches.push(w), + None => lib.swatches.push(w), + } + } + _ => {} + } + } + Ok(lib) +} + +fn read_acb(bytes: &[u8], fallback: &str) -> Result { + let mut data = AseData(bytes); + data.bytes(ACB_SIGNATURE.len())?; + let version = data.u16()?; + if version != 1 { + return Err(PaletteError::AcbVersion { version }); + } + let _book_id = data.u16()?; + let [title, prefix, suffix, _description] = [data.acb_string()?, data.acb_string()?, data.acb_string()?, data.acb_string()?]; + let count = usize::from(data.u16()?); + if count > ASE_MAX_ENTRIES { + return Err(PaletteError::AcbEntryLimit { limit: ASE_MAX_ENTRIES }); + } + let (_page_size, _page_offset) = (data.u16()?, data.u16()?); + let space = data.u16()?; + let mut colors = Vec::with_capacity(count); + for _ in 0..count { + let name = data.acb_string()?; + let _code = data.bytes(6)?; + let color = match space { + 0 => { + let [r, g, b] = data.array::<3>()?; + PaletteColor::rgb8(r, g, b) + } + 2 => { + let ink = |v: u8| f32::from(255 - v) / 255.0; + let [c, m, y, k] = data.array::<4>()?; + PaletteColor::cmyk(ink(c), ink(m), ink(y), ink(k)) + } + 7 => { + let [l, a, b] = data.array::<3>()?; + PaletteColor::lab(f32::from(l) * 100.0 / 255.0, f32::from(a) - 128.0, f32::from(b) - 128.0) + } + other => return Err(PaletteError::AcbColorSpace { space: other }), + }; + colors.push((name, color)); + } + let spot = data.0.windows(8).last() != Some(b"spflproc".as_slice()); + let mut lib = Palette { name: if title.is_empty() { fallback.into() } else { title }, ..Default::default() }; + let mut names = UniqueNames::default(); + let mut kept = 0usize; + for (name, color) in colors.into_iter().filter(|(n, _)| !n.trim().is_empty()) { + kept = kept.saturating_add(2 * (prefix.len() + name.len() + suffix.len())); + if kept > ACB_MAX_NAME_BYTES { + return Err(PaletteError::AcbNameBytes { limit: ACB_MAX_NAME_BYTES }); + } + let name = names.unique(format!("{prefix}{name}{suffix}").trim().to_string()); + lib.swatches.push(PaletteSwatch { name, color, global: spot, spot }); + } + Ok(lib) +} + +fn ase_swatch(body: &mut AseData) -> Result, PaletteError> { + let name = body.name()?; + let unit = |v: f32| v.clamp(0.0, 1.0); + let color = match &body.array::<4>()? { + b"RGB " => { + let [r, g, b] = [body.f32()?, body.f32()?, body.f32()?]; + PaletteColor::rgb(unit(r), unit(g), unit(b)) + } + b"CMYK" => { + let [c, m, y, k] = [body.f32()?, body.f32()?, body.f32()?, body.f32()?]; + PaletteColor::cmyk(unit(c), unit(m), unit(y), unit(k)) + } + b"LAB " => { + let [l, a, b] = [body.f32()?, body.f32()?, body.f32()?]; + let l = if l > 1.0 { l.min(100.0) } else { unit(l) * 100.0 }; + PaletteColor::lab(l, a.clamp(-128.0, 127.0), b.clamp(-128.0, 127.0)) + } + b"Gray" => PaletteColor::gray(1.0 - unit(body.f32()?)), + _ => return Ok(None), + }; + let kind = if body.0.len() >= 2 { body.u16()? } else { 2 }; + let (global, spot) = match kind { + 0 => (true, false), + 1 => (true, true), + _ => (false, false), + }; + let name = if name.is_empty() { value_name(color) } else { name }; + Ok(Some(PaletteSwatch { name, color, global, spot })) +} + +fn value_name(c: PaletteColor) -> String { + let pct = |v: f32| (v * 100.0).round(); + let byte = |v: f32| (v * 255.0).round(); + match c { + PaletteColor::Cmyk { c, m, y, k } => format!("C={} M={} Y={} K={}", pct(c), pct(m), pct(y), pct(k)), + PaletteColor::Rgb { r, g, b } => format!("R={} G={} B={}", byte(r), byte(g), byte(b)), + PaletteColor::Gray { k } => format!("Gray K={}", pct(k)), + PaletteColor::Lab { l, a, b } => format!("L={} a={} b={}", l.round() + 0.0, a.round() + 0.0, b.round() + 0.0), + } +} + +struct AseData<'a>(&'a [u8]); + +impl<'a> AseData<'a> { + fn bytes(&mut self, n: usize) -> Result<&'a [u8], PaletteError> { + let (head, rest) = self.0.split_at_checked(n).ok_or(PaletteError::TruncatedAse)?; + self.0 = rest; + Ok(head) + } + fn array(&mut self) -> Result<[u8; N], PaletteError> { + let (head, rest) = self.0.split_first_chunk::().ok_or(PaletteError::TruncatedAse)?; + self.0 = rest; + Ok(*head) + } + fn u16(&mut self) -> Result { + self.array().map(u16::from_be_bytes) + } + fn u32(&mut self) -> Result { + self.array().map(u32::from_be_bytes) + } + fn f32(&mut self) -> Result { + let v = f32::from_be_bytes(self.array()?); + Ok(if v.is_finite() { v } else { 0.0 }) + } + fn acb_string(&mut self) -> Result { + let n = usize::try_from(self.u32()?).unwrap_or(usize::MAX); + let (units, _) = self.bytes(n.checked_mul(2).ok_or(PaletteError::TruncatedAse)?)?.as_chunks::<2>(); + let units: Vec = units.iter().take(ASE_MAX_NAME).map(|u| u16::from_be_bytes(*u)).take_while(|&u| u != 0).collect(); + let s = String::from_utf16_lossy(&units); + let s = match s.strip_prefix("$$$/") { + Some(key) => key.split_once('=').map_or("", |(_, text)| text).to_string(), + None => s, + }; + Ok(s.replace("^R", "®").replace("^C", "©")) + } + fn name(&mut self) -> Result { + if self.0.is_empty() { + return Ok(String::new()); + } + let n = usize::from(self.u16()?); + let (units, _) = self.bytes(n * 2)?.as_chunks::<2>(); + let units: Vec = units.iter().take(ASE_MAX_NAME).map(|u| u16::from_be_bytes(*u)).take_while(|&u| u != 0).collect(); + Ok(String::from_utf16_lossy(&units).trim().to_string()) + } +} + +fn group_name(name: &str) -> String { + let name = name.trim(); + if name.is_empty() { "Color Group".into() } else { name.to_string() } +} + +#[derive(Default)] +struct UniqueNames { + taken: HashSet, + last: HashMap, +} + +impl UniqueNames { + fn unique(&mut self, base: String) -> String { + if self.taken.insert(base.clone()) { + return base; + } + let n = self.last.entry(base.clone()).or_insert(1); + loop { + *n += 1; + let name = format!("{base} {n}"); + if self.taken.insert(name.clone()) { + return name; + } + } + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn gpl_roundtrip() { + let pal = Palette { + name: "Test Palette".into(), + swatches: vec![PaletteSwatch { name: "Red".into(), color: PaletteColor::rgb8(255, 0, 0), global: false, spot: false }], + groups: vec![PaletteGroup { + name: "Blues".into(), + swatches: vec![PaletteSwatch { name: "Navy".into(), color: PaletteColor::rgb8(0, 0, 128), global: false, spot: false }], + }], + }; + let bytes = write_palette(&pal, PaletteFormat::Gpl).expect("write gpl"); + assert!(sniff_palette(&bytes)); + let parsed = read_palette(&bytes, "fallback").expect("read gpl"); + assert_eq!(parsed.name, "Test Palette"); + assert_eq!(parsed.swatches.len(), 1); + assert_eq!(parsed.swatches[0].name, "Red"); + assert_eq!(parsed.groups.len(), 1); + assert_eq!(parsed.groups[0].name, "Blues"); + assert_eq!(parsed.groups[0].swatches[0].name, "Navy"); + } + + #[test] + fn typed_errors_distinguish_formats_and_preserve_legacy_messages() { + for (bytes, expected) in [ + (b"no palette".as_slice(), PaletteError::UnsupportedFormat), + (b"ASEF".as_slice(), PaletteError::TruncatedAse), + (b"8BCB".as_slice(), PaletteError::TruncatedAcb), + (b"8BCB\0\x01\0\0\0\0\0\x03\0x".as_slice(), PaletteError::TruncatedAcb), + (b"ASEF\0\x02\0\x03".as_slice(), PaletteError::AseVersion { major: 2, minor: 3 }), + (b"8BCB\0\x02".as_slice(), PaletteError::AcbVersion { version: 2 }), + ] { + assert_eq!(read_palette_typed(bytes, "fallback"), Err(expected)); + assert_eq!(read_palette(bytes, "fallback"), Err(expected.to_string())); + } + assert_eq!(read_palette(b"8BCB", "fallback"), Err("the color book is cut short".into())); + } + + #[test] + fn structured_error_display_preserves_legacy_wording() { + let cases = [ + (PaletteError::UnsupportedFormat, "not a supported palette (.gpl, .ase, or .acb)"), + (PaletteError::TruncatedAse, "the swatch exchange file is cut short"), + (PaletteError::TruncatedAcb, "the color book is cut short"), + ( + PaletteError::AseWriteEntryLimit { limit: 3, entries: 4 }, + "at most 3 colors and groups are supported in a swatch exchange file, and this library has 4", + ), + (PaletteError::AseReadEntryLimit { limit: 3 }, "the swatch exchange file holds more than 3 colors and groups"), + (PaletteError::AseBlockCount, "too many swatch exchange blocks"), + (PaletteError::AseBlockLength, "a swatch exchange block is too long"), + (PaletteError::AseNameLength, "a swatch exchange name is too long"), + (PaletteError::AseVersion { major: 2, minor: 3 }, "swatch exchange version 2.3 isn't supported (only 1.x)"), + (PaletteError::AcbVersion { version: 2 }, "color book version 2 isn't supported (only 1)"), + (PaletteError::AcbEntryLimit { limit: 3 }, "the color book holds more than 3 colors"), + (PaletteError::AcbColorSpace { space: 5 }, "color books in color space 5 aren't supported (only RGB, CMYK and Lab)"), + (PaletteError::AcbNameBytes { limit: 64 << 20 }, "the color book's names take more than 64 MB"), + ]; + for (error, expected) in cases { + assert_eq!(error.to_string(), expected); + } + } + + #[test] + fn typed_write_limit_exposes_counts_without_parsing_english() { + let palette = Palette { groups: vec![PaletteGroup::default(); ASE_MAX_ENTRIES + 1], ..Default::default() }; + let error = PaletteError::AseWriteEntryLimit { limit: ASE_MAX_ENTRIES, entries: ASE_MAX_ENTRIES + 1 }; + assert_eq!(write_palette_typed(&palette, PaletteFormat::Ase), Err(error)); + assert_eq!(write_palette(&palette, PaletteFormat::Ase), Err(error.to_string())); + } + + #[test] + fn typed_success_keeps_legacy_bytes_and_palette() { + let palette = Palette { + name: "typed".into(), + swatches: vec![PaletteSwatch { name: "red".into(), color: PaletteColor::rgb8(255, 0, 0), global: false, spot: false }], + groups: vec![], + }; + assert_eq!( + write_palette_typed(&palette, PaletteFormat::Ase).expect("ASE golden"), + b"ASEF\0\x01\0\0\0\0\0\x01\0\x01\0\0\0\x1c\0\x04\0r\0e\0d\0\0RGB \x3f\x80\0\0\0\0\0\0\0\0\0\0\0\x02" + ); + for format in PaletteFormat::ALL { + let typed = write_palette_typed(&palette, format).expect("typed write"); + assert_eq!(write_palette(&palette, format), Ok(typed.clone())); + if format.readable() { + assert_eq!(read_palette(&typed, "typed"), read_palette_typed(&typed, "typed").map_err(|error| error.to_string())); + } + } + } + + #[test] + fn ase_roundtrip() { + let pal = Palette { + name: "ASE".into(), + swatches: vec![ + PaletteSwatch { name: "Spot Red".into(), color: PaletteColor::rgb(1.0, 0.0, 0.0), global: true, spot: true }, + PaletteSwatch { name: "CMYK Cyan".into(), color: PaletteColor::cmyk(1.0, 0.0, 0.0, 0.0), global: true, spot: false }, + PaletteSwatch { name: "Lab Mid".into(), color: PaletteColor::lab(50.0, 10.0, -20.0), global: false, spot: false }, + PaletteSwatch { name: "Gray 40".into(), color: PaletteColor::gray(0.4), global: false, spot: false }, + ], + groups: vec![PaletteGroup { + name: "Group 1".into(), + swatches: vec![PaletteSwatch { name: "Green".into(), color: PaletteColor::rgb(0.0, 1.0, 0.0), global: false, spot: false }], + }], + }; + let bytes = write_palette(&pal, PaletteFormat::Ase).expect("write ase"); + assert!(sniff_palette(&bytes)); + let parsed = read_palette(&bytes, "ASE").expect("read ase"); + assert_eq!(parsed.swatches.len(), 4); + assert!(parsed.swatches[0].spot && parsed.swatches[0].global); + assert!(!parsed.swatches[1].spot && parsed.swatches[1].global); + assert_eq!(parsed.groups.len(), 1); + assert_eq!(parsed.groups[0].name, "Group 1"); + } + + #[test] + fn css_output() { + let pal = Palette { + name: "Brand".into(), + swatches: vec![ + PaletteSwatch { name: "Primary Blue".into(), color: PaletteColor::rgb8(0, 102, 204), global: true, spot: true }, + PaletteSwatch { name: "Primary Blue".into(), color: PaletteColor::rgb8(0, 0, 0), global: false, spot: false }, + ], + groups: vec![], + }; + let bytes = write_palette(&pal, PaletteFormat::Css).expect("write css"); + let css = String::from_utf8(bytes).expect("utf8"); + assert!(css.contains("--primary-blue: #0066cc; /* spot */")); + assert!(css.contains("--primary-blue-2: #000000;")); + } + + #[test] + fn acb_read() { + let mut acb = Vec::new(); + acb.extend_from_slice(b"8BCB"); + acb.extend_from_slice(&1u16.to_be_bytes()); + acb.extend_from_slice(&3000u16.to_be_bytes()); + let put_str = |buf: &mut Vec, s: &str| { + let units: Vec = s.encode_utf16().collect(); + buf.extend_from_slice(&(units.len() as u32).to_be_bytes()); + for u in units { + buf.extend_from_slice(&u.to_be_bytes()); + } + }; + put_str(&mut acb, "$$$/Book/Title=Pantone^R"); + put_str(&mut acb, "PANTONE "); + put_str(&mut acb, " C"); + put_str(&mut acb, ""); + acb.extend_from_slice(&1u16.to_be_bytes()); // count + acb.extend_from_slice(&7u16.to_be_bytes()); // page size + acb.extend_from_slice(&0u16.to_be_bytes()); // page offset + acb.extend_from_slice(&0u16.to_be_bytes()); // RGB + put_str(&mut acb, "185"); + acb.extend_from_slice(b"000185"); + acb.extend_from_slice(&[228, 0, 43]); + acb.extend_from_slice(b"spflspot"); + + assert!(sniff_palette(&acb)); + let parsed = read_palette(&acb, "fallback").expect("read acb"); + assert_eq!(parsed.name, "Pantone®"); + assert_eq!(parsed.swatches.len(), 1); + assert_eq!(parsed.swatches[0].name, "PANTONE 185 C"); + assert!(parsed.swatches[0].spot); + } +} diff --git a/crates/cms/src/profile.rs b/crates/cms/src/profile.rs index eac2e4500..786750479 100644 --- a/crates/cms/src/profile.rs +++ b/crates/cms/src/profile.rs @@ -224,7 +224,8 @@ pub struct Profile { pub b2a: [Option; 3], /// The bytes this profile was parsed from (or encoded to), kept for byte-exact embedding. pub(crate) bytes: Option>>, - pub(crate) hash: std::sync::OnceLock, + /// Lazily computed content hash: a cache, not part of the profile's identity. + pub(crate) hash: HashCache, } impl Profile { @@ -385,7 +386,7 @@ impl Profile { /// fixed-key 64-bit hash, so a crafted profile can share another's: equal hashes only narrow /// the search, [`Profile::same_bytes`] decides. pub fn content_hash(&self) -> u64 { - *self.hash.get_or_init(|| { + *self.hash.0.get_or_init(|| { use std::hash::{Hash, Hasher}; let mut h = std::collections::hash_map::DefaultHasher::new(); self.to_bytes().hash(&mut h); @@ -594,7 +595,7 @@ mod tests { /// `p` with the content hash of `other`: the hash is a fixed-key 64-bit SipHash, so a /// crafted profile can have another's (#8613). Setting it stands in for finding one. fn with_hash_of(p: &Profile, other: &Profile) -> Profile { - let p = Profile { hash: std::sync::OnceLock::from(other.content_hash()), ..p.clone() }; + let p = Profile { hash: HashCache(std::sync::OnceLock::from(other.content_hash())), ..p.clone() }; assert_eq!(p.content_hash(), other.content_hash()); p } @@ -633,3 +634,15 @@ mod tests { assert_eq!(eval(&cached(srgb, lab, opts).unwrap()), sr); } } + +/// A profile's lazily computed content hash. Whether it has been computed yet depends on who asked +/// first (a shared built-in profile is hashed by whichever caller runs first), so it never takes part +/// in a profile's equality. +#[derive(Clone, Debug, Default)] +pub(crate) struct HashCache(std::sync::OnceLock); + +impl PartialEq for HashCache { + fn eq(&self, _: &Self) -> bool { + true + } +} diff --git a/crates/cms/src/synth.rs b/crates/cms/src/synth.rs index d80eb2be9..cb2c2f397 100644 --- a/crates/cms/src/synth.rs +++ b/crates/cms/src/synth.rs @@ -19,6 +19,9 @@ //! L* is scaled onto the device black, chroma is softly compressed against a gamut boundary //! descriptor sampled from the forward model — then solved as above. //! +//! That is [`GamutMapping::Legacy`]. [`GamutMapping::Oklab`] maps out-of-gamut colours in Oklab +//! instead and gives saturation its own table; the Coated FOGRA39 built-in uses it. +//! //! The model is plausible for coated offset, not a measured characterisation: use a real //! profile from your print provider for production print. //! @@ -51,6 +54,11 @@ pub struct CmykParams { pub k_max: f64, /// Exponent of the black generation curve above `gcr_start`. pub gcr_gamma: f64, + /// Black generation as a curve of `[gray component, black]` points with increasing gray + /// components in `[0, 1]`, interpolated linearly and held flat beyond the ends. Empty by + /// default: black is then `k_max` times the ramp of `gcr_start` and `gcr_gamma` (the curve + /// of the shipped Photocraft profile). + pub gcr_curve: Vec<[f64; 2]>, /// Tone value increase at 50 % for C, M, Y, K. pub tvi: [f64; 4], /// Grid points of the AToB (4D) and BToA (3D) tables. @@ -63,6 +71,32 @@ pub struct CmykParams { /// encoding and separates to a trace of ink. Off by default, which keeps the bytes of the /// shipped Photocraft profile. pub white_on_node: bool, + /// How the BToA tables bring colours into the gamut. [`GamutMapping::Legacy`] by default, + /// which keeps the bytes of the shipped Photocraft profile. + pub mapping: GamutMapping, +} + +/// How the BToA tables map colours the printer cannot reach. +#[derive(Clone, Copy, Debug, PartialEq)] +pub enum GamutMapping { + /// The shipped Photocraft profile: out-of-gamut colours land on the closest reachable + /// colour (ΔE76); perceptual scales L* onto the device black and compresses Lab chroma; + /// saturation shares the perceptual table. + Legacy, + /// Gamut mapping in Oklab, whose hue lines stay perceptually constant (a CIELAB hue line + /// from a saturated blue toward grey drifts toward purple; an Oklab one does not): + /// + /// * **Colorimetric**: in-gamut colours separate exactly. An out-of-gamut colour takes the + /// closest colour the printer reaches in Oklab, lightness and hue weighted above chroma, + /// and more so the further outside it is; black is generated from the clipped colour, so + /// inks the clip drives to 100 % stay there. + /// * **Perceptual** and **saturation**: the ICC v4 perceptual reference black is mapped + /// onto the device black linearly in XYZ (as black point compensation does) for neutrals, + /// fading out with Oklab chroma, so greys separate as with colorimetric + BPC and colourful + /// colours keep their lightness. Perceptual then compresses Oklab chroma above `knee` × + /// the gamut boundary into the boundary; saturation scales Oklab chroma by `saturation` + /// and clips as colorimetric does. + Oklab { knee: f64, saturation: f64 }, } impl Default for CmykParams { @@ -74,10 +108,12 @@ impl Default for CmykParams { gcr_start: 0.2, k_max: 0.95, gcr_gamma: 1.1, + gcr_curve: Vec::new(), tvi: [0.14, 0.14, 0.14, 0.17], grid_a2b: 11, grid_b2a: 21, white_on_node: false, + mapping: GamutMapping::Legacy, } } } @@ -189,6 +225,11 @@ impl Forward for TableForward { /// Bounded least-squares solve for C, M, Y given K, minimising ΔE76 to `target`, subject to /// `C + M + Y ≤ limit` (projected Levenberg–Marquardt with a numerical Jacobian). fn solve_cmy(model: &F, target: [f64; 3], k: f64, limit: f64, seeds: &[[f64; 3]]) -> ([f64; 3], f64) { + solve_cmy_by(model, k, limit, seeds, |l| [l[0] - target[0], l[1] - target[1], l[2] - target[2]]) +} + +/// [`solve_cmy`] minimising the norm of `residual(lab)` instead of ΔE76. +fn solve_cmy_by(model: &F, k: f64, limit: f64, seeds: &[[f64; 3]], residual: impl Fn([f64; 3]) -> [f64; 3]) -> ([f64; 3], f64) { let project = |mut x: [f64; 3]| { for _ in 0..4 { for v in &mut x { @@ -208,10 +249,7 @@ fn solve_cmy(model: &F, target: [f64; 3], k: f64, limit: f6 } x }; - let err = |x: [f64; 3]| { - let l = model.lab([x[0], x[1], x[2], k]); - [l[0] - target[0], l[1] - target[1], l[2] - target[2]] - }; + let err = |x: [f64; 3]| residual(model.lab([x[0], x[1], x[2], k])); let norm2 = |e: [f64; 3]| e[0] * e[0] + e[1] * e[1] + e[2] * e[2]; let mut best = ([0.0; 3], f64::INFINITY); for seed in seeds { @@ -281,13 +319,32 @@ fn solve_cmy(model: &F, target: [f64; 3], k: f64, limit: f6 const SEEDS: [[f64; 3]; 5] = [[0.3, 0.3, 0.3], [0.05, 0.05, 0.05], [0.8, 0.8, 0.8], [0.9, 0.2, 0.2], [0.2, 0.9, 0.9]]; +/// Black for a gray component `g` (the smallest of C, M, Y without black). +fn gcr(p: &CmykParams, g: f64) -> f64 { + let Some(first) = p.gcr_curve.first() else { + // The Photocraft profile's curve. + return if g <= p.gcr_start { 0.0 } else { p.k_max * ((g - p.gcr_start) / (1.0 - p.gcr_start)).powf(p.gcr_gamma) }; + }; + let mut k = first[1]; + for w in p.gcr_curve.windows(2) { + let ([g0, k0], [g1, k1]) = (w[0], w[1]); + if g >= g1 { + k = k1; + } else if g > g0 { + k = k0 + (k1 - k0) * (g - g0) / (g1 - g0); + break; + } + } + k.clamp(0.0, 1.0) +} + /// Colorimetric separation of a relative Lab target: GCR black generation then a CMY solve. pub fn separate(model: &F, p: &CmykParams, target: [f64; 3], warm: Option<[f64; 4]>) -> ([f64; 4], f64) { let mut seeds: Vec<[f64; 3]> = warm.map(|w| vec![[w[0], w[1], w[2]]]).unwrap_or_default(); seeds.extend_from_slice(&SEEDS); let (cmy0, _) = solve_cmy(model, target, 0.0, 3.0, &seeds); let g = cmy0[0].min(cmy0[1]).min(cmy0[2]); - let k = if g <= p.gcr_start { 0.0 } else { p.k_max * ((g - p.gcr_start) / (1.0 - p.gcr_start)).powf(p.gcr_gamma) }; + let k = gcr(p, g); let mut seeds2 = vec![[(cmy0[0] - k).max(0.0), (cmy0[1] - k).max(0.0), (cmy0[2] - k).max(0.0)], cmy0]; seeds2.extend_from_slice(&seeds); let (cmy, de) = solve_cmy(model, target, k, (p.tac - k).max(0.0), &seeds2); @@ -389,6 +446,187 @@ impl Gbd { } } +/// ΔE76 under which a separation counts as reaching its target. +const REACH: f64 = 1.5; +/// Oklab chroma beyond any printable colour: the top of the boundary search. +const OKLAB_CHROMA_MAX: f64 = 0.5; +/// Oklab chroma above which the perceptual and saturation tables no longer lift black: they lift +/// neutrals fully, and less the more colourful a colour is. +const LIFT_CHROMA: f64 = 0.1; +/// Weight of lightness and hue against chroma when a colour just outside the gamut is clipped. +const CLIP_WEIGHT: f64 = 1.5; +/// Growth of that weight with the squared share of chroma the clip loses. +const CLIP_WEIGHT_GROWTH: f64 = 200.0; + +// Oklab (Björn Ottosson, 2020): XYZ (D65) → cone response → cube root → Lab-like axes. +const OKLAB_M1: math::Mat3 = + [[0.8189330101, 0.3618667424, -0.1288597137], [0.0329845436, 0.9293118715, 0.0361456387], [0.0482003018, 0.2643662691, 0.6338517070]]; +const OKLAB_M2: math::Mat3 = + [[0.2104542553, 0.7936177850, -0.0040720468], [1.9779984951, -2.4285922050, 0.4505937099], [0.0259040371, 0.7827717662, -0.8086757660]]; +const OKLAB_M1_INV: math::Mat3 = + [[1.2270138511, -0.5577999807, 0.2812561490], [-0.0405801784, 1.1122568696, -0.0716766787], [-0.0763812845, -0.4214819784, 1.5861632204]]; +const OKLAB_M2_INV: math::Mat3 = [[1.0, 0.3963377774, 0.2158037573], [1.0, -0.1055613458, -0.0638541728], [1.0, -0.0894841775, -1.2914855480]]; + +/// The [`GamutMapping::Oklab`] separations of one forward model. +struct OklabMapper<'a, F: Forward + ?Sized> { + model: &'a F, + p: &'a CmykParams, + knee: f64, + saturation: f64, + /// XYZ scale that maps the v4 perceptual reference black onto the device black (the white + /// stays fixed): `v' = a·v + w·(1 − a)`. + black_scale: f64, + to_d65: math::Mat3, + to_d50: math::Mat3, +} + +impl<'a, F: Forward + ?Sized> OklabMapper<'a, F> { + fn new(model: &'a F, p: &'a CmykParams, knee: f64, saturation: f64) -> Self { + let d65 = math::xy_to_xyz(math::D65_XY); + // The darkest neutral the printer reaches. + let (black, _) = separate(model, p, [0.0, 0.0, 0.0], None); + let device = math::lab_to_xyz([model.lab(black)[0], 0.0, 0.0], math::D50)[1]; + let reference = crate::transform::PERCEPTUAL_BLACK[1]; + OklabMapper { + model, + p, + knee, + saturation, + black_scale: (1.0 - device) / (1.0 - reference), + to_d65: math::bradford(math::D50, d65), + to_d50: math::bradford(d65, math::D50), + } + } + + fn oklab(&self, lab: [f64; 3]) -> [f64; 3] { + let xyz = math::apply(&self.to_d65, math::lab_to_xyz(lab, math::D50)); + math::apply(&OKLAB_M2, math::apply(&OKLAB_M1, xyz).map(f64::cbrt)) + } + + fn lab(&self, ok: [f64; 3]) -> [f64; 3] { + let lms = math::apply(&OKLAB_M2_INV, ok).map(|v| v * v * v); + math::xyz_to_lab(math::apply(&self.to_d50, math::apply(&OKLAB_M1_INV, lms)), math::D50) + } + + /// The most chroma (scale of `ok`'s chroma in `[0, top]`) the printer reaches at `ok`'s + /// lightness and hue, and its separation; `None` when even the neutral is out of reach. + fn boundary(&self, ok: [f64; 3], top: f64, warm: Option<[f64; 4]>) -> Option<(f64, [f64; 4])> { + let (grey, d) = separate(self.model, self.p, self.lab([ok[0], 0.0, 0.0]), warm); + if d > REACH { + return None; + } + let (mut lo, mut hi, mut best) = (0.0, top, grey); + for _ in 0..14 { + let mid = 0.5 * (lo + hi); + let (c, d) = separate(self.model, self.p, self.lab([ok[0], ok[1] * mid, ok[2] * mid]), Some(best)); + if d <= REACH { + lo = mid; + best = c; + } else { + hi = mid; + } + } + Some((lo, best)) + } + + /// Colorimetric: exact in gamut; outside, the closest colour the printer reaches in Oklab, + /// lightness and hue weighted above chroma, and more so the further outside the colour is. + fn clip(&self, lab: [f64; 3], warm: Option<[f64; 4]>) -> [f64; 4] { + let (cmyk, de) = separate(self.model, self.p, lab, warm); + if de <= REACH { + return cmyk; + } + let ok = self.oklab(lab); + let c0 = ok[1].hypot(ok[2]); + // Unit vectors along the colour's chroma and hue directions. + let (u, v) = if c0 > 1e-9 { ([ok[1] / c0, ok[2] / c0], [-ok[2] / c0, ok[1] / c0]) } else { ([1.0, 0.0], [0.0, 1.0]) }; + // Lightness and hue errors weighted by `w`, chroma error by 1; scaled by 100 so the + // solver's step tolerances suit it as they suit ΔE76. + let residual = |w: f64| { + move |l: [f64; 3]| { + let o = self.oklab(l); + let (da, db) = (o[1] - ok[1], o[2] - ok[2]); + [100.0 * w * (o[0] - ok[0]), 100.0 * (da * u[0] + db * u[1]), 100.0 * w * (da * v[0] + db * v[1])] + } + }; + let solve = |w: f64, k: f64, from: [f64; 3]| { + let mut seeds = vec![from]; + seeds.extend_from_slice(&SEEDS); + solve_cmy_by(self.model, k, (self.p.tac - k).max(0.0), &seeds, residual(w)).0 + }; + // A first clip without black measures how far outside the colour is. A colour just + // outside may give up a little lightness and hue to keep its chroma (a red reaches the + // full magenta and yellow edge); one far outside keeps its lightness and hue and loses + // chroma (a saturated blue does not slide along the gamut surface). + let first = solve(CLIP_WEIGHT, 0.0, [cmyk[0], cmyk[1], cmyk[2]]); + let o = self.oklab(self.model.lab([first[0], first[1], first[2], 0.0])); + let loss = if c0 > 1e-9 { (1.0 - o[1].hypot(o[2]) / c0).clamp(0.0, 1.0) } else { 0.0 }; + let w = CLIP_WEIGHT * (1.0 + CLIP_WEIGHT_GROWTH * loss * loss); + let free = solve(w, 0.0, first); + let norm = |c: [f64; 4]| residual(w)(self.model.lab(c)).iter().map(|v| v * v).sum::(); + // Candidates, the closest kept: the separation itself (a colour it nearly reaches stays + // continuous with its in-gamut neighbours), the clip with the separation's black, and + // the clip with black generated from the black-free clip's gray component (inks the + // clip drives to 100 % stay there and black replaces the rest). + let mut best = (norm(cmyk), cmyk); + for k in [cmyk[3], gcr(self.p, free[0].min(free[1]).min(free[2]))] { + for from in [[cmyk[0], cmyk[1], cmyk[2]], free] { + let cmy = solve(w, k, from); + let c = [cmy[0], cmy[1], cmy[2], k]; + let n = norm(c); + if n < best.0 { + best = (n, c); + } + } + } + // Near paper white the gamut narrows to a point: the separation's closest colour keeps + // light tints' chroma where holding lightness would drop them toward bare paper, and + // the table nodes there carry the in-gamut tints between them. The inks blend from the + // clip at L* 85 to the separation at L* 95. + let clip_share = ((95.0 - lab[0]) / 10.0).clamp(0.0, 1.0); + std::array::from_fn(|i| clip_share * best.1[i] + (1.0 - clip_share) * cmyk[i]) + } + + /// Maps the v4 perceptual reference black onto the device black, linearly in XYZ, for + /// neutrals; colourful colours keep their lightness. + fn lift_black(&self, lab: [f64; 3]) -> [f64; 3] { + let ok = self.oklab(lab); + let neutral = (1.0 - ok[1].hypot(ok[2]) / LIFT_CHROMA).clamp(0.0, 1.0); + let a = 1.0 - neutral * (1.0 - self.black_scale); + let xyz = math::lab_to_xyz(lab, math::D50); + math::xyz_to_lab(std::array::from_fn(|i| a * xyz[i] + math::D50[i] * (1.0 - a)), math::D50) + } + + fn perceptual(&self, lab: [f64; 3], warm: Option<[f64; 4]>) -> [f64; 4] { + let lab = self.lift_black(lab); + let ok = self.oklab(lab); + let c = ok[1].hypot(ok[2]); + if c < 1e-9 { + return self.clip(lab, warm); + } + let Some((s, edge)) = self.boundary(ok, OKLAB_CHROMA_MAX / c, warm) else { + return self.clip(lab, warm); + }; + // Chroma above the knee is compressed smoothly into the boundary chroma `cb`. + let cb = s * c; + let knee = self.knee * cb; + if c <= knee { + return self.clip(lab, warm); + } + let c2 = knee + (cb - knee) * ((c - knee) / (cb - knee).max(1e-9)).tanh(); + let f = c2 / c; + if f >= s { + return edge; + } + self.clip(self.lab([ok[0], ok[1] * f, ok[2] * f]), Some(edge)) + } + + fn saturation(&self, lab: [f64; 3], warm: Option<[f64; 4]>) -> [f64; 4] { + let ok = self.oklab(self.lift_black(lab)); + self.clip(self.lab([ok[0], ok[1] * self.saturation, ok[2] * self.saturation]), warm) + } +} + fn lab_node_legacy(i: usize, n: usize) -> f64 { i as f64 / (n - 1) as f64 } @@ -425,6 +663,18 @@ fn white_node_curve(l_axis: bool, x: f64) -> f64 { } fn b2a_table(model: &F, p: &CmykParams, gbd: Option<&Gbd>) -> Result { + b2a_table_with(p, |lab, warm| { + let target = match gbd { + Some(g) => g.compress(lab), + None => lab, + }; + separate(model, p, target, warm).0 + }) +} + +/// Samples a BToA table: `node` separates each relative Lab node, warm-started from the +/// previous node along b. +fn b2a_table_with(p: &CmykParams, node: impl Fn([f64; 3], Option<[f64; 4]>) -> [f64; 4] + Sync) -> Result { let n = p.grid_b2a.max(2); let nodes = n * n * n; let step = (n - 1) as f64; @@ -440,11 +690,7 @@ fn b2a_table(model: &F, p: &CmykParams, gbd: Option<&Gbd>) } else { decode_v2([lab_node_legacy(li, n), lab_node_legacy(ai, n), lab_node_legacy(bi, n)]) }; - let target = match gbd { - Some(g) => g.compress(lab), - None => lab, - }; - let (cmyk, _) = if p.white_on_node && lab == [100.0, 0.0, 0.0] { ([0.0; 4], 0.0) } else { separate(model, p, target, warm) }; + let cmyk = if p.white_on_node && lab == [100.0, 0.0, 0.0] { [0.0; 4] } else { node(lab, warm) }; warm = Some(cmyk); out.extend(cmyk.map(|v| v as f32)); } @@ -466,6 +712,15 @@ fn check_grids(p: &CmykParams) -> Result<(), CmsError> { if p.white_on_node && p.grid_b2a.is_multiple_of(2) { return Err(invalid_arg(format!("white on a node needs an odd BToA grid, not {}", p.grid_b2a))); } + let valid = |v: &[f64; 2]| v.iter().all(|x| (0.0..=1.0).contains(x)); + if !p.gcr_curve.iter().all(valid) || p.gcr_curve.windows(2).any(|w| w[1][0] <= w[0][0]) { + return Err(invalid_arg(format!("black generation curve {:?} needs points in [0, 1] with increasing gray components", p.gcr_curve))); + } + if let GamutMapping::Oklab { knee, saturation } = p.mapping + && !((0.0..1.0).contains(&knee) && saturation.is_finite() && saturation > 0.0) + { + return Err(invalid_arg(format!("Oklab gamut mapping needs a knee in [0, 1) and a positive saturation, not {knee} and {saturation}"))); + } Ok(()) } @@ -524,11 +779,23 @@ pub fn cmyk_profile_from_model(model: &F, paper: [f64; 3], } fn lut_profile(model: &F, a2b: Clut, paper: [f64; 3], p: &CmykParams) -> Result { - let gbd = Gbd::new(model, p); - let colorimetric = b2a_table(model, p, None)?; - let perceptual = b2a_table(model, p, Some(&gbd))?; + let (perceptual, colorimetric, saturation) = match p.mapping { + GamutMapping::Legacy => { + let gbd = Gbd::new(model, p); + let colorimetric = b2a_table(model, p, None)?; + let perceptual = b2a_table(model, p, Some(&gbd))?; + (perceptual.clone(), colorimetric, perceptual) + } + GamutMapping::Oklab { knee, saturation } => { + let m = OklabMapper::new(model, p, knee, saturation); + let colorimetric = b2a_table_with(p, |lab, warm| m.clip(lab, warm))?; + let perceptual = b2a_table_with(p, |lab, warm| m.perceptual(lab, warm))?; + let saturation = b2a_table_with(p, |lab, warm| m.saturation(lab, warm))?; + (perceptual, colorimetric, saturation) + } + }; let a2b = lut16(a2b, false); - let (b0, b1) = (lut16(perceptual, p.white_on_node), lut16(colorimetric, p.white_on_node)); + let (b0, b1, b2) = (lut16(perceptual, p.white_on_node), lut16(colorimetric, p.white_on_node), lut16(saturation, p.white_on_node)); Ok(Profile { version: (4, 0x30), class: ProfileClass::Output, @@ -544,7 +811,7 @@ fn lut_profile(model: &F, a2b: Clut, paper: [f64; 3], p: &C trc: None, gray_trc: None, a2b: [Some(a2b.clone()), Some(a2b.clone()), Some(a2b)], - b2a: [Some(b0.clone()), Some(b1), Some(b0)], + b2a: [Some(b0), Some(b1), Some(b2)], bytes: None, hash: Default::default(), } @@ -555,3 +822,48 @@ fn lut_profile(model: &F, a2b: Clut, paper: [f64; 3], p: &C pub fn coated_cmyk() -> Result { cmyk_profile(&CmykParams::default()) } + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn oklab_mapping_refuses_bad_parameters() { + for (knee, saturation) in [(1.0, 1.0), (-0.1, 1.0), (f64::NAN, 1.0), (0.5, 0.0), (0.5, f64::INFINITY), (0.5, f64::NAN)] { + let p = CmykParams { grid_a2b: 2, grid_b2a: 2, mapping: GamutMapping::Oklab { knee, saturation }, ..CmykParams::default() }; + assert!(cmyk_profile(&p).is_err(), "knee {knee}, saturation {saturation}"); + } + } + + #[test] + fn black_generation_curve() { + let p = CmykParams { gcr_curve: vec![[0.0, 0.0], [0.5, 0.2], [1.0, 0.9]], ..CmykParams::default() }; + for (g, k) in [(-1.0, 0.0), (0.0, 0.0), (0.25, 0.1), (0.5, 0.2), (0.75, 0.55), (1.0, 0.9), (2.0, 0.9)] { + assert!((gcr(&p, g) - k).abs() < 1e-12, "g {g}: {} != {k}", gcr(&p, g)); + } + for curve in [vec![[0.5, 0.2], [0.5, 0.3]], vec![[0.5, 0.2], [0.2, 0.3]], vec![[0.0, 1.5]], vec![[f64::NAN, 0.0]]] { + let p = CmykParams { grid_a2b: 2, grid_b2a: 2, gcr_curve: curve.clone(), ..CmykParams::default() }; + assert!(cmyk_profile(&p).is_err(), "{curve:?}"); + } + } + + #[test] + fn oklab_round_trips() { + let m = CmykModel::coated(CmykParams::default().tvi); + let p = CmykParams::default(); + let mapper = OklabMapper::new(&m, &p, 0.65, 1.05); + for lab in [[50.0, 0.0, 0.0], [44.0, 63.7, 47.0], [31.9, 32.9, -76.8], [90.0, -5.0, 80.0]] { + let back = mapper.lab(mapper.oklab(lab)); + // The published matrices carry 10 digits, so the inverses are exact to about 1e-5 ΔE. + assert!(math::delta_e76(lab, back) < 1e-3, "{lab:?} -> {back:?}"); + } + } + + #[test] + fn oklab_profile_has_three_tables() { + let p = CmykParams { grid_a2b: 5, grid_b2a: 5, mapping: GamutMapping::Oklab { knee: 0.65, saturation: 1.05 }, ..CmykParams::default() }; + let profile = cmyk_profile(&p).unwrap(); + let [Some(b0), Some(b1), Some(b2)] = &profile.b2a else { panic!("missing BToA tables") }; + assert!(b0 != b1 && b0 != b2, "perceptual shares a table"); + } +} diff --git a/crates/cms/src/transform.rs b/crates/cms/src/transform.rs index d1a96e3b5..20df3f791 100644 --- a/crates/cms/src/transform.rs +++ b/crates/cms/src/transform.rs @@ -58,7 +58,7 @@ const OUT_TABLE: usize = GpuMatrixShaper::OUTPUT_ENTRIES; const _: () = assert!(OUT_TABLE.is_power_of_two()); /// ICC v4 perceptual reference medium black (ICC.1:2010 §6.3.4.4), XYZ. -const PERCEPTUAL_BLACK: [f64; 3] = [0.00336, 0.0034731, 0.00287]; +pub(crate) const PERCEPTUAL_BLACK: [f64; 3] = [0.00336, 0.0034731, 0.00287]; /// Accelerated representation of a transform. #[derive(Debug)] diff --git a/crates/cms/tests/fogra39.rs b/crates/cms/tests/fogra39.rs index f3c375656..806bff713 100644 --- a/crates/cms/tests/fogra39.rs +++ b/crates/cms/tests/fogra39.rs @@ -12,8 +12,8 @@ //! ([`synth::cmyk_profile_from_model`]). use craft_cms::math::{self, delta_e2000}; -use craft_cms::synth::{self, CmykParams, Forward}; -use craft_cms::{Builtin, Intent, Transform}; +use craft_cms::synth::{self, CmykParams, Forward, GamutMapping}; +use craft_cms::{Builtin, Intent, Profile, Transform}; const DATA: &str = concat!(env!("CARGO_MANIFEST_DIR"), "/tests/data/FOGRA39.txt"); const PROFILE: &str = concat!(env!("CARGO_MANIFEST_DIR"), "/profiles/craft-coated-fogra39.icc"); @@ -336,8 +336,10 @@ fn regen_coated_fogra39() { description: Builtin::CoatedFogra39.description().into(), copyright: craft_cms::builtin::COATED_FOGRA39_COPYRIGHT.into(), tac: 3.3, + gcr_curve: vec![[0.0, 0.0], [0.2, 0.05], [0.5, 0.205], [0.67, 0.5], [1.0, 0.95]], grid_b2a: 33, white_on_node: true, + mapping: GamutMapping::Oklab { knee: 0.65, saturation: 1.05 }, ..CmykParams::default() }; let profile = synth::cmyk_profile_from_model(&f, paper(&p), ¶ms).unwrap(); @@ -381,3 +383,66 @@ fn stand_in_separations_respect_the_ink_limit() { } } } + +/// sRGB patches and their separations by the reference application (Convert to Profile to +/// Coated FOGRA39, dither on), CMYK % per intent: relative + BPC, relative, perceptual, +/// saturation, absolute. Measured for storytold/photocraft#14267. +const REFERENCE_SEPARATIONS: [([u8; 3], [[f32; 4]; 5]); 3] = [ + ( + [200, 30, 30], + [[14.5, 97.7, 95.3, 4.3], [13.3, 100.0, 100.0, 5.5], [18.0, 96.9, 92.9, 8.6], [14.9, 100.0, 100.0, 5.9], [8.6, 100.0, 100.0, 2.4]], + ), + ([30, 60, 200], [[91.8, 75.3, 0.0, 0.0], [94.5, 76.5, 0.0, 0.0], [94.5, 77.7, 0.0, 0.0], [93.7, 76.9, 0.0, 0.0], [92.6, 74.9, 0.0, 0.0]]), + ( + [128, 128, 128], + [[49.0, 38.4, 38.4, 20.0], [49.8, 39.2, 38.8, 21.2], [49.0, 38.4, 38.4, 20.0], [49.0, 38.4, 38.4, 20.0], [46.7, 36.9, 38.4, 18.4]], + ), +]; + +const SEPARATION_INTENTS: [(Intent, bool); 5] = [ + (Intent::RelativeColorimetric, true), + (Intent::RelativeColorimetric, false), + (Intent::Perceptual, true), + (Intent::Saturation, true), + (Intent::AbsoluteColorimetric, false), +]; + +fn fogra39() -> &'static Profile { + let p = Builtin::CoatedFogra39.profile(); + assert_eq!(p.description, Builtin::CoatedFogra39.description(), "the shipped profile parses"); + p +} + +fn separation(intent: Intent, bpc: bool, rgb: [u8; 3]) -> [f32; 4] { + let t = Transform::new(Builtin::Srgb.profile(), fogra39(), intent, bpc).unwrap(); + let mut o = [0.0f32; 4]; + t.eval(&rgb.map(|v| v as f32 / 255.0), &mut o).unwrap(); + o.map(|v| v * 100.0) +} + +/// sRGB → Coated FOGRA39 matches the reference application's inks on a red, a saturated blue +/// and a mid grey for every intent. Most land within 2 % per ink; red at the magenta–yellow +/// edge lands between table nodes that are and are not clipped, which costs up to 2.2 % with +/// the 33³ BToA tables. +#[test] +fn separates_like_the_reference_application() { + let mut worst = 0.0f32; + for (rgb, want) in REFERENCE_SEPARATIONS { + for ((intent, bpc), want) in SEPARATION_INTENTS.into_iter().zip(want) { + let got = separation(intent, bpc, rgb); + let diff = (0..4).map(|i| (got[i] - want[i]).abs()).fold(0.0f32, f32::max); + eprintln!("{rgb:?} {intent:?} bpc {bpc}: {got:.1?} reference {want:?} (max {diff:.1})"); + worst = worst.max(diff); + } + } + assert!(worst <= 2.5, "worst ink difference {worst} %"); +} + +/// Saturation has its own table: a red separates with more magenta and yellow than +/// perceptual, whose chroma compression takes some back. +#[test] +fn saturation_and_perceptual_separate_differently() { + let red = [200, 30, 30]; + let (perceptual, saturation) = (separation(Intent::Perceptual, true, red), separation(Intent::Saturation, true, red)); + assert!(saturation[1] > perceptual[1] + 1.0 && saturation[2] > perceptual[2] + 1.0, "perceptual {perceptual:?}, saturation {saturation:?}"); +} diff --git a/crates/color-transform/Cargo.toml b/crates/color-transform/Cargo.toml new file mode 100644 index 000000000..8b979d4c0 --- /dev/null +++ b/crates/color-transform/Cargo.toml @@ -0,0 +1,21 @@ +[package] +name = "craft-color-transform" +description = "Color transforms for Craft apps: RGB spaces and Bradford adaptation, white balance by temperature and tint, OkLab and OkLCh, monotone tone curves and 1D lookup tables, and BT.2408 PQ tone mapping" +version.workspace = true +edition.workspace = true +license.workspace = true +rust-version.workspace = true +repository.workspace = true + +[lints] +workspace = true + +[dependencies] +# PQ (SMPTE ST 2084), the HDR reference white and the color primaries tags. +craft-color = { workspace = true } +# The 3×3 matrix arithmetic and Bradford adaptation (`craft_cms::math`). +craft-cms = { workspace = true } +serde = { workspace = true } + +[dev-dependencies] +serde_json = { workspace = true } diff --git a/crates/color-transform/README.md b/crates/color-transform/README.md new file mode 100644 index 000000000..967be6a52 --- /dev/null +++ b/crates/color-transform/README.md @@ -0,0 +1,74 @@ +# craft-color-transform + +Color transforms for the Craft apps: RGB spaces and chromatic adaptation, white balance by +temperature and tint, OkLab and OkLCh, monotone tone curves and 1D lookup tables, and PQ tone +mapping. It builds on [`craft-color`](../color), which holds the frame color tags, the Y'CbCr +matrices and the sRGB, PQ and HLG transfer functions. It depends on `craft-color`, `craft-cms` +and `serde`, contains no `unsafe` code, and builds for `wasm32-unknown-unknown`. The per-pixel +functions take `f32` and do not allocate. + +The matrix arithmetic comes from `craft_cms::math`. `Mat3` wraps its row-major `[[f64; 3]; 3]` +and converts to and from it with `From`. `mul`, `apply` and `determinant` call `math::mul`, +`math::apply` and `math::det`, `Mat3::inverse` calls `math::inverse`, `Xy::to_xyz` calls +`math::xy_to_xyz` after checking the chromaticity, `BRADFORD` is `math::BRADFORD`, and +`bradford_xyz` calls `math::bradford_checked`. `math::inverse` divides the matrix by its largest +entry before taking the determinant. `math::invert`, which `craft-cms` uses to validate ICC +matrices, keeps its absolute determinant floor of 1e-12. `RgbSpace::to_xyz` builds the +normalized primary matrix with `math::inverse` rather than with `math::rgb_to_xyz_matrix`, which +inverts with `math::invert`, and returns the identity when the normalized matrix has no inverse. + +Moved from StudioCraft's `craft-color-transform` +([`crates/craft-color-transform`](https://github.com/blamejs/StudioCraft/tree/2abe1824aa0d849faf8d5f91557d68ebe577f495/crates/craft-color-transform)). +Parts of it started in other Craft apps: + +- `cct`, `oklab` and `curve` came from LightCraft's `lightcraft-color` (`crates/color/src/cct.rs`, + `perceptual.rs` and `spline.rs`). `MonotoneCurve` now loads a saved curve through its + constructor, so a file cannot give it arrays of different lengths, and it bounds the points it + keeps and the size of their coordinates. `OkLab::for_space` extends the BT.2020-only OkLab + conversion to any `RgbSpace`. +- `tonemap` came from FilmCraft's `filmcraft-color` (`crates/color/src/transform.rs`, + `bt2390_eetf` and its maxRGB operator). It now follows Report ITU-R BT.2408-8 Annex 5 with + the black lift, passes values through when the target peak is at or above the source peak, + and handles a target peak below a third of the source range (see `Eetf`). + +License: MIT OR Apache-2.0. + +## Contents + +| Item | What it does | Source of the formula | +| --- | --- | --- | +| `Mat3`, `Xy`, `RgbSpace` | 3×3 matrices, CIE 1931 chromaticities, RGB spaces from primaries and a white point. `RgbSpace::to_xyz` is the normalized primary matrix. `RgbSpace::from(craft_color::Primaries)` gives the space of a frame tag. | SMPTE RP 177; primaries from ITU-R BT.709, BT.601, BT.2020 and SMPTE EG 432-1 | +| `bradford`, `bradford_xyz` | The Bradford chromatic adaptation matrix between two whites. `RgbSpace::to_space` converts between spaces with it. | The Bradford cone response matrix | +| `cct::temp_tint_to_xy`, `cct::xy_to_temp_tint` | A white at a correlated color temperature and tint, and back. Tint is Duv × 3000 along the locus normal in CIE 1960 (u, v); positive is towards green. | Kim et al., "Design of Advanced Color Temperature Control System for HDTV Applications", Journal of the Korean Physical Society 41 (2002) | +| `cct::wb_matrix`, `cct::white_balance` | The RGB matrix that makes a scene lit by one white look lit by another. | Bradford adaptation | +| `oklab` | OkLab from linear sRGB with the published matrices, from XYZ, and for any `RgbSpace` (`OkLab::for_space`, with `f32` matrices; `oklab::lms_matrices` gives the same matrices in `f64`); OkLCh. | B. Ottosson, "A perceptual color space for image processing" (2020) | +| `curve::MonotoneCurve` | A tone curve through points that does not overshoot between them. It saves as its list of points. `knots` gives each point with its tangent for evaluation in a shader. | Fritsch and Carlson, "Monotone Piecewise Cubic Interpolation", SIAM J. Numer. Anal. 17 (1980) | +| `curve::Lut1` | A 1D lookup table over 0..1 with linear interpolation. | | +| `tonemap::Eetf` | The reference EETF from a mastering display to a target display, with the black lift, on PQ values or nits. When the target peak is below a third of the source range in PQ, where the Annex's knee would be negative, the knee is 0 and the spline starts with a slope of 3 × maxLum. When minLum is above 0.25, where the Annex's lift minLum × (1 − E2)⁴ would make the output fall near black and raise the peak above the target peak, the lift is minLum × (1 − E2 / r)ᵏ with r = max(T, min(1, 2 − 4 minLum)) and k = min(4, r / minLum), where T is the smaller of maxLum and 1. This equals the Annex's lift up to minLum 0.25, keeps the output rising, changes continuously with the target black, and from minLum 0.5 reaches 0 at the top of the output. A target black above the source peak reads as the source peak. Both rules are the crate's own. | Report ITU-R BT.2408-8, Annex 5 | +| `tonemap::ToneMap` | The EETF applied to linear RGB by max(R, G, B) as a ratio, with 1.0 at the 203-nit reference white. | Report ITU-R BT.2408-8, Annex 5 (the maxRGB option) | + +## Hostile input + +- A chromaticity with `y` at or below 0, or with a coordinate that is not finite, is rejected by + `Xy::to_xyz`. `bradford` then returns the identity, and so does `RgbSpace::to_xyz` for such a + white, for collinear primaries and for a white that gives a primary no weight. `Mat3::inverse` + and `bradford_xyz` return `None` or the identity instead of a matrix with entries beyond + `f64`. +- Temperatures are clamped to 1000 K to 100 000 K, and NaN reads as 6500 K. A tint that is not + finite reads as 0. +- `MonotoneCurve` keeps at most 1024 points and drops points with a coordinate that is not + finite or is beyond ±1e6. A saved curve is read back through the same constructor, so a file + cannot give it mismatched arrays. +- `Lut1::from_fn` and `MonotoneCurve::to_lut` build at most 65 536 entries. +- Luminances are clamped to 0..10 000 nits. A target peak that is NaN or not above 0 gives an + EETF and a `ToneMap` that pass values through. + +## Tests + +`cargo test -p craft-color-transform` checks the code against published values: the sRGB matrix of +IEC 61966-2-1, the BT.709 and BT.2020 luminance weights, the BT.709 to BT.2020 matrix of +ITU-R BT.2087, the D65 to D50 Bradford matrix as Lindbloom's chromatic adaptation page prints it, +illuminant A and D65 from CIE 15:2004 (temperature, Duv, CIE 1960 coordinates), Ottosson's XYZ to +OkLab table, the OkLab value CSS Color Module Level 4 gives for `#7654CD`, the PQ levels of +BT.2408, and EETF values computed from the BT.2408 Annex 5 equations by a separate +implementation. diff --git a/crates/color-transform/src/cct.rs b/crates/color-transform/src/cct.rs new file mode 100644 index 000000000..1f81cdb19 --- /dev/null +++ b/crates/color-transform/src/cct.rs @@ -0,0 +1,243 @@ +//! Correlated color temperature, tint and white balance. +//! +//! The Planckian locus is the cubic approximation of Kim et al., "Design of Advanced Color +//! Temperature Control System for HDTV Applications", Journal of the Korean Physical Society 41 +//! (2002), over 1667 K to 25000 K. Outside that range the locus continues as a straight line in +//! mired (10⁶ / K) from the end of the approximation. Temperatures are clamped to +//! [`MIN_TEMPERATURE`] to [`MAX_TEMPERATURE`]. +//! +//! Tint is a signed distance from the locus in CIE 1960 (u, v), along the locus normal, in units +//! of 1/[`TINT_SCALE`] of Duv. A positive tint is a white above the locus (towards green), so the +//! correction that removes it adds magenta; a negative tint is a white below the locus. + +use crate::{Mat3, RgbSpace, Xy, bradford}; + +/// Tint units per unit of Duv. +pub const TINT_SCALE: f64 = 3000.0; +/// The lowest temperature the approximation covers, in kelvin. +pub const KIM_MIN: f64 = 1667.0; +/// The highest temperature the approximation covers, in kelvin. +pub const KIM_MAX: f64 = 25000.0; +/// The lowest temperature the functions here take. +pub const MIN_TEMPERATURE: f64 = 1000.0; +/// The highest temperature the functions here take. +pub const MAX_TEMPERATURE: f64 = 100_000.0; + +fn kim_xy(t: f64) -> Xy { + let t = t.clamp(KIM_MIN, KIM_MAX); + let (t2, t3) = (t * t, t * t * t); + let x = if t <= 4000.0 { + -0.2661239e9 / t3 - 0.2343589e6 / t2 + 0.8776956e3 / t + 0.179910 + } else { + -3.0258469e9 / t3 + 2.1070379e6 / t2 + 0.2226347e3 / t + 0.240390 + }; + let (x2, x3) = (x * x, x * x * x); + let y = if t <= 2222.0 { + -1.1063814 * x3 - 1.34811020 * x2 + 2.18555832 * x - 0.20219683 + } else if t <= 4000.0 { + -0.9549476 * x3 - 1.37418593 * x2 + 2.09137015 * x - 0.16748867 + } else { + 3.0817580 * x3 - 5.87338670 * x2 + 3.75112997 * x - 0.37001483 + }; + Xy::new(x, y) +} + +/// CIE 1931 xy to CIE 1960 (u, v). +pub fn xy_to_uv(p: Xy) -> (f64, f64) { + let d = -2.0 * p.x + 12.0 * p.y + 3.0; + (4.0 * p.x / d, 6.0 * p.y / d) +} + +/// CIE 1960 (u, v) to CIE 1931 xy. +pub fn uv_to_xy(u: f64, v: f64) -> Xy { + let d = 2.0 * u - 8.0 * v + 4.0; + Xy::new(3.0 * u / d, 2.0 * v / d) +} + +/// A temperature in range: NaN reads as 6500 K. +fn sane_temperature(t: f64) -> f64 { + if t.is_nan() { 6500.0 } else { t.clamp(MIN_TEMPERATURE, MAX_TEMPERATURE) } +} + +/// The locus in (u, v) at `t` kelvin. +fn locus_uv(t: f64) -> (f64, f64) { + if (KIM_MIN..=KIM_MAX).contains(&t) { + return xy_to_uv(kim_xy(t)); + } + let (a, b) = if t < KIM_MIN { (KIM_MIN, KIM_MIN + 50.0) } else { (KIM_MAX - 500.0, KIM_MAX) }; + let (ua, va) = xy_to_uv(kim_xy(a)); + let (ub, vb) = xy_to_uv(kim_xy(b)); + let (ma, mb, m) = (1e6 / a, 1e6 / b, 1e6 / t); + let s = (m - ma) / (mb - ma); + (ua + (ub - ua) * s, va + (vb - va) * s) +} + +/// The unit normal of the locus at `t`, pointing towards green (increasing v). +fn locus_normal(t: f64) -> (f64, f64) { + let m = 1e6 / t; + let (u0, v0) = locus_uv(1e6 / (m + 1.0)); + let (u1, v1) = locus_uv(1e6 / (m - 1.0).max(1.0)); + let (du, dv) = (u1 - u0, v1 - v0); + let l = du.hypot(dv).max(1e-12); + let (nx, ny) = (-dv / l, du / l); + if ny < 0.0 { (-nx, -ny) } else { (nx, ny) } +} + +/// The chromaticity of a white at temperature `t` (kelvin) and `tint`. A NaN tint reads as 0. +pub fn temp_tint_to_xy(t: f64, tint: f64) -> Xy { + let t = sane_temperature(t); + let tint = if tint.is_finite() { tint } else { 0.0 }; + let (u, v) = locus_uv(t); + let (nu, nv) = locus_normal(t); + let duv = tint / TINT_SCALE; + uv_to_xy(u + nu * duv, v + nv * duv) +} + +/// The temperature and tint of a white: the nearest point on the locus, searched in mired, and +/// the signed distance from it. The inverse of [`temp_tint_to_xy`] over its range. A +/// chromaticity with no (u, v) coordinates (NaN, or on the line where their denominator is 0) +/// reads as 6500 K with no tint. +pub fn xy_to_temp_tint(p: Xy) -> (f64, f64) { + let (u, v) = xy_to_uv(p); + if !(u.is_finite() && v.is_finite()) { + return (6500.0, 0.0); + } + let dist = |m: f64| { + let (lu, lv) = locus_uv(1e6 / m); + (u - lu).powi(2) + (v - lv).powi(2) + }; + let (lo, hi) = (1e6 / MAX_TEMPERATURE, 1e6 / MIN_TEMPERATURE); + // A scan every 5 mired, then a golden-section search around the best step. + let mut best = lo; + let mut best_d = f64::MAX; + let mut m = lo; + while m <= hi { + let d = dist(m); + if d < best_d { + best_d = d; + best = m; + } + m += 5.0; + } + let (mut a, mut b) = ((best - 5.0).max(lo), (best + 5.0).min(hi)); + let g = 0.618_033_988_75; + for _ in 0..60 { + let c = b - g * (b - a); + let d = a + g * (b - a); + if dist(c) < dist(d) { b = d } else { a = c } + } + let t = 1e6 / ((a + b) / 2.0); + let (lu, lv) = locus_uv(t); + let (nu, nv) = locus_normal(t); + (t, ((u - lu) * nu + (v - lv) * nv) * TINT_SCALE) +} + +/// The matrix (linear RGB in `space` to the same space) that makes a scene lit by a white at +/// `src` look as if it were lit by the space's own white (Bradford adaptation). +pub fn wb_matrix(space: &RgbSpace, src: Xy) -> Mat3 { + space.from_xyz().mul(&bradford(src, space.white)).mul(&space.to_xyz()) +} + +/// The matrix (linear RGB in `space` to the same space) that makes a scene lit by a white at +/// temperature and tint `from` look as if it were lit by the white at `to`. Equal settings give +/// the identity. A lower `from` temperature than `to` cools the picture. +pub fn white_balance(space: &RgbSpace, from: (f64, f64), to: (f64, f64)) -> Mat3 { + let (src, dst) = (temp_tint_to_xy(from.0, from.1), temp_tint_to_xy(to.0, to.1)); + if src == dst { + return Mat3::IDENTITY; + } + space.from_xyz().mul(&bradford(src, dst)).mul(&space.to_xyz()) +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::{D65, REC2020, SRGB}; + + /// CIE 15:2004 gives illuminant A (a Planckian radiator at 2856 K) as x = 0.44757, + /// y = 0.40745. The cubic approximation lands within 0.001 Duv of it. + #[test] + fn illuminant_a_lies_on_the_locus() { + let (u, v) = xy_to_uv(temp_tint_to_xy(2856.0, 0.0)); + let (ua, va) = xy_to_uv(Xy::new(0.44757, 0.40745)); + assert!((u - ua).hypot(v - va) < 1e-3, "{u} {v}"); + let (t, _) = xy_to_temp_tint(Xy::new(0.44757, 0.40745)); + assert!((t - 2856.0).abs() < 15.0, "{t}"); + } + + /// CIE 15:2004 gives D65 a correlated color temperature of 6504 K; it lies above the locus + /// by a Duv of about 0.0032. + #[test] + fn d65_reads_as_6504_k_above_the_locus() { + let (t, tint) = xy_to_temp_tint(D65); + assert!((t - 6504.0).abs() < 15.0, "{t}"); + assert!((tint / TINT_SCALE - 0.0032).abs() < 3e-4, "{tint}"); + } + + /// D65 in CIE 1960 UCS is (0.1978, 0.3122). + #[test] + fn uv_matches_cie_1960_for_d65() { + let (u, v) = xy_to_uv(D65); + assert!((u - 0.1978).abs() < 1e-4 && (v - 0.3122).abs() < 1e-4, "{u} {v}"); + let back = uv_to_xy(u, v); + assert!((back.x - D65.x).abs() < 1e-12 && (back.y - D65.y).abs() < 1e-12); + } + + #[test] + fn temperature_and_tint_round_trip() { + for t in [1200.0, 2000.0, 2856.0, 4000.0, 5003.0, 6500.0, 9000.0, 15000.0, 30000.0, 50000.0] { + for tint in [-100.0, -20.0, 0.0, 35.0, 150.0] { + let (t2, tint2) = xy_to_temp_tint(temp_tint_to_xy(t, tint)); + assert!((t2 - t).abs() / t < 0.01, "{t} {tint} -> {t2}"); + assert!((tint2 - tint).abs() < 1.0, "{t} {tint} -> {tint2}"); + } + } + } + + #[test] + fn warmer_whites_are_redder_and_positive_tint_is_greener() { + assert!(temp_tint_to_xy(3000.0, 0.0).x > temp_tint_to_xy(9000.0, 0.0).x); + let (_, v0) = xy_to_uv(temp_tint_to_xy(5000.0, 0.0)); + let (_, v1) = xy_to_uv(temp_tint_to_xy(5000.0, 50.0)); + assert!(v1 > v0); + } + + #[test] + fn wb_matrix_maps_the_source_white_to_neutral() { + let src = temp_tint_to_xy(3200.0, 10.0); + let m = wb_matrix(&REC2020, src); + let out = m.apply(REC2020.from_xyz().apply(src.to_xyz().unwrap())); + assert!((out[0] - out[1]).abs() < 1e-9 && (out[1] - out[2]).abs() < 1e-9, "{out:?}"); + } + + #[test] + fn white_balance_is_the_identity_for_equal_settings_and_cools_a_warm_light() { + assert_eq!(white_balance(&SRGB, (6500.0, 0.0), (6500.0, 0.0)), Mat3::IDENTITY); + // Light at 3200 K made to look like 6500 K: a white surface lit by it turns neutral. + let m = white_balance(&SRGB, (3200.0, 0.0), (6500.0, 0.0)); + let gray = m.apply([1.0, 1.0, 1.0]); + assert!(gray[2] > gray[0], "{gray:?}"); + let lit = SRGB.from_xyz().apply(temp_tint_to_xy(3200.0, 0.0).to_xyz().unwrap()); + let lit6500 = SRGB.from_xyz().apply(temp_tint_to_xy(6500.0, 0.0).to_xyz().unwrap()); + let out = m.apply(lit); + for i in 0..3 { + assert!((out[i] - lit6500[i]).abs() < 1e-9, "{out:?} {lit6500:?}"); + } + } + + #[test] + fn hostile_temperatures_stay_finite() { + for t in [f64::NAN, f64::INFINITY, f64::NEG_INFINITY, 0.0, -5.0, 1e300] { + for tint in [f64::NAN, f64::INFINITY, 0.0] { + let p = temp_tint_to_xy(t, tint); + assert!(p.x.is_finite() && p.y.is_finite(), "{t} {tint} {p:?}"); + let m = white_balance(&SRGB, (t, tint), (6500.0, 0.0)); + assert!(m.0.iter().flatten().all(|v| v.is_finite()), "{t} {tint}"); + } + } + // -2x + 12y + 3 = 0 at (1.5, 0): the (u, v) denominator. + for p in [Xy::new(f64::NAN, f64::NAN), Xy::new(1.5, 0.0), Xy::new(f64::INFINITY, 0.3)] { + assert_eq!(xy_to_temp_tint(p), (6500.0, 0.0), "{p:?}"); + } + } +} diff --git a/crates/color-transform/src/curve.rs b/crates/color-transform/src/curve.rs new file mode 100644 index 000000000..cdf135cd5 --- /dev/null +++ b/crates/color-transform/src/curve.rs @@ -0,0 +1,421 @@ +//! Tone curves: monotone cubic Hermite splines and 1D lookup tables. +//! +//! [`MonotoneCurve`] interpolates its points with the tangents of F. N. Fritsch and R. E. +//! Carlson, "Monotone Piecewise Cubic Interpolation", SIAM Journal on Numerical Analysis 17 +//! (1980): between two points the curve does not overshoot, so a curve whose points rise never +//! falls. + +use std::fmt; + +use serde::de::{IgnoredAny, SeqAccess, Visitor}; +use serde::{Deserialize, Deserializer, Serialize}; + +/// The most points a [`MonotoneCurve`] keeps; points past it are ignored. +pub const MAX_POINTS: usize = 1024; +/// The largest coordinate a [`MonotoneCurve`] point may have; points farther out are dropped. +pub const MAX_COORDINATE: f64 = 1e6; + +/// A curve through points in `0..1 × 0..1` (any finite values work). It is saved as its points. +#[derive(Clone, Debug, PartialEq, Serialize)] +#[serde(into = "Vec<(f64, f64)>")] +pub struct MonotoneCurve { + xs: Vec, + ys: Vec, + ms: Vec, +} + +impl From> for MonotoneCurve { + fn from(points: Vec<(f64, f64)>) -> MonotoneCurve { + MonotoneCurve::new(&points) + } +} + +/// Reads a saved list of points, keeping the first [`MAX_POINTS`] and skipping the rest +/// without storing them. +impl<'de> Deserialize<'de> for MonotoneCurve { + fn deserialize>(d: D) -> Result { + struct Points; + impl<'de> Visitor<'de> for Points { + type Value = MonotoneCurve; + fn expecting(&self, f: &mut fmt::Formatter) -> fmt::Result { + f.write_str("a list of [x, y] points") + } + fn visit_seq>(self, mut seq: A) -> Result { + let mut p = Vec::with_capacity(seq.size_hint().unwrap_or(0).min(MAX_POINTS)); + while p.len() < MAX_POINTS { + match seq.next_element::<(f64, f64)>()? { + Some(q) => p.push(q), + None => return Ok(MonotoneCurve::new(&p)), + } + } + while seq.next_element::()?.is_some() {} + Ok(MonotoneCurve::new(&p)) + } + } + d.deserialize_seq(Points) + } +} + +impl From for Vec<(f64, f64)> { + fn from(c: MonotoneCurve) -> Vec<(f64, f64)> { + c.points() + } +} + +impl MonotoneCurve { + /// A curve through `points`, sorted by x. Points with a coordinate that is not finite or is + /// beyond ±[`MAX_COORDINATE`] are dropped, and of points closer than 1e-9 in x the first is + /// kept. Fewer than two points give the identity. + pub fn new(points: &[(f64, f64)]) -> MonotoneCurve { + let ok = |v: f64| v.is_finite() && v.abs() <= MAX_COORDINATE; + let mut p: Vec<(f64, f64)> = points.iter().take(MAX_POINTS).copied().filter(|(x, y)| ok(*x) && ok(*y)).collect(); + p.sort_by(|a, b| a.0.total_cmp(&b.0)); + p.dedup_by(|a, b| (a.0 - b.0).abs() < 1e-9); + if p.len() < 2 { + p = vec![(0.0, 0.0), (1.0, 1.0)]; + } + let n = p.len(); + let xs: Vec = p.iter().map(|q| q.0).collect(); + let ys: Vec = p.iter().map(|q| q.1).collect(); + let d: Vec = xs.windows(2).zip(ys.windows(2)).map(|(x, y)| (y[1] - y[0]) / (x[1] - x[0])).collect(); + let mut ms = vec![0.0; n]; + ms[0] = d[0]; + ms[n - 1] = d[n - 2]; + for i in 1..n - 1 { + ms[i] = if d[i - 1] * d[i] <= 0.0 { 0.0 } else { (d[i - 1] + d[i]) / 2.0 }; + } + // The Fritsch–Carlson limit: tangents inside the circle of radius 3 keep each segment + // monotone. The length of (m₀, m₁) is compared with 3·|d|, which stays finite when the + // secant d is subnormal. + for i in 0..n - 1 { + if d[i] == 0.0 { + ms[i] = 0.0; + ms[i + 1] = 0.0; + continue; + } + let r = ms[i].hypot(ms[i + 1]); + let limit = 3.0 * d[i].abs(); + if r > limit { + ms[i] = ms[i] / r * limit; + ms[i + 1] = ms[i + 1] / r * limit; + } + } + MonotoneCurve { xs, ys, ms } + } + + pub fn identity() -> MonotoneCurve { + MonotoneCurve::new(&[(0.0, 0.0), (1.0, 1.0)]) + } + + /// Whether the curve maps every value in `0..1` to itself. A curve whose points do not + /// reach 0 and 1 is not the identity, since it clamps outside them. + pub fn is_identity(&self) -> bool { + let covers = self.xs.first().is_some_and(|x| *x <= 0.0) && self.xs.last().is_some_and(|x| *x >= 1.0); + covers && self.xs.iter().zip(&self.ys).all(|(x, y)| x == y) && self.ms.iter().all(|m| *m == 1.0) + } + + /// The curve at `x`. Below the first point it is the first point's y, above the last the + /// last's. NaN gives NaN. + pub fn eval(&self, x: f64) -> f64 { + if x.is_nan() { + return x; + } + let n = self.xs.len(); + if x <= self.xs[0] { + return self.ys[0]; + } + if x >= self.xs[n - 1] { + return self.ys[n - 1]; + } + let i = match self.xs.binary_search_by(|v| v.total_cmp(&x)) { + Ok(i) => return self.ys[i], + Err(i) => i - 1, + }; + hermite(self.xs[i], self.ys[i], self.ms[i], self.xs[i + 1], self.ys[i + 1], self.ms[i + 1], x) + } + + /// The curve sampled at `n` evenly spaced points over `0..1` (at least 2). + pub fn to_lut(&self, n: usize) -> Lut1 { + let n = n.clamp(2, MAX_LUT); + Lut1 { v: (0..n).map(|i| self.eval(i as f64 / (n - 1) as f64) as f32).collect() } + } + + /// The points, sorted by x. + pub fn points(&self) -> Vec<(f64, f64)> { + self.xs.iter().copied().zip(self.ys.iter().copied()).collect() + } + + /// Each point as `[x, y, tangent]`, for code that evaluates the same spline elsewhere (a + /// GPU pass): between points `k` and `k + 1`, with `h = x₁ − x₀` and `t = (x − x₀) / h`, + /// the curve is `(2t³ − 3t² + 1) y₀ + (t³ − 2t² + t) h m₀ + (−2t³ + 3t²) y₁ + (t³ − t²) h m₁`. + pub fn knots(&self) -> impl ExactSizeIterator + '_ { + self.xs.iter().zip(&self.ys).zip(&self.ms).map(|((x, y), m)| [*x, *y, *m]) + } +} + +fn hermite(x0: f64, y0: f64, m0: f64, x1: f64, y1: f64, m1: f64, x: f64) -> f64 { + let h = x1 - x0; + let t = (x - x0) / h; + let (t2, t3) = (t * t, t * t * t); + (2.0 * t3 - 3.0 * t2 + 1.0) * y0 + (t3 - 2.0 * t2 + t) * h * m0 + (-2.0 * t3 + 3.0 * t2) * y1 + (t3 - t2) * h * m1 +} + +/// The most entries [`Lut1::from_fn`] and [`MonotoneCurve::to_lut`] build. +pub const MAX_LUT: usize = 1 << 16; + +/// A 1D lookup table over `0..1` with linear interpolation. Inputs outside `0..1` clamp. +#[derive(Clone, Debug, PartialEq)] +pub struct Lut1 { + pub v: Vec, +} + +impl Lut1 { + /// The identity with `n` entries (2 to [`MAX_LUT`]). + pub fn identity(n: usize) -> Lut1 { + Lut1::from_fn(n, |x| x) + } + + /// `f` sampled at `n` evenly spaced points over `0..1` (2 to [`MAX_LUT`]). + pub fn from_fn(n: usize, f: impl Fn(f32) -> f32) -> Lut1 { + let n = n.clamp(2, MAX_LUT); + Lut1 { v: (0..n).map(|i| f(i as f32 / (n - 1) as f32)).collect() } + } + + /// The table at `x`. `v` is public, so a table of 1 entry reads as that constant and an + /// empty one as the identity. + #[inline] + pub fn eval(&self, x: f32) -> f32 { + let x = x.clamp(0.0, 1.0); + let n = self.v.len(); + if n < 2 { + return self.v.first().copied().unwrap_or(x); + } + let f = x * (n - 1) as f32; + let i = (f as usize).min(n - 2); + let t = f64::from(f - i as f32); + // Weighted in f64, so entries as far apart as ±f32::MAX do not overflow, and t = 0 and + // t = 1 give the entries exactly. + (f64::from(self.v[i]) * (1.0 - t) + f64::from(self.v[i + 1]) * t) as f32 + } + + /// `self ∘ inner`: `inner` applies first. An empty `inner` is the identity, so the result + /// is `self`. The result is sampled on the densest grid of at most [`MAX_LUT`] entries that + /// holds the sample points of both tables. Between two grid points it differs from + /// `self.eval(inner.eval(x))` by at most one grid step times the product of the two + /// tables' steepest slopes. When no grid of that size holds both tables' points, the result + /// uses the longer table's grid, with the same bound for that grid's step: a table whose + /// slope is near its entry count can then lose the other table's knots between two samples. + pub fn compose(&self, inner: &Lut1) -> Lut1 { + if inner.v.is_empty() { + return self.clone(); + } + let on_inner = || Lut1 { v: inner.v.iter().map(|&x| self.eval(x)).collect() }; + let resampled = |n: usize| Lut1::from_fn(n, |x| self.eval(inner.eval(x))); + let (a, b) = (inner.v.len() - 1, self.v.len().saturating_sub(1)); + if a == 0 || b == 0 { + return on_inner(); + } + let common = (a / gcd(a, b)).checked_mul(b).filter(|l| *l < MAX_LUT); + let steps = common.map(|l| (MAX_LUT - 1) / l * l); + match steps { + Some(s) if s == a => on_inner(), + Some(s) => resampled(s + 1), + None if inner.v.len() >= self.v.len() => on_inner(), + None => resampled(self.v.len()), + } + } + + pub fn is_identity(&self) -> bool { + let n = self.v.len(); + n >= 2 && self.v.iter().enumerate().all(|(i, &y)| (y - i as f32 / (n - 1) as f32).abs() < 1e-6) + } +} + +fn gcd(mut a: usize, mut b: usize) -> usize { + while b != 0 { + (a, b) = (b, a % b); + } + a +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn the_identity_curve_maps_every_value_to_itself() { + let c = MonotoneCurve::identity(); + assert!(c.is_identity()); + for i in 0..=10 { + let x = i as f64 / 10.0; + assert!((c.eval(x) - x).abs() < 1e-12); + } + assert!(c.to_lut(256).is_identity()); + assert!(!MonotoneCurve::new(&[(0.0, 0.0), (0.5, 0.6), (1.0, 1.0)]).is_identity()); + // These points lie on the diagonal, but the curve clamps below 0.2 and above 0.8. + let inner = MonotoneCurve::new(&[(0.2, 0.2), (0.8, 0.8)]); + assert_eq!(inner.eval(0.0), 0.2); + assert!(!inner.is_identity()); + assert!(MonotoneCurve::new(&[(-1.0, -1.0), (2.0, 2.0)]).is_identity()); + } + + #[test] + fn the_curve_passes_through_its_points_and_rises_with_them() { + let pts = [(0.0, 0.0), (0.25, 0.15), (0.5, 0.5), (0.75, 0.88), (1.0, 1.0)]; + let c = MonotoneCurve::new(&pts); + for (x, y) in pts { + assert!((c.eval(x) - y).abs() < 1e-12); + } + let mut prev = -1.0; + for i in 0..=1000 { + let y = c.eval(i as f64 / 1000.0); + assert!(y >= prev - 1e-12); + prev = y; + } + } + + /// Data that rise, then stay level: a natural cubic spline overshoots the level part, and + /// this curve stays on it. + #[test] + fn the_curve_does_not_overshoot_a_level_run() { + let c = MonotoneCurve::new(&[(0.0, 0.0), (0.4, 0.5), (0.6, 0.5), (1.0, 1.0)]); + for i in 400..=600 { + let y = c.eval(i as f64 / 1000.0); + assert!((y - 0.5).abs() < 1e-9, "{y}"); + } + } + + /// Steep and shallow neighbors: the unlimited average tangent overshoots, the limited one + /// keeps the segment within its end values. + #[test] + fn steep_steps_stay_monotone() { + let c = MonotoneCurve::new(&[(0.0, 0.0), (0.1, 0.0), (0.2, 1.0), (1.0, 1.0)]); + let mut prev = -1.0; + for i in 0..=1000 { + let y = c.eval(i as f64 / 1000.0); + assert!((0.0..=1.0).contains(&y) && y >= prev - 1e-12, "{i} {y}"); + prev = y; + } + } + + #[test] + fn the_knots_evaluate_to_the_same_curve() { + let c = MonotoneCurve::new(&[(0.0, 0.1), (0.3, 0.2), (0.7, 0.9), (1.0, 0.95)]); + let k: Vec<[f64; 3]> = c.knots().collect(); + assert_eq!(k.len(), 4); + for i in 0..=100 { + let x = i as f64 / 100.0; + let seg = k.windows(2).find(|w| x >= w[0][0] && x <= w[1][0]).unwrap(); + let y = hermite(seg[0][0], seg[0][1], seg[0][2], seg[1][0], seg[1][1], seg[1][2], x); + assert!((y - c.eval(x)).abs() < 1e-12, "{x}"); + } + } + + #[test] + fn luts_compose() { + let a = Lut1::from_fn(1024, |x| x * x); + let b = Lut1::from_fn(1024, f32::sqrt); + assert!((a.compose(&b).eval(0.3) - 0.3).abs() < 2e-3); + assert_eq!(a.compose(&Lut1 { v: vec![] }), a); + } + + /// A short `inner` does not drop the outer table's points between its own. + #[test] + fn composing_with_a_short_table_keeps_the_outer_curve() { + let peak = Lut1 { v: vec![0.0, 1.0, 0.0] }; + let c = peak.compose(&Lut1::identity(2)); + assert_eq!(c.eval(0.5), 1.0); + assert_eq!(c.eval(0.0), 0.0); + assert_eq!(c.eval(1.0), 0.0); + assert_eq!(peak.compose(&Lut1 { v: vec![0.5] }).eval(0.2), 1.0); + // Grids that do not hold each other's points, and inner tables that cross the outer + // peak between their own points. + let cases = [ + (Lut1::identity(4), peak.clone()), + (Lut1 { v: vec![0.0, 1.0, 0.0, 1.0] }, peak.clone()), + (peak.clone(), Lut1::identity(4)), + (peak.clone(), peak.clone()), + (peak.clone(), Lut1 { v: vec![0.0, 0.75] }), + (Lut1::from_fn(17, |x| (x * 9.0).sin().abs()), Lut1::from_fn(9, |x| x * x)), + ]; + for (outer, inner) in &cases { + let c = outer.compose(inner); + for i in 0..=3000 { + let x = i as f32 / 3000.0; + let want = outer.eval(inner.eval(x)); + assert!((c.eval(x) - want).abs() < 1e-3, "{outer:?} {inner:?} {x}"); + } + } + assert!((peak.compose(&Lut1 { v: vec![0.0, 0.75] }).eval(2.0 / 3.0) - 1.0).abs() < 1e-3); + // A grid beyond MAX_LUT entries falls back to the longer table's grid. + let big = Lut1::identity(MAX_LUT - 1).compose(&Lut1::identity(MAX_LUT)); + assert_eq!(big.v.len(), MAX_LUT); + } + + /// Entries this far apart overflow a difference taken between them. + #[test] + fn far_apart_entries_interpolate_without_overflow() { + let wide = Lut1 { v: vec![-f32::MAX, f32::MAX] }; + assert_eq!(wide.eval(0.0), -f32::MAX); + assert_eq!(wide.eval(1.0), f32::MAX); + assert_eq!(wide.eval(0.5), 0.0); + assert!(wide.eval(0.25).is_finite()); + let high = Lut1 { v: vec![f32::MAX, f32::MAX] }; + assert_eq!(high.eval(0.3), f32::MAX); + } + + #[test] + fn a_curve_saves_as_its_points_and_a_hostile_file_does_not_break_it() { + let c = MonotoneCurve::new(&[(0.0, 0.0), (0.5, 0.7), (1.0, 1.0)]); + let json = serde_json::to_string(&c).unwrap(); + assert_eq!(json, "[[0.0,0.0],[0.5,0.7],[1.0,1.0]]"); + assert_eq!(serde_json::from_str::(&json).unwrap(), c); + // A single point, unsorted points and duplicates load as a working curve. + assert!(serde_json::from_str::("[[0.5,0.5]]").unwrap().is_identity()); + let messy: MonotoneCurve = serde_json::from_str("[[1.0,1.0],[0.0,0.0],[0.0,0.3],[0.5,0.2]]").unwrap(); + assert_eq!(messy.points(), vec![(0.0, 0.0), (0.5, 0.2), (1.0, 1.0)]); + // The fields are not read from a file, so their lengths always agree. + assert!(serde_json::from_str::(r#"{"xs":[0.0],"ys":[],"ms":[]}"#).is_err()); + // A long list keeps its first MAX_POINTS points. + let long: Vec<(f64, f64)> = (0..3000).map(|i| (f64::from(i) / 3000.0, f64::from(i) / 3000.0)).collect(); + let loaded: MonotoneCurve = serde_json::from_str(&serde_json::to_string(&long).unwrap()).unwrap(); + assert_eq!(loaded.points().len(), MAX_POINTS); + assert_eq!(loaded.points()[MAX_POINTS - 1], long[MAX_POINTS - 1]); + } + + #[test] + fn nan_input_and_short_or_huge_tables_do_not_panic() { + let c = MonotoneCurve::new(&[(0.0, 0.0), (0.5, 0.6), (1.0, 1.0)]); + assert!(c.eval(f64::NAN).is_nan()); + assert!(c.eval(-f64::NAN).is_nan()); + assert_eq!(c.eval(-3.0), 0.0); + assert_eq!(c.eval(9.0), 1.0); + for n in [0, 1] { + assert_eq!(c.to_lut(n).v.len(), 2, "{n}"); + assert!(Lut1::identity(n).is_identity(), "{n}"); + } + assert_eq!(Lut1::from_fn(usize::MAX, |x| x).v.len(), MAX_LUT); + assert_eq!(Lut1 { v: vec![] }.eval(0.3), 0.3); + assert_eq!(Lut1 { v: vec![] }.eval(-1.0), 0.0); + assert_eq!(Lut1 { v: vec![0.7] }.eval(0.3), 0.7); + assert!(!Lut1 { v: vec![0.0] }.is_identity()); + let many: Vec<(f64, f64)> = (0..5000).map(|i| (i as f64, i as f64)).collect(); + assert_eq!(MonotoneCurve::new(&many).points().len(), MAX_POINTS); + let bad = MonotoneCurve::new(&[(f64::NAN, 0.0), (0.2, f64::INFINITY), (0.5, 0.5)]); + assert!(bad.is_identity()); + // Differences between these would overflow to infinity and give NaN slopes. + let far = MonotoneCurve::new(&[(-1e308, -1e308), (0.5, 0.25), (1e308, 1e308)]); + assert!(far.is_identity()); + let wide = MonotoneCurve::new(&[(-1e6, -1e6), (1e6, 1e6), (0.0, 0.5)]); + assert!(wide.eval(3.0).is_finite()); + // A subnormal secant next to a normal one: the tangent over that secant overflows. + let flat_then_steep = MonotoneCurve::new(&[(0.0, 0.0), (0.5, 1e-310), (1.0, 1.0)]); + assert!(flat_then_steep.knots().flatten().all(f64::is_finite)); + let mut prev = -1.0; + for i in 0..=1000 { + let y = flat_then_steep.eval(f64::from(i) / 1000.0); + assert!(y.is_finite() && y >= prev, "{i} {y}"); + prev = y; + } + } +} diff --git a/crates/color-transform/src/lib.rs b/crates/color-transform/src/lib.rs new file mode 100644 index 000000000..7708cd75e --- /dev/null +++ b/crates/color-transform/src/lib.rs @@ -0,0 +1,21 @@ +//! Color transforms for the Craft apps. +//! +//! - [`Mat3`], CIE [`Xy`] chromaticities and RGB spaces defined by primaries and a white point +//! ([`RgbSpace`]), with Bradford chromatic adaptation ([`bradford`]). +//! - White balance by correlated color temperature and tint ([`cct`]). +//! - OkLab and OkLCh ([`oklab`]). +//! - Monotone tone curves and 1D lookup tables ([`curve`]). +//! - PQ tone mapping with the reference EETF of Report ITU-R BT.2408 Annex 5 ([`tonemap`]). +//! +//! Frame color tags, Y'CbCr matrices and the transfer functions (sRGB, PQ, HLG) are in +//! `craft-color`; this crate builds on them. Every function that runs per pixel works on `f32` +//! without allocating, and builds for `wasm32-unknown-unknown`. +#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)] + +pub mod cct; +pub mod curve; +pub mod oklab; +mod space; +pub mod tonemap; + +pub use space::{BRADFORD, D50, D65, DISPLAY_P3, Mat3, REC601_525, REC601_625, REC2020, RgbSpace, SRGB, Xy, bradford, bradford_xyz}; diff --git a/crates/color-transform/src/oklab.rs b/crates/color-transform/src/oklab.rs new file mode 100644 index 000000000..73f5f7e4d --- /dev/null +++ b/crates/color-transform/src/oklab.rs @@ -0,0 +1,246 @@ +//! OkLab and OkLCh, as Björn Ottosson defined them in "A perceptual color space for image +//! processing" (2020). +//! +//! [`from_linear_srgb`] and [`to_linear_srgb`] use the published linear sRGB matrices. +//! [`OkLab::for_space`] builds the conversion for any [`RgbSpace`] from the published XYZ +//! matrix, adapting the space's white to D65 first (Bradford). + +use crate::{D65, Mat3, RgbSpace, bradford}; + +/// XYZ (D65) to approximate cone responses (the published M1). +pub const XYZ_TO_LMS: Mat3 = + Mat3([[0.8189330101, 0.3618667424, -0.1288597137], [0.0329845436, 0.9293118715, 0.0361456387], [0.0482003018, 0.2643662691, 0.6338517070]]); +/// Cube-rooted cone responses to Lab (the published M2). +pub const LMS_TO_LAB: Mat3 = + Mat3([[0.2104542553, 0.7936177850, -0.0040720468], [1.9779984951, -2.4285922050, 0.4505937099], [0.0259040371, 0.7827717662, -0.8086757660]]); + +/// Linear sRGB to cone responses (published with the linear sRGB conversion). +pub const SRGB_TO_LMS: Mat3 = + Mat3([[0.4122214708, 0.5363325363, 0.0514459929], [0.2119034982, 0.6806995451, 0.1073969566], [0.0883024619, 0.2817188376, 0.6299787005]]); +/// Cone responses to linear sRGB (published with the linear sRGB conversion). +pub const LMS_TO_SRGB: Mat3 = + Mat3([[4.0767416621, -3.3077115913, 0.2309699292], [-1.2684380046, 2.6097574011, -0.3413193965], [-0.0041960863, -0.7034186147, 1.7076147010]]); +/// Lab to cube-rooted cone responses (published with the linear sRGB conversion). +pub const LAB_TO_LMS: Mat3 = Mat3([[1.0, 0.3963377774, 0.2158037573], [1.0, -0.1055613458, -0.0638541728], [1.0, -0.0894841775, -1.2914855480]]); + +const fn f32s(m: &Mat3) -> [[f32; 3]; 3] { + let m = &m.0; + [ + [m[0][0] as f32, m[0][1] as f32, m[0][2] as f32], + [m[1][0] as f32, m[1][1] as f32, m[1][2] as f32], + [m[2][0] as f32, m[2][1] as f32, m[2][2] as f32], + ] +} + +const SRGB_LMS: [[f32; 3]; 3] = f32s(&SRGB_TO_LMS); +const LMS_SRGB: [[f32; 3]; 3] = f32s(&LMS_TO_SRGB); +const LAB: [[f32; 3]; 3] = f32s(&LMS_TO_LAB); +const LAB_INV: [[f32; 3]; 3] = f32s(&LAB_TO_LMS); + +#[inline] +fn mul(m: &[[f32; 3]; 3], v: [f32; 3]) -> [f32; 3] { + [ + m[0][0] * v[0] + m[0][1] * v[1] + m[0][2] * v[2], + m[1][0] * v[0] + m[1][1] * v[1] + m[1][2] * v[2], + m[2][0] * v[0] + m[2][1] * v[1] + m[2][2] * v[2], + ] +} + +/// Linear sRGB (BT.709 primaries, D65) to OkLab `[L, a, b]`. +#[inline] +pub fn from_linear_srgb(rgb: [f32; 3]) -> [f32; 3] { + mul(&LAB, mul(&SRGB_LMS, rgb).map(f32::cbrt)) +} + +/// OkLab to linear sRGB. +#[inline] +pub fn to_linear_srgb(lab: [f32; 3]) -> [f32; 3] { + mul(&LMS_SRGB, mul(&LAB_INV, lab).map(|v| v * v * v)) +} + +/// XYZ (D65, white Y = 1) to OkLab. +pub fn from_xyz(xyz: [f64; 3]) -> [f64; 3] { + LMS_TO_LAB.apply(XYZ_TO_LMS.apply(xyz).map(f64::cbrt)) +} + +/// The `f64` matrices [`OkLab::for_space`] starts from: linear RGB in `space` to cone responses +/// (the white adapted to D65 by Bradford), and back. `None` when the first has no inverse. Code +/// that builds its matrices once per render in `f64` uses these with [`LMS_TO_LAB`] and +/// [`LAB_TO_LMS`]. +pub fn lms_matrices(space: &RgbSpace) -> Option<(Mat3, Mat3)> { + let to_lms = XYZ_TO_LMS.mul(&bradford(space.white, D65)).mul(&space.to_xyz()); + to_lms.inverse().map(|from_lms| (to_lms, from_lms)) +} + +/// OkLab to OkLCh `[L, C, h]`, with the hue in radians from −π to π. +#[inline] +pub fn lab_to_lch(lab: [f32; 3]) -> [f32; 3] { + [lab[0], lab[1].hypot(lab[2]), lab[2].atan2(lab[1])] +} + +/// OkLCh to OkLab. +#[inline] +pub fn lch_to_lab(lch: [f32; 3]) -> [f32; 3] { + let (s, c) = lch[2].sin_cos(); + [lch[0], lch[1] * c, lch[1] * s] +} + +/// The OkLab conversion for one RGB space, with its matrices precomputed in `f32`. +#[derive(Clone, Copy, Debug, PartialEq)] +pub struct OkLab { + to_lms: [[f32; 3]; 3], + from_lms: [[f32; 3]; 3], +} + +impl OkLab { + /// The conversion for linear RGB in `space`. + pub fn for_space(space: &RgbSpace) -> OkLab { + let pair = lms_matrices(space).map(|(to_lms, from_lms)| (to_lms.to_f32(), from_lms.to_f32())); + let finite = |m: &[[f32; 3]; 3]| m.iter().flatten().all(|v| v.is_finite()); + match pair { + Some((to_lms, from_lms)) if finite(&to_lms) && finite(&from_lms) => OkLab { to_lms, from_lms }, + // A matrix with no inverse or with an entry beyond f32 falls back to XYZ_TO_LMS + // alone, the matrix a space gets when its primaries and its white are both rejected. + _ => OkLab { to_lms: f32s(&XYZ_TO_LMS), from_lms: XYZ_TO_LMS.inverse().unwrap_or(Mat3::IDENTITY).to_f32() }, + } + } + + /// The `f32` matrices, row-major: linear RGB to cone responses, and back. GPU passes that + /// convert to OkLab use these with [`LMS_TO_LAB`]. + pub fn matrices(&self) -> ([[f32; 3]; 3], [[f32; 3]; 3]) { + (self.to_lms, self.from_lms) + } + + /// Linear RGB to OkLab. + #[inline] + pub fn from_rgb(&self, rgb: [f32; 3]) -> [f32; 3] { + mul(&LAB, mul(&self.to_lms, rgb).map(f32::cbrt)) + } + + /// OkLab to linear RGB. + #[inline] + pub fn to_rgb(&self, lab: [f32; 3]) -> [f32; 3] { + mul(&self.from_lms, mul(&LAB_INV, lab).map(|v| v * v * v)) + } +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::{D50, REC2020, SRGB, Xy}; + + /// The table of XYZ values and their OkLab coordinates in Ottosson's definition, rounded + /// to three decimals. + #[test] + fn xyz_matches_the_published_table() { + let table = [ + ([0.950, 1.000, 1.089], [1.000, 0.000, 0.000]), + ([1.000, 0.000, 0.000], [0.450, 1.236, -0.019]), + ([0.000, 1.000, 0.000], [0.922, -0.671, 0.263]), + ([0.000, 0.000, 1.000], [0.153, -1.415, -0.449]), + ]; + for (xyz, want) in table { + let lab = from_xyz(xyz); + for i in 0..3 { + assert!((lab[i] - want[i]).abs() < 6e-4, "{xyz:?} -> {lab:?}"); + } + } + } + + /// CSS Color Module Level 4 (section 2, "These are exactly equivalent") gives #7654CD as + /// oklab(54.43237% 0.0681665 -0.1656703). + #[test] + fn an_srgb_color_matches_css_color_4() { + let rgb = [0x76, 0x54, 0xCD].map(|v: u8| craft_color::srgb_to_linear(f32::from(v) / 255.0)); + let lab = from_linear_srgb(rgb); + let want = [0.5443237, 0.0681665, -0.1656703]; + for i in 0..3 { + assert!((lab[i] - want[i]).abs() < 2e-4, "{lab:?}"); + } + } + + #[test] + fn the_srgb_matrices_and_the_space_built_from_xyz_agree() { + let srgb = OkLab::for_space(&SRGB); + for c in [[0.1, 0.5, 0.9], [1.0, 0.0, 0.0], [0.02, 0.03, 0.01], [1.0, 1.0, 1.0]] { + let a = from_linear_srgb(c); + let b = srgb.from_rgb(c); + for i in 0..3 { + assert!((a[i] - b[i]).abs() < 2e-4, "{c:?} {a:?} {b:?}"); + } + } + } + + #[test] + fn white_is_l1_and_grays_have_no_chroma_in_every_space() { + let d50 = crate::RgbSpace { white: D50, ..SRGB }; + for space in [SRGB, REC2020, d50] { + let ok = OkLab::for_space(&space); + let w = ok.from_rgb([1.0, 1.0, 1.0]); + assert!((w[0] - 1.0).abs() < 2e-4 && w[1].abs() < 2e-4 && w[2].abs() < 2e-4, "{space:?} {w:?}"); + let g = ok.from_rgb([0.18, 0.18, 0.18]); + assert!(g[1].abs() < 2e-4 && g[2].abs() < 2e-4, "{space:?} {g:?}"); + } + } + + #[test] + fn conversions_round_trip() { + let ok = OkLab::for_space(&REC2020); + for c in [[0.1, 0.5, 0.9], [1.0, 0.0, 0.0], [0.02, 0.03, 0.01], [2.0, 1.5, 0.3], [-0.1, 0.4, 0.2]] { + let a = to_linear_srgb(from_linear_srgb(c)); + let b = ok.to_rgb(ok.from_rgb(c)); + for i in 0..3 { + assert!((a[i] - c[i]).abs() < 1e-4 * c[i].abs().max(1.0), "{c:?} {a:?}"); + assert!((b[i] - c[i]).abs() < 1e-4 * c[i].abs().max(1.0), "{c:?} {b:?}"); + } + } + let lab = lch_to_lab(lab_to_lch([0.5, 0.1, -0.05])); + assert!((lab[1] - 0.1).abs() < 1e-6 && (lab[2] + 0.05).abs() < 1e-6); + } + + #[test] + fn a_space_that_does_not_exist_does_not_produce_nan() { + let bad = crate::RgbSpace { r: Xy::new(0.3, 0.0), ..SRGB }; + let ok = OkLab::for_space(&bad); + assert!(ok.from_rgb([0.5, 0.5, 0.5]).iter().all(|v| v.is_finite())); + } + + #[test] + fn the_f64_matrices_match_the_published_xyz_conversion() { + let (to, from) = lms_matrices(&SRGB).unwrap(); + let p = to.mul(&from); + for i in 0..3 { + for j in 0..3 { + assert!((p.0[i][j] - if i == j { 1.0 } else { 0.0 }).abs() < 1e-12, "{p:?}"); + } + } + // The published linear sRGB matrix and the one built from XYZ differ by at most 3.1e-4. + for i in 0..3 { + for j in 0..3 { + assert!((to.0[i][j] - SRGB_TO_LMS.0[i][j]).abs() < 5e-4, "{to:?}"); + } + } + for c in [[0.1, 0.5, 0.9], [1.0, 1.0, 1.0]] { + let lab = LMS_TO_LAB.apply(to.apply(c).map(f64::cbrt)); + let f = OkLab::for_space(&SRGB).from_rgb(c.map(|v| v as f32)); + for i in 0..3 { + assert!((lab[i] - f64::from(f[i])).abs() < 1e-5, "{c:?} {lab:?} {f:?}"); + } + } + let bad = crate::RgbSpace { r: Xy::new(0.3, 0.0), ..SRGB }; + assert!(lms_matrices(&bad).is_some_and(|(t, _)| t.0.iter().flatten().all(|v| v.is_finite()))); + } + + /// A white this close to y = 0 gives `f64` matrices with entries beyond `f32`. + #[test] + fn a_space_whose_matrices_overflow_f32_does_not_produce_nan() { + let far = crate::RgbSpace { white: Xy::new(0.5, 1e-40), ..SRGB }; + let ok = OkLab::for_space(&far); + let (to, from) = ok.matrices(); + assert!(to.iter().chain(from.iter()).flatten().all(|v| v.is_finite()), "{to:?} {from:?}"); + for c in [[0.0; 3], [0.5, 0.5, 0.5], [1.0, 0.0, 0.0]] { + assert!(ok.from_rgb(c).iter().all(|v| v.is_finite()), "{c:?}"); + assert!(ok.to_rgb(ok.from_rgb(c)).iter().all(|v| v.is_finite()), "{c:?}"); + } + } +} diff --git a/crates/color-transform/src/space.rs b/crates/color-transform/src/space.rs new file mode 100644 index 000000000..c0c1da382 --- /dev/null +++ b/crates/color-transform/src/space.rs @@ -0,0 +1,295 @@ +//! 3×3 matrices, chromaticities, RGB spaces and Bradford chromatic adaptation. + +use craft_cms::math; +use craft_color::Primaries; +use serde::{Deserialize, Serialize}; + +/// A row-major 3×3 matrix. +#[derive(Clone, Copy, Debug, PartialEq, Serialize, Deserialize)] +pub struct Mat3(pub [[f64; 3]; 3]); + +impl Mat3 { + pub const IDENTITY: Mat3 = Mat3([[1.0, 0.0, 0.0], [0.0, 1.0, 0.0], [0.0, 0.0, 1.0]]); + + pub const fn diag(a: f64, b: f64, c: f64) -> Mat3 { + Mat3([[a, 0.0, 0.0], [0.0, b, 0.0], [0.0, 0.0, c]]) + } + + /// `self × o`: applying the product applies `o` first ([`math::mul`]). + pub fn mul(&self, o: &Mat3) -> Mat3 { + Mat3(math::mul(&self.0, &o.0)) + } + + /// [`math::apply`]. + pub fn apply(&self, v: [f64; 3]) -> [f64; 3] { + math::apply(&self.0, v) + } + + /// [`math::det`]. + pub fn determinant(&self) -> f64 { + math::det(&self.0) + } + + /// The inverse, or `None` when the matrix holds a non-finite value, is singular to within + /// rounding (the determinant is at most 1e-12 times the cube of the largest entry), or has an + /// inverse with an entry beyond the range of `f64` ([`math::inverse`]). + pub fn inverse(&self) -> Option { + math::inverse(&self.0).map(Mat3) + } + + pub fn transpose(&self) -> Mat3 { + let m = &self.0; + Mat3([[m[0][0], m[1][0], m[2][0]], [m[0][1], m[1][1], m[2][1]], [m[0][2], m[1][2], m[2][2]]]) + } + + /// The matrix as `f32`, row-major, for per-pixel code and GPU uniforms. + pub fn to_f32(&self) -> [[f32; 3]; 3] { + self.0.map(|r| r.map(|v| v as f32)) + } +} + +/// A row-major array, the form `craft_cms::math::Mat3` takes. +impl From<[[f64; 3]; 3]> for Mat3 { + fn from(m: [[f64; 3]; 3]) -> Mat3 { + Mat3(m) + } +} + +impl From for [[f64; 3]; 3] { + fn from(m: Mat3) -> [[f64; 3]; 3] { + m.0 + } +} + +/// A CIE 1931 xy chromaticity. +#[derive(Clone, Copy, Debug, PartialEq, Serialize, Deserialize)] +pub struct Xy { + pub x: f64, + pub y: f64, +} + +impl Xy { + pub const fn new(x: f64, y: f64) -> Xy { + Xy { x, y } + } + + /// XYZ with Y = 1, or `None` when `y` is not above 0, a coordinate is not finite, or `y` is + /// so small that X or Z overflows. + pub fn to_xyz(self) -> Option<[f64; 3]> { + if !(self.x.is_finite() && self.y.is_finite() && self.y > 0.0) { + return None; + } + let xyz = math::xy_to_xyz([self.x, self.y]); + xyz.iter().all(|v| v.is_finite()).then_some(xyz) + } + + /// The chromaticity of an XYZ triple, or `None` when X + Y + Z is not above 0. + pub fn from_xyz(v: [f64; 3]) -> Option { + let s = v[0] + v[1] + v[2]; + if !(s.is_finite() && s > 0.0) { + return None; + } + Some(Xy::new(v[0] / s, v[1] / s)) + } +} + +/// CIE standard illuminant D65, as ITU-R BT.709 and BT.2020 give it. +pub const D65: Xy = Xy::new(0.3127, 0.3290); +/// CIE illuminant D50, the ICC profile connection space white. +pub const D50: Xy = Xy::new(0.3457, 0.3585); + +/// An RGB color space: three primaries and a white point. A space read at run time (from a +/// file's primaries or a stream's mastering metadata) is built with a struct literal. +#[derive(Clone, Copy, Debug, PartialEq, Serialize, Deserialize)] +pub struct RgbSpace { + pub r: Xy, + pub g: Xy, + pub b: Xy, + pub white: Xy, +} + +/// The ITU-R BT.709 primaries, which sRGB (IEC 61966-2-1) shares. +pub const SRGB: RgbSpace = RgbSpace { r: Xy::new(0.64, 0.33), g: Xy::new(0.30, 0.60), b: Xy::new(0.15, 0.06), white: D65 }; +/// ITU-R BT.601, 625-line systems. +pub const REC601_625: RgbSpace = RgbSpace { r: Xy::new(0.64, 0.33), g: Xy::new(0.29, 0.60), b: Xy::new(0.15, 0.06), white: D65 }; +/// ITU-R BT.601, 525-line systems. +pub const REC601_525: RgbSpace = RgbSpace { r: Xy::new(0.630, 0.340), g: Xy::new(0.310, 0.595), b: Xy::new(0.155, 0.070), white: D65 }; +/// ITU-R BT.2020 (and BT.2100). +pub const REC2020: RgbSpace = RgbSpace { r: Xy::new(0.708, 0.292), g: Xy::new(0.170, 0.797), b: Xy::new(0.131, 0.046), white: D65 }; +/// The DCI-P3 primaries with a D65 white (SMPTE EG 432-1). +pub const DISPLAY_P3: RgbSpace = RgbSpace { r: Xy::new(0.680, 0.320), g: Xy::new(0.265, 0.690), b: Xy::new(0.150, 0.060), white: D65 }; + +impl From for RgbSpace { + fn from(p: Primaries) -> RgbSpace { + match p { + Primaries::Bt709 => SRGB, + Primaries::Bt601_625 => REC601_625, + Primaries::Bt601_525 => REC601_525, + Primaries::Bt2020 => REC2020, + Primaries::P3D65 => DISPLAY_P3, + } + } +} + +impl RgbSpace { + /// Linear RGB in this space to XYZ, with the space's white at Y = 1 (the normalized primary + /// matrix of SMPTE RP 177). Primaries or a white that do not define a space (collinear + /// primaries, a `y` of 0, a white on a primary or on the line between two) give the identity. + pub fn to_xyz(&self) -> Mat3 { + let (Some(r), Some(g), Some(b), Some(w)) = (self.r.to_xyz(), self.g.to_xyz(), self.b.to_xyz(), self.white.to_xyz()) else { + return Mat3::IDENTITY; + }; + let m = Mat3([[r[0], g[0], b[0]], [r[1], g[1], b[1]], [r[2], g[2], b[2]]]); + let Some(inv) = m.inverse() else { return Mat3::IDENTITY }; + let s = inv.apply(w); + let npm = m.mul(&Mat3::diag(s[0], s[1], s[2])); + // A white that gives a primary no weight leaves a matrix with no inverse. + if npm.inverse().is_none() { Mat3::IDENTITY } else { npm } + } + + /// XYZ to linear RGB in this space: the inverse of [`to_xyz`](Self::to_xyz). + pub fn from_xyz(&self) -> Mat3 { + self.to_xyz().inverse().unwrap_or(Mat3::IDENTITY) + } + + /// The luminance weights of R, G and B (the Y row of [`to_xyz`](Self::to_xyz)). + pub fn luma(&self) -> [f64; 3] { + self.to_xyz().0[1] + } + + /// Linear RGB in `self` to linear RGB in `dst`, Bradford-adapting between the white points. + pub fn to_space(&self, dst: &RgbSpace) -> Mat3 { + dst.from_xyz().mul(&bradford(self.white, dst.white)).mul(&self.to_xyz()) + } +} + +/// The Bradford cone response matrix (XYZ to sharpened cone responses). +pub const BRADFORD: Mat3 = Mat3(math::BRADFORD); + +/// The Bradford chromatic adaptation matrix (XYZ to XYZ) from white `src` to white `dst`. A +/// white that [`Xy::to_xyz`] rejects gives the identity. +pub fn bradford(src: Xy, dst: Xy) -> Mat3 { + if src == dst { + return Mat3::IDENTITY; + } + match (src.to_xyz(), dst.to_xyz()) { + (Some(s), Some(d)) => bradford_xyz(s, d), + _ => Mat3::IDENTITY, + } +} + +/// [`bradford`] for whites given as XYZ. A white with a cone response that is not above 0 or +/// not finite, or a pair whose response ratios overflow, gives the identity. +pub fn bradford_xyz(src: [f64; 3], dst: [f64; 3]) -> Mat3 { + math::bradford_checked(src, dst).map_or(Mat3::IDENTITY, Mat3) +} + +#[cfg(test)] +mod tests { + use super::*; + + fn close(a: &Mat3, b: &[[f64; 3]; 3], tol: f64) { + for i in 0..3 { + for j in 0..3 { + assert!((a.0[i][j] - b[i][j]).abs() < tol, "[{i}][{j}] {} vs {}", a.0[i][j], b[i][j]); + } + } + } + + /// IEC 61966-2-1 gives the sRGB RGB to XYZ matrix to four decimals. + #[test] + fn srgb_matrix_matches_iec_61966_2_1() { + close(&SRGB.to_xyz(), &[[0.4124, 0.3576, 0.1805], [0.2126, 0.7152, 0.0722], [0.0193, 0.1192, 0.9505]], 1e-4); + } + + /// ITU-R BT.2020 and BT.709 give the luminance coefficients. + #[test] + fn luminance_weights_match_bt709_and_bt2020() { + for (space, want) in [(SRGB, [0.2126, 0.7152, 0.0722]), (REC2020, [0.2627, 0.6780, 0.0593])] { + let l = space.luma(); + for i in 0..3 { + assert!((l[i] - want[i]).abs() < 1e-4, "{space:?} {l:?}"); + } + } + } + + /// The Bradford matrix from D65 to D50 as Lindbloom's chromatic adaptation tables print it, + /// with his reference whites. + #[test] + fn bradford_d65_to_d50_matches_the_published_matrix() { + let m = bradford_xyz([0.95047, 1.0, 1.08883], [0.96422, 1.0, 0.82521]); + let want = [[1.0478112, 0.0228866, -0.0501270], [0.0295424, 0.9904844, -0.0170491], [-0.0092345, 0.0150436, 0.7521316]]; + close(&m, &want, 1e-6); + } + + #[test] + fn adaptation_maps_white_to_white_and_round_trips() { + let m = bradford(D65, D50); + let w = m.apply(D65.to_xyz().unwrap()); + let d50 = D50.to_xyz().unwrap(); + for i in 0..3 { + assert!((w[i] - d50[i]).abs() < 1e-12); + } + let back = bradford(D50, D65).mul(&m); + close(&back, &Mat3::IDENTITY.0, 1e-12); + let v = SRGB.to_space(&REC2020).apply([1.0, 1.0, 1.0]); + assert!(v.iter().all(|c| (c - 1.0).abs() < 1e-9), "{v:?}"); + } + + /// The BT.709 to BT.2020 conversion matrix of Report ITU-R BT.2087 (equation 2). + #[test] + fn bt709_to_bt2020_matches_bt2087() { + let want = [[0.6274, 0.3293, 0.0433], [0.0691, 0.9195, 0.0114], [0.0164, 0.0880, 0.8956]]; + close(&SRGB.to_space(&REC2020), &want, 1e-4); + } + + #[test] + fn primaries_tags_map_to_spaces() { + assert_eq!(RgbSpace::from(Primaries::Bt2020), REC2020); + assert_eq!(RgbSpace::from(Primaries::default()), SRGB); + } + + #[test] + fn hostile_whites_and_primaries_do_not_produce_nan() { + assert_eq!(Xy::new(0.3, 0.0).to_xyz(), None); + assert_eq!(Xy::new(f64::NAN, 0.3).to_xyz(), None); + assert_eq!(Xy::new(0.3, 1e-320).to_xyz(), None); + assert_eq!(bradford(Xy::new(0.3, 1e-320), D65), Mat3::IDENTITY); + assert_eq!(Xy::from_xyz([0.0, 0.0, 0.0]), None); + assert_eq!(bradford(Xy::new(0.3, 0.0), D65), Mat3::IDENTITY); + assert_eq!(bradford(D65, Xy::new(f64::INFINITY, 0.3)), Mat3::IDENTITY); + assert_eq!(bradford_xyz([-1.0, 1.0, 1.0], [0.95, 1.0, 1.09]), Mat3::IDENTITY); + let flat = RgbSpace { r: Xy::new(0.2, 0.2), g: Xy::new(0.3, 0.3), b: Xy::new(0.4, 0.4), white: D65 }; + assert_eq!(flat.to_xyz(), Mat3::IDENTITY); + assert_eq!(Mat3([[f64::NAN; 3]; 3]).inverse(), None); + // The determinant, 1e-312, has no finite reciprocal; the inverse itself is finite. + let tiny = Mat3::diag(1e-104, 1e-104, 1e-104).inverse().unwrap(); + close(&tiny, &[[1e104, 0.0, 0.0], [0.0, 1e104, 0.0], [0.0, 0.0, 1e104]], 1e93); + // A determinant beyond f64 in either direction still leaves a finite inverse. + let small = Mat3::diag(1e-200, 1e-200, 1e-200).inverse().unwrap(); + close(&small, &Mat3::diag(1e200, 1e200, 1e200).0, 1e186); + let large = Mat3::diag(1e110, 1e110, 1e110).inverse().unwrap(); + close(&large, &Mat3::diag(1e-110, 1e-110, 1e-110).0, 1e-124); + // An inverse with entries beyond f64 is no inverse. + assert_eq!(Mat3::diag(1e-310, 1e-310, 1e-310).inverse(), None); + assert_eq!(Mat3([[0.0; 3]; 3]).inverse(), None); + assert_eq!(Mat3::diag(f64::MAX, f64::MAX, f64::MAX).inverse().map(|m| m.0[0][0]), Some(1.0 / f64::MAX)); + // A white on a primary leaves two primaries with no weight: no space. + let on_red = RgbSpace { white: SRGB.r, ..SRGB }; + assert_eq!(on_red.to_xyz(), Mat3::IDENTITY); + assert_eq!(on_red.from_xyz(), Mat3::IDENTITY); + // Cone responses this small give scale ratios beyond f64. + assert_eq!(bradford_xyz([1e-320; 3], D65.to_xyz().unwrap()), Mat3::IDENTITY); + } + + /// A space built from primaries read at run time saves and loads, and its matrix converts + /// to and from a plain array. + #[test] + fn spaces_save_and_load() { + let read = RgbSpace { r: Xy::new(0.7, 0.29), g: Xy::new(0.16, 0.8), b: Xy::new(0.13, 0.05), white: D50 }; + let json = serde_json::to_string(&read).unwrap(); + assert_eq!(serde_json::from_str::(&json).unwrap(), read); + let m: [[f64; 3]; 3] = read.to_xyz().into(); + assert_eq!(Mat3::from(m), read.to_xyz()); + } +} diff --git a/crates/color-transform/src/tonemap.rs b/crates/color-transform/src/tonemap.rs new file mode 100644 index 000000000..45bafd2cd --- /dev/null +++ b/crates/color-transform/src/tonemap.rs @@ -0,0 +1,406 @@ +//! PQ tone mapping with the reference EETF of Report ITU-R BT.2408-8, Annex 5 ("Displaying +//! PQ: calculating the EETF"), which Report ITU-R BT.2390 described before it. +//! +//! The EETF works on PQ (SMPTE ST 2084) values: it keeps the range below a knee 1:1, rolls off +//! the range above it with a Hermite spline so the source peak lands on the target peak, and +//! lifts the target black with a tapered offset. [`ToneMap`] applies it to RGB by max(R, G, B), +//! the "maxRGB" option of the Annex, as a ratio, so hue and saturation are kept. + +use craft_color::{REFERENCE_WHITE_NITS, pq_eotf, pq_inverse_eotf}; + +/// PQ code value (0..1) of `nits`. +fn pq(nits: f64) -> f64 { + f64::from(pq_inverse_eotf((nits / 10_000.0).clamp(0.0, 1.0) as f32)) +} + +/// Luminance in nits of the PQ value `e`. +fn nits(e: f64) -> f64 { + f64::from(pq_eotf(e.clamp(0.0, 1.0) as f32)) * 10_000.0 +} + +/// A luminance in nits: NaN, negative values and infinity read as 0, 0 and 10 000. +fn sane(n: f64) -> f64 { + if n.is_nan() { 0.0 } else { n.clamp(0.0, 10_000.0) } +} + +/// The reference EETF from a mastering display (black `src_black`, peak `src_peak`) to a +/// target display (black `dst_black`, peak `dst_peak`), all in nits. +#[derive(Clone, Copy, Debug, PartialEq)] +pub struct Eetf { + pb: f64, + span: f64, + min_lum: f64, + max_lum: f64, + ks: f64, + /// The spline's slope at the knee: 1 within the Annex's range. + slope: f64, + /// The black lift's exponent: 4 within the Annex's range. + lift: f64, + /// The E2 at which the black lift reaches 0: 1 within the Annex's range. + reach: f64, +} + +impl Eetf { + /// Luminances are clamped to 0..10 000 nits. A target black below the source black adds no + /// lift. When the source range is empty the EETF passes values through. + /// + /// When the target peak sits below a third of the source range in PQ, the Annex's knee + /// (KS = 1.5 maxLum − 0.5) is negative. The knee is then 0 and the spline starts with a + /// slope of 3 maxLum, the steepest that keeps it rising. + /// + /// The Annex's black lift, minLum × (1 − E2)⁴, makes the output fall near black when minLum + /// is above 0.25, and lifts the peak well above the target peak. The lift here is + /// minLum × (1 − E2 / r)ᵏ with r = max(T, min(1, 2 − 4 minLum)) and k = min(4, r / minLum), + /// where T, the top of the output, is the smaller of maxLum and 1. Up to minLum 0.25 this is + /// the Annex's lift. Above it, k is the largest exponent that keeps the output rising, r moves + /// continuously from 1 down to T, and from minLum 0.5 the lift reaches 0 at the top of the + /// output. A target black above the source peak reads as the source peak. + /// + /// A target peak at or below the source black would put every output at the source black + /// or above it; the source black then reads as 0. A target black above the target peak + /// reads as the target peak. A target peak that is NaN or not above 0 names no display, and + /// the EETF then passes values through. + pub fn new(src_black: f64, src_peak: f64, dst_black: f64, dst_peak: f64) -> Eetf { + let pb = pq(sane(src_black)); + let pass = Eetf { pb, span: 0.0, min_lum: 0.0, max_lum: 1.0, ks: 1.0, slope: 1.0, lift: 4.0, reach: 1.0 }; + if dst_peak.is_nan() || dst_peak <= 0.0 { + return pass; + } + let (dst_peak, pw) = (sane(dst_peak), pq(sane(src_peak))); + let dst_black = sane(dst_black).min(dst_peak); + if pw <= pb { + return pass; + } + let pb = if pq(dst_peak) <= pb { 0.0 } else { pb }; + let span = pw - pb; + // Step 2. + let min_lum = ((pq(dst_black) - pb) / span).max(0.0); + let max_lum = ((pq(dst_peak) - pb) / span).max(0.0); + let ks = 1.5 * max_lum - 0.5; + let (ks, slope) = if ks >= 0.0 { (ks, 1.0) } else { (0.0, 3.0 * max_lum) }; + // E2 ends at `top`. The output's slope at E2 = 0 is 1 − lift × minLum / reach, so the + // exponent is at most reach / minLum. Up to minLum 0.25 this gives the Annex's (1, 4); both + // change continuously above it, and reach is `top` from minLum 0.5. A target black above + // the source peak (minLum above `top`) reads as the source peak. + let top = max_lum.min(1.0); + let min_lum = min_lum.min(top); + let reach = top.max((2.0 - 4.0 * min_lum).min(1.0)); + let lift = if min_lum > 0.0 { (reach / min_lum).min(4.0) } else { 4.0 }; + Eetf { pb, span, min_lum, max_lum, ks, slope, lift, reach } + } + + /// Whether the EETF passes every value through unchanged. + pub fn is_identity(&self) -> bool { + self.span <= 0.0 || (self.max_lum >= 1.0 && self.min_lum <= 0.0) + } + + /// The EETF on a PQ value (0..1): steps 1 to 5 of the Annex. Unless the EETF is the + /// identity, values above the source peak map as the peak does. + pub fn apply_pq(&self, e: f64) -> f64 { + if self.is_identity() || e.is_nan() { + return e; + } + // Step 1. + let e1 = ((e - self.pb) / self.span).clamp(0.0, 1.0); + // Steps 3 and 4: 1:1 below the knee, the Hermite spline above it. + let e2 = if e1 < self.ks || self.max_lum >= 1.0 { + e1 + } else { + let t = (e1 - self.ks) / (1.0 - self.ks); + let (t2, t3) = (t * t, t * t * t); + (2.0 * t3 - 3.0 * t2 + 1.0) * self.ks + (t3 - 2.0 * t2 + t) * (1.0 - self.ks) * self.slope + (-2.0 * t3 + 3.0 * t2) * self.max_lum + }; + let e3 = if self.reach == 1.0 && self.lift == 4.0 { + e2 + self.min_lum * (1.0 - e2).powi(4) + } else { + e2 + self.min_lum * (1.0 - e2 / self.reach).max(0.0).powf(self.lift) + }; + // Step 5. + e3 * self.span + self.pb + } + + /// The EETF on a luminance in nits. + pub fn apply_nits(&self, n: f64) -> f64 { + nits(self.apply_pq(pq(sane(n)))) + } +} + +/// The BT.2408 EETF from a display of peak `src_peak` to one of peak `dst_peak` (nits), with +/// black at 0. +pub fn eetf(n: f64, src_peak: f64, dst_peak: f64) -> f64 { + Eetf::new(0.0, src_peak, 0.0, dst_peak).apply_nits(n) +} + +/// Entries in [`ToneMap`]'s table. +const TABLE: usize = 4096; + +/// Tone mapping of linear RGB, where 1.0 is reference white, from a source peak to a target +/// peak. It applies the EETF (black at 0) to max(R, G, B) and scales the three channels by the +/// same ratio. The ratios are tabulated on a PQ axis once, so [`apply`](Self::apply) does not +/// allocate. +#[derive(Clone, Debug, PartialEq)] +pub struct ToneMap { + src_peak: f32, + dst_peak: f32, + white: f32, + identity: bool, + /// Output nits over input nits, at PQ values `i / (TABLE − 1)`. + ratio: Vec, +} + +impl ToneMap { + /// Tone mapping with reference white at `craft_color::REFERENCE_WHITE_NITS` (203 nits, + /// Report ITU-R BT.2408). + pub fn new(src_peak_nits: f64, dst_peak_nits: f64) -> ToneMap { + ToneMap::with_reference_white(src_peak_nits, dst_peak_nits, REFERENCE_WHITE_NITS) + } + + /// Tone mapping where 1.0 is `white_nits`. A white that is not above 0 or not finite reads + /// as 203 nits, and one above 10 000 nits as 10 000. + pub fn with_reference_white(src_peak_nits: f64, dst_peak_nits: f64, white_nits: f64) -> ToneMap { + let (s, d) = (sane(src_peak_nits), sane(dst_peak_nits)); + let white = if white_nits.is_finite() && white_nits > 0.0 { white_nits.min(10_000.0) } else { REFERENCE_WHITE_NITS }; + let curve = Eetf::new(0.0, s, 0.0, d); + let identity = curve.is_identity(); + let ratio = if identity { + Vec::new() + } else { + (0..TABLE) + .map(|i| { + let e = i as f64 / (TABLE - 1) as f64; + let n = nits(e); + if n <= 1e-6 { 1.0 } else { (curve.apply_nits(n) / n) as f32 } + }) + .collect() + }; + ToneMap { src_peak: s as f32, dst_peak: d as f32, white: white as f32, identity, ratio } + } + + /// Whether [`apply`](Self::apply) returns its input (the target peak is at or above the + /// source peak). + pub fn is_identity(&self) -> bool { + self.identity + } + + /// One pixel of linear RGB, 1.0 = reference white. + #[inline] + pub fn apply(&self, c: [f32; 3]) -> [f32; 3] { + if self.identity { + return c; + } + let m = c[0].max(c[1]).max(c[2]); + // NaN (all three channels NaN) and values at or below 0 pass through. + if m.is_nan() || m <= 0.0 { + return c; + } + let n = m * self.white; + if n >= self.src_peak { + // The brightest channel lands on the target peak. Dividing by m first keeps an + // infinite channel (or an n that overflows) from giving infinity times 0. + let peak = self.dst_peak / self.white; + return c.map(|v| if v >= m { peak } else { v / m * peak }); + } + let k = self.lookup(pq_inverse_eotf(n / 10_000.0)); + c.map(|v| v * k) + } + + #[inline] + fn lookup(&self, e: f32) -> f32 { + let last = self.ratio.len().saturating_sub(1); + let p = e.clamp(0.0, 1.0) * last as f32; + let i = (p as usize).min(last.saturating_sub(1)); + let (Some(a), Some(b)) = (self.ratio.get(i), self.ratio.get(i + 1)) else { return 1.0 }; + a + (b - a) * (p - i as f32) + } +} + +#[cfg(test)] +mod tests { + use super::*; + + /// Report ITU-R BT.2408 lists 203 nits (HDR reference white) at 58 % PQ and 1000 nits at + /// 75 %; these check the PQ functions the EETF stands on. + #[test] + fn pq_reference_levels() { + assert!((pq(203.0) - 0.58).abs() < 0.005, "{}", pq(203.0)); + assert!((pq(1000.0) - 0.75).abs() < 0.005, "{}", pq(1000.0)); + assert!((nits(pq(100.0)) - 100.0).abs() < 0.05); + } + + /// Values computed from the Annex 5 equations and the ST 2084 constants by a separate + /// implementation, 1000 nits to 100 nits. + #[test] + fn matches_an_independent_evaluation_of_the_annex() { + let curve = Eetf::new(0.0, 1000.0, 0.0, 100.0); + for (input, want) in ORACLE_1000_TO_100 { + let got = curve.apply_nits(input); + assert!((got - want).abs() <= want * 2e-4 + 1e-4, "{input} nits: {got} vs {want}"); + } + let lifted = Eetf::new(0.0, 1000.0, 0.1, 100.0); + for (input, want) in ORACLE_1000_TO_100_BLACK_01 { + let got = lifted.apply_nits(input); + assert!((got - want).abs() <= want * 2e-4 + 1e-4, "{input} nits: {got} vs {want}"); + } + } + + const ORACLE_1000_TO_100: [(f64, f64); 9] = [ + (0.0, 0.000000), + (1.0, 1.000000), + (10.0, 10.000000), + (50.0, 46.142955), + (100.0, 69.454403), + (203.0, 88.243641), + (400.0, 97.598409), + (700.0, 99.854805), + (1000.0, 100.000000), + ]; + const ORACLE_1000_TO_100_BLACK_01: [(f64, f64); 9] = [ + (0.0, 0.100000), + (1.0, 1.608558), + (10.0, 11.080978), + (50.0, 47.142334), + (100.0, 70.309850), + (203.0, 88.992667), + (400.0, 98.298831), + (700.0, 100.543945), + (1000.0, 100.688420), + ]; + + #[test] + fn the_knee_keeps_low_values_and_lands_the_peak_on_the_target() { + let curve = Eetf::new(0.0, 1000.0, 0.0, 100.0); + assert!((curve.apply_nits(1000.0) - 100.0).abs() < 0.05); + assert!((curve.apply_nits(5000.0) - 100.0).abs() < 0.05, "above the source peak"); + // Below the knee (KS = 1.5 maxLum − 0.5) the EETF is 1:1. + let below = nits(curve.ks * pq(1000.0) * 0.99); + assert!((curve.apply_nits(below) - below).abs() < below * 1e-4, "{below}"); + let mut prev = 0.0; + for i in 0..=1000 { + let out = curve.apply_pq(f64::from(i) / 1000.0 * pq(1000.0)); + assert!(out >= prev - 1e-12, "monotone"); + prev = out; + } + assert!(Eetf::new(0.0, 100.0, 0.0, 1000.0).is_identity()); + assert_eq!(eetf(400.0, 100.0, 1000.0) as f32, nits(pq(400.0)) as f32); + } + + /// 10 000 nits to 1 nit puts the target peak below a third of the source range: the curve + /// still rises from 0 to the target peak and keeps shadows apart. + #[test] + fn a_deep_reduction_keeps_rising_without_crushing_shadows() { + let curve = Eetf::new(0.0, 10_000.0, 0.0, 1.0); + let mut prev = -1.0; + for i in 0..=2000 { + let out = curve.apply_pq(f64::from(i) / 2000.0); + assert!(out > prev || i == 0, "{i}: {out} after {prev}"); + assert!(out >= 0.0); + prev = out; + } + assert!((curve.apply_nits(10_000.0) - 1.0).abs() < 1e-3); + assert!(curve.apply_nits(0.01) > 0.0 && curve.apply_nits(0.01) < curve.apply_nits(0.1)); + } + + #[test] + fn the_black_lift_raises_black_to_the_target_black() { + let curve = Eetf::new(0.0, 1000.0, 0.1, 100.0); + assert!((curve.apply_nits(0.0) - 0.1).abs() < 1e-3, "{}", curve.apply_nits(0.0)); + // The taper (1 − E2)⁴ is small but not 0 at the target peak, so the peak rises a little. + let peak = curve.apply_nits(1000.0); + assert!(peak > 100.0 && peak < 101.0, "{peak}"); + } + + #[test] + fn a_high_target_black_keeps_the_output_rising_and_lands_the_peak() { + let cases = [(100.0, 100.0), (50.0, 100.0), (10.0, 100.0), (1.0, 100.0), (0.1, 1000.0), (40.0, 4000.0), (2000.0, 4000.0)]; + for (black, peak) in cases { + let curve = Eetf::new(0.0, 1000.0, black, peak); + // A target black above the 1000-nit source peak reads as the source peak. + let want = f64::min(black, 1000.0); + assert!((curve.apply_nits(0.0) - want).abs() < 1e-2 * want.max(1.0), "{black} {peak}: {}", curve.apply_nits(0.0)); + // From minLum 0.5 the lift reaches 0 at the top of the output. + let top = curve.apply_nits(1000.0); + if curve.min_lum >= 0.5 { + assert!((top - f64::min(peak, 1000.0)).abs() < 1e-2 * peak, "{black} {peak}: {top}"); + } + let mut last = curve.apply_pq(0.0); + for i in 1..=1000 { + let out = curve.apply_pq(f64::from(i) / 1000.0); + assert!(out >= last - 1e-12, "{black} {peak} at {i}: {out} < {last}"); + last = out; + } + } + } + + #[test] + fn the_output_changes_continuously_with_the_target_black() { + for peak in [100.0, 300.0, 4000.0] { + let at = |black: f64, n: f64| Eetf::new(0.0, 1000.0, black, peak).apply_pq(pq(n)); + // Target blacks 1/20 000 of the target peak's PQ value apart. + let black = |i: u32| nits(f64::from(i) / 20_000.0 * pq(peak)); + for n in [0.0, 1.0, 100.0, 1000.0] { + let mut last = at(0.0, n); + for i in 1..=20_000 { + let out = at(black(i), n); + assert!((out - last).abs() < 1e-3, "peak {peak}, input {n}, black {}: {last} to {out}", black(i)); + last = out; + } + } + } + } + + #[test] + fn tone_map_keeps_hue_and_maps_the_peak() { + let tm = ToneMap::new(1000.0, 203.0); + let peak = 1000.0 / 203.0; + let out = tm.apply([peak, peak * 0.5, peak * 0.25]); + assert!((out[0] - 1.0).abs() < 1e-3, "{out:?}"); + assert!((out[1] / out[0] - 0.5).abs() < 1e-6 && (out[2] / out[0] - 0.25).abs() < 1e-6); + let low = tm.apply([0.02, 0.01, 0.0]); + assert!((low[0] - 0.02).abs() < 1e-4, "{low:?}"); + assert_eq!(tm.apply([0.0, 0.0, 0.0]), [0.0, 0.0, 0.0]); + assert_eq!(tm.apply([-1.0, -2.0, -0.5]), [-1.0, -2.0, -0.5]); + } + + /// With a target peak above the source peak nothing changes, highlights above the source + /// peak included (they are not raised to the target peak). + #[test] + fn a_brighter_target_leaves_colors_alone() { + let tm = ToneMap::new(1000.0, 4000.0); + assert!(tm.is_identity()); + let hot = [1200.0 / 203.0, 0.5, 0.1]; + assert_eq!(tm.apply(hot), hot); + } + + #[test] + fn hostile_values_do_not_panic_or_spread() { + let tm = ToneMap::new(f64::NAN, f64::INFINITY); + assert!(tm.is_identity()); + let huge = ToneMap::with_reference_white(1000.0, 100.0, 1e100); + assert!((huge.apply([1.0, 1.0, 1.0])[0] - 100.0 / 10_000.0).abs() < 1e-4, "{:?}", huge.apply([1.0, 1.0, 1.0])); + let tm = ToneMap::with_reference_white(1000.0, 100.0, -3.0); + // max() skips NaN, so the other channels are mapped by their own maximum. + assert!(tm.apply([f32::NAN, 0.5, 0.5]).iter().skip(1).all(|v| v.is_finite())); + assert_eq!(tm.apply([f32::INFINITY, 0.5, 0.0]), [100.0 / 203.0, 0.0, 0.0]); + assert_eq!(tm.apply([f32::MAX, f32::MAX, 0.0]), [100.0 / 203.0, 100.0 / 203.0, 0.0]); + // A target peak below the source black: the peak still lands on the target peak. + let dim = Eetf::new(100.0, 1000.0, 0.0, 50.0); + assert!((dim.apply_nits(1000.0) - 50.0).abs() < 0.05, "{}", dim.apply_nits(1000.0)); + assert!(Eetf::new(0.0, 1000.0, 500.0, 100.0).apply_nits(0.0) <= 100.0 + 0.05); + let e = Eetf::new(500.0, 100.0, 0.0, 50.0); + assert!(e.is_identity()); + assert_eq!(e.apply_pq(0.3), 0.3); + assert!(Eetf::new(0.0, 1000.0, 0.0, 100.0).apply_pq(f64::NAN).is_nan()); + } + + /// A target peak that is NaN, 0 or negative passes the picture through instead of turning it + /// black. + #[test] + fn a_missing_target_peak_passes_values_through() { + for peak in [f64::NAN, 0.0, -100.0, f64::NEG_INFINITY] { + let tm = ToneMap::new(1000.0, peak); + assert!(tm.is_identity(), "{peak}"); + assert_eq!(tm.apply([0.8, 0.5, 0.1]), [0.8, 0.5, 0.1], "{peak}"); + assert!(Eetf::new(0.0, 1000.0, 0.0, peak).is_identity(), "{peak}"); + } + } +} diff --git a/crates/color-ui/src/ui/area.rs b/crates/color-ui/src/ui/area.rs index 2661e3290..a74650e80 100644 --- a/crates/color-ui/src/ui/area.rs +++ b/crates/color-ui/src/ui/area.rs @@ -39,8 +39,9 @@ pub struct ColorAreaStyle { /// The area keeps its axes right to left: across still grows to the right. Its value text names both components /// ("Saturation 40 %, Brightness 70 %", from [`names`](ColorArea::names)). /// -/// It is at least `size.plot` and fills the width its row leaves; with `Props::sizing(Sizing::Fill)` it takes the room -/// on both axes, however small (the Color panel's field, as tall as its dock group leaves it). +/// Its size comes from its [`shape`](ColorArea::shape), never from the room: the compact pickers' field at plot +/// proportions, or the Color Picker dialog's square. With `Props::sizing(Sizing::Fill)` it takes the room on both axes +/// instead, however small (the Color panel's field, as tall as its dock group leaves it). #[derive(craft_ui::contract::Component, craft_ui::contract::Props)] pub struct ColorArea<'a> { #[common] @@ -56,12 +57,27 @@ pub struct ColorArea<'a> { /// The names of the across and down components in the value text; the model's channel names without them. #[prop] names: Option<[Label; 2]>, + /// The size of an area that does not fill its room; plot proportions by default. + #[prop] + shape: AreaShape, +} + +/// The size of a [`ColorArea`] that does not fill its room. +#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash)] +#[non_exhaustive] +pub enum AreaShape { + /// `size.plot.width` wide and `size.plot.height` tall: the field of the Color panel's popover and the compact + /// pickers, wider than tall. + #[default] + Plot, + /// A square `size.plot.width` on a side: the Color Picker dialog's field, as Photoshop's. + Square, } impl<'a> ColorArea<'a> { /// An area named `label` ("Saturation and brightness") showing `values`, values of `mode`'s model. pub fn new(label: impl Into