radiant-docs 0.1.49 → 0.1.51

package/dist/index.js

@@ -36,6 +36,7 @@ var log = {
   ),
   blank: () => console.log("")
 };
+var SUPPORTED_COMMANDS = /* @__PURE__ */ new Set(["dev", "check"]);
 function getUserDocsDir() {
   return process.cwd();
 }
@@ -75,6 +76,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 +98,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 +136,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)...");
@@ -149,6 +153,7 @@ async function installDependencies(cacheDir) {
     });
     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 +184,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 +349,13 @@ ${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 --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 +368,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);
@@ -325,6 +391,10 @@ async function run() {
   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.49",
+  "version": "0.1.51",
   "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/components/SidebarGroup.astro

@@ -22,7 +22,7 @@ const currentPrefix = parentSlug ? `${parentSlug}/${groupSlug}` : groupSlug;
   <div class:list={["text-sm font-semibold mb-2 flex items-center gap-2 px-2"]}>
     {item.icon && <Icon name={item.icon} class="size-4 text-neutral-500" />}
     {item.group}
-    {item.tag && <Tag>{item.tag}</Tag>}
+    {item.tag && <Tag tag={item.tag} />}
   </div>
 
   <ul>

package/template/src/components/SidebarLink.astro

@@ -3,13 +3,13 @@ import { buildMdxPageHref, deriveTitleFromEntryId } from "../lib/utils";
 import Icon from "./ui/Icon.astro";
 import Tag from "./ui/Tag.astro";
 import { getCollection } from "astro:content";
-import { getConfig } from "../lib/validation";
+import { getConfig, type NavTag } from "../lib/validation";
 
 interface Props {
   path: string;
   groupSlug?: string;
   icon?: string | null;
-  tag?: string;
+  tag?: NavTag;
   title?: string;
 }
 
@@ -61,6 +61,6 @@ const isActive = currentPath === targetPath;
   <div class="flex items-center gap-2">
     {icon && <Icon name={icon} class="size-4 opacity-75" />}
     {text}
-    {tag && <Tag>{tag}</Tag>}
+    {tag && <Tag tag={tag} />}
   </div>
 </a>

package/template/src/components/SidebarSubgroup.astro

@@ -82,7 +82,7 @@ const containsActivePage = item.pages.some((child) => {
     <div class="flex items-center gap-2">
       {item.icon && <Icon name={item.icon} class="size-4 opacity-75" />}
       {item.group}
-      {item.tag && <Tag>{item.tag}</Tag>}
+      {item.tag && <Tag tag={item.tag} />}
     </div>
     <svg
       xmlns="http://www.w3.org/2000/svg"

package/template/src/components/sidebar/SidebarEndpointLink.astro

@@ -2,13 +2,14 @@
 import Tag from "../ui/Tag.astro";
 import { buildOpenApiEndpointHref } from "../../lib/utils";
 import { methodColors } from "../../lib/utils";
+import type { NavTag } from "../../lib/validation";
 
 interface Props {
   method: string;
   path: string;
   summary?: string;
   title?: string;
-  tag?: string;
+  tag?: NavTag;
   parentSlug?: string;
 }
 
@@ -49,6 +50,6 @@ const isActive = currentPath === targetPath;
   </span>
   <div class="flex items-center gap-2 min-w-0">
     <span>{text}</span>
-    {tag && <Tag>{tag}</Tag>}
+    {tag && <Tag tag={tag} />}
   </div>
 </a>

package/template/src/components/ui/Tag.astro

@@ -1,5 +1,67 @@
+---
+import {
+  getConfig,
+  type NavTag,
+  type ThemeColorByMode,
+} from "../../lib/validation";
+
+interface Props {
+  tag?: NavTag;
+  color?: string | ThemeColorByMode;
+}
+
+const { tag, color } = Astro.props;
+const config = await getConfig();
+
+function getTagText(value: NavTag | undefined): string | undefined {
+  if (typeof value === "string") return value;
+  return value?.text;
+}
+
+function getTagColor(
+  value: NavTag | undefined,
+): string | ThemeColorByMode | undefined {
+  if (typeof value === "object" && value !== null) {
+    return value.color;
+  }
+  return undefined;
+}
+
+function resolveColorByMode(
+  value: string | ThemeColorByMode | undefined,
+): { light: string; dark: string } | undefined {
+  if (typeof value === "string") {
+    return { light: value, dark: value };
+  }
+
+  const light = value?.light ?? value?.dark;
+  const dark = value?.dark ?? value?.light;
+  if (!light || !dark) return undefined;
+
+  return { light, dark };
+}
+
+const text = getTagText(tag);
+const configuredColor =
+  color ?? getTagColor(tag) ?? config.theme?.tag?.color ?? undefined;
+const resolvedColor = resolveColorByMode(configuredColor);
+const colorStyle = resolvedColor
+  ? `--rd-tag-color-light:${resolvedColor.light};--rd-tag-color-dark:${resolvedColor.dark};`
+  : undefined;
+---
+
 <span
-  class="text-[9px] bg-blue-100/70 text-blue-800/90 border border-blue-800/10 px-1.5 py-px rounded-full tracking-wide font-semibold shrink-0 normal-case"
+  class="rd-tag text-[9px] border px-[5px] py-[2px] rounded-full tracking-wide leading-none font-medium shrink-0"
+  style={colorStyle}
 >
-  <slot />
+  {text ? text : <slot />}
 </span>
+
+<style>
+  .rd-tag {
+    --rd-tag-color: var(--rd-tag-color-light, var(--color-theme));
+    background-color: color-mix(in oklab, var(--rd-tag-color) 8%, transparent);
+    border-color: color-mix(in oklab, var(--rd-tag-color) 0%, transparent);
+    color: color-mix(in oklab, var(--rd-tag-color) 95%, transparent);
+  }
+</style>

package/template/src/components/user/CodeBlock.astro

@@ -282,7 +282,7 @@ const renderedCodeLinesHtml = normalizedTokenLines
 >
   <div
     class:list={[
-      "w-full max-w-full min-w-0 bg-(--rd-code-surface)",
+      "w-full max-w-full min-w-0",
       parsedInCodeGroup
         ? "rounded-tr-none rounded-xl"
         : parsedFlushTop

package/template/src/components/user/ComponentPreviewBlock.astro

@@ -98,7 +98,7 @@ const isInitiallyExpanded = shouldShowAllCode || totalLineCount <= visibleLines;
       >
         <button
           type="button"
-          class="pointer-events-auto inline-flex h-8 items-center justify-center rounded-xl [corner-shape:superellipse(1.2)] border-[0.5px] border-neutral-900/10 dark:border-white/8 bg-linear-to-br from-white via-white/10 to-neutral-900/5 dark:from-white/7 dark:via-white/6 dark:to-white/2 px-3 text-sm font-medium text-neutral-600 hover:text-neutral-900 dark:text-neutral-300/90 hover:dark:text-neutral-200 transition-colors duration-200 hover:bg-neutral-50/80 cursor-pointer dark:hover:bg-neutral-700/30 shadow-[0_.5px_1px_rgba(0,0,0,0.15),0_5px_12px_-4px_rgba(0,0,0,0.08)] dark:shadow-[0_-0.5px_0px_rgba(255,255,255,0.15),0_5px_12px_-4px_rgba(0,0,0,0.6)]"
+          class="pointer-events-auto inline-flex h-8 items-center justify-center rounded-xl [corner-shape:superellipse(1.2)] border-[0.5px] border-neutral-900/10 dark:border-white/8 bg-linear-to-br from-white via-white/10 to-neutral-900/5 dark:from-white/7 dark:via-white/6 dark:to-white/2 px-3 text-sm font-medium text-neutral-600 hover:text-neutral-900 dark:text-neutral-300/90 hover:dark:text-neutral-200 transition-colors duration-200 hover:bg-neutral-50/80 cursor-pointer dark:hover:bg-neutral-700/30 shadow-[0_.5px_1px_rgba(0,0,0,0.15),0_5px_12px_-4px_rgba(0,0,0,0.08)] dark:shadow-[0_-0.5px_0px_rgba(255,255,255,0.15),0_5px_12px_-4px_rgba(0,0,0,0.18)]"
           data-rd-preview-expand
         >
           View code

package/template/src/components/user/Image.astro

@@ -114,7 +114,23 @@ function isConstrainedWidthValue(value: unknown): boolean {
   return true;
 }
 
+function toCssWidthValue(value: unknown): string | undefined {
+  if (typeof value === "number") {
+    if (!Number.isFinite(value) || value <= 0) return undefined;
+    return `${value}px`;
+  }
+
+  if (typeof value !== "string") return undefined;
+  const normalized = value.trim();
+  if (!normalized) return undefined;
+
+  return /^-?\d*\.?\d+$/.test(normalized) ? `${normalized}px` : normalized;
+}
+
 const hasCustomImageWidth = isConstrainedWidthValue(rawWidth);
+const contentWidthStyle = hasCustomImageWidth
+  ? `width: ${toCssWidthValue(rawWidth) ?? "auto"};`
+  : undefined;
 
 const slotCaptionHtml = Astro.slots.has("default")
   ? (await Astro.slots.render("default")).trim()
@@ -240,45 +256,46 @@ const hasCaption = slotCaptionHtml.length > 0;
   }"
 >
   <div
-    class="overflow-hidden rounded-[11px]"
+    class:list={["max-w-full", !hasCustomImageWidth && "w-full"]}
+    style={contentWidthStyle}
   >
-    <img
-      {...lightImageAttrs}
-      x-ref="lightImg"
-      title={title}
-      class:list={[
-        "h-auto my-0! block transition-opacity",
-        hasDarkSource && "dark:hidden",
-        zoomEnabled && "cursor-zoom-in",
-        hasCustomImageWidth ? "max-w-full" : "w-full",
-      ]}
-      :class="showZoomed ? 'opacity-0 duration-0' : 'opacity-100 duration-300'"
-      @click={zoomEnabled ? "zoom()" : undefined}
-    />
+    <div class="overflow-hidden rounded-[11px]">
+      <img
+        {...lightImageAttrs}
+        x-ref="lightImg"
+        title={title}
+        class:list={[
+          "h-auto my-0! block w-full transition-opacity",
+          hasDarkSource && "dark:hidden",
+          zoomEnabled && "cursor-zoom-in",
+        ]}
+        :class="showZoomed ? 'opacity-0 duration-0' : 'opacity-100 duration-300'"
+        @click={zoomEnabled ? "zoom()" : undefined}
+      />
+      {
+        darkImageAttrs && (
+          <img
+            {...darkImageAttrs}
+            x-ref="darkImg"
+            title={title}
+            class:list={[
+              "h-auto my-0! hidden w-full transition-opacity dark:block",
+              zoomEnabled && "cursor-zoom-in",
+            ]}
+            :class="showZoomed ? 'opacity-0 duration-0' : 'opacity-100 duration-300'"
+            @click={zoomEnabled ? "zoom()" : undefined}
+          />
+        )
+      }
+    </div>
     {
-      darkImageAttrs && (
-        <img
-          {...darkImageAttrs}
-          x-ref="darkImg"
-          title={title}
-          class:list={[
-            "h-auto my-0! hidden transition-opacity dark:block",
-            zoomEnabled && "cursor-zoom-in",
-            hasCustomImageWidth ? "max-w-full" : "w-full",
-          ]}
-          :class="showZoomed ? 'opacity-0 duration-0' : 'opacity-100 duration-300'"
-          @click={zoomEnabled ? "zoom()" : undefined}
-        />
+      hasCaption && (
+        <figcaption class="prose-rules mt-1! xs:mt-1.5! max-w-none! *:max-w-none! text-center text-xs! xs:text-sm! text-neutral-500 dark:text-neutral-400 leading-relaxed px-2">
+          <Fragment set:html={slotCaptionHtml} />
+        </figcaption>
       )
     }
   </div>
-  {
-    hasCaption && (
-      <figcaption class="prose-rules mt-1! xs:mt-1.5! max-w-none! *:max-w-none! text-center text-xs! xs:text-sm! text-neutral-500 dark:text-neutral-400 leading-relaxed px-2">
-        <Fragment set:html={slotCaptionHtml} />
-      </figcaption>
-    )
-  }
 
   {
     zoomEnabled && (

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

@@ -131,7 +131,7 @@ const INTERNAL_ONLY_COMPONENTS = new Set(["ComponentPreview"]);
 export type NavPage = {
   page: string;
   icon?: string | null;
-  tag?: string;
+  tag?: NavTag;
   title?: string;
 };
 export type NavOpenApiPageRef = {
@@ -141,14 +141,14 @@ export type NavOpenApiPageRef = {
 export type NavOpenApiPage = {
   openapi: NavOpenApiPageRef;
   title?: string;
-  tag?: string;
+  tag?: NavTag;
 };
 export type NavGroup = {
   group: string;
   pages: (string | NavPage | NavGroup | NavOpenApiPage)[];
   icon?: string | null;
   expanded?: boolean; // need to add this logic
-  tag?: string;
+  tag?: NavTag;
 };
 export type NavOpenApi = {
   source: string;
@@ -199,6 +199,16 @@ export type Logo = {
   href?: string;
   pill?: string | false;
 };
+export type ThemeColorByMode = {
+  light?: string;
+  dark?: string;
+};
+export type NavTag =
+  | string
+  | {
+      text: string;
+      color?: string | ThemeColorByMode;
+    };
 export const BASE_COLOR_OPTIONS = [
   "slate",
   "gray",
@@ -217,10 +227,6 @@ export type BaseColorByMode = {
 };
 export const DEFAULT_THEME_COLOR_LIGHT = "#171717";
 export const DEFAULT_THEME_COLOR_DARK = "#f5f5f5";
-export type ThemeColorByMode = {
-  light?: string;
-  dark?: string;
-};
 export type CardCoverTheme = {
   colors?: string[];
   colorSeed?: string;
@@ -241,15 +247,18 @@ export type CodeSyntaxThemeConfig =
 export type CodeTheme = {
   syntaxTheme?: CodeSyntaxThemeConfig;
 };
+export type TagTheme = {
+  color?: string | ThemeColorByMode;
+};
 export type DocsTheme = {
   baseColor?: BaseColorOption | BaseColorByMode;
   themeColor?: string | ThemeColorByMode;
   card?: CardTheme;
   code?: CodeTheme;
+  tag?: TagTheme;
 };
 export type AssistantIcon = {
   src?: string;
-  color?: string;
 };
 export type AssistantButtonSize = "small" | "default";
 export type AssistantButtonConfig = {
@@ -428,6 +437,71 @@ function normalizeThemeColorConfig(
   };
 }
 
+function normalizeNavTagConfig(
+  value: unknown,
+  currentPath: Path,
+  label: string,
+): NavTag | undefined {
+  if (value === undefined || value === null) return undefined;
+
+  if (typeof value === "string") {
+    const trimmedText = value.trim();
+    if (trimmedText.length === 0) {
+      throwConfigError(`${label} cannot be empty.`, currentPath);
+    }
+    return trimmedText;
+  }
+
+  checkType(value, "object", currentPath, label);
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throwConfigError(
+      `${label} must be a string or an object with text and optional color.`,
+      currentPath,
+    );
+  }
+
+  const tagConfig = value as Record<string, unknown>;
+  const allowedKeys = new Set(["text", "color"]);
+  for (const key of Object.keys(tagConfig)) {
+    if (!allowedKeys.has(key)) {
+      throwConfigError(`${label} object only supports 'text' and 'color'.`, [
+        ...currentPath,
+        key,
+      ]);
+    }
+  }
+
+  checkType(tagConfig.text, "string", [...currentPath, "text"], `${label} text`);
+  if (typeof tagConfig.text !== "string") {
+    throwConfigError(`${label} text must be a string.`, [
+      ...currentPath,
+      "text",
+    ]);
+  }
+
+  const trimmedText = tagConfig.text.trim();
+  if (trimmedText.length === 0) {
+    throwConfigError(`${label} text cannot be empty.`, [
+      ...currentPath,
+      "text",
+    ]);
+  }
+
+  const color =
+    tagConfig.color !== undefined
+      ? normalizeThemeColorConfig(
+          tagConfig.color,
+          [...currentPath, "color"],
+          `${label} color`,
+        )
+      : undefined;
+
+  return {
+    text: trimmedText,
+    ...(color !== undefined ? { color } : {}),
+  };
+}
+
 function normalizeHexColorArray(
   value: unknown,
   currentPath: Path,
@@ -909,6 +983,7 @@ async function validateNavigationNode(
     checkType(item.expanded, "boolean", [...path, "expanded"], "Expanded");
 
     validateIcon(item.icon, [...path, "icon"]);
+    item.tag = normalizeNavTagConfig(item.tag, [...path, "tag"], "Group tag");
 
     // Check if pages array exists and validate children
     if (!item.pages)
@@ -947,6 +1022,7 @@ async function validateNavigationNode(
 
     // Validate optional title
     checkType(item.title, "string", [...path, "title"], "Page title");
+    item.tag = normalizeNavTagConfig(item.tag, [...path, "tag"], "Page tag");
 
     // Check D.2/D.3: Page cannot have group properties
     if ("expanded" in item)
@@ -971,7 +1047,11 @@ async function validateNavigationNode(
 
     await validateNavOpenApiPage(item.openapi, [...path, "openapi"]);
     checkType(item.title, "string", [...path, "title"], "Open API page title");
-    checkType(item.tag, "string", [...path, "tag"], "Open API page tag");
+    item.tag = normalizeNavTagConfig(
+      item.tag,
+      [...path, "tag"],
+      "Open API page tag",
+    );
 
     if ("expanded" in item)
       throwConfigError("Open API page items cannot have 'expanded'.", [
@@ -1855,6 +1935,37 @@ function validateTheme(theme: DocsConfig["theme"]): void {
     }
   }
 
+  if (theme.tag !== undefined) {
+    checkType(theme.tag, "object", ["theme", "tag"], "Theme tag");
+    if (
+      typeof theme.tag !== "object" ||
+      theme.tag === null ||
+      Array.isArray(theme.tag)
+    ) {
+      throwConfigError("Theme tag must be an object.", ["theme", "tag"]);
+    }
+
+    const tagTheme = theme.tag as TagTheme & Record<string, unknown>;
+    const allowedTagKeys = new Set(["color"]);
+    for (const key of Object.keys(tagTheme)) {
+      if (!allowedTagKeys.has(key)) {
+        throwConfigError("Theme tag configuration only supports 'color'.", [
+          "theme",
+          "tag",
+          key,
+        ]);
+      }
+    }
+
+    if (tagTheme.color !== undefined) {
+      tagTheme.color = normalizeThemeColorConfig(
+        tagTheme.color,
+        ["theme", "tag", "color"],
+        "Theme tag color",
+      );
+    }
+  }
+
   if (theme.card !== undefined) {
     checkType(theme.card, "object", ["theme", "card"], "Theme card");
     if (
@@ -2293,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"],
     );
   }
@@ -2320,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 {