cg-code-graph 0.10.1__py3-none-any.whl

codegraph/viz/tools/package-lock.json

@@ -0,0 +1,303 @@
+{
+  "name": "codegraph-viz-tools",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "codegraph-viz-tools",
+      "dependencies": {
+        "puppeteer-core": "25.12.0"
+      }
+    },
+    "node_modules/@puppeteer/browsers": {
+      "version": "3.2.3",
+      "resolved": "https://registry.npmjs.org/@puppeteer/browsers/-/browsers-3.2.3.tgz",
+      "integrity": "sha512-2Bt3m6dDAJqmZehn0wiXSYyQmuhyiHHZ7FjvrVaS1W2RoFGV6eCK71UvKYkNJjkwC1Q9nobjhvTMhLQztFVINA==",
+      "dependencies": {
+        "modern-tar": "^0.8.4",
+        "yargs": "^18.0.0"
+      },
+      "bin": {
+        "browsers": "lib/main-cli.js"
+      },
+      "engines": {
+        "node": ">=22.12.0"
+      },
+      "peerDependencies": {
+        "proxy-agent": ">=8.0.1",
+        "yauzl": "^2.10.0 || ^3.4.0"
+      },
+      "peerDependenciesMeta": {
+        "proxy-agent": {
+          "optional": true
+        },
+        "yauzl": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/ansi-regex": {
+      "version": "6.4.0",
+      "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-6.4.0.tgz",
+      "integrity": "sha512-KzTVk2tCWAHtYrvvvaP8bJKJq2pVinhLcGEQdtLIYPbmNGNyYe8QwNaTUYQp2J7/vIsUKt5QCqAfUkYyG9DkOw==",
+      "engines": {
+        "node": ">=12"
+      },
+      "funding": {
+        "url": "https://github.com/chalk/ansi-regex?sponsor=1"
+      }
+    },
+    "node_modules/ansi-styles": {
+      "version": "6.2.3",
+      "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-6.2.3.tgz",
+      "integrity": "sha512-4Dj6M28JB+oAH8kFkTLUo+a2jwOFkuqb3yucU0CANcRRUbxS0cP0nZYCGjcc3BNXwRIsUVmDGgzawme7zvJHvg==",
+      "engines": {
+        "node": ">=12"
+      },
+      "funding": {
+        "url": "https://github.com/chalk/ansi-styles?sponsor=1"
+      }
+    },
+    "node_modules/chromium-bidi": {
+      "version": "17.0.2",
+      "resolved": "https://registry.npmjs.org/chromium-bidi/-/chromium-bidi-17.0.2.tgz",
+      "integrity": "sha512-5v9GQFhTktFvotn/OFNJBmKLKRAb6n9r0bVCwf7sHgWc3/JryK0bj1nn93L3pHFrfgcsu6Be6EWsDi+1XHTGDg==",
+      "dependencies": {
+        "mitt": "^3.0.1",
+        "zod": "^3.24.1"
+      },
+      "engines": {
+        "node": ">=20.19.0 <22.0.0 || >=22.12.0"
+      },
+      "peerDependencies": {
+        "devtools-protocol": "*"
+      }
+    },
+    "node_modules/cliui": {
+      "version": "9.0.1",
+      "resolved": "https://registry.npmjs.org/cliui/-/cliui-9.0.1.tgz",
+      "integrity": "sha512-k7ndgKhwoQveBL+/1tqGJYNz097I7WOvwbmmU2AR5+magtbjPWQTS1C5vzGkBC8Ym8UWRzfKUzUUqFLypY4Q+w==",
+      "dependencies": {
+        "string-width": "^7.2.0",
+        "strip-ansi": "^7.1.0",
+        "wrap-ansi": "^9.0.0"
+      },
+      "engines": {
+        "node": ">=20"
+      }
+    },
+    "node_modules/cliui/node_modules/string-width": {
+      "version": "7.2.0",
+      "resolved": "https://registry.npmjs.org/string-width/-/string-width-7.2.0.tgz",
+      "integrity": "sha512-tsaTIkKW9b4N+AEj+SVA+WhJzV7/zMhcSu78mLKWSk7cXMOSHsBKFWUs0fWwq8QyK3MgJBQRX6Gbi4kYbdvGkQ==",
+      "dependencies": {
+        "emoji-regex": "^10.3.0",
+        "get-east-asian-width": "^1.0.0",
+        "strip-ansi": "^7.1.0"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/devtools-protocol": {
+      "version": "0.0.1687809",
+      "resolved": "https://registry.npmjs.org/devtools-protocol/-/devtools-protocol-0.0.1687809.tgz",
+      "integrity": "sha512-t7kSb+UKYdyxcmqy98U2P86ne6rCve3DIJ4+lp54i/hhClgFuG35JrLj23rO14Jw3sWDsp7i+22QhNU0+/qk8g=="
+    },
+    "node_modules/emoji-regex": {
+      "version": "10.6.0",
+      "resolved": "https://registry.npmjs.org/emoji-regex/-/emoji-regex-10.6.0.tgz",
+      "integrity": "sha512-toUI84YS5YmxW219erniWD0CIVOo46xGKColeNQRgOzDorgBi1v4D71/OFzgD9GO2UGKIv1C3Sp8DAn0+j5w7A=="
+    },
+    "node_modules/escalade": {
+      "version": "3.2.0",
+      "resolved": "https://registry.npmjs.org/escalade/-/escalade-3.2.0.tgz",
+      "integrity": "sha512-WUj2qlxaQtO4g6Pq5c29GTcWGDyd8itL8zTlipgECz3JesAiiOKotd8JU6otB3PACgG6xkJUyVhboMS+bje/jA==",
+      "engines": {
+        "node": ">=6"
+      }
+    },
+    "node_modules/get-caller-file": {
+      "version": "2.0.5",
+      "resolved": "https://registry.npmjs.org/get-caller-file/-/get-caller-file-2.0.5.tgz",
+      "integrity": "sha512-DyFP3BM/3YHTQOCUL/w0OZHR0lpKeGrxotcHWcqNEdnltqFwXVfhEBQ94eIo34AfQpo0rGki4cyIiftY06h2Fg==",
+      "engines": {
+        "node": "6.* || 8.* || >= 10.*"
+      }
+    },
+    "node_modules/get-east-asian-width": {
+      "version": "1.7.0",
+      "resolved": "https://registry.npmjs.org/get-east-asian-width/-/get-east-asian-width-1.7.0.tgz",
+      "integrity": "sha512-XjH1AECxf0giL2V1aU8vKyRR2ppRUb5c0EvT7zuJTokQ74bNo52zOtghqdWIqrhUD79fo3x0WfKZdOqxF6LG1Q==",
+      "engines": {
+        "node": ">=18"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/mitt": {
+      "version": "3.0.1",
+      "resolved": "https://registry.npmjs.org/mitt/-/mitt-3.0.1.tgz",
+      "integrity": "sha512-vKivATfr97l2/QBCYAkXYDbrIWPM2IIKEl7YPhjCvKlG3kE2gm+uBo6nEXK3M5/Ffh/FLpKExzOQ3JJoJGFKBw=="
+    },
+    "node_modules/modern-tar": {
+      "version": "0.8.5",
+      "resolved": "https://registry.npmjs.org/modern-tar/-/modern-tar-0.8.5.tgz",
+      "integrity": "sha512-snEhs+6G5Tjd4I7tLCDOaoln2RgE0bD19RzEKgvgK2hZ5VKy3MpLhLTZ2fWpXSTg4K2cyPwp+VHATFJhxfnOeA==",
+      "engines": {
+        "node": ">=18.0.0"
+      }
+    },
+    "node_modules/puppeteer-core": {
+      "version": "25.12.0",
+      "resolved": "https://registry.npmjs.org/puppeteer-core/-/puppeteer-core-25.12.0.tgz",
+      "integrity": "sha512-z6LQUt5SH7jwGtGA+nMtJuEjZIsqPiwQ+EFHCYuVDQrJpvifNmmGuyDvTzAKPyFzihxgHc5f3aMzu2kn8Ps37A==",
+      "dependencies": {
+        "@puppeteer/browsers": "3.2.3",
+        "chromium-bidi": "17.0.2",
+        "devtools-protocol": "0.0.1687809",
+        "typed-query-selector": "^2.12.2",
+        "webdriver-bidi-protocol": "0.4.3",
+        "ws": "^8.21.3"
+      },
+      "engines": {
+        "node": ">=22.12.0"
+      }
+    },
+    "node_modules/string-width": {
+      "version": "8.3.0",
+      "resolved": "https://registry.npmjs.org/string-width/-/string-width-8.3.0.tgz",
+      "integrity": "sha512-ZbmZM0JCihQN91dWnxoipT2KOEyHqEyfRXUyjuRhW8b/xnqPDoq4gWEVApTVa9db2wN8mmoikgFBbjh71+cGeQ==",
+      "dependencies": {
+        "get-east-asian-width": "^1.5.0",
+        "strip-ansi": "^7.1.2"
+      },
+      "engines": {
+        "node": ">=20"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/strip-ansi": {
+      "version": "7.2.0",
+      "resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-7.2.0.tgz",
+      "integrity": "sha512-yDPMNjp4WyfYBkHnjIRLfca1i6KMyGCtsVgoKe/z1+6vukgaENdgGBZt+ZmKPc4gavvEZ5OgHfHdrazhgNyG7w==",
+      "dependencies": {
+        "ansi-regex": "^6.2.2"
+      },
+      "engines": {
+        "node": ">=12"
+      },
+      "funding": {
+        "url": "https://github.com/chalk/strip-ansi?sponsor=1"
+      }
+    },
+    "node_modules/typed-query-selector": {
+      "version": "2.12.3",
+      "resolved": "https://registry.npmjs.org/typed-query-selector/-/typed-query-selector-2.12.3.tgz",
+      "integrity": "sha512-/dtuMZyutHLlrxWhhC1uib00ELUr2dZ8C9B8YzZYsJmeE3V56OxRblrSM2UaF142pcMtak7ehZ6+poWGeehNIg=="
+    },
+    "node_modules/webdriver-bidi-protocol": {
+      "version": "0.4.3",
+      "resolved": "https://registry.npmjs.org/webdriver-bidi-protocol/-/webdriver-bidi-protocol-0.4.3.tgz",
+      "integrity": "sha512-uuN0goWfxP22B7J/uAgBpOYNPttC+XVseYE+rSY5+rQ+YBeVz/VORw8WbmLVcqW78zNg5A4qnjNXYUWR3il2ig=="
+    },
+    "node_modules/wrap-ansi": {
+      "version": "9.0.2",
+      "resolved": "https://registry.npmjs.org/wrap-ansi/-/wrap-ansi-9.0.2.tgz",
+      "integrity": "sha512-42AtmgqjV+X1VpdOfyTGOYRi0/zsoLqtXQckTmqTeybT+BDIbM/Guxo7x3pE2vtpr1ok6xRqM9OpBe+Jyoqyww==",
+      "dependencies": {
+        "ansi-styles": "^6.2.1",
+        "string-width": "^7.0.0",
+        "strip-ansi": "^7.1.0"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "funding": {
+        "url": "https://github.com/chalk/wrap-ansi?sponsor=1"
+      }
+    },
+    "node_modules/wrap-ansi/node_modules/string-width": {
+      "version": "7.2.0",
+      "resolved": "https://registry.npmjs.org/string-width/-/string-width-7.2.0.tgz",
+      "integrity": "sha512-tsaTIkKW9b4N+AEj+SVA+WhJzV7/zMhcSu78mLKWSk7cXMOSHsBKFWUs0fWwq8QyK3MgJBQRX6Gbi4kYbdvGkQ==",
+      "dependencies": {
+        "emoji-regex": "^10.3.0",
+        "get-east-asian-width": "^1.0.0",
+        "strip-ansi": "^7.1.0"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/ws": {
+      "version": "8.22.0",
+      "resolved": "https://registry.npmjs.org/ws/-/ws-8.22.0.tgz",
+      "integrity": "sha512-Ydggc987+RO0AnWtZ/7Wq9FtNvcrL1b/RO0ud9mWjUPgDrsAAwQSF51sm2hm1XofbU/4jkpGEsLFsZZxU+1DOg==",
+      "engines": {
+        "node": ">=10.0.0"
+      },
+      "peerDependencies": {
+        "bufferutil": "^4.0.1",
+        "utf-8-validate": ">=5.0.2"
+      },
+      "peerDependenciesMeta": {
+        "bufferutil": {
+          "optional": true
+        },
+        "utf-8-validate": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/y18n": {
+      "version": "5.0.8",
+      "resolved": "https://registry.npmjs.org/y18n/-/y18n-5.0.8.tgz",
+      "integrity": "sha512-0pfFzegeDWJHJIAmTLRP2DwHjdF5s7jo9tuztdQxAhINCdvS+3nGINqPd00AphqJR/0LhANUS6/+7SCb98YOfA==",
+      "engines": {
+        "node": ">=10"
+      }
+    },
+    "node_modules/yargs": {
+      "version": "18.2.0",
+      "resolved": "https://registry.npmjs.org/yargs/-/yargs-18.2.0.tgz",
+      "integrity": "sha512-9OpKOLeaoNFecEp7P6iYbzze/5CqWoH7N3SMs/6y1XF4nMvFMspEGZzJ6uFi9MmQwXhyzqYoSEKO3tvA3Z/o2w==",
+      "dependencies": {
+        "cliui": "^9.0.1",
+        "escalade": "^3.1.1",
+        "get-caller-file": "^2.0.5",
+        "string-width": "^8.2.1",
+        "y18n": "^5.0.5",
+        "yargs-parser": "^22.0.0"
+      },
+      "engines": {
+        "node": "^20.19.0 || ^22.12.0 || >=23"
+      }
+    },
+    "node_modules/yargs-parser": {
+      "version": "22.0.0",
+      "resolved": "https://registry.npmjs.org/yargs-parser/-/yargs-parser-22.0.0.tgz",
+      "integrity": "sha512-rwu/ClNdSMpkSrUb+d6BRsSkLUq1fmfsY6TOpYzTwvwkg1/NRG85KBy3kq++A8LKQwX6lsu+aWad+2khvuXrqw==",
+      "engines": {
+        "node": "^20.19.0 || ^22.12.0 || >=23"
+      }
+    },
+    "node_modules/zod": {
+      "version": "3.25.76",
+      "resolved": "https://registry.npmjs.org/zod/-/zod-3.25.76.tgz",
+      "integrity": "sha512-gzUt/qt81nXsFGKIFcC3YnfEAx5NkunCfnDlvuBSSFS02bcXu4Lmea0AFIUwbLWxWPx3d9p8S5QoaujKcNQxcQ==",
+      "funding": {
+        "url": "https://github.com/sponsors/colinhacks"
+      }
+    }
+  }
+}

codegraph/viz/tools/package.json

@@ -0,0 +1,7 @@
+{
+  "name": "codegraph-viz-tools",
+  "private": true,
+  "description": "Headless screenshots of the code-graph view (uses the system Chrome; no browser download).",
+  "type": "module",
+  "dependencies": { "puppeteer-core": "25.12.0" }
+}

codegraph/viz/tools/shoot.mjs

@@ -0,0 +1,165 @@
+// Headless screenshots + layout checks of the code-graph view (issue #82 test plan).
+// Usage: node shoot.mjs <base-url> <out-dir>   (the view must be served: codegraph.cli serve --db … --port …)
+// Environment:
+//   CHROME   browser binary (default /usr/bin/google-chrome)
+//   WIDTHS   viewport widths, comma-separated (default 1280,1920; heights 1024→768, 1280→800, 1440→900, 1920→1080)
+//   DPR      deviceScaleFactor (default 2)
+//   SHOTS    JSON file with [{file, hash | url, maxTop?, actions?}] instead of the bundled sample-app list
+//   PRESETS  1 = also shoot every query from /api/presets (starter presets of the served graph)
+//   ONLY     substring filter on the file name
+//   NO_ASSERT 1 = report failures but exit 0
+//   THEME    light | dark: emulate prefers-color-scheme (default: the browser's)
+//   BUDGET_FIRST  first-graph budget in ms (default 1500; tReady includes the API call)
+// Shots: "landing" (hash ''), a hash on <base-url>, or an absolute url (e.g. file:///…/export.html from viz-export).
+// actions: [{expandFirstCluster: true}, {tap: '<node id>'}, {key: 'Escape'}, {wait: ms}].
+// Assertions per shot and width: no console error / warning / page error / HTTP >= 400; header.scrollWidth <=
+// clientWidth with no clipped or wrapped control and height <= 56 px; every drawn label >= 11 px (font-size x zoom);
+// <= 5 % of visible node label boxes overlap; no compound box around one node; top-level items <= maxTop.
+// Writes <out-dir>/metrics.json and exits 1 when an assertion fails.
+import puppeteer from 'puppeteer-core'
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+
+const base = (process.argv[2] || 'http://127.0.0.1:8177/').replace(/#.*$/, '')
+const out = process.argv[3] || 'screenshots'
+mkdirSync(out, { recursive: true })
+const enc = (s) => encodeURIComponent(s)
+const HEIGHT = { 1024: 768, 1280: 800, 1440: 900, 1920: 1080 }
+const WIDTHS = (process.env.WIDTHS || '1280,1920').split(',').map(Number)
+const DPR = Number(process.env.DPR || 2)
+const MIN_PX = 11; const MAX_OVERLAP = 5; const MAX_HEADER = 56
+// Default shots match the bundled sample apps (examples/); pass SHOTS=path/to/shots.json for your project.
+const DEFAULT_SHOTS = [
+  { file: 'sample_landing.png', hash: '' },
+  { file: 'sample_reaches_warehouse.png', hash: `mode=reaches&spec=${enc('connection:warehouse')}&spec=${enc('table:warehouse_stock')}&select=${enc('connection:warehouse')}&hl=0` },
+  { file: 'sample_report_page_downstream_tables.png', hash: `mode=downstream&spec=${enc('page:/reports/:id')}&sinks=${enc('table,column')}&select=${enc('page:app/pages/reports/[id].vue')}&hl=0` },
+  { file: 'sample_report_page_path_orders.png', hash: `mode=path&spec=${enc('page:/reports/:id')}&spec=${enc('ReportController::top')}&spec=${enc('table:orders')}` +
+    `&select=${enc('method:App\\Services\\SalesReportService::build')}` },
+  { file: 'sample_plan_preorders_overview.png', hash: 'mode=plan&spec=preorders' },
+  { file: 'sample_timezone_request_key_reaches.png', hash: `mode=reaches&spec=${enc('request_key:timezone')}` }
+]
+let SHOTS = process.env.SHOTS ? JSON.parse(readFileSync(process.env.SHOTS, 'utf8')) : DEFAULT_SHOTS
+if (process.env.PRESETS === '1') {
+  const presets = await (await fetch(new URL('api/presets', base))).json()
+  SHOTS = SHOTS.concat(presets.map((p) => ({
+    file: `preset_${p.id}.png`,
+    hash: `mode=${p.mode}` + p.specs.map((s) => `&spec=${enc(s)}`).join('') + (p.sinks ? `&sinks=${enc(p.sinks.join(','))}` : '')
+  })))
+}
+const only = process.env.ONLY
+
+async function measure (page) {
+  return page.evaluate((MIN_PX) => {
+    const hd = document.querySelector('header')
+    const r = { ready: document.body.dataset.ready, header: { scroll: hd.scrollWidth, client: hd.clientWidth, height: hd.offsetHeight } }
+    const vis = [...hd.querySelectorAll('select,button,input,a')].filter((c) => c.offsetParent && getComputedStyle(c).visibility !== 'hidden')
+    r.clipped = vis.filter((c) => c.getBoundingClientRect().right > hd.clientWidth + 1).map((c) => c.id || c.textContent.trim())
+    r.wrapped = vis.filter((c) => c.tagName !== 'INPUT' && c.tagName !== 'SELECT' && c.getBoundingClientRect().height > 34).map((c) => c.id || c.textContent.trim())
+    const land = document.getElementById('landing')
+    if (land && !land.hidden) {
+      r.landing = { stats: land.querySelectorAll('.stat').length, cards: land.querySelectorAll('.card').length }
+      return r
+    }
+    const c = window.__cgCy
+    if (!c) return r
+    const z = c.zoom(); const ext = c.extent()
+    const inView = (bb) => bb.x2 > ext.x1 && bb.x1 < ext.x2 && bb.y2 > ext.y1 && bb.y1 < ext.y2
+    let minPx = Infinity; let drawn = 0; let hidden = 0; const boxes = []
+    c.elements().forEach((e) => {
+      if (!e.visible() || !e.style('label')) return
+      const px = parseFloat(e.style('font-size')) * z
+      if (px < (parseFloat(e.style('min-zoomed-font-size')) || 0)) { hidden++; return }
+      const bb = e.boundingBox({ includeNodes: false, includeEdges: false, includeLabels: true, includeOverlays: false })
+      if (!bb.w || !inView(bb)) return
+      drawn++; minPx = Math.min(minPx, px)
+      if (e.isNode()) boxes.push(bb)
+    })
+    let ov = 0
+    boxes.forEach((a, i) => { if (boxes.some((b, j) => i !== j && a.x1 < b.x2 && b.x1 < a.x2 && a.y1 < b.y2 && b.y1 < a.y2)) ov++ })
+    const ltr = c.edges().filter((e) => e.source().position().x < e.target().position().x).length
+    Object.assign(r, {
+      zoom: +z.toFixed(3),
+      labels: { drawn, hidden, minPx: drawn ? +minPx.toFixed(1) : null, overlapPct: boxes.length ? +(100 * ov / boxes.length).toFixed(1) : 0 },
+      top: c.nodes().filter((n) => !n.isChild() && !n.hasClass('lane')).length,
+      single: c.nodes(':parent').filter((p) => p.children().length === 1).length,
+      clusters: c.nodes('.cluster').length,
+      edges: c.edges().length,
+      ltrPct: c.edges().length ? +(100 * ltr / c.edges().length).toFixed(1) : null,
+      targetsVisible: c.nodes('.target, .entry').filter((n) => inView(n.boundingBox())).length + '/' + c.nodes('.target, .entry').length,
+      offscreen: c.nodes().not(':parent').filter((n) => { const b = n.boundingBox({ includeLabels: false }); return b.x1 < ext.x1 - 1 || b.x2 > ext.x2 + 1 || b.y1 < ext.y1 - 1 || b.y2 > ext.y2 + 1 }).length,
+      fitAll: document.getElementById('fitall').hidden ? null : document.getElementById('fitall').textContent,
+      status: document.getElementById('status').innerText.slice(0, 160)
+    })
+    return r
+  }, MIN_PX)
+}
+
+// performance budgets (#82 item 15): first graph <= 1.5 s for <= 300 nodes, layout <= 1.5 s, <= 400 rendered elements
+const BUDGET = { firstGraphMs: Number(process.env.BUDGET_FIRST || 1500), layoutMs: 1500, rendered: 400 }
+function check (m, s) {
+  const f = []
+  if (m.perf && m.perf.nodes && m.perf.nodes <= 300 && m.tReady > BUDGET.firstGraphMs) f.push(`first graph ${m.tReady} ms > ${BUDGET.firstGraphMs}`)
+  if (m.perf && m.perf.layoutMs > BUDGET.layoutMs) f.push(`layout ${m.perf.layoutMs} ms > ${BUDGET.layoutMs}`)
+  if (m.perf && m.perf.rendered > BUDGET.rendered) f.push(`rendered elements ${m.perf.rendered} > ${BUDGET.rendered}`)
+  if (m.offscreen) f.push(`${m.offscreen} nodes outside the canvas on first load (fit must include every node)`)
+  if (m.logs.length) f.push(`console: ${m.logs.length} (${m.logs[0]})`)
+  if (!['1', 'landing'].includes(m.ready)) f.push(`view reported ${m.ready}`)
+  if (m.header.scroll > m.header.client) f.push(`header overflow ${m.header.scroll} > ${m.header.client}`)
+  if (m.clipped.length) f.push('clipped: ' + m.clipped.join(', '))
+  if (m.wrapped.length) f.push('wrapped: ' + m.wrapped.join(', '))
+  if (m.width >= 1280 && m.header.height > MAX_HEADER) f.push(`header height ${m.header.height}`)
+  if (m.labels) {
+    if (m.labels.minPx !== null && m.labels.minPx < MIN_PX) f.push(`label ${m.labels.minPx} px < ${MIN_PX}`)
+    if (m.labels.overlapPct > MAX_OVERLAP) f.push(`label overlap ${m.labels.overlapPct} % > ${MAX_OVERLAP}`)
+    if (m.single) f.push(`${m.single} single-node compound(s)`)
+    if (s.maxTop && m.top > s.maxTop) f.push(`top-level items ${m.top} > ${s.maxTop}`)
+  }
+  return f
+}
+
+const browser = await puppeteer.launch({ executablePath: process.env.CHROME || '/usr/bin/google-chrome', headless: true,
+  args: ['--no-sandbox', '--disable-gpu'] })
+const results = []
+try {
+  for (const s of SHOTS) {
+    if (only && !s.file.includes(only)) continue
+    for (const w of WIDTHS) {
+      const page = await browser.newPage()
+      const logs = []
+      page.on('console', (m) => { if (['error', 'warn', 'warning'].includes(m.type())) logs.push(`console.${m.type()}: ${m.text()}`) })
+      page.on('pageerror', (e) => logs.push('pageerror: ' + e.message))
+      page.on('response', (r) => { if (r.status() >= 400) logs.push(`http ${r.status()}: ${r.url()}`) })
+      await page.setViewport({ width: w, height: HEIGHT[w] || Math.round(w * 0.5625), deviceScaleFactor: DPR })
+      if (process.env.THEME) await page.emulateMediaFeatures([{ name: 'prefers-color-scheme', value: process.env.THEME }])
+      // long tasks (main thread blocked > 50 ms) from the first byte on (#82 item 15)
+      await page.evaluateOnNewDocument(() => {
+        window.__cgLong = []
+        try { new PerformanceObserver((l) => { for (const e of l.getEntries()) window.__cgLong.push(e.duration) }).observe({ type: 'longtask', buffered: true }) } catch (e) { /* unsupported */ }
+      })
+      const t0 = Date.now()
+      await page.goto(s.url || (base + (s.hash ? '#' + s.hash : '')), { waitUntil: 'networkidle0' })
+      await page.waitForFunction(() => ['1', 'error', 'empty', 'landing'].includes(document.body.dataset.ready), { timeout: 60000 })
+      const tReady = Date.now() - t0
+      for (const a of s.actions || []) {
+        if (a.expandFirstCluster) await page.evaluate(() => { const n = window.__cgCy.nodes('.cluster').not('.open')[0]; if (n) n.emit('tap') })
+        if (a.tap) await page.evaluate((id) => window.__cgCy.getElementById(id).emit('tap'), a.tap)
+        if (a.key) await page.keyboard.press(a.key)
+        if (a.wait) await new Promise((r) => setTimeout(r, a.wait))
+      }
+      await new Promise((r) => setTimeout(r, 1000))  // last render + panel fetch
+      const file = `${out}/${s.file.replace(/\.png$/, '')}_${w}.png`
+      await page.screenshot({ path: file })
+      const perf = await page.evaluate(() => ({ layoutMs: Math.round(window.__cgLayoutMs || 0), maxLongTaskMs: Math.round(Math.max(0, ...(window.__cgLong || []))),
+        rendered: window.__cgCy ? window.__cgCy.elements(':visible').length : 0, nodes: window.__cgCy ? window.__cgCy.nodes().length : 0 }))
+      const m = { file, width: w, tReady, perf, ...(await measure(page)), logs }
+      m.failures = check(m, s)
+      results.push(m)
+      console.log(`${m.failures.length ? 'FAIL' : 'ok  '} ${file}` + (m.perf && m.perf.nodes ? `  ready ${m.tReady} ms layout ${m.perf.layoutMs} ms longtask ${m.perf.maxLongTaskMs} ms els ${m.perf.rendered}` : '') + (m.labels ? `  zoom ${m.zoom} label>=${m.labels.minPx}px overlap ${m.labels.overlapPct}% top ${m.top} ltr ${m.ltrPct}%` : m.landing ? `  landing stats ${m.landing.stats} cards ${m.landing.cards}` : '') +
+        (m.failures.length ? '\n     ' + m.failures.join('\n     ') : ''))
+      await page.close()
+    }
+  }
+} finally { await browser.close() }
+writeFileSync(`${out}/metrics.json`, JSON.stringify(results, null, 1))
+const failed = results.filter((r) => r.failures.length).length
+console.log(`${results.length} shots, ${failed} failed; metrics in ${out}/metrics.json`)
+if (failed && process.env.NO_ASSERT !== '1') process.exit(1)