docs: publish the Web Foundations application onramp

Sanitized snapshot of private source 144ca0a9544042b0477ae732c1356cf0b9d62b3f. Add package selection, adoption workflow, and optional Sandwich Hime integration guidance. AI-Assistance: OpenAI Codex assisted documentation, verification, and publication. Signed-off-by: Cole Speelman <crspeelman@gmail.com>
2026-08-16 21:10:18 -04:00
parent a18f1dd22a
commit 206d09e4cd
10 changed files with 282 additions and 15 deletions
@@ -0,0 +1,71 @@
+<!-- SPDX-License-Identifier: MPL-2.0 -->
+
+# HTML with Sandwich Hime
+
+Gamertan Web Foundations owns reusable web-application boundaries; it does not
+own HTML or a template language. [Sandwich Hime](https://sandwichhime.com/) is
+the preferred companion for Gamertan applications that want HTML-first,
+ahead-of-time templates with typed Go composition.
+
+The relationship is intentionally optional:
+
+| Application responsibility | Owner |
+| --- | --- |
+| Request identity, logging, security primitives, sessions, and analytics | Web Foundations packages selected by the application |
+| Routing, authorization decisions, status, headers, caching, and deployment | The application |
+| Visible HTML and typed component composition | Authored `.sando` templates |
+| Template parsing, contextual analysis, and Go generation | Hime-san during development or CI |
+| Rendering generated components | The small `sando` runtime in production |
+
+Web Foundations does not import Sandwich Hime. Sandwich Hime does not import
+Web Foundations. An application chooses both and provides the seam between
+them.
+
+## Request flow
+
+```text
+request
+  -> requestmeta / selected middleware
+  -> application router and handler
+  -> typed view data
+  -> generated Sandwich Hime component
+  -> buffered sando.Render
+  -> application-owned HTTP response
+```
+
+Buffer the component before committing a successful response so a rendering
+error can still become a clean application error:
+
+```go
+func renderHTML(response http.ResponseWriter, request *http.Request, status int, component sando.Component) {
+	var output bytes.Buffer
+	if err := sando.Render(request.Context(), &output, component); err != nil {
+		log.Printf("render page: %v", err)
+		response.Header().Set("Cache-Control", "no-store")
+		http.Error(response, "could not render page", http.StatusInternalServerError)
+		return
+	}
+	response.Header().Set("Content-Type", "text/html; charset=utf-8")
+	response.WriteHeader(status)
+	_, _ = response.Write(output.Bytes())
+}
+```
+
+The handler—not the template—should interpret request metadata, principals,
+permissions, analytics, or storage errors. It passes only the resulting typed
+display data into the component. Templates should not acquire an implicit
+request global or turn middleware context into an inheritance framework.
+
+Handwritten `sando.Component` implementations and `Trust*` values are explicit
+trusted-output capabilities. Keep them conspicuous and review them separately
+from ordinary untrusted values.
+
+## Continue with the official lessons
+
+- [Build a component, page, and small site](https://sandwichhime.com/docs/tutorial/).
+- [Follow a request through a larger Go application](https://sandwichhime.com/docs/tutorial/application/).
+- [Review the Sandwich Hime security boundary](https://sandwichhime.com/docs/security/).
+
+Those tutorials own the template syntax and compiler workflow. This repository
+documents only the application seam so the two projects do not drift into a
+single mandatory framework.