diff --git a/docs/SESSION-HANDOFF.md b/docs/SESSION-HANDOFF.md new file mode 100644 index 0000000000..05c0e4caef --- /dev/null +++ b/docs/SESSION-HANDOFF.md @@ -0,0 +1,175 @@ +# Session Handoff — Website Capture & DESIGN.md System + +> Last updated: 2026-04-07 (end of marathon session) +> Branch: `feat/website-capture-design-md` +> Key commit: d60a9f8 + +## What Was Built This Session + +### Core Pipeline: `hyperframes capture ` + +A complete website-to-video pipeline that produces AI-agent-ready output: + +``` +hyperframes capture https://stripe.com -o /tmp/stripe +``` + +**Pipeline steps (in order):** +1. Launch headless Chrome (Puppeteer) +2. Catalog animations (Web Animations API, CSS, IntersectionObserver, CDP) +3. Extract HTML & CSS +4. Extract design tokens (colors, fonts, headings, CTAs, sections, CSS variables) +5. Catalog assets with HTML contexts (img[src], css url(), link[rel=preload], video[src], etc.) +6. Detect JS libraries (GSAP, Three.js, ScrollTrigger, etc. via globals + script URLs) +7. Extract ALL visible text in DOM order +8. Extract inline SVGs (up to 50, 10KB each) +9. **Full-page screenshot via Playwright** (not Puppeteer — Playwright doesn't resize viewport, preserving fixed/sticky layouts) +10. Download assets (fonts, images, SVGs, favicon) +11. **AI-generated DESIGN.md** via Gemini 3.1 Pro or Claude Sonnet (screenshot + tokens → rich design system prose + programmatic asset catalog) +12. **AI-generated replica.html** — clean single-file Tailwind CSS recreation of the website +13. **Refinement pass** — screenshots replica, compares to original, asks AI to fix differences +14. Generate CLAUDE.md + .cursorrules (AI agent instructions) +15. *(Optional)* Split into section compositions, verify, CSS purge, HTML prettify + +**Output files:** +- `DESIGN.md` — AI-written design system (colors, typography, elevation, components, do's/don'ts) + programmatic asset catalog with HTML contexts +- `replica.html` — Clean Tailwind CSS recreation (~30-56KB, single file) +- `screenshots/full-page.png` — Full-page website screenshot +- `screenshots/replica-screenshot.png` — Screenshot of the replica (for comparison) +- `CLAUDE.md` + `.cursorrules` — AI agent instructions (auto-read by Claude Code/Cursor) +- `assets/` — Downloaded fonts, images, SVGs, favicon +- `assets/svgs/` — Extracted inline SVGs from the page +- `extracted/` — Raw HTML, CSS, animation data, tokens.json +- `compositions/` — *(if split enabled)* Per-section HTML compositions (CSS-purged, prettified) + +### Key Files + +| File | Purpose | +|------|---------| +| `packages/cli/src/capture/index.ts` | Pipeline orchestrator | +| `packages/cli/src/capture/designMdGenerator.ts` | AI-powered DESIGN.md generation (Gemini or Claude) | +| `packages/cli/src/capture/replicaGenerator.ts` | AI-powered HTML replica + refinement loop | +| `packages/cli/src/capture/assetCataloger.ts` | Comprehensive asset extraction with HTML contexts | +| `packages/cli/src/capture/screenshotCapture.ts` | Full-page screenshot (Playwright) | +| `packages/cli/src/capture/cssPurger.ts` | PurgeCSS + Prettier for compositions | +| `packages/cli/src/capture/agentPromptGenerator.ts` | CLAUDE.md/.cursorrules generation | +| `packages/cli/src/capture/tokenExtractor.ts` | Design token extraction (colors, fonts, headings, SVGs) | +| `packages/cli/src/capture/animationCataloger.ts` | Animation detection (4 techniques) | +| `packages/cli/src/capture/assetDownloader.ts` | Asset downloading + inline SVG saving | +| `packages/cli/src/capture/briefGenerator.ts` | Legacy (replaced by DESIGN.md, kept for reference) | +| `packages/cli/src/commands/capture.ts` | CLI command definition | + +### Research Documentation + +| File | Contents | +|------|----------| +| `docs/research/aura-build-and-design-systems.md` | Complete Aura.build analysis, DESIGN.md format, prompt builder | +| `docs/research/aura-prompt-comparison.md` | Side-by-side comparison of Aura's with/without screenshot prompts | +| `docs/research/aura-examples/stripe-DESIGN.md` | Aura's Stripe DESIGN.md for comparison | +| `docs/research/reverse-engineered-aura-system-prompt.md` | **Reverse-engineered Aura system instructions** based on output analysis | + +## Known Issues & Gaps + +### Screenshot +- Puppeteer `fullPage:true` breaks complex sites (mesh gradients, position:fixed layers) — solved by using Playwright instead +- Chrome 16,384px height limit — pages taller than this get clipped at the bottom +- Stripe's hero wave gradient still shows artifacts in some captures + +### Replica Quality +- Gemini 3.1 Pro produces better replicas than Claude Sonnet for visual-to-code +- Company logos in "logo walls" often rendered as text instead of images because the original site uses inline SVGs (not `` tags) — our extractor now saves them to `assets/svgs/` but the AI can't access local files during generation +- Refinement pass sometimes rewrites Tailwind to vanilla CSS (fixed with explicit rules in refinement prompt) +- Complex animations (WebGL gradients, Three.js scenes) not reproduced — AI generates static alternatives + +### DESIGN.md +- Comparable to Aura's quality for most sections +- Asset catalog includes HTML contexts (img[src], css url(), link[rel=preload], etc.) +- Deduplicates srcset resolution variants +- Filters tracking pixels and CSS fragment references +- Inline SVGs now saved but listed as local paths (not URLs accessible to external AI) + +### Compositions (Optional Path) +- CSS purge reduces captured compositions by 87% (7.2MB → 918KB) +- HTML prettify makes them AI-readable (one-tag-per-line) +- But compositions may be unnecessary — replica.html serves the same purpose more cleanly + +## Environment Variables + +| Variable | Purpose | +|----------|---------| +| `GEMINI_API_KEY` | Google Gemini API (for DESIGN.md and replica generation) | +| `ANTHROPIC_API_KEY` | Claude API (fallback for DESIGN.md and replica) | +| `CLAUDE_API_KEY` | Alternative Claude API key name | + +Gemini is preferred when set. Falls back to Claude. If neither is set, DESIGN.md uses a structured template (no AI prose) and replica is skipped. + +## Model IDs +- Gemini: `gemini-3.1-pro-preview` (NOT gemini-2.5-flash) +- Claude: `claude-sonnet-4-20250514` + +## What's Next + +### Priority 1: HyperFrames Video Creation Workflow +The whole point was to create VIDEOS from captured websites. The current output (DESIGN.md + screenshot + replica.html) gives an AI agent everything it needs to create on-brand video compositions. But we need: + +1. **A prompt/skill that bridges DESIGN.md → HyperFrames compositions** — the AI reads the DESIGN.md, understands the brand, then creates video compositions following HyperFrames rules (GSAP timelines, data-* attributes, clip visibility) +2. **Use-case library** — pre-built prompts for common video types: + - 15s social media ad + - 30s product tour + - Feature highlight reel + - Testimonial spotlight + - Competitor comparison + - Customer case study +3. **Prompt builder** — interactive prompt construction (like Aura's but for video) + +### Priority 2: SVG Logo Fix +Inline SVGs are saved locally but the AI can't access them during generation. Options: +- Embed SVG code directly in DESIGN.md (bloats the file) +- Upload to a temp CDN during capture +- Accept this limitation — the local AI agent (Claude Code) CAN read them + +### Priority 3: Web Shader Extractor Integration +141K websites use Three.js. Stripe, Linear, Vercel all have WebGL. The lixiaolin94/skills shader extractor could capture these effects. Research done, implementation deferred. + +### Priority 4: Prompt Builder UI +Could live in HyperFrames Studio. Categories (from Aura research): +- Scene types: Hero, Features, Stats, Testimonial, CTA, Comparison +- Duration: 15s, 30s, 60s +- Style: Energetic, Corporate, Cinematic, Minimal +- Transitions: Wipe, Fade, Slide, Scale +- Animation: Stagger, Counter, Reveal, Float + +## Dependencies Added +- `purgecss` — CSS tree-shaking for compositions +- `prettier` — HTML prettification +- `@anthropic-ai/sdk` — Claude API +- `@google/genai` — Gemini API +- `playwright` — Full-page screenshots (better than Puppeteer for this) + +## How to Test + +```bash +# Capture with Gemini (recommended) +GEMINI_API_KEY="your-key" npx tsx packages/cli/src/cli.ts capture https://notion.com -o /tmp/test --skip-split + +# Capture with Claude (fallback) +ANTHROPIC_API_KEY="your-key" npx tsx packages/cli/src/cli.ts capture https://notion.com -o /tmp/test --skip-split + +# With compositions (full pipeline) +GEMINI_API_KEY="your-key" npx tsx packages/cli/src/cli.ts capture https://notion.com -o /tmp/test + +# Serve and view replica +python3 -m http.server 3334 --directory /tmp/test +open http://localhost:3334/replica.html +``` + +## User Preferences (from memory) + +- DESIGN.md must be AI-generated prose, not template filling +- Always verify by reading outputs, comparing to references +- Don't hide problems — show them honestly +- Research thoroughly before implementing +- Match Aura.build quality as the benchmark +- Don't add HyperFrames-specific sections to DESIGN.md (keep it universal) +- Full-page screenshot only (no per-section screenshots) +- Gemini 3.1 Pro preferred over Claude for visual-to-code tasks diff --git a/docs/research/aura-examples/stripe-DESIGN.md b/docs/research/aura-examples/stripe-DESIGN.md new file mode 100644 index 0000000000..3bdd50b70e --- /dev/null +++ b/docs/research/aura-examples/stripe-DESIGN.md @@ -0,0 +1,70 @@ +# Design System + +## Overview +Stripe's visual personality is defined by "High-Fidelity Minimalism." The system uses high-density information layouts paired with ethereal, animated gradients (the signature "mesh gradient" look). It strikes a balance between professional financial infrastructure and cutting-edge software engineering. Key characteristics include extreme typographic precision, fluid motion cues (the hero "wave"), and a layered UI approach that simulates physical depth through soft shadows and sophisticated border treatments. The layout is structured on a strict grid with significant responsive adaptations, transitioning from dense 12-column desktop views to simplified vertical stacks on mobile. + +## Colors + +### Brand & Core +- **Primary Brand**: #635bff (Stripe Purple / Brand 500) +- **Text Solid**: #0a2540 (Dark Navy) +- **Text Soft**: #424770 (Slate Blue) +- **Background Subdued**: #f6f9fc (Light Gray/Blue tint) +- **White**: #ffffff + +### Semantic & Accents +- **Action Text**: #00d4ff (Electric Blue accent) +- **Accent Magenta**: #ea2261 (Connect product accent) +- **Accent Orange**: #ff6118 (Payments/Agentic accent) +- **Accent Yellow**: #fc5 (Billing/Startups accent) +- **Border Quiet**: #e6ebf1 (Soft UI borders) + +## Typography +- **Primary Font**: Sohne-var (Custom sans-serif). Used for all body and headings. Characteristics: Geometric but legible, varied weights from 300 (Light) to 700 (Bold). +- **Code Font**: SourceCodePro (Monospace). Used for API references and developer-centric components. +- **Hierarchy**: + - **Hero Title**: Variable sizing (max-width 32ch), ~3.5rem on desktop, tight line-height (1.15). + - **Section Headings**: `hds-heading--lg` (~2rem desktop), `hds-heading--md` (~1.625rem). + - **Body Text**: `hds-font-text-md` (~0.875rem to 1rem) with high tracking/line-height for readability (1.4). + +## Elevation +- **Surface Layering**: Uses `isolation: isolate` to manage complex animated background layers. +- **Shadows**: + - `hds-shadow-md`: 0 6px 22px rgba(0, 55, 112, 0.1) for floating cards. + - `hds-canary-ui-shadow`: 0 16px 32px rgba(50, 50, 93, 0.12) for dashboard-style graphic cards. +- **Borders**: Heavy reliance on 1px solid or dashed borders (`1px dashed #e5edf5`) instead of heavy shadows for separating content sections. + +## Components +- **Navigation**: A sophisticated mega-menu with blur effects (`backdrop-filter: blur(5px)`) and animated chevron transitions. +- **Bento Cards**: Interactive grid items with localized gradient "blobs" (`--bento-left-blob`) and nested graphics. +- **Logo Carousel**: A continuous marquee featuring SVG partner logos with grayscale-to-color hover transitions. +- **Interactive Graphics**: Pseudo-dashboard UI components (Tax, Invoicing, Connect) that use CSS transforms and absolute positioning to simulate product interfaces. +- **Buttons**: + - **Primary**: Solid background with a slight pill-shape border-radius. + - **Secondary**: Ghost style with `hds-icon-hover-arrow` that animates on hover. + +## Do's and Don'ts +- **Do**: Use 1px dashed borders to separate high-level footer categories. +- **Do**: Apply `text-wrap: pretty` or `balance` to headings to prevent widows. +- **Don't**: Use generic drop shadows; use the specific color-mixed elevations defined in the HDS system. +- **Do**: Use subtle mesh gradients in background layers to provide depth without distracting from text. +- **Don't**: Overcomplicate mobile layouts; collapse multi-column desktop grids into single-column stacks. + +## Assets + +### Fonts +- **Sohne Variable**: https://b.stripecdn.com/mkt-ssr-statics/assets/_next/static/media/Sohne.cb178166.woff2 +- **Source Code Pro**: https://b.stripecdn.com/mkt-ssr-statics/assets/_next/static/media/SourceCodePro-Medium.f5ba3e6a.woff2 +- **Sohne (Alt Path)**: https://stripe.com/mkt-ssr-statics/assets/_next/static/media/Sohne.cb178166.woff2 +- **Source Code Pro (Alt Path)**: https://stripe.com/mkt-ssr-statics/assets/_next/static/media/SourceCodePro-Medium.f5ba3e6a.woff2 + +### Images +- **Personalize Background**: https://images.ctfassets.net/fzn2n1nzq965/243SyQMmyCkQOj9SIYcV9m/9ca6154f96e65aa92bb35401e70f3725/Frame_2147247494.png +- **Decagon Logo**: https://images.stripeassets.com/fzn2n1nzq965/1hreJwxuVJ5ucPtuA7pRKH/3c5630387bca898d01ae17fc7ae2890a/decagon.png?w=432&fm=webp&q=90 +- **Connect Bento Background**: https://images.stripeassets.com/fzn2n1nzq965/1j4wM9h2bBsyRFvTv6Wsn0/07f4b9b1e1e17fdc509d9087454dd8bc/ConnectBentoBackground.jpg?w=1242&fm=webp&q=90 +- **Agentic Mobile Graphic**: https://images.stripeassets.com/fzn2n1nzq965/1k7ckFceNFlxqF47hWJUlM/eaa4d8b3f8e4b76ba3dd7df7da88e099/the-happenings-agentic-mobile.png?w=336&fm=webp&q=90 +- **Browserbase Case Study**: https://images.stripeassets.com/fzn2n1nzq965/1NiQJZA0rKbwXZ7mD4BCrM/0abdaba77e564f858a33241a9aab0939/browserbase.png?w=432&fm=webp&q=90 +- **The Quincunx Book Cover**: https://images.stripeassets.com/fzn2n1nzq965/2gq7OxrRa1Ee5L8uFUX75n/2398783b25e6c09d095a94e8bae4b1e4/TheQuincunx.png?w=296&fm=webp&q=90 +- **Connect Mobile Background**: https://images.stripeassets.com/fzn2n1nzq965/43eqkFV1GG5GqcbNNeEzVp/8f4705b1b80a4c835c2960ed8055d649/ConnectMobileBackground.jpg?w=1104&fm=webp&q=90 +- **Sessions Banner**: https://images.stripeassets.com/fzn2n1nzq965/5cRV5XgALGMWv62qKuH0Rw/f0429f90b5731f51c44c47b187626bbd/sessions-banner-background_2x.png?w=1232&fm=webp&q=90 +- **Retailers Mobile Graphic**: https://images.stripeassets.com/fzn2n1nzq965/7EVLwfXmG3pl1vhBssMrFB/b6d8612b1f567922c1355d864c279678/the-happenings-payment-retailers-mobile.png?w=336&fm=webp&q=90 diff --git a/docs/research/reverse-engineered-aura-system-prompt.md b/docs/research/reverse-engineered-aura-system-prompt.md new file mode 100644 index 0000000000..cf7b2fba61 --- /dev/null +++ b/docs/research/reverse-engineered-aura-system-prompt.md @@ -0,0 +1,121 @@ +# Reverse-Engineered Aura System Instructions + +> Based on analysis of Aura.build outputs (code.html for Notion, code2.html for Soulscape), +> the Aura AI's own statement about its system instructions, and the Prompt Builder categories. + +## The Prompt (Estimated) + +``` +You generate single-file HTML implementations of websites from screenshots and design references. + +## Output Format +- Single HTML file. Start with , end with . +- No markdown wrapping. No code fences. No explanation or commentary. +- Clean, well-indented, semantic HTML5 with descriptive comments for each section. +- Target: 400-800 lines for a full page. + +## Tech Stack (use EXACTLY this — no substitutions) +- Tailwind CSS: +- Icons: with elements. Call lucide.createIcons() once at the end of . For dark/cinematic designs, use Iconify with and elements instead. +- Google Fonts: tag in for typeface matching. Only load the weights you actually use. +- For fonts NOT on Google Fonts: use @font-face with the exact URL from the DESIGN.md Assets section. + +## Tailwind Usage Rules +- Use Tailwind utility classes for ALL styling. Do NOT write custom CSS classes except for: + - @font-face declarations (when needed) + - @keyframes (ONLY if Tailwind's arbitrary animation syntax cannot express it) + - Complex CSS-only interactions (accordion hover effects) +- Use tailwind.config to extend colors, fonts, animations, and keyframes for the specific site's design tokens. Define these in a and tailwind.config. +- Keep Lucide icons with and lucide.createIcons(). +- Use real image URLs from the DESIGN.md Assets section for ALL visible images, company logos, headshots. NEVER use text spans or gray rectangles as placeholders. +- Use EXACT text from the original — do NOT paraphrase or fabricate. +- ZERO JavaScript functions. CSS-only animations. +- Every section must be visible on page load. + +Focus on fixing: +- Missing or wrong sections +- Wrong colors, fonts, spacing +- Missing images that should use DESIGN.md asset URLs +- Company logos that are text instead of real tags +- Layout/alignment differences +- Missing icons + +Output ONLY the complete corrected HTML. Start with , end with . No explanation. + +DESIGN.md for asset reference: + +${designMd}`; + + let refinedHtml = ""; + + if (useGemini) { + const { GoogleGenAI } = await import("@google/genai"); + const genai2 = new GoogleGenAI({ apiKey: geminiKey! }); + const refParts: Array< + { inlineData: { mimeType: string; data: string } } | { text: string } + > = [ + { inlineData: { mimeType: "image/png", data: origB64 } }, + { inlineData: { mimeType: "image/png", data: replicaB64 } }, + { text: refinementPrompt }, + ]; + const refResponse = await genai2.models.generateContent({ + model: "gemini-3.1-pro-preview", + contents: [{ role: "user", parts: refParts }], + config: { thinkingConfig: { thinkingBudget: 10000 } }, + }); + refinedHtml = refResponse.text ?? ""; + } else { + const { default: Anthropic } = await import("@anthropic-ai/sdk"); + const client2 = new Anthropic({ apiKey: anthropicKey! }); + const refStream = await client2.messages.stream({ + model: "claude-sonnet-4-20250514", + max_tokens: 32000, + messages: [ + { + role: "user", + content: [ + { + type: "image" as const, + source: { + type: "base64" as const, + media_type: "image/png" as const, + data: origB64, + }, + }, + { + type: "image" as const, + source: { + type: "base64" as const, + media_type: "image/png" as const, + data: replicaB64, + }, + }, + { type: "text" as const, text: refinementPrompt }, + ], + }, + ], + system: "Output ONLY raw HTML. No markdown, no code fences, no explanation.", + }); + for await (const event of refStream) { + if (event.type === "content_block_delta" && event.delta.type === "text_delta") { + refinedHtml += event.delta.text; + } + } + } + + const refinedResult = extractHtmlFromResponse(refinedHtml); + if (refinedResult) { + writeFileSync(outputPath, refinedResult, "utf-8"); + const refinedKb = (Buffer.byteLength(refinedResult) / 1024).toFixed(0); + onProgress?.(`Replica refined (${refinedKb} KB)`); + } else { + onProgress?.("Refinement returned invalid HTML — keeping original"); + } + } else { + onProgress?.( + `Original screenshot too large for refinement (${(origBuf.length / 1024 / 1024).toFixed(1)} MB)`, + ); + } + } else { + onProgress?.("No original screenshot available for refinement comparison"); + } + } catch (err) { + const msg = err instanceof Error ? err.message : String(err); + onProgress?.(`Refinement error: ${msg.slice(0, 200)}`); + } + + return "replica.html"; +} + +function extractHtmlFromResponse(text: string): string | null { + // Extract HTML from markdown code block if wrapped + const codeBlockMatch = text.match(/```html\n([\s\S]*?)```/); + if (codeBlockMatch) { + text = codeBlockMatch[1]!; + } + if (!text.includes(", end with . +- No markdown wrapping. No code fences. No explanation or commentary. +- Clean, well-indented, semantic HTML5 with comments marking each section. +- Target 500-900 lines for a full page. + +TECH STACK (use EXACTLY this): +- Tailwind CSS: +- Extend tailwind.config with the site's exact design tokens (colors, fonts, animations, keyframes). +- Icons: with . Call lucide.createIcons() once at end of . For dark/cinematic sites, use Iconify Solar icons instead. +- Google Fonts via in for typography. For fonts not on Google Fonts, use @font-face with the URL from DESIGN.md Assets. +- CSS @keyframes for marquee/continuous animations defined in tailwind.config or