diff --git a/.github/workflows/actions.lock b/.github/workflows/actions.lock index c7f0a2e6b..496d685c3 100644 --- a/.github/workflows/actions.lock +++ b/.github/workflows/actions.lock @@ -50,6 +50,7 @@ workflows: - 'actions/checkout@v7.0.1' - 'dtolnay/rust-toolchain@stable' - 'step-security/harden-runner@v2.22.4' + '.github/workflows/full-validation.yml': [] '.github/workflows/house-rules.yml': [] '.github/workflows/jpeg.yml': - 'actions/checkout@v7.0.1' 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/workspace.yml b/.github/workflows/workspace.yml index 380f453ee..dac20b9d2 100644 --- a/.github/workflows/workspace.yml +++ b/.github/workflows/workspace.yml @@ -70,7 +70,12 @@ jobs: python3 scripts/test-workspace-concurrency.py python3 scripts/test-workspace-tests.py fi - cargo fmt --check + # 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 diff --git a/ATTRIBUTION.md b/ATTRIBUTION.md index de712b4ee..f5a4217d8 100644 --- a/ATTRIBUTION.md +++ b/ATTRIBUTION.md @@ -146,6 +146,10 @@ Sanitization, animation fitting and numeric output policy remain caller-owned. `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. @@ -161,6 +165,14 @@ Sanitization, animation fitting and numeric output policy remain caller-owned. `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. diff --git a/Cargo.lock b/Cargo.lock index 199298376..263fc929a 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" @@ -1747,6 +1758,7 @@ dependencies = [ "craft-cms", "craft-codepage", "craft-color", + "craft-color-transform", "craft-color-ui", "craft-control", "craft-control-protocol", @@ -1757,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", @@ -1772,6 +1787,8 @@ dependencies = [ "craft-elf", "craft-eps", "craft-epub", + "craft-esign", + "craft-evm", "craft-ews", "craft-exr", "craft-fcproj-format", @@ -1790,6 +1807,7 @@ dependencies = [ "craft-frame", "craft-gainmap", "craft-gcode", + "craft-geom", "craft-gif", "craft-gridcraft-format", "craft-gzip", @@ -1882,6 +1900,7 @@ dependencies = [ "craft-stencilcraft-document", "craft-stencilcraft-format", "craft-stream-codecs", + "craft-suite-account", "craft-svg", "craft-table", "craft-tar", @@ -1909,6 +1928,7 @@ dependencies = [ "craft-window", "craft-wordmodel", "craft-xcf", + "craft-xfa", "craft-xfdf", "craft-xfl", "craft-xls", @@ -1966,7 +1986,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", @@ -2128,6 +2148,7 @@ name = "craft-cloud-ui" version = "0.1.0" dependencies = [ "craft-cloud", + "craft-esign", "egui", "egui_kittest", "image", @@ -2158,6 +2179,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" @@ -2182,10 +2213,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]] @@ -2273,6 +2309,36 @@ dependencies = [ "thiserror 2.0.21", ] +[[package]] +name = "craft-develop" +version = "0.1.0" +dependencies = [ + "craft-develop-model", + "proptest", + "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" @@ -2321,6 +2387,7 @@ dependencies = [ "craft-wordmodel", "image", "log", + "md4", "miniz_oxide 0.9.1", "proptest", "serde_json", @@ -2462,6 +2529,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" @@ -2695,6 +2782,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" @@ -2825,6 +2920,7 @@ dependencies = [ "craft-dds", "craft-heif", "craft-jpeg", + "craft-jxl", "craft-media-testkit", "craft-metadata", "craft-tiff", @@ -2896,6 +2992,7 @@ dependencies = [ name = "craft-java-class" version = "0.1.0" dependencies = [ + "craft-testkit", "serde", "thiserror 2.0.21", ] @@ -2938,6 +3035,7 @@ dependencies = [ name = "craft-jxl" version = "0.1.0" dependencies = [ + "brotli-decompressor 5.0.3", "craft-cms", "jixel", "jxl-oxide", @@ -3834,6 +3932,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" @@ -3842,11 +3955,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", @@ -3876,6 +3992,7 @@ dependencies = [ name = "craft-tar" version = "0.1.0" dependencies = [ + "craft-testkit", "serde", ] @@ -4319,6 +4436,7 @@ dependencies = [ name = "craft-wasm" version = "0.1.0" dependencies = [ + "craft-testkit", "serde", "thiserror 2.0.21", "wasmparser 0.261.0", @@ -4413,6 +4531,13 @@ dependencies = [ "thiserror 2.0.21", ] +[[package]] +name = "craft-xfa" +version = "0.1.0" +dependencies = [ + "craft-xml", +] + [[package]] name = "craft-xfdf" version = "0.1.0" @@ -5385,7 +5510,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", @@ -6042,6 +6167,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" @@ -6062,6 +6198,7 @@ checksum = "0d50a92467f8ba5dd6e3ee5d4bd04d73ab2e4e1c44474a0674821dfce14b79bc" dependencies = [ "futures-core", "futures-io", + "futures-macro", "futures-sink", "futures-task", "memchr", @@ -6709,6 +6846,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" @@ -7744,6 +7890,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" @@ -8094,6 +8261,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" @@ -9447,7 +9623,7 @@ dependencies = [ "generic-array", "getrandom 0.2.17", "hex", - "hkdf", + "hkdf 0.12.4", "idea", "k256", "log", @@ -11033,6 +11209,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" @@ -13875,6 +14070,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" @@ -14502,6 +14710,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" diff --git a/Cargo.toml b/Cargo.toml index b448d8fc6..4e7ad18c7 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -11,6 +11,8 @@ 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" } @@ -60,6 +62,9 @@ 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" } @@ -70,6 +75,7 @@ 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" } @@ -96,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" } @@ -105,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" } @@ -137,7 +142,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" } @@ -185,6 +190,9 @@ craft-pst = { path = "crates/pst" } craft-quit = { path = "crates/quit" } 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" } @@ -193,6 +201,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" } diff --git a/crates/cloud-ui/Cargo.toml b/crates/cloud-ui/Cargo.toml index 45cc4306f..21dab37ab 100644 --- a/crates/cloud-ui/Cargo.toml +++ b/crates/cloud-ui/Cargo.toml @@ -12,9 +12,11 @@ workspace = true [dependencies] egui = { workspace = true } -# The vendor-neutral vocabulary the share dialog speaks. No IO and no -# vendor, so this stays buildable for the web. +# 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 } @@ -26,6 +28,8 @@ 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"] } 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 index 74e2a1ad8..6ac9f56e0 100644 --- a/crates/cloud-ui/src/lib.rs +++ b/crates/cloud-ui/src/lib.rs @@ -1,19 +1,21 @@ #![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 account menu and the presence bar that -//! every Craft app shares. +//! 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`, `share` -//! and `presence` from here, with the same `share` and `cloud` features, so `craft_ui::…` paths -//! stay as on main. +//! 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")] 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/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/control/Cargo.toml b/crates/control/Cargo.toml index 0a18ccc99..5c4a90242 100644 --- a/crates/control/Cargo.toml +++ b/crates/control/Cargo.toml @@ -10,6 +10,12 @@ repository.workspace = true [lints] workspace = true +[features] +default = [] +# AI agents in the open window (desktop): the ArtCraft Launcher's switch, the connection file and +# the `-cli mcp` side that finds the open window. The agent settings build without it. +agents = ["dep:craft-ai-agents", "dep:craft-atomic", "dep:craft-flags", "dep:log"] + [dependencies] serde = { workspace = true } serde_json = { workspace = true } @@ -18,6 +24,16 @@ serde_json = { workspace = true } [target.'cfg(not(target_arch = "wasm32"))'.dependencies] # The per-launch control token: 32 random bytes from the operating system (MIT OR Apache-2.0). getrandom = "0.3" +# The launcher's app list, read in one place for the launcher, the gateway and every app (MIT OR Apache-2.0, ours). +craft-ai-agents = { workspace = true, optional = true } +craft-atomic = { workspace = true, optional = true } +craft-flags = { workspace = true, optional = true } +log = { workspace = true, optional = true } [dev-dependencies] proptest = { workspace = true } +tempfile = "3" + +[[test]] +name = "agents" +required-features = ["agents"] diff --git a/crates/control/src/agents/connection.rs b/crates/control/src/agents/connection.rs new file mode 100644 index 000000000..0c0bcebc7 --- /dev/null +++ b/crates/control/src/agents/connection.rs @@ -0,0 +1,115 @@ +//! The connection file: where an app's control server listens for agents. + +use std::net::{SocketAddr, TcpStream}; +use std::path::{Path, PathBuf}; +use std::time::Duration; + +use serde::{Deserialize, Serialize}; + +/// The connection file in the app's settings folder, present while the app accepts agents. +pub const CONNECTION_FILE: &str = "agent-connection.json"; +/// The token file the app keeps in its settings folder for agent connections. +pub const TOKEN_FILE: &str = "agent-control.token"; +/// How long [`probe`] waits for a connection to be accepted. +pub const PROBE_TIMEOUT: Duration = Duration::from_millis(500); +/// The version of the [`Connection`] file format. +const CONNECTION_VERSION: u32 = 1; +/// The largest connection file read; anything bigger is not one. +const MAX_CONNECTION_BYTES: u64 = 1 << 20; + +/// What an app publishes in [`CONNECTION_FILE`]: `{"version", "pid", "port", "tokenFile", "app"}`. +/// Holds no secret: the token stays in its own owner-only file. +#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)] +#[serde(rename_all = "camelCase")] +pub struct Connection { + /// The file format's version (1). + pub version: u32, + /// The app's process id: only that process removes the file. + pub pid: u32, + /// The loopback port of the control server. + pub port: u16, + /// The file holding the token. + pub token_file: PathBuf, + /// The app's version, for diagnostics. + pub app: String, +} + +impl Connection { + /// This process's connection on `port`, naming `app` (the app's version string). + pub fn new(port: u16, token_file: PathBuf, app: impl Into) -> Self { + Self { version: CONNECTION_VERSION, pid: std::process::id(), port, token_file, app: app.into() } + } + + /// `127.0.0.1:`. + pub fn addr(&self) -> String { + format!("127.0.0.1:{}", self.port) + } +} + +fn io_error(path: &Path, e: impl std::fmt::Display) -> std::io::Error { + std::io::Error::other(format!("{}: {e}", path.display())) +} + +/// Publishes `c` in `dir` (made if missing), written atomically so a reader never sees half a +/// file. +pub fn write_connection(dir: &Path, c: &Connection) -> std::io::Result<()> { + std::fs::create_dir_all(dir).map_err(|e| io_error(dir, e))?; + let path = dir.join(CONNECTION_FILE); + let text = serde_json::to_string_pretty(c).map_err(|e| io_error(&path, e))?; + craft_atomic::atomic_write(&path, text.as_bytes()).map_err(|e| io_error(&path, e)) +} + +/// The connection published in `dir`, if any. A file of another version, with port 0, or one +/// that does not parse (invalid UTF-8 included) counts as none: the app rewrites it when it next +/// starts listening. Anything but a regular file (a FIFO would block the read) or a file over +/// 1 MiB is an error, and left alone. +pub fn read_connection(dir: &Path) -> std::io::Result> { + let path = dir.join(CONNECTION_FILE); + let meta = match std::fs::metadata(&path) { + Ok(m) => m, + Err(e) if e.kind() == std::io::ErrorKind::NotFound => return Ok(None), + Err(e) => return Err(io_error(&path, e)), + }; + if !meta.is_file() { + return Err(io_error(&path, "not a regular file")); + } + if meta.len() > MAX_CONNECTION_BYTES { + return Err(io_error(&path, format!("larger than {MAX_CONNECTION_BYTES} bytes"))); + } + let bytes = match std::fs::read(&path) { + Ok(b) => b, + Err(e) if e.kind() == std::io::ErrorKind::NotFound => return Ok(None), + Err(e) => return Err(io_error(&path, e)), + }; + Ok(serde_json::from_slice::(&bytes).ok().filter(|c| c.version == CONNECTION_VERSION && c.port != 0)) +} + +/// Removes the connection file in `dir` if process `pid` wrote it (another instance may have +/// published its own since). Errors are ignored: a stale file only fails [`probe`]. +pub fn remove_connection(dir: &Path, pid: u32) { + if let Ok(Some(c)) = read_connection(dir) + && c.pid == pid + { + let _ = std::fs::remove_file(dir.join(CONNECTION_FILE)); + } +} + +/// Removes the connection file in `dir` when nothing listens on its port any more (an app that +/// crashed or quit without removing it), or when it does not read as a connection. A live +/// instance's file is kept, and so is anything but a regular file. Errors are ignored. +pub fn remove_stale_connection(dir: &Path) { + let path = dir.join(CONNECTION_FILE); + let stale = match read_connection(dir) { + Ok(Some(c)) => !probe(c.port, PROBE_TIMEOUT), + Ok(None) => path.is_file(), + Err(_) => false, + }; + if stale { + let _ = std::fs::remove_file(path); + } +} + +/// Whether something accepts connections on loopback `port` within `timeout`; port 0 never does. +pub fn probe(port: u16, timeout: Duration) -> bool { + port != 0 && TcpStream::connect_timeout(&SocketAddr::from(([127, 0, 0, 1], port)), timeout).is_ok() +} diff --git a/crates/control/src/agents/live.rs b/crates/control/src/agents/live.rs new file mode 100644 index 000000000..49b242ff5 --- /dev/null +++ b/crates/control/src/agents/live.rs @@ -0,0 +1,601 @@ +//! The other end of the link: where an app's `-cli mcp` sends each tool call. +//! +//! [`Live::resolve`] runs before every tool call. It reads the connection file the app publishes +//! while it accepts agents ([`super::write_connection`]), so the app may start, quit or move to another port +//! while the MCP client stays connected, and the client's configuration holds no port and no +//! token: +//! +//! - An app that accepts agents: the call goes to its open window ([`Route::Window`]). The same +//! port, token and process id keep the window client the app made; any change makes a new one. +//! - No app accepts agents, and the person doesn't let agents use it ([`Consent::allowed`] off, or +//! [`AgentSettings::allow_agent_control`] off, under which the app doesn't listen either): a +//! session without a window with only the folders given to the command +//! ([`LiveConfig::read_roots`], [`LiveConfig::write_root`]), as `mcp` always worked. The app's own +//! folders are for agents the person let in. +//! - No app accepts agents, but agents are allowed: the closed-app choice decides +//! ([`LiveConfig::when_closed`], otherwise [`AgentSettings::when_app_closed`]): start the app and +//! wait until it accepts agents, a headless session with the app's agent folders (the command's +//! folders win), or an error that says what to do. +//! +//! Once headless, the session stays headless: documents don't move under the agent. Only a session +//! made with the app's agent folders ends when the person stops letting agents in; the next call +//! gets one with the command's folders. A window route is dropped as soon as no app accepts agents. +//! Lookups are +//! serialised, so concurrent calls start the app once: calls that queued while a start was under +//! way and found no window get that start's error rather than starting the app again; a call made +//! after it tries again. +//! +//! The crate has no async runtime: `resolve` blocks (file reads, a loopback probe, and while an +//! app starts, polling), so an async MCP server calls it from its blocking pool. What a window +//! client and a headless session are stays the app's ([`LiveConfig::new`]'s `connect` and +//! `headless`), and so do the tools and the transport. Errors are the tool call's result: words +//! for the agent, and through it the person, naming the app. + +use std::ffi::{OsStr, OsString}; +use std::fmt; +use std::path::{Path, PathBuf}; +use std::sync::atomic::{AtomicU64, Ordering}; +use std::sync::{Mutex, PoisonError}; +use std::time::{Duration, Instant}; + +use super::{AgentSettings, Connection, PROBE_TIMEOUT, WhenAppClosed, probe, read_connection}; + +/// Starts the desktop app; see [`launcher`]. +pub type LaunchFn = Box Result<(), String> + Send + Sync>; +/// What the person allows now, read from the app's settings folder before every call. +pub type ConsentFn = Box Consent + Send + Sync>; +/// Makes the app's client for its open window. +pub type ConnectFn = Box Result + Send + Sync>; +/// Makes the app's headless session with these folders. +pub type HeadlessFn = Box Result + Send + Sync>; + +/// How long a started app gets to accept agents. A first start can take a while (GPU shader +/// caches, a font scan), but MCP clients give a tool call about a minute. +pub const LAUNCH_TIMEOUT: Duration = Duration::from_secs(45); +/// How often a starting app's connection file is looked for. +pub const LAUNCH_POLL: Duration = Duration::from_millis(250); +/// The longest [`LiveConfig::launch_timeout`] used; a longer one is cut to this. +const MAX_LAUNCH_TIMEOUT: Duration = Duration::from_secs(600); +/// The range [`LiveConfig::poll`] is kept in. +const POLL_RANGE: (Duration, Duration) = (Duration::from_millis(1), Duration::from_secs(1)); + +/// The open window a call goes to: from the connection file, with the token from its token file. +#[derive(Clone, PartialEq, Eq)] +#[non_exhaustive] +pub struct Window { + /// The loopback port of the app's control server. + pub port: u16, + /// The app's process id. + pub pid: u32, + /// The control token, as its token file holds it (trimmed). + pub token: String, +} + +impl Window { + /// `127.0.0.1:`. + pub fn addr(&self) -> String { + format!("127.0.0.1:{}", self.port) + } +} + +impl fmt::Debug for Window { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + // Never the token: Debug output ends up in logs. + f.debug_struct("Window").field("port", &self.port).field("pid", &self.pid).finish_non_exhaustive() + } +} + +/// Whether the person lets agents use the app now, and its agent settings. +#[derive(Clone, Debug, Default, PartialEq, Eq)] +#[non_exhaustive] +pub struct Consent { + /// Agents may use the app: `agents_allowed(mcp_flag(), launcher_allows(""), legacy)` + /// ([`super::agents_allowed`]), with the suite's `AI-MCP` flag the ArtCraft Launcher's switch. + /// [`Live`] also requires [`AgentSettings::allow_agent_control`]. + pub allowed: bool, + /// The app's agent settings (closed-app choice, folders). + pub settings: AgentSettings, +} + +impl Consent { + /// `allowed` with these settings. + pub fn new(allowed: bool, settings: AgentSettings) -> Self { + Self { allowed, settings } + } +} + +/// The folders a headless session may open from and save to. +#[derive(Clone, Debug, Default, PartialEq, Eq)] +#[non_exhaustive] +pub struct HeadlessFolders { + /// Folders files may be opened from. + pub read: Vec, + /// The folder files may be saved to. + pub write: Option, +} + +/// Where a tool call goes: the app's window client or its headless session. +#[derive(Clone, Debug)] +pub enum Route { + /// The open window. + Window(W), + /// A session without a window. + Headless(H), +} + +/// What [`Live`] needs from the app. +#[non_exhaustive] +pub struct LiveConfig { + /// The app's name in messages (`"PhotoCraft"`). + pub app_name: String, + /// The app's settings folder: connection file, token file and settings. + pub config_dir: PathBuf, + /// Overrides the app's closed-app choice (the CLI's `--when-closed`). + pub when_closed: Option, + /// Folders a headless session may open from (the CLI's read roots); while agents are allowed + /// they replace the app's read folder. + pub read_roots: Vec, + /// The folder a headless session may save to (the CLI's write root); while agents are allowed + /// it replaces the app's write folder. + pub write_root: Option, + /// Starts the app; `None` when this install can't ([`launcher`] found nothing to start). + pub launch: Option, + /// How long a started app gets to accept agents ([`LAUNCH_TIMEOUT`]; at most 10 minutes). + pub launch_timeout: Duration, + /// How often a starting app is looked for ([`LAUNCH_POLL`]; kept between 1 ms and 1 s). + pub poll: Duration, + consent: ConsentFn, + connect: ConnectFn, + headless: HeadlessFn, +} + +impl LiveConfig { + /// The app `app_name` with its settings in `config_dir`: `consent` reads whether agents may + /// use it, `connect` makes a client for its open window, `headless` a session without one. + pub fn new( + app_name: impl Into, + config_dir: PathBuf, + consent: impl Fn(&Path) -> Consent + Send + Sync + 'static, + connect: impl Fn(&Window) -> Result + Send + Sync + 'static, + headless: impl Fn(&HeadlessFolders) -> Result + Send + Sync + 'static, + ) -> Self { + Self { + app_name: app_name.into(), + config_dir, + when_closed: None, + read_roots: Vec::new(), + write_root: None, + launch: None, + launch_timeout: LAUNCH_TIMEOUT, + poll: LAUNCH_POLL, + consent: Box::new(consent), + connect: Box::new(connect), + headless: Box::new(headless), + } + } +} + +/// The port, token and process id a window client was made for: a restarted app may keep its +/// port and token, but its old socket is gone. +type WindowKey = (u16, String, u32); +/// The route the last call took. +struct Current { + route: Route, + /// For a window, the key its client was made for. + key: Option, + /// A headless session that holds folders of the app's agent settings: it lasts only while + /// the person lets agents in. + app_folders: bool, +} + +/// Resolves each tool call of one MCP session; see the module docs. +pub struct Live { + cfg: LiveConfig, + /// Serialises lookups, so concurrent calls start the app once; holds the last start's error. + lookup: Mutex>, + /// How many starts have finished, read before a call queues for `lookup`. + finished: AtomicU64, + current: Mutex>>, +} + +impl Live { + /// A session that has not resolved anything yet. + pub fn new(cfg: LiveConfig) -> Self { + Self { cfg, lookup: Mutex::new(None), finished: AtomicU64::new(0), current: Mutex::new(None) } + } + + /// The route the last [`Self::resolve`] chose, if any. + pub fn current(&self) -> Option> { + self.current.lock().unwrap_or_else(PoisonError::into_inner).as_ref().map(|c| c.route.clone()) + } + + fn set(&self, route: Route, key: Option, app_folders: bool) -> Route { + *self.current.lock().unwrap_or_else(PoisonError::into_inner) = Some(Current { route: route.clone(), key, app_folders }); + route + } + + /// The headless session to keep using, if any: one made with the app's folders only while + /// agents are still `allowed`. A route that may not be kept is dropped. + fn sticky_headless(&self, allowed: bool) -> Option> { + let mut current = self.current.lock().unwrap_or_else(PoisonError::into_inner); + match current.as_ref() { + Some(c) if matches!(c.route, Route::Headless(_)) && (allowed || !c.app_folders) => Some(c.route.clone()), + Some(c) if matches!(c.route, Route::Headless(_)) => { + *current = None; + None + } + _ => None, + } + } + + /// Forgets a window route: no app accepts agents any more, so its client is for a socket + /// that is gone. + fn drop_window(&self) { + let mut current = self.current.lock().unwrap_or_else(PoisonError::into_inner); + if current.as_ref().is_some_and(|c| matches!(c.route, Route::Window(_))) { + *current = None; + } + } + + /// Where the next tool call goes. Blocks; see the module docs. The error is the tool call's + /// result. + pub fn resolve(&self) -> Result, String> { + let queued_at = self.finished.load(Ordering::Acquire); + let mut last_failure = self.lookup.lock().unwrap_or_else(PoisonError::into_inner); + let consent = (self.cfg.consent)(&self.cfg.config_dir); + // Allow Agent Control off refuses agents, as the app does: it doesn't listen then. + let allowed = consent.allowed && consent.settings.allow_agent_control; + if let Some(route) = self.sticky_headless(allowed) { + return Ok(route); + } + if let Some(window) = self.find_app()? { + return self.use_window(window); + } + self.drop_window(); + let app = &self.cfg.app_name; + if !allowed { + let folders = HeadlessFolders { read: self.cfg.read_roots.clone(), write: self.cfg.write_root.clone() }; + return self.headless(&folders, false, &format!("{app} can't use the automation roots")); + } + match self.cfg.when_closed.unwrap_or(consent.settings.when_app_closed) { + WhenAppClosed::Error => Err(format!("{app} isn't running: open it, then try again.")), + WhenAppClosed::Headless => { + let app_read = self.cfg.read_roots.is_empty() && consent.settings.read_folder().is_some(); + let app_write = self.cfg.write_root.is_none() && consent.settings.write_folder().is_some(); + let read = + if self.cfg.read_roots.is_empty() { consent.settings.read_folder().into_iter().collect() } else { self.cfg.read_roots.clone() }; + let write = self.cfg.write_root.clone().or_else(|| consent.settings.write_folder()); + let why = format!("{app} isn't running and its agent folders can't be used"); + self.headless(&HeadlessFolders { read, write }, app_read || app_write, &why) + } + WhenAppClosed::Launch => { + // A start finished while this call waited and the app still isn't there: its answer + // is this call's too, rather than a second start of an app that may be opening. + if self.finished.load(Ordering::Acquire) != queued_at + && let Some(failure) = last_failure.as_ref() + { + return Err(failure.clone()); + } + let started = self.launch_and_wait(); + *last_failure = started.as_ref().err().cloned(); + self.finished.fetch_add(1, Ordering::AcqRel); + started + } + } + } + + /// A headless session with `folders` from now on; `app_folders` when some of them are the + /// app's agent folders. `why` leads its error. + fn headless(&self, folders: &HeadlessFolders, app_folders: bool, why: &str) -> Result, String> { + let session = (self.cfg.headless)(folders).map_err(|e| format!("{why}: {e}"))?; + Ok(self.set(Route::Headless(session), None, app_folders)) + } + + /// Starts the app and waits until it accepts agents, at most the launch timeout. + fn launch_and_wait(&self) -> Result, String> { + let app = &self.cfg.app_name; + let Some(launch) = &self.cfg.launch else { + return Err(format!("{app} isn't running, and this install can't start it from here: open {app}, then try again.")); + }; + launch().map_err(|e| format!("couldn't start {app}: {e}"))?; + let timeout = self.cfg.launch_timeout.min(MAX_LAUNCH_TIMEOUT); + let started = Instant::now(); + let deadline = started.checked_add(timeout).unwrap_or(started); + let poll = self.cfg.poll.clamp(POLL_RANGE.0, POLL_RANGE.1); + loop { + std::thread::sleep(poll); + if let Some(window) = self.find_app()? { + return self.use_window(window); + } + if Instant::now() >= deadline { + return Err(format!( + "{app} didn't accept agents within {} s of starting. If it's still opening, try again in a moment; otherwise check that AI agents are on in ArtCraft Launcher › Settings › AI agents.", + timeout.as_secs() + )); + } + } + } + + /// The client for `window`: the one made for the same port, token and process, or a new one. + fn use_window(&self, window: Window) -> Result, String> { + let key: WindowKey = (window.port, window.token.clone(), window.pid); + { + let current = self.current.lock().unwrap_or_else(PoisonError::into_inner); + if let Some(c) = current.as_ref() + && c.key.as_ref() == Some(&key) + { + return Ok(c.route.clone()); + } + } + let client = (self.cfg.connect)(&window).map_err(|e| format!("couldn't reach {}'s window: {e}", self.cfg.app_name))?; + Ok(self.set(Route::Window(client), Some(key), false)) + } + + /// The app accepting agents now: `None` when there is no connection file, or one left by an + /// app that crashed (nothing listens on its port). + fn find_app(&self) -> Result, String> { + find_window(&self.cfg.config_dir, &self.cfg.app_name) + } +} + +/// The window accepting agents with its settings in `dir`, with the token from its token file; +/// `None` when no app accepts agents there. `app_name` names the app in errors. +pub fn find_window(dir: &Path, app_name: &str) -> Result, String> { + let Some(c): Option = read_connection(dir).map_err(|e| e.to_string())? else { return Ok(None) }; + if !probe(c.port, PROBE_TIMEOUT) { + return Ok(None); + } + let token = read_token(&c.token_file).map_err(|e| format!("{app_name}'s agent token: {e}"))?; + Ok(Some(Window { port: c.port, pid: c.pid, token })) +} + +/// The largest token file read; a token is far shorter. +const MAX_TOKEN_FILE: u64 = 4096; + +/// The token in the token file at `path`, trimmed and otherwise as written: the app's server +/// compares it exactly ([`crate::auth::tokens_match`]). The file must be a regular file of at most +/// [`MAX_TOKEN_FILE`] bytes holding one token (no spaces or control characters in it), and on Unix +/// readable by its owner only: a token others could read is refused rather than used. +fn read_token(path: &Path) -> Result { + use std::io::Read; + let shown = |e: &dyn fmt::Display| format!("{}: {e}", path.display()); + // Before opening: opening a FIFO for reading blocks until something writes to it. + if !std::fs::metadata(path).map_err(|e| shown(&e))?.is_file() { + return Err(shown(&"not a regular file")); + } + let file = std::fs::File::open(path).map_err(|e| shown(&e))?; + let meta = file.metadata().map_err(|e| shown(&e))?; + if !meta.is_file() { + return Err(shown(&"not a regular file")); + } + #[cfg(unix)] + { + use std::os::unix::fs::MetadataExt; + if meta.mode() & 0o077 != 0 { + return Err(shown(&format!("readable by group or others (mode {:o}); restrict it to its owner", meta.mode() & 0o777))); + } + } + let mut text = String::new(); + file.take(MAX_TOKEN_FILE + 1).read_to_string(&mut text).map_err(|e| shown(&e))?; + if text.len() as u64 > MAX_TOKEN_FILE { + return Err(shown(&format!("larger than {MAX_TOKEN_FILE} bytes"))); + } + let token = text.trim(); + if token.is_empty() || token.chars().any(|c| c.is_whitespace() || c.is_control()) { + return Err(shown(&"not a control token")); + } + Ok(token.to_owned()) +} + +/// How to start the desktop app `exe` (its file name without `.exe`) that ships beside the CLI at +/// `cli`: detached and with no standard streams, since the CLI's carry the MCP protocol and the +/// app must outlive the MCP client. `None` where this install can't start it: inside a Flatpak, +/// or with no app beside the CLI. +pub fn launcher(cli: &Path, exe: &str) -> Option { + use std::process::{Command, Stdio}; + let env = |name: &str| std::env::var_os(name).filter(|v| !v.is_empty()); + // Both sides resolved, so a mount reached through a symlink (`$TMPDIR`) still matches. + let resolved = |p: &Path| std::fs::canonicalize(p).unwrap_or_else(|_| p.to_path_buf()); + let install = Install { + platform: Platform::current(), + flatpak: env("FLATPAK_ID").is_some(), + appimage: env("APPIMAGE"), + appdir: env("APPDIR").map(|d| resolved(Path::new(&d)).into_os_string()), + system_root: env("SystemRoot"), + }; + let (program, args) = launch_command(&resolved(cli), exe, &install, &|p| p.is_file())?; + let mut command = Command::new(program); + command.args(args); + let command = Mutex::new(command); + Some(Box::new(move || { + let mut c = command.lock().unwrap_or_else(PoisonError::into_inner); + c.stdin(Stdio::null()).stdout(Stdio::null()).stderr(Stdio::null()); + detach(&mut c); + let child = c.spawn().map_err(|e| e.to_string())?; + reap(child); + Ok(()) + })) +} + +/// Waits for `child` on a thread of its own, so a start helper that exits (`open`, Explorer) or an +/// app that quits before the CLI does is reaped rather than left a zombie until the MCP client +/// ends; the app keeps running on its own either way. Without a thread the child is dropped, as +/// before. +fn reap(mut child: std::process::Child) { + let _ = std::thread::Builder::new().name("app-start-reaper".into()).spawn(move || { + let _ = child.wait(); + }); +} + +/// What [`launch_command`] needs to know about the install, from the environment. +#[derive(Clone, Debug, Default)] +struct Install { + platform: Platform, + /// Inside a Flatpak (`FLATPAK_ID`). + flatpak: bool, + /// The AppImage the running image set (`APPIMAGE`). + appimage: Option, + /// That image's mount point (`APPDIR`). + appdir: Option, + /// `%SystemRoot%` (Windows). + system_root: Option, +} + +/// The platform [`launch_command`] plans for. +#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)] +enum Platform { + Windows, + MacOs, + #[default] + Other, +} + +impl Platform { + /// The platform this build runs on. + fn current() -> Self { + if cfg!(windows) { + Self::Windows + } else if cfg!(target_os = "macos") { + Self::MacOs + } else { + Self::Other + } + } +} + +/// The program and arguments that start the app; see [`launcher`]. +fn launch_command(cli: &Path, exe: &str, install: &Install, is_file: &dyn Fn(&Path) -> bool) -> Option<(PathBuf, Vec)> { + let platform = install.platform; + if install.flatpak { + return None; + } + // Only when this CLI runs from that image's mount: a process started from another AppImage + // (an MCP client packaged as one) inherits its `APPIMAGE` too. + if let (Some(image), Some(mount)) = (&install.appimage, &install.appdir) + && cli.starts_with(mount) + { + // The AppImage's mount point goes away with the CLI; the image itself stays. + return Some((PathBuf::from(image), Vec::new())); + } + let dir = cli.parent()?; + if platform == Platform::MacOs + && dir.ends_with("Contents/MacOS") + && let Some(bundle) = dir.parent().and_then(Path::parent) + { + // A macOS app bundle: LaunchServices starts (or brings forward) the app. + return Some((PathBuf::from("/usr/bin/open"), vec![OsString::from("-a"), bundle.as_os_str().to_os_string()])); + } + let app = dir.join(if platform == Platform::Windows { format!("{exe}.exe") } else { exe.to_owned() }); + if !is_file(&app) { + return None; + } + Some(if platform == Platform::Windows { windows_launch(&app, install.system_root.as_deref()) } else { (app, Vec::new()) }) +} + +/// How Windows starts the app at `app`: through Explorer, as a double-click would. The app is then +/// no child of the CLI, so it outlives the MCP client ending the CLI's process tree (Claude Code +/// does on Windows), and it runs outside the container of a Microsoft Store client (Claude +/// Desktop): there, new files under `%APPDATA%` land in the client's package, where the app +/// started from the Start menu would never see them. Explorer reads a comma as a separator, so +/// such a path is started directly. (`%WINDIR%` can be empty under a Store client, hence +/// `%SystemRoot%`.) +fn windows_launch(app: &Path, system_root: Option<&OsStr>) -> (PathBuf, Vec) { + if app.to_string_lossy().contains(',') { + return (app.to_path_buf(), Vec::new()); + } + let root = system_root.filter(|r| !r.is_empty()).map_or_else(|| PathBuf::from(r"C:\Windows"), PathBuf::from); + (root.join("explorer.exe"), vec![app.as_os_str().to_os_string()]) +} + +/// Keeps the app running when the MCP client stops the CLI (and its process group). +fn detach(c: &mut std::process::Command) { + #[cfg(unix)] + { + use std::os::unix::process::CommandExt; + c.process_group(0); + } + #[cfg(windows)] + { + use std::os::windows::process::CommandExt; + const DETACHED_PROCESS: u32 = 0x0000_0008; + const CREATE_NEW_PROCESS_GROUP: u32 = 0x0000_0200; + c.creation_flags(DETACHED_PROCESS | CREATE_NEW_PROCESS_GROUP); + } + #[cfg(not(any(unix, windows)))] + let _ = c; +} + +#[cfg(test)] +mod tests { + #![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)] + use super::*; + + fn plan( + cli: &str, + platform: Platform, + flatpak: bool, + appimage: Option<&str>, + root: Option<&str>, + exists: bool, + ) -> Option<(PathBuf, Vec)> { + // An AppImage's mount is where its CLI runs from. + let appdir = appimage.map(|_| OsString::from("/tmp/.mount")); + let install = Install { platform, flatpak, appimage: appimage.map(OsString::from), appdir, system_root: root.map(OsString::from) }; + launch_command(Path::new(cli), "photocraft", &install, &|_| exists) + } + + #[test] + fn windows_starts_the_app_through_explorer() { + let app = Path::new(r"C:\Program Files\PhotoCraft\photocraft.exe"); + let (program, args) = windows_launch(app, Some(OsStr::new(r"D:\Win"))); + assert_eq!(program, Path::new(r"D:\Win").join("explorer.exe")); + assert_eq!(args, [app.as_os_str()]); + // No usable %SystemRoot%: the default Windows folder. + let default = Path::new(r"C:\Windows").join("explorer.exe"); + assert_eq!(windows_launch(app, Some(OsStr::new(""))).0, default); + assert_eq!(windows_launch(app, None).0, default); + // Explorer would split this path at the comma. + let comma = Path::new(r"C:\Apps, tools\photocraft.exe"); + assert_eq!(windows_launch(comma, None), (comma.to_path_buf(), Vec::new())); + } + + #[test] + fn the_launch_command_fits_the_install() { + // Flatpak: the sandbox can't start the app. + assert_eq!(plan("/app/bin/photocraft-cli", Platform::Other, true, Some("/x.AppImage"), None, true), None); + // An AppImage starts its image, not the mount point the CLI runs from. + assert_eq!( + plan("/tmp/.mount/usr/bin/photocraft-cli", Platform::Other, false, Some("/home/a/P.AppImage"), None, false), + Some((PathBuf::from("/home/a/P.AppImage"), Vec::new())) + ); + // Another AppImage's variables (an MCP client packaged as one): the app beside the CLI. + let client = plan("/opt/pc/photocraft-cli", Platform::Other, false, Some("/home/a/Client.AppImage"), None, true); + assert_eq!(client, Some((PathBuf::from("/opt/pc/photocraft"), Vec::new()))); + let no_mount = Install { appimage: Some("/home/a/P.AppImage".into()), ..Install::default() }; + assert_eq!( + launch_command(Path::new("/tmp/.mount/usr/bin/photocraft-cli"), "photocraft", &no_mount, &|_| false), + None, + "APPIMAGE without APPDIR" + ); + // A macOS bundle opens through LaunchServices. + let (program, args) = plan("/Applications/PhotoCraft.app/Contents/MacOS/photocraft-cli", Platform::MacOs, false, None, None, false).unwrap(); + assert_eq!(program, Path::new("/usr/bin/open")); + assert_eq!(args, [OsString::from("-a"), OsString::from("/Applications/PhotoCraft.app")]); + // Beside the CLI, by the app's file name. + assert_eq!(plan("/opt/pc/photocraft-cli", Platform::Other, false, None, None, true), Some((PathBuf::from("/opt/pc/photocraft"), Vec::new()))); + let (program, args) = plan(r"C:\PC\photocraft-cli.exe", Platform::Windows, false, None, Some(r"C:\Win"), true).unwrap(); + assert_eq!(program, Path::new(r"C:\Win").join("explorer.exe")); + // The app beside the CLI (on a non-Windows host the backslashes are no separators). + assert_eq!(args, [Path::new(r"C:\PC\photocraft-cli.exe").parent().unwrap().join("photocraft.exe").into_os_string()]); + // No app beside the CLI: nothing to start. + assert_eq!(plan("/opt/pc/photocraft-cli", Platform::Other, false, None, None, false), None); + assert_eq!(plan("photocraft-cli", Platform::Other, false, None, None, true).map(|p| p.0), Some(PathBuf::from("photocraft"))); + } + + #[test] + fn a_window_never_shows_its_token() { + let w = Window { port: 7, pid: 9, token: "ab".repeat(32) }; + assert!(!format!("{w:?}").contains("abab")); + assert_eq!(w.addr(), "127.0.0.1:7"); + } +} diff --git a/crates/control/src/agents/mod.rs b/crates/control/src/agents/mod.rs new file mode 100644 index 000000000..e1b0b9923 --- /dev/null +++ b/crates/control/src/agents/mod.rs @@ -0,0 +1,78 @@ +//! AI agents in the open window, with no UI toolkit: whether the person lets agents use the app, +//! how the app tells its own `-cli mcp` where it listens, and where that CLI sends each tool +//! call. +//! +//! One switch serves every Craft app: the ArtCraft Launcher's *Settings › AI agents › Let AI agents +//! use Craft apps*, which writes the launcher's app list (`craft_ai_agents`). With the suite's +//! `AI-MCP` flag on, an app lets agents in when that list names it ([`AgentSwitch`]); without the +//! flag, the app's own earlier consent decides ([`agents_allowed`]). Apps have no agents switch of +//! their own. +//! +//! While agents may connect, the app serves its control channel on loopback with a token +//! ([`crate::server`], [`crate::auth`], or its own) and publishes where in its settings folder +//! ([`CONNECTION_FILE`]): the port, its process id and the token file. The app's `-cli mcp` +//! reads that file before every tool call ([`Live`]), so an MCP client's configuration never holds +//! a port or a token. The file holds no secret. A crashed app can leave it behind; nothing then +//! listens on its port ([`probe`]), and the app's next launch removes it +//! ([`remove_stale_connection`]). An app that quits removes its own ([`remove_connection`]). +//! +//! | 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 same formats as `craft_automation::agents` on the shared UI library's branch (`next`), +//! which adds the egui link host and the Agents page of Preferences. +//! +//! # Adding an app +//! +//! The app (its id is the one in the ArtCraft Launcher's catalog, `"gridcraft"`): +//! +//! 1. At start, [`remove_stale_connection`] in its settings folder, then +//! `AgentSwitch::watch("gridcraft", wake)`, where `wake` asks the UI for a frame. +//! 2. Agents may connect while `settings.allow_agent_control && switch.allows(legacy)` +//! ([`AgentSettings::allow_agent_control`], [`AgentSwitch::allows`]); check it again when the +//! launcher's switch wakes the app and when the person changes the setting. When it turns true, +//! listen on loopback with a token, the token in an owner-only file +//! ([`crate::auth::App::write_token_file`]), and [`write_connection`] with [`Connection::new`]; +//! when it turns false, and when the app quits, stop listening and [`remove_connection`] with +//! the app's process id. No restart, no agents switch of its own. There is one connection file +//! per settings folder: an app that runs more than one process on one folder lets only one of +//! them accept agents. +//! +//! Its `gridcraft-cli mcp`: +//! +//! 1. A [`LiveConfig`] with the app's settings folder; `consent` reads its saved +//! [`AgentSettings`] and answers `agents_allowed(mcp_flag(), launcher_allows("gridcraft"), legacy)` +//! ([`agents_allowed`], [`mcp_flag`], [`launcher_allows`]); `connect` makes the app's client for a +//! [`Window`] (its address and token); `headless` makes its session without a window for +//! [`HeadlessFolders`]. [`launcher`] starts the app beside the CLI. +//! 2. Before every tool call, [`Live::resolve`] (from a blocking thread in an async server), then +//! the call goes to the [`Route`] it returns. `--headless` skips [`Live`] altogether. + +// The links above name items of the `agents` feature; without it they have nothing to point at, +// and the docs of the settings alone still build. +#![cfg_attr(not(all(feature = "agents", not(target_arch = "wasm32"))), allow(rustdoc::broken_intra_doc_links))] + +mod settings; +pub use settings::{AgentSettings, WhenAppClosed, agents_allowed, folder}; + +#[cfg(all(feature = "agents", not(target_arch = "wasm32")))] +mod connection; +#[cfg(all(feature = "agents", not(target_arch = "wasm32")))] +mod live; +#[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, +}; +#[cfg(all(feature = "agents", not(target_arch = "wasm32")))] +pub use live::{ + ConnectFn, Consent, ConsentFn, HeadlessFn, HeadlessFolders, LAUNCH_POLL, LAUNCH_TIMEOUT, LaunchFn, Live, LiveConfig, Route, Window, find_window, + launcher, +}; +#[cfg(all(feature = "agents", not(target_arch = "wasm32")))] +pub use switch::{AgentSwitch, POLL, launcher_allows, mcp_flag}; diff --git a/crates/control/src/agents/settings.rs b/crates/control/src/agents/settings.rs new file mode 100644 index 000000000..04ae933aa --- /dev/null +++ b/crates/control/src/agents/settings.rs @@ -0,0 +1,124 @@ +//! The agent settings an app saves in its preferences, and who decides that agents may connect. + +use std::path::PathBuf; + +use serde::{Deserialize, Serialize}; + +/// The agent settings of an app's Preferences (its `integrations` section in PhotoCraft). Saved in +/// camelCase: `allowAgentControl`, `controlPort`, `readRoot`, `writeRoot`, `whenAppClosed`. +#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)] +#[serde(default, rename_all = "camelCase")] +#[non_exhaustive] +pub struct AgentSettings { + /// Off refuses every control server, `--control` included. + pub allow_agent_control: bool, + /// The loopback port agents connect to; 0 is any free port, published in the connection file. + pub control_port: u32, + /// The folder agents may open from; empty is none. Applied at once while agents are connected. + pub read_root: String, + /// The folder agents may save to; empty is none. Applied at once while agents are connected. + pub write_root: String, + /// What the app's `-cli mcp` does while agents may use the app but it is closed. + pub when_app_closed: WhenAppClosed, +} + +impl Default for AgentSettings { + fn default() -> Self { + Self { + allow_agent_control: true, + control_port: 0, + read_root: String::new(), + write_root: String::new(), + when_app_closed: WhenAppClosed::Launch, + } + } +} + +impl AgentSettings { + /// [`Self::read_root`] as a path ([`folder`]). + pub fn read_folder(&self) -> Option { + folder(&self.read_root) + } + + /// [`Self::write_root`] as a path ([`folder`]). + pub fn write_folder(&self) -> Option { + folder(&self.write_root) + } +} + +/// A folder setting as a path, trimmed; empty or blank is `None`. +pub fn folder(pref: &str) -> Option { + let pref = pref.trim(); + (!pref.is_empty()).then(|| PathBuf::from(pref)) +} + +/// What an app's `-cli mcp` does when an agent calls a tool while the app is closed. +#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash, Serialize, Deserialize)] +#[serde(rename_all = "lowercase")] +pub enum WhenAppClosed { + /// Open the app and wait for it. + #[default] + Launch, + /// Run the tool without a window. + Headless, + /// Answer with an error that asks to open the app. + Error, +} + +impl WhenAppClosed { + /// The saved names, in [`Self::ALL`] order. + pub const NAMES: &'static [&'static str] = &["launch", "headless", "error"]; + /// Every choice, in the order a menu lists them. + pub const ALL: [Self; 3] = [Self::Launch, Self::Headless, Self::Error]; + + /// The saved name. + pub fn name(self) -> &'static str { + match self { + Self::Launch => "launch", + Self::Headless => "headless", + Self::Error => "error", + } + } + + /// The choice a saved name means; `None` for any other text. + pub fn parse(name: &str) -> Option { + Self::ALL.into_iter().find(|c| c.name() == name) + } +} + +/// Whether agents may use the open window. With the suite's `AI-MCP` flag only the launcher's +/// switch decides: one switch for every Craft app, none in the app. Without the flag the app's own +/// earlier consent decides (`legacy`; PhotoCraft's is a Control Port saved before the switch). +/// Allow Agent Control off still refuses agents either way ([`AgentSettings::allow_agent_control`]). +pub fn agents_allowed(mcp_flag: bool, launcher: bool, legacy: bool) -> bool { + if mcp_flag { launcher } else { legacy } +} + +#[cfg(test)] +mod tests { + #![allow(clippy::unwrap_used)] + use super::*; + + // The saved names read back as the same choice, and nothing else reads as one. + #[test] + fn when_app_closed_names_round_trip() { + for choice in WhenAppClosed::ALL { + assert_eq!(WhenAppClosed::parse(choice.name()), Some(choice)); + assert_eq!(serde_json::to_value(choice).unwrap(), serde_json::json!(choice.name())); + } + assert_eq!(WhenAppClosed::NAMES, WhenAppClosed::ALL.map(WhenAppClosed::name)); + assert_eq!(WhenAppClosed::parse("Launch"), None); + let settings: AgentSettings = serde_json::from_str(r#"{"whenAppClosed": "headless", "controlPort": 7878}"#).unwrap(); + assert_eq!((settings.when_app_closed, settings.control_port, settings.allow_agent_control), (WhenAppClosed::Headless, 7878, true)); + } + + // A folder setting is trimmed; empty or blank means no folder. + #[test] + fn folder_preferences_are_trimmed() { + assert_eq!(folder(""), None); + assert_eq!(folder(" "), None); + assert_eq!(folder(" /work/project "), Some(PathBuf::from("/work/project"))); + let settings = AgentSettings { read_root: " /in ".into(), ..AgentSettings::default() }; + assert_eq!((settings.read_folder(), settings.write_folder()), (Some(PathBuf::from("/in")), None)); + } +} diff --git a/crates/control/src/agents/switch.rs b/crates/control/src/agents/switch.rs new file mode 100644 index 000000000..9165879dc --- /dev/null +++ b/crates/control/src/agents/switch.rs @@ -0,0 +1,94 @@ +//! The ArtCraft Launcher's switch for one app, behind the suite's `AI-MCP` flag. + +use std::sync::atomic::{AtomicBool, Ordering}; +use std::sync::{Arc, Weak}; +use std::time::Duration; + +use super::agents_allowed; + +/// How often [`AgentSwitch::watch`] reads the launcher's app list. +pub const POLL: Duration = Duration::from_secs(2); + +/// The suite's `AI-MCP` flag (`ArtCraft/flags.toml` or `CRAFT_FLAGS`). Reads the flags file; +/// what could not be read is logged. +pub fn mcp_flag() -> bool { + let flags = craft_flags::load(); + for problem in &flags.problems { + log::warn!("flags: {problem}"); + } + flags.enabled(&craft_flags::AI_MCP) +} + +/// The launcher's switch (Settings › AI agents › *Let AI agents use Craft apps*) lets agents use +/// the app `app_id`: the `AI-MCP` flag is on and the launcher's app list names the app. Reads two +/// small files; ask from a timer or a command, not every frame ([`AgentSwitch`] does that). +pub fn launcher_allows(app_id: &str) -> bool { + mcp_flag() && craft_ai_agents::allowed(app_id) +} + +/// The launcher's switch for one app, watched on a thread so a frame can ask without touching the +/// disk. The `AI-MCP` flag is read once, at [`Self::watch`]; the launcher's list every [`POLL`]. +/// Clones share one watch; the thread ends after the last clone is dropped. +#[derive(Clone, Debug)] +pub struct AgentSwitch { + mcp_flag: bool, + on: Arc, +} + +impl AgentSwitch { + /// Watches the launcher's list for `app_id`; a change logs `agents on/off` and calls `wake` (the + /// app asks for a frame there). + /// Without the `AI-MCP` flag nothing is watched: the launcher's list means nothing then. + pub fn watch(app_id: &'static str, wake: impl Fn() + Send + 'static) -> Self { + let flag = mcp_flag(); + if !flag { + return Self::fixed(false, false); + } + Self::watch_with(flag, move || craft_ai_agents::allowed(app_id), POLL, wake) + } + + /// A switch that never changes: tests, the web, an app without agents. + pub fn fixed(mcp_flag: bool, launcher: bool) -> Self { + Self { mcp_flag, on: Arc::new(AtomicBool::new(launcher)) } + } + + /// [`Self::watch`] with the flag given, `probe` asked once now and then every `poll`. + #[doc(hidden)] + pub fn watch_with(mcp_flag: bool, probe: impl Fn() -> bool + Send + 'static, poll: Duration, wake: impl Fn() + Send + 'static) -> Self { + let on = Arc::new(AtomicBool::new(probe())); + let seen: Weak = Arc::downgrade(&on); + let started = std::thread::Builder::new().name("launcher-agents".into()).spawn(move || { + loop { + std::thread::sleep(poll); + let now = probe(); + let Some(seen) = seen.upgrade() else { return }; + if seen.swap(now, Ordering::Relaxed) != now { + log::info!("ArtCraft Launcher: agents {}", if now { "on" } else { "off" }); + wake(); + } + } + }); + // Without a thread a later "off" in the launcher would never be seen: agents stay out. + if let Err(e) = started { + log::warn!("couldn't watch the ArtCraft Launcher's agents switch, so agents stay off: {e}"); + on.store(false, Ordering::Relaxed); + } + Self { mcp_flag, on } + } + + /// The `AI-MCP` flag as it was when the watch started. + pub fn mcp_flag(&self) -> bool { + self.mcp_flag + } + + /// Whether the launcher's list named the app at the last poll. + pub fn launcher(&self) -> bool { + self.on.load(Ordering::Relaxed) + } + + /// Whether agents may use the open window ([`agents_allowed`]); `legacy` is the app's own + /// earlier consent, which counts only without the flag. + pub fn allows(&self, legacy: bool) -> bool { + agents_allowed(self.mcp_flag, self.launcher(), legacy) + } +} diff --git a/crates/control/src/lib.rs b/crates/control/src/lib.rs index 26727a97c..56ce2e685 100644 --- a/crates/control/src/lib.rs +++ b/crates/control/src/lib.rs @@ -2,12 +2,15 @@ //! files ([`auth`]), the loopback server that admits a connection by the token and hands each //! request to the window ([`server`]), the client that talks to it ([`client`]), the request the //! window answers ([`ControlRequest`]), the document watch subscribed connections wait on -//! ([`DocumentWatch`]), and what a request still running does when it finishes ([`Effect`]). It +//! ([`DocumentWatch`]), what a request still running does when it finishes ([`Effect`]), and AI +//! agents in the open window behind the ArtCraft Launcher's switch ([`agents`]: its settings on +//! every target, the switch, the connection file and the CLI's side with feature `agents`). It //! needs no UI toolkit; the window's own requests over egui (`ui.screenshot`, `ui.resize`) are //! `craft-control-egui`. #![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)] #![forbid(unsafe_code)] +pub mod agents; pub mod auth; mod cancel; #[cfg(not(target_arch = "wasm32"))] diff --git a/crates/control/tests/agents.rs b/crates/control/tests/agents.rs new file mode 100644 index 000000000..95a4651eb --- /dev/null +++ b/crates/control/tests/agents.rs @@ -0,0 +1,572 @@ +//! AI agents in the open window: the launcher's switch, the connection file, and where an app's +//! `-cli mcp` sends each tool call. +// Unwrapping, expecting and panicking on failure is fine in tests, unlike in shipped code. +#![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)] + +use std::net::TcpListener; +use std::path::{Path, PathBuf}; +use std::sync::atomic::{AtomicBool, AtomicUsize, Ordering}; +use std::sync::{Arc, Mutex}; +use std::time::{Duration, Instant}; + +use craft_control::agents::{ + AgentSettings, AgentSwitch, CONNECTION_FILE, Connection, Consent, HeadlessFolders, Live, LiveConfig, Route, TOKEN_FILE, WhenAppClosed, Window, + agents_allowed, find_window, read_connection, remove_connection, remove_stale_connection, write_connection, +}; + +fn temp_dir(tag: &str) -> tempfile::TempDir { + tempfile::Builder::new().prefix(&format!("craft-agents-{tag}-")).tempdir().expect("a temp dir") +} + +/// Waits up to five seconds for `done`. +fn wait_for(mut done: impl FnMut() -> bool) -> bool { + let started = Instant::now(); + while !done() { + if started.elapsed() > Duration::from_secs(5) { + return false; + } + std::thread::sleep(Duration::from_millis(5)); + } + true +} + +const TOKEN: &str = "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"; + +/// Writes `text` as an owner-only token file, as an app's own token writer does. +fn write_token(path: &Path, text: &str) { + std::fs::write(path, text).unwrap(); + #[cfg(unix)] + { + use std::os::unix::fs::PermissionsExt; + std::fs::set_permissions(path, std::fs::Permissions::from_mode(0o600)).unwrap(); + } +} + +/// An app accepting agents in `dir`: a listener on a free loopback port, its token file and its +/// connection file. Dropping the listener leaves the file behind, as a crashed app would. +fn publish(dir: &Path) -> (TcpListener, Connection) { + let listener = TcpListener::bind("127.0.0.1:0").unwrap(); + write_token(&dir.join(TOKEN_FILE), &format!("{}\n", TOKEN.to_ascii_uppercase())); + let c = Connection::new(listener.local_addr().unwrap().port(), dir.join(TOKEN_FILE), "Test 1.0"); + write_connection(dir, &c).unwrap(); + (listener, c) +} + +// ---- The launcher's switch ---------------------------------------------------------------------- + +/// With the `AI-MCP` flag only the launcher's switch decides; without it the app's earlier consent. +#[test] +fn with_the_flag_only_the_launchers_switch_lets_agents_in() { + assert!(agents_allowed(false, false, true), "without the flag, the app's earlier consent"); + assert!(!agents_allowed(false, true, false), "the launcher's list means nothing without the flag"); + assert!(agents_allowed(true, true, false)); + assert!(!agents_allowed(true, false, true), "no second switch in the app"); + assert!(AgentSwitch::fixed(true, true).allows(false)); + assert!(!AgentSwitch::fixed(false, true).allows(false)); +} + +/// The switch follows the launcher's list within a poll, wakes the app once per change rather than +/// once per poll, and its thread ends once the last clone is dropped. +#[test] +fn the_switch_wakes_once_per_change() { + let launcher = Arc::new(AtomicBool::new(false)); + let probes = Arc::new(AtomicUsize::new(0)); + let wakes = Arc::new(AtomicUsize::new(0)); + // Held by the watch thread through its probe: gone once the thread has ended. + let alive = Arc::new(()); + let probe = { + let (launcher, probes, alive) = (launcher.clone(), probes.clone(), alive.clone()); + move || { + let _ = &alive; + probes.fetch_add(1, Ordering::Relaxed); + launcher.load(Ordering::Relaxed) + } + }; + let wake = { + let wakes = wakes.clone(); + move || { + wakes.fetch_add(1, Ordering::Relaxed); + } + }; + let switch = AgentSwitch::watch_with(true, probe, Duration::from_millis(5), wake); + let clone = switch.clone(); + assert!(!switch.launcher()); + + launcher.store(true, Ordering::Relaxed); + assert!(wait_for(|| clone.launcher()), "the switch follows the launcher"); + assert!(switch.allows(false)); + let polled = probes.load(Ordering::Relaxed); + assert!(wait_for(|| probes.load(Ordering::Relaxed) > polled + 10)); + launcher.store(false, Ordering::Relaxed); + assert!(wait_for(|| !switch.launcher())); + assert!(wait_for(|| wakes.load(Ordering::Relaxed) == 2)); + assert_eq!(wakes.load(Ordering::Relaxed), 2, "one wake per change, not per poll"); + + drop(switch); + drop(clone); + assert!(wait_for(|| Arc::strong_count(&alive) == 1), "the watch ended with the last switch"); + let after_end = probes.load(Ordering::Relaxed); + std::thread::sleep(Duration::from_millis(20)); + assert_eq!(probes.load(Ordering::Relaxed), after_end, "nothing probes after the watch ended"); +} + +// ---- The connection file ------------------------------------------------------------------------ + +/// A published connection reads back in its documented shape, and only the process that wrote it +/// removes it. +#[test] +fn a_published_connection_reads_back_and_only_its_writer_removes_it() { + let dir = temp_dir("conn"); + let dir = dir.path(); + assert_eq!(read_connection(dir).unwrap(), None, "no file"); + let c = Connection::new(7878, dir.join(TOKEN_FILE), "MyApp 1.2.3"); + write_connection(dir, &c).unwrap(); + assert_eq!(read_connection(dir).unwrap(), Some(c.clone())); + assert_eq!(c.addr(), "127.0.0.1:7878"); + let v: serde_json::Value = serde_json::from_str(&std::fs::read_to_string(dir.join(CONNECTION_FILE)).unwrap()).unwrap(); + let mut keys: Vec<_> = v.as_object().unwrap().keys().cloned().collect(); + keys.sort(); + assert_eq!(keys, ["app", "pid", "port", "tokenFile", "version"]); + assert_eq!((v["version"].as_u64(), v["port"].as_u64(), v["app"].as_str()), (Some(1), Some(7878), Some("MyApp 1.2.3"))); + + remove_connection(dir, c.pid.wrapping_add(1)); + assert!(dir.join(CONNECTION_FILE).is_file(), "another process's file stays"); + remove_connection(dir, c.pid); + assert!(!dir.join(CONNECTION_FILE).exists()); +} + +/// A damaged, foreign or port-0 file reads as none; a directory in its place is an error and is +/// left alone; a file nobody listens on is removed as stale and a live one kept. +#[test] +fn a_damaged_foreign_or_stale_connection_file_counts_as_none() { + let dir = temp_dir("bad-conn"); + let dir = dir.path(); + for text in [ + &b""[..], + b"{not json", + b"[]", + br#"{"version":2,"pid":1,"port":7878,"tokenFile":"t","app":"x"}"#, + br#"{"version":1,"pid":1,"port":0,"tokenFile":"t","app":"x"}"#, + b"\xff\xfe not utf-8", + ] { + std::fs::write(dir.join(CONNECTION_FILE), text).unwrap(); + assert_eq!(read_connection(dir).unwrap(), None, "{}", String::from_utf8_lossy(text)); + remove_stale_connection(dir); + assert!(!dir.join(CONNECTION_FILE).exists(), "an unreadable file is not a connection"); + } + + std::fs::create_dir(dir.join(CONNECTION_FILE)).unwrap(); + assert!(read_connection(dir).is_err()); + remove_stale_connection(dir); + assert!(dir.join(CONNECTION_FILE).is_dir(), "anything but a regular file is left alone"); + std::fs::remove_dir(dir.join(CONNECTION_FILE)).unwrap(); + + let live = TcpListener::bind("127.0.0.1:0").unwrap(); + let live_port = live.local_addr().unwrap().port(); + write_connection(dir, &Connection { pid: 1, ..Connection::new(live_port, dir.join(TOKEN_FILE), "x") }).unwrap(); + remove_stale_connection(dir); + assert!(dir.join(CONNECTION_FILE).is_file(), "something listens on {live_port}"); + drop(live); + let closed = TcpListener::bind("127.0.0.1:0").unwrap().local_addr().unwrap().port(); + write_connection(dir, &Connection { pid: 1, ..Connection::new(closed, dir.join(TOKEN_FILE), "x") }).unwrap(); + remove_stale_connection(dir); + assert!(!dir.join(CONNECTION_FILE).exists(), "nothing listens on {closed}"); +} + +// ---- The CLI's side ----------------------------------------------------------------------------- + +/// What the stand-in app made: a window client (its window) or a headless session (its folders), +/// with counts of each. +#[derive(Default)] +struct Made { + connects: AtomicUsize, + sessions: AtomicUsize, +} + +type TestLive = Live; + +fn config(dir: &Path, consent: Consent, made: &Arc) -> LiveConfig { + let (a, b) = (made.clone(), made.clone()); + let mut cfg = LiveConfig::new( + "Test", + dir.to_path_buf(), + move |_: &Path| consent.clone(), + move |w: &Window| { + a.connects.fetch_add(1, Ordering::Relaxed); + Ok(w.clone()) + }, + move |f: &HeadlessFolders| { + b.sessions.fetch_add(1, Ordering::Relaxed); + Ok(f.clone()) + }, + ); + cfg.poll = Duration::from_millis(5); + cfg +} + +fn settings(when: WhenAppClosed, read: &str, write: &str) -> AgentSettings { + let mut s = AgentSettings::default(); + s.when_app_closed = when; + s.read_root = read.into(); + s.write_root = write.into(); + s +} + +fn allowed(when: WhenAppClosed) -> Consent { + Consent::new(true, settings(when, "/app-in", "/app-out")) +} + +fn headless_folders(route: Result, String>) -> HeadlessFolders { + match route { + Ok(Route::Headless(f)) => f, + Ok(Route::Window(w)) => panic!("expected headless, got the window {w:?}"), + Err(e) => panic!("expected headless, got the error {e}"), + } +} + +fn window(route: Result, String>) -> Window { + match route { + Ok(Route::Window(w)) => w, + Ok(Route::Headless(f)) => panic!("expected the window, went headless with {f:?}"), + Err(e) => panic!("expected the window, got the error {e}"), + } +} + +fn paths(p: &[&str]) -> Vec { + p.iter().map(PathBuf::from).collect() +} + +/// An app accepting agents takes the call; the same port, token and process keep the client, a +/// restarted app (another process on the same port and token) gets a new one. +#[test] +fn an_open_app_takes_the_call_and_keeps_its_client_until_it_restarts() { + let dir = temp_dir("window"); + let (_listener, c) = publish(dir.path()); + let made = Arc::new(Made::default()); + // Even without consent: an app publishes its connection only while it accepts agents. + let live = TestLive::new(config(dir.path(), Consent::default(), &made)); + let w = window(live.resolve()); + assert_eq!( + (w.port, w.pid, w.token.as_str(), w.addr()), + (c.port, c.pid, TOKEN.to_ascii_uppercase().as_str(), c.addr()), + "the token is trimmed, otherwise as written" + ); + window(live.resolve()); + assert_eq!(made.connects.load(Ordering::Relaxed), 1, "the same window keeps its client"); + assert!(matches!(live.current(), Some(Route::Window(_)))); + + write_connection(dir.path(), &Connection { pid: c.pid.wrapping_add(1), ..c.clone() }).unwrap(); + assert_eq!(window(live.resolve()).pid, c.pid.wrapping_add(1)); + assert_eq!(made.connects.load(Ordering::Relaxed), 2, "a restarted app gets a new client"); + assert_eq!(made.sessions.load(Ordering::Relaxed), 0); +} + +/// No app accepts agents and the person doesn't let them use it: headless with only the command's +/// folders, never the app's. +#[test] +fn without_consent_a_closed_app_runs_headless_with_the_commands_folders_only() { + let dir = temp_dir("no-consent"); + let made = Arc::new(Made::default()); + let consent = Consent::new(false, settings(WhenAppClosed::Launch, "/app-in", "/app-out")); + let live = TestLive::new(config(dir.path(), consent.clone(), &made)); + assert_eq!(headless_folders(live.resolve()), HeadlessFolders::default(), "no folders given, none used"); + + let mut cfg = config(dir.path(), consent, &made); + cfg.read_roots = paths(&["/cli-in"]); + cfg.write_root = Some(PathBuf::from("/cli-out")); + let f = headless_folders(TestLive::new(cfg).resolve()); + assert_eq!((f.read, f.write), (paths(&["/cli-in"]), Some(PathBuf::from("/cli-out")))); +} + +/// Agents allowed, app closed, "headless": the app's agent folders, each replaced by the command's. +#[test] +fn allowed_and_closed_runs_headless_with_the_apps_folders_unless_the_command_gives_its_own() { + let dir = temp_dir("headless"); + let made = Arc::new(Made::default()); + let f = headless_folders(TestLive::new(config(dir.path(), allowed(WhenAppClosed::Headless), &made)).resolve()); + assert_eq!((f.read, f.write), (paths(&["/app-in"]), Some(PathBuf::from("/app-out")))); + + let mut cfg = config(dir.path(), allowed(WhenAppClosed::Headless), &made); + cfg.read_roots = paths(&["/cli-a", "/cli-b"]); + let f = headless_folders(TestLive::new(cfg).resolve()); + assert_eq!((f.read, f.write), (paths(&["/cli-a", "/cli-b"]), Some(PathBuf::from("/app-out")))); + + let mut cfg = config(dir.path(), allowed(WhenAppClosed::Headless), &made); + cfg.write_root = Some(PathBuf::from("/cli-out")); + let f = headless_folders(TestLive::new(cfg).resolve()); + assert_eq!((f.read, f.write), (paths(&["/app-in"]), Some(PathBuf::from("/cli-out")))); +} + +/// Agents allowed, app closed, "error": the call fails with words that name the app; the command's +/// choice wins over the app's. +#[test] +fn the_closed_app_choice_decides_and_the_command_overrides_it() { + let dir = temp_dir("error"); + let made = Arc::new(Made::default()); + let err = TestLive::new(config(dir.path(), allowed(WhenAppClosed::Error), &made)).resolve().err().unwrap(); + assert_eq!(err, "Test isn't running: open it, then try again."); + + let mut cfg = config(dir.path(), allowed(WhenAppClosed::Error), &made); + cfg.when_closed = Some(WhenAppClosed::Headless); + headless_folders(TestLive::new(cfg).resolve()); + let mut cfg = config(dir.path(), allowed(WhenAppClosed::Headless), &made); + cfg.when_closed = Some(WhenAppClosed::Error); + assert!(TestLive::new(cfg).resolve().is_err()); +} + +/// Once headless, the session stays headless even when the app starts, so documents don't move +/// under the agent. +#[test] +fn a_headless_session_stays_headless() { + let dir = temp_dir("sticky"); + let made = Arc::new(Made::default()); + let live = TestLive::new(config(dir.path(), Consent::default(), &made)); + headless_folders(live.resolve()); + let _app = publish(dir.path()); + headless_folders(live.resolve()); + assert_eq!((made.sessions.load(Ordering::Relaxed), made.connects.load(Ordering::Relaxed)), (1, 0), "one session, no window"); +} + +/// A connection file left by an app that crashed counts as a closed app. +#[test] +fn a_crashed_apps_connection_file_counts_as_closed() { + let dir = temp_dir("crashed"); + drop(publish(dir.path()).0); + let made = Arc::new(Made::default()); + headless_folders(TestLive::new(config(dir.path(), Consent::default(), &made)).resolve()); + assert_eq!(find_window(dir.path(), "Test").unwrap(), None); +} + +/// A token file that isn't a token, is too big, is missing, isn't a regular file or (on Unix) +/// others can read fails the call and names the app; nothing is sent to the window. +#[test] +fn a_bad_token_file_fails_the_call() { + let dir = temp_dir("token"); + let (_listener, _c) = publish(dir.path()); + let made = Arc::new(Made::default()); + for bad in ["", " \n", "not a token", &"a".repeat(5000)] { + write_token(&dir.path().join(TOKEN_FILE), bad); + let err = TestLive::new(config(dir.path(), Consent::default(), &made)).resolve().err().unwrap(); + assert!(err.starts_with("Test's agent token: "), "{err}"); + } + // Any token the app's server accepts is passed on: upper case, dashes. + write_token(&dir.path().join(TOKEN_FILE), "AB12-cd34-EF56-0000-1111-2222-3333-4444"); + assert_eq!(find_window(dir.path(), "Test").unwrap().unwrap().token, "AB12-cd34-EF56-0000-1111-2222-3333-4444"); + #[cfg(unix)] + { + use std::os::unix::fs::PermissionsExt; + let token = dir.path().join(TOKEN_FILE); + write_token(&token, TOKEN); + std::fs::set_permissions(&token, std::fs::Permissions::from_mode(0o644)).unwrap(); + let err = find_window(dir.path(), "Test").err().unwrap(); + assert!(err.contains("readable by group or others"), "{err}"); + // A FIFO would block a plain open until something writes to it. + std::fs::remove_file(&token).unwrap(); + assert!(std::process::Command::new("mkfifo").arg(&token).status().unwrap().success()); + let err = find_window(dir.path(), "Test").err().unwrap(); + assert!(err.contains("not a regular file"), "{err}"); + } + std::fs::remove_file(dir.path().join(TOKEN_FILE)).unwrap(); + assert!(find_window(dir.path(), "Test").is_err()); + assert_eq!(made.connects.load(Ordering::Relaxed), 0); +} + +/// The app's own errors reach the agent with what was being done. +#[test] +fn the_apps_errors_reach_the_agent() { + let dir = temp_dir("app-errors"); + let consent = Consent::default(); + let cfg: LiveConfig = LiveConfig::new( + "Test", + dir.path().to_path_buf(), + move |_: &Path| consent.clone(), + |w: &Window| Ok(w.clone()), + |_: &HeadlessFolders| Err("no such folder".into()), + ); + assert_eq!(TestLive::new(cfg).resolve().err().unwrap(), "Test can't use the automation roots: no such folder"); + + let (_listener, _c) = publish(dir.path()); + let cfg: LiveConfig = LiveConfig::new( + "Test", + dir.path().to_path_buf(), + |_: &Path| Consent::default(), + |_: &Window| Err("refused".into()), + |f: &HeadlessFolders| Ok(f.clone()), + ); + let live = TestLive::new(cfg); + assert_eq!(live.resolve().err().unwrap(), "couldn't reach Test's window: refused"); + assert!(live.current().is_none(), "a failed connect leaves no route"); +} + +/// "Launch" without a way to start the app, a start that fails, and an app that never accepts +/// agents each end with words that say what to do. +#[test] +fn a_launch_that_cannot_happen_or_never_finishes_says_what_to_do() { + let dir = temp_dir("launch-fails"); + let made = Arc::new(Made::default()); + let err = TestLive::new(config(dir.path(), allowed(WhenAppClosed::Launch), &made)).resolve().err().unwrap(); + assert_eq!(err, "Test isn't running, and this install can't start it from here: open Test, then try again."); + + let mut cfg = config(dir.path(), allowed(WhenAppClosed::Launch), &made); + cfg.launch = Some(Box::new(|| Err("boom".into()))); + assert_eq!(TestLive::new(cfg).resolve().err().unwrap(), "couldn't start Test: boom"); + + let mut cfg = config(dir.path(), allowed(WhenAppClosed::Launch), &made); + cfg.launch = Some(Box::new(|| Ok(()))); + cfg.launch_timeout = Duration::from_millis(40); + let err = TestLive::new(cfg).resolve().err().unwrap(); + assert!(err.starts_with("Test didn't accept agents within 0 s of starting."), "{err}"); +} + +/// "Launch" starts the app once, also for calls that arrive together, and the calls go to its +/// window once it accepts agents. +#[test] +fn a_started_app_takes_the_call_and_concurrent_calls_start_it_once() { + let dir = temp_dir("launch"); + let made = Arc::new(Made::default()); + let launches = Arc::new(AtomicUsize::new(0)); + let app: Arc>> = Arc::new(Mutex::new(None)); + let mut cfg = config(dir.path(), allowed(WhenAppClosed::Launch), &made); + let (d, n, slot) = (dir.path().to_path_buf(), launches.clone(), app.clone()); + cfg.launch = Some(Box::new(move || { + n.fetch_add(1, Ordering::Relaxed); + let (d, slot) = (d.clone(), slot.clone()); + // The app takes a moment before it accepts agents. + std::thread::spawn(move || { + std::thread::sleep(Duration::from_millis(60)); + *slot.lock().unwrap() = Some(publish(&d).0); + }); + Ok(()) + })); + let live = Arc::new(TestLive::new(cfg)); + let calls: Vec<_> = (0..4) + .map(|_| { + let live = live.clone(); + std::thread::spawn(move || window(live.resolve())) + }) + .collect(); + let ports: Vec = calls.into_iter().map(|c| c.join().unwrap().port).collect(); + assert_eq!(launches.load(Ordering::Relaxed), 1, "one start for every call"); + assert!(ports.windows(2).all(|p| p[0] == p[1]), "{ports:?}"); + assert_eq!(made.connects.load(Ordering::Relaxed), 1); +} + +/// Calls that queued while a start was under way get its error when the app still isn't there, +/// rather than starting it again; a call made afterwards tries again. +#[test] +fn calls_queued_behind_a_failed_start_share_its_error() { + let dir = temp_dir("launch-shared"); + let made = Arc::new(Made::default()); + let launches = Arc::new(AtomicUsize::new(0)); + let mut cfg = config(dir.path(), allowed(WhenAppClosed::Launch), &made); + let entered = Arc::new(AtomicUsize::new(0)); + let (n, e) = (launches.clone(), entered.clone()); + // The app is started but never accepts agents within the timeout. The start waits until every + // call is under way and then a while longer, so a call that hasn't reached its lookup by the + // time the start ends is very unlikely (there is no hook between the two). + cfg.launch = Some(Box::new(move || { + n.fetch_add(1, Ordering::Relaxed); + assert!(wait_for(|| e.load(Ordering::Relaxed) == 4), "every call starts"); + std::thread::sleep(Duration::from_millis(250)); + Ok(()) + })); + cfg.launch_timeout = Duration::from_millis(150); + let live = Arc::new(TestLive::new(cfg)); + let calls: Vec<_> = (0..4) + .map(|_| { + let (live, entered) = (live.clone(), entered.clone()); + std::thread::spawn(move || { + entered.fetch_add(1, Ordering::Relaxed); + live.resolve() + }) + }) + .collect(); + let answers: Vec<_> = calls.into_iter().map(|c| c.join().unwrap()).collect(); + assert_eq!(launches.load(Ordering::Relaxed), 1, "one start for the calls that came together"); + for answer in &answers { + let err = answer.as_ref().err().unwrap(); + assert!(err.starts_with("Test didn't accept agents within"), "{err}"); + } + assert!(live.resolve().is_err()); + assert_eq!(launches.load(Ordering::Relaxed), 2, "a later call starts the app again"); +} + +/// Allow Agent Control off refuses agents on the CLI's side too, as the app does by not +/// listening: no start, and only the command's folders. +#[test] +fn allow_agent_control_off_counts_as_not_allowed() { + let dir = temp_dir("aac-off"); + let made = Arc::new(Made::default()); + let mut s = settings(WhenAppClosed::Launch, "/app-in", "/app-out"); + s.allow_agent_control = false; + let mut cfg = config(dir.path(), Consent::new(true, s), &made); + cfg.launch = Some(Box::new(|| panic!("nothing may start the app"))); + cfg.read_roots = paths(&["/cli-in"]); + let f = headless_folders(TestLive::new(cfg).resolve()); + assert_eq!((f.read, f.write), (paths(&["/cli-in"]), None)); +} + +/// A window route is dropped once no app accepts agents, so a dead client isn't kept or handed +/// back. +#[test] +fn a_window_that_went_away_is_forgotten() { + let dir = temp_dir("gone"); + let made = Arc::new(Made::default()); + let live = TestLive::new(config(dir.path(), allowed(WhenAppClosed::Error), &made)); + let (listener, c) = publish(dir.path()); + window(live.resolve()); + drop(listener); + remove_connection(dir.path(), c.pid); + assert!(live.resolve().is_err(), "the app is closed and the choice is an error"); + assert!(live.current().is_none(), "the dead window is gone"); +} + +/// A headless session with the app's agent folders ends when the person stops letting agents in; +/// one with only the command's folders stays. +#[test] +fn a_headless_session_with_the_apps_folders_ends_with_consent() { + let dir = temp_dir("revoke"); + let made = Arc::new(Made::default()); + let on = Arc::new(AtomicBool::new(true)); + let gate = on.clone(); + let (b, c) = (made.clone(), made.clone()); + let cfg: LiveConfig = LiveConfig::new( + "Test", + dir.path().to_path_buf(), + move |_: &Path| Consent::new(gate.load(Ordering::Relaxed), settings(WhenAppClosed::Headless, "/app-in", "/app-out")), + move |w: &Window| { + b.connects.fetch_add(1, Ordering::Relaxed); + Ok(w.clone()) + }, + move |f: &HeadlessFolders| { + c.sessions.fetch_add(1, Ordering::Relaxed); + Ok(f.clone()) + }, + ); + let live = TestLive::new(cfg); + assert_eq!(headless_folders(live.resolve()).read, paths(&["/app-in"])); + on.store(false, Ordering::Relaxed); + assert_eq!(headless_folders(live.resolve()), HeadlessFolders::default(), "the app's folders went with the consent"); + on.store(true, Ordering::Relaxed); + assert_eq!(headless_folders(live.resolve()), HeadlessFolders::default(), "a session without the app's folders stays"); + assert_eq!(made.sessions.load(Ordering::Relaxed), 2); +} + +/// A huge launch timeout or poll is cut down rather than overflowing the deadline or blocking. +#[test] +fn a_huge_launch_timeout_or_poll_neither_panics_nor_hangs() { + let dir = temp_dir("huge"); + let made = Arc::new(Made::default()); + let mut cfg = config(dir.path(), allowed(WhenAppClosed::Launch), &made); + let (d, app) = (dir.path().to_path_buf(), Arc::new(Mutex::new(None))); + let slot = app.clone(); + cfg.launch = Some(Box::new(move || { + *slot.lock().unwrap() = Some(publish(&d).0); + Ok(()) + })); + cfg.launch_timeout = Duration::MAX; + cfg.poll = Duration::MAX; + let started = Instant::now(); + window(TestLive::new(cfg).resolve()); + assert!(started.elapsed() < Duration::from_secs(5), "{:?}", started.elapsed()); +} diff --git a/crates/craft/Cargo.toml b/crates/craft/Cargo.toml index 270659039..708bbf2b6 100644 --- a/crates/craft/Cargo.toml +++ b/crates/craft/Cargo.toml @@ -204,6 +204,15 @@ craft-pcap = { workspace = true, optional = true } craft-sourcemap = { workspace = true, optional = true } craft-wasm = { workspace = true, optional = true } craft-xfdf = { workspace = true, optional = true } +craft-color-transform = { workspace = true, optional = true } +craft-develop = { workspace = true, optional = true } +craft-develop-model = { workspace = true, optional = true } +craft-dex = { workspace = true, optional = true } +craft-esign = { workspace = true, optional = true } +craft-evm = { workspace = true, optional = true } +craft-geom = { workspace = true, optional = true } +craft-suite-account = { workspace = true, optional = true } +craft-xfa = { workspace = true, optional = true } [features] ui = [ @@ -324,6 +333,7 @@ cloud-local = ["dep:craft-cloud-local"] cloud-ui = ["dep:craft-cloud-ui"] cloud-ui-cloud = ["cloud-ui", "craft-cloud-ui/cloud"] +cloud-ui-esign = ["cloud-ui", "craft-cloud-ui/esign"] cloud-ui-share = ["cloud-ui", "craft-cloud-ui/share"] cms = ["dep:craft-cms"] @@ -332,9 +342,12 @@ codepage = ["dep:craft-codepage"] color = ["dep:craft-color"] +color-transform = ["dep:craft-color-transform"] + color-ui = ["dep:craft-color-ui", "keymap", "settings", "window", "platform"] control = ["dep:craft-control"] +control-agents = ["control", "craft-control/agents"] control-protocol = ["dep:craft-control-protocol"] @@ -353,6 +366,12 @@ deckcraft-format = ["dep:craft-deckcraft-format"] designcraft-format = ["dep:craft-designcraft-format"] +develop = ["dep:craft-develop"] + +develop-model = ["dep:craft-develop-model"] + +dex = ["dep:craft-dex"] + dialogs = ["dep:craft-dialogs"] # native only: rfd's folder picker and file paths doc = ["dep:craft-doc"] @@ -386,6 +405,10 @@ eps-paths = ["eps", "craft-eps/paths"] epub = ["dep:craft-epub"] +esign = ["dep:craft-esign"] + +evm = ["dep:craft-evm"] + ews = ["dep:craft-ews"] exr = ["dep:craft-exr"] @@ -443,6 +466,8 @@ gainmap = ["dep:craft-gainmap"] gcode = ["dep:craft-gcode"] +geom = ["dep:craft-geom"] + gif = ["dep:craft-gif"] gif-frames = ["gif", "craft-gif/frames"] @@ -476,6 +501,7 @@ image-codecs-avif = ["image-codecs", "craft-image-codecs/avif"] image-codecs-avif-decode = ["image-codecs", "craft-image-codecs/avif-decode"] image-codecs-corpus = ["image-codecs", "craft-image-codecs/corpus"] image-codecs-heif = ["image-codecs", "craft-image-codecs/heif"] +image-codecs-jxl = ["image-codecs", "craft-image-codecs/jxl"] image-codecs-sgi = ["image-codecs", "craft-image-codecs/sgi"] image-codecs-sunraster = ["image-codecs", "craft-image-codecs/sunraster"] image-codecs-threads = ["image-codecs", "craft-image-codecs/threads"] @@ -719,6 +745,8 @@ stencilcraft-format = ["dep:craft-stencilcraft-format"] stream-codecs = ["dep:craft-stream-codecs"] +suite-account = ["dep:craft-suite-account"] + svg = ["dep:craft-svg"] svg-draw = ["svg", "craft-svg/draw"] svg-paths = ["svg", "craft-svg/paths"] @@ -820,6 +848,7 @@ timeline-xml = ["timeline", "craft-timeline/xml"] ui-app = ["ui", "craft-ui/app"] ui-cloud = ["ui", "craft-ui/cloud"] ui-color_fonts = ["ui", "craft-ui/color_fonts"] +ui-esign = ["ui", "craft-ui/esign"] ui-share = ["ui", "craft-ui/share"] ui-snapshot = ["ui", "craft-ui/snapshot"] ui-system_fonts = ["ui", "craft-ui/system_fonts"] @@ -889,6 +918,8 @@ wordmodel-test-support = ["wordmodel", "craft-wordmodel/test-support"] xcf = ["dep:craft-xcf"] +xfa = ["dep:craft-xfa"] + xfdf = ["dep:craft-xfdf"] xfl = ["dep:craft-xfl"] diff --git a/crates/craft/src/lib.rs b/crates/craft/src/lib.rs index 75bade419..2509c4069 100644 --- a/crates/craft/src/lib.rs +++ b/crates/craft/src/lib.rs @@ -47,6 +47,8 @@ pub use craft_cms as cms; pub use craft_codepage as codepage; #[cfg(feature = "color")] pub use craft_color as color; +#[cfg(feature = "color-transform")] +pub use craft_color_transform as color_transform; #[cfg(feature = "color-ui")] pub use craft_color_ui as color_ui; #[cfg(feature = "control")] @@ -67,6 +69,12 @@ pub use craft_dds as dds; pub use craft_deckcraft_format as deckcraft_format; #[cfg(feature = "designcraft-format")] pub use craft_designcraft_format as designcraft_format; +#[cfg(feature = "develop")] +pub use craft_develop as develop; +#[cfg(feature = "develop-model")] +pub use craft_develop_model as develop_model; +#[cfg(feature = "dex")] +pub use craft_dex as dex; #[cfg(feature = "dialogs")] pub use craft_dialogs as dialogs; #[cfg(feature = "doc")] @@ -97,6 +105,10 @@ pub use craft_elf as elf; pub use craft_eps as eps; #[cfg(feature = "epub")] pub use craft_epub as epub; +#[cfg(feature = "esign")] +pub use craft_esign as esign; +#[cfg(feature = "evm")] +pub use craft_evm as evm; #[cfg(feature = "ews")] pub use craft_ews as ews; #[cfg(feature = "exr")] @@ -133,6 +145,8 @@ pub use craft_frame as frame; pub use craft_gainmap as gainmap; #[cfg(feature = "gcode")] pub use craft_gcode as gcode; +#[cfg(feature = "geom")] +pub use craft_geom as geom; #[cfg(feature = "gif")] pub use craft_gif as gif; #[cfg(feature = "gridcraft-format")] @@ -315,6 +329,8 @@ pub use craft_stencilcraft_document as stencilcraft_document; pub use craft_stencilcraft_format as stencilcraft_format; #[cfg(feature = "stream-codecs")] pub use craft_stream_codecs as stream_codecs; +#[cfg(feature = "suite-account")] +pub use craft_suite_account as suite_account; #[cfg(feature = "svg")] pub use craft_svg as svg; #[cfg(feature = "table")] @@ -368,6 +384,8 @@ pub use craft_window as window; pub use craft_wordmodel as wordmodel; #[cfg(feature = "xcf")] pub use craft_xcf as xcf; +#[cfg(feature = "xfa")] +pub use craft_xfa as xfa; #[cfg(feature = "xfdf")] pub use craft_xfdf as xfdf; #[cfg(feature = "xfl")] diff --git a/crates/csv/README.md b/crates/csv/README.md index bfd525c8c..8fd264d4c 100644 --- a/crates/csv/README.md +++ b/crates/csv/README.md @@ -11,7 +11,7 @@ mapping a SYLK sheet onto a document are the caller's work. | Function | What it does | |---|---| | `decode_text(bytes)` | UTF-8 and UTF-16 byte order marks; without one, valid UTF-8 is kept; other bytes are Windows-1256 when they read as Arabic, else Windows-1252 | -| `sniff_delimiter(text, quote)` | comma, semicolon or tab: the one with the most consistent field count over the first 20 non-blank records in a 64 KiB sample; when no candidate finds coherent complete records with a delimiter in each, a candidate that finds no complete record counts the delimiters of the first record up to the end of the sample, or up to a quoted field still open there, and a quote inside a field that does not start with one makes that record incoherent; quote boundaries must be coherent, and ties prefer tab, comma, then semicolon | +| `sniff_delimiter(text, quote)` | comma, semicolon or tab: the one with the most consistent field count over the first 20 records with other text in a 64 KiB sample; when none separates those records, the candidates whose records hold only their delimiters and whitespace (rows of empty cells) are compared the same way, leaving out any candidate that found a record with other text; when no candidate finds coherent complete records with a delimiter in each, a candidate that finds no complete record with other text counts the delimiters of the first such record up to the end of the sample, or up to a quoted field still open there (after its rows of empty cells, a record without its delimiter is left out), and a quote inside a field that does not start with one makes that record incoherent; quote boundaries must be coherent, and ties prefer tab, comma, then semicolon | | `parse_records(text, delim, quote, max_fields, on_record)` | records of fields, one callback per record (return `false` to stop); CR, LF and CRLF line ends; quoted fields with doubled quotes and line breaks; a quote in the middle of a field is text | | `records(text, delim, quote, max_records, max_fields)` | the same, collected | | `push_field(out, field, delim)`, `field_len(field, delim)` | one field as written, quoted only when it holds the delimiter, a quote or a line break; its exact length, to enforce a size cap before writing | diff --git a/crates/csv/src/lib.rs b/crates/csv/src/lib.rs index 70f6148a6..395ad2152 100644 --- a/crates/csv/src/lib.rs +++ b/crates/csv/src/lib.rs @@ -33,13 +33,17 @@ pub use decode::{decode_text, decode_utf8}; /// Picks comma, semicolon or tab by consistent field counts in the first non-blank records. /// Quotes start only at a candidate field boundary; candidates with incoherent quoted fields /// are discarded when another coherent candidate separates the records. Ties prefer tab, -/// then comma, then semicolon. Comma is the fallback when no candidate separates the text. +/// then comma, then semicolon. When no candidate separates the records that hold other text, +/// the same rules pick among the candidates whose records hold only their delimiters and +/// whitespace, such as an exported row of empty cells; a candidate that finds a record with +/// other text is left out of that pick. Comma is the fallback when neither pick finds one. /// Only the first 64 KiB are read. A record cut off at the end of that sample is left out, /// except when no candidate finds coherent complete records with a delimiter in each. Then a candidate -/// that finds no complete record counts the delimiters read so far in the first record, and that -/// record is incoherent when it has a quote inside a field that does not start with one. When one -/// of those candidates ends the sample inside a quoted field, each of them counts only up to that -/// field's opening quote. +/// that finds no complete record with other text counts the delimiters read so far in the first +/// such record, unless it found rows of its empty cells and that record has none of its +/// delimiters. That record is incoherent when it has a quote inside a field that does not start +/// with one. When one of those candidates ends the sample inside a quoted field, each of them +/// counts only up to that field's opening quote. pub fn sniff_delimiter(text: &str, quote: char) -> u8 { const SAMPLE_BYTES: usize = 64 * 1024; let mut sample_end = text.len().min(SAMPLE_BYTES); @@ -64,7 +68,15 @@ pub fn sniff_delimiter(text: &str, quote: char) -> u8 { (scan.count, scan.record_has_content, scan.record_coherent, scan.record_bare_quote) = (before_cut.count, before_cut.record_has_content, before_cut.record_coherent, before_cut.record_bare_quote); } - if scan.record_has_content { + if scan.delimiter_only_counts.is_empty() { + if scan.record_has_content { + scan.coherent &= scan.record_coherent && !scan.record_bare_quote; + scan.counts.push(scan.count); + } else { + scan.push_delimiter_only_record(); + } + } else if scan.record_has_content && scan.count > 0 { + // After rows of empty cells, a cut record without this delimiter is left out. scan.coherent &= scan.record_coherent && !scan.record_bare_quote; scan.counts.push(scan.count); } @@ -79,6 +91,8 @@ pub fn sniff_delimiter(text: &str, quote: char) -> u8 { } else if scan.record_has_content { scan.coherent &= scan.record_coherent; scan.counts.push(scan.count); + } else { + scan.push_delimiter_only_record(); } } } @@ -86,23 +100,34 @@ pub fn sniff_delimiter(text: &str, quote: char) -> u8 { } fn pick_delimiter(scans: [DelimiterScan; 3]) -> u8 { - let candidates = - scans.map(|scan| (scan.delimiter, scan.counts.iter().copied().min().unwrap_or(0), scan.counts.iter().sum::(), scan.coherent)); + let with_text = scans.each_ref().map(|scan| (scan.delimiter, scan.counts.as_slice(), scan.coherent)); + // Records of delimiters alone have no quotes, so they are coherent. + let delimiters_only = + scans.each_ref().map(|scan| (scan.delimiter, if scan.counts.is_empty() { scan.delimiter_only_counts.as_slice() } else { &[] }, true)); + best_delimiter(with_text).or_else(|| best_delimiter(delimiters_only)).unwrap_or(b',') +} + +fn best_delimiter(candidates: [(u8, &[usize], bool); 3]) -> Option { + let candidates = candidates + .map(|(delimiter, counts, coherent)| (delimiter, counts.iter().copied().min().unwrap_or(0), counts.iter().sum::(), coherent)); let prefer_coherent = candidates.iter().any(|(_, min, _, coherent)| *min > 0 && *coherent); - let mut best = (b',', 0usize, 0usize); + let mut best: Option<(u8, usize, usize)> = None; for (delimiter, min, total, coherent) in candidates { - if min > 0 && (!prefer_coherent || coherent) && (min, total) > (best.1, best.2) { - best = (delimiter, min, total); + if min > 0 && (!prefer_coherent || coherent) && best.is_none_or(|(_, best_min, best_total)| (min, total) > (best_min, best_total)) { + best = Some((delimiter, min, total)); } } - best.0 + best.map(|(delimiter, _, _)| delimiter) } /// One candidate delimiter's pass over the sample in [`sniff_delimiter`]. struct DelimiterScan { delimiter: u8, - /// Delimiter counts of the complete non-blank records, at most 20. + /// Delimiter counts of the complete records that hold other text, at most 20. counts: Vec, + /// Delimiter counts of the complete records that hold only this candidate's delimiters and + /// whitespace, at most 20. They do not count toward the 20 records above. + delimiter_only_counts: Vec, /// Whether every counted record had coherent quoted fields. coherent: bool, reached_record_limit: bool, @@ -117,10 +142,21 @@ struct DelimiterScan { open_quote: Option, } +impl DelimiterScan { + /// Keeps the open record's delimiter count when the record has no other text and at least + /// one delimiter. + fn push_delimiter_only_record(&mut self) { + if !self.record_has_content && self.count > 0 && self.delimiter_only_counts.len() < 20 { + self.delimiter_only_counts.push(self.count); + } + } +} + fn scan_delimiter(sample: &str, delimiter: u8, quote: char) -> DelimiterScan { let mut scan = DelimiterScan { delimiter, counts: Vec::new(), + delimiter_only_counts: Vec::new(), coherent: true, reached_record_limit: false, count: 0, @@ -158,6 +194,8 @@ fn scan_delimiter(sample: &str, delimiter: u8, quote: char) -> DelimiterScan { scan.reached_record_limit = true; break; } + } else { + scan.push_delimiter_only_record(); } scan.count = 0; after_quote = false; @@ -403,6 +441,64 @@ mod tests { assert_eq!(sniff_delimiter(&format!("a,b,c;\"hello,\";d\n{}", "x;y;z\n".repeat(12_000)), '"'), b';'); } + // A sheet whose only value is far down exports rows of empty cells that fill the whole sample. + #[test] + fn delimiter_sniffing_reads_a_sparse_semicolon_export() { + assert_eq!(sniff_delimiter(&format!("{};7\n", ";\n".repeat(40_000)), '"'), b';'); + } + + #[test] + fn delimiter_sniffing_reads_a_sparse_semicolon_export_with_crlf() { + assert_eq!(sniff_delimiter(&format!("{};7\r\n", ";\r\n".repeat(40_000)), '"'), b';'); + } + + #[test] + fn delimiter_sniffing_reads_a_sparse_tab_export() { + assert_eq!(sniff_delimiter(&format!("{}\t7\r\n", "\t\r\n".repeat(40_000)), '"'), b'\t'); + } + + #[test] + fn delimiter_sniffing_reads_a_short_file_of_empty_semicolon_cells() { + assert_eq!(sniff_delimiter(";;\n;;\n", '"'), b';'); + assert_eq!(sniff_delimiter(";;\r\n;;", '"'), b';'); + } + + #[test] + fn delimiter_sniffing_reads_empty_semicolon_cells_padded_with_whitespace() { + assert_eq!(sniff_delimiter(&"; ; \n".repeat(20_000), '"'), b';'); + } + + #[test] + fn delimiter_sniffing_reads_a_first_record_of_empty_cells_longer_than_the_sample() { + assert_eq!(sniff_delimiter(&format!("{}\n1;2\n", ";".repeat(70_000)), '"'), b';'); + } + + #[test] + fn delimiter_sniffing_leaves_out_a_cut_record_after_a_row_of_empty_cells() { + assert_eq!(sniff_delimiter(&format!(";\n{};7\n", "x".repeat(70_000)), '"'), b';'); + } + + #[test] + fn delimiter_sniffing_counts_a_long_record_after_a_row_of_empty_cells() { + // Delimiters inside the long record's quoted field are text for every candidate. + assert_eq!(sniff_delimiter(&format!("\t\nname\t\"{}\"\n", "x,y".repeat(30_000)), '"'), b'\t'); + assert_eq!(sniff_delimiter(&format!(";\nname;\"{}\"\n", "x,y\t".repeat(20_000)), '"'), b';'); + } + + #[test] + fn delimiter_sniffing_lets_records_with_text_outweigh_records_of_delimiters_alone() { + // Rows of tabs alone are blank to the other candidates and do not outweigh them. + assert_eq!(sniff_delimiter(&format!("{}a;b\nc;d\n", "\t\n".repeat(25)), '"'), b';'); + assert_eq!(sniff_delimiter(&format!("{}a;b\nc;d\n", "\t\t\n".repeat(25)), '"'), b';'); + // The same holds for a record with text cut off at the end of the sample. + assert_eq!(sniff_delimiter(&format!("\t\n{}", "x;".repeat(40_000)), '"'), b';'); + // A candidate with a record of other text is judged on those records alone. + assert_eq!(sniff_delimiter(&format!("title\n{}", ";\n".repeat(25)), '"'), b','); + // Rows of empty cells in a comma file; comma is also the fallback. + assert_eq!(sniff_delimiter("a,b,c,d\n,,,\n,,,\n1,2,3,4\n", '"'), b','); + assert_eq!(sniff_delimiter(&format!("{}x;y\n", ",,,\n".repeat(20_000)), '"'), b','); + } + #[test] fn parser_stops_collecting_fields_at_the_cap() { let (max, extra) = (16_384usize, 50); diff --git a/crates/dds/README.md b/crates/dds/README.md index 2dae26bc1..37eb70cc8 100644 --- a/crates/dds/README.md +++ b/crates/dds/README.md @@ -23,21 +23,22 @@ in part. Pixels are 8 bits per channel (`encode`, `Texture::decode`) or 16 bits per channel (`encode16`, `Texture::decode16`), interleaved and top row first, in one of four `Layout`s (`Gray`, `GrayA`, `Rgb`, `Rgba`). BC1 to BC3 are written from RGBA, BC4 from gray and BC5 from RGB -(`DdsCompression::layout` names it). BC4 reads back as gray. BC5 stores red and green only, so it -reads back as RGB with blue 0: for a tangent-space normal map, X and Y, with Z left to the -renderer. ATI2 files are read as Microsoft's tools read them (red in the first block), not with -the two blocks swapped as FFmpeg does. +(`DdsCompression::layout` names it). BC4 reads back as gray. BC5 and `R16G16_UNORM` store red +and green only, so they read as RGB with blue 0: for a tangent-space normal map, X and Y, with Z +left to the renderer. ATI2 files are read as Microsoft's tools read them (red in the first block), +not with the two blocks swapped as FFmpeg does. From 16-bit pixels, uncompressed textures keep 16 bits per channel: gray as `R16_UNORM`, gray and alpha (or any two channels, such as a normal map's X and Y) as `R16G16_UNORM`, RGB (alpha -65535) and RGBA as `R16G16B16A16_UNORM`, all with the DX10 header; they read back as gray, gray -and alpha, and RGBA. BC4 and BC5 keep 8-bit endpoints, as the formats store them, but pick them -and the indices against the 16-bit values, so a smooth height or normal map has less error than -when its 8-bit rounding is compressed. BC1 to BC3 round the pixels to 8 bits first. +65535) and RGBA as `R16G16B16A16_UNORM`, all with the DX10 header; they read back as gray, RGB +with blue 0 (red and green holding the two channels), and RGBA. BC4 and BC5 keep 8-bit +endpoints, as the formats store them, but pick them and the indices against the 16-bit values, +so a smooth height or normal map has less error than when its 8-bit rounding is compressed. BC1 to BC3 round the pixels to 8 bits first. `Texture::decode` rounds 16-bit formats to 8 bits; `Texture::decode16` returns them exactly, rescales channel-mask fields from their own width (a 16-bit luminance field exactly), -interpolates BC4 and BC5 at 16 bits, and scales BC1 to BC3 by 257. `craft-image-codecs` still -reads DDS at 8 bits. +interpolates BC4 and BC5 at 16 bits, and scales BC1 to BC3 by 257. `Texture::bits_per_channel` +gives the widest stored channel; `craft-image-codecs` reads a texture through `decode16` when it +is wider than 8 bits. ```rust use craft_dds::{DdsCompression, DdsOptions, Layout, Texture}; diff --git a/crates/dds/src/lib.rs b/crates/dds/src/lib.rs index 685ce81dd..4eb8ff994 100644 --- a/crates/dds/src/lib.rs +++ b/crates/dds/src/lib.rs @@ -5,9 +5,10 @@ //! described by channel masks, RGB or luminance, or 16 bits per channel: `R16_UNORM`, //! `R16G16_UNORM`, `R16G16B16A16_UNORM`) or block-compressed BC1/BC2/BC3 //! (DXT1/DXT3/DXT5) or unsigned BC4/BC5 (ATI1/ATI2), with or without the DX10 header. BC4 opens -//! as gray and BC5 as RGB with blue 0: BC5 stores only red and green, and a normal map's Z is -//! left for the caller to reconstruct. Cubemaps, texture arrays and volume textures are refused -//! rather than flattened to one face or slice, and signed (SNORM) BC4/BC5 is refused too. +//! as gray, and BC5 and `R16G16_UNORM` as RGB with blue 0: they store only red and green, and a +//! normal map's Z is left for the caller to reconstruct. Cubemaps, texture arrays and volume +//! textures are refused rather than flattened to one face or slice, and signed (SNORM) BC4/BC5 is +//! refused too. //! //! Writing: a 2D texture, uncompressed (BGRA or BGRX, luminance with or without alpha), //! BC1/BC2/BC3 or BC4/BC5, optionally with its full mip chain. The legacy header describes all @@ -18,7 +19,7 @@ //! Pixels are 8 bits per channel ([`encode`], [`Texture::decode`]) or 16 bits per channel //! ([`encode16`], [`Texture::decode16`]), interleaved, top row first, in one of the [`Layout`]s. //! Uncompressed 16-bit pixels are written with the DX10 header as `R16_UNORM` (gray), -//! `R16G16_UNORM` (gray and alpha, or any two channels such as a normal map's X and Y) or +//! `R16G16_UNORM` (two channels, such as a normal map's X and Y, read back as red and green) or //! `R16G16B16A16_UNORM` (RGB, with alpha 65535, and RGBA). BC4 and BC5 fit their 8-bit endpoints //! and their indices to the 16-bit values; BC1 to BC3 round the pixels to 8 bits first. The //! crate has no dependencies; the `parallel` feature encodes and decodes rows of blocks (and mip @@ -269,7 +270,8 @@ enum Encoding { Bc1, Bc2, Bc3, - /// 16 bits per channel, little-endian: gray, gray and alpha (or red and green), or RGBA. + /// 16 bits per channel, little-endian: gray, red and green (read as RGB with blue 0), or + /// RGBA. Unorm16 { channels: usize, }, @@ -301,7 +303,7 @@ impl Encoding { Encoding::Masks { gray: true, .. } => Layout::Gray, Encoding::Masks { fields, .. } if fields[3].is_none() => Layout::Rgb, Encoding::Unorm16 { channels: 1 } => Layout::Gray, - Encoding::Unorm16 { channels: 2 } => Layout::GrayA, + Encoding::Unorm16 { channels: 2 } => Layout::Rgb, Encoding::Bc4 => Layout::Gray, Encoding::Bc5 => Layout::Rgb, _ => Layout::Rgba, @@ -479,6 +481,17 @@ impl<'a> Texture<'a> { self.levels } + /// Bits in the widest channel the file stores: 16 for the 16-bit formats, the widest mask + /// field for other uncompressed pixels, 8 for block compressions. Above 8, + /// [`Texture::decode`] rounds samples that [`Texture::decode16`] keeps. + pub fn bits_per_channel(&self) -> u32 { + match self.encoding { + Encoding::Unorm16 { .. } => 16, + Encoding::Masks { fields, .. } => fields.iter().flatten().map(|f| u32::BITS - f.max.leading_zeros()).max().unwrap_or(0), + Encoding::Bc1 | Encoding::Bc2 | Encoding::Bc3 | Encoding::Bc4 | Encoding::Bc5 => 8, + } + } + /// The encoding named by the header, including unsigned BC4 and BC5. pub fn compression(&self) -> DdsCompression { match self.encoding { @@ -534,11 +547,8 @@ impl<'a> Texture<'a> { match encoding { Encoding::Masks { bytes, gray, fields } => decode_masks(Masks { bytes, gray, fields }, data, row_pitch, &mut pixels, row_size), // Each 16-bit sample rounded to the nearest 8-bit level. - Encoding::Unorm16 { .. } => rows(&mut pixels, row_size, |y, dst| { - let src = data.get(y * row_pitch..).unwrap_or_default(); - for (d, s) in dst.iter_mut().zip(src.as_chunks::<2>().0) { - *d = to8(u16::from_le_bytes(*s)); - } + Encoding::Unorm16 { channels: stored } => rows(&mut pixels, row_size, |y, dst| { + unorm16_row(data.get(y * row_pitch..).unwrap_or_default(), stored, dst, to8); }), Encoding::Bc1 | Encoding::Bc2 | Encoding::Bc3 | Encoding::Bc4 | Encoding::Bc5 => { decode_blocks(encoding, data, (w, channels), &mut pixels) @@ -565,11 +575,8 @@ impl<'a> Texture<'a> { let mut pixels = alloc_zeroed(total / 2)?; match encoding { Encoding::Masks { bytes, gray, fields } => decode_masks16(Masks { bytes, gray, fields }, data, row_pitch, &mut pixels, row_size), - Encoding::Unorm16 { .. } => rows(&mut pixels, row_size, |y, dst| { - let src = data.get(y * row_pitch..).unwrap_or_default(); - for (d, s) in dst.iter_mut().zip(src.as_chunks::<2>().0) { - *d = u16::from_le_bytes(*s); - } + Encoding::Unorm16 { channels: stored } => rows(&mut pixels, row_size, |y, dst| { + unorm16_row(data.get(y * row_pitch..).unwrap_or_default(), stored, dst, |v| v); }), Encoding::Bc4 | Encoding::Bc5 => decode_value_blocks16(encoding, data, (w, channels), &mut pixels), Encoding::Bc1 | Encoding::Bc2 | Encoding::Bc3 => { @@ -603,6 +610,21 @@ impl<'a> Texture<'a> { } } +/// One row of 16-bit samples, `stored` a pixel and little-endian, into `dst` through `convert`. +/// Two stored channels are red and green: they fill RGB pixels with blue 0. +fn unorm16_row(src: &[u8], stored: usize, dst: &mut [T], convert: impl Fn(u16) -> T) { + let src = src.as_chunks::<2>().0; + if stored == 2 { + for (d, s) in dst.as_chunks_mut::<3>().0.iter_mut().zip(src.as_chunks::<2>().0) { + *d = [convert(u16::from_le_bytes(s[0])), convert(u16::from_le_bytes(s[1])), T::default()]; + } + } else { + for (d, s) in dst.iter_mut().zip(src) { + *d = convert(u16::from_le_bytes(*s)); + } + } +} + /// A 16-bit sample rounded to the nearest 8-bit level. fn to8(v: u16) -> u8 { ((u32::from(v) + 128) / 257) as u8 @@ -946,7 +968,8 @@ pub fn encode(width: u32, height: u32, layout: Layout, pixels: &[u8], options: D /// [`encode`] for 16-bit pixels. Uncompressed, they keep 16 bits per channel: gray as /// `R16_UNORM`, gray and alpha (or any two channels, such as a normal map's X and Y) as /// `R16G16_UNORM`, RGB (with alpha 65535) and RGBA as `R16G16B16A16_UNORM`, all with the DX10 -/// header. BC4 and BC5 pick their endpoints and indices against the 16-bit values; BC1 to BC3 +/// header. `R16G16_UNORM` holds red and green, so two channels read back as RGB with blue 0. BC4 +/// and BC5 pick their endpoints and indices against the 16-bit values; BC1 to BC3 /// round the pixels to 8 bits and write what [`encode`] writes from them. pub fn encode16(width: u32, height: u32, layout: Layout, pixels: &[u16], options: DdsOptions) -> Result, DdsError> { if width == 0 || height == 0 { @@ -1293,6 +1316,24 @@ mod tests { assert_eq!(Texture::parse(&file).and_then(|t| t.decode()), Ok(vec![7; 64])); } + #[test] + fn bits_per_channel_is_the_widest_stored_channel() { + let options = |compression| DdsOptions { compression, mipmaps: false }; + let gray = encode(4, 4, Layout::Gray, &[7; 16], options(DdsCompression::None)).unwrap(); + let bc4 = encode(4, 4, Layout::Gray, &[7; 16], options(DdsCompression::Bc4)).unwrap(); + let r16 = encode16(4, 4, Layout::Gray, &[7; 16], options(DdsCompression::None)).unwrap(); + let bits = |file: &[u8]| Texture::parse(file).unwrap().bits_per_channel(); + assert_eq!((bits(&gray), bits(&bc4), bits(&r16)), (8, 8, 16)); + // A2R10G10B10 as masks: 10 bits. + let mut a2r10 = gray[..HEADER].to_vec(); + a2r10[80..84].copy_from_slice(&(DDPF_RGB | DDPF_ALPHAPIXELS).to_le_bytes()); + a2r10[88..92].copy_from_slice(&32u32.to_le_bytes()); + for (i, mask) in [0x3ff0_0000u32, 0xf_fc00, 0x3ff, 0xc000_0000].into_iter().enumerate() { + a2r10[92 + 4 * i..96 + 4 * i].copy_from_slice(&mask.to_le_bytes()); + } + assert_eq!(bits(&a2r10), 10); + } + /// Samples spread over the whole 16-bit range, `channels` a pixel. fn spread16(width: usize, height: usize, channels: usize) -> Vec { (0..width * height * channels).map(|i| (i as u32 * 7919 % 65536) as u16).collect() @@ -1303,13 +1344,17 @@ mod tests { let (w, h) = (7, 5); for (layout, dxgi, read_as, pixel_bytes) in [ (Layout::Gray, 56, Layout::Gray, 2), - (Layout::GrayA, 35, Layout::GrayA, 4), + (Layout::GrayA, 35, Layout::Rgb, 4), (Layout::Rgb, 11, Layout::Rgba, 8), (Layout::Rgba, 11, Layout::Rgba, 8), ] { let pixels = spread16(w, h, layout.channels()); - let want: Vec = - if layout == Layout::Rgb { pixels.chunks(3).flat_map(|p| [p[0], p[1], p[2], 65535]).collect() } else { pixels.clone() }; + let want: Vec = match layout { + // R16G16 holds red and green: the two channels read back with blue 0. + Layout::GrayA => pixels.chunks(2).flat_map(|p| [p[0], p[1], 0]).collect(), + Layout::Rgb => pixels.chunks(3).flat_map(|p| [p[0], p[1], p[2], 65535]).collect(), + _ => pixels.clone(), + }; for mipmaps in [false, true] { let file = encode16(w as u32, h as u32, layout, &pixels, DdsOptions { compression: DdsCompression::None, mipmaps }).unwrap(); assert_eq!(le32(&file, HEADER).unwrap(), dxgi, "{layout:?}"); @@ -1358,6 +1403,7 @@ mod tests { let texture = Texture::parse(&l16).unwrap(); assert_eq!(texture.decode16().unwrap(), [300, 65000]); assert_eq!(texture.decode().unwrap(), [1, 253]); + assert_eq!(texture.bits_per_channel(), 16); // G16R16 as masks (red low, green high) reads as RGB at 16 bits, blue 0. let mut g16r16 = l16[..HEADER].to_vec(); g16r16[80..84].copy_from_slice(&DDPF_RGB.to_le_bytes()); @@ -1369,6 +1415,36 @@ mod tests { assert_eq!((texture.layout(), texture.decode16().unwrap()), (Layout::Rgb, vec![300, 40000, 0, 65535, 7, 0])); } + /// A DX10 `R16G16` file (DXGI 35, or 33 typeless) of `levels` levels: red then green, + /// little-endian, each level packed after the one above. + fn rg16_file(width: u32, height: u32, dxgi: u32, levels: u32, samples: &[u16]) -> Vec { + let mut file = header(width, height, Store::R16, levels, 0).unwrap().to_vec(); + file[HEADER..HEADER + 4].copy_from_slice(&dxgi.to_le_bytes()); + file[20..24].copy_from_slice(&(width * 4).to_le_bytes()); + file.extend(samples.iter().flat_map(|v| v.to_le_bytes())); + file + } + + #[test] + fn r16g16_textures_read_as_red_and_green_with_blue_0() { + // R16G16 stores red and green and no alpha: blue is 0, as for BC5 and G16R16 masks. + let (w, h) = (3, 2); + let top = spread16(w, h, 2); + let rgb: Vec = top.chunks(2).flat_map(|p| [p[0], p[1], 0]).collect(); + for dxgi in [35, 33] { + // 3×2, then 1×1 with red 11 and green 22. + let file = rg16_file(w as u32, h as u32, dxgi, 2, &[top.clone(), vec![11, 22]].concat()); + let texture = Texture::parse(&file).unwrap(); + assert_eq!((texture.layout(), texture.bits_per_channel()), (Layout::Rgb, 16), "DXGI {dxgi}"); + assert_eq!(texture.decode16().unwrap(), rgb, "DXGI {dxgi}"); + assert_eq!(texture.decode().unwrap(), rgb.iter().map(|&v| to8(v)).collect::>(), "DXGI {dxgi}"); + let level = texture.mip_level(1).unwrap(); + assert_eq!(level.decode16().unwrap(), [11, 22, 0]); + assert!(matches!(level.decode16_with_limit(5), Err(DdsError::LimitExceeded { required: 6, limit: 5 }))); + assert!(Texture::parse(&file[..file.len() - 5]).unwrap().decode16().is_err()); + } + } + #[test] fn typeless_and_padded_16_bit_textures_are_read() { // Rows padded to 8 bytes, as other writers may store them: the padding is skipped. @@ -1380,8 +1456,9 @@ mod tests { padded.extend_from_slice(&[0xee, 0xee]); } assert_eq!(Texture::parse(&padded).unwrap().decode16().unwrap(), [1, 2, 3, 4, 5, 6]); - // The typeless forms read as the UNORM ones; typeless RGBA refuses premultiplied alpha too. - for (unorm, typeless, layout) in [(56u32, 53u32, Layout::Gray), (35, 33, Layout::GrayA), (11, 9, Layout::Rgba)] { + // The typeless forms read as the UNORM ones (R16G16's in its own test); typeless RGBA + // refuses premultiplied alpha too. + for (unorm, typeless, layout) in [(56u32, 53u32, Layout::Gray), (11, 9, Layout::Rgba)] { let pixels = spread16(3, 2, layout.channels()); let file = encode16(3, 2, layout, &pixels, DdsOptions::default()).unwrap(); assert_eq!(le32(&file, HEADER).unwrap(), unorm); diff --git a/crates/dds/tests/boundary.rs b/crates/dds/tests/boundary.rs index 3a891f73a..1dab9b33b 100644 --- a/crates/dds/tests/boundary.rs +++ b/crates/dds/tests/boundary.rs @@ -74,14 +74,17 @@ fn mip_views_reuse_shared_decoders_and_keep_their_bounds() { #[test] fn sixteen_bit_mip_views_preserve_samples_and_stored_offsets() { for (layout, channels) in [(Layout::Gray, 1), (Layout::GrayA, 2), (Layout::Rgba, 4)] { + // Two channels are stored as R16G16 and read back as red and green with blue 0. + let read = + |samples: Vec| -> Vec { if channels == 2 { samples.chunks(2).flat_map(|p| [p[0], p[1], 0]).collect() } else { samples } }; let pixels: Vec = (0..16).flat_map(|p| (0..channels).map(move |c| (p * 400 + c * 31 + 7) as u16)).collect(); let bytes = craft_dds::encode16(4, 4, layout, &pixels, DdsOptions { compression: DdsCompression::None, mipmaps: true }).unwrap(); let texture = Texture::parse(&bytes).unwrap(); assert_eq!(texture.compression(), DdsCompression::None); assert_eq!(texture.levels(), 3); - assert_eq!(texture.decode16().unwrap(), pixels); + assert_eq!(texture.decode16().unwrap(), read(pixels)); for (index, averages) in [(1, vec![1000, 1800, 4200, 5000]), (2, vec![3000])] { - let expected: Vec = averages.iter().flat_map(|p| (0..channels).map(move |c| (p + c * 31 + 7) as u16)).collect(); + let expected = read(averages.iter().flat_map(|p| (0..channels).map(move |c| (p + c * 31 + 7) as u16)).collect()); let level = texture.mip_level(index).unwrap(); let budget = (expected.len() * 2) as u64; assert!(matches!(level.decode16_with_limit(budget - 1), Err(craft_dds::DdsError::LimitExceeded { .. }))); diff --git a/crates/designcraft-format/src/lib.rs b/crates/designcraft-format/src/lib.rs index eab431eab..9ce481a3b 100644 --- a/crates/designcraft-format/src/lib.rs +++ b/crates/designcraft-format/src/lib.rs @@ -127,9 +127,10 @@ pub fn starts_designcraft(prefix: &[u8]) -> bool { craft_document_bundle::starts_with_mimetype(prefix, BUNDLE) } -/// Read the first-page PNG preview from a ZIP package, with a fixed 4 MiB cap. +/// Read the first-page PNG preview from an unprefixed native ZIP package, with a fixed 4 MiB cap. +/// Nonmatching signatures are rejected after at most four bytes read. pub fn read_preview(reader: R) -> Option> { - craft_document_bundle::read_preview_from(reader, PREVIEW) + craft_document_bundle::read_unprefixed_preview_from(reader, PREVIEW) } fn is_linked(document: &Value, id: &str) -> bool { diff --git a/crates/designcraft-format/src/tests.rs b/crates/designcraft-format/src/tests.rs index 38cf1c34f..736d2e17c 100644 --- a/crates/designcraft-format/src/tests.rs +++ b/crates/designcraft-format/src/tests.rs @@ -167,3 +167,37 @@ fn bytes_supplied_for_a_linked_asset_are_not_written() -> Result<(), Box(&bytes)?.assets, [("8".to_owned(), b"kept".to_vec())]); Ok(()) } + +#[test] +fn preview_uses_the_strict_signature_path_without_losing_cursor_independence() -> Result<(), Box> { + struct Counted { + cursor: std::io::Cursor>, + bytes_read: usize, + } + impl std::io::Read for Counted { + fn read(&mut self, out: &mut [u8]) -> std::io::Result { + let n = self.cursor.read(out)?; + self.bytes_read += n; + Ok(n) + } + } + impl std::io::Seek for Counted { + fn seek(&mut self, position: std::io::SeekFrom) -> std::io::Result { + self.cursor.seek(position) + } + } + let mut non_zip = Counted { cursor: std::io::Cursor::new(vec![0x42; 1 << 20]), bytes_read: 0 }; + non_zip.cursor.set_position(100); + assert_eq!(read_preview(&mut non_zip), None); + assert!(non_zip.bytes_read <= 4); + + let bytes = save(&json!({}), "DesignCraft test", Some(b"png"), &[], &[])?; + let mut cursor = std::io::Cursor::new(&bytes); + cursor.set_position(bytes.len() as u64); + assert_eq!(read_preview(cursor), Some(b"png".to_vec())); + let mut prefixed = b"MZsynthetic-prefix".to_vec(); + prefixed.extend(bytes); + assert_eq!(craft_document_bundle::read_preview_from(std::io::Cursor::new(&prefixed), PREVIEW), Some(b"png".to_vec())); + assert_eq!(read_preview(std::io::Cursor::new(prefixed)), None); + Ok(()) +} diff --git a/crates/develop-model/Cargo.toml b/crates/develop-model/Cargo.toml new file mode 100644 index 000000000..ec5848b86 --- /dev/null +++ b/crates/develop-model/Cargo.toml @@ -0,0 +1,21 @@ +[package] +name = "craft-develop-model" +description = "Raw develop settings as data: the non-destructive edit model (white balance, tone, colour, detail, optics, geometry, masks), control specs with ranges and defaults, process versions, presets, and the mapping to and from Camera Raw's crs: settings." +version.workspace = true +edition.workspace = true +license.workspace = true +rust-version.workspace = true +repository.workspace = true + +[lints] +workspace = true + +[dependencies] +craft-geom = { workspace = true } +craft-metadata = { workspace = true } +serde = { workspace = true } +serde_json = { workspace = true } +miniz_oxide = "0.9" + +[dev-dependencies] +proptest = { workspace = true } diff --git a/crates/develop-model/README.md b/crates/develop-model/README.md new file mode 100644 index 000000000..c6b07f204 --- /dev/null +++ b/crates/develop-model/README.md @@ -0,0 +1,51 @@ +# craft-develop-model + +Raw develop settings as data: the second of the three crates planned in craft-libs#587 +(`craft-raw`, `craft-develop-model`, `craft-develop`). No rendering, no GPU, no I/O. An app can +store, copy, merge, migrate and serialise a photo's edits without depending on the pipeline. + +```toml +craft-develop-model = { git = "https://github.com/storytold/craft-libs", rev = "" } +``` + +The base is LightCraft's `lightcraft-develop` and the `crs:` import from `lightcraft-engine` +(`crs.rs`, `crs_masks.rs`) at `a75497d6`. Issue numbers in comments are LightCraft's +(`storytold/lightcraft#N`). + +## What is here + +| Module | Contents | +|---|---| +| `settings` | `DevelopSettings`, the complete, serialisable description of a photo's look: white balance (Kelvin or relative scale), light, tone curve, HSL / mixer / point colour, B&W mix, colour grading, calibration, effects (vignette, grain), detail, optics (lens profile, embedded corrections, defringe), geometry and Upright, crop, masks (brush, linear, radial, range, AI segmentation), spots, red eye, lens blur, enhance, HDR. `ProcessVersion` / `Process`: which formulas an edit renders with, so later formula changes leave existing edits alone ([process versions](docs/process-versions.md)). | +| `controls` | `CONTROLS`: every numeric slider by id, with its label, section, range, default, step and track gradient. UIs and agents address sliders through it. | +| `presets` | `Preset`, `SettingsGroup` (the groups a copy, paste, sync or preset covers), `extract_groups`, `apply_partial` (a partial settings object merged at an amount), `deep_merge`. | +| `segmask` | `SegMask`: a compressed AI segmentation mask stored inside the settings. | +| `crs`, `crs_masks` | Camera Raw / Lightroom `crs:` properties (from `craft_metadata::parse_xmp`) mapped to a *partial* `DevelopSettings` JSON object, which is merged like a preset: global adjustments, tone curves, white balance (`Target` decides how a `crs:` temperature is read), crop, Upright, local corrections and retouch spots, with a report of what was read and what was left out. `preset_from_xmp` reads an XMP preset. The field table is in [xmp-interop](docs/xmp-interop.md). | + +Reading the `crs:` packet itself (names, structures, Camera Raw's number formats) is +[`craft-crs`](../crs/README.md)'s job; this crate decides what those settings mean for the edit +model. The mapping is a best-effort approximation of the other application's look, not a pixel match. + +## Different from LightCraft + +Fixes made here that LightCraft `a75497d6` does not have. It gets them when it switches to this crate. + +- `to_json_for_merge` states every setting the stored JSON leaves out at its default (HDR, the profile and its camera + local tone, the curve, Lens Blur's and Denoise's optional settings), not only Remove Hot Pixels. Copying a group + turns them off on the target, and a preset at an amount starts from them. +- `reset_section` resets the sliders of point colours and red eyes, Upright with its guides, and the lens profile and + Remove Chromatic Aberration switches. Settings from outside the app keep those sliders in range. +- `is_unedited` counts a chosen white balance as an edit. As shot, the numbers stay the photo's own. +- A preset at no amount adds no mask, and its Lens Blur focus mask follows its mask to the id the photo gives it. +- `crs:` import: a brush dab that is not a finite number is dropped, brush runs that differ in `crs:MaskInverted` stay + two components, `crs:RetouchInfo` is read only without `crs:RetouchAreas`, and an XMP preset keeps its masks. +- `Homography::from_quads` (`craft-geom`) solves a mapping that sends the origin to infinity. + +## Not here yet + +- Writing `crs:` back from `DevelopSettings`. LightCraft writes its own `lc:settings` in a sidecar; PhotoCraft's + Camera Raw writes `crs:`. That comes with the PhotoCraft switch, together with the migration of PhotoCraft's + current Camera Raw settings. +- The tests that render a mask or a spot to check its sense (inside or outside a radial, where a spot lands) + need the pipeline. They come back with `craft-develop`. The mapping half of each is kept here. +- LightCraft-only paths: `Target` from a catalog photo, and `.lrtemplate` (Lua) presets. diff --git a/crates/develop-model/docs/process-versions.md b/crates/develop-model/docs/process-versions.md new file mode 100644 index 000000000..20443b9bc --- /dev/null +++ b/crates/develop-model/docs/process-versions.md @@ -0,0 +1,132 @@ +# Process versions + +> **Changes:** [revision history](#revision-history) + +Every photo's develop settings record the **rendering process** they are interpreted by +(`DevelopSettings::process`, a `ProcessVersion` in `crates/develop/src/settings.rs`). Lightroom calls +this the process version. It lets the look of LightCraft improve (a new default tone curve, issue #146; +stronger Light sliders, issue #196) without changing a single photo someone has already edited. + +| Process | What it changes | +|---|---| +| **V1** | LightCraft's rendering from before process versions existed. Frozen. | +| **V2** | Highlights and Shadows keep fine detail (issue #632): their base layer (`local::tone_base`) is the edge-aware filter of a separable median of log luminance (radius 0.15 % of the long edge, at most 24 px, `local::BASE_DETAIL`) instead of log luminance itself, so twigs, lines and texture take their surroundings' shift and keep their contrast; region edges stay sharp. CPU (`local::prepare`) and GPU prepare branch on `local::tone_base_detail` (0 = no median under V1); the base plane is cached per process (`local::BaseKey`). Renders without Highlights or Shadows (global or local) are the same as V1's. Tone map unchanged. | +| **V3** | Pixel-scale sharpening (issue #757): Radius uses the original photo’s pixels, Detail controls halo damping, and downsized sources retain a response-matched sharpening band. V1 and V2 keep texture-band sharpening exactly. The sharpen plane is keyed by radius and process and invalidated after noise-reduction changes. The Highlights/Shadows base and tone map are unchanged from V2. | +| **V4** | V3 plus calibrated global Contrast (per channel) and Blacks (per-channel/luminance mix) on raws with a camera tone curve. Whites behaves exactly as V2, both signs; its calibration is a planned follow-up. Other sources and local adjustments retain V2 operators. See [calibrated Light operators](https://github.com/storytold/lightcraft/blob/a75497d6/docs/light-v3.md). | +| **V5** | V4 plus: a raw's tone curve rolls off into white in stops instead of reaching it within about a stop of the sensor's white, so raising Exposure keeps the highlights the sensor recorded (issue #1632). **Camera curve** (the look fitted to the embedded JPEG, or a DNG's `ProfileToneCurve`; `CameraTone`): past its last knot `CameraTone::apply_rolloff` closes the gap to white by `gap / (1 + c·(2^t − 1))` at `t` stops past the knot, with `c` matching the curve's slope there and the gap halving every stop in the end (`tone::ROLLOFF_STOPS`); `ToneMap::camera_rolloff_hdr` builds the table from it. Under V1 to V4 the curve past its last knot (fitted only to camera JPEG tones below 0.85, so 1 to 3 stops below the sensor's white on most photos) closes on white exponentially in linear light: the sensor's white renders at 8-bit 246 to 254 at Exposure 0 and 254 to 255 from Exposure +1. On the 11 CC0 corpus files with a fitted look (8 Sony, 2 Nikon, 1 Fujifilm) it now renders at 239 to 250 at Exposure 0 and 247 to 253 at +1. A DNG curve that reaches white at the sensor's white renders as before. **Generic curve** (raws without a camera curve, `ToneMap::rolloff_hdr`): from half a stop below its white point (`tone::GENERIC_KNEE_STOPS`) the same shoulder takes over, with the extended Reinhard curve's value and slope at the join, where V1 to V4 clip at the white point (scene 1.18 at default settings, ¼ stop above the sensor's white). The sensor's white renders at about 235, 248 and 252 at Exposure 0, +1 and +2 (V1 to V4: 239, 255, 255; the CC0 Canon R8 file and 6 CC0 DNGs without a camera curve). Content past the old clip point, such as a clipped sky, now renders up to 15 codes below white at Exposure 0 and reaches 255 about 5 stops past the sensor's white. Below the last knot or the join, JPEGs and other display-referred sources, and the camera fit itself are unchanged; CPU and GPU share the tone LUT. | +| **V6** | V5 plus: colour noise reduction filters the linear colour differences R−Y and B−Y with the joint method (issue #815, `docs/nr-color-joint.md`): edge-aware weights from a denoised guide shared by both differences, anisotropic diffusion over scales, a brake for isolated colour specks; Y is kept exactly. V1 to V5 keep the blurred chromaticity (`local::denoise`). CPU (`local::denoise`) and GPU (`render::denoise`) branch on `local::joint_colour_nr`. Renders with Color 0 are the same as V2's. | +| **V7** | V6 plus: film grain from crystal layers ([grain.md](https://github.com/storytold/lightcraft/blob/a75497d6/docs/grain.md), `crates/pipeline/src/crystal.rs`), after Aurélien Pierre's model: resolution independent (a preview is the export's grain box-downscaled), fading out at black and white, calibrated to Lightroom Classic's strength and width at mid grey. V1 to V6 keep their two-octave value noise exactly (`finish::ValueGrain`; on the GPU `F_GRAIN_MODEL` 0); `finish::GrainModel::new` picks the model per process. Renders without grain don't depend on this. | +| **V8** (the latest) | V7 plus: Highlights and Shadows take their edge-aware filter of log luminance without its fine detail (`local::detail_free`: each value clamped between its separable median at the V2 radius and the median of a 3× wider neighbourhood) instead of V2's plain median (`local::base_keeps_gaps`), so the gaps in dark lettering on a bright panel are not lifted into bright blocks (issue #3460). CPU (`local::tone_base`) and GPU (`render::tone_base`) branch on it; the base plane is keyed by process. Renders without Highlights or Shadows (global or local) are the same as V7's. | + +## The rule + +**A change that alters how existing settings render ships as a new process. V1 is frozen.** + +- A deliberate change of look (tone model, slider response, default curve, how a stage interprets a + value) goes into a new process. Photos stay on the process they have until someone runs Update to + Current Process (or Reset). +- Bug fixes that make output correct where it was broken (a crash, NaN or black output, a decoder + error, CPU and GPU disagreeing) are not looks and can land in place, as before. +- Changes to how a file is decoded or which camera colour it gets change the source, not how settings + are interpreted; the process doesn't reach that stage today. + +**Neutral display tone map** (JPEG, PNG and other display-referred sources with Contrast, Whites and +Blacks at 0) is the identity up to white: the SDR shoulder no longer pulls 1.0 down to 0.9875 (8-bit +255 to 254, issue #1945). It landed in place as a bug fix, since the tone map promised identity at +neutral settings; edited curves keep the shoulder and their V1 look. + +**AI mask edges** (Object and Describe selections stored as a model's grid) follow the photo's edges +when they are enlarged to the output (issue #3272): the plain enlargement spilled 1–2 px onto the +background, which a raised Exposure turned into a bright outline around the subject in previews and +exports. Existing AI masks become 1–2 px tighter at a subject's edges, on every process; their +inside, their outside and edges without contrast in the photo are unchanged. It landed in place as +a bug fix: the outline is output that isn't in the photo nor in the edit, not a look anyone chose. + +**A mask whose first component is Intersect** starts from that component, on the CPU and the GPU +(issue #1889). It used to start from nothing, so alone it selected nothing, with a later Add it gave +only what was added, and with the mask's Invert it gave the whole photo. Such masks now include the +first component, on every process. It landed in place as a bug fix: intersecting with nothing is not +a look anyone chose. + +**Lettering under Highlights and Shadows** (V8) no longer grows blocks of the wrong tone. V2's base +is the edge-aware filter of a separable median alone. Dark lettering on a bright panel (a bus +number, a sign) has strokes and gaps about as wide as the median's radius, so each row and column +window was close to half letter and half panel, and the median picked one tone or the other in +rectangles: it filled the gaps between the letters and their counters with the letters' tone. +Shadows then lifted those patches of panel by over 1 EV, into bright blocks beside the letters. From V8 each +value moves toward that median only as far as the median of a 3× wider neighbourhood agrees +(`local::detail_free`). A twig against a wall has both medians on the wall's side and takes its tone, +as before (#632); the gap between two strokes sits in a wider neighbourhood that is mostly panel, the +two medians disagree, and the gap keeps its own tone. The letters themselves count as fine dark detail +on the panel and keep their contrast, as twigs do. V8 differs from V7 under Highlights or Shadows only in detail +about as fine as the radius, mostly where it is packed closely (lettering, grilles). V2 to V7 +are released and keep the blocks (`tests_legacy` locks V1 and V2); Update to Current Process moves a photo past them. + +## Adding a process + +1. Add a variant to `Process` (`V2`), append it to `Process::ALL` (oldest first), give it its number in + `Process::version` and make it `Process::LATEST`. +2. The compiler then points at every `match` on `Process`. The base tone map is chosen in one place, + `lightcraft_pipeline::finish::base_tone` (both the CPU and the GPU renderer take it from there): give + V2 its own arm and leave V1's alone. A process that changes another stage branches there the same + way, on `s.process.process()`; if that stage is cached (`Plan::lin_key`, the planes in `local.rs`), + add the process to its key. +3. Keep `settings_saved_before_process_versions_load_as_v1` (`crates/develop/src/tests_process.rs`) + passing: settings saved without the field must stay V1, not become the new latest. That is the + field's `#[serde(default = "ProcessVersion::legacy")]`; the struct-level `Default` gives new + settings the latest instead. +4. Render a few procedural scenes on both processes and compare, and update `docs/parity-checklist.md`. + +## What gets which process + +| | Process | +|---|---| +| A newly imported, merged or Lightroom-imported photo | the latest | +| Settings saved without the field (catalogs and their snapshots, versions and history, `lc:settings` in XMP sidecars, browser libraries: everything from before process versions), or with a damaged value | V1 | +| Reset (`develop.reset`) | the latest | +| Reset of a section or a slider | unchanged | +| Update to Current Process (`develop.updateProcess`) | the latest, for photos on an older one; one undo step. The menu item follows the selection; a call with `ids` / `id` acts on those photos whatever is selected | +| Virtual copy, duplicate | the source's | +| Copy / paste / sync / Auto Sync / presets | unchanged (see below) | +| `crs:` edits (XMP from other raw developers, Lightroom catalogs, imported presets) | unchanged; a new photo has the latest | +| Restoring a version or history step | the one it had | + +**Copy, paste, sync and presets** never carry the process: it is in no settings group, so the photos +they change keep their own and interpret the pasted values with it. (Lightroom offers the process +version as a separate checkbox when syncing; LightCraft's groups are coarser and keep it out.) Partial +settings JSON that names `process` itself (`develop.merge`, a hand-written preset) sets it. + +**Lightroom edits** are re-interpreted by LightCraft's mapper (`crates/engine/src/crs.rs`), which is +written against the current rendering. `crs:ProcessVersion` numbers Adobe's renderer, not ours, and is +ignored; a photo imported with Lightroom edits is on LightCraft's latest process, and an existing +LightCraft photo that receives them keeps its own. + +**A number above this build's latest** (a library or sidecar written by a newer LightCraft) loads, is +kept when saved, and renders with the newest process this build has. Update to Current Process never +moves a photo to an older process; Reset does move it to this build's latest. + +**A damaged value** (anything but a whole number from 0 to 2^32 - 1; `2.0` counts as 2) reads as V1, +like a missing field, and costs nothing else: the rest of the settings load from the catalog, a +snapshot, the op log or an `lc:settings` sidecar as usual. The damaged value isn't kept: the photo is +saved as V1. + +## Storage + +The process is saved as `"process": ` in the settings JSON, except V1, which is left out. +Settings made before process versions existed are therefore saved exactly as before, and their +preview-cache keys (`DevelopSettings::hash64`) don't change. `develop.get` (MCP `get_develop`) always +states the process. + +From process V3 on, persistent thumbnail, view-render and variant keys also include the +resolved rendering process. A future number can keep the same settings hash across builds +while resolving to different operators, so those keys must differ. V1 and V2 omit this +extra field and retain their existing cached renders. No cache-version bump is needed. + +## Revision history + +| Date | Change | Summary | +|---|---|---| +| 2026-11-08 | minor | V8: the Highlights/Shadows base keeps the gaps in dark lettering (#3460) | +| 2026-11-07 | minor | V7: film grain from crystal layers ([grain.md](https://github.com/storytold/lightcraft/blob/a75497d6/docs/grain.md)); V1 to V6 keep their value noise | +| 2026-11-05 | minor | V5: a raw's tone curve rolls off into white in stops, so raising Exposure keeps recorded highlights (#1632) | +| 2026-10-12 | minor | Calibrated Contrast and Blacks, V2 Whites, resolved-process cache keys and number coordination | diff --git a/crates/develop-model/docs/xmp-interop.md b/crates/develop-model/docs/xmp-interop.md new file mode 100644 index 000000000..78cb1f467 --- /dev/null +++ b/crates/develop-model/docs/xmp-interop.md @@ -0,0 +1,342 @@ +# XMP sidecars and interchange + +LightCraft keeps its catalog as the source of truth, and can also store each photo's metadata and develop settings in +an XMP sidecar next to the original. Sidecars let edits travel with the files (backups, another LightCraft library, +other tools), and let LightCraft pick up edits made elsewhere. + +## Sidecar files + +| | | +|---|---| +| Name | `.xmp` by default (`IMG_0001.CR3` → `IMG_0001.xmp`); `.xmp` (`IMG_0001.CR3.xmp`) with `naming: "full"`. Reading accepts either (preferred first) and `.XMP`. With stem naming, files sharing a stem don't share a sidecar: see *Shared names* below. | +| Write | `photo.saveMetadataToFile {ids?}` (Photo ▸ Save Metadata to File, ⌘S), or automatically after every change with `library.xmpPreferences {autoWrite: true}` (File ▸ Automatically Write Changes into XMP). Slider drags are written once, when the drag ends; undo/redo rewrite the sidecar. An existing sidecar is **merged into, never replaced** (see *Saving into an existing sidecar*). Written atomically (temp file, fsync, rename). The result lists `written`, `merged` and `backups`. | +| Read | On import (`library.import`, the report counts `sidecars`), and `photo.readMetadataFromFile {ids?}` (one undo step). Manual rereading uses embedded XMP in raw/DNG and JPEG files when no sidecar exists. A discovered sidecar that cannot be read or parsed is reported in `failed`, without applying embedded values. `photo.readMetadataFromFile` never writes the sidecar, even with auto-write on: writing back what it has just read would add `lc:settings`, which later reads prefer over another app's `crs:` edits (issue #934). A file arriving in an import is ranked as if it were catalogued already: it reads its own `.xmp` when another file of its stem (a raw first) owns the shared stem sidecar (issue #1905). | +| Preferences | `library.xmpPreferences {autoWrite?, naming?: stem\|full}`, stored in the library's `prefs.json`. | + +What we write (standard namespaces, so other tools can read the metadata): + +| Field | XMP property | +|---|---| +| Rating 0–5 | `xmp:Rating` | +| Colour label | `xmp:Label` (`Red`, `Yellow`, `Green`, `Blue`, `Purple`) | +| Title / caption / copyright / creator | `dc:title` / `dc:description` / `dc:rights` / `dc:creator` | +| Copyright status | `xmpRights:Marked` (`True` copyrighted, `False` public domain, absent = unknown) | +| Rights usage terms / copyright info URL | `xmpRights:UsageTerms` / `xmpRights:WebStatement` | +| Keywords | `dc:subject` (names: `Places`, `Italy`, `Rome`) and, when any keyword has levels, `lr:hierarchicalSubject` (paths: `Places\|Italy\|Rome`, with the flat keywords too) | +| Capture time, GPS | `exif:DateTimeOriginal`, `photoshop:DateCreated`, `exif:GPSLatitude`/`GPSLongitude` | +| Pick / reject flag | `lc:flag` (`pick`, `reject`, `none`) | +| Location | `lc:location` | +| Develop settings | `lc:settings` — our complete `DevelopSettings` as JSON (exact round trip, incl. masks, spots, crop and the rendering process; settings without `process` are V1, see [process-versions.md](process-versions.md)) | + +`lc:` is `http://ns.lightcraft.app/lc/1.0/`. + +Reading merges into the catalog with the **sidecar winning** for every field it states; fields it doesn't state are +kept. The one exception is the **capture time**: a valid time embedded in the file (EXIF/IPTC) wins. Invalid EXIF +clock values are skipped, allowing DateTimeDigitized, IFD0 DateTime or embedded XMP to supply the time. If the file +has no valid capture time, the sidecar's `exif:DateTimeOriginal`, else `photoshop:DateCreated`, else `xmp:CreateDate` +(ISO 8601) is used — on import (it then also files a copied photo in its date folder) and by +`photo.readMetadataFromFile` (undoable). An incomplete or malformed XMP timestamp is not projected as a capture time, +remains available in the raw property map, and does not prevent the next valid capture-time property from being used. +`xmp:Rating="-1"` (the XMP convention for rejected) sets the reject flag. Develop settings come from +`lc:settings` when present (exact); otherwise from the `crs:` fields below (approximate). + +When foreign `crs:` settings are only partly transferable, `library.import` includes per-photo `warnings` in its +report. Warnings identify unsupported profile names, saved Upright geometry that will be recalculated, and other +unmapped adjustments; they do not change the source packet or become catalog edits. + +Manual rereading and undo leave the JPEG original unchanged. Manual rereading also leaves sidecar files unchanged, +even with automatic XMP writing on. With automatic XMP writing off (the default), undo/redo leave sidecars unchanged; +with it enabled, subsequent edits and undo/redo can trigger the existing sidecar writer. `photo.allMetadata` uses +its already loaded file bytes for embedded XMP, with an existing sidecar taking precedence. + +Manual JPEG rereading uses the first standard XMP APP1 before the first SOS (scan) or EOI (end) marker. +Scanning is limited to a 16 MiB header span, including SOI, segment headers and skipped payloads, and 4096 +marker/fill steps after SOI. Non-APP1 payloads are skipped without loading them. Each APP1 payload must be +complete and is at most 65,533 bytes. Header extraction succeeds for the first complete +standard XMP packet within both limits, including a packet ending exactly at either limit; otherwise it +fails without a whole-file fallback, including on I/O errors or an incomplete APP1 whose available bytes +form parseable XMP. A valid JPEG with +XMP beyond those limits therefore cannot be manually reread through this path. Extended XMP assembly and +packets between scans are not supported by manual JPEG rereading. + +Packet completeness is stricter than the shared best-effort JPEG extractor; it is not strict whole-JPEG +validation. A complete early XMP packet can be returned without examining the remaining file. Import and +`photo.allMetadata` retain their existing extraction paths. Command regressions in +`crates/engine/src/tests/xmp.rs` cover metadata/undo and sidecar precedence, an over-nested XMP packet and a +truncated APP1 without an XMP signature. Separate reader cases in `sidecar::jpeg_header_tests` use small +counted readers and injected limits for span/step boundaries, complete versus truncated APP1, early stopping, +short reads and I/O errors. + +## Saving into an existing sidecar + +A sidecar may already hold another application's data — e.g. its `crs:` develop settings and `xmpMM:History` — often +the only copy of those edits outside that application's catalog. Saving never drops it: + +- LightCraft **owns** the properties in the table above: `xmp:Rating`, `xmp:Label`, `dc:title`, `dc:description`, + `dc:rights`, `dc:creator`, `dc:subject`, `lr:hierarchicalSubject`, `Iptc4xmpCore:Location`, `Iptc4xmpCore:AltTextAccessibility`, + `Iptc4xmpCore:ExtDescrAccessibility`, `photoshop:City`/`State`/`Country`, `xmpRights:Marked`/`UsageTerms`/ + `WebStatement` and everything in `lc:`. They are replaced on every save, and removed when LightCraft has no value + (clearing a title in LightCraft clears it in the file). All of them are read back on import, so the library starts + from what the sidecar said. +- The **capture time** (`exif:DateTimeOriginal`, `photoshop:DateCreated`) and **GPS** (`exif:GPSLatitude`, + `exif:GPSLongitude`) are replaced only when LightCraft has a value; otherwise the file's stay. +- **Everything else is kept byte for byte**: other namespaces (`crs:`, `xmpMM:`, the rest of `lr:`, unknown + ones), `xmp:CreatorTool`, comments, the packet wrapper and padding. LightCraft's properties go into one + `rdf:Description` of their own; owned properties written by another application (in attribute or element form) are + removed from its description, which otherwise stays as it was. +- Ownership follows the namespace URI, not the prefix spelling. A foreign namespace bound to `lc:` or `xmp:` + stays foreign: its properties are preserved and do not become LightCraft settings or ratings. Genuine namespace + aliases remain interchangeable, including namespace declarations containing XML character references. +- A sidecar that can't be read as XMP (not well-formed, not UTF-8, no `rdf:RDF`) is first copied to + `.xmp.bak-