launchframe 0.4.0 → 0.4.2

package/.windsurf/workflows/launchframe.md

@@ -0,0 +1,39 @@
+<!-- AUTO-GENERATED from .claude/skills/launchframe/SKILL.md — do not edit directly.
+     Run `node scripts/sync-skills.mjs` to regenerate. -->
+
+
+# Launchframe
+
+Help the user create a **new** Launchframe project. The CLI is **parameterless**:
+
+```bash
+npx launchframe@latest
+```
+
+It unpacks the full template into the **current working directory** (the folder root where the user runs the command). They should `mkdir`, `cd` into an **empty** folder first.
+
+## What you do
+
+1. Ensure the user has an **empty** directory (no existing `package.json`, `src/`, or `next.config.ts` there). If the workspace is already a Launchframe/Next project, they may only need `/clone-website` instead — clarify.
+
+2. Run exactly:
+
+   ```bash
+   npx launchframe@latest
+   ```
+
+   Optional: `LAUNCHFRAME_SOURCE_URL` and `LAUNCHFRAME_SAAS_IDEA` environment variables in the same shell if they want values pre-filled without editing files later.
+
+3. **Never** run this with the output target **inside** the `launchframe` package directory (the npm-installed template). If the open folder is this monorepo/template, have them `mkdir ../my-app && cd ../my-app` (sibling path), then run `npx launchframe@latest` there.
+
+4. Optional flags (same as CLI): `--dir <path>` to scaffold into another folder instead of cwd, `--skip-install` to skip `npm install`.
+
+5. After it finishes: they should **`npm run dev`** from **that same folder** (no extra `cd` if they scaffolded into cwd). Then they edit **`src/lib/launchframe-config.ts`** for reference URL and SaaS idea, and run **`/clone-website`** with that URL.
+
+## If optional notes from the user after the slash command (the CLI itself needs no URL or SaaS strings) are present
+
+The user may still paste a URL or idea in chat — **do not** require them for the CLI. Put any extra context into **`src/lib/launchframe-config.ts`** or `launchframe.context.json` for them after scaffold.
+
+## Fallback (local dev only)
+
+From a checkout of this repo: `node bin/launchframe.mjs` with the same empty-folder rules (optionally `--dir` outside the package root).

package/AGENTS.md

@@ -7,7 +7,7 @@ This version has breaking changes — APIs, conventions, and file structure may
 # 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> ...]`.
+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 — for a **new** folder, `mkdir`, `cd` into an **empty** directory, run **`npx launchframe@latest`** (no parameters), then edit **`src/lib/launchframe-config.ts`** and run **`/clone-website`** with your URL (or invoke **`/launchframe`** so the agent runs the same command). Or work in this repo and run **`/clone-website <url1> [<url2> ...]`** to clone into the current tree.
 
 ## Tech Stack
 - **Framework:** Next.js 16 (App Router, React 19, TypeScript strict)
@@ -35,6 +35,7 @@ A reusable template for reverse-engineering any website into a clean, modern Nex
 - **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
+- **DOM crawl priority** — when walking the target page, emphasize **images** (raster, responsive sources, CSS backgrounds), **SVGs** (inline icons, sprites, masks), then **motion** (keyframes, transitions, scroll/time-driven animation, libraries). Scrape and save real assets from the DOM/network first; **create** a stand-in image or vector only when fetch/blocking prevents extraction, and label substitutes clearly in research notes so the clone stays auditable
 
 ## Project Structure
 ```
@@ -60,6 +61,6 @@ 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.
+- After editing `.claude/skills/*/SKILL.md` (for example `clone-website` or `launchframe`), run `node scripts/sync-skills.mjs` to regenerate skill and command files for all platforms.
 
 @docs/research/INSPECTION_GUIDE.md

package/README.md

@@ -2,7 +2,7 @@
 
 <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>
 
-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`).
+Scaffold a Next.js + shadcn/ui project in **the folder where you run the command** — use **`npx launchframe@latest`** (no arguments; create an empty directory, `cd` into it, then run it). Configure the reference URL and SaaS copy in **`src/lib/launchframe-config.ts`**. Then run **`/clone-website`** so your AI agent reverse-engineers the reference layout while preserving your messaging (`launchframe.context.json`, `docs/research/LAUNCHFRAME.md`, `src/lib/launchframe-config.ts`). In the agent, **`/launchframe`** means the same one-liner.
 
 **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.
 
@@ -14,32 +14,33 @@ Scaffold a Next.js + shadcn/ui project from **a reference URL you want to copy**
 
 ## Quick Start
 
-### CLI (recommended)
+### 1. New project (empty folder)
 
-From an empty folder (or anywhere you want the project folder created):
+Create an **empty** directory, go into it, run the CLI with **no parameters** — files are written to **that folder** (your project root):
 
 ```bash
-npx launchframe@latest https://example.com "Your SaaS idea in plain language"
+mkdir my-app
+cd my-app
+npx launchframe@latest
 ```
 
-Optional flags:
+Optional: set `LAUNCHFRAME_SOURCE_URL` and `LAUNCHFRAME_SAAS_IDEA` in the environment before running to pre-fill config without editing files.
 
-- `--dir my-app` / `-o my-app` — output folder name (default: `<hostname>-launchframe`)
-- `--skip-install` — scaffold files only; run `npm install` yourself
+Then edit `src/lib/launchframe-config.ts` if you still need to change the reference URL or SaaS pitch, run `npm run dev`, and use **`/clone-website`** with your reference URL.
 
-Then:
+### AI agents (slash command)
 
-```bash
-cd <your-project-folder>
-npm run dev
-```
+In Cursor, Claude Code, Continue, etc., **`/launchframe`** tells the agent to run **`npx launchframe@latest`** in an empty folder the user chooses (same as above). No URL or SaaS strings are required on the command line.
+
+### Optional flags
 
-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.
+- `--dir path` / `-o path` — scaffold into another folder instead of the current directory (must be empty)
+- `--skip-install` — skip `npm install`
 
 ### 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
+2. Point `src/lib/launchframe-config.ts` at your site, or create sibling folder and run **`npx launchframe@latest`** there
 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.

package/bin/launchframe.mjs

@@ -1,54 +1,82 @@
 #!/usr/bin/env node
 /**
- * Scaffold a Launchframe project: clone reference URL via AI workflow + SaaS landing copy.
- * Usage: npx launchframe@latest <url> "<saas-idea>" [--dir=name] [--skip-install]
+ * Scaffold a Launchframe project into the current directory (or --dir).
+ * Usage: npx launchframe@latest [--dir=path] [--skip-install]
+ * Optional: LAUNCHFRAME_SOURCE_URL, LAUNCHFRAME_SAAS_IDEA env vars, or legacy CLI args.
  */
 
-import { cp, mkdir, readdir, readFile, writeFile } from "fs/promises";
+import { cp, mkdir, readdir, readFile, stat, writeFile } from "fs/promises";
 import { spawn } from "node:child_process";
-import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const PKG_ROOT = resolve(__dirname, "..");
 
-const SKIP_DIR_NAMES = new Set(["bin", "node_modules", ".git", ".next", "dist", "out"]);
-
-/** Root dot-directories we ship for agent tooling */
-const ALLOW_DOT_DIRS = new Set([
-  ".cursor",
-  ".claude",
-  ".codex",
-  ".continue",
-  ".gemini",
-  ".opencode",
-  ".windsurf",
-  ".github",
+const DEFAULT_URL = "https://example.com";
+const DEFAULT_SAAS_IDEA =
+  "Edit your SaaS pitch in src/lib/launchframe-config.ts, then run /clone-website with your reference URL.";
+
+/**
+ * Never copy these root entries into a scaffolded app (build artifacts, VCS, the CLI itself).
+ * All other root files and folders are copied as-is — including every dotfile and dot-directory
+ * so AI agents see the same agent rules and commands as this template.
+ */
+const SKIP_DIR_NAMES = new Set([
+  "bin",
+  "node_modules",
+  ".git",
+  ".next",
+  "dist",
+  "out",
+  "coverage",
+  ".turbo",
 ]);
 
-const SKIP_ROOT_FILES = new Set(["package-lock.json"]);
+const SKIP_ROOT_FILES = new Set([
+  "package-lock.json",
+  ".DS_Store",
+  "Thumbs.db",
+]);
+
+async function pathExists(p) {
+  try {
+    await stat(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
 
 function printHelp() {
   console.log(`
-launchframe — scaffold a Next.js app for cloning a reference site + your SaaS idea
+launchframe — scaffold a Next.js app into the current directory (project root)
 
 Usage:
-  npx launchframe@latest <url> "<saas-idea>" [options]
+  npx launchframe@latest
+
+This unpacks the template into the folder you are in (where you ran the command).
+No URL or SaaS arguments are required — edit src/lib/launchframe-config.ts after scaffold.
 
-Arguments:
-  <url>           HTTPS URL of the site to reverse-engineer (visual reference)
-  "<saas-idea>"   Short pitch / positioning that should appear on the landing page
+Optional environment variables (same session):
+  LAUNCHFRAME_SOURCE_URL     Reference site to clone later (https://...)
+  LAUNCHFRAME_SAAS_IDEA     Short landing-page pitch text
+
+Legacy (optional positional args, for scripts only):
+  npx launchframe@latest <url> "<saas-idea>"
 
 Options:
-  --dir, -o       Output folder (default: first label of hostname + "-launchframe")
+  --dir, -o       Scaffold into this folder instead of the current directory (must be empty)
   --skip-install  Do not run npm install after scaffolding
   -h, --help      Show this message
 
 Note:
-  The output folder must not live inside the Launchframe package directory (the folder that contains this CLI).
+  Run inside an empty project folder (no existing package.json / src / next.config).
+  The output folder must not be inside the Launchframe npm package directory.
 
 Example:
-  npx launchframe@latest https://stripe.com "AI invoicing for freelancers"
+  mkdir my-app && cd my-app
+  npx launchframe@latest
 `);
 }
 
@@ -106,20 +134,8 @@ function validateUrl(raw) {
   return u.href;
 }
 
-function defaultDirName(urlStr) {
-  try {
-    const host = new URL(urlStr).hostname.replace(/^www\./i, "");
-    const label = host.split(".")[0] || "site";
-    const safe = label.replace(/[^a-zA-Z0-9-_]/g, "-").toLowerCase();
-    return `${safe || "site"}-launchframe`;
-  } catch {
-    return "launchframe-app";
-  }
-
-}
-
-function slugFromDir(dir) {
-  const base = dir.replace(/\\/g, "/").split("/").filter(Boolean).pop() ?? "launchframe-app";
+function slugFromDir(destRootAbs) {
+  const base = basename(resolve(destRootAbs));
   return base
     .toLowerCase()
     .replace(/[^a-z0-9-_]/g, "-")
@@ -133,9 +149,6 @@ function tsStringLiteral(value) {
 
 function shouldCopyRootEntry(baseName, isDirectory) {
   if (SKIP_DIR_NAMES.has(baseName)) return false;
-  if (isDirectory && baseName.startsWith(".")) {
-    if (!ALLOW_DOT_DIRS.has(baseName)) return false;
-  }
   if (!isDirectory && SKIP_ROOT_FILES.has(baseName)) return false;
   return true;
 }
@@ -188,7 +201,8 @@ async function writeGeneratedPackageJson(destRoot, npmPackageName) {
 
 async function writeLaunchframeArtifacts(destRoot, url, idea) {
   const configTs = `/**
- * Written by Launchframe CLI — edit freely after scaffolding.
+ * Set your reference site and positioning, then use /clone-website with the same URL.
+ * Written by Launchframe CLI — edit freely.
  */
 export const LAUNCHFRAME_SOURCE_URL = ${tsStringLiteral(url)} as const;
 
@@ -201,7 +215,7 @@ export const LAUNCHFRAME_SAAS_IDEA = ${tsStringLiteral(idea)} as const;
     sourceUrl: url,
     saasIdea: idea,
     notes:
-      "Use /clone-website with sourceUrl for pixel-perfect extraction. Align landing copy with saasIdea.",
+      "Edit this file or src/lib/launchframe-config.ts. Use /clone-website with sourceUrl for pixel-perfect extraction.",
   };
   await writeFile(
     join(destRoot, "launchframe.context.json"),
@@ -219,7 +233,7 @@ ${url}
 
 ${idea}
 
-When running \`/clone-website\`, pass the reference URL above. After structural cloning, rewrite headings and hero copy so they clearly communicate the SaaS idea while respecting attribution and copyright for third-party brands.
+When running \`/clone-website\`, pass the reference URL above (update src/lib/launchframe-config.ts first if you still use the default). After structural cloning, align hero copy with your SaaS idea while respecting attribution and copyright for third-party brands.
 `;
 
   await mkdir(join(destRoot, "docs", "research"), { recursive: true });
@@ -231,7 +245,14 @@ async function writeReadme(destRoot, npmPackageName, url, idea) {
 
 Created with [\`launchframe\`](https://www.npmjs.com/package/launchframe).
 
-## Inputs
+## Configure
+
+Edit \`src/lib/launchframe-config.ts\`:
+
+- \`LAUNCHFRAME_SOURCE_URL\` — site to reverse-engineer
+- \`LAUNCHFRAME_SAAS_IDEA\` — landing copy / positioning
+
+Current values (from scaffold):
 
 - **Reference site:** ${url}
 - **SaaS idea:** ${idea}
@@ -243,13 +264,7 @@ npm install
 npm run dev
 \`\`\`
 
-Open your AI agent (Cursor, Claude Code, etc.) and run:
-
-\`\`\`
-/clone-website ${url}
-\`\`\`
-
-Keep the SaaS positioning from \`launchframe.context.json\` / \`src/lib/launchframe-config.ts\` when adapting cloned sections.
+Open your AI agent and run \`/clone-website <your-reference-url>\` (same URL as in the config).
 
 See \`AGENTS.md\` for full agent instructions.
 `;
@@ -257,6 +272,21 @@ See \`AGENTS.md\` for full agent instructions.
   await writeFile(join(destRoot, "README.md"), body, "utf8");
 }
 
+/** Refuse to stomp an existing Next-style project in the target directory. */
+async function assertScaffoldTargetVacant(destRoot) {
+  const conflicts = ["package.json", "next.config.ts", "src"];
+  for (const c of conflicts) {
+    if (await pathExists(join(destRoot, c))) {
+      console.error(
+        `Refusing to scaffold: "${c}" already exists in this folder.\n` +
+          `Create a new empty directory, cd into it, then run:\n` +
+          `  npx launchframe@latest\n`,
+      );
+      process.exit(1);
+    }
+  }
+}
+
 function runNpmInstall(cwd) {
   return new Promise((resolvePromise, reject) => {
     const child = spawn("npm", ["install"], {
@@ -272,6 +302,17 @@ function runNpmInstall(cwd) {
   });
 }
 
+function resolveUrlAndIdea(args) {
+  const envUrl =
+    process.env.LAUNCHFRAME_SOURCE_URL?.trim() || process.env.LAUNCHFRAME_URL?.trim();
+  const envIdea = process.env.LAUNCHFRAME_SAAS_IDEA?.trim();
+
+  let urlRaw = args.url?.trim() || envUrl || DEFAULT_URL;
+  let ideaRaw = args.idea?.trim() || envIdea || DEFAULT_SAAS_IDEA;
+
+  return { urlRaw, ideaRaw };
+}
+
 async function main() {
   const args = parseArgs(process.argv.slice(2));
   if (args.help) {
@@ -279,36 +320,31 @@ async function main() {
     process.exit(0);
   }
 
-  if (!args.url || !args.idea) {
-    console.error("Error: missing URL or SaaS idea.\n");
-    printHelp();
+  const destRoot = args.dir?.trim()
+    ? resolve(process.cwd(), args.dir.trim())
+    : resolve(process.cwd());
+
+  if (isForbiddenOutput(PKG_ROOT, destRoot)) {
+    console.error(
+      "Output folder cannot be inside the Launchframe package directory. Create a new folder outside this package and cd into it, then run npx launchframe@latest again.",
+    );
     process.exit(1);
   }
 
+  await assertScaffoldTargetVacant(destRoot);
+
+  const { urlRaw, ideaRaw } = resolveUrlAndIdea(args);
+
   let url;
   try {
-    url = validateUrl(args.url);
+    url = validateUrl(urlRaw);
   } catch (e) {
     console.error(String(e.message));
     process.exit(1);
   }
 
-  const idea = args.idea.trim();
-  if (!idea) {
-    console.error("Error: SaaS idea cannot be empty.");
-    process.exit(1);
-  }
-
-  const dirName = args.dir?.trim() || defaultDirName(url);
-  const destRoot = resolve(process.cwd(), dirName);
-  const npmPackageName = slugFromDir(dirName);
-
-  if (isForbiddenOutput(PKG_ROOT, destRoot)) {
-    console.error(
-      "Output folder cannot be inside the Launchframe package directory. Run from a parent folder or choose another path.",
-    );
-    process.exit(1);
-  }
+  const idea = ideaRaw.trim() || DEFAULT_SAAS_IDEA;
+  const npmPackageName = slugFromDir(destRoot);
 
   await mkdir(destRoot, { recursive: true });
 
@@ -318,22 +354,23 @@ async function main() {
   await writeLaunchframeArtifacts(destRoot, url, idea);
   await writeReadme(destRoot, npmPackageName, url, idea);
 
-  console.log(`\nCreated Launchframe project at ${destRoot}`);
+  console.log(`\nScaffolded Launchframe in:\n  ${destRoot}`);
   console.log(`  Reference URL: ${url}`);
   console.log(`  SaaS idea: ${idea}\n`);
+  console.log("Edit src/lib/launchframe-config.ts if you need different values.\n");
 
   if (!args.skipInstall) {
     console.log("Running npm install...\n");
     try {
       await runNpmInstall(destRoot);
-      console.log("\nDone. Next: cd " + JSON.stringify(dirName) + " && npm run dev\n");
+      console.log("\nDone. From this folder: npm run dev\n");
     } catch (e) {
       console.error(String(e.message));
-      console.error("\nDependencies were not installed. Run npm install inside the folder manually.\n");
+      console.error("\nRun npm install in this folder manually.\n");
       process.exit(1);
     }
   } else {
-    console.log("Skipped npm install (--skip-install). Run npm install inside the folder.\n");
+    console.log("Skipped npm install (--skip-install). Run npm install in this folder.\n");
   }
 }
 

package/docs/research/INSPECTION_GUIDE.md

@@ -4,6 +4,16 @@
 
 This guide outlines what to capture when inspecting a target website via Chrome MCP or browser DevTools.
 
+## Priority: media, SVGs, and motion (do this early)
+
+When crawling the DOM and network, **tackle these before fine-tuning copy or spacing**:
+
+1. **Raster imagery** — Every `<img>`, `<picture>` / `source`, `srcset` / `sizes`, CDN URLs, lazy-loaded `data-src`, `loading="lazy"` nodes, **CSS `background-image`** on the element and ancestors (including `::before` / `::after`), masks that use `url()`, `<video>` still / poster frames. Prefer **downloading** originals via scripts or MCP; if a URL is blocked or session-gated, **export a screenshot** of the element’s bounding box at a crisp DPR and store it under `public/images/`, and note the substitute in the spec.
+2. **SVGs** — Inline `<svg>`, `<use>` / sprite sheets, **SVG in CSS** (`mask-image`, `background-image`), favicons as SVG, logo marks. Prefer extracting path/viewBox into React components or static files under `public/` — **recreate** from a screenshot/trace only when the markup is obfuscated or blocked.
+3. **Motion & animation** — Inspect Styles for `animation`, `animation-name`, `animation-timeline`, `transition`, `transform`, `@keyframes`; check for libraries (Framer Motion, GSAP, Lottie, Lenis). Capture **durations, easings, delays, fill-modes**, scroll/view triggers, and `prefers-reduced-motion` handling. Motion often defines perceived quality — do not leave it as an afterthought.
+
+Then continue with typography, spacing, and component structure as usual.
+
 ## Phase 1: Visual Audit
 
 ### Screenshots to Capture

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "launchframe",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "private": false,
   "description": "Scaffold a Next.js app from a reference URL plus your SaaS idea — AI-ready website cloning",
   "author": "JCodesMore",
@@ -62,7 +62,9 @@
     ".gemini",
     ".opencode",
     ".windsurf",
-    ".github"
+    ".github",
+    ".amazonq",
+    ".augment"
   ],
   "scripts": {
     "dev": "next dev",