jamdesk 1.0.20 → 1.0.21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jamdesk",
-  "version": "1.0.20",
+  "version": "1.0.21",
   "description": "CLI for Jamdesk — build, preview, and deploy documentation sites from MDX. Dev server with hot reload, 50+ components, OpenAPI support, AI search, and Mintlify migration",
   "keywords": [
     "jamdesk",

package/vendored/app/[[...slug]]/page.tsx

@@ -47,7 +47,7 @@ import fs from 'fs';
 import path from 'path';
 import matter from 'gray-matter';
 import { getDocsConfig, getContentDir } from '@/lib/docs';
-import { buildSeoMetadata, generateAutoDescription } from '@/lib/seo';
+import { buildSeoMetadata, generateAutoDescription, buildSiteTitle } from '@/lib/seo';
 import { buildJsonLd } from '@/lib/json-ld';
 import {
   getContentLoader,
@@ -339,7 +339,7 @@ export async function generateMetadata({ params }: PageProps) {
   if (normalizedSlug.length === 0) {
     const config = await loader.getConfig();
     return {
-      title: `${config.name} - Redirecting...`,
+      title: { absolute: `${config.name} - Redirecting...` },
       robots: { index: false }, // Don't index redirect page
     };
   }
@@ -372,8 +372,14 @@ export async function generateMetadata({ params }: PageProps) {
 
   const seoMetadata = buildSeoMetadata(config, data, pagePath, baseUrl, languages);
 
+  // If page title matches config.name, use absolute to prevent "X — X" double-wrap.
+  // If no title, use buildSiteTitle (which avoids "X Documentation Documentation").
+  const titleValue = data.title
+    ? (data.title === config.name ? { absolute: data.title } : data.title)
+    : { absolute: buildSiteTitle(config.name) };
+
   return {
-    title: data.title || `${config.name} Documentation`,
+    title: titleValue,
     description: data.description || '',
     ...seoMetadata,
     ...(data.rss ? {

package/vendored/app/api/search-ev/route.ts

@@ -0,0 +1,69 @@
+/**
+ * Search Analytics Event Proxy
+ * Proxies to Firebase Cloud Functions via first-party domain to avoid ad blockers
+ * and CORS issues. Mirrors /api/ev but targets the search analytics function.
+ */
+
+import { NextRequest, NextResponse } from 'next/server';
+
+const ANALYTICS_ENDPOINT = 'https://us-central1-jamdesk-prod.cloudfunctions.net/trackSearchAnalytics';
+const TIMEOUT_MS = 5000;
+
+export const runtime = 'edge';
+
+export async function POST(request: NextRequest) {
+  try {
+    const body = await request.json();
+
+    // Forward geo headers from Vercel + User-Agent for bot detection
+    const headers: HeadersInit = {
+      'Content-Type': 'application/json',
+      'X-Analytics-Secret': process.env.ANALYTICS_SECRET || '',
+    };
+    const userAgent = request.headers.get('user-agent');
+    if (userAgent) {
+      headers['User-Agent'] = userAgent;
+    }
+    const forwardHeaders = ['x-vercel-ip-country', 'x-vercel-ip-city', 'x-forwarded-for'];
+    for (const h of forwardHeaders) {
+      const val = request.headers.get(h);
+      if (val) headers[h] = val;
+    }
+
+    // Timeout protection - don't let slow Firebase responses hang the request
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), TIMEOUT_MS);
+
+    const response = await fetch(ANALYTICS_ENDPOINT, {
+      method: 'POST',
+      headers,
+      body: JSON.stringify(body),
+      signal: controller.signal,
+    });
+    clearTimeout(timeout);
+
+    // Handle non-JSON responses (e.g., Firebase error pages)
+    const text = await response.text();
+    try {
+      const data = JSON.parse(text);
+      return NextResponse.json(data, { status: response.status });
+    } catch {
+      console.error('[Search Analytics Proxy] Non-JSON response:', text.slice(0, 200));
+      return NextResponse.json({ success: true, proxied: false });
+    }
+  } catch (error) {
+    console.error('[Search Analytics Proxy] Error:', error);
+    return NextResponse.json({ success: true, proxied: false });
+  }
+}
+
+export async function OPTIONS() {
+  return new NextResponse(null, {
+    status: 204,
+    headers: {
+      'Access-Control-Allow-Origin': '*',
+      'Access-Control-Allow-Methods': 'POST, OPTIONS',
+      'Access-Control-Allow-Headers': 'Content-Type',
+    },
+  });
+}

package/vendored/app/layout.tsx

@@ -17,6 +17,7 @@ import type { DocsConfig, Favicon, FontConfig } from '@/lib/docs-types';
 import { ASSET_PREFIX, transformConfigImagePath } from '@/lib/docs-types';
 import { LinkPrefixProvider } from '@/lib/link-prefix-context';
 import { getAnalyticsScript } from '@/lib/analytics-script';
+import { buildSiteTitle } from '@/lib/seo';
 
 // Pre-load fonts - Next.js will tree-shake unused ones
 const inter = Inter({
@@ -47,6 +48,14 @@ function getFaviconPath(favicon: Favicon | undefined, assetVersion?: string): st
   return transformConfigImagePath(favicon.light, assetVersion) || DEFAULT_FAVICON;
 }
 
+const FALLBACK_METADATA: Metadata = {
+  title: {
+    template: '%s — Documentation',
+    default: 'Documentation',
+  },
+  description: 'Documentation',
+};
+
 export async function generateMetadata(): Promise<Metadata> {
   // Get config - from R2 in ISR mode, from filesystem in static mode
   let config: DocsConfig;
@@ -58,17 +67,10 @@ export async function generateMetadata(): Promise<Metadata> {
       try {
         config = await getIsrDocsConfig(projectSlug);
       } catch {
-        // Project not found - use minimal fallback
-        return {
-          title: 'Documentation',
-          description: 'Documentation',
-        };
+        return FALLBACK_METADATA;
       }
     } else {
-      return {
-        title: 'Documentation',
-        description: 'Documentation',
-      };
+      return FALLBACK_METADATA;
     }
   } else {
     config = getDocsConfig();
@@ -76,7 +78,10 @@ export async function generateMetadata(): Promise<Metadata> {
 
   const faviconPath = getFaviconPath(config.favicon, config.assetVersion);
   return {
-    title: `${config.name} Documentation`,
+    title: {
+      template: `%s — ${config.name}`,
+      default: buildSiteTitle(config.name),
+    },
     description: config.description || `Documentation for ${config.name}`,
     icons: {
       icon: faviconPath,
@@ -217,6 +222,43 @@ async function ConditionalGA({ gaId }: { gaId: string }) {
   }
 }
 
+// Render Plausible Analytics — supports standard (data-domain) and paid proxy (scriptUrl) modes
+function PlausibleScript({
+  domain,
+  server,
+  scriptUrl,
+}: {
+  domain?: string;
+  server?: string;
+  scriptUrl?: string;
+}): React.ReactElement {
+  // Paid proxy script mode (pa-XXXXX.js) — Plausible's CDN handles routing internally,
+  // no endpoint or data-domain needed. scriptUrl takes precedence over domain/server.
+  if (scriptUrl) {
+    return (
+      <>
+        <script async src={scriptUrl} />
+        <script dangerouslySetInnerHTML={{
+          __html: 'window.plausible=window.plausible||function(){(plausible.q=plausible.q||[]).push(arguments)},plausible.init=plausible.init||function(i){plausible.o=i||{}};plausible.init()',
+        }} />
+      </>
+    );
+  }
+
+  // Standard mode — data-domain with optional self-hosted server
+  const baseServer = server || 'https://plausible.io';
+  const plausibleServer = baseServer.replace(/\/+$/, '');
+  const scriptProps: Record<string, unknown> = {
+    defer: true,
+    'data-domain': domain,
+    src: `${plausibleServer}/js/script.js`,
+  };
+  if (server) {
+    scriptProps['data-api'] = `${plausibleServer}/api/event`;
+  }
+  return <script {...scriptProps} />;
+}
+
 export default async function RootLayout({
   children,
 }: {
@@ -324,8 +366,16 @@ export default async function RootLayout({
         {config.integrations?.posthog && (
           <link rel="dns-prefetch" href={config.integrations.posthog.apiHost || "https://app.posthog.com"} />
         )}
-        {config.integrations?.plausible && (
-          <link rel="dns-prefetch" href={config.integrations.plausible.server || "https://plausible.io"} />
+        {(config.integrations?.plausible?.domain || config.integrations?.plausible?.scriptUrl) && (
+          <link rel="dns-prefetch" href={(() => {
+            try {
+              return config.integrations!.plausible!.scriptUrl
+                ? new URL(config.integrations!.plausible!.scriptUrl).origin
+                : config.integrations!.plausible!.server || "https://plausible.io";
+            } catch {
+              return config.integrations!.plausible!.server || "https://plausible.io";
+            }
+          })()} />
         )}
         {config.integrations?.intercom && (
           <link rel="dns-prefetch" href="https://widget.intercom.io" />
@@ -427,6 +477,14 @@ export default async function RootLayout({
         {analyticsScript && (
           <script dangerouslySetInnerHTML={{ __html: analyticsScript }} />
         )}
+        {/* Plausible Analytics */}
+        {(config.integrations?.plausible?.domain || config.integrations?.plausible?.scriptUrl) && (
+          <PlausibleScript
+            domain={config.integrations.plausible.domain}
+            server={config.integrations.plausible.server}
+            scriptUrl={config.integrations.plausible.scriptUrl}
+          />
+        )}
       </head>
       <body className={fontClassName} data-theme={themeName || 'jam'}>
         {/* Google Tag Manager */}

package/vendored/components/search/SearchModal.tsx

@@ -167,7 +167,7 @@ export function SearchModal({ isOpen, onClose, popularPages, onNavigate }: Searc
 
       const init = async () => {
         try {
-          const [{ initializeSearch, isInitialized }, response] = await Promise.all([
+          const [{ initializeSearch, getLastData }, response] = await Promise.all([
             import('@/lib/search-client'),
             fetch(`${linkPrefix}/search-data.json`),
           ]);
@@ -176,10 +176,12 @@ export function SearchModal({ isOpen, onClose, popularPages, onNavigate }: Searc
             throw new Error(`Failed to fetch search data: ${response.status}`);
           }
 
-          if (!isInitialized()) {
-            const data = await response.json();
-            await initializeSearch(data);
-          }
+          // If the ETag matches we already have the current data in memory —
+          // pass it back to initializeSearch so the fingerprint check short-circuits.
+          const etag = response.headers.get('etag') ?? '';
+          const lastData = getLastData(etag);
+          const data = lastData ?? await response.json();
+          await initializeSearch(data, etag);
         } catch (error) {
           console.error('Failed to initialize search:', error);
           setInitError('Search is temporarily unavailable');

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

@@ -595,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 };
@@ -622,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/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/middleware-helpers.ts

@@ -293,6 +293,7 @@ export const INTERNAL_API_ROUTES = [
   '/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/search-client.ts

@@ -11,8 +11,7 @@ export interface SearchResult {
   type?: 'api' | 'component' | 'guide' | 'help' | 'quickstart';
 }
 
-// Orama database instance
-let db: Orama<{
+type OramaDb = Orama<{
   id: 'string';
   title: 'string';
   description: 'string';
@@ -20,47 +19,91 @@ let db: Orama<{
   slug: 'string';
   section: 'string';
   type: 'string';
-}> | null = null;
+}>;
 
+// Orama database instance
+let db: OramaDb | null = null;
+// Fingerprint of the data that is currently indexed (committed) or null if not yet built
+let committedFingerprint: string | null = null;
+// Fingerprint of the data currently being built (in-flight), to deduplicate concurrent calls
+let buildingFingerprint: string | null = null;
 let initPromise: Promise<void> | null = null;
+// ETag of the last fetched search-data.json and the parsed data it produced.
+// Lets the modal skip response.json() when the CDN returns the same ETag.
+let lastEtag = '';
+let lastParsedData: SearchResult[] | null = null;
+
+/**
+ * Cheap fingerprint: count + first/last IDs + a sample of content lengths.
+ * Detects new/removed pages AND content edits (which change content length).
+ */
+function fingerprint(data: SearchResult[]): string {
+  if (data.length === 0) return '0';
+  const first = data[0].id;
+  const last = data[data.length - 1].id;
+  const step = Math.max(1, Math.floor(data.length / 8));
+  let contentSig = '';
+  // Sample up to 8 evenly-spaced items' content lengths to detect edits
+  for (let i = 0; i < data.length; i += step) {
+    contentSig += data[i].content.length + ',';
+  }
+  return `${data.length}:${first}:${last}:${contentSig}`;
+}
+
+async function buildIndex(data: SearchResult[], etag: string): Promise<void> {
+  db = await create({
+    schema: {
+      id: 'string',
+      title: 'string',
+      description: 'string',
+      content: 'string',
+      slug: 'string',
+      section: 'string',
+      type: 'string',
+    },
+  });
 
-export async function initializeSearch(data: SearchResult[]): Promise<void> {
-  // Only initialize once
-  if (db) return;
-
-  // Return existing promise if already initializing
-  if (initPromise) return initPromise;
-
-  initPromise = (async () => {
-    db = await create({
-      schema: {
-        id: 'string',
-        title: 'string',
-        description: 'string',
-        content: 'string',
-        slug: 'string',
-        section: 'string',
-        type: 'string',
-      },
-    });
-
-    // Normalize data - ensure all fields are strings
-    const normalizedData = data.map(item => ({
-      id: item.id,
-      title: item.title,
-      description: item.description || '',
-      content: item.content,
-      slug: item.slug,
-      section: item.section || '',
-      type: item.type || 'guide',
-    }));
-
-    await insertMultiple(db, normalizedData);
-  })();
+  const normalizedData = data.map(item => ({
+    id: item.id,
+    title: item.title,
+    description: item.description || '',
+    content: item.content,
+    slug: item.slug,
+    section: item.section || '',
+    type: item.type || 'guide',
+  }));
 
+  await insertMultiple(db, normalizedData);
+  committedFingerprint = buildingFingerprint;
+  lastParsedData = data;
+  lastEtag = etag;
+}
+
+export async function initializeSearch(data: SearchResult[], etag = ''): Promise<void> {
+  const fp = fingerprint(data);
+
+  // Skip rebuild if the committed index already matches
+  if (fp === committedFingerprint) return;
+
+  // If a build with this exact data is already in flight, wait on it
+  if (initPromise && fp === buildingFingerprint) return initPromise;
+
+  // New data available (or first init) — rebuild the index
+  buildingFingerprint = fp;
+  initPromise = buildIndex(data, etag);
   return initPromise;
 }
 
+/**
+ * Returns the previously parsed search data if the given ETag matches the
+ * last successful fetch, so the modal can skip response.json() on unchanged data.
+ * Returns null when the ETag is empty, unknown, or has changed.
+ */
+export function getLastData(etag: string | null): SearchResult[] | null {
+  if (!etag || etag !== lastEtag || !lastParsedData) return null;
+  return lastParsedData;
+}
+
 export async function search(query: string, limit = 10): Promise<SearchResult[]> {
   if (!db) {
     console.warn('Search database not initialized');
@@ -86,6 +129,8 @@ export async function search(query: string, limit = 10): Promise<SearchResult[]>
   return results.hits.map(hit => hit.document as unknown as SearchResult);
 }
 
+/** @internal Used by tests only */
 export function isInitialized(): boolean {
   return db !== null;
 }
+

package/vendored/lib/seo.ts

@@ -11,6 +11,18 @@ import type { Metadata } from 'next';
 import type { DocsConfig, Logo, LogoConfig, Favicon, FaviconConfig, LanguageConfig, LanguageCode } from './docs-types';
 import { transformLanguagePath, extractLanguageFromPath, isValidLanguageCode } from './language-utils';
 
+const HAS_DOCS_SUFFIX = /\b(?:Documentation|Docs)\s*$/i;
+
+/**
+ * Build a display title for the site, appending "Documentation" only when
+ * config.name doesn't already end with a docs-related word.
+ */
+export function buildSiteTitle(configName: string): string {
+  return HAS_DOCS_SUFFIX.test(configName)
+    ? configName
+    : `${configName} Documentation`;
+}
+
 /**
  * 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.

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

@@ -32,13 +32,16 @@ function getContentType(filename: string): string {
  * @param filename - The R2 filename (e.g., 'sitemap.xml', 'search-data.json')
  * @param label - Human-readable label for log messages (e.g., 'Sitemap', 'Search data')
  * @param contentTypeOverride - Override the inferred content type (e.g., 'application/rss+xml')
+ * @param cacheControlOverride - Override the default Cache-Control header
  */
 export function createStaticFileHandler(
   filename: string,
   label: string,
-  contentTypeOverride?: string
+  contentTypeOverride?: string,
+  cacheControlOverride?: string
 ): (request: NextRequest) => Promise<NextResponse> {
   const contentType = contentTypeOverride || getContentType(filename);
+  const cacheControl = cacheControlOverride || 'public, max-age=3600, s-maxage=86400';
 
   return async function GET(request: NextRequest): Promise<NextResponse> {
     if (!isIsrMode()) {
@@ -63,7 +66,7 @@ export function createStaticFileHandler(
       return new NextResponse(content, {
         headers: {
           'Content-Type': contentType,
-          'Cache-Control': 'public, max-age=3600, s-maxage=86400',
+          'Cache-Control': cacheControl,
         },
       });
     } catch (error) {

package/vendored/lib/validate-config.ts

@@ -31,6 +31,7 @@ export interface DocsConfig {
 export interface IntegrationsConfig {
   ga4?: { measurementId: string };
   gtm?: { tagId: string };
+  plausible?: { domain?: string; server?: string; scriptUrl?: string };
   [key: string]: unknown;
 }
 

package/vendored/schema/docs-schema.json

@@ -1141,15 +1141,27 @@
               },
               "plausible": {
                 "type": "object",
-                "description": "Plausible Analytics integration. Include empty object {} to indicate placeholder.",
+                "description": "Plausible Analytics. Use domain for standard setup (free/paid). Use scriptUrl for paid proxy scripts that bypass ad blockers (pa-XXXXX.js URLs from Plausible dashboard). Only set one.",
                 "properties": {
                   "domain": {
-                    "type": "string"
+                    "type": "string",
+                    "description": "Standard setup: your site domain registered in Plausible (e.g., docs.example.com). Used as the data-domain attribute."
                   },
                   "server": {
-                    "type": "string"
+                    "type": "string",
+                    "format": "uri",
+                    "description": "Self-hosted only: URL of your Plausible server. Only used with domain, not scriptUrl."
+                  },
+                  "scriptUrl": {
+                    "type": "string",
+                    "format": "uri",
+                    "description": "Proxy setup: full URL to your Plausible paid proxy script (e.g., https://plausible.io/js/pa-XXXXX.js). Site identity is embedded in the script — no domain needed."
                   }
                 },
+                "anyOf": [
+                  { "required": ["domain"] },
+                  { "required": ["scriptUrl"] }
+                ],
                 "additionalProperties": false
               },
               "segment": {