@dogsbay/format-astro 0.2.0-beta.16 → 0.2.0-beta.161

package/dist/project.d.ts

@@ -1,4 +1,44 @@
 import type { ExportPage, NavItem } from "@dogsbay/types";
+import { type MarkdownStyle } from "@dogsbay/format-dogsbay-md";
+import { type SiteChrome } from "@dogsbay/site-files";
+import { type VersionMenu, type ProductModel } from "@dogsbay/site-files";
+import { type BlogEmitConfig } from "./blog.js";
+import { type RedirectsConfig } from "./redirects.js";
+/**
+ * Astro `outDir` for a Cloudflare Workers deploy mounted on a host subpath.
+ *
+ * Workers Static Assets resolves the FULL request pathname against the
+ * asset manifest and strips nothing. A site mounted at `dogsbay.ai/blog/*`
+ * is therefore asked for `/blog/index.html`, and unless the build output
+ * actually contains `blog/`, every request 404s. Astro's `base` does not
+ * do this: it prefixes generated URLs (including `/blog/_astro/...`) but
+ * leaves the emitted files at `dist/` root. Setting `outDir` to
+ * `./dist<urlBase>` is what makes the two agree.
+ *
+ * GitHub Pages needs the OPPOSITE and must not get this. There the
+ * uploaded artifact IS the site root, served at `https://<user>.github.io/
+ * <repo>/`, so the host supplies the prefix: URLs must carry it, files
+ * must not. Emitting `outDir` for a Pages build would produce
+ * `/<repo>/<repo>/`. Hence the deploy-target gate — the same `site.url`
+ * deliberately yields different layouts per target.
+ *
+ * Returns `undefined` when the target is not Workers or the site sits at
+ * the host root (no path in `site.url`), which is the common case.
+ */
+export declare function workersSubpathOutDir(deploy: AstroProjectOptions["deploy"], urlBase: string): string | undefined;
+/**
+ * Build the `excludeFromRoutes` predicate.
+ *
+ * Exported because more than one emitter has to agree on which pages
+ * become routes. The blog listed excluded pages as posts, producing index
+ * cards and Newer/Older links to pages that were never emitted — a 404
+ * from the site's own front page.
+ *
+ * A single-segment pattern matches ANY segment (fragment dirs symlink to
+ * many depths in AsciiBinder corpora); a multi-segment pattern matches as
+ * a leading path prefix, so `welcome/_internal` excludes only that tree.
+ */
+export declare function makeSlugExcluder(excludeFromRoutes?: string[]): (slug: string) => boolean;
 export interface AstroProjectOptions {
     siteName?: string;
     theme?: string;
@@ -6,13 +46,78 @@ export interface AstroProjectOptions {
     repoUrl?: string;
     editUri?: string;
     copyright?: string;
+    /**
+     * The site's chrome (@dogsbay/site-files `siteChrome`: logo, colour mode, announcement, header
+     * links, footer columns), written into site.json as `chrome`. With it, `copyright` is inline
+     * Markdown (the agreed rule); without it (legacy callers), copyright stays HTML as given.
+     */
+    chrome?: SiteChrome;
+    /** The chrome's logo files, absolute, checked inside the project by the caller. */
+    chromeLogoFiles?: {
+        light: string;
+        dark?: string;
+    };
+    /** The line under the site name in the sidebar header (`site.tagline`). Default "Documentation". */
+    tagline?: string;
+    /** `content.imageCaptions`: a titled block image is a captioned figure. */
+    imageCaptions?: "title" | false;
+    /** `content.html`: "sanitize" filters raw HTML and directive attributes before serializing (@dogsbay/render-html/sanitize). */
+    html?: "keep" | "sanitize";
+    /**
+     * "Powered by DogsBay" footer attribution. Default ON — an unset value
+     * means true. `poweredBy: false` in dogsbay.config.yml removes it, and
+     * removes it completely: no markup, no link, no trace. See
+     * docs/powered-by.md.
+     */
+    poweredBy?: boolean;
     /**
      * Brand keywords for the site. Emitted into `src/data/site.json`
      * so the `seo/h1-brand-keyword` audit rule can read them.
      */
     brandKeywords?: string[];
+    /**
+     * Site-wide noindex. When true, every emitted page passes
+     * `noindex={true}` to DocsLayout regardless of frontmatter, and
+     * the sitemap emits zero `<url>` entries. Pages can ESCALATE
+     * (frontmatter `noindex: true` still works) but not opt out.
+     * See plans/site-level-robots-meta.md.
+     */
+    noindex?: boolean;
+    /**
+     * Site-wide nofollow. Same one-way semantics as `noindex` — site
+     * forces, page frontmatter `nofollow: true` can escalate but
+     * cannot opt out. Independent of `noindex`.
+     */
+    nofollow?: boolean;
     /** Source project directory (for copying extra_css, assets, etc.) */
     sourceDir?: string;
+    /**
+     * External asset directories mounted into the `_assets` convention. Each
+     * dir's CONTENTS are copied to `public/_assets/` (e.g. a Docusaurus `static/`
+     * dir, whose `/img/x` refs the importer rewrote to `/_assets/img/x`).
+     * `into` targets an `_assets/<into>` subdir; `mediaOnly` copies only media
+     * files (for mounts whose dir is the docs tree itself).
+     */
+    assetMounts?: {
+        dir: string;
+        into?: string;
+        mediaOnly?: boolean;
+        root?: string;
+        skip?: string[];
+    }[];
+    /**
+     * Per-source asset directories with the URL prefix their content refs
+     * were rewritten with. Used by multi-source (versioned/localised) builds
+     * so EACH source's assets are copied under `public/<urlPrefix>/...`
+     * (e.g. `public/8.8/_assets/...`) and same-path images across versions
+     * don't collide. When set, it REPLACES the single-`sourceDir` asset copy
+     * (which only ever copied the first source, version-less). `urlPrefix`
+     * empty/absent copies to `public/...` flat (the baseline source).
+     */
+    assetSourceDirs?: {
+        dir: string;
+        urlPrefix?: string;
+    }[];
     /** Custom CSS files from mkdocs.yml extra_css */
     extraCss?: string[];
     /** Enable Astro image optimization (copies to src/assets/ instead of public/) */
@@ -49,6 +154,8 @@ export interface AstroProjectOptions {
      * `taxonomies.tags.labels`. URLs continue to use slugs.
      */
     tagLabels?: import("@dogsbay/types").SiteConfig["tagLabels"];
+    /** Automatic chip colors. Sourced from `taxonomies.tags.autoColor`. */
+    tagAutoColor?: import("@dogsbay/types").SiteConfig["tagAutoColor"];
     /**
      * Map of taxonomy name → index path, sourced from declared
      * `taxonomies` entries. Lets renderer components surface a link
@@ -63,6 +170,12 @@ export interface AstroProjectOptions {
      * See plans/search-facets.md.
      */
     taxonomyDisplay?: import("@dogsbay/types").SiteConfig["taxonomyDisplay"];
+    /**
+     * Declared taxonomies with `hierarchical: true`: a page's nested value in one
+     * of them is a search facet at every level (`ai/llm` → `ai`, `ai/llm`), as
+     * `pageFacets` (@dogsbay/site-files) maps it for DocsLayout and dogsbay-ssg.
+     */
+    hierarchicalTaxonomies?: string[];
     /** Canonical site URL — required for sitemap.xml + canonical tags */
     siteUrl?: string;
     /** Site-wide description used as default <meta name="description"> */
@@ -91,13 +204,51 @@ export interface AstroProjectOptions {
         id: string;
         label?: string;
         eol?: boolean;
+        prerelease?: boolean;
+        hidden?: boolean;
+        canonical?: "self";
+        noindex?: boolean;
+        sitemap?: boolean;
+        badge?: boolean;
+        path?: "";
     }>;
+    /**
+     * Units whose home has no page, forwarded to their first page (site-files `homeForwards`):
+     * `[from, to]` site paths without the base path, written as redirects.
+     */
+    homeForwards?: Array<[string, string]>;
+    /** Leave out a redirect the build cannot honour, with a warning, instead of failing. */
+    allowBrokenRedirects?: boolean;
+    /**
+     * The version menu's links and limit (`content.versionMenu`, @dogsbay/site-files
+     * version-menu.ts). With a `products:` block each product's comes from the model.
+     */
+    versionMenu?: VersionMenu;
     /**
      * Which version is the default. Marked in switcherMap.json so
-     * the switcher can highlight it; PR 4c wires the default-
-     * version redirect that uses this same field.
+     * the switcher can highlight it, and drives the default-version
+     * redirect middleware. A pre-release version is never the
+     * default (enforced at config load).
      */
     defaultVersion?: string;
+    /**
+     * With a `products:` block: the model from @dogsbay/site-files
+     * (`productModel`). Each product's own versions and default then drive
+     * canonicals, the version switcher (`productVersions`), the forward from
+     * a product's root to its default version, and the data files
+     * `_dogsbay/versions.js` and `<unit home>_dogsbay/pages.js`.
+     */
+    products?: ProductModel;
+    /**
+     * The project's own `_headers` / `_redirects` (from the root of a source served at the site
+     * root): written first, the generated rules after, generated ones they already decide left out
+     * (@dogsbay/site-files host-files.ts, as dogsbay-ssg does). With its own `_redirects` the file is
+     * written whatever `deploy` says, since the project's host reads it.
+     */
+    hostFiles?: {
+        headers?: string;
+        redirects?: string;
+    };
     /**
      * Declared locales for the i18n axis. Same role as
      * `versions` for the locale axis.
@@ -112,12 +263,89 @@ export interface AstroProjectOptions {
      */
     defaultLocale?: string;
     /**
-     * When set, emit a deploy config file + dev dep + script for the
-     * named platform. Only "cloudflare-workers" supported today.
-     * Other adapters (netlify, vercel, gh-pages) follow the same shape;
-     * left unimplemented per Phase 1 scope.
+     * When set, emit deploy artifacts for the named platform.
+     *
+     * - `"cloudflare-workers"` — `wrangler.jsonc` + `wrangler` devDep +
+     *   `deploy` script.
+     * - `"github-pages"` — `.github/workflows/deploy.yml` (Astro →
+     *   `actions/deploy-pages` workflow) + `public/.nojekyll`.
+     *
+     * Both targets scaffold their files write-if-missing — re-running
+     * the build never clobbers an author-edited workflow YAML or
+     * wrangler config.
+     */
+    /**
+     * Other sites on this host whose sitemap / llms.txt this site
+     * aggregates. See `AggregateSource` in `@dogsbay/cli` and
+     * plans/subpath-robots-txt.md.
+     */
+    aggregates?: {
+        name: string;
+        description?: string;
+        url?: string;
+        sitemap?: string;
+        llmsTxt?: string;
+    }[];
+    deploy?: "cloudflare-workers" | "github-pages";
+    /**
+     * `redirects:` from dogsbay.config.yml — source path → target, or an object
+     * with a status. Merged with `redirect:` / `aliases:` page frontmatter and
+     * emitted per deploy target. See plans/redirects-and-aliases.md.
+     */
+    redirects?: RedirectsConfig;
+    /**
+     * Astro `build.inlineStylesheets` policy.
+     *
+     * - `"auto"` (default): inline only stylesheets below 4 KB,
+     *   externalize the rest. Best for multi-page sites.
+     * - `"always"`: inline every stylesheet. Best for single-page
+     *   sites where first-paint latency dominates.
+     * - `"never"`: always externalize. Maximizes cache reuse.
+     *
+     * Mirrors `dogsbay.config.yml`'s `build.inlineStylesheets`. Flows
+     * through `astro.config.dogsbay.mjs` so changes propagate without
+     * a scaffold rebuild. See docs/perf-tuning.md.
+     */
+    inlineStylesheets?: "auto" | "always" | "never";
+    /**
+     * Sidebar navigation render mode.
+     *
+     * - `"client"` (default): emit `<DocsNavClient />` — an empty placeholder
+     *   that a tiny client script hydrates from `/_dogsbay/nav.json`.
+     *   Page HTML stays small regardless of nav size; the nav DOM persists
+     *   across view transitions. Trade-off: no-JS users see no sidebar
+     *   nav, search-engine crawlers reach pages via `sitemap.xml` and
+     *   in-content links rather than the sidebar.
+     * - `"ssr-full"`: render the full nav tree into every page's HTML.
+     *   Best for tiny sites or strict no-JS / SEO contexts.
+     *
+     * See plans/client-rendered-nav.md.
+     */
+    navMode?: "client" | "ssr-full";
+    /**
+     * Table-of-contents placement — forwarded to DocsLayout's `toc` prop.
+     * Mirrors `DogsbayConfig.toc`:
+     * - `"top"` (default) — expandable "On this page" at the top of the
+     *   article; frees the right rail for plugin content (e.g. Ask AI).
+     * - `"popover"` — an "On this page" control in the header.
+     * - `"rail"` — the classic right-hand TOC sidebar. In this mode the rail
+     *   belongs to the TOC, so the `RightRail` plugin region is not emitted.
+     * - `"off"` — no table of contents.
+     */
+    toc?: "top" | "popover" | "rail" | "off";
+    /**
+     * Repo root — the directory containing `dogsbay.config.yml`. The
+     * Astro project (`outputDir`) is typically a subdirectory like
+     * `<projectDir>/astro/`. Deploy artifacts that GitHub Actions
+     * needs at the repo root (`.github/workflows/deploy.yml`) are
+     * written here, while artifacts that ship inside the Astro build
+     * (e.g. `public/.nojekyll`) stay under `outputDir`.
+     *
+     * When unset, defaults to `outputDir` — covers flat-layout flows
+     * (`dogsbay convert --to astro`) where the Astro project IS the
+     * repo. site-init and site-build always pass it explicitly.
      */
-    deploy?: "cloudflare-workers";
+    projectDir?: string;
     /**
      * Overwrite all files including maintainer-customizable scaffold
      * files (theme.css, astro.config.mjs, package.json, site.json,
@@ -143,6 +371,42 @@ export interface AstroProjectOptions {
      * to static `.md` files in `dist/`. Default `true`.
      */
     mdMirror?: boolean;
+    /**
+     * Where links in the Markdown copies (each `.md` and llms-full.txt) go: `html` (default), the
+     * page as the site serves it, so a person follows what an agent quotes; `md`, a page's `.md`
+     * copy (links to anything without one stay as they are). Absolute with `siteUrl`. Same key and
+     * meaning as dogsbay-ssg's `agent.mdMirrorLinks` (plans/md-mirror-links.md).
+     */
+    mdMirrorLinks?: "html" | "md";
+    /** Write llms-full.txt. Default true; off with `mdMirror: false` too (as dogsbay-ssg). */
+    llmsFull?: boolean;
+    /** How the Markdown copies are written: the site's `style:` (dogsbay.config.yml). */
+    markdownStyle?: MarkdownStyle;
+    /**
+     * Granularity views — emit aggregate "single-page" views alongside the
+     * topic-grained pages. Additive: the topic site is unchanged; aggregates
+     * are quarantined (noindex + excludeFromSearch → robots/sitemap/pagefind/
+     * llms all exclude them) and kept out of nav. See plans/granularity-views.md.
+     *
+     * Per-node opt-in via the nav file's `single-page: yes | no | children`
+     * annotation (default "no"). `book: true` is the legacy all-on switch: it
+     * seeds the top-level groups as if each were `single-page: yes`, so a node's
+     * own annotation still overrides. `maxSinglePageMB` (default 3) is a safety
+     * cap — a rollup whose source exceeds it is skipped with a warning instead of
+     * building a multi-minute / multi-MB page. See plans/granularity-views.md and
+     * docs-dev/granularity-book-perf.md.
+     */
+    granularity?: {
+        book?: boolean;
+        maxSinglePageMB?: number;
+    };
+    /**
+     * Blog mode. When set, every emitted page wears `chrome="blog"` (no
+     * sidebar), carries a byline, and takes its prev/next from DATE order
+     * rather than nav order. The reverse-chron index itself is emitted
+     * separately by `emitBlogFiles`. See plans/blog-capability.md.
+     */
+    blog?: BlogEmitConfig;
     /**
      * `Content-Signal` directive for the AI training corpus permission
      * emitted in robots.txt. Default `"no"` — opt out of training by
@@ -160,6 +424,22 @@ export interface AstroProjectOptions {
      * search results emitted in robots.txt. Default `"yes"`.
      */
     aiSearch?: "yes" | "no";
+    /**
+     * Emit the Article 4 reservation-of-rights preamble above the
+     * `Content-Signal` line in robots.txt. Default `false`.
+     * See `CONTENT_SIGNAL_PREAMBLE` in @dogsbay/site-files.
+     */
+    contentSignalPreamble?: boolean;
+    /**
+     * Emit the non-standard `Llms-Txt:` line in robots.txt. Default
+     * `false` — see `AgentConfig.llmsTxtDirective` in `@dogsbay/cli`.
+     */
+    llmsTxtDirective?: boolean;
+    /**
+     * "When to use this" guidance for llms.txt. See
+     * `AgentConfig.llmsWhenToUse` in `@dogsbay/cli`.
+     */
+    llmsWhenToUse?: string;
     /**
      * Per-page LLM action UI ("Copy as markdown", "Open in Claude/
      * ChatGPT/Perplexity/Gemini"). When omitted, the cluster is not
@@ -168,6 +448,46 @@ export interface AstroProjectOptions {
      * See plans/llm-page-actions.md.
      */
     llmActions?: import("@dogsbay/types").SiteConfig["llmActions"];
+    /**
+     * Resolved glyphs for the internal/external link-icon affordance.
+     * Baked into `site.json` as `linkIcons` and consumed by `DocsLayout`.
+     * Omitted when the feature is off. See plans/link-resolution-and-icons.md.
+     */
+    linkIcons?: import("@dogsbay/types").SiteConfig["linkIcons"];
+    /**
+     * Patterns that mark slugs as fragments (no Astro route).
+     * Pages matching any pattern are written to neither
+     * `src/pages/*.astro` nor `src/pages/*.md.ts`. The `.md` source
+     * files remain on disk under `content/` so `{% include %}`
+     * directives in other pages can still resolve them; they just
+     * aren't reachable as URLs.
+     *
+     * Match semantics depend on whether the pattern contains `/`:
+     *   - `"modules"` (single segment) matches ANY path segment of
+     *     the slug equal to "modules" — `modules/foo`,
+     *     `welcome/modules/foo`, `a/b/modules/c` all exclude.
+     *     What AsciiBinder corpora want — fragment dirs symlink
+     *     into section dirs so the same dir name appears at many
+     *     depths.
+     *   - `"foo/bar"` (multi-segment) matches as a leading prefix
+     *     only — `foo/bar` and `foo/bar/baz` exclude, but
+     *     `welcome/foo/bar` does not. For when a specific path
+     *     tree is fragment territory.
+     *
+     * The companion signal — frontmatter `_fragment: true` — is also
+     * honoured (per-page opt-out, set by importers that know which
+     * `.md` files are include-only fragments vs navigable pages —
+     * `migrate-asciidoc` is the first such importer). Either signal
+     * is enough to skip; both stack.
+     *
+     * Typical use case: AsciiBinder-style corpora where shared
+     * fragments live under `modules/`, `_attributes/`, `snippets/`
+     * — the converter writes them as `.md` so includes resolve, but
+     * they have no business being navigable as standalone pages
+     * (and emitting 18k useless routes punishes the Astro compiler).
+     * See plans/build-at-scale.md.
+     */
+    excludeFromRoutes?: string[];
 }
 /**
  * Export pages + nav to a complete Astro project directory.
@@ -204,24 +524,95 @@ export declare function exportAstroProject(pages: ExportPage[], nav: NavItem[],
  * through the full scaffold path. `emitSiteScaffold` also calls it.
  */
 export declare function emitSiteConfig(outputDir: string, siteName: string, options: AstroProjectOptions): void;
+/**
+ * Re-pin an existing site's `@dogsbay/*` dependencies to the building CLI's
+ * version. Safe to call on every build.
+ *
+ * `package.json` is scaffold-once, and for a long time this ran only from
+ * `emitSiteScaffold`, which `site build` never calls — so the guard against
+ * version drift was unreachable from the one command where drift happens.
+ * Measured on openshift-docs-markdown: a site rebuilt weekly for months kept
+ * installing the `@dogsbay/docs-layout` written at its first scaffold, so no
+ * change to a runtime component ever reached it. Its sibling escaped only
+ * because that workflow passes `--force`, which re-scaffolds.
+ *
+ * Returns the changes made, so the caller can report them: a build that
+ * silently edits a tracked file is worse than the drift it fixes.
+ */
+export declare function syncSiteDependencies(outputDir: string, options?: {
+    local?: boolean;
+}): string[];
 export declare function emitSiteScaffold(outputDir: string, siteName: string, options: AstroProjectOptions, writeScaffold: boolean): number;
 /**
- * Emit content-tier files: nav.json, every page's .astro, the per-page
- * .md mirror endpoint (when `mdMirror` is enabled), and the index
- * redirect. Returns the count of pages emitted and the merged nav for
- * downstream consumers (llms.txt builder).
+ * Nav entries come from a project's own TOC files (toctrees, `_toc.yml`,
+ * `myst.yml`, nav.yml), i.e. from content. An href with a scheme other than
+ * http(s)/mailto/tel — `javascript:` above all — is dropped (the entry keeps
+ * its label and children), so it cannot reach the sidebar, nav.json or a
+ * page's previous/next link.
  */
+export declare function dropUnsafeNavHrefs(items: NavItem[]): NavItem[];
 export declare function emitAstroPages(pages: ExportPage[], nav: NavItem[], outputDir: string, options: AstroProjectOptions): Promise<{
     generated: number;
     outputNav: NavItem[];
+    /**
+     * Output paths (relative to outputDir, OS-native separators) of the
+     * `.astro` files just written. Used by passthrough emit to detect
+     * collisions with hand-authored `.astro` files declared in nav.yml
+     * — see plans/passthrough-astro-pages.md.
+     */
+    generatedPaths: Set<string>;
 }>;
+/** Passthrough source → destination pair, computed by the CLI's collector. */
+export interface PassthroughCopy {
+    /** Absolute path to the source file (under contentDir). */
+    sourceAbs: string;
+    /**
+     * Output path relative to outputDir, OS-native separators. Same
+     * shape as `emitAstroPages` `generatedPaths` so the collision
+     * check can use a plain `Set.has`.
+     */
+    outputRelPath: string;
+    /** Source path relative to contentDir, for error messages. */
+    source: string;
+}
+/**
+ * Copy each passthrough `.astro` source to its computed output path.
+ * Aborts with a clear error if the destination is already in
+ * `generatedPaths` (a generated page from `emitAstroPages` would
+ * silently overwrite the hand-authored file otherwise).
+ */
+export declare function emitPassthroughAstroPages(copies: PassthroughCopy[], outputDir: string, generatedPaths: Set<string>): {
+    copied: number;
+};
 /**
  * Emit `public/robots.txt` with `Content-Signal` directives + sitemap
  * link. Always overwrites — the file's contents are pure derivation
  * from `options`. Maintainers wanting custom Disallow rules layer
  * them at the CDN level.
  */
-export declare function emitConfigDerivedFiles(outputDir: string, options: AstroProjectOptions): void;
+export declare function emitConfigDerivedFiles(outputDir: string, options: AstroProjectOptions, pages?: ExportPage[]): void;
+/**
+ * Per-deploy-target artifact emission.
+ *
+ * Called from `emitSiteScaffold` (with `forceOverwrite=writeScaffold`
+ * so `--force` regenerates from template) and from `dogsbay site
+ * build` (with `forceOverwrite=false` so an existing site can adopt
+ * a deploy target by editing config and rebuilding — the missing
+ * artifact gets created on the next build).
+ *
+ * Emit policy is the union: write when forced OR when the file is
+ * missing. Author edits to e.g. the workflow YAML survive every
+ * regular build.
+ *
+ * Currently handles `github-pages` (workflow + .nojekyll). The
+ * existing `cloudflare-workers` artifacts (wrangler.jsonc + package
+ * scripts) stay in the scaffold-only path because they overlap with
+ * scaffold-only files (package.json scripts, devDependencies). A
+ * future refactor could fold them in here too.
+ */
+export declare function emitDeployArtifacts(outputDir: string, options: AstroProjectOptions, opts?: {
+    forceOverwrite: boolean;
+}): void;
 /**
  * Shape of the emitted `src/data/switcherMap.json` file.
  * Switcher components import this JSON directly, so the shape
@@ -251,7 +642,13 @@ export interface SwitcherMap {
         id: string;
         label?: string;
         eol?: boolean;
+        prerelease?: boolean;
+        hidden?: boolean;
         default?: boolean;
+        /** Served at the site root (`path: ""`): its pages have no version segment. */
+        root?: boolean;
+        /** "Version: <label>" above each page's title. */
+        badge?: boolean;
     }>;
     /**
      * Declared locales in declaration order. Same role as
@@ -269,7 +666,67 @@ export interface SwitcherMap {
      * the full URL plus the (locale, version) combo it represents.
      */
     byLogicalKey: Record<string, SwitcherVariant[]>;
+    /**
+     * With a `products:` block: each product's version rows per locale, keyed
+     * `<product|_>/<locale|_>`, in config order, hidden versions left out, each
+     * with its home URL (where the row goes when the page is not in it). The
+     * version switcher uses these instead of `versions`.
+     */
+    productVersions?: Record<string, Array<{
+        id: string;
+        label?: string;
+        eol?: boolean;
+        prerelease?: boolean;
+        default?: boolean;
+        badge?: boolean;
+        home: string;
+    }>>;
+    /**
+     * The version menu's links (hrefs as served, base path included) and limit,
+     * keyed by product name, `_` for the site-wide versions and the unnamed
+     * source. Left out when no menu has any.
+     */
+    versionMenu?: Record<string, {
+        links: Array<{
+            label: string;
+            href: string;
+        }>;
+        limit?: number;
+    }>;
+    /**
+     * With a `products:` block and two or more products: the product menu per
+     * locale (`<locale|_>`), in the block's order, each entry going to the
+     * product's home (its default version, in the locale when it has one) —
+     * site-files `productSwitcher`, as dogsbay-ssg's product menu.
+     */
+    products?: Record<string, Array<{
+        name: string;
+        label: string;
+        home: string;
+    }>>;
+    /**
+     * The version banner each unit's pages carry, keyed by site-files `unitKeyString` (product,
+     * locale, version; just the version for site-wide versions): the version's own text, or a kind
+     * the layout words (older, no longer maintained, not released), and the default version it points
+     * to with its home URL (where the link goes when the page is not in that version). As dogsbay-ssg:
+     * with a `products:` block from site-files `unitOf`; site-wide, an older version only. Left out
+     * when no page has one.
+     */
+    banners?: Record<string, VersionBannerData>;
 }
+/** A unit's version banner in switcherMap.json (site-files `UnitBanner`, `latest.home` as served). */
+export type VersionBannerData = ({
+    kind: "custom";
+    text: string;
+} | {
+    kind: "eol" | "prerelease" | "old";
+}) & {
+    latest?: {
+        id: string;
+        label: string;
+        home: string;
+    };
+};
 export interface SwitcherVariant {
     /** Present when the locale axis is active for this site. */
     locale?: string;
@@ -317,4 +774,36 @@ export declare function emitMissingTranslationStubs(pages: ExportPage[], outputD
  * `emitAstroPages` (they share the page-loop's serialization step).
  */
 export declare function emitAgentReadinessFiles(pages: ExportPage[], outputNav: NavItem[], outputDir: string, siteName: string, options: AstroProjectOptions): void;
-//# sourceMappingURL=project.d.ts.map
+/**
+ * Build the contents of `public/_headers` (Cloudflare Pages / Workers
+ * Static Assets convention). Emits a global RFC 8288 Link header
+ * pointing at this mount's llms.txt index, so agents don't need to
+ * parse HTML to discover the LLM-friendly content listing.
+ *
+ * The Link target is basePath-prefixed (`</docs/llms.txt>` for a
+ * `/docs` mount) — matches where the platform actually emits
+ * llms.txt under the per-mount layout.
+ */
+/**
+ * URL for `<link rel="icon">`, or `false` when the project ships no
+ * favicon.
+ *
+ * The scaffold deliberately ships none — authors drop their own into
+ * `public/`. Emitting the link unconditionally therefore advertised a
+ * 404 on every generated site. Checks `.ico` then `.svg`, matching the
+ * two the scaffold documents.
+ */
+export declare function faviconHref(outputDir: string, urlBase: string): string | false;
+/**
+ * The version served at the site root: the `defaultVersion` when its
+ * `versions` entry has `path: ""` (the CLI's config load allows it on no
+ * other version). Its pages have no version segment.
+ */
+export declare function rootVersionOf(options: Pick<AstroProjectOptions, "versions" | "defaultVersion">): string | undefined;
+/**
+ * Copy the UI component folders the serializer can emit into the site's
+ * `src/components/ui/`, skipping any that exist (project-owned, maybe
+ * edited). Returns the names added. `site build` calls it so a component
+ * introduced in a release (Kbd, FileTree) reaches sites scaffolded earlier.
+ */
+export declare function copyComponents(outputDir: string): string[];