@sun-asterisk/sungen 2.4.6 → 2.5.1

package/src/generators/test-generator/code-generator.ts

@@ -3,6 +3,7 @@ import path from 'path';
 import { ParsedFeature, ParsedScenario, ParsedStep } from '../gherkin-parser';
 import { StepMapper } from './step-mapper';
 import { TestGeneratorAdapter, adapterRegistry } from './adapters';
+import { transformToRuntimeData } from './utils/runtime-data-transformer';
 
 /**
  * Filter base scenario steps for @extend: only keep Given→When steps.
@@ -27,6 +28,33 @@ function filterBaseStepsForExtend(steps: ParsedStep[]): ParsedStep[] {
   return result;
 }
 
+/**
+ * Extract @cleanup:* tags into autoCleanup config string for test.use()
+ * @cleanup:overlay @cleanup:forms → 'overlay: true, forms: true'
+ */
+function extractCleanupConfig(tags: string[]): string | undefined {
+  const validKeys = ['overlay', 'forms', 'scroll', 'storage'];
+  const entries = tags
+    .filter(t => t.startsWith('@cleanup:'))
+    .map(t => t.replace('@cleanup:', ''))
+    .filter(key => {
+      if (!validKeys.includes(key)) {
+        console.warn(`⚠ Unknown @cleanup:${key} — valid options: ${validKeys.join(', ')}`);
+        return false;
+      }
+      return true;
+    });
+  if (entries.length === 0) return undefined;
+  return entries.map(key => `${key}: true`).join(', ');
+}
+
+/**
+ * Check for @screenshot:on-failure tag
+ */
+function hasScreenshotOnFailure(tags: string[]): boolean {
+  return tags.includes('@screenshot:on-failure');
+}
+
 /**
  * Extract auth role from tags
  * @auth:admin → 'admin'
@@ -106,7 +134,7 @@ export class CodeGenerator {
   // Steps registry built per feature during generateTestCode(); used by countSteps()
   private stepsRegistry = new Map<string, ParsedScenario>();
 
-  constructor(options: { useAI?: boolean; verbose?: boolean; framework?: string; baseURL?: string; screenName?: string } = {}) {
+  constructor(options: { useAI?: boolean; verbose?: boolean; framework?: string; baseURL?: string; screenName?: string; runtimeData?: boolean } = {}) {
     this.options = options;
     this.screenName = options.screenName;
     this.stepMapper = new StepMapper(options);
@@ -155,14 +183,19 @@ export class CodeGenerator {
       : path.join(outputDir, fileName);
 
     // Generate imports using adapter
-    const imports = this.adapter.renderImports();
+    const imports = this.adapter.renderImports({ runtimeData: this.options.runtimeData });
 
     // Generate test code (async now to support AI mapping)
     const testCode = await this.generateTestCode(feature);
 
     // Combine and collapse any runs of 3+ newlines down to 2 (one blank line max)
     const raw = `${imports}\n\n${testCode}`;
-    const code = raw.replace(/\n{3,}/g, '\n\n');
+    let code = raw.replace(/\n{3,}/g, '\n\n');
+
+    // Runtime data: replace __SUNGEN_TD_ markers with testData.get() calls
+    if (this.options.runtimeData) {
+      code = transformToRuntimeData(code);
+    }
 
     return {
       featureName: feature.name,
@@ -180,6 +213,7 @@ export class CodeGenerator {
   private countSteps(feature: ParsedFeature): number {
     let total = 0;
     for (const scenario of feature.scenarios) {
+      if (scenario.stepsName || scenario.hookType) continue;
       if (scenario.extendsName) {
         const base = this.stepsRegistry.get(scenario.extendsName);
         total += (base ? base.steps.length : 0) + scenario.steps.length;
@@ -206,17 +240,30 @@ export class CodeGenerator {
    * Ensure specs/base.ts exists in the output directory
    */
   ensureBaseFile(outputDir: string): void {
+    const templatesRoot = path.join(__dirname, '..', '..', '..', 'orchestrator', 'templates');
+
     const basePath = path.join(outputDir, 'base.ts');
-    if (fs.existsSync(basePath)) return;
+    if (!fs.existsSync(basePath)) {
+      const templatePath = path.join(templatesRoot, 'specs-base.ts');
+      if (fs.existsSync(templatePath)) {
+        const baseDir = path.dirname(basePath);
+        if (!fs.existsSync(baseDir)) {
+          fs.mkdirSync(baseDir, { recursive: true });
+        }
+        fs.copyFileSync(templatePath, basePath);
+        console.log('✓ Created: specs/base.ts');
+      }
+    }
 
-    const templatePath = path.join(__dirname, '..', '..', '..', 'orchestrator', 'templates', 'specs-base.ts');
-    if (fs.existsSync(templatePath)) {
-      const baseDir = path.dirname(basePath);
-      if (!fs.existsSync(baseDir)) {
-        fs.mkdirSync(baseDir, { recursive: true });
+    if (this.options.runtimeData) {
+      const testDataPath = path.join(outputDir, 'test-data.ts');
+      if (!fs.existsSync(testDataPath)) {
+        const templatePath = path.join(templatesRoot, 'specs-test-data.ts');
+        if (fs.existsSync(templatePath)) {
+          fs.copyFileSync(templatePath, testDataPath);
+          console.log('✓ Created: specs/test-data.ts');
+        }
       }
-      fs.copyFileSync(templatePath, basePath);
-      console.log('✓ Created: specs/base.ts');
     }
   }
 
@@ -233,12 +280,14 @@ export class CodeGenerator {
     
     // Derive screen name from source file path when not explicitly set
     // qa/screens/{screenName}/features/{featureName}.feature -> screenName
+    let effectiveScreenName = this.screenName;
     if (!this.screenName && feature.sourceFile) {
       const sourceDir = path.dirname(feature.sourceFile);
       const parts = sourceDir.split(path.sep);
       const screensIndex = parts.indexOf('screens');
       if (screensIndex >= 0 && screensIndex < parts.length - 2) {
-        this.stepMapper.setScreenContext(parts[screensIndex + 1]);
+        effectiveScreenName = parts[screensIndex + 1];
+        this.stepMapper.setScreenContext(effectiveScreenName);
       }
     }
 
@@ -261,13 +310,35 @@ export class CodeGenerator {
         this.stepsRegistry.set(scenario.stepsName, scenario);
       }
     }
-    
+
+    // Pre-pass: extract hook scenarios (@beforeAll, @afterEach, @afterAll)
+    const hookScenarios = new Map<string, ParsedScenario>();
+    for (const scenario of feature.scenarios) {
+      if (scenario.hookType) {
+        if (hookScenarios.has(scenario.hookType)) {
+          console.warn(`⚠ Duplicate @${scenario.hookType} hook — last definition wins`);
+        }
+        hookScenarios.set(scenario.hookType, scenario);
+      }
+    }
+
     // Generate background if exists
     let background: string | undefined;
     if (feature.background) {
       background = await this.generateBeforeEach(feature.background);
     }
 
+    // Generate hook blocks
+    const beforeAll = hookScenarios.has('beforeAll')
+      ? await this.generateHook(hookScenarios.get('beforeAll')!, 'beforeAll')
+      : undefined;
+    const afterEach = hookScenarios.has('afterEach')
+      ? await this.generateHook(hookScenarios.get('afterEach')!, 'afterEach')
+      : undefined;
+    const afterAll = hookScenarios.has('afterAll')
+      ? await this.generateHook(hookScenarios.get('afterAll')!, 'afterAll')
+      : undefined;
+
     // Generate all scenarios with feature tags for inheritance
     // Skip scenarios tagged with @manual
     // Track auth role per scenario for grouping
@@ -280,6 +351,11 @@ export class CodeGenerator {
         continue;
       }
 
+      // Skip hook scenarios — already generated as hook blocks above
+      if (scenario.hookType) {
+        continue;
+      }
+
       // Resolve auth tags for @extend scenarios (same logic as generateScenario)
       let authFeatureTags = feature.tags || [];
       if (scenario.extendsName) {
@@ -327,12 +403,24 @@ export class CodeGenerator {
       ? authGroups[0].authRole
       : undefined;
 
+    // Extract @cleanup:* tags for autoCleanup fixture config
+    const cleanupConfig = extractCleanupConfig(feature.tags || []);
+    const screenshotOnFailure = hasScreenshotOnFailure(feature.tags || []);
+
     // Use adapter to render the complete test file structure
     return this.adapter.renderTestFile({
       imports: '', // Not used in template as it's rendered separately
       featureName: feature.name,
       featureDescription: feature.description,
       background,
+      beforeAll,
+      afterEach,
+      afterAll,
+      cleanupConfig,
+      screenshotOnFailure,
+      runtimeData: this.options.runtimeData,
+      screenName: effectiveScreenName,
+      featureFileName: featureName,
       scenarios: needsGrouping ? [] : scenarios,
       authGroups: needsGrouping ? authGroups : undefined,
       singleAuthRole,
@@ -356,6 +444,27 @@ export class CodeGenerator {
     });
   }
 
+  private async generateHook(
+    scenario: ParsedScenario,
+    hookType: 'beforeAll' | 'afterEach' | 'afterAll'
+  ): Promise<string> {
+    const steps: Array<{ comment?: string; code: string }> = [];
+    for (const step of scenario.steps) {
+      const mapped = await Promise.resolve(this.stepMapper.mapStep(step));
+      steps.push({
+        comment: mapped.comment,
+        code: this.indentCode(mapped.code, 4),
+      });
+    }
+
+    const renderMap = {
+      beforeAll: () => this.adapter.renderBeforeAll({ steps }),
+      afterEach: () => this.adapter.renderAfterEach({ steps }),
+      afterAll: () => this.adapter.renderAfterAll({ steps }),
+    };
+    return renderMap[hookType]();
+  }
+
   private async generateScenario(
     scenario: ParsedScenario, 
     hasBackground: boolean,

package/src/generators/test-generator/step-mapper.ts

@@ -35,7 +35,7 @@ export class StepMapper {
   private inRowScope: boolean = false;
   private rowScopeTable: string = '';
 
-  constructor(options: { verbose?: boolean; baseURL?: string; featureName?: string; screenName?: string; featurePath?: string } = {}) {
+  constructor(options: { verbose?: boolean; baseURL?: string; featureName?: string; screenName?: string; featurePath?: string; runtimeData?: boolean } = {}) {
     this.verbose = options.verbose ?? false;
     this.baseURL = options.baseURL || null;  // null means path-only navigation
     this.featureName = options.featureName;
@@ -46,7 +46,7 @@ export class StepMapper {
     this.templateEngine = new TemplateEngine(playwrightTemplatesDir);
     this.patternRegistry = new PatternRegistry();
     this.selectorResolver = new SelectorResolver(undefined, options.screenName);
-    this.dataResolver = new DataResolver(undefined, options.screenName);
+    this.dataResolver = new DataResolver(undefined, options.screenName, options.runtimeData);
 
     if (this.verbose) {
       console.log(`  [StepMapper] ${this.patternRegistry.getPatternCount()} patterns loaded`);

package/src/generators/test-generator/template-engine.ts

@@ -229,8 +229,8 @@ export class TemplateEngine {
     this.baseContext = {};
   }
 
-  renderImports(): string {
-    return this.render('imports', {});
+  renderImports(options?: { runtimeData?: boolean }): string {
+    return this.render('imports', { runtimeData: options?.runtimeData });
   }
 
   renderTestFile(data: {
@@ -238,6 +238,14 @@ export class TemplateEngine {
     featureName: string;
     featureDescription?: string;
     background?: string;
+    beforeAll?: string;
+    afterEach?: string;
+    afterAll?: string;
+    cleanupConfig?: string;
+    screenshotOnFailure?: boolean;
+    runtimeData?: boolean;
+    screenName?: string;
+    featureFileName?: string;
     scenarios: string[];
     authGroups?: Array<{ authRole?: string; scenarios: string[] }>;
     singleAuthRole?: string;
@@ -251,6 +259,24 @@ export class TemplateEngine {
     return this.render('before-each', data);
   }
 
+  renderBeforeAll(data: {
+    steps: Array<{ comment?: string; code: string }>;
+  }): string {
+    return this.render('before-all', data);
+  }
+
+  renderAfterEach(data: {
+    steps: Array<{ comment?: string; code: string }>;
+  }): string {
+    return this.render('after-each', data);
+  }
+
+  renderAfterAll(data: {
+    steps: Array<{ comment?: string; code: string }>;
+  }): string {
+    return this.render('after-all', data);
+  }
+
   renderScenario(data: {
     scenarioName: string;
     steps: Array<{ comment?: string; code: string }>;

package/src/generators/test-generator/utils/data-resolver.ts

@@ -5,8 +5,11 @@ import { readYamlIfExists } from '../../../utils/yaml-io';
 
 /**
  * DataResolver - Resolves data references to actual values
- * at generation time (not runtime)
- * 
+ *
+ * Two modes:
+ * - Compile-time (default): resolves YAML values and bakes them into generated code
+ * - Runtime (runtimeMode=true): returns markers that post-processor converts to testData.get() calls
+ *
  * Supports override files with priority:
  * 1. .override.yaml (highest - user customizations)
  * 2. -override.yaml (legacy - backward compat)
@@ -16,10 +19,12 @@ export class DataResolver {
   private dataCache = new Map<string, any>();
   private testDataDir: string;
   private screenName?: string;
+  private runtimeMode: boolean;
 
-  constructor(testDataDir?: string, screenName?: string) {
+  constructor(testDataDir?: string, screenName?: string, runtimeMode: boolean = false) {
     this.testDataDir = testDataDir || path.join(process.cwd(), 'qa', 'test-data');
     this.screenName = screenName;
+    this.runtimeMode = runtimeMode;
   }
 
   /**
@@ -36,34 +41,18 @@ export class DataResolver {
    * @returns The resolved value
    */
   resolveData(dataRef: string, featureName?: string): string {
-    // Split into parts: email.valid -> [email, valid]
-    // Use only dot (.) as separator
-    const parts = dataRef.split('.');
-    
-    if (parts.length < 1) {
-      throw new Error(`Invalid data reference: ${dataRef}. Expected format: path.to.value`);
+    if (this.runtimeMode) {
+      this.validateDataRef(dataRef, featureName);
+      return DataResolver.encodeMarker(dataRef);
     }
 
-    // If featureName provided, use it as the file name
-    // Otherwise, use first part as filename (backward compatibility)
-    let fileName: string;
-    let valuePath: string[];
-    
-    if (featureName) {
-      fileName = featureName;
-      valuePath = parts;
-    } else {
-      if (parts.length < 2) {
-        throw new Error(`Invalid data reference: ${dataRef}. Expected format: file.path.to.value or provide featureName`);
-      }
-      fileName = parts[0];
-      valuePath = parts.slice(1);
-    }
+    return this.resolveValue(dataRef, featureName);
+  }
 
-    // Load data file
+  private resolveValue(dataRef: string, featureName?: string): string {
+    const { fileName, valuePath } = this.parseDataRef(dataRef, featureName);
     const data = this.loadDataFile(fileName);
 
-    // Navigate to the value
     let current = data;
     for (const key of valuePath) {
       if (current && typeof current === 'object' && key in current) {
@@ -75,7 +64,6 @@ export class DataResolver {
       }
     }
 
-    // Return as string
     if (typeof current === 'string') {
       return current;
     } else if (typeof current === 'number' || typeof current === 'boolean') {
@@ -87,6 +75,36 @@ export class DataResolver {
     }
   }
 
+  private validateDataRef(dataRef: string, featureName?: string): void {
+    // Same navigation as resolveValue — validates the key path exists at compile time
+    this.resolveValue(dataRef, featureName);
+  }
+
+  private parseDataRef(dataRef: string, featureName?: string): { fileName: string; valuePath: string[] } {
+    const parts = dataRef.split('.');
+
+    if (parts.length < 1) {
+      throw new Error(`Invalid data reference: ${dataRef}. Expected format: path.to.value`);
+    }
+
+    if (featureName) {
+      return { fileName: featureName, valuePath: parts };
+    }
+
+    if (parts.length < 2) {
+      throw new Error(`Invalid data reference: ${dataRef}. Expected format: file.path.to.value or provide featureName`);
+    }
+    return { fileName: parts[0], valuePath: parts.slice(1) };
+  }
+
+  static encodeMarker(ref: string): string {
+    return `__SUNGEN_TD_${ref.replace(/\./g, '_D_')}__`;
+  }
+
+  static decodeMarker(encoded: string): string {
+    return encoded.replace(/^__SUNGEN_TD_/, '').replace(/__$/, '').replace(/_D_/g, '.');
+  }
+
   /**
    * Load data file from disk (with caching)
    * Searches new screen-based directory structure only

package/src/generators/test-generator/utils/runtime-data-transformer.ts

@@ -0,0 +1,51 @@
+const MARKER_PATTERN = /__SUNGEN_TD_([A-Za-z0-9_]+)__/;
+
+/**
+ * Replace __SUNGEN_TD_ markers with testData.get() calls in generated code.
+ * Three passes: comments, string literals, then regex literals.
+ */
+export function transformToRuntimeData(code: string): string {
+  // Pass 0: Comments — replace markers in // comments with decoded key name
+  // Prevents Pass 2 from misinterpreting // comment markers as regex delimiters
+  code = code.replace(
+    /\/\/(.*)__SUNGEN_TD_([A-Za-z0-9_]+)__(.*)/g,
+    (_, before, enc, after) => `//${before}${decodeKey(enc)}${after}`
+  );
+
+  // Pass 1: String literal context — handles both whole-string and embedded markers
+  // 'marker'                    → testData.get('key')
+  // 'prefix__marker__suffix'    → `prefix${testData.get('key')}suffix`
+  code = code.replace(
+    /(['"])((?:(?!\1).)*?)__SUNGEN_TD_([A-Za-z0-9_]+)__((?:(?!\1).)*?)\1/g,
+    (_, _quote, prefix, enc, suffix) => {
+      const key = decodeKey(enc);
+      if (!prefix && !suffix) {
+        return `testData.get('${key}')`;
+      }
+      return `\`${prefix}\${testData.get('${key}')}${suffix}\``;
+    }
+  );
+
+  // Pass 2: Regex literal context — /prefix__marker__suffix/ → new RegExp(`...`)
+  // Only matches within a single line (no newlines in prefix/suffix)
+  code = code.replace(
+    /\/((?:[^/\\\n]|\\.)*?)__SUNGEN_TD_([A-Za-z0-9_]+)__((?:[^/\\\n]|\\.)*?)\/([gimsuy]*)/g,
+    (_, prefix, enc, suffix, flags) => {
+      const key = decodeKey(enc);
+      const ref = `testData.get('${key}')`;
+      const flagStr = flags ? `, '${flags}'` : '';
+      if (!prefix && !suffix) return `new RegExp(${ref}${flagStr})`;
+      return `new RegExp(\`${prefix}\${${ref}}${suffix}\`${flagStr})`;
+    }
+  );
+
+  return code;
+}
+
+export function hasRuntimeDataMarkers(code: string): boolean {
+  return MARKER_PATTERN.test(code);
+}
+
+function decodeKey(encoded: string): string {
+  return encoded.replace(/_D_/g, '.');
+}

package/src/generators/types.ts

@@ -170,6 +170,7 @@ export interface GenerateOptions {
   all?: boolean;                  // Generate all screens
   force?: boolean;                // Force re-generation
   skipCache?: boolean;            // Skip cache lookup
+  runtimeData?: boolean;          // Runtime data loading (default: true). False = compile-time hardcoding.
 }
 
 export interface ValidateOptions {

package/src/orchestrator/ai-rules-updater.ts

@@ -41,6 +41,7 @@ export const AI_RULES_FILE_MAPPING: [string, string][] = [
   ['claude-skill-capture-figma.md', '.claude/skills/sungen-capture-figma/SKILL.md'],
   ['claude-skill-capture-local.md', '.claude/skills/sungen-capture-local/SKILL.md'],
   ['claude-skill-capture-live.md', '.claude/skills/sungen-capture-live/SKILL.md'],
+  ['claude-skill-figma-source.md', '.claude/skills/sungen-figma-source/SKILL.md'],
 
   // Skills — GitHub Copilot
   ['github-skill-sungen-gherkin-syntax.md', '.github/skills/sungen-gherkin-syntax/SKILL.md'],
@@ -55,6 +56,7 @@ export const AI_RULES_FILE_MAPPING: [string, string][] = [
   ['github-skill-sungen-capture-figma.md', '.github/skills/sungen-capture-figma/SKILL.md'],
   ['github-skill-sungen-capture-local.md', '.github/skills/sungen-capture-local/SKILL.md'],
   ['github-skill-sungen-capture-live.md', '.github/skills/sungen-capture-live/SKILL.md'],
+  ['github-skill-sungen-figma-source.md', '.github/skills/sungen-figma-source/SKILL.md'],
 ];
 
 export class AIRulesUpdater {

package/src/orchestrator/figma/figma-scaffolder-helpers.ts

@@ -0,0 +1,126 @@
+/**
+ * Internal helpers for figma-scaffolder.ts.
+ * Extracted to keep the main orchestration file under 200 LOC.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import type { Ora } from 'ora';
+import { downloadToPath } from '../../tools/figma/figma-image-downloader';
+import * as FigmaCache from '../../tools/figma/figma-cache';
+
+// ---------------------------------------------------------------------------
+// Name utilities
+// ---------------------------------------------------------------------------
+
+/** Sanitize a Figma frame/variant name to a safe filename (lowercase, dashes). */
+export function sanitizeName(name: string): string {
+  return name
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+}
+
+// ---------------------------------------------------------------------------
+// Version / stub helpers
+// ---------------------------------------------------------------------------
+
+/** Read generator version from root package.json. Falls back to "sungen". */
+export function readGeneratorVersion(cwd: string): string {
+  try {
+    const pkgPath = path.join(cwd, 'package.json');
+    if (fs.existsSync(pkgPath)) {
+      const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8')) as { version?: string };
+      if (pkg.version) return `sungen v${pkg.version}`;
+    }
+  } catch {
+    // fall through
+  }
+  return 'sungen';
+}
+
+/** Minimal spec.md stub pointing users to spec_figma.md. */
+export function minimalSpecMd(screenName: string): string {
+  return `# ${screenName} Screen Specification
+
+<!-- This file is the human-authored source of truth. -->
+<!-- spec_figma.md contains auto-generated Figma data — copy useful sections here. -->
+
+## Overview
+- **URL Path:** /${screenName}
+- **Auth Required:** no
+- **Platform:** web
+
+## Sections
+
+<!-- Add sections, fields, validation rules, and business rules here. -->
+`;
+}
+
+// ---------------------------------------------------------------------------
+// Image download orchestration
+// ---------------------------------------------------------------------------
+
+export interface DownloadImagesOptions {
+  cwd: string;
+  fileKey: string;
+  versionId: string;
+  uiDir: string;
+  imageNodeIds: string[];
+  mainNodeId: string;
+  variantNames: string[];
+  /** Pre-warmed cache entries (nodeId → bytes). */
+  cachedImages: Map<string, Buffer>;
+  /** URL map from getImageUrls response (nodeId → signed URL). */
+  imageUrls: Record<string, string | null>;
+  frameBaseName: string;
+  scaleKind: `${number}x`;
+  spinner: Ora;
+}
+
+/**
+ * Download (or copy from cache) images for each node ID.
+ * Returns relative paths (e.g. "ui/login-frame.png") for each successfully written file.
+ */
+export async function downloadImages(opts: DownloadImagesOptions): Promise<string[]> {
+  const imagePaths: string[] = [];
+
+  for (let i = 0; i < opts.imageNodeIds.length; i++) {
+    const nodeId = opts.imageNodeIds[i];
+    const isMain = nodeId === opts.mainNodeId;
+    const nameSuffix = isMain
+      ? opts.frameBaseName
+      : sanitizeName(opts.variantNames[i - 1] ?? `variant-${i}`);
+    const destPath = path.join(opts.uiDir, `${nameSuffix}.png`);
+    const relPath = `ui/${nameSuffix}.png`;
+
+    // Cache hit path
+    if (opts.cachedImages.has(nodeId)) {
+      opts.spinner.start(`Writing cached image: ${nameSuffix}.png`);
+      fs.writeFileSync(destPath, opts.cachedImages.get(nodeId)!);
+      imagePaths.push(relPath);
+      opts.spinner.succeed(`  ui/${nameSuffix}.png (cached)`);
+      continue;
+    }
+
+    const url = opts.imageUrls[nodeId];
+    if (!url) {
+      opts.spinner.warn(`  No image URL for node ${nodeId} — skipping`);
+      continue;
+    }
+
+    opts.spinner.start(`Downloading ui/${nameSuffix}.png…`);
+    try {
+      await downloadToPath(url, destPath);
+      // Cache downloaded bytes for future runs
+      const bytes = fs.readFileSync(destPath);
+      FigmaCache.put(opts.cwd, opts.fileKey, opts.versionId, nodeId, opts.scaleKind, bytes);
+      imagePaths.push(relPath);
+      opts.spinner.succeed(`  ui/${nameSuffix}.png`);
+    } catch {
+      opts.spinner.warn(`  Failed to download ui/${nameSuffix}.png — skipping`);
+    }
+  }
+
+  return imagePaths;
+}

package/src/orchestrator/figma/figma-scaffolder-types.ts

@@ -0,0 +1,26 @@
+/**
+ * Shared input/output types for FigmaScaffolder.
+ * Kept separate to avoid growing figma-client-types.ts beyond its scope.
+ */
+
+export interface FigmaScaffolderOptions {
+  /** Screen name (e.g. "login", "dashboard"). */
+  screenName: string;
+  /** Full Figma share URL. */
+  figmaUrl: string;
+  /** Absolute or cwd-relative working directory. Default: process.cwd(). */
+  cwd?: string;
+  /** When true, bypass cache and re-fetch from Figma API. Default: false. */
+  refresh?: boolean;
+  /** Render scale for PNG export. Default: 2. */
+  scale?: number;
+}
+
+export interface FigmaScaffolderResult {
+  /** Absolute path to the written spec_figma.md. */
+  specFigmaPath: string;
+  /** Absolute paths to downloaded PNG files. */
+  imagePaths: string[];
+  /** True when spec.md was newly created (was not already present). */
+  specMdCreated: boolean;
+}