launchframe 0.1.7 → 0.1.9

package/README.md

@@ -1,229 +1,238 @@
-# 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.
-
-`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.
-
-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.
-
----
-
-## 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:**
-
-```bash
-cd path/to/your-app-or-empty-folder
-npx launchframe@latest https://site-a.example https://site-b.example
-```
-
-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.
-
-```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 + copy for AI (see below)
-│   └── <host>/
-│       ├── page.html           ← full HTML after JavaScript
-│       ├── visible-text.txt    ← paste-friendly copy extraction
-│       ├── visible-text.json   ← structured headings / body / buttons
-│       ├── media.json          ← img + video URLs
-│       ├── meta.json           ← title, description, lang
-│       └── FOR_AI_REFERENCE.md
-└── mirror/
-    └── <host>/
-        ├── page.tsx         ← Next.js: Motion + Phosphor + image/video patterns
-        ├── layout.json
-        └── MIRROR_NOTES.md
-```
-
----
-
-## Hand the output to your AI
-
-1. Run the command above so `output/<runId>/` exists.
-2. Attach **`reference/<host>/`** (`visible-text.txt`, `page.html`, `media.json`) so the model sees **exact copy and structure** 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 **reference/visible-text.txt & page.html →
-   MIRROR_NOTES.md → 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]
-```
-
-| 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                                          |
-
-```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)
-```
-
----
-
-## Run inside this repo (contributors)
-
-```bash
-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
-```
-
-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
-```
-
----
-
-## What this is not
-
-- **Not a verbatim site downloader.** The crawler builds a typed
-  `SiteLayout` model from the rendered DOM — section tree, geometry,
-  computed style tokens, content kinds — and emits code generated from
-  that model. It does not save the source's HTML/CSS to disk.
-- **Not a content lift.** Heading text, body copy, logos, illustrations,
-  and product imagery become `<TextSlot>` / `<MediaSlot>` placeholders in
-  the mirror page. You fill them with your own copy and assets before
-  shipping.
-- **Not a component library replacement.** It sits *on top* of
-  shadcn/ui and produces theme files plus slot-driven page templates.
-
----
-
-## 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. The output is generated code derived from a
-normalized typed model and slot placeholders — not a verbatim copy of
-the source's markup, copy, or assets. Operators are responsible for the
-content they paste into those slots and for honoring third-party
-trademarks, terms of service, and licenses.
-
----
-
-## License
-
-MIT. See [`LICENSE`](./LICENSE).
+# 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.
+
+`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.
+
+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.
+
+---
+
+## 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:**
+
+```bash
+cd path/to/your-app-or-empty-folder
+npx launchframe@latest https://site-a.example https://site-b.example
+```
+
+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.
+
+```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
+│   └── <host>/
+│       ├── 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
+│       ├── media.json
+│       ├── meta.json
+│       └── FOR_AI_REFERENCE.md
+└── mirror/
+    └── <host>/
+        ├── page.tsx         ← Next.js: Motion + Phosphor + image/video patterns
+        ├── layout.json
+        └── MIRROR_NOTES.md
+```
+
+---
+
+## 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]
+```
+
+| 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                                          |
+
+```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)
+```
+
+---
+
+## Run inside this repo (contributors)
+
+```bash
+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
+```
+
+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
+```
+
+### 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`.
+
+---
+
+## 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.
+
+---
+
+## License
+
+MIT. See [`LICENSE`](./LICENSE).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "launchframe",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "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",
@@ -46,6 +46,7 @@
     "analyze": "tsx packages/analysis/analyze-screenshot.ts",
     "formalize": "tsx packages/patterns/pattern-registry.ts",
     "evaluate": "tsx packages/evaluation/evaluate-page.ts",
+    "sync:agents": "node scripts/sync-agent-rules.mjs",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "format:check": "prettier --check ."
   },