Split embedded and standalone chart surfaces

bible-local/architecture/api-surface.md

@@ -4,30 +4,41 @@
 
 The package is intended to be embedded by other Go applications.
 
-Expected package shape:
+Current package shape:
 
 - `viewer.RenderHTML(snapshot []byte) ([]byte, error)`
-- `viewer.NewHandler(...) http.Handler`
+- `viewer.NewHandler(viewer.HandlerOptions{...}) http.Handler`
+- `viewer.NewStandaloneHandler(viewer.HandlerOptions{...}) http.Handler`
 
-Exact signatures may change during implementation, but the integration model is fixed:
+Integration model:
 
 - embedding app provides the JSON
 - chart renders HTML
+- embedded mode does not own snapshot selection UI
+- standalone mode may provide a local upload screen on `GET /`
 
 ## Expected Runtime Endpoints
 
 These endpoints are expected for the standalone binary only:
 
-- `GET /` - viewer page
-- `POST /render` - accept one Reanimator JSON payload and return rendered HTML or JSON render result
+- `GET /` - upload page
+- `POST /render` - accept one Reanimator JSON payload and return rendered HTML
 - `GET /healthz` - basic process health
 
+Embedded handler endpoints:
+
+- `GET /` - empty viewer shell with no upload controls
+- `POST /render` - accept one Reanimator JSON payload and return rendered HTML
+- `GET /healthz` - basic process health
+- `GET /static/...` - embedded static assets
+
 ## UI Route Rules
 
 - No multi-product navigation
 - No upload wizard with preview/confirm/execute stages
 - No collector/API-connect workflow
 - No background job polling API
+- Embedded mode must not force a file picker into host applications
 
 ## Response Rules
 

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.