dsh-mobilecode 0.11.9 → 0.12.0

package/README.md

@@ -374,6 +374,51 @@ say *why* instead of "something failed".
 - Tolerant internal callers (boot polling, IME checks) opt back into
   best-effort with an explicit `.catch(() => "")`.
 
+## Design workbench (0.12 — native Android UI design & verification)
+
+Reusable capabilities for the loop *explore visual directions → approve a
+design → implement native Compose → render → compare → test on Android →
+refine*. App-specific decisions (learning flow, approved directions) live in
+the app project, never hardcoded here.
+
+- **Reference workspace (`preview_gallery`, `config_matrix`, `design_bridge`
+  tools + `/api/dsh-mobilecode/refs|preview|matrix|openpencil/*` routes)** —
+  import PNG/JPEG/WebP design references with metadata (project, screen,
+  state, provenance, approval status); associate device captures (reuses the
+  existing screencap path; originals stored verbatim, alignment transforms
+  kept separate); persisted under `~/.dsh/mobilecode/reference/` across
+  reloads. Header-only decompression fences (no pixel decode server-side, no
+  new dependency).
+- **Visual diff (`POST /refs/diff`)** — two modes, never conflated:
+  `regression` (any changed pixel fails against a recorded native baseline)
+  and `design-reference` (structure comparison, always `needs_review` — the
+  tool ran; that is not a visual pass). Client canvas downsamples; the server
+  reports concrete changed-region clusters; envelopes persist as evidence
+  files. No quality scores anywhere.
+- **Compose preview gallery** — discovers `@PreviewTest` composables of a
+  Gradle project and renders them through **official Compose Preview
+  Screenshot Testing** (`com.android.compose.screenshot`, pinned
+  0.0.1-alpha16, host layoutlib — works on AGP 8.5+ without toolchain
+  migration; compose-ai-tools needs AGP 8.13 and is documented as a blocked
+  alternative). Failed/stale renders are never labeled current; host-rendered
+  ≠ device-verified (see `docs/design/render-adapter-decision.md`).
+- **Configuration matrix (`config_matrix` tool)** — bounded (1..8) risk-based
+  matrices over real device settings (wm size/density, font scale): every
+  case reads back its ACTUAL configuration, captures evidence, and the device
+  is restored to its found state (including pre-existing overrides) on
+  success, failure and cancellation. Physical devices are refused without
+  explicit approval.
+- **OpenPencil bridge (`design_bridge`, optional)** — file-mode CLI adapter:
+  inspect `.fig` docs, export a frame to PNG into the reference workspace,
+  read design variables. Path-confined (realpath + junction-aware); when the
+  CLI is absent everything degrades to honest `not_run` — the workspace stays
+  fully usable with manual imports. OpenPencil exports are web-oriented
+  (PNG/JSX/HTML); no native Compose export is claimed.
+- **Panel** — the Devices drawer gains two cards: **Reference compare**
+  (import / capture / side-by-side / opacity overlay / swipe slider / diff)
+  and **Preview gallery** (discovery, thumbnails, stale badges, per-entry
+  render).
+
 ## How it works
 
 - `lib/device-build.js` — port of `mobilecode/packages/core/src/device-build.ts`:
@@ -395,6 +440,13 @@ say *why* instead of "something failed".
   Pure + injectable clock/RNG, so `test/mesh-hub.mjs` covers it offline.
 - `sdk/mesh-client.mjs` — dependency-free `fetch` client (join/link/send/
   poll/inbox/leave) for game code running inside the emulators.
+- Design workbench modules: `lib/reference-workspace.js` (reference/capture
+  store + header-only image fences), `lib/visual-compare.js` (pure RGBA diff
+  core — the server never pixel-decodes), `lib/preview-gallery.js` (@PreviewTest
+  discovery + Gradle render driver with timeout tree-kill),
+  `lib/config-matrix.js` (bounded matrix runner, snapshot→apply→confirm→
+  capture→restore on every path), `lib/openpencil.js` (optional CLI bridge,
+  realpath/junction-confined).
 - `lib/setup.js` — settings store (~/.dsh/mobilecode/settings.json), the plugin
   doctor (health checks + auto-fix), and the detached PaddleOCR installer
   (writes an install script to disk and spawns it via cmd.exe, so the install

package/lib/client.js

@@ -354,6 +354,253 @@ window.__ModuleLoader__.load({
 		const readDir = () => { try { return localStorage.getItem("dsh-mobilecode-directory") ?? ""; } catch { return ""; } };
 		const writeDir = (value) => { try { localStorage.setItem("dsh-mobilecode-directory", value); } catch { /* private mode */ } };
 
+		function RefCompareSection({ directory }) {
+			const [project, setProject] = useState(() => {
+				const base = String(directory || "").replace(/[\\/]+$/, "").split(/[\\/]/).pop();
+				return base || "trachtenberg";
+			});
+			const [screen, setScreen] = useState("practice");
+			const [stateId, setStateId] = useState("default");
+			const [refs, setRefs] = useState([]);
+			const [activeId, setActiveId] = useState(null);
+			const [opacity, setOpacity] = useState(55);
+			const [swipe, setSwipe] = useState(50);
+			const [error, setError] = useState("");
+			const [busy, setBusy] = useState("");
+			const [pair, setPair] = useState(null);
+			const [pairVersion, setPairVersion] = useState(0);
+
+			const loadRefs = async (proj) => {
+				try {
+					const data = await apiGet("/refs?project=" + encodeURIComponent(proj ?? project));
+					setRefs(data.records ?? []);
+					setActiveId(data.active?.id ?? null);
+				} catch (err) { setError(err instanceof Error ? err.message : String(err)); }
+			};
+			const loadPair = async () => {
+				try {
+					const data = await apiGet("/refs/compare?project=" + encodeURIComponent(project) +
+						"&screen=" + encodeURIComponent(screen) + "&stateId=" + encodeURIComponent(stateId));
+					setPair(data);
+				} catch (err) { setError(err instanceof Error ? err.message : String(err)); }
+			};
+			useEffect(() => { loadRefs(project); }, [project]);
+			useEffect(() => { loadPair(); /* eslint-disable-line react-hooks/exhaustive-deps */ }, [project, screen, stateId, activeId, pairVersion]);
+
+			const run = async (name, fn) => {
+				setBusy(name); setError("");
+				try { await fn(); } catch (err) { setError(err instanceof Error ? err.message : String(err)); }
+				finally { setBusy(""); }
+			};
+			const importFile = async (file) => {
+				if (!file) return;
+				const data = await new Promise((resolve, reject) => {
+					const reader = new FileReader();
+					reader.onload = () => resolve(reader.result);
+					reader.onerror = () => reject(reader.error);
+					reader.readAsDataURL(file);
+				});
+				await run("import", async () => {
+					await streamPost("/refs/import", { project, screen, stateId, filename: file.name, data, provenance: "manual-import", intendedUse: "compare" });
+					await loadRefs(project); setPairVersion((v) => v + 1);
+				});
+			};
+			const capture = async () => {
+				await run("capture", async () => {
+					await streamPost("/refs/capture", { project, screen, stateId });
+					await loadRefs(project); setPairVersion((v) => v + 1);
+				});
+			};
+			const setActive = async (id) => {
+				await run("active", async () => {
+					await streamPost("/refs/active", { id });
+					setActiveId(id); setPairVersion((v) => v + 1);
+				});
+			};
+			const remove = async (id) => {
+				await run("remove", async () => {
+					await streamPost("/refs/remove", { id });
+					await loadRefs(project); setPairVersion((v) => v + 1);
+				});
+			};
+			const [diff, setDiff] = useState(null);
+			const decodeFrame = async (src, maxDim = 480) => {
+				const img = new Image();
+				img.crossOrigin = "anonymous";
+				await new Promise((resolve, reject) => { img.onload = resolve; img.onerror = () => reject(new Error("image decode failed: " + src)); img.src = src; });
+				if (img.naturalWidth * img.naturalHeight > 24_000_000) throw new Error("image exceeds 24MP decode guard");
+				const scale = Math.min(1, maxDim / Math.max(img.naturalWidth, img.naturalHeight));
+				const w = Math.max(1, Math.round(img.naturalWidth * scale));
+				const hgt = Math.max(1, Math.round(img.naturalHeight * scale));
+				const canvas = document.createElement("canvas");
+				canvas.width = w; canvas.height = hgt;
+				const ctx2d = canvas.getContext("2d", { willReadFrequently: true });
+				ctx2d.drawImage(img, 0, 0, w, hgt);
+				return { width: w, height: hgt, naturalWidth: img.naturalWidth, naturalHeight: img.naturalHeight, rgba: ctx2d.getImageData(0, 0, w, hgt).data };
+			};
+			const runDiff = async (fullRes) => {
+				if (!refSrc || !capSrc) { setError("need both a reference and a capture to diff"); return; }
+				await run("diff", async () => {
+					// Regression needs NATIVE frames: decode both at full resolution and
+					// require equal original dimensions — the server re-checks them against
+					// the stored records before any "passed" is possible. Different aspects
+					// stay triage-only (downsampled, needs_review) — never a silent stretch.
+					const sameSize = fullRes === true;
+					const [a, b] = sameSize
+						? await Promise.all([decodeFrame(refSrc, Infinity), decodeFrame(capSrc, Infinity)])
+						: await Promise.all([decodeFrame(refSrc, 480), decodeFrame(capSrc, 480)]);
+					if (a.width !== b.width || a.height !== b.height) throw new Error("frame sizes differ (" + a.width + "x" + a.height + " vs " + b.width + "x" + b.height + ") — aspects differ; only downsampled triage applies, record a transform for aligned comparison");
+					const toB64 = (f) => { let s = ""; const bytes = f.rgba; for (let i = 0; i < bytes.length; i++) s += String.fromCharCode(bytes[i]); return btoa(s); };
+					const r = await streamPost("/refs/diff", {
+						a: { width: a.width, height: a.height, rgba: toB64(a) },
+						b: { width: b.width, height: b.height, rgba: toB64(b) },
+						mode: sameSize ? "regression" : "design-reference", project, screen, stateId,
+						referenceId: pair?.reference?.id, captureId: pair?.capture?.id,
+					});
+					setDiff(r);
+				});
+			};
+
+			const imgUrl = (record) => record ? API_BASE + "/refs/image?id=" + encodeURIComponent(record.id) : null;
+			const refSrc = imgUrl(pair?.reference ?? refs.find((r) => r.id === activeId));
+			const capSrc = imgUrl(pair?.capture);
+			// native regression only makes sense between IDENTICAL source sizes
+			const sizeMatch = !!pair?.reference && !!pair?.capture &&
+				pair.reference.width === pair.capture.width && pair.reference.height === pair.capture.height;
+			const box = { position: "relative", width: "100%", aspectRatio: "9/19.5", background: "#0b0f14", borderRadius: 8, overflow: "hidden" };
+			const fit = { position: "absolute", inset: 0, width: "100%", height: "100%", objectFit: "contain" };
+
+			return h("div", { className: "mc-card", style: { borderTop: "1px solid var(--mc-border, #2a3340)" } },
+				h("div", { className: "mc-card-head" }, h("span", null, "Reference compare"),
+					h("span", { className: "sp" }), h("span", { style: { opacity: 0.6, fontSize: 11 } }, busy || "slice")),
+				h("div", { className: "mc-row" },
+					h("input", { className: "mc-input", value: project, placeholder: "project", onChange: (e) => setProject(e.target.value), style: { flex: 1 } }),
+				),
+				h("div", { className: "mc-row" },
+					h("input", { className: "mc-input", value: screen, placeholder: "screen", onChange: (e) => setScreen(e.target.value), style: { flex: 1 } }),
+					h("input", { className: "mc-input", value: stateId, placeholder: "state", onChange: (e) => setStateId(e.target.value), style: { flex: 1 } }),
+				),
+				h("div", { className: "mc-row" },
+					h("label", { className: "mc-btn" },
+						busy !== "" ? "Importing…" : "Import reference",
+						h("input", { type: "file", accept: "image/png,image/jpeg,image/webp", style: { display: "none" }, onChange: (e) => importFile(e.target.files?.[0]) }),
+					),
+					h("button", { className: "mc-btn primary", disabled: busy !== "", onClick: capture }, "Capture screen"),
+					h("button", { className: "mc-btn", disabled: busy !== "" || !refSrc || !capSrc, title: "reduced-resolution structure triage — needs_review only, can never pass regression", onClick: () => runDiff(false) }, "Diff (triage)"),
+					h("button", { className: "mc-btn", disabled: busy !== "" || !refSrc || !capSrc || !sizeMatch, title: sizeMatch ? "full-resolution native comparison — regression verdict" : "source sizes differ — a native regression comparison is invalid between different configurations", onClick: () => runDiff(true) }, "Regression (full-res)"),
+				),
+				error !== "" && h("div", { className: "mc-error" }, error),
+				h("div", { style: { position: "relative" }, onMouseMove: undefined },
+					(refSrc || capSrc)
+						? h("div", { style: box },
+							refSrc && h("img", { src: refSrc, style: fit, alt: "reference" }),
+							capSrc && h("img", { src: capSrc, style: { ...fit, clipPath: "inset(0 " + (100 - swipe) + "% 0 0)", opacity: opacity / 100 } },
+								/* capture overlaid on reference */),
+							h("div", { style: { position: "absolute", left: swipe + "%", top: 0, bottom: 0, width: 1, background: "#fff" } }),
+						)
+						: h("div", { className: "mc-empty" }, "Import a reference and capture the screen to compare."),
+					(refSrc || capSrc) && h("div", { className: "mc-row", style: { marginTop: 6, gap: 8 } },
+						h("label", { style: { display: "flex", alignItems: "center", gap: 4, fontSize: 11 } },
+							"opacity", h("input", { type: "range", min: 0, max: 100, value: opacity, onChange: (e) => setOpacity(Number(e.target.value)) })),
+						h("label", { style: { display: "flex", alignItems: "center", gap: 4, fontSize: 11 } },
+							"swipe", h("input", { type: "range", min: 0, max: 100, value: swipe, onChange: (e) => setSwipe(Number(e.target.value)) })),
+					),
+				),
+				h("div", { className: "mc-status" }, h("span", { style: { fontSize: 11, opacity: 0.7 } },
+					"reference " + (refSrc ? "✓" : "—") + " · capture " + (capSrc ? "✓" : "—") +
+					(pair?.reference && pair?.capture ? " · sources " + pair.reference.width + "x" + pair.reference.height + " vs " + pair.capture.width + "x" + pair.capture.height + (sizeMatch ? " (full-res regression available)" : " (triage only)") : "") +
+					" · persisted in ~/.dsh/mobilecode/reference (survives reloads)")),
+				diff && h("div", { style: { border: "1px solid var(--mc-border, #2a3340)", borderRadius: 8, padding: 8, fontSize: 11 } },
+					h("div", null, h("b", null, "diff · " + (diff.mode ?? "—") + " · " + (diff.comparisonSpace ?? "—") + " · " + diff.checkStatus),
+						diff.diff ? h("span", { style: { opacity: 0.7 } }, "  " + diff.diff.changePct + "% changed (" + diff.diff.changedPixels + "/" + diff.diff.totalPixels + " px @ threshold L1>" + diff.diff.threshold + "; " + diff.diff.clusterFilter.droppedPixels + " px in sub-minimum clusters counted in verdict)")
+							: h("span", { style: { opacity: 0.7 } }, "  " + (diff.reason ?? ""))),
+					(diff.diff?.clusters ?? []).slice(0, 4).map((c, i) => h("div", { key: c.x + "," + c.y, style: { opacity: 0.85 } },
+						"region cmp " + c.x + "," + c.y + " " + c.width + "×" + c.height + " (" + c.pixels + " px)" +
+						(diff.regionsA?.[i] ? " · ref-original " + diff.regionsA[i].x + "," + diff.regionsA[i].y + " " + diff.regionsA[i].width + "×" + diff.regionsA[i].height : "") +
+						(diff.regionsB?.[i] ? " · cap-original " + diff.regionsB[i].x + "," + diff.regionsB[i].y + " " + diff.regionsB[i].width + "×" + diff.regionsB[i].height : ""))),
+					(diff.env?.masks ?? []).length > 0 && h("div", { style: { opacity: 0.85 } }, "masks: " + diff.env.masks.map((m) => m.reason).join(" | ")),
+					h("div", { style: { opacity: 0.6 } }, diff.note ?? ""),
+					(diff.limitations ?? []).map((l) => h("div", { key: l, style: { opacity: 0.6 } }, "· " + l)),
+					diff.evidenceFile && h("div", { style: { opacity: 0.6 } }, "evidence: " + diff.evidenceFile)),
+				refs.length > 0 && h("div", { style: { marginTop: 6, display: "flex", flexWrap: "wrap", gap: 6 } },
+					refs.map((record) => h("span", {
+						key: record.id,
+						title: (record.provenance ?? "") + " · " + record.importedAt,
+						onClick: () => setActive(record.id),
+						style: {
+							border: "1px solid " + (record.id === activeId ? "#5aa2ff" : "#2a3340"),
+							borderRadius: 6, padding: "2px 8px", fontSize: 11, cursor: "pointer",
+							background: record.id === activeId ? "rgba(90,162,255,0.15)" : "transparent",
+						},
+					},
+					(record.kind === "capture" ? "📷 " : "🖼 ") + record.screen + "/" + record.stateId,
+					record.id === activeId && h("button", {
+						style: { border: 0, background: "none", cursor: "pointer", marginLeft: 6, color: "#ff7a7a" },
+						onClick: (e) => { e.stopPropagation(); remove(record.id); },
+					}, "✕"))),
+				),
+			);
+		}
+
+		function PreviewGallerySection({ directory }) {
+			const [entries, setEntries] = useState([]);
+			const [warnings, setWarnings] = useState([]);
+			const [gradle, setGradle] = useState(false);
+			const [busy, setBusy] = useState("");
+			const [error, setError] = useState("");
+			const [note, setNote] = useState("");
+
+			const load = async (dir) => {
+				const target = dir ?? directory;
+				if (!target) { setEntries([]); setGradle(false); return; }
+				try {
+					const data = await apiGet("/preview/list?directory=" + encodeURIComponent(target));
+					setGradle(!!data.gradle);
+					setEntries(data.entries ?? []);
+					setWarnings(data.warnings ?? []);
+				} catch (err) { setError(err instanceof Error ? err.message : String(err)); }
+			};
+			useEffect(() => { load(); }, [directory]);
+
+			const renderOne = async (entry) => {
+				setBusy(entry.fqClass + "." + entry.method); setError(""); setNote("");
+				try {
+					const r = await streamPost("/preview/render", { directory, class: entry.fqClass, method: entry.method });
+					if (r.status === "passed") setNote("rendered " + entry.method + (r.provenance?.stale ? " (still stale?)" : ""));
+					else setError(entry.method + ": " + (r.failureKind ?? r.status) + " — " + (r.tail ?? []).slice(-2).join(" | "));
+					await load();
+				} catch (err) { setError(err instanceof Error ? err.message : String(err)); }
+				finally { setBusy(""); }
+			};
+
+			return h("div", { className: "mc-card" },
+				h("div", { className: "mc-card-head" },
+					h("span", null, "Preview gallery"),
+					h("span", { className: "sp" }),
+					h("button", { className: "mc-btn", onClick: () => load() }, "Refresh"),
+				),
+				!gradle && h("div", { className: "mc-empty" }, "Pick a Gradle project directory to discover @PreviewTest composables."),
+				gradle && entries.length === 0 && h("div", { className: "mc-empty" }, "No @PreviewTest previews yet — apply the screenshot adapter (docs/design/render-adapter-decision.md)."),
+				error !== "" && h("div", { className: "mc-error" }, error),
+				note !== "" && h("div", { className: "mc-status" }, h("span", { style: { fontSize: 11 } }, note)),
+				warnings.map((w) => h("div", { className: "mc-error", key: w }, "discovery: " + w)),
+				entries.length > 0 && h("div", { style: { display: "grid", gridTemplateColumns: "repeat(auto-fill, minmax(120px, 1fr))", gap: 8 } },
+					entries.map((entry) => h("div", { key: entry.fqClass + "." + entry.method, style: { border: "1px solid var(--mc-border, #2a3340)", borderRadius: 8, padding: 6, fontSize: 11 } },
+						entry.rendered
+							? h("img", { src: API_BASE + "/preview/image?directory=" + encodeURIComponent(directory) + "&class=" + encodeURIComponent(entry.fqClass) + "&method=" + encodeURIComponent(entry.method), alt: entry.previewName, style: { width: "100%", borderRadius: 4, display: "block" } })
+							: h("div", { style: { height: 150, display: "flex", alignItems: "center", justifyContent: "center", opacity: 0.5 } }, "not rendered"),
+						h("div", { style: { marginTop: 4, fontWeight: 600 } }, entry.previewName),
+						entry.rendered && entry.freshness !== "fresh_tracked_inputs" && h("span", { style: { color: "#ffb020" } },
+							entry.freshness === "unknown" ? "freshness unknown (no manifest)" : entry.freshness === "last_run_failed" ? "last render failed" : "stale — tracked inputs changed"),
+						h("button", { className: "mc-btn", disabled: busy !== "", style: { width: "100%", marginTop: 4 }, onClick: () => renderOne(entry) },
+							busy === entry.fqClass + "." + entry.method ? "rendering…" : "Render"),
+					)),
+				),
+				entries.length > 0 && h("div", { className: "mc-status" },
+					h("span", { style: { fontSize: 11, opacity: 0.7 } }, "host-rendered (layoutlib) — NOT device-verified · failed/stale renders never labeled current")),
+			);
+		}
+
 		function MobileCodePanel({ controller }) {
 			const [directory, setDirectory] = useState(readDir);
 			const [info, setInfo] = useState(null);
@@ -533,6 +780,8 @@ window.__ModuleLoader__.load({
 						),
 					info?.servers?.length === 0 && info?.builds?.length === 0 && (info?.deviceCount ?? 0) === 0 &&
 						h("div", { className: "mc-empty" }, "Nothing running yet — pick a project directory and press Run app, or boot an AVD in Device 1 above."),
+					h(RefCompareSection, { directory: info?.directory ?? "" }),
+				h(PreviewGallerySection, { directory: info?.directory ?? "" }),
 				),
 				h("div", { className: "mc-footer" },
 					h("span", null, "dsh-mobilecode · polls every 2s"),

package/lib/config-matrix.js

@@ -0,0 +1,202 @@
+/**
+ * dsh-mobilecode — bounded configuration matrix runner (T7m/Feature F).
+ *
+ * Drives REAL Android configuration (wm size/density overrides + font scale)
+ * through the existing adb plumbing, captures evidence through the
+ * reference-workspace capture store, and RESTORES the device to the state it
+ * was FOUND in — including pre-existing overrides — on success, failure and
+ * cancellation paths.
+ *
+ * Honesty rules:
+ *  - requested config ≠ actual config: every case queries the device
+ *    (wm size / wm density / settings get font_scale) and reports what it
+ *    ACTUALLY ended up with;
+ *  - scaling the browser pane is NOT an Android configuration change and is
+ *    never represented here;
+ *  - physical devices are refused without an explicit approval flag;
+ *  - font behavior is read back from the platform — no linear px↔sp formula.
+ */
+
+import { tmpdir } from "node:os"
+import * as DeviceBuild from "./device-build.js"
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms))
+
+/** emulator-* serials are safe to reconfigure; physical hardware is not, without approval. */
+export function isEmulatorSerial(serial) {
+  return typeof serial === "string" && serial.startsWith("emulator-")
+}
+
+/** Parse `wm size`/`wm density` output into effective value + whether an override was in place.
+ * Keys are prefixed per-kind (sizeOverridden/densityOverridden) so spreading the two parses
+ * cannot clobber each other's override flag (audit P4-1: both previously used `overridden`). */
+export function parseDisplaySetting(out, kind) {
+  const text = String(out ?? "")
+  const flag = kind === "size" ? "sizeOverridden" : "densityOverridden"
+  const override = kind === "size"
+    ? /Override size:\s*(\d+)x(\d+)/.exec(text)
+    : /Override density:\s*(\d+)/.exec(text)
+  if (override) {
+    return kind === "size"
+      ? { [flag]: true, widthPx: Number(override[1]), heightPx: Number(override[2]) }
+      : { [flag]: true, densityDpi: Number(override[1]) }
+  }
+  const physical = kind === "size"
+    ? /Physical size:\s*(\d+)x(\d+)/.exec(text)
+    : /Physical density:\s*(\d+)/.exec(text)
+  if (!physical) return {}
+  return kind === "size"
+    ? { [flag]: false, widthPx: Number(physical[1]), heightPx: Number(physical[2]) }
+    : { [flag]: false, densityDpi: Number(physical[1]) }
+}
+
+export async function readConfig(serial) {
+  const [sizeOut, densityOut, fontOut] = await Promise.all([
+    DeviceBuild.adbRun(serial, ["shell", "wm", "size"]).catch(() => ""),
+    DeviceBuild.adbRun(serial, ["shell", "wm", "density"]).catch(() => ""),
+    DeviceBuild.adbRun(serial, ["shell", "settings", "get", "system", "font_scale"]).catch(() => ""),
+  ])
+  const fontRaw = String(fontOut ?? "").trim()
+  const fontScale = fontRaw === "" || fontRaw === "null" ? 1 : Number(fontRaw)
+  return {
+    ...parseDisplaySetting(sizeOut, "size"),
+    ...parseDisplaySetting(densityOut, "density"),
+    fontScale: Number.isFinite(fontScale) ? fontScale : 1,
+  }
+}
+
+/** Put one device setting and VERIFY it took effect by reading back (bounded retries). */
+async function setVerified(serial, apply, read, expect, approx = false) {
+  for (let attempt = 0; attempt < 3; attempt++) {
+    await apply()
+    await sleep(approx ? 600 : 300)
+    const actual = await read()
+    const ok = approx ? Math.abs(actual - expect) < 0.01 : actual === expect
+    if (ok) return { ok: true, actual }
+  }
+  return { ok: false, actual: await read() }
+}
+
+async function applyCase(serial, c) {
+  if (c.dims) {
+    const r = await setVerified(serial,
+      () => DeviceBuild.adbRun(serial, ["shell", "wm", "size", `${c.dims[0]}x${c.dims[1]}`]),
+      async () => { const s = await readConfig(serial); return s.widthPx },
+      c.dims[0])
+    if (!r.ok) return { ok: false, step: "size", ...r }
+  }
+  if (c.density) {
+    const r = await setVerified(serial,
+      () => DeviceBuild.adbRun(serial, ["shell", "wm", "density", String(c.density)]),
+      async () => { const s = await readConfig(serial); return s.densityDpi },
+      c.density)
+    if (!r.ok) return { ok: false, step: "density", ...r }
+  }
+  if (c.fontScale !== undefined) {
+    const r = await setVerified(serial,
+      () => DeviceBuild.adbRun(serial, ["shell", "settings", "put", "system", "font_scale", String(c.fontScale)]),
+      async () => { const s = await readConfig(serial); return s.fontScale },
+      c.fontScale, true)
+    if (!r.ok) return { ok: false, step: "font_scale", ...r }
+  }
+  await sleep(700) // reflow settle before capture
+  return { ok: true }
+}
+
+/** Restore to the FOUND state: re-apply pre-existing overrides, else reset. */
+export async function restoreConfig(serial, snapshot) {
+  const problems = []
+  if (snapshot.widthPx !== undefined) {
+    try {
+      if (snapshot.sizeOverridden) await DeviceBuild.adbRun(serial, ["shell", "wm", "size", `${snapshot.widthPx}x${snapshot.heightPx}`])
+      else await DeviceBuild.adbRun(serial, ["shell", "wm", "size", "reset"])
+    } catch (e) { problems.push(`size restore failed: ${e}`) }
+  }
+  if (snapshot.densityDpi !== undefined) {
+    try {
+      if (snapshot.densityOverridden) await DeviceBuild.adbRun(serial, ["shell", "wm", "density", String(snapshot.densityDpi)])
+      else await DeviceBuild.adbRun(serial, ["shell", "wm", "density", "reset"])
+    } catch (e) { problems.push(`density restore failed: ${e}`) }
+  }
+  try { await DeviceBuild.adbRun(serial, ["shell", "settings", "put", "system", "font_scale", String(snapshot.fontScale ?? 1)]) } catch (e) { problems.push(`font_scale restore failed: ${e}`) }
+  await sleep(700)
+  const after = await readConfig(serial)
+  const ok = problems.length === 0 &&
+    (snapshot.widthPx === undefined || (after.widthPx === snapshot.widthPx && after.heightPx === snapshot.heightPx)) &&
+    (snapshot.densityDpi === undefined || after.densityDpi === snapshot.densityDpi) &&
+    Math.abs((after.fontScale ?? 1) - (snapshot.fontScale ?? 1)) < 0.01
+  return { ok, problems, actualAfterRestore: after, snapshotWas: snapshot }
+}
+
+/**
+ * Run a bounded matrix (1..8 cases — explicit expansion is the user's call,
+ * no uncontrolled Cartesian product). Evidence goes through the capture store.
+ */
+export async function runMatrix({ serial, workspace, project, screen, cases, signal }) {
+  if (!isEmulatorSerial(serial)) {
+    return { status: "blocked", reason: "physical-device reconfiguration requires explicit approval; refusing", serial, reports: [] }
+  }
+  if (!Array.isArray(cases) || cases.length === 0 || cases.length > 8) {
+    return { status: "blocked", reason: "matrix must declare 1..8 risk-based cases", reports: [] }
+  }
+  const before = await readConfig(serial)
+  // parse keys are already per-kind (sizeOverridden/densityOverridden) — no re-derivation
+  const snapshot = { ...before }
+  const reports = []
+  const warnings = []
+  let restoreResult = { ok: false, problems: ["not run"], actualAfterRestore: {} }
+  try {
+    for (const c of cases) {
+      if (signal?.aborted) { reports.push({ id: c.id, status: "not_run", reason: "cancelled before case" }); continue }
+      try {
+        const applied = await applyCase(serial, c)
+        if (!applied.ok) {
+          reports.push({ id: c.id, status: "needs_review", step: applied.step, requested: c, actual: await readConfig(serial), warning: "setting did not verify — device reports a different actual configuration" })
+          continue
+        }
+        const actual = await readConfig(serial)
+        const png = await DeviceBuild.screenCapture(serial, tmpdir())
+        const evidence = png ? workspace.capture({ project, screen, stateId: c.id, pngPath: png, device: { serial, ...actual } }) : undefined
+        reports.push({
+          id: c.id,
+          requested: { dims: c.dims, density: c.density, fontScale: c.fontScale },
+          actual,
+          evidenceId: evidence?.id,
+          evidenceFile: evidence?.file,
+          status: evidence ? "captured" : "failed",
+          ...(evidence ? {} : { error: "no screenshot produced" }),
+        })
+      } catch (error) {
+        reports.push({ id: c.id, status: "failed", error: String(error instanceof Error ? error.message : error) })
+      }
+    }
+  } finally {
+    restoreResult = await restoreConfig(serial, snapshot)
+    if (!restoreResult.ok) warnings.push(`device settings NOT fully restored — actual after restore: ${JSON.stringify(restoreResult.actualAfterRestore)} problems: ${restoreResult.problems.join("; ")}`)
+  }
+  return {
+    status: signal?.aborted ? "blocked" : "completed",
+    serial,
+    snapshotBefore: snapshot,
+    reports,
+    // audit P4-4: restore travels as a real envelope field, not an array property
+    // (reports.restore was dropped by JSON serialization)
+    restore: restoreResult,
+    warnings,
+    limitations: ["theme light/dark and orientation rows are app-owned capabilities — this runner covers size/density/font-scale only", "font scale read back from the platform; no px↔sp formula applied"],
+  }
+}
+
+/** Risk-based starter matrix for a phone app from the device's actual state. */
+export function starterCases(actual) {
+  const density = actual.densityDpi ?? 420
+  const d = density / 160
+  const heightPx = actual.heightPx ?? 2400
+  const widthPx = actual.widthPx ?? Math.round(411 * d)
+  const narrowW = Math.round(320 * d)
+  const narrowH = Math.round((heightPx * narrowW) / widthPx)
+  return [
+    { id: "narrow-320dp-fs1.0", dims: [narrowW, narrowH], density, fontScale: 1 },
+    { id: "base-fs2.0", dims: [widthPx, heightPx], density, fontScale: 2 },
+  ]
+}