From 14954131bd7ef07f0ed00b2493e96d3fea9adbd9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Milan=20Felix=20=C5=A0ulc?= <rkfelix@gmail.com>
Date: Sat, 10 Oct 2026 21:32:23 +0200
Subject: [PATCH 01/12] feat(control-center): count a slot as ready only when
 its sidecar is up

/api/slots and /healthz only probed the VNC port, so a slot whose
sidecar was down showed as ready and opening a file then failed with
502. Probe the sidecar's /healthz too (1s timeout) and report vnc,
sidecar and ready (= both) per slot. The tab tooltip says which half
is down. First tests for internal/api cover all four combinations.
---
 AGENTS.md                     |  4 +-
 README.md                     |  4 +-
 internal/api/handlers.go      | 43 +++++++++++----
 internal/api/handlers_test.go | 99 +++++++++++++++++++++++++++++++++++
 web/app.js                    |  6 +++
 5 files changed, 141 insertions(+), 15 deletions(-)
 create mode 100644 internal/api/handlers_test.go

diff --git a/AGENTS.md b/AGENTS.md
index 27a863d..8158524 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -48,8 +48,8 @@ Listens on `:8080` (`LISTEN_ADDR`), plus TLS on `TLS_ADDR` when set.
 | Method | Path                     | Purpose |
 |--------|--------------------------|---------|
 | GET    | `/`                      | Landing page with `<iframe>` viewer + JS bridge. |
-| GET    | `/healthz`               | `{ready, total}` slot reachability summary; 503 when no slot is ready. |
-| GET    | `/api/slots`             | `{count, slots:[{idx, host, ip, path, ready}]}`. `ready` = VNC port accepts TCP (sidecar not probed). |
+| GET    | `/healthz`               | `{ready, total}` count of ready slots (VNC + sidecar up); 503 when none is ready. |
+| GET    | `/api/slots`             | `{count, slots:[{idx, host, ip, path, vnc, sidecar, ready}]}`. `vnc` = VNC port accepts TCP, `sidecar` = sidecar `/healthz` returns 200 within 1s, `ready` = both. |
 | POST   | `/api/slot/{i}/params`   | Forwarded verbatim to `<slot[i]>:7000/params`. |
 | POST   | `/api/slot/{i}/restart`  | Forwarded to `<slot[i]>:7000/restart` (requires `Content-Type: application/json`). |
 | ANY    | `/slot/{i}/*`            | Reverse proxy → `<slot[i]>:<novnc>` (HTTP + WS upgrade). |
diff --git a/README.md b/README.md
index 2a9ee1b..6055292 100644
--- a/README.md
+++ b/README.md
@@ -103,8 +103,8 @@ The system exposes two HTTP services. The **control-center** is the public entry
 | Method | Path                         | Purpose                              |
 |--------|------------------------------|--------------------------------------|
 | GET    | `/`                          | UI: iframe + URL bar + slot tabs     |
-| GET    | `/healthz`                   | `{ready, total}` reachability summary |
-| GET    | `/api/slots`                 | slot table with per-slot reachability |
+| GET    | `/healthz`                   | `{ready, total}` — slots whose desktop **and** sidecar answer; 503 when none |
+| GET    | `/api/slots`                 | slot table with per-slot `vnc`, `sidecar` and `ready` flags |
 | POST   | `/api/slot/{i}/params`       | forwards `{params:{url,…}}` to slot `i` |
 | POST   | `/api/slot/{i}/restart`      | restarts slot `i`'s container (requires `Content-Type: application/json`) |
 | ANY    | `/slot/{i}/*`                | reverse-proxy → `<slot[i]>:port` (HTTP + WS) |
diff --git a/internal/api/handlers.go b/internal/api/handlers.go
index 0d2bb63..3b44d1c 100644
--- a/internal/api/handlers.go
+++ b/internal/api/handlers.go
@@ -20,26 +20,34 @@ import (
 type Handlers struct {
 	Pool   *slots.Pool
 	Client *http.Client
+	// Probe is used for the sidecar /healthz check; short timeout so one
+	// hung sidecar can't stall /api/slots, which the UI polls every 5s.
+	Probe *http.Client
 }
 
 func New(pool *slots.Pool) *Handlers {
 	return &Handlers{
 		Pool:   pool,
 		Client: &http.Client{Timeout: 3 * time.Second},
+		Probe:  &http.Client{Timeout: time.Second},
 	}
 }
 
 type slotEntry struct {
-	Index int    `json:"idx"`
-	Host  string `json:"host"`
-	IP    string `json:"ip,omitempty"`
-	Path  string `json:"path"`
-	Ready bool   `json:"ready"`
+	Index   int    `json:"idx"`
+	Host    string `json:"host"`
+	IP      string `json:"ip,omitempty"`
+	Path    string `json:"path"`
+	VNC     bool   `json:"vnc"`
+	Sidecar bool   `json:"sidecar"`
+	Ready   bool   `json:"ready"`
 }
 
 // readiness probes every slot in parallel. IP is best-effort (empty on
 // resolution failure); Path is the same-origin prefix the browser uses to
-// build the iframe URL.
+// build the iframe URL. A slot is Ready only when both the VNC port accepts
+// TCP and the sidecar answers /healthz — otherwise the desktop shows up but
+// opening a file fails with 502.
 func (h *Handlers) readiness() (ready int, entries []slotEntry) {
 	all := h.Pool.All()
 	entries = make([]slotEntry, len(all))
@@ -48,12 +56,15 @@ func (h *Handlers) readiness() (ready int, entries []slotEntry) {
 		wg.Add(1)
 		go func(i int, s slots.Slot) {
 			defer wg.Done()
+			vnc, sidecar := probe(s.VNCAddr()), h.probeSidecar(s)
 			entries[i] = slotEntry{
-				Index: s.Index,
-				Host:  s.Host,
-				IP:    resolveIP(s.Host),
-				Path:  s.PathPrefix() + "/",
-				Ready: probe(s.VNCAddr()),
+				Index:   s.Index,
+				Host:    s.Host,
+				IP:      resolveIP(s.Host),
+				Path:    s.PathPrefix() + "/",
+				VNC:     vnc,
+				Sidecar: sidecar,
+				Ready:   vnc && sidecar,
 			}
 		}(i, s)
 	}
@@ -199,6 +210,16 @@ func probe(addr string) bool {
 	return true
 }
 
+func (h *Handlers) probeSidecar(s slots.Slot) bool {
+	resp, err := h.Probe.Get(s.SidecarURL() + "/healthz")
+	if err != nil {
+		return false
+	}
+	_, _ = io.Copy(io.Discard, resp.Body)
+	_ = resp.Body.Close()
+	return resp.StatusCode == http.StatusOK
+}
+
 func writeJSON(w http.ResponseWriter, status int, v any) {
 	w.Header().Set("Content-Type", "application/json")
 	w.WriteHeader(status)
diff --git a/internal/api/handlers_test.go b/internal/api/handlers_test.go
new file mode 100644
index 0000000..7c72e39
--- /dev/null
+++ b/internal/api/handlers_test.go
@@ -0,0 +1,99 @@
+package api
+
+import (
+	"encoding/json"
+	"net"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+
+	"github.com/dockette/viewdoc/internal/slots"
+)
+
+// closedAddr returns a loopback address nothing listens on.
+func closedAddr(t *testing.T) string {
+	t.Helper()
+	l, err := net.Listen("tcp", "127.0.0.1:0")
+	if err != nil {
+		t.Fatal(err)
+	}
+	addr := l.Addr().String()
+	_ = l.Close()
+	return addr
+}
+
+func sidecar(t *testing.T, status int) string {
+	t.Helper()
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path != "/healthz" {
+			http.NotFound(w, r)
+			return
+		}
+		w.WriteHeader(status)
+	}))
+	t.Cleanup(srv.Close)
+	return strings.TrimPrefix(srv.URL, "http://")
+}
+
+func TestReadinessRequiresVNCAndSidecar(t *testing.T) {
+	vnc := httptest.NewServer(http.NotFoundHandler())
+	t.Cleanup(vnc.Close)
+	vncUp := strings.TrimPrefix(vnc.URL, "http://")
+	vncDown := closedAddr(t)
+
+	cases := []struct {
+		name         string
+		vnc, sidecar string
+		wantVNC      bool
+		wantSidecar  bool
+	}{
+		{"both up", vncUp, sidecar(t, http.StatusOK), true, true},
+		{"sidecar unhealthy", vncUp, sidecar(t, http.StatusInternalServerError), true, false},
+		{"sidecar down", vncUp, closedAddr(t), true, false},
+		{"vnc down", vncDown, sidecar(t, http.StatusOK), false, true},
+	}
+
+	var entries []string
+	for _, c := range cases {
+		entries = append(entries, "http://"+c.vnc+"|http://"+c.sidecar)
+	}
+	pool, err := slots.FromCSV(strings.Join(entries, ","), slots.Defaults{})
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	rec := httptest.NewRecorder()
+	New(pool).Slots(rec, httptest.NewRequest(http.MethodGet, "/api/slots", nil))
+	var got struct {
+		Slots []slotEntry `json:"slots"`
+	}
+	if err := json.NewDecoder(rec.Body).Decode(&got); err != nil {
+		t.Fatal(err)
+	}
+	if len(got.Slots) != len(cases) {
+		t.Fatalf("got %d slots, want %d", len(got.Slots), len(cases))
+	}
+	for i, c := range cases {
+		e := got.Slots[i]
+		if e.VNC != c.wantVNC || e.Sidecar != c.wantSidecar || e.Ready != (c.wantVNC && c.wantSidecar) {
+			t.Errorf("%s: vnc=%v sidecar=%v ready=%v, want vnc=%v sidecar=%v ready=%v",
+				c.name, e.VNC, e.Sidecar, e.Ready, c.wantVNC, c.wantSidecar, c.wantVNC && c.wantSidecar)
+		}
+	}
+}
+
+func TestHealthzUnavailableWithoutReadySlot(t *testing.T) {
+	vnc := httptest.NewServer(http.NotFoundHandler())
+	t.Cleanup(vnc.Close)
+	// VNC is up but the sidecar is not: the slot must not count as ready.
+	pool, err := slots.FromCSV("http://"+strings.TrimPrefix(vnc.URL, "http://")+"|http://"+closedAddr(t), slots.Defaults{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	rec := httptest.NewRecorder()
+	New(pool).Healthz(rec, httptest.NewRequest(http.MethodGet, "/healthz", nil))
+	if rec.Code != http.StatusServiceUnavailable {
+		t.Fatalf("status = %d, want %d; body %s", rec.Code, http.StatusServiceUnavailable, rec.Body)
+	}
+}
diff --git a/web/app.js b/web/app.js
index 1e39df0..eff6280 100644
--- a/web/app.js
+++ b/web/app.js
@@ -154,6 +154,12 @@
       b.className = `tab tab-${getSlotState(s.idx).state}`;
       if (s.idx === activeSlot) b.classList.add('active');
       b.title = s.ip ? `${s.host} · ${s.ip}` : s.host;
+      // Say which half is down when the desktop is reachable but the sidecar
+      // (which opens files) isn't, or vice versa.
+      if (!s.ready) {
+        const down = [!s.vnc && 'desktop', !s.sidecar && 'sidecar'].filter(Boolean);
+        if (down.length) b.title += ` · ${down.join(' + ')} down`;
+      }
 
       const led = document.createElement('span');
       led.className = 'led';

From 36f3b5ce10649c218f874cc5f97a4ea944d8e157 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Milan=20Felix=20=C5=A0ulc?= <rkfelix@gmail.com>
Date: Sat, 10 Oct 2026 21:33:16 +0200
Subject: [PATCH 02/12] fix(ci): make the lint job pass on Go 1.27.2

- staticcheck v0.8.1 (latest release) can't read go1.27.2 export data
  and crashed the lint job, which skipped every image build. Pin the
  action to master commit 452d5bb86b45 until a newer release ships.
- With go.mod at go 1.27, staticcheck now flags SA1019:
  httputil.ReverseProxy.Director is deprecated since Go 1.26. Move the
  slot proxy to Rewrite. Rewrite strips inbound X-Forwarded-*, so append
  the client to X-Forwarded-For by hand to keep what upstreams saw
  (SetXForwarded would also add X-Forwarded-Host/Proto).
- Add internal/proxy tests (path strip, Host, identity encoding, XFF,
  bare-prefix redirect, HTML shim + JS rewrite); they pass against both
  the old Director code and the new Rewrite code.
---
 .github/workflows/docker.yml |   5 ++
 internal/proxy/proxy.go      |  44 +++++++++------
 internal/proxy/proxy_test.go | 106 +++++++++++++++++++++++++++++++++++
 3 files changed, 138 insertions(+), 17 deletions(-)
 create mode 100644 internal/proxy/proxy_test.go

diff --git a/.github/workflows/docker.yml b/.github/workflows/docker.yml
index 3a46a46..eb939d4 100644
--- a/.github/workflows/docker.yml
+++ b/.github/workflows/docker.yml
@@ -34,6 +34,11 @@ jobs:
         uses: dominikh/staticcheck-action@v1
         with:
           install-go: false
+          # v0.8.1 (latest release) can't read go1.27.2 export data ("export
+          # data version 5 is greater than maximum supported version 4").
+          # Pinned to a master commit verified against go1.27.2; switch
+          # back to a release tag once one newer than v0.8.1 ships.
+          version: "452d5bb86b45"
 
       - name: govulncheck
         run: go run golang.org/x/vuln/cmd/govulncheck@latest ./...
diff --git a/internal/proxy/proxy.go b/internal/proxy/proxy.go
index b3ef461..e2ed52e 100644
--- a/internal/proxy/proxy.go
+++ b/internal/proxy/proxy.go
@@ -5,6 +5,7 @@ import (
 	"crypto/tls"
 	"fmt"
 	"io"
+	"net"
 	"net/http"
 	"net/http/httputil"
 	"net/url"
@@ -36,26 +37,35 @@ const (
 func ForSlot(s slots.Slot) http.Handler {
 	prefix := s.PathPrefix()
 	target := &url.URL{Scheme: s.VNCScheme, Host: s.VNCAddr()}
-	rp := httputil.NewSingleHostReverseProxy(target)
+	rp := &httputil.ReverseProxy{
+		Rewrite: func(pr *httputil.ProxyRequest) {
+			// Strip prefix so the upstream sees its native paths.
+			pr.Out.URL.Path = stripPrefix(pr.In.URL.Path, prefix)
+			pr.Out.URL.RawPath = ""
+			// SetURL also sets the outbound Host header to target.Host.
+			pr.SetURL(target)
+			// Rewrite drops inbound X-Forwarded-*; re-append the client like
+			// the old Director-based proxy did. Not SetXForwarded: that also
+			// adds X-Forwarded-Host/Proto, which the upstreams never saw.
+			if ip, _, err := net.SplitHostPort(pr.In.RemoteAddr); err == nil {
+				if prior := pr.In.Header.Values("X-Forwarded-For"); len(prior) > 0 {
+					ip = strings.Join(prior, ", ") + ", " + ip
+				}
+				pr.Out.Header.Set("X-Forwarded-For", ip)
+			}
+			// Force identity encoding so ModifyResponse can patch the body in place.
+			pr.Out.Header.Set("Accept-Encoding", "identity")
+		},
+		ModifyResponse: func(resp *http.Response) error {
+			return rewriteResponse(resp, prefix)
+		},
+		ErrorHandler: func(w http.ResponseWriter, _ *http.Request, err error) {
+			http.Error(w, fmt.Sprintf("upstream error: %v", err), http.StatusBadGateway)
+		},
+	}
 	if target.Scheme == slots.SchemeHTTPS {
 		rp.Transport = insecureTransport
 	}
-	origDirector := rp.Director
-	rp.Director = func(req *http.Request) {
-		// Strip prefix so the upstream sees its native paths.
-		req.URL.Path = stripPrefix(req.URL.Path, prefix)
-		req.URL.RawPath = ""
-		origDirector(req)
-		req.Host = target.Host
-		// Force identity encoding so ModifyResponse can patch the body in place.
-		req.Header.Set("Accept-Encoding", "identity")
-	}
-	rp.ModifyResponse = func(resp *http.Response) error {
-		return rewriteResponse(resp, prefix)
-	}
-	rp.ErrorHandler = func(w http.ResponseWriter, _ *http.Request, err error) {
-		http.Error(w, fmt.Sprintf("upstream error: %v", err), http.StatusBadGateway)
-	}
 
 	// Redirect /slot/{i} → /slot/{i}/ so relative URLs in HTML resolve under
 	// the slot's prefix instead of `/slot/`.
diff --git a/internal/proxy/proxy_test.go b/internal/proxy/proxy_test.go
new file mode 100644
index 0000000..0dd911b
--- /dev/null
+++ b/internal/proxy/proxy_test.go
@@ -0,0 +1,106 @@
+package proxy
+
+import (
+	"io"
+	"net"
+	"net/http"
+	"net/http/httptest"
+	"strconv"
+	"strings"
+	"testing"
+
+	"github.com/dockette/viewdoc/internal/slots"
+)
+
+// upstreamSlot starts an upstream that records the last request it saw and
+// returns a slot pointing at it.
+func upstreamSlot(t *testing.T, h http.HandlerFunc) slots.Slot {
+	t.Helper()
+	up := httptest.NewServer(h)
+	t.Cleanup(up.Close)
+	host, port, err := net.SplitHostPort(strings.TrimPrefix(up.URL, "http://"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	p, _ := strconv.Atoi(port)
+	return slots.Slot{Index: 3, Host: host, VNCPort: p, VNCScheme: slots.SchemeHTTP}
+}
+
+func TestForSlotRewritesRequest(t *testing.T) {
+	var got *http.Request
+	s := upstreamSlot(t, func(w http.ResponseWriter, r *http.Request) {
+		got = r.Clone(r.Context())
+		w.Header().Set("Content-Type", "image/png")
+		_, _ = io.WriteString(w, "png")
+	})
+
+	req := httptest.NewRequest(http.MethodGet, "http://cc.example/slot/3/vnc/app.png?x=1", nil)
+	req.RemoteAddr = "10.0.0.9:5555"
+	req.Header.Set("X-Forwarded-For", "203.0.113.7")
+	req.Header.Set("Accept-Encoding", "gzip, br")
+	rec := httptest.NewRecorder()
+	ForSlot(s).ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusOK || rec.Body.String() != "png" {
+		t.Fatalf("response = %d %q", rec.Code, rec.Body.String())
+	}
+	checks := []struct{ name, got, want string }{
+		{"path", got.URL.Path, "/vnc/app.png"},
+		{"query", got.URL.RawQuery, "x=1"},
+		{"host", got.Host, s.VNCAddr()},
+		{"accept-encoding", got.Header.Get("Accept-Encoding"), "identity"},
+		{"x-forwarded-for", got.Header.Get("X-Forwarded-For"), "203.0.113.7, 10.0.0.9"},
+		{"x-forwarded-host", got.Header.Get("X-Forwarded-Host"), ""},
+		{"x-forwarded-proto", got.Header.Get("X-Forwarded-Proto"), ""},
+	}
+	for _, c := range checks {
+		if c.got != c.want {
+			t.Errorf("%s = %q, want %q", c.name, c.got, c.want)
+		}
+	}
+}
+
+func TestForSlotRedirectsBarePrefix(t *testing.T) {
+	s := upstreamSlot(t, func(http.ResponseWriter, *http.Request) {
+		t.Error("upstream must not be hit")
+	})
+	rec := httptest.NewRecorder()
+	ForSlot(s).ServeHTTP(rec, httptest.NewRequest(http.MethodGet, "/slot/3?resize=remote", nil))
+	if rec.Code != http.StatusTemporaryRedirect || rec.Header().Get("Location") != "/slot/3/?resize=remote" {
+		t.Fatalf("got %d Location=%q", rec.Code, rec.Header().Get("Location"))
+	}
+}
+
+func TestForSlotRewritesBodies(t *testing.T) {
+	s := upstreamSlot(t, func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("ETag", `"abc"`)
+		switch r.URL.Path {
+		case "/":
+			w.Header().Set("Content-Type", "text/html; charset=utf-8")
+			_, _ = io.WriteString(w, "<html><head><title>x</title></head></html>")
+		case "/app.js":
+			w.Header().Set("Content-Type", "application/javascript")
+			_, _ = io.WriteString(w, "if (window.isSecureContext) go();")
+		}
+	})
+	h := ForSlot(s)
+
+	rec := httptest.NewRecorder()
+	h.ServeHTTP(rec, httptest.NewRequest(http.MethodGet, "/slot/3/", nil))
+	body := rec.Body.String()
+	if !strings.HasPrefix(body, "<html><head><script>") || !strings.Contains(body, `var P = "\/slot\/3";`) {
+		t.Errorf("HTML shim not injected after <head>: %.120q", body)
+	}
+	if rec.Header().Get("Content-Length") != strconv.Itoa(len(body)) {
+		t.Errorf("Content-Length = %q, body is %d bytes", rec.Header().Get("Content-Length"), len(body))
+	}
+	if rec.Header().Get("ETag") != "" || rec.Header().Get("Cache-Control") != "no-store" {
+		t.Errorf("cache headers: ETag=%q Cache-Control=%q", rec.Header().Get("ETag"), rec.Header().Get("Cache-Control"))
+	}
+
+	rec = httptest.NewRecorder()
+	h.ServeHTTP(rec, httptest.NewRequest(http.MethodGet, "/slot/3/app.js", nil))
+	if got, want := rec.Body.String(), "if (window._viewdocSecure_) go();"; got != want {
+		t.Errorf("JS = %q, want %q", got, want)
+	}
+}

From 14e6d2e456965560350ec80606a4c03d30020063 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Milan=20Felix=20=C5=A0ulc?= <rkfelix@gmail.com>
Date: Sat, 10 Oct 2026 21:33:23 +0200
Subject: [PATCH 03/12] chore: small cleanups

- proxy: replace hand-rolled jsonString with encoding/json (also escapes
  <, > and &, so the slot prefix can't close the shim's <script>); gofmt
  the shim doc-comment list.
- api: paramsForLog prints keys sorted, so identical requests log
  identically.
- web: open the ?url= doc in a slot only the first time it's shown, not
  on every tab switch (re-sending stacked duplicate windows in apps that
  hand off to a running instance).
- control-center: drop trailing blank line (gofmt).
---
 cmd/control-center/main.go |  1 -
 internal/api/handlers.go   | 22 +++++------
 internal/proxy/proxy.go    | 77 +++++++++++++-------------------------
 web/app.js                 |  8 +++-
 4 files changed, 42 insertions(+), 66 deletions(-)

diff --git a/cmd/control-center/main.go b/cmd/control-center/main.go
index 43524a4..07b06db 100644
--- a/cmd/control-center/main.go
+++ b/cmd/control-center/main.go
@@ -155,4 +155,3 @@ func logMiddleware(h http.Handler) http.Handler {
 		log.Printf("%s %s %s", r.Method, r.URL.Path, time.Since(start))
 	})
 }
-
diff --git a/internal/api/handlers.go b/internal/api/handlers.go
index 0d2bb63..e1f1e18 100644
--- a/internal/api/handlers.go
+++ b/internal/api/handlers.go
@@ -6,10 +6,13 @@ import (
 	"fmt"
 	"io"
 	"log"
+	"maps"
 	"mime"
 	"net"
 	"net/http"
+	"slices"
 	"strconv"
+	"strings"
 	"sync"
 	"time"
 
@@ -169,25 +172,22 @@ func (h *Handlers) Restart(w http.ResponseWriter, r *http.Request) {
 	_, _ = io.Copy(w, resp.Body)
 }
 
-// paramsForLog renders the sanitized params as space-separated k=v pairs and
-// truncates long values so log lines stay readable.
+// paramsForLog renders the sanitized params as space-separated k=v pairs,
+// sorted by key so identical requests log identically, and truncates long
+// values so log lines stay readable.
 func paramsForLog(p map[string]string) string {
 	if len(p) == 0 {
 		return "(empty)"
 	}
-	var b bytes.Buffer
-	first := true
-	for k, v := range p {
-		if !first {
-			b.WriteByte(' ')
-		}
-		first = false
+	pairs := make([]string, 0, len(p))
+	for _, k := range slices.Sorted(maps.Keys(p)) {
+		v := p[k]
 		if len(v) > 120 {
 			v = v[:117] + "..."
 		}
-		fmt.Fprintf(&b, "%s=%q", k, v)
+		pairs = append(pairs, fmt.Sprintf("%s=%q", k, v))
 	}
-	return b.String()
+	return strings.Join(pairs, " ")
 }
 
 func probe(addr string) bool {
diff --git a/internal/proxy/proxy.go b/internal/proxy/proxy.go
index b3ef461..48b6d96 100644
--- a/internal/proxy/proxy.go
+++ b/internal/proxy/proxy.go
@@ -3,6 +3,7 @@ package proxy
 import (
 	"bytes"
 	"crypto/tls"
+	"encoding/json"
 	"fmt"
 	"io"
 	"net/http"
@@ -127,30 +128,30 @@ func rewriteResponse(resp *http.Response, prefix string) error {
 //
 // What the shim does, top to bottom:
 //
-//   1. _viewdocSecure_ = true — kclient (Webtop) gates VideoDecoder access on
-//      `isSecureContext`. The body rewriter renames that property in the JS
-//      bundle to `_viewdocSecure_`, and we set it true here so the gate clears
-//      over plain http.
+//  1. _viewdocSecure_ = true — kclient (Webtop) gates VideoDecoder access on
+//     `isSecureContext`. The body rewriter renames that property in the JS
+//     bundle to `_viewdocSecure_`, and we set it true here so the gate clears
+//     over plain http.
 //
-//   2. Seed KasmVNC clipboard settings in localStorage. KasmVNC 1.18 detects
-//      iframe embedding (window.self !== window.top) and, unless the URL has
-//      ?show_control_bar=…, takes an "embedded" branch that initSettings
-//      clipboard_up/down/seamless = false — deliberately disabling host↔guest
-//      clipboard sync. initSetting is a no-op when the key already exists, so
-//      writing them here wins and leaves the rest of the embedded-mode chrome
-//      (hidden control bar, resize=remote) intact. Webtop's kclient uses
-//      different, URL-prefixed keys so it's unaffected.
+//  2. Seed KasmVNC clipboard settings in localStorage. KasmVNC 1.18 detects
+//     iframe embedding (window.self !== window.top) and, unless the URL has
+//     ?show_control_bar=…, takes an "embedded" branch that initSettings
+//     clipboard_up/down/seamless = false — deliberately disabling host↔guest
+//     clipboard sync. initSetting is a no-op when the key already exists, so
+//     writing them here wins and leaves the rest of the embedded-mode chrome
+//     (hidden control bar, resize=remote) intact. Webtop's kclient uses
+//     different, URL-prefixed keys so it's unaffected.
 //
-//   3. wrap()/WebSocket/fetch/XHR/EventSource patches — rewrite any same-origin
-//      absolute URL the upstream JS constructs at runtime (`/websockify`,
-//      `/api/audio`, …) to prepend the slot prefix. Comparing URL.host (not
-//      origin) is deliberate: ws:// URLs have a different scheme than the
-//      page's https://, so origin never matches and KasmVNC's
-//      `new WebSocket("wss://host:8443/websockify")` would slip through.
+//  3. wrap()/WebSocket/fetch/XHR/EventSource patches — rewrite any same-origin
+//     absolute URL the upstream JS constructs at runtime (`/websockify`,
+//     `/api/audio`, …) to prepend the slot prefix. Comparing URL.host (not
+//     origin) is deliberate: ws:// URLs have a different scheme than the
+//     page's https://, so origin never matches and KasmVNC's
+//     `new WebSocket("wss://host:8443/websockify")` would slip through.
 //
-//   4. console hook — forwards each iframe's console messages to the parent
-//      via postMessage so DevTools on the outer page shows a unified
-//      "[slot N] …" stream instead of requiring frame-filter juggling.
+//  4. console hook — forwards each iframe's console messages to the parent
+//     via postMessage so DevTools on the outer page shows a unified
+//     "[slot N] …" stream instead of requiring frame-filter juggling.
 const htmlShimTemplate = `<script>
 (function () {
   window._viewdocSecure_ = true;
@@ -253,40 +254,12 @@ const htmlShimTemplate = `<script>
 </script>`
 
 func htmlShim(prefix string) string {
-	p, _ := jsonString(prefix)
+	// json.Marshal also escapes <, > and &, so the prefix can never close
+	// the surrounding <script> tag.
+	p, _ := json.Marshal(prefix)
 	return fmt.Sprintf(htmlShimTemplate, p)
 }
 
-// jsonString produces a JSON-encoded string literal without pulling in encoding/json.
-func jsonString(s string) (string, error) {
-	var b strings.Builder
-	b.WriteByte('"')
-	for _, r := range s {
-		switch r {
-		case '"', '\\', '/':
-			b.WriteByte('\\')
-			b.WriteRune(r)
-		case '\n':
-			b.WriteString(`\n`)
-		case '\r':
-			b.WriteString(`\r`)
-		case '\t':
-			b.WriteString(`\t`)
-		default:
-			if r < 0x20 {
-				b.WriteString(`\u00`)
-				const hex = "0123456789abcdef"
-				b.WriteByte(hex[r>>4])
-				b.WriteByte(hex[r&0xf])
-			} else {
-				b.WriteRune(r)
-			}
-		}
-	}
-	b.WriteByte('"')
-	return b.String(), nil
-}
-
 func rewriteBody(resp *http.Response, fn func([]byte) []byte) error {
 	body, err := io.ReadAll(resp.Body)
 	if err != nil {
diff --git a/web/app.js b/web/app.js
index 1e39df0..7104a0a 100644
--- a/web/app.js
+++ b/web/app.js
@@ -36,7 +36,7 @@
 
   function getSlotState(idx) {
     let s = slotState.get(idx);
-    if (!s) { s = { frame: null, state: 'idle' }; slotState.set(idx, s); }
+    if (!s) { s = { frame: null, state: 'idle', pushedURL: null }; slotState.set(idx, s); }
     return s;
   }
 
@@ -185,12 +185,16 @@
     u.searchParams.set('slot', String(i));
     history.replaceState(null, '', u);
 
+    // Open the current ?url= doc in a slot the first time it's shown, not on
+    // every tab switch — re-sending stacks duplicate windows in apps that
+    // hand off to an already-running instance.
     const docURL = u.searchParams.get('url');
-    if (docURL) pushParams({ url: docURL });
+    if (docURL && getSlotState(i).pushedURL !== docURL) pushParams({ url: docURL });
   }
 
   async function pushParams(p) {
     console.log(`[viewdoc] push slot=${activeSlot}`, p);
+    if (p.url) getSlotState(activeSlot).pushedURL = p.url;
     try {
       const r = await fetch(`/api/slot/${activeSlot}/params`, {
         method: 'POST',

From 84d4f65d9c69835d9fbb249fd4fe71781ff62a77 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Milan=20Felix=20=C5=A0ulc?= <rkfelix@gmail.com>
Date: Sat, 10 Oct 2026 21:33:44 +0200
Subject: [PATCH 04/12] test(proxy): accept either JSON escaping of the slot
 prefix in the shim

---
 internal/proxy/proxy_test.go | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/internal/proxy/proxy_test.go b/internal/proxy/proxy_test.go
index 0dd911b..9e1c76e 100644
--- a/internal/proxy/proxy_test.go
+++ b/internal/proxy/proxy_test.go
@@ -88,7 +88,8 @@ func TestForSlotRewritesBodies(t *testing.T) {
 	rec := httptest.NewRecorder()
 	h.ServeHTTP(rec, httptest.NewRequest(http.MethodGet, "/slot/3/", nil))
 	body := rec.Body.String()
-	if !strings.HasPrefix(body, "<html><head><script>") || !strings.Contains(body, `var P = "\/slot\/3";`) {
+	// Accept "\/slot\/3" and "/slot/3": both are valid JSON for the prefix.
+	if !strings.HasPrefix(body, "<html><head><script>") || !strings.Contains(strings.ReplaceAll(body, `\/`, "/"), `var P = "/slot/3";`) {
 		t.Errorf("HTML shim not injected after <head>: %.120q", body)
 	}
 	if rec.Header().Get("Content-Length") != strconv.Itoa(len(body)) {

From 4dfa91b5b928d0c2fd500865198983cb587f405d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Milan=20Felix=20=C5=A0ulc?= <rkfelix@gmail.com>
Date: Sun, 11 Oct 2026 12:39:10 +0200
Subject: [PATCH 05/12] feat: report each slot's latest request via /status

Opening a file only answered {"ok":true} once the hook was forked;
download failures, refused URLs and crashed apps were visible only in
the viewer's logs.

- viewdoc.sh records the outcome in /tmp/viewdoc.status: refused,
  deduped, downloading, failed (+ error) or launched (+ app). A
  dispatch helper names the app; $STATE also keeps the exit code.
- Sidecar: GET /status returns {phase, url, app, error, updated,
  app_state, exit_code}. POST /params marks the request queued first,
  app_state comes from $STATE (a dead running pid reads as exited),
  and startup clears the file like the last-URL file.
- Control-center: GET /api/slot/{i}/status relays it (1s timeout).
- UI: status next to the buttons for the active slot, polled every 1s
  while queued/downloading and every 5s otherwise.
- Tests for the sidecar handler and the relay; docs for both APIs.
---
 .docker/viewdoc.sh            |  61 ++++++++++++------
 AGENTS.md                     |   3 +
 README.md                     |   2 +
 cmd/control-center/main.go    |   1 +
 cmd/sidecar/main.go           | 112 +++++++++++++++++++++++++++++++++-
 cmd/sidecar/main_test.go      | 101 ++++++++++++++++++++++++++++++
 internal/api/handlers.go      |  26 ++++++++
 internal/api/handlers_test.go |  40 ++++++++++++
 web/app.js                    |  50 +++++++++++++++
 web/index.html                |   1 +
 web/style.css                 |  12 ++++
 11 files changed, 390 insertions(+), 19 deletions(-)
 create mode 100644 cmd/sidecar/main_test.go

diff --git a/.docker/viewdoc.sh b/.docker/viewdoc.sh
index 0fd243c..008e462 100644
--- a/.docker/viewdoc.sh
+++ b/.docker/viewdoc.sh
@@ -12,6 +12,8 @@ QUERY_ENV="/tmp/viewdoc.env"
 LAST="/tmp/.viewdoc_last_url"
 STATE="/tmp/.viewdoc_last_state"
 LOG="/tmp/viewdoc.log"
+# Latest outcome for the sidecar's GET /status (key=value lines).
+STATUS="/tmp/viewdoc.status"
 # A launcher that exits 0 faster than this handed the URL to an already
 # running instance (chromium, soffice, xdg-open) rather than failing.
 HANDOFF_SECS=5
@@ -25,6 +27,18 @@ log() {
   printf '%s\n' "$msg" >&2 || true
 }
 
+# status <phase> [app] [error] — records the outcome of this request for the
+# sidecar's GET /status. Never load-bearing, like log().
+status() {
+  {
+    printf 'phase=%s\n' "$1"
+    printf 'url=%s\n' "$(printf '%s' "$url" | tr '\n' ' ')"
+    printf 'app=%s\n' "${2:-}"
+    printf 'error=%s\n' "${3:-}"
+    printf 'updated=%s\n' "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+  } > "$STATUS.$$" 2>/dev/null && mv -f "$STATUS.$$" "$STATUS" 2>/dev/null || true
+}
+
 [ -r "$QUERY_ENV" ] || { log "no $QUERY_ENV; nothing to do"; exit 0; }
 # shellcheck disable=SC1090
 . "$QUERY_ENV"
@@ -35,13 +49,14 @@ if [ -z "$url" ]; then
   exit 0
 fi
 
-# $STATE is "<pid> <running|handoff|exited>" for the launch that wrote $LAST.
+# $STATE is "<pid> <running|handoff|exited> [rc]" for the launch that wrote
+# $LAST (rc once it has exited).
 # The URL counts as still open while that launch's process is alive, or when
 # it handed off to an existing instance (whose window we can't track). A
 # crashed or closed app ("exited") lets the same URL open again.
 is_open() {
   local pid state
-  read -r pid state < "$STATE" 2>/dev/null || return 1
+  read -r pid state _ < "$STATE" 2>/dev/null || return 1
   case "$state" in
     handoff) return 0 ;;
     running) kill -0 "$pid" 2>/dev/null ;;
@@ -53,11 +68,12 @@ is_open() {
 # "--version.mp4" would be parsed as an option. Only real URLs get through.
 case "$url" in
   http://*|https://*) ;;
-  *) log "not an http(s) URL, refusing: $url"; exit 0 ;;
+  *) log "not an http(s) URL, refusing: $url"; status refused "" "not an http(s) URL"; exit 0 ;;
 esac
 
 if [ -r "$LAST" ] && [ "$(cat "$LAST")" = "$url" ] && is_open; then
   log "dedup hit, $url already open"
+  status deduped
   exit 0
 fi
 
@@ -68,10 +84,12 @@ download() {
   local f
   f="$(mktemp --suffix=".$ext" /tmp/viewdoc-dl.XXXXXXXX)"
   log "download $url -> $f"
+  status downloading "$app"
   if curl -fsSL --max-time 60 -o "$f" "$url"; then
     printf '%s' "$f"
   else
     log "download failed url=$url"
+    status failed "$app" "download failed"
     rm -f "$f"
     return 1
   fi
@@ -81,6 +99,13 @@ lower="$(printf '%s' "$url" | tr '[:upper:]' '[:lower:]')"
 path="${lower%%\?*}"; path="${path%%#*}"
 ext="${path##*.}"
 
+# dispatch <app> names the app this request goes to (for logs + status).
+app=""
+dispatch() {
+  app="$1"
+  log "dispatch=$app ext=$ext url=$url"
+}
+
 run() {
   log "exec: $*"
   # tee fans the launched app's combined stdout/stderr to both the single
@@ -100,7 +125,7 @@ run() {
     owner=""
     read -r owner _ < "$STATE" 2>/dev/null || true
     if [ "$owner" = "$BASHPID" ]; then
-      printf '%s %s\n' "$BASHPID" "$state" > "$STATE"
+      printf '%s %s %s\n' "$BASHPID" "$state" "$rc" > "$STATE"
     fi
     log "exit: $1 rc=$rc state=$state"
   ) &
@@ -108,17 +133,18 @@ run() {
   # doesn't make the next identical request a no-op.
   printf '%s %s\n' "$!" running > "$STATE"
   printf '%s' "$url" > "$LAST"
+  status launched "${app:-$1}"
 }
 
 case "$ext" in
   mp4|mkv|webm|mov|avi|mpeg|mpg|m4v|3gp|3g2|ts|mts|m2ts|vob|wmv|asf|divx|ogv|mp3|wav|flac|ogg|m4a|aac|opus|mka|wma|aiff|ape|mid)
-    log "dispatch=vlc ext=$ext url=$url"
+    dispatch vlc
     # --no-qt-privacy-ask suppresses VLC's first-run "Privacy and Network
     # Access Policy" modal, which otherwise blocks playback until clicked.
     run vlc --no-qt-privacy-ask --no-video-title-show "$url"
     ;;
   doc|docx|odt|rtf|xls|xlsx|ods|csv|ppt|pptx|odp|odg|vsd|vsdx|pub|pages|key|numbers)
-    log "dispatch=soffice ext=$ext url=$url"
+    dispatch soffice
     # soffice handles http(s) URLs natively via UCB. --view opens read-only,
     # --norestore kills the "recover document?" prompt after a previous
     # session, --nologo suppresses the splash. Visio / Publisher / Apple
@@ -130,13 +156,13 @@ case "$ext" in
     # open. curl runs synchronously here because the sidecar already forked
     # viewdoc.sh as a separate process, so blocking here doesn't delay the
     # sidecar's HTTP response. RAR5 needs unrar (p7zip-full only reads RAR4).
-    log "dispatch=xarchiver ext=$ext url=$url"
+    dispatch xarchiver
     if tmpfile="$(download)"; then
       run xarchiver "$tmpfile"
     fi
     ;;
   pcap|pcapng|cap)
-    log "dispatch=wireshark ext=$ext url=$url"
+    dispatch wireshark
     if tmpfile="$(download)"; then
       run wireshark -r "$tmpfile"
     fi
@@ -151,7 +177,7 @@ case "$ext" in
     # rewritten every time because claws-mail saves its own copies on exit.
     cfgdir="/tmp/viewdoc-claws"
     inbox="$cfgdir/Mail/inbox"
-    log "dispatch=claws-mail ext=$ext url=$url"
+    dispatch claws-mail
     if tmpfile="$(download)"; then
       # Outlook .msg is an OLE compound file claws-mail can't read; msgconvert
       # (libemail-outlook-message-perl) rewrites it as MIME first.
@@ -159,6 +185,7 @@ case "$ext" in
         eml="${tmpfile%.msg}.eml"
         if ! msgconvert --outfile "$eml" "$tmpfile" >&2; then
           log "msgconvert failed url=$url"
+          status failed "$app" "msgconvert failed"
           exit 0
         fi
         tmpfile="$eml"
@@ -192,13 +219,13 @@ CFG
   tif|tiff|heic|heif|avif|ico|tga)
     # Formats Chromium won't render. ristretto decodes via gdk-pixbuf, with
     # heif-gdk-pixbuf / libavif-gdk-pixbuf adding HEIC and AVIF.
-    log "dispatch=ristretto ext=$ext url=$url"
+    dispatch ristretto
     if tmpfile="$(download)"; then
       run ristretto "$tmpfile"
     fi
     ;;
   epub|djvu|xps|oxps|cbz|cbr|cb7)
-    log "dispatch=atril ext=$ext url=$url"
+    dispatch atril
     if tmpfile="$(download)"; then
       run atril "$tmpfile"
     fi
@@ -206,7 +233,7 @@ CFG
   txt|log|json|yaml|yml|xml|md|ini|conf|cfg|toml)
     # Downloaded rather than handed to Chromium: servers often send these as
     # application/octet-stream, which Chromium saves instead of showing.
-    log "dispatch=mousepad ext=$ext url=$url"
+    dispatch mousepad
     if tmpfile="$(download)"; then
       run mousepad "$tmpfile"
     fi
@@ -218,19 +245,19 @@ CFG
     fi
     ;;
   dxf)
-    log "dispatch=librecad ext=$ext url=$url"
+    dispatch librecad
     if tmpfile="$(download)"; then
       run librecad "$tmpfile"
     fi
     ;;
   ttf|otf|ttc)
-    log "dispatch=gnome-font-viewer ext=$ext url=$url"
+    dispatch gnome-font-viewer
     if tmpfile="$(download)"; then
       run gnome-font-viewer "$tmpfile"
     fi
     ;;
   bin|exe|dll|so|o|elf|dat|dmp)
-    log "dispatch=ghex ext=$ext url=$url"
+    dispatch ghex
     if tmpfile="$(download)"; then
       run ghex "$tmpfile"
     fi
@@ -244,12 +271,12 @@ CFG
     # the container leaves a stale lock that wedges every new launch).
     for b in chromium chromium-browser google-chrome chrome; do
       if command -v "$b" >/dev/null 2>&1; then
-        log "dispatch=$b ext=$ext url=$url"
+        dispatch "$b"
         run "$b" --no-sandbox --user-data-dir=/tmp/viewdoc-chromium --new-window "$url"
         exit 0
       fi
     done
-    log "dispatch=xdg-open ext=$ext url=$url"
+    dispatch xdg-open
     run xdg-open "$url"
     ;;
 esac
diff --git a/AGENTS.md b/AGENTS.md
index 8158524..96f9fd9 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -52,6 +52,7 @@ Listens on `:8080` (`LISTEN_ADDR`), plus TLS on `TLS_ADDR` when set.
 | GET    | `/api/slots`             | `{count, slots:[{idx, host, ip, path, vnc, sidecar, ready}]}`. `vnc` = VNC port accepts TCP, `sidecar` = sidecar `/healthz` returns 200 within 1s, `ready` = both. |
 | POST   | `/api/slot/{i}/params`   | Forwarded verbatim to `<slot[i]>:7000/params`. |
 | POST   | `/api/slot/{i}/restart`  | Forwarded to `<slot[i]>:7000/restart` (requires `Content-Type: application/json`). |
+| GET    | `/api/slot/{i}/status`   | Relays `<slot[i]>:7000/status` (1s timeout); 502 when the sidecar is down. |
 | ANY    | `/slot/{i}/*`            | Reverse proxy → `<slot[i]>:<novnc>` (HTTP + WS upgrade). |
 | GET    | `/*`                     | Embedded UI assets from `web/` (`embed.FS`), e.g. `/app.js`, `/style.css`. |
 
@@ -64,6 +65,7 @@ Binds to `:7000` in every viewer image. No auth — compose network is the trust
 | POST   | `/params`   | Validate, atomically write `/tmp/viewdoc.{json,env}`, fork `viewdoc.sh`. |
 | GET    | `/healthz`  | Liveness — plain-text `ok`. |
 | POST   | `/restart`  | Reply 202, exit 42. Kasm's `custom_startup.sh` / Webtop's s6 `finish` turn that into a container exit; the orchestrator restarts it (see README → *Restarting a slot*). |
+| GET    | `/status`   | Latest request: `{phase, url, app, error, updated, app_state, exit_code}`. `phase` is `idle` (none since start), `queued` (set by the sidecar on `POST /params`), then `refused` / `deduped` / `downloading` / `failed` / `launched` from `viewdoc.sh` (via `/tmp/viewdoc.status`). For `launched` / `deduped`, `app_state` is `running` / `handoff` / `exited` from `/tmp/.viewdoc_last_state` (a dead `running` pid reads as `exited`). |
 
 `POST /params` body: `{"params": {"<key>": "<value>", ...}}`. Sanitization: key `^[A-Za-z][A-Za-z0-9_]{0,63}$`, ≤32 keys, ≤4096 bytes/value.
 
@@ -106,6 +108,7 @@ Drive the host page with agent-browser (`fill #url-input` + `click #url-form but
 
 When a file load looks broken, check in order:
 1. `curl -sk <host>/api/slot/<i>/params -d '{"params":{"url":"…"}}'` returns `{"ok":true}` — proves the sidecar wrote `/tmp/viewdoc.{json,env}` and forked the hook.
+   Then `curl -sk <host>/api/slot/<i>/status` says what the hook did (`refused`, `failed` + `error`, `launched` + `app_state`). The UI shows the same next to the buttons.
 2. The browser/VLC window is *open* in the desktop — `viewdoc.sh` skips a URL equal to the last one (`/tmp/.viewdoc_last_url`) while that launch is still open: its process is alive, or it handed off to an already-running instance (exit 0 within 5s, e.g. a second Chromium/LibreOffice window). `/tmp/.viewdoc_last_state` holds `<pid> <running|handoff|exited>`. A failed download, a crash, or closing a VLC/Xarchiver/Wireshark window lets the same URL open again; a closed handed-off window can't be detected, so resubmitting that URL stays a no-op. Downloads land in unique `/tmp/viewdoc-dl.*` files, pruned after a day.
 3. The slot's iframe is actually connected (KasmVNC shows "Connection Terminated: a new primary client connected" at the bottom when a fresh client takes over — that banner is normal, not an error).
 
diff --git a/README.md b/README.md
index 6055292..d6baa15 100644
--- a/README.md
+++ b/README.md
@@ -107,6 +107,7 @@ The system exposes two HTTP services. The **control-center** is the public entry
 | GET    | `/api/slots`                 | slot table with per-slot `vnc`, `sidecar` and `ready` flags |
 | POST   | `/api/slot/{i}/params`       | forwards `{params:{url,…}}` to slot `i` |
 | POST   | `/api/slot/{i}/restart`      | restarts slot `i`'s container (requires `Content-Type: application/json`) |
+| GET    | `/api/slot/{i}/status`       | what happened to slot `i`'s latest request (see sidecar `/status`) |
 | ANY    | `/slot/{i}/*`                | reverse-proxy → `<slot[i]>:port` (HTTP + WS) |
 | GET    | `/*`                         | embedded UI assets (`/app.js`, `/style.css`) |
 
@@ -179,6 +180,7 @@ VIEWER_SLOTS="kasm://node-1,webtop://node-2"
 | GET    | `/healthz`  | plain-text `ok`                                          |
 | POST   | `/params`   | validate + atomically write `/tmp/viewdoc.{json,env}`, fork `viewdoc.sh` |
 | POST   | `/restart`  | reply 202, then exit with code 42 — the image turns that into a container exit |
+| GET    | `/status`   | latest request: `phase` (`idle`, `queued`, `refused`, `deduped`, `downloading`, `failed`, `launched`), `url`, `app`, `error`, `updated`, and for launched apps `app_state` (`running`, `handoff`, `exited`) + `exit_code` |
 
 #### Environment
 
diff --git a/cmd/control-center/main.go b/cmd/control-center/main.go
index 07b06db..de551ce 100644
--- a/cmd/control-center/main.go
+++ b/cmd/control-center/main.go
@@ -63,6 +63,7 @@ func main() {
 	mux.HandleFunc("GET /api/slots", h.Slots)
 	mux.HandleFunc("POST /api/slot/{idx}/params", h.Params)
 	mux.HandleFunc("POST /api/slot/{idx}/restart", h.Restart)
+	mux.HandleFunc("GET /api/slot/{idx}/status", h.Status)
 	mux.HandleFunc("GET /favicon.ico", func(w http.ResponseWriter, _ *http.Request) {
 		w.WriteHeader(http.StatusNoContent)
 	})
diff --git a/cmd/sidecar/main.go b/cmd/sidecar/main.go
index 528d4b4..6ba1e9f 100644
--- a/cmd/sidecar/main.go
+++ b/cmd/sidecar/main.go
@@ -14,7 +14,9 @@ import (
 	"os/exec"
 	"path/filepath"
 	"slices"
+	"strconv"
 	"strings"
+	"syscall"
 	"time"
 
 	"github.com/dockette/viewdoc/internal/sanitize"
@@ -34,14 +36,28 @@ const (
 	restartExitCode = 42
 )
 
+// Shared with viewdoc.sh. Vars so tests can point them at a temp dir.
+var (
+	// statusPath holds key=value lines describing the latest request:
+	// phase (queued|refused|deduped|downloading|failed|launched), url, app,
+	// error, updated.
+	statusPath = "/tmp/viewdoc.status"
+	// statePath is "<pid> <running|handoff|exited> [rc]" for the last app
+	// viewdoc.sh launched.
+	statePath = "/tmp/.viewdoc_last_state"
+)
+
 func main() {
 	addr := envOr("LISTEN_ADDR", ":7000")
 
 	// viewdoc.sh skips a URL equal to the last one it opened. Compose's
 	// restart policy reuses the container (and its /tmp), so a fresh
 	// desktop would otherwise refuse to reopen the pre-restart URL.
-	if err := os.Remove(lastPath); err != nil && !errors.Is(err, fs.ErrNotExist) {
-		log.Printf("clear %s: %v", lastPath, err)
+	// The status of a pre-restart request would be stale for the same reason.
+	for _, p := range []string{lastPath, statusPath} {
+		if err := os.Remove(p); err != nil && !errors.Is(err, fs.ErrNotExist) {
+			log.Printf("clear %s: %v", p, err)
+		}
 	}
 
 	mux := http.NewServeMux()
@@ -50,6 +66,7 @@ func main() {
 	})
 	mux.HandleFunc("POST /params", handleParams)
 	mux.HandleFunc("POST /restart", handleRestart)
+	mux.HandleFunc("GET /status", handleStatus)
 
 	srv := &http.Server{
 		Addr:              addr,
@@ -85,6 +102,11 @@ func handleParams(w http.ResponseWriter, r *http.Request) {
 		http.Error(w, err.Error(), http.StatusInternalServerError)
 		return
 	}
+	// Mark the request as queued right away so /status never shows the
+	// previous request's outcome while viewdoc.sh is still starting.
+	if err := writeStatus("queued", clean["url"]); err != nil {
+		log.Printf("write status: %v", err)
+	}
 	go fireHook()
 
 	w.Header().Set("Content-Type", "application/json")
@@ -107,6 +129,92 @@ func handleRestart(w http.ResponseWriter, _ *http.Request) {
 	}()
 }
 
+// handleStatus reports what happened to the latest request, plus whether the
+// app it launched is still up. Phase "idle" means no request since start.
+func handleStatus(w http.ResponseWriter, _ *http.Request) {
+	w.Header().Set("Content-Type", "application/json")
+	_ = json.NewEncoder(w).Encode(readStatus())
+}
+
+type status struct {
+	Phase    string `json:"phase"`
+	URL      string `json:"url,omitempty"`
+	App      string `json:"app,omitempty"`
+	Error    string `json:"error,omitempty"`
+	Updated  string `json:"updated,omitempty"`
+	AppState string `json:"app_state,omitempty"` // running|handoff|exited
+	ExitCode *int   `json:"exit_code,omitempty"`
+}
+
+func readStatus() status {
+	b, err := os.ReadFile(statusPath)
+	if err != nil {
+		return status{Phase: "idle"}
+	}
+	var st status
+	for line := range strings.Lines(string(b)) {
+		k, v, _ := strings.Cut(strings.TrimRight(line, "\n"), "=")
+		switch k {
+		case "phase":
+			st.Phase = v
+		case "url":
+			st.URL = v
+		case "app":
+			st.App = v
+		case "error":
+			st.Error = v
+		case "updated":
+			st.Updated = v
+		}
+	}
+	// Only these phases refer to the app recorded in statePath.
+	if st.Phase == "launched" || st.Phase == "deduped" {
+		st.AppState, st.ExitCode = readAppState()
+	}
+	return st
+}
+
+// readAppState interprets statePath. A "running" pid that no longer exists
+// (killed, or a container restart reused /tmp) is reported as exited.
+func readAppState() (string, *int) {
+	b, err := os.ReadFile(statePath)
+	if err != nil {
+		return "", nil
+	}
+	f := strings.Fields(string(b))
+	if len(f) < 2 {
+		return "", nil
+	}
+	var code *int
+	if len(f) > 2 {
+		if n, err := strconv.Atoi(f[2]); err == nil {
+			code = &n
+		}
+	}
+	if f[1] == "running" {
+		pid, err := strconv.Atoi(f[0])
+		if err != nil || !alive(pid) {
+			return "exited", code
+		}
+	}
+	return f[1], code
+}
+
+// alive reports whether pid exists; EPERM means it does, owned by another user.
+func alive(pid int) bool {
+	if pid <= 0 {
+		return false
+	}
+	err := syscall.Kill(pid, 0)
+	return err == nil || errors.Is(err, syscall.EPERM)
+}
+
+func writeStatus(phase, url string) error {
+	url = strings.ReplaceAll(url, "\n", " ")
+	return atomicWrite(statusPath, fmt.Appendf(nil, "phase=%s\nurl=%s\napp=\nerror=\nupdated=%s\n",
+		phase, url, time.Now().UTC().Format(time.RFC3339)))
+}
+
 func writeQuery(m map[string]string) error {
 	jsonBytes, err := json.Marshal(m)
 	if err != nil {
diff --git a/cmd/sidecar/main_test.go b/cmd/sidecar/main_test.go
new file mode 100644
index 0000000..2a83057
--- /dev/null
+++ b/cmd/sidecar/main_test.go
@@ -0,0 +1,101 @@
+package main
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"strconv"
+	"testing"
+)
+
+func useTempStatus(t *testing.T) {
+	t.Helper()
+	dir := t.TempDir()
+	oldStatus, oldState := statusPath, statePath
+	statusPath, statePath = filepath.Join(dir, "status"), filepath.Join(dir, "state")
+	t.Cleanup(func() { statusPath, statePath = oldStatus, oldState })
+}
+
+func write(t *testing.T, path, s string) {
+	t.Helper()
+	if err := os.WriteFile(path, []byte(s), 0o644); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func getStatus(t *testing.T) status {
+	t.Helper()
+	rec := httptest.NewRecorder()
+	handleStatus(rec, httptest.NewRequest(http.MethodGet, "/status", nil))
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status code %d", rec.Code)
+	}
+	var st status
+	if err := json.Unmarshal(rec.Body.Bytes(), &st); err != nil {
+		t.Fatal(err)
+	}
+	return st
+}
+
+func TestStatusIdleWithoutFile(t *testing.T) {
+	useTempStatus(t)
+	if st := getStatus(t); st.Phase != "idle" {
+		t.Fatalf("phase = %q, want idle", st.Phase)
+	}
+}
+
+func TestStatusQueuedFromWriteStatus(t *testing.T) {
+	useTempStatus(t)
+	if err := writeStatus("queued", "https://x/a.pdf\nevil=1"); err != nil {
+		t.Fatal(err)
+	}
+	st := getStatus(t)
+	if st.Phase != "queued" || st.URL != "https://x/a.pdf evil=1" || st.Updated == "" {
+		t.Fatalf("got %+v", st)
+	}
+	if st.AppState != "" {
+		t.Fatalf("queued must not report app state, got %q", st.AppState)
+	}
+}
+
+func TestStatusFailedCarriesError(t *testing.T) {
+	useTempStatus(t)
+	write(t, statusPath, "phase=failed\nurl=https://x/a.zip\napp=xarchiver\nerror=download failed\nupdated=2026-10-11T08:00:00Z\n")
+	st := getStatus(t)
+	if st.Phase != "failed" || st.App != "xarchiver" || st.Error != "download failed" {
+		t.Fatalf("got %+v", st)
+	}
+}
+
+func TestStatusAppState(t *testing.T) {
+	self := strconv.Itoa(os.Getpid())
+	cases := []struct {
+		name, state string
+		want        string
+		wantCode    int // -1 = no exit code
+	}{
+		{"running and alive", self + " running\n", "running", -1},
+		{"running but gone", "999999999 running\n", "exited", -1},
+		{"handoff", self + " handoff 0\n", "handoff", 0},
+		{"exited with code", self + " exited 127\n", "exited", 127},
+	}
+	for _, c := range cases {
+		t.Run(c.name, func(t *testing.T) {
+			useTempStatus(t)
+			write(t, statusPath, "phase=launched\nurl=https://x/a.mp4\napp=vlc\nerror=\nupdated=2026-10-11T08:00:00Z\n")
+			write(t, statePath, c.state)
+			st := getStatus(t)
+			if st.AppState != c.want {
+				t.Fatalf("app_state = %q, want %q", st.AppState, c.want)
+			}
+			switch {
+			case c.wantCode < 0 && st.ExitCode != nil:
+				t.Fatalf("exit_code = %d, want none", *st.ExitCode)
+			case c.wantCode >= 0 && (st.ExitCode == nil || *st.ExitCode != c.wantCode):
+				t.Fatalf("exit_code = %v, want %d", st.ExitCode, c.wantCode)
+			}
+		})
+	}
+}
diff --git a/internal/api/handlers.go b/internal/api/handlers.go
index f17d37b..2ed5bc8 100644
--- a/internal/api/handlers.go
+++ b/internal/api/handlers.go
@@ -183,6 +183,32 @@ func (h *Handlers) Restart(w http.ResponseWriter, r *http.Request) {
 	_, _ = io.Copy(w, resp.Body)
 }
 
+// Status relays the slot sidecar's GET /status (latest request's phase, app,
+// error, and whether the launched app is still running).
+func (h *Handlers) Status(w http.ResponseWriter, r *http.Request) {
+	idx, err := strconv.Atoi(r.PathValue("idx"))
+	if err != nil {
+		http.NotFound(w, r)
+		return
+	}
+	slot, ok := h.Pool.Get(idx)
+	if !ok {
+		http.Error(w, "slot not found", http.StatusNotFound)
+		return
+	}
+	req, _ := http.NewRequestWithContext(r.Context(), http.MethodGet, slot.SidecarURL()+"/status", nil)
+	resp, err := h.Probe.Do(req)
+	if err != nil {
+		http.Error(w, fmt.Sprintf("sidecar unreachable: %v", err), http.StatusBadGateway)
+		return
+	}
+	defer resp.Body.Close()
+	w.Header().Set("Content-Type", "application/json")
+	w.Header().Set("Cache-Control", "no-store")
+	w.WriteHeader(resp.StatusCode)
+	_, _ = io.Copy(w, resp.Body)
+}
+
 // paramsForLog renders the sanitized params as space-separated k=v pairs,
 // sorted by key so identical requests log identically, and truncates long
 // values so log lines stay readable.
diff --git a/internal/api/handlers_test.go b/internal/api/handlers_test.go
index 7c72e39..a1ade56 100644
--- a/internal/api/handlers_test.go
+++ b/internal/api/handlers_test.go
@@ -97,3 +97,43 @@ func TestHealthzUnavailableWithoutReadySlot(t *testing.T) {
 		t.Fatalf("status = %d, want %d; body %s", rec.Code, http.StatusServiceUnavailable, rec.Body)
 	}
 }
+
+func TestStatusRelaysSidecar(t *testing.T) {
+	const body = `{"phase":"launched","app":"vlc","app_state":"running"}` + "\n"
+	sc := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.Method != http.MethodGet || r.URL.Path != "/status" {
+			http.NotFound(w, r)
+			return
+		}
+		_, _ = w.Write([]byte(body))
+	}))
+	t.Cleanup(sc.Close)
+
+	pool, err := slots.FromCSV("http://"+closedAddr(t)+"|"+sc.URL+",http://"+closedAddr(t)+"|http://"+closedAddr(t), slots.Defaults{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	mux := http.NewServeMux()
+	mux.HandleFunc("GET /api/slot/{idx}/status", New(pool).Status)
+
+	cases := []struct {
+		path     string
+		wantCode int
+		wantBody string
+	}{
+		{"/api/slot/0/status", http.StatusOK, body},
+		{"/api/slot/1/status", http.StatusBadGateway, ""},
+		{"/api/slot/9/status", http.StatusNotFound, ""},
+		{"/api/slot/x/status", http.StatusNotFound, ""},
+	}
+	for _, c := range cases {
+		rec := httptest.NewRecorder()
+		mux.ServeHTTP(rec, httptest.NewRequest(http.MethodGet, c.path, nil))
+		if rec.Code != c.wantCode {
+			t.Errorf("%s: code %d, want %d", c.path, rec.Code, c.wantCode)
+		}
+		if c.wantBody != "" && rec.Body.String() != c.wantBody {
+			t.Errorf("%s: body %q, want %q", c.path, rec.Body.String(), c.wantBody)
+		}
+	}
+}
diff --git a/web/app.js b/web/app.js
index 8160038..0707ab6 100644
--- a/web/app.js
+++ b/web/app.js
@@ -5,6 +5,7 @@
   const input = document.getElementById('url-input');
   const resetBtn = document.getElementById('url-reset');
   const restartBtn = document.getElementById('slot-restart');
+  const statusEl = document.getElementById('slot-status');
 
   // Surface iframe console messages on the outer page so a single DevTools
   // console shows everything across slots. The shim in proxy.go posts these.
@@ -196,6 +197,54 @@
     // hand off to an already-running instance.
     const docURL = u.searchParams.get('url');
     if (docURL && getSlotState(i).pushedURL !== docURL) pushParams({ url: docURL });
+    else loadStatus();
+  }
+
+  // Status of the active slot's latest request (sidecar GET /status). Polled
+  // fast while a request is in flight, slowly otherwise; statusGen drops
+  // responses that arrive after a newer poll or a tab switch.
+  const BUSY_PHASES = new Set(['queued', 'downloading']);
+  let statusGen = 0;
+  let statusTimer = null;
+
+  async function loadStatus() {
+    const gen = ++statusGen;
+    const idx = activeSlot;
+    clearTimeout(statusTimer);
+    let st = null;
+    if (getSlotState(idx).state !== 'restarting') {
+      try {
+        const r = await fetch(`/api/slot/${idx}/status`);
+        if (r.ok) st = await r.json();
+      } catch {}
+    }
+    if (gen !== statusGen) return;
+    renderStatus(st);
+    statusTimer = setTimeout(loadStatus, st && BUSY_PHASES.has(st.phase) ? 1000 : 5000);
+  }
+
+  function describeStatus(st) {
+    const app = st.app || 'app';
+    switch (st.phase) {
+      case 'queued': return ['queued…', 'busy'];
+      case 'downloading': return [`${app}: downloading…`, 'busy'];
+      case 'refused': return [`refused: ${st.error || 'invalid URL'}`, 'error'];
+      case 'failed': return [`${app}: ${st.error || 'failed'}`, 'error'];
+      case 'deduped': return ['already open', 'ok'];
+      case 'launched':
+        if (st.app_state === 'exited') {
+          return st.exit_code ? [`${app} exited (${st.exit_code})`, 'error'] : [`${app} closed`, ''];
+        }
+        return [`${app} · open`, 'ok'];
+      default: return ['', ''];
+    }
+  }
+
+  function renderStatus(st) {
+    const [text, kind] = st ? describeStatus(st) : ['', ''];
+    statusEl.textContent = text;
+    statusEl.className = kind ? `status-${kind}` : '';
+    statusEl.title = st && st.url ? `${st.url}${st.updated ? ` · ${st.updated}` : ''}` : '';
   }
 
   async function pushParams(p) {
@@ -211,6 +260,7 @@
     } catch (e) {
       console.error(`[viewdoc] push slot=${activeSlot} failed`, e);
     }
+    loadStatus();
   }
 
   form.addEventListener('submit', (e) => {
diff --git a/web/index.html b/web/index.html
index 8bdb110..a7135c4 100644
--- a/web/index.html
+++ b/web/index.html
@@ -16,6 +16,7 @@
       <button id="url-reset" type="button" class="danger">Reset</button>
       <button id="slot-restart" type="button" class="danger" title="Restart the active slot's container">Restart</button>
     </form>
+    <span id="slot-status" aria-live="polite"></span>
   </header>
   <main id="viewer"></main>
   <script src="/app.js"></script>
diff --git a/web/style.css b/web/style.css
index 749fcb2..c055b74 100644
--- a/web/style.css
+++ b/web/style.css
@@ -156,6 +156,18 @@ header {
   letter-spacing: 0.3px;
 }
 #url-form button:hover { filter: brightness(1.1); }
+#slot-status {
+  flex: 0 1 auto;
+  max-width: 36ch;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  font-size: 11px;
+  color: var(--fg-dim);
+}
+#slot-status.status-ok    { color: var(--led-connected); }
+#slot-status.status-busy  { color: var(--led-loading); }
+#slot-status.status-error { color: var(--led-down); }
 #url-form button.danger {
   background: var(--led-down);
 }

From 40e2ed6ae5fd247466bd3606f862c602cbf862be Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Milan=20Felix=20=C5=A0ulc?= <rkfelix@gmail.com>
Date: Sun, 11 Oct 2026 12:55:44 +0200
Subject: [PATCH 06/12] fix(sanitize): reject non-http(s) url params and
 colliding keys
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

viewdoc.sh already refuses non-http(s) URLs, but the control-center and
sidecar accepted anything, so a value like --version.mp4 travelled all
the way to the hook. Validate in internal/sanitize (used by both):

- url (any case — keys are upper-cased into VIEWDOC_Q_*) must be an
  absolute http:// or https:// URL with a host;
- keys that are equal after upper-casing are rejected, since they would
  map to the same shell variable.

First tests for internal/sanitize.
---
 AGENTS.md                        |  2 +-
 internal/sanitize/params.go      | 34 ++++++++++++++++
 internal/sanitize/params_test.go | 68 ++++++++++++++++++++++++++++++++
 3 files changed, 103 insertions(+), 1 deletion(-)
 create mode 100644 internal/sanitize/params_test.go

diff --git a/AGENTS.md b/AGENTS.md
index 96f9fd9..6ab0efe 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -67,7 +67,7 @@ Binds to `:7000` in every viewer image. No auth — compose network is the trust
 | POST   | `/restart`  | Reply 202, exit 42. Kasm's `custom_startup.sh` / Webtop's s6 `finish` turn that into a container exit; the orchestrator restarts it (see README → *Restarting a slot*). |
 | GET    | `/status`   | Latest request: `{phase, url, app, error, updated, app_state, exit_code}`. `phase` is `idle` (none since start), `queued` (set by the sidecar on `POST /params`), then `refused` / `deduped` / `downloading` / `failed` / `launched` from `viewdoc.sh` (via `/tmp/viewdoc.status`). For `launched` / `deduped`, `app_state` is `running` / `handoff` / `exited` from `/tmp/.viewdoc_last_state` (a dead `running` pid reads as `exited`). |
 
-`POST /params` body: `{"params": {"<key>": "<value>", ...}}`. Sanitization: key `^[A-Za-z][A-Za-z0-9_]{0,63}$`, ≤32 keys, ≤4096 bytes/value.
+`POST /params` body: `{"params": {"<key>": "<value>", ...}}`. Sanitization (`internal/sanitize`, applied by both the control-center and the sidecar): key `^[A-Za-z][A-Za-z0-9_]{0,63}$`, ≤32 keys, ≤4096 bytes/value, no two keys equal after upper-casing (they'd map to the same `VIEWDOC_Q_*` variable), and `url` (any case) must be an absolute `http://` / `https://` URL with a host — apps get it as a bare argument, so anything else could be read as an option. `viewdoc.sh` repeats the http(s) check.
 
 ## Files (testing)
 
diff --git a/internal/sanitize/params.go b/internal/sanitize/params.go
index 4299f5c..5fd6189 100644
--- a/internal/sanitize/params.go
+++ b/internal/sanitize/params.go
@@ -2,7 +2,9 @@ package sanitize
 
 import (
 	"fmt"
+	"net/url"
 	"regexp"
+	"strings"
 )
 
 const (
@@ -14,11 +16,17 @@ var keyRe = regexp.MustCompile(`^[A-Za-z][A-Za-z0-9_]{0,63}$`)
 
 // Params validates a key/value map intended to be forwarded to a viewer sidecar.
 // Returns a defensively-copied map on success.
+//
+// Keys become VIEWDOC_Q_<KEY> shell variables upper-cased, so keys that only
+// differ in case would collide and are rejected. The "url" param (any case)
+// must be an absolute http(s) URL: viewdoc.sh hands it to apps as a bare
+// argument, where anything else could be parsed as an option.
 func Params(in map[string]string) (map[string]string, error) {
 	if len(in) > MaxKeys {
 		return nil, fmt.Errorf("too many keys: %d (max %d)", len(in), MaxKeys)
 	}
 	out := make(map[string]string, len(in))
+	seen := make(map[string]string, len(in))
 	for k, v := range in {
 		if !keyRe.MatchString(k) {
 			return nil, fmt.Errorf("invalid key %q", k)
@@ -26,7 +34,33 @@ func Params(in map[string]string) (map[string]string, error) {
 		if len(v) > MaxValueLen {
 			return nil, fmt.Errorf("value for %q too long: %d (max %d)", k, len(v), MaxValueLen)
 		}
+		upper := strings.ToUpper(k)
+		if prev, dup := seen[upper]; dup {
+			return nil, fmt.Errorf("keys %q and %q collide", prev, k)
+		}
+		seen[upper] = k
+		if upper == "URL" {
+			if err := checkURL(v); err != nil {
+				return nil, fmt.Errorf("invalid %s: %w", k, err)
+			}
+		}
 		out[k] = v
 	}
 	return out, nil
 }
+
+// checkURL accepts only absolute http(s) URLs with a host, written with a
+// lower-case scheme (viewdoc.sh matches the literal "http://" / "https://").
+func checkURL(raw string) error {
+	u, err := url.Parse(raw)
+	if err != nil {
+		return fmt.Errorf("not a URL: %w", err)
+	}
+	if !strings.HasPrefix(raw, "http://") && !strings.HasPrefix(raw, "https://") {
+		return fmt.Errorf("must start with http:// or https://")
+	}
+	if u.Host == "" {
+		return fmt.Errorf("missing host")
+	}
+	return nil
+}
diff --git a/internal/sanitize/params_test.go b/internal/sanitize/params_test.go
new file mode 100644
index 0000000..f5ef6bc
--- /dev/null
+++ b/internal/sanitize/params_test.go
@@ -0,0 +1,68 @@
+package sanitize
+
+import (
+	"strings"
+	"testing"
+)
+
+func TestParamsURL(t *testing.T) {
+	cases := []struct {
+		url string
+		ok  bool
+	}{
+		{"https://example.com/x.pdf", true},
+		{"http://example.com:8080/a.mp4?x=1#y", true},
+		{"https://example.com/a b.pdf", true},
+		{"--version.mp4", false},
+		{"-x", false},
+		{"file:///etc/passwd", false},
+		{"ftp://example.com/x.zip", false},
+		{"HTTPS://example.com/x.pdf", false},
+		{"https:///x.pdf", false},
+		{"https:example.com/x.pdf", false},
+		{"//example.com/x.pdf", false},
+		{"https://example.com/x\n.pdf", false},
+		{"", false},
+	}
+	for _, c := range cases {
+		_, err := Params(map[string]string{"url": c.url})
+		if (err == nil) != c.ok {
+			t.Errorf("url %q: err=%v, want ok=%v", c.url, err, c.ok)
+		}
+	}
+}
+
+func TestParamsURLKeyAnyCase(t *testing.T) {
+	for _, k := range []string{"URL", "Url"} {
+		if _, err := Params(map[string]string{k: "--version.mp4"}); err == nil {
+			t.Errorf("key %q: expected URL check to apply", k)
+		}
+	}
+}
+
+func TestParamsKeyCollision(t *testing.T) {
+	_, err := Params(map[string]string{"url": "https://a/x.pdf", "URL": "https://b/y.pdf"})
+	if err == nil || !strings.Contains(err.Error(), "collide") {
+		t.Fatalf("err = %v, want collision", err)
+	}
+}
+
+func TestParamsKeysAndLimits(t *testing.T) {
+	if _, err := Params(map[string]string{"bad-key": "x"}); err == nil {
+		t.Error("bad-key accepted")
+	}
+	if _, err := Params(map[string]string{"note": strings.Repeat("x", MaxValueLen+1)}); err == nil {
+		t.Error("oversized value accepted")
+	}
+	many := map[string]string{}
+	for i := range MaxKeys + 1 {
+		many["k"+strings.Repeat("a", i)] = "v"
+	}
+	if _, err := Params(many); err == nil {
+		t.Error("too many keys accepted")
+	}
+	out, err := Params(map[string]string{"note": "free text, not a URL"})
+	if err != nil || out["note"] != "free text, not a URL" {
+		t.Errorf("plain param: out=%v err=%v", out, err)
+	}
+}

From 01033de3fe05c51900424422b6cbf37813d1f25f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Milan=20Felix=20=C5=A0ulc?= <rkfelix@gmail.com>
Date: Sun, 11 Oct 2026 12:59:23 +0200
Subject: [PATCH 07/12] feat(tls): pick the cert via TLS_CERT: embedded,
 generate or file
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The control-center could only serve the pre-generated self-signed cert
embedded from certs/. Keep that as the default and add two sources:

- embedded (default): certs/server.{crt,key} embedded in the binary
  (make cert regenerates it) — same fingerprint everywhere, so the
  browser's "accept once" sticks.
- generate: a P-256 self-signed pair generated on demand, persisted in
  TLS_CERT_DIR (key 0600, reused on later starts; extra SANs via
  TLS_HOSTS) or kept in memory when no dir is set.
- file: your own TLS_CERT_FILE + TLS_KEY_FILE, e.g. CA-issued.

Unset TLS_CERT infers file / generate / embedded from which variables
are set. The startup log names the source and its SHA-256 fingerprint.
Mode selection lives in tlsself.Config with table tests (plus
persistence, key mode and SAN tests). gen-cert reuses the package and
takes -dir. compose documents the alternatives and mounts a certs
volume at /certs (the image ships it owned by nonroot) for generate.
---
 AGENTS.md                        |   4 +-
 Dockerfile                       |   7 +-
 README.md                        |  18 ++-
 cmd/control-center/main.go       |  25 +++-
 cmd/gen-cert/main.go             | 111 +++++------------
 docker-compose.yml               |  15 +++
 internal/tlsself/tlsself.go      | 207 +++++++++++++++++++++++++++++--
 internal/tlsself/tlsself_test.go | 124 ++++++++++++++++++
 8 files changed, 415 insertions(+), 96 deletions(-)
 create mode 100644 internal/tlsself/tlsself_test.go

diff --git a/AGENTS.md b/AGENTS.md
index 6ab0efe..457ef28 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -8,7 +8,7 @@ Remote streaming sandbox for **viewing files** (PDF, office docs, video, audio,
 
 1. **Go stdlib.** Single static binary built on `net/http` + `httputil.ReverseProxy`.
 2. **N slots, default 4** (2× Kasm + 2× Webtop, matching `docker-compose.yml`). Configured via `VIEWER_SLOTS` — comma-separated entries of the form `<vnc>[|<sidecar>]`. The vnc half accepts `http(s)://host[:port]`, plus two pseudo-schemes — `kasm://host[:port]` expands to `https://host:<VIEWER_KASM_DEFAULT_PORT>` (default `6901`), and `webtop://host[:port]` expands to `http://host:<VIEWER_WEBTOP_DEFAULT_PORT>` (default `3000`). The sidecar half accepts `http(s)://host[:port]`; when omitted, the sidecar inherits the vnc host on `VIEWER_SIDECAR_DEFAULT_PORT` (default `7000`). Mixed pools are first-class. See **README.md → Slot configuration** for worked examples.
-3. **Plain HTTP inside, optional TLS outside.** Cleartext across the compose network (Kasm's own self-signed `:6901` is proxied with skip-verify). The control-center additionally serves TLS on `TLS_ADDR` (compose: `:8443`) with the self-signed cert embedded from `certs/server.{crt,key}` (regenerate via `make cert`) — browsers need a secure context for clipboard access.
+3. **Plain HTTP inside, optional TLS outside.** Cleartext across the compose network (Kasm's own self-signed `:6901` is proxied with skip-verify). The control-center additionally serves TLS on `TLS_ADDR` (compose: `:8443`) (browsers need a secure context for clipboard access). `TLS_CERT` picks the cert (`internal/tlsself`): `embedded` (default — the pre-generated self-signed pair in `certs/server.{crt,key}`, regenerate via `make cert`), `generate` (on demand; persisted in `TLS_CERT_DIR`, extra SANs via `TLS_HOSTS`) or `file` (your own `TLS_CERT_FILE` + `TLS_KEY_FILE`). See README → *TLS certificate*.
 4. **Static slot topology.** Slots declared in `docker-compose.yml` and discovered by DNS hostname on the compose network.
 5. **HTTP sidecar for params.** Each viewer image runs a tiny sidecar on `:7000` by default (override per-slot in `VIEWER_SLOTS` or globally via `VIEWER_SIDECAR_DEFAULT_PORT`); control-center pushes params via `POST http://<sidecar-host>:<sidecar-port>/params`.
 6. **Stateless slot selection.** Slot picked by `?slot=<i>` (default `0`) or `?slot=auto` (random ready slot).
@@ -143,7 +143,7 @@ Useful flags: `--headed` to watch a run, `--session <name>` to isolate parallel
 
 ## What NOT to do
 
-- ❌ No TLS between containers, no ACME / real certs, no openssl — the only TLS is the control-center's optional self-signed listener.
+- ❌ No TLS between containers, no ACME / cert issuance, no openssl — the only TLS is the control-center's optional listener, with an embedded, generated or operator-supplied cert (`TLS_CERT`).
 - ❌ No `/var/run/docker.sock`, no `docker exec`, no docker-cli inside any container.
 - ❌ No dynamic slot spawning at runtime.
 - ❌ No pool leasing / session IDs / TTL logic.
diff --git a/Dockerfile b/Dockerfile
index 7babedc..3940d78 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -10,9 +10,14 @@ COPY web ./web
 COPY certs ./certs
 COPY cmd/control-center ./cmd/control-center
 ENV CGO_ENABLED=0
-RUN GOOS=$TARGETOS GOARCH=$TARGETARCH go build -trimpath -ldflags="-s -w" -o /out/control-center ./cmd/control-center
+RUN GOOS=$TARGETOS GOARCH=$TARGETARCH go build -trimpath -ldflags="-s -w" -o /out/control-center ./cmd/control-center \
+ && mkdir -p /out/certs
 
 FROM gcr.io/distroless/static-debian13:nonroot
 COPY --from=build /out/control-center /control-center
+# Mount point for TLS_CERT=generate with TLS_CERT_DIR=/certs, owned by nonroot
+# so a fresh named volume mounted here inherits that ownership and the
+# generated cert can be written.
+COPY --from=build --chown=65532:65532 /out/certs /certs
 EXPOSE 8080
 ENTRYPOINT ["/control-center"]
diff --git a/README.md b/README.md
index d6baa15..43b9e5e 100644
--- a/README.md
+++ b/README.md
@@ -116,12 +116,26 @@ The system exposes two HTTP services. The **control-center** is the public entry
 | Var                            | Default                       | Purpose                                                                                              |
 |--------------------------------|-------------------------------|------------------------------------------------------------------------------------------------------|
 | `LISTEN_ADDR`                  | `:8080`                       | Plain-HTTP bind address                                                                              |
-| `TLS_ADDR`                     | _(unset)_                     | If set, also bind TLS (self-signed cert)                                                             |
+| `TLS_ADDR`                     | _(unset)_                     | If set, also bind TLS. The cert comes from `TLS_CERT` (see **TLS certificate** below).                |
+| `TLS_CERT`                     | _(inferred)_                  | `embedded`, `generate` or `file`. Unset: `file` if `TLS_CERT_FILE` is set, `generate` if `TLS_CERT_DIR` is set, else `embedded`. |
+| `TLS_CERT_DIR`                 | _(unset)_                     | `generate`: keep the cert here (`server.crt` + `server.key`) so it survives restarts. Unset = new in-memory cert on every start. |
+| `TLS_HOSTS`                    | _(unset)_                     | `generate`: extra comma-separated IPs / DNS names for a new cert.                                    |
+| `TLS_CERT_FILE`, `TLS_KEY_FILE` | _(unset)_                    | `file`: paths to your own PEM cert (full chain) and key.                                             |
 | `VIEWER_SLOTS`                 | `kasm://viewer-kasm-1,kasm://viewer-kasm-2,webtop://viewer-webtop-1,webtop://viewer-webtop-2` (the compose services) | Comma-separated slot list. See **Slot configuration** below for the full grammar.                    |
 | `VIEWER_KASM_DEFAULT_PORT`     | `6901`                        | VNC port used for bare entries and the `kasm://` pseudo-scheme.                                      |
 | `VIEWER_WEBTOP_DEFAULT_PORT`   | `3000`                        | VNC port used for the `webtop://` pseudo-scheme.                                                     |
 | `VIEWER_SIDECAR_DEFAULT_PORT`  | `7000`                        | Sidecar port used when the sidecar half of a slot entry is omitted (or specifies no port).           |
 
+#### TLS certificate
+
+`TLS_ADDR` serves the same UI over HTTPS (browsers only allow clipboard access in a secure context). The startup log prints which cert is used and its SHA-256 fingerprint.
+
+| `TLS_CERT` | Cert used | When to use it |
+|------------|-----------|----------------|
+| `embedded` _(default)_ | Pre-generated self-signed pair from `certs/`, embedded in the image (`make cert` regenerates it). | Local and trusted networks: same fingerprint everywhere, so the browser's "accept once" sticks. The key is public in this repo, so it gives no real protection. |
+| `generate` | Self-signed pair generated on first start. With `TLS_CERT_DIR` it's written there (key `0600`) and reused, so the fingerprint stays stable; compose mounts a `certs` volume at `/certs` for this. Without it, a new in-memory cert on every start. Delete the files to regenerate. | A private key per deployment. Always covers `localhost`, `127.0.0.1`, `::1`, plus `TLS_HOSTS`. |
+| `file` | `TLS_CERT_FILE` + `TLS_KEY_FILE`, read at startup. | Your own cert, e.g. from your CA or Let's Encrypt (mount the files read-only). |
+
 #### Slot configuration
 
 Each entry in `VIEWER_SLOTS` has the shape `<vnc>[|<sidecar>]`. The pipe is optional — omit it when the sidecar lives on the same host as the VNC endpoint (the compose default).
@@ -214,7 +228,7 @@ Requires Go **1.27.2+** (`go.mod` pins the toolchain; older Go downloads it auto
 make test          # go test ./...
 go vet ./...
 make build         # docker compose build (all three images)
-make cert          # regenerate certs/server.{crt,key} for your host IPs
+make cert          # regenerate the embedded certs/server.{crt,key} for your host IPs
 ```
 
 CI (`.github/workflows/docker.yml`) runs `go vet`, `go test -race`, staticcheck, govulncheck, shellcheck and hadolint, then builds every image. Pushes to `master` publish `linux/amd64` + `linux/arm64` images to Docker Hub:
diff --git a/cmd/control-center/main.go b/cmd/control-center/main.go
index de551ce..846adf6 100644
--- a/cmd/control-center/main.go
+++ b/cmd/control-center/main.go
@@ -10,6 +10,7 @@ import (
 	"os"
 	"os/signal"
 	"strconv"
+	"strings"
 	"sync"
 	"syscall"
 	"time"
@@ -50,11 +51,20 @@ func main() {
 	var tlsCfg *tls.Config
 	if tlsAddr != "" {
 		var err error
-		tlsCfg, err = tlsself.Load(viewdoc.ServerCert, viewdoc.ServerKey)
+		var src string
+		tlsCfg, src, err = tlsself.Config(tlsself.Options{
+			Mode:         envOr("TLS_CERT", ""),
+			EmbeddedCert: viewdoc.ServerCert,
+			EmbeddedKey:  viewdoc.ServerKey,
+			Dir:          envOr("TLS_CERT_DIR", ""),
+			Hosts:        splitList(envOr("TLS_HOSTS", "")),
+			CertFile:     envOr("TLS_CERT_FILE", ""),
+			KeyFile:      envOr("TLS_KEY_FILE", ""),
+		})
 		if err != nil {
 			log.Fatalf("tls cert: %v", err)
 		}
-		log.Print("TLS enabled with embedded self-signed cert (certs/server.{crt,key})")
+		log.Printf("TLS cert %s", src)
 	}
 
 	mux := http.NewServeMux()
@@ -137,6 +147,17 @@ func envOr(k, def string) string {
 	return def
 }
 
+// splitList splits a comma-separated env value, dropping blanks.
+func splitList(v string) []string {
+	var out []string
+	for _, f := range strings.Split(v, ",") {
+		if f = strings.TrimSpace(f); f != "" {
+			out = append(out, f)
+		}
+	}
+	return out
+}
+
 func envPort(k string, def int) int {
 	v, ok := os.LookupEnv(k)
 	if !ok || v == "" {
diff --git a/cmd/gen-cert/main.go b/cmd/gen-cert/main.go
index 01406fb..dd96a7d 100644
--- a/cmd/gen-cert/main.go
+++ b/cmd/gen-cert/main.go
@@ -1,120 +1,67 @@
-// gen-cert writes a long-lived self-signed TLS cert to certs/server.{crt,key}.
-// SANs are IPs only — viewdoc is accessed by IP:port, no DNS names.
+// gen-cert writes a self-signed TLS cert. By default it regenerates the
+// pre-generated pair under certs/ that the control-center embeds
+// (TLS_CERT=embedded); -dir writes elsewhere, e.g. into a TLS_CERT_DIR.
+//
+//	go run ./cmd/gen-cert [-dir certs] [host ...]
+//
+// Hosts are IPs or DNS names added as SANs (localhost, 127.0.0.1 and ::1 are
+// always included). Without hosts, this machine's non-loopback IPs are used.
 package main
 
 import (
-	"crypto/ecdsa"
-	"crypto/elliptic"
-	"crypto/rand"
 	"crypto/x509"
-	"crypto/x509/pkix"
 	"encoding/pem"
+	"flag"
 	"fmt"
 	"log"
-	"math/big"
 	"net"
-	"os"
 	"path/filepath"
-	"time"
-)
 
-const outDir = "certs"
+	"github.com/dockette/viewdoc/internal/tlsself"
+)
 
 func main() {
-	ips := []net.IP{net.IPv4(127, 0, 0, 1), net.IPv6loopback}
+	dir := flag.String("dir", "certs", "output directory for server.{crt,key}")
+	flag.Parse()
 
-	if len(os.Args) > 1 {
-		for _, a := range os.Args[1:] {
-			ip := net.ParseIP(a)
-			if ip == nil {
-				log.Fatalf("not an IP: %q", a)
-			}
-			ips = appendUnique(ips, ip)
-		}
-	} else {
-		for _, ip := range discoverIPs() {
-			ips = appendUnique(ips, ip)
-		}
-	}
-
-	priv, err := ecdsa.GenerateKey(elliptic.P256(), rand.Reader)
-	if err != nil {
-		log.Fatalf("keygen: %v", err)
+	hosts := flag.Args()
+	if len(hosts) == 0 {
+		hosts = discoverIPs()
 	}
-	serial, err := rand.Int(rand.Reader, new(big.Int).Lsh(big.NewInt(1), 128))
+	certPEM, keyPEM, err := tlsself.Generate(hosts)
 	if err != nil {
-		log.Fatalf("serial: %v", err)
+		log.Fatal(err)
 	}
-
-	now := time.Now()
-	tmpl := &x509.Certificate{
-		SerialNumber:          serial,
-		Subject:               pkix.Name{CommonName: "viewdoc self-signed"},
-		NotBefore:             now.Add(-time.Hour),
-		NotAfter:              now.Add(10 * 365 * 24 * time.Hour),
-		KeyUsage:              x509.KeyUsageDigitalSignature | x509.KeyUsageKeyEncipherment,
-		ExtKeyUsage:           []x509.ExtKeyUsage{x509.ExtKeyUsageServerAuth},
-		IPAddresses:           ips,
-		BasicConstraintsValid: true,
+	if err := tlsself.Write(*dir, certPEM, keyPEM); err != nil {
+		log.Fatal(err)
 	}
 
-	der, err := x509.CreateCertificate(rand.Reader, tmpl, tmpl, &priv.PublicKey, priv)
+	block, _ := pem.Decode(certPEM)
+	cert, err := x509.ParseCertificate(block.Bytes)
 	if err != nil {
-		log.Fatalf("sign: %v", err)
-	}
-	keyDER, err := x509.MarshalPKCS8PrivateKey(priv)
-	if err != nil {
-		log.Fatalf("marshal key: %v", err)
-	}
-
-	if err := os.MkdirAll(outDir, 0o755); err != nil {
-		log.Fatalf("mkdir: %v", err)
-	}
-	crtPath := filepath.Join(outDir, "server.crt")
-	keyPath := filepath.Join(outDir, "server.key")
-	if err := writePEM(crtPath, "CERTIFICATE", der, 0o644); err != nil {
 		log.Fatal(err)
 	}
-	if err := writePEM(keyPath, "PRIVATE KEY", keyDER, 0o644); err != nil {
-		log.Fatal(err)
+	fmt.Printf("wrote %s and %s\nSANs:\n", filepath.Join(*dir, tlsself.CertFile), filepath.Join(*dir, tlsself.KeyFile))
+	for _, n := range cert.DNSNames {
+		fmt.Printf("  %s\n", n)
 	}
-
-	fmt.Printf("wrote %s and %s\nIP SANs:\n", crtPath, keyPath)
-	for _, ip := range ips {
+	for _, ip := range cert.IPAddresses {
 		fmt.Printf("  %s\n", ip)
 	}
 }
 
-func writePEM(path, blockType string, der []byte, mode os.FileMode) error {
-	f, err := os.OpenFile(path, os.O_WRONLY|os.O_CREATE|os.O_TRUNC, mode)
-	if err != nil {
-		return fmt.Errorf("open %s: %w", path, err)
-	}
-	defer f.Close()
-	return pem.Encode(f, &pem.Block{Type: blockType, Bytes: der})
-}
-
-func discoverIPs() []net.IP {
+func discoverIPs() []string {
 	addrs, err := net.InterfaceAddrs()
 	if err != nil {
 		log.Fatalf("interfaces: %v", err)
 	}
-	var out []net.IP
+	var out []string
 	for _, a := range addrs {
 		ipn, ok := a.(*net.IPNet)
 		if !ok || ipn.IP.IsLoopback() || ipn.IP.IsLinkLocalUnicast() || ipn.IP.IsLinkLocalMulticast() {
 			continue
 		}
-		out = append(out, ipn.IP)
+		out = append(out, ipn.IP.String())
 	}
 	return out
 }
-
-func appendUnique(s []net.IP, ip net.IP) []net.IP {
-	for _, x := range s {
-		if x.Equal(ip) {
-			return s
-		}
-	}
-	return append(s, ip)
-}
diff --git a/docker-compose.yml b/docker-compose.yml
index 2a5d323..5a23d7d 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -11,6 +11,18 @@ services:
       # the JS at response time to bypass the check (see internal/proxy/proxy.go).
       VIEWER_SLOTS: "https://viewer-kasm-1:6901,https://viewer-kasm-2:6901,viewer-webtop-1:3000,viewer-webtop-2:3000"
       TLS_ADDR: ":8443"
+      # TLS cert source (README → TLS certificate). Default: the pre-generated
+      # self-signed cert embedded in the image.
+      #   On-demand, kept in the certs volume across restarts:
+      #     TLS_CERT: "generate"
+      #     TLS_CERT_DIR: "/certs"
+      #     TLS_HOSTS: "viewdoc.lan,192.168.1.10"
+      #   Your own cert (mount it, e.g. ./tls:/tls:ro):
+      #     TLS_CERT: "file"
+      #     TLS_CERT_FILE: "/tls/fullchain.pem"
+      #     TLS_KEY_FILE: "/tls/privkey.pem"
+    volumes:
+      - certs:/certs
     ports:
       - "8080:8080"
       - "8443:8443"
@@ -62,3 +74,6 @@ services:
 
 networks:
   viewdoc:
+
+volumes:
+  certs:
diff --git a/internal/tlsself/tlsself.go b/internal/tlsself/tlsself.go
index 9e990c9..1e199c8 100644
--- a/internal/tlsself/tlsself.go
+++ b/internal/tlsself/tlsself.go
@@ -1,21 +1,214 @@
-// Package tlsself loads a pre-generated self-signed TLS cert from PEM bytes.
-// The cert is built once by cmd/gen-cert and committed under certs/. Embedding
-// the PEM into the binary keeps the fingerprint stable across restarts so the
-// browser's "accept once" actually sticks.
+// Package tlsself provides the control-center's TLS cert, from one of three
+// sources (see Options.Mode):
+//
+//   - embedded: the pre-generated self-signed pair committed under certs/
+//     and embedded in the binary (cmd/gen-cert regenerates it). Same
+//     fingerprint everywhere, so the browser's "accept once" sticks.
+//   - generate: a self-signed pair generated on demand — kept in a
+//     directory (a volume in compose) so it survives restarts, or in memory.
+//   - file: your own cert + key files, e.g. issued by a real CA.
 package tlsself
 
 import (
+	"crypto/ecdsa"
+	"crypto/elliptic"
+	"crypto/rand"
+	"crypto/sha256"
 	"crypto/tls"
+	"crypto/x509"
+	"crypto/x509/pkix"
+	"encoding/hex"
+	"encoding/pem"
+	"errors"
 	"fmt"
+	"io/fs"
+	"math/big"
+	"net"
+	"os"
+	"path/filepath"
+	"slices"
+	"time"
 )
 
-func Load(certPEM, keyPEM []byte) (*tls.Config, error) {
+// Modes accepted by Config.
+const (
+	ModeEmbedded = "embedded"
+	ModeGenerate = "generate"
+	ModeFile     = "file"
+)
+
+// Options selects and parameterises the cert source.
+type Options struct {
+	// Mode is ModeEmbedded, ModeGenerate or ModeFile. Empty infers it:
+	// file when CertFile is set, generate when Dir is set, else embedded.
+	Mode string
+
+	EmbeddedCert, EmbeddedKey []byte // ModeEmbedded
+
+	Dir   string   // ModeGenerate: persist here; empty = in memory
+	Hosts []string // ModeGenerate: extra SANs for a new cert
+
+	CertFile, KeyFile string // ModeFile
+}
+
+// Config returns the TLS config for o, plus a description of where the cert
+// came from (mode, location, SHA-256 fingerprint) for the startup log.
+func Config(o Options) (*tls.Config, string, error) {
+	mode := o.Mode
+	if mode == "" {
+		switch {
+		case o.CertFile != "" || o.KeyFile != "":
+			mode = ModeFile
+		case o.Dir != "":
+			mode = ModeGenerate
+		default:
+			mode = ModeEmbedded
+		}
+	}
+	switch mode {
+	case ModeEmbedded:
+		if len(o.EmbeddedCert) == 0 || len(o.EmbeddedKey) == 0 {
+			return nil, "", errors.New("no embedded cert in this build")
+		}
+		cfg, fp, err := Load(o.EmbeddedCert, o.EmbeddedKey)
+		return cfg, "embedded (pre-generated), sha256 " + fp, err
+	case ModeGenerate:
+		cfg, src, err := LoadOrCreate(o.Dir, o.Hosts)
+		return cfg, "generate: " + src, err
+	case ModeFile:
+		if o.CertFile == "" || o.KeyFile == "" {
+			return nil, "", errors.New("file mode needs both TLS_CERT_FILE and TLS_KEY_FILE")
+		}
+		certPEM, err := os.ReadFile(o.CertFile)
+		if err != nil {
+			return nil, "", err
+		}
+		keyPEM, err := os.ReadFile(o.KeyFile)
+		if err != nil {
+			return nil, "", err
+		}
+		cfg, fp, err := Load(certPEM, keyPEM)
+		return cfg, fmt.Sprintf("file %s, sha256 %s", o.CertFile, fp), err
+	}
+	return nil, "", fmt.Errorf("unknown TLS_CERT mode %q (want %s, %s or %s)", mode, ModeEmbedded, ModeGenerate, ModeFile)
+}
+
+const (
+	CertFile = "server.crt"
+	KeyFile  = "server.key"
+	validity = 10 * 365 * 24 * time.Hour
+)
+
+// LoadOrCreate returns a TLS config for dir/server.{crt,key}, generating and
+// writing a self-signed pair for hosts (plus localhost) when either file is
+// missing. An empty dir generates an in-memory cert that changes on every
+// start. The returned string describes where the cert came from.
+func LoadOrCreate(dir string, hosts []string) (*tls.Config, string, error) {
+	if dir == "" {
+		certPEM, keyPEM, err := Generate(hosts)
+		if err != nil {
+			return nil, "", err
+		}
+		cfg, fp, err := Load(certPEM, keyPEM)
+		return cfg, "generated in memory, changes on every start (set TLS_CERT_DIR to keep it), sha256 " + fp, err
+	}
+
+	certPath, keyPath := filepath.Join(dir, CertFile), filepath.Join(dir, KeyFile)
+	certPEM, cerr := os.ReadFile(certPath)
+	keyPEM, kerr := os.ReadFile(keyPath)
+	if cerr == nil && kerr == nil {
+		cfg, fp, err := Load(certPEM, keyPEM)
+		return cfg, fmt.Sprintf("loaded from %s, sha256 %s", dir, fp), err
+	}
+	for _, err := range []error{cerr, kerr} {
+		if err != nil && !errors.Is(err, fs.ErrNotExist) {
+			return nil, "", err
+		}
+	}
+
+	certPEM, keyPEM, err := Generate(hosts)
+	if err != nil {
+		return nil, "", err
+	}
+	if err := Write(dir, certPEM, keyPEM); err != nil {
+		return nil, "", err
+	}
+	cfg, fp, err := Load(certPEM, keyPEM)
+	return cfg, fmt.Sprintf("generated into %s, sha256 %s", dir, fp), err
+}
+
+// Generate creates a self-signed ECDSA P-256 cert valid for ten years. Each
+// host is added as an IP or DNS SAN; localhost, 127.0.0.1 and ::1 are always
+// included.
+func Generate(hosts []string) (certPEM, keyPEM []byte, err error) {
+	priv, err := ecdsa.GenerateKey(elliptic.P256(), rand.Reader)
+	if err != nil {
+		return nil, nil, fmt.Errorf("keygen: %w", err)
+	}
+	serial, err := rand.Int(rand.Reader, new(big.Int).Lsh(big.NewInt(1), 128))
+	if err != nil {
+		return nil, nil, fmt.Errorf("serial: %w", err)
+	}
+	now := time.Now()
+	tmpl := &x509.Certificate{
+		SerialNumber:          serial,
+		Subject:               pkix.Name{CommonName: "viewdoc self-signed"},
+		NotBefore:             now.Add(-time.Hour),
+		NotAfter:              now.Add(validity),
+		KeyUsage:              x509.KeyUsageDigitalSignature,
+		ExtKeyUsage:           []x509.ExtKeyUsage{x509.ExtKeyUsageServerAuth},
+		BasicConstraintsValid: true,
+	}
+	for _, h := range append([]string{"localhost", "127.0.0.1", "::1"}, hosts...) {
+		if ip := net.ParseIP(h); ip != nil {
+			tmpl.IPAddresses = appendUniqueIP(tmpl.IPAddresses, ip)
+		} else if h != "" && !slices.Contains(tmpl.DNSNames, h) {
+			tmpl.DNSNames = append(tmpl.DNSNames, h)
+		}
+	}
+	der, err := x509.CreateCertificate(rand.Reader, tmpl, tmpl, &priv.PublicKey, priv)
+	if err != nil {
+		return nil, nil, fmt.Errorf("sign: %w", err)
+	}
+	keyDER, err := x509.MarshalPKCS8PrivateKey(priv)
+	if err != nil {
+		return nil, nil, fmt.Errorf("marshal key: %w", err)
+	}
+	return pem.EncodeToMemory(&pem.Block{Type: "CERTIFICATE", Bytes: der}),
+		pem.EncodeToMemory(&pem.Block{Type: "PRIVATE KEY", Bytes: keyDER}), nil
+}
+
+// Write stores the pair as dir/server.{crt,key}; the key is readable by the
+// owner only.
+func Write(dir string, certPEM, keyPEM []byte) error {
+	if err := os.MkdirAll(dir, 0o700); err != nil {
+		return err
+	}
+	if err := os.WriteFile(filepath.Join(dir, KeyFile), keyPEM, 0o600); err != nil {
+		return err
+	}
+	return os.WriteFile(filepath.Join(dir, CertFile), certPEM, 0o644)
+}
+
+// Load builds a TLS config from a PEM pair and returns the leaf's SHA-256
+// fingerprint.
+func Load(certPEM, keyPEM []byte) (*tls.Config, string, error) {
 	cert, err := tls.X509KeyPair(certPEM, keyPEM)
 	if err != nil {
-		return nil, fmt.Errorf("x509 key pair: %w", err)
+		return nil, "", fmt.Errorf("x509 key pair: %w", err)
 	}
+	sum := sha256.Sum256(cert.Certificate[0])
 	return &tls.Config{
 		Certificates: []tls.Certificate{cert},
 		MinVersion:   tls.VersionTLS12,
-	}, nil
+	}, hex.EncodeToString(sum[:]), nil
+}
+
+func appendUniqueIP(s []net.IP, ip net.IP) []net.IP {
+	for _, x := range s {
+		if x.Equal(ip) {
+			return s
+		}
+	}
+	return append(s, ip)
 }
diff --git a/internal/tlsself/tlsself_test.go b/internal/tlsself/tlsself_test.go
new file mode 100644
index 0000000..04400bf
--- /dev/null
+++ b/internal/tlsself/tlsself_test.go
@@ -0,0 +1,124 @@
+package tlsself
+
+import (
+	"crypto/x509"
+	"net"
+	"os"
+	"path/filepath"
+	"slices"
+	"strings"
+	"testing"
+)
+
+func leaf(t *testing.T, dir string) *x509.Certificate {
+	t.Helper()
+	cfg, _, err := LoadOrCreate(dir, []string{"10.1.2.3", "viewdoc.example"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	c, err := x509.ParseCertificate(cfg.Certificates[0].Certificate[0])
+	if err != nil {
+		t.Fatal(err)
+	}
+	return c
+}
+
+func TestLoadOrCreatePersists(t *testing.T) {
+	dir := filepath.Join(t.TempDir(), "certs")
+	first := leaf(t, dir)
+
+	if st, err := os.Stat(filepath.Join(dir, KeyFile)); err != nil || st.Mode().Perm() != 0o600 {
+		t.Fatalf("key file: %v mode %v", err, st.Mode())
+	}
+	if second := leaf(t, dir); !first.Equal(second) {
+		t.Fatal("second start generated a new cert instead of loading the stored one")
+	}
+}
+
+func TestSANs(t *testing.T) {
+	c := leaf(t, "")
+	for _, n := range []string{"localhost", "viewdoc.example"} {
+		if !slices.Contains(c.DNSNames, n) {
+			t.Errorf("missing DNS SAN %q in %v", n, c.DNSNames)
+		}
+	}
+	for _, s := range []string{"127.0.0.1", "::1", "10.1.2.3"} {
+		ip := net.ParseIP(s)
+		if !slices.ContainsFunc(c.IPAddresses, ip.Equal) {
+			t.Errorf("missing IP SAN %s in %v", s, c.IPAddresses)
+		}
+	}
+}
+
+func TestInMemoryChangesEachTime(t *testing.T) {
+	if leaf(t, "").Equal(leaf(t, "")) {
+		t.Fatal("in-memory certs should differ between starts")
+	}
+}
+
+func TestConfigModes(t *testing.T) {
+	embCert, embKey, err := Generate(nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	ownDir := t.TempDir()
+	ownCert, ownKey, err := Generate([]string{"own.example"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := Write(ownDir, ownCert, ownKey); err != nil {
+		t.Fatal(err)
+	}
+	ownCertFile, ownKeyFile := filepath.Join(ownDir, CertFile), filepath.Join(ownDir, KeyFile)
+	genDir := filepath.Join(t.TempDir(), "gen")
+
+	fingerprint := func(certPEM, keyPEM []byte) string {
+		_, fp, err := Load(certPEM, keyPEM)
+		if err != nil {
+			t.Fatal(err)
+		}
+		return fp
+	}
+	embFP, ownFP := fingerprint(embCert, embKey), fingerprint(ownCert, ownKey)
+
+	cases := []struct {
+		name    string
+		o       Options
+		wantFP  string // "" = any (freshly generated)
+		wantErr bool
+	}{
+		{"default is embedded", Options{}, embFP, false},
+		{"explicit embedded wins over dir", Options{Mode: ModeEmbedded, Dir: genDir}, embFP, false},
+		{"dir infers generate", Options{Dir: genDir}, "", false},
+		{"generate in memory", Options{Mode: ModeGenerate}, "", false},
+		{"cert file infers file", Options{CertFile: ownCertFile, KeyFile: ownKeyFile}, ownFP, false},
+		{"file without key", Options{Mode: ModeFile, CertFile: ownCertFile}, "", true},
+		{"file missing", Options{CertFile: "/nonexistent.crt", KeyFile: "/nonexistent.key"}, "", true},
+		{"unknown mode", Options{Mode: "acme"}, "", true},
+		{"embedded but none built in", Options{Mode: ModeEmbedded, EmbeddedCert: []byte{}}, "", true},
+	}
+	for _, c := range cases {
+		t.Run(c.name, func(t *testing.T) {
+			o := c.o
+			if o.EmbeddedCert == nil {
+				o.EmbeddedCert, o.EmbeddedKey = embCert, embKey
+			}
+			cfg, src, err := Config(o)
+			if c.wantErr {
+				if err == nil {
+					t.Fatalf("expected error, got cert from %s", src)
+				}
+				return
+			}
+			if err != nil {
+				t.Fatal(err)
+			}
+			if c.wantFP != "" && !strings.Contains(src, c.wantFP) {
+				t.Fatalf("src %q, want fingerprint %s", src, c.wantFP)
+			}
+			if len(cfg.Certificates) != 1 {
+				t.Fatal("no certificate in config")
+			}
+		})
+	}
+}

From dc44ef294d18d90e4a7deeea8ad2233d67fee3f0 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Milan=20Felix=20=C5=A0ulc?= <rkfelix@gmail.com>
Date: Sun, 11 Oct 2026 13:01:28 +0200
Subject: [PATCH 08/12] build(compose): build each viewer image once

Both replicas of each viewer carried a build: section (via the YAML
anchor), so compose built the Kasm and Webtop images twice. Move the
shared settings into x-kasm / x-webtop fragments, give build: only to
the first replica, and set pull_policy: never on the second so it
reuses the local image instead of pulling the published tag.

Also spell VIEWER_SLOTS with the kasm:// / webtop:// pseudo-schemes.
---
 docker-compose.yml | 57 +++++++++++++++++++++++++++-------------------
 1 file changed, 34 insertions(+), 23 deletions(-)

diff --git a/docker-compose.yml b/docker-compose.yml
index 5a23d7d..00e0fc0 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -1,3 +1,27 @@
+x-kasm: &kasm
+  image: dockette/viewdoc:viewer-kasm
+  shm_size: "512m"
+  environment:
+    # VNC_PW seeds ~/.kasmpasswd (the entrypoint requires the file exists);
+    # VNCOPTIONS=-disableBasicAuth tells KasmVNC to skip the basic-auth
+    # challenge so the iframe loads without a browser prompt. KasmVNC has
+    # no kasmvnc.yaml toggle for this and no ?password= URL mechanism — the
+    # CLI flag is the only supported path.
+    VNC_PW: "viewdoc"
+    VNCOPTIONS: "-disableBasicAuth"
+  networks: [viewdoc]
+  restart: unless-stopped
+
+x-webtop: &webtop
+  image: dockette/viewdoc:viewer-webtop
+  shm_size: "512m"
+  environment:
+    PUID: "1000"
+    PGID: "1000"
+    TZ: "Etc/UTC"
+  networks: [viewdoc]
+  restart: unless-stopped
+
 services:
   control-center:
     build:
@@ -9,7 +33,7 @@ services:
       # Webtop runs nginx + kclient on :3000 (plain http). Webtop's kclient
       # requires a secure context (HTTPS or localhost) — the proxy patches
       # the JS at response time to bypass the check (see internal/proxy/proxy.go).
-      VIEWER_SLOTS: "https://viewer-kasm-1:6901,https://viewer-kasm-2:6901,viewer-webtop-1:3000,viewer-webtop-2:3000"
+      VIEWER_SLOTS: "kasm://viewer-kasm-1,kasm://viewer-kasm-2,webtop://viewer-webtop-1,webtop://viewer-webtop-2"
       TLS_ADDR: ":8443"
       # TLS cert source (README → TLS certificate). Default: the pre-generated
       # self-signed cert embedded in the image.
@@ -36,41 +60,28 @@ services:
     networks: [viewdoc]
     restart: unless-stopped
 
-  viewer-kasm-1: &kasm
+  # Each viewer image is built once, by its first replica; the second reuses
+  # it (pull_policy: never keeps compose from fetching the published tag from
+  # Docker Hub in its place). Shared settings live in x-kasm / x-webtop.
+  viewer-kasm-1:
+    <<: *kasm
     build:
       context: .
       dockerfile: .docker/kasm/Dockerfile
-    image: dockette/viewdoc:viewer-kasm
-    shm_size: "512m"
-    environment:
-      # VNC_PW seeds ~/.kasmpasswd (the entrypoint requires the file exists);
-      # VNCOPTIONS=-disableBasicAuth tells KasmVNC to skip the basic-auth
-      # challenge so the iframe loads without a browser prompt. KasmVNC has
-      # no kasmvnc.yaml toggle for this and no ?password= URL mechanism — the
-      # CLI flag is the only supported path.
-      VNC_PW: "viewdoc"
-      VNCOPTIONS: "-disableBasicAuth"
-    networks: [viewdoc]
-    restart: unless-stopped
 
   viewer-kasm-2:
     <<: *kasm
+    pull_policy: never
 
-  viewer-webtop-1: &webtop
+  viewer-webtop-1:
+    <<: *webtop
     build:
       context: .
       dockerfile: .docker/webtop/Dockerfile
-    image: dockette/viewdoc:viewer-webtop
-    shm_size: "512m"
-    environment:
-      PUID: "1000"
-      PGID: "1000"
-      TZ: "Etc/UTC"
-    networks: [viewdoc]
-    restart: unless-stopped
 
   viewer-webtop-2:
     <<: *webtop
+    pull_policy: never
 
 networks:
   viewdoc:

From 7ae9311ea47bd10592a92011f3a088aa84425e65 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Milan=20Felix=20=C5=A0ulc?= <rkfelix@gmail.com>
Date: Sun, 11 Oct 2026 20:08:39 +0200
Subject: [PATCH 09/12] feat: date-based versioning (YYYY.MM.DD)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

viewdoc had no version: images were only published as rolling
<variant> tags. Follow the dockette pattern (a version pinned in the
repo, tagged images, a Versions table — cf. dockette/grafana, tika)
with a release date instead of an upstream version:

- VERSION holds YYYY.MM.DD (YYYY.MM.DD.N for a same-day re-release);
  make release sets it to today's date, skipping already-tagged ones.
- internal/version.Version is set via -ldflags from the VERSION build
  arg (compose: VIEWDOC_VERSION, make build), logged by both binaries
  and returned by /healthz and the sidecar's /status. Images carry
  org.opencontainers.image.version.
- CI: validates VERSION, publishes <variant>-<VERSION> next to
  <variant> and <variant>-<sha>, and a new release job tags the commit
  and creates the GitHub release once all images are pushed. Docker
  Hub login now runs only when pushing (as in dockette/.github).
- README: Versions section and release steps.
---
 .docker/kasm/Dockerfile      |  5 +++-
 .docker/webtop/Dockerfile    |  5 +++-
 .github/workflows/docker.yml | 46 ++++++++++++++++++++++++++++++++++--
 AGENTS.md                    |  1 +
 Dockerfile                   |  5 +++-
 Makefile                     | 32 ++++++++++++++++++++-----
 README.md                    | 23 ++++++++++++------
 VERSION                      |  1 +
 cmd/control-center/main.go   |  2 ++
 cmd/sidecar/main.go          |  8 +++++--
 docker-compose.yml           |  4 ++++
 internal/api/handlers.go     |  3 ++-
 internal/version/version.go  |  9 +++++++
 13 files changed, 123 insertions(+), 21 deletions(-)
 create mode 100644 VERSION
 create mode 100644 internal/version/version.go

diff --git a/.docker/kasm/Dockerfile b/.docker/kasm/Dockerfile
index f7653a7..f25fd0f 100644
--- a/.docker/kasm/Dockerfile
+++ b/.docker/kasm/Dockerfile
@@ -2,17 +2,20 @@
 # Go toolchain under QEMU.
 FROM --platform=$BUILDPLATFORM golang:1.27-alpine AS sidecar
 ARG TARGETOS TARGETARCH
+ARG VERSION=dev
 WORKDIR /src
 COPY go.mod ./
 COPY internal ./internal
 COPY cmd/sidecar ./cmd/sidecar
 ENV CGO_ENABLED=0
-RUN GOOS=$TARGETOS GOARCH=$TARGETARCH go build -trimpath -ldflags="-s -w" -o /out/sidecar ./cmd/sidecar
+RUN GOOS=$TARGETOS GOARCH=$TARGETARCH go build -trimpath -ldflags="-s -w -X github.com/dockette/viewdoc/internal/version.Version=$VERSION" -o /out/sidecar ./cmd/sidecar
 
 # Base pinned by digest for reproducible builds; Dependabot bumps it
 # (.github/dependabot.yml).
 FROM kasmweb/ubuntu-noble-desktop:1.19.0@sha256:14594dcf30c33768485a7dc6cb7bf3b7bef25121743d30371cbc56b525d96c71
 USER root
+ARG VERSION=dev
+LABEL org.opencontainers.image.version=$VERSION
 SHELL ["/bin/bash", "-o", "pipefail", "-c"]
 
 # wireshark-common preseed: we only ever read pcap files, never capture, so
diff --git a/.docker/webtop/Dockerfile b/.docker/webtop/Dockerfile
index f69e5ef..6bf3401 100644
--- a/.docker/webtop/Dockerfile
+++ b/.docker/webtop/Dockerfile
@@ -2,17 +2,20 @@
 # Go toolchain under QEMU.
 FROM --platform=$BUILDPLATFORM golang:1.27-alpine AS sidecar
 ARG TARGETOS TARGETARCH
+ARG VERSION=dev
 WORKDIR /src
 COPY go.mod ./
 COPY internal ./internal
 COPY cmd/sidecar ./cmd/sidecar
 ENV CGO_ENABLED=0
-RUN GOOS=$TARGETOS GOARCH=$TARGETARCH go build -trimpath -ldflags="-s -w" -o /out/sidecar ./cmd/sidecar
+RUN GOOS=$TARGETOS GOARCH=$TARGETARCH go build -trimpath -ldflags="-s -w -X github.com/dockette/viewdoc/internal/version.Version=$VERSION" -o /out/sidecar ./cmd/sidecar
 
 # Base pinned by digest for reproducible builds; Dependabot bumps it
 # (.github/dependabot.yml).
 FROM lscr.io/linuxserver/webtop:ubuntu-xfce@sha256:c766271bf5de1c7c8c6cd7be1ae4015953f1b45a9325dbc1c94f7a163ff7ffc7
 SHELL ["/bin/bash", "-o", "pipefail", "-c"]
+ARG VERSION=dev
+LABEL org.opencontainers.image.version=$VERSION
 
 # wireshark-common preseed: we only ever read pcap files, never capture, so
 # answer "no" to the setuid-helper question and skip the interactive prompt.
diff --git a/.github/workflows/docker.yml b/.github/workflows/docker.yml
index eb939d4..d71c047 100644
--- a/.github/workflows/docker.yml
+++ b/.github/workflows/docker.yml
@@ -24,6 +24,9 @@ jobs:
         with:
           go-version-file: go.mod
 
+      - name: VERSION format
+        run: grep -Eqx '[0-9]{4}\.[0-9]{2}\.[0-9]{2}(\.[0-9]+)?' VERSION || { echo "::error file=VERSION::expected YYYY.MM.DD or YYYY.MM.DD.N, got '$(cat VERSION)'"; exit 1; }
+
       - name: go vet
         run: go vet ./...
 
@@ -103,20 +106,30 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v7
 
+      # Only a push needs credentials; pull requests from forks and Dependabot
+      # have no access to the secrets (same as dockette/.github docker.yml).
       - name: Login to DockerHub
+        if: github.ref == 'refs/heads/master'
         uses: docker/login-action@v4
         with:
           username: ${{ secrets.DOCKERHUB_USERNAME }}
           password: ${{ secrets.DOCKERHUB_TOKEN }}
 
+      - name: Read VERSION
+        id: version
+        run: echo "version=$(cat VERSION)" >> "$GITHUB_OUTPUT"
+
       - name: Set up QEMU
         uses: docker/setup-qemu-action@v4
 
       - name: Set up Docker Buildx
         uses: docker/setup-buildx-action@v4
 
-      # dockette/viewdoc:<variant> (rolling) + dockette/viewdoc:<variant>-<sha>
-      # (immutable, for rollbacks / pinning).
+      # dockette/viewdoc:<variant>             rolling, latest master
+      # dockette/viewdoc:<variant>-<VERSION>   release (YYYY.MM.DD); like other
+      #                                         dockette versions it's rebuilt
+      #                                         by the weekly schedule
+      # dockette/viewdoc:<variant>-<sha>       immutable, for rollbacks / pinning
       - name: Docker meta
         id: meta
         uses: docker/metadata-action@v6
@@ -125,7 +138,10 @@ jobs:
           flavor: latest=false
           tags: |
             type=raw,value=${{ matrix.variant }}
+            type=raw,value=${{ matrix.variant }}-${{ steps.version.outputs.version }}
             type=sha,prefix=${{ matrix.variant }}-,format=short
+          labels: |
+            org.opencontainers.image.version=${{ steps.version.outputs.version }}
 
       - name: Build and push
         uses: docker/build-push-action@v7
@@ -135,10 +151,36 @@ jobs:
           push: ${{ github.ref == 'refs/heads/master' }}
           tags: ${{ steps.meta.outputs.tags }}
           labels: ${{ steps.meta.outputs.labels }}
+          build-args: |
+            VERSION=${{ steps.version.outputs.version }}
           platforms: linux/amd64,linux/arm64
           cache-from: type=gha,scope=${{ matrix.variant }}
           cache-to: type=gha,scope=${{ matrix.variant }}
 
+  # Tags the commit and publishes a GitHub release for VERSION the first
+  # time it reaches master with all images pushed (make release bumps it).
+  release:
+    name: "Release"
+    needs: build
+    runs-on: ubuntu-latest
+    if: github.ref == 'refs/heads/master' && github.event_name == 'push'
+    permissions:
+      contents: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+
+      - name: Create release if VERSION is new
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          v="$(cat VERSION)"
+          if gh release view "$v" >/dev/null 2>&1; then
+            echo "Release $v already exists"
+            exit 0
+          fi
+          gh release create "$v" --target "$GITHUB_SHA" --title "$v" --generate-notes
+
   docs:
     name: "Docs"
     needs: build
diff --git a/AGENTS.md b/AGENTS.md
index 457ef28..01751e0 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -12,6 +12,7 @@ Remote streaming sandbox for **viewing files** (PDF, office docs, video, audio,
 4. **Static slot topology.** Slots declared in `docker-compose.yml` and discovered by DNS hostname on the compose network.
 5. **HTTP sidecar for params.** Each viewer image runs a tiny sidecar on `:7000` by default (override per-slot in `VIEWER_SLOTS` or globally via `VIEWER_SIDECAR_DEFAULT_PORT`); control-center pushes params via `POST http://<sidecar-host>:<sidecar-port>/params`.
 6. **Stateless slot selection.** Slot picked by `?slot=<i>` (default `0`) or `?slot=auto` (random ready slot).
+7. **Date versions.** `VERSION` holds `YYYY.MM.DD` (`.N` for a same-day re-release), bumped by `make release`; it's built into both binaries (`internal/version`, via `-ldflags -X`), tags images `<variant>-<VERSION>`, and CI creates the matching GitHub release. See README → *Versions*.
 
 ## Architecture
 
diff --git a/Dockerfile b/Dockerfile
index 3940d78..79a8a2e 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -2,6 +2,7 @@
 # Go toolchain under QEMU.
 FROM --platform=$BUILDPLATFORM golang:1.27-alpine AS build
 ARG TARGETOS TARGETARCH
+ARG VERSION=dev
 WORKDIR /src
 COPY go.mod ./
 COPY assets.go ./
@@ -10,10 +11,12 @@ COPY web ./web
 COPY certs ./certs
 COPY cmd/control-center ./cmd/control-center
 ENV CGO_ENABLED=0
-RUN GOOS=$TARGETOS GOARCH=$TARGETARCH go build -trimpath -ldflags="-s -w" -o /out/control-center ./cmd/control-center \
+RUN GOOS=$TARGETOS GOARCH=$TARGETARCH go build -trimpath -ldflags="-s -w -X github.com/dockette/viewdoc/internal/version.Version=$VERSION" -o /out/control-center ./cmd/control-center \
  && mkdir -p /out/certs
 
 FROM gcr.io/distroless/static-debian13:nonroot
+ARG VERSION=dev
+LABEL org.opencontainers.image.version=$VERSION
 COPY --from=build /out/control-center /control-center
 # Mount point for TLS_CERT=generate with TLS_CERT_DIR=/certs, owned by nonroot
 # so a fresh named volume mounted here inherits that ownership and the
diff --git a/Makefile b/Makefile
index ee7a96b..29e2d3f 100644
--- a/Makefile
+++ b/Makefile
@@ -1,12 +1,14 @@
-IMAGE  ?= dockette/viewdoc
+IMAGE    ?= dockette/viewdoc
+VERSION  := $(shell cat VERSION)
+VARIANTS := control-center viewer-kasm viewer-webtop
 
-.PHONY: build test run up down logs ps push cert
+.PHONY: build test run up down logs ps push cert version release
 
 cert:
 	go run ./cmd/gen-cert
 
 build:
-	docker compose build
+	VIEWDOC_VERSION=$(VERSION) docker compose build
 
 run:
 	docker compose up
@@ -26,7 +28,25 @@ ps:
 test:
 	go test ./...
 
+# Pushes <variant> and <variant>-$(VERSION) for every image (CI does this on
+# master; this is for manual publishing of a local build).
 push:
-	docker push $(IMAGE):control-center
-	docker push $(IMAGE):viewer-kasm
-	docker push $(IMAGE):viewer-webtop
+	@for v in $(VARIANTS); do \
+	  docker tag $(IMAGE):$$v $(IMAGE):$$v-$(VERSION) && \
+	  docker push $(IMAGE):$$v && \
+	  docker push $(IMAGE):$$v-$(VERSION) || exit 1; \
+	done
+
+version:
+	@echo $(VERSION)
+
+# Sets VERSION to today's date (UTC), YYYY.MM.DD — or YYYY.MM.DD.N when that
+# date is already released (tagged). Commit and push to master to publish:
+# CI then pushes <variant>-<VERSION> images and creates the GitHub release.
+release:
+	@git fetch -q --tags origin 2>/dev/null || true; \
+	v=$$(date -u +%Y.%m.%d); n=0; \
+	while git rev-parse -q --verify "refs/tags/$$v" >/dev/null; do n=$$((n+1)); v=$$(date -u +%Y.%m.%d).$$n; done; \
+	echo "$$v" > VERSION; \
+	echo "VERSION: $(VERSION) -> $$v"; \
+	echo "next: git commit -am 'release: $$v' && git push"
diff --git a/README.md b/README.md
index 43b9e5e..f72c6b8 100644
--- a/README.md
+++ b/README.md
@@ -227,18 +227,27 @@ Requires Go **1.27.2+** (`go.mod` pins the toolchain; older Go downloads it auto
 ```sh
 make test          # go test ./...
 go vet ./...
-make build         # docker compose build (all three images)
+make build         # build all three images, stamped with VERSION
 make cert          # regenerate the embedded certs/server.{crt,key} for your host IPs
+make version       # print VERSION
+make release       # set VERSION to today's date (see Versions)
 ```
 
-CI (`.github/workflows/docker.yml`) runs `go vet`, `go test -race`, staticcheck, govulncheck, shellcheck and hadolint, then builds every image. Pushes to `master` publish `linux/amd64` + `linux/arm64` images to Docker Hub:
+CI (`.github/workflows/docker.yml`) checks the `VERSION` format and runs `go vet`, `go test -race`, staticcheck, govulncheck, shellcheck and hadolint, then builds every image. Pushes to `master` publish `linux/amd64` + `linux/arm64` images to Docker Hub (see **Versions**). The Kasm and Webtop base images are pinned by digest; Dependabot opens weekly PRs for new digests, Go builder images and GitHub Actions.
 
-| Tag                                      | Meaning                          |
-|------------------------------------------|----------------------------------|
-| `dockette/viewdoc:<variant>`             | latest `master` build            |
-| `dockette/viewdoc:<variant>-<short-sha>` | immutable build of that commit   |
+## Versions
 
-`<variant>` is `control-center`, `viewer-kasm` or `viewer-webtop`. The Kasm and Webtop base images are pinned by digest; Dependabot opens weekly PRs for new digests, Go builder images and GitHub Actions.
+viewdoc is versioned by release date: `YYYY.MM.DD`, or `YYYY.MM.DD.N` for another release on the same day. The current version is in [`VERSION`](VERSION). It is built into both binaries (logged at startup, returned by the control-center's `/healthz` and the sidecar's `/status`) and set as the `org.opencontainers.image.version` label.
+
+| Image tag | Meaning |
+|-----------|---------|
+| `dockette/viewdoc:<variant>` | latest `master` build |
+| `dockette/viewdoc:<variant>-2026.10.11` | release `2026.10.11` — pin this |
+| `dockette/viewdoc:<variant>-<short-sha>` | immutable build of that commit |
+
+`<variant>` is `control-center`, `viewer-kasm` or `viewer-webtop`. Like other dockette images, release tags are rebuilt by the weekly schedule to pick up base-image updates; use the `<short-sha>` tag for a byte-identical image.
+
+To release: `make release` sets `VERSION` to today's date (UTC; `.1`, `.2`, … if that date is already tagged), then commit and push to `master`. Once all images are pushed, CI tags the commit and creates the GitHub release `<VERSION>` with generated notes. A plain `docker compose build` stamps `dev`; `make build` uses `VERSION`.
 
 -----
 
diff --git a/VERSION b/VERSION
new file mode 100644
index 0000000..ed2a817
--- /dev/null
+++ b/VERSION
@@ -0,0 +1 @@
+2026.10.11
diff --git a/cmd/control-center/main.go b/cmd/control-center/main.go
index 846adf6..c84b846 100644
--- a/cmd/control-center/main.go
+++ b/cmd/control-center/main.go
@@ -20,6 +20,7 @@ import (
 	"github.com/dockette/viewdoc/internal/proxy"
 	"github.com/dockette/viewdoc/internal/slots"
 	"github.com/dockette/viewdoc/internal/tlsself"
+	"github.com/dockette/viewdoc/internal/version"
 )
 
 const (
@@ -31,6 +32,7 @@ const (
 )
 
 func main() {
+	log.Printf("viewdoc control-center %s", version.Version)
 	addr := envOr("LISTEN_ADDR", defaultListenAddr)
 	tlsAddr := envOr("TLS_ADDR", "")
 
diff --git a/cmd/sidecar/main.go b/cmd/sidecar/main.go
index 6ba1e9f..fbcc888 100644
--- a/cmd/sidecar/main.go
+++ b/cmd/sidecar/main.go
@@ -20,6 +20,7 @@ import (
 	"time"
 
 	"github.com/dockette/viewdoc/internal/sanitize"
+	"github.com/dockette/viewdoc/internal/version"
 )
 
 const (
@@ -73,7 +74,7 @@ func main() {
 		Handler:           mux,
 		ReadHeaderTimeout: 10 * time.Second,
 	}
-	log.Printf("sidecar listening on %s", addr)
+	log.Printf("viewdoc sidecar %s listening on %s", version.Version, addr)
 	if err := srv.ListenAndServe(); err != nil {
 		log.Fatalf("listen: %v", err)
 	}
@@ -133,7 +134,9 @@ func handleRestart(w http.ResponseWriter, _ *http.Request) {
 // app it launched is still up. Phase "idle" means no request since start.
 func handleStatus(w http.ResponseWriter, _ *http.Request) {
 	w.Header().Set("Content-Type", "application/json")
-	_ = json.NewEncoder(w).Encode(readStatus())
+	st := readStatus()
+	st.Version = version.Version
+	_ = json.NewEncoder(w).Encode(st)
 }
 
 type status struct {
@@ -144,6 +147,7 @@ type status struct {
 	Updated  string `json:"updated,omitempty"`
 	AppState string `json:"app_state,omitempty"` // running|handoff|exited
 	ExitCode *int   `json:"exit_code,omitempty"`
+	Version  string `json:"version"` // viewer image release
 }
 
 func readStatus() status {
diff --git a/docker-compose.yml b/docker-compose.yml
index 00e0fc0..29c5d13 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -27,6 +27,8 @@ services:
     build:
       context: .
       dockerfile: Dockerfile
+      args: &version
+        VERSION: ${VIEWDOC_VERSION:-dev}
     image: dockette/viewdoc:control-center
     environment:
       # Kasm runs KasmVNC on :6901 (https, self-signed; proxy skips verify).
@@ -68,6 +70,7 @@ services:
     build:
       context: .
       dockerfile: .docker/kasm/Dockerfile
+      args: *version
 
   viewer-kasm-2:
     <<: *kasm
@@ -78,6 +81,7 @@ services:
     build:
       context: .
       dockerfile: .docker/webtop/Dockerfile
+      args: *version
 
   viewer-webtop-2:
     <<: *webtop
diff --git a/internal/api/handlers.go b/internal/api/handlers.go
index 2ed5bc8..febb8a1 100644
--- a/internal/api/handlers.go
+++ b/internal/api/handlers.go
@@ -18,6 +18,7 @@ import (
 
 	"github.com/dockette/viewdoc/internal/sanitize"
 	"github.com/dockette/viewdoc/internal/slots"
+	"github.com/dockette/viewdoc/internal/version"
 )
 
 type Handlers struct {
@@ -102,7 +103,7 @@ func (h *Handlers) Healthz(w http.ResponseWriter, _ *http.Request) {
 	if ready == 0 {
 		status = http.StatusServiceUnavailable
 	}
-	writeJSON(w, status, map[string]any{"ready": ready, "total": len(entries)})
+	writeJSON(w, status, map[string]any{"ready": ready, "total": len(entries), "version": version.Version})
 }
 
 func (h *Handlers) Params(w http.ResponseWriter, r *http.Request) {
diff --git a/internal/version/version.go b/internal/version/version.go
new file mode 100644
index 0000000..ac16b8d
--- /dev/null
+++ b/internal/version/version.go
@@ -0,0 +1,9 @@
+// Package version holds the viewdoc release, a date in YYYY.MM.DD form
+// (YYYY.MM.DD.N for a second release on the same day) taken from the VERSION
+// file. Builds set it with:
+//
+//	go build -ldflags "-X github.com/dockette/viewdoc/internal/version.Version=$(cat VERSION)"
+package version
+
+// Version is "dev" for builds that don't pass the ldflag.
+var Version = "dev"

From c080d72b0782b1d1276f1e925057b31e92a7760d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Milan=20Felix=20=C5=A0ulc?= <rkfelix@gmail.com>
Date: Sun, 11 Oct 2026 20:08:56 +0200
Subject: [PATCH 10/12] chore: ignore Claude Code worktrees

---
 .gitignore | 1 +
 1 file changed, 1 insertion(+)

diff --git a/.gitignore b/.gitignore
index 1fcdc30..5017be0 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,2 +1,3 @@
 /control-center
 .DS_Store
+.claude/worktrees/

From 2ea887ac0645aa7337caf8398dfa730310c7dfbc Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Milan=20Felix=20=C5=A0ulc?= <rkfelix@gmail.com>
Date: Sun, 11 Oct 2026 20:12:16 +0200
Subject: [PATCH 11/12] fix(viewdoc.sh): avoid A && B || C in status() (SC2015)

The CI runner's shellcheck flags it (the local stable image doesn't);
use an explicit if so the lint job passes.
---
 .docker/viewdoc.sh | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/.docker/viewdoc.sh b/.docker/viewdoc.sh
index 008e462..0c4bd79 100644
--- a/.docker/viewdoc.sh
+++ b/.docker/viewdoc.sh
@@ -30,13 +30,15 @@ log() {
 # status <phase> [app] [error] — records the outcome of this request for the
 # sidecar's GET /status. Never load-bearing, like log().
 status() {
-  {
+  if {
     printf 'phase=%s\n' "$1"
     printf 'url=%s\n' "$(printf '%s' "$url" | tr '\n' ' ')"
     printf 'app=%s\n' "${2:-}"
     printf 'error=%s\n' "${3:-}"
     printf 'updated=%s\n' "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
-  } > "$STATUS.$$" 2>/dev/null && mv -f "$STATUS.$$" "$STATUS" 2>/dev/null || true
+  } > "$STATUS.$$" 2>/dev/null; then
+    mv -f "$STATUS.$$" "$STATUS" 2>/dev/null || true
+  fi
 }
 
 [ -r "$QUERY_ENV" ] || { log "no $QUERY_ENV; nothing to do"; exit 0; }

From d81ffd3bf68195be02719d6b98b97c8967d90cf4 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Milan=20Felix=20=C5=A0ulc?= <rkfelix@gmail.com>
Date: Mon, 12 Oct 2026 08:27:24 +0200
Subject: [PATCH 12/12] release: 2026.10.12

---
 README.md | 2 +-
 VERSION   | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index f72c6b8..710bd16 100644
--- a/README.md
+++ b/README.md
@@ -242,7 +242,7 @@ viewdoc is versioned by release date: `YYYY.MM.DD`, or `YYYY.MM.DD.N` for anothe
 | Image tag | Meaning |
 |-----------|---------|
 | `dockette/viewdoc:<variant>` | latest `master` build |
-| `dockette/viewdoc:<variant>-2026.10.11` | release `2026.10.11` — pin this |
+| `dockette/viewdoc:<variant>-2026.10.12` | release `2026.10.12` — pin this |
 | `dockette/viewdoc:<variant>-<short-sha>` | immutable build of that commit |
 
 `<variant>` is `control-center`, `viewer-kasm` or `viewer-webtop`. Like other dockette images, release tags are rebuilt by the weekly schedule to pick up base-image updates; use the `<short-sha>` tag for a byte-identical image.
diff --git a/VERSION b/VERSION
index ed2a817..636c4db 100644
--- a/VERSION
+++ b/VERSION
@@ -1 +1 @@
-2026.10.11
+2026.10.12