@sorb/seed 0.1.0 → 0.2.0

package/src/render/pagePool.js

@@ -0,0 +1,82 @@
+// E3 — Playwright page lifecycle for the render worker.
+//
+// Reuses the SAME lazy-Playwright-import pattern as captureCli.js's
+// loadChromium: `playwright` is an optional peer dep, so importing it must
+// never happen at module-load time — only when a render is actually requested.
+// This file is the ONLY place worker.js touches Playwright directly, so
+// worker.js (and its tests) can import cleanly without the package installed.
+//
+// Page reuse (the "skip navigation" half of the diff-only optimization): one
+// browser context is kept alive for the pool's lifetime, and one page per URL
+// is kept open across calls — so a second render() for a URL we've already
+// visited skips `page.goto` (the dominant chunk of the measured ~1.75s/render,
+// per hosted-bridge-modes-exploration-plan.md E0) and only re-injects the token
+// map + recaptures. Callers that want a fresh navigation (e.g. the app itself
+// changed) should call `pool.evict(url)` first.
+
+const loadChromium = async () => {
+  const { chromium } = await import('playwright')
+  return chromium
+}
+
+/**
+ * @typedef {object} PagePool
+ * @property {(url: string, viewport?: {width:number,height:number}) => Promise<{page: object, reused: boolean}>} acquire
+ * @property {(url: string) => Promise<void>} evict
+ * @property {() => Promise<void>} closeAll
+ */
+
+/**
+ * Create a real, Playwright-backed page pool. Lazily launches the browser on
+ * the first `acquire()` call.
+ * @returns {PagePool}
+ */
+export function createPagePool() {
+  /** @type {import('playwright').Browser|null} */
+  let browser = null
+  /** @type {import('playwright').BrowserContext|null} */
+  let ctx = null
+  /** @type {Map<string, import('playwright').Page>} */
+  const pages = new Map()
+
+  const ensureBrowser = async () => {
+    if (browser) return
+    const chromium = await loadChromium()
+    browser = await chromium.launch()
+    ctx = await browser.newContext()
+  }
+
+  return {
+    async acquire(url, viewport = { width: 1280, height: 800 }) {
+      await ensureBrowser()
+      const existing = pages.get(url)
+      if (existing) {
+        await existing.setViewportSize(viewport)
+        return { page: existing, reused: true }
+      }
+      const page = await ctx.newPage()
+      await page.setViewportSize(viewport)
+      await page.goto(url, { waitUntil: 'load' })
+      await page.waitForLoadState('networkidle', { timeout: 15000 }).catch(() => {})
+      pages.set(url, page)
+      return { page, reused: false }
+    },
+
+    async evict(url) {
+      const page = pages.get(url)
+      if (page) {
+        await page.close().catch(() => {})
+        pages.delete(url)
+      }
+    },
+
+    async closeAll() {
+      for (const page of pages.values()) await page.close().catch(() => {})
+      pages.clear()
+      if (ctx) await ctx.close().catch(() => {})
+      if (browser) await browser.close().catch(() => {})
+      browser = null
+      ctx = null
+    },
+  }
+}

package/src/render/pagePool.test.js

@@ -0,0 +1,23 @@
+// pagePool.js touches Playwright lazily (only inside acquire()); these tests
+// only cover the laziness/shape contract — they never call acquire(), so they
+// never launch a real browser and pass whether or not Playwright is installed.
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { createPagePool } from './pagePool.js'
+
+test('createPagePool: returns a pool without importing/launching Playwright', () => {
+  const pool = createPagePool()
+  assert.equal(typeof pool.acquire, 'function')
+  assert.equal(typeof pool.evict, 'function')
+  assert.equal(typeof pool.closeAll, 'function')
+})
+
+test('createPagePool: closeAll on a never-used pool is a safe no-op', async () => {
+  const pool = createPagePool()
+  await pool.closeAll() // must not throw even though nothing was ever acquired
+})
+
+test('createPagePool: evict on a url that was never acquired is a safe no-op', async () => {
+  const pool = createPagePool()
+  await pool.evict('https://never-acquired.example')
+})

package/src/render/tokenInject.js

@@ -0,0 +1,53 @@
+// E3 — token-map injection + conformance snapshot.
+//
+// Mode B's input is an app URL + a token map (cssVar -> proposed value,
+// possibly one of several viewports — the caller runs renderJob once per
+// viewport). We inject the map as CSS custom properties on :root (the same
+// mechanism `@sorb/leaf`'s SorbProvider uses at runtime — `var(--token,
+// fallback)`), then read back what the page actually resolved so the caller
+// gets a conformance snapshot, not just a rendered picture.
+
+/**
+ * Set each `tokenMap` entry as a CSS custom property on `document.documentElement`.
+ * @param {{evaluate: Function}} page a Playwright Page (or a test double with the same shape)
+ * @param {Object.<string,string>} tokenMap cssVar name -> value
+ */
+export async function injectTokenMap(page, tokenMap) {
+  await page.evaluate((map) => {
+    const root = document.documentElement
+    for (const key of Object.keys(map)) root.style.setProperty(key, map[key])
+  }, tokenMap)
+}
+
+/**
+ * Read back the RESOLVED (computed) value of each cssVar from `:root`.
+ * @param {{evaluate: Function}} page
+ * @param {string[]} varNames
+ * @returns {Promise<Object.<string,string>>} cssVar -> resolved value (raw string, trimmed)
+ */
+export async function readResolvedVars(page, varNames) {
+  if (!varNames.length) return {}
+  return page.evaluate((names) => {
+    const cs = getComputedStyle(document.documentElement)
+    const out = {}
+    for (const name of names) out[name] = cs.getPropertyValue(name).trim()
+    return out
+  }, varNames)
+}
+
+/**
+ * Compare the requested token map against what actually resolved in-page.
+ * @param {Object.<string,string>} tokenMap requested cssVar -> value
+ * @param {Object.<string,string>} resolvedVars actual cssVar -> resolved value
+ * @returns {{rows: Array<{cssVar:string,expected:string,actual:string,match:boolean}>, conformant: boolean, mismatchCount: number}}
+ */
+export function buildConformance(tokenMap, resolvedVars) {
+  const rows = Object.keys(tokenMap).map((cssVar) => {
+    const expected = String(tokenMap[cssVar]).trim()
+    const actualRaw = resolvedVars ? resolvedVars[cssVar] : undefined
+    const actual = actualRaw == null ? '' : String(actualRaw).trim()
+    return { cssVar, expected, actual, match: expected === actual }
+  })
+  const mismatchCount = rows.filter((r) => !r.match).length
+  return { rows, conformant: mismatchCount === 0, mismatchCount }
+}

package/src/render/tokenInject.test.js

@@ -0,0 +1,59 @@
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { injectTokenMap, readResolvedVars, buildConformance } from './tokenInject.js'
+
+// ─── buildConformance (pure) ─────────────────────────────────────────────────
+test('buildConformance: all match → conformant true, no mismatches', () => {
+  const snap = buildConformance(
+    { '--sorb-color-bg': '#fff', '--sorb-radius': '4px' },
+    { '--sorb-color-bg': '#fff', '--sorb-radius': '4px' },
+  )
+  assert.equal(snap.conformant, true)
+  assert.equal(snap.mismatchCount, 0)
+  assert.equal(snap.rows.length, 2)
+  assert.ok(snap.rows.every((r) => r.match))
+})
+
+test('buildConformance: a resolved value differing from requested is a mismatch', () => {
+  const snap = buildConformance({ '--x': '4px' }, { '--x': '8px' })
+  assert.equal(snap.conformant, false)
+  assert.equal(snap.mismatchCount, 1)
+  assert.deepEqual(snap.rows[0], { cssVar: '--x', expected: '4px', actual: '8px', match: false })
+})
+
+test('buildConformance: a missing resolved var counts as a mismatch (actual = "")', () => {
+  const snap = buildConformance({ '--x': '4px' }, {})
+  assert.equal(snap.mismatchCount, 1)
+  assert.equal(snap.rows[0].actual, '')
+})
+
+test('buildConformance: whitespace is trimmed before comparing', () => {
+  const snap = buildConformance({ '--x': ' 4px ' }, { '--x': '4px' })
+  assert.equal(snap.rows[0].match, true)
+})
+
+// ─── injectTokenMap / readResolvedVars (thin page.evaluate wrappers) ────────
+test('injectTokenMap: calls page.evaluate once with the token map as the arg', async () => {
+  const calls = []
+  const page = { evaluate: async (fn, arg) => calls.push({ fn, arg }) }
+  await injectTokenMap(page, { '--x': '1px' })
+  assert.equal(calls.length, 1)
+  assert.equal(typeof calls[0].fn, 'function')
+  assert.deepEqual(calls[0].arg, { '--x': '1px' })
+})
+
+test('readResolvedVars: passes the var names through and returns page.evaluate result', async () => {
+  const page = {
+    evaluate: async (fn, names) => Object.fromEntries(names.map((n) => [n, 'resolved:' + n])),
+  }
+  const out = await readResolvedVars(page, ['--a', '--b'])
+  assert.deepEqual(out, { '--a': 'resolved:--a', '--b': 'resolved:--b' })
+})
+
+test('readResolvedVars: short-circuits to {} for an empty var list (no page.evaluate call)', async () => {
+  let called = false
+  const page = { evaluate: async () => { called = true } }
+  const out = await readResolvedVars(page, [])
+  assert.deepEqual(out, {})
+  assert.equal(called, false)
+})

package/src/render/walkerBundle.js

@@ -0,0 +1,24 @@
+// Bundles the SAME in-page walker `capture.js` uses (captureRoot →
+// `window.__sorbCapture`) into a single IIFE string, exactly like
+// captureCli.js's private `buildWalkerBundle` and the cloud's
+// runnerEntry.mjs. Factored out here so the render worker can inject it into
+// an arbitrary app page (not just a Storybook iframe) without duplicating the
+// walker itself — only the bundling call is repeated, the capture ALGORITHM
+// (capture.js) is the single shared source.
+import { build } from 'esbuild'
+import { dirname, resolve } from 'node:path'
+
+/** @returns {Promise<string>} an IIFE that installs `window.__sorbCapture`. */
+export const buildWalkerBundle = async () => {
+  const here = dirname(new URL(import.meta.url).pathname)
+  const out = await build({
+    entryPoints: [resolve(here, '../capture.js')],
+    bundle: true,
+    format: 'iife',
+    platform: 'browser',
+    write: false,
+    logLevel: 'silent',
+    target: 'es2020',
+  })
+  return out.outputFiles[0].text
+}

package/src/render/walkerBundle.test.js

@@ -0,0 +1,12 @@
+// esbuild-only (no Playwright/browser needed) — proves the render worker
+// bundles the SAME walker capture.js/captureCli.js already use.
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { buildWalkerBundle } from './walkerBundle.js'
+
+test('buildWalkerBundle: produces an IIFE that installs window.__sorbCapture', async () => {
+  const bundle = await buildWalkerBundle()
+  assert.equal(typeof bundle, 'string')
+  assert.ok(bundle.includes('__sorbCapture'))
+  assert.ok(bundle.length > 0)
+})

package/src/render/worker.js

@@ -0,0 +1,193 @@
+// E3 — hosted-capture render worker (Mode B).
+// hosted-bridge-modes-exploration-plan.md §3 E3.
+//
+// Wraps the EXISTING sorb-seed Playwright capture machinery as a single-job,
+// on-demand render: given an app URL + a token map, navigate, inject the
+// tokens as CSS custom properties, and capture a screenshot + the rendered DOM
+// (via the SAME walker `capture.js`/`captureCli.js` already use) + a
+// conformance snapshot. This is deliberately generic-URL, not Storybook-only
+// (Mode B's reachable target class per E0 is public Storybook/DS-docs/staging
+// URLs, but the walker itself works against any rendered page — Storybook is
+// just where E0 found "public and reachable" apps living).
+//
+// Target class / auth wall (per E0, do not build here): only public URLs are
+// supported. There is no credential-handling path — an auth-walled URL will
+// simply fail to render the real app (login page instead), which is the
+// documented, deferred follow-up, not a bug to fix in this phase.
+//
+// Playwright stays OPTIONAL and LAZY: this module never imports `playwright`
+// itself. It only reaches Playwright through `pagePool.js`'s `createPagePool`,
+// which is dynamically imported on first use — so `renderJob` (and this whole
+// module) import cleanly with Playwright absent, and only throw (with the same
+// actionable message as `captureCli.js`) once a render actually happens.
+
+import { writeFile } from 'node:fs/promises'
+import { randomUUID } from 'node:crypto'
+import { resolve } from 'node:path'
+import { tmpdir } from 'node:os'
+
+import { injectTokenMap, readResolvedVars, buildConformance } from './tokenInject.js'
+import { DiffCache, makeCacheKey } from './diffCache.js'
+
+/**
+ * @typedef {Object.<string,string>} TokenMap cssVar -> value
+ *
+ * @typedef {object} RenderJobInput
+ * @property {string} url app URL to render (public/staging — see module doc)
+ * @property {TokenMap} [tokenMap] cssVars to inject as :root custom properties
+ * @property {{width:number,height:number}} [viewport] default 1280x800; call
+ *   once per viewport for multi-viewport token maps
+ * @property {string} [selector] root selector to capture (default 'body')
+ * @property {boolean} [diffOnly] enable the diff-cache spike (default true)
+ * @property {string} [screenshotDir] dir to write the PNG into (default os.tmpdir())
+ * @property {string} [screenshotPath] exact PNG path (overrides screenshotDir)
+ *
+ * @typedef {object} RenderJobDeps injectable seams (tests supply fakes)
+ * @property {() => Promise<import('./pagePool.js').PagePool>} [pagePool]
+ * @property {DiffCache} [cache]
+ * @property {(page: object, selector: string) => Promise<object>} [captureFn]
+ * @property {() => number} [now]
+ *
+ * @typedef {{path:string, width:number, height:number}} ScreenshotRef
+ *   A REFERENCE to the written screenshot file — never the image bytes inline
+ *   (so logs/NDJSON stay small; callers read the file themselves).
+ *
+ * @typedef {object} ConformanceRow
+ * @property {string} cssVar
+ * @property {string} expected
+ * @property {string} actual
+ * @property {boolean} match
+ *
+ * @typedef {object} ConformanceSnapshot
+ * @property {ConformanceRow[]} rows
+ * @property {boolean} conformant
+ * @property {number} mismatchCount
+ *
+ * @typedef {object} RenderJobTimings ms, for cloud throttle/telemetry metering
+ * @property {number} navigateMs
+ * @property {number} injectMs
+ * @property {number} captureMs
+ * @property {number} screenshotMs
+ * @property {number} totalMs
+ *
+ * @typedef {object} RenderJobDiff node-path diff vs this URL's last render
+ * @property {string[]} changed
+ * @property {string[]} added
+ * @property {string[]} removed
+ *
+ * @typedef {object} RenderJobResult
+ * @property {ScreenshotRef} screenshot
+ * @property {object} dom captured LayerNode tree (root)
+ * @property {ConformanceSnapshot} conformance
+ * @property {RenderJobTimings} timings
+ * @property {boolean} cacheHit exact (url,tokenMap) match — render skipped entirely
+ * @property {boolean} pageReused navigation skipped (page already open for this url)
+ * @property {RenderJobDiff|null} diff null if diffOnly=false or first render for the url
+ * @property {string} cacheKey
+ */
+
+let sharedPoolPromise = null
+async function defaultPagePool() {
+  if (!sharedPoolPromise) {
+    sharedPoolPromise = import('./pagePool.js').then((m) => m.createPagePool())
+  }
+  return sharedPoolPromise
+}
+
+const defaultCache = new DiffCache()
+
+let sharedWalkerBundle = null
+async function defaultCaptureFn(page, selector) {
+  const { buildWalkerBundle } = await import('./walkerBundle.js')
+  if (!sharedWalkerBundle) sharedWalkerBundle = await buildWalkerBundle()
+  // addInitScript covers future navigations on this page; evaluating the
+  // bundle directly also installs it on the CURRENT document — required on
+  // the page-reuse path, where no new navigation happens.
+  await page.addInitScript({ content: sharedWalkerBundle })
+  await page.evaluate(sharedWalkerBundle)
+  return page.evaluate((sel) => {
+    const root = document.querySelector(sel) || document.body
+    return window.__sorbCapture(root)
+  }, selector)
+}
+
+/**
+ * Render one job: navigate (or reuse) `url`, inject `tokenMap`, capture a
+ * screenshot + DOM + conformance snapshot. Reuses sorb-seed's existing
+ * Playwright capture machinery — this function does not reimplement it.
+ * @param {RenderJobInput} input
+ * @param {RenderJobDeps} [deps]
+ * @returns {Promise<RenderJobResult>}
+ */
+export async function renderJob(input, deps = {}) {
+  if (!input || !input.url) throw new Error('renderJob: input.url is required')
+  const {
+    url,
+    tokenMap = {},
+    viewport = { width: 1280, height: 800 },
+    selector = 'body',
+    diffOnly = true,
+    screenshotDir = tmpdir(),
+    screenshotPath,
+  } = input
+
+  const cache = deps.cache || defaultCache
+  const now = deps.now || (() => Date.now())
+  const t0 = now()
+
+  // 1. Exact-match short-circuit — same url + byte-identical token map.
+  const cacheKey = makeCacheKey(url, tokenMap)
+  const cached = cache.getExact(url, tokenMap)
+  if (cached) {
+    return { ...cached, cacheHit: true, timings: { ...cached.timings, totalMs: now() - t0 } }
+  }
+
+  // 2. Acquire a page — reused (nav skipped) if we already rendered this url.
+  const getPool = deps.pagePool || defaultPagePool
+  const pool = await getPool()
+  const tNav = now()
+  const { page, reused } = await pool.acquire(url, viewport)
+  const navigateMs = now() - tNav
+
+  // 3. Inject the token map.
+  const tInject = now()
+  await injectTokenMap(page, tokenMap)
+  const injectMs = now() - tInject
+
+  // 4. Capture DOM (reused walker) + conformance.
+  const tCapture = now()
+  const captureFn = deps.captureFn || defaultCaptureFn
+  const dom = await captureFn(page, selector)
+  const resolvedVars = await readResolvedVars(page, Object.keys(tokenMap))
+  const conformance = buildConformance(tokenMap, resolvedVars)
+  const captureMs = now() - tCapture
+
+  // 5. Screenshot → file ref (never returned inline).
+  const tShot = now()
+  const path = screenshotPath || resolve(screenshotDir, `sorb-render-${randomUUID()}.png`)
+  const shot = await page.screenshot()
+  await writeFile(path, shot)
+  const screenshotMs = now() - tShot
+
+  const timings = { navigateMs, injectMs, captureMs, screenshotMs, totalMs: now() - t0 }
+  const diff = diffOnly ? cache.diffAgainstLastForUrl(url, tokenMap, dom) : null
+
+  const result = {
+    screenshot: { path, width: viewport.width, height: viewport.height },
+    dom,
+    conformance,
+    timings,
+    cacheHit: false,
+    pageReused: reused,
+    diff,
+    cacheKey,
+  }
+
+  cache.putExact(url, tokenMap, result)
+  return result
+}
+
+/** Reset the module-level default cache (test helper). */
+export function __resetDefaultCache() {
+  defaultCache.clear()
+}

package/src/render/worker.test.js

@@ -0,0 +1,233 @@
+// Unit tests for the E3 render-worker orchestration. NO real Playwright/browser
+// is used — `page`/`pool`/`cache` are all fakes injected via `deps`, so these
+// tests exercise job orchestration, token-injection wiring, the diff-cache, and
+// the result shape without a live browser (per the task's hard rule).
+
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { readFile, rm } from 'node:fs/promises'
+import { join } from 'node:path'
+import { tmpdir } from 'node:os'
+import { randomUUID } from 'node:crypto'
+
+import { renderJob } from './worker.js'
+import { DiffCache } from './diffCache.js'
+
+// ─── fakes ────────────────────────────────────────────────────────────────────
+function makeFakePage({ resolvedVars = {} } = {}) {
+  const calls = { evaluate: 0, screenshot: 0 }
+  return {
+    calls,
+    async evaluate() {
+      calls.evaluate++
+      // 1st call in renderJob is injectTokenMap (no meaningful return needed);
+      // 2nd is readResolvedVars, which needs the resolved-values shape back.
+      if (calls.evaluate === 1) return undefined
+      return resolvedVars
+    },
+    async screenshot() {
+      calls.screenshot++
+      return Buffer.from('fake-png-bytes')
+    },
+    async addInitScript() {},
+    async setViewportSize() {},
+  }
+}
+
+function makeFakePool(pagesByUrl = {}) {
+  const acquireCalls = []
+  const seen = new Set()
+  return {
+    acquireCalls,
+    async acquire(url, viewport) {
+      acquireCalls.push({ url, viewport })
+      const reused = seen.has(url)
+      seen.add(url)
+      const page = pagesByUrl[url] || (pagesByUrl[url] = makeFakePage())
+      return { page, reused }
+    },
+    async evict() {},
+    async closeAll() {},
+  }
+}
+
+const scratchDir = tmpdir()
+const scratchPath = () => join(scratchDir, `sorb-worker-test-${randomUUID()}.png`)
+
+// ─── basic shape + reuse ──────────────────────────────────────────────────────
+test('renderJob: requires input.url', async () => {
+  await assert.rejects(() => renderJob({}), /url is required/)
+})
+
+test('renderJob: returns the documented result shape and writes the screenshot file', async () => {
+  const pool = makeFakePool()
+  const cache = new DiffCache()
+  const path = scratchPath()
+  let captureCalls = 0
+  const captureFn = async () => {
+    captureCalls++
+    return { type: 'FRAME', name: 'body', fills: [], children: [] }
+  }
+
+  const result = await renderJob(
+    {
+      url: 'https://demo.sorbcloud.com',
+      tokenMap: { '--sorb-color-bg': '#fff' },
+      screenshotPath: path,
+    },
+    { pagePool: async () => pool, cache, captureFn },
+  )
+
+  try {
+    assert.equal(result.cacheHit, false)
+    assert.equal(result.pageReused, false)
+    assert.equal(captureCalls, 1)
+    assert.equal(result.screenshot.path, path)
+    assert.equal(result.screenshot.width, 1280)
+    assert.equal(result.screenshot.height, 800)
+    assert.ok(result.dom)
+    assert.ok(result.conformance)
+    assert.equal(typeof result.conformance.conformant, 'boolean')
+    assert.ok(result.timings)
+    for (const k of ['navigateMs', 'injectMs', 'captureMs', 'screenshotMs', 'totalMs']) {
+      assert.equal(typeof result.timings[k], 'number')
+    }
+    assert.equal(result.diff, null) // first render for this url → no prior to diff against
+    assert.ok(result.cacheKey.includes('https://demo.sorbcloud.com'))
+
+    const written = await readFile(path)
+    assert.equal(written.toString(), 'fake-png-bytes')
+  } finally {
+    await rm(path, { force: true })
+  }
+})
+
+// ─── exact-match cache short-circuit ─────────────────────────────────────────
+test('renderJob: identical (url, tokenMap) on a warm cache short-circuits the render', async () => {
+  const pool = makeFakePool()
+  const cache = new DiffCache()
+  let captureCalls = 0
+  const captureFn = async () => {
+    captureCalls++
+    return { type: 'FRAME', children: [] }
+  }
+  const input = {
+    url: 'https://demo.sorbcloud.com',
+    tokenMap: { '--x': '1px' },
+    screenshotPath: scratchPath(),
+  }
+  const deps = { pagePool: async () => pool, cache, captureFn }
+
+  const r1 = await renderJob(input, deps)
+  const r2 = await renderJob({ ...input, screenshotPath: scratchPath() }, deps)
+
+  assert.equal(r1.cacheHit, false)
+  assert.equal(r2.cacheHit, true)
+  assert.equal(captureCalls, 1) // second call never re-rendered
+  assert.equal(r2.screenshot.path, r1.screenshot.path) // cached result's own screenshot ref
+  await rm(r1.screenshot.path, { force: true })
+})
+
+test('renderJob: different tokenMap for the same url is NOT a cache hit', async () => {
+  const pool = makeFakePool()
+  const cache = new DiffCache()
+  let captureCalls = 0
+  const captureFn = async () => {
+    captureCalls++
+    return { type: 'FRAME', children: [] }
+  }
+  const deps = { pagePool: async () => pool, cache, captureFn }
+
+  const p1 = scratchPath()
+  const p2 = scratchPath()
+  const r1 = await renderJob({ url: 'https://a', tokenMap: { '--x': '1px' }, screenshotPath: p1 }, deps)
+  const r2 = await renderJob({ url: 'https://a', tokenMap: { '--x': '2px' }, screenshotPath: p2 }, deps)
+
+  assert.equal(r1.cacheHit, false)
+  assert.equal(r2.cacheHit, false)
+  assert.equal(captureCalls, 2)
+  await rm(p1, { force: true })
+  await rm(p2, { force: true })
+})
+
+// ─── page reuse (navigation-skip) ────────────────────────────────────────────
+test('renderJob: a second render of the same url reuses the page (pageReused=true)', async () => {
+  const pool = makeFakePool()
+  const cache = new DiffCache()
+  const captureFn = async () => ({ type: 'FRAME', children: [] })
+  const deps = { pagePool: async () => pool, cache, captureFn }
+
+  const p1 = scratchPath()
+  const p2 = scratchPath()
+  const r1 = await renderJob({ url: 'https://a', tokenMap: { '--x': '1px' }, screenshotPath: p1 }, deps)
+  const r2 = await renderJob({ url: 'https://a', tokenMap: { '--x': '2px' }, screenshotPath: p2 }, deps)
+
+  assert.equal(r1.pageReused, false)
+  assert.equal(r2.pageReused, true)
+  assert.equal(pool.acquireCalls.length, 2)
+  await rm(p1, { force: true })
+  await rm(p2, { force: true })
+})
+
+// ─── diff-cache reporting ─────────────────────────────────────────────────────
+test('renderJob: diffOnly=true reports which dom subtree changed on a re-render', async () => {
+  const pool = makeFakePool()
+  const cache = new DiffCache()
+  let call = 0
+  const captureFn = async () => {
+    call++
+    // second capture differs from the first (a changed fill on the same shape)
+    return {
+      type: 'FRAME',
+      children: [{ type: 'FRAME', fills: call === 1 ? [] : [{ raw: '#fff' }], children: [] }],
+    }
+  }
+  const deps = { pagePool: async () => pool, cache, captureFn }
+
+  const p1 = scratchPath()
+  const p2 = scratchPath()
+  const r1 = await renderJob({ url: 'https://a', tokenMap: { '--x': '1' }, screenshotPath: p1, diffOnly: true }, deps)
+  const r2 = await renderJob({ url: 'https://a', tokenMap: { '--x': '2' }, screenshotPath: p2, diffOnly: true }, deps)
+
+  assert.equal(r1.diff, null)
+  assert.ok(r2.diff)
+  assert.ok(r2.diff.changed.length > 0)
+  await rm(p1, { force: true })
+  await rm(p2, { force: true })
+})
+
+test('renderJob: diffOnly=false skips the diff computation entirely', async () => {
+  const pool = makeFakePool()
+  const cache = new DiffCache()
+  const captureFn = async () => ({ type: 'FRAME', children: [] })
+  const deps = { pagePool: async () => pool, cache, captureFn }
+
+  const p1 = scratchPath()
+  const p2 = scratchPath()
+  await renderJob({ url: 'https://a', tokenMap: { '--x': '1' }, screenshotPath: p1, diffOnly: false }, deps)
+  const r2 = await renderJob({ url: 'https://a', tokenMap: { '--x': '2' }, screenshotPath: p2, diffOnly: false }, deps)
+
+  assert.equal(r2.diff, null)
+  await rm(p1, { force: true })
+  await rm(p2, { force: true })
+})
+
+// ─── conformance wiring end-to-end (with the captureFn/page fakes) ──────────
+test('renderJob: conformance reflects the resolved vs requested token values', async () => {
+  const page = makeFakePage({ resolvedVars: { '--sorb-color-bg': '#000' } }) // mismatch on purpose
+  const pool = { async acquire() { return { page, reused: false } }, async evict() {}, async closeAll() {} }
+  const cache = new DiffCache()
+  const captureFn = async () => ({ type: 'FRAME', children: [] })
+  const path = scratchPath()
+
+  const result = await renderJob(
+    { url: 'https://a', tokenMap: { '--sorb-color-bg': '#fff' }, screenshotPath: path },
+    { pagePool: async () => pool, cache, captureFn },
+  )
+
+  assert.equal(result.conformance.conformant, false)
+  assert.equal(result.conformance.mismatchCount, 1)
+  assert.equal(result.conformance.rows[0].expected, '#fff')
+  assert.equal(result.conformance.rows[0].actual, '#000')
+  await rm(path, { force: true })
+})