design-clone 1.2.0 → 2.1.0

package/src/core/dimension-output.js

@@ -89,7 +89,18 @@ export function sanitizeViewportData(data, vpName) {
 }
 
 /**
- * Build cross-viewport summary for AI consumption
+ * Build cross-viewport summary for AI consumption.
+ * Includes section-aware typography and container data.
+ *
+ * @param {Object} viewports - Viewport data keyed by name (desktop, tablet, mobile)
+ * @returns {Object} Summary with:
+ *   - maxContainerWidth: Largest container width across all viewports
+ *   - commonGap: Average gap from card patterns
+ *   - breakpoints: Viewport width breakpoints
+ *   - typography: Flat h1/h2/h3/body sizes by viewport (backward compat)
+ *   - typographyBySection: Typography grouped by section context (hero h1 != content h1)
+ *   - cardPatterns: Card group statistics
+ *   - sections: Section detection summary (found flag + width/containerWidth)
  */
 export function buildCrossViewportSummary(viewports) {
   const summary = {
@@ -100,31 +111,83 @@ export function buildCrossViewportSummary(viewports) {
       tablet: VIEWPORTS.tablet.width,
       mobile: VIEWPORTS.mobile.width
     },
+    // Flat typography for backward compatibility
     typography: { h1: {}, h2: {}, h3: {}, body: {} },
-    cardPatterns: { totalGroups: 0, avgCardSize: null }
+    // NEW: Typography by section context
+    typographyBySection: {
+      hero: {},
+      content: {},
+      header: {},
+      footer: {},
+      sidebar: {}
+    },
+    cardPatterns: { totalGroups: 0, avgCardSize: null },
+    // NEW: Section summary
+    sections: {
+      hero: { found: false, containerWidth: null },
+      content: { found: false, containerWidth: null },
+      header: { found: false, containerWidth: null },
+      footer: { found: false, containerWidth: null },
+      sidebar: { found: false, width: null }
+    }
   };
 
   for (const [vpName, vpData] of Object.entries(viewports)) {
     if (!vpData) continue;
 
+    // Container section mapping
     if (vpData.containers) {
       for (const container of vpData.containers) {
         if (container.width > summary.maxContainerWidth) {
           summary.maxContainerWidth = container.width;
         }
+        // Track section widths
+        const section = container.section || 'content';
+        if (summary.sections[section]) {
+          summary.sections[section].found = true;
+          // Sidebar uses 'width' field, others use 'containerWidth'
+          if (section === 'sidebar') {
+            if (!summary.sections[section].width ||
+                container.width > summary.sections[section].width) {
+              summary.sections[section].width = container.width;
+            }
+          } else {
+            if (!summary.sections[section].containerWidth ||
+                container.width > summary.sections[section].containerWidth) {
+              summary.sections[section].containerWidth = container.width;
+            }
+          }
+        }
       }
     }
 
+    // Typography by section
     if (vpData.typography) {
       for (const typo of vpData.typography) {
         const tag = typo.selector?.toLowerCase();
-        if (tag === 'h1') summary.typography.h1[vpName] = typo.fontSize;
-        if (tag === 'h2') summary.typography.h2[vpName] = typo.fontSize;
-        if (tag === 'h3') summary.typography.h3[vpName] = typo.fontSize;
-        if (tag === 'p') summary.typography.body[vpName] = typo.fontSize;
+        const section = typo.section || 'content';
+
+        // Flat typography (backward compat) - take first found
+        if (tag === 'h1' && !summary.typography.h1[vpName]) summary.typography.h1[vpName] = typo.fontSize;
+        if (tag === 'h2' && !summary.typography.h2[vpName]) summary.typography.h2[vpName] = typo.fontSize;
+        if (tag === 'h3' && !summary.typography.h3[vpName]) summary.typography.h3[vpName] = typo.fontSize;
+        if (tag === 'p' && !summary.typography.body[vpName]) summary.typography.body[vpName] = typo.fontSize;
+
+        // Typography by section
+        if (!summary.typographyBySection[section]) {
+          summary.typographyBySection[section] = {};
+        }
+        if (!summary.typographyBySection[section][tag]) {
+          summary.typographyBySection[section][tag] = {};
+        }
+        // Take first found per section/tag/viewport
+        if (!summary.typographyBySection[section][tag][vpName]) {
+          summary.typographyBySection[section][tag][vpName] = typo.fontSize;
+        }
       }
     }
 
+    // Card patterns (unchanged)
     if (vpData.cards && vpData.cards.length > 0) {
       summary.cardPatterns.totalGroups += vpData.cards.length;
       if (vpName === 'desktop' && vpData.cards[0]?.avgDimensions) {
@@ -143,6 +206,7 @@ export function buildCrossViewportSummary(viewports) {
 
 /**
  * Generate AI-friendly summary (compact, <5KB)
+ * Includes section-aware typography for accurate reconstruction
  * @param {Object} fullOutput - Full component-dimensions.json
  * @returns {Object} Compact summary for AI prompts
  */
@@ -173,6 +237,29 @@ export function generateAISummary(fullOutput) {
     };
   }
 
+  /**
+   * Convert typographyBySection to AI-friendly format with px units
+   */
+  function inferTypographyBySection(typographyBySection) {
+    const result = {};
+    for (const [section, tags] of Object.entries(typographyBySection || {})) {
+      if (!tags || Object.keys(tags).length === 0) continue;
+      result[section] = {};
+      for (const [tag, sizes] of Object.entries(tags)) {
+        // Use desktop first, then tablet, then mobile
+        const size = sizes.desktop || sizes.tablet || sizes.mobile || 0;
+        if (size > 0) {
+          result[section][tag] = size + "px";
+        }
+      }
+      // Remove empty sections
+      if (Object.keys(result[section]).length === 0) {
+        delete result[section];
+      }
+    }
+    return result;
+  }
+
   return {
     _comment: "USE THESE EXACT VALUES - DO NOT ESTIMATE",
     EXACT_DIMENSIONS: {
@@ -187,6 +274,16 @@ export function generateAISummary(fullOutput) {
       h3: (summary.typography.h3.desktop || 24) + "px",
       body: (summary.typography.body.desktop || 16) + "px"
     },
+    // NEW: Section-aware typography (hero h1 != content h1)
+    TYPOGRAPHY_BY_SECTION: inferTypographyBySection(summary.typographyBySection),
+    // NEW: Section info
+    SECTIONS: {
+      hero: summary.sections?.hero || { found: false },
+      content: summary.sections?.content || { found: false },
+      header: summary.sections?.header || { found: false },
+      footer: summary.sections?.footer || { found: false },
+      sidebar: summary.sections?.sidebar || { found: false }
+    },
     RESPONSIVE: {
       desktop_breakpoint: summary.breakpoints.desktop + "px",
       tablet_breakpoint: summary.breakpoints.tablet + "px",

package/src/core/discover-pages.js

@@ -4,6 +4,11 @@
  * Extracts navigation links from a website to discover cloneable pages.
  * Handles SPA hydration, filters external links, and normalizes URLs.
  *
+ * Enhanced with SPA/Framework support (v1.3):
+ * - Framework detection (Next.js, Nuxt, Vue, React, Angular, Svelte, Astro)
+ * - Framework-specific route discovery
+ * - App state capture (optional)
+ *
  * Usage:
  *   import { discoverPages } from './discover-pages.js';
  *   const result = await discoverPages('https://example.com', { maxPages: 10 });
@@ -13,6 +18,11 @@ import { getBrowser, getPage, disconnectBrowser } from '../utils/browser.js';
 import { waitForDomStable, waitForPageReady } from './page-readiness.js';
 import { dismissCookieBanner } from './cookie-handler.js';
 
+// SPA/Framework support imports
+import { detectFramework, formatDetectionResult } from './framework-detector.js';
+import { discoverRoutes as discoverFrameworkRoutes } from '../route-discoverers/index.js';
+import { captureAppState, formatStateSnapshot } from './app-state-snapshot.js';
+
 // Navigation selectors in priority order
 const NAV_SELECTORS = [
   'header nav a',
@@ -41,14 +51,47 @@ const EXCLUDE_PATTERNS = [
   /tiktok\.com/i
 ];
 
+// Valid framework names for validation
+const VALID_FRAMEWORKS = ['next', 'nuxt', 'vue', 'react', 'angular', 'svelte', 'astro'];
+
 // Default options
 const DEFAULT_OPTIONS = {
   maxPages: 10,
   selectors: null,  // Use default NAV_SELECTORS if null
   includeSubdomains: false,
-  timeout: 30000
+  timeout: 30000,
+  // SPA/Framework options (v1.3)
+  spaMode: true,         // Enable SPA detection and route discovery
+  framework: null,       // Force specific framework (skip detection)
+  noSpaDetect: false,    // Disable SPA/framework detection entirely
+  captureState: false    // Capture app state (Redux/Vuex/Pinia/Zustand)
 };
 
+/**
+ * Log warning message (only in TTY mode)
+ * @param {string} message - Warning message
+ */
+function logWarning(message) {
+  if (process.stderr.isTTY) {
+    console.error(`[discover-pages] WARN: ${message}`);
+  }
+}
+
+/**
+ * Validate and normalize framework option
+ * @param {string|null} framework - Framework name to validate
+ * @returns {string|null} Validated framework name or null
+ */
+function validateFramework(framework) {
+  if (!framework) return null;
+  const normalized = String(framework).toLowerCase().trim();
+  if (VALID_FRAMEWORKS.includes(normalized)) {
+    return normalized;
+  }
+  logWarning(`Invalid framework "${framework}". Valid options: ${VALID_FRAMEWORKS.join(', ')}`);
+  return null;
+}
+
 /**
  * Normalize URL for comparison and deduplication
  * @param {string} baseUrl - Base URL for resolving relative paths
@@ -140,10 +183,102 @@ function shouldExclude(href) {
   return EXCLUDE_PATTERNS.some(pattern => pattern.test(href));
 }
 
+/**
+ * Normalize a path (remove trailing slash except for root)
+ * @param {string} path - Path to normalize
+ * @returns {string} Normalized path
+ */
+function normalizePath(path) {
+  if (!path || typeof path !== 'string') return '/';
+  return path.endsWith('/') && path !== '/' ? path.slice(0, -1) : path;
+}
+
+/**
+ * Merge framework-discovered routes with link-scraped pages
+ * Prioritizes framework routes (higher quality), fills gaps with link-scraped
+ *
+ * @param {Array|null} frameworkRoutes - Routes from framework discoverer
+ * @param {Array|null} linkScrapedPages - Pages from link scraping
+ * @param {string} baseDomain - Base domain for URL normalization
+ * @param {string} baseUrl - Base URL for resolving paths
+ * @returns {Array} Merged and deduplicated pages
+ *
+ * @example
+ * const merged = mergeRoutes(
+ *   [{ path: '/about', name: 'About' }],
+ *   [{ path: '/contact', name: 'Contact' }],
+ *   'example.com',
+ *   'https://example.com'
+ * );
+ */
+function mergeRoutes(frameworkRoutes, linkScrapedPages, baseDomain, baseUrl) {
+  // Input validation
+  if (!baseDomain || typeof baseDomain !== 'string') {
+    logWarning('mergeRoutes: Invalid baseDomain');
+    baseDomain = '';
+  }
+  if (!baseUrl || typeof baseUrl !== 'string') {
+    logWarning('mergeRoutes: Invalid baseUrl');
+    baseUrl = '';
+  }
+
+  const seenPaths = new Set();
+  const merged = [];
+
+  // Add framework routes first (higher quality, more accurate)
+  if (Array.isArray(frameworkRoutes)) {
+    for (const route of frameworkRoutes) {
+      if (!route || typeof route !== 'object') continue;
+
+      const normalizedPath = normalizePath(route.path || '/');
+      if (seenPaths.has(normalizedPath)) continue;
+      seenPaths.add(normalizedPath);
+
+      const url = normalizeUrl(baseUrl, normalizedPath) || route.url || '';
+
+      merged.push({
+        path: normalizedPath,
+        name: route.name || extractPageName('', normalizedPath),
+        url,
+        source: route.source || 'framework',
+        dynamic: Boolean(route.dynamic)
+      });
+    }
+  }
+
+  // Add link-scraped pages (fill gaps)
+  if (Array.isArray(linkScrapedPages)) {
+    for (const page of linkScrapedPages) {
+      if (!page || typeof page !== 'object') continue;
+
+      const normalizedPath = normalizePath(page.path || '/');
+      if (seenPaths.has(normalizedPath)) continue;
+      seenPaths.add(normalizedPath);
+
+      merged.push({
+        path: normalizedPath,
+        name: page.name || extractPageName('', normalizedPath),
+        url: page.url || normalizeUrl(baseUrl, normalizedPath) || '',
+        source: 'link-scrape',
+        dynamic: false
+      });
+    }
+  }
+
+  return merged;
+}
+
 /**
  * Discover pages from a website by extracting navigation links
+ * Enhanced with SPA/Framework support (v1.3)
+ *
  * @param {string} baseUrl - Starting URL to discover from
  * @param {Object} options - Discovery options
+ * @param {number} [options.maxPages=10] - Maximum pages to discover
+ * @param {boolean} [options.spaMode=true] - Enable SPA detection
+ * @param {string} [options.framework] - Force specific framework
+ * @param {boolean} [options.noSpaDetect=false] - Disable SPA detection
+ * @param {boolean} [options.captureState=false] - Capture app state
  * @returns {Promise<Object>} Discovery result
  */
 export async function discoverPages(baseUrl, options = {}) {
@@ -164,7 +299,7 @@ export async function discoverPages(baseUrl, options = {}) {
 
     // Navigate to page
     await page.goto(baseUrl, {
-      waitUntil: ['load', 'networkidle0'],
+      waitUntil: 'networkidle',
       timeout: opts.timeout
     });
 
@@ -182,7 +317,62 @@ export async function discoverPages(baseUrl, options = {}) {
     // Wait a bit more for any dynamic content
     await new Promise(r => setTimeout(r, 1000));
 
-    // Extract links using selectors
+    // =========================================
+    // SPA/Framework Detection (v1.3)
+    // =========================================
+    let frameworkInfo = null;
+    let frameworkRoutes = [];
+    let stateSnapshot = null;
+
+    if (!opts.noSpaDetect) {
+      // Framework detection
+      if (opts.framework) {
+        // User forced specific framework - validate it
+        const validatedFramework = validateFramework(opts.framework);
+        if (validatedFramework) {
+          frameworkInfo = {
+            framework: validatedFramework,
+            version: null,
+            routingType: 'spa',
+            confidence: 'forced',
+            signals: ['user-specified']
+          };
+        }
+      } else {
+        // Auto-detect framework
+        try {
+          frameworkInfo = await detectFramework(page);
+        } catch (e) {
+          logWarning(`Framework detection failed: ${e.message}`);
+          frameworkInfo = null;
+        }
+      }
+
+      // Framework-specific route discovery
+      if (frameworkInfo?.framework && opts.spaMode) {
+        try {
+          const discoveryResult = await discoverFrameworkRoutes(page, baseUrl, frameworkInfo);
+          frameworkRoutes = discoveryResult.routes || [];
+        } catch (e) {
+          logWarning(`Route discovery failed for ${frameworkInfo.framework}: ${e.message}`);
+          frameworkRoutes = [];
+        }
+      }
+
+      // Capture app state (optional)
+      if (opts.captureState && frameworkInfo) {
+        try {
+          stateSnapshot = await captureAppState(page, frameworkInfo);
+        } catch (e) {
+          logWarning(`State capture failed: ${e.message}`);
+          stateSnapshot = null;
+        }
+      }
+    }
+
+    // =========================================
+    // Traditional Link Scraping (existing logic)
+    // =========================================
     const selectors = opts.selectors || NAV_SELECTORS;
     const selectorString = selectors.join(', ');
 
@@ -196,13 +386,13 @@ export async function discoverPages(baseUrl, options = {}) {
 
     // Process and filter links
     const seenUrls = new Set();
-    const pages = [];
+    const linkScrapedPages = [];
 
     // Always include homepage first
     const homeUrl = normalizeUrl(baseUrl, '/');
     if (homeUrl) {
       seenUrls.add(homeUrl);
-      pages.push({
+      linkScrapedPages.push({
         path: '/',
         name: 'Home',
         url: homeUrl
@@ -232,14 +422,31 @@ export async function discoverPages(baseUrl, options = {}) {
 
       // Add to results
       seenUrls.add(normalized);
-      pages.push({
+      linkScrapedPages.push({
         path,
         name: extractPageName(link.text, path),
         url: normalized
       });
 
       // Check max pages limit
-      if (pages.length >= opts.maxPages) break;
+      if (linkScrapedPages.length >= opts.maxPages) break;
+    }
+
+    // =========================================
+    // Merge Routes (v1.3)
+    // =========================================
+    let pages;
+    if (frameworkRoutes.length > 0) {
+      // Merge framework routes with link-scraped pages
+      pages = mergeRoutes(frameworkRoutes, linkScrapedPages, baseDomain, baseUrl);
+    } else {
+      // No framework routes, use link-scraped pages only
+      pages = linkScrapedPages.map(p => ({ ...p, source: 'link-scrape', dynamic: false }));
+    }
+
+    // Apply max pages limit to merged results
+    if (pages.length > opts.maxPages) {
+      pages = pages.slice(0, opts.maxPages);
     }
 
     // Sort by path depth (shallow first)
@@ -257,25 +464,47 @@ export async function discoverPages(baseUrl, options = {}) {
       success: true,
       baseUrl: baseUrlObj.origin,
       baseDomain,
+      // SPA/Framework data (v1.3)
+      framework: frameworkInfo,
+      stateSnapshot: stateSnapshot,
+      // Page discovery results
       pages,
       stats: {
         totalLinksFound: rawLinks.length,
+        frameworkRoutesFound: frameworkRoutes.length,
         pagesDiscovered: pages.length,
         durationMs: duration
       }
     };
   } catch (error) {
+    // Normalize baseUrl in error case for consistency
+    let normalizedBaseUrl = baseUrl;
+    let errorBaseDomain = '';
+    try {
+      const urlObj = new URL(baseUrl);
+      normalizedBaseUrl = urlObj.origin;
+      errorBaseDomain = urlObj.hostname;
+    } catch {
+      // Keep original baseUrl if parsing fails
+    }
+
     return {
       success: false,
-      baseUrl,
+      baseUrl: normalizedBaseUrl,
+      baseDomain: errorBaseDomain,
+      framework: null,
+      stateSnapshot: null,
       pages: [{
         path: '/',
         name: 'Home',
-        url: normalizeUrl(baseUrl, '/') || baseUrl
+        url: normalizeUrl(baseUrl, '/') || baseUrl,
+        source: 'fallback',
+        dynamic: false
       }],
       error: error.message,
       stats: {
         totalLinksFound: 0,
+        frameworkRoutesFound: 0,
         pagesDiscovered: 1,
         durationMs: Date.now() - startTime
       }
@@ -287,11 +516,10 @@ export async function discoverPages(baseUrl, options = {}) {
   }
 }
 
-// CLI support
-const isMainModule = process.argv[1] && (
-  process.argv[1].endsWith('discover-pages.js') ||
-  process.argv[1].includes('discover-pages')
-);
+// CLI support - use exact file match to avoid triggering when imported
+import { fileURLToPath } from 'url';
+const __filename = fileURLToPath(import.meta.url);
+const isMainModule = process.argv[1] === __filename;
 
 if (isMainModule) {
   const url = process.argv[2];