From cacb76e7768f23348341c1e0b9113652203f2e2a Mon Sep 17 00:00:00 2001
From: Kuba Sunderland-Ober <kuba@mareimbrium.org>
Date: Tue, 2 Jun 2026 23:21:36 +0200
Subject: [PATCH 1/5] Rename the build & deploy workflow to tbdocs-gh-pages.

---
 .github/workflows/{jekyll-gh-pages.yml => tbdocs-gh-pages.yml} | 0
 1 file changed, 0 insertions(+), 0 deletions(-)
 rename .github/workflows/{jekyll-gh-pages.yml => tbdocs-gh-pages.yml} (100%)

diff --git a/.github/workflows/jekyll-gh-pages.yml b/.github/workflows/tbdocs-gh-pages.yml
similarity index 100%
rename from .github/workflows/jekyll-gh-pages.yml
rename to .github/workflows/tbdocs-gh-pages.yml

From 2277dc808bc525ed1ecdd098db77e4884c47cc92 Mon Sep 17 00:00:00 2001
From: Kuba Sunderland-Ober <kuba@mareimbrium.org>
Date: Tue, 2 Jun 2026 23:57:39 +0200
Subject: [PATCH 2/5] Plan phase 13: Inline SVG embedding.

---
 builder/PLAN-13.md | 486 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 486 insertions(+)
 create mode 100644 builder/PLAN-13.md

diff --git a/builder/PLAN-13.md b/builder/PLAN-13.md
new file mode 100644
index 00000000..fe849663
--- /dev/null
+++ b/builder/PLAN-13.md
@@ -0,0 +1,486 @@
+## PLAN-13: Phase 13 --- Inline SVG embedding with zoom / export controls
+
+Replaces `<img src="...svg">` rendering with build-time SVG inlining,
+and unifies the gantt-chart injection with the same pipeline.  Every
+`.svg` image referenced from markdown (including `.dot`-generated
+diagrams) is read from disk at render time, embedded directly in the
+page HTML, and wrapped in a controls bar (Download SVG, Copy SVG,
+Download PNG, Copy PNG) with a click-to-zoom fullscreen overlay.
+
+The gantt chart on the BuildInfo page flows through the same
+markdown-it plugin as every other SVG.  Because the gantt's timing
+data is not available until after the build completes, the plugin
+inlines a committed placeholder SVG; a minimal post-build step
+substitutes the real content into the already-written HTML.  The
+wrapper markup, controls, zoom wiring, and JS are identical ---
+the only difference is *when* the SVG content arrives.
+
+What Phase 13 does NOT do:
+
+- Add dark-mode colour support for Graphviz `.dot` diagrams.  The
+  gantt SVG already carries `html.dark-mode` CSS rules that work
+  because it is inline; the `.dot` SVGs generated by
+  `@hpcc-js/wasm-graphviz` do not.  Adding dark-mode classes to
+  `.dot` source files is a separate concern.
+- Change the existing `.dot` → `.svg` regeneration pipeline
+  (`dot.mjs`).  Diagrams are still rendered from `.dot` source by
+  WASM Graphviz; this plan only changes how the resulting `.svg`
+  files are embedded in pages.
+- Touch the offline or PDF build passes.  Inline SVGs are already
+  part of the page HTML by the time those passes run; no
+  rewriting is needed.
+- Add new npm dependencies.
+
+Target wall-clock impact: negligible.  The three `.dot` SVGs
+total ~30 KB; reading them adds < 1 ms to the dispatch task.  The
+per-page render cost is unchanged (string concatenation vs.
+`<img>` tag emission).
+
+---
+
+## 1. Current state
+
+SVG images in markdown (`![alt](/assets/images/dot/foo.svg)`) render
+as `<img src="/tB/assets/images/dot/foo.svg">`.  The browser makes a
+separate HTTP request per SVG.  Page CSS cannot reach the SVG
+internals (dark-mode styling, link colours, etc.).  No zoom or
+download controls exist.
+
+The gantt chart on the BuildInfo page has a separate code path:
+`injectGanttChart()` in `tbdocs.mjs` (lines 756--816) runs after
+the build completes and patches the written HTML, injecting the
+inline SVG, four control links, a PNG-export function, and a
+click-to-zoom script.  This is ~60 lines of self-contained HTML /
+JS generation that duplicates the pattern every future SVG would need.
+
+---
+
+## 2. Architecture
+
+### 2.1. Data flow: SVG contents through the pipeline
+
+```
+  dot.mjs (seed)                       dispatch (main thread)
+  ┌─────────────────┐                  ┌──────────────────────────┐
+  │ .dot → .svg     │──staticFiles──▸  │ reads .svg file contents │
+  │ regeneration    │                  │ into svgContentsMap      │
+  └─────────────────┘                  │ packs into sharedSAB    │
+                                       └────────────┬─────────────┘
+  docs/assets/images/gantt.svg                      │
+  (committed placeholder)                           │
+  ───── also in staticFiles ────────────────────────┘
+                                                    │
+                              ┌──────────────────────┘
+                              ▼
+              ┌──────────────────────────────────┐
+              │  cpu-worker renderEnvInit         │
+              │  unpackShared → svgContentsMap    │
+              │  createMarkdownIt({ ...,          │
+              │    svgContents })                 │
+              └──────────────┬───────────────────┘
+                             ▼
+              ┌──────────────────────────────────┐
+              │  svgInlinePlugin (image renderer) │
+              │  • src ends in .svg?              │
+              │  • content in ctx.svgContents?    │
+              │  → emit wrapper + inline SVG      │
+              │  → set page.hasSvg = true         │
+              └──────────────┬───────────────────┘
+                             ▼
+              ┌──────────────────────────────────┐
+              │  templatePhase / renderHead       │
+              │  page.hasSvg → include            │
+              │  svg-inline.js <script> tag       │
+              └──────────────────────────────────┘
+```
+
+### 2.2. Gantt placeholder lifecycle
+
+1. `docs/assets/images/gantt.svg` is a committed, minimal SVG
+   placeholder (a few bytes; empty `<svg>` with a `viewBox`).
+2. `discover` finds it; `dot.submit` or the static-file list
+   includes it.  `dispatch.execute` reads its content along with
+   every other `.svg`.
+3. The plugin inlines the placeholder into BuildInfo's
+   `renderedContent` --- identical wrapper markup to every other
+   SVG.  The container carries
+   `data-svg-src="assets/images/gantt.svg"`.
+4. `templatePhase` wraps it in the full page HTML.  `writePhase`
+   writes it to `_site/` (and `_site-offline/`).
+5. After the build completes, `injectGanttChart()` (now ~10 lines)
+   reads the BuildInfo HTML back, finds the container by its
+   `data-svg-src`, replaces the placeholder `<svg>…</svg>` with
+   the real gantt SVG, and writes the file back.  It also writes
+   the real gantt SVG to `_site/assets/images/gantt.svg` so a
+   direct-URL download works.
+
+### 2.3. Wrapper HTML shape (emitted by the plugin)
+
+The plugin emits this HTML for every inlined SVG:
+
+```html
+<div class="svg-inline-wrap">
+  <div class="svg-controls">
+    <a href="#" data-action="download-svg"
+       data-filename="<stem>">Download SVG</a>
+    <a href="#" data-action="copy-svg">Copy SVG</a>
+    <a href="#" data-action="download-png"
+       data-filename="<stem>">Download PNG</a>
+    <a href="#" data-action="copy-png"
+       data-filename="<stem>">Copy PNG</a>
+  </div>
+  <div class="svg-container" data-svg-src="<srcRel>"
+       role="img" aria-label="<alt>">
+    <svg …>…</svg>
+  </div>
+</div>
+```
+
+`<stem>` is the filename without extension (e.g. `scheduler-dag`).
+`<srcRel>` is the source-relative path (e.g.
+`assets/images/dot/scheduler-dag.svg`).  `<alt>` is the markdown
+alt text, used for accessibility (the `<svg>` element itself may
+or may not carry a `<title>`; the `aria-label` on the container
+is the reliable fallback).
+
+### 2.4. JS behaviour (`svg-inline.js`)
+
+A single event-delegation script loaded only on pages where
+`page.hasSvg` is true.  Four behaviours, all driven by class /
+data-attribute selectors:
+
+| Action | Trigger | Implementation |
+|--------|---------|----------------|
+| **Zoom** | Click on `.svg-container` (not on a control) | Toggle the container to `position:fixed` fullscreen overlay; match `body` background colour; Escape to close |
+| **Download SVG** | Click `[data-action="download-svg"]` | Serialize sibling `<svg>` via `XMLSerializer`, create Blob, trigger download |
+| **Copy SVG** | Click `[data-action="copy-svg"]` | `navigator.clipboard.writeText(svg.outerHTML)` |
+| **Download / Copy PNG** | Click `[data-action="download-png"]` or `[data-action="copy-png"]` | Serialize SVG → Blob → `<img>` → `<canvas>` at 2048 px wide → PNG blob → download or clipboard write |
+
+Print media: the script injects
+`@media print { .svg-controls { display:none } }` once on load.
+
+Total size: ~60 lines / ~2 KB uncompressed.  No cost on pages
+without SVGs (the `<script>` tag is not emitted).
+
+---
+
+## 3. Module split
+
+```
+builder/
+  render.mjs                +65 / -0 net. svgInlinePlugin function
+                             (~40 lines) + buildSvgWrapper helper
+                             (~25 lines). Registered last in
+                             createMarkdownIt's plugin chain (after
+                             relativeLinksPlugin, which rewrites the
+                             src URL before the image renderer fires).
+
+  template.mjs              +4 / -0. In renderHead, after the
+                             just-the-docs.js <script> line,
+                             conditionally emit a <script defer> for
+                             svg-inline.js when page.hasSvg is true.
+
+  tbdocs.mjs                +15 / -55 net. dispatch.execute reads
+                             .svg staticFiles into svgContentsMap
+                             and packs it into the shared SAB.
+                             injectGanttChart collapses from ~60
+                             lines to ~15 (find container by
+                             data-svg-src, replace <svg> content,
+                             write gantt.svg to _site/).
+
+  cpu-worker.mjs            +3 / -1. renderEnvInit unpacks
+                             svgContentsMap from sharedSAB and passes
+                             it to createMarkdownIt.
+
+  sab-broadcast.mjs          0 / 0. No changes; packShared /
+                             unpackShared are generic JSON.
+
+docs/
+  assets/images/gantt.svg   NEW. Committed placeholder (~100 bytes).
+                             Never updated by the build; the real
+                             gantt is injected into _site/ only.
+
+  assets/js/svg-inline.js   NEW. ~60 lines. Zoom, download, copy
+                             behaviours via event delegation.
+
+  Documentation/
+    BuildInfo.md            +1 / -1. Replace <!-- gantt-chart -->
+                             with ![Build task timeline](/assets/
+                             images/gantt.svg).
+```
+
+Estimated total churn: ~90 lines added, ~55 removed, plus the
+two new files (~160 lines combined).
+
+---
+
+## 4. Implementation order
+
+Three batches; each independently committable and verifiable.
+Batch 2 depends on batch 1; batch 3 depends on batch 2.
+
+| Batch | Substeps | Suggested model | Verifies by |
+|---|---|---|---|
+| 1 | [§5.1](#51-svg-inline-plugin-in-rendermjs) + [§5.2](#52-svg-contents-in-the-shared-sab) + [§5.3](#53-conditional-script-in-templatemjs) --- the plugin, the data plumbing, and the conditional script tag.  Regular `.dot` SVGs are now inlined. | **Opus** | `build.bat && check.bat` clean; inspect `_site/Documentation/Development/Builder/index.html` to confirm the three `.dot` SVGs appear as inline `<svg>` wrapped in `.svg-inline-wrap`, not as `<img>` tags; the `<script src="svg-inline.js">` tag is present in that page's `<head>` and absent in a page with no SVGs (e.g. `_site/tB/Core/Dim/index.html`). |
+| 2 | [§5.4](#54-svg-inlinejs) --- the JS file with zoom / download / copy behaviours. | **Sonnet** | Manual: open the Builder page in a browser; click a diagram to enter fullscreen zoom; press Escape to close; click each of the four control links and verify the download / clipboard result. |
+| 3 | [§5.5](#55-gantt-unification) + [§5.6](#56-buildinfmd-update) --- committed placeholder, simplified gantt injection, BuildInfo.md change. | **Sonnet** | `build.bat && check.bat` clean; the BuildInfo page shows the gantt chart with the same zoom + controls as the `.dot` diagrams; the old `<!-- gantt-chart -->` comment is gone; `injectGanttChart` is < 20 lines. |
+
+### 4.1. Model-selection rationale
+
+- **Opus (batch 1)**: the core architectural work.  The plugin
+  must correctly override the image renderer without breaking
+  non-SVG images, handle the URL-to-srcRel mapping across
+  baseurl configurations, set the page flag at the right time,
+  and the SAB plumbing must survive the structured-clone
+  serialisation.
+- **Sonnet (batches 2, 3)**: batch 2 is a self-contained JS file
+  with no interaction with the build pipeline; batch 3 is a
+  mechanical simplification of existing code plus a one-line
+  markdown change.
+
+---
+
+## 5. Per-substep specifications
+
+### 5.1. SVG inline plugin in `render.mjs`
+
+**Location**: new function `svgInlinePlugin(md, ctx)`, registered
+in `createMarkdownIt` as the last `md.use(...)` call (after
+`flattenAdjacentStrongPlugin`).
+
+**Mechanism**: overrides `md.renderer.rules.image`.
+
+```js
+function svgInlinePlugin(md, ctx) {
+  const orig = md.renderer.rules.image;
+
+  md.renderer.rules.image = (tokens, idx, options, env, self) => {
+    const token = tokens[idx];
+    const srcIdx = token.attrIndex("src");
+    if (srcIdx < 0) return fallback();
+    const src = token.attrs[srcIdx][1];
+    if (!src.endsWith(".svg")) return fallback();
+
+    // Map the rewritten URL back to srcRel.
+    // relativeLinksPlugin has already resolved the URL to
+    // e.g. "/tB/assets/images/dot/scheduler-dag.svg".
+    const prefix = (ctx.baseurl || "") + "/";
+    if (!src.startsWith(prefix)) return fallback();
+    const srcRel = src.slice(prefix.length);
+
+    const svgContent = ctx.svgContents?.get(srcRel);
+    if (!svgContent) return fallback();
+
+    // Extract alt text (same as default image renderer).
+    const alt = self.renderInlineAsText(
+      token.children, options, env);
+    const stem = srcRel.split("/").pop().replace(/\.svg$/, "");
+
+    if (env?.page) env.page.hasSvg = true;
+
+    return buildSvgWrapper(svgContent, alt, stem, srcRel);
+
+    function fallback() {
+      if (orig) return orig(tokens, idx, options, env, self);
+      // markdown-it default image rule
+      token.attrs[token.attrIndex("alt")][1] =
+        self.renderInlineAsText(token.children, options, env);
+      return self.renderToken(tokens, idx, options);
+    }
+  };
+}
+```
+
+**`buildSvgWrapper(svgContent, alt, stem, srcRel)`** returns the
+HTML string from [§2.3](#23-wrapper-html-shape-emitted-by-the-plugin).
+The controls use `data-action` / `data-filename` attributes; no
+inline event handlers.
+
+The function escapes `alt` and `srcRel` for attribute context
+(double-quote safe).
+
+### 5.2. SVG contents in the shared SAB
+
+**Read**: in `dispatch.execute()`, after the `const shared = {`
+block.  Read every `.svg` entry in `state.staticFiles` from disk:
+
+```js
+const svgContentsMap = Object.create(null);
+for (const f of state.staticFiles) {
+  if (f.srcRel.endsWith(".svg") && f.srcPath) {
+    try {
+      svgContentsMap[f.srcRel] = await fs.readFile(f.srcPath, "utf8");
+    } catch {}
+  }
+}
+```
+
+Add `svgContentsMap` to the `shared` object.  `packShared`
+serialises it into the SAB alongside `staticFilesArr`, etc.
+
+`dispatch.execute` is currently synchronous (no `async`).
+Adding the `fs.readFile` calls makes it `async execute(...)`.
+The scheduler already supports async execute functions; no
+framework change needed.
+
+**Unpack**: in `cpu-worker.mjs` `renderEnvInit()`:
+
+```js
+const { ..., svgContentsMap } = unpackShared(_sharedSAB);
+// ...
+const svgContents = new Map(Object.entries(svgContentsMap ?? {}));
+const markdown = createMarkdownIt({
+  highlighter, linkTables, baseurl, staticFiles, svgContents,
+});
+```
+
+**Main-thread markdown-it** (`markdownInit` task): this instance is
+used only for SEO title rendering and does not render page bodies.
+No SVG contents needed; pass `svgContents: new Map()` (or omit).
+
+### 5.3. Conditional script in `template.mjs`
+
+In `renderHead`, after the `just-the-docs.js` `<script>` line
+(line 130), add:
+
+```js
+(page.hasSvg
+  ? `  <script src="${escAttr(relativeUrl(
+      "/assets/js/svg-inline.js", bu))}" defer></script>\n`
+  : "")
+```
+
+`defer` keeps the load non-blocking, same as `theme-switch.js`.
+
+### 5.4. `svg-inline.js`
+
+New file at `docs/assets/js/svg-inline.js`.  ~60 lines, no
+dependencies, IIFE.
+
+Behaviours:
+
+1. **Print-hide CSS injection**.  On load, inject a `<style>` with
+   `@media print { .svg-controls { display:none } }` and the
+   base `.svg-controls a` float styling.
+
+2. **Zoom toggle**.  `document.addEventListener("click", ...)`,
+   delegated to `.svg-container`.  If the click target is inside
+   `.svg-controls`, ignore (let the control handler run).
+   Otherwise toggle the container between normal flow and
+   `position:fixed; inset:0; z-index:9999; background:<body bg>;
+   overflow:auto`.  Set `cursor:zoom-in` / `zoom-out`.  Track
+   state via `dataset.zoomed`.  Escape keydown closes the zoom
+   (with `{capture:true}` so it fires before other handlers).
+
+3. **Control actions**.  `document.addEventListener("click", ...)`,
+   delegated to `.svg-controls a[data-action]`.  `preventDefault`.
+   Navigate from the clicked link to the sibling
+   `.svg-container > svg`.
+
+   - `download-svg`: `new XMLSerializer().serializeToString(svg)`
+     → Blob → object URL → programmatic `<a>` click.
+   - `copy-svg`: `navigator.clipboard.writeText(svg.outerHTML)`.
+   - `download-png` / `copy-png`: serialize SVG → Blob →
+     `<img>.onload` → `<canvas>` at 2048 px wide (aspect from
+     `viewBox`) → `canvas.toBlob("image/png")` → download or
+     `navigator.clipboard.write([new ClipboardItem(...)])`.
+
+   `data-filename` on the link provides the download stem
+   (`<stem>.svg`, `<stem>.png`).
+
+### 5.5. Gantt unification
+
+**Committed placeholder** (`docs/assets/images/gantt.svg`):
+
+```xml
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 900 1">
+  <title>Build task timeline</title>
+</svg>
+```
+
+Minimal; the real content replaces it in `_site/` at the end of
+every build.
+
+**Simplified `injectGanttChart(pages, destRoot, svgContent)`**:
+
+Collapses to ~15 lines.  For each output tree (`destRoot`,
+`destRoot-offline`):
+
+1. Read the BuildInfo HTML from disk.
+2. Find the `data-svg-src="assets/images/gantt.svg"` container.
+   Extract the range from the first `<svg` after that marker to
+   its closing `</svg>`.
+3. Replace that range with `svgContent`.
+4. Write the patched HTML back.
+5. Write `svgContent` to `<root>/assets/images/gantt.svg` so a
+   direct-URL download of the file works.
+
+No controls, no scripts, no zoom wiring --- the plugin already
+emitted all of that around the placeholder.
+
+### 5.6. `BuildInfo.md` update
+
+Replace:
+
+```markdown
+<!-- gantt-chart -->
+```
+
+With:
+
+```markdown
+![Build task timeline](/assets/images/gantt.svg)
+```
+
+The plugin inlines the placeholder SVG and emits the full wrapper.
+The post-build step fills in the real content.
+
+---
+
+## 6. Edge cases
+
+### 6.1. First build on a clean checkout
+
+`docs/assets/images/gantt.svg` is the committed placeholder.  The
+plugin inlines it --- the BuildInfo page renders with an empty
+gantt area and working controls.  After the build completes, the
+post-build step fills in the real gantt.  On the NEXT page load
+(or if the user refreshes), the real gantt is visible.
+
+### 6.2. Missing SVG file
+
+If an `![...](....svg)` references a file not in `staticFiles`
+(e.g. a typo), the plugin falls through to the default `<img>`
+renderer.  The link checker (`check.bat`) catches the broken
+image reference as it does today.
+
+### 6.3. Non-local SVG URLs
+
+Absolute URLs (`https://...svg`), protocol-relative URLs
+(`//...svg`), and fragment-only references (`#...`) bypass the
+plugin entirely (the `src.startsWith(prefix)` guard rejects them).
+Only build-local SVGs with content in the `svgContents` map are
+inlined.
+
+### 6.4. Serve mode
+
+No special handling needed.  The watcher already ignores
+`assets/images/dot/*.svg` writes.  The gantt placeholder at
+`docs/assets/images/gantt.svg` is never written during the build
+(only `_site/` is touched).  Each serve rebuild reads the
+placeholder, inlines it, and the post-build step injects the real
+gantt into `_site/`.
+
+### 6.5. SVG size in the shared SAB
+
+The three `.dot` SVGs and the gantt placeholder total ~30 KB.  The
+existing shared SAB carries ~600 KB of serialised data
+(`linkTablesData` + `staticFilesArr` + `sitePathsArr`).  The SVG
+contents add ~5 % overhead --- negligible.
+
+### 6.6. Accessibility
+
+The `<img alt="...">` tag is replaced by a `<div ... role="img"
+aria-label="...">` on the container.  Screen readers announce the
+alt text; the `<svg>` element's internal `<title>` (if present)
+provides a secondary label.

From 4e5f4843a432164824266f8143ddcfbe8e99fd52 Mon Sep 17 00:00:00 2001
From: Kuba Sunderland-Ober <kuba@mareimbrium.org>
Date: Wed, 3 Jun 2026 00:11:47 +0200
Subject: [PATCH 3/5] Implement phase 13: inline SVG embedding with zoom/export
 controls.

---
 builder/PLAN-13.md                            | 27 ++++--
 builder/cpu-worker.mjs                        |  5 +-
 builder/render.mjs                            | 51 +++++++++++
 builder/tbdocs.mjs                            | 69 ++++----------
 builder/template.mjs                          |  1 +
 docs/Documentation/BuildInfo.md               |  2 +-
 .../assets/images/dot/pdf-render-pipeline.dot |  3 +-
 .../assets/images/dot/pdf-render-pipeline.svg |  6 +-
 docs/assets/images/gantt.svg                  |  3 +
 docs/assets/js/svg-inline.js                  | 90 +++++++++++++++++++
 10 files changed, 193 insertions(+), 64 deletions(-)
 create mode 100644 docs/assets/images/gantt.svg
 create mode 100644 docs/assets/js/svg-inline.js

diff --git a/builder/PLAN-13.md b/builder/PLAN-13.md
index fe849663..4190530c 100644
--- a/builder/PLAN-13.md
+++ b/builder/PLAN-13.md
@@ -25,7 +25,12 @@ What Phase 13 does NOT do:
 - Change the existing `.dot` → `.svg` regeneration pipeline
   (`dot.mjs`).  Diagrams are still rendered from `.dot` source by
   WASM Graphviz; this plan only changes how the resulting `.svg`
-  files are embedded in pages.
+  files are embedded in pages.  (One `.dot` source fix WAS needed:
+  `pdf-render-pipeline.dot` had `margin=12` in its `graph [...]`
+  defaults block, which Graphviz interprets as 12 *inches* on the
+  root graph --- producing a 2239×2406 pt SVG with 864 pt of dead
+  space.  Moved the `margin=12` to each `subgraph cluster_*` where
+  it means 12 *points* of intra-cluster padding.)
 - Touch the offline or PDF build passes.  Inline SVGs are already
   part of the page HTML by the time those passes run; no
   rewriting is needed.
@@ -159,7 +164,11 @@ data-attribute selectors:
 Print media: the script injects
 `@media print { .svg-controls { display:none } }` once on load.
 
-Total size: ~60 lines / ~2 KB uncompressed.  No cost on pages
+Sizing: the script also injects
+`.svg-container svg { width: 100%; height: auto }` so every
+inlined SVG fills the column width and scales proportionally.
+
+Total size: ~80 lines / ~2.5 KB uncompressed.  No cost on pages
 without SVGs (the `<script>` tag is not emitted).
 
 ---
@@ -354,14 +363,16 @@ In `renderHead`, after the `just-the-docs.js` `<script>` line
 
 ### 5.4. `svg-inline.js`
 
-New file at `docs/assets/js/svg-inline.js`.  ~60 lines, no
+New file at `docs/assets/js/svg-inline.js`.  ~80 lines, no
 dependencies, IIFE.
 
 Behaviours:
 
-1. **Print-hide CSS injection**.  On load, inject a `<style>` with
-   `@media print { .svg-controls { display:none } }` and the
-   base `.svg-controls a` float styling.
+1. **CSS injection**.  On load, inject a `<style>` with
+   `@media print { .svg-controls { display:none } }`, the
+   base `.svg-controls a` float styling, and
+   `.svg-container svg { width:100%; height:auto }` so
+   every inlined SVG fills the column width.
 
 2. **Zoom toggle**.  `document.addEventListener("click", ...)`,
    delegated to `.svg-container`.  If the click target is inside
@@ -403,7 +414,9 @@ every build.
 
 **Simplified `injectGanttChart(pages, destRoot, svgContent)`**:
 
-Collapses to ~15 lines.  For each output tree (`destRoot`,
+Collapses to ~15 lines.  No `baseurl` parameter --- static files
+live directly under the output root (`_site/assets/...`), not
+under the baseurl prefix.  For each output tree (`destRoot`,
 `destRoot-offline`):
 
 1. Read the BuildInfo HTML from disk.
diff --git a/builder/cpu-worker.mjs b/builder/cpu-worker.mjs
index f0e5c4a3..163b9c47 100644
--- a/builder/cpu-worker.mjs
+++ b/builder/cpu-worker.mjs
@@ -56,13 +56,14 @@ const handlers = {
 
     const { siteData, initData, linkTablesData, staticFilesArr,
             baseurl, buildInfo, sitePathsArr,
-            skipOffline } = unpackShared(_sharedSAB);
+            skipOffline, svgContentsMap } = unpackShared(_sharedSAB);
 
     const { initHighlighter } = await import("./highlight.mjs");
     const highlighter = await initHighlighter();
     const linkTables  = reconstructLinkTables(linkTablesData);
     const staticFiles = new Set(staticFilesArr);
-    const markdown    = createMarkdownIt({ highlighter, linkTables, baseurl, staticFiles });
+    const svgContents = new Map(Object.entries(svgContentsMap ?? {}));
+    const markdown    = createMarkdownIt({ highlighter, linkTables, baseurl, staticFiles, svgContents });
     const site        = { ...siteData, markdown, buildInfo };
 
     let offlineBase = null;
diff --git a/builder/render.mjs b/builder/render.mjs
index a1bf4993..c606850b 100644
--- a/builder/render.mjs
+++ b/builder/render.mjs
@@ -323,6 +323,7 @@ export function createMarkdownIt(ctx) {
   md.use(kramdownDashesPlugin);
   md.use(kramdownEllipsisPlugin);
   md.use(flattenAdjacentStrongPlugin);
+  md.use(svgInlinePlugin, ctx);
 
   return md;
 }
@@ -1571,6 +1572,56 @@ function normaliseBlockHtml(content) {
 // <img ...>. kramdown wraps any such sequence in a single <p>.
 const STANDALONE_INLINE_HTML_RE = /^(?:<(br|hr|img)\b[^>]*\/?>\s*)+$/i;
 
+// ---------- SVG inline plugin -----------------------------------------------
+
+function svgInlinePlugin(md, ctx) {
+  const orig = md.renderer.rules.image;
+
+  md.renderer.rules.image = (tokens, idx, options, env, self) => {
+    const token = tokens[idx];
+    const srcIdx = token.attrIndex("src");
+    if (srcIdx < 0) return fallback();
+    const src = token.attrs[srcIdx][1];
+    if (!src.endsWith(".svg")) return fallback();
+
+    const prefix = (ctx.baseurl || "") + "/";
+    if (!src.startsWith(prefix)) return fallback();
+    const srcRel = src.slice(prefix.length);
+
+    const svgContent = ctx.svgContents?.get(srcRel);
+    if (!svgContent) return fallback();
+
+    const alt = self.renderInlineAsText(token.children, options, env);
+    const stem = srcRel.split("/").pop().replace(/\.svg$/, "");
+
+    if (env?.page) env.page.hasSvg = true;
+
+    return buildSvgWrapper(svgContent, alt, stem, srcRel);
+
+    function fallback() {
+      if (orig) return orig(tokens, idx, options, env, self);
+      token.attrs[token.attrIndex("alt")][1] =
+        self.renderInlineAsText(token.children, options, env);
+      return self.renderToken(tokens, idx, options);
+    }
+  };
+}
+
+function buildSvgWrapper(svgContent, alt, stem, srcRel) {
+  const esc = escapeHtml;
+  return `<div class="svg-inline-wrap">` +
+    `<div class="svg-controls">` +
+    `<a href="#" data-action="download-svg" data-filename="${esc(stem)}">Download SVG</a>` +
+    `<a href="#" data-action="copy-svg">Copy SVG</a>` +
+    `<a href="#" data-action="download-png" data-filename="${esc(stem)}">Download PNG</a>` +
+    `<a href="#" data-action="copy-png" data-filename="${esc(stem)}">Copy PNG</a>` +
+    `</div>` +
+    `<div class="svg-container" data-svg-src="${esc(srcRel)}" role="img" aria-label="${esc(alt)}">` +
+    svgContent +
+    `</div>` +
+    `</div>`;
+}
+
 // ---------- helpers ---------------------------------------------------------
 
 const HTML_ESCAPE = { "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" };
diff --git a/builder/tbdocs.mjs b/builder/tbdocs.mjs
index 5530308f..67e04bd1 100644
--- a/builder/tbdocs.mjs
+++ b/builder/tbdocs.mjs
@@ -470,7 +470,7 @@ const TASKS = {
   dispatch: {
     expected: ["nav", "buildInit", "buildInfo", "dot", "deriveRedirects", "markdownInit"],
     runOnMain: true,
-    execute({ nav: { sidebar }, buildInit: { initData }, buildInfo: { buildInfo }, dot: _dotSignal, markdownInit: _markdownInitSignal, deriveRedirects: { stubs } }, ctx, state) {
+    async execute({ nav: { sidebar }, buildInit: { initData }, buildInfo: { buildInfo }, dot: _dotSignal, markdownInit: _markdownInitSignal, deriveRedirects: { stubs } }, ctx, state) {
       void _dotSignal;   // dependency signal only -- static files already appended in dot.submit
       void _markdownInitSignal;  // dependency signal only -- markdown + linkTablesSerialized + seoSiteTitle/seoLogoUrl already on state.site
       const chunks = chunkPages(state.pages, ctx.workerCount);
@@ -485,6 +485,14 @@ const TASKS = {
       const sitePaths = buildSitePathsSync(state.pages, state.staticFiles, excludePatterns, stubs, themeAssetRels);
       state.sitePaths = sitePaths;
       const skipOffline = ctx.opts.skipOffline ?? (state.site.config.also_build_offline === false);
+      const svgContentsMap = Object.create(null);
+      for (const f of state.staticFiles) {
+        if (f.srcRel.endsWith(".svg")) {
+          try {
+            svgContentsMap[f.srcRel] = await fs.readFile(path.join(ctx.srcRoot, f.srcRel), "utf8");
+          } catch {}
+        }
+      }
       const shared = {
         siteData: {
           config:       state.site.config,
@@ -499,6 +507,7 @@ const TASKS = {
         sitePathsArr:           [...sitePaths],
         offlineExcludePatterns: excludePatterns,
         skipOffline,
+        svgContentsMap,
       };
       const sharedSAB = packShared(shared);
       return { chunks, sharedSAB };
@@ -763,55 +772,15 @@ async function injectGanttChart(pages, destRoot, svgContent) {
     let html;
     try { html = await fs.readFile(htmlPath, "utf8"); }
     catch (e) { if (e.code !== "ENOENT") throw e; continue; }
-    const dataUrl = `data:image/svg+xml;charset=utf-8,${encodeURIComponent(svgContent)}`;
-    const ls = `font-size:0.85em;float:right;margin-left:1em`;
-    const downloadLink = `<a href="${dataUrl}" download="gantt.svg" style="${ls}">Download SVG</a>`;
-    const copyLink = `<a href="javascript:;" onclick="navigator.clipboard.writeText(document.querySelector('#gantt-chart>svg').outerHTML)" style="${ls}">Copy SVG</a>`;
-    const downloadPng = `<a href="javascript:;" onclick="_ganttPng(1)" style="${ls}">Download PNG</a>`;
-    const copyPng = `<a href="javascript:;" onclick="_ganttPng(0)" style="${ls}">Copy PNG</a>`;
-    const pngFn = [
-      `<script>function _ganttPng(dl){`,
-      `var svg=document.querySelector('#gantt-chart>svg');if(!svg)return;`,
-      `var vb=svg.viewBox.baseVal,w=2048,h=Math.round(vb.height*(w/vb.width));`,
-      `var data=new XMLSerializer().serializeToString(svg);`,
-      `var blob=new Blob([data],{type:'image/svg+xml;charset=utf-8'});`,
-      `var url=URL.createObjectURL(blob);var img=new Image();`,
-      `img.onload=function(){`,
-      `var c=document.createElement('canvas');c.width=w;c.height=h;`,
-      `var ctx=c.getContext('2d');`,
-      `ctx.drawImage(img,0,0,w,h);URL.revokeObjectURL(url);`,
-      `c.toBlob(function(b){`,
-      `if(dl){var a=document.createElement('a');a.href=URL.createObjectURL(b);`,
-      `a.download='gantt.png';a.click();URL.revokeObjectURL(a.href)}`,
-      `else{navigator.clipboard.write([new ClipboardItem({'image/png':b})])}`,
-      `},'image/png')};img.src=url}<` + `/script>`,
-    ].join("");
-    const header = `${pngFn}<style>@media print{#gantt-controls{display:none}}</style><div id="gantt-controls" style="overflow:hidden">${downloadLink}${copyLink}${downloadPng}${copyPng}</div>`;
-    const zoomScript = [
-      `<script>(function(){`,
-      `var c=document.getElementById('gantt-chart');`,
-      `if(!c)return;`,
-      `c.style.cursor='zoom-in';`,
-      `function toggle(){`,
-      `  var svg=c.querySelector('svg');`,
-      `  if(c.dataset.zoomed){`,
-      `    c.removeAttribute('style');c.style.cursor='zoom-in';`,
-      `    if(svg)svg.style.maxWidth='';`,
-      `    delete c.dataset.zoomed;`,
-      `  }else{`,
-      `    var bg=getComputedStyle(document.body).backgroundColor;`,
-      `    Object.assign(c.style,{position:'fixed',top:'0',left:'0',width:'100vw',height:'100vh',`,
-      `      zIndex:'9999',background:bg,padding:'1rem',boxSizing:'border-box',overflow:'auto',cursor:'zoom-out'});`,
-      `    if(svg)svg.style.maxWidth='100%';`,
-      `    c.dataset.zoomed='1';c.scrollTop=0;`,
-      `  }`,
-      `}`,
-      `c.addEventListener('click',toggle);`,
-      `document.addEventListener('keydown',function(e){if(e.key==='Escape'&&c.dataset.zoomed)toggle();},{capture:true});`,
-      `})();<` + `/script>`,
-    ].join("");
-    const patched = html.replace("<!-- gantt-chart -->", `${header}\n<div id="gantt-chart">${svgContent}</div>\n${zoomScript}`);
-    if (patched !== html) await fs.writeFile(htmlPath, patched, "utf8");
+    const marker = 'data-svg-src="assets/images/gantt.svg"';
+    const idx = html.indexOf(marker);
+    if (idx < 0) continue;
+    const svgStart = html.indexOf("<svg", idx);
+    const svgEnd = html.indexOf("</svg>", svgStart);
+    if (svgStart < 0 || svgEnd < 0) continue;
+    const patched = html.slice(0, svgStart) + svgContent + html.slice(svgEnd + 6);
+    await fs.writeFile(htmlPath, patched, "utf8");
+    await fs.writeFile(path.join(root, "assets", "images", "gantt.svg"), svgContent, "utf8");
   }
 }
 
diff --git a/builder/template.mjs b/builder/template.mjs
index 8a20debd..009c1d14 100644
--- a/builder/template.mjs
+++ b/builder/template.mjs
@@ -128,6 +128,7 @@ function renderHead(page, site, init) {
     (init.searchEnabled ? `  <script src="${escAttr(relativeUrl("/assets/js/vendor/lunr.min.js", bu))}"></script>\n` : "") +
     (bu ? `  <script>window.jtdBaseurl=${JSON.stringify(bu)};</script>\n` : "") +
     `  <script src="${escAttr(relativeUrl("/assets/js/just-the-docs.js", bu))}"></script>\n` +
+    (page.hasSvg ? `  <script src="${escAttr(relativeUrl("/assets/js/svg-inline.js", bu))}" defer></script>\n` : "") +
     `  <meta name="viewport" content="width=device-width, initial-scale=1">\n` +
     headSeoBlock(page, site) +
     init.faviconLink +
diff --git a/docs/Documentation/BuildInfo.md b/docs/Documentation/BuildInfo.md
index f1c4d185..982e7243 100644
--- a/docs/Documentation/BuildInfo.md
+++ b/docs/Documentation/BuildInfo.md
@@ -11,4 +11,4 @@ permalink: /Documentation/Development/BuildInfo
 
 Gantt chart of this build's task timeline.
 
-<!-- gantt-chart -->
+![Build task timeline](/assets/images/gantt.svg)
diff --git a/docs/assets/images/dot/pdf-render-pipeline.dot b/docs/assets/images/dot/pdf-render-pipeline.dot
index dc79c706..6af77624 100644
--- a/docs/assets/images/dot/pdf-render-pipeline.dot
+++ b/docs/assets/images/dot/pdf-render-pipeline.dot
@@ -26,10 +26,10 @@ digraph pdf_render {
         fontsize=13
         style="rounded"
         labeljust="l"
-        margin=12
     ]
 
     subgraph cluster_writePdf {
+        margin=12
         label="tbdocs writePdf (pdf.mjs + book.mjs)"
         ASM [label=<assembleBook()<BR/>combine chapter HTML>]
         CSS [label=<copyPdfCss()<BR/>print.css + tb-highlight.css>]
@@ -40,6 +40,7 @@ digraph pdf_render {
     PDFSRC [label=<_site-pdf/book.html<BR/>(~5 MB)<BR/>print.css, tb-highlight.css,<BR/>images>]
 
     subgraph cluster_render {
+        margin=12
         label="render-book.mjs"
         R1 [label=<Phase 1: Render<BR/>puppeteer<BR/>→ headless Chromium<BR/>paged.js<BR/>CSS Paged Media layout<BR/>→ one .pagedjs_page<BR/>per output page>]
         R2 [label=<Phase 2: Generate<BR/>extract metadata<BR/>+ outline tree<BR/>page.pdf() → raw PDF buffer>]
diff --git a/docs/assets/images/dot/pdf-render-pipeline.svg b/docs/assets/images/dot/pdf-render-pipeline.svg
index 270dc8eb..ed9cd551 100644
--- a/docs/assets/images/dot/pdf-render-pipeline.svg
+++ b/docs/assets/images/dot/pdf-render-pipeline.svg
@@ -4,9 +4,9 @@
 <!-- Generated by graphviz version 15.0.0 (0)
  -->
 <!-- Title: pdf_render Pages: 1 -->
-<svg width="2239pt" height="2406pt"
- viewBox="864.00 864.00 1375.00 1542.00" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
-<g id="graph0" class="graph" transform="scale(1 1) rotate(0) translate(868 1537.6)">
+<svg width="511pt" height="678pt"
+ viewBox="0.00 0.00 511.00 678.00" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+<g id="graph0" class="graph" transform="scale(1 1) rotate(0) translate(4 673.6)">
 <title>pdf_render</title>
 <g id="clust1" class="cluster">
 <title>cluster_writePdf</title>
diff --git a/docs/assets/images/gantt.svg b/docs/assets/images/gantt.svg
new file mode 100644
index 00000000..b758af92
--- /dev/null
+++ b/docs/assets/images/gantt.svg
@@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 900 1">
+  <title>Build task timeline</title>
+</svg>
diff --git a/docs/assets/js/svg-inline.js b/docs/assets/js/svg-inline.js
new file mode 100644
index 00000000..3121e088
--- /dev/null
+++ b/docs/assets/js/svg-inline.js
@@ -0,0 +1,90 @@
+(function () {
+  var style = document.createElement("style");
+  style.textContent =
+    "@media print { .svg-controls { display: none } }" +
+    ".svg-controls { overflow: hidden; font-size: 0.85em }" +
+    ".svg-controls a { float: right; margin-left: 1em }" +
+    ".svg-container svg { width: 100%; height: auto }";
+  document.head.appendChild(style);
+
+  document.addEventListener("click", function (e) {
+    var container = e.target.closest(".svg-container");
+    if (!container) return;
+    if (e.target.closest(".svg-controls")) return;
+    e.preventDefault();
+    var svg = container.querySelector("svg");
+    if (container.dataset.zoomed) {
+      container.removeAttribute("style");
+      container.style.cursor = "zoom-in";
+      if (svg) svg.style.maxWidth = "";
+      delete container.dataset.zoomed;
+    } else {
+      var bg = getComputedStyle(document.body).backgroundColor;
+      Object.assign(container.style, {
+        position: "fixed", top: "0", left: "0", width: "100vw", height: "100vh",
+        zIndex: "9999", background: bg, padding: "1rem", boxSizing: "border-box",
+        overflow: "auto", cursor: "zoom-out"
+      });
+      if (svg) svg.style.maxWidth = "100%";
+      container.dataset.zoomed = "1";
+      container.scrollTop = 0;
+    }
+  });
+
+  document.addEventListener("keydown", function (e) {
+    if (e.key !== "Escape") return;
+    var zoomed = document.querySelector(".svg-container[data-zoomed]");
+    if (!zoomed) return;
+    zoomed.removeAttribute("style");
+    zoomed.style.cursor = "zoom-in";
+    var svg = zoomed.querySelector("svg");
+    if (svg) svg.style.maxWidth = "";
+    delete zoomed.dataset.zoomed;
+  }, { capture: true });
+
+  document.addEventListener("click", function (e) {
+    var link = e.target.closest(".svg-controls a[data-action]");
+    if (!link) return;
+    e.preventDefault();
+    var wrap = link.closest(".svg-inline-wrap");
+    var svg = wrap && wrap.querySelector(".svg-container > svg");
+    if (!svg) return;
+    var action = link.dataset.action;
+    var filename = link.dataset.filename || "diagram";
+
+    if (action === "download-svg") {
+      triggerDownload(
+        new Blob([new XMLSerializer().serializeToString(svg)],
+          { type: "image/svg+xml;charset=utf-8" }),
+        filename + ".svg");
+    } else if (action === "copy-svg") {
+      navigator.clipboard.writeText(svg.outerHTML);
+    } else if (action === "download-png" || action === "copy-png") {
+      var data = new XMLSerializer().serializeToString(svg);
+      var blob = new Blob([data], { type: "image/svg+xml;charset=utf-8" });
+      var url = URL.createObjectURL(blob);
+      var img = new Image();
+      img.onload = function () {
+        var vb = svg.viewBox.baseVal;
+        var w = 2048, h = Math.round(vb.height * (w / vb.width));
+        var c = document.createElement("canvas");
+        c.width = w; c.height = h;
+        c.getContext("2d").drawImage(img, 0, 0, w, h);
+        URL.revokeObjectURL(url);
+        c.toBlob(function (b) {
+          if (action === "download-png") triggerDownload(b, filename + ".png");
+          else navigator.clipboard.write([new ClipboardItem({ "image/png": b })]);
+        }, "image/png");
+      };
+      img.src = url;
+    }
+  });
+
+  function triggerDownload(blob, name) {
+    var a = document.createElement("a");
+    a.href = URL.createObjectURL(blob);
+    a.download = name;
+    a.click();
+    URL.revokeObjectURL(a.href);
+  }
+})();

From 4b5f6d62e1f79318f2147196f755948f67768bea Mon Sep 17 00:00:00 2001
From: Kuba Sunderland-Ober <kuba@mareimbrium.org>
Date: Wed, 3 Jun 2026 00:47:42 +0200
Subject: [PATCH 4/5] Sort out styling for inline SVGs.

---
 docs/_sass/custom/custom.scss | 17 +++++++++++++++++
 docs/assets/css/print.css     |  7 +++++++
 docs/assets/js/svg-inline.js  |  8 --------
 3 files changed, 24 insertions(+), 8 deletions(-)

diff --git a/docs/_sass/custom/custom.scss b/docs/_sass/custom/custom.scss
index 352e21b4..984debdd 100644
--- a/docs/_sass/custom/custom.scss
+++ b/docs/_sass/custom/custom.scss
@@ -1,5 +1,22 @@
 @use "admonitions";
 
+// Inline SVG diagrams (Phase 13). Controls are float-right links above
+// the diagram; the SVG fills the column width.
+.svg-controls {
+  overflow: hidden;
+  font-size: 0.85em;
+
+  a {
+    float: right;
+    margin-left: 1em;
+  }
+}
+
+.svg-container svg {
+  width: 100%;
+  height: auto;
+}
+
 .site-logo {
   padding-right: 3rem;
 }
diff --git a/docs/assets/css/print.css b/docs/assets/css/print.css
index e8d39239..c3fa63b4 100644
--- a/docs/assets/css/print.css
+++ b/docs/assets/css/print.css
@@ -17,6 +17,13 @@
    book.html too. Hide it for the PDF render path. */
 button.copy-code { display: none; }
 
+/* SVG inline controls are interactive chrome (zoom, download, copy);
+   hide them in the PDF.  Constrain the SVG to the page width and
+   scale text down so diagram labels don't dominate the page. */
+.svg-controls { display: none; }
+.svg-container svg { max-width: 100%; height: auto; }
+.svg-container text { font-size: 75%; }
+
 
 @page {
   size: A4;
diff --git a/docs/assets/js/svg-inline.js b/docs/assets/js/svg-inline.js
index 3121e088..4455c12a 100644
--- a/docs/assets/js/svg-inline.js
+++ b/docs/assets/js/svg-inline.js
@@ -1,12 +1,4 @@
 (function () {
-  var style = document.createElement("style");
-  style.textContent =
-    "@media print { .svg-controls { display: none } }" +
-    ".svg-controls { overflow: hidden; font-size: 0.85em }" +
-    ".svg-controls a { float: right; margin-left: 1em }" +
-    ".svg-container svg { width: 100%; height: auto }";
-  document.head.appendChild(style);
-
   document.addEventListener("click", function (e) {
     var container = e.target.closest(".svg-container");
     if (!container) return;

From 5c1bdfd592c49157e08ffa5ea7200f581c2e6e19 Mon Sep 17 00:00:00 2001
From: Kuba Sunderland-Ober <kuba@mareimbrium.org>
Date: Wed, 3 Jun 2026 01:11:14 +0200
Subject: [PATCH 5/5] Document changes from phase 13.

---
 docs/Documentation/Builder.md         | 37 ++++++++++++++++++++++++---
 docs/Documentation/Building.md        |  4 ++-
 docs/Documentation/Pipeline-Stages.md |  5 +++-
 3 files changed, 41 insertions(+), 5 deletions(-)

diff --git a/docs/Documentation/Builder.md b/docs/Documentation/Builder.md
index 9401dca8..3c28c1eb 100644
--- a/docs/Documentation/Builder.md
+++ b/docs/Documentation/Builder.md
@@ -87,7 +87,7 @@ Modules grouped by role. Each entry has one line; deep-dive in [Pipeline Stages]
 
 | File | Role |
 |---|---|
-| [`render.mjs`](https://github.com/twinbasic/documentation/blob/main/builder/render.mjs) | markdown-it configuration + plugin stack + `renderPhase`. Built once on main and once per worker. |
+| [`render.mjs`](https://github.com/twinbasic/documentation/blob/main/builder/render.mjs) | markdown-it configuration + plugin stack (including `svgInlinePlugin` for build-time SVG embedding) + `renderPhase`. Built once on main and once per worker. |
 | [`highlight.mjs`](https://github.com/twinbasic/documentation/blob/main/builder/highlight.mjs) | Shiki bootstrap + the bundled twinBASIC grammar. Emits the just-the-docs wrapper structure. |
 | [`highlight-theme.mjs`](https://github.com/twinbasic/documentation/blob/main/builder/highlight-theme.mjs) | Loads `Light.theme` + `Dark.theme`, emits `tb-highlight.css` + scope-to-class lookup. |
 | [`template.mjs`](https://github.com/twinbasic/documentation/blob/main/builder/template.mjs) | `templatePhase` (per-page layout wrap) + `buildInitConfig` + `renderSidebar`. JS template literals; no template engine. |
@@ -333,11 +333,42 @@ Three flags on the pool make the reuse safe:
 
 `serve.mjs` writes to `docs/_serve/` --- disjoint from `build.bat`'s `_site/` family. A one-off `build.bat` run during a serve session never touches the tree the live preview is showing.
 
+## SVG inlining
+
+Markdown `![alt](/assets/images/foo.svg)` references to build-local SVGs are replaced at render time with the SVG content inlined directly in the HTML. The feature removes the browser round-trip for separate SVG files and adds interactive controls (zoom, download, clipboard copy) to every inlined diagram.
+
+The pipeline:
+
+1. **`dispatch.execute()`** reads every `.svg` static file into a `svgContentsMap` keyed by `srcRel`. The map is packed into the shared SAB and broadcast to every render worker.
+2. **`renderEnvInit`** on each worker unpacks `svgContentsMap` and passes it as `svgContents` to `createMarkdownIt`.
+3. **`svgInlinePlugin`** in `render.mjs` overrides the markdown-it image renderer. When the `src` ends in `.svg` and the file's content exists in `ctx.svgContents`, the plugin replaces the `<img>` tag with a wrapper structure containing the raw SVG, four control links (Download SVG, Copy SVG, Download PNG, Copy PNG), and a click-to-zoom container. The plugin also sets `page.hasSvg = true`.
+4. **`templatePhase`** conditionally includes `<script defer src="/assets/js/svg-inline.js">` on pages where `page.hasSvg` is true.
+
+The wrapper HTML emitted by `buildSvgWrapper`:
+
+```html
+<div class="svg-inline-wrap">
+  <div class="svg-controls">
+    <a href="#" data-action="download-svg" data-filename="...">Download SVG</a>
+    <a href="#" data-action="copy-svg">Copy SVG</a>
+    <a href="#" data-action="download-png" data-filename="...">Download PNG</a>
+    <a href="#" data-action="copy-png" data-filename="...">Copy PNG</a>
+  </div>
+  <div class="svg-container" data-svg-src="..." role="img" aria-label="...">
+    <svg>...</svg>
+  </div>
+</div>
+```
+
+`svg-inline.js` (~80 lines, no dependencies) handles four client-side behaviours: click-to-zoom (fullscreen overlay, Escape to close), SVG download (serialises the `<svg>` to XML), SVG clipboard copy, and PNG export (renders the SVG to a 2048 px-wide canvas via `Image` + `toBlob`). The controls are hidden in print CSS.
+
+Only SVGs whose content is present in `svgContents` are inlined; external URLs and missing files fall through to the default `<img>` renderer. The main-thread markdown-it instance (used only for site-level SEO) passes an empty map --- no SVG content needed there.
+
 ## Gantt chart and build introspection
 
 Every build emits an inline-SVG Gantt chart of its task timeline. [`gantt.mjs`](https://github.com/twinbasic/documentation/blob/main/builder/gantt.mjs)'s `renderGantt(grouped)` takes the `Map<section, taskTiming[]>` the scheduler accumulates and renders one SVG row per main-thread task plus one row per worker lane. Workers appear as a single row each with multiple coloured rectangles (one per task they ran, in completion order); the colour encodes the originating section. Boot timings (cold start, `warmInit`, `renderEnvInit`) appear as a distinct row group on the first build of a session.
 
-`tbdocs.mjs:injectGanttChart` splices the rendered SVG into the [Build Info](BuildInfo) page just after `writeOffline` completes and just before the build returns. The page itself is a placeholder with a `<!-- gantt-chart -->` comment that the inject pass replaces. Both the online and offline copies of the page get the SVG; the page also carries small JavaScript helpers for zoom, download, and PNG export.
+The Gantt chart flows through the same SVG inlining pipeline as other diagrams. The [Build Info](BuildInfo) page contains a standard markdown image reference to a placeholder `gantt.svg`; during the render pass it becomes an inline SVG wrapper with zoom and export controls. After `writeOffline` completes, `tbdocs.mjs:injectGanttChart` locates the wrapper's `data-svg-src` marker in the rendered HTML and swaps the placeholder SVG content for the real Gantt chart. Both the online and offline copies of the page are patched; the on-disk `gantt.svg` file is also updated so the offline mirror's fallback stays current.
 
 When adding a new task to `TASKS`, give it a `ganttSection` key matching one of `Seeds` / `Spine` / `Render` / `Write` so it lands in a coherent group. Tasks without a section fall into a generic "Other" bucket.
 
@@ -378,7 +409,7 @@ The site's `/assets/` tree at deploy time is assembled from three sources:
 
 | Source on disk | What lives there | Phase that delivers it |
 |---|---|---|
-| `docs/assets/` | Project-owned content: the SCSS entry point, project JS (`theme-switch.js`), hand-written stylesheets (`print.css`, `just-the-docs-head-nav.css`), Graphviz/DOT diagrams (`.dot` sources + `.svg` renders), and any content images contributors add. | Discovered by [`discover.mjs`](https://github.com/twinbasic/documentation/blob/main/builder/discover.mjs), copied by `writeAssets`. |
+| `docs/assets/` | Project-owned content: the SCSS entry point, project JS (`theme-switch.js`, `svg-inline.js`), hand-written stylesheets (`print.css`, `just-the-docs-head-nav.css`), Graphviz/DOT diagrams (`.dot` sources + `.svg` renders), and any content images contributors add. | Discovered by [`discover.mjs`](https://github.com/twinbasic/documentation/blob/main/builder/discover.mjs), copied by `writeAssets`. |
 | `builder/vendor/just-the-docs/` | Vendored from the just-the-docs theme (v0.10.1): `_sass/` (the theme's SCSS sources, fed into the compilation) and `assets/js/just-the-docs.js` + `assets/js/vendor/lunr.min.js` (the chrome runtime, copied verbatim). See [`builder/vendor/just-the-docs/README.md`](https://github.com/twinbasic/documentation/blob/main/builder/vendor/just-the-docs/README.md) for the inventory, re-vendoring procedure, and the in-tree patches applied to `just-the-docs.js`. | `_sass/` consumed by [`scss.mjs`](https://github.com/twinbasic/documentation/blob/main/builder/scss.mjs); `assets/` copied by `writeAssets`. |
 | Generated in-process | `just-the-docs-combined.css` (from `scss.mjs`) and `tb-highlight.css` (from `highlight-theme.mjs`). Neither is committed; both are rebuilt every run. | Written by `scss` (combined CSS) and `writeAssets` (highlight CSS). |
 
diff --git a/docs/Documentation/Building.md b/docs/Documentation/Building.md
index b69e621c..9a20498e 100644
--- a/docs/Documentation/Building.md
+++ b/docs/Documentation/Building.md
@@ -69,7 +69,9 @@ Diagrams live as `.dot` source files under `docs/assets/images/dot/` and are ref
 
     ![Diagram](/assets/images/dot/<name>.svg)
 
-`tbdocs` regenerates each `.svg` from its `.dot` sibling when the SVG is missing or older than its source --- editing a `.dot` by one character regenerates the SVG on the next build. Both files belong in git; the `.dot` is the canonical source, the `.svg` is the build artifact the browser loads.
+`tbdocs` regenerates each `.svg` from its `.dot` sibling when the SVG is missing or older than its source --- editing a `.dot` by one character regenerates the SVG on the next build. Both files belong in git; the `.dot` is the canonical source, the `.svg` is the build artifact.
+
+At render time, any markdown image reference to a build-local `.svg` is replaced with the SVG content inlined directly in the HTML. Each inlined SVG gets a click-to-zoom overlay and four control links (Download SVG, Copy SVG, Download PNG, Copy PNG). The controls are hidden in print output. See the [SVG inlining](Builder#svg-inlining) section of the Builder page for the implementation details.
 
 The renderer drives `@hpcc-js/wasm-graphviz` directly: one WASM module load (~50 ms) covers the whole batch, then each diagram is a synchronous `gv.dot(src)` call. No headless browser, no in-tree patches, no Chromium dependency for diagrams. Two failure modes are handled distinctly:
 
diff --git a/docs/Documentation/Pipeline-Stages.md b/docs/Documentation/Pipeline-Stages.md
index 5526d23c..ac988c86 100644
--- a/docs/Documentation/Pipeline-Stages.md
+++ b/docs/Documentation/Pipeline-Stages.md
@@ -46,6 +46,7 @@ The pipeline passes three pieces of mutable state through every task: the `pages
 | `seoIsHome` | `render:i` (`computeChunkSeo`) | `boolean` | `true` when the page's permalink is a known home-page URL. |
 | `html` | `render:i` (`templatePhase`) | `string` | Complete HTML document, ready to write to disk. Absent on `layout: book-combined` pages, which `writePdf` owns. |
 | `offlineHtml` | `render:i` (`deriveOfflinePageCached`) | `string\|undefined` | Pre-computed offline HTML for the page, with every absolute URL rewritten to a page-relative path. Set after `templatePhase` when `!skipOffline`. |
+| `hasSvg` | `render:i` (`svgInlinePlugin`) | `boolean\|undefined` | `true` when the page contains at least one inlined SVG. `templatePhase` uses this to conditionally include the `svg-inline.js` script. |
 | `offlineMisses` | `render:i` (`deriveOfflinePageCached`) | `number\|undefined` | Count of URLs that could not be resolved during the per-page offline rewrite. Aggregated by `flushJoin`. |
 
 ### Site object (`site`)
@@ -463,11 +464,13 @@ The same modules as above, with the full export list per file.
 | Symbol | Signature | Description |
 |---|---|---|
 | `renderPhase` | `(pages, site, staticFiles?) → Promise<void>` | Renders each page's `rawContent` to `renderedContent` via the supplied site's markdown-it. Skips `layout: book-combined`. |
-| `createMarkdownIt` | `({ highlighter, linkTables, baseurl, staticFiles }) → MarkdownIt` | Builds the configured markdown-it instance. See [Extending](Extending) for the plugin list and ordering. |
+| `createMarkdownIt` | `({ highlighter, linkTables, baseurl, staticFiles, svgContents? }) → MarkdownIt` | Builds the configured markdown-it instance. `svgContents` is a `Map<srcRel, string>` of pre-read SVG file contents; when present, the `svgInlinePlugin` replaces `<img>` tags for matching `.svg` sources with inline SVG wrappers. See [Extending](Extending) for the plugin list and ordering. |
 | `initHighlighter` | (re-export from `highlight.mjs`) | `() → Promise<object>`. Initialises Shiki with the bundled twinBASIC grammar. |
 | `buildLinkTables` | `(pages) → { byPath, byUrl, byRedirect }` | Map lookups keyed by `srcRel`, `permalink`, and `redirect_from` entries. |
 | `serializeLinkTables` | `(lt) → { byPath, byUrl, byRedirect }` | Serializes the Maps to `[key, permalink]` pair arrays for structured-clone transfer to workers. |
 | `kramdownSlug` | `(text) → string` | Header-id slugify: lowercase, drop characters outside `\p{L}\p{N}\p{M}\p{Pc}\-`, replace spaces with `-`, deduplicate. |
+| `svgInlinePlugin` | `(md, ctx) → void` | markdown-it plugin. Overrides the image renderer: when the `src` ends in `.svg` and its content exists in `ctx.svgContents`, replaces the `<img>` with an inline SVG wrapper (via `buildSvgWrapper`) and sets `page.hasSvg = true`. Non-matching images fall through to the default renderer. Registered last in the plugin chain. |
+| `buildSvgWrapper` | `(svgContent, alt, stem, srcRel) → string` | Returns the `<div class="svg-inline-wrap">` HTML structure containing the SVG controls (download/copy SVG and PNG) and the `<div class="svg-container">` with the raw SVG content. |
 | `rewriteAdmonitions` | `(src) → string` | GFM admonition rewrite to the `markdown-alert markdown-alert-<type>` class structure with the five SVG octicons. |
 
 ### `highlight.mjs`