<!-- SPDX-License-Identifier: AGPL-3.0-only -->

# Sandwich Hime

Sandwich Hime is an HTML-first, ahead-of-time template engine for Go. Hime-san
keeps the direct, mixed-markup feeling of classic PHP while compiling trusted
`.sando` templates into typed, deterministic Go components that an ordinary
`go build` can audit and deploy.

```sando
<?sando go
package views

func Profile(page ProfileView)
?>
<section class="profile">
  <h1><?= page.Name ?></h1>
  <? if page.IsAdmin { ?>
    <?~ AdminBadge() ?>
  <? } ?>
</section>
```

The generated API is ordinary Go:

```go
func Profile(page ProfileView) sando.Component
```

Templates are what authors write. Components are the typed output and
composition unit. Hime-san is an intentionally opinionated development tool,
not an application framework: a consuming project keeps its `.sando` sources,
commits the adjacent `.sando.go` output, and imports only the small Apache-2.0
`sando` runtime. Hime-san never owns the router, middleware, layout policy,
request object, or production server.

## Status

This repository is an unsupported public pre-1.0 source preview, not a supported v1 release. EQL Wiki remains the proof-of-production proving ground, and v1 is gated on security testing, cross-platform determinism, and a 14-day production soak with no renderer, security, or accessibility regression.

[sandwichhime.com](https://sandwichhime.com/) is the running self-hosted proof:
its pages begin as `.sando`, compile into ordinary Go, and ship in an ordinary
Go service whose production binary links only the `sando` runtime—not this
compiler.

For repository development:

```sh
go install ./cmd/himesan
himesan generate ./examples/eql-shaped
himesan check ./examples/eql-shaped
go test ./...
(cd sando && go test ./...)
(cd examples/eql-shaped && himesan dev --config himesan.json)
```

The portable path is `generate`, `check`, and the project's normal Go tools.
For people who want the paved road, `himesan dev` deliberately does more: it
builds the application's own `net/http` program in the user cache,
health-checks a random loopback candidate, preserves the last healthy process,
and serves it through `http://127.0.0.1:7331` with local-only reload
diagnostics. That is a Cole-shaped convenience, not a production server or a
requirement. Take the paved path—or don't.

The eventual versioned installs are:

```sh
go install gamertan.com/sandwich-hime/cmd/himesan@v1.0.0
go get gamertan.com/sandwich-hime/sando@v1.0.0
```

Those vanity paths must not be advertised as working until the corresponding signed releases and `gamertan.com` metadata exist.

## The contract

- One typed template, compiled into one component constructor, per `.sando` file.
- Go statements are trusted source code; rendered values are untrusted.
- `<?= ... ?>` escapes for the statically known HTML context.
- `<?~ ... ?>` composes another component and propagates errors.
- Ambiguous or unsupported HTML contexts fail compilation.
- Generation is deterministic and formatted; each owned output is replaced atomically, and handwritten Go and `go.mod` are never edited.
- `check` is read-only and detects invalid or stale generated output.
- Production builds need no compiler binary.

The language is specified in [SPEC.md](SPEC.md). The security boundary is in [docs/THREAT_MODEL.md](docs/THREAT_MODEL.md), the development loop is in [docs/DEVELOPMENT_SERVER.md](docs/DEVELOPMENT_SERVER.md), and the multi-license boundary is in [LICENSES.md](LICENSES.md).

User-authored templates and generated application files remain under terms chosen by their authors to the extent they hold the necessary rights. The compiler is AGPL-3.0-only, the runtime is Apache-2.0, and [OUTPUT_EXCEPTION.md](OUTPUT_EXCEPTION.md) grants an additional permission for Cole Speelman-owned generator scaffolding copied into output.

## Names matter

- Project: **Sandwich Hime / Hime-san**
- CLI: `himesan`
- Template: `page.sando`
- Generated Go: `page.sando.go`
- Runtime: `sando`
- `.san`: reserved exclusively for the separate San language

The project is never marketed as bare “Hime”; that name is already used by an unrelated Go web framework.

## Why

This is a love letter to hand-built web development: the immediacy of Cole's
2004 Geocities page for a PSO Gameclub, with typed interfaces, reproducible
builds, modern contextual safety, and boring production operations. The first
prototype was a wonderfully cursed princess that could `bless` or `rebuke`
templates, announced when Hime-san was resting, and concluded that creating a
compiler was not hubris but destiny. The jokes stayed because developer joy is
part of the point. The security boundary grew up because care is part of the
point too.

Cole builds with ADHD, neurodivergence, a disabled body, finite energy, and a
family he wants to leave understandable work for. Clear files, calm defaults,
accessible documentation, last-good development builds, and honest limitations
are therefore operating requirements—not decorative empathy. The project aims
to leave room for individuals, tiny teams, learners, disabled people, and
anyone too small to win a complexity contest.

Open source permits corporate use. Independence comes instead from the
AGPL-3.0-only compiler, the Apache-2.0 runtime, application-owned generated
output, contributor-held copyright, founder-led governance, release-key
control, and careful trademark stewardship. Companies may use and contribute;
participation does not confer ownership of the identity or project.

The fuller origin, Japanese craft inspirations, family dedication, human-art
commitment, and stewardship boundary live on the
[project site](https://sandwichhime.com/docs/project/). Performance claims will
follow published measurements, never precede them.