jamdesk 1.1.127 → 1.1.129

package/vendored/components/navigation/SocialFooter.tsx

@@ -22,6 +22,9 @@ interface SocialFooterProps {
   config: DocsConfig;
   hidden?: boolean;
   projectSlug?: string;
+  /** Embed render (widget modal): keep ONLY the "Powered by Jamdesk"
+   *  attribution — drop the link columns + social icons. */
+  embed?: boolean;
 }
 
 /**
@@ -137,7 +140,42 @@ function SocialIcons({ socials }: { socials: Partial<Record<SocialPlatform, stri
   );
 }
 
-export function SocialFooter({ config, hidden, projectSlug }: SocialFooterProps) {
+/** "Powered by Jamdesk" attribution link, shared by the full footer and the
+ *  embed footer. Renders nothing when branding is disabled at build time. */
+function BrandingLink({ projectSlug }: { projectSlug?: string }) {
+  if (!showBranding) return null;
+  return (
+    <a
+      href={getBrandingUrl(projectSlug)}
+      target="_blank"
+      rel="noopener noreferrer"
+      className="group flex items-baseline gap-1 text-sm text-[var(--color-text-muted)]/60 hover:text-[var(--color-text-muted)] transition-colors whitespace-nowrap"
+    >
+      Powered by
+      <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)]"
+        style={WORDMARK_STYLE}
+      />
+    </a>
+  );
+}
+
+export function SocialFooter({ config, hidden, projectSlug, embed }: SocialFooterProps) {
+  // Embed render (widget modal): keep ONLY the "Powered by Jamdesk" attribution.
+  // The link columns + social icons read as out of place inside an embedded
+  // changelog; the attribution stays even when the normal footer is hidden,
+  // since it's the embed widget's branding.
+  if (embed) {
+    if (!showBranding) return null;
+    return (
+      <footer className="mt-10 pt-6 border-t border-[var(--color-border)] flex justify-center">
+        <BrandingLink projectSlug={projectSlug} />
+      </footer>
+    );
+  }
+
   if (hidden) return null;
 
   const { socials, links } = config.footer || {};
@@ -156,22 +194,7 @@ export function SocialFooter({ config, hidden, projectSlug }: SocialFooterProps)
       {hasLinks && <LinkColumns columns={links} />}
       <div className="flex flex-col sm:flex-row sm:items-center sm:justify-between gap-4">
         {hasSocials && <SocialIcons socials={socials} />}
-        {showBranding && (
-          <a
-            href={getBrandingUrl(projectSlug)}
-            target="_blank"
-            rel="noopener noreferrer"
-            className="group flex items-baseline gap-1 text-sm text-[var(--color-text-muted)]/60 hover:text-[var(--color-text-muted)] transition-colors whitespace-nowrap"
-          >
-            Powered by
-            <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)]"
-              style={WORDMARK_STYLE}
-            />
-          </a>
-        )}
+        <BrandingLink projectSlug={projectSlug} />
       </div>
     </footer>
   );

package/vendored/lib/api-spec-menu-gate.ts

@@ -0,0 +1,49 @@
+import type { ContextualOption, DocsConfig } from './docs-types';
+import { siteHasOpenApiSpecs } from './api-specs-bundle';
+import { shouldOfferApiSpecDownload } from './api-spec-offer';
+
+export interface ApiSpecGateInput {
+  isIsr: boolean;
+  isApiPage: boolean;
+  /** This page's frontmatter declares an `openapi:` spec. */
+  pageHasOpenApi: boolean;
+  config: DocsConfig;
+}
+
+/**
+ * Insert `download-api-spec` into the AI-actions menu iff the page offers the
+ * api-specs download (shared gate: shouldOfferApiSpecDownload). The offer
+ * decision is shared with the markdown footer so the two cannot drift; this
+ * function owns only the menu-specific concerns: idempotency and placement.
+ *
+ * Placement: directly below "View as Markdown"; falls back to just after "Copy
+ * page", then the front, when "view" is absent (a customized options list).
+ *
+ * `siteHasOpenApiSpecs` walks the whole docs.json navigation, so it is passed as
+ * a thunk — the shared predicate evaluates it only after the cheap gates pass
+ * and only when the page has no page-level `openapi:`, preserving the original
+ * no-walk-on-guide-pages behavior.
+ */
+export function withApiSpecDownload(
+  options: ContextualOption[],
+  { isIsr, isApiPage, pageHasOpenApi, config }: ApiSpecGateInput,
+): ContextualOption[] {
+  if (options.includes('download-api-spec')) return options;
+  if (
+    !shouldOfferApiSpecDownload({
+      isIsr,
+      menuEnabled: options.length > 0,
+      isApiPage,
+      pageHasOpenApi,
+      siteHasSpecs: () => siteHasOpenApiSpecs(config),
+    })
+  ) {
+    return options;
+  }
+  const result = [...options];
+  const viewIdx = result.indexOf('view');
+  const copyIdx = result.indexOf('copy');
+  const insertAt = viewIdx !== -1 ? viewIdx + 1 : copyIdx !== -1 ? copyIdx + 1 : 0;
+  result.splice(insertAt, 0, 'download-api-spec');
+  return result;
+}

package/vendored/lib/api-spec-offer.ts

@@ -0,0 +1,50 @@
+/**
+ * Single source of truth for "should this page offer the api-specs download?".
+ * Consumed by BOTH the visible menu-button gate (withApiSpecDownload,
+ * lib/api-spec-menu-gate.ts) and the agent-facing markdown footer gate
+ * (apiSpecsMarkdownFooter, lib/api-specs-markdown-hint.ts), so the two gates
+ * cannot drift on the offer condition.
+ *
+ * Pure: no I/O, no config access. Callers resolve the inputs (ISR, frontmatter,
+ * menu, spec existence) and pass primitives.
+ *
+ * Rule: ISR + the AI-actions menu is enabled + the page is an API page (`api:`
+ * or `openapi:` frontmatter) + there is a spec to bundle — a page-level
+ * `openapi:` short-circuits the site-wide spec check, exactly as the menu has
+ * always done.
+ *
+ * `siteHasSpecs` may be a thunk. The menu gate's site-spec check
+ * (siteHasOpenApiSpecs) walks the whole docs.json navigation; the original gate
+ * deliberately avoided that walk on the common non-API-page render path.
+ * Passing `() => …` preserves the laziness — the thunk runs only after the cheap
+ * gates pass and only when the page has no page-level `openapi:`.
+ */
+export interface ApiSpecOfferInput {
+  /** ISR runtime. Both gates are inert in local `jamdesk dev` (isIsr=false). */
+  isIsr: boolean;
+  /**
+   * The AI-actions menu is present with ≥1 option — i.e. NOT disabled via
+   * `contextual.enabled:false` / `options:[]`. This is a derived fact, not a
+   * config flag: callers compute it from the rendered options list
+   * (`options.length > 0` / `getContextualOptions(config).length > 0`), which is
+   * where menu-enablement actually lives (`lib/contextual-defaults.ts`).
+   */
+  menuEnabled: boolean;
+  /** Page frontmatter declares `api:` or `openapi:`. */
+  isApiPage: boolean;
+  /** Page frontmatter declares its own `openapi:` — short-circuits the site-wide check. */
+  pageHasOpenApi: boolean;
+  /**
+   * Whether the site references ≥1 OpenAPI spec anywhere. May be a thunk so a
+   * caller can defer an expensive docs.json navigation walk until the cheap
+   * gates pass; see the menu-gate call site.
+   */
+  siteHasSpecs: boolean | (() => boolean);
+}
+
+export function shouldOfferApiSpecDownload(input: ApiSpecOfferInput): boolean {
+  const { isIsr, menuEnabled, isApiPage, pageHasOpenApi, siteHasSpecs } = input;
+  if (!(isIsr && menuEnabled && isApiPage)) return false;
+  if (pageHasOpenApi) return true;
+  return typeof siteHasSpecs === 'function' ? siteHasSpecs() : siteHasSpecs;
+}

package/vendored/lib/api-specs-bundle.ts

@@ -0,0 +1,255 @@
+/**
+ * api-specs.zip assembly — REQUEST-TIME.
+ *
+ * Assembles the downloadable bundle on demand from specs already in R2 plus
+ * remote-URL specs fetched (SSRF-guarded) at request time. Verbatim bundling:
+ * local specs keep their R2 key path so co-located `$ref`s resolve.
+ *
+ * All I/O is injected so this is unit-testable without R2 or network.
+ */
+import path from 'path';
+
+import { zipSync } from 'fflate';
+
+import type { DocsConfig } from './docs-types';
+import { isUrlSafe } from './url-safety';
+import type { BuildWarning } from '../shared/status-reporter';
+
+/** 8 MiB per remote spec; 10s per fetch — bounds a single short-lived request. */
+const DEFAULT_MAX_BYTES = 8 * 1024 * 1024;
+const DEFAULT_TIMEOUT_MS = 10_000;
+/**
+ * Overall wall-clock budget (ms) for ALL remote fetches in one request, measured
+ * from assembler entry. Each fetch is individually bounded, but a docs.json with
+ * several slow remotes could sum past Vercel's 30s function cap and hard-kill the
+ * request — discarding the local specs already assembled. 25s leaves ~5s headroom
+ * under the cap for zipping + streaming the response.
+ */
+const DEFAULT_REMOTE_BUDGET_MS = 25_000;
+
+export function isHttpUrl(ref: string): boolean {
+  return /^https?:\/\//i.test(ref);
+}
+
+function pushRefs(out: string[], seen: Set<string>, val: unknown): void {
+  const add = (r: unknown) => {
+    if (typeof r === 'string' && r && !seen.has(r)) { seen.add(r); out.push(r); }
+  };
+  if (typeof val === 'string') add(val);
+  else if (Array.isArray(val)) val.forEach(add);
+}
+
+function walk(out: string[], seen: Set<string>, node: unknown): void {
+  if (!node || typeof node !== 'object') return;
+  if (Array.isArray(node)) { for (const n of node) walk(out, seen, n); return; }
+  for (const [key, value] of Object.entries(node as Record<string, unknown>)) {
+    if (key === 'openapi') pushRefs(out, seen, value);
+    else if (value && typeof value === 'object') walk(out, seen, value);
+  }
+}
+
+/** Every `openapi` ref declared anywhere in docs.json (top-level + nested nav),
+ *  de-duplicated, order-preserving. Locals AND http(s) URLs. */
+export function collectConfigOpenApiRefs(config: DocsConfig): string[] {
+  const out: string[] = [];
+  const seen = new Set<string>();
+  pushRefs(out, seen, config.api?.openapi);
+  walk(out, seen, config.navigation);
+  return out;
+}
+
+export function siteHasOpenApiSpecs(config: DocsConfig): boolean {
+  return collectConfigOpenApiRefs(config).length > 0;
+}
+
+export interface ZipEntry { name: string; content: Uint8Array; }
+
+function uniqueName(name: string, used: Set<string>): string {
+  if (!used.has(name)) { used.add(name); return name; }
+  const ext = path.extname(name);
+  const base = name.slice(0, name.length - ext.length);
+  let n = 2;
+  let candidate = `${base}-${n}${ext}`;
+  while (used.has(candidate)) { n += 1; candidate = `${base}-${n}${ext}`; }
+  used.add(candidate);
+  return candidate;
+}
+
+/**
+ * Build a zip from named entries. Entry names are used AS GIVEN (path preserved),
+ * so a local spec passed as `openapi/api.yaml` keeps its directory and its
+ * relative `$ref`s resolve. Colliding names get a `-2`/`-3` suffix. Null if empty.
+ * No `mtime` option: fflate's DOS date floor is 1980, so `mtime: 0` THROWS.
+ */
+export function buildSpecZip(entries: ZipEntry[]): Uint8Array | null {
+  if (entries.length === 0) return null;
+  const used = new Set<string>();
+  const map: Record<string, Uint8Array> = {};
+  for (const e of entries) {
+    const name = e.name.includes('/') ? e.name : (path.basename(e.name) || 'spec');
+    map[uniqueName(name, used)] = e.content;
+  }
+  return zipSync(map);
+}
+
+function remoteWarning(url: string, reason: string): BuildWarning {
+  return {
+    type: 'invalid_openapi_spec',
+    file: 'docs.json',
+    link: url,
+    message: `Remote OpenAPI spec "${url}" excluded from api-specs.zip (${reason}).`,
+  };
+}
+
+function remoteSpecFilename(url: string): string {
+  try {
+    const base = path.basename(new URL(url).pathname);
+    if (base && base !== '/') return base;
+  } catch { /* fall through */ }
+  return 'remote-spec.json';
+}
+
+export type RemoteOutcome = { entry: ZipEntry } | { warning: BuildWarning };
+
+/** Max redirect hops to follow before giving up — bounds redirect chains. */
+const MAX_REDIRECTS = 5;
+
+/**
+ * Fetch one remote spec, SSRF-guarded + bounded. Never throws.
+ *
+ * Follows redirects MANUALLY (`redirect: 'manual'`) and re-validates `isUrlSafe`
+ * on EVERY hop. The default `fetchImpl` in prod is global `fetch` (undici), which
+ * would otherwise follow redirects transparently — letting a safe initial URL
+ * 302 to a private/metadata host and bypass the guard. Re-checking each target
+ * before fetching it closes that SSRF redirect bypass.
+ */
+export async function fetchRemoteSpec(
+  url: string,
+  fetchImpl: typeof fetch,
+  timeoutMs: number,
+  maxBytes: number,
+): Promise<RemoteOutcome> {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    let current = url;
+    for (let hop = 0; hop < MAX_REDIRECTS; hop += 1) {
+      // Re-validate before EVERY fetch — covers the initial URL and each
+      // redirect target, so a 302 to a private/metadata host is blocked.
+      if (!isUrlSafe(current)) return { warning: remoteWarning(url, 'blocked by SSRF guard') };
+      const res = await fetchImpl(current, { signal: controller.signal, redirect: 'manual' });
+      if (res.status >= 300 && res.status < 400) {
+        const loc = res.headers.get('location');
+        if (!loc) return { warning: remoteWarning(url, 'redirect without location') };
+        current = new URL(loc, current).toString();
+        continue;
+      }
+      // Terminal response.
+      if (!res.ok) return { warning: remoteWarning(url, `HTTP ${res.status}`) };
+      const declared = res.headers.get('content-length');
+      if (declared && Number(declared) > maxBytes) {
+        return { warning: remoteWarning(url, `exceeds ${maxBytes} bytes`) };
+      }
+      const buf = new Uint8Array(await res.arrayBuffer());
+      if (buf.byteLength > maxBytes) return { warning: remoteWarning(url, `exceeds ${maxBytes} bytes`) };
+      return { entry: { name: remoteSpecFilename(url), content: buf } };
+    }
+    return { warning: remoteWarning(url, 'too many redirects') };
+  } catch (err) {
+    return { warning: remoteWarning(url, err instanceof Error ? err.message : String(err)) };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+export interface AssembleResult {
+  zip: Uint8Array | null;
+  warnings: BuildWarning[];
+  localCount: number;
+  remoteCount: number;
+}
+
+export interface AssembleDeps {
+  projectSlug: string;
+  /** Raw text of `{slug}/{key}` from R2, or null. (lib/r2-content.ts fetchStaticFile) */
+  fetchStaticFile: (slug: string, key: string) => Promise<string | null>;
+  /** Parsed docs.json from R2, or null. (lib/r2-content.ts fetchDocsConfig) */
+  fetchDocsConfig: (slug: string) => Promise<DocsConfig | null>;
+  fetchImpl?: typeof fetch;
+  timeoutMs?: number;
+  maxBytes?: number;
+  /** Clock for the overall remote-fetch budget. Injectable for tests; defaults to Date.now. */
+  now?: () => number;
+  /** Overall wall-clock budget (ms) across all remote fetches. Default 25s, under Vercel's 30s cap. */
+  overallBudgetMs?: number;
+}
+
+/**
+ * Assemble api-specs.zip for one project from R2 + remote URLs. Never throws on
+ * a single spec — failures become non-blocking warnings. Returns `zip: null`
+ * when the project has zero specs (caller 404s).
+ */
+export async function assembleApiSpecsFromR2(deps: AssembleDeps): Promise<AssembleResult> {
+  const {
+    projectSlug, fetchStaticFile, fetchDocsConfig,
+    fetchImpl = fetch, timeoutMs = DEFAULT_TIMEOUT_MS, maxBytes = DEFAULT_MAX_BYTES,
+    now = Date.now, overallBudgetMs = DEFAULT_REMOTE_BUDGET_MS,
+  } = deps;
+  const remoteDeadline = now() + overallBudgetMs;
+
+  const warnings: BuildWarning[] = [];
+  const entries: ZipEntry[] = [];
+  const enc = new TextEncoder();
+
+  // Local specs: the build wrote them to R2 and recorded the keys in
+  // manifest.openapi. Read each verbatim and keep its KEY path in the zip.
+  const manifestRaw = await fetchStaticFile(projectSlug, 'manifest.json');
+  if (manifestRaw) {
+    let openapiKeys: string[] = [];
+    try {
+      const manifest = JSON.parse(manifestRaw) as { openapi?: Record<string, unknown> };
+      openapiKeys = Object.keys(manifest.openapi ?? {});
+    } catch { /* malformed manifest → treat as no locals */ }
+    for (const key of openapiKeys) {
+      const text = await fetchStaticFile(projectSlug, key);
+      if (text == null) {
+        warnings.push(remoteWarning(key, 'not found in R2 at request time'));
+        continue;
+      }
+      entries.push({ name: key, content: enc.encode(text) });
+    }
+  }
+  const localCount = entries.length;
+
+  // Remote specs: declared in docs.json, never uploaded. Fetch (guarded) now.
+  // fetchDocsConfig RE-THROWS on a non-NotFound R2 error (unlike fetchStaticFile,
+  // which returns null) — catch it so a transient config-read failure degrades to
+  // a warning and we still return the locals we already assembled, rather than
+  // discarding a complete local bundle as a 500.
+  let config: DocsConfig | null = null;
+  try {
+    config = await fetchDocsConfig(projectSlug);
+  } catch (err) {
+    warnings.push(remoteWarning('docs.json', `config read failed: ${err instanceof Error ? err.message : String(err)}`));
+  }
+  let remoteCount = 0;
+  if (config) {
+    const remoteUrls = collectConfigOpenApiRefs(config).filter(isHttpUrl);
+    for (const url of remoteUrls) {
+      // Bound total remote time to the overall budget: once spent, skip remaining
+      // remotes (warn) instead of risking a function timeout that would discard the
+      // locals we already have. Clamp each fetch's timeout to the time left so a
+      // single slow remote can't overrun the budget either.
+      const remaining = remoteDeadline - now();
+      if (remaining <= 0) {
+        warnings.push(remoteWarning(url, 'skipped — overall remote-fetch time budget exceeded'));
+        continue;
+      }
+      const outcome = await fetchRemoteSpec(url, fetchImpl, Math.min(timeoutMs, remaining), maxBytes);
+      if ('entry' in outcome) { entries.push(outcome.entry); remoteCount += 1; }
+      else warnings.push(outcome.warning);
+    }
+  }
+
+  return { zip: buildSpecZip(entries), warnings, localCount, remoteCount };
+}

package/vendored/lib/api-specs-markdown-hint.ts

@@ -0,0 +1,49 @@
+/**
+ * Agent-facing footer telling AI tools the site's OpenAPI specs are downloadable
+ * as a single api-specs.zip. Pure + server-safe: no I/O, no request access. The
+ * route resolves the gate inputs (frontmatter, config) and the absolute URL (via
+ * getBaseUrlFromConfig), then calls this.
+ */
+
+import { shouldOfferApiSpecDownload } from './api-spec-offer';
+
+export interface ApiSpecsHintInput {
+  /** ISR mode only — the route + the R2 bundle only exist in prod. */
+  isIsr: boolean;
+  /** The contextual (AI-actions) menu is non-empty. Mirrors the menu gate's
+   *  `options.length === 0` guard: a site with contextual.enabled:false (or
+   *  options:[]) suppresses the menu item, so it must suppress the footer too. */
+  menuEnabled: boolean;
+  /** frontmatter `openapi:` present (a page-level spec ref). */
+  pageHasOpenApi: boolean;
+  /** frontmatter `api:` present (config-driven API page). */
+  pageHasApi: boolean;
+  /** siteHasOpenApiSpecs(config) — the site references ≥1 spec anywhere. */
+  siteHasSpecs: boolean;
+  /** Absolute api-specs.zip URL (getBaseUrlFromConfig is total → normally non-empty). */
+  zipUrl: string;
+}
+
+/**
+ * The footer Markdown to append, or null when it must not appear. The gate
+ * mirrors withApiSpecDownload (lib/api-spec-menu-gate.ts): ISR + the menu is
+ * enabled + the page is an API page + the site actually has ≥1 spec (a page-level
+ * `openapi:` short-circuits the site-wide check, exactly as the menu does). The
+ * zip route is the source of truth (it 404s if assembly is empty); this is a hint.
+ */
+export function apiSpecsMarkdownFooter(input: ApiSpecsHintInput): string | null {
+  const { pageHasOpenApi, pageHasApi, zipUrl } = input;
+  if (
+    !shouldOfferApiSpecDownload({
+      isIsr: input.isIsr,
+      menuEnabled: input.menuEnabled,
+      isApiPage: pageHasOpenApi || pageHasApi,
+      pageHasOpenApi,
+      siteHasSpecs: input.siteHasSpecs,
+    })
+  ) {
+    return null;
+  }
+  if (!zipUrl) return null; // defensive: getBaseUrlFromConfig is total, so this is contract insurance
+  return `\n\n---\n\n📦 **OpenAPI specs:** Every OpenAPI specification referenced by this documentation is available as a single download — ${zipUrl}`;
+}

package/vendored/lib/api-specs-route.ts

@@ -0,0 +1,45 @@
+/**
+ * Request-time handler for /api-specs.zip (+ /docs variant). Assembles the
+ * bundle on demand from R2 + remote specs and streams it as a download.
+ */
+import { NextRequest, NextResponse } from 'next/server';
+
+import { log } from '@/lib/logger';
+import { isIsrMode } from '@/lib/page-isr-helpers';
+import { fetchStaticFile, fetchDocsConfig } from '@/lib/r2-content';
+import { assembleApiSpecsFromR2 } from '@/lib/api-specs-bundle';
+
+export async function apiSpecsRouteHandler(request: NextRequest): Promise<NextResponse> {
+  // ISR-only: assembly needs R2. Local dev has neither R2 nor the menu item.
+  if (!isIsrMode()) return new NextResponse('Not found', { status: 404 });
+
+  const projectSlug = request.headers.get('x-project-slug');
+  if (!projectSlug) {
+    log('warn', 'api-specs.zip request missing project slug');
+    return new NextResponse('Project not found', { status: 404 });
+  }
+
+  try {
+    const result = await assembleApiSpecsFromR2({ projectSlug, fetchStaticFile, fetchDocsConfig });
+    if (result.warnings.length) {
+      log('warn', 'api-specs.zip assembled with warnings', {
+        projectSlug, warnings: result.warnings.map((w) => w.message),
+      });
+    }
+    if (!result.zip) return new NextResponse('No API specs found', { status: 404 });
+
+    return new NextResponse(Buffer.from(result.zip), {
+      headers: {
+        'Content-Type': 'application/zip',
+        'Content-Disposition': 'attachment; filename="api-specs.zip"',
+        // Always fresh: assembly is cheap, downloads are rare. Avoids any
+        // post-rebuild staleness / R2-overwrite-consistency window.
+        'Cache-Control': 'no-store',
+        'X-Robots-Tag': 'noindex',
+      },
+    });
+  } catch (error) {
+    log('error', 'Error assembling api-specs.zip', { projectSlug, error: String(error) });
+    return new NextResponse('Error assembling API specs', { status: 500 });
+  }
+}

package/vendored/lib/docs-types.ts

@@ -712,7 +712,7 @@ export interface ErrorsConfig {
  */
 export type ContextualOption =
   | 'copy' | 'view' | 'chatgpt' | 'claude' | 'gemini' | 'perplexity'
-  | 'mcp' | 'cursor' | 'vscode'
+  | 'mcp' | 'cursor' | 'vscode' | 'download-api-spec'
   | {
       title: string;
       description: string;

package/vendored/lib/heading-extractor.ts

@@ -6,6 +6,8 @@
  * and Steps.tsx.
  */
 
+import GithubSlugger, { slug as githubSlug } from 'github-slugger';
+
 export interface HeadingInfo {
   id: string;
   text: string;
@@ -17,26 +19,27 @@ export interface HeadingInfo {
 
 /**
  * Generate a URL-friendly slug from heading text.
- * Canonical implementation — also duplicated in validate-links.cjs (CJS, can't import).
- */
-export function generateSlug(text: string): string {
-  return text
-    .toLowerCase()
-    .replace(/[^a-z0-9]+/g, '-')
-    .replace(/^-+|-+$/g, '');
-}
-
-/**
- * Suffix `base` with -2, -3, ... if it has been seen before. First occurrence
- * keeps the bare slug for backwards compatibility with existing inbound links.
- * Mutates `seen` in place — caller owns the lifetime (one Map per page).
  *
- * Mirrored in scripts/validate-links.cjs — keep both in sync.
+ * Delegates to github-slugger — the SAME library `rehype-slug` uses to assign the
+ * real heading `id` attributes during MDX compile (wired in render-doc-page.tsx).
+ * Using it here keeps the "On this page" TOC, <Update>/<Step> anchors, and the
+ * link validator byte-for-byte aligned with the actual DOM ids — including for
+ * non-ASCII headings, where the previous `[^a-z0-9]+ -> '-'` implementation
+ * diverged (accents/apostrophes/underscores became dashes) and produced dead
+ * anchors (e.g. heading "Abrir cualquier página" → real id `abrir-cualquier-página`,
+ * but the old slug was `abrir-cualquier-p-gina`).
+ *
+ * Stateless: repeated calls with the same text return the same slug. For
+ * per-document uniqueness across duplicate headings, use a `GithubSlugger`
+ * instance (as extractHeadings does) — it mirrors rehype-slug's `-1`/`-2`
+ * suffixing exactly.
+ *
+ * Mirrored in scripts/validate-links.cjs (CJS — can't import the ESM-only
+ * github-slugger), where the algorithm + regex are replicated and guarded by a
+ * drift test (`validate-links-slug.test.ts`). Keep both in sync.
  */
-export function uniquifySlug(seen: Map<string, number>, base: string): string {
-  const count = seen.get(base) ?? 0;
-  seen.set(base, count + 1);
-  return count === 0 ? base : `${base}-${count + 1}`;
+export function generateSlug(text: string): string {
+  return githubSlug(text);
 }
 
 const HEADING_REGEX = /^(#{1,6})\s+(.+)$/;
@@ -57,6 +60,10 @@ const STEP_TITLE_REGEX = /<Step\s+[^>]*title=(?:"([^"]+)"|'([^']+)')/g;
  * Includes markdown headings, <Update label="..."> component anchors,
  * and <Step title="..."> entries inside <Steps> blocks (with per-block numbering).
  * Skips content inside fenced code blocks.
+ *
+ * A single page-scoped `GithubSlugger` assigns ids so duplicate titles (across
+ * H2s, Update labels, and Steps) get `-1`, `-2`, ... suffixes in source order —
+ * the same algorithm rehype-slug applies to the real markdown-heading DOM ids.
  */
 export function extractHeadings(content: string): HeadingInfo[] {
   const headings: HeadingInfo[] = [];
@@ -67,9 +74,9 @@ export function extractHeadings(content: string): HeadingInfo[] {
   // block can't stick the counter across subsequent blocks.
   let inStepsBlock = false;
   let stepCounter = 0;
-  // Page-scoped slug counter so duplicate titles (across H2s, Update labels,
-  // and Steps) get -2, -3, ... suffixes in source order.
-  const seenSlugs = new Map<string, number>();
+  // Page-scoped slugger so duplicate titles get -1, -2, ... suffixes in source
+  // order, matching rehype-slug's per-document GithubSlugger.
+  const slugger = new GithubSlugger();
 
   for (let i = 0; i < lines.length; i++) {
     const line = lines[i];
@@ -101,9 +108,8 @@ export function extractHeadings(content: string): HeadingInfo[] {
     if (headingMatch) {
       const level = headingMatch[1].length;
       const text = headingMatch[2].trim();
-      const base = generateSlug(text);
-      if (base) {
-        const id = uniquifySlug(seenSlugs, base);
+      if (generateSlug(text)) {
+        const id = slugger.slug(text);
         headings.push({ id, text, level, line: i + 1 });
       }
     }
@@ -111,9 +117,8 @@ export function extractHeadings(content: string): HeadingInfo[] {
     const updateMatch = line.match(UPDATE_LABEL_REGEX);
     if (updateMatch) {
       const text = updateMatch[1];
-      const base = generateSlug(text);
-      if (base) {
-        const id = uniquifySlug(seenSlugs, base);
+      if (generateSlug(text)) {
+        const id = slugger.slug(text);
         headings.push({ id, text, level: 2, line: i + 1 });
       }
     }
@@ -121,10 +126,9 @@ export function extractHeadings(content: string): HeadingInfo[] {
     if (inStepsBlock) {
       for (const match of line.matchAll(STEP_TITLE_REGEX)) {
         const text = match[1] ?? match[2];
-        const base = generateSlug(text);
-        if (!base) continue;
+        if (!generateSlug(text)) continue;
         stepCounter += 1;
-        const id = uniquifySlug(seenSlugs, base);
+        const id = slugger.slug(text);
         headings.push({
           id,
           text,