spreadlab/docs/m4-handoff.md

Handoff: milestone 4 (single binary + deploy)

You are shipping spreadlab to Justin's server. Milestone 3 is done; this segment turns the repo into one deployable artifact: a Go binary with the built frontend embedded, a public container image, and a Portainer stack behind Caddy. Repo root: grant-proposal/tool/ (paths below relative to it).

State as of 2026-06-10

• All 12 M3 slices are merged and CI is green: the dashboard, playback, chart, controls, panel management, focus modal, tooltips, mobile pass, export, and the accessibility audit (results in commit d9b3812).
• docs/ui-spec.md was amended in place where the implementation deliberately deviates (playback pacing and trickle in 5.4, seed range in 5.3, viewBox and layout forces in 6, readingCaption in 1). The spec is normative again; do not "fix" the app back toward old numbers.
• Deploy shape is DECIDED in grant-proposal/tool-handoff.md (read it): multi-stage Dockerfile (node build, Go build with go:embed, minimal final image), a compose snippet for a Portainer stack joining the existing Caddy network, and a GitHub Actions job pushing a public image to ghcr.io on merge to main. No Docker in the dev loop: native ./dev.sh (tmux session "spreadlab", API :8080 + Vite :5173) stays.
• The UI already carries the "illustrative, not validated" framing everywhere, including PNG exports; deploy adds no copy.

Method

• This is Go/infra territory: Justin is learning Go from the diffs, so the M1/M2 working agreements apply again (unlike the fast autonomous Vue pace of M3). Micro-brief each new concept before the code: go:embed, http.FileServer over an embedded FS, multi-stage builds, GHCR auth and the packages:write permission. Small annotated diffs, one slice per commit, push after each, CI stays green.
• Verify each slice for real: run the binary and curl both / and /api; build the image once locally and run it; after the GHCR job lands, pull the public image and run it cold.
• go generate ./... + commit if generated types ever change (CI drift guard); nothing in this segment should need it.

The one design decision to settle first

//go:embed requires the embedded directory to exist at compile time, but web/dist/ is gitignored, so a naive embed breaks go test ./... for anyone (and CI) without a frontend build. Decide with Justin via AskUserQuestion, batched with the open choices below. Recommended: keep the embed in its own small package (e.g. internal/webdist) with a committed one-line placeholder dist/index.html ("run npm run build"); the Dockerfile overwrites it with the real build. Alternatives: build tags (dev binary without embed) or making CI build the frontend before every Go job.

Suggested slices (each leaves main shippable)

1. Serve the SPA from Go: embed web/dist, serve it on / alongside /api (single page, no client routes; unknown paths can 404). Local proof: npm run build, go run ./cmd/spreadlab, one origin serving both. The vite dev proxy keeps working unchanged.
2. Dockerfile: multi-stage (node build → Go build → minimal final image), plus .dockerignore. Build and run locally once to verify; Docker still stays out of the daily dev loop.
3. GHCR workflow: build and push ghcr.io/justinzeus/spreadlab on push to main (permissions: packages: write), then make the package public. Verify with a cold pull.
4. Portainer stack: compose snippet joining the external Caddy network plus the Caddyfile entry, documented in the README (deploy section). Justin applies it in Portainer; verify the public URL, both themes, a shared link with panels and focus, and a PNG export from the hosted app.

Small open choices (decide with Justin via AskUserQuestion, batched)

• Embed strategy for web/dist (see above; placeholder file recommended).
• Final image base: scratch vs distroless vs alpine (distroless static recommended: CA certs and tzdata without a shell).
• Image tags: latest + commit SHA on main (recommended) vs semver tags.
• Listen port and a /healthz endpoint for compose healthchecks (recommended: keep :8080, add the trivial healthz handler).
• The public hostname, and whether the Caddyfile entry is managed by hand on the server or checked into the repo as documentation.

Traps learned in M3 (do not rediscover)

• npm ci on CI rejects a lockfile that was updated incrementally after installs (missing optional deps like @emnapi/*); regenerate package-lock.json from scratch (rm -rf node_modules package-lock.json && npm install) whenever dependencies change.
• Prettier must never touch web/src/types/ (generated; CI drift guard). web/.prettierignore already enforces this; keep it.
• Headless theme screenshots: web/public/__light.html and __dark.html (gitignored one-liners that set localStorage and redirect; recreate if missing). Screenshot light, dark, and 390 px wide before calling visual work done.
• Compound shell commands need every pipe segment allowlisted, not just the chromium part.
• Playback feel is perceptual: if any slice touches animation, have Justin look at it running in his browser early, not after polish.

First steps

1. Read grant-proposal/tool-handoff.md (deploy shape, working agreements) and skim README + .github/workflows/ci.yml.
2. Batch the open choices above into one AskUserQuestion round.
3. Slice 1 with its micro-brief on go:embed; continue down the list.