yamlover 0.3.48 → 0.3.50

package/README.md

@@ -1,12 +1,20 @@
-# server
+# yamlover
 
-Browse a yamlover tree in the web browser.
+A local-first, editable knowledge graph for humans and LLMs — one plain-text
+directory that a person edits like notes, an agent reads and writes like a
+database, and `git` versions like code. This package is the web server: it
+serves a browser UI (tree, editor, renderers, live queries) over a yamlover
+directory, and an HTTP API an agent can drive directly.
+
+- **Repo:** https://github.com/dims12/yamlover
+- **Live demo** (no install): https://yamlover.inthemoon.net/
+- **Docs** (written in yamlover, click-through): https://yamlover.inthemoon.net/docs
 
 ```console
-$ npx yamlover [ROOT] [--port N] [--headless] [--host ADDR] [--base-path PREFIX] [--no-gitignore] [--prod]
+$ npx yamlover [ROOT] [--port N] [--headless] [--host ADDR] [--base-path PREFIX] [--no-gitignore] [--prod] [--read-only]
 ```
 
-`ROOT` is any yamlover entity — a project directory (one with a `.yamlover/`),
+`ROOT` is any yamlover entity — a project directory (one with a `.yo/`),
 a plain directory, or a single file. It defaults to the current directory. The
 command starts a local web server — **bound to `127.0.0.1` (local only) by
 default**, the safe default for a personal viewer and for the desktop wrapper
@@ -25,6 +33,18 @@ prefix instead of `/` — for hosting several instances behind one reverse proxy
 SPA shell as `window.__BASE__`. The `BASE_PATH` env var seeds the same setting
 (an explicit flag wins), so a shell-less container image can inject it.
 
+`--read-only` serves the tree **content read-only** — e.g. publishing `docs/`:
+every user-data-mutating request (edits, tagging, moves, renames, uploads,
+board edits, agent-docs install) answers **403** `server is read-only`,
+enforced by a route allowlist on the backend, and the UI hides every
+modification affordance (the flag rides into the SPA shell as
+`window.__READONLY__`; `GET /api/info` reports `readOnly` too). The server
+still maintains its own index (`.yo/index.db`), so browsing stays fast and
+live; but it never generates thumbnails (pre-existing ones still serve — a
+miss falls back to the type glyph), never materializes `settings.yo`, and
+never rewrites source files over an externally inferred move. The
+`YAMLOVER_READ_ONLY` env var (`1`/`true`/`yes`) seeds the same setting.
+
 The page is split into two independently scrolling panes:
 
 - **Left — a table of contents.** A collapsible tree of **every** node — object
@@ -62,7 +82,7 @@ Surfaced *stray* files (those not described by the tree) honor `.gitignore` by
 default — `node_modules/`, build output, etc. are hidden. Pass `--no-gitignore`
 to show everything.
 
-The browser URL is the node's path in **JSON space** — `/examples[0]/markup` —
+The browser URL is the node's path in **JSON space** — `/examples/0/markup` —
 plus `?format=` for the representation. Each key is percent-encoded, so a key
 that itself contains a `/` (e.g. `@vitejs/plugin-react`) stays a single segment.
 It updates as you navigate and is shareable / back-button friendly — opening a
@@ -72,7 +92,7 @@ deep link expands the TOC along the path and selects (and scrolls to) the target
 splitting its path at the page boundary and replacing that `/` with `#`: for a full
 path `a/b/c/d` whose served page is `a/b`, the *scrollable* URL is `a/b#c/d` — the
 page loads `a/b` and scrolls to the `c/d` node within it. A **fragment** (a tagged
-region — see `ANNOTATIONS.md`) is one instance: a region of `…/IMG.jpg` lives at
+region — see `docs/annotations`) is one instance: a region of `…/IMG.jpg` lives at
 `…/IMG.jpg/yamlover-fragments/<slug>`, so its scrollable URL is
 `…/IMG.jpg#yamlover-fragments/<slug>` — opening it (or clicking the region in the
 fragments panel) scrolls/pans to **and briefly flashes** the region.
@@ -86,7 +106,7 @@ property-graph index) holds nodes and pointer edges. The HTTP layer
 shapes the React client consumes (the `$yamloverLink` / `$yamloverBinary` /
 `$yamloverMixed` markers, the schema view).
 
-The on-disk index lives at `<root>/.yamlover/index.db`. It is a derived cache
+The on-disk index lives at `<root>/.yo/index.db`. It is a derived cache
 with a persistent **file manifest** (path + hash + size + mtime): startup
 re-indexes against it (an offline reconcile — unchanged blobs are never re-read,
 so it is cheap), and the FS watcher re-indexes on edits and broadcasts the diff
@@ -127,7 +147,7 @@ take an optional `depth` (container-nesting limit).
 |----------|---------|
 | `GET /api/info` | the breadcrumb head (the root label) |
 | `GET /api/tree?path&depth` | the TOC subtree at `path`, `depth` levels deep (default 3) — fetched again per branch for lazy expansion |
-| `GET /api/json?path&depth&binary` | the node's value, one level deep (`depth` default 1); nested containers become link markers (`&binary=1` for a binary leaf's base64) |
+| `GET /api/content/{slash-path}?depth` | **THE ONE WIRE** (`text/yamlover`): the node as a yamlover envelope — header facets, the serialized `source` subtree (cut members respelled as pointers), the fragment-keyed `side` sidecar, `relations`. Clients parse it with the shared `tools/parser` and derive the legacy NodeJson locally |
 | `GET /api/schema?path&depth` | the node's instance schema, with the same link markers |
 | `GET /api/blob?path` | a file-backed node's **raw bytes**, with its (inferred) format as the `Content-Type` |
 | `GET /api/thumb?path&w&h` | a lazily-generated thumbnail of a file-backed blob |
@@ -135,12 +155,12 @@ take an optional `depth` (container-nesting limit).
 | `GET /api/annotations?path` | the annotations on a node |
 | `GET /api/query?q&path` | the query evaluator (colon match templates) |
 | `GET /api/dangling` | pointers that did not resolve at index time |
-| `GET /api/config` | the effective `settings.yamlover` — raw source + parsed settings (read-only; written via `/api/edit`, hot-reloaded on change) |
+| `GET /api/config` | the effective `settings.yo` — raw source + parsed settings (read-only; written via `/api/edit`, hot-reloaded on change) |
 | `GET /api/events` | SSE: `{type:"diff",…}` reindex diffs + `{type:"task",…}` progress |
 | `GET /api/tasks` | long-running tasks in flight (a snapshot for a fresh page) |
 | `POST /api/reindex` | manual reconcile (the watcher's fallback) |
 | `POST /api/edit` | the yamlover **editor** — surgical source edits (see below) |
-| `POST /api/preview` | **stateless**: render a standalone yamlover source as `/api/json` would (nothing touches the store) |
+| `POST /api/preview` | **stateless**: render a standalone yamlover source as a content envelope, like `/api/content` (nothing touches the store) |
 | `POST /api/edit-text` | **stateless**: apply `/api/edit` ops to a standalone source, returning the new source |
 | `POST /api/paste` | clipboard paste / upload (text or files) |
 | `POST /api/mv` | mediated move (surgical inbound-ref rewrite + auto-relink) |
@@ -157,8 +177,8 @@ order and grouped by backing file. It **splices source lines** rather than reser
 comments, quoting, and block scalars elsewhere in the document survive an edit untouched.
 
 `path` is a plain yamlover path naming the node being edited; each segment is a key
-(`:doc:description`) or an **absolute entry index** (`:doc[3]` — keyed entries consume indices
-too). A node has four **facets**: its scalar value, its keyed entries, its ordinal entries, and
+(`:doc:description`) or an **absolute entry index** (`:doc:3`, the bare-integer segment —
+keyed entries consume indices too; the retired `:doc[3]` reads as an alias). A node has four **facets**: its scalar value, its keyed entries, its ordinal entries, and
 its `!!<…>` meta tag.
 
 | op | facets | `meta` |
@@ -171,13 +191,13 @@ its `!!<…>` meta tag.
 That is why editing a chunk's prose is an `emplace`: an annotated chunk is an omni node whose tag
 applications are keyed entries laid over its scalar, and only the scalar facet is being replaced.
 A chapter's **title** works the same way — it is the chapter node's own scalar self-value
-(CHAPTER.md), so a title edit is an `emplace` on the chapter path itself (an empty payload drops
+(docs/documents/chapter), so a title edit is an `emplace` on the chapter path itself (an empty payload drops
 the title line).
 
 `yamlover` is valid inline yamlover **source**, not prose — the caller escapes its own text (the web
 client through `escapeYamloverScalar`), and the server parses the fragment to validate it before
 anything is written. `meta` is a schema pointer (`*::yamlover:$defs:chapter`) written as the tag;
-`null` removes it. `concrete` (`yamlover` | `file/yamlover` | `dir/yamlover`) is accepted only where
+`null` removes it. `concrete` (`yamlover` | `file/yamlover` | `dir/.yo`) is accepted only where
 content is **born**, and rejected on an existing node — converting one is a move, not an edit.
 
 Creating an object is therefore just an `insert` carrying a `meta` and a body: a document's body
@@ -219,10 +239,10 @@ Registered today (a representative slice — the registry is the source of truth
 | renderer | matches (format) | draws with |
 |----------|------------------|------------|
 | `chapter` | `x-yamlover-chapter` | a positional body: numbered chunks + subchapter links |
-| `tag` / `board` | `x-yamlover-tag` / `x-yamlover-board` | tag-hierarchy diagram / board (handled outside the specificity loop) |
+| `tag` / `board` | `x-yamlover-onto` / `x-yamlover-board` | tag-hierarchy diagram / board (handled outside the specificity loop) |
 | `task` | `x-yamlover-task` | task view |
-| `table` | `x-yamlover-table` | a grid (`MARKLOWER.md`): rows/header/caption from the omni entries, merged cells (`colSpan`/`rowSpan`) from resolved relative-index `*` pointers, nested tables inline, marklower cells; prose cells edit in place under the lock |
-| `marklower` | `text/marklower` (a chapter's prose chunks, by schema propagation) | its own inline grammar (`MARKLOWER.md`): emphasis, `` `code` ``, `$$math$$` via KaTeX, links, and `*[…](…)` media embeds |
+| `table` | `x-yamlover-table` | a grid (`docs/documents/marklower`): rows/header/caption from the omni entries, merged cells (`colSpan`/`rowSpan`) from resolved relative-index `*` pointers, nested tables inline, marklower cells; prose cells edit in place under the lock |
+| `marklower` | `text/marklower` (a chapter's prose chunks, by schema propagation) | its own inline grammar (`docs/documents/marklower`): emphasis, `` `code` ``, `$$math$$` via KaTeX, links, and `*[…](…)` media embeds |
 | `markdown` | `text/markdown` | [marked](https://marked.js.org) |
 | `asciidoc` | `text/asciidoc` | [@asciidoctor/core](https://asciidoctor.org) |
 | `csv` | `text/csv`, `text/tab-separated-values` | a table |
@@ -292,7 +312,7 @@ $ npm run test:watch
 This server suite is **separate** from the repository root's `npm test` (which
 runs only the parser and engine suites) and from the editor package's own suite
 (`npm --prefix tools/yed test` — the grammar/corpus conformance gate,
-`EDITOR.md` §9). CI gates on all of them, so run them before pushing. (Run
+`docs/server/editor/yed`). CI gates on all of them, so run them before pushing. (Run
 everything from the project root — see the root `package.json`.)
 
 ## Layout
@@ -311,7 +331,7 @@ src/server/            the engine-backed JSON API
   agent-docs/            the AGENTS.md / CLAUDE.md guide installed by POST /api/agent-docs
 src/client/            the React SPA (tree, node view, render, icons, paths, live SSE)
   renderers/             facet-predicate renderer registry + per-format renderers; the
-                         unlocked editors are yed mounts over ../yed (@yamlover/yed) — EDITOR.md
+                         unlocked editors are yed mounts over ../yed (@yamlover/yed) — docs/server/editor
   vendor/djvu.js         prebuilt DjVu.js bundle (GPL-v2; see vendor/README.md)
 test/                  Vitest suite (server logic + client components)
 index.html             SPA shell

package/bin/ga4.js

@@ -0,0 +1,90 @@
+// The Google Analytics 4 tag injected into the served SPA shell.
+//
+// OFF UNLESS THE SERVER IS TOLD OTHERWISE. Nothing here runs without $GA4_MEASUREMENT_ID,
+// which only the hosted deployment sets — `npx yamlover`, the desktop app and any
+// self-hosted tree serve the same shell and send nothing. A local-first viewer that phoned
+// home by default would be a different product.
+//
+// The tag reports a path the SERVER chose ($GA4_PAGE_PATH), never the one in the address
+// bar, because the address bar is not safe to forward:
+//
+//   • a demo instance is mounted at /demo/<hash>, and that hash IS the credential for it —
+//     copying it into a third-party report hands out the instance;
+//   • below the mount point the URL is the yamlover data path, and in a demo the visitor
+//     may have typed the node names themselves.
+//
+// So a demo collapses to a single page ($GA4_COLLAPSE_PATH) and drops document.title, which
+// the SPA rewrites to the node's own labels. The docs instance serves published content, so
+// it reports its real sub-paths — knowing which chapters get read is the point.
+//
+// No `anonymize_ip`: that is a Universal Analytics parameter and GA4 ignores it. GA4
+// truncates the address on receipt and never stores it.
+
+/** Embed a value as a JS literal that is safe inside `<script>` (`</script>` in a string
+ *  would otherwise close the element early). */
+const js = (v) => JSON.stringify(v ?? "").replace(/</g, "\\u003c");
+
+/** The GA4 `<script>` for a shell served at `basePath`, or "" when analytics is off.
+ *
+ *  `measurementId` — the G-XXXXXXXXXX stream id.
+ *  `pagePath`      — the mount point as analytics should see it (e.g. `/demo/<id>`, `/docs`).
+ *  `collapse`      — report `pagePath` alone, never a sub-path or the document title. */
+export function ga4Tag({ measurementId, basePath = "", pagePath = "", collapse = false }) {
+  if (!measurementId) return "";
+  return (
+    `<script async src="https://www.googletagmanager.com/gtag/js?id=${encodeURIComponent(measurementId)}"></script>` +
+    `<script>(function(){` +
+    // Initialise once per document. The tag wraps history.pushState, so a second copy in the
+    // same page would wrap the wrapper and report every SPA navigation twice.
+    `if(window.__yoGa4__)return;window.__yoGa4__=1;` +
+    // A collapsed tag is handed no base path at all. `at()` would not read it either way,
+    // but not emitting it is what makes "this script cannot know the hash" checkable by
+    // reading the page instead of by reasoning about a branch.
+    `var ID=${js(measurementId)},BASE=${js(collapse ? "" : basePath)},PUB=${js(pagePath)},COLLAPSE=${collapse ? "1" : "0"};` +
+    `window.dataLayer=window.dataLayer||[];function gtag(){dataLayer.push(arguments)}window.gtag=gtag;` +
+    `gtag("js",new Date());` +
+    // The reported path. Query and fragment are dropped wholesale: both carry data paths.
+    // Which also drops the `utm_` keys a referral arrives with — and gtag reads campaign
+    // attribution off `page_location`, so without the lines below every tagged link (the
+    // README's, say) would report as direct traffic. An explicit campaign field overrides
+    // its `utm_` twin, so the five standard keys are read once at load and passed by name.
+    // By name, and only those five: the allowlist is what keeps the redaction above true.
+    //
+    // Not on a collapsed instance, though. There the promise is stronger — NOTHING from this
+    // URL is forwarded — and a hand-written `?utm_source=<the hash>` would otherwise walk
+    // straight through the allowlist. A demo is reached through the registration page anyway,
+    // which is a plain document with a stock tag that reads the query itself.
+    `var CAMPAIGN={};if(!COLLAPSE){var Q=new URLSearchParams(location.search);` +
+    `["source","medium","campaign","term","content"].forEach(function(k){` +
+    `var v=Q.get("utm_"+k);if(v)CAMPAIGN["campaign_"+k]=v})}` +
+    `function at(){if(COLLAPSE)return PUB+"/";var p=location.pathname;` +
+    `if(BASE&&p.indexOf(BASE)===0)p=p.slice(BASE.length)||"/";return PUB+p}` +
+    // Stamped as GLOBAL parameters rather than per-event: the tag's own enhanced-measurement
+    // events (scroll, outbound click, history) are fired by gtag.js and would otherwise
+    // report location.href, routing around the redaction above.
+    `var last="";function stamp(){var p=at();last=p;` +
+    `gtag("set",{page_path:p,page_location:location.origin+p,page_title:COLLAPSE?"yamlover demo":document.title})}` +
+    `stamp();gtag("config",ID,Object.assign({send_page_view:false},CAMPAIGN));gtag("event","page_view");` +
+    // The SPA routes on the JSON path with no document load, so page_view is re-sent by hand.
+    // A collapsed instance reports one path, so every navigation inside it is a repeat — the
+    // `last` guard keeps it to a single page_view instead of one per click.
+    `function nav(){if(at()===last)return;stamp();gtag("event","page_view")}` +
+    `["pushState","replaceState"].forEach(function(m){var o=history[m];` +
+    `history[m]=function(){var r=o.apply(this,arguments);nav();return r}});` +
+    `addEventListener("popstate",nav)})()</script>`
+  );
+}
+
+/** Read the tag's configuration from the environment. `basePath` comes from the caller
+ *  because the flag may override $BASE_PATH; `GA4_PAGE_PATH` defaults to it, which is
+ *  right for a root or /docs mount and is overridden for a demo (whose path is a secret). */
+export function ga4ConfigFromEnv(basePath) {
+  const measurementId = process.env.GA4_MEASUREMENT_ID ?? "";
+  if (!measurementId) return null;
+  return {
+    measurementId,
+    basePath,
+    pagePath: process.env.GA4_PAGE_PATH ?? basePath,
+    collapse: ["1", "true", "yes"].includes(String(process.env.GA4_COLLAPSE_PATH ?? "").toLowerCase()),
+  };
+}

package/bin/yamlover.js

@@ -5,7 +5,7 @@
  *   npx yamlover [ROOT] [--port N]
  *
  * ROOT is the directory to browse (default: the current directory). It may be a
- * yamlover node (with `.yamlover/`), a plain directory, or a single file — the
+ * yamlover node (with `.yo/`), a plain directory, or a single file — the
  * same shapes `tools/walker` understands.
  *
  * Two serve modes, chosen automatically:
@@ -36,6 +36,7 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 import { createRequire } from "node:module";
 import { dirname, join, resolve, extname, sep } from "node:path";
 import fs from "node:fs";
+import { ga4Tag, ga4ConfigFromEnv } from "./ga4.js";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkgRoot = resolve(__dirname, ".."); // tools/server
@@ -67,6 +68,10 @@ let prodFlag = false; // force production (static) mode even in the repo checkou
 // Seeded from $BASE_PATH so a shell-less image (e.g. distroless) can inject it via env without
 // needing `sh -c` to expand it into a `--base-path` flag; an explicit flag below still overrides.
 let basePath = process.env.BASE_PATH ?? "";
+// CONTENT READ-ONLY: every user-data-mutating API route answers 403 and the UI hides its edit
+// affordances; the server still maintains its own index (.yo/index.db). Seeded from
+// $YAMLOVER_READ_ONLY (same shell-less-image rationale as $BASE_PATH); `--read-only` below too.
+let readOnly = ["1", "true", "yes"].includes(String(process.env.YAMLOVER_READ_ONLY ?? "").toLowerCase());
 // Normalize a base path: leading `/`, no trailing `/`; `""`/`"/"` → disabled.
 function normBase(s) {
   let b = (s ?? "").trim();
@@ -88,10 +93,12 @@ for (let i = 0; i < argv.length; i++) {
   else if (a.startsWith("--base-path=")) basePath = normBase(a.slice("--base-path=".length));
   else if (a === "--no-gitignore") gitignore = false;
   else if (a === "--prod") prodFlag = true;
+  else if (a === "--read-only") readOnly = true;
   else if (a === "--help" || a === "-h") {
-    console.log("usage: npx yamlover [ROOT] [--port N] [--headless] [--host ADDR] [--base-path PREFIX] [--no-gitignore] [--prod]");
+    console.log("usage: npx yamlover [ROOT] [--port N] [--headless] [--host ADDR] [--base-path PREFIX] [--no-gitignore] [--prod] [--read-only]");
     console.log("  default: serve on 127.0.0.1 (local only); --headless serves on all interfaces");
     console.log("  --base-path PREFIX: serve the whole app under PREFIX (e.g. /demo/abc) instead of /");
+    console.log("  --read-only: serve content read-only — every modifying request is refused (403)");
     process.exit(0);
   } else if (!a.startsWith("-")) rootArg = a;
 }
@@ -101,6 +108,10 @@ if (!fs.existsSync(dataRoot)) {
   process.exit(1);
 }
 
+// Analytics: null unless $GA4_MEASUREMENT_ID is set, which only the hosted deployment does.
+// Resolved after the flags so it sees the final base path.
+const ga4 = ga4ConfigFromEnv(basePath);
+
 // --- mode ----------------------------------------------------------------- //
 // The engine SOURCE is present only in the monorepo checkout; its absence (the
 // published package) — or an explicit `--prod` — selects production/static mode.
@@ -239,7 +250,7 @@ if (prod) {
     try {
       let html = fs.readFileSync(indexHtmlPath, "utf-8");
       html = await vite.transformIndexHtml(url.pathname, html);
-      html = injectBase(html); // base-path-aware shell (no-op without --base-path)
+      html = injectGlobals(html); // base-path/read-only-aware shell (no-op without either)
       res.setHeader("Content-Type", "text/html; charset=utf-8");
       res.end(html);
     } catch (e) {
@@ -256,7 +267,17 @@ if (prod) {
   // "/src/" source modules; "/node_modules/" pre-bundles); everything else is an app route and
   // gets the SPA shell directly.
   const VITE_PREFIXES = ["/@", "/src/", "/node_modules/"];
+  // The one package asset the shell asks for by name, so it has to be a REAL FILE in live mode
+  // too. Vite's own public/ middleware is unreachable behind the prefix gate above — deliberately,
+  // since letting it serve stray package files is exactly what would shadow a served-tree route —
+  // so the icon gets a single explicit exception rather than the whole directory. Production needs
+  // none of this: `vite build` copies public/ into dist/client, which serveStatic already reads.
+  const faviconPath = join(pkgRoot, "public", "yo-favicon.svg");
   serveClient = (req, res, url) => {
+    if (url.pathname === "/yo-favicon.svg" && fs.existsSync(faviconPath)) {
+      res.setHeader("Content-Type", "image/svg+xml");
+      return fs.createReadStream(faviconPath).pipe(res);
+    }
     if (VITE_PREFIXES.some((p) => url.pathname.startsWith(p))) {
       vite.middlewares(req, res, () => spaShell(res, url)); // an unmatched vite path still lands on the shell
     } else {
@@ -279,7 +300,8 @@ const ts = () => {
 handle = createHandlers(dataRoot, {
   gitignore,
   watch: true, // re-index + push on external edits
-  ensureSettings: true, // create .yamlover/settings.yamlover with defaults if absent (so the gear opens)
+  ensureSettings: !readOnly, // create .yo/settings.yo with defaults if absent (so the gear opens)
+  readOnly,
   log: (line) => console.log(`yamlover ${ts()}  ${line}`),
 });
 handle.ready.catch((e) => console.error(`yamlover ${ts()}  indexing failed:`, e));
@@ -332,22 +354,33 @@ function serveStatic(res, url, distClient, distIndex) {
 function serveIndex(res, distIndex) {
   res.setHeader("Content-Type", "text/html; charset=utf-8");
   res.setHeader("Cache-Control", "no-cache");
-  if (basePath) {
-    // The shell must learn its prefix (the client prepends it to every server URL) and its
-    // root-absolute asset refs must point under the prefix (the strip above maps them back).
-    res.end(injectBase(fs.readFileSync(distIndex, "utf-8")));
-    return;
-  }
-  fs.createReadStream(distIndex).pipe(res);
+  // Always rewritten, never streamed: the built shell's asset refs are RELATIVE (vite
+  // `base: "./"`), and a client route is arbitrarily deep — `./assets/…` served at /a/b/c
+  // would resolve to /a/b/assets/…. Anchoring them at the mount point is what makes a deep
+  // link reloadable, with or without a base path.
+  res.end(injectGlobals(fs.readFileSync(distIndex, "utf-8")));
 }
 
-/** Make a served index.html base-path-aware: expose `window.__BASE__` for the client's URL helper
- *  and prefix root-absolute `src="/…"` / `href="/…"` asset refs with the base path (protocol-relative
- *  `//…` left alone). No-op when no base path is set. */
-function injectBase(html) {
-  if (!basePath) return html;
-  html = html.replace(/((?:src|href)=")\/(?!\/)/g, `$1${basePath}/`);
-  const tag = `<script>window.__BASE__=${JSON.stringify(basePath)}</script>`;
+/** Anchor a served index.html to its mount point and stamp the server's posture into it.
+ *
+ *  Asset refs (`src`/`href`) are rewritten to absolute `<basePath>/…`: the build emits them
+ *  relative so LAZY chunks resolve against `import.meta.url` (see vite.config.mjs), but the
+ *  shell itself is served at every client route, so its own refs must not follow the URL.
+ *  Both spellings are handled — `./assets/…` as built, `/assets/…` should the base ever go
+ *  back to absolute; protocol-relative `//…` is left alone.
+ *
+ *  The pre-render globals follow: `window.__BASE__` (the client's URL helper prefix) and
+ *  `window.__READONLY__` (the client hides every modification affordance), each set only
+ *  when it applies. Last comes the analytics tag, which the hosted deployment configures
+ *  through the environment and every other way of running yamlover leaves off (ga4.js). */
+function injectGlobals(html) {
+  html = html.replace(/((?:src|href)=")(?:\.\/|\/(?!\/))/g, `$1${basePath}/`);
+  const globals = [];
+  if (basePath) globals.push(`window.__BASE__=${JSON.stringify(basePath)}`);
+  if (readOnly) globals.push("window.__READONLY__=true");
+  let tag = globals.length ? `<script>${globals.join(";")}</script>` : "";
+  if (ga4) tag += ga4Tag(ga4);
+  if (!tag) return html;
   return html.includes("<head>") ? html.replace("<head>", `<head>${tag}`) : tag + html;
 }
 
@@ -373,6 +406,11 @@ function listenWithFallback(p, triesLeft) {
     server.off("error", onError); // bound OK — stop intercepting listen errors
     console.log(`yamlover ${ts()}  serving ${dataRoot}${prod ? "" : "  (live/Vite)"}`);
     console.log(`                        http://${shown}:${p}/  (bound to ${host})`);
+    // Say it out loud: analytics is off in every normal run, so when it IS on the operator
+    // should see which stream is being fed and exactly what paths reach it.
+    if (ga4) {
+      console.log(`                        analytics ${ga4.measurementId} → ${ga4.pagePath || ""}/${ga4.collapse ? "" : "…"}`);
+    }
   };
   server.once("error", onError);
   server.once("listening", onListening);