@fragments-sdk/cli 0.14.3 → 0.15.1

package/src/theme/__tests__/component-contrast.test.ts

@@ -3,7 +3,7 @@
  *
  * Validates WCAG 2.1 contrast ratios between CSS custom property pairings
  * (--fui-text-*, --fui-bg-*, --fui-color-*) across all 5 neutral palettes
- * (Stone, Ice, Earth, Sand, Fire) in both light and dark modes.
+ * (Stone, Ice, Earth, Sand, Fire, Fragments) in both light and dark modes.
  *
  * Token values are derived from the seed-derivation system — the same
  * derivation functions that produce the runtime CSS custom properties.
@@ -133,7 +133,7 @@ function ratioOnComposite(fgHex: string, rgbaBg: string, baseHex: string): numbe
 
 // ── Tests ────────────────────────────────────────────────────────────────────
 
-const PALETTE_NAMES: NeutralPalette[] = ["stone", "ice", "earth", "sand", "fire"];
+const PALETTE_NAMES = Object.keys(PALETTES) as NeutralPalette[];
 const brand = DEFAULT_SEEDS.brand;
 
 for (const paletteName of PALETTE_NAMES) {

package/src/theme/__tests__/serializer.test.ts

@@ -282,7 +282,7 @@ describe("Theme Serializer", () => {
       };
 
       const url = encodeThemeToUrl(theme);
-      expect(url).toMatch(/^https:\/\/fragments\.dev\/init\?preset=/);
+      expect(url).toMatch(/^https:\/\/usefragments\.com\/create\?preset=/);
     });
   });
 

package/src/theme/generator.ts

@@ -109,6 +109,9 @@ const DARK_TOKEN_MAPPINGS = {
     md: "fui-dark-shadow-md",
   },
   // Direct dark mode properties
+  accent: "fui-dark-color-accent",
+  accentHover: "fui-dark-color-accent-hover",
+  accentActive: "fui-dark-color-accent-active",
   dangerBg: "fui-dark-color-danger-bg",
   successBg: "fui-dark-color-success-bg",
   warningBg: "fui-dark-color-warning-bg",
@@ -179,7 +182,7 @@ function generateDarkTokens(
   }
 
   // Handle direct dark mode properties
-  const directProps = ["dangerBg", "successBg", "warningBg", "infoBg", "dangerText", "successText", "warningText", "infoText", "backdrop"] as const;
+  const directProps = ["accent", "accentHover", "accentActive", "dangerBg", "successBg", "warningBg", "infoBg", "dangerText", "successText", "warningText", "infoText", "backdrop"] as const;
   for (const prop of directProps) {
     const value = config.dark[prop];
     if (value !== undefined) {
@@ -450,6 +453,13 @@ export function generateScssTokens(config: ThemeConfig): string {
     lines.push("");
   }
 
+  // Density
+  if (config.density) {
+    lines.push("// Density");
+    lines.push(`$fui-density: "${config.density}" !default;`);
+    lines.push("");
+  }
+
   // Dark mode
   const darkTokens = generateDarkTokens(config, "scss");
   if (darkTokens.length > 0) {
@@ -487,6 +497,11 @@ export function generateCssTokens(config: ThemeConfig): string {
     lightTokens.push(...tokens);
   }
 
+  // Density
+  if (config.density) {
+    lightTokens.push(`  --fui-density: ${config.density};`);
+  }
+
   if (lightTokens.length > 0) {
     lines.push(":root {");
     lines.push(...lightTokens);

package/src/theme/schema.ts

@@ -139,11 +139,18 @@ export const themeDarkModeSchema = z.object({
   text: themeTextSchema.optional(),
   borders: themeBordersSchema.optional(),
   shadows: themeShadowsSchema.optional(),
+  accent: colorSchema.optional(),
+  accentHover: colorSchema.optional(),
+  accentActive: colorSchema.optional(),
   dangerBg: colorSchema.optional(),
   successBg: colorSchema.optional(),
   warningBg: colorSchema.optional(),
   infoBg: colorSchema.optional(),
   backdrop: colorSchema.optional(),
+  dangerText: colorSchema.optional(),
+  successText: colorSchema.optional(),
+  warningText: colorSchema.optional(),
+  infoText: colorSchema.optional(),
 }).strict();
 
 /**
@@ -161,6 +168,7 @@ export const themeConfigSchema = z.object({
   radius: themeRadiusSchema.optional(),
   shadows: themeShadowsSchema.optional(),
   dark: themeDarkModeSchema.optional(),
+  density: z.enum(['compact', 'default', 'relaxed']).optional(),
 }).strict();
 
 /**

package/src/theme/serializer.ts

@@ -9,7 +9,7 @@ import { deflateSync, inflateSync } from "node:zlib";
 import { validateThemeConfig } from "./schema.js";
 import type { ThemeConfig } from "./types.js";
 
-const DEFAULT_BASE_URL = "https://fragments.dev/init";
+const DEFAULT_BASE_URL = "https://usefragments.com/create";
 
 /**
  * Convert a Buffer to base64url encoding (URL-safe base64)
@@ -61,22 +61,26 @@ export function compressTheme(config: ThemeConfig): string {
  * @returns Theme configuration or null if invalid
  */
 export function decompressTheme(encoded: string): ThemeConfig | null {
+  // Try zlib-compressed first (CLI native encoding)
   try {
     const buffer = fromBase64Url(encoded);
     const decompressed = inflateSync(buffer);
     const json = decompressed.toString("utf-8");
     const parsed = JSON.parse(json);
+    const result = validateThemeConfig(parsed);
+    if (result.success) return result.data;
+  } catch { /* not zlib-compressed */ }
 
-    // Validate the parsed object
+  // Fall back to plain base64url JSON (browser/docs encoding)
+  try {
+    const buffer = fromBase64Url(encoded);
+    const json = buffer.toString("utf-8");
+    const parsed = JSON.parse(json);
     const result = validateThemeConfig(parsed);
-    if (result.success) {
-      return result.data;
-    }
+    if (result.success) return result.data;
+  } catch { /* invalid */ }
 
-    return null;
-  } catch {
-    return null;
-  }
+  return null;
 }
 
 /**

package/src/theme/types.ts

@@ -136,6 +136,12 @@ export interface ThemeDarkMode {
   borders?: ThemeBorders;
   /** Shadow overrides for dark mode */
   shadows?: ThemeShadows;
+  /** Accent color for dark mode - $fui-dark-color-accent */
+  accent?: string;
+  /** Accent hover for dark mode - $fui-dark-color-accent-hover */
+  accentHover?: string;
+  /** Accent active for dark mode - $fui-dark-color-accent-active */
+  accentActive?: string;
   /** Danger background for dark mode - $fui-dark-color-danger-bg */
   dangerBg?: string;
   /** Success background for dark mode - $fui-dark-color-success-bg */
@@ -185,6 +191,8 @@ export interface ThemeConfig {
   shadows?: ThemeShadows;
   /** Dark mode overrides */
   dark?: ThemeDarkMode;
+  /** Density preset — controls spacing scale */
+  density?: 'compact' | 'default' | 'relaxed';
 }
 
 /**

package/src/validators.ts

@@ -6,8 +6,7 @@ import {
   loadFragmentFile,
 } from './core/node.js';
 import { validateSnippetPolicy, type SnippetValidationOptions } from './service/snippet-validation.js';
-import { createComponentExtractor, type ComponentMeta, type PropMeta } from './core/component-extractor.js';
-import { resolveComponentSourcePath } from './core/auto-props.js';
+import { createComponentExtractor, type ComponentMeta, type PropMeta, resolveComponentSourcePath } from '@fragments-sdk/extract';
 import { parseFragmentFile } from './core/parser.js';
 import { readFile } from 'node:fs/promises';
 

package/src/viewer/__tests__/viewer-integration.test.ts

@@ -191,12 +191,12 @@ describe("discoverInstalledFragments", () => {
       JSON.stringify({ name: "@acme/ui", fragments: { src: "src" } })
     );
     await writeFile(
-      resolve(acmeDir, "src/components/Button.fragment.tsx"),
-      "export default {};"
+      resolve(acmeDir, "src/components/Button.contract.json"),
+      "{}"
     );
     await writeFile(
-      resolve(acmeDir, "src/components/Card.fragment.tsx"),
-      "export default {};"
+      resolve(acmeDir, "src/components/Card.contract.json"),
+      "{}"
     );
 
     const someLibDir = resolve(tmpDir, "node_modules/some-lib");
@@ -206,8 +206,8 @@ describe("discoverInstalledFragments", () => {
       JSON.stringify({ name: "some-lib" })
     );
     await writeFile(
-      resolve(someLibDir, "src/Foo.fragment.tsx"),
-      "export default {};"
+      resolve(someLibDir, "src/Foo.contract.json"),
+      "{}"
     );
   });
 
@@ -219,8 +219,8 @@ describe("discoverInstalledFragments", () => {
     const results = await discoverInstalledFragments(tmpDir);
     const paths = results.map((r) => r.relativePath).sort();
     expect(paths).toEqual([
-      "@acme/ui/src/components/Button.fragment.tsx",
-      "@acme/ui/src/components/Card.fragment.tsx",
+      "@acme/ui/src/components/Button.contract.json",
+      "@acme/ui/src/components/Card.contract.json",
     ]);
   });
 

package/src/viewer/style-utils.ts

@@ -1,414 +1,29 @@
 /**
- * Style comparison utilities for comparing Figma design properties
- * with rendered component computed styles.
- */
-
-/**
- * Style diff result for a single CSS property
- */
-export interface StyleDiffItem {
-  /** CSS property name */
-  property: string;
-  /** Expected value from Figma */
-  figma: string;
-  /** Actual value from rendered component */
-  rendered: string;
-  /** Whether values match (within tolerance) */
-  match: boolean;
-}
-
-/**
- * Result of comparing styles
- */
-export interface StyleComparisonResult {
-  /** Whether all styles match */
-  match: boolean;
-  /** Individual property comparisons */
-  properties: StyleDiffItem[];
-  /** CSS properties from Figma design */
-  figmaStyles: Record<string, string>;
-  /** Computed CSS properties from rendered component */
-  renderedStyles: Record<string, string>;
-}
-
-/**
- * Compare Figma CSS properties with rendered computed styles.
- */
-export function compareStyles(
-  figmaStyles: Record<string, string | undefined>,
-  renderedStyles: Record<string, string>
-): StyleComparisonResult {
-  const properties: StyleDiffItem[] = [];
-  const cleanFigmaStyles: Record<string, string> = {};
-
-  // Properties to compare
-  const propsToCompare = [
-    "backgroundColor",
-    "borderColor",
-    "borderWidth",
-    "borderRadius",
-    "fontFamily",
-    "fontSize",
-    "fontWeight",
-    "lineHeight",
-    "letterSpacing",
-    "textAlign",
-    "boxShadow",
-    "padding",
-    "gap",
-    "opacity",
-  ];
-
-  for (const prop of propsToCompare) {
-    const figmaValue = figmaStyles[prop];
-    const renderedValue = renderedStyles[prop];
-
-    if (figmaValue !== undefined) {
-      cleanFigmaStyles[prop] = figmaValue;
-
-      const match = compareStyleValue(prop, figmaValue, renderedValue || "");
-      properties.push({
-        property: prop,
-        figma: figmaValue,
-        rendered: renderedValue || "(not set)",
-        match,
-      });
-    }
-  }
-
-  const allMatch = properties.every((p) => p.match);
-
-  return {
-    match: allMatch,
-    properties,
-    figmaStyles: cleanFigmaStyles,
-    renderedStyles,
-  };
-}
-
-/**
- * Compare a single style value with tolerance for color and numeric differences.
- */
-export function compareStyleValue(
-  prop: string,
-  figma: string,
-  rendered: string
-): boolean {
-  // Normalize values for comparison
-  const normalizedFigma = normalizeStyleValue(prop, figma);
-  const normalizedRendered = normalizeStyleValue(prop, rendered);
-
-  // Direct match
-  if (normalizedFigma === normalizedRendered) {
-    return true;
-  }
-
-  // Color comparison with tolerance
-  if (prop === "backgroundColor" || prop === "borderColor") {
-    return compareColors(normalizedFigma, normalizedRendered, 5);
-  }
-
-  // Numeric comparison with tolerance (for pixels)
-  if (
-    ["borderWidth", "borderRadius", "fontSize", "padding", "gap"].includes(prop)
-  ) {
-    return compareNumericValues(normalizedFigma, normalizedRendered, 1);
-  }
-
-  return false;
-}
-
-/**
- * Normalize a style value for comparison.
- */
-export function normalizeStyleValue(prop: string, value: string): string {
-  // Remove extra whitespace
-  let normalized = value.trim().replace(/\s+/g, " ");
-
-  // Normalize "none" shadow to empty
-  if (prop === "boxShadow" && normalized === "none") {
-    normalized = "";
-  }
-
-  // Normalize rgba(0, 0, 0, 0) to "transparent"
-  if (normalized.match(/rgba\(\s*0\s*,\s*0\s*,\s*0\s*,\s*0\s*\)/)) {
-    normalized = "transparent";
-  }
-
-  return normalized;
-}
-
-/**
- * Compare two color values with tolerance.
- */
-export function compareColors(
-  color1: string,
-  color2: string,
-  tolerance: number
-): boolean {
-  const rgb1 = parseColor(color1);
-  const rgb2 = parseColor(color2);
-
-  if (!rgb1 || !rgb2) {
-    return color1 === color2;
-  }
-
-  return (
-    Math.abs(rgb1.r - rgb2.r) <= tolerance &&
-    Math.abs(rgb1.g - rgb2.g) <= tolerance &&
-    Math.abs(rgb1.b - rgb2.b) <= tolerance &&
-    Math.abs((rgb1.a ?? 1) - (rgb2.a ?? 1)) <= 0.05
-  );
-}
-
-/**
- * Parse a color string to RGB values.
- */
-export function parseColor(
-  color: string
-): { r: number; g: number; b: number; a?: number } | null {
-  // Handle hex colors
-  const hexMatch = color.match(/^#([0-9a-f]{2})([0-9a-f]{2})([0-9a-f]{2})$/i);
-  if (hexMatch) {
-    return {
-      r: parseInt(hexMatch[1], 16),
-      g: parseInt(hexMatch[2], 16),
-      b: parseInt(hexMatch[3], 16),
-    };
-  }
-
-  // Handle rgb/rgba
-  const rgbaMatch = color.match(
-    /rgba?\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)\s*(?:,\s*([\d.]+))?\s*\)/
-  );
-  if (rgbaMatch) {
-    return {
-      r: parseInt(rgbaMatch[1], 10),
-      g: parseInt(rgbaMatch[2], 10),
-      b: parseInt(rgbaMatch[3], 10),
-      a: rgbaMatch[4] ? parseFloat(rgbaMatch[4]) : 1,
-    };
-  }
-
-  return null;
-}
-
-/**
- * Compare numeric values (e.g., "10px" vs "11px") with tolerance.
- */
-export function compareNumericValues(
-  value1: string,
-  value2: string,
-  tolerance: number
-): boolean {
-  const num1 = parseFloat(value1);
-  const num2 = parseFloat(value2);
-
-  if (isNaN(num1) || isNaN(num2)) {
-    return value1 === value2;
-  }
-
-  return Math.abs(num1 - num2) <= tolerance;
-}
-
-// ----- Enhanced Token-Aware Style Comparison -----
-
-import type {
-  EnhancedStyleDiffItem,
-  TokenFix,
-  TokenUsageSummary,
-  DesignToken,
-} from "../core/index.js";
-
-/**
- * Enhanced style diff result with token information
- */
-export interface EnhancedStyleComparisonResult extends StyleComparisonResult {
-  /** Individual property comparisons with token info */
-  properties: EnhancedStyleDiffItem[];
-  /** Token usage summary */
-  tokenSummary?: TokenUsageSummary;
-}
-
-/**
- * Token registry interface for style comparison
- * (subset of TokenRegistryManager methods needed here)
- */
-export interface TokenLookup {
-  findByValue(value: string, theme?: string): string[];
-  getToken(name: string): DesignToken | undefined;
-  calculateUsageSummary(
-    styleDiffs: Array<{
-      property: string;
-      figma: string;
-      rendered: string;
-      match: boolean;
-    }>,
-    theme?: string
-  ): TokenUsageSummary;
-}
-
-/**
- * Compare styles with token awareness.
+ * Style comparison utilities — thin re-export from @fragments-sdk/core.
  *
- * This enhanced version:
- * 1. Performs normal style comparison
- * 2. Identifies which values match design tokens
- * 3. Flags hardcoded values that should use tokens
- * 4. Generates fix suggestions
- */
-export function compareStylesWithTokens(
-  figmaStyles: Record<string, string | undefined>,
-  renderedStyles: Record<string, string>,
-  tokenLookup?: TokenLookup,
-  theme = "default"
-): EnhancedStyleComparisonResult {
-  const properties: EnhancedStyleDiffItem[] = [];
-  const cleanFigmaStyles: Record<string, string> = {};
-
-  // Properties to compare
-  const propsToCompare = [
-    "backgroundColor",
-    "borderColor",
-    "borderWidth",
-    "borderRadius",
-    "fontFamily",
-    "fontSize",
-    "fontWeight",
-    "lineHeight",
-    "letterSpacing",
-    "textAlign",
-    "boxShadow",
-    "padding",
-    "gap",
-    "opacity",
-    "color",
-  ];
-
-  for (const prop of propsToCompare) {
-    const figmaValue = figmaStyles[prop];
-    const renderedValue = renderedStyles[prop];
-
-    if (figmaValue !== undefined) {
-      cleanFigmaStyles[prop] = figmaValue;
-
-      const match = compareStyleValue(prop, figmaValue, renderedValue || "");
-
-      // Build enhanced diff item
-      const item: EnhancedStyleDiffItem = {
-        property: prop,
-        figma: figmaValue,
-        rendered: renderedValue || "(not set)",
-        match,
-        isHardcoded: false,
-      };
-
-      // Add token information if registry is available
-      if (tokenLookup) {
-        const figmaTokens = tokenLookup.findByValue(figmaValue, theme);
-        const renderedTokens = renderedValue
-          ? tokenLookup.findByValue(renderedValue, theme)
-          : [];
-
-        if (figmaTokens.length > 0) {
-          item.figmaToken = figmaTokens[0];
-        }
-
-        if (renderedTokens.length > 0) {
-          item.renderedToken = renderedTokens[0];
-        }
-
-        // Determine if this is a hardcoded value
-        // Hardcoded = Figma matches a token, but rendered doesn't use a token
-        item.isHardcoded = !!item.figmaToken && !item.renderedToken;
-
-        // Generate fix suggestion if hardcoded
-        if (item.isHardcoded && item.figmaToken) {
-          const token = tokenLookup.getToken(item.figmaToken);
-          if (token) {
-            const cssProperty = toCssProperty(prop);
-            item.suggestedFix = {
-              tokenName: item.figmaToken,
-              tokenValue: token.resolvedValue,
-              codeFix: `${cssProperty}: var(${item.figmaToken});`,
-              confidence: 0.9,
-              reason: `Figma uses token ${item.figmaToken} (${token.resolvedValue}). Replace hardcoded value with token for consistency.`,
-            };
-          }
-        }
-      }
-
-      properties.push(item);
-    }
-  }
-
-  const allMatch = properties.every((p) => p.match);
-
-  // Calculate token summary if registry available
-  let tokenSummary: TokenUsageSummary | undefined;
-  if (tokenLookup) {
-    tokenSummary = tokenLookup.calculateUsageSummary(
-      properties.map((p) => ({
-        property: p.property,
-        figma: p.figma,
-        rendered: p.rendered,
-        match: p.match,
-      })),
-      theme
-    );
-  }
-
-  return {
-    match: allMatch,
-    properties,
-    figmaStyles: cleanFigmaStyles,
-    renderedStyles,
-    tokenSummary,
-  };
-}
-
-/**
- * Convert camelCase to kebab-case CSS property
- */
-function toCssProperty(prop: string): string {
-  return prop.replace(/([A-Z])/g, "-$1").toLowerCase();
-}
-
-/**
- * Format token summary for display
- */
-export function formatTokenSummary(summary: TokenUsageSummary): string {
-  const lines: string[] = [];
-
-  lines.push(`Token Compliance: ${summary.compliancePercent}%`);
-  lines.push(
-    `${summary.usingTokens}/${summary.totalProperties} properties using tokens`
-  );
-
-  if (summary.hardcoded > 0) {
-    lines.push(`${summary.hardcoded} hardcoded value(s) detected`);
-  }
-
-  if (summary.implicitMatches > 0) {
-    lines.push(`${summary.implicitMatches} implicit match(es)`);
-  }
-
-  return lines.join("\n");
-}
-
-/**
- * Get status badge for token compliance
- */
-export function getComplianceBadge(
-  compliancePercent: number
-): { label: string; color: string } {
-  if (compliancePercent >= 100) {
-    return { label: "Excellent", color: "green" };
-  } else if (compliancePercent >= 80) {
-    return { label: "Good", color: "blue" };
-  } else if (compliancePercent >= 50) {
-    return { label: "Fair", color: "yellow" };
-  } else {
-    return { label: "Poor", color: "red" };
-  }
-}
+ * The canonical comparison engine lives in @fragments-sdk/core/style-comparison.
+ * This file exists for backwards compatibility with existing imports.
+ */
+export {
+  // Types
+  type StyleDiffItem,
+  type StyleComparisonResult,
+  type EnhancedStyleComparisonResult,
+  type TokenLookup,
+  type NormalizedToken,
+  type NormalizedStyleMap,
+  type StyleComparisonOptions,
+  // Functions
+  compareStyles,
+  compareStyleValue,
+  compareStylesWithTokens,
+  normalizeStyleValue,
+  compareColors,
+  parseColor,
+  compareNumericValues,
+  formatTokenSummary,
+  getComplianceBadge,
+  // Constants
+  DEFAULT_STYLE_PROPERTIES,
+  DEFAULT_ENHANCED_STYLE_PROPERTIES,
+} from "@fragments-sdk/core";

package/src/viewer/vite-plugin.ts

@@ -1532,9 +1532,9 @@ export function fragmentsPlugin(options: FragmentsPluginOptions): Plugin[] {
       return null;
     },
 
-    // Handle HMR for fragment files
+    // Handle HMR for fragment and contract files
     handleHotUpdate({ file, server }) {
-      if (fragmentFileSet.has(file)) {
+      if (fragmentFileSet.has(file) || file.endsWith('.contract.json')) {
         // Invalidate the virtual fragments module
         const mod = server.moduleGraph.getModuleById(VIRTUAL_FRAGMENTS_RESOLVED);
         if (mod) {