diff --git a/README.md b/README.md index a734c79..476cb5a 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ ditto.site logo

-# ditto.site +# [ditto.site](https://ditto.site) [![CI](https://github.com/ion-design/ditto.site/actions/workflows/ci.yml/badge.svg)](https://github.com/ion-design/ditto.site/actions/workflows/ci.yml) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) @@ -15,6 +15,9 @@ Router project by default, or Vite React when requested. The compiler is not an LLM page author. It is a capture-to-code pipeline: same frozen capture in, byte-stable app out. +Read the public development and evaluation method in +[docs/METHODOLOGY.md](docs/METHODOLOGY.md). + ## Usage - REST API: `https://api.ditto.site` @@ -222,7 +225,8 @@ observed safely. Unsupported app logic, auth, payments, personalization, and arbitrary third-party JavaScript are not replayed. For the detailed service API, see [docs/SERVICE.md](docs/SERVICE.md). For -deployment, see [docs/DEPLOY.md](docs/DEPLOY.md). +deployment, see [docs/DEPLOY.md](docs/DEPLOY.md). For the development method +behind the compiler, see [docs/METHODOLOGY.md](docs/METHODOLOGY.md). Hosted deployments should keep `/v1/clones*` and `/mcp` behind API-key auth. When `SIGNUP_ENABLED=true` in DB mode, the Resend-backed @@ -241,7 +245,7 @@ minting is intentional. | `packages/db/` | Drizzle schema, migrations, repository, and queue wrapper | | `packages/storage/` | local and S3/R2 artifact storage | | `packages/worker/` | queued clone runner and optional verification | -| `docs/` | service, deployment, release, and responsible-use docs | +| `docs/` | methodology, service, deployment, release, and responsible-use docs | | `examples/` | benchmark results and visual evidence | ## Responsible Use diff --git a/docs/METHODOLOGY.md b/docs/METHODOLOGY.md new file mode 100644 index 0000000..8e9fd16 --- /dev/null +++ b/docs/METHODOLOGY.md @@ -0,0 +1,76 @@ +# Methodology + +ditto.site is built as a deterministic capture-to-code compiler. The goal is not +to author a plausible page from a prompt; it is to preserve what a browser +actually rendered and turn that evidence into a runnable app with repeatable +output. + +## Principles + +- **Observed evidence first.** The compiler starts from browser-captured DOM, + computed styles, layout boxes, CSS, assets, fonts, metadata, screenshots, and + interaction or motion signals when they can be observed safely. +- **Deterministic output.** A frozen capture should produce byte-stable app + output. Randomness, timestamps, network state, and heuristic ordering are kept + out of generated files. +- **Generated code over screenshots.** The output is a Next.js or Vite React app + with local assets, route modules, metadata, CSS, and small runtime helpers for + recognized interactions. Screenshots are used for validation, not delivery. +- **No private app replay.** Authenticated state, payments, personalization, + business logic, arbitrary third-party scripts, and access-controlled content + are not recreated. +- **Safety is part of correctness.** SSRF controls, rate limits, artifact + boundaries, and responsible-use limits are treated as part of the system, not + deployment afterthoughts. + +## Development Loop + +1. **Capture a representative fixture or benchmark page.** The browser capture + records the rendered page and the artifacts needed to reconstruct it. +2. **Normalize into a render IR.** Capture data is converted into stable + sections, tokens, assets, semantic metadata, and interaction candidates. +3. **Generate the app.** The generator emits framework files, styles, assets, + route structure, metadata, runtime helpers, and handoff docs. +4. **Validate by building and rendering.** Browser-backed checks compare source + and clone behavior, including structure, screenshots, links, SEO metadata, + responsive layout, interactions, and motion where supported. +5. **Lock regressions with focused tests.** Changes that affect compiler output + should add or update a fixture, unit test, or benchmark note so the behavior + remains explainable. +6. **Keep the service wrapper thin.** The REST, MCP, queue, database, and storage + packages call the compiler through the public barrel instead of reaching into + compiler internals. + +## Validation Gates + +The repository uses small, repeatable gates rather than one broad visual score: + +- TypeScript typechecking across every workspace. +- Node test suites for compiler output, API behavior, storage, cache keys, SSRF, + auth, MCP contracts, and queue/worker paths where infrastructure is available. +- Browser-gated fixture tests through Playwright and Chromium. +- Determinism checks that regenerate from one frozen capture and compare output. +- Optional benchmark runs for broader visual or route coverage. + +Heavy real-site benchmark sweeps are kept outside the default CI path. CI should +stay fast enough to run on every pull request; broader benchmark evidence is +attached when a change materially affects clone output. + +## Review Standard + +Compiler changes should answer three questions: + +- What new source evidence is captured or interpreted? +- How does generation stay deterministic? +- Which fixture, test, or benchmark proves the behavior? + +Service changes should keep the hosted API and MCP contracts stable, preserve +auth and SSRF guarantees, and avoid changing compiler semantics from the service +layer. + +## Safety Boundaries + +See [RESPONSIBLE_USE.md](RESPONSIBLE_USE.md) and [SECURITY.md](../SECURITY.md) +for the public-use and deployment controls. Changes that make phishing, +impersonation, access-control bypass, unbounded third-party capture, or unsafe +fetching easier are out of scope for this project.