feat(pipeline): strength-sweep harness + reliability findings doc

sweep_strength.py renders one open + one closed FPV frame across a
ControlNet strength matrix at fixed seed/prompt and montages them beside
the depth map — the GPU experiment to find the right strength now that
rev-3 depth maps carry a full-range signal (018909b). Findings/plan in
.dev/2026-06-15-diffusion-pipeline-reliability.md.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

.dev/2026-06-15-diffusion-pipeline-reliability.md

@@ -0,0 +1,64 @@
+# Diffusion pipeline reliability — making the depth ControlNet actually followed
+
+**Started:** 2026-06-15 · ongoing (`/loop`)
+**Problem (user):** "controlnet maps generated are barely followed; images of the
+dungeons are very hit and miss."
+
+## Root cause found (iteration 1)
+
+The FPV depth maps fed to the Z-Image Fun depth ControlNet used only a sliver of
+the tonal range. Histogram over all 68 baked seed-7 frames:
+
+- median dynamic range **193 / 255**, worst frame only **54**
+- **0/68** frames reached true black (`<32`); the deepest recesses topped out ~mid-gray
+- only **35/68** reached near-white at the near surfaces
+
+Cause in `reikhelm-web/fpv.js`: a fixed `t = dpix / maxView` with `maxView = 12`.
+The nearest floor sits ~1 cell away (never hit white) and a wall 3 cells ahead
+landed at mid-gray (never black), so small rooms collapsed into the 160–214 band.
+Depth ControlNets are trained on full-range MiDaS / depth-anything maps, so a
+washed-out map gives almost no structural signal → the model freelances.
+
+## Fix shipped — commit `018909b`
+
+Two-pass raycast in `computeFPVDepth`:
+- Pass 1 records each column's wall distance + the frame's true near/far.
+- Pass 2 maps depth through a **per-frame window**: near → white, deepest visible
+  recess → black, every frame.
+- Far plane tracks the deepest *real* surface but is clamped to `minSpan` (5 cells)
+  so a shallow dead-end nook is NOT stretched into a fake tunnel — its faced wall
+  stays an honest mid-gray slab (no black recess → no phantom-door bait).
+- `gamma` 2.0 → 1.5 (normalization now owns the range). `nearPlane`/`minSpan` are opts.
+
+**Verified offline** (headless `bakeAtlasDepths(7)`, 68 frames):
+median range 193 → **255**; near-white frames 35/68 → **68/68**; worst range 54 → 106.
+Visual before/after (`/tmp/ba.png` during the session): open frames now frame a
+black passage; closed frames a clean mid-gray wall.
+
+## Next — needs the render workstation (192.168.1.26:8188, was OFFLINE this iteration)
+
+The depth signal is now strong, so the old strength is almost certainly wrong.
+With a weak signal you crank strength to force adherence; a strong signal wants
+*less*. `bake_atlas.py` defaults `--strength 0.85`.
+
+1. Re-probe the workstation: `python3 tools/comfy-spike/comfy.py probe http://192.168.1.26:8188`
+2. **Strength sweep** (tool already written, validated):
+   ```
+   python3 tools/comfy-spike/sweep_strength.py http://192.168.1.26:8188 \
+       --seed-dir tools/out/atlas/7 --open r8_N --closed r0_N \
+       --strengths 0.55,0.7,0.85,1.0
+   ```
+   → `tools/out/compare/sweep_<run>.png`. Read adherence: does the rendered passage
+   land on the black recess? does the closed wall stay a wall (no phantom door)?
+   Pick the lowest strength that still honors geometry, update `bake_atlas.py` default.
+3. Then re-bake a full atlas at the chosen strength and spot-check a montage vs the
+   old `acc8137`/`a12bcbb` bakes.
+
+## Open levers if still hit-and-miss after strength tuning
+- `nearPlane`/`minSpan`/`gamma` are now tunable per-export — A/B if near surfaces
+  read too blown-out (the AFTER maps are ~47% near-white; may want a slightly
+  deeper nearPlane to retain near-field texture).
+- Subtle masonry-block relief on closed-wall slices so flat walls render as detailed
+  stone (offline-buildable, but verify on GPU it doesn't read as structure).
+- Strength `start_percent`/`end_percent` scheduling (currently 0→1 full) — easing
+  control off in late steps frees texture while locking composition.

reikhelm-web/fpv.js

@@ -124,7 +124,8 @@ export function vantage(env, opts = {}) {
 }
 
 // Build a first-person depth field. Returns { width, height, gray, at, dir }.
-// opts: { stage?, at?[x,y], dir?'N'|'E'|'S'|'W', width?, height?, fov?deg, maxView?, gamma? }
+// opts: { stage?, at?[x,y], dir?'N'|'E'|'S'|'W', width?, height?, fov?deg,
+//         maxView?, gamma?, nearPlane?, minSpan? }
 export function computeFPVDepth(env, opts = {}) {
   const { tiles } = getStage(env, opts.stage);
   const w = env.width, h = env.height;
@@ -132,7 +133,7 @@ export function computeFPVDepth(env, opts = {}) {
   const fov = (opts.fov ?? 80) * Math.PI / 180;            // wider horizontal FOV to fill the widescreen frame
   const planeLen = Math.tan(fov / 2);
   const maxView = opts.maxView ?? 12;     // how far the eye sees (cells) before it's pure dark
-  const gamma = opts.gamma ?? 2.0;        // >1 deepens the falloff to black (matches the proven corridor look)
+  const gamma = opts.gamma ?? 1.5;        // >1 deepens the falloff to black; normalization owns the range now
 
   const at = opts.at ?? vantage(env, opts);
   const dirName = opts.dir ?? 'N';
@@ -146,6 +147,17 @@ export function computeFPVDepth(env, opts = {}) {
   const centerX = W >> 1;
   let ahead = maxView; // straight-ahead wall distance (cells) — big = an opening leads onward
 
+  // Pass 1 — cast every column, recording the wall-hit distance (or maxView when
+  // the ray escapes off-map / through a gap). We need the frame's true near/far
+  // span BEFORE mapping to gray. A fixed 0..maxView scale wastes most of the
+  // tonal range on small rooms: the nearest floor sits ~1 cell off (never quite
+  // white) and a wall 3 cells ahead lands at mid-gray (never black), so a whole
+  // depth map collapses into the 160–214 band — almost no contrast for the depth
+  // ControlNet to honor. Normalizing each frame to its own near/far instead
+  // makes near surfaces white and the deepest recess black every time.
+  const colDist = new Float32Array(W);
+  let nearRaw = 1.0;   // the floor at the screen's bottom edge always sits ~1 cell away
+  let farRaw = 0;
   for (let x = 0; x < W; x++) {
     const camX = 2 * x / W - 1;            // −1 … 1 across the screen
     const rayX = dirX + planeX * camX;
@@ -168,8 +180,27 @@ export function computeFPVDepth(env, opts = {}) {
     }
     const perp = side === 0 ? sideX - deltaX : sideY - deltaY;
     const dist = hit ? clamp(perp, 0.02, maxView) : maxView;
+    colDist[x] = dist;
+    if (dist < nearRaw) nearRaw = dist;
+    if (dist > farRaw) farRaw = dist;
     if (x === centerX) ahead = dist;
+  }
 
+  // Per-frame normalization window. The far plane tracks the deepest surface
+  // actually visible (so a real passage reads black), but is clamped to a floor
+  // (minSpan) so a shallow dead-end nook isn't stretched into a dramatic fake
+  // tunnel — its faced wall stays an honest mid-gray slab, not a black recess
+  // the model would paint a phantom door into. `gamma` then shapes the falloff
+  // within that window.
+  const nearPlane = opts.nearPlane ?? nearRaw;
+  const minSpan = opts.minSpan ?? 5;
+  const farPlane = clamp(farRaw, nearPlane + minSpan, maxView);
+  const span = Math.max(farPlane - nearPlane, 1e-3);
+
+  // Pass 2 — paint each column: a wall slice at its distance, floor/ceiling
+  // ramping toward the camera, every depth mapped through the per-frame window.
+  for (let x = 0; x < W; x++) {
+    const dist = colDist[x];
     // Project the 1-cell-tall wall: lineH = H/dist (fills the screen at dist 1).
     const lineH = H / dist;
     const ds = clamp(Math.floor(half - lineH / 2), 0, H);
@@ -185,7 +216,7 @@ export function computeFPVDepth(env, opts = {}) {
         const p = y < half ? (half - y) : (y - half + 1);
         dpix = Math.min((0.5 * H) / p, maxView);
       }
-      const t = clamp(dpix / maxView, 0, 1);
+      const t = clamp((dpix - nearPlane) / span, 0, 1);
       gray[y * W + x] = Math.round(255 * Math.pow(1 - t, gamma));
     }
   }

tools/comfy-spike/sweep_strength.py

@@ -0,0 +1,117 @@
+#!/usr/bin/env python3
+"""Sweep ControlNet strength for the Z-Image FPV depth pipeline and montage it.
+
+With the rev-3 depth maps (full per-frame normalization, commit 018909b) the
+control signal is now high-contrast, so the right strength almost certainly
+shifted. This renders ONE open frame + ONE closed frame across a strength matrix
+at a fixed seed/prompt/sampler, then stacks them next to their depth map so you
+can read adherence (does the passage land where the black recess is? does a
+closed wall stay a wall?) at a glance.
+
+  python3 tools/comfy-spike/sweep_strength.py http://192.168.1.26:8188 \
+      --seed-dir tools/out/atlas/7 --open r8_N --closed r0_N \
+      --strengths 0.55,0.7,0.85,1.0
+
+Output: tools/out/compare/sweep_<run>.png  (rows = frames, cols = depth + each strength)
+Re-run after re-baking depth maps to compare pipeline revisions head to head.
+"""
+import argparse
+import glob
+import os
+import subprocess
+import sys
+
+REPO = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+COMFY = os.path.join(REPO, "tools", "comfy-spike", "comfy.py")
+VENV_PY = os.path.join(REPO, "tools", "pixelart", ".venv", "bin", "python")
+
+# Mirror bake_atlas.py's proven prompt skeleton so the sweep reflects production.
+STYLE = ("dark fantasy, ancient torchlit stone, warm orange torchlight, deep black shadows, "
+         "wet stone, volumetric haze, architectural photography of an empty ruin, "
+         "empty, deserted, no people, uninhabited, atmospheric, highly detailed, ")
+OPEN_BODY = "grand pillared hall, rows of carved stone columns, a dark arched passage leads onward into shadow ahead"
+WALL_BODY = ("dungeon gatehouse of carved stone, the way ahead ends at a blank unbroken wall of stone blocks, "
+             "sealed solid masonry with no door and no opening, a dead end")
+NEGATIVE = ("person, people, human, figure, character, hands, fingers, hand, arm, arms, "
+            "holding weapon, sword, feet, legs, body, silhouette, UI, HUD, text, watermark, modern")
+
+
+def render(url, depth, prompt, strength, seed, prefix, wait):
+    ok = subprocess.run(["python3", COMFY, "zrender", url, "--depth", depth,
+                         "--width", "1280", "--height", "720", "--strength", str(strength),
+                         "--seed", str(seed), "--prompt", prompt, "--negative", NEGATIVE,
+                         "--prefix", prefix, "--wait", str(wait)],
+                        capture_output=True, text=True)
+    if ok.returncode != 0:
+        sys.stderr.write(ok.stdout + ok.stderr + "\n")
+        return None
+    hits = glob.glob(os.path.join(os.path.dirname(depth), f"out_{prefix}_*.png"))
+    return hits[0] if hits else None
+
+
+def montage(rows, strengths, out):
+    from PIL import Image, ImageDraw
+    cw, ch, pad = 360, 203, 6
+    ncol = 1 + len(strengths)
+    sheet = Image.new("RGB", (cw * ncol + pad * (ncol + 1), (ch + 20) * len(rows) + pad), (16, 16, 16))
+    dr = ImageDraw.Draw(sheet)
+    y = pad
+    for label, depth, imgs in rows:
+        cells = [("depth", depth)] + [(f"str {s}", imgs.get(s)) for s in strengths]
+        x = pad
+        for cap, path in cells:
+            if path and os.path.exists(path):
+                sheet.paste(Image.open(path).convert("RGB").resize((cw, ch)), (x, y + 18))
+            dr.text((x, y + 4), f"{label} · {cap}", fill=(0, 230, 120))
+            x += cw + pad
+        y += ch + 20
+    sheet.save(out)
+    return out
+
+
+def main():
+    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("url")
+    ap.add_argument("--seed-dir", default=os.path.join(REPO, "tools", "out", "atlas", "7"))
+    ap.add_argument("--open", default="r8_N", help="frame id for the open-passage test")
+    ap.add_argument("--closed", default="r0_N", help="frame id for the closed-wall test")
+    ap.add_argument("--strengths", default="0.55,0.7,0.85,1.0")
+    ap.add_argument("--seed", type=int, default=7, help="fixed diffusion seed (style lock)")
+    ap.add_argument("--wait", type=int, default=300)
+    a = ap.parse_args()
+
+    work = os.path.join(a.seed_dir, "_work")
+    strengths = [float(s) for s in a.strengths.split(",") if s.strip()]
+    run = os.getpid()
+    cases = [(a.open, OPEN_BODY), (a.closed, WALL_BODY)]
+
+    rows = []
+    for frame, body in cases:
+        depth = os.path.join(work, f"{frame}_depth.png")
+        if not os.path.exists(depth):
+            sys.exit(f"!! missing depth map {depth} — bake the atlas first")
+        prompt = STYLE + body
+        imgs = {}
+        for s in strengths:
+            prefix = f"sweep_{frame}_{int(s*100)}_{run}"
+            print(f"[{frame} @ strength {s}] rendering ...", flush=True)
+            out = render(a.url, depth, prompt, s, a.seed, prefix, a.wait)
+            if out:
+                imgs[s] = out
+        rows.append((frame, depth, imgs))
+
+    out_dir = os.path.join(REPO, "tools", "out", "compare")
+    os.makedirs(out_dir, exist_ok=True)
+    out = montage(rows, strengths, os.path.join(out_dir, f"sweep_{run}.png"))
+    # tidy the per-strength intermediates; the montage is the artifact
+    for _, _, imgs in rows:
+        for p in imgs.values():
+            try:
+                os.remove(p)
+            except OSError:
+                pass
+    print(f"\nmontage → {os.path.relpath(out, REPO)}")
+
+
+if __name__ == "__main__":
+    main()