docs: make the perf record reproducible and its comparison honest

Three corrections from review:

- The scripts lived under temp/, which is gitignored, so the reproduction
  section could not be run by anyone including a later me. They are in
  scripts/perf/ now, with the commands updated to match.
- The litegraph column is that renderer before this work. The minimap fix
  is renderer-independent and sped it up too, so main's canvas renderer
  is now faster than every number in it and the ratios read better than
  they should. Says so explicitly, with the post-change numbers.
- p95 is collected and was not reported, while the repo's own render gate
  is set on p95 rather than median - which is exactly where fill-in and
  allocation costs show up.

Author: benjcooley

docs/architecture/vue-nodes-large-graph-performance.md

@@ -21,8 +21,13 @@ before any of this work, and is the bar Vue nodes needed to clear.
 |  3000 | min  |   41.6 ms |   280.5 ms |   34.3 ms |        0.82x |    8.2x |
 |  3000 | fit  |  126.5 ms |   380.7 ms |  104.0 ms |        0.82x |    3.7x |
 
-Vue nodes now match or beat the original canvas-renderer baseline in five of
-six configurations. DOM element counts on the 3000-node graph fell from 227,787
+The `litegraph` column is that renderer _before this work_, which is the bar
+Vue nodes had to clear - but it is not the bar after merge. The minimap fix is
+renderer-independent and speeds the canvas renderer up too, so main's canvas
+renderer is now faster than every number in that column. Measured after the
+change, the two renderers at 3000 nodes zoomed out are 104ms and 113ms, i.e.
+about 0.92x rather than the 0.82x the table implies. Read the ratios as "versus
+the problem we started from", not "versus main today". DOM element counts on the 3000-node graph fell from 227,787
 to 5,355 at working zoom and to 418 (application chrome only) when zoomed out.
 
 `min` is the lowest zoom reachable by scrolling (0.1). `fit` is the zoom a
@@ -112,6 +117,11 @@ below the threshold that measurement never arrived and links stayed hidden.
 Crossing into the simplified mode now releases that wait, and links fall back
 to positions derived from node bounds.
 
+p95 is reported alongside the median throughout, because the repo's own render
+gate (`docs/architecture/ecs-migration-plan.md`, referenced by ADR 0008) is set
+on p95 rather than median - and because per-frame allocation and fill-in cost
+show up in the tail while leaving the median flat.
+
 ## Method
 
 Graphs are built by stamping the default workflow across empty space in a grid,
@@ -121,13 +131,22 @@ driving a continuous pan, reporting the median and p95 of the stable portion.
 Both renderers are measured in the same build, on the same workflow, with a
 fresh page each.
 
-Scripts live under `temp/scripts/` (untracked):
+Scripts live under `scripts/perf/`. They were untracked under `temp/` in an
+earlier revision, which made this section unreproducible for anyone including
+a later me, since `/temp/` is gitignored:
 
 ```bash
-node temp/scripts/gen-big-graph.mjs 3000        # build a workflow
-LABEL=my-run node temp/scripts/sweep.mjs        # measure both renderers
-node temp/scripts/build-report.mjs              # render temp/perf-report.html
-SCALE=0.0255 node temp/scripts/profile-pan.mjs temp/big-graph-3000.json
+# Build a workflow of a given size
+node scripts/perf/gen-sized-workflow.mjs 3000 /tmp/wf-3000.json
+
+# Pan cost, both renderers, with the culling threshold swept
+node scripts/perf/sweep-threshold.mjs
+
+# Zoom cost, both renderers
+WORKFLOW=/tmp/wf-3000.json node scripts/perf/measure-zoom.mjs
+
+# Mounted-element counts while panning
+node scripts/perf/measure-culling.mjs
 ```
 
 Caveat: one sample per configuration, with run-to-run variance measured at

scripts/perf/gen-sized-workflow.mjs

@@ -0,0 +1,56 @@
+/** Builds a workflow of exactly N nodes by tiling the default fixture. */
+import { readFileSync, writeFileSync } from 'node:fs'
+const SRC = JSON.parse(
+  readFileSync('browser_tests/assets/large-graph-workflow.json', 'utf8')
+)
+const N = Number(process.argv[2])
+const out = { ...SRC, nodes: [], links: [], groups: [] }
+const COLS = 6,
+  TILE_W = 2600,
+  TILE_H = 2200
+let copy = 0
+while (out.nodes.length < N) {
+  const nodeOffset = copy * (SRC.last_node_id + 1)
+  const linkOffset = copy * (SRC.last_link_id + 1)
+  const dx = (copy % COLS) * TILE_W,
+    dy = Math.floor(copy / COLS) * TILE_H
+  const keep = new Set()
+  for (const node of SRC.nodes) {
+    if (out.nodes.length >= N) break
+    const c = structuredClone(node)
+    c.id = node.id + nodeOffset
+    c.pos = [node.pos[0] + dx, node.pos[1] + dy]
+    for (const i of c.inputs ?? []) if (i.link != null) i.link += linkOffset
+    for (const o of c.outputs ?? [])
+      if (o.links) o.links = o.links.map((l) => l + linkOffset)
+    out.nodes.push(c)
+    keep.add(c.id)
+  }
+  for (const l of SRC.links ?? []) {
+    const [id, oid, os, tid, ts, ty] = l
+    if (keep.has(oid + nodeOffset) && keep.has(tid + nodeOffset))
+      out.links.push([
+        id + linkOffset,
+        oid + nodeOffset,
+        os,
+        tid + nodeOffset,
+        ts,
+        ty
+      ])
+  }
+  copy++
+}
+// Drop dangling input links so the graph stays consistent.
+const linkIds = new Set(out.links.map((l) => l[0]))
+for (const n of out.nodes) {
+  for (const i of n.inputs ?? [])
+    if (i.link != null && !linkIds.has(i.link)) i.link = null
+  for (const o of n.outputs ?? [])
+    if (o.links) o.links = o.links.filter((l) => linkIds.has(l))
+}
+out.last_node_id = copy * (SRC.last_node_id + 1)
+out.last_link_id = copy * (SRC.last_link_id + 1)
+writeFileSync(process.argv[3], JSON.stringify(out))
+console.log(
+  `${process.argv[3]}: ${out.nodes.length} nodes, ${out.links.length} links`
+)

scripts/perf/measure-culling.mjs

@@ -0,0 +1,116 @@
+/**
+ * Measures how many Vue node elements are actually in the DOM for a large
+ * workflow, at default zoom and while panning.
+ *
+ * Usage: node temp/scripts/measure-culling.mjs
+ */
+import { readFileSync } from 'node:fs'
+import { chromium } from '@playwright/test'
+
+const APP_URL = process.env.APP_URL ?? 'http://localhost:5173'
+const WORKFLOW = JSON.parse(
+  readFileSync('browser_tests/assets/large-graph-workflow.json', 'utf8')
+)
+
+const countNodes = () => document.querySelectorAll('[data-node-id]').length
+
+const browser = await chromium.launch()
+const page = await browser.newPage({ viewport: { width: 1280, height: 900 } })
+
+page.on('pageerror', (e) => console.log('PAGE ERROR:', e.message))
+
+await page.goto(APP_URL, { waitUntil: 'domcontentloaded' })
+await page.waitForFunction(() => window.app?.canvas != null, {
+  timeout: 60_000
+})
+
+await page.evaluate(async (workflow) => {
+  await window.app.loadGraphData(workflow)
+}, WORKFLOW)
+
+await page.waitForFunction(
+  () => document.querySelectorAll('[data-node-id]').length > 0,
+  { timeout: 60_000 }
+)
+await page.waitForTimeout(2500)
+
+const totalNodes = await page.evaluate(() => window.app.graph._nodes.length)
+const atDefaultZoom = await page.evaluate(countNodes)
+
+// Pan continuously across the graph, sampling the mounted count as we go.
+const readCamera = () => {
+  const ds = window.app.canvas.ds
+  return {
+    x: Math.round(ds.offset[0]),
+    y: Math.round(ds.offset[1]),
+    z: ds.scale
+  }
+}
+
+const cameraBefore = await page.evaluate(readCamera)
+
+// Pan by driving the canvas transform directly, so the measurement does not
+// depend on which mouse button happens to be bound to panning.
+const samples = []
+for (let step = 1; step <= 6; step++) {
+  await page.evaluate((dx) => {
+    window.app.canvas.ds.offset[0] -= dx
+    window.app.canvas.setDirty(true, true)
+  }, 900)
+  await page.waitForTimeout(160)
+  samples.push(await page.evaluate(countNodes))
+}
+
+const cameraAfter = await page.evaluate(readCamera)
+await page.waitForTimeout(600)
+const afterPan = await page.evaluate(countNodes)
+
+// Continuously pan inside a rAF loop and record frame deltas.
+const frames = await page.evaluate(async () => {
+  const ds = window.app.canvas.ds
+  ds.offset[0] = 0
+  const deltas = []
+
+  await new Promise((resolve) => {
+    let last = performance.now()
+    let i = 0
+    const tick = () => {
+      const now = performance.now()
+      deltas.push(now - last)
+      last = now
+      ds.offset[0] -= 40
+      window.app.canvas.setDirty(true, true)
+      if (++i >= 150) return resolve()
+      requestAnimationFrame(tick)
+    }
+    requestAnimationFrame(tick)
+  })
+
+  // Drop the first few frames while the pan spins up.
+  const stable = deltas.slice(10).sort((a, b) => a - b)
+  const at = (q) => stable[Math.floor(stable.length * q)]
+  return {
+    medianFrameMs: +at(0.5).toFixed(1),
+    p95FrameMs: +at(0.95).toFixed(1),
+    worstFrameMs: +stable[stable.length - 1].toFixed(1)
+  }
+})
+
+console.log(
+  JSON.stringify(
+    {
+      totalNodes,
+      atDefaultZoom,
+      cameraBefore,
+      cameraAfter,
+      duringPan: samples,
+      peakDuringPan: Math.max(...samples),
+      afterPanSettled: afterPan,
+      frames
+    },
+    null,
+    2
+  )
+)
+
+await browser.close()

scripts/perf/measure-zoom.mjs

@@ -0,0 +1,91 @@
+/** Frame cost of a continuous wheel zoom in/out, Vue vs legacy. */
+import { readFileSync } from 'node:fs'
+import { chromium } from '@playwright/test'
+const W = JSON.parse(
+  readFileSync(process.env.WORKFLOW ?? 'temp/huge-workflow.json', 'utf8')
+)
+const browser = await chromium.launch()
+
+async function run(vueNodes) {
+  const p = await browser.newPage({ viewport: { width: 1440, height: 900 } })
+  await p.goto('http://localhost:5173', { waitUntil: 'domcontentloaded' })
+  await p.waitForFunction(() => window.app?.canvas != null, { timeout: 60000 })
+  await p.evaluate(async (v) => {
+    const s = window.app.extensionManager.setting
+    await s.set('Comfy.VueNodes.Enabled', v)
+    await s.set('Comfy.Minimap.Visible', true)
+  }, vueNodes)
+  await p.reload({ waitUntil: 'domcontentloaded' })
+  await p.waitForFunction(() => window.app?.canvas != null, { timeout: 60000 })
+  await p.evaluate(async (w) => window.app.loadGraphData(w), W)
+  await p.waitForTimeout(8000)
+
+  // Start at a working zoom centred on the graph.
+  await p.evaluate(() => {
+    const ds = window.app.canvas.ds,
+      ns = window.app.graph._nodes
+    const cx = ns.reduce((a, n) => a + n.pos[0], 0) / ns.length
+    const cy = ns.reduce((a, n) => a + n.pos[1], 0) / ns.length
+    ds.scale = 0.6
+    ds.offset[0] = -cx + window.innerWidth / 2 / 0.6
+    ds.offset[1] = -cy + window.innerHeight / 2 / 0.6
+    window.app.canvas.setDirty(true, true)
+  })
+  await p.waitForTimeout(3000)
+
+  const stats = await p.evaluate(async () => {
+    const canvas = window.app.canvas
+    const deltas = []
+    const samples = []
+    const el = canvas.canvas
+    const fire = (dy) =>
+      el.dispatchEvent(
+        new WheelEvent('wheel', {
+          deltaY: dy,
+          clientX: window.innerWidth / 2,
+          clientY: window.innerHeight / 2,
+          bubbles: true,
+          cancelable: true
+        })
+      )
+    await new Promise((resolve) => {
+      let last = performance.now(),
+        i = 0
+      const tick = () => {
+        const now = performance.now()
+        deltas.push(now - last)
+        last = now
+        // 60 out then 60 back in
+        fire(i < 60 ? 120 : -120)
+        if (i % 10 === 0)
+          samples.push({
+            i,
+            scale: +canvas.ds.scale.toFixed(3),
+            dom: document.querySelectorAll('[data-node-id]').length,
+            ms: +deltas[deltas.length - 1].toFixed(0)
+          })
+        if (++i >= 120) return resolve()
+        requestAnimationFrame(tick)
+      }
+      requestAnimationFrame(tick)
+    })
+    window.__samples = samples
+    const s = deltas.slice(10).sort((a, b) => a - b)
+    const at = (q) => +s[Math.floor(s.length * q)].toFixed(1)
+    return {
+      median: at(0.5),
+      p95: at(0.95),
+      worst: +s[s.length - 1].toFixed(1),
+      finalScale: +canvas.ds.scale.toFixed(3),
+      domNodes: document.querySelectorAll('[data-node-id]').length,
+      samples
+    }
+  })
+  await p.close()
+  return stats
+}
+
+const legacy = await run(false)
+const vue = await run(true)
+console.log(JSON.stringify({ legacy, vue }, null, 2))
+await browser.close()