c0py/docs/MASTERPLAN.md

C0PY Masterplan — Canonical Web Product Reconstruction Engine

Status: canonical Owner: C0PY Rule: this document and the C0PY IR contracts are the single source of truth for web/product capture and reconstruction across SIAX.

Mission

C0PY turns an observed web product into an evidence-backed digital twin specification that can be reconstructed, verified and repaired autonomously. The system must cover visual fidelity, responsive behavior, assets, interactions, workflows, network contracts, motion, accessibility and product topology.

Non-negotiable architecture

Source product
  -> discovery
  -> deterministic capture
  -> semantic exploration
  -> Canonical Evidence Graph / IR
  -> frozen reconstruction specs
  -> builder adapters
  -> preview deployment
  -> multidimensional verification
  -> repair loop
  -> production candidate

No crawler, AI builder or upstream project owns the truth. The Canonical IR owns the truth.

Canonical layers

1. Discovery — routes, sitemaps, links, navigation, semantic workflow discovery.
2. Capture — Playwright + CDP as primary runtime; DOM, CSSOM, computed styles, accessibility tree, screenshots, storage, network, WebSocket/SSE, canvas/media and performance.
3. Evidence — every assertion stores source, method, capture context, confidence and provenance.
4. Product model — entities, relationships, capabilities, permissions, workflows and state machines inferred from observed behavior.
5. Specification — deterministic page/component/workflow contracts generated from the evidence graph.
6. Reconstruction — adapters for v0, Lovable, Codex and generic agents. Builders consume specs; they do not inspect the source as authority.
7. Verification — geometry, typography, color, assets, routes, state, interaction, workflow, network, motion, accessibility and runtime health.
8. Repair — failures become typed root-cause work items and are repaired iteratively.

Primary technology decisions

• Browser runtime: Playwright.
• Deep browser instrumentation: Chrome DevTools Protocol.
• Crawl orchestration: Crawlee-compatible request graph.
• Session/event replay: rrweb adapter.
• Semantic exploration: Browser Use / Browser Harness adapters.
• Visual comparison: pixelmatch-compatible deterministic diff plus computed-style root cause analysis.
• Optional WebGL forensics: Spector.js adapter.
• Optional archival: SingleFile and Browsertrix only behind process/service adapters due to copyleft boundaries.
• Output target: clean SIAX architecture, normally Next.js + React + TypeScript, regardless of source framework.

Upstream capability policy

Every borrowed idea or implementation MUST be classified as one of:

• CORE — implemented and owned inside C0PY.
• DEPENDENCY — consumed as a package/library.
• CHERRY_PICK — imported/adapted source with exact provenance and license notice.
• ADAPTER — isolated integration behind a C0PY contract.
• REIMPLEMENT — behavior/specification reproduced without copying source.
• REFERENCE_ONLY — studied, never included in runtime.
• DROP — rejected duplicate or lower-value implementation.

See docs/UPSTREAM-CAPABILITY-MATRIX.md.

Canonical package topology

packages/
  types/                 canonical shared contracts
  c0py-core/
    discovery/
    capture/
    evidence/
    provenance/
    product-model/
    specification/
    verification/
    repair/
    adapters/

As implementation grows, high-cohesion modules may graduate into their own workspace packages, but they must continue to consume the same IR contracts.

Evidence model

Evidence confidence MUST use explicit semantics:

• measured: deterministic machine measurement.
• observed: directly observed behavior/state.
• inferred: reasoned from evidence, not directly visible.
• declared: supplied by an authorized configuration/specification.
• unknown: insufficient evidence.

invented is prohibited in clone mode. Adapt/blend mode may create new design/product choices, but they must be marked as synthetic and never confused with source evidence.

Operating modes

• clone — maximize observable fidelity; no creative substitutions without an explicit evidence gap.
• adapt — preserve approved product semantics while transforming brand/design/technology.
• blend — combine explicitly selected capabilities/patterns from multiple references into a new product; every source lineage remains traceable.

Quality gates

A single visual score is forbidden as the release criterion. C0PY uses a fidelity vector:

• geometry
• typography
• colors
• assets
• responsive states
• route coverage
• interaction/state coverage
• workflow coverage
• network-contract parity
• motion parity
• accessibility semantics
• console/runtime health
• production build health

Critical routes, contracted workflows and required interaction states must reach 100% coverage before a clone can be marked complete. Visual tolerances are profile-specific and recorded in the manifest.

Cross-repo rule

Other SIAX repositories may consume C0PY capabilities, evidence and generated specs, but MUST NOT fork a parallel capture ontology, fidelity model or reconstruction masterplan. Cross-repo integrations point back to C0PY contracts/versioned schemas.

Delivery order

1. Canonical IR + provenance.
2. Playwright/CDP capture.
3. route topology and deterministic extraction.
4. HAR/network evidence and authenticated capture profiles.
5. interaction/state delta engine.
6. rrweb replay/event timeline.
7. semantic workflow discovery adapters.
8. design-system extraction.
9. media/motion/WebGL adapters.
10. specification generator.
11. reconstruction adapters.
12. multidimensional QA.
13. autonomous repair loop.
14. clone/adapt/blend orchestration.
15. MCP/API contracts and fleet automations.