@sorb/seed 0.1.1 → 0.2.0

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

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