Interaction Model Detection Mechanism in the AI Website Cloner Template

The template detects interaction models through a systematic three-pass sweep (scroll, click, hover) that observes behavioral changes before generating component specifications.

The JCodesMore/ai-website-cloner-template implements a rigorous interaction model detection mechanism to ensure cloned websites preserve their original behavioral logic. Before generating any React components, the system performs a dedicated interaction sweep using browser-automation tools (Chrome MCP, Playwright MCP, etc.) to classify how each page section responds to user input, scrolling, and time-based triggers.

The Three-Pass Interaction Sweep

The detection mechanism executes a strict sequential observation process defined in /.windsurf/workflows/clone-website.md. This protocol ensures accurate classification by isolating different types of user interactions into distinct observation phases.

Scroll-First Pass

The agent begins by scrolling slowly through the page to identify scroll-driven behaviors. During this pass, the system records visual or behavioral changes that occur automatically, such as navbar shrink effects, fade-in animations, scroll-snap points, and IntersectionObserver triggers.

Click-Then Pass

Only after completing the scroll sweep does the agent click every interactive element (buttons, tabs, cards). This phase identifies click-driven interactions by logging state changes that result from user activation.

Hover-Then Pass

The agent hovers over potentially interactive items to detect CSS changes (color shifts, scale transforms, shadow effects) that indicate hover-driven behaviors.

Responsive Pass

The entire sweep repeats at three specific viewport widths to capture layout-dependent interactions:

• Desktop: 1440 px
• Tablet: 768 px
• Mobile: 390 px

Classification Categories

Based on the observed behavior, each section is classified into one of four interaction models:

• Static: No change on scroll, click, or hover
• Click-driven: Changes only after a click or tap event
• Scroll-driven: Changes occur while scrolling (IntersectionObserver, position:sticky, scroll-snap, animation-timeline, JavaScript scroll listeners)
• Time-driven: Changes occur automatically after a timeout or interval (auto-playing carousels)

The classification is recorded in the component specification file under the Interaction model field:

## Overview

- Interaction model: **scroll-driven with IntersectionObserver**

Implementation in Source Files

The detection logic is documented across several key files in the repository:

• /.windsurf/workflows/clone-website.md: Contains the full interaction sweep protocol, classification rules, and enforcement checklists
• /docs/research/PAGE_TOPOLOGY.md: Stores the detected interaction model for each page section
• /docs/research/components/<Component>.spec.md: Individual component specifications include the Interaction model field used by builder agents

Detection Examples

Detecting Scroll-Driven Behaviors

This JavaScript example from the interaction sweep detects a scroll-driven navbar by comparing computed styles before and after scrolling:

// In the interaction sweep (run via browser MCP)
window.scrollTo(0, 0);                 // start at top
await new Promise(r => setTimeout(r, 500));

const before = getComputedStyle(document.querySelector('nav'));
window.scrollTo(0, 200);               // scroll down
await new Promise(r => setTimeout(r, 500));

const after = getComputedStyle(document.querySelector('nav'));
if (before.backgroundColor !== after.backgroundColor) {
  console.log('INTERACTION MODEL: scroll-driven with IntersectionObserver');
}

Capturing Click-Driven State Changes

For tab components or accordion interfaces, the sweep clicks each interactive element to capture resulting content states:

const tabButtons = document.querySelectorAll('.tab-button');
tabButtons.forEach((btn, i) => {
  btn.click();                         // trigger tab i
  const content = document.querySelector('.tab-content').innerHTML;
  console.log(`Tab ${i} content captured`, content);
});

Documenting Interaction Models in Spec Files

Builder agents reference structured documentation in component spec files to generate correct JavaScript logic:

## Interaction model

INTERACTION MODEL: click-to-switch with opacity transition

## States & Behaviors

- Trigger: click on `.tab-button`
- State A (before): opacity 0, display:none
- State B (after): opacity 1, display:block
- Transition: opacity 0.3s ease

Key Detection Principles

Never Click Before Scrolling

The workflow explicitly enforces observation order to prevent misclassification. According to the source documentation, the rule states: "Don't click first. Scroll … if they do, it's scroll-driven". This ensures scroll-driven animations are not mistaken for click-driven interactions.

Document Exact Triggers

For scroll-driven sections, the mechanism captures the specific trigger parameters, such as IntersectionObserver thresholds or scroll positions in pixels, alongside before/after CSS values.

Save Findings to Research Docs

All observations are persisted in docs/research/PAGE_TOPOLOGY.md and individual component specifications (docs/research/components/<Component>.spec.md), ensuring builder agents access accurate behavioral data during code generation.

Summary

• The interaction model detection mechanism uses a three-pass sweep (scroll, click, hover) to observe behavioral changes
• Sections are classified as static, click-driven, scroll-driven, or time-driven based on observed triggers
• The scroll-first rule prevents misclassification of scroll-based animations
• Detection results are stored in /docs/research/PAGE_TOPOLOGY.md and component spec files
• Builder agents use this data to generate appropriate React hooks (e.g., useIntersectionObserver) and event handlers

Frequently Asked Questions

How does the template avoid misclassifying scroll-driven components as click-driven?

The workflow enforces a strict scroll-first pass before any click interactions occur. According to /.windsurf/workflows/clone-website.md, the agent must scroll through the page first to identify automatic behavioral changes, ensuring scroll-driven animations are not mistaken for click-driven interactions.

What viewport sizes does the responsive pass use?

The responsive pass tests interactions at three specific breakpoints: desktop (1440 px), tablet (768 px), and mobile (390 px). This ensures the detection mechanism captures layout-dependent interactions that may behave differently across device sizes.

Where is the interaction model data stored?

Detected interaction models are recorded in two locations: /docs/research/PAGE_TOPOLOGY.md contains the page-wide topology, while /docs/research/components/<Component>.spec.md stores individual component specifications including the Interaction model field and trigger documentation.

How does the detection mechanism handle time-driven animations?

The scroll-first pass identifies time-driven behaviors by observing changes that occur automatically after timeouts or intervals, such as auto-playing carousels. These are classified separately from user-triggered interactions and documented with their specific timing parameters in the component specifications.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}