jamdesk 1.0.22 → 1.1.0

package/vendored/components/mdx/ApiEndpoint.tsx

@@ -63,7 +63,7 @@ export function ApiEndpoint({ method, path, baseUrl = 'https://api.jamdesk.com/a
   };
 
   return (
-    <div data-api-endpoint="true" onClick={handleCopy} className="flex items-center gap-3 px-3 py-1.5 rounded-xl border border-[var(--color-border)] bg-[var(--color-bg-primary)] mb-4 not-prose cursor-pointer">
+    <div data-api-endpoint="true" className="flex items-center gap-3 px-3 py-1.5 rounded-xl border border-[var(--color-border)] bg-[var(--color-bg-primary)] mb-4 not-prose">
       {/* Method badge */}
       <span className={`px-2.5 py-1 text-xs font-bold rounded-md ${colors.bg} ${colors.text}`}>
         {method}
@@ -78,6 +78,7 @@ export function ApiEndpoint({ method, path, baseUrl = 'https://api.jamdesk.com/a
         onClick={handleCopy}
         className="p-1.5 text-[var(--color-text-muted)] hover:text-[var(--color-text-primary)] hover:bg-[var(--color-bg-secondary)] rounded-md transition-colors"
         title="Copy endpoint URL"
+        aria-label="Copy endpoint URL"
       >
         {copied ? (
           <i className="fa-solid fa-check h-4 w-4 text-emerald-500" aria-hidden="true" />

package/vendored/components/mdx/ImagePriorityProvider.tsx

@@ -0,0 +1,53 @@
+'use client';
+
+import { createContext, useContext, useRef, useMemo, type ReactNode } from 'react';
+
+interface ImagePriorityContextValue {
+  /** Call once per image. Returns true for the first image only. */
+  claimPriority: () => boolean;
+}
+
+const ImagePriorityContext = createContext<ImagePriorityContextValue | null>(null);
+
+/**
+ * Wrap MDX content to auto-prioritize the first image for LCP.
+ * The first image to call `claimPriority()` gets `loading="eager"` + `fetchPriority="high"`.
+ * All subsequent images get the default `loading="lazy"`.
+ */
+export function ImagePriorityProvider({ children }: { children: ReactNode }) {
+  const claimed = useRef(false);
+
+  const value = useMemo<ImagePriorityContextValue>(() => ({
+    claimPriority: () => {
+      if (claimed.current) return false;
+      claimed.current = true;
+      return true;
+    },
+  }), []);
+
+  return (
+    <ImagePriorityContext.Provider value={value}>
+      {children}
+    </ImagePriorityContext.Provider>
+  );
+}
+
+/**
+ * Hook for images to check if they should be the priority (LCP) image.
+ * Returns `{ isFirst: true }` for the first caller, `{ isFirst: false }` for all others.
+ * Safe to use outside provider — returns `{ isFirst: false }`.
+ *
+ * Uses a local ref to cache the result — without this, React strict mode's
+ * double-render would claim priority on the first pass, then the second pass
+ * would see `claimed.current === true` and no image would get priority.
+ */
+export function useImagePriority(): { isFirst: boolean } {
+  const ctx = useContext(ImagePriorityContext);
+  const result = useRef<boolean | null>(null);
+
+  if (result.current === null) {
+    result.current = ctx ? ctx.claimPriority() : false;
+  }
+
+  return { isFirst: result.current };
+}

package/vendored/components/mdx/MDXComponents.tsx

@@ -139,6 +139,7 @@ function HttpCodeBlock({ method, url }: { method: string; url: string }) {
       <button
         className="http-copy-btn p-1.5 text-[var(--color-text-muted)] hover:text-[var(--color-text-primary)] hover:bg-[var(--color-bg-secondary)] rounded-md transition-colors flex-shrink-0"
         title="Copy"
+        aria-label="Copy"
         type="button"
       >
         <i className="fa-regular fa-copy text-sm" aria-hidden="true" />
@@ -217,6 +218,18 @@ export const MDXComponents = {
   ViewWrapper,
   // Media embeds
   YouTube,
+  // Sized images from preprocess-mdx (![alt](url =WIDTHx) syntax).
+  // These are output as <SizedImage> JSX so they go through component mapping
+  // (raw <img> JSX in MDX bypasses the components provider).
+  SizedImage: ({ src, alt, width, height, className, ...rest }: any) => (
+    <ZoomableImage
+      src={src}
+      alt={alt || ''}
+      width={width}
+      height={height}
+      className={`mx-auto block ${className || ''}`.trim()}
+    />
+  ),
   // Localized component aliases (for translated docs)
   Varning: Warning,        // Swedish
   Avertissement: Warning,  // French
@@ -228,6 +241,7 @@ export const MDXComponents = {
     style,
     loading,
     decoding,
+    fetchPriority,
     className,
     class: htmlClass,
     'data-no-zoom': dataNoZoom,
@@ -266,6 +280,7 @@ export const MDXComponents = {
         style={style}
         loading={loading}
         decoding={decoding}
+        fetchPriority={fetchPriority}
         noZoom={disableZoom}
       />
     );

package/vendored/components/mdx/ZoomableImage.tsx

@@ -1,6 +1,8 @@
 'use client';
 
-import { useState, useEffect } from 'react';
+import { useState, useEffect, useCallback } from 'react';
+import { useImagePriority } from './ImagePriorityProvider';
+import { useBodyScrollLock } from '../../hooks/useBodyScrollLock';
 
 interface ZoomableImageProps {
   src: string;
@@ -11,6 +13,7 @@ interface ZoomableImageProps {
   style?: React.CSSProperties;
   loading?: 'lazy' | 'eager';
   decoding?: 'sync' | 'async' | 'auto';
+  fetchPriority?: 'high' | 'low' | 'auto';
   noZoom?: boolean;
 }
 
@@ -23,34 +26,36 @@ export function ZoomableImage({
   style,
   loading,
   decoding,
+  fetchPriority,
   noZoom = false,
 }: ZoomableImageProps) {
+  const { isFirst } = useImagePriority();
   const [isZoomed, setIsZoomed] = useState(false);
-  const [isMobile, setIsMobile] = useState(false);
 
-  // Detect mobile devices
-  useEffect(() => {
-    const checkMobile = () => {
-      setIsMobile(window.innerWidth < 768);
-    };
-    
-    checkMobile();
-    window.addEventListener('resize', checkMobile);
-    return () => window.removeEventListener('resize', checkMobile);
-  }, []);
+  // Auto-prioritize first image for LCP (unless explicitly overridden)
+  const effectiveLoading = loading || (isFirst ? 'eager' : 'lazy');
+  const effectivePriority = fetchPriority || (isFirst ? 'high' : undefined);
 
-  // Disable zoom if noZoom prop is set OR if on mobile
-  const zoomDisabled = noZoom || isMobile;
+  useBodyScrollLock(isZoomed);
 
-  const handleClick = () => {
-    if (!zoomDisabled) {
+  const handleClick = useCallback(() => {
+    // Check mobile at click time — avoids per-image resize listeners
+    if (!noZoom && window.innerWidth >= 768) {
       setIsZoomed(true);
     }
-  };
+  }, [noZoom]);
 
-  const handleClose = () => {
-    setIsZoomed(false);
-  };
+  const handleClose = useCallback(() => setIsZoomed(false), []);
+
+  // Escape key closes zoom modal
+  useEffect(() => {
+    if (!isZoomed) return;
+    const handleKeyDown = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') handleClose();
+    };
+    document.addEventListener('keydown', handleKeyDown);
+    return () => document.removeEventListener('keydown', handleKeyDown);
+  }, [isZoomed, handleClose]);
 
   return (
     <>
@@ -59,17 +64,21 @@ export function ZoomableImage({
         alt={alt}
         width={width}
         height={height}
-        className={`${className} ${zoomDisabled ? '' : 'cursor-zoom-in'}`}
+        className={`${className} ${noZoom ? '' : 'md:cursor-zoom-in'}`}
         style={style}
-        loading={loading || 'lazy'}
+        loading={effectiveLoading}
         decoding={decoding || 'async'}
+        fetchPriority={effectivePriority}
         onClick={handleClick}
       />
-      
-      {/* Zoom Modal - only renders on desktop when zoom is enabled */}
-      {isZoomed && !isMobile && (
-        <div 
+
+      {/* Zoom Modal */}
+      {isZoomed && (
+        <div
           className="image-zoom-modal"
+          role="dialog"
+          aria-modal="true"
+          aria-label={`Zoomed image: ${alt || 'Image'}`}
           onClick={handleClose}
         >
           <div className="image-zoom-backdrop">
@@ -80,4 +89,3 @@ export function ZoomableImage({
     </>
   );
 }
-

package/vendored/lib/analytics-script.ts

@@ -134,14 +134,6 @@ export function getAnalyticsScript(rawSlug: string | null): string {
   window.addEventListener('popstate', function() {
     setTimeout(trackIfNewPath, 0);
   });
-
-  // Fallback: Poll for URL changes (catches Next.js soft navigation)
-  setInterval(function() {
-    if (location.pathname !== lastTrackedPath) {
-      lastTrackedPath = location.pathname;
-      trackPageView();
-    }
-  }, 1000);
 })();
 `;
 }

package/vendored/lib/contextual-defaults.ts

@@ -0,0 +1,16 @@
+import type { DocsConfig, ContextualOption } from './docs-types';
+
+const DEFAULT_OPTIONS: ContextualOption[] = [
+  'copy', 'view', 'chatgpt', 'claude', 'perplexity', 'mcp', 'cursor', 'vscode',
+];
+
+/**
+ * Resolve contextual menu options from config.
+ * Returns empty array if disabled or explicitly empty.
+ */
+export function getContextualOptions(config: DocsConfig): ContextualOption[] {
+  if (config.contextual?.enabled === false) return [];
+  const options = config.contextual?.options;
+  if (options !== undefined) return options;
+  return DEFAULT_OPTIONS;
+}

package/vendored/lib/docs-types.ts

@@ -568,6 +568,13 @@ export interface StylingConfig {
    * Note: May interfere with code examples containing quote characters.
    */
   typography?: boolean;
+  /**
+   * Custom JavaScript file path(s) to include on documentation pages.
+   * Files are resolved relative to the project's content directory.
+   *
+   * Example: "scripts/custom.js" or ["scripts/analytics.js", "scripts/widget.js"]
+   */
+  js?: string | string[];
 }
 
 // =============================================================================
@@ -588,6 +595,7 @@ export interface IntegrationsConfig {
   heap?: { appId: string };
   hightouch?: { writeKey: string; apiHost?: string };
   hotjar?: { hjid: string; hjsv: string };
+  crisp?: { websiteId: string };
   intercom?: { appId: string };
   koala?: { publicApiKey: string };
   logrocket?: { appId: string };
@@ -669,8 +677,8 @@ export interface ErrorsConfig {
 /**
  * Contextual option - built-in or custom
  */
-export type ContextualOption = 
-  | 'copy' | 'view' | 'chatgpt' | 'claude' | 'perplexity' 
+export type ContextualOption =
+  | 'copy' | 'view' | 'chatgpt' | 'claude' | 'gemini' | 'perplexity'
   | 'mcp' | 'cursor' | 'vscode'
   | {
       title: string;
@@ -683,7 +691,8 @@ export type ContextualOption =
  * Contextual menu configuration
  */
 export interface ContextualConfig {
-  options: ContextualOption[];
+  enabled?: boolean;
+  options?: ContextualOption[];
 }
 
 /**

package/vendored/lib/enhance-navigation.ts

@@ -121,7 +121,7 @@ function enhancePages(
 }
 
 /** Navigation keys whose children are sub-nodes (recurse with enhanceNavNode). */
-const RECURSE_KEYS = [
+export const RECURSE_KEYS = [
   'groups', 'tabs', 'anchors', 'dropdowns',
   'products', 'versions', 'languages', 'menu',
 ] as const;

package/vendored/lib/isr-build-executor.ts

@@ -8,7 +8,9 @@
  */
 
 import fs from 'fs';
+import path from 'path';
 import glob from 'fast-glob';
+import type { DocsConfig } from './docs-types.js';
 
 /**
  * Check if ISR mode should be used.
@@ -200,3 +202,42 @@ export const ISR_PHASES = {
 } as const;
 
 export type IsrPhase = keyof typeof ISR_PHASES;
+
+/**
+ * Collect custom JavaScript content from project directory.
+ * Priority: styling.js config > auto-detect .js files in project root.
+ * Returns concatenated JS content or null if none found.
+ */
+export function collectCustomJs(
+  projectDir: string,
+  config: DocsConfig
+): string | null {
+  let jsPaths: string[] = [];
+
+  if (config.styling?.js) {
+    const configured = Array.isArray(config.styling.js)
+      ? config.styling.js
+      : [config.styling.js];
+    jsPaths = configured.map(p => p.replace(/^\//, ''));
+  } else {
+    try {
+      jsPaths = (fs.readdirSync(projectDir) as string[])
+        .filter(f => f.endsWith('.js'))
+        .sort();
+    } catch {
+      return null;
+    }
+  }
+
+  if (jsPaths.length === 0) return null;
+
+  const contents: string[] = [];
+  for (const jsPath of jsPaths) {
+    const fullPath = path.join(projectDir, jsPath);
+    if (fs.existsSync(fullPath)) {
+      contents.push(fs.readFileSync(fullPath, 'utf-8'));
+    }
+  }
+
+  return contents.length > 0 ? contents.join('\n') : null;
+}

package/vendored/lib/preprocess-mdx.ts

@@ -768,13 +768,15 @@ function transformImageDimensionsInText(text: string): string {
 
   return text.replace(pattern, (_match, alt, url, width, height) => {
     const escapedAlt = (alt as string).replace(/"/g, '"');
-    // Center images with explicit dimensions using mx-auto and block display
-    const attrs = [`src="${url}"`, `alt="${escapedAlt}"`, `className="mx-auto block"`];
+    // Use <SizedImage> (registered in MDXComponents) instead of raw <img>.
+    // Raw <img> JSX in MDX bypasses the component provider, so these images
+    // wouldn't get ZoomableImage, ImagePriorityProvider, or loading attributes.
+    const attrs = [`src="${url}"`, `alt="${escapedAlt}"`];
 
     if (width) attrs.push(`width="${width}"`);
     if (height) attrs.push(`height="${height}"`);
 
-    return `<img ${attrs.join(' ')} />`;
+    return `<SizedImage ${attrs.join(' ')} />`;
   });
 }
 

package/vendored/lib/r2-content.ts

@@ -62,4 +62,6 @@ export interface AssetResult {
 
 export async function fetchAsset(_projectSlug: string, _assetPath: string): Promise<AssetResult | null> { return null; }
 export async function fetchStaticFile(_projectSlug: string, _filename: string): Promise<string | null> { return null; }
+export async function fetchCustomCss(_projectSlug: string): Promise<string | null> { return null; }
+export async function fetchCustomJs(_projectSlug: string): Promise<string | null> { return null; }
 export function setR2Client(_client: unknown): void {}

package/vendored/lib/redirect-matcher.ts

@@ -60,6 +60,37 @@ function compileRedirectPatterns(rules: RedirectRule[]): void {
   }
 }
 
+/**
+ * Clear cached redirects for a project (or all projects).
+ * Called during revalidation to pick up updated _redirects.json from R2.
+ */
+export async function clearRedirectCache(projectName?: string): Promise<void> {
+  if (!redis) return;
+  try {
+    if (projectName) {
+      await redis.del(`${CACHE_PREFIX}${projectName}`);
+    } else {
+      // Scan for all redirect cache keys and delete them
+      const keys: string[] = [];
+      let cursor = '0';
+      do {
+        const result: [string, string[]] = await redis.scan(cursor, { match: `${CACHE_PREFIX}*`, count: 100 });
+        cursor = result[0];
+        keys.push(...result[1]);
+      } while (cursor !== '0');
+      if (keys.length > 0) {
+        const pipeline = redis.pipeline();
+        for (const key of keys) {
+          pipeline.del(key);
+        }
+        await pipeline.exec();
+      }
+    }
+  } catch {
+    // Ignore cache clear errors
+  }
+}
+
 /**
  * Fetch redirects for a project from R2 with Redis caching
  * Returns null if no redirects file or error (fail open)

package/vendored/lib/revalidation-helpers.ts

@@ -11,6 +11,8 @@ import { clearSnippetCache } from './snippet-compiler-isr';
 import { clearOpenApiCache } from './openapi-isr';
 import { clearProjectCache as clearMcpProjectCache, clearCache as clearMcpCache } from './mcp-search';
 import { clearNavigationCache } from './navigation-resolver';
+import { STATIC_REVALIDATION_PATHS } from './static-file-route';
+import { clearRedirectCache } from './redirect-matcher';
 
 /**
  * Validate the revalidation secret using constant-time comparison.
@@ -123,6 +125,7 @@ export async function executeRevalidation(
     clearSnippetCache(request.project);
     clearOpenApiCache(request.project);
     clearMcpProjectCache(request.project);
+    await clearRedirectCache(request.project);
     clearNavigationCache(); // Navigation cache keys include project name, clear all for simplicity
     revalidated.push(`cache:${request.project}`);
   }
@@ -160,8 +163,15 @@ export async function executeRevalidation(
     clearOpenApiCache();
     clearMcpCache();
     clearNavigationCache();
+    await clearRedirectCache();
     if (revalidatePath) {
       revalidatePath('/', 'layout');
+      // Also purge CDN cache for static file routes (sitemap, robots, llms.txt, etc.)
+      // These are route handlers with s-maxage caching that revalidatePath('/', 'layout') doesn't cover
+      for (const p of STATIC_REVALIDATION_PATHS) {
+        revalidatePath(p);
+        revalidated.push(`path:${p}`);
+      }
     }
     revalidated.push('all');
   }

package/vendored/lib/revalidation-trigger.ts

@@ -100,6 +100,7 @@ async function revalidateProxy(secret: string, projectSlug: string): Promise<voi
 export interface Manifest {
   files: Record<string, { hash: string }>;
   openapi?: Record<string, { hash: string }>;
+  configHash?: string;
 }
 
 /** Compare manifests and return paths that changed (without .mdx extension). */
@@ -129,9 +130,12 @@ export function getChangedPaths(
     }
   }
 
-  // When only OpenAPI specs changed (no MDX changes), revalidate all pages
-  // because we can't know which pages reference the changed spec
-  if (changed.length === 0 && hasOpenapiChanges(oldManifest, newManifest)) {
+  // When config or OpenAPI specs changed (no MDX changes), revalidate all pages.
+  // Config changes (e.g., _hasCustomJs flag) affect every page's layout.
+  // OpenAPI changes can affect any endpoint page.
+  if (changed.length === 0 &&
+    (oldManifest.configHash !== newManifest.configHash ||
+     hasOpenapiChanges(oldManifest, newManifest))) {
     return Object.keys(newManifest.files).map(p => p.replace('.mdx', ''));
   }
 

package/vendored/lib/seo.ts

@@ -23,6 +23,13 @@ export function buildSiteTitle(configName: string): string {
     : `${configName} Documentation`;
 }
 
+/** Resolve a Logo or Favicon config to a path string, preferring light variant. */
+function resolveImagePath(image?: Logo | Favicon): string {
+  if (!image) return '';
+  if (typeof image === 'string') return image;
+  return (image as LogoConfig).light || (image as LogoConfig).dark || '';
+}
+
 /**
  * Build the OG image URL for a page using the proxy's /api/og endpoint.
  * Returns undefined if og:image is explicitly set in metatags.
@@ -36,7 +43,6 @@ function buildOgImageUrl(
     section?: string;
     logo?: Logo;
     favicon?: Favicon;
-    theme?: 'light' | 'dark';
   }
 ): string {
   const params = new URLSearchParams();
@@ -49,10 +55,6 @@ function buildOgImageUrl(
   if (options?.section) {
     params.set('section', options.section);
   }
-  if (options?.theme) {
-    params.set('theme', options.theme);
-  }
-
   // For hostAtDocs sites (baseUrl ends with /docs), use the parent domain with
   // /_jd/og path instead of cross-domain /api/og. LinkedIn's crawler fails to
   // fetch OG images from different domains. The /_jd/og path is proxied through
@@ -60,24 +62,13 @@ function buildOgImageUrl(
   const isHostAtDocs = baseUrl.endsWith('/docs');
   const rootUrl = baseUrl.replace(/\/docs$/, '');
 
-  // Handle logo - prefer dark variant for OG images (dark background)
+  // Handle logo - prefer light variant for OG images (cream background)
   // Satori (@vercel/og) can't render webp, so fall back to favicon if logo is webp
   if (options?.logo || options?.favicon) {
-    let logoPath = '';
-    if (options?.logo) {
-      if (typeof options.logo === 'string') {
-        logoPath = options.logo;
-      } else {
-        logoPath = (options.logo as LogoConfig).dark || (options.logo as LogoConfig).light;
-      }
-    }
+    let logoPath = resolveImagePath(options?.logo);
     // Fall back to favicon when logo is webp (Satori can't decode webp)
     if ((!logoPath || logoPath.endsWith('.webp')) && options?.favicon) {
-      if (typeof options.favicon === 'string') {
-        logoPath = options.favicon;
-      } else {
-        logoPath = (options.favicon as FaviconConfig).dark || (options.favicon as FaviconConfig).light;
-      }
+      logoPath = resolveImagePath(options.favicon);
     }
     // Make logo URL absolute (use root URL since assets are at domain root)
     if (logoPath && !logoPath.startsWith('http')) {
@@ -242,7 +233,6 @@ export function buildSeoMetadata(
         section: frontmatter.section,
         logo: config.logo,
         favicon: config.favicon,
-        theme: 'dark', // Dark theme looks better for OG images
       }
     );
 

package/vendored/lib/static-artifacts.ts

@@ -5,6 +5,9 @@
  * for ISR projects. These are uploaded to R2 alongside the MDX content.
  */
 
+import type { NavigationConfig } from './docs-types.js';
+import { RECURSE_KEYS } from './enhance-navigation.js';
+
 /**
  * Page metadata for artifact generation.
  */
@@ -206,6 +209,46 @@ export function extractPageMetadata(pages: RawPageInfo[]): PageMetadata[] {
   });
 }
 
+/**
+ * Recursively extract all page paths from a docs.json navigation tree.
+ * Used to filter sitemap/llms.txt to only include pages referenced in navigation.
+ */
+export function extractNavigationPaths(
+  navigation: NavigationConfig | undefined,
+): Set<string> {
+  const paths = new Set<string>();
+  if (!navigation) return paths;
+
+  function walkNode(node: Record<string, unknown>): void {
+    if (Array.isArray(node.pages)) {
+      for (const item of node.pages) {
+        if (typeof item === 'string') {
+          paths.add(item);
+        } else if (typeof item === 'object' && item !== null) {
+          const obj = item as Record<string, unknown>;
+          if (typeof obj.page === 'string') {
+            paths.add(obj.page);
+          }
+          if ('group' in obj) {
+            walkNode(obj);
+          }
+        }
+      }
+    }
+
+    for (const key of RECURSE_KEYS) {
+      if (Array.isArray(node[key])) {
+        for (const child of node[key] as Record<string, unknown>[]) {
+          walkNode(child);
+        }
+      }
+    }
+  }
+
+  walkNode(navigation as Record<string, unknown>);
+  return paths;
+}
+
 /**
  * Options for generating all artifacts.
  */

package/vendored/lib/static-file-route.ts

@@ -12,6 +12,16 @@ import { log } from '@/lib/logger';
 import { isIsrMode } from '@/lib/page-isr-helpers';
 import { fetchStaticFile } from '@/lib/r2-content';
 
+/** Filenames served via createStaticFileHandler (5 at root + 5 at /docs). */
+export const STATIC_FILE_NAMES = [
+  'sitemap.xml', 'robots.txt', 'llms.txt', 'feed.xml', 'search-data.json',
+] as const;
+
+/** All CDN paths for static file routes — used by revalidation to purge CDN cache. */
+export const STATIC_REVALIDATION_PATHS = STATIC_FILE_NAMES.flatMap(
+  f => [`/${f}`, `/docs/${f}`]
+);
+
 const CONTENT_TYPES: Record<string, string> = {
   '.xml': 'application/xml',
   '.json': 'application/json',
@@ -41,7 +51,7 @@ export function createStaticFileHandler(
   cacheControlOverride?: string
 ): (request: NextRequest) => Promise<NextResponse> {
   const contentType = contentTypeOverride || getContentType(filename);
-  const cacheControl = cacheControlOverride || 'public, max-age=3600, s-maxage=86400';
+  const cacheControl = cacheControlOverride || 'public, max-age=3600, s-maxage=3600';
 
   return async function GET(request: NextRequest): Promise<NextResponse> {
     if (!isIsrMode()) {