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:
ularkim
2026-04-15 14:05:01 -04:00
co-authored by Claude Opus 4.6
parent a67753e433
commit 4ecd8fcaed
13 changed files with 1490 additions and 23 deletions
@@ -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 |" : ""}
+12 -6
View File
@@ -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 {
+143
View File
@@ -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) {