@veyralabs/webcloner 0.1.0

package/references/component-detection.md

@@ -0,0 +1,209 @@
+# Component Detection — WebCloner Reference
+
+Algorithm for detecting component boundaries from `docs/site-manifest.json` → `sections`.
+
+---
+
+## Core Rule
+
+**One component = one repeating unit OR one structurally isolated block.**
+
+Don't split by DOM depth. Split by visual/functional independence.
+
+---
+
+## Detection Algorithm
+
+### Step 1 — Map top-level sections
+
+Start from `manifest.sections`. Each entry in the array is a candidate component boundary.
+
+```
+For each section in manifest.sections:
+  - tag is <header> → HeaderNav component
+  - tag is <footer> → Footer component
+  - tag is <main> → recurse into children
+  - tag is <section> or <article> → candidate section component
+```
+
+### Step 2 — Detect repeating patterns
+
+Within a section's `children`, look for repeating structure:
+
+```
+If section.children has N items where N >= 2:
+  AND all items share the same tag
+  AND all items have similar class patterns
+  → This is a list/grid component with repeated cards
+  → One parent component + one card sub-component
+```
+
+**Signal:** Items with identical class prefixes at depth 1:
+- `feature-card`, `feature-card`, `feature-card` → `FeatureCard` component
+- `team-member`, `team-member` → `TeamMember` component
+- `pricing-plan`, `pricing-plan` → `PricingCard` component
+
+### Step 3 — Detect functional groups
+
+Look for elements that only appear together and serve one function:
+
+```
+headline + subheadline + CTA buttons
+→ NOT 3 components. ONE hero content block.
+
+tab-nav + tab-panels
+→ NOT separate. ONE tabs component with internal state.
+
+form label + input + error message + submit
+→ ONE form component.
+```
+
+**Rule:** If removing one element makes the others meaningless → they're one component.
+
+### Step 4 — Detect overlay components
+
+Elements positioned absolutely or with high z-index are separate components:
+- `position: fixed` + `z-index > 10` → overlay/modal
+- `position: sticky` → sticky bar (separate from section it's in)
+- `overflow: hidden` on parent + transformed child → carousel/slider
+
+---
+
+## Component Boundary Signals
+
+| Signal | Component type |
+|--------|---------------|
+| `<header>` tag | HeaderNav |
+| `<footer>` tag | Footer |
+| `<nav>` tag | Navigation (may be inside HeaderNav) |
+| Full-width bg change | New section boundary |
+| `position: fixed`, high `z-index` | Overlay / Modal |
+| `position: sticky` | Sticky bar / floating CTA |
+| N identical sibling structures | List + Card components |
+| Form elements grouped | Form component |
+| `overflow: hidden` + transform | Carousel / Slider |
+| `[data-modal]`, `[role="dialog"]` | Modal component |
+| `[role="tablist"]` + `[role="tab"]` | Tabs component |
+
+---
+
+## Common Sections → Component Names
+
+```
+hero               → Hero.tsx
+features           → Features.tsx (+ FeatureCard.tsx if cards)
+pricing            → Pricing.tsx (+ PricingCard.tsx)
+testimonials       → Testimonials.tsx (+ TestimonialCard.tsx)
+team               → Team.tsx (+ TeamMember.tsx)
+faq                → FAQ.tsx (+ FAQItem.tsx)
+cta-section        → CTASection.tsx
+logos / trusted-by → LogoStrip.tsx
+stats              → Stats.tsx (+ StatItem.tsx)
+blog-preview       → BlogPreview.tsx (+ BlogCard.tsx)
+contact-form       → ContactForm.tsx
+newsletter         → NewsletterSignup.tsx
+header / nav       → HeaderNav.tsx
+footer             → Footer.tsx
+```
+
+---
+
+## Nesting Decision
+
+**Flatten aggressively.** The goal is readable components, not a perfect DOM mirror.
+
+```
+BAD — too granular:
+  <Section>
+    <SectionInner>
+      <SectionContent>
+        <SectionHeadline />
+```
+
+```
+GOOD — right level:
+  <Features>
+    <h2>Headline</h2>
+    {features.map(f => <FeatureCard key={f.id} {...f} />)}
+```
+
+**Rule:** Create a sub-component only if:
+1. It repeats (N >= 2 instances), OR
+2. It has its own behavior state, OR
+3. It's independently reusable across the page
+
+---
+
+## Props Extraction
+
+For each component, identify what varies vs what's fixed:
+
+**Fixed** (hardcode in component):
+- Layout structure
+- CSS classes / styles
+- Animation parameters
+
+**Variable** (extract as props):
+- Text content
+- Images/icons
+- URLs/hrefs
+- Counts/numbers
+- Boolean toggles
+
+Example for FeatureCard:
+```typescript
+interface FeatureCardProps {
+  icon: string;        // path to public/images/icon-*.svg
+  title: string;
+  description: string;
+  href?: string;
+}
+```
+
+---
+
+## Complexity Score
+
+Rate each component before dispatching builder agents:
+
+| Score | Criteria | Estimated build time |
+|-------|----------|---------------------|
+| 1 — Simple | Static, no behavior, <= 3 elements | 10-20 min |
+| 2 — Medium | Hover states OR responsive reflow | 20-40 min |
+| 3 — Complex | Click behavior + multiple states | 40-90 min |
+| 4 — Hard | Scroll animation + GSAP/Framer | 90-180 min |
+| 5 — Very hard | Multiple behaviors + complex responsive | 3+ hours |
+
+Build order: simple first (1-2), then medium (3), then complex (4-5).
+Complex components should get extra spec detail before dispatch.
+
+---
+
+## Red Flags — Components to Watch
+
+**Tabs with scroll-driven content:**
+Some designs show tabs that switch based on scroll position. Confirm by checking:
+```javascript
+// In browser console
+ScrollTrigger.getAll().forEach(st => console.log(st.trigger, st.vars))
+```
+If trigger is the tab content area → scroll-driven.
+If not → click-driven. Decision critical before building.
+
+**Carousels with touch:**
+Mobile swipe carousels need extra handling. Check:
+```javascript
+document.querySelectorAll('[class*="swiper"], [class*="splide"], [class*="glide"]')
+```
+If found → use the same library rather than rebuilding from scratch.
+
+**Sticky + scroll behavior:**
+Components with both `position: sticky` AND scroll-triggered style changes are two behaviors on one element.
+Document both separately in the behavior spec.
+
+**Lazy-loaded sections:**
+Some sections only render after scroll. Scrapling's scroll-and-wait handles this, but verify:
+```javascript
+manifest.sections.length  // should match visible section count on page
+```
+If low count → re-run `extract.py` with longer scroll delay.

package/references/stack-presets.md

@@ -0,0 +1,328 @@
+# Stack Presets — WebCloner Reference
+
+Output configs when the clone target is NOT Next.js.
+Default stack is Next.js 15 + TypeScript + Tailwind v4 + shadcn.
+Use these presets when the user requests a different framework.
+
+---
+
+## When to Use Alternate Stacks
+
+| Use case | Recommended stack |
+|----------|------------------|
+| Default / most cases | Next.js 15 |
+| Static site, no JS needed | Astro |
+| Vue ecosystem / Nuxt site clone | Nuxt 3 |
+| Svelte preference | SvelteKit |
+| Shopify storefront | Hydrogen (Remix-based) |
+| Existing React project | Vite + React |
+
+---
+
+## Astro
+
+**Best for:** Static marketing sites, portfolios, blogs. Zero JS by default.
+
+### Setup
+
+```bash
+npm create astro@latest clone -- --template minimal --typescript strict --install --no-git
+cd clone
+npx astro add tailwind
+npx astro add react  # only if interactive components needed
+```
+
+### File structure
+
+```
+src/
+  layouts/
+    Layout.astro       ← base layout (fonts, globals)
+  components/
+    Hero.astro         ← static sections as .astro
+    Features.astro
+    FeatureCard.astro
+    Header.astro
+    Footer.astro
+    Tabs.tsx           ← interactive components as .tsx (React island)
+  pages/
+    index.astro        ← assemble all sections
+public/
+  images/
+  fonts/
+```
+
+### Component template
+
+```astro
+---
+// Hero.astro
+interface Props {
+  headline: string;
+  subheadline: string;
+  ctaText: string;
+  ctaHref: string;
+}
+const { headline, subheadline, ctaText, ctaHref } = Astro.props;
+---
+
+<section class="hero">
+  <h1>{headline}</h1>
+  <p>{subheadline}</p>
+  <a href={ctaHref}>{ctaText}</a>
+</section>
+
+<style>
+  /* scoped styles */
+</style>
+```
+
+### Interactive islands
+
+Components that need JS (tabs, carousels, modals) use React with `client:load`:
+
+```astro
+---
+import Tabs from '../components/Tabs.tsx';
+---
+<Tabs client:load items={tabData} />
+```
+
+### Animation libraries
+
+- Lenis: use `client:only="react"` wrapper
+- GSAP: inline `<script>` tag in the Astro component
+- AOS: add `data-aos` attributes, init in `<script>` in Layout.astro
+
+### Build + preview
+
+```bash
+npm run build
+npm run preview
+```
+
+---
+
+## Nuxt 3
+
+**Best for:** Cloning Vue/Nuxt sites, SSR marketing sites.
+
+### Setup
+
+```bash
+npx nuxi@latest init clone
+cd clone
+npm install
+npx nuxi@latest module add tailwindcss
+```
+
+### File structure
+
+```
+components/
+  sections/
+    Hero.vue
+    Features.vue
+    FeatureCard.vue
+  layout/
+    Header.vue
+    Footer.vue
+pages/
+  index.vue          ← assemble sections
+app.vue              ← root (fonts, global providers)
+assets/
+  css/
+    main.css         ← globals, tokens
+public/
+  images/
+  fonts/
+```
+
+### Component template
+
+```vue
+<!-- components/sections/Hero.vue -->
+<script setup lang="ts">
+defineProps<{
+  headline: string
+  subheadline: string
+  ctaText: string
+  ctaHref: string
+}>()
+</script>
+
+<template>
+  <section class="hero">
+    <h1>{{ headline }}</h1>
+    <p>{{ subheadline }}</p>
+    <a :href="ctaHref">{{ ctaText }}</a>
+  </section>
+</template>
+```
+
+### Page assembly
+
+```vue
+<!-- pages/index.vue -->
+<template>
+  <main>
+    <Hero v-bind="heroData" />
+    <Features :items="features" />
+    <Footer />
+  </main>
+</template>
+```
+
+### Animation libraries
+
+- Lenis: create `plugins/lenis.client.ts`
+- GSAP: `npm install gsap`, use in `onMounted` hook
+- Framer Motion: NOT available for Vue — use Motion One (`npm install motion`) instead
+
+### Build
+
+```bash
+npm run build
+npm run preview
+```
+
+---
+
+## SvelteKit
+
+**Best for:** Performance-sensitive sites, minimal bundle preference.
+
+### Setup
+
+```bash
+npm create svelte@latest clone
+# Choose: skeleton, TypeScript, ESLint, Prettier
+cd clone
+npm install
+npx svelte-add@latest tailwindcss
+```
+
+### File structure
+
+```
+src/
+  lib/
+    components/
+      sections/
+        Hero.svelte
+        Features.svelte
+        FeatureCard.svelte
+      layout/
+        Header.svelte
+        Footer.svelte
+  routes/
+    +layout.svelte    ← root layout (fonts, providers)
+    +page.svelte      ← assemble sections
+static/
+  images/
+  fonts/
+```
+
+### Component template
+
+```svelte
+<!-- src/lib/components/sections/Hero.svelte -->
+<script lang="ts">
+  export let headline: string;
+  export let subheadline: string;
+  export let ctaText: string;
+  export let ctaHref: string;
+</script>
+
+<section class="hero">
+  <h1>{headline}</h1>
+  <p>{subheadline}</p>
+  <a href={ctaHref}>{ctaText}</a>
+</section>
+```
+
+### Animation
+
+- Svelte has built-in `transition:` and `animate:` directives — use for simple animations
+- GSAP: works normally in `onMount`
+- Lenis: instantiate in `+layout.svelte` `onMount`
+
+### Build
+
+```bash
+npm run build
+npm run preview
+```
+
+---
+
+## Vite + React (no Next.js)
+
+**Best for:** Adding to existing React project, no SSR needed.
+
+### Setup
+
+```bash
+npm create vite@latest clone -- --template react-ts
+cd clone
+npm install
+npm install -D tailwindcss postcss autoprefixer
+npx tailwindcss init -p
+```
+
+### Key differences from Next.js
+
+| Next.js | Vite + React |
+|---------|-------------|
+| `next/image` | `<img>` with manual width/height |
+| `app/page.tsx` | `src/App.tsx` |
+| `app/layout.tsx` | `src/main.tsx` (providers here) |
+| `public/` | `public/` (same) |
+| Server components | Client only — everything is `'use client'` |
+
+### No file-based routing
+
+Single page → `src/App.tsx` assembles sections directly.
+Multi-page → add `react-router-dom`.
+
+---
+
+## Shopify Hydrogen
+
+**Best for:** Ecommerce storefronts (product pages, collections, cart).
+
+### Setup
+
+```bash
+npm create @shopify/hydrogen@latest clone
+# Choose: hello-world template, TypeScript
+```
+
+### Key concepts
+
+- Hydrogen is Remix-based — routes in `app/routes/`
+- Product data from Storefront API (GraphQL)
+- Use `<Image>` from `@shopify/hydrogen` for optimized images
+- Cart via `useCart()` hook
+
+### Scope warning
+
+Hydrogen is complex. WebCloner for Shopify = **visual layer only**.
+Use clone for: storefront layout, product card design, typography, colors.
+Do NOT clone: checkout flow, payment processing, account pages.
+
+---
+
+## Switching Stacks Mid-Project
+
+If user requests a stack change after spec files are written:
+1. Specs are stack-agnostic — reuse them completely
+2. Only the builder agent prompt changes (stack section)
+3. Global tokens (colors, fonts, spacing) copy directly to any stack's equivalent globals file
+4. Assets in `public/` are universal — no changes needed
+
+Update Phase 4 builder prompt constraint line:
+```
+- Stack: [Astro / Nuxt 3 / SvelteKit / Vite+React] + TypeScript + Tailwind
+```
+Everything else in the prompt stays the same.

package/scripts/compare.mjs

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+/**
+ * compare.mjs — Visual regression: screenshot original vs clone side by side.
+ *
+ * Usage:
+ *   node scripts/compare.mjs <original-url> <clone-url>
+ *
+ * Requires: playwright
+ *   npm install playwright && npx playwright install chromium
+ *
+ * Output: docs/qa/compare-desktop.png, docs/qa/compare-mobile.png, docs/qa/report.json
+ */
+
+import { chromium } from 'playwright';
+import fs from 'fs';
+import path from 'path';
+
+const [,, originalUrl, cloneUrl] = process.argv;
+
+if (!originalUrl || !cloneUrl) {
+  console.error('Usage: node scripts/compare.mjs <original-url> <clone-url>');
+  process.exit(1);
+}
+
+const VIEWPORTS = [
+  { name: 'desktop', width: 1440, height: 900 },
+  { name: 'mobile',  width: 390,  height: 844 },
+];
+
+fs.mkdirSync('docs/qa', { recursive: true });
+
+const browser = await chromium.launch();
+const report = { original: originalUrl, clone: cloneUrl, viewports: [] };
+
+for (const vp of VIEWPORTS) {
+  console.log(`Capturing ${vp.name} (${vp.width}x${vp.height})...`);
+
+  const context = await browser.newContext({ viewport: { width: vp.width, height: vp.height } });
+
+  const [pageA, pageB] = await Promise.all([context.newPage(), context.newPage()]);
+
+  await Promise.all([
+    pageA.goto(originalUrl, { waitUntil: 'networkidle' }),
+    pageB.goto(cloneUrl,    { waitUntil: 'networkidle' }),
+  ]);
+
+  await Promise.all([pageA.waitForTimeout(1500), pageB.waitForTimeout(1500)]);
+
+  const [shotA, shotB] = await Promise.all([
+    pageA.screenshot({ fullPage: true }),
+    pageB.screenshot({ fullPage: true }),
+  ]);
+
+  const origPath  = `docs/qa/original-${vp.name}.png`;
+  const clonePath = `docs/qa/clone-${vp.name}.png`;
+  fs.writeFileSync(origPath,  shotA);
+  fs.writeFileSync(clonePath, shotB);
+
+  // Basic size comparison
+  const heightDiff = Math.abs(shotA.length - shotB.length);
+  const sizePct = Math.round((heightDiff / shotA.length) * 100);
+
+  report.viewports.push({
+    viewport: vp.name,
+    original: origPath,
+    clone: clonePath,
+    originalSize: shotA.length,
+    cloneSize: shotB.length,
+    sizeDiffPct: sizePct,
+    note: sizePct > 20 ? 'LARGE DIFF — review manually' : 'within range',
+  });
+
+  console.log(`  ✓ ${vp.name}: original=${origPath} clone=${clonePath} diff=${sizePct}%`);
+  await context.close();
+}
+
+await browser.close();
+
+fs.writeFileSync('docs/qa/report.json', JSON.stringify(report, null, 2));
+
+console.log('\n--- QA Report ---');
+for (const vp of report.viewports) {
+  const flag = vp.sizeDiffPct > 20 ? '⚠' : '✓';
+  console.log(`${flag} ${vp.viewport}: ${vp.note} (${vp.sizeDiffPct}% size diff)`);
+}
+console.log('\nOpen docs/qa/ to compare screenshots side by side.');
+console.log('Full report: docs/qa/report.json');