yamlover 0.3.10 → 0.3.12

package/README.md

@@ -3,15 +3,19 @@
 Browse a yamlover tree in the web browser.
 
 ```console
-$ npx yamlover [ROOT] [--port N] [--host ADDR] [--no-gitignore]
+$ npx yamlover [ROOT] [--port N] [--headless] [--host ADDR] [--no-gitignore] [--prod]
 ```
 
-`ROOT` is any yamlover entity — a directory with a `.yamlover/schema.yaml`, a
-plain directory, or a single file (the same shapes [`walker`](../walker/)
-understands). It defaults to the current directory. The command starts a local
-web server (on `0.0.0.0` by default, so it is reachable from the network — use
-`--host 127.0.0.1` to keep it private) and serves a React single-page app that
-lets you browse the entity starting from `ROOT`.
+`ROOT` is any yamlover entity — a project directory (one with a `.yamlover/`),
+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
+(`tools/desktop`) — and serves a React single-page app that browses the entity
+starting from `ROOT`. Pass `--headless` to bind `0.0.0.0` (all interfaces, e.g.
+for remote access with no GUI), or `--host ADDR` for an explicit override.
+`--prod` forces the prebuilt static client + bundled server (the default when
+the dev sources aren't present, e.g. an installed package); without it, a
+checkout runs the client from source via Vite with HMR.
 
 The page is split into two independently scrolling panes:
 
@@ -20,164 +24,206 @@ The page is split into two independently scrolling panes:
   `05-scalar-as-file` is listed and clickable). A node is *expandable* when it is
   a container with children and has no *active* renderer (see *Renderers*); the
   first three levels load expanded, and deeper branches load lazily via the
-  chevron. Each entry is labeled by its schema `title` (or an instance `title`
-  child) when present, otherwise by its key (objects) or `[index]` (arrays).
+  chevron. Each entry is labeled by its `title` when present, otherwise by its
+  key (objects) or `[index]` (arrays).
 
-  Each row carries a **type/format icon** (chosen by the schema `format`, falling
-  back to `type` — `{}`/`[]` for object/array, `"`/`#`/`◧` for
+  Each row carries a **type/format icon** (chosen by the node's `format`, falling
+  back to its type — `{}`/`[]` for object/array, `"`/`#`/`◧` for
   string/number/boolean, 📅/✉️/🔗/🖼️… for formats). The tree is agnostic to a
   node's *concrete* (how it is stored) — that shows in the node view's tags.
-- **Right — the selected node**, in one of four representations (tabs):
-  - **yaml-schema** *(default)* — our schema (the yamlover schema concrete) as YAML.
-  - **yaml** — the node's value as YAML.
-  - **json** — the node's value as JSON.
-  - **json-schema** — the standard instance JSON Schema (every leaf `const`).
-
-  All four behave **identically**: syntax-highlighted, **one level deep**, with
-  every nested node shown as a **hyperlink** you click to descend (never inlined)
-  — `{ object with N properties }`, `[ array with M items ]`, or
-  `< binary of N bytes >`. A registered renderer, if any, replaces the value
-  views. The selected representation is part of the URL (`?format=`), so it is
-  preserved as you navigate and is shareable.
-
-  A binary leaf's bytes are read only when you select it and view its value: the
-  yaml view shows a YAML `!!binary` block, json shows the `{format,size,base64}`
-  metadata.
-
-Surfaced *stray* files (those the schema does not describe) honor `.gitignore` by
+- **Right — the selected node.** A node with a registered renderer shows that
+  renderer's view; every node also offers a set of **data-representation tabs**,
+  always including:
+  - **yamlover** *(default)* — the node's value in yamlover (YAML-family) syntax.
+  - **yamlover/schema** — the node's instance schema.
+
+  plus **json5p** for a JSON-family file. All representations behave
+  **identically**: syntax-highlighted, **one level deep**, with every nested node
+  shown as a **hyperlink** you click to descend (never inlined) —
+  `{ object with N properties }`, `[ array with M items ]`, or
+  `< binary of N bytes >`. The selected representation is part of the URL
+  (`?format=`), so it is preserved as you navigate and is shareable.
+
+  A binary leaf's bytes are read only when you select it and view its value.
+
+The page updates **live**: an FS watcher re-indexes on external edits and pushes
+what changed over an SSE stream (`/api/events`), so every surface (tree, node
+view, tag pages) refreshes without a reload.
+
+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. Schema-described children are always shown.
+to show everything.
 
 The browser URL is the node's path in **JSON space** — `/examples[0]/markup` —
-never schema space, so there are no `properties` segments, 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 deep link expands
-the TOC along the path and selects (and scrolls to) the target node.
+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
+deep link expands the TOC along the path and selects (and scrolls to) the target.
 
 ## How it works
 
-This is a TypeScript reimplementation of the read side of [`walker`](../walker/)
-(concretes, `$ref`/`$defs`, inline `const`, collapsed files, expanded
-subdirectories), plus a small server and SPA. There is **no build step**: the
-launcher runs [Vite](https://vitejs.dev) in middleware mode, serving the client
-from source with HMR and loading the server-side materializer through Vite's
-`ssrLoadModule`.
-
-Leaf bytes are **read lazily**: materialization builds the tree's structure but
-does not read a leaf's content until that node is actually serialized. So listing
-or eliding a node never reads its file — `value: 30` is read only when its node is
-shown, and a binary blob only when its base64 is requested. The materialized tree
-is cached per server for a short window, so a burst of clicks does not re-read the
-filesystem; edits show up after the window on reload.
+The server is backed by the yamlover **engine** (`tools/engine`): `walkDir`
+turns the directory concrete into the parser's IR, and a `Store` (a SQLite
+property-graph index) holds nodes and pointer edges. The HTTP layer
+(`src/server/engine-api.ts`) reads from the `Store` and emits the response
+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
+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
+over `/api/events`.
+
+**Long-running work runs as background tasks** (`src/server/tasks.ts`): the HTTP
+server listens immediately and serves the previous index (or an empty one on a
+cold start) while the initial walk and the background hasher (which fills in
+content hashes for large blobs the walk no longer reads) run. Store-mutating
+jobs (index, mv, paste, annotate) serialize through one writer queue; reads
+never wait. Progress lands both on the console and in the web UI (SSE `task`
+frames + `GET /api/tasks`).
+
+Leaf bytes are read **lazily**: materialization builds structure but does not
+read a leaf's content until that node is serialized.
+
+### Build
+
+There are two run modes:
+
+- **Dev** (a checkout): the launcher runs [Vite](https://vitejs.dev) in
+  middleware mode, serving the client from source with HMR and loading the
+  server handler through Vite's `ssrLoadModule`.
+- **Prod** (`--prod`, or an installed package): the client is a prebuilt static
+  SPA under `dist/client` and the server handler is a single bundle at
+  `dist/server.js`. `scripts/build.mjs` produces both — `vite build` for the
+  client and `esbuild` for the server (bundling the engine, parser, and the
+  `ignore` / `js-yaml` / `xxhash-wasm` deps, plus the dynamically-imported
+  thumbnail codecs). It runs on `prepack`, so the published npm package ships
+  `dist/` and has **no runtime dependencies**.
 
 ### API
 
-All endpoints take a JSON-space `path` (default `/`); `json` and `schema` take an
-optional `depth` (container-nesting limit).
+All endpoints take a JSON-space `path` (default `/`); the value/schema endpoints
+take an optional `depth` (container-nesting limit).
 
 | endpoint | returns |
 |----------|---------|
-| `GET /api/info` | `{ root }` — the root label (the served entity's yamlover title, else its directory name): the breadcrumb head and TOC root |
-| `GET /api/tree?path&depth` | the table of contents rooted at `path`, `depth` levels deep (default 3) — fetched again per branch for lazy expansion |
-| `GET /api/json?path&depth` | the node's value, one level deep (`depth` default 1); nested containers become link markers (add `&binary=1` for a binary leaf's base64) |
-| `GET /api/schema?path&depth` | the node's instance JSON Schema, one level deep, with the same link markers |
-| `GET /api/blob?path` | a file-backed node's **raw bytes**, with its (inferred) format as the `Content-Type` — what the image / html / pdf / djvu / markup renderers read, instead of base64 over `json` |
+| `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/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 |
+| `GET /api/tagged?path` | the materials filed under a tag (annotations → targets) |
+| `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/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/paste` | clipboard paste / upload (text or files) |
+| `POST /api/mv` | mediated move (surgical inbound-ref rewrite + auto-relink) |
+| `POST /api/tag` | create-on-miss a tag in the taxonomy |
+| `POST / DELETE /api/annotate` | add / remove an annotation on a target |
+| `POST /api/fragment` | upsert a fragment (region of a target) |
+| `POST /api/board` | board mutations |
+| `POST /api/agent-docs` | write the LLM-agent guide (`AGENTS.md` + `CLAUDE.md`) into the root |
 
 A **link marker** — `{ "$yamloverLink": { kind, path, count|size } }` — stands in
 for a node shown only as a link (a nested container past the one-level view, or
 any binary leaf); the client renders it as a `{ object with N properties }`,
 `[ array with M items ]`, or `< binary of N bytes >` hyperlink. The same marker
-appears in both the value and the schema, so every representation (YAML/JSON ×
-data/schema) renders identically — just a syntax choice over one structure. A
-selected binary leaf's bytes arrive as `{ "$yamloverBinary": {format,size,base64} }`.
+appears in both the value and the schema, so every representation renders
+identically. A selected binary leaf's bytes arrive as
+`{ "$yamloverBinary": {format,size,base64} }`.
 
 ### Renderers
 
-A renderer is keyed by a **(type, format)** tuple — the JSON-Schema `type` plus
-its `format` — the same key the TOC icons and the link markers carry. A node with
-no matching renderer falls through to the default tabbed view (YAML/JSON ×
-data/schema) and expands normally in the TOC.
+A renderer declares an **`accepts` predicate** over a node's **type facets**
+(value-type, `format`, and the keyed/ordinal capability flags) — most are
+`byFormat("…")`, which matches on the node's format and tolerates the other
+facets (so tagging a markdown node doesn't break its markdown rendering). The
+most specific matching renderer wins; a node with no match falls through to the
+default data-representation tabs and expands normally in the TOC.
 
-The registry lives in `src/client/renderers/`. A renderer participates three ways,
-all on the one tuple:
+The registry lives in `src/client/renderers/`. A renderer participates several
+ways:
 
 - **`render`** — the full RHS page (its tab is the node's default representation).
-- **`renderChunk`** — its *inline* form, when embedded in another renderer's page.
-  A renderer composes children by routing each to the renderer for the child's own
-  tuple: the `chapter` renderer draws each of its `chunks` by delegating to that
-  chunk's renderer (a `string`/`text/markdown` chunk → the `text` renderer; an
-  `image/png` chunk would route to an image renderer, no change to `chapter`).
+- **`renderChunk`** — its *inline* form, when embedded in another renderer's page
+  (e.g. the `chapter` renderer draws each chunk by delegating to that chunk's
+  own renderer).
 - **`tocView`** — how the node appears in the TOC: which children are navigable,
-  whether it expands, and whether they are loaded (default: its own children,
-  lazily loaded). A renderer can unwrap or filter — `chapter` surfaces its
-  subchapters directly (from its `children` array) and keeps its `chunks` off the
-  tree, so the TOC reads as a table of contents.
-
-A renderer may also declare **`depth`** — the value depth `NodeView` fetches for
-it (default 1; `chapter` needs 2 to reach its chunk/subchapter elements).
-
-Registered today:
-
-| renderer | (type, format) | draws with |
-|----------|----------------|------------|
-| `chapter` | `object` / `x-yamlover-chapter` | numbered chunks + subchapter links |
-| `tag` | `object` / `x-yamlover-tag` | a hierarchy diagram: supertag (containment parent) and subtags (children) wired to the current tag |
-| `text` | `string` / `text/markdown` | [marked](https://marked.js.org) |
-| `asciidoc` | `string` / `text/asciidoc` | [@asciidoctor/core](https://asciidoctor.org) |
-| `image` | `binary` / `image/*` | native `<img>` |
-| `html` | `binary` / `text/html` | sandboxed `<iframe>` |
-| `pdf` | `binary` / `application/pdf` | [pdf.js](https://mozilla.github.io/pdf.js/) via [react-pdf](https://github.com/wojtekmaj/react-pdf) |
-| `djvu` | `binary` / `image/vnd.djvu` | [DjVu.js](https://djvu.js.org) (vendored) |
+  whether it expands and is loaded. A renderer can unwrap or filter (e.g.
+  `chapter` surfaces its subchapters and keeps its chunks off the tree).
+- **`depth`** — the value depth `NodeView` fetches for it (default 1).
+
+Registered today (a representative slice — the registry is the source of truth):
+
+| renderer | matches (format) | draws with |
+|----------|------------------|------------|
+| `chapter` | `x-yamlover-chapter` | numbered chunks + subchapter links |
+| `tag` / `board` | `x-yamlover-tag` / `x-yamlover-board` | tag-hierarchy diagram / board (handled outside the specificity loop) |
+| `task` | `x-yamlover-task` | task view |
+| `markdown` / `marklower` | `text/markdown` | [marked](https://marked.js.org) |
+| `asciidoc` | `text/asciidoc` | [@asciidoctor/core](https://asciidoctor.org) |
+| `csv` | `text/csv`, `text/tab-separated-values` | a table |
+| `plaintext` | `text/plain` | preformatted text |
+| `latex` | `text/x-latex` | [KaTeX](https://katex.org) |
+| `plantuml` | `text/x-plantuml` | rendered diagram |
+| `map` | KML / KMZ | [Leaflet](https://leafletjs.com) |
+| `image` | `image/png`, `jpeg`, `gif`, `webp`, `avif`, `svg+xml`, … | native `<img>` |
+| `html` | `text/html` | sandboxed `<iframe>` |
+| `pdf` | `application/pdf` | [pdf.js](https://mozilla.github.io/pdf.js/) via react-pdf |
+| `djvu` | `image/vnd.djvu` | [DjVu.js](https://djvu.js.org) (vendored) |
+| `epub` / `fb2` | `application/epub+zip` / FictionBook | paged e-book view |
+| `docx` / `doc` / `rtf` | Word / RTF | [mammoth](https://github.com/mwilliamson/mammoth.js) etc. |
+| `spreadsheet` | xlsx / xls | [SheetJS](https://sheetjs.com) |
+| `psd` / `tiff` / `heic` | Photoshop / TIFF / HEIC | decoded to a canvas/image |
 
 Adding a shape is still a single registry entry.
 
+Two implementation notes:
+
+- **DjVu has no native browser support**, so it is decoded client-side by
+  **DjVu.js**, vendored as a prebuilt bundle at `src/client/vendor/djvu.js`.
+  The library is **GPL-v2** (see `src/client/vendor/README.md` for provenance);
+  the rest of this package is not.
+- **pdf.js and DjVu.js (and several heavier codecs) reach for browser globals at
+  import time**, which would break the (Node/jsdom) test run, so their renderers
+  are **lazy-loaded** — importing the registry never pulls them in until such a
+  node is actually shown.
+
 ### File rendering and format inference
 
-The bottom seven renderers above turn the browser into a viewer for the common
-file types a tree carries. They hang off one rule, applied to any file-backed
-node that carries **no explicit schema `format`**: the server **infers a format
-from the file extension** (`formatFromExt` in `src/server/yamlover.ts`). So a
-stray `.pdf`, `.png`, or `.md` — or one declared with only `concrete: file`/
-`file/binary` — renders without a `format:` line. An explicit schema `format`
-always wins.
+The file renderers turn the browser into a viewer for the common file types a
+tree carries. They hang off one rule, applied to any file-backed node that
+carries **no explicit `format`**: the server **infers a format from the file
+extension**. So a stray `.pdf`, `.png`, or `.md` renders without a `format:`
+line. An explicit `format` always wins.
 
 Inference splits two ways by how the renderer consumes the file:
 
-- **Served as bytes** — images, `application/pdf`, `text/html`, `image/vnd.djvu`
-  become `file/binary`. Their renderer points an `<img>`/`<iframe>`/pdf-loader at
-  **`/api/blob`** (or, for DjVu, fetches the `ArrayBuffer`), so the bytes stream
-  straight from disk with no base64 round-trip.
+- **Served as bytes** — images, `application/pdf`, `text/html`, `image/vnd.djvu`,
+  etc. Their renderer points an `<img>`/`<iframe>`/loader at **`/api/blob`** (or
+  fetches the `ArrayBuffer`), so the bytes stream straight from disk with no
+  base64 round-trip.
 - **Read as text** — `.md`/`.adoc` keep a **string** value (the file's text),
-  which the `text`/`asciidoc` renderer parses to HTML. (This preserves the
-  existing "a `.md` file is a string" behavior.)
-
-Two implementation notes:
-
-- **DjVu has no native browser support**, so it is decoded client-side by
-  **DjVu.js**, vendored as a prebuilt bundle at `src/client/vendor/djvu.js`.
-  The library is **GPL-v2** (see `src/client/vendor/README.md` for provenance and
-  how to regenerate); the rest of this package is not.
-- **pdf.js and DjVu.js reach for browser globals at import time**, which would
-  break the (Node/jsdom) test run. So the `pdf` and `djvu` renderers are
-  **lazy-loaded** (`React.lazy`) — importing the registry, as the TOC and the
-  tests do, never pulls them in until a PDF/DjVu node is actually shown.
-
-`examples/18-pdf-tags` exercises this: a library of real papers stored as PDFs
-and one saved HTML page, each rendered in place.
+  which the renderer parses to HTML.
 
 ## Requirements
 
-- Node.js 18+
+- Node.js **22+**.
 
-Dependencies (React, Vite, js-yaml, ignore, plus the renderer libraries
-`react-pdf`, `marked`, `@asciidoctor/core`) install with `npm install` in this
-directory; `npx yamlover` then runs `bin/yamlover.js`. DjVu.js is **vendored**
+There are **no runtime dependencies**: the client deps are bundled into
+`dist/client` by `vite build` and the server deps into `dist/server.js` by
+esbuild at `prepack`. The `devDependencies` (React, Vite, the engine/parser, and
+the renderer libraries) are build- and test-time only. DjVu.js is **vendored**
 (`src/client/vendor/djvu.js`), not an npm dependency.
 
 ## Tests
 
-Both sides are covered by [Vitest](https://vitest.dev) (it runs the TypeScript
+This package is covered by [Vitest](https://vitest.dev) (it runs the TypeScript
 directly, no build):
 
 ```console
@@ -185,30 +231,27 @@ $ npm test          # run once
 $ npm run test:watch
 ```
 
-- **Server** (`test/*.test.ts`, Node) — against the `examples/` fixtures: path
-  encoding round-trips (incl. keys with `/`), materialization and `$ref`/`$defs`
-  equivalence, one-level link markers (object/array/binary) in value and schema,
-  lazy binaries and the `!!binary` payload, the non-YAML → raw-text fallback,
-  `buildTree` (all nodes, depth, titles), `.gitignore` filtering, and the API
-  endpoints (`/api/info`, `/api/tree`, `/api/json`, `/api/schema`).
-- **Client** (`test/client/*`, jsdom + React Testing Library) — path/URL helpers
-  and breadcrumbs, type/format icons, the renderer registry, the unified
-  `Render` (scalars, `{ object with N properties }` / `[ array with M items ]` /
-  `< binary of N bytes >` links, `!!binary`, YAML vs JSON), the `Tree`
-  (selection, lazy expand, leaves), `NodeView` (markers, tab switches, binary,
-  schema), and `App` (breadcrumb head + TOC).
+This server suite is **separate** from the repository root's `npm test`, which
+runs only the parser and engine suites. CI gates on the server suite, so run
+both before pushing. (Run everything from the project root — see the root
+`package.json`.)
 
 ## Layout
 
 ```
-bin/yamlover.js     CLI entry — arg parsing + Vite middleware-mode server
-src/server/         TypeScript port of the walker read side + JSON API
-  yamlover.ts         materialize a logical tree (lazy leaves); toPlain/toSchema/buildTree; formatFromExt
-  gitignore.ts        .gitignore predicate for surfaced stray files
-  api.ts              /api/info, /api/tree, /api/json, /api/schema, /api/blob
-src/client/         the React SPA (tree, node view, render, icons, paths)
-  renderers/          (type, format) registry + chapter/text/asciidoc/media/pdf/djvu
-  vendor/djvu.js      prebuilt DjVu.js bundle (GPL-v2; see vendor/README.md)
-test/               Vitest suite for the server logic
-index.html          SPA shell
+bin/yamlover.js        CLI entry — arg parsing + dev (Vite) / prod (dist) wiring
+scripts/build.mjs      prod build: vite build → dist/client, esbuild → dist/server.js
+src/server/            the engine-backed JSON API
+  engine-api.ts          createHandlers: all /api/* routes, backed by the engine Store
+  embed.ts               annotation / fragment / thumbnail embedding (overlay writes)
+  node-kind.ts           node-kind classification (object|array|scalar|binary|omni|mix)
+  tasks.ts               background task registry + SSE task frames
+  gitignore.ts           .gitignore predicate for surfaced stray files
+  extract/               per-type extractors (thumbnails, fragments)
+  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
+  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/yamlover.js

@@ -48,6 +48,20 @@ let port = 5173;
 let host = "127.0.0.1";
 let gitignore = true; // hide .gitignore'd stray files by default
 let prodFlag = false; // force production (static) mode even in the repo checkout
+// URL prefix to serve the whole app under (e.g. `/demo/abc123`), so many instances can sit behind
+// one host on distinct paths (the demo server). "" = served at the document root (the normal case).
+// 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 ?? "";
+// Normalize a base path: leading `/`, no trailing `/`; `""`/`"/"` → disabled.
+function normBase(s) {
+  let b = (s ?? "").trim();
+  if (b === "" || b === "/") return "";
+  if (!b.startsWith("/")) b = "/" + b;
+  if (b.endsWith("/")) b = b.slice(0, -1);
+  return b;
+}
+basePath = normBase(basePath); // normalize the $BASE_PATH seed (a flag below re-normalizes its own value)
 const argv = process.argv.slice(2);
 for (let i = 0; i < argv.length; i++) {
   const a = argv[i];
@@ -56,11 +70,14 @@ for (let i = 0; i < argv.length; i++) {
   else if (a === "--headless") host = "0.0.0.0"; // serve on all interfaces (no GUI / remote access)
   else if (a === "--host") host = argv[++i];
   else if (a.startsWith("--host=")) host = a.slice("--host=".length);
+  else if (a === "--base-path") basePath = normBase(argv[++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 === "--help" || a === "-h") {
-    console.log("usage: npx yamlover [ROOT] [--port N] [--headless] [--host ADDR] [--no-gitignore] [--prod]");
+    console.log("usage: npx yamlover [ROOT] [--port N] [--headless] [--host ADDR] [--base-path PREFIX] [--no-gitignore] [--prod]");
     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 /");
     process.exit(0);
   } else if (!a.startsWith("-")) rootArg = a;
 }
@@ -85,7 +102,21 @@ let handle;
 let serveClient;
 
 const server = createHttpServer((req, res) => {
-  const url = new URL(req.url, "http://localhost");
+  let url = new URL(req.url, "http://localhost");
+  // Under `--base-path`, strip the prefix up front (and rewrite req.url) so every downstream —
+  // the engine API (exact `/api/...` matches), the static server, and the Vite middleware — sees
+  // root-relative paths and stays oblivious to the prefix. Anything outside the prefix is 404.
+  if (basePath) {
+    const p = url.pathname;
+    if (p === basePath || p.startsWith(basePath + "/")) {
+      req.url = (p.slice(basePath.length) || "/") + url.search;
+      url = new URL(req.url, "http://localhost");
+    } else {
+      res.statusCode = 404;
+      res.end("not found");
+      return;
+    }
+  }
   if (url.pathname.startsWith("/api/")) {
     handle(req, res, url);
     return;
@@ -193,6 +224,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)
         res.setHeader("Content-Type", "text/html; charset=utf-8");
         res.end(html);
       } catch (e) {
@@ -210,6 +242,7 @@ if (prod) {
 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)
   log: (line) => console.log(`yamlover  ${line}`),
 });
 handle.ready.catch((e) => console.error("yamlover: indexing failed:", e));
@@ -262,9 +295,25 @@ 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);
 }
 
+/** 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>`;
+  return html.includes("<head>") ? html.replace("<head>", `<head>${tag}`) : tag + html;
+}
+
 // Listen on `port`; if it is already in use, fall back to the next port (up to
 // `MAX_PORT_TRIES`), so two instances — or a leftover one — don't collide.
 const shown = host === "0.0.0.0" || host === "::" ? "localhost" : host;