Release v4.0

.gitattributes

@@ -0,0 +1 @@
+tests/assets/performance/**/*.3mf filter=lfs diff=lfs merge=lfs -text

.github/workflows/release.yml

@@ -98,7 +98,7 @@ jobs:
                       **macOS:**
                       1. Download the .dmg file for your Mac:
                          - Apple Silicon (M1/M2/M3): *_aarch64.dmg
-                         - Intel: *_x86_64.dmg
+                         - Intel: *_x64.dmg
                       2. Open the DMG and drag Kromacut to Applications
                       3. Remove quarantine (required for unsigned apps):
                          sudo xattr -d com.apple.quarantine /Applications/Kromacut.app

.gitignore

@@ -32,3 +32,7 @@ test-results/
 src-tauri/target/
 src-tauri/gen/
 src-tauri/WixTools/
+
+# Agent workspace files
+.agents/
+.profiles/

AGENTS.md

@@ -13,9 +13,13 @@ geometry, slicer behavior, and print instructions at the same time.
 
 ## Domain Notes
 
-- **Transmission Distance (TD):** Used by auto-paint to model light through thin filament layers
-  with Beer-Lambert-style optical simulation. TD is not just a display value; changing how it is
-  stored or rounded can change generated layer stacks.
+- **Hiding Distance (HD):** Used by auto-paint to model light through thin filament layers with
+  Beer-Lambert-style optical simulation. `filament.td` stores the frontlit hiding distance in mm
+  (introduced in profile schema v2; v3 adds appearance evidence); the field keeps its historical
+  `td` name for data compatibility. Conventional
+  backlit/lithophane Transmission Distance values are an *input format* only — converted ×0.1
+  (`FRONTLIT_TD_SCALE`) at entry or during the one-time v1→v2 migration, never stored. HD is not
+  just a display value; changing how it is stored or rounded can change generated layer stacks.
 - **Auto-paint layers:** Auto-paint chooses physical filament stacks for target image colors. The
   worker path exists so optimizer choices such as exhaustive, simulated annealing, and genetic
   search do not freeze the UI.

CHANGELOG.md

@@ -2,6 +2,57 @@
 
 All notable changes to Kromacut are documented in this file.
 
+## v4.0.0 - 2026-09-10
+
+### Upgrade notes
+
+- **Back up important filament profiles before upgrading.** Legacy photo-based opacity-calibration records are no longer used and are removed on load; affected filaments should be recalibrated with the new wedge workflow. This does not refer to the new Stack Matrix photo measurements.
+- **Regenerate Auto-paint results before printing.** The updated optical model and layer planning can change predicted colors, stack heights, and swap plans. Check the new instructions against your slicer settings.
+- **TD is now frontlit Hiding Distance (HD).** Older uncalibrated values are converted once on load or import. Conventional backlit/lithophane TD remains an accepted input and is converted to HD; do not manually rescale already-migrated profiles.
+- **Preview colors remain predictions, not guaranteed print matches.** Calibration evidence and confidence help identify better-supported estimates, but results still depend on the filament, printing conditions, and lighting.
+
+### Added
+
+- **Stack Matrix calibration** - Print many fixed-depth filament recipes on one board, then photograph and align the result to measure their colors. Choose 2–8 filaments, recipe depth, capacity, and backing; Kromacut prints every combination that fits or selects a color-diverse subset using the HD model. The photo tools include orientation markers, rotation, precision alignment, a projected grid, and corrected previews, with explicit review for uncertain alignment and optional reference-marker correction.
+  Compatible matrices supply measured colors and bounded estimates for nearby recipes. Broader optical fitting must improve held-out measurements; unsupported combinations retain conservative estimates. Derived fitting leaves saved HD values, raw measurements, and physical export colors unchanged. Same-ID legacy imports cannot erase newer appearance evidence.
+  Saved boards remain attached to their owning profile and retain their recipes, regular and first-layer heights, and measurements. New boards follow the current 3D print settings. Plans survive restarts and can be re-downloaded; completed boards can be rephotographed or deleted. Desktop exports use Save As, and cancelled or failed saves do not register a new plan. Calibration 3MFs sanitize invalid characters in filament names.
+- **Palette Proofs** - Export a job-specific 3MF of reachable candidate stacks for selected image colors. Record the closest patch, ties, or **None**, with **Best available**, **Close**, or **Dead on** match quality. Draft results persist across restarts. **Continue targets** tests nearby untried challengers; **New targets** explores other colors, without padding exhausted rows with unrelated candidates. Proofs retain their original settings and can be reopened, re-downloaded while compatible, or deleted. Judgments provide bounded appearance corrections without changing HD calibration or physical filament assignments; broader fits require held-out improvement.
+- **Preserve color separation** - Enhanced matching can assign distinct image colors to distinct printable colors within a hard predicted ΔE limit. Strict mode rejects incomplete results; otherwise unmatched colors merge into valid surviving matches. Results distinguish **Exact optimum**, **Best found**, and **Partial palette**, report preserved colors and repeats, and block printing when no valid mapping exists. The search removes unnecessary filament repetitions. This option and Height dithering are mutually exclusive.
+- **Prediction confidence** - Printable colors report whether they come from exact recipe measurements, interpolation, fitting, or simulation. Matching considers evidence strength alongside predicted color error without weakening the separation limit or overriding Dead-on anchors.
+- **Printable feature-size preview** - Inspect detail at the selected effective extrusion width. The At-risk/Printable preview shows narrow regions and likely neighboring-color takeover. Optional **Omit at-risk colors from matching** applies that substitution throughout matching, preview, and export; isolated regions without a defensible replacement retain their original color. The same line-width setting controls height-dither block size. This is a printability estimate, not a substitute for checking the slicer.
+- **2D touch-up tools** - Added palette-safe Brush, Eraser, Fill, Text, and color picking. Text can be moved, resized, and wrapped; edits support undo while image adjustments remain non-destructive.
+- **3D inspection and color modes** - Added Color accurate, Shaded, Transparent, and Wireframe views, plus a Simulated/Physical filament-color toggle. Color accurate displays the selected swatches without lighting or tone-mapping changes; it does not guarantee a physical color match. These remembered display options never change exported geometry or materials.
+- **Carrier-free Flat Paint** - The experimental Flat Paint workflow now supports face-up prints without a clear carrier layer. Normal color-stack order is retained over backing, with visible blends aligned at the flat top surface and no artwork mirroring. Preview, exports, and instructions follow the selected orientation.
+- **Landing page and web routing** - Added a responsive landing page at `/` and moved the browser tool to `/app`, preserving same-origin saved data and `/docs/...` links. Includes returning-user launch preferences, themes, desktop downloads, search metadata, and direct-route support. Settings provides a direct link to documentation.
+- **Community showcase** - Six responsive project cards combine sixteen preview, slicer, and finished-print images: King of Hearts, Hobbits and Dragons, HOPE, Titan, Batmanga, and Naruto. Captions distinguish predictions from physical results and include creator credits, available source links, and full-size views.
+- **Collapsible controls** - Settings groups in 2D and 3D can collapse while retaining important status and quick actions. Their state is remembered.
+- **Filament templates and palette tools** - Added unofficial Bambu Lab PLA Basic supplier palettes and read-only filament templates with estimated HD values. Templates can be saved as editable profiles. Built-in, supplier, and custom palettes can be cloned; custom colors support names and persistent enable/disable flags. Older palette files remain compatible, and migration to the expanded built-in catalog retains custom palette and profile selections.
+- **HueForge spool import** - Import CSV or TSV spool libraries with flexible columns, quoted fields, multiline values, and a UTF-8 BOM. Names, brands, colors, and spool UUIDs are retained, with duplicate UUIDs made independently editable.
+- **Calibration documentation and community links** - Added an illustrated guide to HD, wedge calibration, Palette Proofs, and Stack Matrices, plus Reddit links in Settings and the README.
+- **Experimental multi-plate switch** - Added a remembered preview toggle and animation. It is explicitly unfinished and does **not** split images or change generated prints.
+- **Developer diagnostics and validation** - Optional desktop recording captures Auto-paint settings, evidence, progress, and final stacks without the source image or changes to optimizer selection. It is off by default. Offline tools create frozen diagnostic print bundles, replay predictions against preserved recipes, and evaluate withheld recipes, filament pairs, and boards. Reports distinguish model estimates from photographed evidence and disclose shared-photo limitations; these tools do not modify saved calibration.
+- **Regression and performance coverage** - Added deterministic stack fixtures, printable-layer and export checks, prediction-consistency and held-out-validation tests, reproducible optimizer benchmarks, and browser coverage for calibration, persistence, exports, and the landing page. Color-quality tests assess predicted colors at printable layer heights, not independently measured print accuracy.
+
+### Changed
+
+- **Frontlit wedge calibration and HD** - Replaced the legacy photo-based opacity workflow with camera-free printed wedges and adjacent opaque reference rails. Quick reads measure scalar HD; additional bases refine a constrained channel estimate. Partial sessions save only completed filaments, and editing a calibrated swatch temporarily disables its calibration without deleting it. STL and multi-material 3MF exports retain the settings used to print the wedge. HD storage semantics were introduced in profile schema v2 and are retained in v3, which also preserves validated appearance evidence.
+- **Auto-paint optical model** - Blending now uses linear-light sRGB and substrate-aware HD estimates. Wedge refinements remain local to tested bases; compatible Stack Matrix evidence can support richer fits within measured thickness ranges. Interpolation and measured-prefix corrections fade outside their support, with conservative estimates used beyond it.
+- **Auto-paint matching and search** - Scoring, preview, and export now share the final layer-snapped, height-limited stack. Only results matching the current layer settings are used for slicing. Matching evaluates predicted CIEDE2000 color error at printable heights, considers poorly matched colors and prediction confidence, and reuses the selected layers in the preview. New Fast, Balanced, Thorough, Deep, and Exact effort tiers replace older algorithm choices, with repeat limits, transition detail, stable seeds, deterministic beam-search tie-breaking, and search progress. Saved algorithm selections migrate to the nearest tier.
+- **Performance** - Reduced startup, 3D-tab, calibration, and optimizer overhead through worker offload, deferred preparation, bounded caches, and lower-allocation processing. Completed work is reused when inputs are unchanged, while deterministic stack and export results are preserved.
+- **Results display** - Transition Zones includes a proportional stack bar and compact height rows. Calibration confidence and optimizer status are easier to scan.
+- **Height dithering** - Replaced Floyd-Steinberg with an error-conserving Stucki kernel while retaining block sizing and edge protection.
+- **Dependency security updates** - Updated Tauri to 2.11.1 to address a Windows IPC origin-confusion issue, alongside Rust dependency and development-tooling updates. The production npm audit is clear; remaining npm findings are confined to development tooling.
+
+### Fixed
+
+- **Desktop file exports** - Filament-profile `.kfil` exports use Save As, handle cancellation without reporting success, and surface write errors. Large 3MF exports stream XML in bounded chunks to avoid desktop WebView read and string-size failures.
+- **Profile and palette persistence** - Failed storage writes no longer report success or replace working state. Imports validate hiding distances and duplicate filament IDs; legacy stored ID collisions are repaired without dropping filament rows, while ambiguous appearance evidence is discarded.
+- **Remembered print settings** - Saved Auto-paint settings load before persistence can replace them with defaults. Unsaved filament edits remain authoritative, Max Height and wedge layer height are remembered, and Reset Print Settings also resets Smooth Meshing.
+- **Max Height and foundation opacity** - Height caps round down to printable boundaries; compression and trimming preserve the foundation's opacity minimum, and impossible foundations are rejected.
+- **Auto-paint edge cases** - Center and Edge priority use actual image regions. Blank seeds, cache inputs, zero-HD limits, and the 500-layer ceiling behave consistently.
+- **Crop controls** - Crop overlays no longer block Save, Cancel, or the image-size controls.
+- **Smooth 3MF integrity** - Validate and, where needed, retriangulate smoothed faces at export precision to prevent pinhole open or non-manifold edges in large exports. STL exports were unaffected.
+
 ## v3.1.0 - 2026-06-18
 
 ### Added

CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md