Spec a no-backend site-planning studio POC on free, keyless map data

Write the proof-of-concept spec for a browser-based planning studio. The spec is the contract the build follows. Write the spec only, no code, except the generator's header comment (section 5) and the state shape (section 9).

Domain: {{domain}}
Users: {{users}}
Jurisdiction for the first presets: {{jurisdiction}}
Anything else the POC must do: {{brief}}

Fixed architecture (state it in section 1; don't debate it):
- Static files only: no backend, no build step, no API keys. Any static file server runs it.
- MapLibre GL JS and Turf are vendored as pinned files in vendor/. Pin MapLibre 5.x, its last script-tag build, and load it and Turf with plain script tags, or vendor MapLibre 6's maplibre-gl.mjs with maplibre-gl-worker.mjs beside it and import it from the app's modules. The app's own code is ES modules, one job per file.
- All data comes from free public services. Each sits behind a small interface with a timeout and a fallback, so a production API can replace it later without touching callers.
- One versioned state object holds the whole project. It persists to localStorage and exports and imports as JSON.

Write Markdown with exactly these sections, in this order. Prefer tables to prose, one line per row.

0. Decisions. What the POC proves, in one sentence. Then each choice the brief leaves open, with the simplest option marked **Assumed**. Use the units and currency of {{jurisdiction}}; never assume others.

1. Files. A tree of public/ with one line per file: its job, and the state keys it reads and writes.

2. External data. Columns: Service | Used for | Request | Timeout | Fallback | What the user sees | Production swap. Cover at least:
- Nominatim: forward search on submit, never per keystroke (its usage policy caps the whole app, all users together, at one request a second and bans autocomplete: fine for a POC, but proxy or swap it before launch). Reverse geocoding of the site centroid detects the country and first-level region (address.country_code, ISO3166-2-lvl4) and picks a constraint preset. A detected preset never overwrites envelope values the user has edited; offer it instead. Drop responses for a boundary that has since changed.
- AWS Terrain Tiles: Terrarium PNGs from s3.amazonaws.com/elevation-tiles-prod/terrarium/{z}/{x}/{y}.png, drawn to a canvas (crossOrigin "anonymous") and decoded as metres = (R × 256 + G + B / 256) − 32768, wrapped as sampler(lng, lat) → metres. If the tiles don't load, the sampler is null and the app plans on flat terrain and says so.
- Overpass: the OpenStreetMap features near the site that the generator's rules need (roads at least; name the exact tags for this domain). If it fails, the generator uses a stated default.
- A keyless raster basemap.
Show attribution for every source (the basemap, OpenStreetMap for Nominatim and Overpass, the terrain tiles' sources) on the map, and print it in the proposal.
No station may block on a third-party service. Add app layers on the map's style.load event, never load, which waits for basemap tiles. Cap any wait on idle (for example 5 s for the proposal snapshot).

3. Stations. Six stations, in this order: Site → Constraints → Generate → Buildings (massing) → Financials → Proposal. Rename each in the words of the domain; keep the order. Columns: # | Station | User does | App computes | Unlocked when | Writes to state | Invalidates. Changing the boundary clears everything generated from it. Changing a constraint marks the layout stale with a "regenerate to apply" note; it never silently rewrites the user's edits.

4. Constraints as data. Two tables.
- Envelope: the numeric limits the generator and checks read (for example density ratio, max height, setbacks, minimum open space, max coverage). Columns: Field | Unit | Generic default | {{jurisdiction}} preset | Read by (the generator rule or check that uses it). Each preset value cites its register row id and status. Cut any field nothing reads.
- Register: the research trail, one row per rule: {id, field, name, value, status, source: {document, clause, url, quote}, checked_on, reviewed}. field is the envelope field the row sets; checked_on is the date the source was read; reviewed stays null until a person ticks the row. status is verified, assumed (a typical value so the POC runs) or check (must be confirmed with the named authority). verified needs the document, the clause and a short quote of the text that holds the value; otherwise use check. Give 6–10 rows for {{jurisdiction}}, plus a generic preset used when reverse geocoding fails or returns a place with no preset.

5. Generator. First the header comment for the generator file, verbatim: a "Layout rules:" list of 5–8 rules for this domain, each naming the envelope field or data input it reads. This list is the generator's spec; any rule change updates it in the same commit. Then the method:
- Deterministic: the same inputs and seed give the same output. Fetched features and the terrain grid are generator inputs: store them in state, so regenerating after import gives identical output.
- Do the layout maths in metres, in a local frame centred on the site and rotated to its long axis. Convert to WGS84 GeoJSON only at the end.
- Include an access rule (connect at the boundary point closest to an existing road, with a fallback edge when Overpass fails), a terrain rule (the steepest ground goes to the least demanding use or stays open) and a placement-order rule (which use sits nearest the access and which farthest).
- Per-use dimensions come from one per-use table (size, default height, coverage, cost and revenue rates, efficiency), never magic numbers.
- Reject a site too small to lay out, with a message giving the minimum size.
- Output: named GeoJSON layers plus a stats object (area by use, lengths, counts, cut and fill when elevation exists).

6. Buildings. What the user adjusts per item, and the rule that sizes it (footprint inset by the setback and capped by coverage; height capped by the envelope). Clamp to the envelope wherever values are read, not only in the UI. Show a live total against the permitted total, with the overshoot when over.

7. Financials. Columns: Line | Formula over state | Default rate (marked **Assumed**) | Proposal section it lands in. Every total, margin and cashflow figure is computed from these lines, never typed. Rates are editable.

8. Proposal. The sections of a print-ready document (browser print to PDF): summary, map snapshot (create the map with canvasContextAttributes: { preserveDrawingBuffer: true }, a top-level option before MapLibre 5, so the canvas can be read), the constraint register with each row's status and source, an area schedule, the financial case. The proposal shows verified rows as cited, not reviewed, until a person ticks them. A readiness checklist gates the button.

9. State and persistence. The state shape as JSON with a version field. Save debounced to localStorage inside try/catch, so private mode and full storage fail quietly. Load only a matching version, deep-merged over the defaults (objects recursively, arrays and GeoJSON replaced whole) so new fields get values. Import rejects a file of the wrong shape with a clear message and keeps the current project.

10. POC cut and brainstorm. "POC v0.1 ships": every station end to end, each in its simplest working form; thin across all six beats deep in one. "Brainstorm (not in the POC)": grouped by station, each item naming the seam it plugs into (a file, interface or state key), for example an optimisation loop behind the same generator signature.

11. Later: AI research agent. How a model with web search fills the same register rows for a drawn site, taking source.url, source.quote and checked_on from pages it opened. The agent may set verified only with that full citation; everything else is check. Its rows arrive with reviewed null, and a person accepts each one before its value changes the envelope. The generator stays deterministic and reads only the envelope.

12. Acceptance tests. Include: with each external host blocked in turn (block it with Playwright's page.route(pattern, r => r.abort()) or a ?block=host test hook), all six stations still complete and show a note; the same seed and inputs give identical GeoJSON; export then import restores an identical project; an over-limit design shows its overshoot.

If the brief is too thin for a section, fill it with assumptions marked **Assumed** rather than skip it. Return only the spec, sections 0 to 12, as Markdown.

Show all 56 lines