blume 2.1.2 → 2.2.0

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

@@ -121,7 +121,9 @@ declare const pageMetaBaseSchema: z.ZodObject<{
     title: z.ZodOptional<z.ZodString>;
     type: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
-export declare const pageMetaSchema: z.ZodObject<{
+export type PageMeta = z.infer<typeof pageMetaBaseSchema>;
+export type PageMetaInput = z.input<typeof pageMetaBaseSchema>;
+export declare const pageMetaSchema: z.ZodPipe<z.ZodObject<{
     ai: z.ZodPrefault<z.ZodObject<{
         exclude: z.ZodDefault<z.ZodBoolean>;
     }, z.core.$strict>>;
@@ -202,9 +204,135 @@ export declare const pageMetaSchema: z.ZodObject<{
     slug: z.ZodOptional<z.ZodString>;
     title: z.ZodOptional<z.ZodString>;
     type: z.ZodOptional<z.ZodString>;
-}, z.core.$strict>;
-export type PageMeta = z.infer<typeof pageMetaBaseSchema>;
-export type PageMetaInput = z.input<typeof pageMetaBaseSchema>;
+}, z.core.$strict>, z.ZodTransform<{
+    ai: {
+        exclude: boolean;
+    };
+    deprecated: boolean;
+    draft: boolean;
+    hidden: boolean;
+    narration: boolean;
+    noindex: boolean;
+    pagination: boolean;
+    search: {
+        exclude: boolean;
+        boost?: number | undefined;
+        keywords?: string[] | undefined;
+        tags?: string[] | undefined;
+    };
+    seo: {
+        noindex: boolean;
+        canonical?: string | undefined;
+        description?: string | undefined;
+        image?: string | undefined;
+        title?: string | undefined;
+        x?: {
+            creator?: string | undefined;
+        } | undefined;
+    };
+    sidebar: {
+        hidden: boolean;
+        badge?: string | undefined;
+        display?: "flat" | "group" | "page" | undefined;
+        icon?: string | undefined;
+        label?: string | undefined;
+        order?: number | undefined;
+    };
+    api?: string | undefined;
+    authMethod?: "none" | "key" | "bearer" | "basic" | undefined;
+    authors?: string | {
+        [x: string]: unknown;
+        name: string;
+        avatar?: string | undefined;
+        image?: string | undefined;
+        url?: string | undefined;
+    } | (string | {
+        [x: string]: unknown;
+        name: string;
+        avatar?: string | undefined;
+        image?: string | undefined;
+        url?: string | undefined;
+    })[] | undefined;
+    changelog?: {
+        category?: string | undefined;
+        date?: string | undefined;
+        version?: string | undefined;
+    } | undefined;
+    date?: string | undefined;
+    description?: string | undefined;
+    icon?: string | undefined;
+    lastModified?: string | undefined;
+    mode?: "default" | "custom" | "wide" | "center" | "frame" | undefined;
+    playground?: "none" | "interactive" | "simple" | undefined;
+    related?: false | (string | Record<string, string>)[] | undefined;
+    slug?: string | undefined;
+    title?: string | undefined;
+    type?: string | undefined;
+}, {
+    ai: {
+        exclude: boolean;
+    };
+    deprecated: boolean;
+    draft: boolean;
+    hidden: boolean;
+    narration: boolean;
+    noindex: boolean;
+    pagination: boolean;
+    search: {
+        exclude: boolean;
+        boost?: number | undefined;
+        keywords?: string[] | undefined;
+        tags?: string[] | undefined;
+    };
+    seo: {
+        noindex: boolean;
+        canonical?: string | undefined;
+        description?: string | undefined;
+        image?: string | undefined;
+        title?: string | undefined;
+        x?: {
+            creator?: string | undefined;
+        } | undefined;
+    };
+    sidebar: {
+        hidden: boolean;
+        badge?: string | undefined;
+        display?: "flat" | "group" | "page" | undefined;
+        icon?: string | undefined;
+        label?: string | undefined;
+        order?: number | undefined;
+    };
+    api?: string | undefined;
+    authMethod?: "none" | "key" | "bearer" | "basic" | undefined;
+    authors?: string | {
+        [x: string]: unknown;
+        name: string;
+        avatar?: string | undefined;
+        image?: string | undefined;
+        url?: string | undefined;
+    } | (string | {
+        [x: string]: unknown;
+        name: string;
+        avatar?: string | undefined;
+        image?: string | undefined;
+        url?: string | undefined;
+    })[] | undefined;
+    changelog?: {
+        category?: string | undefined;
+        date?: string | undefined;
+        version?: string | undefined;
+    } | undefined;
+    date?: string | undefined;
+    description?: string | undefined;
+    icon?: string | undefined;
+    lastModified?: string | undefined;
+    mode?: "default" | "custom" | "wide" | "center" | "frame" | undefined;
+    playground?: "none" | "interactive" | "simple" | undefined;
+    related?: false | (string | Record<string, string>)[] | undefined;
+    slug?: string | undefined;
+    title?: string | undefined;
+    type?: string | undefined;
+}>>;
 /**
  * The page schema as the generated content collections declare it, so
  * `entry.data` is typed and normalized (dates as ISO strings, X handles with
@@ -216,7 +344,7 @@ export type PageMetaInput = z.input<typeof pageMetaBaseSchema>;
  * diagnostic — Blume continues without it unless `--strict` — so the
  * collection must not turn that dropped page into a failed content sync.
  */
-export declare const pageCollectionSchema: z.ZodCatch<z.ZodObject<{
+export declare const pageCollectionSchema: z.ZodCatch<z.ZodPipe<z.ZodObject<{
     ai: z.ZodPrefault<z.ZodObject<{
         exclude: z.ZodDefault<z.ZodBoolean>;
     }, z.core.$strict>>;
@@ -297,7 +425,139 @@ export declare const pageCollectionSchema: z.ZodCatch<z.ZodObject<{
     slug: z.ZodOptional<z.ZodString>;
     title: z.ZodOptional<z.ZodString>;
     type: z.ZodOptional<z.ZodString>;
-}, z.core.$loose>>;
+}, z.core.$loose>, z.ZodTransform<{
+    [x: string]: unknown;
+    ai: {
+        exclude: boolean;
+    };
+    deprecated: boolean;
+    draft: boolean;
+    hidden: boolean;
+    narration: boolean;
+    noindex: boolean;
+    pagination: boolean;
+    search: {
+        exclude: boolean;
+        boost?: number | undefined;
+        keywords?: string[] | undefined;
+        tags?: string[] | undefined;
+    };
+    seo: {
+        noindex: boolean;
+        canonical?: string | undefined;
+        description?: string | undefined;
+        image?: string | undefined;
+        title?: string | undefined;
+        x?: {
+            creator?: string | undefined;
+        } | undefined;
+    };
+    sidebar: {
+        hidden: boolean;
+        badge?: string | undefined;
+        display?: "flat" | "group" | "page" | undefined;
+        icon?: string | undefined;
+        label?: string | undefined;
+        order?: number | undefined;
+    };
+    api?: string | undefined;
+    authMethod?: "none" | "key" | "bearer" | "basic" | undefined;
+    authors?: string | {
+        [x: string]: unknown;
+        name: string;
+        avatar?: string | undefined;
+        image?: string | undefined;
+        url?: string | undefined;
+    } | (string | {
+        [x: string]: unknown;
+        name: string;
+        avatar?: string | undefined;
+        image?: string | undefined;
+        url?: string | undefined;
+    })[] | undefined;
+    changelog?: {
+        category?: string | undefined;
+        date?: string | undefined;
+        version?: string | undefined;
+    } | undefined;
+    date?: string | undefined;
+    description?: string | undefined;
+    icon?: string | undefined;
+    lastModified?: string | undefined;
+    mode?: "default" | "custom" | "wide" | "center" | "frame" | undefined;
+    playground?: "none" | "interactive" | "simple" | undefined;
+    related?: false | (string | Record<string, string>)[] | undefined;
+    slug?: string | undefined;
+    title?: string | undefined;
+    type?: string | undefined;
+}, {
+    [x: string]: unknown;
+    ai: {
+        exclude: boolean;
+    };
+    deprecated: boolean;
+    draft: boolean;
+    hidden: boolean;
+    narration: boolean;
+    noindex: boolean;
+    pagination: boolean;
+    search: {
+        exclude: boolean;
+        boost?: number | undefined;
+        keywords?: string[] | undefined;
+        tags?: string[] | undefined;
+    };
+    seo: {
+        noindex: boolean;
+        canonical?: string | undefined;
+        description?: string | undefined;
+        image?: string | undefined;
+        title?: string | undefined;
+        x?: {
+            creator?: string | undefined;
+        } | undefined;
+    };
+    sidebar: {
+        hidden: boolean;
+        badge?: string | undefined;
+        display?: "flat" | "group" | "page" | undefined;
+        icon?: string | undefined;
+        label?: string | undefined;
+        order?: number | undefined;
+    };
+    api?: string | undefined;
+    authMethod?: "none" | "key" | "bearer" | "basic" | undefined;
+    authors?: string | {
+        [x: string]: unknown;
+        name: string;
+        avatar?: string | undefined;
+        image?: string | undefined;
+        url?: string | undefined;
+    } | (string | {
+        [x: string]: unknown;
+        name: string;
+        avatar?: string | undefined;
+        image?: string | undefined;
+        url?: string | undefined;
+    })[] | undefined;
+    changelog?: {
+        category?: string | undefined;
+        date?: string | undefined;
+        version?: string | undefined;
+    } | undefined;
+    date?: string | undefined;
+    description?: string | undefined;
+    icon?: string | undefined;
+    lastModified?: string | undefined;
+    mode?: "default" | "custom" | "wide" | "center" | "frame" | undefined;
+    playground?: "none" | "interactive" | "simple" | undefined;
+    related?: false | (string | Record<string, string>)[] | undefined;
+    slug?: string | undefined;
+    title?: string | undefined;
+    type?: string | undefined;
+}>>>;
+/** Built-in page frontmatter keys; custom keys must never redeclare one. */
+export declare const BUILT_IN_PAGE_META_KEYS: ReadonlySet<string>;
 export declare const folderMetaSchema: z.ZodObject<{
     collapsed: z.ZodOptional<z.ZodBoolean>;
     directory: z.ZodOptional<z.ZodEnum<{
@@ -1760,7 +2020,7 @@ export declare const blumeConfigSchema: z.ZodObject<{
             options: z.ZodObject<{
                 pollInterval: z.ZodOptional<z.ZodNumber>;
                 prefix: z.ZodOptional<z.ZodString>;
-                exclude: z.ZodDefault<z.ZodArray<z.ZodString>>;
+                exclude: z.ZodPipe<z.ZodDefault<z.ZodArray<z.ZodString>>, z.ZodTransform<string[], string[]>>;
                 include: z.ZodDefault<z.ZodArray<z.ZodString>>;
                 root: z.ZodDefault<z.ZodString>;
             }, z.core.$strict>;

package/dist/types/core/sources/normalize.d.ts

@@ -41,10 +41,29 @@ export declare const unloadablePathDiagnostic: (path: string, file: string) => D
  * line, so its 0-based line is already the file's line minus one.
  */
 export declare const frontmatterYamlDiagnostic: (error: YAMLException, file: string) => Diagnostic;
+export declare const ATTRIBUTE: string;
+/** A heading's trailing `{#id}` marker, where its text holds one. */
+export interface TrailingCurlyMarker {
+    /** Whether the braces also set classes or attributes (`{ #id .wide }`). */
+    attributes: boolean;
+    id: string;
+    /** Where the marker starts in the text. */
+    index: number;
+    /** The braces as written. */
+    marker: string;
+}
+/**
+ * The `{#id}` marker a heading's text ends with: one of the spellings
+ * `BARE_CURLY_MARKER` matches, or an attribute list that sets an id among
+ * other attributes (see `HEADING_ATTRIBUTE_LIST`).
+ */
+export declare const trailingCurlyMarker: (text: string) => TrailingCurlyMarker | undefined;
 export declare const HTML_COMMENT: RegExp;
 export declare const INLINE_CODE: RegExp;
-/** A heading whose trailing `{#id}` marker is unescaped — see `BARE_CURLY_MARKER`. */
+/** A heading whose trailing `{#id}` marker is unescaped — see `trailingCurlyMarker`. */
 export interface CurlyMarker {
+    /** Whether the braces also set classes or attributes (`{ #id .wide }`). */
+    attributes: boolean;
     id: string;
     /** 1-based line of the heading (a setext heading's first text line) in the body. */
     line: number;
@@ -61,10 +80,10 @@ export interface HeadingSite {
 /** Everything one walk over a body yields for the anchor index. */
 export interface BodyScan {
     /**
-     * Raw HTML element ids (`<a id="…">`) outside headings, fences, inline
-     * code, comments, and `<Prompt>` regions — fragment-link targets that
-     * `blume validate` accepts alongside heading slugs. Deduplicated, in
-     * document order.
+     * Raw HTML element ids (`<a id="…">`) and `<a name="…">` names outside
+     * headings, fences, inline code, comments, and `<Prompt>` regions —
+     * fragment-link targets that `blume validate` accepts alongside heading
+     * slugs. Deduplicated, in document order.
      */
     anchors: string[];
     /** Headings whose trailing `{#id}` marker is unescaped, for `.mdx` pages. */
@@ -83,10 +102,77 @@ export interface BodyScan {
  */
 export declare const scanBody: (body: string) => BodyScan;
 export declare const extractHeadings: (body: string) => Heading[];
-export declare const MD_IMAGE: RegExp;
-/** Column (0-based, within `matched`) where a link/image match's target starts. */
-export declare const targetOffsetIn: (matched: string, target: string, title: string | undefined) => number;
-export declare const extractLinks: (body: string, lineOffset?: number) => PageLink[];
+/**
+ * Rewrite the target of every image embed on one line with `rewrite`, which
+ * gets the target as the renderer reads it (see `readDestination`) and
+ * returns the new one, or `null` to leave it as written. Inline code is
+ * skipped: matches run on a copy with code spans blanked, and replacements
+ * splice into the real line by index, which the same-length mask keeps in
+ * step. A rewritten target is written back in the form its destination took.
+ */
+export declare const rewriteImageTargets: (line: string, rewrite: (target: string) => string | null) => string;
+/** A string `href` or `src` on an element, as {@link rewriteElementUrls} reads it. */
+export interface ElementUrl {
+    attribute: string;
+    /** The element's name as written: `img`, `a`, `Card`. */
+    tag: string;
+    value: string;
+}
+/**
+ * Whether an element URL is one `blume validate` reads as a link (see
+ * `ELEMENT_HREF` and `ELEMENT_SRC`): a media element's `src`, or an `<a>`'s or
+ * a component's `href`. Only these name a file the build publishes from
+ * beside the page.
+ */
+export declare const isLinkElementUrl: (url: ElementUrl) => boolean;
+/**
+ * Rewrite every `<Card img="…">` value in `text` (outside code) with
+ * `rewrite`, which returns the new value or `null` to leave one as written.
+ * The include expander rebases a partial's values with it and the
+ * content-asset rewriter points them at their served URL, exactly as both
+ * treat image embeds, so a card's image resolves like `![](./cover.png)`.
+ */
+export declare const rewriteCardImages: (text: string, rewrite: (target: string) => string | null) => string;
+/**
+ * Rewrite every element's string `href` or `src` in `text` (outside code)
+ * with `rewrite`, which returns the new value or `null` to leave one as
+ * written. The include expander rebases a partial's files with it, the
+ * content-asset rewriter points them at their served URL, and the render
+ * plugins rewrite raw HTML with it.
+ */
+export declare const rewriteElementUrls: (text: string, rewrite: (url: ElementUrl) => string | null) => string;
+/**
+ * Rewrite the target of every Markdown link in `text` (outside code) with
+ * `rewrite`, which gets the target as the renderer reads it and returns the
+ * new one, or `null` to leave it as written: inline links (an image embed is
+ * no link; see {@link rewriteImageTargets}), links whose label wraps onto
+ * later lines, and link-reference definitions (`[spec]: ./spec.pdf`). Each
+ * rewritten target is written back in the form its destination took.
+ */
+export declare const rewriteLinkTargets: (text: string, rewrite: (target: string) => string | null) => string;
+/** A link-reference definition, as {@link linkDefinitions} reads one. */
+export interface LinkDefinition {
+    /** The label as CommonMark matches it: case-folded, spaces collapsed. */
+    key: string;
+    /** The definition on a line of its own, out of any container. */
+    text: string;
+}
+/**
+ * Every link-reference definition in `text` (`[label]: /url "Title"`,
+ * outside code; footnotes aren't links), in order, the first of each label
+ * only, since that's the one that renders. A definition is read from its own
+ * line: its destination and any title there, and nothing else, since a line
+ * with more after them is text.
+ */
+export declare const linkDefinitions: (text: string) => LinkDefinition[];
+/**
+ * Extract link targets from a markdown body for later validation, recording the
+ * 1-based line/column of each target. Skips fenced code blocks, inline code,
+ * and — given the page's `format` — comments, none of which render a link.
+ * `lineOffset` shifts every recorded line: the body is frontmatter-stripped, so
+ * diagnostics that point into the raw file must add the stripped block's height.
+ */
+export declare const extractLinks: (body: string, lineOffset?: number, format?: "md" | "mdx") => PageLink[];
 /**
  * Every `<Component path>` in an `.mdx` body, with the 1-based position of its
  * value; lines are shifted by `lineOffset`, as {@link extractLinks} does. Code
@@ -146,6 +232,12 @@ export interface EntryRoute extends Pick<EntryPlacement, "locales" | "version">
      * through {@link localizedRoute} for the route one locale publishes at.
      */
     logicalRoute: string;
+    /**
+     * The logical route an earlier Blume published the entry at, when it
+     * differs: a date-named file or folder (`12-05-2022`) lost its first number
+     * as an ordering prefix. Its old URL redirects to the new one.
+     */
+    formerLogicalRoute?: string;
     /** The prefixed, locale- and version-stripped nav path. */
     navPath: string;
     segments: string[];

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

@@ -65,6 +65,15 @@ export interface SourceEntry {
         includes: string[];
     };
 }
+/**
+ * A redirect a source asks for: from a route one of its pages used to have
+ * to the route it has now, both locale-stripped and without `basePath`, as
+ * the page routes its entries map to.
+ */
+export interface SourceRedirect {
+    from: string;
+    to: string;
+}
 /** The result of a single `ContentSource.load()` call. */
 export interface SourceLoadResult {
     entries: SourceEntry[];
@@ -78,6 +87,13 @@ export interface SourceLoadResult {
      * beneath user-authored meta files, which always win.
      */
     folderMeta?: Record<string, FolderMeta>;
+    /**
+     * Redirects from routes the source's pages moved off: the OpenAPI source
+     * keeps the URLs earlier releases gave operation pages working. Added to
+     * the config's `redirects` after them, skipping any whose `from` a page or
+     * a configured redirect already owns.
+     */
+    redirects?: SourceRedirect[];
 }
 /**
  * Per-source runtime context, handed to an adapter factory at construction so

package/dist/types/core/static-files.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Whether a root-relative path names a file the site serves outside its pages,
+ * as a static host answers it: a file in `public/`, a `public/` folder's
+ * `index.html` (`/demo` and `/demo/` for `public/demo/index.html`), or one of
+ * the files Blume generates (`generated`, base-less paths like `/llms.txt`;
+ * see `deploy/generated-files.ts`). `publicDir` is `null` when the project has
+ * no `public/` folder, which ships no files then. Paths come decoded, without
+ * `deployment.base`, which a host mounts `public/` under.
+ */
+export declare const staticFileResolver: (publicDir: string | null, generated?: Iterable<string>) => ((path: string) => boolean);

package/dist/types/core/static-host.d.ts

@@ -0,0 +1,42 @@
+/**
+ * What a static host does with the URLs `blume dev` and `blume preview`
+ * would otherwise answer on their own terms. Astro's `trailingSlash: "never"`
+ * has both 404 a slashed URL (`/guide/`), which every host answers: Vercel
+ * redirects it to `/guide`, and the others serve `guide/index.html`. And a
+ * folder of HTML shipped in `public/` (`public/demo/index.html`) is served at
+ * `/demo/`, `/demo` redirecting there, so the relative links inside it
+ * resolve against the folder; the dev server 404s both spellings, and Vite's
+ * preview serves only the slashless one.
+ */
+import type { IncomingMessage, Server } from "node:http";
+/** How to answer a request ahead of the server's own handlers. */
+export type HostAnswer = {
+    kind: "redirect";
+    location: string;
+    status: number;
+} | {
+    kind: "rewrite";
+    url: string;
+};
+/**
+ * Whether `public/<path>/index.html` exists: a folder of HTML the site ships
+ * as is. `path` is the decoded request path with `deployment.base` stripped.
+ */
+export declare const publicFolder: (publicDir: string) => (path: string) => boolean;
+/**
+ * How a static host answers a URL's trailing slash, or null to leave the
+ * request alone. A slashed URL redirects to its slashless page, its query
+ * kept, unless it names a public folder, which serves its `index.html`; a
+ * slashless public folder redirects to its slashed URL. `base` is the
+ * normalized `deployment.base`, which the URL carries and `public/` doesn't.
+ * The redirect is a `301`, a `308` for a method a `301` would turn into a
+ * `GET`, as Astro answers on a server-rendered route.
+ */
+export declare const trailingSlashAnswer: (request: Pick<IncomingMessage, "method" | "url">, base: string, isPublicFolder: (path: string) => boolean) => HostAnswer | null;
+/**
+ * Answer every request on `server` with `answer` first: a redirect is sent
+ * then and there, and a rewrite changes the URL the server's own handlers
+ * (Vite's middleware) then see. They're the request listeners the server
+ * already has, so this goes ahead of every middleware, Astro's included.
+ */
+export declare const answerRequestsFirst: (server: Server, answer: (request: IncomingMessage) => HostAnswer | null, headers?: Record<string, string>) => void;

package/dist/types/core/svg-images.d.ts

@@ -0,0 +1,26 @@
+import type { Diagnostic, PageRecord } from "./types.ts";
+/**
+ * Colocated SVGs Astro's image pipeline can't measure. Astro reads an image's
+ * size before it optimizes it, and for an SVG it looks for the `<svg>` tag in
+ * the file's first 1,000 bytes only, then needs a width and height or a
+ * viewBox on that tag. A draw.io export carries its whole diagram in a
+ * `content` attribute on the tag, which pushes the tag's end past that
+ * window, so one diagram fails the build (`NoImageMetadata`). Blume serves
+ * such an SVG as it is instead, from the endpoint that already serves content
+ * images to agents (`/blume-assets/content/…`), and warns about it
+ * (`BLUME_SVG_UNOPTIMIZED`). A browser draws an SVG at any size, so the
+ * only loss is the intrinsic `width`/`height` the optimized `<img>` carries.
+ */
+/** Whether the file at `path` is an SVG Astro can't read the size of. */
+export declare const isUnmeasurableSvg: (path: string) => Promise<boolean>;
+/**
+ * The URL an unmeasurable SVG is served at, unbased (the base links plugin
+ * mounts `deployment.base`), or null when `target` isn't a colocated image
+ * Astro can measure no size for.
+ */
+export declare const unmeasurableSvgUrl: (sourceDir: string, target: string, projectRoot: string) => Promise<string | null>;
+/**
+ * A warning for each image embed of a colocated SVG Astro can't measure, at
+ * the line that embeds it (in a partial, when an `<include>` brought it in).
+ */
+export declare const unmeasurableSvgDiagnostics: (pages: readonly PageRecord[]) => Promise<Diagnostic[]>;

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

@@ -0,0 +1,14 @@
+import type { SourceEntry } from "./sources/types.ts";
+import type { Diagnostic, PageRecord } from "./types.ts";
+/** The site's pages by the names a wiki link can call them (see {@link wikiKey}). */
+export type PageNameIndex = ReadonlyMap<string, readonly PageRecord[]>;
+/** Index pages by file name and title, for {@link syntaxDiagnostics}. */
+export declare const indexPageNames: (pages: readonly PageRecord[]) => PageNameIndex;
+/**
+ * Warn about syntax from other docs tools in an entry's body (see the module
+ * comment). `pages` are the site's pages by name, which a wiki link resolves
+ * against, preferring one in the entry's own `locale`. Lines point into the
+ * file the author wrote, a partial's own file for syntax an `<include>`
+ * brought in.
+ */
+export declare const syntaxDiagnostics: (entry: SourceEntry, sourceName: string, pages?: PageNameIndex, locale?: string) => Diagnostic[];

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

@@ -45,8 +45,13 @@ export interface Heading {
 }
 /** A link target discovered in page content, anchored to its source line. */
 export interface PageLink {
-    /** Raw link target as written, e.g. `./foo`, `/api#auth`, `https://x.dev`. */
+    /** Raw link target as written, e.g. `./foo`, `/api#auth`, `https://x.dev`.
+     * A Markdown destination is read as the renderer reads it: without its
+     * `<…>` brackets, and with backslash escapes resolved. */
     target: string;
+    /** Length of the target's text in the source, when escapes make it differ
+     * from `target`'s (`image\(1\).png` is read as `image(1).png`). */
+    sourceLength?: number;
     /** Set when the target was written as an image embed (`![alt](target)`) —
      * only those go through the image pipeline; a plain link to the same path
      * resolves as a site route. */
@@ -55,6 +60,11 @@ export interface PageLink {
      * the Markdown pipeline neither resolves its relative path file-style nor
      * mounts the base path on it, so it's checked the way a browser reads it. */
     raw?: boolean;
+    /** The element, when the target is a media element's `src` (`img`,
+     * `source`, `video`, `audio`). It's `raw` too: the browser resolves it as
+     * written, unless it names a file beside the page, which the build
+     * publishes and points it at. */
+    src?: string;
     /** 1-based line number in the source file. */
     line: number;
     /** 1-based column of the target within the line. */
@@ -75,6 +85,25 @@ export interface ExampleUse {
     /** Absolute path of the included partial it was written in, if not the page. */
     file?: string;
 }
+/**
+ * A JSX element in an `.mdx` body whose props don't render as written (see
+ * `core/mdx-elements.ts`), located like a {@link PageLink}: an HTML element
+ * with a JavaScript event handler (`handler`), or a childless built-in given
+ * props it doesn't take (`prop`).
+ */
+export interface ElementUse {
+    /** 1-based column of the element's `<` within the line. */
+    column: number;
+    /** Absolute path of the included partial it was written in, if not the page. */
+    file?: string;
+    kind: "handler" | "prop";
+    /** 1-based line number in the source file. */
+    line: number;
+    /** The handler props, or the props the built-in doesn't take. */
+    props: string[];
+    /** The element's name as written (`button`, `Badge`). */
+    tag: string;
+}
 /**
  * Resolved project paths. Computed once per CLI invocation and threaded
  * through the core pipeline.
@@ -162,6 +191,12 @@ export interface PageRecord {
      * checks skip these.
      */
     fallback?: boolean;
+    /**
+     * The route an earlier Blume published the page at, when it differs from
+     * `route`: a date-named file or folder (`12-05-2022`) lost its first number
+     * as an ordering prefix. The scan redirects it to `route`.
+     */
+    formerRoute?: string;
     /**
      * True for pages from a source that publishes one language only (GitHub
      * Releases): they render without a language switcher.
@@ -202,6 +237,12 @@ export interface PageRecord {
     componentsUsed?: string[];
     /** The string `path` of each `<Component>` example in the body (`.mdx` only). */
     examplesUsed?: ExampleUse[];
+    /**
+     * Childless built-ins given props they don't take (`.mdx` only). Reported
+     * once the project's own components are known, since an override takes
+     * whatever props it declares.
+     */
+    unknownProps?: ElementUse[];
     /** Resolved "last updated" ISO date, when the feature is enabled. */
     lastModified?: string;
     /** Absolute paths of files this page `<include>`s, transitively. Drives the