radiant-docs 0.1.61 → 0.1.63

package/template/src/lib/assistant-panel-config.ts

@@ -4,6 +4,8 @@ import {
 } from "./assistant-chrome";
 import { withBasePath } from "./base-path";
 import { getAssistantLauncherIconConfig } from "./assistant-embed-script";
+import type { AssistantShikiRuntimeConfig } from "./assistant-shiki-client";
+import { getClientShikiRuntimeConfig } from "./client-shiki-config";
 import type { DocsConfig } from "./validation";
 
 export type AssistantPanelRuntimeConfig = {
@@ -26,6 +28,7 @@ export type AssistantPanelRuntimeConfig = {
   emptyStateQuestions?: string[];
   devProxyToken?: string;
   chrome: AssistantChromeConfig;
+  shiki?: AssistantShikiRuntimeConfig;
 };
 
 export function getAssistantPanelRuntimeConfig(
@@ -76,5 +79,6 @@ export function getAssistantPanelRuntimeConfig(
     emptyStateQuestions: assistantConfig?.questions,
     devProxyToken: isDev ? assistantDevProxySecret : undefined,
     chrome: getAssistantChromeConfig(config),
+    shiki: getClientShikiRuntimeConfig(config),
   };
 }

package/template/src/lib/assistant-shiki-client.ts

@@ -0,0 +1,522 @@
+export type AssistantCodeSyntaxThemes = {
+  light: string;
+  dark: string;
+};
+
+export type AssistantShikiRuntimeConfig = {
+  assetBaseUrl: string;
+  syntaxThemes: AssistantCodeSyntaxThemes;
+};
+
+type ShikiPlatformManifest = {
+  assetVersion: string;
+  languageAliases: Record<string, string>;
+  languages: Record<
+    string,
+    {
+      aliases?: string[];
+      displayName?: string;
+      module: string;
+      registrations?: string[];
+    }
+  >;
+  runtime: {
+    module: string;
+  };
+  themes: Record<
+    string,
+    {
+      displayName?: string;
+      module: string;
+      type?: string;
+    }
+  >;
+};
+
+type ShikiToken = {
+  content: string;
+  color?: string;
+  bgColor?: string;
+  fontStyle?: number;
+  htmlStyle?: Record<string, string>;
+};
+
+type ShikiTokensResult = {
+  tokens: ShikiToken[][];
+};
+
+type ShikiHighlighter = {
+  codeToTokens: (
+    code: string,
+    options: {
+      lang: string;
+      theme: string;
+    },
+  ) => ShikiTokensResult;
+  loadLanguage: (...languages: unknown[]) => Promise<void> | void;
+};
+
+type ShikiRuntimeModule = {
+  createRadiantShikiHighlighter: (options: {
+    langs?: unknown[];
+    themes?: unknown[];
+    warnings?: boolean;
+  }) => Promise<ShikiHighlighter>;
+};
+
+type LoadedShikiRuntime = {
+  highlighter: ShikiHighlighter;
+  manifest: ShikiPlatformManifest;
+};
+
+type AssistantCodeLineToken = {
+  content: string;
+  color?: string;
+  darkColor?: string;
+  bgColor?: string;
+  darkBgColor?: string;
+  fontStyle?: number;
+  htmlStyle?: Record<string, string>;
+  darkHtmlStyle?: Record<string, string>;
+};
+
+const SHIKI_PLAINTEXT_LANGUAGE = "plaintext";
+const LANGUAGE_ALIAS_COMPAT_TO_VALUE: Record<string, string> = {
+  htm: "html",
+  node: "javascript",
+  plain: SHIKI_PLAINTEXT_LANGUAGE,
+  text: SHIKI_PLAINTEXT_LANGUAGE,
+  txt: SHIKI_PLAINTEXT_LANGUAGE,
+};
+const LANGUAGE_RUNTIME_DEPENDENCIES: Record<string, string[]> = {
+  mdx: ["tsx"],
+};
+
+const runtimePromiseByKey = new Map<string, Promise<LoadedShikiRuntime>>();
+const languageLoadPromiseByKey = new Map<string, Promise<void>>();
+
+function joinUrl(baseUrl: string, path: string): string {
+  return `${baseUrl.replace(/\/+$/, "")}/${path.replace(/^\/+/, "")}`;
+}
+
+function getRuntimeCacheKey(config: AssistantShikiRuntimeConfig): string {
+  return [
+    config.assetBaseUrl.trim(),
+    config.syntaxThemes.light,
+    config.syntaxThemes.dark,
+  ].join("\0");
+}
+
+async function importExternalModule<T>(url: string): Promise<T> {
+  return import(/* @vite-ignore */ url) as Promise<T>;
+}
+
+function normalizeModuleDefault(value: unknown): unknown[] {
+  const moduleValue = (value as { default?: unknown })?.default ?? value;
+  if (Array.isArray(moduleValue)) return moduleValue;
+  return moduleValue ? [moduleValue] : [];
+}
+
+async function loadManifest(
+  assetBaseUrl: string,
+): Promise<ShikiPlatformManifest> {
+  const response = await fetch(joinUrl(assetBaseUrl, "manifest.json"));
+  if (!response.ok) {
+    throw new Error(
+      `Failed to load Shiki manifest: ${response.status} ${response.statusText}`,
+    );
+  }
+
+  return (await response.json()) as ShikiPlatformManifest;
+}
+
+async function loadRuntime(
+  config: AssistantShikiRuntimeConfig,
+): Promise<LoadedShikiRuntime> {
+  const assetBaseUrl = config.assetBaseUrl.trim();
+  if (!assetBaseUrl) {
+    throw new Error("Shiki asset base URL is not configured.");
+  }
+
+  const runtimeCacheKey = getRuntimeCacheKey(config);
+  const cached = runtimePromiseByKey.get(runtimeCacheKey);
+  if (cached) return cached;
+
+  const runtimePromise = (async () => {
+    const manifest = await loadManifest(assetBaseUrl);
+    const runtime = await importExternalModule<ShikiRuntimeModule>(
+      joinUrl(assetBaseUrl, manifest.runtime.module),
+    );
+
+    const themeModules = await Promise.all(
+      Array.from(
+        new Set([config.syntaxThemes.light, config.syntaxThemes.dark]),
+      ).map(async (themeName) => {
+        const themeEntry = manifest.themes[themeName];
+        if (!themeEntry) {
+          throw new Error(`Shiki theme "${themeName}" is not available.`);
+        }
+
+        const moduleValue = await importExternalModule<unknown>(
+          joinUrl(assetBaseUrl, themeEntry.module),
+        );
+        return ((moduleValue as { default?: unknown }).default ??
+          moduleValue) as unknown;
+      }),
+    );
+
+    const highlighter = await runtime.createRadiantShikiHighlighter({
+      langs: [],
+      themes: themeModules,
+      warnings: false,
+    });
+
+    return { highlighter, manifest };
+  })();
+
+  runtimePromiseByKey.set(runtimeCacheKey, runtimePromise);
+  runtimePromise.catch(() => {
+    if (runtimePromiseByKey.get(runtimeCacheKey) === runtimePromise) {
+      runtimePromiseByKey.delete(runtimeCacheKey);
+    }
+  });
+  return runtimePromise;
+}
+
+export async function warmAssistantShikiRuntime(
+  config: AssistantShikiRuntimeConfig,
+): Promise<void> {
+  await loadRuntime(config);
+}
+
+function normalizeLanguageToken(rawLanguage: string): string {
+  const normalized = rawLanguage.trim().toLowerCase();
+  if (!normalized) return "";
+
+  const firstToken = normalized.split(/\s+/)[0] ?? "";
+  const tokenMatch = firstToken.match(/[a-z0-9+#-]+/i);
+  return (tokenMatch?.[0] ?? firstToken).toLowerCase();
+}
+
+export function normalizeAssistantCodeLanguage(rawLanguage: string): string {
+  return normalizeLanguageToken(rawLanguage);
+}
+
+function resolveManifestLanguage(
+  manifest: ShikiPlatformManifest,
+  rawLanguage: string,
+): string {
+  const token = normalizeLanguageToken(rawLanguage);
+  if (!token) return "";
+
+  return (
+    manifest.languageAliases[token] ??
+    manifest.languageAliases[LANGUAGE_ALIAS_COMPAT_TO_VALUE[token] ?? ""] ??
+    LANGUAGE_ALIAS_COMPAT_TO_VALUE[token] ??
+    token
+  );
+}
+
+function buildLanguageLoadOrder(language: string): string[] {
+  return [...(LANGUAGE_RUNTIME_DEPENDENCIES[language] ?? []), language].filter(
+    (value, index, values) => value && values.indexOf(value) === index,
+  );
+}
+
+async function ensureLanguageLoaded({
+  assetBaseUrl,
+  highlighter,
+  language,
+  manifest,
+  runtimeCacheKey,
+}: {
+  assetBaseUrl: string;
+  highlighter: ShikiHighlighter;
+  language: string;
+  manifest: ShikiPlatformManifest;
+  runtimeCacheKey: string;
+}): Promise<string> {
+  if (
+    !language ||
+    language === SHIKI_PLAINTEXT_LANGUAGE ||
+    language === "text"
+  ) {
+    return SHIKI_PLAINTEXT_LANGUAGE;
+  }
+
+  const manifestLanguage = manifest.languages[language]
+    ? language
+    : (manifest.languageAliases[language] ?? "");
+  const languageEntry = manifestLanguage
+    ? manifest.languages[manifestLanguage]
+    : undefined;
+  if (!manifestLanguage || !languageEntry) {
+    return SHIKI_PLAINTEXT_LANGUAGE;
+  }
+
+  const cacheKey = `${runtimeCacheKey}\0${manifestLanguage}`;
+  let loadPromise = languageLoadPromiseByKey.get(cacheKey);
+  if (!loadPromise) {
+    loadPromise = (async () => {
+      const moduleValue = await importExternalModule<unknown>(
+        joinUrl(assetBaseUrl, languageEntry.module),
+      );
+      const registrations = normalizeModuleDefault(moduleValue);
+      await highlighter.loadLanguage(...registrations);
+    })();
+    languageLoadPromiseByKey.set(cacheKey, loadPromise);
+    loadPromise.catch(() => {
+      if (languageLoadPromiseByKey.get(cacheKey) === loadPromise) {
+        languageLoadPromiseByKey.delete(cacheKey);
+      }
+    });
+  }
+
+  await loadPromise;
+  return manifestLanguage;
+}
+
+function escapeHtml(value: string): string {
+  return value
+    .replaceAll("&", "&amp;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("'", "&#39;");
+}
+
+function escapeAttribute(value: string): string {
+  return escapeHtml(value).replaceAll("`", "&#96;");
+}
+
+function buildTokenStyle(token: AssistantCodeLineToken): string {
+  const styleEntries: string[] = [];
+
+  const pushStyleVariable = (property: string, value?: string) => {
+    if (value) styleEntries.push(`${property}:${value}`);
+  };
+
+  pushStyleVariable("--rd-token-color", token.color);
+  pushStyleVariable("--rd-token-color-dark", token.darkColor);
+  pushStyleVariable("--rd-token-bg", token.bgColor);
+  pushStyleVariable("--rd-token-bg-dark", token.darkBgColor);
+
+  const pushHtmlStyle = (
+    styleObject: Record<string, string> | undefined,
+    isDarkStyle: boolean,
+  ) => {
+    if (!styleObject || typeof styleObject !== "object") return;
+
+    for (const [property, value] of Object.entries(styleObject)) {
+      const normalizedProperty = property.trim().toLowerCase();
+      if (normalizedProperty === "color") {
+        pushStyleVariable(
+          isDarkStyle ? "--rd-token-color-dark" : "--rd-token-color",
+          value,
+        );
+        continue;
+      }
+      if (normalizedProperty === "background-color") {
+        pushStyleVariable(
+          isDarkStyle ? "--rd-token-bg-dark" : "--rd-token-bg",
+          value,
+        );
+        continue;
+      }
+
+      styleEntries.push(`${property}:${value}`);
+    }
+  };
+
+  pushHtmlStyle(token.htmlStyle, false);
+  pushHtmlStyle(token.darkHtmlStyle, true);
+
+  if (token.fontStyle) {
+    if (token.fontStyle & 1) styleEntries.push("font-style:italic");
+    if (token.fontStyle & 2) styleEntries.push("font-weight:600");
+    if (token.fontStyle & 4) styleEntries.push("text-decoration:underline");
+  }
+
+  return styleEntries.join(";");
+}
+
+function buildLightOnlyTokenLine(
+  lightLine: ShikiToken[],
+): AssistantCodeLineToken[] {
+  return lightLine.map((token) => ({
+    bgColor: token.bgColor,
+    color: token.color,
+    content: token.content,
+    fontStyle: token.fontStyle,
+    htmlStyle: token.htmlStyle,
+  }));
+}
+
+function mergeTokenLineByContent(
+  lightLine: ShikiToken[],
+  darkLine: ShikiToken[],
+): AssistantCodeLineToken[] | null {
+  const lightContent = lightLine.map((token) => token.content).join("");
+  const darkContent = darkLine.map((token) => token.content).join("");
+  if (lightContent !== darkContent) return null;
+  if (lightContent.length === 0) return [];
+
+  const mergedLine: AssistantCodeLineToken[] = [];
+  let lightTokenIndex = 0;
+  let darkTokenIndex = 0;
+  let lightTokenOffset = 0;
+  let darkTokenOffset = 0;
+
+  while (
+    lightTokenIndex < lightLine.length &&
+    darkTokenIndex < darkLine.length
+  ) {
+    const lightToken = lightLine[lightTokenIndex];
+    const darkToken = darkLine[darkTokenIndex];
+
+    if (lightTokenOffset >= lightToken.content.length) {
+      lightTokenIndex += 1;
+      lightTokenOffset = 0;
+      continue;
+    }
+
+    if (darkTokenOffset >= darkToken.content.length) {
+      darkTokenIndex += 1;
+      darkTokenOffset = 0;
+      continue;
+    }
+
+    const lightRemainingLength = lightToken.content.length - lightTokenOffset;
+    const darkRemainingLength = darkToken.content.length - darkTokenOffset;
+    const segmentLength = Math.min(lightRemainingLength, darkRemainingLength);
+    if (segmentLength <= 0) break;
+
+    const lightSegment = lightToken.content.slice(
+      lightTokenOffset,
+      lightTokenOffset + segmentLength,
+    );
+    const darkSegment = darkToken.content.slice(
+      darkTokenOffset,
+      darkTokenOffset + segmentLength,
+    );
+
+    if (lightSegment !== darkSegment) return null;
+
+    mergedLine.push({
+      bgColor: lightToken.bgColor,
+      color: lightToken.color,
+      content: lightSegment,
+      darkBgColor: darkToken.bgColor,
+      darkColor: darkToken.color,
+      darkHtmlStyle: darkToken.htmlStyle,
+      fontStyle: lightToken.fontStyle,
+      htmlStyle: lightToken.htmlStyle,
+    });
+
+    lightTokenOffset += segmentLength;
+    darkTokenOffset += segmentLength;
+  }
+
+  const mergedContent = mergedLine.map((token) => token.content).join("");
+  return mergedContent === lightContent ? mergedLine : null;
+}
+
+function mergeTokenLines(
+  lightTokenLines: ShikiToken[][],
+  darkTokenLines: ShikiToken[][],
+): AssistantCodeLineToken[][] {
+  const lineCount = Math.max(lightTokenLines.length, darkTokenLines.length);
+  const mergedLines: AssistantCodeLineToken[][] = [];
+
+  for (let lineIndex = 0; lineIndex < lineCount; lineIndex += 1) {
+    const lightLine = lightTokenLines[lineIndex] ?? [];
+    const darkLine = darkTokenLines[lineIndex] ?? [];
+    const mergedLine = mergeTokenLineByContent(lightLine, darkLine);
+    mergedLines.push(mergedLine ?? buildLightOnlyTokenLine(lightLine));
+  }
+
+  return mergedLines;
+}
+
+function renderTokenLinesHtml(
+  code: string,
+  tokenLines: AssistantCodeLineToken[][],
+): string {
+  const rawLines = code.split("\n");
+  const normalizedRawLines = rawLines.length > 0 ? rawLines : [""];
+  const lineCount = Math.max(1, normalizedRawLines.length, tokenLines.length);
+
+  return Array.from({ length: lineCount }, (_, lineIndex) => {
+    const lineTokens = tokenLines[lineIndex] ?? [];
+    const fallbackLineContent = normalizedRawLines[lineIndex] ?? "";
+    const tokenHtml =
+      lineTokens.length > 0
+        ? lineTokens
+            .map((token) => {
+              const tokenStyle = buildTokenStyle(token);
+              const tokenStyleAttribute = tokenStyle
+                ? ` style="${escapeAttribute(tokenStyle)}"`
+                : "";
+              return `<span data-rd-token${tokenStyleAttribute}>${escapeHtml(token.content)}</span>`;
+            })
+            .join("")
+        : fallbackLineContent.length > 0
+          ? escapeHtml(fallbackLineContent)
+          : "&nbsp;";
+
+    return `<span class="flex w-max min-w-full"><span class="flex-1 whitespace-pre pl-3 pr-3">${tokenHtml}</span></span>`;
+  }).join("");
+}
+
+export async function highlightAssistantCodeToHtml({
+  code,
+  config,
+  language,
+}: {
+  code: string;
+  config: AssistantShikiRuntimeConfig;
+  language: string;
+}): Promise<{
+  html: string;
+  language: string;
+}> {
+  const runtime = await loadRuntime(config);
+  const runtimeCacheKey = getRuntimeCacheKey(config);
+  const requestedLanguage = resolveManifestLanguage(runtime.manifest, language);
+  let targetLanguage = requestedLanguage || SHIKI_PLAINTEXT_LANGUAGE;
+
+  for (const languageToLoad of buildLanguageLoadOrder(targetLanguage)) {
+    targetLanguage = await ensureLanguageLoaded({
+      assetBaseUrl: config.assetBaseUrl,
+      highlighter: runtime.highlighter,
+      language: languageToLoad,
+      manifest: runtime.manifest,
+      runtimeCacheKey,
+    });
+  }
+
+  try {
+    const lightTokenResult = runtime.highlighter.codeToTokens(code, {
+      lang: targetLanguage,
+      theme: config.syntaxThemes.light,
+    });
+    const darkTokenResult = runtime.highlighter.codeToTokens(code, {
+      lang: targetLanguage,
+      theme: config.syntaxThemes.dark,
+    });
+    const tokenLines = mergeTokenLines(
+      lightTokenResult.tokens,
+      darkTokenResult.tokens,
+    );
+
+    return {
+      html: renderTokenLinesHtml(code, tokenLines),
+      language: targetLanguage,
+    };
+  } catch {
+    return {
+      html: renderTokenLinesHtml(code, []),
+      language: SHIKI_PLAINTEXT_LANGUAGE,
+    };
+  }
+}

package/template/src/lib/client-shiki-config.ts

@@ -0,0 +1,60 @@
+import type { AssistantShikiRuntimeConfig } from "./assistant-shiki-client";
+import type { DocsConfig } from "./validation";
+import shikiPlatformAssets from "../generated/shiki-platform-assets.json";
+import {
+  DEFAULT_SHIKI_DARK_THEME,
+  DEFAULT_SHIKI_LIGHT_THEME,
+} from "radiant-docs-validator/shiki-theme-config";
+
+export type ClientShikiRuntimeConfig = AssistantShikiRuntimeConfig;
+
+function normalizeStaticAssetHost(value: unknown): string {
+  const rawValue = typeof value === "string" ? value.trim() : "";
+  if (!rawValue) return "";
+
+  const normalizedHost = rawValue.replace(/\/+$/, "");
+  return /^https?:\/\//i.test(normalizedHost)
+    ? normalizedHost
+    : `https://${normalizedHost}`;
+}
+
+function joinUrl(baseUrl: string, path: string): string {
+  return `${baseUrl.replace(/\/+$/, "")}/${path.replace(/^\/+/, "")}`;
+}
+
+function getConfiguredCodeSyntaxThemes(
+  config: DocsConfig,
+): ClientShikiRuntimeConfig["syntaxThemes"] {
+  const configuredSyntaxTheme = config.theme?.code?.syntaxTheme;
+
+  if (typeof configuredSyntaxTheme === "string") {
+    return {
+      light: configuredSyntaxTheme,
+      dark: configuredSyntaxTheme,
+    };
+  }
+
+  return {
+    light: configuredSyntaxTheme?.light ?? DEFAULT_SHIKI_LIGHT_THEME,
+    dark: configuredSyntaxTheme?.dark ?? DEFAULT_SHIKI_DARK_THEME,
+  };
+}
+
+export function getClientShikiRuntimeConfig(
+  config: DocsConfig,
+): ClientShikiRuntimeConfig | undefined {
+  const staticAssetHost = normalizeStaticAssetHost(
+    import.meta.env.STATIC_ASSET_HOST ?? process.env.STATIC_ASSET_HOST,
+  );
+  if (!staticAssetHost) {
+    return undefined;
+  }
+
+  return {
+    assetBaseUrl: joinUrl(
+      staticAssetHost,
+      `${shikiPlatformAssets.prefix}/${shikiPlatformAssets.assetVersion}`,
+    ),
+    syntaxThemes: getConfiguredCodeSyntaxThemes(config),
+  };
+}