kss-modern 1.3.0-beta.0 → 1.3.0-beta.2

package/README.md

@@ -9,7 +9,7 @@ A modern, KSS-compatible styleguide generator. Parses KSS comment blocks from CS
 - Pug template support via worker thread pool
 - Color palette and icon gallery documentation
 - Figma embed integration with light/dark theme sync
-- Accessibility auditing (axe-core) and HTML validation
+- Accessibility auditing (axe-core) and HTML validation, per component or page-wide via `window.kssAudit()` for CI and AI agents
 - Markdown descriptions with custom components (alerts, accordions)
 - Dark mode with three-way toggle (System/Light/Dark)
 - Global search, keyboard navigation, and "Open in Editor" links

package/dist/node/lib/index.d.mts

@@ -202,7 +202,7 @@ type StyleguideChange = {
     type: 'structural';
 } | {
     type: 'markup';
-    file: string;
+    files: string[];
     sections: string[];
 };
 /**

package/dist/node/lib/index.d.ts

@@ -202,7 +202,7 @@ type StyleguideChange = {
     type: 'structural';
 } | {
     type: 'markup';
-    file: string;
+    files: string[];
     sections: string[];
 };
 /**

package/dist/node/lib/index.mjs

@@ -16,11 +16,11 @@ import githubLightDefault from '@shikijs/themes/github-light-default';
 import MarkdownItAsync from 'markdown-it-async';
 import { createHighlighterCore } from 'shiki/core';
 import { createJavaScriptRegexEngine } from 'shiki/engine/javascript';
+import { existsSync, readFileSync } from 'node:fs';
 import os from 'node:os';
 import { Worker } from 'node:worker_threads';
 import fs$1 from 'node:fs/promises';
 import { objectEntries } from '@antfu/utils';
-import { readFileSync } from 'node:fs';
 import chokidar from 'chokidar';
 import 'pug';
 import 'consola';
@@ -217,6 +217,9 @@ function escape(str) {
   return String(str).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
 }
 const when = (condition, content) => condition ? content() : "";
+function attrs(obj) {
+  return Object.entries(obj).filter(([, value]) => value !== null && value !== void 0 && value !== false).map(([key, value]) => value === true ? key : `${key}="${value}"`).join(" ");
+}
 
 const alertRenderer = (bodyContent, props) => {
   const type = props.type || "info";
@@ -390,7 +393,7 @@ function shiftHeadingLevels(markdownContent, rootHeadingLevel) {
   }
   return markdownContent;
 }
-async function parseMarkdown(data) {
+function getMarkdownRenderer() {
   if (!md) {
     md = MarkdownItAsync({ linkify: true, typographer: true });
     md.use(markdownItComponent, {
@@ -411,6 +414,29 @@ async function parseMarkdown(data) {
       )
     );
   }
+  return md;
+}
+const RENDER_CACHE_MAX_ENTRIES = 2e3;
+const renderCache = /* @__PURE__ */ new Map();
+async function renderMarkdownCached(source) {
+  const cached = renderCache.get(source);
+  if (cached !== void 0) {
+    return cached;
+  }
+  const promise = getMarkdownRenderer().renderAsync(source);
+  renderCache.set(source, promise);
+  promise.catch(() => {
+    if (renderCache.get(source) === promise)
+      renderCache.delete(source);
+  });
+  if (renderCache.size > RENDER_CACHE_MAX_ENTRIES) {
+    const oldest = renderCache.keys().next().value;
+    if (oldest !== void 0 && oldest !== source)
+      renderCache.delete(oldest);
+  }
+  return promise;
+}
+async function parseMarkdown(data) {
   if ("filePath" in data) {
     const doesFileExist = fs.existsSync(data.filePath);
     if (!doesFileExist) {
@@ -419,12 +445,12 @@ async function parseMarkdown(data) {
     }
     let fileContent = await fs.readFile(data.filePath, "utf8");
     fileContent = shiftHeadingLevels(fileContent, data.rootHeadingLevel);
-    const parsedMarkdown = await md.renderAsync(fileContent);
+    const parsedMarkdown = await renderMarkdownCached(fileContent);
     return parsedMarkdown;
   } else {
     let fileContent = data.markdownContent.replace("Markdown:", "");
     fileContent = shiftHeadingLevels(fileContent, data.rootHeadingLevel);
-    return await md.renderAsync(fileContent);
+    return await renderMarkdownCached(fileContent);
   }
 }
 
@@ -1038,8 +1064,17 @@ function getPugDependencyGraph() {
 }
 const __filename$1 = fileURLToPath(import.meta.url);
 const __dirname$1 = path.dirname(__filename$1);
-const workerFilePath = __dirname$1.includes("dist/") ? "./pug/worker.mjs" : "./worker.ts";
-const workerFilePathResolved = path.resolve(__dirname$1, workerFilePath);
+function resolveWorkerFile() {
+  const candidates = ["./worker.ts", "./worker.mjs", "./pug/worker.mjs"];
+  for (const candidate of candidates) {
+    const resolved = path.resolve(__dirname$1, candidate);
+    if (existsSync(resolved))
+      return resolved;
+  }
+  return void 0;
+}
+const workerFilePathResolved = resolveWorkerFile();
+let warnedMissingWorker = false;
 const slots = Array.from({ length: MAX_POOL_SIZE }, () => ({ tail: Promise.resolve(), active: 0 }));
 const allWorkers = /* @__PURE__ */ new Set();
 function slotIndexFor(id) {
@@ -1051,6 +1086,8 @@ function slotIndexFor(id) {
   return (hash >>> 0) % MAX_POOL_SIZE;
 }
 function spawnWorker(index) {
+  if (!workerFilePathResolved)
+    throw new Error("pug compile worker file could not be located");
   const worker = new Worker(workerFilePathResolved, { name: `pug-worker-${index}` });
   allWorkers.add(worker);
   return worker;
@@ -1185,7 +1222,11 @@ async function compileIds(mode, contentDir, repository, ids) {
   if (misses.length === 0)
     return clonedRepository;
   const errors = [];
-  const useInline = mode === "development" && misses.length <= INLINE_THRESHOLD;
+  if (!workerFilePathResolved && misses.length > INLINE_THRESHOLD && !warnedMissingWorker) {
+    warnedMissingWorker = true;
+    logger.warn("Pug compile worker not found; compiling markup on the main thread. Rebuilds stay correct but are slower.");
+  }
+  const useInline = !workerFilePathResolved || mode === "development" && misses.length <= INLINE_THRESHOLD;
   if (useInline) {
     await Promise.all(misses.map((id) => compileInline(mode, contentDir, clonedRepository, id, errors)));
   } else {
@@ -1209,6 +1250,66 @@ async function compilePugMarkupIncremental(mode, contentDir, repository, ids) {
   return compileIds(mode, contentDir, repository, wanted);
 }
 
+function createRebuildQueue(handlers) {
+  let isRunning = false;
+  let isStructuralPending = false;
+  const pendingMarkupFiles = /* @__PURE__ */ new Set();
+  let idleResolvers = [];
+  const hasPendingWork = () => isStructuralPending || pendingMarkupFiles.size > 0;
+  const releaseIdleWaiters = () => {
+    const resolvers = idleResolvers;
+    idleResolvers = [];
+    resolvers.forEach((resolve) => resolve());
+  };
+  const runNext = async () => {
+    if (isStructuralPending) {
+      isStructuralPending = false;
+      pendingMarkupFiles.clear();
+      await handlers.onStructural();
+      return;
+    }
+    const changedFiles = [...pendingMarkupFiles];
+    pendingMarkupFiles.clear();
+    await handlers.onMarkup(changedFiles);
+  };
+  const drain = async () => {
+    if (isRunning)
+      return;
+    isRunning = true;
+    try {
+      while (hasPendingWork()) {
+        try {
+          await runNext();
+        } catch (error) {
+          handlers.onError?.(error);
+        }
+      }
+    } finally {
+      isRunning = false;
+      releaseIdleWaiters();
+    }
+  };
+  return {
+    requestStructural: () => {
+      isStructuralPending = true;
+      void drain();
+    },
+    requestMarkup: (changedFiles) => {
+      for (const file of changedFiles) {
+        pendingMarkupFiles.add(file);
+      }
+      void drain();
+    },
+    whenIdle: () => {
+      if (!isRunning && !hasPendingWork())
+        return Promise.resolve();
+      return new Promise((resolve) => {
+        idleResolvers.push(resolve);
+      });
+    }
+  };
+}
+
 const TRANSIENT_FS_ERROR_CODES = /* @__PURE__ */ new Set(["ENOENT", "EBUSY", "EPERM", "EACCES"]);
 function isTransientFsError(error) {
   if (typeof error !== "object" || error === null)
@@ -1253,7 +1354,7 @@ async function generateFullPageFile(data) {
           <meta name="theme-color" media="(prefers-color-scheme: light)" content="${data.theme.light}">
           <meta name="theme-color" media="(prefers-color-scheme: dark)" content="${data.theme.dark}">
       ` : `<meta name="theme-color" content="${data.theme}">`}
-    <script type="module" src="/styleguide-assets/fullpage-DpAT8aw3.js"><\/script>
+    <script type="module" src="/styleguide-assets/fullpage-D-fU_bAa.js"><\/script>
     ${computedStyleTags}
 </head>
 <body${data.page.bodyclass ? ` class="${data.page.bodyclass}"` : ""}>
@@ -1265,6 +1366,9 @@ async function generateFullPageFile(data) {
   await logicalWriteFile(data.filePath, content);
 }
 
+function getSectionTitleLine(section) {
+  return section.source.css.line + 1;
+}
 function getHasSectionExternalFullpage(section) {
   return section.markup.length > 0 && (section.icons === void 0 || section.icons.length === 0) && (section.colors === void 0 || section.colors.length === 0);
 }
@@ -1540,10 +1644,17 @@ function getMainContentSectionWrapper(section, html) {
     }
     return `<p class="mt-2${section.sectionLevel === "second" ? " text-xl" : ""}">${section.description}</p>`;
   };
+  const sourceAttributes = attrs({
+    "data-section-reference": sanitizeSpecialCharacters(section.id),
+    "data-source-file": sanitizeSpecialCharacters(section.source.css.file),
+    "data-source-line": getSectionTitleLine(section),
+    "data-markup-file": section.source.markup?.file ? sanitizeSpecialCharacters(section.source.markup.file) : void 0
+  });
   return `
-<section 
-  id="section-${sectionSanitizeId(section.id)}" 
+<section
+  id="section-${sectionSanitizeId(section.id)}"
   class="styleguide-section border-b px-4 py-10 border-b-styleguide-border scroll-mt-[50px] md:px-10"
+  ${sourceAttributes}
 >
     <div class="flex items-center justify-between gap-6">
         <a class="relative group" href="#section-${sectionSanitizeId(section.id)}">
@@ -1580,7 +1691,7 @@ function getMainContentRegular(section, config) {
   if (config.mode === "development" && config.launchInEditor) {
     const computedRootPath = config.launchInEditor && typeof config.launchInEditor === "object" && "rootDir" in config.launchInEditor ? config.launchInEditor.rootDir : process.cwd();
     const cssFilePath = ensureStartingSlash(path.join(computedRootPath, section.source.css.file));
-    const cssLineNumber = section.source.css.line + 1;
+    const cssLineNumber = getSectionTitleLine(section);
     openInEditorPaths.css = {
       vscode: `vscode://file//${cssFilePath}:${cssLineNumber}`,
       phpstorm: `phpstorm://open?file=${cssFilePath}&line=${cssLineNumber}`
@@ -1602,7 +1713,7 @@ function getMainContentRegular(section, config) {
   };
   const renderOpenInEditorLink = (editorType, contentType, link) => `
     <a
-        class="hidden editor-${editorType}-only @md:inline-flex items-center group/${editorType} gap-1.5 p-4 desktop-device-only cursor-pointer active:scale-90 transition hover:text-styleguide-highlight duration-200"
+        class="pointer-events-auto hidden editor-${editorType}-only @md:inline-flex items-center group/${editorType} gap-1.5 p-4 desktop-device-only cursor-pointer active:scale-90 transition hover:text-styleguide-highlight duration-200"
         href="${link}"
     >
         <span class="hidden @2xl:inline-block">Open ${contentType}</span>
@@ -1635,47 +1746,59 @@ function getMainContentRegular(section, config) {
         </div>
 
         <!-- Code -->
-        <details class="group @container">
-           <summary class="flex cursor-pointer justify-between items-center rounded-b-2xl px-6 text-sm font-light bg-styleguide-bg">
-                <span class="flex gap-2 items-center py-4 select-none">
-                    <svg class="h-4 w-4 group-open:rotate-90 transition-transform" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" fill="currentColor">
-                        <path fill-rule="evenodd" d="M6.22 4.22a.75.75 0 0 1 1.06 0l3.25 3.25a.75.75 0 0 1 0 1.06l-3.25 3.25a.75.75 0 0 1-1.06-1.06L8.94 8 6.22 5.28a.75.75 0 0 1 0-1.06Z" clip-rule="evenodd"/>
-                    </svg>
+        <div class="relative @container">
+          <details class="group">
+             <summary class="flex cursor-pointer items-center rounded-b-2xl px-6 text-sm font-light bg-styleguide-bg">
+                  <span class="flex gap-2 items-center py-4 select-none">
+                      <svg class="h-4 w-4 group-open:rotate-90 transition-transform" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" fill="currentColor">
+                          <path fill-rule="evenodd" d="M6.22 4.22a.75.75 0 0 1 1.06 0l3.25 3.25a.75.75 0 0 1 0 1.06l-3.25 3.25a.75.75 0 0 1-1.06-1.06L8.94 8 6.22 5.28a.75.75 0 0 1 0-1.06Z" clip-rule="evenodd"/>
+                      </svg>
+  
+                      <span class="group-open:hidden">Show code</span>
+                      <span class="group-open:block hidden">Hide code</span>
+                  </span>
+              </summary>
+  
+              <div class="border-t p-6 text-sm bg-styleguide-bg-highlight border-styleguide-border">
+                  <div
+                    id="code-fullpage-${sectionSanitizeId(section.id)}"
+                    class="overflow-x-auto w-full code-highlight"
+                    data-source-code="${encodeURIComponent(sourceCode)}"
+                    data-source-lang="html"
+                  ></div>
+              </div>
+          </details>
 
-                    <span class="group-open:hidden">Show code</span>
-                    <span class="group-open:block hidden">Hide code</span>
-                </span>
-                
-                <span class="flex items-center"> 
+            <span class="pointer-events-none absolute top-0 right-0 flex items-center pr-6 text-sm font-light">
                     ${section.figma ? `<a
-                            class="inline-flex items-center group/figma gap-1.5 p-4 desktop-device-only cursor-pointer active:scale-90 transition hover:text-styleguide-highlight duration-200" 
+                            class="pointer-events-auto inline-flex items-center group/figma gap-1.5 p-4 desktop-device-only cursor-pointer active:scale-90 transition hover:text-styleguide-highlight duration-200"
                             href="${computeFigmaExternalLink(section.figma)}"
                             target="_blank"
                         >
                             <span class="hidden @2xl:inline-block">Open in</span>
                             <span class="sr-only">Figma</span>
-                            <img 
+                            <img
                                 src="styleguide-assets/icons/figma.svg"
-                                width="600" 
-                                height="600" 
-                                class="size-4 saturate-0 group-hover/figma:saturate-100 transition" 
-                                alt="Figma Logo" 
-                                aria-hidden="true" 
+                                width="600"
+                                height="600"
+                                class="size-4 saturate-0 group-hover/figma:saturate-100 transition"
+                                alt="Figma Logo"
+                                aria-hidden="true"
                             >
                         </a>` : ""}
-                
+
                       ${openInEditorPaths.html ? `
                             ${renderOpenInEditorLink("phpstorm", openInEditorPaths.html.phpstorm.includes(".pug") ? "Pug" : "HTML", openInEditorPaths.html.phpstorm)}
                             ${renderOpenInEditorLink("vscode", openInEditorPaths.html.phpstorm.includes(".pug") ? "Pug" : "HTML", openInEditorPaths.html.vscode)}
                           ` : ""}
-                          
+
                       ${openInEditorPaths.css ? `
                             ${renderOpenInEditorLink("phpstorm", "CSS", openInEditorPaths.css.phpstorm)}
                             ${renderOpenInEditorLink("vscode", "CSS", openInEditorPaths.css.vscode)}
                           ` : ""}
 
                     <button
-                        class="inline-flex items-center gap-1.5 p-4 cursor-pointer active:scale-90 transition hover:text-styleguide-highlight duration-200" 
+                        class="pointer-events-auto inline-flex items-center gap-1.5 p-4 cursor-pointer active:scale-90 transition hover:text-styleguide-highlight duration-200"
                         type="button"
                         data-clipboard-value="${encodeURIComponent(sourceCode)}"
                         data-clipboard-uri-encoded="true"
@@ -1690,7 +1813,7 @@ function getMainContentRegular(section, config) {
                     </button>
 
                     <button
-                        class="inline-flex items-center gap-1.5 p-4 cursor-pointer active:scale-90 transition hover:text-styleguide-highlight duration-200" 
+                        class="pointer-events-auto inline-flex items-center gap-1.5 p-4 cursor-pointer active:scale-90 transition hover:text-styleguide-highlight duration-200"
                         type="button"
                         data-code-audit-iframe="preview-fullpage-${sectionSanitizeId(section.id)}"
                         aria-controls="code-audit-dialog"
@@ -1699,10 +1822,10 @@ function getMainContentRegular(section, config) {
                         <svg class="h-4" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 122.88 122.88" aria-hidden="true"><title>accessibility</title><path fill="currentcolor" d="M61.44,0A61.46,61.46,0,1,1,18,18,61.21,61.21,0,0,1,61.44,0Zm-.39,74.18L52.1,98.91a4.94,4.94,0,0,1-2.58,2.83A5,5,0,0,1,42.7,95.5l6.24-17.28a26.3,26.3,0,0,0,1.17-4,40.64,40.64,0,0,0,.54-4.18c.24-2.53.41-5.27.54-7.9s.22-5.18.29-7.29c.09-2.63-.62-2.8-2.73-3.3l-.44-.1-18-3.39A5,5,0,0,1,27.08,46a5,5,0,0,1,5.05-7.74l19.34,3.63c.77.07,1.52.16,2.31.25a57.64,57.64,0,0,0,7.18.53A81.13,81.13,0,0,0,69.9,42c.9-.1,1.75-.21,2.6-.29l18.25-3.42A5,5,0,0,1,94.5,39a5,5,0,0,1,1.3,7,5,5,0,0,1-3.21,2.09L75.15,51.37c-.58.13-1.1.22-1.56.29-1.82.31-2.72.47-2.61,3.06.08,1.89.31,4.15.61,6.51.35,2.77.81,5.71,1.29,8.4.31,1.77.6,3.19,1,4.55s.79,2.75,1.39,4.42l6.11,16.9a5,5,0,0,1-6.82,6.24,4.94,4.94,0,0,1-2.58-2.83L63,74.23,62,72.4l-1,1.78Zm.39-53.52a8.83,8.83,0,1,1-6.24,2.59,8.79,8.79,0,0,1,6.24-2.59Zm36.35,4.43a51.42,51.42,0,1,0,15,36.35,51.27,51.27,0,0,0-15-36.35Z"/></svg>
                         <span class="hidden md:inline-block">Audit</span>
                     </button>
-                    
+
                     ${getHasSectionExternalFullpage(section) ? `
                        <a
-                            class="hidden [.styleguide-section--large_&]:inline-block -mr-2 px-2 py-4 group/externallink hover:text-styleguide-highlight focus:text-styleguide-highlight"
+                            class="pointer-events-auto hidden [.styleguide-section--large_&]:inline-block -mr-2 px-2 py-4 group/externallink hover:text-styleguide-highlight focus:text-styleguide-highlight"
                             href="/${section.fullpageFileName}"
                             target="_blank"
                             title="Open ${section.header} in fullpage"
@@ -1714,17 +1837,7 @@ function getMainContentRegular(section, config) {
                       </a>
                     ` : ""}
                 </span>
-            </summary>
-
-            <div class="border-t p-6 text-sm bg-styleguide-bg-highlight border-styleguide-border">
-                <div 
-                  id="code-fullpage-${sectionSanitizeId(section.id)}" 
-                  class="overflow-x-auto w-full code-highlight"
-                  data-source-code="${encodeURIComponent(sourceCode)}"
-                  data-source-lang="html"
-                ></div>
-            </div>
-        </details>
+        </div>
     </div>
     
     ${section.modifiers?.length > 0 ? `
@@ -2060,7 +2173,7 @@ async function generatePreviewFile(data) {
           <meta name="theme-color" media="(prefers-color-scheme: light)" content="${data.theme.light}">
           <meta name="theme-color" media="(prefers-color-scheme: dark)" content="${data.theme.dark}">
       ` : `<meta name="theme-color" content="${data.theme}">`}
-    <link rel="stylesheet" type="text/css" href="/styleguide-assets/kss-modern-Bw6-exnr.css">
+    <link rel="stylesheet" type="text/css" href="/styleguide-assets/kss-modern-BJ971T05.css">
     <script>
   //#region client/lib/iframe-resize.ts
 var e = [
@@ -2223,7 +2336,7 @@ document.addEventListener("DOMContentLoaded", () => {
 //#endregion
 ;
 <\/script>
-    <script type="module" src="/styleguide-assets/preview-BNQ_kTZ_.js"><\/script>
+    <script type="module" src="/styleguide-assets/preview-DEipbLLB.js"><\/script>
     <link rel="preload" href="/styleguide-assets/fonts/geist-mono-latin-400-normal.woff2" as="font" type="font/woff2" crossorigin="anonymous">
     <link rel="preload" href="/styleguide-assets/fonts/geist-mono-latin-600-normal.woff2" as="font" type="font/woff2" crossorigin="anonymous">
     <link rel="preload" href="/styleguide-assets/fonts/geist-mono-latin-300-normal.woff2" as="font" type="font/woff2" crossorigin="anonymous">
@@ -2278,6 +2391,26 @@ document.addEventListener("DOMContentLoaded", () => {
   await logicalWriteFile(data.filePath, content);
 }
 
+function batchDebounce(fn, windowMs) {
+  let timer;
+  let buffer = [];
+  return (item) => {
+    buffer.push(item);
+    if (timer !== void 0) {
+      clearTimeout(timer);
+    }
+    timer = setTimeout(() => {
+      const batch = buffer;
+      buffer = [];
+      timer = void 0;
+      fn(batch);
+    }, windowMs);
+  };
+}
+
+const BATCH_SETTLE_MS = 300;
+const POLLING_INTERVAL_MS = 300;
+const USE_POLLING = process.env.FORCE_POLLING === "1" || existsSync("/.dockerenv") || existsSync("/run/.containerenv") || process.env.container !== void 0;
 const VALID_CSS_FILE_TYPES = [".css", ".scss", ".sass", ".less"];
 const MARKUP_FILE_TYPES = [".pug", ".html"];
 function isCssFile(filePath) {
@@ -2308,11 +2441,33 @@ function tryReadFileSync(filePath) {
     throw error;
   }
 }
+function planRebuilds(changes) {
+  const structural = changes.some((change) => change.category === "structural");
+  if (structural) {
+    return { structural: true, markupFiles: [] };
+  }
+  const markupFiles = [...new Set(
+    changes.filter((change) => change.category === "markup").map((change) => change.path)
+  )];
+  return { structural: false, markupFiles };
+}
 function watchStyleguideForChanges(watchPath, handlers) {
   if (typeof handlers.onStructuralChange !== "function" || typeof handlers.onMarkupChange !== "function") {
     throw new TypeError("styleguide watch requires onStructuralChange and onMarkupChange callbacks");
   }
   const regexFileContents = /* @__PURE__ */ new Map();
+  const dispatch = batchDebounce((changes) => {
+    const { structural, markupFiles } = planRebuilds(changes);
+    if (structural) {
+      handlers.onStructuralChange();
+      return;
+    }
+    if (markupFiles.length > 0) {
+      handlers.onMarkupChange(markupFiles);
+    }
+  }, BATCH_SETTLE_MS);
+  const requestStructural = () => dispatch({ category: "structural" });
+  const requestMarkup = (filePath) => dispatch({ category: "markup", path: path.resolve(filePath) });
   const handleCssAdd = (filePath) => {
     const contents = tryReadFileSync(filePath);
     if (contents === void 0)
@@ -2322,7 +2477,7 @@ function watchStyleguideForChanges(watchPath, handlers) {
       return;
     }
     regexFileContents.set(filePath, currentFileMatches);
-    handlers.onStructuralChange();
+    requestStructural();
   };
   const handleCssChange = (filePath) => {
     const previousFileMatches = regexFileContents.get(filePath);
@@ -2336,47 +2491,48 @@ function watchStyleguideForChanges(watchPath, handlers) {
       if (currentFileMatches === null) {
         return;
       }
-      handlers.onStructuralChange();
+      requestStructural();
       return;
     }
     if (matchArraysEqual(previousFileMatches, currentFileMatches)) {
       return;
     }
     regexFileContents.set(filePath, currentFileMatches);
-    handlers.onStructuralChange();
+    requestStructural();
   };
   const handleCssUnlink = (filePath) => {
     regexFileContents.delete(filePath);
-    handlers.onStructuralChange();
+    requestStructural();
+  };
+  const routeEvent = (filePath, handleCss) => {
+    if (isCssFile(filePath))
+      handleCss(filePath);
+    else if (isMarkdownFile(filePath))
+      requestStructural();
+    else if (isMarkupFile(filePath))
+      requestMarkup(filePath);
   };
   const validFileTypes = [...VALID_CSS_FILE_TYPES, ".md", ...MARKUP_FILE_TYPES];
   return chokidar.watch(watchPath, {
     ignoreInitial: true,
+    usePolling: USE_POLLING,
+    interval: POLLING_INTERVAL_MS,
+    // Wait until a file has stopped being written before emitting — collapses the
+    // multi-event sequence an atomic-save editor (JetBrains, vim with
+    // backupcopy=auto) produces for a single save, and guarantees the read in the
+    // CSS handlers sees complete content rather than a half-written file.
+    awaitWriteFinish: {
+      stabilityThreshold: 100,
+      pollInterval: 20
+    },
     // @ts-expect-error - chokidar types seem to be incomplete, ignore
     ignored: (filePath, stats) => {
       return stats?.isFile() && !validFileTypes.some((type) => filePath.endsWith(type));
     }
-  }).on("add", (filePath) => {
-    if (isCssFile(filePath))
-      handleCssAdd(filePath);
-    else if (isMarkdownFile(filePath))
-      handlers.onStructuralChange();
-    else if (isMarkupFile(filePath))
-      handlers.onMarkupChange(path.resolve(filePath));
-  }).on("change", (filePath) => {
-    if (isCssFile(filePath))
-      handleCssChange(filePath);
-    else if (isMarkdownFile(filePath))
-      handlers.onStructuralChange();
-    else if (isMarkupFile(filePath))
-      handlers.onMarkupChange(path.resolve(filePath));
-  }).on("unlink", (filePath) => {
-    if (isCssFile(filePath))
-      handleCssUnlink(filePath);
-    else if (isMarkdownFile(filePath))
-      handlers.onStructuralChange();
-    else if (isMarkupFile(filePath))
-      handlers.onMarkupChange(path.resolve(filePath));
+  }).on("add", (filePath) => routeEvent(filePath, handleCssAdd)).on("change", (filePath) => routeEvent(filePath, handleCssChange)).on("unlink", (filePath) => routeEvent(filePath, handleCssUnlink)).on("error", (error) => {
+    if (isTransientFsError(error))
+      return;
+    logger.error("Styleguide watcher error (ignored to keep the dev server running):", error);
   });
 }
 
@@ -2589,6 +2745,19 @@ async function buildContext(config) {
     ownerLocationById
   };
 }
+const ASSETS_MARKER_FILE = ".kss-modern-assets";
+function getAssetsBuildId(theme) {
+  return `kss-modern-BJ971T05.css
+${JSON.stringify(theme)}
+`;
+}
+async function readAssetsBuildId(markerPath) {
+  try {
+    return await fs.readFile(markerPath, "utf-8");
+  } catch {
+    return void 0;
+  }
+}
 async function copyStyleguideAssets(config) {
   const __filename = fileURLToPath(import.meta.url);
   const __dirname = path.dirname(__filename);
@@ -2600,11 +2769,16 @@ async function copyStyleguideAssets(config) {
   };
   const assetsDirectoryPath = findAssetsDirectoryPath();
   const assetsDirectoryOutputPath = path.join(config.outDir, "styleguide-assets");
-  const isAssetsDirectoryAlreadyCopied = await fs.exists(assetsDirectoryOutputPath) && (await fs.readdir(assetsDirectoryOutputPath)).length > 0;
-  if (!isAssetsDirectoryAlreadyCopied) {
-    await fs.copy(assetsDirectoryPath, assetsDirectoryOutputPath);
-    await generateFaviconFiles(assetsDirectoryOutputPath, config.theme);
+  const markerPath = path.join(assetsDirectoryOutputPath, ASSETS_MARKER_FILE);
+  const expectedBuildId = getAssetsBuildId(config.theme);
+  const currentBuildId = await readAssetsBuildId(markerPath);
+  if (currentBuildId === expectedBuildId) {
+    return;
   }
+  await fs.remove(assetsDirectoryOutputPath);
+  await fs.copy(assetsDirectoryPath, assetsDirectoryOutputPath);
+  await generateFaviconFiles(assetsDirectoryOutputPath, config.theme);
+  await fs.writeFile(markerPath, expectedBuildId);
 }
 async function buildAll(config) {
   if (config.mode === "production" && await fs.exists(config.outDir)) {
@@ -2700,35 +2874,37 @@ async function watchStyleguide(config, onChange, onError) {
   }
   let context = initialBuild.context;
   const contentDirPath = config.contentDir.endsWith("/") ? config.contentDir : `${config.contentDir}/`;
-  watchStyleguideForChanges(contentDirPath, {
-    // css/scss/md edits can change section structure -> full rebuild + fresh context
-    onStructuralChange: () => {
-      (async () => {
-        const localBuild = await buildAll(config);
-        context = localBuild.context;
-        if (onChange)
-          onChange({ type: "structural" });
-        if (onError && localBuild.errors) {
-          onError(localBuild.errors);
-        }
-      })().catch((error) => {
-        logger.error("Error during rebuild:", error);
-      });
+  const queue = createRebuildQueue({
+    // css/scss/md/yaml edits can change section structure -> full rebuild + fresh context
+    onStructural: async () => {
+      const localBuild = await buildAll(config);
+      context = localBuild.context;
+      if (onChange)
+        onChange({ type: "structural" });
+      if (onError && localBuild.errors) {
+        onError(localBuild.errors);
+      }
     },
-    // a .pug/.html source edit -> recompile + rewrite only the sections that depend on it
-    onMarkupChange: (changedFile) => {
-      (async () => {
-        const affected = getPugDependencyGraph().getAffectedSections(changedFile);
-        if (affected.length === 0)
-          return;
-        await rebuildSections(config, context, affected);
-        if (onChange)
-          onChange({ type: "markup", file: changedFile, sections: affected });
-      })().catch((error) => {
-        logger.error("Error during incremental rebuild:", error);
-      });
+    // .pug/.html source edits -> recompile + rewrite only the sections that depend on them
+    onMarkup: async (changedFiles) => {
+      const dependencyGraph = getPugDependencyGraph();
+      const affected = [...new Set(
+        changedFiles.flatMap((changedFile) => dependencyGraph.getAffectedSections(changedFile))
+      )];
+      if (affected.length === 0)
+        return;
+      await rebuildSections(config, context, affected);
+      if (onChange)
+        onChange({ type: "markup", files: changedFiles, sections: affected });
+    },
+    onError: (error) => {
+      logger.error("Error during rebuild:", error);
     }
   });
+  watchStyleguideForChanges(contentDirPath, {
+    onStructuralChange: queue.requestStructural,
+    onMarkupChange: queue.requestMarkup
+  });
 }
 
 export { buildAll, buildStyleguide, logger, parseStyleguide, rebuildSections, watchStyleguide };