mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-20 03:47:38 +00:00
docs: add skill architecture redesign spec
Comprehensive redesign of website-to-hyperframes skill and capture pipeline based on code review findings and Claude Code architecture research. Key changes: remove AI auto-generation, restructure skill into phases, embed shader boilerplate in scaffold, fix color format. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
co-authored by
Claude Opus 4.6
parent
a67753e433
commit
4ecd8fcaed
@@ -10,6 +10,7 @@ import { writeFileSync } from "node:fs";
|
||||
import { join } from "node:path";
|
||||
import type { DesignTokens } from "./types.js";
|
||||
import type { AnimationCatalog } from "./animationCataloger.js";
|
||||
import type { CatalogedAsset } from "./assetCataloger.js";
|
||||
|
||||
export function generateAgentPrompt(
|
||||
outputDir: string,
|
||||
@@ -20,6 +21,7 @@ export function generateAgentPrompt(
|
||||
hasDesignMd: boolean,
|
||||
hasLottie?: boolean,
|
||||
hasShaders?: boolean,
|
||||
catalogedAssets?: CatalogedAsset[],
|
||||
): void {
|
||||
const prompt = buildPrompt(
|
||||
url,
|
||||
@@ -29,6 +31,7 @@ export function generateAgentPrompt(
|
||||
hasDesignMd,
|
||||
hasLottie,
|
||||
hasShaders,
|
||||
catalogedAssets,
|
||||
);
|
||||
writeFileSync(join(outputDir, "CLAUDE.md"), prompt, "utf-8");
|
||||
writeFileSync(join(outputDir, ".cursorrules"), prompt, "utf-8");
|
||||
@@ -42,6 +45,7 @@ function buildPrompt(
|
||||
hasDesignMd: boolean,
|
||||
hasLottie?: boolean,
|
||||
hasShaders?: boolean,
|
||||
catalogedAssets?: CatalogedAsset[],
|
||||
): string {
|
||||
const hostname = new URL(url).hostname.replace(/^www\./, "");
|
||||
const title = tokens.title || hostname;
|
||||
@@ -53,6 +57,13 @@ function buildPrompt(
|
||||
const headingCount = tokens.headings?.length ?? 0;
|
||||
const ctaCount = tokens.ctas?.length ?? 0;
|
||||
|
||||
const videoUrls = catalogedAssets
|
||||
? catalogedAssets
|
||||
.filter((a) => a.type === "Video" && a.url.startsWith("http"))
|
||||
.map((a) => a.url)
|
||||
.filter((u, i, arr) => arr.indexOf(u) === i) // deduplicate
|
||||
: [];
|
||||
|
||||
return `# ${title} — Captured Website
|
||||
|
||||
Source: ${url}
|
||||
@@ -73,8 +84,9 @@ ${hasScreenshot ? "| `screenshots/full-page.png` | Full-page screenshot of the w
|
||||
| \`extracted/assets-catalog.json\` | Every asset URL (images, fonts, videos, icons) with HTML context |
|
||||
| \`extracted/animations.json\` | Animation catalog: ${animations?.summary?.webAnimations ?? 0} web animations, ${animations?.summary?.scrollTargets ?? 0} scroll triggers, ${animations?.summary?.canvases ?? 0} canvases |
|
||||
| \`assets/svgs/\` | Extracted inline SVGs (logos, icons, illustrations) |
|
||||
| \`assets/\` | Downloaded images and font files |
|
||||
| \`assets/\` | Downloaded images and font files — **Read every image file to see what it contains** |
|
||||
${hasLottie ? "| `extracted/lottie-manifest.json` | Lottie animations found on this site — read this to see what animations are available (name, dimensions, duration). Embed via `lottie.loadAnimation({ path: 'assets/lottie/animation-0.json' })`. Do NOT read the raw JSON files — they are machine data. |" : ""}
|
||||
${videoUrls.length > 0 ? "| `extracted/video-manifest.json` | Video manifest: every `<video>` element with its URL, surrounding heading/caption context, and a preview screenshot. **Read this + view each preview image** to understand what each video shows before using it. |" : ""}
|
||||
${hasShaders ? "| `extracted/shaders.json` | Captured WebGL shader source code (GLSL vertex + fragment shaders) |" : ""}
|
||||
${hasDesignMd ? "| `DESIGN.md` | AI-generated design system reference |" : ""}
|
||||
|
||||
|
||||
@@ -63,20 +63,21 @@ export async function downloadAssets(
|
||||
if (catalogedAssets && catalogedAssets.length > 0) {
|
||||
// Use catalog — already deduplicated with highest-res srcset variants
|
||||
for (const a of catalogedAssets) {
|
||||
if (a.type !== "Image") continue;
|
||||
if (a.type !== "Image" && a.type !== "Background") continue;
|
||||
if (!a.url.startsWith("http")) continue;
|
||||
// Skip junk
|
||||
if (a.url.includes("pixel") || a.url.includes("beacon") || a.url.includes("analytics"))
|
||||
continue;
|
||||
if (a.url.includes("/favicon")) continue;
|
||||
// Only download images from meaningful contexts
|
||||
// Download images from standard img/video contexts + CSS backgrounds (for hero sections, feature illustrations)
|
||||
const hasGoodContext = a.contexts.some(
|
||||
(c) =>
|
||||
c === "img[src]" ||
|
||||
c === "img[srcset]" ||
|
||||
c === "video[poster]" ||
|
||||
c === "source[srcset]" ||
|
||||
c === "data-src",
|
||||
c === "data-src" ||
|
||||
c === "css url()",
|
||||
);
|
||||
if (!hasGoodContext) continue;
|
||||
const isPoster = a.contexts.includes("video[poster]");
|
||||
@@ -91,11 +92,11 @@ export async function downloadAssets(
|
||||
}
|
||||
}
|
||||
|
||||
// Download up to 25 images in parallel batches, skipping duplicates and tiny files
|
||||
// Pre-filter to deduplicate and cap before downloading
|
||||
// Download all images (no arbitrary cap) — Claude Code needs to see every asset to use them creatively.
|
||||
// The 10KB minimum size filter handles tracking pixels and tiny icons.
|
||||
// Pre-filter to deduplicate before downloading.
|
||||
const toDownload: { url: string; isPoster: boolean; normalized: string }[] = [];
|
||||
for (const { url, isPoster } of imageUrls) {
|
||||
if (toDownload.length >= 25) break;
|
||||
const normalized = normalizeUrl(url);
|
||||
if (downloadedUrls.has(normalized)) continue;
|
||||
downloadedUrls.add(normalized); // Reserve to prevent duplicates in parallel batches
|
||||
@@ -228,6 +229,11 @@ async function fetchBuffer(url: string): Promise<Buffer | null> {
|
||||
headers: { "User-Agent": "HyperFrames/1.0" },
|
||||
});
|
||||
if (!res.ok) return null;
|
||||
// Reject XML/HTML error pages disguised as 200 OK (common with S3/CloudFront)
|
||||
const ct = res.headers.get("content-type") || "";
|
||||
if (ct.includes("text/xml") || ct.includes("text/html") || ct.includes("application/xml")) {
|
||||
return null;
|
||||
}
|
||||
const ab = await res.arrayBuffer();
|
||||
return Buffer.from(ab);
|
||||
} catch {
|
||||
|
||||
@@ -470,6 +470,148 @@ a.addEventListener('DOMLoaded',function(){a.goToAndStop(${midFrame},true);window
|
||||
warnings.push(`Asset cataloging failed: ${err}`);
|
||||
}
|
||||
|
||||
// Generate video manifest — screenshot each <video> element + extract surrounding context
|
||||
// so Claude Code can SEE what each video shows and WHERE it was used on the page.
|
||||
try {
|
||||
const videoElements = await page1.evaluate(`(() => {
|
||||
var videos = Array.from(document.querySelectorAll('video'));
|
||||
return videos.map(function(v) {
|
||||
var src = v.src || v.currentSrc || (v.querySelector('source') ? v.querySelector('source').src : '');
|
||||
if (!src || !src.startsWith('http')) return null;
|
||||
|
||||
// Get bounding box for screenshot
|
||||
var rect = v.getBoundingClientRect();
|
||||
if (rect.width < 10 || rect.height < 10) return null;
|
||||
|
||||
// Nearest heading above the video
|
||||
var heading = '';
|
||||
var el = v;
|
||||
for (var i = 0; i < 8; i++) {
|
||||
el = el.parentElement;
|
||||
if (!el) break;
|
||||
var h = el.querySelector('h1,h2,h3,h4');
|
||||
if (h) { heading = h.textContent.trim().slice(0, 100); break; }
|
||||
}
|
||||
|
||||
// Nearest paragraph/caption text
|
||||
var caption = '';
|
||||
el = v;
|
||||
for (var j = 0; j < 5; j++) {
|
||||
el = el.parentElement;
|
||||
if (!el) break;
|
||||
var p = el.querySelector('p,figcaption,[class*="caption"],[class*="desc"]');
|
||||
if (p) { caption = p.textContent.trim().slice(0, 200); break; }
|
||||
}
|
||||
|
||||
// aria-label on video or wrapper
|
||||
var ariaLabel = v.getAttribute('aria-label') || v.getAttribute('title') || '';
|
||||
var wrapper = v.parentElement;
|
||||
if (!ariaLabel && wrapper) ariaLabel = wrapper.getAttribute('aria-label') || '';
|
||||
|
||||
return {
|
||||
src: src,
|
||||
width: Math.round(rect.width),
|
||||
height: Math.round(rect.height),
|
||||
top: Math.round(rect.top + window.scrollY),
|
||||
left: Math.round(rect.left),
|
||||
heading: heading,
|
||||
caption: caption,
|
||||
ariaLabel: ariaLabel,
|
||||
filename: src.split('/').pop().split('?')[0],
|
||||
};
|
||||
}).filter(Boolean);
|
||||
})`) as Array<{
|
||||
src: string;
|
||||
width: number;
|
||||
height: number;
|
||||
top: number;
|
||||
left: number;
|
||||
heading: string;
|
||||
caption: string;
|
||||
ariaLabel: string;
|
||||
filename: string;
|
||||
}>;
|
||||
|
||||
// Deduplicate by src
|
||||
const seenSrcs = new Set<string>();
|
||||
const uniqueVideos = videoElements.filter((v) => {
|
||||
if (seenSrcs.has(v.src)) return false;
|
||||
seenSrcs.add(v.src);
|
||||
return true;
|
||||
});
|
||||
|
||||
if (uniqueVideos.length > 0) {
|
||||
const videoManifestDir = join(outputDir, "assets", "videos");
|
||||
mkdirSync(videoManifestDir, { recursive: true });
|
||||
const previewDir = join(videoManifestDir, "previews");
|
||||
mkdirSync(previewDir, { recursive: true });
|
||||
|
||||
const videoManifest: Array<{
|
||||
index: number;
|
||||
url: string;
|
||||
filename: string;
|
||||
width: number;
|
||||
height: number;
|
||||
heading: string;
|
||||
caption: string;
|
||||
ariaLabel: string;
|
||||
preview: string;
|
||||
}> = [];
|
||||
|
||||
for (let vi = 0; vi < uniqueVideos.length && vi < 20; vi++) {
|
||||
const v = uniqueVideos[vi]!;
|
||||
const previewName = `video-${vi}-preview.png`;
|
||||
const previewPath = join(previewDir, previewName);
|
||||
|
||||
// Screenshot the video element to get a visible frame
|
||||
try {
|
||||
await page1.evaluate(`(() => {
|
||||
var vids = Array.from(document.querySelectorAll('video'));
|
||||
vids.forEach(function(v) {
|
||||
if ((v.src || v.currentSrc).includes(${JSON.stringify(v.filename)})) {
|
||||
try { v.play(); v.pause(); } catch(e) {}
|
||||
}
|
||||
});
|
||||
})()`);
|
||||
await page1.screenshot({
|
||||
path: previewPath,
|
||||
clip: {
|
||||
x: Math.max(0, v.left),
|
||||
y: Math.max(0, v.top),
|
||||
width: Math.min(v.width, 1920),
|
||||
height: Math.min(v.height, 1080),
|
||||
},
|
||||
});
|
||||
} catch {
|
||||
/* preview failed — non-critical */
|
||||
}
|
||||
|
||||
videoManifest.push({
|
||||
index: vi,
|
||||
url: v.src,
|
||||
filename: v.filename,
|
||||
width: v.width,
|
||||
height: v.height,
|
||||
heading: v.heading,
|
||||
caption: v.caption,
|
||||
ariaLabel: v.ariaLabel,
|
||||
preview: `assets/videos/previews/${previewName}`,
|
||||
});
|
||||
}
|
||||
|
||||
if (videoManifest.length > 0) {
|
||||
writeFileSync(
|
||||
join(outputDir, "extracted", "video-manifest.json"),
|
||||
JSON.stringify(videoManifest, null, 2),
|
||||
"utf-8",
|
||||
);
|
||||
progress("design", `${videoManifest.length} video previews captured`);
|
||||
}
|
||||
}
|
||||
} catch {
|
||||
/* non-blocking — video manifest is best-effort */
|
||||
}
|
||||
|
||||
// Detect JS libraries via globals, DOM fingerprints, and script URLs
|
||||
let detectedLibraries: string[] = [];
|
||||
try {
|
||||
@@ -813,6 +955,7 @@ a.addEventListener('DOMLoaded',function(){a.goToAndStop(${midFrame},true);window
|
||||
!!hasAiKey,
|
||||
discoveredLotties.length > 0,
|
||||
existsSync(join(outputDir, "extracted", "shaders.json")),
|
||||
catalogedAssets,
|
||||
);
|
||||
progress("agent", "CLAUDE.md generated");
|
||||
} catch (err) {
|
||||
|
||||
Reference in New Issue
Block a user