radiant-docs 0.1.50 → 0.1.53

package/dist/index.js

@@ -36,11 +36,14 @@ var log = {
   ),
   blank: () => console.log("")
 };
+var SUPPORTED_COMMANDS = /* @__PURE__ */ new Set(["dev", "check", "prepare"]);
 function getUserDocsDir() {
   return process.cwd();
 }
 function getProjectHash(docsDir) {
-  return crypto.createHash("md5").update(docsDir).digest("hex").slice(0, 8);
+  const cacheKey = process.env.RADIANT_CACHE_KEY?.trim();
+  const hashInput = cacheKey ? `cache-key:${cacheKey}` : docsDir;
+  return crypto.createHash("md5").update(hashInput).digest("hex").slice(0, 8);
 }
 function getCacheDir(docsDir) {
   const projectHash = getProjectHash(docsDir);
@@ -75,6 +78,9 @@ async function getDirectoryFingerprint(dir) {
   await walk(dir);
   return hash.digest("hex");
 }
+function hasFrameworkDependencies(cacheDir) {
+  return fs.existsSync(path.join(cacheDir, "node_modules/.bin/astro"));
+}
 async function validateUserDocs(docsDir) {
   const docsJsonPath = path.join(docsDir, "docs.json");
   if (!fs.existsSync(docsJsonPath)) {
@@ -94,7 +100,7 @@ async function validateUserDocs(docsDir) {
 }
 async function setupCache(cacheDir) {
   const templateDir = getTemplateDir();
-  const nodeModulesExists = fs.existsSync(path.join(cacheDir, "node_modules"));
+  const dependenciesInstalled = hasFrameworkDependencies(cacheDir);
   const cacheExists = fs.existsSync(cacheDir);
   if (!fs.existsSync(templateDir)) {
     log.error(
@@ -132,7 +138,7 @@ async function setupCache(cacheDir) {
     log.success("Framework copied to cache.");
     return true;
   }
-  return !nodeModulesExists;
+  return !dependenciesInstalled;
 }
 async function installDependencies(cacheDir) {
   log.info("Installing dependencies (first run only)...");
@@ -142,13 +148,15 @@ async function installDependencies(cacheDir) {
   }
   log.info(`Cache location: ${cacheDir}`);
   try {
-    execSync("npm install --silent --no-fund --no-audit", {
+    const installCommand = fs.existsSync(path.join(cacheDir, "package-lock.json")) ? "npm ci --silent --no-fund --no-audit" : "npm install --silent --no-fund --no-audit";
+    execSync(installCommand, {
       cwd: cacheDir,
       stdio: "pipe",
       env: process.env
     });
     log.success("Dependencies installed.");
   } catch (error) {
+    await fs.remove(path.join(cacheDir, "node_modules"));
     log.error("Failed to install dependencies.");
     log.error(`Error details: ${error.message}`);
     throw error;
@@ -179,6 +187,66 @@ async function runAstroSync(cacheDir) {
   } catch {
   }
 }
+function toCommandOutput(value) {
+  if (!value) return "";
+  if (Buffer.isBuffer(value)) return value.toString("utf-8");
+  return String(value);
+}
+function getCommandOutput(error) {
+  return [
+    toCommandOutput(error?.stdout),
+    toCommandOutput(error?.stderr),
+    toCommandOutput(error?.message)
+  ].filter(Boolean).join("\n");
+}
+function extractUserErrors(output) {
+  const errors = [];
+  for (const line of output.split("\n")) {
+    if (!line.includes("[USER_ERROR]")) continue;
+    const message = line.split("[USER_ERROR]:")[1]?.trim() || line.trim();
+    if (message && !errors.includes(message)) {
+      errors.push(message);
+    }
+  }
+  return errors;
+}
+function getOutputTail(output, maxLines = 40) {
+  return output.split("\n").map((line) => line.trim()).filter(Boolean).slice(-maxLines).join("\n");
+}
+function runFrameworkCheck(cacheDir) {
+  log.info("Checking documentation...");
+  try {
+    execSync("npm run check", {
+      cwd: cacheDir,
+      stdio: "pipe",
+      env: {
+        ...process.env,
+        RADIANT_CHECK: "1"
+      },
+      encoding: "utf-8"
+    });
+    log.success("Documentation check passed.");
+  } catch (error) {
+    const output = getCommandOutput(error);
+    const userErrors = extractUserErrors(output);
+    log.blank();
+    log.error("Documentation check failed.");
+    if (userErrors.length > 0) {
+      log.blank();
+      for (const userError of userErrors) {
+        log.error(userError);
+      }
+    } else {
+      const outputTail = getOutputTail(output);
+      if (outputTail) {
+        log.blank();
+        console.log(outputTail);
+      }
+    }
+    log.blank();
+    process.exit(typeof error?.status === "number" ? error.status : 1);
+  }
+}
 function startDevServer(cacheDir) {
   const child = spawn("npm", ["run", "dev"], {
     cwd: cacheDir,
@@ -284,12 +352,14 @@ ${colors.bright}${colors.cyan}\u25C6 Radiant${colors.reset} v${VERSION}
 ${colors.bright}Usage:${colors.reset}
   radiant              Start the dev server
   radiant dev          Start the dev server
+  radiant check        Validate and build the docs once
+  radiant prepare      Prepare cached framework dependencies
   radiant --help       Show this help message
   radiant --version    Show version
 
 ${colors.bright}Description:${colors.reset}
   Run this command from your documentation folder (containing docs.json)
-  to preview your docs locally with hot reload.
+  to preview your docs locally with hot reload, or run a one-time check.
 `);
 }
 async function run() {
@@ -302,8 +372,8 @@ async function run() {
     console.log(VERSION);
     process.exit(0);
   }
-  const command = args[0];
-  if (command && command !== "dev") {
+  const command = args[0] || "dev";
+  if (!SUPPORTED_COMMANDS.has(command)) {
     log.error(`Unknown command: ${command}`);
     showHelp();
     process.exit(1);
@@ -316,15 +386,25 @@ async function run() {
   const docsDir = getUserDocsDir();
   const cacheDir = getCacheDir(docsDir);
   const contentDir = getContentDir(cacheDir);
-  await validateUserDocs(docsDir);
+  if (command !== "prepare") {
+    await validateUserDocs(docsDir);
+  }
   const needsInstall = await setupCache(cacheDir);
   if (needsInstall) {
     await installDependencies(cacheDir);
   }
+  if (command === "prepare") {
+    log.success("Radiant framework cache is ready.");
+    return;
+  }
   log.info("Syncing your documentation...");
   await syncContent(docsDir, contentDir);
   await runAstroSync(cacheDir);
   log.success("Content synced.");
+  if (command === "check") {
+    runFrameworkCheck(cacheDir);
+    return;
+  }
   log.info("Starting dev server...");
   const devServer = startDevServer(cacheDir);
   const watcher = watchUserContent(docsDir, contentDir, async () => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "radiant-docs",
-  "version": "0.1.50",
+  "version": "0.1.53",
   "description": "CLI tool for previewing Radiant documentation locally",
   "type": "module",
   "bin": {

package/template/astro.config.mjs

@@ -68,8 +68,13 @@ const headingAnchorContent = {
   ],
 };
 
-if (process.env.npm_lifecycle_event === "build") {
-  // Run validation for build before Astro's internal validation
+const shouldValidateDocs =
+  process.env.npm_lifecycle_event === "build" ||
+  process.env.npm_lifecycle_event === "check" ||
+  process.env.RADIANT_CHECK === "1";
+
+if (shouldValidateDocs) {
+  // Run validation before Astro's internal validation for build/check commands.
   try {
     await getConfig();
     await validateMdxContent();

package/template/package.json

@@ -5,6 +5,7 @@
   "scripts": {
     "dev": "astro dev",
     "start": "tsx runner.ts",
+    "check": "astro build",
     "prebuild": "rm -rf public/pagefind",
     "build": "astro build && node scripts/remove-assistant-for-non-pro.mjs && node scripts/generate-og-metadata.mjs && node scripts/generate-og-images.mjs && node scripts/stamp-og-image-versions.mjs && node scripts/stamp-image-versions.mjs && pagefind --site dist && node scripts/stamp-pagefind-runtime-version.mjs && node scripts/generate-proxy-allowed-origins.mjs && node scripts/generate-robots-txt.mjs",
     "preview": "astro preview",

package/template/src/components/Header.astro

@@ -77,14 +77,14 @@ const assistantHeaderButtonStyle = assistantHeaderThemeColors
   ? [
       `--assistant-header-theme-light: ${assistantHeaderThemeColors.light}`,
       `--assistant-header-theme-dark: ${assistantHeaderThemeColors.dark}`,
-      `--assistant-header-foreground-light: ${
-        config.assistant?.icon?.color ??
-        getButtonForegroundColor("light", assistantHeaderThemeColors.light)
-      }`,
-      `--assistant-header-foreground-dark: ${
-        config.assistant?.icon?.color ??
-        getButtonForegroundColor("dark", assistantHeaderThemeColors.dark)
-      }`,
+      `--assistant-header-foreground-light: ${getButtonForegroundColor(
+        "light",
+        assistantHeaderThemeColors.light,
+      )}`,
+      `--assistant-header-foreground-dark: ${getButtonForegroundColor(
+        "dark",
+        assistantHeaderThemeColors.dark,
+      )}`,
     ].join("; ")
   : "";
 

package/template/src/lib/assistant-embed-script.ts

@@ -153,18 +153,14 @@ export function getAssistantLauncherIconConfig(
     dark: getAssistantButtonColor(config, "dark"),
   };
   const iconColors = {
-    light:
-      assistantConfig?.icon?.color ??
-      getThemeForegroundColor(
-        themeColors.light,
-        getDocsBaseColorShade(config.theme, "light", "900"),
-      ),
-    dark:
-      assistantConfig?.icon?.color ??
-      getThemeForegroundColor(
-        themeColors.dark,
-        getDocsBaseColorShade(config.theme, "dark", "900"),
-      ),
+    light: getThemeForegroundColor(
+      themeColors.light,
+      getDocsBaseColorShade(config.theme, "light", "900"),
+    ),
+    dark: getThemeForegroundColor(
+      themeColors.dark,
+      getDocsBaseColorShade(config.theme, "dark", "900"),
+    ),
   };
   const icon = resolveLauncherIcon(assistantConfig?.icon?.src);
 
@@ -297,9 +293,240 @@ export function renderAssistantEmbedScript(config: DocsConfig): string {
     });
   }
 
+  function normalizePathForMatching(value) {
+    var pathname = String(value || "").trim();
+    if (!pathname) return "";
+    if (pathname === "*") return "*";
+
+    try {
+      if (/^[a-z][a-z0-9+.-]*:\\/\\//i.test(pathname)) {
+        pathname = new URL(pathname).pathname;
+      }
+    } catch {
+      // Fall back to treating the value as a path pattern.
+    }
+
+    var hashIndex = pathname.indexOf("#");
+    if (hashIndex >= 0) {
+      pathname = pathname.slice(0, hashIndex);
+    }
+
+    var queryIndex = pathname.indexOf("?");
+    if (queryIndex >= 0) {
+      pathname = pathname.slice(0, queryIndex);
+    }
+
+    if (!pathname) return "";
+    if (pathname.charAt(0) !== "/") {
+      pathname = "/" + pathname;
+    }
+
+    pathname = pathname.replace(/\\/{2,}/g, "/");
+    if (pathname.length > 1 && !pathname.endsWith("/*")) {
+      pathname = pathname.replace(/\\/+$/, "");
+    }
+
+    return pathname || "/";
+  }
+
+  function parsePathPatterns(value) {
+    var rawPatterns = [];
+
+    if (Array.isArray(value)) {
+      rawPatterns = value;
+    } else if (typeof value === "string") {
+      var trimmed = value.trim();
+      if (!trimmed) return [];
+
+      if (trimmed.charAt(0) === "[") {
+        try {
+          var parsed = JSON.parse(trimmed);
+          if (Array.isArray(parsed)) {
+            rawPatterns = parsed;
+          } else {
+            rawPatterns = [trimmed];
+          }
+        } catch {
+          rawPatterns = trimmed.split(/[\\n,]/);
+        }
+      } else {
+        rawPatterns = trimmed.split(/[\\n,]/);
+      }
+    }
+
+    var seenPatterns = {};
+    return rawPatterns
+      .map(normalizePathForMatching)
+      .filter(function (pattern) {
+        if (!pattern || seenPatterns[pattern]) return false;
+        seenPatterns[pattern] = true;
+        return true;
+      });
+  }
+
+  function escapeRegExp(value) {
+    return String(value).replace(/[|\\\\{}()[\\]^$+?.]/g, "\\\\$&");
+  }
+
+  function pathMatchesPattern(pathname, pattern) {
+    if (pattern === "*") return true;
+
+    if (pattern.endsWith("/*")) {
+      var basePath = normalizePathForMatching(pattern.slice(0, -2));
+      return pathname === basePath || pathname.startsWith(basePath + "/");
+    }
+
+    if (pattern.indexOf("*") >= 0) {
+      var patternRegex = new RegExp(
+        "^" + pattern.split("*").map(escapeRegExp).join(".*") + "$",
+      );
+      return patternRegex.test(pathname);
+    }
+
+    return pathname === pattern;
+  }
+
+  function isCurrentPathExcluded() {
+    if (!excludedPathPatterns.length) return false;
+    var pathname = normalizePathForMatching(window.location.pathname || "/");
+    return excludedPathPatterns.some(function (pattern) {
+      return pathMatchesPattern(pathname, pattern);
+    });
+  }
+
+  function parseDurationMs(value, fallbackMs) {
+    var rawValue = String(value || "").trim();
+    var match = rawValue.match(/^([0-9]*\\.?[0-9]+)(ms|s)$/);
+    if (!match) return fallbackMs;
+
+    var amount = Number.parseFloat(match[1]);
+    if (!Number.isFinite(amount)) return fallbackMs;
+
+    return match[2] === "s" ? amount * 1000 : amount;
+  }
+
+  function clearRouteVisibilityRemovalTimeout() {
+    if (!routeVisibilityRemovalTimeout) return;
+    window.clearTimeout(routeVisibilityRemovalTimeout);
+    routeVisibilityRemovalTimeout = undefined;
+  }
+
+  function unmountEmbedElements() {
+    clearRouteVisibilityRemovalTimeout();
+    setOpen(false);
+
+    if (launcherButton) {
+      launcherButton.remove();
+      launcherButton = undefined;
+    }
+
+    if (panelShell) {
+      panelShell.remove();
+      panelShell = undefined;
+    }
+
+    panelFrame = undefined;
+  }
+
+  function hideEmbedElementsForRouteExclusion() {
+    if (!panelShell && !launcherButton) {
+      return;
+    }
+
+    clearRouteVisibilityRemovalTimeout();
+    setOpen(false);
+
+    if (launcherButton) {
+      launcherButton.dataset.routeHidden = "true";
+    }
+
+    routeVisibilityRemovalTimeout = window.setTimeout(function () {
+      routeVisibilityRemovalTimeout = undefined;
+      if (isCurrentPathExcluded()) {
+        unmountEmbedElements();
+      }
+    }, routeVisibilityRemovalDelayMs);
+  }
+
+  function applyRouteVisibility() {
+    if (isCurrentPathExcluded()) {
+      hideEmbedElementsForRouteExclusion();
+      return;
+    }
+
+    mount();
+  }
+
+  function scheduleRouteVisibilityCheck() {
+    window.setTimeout(applyRouteVisibility, 0);
+  }
+
+  function installRouteVisibilityListeners() {
+    if (!excludedPathPatterns.length || routeVisibilityListenersInstalled) {
+      return;
+    }
+
+    routeVisibilityListenersInstalled = true;
+
+    if (window.history && typeof window.history.pushState === "function") {
+      originalHistoryPushState = window.history.pushState;
+      patchedHistoryPushState = function () {
+        var result = originalHistoryPushState.apply(this, arguments);
+        scheduleRouteVisibilityCheck();
+        return result;
+      };
+      window.history.pushState = patchedHistoryPushState;
+    }
+
+    if (window.history && typeof window.history.replaceState === "function") {
+      originalHistoryReplaceState = window.history.replaceState;
+      patchedHistoryReplaceState = function () {
+        var result = originalHistoryReplaceState.apply(this, arguments);
+        scheduleRouteVisibilityCheck();
+        return result;
+      };
+      window.history.replaceState = patchedHistoryReplaceState;
+    }
+
+    window.addEventListener("popstate", scheduleRouteVisibilityCheck);
+    window.addEventListener("hashchange", scheduleRouteVisibilityCheck);
+  }
+
+  function restoreRouteVisibilityListeners() {
+    if (!routeVisibilityListenersInstalled) {
+      return;
+    }
+
+    if (
+      window.history &&
+      patchedHistoryPushState &&
+      window.history.pushState === patchedHistoryPushState
+    ) {
+      window.history.pushState = originalHistoryPushState;
+    }
+
+    if (
+      window.history &&
+      patchedHistoryReplaceState &&
+      window.history.replaceState === patchedHistoryReplaceState
+    ) {
+      window.history.replaceState = originalHistoryReplaceState;
+    }
+
+    window.removeEventListener("popstate", scheduleRouteVisibilityCheck);
+    window.removeEventListener("hashchange", scheduleRouteVisibilityCheck);
+    routeVisibilityListenersInstalled = false;
+  }
+
   var docsOrigin = resolveDocsOrigin();
   var docsBasePath = resolveDocsBasePath();
   var chrome = generatedConfig.chrome || {};
+  var excludedPathPatterns = parsePathPatterns(
+    scriptDataset.excludePaths ||
+      globalConfig.excludePaths ||
+      globalConfig.excludedPaths ||
+      "",
+  );
   var zIndex = scriptDataset.zIndex || chrome.zIndex || "2147483000";
   var configuredMode =
     scriptDataset.mode ||
@@ -339,6 +566,7 @@ export function renderAssistantEmbedScript(config: DocsConfig): string {
   var panelSizeTiming = chrome.panelSizeTiming || "cubic-bezier(.22,1.18,.36,1)";
   var panelCloseDuration = chrome.panelCloseDuration || ".2s";
   var panelCloseTiming = chrome.panelCloseTiming || "cubic-bezier(.25,1,.5,1)";
+  var launcherRouteExitDurationMs = 460;
   var mobileBreakpoint = chrome.mobileBreakpoint || "640px";
   var panelFullscreenHeightBreakpoint =
     chrome.panelFullscreenHeightBreakpoint || "560px";
@@ -367,6 +595,17 @@ export function renderAssistantEmbedScript(config: DocsConfig): string {
   var panelSize = readPanelSize();
   var panelSizeTransitionTimeout;
   var isPanelFullscreen = false;
+  var routeVisibilityRemovalTimeout;
+  var routeVisibilityRemovalDelayMs =
+    Math.max(
+      parseDurationMs(panelCloseDuration, 200),
+      launcherRouteExitDurationMs,
+    ) + 80;
+  var routeVisibilityListenersInstalled = false;
+  var originalHistoryPushState;
+  var originalHistoryReplaceState;
+  var patchedHistoryPushState;
+  var patchedHistoryReplaceState;
   var systemThemeMediaQuery =
     typeof window.matchMedia === "function"
       ? window.matchMedia("(prefers-color-scheme: dark)")
@@ -508,9 +747,11 @@ export function renderAssistantEmbedScript(config: DocsConfig): string {
     style.textContent = [
       ".assistant-embed-frame{display:block;width:100%;height:100%;border:0;background:transparent;color-scheme:normal;}",
       "@keyframes assistant-embed-launcher-enter{0%{opacity:0;transform:translateY(3px) scale(.96);}46%{opacity:1;transform:translateY(0) scale(1.012);}72%{opacity:1;transform:translateY(0) scale(.998);}100%{opacity:1;transform:translateY(0) scale(1);}}",
+      "@keyframes assistant-embed-launcher-exit{0%{opacity:1;transform:translateY(0) scale(1);}28%{opacity:1;transform:translateY(0) scale(.998);}54%{opacity:1;transform:translateY(0) scale(1.012);}100%{opacity:0;transform:translateY(3px) scale(.96);}}",
       ".assistant-embed-launcher{position:fixed;display:inline-flex;align-items:center;justify-content:center;border:0;padding:0;cursor:pointer;color:var(--assistant-embed-icon-color);background:linear-gradient(to bottom,color-mix(in oklab,var(--assistant-embed-theme) 88%,white),color-mix(in oklab,var(--assistant-embed-theme) 90%,black));animation:assistant-embed-launcher-enter 460ms linear backwards;transition:transform 180ms ease,opacity 160ms ease;transform-origin:center center;}",
       ".assistant-embed-launcher:hover{opacity:.96;transform:translateY(-1px) scale(1.03);}",
       ".assistant-embed-launcher:active{transform:translateY(0) scale(.96);}",
+      ".assistant-embed-launcher[data-route-hidden='true']{pointer-events:none;animation:assistant-embed-launcher-exit 460ms linear forwards;}",
       ".assistant-embed-launcher{width:" +
         launcherSize +
         ";height:" +
@@ -883,6 +1124,10 @@ export function renderAssistantEmbedScript(config: DocsConfig): string {
   }
 
   function setOpen(nextOpen) {
+    if (nextOpen === true && isCurrentPathExcluded()) {
+      return;
+    }
+
     var wasOpen = isOpen;
     isOpen = nextOpen === true;
     setPanelOpen(isOpen);
@@ -972,6 +1217,25 @@ export function renderAssistantEmbedScript(config: DocsConfig): string {
       return;
     }
 
+    if (isCurrentPathExcluded()) {
+      hideEmbedElementsForRouteExclusion();
+      return;
+    }
+
+    clearRouteVisibilityRemovalTimeout();
+
+    if (launcherButton) {
+      delete launcherButton.dataset.routeHidden;
+    }
+
+    if (panelShell && launcherButton) {
+      return;
+    }
+
+    if (panelShell || launcherButton) {
+      unmountEmbedElements();
+    }
+
     ensureStyle();
     updatePanelLayout();
 
@@ -1063,16 +1327,12 @@ export function renderAssistantEmbedScript(config: DocsConfig): string {
     },
     destroy: function () {
       setSystemThemeListener(false);
+      restoreRouteVisibilityListeners();
       window.removeEventListener("resize", updatePanelLayout);
       if (panelSizeTransitionTimeout) {
         window.clearTimeout(panelSizeTransitionTimeout);
       }
-      if (launcherButton) {
-        launcherButton.remove();
-      }
-      if (panelShell) {
-        panelShell.remove();
-      }
+      unmountEmbedElements();
       var style = document.getElementById(styleId);
       if (style) {
         style.remove();
@@ -1082,6 +1342,7 @@ export function renderAssistantEmbedScript(config: DocsConfig): string {
   };
 
   setSystemThemeListener(themeMode === "system");
+  installRouteVisibilityListeners();
   mount();
 })();
 `;

package/template/src/lib/validation.ts

@@ -259,7 +259,6 @@ export type DocsTheme = {
 };
 export type AssistantIcon = {
   src?: string;
-  color?: string;
 };
 export type AssistantButtonSize = "small" | "default";
 export type AssistantButtonConfig = {
@@ -2405,22 +2404,19 @@ function validateAssistant(assistant: DocsConfig["assistant"]): void {
     ]);
   }
 
-  const allowedIconKeys = new Set(["src", "color"]);
+  const allowedIconKeys = new Set(["src"]);
   for (const key of Object.keys(assistant.icon)) {
     if (!allowedIconKeys.has(key)) {
       throwConfigError(
-        "Assistant icon only supports 'src' and 'color'.",
+        "Assistant icon only supports 'src'.",
         ["assistant", "icon", key],
       );
     }
   }
 
-  if (
-    assistant.icon.src === undefined &&
-    assistant.icon.color === undefined
-  ) {
+  if (assistant.icon.src === undefined) {
     throwConfigError(
-      "Assistant icon must include 'src', 'color', or both.",
+      "Assistant icon must include 'src'.",
       ["assistant", "icon"],
     );
   }
@@ -2432,13 +2428,6 @@ function validateAssistant(assistant: DocsConfig["assistant"]): void {
     );
   }
 
-  if (assistant.icon.color !== undefined) {
-    assistant.icon.color = normalizeHexColor(
-      assistant.icon.color,
-      ["assistant", "icon", "color"],
-      "Assistant icon color",
-    );
-  }
 }
 
 function validateHome(home: DocsConfig["home"]): string | undefined {