docs: Document the dependency special cases in the ui README

mermaid, pagefind, @asciidoctor/tabs, highlight.js, fontawesome and
fontsource each get consumed in a non-obvious way; the README now says
how and why, plus how the asset hashing works.

Author: lfrancke

ui/README.adoc

@@ -60,6 +60,19 @@ Inside the `src` directory are:
 
 The js entries are `js/site.js` (the numbered scripts under `src/js`, concatenated in order) and one `js/vendor/<name>.js` per `src/js/vendor/<name>.bundle.js` with its imports bundled in.
 
+=== Dependency special cases
+
+* `mermaid`: ships its own prebuilt es-module dist and breaks at runtime when re-bundled; the build copies the entry and its transitive chunk imports verbatim and loads it on demand (see `partials/mermaid-script.hbs`).
+* `pagefind`: lives entirely outside this UI bundle. It is a devDependency of the repository root, indexes the finished site after the Antora build (`make build-search-index`) and self-serves its assets under `/pagefind/`. The asset hashing below does not cover it.
+* `@asciidoctor/tabs`: doubles as a build-time Asciidoctor extension (playbook) and a runtime asset. The browser js and the css are imported by explicit path (`dist/js/tabs.js`, `dist/css/tabs.css`) because Vite honors neither the `browser` nor the `style` package field.
+* `highlight.js`: bundled from its modular source with a curated language list in `src/js/vendor/highlight.bundle.js`.
+* `@fortawesome/fontawesome-free`: the icon sprite `img/icons.svg` is generated at build time from the package's svgs (CC BY 4.0, attributed in NOTICE and in the sprite itself).
+* `@fontsource/*`: the font files are pulled out of the packages via the `~@fontsource/` url alias in `src/css/fonts.css`.
+
+=== Asset caching
+
+The css and js entry files carry a content hash in their names and are served with immutable cache headers (see `netlify.toml`). The hbs templates reference them by their unhashed names; the build rewrites the references while staging the bundle. Fonts and images keep stable names with moderate cache lifetimes.
+
 === Building the final documentation
 
 The build is wired into the Playbooks of this repository: