@sorb/seed 0.1.1 → 0.2.0

package/src/render/worker.test.js

@@ -0,0 +1,233 @@
+// Unit tests for the E3 render-worker orchestration. NO real Playwright/browser
+// is used — `page`/`pool`/`cache` are all fakes injected via `deps`, so these
+// tests exercise job orchestration, token-injection wiring, the diff-cache, and
+// the result shape without a live browser (per the task's hard rule).
+
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { readFile, rm } from 'node:fs/promises'
+import { join } from 'node:path'
+import { tmpdir } from 'node:os'
+import { randomUUID } from 'node:crypto'
+
+import { renderJob } from './worker.js'
+import { DiffCache } from './diffCache.js'
+
+// ─── fakes ────────────────────────────────────────────────────────────────────
+function makeFakePage({ resolvedVars = {} } = {}) {
+  const calls = { evaluate: 0, screenshot: 0 }
+  return {
+    calls,
+    async evaluate() {
+      calls.evaluate++
+      // 1st call in renderJob is injectTokenMap (no meaningful return needed);
+      // 2nd is readResolvedVars, which needs the resolved-values shape back.
+      if (calls.evaluate === 1) return undefined
+      return resolvedVars
+    },
+    async screenshot() {
+      calls.screenshot++
+      return Buffer.from('fake-png-bytes')
+    },
+    async addInitScript() {},
+    async setViewportSize() {},
+  }
+}
+
+function makeFakePool(pagesByUrl = {}) {
+  const acquireCalls = []
+  const seen = new Set()
+  return {
+    acquireCalls,
+    async acquire(url, viewport) {
+      acquireCalls.push({ url, viewport })
+      const reused = seen.has(url)
+      seen.add(url)
+      const page = pagesByUrl[url] || (pagesByUrl[url] = makeFakePage())
+      return { page, reused }
+    },
+    async evict() {},
+    async closeAll() {},
+  }
+}
+
+const scratchDir = tmpdir()
+const scratchPath = () => join(scratchDir, `sorb-worker-test-${randomUUID()}.png`)
+
+// ─── basic shape + reuse ──────────────────────────────────────────────────────
+test('renderJob: requires input.url', async () => {
+  await assert.rejects(() => renderJob({}), /url is required/)
+})
+
+test('renderJob: returns the documented result shape and writes the screenshot file', async () => {
+  const pool = makeFakePool()
+  const cache = new DiffCache()
+  const path = scratchPath()
+  let captureCalls = 0
+  const captureFn = async () => {
+    captureCalls++
+    return { type: 'FRAME', name: 'body', fills: [], children: [] }
+  }
+
+  const result = await renderJob(
+    {
+      url: 'https://demo.sorbcloud.com',
+      tokenMap: { '--sorb-color-bg': '#fff' },
+      screenshotPath: path,
+    },
+    { pagePool: async () => pool, cache, captureFn },
+  )
+
+  try {
+    assert.equal(result.cacheHit, false)
+    assert.equal(result.pageReused, false)
+    assert.equal(captureCalls, 1)
+    assert.equal(result.screenshot.path, path)
+    assert.equal(result.screenshot.width, 1280)
+    assert.equal(result.screenshot.height, 800)
+    assert.ok(result.dom)
+    assert.ok(result.conformance)
+    assert.equal(typeof result.conformance.conformant, 'boolean')
+    assert.ok(result.timings)
+    for (const k of ['navigateMs', 'injectMs', 'captureMs', 'screenshotMs', 'totalMs']) {
+      assert.equal(typeof result.timings[k], 'number')
+    }
+    assert.equal(result.diff, null) // first render for this url → no prior to diff against
+    assert.ok(result.cacheKey.includes('https://demo.sorbcloud.com'))
+
+    const written = await readFile(path)
+    assert.equal(written.toString(), 'fake-png-bytes')
+  } finally {
+    await rm(path, { force: true })
+  }
+})
+
+// ─── exact-match cache short-circuit ─────────────────────────────────────────
+test('renderJob: identical (url, tokenMap) on a warm cache short-circuits the render', async () => {
+  const pool = makeFakePool()
+  const cache = new DiffCache()
+  let captureCalls = 0
+  const captureFn = async () => {
+    captureCalls++
+    return { type: 'FRAME', children: [] }
+  }
+  const input = {
+    url: 'https://demo.sorbcloud.com',
+    tokenMap: { '--x': '1px' },
+    screenshotPath: scratchPath(),
+  }
+  const deps = { pagePool: async () => pool, cache, captureFn }
+
+  const r1 = await renderJob(input, deps)
+  const r2 = await renderJob({ ...input, screenshotPath: scratchPath() }, deps)
+
+  assert.equal(r1.cacheHit, false)
+  assert.equal(r2.cacheHit, true)
+  assert.equal(captureCalls, 1) // second call never re-rendered
+  assert.equal(r2.screenshot.path, r1.screenshot.path) // cached result's own screenshot ref
+  await rm(r1.screenshot.path, { force: true })
+})
+
+test('renderJob: different tokenMap for the same url is NOT a cache hit', async () => {
+  const pool = makeFakePool()
+  const cache = new DiffCache()
+  let captureCalls = 0
+  const captureFn = async () => {
+    captureCalls++
+    return { type: 'FRAME', children: [] }
+  }
+  const deps = { pagePool: async () => pool, cache, captureFn }
+
+  const p1 = scratchPath()
+  const p2 = scratchPath()
+  const r1 = await renderJob({ url: 'https://a', tokenMap: { '--x': '1px' }, screenshotPath: p1 }, deps)
+  const r2 = await renderJob({ url: 'https://a', tokenMap: { '--x': '2px' }, screenshotPath: p2 }, deps)
+
+  assert.equal(r1.cacheHit, false)
+  assert.equal(r2.cacheHit, false)
+  assert.equal(captureCalls, 2)
+  await rm(p1, { force: true })
+  await rm(p2, { force: true })
+})
+
+// ─── page reuse (navigation-skip) ────────────────────────────────────────────
+test('renderJob: a second render of the same url reuses the page (pageReused=true)', async () => {
+  const pool = makeFakePool()
+  const cache = new DiffCache()
+  const captureFn = async () => ({ type: 'FRAME', children: [] })
+  const deps = { pagePool: async () => pool, cache, captureFn }
+
+  const p1 = scratchPath()
+  const p2 = scratchPath()
+  const r1 = await renderJob({ url: 'https://a', tokenMap: { '--x': '1px' }, screenshotPath: p1 }, deps)
+  const r2 = await renderJob({ url: 'https://a', tokenMap: { '--x': '2px' }, screenshotPath: p2 }, deps)
+
+  assert.equal(r1.pageReused, false)
+  assert.equal(r2.pageReused, true)
+  assert.equal(pool.acquireCalls.length, 2)
+  await rm(p1, { force: true })
+  await rm(p2, { force: true })
+})
+
+// ─── diff-cache reporting ─────────────────────────────────────────────────────
+test('renderJob: diffOnly=true reports which dom subtree changed on a re-render', async () => {
+  const pool = makeFakePool()
+  const cache = new DiffCache()
+  let call = 0
+  const captureFn = async () => {
+    call++
+    // second capture differs from the first (a changed fill on the same shape)
+    return {
+      type: 'FRAME',
+      children: [{ type: 'FRAME', fills: call === 1 ? [] : [{ raw: '#fff' }], children: [] }],
+    }
+  }
+  const deps = { pagePool: async () => pool, cache, captureFn }
+
+  const p1 = scratchPath()
+  const p2 = scratchPath()
+  const r1 = await renderJob({ url: 'https://a', tokenMap: { '--x': '1' }, screenshotPath: p1, diffOnly: true }, deps)
+  const r2 = await renderJob({ url: 'https://a', tokenMap: { '--x': '2' }, screenshotPath: p2, diffOnly: true }, deps)
+
+  assert.equal(r1.diff, null)
+  assert.ok(r2.diff)
+  assert.ok(r2.diff.changed.length > 0)
+  await rm(p1, { force: true })
+  await rm(p2, { force: true })
+})
+
+test('renderJob: diffOnly=false skips the diff computation entirely', async () => {
+  const pool = makeFakePool()
+  const cache = new DiffCache()
+  const captureFn = async () => ({ type: 'FRAME', children: [] })
+  const deps = { pagePool: async () => pool, cache, captureFn }
+
+  const p1 = scratchPath()
+  const p2 = scratchPath()
+  await renderJob({ url: 'https://a', tokenMap: { '--x': '1' }, screenshotPath: p1, diffOnly: false }, deps)
+  const r2 = await renderJob({ url: 'https://a', tokenMap: { '--x': '2' }, screenshotPath: p2, diffOnly: false }, deps)
+
+  assert.equal(r2.diff, null)
+  await rm(p1, { force: true })
+  await rm(p2, { force: true })
+})
+
+// ─── conformance wiring end-to-end (with the captureFn/page fakes) ──────────
+test('renderJob: conformance reflects the resolved vs requested token values', async () => {
+  const page = makeFakePage({ resolvedVars: { '--sorb-color-bg': '#000' } }) // mismatch on purpose
+  const pool = { async acquire() { return { page, reused: false } }, async evict() {}, async closeAll() {} }
+  const cache = new DiffCache()
+  const captureFn = async () => ({ type: 'FRAME', children: [] })
+  const path = scratchPath()
+
+  const result = await renderJob(
+    { url: 'https://a', tokenMap: { '--sorb-color-bg': '#fff' }, screenshotPath: path },
+    { pagePool: async () => pool, cache, captureFn },
+  )
+
+  assert.equal(result.conformance.conformant, false)
+  assert.equal(result.conformance.mismatchCount, 1)
+  assert.equal(result.conformance.rows[0].expected, '#fff')
+  assert.equal(result.conformance.rows[0].actual, '#000')
+  await rm(path, { force: true })
+})

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