@su-record/vibe 2.16.0 → 2.16.2

package/hooks/scripts/clone-extract.js

@@ -11,6 +11,7 @@
  *   computed.json        — per-element computed CSS + box + pseudo-elements + shadow DOM
  *   screenshot.png       — full-page screenshot
  *   stylesheets.json     — @font-face + @keyframes harvested from all sheets
+ *   states.json          — non-default state rules (hover/focus/active/checked/tab/aria/data-state)
  *   asset-map.json       — remote URL → local path mapping
  *   assets/images/*, assets/fonts/*
  *
@@ -233,8 +234,32 @@ const PAGE_EXTRACT = `
 (function (props) {
   const out = [];
   const stylesheets = { fontFaces: [], keyframes: [], cssVars: {} };
+  const stateRules = [];
   const pathById = new Map();
 
+  // ── Non-default state rule harvesting (hover/focus/active/checked/tab/aria/data-state) ──
+  // Deterministic: read state-dependent declarations straight from the stylesheets
+  // (no scripted clicking/hovering, so the output stays reproducible).
+  const propSet = new Set(props);
+  const STATE_RE = /:hover|:focus(?:-visible|-within)?|:active|:checked|:target|\\[aria-(?:expanded|selected|current|pressed)|\\[data-(?:state|active|open|selected)|\\[open\\]|\\.is-[a-z-]+|\\.(?:active|open|selected|expanded|current|show|visible)(?![\\w-])/i;
+  const harvestStateRule = (rule, media) => {
+    if (rule.selectorText && STATE_RE.test(rule.selectorText)) {
+      const decl = {};
+      for (let i = 0; i < rule.style.length; i++) {
+        const p = rule.style[i];
+        if (propSet.has(p)) decl[p] = rule.style.getPropertyValue(p).trim();
+      }
+      if (Object.keys(decl).length && stateRules.length < 1200) {
+        stateRules.push({ selector: rule.selectorText.trim(), media: media || null, css: decl });
+      }
+    }
+    // Recurse @media / @supports blocks so state rules nested under them are not lost
+    if (rule.cssRules && (rule.media || rule.conditionText)) {
+      const mq = rule.media ? rule.media.mediaText : (media || null);
+      for (const r of rule.cssRules) harvestStateRule(r, mq);
+    }
+  };
+
   // Stable ID via DOM path (no attribute mutation)
   const pathFor = (el, parent) => {
     if (!parent) return '0';
@@ -469,6 +494,7 @@ const PAGE_EXTRACT = `
         stylesheets.keyframes.push({ name: rule.name, frames });
       }
     }
+    for (const rule of rules) harvestStateRule(rule, null);
   }
 
   // :root CSS vars
@@ -484,6 +510,7 @@ const PAGE_EXTRACT = `
     nodes: out,
     assets: { images: Array.from(images), fonts: Array.from(fonts) },
     stylesheets,
+    stateRules,
     title: document.title,
     html: document.documentElement.outerHTML,
     docSize: {
@@ -592,7 +619,9 @@ async function capture({ url, opts }) {
 
     await freezeAnimations(page);
 
-    const extracted = await page.evaluate(PAGE_EXTRACT, CSS_PROPS);
+    // PAGE_EXTRACT is a parenthesized function-expression string. page.evaluate treats a
+    // string arg as an expression and ignores extra args, so build the call ourselves.
+    const extracted = await page.evaluate(`(${PAGE_EXTRACT})(${JSON.stringify(CSS_PROPS)})`);
 
     // Screenshot AFTER freezing animations
     const shotPath = path.join(opts.out, 'screenshot.png');
@@ -666,6 +695,14 @@ async function capture({ url, opts }) {
       });
     }
 
+    // Rewrite remote asset URLs inside harvested state rules (e.g. :hover background-image)
+    for (const sr of extracted.stateRules) {
+      if (!sr.css) continue;
+      for (const prop of ['background-image', 'mask-image', 'border-image']) {
+        if (sr.css[prop]) sr.css[prop] = rewriteCssValue(sr.css[prop]);
+      }
+    }
+
     // Write outputs
     fs.writeFileSync(path.join(opts.out, 'rendered.html'), html);
     fs.writeFileSync(
@@ -686,11 +723,18 @@ async function capture({ url, opts }) {
       path.join(opts.out, 'stylesheets.json'),
       JSON.stringify(extracted.stylesheets, null, 2),
     );
+    fs.writeFileSync(
+      path.join(opts.out, 'states.json'),
+      JSON.stringify({
+        meta: { url, bp: opts.bp || null, capturedAt: new Date().toISOString() },
+        stateRules: extracted.stateRules,
+      }, null, 2),
+    );
     fs.writeFileSync(path.join(opts.out, 'asset-map.json'), JSON.stringify(assetMap, null, 2));
 
     const okCount = Object.values(assetMap).filter((a) => a.status === 'ok').length;
     console.log(`[clone-extract] done → ${opts.out}`);
-    console.log(`  nodes: ${extracted.nodes.length}, fontFaces: ${extracted.stylesheets.fontFaces.length}`);
+    console.log(`  nodes: ${extracted.nodes.length}, fontFaces: ${extracted.stylesheets.fontFaces.length}, stateRules: ${extracted.stateRules.length}`);
     console.log(`  assets: ${okCount}/${Object.keys(assetMap).length} downloaded`);
   } finally {
     await browser.close();

package/hooks/scripts/clone-refine.js

@@ -29,6 +29,7 @@ function parseArgs(argv) {
     else if (a.startsWith('--bp=')) opts.bp = a.slice(5);
     else if (a.startsWith('--stylesheets=')) opts.stylesheets = a.slice(14);
     else if (a.startsWith('--asset-map=')) opts.assetMap = a.slice(12);
+    else if (a.startsWith('--states=')) opts.states = a.slice(9);
   }
   return { htmlPath, computedPath, opts };
 }
@@ -452,6 +453,131 @@ function applyTokens(nodes, tokens) {
   for (const n of nodes) walkAndApply(n);
 }
 
+// ─── Interaction model classification (static-DOM heuristic) ────────
+// The live interaction (#1 clone failure mode) cannot be fully known from a
+// static snapshot, so we surface ranked SIGNALS + a best-guess model that the
+// builder confirms against the live site in Phase 5 — never a silent decision.
+const CAROUSEL_RE = /slider|carousel|swiper|marquee|slick|embla|ticker|autoplay/;
+const SCROLL_RE = /parallax|reveal|animate-on-scroll|scroll-|sticky|fade-in|fade-up|slide-in|in-view|gsap|lenis|locomotive/;
+const TOGGLE_RE = /accordion|tabs?|dropdown|modal|toggle|menu|collaps|drawer|popover|expand|hamburger/;
+const INTERACTIVE_TAGS = new Set(['button', 'summary', 'details', 'input', 'select', 'textarea', 'label']);
+const TOGGLE_ROLES = new Set(['tab', 'tablist', 'switch', 'menuitem', 'menuitemcheckbox', 'button']);
+
+function firstClass(cls, re) {
+  return (cls || '').split(/\s+/).find((c) => re.test(c)) || null;
+}
+
+function collectInteractionSignals(root) {
+  const sig = {
+    sticky: null, anim: null, infinite: null, transition: false, pointer: false,
+    interactiveTag: null, toggleClass: null, scrollClass: null, carouselClass: null, toggleRole: null,
+  };
+  const visit = (n) => {
+    const css = n.css || {};
+    const cls = (n.classes || '').toLowerCase();
+    const role = ((n.attrs && n.attrs.role) || '').toLowerCase();
+    if (!sig.sticky && (css.position === 'sticky' || css.position === 'fixed')) sig.sticky = `${css.position} on <${n.tag}>`;
+    if (css.animation) { sig.anim = sig.anim || n.tag; if (/infinite/.test(css.animation)) sig.infinite = sig.infinite || `animation infinite on <${n.tag}>`; }
+    if (css.transition) sig.transition = true;
+    if (css.cursor === 'pointer') sig.pointer = true;
+    if (!sig.interactiveTag && (INTERACTIVE_TAGS.has(n.tag) || (n.tag === 'a' && n.attrs && n.attrs.href))) sig.interactiveTag = n.tag;
+    sig.carouselClass = sig.carouselClass || firstClass(cls, CAROUSEL_RE);
+    sig.scrollClass = sig.scrollClass || firstClass(cls, SCROLL_RE);
+    sig.toggleClass = sig.toggleClass || firstClass(cls, TOGGLE_RE);
+    if (!sig.toggleRole && TOGGLE_ROLES.has(role)) sig.toggleRole = role;
+    for (const c of (n.children || [])) visit(c);
+  };
+  visit(root);
+  return sig;
+}
+
+function interactionSignalList(sig) {
+  const s = [];
+  if (sig.infinite) s.push(sig.infinite);
+  if (sig.carouselClass) s.push(`carousel class ".${sig.carouselClass}"`);
+  if (sig.scrollClass) s.push(`scroll class ".${sig.scrollClass}"`);
+  if (sig.sticky) s.push(sig.sticky);
+  if (sig.toggleClass) s.push(`toggle class ".${sig.toggleClass}"`);
+  if (sig.toggleRole) s.push(`role="${sig.toggleRole}"`);
+  if (sig.interactiveTag) s.push(`<${sig.interactiveTag}>`);
+  if (sig.anim) s.push(`animation on <${sig.anim}>`);
+  if (sig.transition) s.push('css transition');
+  if (sig.pointer) s.push('cursor:pointer');
+  return s.slice(0, 8);
+}
+
+function decideInteraction(sig) {
+  let model = 'static';
+  let confidence = 'low';
+  if (sig.infinite || sig.carouselClass) {
+    model = 'time-driven';
+    confidence = (sig.infinite || /swiper|slick|embla|carousel/.test(sig.carouselClass || '')) ? 'high' : 'medium';
+  } else if (sig.scrollClass || (sig.sticky && (sig.anim || sig.transition))) {
+    model = 'scroll-driven';
+    confidence = sig.scrollClass ? 'medium' : 'low';
+  } else if (sig.interactiveTag === 'details' || sig.toggleRole === 'tab' || sig.toggleClass) {
+    model = 'click-driven';
+    confidence = (sig.interactiveTag === 'details' || sig.toggleRole === 'tab') ? 'high' : 'medium';
+  } else if (sig.interactiveTag || sig.toggleRole) {
+    model = 'click-driven';
+    confidence = 'medium';
+  } else if (sig.pointer && sig.transition) {
+    model = 'hover';
+    confidence = 'medium';
+  }
+  return {
+    model,
+    confidence,
+    signals: interactionSignalList(sig),
+    note: 'Static-DOM heuristic — confirm the real interaction on the live site (Phase 5).',
+  };
+}
+
+// ─── State rule matching: attach harvested state rules to their section ─────
+const LEAF_INTERACTIVE = ['button', 'a', 'input', 'summary', 'details', 'label', 'select'];
+
+// Match a bare tag at a selector boundary (so `a:hover` matches but `.cta:hover` does not)
+const _tagSelCache = {};
+function tagSelRe(t) {
+  return _tagSelCache[t] || (_tagSelCache[t] = new RegExp('(^|[\\s>+~,(])' + t + '(?=[:.\\[\\s>+~,)]|$)'));
+}
+
+function collectClassTagSets(root) {
+  const classSet = new Set();
+  const tagSet = new Set();
+  const visit = (n) => {
+    tagSet.add(n.tag);
+    for (const c of (n.classes || '').split(/\s+/)) if (c) classSet.add(c.toLowerCase());
+    for (const c of (n.children || [])) visit(c);
+  };
+  visit(root);
+  return { classArr: Array.from(classSet), tagSet };
+}
+
+function sectionStateRules(stateRules, classArr, tagSet, limit = 60) {
+  if (!stateRules || !stateRules.length) return [];
+  const picked = [];
+  for (const sr of stateRules) {
+    const sel = sr.selector.toLowerCase();
+    const classHit = classArr.some((c) => sel.includes('.' + c));
+    const tagHit = !classHit && LEAF_INTERACTIVE.some((t) => tagSet.has(t) && tagSelRe(t).test(sel));
+    if (classHit || tagHit) {
+      picked.push({ selector: sr.selector, media: sr.media || null, css: sr.css });
+      if (picked.length >= limit) break;
+    }
+  }
+  return picked;
+}
+
+function loadStateRules() {
+  const statesPath = opts.states || path.join(path.dirname(computedPath), 'states.json');
+  try {
+    return JSON.parse(fs.readFileSync(statesPath, 'utf8')).stateRules || [];
+  } catch {
+    return [];
+  }
+}
+
 // ─── Main ───────────────────────────────────────────────────────────
 function main() {
   const computed = JSON.parse(fs.readFileSync(computedPath, 'utf8'));
@@ -462,13 +588,17 @@ function main() {
 
   // Section detection
   const sectionEntries = findSections(roots);
-  console.log(`[clone-refine] detected ${sectionEntries.length} sections, ${tokens.colors.length} colors, ${tokens.typography.length} typo, ${tokens.spacing.length} spacings`);
+  const stateRules = loadStateRules();
+  console.log(`[clone-refine] detected ${sectionEntries.length} sections, ${tokens.colors.length} colors, ${tokens.typography.length} typo, ${tokens.spacing.length} spacings, ${stateRules.length} state rules`);
 
   // Build refined sections
   const sections = sectionEntries.map(({ node, label }) => {
     const subtree = trimSubtree(node);
     const components = detectComponents(node);
     const images = classifyImages(node);
+    const interaction = decideInteraction(collectInteractionSignals(node));
+    const { classArr, tagSet } = collectClassTagSets(node);
+    const states = sectionStateRules(stateRules, classArr, tagSet);
     return {
       name: label,
       nodeRef: node.id,
@@ -476,8 +606,10 @@ function main() {
       classes: node.classes,
       box: node.box,
       css: node.css || {},
+      interaction,
       components,
       images,
+      states,
       children: (subtree.children || []),
     };
   });

package/hooks/scripts/clone-spec.js

@@ -0,0 +1,186 @@
+#!/usr/bin/env node
+
+/**
+ * clone-spec.js — sections.json → per-section build-contract spec (*.spec.md)
+ *
+ * Usage:
+ *   node clone-spec.js <sections.json> --out=<dir> [--section=Name] [--feature=name]
+ *
+ * Why this exists (clone Phase 3, Step 0 — the spec gate):
+ *   No section is built without a completed spec. The spec is the contract AND the
+ *   audit trail: it forces extraction rigor (interaction model, states, assets, text,
+ *   computed CSS) into a single reviewable file before any component code is written.
+ *   Generated deterministically from sections.json — Claude fills the TODOs, never guesses.
+ *
+ * Output (in <dir>):
+ *   <Section>.spec.md   — one contract per detected section
+ */
+
+import fs from 'fs';
+import path from 'path';
+
+// ─── CLI ────────────────────────────────────────────────────────────
+function parseArgs(argv) {
+  const [, , sectionsPath, ...rest] = argv;
+  const opts = {};
+  for (const a of rest) {
+    if (a.startsWith('--out=')) opts.out = a.slice(6);
+    else if (a.startsWith('--section=')) opts.section = a.slice(10);
+    else if (a.startsWith('--feature=')) opts.feature = a.slice(10);
+  }
+  return { sectionsPath, opts };
+}
+
+const { sectionsPath, opts } = parseArgs(process.argv);
+if (!sectionsPath || !opts.out) {
+  console.error('Usage: node clone-spec.js <sections.json> --out=<dir> [--section=Name] [--feature=name]');
+  process.exit(1);
+}
+
+// ─── Helpers ────────────────────────────────────────────────────────
+function safeName(name) {
+  return (name || 'Section').replace(/[^a-zA-Z0-9_-]/g, '-');
+}
+
+function collectText(section, limit = 25) {
+  const texts = [];
+  const seen = new Set();
+  const visit = (n) => {
+    if (n.text) {
+      const t = n.text.length > 120 ? n.text.slice(0, 120) + '…' : n.text;
+      if (!seen.has(t)) { seen.add(t); texts.push(t); }
+    }
+    for (const c of (n.children || [])) visit(c);
+  };
+  for (const c of (section.children || [])) visit(c);
+  return texts.slice(0, limit);
+}
+
+function cssBlock(css) {
+  const entries = Object.entries(css || {}).filter(([k]) => k !== '--vars');
+  if (!entries.length) return '(none captured)';
+  return entries.map(([k, v]) => `${k}: ${v};`).join('\n');
+}
+
+function interactionBlock(it) {
+  if (!it) return '- **Heuristic guess:** `unknown`\n';
+  const signals = (it.signals || []).length
+    ? it.signals.map((s) => `  - ${s}`).join('\n')
+    : '  - (no interaction signals detected — likely static)';
+  return [
+    `- **Heuristic guess:** \`${it.model}\` (confidence: ${it.confidence})`,
+    `- **Signals detected:**`,
+    signals,
+    `- **Confirmed model:** TODO — verify on the live site, then record the final model.`,
+    `- **Trigger & transition:** TODO — exact trigger (click/scroll/hover/time), duration, easing.`,
+  ].join('\n');
+}
+
+function statesBlock(states) {
+  if (!states || !states.length) {
+    return '- None harvested. TODO: confirm there are truly no hover/focus/active/open states.';
+  }
+  return states.map((sr) => {
+    const decls = Object.entries(sr.css || {}).map(([k, v]) => `    - ${k}: ${v}`).join('\n');
+    const media = sr.media ? ` _(under \`@media ${sr.media}\`)_` : '';
+    return `- \`${sr.selector}\`${media}\n${decls}`;
+  }).join('\n');
+}
+
+function componentsBlock(components) {
+  if (!components || !components.length) return '- None detected.';
+  return components.map((c) => {
+    const cls = c.exemplarClasses ? `.${String(c.exemplarClasses).split(/\s+/).slice(0, 3).join('.')}` : '';
+    return `- \`<${c.exemplarTag}>${cls}\` ×${c.count} → TODO: reuse existing component or create new?`;
+  }).join('\n');
+}
+
+function assetsBlock(images) {
+  const bg = (images && images.bg) || [];
+  const content = (images && images.content) || [];
+  const lines = [];
+  lines.push(bg.length ? `- **background:** ${bg.map((u) => `\`${u}\``).join(', ')}` : '- **background:** none');
+  lines.push(content.length ? `- **content (<img>):** ${content.map((u) => `\`${u}\``).join(', ')}` : '- **content (<img>):** none');
+  return lines.join('\n');
+}
+
+// ─── Spec rendering ─────────────────────────────────────────────────
+function renderSpec(section, meta) {
+  const box = section.box || {};
+  const texts = collectText(section);
+  const textBlock = texts.length
+    ? texts.map((t) => `- "${t}"`).join('\n')
+    : '- (no direct text — likely visual/asset-only section)';
+  return `# ${section.name} — Clone Spec (${meta.bp})
+
+> Auto-generated skeleton from sections.json by clone-spec.js. **This is a build contract.**
+> Complete every \`TODO\` before dispatching the build. No section ships without a completed spec.
+
+- **Feature:** ${meta.feature}
+- **Breakpoint:** ${meta.bp} (${meta.viewport ? `${meta.viewport.width}×${meta.viewport.height}` : '?'})
+- **Source URL:** ${meta.url || '?'}
+- **Node ref:** \`${section.nodeRef}\` · **Root box:** ${Math.round(box.w || 0)}×${Math.round(box.h || 0)} @ (${Math.round(box.x || 0)}, ${Math.round(box.y || 0)})
+
+## Interaction model — ⚠ confirm before building
+${interactionBlock(section.interaction)}
+
+## States to reproduce
+_Harvested non-default state rules (hover/focus/active/checked/tab/aria/data-state). Implement each._
+${statesBlock(section.states)}
+
+## Layout — root computed CSS (use as-is, no guessing)
+\`\`\`css
+${cssBlock(section.css)}
+\`\`\`
+
+## Assets (local paths only — never hotlink)
+${assetsBlock(section.images)}
+
+## Text content (replace copyrighted copy with placeholders)
+${textBlock}
+
+## Component candidates
+${componentsBlock(section.components)}
+
+## Build checklist
+- [ ] HTML semantics + final tags chosen
+- [ ] SCSS via clone-to-scss.js (computed values as-is — no eyeballing)
+- [ ] Every state above implemented
+- [ ] Interaction model confirmed on live site & wired
+- [ ] All assets local (public/images/${meta.feature}/) — no hotlinks
+- [ ] clone-validate.js PASS
+- [ ] Pixel diff ≤ 0.05 (Phase 5)
+`;
+}
+
+// ─── Main ───────────────────────────────────────────────────────────
+function main() {
+  const data = JSON.parse(fs.readFileSync(sectionsPath, 'utf8'));
+  const meta = {
+    feature: opts.feature || (data.meta && data.meta.feature) || 'feature',
+    url: data.meta && data.meta.url,
+    viewport: data.meta && data.meta.viewport,
+    bp: opts.section ? (data.meta && data.meta.bp) : (data.meta && data.meta.bp) || '?',
+  };
+  let sections = data.sections || [];
+  if (opts.section) sections = sections.filter((s) => s.name === opts.section);
+  if (!sections.length) {
+    console.error(`[clone-spec] no sections${opts.section ? ` matching "${opts.section}"` : ''} in ${sectionsPath}`);
+    process.exit(1);
+  }
+
+  fs.mkdirSync(opts.out, { recursive: true });
+  for (const section of sections) {
+    const file = path.join(opts.out, `${safeName(section.name)}.spec.md`);
+    fs.writeFileSync(file, renderSpec(section, meta));
+    console.log(`[clone-spec] wrote ${file}`);
+  }
+  console.log(`[clone-spec] done → ${sections.length} spec(s) in ${opts.out}`);
+}
+
+try { main(); }
+catch (e) {
+  console.error(`[clone-spec] FAIL: ${e.message}`);
+  if (process.env.DEBUG) console.error(e.stack);
+  process.exit(1);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@su-record/vibe",
-  "version": "2.16.0",
+  "version": "2.16.2",
   "description": "AI Coding Framework for Claude Code — 42+ agents, 70 skills, multi-LLM orchestration",
   "type": "module",
   "main": "dist/cli/index.js",

package/skills/clone/SKILL.md

@@ -34,6 +34,13 @@ The rendered DOM is the source of truth for markup. Screenshots are for pixel ve
 4. Do NOT copy textual content verbatim from copyrighted sources for production use.
    This skill is for layout/markup learning ("클론 코딩"). Replace text with placeholders
    or user-provided copy when shipping a real product.
+
+5. Do NOT build a section without confirming its interaction model. The model in
+   sections.json is a static-DOM heuristic — verify scroll-driven vs click-driven vs
+   time-driven vs hover against the live site. Misidentifying it is the #1 clone failure mode.
+
+6. Do NOT ship default-state-only. Implement every harvested state (hover/focus/active/open/
+   tab-switch) from states.json / the section spec.
 ```
 
 ## Full Flow
@@ -43,8 +50,8 @@ Input: a URL (or multiple URLs for multi-page clones)
 
 → Phase 0: Setup (stack detection, feature naming, working dir)
 → Phase 1: Capture (Puppeteer → rendered HTML + computed CSS + screenshots + assets)
-→ Phase 2: Refine (DOM → sections.json per breakpoint)
-→ Phase 3: Scaffold (sections.json → SCSS auto-gen + Claude-authored HTML/components)
+→ Phase 2: Refine (DOM → sections.json per breakpoint; + interaction model + states)
+→ Phase 3: Scaffold (spec gate → SCSS auto-gen + Claude-authored HTML/components)
 → Phase 4: Compile gate
 → Phase 5: Pixel verification loop
 
@@ -55,7 +62,7 @@ Working directory:
   └── tokens.json    — extracted design tokens (colors/fonts/spacing)
 
 Code output: placed directly in the project directory per detected stack
-  components/{feature}/, styles/{feature}/, public/images/{feature}/
+  components/{feature}/, components/{feature}/_specs/, styles/{feature}/, public/images/{feature}/
 ```
 
 ---
@@ -111,6 +118,7 @@ node {{VIBE_PATH}}/hooks/scripts/clone-extract.js capture <URL> \
   ├── rendered.html       — final DOM after JS execution
   ├── computed.json       — per-element computed CSS + bounding box
   ├── screenshot.png      — full-page screenshot
+  ├── states.json         — non-default state rules (hover/focus/active/checked/tab/aria/data-state)
   ├── assets/
   │   ├── images/         — all <img>, background-image, <picture> sources
   │   └── fonts/          — @font-face srcs
@@ -127,6 +135,9 @@ node {{VIBE_PATH}}/hooks/scripts/clone-extract.js capture <URL> \
 5. Download assets in parallel (concurrency=8), preserve original extensions
 6. Rewrite asset URLs in rendered.html and computed.json to local paths
 7. Strip inline analytics/tracking scripts before saving rendered.html
+8. Harvest non-default state rules from all stylesheets → states.json
+   (deterministic: read :hover/:focus/:active/:checked/[aria-*]/[data-state]/.is-*/.active
+    declarations straight from CSS — NO scripted clicking, so output stays reproducible)
 ```
 
 ---
@@ -136,11 +147,12 @@ node {{VIBE_PATH}}/hooks/scripts/clone-extract.js capture <URL> \
 ### BLOCKING Command — Writing custom refine scripts is forbidden
 
 ```bash
-# MO
+# MO  (--states is optional — auto-resolved as states.json next to computed.json)
 node {{VIBE_PATH}}/hooks/scripts/clone-refine.js \
   /tmp/{feature}/mo/rendered.html \
   /tmp/{feature}/mo/computed.json \
   --out=/tmp/{feature}/mo/sections.json \
+  --states=/tmp/{feature}/mo/states.json \
   --bp=mo
 
 # PC
@@ -148,6 +160,7 @@ node {{VIBE_PATH}}/hooks/scripts/clone-refine.js \
   /tmp/{feature}/pc/rendered.html \
   /tmp/{feature}/pc/computed.json \
   --out=/tmp/{feature}/pc/sections.json \
+  --states=/tmp/{feature}/pc/states.json \
   --bp=pc
 ```
 
@@ -175,6 +188,13 @@ Refinement applied when converting rendered.html + computed.json → sections.js
      typography (font-*, line-height, letter-spacing, text-*, color),
      decoration (background, border, border-radius, box-shadow, opacity),
      transform/transition
+  9. Classify interaction model per section (static-DOM heuristic) → section.interaction
+     = { model, confidence, signals[], note }. model ∈ static | click-driven | scroll-driven
+     | time-driven | hover. This is a best-guess + ranked SIGNALS, NOT a silent decision —
+     the builder confirms it against the live site (Phase 5). Misidentifying the interaction
+     model is the #1 clone failure mode (scroll-driven original built as a click UI, etc.).
+ 10. Attach matching state rules from states.json to each section → section.states
+     (rules whose selector references a class/leaf-tag inside that section's subtree)
 ```
 
 ### Output
@@ -188,8 +208,17 @@ Refinement applied when converting rendered.html + computed.json → sections.js
       {
         name: "Header" | "Hero" | "Features" | ...,
         nodeRef, tag, size, css,
+        interaction: {        // static-DOM heuristic — builder confirms in Phase 5
+          model: "static" | "click-driven" | "scroll-driven" | "time-driven" | "hover",
+          confidence: "high" | "medium" | "low",
+          signals: [...],     // ranked evidence (sticky, infinite animation, role=tab, …)
+          note
+        },
         text,                 // text content (placeholder candidates)
         components: [...],    // detected repeated patterns
+        states: [             // non-default state rules scoped to this section
+          { selector, media, css }
+        ],
         children: [...],      // full recursive subtree
         images: { bg, content: [...] }
       }
@@ -207,6 +236,12 @@ Refinement applied when converting rendered.html + computed.json → sections.js
 ### BLOCKING Command — SCSS must only use script output
 
 ```bash
+# Step 0: Generate per-section build-contract specs (run once per BP)
+node {{VIBE_PATH}}/hooks/scripts/clone-spec.js \
+  /tmp/{feature}/{bp}/sections.json \
+  --out=/path/to/project/components/{feature}/_specs/ \
+  --feature={feature}
+
 # Step A: Auto-generate SCSS skeleton (run once per BP)
 node {{VIBE_PATH}}/hooks/scripts/clone-to-scss.js \
   /tmp/{feature}/{bp}/sections.json \
@@ -220,22 +255,33 @@ node {{VIBE_PATH}}/hooks/scripts/clone-validate.js \
   --section={SectionName}
 ```
 
+⛔ **No section is built without a completed spec.** Step 0 emits `_specs/{Section}.spec.md`
+   (interaction model + states + computed CSS + assets + text + checklist). Before writing a
+   section's component, Claude reviews its spec and resolves every `TODO` (confirm interaction
+   model, list states to implement, choose tags, replace copyrighted text). The spec is the
+   contract AND the audit trail — it forces extraction rigor before any code is written.
 ⛔ **Writing SCSS files directly without calling clone-to-scss.js invalidates Phase 3.**
-⛔ **Do NOT write custom SCSS generation scripts.**
+⛔ **Do NOT write custom SCSS / spec generation scripts.**
 ⛔ **Do NOT proceed to the next section without a clone-validate.js PASS.**
-✅ Use clone-to-scss.js output as-is. If unsatisfactory, modify the script.
+✅ Use clone-spec.js / clone-to-scss.js output as-is. If unsatisfactory, modify the script.
 
 ```
 Phase 3A: MO Scaffold
   Input: /tmp/{feature}/mo/sections.json
+  Step 0 once: clone-spec.js → emit _specs/{Section}.spec.md for every section
   ⛔ No parallelism. Process one section at a time:
-    1. Read the target section from sections.json
+    1. Read the target section's spec → resolve every TODO:
+       ├─ Confirm the interaction model (spec.interaction is a heuristic guess)
+       ├─ List the states to implement (spec.states)
+       └─ Mark copyrighted text for placeholder replacement
     2. Map component candidates against component-index.json
        ├─ Match → import existing
        └─ No match → create new in components/{feature}/
     3. clone-to-scss.js → auto-generate SCSS skeleton (computed values as-is) — Step A once
     4. Claude: HTML structure + semantic tags + framework-specific component file
        ⛔ No CSS written directly in <style> blocks — only @import/@use allowed
+       ⛔ Build for the CONFIRMED interaction model (don't build a click UI for a
+          scroll-driven original); wire every state from the spec (hover/active/open/…)
        Framework mapping:
          - React/Next → .tsx with CSS Modules or styled-components per stack
          - Vue/Nuxt   → .vue with scoped <style lang="scss"> @import only
@@ -258,7 +304,8 @@ Claude's role (restricted):
   ✅ Component candidates: decide which patterns become reusable components
   ✅ HTML semantics: section/h1/p/button/nav tag selection
   ✅ Text replacement: substitute copyrighted copy with placeholders or user-supplied text
-  ✅ Interactions: hover/focus states, click handlers, conditional rendering
+  ✅ Interaction model: confirm the spec's heuristic guess, then build for the real model
+  ✅ Interactions: implement every state in the spec (hover/focus/active/open), click handlers
   ❌ Do NOT modify SCSS CSS values (use clone-to-scss.js output as-is)
   ❌ Do NOT write CSS directly in <style> blocks
   ❌ Do NOT use vw/clamp/@media or create custom mixins in Phase 3A/3B
@@ -359,3 +406,5 @@ Claude must:
 | robots.txt disallows path | Halt Phase 1. Inform user; require explicit `--ignore-robots` flag to proceed. |
 | clone-refine.js produces empty sections | Site likely uses Shadow DOM or canvas rendering. Report and ask whether to fall back to screenshot-only mode. |
 | Pixel diff stuck > 0.05 after 5 rounds | Likely font fallback or anti-aliasing. Report metric, allow user to accept threshold. |
+| Interaction model guess wrong (Phase 5) | section.interaction is a static-DOM heuristic. Re-observe the live site, correct the model in the spec, rebuild the section for the confirmed model. |
+| states.json empty but site has hover/tabs | States may be set via inline JS, not CSS rules. Note in the spec and capture them manually from the live site during Phase 5. |

package/skills/vibe.clone/SKILL.md

@@ -52,18 +52,23 @@ Phase 0: Setup
 Phase 1: Capture (병렬 — scope에 따라 MO/PC 동시)
   - node {{VIBE_PATH}}/hooks/scripts/clone-extract.js capture <url> \
       --out=/tmp/{feature}/{bp}/ --viewport={WxH} --bp={mo|pc}
-  - 출력: rendered.html, computed.json, screenshot.png, asset-map.json, assets/
+  - 출력: rendered.html, computed.json, screenshot.png, states.json, asset-map.json, assets/
 
 Phase 2: Refine (BP마다 독립)
   - node {{VIBE_PATH}}/hooks/scripts/clone-refine.js \
       /tmp/{feature}/{bp}/rendered.html /tmp/{feature}/{bp}/computed.json \
-      --out=/tmp/{feature}/{bp}/sections.json --bp={mo|pc}
+      --out=/tmp/{feature}/{bp}/sections.json --states=/tmp/{feature}/{bp}/states.json --bp={mo|pc}
+  - sections.json 에 section.interaction(인터랙션 모델 추정) + section.states(상태 규칙) 포함
 
 Phase 3: Scaffold (BP 순차 — MO 완료 후 PC)
+  - Step 0: node {{VIBE_PATH}}/hooks/scripts/clone-spec.js \
+      /tmp/{feature}/{bp}/sections.json \
+      --out=./components/{feature}/_specs/ --feature={feature}
+    → 섹션별 빌드 계약서(_specs/{Section}.spec.md). 빌드 전 TODO(인터랙션 모델 확정·상태 목록·텍스트 교체) 해결
   - Step A: node {{VIBE_PATH}}/hooks/scripts/clone-to-scss.js \
       /tmp/{feature}/{bp}/sections.json \
       --out=./styles/{feature}/ --feature={feature}
-  - Claude: 섹션별로 HTML/컴포넌트 작성 (스택별 .tsx/.vue/.svelte/.html)
+  - Claude: 섹션별로 HTML/컴포넌트 작성 (스택별 .tsx/.vue/.svelte/.html) — 확정된 인터랙션 모델 + 모든 상태 반영
   - Step B: node {{VIBE_PATH}}/hooks/scripts/clone-validate.js \
       ./styles/{feature}/ /tmp/{feature}/{bp}/sections.json --section={Name}
   - 섹션마다 PASS 받고 다음 섹션 진행
@@ -83,10 +88,11 @@ Phase 5: Pixel Verification (P1=0까지 루프 — clone SKILL.md 규칙)
 
 ```
 /tmp/{feature}/                  # 작업 디렉토리 (산출물 원본)
-  ├── mo/, pc/                   # rendered.html, computed.json, screenshot.png, sections.json, assets/
+  ├── mo/, pc/                   # rendered.html, computed.json, screenshot.png, states.json, sections.json, assets/
   └── project-tokens.json        # 기존 프로젝트 토큰 인덱스
 
 ./components/{feature}/          # Claude가 작성한 컴포넌트 (.tsx/.vue/.svelte/.html)
+./components/{feature}/_specs/   # clone-spec.js가 생성한 섹션별 빌드 계약서 (*.spec.md)
 ./styles/{feature}/              # clone-to-scss.js가 생성한 SCSS 파일
   ├── _tokens.scss               # CSS 변수
   ├── _base.scss                 # @font-face