@writedocs/generator 0.1.0 → 0.2.1

package/src/lib/config.ts

@@ -1,2131 +1,1306 @@
-import fs from 'node:fs';
-import path from 'node:path';
-import matter from 'gray-matter';
-import { z } from 'astro/zod';
-import { writedocsTempDir } from './writedocs-temp-dir.js';
-
-// ---------------------------------------------------------------------
-// Pages & groups - the leaf content any container ultimately bottoms out
-// at. A group can nest other groups arbitrarily deep, and can optionally
-// link its own label to a page (`page`) independent of expanding or
-// collapsing its children - see NavTree.astro for how that renders.
-// ---------------------------------------------------------------------
-
-const navPageSchema = z.string();
-
-// A group ordinarily lists its own children by hand (`pages`), but can
-// instead auto-generate them from an OpenAPI spec via `openapi: { src,
-// path }` - resolved by loadDocsConfig() (via expandOpenApiInNavigation()
-// below, reading the manifest generate-api-pages.js writes for this exact
-// group) into a real `{ group, pages }` node - one sub-group per tag -
-// before anything else in this file ever sees it, so
-// resolveSections()/flattenNav()/buildNavTree()/etc. only ever need to
-// understand the ordinary pages-array shape. `.strict()` on both variants
-// is load-bearing (see withChildren()'s own comment on this pattern
-// below): without it, a group written with both `pages` and `openapi` at
-// once would silently have one dropped instead of rejected.
-const navGroupPagesSchema: z.ZodType<{ group: string; page?: string; pages: NavItem[] }> = z.lazy(() =>
-  z
-    .object({
-      group: z.string(),
-      page: z.string().optional(),
-      pages: z.array(navItemSchema),
-    })
-    .strict()
-);
-
-const navGroupOpenApiSchema = z.object({
-  group: z.string(),
-  openapi: z
-    .object({
-      // Path to an OpenAPI 3.x spec, relative to the content directory
-      // (alongside writedocs.json) - same convention the old top-level
-      // `openapi` field used. See generate-api-pages.js (the pre-Astro
-      // build/dev step that actually parses this and writes the
-      // manifest/operation JSON this group's pages are expanded from).
-      src: z.string(),
-      // Base URL path every page generated from this spec is namespaced
-      // under, e.g. "/api" -> pages served at /api/<tag>/<operation>/.
-      // Also doubles as this spec's own unique key under
-      // writedocsTempDir()'s openapi/<path>/ directory (manifest.json + operations/*.json),
-      // so two openapi groups in the same writedocs.json must use different
-      // `path` values - generate-api-pages.js throws a clear error if
-      // they collide.
-      path: z.string(),
-    })
-    .strict(),
-}).strict();
-
-export type GroupNavItem =
-  | { group: string; page?: string; pages: NavItem[] }
-  | { group: string; openapi: { src: string; path: string } };
-
-const navGroupSchema: z.ZodType<GroupNavItem> = z.union([navGroupPagesSchema, navGroupOpenApiSchema]);
-
-// A bare external link sitting directly in a `pages` array, alongside
-// page slugs and groups - e.g. a "Support" link to an external help
-// desk shown right in the sidebar, rather than only reachable via
-// navigation.global.dropdowns. Discriminated from navGroupSchema by
-// its required `label`/`href` keys (vs `group`/`pages`/`openapi`), so a
-// plain (non-strict at the union level) schema is enough for Zod to pick
-// the right branch; `.strict()` here still catches a typo'd extra key.
-const navLinkSchema = z.object({ label: z.string(), href: z.string() }).strict();
-
-const navItemSchema: z.ZodType<NavItem> = z.lazy(() =>
-  z.union([navPageSchema, navGroupSchema, navLinkSchema])
-);
-
-export type NavItem = string | GroupNavItem | { label: string; href: string };
-
-// ---------------------------------------------------------------------
-// Containers: tabs, versions, languages, dropdowns, products.
-//
-// This schema is modeled directly on Mintlify's writedocs.json
-// (https://mintlify.com/writedocs.json / mintlify.com/docs/organize/navigation):
-// all five container kinds are structurally identical except for their
-// own identifying field. Each owns *exactly one* of {pages, tabs,
-// versions, languages, dropdowns, products} as its content, or is a bare
-// external `href` link with no content of its own. That symmetry is what
-// lets any of them nest inside any other - a tab can contain versions, a
-// version can contain languages, a language can contain tabs, and so on,
-// bottoming out at a `pages` array. `withChildren()` is the single place
-// that shape is defined, instead of hand-writing the union five times.
-// ---------------------------------------------------------------------
-
-export type NavChildren =
-  | { pages: NavItem[] }
-  | { tabs: TabItem[] }
-  | { versions: VersionItem[] }
-  | { languages: LanguageItem[] }
-  | { dropdowns: DropdownItem[] }
-  | { products: ProductItem[] }
-  | { href: string };
-
-export type TabItem = { tab: string; icon?: string } & NavChildren;
-export type VersionItem = { version: string; label?: string; tag?: string; default?: boolean } & NavChildren;
-export type LanguageItem = { language: string; label?: string } & NavChildren;
-export type DropdownItem = { dropdown: string; icon?: string } & NavChildren;
-export type ProductItem = { product: string; icon?: string; description?: string } & NavChildren;
-
-// `.strict()` on every variant is load-bearing, not decoration: Zod
-// objects silently strip unrecognized keys by default, so without it a
-// node written with two children fields at once (e.g. both `pages` and
-// `versions`) would just have the second one dropped instead of
-// rejected - defeating the entire "exactly one child kind per level"
-// rule this schema exists to enforce (mirroring Mintlify's own "a tab
-// cannot contain both anchors and groups at the same level").
-function withChildren<Base extends z.ZodRawShape>(base: Base) {
-  return z.union([
-    z.object({ ...base, pages: z.array(navItemSchema) }).strict(),
-    z.object({ ...base, tabs: z.array(tabSchema).min(1) }).strict(),
-    z.object({ ...base, versions: z.array(versionSchema).min(1) }).strict(),
-    z.object({ ...base, languages: z.array(languageSchema).min(1) }).strict(),
-    z.object({ ...base, dropdowns: z.array(dropdownSchema).min(1) }).strict(),
-    z.object({ ...base, products: z.array(productSchema).min(1) }).strict(),
-    z.object({ ...base, href: z.string() }).strict(),
-  ]);
-}
-
-// Each of these five is defined via z.lazy() because withChildren()
-// references all five by name (mutual recursion) - safe because none of
-// them are actually *called* until a real writedocs.json is parsed, by which
-// point every const below has been assigned. The same pattern already
-// used for navItemSchema/navGroupSchema above.
-const tabSchema: z.ZodType<TabItem> = z.lazy(() =>
-  withChildren({ tab: z.string(), icon: z.string().optional() })
-);
-
-const versionSchema: z.ZodType<VersionItem> = z.lazy(() =>
-  withChildren({
-    version: z.string(),
-    label: z.string().optional(),
-    tag: z.string().optional(),
-    default: z.boolean().optional(),
-  })
-);
-
-const languageSchema: z.ZodType<LanguageItem> = z.lazy(() =>
-  withChildren({ language: z.string(), label: z.string().optional() })
-);
-
-const dropdownSchema: z.ZodType<DropdownItem> = z.lazy(() =>
-  withChildren({ dropdown: z.string(), icon: z.string().optional() })
-);
-
-const productSchema: z.ZodType<ProductItem> = z.lazy(() =>
-  withChildren({ product: z.string(), icon: z.string().optional(), description: z.string().optional() })
-);
-
-// ---------------------------------------------------------------------
-// Root navigation: a flat array (shorthand for one implicit section - the
-// common case) or an object choosing exactly one primary organizational
-// pattern, per Mintlify's convention ("choose one primary organizational
-// pattern at the root level of your navigation").
-//
-// `global.dropdowns` is the one exception to "exactly one pattern": it's
-// not a primary pattern, it's a persistent set of topbar dropdown
-// triggers that render on every page regardless of which tab/version/
-// language/product is active - equivalent to Mintlify's
-// `navigation.global.anchors`. This replaces the earlier `{tabs,
-// dropdowns}` shape (both present at once), which doesn't generalize
-// once versions/languages/products are also root-level choices.
-// ---------------------------------------------------------------------
-
-export type NavigationConfig =
-  | NavItem[]
-  | { global?: { dropdowns: DropdownItem[] }; tabs: TabItem[] }
-  | { global?: { dropdowns: DropdownItem[] }; versions: VersionItem[] }
-  | { global?: { dropdowns: DropdownItem[] }; languages: LanguageItem[] }
-  | { global?: { dropdowns: DropdownItem[] }; dropdowns: DropdownItem[] }
-  | { global?: { dropdowns: DropdownItem[] }; products: ProductItem[] };
-
-const globalSchema = z.object({ dropdowns: z.array(dropdownSchema).min(1) });
-
-const navigationSchema = z.union([
-  z.array(navItemSchema),
-  z.object({ global: globalSchema.optional(), tabs: z.array(tabSchema).min(1) }).strict(),
-  z.object({ global: globalSchema.optional(), versions: z.array(versionSchema).min(1) }).strict(),
-  z.object({ global: globalSchema.optional(), languages: z.array(languageSchema).min(1) }).strict(),
-  z.object({ global: globalSchema.optional(), dropdowns: z.array(dropdownSchema).min(1) }).strict(),
-  z.object({ global: globalSchema.optional(), products: z.array(productSchema).min(1) }).strict(),
-]) as z.ZodType<NavigationConfig>;
-
-const DEFAULT_PRIMARY = '#6366f1';
-
-// A logo is either one path used for both color modes, or a
-// { light, dark, label } object - each image shown only while that mode
-// is active (see BaseLayout.astro's .wd-logo-light/.wd-logo-dark CSS).
-// The topbar shows *only* the image by default - no site name text next
-// to it, since a real logo asset usually already is a wordmark. `label`
-// is the opt-in way to add text back next to the image (e.g. a product
-// name alongside a symbol-only mark); it only exists on the object form,
-// since a single shared image path is just as easy to bake the label
-// into directly.
-//
-// `light`/`dark` are themselves optional (unlike the string form, which
-// is inherently "both"): a site with no logo *images* at all can still
-// set `styles.logo: { label: "..." }` to override the topbar's fallback
-// text without providing any image - see BaseLayout.astro's
-// hasLogoImage/logoLabel/brandLabel derivation, where an object with
-// only `label` set already resolves correctly (brandLabel = logoLabel,
-// same as if an image were also present) without needing any change
-// there; only this schema needed loosening; light/dark were previously
-// both required whenever the object form was used at all.
-//
-// Standalone const (rather than inlined into stylesSchema.logo below) so
-// footer.logo further down can share the exact same union instead of an
-// independently-written copy - see footerSchema's own comment on why a
-// footer logo needs this at all.
-const logoSchema = z.union([
-  z.string(),
-  z.object({ light: z.string().optional(), dark: z.string().optional(), label: z.string().optional() }).strict(),
-]);
-
-// Same {light, dark}-with-fallback shape applies to `colors.dark`: any
-// of primary/text left unset there falls back to the light-mode value
-// already given above, so a site only has to specify what actually
-// differs in dark mode. There used to be a `background`/`dark.background`
-// pair here too, doing effectively the same job as `background.colors`
-// further down (see that field's own comment) - two writedocs.json fields
-// both named "background" that visually looked interchangeable but
-// weren't quite (one drove --wd-background site-wide, the other only
-// the <body> canvas), which was confusing to author against and easy to
-// half-configure by setting only one. Removed in favor of `background`
-// alone being the single place to set any background color - see that
-// field's comment for what it now covers.
-// One side of `styles.navbar` (light or dark) - either a bare background
-// color (the original shape) or `{ background, accent? }` once a site
-// wants its own accent color (the active-tab fill / hover underline)
-// inside the navbar specifically, independent of the sitewide
-// `styles.colors.primary`. Deliberately does NOT carry a text/icon color
-// field at all - see `navbar`'s own comment below (stylesSchema) for why
-// that's resolved automatically instead of being configurable. Kept as a
-// standalone const rather than inlined so `light`/`dark` share the exact
-// same union rather than two independently-written (and possibly
-// drifting) copies of it.
-const navbarColorValueSchema = z.union([
-  z.string(),
-  z
-    .object({
-      background: z.string(),
-      accent: z.string().optional(),
-    })
-    .strict(),
-]);
-
-// One font declaration - almost exactly Mintlify's own `fonts` shape (see
-// docs/dev/docs/site-config.mdx's own "Fonts" section for the research this
-// was based on): a bare Google Fonts family name (`family` alone - Google
-// Fonts loads it automatically, see googleFontsHref() below), or a local/
-// externally-hosted font file (`source` + `format` together; `source` is
-// either a project-relative path like the other five asset-fallback fields
-// this schema already has - see collectConfiguredAssetPaths() - or a full
-// https:// URL to an externally-hosted font). `weight` does two things at
-// once, both driven by BaseLayout.astro: it narrows which file actually
-// loads (folded into the Google Fonts URL's `:wght@` axis, or the
-// generated `@font-face` rule's own `font-weight` descriptor for a
-// `source` font - see googleFontsHref()/fontFaceRule() below), *and* it's
-// applied as a real CSS `font-weight` on h1-h6 (for `heading`) or `body`
-// (for `body`) - see BaseLayout's own `wdFontWeightHeading`/
-// `wdFontWeightBody`. Both halves matter: loading only the 400-weight file
-// while leaving h1-h6 at the browser's UA-default `font-weight: bold`
-// faux-bolds that file back to looking bold anyway, with no visible
-// change from configuring a lighter weight at all - the bug this second
-// half fixes (caught from real user-reported behavior, not anticipated
-// up front). Left unset anywhere in `styles.fonts` renders no font-weight
-// rule at all, keeping today's plain browser-default bold headings/normal
-// body text unchanged for a site that hasn't touched this field.
-const fontVariantSchema = z
-  .object({
-    family: z.string(),
-    weight: z.number().optional(),
-    source: z.string().optional(),
-    format: z.enum(['woff', 'woff2']).optional(),
-  })
-  .strict();
-
-export type FontVariant = z.infer<typeof fontVariantSchema>;
-
-// The top-level shape adds `heading`/`body`: each independently optional,
-// each falling back to the top-level family/weight/source/format when
-// unset (see resolveFonts() below) - so a site can set one font for
-// everything (`fonts.family` alone), or split headings and body text
-// without needing to repeat itself for whichever side isn't changing.
-const fontsSchema = z
-  .object({
-    family: z.string(),
-    weight: z.number().optional(),
-    source: z.string().optional(),
-    format: z.enum(['woff', 'woff2']).optional(),
-    heading: fontVariantSchema.optional(),
-    body: fontVariantSchema.optional(),
-  })
-  .strict();
-
-export type FontsConfig = z.infer<typeof fontsSchema>;
-
-const stylesSchema = z
-  .object({
-    colors: z
-      .object({
-        primary: z.string().default(DEFAULT_PRIMARY),
-        text: z.string().optional(),
-        dark: z
-          .object({
-            primary: z.string().optional(),
-            text: z.string().optional(),
-          })
-          .optional(),
-      })
-      .default({ primary: DEFAULT_PRIMARY }),
-    logo: logoSchema.optional(),
-    favicon: z.string().optional(),
-    // No default value here (unlike `colors.primary`'s DEFAULT_PRIMARY) -
-    // resolveFonts() below is where "Inter" actually gets applied as the
-    // site-wide default whenever this field is left unset entirely, so
-    // that fallback lives in one place alongside the rest of the
-    // resolution logic rather than being duplicated as a schema default
-    // *and* a resolver fallback.
-    fonts: fontsSchema.optional(),
-    // The Shiki theme *name* (not a full theme object/JSON - see
-    // https://shiki.style/themes for the built-in list) each fenced
-    // (```) MDX code block, and the API playground's request/response
-    // snippets, use in light/dark mode - read out of writedocs.json by both
-    // astro.config.mjs (Shiki's dual-theme markdown config) and
-    // ApiReferencePanel.astro (its own separate <Code/> usages, which
-    // don't inherit markdown.shikiConfig) via resolveCodeblockTheme()
-    // below, the single source of truth for the 'github-light'/
-    // 'github-dark' fallback. Left per-key optional (not defaulted in
-    // the schema itself) so a site can override just one side (e.g.
-    // only `dark`) and still get the ordinary default for the other.
-    codeblocks: z
-      .object({
-        light: z.string().optional(),
-        dark: z.string().optional(),
-        // Maps a fenced (```) block's own language tag to whichever real
-        // Shiki grammar actually highlights it, before that tag ever
-        // reaches Shiki - see resolveCodeblockLangAlias() below for the
-        // one built-in entry (mdx -> jsx) this ships with by default and
-        // why. A site can add its own entries for any other language tag
-        // that either doesn't tokenize well under its own grammar, or
-        // that a site wants to write under a shorter/friendlier fence tag
-        // than Shiki's own bundled id (e.g. `groovy: 'java'` for a close-
-        // enough approximation Shiki doesn't ship a dedicated grammar for
-        // at all) - merged with, not replacing, the built-in default, so
-        // adding one of a site's own doesn't require re-declaring mdx.
-        langAlias: z.record(z.string(), z.string()).optional(),
-      })
-      .strict()
-      .optional(),
-    // The topbar's own background, independent of `background` below (the
-    // page's) - a site may want its navbar to stand out (a dark or
-    // brand-colored bar over a light page) rather than blend into the
-    // page, which is the default when this is left unset. Same {light,
-    // dark} shape (and same per-key-optional, not defaulted here) as
-    // `codeblocks` right above, rather than nested under `colors` - it's a
-    // topbar-specific override, not a third general-purpose page color, so
-    // it reads more like "one more themed surface" alongside codeblocks
-    // than a sibling of primary/text. BaseLayout.astro's own
-    // lightNavbarBg/darkNavbarBg resolution is what falls each side back
-    // to the page background when unset.
-    //
-    // Each side (`light`/`dark`) is either a bare string - just the
-    // background color, exactly the original shape, kept for backwards
-    // compatibility - or `{ background, accent? }`, for when a site also
-    // wants the navbar's own active-tab-fill/hover-underline color to
-    // differ from the sitewide `styles.colors.primary` (`accent`'s only
-    // job - see BaseLayout.astro's lightNavbarAccent). Deliberately no
-    // text/icon color field here at all: BaseLayout.astro always resolves
-    // the navbar's plain text/icon color itself, picking black or white by
-    // contrast against whatever `background` resolves to
-    // (contrastTextColor() below) the moment this field is configured at
-    // all (string or object) - never a value read from writedocs.json. A
-    // manually-set text color is a legibility footgun a site author can
-    // get wrong (or drift out of sync after later changing `background`
-    // without remembering to update it too) in a way "compute it
-    // correctly, every time" simply can't - there's no legitimate reason
-    // to want *illegible* navbar text, unlike `accent`, which is a real
-    // aesthetic choice. Real bug this fixes: a site setting `navbar.light`
-    // to the same value as `colors.primary` (a plausible thing to reach
-    // for - "brand-colored navbar") made every topbar label/icon/link
-    // render in the default near-black text color against that same
-    // saturated background, all but unreadable - and an earlier version of
-    // this feature that let a writedocs.json-supplied color double as the text
-    // color reintroduced the identical bug one level down, just requiring
-    // one more (still guessable-wrong) field to trigger it.
-    navbar: z
-      .object({
-        light: navbarColorValueSchema.optional(),
-        dark: navbarColorValueSchema.optional(),
-      })
-      .strict()
-      .optional(),
-    // The single place to configure any background color: `colors` is a
-    // solid color (falls back to '#ffffff'/'#0b1120' when unset - see
-    // BaseLayout.astro's lightBackground/darkBackground resolution), and
-    // `images` layers an image on top of it (or is the whole background
-    // by itself, if `colors` is left at its default). This one pair now
-    // drives everything background-related site-wide - --wd-background
-    // (dropdowns/modals/kbd chips/footer/topbar-fallback/etc., see every
-    // `var(--wd-background)` call site) *and* the <body> canvas behind the
-    // main/toc columns - rather than the two being independently
-    // configurable fields that happened to look alike but didn't affect
-    // the same things (see this schema's own comment on `colors.dark`
-    // above for why that split was removed). Both are per-mode optional,
-    // same "only specify what differs" pattern as codeblocks/navbar above.
-    // The topbar and footer still get their own explicit opaque
-    // background (topbar.css/footer.css) specifically so an `images`
-    // background doesn't show through them; see those files' own
-    // comments. The sidebar column has no background of its own (base.css)
-    // and lets it show through, same as the main/toc columns.
-    background: z
-      .object({
-        colors: z
-          .object({
-            light: z.string().optional(),
-            dark: z.string().optional(),
-          })
-          .strict()
-          .optional(),
-        images: z
-          .object({
-            light: z.string().optional(),
-            dark: z.string().optional(),
-          })
-          .strict()
-          .optional(),
-      })
-      .strict()
-      .optional(),
-  })
-  .default({ colors: { primary: DEFAULT_PRIMARY } });
-
-// `href` is always required - a link with nowhere to go isn't a link.
-// `label`/`icon` are each individually optional, but not both at once
-// (enforced by the .refine() below, same shape as scriptEntrySchema's own
-// exactly-one-of check above) - a link needs *something* visible to render,
-// whichever of the two, and can have both (icon rendered to the left of the
-// label - see TopBar.astro/SiteFooter.astro, the two renderers of this
-// shape). An icon-only link (no label) is the common case for something
-// like a bare GitHub mark in the topbar; label-only (no icon) is every
-// plain text link this already supported before `icon` existed - both
-// still need to keep working unchanged, hence neither field being outright
-// required on its own.
-const topbarLinkSchema = z
-  .object({
-    label: z.string().optional(),
-    href: z.string(),
-    // Same string shape as every other writedocs.json `icon` field (a plain
-    // Lucide name, or the explicit "collection:icon-name" form for
-    // anything else - see resolveIcon()/AppIcon.astro) - not documented
-    // again here since that convention is already established elsewhere
-    // in this file (tabs/switchers/socials all take the identical shape).
-    icon: z.string().optional(),
-  })
-  .strict()
-  .refine((link) => Boolean(link.label) || Boolean(link.icon), {
-    message: 'Each topbar.links/footer column link needs a "label", an "icon", or both - a link with neither has nothing to render.',
-  });
-
-// One column of the footer (BaseLayout.astro's <footer class="wd-footer">) -
-// an optional heading (e.g. "Resources", "Community") plus a list of links,
-// reusing the exact same {label, icon, href} shape as topbar.links above (a
-// footer link is the same thing rendered in a different place, no reason
-// for a second, identical-but-differently-named schema). `title` is
-// optional so a single-column footer with no heading (just a bare list of
-// links) is valid too.
-const footerColumnSchema = z
-  .object({
-    title: z.string().optional(),
-    links: z.array(topbarLinkSchema).default([]),
-  })
-  .strict();
-
-// Off by default (empty `columns`, same convention as `topbar` above - a
-// footer with nothing configured just doesn't render at all, see
-// BaseLayout.astro's `hasFooterContent` check) rather than `.optional()`
-// like contextMenu: unlike that field, an empty/default footer has no
-// build-output or routing implications to gate, it's purely visual, so
-// there's no reason to distinguish "unset" from "set to nothing" the way
-// contextMenu needs to.
-// Same {light, dark, label} union as `styles.logo` (via the shared
-// logoSchema above) - unset by default, in which case the footer just
-// shows the sitewide `styles.logo` (BaseLayout.astro's existing
-// logoLight/logoDark/logoLabel, already threaded into SiteFooter as-is).
-// Set here, it replaces that entirely rather than filling in only the
-// missing side of it - a footer.logo with only `dark` set shows *just*
-// the dark-mode image, not styles.logo's light image plus this dark one -
-// the same all-or-nothing-relative-to-styles.logo resolution BaseLayout.astro
-// already applies.
-const footerSchema = z
-  .object({
-    columns: z.array(footerColumnSchema).default([]),
-    logo: logoSchema.optional(),
-  })
-  .strict()
-  .default({ columns: [] });
-
-export type FooterColumn = z.infer<typeof footerColumnSchema>;
-export type FooterConfig = z.infer<typeof footerSchema>;
-
-// Shared by both writedocs.json's top-level `seo` (site-wide defaults) and a
-// page's own frontmatter `seo` (per-page overrides) - see
-// content.config.ts's docsSchema, which imports this exact schema rather
-// than redeclaring the same shape a second time. mergeSeo() below is what
-// actually combines the two, field by field, at render time.
-export const seoFieldsSchema = z
-  .object({
-    // Open Graph / Twitter card image - a relative path (resolved against
-    // `domain` below into an absolute URL, since most social crawlers
-    // require one) or an already-absolute https:// URL.
-    ogImage: z.string().optional(),
-    // og:type - "website" for most pages, "article" for blog-post-shaped
-    // content, etc. Defaults to "website" if never set anywhere.
-    ogType: z.string().optional(),
-    twitterCard: z.enum(['summary', 'summary_large_image']).optional(),
-    keywords: z.array(z.string()).optional(),
-    // Renders <meta name="robots" content="noindex, nofollow" /> and
-    // (see astro.config.mjs's sitemap `filter`) excludes the page from
-    // sitemap.xml entirely - both driven off this one flag, since listing
-    // a page in the sitemap while also telling crawlers not to index it
-    // would be self-contradictory.
-    noindex: z.boolean().optional(),
-  })
-  .strict();
-
-export type SeoFields = z.infer<typeof seoFieldsSchema>;
-
-/** Field-by-field merge of a page's own `seo` frontmatter over writedocs.json's
- *  site-wide `seo` defaults - a page only overrides the specific fields it
- *  sets, falling back to the site default for everything else, rather than
- *  a page's (possibly partial) `seo` object replacing the site's wholesale. */
-export function mergeSeo(site: SeoFields, page?: SeoFields): SeoFields {
-  if (!page) return site;
-  return {
-    ogImage: page.ogImage ?? site.ogImage,
-    ogType: page.ogType ?? site.ogType,
-    twitterCard: page.twitterCard ?? site.twitterCard,
-    keywords: page.keywords ?? site.keywords,
-    noindex: page.noindex ?? site.noindex,
-  };
-}
-
-// Controls for the OpenAPI API playground's "Try it" modal - separate
-// from a group's own `openapi: { src, path }` field (which spec to use,
-// and where) since this is about how a *request* it sends behaves, not
-// about the spec itself.
-const apiSchema = z
-  .object({
-    // Whether the Try-it modal's Send button routes its request through
-    // writedocs' own CORS proxy (https://proxy.writechoice.io/) rather
-    // than calling the API directly from the browser. Almost no
-    // real-world API sends back Access-Control-Allow-Origin headers
-    // permitting an arbitrary docs site's origin, so a direct browser
-    // fetch() from the Try-it modal fails for most real APIs without
-    // this - see PROXY_BASE_URL in ApiReferencePanel.astro for the
-    // actual request-forwarding logic. Defaults to enabled; a site can
-    // set this to `false` to always call the API directly instead (the
-    // API is already CORS-permissive, same-origin in some deployments,
-    // or the site owner doesn't want requests routed through a third
-    // party at all).
-    proxy: z.boolean().default(true),
-  })
-  .strict()
-  .default({ proxy: true });
-
-// The "Copy page" dropdown shown next to a page's title - copy the raw
-// Markdown to the clipboard, open the raw Markdown in a new tab, or
-// deep-link into an AI assistant with a prompt pointing at it. Opt-in:
-// undefined (the field simply absent from writedocs.json) means the feature
-// is off entirely - no menu rendered, no .md routes generated at build
-// time either (see [...slug].md.ts) - rather than defaulting to on,
-// since it changes both the UI and the build output. Once a site does
-// write a `contextMenu` key (even `{}`), copying/viewing-as-Markdown are
-// always included (they need nothing but the page's own content); only
-// `openIn` (the AI-assistant deep-links, which need an absolute URL to
-// point the assistant at) is independently configurable.
-const contextMenuSchema = z
-  .object({
-    openIn: z.array(z.enum(['chatgpt', 'claude', 'perplexity'])).default(['chatgpt', 'claude', 'perplexity']),
-  })
-  .strict();
-
-export type ContextMenuConfig = z.infer<typeof contextMenuSchema>;
-
-// One entry in writedocs.json's `redirects` array - wired almost directly into
-// Astro's own `redirects` config option (astro.config.mjs), which is what
-// actually generates the redirect pages. `permanent` is deliberately not
-// part of this schema: with no server/adapter (this project always builds
-// `output: 'static'` with none installed), Astro's own docs say a static
-// redirect "does not support status codes" at all - it's always a client-
-// side `<meta http-equiv="refresh">` page, full stop. Accepting a
-// `permanent` field here that silently did nothing would be worse than
-// not offering it.
-const redirectSchema = z
-  .object({
-    source: z.string(),
-    destination: z.string(),
-  })
-  .strict();
-
-export type RedirectConfig = z.infer<typeof redirectSchema>;
-
-// A site-wide banner rendered above the topbar on every page (except
-// `mode: blank`, which drops all site chrome including this - see
-// BaseLayout.astro). Optional/undefined by default, same convention as
-// `contextMenu` above - a site with no banner configured gets no banner
-// markup at all, not an empty one.
-const bannerSchema = z
-  .object({
-    content: z.string(),
-    // Persisted via localStorage once dismissed (see BaseLayout.astro's
-    // initBanner()) - a static site has no server-side session to track
-    // this against, so "dismissed" only ever means "dismissed in this
-    // browser". A banner without `dismissible` reappears on every visit,
-    // appropriate for something that should stay visible until the site
-    // author removes it from writedocs.json themselves (e.g. "this version is
-    // deprecated"), not something a reader can permanently clear.
-    dismissible: z.boolean().default(false),
-    type: z.enum(['info', 'warning', 'critical']).default('info'),
-  })
-  .strict();
-
-export type BannerConfig = z.infer<typeof bannerSchema>;
-
-// Content for the custom 404 page (src/pages/404.astro) - Astro's own
-// file-based convention (a static build emits this as 404.html at the
-// site root; most static hosts pick it up automatically for unmatched
-// routes). Both fields are optional with hardcoded fallbacks in 404.astro
-// itself, so a site doesn't have to set either to get a reasonably
-// branded 404 page (still rendered inside the normal BaseLayout/topbar
-// chrome, just with placeholder content).
-const notFoundSchema = z
-  .object({
-    title: z.string().optional(),
-    description: z.string().optional(),
-  })
-  .strict()
-  .default({});
-
-export type NotFoundConfig = z.infer<typeof notFoundSchema>;
-
-// One <script> tag to inject - exactly one of `src` (an external/local
-// file, rendered as `<script src="...">`) or `content` (inline JS,
-// rendered via `<script is:inline set:html="...">`) has to be set, not
-// both and not neither - enforced by the `.refine()` below rather than
-// leaving both optional and silently rendering an empty tag if a site
-// author gets this wrong.
-const scriptEntrySchema = z
-  .object({
-    src: z.string().optional(),
-    content: z.string().optional(),
-  })
-  .strict()
-  .refine((v) => (v.src ? !v.content : !!v.content), {
-    message: 'Each scripts.head/scripts.body entry needs exactly one of "src" or "content", not both or neither.',
-  });
-
-export type ScriptEntry = z.infer<typeof scriptEntrySchema>;
-
-// Raw third-party script injection - analytics snippets, chat widgets,
-// anything that needs a real <script> tag writedocs.json's own structured
-// fields (styles, integrations-style config, ...) don't have a dedicated
-// slot for yet. `head` renders right before </head>; `body` renders right
-// before </body> (after everything else has already loaded/hydrated -
-// see BaseLayout.astro), matching where a third-party script's own
-// install instructions usually say to put it.
-const scriptsSchema = z
-  .object({
-    head: z.array(scriptEntrySchema).default([]),
-    body: z.array(scriptEntrySchema).default([]),
-  })
-  .strict()
-  .default({ head: [], body: [] });
-
-export type ScriptsConfig = z.infer<typeof scriptsSchema>;
-
-// writedocs.json's `integrations` - a curated, high-value subset of analytics
-// providers, each getting its own minimal config object (just the id(s)
-// it actually needs) rather than requiring a site author to hand-write
-// the provider's own install snippet through the generic `scripts` field
-// above. This is deliberately its own thing, not built as sugar over
-// `scripts` the way the roadmap once implied it might be - most of these
-// providers' real snippets need `defer`/`async`/`data-*` attributes
-// ScriptEntry's plain `{ src?, content? }` shape has no way to express,
-// so BaseLayout.astro renders each provider with its own bespoke markup
-// instead of generating a ScriptEntry array to feed through the generic
-// renderer. Every snippet shape below was sourced from that provider's
-// own current official docs (fetched directly, not recalled from
-// training data) while building this feature - see
-// docs/dev/docs/integrations.mdx for links and dates.
-//
-// Every provider field is optional and independent - a site can turn on
-// any subset (including all of them at once, for a migration period) or
-// none. No "the" analytics field; a site picks whichever provider(s) it
-// actually uses.
-
-const ga4IntegrationSchema = z
-  .object({
-    // A GA4 "Measurement ID", always shaped like "G-XXXXXXXXXX" - not
-    // validated against that shape here, since Google could change the
-    // prefix/length without this schema needing to track it.
-    measurementId: z.string(),
-  })
-  .strict();
-
-const googleTagManagerIntegrationSchema = z
-  .object({
-    // A GTM container id, shaped like "GTM-XXXXXXX".
-    containerId: z.string(),
-  })
-  .strict();
-
-const plausibleIntegrationSchema = z
-  .object({
-    domain: z.string(),
-    // Plausible's own hosted script URL by default - override for a
-    // self-hosted instance, a reverse-proxy path (Plausible's own
-    // documented way to dodge ad-blockers), or one of Plausible's
-    // documented script *extensions* (e.g.
-    // "https://plausible.io/js/script.hash.outbound-links.js").
-    src: z.string().default('https://plausible.io/js/script.js'),
-  })
-  .strict();
-
-const fathomIntegrationSchema = z
-  .object({
-    // Fathom's own short "Site ID", not a full URL or measurement id.
-    siteId: z.string(),
-  })
-  .strict();
-
-const posthogIntegrationSchema = z
-  .object({
-    // PostHog calls this a "project API key" (starts with "phc_") in its
-    // own docs - `apiKey` here rather than that exact name, matching this
-    // schema's own plainer naming convention for the equivalent id on
-    // every other provider above.
-    apiKey: z.string(),
-    // PostHog is region-sharded (US/EU) with no single universal default
-    // - "https://us.i.posthog.com" is PostHog's own default for a new
-    // project, but a site on their EU cloud (or a self-hosted instance)
-    // must override this to the host shown in their own project
-    // settings, or events silently go nowhere.
-    apiHost: z.string().default('https://us.i.posthog.com'),
-  })
-  .strict();
-
-const umamiIntegrationSchema = z
-  .object({
-    websiteId: z.string(),
-    // Unlike Plausible/PostHog, Umami has no single hosted default that
-    // works for most users - it's commonly self-hosted, and even Umami
-    // Cloud users get a per-region script URL. Defaults to Umami Cloud's
-    // own documented script URL, which only happens to be correct for a
-    // Cloud user on that specific region; anyone self-hosting (the more
-    // common case for this particular provider) must override it to
-    // their own instance's own /script.js path.
-    src: z.string().default('https://cloud.umami.is/script.js'),
-  })
-  .strict();
-
-// AI chat over the site's own docs content, via a third-party provider
-// (DocsBot, currently the only one wired up) rather than a self-hosted
-// RAG pipeline - see the roadmap's own "AI chat over docs content" line
-// in docs/dev/docs/roadmap.mdx, which this fulfills via integration
-// rather than by building the retrieval/generation stack in-house.
-// Deliberately named `askAi` here, not `docsbot` - this is the
-// writedocs.json-facing, provider-neutral name for the feature (matching
-// the "Ask AI" label this kind of button/widget is conventionally
-// given in docs sites generally), independent of which vendor happens
-// to sit behind it today. `id` matches DocsBot's own embed config
-// field name exactly (`DocsBotAI.init({ id: 'teamId/botId' })`) - it's
-// a single opaque "teamId/botId" string DocsBot treats as one value,
-// not two separate ids, so this schema doesn't split it either.
-const askAiIntegrationSchema = z
-  .object({
-    id: z.string(),
-  })
-  .strict();
-
-const integrationsSchema = z
-  .object({
-    ga4: ga4IntegrationSchema.optional(),
-    googleTagManager: googleTagManagerIntegrationSchema.optional(),
-    plausible: plausibleIntegrationSchema.optional(),
-    fathom: fathomIntegrationSchema.optional(),
-    posthog: posthogIntegrationSchema.optional(),
-    umami: umamiIntegrationSchema.optional(),
-    askAi: askAiIntegrationSchema.optional(),
-  })
-  .strict()
-  .default({});
-
-export type IntegrationsConfig = z.infer<typeof integrationsSchema>;
-
-export const docsConfigSchema = z.object({
-  name: z.string(),
-  description: z.string().optional(),
-  styles: stylesSchema,
-  navigation: navigationSchema,
-  // Platform name -> profile/page URL (e.g. `{ "github": "https://
-  // github.com/...", "twitter": "https://twitter.com/..." }`), free-form
-  // rather than an enum of known platforms - the key doubles as the icon
-  // reference BaseLayout.astro's footer resolves via resolveIcon() below
-  // (bare `"github"` -> `lucide:github`; use an explicit
-  // `"simple-icons:whatever"` key instead when the bare lucide name isn't
-  // right for a given platform). Rendered as a row of icon links in the
-  // footer - see hasFooterContent/`.wd-footer-socials` in BaseLayout.astro.
-  socials: z.record(z.string(), z.string()).default({}),
-  topbar: z
-    .object({ links: z.array(topbarLinkSchema).default([]) })
-    .default({ links: [] }),
-  // Columns of links below the page content - see footerSchema/
-  // footerColumnSchema above. Renders alongside `socials` above (as a row
-  // of icon links) in the same <footer> - see BaseLayout.astro.
-  footer: footerSchema,
-  api: apiSchema,
-  // The site's own deployed domain, e.g. "docs.example.com" or
-  // "https://docs.example.com" (the scheme is optional - resolveSiteUrl()
-  // below normalizes either form to a full https:// origin). Powers three
-  // things that all need an absolute origin to work: sitemap.xml
-  // generation (astro.config.mjs only registers @astrojs/sitemap when this
-  // is set - a sitemap of relative URLs isn't meaningful), the canonical
-  // <link> and og:url/twitter meta tags (BaseLayout.astro), and resolving
-  // a relative `seo.ogImage` into an absolute URL for social crawlers.
-  // Left optional and simply skipped (with a log message, not an error) at
-  // every one of those call sites when unset - most fixtures/local builds
-  // have no real deployed domain yet.
-  domain: z.string().optional(),
-  // Site-wide meta tag defaults - see seoFieldsSchema above. A page's own
-  // frontmatter `seo` (content.config.ts's docsSchema) overrides these
-  // field by field via mergeSeo(), rather than needing to repeat every
-  // field on every page.
-  seo: seoFieldsSchema.default({}),
-  // The "Copy page" dropdown - see contextMenuSchema above. Absent by
-  // default (no menu, no .md routes).
-  contextMenu: contextMenuSchema.optional(),
-  // See redirectSchema above. Wired directly into Astro's own `redirects`
-  // config option in astro.config.mjs.
-  redirects: z.array(redirectSchema).default([]),
-  // Site-wide `[[key]]` substitution values, applied to page prose text
-  // at build time (see the remarkSubstituteVariables plugin wired into
-  // astro.config.mjs) - e.g. `{ "productName": "Acme" }` lets every page
-  // write `[[productName]]` once instead of hardcoding it everywhere.
-  // Double square brackets, not the more familiar `{{key}}` - MDX
-  // reserves single curly braces for embedded JS expressions, so
-  // `{{productName}}` in an .mdx file parses as a JS object-literal
-  // expression (`{productName}`, shorthand syntax) rather than literal
-  // text, and throws `ReferenceError: productName is not defined` at
-  // render time - see remarkSubstituteVariables' own comment in
-  // mdx-substitute-variables.js for the full explanation. Deliberately a
-  // flat string map, not typed values - this is text substitution into
-  // prose, not a templating language.
-  variables: z.record(z.string(), z.string()).default({}),
-  // See bannerSchema above. Absent by default (no banner rendered).
-  banner: bannerSchema.optional(),
-  // See notFoundSchema above.
-  notFound: notFoundSchema,
-  // See scriptsSchema above.
-  scripts: scriptsSchema,
-  // See integrationsSchema above.
-  integrations: integrationsSchema,
-});
-
-export type DocsConfig = z.infer<typeof docsConfigSchema>;
-
-/** 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.`
-    );
-  }
-  const raw = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
-  const result = docsConfigSchema.safeParse(raw);
-  if (!result.success) {
-    const issues = result.error.issues
-      .map((i) => `  - ${i.path.join('.') || '(root)'}: ${i.message}`)
-      .join('\n');
-    throw new Error(`[writedocs] writedocs.json failed validation:\n${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 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 [];
+}