ltcai 10.6.3 → 10.8.0

package/scripts/check_screenshot_pixel_delta.py

@@ -0,0 +1,517 @@
+#!/usr/bin/env python3
+"""Compare release screenshots against a prior release and fail on no-change.
+
+Proves the layout rebuild actually moved pixels (or height), not just copy.
+
+Usage:
+  python scripts/check_screenshot_pixel_delta.py \\
+    --current output/release/v10.6.3/screenshots \\
+    --baseline output/release/v10.6.2/screenshots
+
+Environment:
+  LTCAI_SCREENSHOT_CURRENT            default: output/release/v{package}/screenshots
+  LTCAI_SCREENSHOT_BASELINE           explicit baseline dir (must match expected version)
+  LTCAI_SCREENSHOT_BASELINE_VERSION   pin expected baseline, e.g. 10.6.2 (default: prior git tag)
+  LTCAI_PIXEL_MIN_PCT                 default: 1.5  (non-LivingBrain screens)
+  LTCAI_PIXEL_MIN_PCT_LIVE            default: 8.0  (01/03/04 — animation alone ~7.9%)
+  LTCAI_HEIGHT_MIN_PX                 default: 24   (layout height shift counts as change)
+
+Exit 0 all screens moved enough, 1 one or more below threshold / wrong baseline, 2 bad args.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import subprocess
+import sys
+from pathlib import Path
+from typing import Dict, List, Optional, Tuple
+
+from PIL import Image, ImageChops
+
+SHOTS = [
+    "01-login.png",
+    "02-recommended-models.png",
+    "03-install-load-progress.png",
+    "04-brain-chat-home.png",
+    "05-memory-graph.png",
+    "06-capture.png",
+    "07-model-library.png",
+    "08-system.png",
+    "09-automation-runs.png",
+    "10-admin-console.png",
+    "11-knowledge-journey.png",
+    "12-review-center.png",
+]
+
+# LivingBrain animation noise can hit ~7.9% with zero layout change.
+LIVING_BRAIN = {
+    "01-login.png",
+    "03-install-load-progress.png",
+    "04-brain-chat-home.png",
+}
+
+
+def _repo_root() -> Path:
+    return Path(__file__).resolve().parents[1]
+
+
+def _package_version(root: Path) -> str:
+    package = json.loads((root / "package.json").read_text(encoding="utf-8"))
+    return str(package["version"])
+
+
+def _default_current(root: Path) -> Path:
+    env = os.environ.get("LTCAI_SCREENSHOT_CURRENT")
+    if env:
+        return Path(env)
+    version = _package_version(root)
+    return root / "output" / "release" / f"v{version}" / "screenshots"
+
+
+def _version_key(name: str) -> Tuple[int, ...]:
+    m = re.match(r"v?(\d+)\.(\d+)\.(\d+)", name)
+    if not m:
+        return (0, 0, 0)
+    return tuple(int(p) for p in m.groups())
+
+
+def _normalize_version(name: str) -> str:
+    return name[1:] if name.startswith("v") else name
+
+
+def _git_version_tags(root: Path) -> List[str]:
+    """Return sorted semver tags like ``10.6.2`` (no leading v) from the repo."""
+    try:
+        result = subprocess.run(
+            ["git", "tag", "-l", "v*.*.*"],
+            cwd=root,
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+    except OSError:
+        return []
+    if result.returncode != 0:
+        return []
+    tags: List[Tuple[Tuple[int, ...], str]] = []
+    for line in result.stdout.splitlines():
+        name = line.strip()
+        if not name:
+            continue
+        key = _version_key(name)
+        if key == (0, 0, 0):
+            continue
+        tags.append((key, _normalize_version(name)))
+    tags.sort(key=lambda item: item[0])
+    return [version for _, version in tags]
+
+
+def expected_baseline_version(root: Path, current_version: Optional[str] = None) -> str:
+    """Pin the baseline to a release tag — never "any older dir".
+
+    Resolution order:
+      1. ``LTCAI_SCREENSHOT_BASELINE_VERSION`` (explicit pin)
+      2. Git tag whose name matches the package version (same-name tag)
+         — used when the version was not bumped after a release. Comparing
+         against the prior tag (e.g. 10.6.2 while package is still 10.6.3 and
+         ``v10.6.3`` is tagged) lets screens that are identical to the already
+         shipped release pass, because they still differ from two-releases-ago.
+         Same-name baseline forces a real delta vs the published screenshots
+         (materialized via ``git show`` when the on-disk dir is missing/stale).
+      3. Highest git tag strictly older than the package version
+      4. Patch-1 of the package version (last resort when tags are unavailable)
+
+    This also prevents a silent downgrade to v10.6.1 when v10.6.2 is deleted
+    from ``output/release/`` — which would inflate the pixel-change rate.
+    """
+    env = os.environ.get("LTCAI_SCREENSHOT_BASELINE_VERSION")
+    if env:
+        return _normalize_version(env.strip())
+
+    current = _normalize_version(current_version or _package_version(root))
+    tags = _git_version_tags(root)
+    # Same-name tag = this version already shipped. Baseline is that release,
+    # not the prior one (failure mode: unbumped recapture vs two-releases-ago).
+    if current in tags:
+        return current
+
+    cur_key = _version_key(current)
+    older = [v for v in tags if _version_key(v) < cur_key]
+    if older:
+        return older[-1]
+
+    major, minor, patch = cur_key
+    if patch > 0:
+        return f"{major}.{minor}.{patch - 1}"
+    if minor > 0:
+        return f"{major}.{minor - 1}.0"
+    if major > 0:
+        return f"{major - 1}.0.0"
+    return current
+
+
+def _baseline_dir_for_version(root: Path, version: str) -> Path:
+    return root / "output" / "release" / f"v{_normalize_version(version)}" / "screenshots"
+
+
+def _baseline_looks_complete(shots: Path) -> bool:
+    return shots.is_dir() and (shots / "01-login.png").is_file()
+
+
+def _extract_baseline_from_git(root: Path, version: str) -> Optional[Path]:
+    """Materialize ``v{version}`` release screenshots from the matching git tag.
+
+    Used when the working tree no longer has ``output/release/vX.Y.Z`` but the
+    tag still carries the evidence (so deleting a local dir cannot silently
+    fall back to an older on-disk release).
+    """
+    version = _normalize_version(version)
+    tag = f"v{version}"
+    probe = subprocess.run(
+        ["git", "rev-parse", "--verify", f"{tag}^{{commit}}"],
+        cwd=root,
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    if probe.returncode != 0:
+        return None
+
+    cache = root / "output" / ".cache" / "screenshot-baseline" / f"v{version}" / "screenshots"
+    cache.mkdir(parents=True, exist_ok=True)
+    extracted = 0
+    for name in SHOTS:
+        dest = cache / name
+        if dest.is_file() and dest.stat().st_size > 0:
+            extracted += 1
+            continue
+        git_path = f"output/release/v{version}/screenshots/{name}"
+        result = subprocess.run(
+            ["git", "show", f"{tag}:{git_path}"],
+            cwd=root,
+            capture_output=True,
+            check=False,
+        )
+        if result.returncode != 0 or not result.stdout:
+            continue
+        dest.write_bytes(result.stdout)
+        extracted += 1
+    if extracted < len(SHOTS):
+        return None
+    return cache
+
+
+def resolve_baseline(
+    root: Path,
+    current: Path,
+    *,
+    explicit: Optional[Path] = None,
+) -> Tuple[Optional[Path], str]:
+    """Return ``(baseline_dir_or_None, expected_version)``.
+
+    Never substitutes an older-than-expected on-disk release. Callers must fail
+    when the path is None.
+
+    When the baseline version equals the package version (same-name tag path),
+    prefer screenshots materialized from the git tag over
+    ``output/release/vX.Y.Z/`` — that on-disk dir is where capture writes, so
+    it may already hold WIP overwrites of the published release.
+    """
+    expected = expected_baseline_version(root)
+    print(f"pixel delta: expected baseline version = v{expected}")
+
+    if explicit is not None:
+        return explicit.resolve(), expected
+
+    env = os.environ.get("LTCAI_SCREENSHOT_BASELINE")
+    if env:
+        path = Path(env).resolve()
+        # If the path embeds a version segment, it must match the pin.
+        parent_name = path.parent.name if path.name == "screenshots" else path.name
+        if parent_name.startswith("v") and _normalize_version(parent_name) != expected:
+            print(
+                f"pixel delta: LTCAI_SCREENSHOT_BASELINE points at {parent_name}, "
+                f"expected v{expected}",
+                file=sys.stderr,
+            )
+            return None, expected
+        return path, expected
+
+    package = _normalize_version(_package_version(root))
+    same_name_as_package = _normalize_version(expected) == package
+
+    # Same-name baseline: always take the tagged release via git show.
+    # Local output/release/v{package}/ is the capture target and may already
+    # contain unreleased UI (exactly the failure mode this pin prevents).
+    if same_name_as_package:
+        extracted = _extract_baseline_from_git(root, expected)
+        if extracted is not None and _baseline_looks_complete(extracted):
+            print(
+                f"pixel delta: same-name tag v{expected} — "
+                f"materialized baseline from git (not on-disk output/release/)"
+            )
+            return extracted.resolve(), expected
+        print(
+            f"pixel delta: same-name tag v{expected} but git materialization failed",
+            file=sys.stderr,
+        )
+        return None, expected
+
+    local = _baseline_dir_for_version(root, expected)
+    if _baseline_looks_complete(local):
+        return local.resolve(), expected
+
+    extracted = _extract_baseline_from_git(root, expected)
+    if extracted is not None and _baseline_looks_complete(extracted):
+        print(f"pixel delta: materialized baseline from git tag v{expected}")
+        return extracted.resolve(), expected
+
+    return None, expected
+
+
+def _default_baseline(root: Path, current: Path) -> Optional[Path]:
+    """Backward-compatible helper: path only (no version). Prefer resolve_baseline."""
+    path, _version = resolve_baseline(root, current)
+    return path
+
+
+def _pixel_delta_pct(
+    a: Path,
+    b: Path,
+    region: Optional[List[float]] = None,
+) -> Tuple[float, int, int, int, int]:
+    """Return (changed_pct, changed_px, total_px, height_a, height_b).
+
+    ``region`` is ``[x0, y0, x1, y1]`` as fractions of the aligned canvas. It
+    narrows the comparison to the part of the screen a release says it
+    changed, so an animated element elsewhere cannot mask a real change — or
+    manufacture one. Heights are always reported for the full images.
+    """
+    with Image.open(a) as im_a, Image.open(b) as im_b:
+        im_a = im_a.convert("RGB")
+        im_b = im_b.convert("RGB")
+        h_a, h_b = im_a.size[1], im_b.size[1]
+        # Align to common box so pure vertical growth still registers.
+        w = max(im_a.size[0], im_b.size[0])
+        h = max(h_a, h_b)
+        canvas_a = Image.new("RGB", (w, h), (0, 0, 0))
+        canvas_b = Image.new("RGB", (w, h), (0, 0, 0))
+        canvas_a.paste(im_a, (0, 0))
+        canvas_b.paste(im_b, (0, 0))
+        if region:
+            x0, y0, x1, y1 = region
+            box = (
+                max(0, min(w, int(round(w * x0)))),
+                max(0, min(h, int(round(h * y0)))),
+                max(0, min(w, int(round(w * x1)))),
+                max(0, min(h, int(round(h * y1)))),
+            )
+            if box[2] > box[0] and box[3] > box[1]:
+                canvas_a = canvas_a.crop(box)
+                canvas_b = canvas_b.crop(box)
+                w, h = canvas_a.size
+        diff = ImageChops.difference(canvas_a, canvas_b)
+        # Any channel delta > 8 counts as changed (ignore sub-pixel AA noise).
+        # Count on RGB getdata: a pixel is changed if any channel exceeds the
+        # threshold. (A point()+convert("L") mask would average channels and
+        # under-count single-channel diffs, so we do not use it.)
+        pixels = list(diff.getdata())
+        changed = sum(1 for r, g, b in pixels if r > 8 or g > 8 or b > 8)
+        total = w * h
+        pct = (100.0 * changed / total) if total else 0.0
+        return pct, changed, total, h_a, h_b
+
+
+CLAIMS_PATH = "scripts/release_screen_claims.json"
+
+
+def _load_screen_claims(root: Path, version: str) -> Optional[Dict[str, Dict[str, object]]]:
+    """What this release says it changed, or None for "all twelve".
+
+    A version with no entry is gated on every screen, so forgetting to write a
+    claim makes this check stricter rather than weaker.
+    """
+    path = root / CLAIMS_PATH
+    if not path.is_file():
+        return None
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except ValueError as exc:
+        print(f"pixel delta: {CLAIMS_PATH} is not valid JSON ({exc})", file=sys.stderr)
+        return None
+    entry = data.get(_normalize_version(version))
+    if not isinstance(entry, dict):
+        return None
+    return {
+        name: (options if isinstance(options, dict) else {})
+        for name, options in entry.items()
+        if name in SHOTS
+    }
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    root = _repo_root()
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--current", type=Path, default=_default_current(root))
+    parser.add_argument("--baseline", type=Path, default=None)
+    parser.add_argument(
+        "--expect-baseline-version",
+        type=str,
+        default=None,
+        help="Override expected baseline version pin (same as LTCAI_SCREENSHOT_BASELINE_VERSION)",
+    )
+    parser.add_argument(
+        "--min-pct",
+        type=float,
+        default=float(os.environ.get("LTCAI_PIXEL_MIN_PCT", "1.5")),
+        help="Minimum pixel change %% for non-LivingBrain screens",
+    )
+    parser.add_argument(
+        "--min-pct-live",
+        type=float,
+        default=float(os.environ.get("LTCAI_PIXEL_MIN_PCT_LIVE", "8.0")),
+        help="Minimum pixel change %% for LivingBrain screens (above ~7.9%% noise)",
+    )
+    parser.add_argument(
+        "--min-height-px",
+        type=int,
+        default=int(os.environ.get("LTCAI_HEIGHT_MIN_PX", "24")),
+        help="Height delta (px) that counts as a layout change even if pixel %% is low",
+    )
+    args = parser.parse_args(argv)
+
+    if args.expect_baseline_version:
+        os.environ["LTCAI_SCREENSHOT_BASELINE_VERSION"] = _normalize_version(
+            args.expect_baseline_version
+        )
+
+    current = args.current.resolve()
+    baseline, expected_version = resolve_baseline(
+        root, current, explicit=args.baseline
+    )
+    print(f"pixel delta: current  = {current}")
+    print(f"pixel delta: baseline = {baseline}")
+    print(f"pixel delta: baseline version pin = v{expected_version}")
+
+    if not current.is_dir():
+        print(f"pixel delta: current dir missing: {current}", file=sys.stderr)
+        return 2
+    if baseline is None or not baseline.is_dir():
+        print(
+            f"pixel delta: FAIL — expected baseline v{expected_version} is missing "
+            f"(will not fall back to an older release). "
+            f"Restore output/release/v{expected_version}/screenshots or the git tag.",
+            file=sys.stderr,
+        )
+        return 1
+
+    # Final pin check: if baseline path embeds a version, it must match.
+    parent_name = baseline.parent.name if baseline.name == "screenshots" else baseline.name
+    if parent_name.startswith("v") and _normalize_version(parent_name) != expected_version:
+        print(
+            f"pixel delta: FAIL — baseline path version {parent_name} "
+            f"!= expected v{expected_version}",
+            file=sys.stderr,
+        )
+        return 1
+
+    print(
+        f"pixel delta: thresholds static>={args.min_pct:.1f}% "
+        f"live>={args.min_pct_live:.1f}% height>={args.min_height_px}px"
+    )
+    print(
+        f"{'file':<32} {'px%':>8} {'Δh':>6} {'min%':>6} {'pass':>5}"
+    )
+    print("-" * 64)
+
+    claims = _load_screen_claims(root, _package_version(root))
+    if claims is None:
+        print(f"pixel delta: no claim for this version in {CLAIMS_PATH} — gating all {len(SHOTS)} screens")
+    else:
+        print(
+            f"pixel delta: gating {len(claims)} claimed screen(s); "
+            f"{len(SHOTS) - len(claims)} unclaimed screen(s) measured but not gated"
+        )
+
+    failures: List[str] = []
+    results: List[Dict[str, object]] = []
+
+    for name in SHOTS:
+        claimed = claims is None or name in SHOTS and name in claims
+        options = (claims or {}).get(name, {}) if claims is not None else {}
+        cur = current / name
+        base = baseline / name
+        if not cur.is_file():
+            failures.append(f"{name}: missing in current")
+            print(f"{name:<32} {'—':>8} {'—':>6} {'—':>6} FAIL")
+            continue
+        if not base.is_file():
+            failures.append(f"{name}: missing in baseline")
+            print(f"{name:<32} {'—':>8} {'—':>6} {'—':>6} FAIL")
+            continue
+
+        region = options.get("region") if isinstance(options.get("region"), list) else None
+        pct, changed, total, h_cur, h_base = _pixel_delta_pct(cur, base, region)
+        height_delta = abs(h_cur - h_base)
+        live = name in LIVING_BRAIN
+        # A claim that names its region has already excluded the animated part
+        # of the screen, so the live threshold no longer buys anything there.
+        default_min = args.min_pct_live if (live and not region) else args.min_pct
+        override = options.get("min_pct")
+        min_pct = float(override) if isinstance(override, (int, float)) else default_min
+        # Height growth alone proves layout rebuild for full-page shots.
+        moved = pct >= min_pct or height_delta >= args.min_height_px
+        ok = moved or not claimed
+        tag = "ok" if moved else ("—" if not claimed else "FAIL")
+        if claimed and not moved:
+            failures.append(
+                f"{name}: pixel={pct:.2f}% (need>={min_pct:.1f}%) "
+                f"height_delta={height_delta}px (need>={args.min_height_px})"
+                + (f" region={region}" if region else "")
+            )
+        marker = "" if claimed else " (unclaimed)"
+        print(f"{name:<32} {pct:7.2f}% {height_delta:5d}p {min_pct:5.1f}% {tag:>5}{marker}")
+        results.append(
+            {
+                "file": name,
+                "pixel_pct": round(pct, 3),
+                "height_current": h_cur,
+                "height_baseline": h_base,
+                "height_delta": height_delta,
+                "min_pct": min_pct,
+                "living_brain": live,
+                "region": region,
+                "claimed": claimed,
+                "moved": moved,
+                "pass": ok,
+            }
+        )
+
+    print("-" * 64)
+    gated = sum(1 for item in results if item["claimed"])
+    if failures:
+        print(f"pixel delta: FAIL — {len(failures)}/{gated} claimed screen(s) below threshold")
+        for item in failures:
+            print(f"  - {item}", file=sys.stderr)
+        return 1
+
+    # An unclaimed screen that moved is not a failure, but it is worth saying:
+    # it is either an unintended side effect or a claim someone forgot to write.
+    surprises = [
+        f"{item['file']} ({item['pixel_pct']:.2f}%)"
+        for item in results
+        if not item["claimed"] and item["moved"]
+    ]
+    if surprises:
+        print(f"pixel delta: note — unclaimed screens that changed anyway: {', '.join(surprises)}")
+
+    print(f"pixel delta: PASS — all {gated} claimed screen(s) moved vs baseline v{expected_version}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/measure_brain_home_fill.mjs

@@ -0,0 +1,141 @@
+#!/usr/bin/env node
+/**
+ * Measure Brain chat home (screen 04) content fill against the viewport.
+ *
+ * The layout rebuild requires the empty home's content bottom to reach at
+ * least 90% of the 920px capture viewport — not "looks better" prose.
+ *
+ * Walks the same onboarding path as capture_release_evidence.mjs so #/brain
+ * is the empty first-run home against the visual mock server.
+ *
+ * Exit 0 when bottom/viewport >= --min-ratio (default 0.90), else 1.
+ */
+import { chromium } from "playwright";
+import { spawn } from "node:child_process";
+
+const repoRoot = process.cwd();
+const port = Number(process.env.LTCAI_RELEASE_EVIDENCE_PORT || 4937);
+const baseURL = `http://127.0.0.1:${port}`;
+const minRatio = Number(process.env.LTCAI_HOME_FILL_MIN || "0.90");
+
+const server = spawn(process.execPath, ["tests/visual/mock_server.cjs"], {
+  cwd: repoRoot,
+  env: { ...process.env, LTCAI_VISUAL_PORT: String(port) },
+  stdio: ["ignore", "pipe", "pipe"],
+});
+
+async function waitForServer() {
+  const deadline = Date.now() + 15000;
+  while (Date.now() < deadline) {
+    try {
+      const res = await fetch(`${baseURL}/health`);
+      if (res.ok) return;
+    } catch {
+      /* retry */
+    }
+    await new Promise((r) => setTimeout(r, 150));
+  }
+  throw new Error(`visual server did not start on ${baseURL}`);
+}
+
+async function main() {
+  await waitForServer();
+  const browser = await chromium.launch({ headless: true });
+  const context = await browser.newContext({
+    viewport: { width: 1440, height: 920 },
+  });
+  const page = await context.newPage();
+  page.setDefaultTimeout(15000);
+
+  // Same first-run reset as release capture — without this the product flow
+  // may already be complete and the wake button never appears.
+  await page.addInitScript(() => {
+    localStorage.removeItem("lattice.productFlow.complete");
+    localStorage.removeItem("lattice.productFlow.user");
+    localStorage.setItem("lattice.language", "ko");
+    localStorage.setItem("lattice.mode", "basic");
+  });
+
+  await page.goto(`${baseURL}/app`, { waitUntil: "networkidle" });
+  const korean = page.getByRole("button", { name: "한국어" });
+  if (await korean.count()) {
+    await korean.click();
+  }
+  await page.getByRole("button", { name: "Brain 지금 깨우기" }).click();
+  await page.getByText("이 Brain의 주인을 정합니다.").waitFor();
+  await page.getByPlaceholder(/You|나/).fill("Codex");
+  await page.getByPlaceholder("you@local").fill("codex@local");
+  await page.getByPlaceholder("로컬 Brain 비밀번호").fill("Lattice123");
+  await page.getByRole("button", { name: "내 Brain 시작하기" }).click();
+  await page.getByText("추천대로 시작하세요.").waitFor();
+  await page.getByRole("button", { name: "추천으로 바로 시작" }).click();
+  await page.getByText("모델을 준비하고 시작합니다.").waitFor();
+  await page.getByRole("button", { name: "준비하고 시작하기" }).click();
+  await page.waitForTimeout(180);
+  await page
+    .getByRole("button", { name: /시작|들어가|Brain 열기|Open Brain/i })
+    .first()
+    .click({ timeout: 5000 })
+    .catch(() => {});
+  await page.locator("main[aria-label='Lattice Brain']").waitFor({ timeout: 15000 });
+  await page.waitForTimeout(250);
+
+  const metrics = await page.evaluate(() => {
+    const main = document.querySelector("main[aria-label='Lattice Brain']");
+    const home =
+      document.querySelector(".brain-centered-home") ||
+      document.querySelector(".brain-home-station") ||
+      main;
+    const quiet = document.querySelector(
+      "footer.brain-home-quiet, .brain-home-quiet, .brain-home-shelves",
+    );
+    const composer = document.querySelector(
+      ".brain-composer, [data-testid='brain-composer'], textarea",
+    );
+    const box = (el) => {
+      if (!el) return null;
+      const r = el.getBoundingClientRect();
+      return { top: r.top, bottom: r.bottom, height: r.height, width: r.width };
+    };
+    const candidates = [home, quiet, composer, main].filter(Boolean);
+    let bottom = 0;
+    let top = Infinity;
+    for (const el of candidates) {
+      const r = el.getBoundingClientRect();
+      bottom = Math.max(bottom, r.bottom);
+      top = Math.min(top, r.top);
+    }
+    return {
+      viewport: { width: window.innerWidth, height: window.innerHeight },
+      main: box(main),
+      home: box(home),
+      quiet: box(quiet),
+      composer: box(composer),
+      contentTop: top === Infinity ? 0 : top,
+      contentBottom: bottom,
+    };
+  });
+
+  await browser.close();
+
+  const ratio = metrics.contentBottom / metrics.viewport.height;
+  const pct = (100 * ratio).toFixed(1);
+  console.log(JSON.stringify({ ...metrics, fillRatio: ratio, fillPct: `${pct}%`, minRatio }, null, 2));
+  console.log(
+    `brain home fill: contentBottom=${metrics.contentBottom.toFixed(1)}px / viewport=${metrics.viewport.height}px = ${pct}% (need >= ${(100 * minRatio).toFixed(0)}%)`,
+  );
+
+  if (ratio + 1e-6 < minRatio) {
+    console.error(
+      `brain home fill FAIL: content only reaches ${pct}% of viewport (required ${(100 * minRatio).toFixed(0)}%).`,
+    );
+    process.exit(1);
+  }
+  console.log("brain home fill PASS");
+}
+
+try {
+  await main();
+} finally {
+  server.kill();
+}

package/scripts/release_screen_claims.json

@@ -0,0 +1,37 @@
+{
+  "_comment": [
+    "Which screens each release claims to have changed, and where.",
+    "",
+    "The pixel gate used to require all twelve screens to move on every",
+    "release. That was right for 10.6.x/10.7.0, which were explicitly",
+    "'rearrange every screen' releases, and wrong as a standing rule: a",
+    "release that deliberately touches four screens would have to churn the",
+    "other eight or fail — which is the dishonesty the gate exists to catch,",
+    "inverted.",
+    "",
+    "A release lists the screens it claims to have changed. Claimed screens",
+    "are gated exactly as before. Unclaimed screens are still measured and",
+    "printed, so an unintended change is visible, but do not fail the run.",
+    "A version with no entry here is gated on all twelve — forgetting to",
+    "write a claim makes the gate stricter, never weaker.",
+    "",
+    "'region' narrows the comparison to [x0, y0, x1, y1] as fractions of the",
+    "image. Use it when a screen carries an animated element that dominates a",
+    "whole-image delta: naming where the change is makes the claim more",
+    "specific, not less."
+  ],
+
+  "10.8.0": {
+    "01-login.png": {},
+    "02-recommended-models.png": {},
+    "03-install-load-progress.png": {},
+    "05-memory-graph.png": {
+      "_why": "The provenance meter in this screen's header wrapped into a ragged three-line block that ran into the page title. It is a bordered column with a straight left edge now."
+    },
+    "04-brain-chat-home.png": {
+      "_why": "The Brain organism sits in this screen's greeting banner and moved 7.34% of that band between 10.6.3 and 10.7.0 with no layout intent, which is why 04 carries the 8% live threshold. 10.8.0 changed the suggestion deck and the shelf row below the composer; measuring that region directly is both stricter (the claim names where) and able to see a change the whole-image metric cannot.",
+      "region": [0.0, 0.45, 1.0, 0.85],
+      "min_pct": 1.5
+    }
+  }
+}