Split embedded and standalone chart surfaces

bible-local/decisions/2026-03-15-embedded-vs-standalone-surfaces.md

@@ -0,0 +1,36 @@
+# Decision: Embedded And Standalone Surfaces Are Separate
+
+**Date:** 2026-03-15
+**Status:** active
+
+## Context
+
+`chart` has two legitimate use cases:
+
+- embedded inside another Go application that already knows how to locate and pass a snapshot
+- run as a standalone local tool for manual inspection of a JSON file
+
+These two use cases need different first-screen behavior.
+
+The embedded case must stay clean and must not force upload controls into a host application's UI.
+
+The standalone case still needs a practical way to open a snapshot from the browser.
+
+## Decision
+
+The project exposes two handler surfaces:
+
+- `viewer.NewHandler(...)` for embedded mode
+- `viewer.NewStandaloneHandler(...)` for standalone mode
+
+Embedded mode renders the viewer without upload controls on `GET /`.
+
+Standalone mode renders a first-screen upload form on `GET /` and posts the selected snapshot to `/render`.
+
+Both modes share the same read-only snapshot renderer and the same `/render` behavior once snapshot bytes are provided.
+
+## Consequences
+
+- Host applications can embed `chart` without inheriting standalone upload UI.
+- The standalone binary remains usable without requiring an external host application.
+- Future UI work must keep embedded and standalone entry surfaces separate.