living-documentation 4.1.0 → 4.2.0

package/README.md

@@ -2,7 +2,7 @@
 
 A CLI tool that serves a local Markdown documentation viewer in your browser.
 
-No cloud, no database, no build step — just point it at a folder of `.md` files.
+No cloud, no database, no build step — just point it at a folder where you add your project's folder documentation composed of `.md` files (ADR : Architecture Decision Records, generally).
 
 ![Node.js](https://img.shields.io/badge/Node.js-18%2B-green)
 ![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue)
@@ -11,12 +11,22 @@ No cloud, no database, no build step — just point it at a folder of `.md` file
 ## Features
 
 - **Sidebar** grouped by category, sorted alphabetically by full filename
+[![README Diagrams](./images/readme-sidebar.png)](/diagram?id=d1775399110713)
+
+- **Categories Sections and General section** — Categories are extracted from the fileName pattern of your Markdown documents (that may be Architecture Decision Records ADRs).
+ExtraFiles (added in the admin section) are always first, always expanded in a `GENERAL Section` that holds uncategorized docs and extra files
+[![README Diagrams](./images/readme-filename-pattern.png)](/diagram?id=d1775399110713)
+
 - **Recursive folder scanning** — subdirectories are scanned automatically; subdirectory name becomes the category
-- **General section** — always first, always expanded; holds uncategorized docs and extra files
-- **Extra files** — include Markdown files from outside the docs folder (e.g. `README.md`, `CLAUDE.md`)
-- **Full-text search** — instant filter + server-side content search
+
+- **Extra files** — You can add custom ExtraFiles to your documentation that are outside the docs folder (e.g. `README.md`, `CLAUDE.md`) in the `Admin` Page
+[![README Diagrams](./images/readme-extra-files.png)](/diagram?id=d1775399110713)
+
 - **Dark mode** — follows system preference, manually toggleable
 - **Syntax highlighting** — always dark, high-contrast code blocks
+[![README Diagrams](./images/readme-code-blocks.png)](/diagram?id=d1775399110713)
+
+- **Full-text search** — instant filter + server-side content search
 - **Export to PDF** — print-friendly layout via `window.print()`
 - **Deep links** — share a direct URL to any document (`?doc=…`)
 - **Admin panel** — configure title, theme, filename pattern, and extra files in the browser
@@ -222,4 +232,4 @@ The compiled package is self-contained inside `dist/`. Only `dist/` is included
 
 ## License
 
-MIT
+MIT

package/dist/src/frontend/diagram/image-name-modal.js

@@ -0,0 +1,48 @@
+// ── Image filename modal ───────────────────────────────────────────────────────
+// Returns a Promise<string|null>:
+//   string (possibly empty) → user confirmed (empty = use auto name)
+//   null                    → user cancelled
+
+const IMAGE_NAME_RE = /^[a-z0-9_-]*$/i;
+
+export function promptImageName() {
+  return new Promise((resolve) => {
+    const modal   = document.getElementById('imageNameModal');
+    const input   = document.getElementById('imageNameInput');
+    const error   = document.getElementById('imageNameError');
+    const confirm = document.getElementById('imageNameConfirm');
+    const cancel  = document.getElementById('imageNameCancel');
+
+    input.value = '';
+    error.classList.add('hidden');
+    modal.style.display = 'flex';
+    setTimeout(() => input.focus(), 50);
+
+    function validate() {
+      const val = input.value.trim();
+      const ok  = val === '' || IMAGE_NAME_RE.test(val);
+      error.classList.toggle('hidden', ok);
+      return ok;
+    }
+
+    function close(name) {
+      modal.style.display = 'none';
+      confirm.removeEventListener('click',  onConfirm);
+      cancel.removeEventListener('click',   onCancel);
+      input.removeEventListener('input',    validate);
+      input.removeEventListener('keydown',  onKey);
+      resolve(name);
+    }
+    function onConfirm() { if (validate()) close(input.value.trim()); }
+    function onCancel()  { close(null); }
+    function onKey(e) {
+      if (e.key === 'Enter')  { e.preventDefault(); if (validate()) close(input.value.trim()); }
+      if (e.key === 'Escape') { e.preventDefault(); close(null); }
+    }
+
+    confirm.addEventListener('click',  onConfirm);
+    cancel.addEventListener('click',   onCancel);
+    input.addEventListener('input',    validate);
+    input.addEventListener('keydown',  onKey);
+  });
+}

package/dist/src/frontend/diagram/image-upload.js

@@ -11,22 +11,24 @@ async function toBase64(blob) {
   });
 }
 
-export async function uploadImageFile(file) {
+export async function uploadImageFile(file, name = '') {
   const ext    = (file.name.split('.').pop() || 'png').toLowerCase();
   const base64 = await toBase64(file);
-  return _upload(base64, ext);
+  return _upload(base64, ext, name);
 }
 
-export async function uploadImageBlob(blob, ext = 'png') {
+export async function uploadImageBlob(blob, ext = 'png', name = '') {
   const base64 = await toBase64(blob);
-  return _upload(base64, ext);
+  return _upload(base64, ext, name);
 }
 
-async function _upload(base64, ext) {
+async function _upload(base64, ext, name = '') {
+  const body = { data: base64, ext };
+  if (name) body.name = name;
   const res  = await fetch('/api/images/upload', {
     method:  'POST',
     headers: { 'Content-Type': 'application/json' },
-    body:    JSON.stringify({ data: base64, ext }),
+    body:    JSON.stringify(body),
   });
   if (!res.ok) throw new Error('Upload failed');
   const { filename } = await res.json();

package/dist/src/frontend/diagram/main.js

@@ -16,6 +16,7 @@ import { loadDiagramList, newDiagram, saveDiagram } from './persistence.js';
 import { copySelected, pasteClipboard, copySelectionAsPng } from './clipboard.js';
 import { createImageNode } from './network.js';
 import { uploadImageBlob } from './image-upload.js';
+import { promptImageName } from './image-name-modal.js';
 import { showToast }       from './toast.js';
 
 // ── Tool management ───────────────────────────────────────────────────────────
@@ -158,7 +159,7 @@ document.addEventListener('keydown', (e) => {
   if ((e.metaKey || e.ctrlKey) && e.key === 'a')             { e.preventDefault(); selectAll();       return; }
   if ((e.metaKey || e.ctrlKey) && e.key === 'c' && e.shiftKey) { e.preventDefault(); copySelectionAsPng(); return; }
   if ((e.metaKey || e.ctrlKey) && e.key === 'c')               { e.preventDefault(); copySelected();       return; }
-  if ((e.metaKey || e.ctrlKey) && e.key === 'v')             { e.preventDefault(); pasteClipboard();  return; }
+  // Cmd+V is handled in the 'paste' event below (needs clipboardData access)
   if ((e.metaKey || e.ctrlKey) && e.key === 's')             { e.preventDefault(); saveDiagram();     return; }
   if (e.key === 'Escape' || e.key === 's' || e.key === 'S')  { cancelStamp(); hideLinkPanel(); setTool('select'); return; }
   if (e.key === 'r' || e.key === 'R')  { setTool('addNode', 'box');      return; }
@@ -172,25 +173,37 @@ document.addEventListener('keydown', (e) => {
   if (e.key === 'g' || e.key === 'G')  { toggleGrid();                   return; }
 });
 
-// ── Paste image from clipboard ────────────────────────────────────────────────
+// ── Paste (image or shapes) ───────────────────────────────────────────────────
 document.addEventListener('paste', async (e) => {
   if (e.target.tagName === 'INPUT' || e.target.tagName === 'TEXTAREA') return;
   if (!st.network) return;
-  const items = Array.from(e.clipboardData.items || []);
-  const imageItem = items.find((it) => it.type.startsWith('image/'));
-  if (!imageItem) return;
   e.preventDefault();
-  const blob = imageItem.getAsFile();
-  if (!blob) return;
-  const ext = imageItem.type.split('/')[1] || 'png';
-  try {
-    const src = await uploadImageBlob(blob, ext);
-    // Place at centre of current viewport
-    const center = st.network.getViewPosition();
-    createImageNode(src, center.x, center.y);
-    showToast('Image ajoutée');
-  } catch {
-    showToast('Impossible d\'importer l\'image', 'error');
+
+  const items     = Array.from(e.clipboardData?.items || []);
+  const imageItem = items.find((it) => it.type.startsWith('image/'));
+
+  if (imageItem) {
+    const blob = imageItem.getAsFile();
+    if (!blob) return;
+    const ext = imageItem.type.split('/')[1] || 'png';
+
+    const name = await promptImageName();
+    if (name === null) return; // user cancelled
+
+    try {
+      const src = await uploadImageBlob(blob, ext, name);
+      const center = st.network.getViewPosition();
+      createImageNode(src, center.x, center.y);
+      showToast('Image ajoutée');
+      // Clear system clipboard so the next Cmd+V pastes shapes, not the image again
+      // (our Cmd+C only writes to st.clipboard, not the system clipboard)
+      navigator.clipboard.writeText('').catch(() => {});
+    } catch {
+      showToast('Impossible d\'importer l\'image', 'error');
+    }
+  } else {
+    // No image — paste shapes from internal clipboard
+    pasteClipboard();
   }
 });
 

package/dist/src/frontend/diagram/network.js

@@ -5,6 +5,7 @@
 import { st, markDirty } from './state.js';
 import { visNodeProps, SHAPE_DEFAULTS }   from './node-rendering.js';
 import { uploadImageFile } from './image-upload.js';
+import { promptImageName } from './image-name-modal.js';
 import { showToast }       from './toast.js';
 import { visEdgeProps }   from './edge-rendering.js';
 import { showNodePanel, hideNodePanel } from './node-panel.js';
@@ -184,8 +185,10 @@ function pickAndCreateImageNode(canvasX, canvasY) {
   input.onchange = async () => {
     const file = input.files && input.files[0];
     if (!file) return;
+    const name = await promptImageName();
+    if (name === null) return; // user cancelled
     try {
-      const src = await uploadImageFile(file);
+      const src = await uploadImageFile(file, name);
       createImageNode(src, canvasX, canvasY);
     } catch {
       showToast('Impossible d\'importer l\'image', 'error');
@@ -196,22 +199,53 @@ function pickAndCreateImageNode(canvasX, canvasY) {
 
 export function createImageNode(imageSrc, canvasX, canvasY) {
   if (!st.network) return;
-  const id = 'n' + Date.now();
-  const defaults = SHAPE_DEFAULTS['image'];
-  st.nodes.add({
-    id, label: '', imageSrc,
-    shapeType: 'image', colorKey: 'c-gray',
-    nodeWidth: defaults[0], nodeHeight: defaults[1],
-    fontSize: null, rotation: 0, labelRotation: 0,
-    x: canvasX, y: canvasY,
-    ...visNodeProps('image', 'c-gray', defaults[0], defaults[1], null, null, null),
-  });
-  markDirty();
-  setTimeout(() => {
-    st.network.selectNodes([id]);
-    st.selectedNodeIds = [id];
-    showNodePanel();
-  }, 50);
+  const id      = 'n' + Date.now();
+  const captionId = id + 'c';
+
+  const addNode = (nW, nH) => {
+    const filename   = imageSrc.split('/').pop() || '';
+    const textDefs   = SHAPE_DEFAULTS['text-free'];
+    const captionH   = textDefs[1];
+    const GAP        = 8;
+
+    const groupId = 'g' + Date.now();
+    st.nodes.add({
+      id, label: '', imageSrc, groupId,
+      shapeType: 'image', colorKey: 'c-gray',
+      nodeWidth: nW, nodeHeight: nH,
+      fontSize: null, rotation: 0, labelRotation: 0,
+      x: canvasX, y: canvasY,
+      ...visNodeProps('image', 'c-gray', nW, nH, null, null, null),
+    });
+    st.nodes.add({
+      id: captionId, label: filename, groupId,
+      shapeType: 'text-free', colorKey: 'c-gray',
+      nodeWidth: nW, nodeHeight: captionH,
+      fontSize: null, rotation: 0, labelRotation: 0,
+      x: canvasX, y: canvasY + nH / 2 + GAP + captionH / 2,
+      ...visNodeProps('text-free', 'c-gray', nW, captionH, null, null, null),
+    });
+    markDirty();
+    setTimeout(() => {
+      st.network.selectNodes([id]);
+      st.selectedNodeIds = [id];
+      showNodePanel();
+    }, 50);
+  };
+
+  const img = new Image();
+  img.onload = () => {
+    const MAX = 300;
+    const ratio = img.naturalWidth / img.naturalHeight;
+    let nW = img.naturalWidth, nH = img.naturalHeight;
+    if (nW > MAX) { nW = MAX; nH = Math.round(MAX / ratio); }
+    addNode(nW, nH);
+  };
+  img.onerror = () => {
+    const d = SHAPE_DEFAULTS['image'];
+    addNode(d[0], d[1]);
+  };
+  img.src = imageSrc;
 }
 
 function onClickNode(params) {

package/dist/src/frontend/diagram/selection-overlay.js

@@ -74,6 +74,7 @@ function onResizeStart(e, corner) {
   e.preventDefault();
   e.stopPropagation();
 
+  const positions = st.network.getPositions(st.selectedNodeIds);
   const startBBs = st.selectedNodeIds.map((id) => {
     const n = st.nodes.get(id);
     const b = nodeBounds(id);
@@ -81,13 +82,22 @@ function onResizeStart(e, corner) {
     const defaults = SHAPE_DEFAULTS[shape] || [60, 28];
     const initW = (n && n.nodeWidth)  || (b ? Math.round(b.maxX - b.minX) : defaults[0]);
     const initH = (n && n.nodeHeight) || (b ? Math.round(b.maxY - b.minY) : defaults[1]);
-    return { id, node: n, initW, initH };
+    const pos = positions[id] || { x: 0, y: 0 };
+    return { id, node: n, initW, initH, initX: pos.x, initY: pos.y };
   });
 
-  const initBoxW = startBBs.reduce((m, b) => Math.max(m, b.initW), 0);
-  const initBoxH = startBBs.reduce((m, b) => Math.max(m, b.initH), 0);
+  // True bounding box of the whole selection (for scale reference and pivot)
+  let bbMinX = Infinity, bbMinY = Infinity, bbMaxX = -Infinity, bbMaxY = -Infinity;
+  for (const { id } of startBBs) {
+    const b = nodeBounds(id);
+    if (!b) continue;
+    bbMinX = Math.min(bbMinX, b.minX); bbMinY = Math.min(bbMinY, b.minY);
+    bbMaxX = Math.max(bbMaxX, b.maxX); bbMaxY = Math.max(bbMaxY, b.maxY);
+  }
+  const initBoxW = (bbMaxX - bbMinX) || 1;
+  const initBoxH = (bbMaxY - bbMinY) || 1;
 
-  st.resizeDrag = { corner, startMouse: { x: e.clientX, y: e.clientY }, startBBs, initBoxW, initBoxH };
+  st.resizeDrag = { corner, startMouse: { x: e.clientX, y: e.clientY }, startBBs, initBoxW, initBoxH, bbMinX, bbMinY, bbMaxX, bbMaxY };
   st.selectedNodeIds.forEach((id) => st.nodes.update({ id, fixed: true }));
   document.getElementById('vis-canvas').style.pointerEvents = 'none';
   document.addEventListener('mousemove', onResizeDrag);
@@ -110,22 +120,34 @@ function onResizeDrag(e) {
     if (c === 'bl') { nW = initW - cdx; nH = initH + cdy; }
     if (c === 'tr') { nW = initW + cdx; nH = initH - cdy; }
     if (c === 'tl') { nW = initW - cdx; nH = initH - cdy; }
+    if (e.shiftKey && initW > 0 && initH > 0) {
+      const scale = Math.max(nW / initW, nH / initH);
+      nW = initW * scale;
+      nH = initH * scale;
+    }
     nW = Math.max(MIN, Math.round(nW));
     nH = Math.max(MIN, Math.round(nH));
     st.nodes.update({ id, nodeWidth: nW, nodeHeight: nH, ...visNodeProps(node.shapeType || 'box', node.colorKey || 'c-gray', nW, nH, node.fontSize, node.textAlign, node.textValign) });
     updatedIds.push(id);
   } else {
-    const { initBoxW, initBoxH } = st.resizeDrag;
+    const { initBoxW, initBoxH, bbMinX, bbMinY, bbMaxX, bbMaxY } = st.resizeDrag;
     let sx = 1, sy = 1;
     if (c === 'br') { sx = (initBoxW + cdx) / initBoxW; sy = (initBoxH + cdy) / initBoxH; }
     if (c === 'bl') { sx = (initBoxW - cdx) / initBoxW; sy = (initBoxH + cdy) / initBoxH; }
     if (c === 'tr') { sx = (initBoxW + cdx) / initBoxW; sy = (initBoxH - cdy) / initBoxH; }
     if (c === 'tl') { sx = (initBoxW - cdx) / initBoxW; sy = (initBoxH - cdy) / initBoxH; }
     sx = Math.max(0.1, sx); sy = Math.max(0.1, sy);
-    for (const { id, node, initW, initH } of st.resizeDrag.startBBs) {
+    if (e.shiftKey) { const s = Math.max(sx, sy); sx = s; sy = s; }
+
+    // Pivot = corner opposite to the drag corner (stays fixed during scale)
+    const pivotX = (c === 'br' || c === 'tr') ? bbMinX : bbMaxX;
+    const pivotY = (c === 'br' || c === 'bl') ? bbMinY : bbMaxY;
+
+    for (const { id, node, initW, initH, initX, initY } of st.resizeDrag.startBBs) {
       const nW = Math.max(MIN, Math.round(initW * sx));
       const nH = Math.max(MIN, Math.round(initH * sy));
       st.nodes.update({ id, nodeWidth: nW, nodeHeight: nH, ...visNodeProps(node.shapeType || 'box', node.colorKey || 'c-gray', nW, nH, node.fontSize, node.textAlign, node.textValign) });
+      st.network.moveNode(id, pivotX + (initX - pivotX) * sx, pivotY + (initY - pivotY) * sy);
       updatedIds.push(id);
     }
   }

package/dist/src/frontend/diagram.html

@@ -1124,6 +1124,39 @@
     </div>
 
     <div id="toastContainer"></div>
+
+    <!-- Image name modal -->
+    <div id="imageNameModal" style="display:none;position:fixed;inset:0;z-index:1000;background:rgba(0,0,0,0.5);"
+         class="flex items-center justify-center">
+      <div class="bg-white dark:bg-gray-800 rounded-xl shadow-2xl p-6 w-80 flex flex-col gap-3">
+        <p class="text-sm font-semibold text-gray-700 dark:text-gray-200">Nom du fichier image</p>
+        <p class="text-xs text-gray-400 dark:text-gray-500">
+          Lettres, chiffres, <code class="bg-gray-100 dark:bg-gray-700 px-0.5 rounded">_</code> et
+          <code class="bg-gray-100 dark:bg-gray-700 px-0.5 rounded">-</code> uniquement.
+          Laisser vide pour un nom automatique.
+        </p>
+        <div class="flex items-center gap-1">
+          <input id="imageNameInput" type="text" autocomplete="off" spellcheck="false"
+                 class="flex-1 rounded border border-gray-300 dark:border-gray-600 bg-white dark:bg-gray-700
+                        text-gray-900 dark:text-gray-100 text-sm px-2 py-1 outline-none focus:ring-2 focus:ring-blue-400"
+                 placeholder="nom_image" />
+          <span class="text-xs text-gray-400 dark:text-gray-500 whitespace-nowrap">.png</span>
+        </div>
+        <p id="imageNameError" class="text-xs text-red-500 hidden">Caractères autorisés : lettres, chiffres, _ et -</p>
+        <div class="flex gap-2 justify-end">
+          <button id="imageNameCancel"
+                  class="px-3 py-1 text-xs rounded border border-gray-300 dark:border-gray-600
+                         text-gray-600 dark:text-gray-300 hover:bg-gray-100 dark:hover:bg-gray-700">
+            Annuler
+          </button>
+          <button id="imageNameConfirm"
+                  class="px-3 py-1 text-xs rounded bg-blue-500 text-white hover:bg-blue-600">
+            Coller
+          </button>
+        </div>
+      </div>
+    </div>
+
     <script type="module" src="/diagram/main.js"></script>
   </body>
 </html>

package/dist/src/frontend/index.html

@@ -139,10 +139,18 @@
         border-radius: 2px;
         padding: 0 2px;
       }
+      mark.match-active {
+        background: #f97316;
+        color: #fff;
+      }
       .dark mark {
         background: #713f12;
         color: #fef9c3;
       }
+      .dark mark.match-active {
+        background: #ea580c;
+        color: #fff;
+      }
     </style>
   </head>
 
@@ -329,6 +337,13 @@
                     >
                       &#9998; Edit
                     </button>
+                    <button
+                      onclick="openDiagramLinkModal()"
+                      title="Link a diagram"
+                      class="no-print text-sm px-3 py-1.5 rounded-lg border border-gray-200 dark:border-gray-700 text-gray-600 dark:text-gray-400 hover:bg-gray-50 dark:hover:bg-gray-800 transition-colors"
+                    >
+                      &#9671; Diagram
+                    </button>
                   </div>
                   <!-- Edit mode actions -->
                   <div id="edit-actions" class="hidden flex items-center gap-2">
@@ -379,6 +394,65 @@
     </div>
     <!-- end root -->
 
+    <!-- ── Diagram link modal ── -->
+    <div id="diag-link-modal" class="hidden fixed inset-0 z-50 flex items-center justify-center bg-black/50">
+      <div class="bg-white dark:bg-gray-900 rounded-xl shadow-xl w-full max-w-lg mx-4 p-6 space-y-5">
+        <h3 class="text-base font-semibold text-gray-900 dark:text-gray-50">&#9671; Link a diagram</h3>
+
+        <!-- Mode toggle -->
+        <div class="flex gap-4 text-sm">
+          <label class="flex items-center gap-2 cursor-pointer">
+            <input type="radio" name="diag-mode" id="diag-mode-existing" value="existing" checked onchange="diagModeChanged()" />
+            <span class="text-gray-700 dark:text-gray-300">Existing diagram</span>
+          </label>
+          <label class="flex items-center gap-2 cursor-pointer">
+            <input type="radio" name="diag-mode" id="diag-mode-new" value="new" onchange="diagModeChanged()" />
+            <span class="text-gray-700 dark:text-gray-300">New diagram</span>
+          </label>
+        </div>
+
+        <!-- Existing diagram picker -->
+        <div id="diag-existing-section" class="space-y-1.5">
+          <label class="block text-xs font-medium text-gray-500 dark:text-gray-400">Select diagram</label>
+          <select id="diag-select" onchange="diagUpdatePreview()"
+            class="w-full px-3 py-2 text-sm rounded-lg border border-gray-300 dark:border-gray-600 bg-gray-50 dark:bg-gray-800 text-gray-900 dark:text-gray-100 focus:outline-none focus:ring-2 focus:ring-blue-500">
+          </select>
+        </div>
+
+        <!-- New diagram name -->
+        <div id="diag-new-section" class="hidden space-y-1.5">
+          <label class="block text-xs font-medium text-gray-500 dark:text-gray-400">Diagram name</label>
+          <input id="diag-new-name" type="text" placeholder="My diagram" oninput="diagUpdatePreview()"
+            class="w-full px-3 py-2 text-sm rounded-lg border border-gray-300 dark:border-gray-600 bg-gray-50 dark:bg-gray-800 text-gray-900 dark:text-gray-100 focus:outline-none focus:ring-2 focus:ring-blue-500" />
+        </div>
+
+        <!-- Image filename -->
+        <div class="space-y-1.5">
+          <label class="block text-xs font-medium text-gray-500 dark:text-gray-400">Image filename <span class="font-normal text-gray-400">(saved in ./images/)</span></label>
+          <input id="diag-img-name" type="text" placeholder="diagram.png" oninput="diagUpdatePreview()"
+            class="w-full px-3 py-2 text-sm rounded-lg border border-gray-300 dark:border-gray-600 bg-gray-50 dark:bg-gray-800 text-gray-900 dark:text-gray-100 font-mono focus:outline-none focus:ring-2 focus:ring-blue-500" />
+        </div>
+
+        <!-- Markdown preview -->
+        <div class="space-y-1.5">
+          <label class="block text-xs font-medium text-gray-500 dark:text-gray-400">Markdown that will be appended</label>
+          <pre id="diag-preview" class="text-xs bg-gray-100 dark:bg-gray-800 rounded-lg px-3 py-2 overflow-x-auto text-gray-700 dark:text-gray-300 whitespace-pre-wrap"></pre>
+        </div>
+
+        <!-- Actions -->
+        <div class="flex justify-end gap-3 pt-1">
+          <button onclick="closeDiagramLinkModal()"
+            class="text-sm px-4 py-2 rounded-lg border border-gray-200 dark:border-gray-700 text-gray-600 dark:text-gray-400 hover:bg-gray-50 dark:hover:bg-gray-800 transition-colors">
+            Cancel
+          </button>
+          <button onclick="insertDiagramLink()" id="diag-insert-btn"
+            class="text-sm px-4 py-2 rounded-lg bg-blue-600 hover:bg-blue-700 text-white font-semibold transition-colors">
+            Insert &amp; Open Diagram
+          </button>
+        </div>
+      </div>
+    </div>
+
     <!-- ── Word Cloud overlay ── -->
     <div
       id="wc-overlay"
@@ -920,7 +994,7 @@
         const list = document.getElementById("search-notice-list");
         list.innerHTML = matches.map((m, i) =>
           `<li>
-            <button onclick="scrollToMatch('${m.id}')"
+            <button onclick="scrollToMatch('${m.id}')" data-match-id="${m.id}"
               class="w-full text-left px-3 py-1.5 hover:bg-yellow-100 dark:hover:bg-yellow-900/30 transition-colors">
               <span class="text-yellow-600 dark:text-yellow-500 font-mono text-xs mr-2">${i + 1}.</span
               ><span class="text-xs">${esc(m.snippet)}</span>
@@ -933,9 +1007,23 @@
         const mark      = document.getElementById(id);
         const container = document.getElementById("content-area");
         if (!mark || !container) return;
-        const markTop      = mark.getBoundingClientRect().top;
-        const containerTop = container.getBoundingClientRect().top;
-        container.scrollTop += markTop - containerTop - container.clientHeight / 3;
+
+        // Orange on the active mark, yellow on the rest
+        document.querySelectorAll("mark.match-active").forEach((m) => m.classList.remove("match-active"));
+        mark.classList.add("match-active");
+
+        // Highlight active list item
+        document.querySelectorAll("#search-notice-list button").forEach((b) => {
+          b.classList.toggle("bg-orange-100", b.dataset.matchId === id);
+          b.classList.toggle("dark:bg-orange-900/30", b.dataset.matchId === id);
+        });
+
+        const stickyHeader  = document.querySelector("#doc-view header");
+        const headerHeight  = stickyHeader ? stickyHeader.getBoundingClientRect().height : 0;
+        const markTop       = mark.getBoundingClientRect().top;
+        const containerTop  = container.getBoundingClientRect().top;
+        const targetOffset  = headerHeight + (container.clientHeight - headerHeight) / 3;
+        container.scrollTop += markTop - containerTop - targetOffset;
       }
 
       function esc(str) {
@@ -948,6 +1036,112 @@
       }
 
 
+      // ── Diagram link modal ────────────────────────────────────
+      let _diagrams = [];
+
+      async function openDiagramLinkModal() {
+        if (!currentDocId) return;
+        // Fetch diagram list
+        try {
+          _diagrams = await fetch("/api/diagrams").then((r) => r.json());
+        } catch { _diagrams = []; }
+
+        const sel = document.getElementById("diag-select");
+        sel.innerHTML = _diagrams.length
+          ? _diagrams.map((d) => `<option value="${esc(d.id)}">${esc(d.title)}</option>`).join("")
+          : `<option value="" disabled>No diagrams yet</option>`;
+
+        // Pre-fill image name from current doc title
+        const docTitle = document.getElementById("doc-title").textContent.trim();
+        const slug = docTitle.toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_|_$/g, "");
+        document.getElementById("diag-img-name").value = slug ? slug + ".png" : "diagram.png";
+        document.getElementById("diag-new-name").value = docTitle ? docTitle + " Diagram" : "";
+
+        // Default mode
+        document.getElementById("diag-mode-existing").checked = true;
+        diagModeChanged();
+
+        document.getElementById("diag-link-modal").classList.remove("hidden");
+      }
+
+      function closeDiagramLinkModal() {
+        document.getElementById("diag-link-modal").classList.add("hidden");
+      }
+
+      function diagModeChanged() {
+        const isNew = document.getElementById("diag-mode-new").checked;
+        document.getElementById("diag-existing-section").classList.toggle("hidden", isNew);
+        document.getElementById("diag-new-section").classList.toggle("hidden", !isNew);
+        diagUpdatePreview();
+      }
+
+      function diagUpdatePreview() {
+        const isNew   = document.getElementById("diag-mode-new").checked;
+        const imgName = document.getElementById("diag-img-name").value.trim() || "diagram.png";
+        let diagId, diagLabel;
+        if (isNew) {
+          diagId    = "d" + Date.now();
+          diagLabel = document.getElementById("diag-new-name").value.trim() || "Diagram";
+        } else {
+          const sel = document.getElementById("diag-select");
+          diagId    = sel.value;
+          diagLabel = sel.options[sel.selectedIndex]?.text || "Diagram";
+        }
+        const md = `\n\n[![${diagLabel}](./images/${imgName})](/diagram?id=${diagId})`;
+        document.getElementById("diag-preview").textContent = md.trim();
+        // store for insertDiagramLink
+        document.getElementById("diag-insert-btn").dataset.diagId    = diagId;
+        document.getElementById("diag-insert-btn").dataset.diagLabel = diagLabel;
+        document.getElementById("diag-insert-btn").dataset.imgName   = imgName;
+        document.getElementById("diag-insert-btn").dataset.isNew     = isNew ? "1" : "0";
+      }
+
+      async function insertDiagramLink() {
+        const btn      = document.getElementById("diag-insert-btn");
+        const diagId   = btn.dataset.diagId;
+        const diagLabel= btn.dataset.diagLabel;
+        const imgName  = btn.dataset.imgName;
+        const isNew    = btn.dataset.isNew === "1";
+
+        btn.disabled = true;
+        btn.textContent = "Saving…";
+
+        try {
+          // Create new diagram if needed
+          if (isNew) {
+            await fetch(`/api/diagrams/${diagId}`, {
+              method: "PUT",
+              headers: { "Content-Type": "application/json" },
+              body: JSON.stringify({ title: diagLabel, nodes: [], edges: [] }),
+            });
+          }
+
+          // Append markdown to document and save
+          const md = `\n\n[![${diagLabel}](./images/${imgName})](/diagram?id=${diagId})`;
+          const newContent = currentDocContent + md;
+          const res = await fetch("/api/documents/" + currentDocId, {
+            method: "PUT",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ content: newContent }),
+          });
+          if (!res.ok) throw new Error(await res.text());
+          currentDocContent = newContent;
+
+          // Re-render the document so the page is up-to-date when the user navigates back
+          const doc = await fetch("/api/documents/" + currentDocId).then((r) => r.json());
+          const contentEl = document.getElementById("doc-content");
+          contentEl.innerHTML = doc.html;
+          contentEl.querySelectorAll("pre code").forEach((b) => hljs.highlightElement(b));
+
+          closeDiagramLinkModal();
+          window.location.href = `/diagram?id=${diagId}`;
+        } catch (err) {
+          btn.disabled = false;
+          btn.textContent = "Insert & Open Diagram";
+          alert("Error: " + err.message);
+        }
+      }
+
       // Browser back/forward
       window.addEventListener("popstate", (e) => {
         const id =

package/dist/src/routes/images.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"images.d.ts","sourceRoot":"","sources":["../../../src/routes/images.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAqB,MAAM,SAAS,CAAC;AAIpD,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAuCrD"}
+{"version":3,"file":"images.d.ts","sourceRoot":"","sources":["../../../src/routes/images.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAqB,MAAM,SAAS,CAAC;AAIpD,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CA6CrD"}

package/dist/src/routes/images.js

@@ -11,7 +11,7 @@ function imagesRouter(docsPath) {
     const router = (0, express_1.Router)();
     // POST /api/images/upload — save a base64-encoded image to DOCS_FOLDER/images/
     router.post('/upload', (req, res) => {
-        const { data, ext } = req.body;
+        const { data, ext, name } = req.body;
         if (typeof data !== 'string' || !data) {
             return res.status(400).json({ error: 'data is required' });
         }
@@ -22,12 +22,19 @@ function imagesRouter(docsPath) {
         if (!fs_1.default.existsSync(imagesDir)) {
             fs_1.default.mkdirSync(imagesDir, { recursive: true });
         }
-        const now = new Date();
-        const pad = (n) => String(n).padStart(2, '0');
-        const timestamp = `${now.getFullYear()}_${pad(now.getMonth() + 1)}_${pad(now.getDate())}` +
-            `_${pad(now.getHours())}${pad(now.getMinutes())}${pad(now.getSeconds())}`;
-        const random = Math.random().toString(36).slice(2, 6);
-        const filename = `image_${timestamp}_${random}.${safeExt}`;
+        let baseName;
+        if (typeof name === 'string' && name.trim()) {
+            baseName = name.trim().replace(/[^a-z0-9_\-]/gi, '_').replace(/_+/g, '_').replace(/^_|_$/g, '');
+        }
+        else {
+            const now = new Date();
+            const pad = (n) => String(n).padStart(2, '0');
+            const timestamp = `${now.getFullYear()}_${pad(now.getMonth() + 1)}_${pad(now.getDate())}` +
+                `_${pad(now.getHours())}${pad(now.getMinutes())}${pad(now.getSeconds())}`;
+            const random = Math.random().toString(36).slice(2, 6);
+            baseName = `image_${timestamp}_${random}`;
+        }
+        const filename = `${baseName}.${safeExt}`;
         const filePath = path_1.default.join(imagesDir, filename);
         try {
             fs_1.default.writeFileSync(filePath, Buffer.from(base64, 'base64'));

package/dist/src/routes/images.js.map

@@ -1 +1 @@
-{"version":3,"file":"images.js","sourceRoot":"","sources":["../../../src/routes/images.ts"],"names":[],"mappings":";;;;;AAIA,oCAuCC;AA3CD,qCAAoD;AACpD,4CAAoB;AACpB,gDAAwB;AAExB,SAAgB,YAAY,CAAC,QAAgB;IAC3C,MAAM,MAAM,GAAG,IAAA,gBAAM,GAAE,CAAC;IAExB,+EAA+E;IAC/E,MAAM,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC,GAAY,EAAE,GAAa,EAAE,EAAE;QACrD,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,GAAG,GAAG,CAAC,IAAuC,CAAC;QAElE,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,CAAC,IAAI,EAAE,CAAC;YACtC,OAAO,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,kBAAkB,EAAE,CAAC,CAAC;QAC7D,CAAC;QAED,MAAM,OAAO,GAAG,CAAC,OAAO,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,aAAa,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,WAAW,EAAE,IAAI,KAAK,CAAC;QAE1G,0CAA0C;QAC1C,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,4BAA4B,EAAE,EAAE,CAAC,CAAC;QAE9D,MAAM,SAAS,GAAG,cAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;QAChD,IAAI,CAAC,YAAE,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;YAC9B,YAAE,CAAC,SAAS,CAAC,SAAS,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAC/C,CAAC;QAED,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,MAAM,GAAG,GAAG,CAAC,CAAS,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;QACtD,MAAM,SAAS,GACb,GAAG,GAAG,CAAC,WAAW,EAAE,IAAI,GAAG,CAAC,GAAG,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC,IAAI,GAAG,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC,EAAE;YACvE,IAAI,GAAG,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC,GAAG,GAAG,CAAC,GAAG,CAAC,UAAU,EAAE,CAAC,GAAG,GAAG,CAAC,GAAG,CAAC,UAAU,EAAE,CAAC,EAAE,CAAC;QAC5E,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QACtD,MAAM,QAAQ,GAAG,SAAS,SAAS,IAAI,MAAM,IAAI,OAAO,EAAE,CAAC;QAC3D,MAAM,QAAQ,GAAG,cAAI,CAAC,IAAI,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;QAEhD,IAAI,CAAC;YACH,YAAE,CAAC,aAAa,CAAC,QAAQ,EAAE,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC;YAC1D,GAAG,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC;QACzB,CAAC;QAAC,MAAM,CAAC;YACP,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,sBAAsB,EAAE,CAAC,CAAC;QAC1D,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,OAAO,MAAM,CAAC;AAChB,CAAC"}
+{"version":3,"file":"images.js","sourceRoot":"","sources":["../../../src/routes/images.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "living-documentation",
-  "version": "4.1.0",
+  "version": "4.2.0",
   "description": "A CLI tool that serves a local Markdown documentation viewer",
   "main": "dist/src/server.js",
   "bin": {