site-prototype

site-prototype creates ordinary, editable Astro projects from selected pages of a public website. It preserves browser-rendered HTML and referenced visual assets, then provides repeatable source-versus-prototype screenshots and browser QA.

It does not generate a patch language, proxy the live site, or hide copied pages behind a proprietary runtime.

The project is alpha software. Use it for authorized public marketing, editorial, portfolio, and ecommerce pages where a static visual prototype is appropriate.

What it creates

• One editable .astro route for every selected source route.
• Local, content-addressed copies of referenced images, fonts, stylesheets, and media.
• Desktop and mobile source captures plus local and difference screenshots.
• Browser-QA reports for broken images, overflow, console errors, source links, active forms, and route coverage.
• Static-site safety defaults that remove source scripts and disable forms, checkout, account actions, tracking, and indexing.

Requirements

• Bun 1.3 or newer
• Python 3.10 or newer
• pipx for the isolated Python CLI installation
• Git
• site-capture with its Playwright extra
• Playwright Chromium for both Bun and Python

Install

Install the capture dependency as an isolated Python application:

pipx install --include-deps \
  "site-capture[playwright] @ git+https://github.com/HanifCarroll/site-capture.git"
playwright install chromium

Then install and link this CLI:

git clone https://github.com/HanifCarroll/site-prototype.git
cd site-prototype
bun install --frozen-lockfile
bunx playwright install chromium
bun link

Verify every prerequisite before creating a project:

site-prototype doctor

Quick start

Discover candidate routes:

site-prototype discover https://example.com --max-pages 30

Create a project with explicit routes:

site-prototype create https://example.com \
  --name example-prototype \
  --route / \
  --route /about \
  --route /products

The default destination is ./example-prototype. Use --output /path/to/project to choose another location.

Exclude a known popup or third-party runtime root from both the source screenshots and generated markup:

site-prototype create https://example.com \
  --name example-prototype \
  --route / \
  --exclude-selector '.newsletter-modal' \
  --exclude-selector '#tracking-sandbox'

Selectors are explicit and repeatable. A selector that matches nothing is preserved as a capture warning; the tool does not infer replacements.

Or run each phase separately:

site-prototype init https://example.com --name example-prototype --route /
site-prototype capture ./example-prototype
site-prototype build ./example-prototype
site-prototype compare ./example-prototype
site-prototype qa ./example-prototype

Generated project

Each project is a normal Astro repository:

reference/                 Immutable source captures and QA evidence
src/pages/                 Editable .astro pages
public/source-assets/      Localized images, fonts, CSS, and media
.site-prototype.json       Routes, viewports, and safety settings

The generated site removes captured scripts, disables live forms and commerce/account actions, rewrites internal links to local routes, adds noindex, and emits Netlify-compatible headers that prevent indexing. Interactive behavior must be implemented explicitly in Astro, a client script, or a framework island.

Links to internal routes that were not selected for capture are disabled rather than sent to the live site or a local 404. Their original paths remain in data-prototype-source-path attributes and the generation manifest so they can be added deliberately.

Command contract

All commands accept the global --json option before the subcommand. Successful JSON responses contain ok: true; failures contain ok: false and an error string. No command sends forms, purchases, messages, or account actions to the source site.

Fidelity process

1. Capture source routes before editing.
2. Generate the untouched Astro copy.
3. Run compare and resolve structural differences.
4. Make proposed changes directly in src/pages and shared Astro components.
5. Run compare and qa again.

Pixel differences are diagnostic. The QA report separately checks route responses, broken images, horizontal overflow, source-origin link leaks, active forms, and browser console errors.

Development verification

bun run verify
bun run test:e2e

The end-to-end check serves a local two-route website, captures both viewports through site-capture, generates a fresh Astro project, runs visual comparison, and requires the generated project to pass browser QA.

Scope and limitations

The first release targets selected public marketing, editorial, portfolio, and ecommerce pages. It deliberately does not support authenticated applications, live checkout, protected APIs, service workers, canvas/WebGL reconstruction, or automatic component extraction. Third-party iframes are disabled and reported.

Only copy and share a site with the owner's permission. Keep client prototypes private and use the generated robots.txt and response headers on every deployment.

Noindex directives are not authentication. Configure access control with the hosting provider before sharing a client prototype.

Contributing

See CONTRIBUTING.md. Report security problems through the process in SECURITY.md, not a public issue.