blume 2.1.3 → 2.2.1

package/dist/types/core/directive-diagnostics.d.ts

@@ -1,12 +1,26 @@
 import type { SourceEntry } from "./sources/types.ts";
 import type { Diagnostic } from "./types.ts";
 /**
- * Warn about each `:::name` container in an `.mdx` entry that isn't a callout.
- * The page keeps its content — the body renders between the literal `:::`
- * lines (see `markdown/directives.ts`) — but a typo like `:::warnig`, or a
- * `:::details` carried over from another docs tool, should read as the
- * mistake it is rather than as a finished page. Lines point into the file
- * the author wrote, a partial's own file for a container an `<include>`
- * brought in.
+ * Warn about the `:::` directives in an entry that don't render as their
+ * author meant. In `.mdx`:
+ *
+ * - `BLUME_UNKNOWN_DIRECTIVE`: a `:::name` container that isn't a callout.
+ *   The page keeps its content — the body renders between the literal `:::`
+ *   lines (see `markdown/directives.ts`) — but a typo like `:::warnig`, or a
+ *   `:::details` carried over from another docs tool, should read as the
+ *   mistake it is rather than as a finished page.
+ * - `BLUME_DIRECTIVE_OPENING_TEXT`: a callout opener with text after its
+ *   name, which the page drops (`:::tip Some title`).
+ * - `BLUME_DIRECTIVE_CLOSING_TEXT`: a closing fence with text after it, which
+ *   the page drops (`::: card` inside a `:::warning`).
+ * - `BLUME_DIRECTIVE_SPACED_NAME`: a spaced callout opener (`::: tip`), which
+ *   the page shows as text.
+ *
+ * In `.md`, which renders no directives:
+ *
+ * - `BLUME_MD_DIRECTIVE`: a `:::name` opener, which the page shows as text.
+ *
+ * Lines point into the file the author wrote, a partial's own file for a
+ * directive an `<include>` brought in.
  */
-export declare const unknownDirectiveDiagnostics: (entry: SourceEntry, sourceName: string) => Diagnostic[];
+export declare const directiveDiagnostics: (entry: SourceEntry, sourceName: string) => Diagnostic[];

package/dist/types/core/former-routes.d.ts

@@ -0,0 +1,14 @@
+import type { ResolvedConfig } from "./schema.ts";
+import type { PageRecord } from "./types.ts";
+type Redirect = ResolvedConfig["redirects"][number];
+/**
+ * Redirects from the routes an earlier Blume published pages at
+ * (`PageRecord.formerRoute`) to where they publish now, so a date-named
+ * page's old URL keeps working. None is added where the old URL is still
+ * served (another page, or a custom page, lives there now), where an authored
+ * redirect already starts, or where two pages once resolved to it: that was a
+ * duplicate route, which failed the build, so the URL never served either.
+ * Both ends are written base-less, like authored redirects.
+ */
+export declare const formerRouteRedirects: (pages: readonly PageRecord[], served: ReadonlySet<string>, config: Pick<ResolvedConfig, "basePath" | "redirects">) => Redirect[];
+export {};

package/dist/types/core/github.d.ts

@@ -1,10 +1,11 @@
 /**
  * Repository URL derivation for `config.github`.
  *
- * Every repo-derived link — the header mark, per-page edit links, the agent
- * manifest's `repository` — is built from `host`, which defaults to github.com
- * but accepts a GitHub Enterprise origin so self-hosted and data-resident
- * installations get working links instead of ones pointing at the public site.
+ * Every repo-derived link — the footer's repository link, per-page edit links,
+ * the agent manifest's `repository` — is built from `host`, which defaults to
+ * github.com but accepts a GitHub Enterprise origin so self-hosted and
+ * data-resident installations get working links instead of ones pointing at the
+ * public site.
  *
  * The REST base is derived from the host unless `api` is set explicitly, since
  * the two Enterprise flavors expose it differently: Enterprise Cloud with data

package/dist/types/core/heading-markers.d.ts

@@ -13,7 +13,9 @@
  * Both heading pipelines share this parser — the render-time hast plugin
  * (`markdown/heading-anchors.ts`) and the scan-time source scanner
  * (`core/sources/normalize.ts`) — so the rendered `id`, the TOC entry, and the
- * anchor index `blume validate` checks against always agree.
+ * anchor index `blume validate` checks against always agree. Both also escape
+ * a pinned id's punctuation before they parse (`core/pinned-ids.ts`), so
+ * smart punctuation never rewrites the id an author pinned.
  */
 import type GithubSlugger from "github-slugger";
 /**
@@ -22,6 +24,64 @@ import type GithubSlugger from "github-slugger";
  * `remarkPluginFrontmatter` to filter the TOC.
  */
 export declare const TOC_HIDDEN_KEY = "__blumeTocHidden";
+/**
+ * Frontmatter key carrying TOC text out of a render, keyed by slug, for the
+ * headings whose TOC entry must read differently from the heading's text
+ * content: a heading holding a `<Badge>` lists without the badge's text. The
+ * page template reads it back the way it reads {@link TOC_HIDDEN_KEY}.
+ */
+export declare const TOC_TEXT_KEY = "__blumeTocText";
+/**
+ * A heading's auto-generated anchor id, registered with the document slugger.
+ * The text is trimmed first: a heading that opens or ends with something that
+ * has no text (an inline component, an image, raw HTML) would otherwise slug
+ * that edge whitespace into a leading or trailing dash. A slug can still end
+ * in dashes when the slugger drops a symbol after a space (`Features ✨`);
+ * those go too, so no id ends in a dash.
+ */
+export declare const headingSlug: (slugger: GithubSlugger, text: string) => string;
+/**
+ * A heading's text with its badges taken out. `pieces` is the heading's text
+ * in order, with `null` where a badge stood; a badge between two words
+ * leaves one space, not the two around it (`Install <Badge>beta</Badge> now`
+ * reads `Install now`).
+ */
+export declare const joinHeadingText: (pieces: readonly (string | null)[]) => string;
+/**
+ * How a raw HTML node in a heading reads for its anchor: a `<Badge>` tag that
+ * opens or closes a run of badge text (a self-closing one is a badge with no
+ * text), the opening tag of an `<a>` (`target` its `id`, else its `name`),
+ * the `</a>` that closes one, or none of these.
+ */
+export type RawHeadingTag = {
+    kind: "anchor-close";
+} | {
+    kind: "anchor-open";
+    selfClosing: boolean;
+    target?: string;
+} | {
+    kind: "badge";
+    selfClosing: boolean;
+    closing: boolean;
+} | {
+    kind: "other";
+};
+/** Classify a raw HTML node in a heading — see {@link RawHeadingTag}. */
+export declare const rawHeadingTag: (value: string) => RawHeadingTag;
+/**
+ * A JSX attribute: a name with a string value or an `{expression}` one, or a
+ * `{...spread}` (no name).
+ */
+export interface JsxAttribute {
+    name?: string;
+    type: string;
+    value?: string | {
+        type: string;
+        value?: string;
+    } | null;
+}
+/** A JSX `<a>`'s own fragment target: its string `id`, else its `name`. */
+export declare const jsxAnchorTarget: (attributes: readonly JsxAttribute[]) => string | undefined;
 /**
  * Register a pinned `[#id]` with the document slugger, the way
  * `GithubSlugger#slug` registers the slugs it returns — so a later heading
@@ -32,7 +92,10 @@ export declare const TOC_HIDDEN_KEY = "__blumeTocHidden";
  */
 export declare const occupySlug: (slugger: GithubSlugger, id: string) => void;
 export interface HeadingMarkers {
-    /** Author-pinned anchor id from `[#id]` or `{#id}`, used verbatim (never re-slugged). */
+    /**
+     * Author-pinned anchor id from `[#id]` or `{#id}`, used verbatim (never
+     * re-slugged, and never smart-punctuated: see `core/pinned-ids.ts`).
+     */
     id?: string;
     /** The heading text with every trailing marker stripped. */
     text: string;

package/dist/types/core/hidden-pages.d.ts

@@ -0,0 +1,3 @@
+import type { ContentGraph, PageRecord } from "./types.ts";
+/** Whether a page is hidden from the navigation (see the module comment). */
+export declare const isHiddenPage: (page: PageRecord, graph: ContentGraph) => boolean;

package/dist/types/core/includes.d.ts

@@ -1,3 +1,4 @@
+import type { LinkDefinition } from "./sources/normalize.ts";
 import type { Diagnostic } from "./types.ts";
 /**
  * Cheap pre-filter so include-free content (the overwhelmingly common case)
@@ -116,6 +117,28 @@ export declare const expandIncludes: (body: string, options: {
     /** Raw-file line of `body`'s first line, minus one (default `0`). */
     lineOffset?: number;
 }) => Promise<IncludeExpansion>;
+/**
+ * `text` with each of `definitions` it doesn't define itself appended, so a
+ * reference in it resolves through a definition written elsewhere in the
+ * page (CommonMark definitions are document-wide). Definitions render
+ * nothing; they're left off a text that ends in an open code fence, where
+ * they'd show as code.
+ */
+export declare const withDefinitions: (text: string, definitions: readonly LinkDefinition[]) => string;
+/**
+ * A page's source with the link-reference definitions its included partials
+ * write appended, for the render to parse. Each partial is spliced after the
+ * page is parsed (see `markdown/include.ts`), so a reference in the page
+ * (`[PEP 508]`) to a definition in a partial would otherwise stay text,
+ * though an include reads as if written inline. The definitions come from
+ * the expansion every surface shares, so a partial's definition of a file
+ * beside it is already rebased onto the page. The page's own definition of
+ * a label wins.
+ */
+export declare const withIncludedDefinitions: (body: string, options: {
+    sourcePath: string;
+    contentRoot?: string;
+}) => Promise<string>;
 /**
  * Resolve one include statement to its fully-expanded markdown text — the
  * render plugin's entry point (it finds the statements as AST nodes and only

package/dist/types/core/last-modified.d.ts

@@ -4,13 +4,23 @@ export interface ResolvedLastModified {
     enabled: boolean;
     source: "git" | "frontmatter";
 }
+export declare const gitEnv: () => NodeJS.ProcessEnv;
 /** Normalize the `lastModified` config (`false | "git" | "frontmatter"`) into `{ enabled, source }`. */
 export declare const resolveLastModifiedConfig: (value: false | "git" | "frontmatter") => ResolvedLastModified;
 /**
- * Parse `git log --format=%x00%cI --name-only` output into a map of
- * repo-root-relative path → most recent committer ISO date. Each commit emits a
- * NUL-prefixed date line followed by the paths it touched; since git logs
- * newest-first, the first date seen for a path wins. Blank lines are ignored.
+ * Parse `git log --format=%x00%cI --name-status -M100%` output into a map of
+ * repo-root-relative path → the committer ISO date of the newest commit that
+ * changed the file. Each commit emits a NUL-prefixed date line followed by a
+ * status line per path it touched (`M\tpath`, `R100\told\tnew`); since git
+ * logs newest-first, the first date seen for a path wins. Blank lines are
+ * ignored.
+ *
+ * A rename (`-M100%` reports only exact ones, where the content is unchanged)
+ * follows the file the way `git log --follow` does for one path: it dates
+ * nothing itself, and the older commits that name the old path date the file
+ * under its current name, so renaming `page.md` to `page.mdx` keeps the page's
+ * date. A file whose visible history starts at a rename (a shallow clone cut
+ * off the commits before it) takes the rename's date.
  */
 export declare const parseGitLog: (output: string) => Map<string, string>;
 /**
@@ -33,8 +43,10 @@ export declare const gitRepositoryRoot: (root: string) => string | null;
 /**
  * Resolve each source file's last-modified date from git history, keyed by
  * absolute source path. Runs a single `git log` over the given content roots
- * (each local source's own root, which may diverge from `content.root`)
- * and maps repo-root-relative paths back to the given absolute paths
+ * (each local source's own root, which may diverge from `content.root`),
+ * following renames within them (see `parseGitLog`; a file moved in from
+ * outside every root dates from the move), and maps repo-root-relative paths
+ * back to the given absolute paths
  * (monorepo-safe via `rev-parse --show-toplevel`). Returns an empty map if git
  * is unavailable or the project isn't a repo — the feature then simply shows
  * no dates.

package/dist/types/core/links.d.ts

@@ -22,7 +22,9 @@ export interface RelativeLinkBase {
  * `/install`. A `.md`/`.mdx` target is a file link: `resolveFile` maps its
  * decoded path, relative to the linking file, to the route that file
  * publishes at, so a target with its own `slug` or an ordering prefix still
- * lands on its page instead of on its raw Markdown source. Without
+ * lands on its page instead of on its raw Markdown source. A file renamed
+ * from `.md` to `.mdx`, or back, is found under its other extension first,
+ * so a link written before the rename keeps that slug or prefix. Without
  * `resolveFile`, or for a file it doesn't know, the target resolves
  * route-relative with the extension dropped.
  *
@@ -31,6 +33,23 @@ export interface RelativeLinkBase {
  * name (`./node.js` for `node.js.mdx`, `./v1.2`) is still a page link.
  */
 export declare const resolveRelativeHref: (href: string, from: RelativeLinkBase, resolveFile?: (path: string) => string | undefined, hasRoute?: (route: string) => boolean) => string | undefined;
+/**
+ * Where a root-relative link to a content file (`/guide/new.md`, the way
+ * VitePress, Docsify, and TypeDoc write one) lands: the route of the source
+ * file it names under the content root, with the authored `?query#hash`
+ * kept, or `undefined` when it names no source file (or isn't a root-relative
+ * `.md`/`.mdx` link at all). It's read as written from the content root, or,
+ * when it starts with `deployment.base`, as including the base (see
+ * `withBasePath`). `routeOfFile` maps an absolute source path to the route
+ * that file publishes at. A link that names no source file is left alone:
+ * `/guide/new.md` is also the URL of a page's Markdown copy, which a link may
+ * mean on purpose.
+ */
+export declare const resolveRootFileHref: (href: string, options: {
+    contentRoot: string;
+    deployBase: string;
+    routeOfFile: (file: string) => string | undefined;
+}) => string | undefined;
 /**
  * Whether a content file is its folder's index, from its name as written on
  * disk: `index.md(x)` after an ordering prefix, optionally carrying one of
@@ -92,14 +111,35 @@ export declare const validateLinks: (graph: ContentGraph, options: {
      * full-route-set resolution in `nav-diagnostics.ts`/`generateRuntime`.
      */
     extraRoutes?: string[];
+    /**
+     * The files the build generates beside `public/` (`/llms.txt`,
+     * `/sitemap.xml`; see `deploy/generated-files.ts`), base-less: links to
+     * them resolve like links to `public/` files.
+     */
+    generatedFiles?: string[];
     /** Locale routing when i18n is on; links then resolve into the page's locale. */
     i18n?: LocaleRouting | null;
+    /** The project's `public/` folder, or `null` when it has none (and so
+     * ships no public files). */
     publicDir: string | null;
     checkExternal?: boolean;
     /** External URLs not to request (`--ignore`). Internal links are always checked. */
     ignore?: (url: string) => boolean;
-    /** Configured redirects; their `from` paths count as valid link targets. */
+    /**
+     * Configured redirects: their `from` paths count as valid link targets,
+     * and an internal `to` must land somewhere the site serves.
+     */
     redirects?: {
         from: string;
+        to: string;
     }[];
+    /** The config file the redirects are written in, for their positions. */
+    configFile?: string;
+    /**
+     * The `docs` collection's content root, which a root-relative link to a
+     * content file (`/guide/new.md`) is read from.
+     */
+    contentRoot?: string;
+    /** `deployment.base` (`""` or `/seg`), which such a link may start with. */
+    deployBase?: string;
 }) => Promise<Diagnostic[]>;

package/dist/types/core/load-module.d.ts

@@ -1,8 +1,18 @@
+/**
+ * jiti aliases that resolve `blume` and every subpath it exports to the
+ * running Blume package, read from its own `exports` map. Without them a user
+ * module resolves `blume` by walking up from its own folder, so a `meta.ts`
+ * under a content root outside the project (`content.root: "../docs"`, a
+ * sibling workspace package) or a file `blume.config.ts` imports from beside
+ * the project can't find the `blume` installed in the project. A wildcard
+ * export (`./core/*`) becomes a prefix alias (`blume/core/`), which jiti
+ * extends with the rest of the specifier.
+ */
+export declare const blumeModuleAliases: () => Record<string, string>;
 /**
  * Create a loader for user-authored ESM/TS modules (`blume.config.ts`,
- * `meta.ts`). One jiti instance is reused across every file the returned loader
- * is called with. `moduleCache: false` ensures edits are picked up on each load,
- * which is what makes dev-server regeneration reflect config/meta changes.
+ * `meta.ts`), in which `blume` resolves to the running package wherever the
+ * module lives (see {@link blumeModuleAliases}).
  */
 export declare const createModuleLoader: () => ((file: string) => Promise<unknown>);
 /**
@@ -12,6 +22,11 @@ export declare const createModuleLoader: () => ((file: string) => Promise<unknow
  * exports `null`/`undefined`, resolves to `undefined` so the caller can say
  * so, instead of validating `{}` (a bare `defineConfig({…})` call) or
  * `{ config }` (a named export). jiti's default interop is off because it
- * throws on `export default null`.
+ * throws on `export default null`. Turning it off changes how jiti compiles
+ * every module the config reaches, Blume's own source included, but jiti keys
+ * its disk cache by file and source alone, so this loader keeps a cache of its
+ * own: sharing one, it would run code compiled for {@link createModuleLoader}
+ * (and that loader, code compiled for this one), whichever loaded the file
+ * first.
  */
 export declare const createDefaultExportLoader: typeof createModuleLoader;

package/dist/types/core/manifest.d.ts

@@ -8,7 +8,20 @@ export declare const MANIFEST_VERSION = 1;
  * site search provider is enabled, so features like the MCP server can index
  * docs even when on-page search is off.
  */
-export declare const contentIndexable: (page: PageRecord, config: ResolvedConfig) => boolean;
+export declare const contentIndexable: (page: PageRecord, config: ResolvedConfig, graph: ContentGraph) => boolean;
+/**
+ * Fallback materialization: render the fallback locale's content at the
+ * localized URL for any translation a non-default locale is missing, so static
+ * output is fully prerendered (render-fallback, no client redirect). Fallback
+ * routes are not indexed and carry no `hreflang` of their own.
+ */
+/**
+ * The description a page's `<head>` emits — `seo.description` over the front
+ * matter `description` — mirrored onto its route so the OG card's subtitle
+ * matches the page's `og:description`, and the summary page indexes like
+ * `llms.txt` give it.
+ */
+export declare const metaDescription: (page: PageRecord) => string | undefined;
 /** Build the runtime manifest that bridges core and the generated Astro app. */
 export declare const buildManifest: (options: {
     context: ProjectContext;

package/dist/types/core/markdown-mirrors.d.ts

@@ -0,0 +1,22 @@
+import type { RouteSet } from "./locale-links.ts";
+/**
+ * Where Blume serves each page's raw Markdown: a copy beside the page, named
+ * for its route (`/guide.md`, `/guide.mdx`; see `rawMarkdownEndpointTemplate`).
+ */
+/** The extensions every page's Markdown copies are served at. */
+export declare const MIRROR_EXTENSIONS: readonly [".md", ".mdx"];
+/** The name a page's Markdown copies are served under, from its route. */
+export declare const mirrorName: (route: string) => string;
+/**
+ * The page whose Markdown copies are served under `name`, if any are: the
+ * root's under `/index`, and a page's under its own route. `/index` is no
+ * page's route, yet it names the root's copies, so a path that isn't a page
+ * can still name a served copy.
+ */
+export declare const mirrorOwner: (pages: RouteSet, name: string) => string | undefined;
+/**
+ * The page a served Markdown copy at `path` belongs to (`/guide.md` the page
+ * `/guide`'s, `/index.mdx` the root's), or `undefined` when `path` is no
+ * served copy.
+ */
+export declare const mirroredPage: (pages: RouteSet, path: string) => string | undefined;

package/dist/types/core/mcp-clients.d.ts

@@ -0,0 +1,47 @@
+import type { LocalizableLabel } from "./schema.ts";
+/**
+ * Clients the "Connect to MCP" page action knows how to install the server
+ * into, in display order. Shared by the config schema (`agents.mcp.clients`
+ * entries validate against this list) and the PageActions menu (which renders
+ * the full list when the config is `true`). Lives outside `schema.ts` so the
+ * component can import the list without pulling the whole config schema into
+ * the layout module graph.
+ */
+export declare const mcpClients: readonly ["claude-code", "codex", "cursor", "vscode"];
+export type McpClient = (typeof mcpClients)[number];
+/** A client Blume doesn't ship: a menu row that copies its `command`. */
+export interface McpCustomClient {
+    /**
+     * Command the row copies, with `{name}` (the server name as an id, like
+     * `acme-docs`) and `{url}` (the server's absolute URL) filled in.
+     */
+    command: string;
+    /** Icon beside the label: a Lucide name, inline SVG, or image. Defaults to `terminal`. */
+    icon?: string;
+    /** Row label, optionally per locale (`{ en: "…", de: "…" }`). */
+    label: LocalizableLabel;
+}
+export type McpClientEntry = McpClient | McpCustomClient;
+/** A menu entry as a page renders it: a custom label resolved to its locale. */
+export type McpMenuEntry = McpClient | (Omit<McpCustomClient, "label"> & {
+    label: string;
+});
+/** Whether a `clients` entry names a built-in client rather than a custom one. */
+export declare const isBuiltInMcpClient: (client: McpClientEntry | McpMenuEntry) => client is McpClient;
+/** Resolve the custom clients' labels for one page's locale. */
+export declare const mcpMenuEntries: (clients: readonly McpClientEntry[], locale?: string, defaultLocale?: string) => McpMenuEntry[];
+/**
+ * The menu's rows after "Copy server URL", each with whether a rule goes
+ * above it: wherever the list switches between commands to copy and install
+ * links ("Copy server URL" copies too), so the default menu keeps its one
+ * rule before Cursor.
+ */
+export declare const mcpMenuRows: (entries: readonly McpMenuEntry[]) => {
+    client: McpMenuEntry;
+    rule: boolean;
+}[];
+/** Fill a custom client's command for the server it installs. */
+export declare const mcpClientCommand: (command: string, server: {
+    name: string;
+    url: string;
+}) => string;

package/dist/types/core/mdx-elements.d.ts

@@ -0,0 +1,32 @@
+import type { Nodes } from "mdast";
+import type { ElementUse } from "./types.ts";
+/**
+ * JSX elements in an `.mdx` body whose props don't render as written:
+ *
+ * - `handler`: an HTML element with a JavaScript event handler
+ *   (`<button onClick={() => …}>`). The page is static HTML, so the function
+ *   is written into the attribute as text and never runs. A string handler
+ *   (`onclick="…"`) is inline script the browser does run, and is left alone.
+ * - `prop`: a built-in that shows its children (see `BUILTIN_CHILD_PROPS`),
+ *   used without any, with props it doesn't take. Those are ignored, so the
+ *   element renders without the content they carry.
+ */
+type JsxElement = Extract<Nodes, {
+    type: "mdxJsxFlowElement" | "mdxJsxTextElement";
+}>;
+type AttributeValue = Extract<JsxElement["attributes"][number], {
+    type: "mdxJsxAttribute";
+}>["value"];
+type ExpressionValue = Extract<AttributeValue, {
+    type: string;
+}>;
+/** Whether an attribute's value is a `{…}` expression, not a string or nothing. */
+export declare const isExpression: (value: AttributeValue) => value is ExpressionValue;
+/**
+ * Every element in an `.mdx` body whose props don't render as written (see
+ * the module comment), in source order, its line shifted by `lineOffset`. The
+ * body is parsed only when a cheap test finds a suspect, and a body MDX can't
+ * parse fails to render with its own error, so it yields none.
+ */
+export declare const extractElementUses: (body: string, lineOffset?: number) => ElementUse[];
+export {};

package/dist/types/core/mdx-syntax.d.ts

@@ -0,0 +1,100 @@
+import type { SourceEntry } from "./sources/types.ts";
+import type { Diagnostic } from "./types.ts";
+import type { ContentVariables } from "./variables.ts";
+/**
+ * MDX that doesn't parse, found before Astro compiles it. The parse is
+ * Sätteri's, with the feature set the renderer uses, so a body that fails it
+ * here fails `astro build` too: Astro compiles every `.mdx` file in the
+ * collection, drafts and pages the scan dropped included. Parsing only (no
+ * plugins, no render) keeps it cheap enough to run on every page.
+ *
+ * - `BLUME_MDX_SYNTAX` (error): the page's own text doesn't parse, so the
+ *   build fails at it.
+ * - `BLUME_MDX_SYNTAX` (warning): the page parses, but not once its
+ *   `<include>`s are spliced in. Reported in the partial. The render splices a
+ *   partial more leniently than this parse reads it, so the page may still
+ *   build, with the partial's markup rendered wrong (an HTML comment shown as
+ *   text, an unclosed `<img>` taking in what follows it).
+ *
+ * The same reading locates a build failure Astro reports with no line: an
+ * `.mdx` page that throws while it renders (a `{…}` expression reading a name
+ * nothing defines), or a partial that breaks the including page's compile.
+ */
+/** Where MDX stopped reading a text, and why. */
+export interface MdxSyntaxError {
+    column: number;
+    line: number;
+    /** Sätteri's message, without its leading position and trailing rule id. */
+    reason: string;
+}
+/**
+ * The first MDX syntax error in `text`, a page body with its front matter
+ * off, or null when it parses.
+ *
+ * Only the verdict is needed, so the parse stays native: Sätteri's tree is
+ * dropped unread rather than built as JavaScript objects, which costs as much
+ * again as the parse itself on every page. A parse error carries its own
+ * position, so node positions aren't tracked either.
+ */
+export declare const mdxSyntaxError: (text: string) => MdxSyntaxError | null;
+/** A position in the file the author wrote. */
+interface Site {
+    column?: number;
+    file: string;
+    line: number;
+}
+/** Maps a line and column of the parsed text to the file it came from. */
+type SiteOf = (line: number, column?: number) => Site;
+/**
+ * The `BLUME_MDX_SYNTAX` diagnostic for `error`, read from a text whose lines
+ * `siteOf` places.
+ */
+export declare const mdxSyntaxDiagnostic: (error: MdxSyntaxError, siteOf: SiteOf, options: {
+    includedIn?: string;
+    severity: Diagnostic["severity"];
+}) => Diagnostic;
+/** What the scan learned from parsing an `.mdx` entry. */
+export interface MdxSyntaxCheck {
+    diagnostics: Diagnostic[];
+    /** Whether the page's own text fails to parse, so its build would fail. */
+    unparsable: boolean;
+}
+/**
+ * Parse an `.mdx` entry's body, and its include-expanded text when it has
+ * one (see the module comment). The body is read as the build reads it: with
+ * the site's variables substituted, which the scan has already done when
+ * there was no expansion to do it in.
+ */
+export declare const mdxSyntaxCheck: (entry: SourceEntry, sourceName: string, variables?: ContentVariables) => MdxSyntaxCheck;
+/** A page as the build failure locator reads it. */
+export interface FailedPage {
+    /** The owning source's content root, which bounds its includes. */
+    contentRoot?: string;
+    /** How a message names the page: its path from the project root. */
+    name: string;
+    sourcePath: string;
+    variables?: ContentVariables;
+}
+/** What a build failure in an `.mdx` page said about itself. */
+export type MdxFailure = {
+    kind: "syntax";
+} | {
+    kind: "undefined-name";
+    name: string;
+};
+/** Where a build failure happened in the files the author wrote. */
+export interface MdxFailureSite extends Site {
+    /** For a syntax failure, the parse's own diagnostic. */
+    diagnostic?: Diagnostic;
+    /** For an undefined name, the expression that reads it, braces included. */
+    expression?: string;
+}
+/**
+ * Locate a build failure Astro reported against an `.mdx` page with no line:
+ * the expression that reads an undefined name, or the syntax error that
+ * stopped the compile (which, when the page's own text parsed, sits in a
+ * partial it includes). Null when the page can't be read or the cause can't
+ * be found in it.
+ */
+export declare const locateMdxFailure: (page: FailedPage, failure: MdxFailure) => Promise<MdxFailureSite | null>;
+export {};

package/dist/types/core/meta-diagnostics.d.ts

@@ -0,0 +1,7 @@
+import type { DiscoveredFolderMeta } from "./meta.ts";
+import type { Diagnostic, PageRecord } from "./types.ts";
+/** Folder-meta diagnostics against every page the sources produced. */
+export declare const folderMetaDiagnostics: (discovered: DiscoveredFolderMeta, pages: readonly PageRecord[], options?: {
+    localeDirs?: readonly string[];
+    versionDirs?: readonly string[];
+}) => Promise<Diagnostic[]>;

package/dist/types/core/meta.d.ts

@@ -19,6 +19,26 @@ export interface FolderMetaSource {
  * translates through this too, so it covers exactly the ones the scan reads.
  */
 export declare const findFolderMetaFiles: (source: FolderMetaSource, patterns?: readonly string[]) => Promise<string[]>;
+/** Folder meta by key: per-locale `meta.*` files, and shared `meta.$.*` ones. */
+export interface FolderMetaMaps {
+    meta: Map<string, FolderMeta>;
+    shared: Map<string, FolderMeta>;
+}
+/** A folder-meta file Blume found but doesn't read, and the key it would have. */
+export interface UnreadFolderMeta {
+    /** Its folder, relative to the source root. */
+    dir: string;
+    file: string;
+    key: string;
+}
+/** What {@link discoverFolderMeta} found across the sources. */
+export interface DiscoveredFolderMeta extends FolderMetaMaps {
+    diagnostics: Diagnostic[];
+    /** The file each meta in `meta` and `shared` was read from. */
+    files: Map<FolderMeta, string>;
+    /** Meta files under a source root that no source's `include` globs reach. */
+    unread: UnreadFolderMeta[];
+}
 /**
  * Discover `meta.{ts,js,mjs}` files across the given filesystem sources. Keys are
  * the source's route prefix joined with the directory relative to that source's
@@ -43,8 +63,15 @@ export declare const findFolderMetaFiles: (source: FolderMetaSource, patterns?:
 export declare const discoverFolderMeta: (sources: string | FolderMetaSource[], options?: {
     localeDirs?: readonly string[];
     versionDirs?: readonly string[];
-}) => Promise<{
-    meta: Map<string, FolderMeta>;
-    shared: Map<string, FolderMeta>;
-    diagnostics: Diagnostic[];
-}>;
+}) => Promise<DiscoveredFolderMeta>;
+/**
+ * Lay the folder meta content sources derive (the OpenAPI source's tag
+ * titles and order) beneath the user's `meta.ts` and `meta.$.ts` files, field
+ * by field: a user file's own keys win, and the generated ones fill the rest,
+ * so a `meta.ts` that only renames a tag group keeps its generated `order`.
+ * Generated meta is locale-agnostic, keyed like `meta.$.*`, so it also sits
+ * beneath a locale's own `meta.ts` (`fr/reference/pets` over
+ * `reference/pets`). It doesn't reach into an archived version's snapshot,
+ * whose groups read only meta keyed under the version.
+ */
+export declare const withGeneratedFolderMeta: (user: FolderMetaMaps, generated: Map<string, FolderMeta>, localeDirs?: readonly string[]) => FolderMetaMaps;