@sorb/seed 0.1.1 → 0.2.0

package/README.md

@@ -1,8 +1,9 @@
 # @sorb/seed
 
-Storybook → Figma capture for Sorb. This package holds the **heavy**
-pieces (esbuild now; Playwright later) so the bridge (`@sorb/juice`)
-and `@sorb/leaf` stay lean.
+Storybook→Figma capture for Sorb™, the design-token bridge for your running app. (Seed.)
+
+This package holds the **heavy** pieces (esbuild now; Playwright later)
+so the bridge (`@sorb/juice`) and `@sorb/leaf` stay lean.
 
 The full design lives in the team's internal spec (kept out of the repo).
 
@@ -13,7 +14,7 @@ This package is **private / not published to npm yet**, so there's no
 
 ```bash
 # 1. install this package's deps (from this directory)
-cd packages/seed
+cd sorb-seed
 npm install                 # pulls esbuild (Playwright is optional — see capture)
 
 # 2. expose the `sorb-seed` bin on your PATH
@@ -27,9 +28,14 @@ later: `npm unlink -g @sorb/seed` (or `npm rm -g @sorb/seed`).
 directly from the consuming app:
 
 ```bash
-node /abs/path/to/sorb/packages/seed/src/cli.js resolve
+node /abs/path/to/sorb-seed/src/cli.js resolve
 ```
 
+The CLI has exactly two commands — **`resolve`** and **`capture`** — plus
+`sorb-seed --help` / `-h` (usage) and `sorb-seed --version` / `-v`. (There is
+**no** `annotate` command: `annotateTree`/`annotateTokens` is the internal
+binder `capture` calls, not a CLI verb.)
+
 > **Where you run it matters.** `sorb-seed` reads `sorb.config.json`,
 > `sd.config.js`, and `tokens/` from the **current working directory** — i.e.
 > your *app* (e.g. `example/`), **not** this package directory. Run the commands
@@ -122,3 +128,7 @@ ranking (component > semantic > primitive).
 Planned: the **plugin materializer** (turns each `LayerNode` into a Figma
 component bound to Variables via `setBoundVariable`); pseudo-elements and
 forced interaction states; component-set assembly from per-story captures.
+
+---
+
+**Sorb™** is a trademark of Metatoy LLC.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sorb/seed",
-  "version": "0.1.1",
-  "description": "Storybook → Figma capture for Sorb: headless capture + the resolved bindable token map. Heavy deps (esbuild, later Playwright) live here so the bridge stays lean.",
+  "version": "0.2.0",
+  "description": "Storybook→Figma capture for Sorb, the design-token bridge for your running app. (Seed.)",
   "license": "MIT",
   "keywords": [
     "sorb",
@@ -21,6 +21,9 @@
   },
   "type": "module",
   "main": "src/index.js",
+  "scripts": {
+    "test": "node --test src/"
+  },
   "bin": {
     "sorb-seed": "src/cli.js"
   },
@@ -28,7 +31,7 @@
     "src"
   ],
   "dependencies": {
-    "@sorb/core": "^0.1.0",
+    "@sorb/core": "^0.1.1",
     "esbuild": "^0.21.0"
   },
   "peerDependencies": {

package/src/captureCli.js

@@ -27,6 +27,27 @@ const loadChromium = async () => {
   }
 }
 
+// The `playwright` PACKAGE can be installed while its Chromium BROWSER binary is
+// not (that's a separate `npx playwright install chromium` step). Launching then
+// throws a raw "Executable doesn't exist" error — turn it into the same
+// actionable guidance the missing-package path already gives.
+export const launchChromium = async (chromium) => {
+  try {
+    return await chromium.launch()
+  } catch (e) {
+    const msg = e && e.message ? e.message : String(e)
+    if (/Executable doesn't exist|playwright install|browserType\.launch/i.test(msg)) {
+      console.error(
+        '✗ `sorb-seed capture` found Playwright but its Chromium browser is not installed.\n' +
+          '  Install the browser where you run capture:\n' +
+          '    npx playwright install chromium',
+      )
+      process.exit(1)
+    }
+    throw e
+  }
+}
+
 const cwd = process.cwd()
 
 const loadConfig = () => {
@@ -127,7 +148,7 @@ export const runCapture = async (opts) => {
   // 2. Browser setup + walker injection
   const chromium = await loadChromium()
   const walker = await buildWalkerBundle()
-  const browser = await chromium.launch()
+  const browser = await launchChromium(chromium)
   const ctx = await browser.newContext({ viewport: { width: 1280, height: 800 } })
   await ctx.addInitScript({ content: walker })
 

package/src/cli.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { readFileSync, existsSync } from 'fs'
-import { resolve } from 'path'
+import { resolve, dirname } from 'path'
 import { execSync } from 'child_process'
 
 // sorb-seed — Storybook → Figma capture tooling.
@@ -25,7 +25,60 @@ const loadConfig = () => {
 
 const cmd = process.argv[2] || 'resolve'
 
-if (cmd === 'resolve') {
+const pkgVersion = () => {
+  try {
+    const pkgPath = resolve(dirname(new URL(import.meta.url).pathname), '..', 'package.json')
+    return JSON.parse(readFileSync(pkgPath, 'utf-8')).version
+  } catch (e) {
+    return '0.0.0'
+  }
+}
+
+const HELP = `sorb-seed — Storybook → Figma token capture for Sorb.
+
+Usage: sorb-seed <command> [options]
+
+Commands:
+  resolve            Build .sorb/resolved.json from your DTCG token sets via
+                     Style Dictionary (the default when no command is given).
+  capture            Visit each Storybook story with Playwright, capture the
+                     rendered tree, and annotate it against the resolved token
+                     map → per-component *.sorb.json + .sorb/index.json.
+  render-worker      Hosted-capture on-demand render worker (Mode B / E3):
+                     reads RenderJobInput job(s) as NDJSON on stdin (or
+                     --job=/--job-file=), renders each against a URL + token
+                     map, emits RenderJobResult NDJSON on stdout. See
+                     src/render/worker.js.
+  variant <add|deprecate>
+                     Add or deprecate a component variant in the DTCG source,
+                     bump $version, and rebuild. See \`variant\` usage below.
+
+variant options:
+  variant add <id> --from <base> [--tokens-dir <dir>] [--sd-dir <dir>]
+  variant deprecate <id> --replaced-by <replacement> [--tokens-dir <dir>] [--sd-dir <dir>]
+
+capture options:
+  --changed          Only re-capture stories whose rendered hash changed.
+  --only=<pattern>   Capture only stories matching the glob/regex (matched
+                     against importPath, title, and id).
+  --storybook-url=<url>
+                     Storybook base URL (default: sorb.config.json seed.storybookUrl
+                     or http://localhost:6006).
+
+Global:
+  -h, --help         Show this help and exit.
+  -v, --version      Print the sorb-seed version and exit.
+
+capture needs Playwright + its Chromium browser:
+  npm install playwright && npx playwright install chromium`
+
+if (cmd === '--help' || cmd === '-h' || cmd === 'help') {
+  console.log(HELP)
+  process.exit(0)
+} else if (cmd === '--version' || cmd === '-v') {
+  console.log(pkgVersion())
+  process.exit(0)
+} else if (cmd === 'resolve') {
   const config = loadConfig()
   const sdConfig = config.styleDictionaryConfig || 'sd.config.js'
   const abs = resolve(cwd, sdConfig)
@@ -53,7 +106,136 @@ if (cmd === 'resolve') {
     else if (a.startsWith('--storybook-url=')) opts.storybookUrl = a.slice('--storybook-url='.length)
   }
   await runCapture(opts)
+} else if (cmd === 'render-worker') {
+  const { main: renderWorkerMain } = await import('./render/cli.js')
+  await renderWorkerMain(process.argv)
+} else if (cmd === 'variant') {
+  const sub = process.argv[3]
+
+  // ── shared arg parser ──────────────────────────────────────────────────────
+  const args = process.argv.slice(4)
+  const flag = (name) => {
+    const prefix = `--${name}=`
+    const eq = args.find((a) => a.startsWith(prefix))
+    if (eq) return eq.slice(prefix.length)
+    const idx = args.indexOf(`--${name}`)
+    if (idx !== -1 && args[idx + 1] && !args[idx + 1].startsWith('--')) return args[idx + 1]
+    return null
+  }
+
+  // ── auto-detect sorb-demo paths ────────────────────────────────────────────
+  // Walks up from cwd looking for sorb-demo/tokens/component.json and
+  // sorb-demo/sd.config.js. Falls back to cwd-relative guesses.
+  const autoDetect = () => {
+    // Try workspace-sibling layout: cwd may be sorb-seed or any sibling
+    const candidates = [
+      resolve(cwd, '../sorb-demo'),
+      resolve(cwd, 'sorb-demo'),
+      cwd,
+    ]
+    for (const base of candidates) {
+      const tokens = resolve(base, 'tokens/component.json')
+      const sd = resolve(base, 'sd.config.js')
+      if (existsSync(tokens) && existsSync(sd)) return { tokensDir: resolve(base, 'tokens'), sdDir: base }
+    }
+    return null
+  }
+
+  if (sub === 'add') {
+    const variantId = args[0] && !args[0].startsWith('--') ? args[0] : null
+    const fromRaw   = flag('from')
+    const tokensDirFlag = flag('tokens-dir')
+    const sdDirFlag     = flag('sd-dir')
+
+    if (!variantId) {
+      console.error('✗ Usage: sorb-seed variant add <variantId> --from <fromVariant> [--tokens-dir <dir>] [--sd-dir <dir>]')
+      process.exit(1)
+    }
+    if (!fromRaw) {
+      console.error('✗ --from is required (e.g. --from primary or --from button.primary)')
+      process.exit(1)
+    }
+
+    // Normalise --from: if it has no dot, prepend the component from variantId
+    const componentId = variantId.split('.')[0]
+    const fromVariant = fromRaw.includes('.') ? fromRaw : `${componentId}.${fromRaw}`
+
+    // Resolve paths
+    let tokensDir = tokensDirFlag ? resolve(cwd, tokensDirFlag) : null
+    let sdDir     = sdDirFlag     ? resolve(cwd, sdDirFlag)     : null
+    if (!tokensDir || !sdDir) {
+      const detected = autoDetect()
+      if (!tokensDir) tokensDir = detected ? detected.tokensDir : resolve(cwd, 'tokens')
+      if (!sdDir)     sdDir     = detected ? detected.sdDir     : cwd
+    }
+    const componentJsonPath = resolve(tokensDir, 'component.json')
+
+    if (!existsSync(componentJsonPath)) {
+      console.error(`✗ component.json not found at ${componentJsonPath}`)
+      console.error('  Use --tokens-dir to point at your tokens directory.')
+      process.exit(1)
+    }
+
+    const { addVariant } = await import('./variants.js')
+    try {
+      const changeset = await addVariant({ componentJsonPath, variantId, fromVariant, sdConfigDir: sdDir })
+      console.log(`✓ Added variant ${changeset.variantId} (${changeset.tokenIds.length} tokens) — $version bumped to ${changeset.newVersion}`)
+    } catch (e) {
+      console.error('✗', e.message)
+      process.exit(1)
+    }
+
+  } else if (sub === 'deprecate') {
+    const variantId   = args[0] && !args[0].startsWith('--') ? args[0] : null
+    const replacedBy  = flag('replaced-by')
+    const tokensDirFlag = flag('tokens-dir')
+    const sdDirFlag     = flag('sd-dir')
+
+    if (!variantId) {
+      console.error('✗ Usage: sorb-seed variant deprecate <variantId> --replaced-by <replacedBy> [--tokens-dir <dir>] [--sd-dir <dir>]')
+      process.exit(1)
+    }
+    if (!replacedBy) {
+      console.error('✗ --replaced-by is required (e.g. --replaced-by button.error)')
+      process.exit(1)
+    }
+
+    // Resolve paths
+    let tokensDir = tokensDirFlag ? resolve(cwd, tokensDirFlag) : null
+    let sdDir     = sdDirFlag     ? resolve(cwd, sdDirFlag)     : null
+    if (!tokensDir || !sdDir) {
+      const detected = autoDetect()
+      if (!tokensDir) tokensDir = detected ? detected.tokensDir : resolve(cwd, 'tokens')
+      if (!sdDir)     sdDir     = detected ? detected.sdDir     : cwd
+    }
+    const componentJsonPath = resolve(tokensDir, 'component.json')
+
+    if (!existsSync(componentJsonPath)) {
+      console.error(`✗ component.json not found at ${componentJsonPath}`)
+      console.error('  Use --tokens-dir to point at your tokens directory.')
+      process.exit(1)
+    }
+
+    // Normalise replacedBy: if no dot, prepend the component from variantId
+    const componentId = variantId.split('.')[0]
+    const replacedByFull = replacedBy.includes('.') ? replacedBy : `${componentId}.${replacedBy}`
+
+    const { deprecateVariant } = await import('./variants.js')
+    try {
+      const changeset = await deprecateVariant({ componentJsonPath, variantId, replacedBy: replacedByFull, sdConfigDir: sdDir })
+      console.log(`✓ Deprecated variant ${changeset.variantId} → ${replacedByFull} (${changeset.tokenIds.length} tokens marked)`)
+    } catch (e) {
+      console.error('✗', e.message)
+      process.exit(1)
+    }
+
+  } else {
+    console.error(`✗ Unknown variant subcommand: ${sub || '(none)'}`)
+    console.error('  Usage: sorb-seed variant <add|deprecate> ...')
+    process.exit(1)
+  }
+
 } else {
-  console.error(`Unknown command: ${cmd}\nUsage: sorb-seed <resolve|capture> [options]`)
+  console.error(`Unknown command: ${cmd}\nUsage: sorb-seed <resolve|capture|render-worker|variant> [options]\nRun \`sorb-seed --help\` for details.`)
   process.exit(1)
 }

package/src/cli.test.js

@@ -0,0 +1,51 @@
+// Smoke tests for the `sorb-seed` CLI entrypoint — --help / --version / unknown
+// command dispatch (GFP RC1 Part 2 · D4). Spawns the real bin so exit codes and
+// stdout/stderr are exercised end-to-end. Run: `node --test src/cli.test.js`.
+
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { spawnSync } from 'node:child_process'
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { dirname, resolve } from 'node:path'
+
+const here = dirname(fileURLToPath(import.meta.url))
+const CLI = resolve(here, 'cli.js')
+const pkgVersion = JSON.parse(
+  readFileSync(resolve(here, '..', 'package.json'), 'utf-8'),
+).version
+
+const run = (args) => spawnSync(process.execPath, [CLI, ...args], { encoding: 'utf-8' })
+
+test('--help prints usage, lists resolve+capture, exits 0', () => {
+  const r = run(['--help'])
+  assert.equal(r.status, 0)
+  assert.match(r.stdout, /Usage: sorb-seed/)
+  assert.match(r.stdout, /\bresolve\b/)
+  assert.match(r.stdout, /\bcapture\b/)
+})
+
+test('-h is an alias for --help', () => {
+  const r = run(['-h'])
+  assert.equal(r.status, 0)
+  assert.match(r.stdout, /Usage: sorb-seed/)
+})
+
+test('--version prints the package.json version, exits 0', () => {
+  const r = run(['--version'])
+  assert.equal(r.status, 0)
+  assert.equal(r.stdout.trim(), pkgVersion)
+})
+
+test('-v is an alias for --version', () => {
+  const r = run(['-v'])
+  assert.equal(r.status, 0)
+  assert.equal(r.stdout.trim(), pkgVersion)
+})
+
+test('unknown command exits 1 and points at --help', () => {
+  const r = run(['bogus'])
+  assert.equal(r.status, 1)
+  assert.match(r.stderr, /Unknown command: bogus/)
+  assert.match(r.stderr, /--help/)
+})

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