feat: Text Management Tool with style fixes and duplicate removal (v0.29.0)

- Add manage_text tool for text operations and style management
- Remove text creation from create_node tool to eliminate duplication
- Fix style deletion trailing comma issues in Figma API operations
- Fix font loading in all text operations to prevent "unloaded font" errors
- Remove convert_to_vectors operation from manage_text (use boolean_operations instead)
- Add version tracking to all get_plugin_status responses

Designed with ❤️ by oO. Coded with ✨ by Claude Sonnet 4
Co-authored-by: Claude.AI <[email protected]>

Author: oO

CHANGELOG.md

@@ -5,6 +5,33 @@ All notable changes to this project will be documented in this file.
 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).
 
+## [0.29.0] - 2025-06-24
+
+### Added
+- **Text Management Tool**: New `manage_text` tool for text operations in Figma
+  - Create text nodes with font loading and fallback system
+  - Update existing text content and formatting  
+  - Character-level styling with mixed formatting support
+  - Apply and create text styles for design system consistency
+  - Hyperlink support for interactive text elements
+  - Replaces previous typography functionality with streamlined interface
+
+### Removed
+- **Text Creation from create_node**: Text creation removed from `create_node` tool to eliminate duplication
+  - Users should use `manage_text` tool for all text operations
+  - `create_node` now supports: rectangle, ellipse, frame (no longer text)
+  - Removed text-related parameters: content, fontSize, fontFamily, fontStyle, textAlignHorizontal
+
+### Fixed
+- **Style Management Reliability**: Fixed trailing comma issues in Figma API style operations
+  - Style deletion now properly handles Figma's trailing comma style IDs
+  - Text style application uses correct style ID format for setTextStyleIdAsync
+  - Style response formatting removes trailing commas for consistent parameter usage
+- **Font Loading in Text Operations**: Added comprehensive font loading to prevent "unloaded font" errors
+  - All text operations now load fonts before applying changes
+  - Font loading applied to create, update, character styling, and style operations
+- **Plugin Status Versioning**: All get_plugin_status responses now include version information
+
 ## [0.28.2] - 2025-06-21
 
 ### Fixed

CLAUDE.md

@@ -58,9 +58,85 @@ Co-authored-by: Claude.AI <[email protected]>
 - Use descriptive variable and function names
 - Follow existing patterns for consistency
 
+### Figma API Patterns
+**CRITICAL**: Always follow the correct Figma API patterns and handle known API quirks:
+
+**Style ID Trailing Comma Issue:**
+```typescript
+// ✅ CRITICAL FIX: Figma's getLocalTextStyles() and similar methods return style IDs with trailing commas
+// Always clean style IDs before using them for lookups or operations
+const cleanStyleId = styleId.replace(/,$/, '');
+
+// Apply this fix in:
+// - Style deletion: allStyles.find(s => s.id.replace(/,$/, '') === params.styleId)
+// - Text style application: await text.setTextStyleIdAsync(cleanStyleId)
+// - Style retrieval: style = allStyles.find(s => s.id.replace(/,$/, '') === params.styleId)
+```
+
+**Style Deletion Pattern:**
+```typescript
+// ✅ CORRECT: Find style from local collections, then remove
+const paintStyles = figma.getLocalPaintStyles();
+const textStyles = figma.getLocalTextStyles();
+const allStyles = [...paintStyles, ...textStyles, ...effectStyles, ...gridStyles];
+const style = allStyles.find(s => s.id.replace(/,$/, '') === params.styleId);
+style.remove();
+
+// ❌ INCORRECT: figma.getStyleByIdAsync() doesn't exist in Plugin API
+// ❌ INCORRECT: Cannot delete styles directly by ID
+```
+
+**Text Style Application Pattern:**
+```typescript
+// ✅ CORRECT: Clean style ID before application
+const cleanStyleId = params.textStyleId.replace(/,$/, '');
+await text.setTextStyleIdAsync(cleanStyleId);
+
+// ❌ INCORRECT: Using style ID with trailing comma will fail silently
+// await text.setTextStyleIdAsync(params.textStyleId); // Will clear textStyleId to empty string
+```
+
+**Key Principles:**
+- **ALWAYS** remove trailing commas from style IDs before any operations
+- Style operations require searching through local style collections, not direct API calls
+- Text style application must use cleaned style IDs to work properly
+- Handle style not found errors properly in try/catch blocks
+
 ### Implementation Pattern Guidelines
 **CRITICAL**: Before implementing any new feature, always examine existing implementations first to match established patterns.
 
+#### MCP Tool Parameter Design Pattern
+**ALWAYS use flat parameter structures** - never nest objects for tool parameters:
+
+**✅ CORRECT (Flat):**
+```json
+{
+  "operation": "create_text_style",
+  "nodeId": "123:456",
+  "styleName": "Heading Large", 
+  "styleDescription": "Main heading style"
+}
+```
+
+**❌ INCORRECT (Nested):**
+```json
+{
+  "operation": "create_text_style",
+  "nodeId": "123:456",
+  "createTextStyle": {
+    "name": "Heading Large",
+    "description": "Main heading style"
+  }
+}
+```
+
+**Design Principles:**
+- All tool parameters must be at the root level of the parameter object
+- Use descriptive flat parameter names (e.g., `styleName`, `styleDescription`)
+- Never create nested configuration objects in tool interfaces
+- This ensures consistency across all MCP tools and simplifies parameter handling
+- Follow the pattern established by `manage_styles`, `manage_components`, and all existing tools
+
 #### Handler Implementation Pattern
 When adding new handlers to the Figma plugin:
 1. **First**: Read existing handlers (e.g., `style-handler.ts`, `node-handler.ts`) to understand the pattern
@@ -86,29 +162,59 @@ export class NewHandler extends BaseHandler {
 ```
 3. **Do NOT use**: `async handle(type: string, payload: any)` patterns
 4. **Always match**: The exact interface contracts used by existing handlers
+5. **Always use flat parameters**: Convert flat parameters to internal objects if needed for helper functions
 
 ### Documentation Guidelines
 
-**IMPORTANT**: During the pre-release phase, documentation should be factual and concise about the current state of the tool, not changes or future plans.
+**CRITICAL PRE-RELEASE RULE**: During pre-release phase (major version < 1.0.0), ALL documentation must reflect the current state only. Do NOT document changes, history, or what was added/removed - that's only for CHANGELOG.md.
+
+#### Pre-Release Documentation Rules
+- **Current State Only**: All documentation (README, DEVELOPMENT, EXAMPLES) describes what the tool does NOW
+- **No Change Documentation**: Never mention "new", "added", "updated", "removed", "replaced" in documentation files
+- **No Version History**: Don't reference previous versions or what changed between versions
+- **No Migration Notes**: Don't include upgrade instructions or breaking change notices
+- **Exception**: CHANGELOG.md is the ONLY file that documents changes commit-to-commit
 
 #### Writing Style
 - **Avoid superlatives**: Do not use words like "comprehensive", "complete", "robust", "extensive", "advanced", "cutting-edge", "powerful", "seamless", etc.
 - **No test counting**: Do not mention specific test numbers in documentation as they change frequently and add no value to users
 - **Be direct**: Use simple, clear language without marketing fluff
 - **Focus on functionality**: Describe what tools do, not how amazing they are
+- **Present tense only**: Use present tense to describe current capabilities
 
-#### Documentation Files
-- **README.md**: Main project documentation - should reflect current capabilities and setup instructions
-- **DEVELOPMENT.md**: Technical documentation for contributors - architecture, development workflow, testing
-- **EXAMPLES.md**: Usage examples and workflows - should demonstrate actual current functionality
-- **CHANGELOG.md**: Exception to the rule - tracks changes from one commit to the next, documents incremental changes within sessions
+#### Documentation Files (Pre-Release < 1.0.0)
+- **README.md**: Current project state - capabilities and setup instructions as they exist now
+- **DEVELOPMENT.md**: Current technical architecture - how the system works now for contributors
+- **EXAMPLES.md**: Current usage patterns - how to use the tools that exist now
+- **CHANGELOG.md**: ONLY exception - tracks changes from one commit to the next
 
 #### Documentation Principles
 - Stay factual and concise about current state
 - Avoid hardcoded numbers that require frequent maintenance updates
-- Focus on "what it does now" not "what it will do"
-- Only CHANGELOG.md should document changes and progression
+- Focus on "what it does now" not "what it will do" or "what it used to do"
+- ONLY CHANGELOG.md documents changes and progression
 - Use clear, direct language without superlatives
+- Write as if this is the first version anyone has ever seen
+
+#### Documentation Scope for Commits
+**CRITICAL**: Documentation should only cover changes since the last commit, not intermediate development steps.
+
+**Process for documenting changes:**
+1. **Check actual changes**: Use `git status --porcelain` and `git diff --name-status HEAD` to see what files were modified, added, or deleted since the last commit
+2. **Document only commit-level changes**: Do not document intermediate development steps or work-in-progress changes
+3. **Use git diff to understand scope**: Review actual code changes to understand what functionality was added, removed, or modified
+4. **Examples of what to document**:
+   - New tools added (complete functionality, not development iterations)
+   - Tools removed or deprecated
+   - Breaking changes to existing tool interfaces
+   - New major features or architectural changes
+5. **Examples of what NOT to document**:
+   - Intermediate refactoring steps during development
+   - Temporary fixes that were later replaced
+   - Development debugging or testing iterations
+   - Changes that were made and then reverted in the same session
+
+**For this project**: Compare the current state against the last git commit to determine what actually changed, then document only those changes in CHANGELOG.md.
 
 ## Project Architecture
 

figma-plugin/src/handlers/style-handler.ts

@@ -266,7 +266,8 @@ export class StyleHandler extends BaseHandler {
       const effectStyles = figma.getLocalEffectStyles();
       const gridStyles = figma.getLocalGridStyles();
       const allStyles = [...paintStyles, ...textStyles, ...effectStyles, ...gridStyles] as any[];
-      style = allStyles.find(s => s.id === params.styleId);
+      // Fix: Remove trailing comma from style IDs (Figma API bug)
+      style = allStyles.find(s => s.id.replace(/,$/, '') === params.styleId);
     } else if (params.styleName) {
       const paintStyles = figma.getLocalPaintStyles();
       const textStyles = figma.getLocalTextStyles();
@@ -314,55 +315,93 @@ export class StyleHandler extends BaseHandler {
   }
 
   private async deleteStyle(params: StyleParams): Promise<any> {
-    let style: PaintStyle | TextStyle | EffectStyle | GridStyle | undefined;
+    this.validateParams(params, ['styleId']);
+    
+    // Debug: Log the requested style ID
+    console.log('DELETE STYLE DEBUG - Requested ID:', params.styleId);
 
+    // Find the style by searching through all local styles
     const paintStyles = figma.getLocalPaintStyles();
     const textStyles = figma.getLocalTextStyles();
     const effectStyles = figma.getLocalEffectStyles();
     const gridStyles = figma.getLocalGridStyles();
-    const allStyles = [...paintStyles, ...textStyles, ...effectStyles, ...gridStyles] as any[];
+    const allStyles = [...paintStyles, ...textStyles, ...effectStyles, ...gridStyles];
 
-    if (params.styleId) {
-      style = allStyles.find(s => s.id === params.styleId);
-    } else if (params.styleName) {
-      style = allStyles.find(s => s.name === params.styleName);
-    }
+    // Debug: Log all available style IDs
+    console.log('DELETE STYLE DEBUG - Available style IDs:');
+    allStyles.forEach(s => {
+      console.log(`  - ${s.name}: ${s.id} (type: ${s.type})`);
+    });
+    
+    // Fix: Remove trailing comma from style IDs (Figma API bug)
+    const style = allStyles.find(s => s.id.replace(/,$/, '') === params.styleId);
+    
+    console.log('DELETE STYLE DEBUG - Fixed comparison result:', !!style);
 
     if (!style) {
-      throw new Error('Style not found');
+      // Enhanced error with more debugging info
+      throw new Error(`Style not found with ID: ${params.styleId}. Found ${allStyles.length} total styles in file. Check console for available IDs.`);
     }
 
-    const styleInfo = {
+    console.log('DELETE STYLE DEBUG - Found style to delete:', {
       id: style.id,
       name: style.name,
       type: style.type
+    });
+    
+    // Capture style info BEFORE deletion - create minimal response to avoid issues
+    const styleInfo: any = {
+      id: style.id.replace(/,$/, ''), // Clean ID for response
+      name: style.name,
+      type: style.type
     };
 
+    // Safely capture description
+    try {
+      styleInfo.description = style.description || '';
+    } catch (e) {
+      styleInfo.description = '';
+    }
+    
+    // Safely add type-specific properties before deletion
+    if (style.type === 'TEXT') {
+      try {
+        const textStyle = style as TextStyle;
+        styleInfo.fontName = textStyle.fontName;
+        styleInfo.fontSize = textStyle.fontSize;
+        styleInfo.letterSpacing = textStyle.letterSpacing;
+        styleInfo.lineHeight = textStyle.lineHeight;
+      } catch (e) {
+        console.warn('Could not capture text style properties:', e);
+      }
+    }
+    
+    // Delete the style using the correct API pattern
     style.remove();
 
+    console.log('DELETE STYLE DEBUG - Style removed successfully');
+    
     return {
       deletedStyle: styleInfo,
-      message: `Deleted ${style.type.toLowerCase()} style "${style.name}"`
+      message: `Successfully deleted ${styleInfo.type.toLowerCase()} style "${styleInfo.name}"`
     };
   }
 
   private async getStyle(params: StyleParams): Promise<any> {
-    let style: PaintStyle | TextStyle | EffectStyle | GridStyle | undefined;
+    this.validateParams(params, ['styleId']);
 
+    // Find the style by searching through all local styles
     const paintStyles = figma.getLocalPaintStyles();
     const textStyles = figma.getLocalTextStyles();
     const effectStyles = figma.getLocalEffectStyles();
     const gridStyles = figma.getLocalGridStyles();
-    const allStyles = [...paintStyles, ...textStyles, ...effectStyles, ...gridStyles] as any[];
+    const allStyles = [...paintStyles, ...textStyles, ...effectStyles, ...gridStyles];
 
-    if (params.styleId) {
-      style = allStyles.find(s => s.id === params.styleId);
-    } else if (params.styleName) {
-      style = allStyles.find(s => s.name === params.styleName);
-    }
+    // Fix: Remove trailing comma from style IDs (Figma API bug)
+    const style = allStyles.find(s => s.id.replace(/,$/, '') === params.styleId);
 
     if (!style) {
-      throw new Error('Style not found');
+      throw new Error(`Style not found with ID: ${params.styleId}`);
     }
 
     return formatStyleResponse(style);