clone

an offline map explorer where each world, from a game map to a city's open data, ships as one .atlas file

main
atlas / docs / decisions / 0006-the-scene-description-seam.md
0006-the-scene-description-seam.md 2.5K rendered
1# 6. The seam is driven by an inert scene description23- **Date:** 2026-08-024- **Status:** accepted5- **Where it is written down:** issue #5 §5.5, §10 decision 12;6 [render-seam.md](../render-seam.md), [app.md](../app.md) §678## Context910Something has to draw the map, and whatever draws it cannot be hypermedia. The11risk is that the drawing code slowly becomes a second application: it starts12holding discrete state, it starts fetching things the server already knows, and13the "thin seam" becomes the place where the real logic lives — which is where14the reference implementation ended up.1516## Decision1718The server renders an **inert `#atlas-viewport-state` node** — data attributes19and `<data>` children, readable with no JavaScript running — and the seam20observes and reconciles it. `readScene(node)` is a pure, lenient function of a21node-shaped thing; `sceneChange(was, now)` names what moved (`volume`, `world`,22`lens`, `filters`, `selection`, `grid`, `camera`) and the seam acts on the23names, which is what makes a swap a reconcile rather than a rebuild.2425**Data flows one way** — server → scene description → seam. Exactly two things26flow back: the `atlas:pick` event and the debounced camera report.2728The seam stands on three published documents (the `/data` plane, the scene29description, the analysis API) and one duty (diagnostics), and on nothing else.30Two custom elements are its whole surface.3132**Deletability is a design principle, not a CI stunt.** It is upheld by33mechanisms: depcheck forbids inbound imports, the dependency surface is the34published contracts, custom elements are progressive by construction, and35`docs/render-seam.md` is held to the standard of a complete blind-rewrite36brief. No job deletes the folder to prove a point.3738## Consequences3940- The viewport is morph-skipped: a swap may touch its attributes, never its41 internals. That requirement is what lets the scene node live inside a page42 the server re-renders freely.43- Until the bundle loads, `<atlas-viewport>` is an unknown element that renders44 nothing and breaks nothing. The application serves a complete page with the45 seam's assets absent — asserted, not asserted-about, by the `seam-assets`46 waiver ([ADR 13](0013-assets-and-static-are-two-mounts.md)).47- The parity harness can compare server state and seam state under matching key48 names, because both publish diagnostics against one schema.49- A ~3,000 authored-line budget is tracked as a warning: a seam growing a50 second application inside it becomes visible in CI rather than later.