radiant-docs 0.1.62 → 0.1.64

package/template/package.json

@@ -10,18 +10,19 @@
     "preview": "astro preview",
     "astro": "astro",
     "search:index": "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 && cp -r dist/pagefind public/",
-    "shiki:publish-platform-assets": "node scripts/publish-shiki-platform-assets.mjs",
-    "shiki:publish-platform-assets:dev": "node scripts/publish-shiki-platform-assets.mjs --env-file .env --check-current",
-    "shiki:publish-platform-assets:dev:dry-run": "node scripts/publish-shiki-platform-assets.mjs --env-file .env --check-current --dry-run"
+    "shiki:assets:update": "node scripts/publish-shiki-platform-assets.mjs --prepare-only --write-current",
+    "shiki:assets:upload": "node scripts/publish-shiki-platform-assets.mjs --check-current",
+    "shiki:assets:upload:dev": "node scripts/publish-shiki-platform-assets.mjs --env-file .env --check-current"
   },
   "dependencies": {
     "@alpinejs/collapse": "^3.15.2",
     "@alpinejs/focus": "^3.15.3",
     "@alpinejs/persist": "^3.15.2",
-    "@astrojs/alpinejs": "^0.4.9",
-    "@astrojs/mdx": "^4.3.12",
-    "@astrojs/preact": "^4.1.3",
-    "@astrojs/sitemap": "^3.7.2",
+    "@astrojs/alpinejs": "^1.0.0",
+    "@astrojs/markdown-remark": "^7.2.0",
+    "@astrojs/mdx": "^7.0.0",
+    "@astrojs/preact": "^6.0.0",
+    "@astrojs/sitemap": "^3.7.3",
     "@aws-sdk/client-s3": "^3.964.0",
     "@fontsource-variable/geist": "^5.2.9",
     "@fontsource-variable/geist-mono": "^5.2.8",
@@ -37,22 +38,21 @@
     "@iconify-json/lucide": "^1.2.79",
     "@iconify-json/simple-icons": "^1.2.69",
     "@iconify/react": "^6.0.2",
-    "@jongwooo/prism-theme-github": "^1.15.1",
     "@paper-design/shaders": "^0.0.76",
     "@preact/preset-vite": "^2.10.3",
     "@readme/oas-to-snippet": "^29.3.0",
     "@resvg/resvg-js": "^2.6.2",
-    "@shikijs/core": "3.23.0",
-    "@shikijs/engine-javascript": "3.23.0",
-    "@shikijs/langs": "3.23.0",
-    "@shikijs/themes": "3.23.0",
+    "@shikijs/core": "4.2.0",
+    "@shikijs/engine-javascript": "4.2.0",
+    "@shikijs/langs": "4.2.0",
+    "@shikijs/themes": "4.2.0",
     "@stoplight/spectral-core": "^1.20.0",
     "@stoplight/spectral-rulesets": "^1.22.0",
     "@tailwindcss/typography": "^0.5.19",
     "@tailwindcss/vite": "^4.1.17",
     "@xt0rted/expressive-code-file-icons": "^1.0.0",
     "alpinejs": "^3.15.2",
-    "astro": "^5.16.4",
+    "astro": "^7.0.2",
     "astro-icon": "^1.1.5",
     "fontkit": "^2.0.4",
     "fs-extra": "^11.3.3",
@@ -62,23 +62,19 @@
     "oas": "^28.7.0",
     "openapi-sampler": "^1.6.2",
     "preact": "^10.29.0",
-    "prism-themes": "^1.9.0",
-    "prismjs": "^1.30.0",
-    "radiant-docs-validator": "^0.1.28",
+    "radiant-docs-validator": "^0.1.29",
     "rehype-autolink-headings": "^7.1.0",
     "rehype-slug": "^6.0.0",
     "remark-gfm": "^4.0.1",
+    "shiki": "4.2.0",
     "simple-git": "^3.30.0",
-    "shiki": "3.23.0",
     "tailwindcss": "^4.2.2",
     "wawoff2": "^2.0.1",
-    "yaml": "^2.8.2",
-    "zod": "^3.25.76"
+    "yaml": "^2.8.2"
   },
   "devDependencies": {
     "@types/fs-extra": "^11.0.4",
     "@types/mime-types": "^3.0.1",
-    "@types/prismjs": "^1.26.5",
     "esbuild": "^0.25.12",
     "pagefind": "^1.4.0",
     "tsx": "^4.21.0"

package/template/scripts/generate-proxy-allowed-origins.mjs

@@ -1,201 +1,24 @@
 import fs from "node:fs/promises";
 import path from "node:path";
-import YAML from "yaml";
+import { buildAllowedOrigins } from "../src/lib/proxy-allowed-origins.mjs";
 
 const CWD = process.cwd();
-const DOCS_DIR = path.join(CWD, "src/content/docs");
-const DOCS_CONFIG_PATH = path.join(DOCS_DIR, "docs.json");
 const OUTPUT_DIR = path.join(CWD, ".radiant");
 const OUTPUT_FILE = path.join(OUTPUT_DIR, "proxy-allowed-origins.json");
 
-function isRecord(value) {
-  return typeof value === "object" && value !== null;
-}
-
-function isHttpUrl(value) {
-  return /^https?:\/\//i.test(String(value).trim());
-}
-
-function collectOpenApiSourcesFromNavigation(navigationNode, target) {
-  if (!isRecord(navigationNode)) {
-    return;
-  }
-
-  const openApiConfig = navigationNode.openapi;
-  if (typeof openApiConfig === "string") {
-    const trimmed = openApiConfig.trim();
-    if (trimmed) {
-      target.add(trimmed);
-    }
-  } else if (
-    isRecord(openApiConfig) &&
-    typeof openApiConfig.source === "string"
-  ) {
-    const trimmed = openApiConfig.source.trim();
-    if (trimmed) {
-      target.add(trimmed);
-    }
-  }
-
-  const menu = navigationNode.menu;
-  if (isRecord(menu) && Array.isArray(menu.items)) {
-    for (const menuItem of menu.items) {
-      if (!isRecord(menuItem)) {
-        continue;
-      }
-      collectOpenApiSourcesFromNavigation(menuItem, target);
-    }
-  }
-
-  const tabs = navigationNode.tabs;
-  if (isRecord(tabs) && Array.isArray(tabs.items)) {
-    for (const tabItem of tabs.items) {
-      if (!isRecord(tabItem)) {
-        continue;
-      }
-      collectOpenApiSourcesFromNavigation(tabItem, target);
-    }
-  }
-}
-
-function resolveServerTemplateUrl(rawUrl, rawVariables) {
-  let unresolved = false;
-  const variables = isRecord(rawVariables) ? rawVariables : null;
-
-  const resolved = rawUrl.replace(/\{([^}]+)\}/g, (_match, tokenName) => {
-    if (!variables) {
-      unresolved = true;
-      return "";
-    }
-
-    const variableConfig = variables[tokenName];
-    if (
-      !isRecord(variableConfig) ||
-      typeof variableConfig.default !== "string"
-    ) {
-      unresolved = true;
-      return "";
-    }
-
-    const defaultValue = variableConfig.default.trim();
-    if (!defaultValue) {
-      unresolved = true;
-      return "";
-    }
-
-    return defaultValue;
-  });
-
-  if (unresolved) {
-    return null;
-  }
-
-  return resolved;
-}
-
-function normalizeAllowedOrigin(rawUrl) {
-  let parsed;
-  try {
-    parsed = new URL(rawUrl);
-  } catch {
-    return null;
-  }
-
-  if (parsed.protocol !== "https:") {
-    return null;
-  }
-
-  if (!parsed.hostname || parsed.username || parsed.password) {
-    return null;
-  }
-
-  return parsed.origin.toLowerCase();
-}
-
-async function loadOpenApiSpec(source) {
-  let fileContent;
-
-  if (isHttpUrl(source)) {
-    const response = await fetch(source);
-    if (!response.ok) {
-      throw new Error(
-        `Failed to fetch OpenAPI spec (${response.status} ${response.statusText})`,
-      );
-    }
-    fileContent = await response.text();
-  } else {
-    const absolutePath = path.join(DOCS_DIR, source);
-    fileContent = await fs.readFile(absolutePath, "utf8");
-  }
-
-  const trimmed = fileContent.trim();
-  if (trimmed.startsWith("<!DOCTYPE") || trimmed.startsWith("<html")) {
-    throw new Error("OpenAPI source returned HTML instead of JSON or YAML");
-  }
-
-  try {
-    return JSON.parse(fileContent);
-  } catch {
-    return YAML.parse(fileContent);
-  }
-}
-
-async function buildAllowedOrigins() {
-  const docsConfigRaw = await fs.readFile(DOCS_CONFIG_PATH, "utf8");
-  const docsConfig = JSON.parse(docsConfigRaw);
-
-  if (!isRecord(docsConfig) || !isRecord(docsConfig.navigation)) {
-    return [];
-  }
-
-  const sources = new Set();
-  collectOpenApiSourcesFromNavigation(docsConfig.navigation, sources);
-  if (sources.size === 0) {
-    return [];
-  }
-
-  const allowedOrigins = new Set();
-
-  for (const source of sources) {
-    try {
-      const spec = await loadOpenApiSpec(source);
-      const servers =
-        isRecord(spec) && Array.isArray(spec.servers) ? spec.servers : [];
-
-      for (const server of servers) {
-        if (!isRecord(server) || typeof server.url !== "string") {
-          continue;
-        }
-
-        const resolvedUrl = resolveServerTemplateUrl(
-          server.url,
-          server.variables,
-        );
-        if (!resolvedUrl) {
-          continue;
-        }
-
-        const normalizedOrigin = normalizeAllowedOrigin(resolvedUrl);
-        if (normalizedOrigin) {
-          allowedOrigins.add(normalizedOrigin);
-        }
-      }
-    } catch (error) {
-      console.warn(
-        `⚠️ Failed to extract OpenAPI server origins from "${source}":`,
-        error instanceof Error ? error.message : String(error),
-      );
-    }
-  }
-
-  return Array.from(allowedOrigins).sort();
-}
-
 async function run() {
   let allowedOrigins = [];
 
   try {
-    allowedOrigins = await buildAllowedOrigins();
+    allowedOrigins = await buildAllowedOrigins({
+      cwd: CWD,
+      onSourceError(source, error) {
+        console.warn(
+          `⚠️ Failed to extract OpenAPI server origins from "${source}":`,
+          error instanceof Error ? error.message : String(error),
+        );
+      },
+    });
   } catch (error) {
     console.warn(
       "⚠️ Failed to generate proxy allowed origins. Falling back to empty allowlist.",

package/template/scripts/publish-shiki-platform-assets.mjs

@@ -39,7 +39,7 @@ const DEFAULT_R2_REQUEST_TIMEOUT_MS = 30_000;
 const IMMUTABLE_CACHE_CONTROL = "public, max-age=31536000, immutable";
 const MARKER_CACHE_CONTROL = "no-store";
 const UPLOAD_COMPLETE_MARKER = ".radiant-upload-complete.json";
-const UPLOAD_MARKER_VERSION = 1;
+const UPLOAD_MARKER_VERSION = 2;
 
 const LICENSE_PACKAGES = [
   "shiki",
@@ -658,7 +658,7 @@ async function checkCurrentAssetFile(filePath, descriptor) {
   if (!(await pathExists(filePath))) {
     throw new Error(
       `Current Shiki platform asset file is missing: ${filePath}\n` +
-        "Run: npm --prefix framework run shiki:publish-platform-assets -- --prepare-only --write-current",
+        "Run: npm --prefix framework run shiki:assets:update",
     );
   }
 
@@ -671,7 +671,7 @@ async function checkCurrentAssetFile(filePath, descriptor) {
     `Current Shiki platform asset file is out of date: ${filePath}\n` +
       `Expected: ${describeCurrentDescriptor(descriptor)}\n` +
       `Found: ${describeCurrentDescriptor(current)}\n` +
-      "Run: npm --prefix framework run shiki:publish-platform-assets -- --prepare-only --write-current",
+      "Run: npm --prefix framework run shiki:assets:update",
   );
 }
 
@@ -808,7 +808,24 @@ async function sendR2CommandWithTimeout(s3, command, { label, timeoutMs }) {
   }
 }
 
-async function objectHasSameHash(s3, bucket, key, sha256, requestTimeoutMs) {
+function normalizeCacheControl(value) {
+  return String(value ?? "")
+    .trim()
+    .toLowerCase()
+    .replace(/\s*,\s*/g, ",");
+}
+
+function cacheControlMatches(actual, expected) {
+  return normalizeCacheControl(actual) === normalizeCacheControl(expected);
+}
+
+async function objectMatchesExpectedAssetMetadata(
+  s3,
+  bucket,
+  key,
+  sha256,
+  requestTimeoutMs,
+) {
   try {
     const response = await sendR2CommandWithTimeout(
       s3,
@@ -821,7 +838,10 @@ async function objectHasSameHash(s3, bucket, key, sha256, requestTimeoutMs) {
         timeoutMs: requestTimeoutMs,
       },
     );
-    return response.Metadata?.["radiant-sha256"] === sha256;
+    return (
+      response.Metadata?.["radiant-sha256"] === sha256 &&
+      cacheControlMatches(response.CacheControl, IMMUTABLE_CACHE_CONTROL)
+    );
   } catch (error) {
     const statusCode = error?.$metadata?.httpStatusCode;
     if (statusCode === 403 || statusCode === 404) return false;
@@ -856,6 +876,10 @@ async function completionMarkerMatches({
       metadata["radiant-shiki-asset-version"] === assetVersion &&
       metadata["radiant-shiki-file-count"] === String(fileCount) &&
       metadata["radiant-shiki-manifest-sha256"] === manifestSha256 &&
+      cacheControlMatches(
+        metadata["radiant-shiki-cache-control"],
+        IMMUTABLE_CACHE_CONTROL,
+      ) &&
       metadata["radiant-shiki-marker-version"] ===
         String(UPLOAD_MARKER_VERSION)
     );
@@ -875,6 +899,7 @@ function buildCompletionMarker({
 }) {
   return {
     assetVersion,
+    assetCacheControl: IMMUTABLE_CACHE_CONTROL,
     completedAt: new Date().toISOString(),
     fileCount,
     manifest: {
@@ -918,6 +943,7 @@ async function uploadCompletionMarker({
       Metadata: {
         "radiant-sha256": hashBuffer(body),
         "radiant-shiki-asset-version": assetVersion,
+        "radiant-shiki-cache-control": IMMUTABLE_CACHE_CONTROL,
         "radiant-shiki-file-count": String(fileCount),
         "radiant-shiki-manifest-sha256": manifestSha256,
         "radiant-shiki-marker-version": String(UPLOAD_MARKER_VERSION),
@@ -986,7 +1012,7 @@ async function uploadAssets({
       const body = await fs.readFile(absolutePath);
       const sha256 = hashBuffer(body);
       const key = joinPosix(uploadPrefix, relativePath);
-      const shouldSkip = await objectHasSameHash(
+      const shouldSkip = await objectMatchesExpectedAssetMetadata(
         s3,
         args.bucket,
         key,

package/template/src/components/chat/AssistantEmbedPanel.tsx

@@ -10,6 +10,7 @@ import { getDocsBasePath, withBasePath } from "../../lib/base-path";
 import {
   highlightAssistantCodeToHtml,
   normalizeAssistantCodeLanguage,
+  warmAssistantShikiRuntime,
   type AssistantShikiRuntimeConfig,
 } from "../../lib/assistant-shiki-client";
 
@@ -56,15 +57,22 @@ type AssistantColorByMode = {
   dark: string;
 };
 
+type AssistantMessageSource = {
+  href: string;
+  label: string;
+};
+
 type ChatMessage = {
   id: string;
   role: "user" | "assistant";
   content: string;
+  sources?: AssistantMessageSource[];
 };
 
 type AssistantStreamEvent = {
   type?: string;
   delta?: string;
+  sources?: unknown;
 };
 
 type ChatInputKeyEvent = JSX.TargetedKeyboardEvent<HTMLTextAreaElement>;
@@ -351,6 +359,33 @@ function createMessageId(): string {
   return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
 }
 
+function normalizeAssistantMessageSources(
+  rawSources: unknown,
+): AssistantMessageSource[] {
+  if (!Array.isArray(rawSources)) {
+    return [];
+  }
+
+  return rawSources.flatMap((rawSource) => {
+    if (!rawSource || typeof rawSource !== "object") {
+      return [];
+    }
+
+    const source = rawSource as Partial<AssistantMessageSource>;
+    const href = typeof source.href === "string" ? source.href.trim() : "";
+    const label =
+      typeof source.label === "string" && source.label.trim()
+        ? source.label.trim()
+        : href;
+
+    if (!href || !label) {
+      return [];
+    }
+
+    return [{ href, label }];
+  });
+}
+
 function normalizePersistedMessages(rawMessages: unknown): ChatMessage[] {
   if (!Array.isArray(rawMessages)) {
     return [];
@@ -372,6 +407,7 @@ function normalizePersistedMessages(rawMessages: unknown): ChatMessage[] {
       id: message.id,
       role: message.role,
       content: message.content,
+      sources: normalizeAssistantMessageSources(message.sources),
     }));
 }
 
@@ -953,6 +989,43 @@ function AssistantMarkdownBlock({
   );
 }
 
+function AssistantSourcesBlock({
+  linkTarget,
+  onClick,
+  sources,
+}: {
+  linkTarget: AssistantLinkTarget;
+  onClick: (event: JSX.TargetedMouseEvent<HTMLDivElement>) => void;
+  sources: AssistantMessageSource[] | undefined;
+}) {
+  const visibleSources = normalizeAssistantMessageSources(sources);
+  if (visibleSources.length === 0) {
+    return null;
+  }
+
+  return (
+    <div
+      className="ask-ai-sources ask-ai-markdown prose-rules mt-3 max-w-full min-w-0 wrap-break-word text-[15px]!"
+      onClick={onClick}
+    >
+      <p>Sources:</p>
+      <ul>
+        {visibleSources.map((source) => (
+          <li key={`${source.href}\0${source.label}`}>
+            <a
+              href={source.href}
+              target={linkTarget === "blank" ? "_blank" : undefined}
+              rel={linkTarget === "blank" ? "noopener noreferrer" : undefined}
+            >
+              {source.label}
+            </a>
+          </li>
+        ))}
+      </ul>
+    </div>
+  );
+}
+
 function extractErrorMessage(rawBody: string): string {
   if (!rawBody.trim()) {
     return "";
@@ -1110,6 +1183,7 @@ export default function AssistantEmbedPanel({
   const panelSizeRef = useRef<AssistantPanelSize>(
     panelSize ?? initialPanelState.panelSize,
   );
+  const hasPrewarmedShikiRef = useRef(false);
   const skipNextMessagesPersistRef = useRef(false);
   const inputRef = useRef<HTMLTextAreaElement | null>(null);
   const resolvedApiPathRef = useRef(
@@ -1799,6 +1873,13 @@ export default function AssistantEmbedPanel({
     setMessages(nextConversation);
     queueThreadScrollToBottom(nextConversation);
 
+    if (shiki && !hasPrewarmedShikiRef.current) {
+      hasPrewarmedShikiRef.current = true;
+      void warmAssistantShikiRuntime(shiki).catch((error) => {
+        console.warn("Assistant embed Shiki runtime prewarm failed", error);
+      });
+    }
+
     activeRequestAbortRef.current?.abort();
     const abortController = new AbortController();
     activeRequestAbortRef.current = abortController;
@@ -1916,6 +1997,49 @@ export default function AssistantEmbedPanel({
                   : message,
               );
             });
+            continue;
+          }
+
+          if (parsed.type === "sources") {
+            const nextSources = normalizeAssistantMessageSources(
+              parsed.sources,
+            );
+            if (nextSources.length === 0) {
+              continue;
+            }
+
+            if (!hasReceivedFirstTextDelta) {
+              hasReceivedFirstTextDelta = true;
+              setSharedAwaitingFirstToken(false);
+            }
+
+            setMessages((previous) => {
+              const existingAssistantMessage = previous.find(
+                (message) => message.id === assistantId,
+              );
+
+              const nextMessages = existingAssistantMessage
+                ? previous.map((message) =>
+                    message.id === assistantId
+                      ? {
+                          ...message,
+                          sources: nextSources,
+                        }
+                      : message,
+                  )
+                : [
+                    ...previous,
+                    {
+                      id: assistantId,
+                      role: "assistant" as const,
+                      content: "",
+                      sources: nextSources,
+                    },
+                  ];
+
+              queueThreadScrollToBottom(nextMessages);
+              return nextMessages;
+            });
           }
         }
       }
@@ -2242,7 +2366,8 @@ export default function AssistantEmbedPanel({
             {messages.map((message) => {
               if (
                 message.role === "assistant" &&
-                message.content.length === 0
+                message.content.length === 0 &&
+                normalizeAssistantMessageSources(message.sources).length === 0
               ) {
                 return null;
               }
@@ -2265,6 +2390,13 @@ export default function AssistantEmbedPanel({
                     onRendered={handleMarkdownRendered}
                     shiki={shiki}
                   />
+                  {!isUser ? (
+                    <AssistantSourcesBlock
+                      linkTarget={linkTarget}
+                      onClick={handleRenderedMarkdownClick}
+                      sources={message.sources}
+                    />
+                  ) : null}
                 </div>
               );
             })}