gutterpress 0.9.0-alpha.1 → 0.9.0-alpha.2

package/dist/{cli-yp0d2hp8.js → cli-k4bd06sd.js}

@@ -20,13 +20,13 @@ import {
   stampCreator,
   stripAnnotations,
   warn
-} from "./cli-v2dze8ja.js";
+} from "./cli-najycadg.js";
 import {
   BuildError,
   DEBOUNCE,
   UsageError,
   resolvePort
-} from "./cli-rkqxbnkq.js";
+} from "./cli-e5zhb0xs.js";
 import {
   gitDirFor,
   gitScopeFor,
@@ -4566,17 +4566,6 @@ async function assembleBookHtml(opts) {
     throw new Error("No markdown files to render");
   }
   const md = createMarkdownRenderer(opts.plugins);
-  let sourceChapter = null;
-  if (opts.wrapChapters) {
-    const renderToken = md.renderer.renderToken.bind(md.renderer);
-    md.renderer.renderToken = (tokens, idx, options) => {
-      const token = tokens[idx];
-      if (sourceChapter !== null && token.level === 0 && token.map !== null && token.type.endsWith("_open")) {
-        token.attrSet("data-chapter-src", sourceChapter);
-      }
-      return renderToken(tokens, idx, options);
-    };
-  }
   let bodyContent = "";
   const imageRefs = new Set;
   for (const file of files) {
@@ -4589,20 +4578,22 @@ async function assembleBookHtml(opts) {
       throw new Error(`Failed to read file ${file}: ${errorMsg}`);
     }
     const env = {};
-    sourceChapter = opts.wrapChapters ? chapterId : null;
-    let rendered;
-    try {
-      rendered = md.render(content, env);
-    } finally {
-      sourceChapter = null;
-    }
+    const rendered = md.render(content, env);
     if (env.layoutWarnings && env.layoutWarnings.length > 0) {
       opts.onChapterWarnings?.(chapterId, env.layoutWarnings);
     }
     for (const ref of env.imageRefs ?? [])
       imageRefs.add(ref);
-    bodyContent += rendered + `
+    if (opts.wrapChapters) {
+      const safe = chapterId.replace(/&/g, "&").replace(/"/g, """);
+      bodyContent += `<div class="gutterpress-chapter" data-chapter-src="${safe}">
+${rendered}
+</div>
+`;
+    } else {
+      bodyContent += rendered + `
 `;
+    }
   }
   if (opts.onImageRefs) {
     for (const ref of collectHtmlImageRefs(bodyContent))
@@ -6023,13 +6014,13 @@ var favicon_default = "./favicon-wkbm9cjn.ico";
 var manifest_schema_default = "./manifest.schema-z61rzw44.json";
 
 // src/assets/preview/scripts/pagedjs-interface.js
-var pagedjs_interface_default = "./pagedjs-interface-80g3xa8p.js";
+var pagedjs_interface_default = "./pagedjs-interface-qxvzgwd7.js";
 
 // src/assets/preview/scripts/pagedjs-bridge.js
 var pagedjs_bridge_default = "./pagedjs-bridge-vn4hk9fx.js";
 
 // src/assets/preview/scripts/preview-shell.js
-var preview_shell_default = "./preview-shell-rghtfmc8.js";
+var preview_shell_default = "./preview-shell-6dqexx1m.js";
 
 // src/assets/vendor/paged.polyfill.js
 var paged_polyfill_default = "./paged.polyfill-n95pbxfn.js";
@@ -7032,12 +7023,17 @@ async function renderPreviewBook(inputPath, config, opts) {
     }
   });
 }
-function injectPreviewScripts(html) {
+function injectPreviewScripts(html, pageIsolateChapters) {
   const iface = `<script src="/preview/scripts/pagedjs-interface.js"></script>
   ` + `<script src="/preview/scripts/pagedjs-bridge.js"></script>
   `;
-  return html.replace(pagedjsPolyfillTagRegex(), iface + BREAK_INSIDE_HANDLER + `
+  let output = html.replace(pagedjsPolyfillTagRegex(), iface + BREAK_INSIDE_HANDLER + `
   <script src="/vendor/paged.polyfill.js"></script>`);
+  if (pageIsolateChapters && /<\/head>/i.test(output)) {
+    output = output.replace(/<\/head>/i, `<style>.gutterpress-chapter{break-before:page}</style>
+</head>`);
+  }
+  return output;
 }
 async function generateAndWriteHtml(inputPath, tempDir, config, cssAssets) {
   if (!inputPath) {
@@ -7046,9 +7042,10 @@ async function generateAndWriteHtml(inputPath, tempDir, config, cssAssets) {
     return;
   }
   const nextAssets = new Map;
+  const incremental = incrementalPreviewEnabled();
   const html = await renderPreviewBook(inputPath, config, {
     files: config.source?.files ?? null,
-    wrapChapters: true,
+    wrapChapters: incremental,
     onCssAssets: (copies) => {
       for (const copy of copies)
         nextAssets.set(copy.to, copy.from);
@@ -7057,7 +7054,39 @@ async function generateAndWriteHtml(inputPath, tempDir, config, cssAssets) {
   cssAssets.clear();
   for (const [to, from] of nextAssets)
     cssAssets.set(to, from);
-  await fsp4.writeFile(path10.join(tempDir, BOOK_HTML_FILENAME), injectPreviewScripts(html), "utf-8");
+  await fsp4.writeFile(path10.join(tempDir, BOOK_HTML_FILENAME), injectPreviewScripts(html, incremental), "utf-8");
+}
+async function renderChapterPreviewHtml(inputPath, file, config) {
+  const html = await renderPreviewBook(inputPath, config, {
+    files: [canonicalChapterId(file)],
+    wrapChapters: true
+  });
+  return injectPreviewScripts(html, true);
+}
+function describeChanges(changes, inputResolved) {
+  const files = [];
+  for (const [changedPath, event] of changes) {
+    const relative2 = path10.relative(inputResolved, path10.resolve(changedPath));
+    if (relative2 === "" || relative2 === ".." || relative2.startsWith(`..${path10.sep}`) || path10.isAbsolute(relative2))
+      continue;
+    files.push({
+      relativePath: canonicalChapterId(relative2),
+      ext: path10.extname(changedPath).toLowerCase(),
+      event
+    });
+  }
+  return files;
+}
+function decideBroadcast(files, changeCount, incremental) {
+  const only = files.length === 1 ? files[0] : null;
+  if (incremental && changeCount === 1 && only?.ext === ".md" && only.event !== "unlink" && only.event !== "unlinkDir") {
+    return {
+      kind: "chapter-splice",
+      chapterId: canonicalChapterId(only.relativePath),
+      relativePath: only.relativePath
+    };
+  }
+  return { kind: "full-reload" };
 }
 function isDotPathUnderRoot(candidatePath, root) {
   const normalizedRoot = root.replace(/\\/g, "/").replace(/\/+$/, "");
@@ -7176,21 +7205,43 @@ function createFileWatcher(state) {
   let closed = false;
   const pendingChanges = new Map;
   const suppressInitialExternalAdds = new Set;
+  const settledWrites = new Map;
+  let immediatePending = false;
   function scheduleRebuild() {
     if (closed)
       return;
     if (state.rebuildTimer)
       clearTimeout(state.rebuildTimer);
-    state.rebuildTimer = setTimeout(runRebuild, DEBOUNCE.FILE_WATCH);
-  }
-  function recordChange(event, filePath2) {
+    const timer = setTimeout(() => {
+      if (state.rebuildTimer === timer)
+        state.rebuildTimer = null;
+      runRebuild();
+    }, DEBOUNCE.FILE_WATCH);
+    state.rebuildTimer = timer;
+  }
+  async function recordChange(event, filePath2) {
     if (closed)
       return;
-    debug(`File ${event}: ${filePath2}`);
-    pendingChanges.set(path10.resolve(filePath2), event);
+    const target = path10.resolve(filePath2);
+    const settled = settledWrites.get(target);
+    if (settled && event !== "unlink" && Date.now() <= settled.expiresAt) {
+      const diskContent = await fsp4.readFile(target, "utf8").catch(() => null);
+      if (closed)
+        return;
+      if (settledWrites.get(target) === settled && diskContent === settled.content) {
+        debug(`Suppressed settled-write watcher echo: ${target}`);
+        return;
+      }
+    }
+    if (settledWrites.get(target) === settled)
+      settledWrites.delete(target);
+    debug(`File ${event}: ${target}`);
+    pendingChanges.set(target, event);
     scheduleRebuild();
   }
-  watcher.on("all", recordChange);
+  watcher.on("all", (event, filePath2) => {
+    recordChange(event, filePath2);
+  });
   externalWatcher.on("all", (event, filePath2) => {
     const target = path10.resolve(filePath2);
     if (!desiredExternals.has(target))
@@ -7199,6 +7250,43 @@ function createFileWatcher(state) {
       return;
     recordChange(event, target);
   });
+  function isWatchedSource(target) {
+    const rel = path10.relative(inputResolved, target);
+    const inProject = rel === "" || rel !== ".." && !rel.startsWith(`..${path10.sep}`) && !path10.isAbsolute(rel);
+    if (inProject)
+      return !isIgnoredWatchPath(target, inputResolved);
+    return desiredExternals.has(target);
+  }
+  function acceptSettledWrite(target, writtenContent) {
+    const settled = { content: writtenContent, expiresAt: Date.now() + 2000 };
+    settledWrites.set(target, settled);
+    const expiry = setTimeout(() => {
+      if (settledWrites.get(target) === settled)
+        settledWrites.delete(target);
+    }, 2000);
+    expiry.unref?.();
+    pendingChanges.set(target, "change");
+    immediatePending = true;
+    if (state.rebuildTimer) {
+      clearTimeout(state.rebuildTimer);
+      state.rebuildTimer = null;
+    }
+    if (!state.isRebuilding)
+      runRebuild();
+  }
+  state.notifySettledWrite = (filePath2, writtenContent) => {
+    if (closed)
+      return;
+    const target = path10.resolve(filePath2);
+    if (isWatchedSource(target)) {
+      acceptSettledWrite(target, writtenContent);
+      return;
+    }
+    syncQueue.then(() => {
+      if (!closed && isWatchedSource(target))
+        acceptSettledWrite(target, writtenContent);
+    });
+  };
   let watchedExternalRoots = new Set;
   let syncQueue = Promise.resolve();
   function syncExternalWatches() {
@@ -7250,10 +7338,15 @@ function createFileWatcher(state) {
   async function runRebuild() {
     if (closed || state.isRebuilding)
       return;
+    if (state.rebuildTimer) {
+      clearTimeout(state.rebuildTimer);
+      state.rebuildTimer = null;
+    }
     const changes = [...pendingChanges.entries()];
     pendingChanges.clear();
     if (changes.length === 0)
       return;
+    immediatePending = false;
     state.isRebuilding = true;
     let resolveInFlight;
     const inFlight = new Promise((resolve9) => {
@@ -7273,8 +7366,14 @@ function createFileWatcher(state) {
       await generateAndWriteHtml(inputResolved, state.tempDir, updatedConfig, state.cssAssets);
       if (closed)
         return;
-      state.previewServer?.broadcastReload();
-      info(changes.length > 1 ? `Preview updated (${changes.length} files changed — full reload)` : "Preview updated");
+      const decision = decideBroadcast(describeChanges(changes, inputResolved), changes.length, incrementalPreviewEnabled());
+      if (decision.kind === "chapter-splice") {
+        state.previewServer?.broadcastContentUpdate(decision.chapterId);
+        info(`Chapter updated: ${decision.relativePath}`);
+      } else {
+        state.previewServer?.broadcastReload();
+        info(changes.length > 1 ? `Preview updated (${changes.length} files changed — full reload)` : "Preview updated");
+      }
     } catch (err) {
       error("Failed to regenerate preview:", err);
     } finally {
@@ -7282,13 +7381,19 @@ function createFileWatcher(state) {
       resolveInFlight();
       if (state.rebuildPromise === inFlight)
         state.rebuildPromise = null;
-      if (!closed && pendingChanges.size > 0)
-        scheduleRebuild();
+      if (!closed && pendingChanges.size > 0) {
+        if (immediatePending)
+          runRebuild();
+        else
+          scheduleRebuild();
+      }
     }
   }
   const closeBookWatcher = watcher.close.bind(watcher);
   watcher.close = async () => {
     closed = true;
+    state.notifySettledWrite = null;
+    settledWrites.clear();
     await syncQueue.catch(() => {});
     await state.rebuildPromise?.catch(() => {});
     await externalWatcher.close();
@@ -7441,6 +7546,7 @@ function createServerState(inputPath, tempDir, config, options) {
     rebuildTimer: null,
     isRebuilding: false,
     rebuildPromise: null,
+    notifySettledWrite: null,
     previewServer: null,
     isShuttingDown: false,
     tempDir,
@@ -7453,11 +7559,13 @@ function createServerState(inputPath, tempDir, config, options) {
 // src/preview/http-server.ts
 import http2 from "node:http";
 import net from "node:net";
+import { randomUUID } from "node:crypto";
 import { readFile as readFile20, stat as stat4 } from "node:fs/promises";
 import path12 from "path";
 import { WebSocket, WebSocketServer } from "ws";
 var HMR_PATH = "/__gutterpress-hmr";
-var HMR_CLIENT_SNIPPET = `
+function hmrClientSnippet(initialRevision, instanceId) {
+  return `
 <script>
   (function () {
     // When loaded by the preview SHELL (iframe double-buffer), the shell loads us
@@ -7467,6 +7575,10 @@ var HMR_CLIENT_SNIPPET = `
     // for scroll-anchor and reload.
     if (/[?&]gutterpressshell=1/.test(location.search)) return;
   var ANCHOR_KEY = 'gutterpress-scroll-anchor';
+  var appliedRevision = ${initialRevision};
+  var appliedInstance = ${JSON.stringify(instanceId)};
+  var readyToAcknowledge = false;
+  var reloadRequested = false;
 
     // Find the element nearest the top of the viewport that carries a source
     // line (markdown-it-source-map emits data-source-line on block elements).
@@ -7517,7 +7629,13 @@ var HMR_CLIENT_SNIPPET = `
           }
         }
         if (el) {
-          window.scrollBy(0, el.getBoundingClientRect().top - a.offset);
+          window.scrollBy({
+            top: el.getBoundingClientRect().top - a.offset,
+            behavior: 'instant'
+          });
+          if (window.previewAPI && typeof window.previewAPI.refresh === 'function') {
+            window.previewAPI.refresh();
+          }
           return;
         }
         if (tries++ < 240) setTimeout(attempt, 25); // wait for pagination
@@ -7525,44 +7643,100 @@ var HMR_CLIENT_SNIPPET = `
     }
     var restored = false;
     function restoreOnce() { if (restored) return; restored = true; restoreAnchor(); }
+    function finishInitialRender() {
+      restoreOnce();
+      readyToAcknowledge = true;
+      acknowledge();
+    }
     // CRITICAL ordering: when the Paged.js polyfill is present it re-paginates on
-    // load and its PagedConfig.after calls scrollTo(0,0) THEN fires
+    // load and its PagedConfig.after scrolls to the document start THEN fires
     // 'renderingComplete'. So in engine mode we MUST wait for that event —
-    // restoring earlier would be wiped by the scrollTo(0,0). In static mode (no
+    // restoring earlier would be wiped by that initial scroll. In static mode (no
     // engine) the content is final immediately, so restore right after load.
-    var hasEngine = !!document.querySelector('script[src*="paged.polyfill"], script[src*="pagedjs"]');
-    window.addEventListener('renderingComplete', restoreOnce);
+    var hasEngine = !!document.querySelector('script[src*="paged.polyfill"]');
+    window.addEventListener('renderingComplete', finishInitialRender);
     if (!hasEngine) {
       if (document.readyState === 'loading') {
-        document.addEventListener('DOMContentLoaded', function () { setTimeout(restoreOnce, 50); });
+        document.addEventListener('DOMContentLoaded', function () { setTimeout(finishInitialRender, 50); });
       } else {
-        setTimeout(restoreOnce, 50);
+        setTimeout(finishInitialRender, 50);
       }
     }
-    setTimeout(restoreOnce, 10000); // safety net if renderingComplete never fires
+    var ws = null;
+    var reconnectTimer = null;
+    var reconnectDelay = 250;
+    var stopped = false;
 
-    var ws = new WebSocket(location.origin.replace(/^http/, 'ws') + '${HMR_PATH}');
-    ws.onmessage = function (e) {
-      var msg;
-      try { msg = JSON.parse(e.data); } catch (_) { return; }
-      if (msg.type === 'full-reload') {
+    function acknowledge() {
+      if (!readyToAcknowledge || !ws || ws.readyState !== 1) return;
+      try {
+        ws.send(JSON.stringify({
+          type: 'reload-applied',
+          instance: appliedInstance,
+          revision: appliedRevision
+        }));
+      } catch (_) {}
+    }
+
+    function connect() {
+      if (stopped) return;
+      ws = new WebSocket(location.origin.replace(/^http/, 'ws') + '${HMR_PATH}');
+      ws.onopen = function () {
+        reconnectDelay = 250;
+        acknowledge();
+      };
+      ws.onmessage = function (e) {
+        var msg;
+        try { msg = JSON.parse(e.data); } catch (_) { return; }
+        if (
+          msg.type !== 'reload-state' &&
+          msg.type !== 'full-reload' &&
+          msg.type !== 'content-update'
+        ) return;
+        var instance = typeof msg.instance === 'string' ? msg.instance : null;
+        var revision = Number(msg.revision);
+        if (!instance || !Number.isSafeInteger(revision) || revision < 0) return;
+        if (instance === appliedInstance && revision <= appliedRevision) {
+          acknowledge();
+          return;
+        }
+        if (reloadRequested) return;
+        reloadRequested = true;
         try { var a = captureAnchor(); if (a) sessionStorage.setItem(ANCHOR_KEY, JSON.stringify(a)); } catch (_) {}
         location.reload();
-        return;
-      }
-    };
+      };
+      ws.onclose = function () {
+        ws = null;
+        if (stopped || reconnectTimer !== null) return;
+        reconnectTimer = setTimeout(function () {
+          reconnectTimer = null;
+          connect();
+        }, reconnectDelay);
+        reconnectDelay = Math.min(reconnectDelay * 2, 5000);
+      };
+      ws.onerror = function () { try { ws.close(); } catch (_) {} };
+    }
+
+    window.addEventListener('beforeunload', function () {
+      stopped = true;
+      if (reconnectTimer !== null) clearTimeout(reconnectTimer);
+    });
+    connect();
   })();
 </script>
 `;
-var SHELL_HTML = `<!doctype html>
+}
+function shellHtml(initialRevision, instanceId) {
+  return `<!doctype html>
 <html lang="en"><head><meta charset="utf-8"><title>gutterpress preview</title>
 <style>html,body{margin:0;height:100%;background:#fff;overflow:hidden}
 iframe{position:absolute;inset:0;width:100%;height:100%;border:0;display:block}</style>
 </head><body>
 <iframe id="gutterpress-active" src="/book.html?gutterpressshell=1" title="preview"></iframe>
-<script>window.__GUTTERPRESS_HMR=${JSON.stringify(HMR_PATH)};</script>
+<script>window.__GUTTERPRESS_HMR=${JSON.stringify(HMR_PATH)};window.__GUTTERPRESS_INSTANCE=${JSON.stringify(instanceId)};window.__GUTTERPRESS_REVISION=${initialRevision};</script>
 <script src="/preview/scripts/preview-shell.js"></script>
 </body></html>`;
+}
 function probePort(port, host) {
   return new Promise((resolve9) => {
     const srv = net.createServer();
@@ -7604,13 +7778,14 @@ async function findAvailablePort(startPort, host = "127.0.0.1") {
   }
   throw new BuildError(`Could not find an available port on ${host} from ${firstPort} to ${port - 1}; all are already in use. ` + "Stop another preview server or pass --port with an available port.", undefined, { cause: lastBusyError });
 }
-function injectHmrClient(html) {
+function injectHmrClient(html, revision, instanceId) {
+  const snippet = hmrClientSnippet(revision, instanceId);
   const closingBody = html.lastIndexOf("</body>");
   if (closingBody === -1)
-    return html + HMR_CLIENT_SNIPPET;
-  return html.slice(0, closingBody) + HMR_CLIENT_SNIPPET + html.slice(closingBody);
+    return html + snippet;
+  return html.slice(0, closingBody) + snippet + html.slice(closingBody);
 }
-async function serveStatic(absPath, res, cacheControl = "no-store", extraHeaders = {}) {
+async function serveStatic(absPath, res, cacheControl = "no-store", extraHeaders = {}, hmrRevision = 0, hmrInstance = "") {
   let filePath2 = absPath;
   try {
     const s = await stat4(filePath2);
@@ -7631,7 +7806,7 @@ async function serveStatic(absPath, res, cacheControl = "no-store", extraHeaders
   }
   const isHtml = filePath2.endsWith(".html") || filePath2.endsWith(".htm");
   if (isHtml) {
-    const withHmr = injectHmrClient(data.toString("utf-8"));
+    const withHmr = injectHmrClient(data.toString("utf-8"), hmrRevision, hmrInstance);
     res.writeHead(200, { "Content-Type": "text/html; charset=utf-8", "Cache-Control": "no-store" });
     res.end(withHmr);
     return;
@@ -7650,11 +7825,88 @@ function matchesEmbedded(urlPathname) {
   return EMBEDDED_PREFIXES.some((p) => urlPathname.startsWith(p));
 }
 async function createPreviewServer(state, port) {
-  const clients = new Set;
+  const ACK_RETRY_MS = 2000;
+  const MAX_ACK_RETRIES = 95;
+  const instanceId = randomUUID();
+  let reloadRevision = 0;
+  const clients = new Map;
+  function sendRevision(ws, type, file) {
+    if (ws.readyState !== WebSocket.OPEN)
+      return;
+    try {
+      ws.send(JSON.stringify({
+        type,
+        instance: instanceId,
+        revision: reloadRevision,
+        ...file ? { file } : {}
+      }));
+    } catch {}
+  }
+  function waitForAcknowledgement(ws) {
+    const client = clients.get(ws);
+    if (!client)
+      return;
+    if (client.acknowledgedRevision >= reloadRevision) {
+      if (client.retryTimer !== null)
+        clearTimeout(client.retryTimer);
+      client.retryTimer = null;
+      client.retryAttempts = 0;
+      return;
+    }
+    if (client.retryTimer !== null)
+      return;
+    client.retryTimer = setTimeout(() => {
+      const current = clients.get(ws);
+      if (!current)
+        return;
+      current.retryTimer = null;
+      if (current.retryAttempts >= MAX_ACK_RETRIES) {
+        ws.terminate();
+        return;
+      }
+      current.retryAttempts++;
+      sendRevision(ws, "reload-state");
+      waitForAcknowledgement(ws);
+    }, ACK_RETRY_MS);
+    client.retryTimer.unref?.();
+  }
+  function removeClient(ws) {
+    const client = clients.get(ws);
+    if (client && client.retryTimer !== null)
+      clearTimeout(client.retryTimer);
+    clients.delete(ws);
+  }
   const wss = new WebSocketServer({ noServer: true });
   wss.on("connection", (ws) => {
-    clients.add(ws);
-    ws.on("close", () => clients.delete(ws));
+    clients.set(ws, { acknowledgedRevision: -1, retryAttempts: 0, retryTimer: null });
+    ws.on("message", (raw) => {
+      let message;
+      try {
+        message = JSON.parse(raw.toString());
+      } catch {
+        return;
+      }
+      if (!message || typeof message !== "object")
+        return;
+      const payload = message;
+      if (payload.type !== "reload-applied")
+        return;
+      const revision = Number(payload.revision);
+      if (payload.instance !== instanceId || !Number.isSafeInteger(revision) || revision < 0 || revision > reloadRevision)
+        return;
+      const client = clients.get(ws);
+      if (!client)
+        return;
+      client.acknowledgedRevision = Math.max(client.acknowledgedRevision, revision);
+      waitForAcknowledgement(ws);
+    });
+    ws.on("close", () => removeClient(ws));
+    ws.on("error", () => {
+      removeClient(ws);
+      ws.terminate();
+    });
+    sendRevision(ws, "reload-state");
+    waitForAcknowledgement(ws);
   });
   const server = http2.createServer(async (req, res) => {
     const url = new URL(req.url, "http://127.0.0.1");
@@ -7677,6 +7929,34 @@ async function createPreviewServer(state, port) {
       res.end("Not Found");
       return;
     }
+    if (url.pathname === "/__chapter" && req.method === "GET") {
+      const rawFile = url.searchParams.get("file");
+      const file = rawFile ? canonicalChapterId(rawFile) : "";
+      const revision = Number(url.searchParams.get("revision"));
+      const configuredFiles = state.config.source?.files;
+      if (!file || !state.currentInputPath || !incrementalPreviewEnabled() || !Number.isSafeInteger(revision) || revision !== reloadRevision || path12.extname(file).toLowerCase() !== ".md" || hasDotSegment(file) || !resolveWithinRoot(file, state.currentInputPath) || Array.isArray(configuredFiles) && configuredFiles.length > 0 && !configuredFiles.some((configured) => canonicalChapterId(configured) === file)) {
+        res.writeHead(400);
+        res.end("Bad Request");
+        return;
+      }
+      try {
+        const html = await renderChapterPreviewHtml(state.currentInputPath, file, state.config);
+        if (revision !== reloadRevision) {
+          res.writeHead(409);
+          res.end("Superseded");
+          return;
+        }
+        res.writeHead(200, {
+          "Content-Type": "text/html; charset=utf-8",
+          "Cache-Control": "no-store"
+        });
+        res.end(html);
+      } catch (error2) {
+        res.writeHead(500);
+        res.end(error2 instanceof Error ? error2.message : String(error2));
+      }
+      return;
+    }
     if (matchesEmbedded(url.pathname)) {
       if (req.headers["if-none-match"] === EMBEDDED_ETAG) {
         res.writeHead(304, { ETag: EMBEDDED_ETAG, "Cache-Control": EMBEDDED_CACHE_CONTROL });
@@ -7695,7 +7975,7 @@ async function createPreviewServer(state, port) {
     }
     if (url.pathname === "/" && incrementalPreviewEnabled()) {
       res.writeHead(200, { "Content-Type": "text/html; charset=utf-8", "Cache-Control": "no-store" });
-      res.end(SHELL_HTML);
+      res.end(shellHtml(reloadRevision, instanceId));
       return;
     }
     const pathname = url.pathname === "/" ? "/book.html" : url.pathname;
@@ -7722,7 +8002,7 @@ async function createPreviewServer(state, port) {
       res.end("Not Found");
       return;
     }
-    await serveStatic(absPath, res).catch((err) => {
+    await serveStatic(absPath, res, "no-store", {}, reloadRevision, instanceId).catch((err) => {
       if (!res.headersSent) {
         res.writeHead(500);
         res.end(`Internal Server Error: ${err.message}`);
@@ -7749,14 +8029,21 @@ async function createPreviewServer(state, port) {
     openPath(serverUrl).catch(() => {});
   }
   let stopped = false;
-  const broadcast = (payload) => {
+  const broadcastUpdate = (type, file) => {
     if (stopped)
       return;
-    const message = JSON.stringify(payload);
-    for (const ws of clients) {
-      if (ws.readyState === WebSocket.OPEN)
-        ws.send(message);
+    reloadRevision++;
+    for (const [ws] of clients) {
+      sendRevision(ws, type, file);
+      waitForAcknowledgement(ws);
+    }
+  };
+  const updateInFlight = () => {
+    for (const client of clients.values()) {
+      if (client.acknowledgedRevision < reloadRevision)
+        return true;
     }
+    return false;
   };
   return {
     port: boundPort,
@@ -7764,8 +8051,11 @@ async function createPreviewServer(state, port) {
       if (stopped)
         return;
       stopped = true;
-      for (const ws of clients)
+      for (const [ws, client] of clients) {
+        if (client.retryTimer !== null)
+          clearTimeout(client.retryTimer);
         ws.terminate();
+      }
       clients.clear();
       wss.close();
       await new Promise((resolve9) => {
@@ -7776,7 +8066,13 @@ async function createPreviewServer(state, port) {
       });
     },
     broadcastReload() {
-      broadcast({ type: "full-reload" });
+      broadcastUpdate("full-reload");
+    },
+    broadcastContentUpdate(file) {
+      if (updateInFlight())
+        broadcastUpdate("full-reload");
+      else
+        broadcastUpdate("content-update", canonicalChapterId(file));
     }
   };
 }
@@ -7829,7 +8125,10 @@ async function startPreviewServer(options) {
       }
       await shutdownServer(state);
     },
-    restart: restartPreview2
+    restart: restartPreview2,
+    notifySettledWrite: (filePath2, writtenContent) => {
+      state.notifySettledWrite?.(filePath2, writtenContent);
+    }
   };
 }
 
@@ -7840,7 +8139,7 @@ import path14 from "node:path";
 
 // src/lib/manifest-doc.ts
 import { existsSync as existsSync10 } from "node:fs";
-import { randomUUID } from "node:crypto";
+import { randomUUID as randomUUID2 } from "node:crypto";
 import { mkdir as mkdir6, open, readFile as readFile21, rename, rm as rm2 } from "node:fs/promises";
 import path13 from "node:path";
 import { parseDocument, isSeq, YAMLSeq } from "yaml";
@@ -7862,7 +8161,7 @@ async function loadManifestDoc(projectDir) {
 async function writeManifestDoc(file, doc) {
   const dir = path13.dirname(file);
   await mkdir6(dir, { recursive: true });
-  const temporary = path13.join(dir, `.${path13.basename(file)}.tmp-${process.pid}-${randomUUID()}`);
+  const temporary = path13.join(dir, `.${path13.basename(file)}.tmp-${process.pid}-${randomUUID2()}`);
   try {
     const handle = await open(temporary, "wx", 438);
     try {
@@ -8136,7 +8435,7 @@ import path16 from "node:path";
 import { isSeq as isSeq3, isMap as isMap2, isScalar as isScalar2, YAMLMap, Scalar } from "yaml";
 
 // src/lib/npm-plugin-installer.ts
-import { createHash as createHash4, randomUUID as randomUUID2, timingSafeEqual } from "node:crypto";
+import { createHash as createHash4, randomUUID as randomUUID3, timingSafeEqual } from "node:crypto";
 import { createReadStream as createReadStream2 } from "node:fs";
 import {
   lstat as lstat2,
@@ -8812,7 +9111,7 @@ async function installNpmPlugin(projectDirInput, packageSpec, options = {}) {
     }
     try {
       await lstat2(finalRoot);
-      backupRoot = `${finalRoot}.backup-${randomUUID2()}`;
+      backupRoot = `${finalRoot}.backup-${randomUUID3()}`;
       await rename2(finalRoot, backupRoot);
     } catch (error2) {
       if (error2.code !== "ENOENT")