Release v4.0

[vycdev]

Summary

This PR promotes the full Kromacut v4.0.0 release train from develop to main. It is a major release spanning physical filament calibration, appearance-aware Auto-paint, image preparation, 3D inspection, export reliability, the web experience, and desktop security updates.

Highlights

Three complementary physical calibration workflows

• Hiding Distance: camera-free printed wedges with Quick and Accurate multi-base measurements, per-channel HD values, confidence scoring, partial result entry, and calibrated profile persistence.
• Palette Proof: image-driven target selection from original or fitted/achievable colors, printable candidate matrices, iterative continuations, match-quality judgments, and regularized appearance fitting.
• Stack Matrix: HD-guided selection from large fixed-depth recipe spaces, worker-backed 3MF creation, photographed-board orientation and alignment, perspective correction, LUT extraction, reference-marker lighting correction, and profile-integrated appearance evidence.

Better Auto-paint and physical output

• Hiding Distance replaces ambiguous stored TD values, with one-time migration and per-channel optical behavior.
• Enhanced matching scores the same layer-snapped physical stack used by preview and export with deterministic CIEDE2000-based optimization.
• Added optimizer effort tiers, progress reporting, repeated-swap controls, transition detail, stable seeds, region weighting, and Preserve color separation.
• Palette Proof and Stack Matrix evidence improve achievable-color fitting without introducing a second stack simulator.
• Added carrier-free Flat Paint, producing an unmirrored, face-up print without a transparent carrier.
• Added Simulated/Physical preview colors and Shaded, Transparent, and Wireframe inspection modes.

Image preparation and workflow

• New responsive landing page at /, with the tool moved to /app.
• Hard-edged Brush, Eraser, Fill, Text, and color-picker touch-up tools.
• Supplier palettes and filament-profile templates, beginning with Bambu Lab PLA Basic.
• Palette cloning, editable color names, and per-color enable/disable controls.
• Collapsible 2D and 3D control groups with remembered state.
• Improved crop workflow, settings navigation, and in-app calibration theory documentation.

Reliability and compatibility

• Hardened smooth meshing and serialized 3MF topology against slicer-visible open or non-manifold geometry.
• Streamed large desktop exports and moved heavy calibration/export work off the main UI thread.
• Added safer profile validation and schema-v3 appearance-evidence import/export.
• Added HueForge spool CSV/TSV profile imports.
• Updated Tauri and supporting dependencies to resolve applicable security alerts.
• Expanded deterministic optimizer, calibration, meshing, export, routing, and browser-flow regression coverage.

Release gallery

Landing page	2D touch-up tools
Enhanced Auto-paint result	3D inspection modes
Palette Proof target selection	Stack Matrix photo workflow

Open the complete v4.0.0 screenshot gallery

Image preparation and palettes

Image workspace	Supplier palettes
Named and selectively disabled colors	Crop workflow

Auto-paint and 3D output

Calibrated HD profile	Carrier-free Flat Paint controls
Physical filament preview colors	Application settings

Calibration workflows

Calibration hub	Accurate multi-base HD calibration
Frontlit calibration wedge	Selected Palette Proof colors
Palette Proof map	Stack Matrix setup
Calibration theory documentation

Showcase artwork uses public-domain images from Wikimedia Commons: Van Gogh self-portrait and Rainbow landscape. Calibration screens use Kromacut's repository test profile and genuine application states; no physical print results were simulated.

Compatibility notes

• Older uncalibrated opacity values migrate once to the frontlit HD scale.
• Calibrations produced by the removed photo-based workflow should be recreated with the new frontlit wedge.
• Profile schema v3 adds bounded Palette Proof and Stack Matrix evidence while preserving v2 HD semantics.
• Multi-plate work in this release is preliminary scaffolding and does not yet change generated output.

Validation

• Earlier release review: 614 Node regression tests and 4 Rust tests passed.
• Version-bump verification: npm run lint, npm run build, and cargo check --locked passed for 4.0.0.
• Final release-day npm run test:e2e: 17 smoke tests passed, including browser STL/3MF exports, landing/docs routes, keyboard focus, profile Save As, and Stack Matrix saves/settings/reopening.
• Final release-day Palette Proof browser test: passed, including persistence and frozen 3MF download.
• All app/package/update-feed versions agree on 4.0.0; changelog extraction includes the upgrade notes and excludes previous releases.
• GitHub branch-direction check.

Release checklist

• Date CHANGELOG.md for 2026-09-10 and replace the updater's upcoming-release placeholder.
• Preserve the profile-backup, legacy recalibration, and regenerated-stack upgrade warnings.
• Merge this PR and push v4.0.0 at the merge commit.
• Confirm all native build jobs and the website deployment succeed.
• Verify published installer assets, release notes, and live update metadata before announcements.

Packaged-installer runtime testing on every operating system is not claimed by these checks.

[vycdev2]

Phase 1 final: revise before running the grouped-validation experiment

Verdict: Revise. The grouped held-out validation implementation was not started because the mandatory frozen-base K-logo Exact checkpoint failed before any production change. Supported Node 22 matches the refreshed 779,955 iteration count and all reported stack semantics, but not the checked-in final-stack fingerprint; Node 24/26 also diverges on counted iterations. Refreshing the golden merely to pass was explicitly prohibited.

No experimental branch was pushed, no draft PR was opened, and nothing was merged. Detailed raw attempts and the failure report are retained in /opt/data/research/kromacut-overnight-2026-08-31/results/phase-1/. The next run should first make the benchmark reproducible on an explicitly pinned supported Node runtime, then restart phase 1 from a newly frozen base.

This was generated by an AI agent (vycdev2). Please verify any changes before merging or applying.

[vycdev2]

Phase 1 restart checkpoint: known baseline mismatch recorded

Frozen base 36f88893674bba53c6d7edda5734ac127a13e269 was fetched from upstream/develop and remains unchanged. On Node 22.23.2, the calibrated K-logo Exact replay reproduced 779,955 iterations, score 55246513.08145709, the expected order, 3 repeats, 10 transition zones, 52 physical layers, 4.48 mm height, and 22/27 uniquely preserved colors. Its semantic result still has fingerprint final-stack-v1-ef8db13469d7ed46 rather than the checked-in final-stack-v1-9a83dcfa775aae0f, so the benchmark exits on that assertion.

Per the latest explicit override, this mismatch is recorded once and is non-blocking for the grouped held-out validation experiment. No golden, profile, calibration data, source, or test has been changed to hide it. The implementation will continue from the frozen base and will preserve exact Stack Matrix and Palette Proof anchors.

This was generated by an AI agent (vycdev2). Please verify any changes before merging or applying.

[vycdev2]

Phase 2 checkpoint: bounded hybrid reranking implemented

The hybrid experiment is running from frozen upstream/develop base 36f88893674bba53c6d7edda5734ac127a13e269, independently of phase 1. The known Node 22.23.2 calibrated fingerprint mismatch was recorded once before implementation and no golden was edited to conceal it.

The branch keeps CIE76 for continuous candidate generation, then reranks a deterministic bounded printable shortlist using realized CIEDE2000 plus the existing confidence cost. The shortlist retains the selected snapped layer and immediate printable neighbors. Separation limits/reporting use realized CIEDE2000, and preview height mapping consumes all optimizer final-stack target mappings.

Measured checkpoint:

• Node 22.23.2 full suite: 546/546 passing
• ESLint and production build: passing
• deterministic benchmark repeat: 8/8 rows identical
• fixed-palette average mean/p95/worst ΔE00 improvements: 0.537 / 2.914 / 16.962; coverage@6 improved 0.0131
• end-to-end average mean/p95/worst ΔE00 improvements: 0.071 / 3.224 / 17.270; coverage@6 decreased 0.0479
• Preserve-mode unique counts improved 23→31, 23→37, 18→26, and 40→46
• median end-to-end runtime overhead: 28.36%; score evaluations unchanged; average measured peak RSS decreased 20.96 MiB

Draft experiment: #74

This was generated by an AI agent (vycdev2). Please verify any changes before merging or applying.

[vycdev2]

Phase 2 final: Promote for maintainer review

Verdict: Promote as a draft experiment, do not merge automatically.

The bounded hybrid reranker preserved the fast CIE76 first stage. Across eight fixed-palette comparisons, average weighted mean/p95/worst ΔE00 improved by 0.537 / 2.914 / 16.962, with coverage@6 improving by 0.0131. Across eight end-to-end searches, average mean/p95/worst improved by 0.071 / 3.224 / 17.270; coverage@6 decreased by 0.0479. Preserve-mode unique counts improved in every fixture: 23→31, 23→37, 18→26, and 40→46.

The cost is explicit: median end-to-end runtime increased 28.36% (244.62 ms median absolute increase), although score evaluations were unchanged and average measured peak RSS decreased 20.96 MiB.

Verification on Node 22.23.2: 546/546 tests passed, ESLint passed, production build passed, benchmark repeat determinism was 8/8, and an independent read-only review found no security concerns or logic errors. Pushed verified commit: faa656e2d01bfd817ca85bb3e5f93ec0339d7af0.

Draft PR: #74

No merge was performed.

This was generated by an AI agent (vycdev2). Please verify any changes before merging or applying.

[vycdev2]

Phase 1 methodology: grouped held-out effective-optics validation

Implementation is isolated on exp/grouped-calibration-validation from frozen upstream/develop commit 36f88893674bba53c6d7edda5734ac127a13e269.

The experiment uses only existing Stack Matrix/profile data. Runtime-only source metadata keeps samples from one physical matrix together. When only one matrix is available, deterministic terminal-interaction groups based on backing, previous filament, and terminal filament provide leakage-resistant held-out folds without adding persisted fields, formats, controls, measurements, or calibration steps. Exact Stack Matrix and Palette Proof anchors remain outside this fit and are unchanged.

Validation covers source-group indivisibility, interaction-group indivisibility, deterministic input-order independence, conflicting matrix families, strict held-out acceptance, exact-anchor preservation, full repository tests, lint/build, and four existing calibrated fixtures under Node 22.23.2. The already-recorded frozen-base golden/fingerprint mismatch remains non-blocking and no goldens are being edited.

This was generated by an AI agent (vycdev2). Please verify any changes before merging or applying.

[vycdev2]

Phase 1 complete: grouped held-out effective-optics experiment

Draft experiment: #75
Commit: d25cfb62adf9b45cca283b912ef7d2a8f78a01f8

The implementation replaces row-level validation with deterministic source-group validation. Physical Stack Matrix samples and terminal optical interactions stay indivisible across train/validation folds. It uses only runtime metadata and existing evidence; persisted profiles, calibration formats, UI, and calibration requirements are unchanged.

Existing calibrated-fixture replay on Node 22.23.2

Fixture	Weighted mean ΔE	Weighted p95 ΔE	Coverage6
cats	9.891 → 9.891	15.719 → 15.719	15.93% → 15.93%
desk landscape	10.196 → 10.132	14.280 → 14.280	19.95% → 17.46%
k-logo	8.334 → 8.334	17.968 → 17.968	29.05% → 29.05%
prismatic portrait	9.223 → 8.595	21.288 → 20.715	40.74% → 40.98%

All 1,030 exact Stack Matrix/Palette Proof anchor IDs were preserved on every fixture. Two candidate runs produced identical effective-optics state, anchors, realized metrics, and optimizer results. The grouped held-out estimate was appropriately less optimistic: validation mean ΔE changed from 10.1604 to 10.6659, while fit error remained 10.1166 and confidence moved from 0.8490 to 0.8435.

Validation completed:

• focused grouped-validation regression tests passed;
• lint and production build passed;
• full suite ran with 543 passing tests and only the already-recorded Node/runtime Auto Paint golden mismatch plus its parent red; no goldens were edited;
• the canonical k-logo benchmark remained red: the frozen base had the known final-stack fingerprint mismatch, while the candidate preserved its order, realized quality, and physical stack but changed the deterministic search path with the intended validation fingerprint;
• static security scan and git diff --check passed;
• independent fresh-context review passed with no security concerns or blocking logic errors;
• pushed SHA and draft PR head SHA were verified.

The experiment is intentionally not merged. Desk landscape's 2.49-point Coverage6 reduction, despite its small mean-ΔE improvement, needs broader multi-profile evidence before promotion.

Artifacts: /opt/data/research/kromacut-overnight-2026-08-31/results/phase-1/

This was generated by an AI agent (vycdev2). Please verify any changes before merging or applying.

[vycdev2]

Phase 3/4 result: bounded incremental Exact/Deep optical-prefix scoring is published as draft PR #76 from the same frozen develop base.

Verdict: Discard for Phase 4 integration. Exhaustive calibrated equivalence passed for all 109,600 no-repeat candidates with zero palette, semantic, score, or tie-breaking mismatches. Two final Node 22.23.2 runs per mode preserved the exact 779,955-iteration result, score, order, 3 repeats, 52 layers, 4.48 mm, and final stack fingerprint.

The incremental path reduced mean optimizer time from 417,326.642 ms to 409,759.674 ms, only 1.8%. Mean peak RSS fell 7.4%, but the two incremental runs ranged from 243.1 MB to 283.2 MB, so the memory result was not stable enough to call material. Final caches were bounded at 8,192 score entries, 512 appearance predictions, and 8,192 transition thicknesses.

Known frozen-base mismatches remain visible and unchanged: the calibrated replay still produces final-stack-v1-ef8db13469d7ed46 instead of the fixture's final-stack-v1-9a83dcfa775aae0f; the full suite is 546/548 from the existing B&W repeats golden child plus parent count; and the hot-path benchmark reaches the existing separation-checksum mismatch. Lint, build, focused tests, exhaustive equivalence, repeated calibrated A/B, and independent review completed.

Draft experiment: #76

This was generated by an AI agent (vycdev2). Please verify any changes before merging or applying.

[vycdev2]

Final phase 4 recommendation

Keep commits: none. The final integration remains on frozen develop commit 36f88893674bba53c6d7edda5734ac127a13e269 and adds only the engineering decision record.

• Revise d25cfb62adf9b45cca283b912ef7d2a8f78a01f8 from PR experiment: group effective-optics validation #75. Grouped validation is leakage-resistant and anchor-preserving, but the single-matrix evidence does not resolve the 2.49-point Desk Coverage@6 loss and one lost preserved color.
• Revise faa656e2d01bfd817ca85bb3e5f93ec0339d7af0 from PR exp: bounded hybrid DE2000 reranking #74. The bounded mapper improves aggregate mean/p95/worst error and Preserve counts in fast tests, but aggregate Coverage@6 falls 4.79 points. Phase 4 also found that Exact K-logo changes to an unreviewed 109,600-iteration, 27/27-color, zero-repeat stack and fails the recorded 779,955-iteration replay. The fixture was not changed.
• Discard b43d15adb3002099ae63bba2637b08d4b1044bbe from PR perf: experiment with incremental Exact prefix scoring #76. Its 109,600-candidate equivalence is sound, but the measured end-to-end optimizer gain is only 1.8% and RSS improvement is unstable.

The actual no-experiment retained state was replayed twice and was deterministic. The full Node 22.23.2 suite reproduced only the frozen-base known golden failure, while lint and build passed. Draft integration PR: #77

No PR should be merged automatically.

This was generated by an AI agent (vycdev2). Please verify any changes before merging or applying.