@sorb/seed 0.1.0 → 0.2.0

package/src/annotateTokens.test.js

@@ -0,0 +1,208 @@
+// Tests for the capture token-annotator (auto-bind: property affinity + tier
+// precedence). Run: node --test  (zero-dep; resolves @sorb/core via the workspace link).
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import {
+  normalizeColor,
+  classifyColor,
+  normalizeDimension,
+  buildTokenIndex,
+  matchColor,
+  matchDimension,
+  annotateTree,
+} from './annotateTokens.js'
+
+// A resolved map where one color value (#0f65ef) is shared across a component
+// bg, a component border, a semantic bg, and a semantic border — so the tests
+// exercise BOTH role affinity (which property) and tier precedence (the tiebreak).
+const RESOLVED = [
+  { id: 'button.primary.bg.default', cssVar: '--button-primary-bg-default', value: '#0f65ef', tier: 'component', type: 'color' },
+  { id: 'button.primary.border.default', cssVar: '--button-primary-border-default', value: '#0F65EF', tier: 'component', type: 'color' },
+  { id: 'color.action.primary', cssVar: '--color-action-primary', value: '#0f65ef', tier: 'semantic', type: 'color' },
+  { id: 'color.border.default', cssVar: '--color-border-default', value: '#0f65ef', tier: 'semantic', type: 'color' },
+  { id: 'button.primary.text.default', cssVar: '--button-primary-text-default', value: '#ffffff', tier: 'component', type: 'color' },
+  { id: 'button.radius', cssVar: '--button-radius', value: '4px', tier: 'component', type: 'dimension' },
+]
+
+test('normalizeColor handles hex (3/4/6/8), rgb(a), transparent, and rejects junk', () => {
+  assert.equal(normalizeColor('#fff'), '#ffffffff')
+  assert.equal(normalizeColor('#FFFF'), '#ffffffff')
+  assert.equal(normalizeColor('#0f65ef'), '#0f65efff')
+  assert.equal(normalizeColor('#0F65EF80'), '#0f65ef80')
+  assert.equal(normalizeColor('rgb(15, 101, 239)'), '#0f65efff')
+  assert.equal(normalizeColor('rgba(0,0,0,0)'), '#00000000')
+  assert.equal(normalizeColor('transparent'), '#00000000')
+  assert.equal(normalizeColor('not-a-color'), null)
+  assert.equal(normalizeColor(null), null)
+})
+
+test('normalizeDimension parses px / unitless / decimals, rejects non-lengths', () => {
+  assert.equal(normalizeDimension('4px'), 4)
+  assert.equal(normalizeDimension('4'), 4)
+  assert.equal(normalizeDimension(8), 8)
+  assert.equal(normalizeDimension('2.5px'), 2.5)
+  assert.equal(normalizeDimension('-1px'), -1)
+  assert.equal(normalizeDimension('1rem'), null)
+  assert.equal(normalizeDimension(null), null)
+})
+
+test('buildTokenIndex groups tokens by normalized value into colors/dims', () => {
+  const idx = buildTokenIndex(RESOLVED)
+  assert.equal(idx.colors.get('#0f65efff').length, 4) // four tokens share this color
+  assert.equal(idx.colors.get('#ffffffff').length, 1)
+  assert.equal(idx.dims.get(4).length, 1)
+})
+
+test('matchColor: role affinity picks the right property family', () => {
+  const idx = buildTokenIndex(RESOLVED)
+  // bg role → only the component bg carries `.bg`
+  assert.equal(matchColor(idx, '#0f65ef', 'bg').token, 'button.primary.bg.default')
+  // border role → two `.border` cands; tier tiebreak picks component over semantic
+  assert.equal(matchColor(idx, '#0f65ef', 'border').token, 'button.primary.border.default')
+})
+
+test('matchColor: all matches are kept as candidates regardless of the pick', () => {
+  const idx = buildTokenIndex(RESOLVED)
+  const res = matchColor(idx, '#0f65ef', 'bg')
+  assert.equal(res.candidates.length, 4)
+  assert.ok(res.candidates.includes('color.action.primary'))
+})
+
+test('matchColor: with no role, tier precedence wins (component beats semantic)', () => {
+  const idx = buildTokenIndex(RESOLVED)
+  const res = matchColor(idx, '#0f65ef')
+  assert.ok(['button.primary.bg.default', 'button.primary.border.default'].includes(res.token))
+})
+
+test('matchColor / matchDimension return null token for a value with no match', () => {
+  const idx = buildTokenIndex(RESOLVED)
+  assert.equal(matchColor(idx, '#123456', 'bg').token, null)
+  assert.equal(matchDimension(idx, 99, 'radius').token, null)
+})
+
+test('matchDimension binds a radius value to the component radius token', () => {
+  const idx = buildTokenIndex(RESOLVED)
+  assert.equal(matchDimension(idx, 4, 'radius').token, 'button.radius')
+})
+
+test('annotateTree binds a button: fill→bg, stroke→border, radius, TEXT child→text', () => {
+  const idx = buildTokenIndex(RESOLVED)
+  const node = {
+    type: 'FRAME',
+    fills: [{ raw: '#0f65ef' }],
+    strokes: [{ raw: '#0f65ef' }],
+    cornerRadius: 4,
+    children: [{ type: 'TEXT', fills: [{ raw: '#ffffff' }] }],
+  }
+  const out = annotateTree(node, idx)
+  assert.equal(out.sorb.tokens.fill, 'button.primary.bg.default')
+  assert.equal(out.sorb.tokens.stroke, 'button.primary.border.default')
+  assert.equal(out.sorb.tokens.cornerRadius, 'button.radius')
+  // a fill on a TEXT node is foreground → the `text` role
+  assert.equal(out.children[0].sorb.tokens.fill, 'button.primary.text.default')
+})
+
+test('annotateTree leaves unmatched nodes without a `sorb` key', () => {
+  const idx = buildTokenIndex(RESOLVED)
+  const node = { type: 'FRAME', fills: [{ raw: '#abcdef' }] }
+  const out = annotateTree(node, idx)
+  assert.equal(out.sorb, undefined)
+})
+
+// ── REC-6: CSS named-color support + unparseable/no-match marker ──────────────
+
+test('REC-6: normalizeColor resolves common CSS named colors', () => {
+  assert.equal(normalizeColor('red'), '#ff0000ff')
+  assert.equal(normalizeColor('WHITE'), '#ffffffff') // case-insensitive
+  assert.equal(normalizeColor('rebeccapurple'), null) // not in the minimal table → no-match
+  assert.equal(normalizeColor('purple'), '#800080ff')
+})
+
+test('REC-6: classifyColor distinguishes ok / no-match / unparseable', () => {
+  assert.deepEqual(classifyColor('#0f65ef'), { hex: '#0f65efff', status: 'ok' })
+  assert.deepEqual(classifyColor('blue'), { hex: '#0000ffff', status: 'ok' })
+  // a `#`-prefixed but malformed value is recognized-but-unparseable, not just no-match
+  assert.equal(classifyColor('#ggg').status, 'unparseable')
+  assert.equal(classifyColor('#12').status, 'unparseable')
+  assert.equal(classifyColor('rgb(1,2)').status, 'unparseable')
+  assert.equal(classifyColor('rgb(x,y,z)').status, 'unparseable')
+  // a clean non-color (e.g. a dimension) is no-match, not unparseable
+  assert.equal(classifyColor('4px').status, 'no-match')
+  assert.equal(classifyColor('not-a-color').status, 'no-match')
+  assert.equal(classifyColor(null).status, 'no-match')
+})
+
+test('REC-6: normalizeColor tolerates exotic whitespace (NBSP) around a hex', () => {
+  assert.equal(normalizeColor(' #0f65ef '), '#0f65efff')
+})
+
+// ── REC-1: buildTokenIndex.dropped[] for vanished tokens ─────────────────────
+
+test('REC-1: buildTokenIndex still destructures to {colors, dims} (backward-compat)', () => {
+  const { colors, dims, dropped } = buildTokenIndex(RESOLVED)
+  assert.ok(colors.get('#0f65efff'))
+  assert.ok(dims.get(4))
+  assert.deepEqual(dropped, []) // a clean map drops nothing
+})
+
+test('REC-1: an unparseable-color token is dropped with a marker reason', () => {
+  const { dropped } = buildTokenIndex([
+    { id: 'color.bad', cssVar: '--bad', value: '#ggg', tier: 'semantic', type: 'color' },
+  ])
+  assert.equal(dropped.length, 1)
+  assert.equal(dropped[0].id, 'color.bad')
+  assert.equal(dropped[0].reason, 'unparseable-color')
+})
+
+test('REC-1: a no-match token (NBSP-only / junk) is dropped as no-match', () => {
+  const { dropped } = buildTokenIndex([
+    { id: 'space.weird', cssVar: '--w', value: ' ', tier: 'primitive', type: 'dimension' },
+  ])
+  assert.equal(dropped.length, 1)
+  assert.equal(dropped[0].reason, 'no-match')
+})
+
+// ── REC-2: unresolved-alias / cycle detection ────────────────────────────────
+
+test('REC-2: a still-wrapped {…} value is dropped as unresolved-alias (not thrown)', () => {
+  const { dropped, colors } = buildTokenIndex([
+    { id: 'color.action', cssVar: '--a', value: '{color.brand.primary}', tier: 'semantic', type: 'color' },
+    { id: 'color.brand.primary', cssVar: '--p', value: '#0f65ef', tier: 'primitive', type: 'color' },
+  ])
+  const alias = dropped.find((d) => d.id === 'color.action')
+  assert.ok(alias)
+  assert.equal(alias.reason, 'unresolved-alias')
+  // the real token still indexed normally
+  assert.ok(colors.get('#0f65efff'))
+})
+
+test('REC-2: an A↔B alias cycle is detected and dropped as alias-cycle', () => {
+  const { dropped } = buildTokenIndex([
+    { id: 'a', cssVar: '--a', value: '{b}', tier: 'semantic', type: 'color' },
+    { id: 'b', cssVar: '--b', value: '{a}', tier: 'semantic', type: 'color' },
+  ])
+  const reasons = dropped.map((d) => d.reason)
+  assert.equal(dropped.length, 2)
+  assert.ok(reasons.every((r) => r === 'alias-cycle'))
+})
+
+// ── pick() off-role fallback → low-confidence diagnostic ─────────────────────
+
+test('off-role fallback bind is surfaced as a low-confidence diagnostic', () => {
+  // #ffffff only carries a `.text` token; binding it as a frame `bg` fill is off-role.
+  const idx = buildTokenIndex(RESOLVED)
+  const node = { type: 'FRAME', fills: [{ raw: '#ffffff' }] }
+  const out = annotateTree(node, idx)
+  assert.equal(out.sorb.tokens.fill, 'button.primary.text.default') // still binds
+  assert.ok(Array.isArray(out.sorb.diagnostics))
+  assert.equal(out.sorb.diagnostics[0].kind, 'off-role-bind')
+  assert.equal(out.sorb.diagnostics[0].detail.role, 'bg')
+})
+
+test('an on-role bind attaches no diagnostics (additive, only when needed)', () => {
+  const idx = buildTokenIndex(RESOLVED)
+  const node = { type: 'FRAME', fills: [{ raw: '#0f65ef' }] }
+  const out = annotateTree(node, idx)
+  assert.equal(out.sorb.tokens.fill, 'button.primary.bg.default')
+  assert.equal(out.sorb.diagnostics, undefined)
+})

package/src/capture.js

@@ -201,6 +201,106 @@ export const captureNode = (el, parentRect) => {
 /** Entry point: capture a root element with itself at the origin (0,0). */
 export const captureRoot = (el) => captureNode(el, el.getBoundingClientRect())
 
+// ─── Capture root trim (sorb-capture-trim-spec.md) ──────────────────────────
+// Storybook wraps each story in full-width padded divs, so a raw captured root
+// is the story container (e.g. 1248×86) with the real component (button 82×38)
+// nested at an offset inside empty wrappers. `tightenRoot` trims the tree to the
+// meaningful component AT CAPTURE TIME so every consumer (insert, preview, label
+// wrapper) gets a tight, token-bound node. Pure + annotation-safe: it runs in
+// captureCli BEFORE annotateTree, and only drops un-annotated, non-visual
+// wrappers, so token bindings on the kept subtree are untouched.
+
+/**
+ * "Content-bearing" = the node, or any descendant, paints (a non-transparent
+ * fill or a stroke) or is TEXT. Same notion as the preview SVG walker.
+ * @param {object} node LayerNode
+ * @returns {boolean}
+ */
+export const hasContent = (node) => {
+  if (!node) return false
+  if (node.type === 'TEXT') return true
+  if ((node.fills && node.fills[0]) || (node.strokes && node.strokes[0])) return true
+  return (node.children || []).some(hasContent)
+}
+
+/** A node that ITSELF paints (own fill/stroke) or is TEXT — vs a transparent wrapper. */
+const selfPaints = (node) =>
+  node.type === 'TEXT' || !!(node.fills && node.fills[0]) || !!(node.strokes && node.strokes[0])
+
+/**
+ * Union of the rects of all self-painting (or TEXT) nodes in `node`'s subtree,
+ * expressed in `node`'s LOCAL coordinate space (node's own origin = 0,0).
+ * Returns null when nothing in the subtree paints. Children carry offsets
+ * relative to their parent, so the walk accumulates them; negative/overflow
+ * offsets are included (the union never clips content).
+ * @param {object} node
+ * @returns {{minX:number,minY:number,maxX:number,maxY:number}|null}
+ */
+export const contentBBox = (node) => {
+  let box = null
+  const acc = (n, ox, oy) => {
+    if (!n) return
+    if (selfPaints(n)) {
+      const x1 = ox + (n.width || 0)
+      const y1 = oy + (n.height || 0)
+      if (box === null) box = { minX: ox, minY: oy, maxX: x1, maxY: y1 }
+      else {
+        if (ox < box.minX) box.minX = ox
+        if (oy < box.minY) box.minY = oy
+        if (x1 > box.maxX) box.maxX = x1
+        if (y1 > box.maxY) box.maxY = y1
+      }
+    }
+    for (const c of n.children || []) acc(c, ox + (c.x || 0), oy + (c.y || 0))
+  }
+  acc(node, 0, 0)
+  return box
+}
+
+/**
+ * Trim a captured root to its meaningful component:
+ *  1) descend through pure pass-through wrappers (a single content-bearing,
+ *     non-TEXT child, and no paint of their own),
+ *  2) crop the kept node to its content bounding box and normalize direct-child
+ *     offsets so content sits at the origin.
+ * Mutates the kept node's geometry in step 2 and returns it. See
+ * sorb-capture-trim-spec.md §3.
+ * @param {object} root LayerNode
+ * @returns {object} the tightened node
+ */
+export const tightenRoot = (root) => {
+  if (!root) return root
+  let node = root
+  // 1) descend through pure pass-through wrappers
+  while (true) {
+    const selfVisual = (node.fills && node.fills[0]) || (node.strokes && node.strokes[0])
+    if (selfVisual) break // node paints something → keep it
+    const kids = (node.children || []).filter(hasContent)
+    // unwrap a sole content-bearing child UNLESS it is TEXT (the wrapper carries
+    // the component's frame; don't descend into raw text). Multiple content kids
+    // (e.g. a variant row) → stop here.
+    if (kids.length === 1 && kids[0].type !== 'TEXT') {
+      node = kids[0]
+      continue
+    }
+    break
+  }
+  // 2) crop node to the bbox of its content (local coords)
+  const bbox = contentBBox(node)
+  if (bbox === null) return node // nothing drawn → leave as-is
+  const dx = bbox.minX
+  const dy = bbox.minY
+  for (const child of node.children || []) {
+    child.x = (child.x || 0) - dx
+    child.y = (child.y || 0) - dy
+  }
+  node.x = 0
+  node.y = 0
+  node.width = bbox.maxX - bbox.minX
+  node.height = bbox.maxY - bbox.minY
+  return node
+}
+
 // 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.

package/src/capture.test.js

@@ -0,0 +1,142 @@
+// Unit tests for the capture root-trim helpers (sorb-capture-trim-spec.md §6).
+// Pure geometry — no Playwright/DOM needed. Run: `node --test src/capture.test.js`.
+
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { hasContent, contentBBox, tightenRoot } from './capture.js'
+
+// ─── tiny LayerNode factories ───────────────────────────────────────────────
+const SOLID = [{ type: 'SOLID', r: 0.1, g: 0.3, b: 0.9 }]
+
+/** A FRAME. Pass `{ fill: true }` to make it self-painting. */
+const frame = (x, y, w, h, opts = {}, children = []) => ({
+  type: 'FRAME',
+  name: opts.name || 'div',
+  x, y, width: w, height: h,
+  fills: opts.fill ? SOLID : [],
+  strokes: opts.stroke ? SOLID : [],
+  children,
+})
+
+const text = (x, y, w, h, value = 'Primary') => ({
+  type: 'TEXT', name: value, x, y, width: w, height: h, fills: SOLID, children: [],
+})
+
+// ─── hasContent ─────────────────────────────────────────────────────────────
+test('hasContent: TEXT, painted frame, and nested content are content-bearing', () => {
+  assert.equal(hasContent(text(0, 0, 10, 10)), true)
+  assert.equal(hasContent(frame(0, 0, 10, 10, { fill: true })), true)
+  assert.equal(hasContent(frame(0, 0, 10, 10, { stroke: true })), true)
+  // transparent wrapper around a painted child → content-bearing via descendant
+  assert.equal(hasContent(frame(0, 0, 10, 10, {}, [frame(0, 0, 5, 5, { fill: true })])), true)
+  // empty transparent wrapper → not content-bearing
+  assert.equal(hasContent(frame(0, 0, 10, 10, {}, [frame(0, 0, 5, 5)])), false)
+  assert.equal(hasContent(null), false)
+})
+
+// ─── contentBBox ────────────────────────────────────────────────────────────
+test('contentBBox: union of painted/text rects in local coords; null when nothing paints', () => {
+  // a painted button with an inset text label
+  const button = frame(0, 0, 82, 38, { fill: true }, [text(16, 10, 50, 18)])
+  assert.deepEqual(contentBBox(button), { minX: 0, minY: 0, maxX: 82, maxY: 38 })
+
+  // transparent wrapper: bbox bounds only the painted descendants (accumulated offset)
+  const wrapped = frame(0, 0, 200, 100, {}, [frame(20, 30, 40, 20, { fill: true })])
+  assert.deepEqual(contentBBox(wrapped), { minX: 20, minY: 30, maxX: 60, maxY: 50 })
+
+  // nothing drawn → null
+  assert.equal(contentBBox(frame(0, 0, 100, 100, {}, [frame(0, 0, 10, 10)])), null)
+})
+
+test('contentBBox: negative/overflow offsets are included (never clips content)', () => {
+  const n = frame(0, 0, 100, 100, {}, [
+    frame(-5, -8, 10, 10, { fill: true }),
+    frame(90, 95, 20, 20, { fill: true }),
+  ])
+  assert.deepEqual(contentBBox(n), { minX: -5, minY: -8, maxX: 110, maxY: 115 })
+})
+
+// ─── tightenRoot: the three canonical shapes (spec §6) ──────────────────────
+test('tightenRoot: single component — descends wrappers, crops to the button (82×38 at origin)', () => {
+  // story 1248×86 → wrapper → wrapper → button 82×38 @(24,24) → text
+  const tree = frame(0, 0, 1248, 86, {}, [
+    frame(0, 0, 1248, 86, {}, [
+      frame(0, 0, 1248, 86, {}, [
+        frame(24, 24, 82, 38, { fill: true, name: 'button' }, [text(16, 10, 50, 18)]),
+      ]),
+    ]),
+  ])
+  const out = tightenRoot(tree)
+  assert.equal(out.name, 'button')
+  assert.equal(out.x, 0)
+  assert.equal(out.y, 0)
+  assert.equal(out.width, 82)
+  assert.equal(out.height, 38)
+  // the text child is preserved (annotation-safe) and unshifted (dx=dy=0)
+  assert.equal(out.children.length, 1)
+  assert.equal(out.children[0].type, 'TEXT')
+})
+
+test('tightenRoot: multi-child row — stops at the row, crops to the variant group (tight, not 1248)', () => {
+  // a row of three buttons, left-padded by 10
+  const row = frame(0, 0, 1248, 40, { name: 'row' }, [
+    frame(10, 0, 80, 40, { fill: true }, [text(8, 10, 40, 18)]),
+    frame(110, 0, 90, 40, { fill: true }, [text(8, 10, 50, 18)]),
+    frame(210, 0, 70, 40, { fill: true }, [text(8, 10, 40, 18)]),
+  ])
+  const tree = frame(0, 0, 1248, 40, {}, [row])
+  const out = tightenRoot(tree)
+  assert.equal(out.name, 'row')
+  assert.equal(out.x, 0)
+  assert.equal(out.width, 270) // (210+70) - 10  → tight row, not 1248
+  assert.equal(out.height, 40)
+  assert.equal(out.children.length, 3)
+  assert.equal(out.children[0].x, 0) // first button shifted left by dx=10
+  assert.equal(out.children[1].x, 100)
+  assert.equal(out.children[2].x, 200)
+})
+
+test('tightenRoot: visual card — descent stops at the painted surface (kept, not skipped)', () => {
+  const card = frame(20, 10, 320, 180, { fill: true, name: 'card' }, [
+    frame(16, 16, 200, 24, {}, [text(0, 0, 180, 20, 'Title')]),
+  ])
+  const tree = frame(0, 0, 1248, 220, {}, [card])
+  const out = tightenRoot(tree)
+  assert.equal(out.name, 'card')
+  assert.equal(out.width, 320) // card surface preserved
+  assert.equal(out.height, 180)
+  assert.equal(out.x, 0)
+})
+
+// ─── tightenRoot: edge cases (spec §5) ──────────────────────────────────────
+test('tightenRoot: sole child is TEXT — does not descend into raw text; crops the wrapper to it', () => {
+  const tree = frame(0, 0, 200, 50, { name: 'label-wrap' }, [text(5, 5, 40, 16, 'Hi')])
+  const out = tightenRoot(tree)
+  assert.equal(out.name, 'label-wrap') // kept the wrapper, not the TEXT
+  assert.equal(out.width, 40)
+  assert.equal(out.height, 16)
+  assert.equal(out.children[0].x, 0) // text normalized to origin
+  assert.equal(out.children[0].y, 0)
+})
+
+test('tightenRoot: nothing drawn — returns the tree untouched, no crash', () => {
+  const tree = frame(0, 0, 100, 100, {}, [frame(0, 0, 50, 50)])
+  const out = tightenRoot(tree)
+  assert.equal(out, tree) // unchanged reference
+  assert.equal(out.width, 100)
+})
+
+test('tightenRoot: wrapper with its OWN bound fill stops descent (no lost token surface)', () => {
+  // an Alert/Card whose background is token-bound: selfVisual → keep it
+  const alert = frame(0, 0, 600, 60, { fill: true, name: 'alert' }, [
+    frame(0, 0, 600, 60, {}, [text(12, 20, 200, 18, 'Heads up')]),
+  ])
+  const tree = frame(0, 0, 1248, 60, {}, [alert])
+  const out = tightenRoot(tree)
+  assert.equal(out.name, 'alert')
+  assert.equal(out.width, 600)
+})
+
+test('tightenRoot: null/empty input is safe', () => {
+  assert.equal(tightenRoot(null), null)
+})

package/src/captureCli.js

@@ -7,6 +7,7 @@ import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'fs'
 import { createHash } from 'crypto'
 import { dirname, resolve, basename, extname } from 'path'
 import { build } from 'esbuild'
+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
@@ -26,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 = () => {
@@ -126,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 })
 
@@ -159,7 +181,12 @@ export const runCapture = async (opts) => {
         await page.close()
         continue
       }
-      const tree = annotateTree(rawTree, index)
+      // 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
+      // token bindings are unaffected.
+      const tightened = tightenRoot(rawTree)
+      const tree = annotateTree(tightened, index)
       const hash = 'sha256:' + sha256(JSON.stringify(tree))
 
       // --changed: reuse the previous artifact if hash matches