@writedocs/generator 0.4.6 → 0.4.8

package/src/lib/config.ts

@@ -1,1306 +1,1412 @@
-import fs from 'node:fs';
-import path from 'node:path';
-import matter from 'gray-matter';
-import { writedocsTempDir } from './writedocs-temp-dir.js';
-import {
-  formatValidationIssues,
-  validateDocsConfig,
-  type DocsConfig,
-  type DropdownItem,
-  type FontVariant,
-  type LanguageItem,
-  type NavChildren,
-  type NavItem,
-  type NavigationConfig,
-  type ProductItem,
-  type TabItem,
-  type VersionItem,
-} from './config-schema.ts';
-
-// O schema do writedocs.json mora em ./config-schema.ts desde a extracao (E11):
-// aquele modulo importa so `zod`, sem nada de node:fs, pra que a plataforma
-// possa importa-lo por `@writedocs/generator/config-schema`. Este reexport
-// mantem a superficie deste arquivo exatamente como era - quem importa
-// `docsConfigSchema`, `DocsConfig`, `seoFieldsSchema`, `mergeSeo` etc. de
-// './config.js' continua importando do mesmo lugar, sem mudar uma linha.
-//
-// `.ts` e nao o `./config-schema.js` gerado, de proposito - e a unica coisa no
-// repositorio que ainda aponta pra fonte, e o bin/ e o `exports` apontam pro
-// `.js`. O motivo e que este reexport carrega 24 `export type`/`interface`
-// (DocsConfig, NavItem, Selector, GlobalDropdownView, ContextMenuConfig...) que
-// uma duzia de .astro consome como `import type { X } from '../lib/config'`, e
-// o esbuild apaga todos eles: o `.js` gerado exporta exatamente 5 simbolos de
-// runtime. Este repositorio nao tem tsconfig.json nem o typescript instalado,
-// entao (a) nada configura o mapeamento `.js` -> `.ts` que faria os tipos
-// voltarem e (b) nao existe typecheck que reclamasse - a troca so apagaria os
-// tipos em silencio. Aqui tudo passa pelo transform do Astro/Vite, que le `.ts`
-// nativamente, entao o `.js` nao resolve problema nenhum deste lado.
-//
-// O custo aceito e que o tarball leva as duas copias e um build do Astro pode
-// carregar as duas (o `.ts` por aqui, o `.js` por quem importa o subpath) - duas
-// instancias do schema, inofensivas porque nada compara identidade de schema.
-export * from './config-schema.ts';
-
-/** Normalizes writedocs.json's `domain` into a full origin with no trailing
- *  slash (e.g. "docs.example.com" -> "https://docs.example.com"), or null
- *  if the site hasn't set one. The single source of truth for "does this
- *  site have a real deployed URL" - astro.config.mjs (sitemap
- *  registration), BaseLayout.astro (canonical/OG/Twitter URLs), and
- *  resolveAbsoluteUrl() below all call this rather than reading
- *  config.domain directly, so the http(s):// normalization only happens
- *  in one place. */
-export function resolveSiteUrl(config: Pick<DocsConfig, 'domain'>): string | null {
-  if (!config.domain) return null;
-  const withScheme = /^https?:\/\//i.test(config.domain) ? config.domain : `https://${config.domain}`;
-  return withScheme.replace(/\/+$/, '');
-}
-
-/** Resolves a possibly-relative asset path (e.g. `seo.ogImage: "/card.png"`)
- *  against the site's own domain into an absolute URL - social crawlers
- *  (Facebook/Twitter/Slack unfurls) generally require an absolute
- *  og:image/twitter:image URL, a same-origin relative path isn't reliably
- *  respected. Returns the value unchanged if it's already absolute, or if
- *  there's no siteUrl to resolve it against (a relative path is still
- *  better than nothing in that case - most social crawlers do at least
- *  attempt to fetch it relative to the page they scraped). */
-export function resolveAbsoluteUrl(siteUrl: string | null, value: string): string {
-  if (/^https?:\/\//i.test(value)) return value;
-  if (!siteUrl) return value;
-  return `${siteUrl}${value.startsWith('/') ? '' : '/'}${value}`;
-}
-
-/** The resolved (never-undefined) Shiki theme names for light/dark code
- *  blocks - shared by astro.config.mjs (sitewide MDX code-fence
- *  highlighting) and ApiReferencePanel.astro (the API playground's own
- *  separate <Code/> usages, which don't inherit markdown.shikiConfig at
- *  all - see astro.config.mjs's own comment on that) so both read the
- *  same writedocs.json field and fall back to the same defaults instead of
- *  each hardcoding its own copy. */
-export function resolveCodeblockTheme(config: DocsConfig): { light: string; dark: string } {
-  return {
-    light: config.styles.codeblocks?.light ?? 'github-light',
-    dark: config.styles.codeblocks?.dark ?? 'github-dark',
-  };
-}
-
-// mdx is a real, bundled Shiki grammar (@shikijs/langs' mdx.mjs - it does
-// exist, this isn't a "Shiki doesn't know this language" situation), but in
-// practice it tokenizes ```mdx fences into one single run per line with no
-// internal token boundaries at all - every character, JSX tag or not,
-// lands in the exact same TextMate scope and renders in the theme's plain
-// foreground color. Confirmed directly against real built output: every
-// span in a ```mdx block's compiled HTML carries the identical inline
-// color, none of the tag/attribute/string distinction a JS or JSX fence
-// gets. Aliasing to jsx - a close structural match for the JSX-heavy
-// snippets these fences are actually used for in this codebase's own docs
-// (`<Callout>`, `<Card>`, etc.) - actually highlights the tags/attributes,
-// at the cost of not distinctly coloring the markdown-prose portions
-// interleaved between them (jsx's grammar doesn't know about those) - a
-// worthwhile trade given the alternative is no color at all. See
-// astro.config.mjs's own shikiConfig.langAlias for where this actually
-// gets used. */
-const DEFAULT_CODEBLOCK_LANG_ALIAS: Record<string, string> = { mdx: 'jsx' };
-
-/** The resolved fence-language alias map - the built-in mdx -> jsx default
- *  above, merged with (not replaced by) whatever a site adds under its own
- *  writedocs.json styles.codeblocks.langAlias, so a site can extend this list
- *  without having to redeclare the built-in entry to keep it. Same
- *  "shared resolver, not each consumer re-deriving its own defaults"
- *  pattern resolveCodeblockTheme() right above already establishes -
- *  though today only astro.config.mjs actually consumes this one, unlike
- *  that one, since ApiReferencePanel.astro's own <Code/> usages never
- *  render a `mdx`-tagged snippet (API operation samples are curl/js/
- *  python/etc., not MDX markup) to begin with. */
-export function resolveCodeblockLangAlias(config: DocsConfig): Record<string, string> {
-  return { ...DEFAULT_CODEBLOCK_LANG_ALIAS, ...config.styles.codeblocks?.langAlias };
-}
-
-const DEFAULT_FONT_FAMILY = 'Inter';
-
-export interface ResolvedFonts {
-  base: FontVariant;
-  heading: FontVariant | null;
-  body: FontVariant | null;
-}
-
-/** Resolves writedocs.json's `styles.fonts` into the three font declarations
- *  BaseLayout.astro actually needs to render: `base` (the site-wide
- *  default - every element gets this unless `heading`/`body` narrows it
- *  further), and `heading`/`body`, each `null` when not independently
- *  configured (letting BaseLayout fall back to `base` for whichever side
- *  wasn't overridden, rather than this function silently copying `base`
- *  into both and losing the distinction between "explicitly set to the
- *  same font" and "just inheriting the default"). The one hardcoded
- *  default in this whole feature lives right here: no `styles.fonts` at
- *  all resolves to plain Inter, loaded for real (a Google Fonts `<link>`,
- *  not just a name in a fallback stack that only renders correctly for a
- *  reader who happens to already have Inter installed - see base.css's
- *  old `font-family` rule, which was exactly that, before this feature
- *  existed). */
-export function resolveFonts(config: DocsConfig): ResolvedFonts {
-  const fonts = config.styles.fonts;
-  const base: FontVariant = fonts
-    ? { family: fonts.family, weight: fonts.weight, source: fonts.source, format: fonts.format }
-    : { family: DEFAULT_FONT_FAMILY };
-  return { base, heading: fonts?.heading ?? null, body: fonts?.body ?? null };
-}
-
-/** The Google Fonts CSS2 API URL for every font in `fonts` that isn't a
- *  `source`-based (local/externally-hosted) font - `null` if there's
- *  nothing to load this way at all (every configured font has its own
- *  `source`). One request covers every family needed (`&family=` repeated
- *  per unique family+weight pair, deduped so the same pair - e.g. `base`
- *  and `body` both left at the site default - isn't requested twice)
- *  rather than a separate `<link>` per font. `display=swap` avoids an
- *  invisible-text flash while the font file loads (renders in the
- *  fallback stack immediately, swaps once the real font is ready) -
- *  Google's own recommended default for exactly this use case. */
-export function googleFontsHref(fonts: ResolvedFonts): string | null {
-  const entries = [fonts.base, fonts.heading, fonts.body].filter(
-    (f): f is FontVariant => f !== null && !f.source
-  );
-  if (entries.length === 0) return null;
-  const seen = new Set<string>();
-  const params: string[] = [];
-  for (const f of entries) {
-    const key = `${f.family}|${f.weight ?? ''}`;
-    if (seen.has(key)) continue;
-    seen.add(key);
-    const familyParam = f.family.trim().replace(/\s+/g, '+');
-    params.push(f.weight ? `family=${familyParam}:wght@${f.weight}` : `family=${familyParam}`);
-  }
-  return `https://fonts.googleapis.com/css2?${params.join('&')}&display=swap`;
-}
-
-/** A `@font-face` rule for one `source`-based font (local project path or
- *  externally-hosted URL), or `''` for a Google Font (no `source` - see
- *  googleFontsHref() above, the other half of font loading). `weight`
- *  becomes the rule's `font-weight` *descriptor* here - it tells the
- *  browser which weight this specific file represents, so a `font-weight`
- *  CSS value requested elsewhere (BaseLayout.astro's own
- *  `wdFontWeightHeading`/`wdFontWeightBody`, see its comment) picks the
- *  real matching file instead of synthetically ("faux") bolding/
- *  thinning a mismatched one. This function only ever produces the
- *  `@font-face` rule itself - actually applying `font-weight` to any
- *  element (h1-h6, body) is BaseLayout's job, not this one's. */
-export function fontFaceRule(font: FontVariant | null): string {
-  if (!font || !font.source) return '';
-  const weightDecl = font.weight !== undefined ? ` font-weight: ${font.weight};` : '';
-  return `@font-face { font-family: '${font.family}'; src: url('${font.source}') format('${font.format ?? 'woff2'}'); font-display: swap;${weightDecl} }`;
-}
-
-/** Splits one side of `styles.navbar` (the string-or-object union
- *  navbarColorValueSchema allows) into its two parts, filling in the
- *  fallback background when the field is unset at all. `accent` stays
- *  `undefined` - not defaulted here - for both the bare-string case and
- *  the object case where a site set `background` without `accent`;
- *  BaseLayout.astro is what turns that `undefined` into "fall back to
- *  --wd-primary" for the accent CSS var. There's no `foreground` here at
- *  all to resolve - the navbar's text/icon color is never read from
- *  writedocs.json, see `navbar`'s own schema comment (stylesSchema) for why. */
-export function resolveNavbarColor(
-  value: string | { background: string; accent?: string } | undefined,
-  fallbackBackground: string
-): { background: string; accent: string | undefined } {
-  if (!value) return { background: fallbackBackground, accent: undefined };
-  if (typeof value === 'string') return { background: value, accent: undefined };
-  return { background: value.background, accent: value.accent };
-}
-
-/** Picks black or white text for readable contrast against `hexColor`,
- *  via the standard relative-luminance formula (ITU-R BT.601 weights -
- *  the same "perceived brightness" approximation used all over the web
- *  for exactly this "what text color goes on this swatch" problem, not
- *  the more expensive WCAG relative-luminance formula, which isn't
- *  needed for a binary choose-the-less-bad-option decision like this
- *  one). Used two ways in BaseLayout.astro: for `--wd-navbar-accent-text`
- *  (the active tab's own fill used to always be `var(--wd-primary)` with
- *  hardcoded `color: #fff`, which only actually read fine because every
- *  default/example primary color so far has been dark/saturated enough
- *  for white text; once a site's navbar accent can be *any* color -
- *  `styles.navbar.light.accent`, falling back to `styles.colors.primary`
- *  when unset, see resolveNavbarColor() above - that assumption can't
- *  hold unconditionally), and for `--wd-navbar-foreground` itself once
- *  `styles.navbar` is configured at all (the navbar's plain text/icon
- *  color - see `navbar`'s own schema comment for why that's always
- *  computed, never a writedocs.json value). Malformed input (not a 6-digit
- *  `#rrggbb` hex) falls back to white rather than throwing - same "don't
- *  fail a build over a cosmetic color value" posture every other color
- *  field here takes (none of them validate hex syntax either). */
-export function contrastTextColor(hexColor: string): '#000000' | '#ffffff' {
-  const match = /^#?([0-9a-f]{6})$/i.exec(hexColor.trim());
-  if (!match) return '#ffffff';
-  const hex = match[1];
-  const r = parseInt(hex.slice(0, 2), 16);
-  const g = parseInt(hex.slice(2, 4), 16);
-  const b = parseInt(hex.slice(4, 6), 16);
-  const luminance = (299 * r + 587 * g + 114 * b) / 1000;
-  return luminance > 150 ? '#000000' : '#ffffff';
-}
-
-/** Whether an href points off-site - has an explicit scheme (`https:`,
- *  `mailto:`, `tel:`, ...) or is protocol-relative (`//...`) - versus a
- *  same-site path, which this codebase always produces as a single
- *  leading slash (hrefForSlug() in [...slug].astro). Used everywhere a
- *  nav link is rendered to decide whether it should open in a new tab;
- *  deliberately a plain string check rather than a schema-level flag,
- *  so it applies uniformly to every href source (topbar.links, a
- *  switcher/tab pill pointing at a bare `href` container, a global
- *  dropdown's own link, a sidebar link leaf) without threading an
- *  `external` field through every one of those call sites. */
-export function isExternalHref(href: string): boolean {
-  return /^[a-z][a-z0-9+.-]*:/i.test(href) || href.startsWith('//');
-}
-
-// ---------------------------------------------------------------------
-// Icons - writedocs.json's `icon` fields (TabItem, DropdownItem, ProductItem,
-// Card) are plain strings with no schema-level distinction between "an
-// emoji, paste it verbatim" and "an icon-set name, look it up". Resolved
-// here rather than validated in the schema, since both are valid uses of
-// the same string field and the right rendering only becomes obvious once
-// you look at the value's shape.
-// ---------------------------------------------------------------------
-
-export type IconResolution =
-  | { kind: 'iconify'; name: string } // ready for astro-icon/components' <Icon name=... />
-  | { kind: 'text'; value: string }; // literal text/emoji, rendered as-is
-
-const DEFAULT_ICON_COLLECTION = 'lucide';
-
-/** Resolves a writedocs.json `icon` string into either an Iconify icon id or
- *  literal text, covering three forms:
- *  - "collection:icon-name" (e.g. "mdi:server", "simple-icons:github")
- *    - used as-is against whatever @iconify-json/* collections are
- *    installed (see astro.config.mjs / package.json).
- *  - a bare name using only letters/digits/hyphens (e.g. "smartphone",
- *    "book-open") - defaults to the "lucide" collection, matching what
- *    docs.json-examples/ already assumes for plain icon-name strings.
- *  - anything else (an emoji, a symbol, arbitrary text) - rendered
- *    verbatim, preserving the original "just paste an emoji" behavior
- *    from before icon-library support existed. */
-export function resolveIcon(icon: string): IconResolution {
-  if (/^[a-z0-9-]+:[a-z0-9-]+$/i.test(icon)) return { kind: 'iconify', name: icon };
-  if (/^[a-z0-9-]+$/i.test(icon)) return { kind: 'iconify', name: `${DEFAULT_ICON_COLLECTION}:${icon}` };
-  return { kind: 'text', value: icon };
-}
-
-// ---------------------------------------------------------------------
-// OpenAPI navigation expansion - turns a group's `openapi: { src, path }`
-// shorthand into a concrete `{ group, pages }` (one sub-group per tag),
-// using the per-spec manifest generate-api-pages.js writes to
-// writedocsTempDir()'s openapi/<path>/manifest.json before Astro starts (both
-// `writedocs dev` and `writedocs build` run it first - see
-// src/cli/dev.js, src/cli/build.js). Applied once, here in
-// loadDocsConfig(), so every other function in this file
-// (resolveSections, flattenNav, buildNavTree, ...) only ever sees plain
-// page-slug strings and ordinary `{ group, pages }` nodes, and never
-// needs to know the `openapi` group shorthand exists. A writedocs.json can
-// have any number of these groups, each pointing at its own spec and
-// mounted under its own `path` - generate-api-pages.js namespaces each
-// spec's manifest/operations under that same `path`, so there's no
-// cross-spec collision as long as every group uses a distinct `path`.
-// ---------------------------------------------------------------------
-
-export interface OpenApiManifestEntry {
-  slug: string;
-  method: string;
-  path: string;
-  tags: string[];
-  title: string;
-  generated: boolean;
-}
-
-/** `specPath` is the owning group's own `openapi.path` (e.g. "/api") -
- *  generate-api-pages.js writes each spec's manifest under a directory
- *  named after that same value, so this only ever needs to know which
- *  group is asking, not anything about the spec's contents itself. */
-function loadOpenApiManifest(contentDir: string, specPath: string): OpenApiManifestEntry[] | null {
-  const normalized = specPath.replace(/^\/+|\/+$/g, '');
-  const manifestPath = path.join(writedocsTempDir(contentDir), 'openapi', normalized, 'manifest.json');
-  if (!fs.existsSync(manifestPath)) return null;
-  try {
-    return JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
-  } catch {
-    return null; // stale/partial write from an interrupted previous run - treat as absent
-  }
-}
-
-/** Expands one group's `openapi: { src, path }` into the `pages` array
- *  it stands in for - one sub-group per tag (in first-seen order),
- *  untagged operations collected into a trailing "Other" group. Returns
- *  an empty array (an empty, harmless group) rather than throwing if the
- *  manifest is missing - generate-api-pages.js always runs before this
- *  does (see src/cli/dev.js/build.js), so a missing manifest here means
- *  generation hasn't happened yet rather than a user error worth
- *  crashing the dev server over. */
-function expandOpenApiGroupPages(openapiRef: { src: string; path: string }, contentDir: string): NavItem[] {
-  const manifest = loadOpenApiManifest(contentDir, openapiRef.path);
-  if (!manifest) return [];
-
-  const seenTags: string[] = [];
-  const byTag = new Map<string, string[]>();
-  const untagged: string[] = [];
-  for (const op of manifest) {
-    const tag = op.tags[0];
-    if (!tag) {
-      untagged.push(op.slug);
-      continue;
-    }
-    if (!byTag.has(tag)) {
-      byTag.set(tag, []);
-      seenTags.push(tag);
-    }
-    byTag.get(tag)!.push(op.slug);
-  }
-  const groups: NavItem[] = seenTags.map((tag) => ({ group: tag, pages: byTag.get(tag)! }));
-  return untagged.length > 0 ? [...groups, { group: 'Other', pages: untagged }] : groups;
-}
-
-function expandOpenApiInPages(pages: NavItem[], contentDir: string): NavItem[] {
-  return pages.map((item): NavItem => {
-    if (typeof item === 'string') return item;
-    if ('href' in item) return item;
-    if ('openapi' in item) {
-      // A group using the { group, openapi: { src, path } } shorthand -
-      // replace it with a real { group, pages } node built from that
-      // spec's own manifest, so nothing downstream needs to know the
-      // shorthand ever existed.
-      return { group: item.group, pages: expandOpenApiGroupPages(item.openapi, contentDir) };
-    }
-    // An ordinary { group, page?, pages } - recurse into its own pages,
-    // since an openapi-group can be nested inside a hand-authored group
-    // too (e.g. wrapping it to add hand-written pages alongside the
-    // auto-generated ones).
-    return { ...item, pages: expandOpenApiInPages(item.pages, contentDir) };
-  });
-}
-
-/** Mirrors walkSections()'s traversal (tabs/versions/languages/
- *  dropdowns/products, each bottoming out at `pages`), but rewrites
- *  rather than collects - every `pages` array anywhere in the tree gets
- *  run through expandOpenApiInPages(). */
-function expandOpenApiInContainer(node: NavChildren, contentDir: string): NavChildren {
-  if ('pages' in node) return { pages: expandOpenApiInPages(node.pages, contentDir) };
-  if ('href' in node) return node;
-  if ('tabs' in node) {
-    return { tabs: node.tabs.map((t) => ({ ...t, ...expandOpenApiInContainer(t, contentDir) })) };
-  }
-  if ('versions' in node) {
-    return { versions: node.versions.map((v) => ({ ...v, ...expandOpenApiInContainer(v, contentDir) })) };
-  }
-  if ('languages' in node) {
-    return { languages: node.languages.map((l) => ({ ...l, ...expandOpenApiInContainer(l, contentDir) })) };
-  }
-  if ('dropdowns' in node) {
-    return { dropdowns: node.dropdowns.map((d) => ({ ...d, ...expandOpenApiInContainer(d, contentDir) })) };
-  }
-  if ('products' in node) {
-    return { products: node.products.map((p) => ({ ...p, ...expandOpenApiInContainer(p, contentDir) })) };
-  }
-  return node;
-}
-
-function expandOpenApiInNavigation(navigation: NavigationConfig, contentDir: string): NavigationConfig {
-  if (Array.isArray(navigation)) return expandOpenApiInPages(navigation, contentDir);
-  const expanded = { ...navigation, ...expandOpenApiInContainer(navigation as Container, contentDir) };
-  if (navigation.global?.dropdowns) {
-    expanded.global = {
-      dropdowns: navigation.global.dropdowns.map(
-        (d) => ({ ...d, ...expandOpenApiInContainer(d, contentDir) }) as DropdownItem
-      ),
-    };
-  }
-  return expanded as NavigationConfig;
-}
-
-export function loadDocsConfig(contentDir: string): DocsConfig {
-  const configPath = path.join(contentDir, 'writedocs.json');
-  if (!fs.existsSync(configPath)) {
-    throw new Error(
-      `[writedocs] writedocs.json not found at ${configPath}. Run "writedocs init" to scaffold one.`
-    );
-  }
-  // A validacao em si (JSON.parse incluso) vive em validateDocsConfig
-  // (./config-schema.ts), o mesmo ponto de entrada que o `writedocs validate` e
-  // a plataforma usam - e o que garante que os tres reportem exatamente os
-  // mesmos problemas, com as mesmas palavras.
-  //
-  // As duas formas de falhar continuam saindo daqui EXATAMENTE como saiam antes
-  // desta extracao:
-  //   - JSON quebrado: relanca o proprio SyntaxError do JSON.parse (mesmo tipo,
-  //     mesma mensagem que o runtime produz);
-  //   - schema invalido: o mesmo Error, com o mesmo texto, montado a partir do
-  //     mesmo formatador que a CLI usa.
-  const result = validateDocsConfig(fs.readFileSync(configPath, 'utf-8'));
-  if (!result.ok) {
-    if (result.parseError) throw result.parseError;
-    throw new Error(`[writedocs] writedocs.json failed validation:\n${formatValidationIssues(result.issues)}`);
-  }
-  // A no-op pass over ordinary navigation trees (no openapi groups) -
-  // always run, rather than gated behind a global manifest check, since
-  // there's no longer a single global spec to check for.
-  result.data.navigation = expandOpenApiInNavigation(result.data.navigation, contentDir);
-  return result.data;
-}
-
-// --- Locating a page by file id, independent of its effective slug -----
-//
-// writedocs.json's `pages` arrays, and every helper above/below that walks
-// them (flattenNav, firstSlugOf, containerContainsSlug, buildNavTree, ...),
-// always identify a page by its file id - its path relative to the
-// content directory (project root), extension stripped, with a trailing
-// `/index` segment dropped (matching Astro's own default id computation -
-// see the `/index` note below) - regardless of how that page ends up
-// being served. docs/ is not special: a file at `docs/guides/x.mdx` has
-// file id `docs/guides/x`, the exact same rule applied to a file
-// anywhere else in the project.
-//
-// A page's actual URL is a separate question, and Astro's own glob()
-// content loader already has a first-class answer for it: if a page's
-// frontmatter sets `slug`, `entry.id` (and therefore the route Astro
-// builds for it) becomes that value verbatim instead of the file-path
-// default - see astro/dist/content/loaders/glob.js's generateIdDefault:
-// `if (data.slug) return data.slug`. content.config.ts's `slug` schema
-// field is deliberately the same field Astro already recognizes, so
-// nothing here needs to reimplement the override or track it separately -
-// it only needs a way to find a page BY file id (to resolve writedocs.json's
-// references) even once `entry.id` no longer equals it.
-//
-// --- Page discovery -------------------------------------------------
-//
-// Any .md/.mdx file anywhere under the content directory becomes a page
-// candidate the moment it has *any* frontmatter block at all - docs/ has
-// no special status here, it's just a folder like any other (a
-// conventional, recommended place to put most pages, not a requirement).
-// content.config.ts's `pages` collection is the same docsSchema applied
-// to exactly this file set. A file with zero frontmatter (no `---` block
-// whatsoever) is never a page candidate - a snippet (see
-// docs/dev/docs/snippets.mdx) typically has none, which is what lets it
-// live anywhere without tripping schema validation. A file that *does*
-// open a frontmatter block but is missing a required field (`title`)
-// still fails validation exactly as before - only "no frontmatter at
-// all" is new; a genuine mistake (frontmatter present, title forgotten)
-// stays a loud build error rather than being silently treated as
-// non-page content.
-//
-// A handful of directories are never scanned regardless of what's in
-// them - build output, dependencies, and writedocs' own working
-// directories, none of which a site author would ever intend as page
-// content. Only excluded at the content directory's own top level (a
-// hand-authored `guides/dist-notes.mdx` isn't mistaken for the build
-// output directory `dist/` just because a folder two levels down happens
-// to also be named `dist`).
-const EXCLUDED_TOP_LEVEL_DIRS = new Set(['node_modules', 'dist', '.astro', '.writedocs', 'public', '.git']);
-
-/** Recursively finds every .md/.mdx file under `contentDir` that has a
- *  frontmatter block, skipping the handful of build/dependency
- *  directories a real content directory tends to also contain (see
- *  EXCLUDED_TOP_LEVEL_DIRS above) - docs/ is scanned exactly like any
- *  other folder, no special-casing. Returns POSIX-relative paths (from
- *  `contentDir`) suitable to hand straight to Astro's `glob()` loader as
- *  a literal `pattern` array - see content.config.ts's `pages`
- *  collection, and [...slug].astro, which needs the identical list to
- *  decide whether calling `getCollection('pages')` is worth doing at all
- *  (see content.config.ts's own comment on why an empty collection still
- *  needs to exist, just backed by a no-op loader, to avoid Astro's "does
- *  not exist or is empty" warning). Also reused directly by
- *  astro.config.mjs's noindex/sitemap scan, so that scan always sees
- *  exactly the same file set that actually becomes a page - no risk of
- *  the two drifting apart. Synchronous and re-run from scratch wherever
- *  it's called rather than cached and shared across modules - consistent
- *  with how loadDocsConfig() itself is already called repeatedly across
- *  this codebase instead of threaded through as shared state, and cheap
- *  enough in practice (a docs site's own file count) not to matter. */
-export function findAllPages(contentDir: string): string[] {
-  const results: string[] = [];
-  function walk(dir: string, relBase: string) {
-    let entries: fs.Dirent[];
-    try {
-      entries = fs.readdirSync(dir, { withFileTypes: true });
-    } catch {
-      return;
-    }
-    for (const entry of entries) {
-      const rel = relBase ? `${relBase}/${entry.name}` : entry.name;
-      const abs = path.join(dir, entry.name);
-      if (entry.isDirectory()) {
-        if (relBase === '' && EXCLUDED_TOP_LEVEL_DIRS.has(entry.name)) continue;
-        walk(abs, rel);
-        continue;
-      }
-      if (!entry.isFile() || !/\.mdx?$/i.test(entry.name)) continue;
-      let raw: string;
-      try {
-        raw = fs.readFileSync(abs, 'utf-8');
-      } catch {
-        continue;
-      }
-      const { data } = matter(raw);
-      if (Object.keys(data).length === 0) continue; // no frontmatter at all - not a page
-      results.push(rel);
-    }
-  }
-  walk(contentDir, '');
-  return results;
-}
-
-/** Any `.css`/`.js` file anywhere in the project - root or any subfolder,
- *  `public/` included - auto-loaded site-wide with zero `writedocs.json`
- *  config, on top of (not instead of) the explicit `scripts` field
- *  (bannerSchema and friends, above). Drop a file in, it loads;
- *  there's no field naming which ones to use, matching the same "just
- *  works" convention `docs/`'s own file discovery already follows (see
- *  findAllPages() above / `content-pipeline.mdx`) - a site author already
- *  drops content files in and expects them found, rather than also
- *  listing every one in writedocs.json.
- *
- *  Two separate walks, because `public/` needs different treatment than
- *  everywhere else:
- *
- *  - `css`/`js`: every `.css`/`.js` file outside `public/` (root, `docs/`,
- *    `snippets/`, any custom folder) - reused as the walk-with-exclusions
- *    shape from findAllPages() above, and its exact `EXCLUDED_TOP_LEVEL_DIRS`
- *    set (skipped only at the project root, same as there), so `dist/`,
- *    `node_modules/`, `.astro/`, `.writedocs/`, `.git/`, and (for this
- *    half only - see below) `public/` are never walked into. BaseLayout.astro
- *    reads each one's raw content and inlines it as a `<style>`/
- *    `<script is:inline>` tag.
- *  - `publicCss`/`publicJs`: every `.css`/`.js` file *inside* `public/`,
- *    walked separately (starting from `<contentDir>/public` rather than
- *    `contentDir` itself, so the same `EXCLUDED_TOP_LEVEL_DIRS` check
- *    doesn't apply here - there's no `public/public/` or `public/dist/`
- *    convention to guard against). Returned as public-URL-rooted hrefs
- *    (a leading `/`, no `public` segment - `public/custom.css` becomes
- *    `/custom.css`) rather than content-dir-relative paths, since these
- *    files are already served as static assets at exactly that URL once
- *    Astro copies `public/` into the build output. BaseLayout.astro
- *    renders these as ordinary `<link rel="stylesheet">`/`<script src>`
- *    tags pointing at that URL instead of inlining their content -
- *    inlining would duplicate every byte (once in the page's own HTML,
- *    once more as the independently-fetchable static file at that same
- *    URL) for no benefit, where a `<link>`/`<script src>` gets normal
- *    browser caching across pages instead of repeating the content on
- *    every single page's markup.
- *
- *  Both halves are broader than they might sound - a stray `.js` file
- *  kept in `docs/`, `snippets/`, or `public/` for an unrelated reason
- *  (a snippet's own local helper, an image gallery's lightbox script
- *  someone dropped in `public/` to reference from a raw `<script src>`
- *  in an .mdx file, say) gets auto-injected sitewide the same as a
- *  deliberate one; there's no separate "this one's just tooling" signal
- *  to opt out of the convention short of renaming its extension.
- *
- *  Both `css`/`js` and `publicCss`/`publicJs` are sorted alphabetically
- *  by their respective path for deterministic load order across rebuilds
- *  - same reasoning as llms.txt's own alphabetical-by-slug sort (see
- *  llms.txt.ts) - filesystem readdir order isn't guaranteed portable
- *  across OSes or directory-walk order otherwise.
- *
- *  `css`/`js` return POSIX-separated paths relative to `contentDir`, not
- *  absolute paths or file contents - BaseLayout.astro (the sole caller)
- *  resolves and reads each one's content itself, right before inlining
- *  it, so a file's content is always current as of that specific
- *  request/build rather than cached here across a `writedocs dev`
- *  session. `publicCss`/`publicJs` return the public-URL hrefs described
- *  above - nothing to read, Astro's own static-file serving/copy already
- *  handles those. */
-export function findRootAssets(
-  contentDir: string
-): { css: string[]; js: string[]; publicCss: string[]; publicJs: string[] } {
-  const css: string[] = [];
-  const js: string[] = [];
-  function walk(dir: string, relBase: string) {
-    let entries: fs.Dirent[];
-    try {
-      entries = fs.readdirSync(dir, { withFileTypes: true });
-    } catch {
-      return;
-    }
-    for (const entry of entries) {
-      const rel = relBase ? `${relBase}/${entry.name}` : entry.name;
-      const abs = path.join(dir, entry.name);
-      if (entry.isDirectory()) {
-        if (relBase === '' && EXCLUDED_TOP_LEVEL_DIRS.has(entry.name)) continue;
-        walk(abs, rel);
-        continue;
-      }
-      if (!entry.isFile()) continue;
-      if (/\.css$/i.test(entry.name)) css.push(rel);
-      else if (/\.js$/i.test(entry.name)) js.push(rel);
-    }
-  }
-  walk(contentDir, '');
-  css.sort();
-  js.sort();
-
-  const publicCss: string[] = [];
-  const publicJs: string[] = [];
-  function walkPublic(dir: string, relBase: string) {
-    let entries: fs.Dirent[];
-    try {
-      entries = fs.readdirSync(dir, { withFileTypes: true });
-    } catch {
-      return;
-    }
-    for (const entry of entries) {
-      const rel = relBase ? `${relBase}/${entry.name}` : entry.name;
-      const abs = path.join(dir, entry.name);
-      if (entry.isDirectory()) {
-        walkPublic(abs, rel);
-        continue;
-      }
-      if (!entry.isFile()) continue;
-      if (/\.css$/i.test(entry.name)) publicCss.push(`/${rel}`);
-      else if (/\.js$/i.test(entry.name)) publicJs.push(`/${rel}`);
-    }
-  }
-  walkPublic(path.join(contentDir, 'public'), '');
-  publicCss.sort();
-  publicJs.sort();
-
-  return { css, js, publicCss, publicJs };
-}
-
-/** The root-relative URL paths (leading `/`, e.g. `/images/hero.svg`)
- *  referenced by the writedocs.json/styles fields that point at a static asset
- *  *by URL* rather than embedding it inline: `styles.favicon`,
- *  `styles.logo` (both the plain-string and `{light, dark}` object forms),
- *  `styles.background.images.{light,dark}`, and `seo.ogImage`. External
- *  URLs (anything not starting with `/` - `https://...`, mainly) are
- *  filtered out, since those need no local file resolution at all.
- *  Deduped, since e.g. `logo.light` and `background.images.light`
- *  coincidentally pointing at the same file shouldn't resolve/copy it
- *  twice.
- *
- *  Used by `stylesAssetFallback()` (`styles-asset-integration.js`,
- *  imported from `astro.config.mjs`) to let every one of these resolve
- *  from *anywhere* in the project, not just `public/` - previously,
- *  `public/` was the one place `styles.background.images` (etc.) had to
- *  live, since Astro's own `publicDir` copy is the only thing that ever
- *  served them; everywhere else in this codebase's own "drop a file
- *  anywhere, it's found" convention (`findRootAssets()` right above,
- *  `findAllPages()` for content) already worked project-wide. See that
- *  integration's own comment for the actual resolution mechanism (a dev-time
- *  middleware plus a post-build copy step, not a duplicated `publicDir`)
- *  and why a straight copy-into-`public/`-on-disk approach was rejected.
- *
- *  Logo light/dark resolution here deliberately mirrors BaseLayout.astro's
- *  own `logoLight`/`logoDark` derivation exactly (a plain-string `logo`
- *  counts as both light and dark) - two independent implementations of
- *  that same union-unwrapping would only be one accidental edit away from
- *  disagreeing with each other. `footer.logo` (footerSchema) gets the
- *  same treatment, independently of `styles.logo` - both are collected
- *  unconditionally here (not just whichever one BaseLayout.astro would
- *  actually end up using for a given page), since this function has no
- *  page context to know which page modes render a footer at all; an
- *  unreferenced path collected here that never actually renders anywhere
- *  is harmless (nothing copies/resolves a file that's never requested),
- *  but a real footer.logo file silently 404ing because this function
- *  didn't know to resolve it is exactly the bug this comment is warning
- *  future edits away from repeating.
- *
- *  Per-page frontmatter `seo.ogImage` overrides are deliberately out of
- *  scope - those aren't visible from a `DocsConfig` alone (they live in
- *  each page's own frontmatter, merged in per-request by [...slug].astro/
- *  BaseLayout.astro), and resolving every page's own override would need
- *  a full content scan this function has no reason to also become. A
- *  page overriding `seo.ogImage` to something outside `public/` still
- *  needs to put it there for now. */
-export function collectConfiguredAssetPaths(config: DocsConfig): string[] {
-  const logo = config.styles.logo;
-  const logoLight = typeof logo === 'string' ? logo : logo?.light;
-  const logoDark = typeof logo === 'string' ? logo : logo?.dark;
-  const footerLogo = config.footer.logo;
-  const footerLogoLight = typeof footerLogo === 'string' ? footerLogo : footerLogo?.light;
-  const footerLogoDark = typeof footerLogo === 'string' ? footerLogo : footerLogo?.dark;
-  const fonts = config.styles.fonts;
-  const raw: (string | undefined)[] = [
-    config.styles.favicon,
-    logoLight,
-    logoDark,
-    footerLogoLight,
-    footerLogoDark,
-    config.styles.background?.images?.light,
-    config.styles.background?.images?.dark,
-    config.seo?.ogImage,
-    // A `styles.fonts` `source` is only ever handled here when it's a
-    // project-relative path (the `p.startsWith('/')` filter below already
-    // excludes both Google Font names, which never start with "/", and a
-    // full https:// external font URL, which the browser fetches directly
-    // - neither needs resolving/copying through this pipeline at all).
-    fonts?.source,
-    fonts?.heading?.source,
-    fonts?.body?.source,
-  ];
-  const paths = raw.filter((p): p is string => Boolean(p) && p.startsWith('/'));
-  return Array.from(new Set(paths));
-}
-
-export interface DocsEntryLike {
-  id: string;
-  filePath?: string;
-}
-
-/** Recovers a content entry's writedocs.json-facing file id (its path
- *  relative to the content directory, extension stripped, trailing
- *  `/index` dropped), independent of any frontmatter `slug` override -
- *  `entry.filePath` is always root-relative and POSIX-separated (how
- *  Astro's content layer records it, relative to whatever `--root` Astro
- *  itself was invoked with - see run-astro.js), so both it and the
- *  content directory are resolved to absolute paths before comparing,
- *  rather than string-matching a prefix that could be relative,
- *  absolute, or platform-separated inconsistently.
- *
- *  The trailing-`/index`-drop mirrors Astro's own default id computation
- *  exactly (`getContentEntryIdAndSlug()` in astro/dist/content/
- *  utils.js: segments are joined then `.replace(/\/index$/, '')`) -
- *  without it, a nested index file like `docs/guides/index.mdx` (Astro's
- *  own default id: "docs/guides") would recover the wrong file id here
- *  ("docs/guides/index"), and a writedocs.json reference written to match the
- *  page's real URL would fail to resolve. A single-segment `index.mdx`
- *  at the content root is unaffected either way - the regex requires a
- *  preceding `/`, which a bare "index" doesn't have (matching Astro's
- *  own behavior: a root-level index.mdx keeps file id "index", not "").
- *
- *  Full per-segment slugification (github-slugger, applied by Astro to
- *  every path segment) is deliberately *not* replicated here - every
- *  filename in this codebase's own fixtures and every filename this
- *  function needs to have handled correctly is already slug-safe
- *  (lowercase, hyphenated, no spaces/unicode), so slugification is
- *  always a no-op in practice; only the `/index`-stripping behavior is
- *  reproduced, since that's the one part of Astro's algorithm this
- *  change newly exercises (a file that used to be a collection's own
- *  base-root index, exempt from stripping, and is now nested one level
- *  deeper).
- *
- *  Entries from the `generatedDocs` collection (auto-generated OpenAPI
- *  stub pages - see content.config.ts / generate-api-pages.js) live
- *  under writedocsTempDir()'s generated-docs/ directory - an OS temp
- *  directory location entirely outside contentDir, not a subdirectory
- *  of it - so `relativeToContentDir` for one of these always starts with
- *  `..` (walking back out of contentDir to reach it), and the check
- *  right below falls back to `entry.id` instead of computing a
- *  nonsensical id relative to a directory the file was never actually
- *  under. Those entries always set their own `slug` frontmatter
- *  explicitly, so there's no independent "file path" identity worth
- *  recovering for them the way there is for a hand-written page that
- *  might move around - `entry.id` (Astro's already-resolved slug)
- *  already IS the exact value generate-api-pages.js's own manifest
- *  references them by. */
-export function fileIdForEntry(
-  contentDir: string,
-  packageRoot: string,
-  entry: DocsEntryLike
-): string {
-  if (!entry.filePath) return entry.id;
-  const absoluteContentDir = path.resolve(contentDir);
-  const absoluteFilePath = path.resolve(packageRoot, entry.filePath);
-  const relativeToContentDir = path.relative(absoluteContentDir, absoluteFilePath);
-  if (relativeToContentDir.startsWith('..')) return entry.id;
-  const posixRelative = relativeToContentDir.split(path.sep).join('/');
-  if (EXCLUDED_TOP_LEVEL_DIRS.has(posixRelative.split('/')[0])) return entry.id;
-  return posixRelative.replace(/\.mdx?$/i, '').replace(/\/index$/, '');
-}
-
-/** Normalizes a raw `entry.id` into the bare, slash-free form every
- *  route/href in this codebase assumes. Once a page sets a frontmatter
- *  `slug`, `entry.id` becomes that value completely verbatim - Astro's
- *  glob loader applies no normalization of its own (see
- *  generateIdDefault in astro/dist/content/loaders/glob.js) - so
- *  `slug: /` or `slug: /guides/new-name` (both natural things to write,
- *  mirroring how every href elsewhere in writedocs.json already has a
- *  leading slash) would otherwise produce broken multi-slash hrefs
- *  wherever hrefForSlug wraps the value in its own `/${slug}/`, and a
- *  bare "/" would additionally fail to be recognized as claiming root,
- *  colliding with the synthetic root-redirect route. */
-export function normalizeEntryId(id: string): string {
-  const trimmed = id.replace(/^\/+/, '').replace(/\/+$/, '');
-  return trimmed === '' ? 'index' : trimmed;
-}
-
-export interface FlatNavEntry {
-  slug: string;
-  group: string | null;
-}
-
-export function flattenNav(navigation: NavItem[], group: string | null = null): FlatNavEntry[] {
-  return navigation.flatMap((item): FlatNavEntry[] => {
-    if (typeof item === 'string') {
-      return [{ slug: item, group }];
-    }
-    if ('href' in item) return []; // external link leaf, not a content page - no route/prev-next entry
-    // loadDocsConfig() always expands `{ group, openapi }` shorthand into
-    // a real `{ group, pages }` before anything reaches here (see
-    // expandOpenApiInNavigation() above) - this is just a defensive
-    // no-op for the shouldn't-happen case of an unexpanded node.
-    if ('openapi' in item) return [];
-    const ownPage: FlatNavEntry[] = item.page ? [{ slug: item.page, group: item.group }] : [];
-    return [...ownPage, ...flattenNav(item.pages, item.group)];
-  });
-}
-
-// --- Sections -------------------------------------------------------
-//
-// A Section is the atomic unit that owns one page tree and therefore one
-// sidebar - every real content page belongs to exactly one Section,
-// whichever `pages` leaf it's listed under, however deep in the
-// tabs/versions/languages/dropdowns/products tree that leaf lives.
-//
-// A Section's `path` records the full chain of containers from the
-// navigation root down to it, one PathSegment per level. This is
-// everything the topbar needs to render the right selector controls
-// (tabs bar, version dropdown, ...) and highlight the right option in
-// each - without the router or layout needing to know how deep or in
-// what order the site author nested things.
-
-export type PathSegment =
-  | { kind: 'tab'; items: TabItem[]; index: number }
-  | { kind: 'version'; items: VersionItem[]; index: number }
-  | { kind: 'language'; items: LanguageItem[]; index: number }
-  | { kind: 'dropdown'; items: DropdownItem[]; index: number }
-  | { kind: 'product'; items: ProductItem[]; index: number };
-
-export interface Section {
-  pages: NavItem[];
-  path: PathSegment[];
-}
-
-type Container = NavChildren;
-type NamedContainer = TabItem | VersionItem | LanguageItem | DropdownItem | ProductItem;
-
-function walkSections(node: Container, path: PathSegment[], out: Section[]): void {
-  if ('pages' in node) {
-    out.push({ pages: node.pages, path });
-    return;
-  }
-  if ('href' in node) return; // external link, not a Section
-  if ('tabs' in node) {
-    node.tabs.forEach((item, index) =>
-      walkSections(item, [...path, { kind: 'tab', items: node.tabs, index }], out)
-    );
-    return;
-  }
-  if ('versions' in node) {
-    node.versions.forEach((item, index) =>
-      walkSections(item, [...path, { kind: 'version', items: node.versions, index }], out)
-    );
-    return;
-  }
-  if ('languages' in node) {
-    node.languages.forEach((item, index) =>
-      walkSections(item, [...path, { kind: 'language', items: node.languages, index }], out)
-    );
-    return;
-  }
-  if ('dropdowns' in node) {
-    node.dropdowns.forEach((item, index) =>
-      walkSections(item, [...path, { kind: 'dropdown', items: node.dropdowns, index }], out)
-    );
-    return;
-  }
-  if ('products' in node) {
-    node.products.forEach((item, index) =>
-      walkSections(item, [...path, { kind: 'product', items: node.products, index }], out)
-    );
-    return;
-  }
-}
-
-export function resolveSections(navigation: NavigationConfig): Section[] {
-  if (Array.isArray(navigation)) return [{ pages: navigation, path: [] }];
-  const sections: Section[] = [];
-  walkSections(navigation as Container, [], sections);
-  // global.dropdowns sits outside the primary pattern, but its pages
-  // still need routes generated for them - walk each entry too, with an
-  // empty path (they don't participate in the tabs/version/etc.
-  // selector chain, only in the always-visible globalDropdowns list).
-  for (const dropdown of navigation.global?.dropdowns ?? []) {
-    walkSections(dropdown, [], sections);
-  }
-  return sections;
-}
-
-/** Which Section (by index into resolveSections()'s result) a page belongs to. */
-export function findSectionIndexForSlug(sections: Section[], slug: string): number {
-  const index = sections.findIndex((s) => flattenNav(s.pages).some((entry) => entry.slug === slug));
-  return index === -1 ? 0 : index;
-}
-
-/** The always-visible topbar dropdown list - independent of whichever
- *  primary pattern/section is active (Mintlify's equivalent is
- *  `navigation.global.anchors`). */
-export function resolveGlobalDropdowns(navigation: NavigationConfig): DropdownItem[] {
-  if (Array.isArray(navigation)) return [];
-  return navigation.global?.dropdowns ?? [];
-}
-
-/** The first real page slug reachable by descending into a container's
- *  content, however deep - used to compute where a selector option (a
- *  tab, a version, ...) navigates to when chosen. Null for an external
- *  `href` leaf, which the caller renders as a plain link using the
- *  node's own href instead. Versions prefer whichever entry is marked
- *  `default` (falling back to the first), matching Mintlify's version
- *  default rule. */
-/** Tries `firstSlugOf()` against each item in order, returning the first
- *  non-null result - a plain `items[0]` pick (the previous behavior)
- *  breaks the moment that first sibling happens to be a bare `href` leaf
- *  (returns null, with nothing that tries the next one), which is a real
- *  case now that any container - not just a nested dropdown - can be a
- *  bare external link (e.g. a `tabs` array whose first entry is
- *  `{ tab: "Status", href: "..." }`). */
-function firstSlugAmong(items: Container[]): string | null {
-  for (const item of items) {
-    const slug = firstSlugOf(item);
-    if (slug !== null) return slug;
-  }
-  return null;
-}
-
-export function firstSlugOf(node: Container): string | null {
-  if ('pages' in node) return flattenNav(node.pages)[0]?.slug ?? null;
-  if ('href' in node) return null;
-  if ('tabs' in node) return firstSlugAmong(node.tabs);
-  if ('versions' in node) {
-    // Try the `default`-tagged version(s) first (matching the old
-    // "preferred" pick), then fall through to the rest in order - same
-    // href-leaf-with-no-fallback concern as `tabs` above, just with an
-    // extra preference pass in front of it.
-    const defaults = node.versions.filter((v) => v.default);
-    const rest = node.versions.filter((v) => !v.default);
-    return firstSlugAmong([...defaults, ...rest]);
-  }
-  if ('languages' in node) return firstSlugAmong(node.languages);
-  if ('dropdowns' in node) return firstSlugAmong(node.dropdowns);
-  if ('products' in node) return firstSlugAmong(node.products);
-  return null;
-}
-
-/** For a version/language switcher, finds where the reader's current
- *  page would live inside a *different* version/language's own subtree,
- *  so switching keeps them on the same conceptual page instead of always
- *  bouncing to that option's first page (see buildSelectors() below,
- *  which is the only caller). "Same page" is approximated positionally
- *  rather than by name, since nothing guarantees a version/language's
- *  own identifier lines up with its pages' file paths - a version
- *  tagged "2025-09" could just as easily keep its pages under a "v1"
- *  folder with no relation to that string, so there's no naming
- *  convention to key off safely; this heuristic only ever compares tree
- *  position, never path text. (docs.json-examples/00-kitchen-sink/'s own
- *  versions - "2025-09"/"2026-01" under Core Platform - happen to have
- *  folder names that line up with their version strings, so it doesn't
- *  demonstrate the mismatched-folder-name case directly; the guarantee
- *  still doesn't exist regardless of what one fixture happens to do.)
- *
- *  Two things have to line up for a page to count as "the same" one:
- *  first, `remainingPath` (whatever tab/product/dropdown was chosen
- *  *below* the version/language being switched, on the reader's actual
- *  page) has to exist at the same index in `item`'s own subtree too -
- *  an option isn't guaranteed to nest the same way that many levels
- *  down (a version could add/remove a tab), so any mismatch here bails
- *  out to null immediately rather than guessing. Second, once both
- *  bottom out at a leaf `pages` list, `position` (the reader's own page
- *  index within *its* pages list) has to exist in `item`'s pages list
- *  too - two versions/languages of the same docs are usually authored
- *  with matching page order even when the file paths differ, so this
- *  is a reasonable proxy for "the same page" without relying on names.
- *
- *  Returns null - meaning "no equivalent page, fall back to
- *  firstSlugOf()" - on any structural mismatch or an out-of-range
- *  position, rather than guessing at a wrong page. */
-export function equivalentPageIn(
-  item: Container,
-  remainingPath: PathSegment[],
-  position: number
-): string | null {
-  if ('pages' in item) return flattenNav(item.pages)[position]?.slug ?? null;
-  if ('href' in item) return null;
-  const [next, ...rest] = remainingPath;
-  if (!next) return null; // the reader's own page didn't go this deep - no basis to pick a branch
-  if ('tabs' in item && next.kind === 'tab') {
-    const target = item.tabs[next.index];
-    return target ? equivalentPageIn(target, rest, position) : null;
-  }
-  if ('versions' in item && next.kind === 'version') {
-    const target = item.versions[next.index];
-    return target ? equivalentPageIn(target, rest, position) : null;
-  }
-  if ('languages' in item && next.kind === 'language') {
-    const target = item.languages[next.index];
-    return target ? equivalentPageIn(target, rest, position) : null;
-  }
-  if ('dropdowns' in item && next.kind === 'dropdown') {
-    const target = item.dropdowns[next.index];
-    return target ? equivalentPageIn(target, rest, position) : null;
-  }
-  if ('products' in item && next.kind === 'product') {
-    const target = item.products[next.index];
-    return target ? equivalentPageIn(target, rest, position) : null;
-  }
-  return null; // structural mismatch - this option nests differently at this depth
-}
-
-/** The first real page slug in the whole site, root navigation pattern
- *  included - used to redirect `/` somewhere sensible when nothing in
- *  the navigation happens to be a page literally named "index" (the
- *  usual "docs/index.mdx is the homepage" convention). Mirrors
- *  firstSlugOf()'s per-container descent, plus the flat-array root case
- *  firstSlugOf() alone can't handle since a bare array isn't a Container. */
-export function firstSlugOfNavigation(navigation: NavigationConfig): string | null {
-  if (Array.isArray(navigation)) return flattenNav(navigation)[0]?.slug ?? null;
-  return firstSlugOf(navigation as Container);
-}
-
-/** Whether `slug` is reachable anywhere underneath a container, however
- *  deep - used for computing active state on nodes that aren't part of
- *  the active Section's own `path` (global dropdown entries). */
-export function containerContainsSlug(node: Container, slug: string): boolean {
-  if ('pages' in node) return flattenNav(node.pages).some((entry) => entry.slug === slug);
-  if ('href' in node) return false;
-  if ('tabs' in node) return node.tabs.some((t) => containerContainsSlug(t, slug));
-  if ('versions' in node) return node.versions.some((v) => containerContainsSlug(v, slug));
-  if ('languages' in node) return node.languages.some((l) => containerContainsSlug(l, slug));
-  if ('dropdowns' in node) return node.dropdowns.some((d) => containerContainsSlug(d, slug));
-  if ('products' in node) return node.products.some((p) => containerContainsSlug(p, slug));
-  return false;
-}
-
-function labelOf(item: NamedContainer): string {
-  if ('tab' in item) return item.tab;
-  if ('version' in item) return item.label ?? item.version;
-  if ('language' in item) return item.label ?? item.language;
-  if ('dropdown' in item) return item.dropdown;
-  return item.product;
-}
-
-function iconOf(item: NamedContainer): string | undefined {
-  return (item as { icon?: string }).icon;
-}
-
-// --- Topbar selectors -------------------------------------------------
-//
-// One Selector per PathSegment on the active Section's path. Tabs render
-// as the horizontal pill bar (all options always visible, exactly one
-// current); versions/languages/products, and dropdowns used as a nested
-// path segment, render as a single switcher control instead - the
-// trigger shows the *current* option, its menu lists the alternatives.
-// See BaseLayout.astro for the actual markup per kind.
-
-export interface SelectorOption {
-  label: string;
-  icon?: string;
-  tag?: string;
-  href: string;
-  active: boolean;
-  // Set when this option's own container is a `dropdowns` list (e.g. a
-  // tab whose content is `dropdowns` instead of `pages`) - the tab pill
-  // itself becomes a dropdown-trigger showing these as its menu, rather
-  // than a separate dropdown control rendered alongside it. Only ever
-  // populated one level deep (a dropdown option doesn't itself get a
-  // nested `dropdown` - matches the one level of "a tab/dropdown owns a
-  // dropdowns list" this is meant to cover).
-  dropdown?: SelectorOption[];
-}
-
-export interface Selector {
-  kind: PathSegment['kind'];
-  options: SelectorOption[];
-}
-
-/** An option's own `dropdowns` menu, if it has one (see SelectorOption.dropdown
- *  above) - `activeSegment` is the *next* PathSegment after this option's own
- *  segment, only passed when this option is the active one on its level, so a
- *  sibling option that also happens to own `dropdowns` doesn't spuriously mark
- *  one of its entries active just because some *other* option is currently
- *  selected. */
-function dropdownMenuOf(
-  node: NavChildren,
-  hrefForSlug: (slug: string) => string,
-  activeSegment: PathSegment | undefined
-): SelectorOption[] | undefined {
-  if (!('dropdowns' in node)) return undefined;
-  return node.dropdowns.map((d, i) => ({
-    label: d.dropdown,
-    icon: iconOf(d),
-    href: 'href' in d ? d.href : hrefForSlug(firstSlugOf(d) ?? 'index'),
-    active: activeSegment?.kind === 'dropdown' && activeSegment.index === i,
-  }));
-}
-
-/** `activePagePosition` is the reader's current page's own index within
- *  its Section's flattened pages list (-1 if it can't be found there,
- *  which just disables the position-preserving behavior below) - see
- *  [...slug].astro for how it's computed. Only version/language
- *  switchers try to preserve position across options; tabs/dropdowns/
- *  products keep linking to firstSlugOf() unconditionally, since those
- *  represent genuinely different content (an "API Reference" tab isn't
- *  "the same page" as a "Guides" tab just because they're both first),
- *  unlike a version/language of what's meant to be the same docs. */
-export function buildSelectors(
-  path: PathSegment[],
-  hrefForSlug: (slug: string) => string,
-  activePagePosition: number = -1
-): Selector[] {
-  return path.map((segment, segIndex): Selector => {
-    const preservesPosition =
-      (segment.kind === 'version' || segment.kind === 'language') && activePagePosition >= 0;
-    const remainingPath = path.slice(segIndex + 1);
-    return {
-      kind: segment.kind,
-      options: (segment.items as NamedContainer[]).map((item, i) => {
-        const isActive = i === segment.index;
-        const equivalentSlug = preservesPosition
-          ? equivalentPageIn(item as Container, remainingPath, activePagePosition)
-          : null;
-        const targetSlug = equivalentSlug ?? firstSlugOf(item as Container) ?? 'index';
-        return {
-          label: labelOf(item),
-          icon: iconOf(item),
-          tag: 'tag' in item ? item.tag : undefined,
-          href: 'href' in item ? item.href : hrefForSlug(targetSlug),
-          active: isActive,
-          dropdown: dropdownMenuOf(item, hrefForSlug, isActive ? path[segIndex + 1] : undefined),
-        };
-      }),
-    };
-  });
-}
-
-// --- Global dropdowns ---------------------------------------------------
-//
-// Unlike path-segment selectors, global dropdowns aren't a mutually
-// exclusive "pick one" choice - `global.dropdowns` is an array where
-// *every* entry renders as its own always-visible trigger button
-// simultaneously (Mintlify's anchors work the same way). A trigger's
-// menu lists its own direct pages as quick links; a bare-href entry is
-// just a plain link with no menu; a deeply-nested entry (tabs/versions/
-// etc. instead of direct pages) falls back to linking straight to its
-// first page, since building a rich flyout for that combination isn't
-// worth the complexity for what's meant to be a quick-links affordance.
-
-export interface GlobalDropdownView {
-  label: string;
-  icon?: string;
-  href: string | null;
-  items: SelectorOption[];
-}
-
-export function buildGlobalDropdowns(
-  dropdowns: DropdownItem[],
-  currentSlug: string,
-  titleForSlug: (slug: string) => string,
-  hrefForSlug: (slug: string) => string
-): GlobalDropdownView[] {
-  return dropdowns.map((d): GlobalDropdownView => {
-    if ('href' in d) {
-      return { label: d.dropdown, icon: d.icon, href: d.href, items: [] };
-    }
-    if ('pages' in d) {
-      const items = flattenNav(d.pages).map((entry) => ({
-        label: titleForSlug(entry.slug),
-        href: hrefForSlug(entry.slug),
-        active: entry.slug === currentSlug,
-      }));
-      return { label: d.dropdown, icon: d.icon, href: null, items };
-    }
-    const slug = firstSlugOf(d);
-    return { label: d.dropdown, icon: d.icon, href: slug ? hrefForSlug(slug) : '#', items: [] };
-  });
-}
-
-// --- Sidebar (recursive) -------------------------------------------------
-
-// A group node's `pageSlug` is the page its own label links to (null if
-// it's a pure disclosure/label with no page of its own - the group only
-// groups). NavTree.astro renders depth-0 groups as static, non-collapsible
-// section titles (linked if `pageSlug` is set, plain text otherwise) and
-// every deeper group as a collapsible row styled like a page item, with a
-// chevron, defaulting open when it contains the active page - see
-// navTreeContainsSlug() below.
-export type NavTreeNode =
-  | { kind: 'page'; slug: string; title: string; method: string | null }
-  | { kind: 'group'; label: string; pageSlug: string | null; children: NavTreeNode[] }
-  | { kind: 'link'; label: string; href: string };
-
-/** Builds the sidebar's view model, preserving group nesting depth.
- *  `methodForSlug` is optional (most sites have no OpenAPI pages at all)
- *  and, when given, returns the HTTP method to badge a page with in the
- *  sidebar (e.g. "GET") or null for an ordinary page - see
- *  NavTree.astro for how that badge renders. */
-export function buildNavTree(
-  navigation: NavItem[],
-  titleForSlug: (slug: string) => string,
-  methodForSlug?: (slug: string) => string | null
-): NavTreeNode[] {
-  return navigation.map((item): NavTreeNode => {
-    if (typeof item === 'string') {
-      return {
-        kind: 'page',
-        slug: item,
-        title: titleForSlug(item),
-        method: methodForSlug?.(item) ?? null,
-      };
-    }
-    if ('href' in item) {
-      return { kind: 'link', label: item.label, href: item.href };
-    }
-    // loadDocsConfig() always expands `{ group, openapi }` shorthand into
-    // a real `{ group, pages }` before anything reaches here (see
-    // expandOpenApiInNavigation() in the OpenAPI section above) - this is
-    // just a defensive no-op for the shouldn't-happen case of an
-    // unexpanded node reaching the sidebar builder.
-    if ('openapi' in item) {
-      return { kind: 'group', label: item.group, pageSlug: null, children: [] };
-    }
-    return {
-      kind: 'group',
-      label: item.group,
-      pageSlug: item.page ?? null,
-      children: buildNavTree(item.pages, titleForSlug, methodForSlug),
-    };
-  });
-}
-
-/** Whether `slug` is the group's own attached page, or belongs to any page/group nested inside it. */
-export function navTreeContainsSlug(nodes: NavTreeNode[], slug: string): boolean {
-  return nodes.some((node) => {
-    if (node.kind === 'page') return node.slug === slug;
-    if (node.kind === 'link') return false;
-    return node.pageSlug === slug || navTreeContainsSlug(node.children, slug);
-  });
-}
-
-export interface BreadcrumbCrumb {
-  label: string;
-  href: string | null;
-}
-
-/** The chain of ancestor group labels (root first) that `slug` is nested
- *  under within `nodes` - empty when the page sits at the top level of its
- *  Section with no enclosing group at all, in which case the caller should
- *  skip rendering breadcrumbs entirely (there'd be nothing to show but the
- *  fixed home icon Breadcrumbs.astro always renders first).
- *
- *  Deliberately never includes the current page itself - only the groups
- *  it's nested under (that's already the <h1> right below, repeating it
- *  in the breadcrumb trail would just be noise). A group whose own
- *  attached page (`pageSlug`, see NavTreeNode) *is* `slug` is excluded
- *  from its own trail for the same reason - you're looking at that page,
- *  it doesn't need to also list itself as its own ancestor. A group only
- *  appears here when `slug` is nested *inside* it (its own page, if any,
- *  links to that group's landing page - `href: null` for a label-only
- *  group with no page of its own to link to). */
-export function ancestorGroupsForSlug(
-  nodes: NavTreeNode[],
-  slug: string,
-  hrefForSlug: (slug: string) => string
-): BreadcrumbCrumb[] {
-  for (const node of nodes) {
-    if (node.kind !== 'group') continue;
-    if (node.pageSlug === slug) return [];
-    if (navTreeContainsSlug(node.children, slug)) {
-      const crumb: BreadcrumbCrumb = { label: node.label, href: node.pageSlug ? hrefForSlug(node.pageSlug) : null };
-      return [crumb, ...ancestorGroupsForSlug(node.children, slug, hrefForSlug)];
-    }
-  }
-  return [];
-}
+import fs from 'node:fs';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import matter from 'gray-matter';
+import { writedocsTempDir } from './writedocs-temp-dir.js';
+import {
+  formatValidationIssues,
+  validateDocsConfig,
+  type DocsConfig,
+  type DropdownItem,
+  type FontVariant,
+  type LanguageItem,
+  type NavChildren,
+  type NavItem,
+  type NavigationConfig,
+  type ProductItem,
+  type TabItem,
+  type VersionItem,
+} from './config-schema.ts';
+
+// O schema do writedocs.json mora em ./config-schema.ts desde a extracao (E11):
+// aquele modulo importa so `zod`, sem nada de node:fs, pra que a plataforma
+// possa importa-lo por `@writedocs/generator/config-schema`. Este reexport
+// mantem a superficie deste arquivo exatamente como era - quem importa
+// `docsConfigSchema`, `DocsConfig`, `seoFieldsSchema`, `mergeSeo` etc. de
+// './config.js' continua importando do mesmo lugar, sem mudar uma linha.
+//
+// `.ts` e nao o `./config-schema.js` gerado, de proposito - e a unica coisa no
+// repositorio que ainda aponta pra fonte, e o bin/ e o `exports` apontam pro
+// `.js`. O motivo e que este reexport carrega 24 `export type`/`interface`
+// (DocsConfig, NavItem, Selector, GlobalDropdownView, ContextMenuConfig...) que
+// uma duzia de .astro consome como `import type { X } from '../lib/config'`, e
+// o esbuild apaga todos eles: o `.js` gerado exporta exatamente 5 simbolos de
+// runtime. Este repositorio nao tem tsconfig.json nem o typescript instalado,
+// entao (a) nada configura o mapeamento `.js` -> `.ts` que faria os tipos
+// voltarem e (b) nao existe typecheck que reclamasse - a troca so apagaria os
+// tipos em silencio. Aqui tudo passa pelo transform do Astro/Vite, que le `.ts`
+// nativamente, entao o `.js` nao resolve problema nenhum deste lado.
+//
+// O custo aceito e que o tarball leva as duas copias e um build do Astro pode
+// carregar as duas (o `.ts` por aqui, o `.js` por quem importa o subpath) - duas
+// instancias do schema, inofensivas porque nada compara identidade de schema.
+export * from './config-schema.ts';
+
+/** Normalizes writedocs.json's `domain` into a full origin with no trailing
+ *  slash (e.g. "docs.example.com" -> "https://docs.example.com"), or null
+ *  if the site hasn't set one. The single source of truth for "does this
+ *  site have a real deployed URL" - astro.config.mjs (sitemap
+ *  registration), BaseLayout.astro (canonical/OG/Twitter URLs), and
+ *  resolveAbsoluteUrl() below all call this rather than reading
+ *  config.domain directly, so the http(s):// normalization only happens
+ *  in one place. */
+export function resolveSiteUrl(config: Pick<DocsConfig, 'domain'>): string | null {
+  if (!config.domain) return null;
+  const withScheme = /^https?:\/\//i.test(config.domain) ? config.domain : `https://${config.domain}`;
+  return withScheme.replace(/\/+$/, '');
+}
+
+/** Resolves a possibly-relative asset path (e.g. `seo.ogImage: "/card.png"`)
+ *  against the site's own domain into an absolute URL - social crawlers
+ *  (Facebook/Twitter/Slack unfurls) generally require an absolute
+ *  og:image/twitter:image URL, a same-origin relative path isn't reliably
+ *  respected. Returns the value unchanged if it's already absolute, or if
+ *  there's no siteUrl to resolve it against (a relative path is still
+ *  better than nothing in that case - most social crawlers do at least
+ *  attempt to fetch it relative to the page they scraped). */
+export function resolveAbsoluteUrl(siteUrl: string | null, value: string): string {
+  if (/^https?:\/\//i.test(value)) return value;
+  if (!siteUrl) return value;
+  return `${siteUrl}${value.startsWith('/') ? '' : '/'}${value}`;
+}
+
+/** The resolved (never-undefined) Shiki theme names for light/dark code
+ *  blocks - shared by astro.config.mjs (sitewide MDX code-fence
+ *  highlighting) and ApiReferencePanel.astro (the API playground's own
+ *  separate <Code/> usages, which don't inherit markdown.shikiConfig at
+ *  all - see astro.config.mjs's own comment on that) so both read the
+ *  same writedocs.json field and fall back to the same defaults instead of
+ *  each hardcoding its own copy. */
+export function resolveCodeblockTheme(config: DocsConfig): { light: string; dark: string } {
+  return {
+    light: config.styles.codeblocks?.light ?? 'github-light',
+    dark: config.styles.codeblocks?.dark ?? 'github-dark',
+  };
+}
+
+// mdx is a real, bundled Shiki grammar (@shikijs/langs' mdx.mjs - it does
+// exist, this isn't a "Shiki doesn't know this language" situation), but in
+// practice it tokenizes ```mdx fences into one single run per line with no
+// internal token boundaries at all - every character, JSX tag or not,
+// lands in the exact same TextMate scope and renders in the theme's plain
+// foreground color. Confirmed directly against real built output: every
+// span in a ```mdx block's compiled HTML carries the identical inline
+// color, none of the tag/attribute/string distinction a JS or JSX fence
+// gets. Aliasing to jsx - a close structural match for the JSX-heavy
+// snippets these fences are actually used for in this codebase's own docs
+// (`<Callout>`, `<Card>`, etc.) - actually highlights the tags/attributes,
+// at the cost of not distinctly coloring the markdown-prose portions
+// interleaved between them (jsx's grammar doesn't know about those) - a
+// worthwhile trade given the alternative is no color at all. See
+// astro.config.mjs's own shikiConfig.langAlias for where this actually
+// gets used. */
+const DEFAULT_CODEBLOCK_LANG_ALIAS: Record<string, string> = { mdx: 'jsx' };
+
+/** The resolved fence-language alias map - the built-in mdx -> jsx default
+ *  above, merged with (not replaced by) whatever a site adds under its own
+ *  writedocs.json styles.codeblocks.langAlias, so a site can extend this list
+ *  without having to redeclare the built-in entry to keep it. Same
+ *  "shared resolver, not each consumer re-deriving its own defaults"
+ *  pattern resolveCodeblockTheme() right above already establishes -
+ *  though today only astro.config.mjs actually consumes this one, unlike
+ *  that one, since ApiReferencePanel.astro's own <Code/> usages never
+ *  render a `mdx`-tagged snippet (API operation samples are curl/js/
+ *  python/etc., not MDX markup) to begin with. */
+export function resolveCodeblockLangAlias(config: DocsConfig): Record<string, string> {
+  return { ...DEFAULT_CODEBLOCK_LANG_ALIAS, ...config.styles.codeblocks?.langAlias };
+}
+
+const DEFAULT_FONT_FAMILY = 'Inter';
+
+export interface ResolvedFonts {
+  base: FontVariant;
+  heading: FontVariant | null;
+  body: FontVariant | null;
+}
+
+/** Resolves writedocs.json's `styles.fonts` into the three font declarations
+ *  BaseLayout.astro actually needs to render: `base` (the site-wide
+ *  default - every element gets this unless `heading`/`body` narrows it
+ *  further), and `heading`/`body`, each `null` when not independently
+ *  configured (letting BaseLayout fall back to `base` for whichever side
+ *  wasn't overridden, rather than this function silently copying `base`
+ *  into both and losing the distinction between "explicitly set to the
+ *  same font" and "just inheriting the default"). The one hardcoded
+ *  default in this whole feature lives right here: no `styles.fonts` at
+ *  all resolves to plain Inter, loaded for real (a Google Fonts `<link>`,
+ *  not just a name in a fallback stack that only renders correctly for a
+ *  reader who happens to already have Inter installed - see base.css's
+ *  old `font-family` rule, which was exactly that, before this feature
+ *  existed). */
+export function resolveFonts(config: DocsConfig): ResolvedFonts {
+  const fonts = config.styles.fonts;
+  const base: FontVariant = fonts
+    ? { family: fonts.family, weight: fonts.weight, source: fonts.source, format: fonts.format }
+    : { family: DEFAULT_FONT_FAMILY };
+  return { base, heading: fonts?.heading ?? null, body: fonts?.body ?? null };
+}
+
+/** The Google Fonts CSS2 API URL for every font in `fonts` that isn't a
+ *  `source`-based (local/externally-hosted) font - `null` if there's
+ *  nothing to load this way at all (every configured font has its own
+ *  `source`). One request covers every family needed (`&family=` repeated
+ *  per unique family+weight pair, deduped so the same pair - e.g. `base`
+ *  and `body` both left at the site default - isn't requested twice)
+ *  rather than a separate `<link>` per font. `display=swap` avoids an
+ *  invisible-text flash while the font file loads (renders in the
+ *  fallback stack immediately, swaps once the real font is ready) -
+ *  Google's own recommended default for exactly this use case. */
+export function googleFontsHref(fonts: ResolvedFonts): string | null {
+  const entries = [fonts.base, fonts.heading, fonts.body].filter(
+    (f): f is FontVariant => f !== null && !f.source
+  );
+  if (entries.length === 0) return null;
+  const seen = new Set<string>();
+  const params: string[] = [];
+  for (const f of entries) {
+    const key = `${f.family}|${f.weight ?? ''}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    const familyParam = f.family.trim().replace(/\s+/g, '+');
+    params.push(f.weight ? `family=${familyParam}:wght@${f.weight}` : `family=${familyParam}`);
+  }
+  return `https://fonts.googleapis.com/css2?${params.join('&')}&display=swap`;
+}
+
+/** A `@font-face` rule for one `source`-based font (local project path or
+ *  externally-hosted URL), or `''` for a Google Font (no `source` - see
+ *  googleFontsHref() above, the other half of font loading). `weight`
+ *  becomes the rule's `font-weight` *descriptor* here - it tells the
+ *  browser which weight this specific file represents, so a `font-weight`
+ *  CSS value requested elsewhere (BaseLayout.astro's own
+ *  `wdFontWeightHeading`/`wdFontWeightBody`, see its comment) picks the
+ *  real matching file instead of synthetically ("faux") bolding/
+ *  thinning a mismatched one. This function only ever produces the
+ *  `@font-face` rule itself - actually applying `font-weight` to any
+ *  element (h1-h6, body) is BaseLayout's job, not this one's. */
+export function fontFaceRule(font: FontVariant | null): string {
+  if (!font || !font.source) return '';
+  const weightDecl = font.weight !== undefined ? ` font-weight: ${font.weight};` : '';
+  return `@font-face { font-family: '${font.family}'; src: url('${font.source}') format('${font.format ?? 'woff2'}'); font-display: swap;${weightDecl} }`;
+}
+
+/** Splits one side of `styles.navbar` (the string-or-object union
+ *  navbarColorValueSchema allows) into its two parts, filling in the
+ *  fallback background when the field is unset at all. `accent` stays
+ *  `undefined` - not defaulted here - for both the bare-string case and
+ *  the object case where a site set `background` without `accent`;
+ *  BaseLayout.astro is what turns that `undefined` into "fall back to
+ *  --wd-primary" for the accent CSS var. There's no `foreground` here at
+ *  all to resolve - the navbar's text/icon color is never read from
+ *  writedocs.json, see `navbar`'s own schema comment (stylesSchema) for why. */
+export function resolveNavbarColor(
+  value: string | { background: string; accent?: string } | undefined,
+  fallbackBackground: string
+): { background: string; accent: string | undefined } {
+  if (!value) return { background: fallbackBackground, accent: undefined };
+  if (typeof value === 'string') return { background: value, accent: undefined };
+  return { background: value.background, accent: value.accent };
+}
+
+/** Picks black or white text for readable contrast against `hexColor`,
+ *  via the standard relative-luminance formula (ITU-R BT.601 weights -
+ *  the same "perceived brightness" approximation used all over the web
+ *  for exactly this "what text color goes on this swatch" problem, not
+ *  the more expensive WCAG relative-luminance formula, which isn't
+ *  needed for a binary choose-the-less-bad-option decision like this
+ *  one). Used two ways in BaseLayout.astro: for `--wd-navbar-accent-text`
+ *  (the active tab's own fill used to always be `var(--wd-primary)` with
+ *  hardcoded `color: #fff`, which only actually read fine because every
+ *  default/example primary color so far has been dark/saturated enough
+ *  for white text; once a site's navbar accent can be *any* color -
+ *  `styles.navbar.light.accent`, falling back to `styles.colors.primary`
+ *  when unset, see resolveNavbarColor() above - that assumption can't
+ *  hold unconditionally), and for `--wd-navbar-foreground` itself once
+ *  `styles.navbar` is configured at all (the navbar's plain text/icon
+ *  color - see `navbar`'s own schema comment for why that's always
+ *  computed, never a writedocs.json value). Malformed input (not a 6-digit
+ *  `#rrggbb` hex) falls back to white rather than throwing - same "don't
+ *  fail a build over a cosmetic color value" posture every other color
+ *  field here takes (none of them validate hex syntax either). */
+export function contrastTextColor(hexColor: string): '#000000' | '#ffffff' {
+  const match = /^#?([0-9a-f]{6})$/i.exec(hexColor.trim());
+  if (!match) return '#ffffff';
+  const hex = match[1];
+  const r = parseInt(hex.slice(0, 2), 16);
+  const g = parseInt(hex.slice(2, 4), 16);
+  const b = parseInt(hex.slice(4, 6), 16);
+  const luminance = (299 * r + 587 * g + 114 * b) / 1000;
+  return luminance > 150 ? '#000000' : '#ffffff';
+}
+
+/** Whether an href points off-site - has an explicit scheme (`https:`,
+ *  `mailto:`, `tel:`, ...) or is protocol-relative (`//...`) - versus a
+ *  same-site path, which this codebase always produces as a single
+ *  leading slash (hrefForSlug() in [...slug].astro). Used everywhere a
+ *  nav link is rendered to decide whether it should open in a new tab;
+ *  deliberately a plain string check rather than a schema-level flag,
+ *  so it applies uniformly to every href source (topbar.links, a
+ *  switcher/tab pill pointing at a bare `href` container, a global
+ *  dropdown's own link, a sidebar link leaf) without threading an
+ *  `external` field through every one of those call sites. */
+export function isExternalHref(href: string): boolean {
+  return /^[a-z][a-z0-9+.-]*:/i.test(href) || href.startsWith('//');
+}
+
+// ---------------------------------------------------------------------
+// Icons - writedocs.json's `icon` fields (TabItem, DropdownItem, ProductItem,
+// Card) are plain strings with no schema-level distinction between "an
+// emoji, paste it verbatim" and "an icon-set name, look it up". Resolved
+// here rather than validated in the schema, since both are valid uses of
+// the same string field and the right rendering only becomes obvious once
+// you look at the value's shape.
+// ---------------------------------------------------------------------
+
+export type IconResolution =
+  | { kind: 'iconify'; name: string } // ready for astro-icon/components' <Icon name=... />
+  | { kind: 'image'; src: string } // an image URL or site path, rendered as <img>
+  | { kind: 'text'; value: string }; // literal text/emoji, rendered as-is
+
+const DEFAULT_ICON_COLLECTION = 'lucide';
+
+// Where a bare icon name is looked up, in order. Lucide stays first so no
+// existing site's icons change; Font Awesome comes after because it's
+// Mintlify's default library - Mintlify content writes `icon="gear"` or
+// `icon="discord"`, names Lucide doesn't have, and astro-icon fails the
+// whole build on a name it can't find. Solid before brands, same as
+// Mintlify's own lookup.
+const BARE_ICON_COLLECTIONS = [DEFAULT_ICON_COLLECTION, 'fa6-solid', 'fa6-brands'];
+
+// Loaded lazily, once per collection, from the installed @iconify-json/*
+// packages (the same data astro-icon itself renders from). Resolved
+// against this package, not the site being built - WRITEDOCS_PACKAGE_ROOT
+// is set by run-astro.js; outside that subprocess, this file's own URL
+// still sits inside the package.
+interface IconifyCollection {
+  icons?: Record<string, { body: string; width?: number; height?: number }>;
+  aliases?: Record<string, { parent: string; width?: number; height?: number }>;
+  width?: number;
+  height?: number;
+}
+const iconCollections = new Map<string, IconifyCollection | null>();
+function loadIconCollection(collection: string): IconifyCollection | null {
+  if (!iconCollections.has(collection)) {
+    const packageRoot = process.env.WRITEDOCS_PACKAGE_ROOT;
+    const require = createRequire(packageRoot ? path.join(packageRoot, 'package.json') : import.meta.url);
+    let data: IconifyCollection | null = null;
+    try {
+      data = require(`@iconify-json/${collection}/icons.json`);
+    } catch {
+      data = null;
+    }
+    iconCollections.set(collection, data);
+  }
+  return iconCollections.get(collection) ?? null;
+}
+function collectionHasIcon(collection: string, name: string): boolean {
+  const data = loadIconCollection(collection);
+  return Boolean(data && (data.icons?.[name] || data.aliases?.[name]));
+}
+
+/** A standalone <svg> for an icon string, or null if it isn't an installed
+ *  Iconify icon (emoji/text, or a name no collection has). For the few
+ *  places that build HTML outside an Astro component and so can't use
+ *  astro-icon's <Icon> - a code block's title bar is built as HAST inside
+ *  a Shiki transformer (see shiki-code-block.js). Follows one level of
+ *  Iconify alias, which is all the installed collections use. */
+export function iconSvg(icon: string): string | null {
+  const resolved = resolveIcon(icon);
+  if (resolved.kind !== 'iconify') return null;
+  const [collection, name] = resolved.name.split(':');
+  const data = loadIconCollection(collection);
+  if (!data) return null;
+  const alias = data.aliases?.[name];
+  const entry = data.icons?.[alias ? alias.parent : name];
+  if (!entry) return null;
+  const width = entry.width ?? alias?.width ?? data.width ?? 16;
+  const height = entry.height ?? alias?.height ?? data.height ?? 16;
+  return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${width} ${height}">${entry.body}</svg>`;
+}
+
+/** Resolves a writedocs.json `icon` string into either an Iconify icon id or
+ *  literal text, covering three forms:
+ *  - "collection:icon-name" (e.g. "mdi:server", "simple-icons:github")
+ *    - used as-is against whatever @iconify-json/* collections are
+ *    installed (see astro.config.mjs / package.json).
+ *  - a bare name using only letters/digits/hyphens (e.g. "smartphone",
+ *    "book-open") - looked up in BARE_ICON_COLLECTIONS order (lucide,
+ *    then Font Awesome solid, then brands), using the first collection
+ *    that has it. A name none of them has still resolves to "lucide:...",
+ *    so the build error names the same collection it always did.
+ *  - an image URL or path - "https://...", "//...", "/icons/x.svg",
+ *    "./x.png" - rendered as an <img>. Mintlify accepts these for any
+ *    icon; before this they were printed as literal text.
+ *  - anything else (an emoji, a symbol, arbitrary text) - rendered
+ *    verbatim, preserving the original "just paste an emoji" behavior
+ *    from before icon-library support existed. */
+export function resolveIcon(icon: string): IconResolution {
+  if (/^(?:https?:)?\/\/|^\.{0,2}\//i.test(icon)) return { kind: 'image', src: icon };
+  if (/^[a-z0-9-]+:[a-z0-9-]+$/i.test(icon)) return { kind: 'iconify', name: icon };
+  if (/^[a-z0-9-]+$/i.test(icon)) {
+    const collection = BARE_ICON_COLLECTIONS.find((c) => collectionHasIcon(c, icon)) ?? DEFAULT_ICON_COLLECTION;
+    return { kind: 'iconify', name: `${collection}:${icon}` };
+  }
+  return { kind: 'text', value: icon };
+}
+
+// ---------------------------------------------------------------------
+// OpenAPI navigation expansion - turns a group's `openapi: { src, path }`
+// shorthand into a concrete `{ group, pages }` (one sub-group per tag),
+// using the per-spec manifest generate-api-pages.js writes to
+// writedocsTempDir()'s openapi/<path>/manifest.json before Astro starts (both
+// `writedocs dev` and `writedocs build` run it first - see
+// src/cli/dev.js, src/cli/build.js). Applied once, here in
+// loadDocsConfig(), so every other function in this file
+// (resolveSections, flattenNav, buildNavTree, ...) only ever sees plain
+// page-slug strings and ordinary `{ group, pages }` nodes, and never
+// needs to know the `openapi` group shorthand exists. A writedocs.json can
+// have any number of these groups, each pointing at its own spec and
+// mounted under its own `path` - generate-api-pages.js namespaces each
+// spec's manifest/operations under that same `path`, so there's no
+// cross-spec collision as long as every group uses a distinct `path`.
+// ---------------------------------------------------------------------
+
+export interface OpenApiManifestEntry {
+  slug: string;
+  method: string;
+  path: string;
+  tags: string[];
+  title: string;
+  generated: boolean;
+}
+
+/** `specPath` is the owning group's own `openapi.path` (e.g. "/api") -
+ *  generate-api-pages.js writes each spec's manifest under a directory
+ *  named after that same value, so this only ever needs to know which
+ *  group is asking, not anything about the spec's contents itself. */
+function loadOpenApiManifest(contentDir: string, specPath: string): OpenApiManifestEntry[] | null {
+  const normalized = specPath.replace(/^\/+|\/+$/g, '');
+  const manifestPath = path.join(writedocsTempDir(contentDir), 'openapi', normalized, 'manifest.json');
+  if (!fs.existsSync(manifestPath)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+  } catch {
+    return null; // stale/partial write from an interrupted previous run - treat as absent
+  }
+}
+
+/** Expands one group's `openapi: { src, path }` into the `pages` array
+ *  it stands in for - one sub-group per tag (in first-seen order),
+ *  untagged operations collected into a trailing "Other" group. Returns
+ *  an empty array (an empty, harmless group) rather than throwing if the
+ *  manifest is missing - generate-api-pages.js always runs before this
+ *  does (see src/cli/dev.js/build.js), so a missing manifest here means
+ *  generation hasn't happened yet rather than a user error worth
+ *  crashing the dev server over. */
+function expandOpenApiGroupPages(openapiRef: { src: string; path: string }, contentDir: string): NavItem[] {
+  const manifest = loadOpenApiManifest(contentDir, openapiRef.path);
+  if (!manifest) return [];
+
+  const seenTags: string[] = [];
+  const byTag = new Map<string, string[]>();
+  const untagged: string[] = [];
+  for (const op of manifest) {
+    const tag = op.tags[0];
+    if (!tag) {
+      untagged.push(op.slug);
+      continue;
+    }
+    if (!byTag.has(tag)) {
+      byTag.set(tag, []);
+      seenTags.push(tag);
+    }
+    byTag.get(tag)!.push(op.slug);
+  }
+  const groups: NavItem[] = seenTags.map((tag) => ({ group: tag, pages: byTag.get(tag)! }));
+  return untagged.length > 0 ? [...groups, { group: 'Other', pages: untagged }] : groups;
+}
+
+function expandOpenApiInPages(pages: NavItem[], contentDir: string): NavItem[] {
+  return pages.map((item): NavItem => {
+    if (typeof item === 'string') return item;
+    if ('href' in item) return item;
+    if ('openapi' in item) {
+      // A group using the { group, openapi: { src, path } } shorthand -
+      // replace it with a real { group, pages } node built from that
+      // spec's own manifest, so nothing downstream needs to know the
+      // shorthand ever existed.
+      return { group: item.group, pages: expandOpenApiGroupPages(item.openapi, contentDir) };
+    }
+    // An ordinary { group, page?, pages } - recurse into its own pages,
+    // since an openapi-group can be nested inside a hand-authored group
+    // too (e.g. wrapping it to add hand-written pages alongside the
+    // auto-generated ones).
+    return { ...item, pages: expandOpenApiInPages(item.pages, contentDir) };
+  });
+}
+
+/** Mirrors walkSections()'s traversal (tabs/versions/languages/
+ *  dropdowns/products, each bottoming out at `pages`), but rewrites
+ *  rather than collects - every `pages` array anywhere in the tree gets
+ *  run through expandOpenApiInPages(). */
+function expandOpenApiInContainer(node: NavChildren, contentDir: string): NavChildren {
+  if ('pages' in node) return { pages: expandOpenApiInPages(node.pages, contentDir) };
+  if ('href' in node) return node;
+  if ('tabs' in node) {
+    return { tabs: node.tabs.map((t) => ({ ...t, ...expandOpenApiInContainer(t, contentDir) })) };
+  }
+  if ('versions' in node) {
+    return { versions: node.versions.map((v) => ({ ...v, ...expandOpenApiInContainer(v, contentDir) })) };
+  }
+  if ('languages' in node) {
+    return { languages: node.languages.map((l) => ({ ...l, ...expandOpenApiInContainer(l, contentDir) })) };
+  }
+  if ('dropdowns' in node) {
+    return { dropdowns: node.dropdowns.map((d) => ({ ...d, ...expandOpenApiInContainer(d, contentDir) })) };
+  }
+  if ('products' in node) {
+    return { products: node.products.map((p) => ({ ...p, ...expandOpenApiInContainer(p, contentDir) })) };
+  }
+  return node;
+}
+
+function expandOpenApiInNavigation(navigation: NavigationConfig, contentDir: string): NavigationConfig {
+  if (Array.isArray(navigation)) return expandOpenApiInPages(navigation, contentDir);
+  const expanded = { ...navigation, ...expandOpenApiInContainer(navigation as Container, contentDir) };
+  if (navigation.global?.dropdowns) {
+    expanded.global = {
+      dropdowns: navigation.global.dropdowns.map(
+        (d) => ({ ...d, ...expandOpenApiInContainer(d, contentDir) }) as DropdownItem
+      ),
+    };
+  }
+  return expanded as NavigationConfig;
+}
+
+export function loadDocsConfig(contentDir: string): DocsConfig {
+  const configPath = path.join(contentDir, 'writedocs.json');
+  if (!fs.existsSync(configPath)) {
+    throw new Error(
+      `[writedocs] writedocs.json not found at ${configPath}. Run "writedocs init" to scaffold one.`
+    );
+  }
+  // A validacao em si (JSON.parse incluso) vive em validateDocsConfig
+  // (./config-schema.ts), o mesmo ponto de entrada que o `writedocs validate` e
+  // a plataforma usam - e o que garante que os tres reportem exatamente os
+  // mesmos problemas, com as mesmas palavras.
+  //
+  // As duas formas de falhar continuam saindo daqui EXATAMENTE como saiam antes
+  // desta extracao:
+  //   - JSON quebrado: relanca o proprio SyntaxError do JSON.parse (mesmo tipo,
+  //     mesma mensagem que o runtime produz);
+  //   - schema invalido: o mesmo Error, com o mesmo texto, montado a partir do
+  //     mesmo formatador que a CLI usa.
+  const result = validateDocsConfig(fs.readFileSync(configPath, 'utf-8'));
+  if (!result.ok) {
+    if (result.parseError) throw result.parseError;
+    throw new Error(`[writedocs] writedocs.json failed validation:\n${formatValidationIssues(result.issues)}`);
+  }
+  // A no-op pass over ordinary navigation trees (no openapi groups) -
+  // always run, rather than gated behind a global manifest check, since
+  // there's no longer a single global spec to check for.
+  result.data.navigation = expandOpenApiInNavigation(result.data.navigation, contentDir);
+  return result.data;
+}
+
+// --- Locating a page by file id, independent of its effective slug -----
+//
+// writedocs.json's `pages` arrays, and every helper above/below that walks
+// them (flattenNav, firstSlugOf, containerContainsSlug, buildNavTree, ...),
+// always identify a page by its file id - its path relative to the
+// content directory (project root), extension stripped, with a trailing
+// `/index` segment dropped (matching Astro's own default id computation -
+// see the `/index` note below) - regardless of how that page ends up
+// being served. docs/ is not special: a file at `docs/guides/x.mdx` has
+// file id `docs/guides/x`, the exact same rule applied to a file
+// anywhere else in the project.
+//
+// A page's actual URL is a separate question, and Astro's own glob()
+// content loader already has a first-class answer for it: if a page's
+// frontmatter sets `slug`, `entry.id` (and therefore the route Astro
+// builds for it) becomes that value verbatim instead of the file-path
+// default - see astro/dist/content/loaders/glob.js's generateIdDefault:
+// `if (data.slug) return data.slug`. content.config.ts's `slug` schema
+// field is deliberately the same field Astro already recognizes, so
+// nothing here needs to reimplement the override or track it separately -
+// it only needs a way to find a page BY file id (to resolve writedocs.json's
+// references) even once `entry.id` no longer equals it.
+//
+// --- Page discovery -------------------------------------------------
+//
+// Any .md/.mdx file anywhere under the content directory becomes a page
+// candidate the moment it has *any* frontmatter block at all - docs/ has
+// no special status here, it's just a folder like any other (a
+// conventional, recommended place to put most pages, not a requirement).
+// content.config.ts's `pages` collection is the same docsSchema applied
+// to exactly this file set. A file with zero frontmatter (no `---` block
+// whatsoever) is never a page candidate - a snippet (see
+// docs/dev/docs/snippets.mdx) typically has none, which is what lets it
+// live anywhere without tripping schema validation. A file that *does*
+// open a frontmatter block but is missing a required field (`title`)
+// still fails validation exactly as before - only "no frontmatter at
+// all" is new; a genuine mistake (frontmatter present, title forgotten)
+// stays a loud build error rather than being silently treated as
+// non-page content.
+//
+// A handful of directories are never scanned regardless of what's in
+// them - build output, dependencies, and writedocs' own working
+// directories, none of which a site author would ever intend as page
+// content. Only excluded at the content directory's own top level (a
+// hand-authored `guides/dist-notes.mdx` isn't mistaken for the build
+// output directory `dist/` just because a folder two levels down happens
+// to also be named `dist`).
+const EXCLUDED_TOP_LEVEL_DIRS = new Set(['node_modules', 'dist', '.astro', '.writedocs', 'public', '.git']);
+
+/** Recursively finds every .md/.mdx file under `contentDir` that has a
+ *  frontmatter block, skipping the handful of build/dependency
+ *  directories a real content directory tends to also contain (see
+ *  EXCLUDED_TOP_LEVEL_DIRS above) - docs/ is scanned exactly like any
+ *  other folder, no special-casing. Returns POSIX-relative paths (from
+ *  `contentDir`) suitable to hand straight to Astro's `glob()` loader as
+ *  a literal `pattern` array - see content.config.ts's `pages`
+ *  collection, and [...slug].astro, which needs the identical list to
+ *  decide whether calling `getCollection('pages')` is worth doing at all
+ *  (see content.config.ts's own comment on why an empty collection still
+ *  needs to exist, just backed by a no-op loader, to avoid Astro's "does
+ *  not exist or is empty" warning). Also reused directly by
+ *  astro.config.mjs's noindex/sitemap scan, so that scan always sees
+ *  exactly the same file set that actually becomes a page - no risk of
+ *  the two drifting apart. Synchronous and re-run from scratch wherever
+ *  it's called rather than cached and shared across modules - consistent
+ *  with how loadDocsConfig() itself is already called repeatedly across
+ *  this codebase instead of threaded through as shared state, and cheap
+ *  enough in practice (a docs site's own file count) not to matter. */
+export function findAllPages(contentDir: string): string[] {
+  const results: string[] = [];
+  function walk(dir: string, relBase: string) {
+    let entries: fs.Dirent[];
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const rel = relBase ? `${relBase}/${entry.name}` : entry.name;
+      const abs = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (relBase === '' && EXCLUDED_TOP_LEVEL_DIRS.has(entry.name)) continue;
+        walk(abs, rel);
+        continue;
+      }
+      if (!entry.isFile() || !/\.mdx?$/i.test(entry.name)) continue;
+      let raw: string;
+      try {
+        raw = fs.readFileSync(abs, 'utf-8');
+      } catch {
+        continue;
+      }
+      const { data } = matter(raw);
+      if (Object.keys(data).length === 0) continue; // no frontmatter at all - not a page
+      results.push(rel);
+    }
+  }
+  walk(contentDir, '');
+  return results;
+}
+
+/** Any `.css`/`.js` file anywhere in the project - root or any subfolder,
+ *  `public/` included - auto-loaded site-wide with zero `writedocs.json`
+ *  config, on top of (not instead of) the explicit `scripts` field
+ *  (bannerSchema and friends, above). Drop a file in, it loads;
+ *  there's no field naming which ones to use, matching the same "just
+ *  works" convention `docs/`'s own file discovery already follows (see
+ *  findAllPages() above / `content-pipeline.mdx`) - a site author already
+ *  drops content files in and expects them found, rather than also
+ *  listing every one in writedocs.json.
+ *
+ *  Two separate walks, because `public/` needs different treatment than
+ *  everywhere else:
+ *
+ *  - `css`/`js`: every `.css`/`.js` file outside `public/` (root, `docs/`,
+ *    `snippets/`, any custom folder) - reused as the walk-with-exclusions
+ *    shape from findAllPages() above, and its exact `EXCLUDED_TOP_LEVEL_DIRS`
+ *    set (skipped only at the project root, same as there), so `dist/`,
+ *    `node_modules/`, `.astro/`, `.writedocs/`, `.git/`, and (for this
+ *    half only - see below) `public/` are never walked into. BaseLayout.astro
+ *    reads each one's raw content and inlines it as a `<style>`/
+ *    `<script is:inline>` tag.
+ *  - `publicCss`/`publicJs`: every `.css`/`.js` file *inside* `public/`,
+ *    walked separately (starting from `<contentDir>/public` rather than
+ *    `contentDir` itself, so the same `EXCLUDED_TOP_LEVEL_DIRS` check
+ *    doesn't apply here - there's no `public/public/` or `public/dist/`
+ *    convention to guard against). Returned as public-URL-rooted hrefs
+ *    (a leading `/`, no `public` segment - `public/custom.css` becomes
+ *    `/custom.css`) rather than content-dir-relative paths, since these
+ *    files are already served as static assets at exactly that URL once
+ *    Astro copies `public/` into the build output. BaseLayout.astro
+ *    renders these as ordinary `<link rel="stylesheet">`/`<script src>`
+ *    tags pointing at that URL instead of inlining their content -
+ *    inlining would duplicate every byte (once in the page's own HTML,
+ *    once more as the independently-fetchable static file at that same
+ *    URL) for no benefit, where a `<link>`/`<script src>` gets normal
+ *    browser caching across pages instead of repeating the content on
+ *    every single page's markup.
+ *
+ *  Both halves are broader than they might sound - a stray `.js` file
+ *  kept in `docs/`, `snippets/`, or `public/` for an unrelated reason
+ *  (a snippet's own local helper, an image gallery's lightbox script
+ *  someone dropped in `public/` to reference from a raw `<script src>`
+ *  in an .mdx file, say) gets auto-injected sitewide the same as a
+ *  deliberate one; there's no separate "this one's just tooling" signal
+ *  to opt out of the convention short of renaming its extension.
+ *
+ *  Both `css`/`js` and `publicCss`/`publicJs` are sorted alphabetically
+ *  by their respective path for deterministic load order across rebuilds
+ *  - same reasoning as llms.txt's own alphabetical-by-slug sort (see
+ *  llms.txt.ts) - filesystem readdir order isn't guaranteed portable
+ *  across OSes or directory-walk order otherwise.
+ *
+ *  `css`/`js` return POSIX-separated paths relative to `contentDir`, not
+ *  absolute paths or file contents - BaseLayout.astro (the sole caller)
+ *  resolves and reads each one's content itself, right before inlining
+ *  it, so a file's content is always current as of that specific
+ *  request/build rather than cached here across a `writedocs dev`
+ *  session. `publicCss`/`publicJs` return the public-URL hrefs described
+ *  above - nothing to read, Astro's own static-file serving/copy already
+ *  handles those. */
+export function findRootAssets(
+  contentDir: string
+): { css: string[]; js: string[]; publicCss: string[]; publicJs: string[] } {
+  const css: string[] = [];
+  const js: string[] = [];
+  function walk(dir: string, relBase: string) {
+    let entries: fs.Dirent[];
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const rel = relBase ? `${relBase}/${entry.name}` : entry.name;
+      const abs = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (relBase === '' && EXCLUDED_TOP_LEVEL_DIRS.has(entry.name)) continue;
+        walk(abs, rel);
+        continue;
+      }
+      if (!entry.isFile()) continue;
+      if (/\.css$/i.test(entry.name)) css.push(rel);
+      else if (/\.js$/i.test(entry.name)) js.push(rel);
+    }
+  }
+  walk(contentDir, '');
+  css.sort();
+  js.sort();
+
+  const publicCss: string[] = [];
+  const publicJs: string[] = [];
+  function walkPublic(dir: string, relBase: string) {
+    let entries: fs.Dirent[];
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const rel = relBase ? `${relBase}/${entry.name}` : entry.name;
+      const abs = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        walkPublic(abs, rel);
+        continue;
+      }
+      if (!entry.isFile()) continue;
+      if (/\.css$/i.test(entry.name)) publicCss.push(`/${rel}`);
+      else if (/\.js$/i.test(entry.name)) publicJs.push(`/${rel}`);
+    }
+  }
+  walkPublic(path.join(contentDir, 'public'), '');
+  publicCss.sort();
+  publicJs.sort();
+
+  return { css, js, publicCss, publicJs };
+}
+
+/** The root-relative URL paths (leading `/`, e.g. `/images/hero.svg`)
+ *  referenced by the writedocs.json/styles fields that point at a static asset
+ *  *by URL* rather than embedding it inline: `styles.favicon`,
+ *  `styles.logo` (both the plain-string and `{light, dark}` object forms),
+ *  `styles.background.images.{light,dark}`, and `seo.ogImage`. External
+ *  URLs (anything not starting with `/` - `https://...`, mainly) are
+ *  filtered out, since those need no local file resolution at all.
+ *  Deduped, since e.g. `logo.light` and `background.images.light`
+ *  coincidentally pointing at the same file shouldn't resolve/copy it
+ *  twice.
+ *
+ *  Used by `stylesAssetFallback()` (`styles-asset-integration.js`,
+ *  imported from `astro.config.mjs`) to let every one of these resolve
+ *  from *anywhere* in the project, not just `public/` - previously,
+ *  `public/` was the one place `styles.background.images` (etc.) had to
+ *  live, since Astro's own `publicDir` copy is the only thing that ever
+ *  served them; everywhere else in this codebase's own "drop a file
+ *  anywhere, it's found" convention (`findRootAssets()` right above,
+ *  `findAllPages()` for content) already worked project-wide. See that
+ *  integration's own comment for the actual resolution mechanism (a dev-time
+ *  middleware plus a post-build copy step, not a duplicated `publicDir`)
+ *  and why a straight copy-into-`public/`-on-disk approach was rejected.
+ *
+ *  Logo light/dark resolution here deliberately mirrors BaseLayout.astro's
+ *  own `logoLight`/`logoDark` derivation exactly (a plain-string `logo`
+ *  counts as both light and dark) - two independent implementations of
+ *  that same union-unwrapping would only be one accidental edit away from
+ *  disagreeing with each other. `footer.logo` (footerSchema) gets the
+ *  same treatment, independently of `styles.logo` - both are collected
+ *  unconditionally here (not just whichever one BaseLayout.astro would
+ *  actually end up using for a given page), since this function has no
+ *  page context to know which page modes render a footer at all; an
+ *  unreferenced path collected here that never actually renders anywhere
+ *  is harmless (nothing copies/resolves a file that's never requested),
+ *  but a real footer.logo file silently 404ing because this function
+ *  didn't know to resolve it is exactly the bug this comment is warning
+ *  future edits away from repeating.
+ *
+ *  Per-page frontmatter `seo.ogImage` overrides are deliberately out of
+ *  scope - those aren't visible from a `DocsConfig` alone (they live in
+ *  each page's own frontmatter, merged in per-request by [...slug].astro/
+ *  BaseLayout.astro), and resolving every page's own override would need
+ *  a full content scan this function has no reason to also become. A
+ *  page overriding `seo.ogImage` to something outside `public/` still
+ *  needs to put it there for now. */
+export function collectConfiguredAssetPaths(config: DocsConfig): string[] {
+  const logo = config.styles.logo;
+  const logoLight = typeof logo === 'string' ? logo : logo?.light;
+  const logoDark = typeof logo === 'string' ? logo : logo?.dark;
+  const footerLogo = config.footer.logo;
+  const footerLogoLight = typeof footerLogo === 'string' ? footerLogo : footerLogo?.light;
+  const footerLogoDark = typeof footerLogo === 'string' ? footerLogo : footerLogo?.dark;
+  const fonts = config.styles.fonts;
+  const raw: (string | undefined)[] = [
+    config.styles.favicon,
+    logoLight,
+    logoDark,
+    footerLogoLight,
+    footerLogoDark,
+    config.styles.background?.images?.light,
+    config.styles.background?.images?.dark,
+    config.seo?.ogImage,
+    // A `styles.fonts` `source` is only ever handled here when it's a
+    // project-relative path (the `p.startsWith('/')` filter below already
+    // excludes both Google Font names, which never start with "/", and a
+    // full https:// external font URL, which the browser fetches directly
+    // - neither needs resolving/copying through this pipeline at all).
+    fonts?.source,
+    fonts?.heading?.source,
+    fonts?.body?.source,
+  ];
+  const paths = raw.filter((p): p is string => Boolean(p) && p.startsWith('/'));
+  return Array.from(new Set(paths));
+}
+
+export interface DocsEntryLike {
+  id: string;
+  filePath?: string;
+}
+
+/** Recovers a content entry's writedocs.json-facing file id (its path
+ *  relative to the content directory, extension stripped, trailing
+ *  `/index` dropped), independent of any frontmatter `slug` override -
+ *  `entry.filePath` is always root-relative and POSIX-separated (how
+ *  Astro's content layer records it, relative to whatever `--root` Astro
+ *  itself was invoked with - see run-astro.js), so both it and the
+ *  content directory are resolved to absolute paths before comparing,
+ *  rather than string-matching a prefix that could be relative,
+ *  absolute, or platform-separated inconsistently.
+ *
+ *  The trailing-`/index`-drop mirrors Astro's own default id computation
+ *  exactly (`getContentEntryIdAndSlug()` in astro/dist/content/
+ *  utils.js: segments are joined then `.replace(/\/index$/, '')`) -
+ *  without it, a nested index file like `docs/guides/index.mdx` (Astro's
+ *  own default id: "docs/guides") would recover the wrong file id here
+ *  ("docs/guides/index"), and a writedocs.json reference written to match the
+ *  page's real URL would fail to resolve. A single-segment `index.mdx`
+ *  at the content root is unaffected either way - the regex requires a
+ *  preceding `/`, which a bare "index" doesn't have (matching Astro's
+ *  own behavior: a root-level index.mdx keeps file id "index", not "").
+ *
+ *  Full per-segment slugification (github-slugger, applied by Astro to
+ *  every path segment) is deliberately *not* replicated here - every
+ *  filename in this codebase's own fixtures and every filename this
+ *  function needs to have handled correctly is already slug-safe
+ *  (lowercase, hyphenated, no spaces/unicode), so slugification is
+ *  always a no-op in practice; only the `/index`-stripping behavior is
+ *  reproduced, since that's the one part of Astro's algorithm this
+ *  change newly exercises (a file that used to be a collection's own
+ *  base-root index, exempt from stripping, and is now nested one level
+ *  deeper).
+ *
+ *  Entries from the `generatedDocs` collection (auto-generated OpenAPI
+ *  stub pages - see content.config.ts / generate-api-pages.js) live
+ *  under writedocsTempDir()'s generated-docs/ directory - an OS temp
+ *  directory location entirely outside contentDir, not a subdirectory
+ *  of it - so `relativeToContentDir` for one of these always starts with
+ *  `..` (walking back out of contentDir to reach it), and the check
+ *  right below falls back to `entry.id` instead of computing a
+ *  nonsensical id relative to a directory the file was never actually
+ *  under. Those entries always set their own `slug` frontmatter
+ *  explicitly, so there's no independent "file path" identity worth
+ *  recovering for them the way there is for a hand-written page that
+ *  might move around - `entry.id` (Astro's already-resolved slug)
+ *  already IS the exact value generate-api-pages.js's own manifest
+ *  references them by. */
+export function fileIdForEntry(
+  contentDir: string,
+  packageRoot: string,
+  entry: DocsEntryLike
+): string {
+  if (!entry.filePath) return entry.id;
+  const absoluteContentDir = path.resolve(contentDir);
+  const absoluteFilePath = path.resolve(packageRoot, entry.filePath);
+  const relativeToContentDir = path.relative(absoluteContentDir, absoluteFilePath);
+  if (relativeToContentDir.startsWith('..')) return entry.id;
+  const posixRelative = relativeToContentDir.split(path.sep).join('/');
+  if (EXCLUDED_TOP_LEVEL_DIRS.has(posixRelative.split('/')[0])) return entry.id;
+  return posixRelative.replace(/\.mdx?$/i, '').replace(/\/index$/, '');
+}
+
+/** Normalizes a raw `entry.id` into the bare, slash-free form every
+ *  route/href in this codebase assumes. Once a page sets a frontmatter
+ *  `slug`, `entry.id` becomes that value completely verbatim - Astro's
+ *  glob loader applies no normalization of its own (see
+ *  generateIdDefault in astro/dist/content/loaders/glob.js) - so
+ *  `slug: /` or `slug: /guides/new-name` (both natural things to write,
+ *  mirroring how every href elsewhere in writedocs.json already has a
+ *  leading slash) would otherwise produce broken multi-slash hrefs
+ *  wherever hrefForSlug wraps the value in its own `/${slug}/`, and a
+ *  bare "/" would additionally fail to be recognized as claiming root,
+ *  colliding with the synthetic root-redirect route. */
+export function normalizeEntryId(id: string): string {
+  const trimmed = id.replace(/^\/+/, '').replace(/\/+$/, '');
+  return trimmed === '' ? 'index' : trimmed;
+}
+
+export interface FlatNavEntry {
+  slug: string;
+  group: string | null;
+}
+
+export function flattenNav(navigation: NavItem[], group: string | null = null): FlatNavEntry[] {
+  return navigation.flatMap((item): FlatNavEntry[] => {
+    if (typeof item === 'string') {
+      return [{ slug: item, group }];
+    }
+    if ('href' in item) return []; // external link leaf, not a content page - no route/prev-next entry
+    // loadDocsConfig() always expands `{ group, openapi }` shorthand into
+    // a real `{ group, pages }` before anything reaches here (see
+    // expandOpenApiInNavigation() above) - this is just a defensive
+    // no-op for the shouldn't-happen case of an unexpanded node.
+    if ('openapi' in item) return [];
+    const ownPage: FlatNavEntry[] = item.page ? [{ slug: item.page, group: item.group }] : [];
+    return [...ownPage, ...flattenNav(item.pages, item.group)];
+  });
+}
+
+// --- Sections -------------------------------------------------------
+//
+// A Section is the atomic unit that owns one page tree and therefore one
+// sidebar - every real content page belongs to exactly one Section,
+// whichever `pages` leaf it's listed under, however deep in the
+// tabs/versions/languages/dropdowns/products tree that leaf lives.
+//
+// A Section's `path` records the full chain of containers from the
+// navigation root down to it, one PathSegment per level. This is
+// everything the topbar needs to render the right selector controls
+// (tabs bar, version dropdown, ...) and highlight the right option in
+// each - without the router or layout needing to know how deep or in
+// what order the site author nested things.
+
+export type PathSegment =
+  | { kind: 'tab'; items: TabItem[]; index: number }
+  | { kind: 'version'; items: VersionItem[]; index: number }
+  | { kind: 'language'; items: LanguageItem[]; index: number }
+  | { kind: 'dropdown'; items: DropdownItem[]; index: number }
+  | { kind: 'product'; items: ProductItem[]; index: number };
+
+export interface Section {
+  pages: NavItem[];
+  path: PathSegment[];
+}
+
+type Container = NavChildren;
+type NamedContainer = TabItem | VersionItem | LanguageItem | DropdownItem | ProductItem;
+
+function walkSections(node: Container, path: PathSegment[], out: Section[]): void {
+  if ('pages' in node) {
+    out.push({ pages: node.pages, path });
+    return;
+  }
+  if ('href' in node) return; // external link, not a Section
+  if ('tabs' in node) {
+    node.tabs.forEach((item, index) =>
+      walkSections(item, [...path, { kind: 'tab', items: node.tabs, index }], out)
+    );
+    return;
+  }
+  if ('versions' in node) {
+    node.versions.forEach((item, index) =>
+      walkSections(item, [...path, { kind: 'version', items: node.versions, index }], out)
+    );
+    return;
+  }
+  if ('languages' in node) {
+    node.languages.forEach((item, index) =>
+      walkSections(item, [...path, { kind: 'language', items: node.languages, index }], out)
+    );
+    return;
+  }
+  if ('dropdowns' in node) {
+    node.dropdowns.forEach((item, index) =>
+      walkSections(item, [...path, { kind: 'dropdown', items: node.dropdowns, index }], out)
+    );
+    return;
+  }
+  if ('products' in node) {
+    node.products.forEach((item, index) =>
+      walkSections(item, [...path, { kind: 'product', items: node.products, index }], out)
+    );
+    return;
+  }
+}
+
+export function resolveSections(navigation: NavigationConfig): Section[] {
+  if (Array.isArray(navigation)) return [{ pages: navigation, path: [] }];
+  const sections: Section[] = [];
+  walkSections(navigation as Container, [], sections);
+  // global.dropdowns sits outside the primary pattern, but its pages
+  // still need routes generated for them - walk each entry too, with an
+  // empty path (they don't participate in the tabs/version/etc.
+  // selector chain, only in the always-visible globalDropdowns list).
+  for (const dropdown of navigation.global?.dropdowns ?? []) {
+    walkSections(dropdown, [], sections);
+  }
+  return sections;
+}
+
+/** Which Section (by index into resolveSections()'s result) a page belongs to. */
+export function findSectionIndexForSlug(sections: Section[], slug: string): number {
+  const index = sections.findIndex((s) => flattenNav(s.pages).some((entry) => entry.slug === slug));
+  return index === -1 ? 0 : index;
+}
+
+/** The always-visible topbar dropdown list - independent of whichever
+ *  primary pattern/section is active (Mintlify's equivalent is
+ *  `navigation.global.anchors`). */
+export function resolveGlobalDropdowns(navigation: NavigationConfig): DropdownItem[] {
+  if (Array.isArray(navigation)) return [];
+  return navigation.global?.dropdowns ?? [];
+}
+
+/** The first real page slug reachable by descending into a container's
+ *  content, however deep - used to compute where a selector option (a
+ *  tab, a version, ...) navigates to when chosen. Null for an external
+ *  `href` leaf, which the caller renders as a plain link using the
+ *  node's own href instead. Versions prefer whichever entry is marked
+ *  `default` (falling back to the first), matching Mintlify's version
+ *  default rule. */
+/** Tries `firstSlugOf()` against each item in order, returning the first
+ *  non-null result - a plain `items[0]` pick (the previous behavior)
+ *  breaks the moment that first sibling happens to be a bare `href` leaf
+ *  (returns null, with nothing that tries the next one), which is a real
+ *  case now that any container - not just a nested dropdown - can be a
+ *  bare external link (e.g. a `tabs` array whose first entry is
+ *  `{ tab: "Status", href: "..." }`). */
+function firstSlugAmong(items: Container[]): string | null {
+  for (const item of items) {
+    const slug = firstSlugOf(item);
+    if (slug !== null) return slug;
+  }
+  return null;
+}
+
+export function firstSlugOf(node: Container): string | null {
+  if ('pages' in node) return flattenNav(node.pages)[0]?.slug ?? null;
+  if ('href' in node) return null;
+  if ('tabs' in node) return firstSlugAmong(node.tabs);
+  if ('versions' in node) {
+    // Try the `default`-tagged version(s) first (matching the old
+    // "preferred" pick), then fall through to the rest in order - same
+    // href-leaf-with-no-fallback concern as `tabs` above, just with an
+    // extra preference pass in front of it.
+    const defaults = node.versions.filter((v) => v.default);
+    const rest = node.versions.filter((v) => !v.default);
+    return firstSlugAmong([...defaults, ...rest]);
+  }
+  if ('languages' in node) return firstSlugAmong(node.languages);
+  if ('dropdowns' in node) return firstSlugAmong(node.dropdowns);
+  if ('products' in node) return firstSlugAmong(node.products);
+  return null;
+}
+
+/** For a version/language switcher, finds where the reader's current
+ *  page would live inside a *different* version/language's own subtree,
+ *  so switching keeps them on the same conceptual page instead of always
+ *  bouncing to that option's first page (see buildSelectors() below,
+ *  which is the only caller). "Same page" is approximated positionally
+ *  rather than by name, since nothing guarantees a version/language's
+ *  own identifier lines up with its pages' file paths - a version
+ *  tagged "2025-09" could just as easily keep its pages under a "v1"
+ *  folder with no relation to that string, so there's no naming
+ *  convention to key off safely; this heuristic only ever compares tree
+ *  position, never path text. (docs.json-examples/00-kitchen-sink/'s own
+ *  versions - "2025-09"/"2026-01" under Core Platform - happen to have
+ *  folder names that line up with their version strings, so it doesn't
+ *  demonstrate the mismatched-folder-name case directly; the guarantee
+ *  still doesn't exist regardless of what one fixture happens to do.)
+ *
+ *  Two things have to line up for a page to count as "the same" one:
+ *  first, `remainingPath` (whatever tab/product/dropdown was chosen
+ *  *below* the version/language being switched, on the reader's actual
+ *  page) has to exist at the same index in `item`'s own subtree too -
+ *  an option isn't guaranteed to nest the same way that many levels
+ *  down (a version could add/remove a tab), so any mismatch here bails
+ *  out to null immediately rather than guessing. Second, once both
+ *  bottom out at a leaf `pages` list, `position` (the reader's own page
+ *  index within *its* pages list) has to exist in `item`'s pages list
+ *  too - two versions/languages of the same docs are usually authored
+ *  with matching page order even when the file paths differ, so this
+ *  is a reasonable proxy for "the same page" without relying on names.
+ *
+ *  Returns null - meaning "no equivalent page, fall back to
+ *  firstSlugOf()" - on any structural mismatch or an out-of-range
+ *  position, rather than guessing at a wrong page. */
+export function equivalentPageIn(
+  item: Container,
+  remainingPath: PathSegment[],
+  position: number
+): string | null {
+  if ('pages' in item) return flattenNav(item.pages)[position]?.slug ?? null;
+  if ('href' in item) return null;
+  const [next, ...rest] = remainingPath;
+  if (!next) return null; // the reader's own page didn't go this deep - no basis to pick a branch
+  if ('tabs' in item && next.kind === 'tab') {
+    const target = item.tabs[next.index];
+    return target ? equivalentPageIn(target, rest, position) : null;
+  }
+  if ('versions' in item && next.kind === 'version') {
+    const target = item.versions[next.index];
+    return target ? equivalentPageIn(target, rest, position) : null;
+  }
+  if ('languages' in item && next.kind === 'language') {
+    const target = item.languages[next.index];
+    return target ? equivalentPageIn(target, rest, position) : null;
+  }
+  if ('dropdowns' in item && next.kind === 'dropdown') {
+    const target = item.dropdowns[next.index];
+    return target ? equivalentPageIn(target, rest, position) : null;
+  }
+  if ('products' in item && next.kind === 'product') {
+    const target = item.products[next.index];
+    return target ? equivalentPageIn(target, rest, position) : null;
+  }
+  return null; // structural mismatch - this option nests differently at this depth
+}
+
+/** The first real page slug in the whole site, root navigation pattern
+ *  included - used to redirect `/` somewhere sensible when nothing in
+ *  the navigation happens to be a page literally named "index" (the
+ *  usual "docs/index.mdx is the homepage" convention). Mirrors
+ *  firstSlugOf()'s per-container descent, plus the flat-array root case
+ *  firstSlugOf() alone can't handle since a bare array isn't a Container. */
+export function firstSlugOfNavigation(navigation: NavigationConfig): string | null {
+  if (Array.isArray(navigation)) return flattenNav(navigation)[0]?.slug ?? null;
+  return firstSlugOf(navigation as Container);
+}
+
+/** Whether `slug` is reachable anywhere underneath a container, however
+ *  deep - used for computing active state on nodes that aren't part of
+ *  the active Section's own `path` (global dropdown entries). */
+export function containerContainsSlug(node: Container, slug: string): boolean {
+  if ('pages' in node) return flattenNav(node.pages).some((entry) => entry.slug === slug);
+  if ('href' in node) return false;
+  if ('tabs' in node) return node.tabs.some((t) => containerContainsSlug(t, slug));
+  if ('versions' in node) return node.versions.some((v) => containerContainsSlug(v, slug));
+  if ('languages' in node) return node.languages.some((l) => containerContainsSlug(l, slug));
+  if ('dropdowns' in node) return node.dropdowns.some((d) => containerContainsSlug(d, slug));
+  if ('products' in node) return node.products.some((p) => containerContainsSlug(p, slug));
+  return false;
+}
+
+function labelOf(item: NamedContainer): string {
+  if ('tab' in item) return item.tab;
+  if ('version' in item) return item.label ?? item.version;
+  if ('language' in item) return item.label ?? item.language;
+  if ('dropdown' in item) return item.dropdown;
+  return item.product;
+}
+
+function iconOf(item: NamedContainer): string | undefined {
+  return (item as { icon?: string }).icon;
+}
+
+// --- Topbar selectors -------------------------------------------------
+//
+// One Selector per PathSegment on the active Section's path. Tabs render
+// as the horizontal pill bar (all options always visible, exactly one
+// current); versions/languages/products, and dropdowns used as a nested
+// path segment, render as a single switcher control instead - the
+// trigger shows the *current* option, its menu lists the alternatives.
+// See BaseLayout.astro for the actual markup per kind.
+
+export interface SelectorOption {
+  label: string;
+  icon?: string;
+  tag?: string;
+  href: string;
+  active: boolean;
+  // Set when this option's own container is a `dropdowns` list (e.g. a
+  // tab whose content is `dropdowns` instead of `pages`) - the tab pill
+  // itself becomes a dropdown-trigger showing these as its menu, rather
+  // than a separate dropdown control rendered alongside it. Only ever
+  // populated one level deep (a dropdown option doesn't itself get a
+  // nested `dropdown` - matches the one level of "a tab/dropdown owns a
+  // dropdowns list" this is meant to cover).
+  dropdown?: SelectorOption[];
+}
+
+export interface Selector {
+  kind: PathSegment['kind'];
+  options: SelectorOption[];
+}
+
+/** An option's own `dropdowns` menu, if it has one (see SelectorOption.dropdown
+ *  above) - `activeSegment` is the *next* PathSegment after this option's own
+ *  segment, only passed when this option is the active one on its level, so a
+ *  sibling option that also happens to own `dropdowns` doesn't spuriously mark
+ *  one of its entries active just because some *other* option is currently
+ *  selected. */
+function dropdownMenuOf(
+  node: NavChildren,
+  hrefForSlug: (slug: string) => string,
+  activeSegment: PathSegment | undefined
+): SelectorOption[] | undefined {
+  if (!('dropdowns' in node)) return undefined;
+  return node.dropdowns.map((d, i) => ({
+    label: d.dropdown,
+    icon: iconOf(d),
+    href: 'href' in d ? d.href : hrefForSlug(firstSlugOf(d) ?? 'index'),
+    active: activeSegment?.kind === 'dropdown' && activeSegment.index === i,
+  }));
+}
+
+/** `activePagePosition` is the reader's current page's own index within
+ *  its Section's flattened pages list (-1 if it can't be found there,
+ *  which just disables the position-preserving behavior below) - see
+ *  [...slug].astro for how it's computed. Only version/language
+ *  switchers try to preserve position across options; tabs/dropdowns/
+ *  products keep linking to firstSlugOf() unconditionally, since those
+ *  represent genuinely different content (an "API Reference" tab isn't
+ *  "the same page" as a "Guides" tab just because they're both first),
+ *  unlike a version/language of what's meant to be the same docs. */
+export function buildSelectors(
+  path: PathSegment[],
+  hrefForSlug: (slug: string) => string,
+  activePagePosition: number = -1
+): Selector[] {
+  return path.map((segment, segIndex): Selector => {
+    const preservesPosition =
+      (segment.kind === 'version' || segment.kind === 'language') && activePagePosition >= 0;
+    const remainingPath = path.slice(segIndex + 1);
+    return {
+      kind: segment.kind,
+      options: (segment.items as NamedContainer[]).map((item, i) => {
+        const isActive = i === segment.index;
+        const equivalentSlug = preservesPosition
+          ? equivalentPageIn(item as Container, remainingPath, activePagePosition)
+          : null;
+        const targetSlug = equivalentSlug ?? firstSlugOf(item as Container) ?? 'index';
+        return {
+          label: labelOf(item),
+          icon: iconOf(item),
+          tag: 'tag' in item ? item.tag : undefined,
+          href: 'href' in item ? item.href : hrefForSlug(targetSlug),
+          active: isActive,
+          dropdown: dropdownMenuOf(item, hrefForSlug, isActive ? path[segIndex + 1] : undefined),
+        };
+      }),
+    };
+  });
+}
+
+// --- Global dropdowns ---------------------------------------------------
+//
+// Unlike path-segment selectors, global dropdowns aren't a mutually
+// exclusive "pick one" choice - `global.dropdowns` is an array where
+// *every* entry renders as its own always-visible trigger button
+// simultaneously (Mintlify's anchors work the same way). A trigger's
+// menu lists its own direct pages as quick links; a bare-href entry is
+// just a plain link with no menu; a deeply-nested entry (tabs/versions/
+// etc. instead of direct pages) falls back to linking straight to its
+// first page, since building a rich flyout for that combination isn't
+// worth the complexity for what's meant to be a quick-links affordance.
+
+export interface GlobalDropdownView {
+  label: string;
+  icon?: string;
+  href: string | null;
+  items: SelectorOption[];
+}
+
+export function buildGlobalDropdowns(
+  dropdowns: DropdownItem[],
+  currentSlug: string,
+  titleForSlug: (slug: string) => string,
+  hrefForSlug: (slug: string) => string,
+  metaForSlug?: (slug: string) => NavPageMeta | undefined
+): GlobalDropdownView[] {
+  return dropdowns.map((d): GlobalDropdownView => {
+    if ('href' in d) {
+      return { label: d.dropdown, icon: d.icon, href: d.href, items: [] };
+    }
+    if ('pages' in d) {
+      // Same `hidden`/`url` handling as buildNavTree().
+      const items = flattenNav(d.pages)
+        .filter((entry) => !metaForSlug?.(entry.slug)?.hidden)
+        .map((entry) => ({
+          label: titleForSlug(entry.slug),
+          href: metaForSlug?.(entry.slug)?.url ?? hrefForSlug(entry.slug),
+          active: entry.slug === currentSlug,
+        }));
+      return { label: d.dropdown, icon: d.icon, href: null, items };
+    }
+    const slug = firstSlugOf(d);
+    return { label: d.dropdown, icon: d.icon, href: slug ? hrefForSlug(slug) : '#', items: [] };
+  });
+}
+
+// --- Sidebar (recursive) -------------------------------------------------
+
+// A group node's `pageSlug` is the page its own label links to (null if
+// it's a pure disclosure/label with no page of its own - the group only
+// groups). NavTree.astro renders depth-0 groups as static, non-collapsible
+// section titles (linked if `pageSlug` is set, plain text otherwise) and
+// every deeper group as a collapsible row styled like a page item, with a
+// chevron, defaulting open when it contains the active page - see
+// navTreeContainsSlug() below.
+export type NavTreeNode =
+  | {
+      kind: 'page';
+      slug: string;
+      title: string;
+      method: string | null;
+      icon?: string;
+      tag?: string;
+      deprecated?: boolean;
+    }
+  | { kind: 'group'; label: string; pageSlug: string | null; children: NavTreeNode[] }
+  | { kind: 'link'; label: string; href: string };
+
+/** Builds the sidebar's view model, preserving group nesting depth.
+ *  `methodForSlug` is optional (most sites have no OpenAPI pages at all)
+ *  and, when given, returns the HTTP method to badge a page with in the
+ *  sidebar (e.g. "GET") or null for an ordinary page - see
+ *  NavTree.astro for how that badge renders. */
+/** Per-page frontmatter that changes how a page shows up in navigation -
+ *  Mintlify's `hidden`, `url`, `icon`, `tag` and `deprecated` (see
+ *  content.config.ts's docsSchema). */
+export interface NavPageMeta {
+  hidden?: boolean;
+  url?: string;
+  icon?: string;
+  tag?: string;
+  deprecated?: boolean;
+}
+
+export function buildNavTree(
+  navigation: NavItem[],
+  titleForSlug: (slug: string) => string,
+  methodForSlug?: (slug: string) => string | null,
+  metaForSlug?: (slug: string) => NavPageMeta | undefined
+): NavTreeNode[] {
+  return navigation.flatMap((item): NavTreeNode[] => {
+    if (typeof item === 'string') {
+      const meta = metaForSlug?.(item);
+      // A `hidden` page keeps its route but gets no sidebar entry.
+      if (meta?.hidden) return [];
+      // A `url` page is an external link in the sidebar, not a page.
+      if (meta?.url) return [{ kind: 'link', label: titleForSlug(item), href: meta.url }];
+      return [
+        {
+          kind: 'page',
+          slug: item,
+          title: titleForSlug(item),
+          method: methodForSlug?.(item) ?? null,
+          icon: meta?.icon,
+          tag: meta?.tag,
+          deprecated: meta?.deprecated,
+        },
+      ];
+    }
+    if ('href' in item) {
+      return [{ kind: 'link', label: item.label, href: item.href }];
+    }
+    // loadDocsConfig() always expands `{ group, openapi }` shorthand into
+    // a real `{ group, pages }` before anything reaches here (see
+    // expandOpenApiInNavigation() in the OpenAPI section above) - this is
+    // just a defensive no-op for the shouldn't-happen case of an
+    // unexpanded node reaching the sidebar builder.
+    if ('openapi' in item) {
+      return [{ kind: 'group', label: item.group, pageSlug: null, children: [] }];
+    }
+    return [
+      {
+        kind: 'group',
+        label: item.group,
+        pageSlug: item.page ?? null,
+        children: buildNavTree(item.pages, titleForSlug, methodForSlug, metaForSlug),
+      },
+    ];
+  });
+}
+
+/** Whether `slug` is the group's own attached page, or belongs to any page/group nested inside it. */
+export function navTreeContainsSlug(nodes: NavTreeNode[], slug: string): boolean {
+  return nodes.some((node) => {
+    if (node.kind === 'page') return node.slug === slug;
+    if (node.kind === 'link') return false;
+    return node.pageSlug === slug || navTreeContainsSlug(node.children, slug);
+  });
+}
+
+export interface BreadcrumbCrumb {
+  label: string;
+  href: string | null;
+}
+
+/** The chain of ancestor group labels (root first) that `slug` is nested
+ *  under within `nodes` - empty when the page sits at the top level of its
+ *  Section with no enclosing group at all, in which case the caller should
+ *  skip rendering breadcrumbs entirely (there'd be nothing to show but the
+ *  fixed home icon Breadcrumbs.astro always renders first).
+ *
+ *  Deliberately never includes the current page itself - only the groups
+ *  it's nested under (that's already the <h1> right below, repeating it
+ *  in the breadcrumb trail would just be noise). A group whose own
+ *  attached page (`pageSlug`, see NavTreeNode) *is* `slug` is excluded
+ *  from its own trail for the same reason - you're looking at that page,
+ *  it doesn't need to also list itself as its own ancestor. A group only
+ *  appears here when `slug` is nested *inside* it (its own page, if any,
+ *  links to that group's landing page - `href: null` for a label-only
+ *  group with no page of its own to link to). */
+export function ancestorGroupsForSlug(
+  nodes: NavTreeNode[],
+  slug: string,
+  hrefForSlug: (slug: string) => string
+): BreadcrumbCrumb[] {
+  for (const node of nodes) {
+    if (node.kind !== 'group') continue;
+    if (node.pageSlug === slug) return [];
+    if (navTreeContainsSlug(node.children, slug)) {
+      const crumb: BreadcrumbCrumb = { label: node.label, href: node.pageSlug ? hrefForSlug(node.pageSlug) : null };
+      return [crumb, ...ancestorGroupsForSlug(node.children, slug, hrefForSlug)];
+    }
+  }
+  return [];
+}