docs: web platform + clean URLs + dark/light mode (#37)

* chore(docs): replace d2 diagram pipeline with mermaid

Remove docs/_diagrams/ and d2 build step from Makefile. The HTML
template already initialises mermaid.js; diagrams are now inline
code fences rendered client-side.

* docs(architecture): add mermaid diagram + web/CDP platform docs

Replace SVG img tag with inline mermaid flowchart showing both native
(Maestro sidecar + in-app SDK) and web (Chrome CDP) paths. Update
Processes, Transports table, and per-step cycle sections.

* docs(design-principles): update principles 1-4 for web platform

Principles 1, 2, 3, and 4 referenced Maestro and native-only concepts.
Add web/CDP context and update driver-is-an-interface to name both
sidecar and chrome implementations.

* docs(manual): add web prerequisites and folio-web example

Update --platform flag to list android, ios, web. Add web prerequisites
section (Chrome, no SDK needed) and folio-web quick-start to
getting-started.

* chore(gitignore): untrack inspect dist/index.html build artifact

index.html is regenerated by vite on every build with a new content hash,
making it permanently dirty. Only .gitkeep is needed for //go:embed to
compile on a fresh checkout. Also remove duplicate dist/* line and stale
d2 diagram ignore entries.

* feat(docs): click-to-zoom for mermaid diagrams

* docs(architecture): change diagram layout from LR to TB

* docs(getting-started): link npm and Maven Central package headers

* update docs root

* docs(spec): rewrite npm package README

Update usage example to current API, drop stale version-compatibility
and license sections.

* build(docs): output pages as pagename/index.html for clean URLs

Split DOCS_OUT into INDEX_OUT (index.md files stay as index.html) and
PAGE_OUT (all other pages become pagename/index.html). The __ROOT__
depth computation already handles the extra directory level correctly.

* chore(docs): update sidebar links to directory-style URLs

* docs: update cross-links from .html to directory-style paths

* ci(docs): remove d2 install step

* feat(docs): dark/light mode toggle

Add theme toggle button (top-right, fixed). Persists preference in
localStorage; falls back to prefers-color-scheme. Flash-free via inline
script in <head> that sets data-theme before first paint.

* fix(docs): fix inspect image path broken by directory URL restructure

* feat(docs): click-to-fullscreen for all article images

* fix(inspect): allow AssetsFS override in ServerOptions; drop unused request param from serveIndex

* fix(inspect): use in-memory FS in tests so TestAssets_FallbackToIndexHTML passes without web build

internal/inspect/dist/index.html

@@ -1,13 +0,0 @@
-<!doctype html>
-<html lang="en">
-  <head>
-    <meta charset="UTF-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>sanderling inspect</title>
-    <script type="module" crossorigin src="/assets/index-DFpYQDqN.js"></script>
-    <link rel="stylesheet" crossorigin href="/assets/index-BSJUf7yI.css">
-  </head>
-  <body>
-    <div id="root"></div>
-  </body>
-</html>

internal/inspect/server.go

@@ -18,6 +18,8 @@ import (
 type ServerOptions struct {
 	RunsDirectory string
 	DevTarget     string
+	// AssetsFS overrides the default embedded dist FS. Intended for tests.
+	AssetsFS fs.FS
 }
 
 // Server holds the HTTP handlers for `sanderling inspect`.
@@ -33,11 +35,15 @@ type Server struct {
 // server reverse-proxies non-API GETs to it; otherwise it serves embedded
 // assets from the dist FS.
 func NewServer(options ServerOptions) (*Server, error) {
+	assetsFS := options.AssetsFS
+	if assetsFS == nil {
+		assetsFS = Assets()
+	}
 	server := &Server{
 		options: options,
 		cache:   NewCache(options.RunsDirectory),
 		watcher: NewWatcher(options.RunsDirectory),
-		assets:  spaHandler(Assets()),
+		assets:  spaHandler(assetsFS),
 	}
 	if options.DevTarget != "" {
 		proxy, err := newDevProxy(options.DevTarget)
@@ -207,12 +213,12 @@ func spaHandler(assets fs.FS) http.Handler {
 	return http.HandlerFunc(func(responseWriter http.ResponseWriter, request *http.Request) {
 		clean := strings.TrimPrefix(path.Clean(request.URL.Path), "/")
 		if clean == "" {
-			serveIndex(responseWriter, request, assets)
+			serveIndex(responseWriter, assets)
 			return
 		}
 		file, err := assets.Open(clean)
 		if err != nil {
-			serveIndex(responseWriter, request, assets)
+			serveIndex(responseWriter, assets)
 			return
 		}
 		file.Close()
@@ -220,7 +226,7 @@ func spaHandler(assets fs.FS) http.Handler {
 	})
 }
 
-func serveIndex(responseWriter http.ResponseWriter, request *http.Request, assets fs.FS) {
+func serveIndex(responseWriter http.ResponseWriter, assets fs.FS) {
 	file, err := assets.Open("index.html")
 	if err != nil {
 		http.Error(responseWriter, "index.html missing from embedded assets", http.StatusInternalServerError)

internal/inspect/server_test.go

@@ -4,6 +4,7 @@ import (
 	"context"
 	"encoding/json"
 	"io"
+	"io/fs"
 	"net/http"
 	"net/http/httptest"
 	"net/url"
@@ -11,11 +12,18 @@ import (
 	"path/filepath"
 	"strings"
 	"testing"
+	"testing/fstest"
 	"time"
 
 	"github.com/priyanshujain/sanderling/internal/trace"
 )
 
+var testAssetsFS fs.FS = fstest.MapFS{
+	"index.html": &fstest.MapFile{
+		Data: []byte(`<!doctype html><html><body><div id="root"></div></body></html>`),
+	},
+}
+
 func newFixtureServer(t *testing.T) (*Server, string) {
 	t.Helper()
 	root := t.TempDir()
@@ -48,7 +56,7 @@ func newFixtureServer(t *testing.T) (*Server, string) {
 		t.Fatal(err)
 	}
 
-	server, err := NewServer(ServerOptions{RunsDirectory: root})
+	server, err := NewServer(ServerOptions{RunsDirectory: root, AssetsFS: testAssetsFS})
 	if err != nil {
 		t.Fatal(err)
 	}