jamdesk 1.1.148 → 1.1.150

package/vendored/components/mdx/MermaidInner.tsx

@@ -1,6 +1,6 @@
 'use client';
 
-import { useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react';
+import { useEffect, useLayoutEffect, useRef, useState } from 'react';
 import mermaid from 'mermaid';
 import {
   CACHE_KEY_PREFIX,
@@ -355,11 +355,6 @@ export function MermaidInner({ children, className, minWidth }: MermaidInnerProp
   });
   const [error, setError] = useState<string | null>(null);
 
-  // Reserves space so the skeleton → SVG swap doesn't shift layout below it.
-  // Derived from svg (not separate state) so it can't desync. The regex is
-  // cheap (small string, no backtracking).
-  const minHeightPx = useMemo(() => (svg ? readSvgHeight(svg) : 0), [svg]);
-
   useEffect(() => {
     let cancelled = false;
 
@@ -482,8 +477,7 @@ export function MermaidInner({ children, className, minWidth }: MermaidInnerProp
   return (
     <div
       ref={containerRef}
-      className={`mermaid-container my-6 flex justify-center overflow-x-auto ${className || ''}`}
-      style={minHeightPx ? { minHeight: `${minHeightPx}px` } : undefined}
+      className={`mermaid-container my-6 flex justify-center items-start overflow-x-auto ${className || ''}`}
       dangerouslySetInnerHTML={{ __html: svg }}
     />
   );

package/vendored/components/mdx/OpenApiEndpoint.tsx

@@ -829,7 +829,7 @@ export function OpenApiEndpoint({
 
   if (playgroundOnly) {
     return (
-      <div className="openapi-endpoint">
+      <div className="openapi-endpoint" data-markdown-ignore>
         <ApiEndpoint
           method={method}
           path={path}
@@ -842,7 +842,12 @@ export function OpenApiEndpoint({
   }
 
   return (
-    <div className="openapi-endpoint">
+    /* data-markdown-ignore: the endpoint UI is generated from the spec
+       and intentionally absent from the .md export (which points agents
+       at api-specs.zip). afdocs strips [data-markdown-ignore] before the
+       markdown-content-parity comparison, so OpenAPI pages don't false-
+       fail parity. */
+    <div className="openapi-endpoint" data-markdown-ignore>
       {/* Deprecation Warning */}
       {deprecated && (
         <div className="flex items-center gap-2 p-3 mb-4 bg-amber-500/10 border border-amber-500/20 rounded-lg text-amber-600 dark:text-amber-400">

package/vendored/components/navigation/SocialFooter.tsx

@@ -16,6 +16,14 @@ const WORDMARK_STYLE: CSSProperties = {
   backgroundColor: 'currentColor',
   WebkitMask: WORDMARK_MASK,
   mask: WORDMARK_MASK,
+  // The wordmark SVG's viewBox runs from the j-dot (top) to the j-descender
+  // (bottom), so its typographic baseline sits ~76% down the box. Under the
+  // link's `items-baseline` the span's box-bottom lands on the text baseline,
+  // which leaves the glyphs ~3.3px ABOVE it (measured live). Nudge down by that
+  // much so the wordmark and "Powered by" share a baseline. Inline transform
+  // (not a Tailwind `translate-y-*` class) because the theme's CSS build purges
+  // arbitrary transform utilities — that silently dropped the previous fix.
+  transform: 'translateY(3.5px)',
 };
 
 interface SocialFooterProps {
@@ -155,7 +163,7 @@ function BrandingLink({ projectSlug }: { projectSlug?: string }) {
       <span
         role="img"
         aria-label="Jamdesk"
-        className="inline-block translate-y-[2px] text-[var(--color-text-muted)]/85 group-hover:text-[var(--color-text-primary)]"
+        className="inline-block text-[var(--color-text-muted)]/85 group-hover:text-[var(--color-text-primary)]"
         style={WORDMARK_STYLE}
       />
     </a>

package/vendored/lib/build/error-parser.ts

@@ -191,7 +191,9 @@ export function parseErrorDetails(
       '• "name": Your site name\n' +
       '• "theme": One of "jam", "nebula", or "pulsar"\n' +
       '• "colors": { "primary": "#hexcolor" }\n' +
-      '• "navigation": { "anchors": [...] } or { "groups": [...] }\n\n';
+      '• "navigation": one of "tabs", "groups", "pages", "dropdowns", ' +
+      '"versions", "languages", or "products" ' +
+      '(e.g. { "groups": [...] })\n\n';
 
     let suggestion = `${intro}\n\n`;
     if (discoveryHint) {
@@ -249,10 +251,11 @@ export function parseErrorDetails(
         `Error occurred while building: ${file}`,
       suggestion:
         'Check your docs.json configuration file. The "navigation" field ' +
-        'must be an object with "anchors", "tabs", or "groups".\n\n' +
+        'must be an object with one of "tabs", "groups", "pages", ' +
+        '"dropdowns", "versions", "languages", or "products".\n\n' +
         'Example:\n' +
         '"navigation": {\n' +
-        '  "anchors": [{ "anchor": "Docs", "groups": [...] }]\n' +
+        '  "groups": [{ "group": "Docs", "pages": [...] }]\n' +
         '}\n\n' +
         'See https://www.jamdesk.com/docs/navigation for details.',
     };

package/vendored/lib/docs-types.ts

@@ -711,6 +711,7 @@ export interface SeoConfig {
   indexing?: 'navigable' | 'all';
   /** Include hidden pages in sitemap (default: false) */
   indexHiddenPages?: boolean;
+  ai?: { llmsTxt?: boolean }; // default true; false suppresses llms.txt + llms-full.txt
 }
 
 /**

package/vendored/lib/extract-faq.ts

@@ -0,0 +1,54 @@
+export interface FaqPair { question: string; answer: string; }
+
+// Nested component subtrees that are NOT part of the FAQ answer prose (CTAs,
+// cards, media, callouts). Drop them WITH their inner text before flattening.
+const NESTED_BLOCK_TAGS = [
+  'Card', 'CardGroup', 'Columns', 'Frame', 'Note', 'Warning', 'Tip', 'Info',
+  'Steps', 'Step', 'Tabs', 'Tab', 'CodeGroup',
+];
+
+function stripMarkdown(s: string): string {
+  return s
+    .replace(/```[\s\S]*?```/g, ' ')         // fenced code
+    .replace(/`([^`]+)`/g, '$1')              // inline code
+    .replace(/!\[[^\]]*\]\([^)]*\)/g, ' ')    // images
+    .replace(/\[([^\]]+)\]\([^)]*\)/g, '$1')  // links → text
+    .replace(/(\*\*|__)(.*?)\1/g, '$2')       // bold
+    .replace(/(\*|_)(.*?)\1/g, '$2')          // italic
+    .replace(/^#{1,6}\s+/gm, '')              // ATX headings
+    .replace(/^\s*[-*+]\s+/gm, '')            // bullet markers
+    .replace(/^\s*\d+\.\s+/gm, '');           // ordered markers
+}
+
+// Lightweight extraction of <Accordion title="...">body</Accordion>. Only the
+// QUOTED-title form is matched (the title={expr} form is intentionally skipped —
+// an expression can't be resolved to display text). Answers are reduced to plain
+// text for schema.org: nested component subtrees dropped, markdown stripped.
+//
+// KNOWN LIMITATION (regex, not AST): an <Accordion> nested INSIDE another
+// <Accordion> body truncates the outer answer at the first </Accordion> and
+// merges the inner answer in (the inner question is lost). Harmless for the
+// FAQPage JSON-LD — output stays valid, just an imperfect answer string on the
+// rare nested page. Sibling accordions in an <AccordionGroup> are unaffected.
+// The fix for true nesting is the compiled-MDX AST walk (mdxJsxFlowElement),
+// the documented upgrade path; kept regex-first per the plan's decision.
+export function extractFaqPairs(rawMdx: string): FaqPair[] {
+  const pairs: FaqPair[] = [];
+  const re = /<Accordion\b[^>]*?\btitle\s*=\s*("|')(.*?)\1[^>]*>([\s\S]*?)<\/Accordion>/g;
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(rawMdx))) {
+    const question = m[2].trim();
+    let body = m[3];
+    for (const tag of NESTED_BLOCK_TAGS) {
+      body = body
+        .replace(new RegExp(`<${tag}\\b[^>]*>[\\s\\S]*?<\\/${tag}>`, 'g'), ' ') // paired
+        .replace(new RegExp(`<${tag}\\b[^>]*/>`, 'g'), ' ');                    // self-closing
+    }
+    const answer = stripMarkdown(body)
+      .replace(/<[^>]+>/g, ' ') // any remaining tags
+      .replace(/\s+/g, ' ')
+      .trim();
+    if (question && answer) pairs.push({ question, answer });
+  }
+  return pairs;
+}

package/vendored/lib/firestore-helpers.ts

@@ -1,4 +1,4 @@
-import admin from 'firebase-admin';
+import { getFirestore } from 'firebase-admin/firestore';
 
 /**
  * True when a Firestore project claims this slug (the canonical slug lives at
@@ -10,8 +10,7 @@ import admin from 'firebase-admin';
  * dashboard/firestore.indexes.json, so this query needs no new index.
  */
 export async function isSlugActive(slug: string): Promise<boolean> {
-  const snap = await admin
-    .firestore()
+  const snap = await getFirestore()
     .collectionGroup('github')
     .where('slug', '==', slug)
     .limit(1)

package/vendored/lib/fix-engine.ts

@@ -0,0 +1,293 @@
+// builder/build-service/lib/fix-engine.ts
+//
+// Dependency-free deterministic doc-warning fix engine. Imports NOTHING so it
+// byte-syncs into the CLI's src/lib (cli/src cannot import cli/vendored).
+//
+// The engine does NO slugging and NO I/O: the caller injects heading data via
+// FixContext.headingsOf(), populated from the canonical extractHeadings()
+// (heading-extractor.ts) whose ids ARE the real rehype-slug DOM ids. Re-slugging
+// here is forbidden — markdown-only re-slugging diverges from real ids (dedup
+// suffixes shift when <Update>/<Step> anchors share heading text) and was the
+// original wrong-fix bug.
+
+// ---- Types ----------------------------------------------------------------
+
+export interface Edit {
+  file: string;
+  /** 1-indexed source line the edit applies to (from the warning). */
+  line: number;
+  oldText: string;
+  newText: string;
+}
+
+export interface FixResult {
+  status: 'fixed' | 'skipped';
+  edits: Edit[];
+  reason: string;
+}
+
+export interface LocaleInfo {
+  codes: string[];
+  defaultCode: string;
+}
+
+export interface FixWarning {
+  type: string;
+  file: string;
+  line: number | null;
+  link: string;
+  message?: string;
+}
+
+/** Structural subset of heading-extractor's HeadingInfo — extractHeadings()
+ *  output is assignable to EngineHeading[] directly (no mapping). */
+export interface EngineHeading {
+  id: string;
+  stepNumber?: number;
+  isUpdate?: boolean;
+}
+
+export interface FixContext {
+  currentPagePath: string;
+  locales: LocaleInfo;
+  /** Resolve a doc link href to a normalized page path, or null if it does not exist. */
+  resolveLinkPagePath(href: string): string | null;
+  /** Ordered headings for a page path (no extension) via extractHeadings(), or null. */
+  headingsOf(pagePath: string): EngineHeading[] | null;
+}
+
+export type Fixer = (warning: FixWarning, ctx: FixContext) => FixResult;
+
+/** A markdown heading entry (not a <Step> or <Update> component anchor). */
+export function isMarkdownHeading(h: EngineHeading): boolean {
+  return h.stepNumber == null && !h.isUpdate;
+}
+
+/** True iff `candidate` is an exact heading id on `headings`. The canonical
+ *  guard for any externally-sourced (e.g. AI) anchor suggestion — the engine
+ *  itself uses the same `allIds.includes(...)` check inside fixBrokenLink's
+ *  `emit`. Phase 2's AI tier MUST route every suggestion through this so a
+ *  hallucinated fragment can never be written. Pure, dependency-free. */
+export function isRealAnchor(candidate: string, headings: EngineHeading[]): boolean {
+  if (!candidate) return false;
+  return headings.some((h) => h.id === candidate);
+}
+
+/** Substring appended to the skip reason when the deterministic engine defers an
+ *  anchor to the AI tier. Exported so the AI-tier callers match on this constant
+ *  instead of a re-typed literal — producer and consumer cannot drift. */
+export const NEEDS_AI_MARKER = '(needs AI)';
+
+// ---- Edit application -----------------------------------------------------
+
+// A flagged href is always the target of a markdown link `](href)` or an
+// `href="…"`/`href='…'` attribute, so in source it is bounded on the left by a
+// delimiter — never by another URL/path character. A match whose preceding char
+// IS a path character is the href appearing as a SUBSTRING inside a longer URL
+// (e.g. `/setup#x` inside `/guide/setup#x`) and must be skipped, or the edit
+// would corrupt an unrelated, valid link on the same line.
+const URL_PATH_CHAR = /[A-Za-z0-9\-._~%/#?:@]/;
+
+/** Index of the next occurrence of `href` at/after `from` that sits at a link
+ *  boundary (not as a substring inside a longer path), or -1. */
+function findHrefBoundary(line: string, href: string, from: number): number {
+  let pos = line.indexOf(href, from);
+  while (pos !== -1) {
+    if (pos === 0 || !URL_PATH_CHAR.test(line[pos - 1])) return pos;
+    pos = line.indexOf(href, pos + 1);
+  }
+  return -1;
+}
+
+/**
+ * Apply edits, replacing each edit's oldText with newText on its specific
+ * (1-indexed) source line. Line-scoped, so an identical href on another line
+ * (e.g. a code sample) is never touched. Within a line: oldText is matched at a
+ * link boundary (so a short href is never replaced inside a longer one),
+ * matching runs against the ORIGINAL line (so an edit whose newText contains its
+ * oldText is never re-matched), and edits apply right-to-left so earlier
+ * positions keep their indices. Identical oldTexts on one line consume
+ * successive occurrences. Throws if a line is out of range or an oldText is
+ * absent — a missing match means the source changed since the fix was derived,
+ * and a partial/wrong edit must never be written.
+ */
+export function applyEdits(content: string, edits: Edit[]): string {
+  if (edits.length === 0) return content;
+  const lines = content.split('\n');
+
+  const byLine = new Map<number, Edit[]>();
+  for (const edit of edits) {
+    const list = byLine.get(edit.line);
+    if (list) list.push(edit);
+    else byLine.set(edit.line, [edit]);
+  }
+
+  for (const [line, lineEdits] of byLine) {
+    const idx = line - 1;
+    if (idx < 0 || idx >= lines.length) {
+      throw new Error(`applyEdits: line ${line} out of range (${lines.length} lines)`);
+    }
+    const src = lines[idx];
+    // Resolve every edit to a concrete [start,end) span on the ORIGINAL line.
+    const spans: Array<{ start: number; end: number; newText: string }> = [];
+    const nextFrom = new Map<string, number>();
+    for (const edit of lineEdits) {
+      const from = nextFrom.get(edit.oldText) ?? 0;
+      const start = findHrefBoundary(src, edit.oldText, from);
+      if (start === -1) {
+        throw new Error(`applyEdits: oldText not found on line ${line}: ${JSON.stringify(edit.oldText)}`);
+      }
+      const end = start + edit.oldText.length;
+      nextFrom.set(edit.oldText, end);
+      spans.push({ start, end, newText: edit.newText });
+    }
+    // Apply right-to-left so an earlier span's indices survive later edits.
+    spans.sort((a, b) => b.start - a.start);
+    let out = src;
+    for (const s of spans) out = out.slice(0, s.start) + s.newText + out.slice(s.end);
+    lines[idx] = out;
+  }
+  return lines.join('\n');
+}
+
+// ---- Distance / nearest-slug (ported from validate-links.cjs) -------------
+
+const MAX_SUGGESTION_DISTANCE = 2;
+
+export function levenshtein(a: string, b: string): number {
+  if (a === b) return 0;
+  if (a.length === 0) return b.length;
+  if (b.length === 0) return a.length;
+  let prev = new Array<number>(b.length + 1);
+  let curr = new Array<number>(b.length + 1);
+  for (let j = 0; j <= b.length; j++) prev[j] = j;
+  for (let i = 0; i < a.length; i++) {
+    curr[0] = i + 1;
+    for (let j = 0; j < b.length; j++) {
+      const cost = a[i] === b[j] ? 0 : 1;
+      curr[j + 1] = Math.min(curr[j] + 1, prev[j + 1] + 1, prev[j] + cost);
+    }
+    [prev, curr] = [curr, prev];
+  }
+  return prev[b.length];
+}
+
+export function closestSlug(fragment: string, slugs: Iterable<string>): string | null {
+  if (!fragment) return null;
+  let best: string | null = null;
+  let bestDist = Infinity;
+  let secondDist = Infinity;
+  for (const slug of slugs) {
+    if (Math.abs(fragment.length - slug.length) > MAX_SUGGESTION_DISTANCE) continue;
+    const d = levenshtein(fragment, slug);
+    if (d < bestDist) {
+      secondDist = bestDist;
+      bestDist = d;
+      best = slug;
+    } else if (d < secondDist) {
+      secondDist = d;
+    }
+  }
+  return best !== null && bestDist >= 1 && bestDist <= MAX_SUGGESTION_DISTANCE && bestDist < secondDist
+    ? best
+    : null;
+}
+
+// ---- Link + locale helpers ------------------------------------------------
+
+export function parseHref(href: string): { path: string | null; fragment: string | null } {
+  const i = href.indexOf('#');
+  if (i === -1) return { path: href, fragment: null };
+  return { path: i === 0 ? null : href.slice(0, i), fragment: href.slice(i + 1) || null };
+}
+
+export function normalizeLinkPath(linkPath: string, hostAtDocs: boolean): string {
+  let p = linkPath;
+  if (hostAtDocs && p.startsWith('/docs/')) p = p.slice('/docs/'.length);
+  if (p.startsWith('/')) p = p.slice(1);
+  return p.replace(/\.mdx$/, '');
+}
+
+/** The default-locale twin of a localized page path, or null if already default. */
+export function defaultTwinPath(pagePath: string, locales: LocaleInfo): string | null {
+  const segments = pagePath.split('/');
+  const first = segments[0];
+  if (first !== locales.defaultCode && locales.codes.includes(first)) {
+    return segments.slice(1).join('/');
+  }
+  return null;
+}
+
+// ---- Broken-link fixer ----------------------------------------------------
+
+function skip(reason: string): FixResult {
+  return { status: 'skipped', edits: [], reason };
+}
+
+export const fixBrokenLink: Fixer = (warning, ctx) => {
+  const { path: linkPath, fragment } = parseHref(warning.link);
+  if (!fragment) return skip('not a fragment link — out of scope for phase 1');
+  if (!linkPath) return skip('same-page fragment — out of scope for phase 1');
+  if (warning.line == null) return skip('warning has no line — cannot place a safe edit');
+
+  const targetPage = ctx.resolveLinkPagePath(linkPath);
+  if (!targetPage) return skip('target page could not be resolved');
+  const targetHeadings = ctx.headingsOf(targetPage);
+  if (!targetHeadings) return skip('target page headings could not be read');
+
+  const allIds = targetHeadings.map((h) => h.id);
+
+  // (0) Re-derivation: may already be valid in current source.
+  if (allIds.includes(fragment)) return skip('already valid — fragment exists on target');
+
+  // Emit only a fragment that is a REAL anchor on the target (never point at a
+  // non-existent or wrong-kind id), reconstructing the href (no substring replace).
+  const emit = (candidate: string, reason: string): FixResult => {
+    if (!allIds.includes(candidate)) return skip('internal: candidate is not a real anchor — refusing');
+    return {
+      status: 'fixed',
+      edits: [{ file: warning.file, line: warning.line as number, oldText: warning.link, newText: linkPath + '#' + candidate }],
+      reason,
+    };
+  };
+
+  // (1) Cross-locale positional map FIRST (high precision for localized targets).
+  // Ordinals over MARKDOWN headings only (so <Step>/<Update> can't misalign them),
+  // but the emitted id is the target heading's REAL id (full-set dedup).
+  const twinPage = defaultTwinPath(targetPage, ctx.locales);
+  if (twinPage) {
+    const twinHeadings = ctx.headingsOf(twinPage);
+    if (twinHeadings) {
+      const twinMd = twinHeadings.filter(isMarkdownHeading);
+      const targetMd = targetHeadings.filter(isMarkdownHeading);
+      const ordinal = twinMd.findIndex((h) => h.id === fragment);
+      if (ordinal !== -1 && twinMd.length === targetMd.length && targetMd[ordinal]) {
+        return emit(targetMd[ordinal].id, `cross-locale positional map: #${fragment} → #${targetMd[ordinal].id}`);
+      }
+    }
+  }
+
+  // (2) Near-miss fallback (typos within the same language).
+  const near = closestSlug(fragment, allIds);
+  if (near) return emit(near, `near-miss: #${fragment} → #${near}`);
+
+  return skip(`no confident deterministic fix — structures diverge or target is ambiguous ${NEEDS_AI_MARKER}`);
+};
+
+// ---- Registry + engine entry point ----------------------------------------
+
+/** Fixer registry keyed by BuildWarningType. Phase 1: broken_link only. */
+export const FIXERS: Record<string, Fixer> = {
+  broken_link: fixBrokenLink,
+};
+
+/**
+ * Run the registered fixer for a warning. Deterministic-first is implemented
+ * inside each fixer (exact strategies, then 'skipped' for AI cases). The AI
+ * fallback tier is wired in Phase 2; until then a 'skipped' result is terminal.
+ */
+export function runFixer(warning: FixWarning, ctx: FixContext): FixResult {
+  const fixer = FIXERS[warning.type];
+  if (!fixer) return skip(`no fixer registered for type "${warning.type}"`);
+  return fixer(warning, ctx);
+}

package/vendored/lib/health-checks.ts

@@ -190,10 +190,10 @@ export async function checkFirestoreHealth(db: Firestore): Promise<FirestoreHeal
     let writeLatencyMs: number | null = null;
     try {
       const writeStart = Date.now();
-      const admin = await import('firebase-admin');
+      const { FieldValue } = await import('firebase-admin/firestore');
       await Promise.race([
         healthRef.set(
-          { lastCheck: admin.firestore.FieldValue.serverTimestamp() },
+          { lastCheck: FieldValue.serverTimestamp() },
           { merge: true }
         ),
         new Promise((_, reject) =>