# Platform Changelog

Track all notable changes to the Frontfriend platform

# Platform Changelog

All notable changes to the Frontfriend platform will be documented in this page.

## v3.8.2 - 2026-03-22

### Fixed
- **Turbopack CSS Parsing: `file:` Variant Classes in Safelist** - Safelisted classes with `file:` prefix (e.g., `file:placeholder:text-neutral-subtle`) caused Turbopack to crash with invalid chained pseudo-element selectors
  - Root cause: component config class extraction included `file:` variant classes, which Tailwind JIT resolved into invalid CSS like `::placeholder::file-selector-button`
  - Added filter to exclude `file:` prefixed classes from safelist generation
  - These classes still work via Tailwind JIT when used in component markup
  - Companion fix in `@frontfriend/tailwind` v3.0.4 provides client-side defense

## v3.8.1 - 2026-03-19

### Fixed
- **CSS Validator: Tailwind `!important` Modifier** - Classes with `!` prefix (e.g., `!text-neutral-subtle`) were incorrectly rejected by the component config validator
  - Root cause: contradictory regex in Layer 3 syntax validation rejected `!` despite the allowlist explicitly permitting it
  - Removed redundant regex check, keeping precise allowlist for valid starting characters
  - 42 total tests with 100% pass rate

## v3.7.0 - 2025-12-20

### Added - Design System Editor Overhaul & Multi-Layer Validation

**CodeMirror-Based JSON Editor:**
- **Professional Code Editor** replacing simple textarea with CodeMirror v6
  - Syntax highlighting for JSON and CSS with OneDark theme
  - Line numbers and fold gutter with collapse/expand functionality
  - Real-time JSON syntax validation with inline error indicators
  - Smart folding: collapses first-level children only
  - Error boundary with textarea fallback for reliability

**Multi-Layer Validation System:**
- **Layer 1 - JSON Schema Validation** with Ajv for structure and types
  - Fast and comprehensive schema validation
  - Catches malformed JSON and type mismatches

- **Layer 2 - Smart CSS Class Detection** distinguishing classes from value props
  - Validates CSS class strings (e.g., `"flex gap-4"`, `"text-sm"`)
  - Allows value props without validation (e.g., `"9"`, `"4"`, `"true"`)
  - Skips paths containing `"props"` to avoid false positives
  - Context-aware intelligent validation

- **Layer 3 - Syntax Validation** with fast-path regex checks
  - Prevents CSS injection and invalid syntax
  - Next.js 16 + Turbopack compatibility
  - 38 comprehensive tests with 100% pass rate
  - No false positives for custom utilities

**Enhanced User Experience:**
- **Inline Error Display** with Alert components below each editor
  - CSS validation errors with property, className, reason, and suggestions
  - JSON schema errors with clear, actionable messages
  - Better debugging experience than toast-only notifications

- **Automatic Alphabetical Sorting** of JSON keys on load and save
  - Recursive sorting for all nested objects
  - Improves readability and component discoverability
  - Consistent ordering across team members

- **UI/UX Improvements**
  - Version tags auto-refresh after saving configuration
  - Copy endpoint URL with single-click button
  - Cleaner, more professional layout
  - Better use of screen space

**Validation Scripts for CI/CD:**
- `pnpm validate:ui-config` - Full validation suite (JSON + Tailwind)
- `pnpm validate:json` - Schema validation only
- `pnpm validate:tailwind` - Tailwind ESLint validation
- Scripts for pre-commit hooks, CI/CD pipelines, database migration validation

### Changed

**API Validation Integration:**
- Both update and sync-tokens endpoints now validate `componentsConfig` before saving
- Returns 400 with detailed error objects including:
  - Component name, property path, className, reason, and suggestions
- Enhanced error handling with structured validation feedback

**Design System Form:**
- Updated with sorting, inline error display, and real-time validation
- Replaced simple code editor with CodeMirror-based JSON editor
- Improved form validation feedback

### Added - Dependencies

**Validation:**
- `ajv` (v8.17.1), `ajv-formats` (v3.0.1)

**CodeMirror v6:**
- Core: `codemirror` (v6.0.2)
- Features: autocomplete, commands, lang-css, lang-json, lint, search
- View: state, theme-one-dark, view

### Removed
- `code-editor.tsx` - Replaced by CodeMirror-based `json-editor.tsx`

### Security
- **Multi-layer validation prevents CSS injection attacks**
- JSON schema validation prevents schema poisoning
- Error boundary prevents editor crashes from exposing state
- Enhanced input sanitization with defense-in-depth approach

### Performance
- CodeMirror optimized for large JSON files
- Incremental parsing and validation
- Efficient syntax highlighting and folding

## v3.6.0 - 2025-12-16

### Added - Master Design System & Version Management Enhancements

**Master Design System:**
- **System Templates Workspace**: Special hidden workspace for master design system
  - Accessible only to superadmins
  - Contains master design system template for new design systems
  - Hidden from regular workspace listings
  - Visible in Figma plugin workspace selector for superadmins
  - New utility functions in `lib/system-workspace.ts` for system workspace checks

- **Superadmin Access Control**:
  - JWT tokens now include `globalRole` field for plugin authentication
  - Plugin can identify and show superadmin-only features
  - Updated `lib/jwt-utils.ts` and `lib/auth-plugin.ts` for role-based access
  - System workspace access checks across all relevant endpoints

- **Admin Interface**:
  - New admin sidebar menu item "Master Design System"
  - Direct access to master design system editing at `/admin/master-design-system`
  - Reuses existing design system components for consistency

**Version Management UI Improvements:**
- **Pagination**: Version history now paginated (10 versions per page)
  - Previous/Next navigation controls
  - Shows current page range (e.g., "Showing 1 to 10 of 16 versions")
  - Significantly improves performance for design systems with many versions

- **Delete Deprecated Versions**:
  - New delete option in version dropdown menu for deprecated versions
  - Confirmation dialog before deletion
  - Safeguards: only deprecated versions without active tags can be deleted
  - New `DELETE /api/design-systems/{ffId}/versions/{versionId}` endpoint

- **Confirmation Dialogs**:
  - Tag promotion now shows confirmation dialog
  - Delete version shows destructive confirmation dialog
  - Both dialogs display version and tag names for clarity

- **Tag Menu Improvements**:
  - Tag promotion menu items now ordered: dev → next → latest
  - Other custom tags appear after default tags
  - More intuitive workflow for version promotion

**Auto-Deprecation Logic:**
- Released versions without tags are automatically deprecated when:
  - A new version is created via token sync, OR
  - A newer version is released
- Prevents accumulation of unused released versions
- Keeps version history clean and manageable

**Performance Optimizations:**
- Version list queries now use `select` instead of `include`
- Only loads necessary fields (not large JSON blobs like sourceTokens)
- Significant performance improvement for version history display
- Reduced database load and faster page rendering

**API Updates:**
- Enhanced `/api/design-systems/{ffId}/versions` with pagination support
  - Now accepts `limit` and `offset` query parameters
  - Returns `total` count for pagination controls
- Updated `lib/version-resolver.ts` with pagination and total count
- System workspace access checks added to multiple endpoints:
  - `/api/workspaces` - Shows System Templates to superadmins
  - `/api/workspaces/{workspaceId}/projects`
  - `/api/workspaces/{workspaceId}/design-systems`
  - `/api/workspaces/{workspaceId}/design-systems/{designSystemId}/tokens`
  - `/api/design-systems/{ffId}/versions/{versionId}/release`
  - `/api/design-systems/{ffId}/tags/{tagName}/move`

### Changed
- JWT token generation now includes `globalRole` for both initial auth and token refresh
- Plugin user interface updated to include and validate `globalRole`
- Version queries optimized to select only required fields

### Fixed
- Pagination now works correctly with proper total count from database
- Old released versions without tags are now properly deprecated
- System workspace access properly validated for superadmins

## v3.5.0 - 2025-12-01

### Added - Design System Versioning Architecture

**Core Versioning System:**
- **Immutable Version Snapshots**: DesignSystemVersion model with semantic versioning (vX.Y.Z)
  - Each version is an immutable snapshot of design tokens and configuration
  - Automatic version label incrementing (v1.0.0 → v1.0.1 → v1.0.2)
  - Version status lifecycle: draft → released → deprecated
  - Only one draft version exists at any time (old drafts auto-deprecated)
  - Version metadata includes creator, notes, and Figma sync information

- **Mutable Tag Pointers**: DesignSystemTag model for version management
  - Three default tags: `dev`, `next`, `latest`
  - Tags point to specific versions and can be moved between versions
  - Protected tags (`next`, `latest`) require manual promotion and released versions
  - Automatic `dev` tag promotion on new version creation
  - Tag history tracking with timestamps

**Smart Token Synchronization:**
- SHA-256 hash-based token comparison prevents unnecessary version creation
- Versions created only when tokens actually change
- `lastTokenSyncAt` always updates regardless of token changes
- Configuration preservation across versions (componentsConfig, customCss, icons, fonts)
- Automatic draft deprecation before new version creation
- Token change detection with deterministic object comparison

**New API Endpoints:**
- `GET /api/design-systems/{ffId}/tags` - List all tags
- `POST /api/design-systems/{ffId}/tags` - Create new tag
- `GET /api/design-systems/{ffId}/tags/{tagName}` - Get specific tag
- `PUT /api/design-systems/{ffId}/tags/{tagName}` - Update tag
- `DELETE /api/design-systems/{ffId}/tags/{tagName}` - Delete tag (unprotected only)
- `POST /api/design-systems/{ffId}/tags/{tagName}/move` - Move tag to different version
- `GET /api/design-systems/{ffId}/versions` - List all versions with pagination
- `POST /api/design-systems/{ffId}/versions` - Create new version manually
- `GET /api/design-systems/{ffId}/versions/{versionId}` - Get specific version
- `DELETE /api/design-systems/{ffId}/versions/{versionId}` - Delete version (drafts only)
- `POST /api/design-systems/{ffId}/versions/{versionId}/release` - Release draft version
- `POST /api/design-systems/{ffId}/versions/{versionId}/deprecate` - Deprecate version

### Changed

**Token Synchronization:**
- Token sync endpoints now create versions only when tokens change (SHA-256 comparison)
- Always update `lastTokenSyncAt` timestamp regardless of token changes
- Automatically promote dev tag to new versions
- Preserve all configs from current dev version

**Configuration Management:**
- Config update endpoint now uses dev version tokens instead of legacy tokens field
- Proper cache invalidation after updates

**Processed Tokens Endpoint:**
- Tag parameter support: `?tag=dev`, `?tag=next`, `?tag=latest`
- On-demand token processing for uncached versions
- Response headers include version metadata
- **Backward Compatible**: Defaults to `latest` tag when no tag specified

**Database Schema:**
- Added `DesignSystemVersion` and `DesignSystemTag` models
- Maintained backward compatibility with legacy fields

### Fixed
- Fixed `lastTokenSyncAt` showing "Never" after successful syncs
- Fixed cache invalidation issues
- Fixed duplicate version creation on unchanged token syncs
- Fixed loading states causing UI flash

### Security
- Authentication required for all version and tag management endpoints
- Protected tags prevent accidental promotion of draft versions
- Version immutability ensures audit trail and rollback capability

## v3.2.2 - 2025-11-14

### Fixed
- **Overlay and Layer Token Alpha Handling** - Semantic tokens with transparency now render correctly with proper opacity
  - Fixed overlay and layer token processing to convert 8-digit hex values to HSL with alpha format
  - Added ColorProcessor injection to SemanticProcessor for consistent color transformation pipeline
  - Output format now properly includes alpha channel (e.g., `206 92% 5% / 0.9` instead of `206 92% 5%`)
  - Affects `lib/token-processor/processors/semantic.processor.ts` and `lib/token-processor/index.ts`
- **Font Token Recognition** - Text style tokens now correctly generate font utilities
  - Updated FontProcessor to recognize both `$type: "text"` and `$type: "string"` as valid font token indicators
  - Font utilities like `font-primary` now generate correctly from Figma text styles
  - Affects `lib/token-processor/processors/font.processor.ts`

### Added
- **Global Tokens Field** - Added `globalTokens` field to ProcessedTokens interface for frontfriend-tailwind package compatibility
  - Ensures token structure matches expected format across the platform
  - Affects `lib/token-processor/types.ts`
- **CORS Support** - Added CORS headers for Figma plugin development at `http://localhost:4720`
  - Enables plugin communication with platform during local development
  - Affects `middleware.ts`

## v3.2.1 - 2025-10-30

### Fixed
- **Turbopack Compatibility** - Fixed server-side safelist generation to prevent invalid CSS selectors
  - Removed variant generation from `generateSafelist()`
  - Prevents generation of invalid CSS selector combinations like `.file\:placeholder\:text-neutral-subtle::-moz-placeholder::file-selector-button`
  - Safelist now only includes base classes (e.g., `bg-brand-mid` instead of `hover:bg-brand-mid`)
  - Tailwind's JIT still detects and generates variant classes when actually used in components
  - Ensures tokens served via api are Turbopack-compatible
  - **Impact**: Client applications can now use Next.js with `--turbopack` flag without CSS parsing errors

### Changed
- Server-side token processor now generates safelist without variant prefixes
- Improved compatibility with Next.js 15.3+ Turbopack builds

## v3.2.0 - 2025-08-31

### Added
- **Templates Gallery** - New `/templates` page with downloadable starter templates for React+Vite, Next.js 15, and Vue+Vite
- **Export API Endpoints** - Public endpoints for exporting pages and projects
  - `/api/export/pages/[pageId]` - Export individual pages with ff-id validation
  - `/api/export/projects/[projectId]` - Export entire projects with all pages
- **Template Download API** - `/api/templates/download/[template]` endpoint for downloading starter templates
- **Project CLI Popover** - New UI component showing CLI commands for adding pages/projects to local codebases
- **Version Configuration** - Centralized version management system for templates and dependencies
- Sandpack-based live code preview functionality for generated components
- Support for CodeSandbox workers and iframes in Content Security Policy
- Fallback support for both ffId and database ID in design system API routes
- Dynamic CSS generation with design tokens for preview mode
- Backward compatibility for design systems without ffId field

### Changed
- Enhanced code generation to support better import organization and component structure
- Updated CSP configuration to allow blob: URLs for worker creation
- Improved design token loading to fetch tokens dynamically in preview
- Modified `/api/design-systems/[ffId]/tokens` and `/api/design-systems/[ffId]/processed-tokens` to support both ffId and database ID lookups
- Improved page generation to streamline the export process

### Fixed
- Resolved hardcoded absolute paths in tailwind-generator.ts
- Fixed directory change (process.chdir) issues in Turbopack environment
- Removed debug console.log statements from production code
- Fixed JWT test to properly validate environment variable on token generation
- Corrected ffId passing from page to component for token fetching
- Fixed mismatched quotes in import statements for export endpoints

### Security
- Added security-conscious CSP headers for Sandpack integration
- Maintained strict CSP in production while allowing necessary exceptions for code preview
- ff-id validation for all export endpoints

## v3.1.0 - 2025-08-25

### Added
- hexToVarMap to ColorProcessor for mapping hex values to CSS variable names

### Changed
- Updated SemanticProcessor to use hexToVarMap for proper CSS variable references
- Consolidated cls field to safelist across codebase for better clarity and consistency
- Updated ProcessedTokens type interface to remove cls and animation fields

### Fixed
- Semantic variables now reference CSS variables instead of hex colors for proper theming support
- JWT_SECRET validation now occurs at module load time for early error detection

### Removed
- Unused animation/keyframes processing from token processor
- AnimationProcessor class - animations now handled by standard Tailwind

### Internal
- Improved semantic token processing architecture
- Enhanced type safety in token processing pipeline

## v3.0.0 - 2025-08-18

### Added
- JWT-based authentication system for enhanced security between Figma plugin and platform
- Automatic token refresh with 5-minute pre-expiry detection
- Secure refresh token rotation mechanism with 7-day expiry
- New `/api/plugin/token` endpoint for token management
- CORS configuration for secure Figma plugin communication
- Database schema for refresh token storage and management
- **Role-Based Access Control (RBAC)** system with global and workspace-level roles
  - Global roles: `superadmin` and `user`
  - Workspace roles: `owner`, `admin`, and `member`
- **Waitlist system** for new user onboarding (no automatic workspace creation)
- **Admin panel** at `/admin/users` for superadmins to manage users
- Token family-based reuse detection for enhanced security
- Rate limiting on authentication endpoints
- Comprehensive test suite for authentication and RBAC
- Security headers (CSP, HSTS, X-Frame-Options, etc.)
- Structured security logging system

### Changed
- Plugin authentication migrated from session-based to JWT tokens
- Access tokens now expire after 15 minutes for enhanced security
- Figma plugin now uses clientStorage API instead of localStorage
- **New users no longer get automatic workspace creation** - they see a waitlist page
- Workspace selector moved to settings in Figma plugin
- **Members cannot create or view design systems** (role-based restrictions)
- Environment-based configuration for JWT secrets and CORS origins

### Fixed
- React hooks dependency issues in plugin causing infinite re-renders
- CORS headers configuration for Figma plugin requests

### Security
- Implemented JWT-based authentication with automatic token rotation
- Enhanced security with time-limited access tokens
- Secure storage of refresh tokens in database
- **Token rotation with family-based reuse detection**
- **Rate limiting on auth endpoints** to prevent brute force attacks
- **Sanitized error messages** to prevent information leakage
- **Secure ID generation** using `crypto.randomUUID()`

### Internal
- Active state indicators in sidebar navigation
- Workspace role display in team-switcher
- Role badges in Figma plugin settings
- Superadmin-only local development features in Figma plugin

## v2.0.0 - 2025-06-01

### Added
- New Figma plugin for seamless design-to-code workflow
- Real-time code preview and editing capabilities
- Enhanced project and page management interface
- Email-based authentication with secure access control
- Improved design import workflow

### Changed
- Completely redesigned user interface for better usability
- Significantly improved platform performance and stability
- Enhanced code generation accuracy
- Streamlined project organization

### Removed
- Legacy authentication methods
- Outdated UI components

---

## v1.5.0 - 2025-05-15

### Added
- Dark mode support for improved visual comfort
- Enhanced component library for better design consistency
- Advanced design tokens management
- Improved Figma integration for faster imports

### Changed
- Faster page loading and overall performance improvements
- Optimized code generation speed
- Updated styling system for better customization

### Fixed
- Various visual inconsistencies
- Performance bottlenecks
- Code generation accuracy improvements

---

## v1.0.0 - 2024-09-01

### Added
- Initial release of Frontfriend platform
- Figma to code generation capabilities
- Support for React and Vue frameworks
- Tailwind CSS styling support
- Live component preview
- Secure user authentication

---

*The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).*