@sorb/seed 0.1.0-canary.0

package/README.md

@@ -0,0 +1,124 @@
+# @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.
+
+The full design lives in the team's internal spec (kept out of the repo).
+
+## Install & link the CLI
+
+This package is **private / not published to npm yet**, so there's no
+`npm i @sorb/seed`. To get the `sorb-seed` command working:
+
+```bash
+# 1. install this package's deps (from this directory)
+cd packages/seed
+npm install                 # pulls esbuild (Playwright is optional — see capture)
+
+# 2. expose the `sorb-seed` bin on your PATH
+npm link                    # creates a global symlink to bin → src/cli.js
+```
+
+`sorb-seed` is now runnable from anywhere. To remove the global symlink
+later: `npm unlink -g @sorb/seed` (or `npm rm -g @sorb/seed`).
+
+**Prefer not to touch your global PATH?** Skip `npm link` and invoke the source
+directly from the consuming app:
+
+```bash
+node /abs/path/to/sorb/packages/seed/src/cli.js resolve
+```
+
+> **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
+> below from the app you're capturing, after `npm link`ing here once.
+
+## Status
+
+Early — not yet published (`private`). Implemented so far:
+
+- **`sorb-seed resolve`** — a thin wrapper around **Style Dictionary**. The
+  DTCG token sets (`tokens/{primitive,semantic,component}.json`) are the source
+  of truth; SD's `sorb/resolved-map` format emits `.sorb/resolved.json` —
+  one entry per token: `[{ id, cssVar, value, tier, type }]` where
+  `tier ∈ {primitive, semantic, component}`. Reads `sorb.config.json`
+  (`styleDictionaryConfig`, default `sd.config.js`). The bridge (`sorb dev`)
+  serves this at `GET /tokens/resolved`; the plugin's **Sync Variables** button
+  and `capture`'s annotator both consume it. (This retired the old
+  esbuild-bundle-and-eval theme resolver.)
+
+  ```bash
+  sorb-seed resolve   # → runs style-dictionary build → .sorb/resolved.json
+  ```
+
+- **`sorb-seed capture`** (`src/captureCli.js`) — Playwright runner that
+  visits every story in your running Storybook, injects the walker (below),
+  captures the rendered root, annotates tokens against `.sorb/resolved.json`,
+  and writes:
+  - one **`<Component>.sorb.json`** *next to each story file* (containing
+    all of that component's stories), and
+  - **`.sorb/index.json`** — a story-id → artifact map (with content hashes
+    for `--changed`).
+
+  Playwright is an **optional peer dependency** — it (and its ~150 MB browser)
+  is only needed for `capture`, never for `resolve` or a plain install.
+
+  The URLs below align with the **sorb-demo** services (`npm run demo`):
+
+  | Service | URL |
+  |---|---|
+  | App (Vite) | `http://localhost:5173` |
+  | Bridge (`sorb dev`) | `http://localhost:7777` |
+  | Storybook | `http://localhost:6006` |
+
+  ```bash
+  # one-time, only if you'll run capture:
+  npm install playwright        # its postinstall fetches Chromium automatically
+  #   (if browsers were skipped: npx playwright install chromium)
+
+  # capture against the demo's Storybook (set once in sorb.config.json)
+  sorb-seed capture                                      # uses seed.storybookUrl
+  sorb-seed capture --only=Button.stories                # filter by importPath/title/id
+  sorb-seed capture --changed                            # skip unchanged stories
+  sorb-seed capture --storybook-url=http://localhost:6006  # override on the fly
+  ```
+
+  Set `seed.storybookUrl` in `sorb.config.json` so you don't need the flag:
+
+  ```jsonc
+  {
+    "seed": { "storybookUrl": "http://localhost:6006" }
+  }
+  ```
+
+  The captured artifacts are then served by the bridge at
+  `GET http://localhost:7777/artifacts` (the index) and
+  `GET http://localhost:7777/artifact?id=<storyId>` (one artifact, looked up
+  by id — never a raw filesystem path). The Figma plugin's **Storybook** tab
+  fetches from these endpoints to list and insert captured components.
+
+- **`captureRoot(el)`** (`src/capture.js`) — in-page DOM walker (our own
+  capture engine, no `htmlToFigma` dependency). Maps element →
+  FRAME/RECTANGLE/TEXT `LayerNode` with fills, strokes, corner radius, single
+  box-shadow, text (family/weight/size/line-height/letter-spacing/align/color),
+  flex → auto-layout + padding, and geometry relative to each parent. Designed
+  to run via Playwright's `page.evaluate`; pure helpers (color/dim/shadow
+  parsing) unit-tested. Scope (v1) supports the design-system primitive case;
+  gradients/grid/transform/pseudo-elements are deferred.
+- **`annotateTree(node, index)`** (`src/annotateTokens.js`) — walks a captured
+  tree, attaches a `sorb.tokens` / `sorb.candidates` side-channel to each
+  node whose bindable values (fill, stroke, corner radius, effect color) match
+  the resolved bindable map. Idempotent; preserves raw values for the plugin
+  materializer.
+
+Validated end-to-end against the sorb-demo resolved map: a Button DOM →
+`captureRoot` → `annotateTree` binds `fill` → `button.primary.bg.default`,
+`stroke` → `button.primary.border.default`, `cornerRadius` → `button.radius`,
+text fill → `button.primary.text.default`, using tier + property-affinity
+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.

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@sorb/seed",
+  "version": "0.1.0-canary.0",
+  "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.",
+  "license": "MIT",
+  "keywords": [
+    "sorb",
+    "design-tokens",
+    "figma",
+    "storybook",
+    "tokens"
+  ],
+  "homepage": "https://github.com/metatoy/sorb-seed#readme",
+  "bugs": "https://github.com/metatoy/sorb-seed/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/metatoy/sorb-seed.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "src/index.js",
+  "bin": {
+    "sorb-seed": "src/cli.js"
+  },
+  "files": [
+    "src"
+  ],
+  "dependencies": {
+    "@sorb/core": "^0.1.0",
+    "esbuild": "^0.21.0"
+  },
+  "peerDependencies": {
+    "playwright": "^1.60.0"
+  },
+  "peerDependenciesMeta": {
+    "playwright": {
+      "optional": true
+    }
+  }
+}

package/src/annotateTokens.js

@@ -0,0 +1,118 @@
+import { TIER_RANK } from '@sorb/core'
+
+// Token annotation for captured layer values.
+//
+// Exact, normalized matching against the resolved bindable token map
+// (Style Dictionary's `sorb/resolved-map`: { id, cssVar, value, tier, type }):
+//   colors → canonical #rrggbbaa (lowercase); dimensions → px number.
+// On collision, best-guess prefers the most specific tier
+// (component > semantic > primitive), then resolved order; ALL matches are kept
+// as `candidates` so the plugin can offer a switch.
+// (Phase 4 adds property affinity — fill→bg, stroke→border, etc.)
+
+const expandHex = (h) => {
+  h = h.toLowerCase()
+  if (h.length === 3 || h.length === 4) h = h.split('').map((c) => c + c).join('')
+  if (h.length === 6) h += 'ff'
+  return '#' + h
+}
+const toHex2 = (n) =>
+  Math.round(Math.max(0, Math.min(255, n))).toString(16).padStart(2, '0')
+const alphaHex = (a) => toHex2(Math.max(0, Math.min(1, a)) * 255)
+
+/** Normalize any CSS color to canonical `#rrggbbaa`, or null if not a color. */
+export const normalizeColor = (value) => {
+  if (value == null) return null
+  const s = String(value).trim().toLowerCase()
+  if (s === 'transparent') return '#00000000'
+  let m = s.match(/^#([0-9a-f]{3,8})$/)
+  if (m) return expandHex(m[1])
+  m = s.match(/^rgba?\(\s*([^)]+)\)$/)
+  if (m) {
+    const p = m[1].split(',').map((x) => x.trim())
+    if (p.length < 3) return null
+    const a = p[3] !== undefined ? parseFloat(p[3]) : 1
+    return '#' + toHex2(+p[0]) + toHex2(+p[1]) + toHex2(+p[2]) + alphaHex(a)
+  }
+  return null
+}
+
+/** Normalize a CSS length to a px number, or null. */
+export const normalizeDimension = (value) => {
+  if (value == null) return null
+  const m = String(value).trim().match(/^(-?\d+(?:\.\d+)?)(?:px)?$/)
+  return m ? parseFloat(m[1]) : null
+}
+
+/** Build value→[token] indexes (colors, dims) from the resolved bindable map. */
+export const buildTokenIndex = (resolved) => {
+  const colors = new Map()
+  const dims = new Map()
+  const add = (map, key, t) => {
+    if (key == null) return
+    if (!map.has(key)) map.set(key, [])
+    map.get(key).push(t)
+  }
+  for (const t of resolved) {
+    const c = normalizeColor(t.value)
+    if (c) add(colors, c, t)
+    else add(dims, normalizeDimension(t.value), t)
+  }
+  return { colors, dims }
+}
+
+// Binding = property affinity first, then tier precedence.
+//
+// Tier rank alone is ambiguous: one color value (e.g. #0F65EF) can match a
+// `bg`, a `border`, AND a `text` token. The captured node's *property* tells us
+// the role it plays — a frame fill wants a `bg` token, a stroke a `border`, a
+// text fill a `text`, a corner radius a `radius`. We filter candidates to that
+// role, then break remaining ties by tier (component > semantic > primitive).
+// If no candidate carries the role, fall back to the full set (tier-only).
+// TIER_RANK is the canonical ordering from @sorb/core (shared contract).
+
+// role → the path segment a matching token id should contain (`.bg`, `.text`,
+// `.border`, `.radius`). Matched on `.<role>` so `color.bg.surface`,
+// `button.primary.bg.default`, and `button.radius` all qualify.
+const byTier = (a, b) => (TIER_RANK[a.tier] ?? 9) - (TIER_RANK[b.tier] ?? 9)
+
+const pick = (cands, role) => {
+  if (!cands || !cands.length) return { token: null, candidates: [] }
+  const roled = role ? cands.filter((c) => c.id.includes('.' + role)) : []
+  const pool = roled.length ? roled : cands
+  const best = [...pool].sort(byTier)[0]
+  return { token: best.id, candidates: cands.map((c) => c.id) }
+}
+
+export const matchColor = (index, value, role) => {
+  const c = normalizeColor(value)
+  return c ? pick(index.colors.get(c), role) : { token: null, candidates: [] }
+}
+
+export const matchDimension = (index, value, role) => {
+  const d = normalizeDimension(value)
+  return d == null ? { token: null, candidates: [] } : pick(index.dims.get(d), role)
+}
+
+// Walk a captured LayerNode tree and attach `sorb.tokens` / `.candidates`
+// to each node whose bindable values match a token. Mutates and returns the
+// tree. (The plugin materializer reads these to bind Figma Variables.)
+export const annotateTree = (node, index) => {
+  const tokens = {}
+  const candidates = {}
+  const set = (key, res) => {
+    if (res.token) { tokens[key] = res.token; candidates[key] = res.candidates }
+  }
+  // A fill on a TEXT node is foreground (`text`); on a frame it's `bg`.
+  const fillRole = node.type === 'TEXT' ? 'text' : 'bg'
+  if (node.fills && node.fills[0]) set('fill', matchColor(index, node.fills[0].raw, fillRole))
+  if (node.strokes && node.strokes[0]) set('stroke', matchColor(index, node.strokes[0].raw, 'border'))
+  if (typeof node.cornerRadius === 'number') set('cornerRadius', matchDimension(index, node.cornerRadius, 'radius'))
+  if (Array.isArray(node.effects)) {
+    // No shadow tokens yet → no role, falls back to tier-only.
+    node.effects.forEach((e, i) => { if (e.color) set(`effect${i}`, matchColor(index, e.color.raw)) })
+  }
+  if (Object.keys(tokens).length) node.sorb = { tokens, candidates }
+  if (Array.isArray(node.children)) node.children.forEach((c) => annotateTree(c, index))
+  return node
+}

package/src/capture.js

@@ -0,0 +1,209 @@
+// Sorb capture walker — runs IN THE PAGE (headless browser).
+//
+// Turns a DOM element (a Storybook story root) into our own `LayerNode` tree
+// via getComputedStyle + getBoundingClientRect. Values are kept as `raw` CSS
+// strings so the token annotator can match them later; colors are also given
+// in Figma's {r,g,b}+opacity form for the materializer.
+//
+// Scope (v1): FRAME/RECTANGLE/TEXT; solid background fills; uniform border +
+// corner radius; a single box-shadow; text (family/weight/size/line-height/
+// letter-spacing/align/color); flex → auto-layout (+ padding); geometry
+// relative to each parent. Deferred: gradients, bg-images, transforms, grid,
+// pseudo-elements, SVG/img, per-side borders, multiple shadows.
+//
+// The DOM functions only run in a browser; the pure helpers are unit-tested.
+
+// ─── pure helpers (no DOM) ───────────────────────────────────────────────────
+
+/** "rgb(15, 101, 239)" / "rgba(…,a)" → { color:{r,g,b}, opacity, raw } or null. */
+export const rgbToFigma = (str) => {
+  if (str == null) return null
+  const s = String(str).trim()
+  const m = s.match(/^rgba?\(\s*([^)]+)\)$/i)
+  if (!m) return null
+  const p = m[1].split(',').map((x) => parseFloat(x.trim()))
+  if (p.length < 3 || p.some((n, i) => i < 3 && Number.isNaN(n))) return null
+  const a = p[3] === undefined ? 1 : p[3]
+  return { color: { r: p[0] / 255, g: p[1] / 255, b: p[2] / 255 }, opacity: a, raw: s }
+}
+
+/** "4px" → 4; "0px" → 0; "none"/"normal"/"" → null. */
+export const pxNum = (str) => {
+  if (str == null) return null
+  const m = String(str).trim().match(/^(-?\d+(?:\.\d+)?)px$/)
+  return m ? parseFloat(m[1]) : null
+}
+
+const FULLY_TRANSPARENT = (c) => !c || c.opacity === 0
+
+/** Parse a single CSS box-shadow into a Figma effect, or null for "none". */
+export const parseShadow = (str) => {
+  if (str == null) return null
+  const s = String(str).trim()
+  if (s === '' || s === 'none') return null
+  const inset = /\binset\b/.test(s)
+  const colorMatch = s.match(/rgba?\([^)]*\)|#[0-9a-f]{3,8}/i)
+  const color = colorMatch ? rgbToFigma(colorMatch[0]) : { color: { r: 0, g: 0, b: 0 }, opacity: 1, raw: 'rgb(0,0,0)' }
+  const rest = s.replace(colorMatch ? colorMatch[0] : '', '').replace(/\binset\b/, '')
+  const nums = (rest.match(/-?\d+(?:\.\d+)?px/g) || []).map((n) => pxNum(n))
+  const [x = 0, y = 0, blur = 0, spread = 0] = nums
+  return {
+    type: inset ? 'INNER_SHADOW' : 'DROP_SHADOW',
+    offset: { x, y },
+    radius: blur,
+    spread,
+    color,
+    raw: s,
+  }
+}
+
+/** CSS font-weight → number (normal=400, bold=700). */
+export const normalizeWeight = (w) => {
+  if (w === 'normal' || w == null) return 400
+  if (w === 'bold') return 700
+  const n = parseInt(w, 10)
+  return Number.isNaN(n) ? 400 : n
+}
+
+export const mapJustify = (v) =>
+  ({ 'flex-start': 'MIN', start: 'MIN', 'flex-end': 'MAX', end: 'MAX',
+     center: 'CENTER', 'space-between': 'SPACE_BETWEEN' })[v] || 'MIN'
+
+export const mapAlign = (v) =>
+  ({ 'flex-start': 'MIN', start: 'MIN', 'flex-end': 'MAX', end: 'MAX',
+     center: 'CENTER', baseline: 'MIN', stretch: 'MIN' })[v] || 'MIN'
+
+export const mapTextAlign = (v) =>
+  ({ left: 'LEFT', right: 'RIGHT', center: 'CENTER', justify: 'JUSTIFIED',
+     start: 'LEFT', end: 'RIGHT' })[v] || 'LEFT'
+
+const SKIP_TAGS = new Set(['SCRIPT', 'STYLE', 'LINK', 'META', 'HEAD', 'NOSCRIPT', 'BR'])
+
+// ─── DOM walker (browser only) ───────────────────────────────────────────────
+
+const firstFamily = (fontFamily) =>
+  String(fontFamily || '').split(',')[0].trim().replace(/^["']|["']$/g, '')
+
+const lineHeightOf = (cs) => {
+  if (cs.lineHeight === 'normal') return { unit: 'AUTO' }
+  const px = pxNum(cs.lineHeight)
+  return px == null ? { unit: 'AUTO' } : { unit: 'PIXELS', value: px }
+}
+
+const cornerRadiusOf = (cs) => {
+  const tl = pxNum(cs.borderTopLeftRadius) || 0
+  const tr = pxNum(cs.borderTopRightRadius) || 0
+  const br = pxNum(cs.borderBottomRightRadius) || 0
+  const bl = pxNum(cs.borderBottomLeftRadius) || 0
+  return tl === tr && tr === br && br === bl ? tl : [tl, tr, br, bl]
+}
+
+const isHidden = (cs) =>
+  cs.display === 'none' || cs.visibility === 'hidden' || cs.visibility === 'collapse'
+
+const textLayer = (textNode, cs, parentRect) => {
+  const value = textNode.nodeValue.replace(/\s+/g, ' ').trim()
+  if (!value) return null
+  const range = document.createRange()
+  range.selectNodeContents(textNode)
+  const r = range.getBoundingClientRect()
+  const fill = rgbToFigma(cs.color)
+  return {
+    type: 'TEXT',
+    name: value.slice(0, 40),
+    x: r.left - parentRect.left,
+    y: r.top - parentRect.top,
+    width: r.width,
+    height: r.height,
+    characters: value,
+    fontFamily: firstFamily(cs.fontFamily),
+    fontWeight: normalizeWeight(cs.fontWeight),
+    italic: cs.fontStyle === 'italic',
+    fontSize: pxNum(cs.fontSize) || 16,
+    lineHeight: lineHeightOf(cs),
+    letterSpacing: pxNum(cs.letterSpacing) || 0,
+    textAlign: mapTextAlign(cs.textAlign),
+    fills: FULLY_TRANSPARENT(fill) ? [] : [{ type: 'SOLID', ...fill }],
+  }
+}
+
+/**
+ * Capture one element (and its subtree) into a LayerNode.
+ * @param {Element} el
+ * @param {DOMRect} parentRect  rect to make this node's geometry relative to
+ * @returns {object|null} LayerNode, or null if skipped
+ */
+export const captureNode = (el, parentRect) => {
+  if (SKIP_TAGS.has(el.tagName)) return null
+  const cs = getComputedStyle(el)
+  if (isHidden(cs)) return null
+  const rect = el.getBoundingClientRect()
+
+  const bg = rgbToFigma(cs.backgroundColor)
+  const fills = FULLY_TRANSPARENT(bg) ? [] : [{ type: 'SOLID', ...bg }]
+
+  const borderW = pxNum(cs.borderTopWidth) || 0
+  const borderC = rgbToFigma(cs.borderTopColor)
+  const hasStroke = borderW > 0 && cs.borderTopStyle !== 'none' && !FULLY_TRANSPARENT(borderC)
+  const strokes = hasStroke ? [{ type: 'SOLID', ...borderC }] : []
+
+  const shadow = parseShadow(cs.boxShadow)
+
+  // drop entirely invisible, zero-area, contentless nodes
+  const area = rect.width * rect.height
+  if (area === 0 && !fills.length && !strokes.length) return null
+
+  const display = cs.display
+  const isFlex = display === 'flex' || display === 'inline-flex'
+  const layout = isFlex
+    ? {
+        mode: cs.flexDirection.startsWith('column') ? 'VERTICAL' : 'HORIZONTAL',
+        primaryAxisAlign: mapJustify(cs.justifyContent),
+        counterAxisAlign: mapAlign(cs.alignItems),
+        itemSpacing: pxNum(cs.columnGap) || pxNum(cs.gap) || 0,
+        paddingTop: pxNum(cs.paddingTop) || 0,
+        paddingRight: pxNum(cs.paddingRight) || 0,
+        paddingBottom: pxNum(cs.paddingBottom) || 0,
+        paddingLeft: pxNum(cs.paddingLeft) || 0,
+      }
+    : { mode: 'NONE' }
+
+  const node = {
+    type: 'FRAME',
+    name: el.tagName.toLowerCase(),
+    x: rect.left - parentRect.left,
+    y: rect.top - parentRect.top,
+    width: rect.width,
+    height: rect.height,
+    opacity: cs.opacity === '' ? 1 : parseFloat(cs.opacity),
+    clipsContent: cs.overflow === 'hidden' || cs.overflowX === 'hidden',
+    fills,
+    strokes,
+    strokeWeight: hasStroke ? borderW : 0,
+    cornerRadius: cornerRadiusOf(cs),
+    effects: shadow ? [shadow] : [],
+    layout,
+    children: [],
+  }
+
+  for (const child of el.childNodes) {
+    if (child.nodeType === 3 /* TEXT_NODE */) {
+      const t = textLayer(child, cs, rect)
+      if (t) node.children.push(t)
+    } else if (child.nodeType === 1 /* ELEMENT_NODE */) {
+      const c = captureNode(child, rect)
+      if (c) node.children.push(c)
+    }
+  }
+  return node
+}
+
+/** Entry point: capture a root element with itself at the origin (0,0). */
+export const captureRoot = (el) => captureNode(el, el.getBoundingClientRect())
+
+// Install the walker on `window` so it can be called from a Playwright
+// page.evaluate(() => window.__sorbCapture(...)) after this module is
+// bundled and injected via addInitScript. No-op in Node tests.
+if (typeof window !== 'undefined') {
+  window.__sorbCapture = (el) => captureRoot(el || document.querySelector('#storybook-root'))
+}

package/src/captureCli.js

@@ -0,0 +1,256 @@
+// `sorb-seed capture` — Playwright runner that visits each Storybook story,
+// injects our in-page walker, captures the rendered root, annotates tokens
+// against the resolved bindable map, and writes per-component artifacts +
+// a top-level index. See spec → Capture engine.
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'fs'
+import { createHash } from 'crypto'
+import { dirname, resolve, basename, extname } from 'path'
+import { build } from 'esbuild'
+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)
+  }
+}
+
+const cwd = process.cwd()
+
+const loadConfig = () => {
+  const p = resolve(cwd, 'sorb.config.json')
+  if (!existsSync(p)) {
+    console.error('✗ No sorb.config.json in', cwd)
+    process.exit(1)
+  }
+  return JSON.parse(readFileSync(p, 'utf-8'))
+}
+
+const loadResolved = () => {
+  const p = resolve(cwd, '.sorb/resolved.json')
+  if (!existsSync(p)) {
+    console.error('✗ No .sorb/resolved.json — run `sorb-seed resolve` first.')
+    process.exit(1)
+  }
+  const data = JSON.parse(readFileSync(p, 'utf-8'))
+  return Array.isArray(data) ? data : data.tokens
+}
+
+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')
+  return entries.filter((e) => re.test(e.importPath) || re.test(e.title) || re.test(e.id))
+}
+
+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,
+  )
+  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 chromium.launch()
+  const ctx = await browser.newContext({ viewport: { width: 1280, height: 800 } })
+  await ctx.addInitScript({ content: walker })
+
+  // 3. Capture each story, 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()
+    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 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
+      }
+      const tree = annotateTree(rawTree, index)
+      const hash = 'sha256:' + sha256(JSON.stringify(tree))
+
+      // --changed: reuse the previous artifact if hash matches
+      const prevHash = oldIndex.stories[entry.id]?.hash
+      if (opts.changed && prevHash === hash) {
+        console.log('    = unchanged')
+        await page.close()
+        continue
+      }
+
+      if (!captured.has(entry.importPath)) {
+        captured.set(entry.importPath, {
+          schemaVersion: 1,
+          component: componentNameFromImportPath(entry.importPath),
+          importPath: entry.importPath,
+          capturedAt: new Date().toISOString(),
+          stories: [],
+        })
+      }
+      captured.get(entry.importPath).stories.push({
+        id: entry.id,
+        name: entry.name,
+        title: entry.title,
+        hash,
+        root: tree,
+      })
+    } catch (e) {
+      console.error('    ✗', entry.id, '—', e.message)
+    } finally {
+      await page.close()
+    }
+  }
+  await browser.close()
+
+  // 4. Write artifacts next to each story file, then the index
+  const indexOut = {
+    schemaVersion: 1,
+    generatedAt: new Date().toISOString(),
+    storybookUrl: sbUrl,
+    components: [],
+    stories: { ...oldIndex.stories }, // preserves entries we didn't recapture
+  }
+  for (const [importPath, art] of captured) {
+    const absStoryFile = resolve(cwd, importPath)
+    const outDir = dirname(absStoryFile)
+    if (!existsSync(outDir)) mkdirSync(outDir, { recursive: true })
+    const outPath = resolve(outDir, `${art.component}.sorb.json`)
+    writeFileSync(outPath, JSON.stringify(art, null, 2) + '\n')
+    const rel = relativeFromCwd(outPath)
+    console.log(`✓ ${rel}  (${art.stories.length} stor${art.stories.length === 1 ? 'y' : 'ies'})`)
+    indexOut.components.push({ component: art.component, importPath, artifact: rel })
+    for (const s of art.stories) {
+      indexOut.stories[s.id] = {
+        component: art.component,
+        importPath,
+        artifact: rel,
+        title: s.title,
+        name: s.name,
+        hash: s.hash,
+      }
+    }
+  }
+
+  const indexDir = resolve(cwd, '.sorb')
+  mkdirSync(indexDir, { recursive: true })
+  writeFileSync(
+    resolve(indexDir, 'index.json'),
+    JSON.stringify(indexOut, null, 2) + '\n',
+  )
+  console.log('→ .sorb/index.json')
+}
+
+const relativeFromCwd = (abs) => {
+  const c = cwd.endsWith('/') ? cwd : cwd + '/'
+  return abs.startsWith(c) ? abs.slice(c.length) : abs
+}
+
+const readOldIndex = (config) => {
+  const p = resolve(cwd, '.sorb/index.json')
+  if (!existsSync(p)) return { stories: {} }
+  try { return JSON.parse(readFileSync(p, 'utf-8')) } catch { return { stories: {} } }
+}
+
+// Allow running as `node captureCli.js [--only=...] [--changed]` for testing;
+// the package bin (`sorb-seed capture`) routes here via cli.js.
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const opts = {}
+  for (const a of process.argv.slice(2)) {
+    if (a === '--changed') opts.changed = true
+    else if (a.startsWith('--only=')) opts.only = a.slice('--only='.length)
+    else if (a.startsWith('--storybook-url=')) opts.storybookUrl = a.slice('--storybook-url='.length)
+  }
+  runCapture(opts).catch((e) => { console.error(e); process.exit(1) })
+}

package/src/cli.js

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+import { readFileSync, existsSync } from 'fs'
+import { resolve } from 'path'
+import { execSync } from 'child_process'
+
+// sorb-seed — Storybook → Figma capture tooling.
+//
+// `resolve` is now a thin wrapper around Style Dictionary: the DTCG token sets
+// (primitive/semantic/component) are the source of truth, and SD's
+// `sorb/resolved-map` format produces `.sorb/resolved.json` directly —
+// the schema { id, cssVar, value, tier, type }. This retires the old
+// esbuild-bundle-and-eval resolver (and its theme.js scraping). The app build
+// owns SD; the bridge and `capture` are pure consumers of its output.
+
+const cwd = process.cwd()
+
+const loadConfig = () => {
+  const p = resolve(cwd, 'sorb.config.json')
+  if (!existsSync(p)) {
+    console.error('✗ No sorb.config.json in', cwd)
+    process.exit(1)
+  }
+  return JSON.parse(readFileSync(p, 'utf-8'))
+}
+
+const cmd = process.argv[2] || 'resolve'
+
+if (cmd === 'resolve') {
+  const config = loadConfig()
+  const sdConfig = config.styleDictionaryConfig || 'sd.config.js'
+  const abs = resolve(cwd, sdConfig)
+  if (!existsSync(abs)) {
+    console.error(
+      '✗ Style Dictionary config not found:', sdConfig,
+      '\n  Set "styleDictionaryConfig" in sorb.config.json (default: sd.config.js).',
+    )
+    process.exit(1)
+  }
+  try {
+    console.log('→ Running Style Dictionary:', sdConfig)
+    execSync(`npx style-dictionary build --config ${abs}`, { stdio: 'inherit', cwd })
+    console.log('✓ Built .sorb/resolved.json (and CSS vars + theme) from DTCG sources')
+  } catch (e) {
+    console.error('✗ Style Dictionary build failed')
+    process.exit(1)
+  }
+} else if (cmd === 'capture') {
+  const { runCapture } = await import('./captureCli.js')
+  const opts = {}
+  for (const a of process.argv.slice(3)) {
+    if (a === '--changed') opts.changed = true
+    else if (a.startsWith('--only=')) opts.only = a.slice('--only='.length)
+    else if (a.startsWith('--storybook-url=')) opts.storybookUrl = a.slice('--storybook-url='.length)
+  }
+  await runCapture(opts)
+} else {
+  console.error(`Unknown command: ${cmd}\nUsage: sorb-seed <resolve|capture> [options]`)
+  process.exit(1)
+}

package/src/index.js

@@ -0,0 +1,7 @@
+// Public library surface for @sorb/seed.
+//
+// The resolved bindable token map is now produced by Style Dictionary (see
+// `sorb-seed resolve`, a thin SD wrapper), not by scraping a theme module —
+// 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'