@createlex/figgen 1.5.0 → 1.5.3

package/README.md

@@ -103,9 +103,9 @@ For Ollama (fully local):
 
 | Tier | How | Cost |
 |---|---|---|
-| **1 — AI-native** | AI IDE calls `write_selection_to_xcode`; plugin generates code; no extra key needed | Your existing AI subscription |
-| **2 — BYOK** | Set `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, or `HF_API_TOKEN`; MCP server calls the model | Your API key |
-| **3 — CreateLex hosted** | No keys set; falls back to hosted pattern matcher | CreateLex subscription |
+| **1 — AI-native** | AI IDE calls `figma_to_swiftui`; server exports assets and returns either a validated one-shot write or a prompt package for the IDE model to finish with `write_generated_swiftui_to_xcode` | Your existing AI subscription |
+| **2 — BYOK** | Set `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, or `HF_API_TOKEN`; MCP server calls the model and only accepts the result if it passes a fidelity check | Your API key |
+| **3 — CreateLex hosted** | No keys set; server may use hosted semantic generation, but rejects low-fidelity output and falls back to the AI-native prompt package | CreateLex subscription |
 
 ### Login (Tier 3 only)
 
@@ -121,12 +121,12 @@ npx @createlex/figgen login
 ```
 1. Select a frame in Figma
 2. Ask your AI: "Generate SwiftUI for my selected Figma frame"
-3. AI calls write_selection_to_xcode
-4. Plugin generates code + exports PNG/SVG assets
-5. Files appear in Xcode immediately
+3. AI calls `figma_to_swiftui`
+4. If `oneShot=true`, files are already written to Xcode
+5. If `oneShot=false`, AI uses `generationPrompt` to generate SwiftUI and then calls `write_generated_swiftui_to_xcode`
 ```
 
-**Critical:** `write_selection_to_xcode` **overwrites the Swift file** on every call. Apply all manual refinements (adaptive layout, hidden node removal, real buttons, etc.) **after** the last MCP call, not before.
+**Critical:** `write_selection_to_xcode` **overwrites the Swift file** on every call and is now best treated as a direct-write scaffold tool, not the default high-fidelity path. Apply all manual refinements (adaptive layout, hidden node removal, real buttons, etc.) **after** the last MCP call, not before.
 
 To hide a node from export: set it invisible in Figma before running. Hidden nodes (`visible: false`) are skipped in both the asset export plan and code generation.
 
@@ -159,7 +159,7 @@ To hide a node from export: set it invisible in Figma before running. Hidden nod
 | Tool | Parameters | Description |
 |---|---|---|
 | `get_design_context` | `excludeScreenshot` (bool) | Full node tree + asset export plan + generation hints. Also available via `GET http://localhost:7765/design-context` |
-| `get_swiftui_generation_prompt` | — | Returns `systemPrompt` + `userMessage` to feed to any LLM manually |
+| `get_swiftui_generation_prompt` | — | Returns `systemPrompt` + `userMessage` for the preferred AI-native high-fidelity workflow |
 | `generate_swiftui` | `generationMode`, `scope` | Runs plugin generator; returns code without writing to disk |
 | `analyze_generation` | `generationMode` | Code + per-node diagnostics + refinement hints |
 
@@ -177,10 +177,10 @@ To hide a node from export: set it invisible in Figma before running. Hidden nod
 |---|---|---|
 | `get_project_path` | — | Reads saved Xcode source folder |
 | `set_project_path` | `path` | Persists Xcode project path to config |
-| `write_selection_to_xcode` | `generationMode`, `includeOverflow`, `projectPath`, `nodeIds` | **Primary tool.** Generates from Figma selection + exports PNG/SVG assets + writes Swift + asset catalog in one call |
+| `write_selection_to_xcode` | `generationMode`, `includeOverflow`, `projectPath`, `nodeIds` | Direct-write scaffold tool. Generates from Figma selection + exports PNG/SVG assets + writes Swift + asset catalog in one call |
 | `write_generated_swiftui_to_xcode` | `code`, `structName`, `images[]`, `additionalFiles[]`, `projectPath` | Writes pre-generated Swift code + manually provided image payloads |
 | `write_svg_to_xcode` | `nodeId`, `assetName` | Exports a single SVG directly to Assets.xcassets |
-| `figma_to_swiftui` | `scope`, `generationMode` | One-shot: generates code + assets + tokens + components in a single response |
+| `figma_to_swiftui` | `scope`, `generationMode` | Preferred universal entrypoint. Exports assets, then either writes validated one-shot output or returns an AI-native prompt package |
 
 ### Component analysis
 
@@ -190,8 +190,8 @@ To hide a node from export: set it invisible in Figma before running. Hidden nod
 
 ### `write_selection_to_xcode` vs `write_generated_swiftui_to_xcode`
 
-- **`write_selection_to_xcode`** — plugin generates code AND exports assets automatically. One call does everything. This is what the AI should use in the standard workflow.
-- **`write_generated_swiftui_to_xcode`** — you supply the Swift code string and base64-encoded image payloads. Use when an external LLM generated the code and you need to write it plus manually gathered assets to disk.
+- **`write_selection_to_xcode`** — plugin generates code AND exports assets automatically. Use this when you explicitly want an immediate local scaffold write and can tolerate lower fidelity than the AI-native flow.
+- **`write_generated_swiftui_to_xcode`** — you supply the Swift code string and base64-encoded image payloads. This is the preferred final write step when an external or IDE-integrated LLM generated the code from the prompt package.
 
 ---
 

package/companion/bridge-server.cjs

@@ -316,13 +316,14 @@ function startBridgeServer(options = {}) {
     const assetCount = data.assetExportPlan?.candidates?.length ?? 0;
     const aiWorkflow = {
       IF_YOU_HAVE_MCP_ACCESS: {
-        step1: 'Call the MCP tool `write_selection_to_xcode` with generationMode="editable" (the default). It exports individual PNG assets with correct blendMode info and generates Image("name").blendMode() calls automatically.',
-        step2: 'After write_selection_to_xcode returns, ONLY refine: add GeometryReader for responsiveness, wire @State interactions. DO NOT rewrite Image("name") calls, DO NOT switch to fidelity mode unless the whole frame is a single photo with no text.',
-        mcpTool: 'write_selection_to_xcode',
+        step1: 'Call the MCP tool `figma_to_swiftui` with generationMode="editable" (the default). It exports the assets first, then either writes SwiftUI directly if the one-shot result passes a fidelity check, or returns an AI-native prompt package.',
+        step2: 'If figma_to_swiftui returns oneShot=false, use generationPrompt.systemPrompt as the system message and generationPrompt.userMessage as the user message, then write the result with `write_generated_swiftui_to_xcode`.',
+        step3: 'After code is written, ONLY refine: add GeometryReader for responsiveness, wire @State interactions, and extract reusable subviews. DO NOT rewrite Image("name") calls, DO NOT switch to fidelity mode unless the whole frame is a single photo with no text.',
+        mcpTool: 'figma_to_swiftui',
         mcpServer: 'figma-swiftui',
       },
       IF_NO_MCP_ACCESS: {
-        instruction: 'Use _generationPrompt.systemPrompt as the system message and _generationPrompt.userMessage as the user message to generate native SwiftUI code. Output individual SwiftUI views — Text(), VStack, HStack, ZStack, Image("name") — NOT a single composite Image().',
+        instruction: 'Use _generationPrompt.systemPrompt as the system message and _generationPrompt.userMessage as the user message to generate native SwiftUI code. Output individual SwiftUI views — Text(), VStack, HStack, ZStack, Image("name") — NOT a single composite Image() or placeholder scaffold.',
         rule1: 'Every asset in assetExportPlan.candidates MUST become Image("assetName").resizable() — never Rectangle() or Color.',
         rule2: 'Text nodes become Text("content") with .font(.system(size: X, weight: .bold)) — NEVER custom font names.',
         rule3: 'Output a full SwiftUI View struct with individual elements positioned using the node geometry in the design context.',

package/companion/mcp-server.mjs

@@ -106,6 +106,59 @@ function ensureRuntimeAuthorized() {
   }
 }
 
+function countImageReferences(code, imageNames = []) {
+  if (!code) return 0;
+  if (imageNames.length === 0) {
+    return (code.match(/Image\("/g) || []).length;
+  }
+  return imageNames.reduce((count, imageName) => {
+    return count + (code.includes(`Image("${imageName}")`) ? 1 : 0);
+  }, 0);
+}
+
+function countTextLiterals(root) {
+  if (!root || typeof root !== 'object') return 0;
+  let count = 0;
+  const stack = [root];
+  while (stack.length > 0) {
+    const current = stack.pop();
+    if (!current || typeof current !== 'object') continue;
+    if (current.type === 'TEXT' && current.text?.characters) {
+      count += 1;
+    }
+    if (Array.isArray(current.children)) {
+      stack.push(...current.children);
+    }
+  }
+  return count;
+}
+
+function isLowFidelitySemanticResult({ code, context, imageNames = [] }) {
+  if (!code || typeof code !== 'string') return true;
+
+  const metadata = context?.metadata;
+  const root = Array.isArray(metadata?.nodes) ? metadata.nodes[0] : metadata;
+  const assetCandidates = context?.assetExportPlan?.candidates ?? [];
+  const imageReferenceCount = countImageReferences(code, imageNames);
+  const textNodeCount = countTextLiterals(root);
+  const primitiveCount = (code.match(/\b(Text|Image|Button|TextField|Toggle|Picker|VStack|HStack|ZStack)\b/g) || []).length;
+  const rectangleCount = (code.match(/\bRectangle\(/g) || []).length;
+
+  if (assetCandidates.length >= 3 && imageReferenceCount === 0) {
+    return true;
+  }
+
+  if (textNodeCount >= 3 && primitiveCount <= 8) {
+    return true;
+  }
+
+  if (rectangleCount > 0 && imageReferenceCount < Math.min(2, assetCandidates.length)) {
+    return true;
+  }
+
+  return false;
+}
+
 async function tryHostedSemanticGeneration({ nodeIds, generationMode, includeOverflow, analyze }) {
   if (generationMode !== 'editable') {
     return null;
@@ -123,23 +176,27 @@ async function tryHostedSemanticGeneration({ nodeIds, generationMode, includeOve
     try {
       const byokResult = await generateWithLocalKey(context, generationMode);
       if (byokResult?.handled) {
-        const metadata = context?.metadata;
-        const selection = Array.isArray(metadata?.nodes)
-          ? { ids: metadata.nodes.map((n) => n.id), names: metadata.nodes.map((n) => n.name) }
-          : { ids: [metadata?.id], names: [metadata?.name] };
-
-        if (analyze) {
-          return {
-            selection: metadata,
-            generated: { ...byokResult, imageCount: 0, imageNames: [] },
-            assetExportPlan: context?.assetExportPlan ?? null,
-            reusableComponents: context?.reusableComponents ?? null,
-            generationHints: context?.generationHints ?? null,
-            manualRefinementHints: context?.generationHints?.manualRefinementHints ?? [],
-            hosted: false,
-          };
+        if (!analyze && isLowFidelitySemanticResult({ code: byokResult.code, context })) {
+          console.warn('[figgen] Rejecting low-fidelity BYOK semantic result; falling back.');
+        } else {
+          const metadata = context?.metadata;
+          const selection = Array.isArray(metadata?.nodes)
+            ? { ids: metadata.nodes.map((n) => n.id), names: metadata.nodes.map((n) => n.name) }
+            : { ids: [metadata?.id], names: [metadata?.name] };
+
+          if (analyze) {
+            return {
+              selection: metadata,
+              generated: { ...byokResult, imageCount: 0, imageNames: [] },
+              assetExportPlan: context?.assetExportPlan ?? null,
+              reusableComponents: context?.reusableComponents ?? null,
+              generationHints: context?.generationHints ?? null,
+              manualRefinementHints: context?.generationHints?.manualRefinementHints ?? [],
+              hosted: false,
+            };
+          }
+          return { ...byokResult, selection, imageCount: 0, imageNames: [], hosted: false };
         }
-        return { ...byokResult, selection, imageCount: 0, imageNames: [], hosted: false };
       }
     } catch (byokError) {
       console.error('[figgen] BYOK generation failed, falling back to hosted:', byokError.message);
@@ -167,6 +224,11 @@ async function tryHostedSemanticGeneration({ nodeIds, generationMode, includeOve
     return null;
   }
 
+  if (!analyze && isLowFidelitySemanticResult({ code: data.code, context })) {
+    console.warn('[figgen] Rejecting low-fidelity hosted semantic result; falling back.');
+    return null;
+  }
+
   const selection = Array.isArray(metadata?.nodes)
     ? {
         ids: metadata.nodes.map((node) => node.id),
@@ -423,7 +485,7 @@ server.registerTool('get_metadata', {
 });
 
 server.registerTool('get_design_context', {
-  description: 'Return node metadata, asset export candidates, and generation hints for the current Figma selection. PREFERRED WORKFLOW: call figma_to_swiftui instead — it handles LLM generation, Image("name") asset refs, PNG export, DesignTokens, and reusable components in one shot. Only call get_design_context if you need to inspect the raw node tree before generating.',
+  description: 'Return node metadata, asset export candidates, and generation hints for the current Figma selection. For high-fidelity results across all models and IDEs, use this with get_swiftui_generation_prompt or figma_to_swiftui\'s AI-native fallback instead of relying on a one-shot scaffold write.',
   inputSchema: {
     nodeIds: z.array(z.string()).optional().describe('Optional list of Figma node ids. If omitted, uses the current selection'),
     nodeId: z.string().optional().describe('Optional single Figma node id'),
@@ -441,7 +503,7 @@ server.registerTool('get_design_context', {
 });
 
 server.registerTool('get_swiftui_generation_prompt', {
-  description: 'Return a ready-to-use SwiftUI system prompt and user message for AI-native generation. PREFERRED: use figma_to_swiftui instead — it pre-writes assets and handles LLM generation automatically. Only use get_swiftui_generation_prompt when you need the raw prompt. If you do: (a) use .font(.system(size:weight:)) — never hardcode custom font names like Inter or Roboto, (b) reference every assetExportPlan entry as Image("name") not Rectangle().',
+  description: 'Return a ready-to-use SwiftUI system prompt and user message for AI-native generation. This is the preferred high-fidelity path for all models and IDEs: generate code from the prompt, then write it with write_generated_swiftui_to_xcode. Use .font(.system(size:weight:)) and reference every exported asset as Image("name"), never Rectangle().',
   inputSchema: {
     nodeIds: z.array(z.string()).optional().describe('Optional list of Figma node ids. If omitted, uses the current selection'),
     nodeId: z.string().optional().describe('Optional single Figma node id'),
@@ -768,7 +830,7 @@ server.registerTool('write_generated_swiftui_to_xcode', {
 });
 
 server.registerTool('write_selection_to_xcode', {
-  description: 'Generate SwiftUI from the connected Figma selection and write it into the configured Xcode project. THIS IS THE CORRECT TOOL TO CALL — it exports real PNG assets to Assets.xcassets and generates Image("name") references automatically. Always use the default generationMode="editable" — individual assets include blendModeSwiftUI values so blend modes are applied correctly on each Image(). Only use generationMode="fidelity" when the ENTIRE frame is a single photographic image or illustration with no text, no interactive elements, and no distinct layers (e.g. a full-bleed photo background).',
+  description: 'Generate SwiftUI from the connected Figma selection and write it directly into the configured Xcode project. Use this when you explicitly want an immediate local scaffold write. For the most reliable cross-model, cross-IDE high-fidelity workflow, prefer figma_to_swiftui or get_swiftui_generation_prompt plus write_generated_swiftui_to_xcode. Always use generationMode="editable" unless the ENTIRE frame is a single photographic image or illustration with no text or interactive elements.',
   inputSchema: {
     nodeIds: z.array(z.string()).optional().describe('Optional list of Figma node ids. If omitted, uses the current selection'),
     includeOverflow: z.boolean().default(false).describe('Ignore Figma clipping when generating layout'),
@@ -828,18 +890,8 @@ server.registerTool('write_selection_to_xcode', {
     includeImages: true,
   });
 
-  const images = Array.isArray(generated.images) ? generated.images : [];
-  const imageNames = images.map((img) => img.name);
-
-  // If the hosted provider returned a generic template that doesn't reference any exported
-  // assets, fall back to the plugin-generated code which has correct Image("name") calls.
-  const hostedMissedAssets =
-    imageNames.length > 0 &&
-    llmCode &&
-    !imageNames.some((n) => llmCode.includes(`Image("${n}")`));
-
-  // Prefer LLM-generated code only when it actually wires up the exported assets.
-  const finalCode = hostedMissedAssets ? (generated.code || llmCode) : (llmCode || generated.code);
+  // Prefer LLM-generated code over template-generated code
+  const finalCode = llmCode || generated.code;
 
   const effectiveStructName = inferStructName({
     code: finalCode,
@@ -850,7 +902,7 @@ server.registerTool('write_selection_to_xcode', {
     targetDir,
     code: finalCode,
     structName: effectiveStructName,
-    images,
+    images: Array.isArray(generated.images) ? generated.images : [],
     additionalFiles: llmAdditionalFiles,
   });
 
@@ -870,6 +922,8 @@ server.registerTool('write_selection_to_xcode', {
     filePath: result.results?.swiftFile ?? null,
   });
 
+  const imageNames = (generated.images ?? []).map((img) => img.name);
+
   return jsonResult(buildCompactResponse({
     result,
     structName: effectiveStructName,
@@ -894,9 +948,9 @@ server.registerTool('write_selection_to_xcode', {
 
 server.registerTool('figma_to_swiftui', {
   description:
-    'One-shot Figma-to-SwiftUI: generates production-ready SwiftUI code from the current Figma selection (or all page frames) and writes it to the Xcode project — including PNG assets, DesignTokens.swift, and reusable components. ' +
-    'With BYOK keys (ANTHROPIC_API_KEY / OPENAI_API_KEY) or a CreateLex subscription this is a TRUE single-call operation. ' +
-    'Without those, it pre-writes assets and returns a structured prompt so the calling AI can generate code and finish with one more write_generated_swiftui_to_xcode call. ' +
+    'Universal Figma-to-SwiftUI entrypoint for all models and IDEs. It inspects the current Figma selection (or all page frames), exports PNG assets, and then either: ' +
+    '(a) writes SwiftUI directly if one-shot generation passes a fidelity check, or ' +
+    '(b) returns a structured AI-native prompt package so the calling model can generate code and finish with write_generated_swiftui_to_xcode. ' +
     'Use scope="page" to batch-generate every top-level frame on the current page.',
   inputSchema: {
     nodeIds: z.array(z.string()).optional().describe('Optional list of Figma node ids. If omitted, uses the current selection'),
@@ -950,13 +1004,18 @@ server.registerTool('figma_to_swiftui', {
   // 4. Attempt LLM generation (Tier 2 BYOK → Tier 3 Hosted)
   // -------------------------------------------------------------------------
   let llmResult = null;
+  let fidelityFallback = null;
 
   // Tier 2: BYOK
   if (process.env.ANTHROPIC_API_KEY || process.env.HF_API_TOKEN || process.env.OPENAI_API_KEY) {
     try {
       const byokResult = await generateWithLocalKey(context, generationMode);
       if (byokResult?.handled) {
-        llmResult = byokResult;
+        if (isLowFidelitySemanticResult({ code: byokResult.code, context, imageNames })) {
+          fidelityFallback = `Rejected low-fidelity BYOK output from ${byokResult.provider}. Returning the AI-native prompt package instead.`;
+        } else {
+          llmResult = byokResult;
+        }
       }
     } catch (err) {
       console.error('[figgen] BYOK generation failed:', err?.message ?? err);
@@ -973,10 +1032,9 @@ server.registerTool('figma_to_swiftui', {
           context,
           generationMode,
           includeOverflow,
-          imageNames,
         });
         if (response.ok && data?.handled) {
-          llmResult = {
+          const hostedResult = {
             handled: true,
             provider: data.provider || 'createlex-hosted',
             code: data.code,
@@ -984,6 +1042,11 @@ server.registerTool('figma_to_swiftui', {
             componentFiles: [],
             diagnostics: data.diagnostics || [],
           };
+          if (isLowFidelitySemanticResult({ code: hostedResult.code, context, imageNames })) {
+            fidelityFallback = `Rejected low-fidelity hosted output from ${hostedResult.provider}. Returning the AI-native prompt package instead.`;
+          } else {
+            llmResult = hostedResult;
+          }
         }
       }
     } catch (err) {
@@ -996,14 +1059,7 @@ server.registerTool('figma_to_swiftui', {
   // -------------------------------------------------------------------------
   if (llmResult) {
     const parsed = parseClaudeResponse(llmResult.code || '');
-    const llmCode = parsed.code || llmResult.code || '';
-    // If the hosted provider returned a generic template that doesn't reference any exported
-    // assets, fall back to the plugin-generated code which has correct Image("name") calls.
-    const hostedMissedAssets =
-      llmResult.provider === 'createlex-hosted' &&
-      imageNames.length > 0 &&
-      !imageNames.some((n) => llmCode.includes(`Image("${n}")`));
-    const finalCode = hostedMissedAssets ? (generated.code || llmCode) : (llmCode || generated.code);
+    const finalCode = parsed.code || llmResult.code || generated.code;
     const effectiveStructName = inferStructName({
       code: finalCode,
       selectionNames: generated.selection?.names ?? [],
@@ -1157,6 +1213,7 @@ server.registerTool('figma_to_swiftui', {
       assetsPreWritten
         ? `🖼  ${imageNames.length} PNG asset(s) pre-written to Assets.xcassets: ${imageNames.join(', ')}.`
         : null,
+      fidelityFallback,
       'Generate SwiftUI code using the generationPrompt above (systemPrompt + userMessage).',
       'Output code using <file name="StructName.swift"> XML tags.',
       'Then call write_generated_swiftui_to_xcode with the generated code and images:[] (assets are already on disk).',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@createlex/figgen",
-  "version": "1.5.0",
+  "version": "1.5.3",
   "description": "CreateLex MCP runtime for Figma-to-SwiftUI generation and Xcode export",
   "bin": {
     "figgen": "bin/figgen.js"