How the AI-Website-Cloner Template Differentiates Between Scroll and Click Interaction Models

The template distinguishes scroll-driven from click-driven interactions through a documentation-driven workflow that mandates a "scroll-first" inspection rule, capturing the exact interaction mechanism in a component specification's INTERACTION MODEL field rather than through runtime detection code.

The JCodesMore/ai-website-cloner-template provides a structured framework for AI agents to clone websites by defining how to differentiate between scroll vs. click interaction models during the reconnaissance phase. Instead of relying on automated runtime detection, the repository encodes the distinction into workflow documentation that guides agents through a systematic inspection process. This architectural contract ensures that interaction models are correctly identified, recorded, and later implemented by builder agents.

Documentation-Driven Workflow for Interaction Detection

The repository contains no runtime logic for programmatically detecting interaction types. Instead, the differentiation strategy is embedded in markdown workflow files that serve as instructions for AI agents.

The Scroll-First Inspection Rule

According to .windsurf/workflows/clone-website.md (lines 80-89), the agent must follow a strict inspection order: scroll before click. The documentation instructs agents to first scroll through a section while watching for visual changes triggered by:

• IntersectionObserver thresholds
• CSS scroll-snap points
• Sticky positioning changes
• animation-timeline scroll effects
• JavaScript scroll event listeners

Only if no scroll-driven behavior is detected does the agent fall back to testing click-driven interactions. This rule prevents misclassification of scroll-activated components as static or click-dependent elements.

The INTERACTION MODEL Specification Tag

The .opencode/commands/clone-website.md file (lines 83-89) introduces a mandatory tagging system. Agents must record the detected mechanism using an INTERACTION MODEL field in the component specification, such as:

"INTERACTION MODEL: scroll-driven with IntersectionObserver"

The .github/skills/clone-website/SKILL.md file (lines 83-89) reinforces this requirement for the AI skill used during cloning, ensuring consistency across different agent implementations.

Architectural Flow: From Inspection to Implementation

The template implements a four-phase pipeline to differentiate and process interaction models:

1. Inspection Order – Agents execute a "scroll-first" sweep through the target UI section using browser automation tools (Playwright/Chrome MCP).
2. Mechanism Capture – When visual changes occur, the agent documents the precise trigger mechanism (e.g., IntersectionObserver rootMargin or scroll-snap alignment).
3. Specification Recording – The interaction model is encoded in the component spec using the INTERACTION MODEL field, distinguishing between scroll-driven, click-driven, hover-driven, or static types.
4. Implementation Generation – Builder agents read the specification and generate appropriate code (e.g., IntersectionObserver for scroll events or addEventListener('click') for click handlers).

This workflow is outlined in the README.md (Section 1 – Reconnaissance), which lists the "interaction sweep (scroll, click, hover, responsive)" as a core reconnaissance step.

Component Specification Structure

The template defines a TypeScript interface—typically located at src/types/component-spec.ts—that type-enforces the interaction model classification:

export interface ComponentSpec {
  /** Human-readable name */
  name: string;
  /** Path to the original page element */
  selector: string;
  /** CSS captured for each visual state */
  styles: Record<string, Record<string, string>>;
  /** Interaction model – scroll-driven, click-driven, hover-driven or static */
  interactionModel:
    | { type: "scroll-driven"; trigger: string }
    | { type: "click-driven"; selector: string }
    | { type: "hover-driven"; selector: string }
    | { type: "static" };
}

The interactionModel union type strictly differentiates between scroll and click behaviors, ensuring type safety throughout the cloning pipeline.

Practical Implementation Examples

Recording Scroll-Driven Behavior in JSON

When an inspection agent detects a header that changes background color on scroll, it generates a specification like this:

{
  "name": "Header",
  "selector": ".site-header",
  "styles": {
    "state-0": { "background": "#fff", "boxShadow": "none" },
    "state-scrolled": { "background": "#000", "boxShadow": "0 2px 4px rgba(0,0,0,.1)" }
  },
  "interactionModel": {
    "type": "scroll-driven",
    "trigger": "IntersectionObserver threshold=0.5"
  }
}

This JSON explicitly differentiates the interaction model as scroll-driven and specifies the IntersectionObserver configuration that triggers the visual state change.

Generating Code from the Specification

A builder agent consuming this specification generates React code that implements the documented scroll behavior rather than a click handler:

import { useEffect } from "react";

export function Header() {
  useEffect(() => {
    const target = document.querySelector(".site-header");
    const obs = new IntersectionObserver(
      ([entry]) => {
        if (entry.intersectionRatio < 0.5) {
          target?.classList.add("scrolled");
        } else {
          target?.classList.remove("scrolled");
        }
      },
      { threshold: [0, 0.5] }
    );
    obs.observe(document.querySelector("#sentinel")!);
    return () => obs.disconnect();
  }, []);

  return (
    <header className="site-header">
      {/* … */}
    </header>
  );
}

The builder reads interactionModel.type === "scroll-driven" and injects an IntersectionObserver. For a click-driven specification, it would instead attach a click event listener to the element specified in the selector field.

Summary

• The JCodesMore/ai-website-cloner-template differentiates scroll vs. click interaction models through documentation-driven workflow rather than runtime detection.
• The scroll-first inspection rule in .windsurf/workflows/clone-website.md mandates checking scroll behaviors before testing click events.
• Agents record detected mechanisms using the INTERACTION MODEL tag defined in .opencode/commands/clone-website.md.
• The ComponentSpec interface type-enforces interaction classification as scroll-driven, click-driven, hover-driven, or static.
• Builder agents generate implementation code—such as IntersectionObserver instances or click event listeners—based on the recorded specification.

Frequently Asked Questions

Does the template use runtime JavaScript to detect scroll vs. click events?

No. The repository contains no runtime detection logic. Instead, the template relies on AI agents to manually inspect target websites during the reconnaissance phase, following the "scroll-first" workflow documented in .windsurf/workflows/clone-website.md. The agents observe behavior and record the interaction model in the component specification.

What files define the interaction model detection workflow?

The primary workflow definitions reside in three locations: .windsurf/workflows/clone-website.md (lines 80-89) for Windsurf IDE integration, .opencode/commands/clone-website.md (lines 83-89) for Opencode commands, and .github/skills/clone-website/SKILL.md (lines 83-89) for GitHub Skills. The README.md (Section 1) provides the high-level reconnaissance overview.

How does the builder agent know which interaction type to implement?

Builder agents read the interactionModel field from the ComponentSpec interface. If the type property equals "scroll-driven", the agent generates scroll-related code like IntersectionObserver. If the type is "click-driven", it generates an event listener for the specified selector. This architectural contract ensures the implementation matches the inspected behavior.

Can the template handle hover-driven interactions as well?

Yes. The ComponentSpec interface includes a hover-driven option in its union type, and the README.md lists "hover" as part of the required interaction sweep. Agents can record hover states in the specification, allowing builders to generate appropriate mouse event handlers alongside scroll and click implementations.

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