Merge branch 'main' into worktree-agent-aecd35c3421bad4ae

# Conflicts:
#	crates/ui-egui/src/render.rs

docs/control-protocol.md

@@ -21,7 +21,7 @@ mode ([mcp.md](mcp.md)) is a thin layer over this channel. Implementation:
 | `engine.commands` | — | Engine + UI commands: id, label, menu, shortcut, params doc, enabled |
 | `ui.menu.list` | — | Menu entries (flat: id, label, menu path, shortcut, enabled) |
 | `ui.menu.tree` | — | The menu bar as shown (File … Help): items `{id, params?, label, shortcut?, enabled, checked?}`, separators, submenus — the model behind the native macOS menu bar and the in-window menus |
-| `ui.inspect` | — | UI state, window, canvas/image rects, active photo, selection, perf, status |
+| `ui.inspect` | — | UI state, window, canvas/image rects, active photo, selection, perf, status, memory (bytes per cache, see `library.memory`; plus stage caches and textures) |
 | `ui.widgets` | `{filter?}` | On-screen widgets `{id, rect: [x, y, w, h]}` (screen points) |
 | `ui.clickWidget` / `ui.dragWidget` / `ui.hoverWidget` | `{id, count?, fx?, fy?}` / `{id, toX?, toY?, dx?, dy?, steps?}` / `{id, fx?, fy?}` | Real egui input on a widget (hover: the pointer rests on it, e.g. for preset/profile previews) |
 | `ui.move` / `ui.click` / `ui.drag` | `{x, y, count?, button?}` / `{x, y, toX, toY, steps?}` | Raw pointer input, screen points |

docs/gpu-pipeline.md

@@ -88,6 +88,33 @@ the device on their first GPU render. `lightcraft_gpu::ready()` asks without blo
   one is rendered (decoded source kept, view render cached): stepping through photos shows the
   developed image in ~50 ms.
 
+## Memory (M5.6)
+- `library.memory` reports what the engine's caches hold (decoded thumbnail / preview / full-size
+  sources, rendered previews) and the GPU renderer's device buffers (allocated, of which pooled
+  and retired); `ui.inspect` → `memory` adds the loupe's stage caches (CPU images, GPU buffers)
+  and the textures.
+- Heap profile: build `lightcraft-cli` with `--features dhat-heap`; `library.memory` then also
+  reports live/peak heap bytes and the run writes `dhat-heap.json` (`LIGHTCRAFT_DHAT_FILE`), whose
+  allocation sites at the peak (`t-gmax`) show who holds the memory.
+- Measuring the scenario (import 14 raws from `corpus/raw`, open the loupe, step 12 times):
+  `/usr/bin/time -l lightcraft-cli snapshot <files> --script steps.jsonl -o out.png` → "maximum
+  resident set size" and "peak memory footprint". Run it several times: the high-water mark is
+  noisy (allocator caching, scheduling). On Apple silicon GPU buffers count in the footprint.
+- Imports read raw headers only (`lightcraft_raw::probe_info`): no pixel data is decompressed.
+- One budget (`memory::budget`, default min(25 % of RAM, 1.5 GiB); `LIGHTCRAFT_MEMORY_MB` or
+  `app.memoryBudget {mb}`): half for the engine caches (decoded thumbnail / preview / full
+  sources and rendered previews, evicted least recently used *across* them; the photo on screen
+  stays), a quarter for decodes in flight (`memory::work_gate`: grid thumbnails, neighbour
+  prefetch and import probes wait for room, loupe and export loads never wait), an eighth for the
+  GPU buffer pool (reuse by best fit within 25 %; freed after 3 s idle).
+- Decodes free the file's bytes and the raw samples as soon as they are consumed and colour /
+  crop / orient in place. macOS keeps freed large blocks resident ("reusable") until the system
+  is short of memory, so the resident size climbed with every photo decoded; the apps install
+  `malloc_zone_pressure_relief` as `memory::set_release_hook`, called after each decode, import
+  and idle trim.
+- Result (M4 Pro, 14 raws, loupe, 12 steps): peak RSS 1.9–2.3 GB → 0.83–0.99 GB, peak footprint
+  2.5–2.6 GB → 0.91–0.96 GB, heap peak 930 → ~600 MB; stepping median ~13 ms (unchanged).
+
 ## Open items
 - Keep the loupe texture on the GPU (render into an `egui-wgpu` texture on eframe's device instead of
   reading back); share the device with eframe.

docs/parity.md

@@ -32,7 +32,7 @@ and prints the summary; `cargo xtask parity --write` refreshes the summary table
 | I. Remove / healing (REM) | 3 | 3 | 4 | 2 | 2/4 (50%) | 1/3 (33%) |
 | J. Red eye (EYE) | 0 | 0 | 2 | 0 | — | 0/1 (0%) |
 | K. Masking (MASK) | 6 | 10 | 7 | 0 | 4/8 (50%) | 2/5 (40%) |
-| L. Presets (PRE) | 1 | 4 | 2 | 1 | 0/2 (0%) | 1/2 (50%) |
+| L. Presets (PRE) | 3 | 2 | 2 | 1 | 2/2 (100%) | 1/2 (50%) |
 | M. Versions & history (VER) | 3 | 1 | 1 | 0 | 1/1 (100%) | 2/3 (67%) |
 | N. Copy / paste / sync (SYNC) | 4 | 0 | 1 | 0 | 3/3 (100%) | 1/1 (100%) |
 | O. Merge (MERGE) | 3 | 0 | 1 | 0 | — | — |
@@ -44,11 +44,11 @@ and prints the summary; `cargo xtask parity --write` refreshes the summary table
 | U. Map & location (MAP) | 0 | 1 | 1 | 0 | — | 0/1 (0%) |
 | V. Preferences (PREF) | 0 | 3 | 5 | 3 | 0/1 (0%) | 0/4 (0%) |
 | W. Cloud & AI infrastructure (CLOUD / AI) | 0 | 1 | 1 | 2 | — | — |
-| X. Cross-cutting behaviours (BEHAV) | 10 | 2 | 5 | 1 | 7/8 (88%) | 3/5 (60%) |
+| X. Cross-cutting behaviours (BEHAV) | 10 | 3 | 4 | 1 | 7/8 (88%) | 3/5 (60%) |
 | Y. Menus | 46 | 18 | 21 | 8 | 37/47 (79%) | 7/23 (30%) |
 | Z. Keyboard shortcuts (desktop) | 46 | 16 | 18 | 1 | 39/52 (75%) | 7/23 (30%) |
 | Lightroom Classic extras | 4 | 19 | 56 | 9 | — | 3/21 (14%) |
-| **Total** | 211 | 102 | 187 | 37 | 153/198 (77%) | 49/144 (34%) |
+| **Total** | 213 | 101 | 186 | 37 | 155/198 (78%) | 49/144 (34%) |
 <!-- /parity:summary -->
 
 ## Top gaps