launchframe 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Evan Gruhlkey and Launchframe contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,200 @@
+# 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 is **not** a website cloning tool. It does not store HTML, JS, CSS,
+brand assets, logos, illustrations, or copywriting. Proprietary type
+families are substituted with open-source equivalents. See the
+[anti-clone policy](./rules/anti-clone-policy.md).
+
+---
+
+## 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, open **`output/<runId>/FOR_AI.md`** — it tells you
+exactly how to attach the folder in **Cursor** or **Claude Code** so
+the model follows your tokens when building UI.
+
+```txt
+output/<runId>/
+├── FOR_AI.md            ← paste / @-attach this for your AI (handoff instructions)
+├── tokens.json          ← every 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 observations
+```
+
+---
+
+## Hand the output to your AI
+
+1. Run the command above so `output/<runId>/` exists.
+2. Either:
+   - **Cursor:** `@`-attach the folder (or `FOR_AI.md` + `REPORT.md` + `tokens.json`) and paste the instruction block from `FOR_AI.md` into Composer, or
+   - **Claude Code:** copy the `output/<runId>/` folder into your project and attach it.
+3. The AI's authority order is **REPORT.md → tokens.json → merge tailwind.config.ts and globals.css into the app**. It must use semantic tokens (`bg-background`, `text-muted-foreground`, `bg-primary`, …) and write **original copy only**.
+
+---
+
+## 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/                # Original shadcn/ui blocks across families
+│   └── evaluation/            # Coherence / clone-risk / a11y evaluator
+├── pattern-atlas/             # Formalized pattern catalog per category
+├── prompts/                   # Markdown prompts for AI agents
+├── rules/                     # Design / copy / anti-clone / a11y policy
+├── 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/clone/a11y)
+npm run typecheck      # Project-wide TypeScript check
+```
+
+---
+
+## What this is not
+
+- **Not a scraper.** It captures only what is publicly rendered, stores
+  no HTML, and never republishes site content.
+- **Not a clone tool.** Anti-clone policy is enforced by capture-side
+  policy and synthesis-side normalization.
+- **Not a component library replacement.** It sits *on top* of
+  shadcn/ui and produces theme files for it.
+
+---
+
+## Anti-clone policy in one paragraph
+
+Launchframe captures publicly rendered pages, reads the **computed
+appearance** of those pages, and synthesizes an original design system
+from aggregate signals. It never stores HTML, JS, CSS, brand assets,
+illustrations, logos, or copy. Proprietary type families are
+substituted with open-source equivalents. Generated pages and design
+systems are checked against captured corpora for structural and
+token-level overlap; anything above the configured threshold fails the
+build. Full policy:
+[`rules/anti-clone-policy.md`](./rules/anti-clone-policy.md).
+
+---
+
+## License
+
+MIT. See [`LICENSE`](./LICENSE).

package/bin/launchframe.mjs

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+/**
+ * CLI entry for `npx launchframe` / `npm exec launchframe`.
+ * Spawns the TypeScript extract pipeline with the same Node that installed
+ * this package. Output defaults to `./output/<runId>/` in the *current*
+ * working directory (where the user ran the command), not inside the
+ * package install path.
+ */
+
+import { spawnSync } from "node:child_process";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const pkgRoot = join(__dirname, "..");
+const pkgJsonPath = join(pkgRoot, "package.json");
+
+const require = createRequire(pkgJsonPath);
+
+let tsxCli;
+try {
+  const tsxPkg = require.resolve("tsx/package.json", { paths: [pkgRoot] });
+  tsxCli = join(dirname(tsxPkg), "dist", "cli.mjs");
+} catch {
+  console.error(
+    "launchframe: could not resolve the `tsx` runtime. Re-install: npm install -g launchframe",
+  );
+  process.exit(1);
+}
+
+const extractScript = join(pkgRoot, "packages", "extract", "extract.ts");
+
+const result = spawnSync(
+  process.execPath,
+  [tsxCli, extractScript, ...process.argv.slice(2)],
+  {
+    cwd: process.cwd(),
+    stdio: "inherit",
+    env: process.env,
+    shell: false,
+  },
+);
+
+process.exit(result.status === null ? 1 : result.status);

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "launchframe",
+  "version": "0.1.0",
+  "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",
+  "homepage": "https://github.com/evangruhlkey/launchframe#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/evangruhlkey/launchframe.git"
+  },
+  "bugs": {
+    "url": "https://github.com/evangruhlkey/launchframe/issues"
+  },
+  "keywords": [
+    "launchframe",
+    "shadcn",
+    "shadcn-ui",
+    "tailwind",
+    "design-system",
+    "design-tokens",
+    "playwright",
+    "cursor",
+    "claude-code",
+    "ai",
+    "cli"
+  ],
+  "bin": {
+    "launchframe": "bin/launchframe.mjs"
+  },
+  "files": [
+    "bin",
+    "packages/extract",
+    "README.md",
+    "LICENSE"
+  ],
+  "workspaces": [
+    "apps/*",
+    "packages/*"
+  ],
+  "scripts": {
+    "extract": "tsx packages/extract/extract.ts",
+    "studio": "npm run dev --workspace apps/studio",
+    "studio:build": "npm run build --workspace apps/studio",
+    "capture": "tsx packages/capture/screenshot-site.ts",
+    "analyze": "tsx packages/analysis/analyze-screenshot.ts",
+    "formalize": "tsx packages/patterns/pattern-registry.ts",
+    "evaluate": "tsx packages/evaluation/evaluate-page.ts",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "format:check": "prettier --check ."
+  },
+  "dependencies": {
+    "playwright": "^1.48.0",
+    "tsx": "^4.19.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.7.0",
+    "prettier": "^3.3.3",
+    "typescript": "^5.6.0"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  }
+}

package/packages/extract/browser-extract.ts

@@ -0,0 +1,237 @@
+/**
+ * Browser-side token harvester.
+ *
+ * The exported `harvestTokens` is serialized by Playwright and run inside
+ * the page via `page.evaluate`. It walks the rendered DOM, collects
+ * computed styles, and returns a JSON-serializable raw observations
+ * record. It does NOT capture HTML, scripts, or third-party assets — it
+ * only reports values the browser already computed.
+ *
+ * The function is written as a single self-contained block so Playwright
+ * can serialize it without surprises. Helpers are inlined.
+ */
+
+import type { Page } from "playwright";
+
+import type { RawTokens } from "./types.js";
+
+/** Public entry: invoke the harvester inside the page. */
+export async function harvestTokens(
+  page: Page,
+  url: string,
+  viewport: { width: number; height: number },
+): Promise<RawTokens> {
+  // tsx/esbuild transpiles nested function declarations with a `__name`
+  // helper for nicer stack traces. Playwright serializes the function to
+  // a string and evaluates it in the browser, where `__name` is
+  // undefined. Define it as an identity function before invoking the
+  // harvester so the wrapped declarations resolve cleanly.
+  await page.evaluate(() => {
+    const g = globalThis as unknown as { __name?: (fn: unknown) => unknown };
+    if (typeof g.__name === "undefined") g.__name = (fn: unknown) => fn;
+  });
+
+  const partial = await page.evaluate(harvestInPage);
+  return {
+    url,
+    capturedAt: new Date().toISOString(),
+    viewport,
+    ...partial,
+  };
+}
+
+/**
+ * The harvester. Plain JS so Playwright can serialize it.
+ * Intentionally kept dependency-free.
+ */
+function harvestInPage(): Omit<RawTokens, "url" | "capturedAt" | "viewport"> {
+  const colorObs: Array<{
+    hex: string;
+    role: "text" | "background" | "border" | "shadow";
+    area: number;
+  }> = [];
+  const typeAgg = new Map<
+    string,
+    {
+      fontFamily: string;
+      fontSize: number;
+      fontWeight: number;
+      lineHeight: number;
+      letterSpacing: number;
+      count: number;
+    }
+  >();
+  const spacingAgg = new Map<string, { axis: "padding" | "gap" | "margin"; px: number; count: number }>();
+  const radiiAgg = new Map<number, number>();
+  const shadowsAgg = new Map<string, number>();
+
+  const all = document.querySelectorAll<HTMLElement>("body *");
+
+  /* ---------------- color helpers ---------------- */
+  const toHex = (rgb: string): string | null => {
+    if (!rgb || rgb === "transparent") return null;
+    const m = rgb.match(/rgba?\(([^)]+)\)/);
+    if (!m) return null;
+    const parts = m[1]!.split(",").map((s) => s.trim());
+    const r = parseInt(parts[0]!, 10);
+    const g = parseInt(parts[1]!, 10);
+    const b = parseInt(parts[2]!, 10);
+    const a = parts[3] !== undefined ? parseFloat(parts[3]) : 1;
+    if (a < 0.05) return null;
+    if ([r, g, b].some((n) => Number.isNaN(n))) return null;
+    const h = (n: number) => n.toString(16).padStart(2, "0");
+    return `#${h(r)}${h(g)}${h(b)}`;
+  };
+
+  const recordColor = (
+    hex: string | null,
+    role: "text" | "background" | "border" | "shadow",
+    area: number,
+  ) => {
+    if (!hex || area <= 0) return;
+    colorObs.push({ hex, role, area });
+  };
+
+  /* ---------------- spacing helpers ---------------- */
+  const recordSpacing = (axis: "padding" | "gap" | "margin", px: number) => {
+    if (!Number.isFinite(px) || px <= 0 || px > 256) return;
+    const key = `${axis}:${Math.round(px)}`;
+    const existing = spacingAgg.get(key);
+    if (existing) existing.count += 1;
+    else spacingAgg.set(key, { axis, px: Math.round(px), count: 1 });
+  };
+
+  /* ---------------- container width tracking ------- */
+  let dominantContainerPx: number | null = null;
+  let dominantContainerArea = 0;
+
+  /* ---------------- main pass ---------------- */
+  for (const el of Array.from(all)) {
+    const style = getComputedStyle(el);
+    if (style.visibility === "hidden" || style.display === "none") continue;
+
+    const rect = el.getBoundingClientRect();
+    if (rect.width <= 0 || rect.height <= 0) continue;
+    const area = rect.width * rect.height;
+
+    // Background
+    recordColor(toHex(style.backgroundColor), "background", area);
+
+    // Border (read each side; the four-side shorthand is typical)
+    const borderColor = toHex(style.borderTopColor);
+    const borderWidth =
+      parseFloat(style.borderTopWidth) || parseFloat(style.borderBottomWidth) || 0;
+    if (borderWidth > 0) recordColor(borderColor, "border", borderWidth * (rect.width + rect.height) * 2);
+
+    // Box shadow color
+    const shadow = style.boxShadow;
+    if (shadow && shadow !== "none") {
+      shadowsAgg.set(shadow, (shadowsAgg.get(shadow) ?? 0) + 1);
+      const colorMatch = shadow.match(/rgba?\([^)]+\)|#[0-9a-fA-F]{3,8}/);
+      if (colorMatch) recordColor(toHex(colorMatch[0]), "shadow", area * 0.05);
+    }
+
+    // Text content + color (only if the element has direct text)
+    const directText = directTextLength(el);
+    if (directText > 0) {
+      const fontSize = parseFloat(style.fontSize) || 16;
+      const textArea = directText * fontSize * fontSize * 0.45;
+      recordColor(toHex(style.color), "text", textArea);
+
+      const fontFamily = simplifyFontFamily(style.fontFamily);
+      const fontWeight = normalizeWeight(style.fontWeight);
+      const lineHeight =
+        style.lineHeight === "normal"
+          ? Math.round(fontSize * 1.4)
+          : parseFloat(style.lineHeight) || Math.round(fontSize * 1.4);
+      const letterSpacing =
+        style.letterSpacing === "normal" ? 0 : parseFloat(style.letterSpacing) || 0;
+
+      const k = `${fontFamily}|${fontSize}|${fontWeight}`;
+      const existing = typeAgg.get(k);
+      if (existing) existing.count += directText;
+      else
+        typeAgg.set(k, {
+          fontFamily,
+          fontSize: Math.round(fontSize),
+          fontWeight,
+          lineHeight: Math.round(lineHeight),
+          letterSpacing,
+          count: directText,
+        });
+    }
+
+    // Spacing
+    for (const side of ["padding-top", "padding-right", "padding-bottom", "padding-left"]) {
+      recordSpacing("padding", parseFloat(style.getPropertyValue(side)));
+    }
+    if ((style as CSSStyleDeclaration).gap) recordSpacing("gap", parseFloat(style.gap));
+    if ((style as CSSStyleDeclaration).rowGap)
+      recordSpacing("gap", parseFloat(style.rowGap));
+    if ((style as CSSStyleDeclaration).columnGap)
+      recordSpacing("gap", parseFloat(style.columnGap));
+
+    // Border radius
+    const radius = parseFloat(style.borderTopLeftRadius);
+    if (Number.isFinite(radius) && radius > 0 && radius < 64) {
+      const r = Math.round(radius);
+      radiiAgg.set(r, (radiiAgg.get(r) ?? 0) + 1);
+    }
+
+    // Container candidate: a wide horizontally-centered block element
+    const tag = el.tagName;
+    const isLayout =
+      tag === "MAIN" || tag === "SECTION" || tag === "DIV" || tag === "ARTICLE";
+    if (
+      isLayout &&
+      rect.width >= 720 &&
+      rect.width <= 1600 &&
+      rect.height >= 200 &&
+      area > dominantContainerArea
+    ) {
+      dominantContainerArea = area;
+      dominantContainerPx = Math.round(rect.width);
+    }
+  }
+
+  return {
+    colors: colorObs,
+    typography: Array.from(typeAgg.values()),
+    spacing: Array.from(spacingAgg.values()),
+    radii: Array.from(radiiAgg, ([px, count]) => ({ px, count })),
+    shadows: Array.from(shadowsAgg, ([value, count]) => ({ value, count })),
+    dominantContainerPx,
+  };
+
+  /* ----- inlined helpers ----- */
+
+  function directTextLength(el: Element): number {
+    let total = 0;
+    for (const child of Array.from(el.childNodes)) {
+      if (child.nodeType === 3) {
+        const text = (child.nodeValue ?? "").trim();
+        if (text) total += text.length;
+      }
+    }
+    return total;
+  }
+
+  function simplifyFontFamily(raw: string): string {
+    if (!raw) return "system-ui";
+    const first = raw.split(",")[0]!.trim().replace(/^["']|["']$/g, "");
+    return first || "system-ui";
+  }
+
+  function normalizeWeight(raw: string): number {
+    const named: Record<string, number> = {
+      normal: 400,
+      bold: 700,
+      lighter: 300,
+      bolder: 700,
+    };
+    if (named[raw] !== undefined) return named[raw]!;
+    const n = parseInt(raw, 10);
+    if (Number.isFinite(n)) return Math.max(100, Math.min(900, n));
+    return 400;
+  }
+}