@sorb/seed 0.1.1 → 0.3.0

package/src/sources/figmaPlugin.test.js

@@ -0,0 +1,65 @@
+// Tests for the `figma-plugin` SourceConnector (figma-source-connector.md
+// §1a). Mirrors the contract-registration style of sorb-core's
+// connectors.test.js dummy-source test, plus exercises readTokens() as a
+// bridge CLIENT against a mocked `fetch` (no real juice server needed —
+// the contract is "GET /tokens/figma returns { tokens: ResolvedToken[] }").
+import test from 'node:test'
+import assert from 'node:assert/strict'
+import { connectors, getSource } from '@sorb/core'
+import { figmaPluginConnector, bridgeOriginOf } from './figmaPlugin.js'
+
+test('registers under id "figma-plugin" and round-trips via getSource (contract dispatch)', () => {
+  assert.equal(getSource('figma-plugin'), figmaPluginConnector)
+  assert.equal(connectors.source.get('figma-plugin'), figmaPluginConnector)
+})
+
+test('bridgeOriginOf: defaults to the juice dev port, honors seed.bridgeOrigin, strips trailing slash', () => {
+  assert.equal(bridgeOriginOf({}), 'http://localhost:7777')
+  assert.equal(bridgeOriginOf(), 'http://localhost:7777')
+  assert.equal(bridgeOriginOf({ seed: { bridgeOrigin: 'http://localhost:9999/' } }), 'http://localhost:9999')
+  assert.equal(bridgeOriginOf({ bridgeOrigin: 'http://example.com/' }), 'http://example.com')
+})
+
+test('readTokens: reads the resolved-map array back from GET /tokens/figma', async (t) => {
+  const tokens = [{ id: 'color.bg.primary', cssVar: '--color-bg-primary', value: '#ffffff', tier: 'primitive', type: 'color' }]
+  const calls = []
+  const realFetch = global.fetch
+  global.fetch = async (url) => {
+    calls.push(url)
+    return { ok: true, status: 200, json: async () => ({ fileKey: 'abc', exportedAt: '2026-08-29T00:00:00Z', tokens }) }
+  }
+  t.after(() => { global.fetch = realFetch })
+
+  const got = await figmaPluginConnector.readTokens({ seed: { bridgeOrigin: 'http://localhost:7777' } })
+  assert.deepEqual(got, tokens)
+  assert.equal(calls[0], 'http://localhost:7777/tokens/figma')
+})
+
+test('readTokens: 404 (no export yet) throws an actionable "Export variables" error', async (t) => {
+  const realFetch = global.fetch
+  global.fetch = async () => ({ ok: false, status: 404, json: async () => ({ error: 'No Figma export yet.' }) })
+  t.after(() => { global.fetch = realFetch })
+
+  await assert.rejects(() => figmaPluginConnector.readTokens({}), /Export variables/)
+})
+
+test('readTokens: non-2xx, non-404 → surfaces the HTTP status', async (t) => {
+  const realFetch = global.fetch
+  global.fetch = async () => ({ ok: false, status: 500, json: async () => ({}) })
+  t.after(() => { global.fetch = realFetch })
+
+  await assert.rejects(() => figmaPluginConnector.readTokens({}), /HTTP 500/)
+})
+
+test('readTokens: network failure (bridge not running) → actionable error naming the origin', async (t) => {
+  const realFetch = global.fetch
+  global.fetch = async () => { throw new Error('ECONNREFUSED') }
+  t.after(() => { global.fetch = realFetch })
+
+  await assert.rejects(() => figmaPluginConnector.readTokens({}), /could not reach the bridge at http:\/\/localhost:7777/)
+})
+
+test('listUnits/captureGeometry: v1 tokens-first scope — throw a clear not-yet-implemented error, not a silent no-op', async () => {
+  await assert.rejects(() => figmaPluginConnector.listUnits({}), /not implemented in v1/)
+  await assert.rejects(() => figmaPluginConnector.captureGeometry({ id: 'u1' }, {}), /not implemented in v1/)
+})

package/src/sources/storybookDom.js

@@ -0,0 +1,188 @@
+// `storybook-dom` SourceConnector — the default SOURCE connector (registered
+// under `@sorb/core`'s DEFAULT_SOURCE_ID = 'storybook-dom'). Extracted from
+// captureCli.js verbatim (spec/sorb/connectors-architecture.md §3.1, C1) — a
+// pure refactor, no behavior change. Owns everything source-specific:
+// discovering Storybook story entries (`listUnits`), running Playwright +
+// the `capture.js` walker to capture one entry's raw geometry
+// (`captureGeometry`), and reading the DTCG/Style-Dictionary resolved token
+// map (`readTokens`). The generic pipeline (tightenRoot -> annotateTree ->
+// hash -> write) stays in captureCli.js and is fed by this connector.
+
+import { basename, extname, dirname, resolve } from 'path'
+import { readFileSync, existsSync } from 'fs'
+import { build } from 'esbuild'
+import { registerSource } from '@sorb/core'
+
+// 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
+  }
+}
+
+// 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'
+
+// 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.
+export const storybookUrlOf = (config) =>
+  (config.seed && config.seed.storybookUrl) || 'http://localhost:6006'
+
+// ─── Playwright session (browser + context + walker init script) ──────────
+// Lazily launched on the first captureGeometry() call and reused across every
+// unit in a run — exactly today's single-launch/many-pages lifecycle. Not
+// part of the shared SourceConnector contract (that's just listUnits /
+// captureGeometry / readTokens); captureCli.js calls closeSession() once
+// after it has processed every unit, mirroring today's single browser.close().
+let session = null // { browser, ctx, sbUrl }
+
+const ensureSession = async (sbUrl) => {
+  if (session && session.sbUrl === sbUrl) return session
+  if (session) await closeSession()
+  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 })
+  session = { browser, ctx, sbUrl }
+  return session
+}
+
+export const closeSession = async () => {
+  if (session) {
+    await session.browser.close()
+    session = null
+  }
+}
+
+// ─── SourceConnector implementation ────────────────────────────────────────
+
+const listUnits = async (config) => {
+  const sbUrl = storybookUrlOf(config).replace(/\/$/, '')
+  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 = Object.values(sbIndex.entries || sbIndex.stories || {}).filter(isStoryEntry)
+  return entries.map((e) => ({
+    id: e.id,
+    name: e.name,
+    title: e.title,
+    importPath: e.importPath,
+  }))
+}
+
+const captureGeometry = async (unit, config) => {
+  const sbUrl = storybookUrlOf(config).replace(/\/$/, '')
+  const { ctx } = await ensureSession(sbUrl)
+  const url = `${sbUrl}/iframe.html?id=${unit.id}&viewMode=story`
+  const page = await ctx.newPage()
+  try {
+    console.log(`  · ${unit.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')
+      return null
+    }
+    return rawTree
+  } finally {
+    await page.close()
+  }
+}
+
+// Thin wrapper over the resolved bindable token map produced by `sorb-seed
+// resolve` (Style Dictionary build against the DTCG sources). Capture's own
+// generic pipeline still reads `.sorb/resolved.json` directly (unchanged) —
+// this exists so the connector satisfies the SOURCE contract for other
+// consumers. Does not move the SD internals (those stay owned by `resolve`).
+const readTokens = async (config) => {
+  const cwd = process.cwd()
+  const p = resolve(cwd, '.sorb/resolved.json')
+  if (!existsSync(p)) {
+    throw new Error('No .sorb/resolved.json — run `sorb-seed resolve` first.')
+  }
+  const data = JSON.parse(readFileSync(p, 'utf-8'))
+  return Array.isArray(data) ? data : data.tokens
+}
+
+export const storybookDomConnector = {
+  id: 'storybook-dom',
+  listUnits,
+  captureGeometry,
+  readTokens,
+}
+
+registerSource(storybookDomConnector)

package/src/variants.js

@@ -0,0 +1,279 @@
+// sorb-seed — variant lifecycle engine.
+//
+// Provides add and deprecate operations against DTCG component token sources.
+// Each operation mutates the source JSON, bumps the $version, re-runs the SD
+// build, and returns a VariantChangeset describing what changed.
+
+import { readFileSync, writeFileSync } from 'fs'
+import { spawn } from 'child_process'
+
+// ─── types ───────────────────────────────────────────────────────────────────
+
+/**
+ * @typedef {Object} AddVariantOptions
+ * @property {string} componentJsonPath - Absolute path to the component DTCG JSON file.
+ * @property {string} variantId         - Full dot-path of the new variant, e.g. "button.tertiary".
+ * @property {string} fromVariant       - Full dot-path of the source variant, e.g. "button.primary".
+ * @property {string} sdConfigDir       - Directory containing sd.config.js (runs `npm run tokens` here).
+ */
+
+/**
+ * @typedef {Object} DeprecateVariantOptions
+ * @property {string} componentJsonPath - Absolute path to the component DTCG JSON file.
+ * @property {string} variantId         - Full dot-path of the variant to deprecate, e.g. "button.danger".
+ * @property {string} replacedBy        - Replacement variant dot-path, e.g. "button.error".
+ * @property {string} sdConfigDir       - Directory containing sd.config.js.
+ */
+
+/**
+ * @typedef {Object} VariantChangeset
+ * @property {'add'|'deprecate'} action   - Which operation was performed.
+ * @property {string}            variantId - The target variant dot-path.
+ * @property {string[]}          tokenIds  - All token ids affected (leaf nodes).
+ * @property {string}            newVersion - The bumped $version written to the source file.
+ */
+
+// ─── helpers ─────────────────────────────────────────────────────────────────
+
+/**
+ * Bump the semver patch segment of a version string.
+ * Non-parseable input returns "1.0.1" as a safe fallback.
+ * @param {string} version
+ * @returns {string}
+ */
+export const bumpVersion = (version) => {
+  if (typeof version !== 'string') return '1.0.1'
+  const parts = version.split('.')
+  if (parts.length !== 3) return '1.0.1'
+  const [major, minor, patch] = parts.map(Number)
+  if (parts.some((p, i) => isNaN([major, minor, patch][i]))) return '1.0.1'
+  return `${major}.${minor}.${patch + 1}`
+}
+
+/**
+ * Walk a variant slice (prop × state tree) and collect fully-qualified token
+ * ids for every leaf node (a node that has a `$value` property).
+ * @param {string} componentId - e.g. "button"
+ * @param {string} variantKey  - e.g. "tertiary"
+ * @param {Object} sliceObj    - The variant's token subtree.
+ * @returns {string[]}
+ */
+export const flattenVariantIds = (componentId, variantKey, sliceObj) => {
+  const ids = []
+
+  /**
+   * @param {Object} node
+   * @param {string[]} path - segments accumulated so far (below variantKey)
+   */
+  const walk = (node, path) => {
+    if (node === null || typeof node !== 'object') return
+    if ('$value' in node) {
+      // Leaf token — build the full dot-path id.
+      ids.push([componentId, variantKey, ...path].join('.'))
+      return
+    }
+    for (const key of Object.keys(node)) {
+      if (key.startsWith('$')) continue // skip metadata keys ($type, $description, etc.)
+      walk(node[key], [...path, key])
+    }
+  }
+
+  walk(sliceObj, [])
+  return ids
+}
+
+/**
+ * Deep-clone a variant slice (the value stored under a variant key).
+ * Equivalent to JSON round-trip — suitable for pure token objects.
+ * @param {Object} fromSlice
+ * @returns {Object}
+ */
+export const cloneVariantSlice = (fromSlice) => JSON.parse(JSON.stringify(fromSlice))
+
+/**
+ * Walk a variant slice and mark every leaf node as deprecated, setting
+ * `$deprecated = true` and `$extensions.sorb.replacedBy` to `replacedBy`.
+ * Returns a **deep clone** with the mutations applied; the original is never
+ * touched.
+ * @param {Object} sliceObj  - The variant's token subtree.
+ * @param {string} replacedBy - Replacement variant dot-path.
+ * @returns {Object} mutated deep clone
+ */
+export const applyDeprecation = (sliceObj, replacedBy) => {
+  const clone = cloneVariantSlice(sliceObj)
+
+  const walk = (node) => {
+    if (node === null || typeof node !== 'object') return
+    if ('$value' in node) {
+      node.$deprecated = true
+      node.$extensions = { sorb: { replacedBy } }
+      return
+    }
+    for (const key of Object.keys(node)) {
+      if (key.startsWith('$')) continue
+      walk(node[key])
+    }
+  }
+
+  walk(clone)
+  return clone
+}
+
+/**
+ * Run `npm run tokens` in the given directory and return a promise that
+ * resolves on exit 0 or rejects with the collected output on non-zero exit.
+ * @param {string} sdConfigDir
+ * @returns {Promise<void>}
+ */
+const runSdBuild = (sdConfigDir) =>
+  new Promise((resolve, reject) => {
+    const chunks = []
+    const child = spawn('npm', ['run', 'tokens'], {
+      cwd: sdConfigDir,
+      stdio: 'pipe',
+    })
+    child.stdout.on('data', (d) => chunks.push(d))
+    child.stderr.on('data', (d) => chunks.push(d))
+    child.on('close', (code) => {
+      if (code === 0) {
+        resolve()
+      } else {
+        const output = Buffer.concat(chunks).toString('utf-8')
+        reject(
+          new Error(
+            `SD build failed (exit ${code}) in ${sdConfigDir}:\n${output}`,
+          ),
+        )
+      }
+    })
+    child.on('error', (err) => reject(err))
+  })
+
+// ─── exported API ─────────────────────────────────────────────────────────────
+
+/**
+ * Add a new component variant by cloning an existing one.
+ *
+ * Reads `componentJsonPath`, deep-clones the `fromVariant` slice into a new
+ * `variantId` key, bumps the set's `$version`, writes the file back, runs the
+ * SD build, and returns a {@link VariantChangeset}.
+ *
+ * @param {AddVariantOptions} options
+ * @returns {Promise<VariantChangeset>}
+ */
+export const addVariant = async (options) => {
+  const { componentJsonPath, variantId, fromVariant, sdConfigDir } = options
+
+  // 1. Read + parse.
+  const raw = readFileSync(componentJsonPath, 'utf-8')
+  const parsed = JSON.parse(raw)
+
+  // 2. Resolve keys.
+  const componentId = variantId.split('.')[0]
+  const newKey = variantId.split('.').slice(1).join('.')
+  const fromKey = fromVariant.split('.').slice(1).join('.')
+
+  // 3. Find component object.
+  const componentObj = parsed[componentId]
+  if (!componentObj || typeof componentObj !== 'object') {
+    throw new Error(
+      `addVariant: component "${componentId}" not found in ${componentJsonPath}`,
+    )
+  }
+
+  // 4. Find source slice.
+  const fromSlice = componentObj[fromKey]
+  if (!fromSlice || typeof fromSlice !== 'object') {
+    throw new Error(
+      `addVariant: source variant "${fromKey}" not found in component "${componentId}"`,
+    )
+  }
+
+  // 5. Deep-clone into new key.
+  componentObj[newKey] = JSON.parse(JSON.stringify(fromSlice))
+
+  // 6. Bump $version.
+  const prevVersion = parsed.$version ?? '1.0.0'
+  const newVersion = bumpVersion(String(prevVersion))
+  parsed.$version = newVersion
+
+  // 7. Write back.
+  writeFileSync(componentJsonPath, JSON.stringify(parsed, null, 2) + '\n', 'utf-8')
+
+  // 8. Run SD build.
+  await runSdBuild(sdConfigDir)
+
+  // 9. Collect token ids from the cloned slice.
+  const tokenIds = flattenVariantIds(componentId, newKey, componentObj[newKey])
+
+  return { action: 'add', variantId, tokenIds, newVersion }
+}
+
+/**
+ * Mark every leaf token in a component variant as deprecated.
+ *
+ * Walks the `variantId` slice, sets `$deprecated = true` and
+ * `$extensions.sorb.replacedBy` on every leaf, bumps `$version`, writes the
+ * file back, runs the SD build, and returns a {@link VariantChangeset}.
+ *
+ * @param {DeprecateVariantOptions} options
+ * @returns {Promise<VariantChangeset>}
+ */
+export const deprecateVariant = async (options) => {
+  const { componentJsonPath, variantId, replacedBy, sdConfigDir } = options
+
+  // 1. Read + parse.
+  const raw = readFileSync(componentJsonPath, 'utf-8')
+  const parsed = JSON.parse(raw)
+
+  // 2. Resolve keys.
+  const componentId = variantId.split('.')[0]
+  const variantKey = variantId.split('.').slice(1).join('.')
+
+  // 3. Find variant slice (error if absent).
+  const componentObj = parsed[componentId]
+  if (!componentObj || typeof componentObj !== 'object') {
+    throw new Error(
+      `deprecateVariant: component "${componentId}" not found in ${componentJsonPath}`,
+    )
+  }
+  const variantSlice = componentObj[variantKey]
+  if (!variantSlice || typeof variantSlice !== 'object') {
+    throw new Error(
+      `deprecateVariant: variant "${variantKey}" not found in component "${componentId}"`,
+    )
+  }
+
+  // 4. Walk the slice; mark every leaf node.
+  const tokenIds = []
+
+  const walk = (node, path) => {
+    if (node === null || typeof node !== 'object') return
+    if ('$value' in node) {
+      node.$deprecated = true
+      node.$extensions = { sorb: { replacedBy } }
+      tokenIds.push([componentId, variantKey, ...path].join('.'))
+      return
+    }
+    for (const key of Object.keys(node)) {
+      if (key.startsWith('$')) continue
+      walk(node[key], [...path, key])
+    }
+  }
+
+  walk(variantSlice, [])
+
+  // 5. Bump $version.
+  const prevVersion = parsed.$version ?? '1.0.0'
+  const newVersion = bumpVersion(String(prevVersion))
+  parsed.$version = newVersion
+
+  // 6. Write back.
+  writeFileSync(componentJsonPath, JSON.stringify(parsed, null, 2) + '\n', 'utf-8')
+
+  // 7. Run SD build.
+  await runSdBuild(sdConfigDir)
+
+  // 8. Return changeset.
+  return { action: 'deprecate', variantId, tokenIds, newVersion }
+}

package/src/variants.test.js

@@ -0,0 +1,129 @@
+// Tests for the variants.js pure helpers.
+// Run: node --test src/variants.test.js
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import {
+  bumpVersion,
+  flattenVariantIds,
+  cloneVariantSlice,
+  applyDeprecation,
+} from './variants.js'
+
+// ─── In-memory button component token matrix ─────────────────────────────────
+
+const BUTTON_PRIMARY_SLICE = {
+  bg: {
+    default: { $value: '#0f65ef', $type: 'color' },
+    hover:   { $value: '#0a4fc4', $type: 'color' },
+  },
+  text: {
+    default: { $value: '#ffffff', $type: 'color' },
+  },
+  border: {
+    default: { $value: '#0f65ef', $type: 'color' },
+  },
+}
+
+const BUTTON_SINGLE_LEVEL_SLICE = {
+  radius: { $value: '4px', $type: 'dimension' },
+}
+
+// ─── flattenVariantIds ────────────────────────────────────────────────────────
+
+test('flattenVariantIds — button.primary slice produces expected ids', () => {
+  const ids = flattenVariantIds('button', 'primary', BUTTON_PRIMARY_SLICE)
+  assert.deepEqual(ids.sort(), [
+    'button.primary.bg.default',
+    'button.primary.bg.hover',
+    'button.primary.border.default',
+    'button.primary.text.default',
+  ])
+})
+
+test('flattenVariantIds — single-level slice produces correct ids', () => {
+  const ids = flattenVariantIds('button', 'base', BUTTON_SINGLE_LEVEL_SLICE)
+  assert.deepEqual(ids, ['button.base.radius'])
+})
+
+test('flattenVariantIds — skips $-prefixed metadata keys', () => {
+  const sliceWithMeta = {
+    $description: 'ignored',
+    bg: { $value: '#000000', $type: 'color' },
+  }
+  const ids = flattenVariantIds('button', 'ghost', sliceWithMeta)
+  assert.deepEqual(ids, ['button.ghost.bg'])
+})
+
+// ─── bumpVersion ─────────────────────────────────────────────────────────────
+
+test('bumpVersion — "1.0.0" bumps patch to "1.0.1"', () => {
+  assert.equal(bumpVersion('1.0.0'), '1.0.1')
+})
+
+test('bumpVersion — "2.3.7" bumps patch to "2.3.8"', () => {
+  assert.equal(bumpVersion('2.3.7'), '2.3.8')
+})
+
+test('bumpVersion — malformed string falls back to "1.0.1"', () => {
+  assert.equal(bumpVersion('not-a-semver'), '1.0.1')
+})
+
+test('bumpVersion — too few parts falls back to "1.0.1"', () => {
+  assert.equal(bumpVersion('1.0'), '1.0.1')
+})
+
+test('bumpVersion — non-string input falls back to "1.0.1"', () => {
+  assert.equal(bumpVersion(null), '1.0.1')
+  assert.equal(bumpVersion(undefined), '1.0.1')
+  assert.equal(bumpVersion(42), '1.0.1')
+})
+
+// ─── cloneVariantSlice ────────────────────────────────────────────────────────
+
+test('cloneVariantSlice — returns a deep copy, not the same reference', () => {
+  const clone = cloneVariantSlice(BUTTON_PRIMARY_SLICE)
+  assert.deepEqual(clone, BUTTON_PRIMARY_SLICE)
+  assert.notEqual(clone, BUTTON_PRIMARY_SLICE)
+  assert.notEqual(clone.bg, BUTTON_PRIMARY_SLICE.bg)
+  assert.notEqual(clone.bg.default, BUTTON_PRIMARY_SLICE.bg.default)
+})
+
+test('cloneVariantSlice — mutation of clone does not affect original', () => {
+  const clone = cloneVariantSlice(BUTTON_PRIMARY_SLICE)
+  clone.bg.default.$value = 'mutated'
+  assert.equal(BUTTON_PRIMARY_SLICE.bg.default.$value, '#0f65ef')
+})
+
+// ─── applyDeprecation ─────────────────────────────────────────────────────────
+
+test('applyDeprecation — all leaf nodes get $deprecated:true', () => {
+  const result = applyDeprecation(BUTTON_PRIMARY_SLICE, 'button.primary-v2')
+  assert.equal(result.bg.default.$deprecated, true)
+  assert.equal(result.bg.hover.$deprecated, true)
+  assert.equal(result.text.default.$deprecated, true)
+  assert.equal(result.border.default.$deprecated, true)
+})
+
+test('applyDeprecation — all leaf nodes get $extensions.sorb.replacedBy set', () => {
+  const result = applyDeprecation(BUTTON_PRIMARY_SLICE, 'button.primary-v2')
+  assert.equal(result.bg.default.$extensions.sorb.replacedBy, 'button.primary-v2')
+  assert.equal(result.bg.hover.$extensions.sorb.replacedBy, 'button.primary-v2')
+  assert.equal(result.text.default.$extensions.sorb.replacedBy, 'button.primary-v2')
+  assert.equal(result.border.default.$extensions.sorb.replacedBy, 'button.primary-v2')
+})
+
+test('applyDeprecation — does not mutate the original slice', () => {
+  const original = {
+    bg: { default: { $value: '#0f65ef', $type: 'color' } },
+  }
+  applyDeprecation(original, 'button.new')
+  assert.equal(original.bg.default.$deprecated, undefined)
+  assert.equal(original.bg.default.$extensions, undefined)
+})
+
+test('applyDeprecation — skips intermediate (non-leaf) nodes', () => {
+  const result = applyDeprecation(BUTTON_PRIMARY_SLICE, 'button.primary-v2')
+  // intermediate nodes should not have $deprecated or $extensions set
+  assert.equal(result.bg.$deprecated, undefined)
+  assert.equal(result.$deprecated, undefined)
+})