# How Layered Images and Overlay Compositions Are Detected During Extraction in AI Website Cloning

> Discover how AI website cloning extracts layered images and overlay compositions by analyzing img and background-image positions and z-index values. Rebuild complex layouts easily.

- Repository: [JCodesMore/ai-website-cloner-template](https://github.com/JCodesMore/ai-website-cloner-template)
- Tags: deep-dive
- Published: 2026-06-26

---

**The extraction script captures every `<img>` and CSS `background-image` along with their `position` and `z-index` values, then identifies overlapping assets by comparing these computed styles to rebuild layered compositions in the cloned output.**

When the **`/clone-website`** skill runs in the **JCodesMore/ai-website-cloner-template** repository, it executes a specialized *layered-assets detection* phase that ensures no visual element is overlooked. This process discriminates between background layers, foreground mock-ups, and overlay icons by analyzing the computed CSS properties of every image asset before the component specifications are written.

## The Layered-Assets Detection Pipeline

The detection logic is implemented in the browser-MCP extraction script defined in [`.windsurf/workflows/clone-website.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/.windsurf/workflows/clone-website.md). It operates by enumerating two distinct categories of visual assets and correlating their spatial metadata.

### Scanning Inline Image Elements

The script first iterates over every `<img>` tag in the DOM using `document.querySelectorAll('img')`. For each image, it records the `src`, `alt`, dimensions, **position**, and **z-index** (lines 2 011‑2 018).

These properties determine whether an image functions as a background element, a foreground UI mock-up, or a floating overlay icon. The `position` value (e.g., `absolute`, `fixed`, `relative`) combined with the `zIndex` creates a complete stacking context profile for the asset.

```javascript
// Excerpt from .windsurf/workflows/clone-website.md
images: [...document.querySelectorAll('img')].map(img => ({
  src: img.src,
  alt: img.alt,
  width: img.naturalWidth,
  height: img.naturalHeight,
  position: getComputedStyle(img).position,
  zIndex: getComputedStyle(img).zIndex
})),

```

### Extracting CSS Background Images

The extraction script then scans *every* DOM node using `document.querySelectorAll('*')` to identify elements with computed `background-image` styles that are not `none` (lines 2 011‑2 016). It captures the first class name and tag name to preserve the exact selector specificity required for reconstruction.

This step ensures that decorative backgrounds and texture layers—which often lack `<img>` tags—are included in the asset inventory.

```javascript
// Excerpt from .windsurf/workflows/clone-website.md
backgroundImages: [...document.querySelectorAll('*')]
  .filter(el => {
    const bg = getComputedStyle(el).backgroundImage;
    return bg && bg !== 'none';
  })
  .map(el => ({
    url: getComputedStyle(el).backgroundImage,
    element: el.tagName + '.' + el.className?.split(' ')[0]
  })),

```

### Identifying Overlay Compositions via Stacking Context

By comparing the `position` and `zIndex` values of collected images and background-images, the system recognizes when multiple assets occupy the same container. When the extraction phase detects multiple entries for a single container with overlapping coordinates, it flags the group as a **layered image** or **overlay composition**.

This detection happens before any component specifications are generated, ensuring that builders receive a complete set of visual assets—including hidden overlays that would be missed if only standalone `<img>` elements were examined.

## Parallel Asset Download and Storage

After enumeration, a separate download script fetches every discovered image, video, and background-image in parallel. These assets are stored in the clone's `public/` folder, maintaining the exact same layers that the live site renders.

The builder receives a structured asset manifest that distinguishes between background images, overlay images, and icon components:

```markdown

## Assets

- Background image: `public/images/header-bg.webp`
- Overlay image: `public/images/header-hero.png`
- Icons: `<ArrowIcon>` from `icons.tsx`

```

## Key Implementation Files

| File | Role |
|------|------|
| [`.windsurf/workflows/clone-website.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/.windsurf/workflows/clone-website.md) | Contains the JavaScript extraction logic that detects `<img>` and `background-image` assets, including position and z-index analysis. |
| [`docs/research/INSPECTION_GUIDE.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/docs/research/INSPECTION_GUIDE.md) | Provides checklist items reminding extractors to "Don't miss overlay/layered images." |
| [`scripts/sync-agent-rules.sh`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/scripts/sync-agent-rules.sh) | Regenerates platform-specific instruction files to keep detection logic synchronized across agents. |
| [`README.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/README.md) | High-level overview of the cloning process emphasizing the importance of layered asset detection. |

## Summary

- The extraction script in [`.windsurf/workflows/clone-website.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/.windsurf/workflows/clone-website.md) performs a **layered-assets detection** step before generating component specifications.
- It collects all `<img>` elements and CSS `background-image` properties along with their computed `position` and `zIndex` values.
- Overlay compositions are identified by analyzing stacking contexts where multiple assets occupy the same container.
- A parallel download script ensures all layers—including hidden overlays—are preserved in the `public/` folder for accurate reconstruction.

## Frequently Asked Questions

### How does the extraction script distinguish between background images and overlay images?

The script examines the `position` and `zIndex` computed styles for every asset. Background elements typically have lower z-index values or static positioning, while overlays use `absolute` or `fixed` positioning with higher z-index values. This spatial data allows the system to categorize each layer correctly during the reconstruction phase.

### Why does the detection process scan all DOM nodes instead of just `<img>` tags?

Many modern websites use CSS `background-image` for decorative layers, textures, and responsive imagery that never appear as `<img>` elements. The script calls `document.querySelectorAll('*')` to ensure these CSS-based assets are captured, preventing the cloned site from missing critical visual layers that contribute to the composite design.

### What happens to assets that are flagged as layered compositions?

When multiple assets are detected within the same container with overlapping positioning data, they are flagged as layered images. The download script then fetches these assets in parallel and stores them in the `public/` directory. The builder receives a specification that references each layer separately, allowing the Next.js project to reconstruct the exact same stacking order as the original site.

### Where is the detection logic documented for maintenance purposes?

The primary extraction logic resides in [`.windsurf/workflows/clone-website.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/.windsurf/workflows/clone-website.md) (lines 2 011‑2 018). Additional guidance appears in [`docs/research/INSPECTION_GUIDE.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/docs/research/INSPECTION_GUIDE.md), which includes explicit checklist items reminding developers not to miss overlay and layered images during extraction.