ericshang98 / perfect-web-clone

Perfect Web Clone

Pixel-perfect cloning is this skill. The current agent is the harness runtime.
pwc is the deterministic hands and eyes: it captures, persists, builds,
renders, replays, and measures. It never calls another model. You understand
the evidence, author code, and choose targeted repairs.

A single natural-language request such as “复刻 https://example.com” authorizes
the entire local reproduction workflow. Treat it as one user operation even
though the harness performs many internal tool calls and repair iterations.

Do not ask for routine confirmation when the request contains a usable URL.
Infer that a full-page clone is the default.
Continue across phases without returning control merely to announce progress or
request ordinary implementation choices. Ask only when a missing fact would
materially change scope, when credentials or new authority are required, or when
the user must resolve an external blocker.

Deployment is never implicit. Produce a local build and review URL by default;
deploy only when the user explicitly asks.

Use one owning agent for the whole page so global visual context survives across
sections. Do not delegate unless the user explicitly asks.

Non-negotiable execution contract

1. Run capture, planning, authoring, build, verification, repair, and handoff as
   one continuous task.

2. Inspect every ok or success flag and its error evidence. Never invent a
   tool result.

3. Preserve immutable raw evidence separately from normalized evidence. Refuse
   to plan from an incomplete capture.

4. Reproduce every planned top-level section and every independently required
   critical region. Do not stop after the viewport or after a visually dominant
   subset.

5. Implement and replay every required common interaction: carousel, menu, tabs,
   accordion/details, and other contracts discovered during capture.
   A visually similar but inert control fails.

6. Run gates in dependency order. A downstream score cannot override an
   upstream structural or behavioral failure.

7. Repair the smallest owning component identified by evidence, rebuild, and
   re-run all affected gates.

8. Never hide, waive silently, or average away a red gate.
   A missing critical region cannot be offset by aggregate visual similarity.

9. End only in ready_for_user_review or failed_with_residuals.
   Only the user can accept the result.

Read [references/harness-contract.md](references/harness-contract.md) before
starting a new run or resuming one. It defines the progress ledger, terminal
states, evidence vocabulary, and exact stop rules.

Install the measured core if pwc is missing:

pip install "git+https://github.com/ericshang98/Perfect-Web-Clone.git"
playwright install chromium

Every pwc command prints JSON. ok: false is a stop-and-fix signal.

Continuous workflow

1. Resolve and resume

• Extract the target URL from the request. If none is present and it cannot be
  recovered from the current browser/task context, ask for it.

• Check the active sandbox for .pwc/run.json. Resume rather than restart when
  its URL matches and its status is non-terminal. Start a fresh run when the URL
  differs.

• Record the current phase and evidence after every successful phase and after
  every failure. The ledger is an audit trail, not a substitute for tool output.

2. Capture trustworthy source evidence

pwc extract <url>

• Require ok: true and
  summary.capture_integrity.status == "passed".

• Record source_id; use the same value for all later commands.

• Surface capture_residuals and the site_classification ceiling. If the page
  relies on WebGL, runtime canvas drawing, or scroll choreography that cannot be
  captured faithfully, continue only within the measured ceiling and keep it as
  a residual.

• Stop with failed_with_residuals if source integrity remains red after the
  extractor's retry budget. Never generate from guessed or partial content.

• Immediately inspect the capture inventory (screenshots, breakpoints, discovered
  interactions) in the source directory so breakpoint, state, and interaction
  expectations exist before code generation. Record them in .pwc/run.json.

3. Plan the complete page

pwc plan <source_id>

• Use the ordered real #main children as section and repair units.

• Treat every required_structure entry as a hard anchor, even when nested
  inside a large parent section.

• Review page geometry and source screenshots before authoring. Confirm that the
  plan spans the captured document height and contains the prominent regions
  visible in the raw evidence.

• Record all planned section ids in .pwc/run.json.

4. Create the shell and author every section

pwc assemble <source_id>

Missing section files are expected on this first call. Assembly initializes
.pwc/run.json; read, update, and rewrite that ledger as the agent advances.

For each planned section, in order:

1. pwc section <source_id> <section_name>
2. Author clean semantic JSX and scoped local styles from the section evidence.

3. Write only its namespaced component files under
   src/components/sections/<namespace>/.

4. Mark the section complete in .pwc/run.json.

Maintain whole-page layout tokens across sections. Reuse localized assets from
the capture. Never ship source-framework markup, source-specific class
fingerprints, hotlinked media, or an image snapshot in place of real content.
Use real text, images, links, video, and controls.

Apply these authoring requirements:

• Preserve sticky behavior and avoid clipping sticky ancestors.
• Reconstruct footer columns from source layout geometry.
• Render review widgets from captured review data.
• Emit functional localized video elements.

• Reveal recoverable lazy content instead of preserving an accidental empty
  capture state.

• Attach data-pwc-critical="<anchor>" to each required structural region.
• Keep the assembly-owned data-pwc-section wrapper for every section.

For each interaction contract:

• Implement its state transition and visible controlled surface.
• Attach data-pwc-interaction="<contract id>" to the control.

• Attach data-pwc-controlled="<contract id>" to the controlled surface where
  applicable.

• Support repeated activation where the source does, such as next/previous
  carousel steps and open/close menu or accordion behavior.

An unresolved asset, region, or behavior becomes an explicit residual.

5. Build before judging fidelity

pwc assemble <source_id>
pwc build

• Require no missing_section_files.
• Require success: true plus a produced dist/.
• On failure, read the build JSON, repair the owning component, and rebuild.

Never run acceptance scoring against a broken or stale build.

6. Verify in gate order

Start a local preview of dist/ and retain its URL for user review. Verify at
the captured breakpoints and observable states.

Run:

1. Source integrity from extraction.
2. Critical structure: every planned section and data-pwc-critical anchor exists.

3. Required interaction replay in the preview (carousel, menu, tabs, accordion).
   Static look-alikes fail.

4. pwc fingerprints <dist_dir>
5. pwc weight <dist_dir>

6. Screenshot the clone and
   pwc score --ref <source.png> --cand <clone.png>
   Use --sections with per-section bounds when heights differ.

7. Compare to a same-source baseline when one exists.

Do not treat one aggregate SSIM number as acceptance. Structure, interaction,
and each required breakpoint/state remain individually visible in the result.

7. Repair automatically

While a required gate is red and budget remains:

1. Select the earliest failed hard gate; within it select the worst measured
   section or state.

2. Map its evidence to the owning component using section bounds, interaction
   ids, screenshot diffs, and diagnostic output.

3. Read the current component and pwc section <source_id> <name>.

4. Make one evidence-based repair to that component or shared token when the
   evidence proves the error is global.

5. Rebuild and replay every affected structural, behavioral, and visual gate.

6. Update .pwc/run.json with the attempt, measurement delta, and evidence
   paths.

Use at most five repair attempts per breakpoint × state. Stop early after one
non-improving retry followed by a second attempt that also fails to improve the
same metric. Preserve the best measured candidate; do not leave a regression as
the final artifact.

8. Hand off honestly

Set ready_for_user_review only when:

• capture integrity passed;
• all planned sections and critical anchors exist materially;
• all required common interactions replay successfully;
• the production build passed;
• fingerprints and required budgets passed;
• required visual breakpoint/state gates passed; and
• every claimed result has an evidence path or tool output.

Otherwise set failed_with_residuals and list every residual with its gate,
section/state, expected value, measured value, evidence, attempts, and reason for
stopping.

Return the local review URL, source project path, dist/ path, evidence/report
paths, gate summary, and residuals. Say “ready for your review,” never “accepted”
or “pixel-perfect.” The user's visual and functional review is the final
decision.

Tool map

Authoring writes src/components/sections/<namespace>/ in the assembled
project. Preview is a local server on dist/. Interaction replay is done in
that preview; a visually similar but inert control fails.

Deterministic codegen (html_to_jsx) is a starting point, not the default path
for client-quality work.