@sorb/seed 0.2.0 → 0.4.0

package/src/adapt/mapToToken.js

@@ -0,0 +1,94 @@
+// P1 — mapToToken: map a detected site to the nearest resolved token, reusing
+// the EXACT capture matcher (matchColor/matchDimension from annotateTokens.js),
+// and attach a confidence score.
+//
+// Confidence model (spec §6-P1, open-question "Confidence score model"):
+//   - exact value match + exactly ONE *on-role* candidate + on-role (offRole=false)
+//       ⇒ high confidence (1.0) ⇒ status 'auto'
+//   - a token bound, but EITHER offRole=true OR more than one on-role candidate
+//       ⇒ medium confidence (0.6) ⇒ status 'review'  (ambiguous → human gate)
+//   - no token matched
+//       ⇒ confidence 0 ⇒ status 'unmapped'
+//
+// "One candidate" = one candidate AFTER property-affinity role filtering (the
+// disambiguated pool the matcher actually picks from), NOT the raw value-
+// collision set. A single color (#0f65ef) collides with bg/border/text tokens,
+// but role 'bg' narrows that to exactly one bg token — an unambiguous bind, so
+// it earns 'auto'. The full collision set is still reported as `candidates`.
+//
+// AUTO_THRESHOLD is the single explicit cut between 'auto' and 'review'. A
+// mapping with confidence >= AUTO_THRESHOLD is auto-applied; below it routes to
+// review. 0.9 sits above the medium score (0.6) and at-or-below high (1.0), so
+// only unambiguous exact one-candidate on-role picks clear it.
+export const AUTO_THRESHOLD = 0.9
+
+const HIGH = 1.0 // exact + single candidate + on-role
+const MEDIUM = 0.6 // bound but ambiguous (off-role OR multiple candidates)
+
+import { matchColor, matchDimension, normalizeColor } from '../annotateTokens.js'
+
+/**
+ * Choose the matcher by the site's value type: a value that normalizes to a
+ * color goes through matchColor; otherwise (a dimension) through matchDimension.
+ * Role is passed straight through (annotateTokens applies property affinity).
+ * @param {import('./types.js').AdaptSite} site
+ * @param {{colors:Map, dims:Map}} index
+ */
+const matchSite = (site, index) => {
+  // Prefer color when the raw value is a color; the detector only ever flags a
+  // raw that is one or the other, but a value like '4' is unambiguously a dim.
+  if (normalizeColor(site.raw) != null) return matchColor(index, site.raw, site.role)
+  return matchDimension(index, site.raw, site.role)
+}
+
+/**
+ * Map one detected site → its nearest resolved token + confidence.
+ * @param {import('./types.js').AdaptSite} site
+ * @param {{colors:Map, dims:Map}} index   from buildTokenIndex(resolved)
+ * @param {import('@sorb/core').ResolvedToken[]} [resolved]  optional, to resolve cssVar
+ * @returns {import('./types.js').AdaptMapping}
+ */
+export function mapToToken(site, index, resolved) {
+  const res = matchSite(site, index)
+  if (!res.token) {
+    return { tokenId: null, cssVar: null, confidence: 0, candidates: res.candidates || [], offRole: false }
+  }
+  const offRole = !!res.offRole
+  // Count candidates AFTER role filtering — the pool the matcher disambiguated
+  // to. When offRole (role missed entirely) we use the full set, which is
+  // already ambiguous by definition.
+  const onRole =
+    site.role && !offRole
+      ? res.candidates.filter((id) => id.includes('.' + site.role))
+      : res.candidates
+  const ambiguous = offRole || onRole.length > 1
+  const confidence = ambiguous ? MEDIUM : HIGH
+  const cssVar = resolveCssVar(res.token, resolved)
+  return { tokenId: res.token, cssVar, confidence, candidates: res.candidates, offRole }
+}
+
+/**
+ * Map a confidence score to a report status using the single AUTO_THRESHOLD cut.
+ * @param {import('./types.js').AdaptMapping} mapping
+ * @returns {'auto'|'review'|'unmapped'}
+ */
+export function statusFor(mapping) {
+  if (!mapping.tokenId) return 'unmapped'
+  return mapping.confidence >= AUTO_THRESHOLD ? 'auto' : 'review'
+}
+
+/**
+ * Look up a token's cssVar from the resolved map (so the report carries the
+ * `--var` for the codemod/shim). Falls back to deriving it from the id when the
+ * resolved map isn't supplied.
+ * @param {string} tokenId
+ * @param {import('@sorb/core').ResolvedToken[]} [resolved]
+ */
+export function resolveCssVar(tokenId, resolved) {
+  if (resolved) {
+    const t = resolved.find((r) => r.id === tokenId)
+    if (t && t.cssVar) return t.cssVar
+  }
+  // Derive `--a-b-c` from `a.b.c` as a last resort (matches the SD convention).
+  return '--' + String(tokenId).replace(/\./g, '-')
+}

package/src/adapt/mapToToken.test.js

@@ -0,0 +1,103 @@
+// P1 acceptance: against sorb-demo's real resolved.json, mapToToken binds the
+// legacy Button fixture's hardcoded values to the SAME tokens annotateTokens.js
+// would, with the documented auto/review split. Run: node --test src/
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { readFileSync } from 'fs'
+import { fileURLToPath } from 'url'
+import { dirname, join } from 'path'
+import { buildTokenIndex, matchColor, matchDimension } from '../annotateTokens.js'
+import { detectHardcoded } from './detectHardcoded.js'
+import { mapToToken, statusFor, AUTO_THRESHOLD, resolveCssVar } from './mapToToken.js'
+
+const here = dirname(fileURLToPath(import.meta.url))
+const RESOLVED = JSON.parse(
+  readFileSync(
+    join(here, '..', '..', '..', 'sorb-demo', '.sorb', 'resolved.json'),
+    'utf-8',
+  ),
+)
+const index = buildTokenIndex(RESOLVED)
+
+const site = (raw, role, prop = 'x') => ({ file: 'f', loc: { line: 1, column: 0 }, prop, raw, role })
+
+test('P1: #0f65ef as bg → button.primary.bg.default, auto (exact, on-role, single bg)', () => {
+  const m = mapToToken(site('#0f65ef', 'bg'), index, RESOLVED)
+  assert.equal(m.tokenId, 'button.primary.bg.default')
+  assert.equal(m.cssVar, '--button-primary-bg-default')
+  assert.equal(m.confidence, 1.0)
+  assert.equal(m.offRole, false)
+  assert.equal(statusFor(m), 'auto')
+})
+
+test('P1: 4 and 4px as radius → button.radius, auto', () => {
+  for (const raw of ['4', '4px']) {
+    const m = mapToToken(site(raw, 'radius'), index, RESOLVED)
+    assert.equal(m.tokenId, 'button.radius', `raw=${raw}`)
+    assert.equal(m.cssVar, '--button-radius')
+    assert.equal(statusFor(m), 'auto')
+  }
+})
+
+test('P1: white as text → a *.text.*default* token, in review (ambiguous: many text candidates)', () => {
+  const m = mapToToken(site('#ffffff', 'text'), index, RESOLVED)
+  assert.ok(/\.text\..*default$/.test(m.tokenId), `got ${m.tokenId}`)
+  assert.equal(m.tokenId, 'button.primary.text.default')
+  assert.ok(m.candidates.length > 1)
+  assert.equal(m.confidence, 0.6)
+  assert.equal(statusFor(m), 'review')
+})
+
+test('P1: binding is byte-identical to annotateTokens matchColor/matchDimension', () => {
+  // Same index, same matcher → same token. This is the no-drift guarantee.
+  assert.equal(
+    mapToToken(site('#0f65ef', 'bg'), index, RESOLVED).tokenId,
+    matchColor(index, '#0f65ef', 'bg').token,
+  )
+  assert.equal(
+    mapToToken(site('#0f65ef', 'border'), index, RESOLVED).tokenId,
+    matchColor(index, '#0f65ef', 'border').token,
+  )
+  assert.equal(
+    mapToToken(site('4px', 'radius'), index, RESOLVED).tokenId,
+    matchDimension(index, '4px', 'radius').token,
+  )
+})
+
+test('P1: a value with no token → unmapped, confidence 0', () => {
+  const m = mapToToken(site('#123456', 'bg'), index, RESOLVED)
+  assert.equal(m.tokenId, null)
+  assert.equal(m.confidence, 0)
+  assert.equal(statusFor(m), 'unmapped')
+})
+
+test('P1: an off-role bind is medium confidence → review', () => {
+  // #0f65ef has no `.text` token in sorb-demo? It does NOT — narrow to a value
+  // that only carries one role and force the wrong role. white only carries
+  // bg/text tokens; asking for 'border' falls back off-role.
+  const m = mapToToken(site('#ffffff', 'border'), index, RESOLVED)
+  assert.equal(m.offRole, true)
+  assert.equal(statusFor(m), 'review')
+})
+
+test('P1: AUTO_THRESHOLD sits between medium (0.6) and high (1.0)', () => {
+  assert.ok(0.6 < AUTO_THRESHOLD && AUTO_THRESHOLD <= 1.0)
+})
+
+test('P1: resolveCssVar prefers the resolved map, falls back to id derivation', () => {
+  assert.equal(resolveCssVar('button.radius', RESOLVED), '--button-radius')
+  assert.equal(resolveCssVar('a.b.c', undefined), '--a-b-c')
+})
+
+test('P1: end-to-end over the legacy fixture maps the expected auto set', () => {
+  const src = readFileSync(join(here, '__fixtures__', 'Button.legacy.jsx'), 'utf-8')
+  const sites = detectHardcoded(src, 'Button.legacy.jsx')
+  const mapped = sites.map((s) => ({ s, m: mapToToken(s, index, RESOLVED) }))
+  // bg #0F65EF and radius 4/4px must be auto.
+  const bg = mapped.find((x) => x.s.role === 'bg')
+  assert.equal(bg.m.tokenId, 'button.primary.bg.default')
+  assert.equal(statusFor(bg.m), 'auto')
+  const rad = mapped.find((x) => x.s.role === 'radius')
+  assert.equal(rad.m.tokenId, 'button.radius')
+  assert.equal(statusFor(rad.m), 'auto')
+})

package/src/adapt/report.js

@@ -0,0 +1,53 @@
+// P1 — report emitter: detect → map → score → AdaptRow[], and write it to
+// `.sorb/adapt-report.json` (gitignored generated output).
+import { mkdirSync, writeFileSync } from 'fs'
+import { join } from 'path'
+import { mapToToken, statusFor } from './mapToToken.js'
+
+/**
+ * Score a list of detected sites into report rows.
+ * @param {import('./types.js').AdaptSite[]} sites
+ * @param {{colors:Map, dims:Map}} index
+ * @param {import('@sorb/core').ResolvedToken[]} [resolved]  to fill cssVar
+ * @returns {import('./types.js').AdaptRow[]}
+ */
+export function buildReport(sites, index, resolved) {
+  return sites.map((site) => {
+    const m = mapToToken(site, index, resolved)
+    return {
+      file: site.file,
+      loc: site.loc,
+      prop: site.prop,
+      raw: site.raw,
+      tokenId: m.tokenId,
+      cssVar: m.cssVar,
+      confidence: m.confidence,
+      candidates: m.candidates,
+      status: statusFor(m),
+    }
+  })
+}
+
+/**
+ * Summary counts by status.
+ * @param {import('./types.js').AdaptRow[]} rows
+ */
+export function summarize(rows) {
+  const out = { total: rows.length, auto: 0, review: 0, unmapped: 0 }
+  for (const r of rows) out[r.status]++
+  return out
+}
+
+/**
+ * Write the report to `<cwd>/.sorb/adapt-report.json`.
+ * @param {import('./types.js').AdaptRow[]} rows
+ * @param {string} cwd
+ * @returns {string} the absolute path written
+ */
+export function writeReport(rows, cwd) {
+  const dir = join(cwd, '.sorb')
+  mkdirSync(dir, { recursive: true })
+  const path = join(dir, 'adapt-report.json')
+  writeFileSync(path, JSON.stringify(rows, null, 2) + '\n', 'utf-8')
+  return path
+}

package/src/adapt/report.test.js

@@ -0,0 +1,66 @@
+// P1 acceptance: buildReport produces scored AdaptRow[] with the auto/review/
+// unmapped split, and writeReport writes JSON to .sorb/. Run: node --test src/
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { readFileSync, existsSync, rmSync, mkdtempSync } from 'fs'
+import { tmpdir } from 'os'
+import { fileURLToPath } from 'url'
+import { dirname, join } from 'path'
+import { buildTokenIndex } from '../annotateTokens.js'
+import { detectHardcoded } from './detectHardcoded.js'
+import { buildReport, summarize, writeReport } from './report.js'
+
+const here = dirname(fileURLToPath(import.meta.url))
+const RESOLVED = JSON.parse(
+  readFileSync(join(here, '..', '..', '..', 'sorb-demo', '.sorb', 'resolved.json'), 'utf-8'),
+)
+const index = buildTokenIndex(RESOLVED)
+const fixtureSrc = readFileSync(join(here, '__fixtures__', 'Button.legacy.jsx'), 'utf-8')
+
+test('buildReport emits one row per detected site with the full schema', () => {
+  const sites = detectHardcoded(fixtureSrc, 'Button.legacy.jsx')
+  const rows = buildReport(sites, index, RESOLVED)
+  assert.equal(rows.length, sites.length)
+  for (const r of rows) {
+    for (const k of ['file', 'loc', 'prop', 'raw', 'tokenId', 'cssVar', 'confidence', 'candidates', 'status']) {
+      assert.ok(Object.prototype.hasOwnProperty.call(r, k), `missing ${k}`)
+    }
+    assert.ok(['auto', 'review', 'unmapped'].includes(r.status))
+  }
+})
+
+test('buildReport splits the legacy fixture into auto/review correctly', () => {
+  const sites = detectHardcoded(fixtureSrc, 'Button.legacy.jsx')
+  const rows = buildReport(sites, index, RESOLVED)
+  const bg = rows.find((r) => r.prop === 'backgroundColor')
+  assert.equal(bg.tokenId, 'button.primary.bg.default')
+  assert.equal(bg.status, 'auto')
+  const rad = rows.find((r) => r.prop === 'borderRadius')
+  assert.equal(rad.tokenId, 'button.radius')
+  assert.equal(rad.status, 'auto')
+  // white text is ambiguous → review
+  const text = rows.find((r) => r.prop === 'color')
+  assert.equal(text.status, 'review')
+})
+
+test('summarize counts statuses and totals', () => {
+  const rows = buildReport(detectHardcoded(fixtureSrc, 'f'), index, RESOLVED)
+  const s = summarize(rows)
+  assert.equal(s.total, rows.length)
+  assert.equal(s.auto + s.review + s.unmapped, rows.length)
+  assert.ok(s.auto >= 1)
+})
+
+test('writeReport writes .sorb/adapt-report.json with valid JSON', () => {
+  const cwd = mkdtempSync(join(tmpdir(), 'sorb-adapt-'))
+  try {
+    const rows = buildReport(detectHardcoded(fixtureSrc, 'f'), index, RESOLVED)
+    const path = writeReport(rows, cwd)
+    assert.ok(existsSync(path))
+    assert.equal(path, join(cwd, '.sorb', 'adapt-report.json'))
+    const back = JSON.parse(readFileSync(path, 'utf-8'))
+    assert.deepEqual(back, rows)
+  } finally {
+    rmSync(cwd, { recursive: true, force: true })
+  }
+})

package/src/adapt/runBenchmark.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+// Run the legacy-adapter benchmark over the labeled fixture corpus against
+// sorb-demo's resolved map. Prints the MEASURED precision/recall/coverage —
+// the number behind the "~99%" claim. `pnpm bench`.
+import { fileURLToPath } from 'url'
+import { dirname, join, resolve } from 'path'
+import { runBenchmark } from './benchmark.js'
+
+const here = dirname(fileURLToPath(import.meta.url))
+const corpus = join(here, '__fixtures__', 'corpus')
+// Default to sorb-demo's resolved map (sibling repo); override with argv[2].
+const resolvedPath =
+  process.argv[2] ||
+  resolve(here, '..', '..', '..', 'sorb-demo', '.sorb', 'resolved.json')
+
+runBenchmark(corpus, resolvedPath)

package/src/adapt/types.js

@@ -0,0 +1,48 @@
+// JSDoc typedefs for the Legacy-React adapter (roadmap §6).
+//
+// JavaScript only — these are documentation/IDE shapes, not emitted types.
+// Shared token shapes (`ResolvedToken`, `Tier`) come from @sorb/core; the
+// adapter never re-declares them.
+
+/**
+ * A CSS property "role" the matcher understands. Drives property affinity in
+ * `matchColor`/`matchDimension` (annotateTokens.js). `null` ⇒ tier-only match.
+ * @typedef {'bg'|'text'|'border'|'radius'|null} AdaptRole
+ */
+
+/**
+ * A single detected hardcoded style site in consumer source.
+ * @typedef {Object} AdaptSite
+ * @property {string} file              Source file path (as passed to detect).
+ * @property {{line:number, column:number}} loc  1-based line, 0-based column (Babel loc.start).
+ * @property {string} prop              The CSS/JSX property name as written (e.g. 'backgroundColor', 'border-radius').
+ * @property {string} raw              The raw literal value as written (e.g. '#0F65EF', '4px', '4').
+ * @property {AdaptRole} role          Property→role mapping (bg/text/border/radius) or null.
+ */
+
+/**
+ * The result of mapping one site to the nearest resolved token.
+ * @typedef {Object} AdaptMapping
+ * @property {string|null} tokenId     Resolved token id, or null when unmapped.
+ * @property {string|null} cssVar      The token's `--css-var`, or null.
+ * @property {number} confidence       0..1 confidence score (see mapToToken).
+ * @property {string[]} candidates     All token ids that matched the value.
+ * @property {boolean} offRole         True when the pick fell back off-role (low confidence).
+ */
+
+/**
+ * A fully scored report row (detect → map → score). Emitted to
+ * `.sorb/adapt-report.json`.
+ * @typedef {Object} AdaptRow
+ * @property {string} file
+ * @property {{line:number, column:number}} loc
+ * @property {string} prop
+ * @property {string} raw
+ * @property {string|null} tokenId
+ * @property {string|null} cssVar
+ * @property {number} confidence
+ * @property {string[]} candidates
+ * @property {'auto'|'review'|'unmapped'} status
+ */
+
+export {}

package/src/captureCli.js

@@ -5,48 +5,11 @@
 
 import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'fs'
 import { createHash } from 'crypto'
-import { dirname, resolve, basename, extname } from 'path'
-import { build } from 'esbuild'
+import { resolve, dirname, basename, extname } from 'path'
+import { getSource, resolveConnectorIds } from '@sorb/core'
 import { tightenRoot } from './capture.js'
 import { buildTokenIndex, annotateTree } from './annotateTokens.js'
-
-// Playwright is an OPTIONAL peer dep — only `capture` needs it, and it pulls a
-// ~150 MB browser. Lazy-load it so plain installs and `resolve` stay lean.
-const loadChromium = async () => {
-  try {
-    const { chromium } = await import('playwright')
-    return chromium
-  } catch {
-    console.error(
-      '✗ `sorb-seed capture` needs Playwright (it is an optional peer dep).\n' +
-        '  Install it where you run capture:\n' +
-        '    npm install playwright            # its postinstall fetches Chromium\n' +
-        '  (or: npm install playwright && npx playwright install chromium)',
-    )
-    process.exit(1)
-  }
-}
-
-// 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
-  }
-}
+import { closeSession, storybookUrlOf } from './sources/storybookDom.js'
 
 const cwd = process.cwd()
 
@@ -71,47 +34,12 @@ const loadResolved = () => {
 
 const sha256 = (s) => createHash('sha256').update(s).digest('hex')
 
-// Bundle the walker into a single IIFE string we can addInitScript() into
-// every page. Playwright can't pass functions across the boundary directly,
-// and our walker has cross-file imports → bundling is the clean answer.
-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
-}
-
-const isStoryEntry = (e) =>
-  e && (e.type === 'story' || (e.type === undefined && e.importPath)) // SB7/8: type:'story'
-
-// Group story entries by their component (importPath) and pick the directory
-// of the story file as the artifact output dir (co-located).
-const groupByComponent = (entries) => {
-  const groups = new Map()
-  for (const e of entries) {
-    if (!groups.has(e.importPath)) groups.set(e.importPath, [])
-    groups.get(e.importPath).push(e)
-  }
-  return groups
-}
-
 // componentName: "Button" from "./src/.../Button.stories.jsx"
 const componentNameFromImportPath = (importPath) => {
   const file = basename(importPath, extname(importPath)) // "Button.stories"
   return file.replace(/\.stories$/i, '')
 }
 
-// sorb.config.json may set seed.storybookUrl. Fall back to localhost.
-const storybookUrlOf = (config) =>
-  (config.seed && config.seed.storybookUrl) || 'http://localhost:6006'
-
 const filterEntries = (entries, only) => {
   if (!only) return entries
   const re = new RegExp(only.replace(/[*]/g, '.*'), 'i')
@@ -122,65 +50,38 @@ export const runCapture = async (opts) => {
   const config = loadConfig()
   const resolved = loadResolved()
   const index = buildTokenIndex(resolved)
-  const sbUrl = (opts.storybookUrl || storybookUrlOf(config)).replace(/\/$/, '')
-
-  // 1. Discover stories
-  console.log(`→ Storybook: ${sbUrl}`)
-  let sbIndex
-  try {
-    const res = await fetch(`${sbUrl}/index.json`)
-    if (!res.ok) throw new Error('HTTP ' + res.status)
-    sbIndex = await res.json()
-  } catch (e) {
-    console.error('✗ Could not fetch Storybook index:', e.message)
-    process.exit(1)
-  }
-  const entries = filterEntries(
-    Object.values(sbIndex.entries || sbIndex.stories || {}).filter(isStoryEntry),
-    opts.only,
-  )
+  // `--storybook-url=` is a capture-command flag, not a sorb.config.json key —
+  // fold it into an effective config so the connector's own storybookUrlOf()
+  // resolution (config.seed.storybookUrl -> localhost default) still applies
+  // the same precedence the CLI used to apply inline.
+  const effectiveConfig = opts.storybookUrl
+    ? { ...config, seed: { ...(config.seed || {}), storybookUrl: opts.storybookUrl } }
+    : config
+
+  const connector = getSource(resolveConnectorIds(config).source)
+
+  // 1. Discover units (source connector)
+  const rawEntries = await connector.listUnits(effectiveConfig)
+  const entries = filterEntries(rawEntries, opts.only)
   if (!entries.length) {
     console.error('✗ No stories matched filter:', opts.only || '(all)')
     process.exit(1)
   }
   console.log(`→ ${entries.length} stories selected`)
 
-  // 2. Browser setup + walker injection
-  const chromium = await loadChromium()
-  const walker = await buildWalkerBundle()
-  const browser = await launchChromium(chromium)
-  const ctx = await browser.newContext({ viewport: { width: 1280, height: 800 } })
-  await ctx.addInitScript({ content: walker })
-
-  // 3. Capture each story, group by component
+  // 2. Capture each unit (source connector), group by component
   const captured = new Map() // importPath -> { component, importPath, stories[] }
   const oldIndex = readOldIndex(config)
 
-  for (const entry of entries) {
-    const url = `${sbUrl}/iframe.html?id=${entry.id}&viewMode=story`
-    const page = await ctx.newPage()
+  for (const unit of entries) {
+    // The whole per-unit body is wrapped so a throw in ANY step (capture,
+    // tighten, annotate, hash, store) skips just that unit and continues the
+    // run — matching the pre-connector behavior (a single bad story must not
+    // abort the entire capture).
     try {
-      console.log(`  · ${entry.id}`)
-      await page.goto(url, { waitUntil: 'load' })
-      // Wait for Storybook to actually render the story.
-      await page
-        .waitForFunction(
-          () => !!document.querySelector('#storybook-root *'),
-          { timeout: 15000 },
-        )
-        .catch(() => {})
-      await page.evaluate(() => document.fonts && document.fonts.ready)
-      await page.waitForLoadState('networkidle', { timeout: 15000 }).catch(() => {})
+      const rawTree = await connector.captureGeometry(unit, effectiveConfig)
+      if (!rawTree) continue // connector already logged why it skipped
 
-      const rawTree = await page.evaluate(() => {
-        const root = document.querySelector('#storybook-root')
-        return root ? window.__sorbCapture(root) : null
-      })
-      if (!rawTree) {
-        console.warn('    ⚠ no #storybook-root content; skipped')
-        await page.close()
-        continue
-      }
       // Trim the story container down to the meaningful component BEFORE
       // annotation/storage so insert + preview get a tight, token-bound node
       // (sorb-capture-trim-spec.md). Annotation runs on the kept subtree, so
@@ -190,42 +91,40 @@ export const runCapture = async (opts) => {
       const hash = 'sha256:' + sha256(JSON.stringify(tree))
 
       // --changed: reuse the previous artifact if hash matches
-      const prevHash = oldIndex.stories[entry.id]?.hash
+      const prevHash = oldIndex.stories[unit.id]?.hash
       if (opts.changed && prevHash === hash) {
         console.log('    = unchanged')
-        await page.close()
         continue
       }
 
-      if (!captured.has(entry.importPath)) {
-        captured.set(entry.importPath, {
+      if (!captured.has(unit.importPath)) {
+        captured.set(unit.importPath, {
           schemaVersion: 1,
-          component: componentNameFromImportPath(entry.importPath),
-          importPath: entry.importPath,
+          component: componentNameFromImportPath(unit.importPath),
+          importPath: unit.importPath,
           capturedAt: new Date().toISOString(),
           stories: [],
         })
       }
-      captured.get(entry.importPath).stories.push({
-        id: entry.id,
-        name: entry.name,
-        title: entry.title,
+      captured.get(unit.importPath).stories.push({
+        id: unit.id,
+        name: unit.name,
+        title: unit.title,
         hash,
         root: tree,
       })
     } catch (e) {
-      console.error('    ✗', entry.id, '—', e.message)
-    } finally {
-      await page.close()
+      console.error('    ✗', unit.id, '—', e.message)
+      continue
     }
   }
-  await browser.close()
+  await closeSession()
 
-  // 4. Write artifacts next to each story file, then the index
+  // 3. Write artifacts next to each story file, then the index
   const indexOut = {
     schemaVersion: 1,
     generatedAt: new Date().toISOString(),
-    storybookUrl: sbUrl,
+    storybookUrl: storybookUrlOf(effectiveConfig).replace(/\/$/, ''),
     components: [],
     stories: { ...oldIndex.stories }, // preserves entries we didn't recapture
   }

package/src/cli.js

@@ -235,7 +235,22 @@ if (cmd === '--help' || cmd === '-h' || cmd === 'help') {
     process.exit(1)
   }
 
+} else if (cmd === 'adapt') {
+  // Legacy-React adapter (roadmap §6): detect hardcoded styles → map to the
+  // nearest resolved token → scored report / runtime-shim payload / codemod.
+  const { runAdaptCli } = await import('./adapt/adaptCli.js')
+  await runAdaptCli(process.argv.slice(3), cwd)
 } else {
-  console.error(`Unknown command: ${cmd}\nUsage: sorb-seed <resolve|capture|render-worker|variant> [options]\nRun \`sorb-seed --help\` for details.`)
+  console.error(
+    `Unknown command: ${cmd}\n` +
+    `Usage: sorb-seed <resolve|capture|render-worker|variant|adapt> [options]\n` +
+    `  resolve                 build .sorb/resolved.json from DTCG sources (Style Dictionary)\n` +
+    `  capture [--changed]     headless Storybook → Figma capture\n` +
+    `  render-worker           internal render worker (variant preview rendering)\n` +
+    `  variant <add|deprecate> manage component variants\n` +
+    `  adapt   [--src <glob>] [--resolved <path>] [--mode report|shim|codemod] [--write]\n` +
+    `          detect hardcoded styles in a legacy React app and map them to tokens\n` +
+    `Run \`sorb-seed --help\` for details.`,
+  )
   process.exit(1)
 }