blume 1.7.3 → 2.0.1

package/dist/types/core/site-url.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Absolute-URL building for the configured `deployment.site`, shared by every
+ * emitter that prints site URLs (sitemap, RSS, robots, llms.txt, the MCP and
+ * agent-discovery documents). One implementation replaces eight per-file
+ * copies that had drifted across three different trailing-slash treatments.
+ *
+ * Deliberately not `new URL(path, site)`: a root-absolute path would drop the
+ * base path of a subpath deployment (`acme.com/docs`). ufo's `joinURL` joins
+ * without that footgun; the site is first trimmed with the ReDoS-safe
+ * `trimEnd` loop so even a malformed `site` with piled-up trailing slashes
+ * joins cleanly.
+ */
+/** The configured site with any trailing slashes dropped. */
+export declare const siteRoot: (site: string) => string;
+/** `site` + root-absolute `path` (already carrying any deployment base). */
+export declare const absoluteUrl: (site: string, path: string) => string;

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

@@ -0,0 +1,36 @@
+import type { Diagnostic } from "../types.ts";
+/** Where to write downloaded assets and how to reference them publicly. */
+export interface AssetContext {
+    assetsDir: string;
+    assetsBaseUrl: string;
+    /** Injected for tests; defaults to the global `fetch`. */
+    fetchImpl?: typeof fetch;
+    /**
+     * Gate for concurrent downloads. A source shares one gate across every page
+     * it materializes, so a database of video-heavy pages doesn't open every
+     * download at once. Defaults to no gate.
+     */
+    limit?: <T>(task: () => Promise<T>) => Promise<T>;
+    /**
+     * Downloads in progress, keyed by asset stem. A source shares one table
+     * (alongside `limit`) across every page it materializes, so two pages that
+     * reference the same asset share one download instead of racing to publish
+     * the same file. Defaults to a table private to this call.
+     */
+    inFlight?: Map<string, Promise<string>>;
+    /** Abort a download that hasn't completed within this many milliseconds. */
+    timeoutMs?: number;
+}
+/**
+ * Download remote media referenced in a Markdown body into the asset dir and
+ * rewrite the reference to the local public path. Markdown images and the
+ * `src` of a `<video>` tag are both covered. Remote CMS URLs (notably Notion's
+ * signed, expiring links) would otherwise rot a static build. Assets are
+ * content-addressed by URL hash, so repeated builds are stable and deduped —
+ * and a file already on disk is not fetched again, which keeps a dev poll
+ * from re-downloading every video on every tick.
+ */
+export declare const materializeAssets: (markdown: string, ctx: AssetContext) => Promise<{
+    markdown: string;
+    diagnostics: Diagnostic[];
+}>;

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

@@ -0,0 +1,37 @@
+import type { SourceEntry, SourceLoadResult } from "./types.ts";
+/**
+ * Small, stable content hash for cache/HMR bookkeeping — and for staged asset
+ * *filenames* (see sources/assets.ts and content-assets.ts), where a collision
+ * silently serves the wrong file. 64 bits of SHA-256 keeps those names
+ * collision-safe at any realistic asset count; the old 31-bit DJB2 hash had a
+ * ~46k-item birthday bound.
+ */
+export declare const hashText: (text: string) => string;
+/** A stable digest of a source's entries, for change detection while polling. */
+export declare const entriesDigest: (entries: SourceEntry[]) => string;
+/**
+ * Build an opt-in polling watcher for a remote source: re-`load()` on an
+ * interval and fire `onChange` only when the entry digest changes, so a remote
+ * source can hot-reload in dev without refetching the world on every keystroke.
+ *
+ * `load` must fetch fresh (bypassing the cache-first dev path) — polling the
+ * cache-first loader would serve the identical snapshot on every tick and
+ * never observe a remote change. `seed` (the source's regular, cache-first
+ * loader) establishes the baseline digest from what dev actually served, so a
+ * remote change landing before the first tick still fires.
+ */
+export declare const pollingWatch: (load: () => Promise<SourceLoadResult>, intervalSeconds: number, seed?: () => Promise<SourceLoadResult>) => ((onChange: () => void) => () => void);
+/** A per-source snapshot of the last successful fetch, for offline tolerance. */
+export interface SnapshotCache {
+    read: () => Promise<SourceEntry[]>;
+    write: (entries: SourceEntry[]) => Promise<void>;
+}
+/** Build a JSON snapshot cache under `<cacheDir>/entries.json`. */
+export declare const snapshotCache: (cacheDir: string) => SnapshotCache;
+/**
+ * Run a remote `fetchEntries`, caching the result. When `refresh` is false and a
+ * snapshot exists, serve it without fetching (cache-first dev). On fetch failure,
+ * serve the last-known-good snapshot with a warning so a CMS/network outage
+ * doesn't fail the build; if there is no snapshot either, surface a hard error.
+ */
+export declare const loadWithCache: (name: string, cache: SnapshotCache, fetchEntries: () => Promise<SourceEntry[]>, refresh?: boolean) => Promise<SourceLoadResult>;

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

@@ -0,0 +1,28 @@
+import type { ContentSourceAdapter } from "../../sources/registry.ts";
+import type { ResolvedConfig } from "../schema.ts";
+/** Resolve a source `root` against the project root (absolute passes through). */
+export declare const resolveSourceRoot: (projectRoot: string, root: string) => string;
+/** The configured sources of one adapter `kind`, in config order. */
+export declare const sourcesOfKind: <Kind extends ContentSourceAdapter["kind"]>(config: ResolvedConfig, kind: Kind) => Extract<ContentSourceAdapter, {
+    kind: Kind;
+}>[];
+/**
+ * The generated `docs` glob collection: its base directory and the include /
+ * exclude globs applied under it. Astro's glob loader ids each entry by its
+ * path relative to `base`, and a filesystem source ids each entry relative to
+ * its own root — so the two only agree when the collection is rooted at that
+ * source. The collection therefore roots at the first `filesystem()` source
+ * (the implicit one, for a zero-config project). Further filesystem sources
+ * must share that root and partition it with globs: every filesystem source's
+ * `include` feeds the collection, and only a pattern every one of them
+ * excludes is excluded, so no source's pages are globbed away. A source
+ * rooted elsewhere can't share the base and is caught by the entry-id guard in
+ * `scanProject`. With no filesystem source at all the collection globs nothing
+ * and its base is the default `docs` directory, which only anchors paths.
+ */
+export interface DocsCollection {
+    base: string;
+    include: string[];
+    exclude: string[];
+}
+export declare const resolveDocsCollection: (config: ResolvedConfig, projectRoot: string) => DocsCollection;

package/dist/types/core/sources/contentful-rich-text.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Contentful rich text → Markdown. Covers the block, inline, and mark types
+ * the Rich Text editor emits; embedded entries fall through to a serializer
+ * keyed by content type or are noted in a comment. Links to assets and
+ * entries arrive unresolved from the Delivery API (`data.target` is a
+ * `sys` link), so the source hands in resolvers over the response's
+ * `includes`; a document the SDK already resolved (with `fields` inline)
+ * lowers the same way.
+ */
+import type { JsonObject } from "./json.ts";
+/** An asset's file as a Markdown image needs it. */
+export interface ContentfulAsset {
+    description?: string;
+    title?: string;
+    url: string;
+}
+export interface ContentfulRichTextOptions {
+    /** Resolve an asset link (`data.target.sys.id`) to its file. */
+    resolveAsset?: (id: string) => ContentfulAsset | null;
+    /** Resolve an entry link to the entry (`sys` plus `fields`). */
+    resolveEntry?: (id: string) => JsonObject | null;
+    /**
+     * Serializers for embedded entries, keyed by content type id; return
+     * Markdown or MDX. Setting any writes the source's entries as MDX.
+     */
+    serializers?: Record<string, (entry: JsonObject) => string>;
+}
+/** The file behind an asset entry, or null when it carries none. */
+export declare const assetFromEntry: (asset: JsonObject) => ContentfulAsset | null;
+/** Serialize a rich text document (`nodeType: "document"`) to Markdown. */
+export declare const contentfulRichTextToMarkdown: (doc: JsonObject, options?: ContentfulRichTextOptions) => string;

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

@@ -0,0 +1,40 @@
+import type { JsonObject } from "./json.ts";
+import type { RemoteFieldMap } from "./remote.ts";
+import type { ContentSource, SourceContext } from "./types.ts";
+export interface ContentfulSourceOptions {
+    name: string;
+    prefix?: string;
+    /** Space id. */
+    space: string;
+    /** Environment id; default `master`. */
+    environment?: string;
+    /** The content type id whose entries become pages. */
+    contentType: string;
+    /** Locale code to fetch; omit for the space's default locale. */
+    locale?: string;
+    /**
+     * Field ids mapping an entry onto Blume meta + body. Paths resolve against
+     * the entry's `fields`, with `sys` reachable as `sys.<key>`. Defaults:
+     * `title`, `description`, `slug`, `body`, `sys.updatedAt`.
+     */
+    fields?: RemoteFieldMap;
+    /** Extra query parameters for the entries request (`fields.section: "sdk"`). */
+    params?: Record<string, string>;
+    /** Serializers for embedded entries, keyed by content type id. */
+    serializers?: Record<string, (entry: JsonObject) => string>;
+    /** Delivery API token; defaults to `CONTENTFUL_ACCESS_TOKEN`. */
+    token?: string;
+    /** Preview API token for `--preview`; defaults to `CONTENTFUL_PREVIEW_TOKEN`. */
+    previewToken?: string;
+    /** Opt-in dev polling interval (seconds); omit to freeze for the session. */
+    pollInterval?: number;
+    /** Injected for tests; defaults to the global `fetch`. */
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Contentful content source. Pages through the Delivery API (the Preview API
+ * under `--preview`), maps each entry's fields to frontmatter, and lowers its
+ * rich text body to Markdown with the page's `includes` resolving asset and
+ * entry links.
+ */
+export declare const contentfulSource: (options: ContentfulSourceOptions, ctx?: SourceContext) => ContentSource;

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

@@ -0,0 +1,24 @@
+import type { ContentSource } from "./types.ts";
+/** Options for the built-in filesystem source. */
+export interface FilesystemSourceOptions {
+    /** Stable source name; namespaces ids and diagnostics. */
+    name: string;
+    /** Optional route prefix. */
+    prefix?: string;
+    /** Content root, absolute or relative to `projectRoot`. */
+    root: string;
+    include: string[];
+    exclude: string[];
+    /** Absolute project root, used to resolve a relative `root`. */
+    projectRoot: string;
+    /** When set, a missing root throws this code instead of the generic one. */
+    missingCode?: string;
+}
+/**
+ * The built-in content source: discover and read `.md`/`.mdx` files under a
+ * content root. This is the extraction of the original `discoverContent()` scan
+ * into a `ContentSource`; every other adapter follows the same contract.
+ */
+export declare const filesystemSource: (options: FilesystemSourceOptions) => ContentSource & {
+    readonly contentRoot: string;
+};

package/dist/types/core/sources/github-releases.d.ts

@@ -0,0 +1,31 @@
+import type { ContentSource, SourceContext } from "./types.ts";
+/** Options for the built-in GitHub Releases changelog source. */
+export interface GithubReleasesSourceOptions {
+    /** GitHub REST API base; overridable for GitHub Enterprise / tests. */
+    baseUrl?: string;
+    /** Include draft releases (needs a token with repo write access). Default off. */
+    drafts?: boolean;
+    /** Injected for tests; defaults to the global `fetch`. */
+    fetchImpl?: typeof fetch;
+    /** Cap the number of releases materialized, newest-first. Default 100. */
+    limit?: number;
+    name: string;
+    /** Repository owner (user or org). */
+    owner: string;
+    /** Opt-in dev polling interval (seconds); omit to freeze for the session. */
+    pollInterval?: number;
+    /** Namespaces the source's routes under `/<prefix>/`; e.g. `changelog`. */
+    prefix?: string;
+    /** Include prereleases. Default off. */
+    prereleases?: boolean;
+    /** Repository name. */
+    repo: string;
+}
+/**
+ * GitHub Releases content source. Pulls a repo's releases from the REST API and
+ * materializes each as a `type: changelog` entry, so a project's release notes
+ * become its changelog with no files to maintain. A private repo authenticates
+ * with `GITHUB_TOKEN`. A snapshot under `.blume/cache/<source>/` keeps rebuilds
+ * offline-tolerant.
+ */
+export declare const githubReleasesSource: (options: GithubReleasesSourceOptions, ctx: SourceContext) => ContentSource;

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

@@ -0,0 +1,30 @@
+/**
+ * The JSON a CMS API returns: arbitrary values a query or REST endpoint
+ * hands back, typed as a closed union so a source narrows with predicates
+ * instead of casting.
+ */
+export type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+/** A JSON object: a document, a node in a rich-text tree, an API envelope. */
+export interface JsonObject {
+    [key: string]: JsonValue;
+}
+/**
+ * A node a dot path can descend into. Arrays pass too (matching their runtime
+ * string-key indexing, e.g. `items.0`), so the predicate types them as the
+ * keyed form both traverse through.
+ */
+export declare const isJsonObject: (value: JsonValue | undefined) => value is JsonObject;
+/** Resolve a dot path (`slug.current`) against a document. */
+export declare const getPath: (doc: JsonObject, path: string) => JsonValue | undefined;
+export declare const isStringValue: (value: JsonValue | undefined) => value is string;
+export declare const asString: (value: JsonValue | undefined) => string | undefined;
+/** The elements of an array value, or none when the value is not an array. */
+export declare const asArray: (value: JsonValue | undefined) => JsonValue[];
+/** The object form of a value, or none when it is a scalar, array, or absent. */
+export declare const asObject: (value: JsonValue | undefined) => JsonObject | undefined;
+export declare const isNumberValue: (value: JsonValue | undefined) => value is number;
+export declare const asNumber: (value: JsonValue | undefined) => number | undefined;
+/** The object elements of an array value; scalars and nested arrays are dropped. */
+export declare const objectsIn: (value: JsonValue | undefined) => JsonObject[];

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

@@ -0,0 +1,19 @@
+/**
+ * Lexical (Payload's rich text editor) → Markdown. Covers the nodes Payload's
+ * default features emit — paragraphs, headings, lists (bullet, numbered,
+ * check), quotes, links, uploads, horizontal rules — and hands `block` /
+ * `inlineBlock` nodes to a serializer keyed by their `blockType`, or notes
+ * them in a comment.
+ */
+import type { JsonObject } from "./json.ts";
+export interface LexicalOptions {
+    /** The CMS origin a relative upload URL (`/media/x.png`) resolves against. */
+    baseUrl?: string;
+    /** Serializers for `block`/`inlineBlock` nodes, keyed by `fields.blockType`. */
+    serializers?: Record<string, (fields: JsonObject) => string>;
+}
+/**
+ * Serialize a Lexical editor state (`{ root: { children } }`, or the root
+ * node itself) to Markdown.
+ */
+export declare const lexicalToMarkdown: (state: JsonObject, options?: LexicalOptions) => string;

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

@@ -0,0 +1,75 @@
+/**
+ * Shared primitives for lowering a CMS's rich-text tree to Markdown text.
+ * Every rich-text lowerer (Portable Text, Contentful, Lexical, Strapi
+ * blocks) renders inline runs, wraps them in block syntax, and joins blocks
+ * with blank lines; these helpers keep that Markdown identical across them.
+ */
+export declare const escapeMarkdownText: (text: string) => string;
+/** The marks a lowerer can put on an inline run. */
+export interface InlineMarks {
+    bold?: boolean;
+    code?: boolean;
+    italic?: boolean;
+    strike?: boolean;
+}
+/**
+ * A code span whose delimiter outruns any backtick run inside it, padded with
+ * a space on each side when the code starts or ends with a backtick (the
+ * CommonMark rule that keeps the padding out of the rendered code).
+ */
+export declare const codeSpan: (code: string) => string;
+/**
+ * Wrap a text run in the Markdown for its marks. Code stays verbatim inside
+ * the backticks (an escape would render as a backslash); everything else is
+ * escaped first. Whitespace at either edge moves outside the delimiters,
+ * since `** bold **` is not strong emphasis but `**bold**` is — editors
+ * routinely bold a word together with the space after it.
+ */
+export declare const renderInline: (text: string, marks: InlineMarks) => string;
+/** A link or image destination as Markdown can carry it verbatim. */
+export declare const destination: (url: string) => string;
+/**
+ * A Markdown link, or the label alone when the target is missing — or unsafe:
+ * CMS content is the editor's, not the site author's, so a destination that
+ * isn't a web, mail, or relative address (`javascript:`, `data:`) never
+ * becomes a clickable link on the docs site (see `safe-links.ts`).
+ */
+export declare const renderLink: (label: string, href?: string) => string;
+/** The ATX prefix for a heading level, clamped to Markdown's six. */
+export declare const headingPrefix: (level: number) => string;
+/** Quote every line of a block. */
+export declare const blockquote: (text: string) => string;
+/**
+ * A list item: the marker on the first line, and every continuation line
+ * indented to the marker's width so nested blocks stay inside the item.
+ */
+export declare const listItem: (marker: string, body: string) => string;
+/** Indent every non-empty line, for a nested list hanging off an item. */
+export declare const indent: (text: string, width: number) => string;
+/** A fenced code block whose fence outruns any backtick run in the code. */
+export declare const codeFence: (code: string, language?: string) => string;
+/** A Markdown image; the alt is escaped so a `]` in a caption can't close it. */
+export declare const image: (alt: string, url: string) => string;
+/**
+ * Whether a lowerer's output is written as MDX. Serializers are how a CMS
+ * block becomes a Blume component, and components (like directives) only
+ * render in MDX, so configuring any serializer switches the source's
+ * rich-text bodies to `.mdx`. The escaping above keeps the rest of the
+ * lowered text valid there.
+ */
+export declare const writesMdx: <Node>(serializers?: Record<string, (node: Node) => string>) => boolean;
+/**
+ * A comment marking a node the lowerer has no Markdown for — an MDX comment
+ * when the output is MDX, which rejects `<!-- -->`.
+ */
+export declare const unsupported: (what: string, mdx?: boolean) => string;
+/** Blocks separated by blank lines; empty blocks are dropped. */
+export declare const joinBlocks: (blocks: string[]) => string;
+/** A whole document: its blocks plus the trailing newline a file ends with. */
+export declare const markdownDocument: (blocks: string[]) => string;
+/**
+ * A media URL as a static site can reference it. A protocol-relative
+ * Contentful asset (`//images.ctfassets.net/…`) gets `https:`; a path a
+ * self-hosted CMS serves (`/uploads/x.png`) resolves against the CMS origin.
+ */
+export declare const absoluteUrl: (url: string, base?: string) => string;

package/dist/types/core/sources/mdx-remote.d.ts

@@ -0,0 +1,28 @@
+import type { ContentSource, SourceContext } from "./types.ts";
+/** Options for the built-in remote Markdown/MDX source. */
+export interface MdxRemoteSourceOptions {
+    name: string;
+    prefix?: string;
+    /** Raw base URL for `files`, e.g. `https://raw.githubusercontent.com/o/r/main/docs`. */
+    url?: string;
+    /** Explicit source-relative file paths to fetch from `url`. */
+    files?: string[];
+    /** Enumerate a GitHub repo subtree via the git-trees API. */
+    github?: {
+        owner: string;
+        repo: string;
+        ref: string;
+        path: string;
+    };
+    include: string[];
+    /** Opt-in dev polling interval (seconds); omit to freeze for the session. */
+    pollInterval?: number;
+    /** Injected for tests; defaults to the global `fetch`. */
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Remote Markdown/MDX content source. Fetches raw `.md`/`.mdx` over HTTP and
+ * passes the text straight through `normalizeEntry`. A snapshot under
+ * `.blume/cache/<source>/` makes rebuilds offline-tolerant.
+ */
+export declare const mdxRemoteSource: (options: MdxRemoteSourceOptions, ctx: SourceContext) => ContentSource;

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

@@ -0,0 +1,147 @@
+import type { ResolvedI18nConfig } from "../schema.ts";
+import type { Diagnostic, Heading, PageLink, PageRecord } from "../types.ts";
+import type { NormalizeContext, SourceEntry } from "./types.ts";
+/**
+ * Slugify a content/route slug (Sanity, Notion, frontmatter `slug`). Heading
+ * anchor ids are *not* slugged here — they use a `github-slugger` in
+ * {@link extractHeadings}, matching the renderer (see `markdown/heading-anchors`)
+ * so `blume validate` checks anchors against the exact rendered heading ids.
+ *
+ * The keep-class is Unicode letters/marks/numbers, not `\w`: ASCII slugs are
+ * unchanged, but a CJK/Cyrillic/accented slug keeps its characters instead of
+ * collapsing to `""` (which forced Sanity/Notion routes onto their opaque
+ * document-id fallbacks) or dropping accents (`café` → `caf`). NFC first so a
+ * macOS-NFD `é` (e + combining mark) slugs identically to the composed form.
+ */
+export declare const slugify: (text: string) => string;
+/**
+ * {@link slugify} for a slug that may span path segments (`guides/setup`).
+ * `slugify` deletes `/` along with all other punctuation, which would mash
+ * `guides/setup` into `guidessetup` — and collide it with a genuine `guidessetup`
+ * document. Each segment is slugged on its own and the separators kept.
+ */
+export declare const slugifyPath: (text: string) => string;
+export declare const HTML_COMMENT: RegExp;
+export declare const INLINE_CODE: RegExp;
+/** A heading whose trailing `{#id}` marker is unescaped — see `BARE_CURLY_MARKER`. */
+export interface CurlyMarker {
+    id: string;
+    /** 1-based line of the heading (a setext heading's first text line) in the body. */
+    line: number;
+}
+/** Where a heading's text ends in the scanned text, for appending a marker. */
+export interface HeadingSite {
+    /** 1-based line (of the text passed to `scanBody`) that any trailing marker ends. */
+    line: number;
+    /** True when the heading already pins its id with `[#id]`/`{#id}`. */
+    pinned: boolean;
+}
+/** 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.
+     */
+    anchors: string[];
+    /** Headings whose trailing `{#id}` marker is unescaped, for `.mdx` pages. */
+    curlyMarkers: CurlyMarker[];
+    headings: Heading[];
+    /** Index-aligned with `headings`: where each one's markers would go. */
+    sites: HeadingSite[];
+}
+/**
+ * Scan a body for its headings, explicit HTML anchors, and unescaped `{#id}`
+ * markers in one fence-aware walk (the same walk `extractHeadings` exposes for
+ * headings alone).
+ */
+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[];
+export declare const extractComponentTags: (body: string) => string[];
+/**
+ * Height of the frontmatter block stripped from `raw` to produce `body` (0
+ * when the raw text is unknown or nothing was stripped). Link positions are
+ * extracted from the stripped body, but diagnostics point into the raw
+ * document — recorded lines must shift by this offset to match it.
+ */
+export declare const strippedLineOffset: (raw: string | undefined, body: string) => number;
+/** Whether a raw frontmatter value is a string (e.g. the `type` override). */
+export declare const isStringValue: (value: SourceEntry["data"][string]) => value is string;
+/** What a route resolution needs from the owning source and the config. */
+export type RouteContext = Pick<NormalizeContext, "i18n" | "versions"> & {
+    /** The source's route prefix (`NormalizeContext["source"]["prefix"]`). */
+    prefix?: string;
+};
+/** Where an entry's ref places it once its directories are read off. */
+export interface EntryPlacement {
+    /**
+     * The locale codes the entry publishes in: `[""]` without i18n, one code for
+     * a placed file, every configured code for a shared `$` file.
+     */
+    locales: string[];
+    /** The ref with its version and locale directories stripped, prefix-less. */
+    navPath: string;
+    /** The version snapshot the entry belongs to (`""` for current). */
+    version: string;
+}
+/**
+ * Read the version and locale directories off an entry's ref. The version is
+ * detected first: a snapshot directory is outermost on disk
+ * (`v1.0/fr/page.mdx`), so the locale parser must see a version-stripped ref.
+ * The current version is `""` and lives at the root. Locale placement comes
+ * from the ref (a leading dir, or a filename suffix under the `dot` parser),
+ * never the slug — the slug is the logical, locale-agnostic path within a
+ * locale. A shared `$` file maps to every locale; a source without i18n
+ * placement maps to one.
+ */
+export declare const placeEntryRef: (ref: string, ext: string, ctx: Pick<RouteContext, "i18n" | "versions">) => EntryPlacement;
+/** Everything `normalizeEntry` derives from an entry's ref and slug. */
+export interface EntryRoute extends Pick<EntryPlacement, "locales" | "version"> {
+    groups: string[];
+    /**
+     * The version-prefixed, locale-agnostic route — the translation key. Pass it
+     * through {@link localizedRoute} for the route one locale publishes at.
+     */
+    logicalRoute: string;
+    /** The prefixed, locale- and version-stripped nav path. */
+    navPath: string;
+    segments: string[];
+    /** The version-agnostic mapped route. */
+    versionKey: string;
+}
+/**
+ * The canonical route resolution, shared by {@link normalizeEntry} and any
+ * source that must predict the route an entry will publish at — the Obsidian
+ * source turns `[[Note]]` into a real href, and a second derivation of a route
+ * is a second answer.
+ *
+ * A frontmatter `slug` wins, then the adapter-supplied `entry.slug` (the typed
+ * SPI's "logical route input; defaults to ref if omitted"), then the ref. The
+ * extension is re-appended so `mapRoute`'s extname strip can't eat a dotted
+ * slug segment (`v1.2`). A slug that trims to nothing falls back. The version
+ * prefixes the mapped route *after* `mapRoute` runs: the mapped route is the
+ * version-agnostic key, the config id is prepended verbatim (never
+ * numeric-prefix-stripped), a frontmatter `slug` gets versionized so snapshots
+ * can't collide with the live page, and `translationKey` becomes
+ * version-specific for free. `basePath` is not applied here — it is outermost,
+ * after locale prefixing — so the result reads `{locale?}/{prefix?}/…`.
+ */
+export declare const resolveEntryRoute: (entry: Pick<SourceEntry, "ref" | "slug">, ext: string, frontmatterSlug: string | undefined, ctx: RouteContext) => EntryRoute;
+/** The route a logical route publishes at in one locale, base path excluded. */
+export declare const localizedRoute: (logicalRoute: string, locale: string, i18n: ResolvedI18nConfig | undefined) => string;
+/** The per-locale page records and diagnostics from one source entry. */
+export interface NormalizedEntry {
+    pages: PageRecord[];
+    diagnostics: Diagnostic[];
+}
+/**
+ * Normalize one source entry into per-locale `PageRecord`s. This is the single
+ * funnel every adapter's entries pass through, so route mapping, heading/link
+ * extraction, and meta validation are identical regardless of origin.
+ */
+export declare const normalizeEntry: (entry: SourceEntry, ctx: NormalizeContext) => NormalizedEntry;