jamdesk 1.0.19 → 1.0.21

package/vendored/hooks/useBodyScrollLock.ts

@@ -0,0 +1,37 @@
+'use client';
+
+import { useEffect } from 'react';
+
+let lockCount = 0;
+let savedOverflow = '';
+let savedPaddingRight = '';
+
+/**
+ * Lock body scroll when `active` is true. Multiple concurrent locks
+ * are ref-counted — body scroll is only restored when all locks release.
+ * Compensates for scrollbar removal to prevent layout shift.
+ */
+export function useBodyScrollLock(active: boolean): void {
+  useEffect(() => {
+    if (!active) return;
+
+    if (lockCount === 0) {
+      const scrollbarWidth = window.innerWidth - document.documentElement.clientWidth;
+      savedOverflow = document.body.style.overflow;
+      savedPaddingRight = document.body.style.paddingRight;
+      document.body.style.overflow = 'hidden';
+      if (scrollbarWidth > 0) {
+        document.body.style.paddingRight = `${scrollbarWidth}px`;
+      }
+    }
+    lockCount++;
+
+    return () => {
+      lockCount--;
+      if (lockCount === 0) {
+        document.body.style.overflow = savedOverflow;
+        document.body.style.paddingRight = savedPaddingRight;
+      }
+    };
+  }, [active]);
+}

package/vendored/lib/analytics-client.ts

@@ -2,17 +2,28 @@
 // Tracks search queries and clicks for analytics dashboard
 
 // Firebase Function URL for search analytics
-const ANALYTICS_URL = 'https://us-central1-jamdesk-prod.cloudfunctions.net/trackSearchAnalytics';
+const ANALYTICS_URL = '/api/search-ev';
+
+// Reuse the same session ID as the pageview tracking script (localStorage with 30-min inactivity timeout).
+// Every call refreshes the timestamp, so active users keep the same session.
+const SESSION_TIMEOUT_MS = 1800000; // 30 minutes
 
-// Session ID persists for the browser session
 function getSessionId(): string {
   if (typeof window === 'undefined') return 'ssr';
 
-  let sessionId = sessionStorage.getItem('jd_session_id');
-  if (!sessionId) {
-    sessionId = `${Date.now()}-${Math.random().toString(36).slice(2, 11)}`;
-    sessionStorage.setItem('jd_session_id', sessionId);
+  const now = Date.now();
+  let sessionId = localStorage.getItem('jamdesk_session_id');
+  const sessionTs = localStorage.getItem('jamdesk_session_ts');
+
+  if (!sessionId || !sessionTs || (now - parseInt(sessionTs)) >= SESSION_TIMEOUT_MS) {
+    // Match the tracking script's format: 16 random bytes as hex + timestamp in base36
+    const bytes = new Uint8Array(16);
+    crypto.getRandomValues(bytes);
+    sessionId = Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('') +
+      now.toString(36);
+    localStorage.setItem('jamdesk_session_id', sessionId);
   }
+  localStorage.setItem('jamdesk_session_ts', now.toString());
   return sessionId;
 }
 
@@ -67,7 +78,6 @@ export function trackSearch(event: SearchEvent): void {
       headers: { 'Content-Type': 'application/json' },
       body: payload,
       keepalive: true,
-      mode: 'cors',
     }).catch(() => {
       // Silent fail - analytics should never break the app
     });

package/vendored/lib/docs-types.ts

@@ -467,6 +467,7 @@ export interface PageFrontmatter {
   api?: string;
   openapi?: string;
   hideFooter?: boolean;
+  rss?: boolean;
 }
 
 // =============================================================================
@@ -594,7 +595,7 @@ export interface IntegrationsConfig {
   osano?: { scriptSource: string };
   pirsch?: { id: string };
   posthog?: { apiKey: string; apiHost?: string };
-  plausible?: { domain: string; server?: string };
+  plausible?: { domain?: string; server?: string; scriptUrl?: string };
   segment?: { key: string };
   telemetry?: { enabled: boolean };
   cookies?: { key?: string; value?: string };
@@ -621,7 +622,7 @@ export interface SearchConfig {
  * AI Chat configuration
  */
 export interface ChatConfig {
-  /** Enable AI chat assistant (default: false) */
+  /** Enable AI chat assistant (default: true) */
   enabled?: boolean;
   /** Starter questions shown in empty state (max 4). Auto-generated by Haiku during builds when omitted. Set to [] to disable. */
   starterQuestions?: string[];

package/vendored/lib/email-templates/components/base-layout.tsx

@@ -24,16 +24,16 @@ const darkModeStyles = `
 @media (prefers-color-scheme: dark) {
   .email-logo-light { display: none !important; }
   .email-logo-dark { display: block !important; }
-  .email-body { background-color: #0A1628 !important; }
-  .email-container { background-color: #111827 !important; }
-  .email-content { background-color: #111827 !important; }
-  .email-footer { background-color: #111827 !important; border-color: #374151 !important; }
-  .email-title { color: #F9FAFB !important; }
-  .email-paragraph { color: #E5E7EB !important; }
-  .email-footer-text { color: #9CA3AF !important; }
+  .email-body { background-color: #181210 !important; }
+  .email-container { background-color: #2c2420 !important; }
+  .email-content { background-color: #2c2420 !important; }
+  .email-footer { background-color: #2c2420 !important; border-color: #3a302a !important; }
+  .email-title { color: #f0ebe5 !important; }
+  .email-paragraph { color: #c4b8ac !important; }
+  .email-footer-text { color: #9a8e82 !important; }
 
-  /* Prevent white text inversion on indigo elements */
-  .email-button { color: #ffffff !important; background-color: #635BFF !important; }
+  /* Prevent white text inversion on accent elements */
+  .email-button { color: #ffffff !important; background-color: #ff3621 !important; }
 
   /* Error box */
   .email-error-box { background-color: #450a0a !important; border-color: #dc2626 !important; }
@@ -52,13 +52,13 @@ export interface BaseLayoutProps {
 
 // Muted dashboard style guide colors
 export const colors = {
-  primary: '#635BFF',      // Indigo
-  primaryMuted: '#9966FF', // Purple accent
-  background: '#F6F9FC',   // bg-primary
+  primary: '#ff3621',      // Warm red
+  primaryMuted: '#ff3621', // Warm red
+  background: '#faf8f5',   // bg-primary
   cardBg: '#ffffff',       // bg-secondary
-  textPrimary: '#0A2540',  // primary-navy
-  textSecondary: '#425466', // text-secondary
-  border: '#E3E8EE',       // border-primary
+  textPrimary: '#1b3139',  // primary-navy
+  textSecondary: '#5a6f77', // text-secondary
+  border: '#e8e4df',       // border-primary
   // Error colors (used by ErrorBox component)
   errorBg: '#FEF2F2',
   errorBorder: '#EF4444',

package/vendored/lib/extract-highlights.ts

@@ -11,6 +11,7 @@ export interface ExtractedHighlights {
   seoIndexable: boolean;
   analyticsIntegrations: string[];
   apiPlaygroundType: 'interactive' | 'simple' | 'hidden' | null;
+  chatEnabled: boolean;
   languageCount: number;
   redirectCount: number;
   pageCount: number;
@@ -115,6 +116,7 @@ export function extractConfigHighlights(config: DocsConfig, pageCount: number =
     seoIndexable,
     analyticsIntegrations,
     apiPlaygroundType,
+    chatEnabled: config.chat?.enabled !== false,
     languageCount: countLanguages(config),
     redirectCount: config.redirects?.length ?? 0,
     pageCount,

package/vendored/lib/heading-extractor.ts

@@ -2,7 +2,7 @@
  * Heading extractor for link validation.
  * Extracts heading slugs from MDX content to validate #fragment links.
  *
- * Uses the same slug generation as TableOfContents.tsx (client-side DOM IDs).
+ * Canonical source for generateSlug — imported by TableOfContents.tsx and Update.tsx.
  */
 
 export interface HeadingInfo {
@@ -14,7 +14,7 @@ export interface HeadingInfo {
 
 /**
  * Generate a URL-friendly slug from heading text.
- * Must stay in sync with TableOfContents.tsx:207-209.
+ * Canonical implementation — also duplicated in validate-links.cjs (CJS, can't import).
  */
 export function generateSlug(text: string): string {
   return text

package/vendored/lib/indexnow.ts

@@ -0,0 +1,77 @@
+/**
+ * IndexNow URL Submission for Documentation Sites
+ *
+ * Notifies search engines about changed pages after builds.
+ * Modeled after marketing/lib/indexnow.ts but parameterized for
+ * multi-tenant use (dynamic host/key per project).
+ */
+
+import { createHash } from 'crypto';
+
+const INDEXNOW_ENDPOINT = 'https://api.indexnow.org/indexnow';
+const FETCH_TIMEOUT_MS = 5_000;
+const MAX_BATCH_SIZE = 10_000;
+const KEY_SALT = 'jamdesk-indexnow-v1';
+
+export interface IndexNowResult {
+  success: boolean;
+  status: number;
+  submitted: number;
+}
+
+/** IndexNow accepts both 200 (OK) and 202 (Accepted) as success. */
+function isSuccessStatus(status: number): boolean {
+  return status === 200 || status === 202;
+}
+
+/** Deterministic IndexNow key for a project (32-char hex). */
+export function generateIndexNowKey(projectSlug: string): string {
+  return createHash('md5').update(`${KEY_SALT}:${projectSlug}`).digest('hex');
+}
+
+/** Build full URLs from changed content paths. */
+export function buildChangedUrls(
+  changedPaths: string[], baseUrl: string, hostAtDocs: boolean
+): string[] {
+  if (changedPaths.length === 0) return [];
+  const prefix = hostAtDocs ? '/docs' : '';
+  return changedPaths.map((p) => {
+    // Defensive: getChangedPaths() already strips extensions, but guard against raw file paths
+    const clean = p.replace(/\.mdx?$/, '');
+    return `${baseUrl}${prefix}/${clean}`;
+  });
+}
+
+/** Submit URLs to IndexNow. Single URL uses GET, multiple uses batch POST. */
+export async function submitToIndexNow(
+  urls: string[], host: string, key: string
+): Promise<IndexNowResult> {
+  if (urls.length === 0) {
+    return { success: true, status: 200, submitted: 0 };
+  }
+
+  const timeoutSignal = AbortSignal.timeout(FETCH_TIMEOUT_MS);
+
+  if (urls.length === 1) {
+    const params = new URLSearchParams({ url: urls[0], key });
+    const res = await fetch(`${INDEXNOW_ENDPOINT}?${params}`, {
+      signal: timeoutSignal,
+    });
+    return { success: isSuccessStatus(res.status), status: res.status, submitted: 1 };
+  }
+
+  const submitted = Math.min(urls.length, MAX_BATCH_SIZE);
+  const res = await fetch(INDEXNOW_ENDPOINT, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json; charset=utf-8' },
+    signal: timeoutSignal,
+    body: JSON.stringify({
+      host,
+      key,
+      keyLocation: `https://${host}/api/indexnow/${key}`,
+      urlList: urls.slice(0, MAX_BATCH_SIZE),
+    }),
+  });
+
+  return { success: isSuccessStatus(res.status), status: res.status, submitted };
+}

package/vendored/lib/json-ld.ts

@@ -0,0 +1,171 @@
+/**
+ * JSON-LD Structured Data for Documentation Pages
+ *
+ * Generates WebSite + BreadcrumbList schemas for search engine rich results.
+ * Rendered as <script type="application/ld+json"> in page.tsx.
+ *
+ * Breadcrumb path extraction is server-side only (pure functions, no hooks).
+ * Intentionally separate from Breadcrumb.tsx which is a 'use client' component.
+ */
+
+import type { DocsConfig, NavigationPage, GroupConfig } from './docs-types';
+import { normalizeNavPage } from './docs-types';
+
+interface BreadcrumbEntry {
+  name: string;
+  url: string;
+}
+
+export interface JsonLdOptions {
+  config: DocsConfig;
+  pagePath: string;
+  pageTitle: string;
+  baseUrl: string;
+}
+
+export interface JsonLdGraph {
+  '@context': string;
+  '@graph': Array<Record<string, unknown>>;
+}
+
+function formatSlugAsTitle(slug: string): string {
+  const lastSegment = slug.split('/').pop()!;
+  return lastSegment
+    .replace(/-/g, ' ')
+    .replace(/\b\w/g, (l) => l.toUpperCase());
+}
+
+/**
+ * Find the first leaf page path in a list of navigation items.
+ * Recurses into nested groups until it finds a non-group page.
+ */
+function getFirstPage(pages: (NavigationPage | GroupConfig)[]): string | null {
+  for (const item of pages) {
+    if (typeof item === 'object' && 'group' in item) {
+      if (item.pages) {
+        const found = getFirstPage(item.pages);
+        if (found) return found;
+      }
+    } else {
+      return normalizeNavPage(item).path;
+    }
+  }
+  return null;
+}
+
+/** Build a group's URL from its first page, falling back to baseUrl. */
+function buildGroupUrl(group: GroupConfig, baseUrl: string): string {
+  const firstPage = group.pages ? getFirstPage(group.pages) : null;
+  return firstPage ? `${baseUrl}/${firstPage}` : baseUrl;
+}
+
+/**
+ * Find the breadcrumb path for a page by walking the navigation tree.
+ * Returns [{name, url}] from Home -> group(s) -> current page.
+ */
+export function findBreadcrumbPath(
+  config: DocsConfig, targetSlug: string, baseUrl: string, pageTitle?: string
+): BreadcrumbEntry[] {
+  const nav = config.navigation;
+  const home: BreadcrumbEntry = { name: 'Home', url: baseUrl };
+  const pageEntry: BreadcrumbEntry = {
+    name: pageTitle || formatSlugAsTitle(targetSlug),
+    url: `${baseUrl}/${targetSlug}`,
+  };
+
+  function searchPages(
+    pages: (NavigationPage | GroupConfig)[], trail: BreadcrumbEntry[]
+  ): BreadcrumbEntry[] | null {
+    for (const item of pages) {
+      if (typeof item === 'object' && 'group' in item) {
+        const groupUrl = buildGroupUrl(item, baseUrl);
+        const next = [...trail, { name: item.group, url: groupUrl }];
+        if (item.pages) {
+          const found = searchPages(item.pages, next);
+          if (found) return found;
+        }
+      } else {
+        if (normalizeNavPage(item).path === targetSlug) return trail;
+      }
+    }
+    return null;
+  }
+
+  function searchGroups(groups: GroupConfig[]): BreadcrumbEntry[] | null {
+    for (const group of groups) {
+      const groupUrl = buildGroupUrl(group, baseUrl);
+      const trail = [{ name: group.group, url: groupUrl }];
+      if (group.pages) {
+        const found = searchPages(group.pages, trail);
+        if (found) return found;
+      }
+    }
+    return null;
+  }
+
+  // Search all navigation structures (mirrors Breadcrumb.tsx order)
+  let trail: BreadcrumbEntry[] | null = null;
+
+  if (!trail && nav.languages) {
+    for (const lang of nav.languages) {
+      if (!lang.tabs) continue;
+      for (const tab of lang.tabs) {
+        if (tab.groups) trail = searchGroups(tab.groups);
+        if (trail) break;
+      }
+      if (trail) break;
+    }
+  }
+  if (!trail && nav.anchors) {
+    for (const anchor of nav.anchors) {
+      if (anchor.groups) trail = searchGroups(anchor.groups);
+      if (trail) break;
+    }
+  }
+  if (!trail && nav.tabs) {
+    for (const tab of nav.tabs) {
+      if (tab.groups) trail = searchGroups(tab.groups);
+      if (trail) break;
+    }
+  }
+  if (!trail && nav.groups) {
+    trail = searchGroups(nav.groups);
+  }
+
+  // Deduplicate: remove group entries whose URL matches the next entry.
+  // Groups link to their first page, which may be the current page itself.
+  const result = [home, ...(trail || []), pageEntry];
+  return result.filter((entry, i) =>
+    i === result.length - 1 || entry.url !== result[i + 1]?.url
+  );
+}
+
+/**
+ * Build JSON-LD structured data for a documentation page.
+ * Returns a schema.org @graph with WebSite + BreadcrumbList.
+ */
+export function buildJsonLd(options: JsonLdOptions): JsonLdGraph {
+  const { config, pagePath, pageTitle, baseUrl } = options;
+  const breadcrumbs = findBreadcrumbPath(config, pagePath, baseUrl, pageTitle);
+
+  return {
+    '@context': 'https://schema.org',
+    '@graph': [
+      {
+        '@type': 'WebSite',
+        name: config.name,
+        url: baseUrl,
+        ...(config.description && { description: config.description }),
+      },
+      {
+        '@type': 'BreadcrumbList',
+        itemListElement: breadcrumbs.map((item, i) => ({
+          '@type': 'ListItem',
+          position: i + 1,
+          name: item.name,
+          item: item.url,
+        })),
+      },
+    ],
+  };
+}

package/vendored/lib/middleware-helpers.ts

@@ -286,12 +286,14 @@ export async function checkRedirects(
 export const INTERNAL_API_ROUTES = [
   '/api/assets',     // Asset serving from R2 (app/api/assets/[...path])
   '/api/ev',         // Analytics events (app/api/ev)
+  '/api/indexnow',   // IndexNow key verification (app/api/indexnow/[key])
   '/api/isr-health', // Health check endpoint (app/api/isr-health)
   '/api/chat',       // Chat endpoint (app/api/chat/[project])
   '/api/mcp',        // MCP endpoint (app/api/mcp/[project])
   '/api/og',         // OG image generation (app/api/og)
   '/api/r2',         // R2 content serving (app/api/r2/[project]/[...path])
   '/api/revalidate', // Cache revalidation (app/api/revalidate)
+  '/api/search-ev',  // Search analytics proxy (app/api/search-ev)
 ];
 
 /**

package/vendored/lib/openapi/errors.ts

@@ -81,6 +81,26 @@ export function formatOpenApiError(
     };
   }
   
+  // Network/fetch error (URL validation) — check before "invalid" pattern
+  // since URLs may contain "invalid" in the domain name
+  if (
+    message.includes('ENOTFOUND') ||
+    message.includes('ECONNREFUSED') ||
+    message.includes('getaddrinfo') ||
+    message.includes('ETIMEDOUT') ||
+    message.includes('request to') ||
+    message.includes('fetch failed') ||
+    message.includes('Error downloading')
+  ) {
+    return {
+      type: 'validation_error',
+      specPath,
+      message: `Failed to fetch OpenAPI specification: ${specPath}`,
+      suggestion: 'Check that the URL is correct and the server is accessible.',
+      details: message,
+    };
+  }
+
   // Invalid type or value
   if (message.includes('type') || message.includes('must be') || message.includes('invalid')) {
     return {
@@ -91,7 +111,7 @@ export function formatOpenApiError(
       details: message,
     };
   }
-  
+
   // Generic validation error
   return {
     type: 'validation_error',

package/vendored/lib/openapi/validator.ts

@@ -9,7 +9,7 @@ import SwaggerParser from '@apidevtools/swagger-parser';
 import fs from 'fs';
 import path from 'path';
 import type { OpenAPI } from 'openapi-types';
-import type { ValidationResult } from './types';
+import type { ValidationResult, OpenApiValidationError } from './types';
 import { formatOpenApiError, createFileNotFoundError } from './errors';
 
 /**
@@ -32,12 +32,49 @@ function detectVersion(api: OpenAPI.Document): '2.0' | '3.0' | '3.1' {
 }
 
 /**
- * Validate an OpenAPI specification file
- * 
+ * Check for duplicate operationIds across all endpoints.
+ * SwaggerParser.validate() does not catch these, but they break
+ * docs navigation and routing.
+ */
+function checkDuplicateOperationIds(
+  api: OpenAPI.Document,
+  specPath: string
+): OpenApiValidationError | null {
+  const seen = new Map<string, string>(); // operationId → "METHOD /path"
+  const paths = (api as any).paths || {};
+  const methods = ['get', 'post', 'put', 'patch', 'delete', 'head', 'options'];
+
+  for (const [pathStr, pathItem] of Object.entries(paths)) {
+    for (const method of methods) {
+      const operation = (pathItem as Record<string, any>)?.[method];
+      if (!operation?.operationId) continue;
+
+      const id = operation.operationId;
+      const endpoint = `${method.toUpperCase()} ${pathStr}`;
+
+      if (seen.has(id)) {
+        return {
+          type: 'validation_error',
+          specPath,
+          message: `Duplicate operationId "${id}" in OpenAPI specification: ${specPath}`,
+          suggestion: `operationId "${id}" is used by both ${seen.get(id)} and ${endpoint}. Each operationId must be unique.`,
+        };
+      }
+
+      seen.set(id, endpoint);
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Validate an OpenAPI specification file or URL
+ *
  * This validates the spec against the OpenAPI schema and resolves all $ref references.
  * The returned api object has all references dereferenced (inlined).
- * 
- * @param specPath - Path to the spec file (relative to projectDir)
+ *
+ * @param specPath - Path to the spec file (relative to projectDir) or a URL
  * @param projectDir - Project root directory
  * @returns Validation result with dereferenced API document if valid
  */
@@ -45,33 +82,43 @@ export async function validateOpenApiSpec(
   specPath: string,
   projectDir: string
 ): Promise<ValidationResult> {
-  // Normalize the spec path (remove leading slash if present)
-  const normalizedPath = specPath.startsWith('/') ? specPath.slice(1) : specPath;
-  const fullPath = path.join(projectDir, normalizedPath);
-  
-  // Check file exists first (better error message than swagger-parser's)
-  if (!fs.existsSync(fullPath)) {
-    return {
-      valid: false,
-      error: createFileNotFoundError(specPath),
-    };
+  const isUrl = specPath.startsWith('http://') || specPath.startsWith('https://');
+
+  let target: string;
+
+  if (isUrl) {
+    // SwaggerParser.validate() natively supports URLs
+    target = specPath;
+  } else {
+    const normalizedPath = specPath.startsWith('/') ? specPath.slice(1) : specPath;
+    target = path.join(projectDir, normalizedPath);
+
+    if (!fs.existsSync(target)) {
+      return {
+        valid: false,
+        error: createFileNotFoundError(specPath),
+      };
+    }
   }
-  
+
   try {
-    // Validate AND dereference in one step
-    // This throws if validation fails
-    const api = await SwaggerParser.validate(fullPath) as OpenAPI.Document;
-    
+    const api = await SwaggerParser.validate(target) as OpenAPI.Document;
+
     const version = detectVersion(api);
-    
-    // Warn about Swagger 2.0
+
     if (version === '2.0') {
       console.warn(
         `Note: ${specPath} uses OpenAPI 2.0 (Swagger). ` +
         `Consider upgrading to OpenAPI 3.0+ for full feature support.`
       );
     }
-    
+
+    // Check for duplicate operationIds (swagger-parser doesn't catch these)
+    const duplicateError = checkDuplicateOperationIds(api, specPath);
+    if (duplicateError) {
+      return { valid: false, error: duplicateError };
+    }
+
     return {
       valid: true,
       api,

package/vendored/lib/route-helpers.ts

@@ -5,6 +5,11 @@
 import { redis } from './redis';
 import { isCustomDomain, parseRedisConfig } from './domain-helpers';
 
+const analyticsHeaders = {
+  'Content-Type': 'application/json',
+  'X-Analytics-Secret': process.env.ANALYTICS_SECRET || '',
+};
+
 /**
  * Resolve docsPath for a project ('' or '/docs').
  * Queries Redis for projectCfg: or domainCfg: keys to determine hostAtDocs.
@@ -51,7 +56,7 @@ export async function trackServerAnalytics(params: {
   try {
     await fetch(trackingUrl, {
       method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
+      headers: analyticsHeaders,
       body: JSON.stringify({
         ...params,
         sessionId: `${params.source}-${Date.now()}`,
@@ -80,7 +85,7 @@ export async function trackChatAnalytics(params: {
   userAgent?: string;
 }): Promise<void> {
   const trackingUrl = process.env.CHAT_TRACKING_URL || 'https://us-central1-jamdesk-prod.cloudfunctions.net/trackChatAnalytics';
-  const headers: Record<string, string> = { 'Content-Type': 'application/json' };
+  const headers: Record<string, string> = {...analyticsHeaders};
   if (params.userAgent) {
     headers['User-Agent'] = params.userAgent;
   }