@cdx-ui/styles 0.0.1-beta.87 → 0.0.1-beta.89

package/src/__tests__/sd.config.test.ts

@@ -0,0 +1,856 @@
+import type { TransformedToken } from 'style-dictionary/types';
+import {
+  SHADOW_CATEGORIES,
+  composeShadowLayer,
+  createConfig,
+  formatTokenValue,
+  groupByPlatform,
+  groupByTypographyStyle,
+  isCompositeTypography,
+  isModePath,
+  isPlatformPath,
+  isShadowSubProperty,
+  isTailwindThemeToken,
+  pathToVarName,
+  register,
+  renderVariantBlock,
+  roundAlpha,
+  tokenValue,
+} from '../../sd.config';
+
+// ---------------------------------------------------------------------------
+// Token fixture factory
+// ---------------------------------------------------------------------------
+
+interface MakeTokenInput {
+  path: string[];
+  name?: string;
+  value?: unknown;
+  type?: string;
+  $value?: unknown;
+  $type?: string;
+  $extensions?: Record<string, unknown>;
+  original?: Partial<TransformedToken['original']>;
+}
+
+function makeToken({
+  path,
+  name,
+  value,
+  type,
+  $value,
+  $type,
+  $extensions,
+  original,
+}: MakeTokenInput): TransformedToken {
+  // Minimal `TransformedToken` — only the fields helpers actually read.
+  return {
+    name: name ?? path.join('-'),
+    path,
+    value,
+    type,
+    $value,
+    $type,
+    ...($extensions ? { $extensions } : {}),
+    original: {
+      value,
+      $value,
+      ...original,
+    },
+    filePath: 'test.json',
+    isSource: true,
+  } as unknown as TransformedToken;
+}
+
+// ---------------------------------------------------------------------------
+// pathToVarName
+// ---------------------------------------------------------------------------
+
+describe('pathToVarName', () => {
+  it('joins a flat dot-path with dashes', () => {
+    expect(pathToVarName(['color', 'brand', '500'])).toBe('color-brand-500');
+  });
+
+  it('strips a leading platform.<name> prefix', () => {
+    expect(pathToVarName(['platform', 'web', 'font', 'sans'])).toBe('font-sans');
+    expect(pathToVarName(['platform', 'ios', 'font', 'mono'])).toBe('font-mono');
+  });
+
+  it('strips a leading modes.light or modes.dark prefix', () => {
+    expect(pathToVarName(['modes', 'light', 'color', 'surface', 'background'])).toBe(
+      'color-surface-background',
+    );
+    expect(pathToVarName(['modes', 'dark', 'color', 'content', 'primary'])).toBe(
+      'color-content-primary',
+    );
+  });
+
+  it('leaves modes.<other> untouched (only light/dark are stripped)', () => {
+    expect(pathToVarName(['modes', 'sepia', 'color', 'foo'])).toBe('modes-sepia-color-foo');
+  });
+
+  it('collapses spacing.base to the literal "spacing"', () => {
+    expect(pathToVarName(['spacing', 'base'])).toBe('spacing');
+  });
+
+  it('maps text.<size>.font-size to text-<size>', () => {
+    expect(pathToVarName(['text', 'xl', 'font-size'])).toBe('text-xl');
+    expect(pathToVarName(['text', 'sm', 'font-size'])).toBe('text-sm');
+  });
+
+  it('maps text.<size>.line-height to text-<size>--line-height', () => {
+    expect(pathToVarName(['text', 'md', 'line-height'])).toBe('text-md--line-height');
+  });
+
+  it('does not mutate the input array', () => {
+    const input = ['platform', 'web', 'font', 'sans'];
+    pathToVarName(input);
+    expect(input).toEqual(['platform', 'web', 'font', 'sans']);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// SHADOW_CATEGORIES + shadow helpers
+// ---------------------------------------------------------------------------
+
+describe('SHADOW_CATEGORIES', () => {
+  it('lists every shadow-style token category', () => {
+    expect(SHADOW_CATEGORIES).toEqual(['drop-shadow', 'shadow', 'inset-shadow', 'text-shadow']);
+  });
+});
+
+describe('isShadowSubProperty', () => {
+  it.each(['offset-x', 'offset-y', 'blur-radius', 'spread-radius', 'color'])(
+    'returns true for shadow leaf %s under a shadow category',
+    (leaf) => {
+      const token = makeToken({ path: ['shadow', 'md', leaf] });
+      expect(isShadowSubProperty(token)).toBe(true);
+    },
+  );
+
+  it.each(SHADOW_CATEGORIES)(
+    'detects sub-properties under any shadow category (%s)',
+    (category) => {
+      const token = makeToken({ path: [category, 'lg', 'offset-y'] });
+      expect(isShadowSubProperty(token)).toBe(true);
+    },
+  );
+
+  it('returns false for non-shadow categories', () => {
+    expect(isShadowSubProperty(makeToken({ path: ['color', 'brand', '500'] }))).toBe(false);
+  });
+
+  it('returns false for non-sub-property leaves under a shadow category', () => {
+    expect(isShadowSubProperty(makeToken({ path: ['shadow', 'md', 'not-a-shadow-prop'] }))).toBe(
+      false,
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// isTailwindThemeToken
+// ---------------------------------------------------------------------------
+
+describe('isTailwindThemeToken', () => {
+  it('returns true for tokens with one of the Tailwind theme prefixes', () => {
+    expect(isTailwindThemeToken(makeToken({ name: 'color-brand-500', path: [] }))).toBe(true);
+    expect(isTailwindThemeToken(makeToken({ name: 'spacing', path: [] }))).toBe(true);
+    expect(isTailwindThemeToken(makeToken({ name: 'text-xl', path: [] }))).toBe(true);
+  });
+
+  it('returns false for tokens whose name does not match any prefix', () => {
+    expect(isTailwindThemeToken(makeToken({ name: 'something-arbitrary', path: [] }))).toBe(false);
+  });
+
+  it('returns false for shadow sub-properties even when name would match', () => {
+    expect(
+      isTailwindThemeToken(makeToken({ path: ['shadow', 'md', 'offset-x'], name: 'shadow-md' })),
+    ).toBe(false);
+  });
+
+  it('returns true for tokens marked as composed via $extensions', () => {
+    expect(
+      isTailwindThemeToken(
+        makeToken({
+          path: ['shadow', 'md'],
+          name: 'shadow-md',
+          $extensions: { composed: true },
+        }),
+      ),
+    ).toBe(true);
+  });
+
+  it('returns true when original.$extensions.composed is set', () => {
+    expect(
+      isTailwindThemeToken(
+        makeToken({
+          path: ['shadow', 'md'],
+          name: 'arbitrary-name',
+          original: { $extensions: { composed: true } as Record<string, unknown> },
+        }),
+      ),
+    ).toBe(true);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// isCompositeTypography / isModePath / isPlatformPath
+// ---------------------------------------------------------------------------
+
+describe('isCompositeTypography', () => {
+  it('returns true when path[0] is "typography"', () => {
+    expect(isCompositeTypography(makeToken({ path: ['typography', 'heading', 'xl'] }))).toBe(true);
+  });
+
+  it('returns false otherwise', () => {
+    expect(isCompositeTypography(makeToken({ path: ['color', 'brand'] }))).toBe(false);
+  });
+});
+
+describe('isModePath', () => {
+  it('returns true for any modes.* token when no mode arg is passed', () => {
+    expect(isModePath(makeToken({ path: ['modes', 'light', 'color'] }))).toBe(true);
+    expect(isModePath(makeToken({ path: ['modes', 'dark', 'color'] }))).toBe(true);
+  });
+
+  it('returns true only when path[1] matches the given mode arg', () => {
+    const lightToken = makeToken({ path: ['modes', 'light', 'color'] });
+    const darkToken = makeToken({ path: ['modes', 'dark', 'color'] });
+    expect(isModePath(lightToken, 'light')).toBe(true);
+    expect(isModePath(lightToken, 'dark')).toBe(false);
+    expect(isModePath(darkToken, 'light')).toBe(false);
+    expect(isModePath(darkToken, 'dark')).toBe(true);
+  });
+
+  it('returns false when path[0] is not "modes"', () => {
+    expect(isModePath(makeToken({ path: ['color', 'brand'] }))).toBe(false);
+  });
+});
+
+describe('isPlatformPath', () => {
+  it('returns true when path[0] is "platform"', () => {
+    expect(isPlatformPath(makeToken({ path: ['platform', 'web', 'font'] }))).toBe(true);
+  });
+
+  it('returns false otherwise', () => {
+    expect(isPlatformPath(makeToken({ path: ['color'] }))).toBe(false);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// formatTokenValue / tokenValue
+// ---------------------------------------------------------------------------
+
+describe('formatTokenValue', () => {
+  it('wraps string-typed values in single quotes', () => {
+    const token = makeToken({ path: ['font'], $type: 'string', $value: 'Inter' });
+    expect(formatTokenValue(token)).toBe("'Inter'");
+  });
+
+  it('falls back to the legacy `type` field when $type is absent', () => {
+    const token = makeToken({ path: ['font'], type: 'string', value: 'Roboto' });
+    expect(formatTokenValue(token)).toBe("'Roboto'");
+  });
+
+  it('does not quote string values that are already var() references', () => {
+    const token = makeToken({
+      path: ['font', 'display'],
+      $type: 'string',
+      $value: 'var(--font-display)',
+    });
+    expect(formatTokenValue(token)).toBe('var(--font-display)');
+  });
+
+  it('returns non-string values stringified without quoting', () => {
+    const token = makeToken({ path: ['spacing', '4'], $type: 'dimension', $value: '16px' });
+    expect(formatTokenValue(token)).toBe('16px');
+  });
+});
+
+describe('tokenValue', () => {
+  it('prefers $value over value', () => {
+    expect(tokenValue(makeToken({ path: ['x'], $value: 'new', value: 'old' }))).toBe('new');
+  });
+
+  it('falls back to value when $value is absent', () => {
+    expect(tokenValue(makeToken({ path: ['x'], value: 'legacy' }))).toBe('legacy');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// composeShadowLayer / roundAlpha
+// ---------------------------------------------------------------------------
+
+describe('composeShadowLayer', () => {
+  it('renders a non-inset layer with offsets, blur, and string color', () => {
+    const layer = {
+      'offset-x': { $value: 0 },
+      'offset-y': { $value: 2 },
+      'blur-radius': { $value: 4 },
+      'spread-radius': { $value: 0 },
+      color: { $value: 'rgba(0, 0, 0, 0.1)' },
+    };
+    expect(composeShadowLayer(layer, false)).toBe('0px 2px 4px rgba(0, 0, 0, 0.1)');
+  });
+
+  it('omits spread when it equals 0', () => {
+    const layer = {
+      'offset-x': { $value: 1 },
+      'offset-y': { $value: 1 },
+      'blur-radius': { $value: 2 },
+      'spread-radius': { $value: 0 },
+      color: { $value: '#000' },
+    };
+    expect(composeShadowLayer(layer, false)).toBe('1px 1px 2px #000');
+  });
+
+  it('includes a non-zero spread', () => {
+    const layer = {
+      'offset-x': { $value: 0 },
+      'offset-y': { $value: 0 },
+      'blur-radius': { $value: 8 },
+      'spread-radius': { $value: 4 },
+      color: { $value: '#111' },
+    };
+    expect(composeShadowLayer(layer, false)).toBe('0px 0px 8px 4px #111');
+  });
+
+  it('prepends "inset " when isInset=true', () => {
+    const layer = {
+      'offset-x': { $value: 0 },
+      'offset-y': { $value: 1 },
+      'blur-radius': { $value: 3 },
+      'spread-radius': { $value: 0 },
+      color: { $value: '#222' },
+    };
+    expect(composeShadowLayer(layer, true)).toBe('inset 0px 1px 3px #222');
+  });
+
+  it('renders object colors with hex+alpha as rgb(0 0 0 / alpha)', () => {
+    const layer = {
+      'offset-x': { $value: 0 },
+      'offset-y': { $value: 2 },
+      'blur-radius': { $value: 4 },
+      'spread-radius': { $value: 0 },
+      color: { $value: { hex: '#000000', alpha: 0.25 } },
+    };
+    expect(composeShadowLayer(layer, false)).toBe('0px 2px 4px rgb(0 0 0 / 0.25)');
+  });
+
+  it('falls back to a sensible default when color is absent', () => {
+    const layer = {
+      'offset-x': { $value: 0 },
+      'offset-y': { $value: 0 },
+      'blur-radius': { $value: 0 },
+      'spread-radius': { $value: 0 },
+      // color intentionally omitted
+    } as Record<string, { $value: string | number | Record<string, unknown> }>;
+    expect(composeShadowLayer(layer, false)).toBe('0px 0px 0px rgb(0 0 0 / 0.1)');
+  });
+
+  it('treats missing offsets/blur/spread as 0', () => {
+    const layer = {
+      color: { $value: '#333' },
+    } as Record<string, { $value: string | number | Record<string, unknown> }>;
+    expect(composeShadowLayer(layer, false)).toBe('0px 0px 0px #333');
+  });
+});
+
+describe('roundAlpha', () => {
+  it('rounds to 4 fractional digits without trailing zeros', () => {
+    expect(roundAlpha(0.123456)).toBe('0.1235');
+    expect(roundAlpha(0.5)).toBe('0.5');
+    expect(roundAlpha(1)).toBe('1');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// renderVariantBlock
+// ---------------------------------------------------------------------------
+
+describe('renderVariantBlock', () => {
+  it('returns an empty string when no tokens are passed', () => {
+    expect(renderVariantBlock('light', [])).toBe('');
+  });
+
+  it('emits an @variant block with one declaration per token', () => {
+    const tokens = [
+      makeToken({
+        path: ['modes', 'light', 'color', 'surface', 'background'],
+        name: 'color-surface-background',
+        $type: 'color',
+        $value: '#ffffff',
+      }),
+      makeToken({
+        path: ['modes', 'light', 'color', 'content', 'primary'],
+        name: 'color-content-primary',
+        $type: 'color',
+        $value: '#000000',
+      }),
+    ];
+
+    const out = renderVariantBlock('light', tokens);
+    expect(out).toContain('@variant light {');
+    expect(out).toContain('--color-surface-background: #ffffff;');
+    expect(out).toContain('--color-content-primary: #000000;');
+    expect(out.trim().endsWith('}')).toBe(true);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// groupByPlatform / groupByTypographyStyle
+// ---------------------------------------------------------------------------
+
+describe('groupByPlatform', () => {
+  it('groups tokens by path[1] (the platform name)', () => {
+    const tokens = [
+      makeToken({ path: ['platform', 'web', 'font', 'sans'] }),
+      makeToken({ path: ['platform', 'ios', 'font', 'sans'] }),
+      makeToken({ path: ['platform', 'web', 'font', 'mono'] }),
+    ];
+    const grouped = groupByPlatform(tokens);
+    expect(Object.keys(grouped).sort()).toEqual(['ios', 'web']);
+    expect(grouped.web).toHaveLength(2);
+    expect(grouped.ios).toHaveLength(1);
+  });
+
+  it('returns an empty object when given no tokens', () => {
+    expect(groupByPlatform([])).toEqual({});
+  });
+});
+
+describe('groupByTypographyStyle', () => {
+  it('groups typography tokens by category-size and emits property maps', () => {
+    const tokens = [
+      makeToken({
+        path: ['typography', 'heading', 'xl', 'font-family'],
+        $value: 'Crimson Pro',
+      }),
+      makeToken({
+        path: ['typography', 'heading', 'xl', 'font-size'],
+        $value: '40px',
+      }),
+      makeToken({
+        path: ['typography', 'body', 'md', 'font-family'],
+        $value: 'var(--font-body)',
+      }),
+    ];
+    const grouped = groupByTypographyStyle(tokens);
+
+    expect(grouped['heading-xl']['font-family']).toBe("'Crimson Pro'");
+    expect(grouped['heading-xl']['font-size']).toBe('40px');
+    expect(grouped['body-md']['font-family']).toBe('var(--font-body)');
+  });
+
+  it('skips non-typography tokens', () => {
+    const tokens = [
+      makeToken({ path: ['color', 'brand', '500'], $value: '#abc' }),
+      makeToken({
+        path: ['typography', 'label', 'sm', 'font-size'],
+        $value: '12px',
+      }),
+    ];
+    const grouped = groupByTypographyStyle(tokens);
+    expect(Object.keys(grouped)).toEqual(['label-sm']);
+  });
+
+  it('JSON-stringifies object-typed values', () => {
+    const tokens = [
+      makeToken({
+        path: ['typography', 'heading', 'lg', 'shadow'],
+        $value: { x: 1, y: 2 } as unknown as string,
+      }),
+    ];
+    const grouped = groupByTypographyStyle(tokens);
+    expect(grouped['heading-lg'].shadow).toBe('{"x":1,"y":2}');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// createConfig
+// ---------------------------------------------------------------------------
+
+describe('createConfig', () => {
+  it('returns a SD config object with source pointing at the requested preset', () => {
+    const cfg = createConfig('poise');
+    expect(cfg.source).toEqual(['tokens/presets/poise.json']);
+  });
+
+  it('prefixes paths when a basePath is provided (trailing slash normalized)', () => {
+    expect(createConfig('pulse', '/abs/path/').source).toEqual([
+      '/abs/path/tokens/presets/pulse.json',
+    ]);
+    expect(createConfig('pulse', '/abs/path').source).toEqual([
+      '/abs/path/tokens/presets/pulse.json',
+    ]);
+  });
+
+  it('enables DTCG and broken-reference logging to console', () => {
+    const cfg = createConfig('poise');
+    expect(cfg.usesDtcg).toBe(true);
+    expect(cfg.log.errors.brokenReferences).toBe('console');
+  });
+
+  it('declares the two preprocessors in order: fonts/promote then shadow/compose', () => {
+    expect(createConfig('poise').preprocessors).toEqual(['fonts/promote', 'shadow/compose']);
+  });
+
+  it('declares css-theme, css-utilities, and css-vanilla platforms', () => {
+    const platforms = createConfig('poise').platforms;
+    expect(Object.keys(platforms).sort()).toEqual(['css-theme', 'css-utilities', 'css-vanilla']);
+  });
+
+  it('css-theme platform uses the cdx custom format and the expected transforms', () => {
+    const cssTheme = createConfig('poise').platforms['css-theme'];
+    expect(cssTheme.transforms).toEqual([
+      'name/tailwind',
+      'color/css',
+      'size/pxToRem',
+      'value/cssReferences',
+    ]);
+    expect(cssTheme.files).toEqual([{ destination: 'css/theme.css', format: 'css/cdx-theme' }]);
+  });
+
+  it('css-utilities platform filters to composite typography tokens', () => {
+    const cssUtil = createConfig('poise').platforms['css-utilities'];
+    expect(cssUtil.files[0].format).toBe('css/tailwind-utilities');
+    expect(cssUtil.files[0].filter).toBe(isCompositeTypography);
+  });
+
+  it('css-vanilla platform emits vanilla.css with the cdx-vanilla format', () => {
+    const cssVanilla = createConfig('poise').platforms['css-vanilla'];
+    expect(cssVanilla.files).toEqual([
+      { destination: 'css/vanilla.css', format: 'css/cdx-vanilla' },
+    ]);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// register
+// ---------------------------------------------------------------------------
+
+describe('register', () => {
+  it('registers two transforms, two preprocessors, and three formats on the SD instance', () => {
+    const calls: Record<string, string[]> = {
+      registerTransform: [],
+      registerPreprocessor: [],
+      registerFormat: [],
+    };
+
+    const mockSd = {
+      registerTransform: jest.fn((arg: { name: string }) => calls.registerTransform.push(arg.name)),
+      registerPreprocessor: jest.fn((arg: { name: string }) =>
+        calls.registerPreprocessor.push(arg.name),
+      ),
+      registerFormat: jest.fn((arg: { name: string }) => calls.registerFormat.push(arg.name)),
+    } as unknown as Parameters<typeof register>[0];
+
+    register(mockSd);
+
+    expect(calls.registerTransform.sort()).toEqual(['name/tailwind', 'value/cssReferences']);
+    expect(calls.registerPreprocessor.sort()).toEqual(['fonts/promote', 'shadow/compose']);
+    expect(calls.registerFormat.sort()).toEqual([
+      'css/cdx-theme',
+      'css/cdx-vanilla',
+      'css/tailwind-utilities',
+    ]);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// register — captured callback behaviour (transforms, preprocessors, formats)
+// ---------------------------------------------------------------------------
+
+interface Registration {
+  name: string;
+  transform?: (token: TransformedToken) => unknown;
+  preprocessor?: (dictionary: Record<string, unknown>) => Record<string, unknown>;
+  format?: (args: {
+    dictionary: { allTokens: TransformedToken[] };
+    file: Record<string, unknown>;
+  }) => Promise<string>;
+}
+
+/** Runs `register` against a recording stub and returns the captured config objects by name. */
+function captureRegistrations() {
+  const transforms: Record<string, Registration> = {};
+  const preprocessors: Record<string, Registration> = {};
+  const formats: Record<string, Registration> = {};
+
+  const mockSd = {
+    registerTransform: (arg: Registration) => {
+      transforms[arg.name] = arg;
+    },
+    registerPreprocessor: (arg: Registration) => {
+      preprocessors[arg.name] = arg;
+    },
+    registerFormat: (arg: Registration) => {
+      formats[arg.name] = arg;
+    },
+  } as unknown as Parameters<typeof register>[0];
+
+  register(mockSd);
+
+  return { transforms, preprocessors, formats };
+}
+
+describe('register — name/tailwind transform', () => {
+  it('maps a token path to its Tailwind variable name', () => {
+    const { transforms } = captureRegistrations();
+    const token = makeToken({ path: ['platform', 'web', 'font', 'sans'] });
+    expect(transforms['name/tailwind'].transform?.(token)).toBe('font-sans');
+  });
+});
+
+describe('register — value/cssReferences transform', () => {
+  it('rewrites a DTCG alias reference to a var() of the resolved variable name', () => {
+    const { transforms } = captureRegistrations();
+    const token = makeToken({
+      path: ['color', 'accent'],
+      $value: '#resolved',
+      original: { $value: '{color.brand.500}' },
+    });
+    expect(transforms['value/cssReferences'].transform?.(token)).toBe('var(--color-brand-500)');
+  });
+
+  it('returns the token value unchanged when original.$value is not an alias', () => {
+    const { transforms } = captureRegistrations();
+    const token = makeToken({
+      path: ['color', 'brand', '500'],
+      $value: '#112233',
+      original: { $value: '#112233' },
+    });
+    expect(transforms['value/cssReferences'].transform?.(token)).toBe('#112233');
+  });
+
+  it('falls back to value when original.$value is absent', () => {
+    const { transforms } = captureRegistrations();
+    const token = makeToken({ path: ['color', 'brand'], value: 'legacy' });
+    expect(transforms['value/cssReferences'].transform?.(token)).toBe('legacy');
+  });
+});
+
+describe('register — fonts/promote preprocessor', () => {
+  it('promotes semantic fonts from modes.light.font to the top-level font group', () => {
+    const { preprocessors } = captureRegistrations();
+    const dictionary = {
+      modes: { light: { font: { body: { $value: 'DM Sans' }, display: { $value: 'Bitter' } } } },
+    } as Record<string, unknown>;
+
+    const result = preprocessors['fonts/promote'].preprocessor?.(dictionary) as Record<
+      string,
+      { body: { $value: string }; display: { $value: string } }
+    >;
+
+    expect(result.font.body).toEqual({ $value: 'DM Sans' });
+    expect(result.font.display).toEqual({ $value: 'Bitter' });
+  });
+
+  it('does not overwrite an existing top-level font entry', () => {
+    const { preprocessors } = captureRegistrations();
+    const dictionary = {
+      font: { body: { $value: 'existing' } },
+      modes: { light: { font: { body: { $value: 'DM Sans' } } } },
+    } as Record<string, unknown>;
+
+    const result = preprocessors['fonts/promote'].preprocessor?.(dictionary) as Record<
+      string,
+      { body: { $value: string } }
+    >;
+
+    expect(result.font.body).toEqual({ $value: 'existing' });
+  });
+
+  it('returns the dictionary untouched when modes.light.font is absent', () => {
+    const { preprocessors } = captureRegistrations();
+    const dictionary = { color: { brand: { $value: '#000' } } } as Record<string, unknown>;
+    const result = preprocessors['fonts/promote'].preprocessor?.(dictionary);
+    expect(result).toBe(dictionary);
+    expect(result).not.toHaveProperty('font');
+  });
+});
+
+describe('register — shadow/compose preprocessor', () => {
+  it('composes a multi-layer shadow into a comma-joined shorthand', () => {
+    const { preprocessors } = captureRegistrations();
+    const dictionary = {
+      shadow: {
+        md: {
+          '0': {
+            'offset-x': { $value: 0 },
+            'offset-y': { $value: 1 },
+            'blur-radius': { $value: 2 },
+            'spread-radius': { $value: 0 },
+            color: { $value: '#000' },
+          },
+          '1': {
+            'offset-x': { $value: 0 },
+            'offset-y': { $value: 2 },
+            'blur-radius': { $value: 4 },
+            'spread-radius': { $value: 0 },
+            color: { $value: '#111' },
+          },
+        },
+      },
+    } as Record<string, unknown>;
+
+    const result = preprocessors['shadow/compose'].preprocessor?.(dictionary) as {
+      shadow: { md: { $value: string; $extensions: { composed: boolean } } };
+    };
+
+    expect(result.shadow.md.$value).toBe('0px 1px 2px #000, 0px 2px 4px #111');
+    expect(result.shadow.md.$extensions.composed).toBe(true);
+  });
+
+  it('composes a single-layer shadow declared with flat sub-properties', () => {
+    const { preprocessors } = captureRegistrations();
+    const dictionary = {
+      shadow: {
+        sm: {
+          'offset-x': { $value: 0 },
+          'offset-y': { $value: 1 },
+          'blur-radius': { $value: 2 },
+          'spread-radius': { $value: 0 },
+          color: { $value: '#111' },
+        },
+      },
+    } as Record<string, unknown>;
+
+    const result = preprocessors['shadow/compose'].preprocessor?.(dictionary) as {
+      shadow: { sm: { $value: string } };
+    };
+
+    expect(result.shadow.sm.$value).toBe('0px 1px 2px #111');
+  });
+
+  it('prefixes inset for the inset-shadow category', () => {
+    const { preprocessors } = captureRegistrations();
+    const dictionary = {
+      'inset-shadow': {
+        sm: {
+          'offset-x': { $value: 0 },
+          'offset-y': { $value: 1 },
+          'blur-radius': { $value: 3 },
+          'spread-radius': { $value: 0 },
+          color: { $value: '#222' },
+        },
+      },
+    } as Record<string, unknown>;
+
+    const result = preprocessors['shadow/compose'].preprocessor?.(dictionary) as {
+      'inset-shadow': { sm: { $value: string } };
+    };
+
+    expect(result['inset-shadow'].sm.$value).toBe('inset 0px 1px 3px #222');
+  });
+
+  it('leaves size groups without shadow sub-properties untouched', () => {
+    const { preprocessors } = captureRegistrations();
+    const untouched = { note: 'not a shadow layer' };
+    const dictionary = { shadow: { weird: untouched } } as Record<string, unknown>;
+
+    const result = preprocessors['shadow/compose'].preprocessor?.(dictionary) as {
+      shadow: { weird: unknown };
+    };
+
+    expect(result.shadow.weird).toBe(untouched);
+  });
+
+  it('ignores shadow categories that are not present in the dictionary', () => {
+    const { preprocessors } = captureRegistrations();
+    const dictionary = { color: { brand: { $value: '#000' } } } as Record<string, unknown>;
+    const result = preprocessors['shadow/compose'].preprocessor?.(dictionary);
+    expect(result).toBe(dictionary);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// register — format functions
+// ---------------------------------------------------------------------------
+
+/** Token fixtures shared by the theme + vanilla format assertions. */
+const FORMAT_TOKENS: TransformedToken[] = [
+  makeToken({
+    path: ['color', 'brand', '500'],
+    name: 'color-brand-500',
+    $type: 'color',
+    $value: '#112233',
+  }),
+  makeToken({
+    path: ['modes', 'light', 'color', 'surface', 'background'],
+    name: 'color-surface-background',
+    $type: 'color',
+    $value: '#ffffff',
+  }),
+  makeToken({
+    path: ['modes', 'dark', 'color', 'surface', 'background'],
+    name: 'color-surface-background',
+    $type: 'color',
+    $value: '#000000',
+  }),
+  makeToken({
+    path: ['platform', 'web', 'font', 'sans'],
+    name: 'font-sans',
+    $type: 'string',
+    $value: 'Inter',
+  }),
+  makeToken({
+    path: ['platform', 'ios', 'font', 'sans'],
+    name: 'font-sans',
+    $type: 'string',
+    $value: 'SF Pro',
+  }),
+  makeToken({ path: ['typography', 'heading', 'xl', 'font-size'], $value: '40px' }),
+  makeToken({ path: ['typography', 'heading', 'xl', 'font-family'], $value: 'Crimson Pro' }),
+];
+
+describe('register — css/cdx-theme format', () => {
+  it('emits @theme static, mode variants, and platform variants', async () => {
+    const { formats } = captureRegistrations();
+    const css = await formats['css/cdx-theme'].format?.({
+      dictionary: { allTokens: FORMAT_TOKENS },
+      file: {},
+    });
+
+    expect(css).toContain('@theme static {');
+    expect(css).toContain('--color-brand-500: #112233;');
+    expect(css).toContain('--color-surface-background: #ffffff;');
+    expect(css).toContain('@layer theme {');
+    expect(css).toContain('@variant light {');
+    expect(css).toContain('@variant dark {');
+    expect(css).toContain('@variant web {');
+    expect(css).toContain('@variant ios {');
+    expect(css).toContain("--font-sans: 'Inter';");
+  });
+});
+
+describe('register — css/tailwind-utilities format', () => {
+  it('emits an @utility block per composite typography style', async () => {
+    const { formats } = captureRegistrations();
+    const css = await formats['css/tailwind-utilities'].format?.({
+      dictionary: { allTokens: FORMAT_TOKENS },
+      file: {},
+    });
+
+    expect(css).toContain('@utility heading-xl {');
+    expect(css).toContain('font-size: 40px;');
+    expect(css).toContain("font-family: 'Crimson Pro';");
+  });
+});
+
+describe('register — css/cdx-vanilla format', () => {
+  it('emits :root primitives, a dark-mode media block, and typography classes', async () => {
+    const { formats } = captureRegistrations();
+    const css = await formats['css/cdx-vanilla'].format?.({
+      dictionary: { allTokens: FORMAT_TOKENS },
+      file: {},
+    });
+
+    expect(css).toContain(':root {');
+    expect(css).toContain('--color-brand-500: #112233;');
+    expect(css).toContain("--font-sans: 'Inter';");
+    expect(css).toContain('@media (prefers-color-scheme: dark) {');
+    expect(css).toContain('.heading-xl {');
+    expect(css).toContain('font-size: 40px;');
+  });
+});