@sorb/seed 0.1.1 → 0.3.0

package/src/emit/sorbFormat.test.js

@@ -0,0 +1,133 @@
+// Tests for the Sorb Tailwind v4 theme format (`sorb/tailwind-theme`).
+// Run: node --test  (zero-dep, Node's built-in runner — matches the workspace convention).
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { tailwindThemeEntry, sorbTailwind, tailwindV3Slot, sorbTailwindV3 } from './sorbFormat.js'
+
+// Helper: a token as Style Dictionary hands it to a format (path + $type).
+const tok = (id, type) => ({ path: id.split('.'), $type: type })
+
+test('color tokens map to the Tailwind --color-* family, value = var(self)', () => {
+  // semantic: leading `color.` is the namespace, not doubled
+  assert.deepEqual(tailwindThemeEntry(tok('color.action.primary', 'color')), {
+    key: '--color-action-primary',
+    ref: 'var(--color-action-primary)',
+  })
+  // primitive ramp
+  assert.deepEqual(tailwindThemeEntry(tok('color.blue.300', 'color')), {
+    key: '--color-blue-300',
+    ref: 'var(--color-blue-300)',
+  })
+})
+
+test('component colors keep their full path under the color family', () => {
+  // button.primary.bg.default has $type color but path does NOT start with `color`
+  assert.deepEqual(tailwindThemeEntry(tok('button.primary.bg.default', 'color')), {
+    key: '--color-button-primary-bg-default',
+    ref: 'var(--button-primary-bg-default)', // ref always points at the token's own css var
+  })
+})
+
+test('radius dimensions map to --radius-* (→ rounded-* utilities)', () => {
+  assert.deepEqual(tailwindThemeEntry(tok('radius.100', 'dimension')), {
+    key: '--radius-100',
+    ref: 'var(--radius-100)',
+  })
+  // component radius is remapped into the radius family so rounded-button works
+  assert.deepEqual(tailwindThemeEntry(tok('button.radius', 'dimension')), {
+    key: '--radius-button',
+    ref: 'var(--button-radius)',
+  })
+})
+
+test('space → --spacing-*, font.size → --text-*, fontWeight → --font-weight-*', () => {
+  assert.equal(tailwindThemeEntry(tok('space.200', 'dimension')).key, '--spacing-200')
+  assert.equal(tailwindThemeEntry(tok('space.200', 'dimension')).ref, 'var(--space-200)')
+  assert.equal(tailwindThemeEntry(tok('font.size.300', 'dimension')).key, '--text-300')
+  assert.equal(tailwindThemeEntry(tok('font.weight.semibold', 'fontWeight')).key, '--font-weight-semibold')
+})
+
+test('the ref is ALWAYS a var() reference, never a baked literal (live-preview invariant)', () => {
+  // This is the property that makes the bridge's runtime var-swap recolor
+  // Tailwind utilities with no Tailwind-specific code. Every entry must be var(…).
+  for (const t of [
+    tok('color.action.primary', 'color'),
+    tok('button.radius', 'dimension'),
+    tok('space.100', 'dimension'),
+  ]) {
+    assert.match(tailwindThemeEntry(t).ref, /^var\(--[a-z0-9-]+\)$/)
+  }
+})
+
+test('sorbTailwind emits an `@theme inline` block, one entry per token', () => {
+  const dictionary = {
+    allTokens: [
+      tok('color.action.primary', 'color'),
+      tok('button.radius', 'dimension'),
+      tok('space.100', 'dimension'),
+    ],
+  }
+  const css = sorbTailwind({ dictionary })
+  assert.match(css, /@theme inline \{/)
+  assert.match(css, /\}\s*$/)
+  assert.match(css, /^ {2}--color-action-primary: var\(--color-action-primary\);$/m)
+  assert.match(css, /^ {2}--radius-button: var\(--button-radius\);$/m)
+  // exactly 3 entries
+  assert.equal((css.match(/: var\(/g) || []).length, 3)
+})
+
+test('duplicate theme keys are skipped (collision guard), not emitted twice', () => {
+  const dictionary = {
+    // two distinct tokens that would collapse to the same theme key
+    allTokens: [tok('color.action.primary', 'color'), tok('color.action.primary', 'color')],
+  }
+  const css = sorbTailwind({ dictionary })
+  assert.equal((css.match(/--color-action-primary: /g) || []).length, 1)
+})
+
+// ─── Tailwind v3 preset (sorb/tailwind-v3-preset) ────────────────────────────
+
+test('v3 slot: colors strip leading `color`, components keep full path', () => {
+  assert.deepEqual(tailwindV3Slot(tok('color.action.primary', 'color')), {
+    category: 'colors', keyPath: ['action', 'primary'], ref: 'var(--color-action-primary)',
+  })
+  assert.deepEqual(tailwindV3Slot(tok('button.primary.bg.default', 'color')), {
+    category: 'colors', keyPath: ['button', 'primary', 'bg', 'default'], ref: 'var(--button-primary-bg-default)',
+  })
+})
+
+test('v3 slot: dimensions/weights map to the right v3 categories', () => {
+  assert.deepEqual(tailwindV3Slot(tok('radius.100', 'dimension')), { category: 'borderRadius', keyPath: ['100'], ref: 'var(--radius-100)' })
+  assert.deepEqual(tailwindV3Slot(tok('button.radius', 'dimension')), { category: 'borderRadius', keyPath: ['button'], ref: 'var(--button-radius)' })
+  assert.deepEqual(tailwindV3Slot(tok('space.200', 'dimension')), { category: 'spacing', keyPath: ['200'], ref: 'var(--space-200)' })
+  assert.deepEqual(tailwindV3Slot(tok('font.size.300', 'dimension')), { category: 'fontSize', keyPath: ['300'], ref: 'var(--font-size-300)' })
+  assert.deepEqual(tailwindV3Slot(tok('font.weight.regular', 'fontWeight')), { category: 'fontWeight', keyPath: ['regular'], ref: 'var(--font-weight-regular)' })
+})
+
+test('v3 slot: unknown type → null (no v3 family)', () => {
+  assert.equal(tailwindV3Slot({ path: ['z', 'index'], $type: 'number' }), null)
+})
+
+test('sorbTailwindV3 emits a requireable preset with nested theme.extend of var() refs', () => {
+  const dictionary = {
+    allTokens: [
+      tok('color.action.primary', 'color'),
+      tok('button.primary.bg.default', 'color'),
+      tok('button.radius', 'dimension'),
+      tok('space.100', 'dimension'),
+    ],
+  }
+  const src = sorbTailwindV3({ dictionary })
+  assert.match(src, /^module\.exports = /m)
+  // evaluate the generated CommonJS to prove it's a valid, requireable preset
+  const mod = { exports: {} }
+  new Function('module', 'exports', src)(mod, mod.exports)
+  const ext = mod.exports.theme.extend
+  assert.equal(ext.colors.action.primary, 'var(--color-action-primary)') // → bg-action-primary
+  assert.equal(ext.colors.button.primary.bg.default, 'var(--button-primary-bg-default)')
+  assert.equal(ext.borderRadius.button, 'var(--button-radius)') // → rounded-button
+  assert.equal(ext.spacing['100'], 'var(--space-100)') // → p-100
+  // every leaf is a var() ref (the live-preview invariant), never a literal
+  const leaves = (o) => Object.values(o).flatMap((v) => (typeof v === 'string' ? [v] : leaves(v)))
+  for (const v of leaves(ext)) assert.match(v, /^var\(--[a-z0-9-]+\)$/)
+})

package/src/index.js

@@ -5,3 +5,30 @@
 // so the old `resolveBindableTokens` export is gone. What remains useful as a
 // library is the token-annotation layer used by `capture`.
 export { buildTokenIndex, annotateTree, matchColor, matchDimension } from './annotateTokens.js'
+
+// Sorb's custom Style Dictionary outputs (component-compat-roadmap P0, part
+// 2) — promoted from sorb-demo's copy-local `sd/sorb-format.js` so target
+// adapters import these formats instead of duplicating them. A consumer's
+// `sd.config.js` registers these with `StyleDictionary.registerFormat`/
+// `registerParser` the same way sorb-demo's does.
+export {
+  tierOfFile,
+  SORB_RESOLVED,
+  SORB_THEME_NESTED,
+  SORB_ALIASES,
+  SORB_VERSIONS,
+  SORB_SET_META,
+  SORB_TAILWIND,
+  SORB_TAILWIND_V3,
+  SORB_TOKENSET,
+  sorbSetMeta,
+  sorbVersions,
+  sorbTokenSet,
+  sorbResolved,
+  sorbAliases,
+  sorbThemeNested,
+  tailwindThemeEntry,
+  sorbTailwind,
+  tailwindV3Slot,
+  sorbTailwindV3,
+} from './emit/sorbFormat.js'

package/src/render/cli.js

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+// `sorb-seed render-worker` — E3 hosted-capture on-demand render worker entry.
+// hosted-bridge-modes-exploration-plan.md §3 E3.
+//
+// This is the thin callable seam a cloud off-box runner (queue dispatcher)
+// invokes to run render jobs — mirrors sorb-cloud's `runnerEntry.mjs`
+// NDJSON-over-stdout child-runner contract so the pattern is consistent
+// across the two repos:
+//
+//   Input:  NDJSON on stdin — one `RenderJobInput` JSON object per line
+//           (see worker.js JSDoc). For a one-shot call from a shell, pass
+//           `--job='<json>'` or `--job-file=<path>` instead.
+//   Output: NDJSON on stdout — one line per job:
+//             {"t":"result","data":<RenderJobResult>}
+//             {"t":"error","message":"...","job":<the input job>}
+//           Diagnostics/logs go to STDERR only — stdout is reserved for the
+//           protocol so a queue can pipe it straight into JSON.parse per line.
+//
+// The Playwright page pool persists across jobs read from stdin, so a queue
+// that batches multiple jobs for the SAME url into one process invocation
+// gets pagePool.js's navigation-skip reuse. It is closed once stdin ends (or
+// after the single --job/--job-file run), so the process exits cleanly.
+
+import { readFileSync } from 'node:fs'
+import { renderJob } from './worker.js'
+import { createPagePool } from './pagePool.js'
+
+const emit = (obj) => process.stdout.write(JSON.stringify(obj) + '\n')
+
+async function runOneJob(job, pool) {
+  try {
+    const data = await renderJob(job, { pagePool: async () => pool })
+    emit({ t: 'result', data })
+  } catch (e) {
+    emit({ t: 'error', message: e && e.message ? e.message : String(e), job })
+  }
+}
+
+async function readStdinJobs() {
+  let buf = ''
+  const jobs = []
+  process.stdin.setEncoding('utf8')
+  for await (const chunk of process.stdin) {
+    buf += chunk
+    let nl
+    while ((nl = buf.indexOf('\n')) >= 0) {
+      const line = buf.slice(0, nl)
+      buf = buf.slice(nl + 1)
+      if (line.trim()) jobs.push(JSON.parse(line))
+    }
+  }
+  if (buf.trim()) jobs.push(JSON.parse(buf))
+  return jobs
+}
+
+export async function main(argv = process.argv) {
+  const pool = createPagePool()
+  try {
+    const jobFileArg = argv.find((a) => a.startsWith('--job-file='))
+    const jobArg = argv.find((a) => a.startsWith('--job='))
+
+    if (jobFileArg || jobArg) {
+      const raw = jobFileArg
+        ? readFileSync(jobFileArg.slice('--job-file='.length), 'utf-8')
+        : jobArg.slice('--job='.length)
+      await runOneJob(JSON.parse(raw), pool)
+      return
+    }
+
+    const jobs = await readStdinJobs()
+    for (const job of jobs) await runOneJob(job, pool)
+  } finally {
+    await pool.closeAll()
+  }
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main().catch((e) => {
+    process.stderr.write((e && e.stack ? e.stack : String(e)) + '\n')
+    process.exit(1)
+  })
+}

package/src/render/cli.test.js

@@ -0,0 +1,47 @@
+// cli.js wiring test. Deliberately does NOT exercise a real render (that would
+// launch a real browser) — it drives the `--job=` path with an invalid job
+// (missing `url`), which renderJob rejects BEFORE ever touching the page pool
+// (see worker.js: the url check runs first). That proves the CLI's NDJSON
+// error-emission + pool-lifecycle wiring without needing Playwright/a browser.
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { main } from './cli.js'
+
+function captureStdout(fn) {
+  const lines = []
+  const original = process.stdout.write.bind(process.stdout)
+  process.stdout.write = (chunk) => {
+    lines.push(String(chunk))
+    return true
+  }
+  return fn().finally(() => {
+    process.stdout.write = original
+  }).then(() => lines.join(''))
+}
+
+test('cli main(): --job= with a missing url emits a {t:"error"} NDJSON line, not a throw', async () => {
+  const output = await captureStdout(() => main(['node', 'cli.js', `--job=${JSON.stringify({})}`]))
+  const lines = output.trim().split('\n').filter(Boolean)
+  assert.equal(lines.length, 1)
+  const msg = JSON.parse(lines[0])
+  assert.equal(msg.t, 'error')
+  assert.match(msg.message, /url is required/)
+  assert.deepEqual(msg.job, {})
+})
+
+test('cli main(): --job-file= reads the job from disk', async () => {
+  const { writeFile, rm } = await import('node:fs/promises')
+  const { join } = await import('node:path')
+  const { tmpdir } = await import('node:os')
+  const { randomUUID } = await import('node:crypto')
+  const path = join(tmpdir(), `sorb-cli-test-${randomUUID()}.json`)
+  await writeFile(path, JSON.stringify({}))
+  try {
+    const output = await captureStdout(() => main(['node', 'cli.js', `--job-file=${path}`]))
+    const msg = JSON.parse(output.trim())
+    assert.equal(msg.t, 'error')
+    assert.match(msg.message, /url is required/)
+  } finally {
+    await rm(path, { force: true })
+  }
+})

package/src/render/diffCache.js

@@ -0,0 +1,152 @@
+// E3 (hosted-capture render worker) — diff-only cache spike.
+//
+// Two independent wins, both real (not stubbed), scoped honestly:
+//   1. EXACT-MATCH short-circuit: if a (url, tokenMap) pair was rendered before
+//      and the token map is byte-identical, skip the render entirely and return
+//      the cached result. This is the biggest, cheapest win during the credit
+//      window (repeat previews of an unchanged proposal).
+//   2. CHANGED-SUBTREE REPORT: when the token map differs from the last render
+//      of the SAME url, we still do a full page recapture (Playwright reads the
+//      whole rendered DOM in one pass — there is no cheap partial DOM read), but
+//      we diff the new capture's per-node hashes against the previous one and
+//      report which subtrees actually changed. That's real, useful signal for a
+//      caller (cloud telemetry / a future incremental-repaint UI) even though the
+//      RENDER itself is not selectively re-executed.
+//
+// TRUE selective re-render (only re-rendering the changed subtrees inside the
+// browser, skipping layout for the rest) is NOT implemented — it would require
+// either a persistent, patchable page (partial `page.evaluate` reflow, which
+// Chromium doesn't expose cleanly) or a virtual-DOM diffing shim injected into
+// the target app (out of our control since Mode B targets arbitrary apps). This
+// is the honest boundary called out in hosted-bridge-modes-exploration-plan.md
+// §3 E3 ("keep it behind a flag/option; correctness first, optimization second
+// — leave a documented stub"). What IS implemented (page reuse — skip
+// navigation on a cache-miss-but-same-url render) lives in `pagePool.js`.
+
+import { createHash } from 'node:crypto'
+
+/** Stable JSON stringify (sorted keys) so token-map key order never changes the hash. */
+export const stableStringify = (value) => {
+  const sortKeys = (v) => {
+    if (Array.isArray(v)) return v.map(sortKeys)
+    if (v && typeof v === 'object') {
+      return Object.keys(v)
+        .sort()
+        .reduce((acc, k) => {
+          acc[k] = sortKeys(v[k])
+          return acc
+        }, {})
+    }
+    return v
+  }
+  return JSON.stringify(sortKeys(value))
+}
+
+const sha256 = (s) => createHash('sha256').update(s).digest('hex')
+
+/** Hash a token map (cssVar -> value), order-independent. */
+export const hashTokenMap = (tokenMap) => 'sha256:' + sha256(stableStringify(tokenMap || {}))
+
+/** The cache key for a render: (url, tokenMap-hash). */
+export const makeCacheKey = (url, tokenMap) => `${url}::${hashTokenMap(tokenMap)}`
+
+/**
+ * Per-node hash map keyed by a stable structural path ("0.2.1" = root's 3rd
+ * child's 2nd child), so two trees of the same shape can be compared node-by-
+ * node even though DOM nodes have no stable id. Hash excludes nothing — the
+ * whole node's own fields (not descendants) plus a summary of children count,
+ * so a change anywhere down a branch bubbles up as a changed hash at every
+ * ancestor on that branch (cheap "which top-level regions changed" signal).
+ * @param {object} tree LayerNode-shaped tree (root, with .children[])
+ * @returns {Map<string,string>} path -> sha256 hash
+ */
+export const hashNodePaths = (tree) => {
+  const out = new Map()
+  const walk = (node, path) => {
+    if (!node) return
+    const { children, ...ownFields } = node
+    const own = sha256(stableStringify(ownFields))
+    const childHashes = (children || []).map((c, i) => walk(c, path ? `${path}.${i}` : String(i)))
+    const combined = sha256(own + '|' + childHashes.join(','))
+    out.set(path || '0', combined)
+    return combined
+  }
+  walk(tree, '0')
+  return out
+}
+
+/**
+ * Diff two node-path hash maps.
+ * @returns {{changed:string[], added:string[], removed:string[]}} paths present
+ *   in both but with a different hash / only in `next` / only in `prev`.
+ */
+export const diffNodeHashes = (prevHashes, nextHashes) => {
+  const changed = []
+  const added = []
+  const removed = []
+  for (const [path, hash] of nextHashes) {
+    if (!prevHashes.has(path)) added.push(path)
+    else if (prevHashes.get(path) !== hash) changed.push(path)
+  }
+  for (const path of prevHashes.keys()) {
+    if (!nextHashes.has(path)) removed.push(path)
+  }
+  return { changed, added, removed }
+}
+
+/**
+ * In-memory diff-cache. One process/worker instance's lifetime — not persisted.
+ * `capacity` bounds memory (LRU-by-insertion via Map iteration order); default
+ * is generous since a render result's dom tree is the only heavy field kept.
+ */
+export class DiffCache {
+  constructor({ capacity = 200 } = {}) {
+    this.capacity = capacity
+    /** exact (url,tokenMap-hash) -> full render result */
+    this.exact = new Map()
+    /** url -> { tokenMap, hashes: Map<path,hash> } — last render, ANY token map */
+    this.byUrl = new Map()
+  }
+
+  /** Exact-match lookup: same url + byte-identical token map. */
+  getExact(url, tokenMap) {
+    return this.exact.get(makeCacheKey(url, tokenMap))
+  }
+
+  /** Record an exact-match entry (called after every successful render). */
+  putExact(url, tokenMap, result) {
+    const key = makeCacheKey(url, tokenMap)
+    this.exact.set(key, result)
+    this._evictIfNeeded(this.exact)
+  }
+
+  /**
+   * Diff a freshly-captured tree against the last capture for this URL
+   * (regardless of token map), returning which node paths changed. Also
+   * records this capture as the new "last" for the url. Returns `null` when
+   * there is no prior capture to diff against (first render for this url).
+   */
+  diffAgainstLastForUrl(url, tokenMap, tree) {
+    const prev = this.byUrl.get(url)
+    const nextHashes = hashNodePaths(tree)
+    let diff = null
+    if (prev) {
+      diff = diffNodeHashes(prev.hashes, nextHashes)
+    }
+    this.byUrl.set(url, { tokenMap, hashes: nextHashes })
+    this._evictIfNeeded(this.byUrl)
+    return diff
+  }
+
+  _evictIfNeeded(map) {
+    while (map.size > this.capacity) {
+      const oldestKey = map.keys().next().value
+      map.delete(oldestKey)
+    }
+  }
+
+  clear() {
+    this.exact.clear()
+    this.byUrl.clear()
+  }
+}

package/src/render/diffCache.test.js

@@ -0,0 +1,110 @@
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import {
+  stableStringify,
+  hashTokenMap,
+  makeCacheKey,
+  hashNodePaths,
+  diffNodeHashes,
+  DiffCache,
+} from './diffCache.js'
+
+test('stableStringify: key order does not affect the result', () => {
+  const a = stableStringify({ b: 1, a: 2 })
+  const b = stableStringify({ a: 2, b: 1 })
+  assert.equal(a, b)
+})
+
+test('hashTokenMap: order-independent, sensitive to values', () => {
+  const h1 = hashTokenMap({ '--x': '1', '--y': '2' })
+  const h2 = hashTokenMap({ '--y': '2', '--x': '1' })
+  const h3 = hashTokenMap({ '--y': '3', '--x': '1' })
+  assert.equal(h1, h2)
+  assert.notEqual(h1, h3)
+})
+
+test('hashTokenMap: empty/undefined map is stable', () => {
+  assert.equal(hashTokenMap(undefined), hashTokenMap({}))
+})
+
+test('makeCacheKey: combines url + token-map hash', () => {
+  const k1 = makeCacheKey('https://a.example', { '--x': '1' })
+  const k2 = makeCacheKey('https://b.example', { '--x': '1' })
+  const k3 = makeCacheKey('https://a.example', { '--x': '2' })
+  assert.notEqual(k1, k2)
+  assert.notEqual(k1, k3)
+  assert.equal(k1, makeCacheKey('https://a.example', { '--x': '1' }))
+})
+
+// ─── node-path hashing / diffing ─────────────────────────────────────────────
+const tree = (fill, children = []) => ({ type: 'FRAME', fills: fill ? [{ raw: fill }] : [], children })
+
+test('hashNodePaths: identical trees produce identical hashes at every path', () => {
+  const t1 = tree('#fff', [tree('#000'), tree('#111')])
+  const t2 = tree('#fff', [tree('#000'), tree('#111')])
+  const h1 = hashNodePaths(t1)
+  const h2 = hashNodePaths(t2)
+  assert.deepEqual([...h1.keys()].sort(), [...h2.keys()].sort())
+  for (const [path, hash] of h1) assert.equal(hash, h2.get(path))
+})
+
+test('diffNodeHashes: a leaf change bubbles up to its ancestors, siblings unaffected', () => {
+  const before = tree('#fff', [tree('#000'), tree('#111')])
+  const after = tree('#fff', [tree('#000'), tree('#222')]) // child 1 changed
+  const diff = diffNodeHashes(hashNodePaths(before), hashNodePaths(after))
+  // root (path "0") and the changed child ("0.1") both bubble; the unchanged
+  // sibling ("0.0") must NOT appear.
+  assert.ok(diff.changed.includes('0'))
+  assert.ok(diff.changed.includes('0.1'))
+  assert.ok(!diff.changed.includes('0.0'))
+  assert.deepEqual(diff.added, [])
+  assert.deepEqual(diff.removed, [])
+})
+
+test('diffNodeHashes: added/removed children are reported', () => {
+  const before = tree('#fff', [tree('#000')])
+  const after = tree('#fff', [tree('#000'), tree('#111')])
+  const diff = diffNodeHashes(hashNodePaths(before), hashNodePaths(after))
+  assert.ok(diff.added.includes('0.1'))
+  assert.ok(diff.changed.includes('0')) // root's own hash bubbled (child count changed)
+})
+
+// ─── DiffCache ────────────────────────────────────────────────────────────────
+test('DiffCache: exact getExact/putExact round-trips on (url, tokenMap)', () => {
+  const cache = new DiffCache()
+  assert.equal(cache.getExact('https://a', { x: '1' }), undefined)
+  cache.putExact('https://a', { x: '1' }, { some: 'result' })
+  assert.deepEqual(cache.getExact('https://a', { x: '1' }), { some: 'result' })
+  // different token map → different key → no hit
+  assert.equal(cache.getExact('https://a', { x: '2' }), undefined)
+})
+
+test('DiffCache: diffAgainstLastForUrl returns null on first render, a diff on the second', () => {
+  const cache = new DiffCache()
+  const first = tree('#fff', [tree('#000')])
+  const d1 = cache.diffAgainstLastForUrl('https://a', { x: '1' }, first)
+  assert.equal(d1, null)
+
+  const second = tree('#fff', [tree('#111')]) // changed
+  const d2 = cache.diffAgainstLastForUrl('https://a', { x: '2' }, second)
+  assert.ok(d2)
+  assert.ok(d2.changed.length > 0)
+})
+
+test('DiffCache: capacity eviction bounds memory (oldest-first)', () => {
+  const cache = new DiffCache({ capacity: 2 })
+  cache.putExact('https://a', {}, { n: 1 })
+  cache.putExact('https://b', {}, { n: 2 })
+  cache.putExact('https://c', {}, { n: 3 }) // evicts https://a
+  assert.equal(cache.getExact('https://a', {}), undefined)
+  assert.deepEqual(cache.getExact('https://c', {}), { n: 3 })
+})
+
+test('DiffCache: clear() wipes both maps', () => {
+  const cache = new DiffCache()
+  cache.putExact('https://a', {}, { n: 1 })
+  cache.diffAgainstLastForUrl('https://a', {}, tree('#fff'))
+  cache.clear()
+  assert.equal(cache.getExact('https://a', {}), undefined)
+  assert.equal(cache.diffAgainstLastForUrl('https://a', {}, tree('#fff')), null)
+})

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')
+})