launchframe 0.3.1 → 0.4.0

package/AGENTS.md

@@ -0,0 +1,65 @@
+<!-- BEGIN:nextjs-agent-rules -->
+# This is NOT the Next.js you know
+
+This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in `node_modules/next/dist/docs/` before writing any code. Heed deprecation notices.
+<!-- END:nextjs-agent-rules -->
+
+# Website Reverse-Engineer Template
+
+## What This Is
+A reusable template for reverse-engineering any website into a clean, modern Next.js codebase using AI coding agents. The Next.js + shadcn/ui + Tailwind v4 base is pre-scaffolded — just run `/clone-website <url1> [<url2> ...]`.
+
+## Tech Stack
+- **Framework:** Next.js 16 (App Router, React 19, TypeScript strict)
+- **UI:** shadcn/ui (Radix primitives, Tailwind CSS v4, `cn()` utility)
+- **Icons:** Lucide React (default — will be replaced/supplemented by extracted SVGs)
+- **Styling:** Tailwind CSS v4 with oklch design tokens
+- **Deployment:** Vercel
+
+## Commands
+- `npm run dev` — Start dev server
+- `npm run build` — Production build
+- `npm run lint` — ESLint check
+- `npm run typecheck` — TypeScript check
+- `npm run check` — Run lint + typecheck + build
+
+## Code Style
+- TypeScript strict mode, no `any`
+- Named exports, PascalCase components, camelCase utils
+- Tailwind utility classes, no inline styles
+- 2-space indentation
+- Responsive: mobile-first
+
+## Design Principles
+- **Pixel-perfect emulation** — match the target's spacing, colors, typography exactly
+- **No personal aesthetic changes during emulation phase** — match 1:1 first, customize later
+- **Real content** — use actual text and assets from the target site, not placeholders
+- **Beauty-first** — every pixel matters
+
+## Project Structure
+```
+src/
+  app/              # Next.js routes
+  components/       # React components
+    ui/             # shadcn/ui primitives
+    icons.tsx       # Extracted SVG icons as React components
+  lib/
+    utils.ts        # cn() utility (shadcn)
+  types/            # TypeScript interfaces
+  hooks/            # Custom React hooks
+public/
+  images/           # Downloaded images from target site
+  videos/           # Downloaded videos from target site
+  seo/              # Favicons, OG images, webmanifest
+docs/
+  research/         # Inspection output (design tokens, components, layout)
+  design-references/ # Screenshots and visual references
+scripts/            # Asset download scripts
+```
+
+## MOST IMPORTANT NOTES
+- When launching Claude Code agent teams, ALWAYS have each teammate work in their own worktree branch and merge everyone's work at the end, resolving any merge conflicts smartly since you are basically serving the orchestrator role and have full context to our goals, work given, work achieved, and desired outcomes.
+- After editing `AGENTS.md`, run `bash scripts/sync-agent-rules.sh` to regenerate platform-specific instruction files.
+- After editing `.claude/skills/clone-website/SKILL.md`, run `node scripts/sync-skills.mjs` to regenerate the skill for all platforms.
+
+@docs/research/INSPECTION_GUIDE.md

package/README.md

@@ -1,56 +1,162 @@
-# Launchframe
+# Launchframe (AI Website Cloner)
 
-> **Scaffold a SaaS-ready Next.js codebase from any URL — in one command.**
+<a href="https://github.com/JCodesMore/ai-website-cloner-template/blob/master/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT License" /></a> <a href="https://github.com/JCodesMore/ai-website-cloner-template/stargazers"><img src="https://img.shields.io/github/stars/JCodesMore/ai-website-cloner-template?style=flat" alt="Stars" /></a> <a href="https://discord.gg/hrTSX5yTpB"><img src="https://img.shields.io/discord/1400896964597383279?label=discord" alt="Discord" /></a>
 
-```bash
-npx launchframe@latest <url> "<saas idea>"
-```
+Scaffold a Next.js + shadcn/ui project from **a reference URL you want to copy** plus **your SaaS idea** that drives landing-page positioning. Then run `/clone-website` so your AI agent reverse-engineers the reference layout while preserving your messaging inputs (`launchframe.context.json`, `docs/research/LAUNCHFRAME.md`, `src/lib/launchframe-config.ts`).
 
-Launchframe drops an [AI-cloner template](https://github.com/JCodesMore/ai-website-cloner-template) into **your current folder (project root)** by default — so **`.cursor`**, **`.claude`**, and the rest of the dotfolders sit where your editor expects them when you open that folder. It **runs `npm install` for you**. Then tell your AI **Build it** (same as `/clone-website`).
+**Recommended: [Claude Code](https://docs.anthropic.com/en/docs/claude-code) with Opus 4.7 for best results** — but works with a variety of AI coding agents.
 
-## Why Launchframe
+## Demo
 
-Cloning a website is a solved problem if you have a great AI agent and a great template. What's missing is **a one-command entrypoint that wires those together with your specific intent**.
+[![Watch the demo](docs/design-references/comparison.png)](https://youtu.be/O669pVZ_qr0)
 
-- Pick a real, beautiful, production-tested landing page
-- Pick the SaaS you want to ship
-- Get a buildable Next.js codebase in seconds, ready for your AI agent to clone + rebrand
+> Click the image above to watch the full demo on YouTube.
 
 ## Quick Start
 
-From an **empty** project folder (or after `git init` only):
+### CLI (recommended)
+
+From an empty folder (or anywhere you want the project folder created):
+
+```bash
+npx launchframe@latest https://example.com "Your SaaS idea in plain language"
+```
+
+Optional flags:
+
+- `--dir my-app` / `-o my-app` — output folder name (default: `<hostname>-launchframe`)
+- `--skip-install` — scaffold files only; run `npm install` yourself
+
+Then:
 
 ```bash
-mkdir my-saas && cd my-saas
-npx launchframe@latest https://linear.app "AI-powered customer feedback platform"
+cd <your-project-folder>
+npm run dev
 ```
 
-Then open **this folder** in [Cursor](https://cursor.com/) and chat: **Build it.**
+Open your AI agent and run `/clone-website <same-reference-url>` so it rebuilds the reference site into components while aligning hero copy with your SaaS idea files above.
+
+### Git template (advanced)
+
+1. Clone this repository and `npm install`
+2. Replace `src/lib/launchframe-config.ts` or run `npx launchframe ...` into a fresh folder
+3. Run `/clone-website <target-url>` from your agent
+
+> Using a different agent? Open `AGENTS.md` for project instructions — most agents pick it up automatically.
+
+## Supported Platforms
+
+| Agent                                                         | Status                     |
+| ------------------------------------------------------------- | -------------------------- |
+| [Claude Code](https://docs.anthropic.com/en/docs/claude-code) | **Recommended** — Opus 4.7 |
+| [Codex CLI](https://github.com/openai/codex)                  | Supported                  |
+| [OpenCode](https://opencode.ai/)                              | Supported                  |
+| [GitHub Copilot](https://github.com/features/copilot)         | Supported                  |
+| [Cursor](https://cursor.com/)                                 | Supported                  |
+| [Windsurf](https://codeium.com/windsurf)                      | Supported                  |
+| [Gemini CLI](https://github.com/google-gemini/gemini-cli)     | Supported                  |
+| [Cline](https://github.com/cline/cline)                       | Supported                  |
+| [Roo Code](https://github.com/RooCodeInc/Roo-Code)            | Supported                  |
+| [Continue](https://continue.dev/)                             | Supported                  |
+| [Amazon Q](https://aws.amazon.com/q/developer/)               | Supported                  |
+| [Augment Code](https://www.augmentcode.com/)                  | Supported                  |
+| [Aider](https://aider.chat/)                                  | Supported                  |
+
+## Prerequisites
+
+- [Node.js](https://nodejs.org/) 24+
+- An AI coding agent (see [Supported Platforms](#supported-platforms))
+
+## Tech Stack
+
+- **Next.js 16** — App Router, React 19, TypeScript strict
+- **shadcn/ui** — Radix primitives + Tailwind CSS v4
+- **Tailwind CSS v4** — oklch design tokens
+- **Lucide React** — default icons (replaced by extracted SVGs during cloning)
 
-Files land in the **current directory** so workspace rules apply. Prefer a subfolder? Use `--dir launchframe-app`.
+## How It Works
 
-## CLI Reference
+The `/clone-website` skill runs a multi-phase pipeline:
 
+1. **Reconnaissance** — screenshots, design token extraction, interaction sweep (scroll, click, hover, responsive)
+2. **Foundation** — updates fonts, colors, globals, downloads all assets
+3. **Component Specs** — writes detailed spec files (`docs/research/components/`) with exact computed CSS values, states, behaviors, and content
+4. **Parallel Build** — dispatches builder agents in git worktrees, one per section/component
+5. **Assembly & QA** — merges worktrees, wires up the page, runs visual diff against the original
+
+Each builder agent receives the full component specification inline — exact `getComputedStyle()` values, interaction models, multi-state content, responsive breakpoints, and asset paths. No guessing.
+
+## Use Cases
+
+- **Platform migration** — rebuild a site you own from WordPress/Webflow/Squarespace into a modern Next.js codebase
+- **Lost source code** — your site is live but the repo is gone, the developer left, or the stack is legacy. Get the code back in a modern format
+- **Learning** — deconstruct how production sites achieve specific layouts, animations, and responsive behavior by working with real code
+
+## Not Intended For
+
+- **Phishing or impersonation** — this project must not be used for deceptive purposes, impersonation, or any activity that breaks the law.
+- **Passing off someone's design as your own** — logos, brand assets, and original copy belong to their owners.
+- **Violating terms of service** — some sites explicitly prohibit scraping or reproduction. Check first.
+
+## Project Structure
+
+```
+src/
+  app/              # Next.js routes
+  components/       # React components
+    ui/             # shadcn/ui primitives
+    icons.tsx       # Extracted SVG icons
+  lib/utils.ts      # cn() utility
+  types/            # TypeScript interfaces
+  hooks/            # Custom React hooks
+public/
+  images/           # Downloaded images from target
+  videos/           # Downloaded videos from target
+  seo/              # Favicons, OG images
+docs/
+  research/         # Extraction output & component specs
+  design-references/ # Screenshots
+scripts/
+  sync-agent-rules.sh  # Regenerate agent instruction files
+  sync-skills.mjs      # Regenerate /clone-website for all platforms
+AGENTS.md           # Agent instructions (single source of truth)
+CLAUDE.md           # Claude Code config (imports AGENTS.md)
+GEMINI.md           # Gemini CLI config (imports AGENTS.md)
+```
+
+## Commands
+
+```bash
+npm run dev    # Start dev server
+npm run build  # Production build
+npm run lint   # ESLint check
+npm run typecheck # TypeScript check
+npm run check  # Run lint + typecheck + build
 ```
-npx launchframe@latest <url> "<saas idea>" [options]
-
-Options:
-  --dir <path>   Output folder (default: .)
-  --force        Merge into a non-empty directory (use with care)
-  --skip-install Skip npm install (CI / debugging)
-  --help, -h     Help
-  --version, -v  Version
+
+### If using docker
+
+```bash
+docker compose up app --build # build and run the app
+docker compose up dev --build # run the app in dev mode on port 3001
 ```
 
-## Monorepo (this repository)
+## Updating for Other Platforms
+
+Two source-of-truth files power all platform support. Edit the source, then run the sync script:
+
+| What                   | Source of truth                         | Sync command                       |
+| ---------------------- | --------------------------------------- | ---------------------------------- |
+| Project instructions   | `AGENTS.md`                             | `bash scripts/sync-agent-rules.sh` |
+| `/clone-website` skill | `.claude/skills/clone-website/SKILL.md` | `node scripts/sync-skills.mjs`     |
+
+Each script regenerates the platform-specific copies automatically. Agents that read the source files natively need no regeneration.
 
-- **`template/`** — Next.js app + agent skills (what `npx launchframe` copies).
-- **`bin/launchframe.mjs`** — CLI entrypoint.
 
-To work on the app: `cd template && npm install && npm run dev`.
+## Star History
 
-To verify the npm tarball before publish: `npm pack` at the repo root — the package must include `bin/` and `template/`.
+[![Star History Chart](https://api.star-history.com/svg?repos=JCodesMore/ai-website-cloner-template&type=Date)](https://star-history.com/#JCodesMore/ai-website-cloner-template&Date)
 
 ## License
 
-MIT — see [LICENSE](./LICENSE).
+MIT