@critical-labs/qa-conductor 0.0.0-stage → 0.3.0

package/lib/session.mjs

@@ -0,0 +1,250 @@
+// Session state machine + boot/teardown pipeline for PR-QA previews.
+// Pure reducer (unit-tested) + an orchestration function whose effectful
+// collaborators (the five adapters, readBaseEnv) are injected.
+
+// The two side-by-side panes. Everything else about a pane (containers,
+// ports, env files, public origins) belongs to the Provisioner or to config.
+export const ROLES = ['base', 'pr']
+
+const ACTIVE = ['ensuring-image', 'cloning', 'migrating', 'starting', 'ready', 'tearing-down']
+const STEPS = ['ensuring-image', 'cloning', 'migrating', 'starting']
+// Boot stages that run against a provisioned pane, where a log tail makes sense.
+export const PANE_STAGES = ['cloning', 'migrating', 'starting']
+
+export function createSession() {
+  return {
+    status: 'idle',
+    pr: null,
+    baseTag: null,
+    prTag: null,
+    startedAt: null,
+    lastActivity: 0,
+    error: null,
+    tokens: null,
+  }
+}
+
+export function reduce(s, event) {
+  switch (event.type) {
+    case 'open':
+      if (s.status !== 'idle' && s.status !== 'error') return s
+      return { ...createSession(), status: 'ensuring-image', pr: event.pr }
+    case 'step':
+      if (!ACTIVE.includes(s.status) || !STEPS.includes(event.step)) return s
+      return { ...s, status: event.step }
+    case 'tags':
+      return { ...s, baseTag: event.baseTag ?? s.baseTag, prTag: event.prTag ?? s.prTag }
+    case 'ready':
+      if (s.status !== 'starting') return s
+      return { ...s, status: 'ready', startedAt: event.now, lastActivity: event.now, tokens: event.tokens }
+    case 'error':
+      if (s.status === 'idle') return s
+      return { ...s, status: 'error', error: { step: event.step, message: event.message } }
+    case 'teardown':
+      if (s.status === 'idle') return s
+      return { ...s, status: 'tearing-down' }
+    case 'torn-down':
+      return createSession()
+    default:
+      return s
+  }
+}
+
+export function touch(s, now) {
+  return { ...s, lastActivity: now }
+}
+
+export function isIdle(s, now, idleMs) {
+  return s.status === 'ready' && now - s.lastActivity > idleMs
+}
+
+// --- env-file derivation --------------------------------------------------
+
+export function parseEnv(text) {
+  const out = {}
+  for (const line of text.split('\n')) {
+    const t = line.trim()
+    if (!t || t.startsWith('#')) continue
+    const i = t.indexOf('=')
+    if (i < 1) continue
+    out[t.slice(0, i)] = t.slice(i + 1)
+  }
+  return out
+}
+
+// Deriving a pane's env is app policy: it lives in the consumer's EnvTransform.
+
+export function renderEnv(env) {
+  return `${Object.entries(env).map(([k, v]) => `${k}=${v}`).join('\n')}\n`
+}
+
+// Derive the migrate companion image for an app image tag (a helper for
+// BuildConventions that publish `migrate-<tag>` images):
+//   ghcr.io/x/app:1.0.0-rc.38   -> ghcr.io/x/app:migrate-1.0.0-rc.38
+//   ghcr.io/x/app:pr-7-abc123   -> ghcr.io/x/app:migrate-pr-7-abc123
+export function migrateImageFor(appImage) {
+  const i = appImage.lastIndexOf(':')
+  return `${appImage.slice(0, i)}:migrate-${appImage.slice(i + 1)}`
+}
+
+// --- boot + teardown ------------------------------------------------------
+
+// v3 orchestrator: composes the five seams. The core owns ordering,
+// cancellation and failure cleanup; it never touches docker, the filesystem
+// or a registry. deps:
+//   adapters    — { provisioner, build, seed, envTransform, auth }
+//   env         — { operatorEmail, paneOrigins: { base, pr } }
+//   readBaseEnv? — async () => env map the pane env is derived from (homefree:
+//                  the prod stack's .env). Default: {}.
+//   onProgress, onBuild?
+//   signal?     — AbortSignal. The caller aborts it when the session is torn down
+//             or taken over. bootSession checks it between stages, between
+//             panes and before each launch, and threads it into
+//             build.ensureBuilt(pr, {signal}) and every Provisioner call
+//             (provisionDatabase, reserveServices, runMigrate, launchServices,
+//             waitHealthy) so long waits exit. Provisioners may ignore it.
+// Build progress is surfaced through build.subscribeBuild when the adapter
+// offers it; a missing hook is a no-op (the #186 pattern).
+//
+// Returns { baseTag, prTag, loginUrls, upstreams }: upstreams are each pane's
+// reserved primary-service port (`app`, else the first service), which the
+// pane proxies route to. A tag is the resolve* result's `label` when it gives
+// one, else the primary service's ref.
+//
+// A failed (not aborted) boot annotates the error before tearing down: the
+// failing pane's log tail as `err.logTail` (read while the pane still exists)
+// and its role as `err.failedRole`.
+//
+// An ABORTED boot never tears down: whoever aborted it already did, and a
+// newer session may now own the deterministic pane resources. (2026-09-25
+// incident: a stale boot stuck in ensureBuilt survived /api/teardown, then its
+// failure path destroyed the next session's containers.)
+export async function bootSession(deps, prNumber) {
+  const { adapters, env, readBaseEnv = async () => ({}), onProgress, onBuild, signal } = deps
+  const { provisioner, build, seed, envTransform, auth } = adapters
+  const checkpoint = () => {
+    if (signal?.aborted) throw Object.assign(new Error('boot aborted'), { name: 'AbortError' })
+  }
+  // Where the boot is, so a failure can name its pane and read that pane's logs.
+  let stage = null
+  let role = null
+  const enter = next => { stage = next; role = null; onProgress(next) }
+  try {
+    enter('ensuring-image')
+    if (onBuild && typeof build.subscribeBuild === 'function') build.subscribeBuild(onBuild)
+    await build.ensureBuilt(prNumber, { signal })
+    checkpoint()
+    const imagesByRole = { base: await build.resolveBaseImages(), pr: await build.resolvePrImages(prNumber) }
+
+    checkpoint()
+    enter('cloning')
+    const panes = []
+    for (const r of ROLES) {
+      checkpoint()
+      role = r
+      const ref = { role, slug: `qa-${prNumber}-${role}`, publicOrigin: env.paneOrigins[role] }
+      const { dsn, db } = await provisioner.provisionDatabase({ paneRef: ref, databases: seed.databases, signal })
+      await seed.seedPane({ paneRef: ref, db, databases: seed.databases })
+      const services = await provisioner.reserveServices({ paneRef: ref, services: imagesByRole[role].services, signal })
+      panes.push({ ref, dsn, db, services, publicOrigin: ref.publicOrigin })
+    }
+
+    checkpoint()
+    enter('migrating')
+    const prodEnv = await readBaseEnv()
+    const authEnv = typeof auth.envContributions === 'function' ? auth.envContributions() : {}
+    for (const pane of panes) {
+      role = pane.ref.role
+      pane.env = mergeEnv(envTransform.derivePaneEnv({ prodEnv, pane }), authEnv)
+      const { migrate } = imagesByRole[pane.ref.role]
+      if (build.migrationStrategy === 'one-shot-image' && migrate) {
+        if (typeof provisioner.runMigrate !== 'function') {
+          throw new Error('build uses one-shot-image migrations but the provisioner has no runMigrate')
+        }
+        await provisioner.runMigrate({ paneRef: pane.ref, migrate, env: pane.env, signal })
+      }
+    }
+
+    checkpoint()
+    enter('starting')
+    for (const pane of panes) {
+      checkpoint()
+      role = pane.ref.role
+      await provisioner.launchServices({
+        paneRef: pane.ref,
+        services: imagesByRole[pane.ref.role].services,
+        env: pane.env,
+        reserved: pane.services,
+        signal,
+      })
+    }
+    checkpoint()
+    for (const pane of panes) {
+      role = pane.ref.role
+      await provisioner.waitHealthy({ services: pane.services, signal })
+    }
+
+    checkpoint()
+    const loginUrls = {}
+    for (const pane of panes) {
+      role = pane.ref.role
+      const args = { pane, operator: env.operatorEmail, ...(auth.requiresDb ? { db: pane.db } : {}) }
+      loginUrls[pane.ref.role] = await auth.establishSession(args)
+    }
+    const upstreams = {}
+    for (const pane of panes) upstreams[pane.ref.role] = pane.services[primaryService(pane.services)]?.port ?? null
+    return { baseTag: displayTag(imagesByRole.base), prTag: displayTag(imagesByRole.pr), loginUrls, upstreams }
+  } catch (err) {
+    if (!signal?.aborted) {
+      await annotateFailure(err, { provisioner, stage, role })
+      // The log read is async (docker logs): an abort that lands during it
+      // means a newer session may own the deterministic panes now.
+      if (!signal?.aborted) await teardownSession({ provisioner }).catch(() => {})
+    }
+    throw err
+  }
+}
+
+// Attach the failing pane's log tail and role to a boot error. Runs BEFORE
+// teardown, because a Provisioner's logs usually die with its pane. An error
+// that already carries a tail (e.g. a BuildConvention's install output) keeps
+// it, and a failing logs() never masks the boot error.
+async function annotateFailure(err, { provisioner, stage, role }) {
+  if (!err || typeof err !== 'object') return
+  const wantsTail = PANE_STAGES.includes(stage) && role && typeof err.logTail !== 'string'
+  if (wantsTail && typeof provisioner.logs === 'function') {
+    try {
+      const tail = await provisioner.logs({ paneRef: { role }, stage, lines: 40 })
+      if (typeof tail === 'string') err.logTail = tail
+    } catch { /* no tail */ }
+  }
+  err.failedRole = role
+}
+
+// The service a pane's proxy fronts and whose image identifies the pane.
+function primaryService(services) {
+  return 'app' in services ? 'app' : Object.keys(services)[0]
+}
+
+// What the header and the verdict comment call a pane: the BuildConvention's
+// label when it gives one (needed when refs are paths or objects), else the
+// primary service's ref.
+function displayTag(images) {
+  if (typeof images.label === 'string' && images.label) return images.label
+  return images.services[primaryService(images.services)]
+}
+
+function mergeEnv(perService, contributions) {
+  const out = { ...perService }
+  for (const [svc, extra] of Object.entries(contributions)) out[svc] = { ...(out[svc] ?? {}), ...extra }
+  return out
+}
+
+export async function teardownSession({ provisioner }) {
+  // The Provisioner removes everything it created for each pane (containers,
+  // network, env files, managed branches); teardown is idempotent for panes
+  // that never came up.
+  for (const role of ROLES) {
+    await provisioner.teardown({ paneRef: { role } }).catch(() => {})
+  }
+}

package/lib/verdict.mjs

@@ -0,0 +1,33 @@
+// QA verdict: pure PR-comment formatter + post (comment + exclusive label).
+
+export function formatVerdict({ verdict, notes, pr, baseTag, prTag, durationMin }) {
+  const approved = verdict === 'accept'
+  const heading = approved ? '## ✅ QA approved' : '## ❌ QA changes requested'
+  const body = notes && notes.trim() ? notes : '(no notes)'
+  return [
+    '<!-- qa-conductor-verdict -->',
+    heading,
+    '',
+    `Side-by-side QA session for #${pr}.`,
+    '',
+    body,
+    '',
+    '| pane | image |',
+    '| --- | --- |',
+    `| base | \`${baseTag}\` |`,
+    `| PR | \`${prTag}\` |`,
+    '',
+    `Session: ${durationMin} min`,
+    '',
+  ].join('\n')
+}
+
+export async function postVerdict({
+  github, pr, verdict, notes, baseTag, prTag, durationMin,
+  labels = { accept: 'qa-approved', reject: 'qa-changes-requested' },
+}) {
+  const body = formatVerdict({ verdict, notes, pr, baseTag, prTag, durationMin })
+  const comment = await github.postComment(pr, body)
+  await github.setQaLabel(pr, verdict === 'accept' ? labels.accept : labels.reject)
+  return comment?.html_url
+}

package/package.json

@@ -1,6 +1,49 @@
 {
   "name": "@critical-labs/qa-conductor",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.0",
+  "description": "Side-by-side PR-QA harness: boots base-vs-PR app panes against cloned data behind mirrored proxies, with a pluggable five-seam adapter interface (Provisioner, BuildConvention, Seed, EnvTransform, AuthBootstrap) plus an optional Exposure seam.",
+  "type": "module",
+  "license": "MIT",
+  "engines": {
+    "node": ">=22"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/critical-labs/qa-conductor.git"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "files": [
+    "bin",
+    "lib",
+    "public"
+  ],
+  "bin": {
+    "qa-conductor-expose": "bin/qa-conductor-expose.mjs"
+  },
+  "exports": {
+    ".": "./lib/server.mjs",
+    "./session": "./lib/session.mjs",
+    "./config": "./lib/config.mjs",
+    "./docker": "./lib/docker.mjs",
+    "./github": "./lib/github.mjs",
+    "./identity": "./lib/identity.mjs",
+    "./exposure": "./lib/exposure.mjs",
+    "./exec": "./lib/exec.mjs",
+    "./proxy": "./lib/proxy.mjs",
+    "./verdict": "./lib/verdict.mjs",
+    "./adapters/provisioner-docker": "./lib/adapters/provisioner-docker.mjs",
+    "./adapters/build-worktree": "./lib/adapters/build-worktree.mjs",
+    "./adapters/provisioner-process": "./lib/adapters/provisioner-process.mjs",
+    "./adapters/exposure-tailscale": "./lib/adapters/exposure-tailscale.mjs",
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.mjs",
+    "demo": "node demo/server.mjs",
+    "qa": "node qa/self.mjs",
+    "expose": "node bin/qa-conductor-expose.mjs --config qa/self.mjs#loadSelfQaConfig"
+  }
+}

package/public/bridge.js

@@ -0,0 +1,324 @@
+// QA mirror bridge — injected into each pane page by the qa-conductor pane
+// proxy via <script src="/__qa/bridge.js" data-harness="<harness origin>">.
+// Plain browser script: no ESM, no dependencies, zero app changes.
+//
+// The pure helpers (buildSelector / resolveSelector) live at top level and are
+// exported through the CommonJS guard at the bottom so `node --test` can
+// exercise them; the runtime IIFE is inert outside a browser.
+
+// --- pure selector helpers -------------------------------------------------
+
+function attrEscape(value) {
+  return String(value).replace(/\\/g, '\\\\').replace(/"/g, '\\"')
+}
+
+function nthOfType(el) {
+  const siblings = el.parentNode && el.parentNode.children ? el.parentNode.children : []
+  let n = 0
+  for (let i = 0; i < siblings.length; i++) {
+    if (siblings[i].tagName === el.tagName) {
+      n += 1
+      if (siblings[i] === el) return n
+    }
+  }
+  return 1
+}
+
+function structuralPath(el) {
+  const segments = []
+  let node = el
+  while (node && node.tagName && node.tagName !== 'BODY' && node.tagName !== 'HTML') {
+    segments.unshift(node.tagName + ':nth-of-type(' + nthOfType(node) + ')')
+    node = node.parentNode
+  }
+  return segments.join('>')
+}
+
+// Selector ladder, most stable first: data-testid → id → aria-label →
+// button/link text → structural nth-of-type path from <body>. Returns a small
+// descriptor object the peer pane resolves with resolveSelector.
+function buildSelector(el) {
+  const testid = el.getAttribute('data-testid')
+  if (testid) return { t: 'testid', v: testid }
+  if (el.id) return { t: 'id', v: el.id }
+  const aria = el.getAttribute('aria-label')
+  if (aria) return { t: 'aria', v: aria }
+  if (el.tagName === 'BUTTON' || el.tagName === 'A') {
+    const text = (el.textContent || '').trim()
+    if (text.length >= 1 && text.length <= 60 && textIsUnique(el, text)) return { t: 'text', tag: el.tagName, v: text }
+  }
+  return { t: 'path', v: structuralPath(el) }
+}
+
+// Text only identifies an element when no other same-tag element on the page
+// carries it: the peer resolves an ambiguous text match to nothing, so a
+// repeated label ("Open", "Edit", one per row) must fall through to the path.
+function textIsUnique(el, text) {
+  let root = el
+  while (root.parentNode) root = root.parentNode
+  const same = collectByTag(root, el.tagName, [])
+  let count = 0
+  for (let i = 0; i < same.length; i++) {
+    if ((same[i].textContent || '').trim() === text) count += 1
+  }
+  return count === 1
+}
+
+function collectByTag(root, tag, out) {
+  const kids = root && root.children ? root.children : []
+  for (let i = 0; i < kids.length; i++) {
+    if (kids[i].tagName === tag) out.push(kids[i])
+    collectByTag(kids[i], tag, out)
+  }
+  return out
+}
+
+function nthChildOfType(parent, tag, n) {
+  const kids = parent && parent.children ? parent.children : []
+  let seen = 0
+  for (let i = 0; i < kids.length; i++) {
+    if (kids[i].tagName === tag) {
+      seen += 1
+      if (seen === n) return kids[i]
+    }
+  }
+  return null
+}
+
+// Resolve a descriptor against a document. Returns the element, or null when
+// it does not match exactly one element — "where UI matches" is literal, so an
+// ambiguous text match is a non-match.
+function resolveSelector(desc, doc) {
+  if (!desc || !doc) return null
+  if (desc.t === 'testid') return doc.querySelector('[data-testid="' + attrEscape(desc.v) + '"]') || null
+  if (desc.t === 'id') return doc.querySelector('[id="' + attrEscape(desc.v) + '"]') || null
+  if (desc.t === 'aria') return doc.querySelector('[aria-label="' + attrEscape(desc.v) + '"]') || null
+  if (desc.t === 'text') {
+    const candidates = collectByTag(doc.body, desc.tag, [])
+    const matches = []
+    for (let i = 0; i < candidates.length; i++) {
+      if ((candidates[i].textContent || '').trim() === desc.v) matches.push(candidates[i])
+    }
+    return matches.length === 1 ? matches[0] : null
+  }
+  if (desc.t === 'path') {
+    if (typeof desc.v !== 'string') return null
+    if (desc.v === '') return doc.body || null
+    let node = doc.body
+    const segments = desc.v.split('>')
+    for (let i = 0; i < segments.length; i++) {
+      const m = /^([A-Za-z0-9-]+):nth-of-type\((\d+)\)$/.exec(segments[i])
+      if (!m || !node) return null
+      node = nthChildOfType(node, m[1], Number(m[2]))
+    }
+    return node || null
+  }
+  return null
+}
+
+// --- browser runtime -------------------------------------------------------
+
+;(function () {
+  if (typeof window === 'undefined' || typeof document === 'undefined') return
+  if (window.__qaBridgeInstalled) return
+  window.__qaBridgeInstalled = true
+
+  // The harness origin comes from the pane proxy, on the tag that loaded this
+  // script (data-harness), never from the page URL: whoever frames or opens a
+  // pane chooses its URL. Without it the bridge neither sends nor replays.
+  const script = document.currentScript
+  const harnessOrigin = (script && script.dataset && script.dataset.harness) || null
+
+  // Only the harness, as this pane's parent frame, may drive or hear it. A
+  // top-level window (the harness's "Open in new tab") never mirrors.
+  function framedByHarness() {
+    return !!harnessOrigin && window.parent !== window
+  }
+
+  function send(msg) {
+    if (!framedByHarness()) return
+    try {
+      // targetOrigin, not '*': a parent on any other origin never receives
+      // it, so nav paths, captured values and unmatched replies stay with the
+      // harness
+      window.parent.postMessage(msg, harnessOrigin)
+    } catch (err) {
+      // parent gone, or a malformed origin (SyntaxError) — nothing to mirror to
+    }
+  }
+
+  // Heartbeat: a lightweight liveness ping so the harness can tell a live pane
+  // from a crashed or navigated-away one. Reuses send() for its postMessage +
+  // try/catch; independent of the capture/replay paths.
+  setInterval(function () {
+    send({ qa: 1, kind: 'ping' })
+  }, 5000)
+
+  function valueOf(el) {
+    const tag = el.tagName
+    if (tag === 'INPUT') {
+      if (el.type === 'checkbox' || el.type === 'radio') return el.checked
+      return el.value
+    }
+    if (tag === 'TEXTAREA' || tag === 'SELECT') return el.value
+    return undefined
+  }
+
+  // --- capture side ---------------------------------------------------------
+
+  const MIRRORED_KEYS = ['Enter', 'Escape', 'Tab']
+
+  function onCaptured(event) {
+    if (window.__qaReplaying) return
+    const target = event.target
+    if (!target || !target.tagName) return
+    // File pickers cannot be mirrored (browser security) — do those per-pane.
+    if (target.tagName === 'INPUT' && target.type === 'file') return
+    if (event.type === 'keydown' && MIRRORED_KEYS.indexOf(event.key) === -1) return
+    const msg = { qa: 1, kind: 'event', type: event.type, selector: buildSelector(target) }
+    if (event.type === 'keydown') msg.key = event.key
+    const value = valueOf(target)
+    if (value !== undefined) msg.value = value
+    send(msg)
+  }
+
+  const MIRRORED_EVENTS = ['click', 'dblclick', 'input', 'change', 'submit', 'keydown']
+  for (let i = 0; i < MIRRORED_EVENTS.length; i++) {
+    document.addEventListener(MIRRORED_EVENTS[i], onCaptured, true)
+  }
+
+  // Page scroll, coalesced to one message per animation frame (smooth, near
+  // real-time tracking rather than a 150 ms lurch). Each message carries both
+  // the absolute offset and the fraction of the scrollable extent plus that
+  // extent, so the receiver can hold the panes proportionally aligned when the
+  // two documents have different heights (base vs PR diff). A replayed scrollTo
+  // fires its own scroll event asynchronously, so capture is suppressed briefly
+  // after a replay to avoid echo loops.
+  function scrollMetrics() {
+    const de = document.documentElement
+    const maxX = Math.max(1, de.scrollWidth - de.clientWidth)
+    const maxY = Math.max(1, de.scrollHeight - de.clientHeight)
+    return { x: window.scrollX, y: window.scrollY, fx: window.scrollX / maxX, fy: window.scrollY / maxY, maxX: maxX, maxY: maxY }
+  }
+  let scrollScheduled = false
+  let suppressScrollUntil = 0
+  document.addEventListener('scroll', function (event) {
+    if (window.__qaReplaying || Date.now() < suppressScrollUntil) return
+    if (event.target !== document && event.target !== document.documentElement) return
+    if (scrollScheduled) return
+    scrollScheduled = true
+    requestAnimationFrame(function () {
+      scrollScheduled = false
+      if (window.__qaReplaying || Date.now() < suppressScrollUntil) return
+      const m = scrollMetrics()
+      send({ qa: 1, kind: 'event', type: 'scroll', scroll: [m.x, m.y], frac: [m.fx, m.fy], ext: [m.maxX, m.maxY] })
+    })
+  }, true)
+
+  // --- replay side ----------------------------------------------------------
+
+  function applyValue(el, value) {
+    const tag = el.tagName
+    if (tag === 'INPUT' && (el.type === 'checkbox' || el.type === 'radio')) {
+      el.checked = !!value
+      el.dispatchEvent(new Event('change', { bubbles: true }))
+      return
+    }
+    if (tag === 'SELECT') {
+      el.value = value
+      el.dispatchEvent(new Event('change', { bubbles: true }))
+      return
+    }
+    if (tag === 'INPUT' || tag === 'TEXTAREA') {
+      // React tracks the value property descriptor, so go through the native
+      // prototype setter to make controlled components observe the change.
+      const proto = tag === 'INPUT' ? window.HTMLInputElement.prototype : window.HTMLTextAreaElement.prototype
+      const desc = Object.getOwnPropertyDescriptor(proto, 'value')
+      if (desc && desc.set) desc.set.call(el, value)
+      else el.value = value
+      el.dispatchEvent(new Event('input', { bubbles: true }))
+      el.dispatchEvent(new Event('change', { bubbles: true }))
+    }
+  }
+
+  function replay(data) {
+    if (data.type === 'scroll') {
+      if (Array.isArray(data.scroll)) {
+        suppressScrollUntil = Date.now() + 200
+        const de = document.documentElement
+        const myMaxX = Math.max(1, de.scrollWidth - de.clientWidth)
+        const myMaxY = Math.max(1, de.scrollHeight - de.clientHeight)
+        let x = data.scroll[0]
+        let y = data.scroll[1]
+        // When this pane's scrollable extent differs materially from the
+        // sender's, follow the proportional position instead of the raw pixel
+        // offset so the same region stays visible in both panes.
+        if (data.ext && data.frac) {
+          if (Math.abs(data.ext[1] - myMaxY) > 4) y = Math.round(data.frac[1] * myMaxY)
+          if (Math.abs(data.ext[0] - myMaxX) > 4) x = Math.round(data.frac[0] * myMaxX)
+        }
+        window.scrollTo(x, y)
+      }
+      return
+    }
+    const el = resolveSelector(data.selector, document)
+    if (!el) {
+      send({ qa: 1, kind: 'unmatched', type: data.type })
+      return
+    }
+    if (data.type === 'click' || data.type === 'dblclick') {
+      el.click()
+      return
+    }
+    if (data.type === 'keydown') {
+      el.dispatchEvent(new KeyboardEvent('keydown', { key: data.key, bubbles: true, cancelable: true }))
+      return
+    }
+    if (data.type === 'input' || data.type === 'change') {
+      applyValue(el, data.value)
+    }
+    // 'submit' is captured for the harness but deliberately not replayed: the
+    // mirrored click that raised it already drives the peer's own submit path,
+    // and replaying it as well would double-submit.
+  }
+
+  window.addEventListener('message', function (event) {
+    if (!framedByHarness() || event.source !== window.parent || event.origin !== harnessOrigin) return
+    const data = event.data
+    if (!data || data.qa !== 1 || data.kind !== 'replay') return
+    window.__qaReplaying = true
+    try {
+      replay(data)
+    } finally {
+      window.__qaReplaying = false
+    }
+  })
+
+  // --- navigation notifications --------------------------------------------
+  // The harness only uses these for its per-pane URL indicators.
+
+  function sendNav() {
+    send({ qa: 1, kind: 'nav', href: window.location.pathname + window.location.search })
+  }
+
+  const originalPushState = window.history.pushState
+  window.history.pushState = function () {
+    const result = originalPushState.apply(this, arguments)
+    sendNav()
+    return result
+  }
+  const originalReplaceState = window.history.replaceState
+  window.history.replaceState = function () {
+    const result = originalReplaceState.apply(this, arguments)
+    sendNav()
+    return result
+  }
+  window.addEventListener('popstate', sendNav)
+  sendNav()
+})()
+
+// --- test exports (node --test evaluates this file through a CJS wrapper) ---
+
+if (typeof module !== 'undefined' && module.exports) {
+  module.exports = { buildSelector, resolveSelector }
+}