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

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.