Add methodology doc and site link

2026-06-30 12:24:59 -07:00
parent 46d8c150d3
commit 74219bb921
2 changed files with 83 additions and 3 deletions
@@ -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.