How Page Topology Mapping Works in the AI Website Cloner Template

The AI Website Cloner Template extracts a hierarchical page topology document before any component code is written, establishing the structural skeleton that guides all subsequent building phases.

The JCodesMore/ai-website-cloner-template treats page topology mapping as the foundational first step in its cloning pipeline. Before generating a single React component or CSS file, the system creates a comprehensive structural map of the target website. This topology document defines every visual section, container type, and hierarchical relationship from top to bottom, ensuring the final build preserves the exact layout order of the source.

The Reconnaissance Phase: Extracting Page Structure

According to the README.md (lines 88-95), the template implements a five-step pipeline where the initial Reconnaissance phase yields the page topology. During this phase, the AI agent browses the target site, capturing screenshots, scrolling through content, and recording responsive breakpoints. It identifies every visual section and documents its container characteristics—whether scroll areas, columns, sticky layers, or z-index stacking contexts.

The agent writes this data to docs/research/<hostname>/topology.json, creating an ordered list that serves as the single source of truth for the entire cloning process. As documented in .windsurf/workflows/clone-website.md (line 228), the core workflow loop processes sections "for each section in your page topology (top to bottom)," ensuring sequential fidelity.

Topology Document Structure

Each entry in the topology file specifies the section's spatial and structural properties:

{
  "id": "section-3",
  "type": "scroll-container",
  "order": 3,
  "rect": { "x":0, "y":1240, "width":1440, "height":800 }
}

From Topology to Component Specifications

Once the topology document establishes the page skeleton, the pipeline transitions to component spec generation. For each topology entry, the agent extracts computed CSS values, interaction models, and content requirements, writing detailed specification files to docs/research/components/<section-id>.spec.json.

These spec files contain exact design tokens, asset paths, and behavioral requirements needed to recreate the component. Because the topology already defines the structural order, spec generation can proceed systematically without architectural uncertainty.

Parallel Component Building and Assembly

With specifications in hand, the template dispatches dedicated builder agents to implement each component. As outlined in the workflow, each builder operates in its own Git worktree, allowing parallel development while preserving the original layout order defined by the topology.

The topology document enables this concurrency by removing structural dependencies from the component-building phase. Builders reference the pre-defined order and container types, ensuring that when the assembly phase combines all components, the scroll containers, column structures, sticky positioning, and z-index layering match the original site exactly.

Executing the Topology Extraction

To initiate the topology mapping process, run the cloning skill against your target URL:

# The first phase automatically builds the topology document

/clone-website https://example.com

After execution, inspect the generated topology at:

cat docs/research/example.com/topology.json

Then examine a corresponding component specification:

cat docs/research/components/section-3.spec.json

Example spec file structure:

{
  "name": "HeroBanner",
  "styles": {
    "background": "#ffffff",
    "padding": "24px 0"
  },
  "assets": ["images/hero.jpg"],
  "interactions": ["onHover:opacity(0.9)"]
}

Summary

• Page topology mapping is the first distinct phase in the JCodesMore/ai-website-cloner-template pipeline, preceding all component construction.
• The topology document at docs/research/<hostname>/topology.json defines every section's container type, spatial coordinates, and hierarchical order.
• Workflow logic in .windsurf/workflows/clone-website.md processes sections sequentially based on this topology.
• Component specifications are generated only after the topology is established, enabling parallel builder dispatch without layout conflicts.
• Final assembly uses the topology as a blueprint to reconstruct scroll containers, sticky layers, and responsive breakpoints.

Frequently Asked Questions

What file contains the page topology mapping in the AI Website Cloner Template?

The generated topology is stored at docs/research/<hostname>/topology.json, where <hostname> is derived from the target URL. This JSON file lists every visual section from top to bottom, including container types and spatial coordinates, serving as the structural blueprint for the entire cloning process.

Why does the template create a topology document before building components?

Creating the topology first separates structural concerns from implementation details. By establishing the page hierarchy—defining scroll containers, columns, and sticky layers before writing code—the template ensures that parallel component builders can work simultaneously without violating the original site's visual layout or z-index stacking order.

How does the topology mapping process handle responsive breakpoints?

During the Reconnaissance phase, the AI agent scrolls through the target site and captures responsive breakpoints as distinct sections in the topology document. Each entry records the viewport dimensions and behavior, allowing the subsequent assembly phase to recreate exact responsive layouts rather than inferring breakpoints from individual components.

Can I manually edit the topology file to change the page structure?

Yes, since the topology file at docs/research/<hostname>/topology.json is a standard JSON document, you can modify section orders, change container types, or adjust spatial coordinates before the component building phase begins. Edits made before running the builder agents will propagate through to the final assembled page.

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