launchframe 0.1.10 → 0.1.13

package/README.md

@@ -1,158 +1,140 @@
-# launchframe
+# Launchframe
 
-> Point Launchframe at SaaS sites you admire. Get back a drop-in
-> shadcn/ui design system you can build your own UI on top of —
-> with a ready-made handoff for Cursor or Claude Code.
+A reusable workflow for reverse-engineering live marketing sites into a **shadcn-style token theme**, **reference dumps** (DOM, copy index, media index), and a **layout-mirror** React scaffold — optimized for AI coding agents.
 
-`launchframe` opens each URL in headless Chromium, harvests the
-**computed appearance** of the rendered page (colors, type, spacing,
-radii, shadows), and synthesizes an original design system as
-`tailwind.config.ts` + `globals.css` + `tokens.json` + a Markdown
-report and an AI-handoff file.
+**Recommended:** [Claude Code](https://docs.anthropic.com/en/docs/claude-code) or **Cursor** for multi-phase builds — but Launchframe output works with any agent that can read Markdown and TypeScript.
 
-It also crawls the rendered DOM into a typed `SiteLayout` and emits a
-**layout-mirror page** per source: a Next.js component that reconstructs
-the source's section tree, grid, and density from typed primitives, with
-`<TextSlot>` / `<MediaSlot>` placeholders where the source had copy,
-logos, illustrations, or product imagery. The mirror does **not** embed
-the source's copy text, brand assets, or product screenshots — fill those
-slots with your own content before shipping. Proprietary type families
-are substituted with open-source equivalents.
-
----
+Point the CLI at a URL, run **`npx launchframe@latest`**, then drive the same **spec → parallel builders → merge → QA** rhythm popularized by [JCodesMore/ai-website-cloner-template](https://github.com/JCodesMore/ai-website-cloner-template). In Cursor, use the **Clone Website** command (`.cursor/commands/clone-website.md`), which matches that template’s pipeline with Launchframe handling automated recon.
 
 ## Quick start (any folder)
 
-The design system is written to **`./output/<runId>/`** in whatever
-directory you run the command from — not inside the package.
-
 **One time per machine** (Chromium for Playwright):
 
 ```bash
 npx playwright install chromium
 ```
 
-**Every time you want a new theme:**
+**Every extraction** (writes to **`./output/<runId>/`** in the current working directory):
 
 ```bash
 cd path/to/your-app-or-empty-folder
-npx launchframe@latest https://site-a.example https://site-b.example
+npx launchframe@latest https://example.com "Your SaaS idea"
 ```
 
-When it finishes, every source URL has produced a **layout-mirror
-page** under `output/<runId>/mirror/<host>/page.tsx`, plus a synthesized
-design system at the run root.
+Pass multiple URLs for a combined token synthesis (see CLI reference below). Your **SaaS idea** string is stored in `run.json`, `FOR_AI.md`, and `docs/research/`.
+
+**Then hand output to your agent:** attach **`FOR_AI.md`**, **`reference/<host>/`** (especially **`dom-structure.json`**), **`mirror/<host>/`**, **`tokens.json`**, and **`docs/design-references/<host-slug>/`**. For the full builder orchestration checklist, open **`AGENTS.md`** or run the **Clone Website** Cursor command.
+
+## Supported platforms
+
+| Agent | Status |
+| ----- | ------ |
+| [Claude Code](https://docs.anthropic.com/en/docs/claude-code) | Recommended |
+| [Cursor](https://cursor.com/) | Supported — `.cursor/commands/clone-website.md` |
+| [GitHub Copilot](https://github.com/features/copilot) | Supported — `AGENTS.md` → `npm run sync:agents` |
+| [Gemini CLI](https://github.com/google-gemini/gemini-cli) | Supported (`GEMINI.md`) |
+| [Cline](https://github.com/cline/cline) | Supported |
+| [Continue](https://continue.dev/) | Supported |
+| [Amazon Q](https://aws.amazon.com/q/developer/) | Supported |
+| … | Any agent that reads `AGENTS.md` |
+
+## Prerequisites
+
+- [Node.js](https://nodejs.org/) **20+**
+- Chromium via Playwright (`npx playwright install chromium`)
+
+## Tech stack
+
+- **Extract:** Node.js, Playwright, TypeScript
+- **Published CLI:** `npx launchframe` → `packages/extract/`
+- **Studio (optional):** Next.js App Router in `apps/studio/` (**Next.js 16**, **React 19**, Tailwind CSS, **Lucide** via `@framework/blocks` / direct imports — aligned with [ai-website-cloner-template](https://github.com/JCodesMore/ai-website-cloner-template); studio Tailwind is v3 today while their README cites **v4**; emitted run artifacts remain drop-in CSS/token bundles.)
+- **Mirror output:** React, Framer Motion, Phosphor (generated `page.tsx`)
+- **Tokens:** `tailwind.config.ts`, `globals.css`, `tokens.json`, `REPORT.md`
+
+## Parity with [ai-website-cloner-template](https://github.com/JCodesMore/ai-website-cloner-template)
+
+Launchframe mirrors that template’s **phases and artifact roles**, not its single-repo layout:
+
+| Aspect | What they do | What Launchframe does (same intent) |
+| -------- | ------------------ | ------------------------------------- |
+| **Phase 1 recon** | `/clone-website` drives screenshots, tokens, interaction sweep | **`npx launchframe`** performs automated recon (Playwright) into a run folder; optional Browser MCP passes match their sweep discipline (**Clone Website** in Cursor ≈ orchestration checklist) |
+| **Repo shape** | One Next.js app (`src/app`, `components`, …) | **Monorepo:** CLI (`packages/extract`) + optional **`apps/studio`** + **`packages/blocks`**; published CLI ships separately |
+| **Where artifacts live** | `docs/research/`, `docs/design-references/`, `public/` | Same tree **inside** `./output/<runId>/` (gitignored by default). To match their repo layout, run with **`--out path/to/your-next-app/extraction-<slug>`** or merge **`docs/`** + **`downloaded_assets/`** into your app’s **`docs/`** and **`public/images`** (and **`public/videos`**, **`public/seo`**) when integrating |
+| **Stack** | Next 16, React 19, Tailwind v4, Lucide | **Next 16 + React 19 + Lucide** in studio/blocks; Tailwind **v3** in-studio until upgraded to v4 |
+
+## How it works
+
+This repo combines **Launchframe automated extraction** with the **AI Website Cloner**-style agent workflow:
+
+1. **Automated recon** — headless Chromium capture, computed-style aggregation, reference dump (`dom-structure.json`, `visible-text.*`, `media.json`), design-reference PNGs and probes under `docs/design-references/`, and starter topology/spec files under `docs/research/`.
+2. **Foundation** — synthesized shadcn-compatible theme files at the run root; merge into your Next app.
+3. **Component specs** — per-section `.spec.md` files (extend Launchframe’s emitted stubs) with behaviors, states, and assets.
+4. **Parallel build** — agents in worktrees/branches per section or subcomponent.
+5. **Assembly & QA** — wire the target route (from mirror structure), visual diff against references.
+
+Each builder should receive **inline** spec content, not “go read the repo.” Authority order for structure is in **`FOR_AI.md`** and **`AGENTS.md`**.
+
+## Use cases
+
+- Seeding a **design system** from sites you’re allowed to analyze
+- **Layout research** with a typed mirror and DOM reference
+- **Rebuilding** properties you own when only the public site remains
+
+## Not intended for
+
+- **Impersonation or phishing**
+- **Passing off** another brand’s identity, trademarks, or licensed media
+- **Violating robots.txt or site terms** — Launchframe checks robots by default (`--no-robots` is discouraged)
+
+## Output layout
 
 ```txt
 output/<runId>/
-├── FOR_AI.md            ← paste / @-attach this for your AI (handoff instructions)
-├── tokens.json          ← every aggregated value, machine-readable
-├── tailwind.config.ts   ← drop-in Tailwind theme
-├── globals.css          ← drop-in shadcn-compatible CSS variables
-├── theme-preview.tsx    ← render this to eyeball the system
-├── REPORT.md            ← what was extracted, from where, why
-├── run.json             ← full run metadata (sources, timing, status)
-├── screenshots/         ← captured PNGs
-├── raw/                 ← per-site raw token + SiteLayout JSON
-├── reference/           ← verbatim DOM + **exact structure JSON** + copy for AI
+├── FOR_AI.md
+├── tokens.json
+├── tailwind.config.ts
+├── globals.css
+├── theme-preview.tsx
+├── REPORT.md
+├── run.json
+├── screenshots/
+├── raw/
+├── reference/
 │   └── <host>/
+│       ├── dom-structure.json
 │       ├── page.html
-│       ├── dom-structure.json   ← canonical body tree (tags, attrs, text nodes)
-│       ├── structure-outline.txt  ← tag skeleton for quick scanning
-│       ├── visible-text.txt
-│       ├── visible-text.json
+│       ├── visible-text.txt / .json
 │       ├── media.json
-│       ├── meta.json
 │       └── FOR_AI_REFERENCE.md
-└── mirror/
-    └── <host>/
-        ├── page.tsx         ← Next.js: Motion + Phosphor + image/video patterns
-        ├── layout.json
-        └── MIRROR_NOTES.md
+├── mirror/
+│   └── <host>/
+│       ├── page.tsx
+│       └── MIRROR_NOTES.md
+├── docs/
+│   ├── design-references/<host-slug>/   # PNGs, probes, hints
+│   └── research/<host-slug>/             # PAGE_TOPOLOGY, BEHAVIORS, components/*.spec.md
+└── downloaded_assets/<host-slug>/        # when enabled
 ```
 
----
-
-## Hand the output to your AI
-
-1. Run the command above so `output/<runId>/` exists.
-2. Attach **`reference/<host>/`**, especially **`dom-structure.json`** (exact tree) and **`visible-text.*`**, plus **`page.html`** and **`media.json`** so the model sees **exact structure and copy** from the crawl.
-3. Pick the mirror folder: `output/<runId>/mirror/<host>/`.
-4. Either:
-   - **Cursor:** `@`-attach `reference/<host>/`, `mirror/<host>/`, `FOR_AI.md`, and
-     `tokens.json`, then ask the agent to port copy from `visible-text.txt` into
-     `page.tsx` and wire media from `media.json`.
-   - **Claude Code:** copy both folders into your project, then ask the same.
-5. The AI's authority order is **`dom-structure.json` (nesting) → `structure-outline.txt` / `page.html` → `visible-text.*` →
-   MIRROR_NOTES.md → mirror `page.tsx` → tokens.json → tailwind.config.ts + globals.css**. It must:
-   - Keep the section tree, grid composition, density, Motion, and Phosphor usage in `page.tsx`.
-   - Map strings from `visible-text.txt` into the right `<TextSlot>` slots (or replace slots with plain JSX).
-   - Use `media.json` for image/video `src` / `poster` (respect licensing; prefer your own assets).
-
----
-
 ## CLI reference
 
 ```bash
-npx launchframe <url> [<url> ...] [options]
+npx launchframe@latest <url> [<url> ...] ["Your SaaS idea"] [options]
 ```
 
-| Flag           | Default              | Notes                                                    |
-| -------------- | -------------------- | -------------------------------------------------------- |
-| `--out <dir>`  | `./output/<runId>` (under **current working directory**) | Absolute or relative path for the run folder |
-| `--name <slug>`| _(unset)_            | Append a slug to the runId for findability              |
-| `--no-robots`  | _(off)_              | Skip robots.txt check (not recommended)                  |
-| `--rate <n>`   | `15`                 | Per-domain requests per minute                           |
-| `--width <px>` | `1440`               | Viewport width                                           |
-| `--height <px>`| `900`                | Viewport height                                          |
+| Flag | Default | Notes |
+| ---- | ------- | ----- |
+| `--out <dir>` | `./output/<runId>` | Run directory |
+| `--name <slug>` | _(unset)_ | Appends slug to run id |
+| `--no-robots` | off | Skip robots.txt check |
+| `--rate <n>` | `15` | Per-domain requests per minute |
+| `--width <px>` | `1440` | Viewport width |
+| `--height <px>` | `900` | Viewport height |
 
 ```bash
-npx launchframe https://example.com --name my-brand
-npx launchframe https://a.example https://b.example https://c.example --width 1280
-```
-
----
-
-## What the extractor actually does
-
-For each URL:
-
-1. Open the page in headless Chromium at a 1440 × 900 desktop viewport.
-2. Take a full-page screenshot.
-3. Walk the rendered DOM and harvest **computed styles** for every
-   visible element:
-   - Text and background colors, weighted by area
-   - Font families, sizes, weights, line-heights, letter-spacing
-   - Padding, gap, and margin values (snapped to a 4 px grid)
-   - Border radii (mode-picked across the page)
-   - Box-shadow stacks
-   - Dominant container width (the layout signal)
-4. Save the raw observations as JSON.
-
-After every site is captured, the synthesizer:
-
-1. Clusters all colors into a representative palette and derives a full
-   shadcn-compatible ramp (`--background`, `--foreground`, `--primary`,
-   …) for both light and dark themes.
-2. Picks a body base size from the count-weighted mode of body-range
-   font sizes, then fits a single scale ratio that lands the largest
-   observed heading at the `6xl` step. Substitutes proprietary type
-   families (e.g. SF Pro, Söhne, Circular, Graphik) with open-source
-   equivalents.
-3. Snaps spacing values to a 4 px scale, takes the most-used buckets,
-   and computes a recommended container width from the median dominant
-   block width across the corpus.
-4. Picks a representative radius and emits a tasteful three-stop shadow
-   scale.
-5. Writes drop-in files plus a Markdown report attributing every source.
-
-```
-URLs ──▶ Playwright ──▶ raw tokens.json ──▶ synthesize ──▶ DesignSystem ──▶ emit
-                              (per site)                    (one corpus)
+npx launchframe@latest https://example.com "AI billing copilot" --name acme
 ```
 
----
-
 ## Run inside this repo (contributors)
 
 ```bash
@@ -160,78 +142,33 @@ git clone https://github.com/evangruhlkey/launchframe
 cd launchframe
 npm install
 npx playwright install chromium
-npm run extract -- https://site-a.example https://site-b.example
+npm run extract -- https://example.com "Your SaaS idea"
 ```
 
-The repo is a monorepo that also contains a research framework for
-classifying SaaS UI patterns and generating original shadcn blocks:
-
-```txt
-launchframe/
-├── apps/
-│   └── studio/                # Next.js dashboard for browsing patterns/blocks
-├── packages/
-│   ├── extract/               # ← the published CLI
-│   ├── capture/               # Playwright screenshot capture (lower level)
-│   ├── analysis/              # Layout-tree extraction & section classifier
-│   ├── patterns/              # Typed pattern schemas + atlas registry loader
-│   ├── blocks/                # Shadcn/ui blocks + TextSlot / MediaSlot primitives
-│   └── evaluation/            # Coherence + responsiveness/a11y evaluator
-├── pattern-atlas/             # Pattern catalog per category (block-composition mode)
-├── prompts/                   # Markdown prompts for AI agents
-├── rules/                     # Design / copy / a11y rules
-├── registry/                  # shadcn-compatible custom registry manifest
-└── output/                    # ← every `extract` run lands here
-```
-
-Other commands (repo-only):
-
 ```bash
-npm run studio         # Next.js dashboard at localhost:3000
-npm run capture        # Lower-level Playwright capture pipeline
-npm run analyze        # Run section classifier on captured screenshots
-npm run formalize      # Validate the pattern-atlas/*.json files
-npm run evaluate       # Grade a generated page (coherence + a11y)
-npm run typecheck      # Project-wide TypeScript check
-npm run sync:agents    # Regenerate Copilot / Cline / Continue / Amazon Q stubs from AGENTS.md
+npm run studio           # Next.js studio
+npm run studio:build     # Production build
+npm run typecheck
+npm run sync:agents      # Regenerate Copilot / Cline / Continue / Amazon Q stubs from AGENTS.md
 ```
 
 ### AI agents in this repo
 
-- **`AGENTS.md`** (root) is the **single source of truth** for how agents should work here (extract handoff, structure fidelity, compliance). **`docs/research/INSPECTION_GUIDE.md`** is inlined into derived configs when you run `npm run sync:agents`.
-- **Cursor:** `.cursor/rules/project.mdc` points at `AGENTS.md`.
-- **Claude Code / Gemini CLI:** `CLAUDE.md` and `GEMINI.md` import `AGENTS.md`.
-- Edit `AGENTS.md`, then run `npm run sync:agents` (or `bash scripts/sync-agent-rules.sh`) to refresh `.github/copilot-instructions.md`, `.clinerules`, `.continue/rules/project.md`, and `.amazonq/rules/project.md`.
+- **`AGENTS.md`** is the **single source of truth** for agent instructions; **`docs/research/INSPECTION_GUIDE.md`** is inlined when you run **`npm run sync:agents`**.
+- **Cursor:** `.cursor/rules/project.mdc` points at `AGENTS.md`; use **Clone Website** for the full cloner-template-style checklist.
+- Edit **`AGENTS.md`**, then run **`npm run sync:agents`**.
+
+### Updating agent copies from one file
 
----
+| What | Source of truth | Sync command |
+| ---- | ----------------- | ------------ |
+| Project instructions | `AGENTS.md` | `npm run sync:agents` |
+| Cursor multi-phase pipeline | `.cursor/commands/clone-website.md` | (edit in repo — no codegen) |
 
 ## What this is not
 
-- **Not the source site's frontend bundle.** The **layout mirror** is React
-  code emitted from a typed `SiteLayout` (section tree, composition,
-  density) — not a dump of the origin's original components or stylesheets.
-- **Not a substitute for legal clearance.** `reference/<host>/` may contain
-  serialized DOM and visible text for tooling **you** run on pages you are
-  allowed to analyze. You are responsible for trademarks, copy licenses, and
-  `robots.txt`/ToS compliance when using those artifacts.
-- **Not a component library replacement.** Launchframe sits *alongside*
-  shadcn/ui: theme files, reference dumps, and slot-driven mirror pages —
-  you integrate into your own app.
-
----
-
-## Responsible use in one paragraph
-
-Launchframe is intended for layout research and design-system seeding
-against pages you have permission to analyze (your own products, sites
-where the operator has permission, or pages where structural analysis is
-permitted by `robots.txt`). The crawler respects `robots.txt` by default
-and rate-limits per domain. Output includes synthesized theme files, a
-typed **mirror** page scaffold, and (per capture) a **reference** bundle
-(DOM snapshot, visible text, media URLs) for AI-assisted reconstruction.
-Operators remain responsible for how they use copy, media, and branding.
-
----
+- **Not the origin site’s bundle** — output is synthesized tokens, reference artifacts, and a **slot-based mirror**, not a dump of proprietary components.
+- **Not legal clearance** — you are responsible for compliance; see **`FOR_AI.md`** and **`AGENTS.md`**.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "launchframe",
-  "version": "0.1.10",
+  "version": "0.1.13",
   "description": "Point Launchframe at SaaS sites you admire and get back a drop-in shadcn/ui design system (tokens, Tailwind theme, CSS variables, AI handoff) you can build your own UI on top of.",
   "license": "MIT",
   "author": "Evan Gruhlkey",