blume 1.7.2 → 2.0.0

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

@@ -0,0 +1,138 @@
+import type { Diagnostic } from "./types.ts";
+/**
+ * Cheap pre-filter so include-free content (the overwhelmingly common case)
+ * skips the line scan and file reads entirely.
+ */
+export declare const hasIncludeStatements: (text: string) => boolean;
+/** The attributes an include statement supports. */
+export interface IncludeAttributes {
+    /** Force code-block mode with this language (even for `.md`/`.mdx`). */
+    lang?: string;
+    /** Fence meta string in code-block mode (e.g. `title="lib.ts"`). */
+    meta?: string;
+}
+/** A parsed include statement. */
+export interface IncludeStatement {
+    target: string;
+    attributes: IncludeAttributes;
+}
+/**
+ * Parse one trimmed line as an include statement, or `null` when it isn't
+ * one. Only `lang` and `meta` are meaningful; unknown attributes parse and
+ * are ignored so a future attribute degrades gracefully on older versions.
+ */
+export declare const parseIncludeStatement: (line: string) => IncludeStatement | null;
+/**
+ * Parse one raw `.md` source line as an include statement, applying the
+ * line-level rules the renderer sees: a line indented like code (4 spaces or
+ * a tab) is an indented code block, shown literally rather than spliced. The
+ * render plugin's `.md` visitors share this so the two halves can't drift.
+ */
+export declare const parseIncludeLine: (line: string) => IncludeStatement | null;
+/** What a line that may open an include statement turned out to be. */
+export type IncludeMatch = 
+/** A statement, ending on line `end` (the same line when it isn't wrapped). */
+{
+    kind: "statement";
+    end: number;
+    statement: IncludeStatement;
+}
+/** A line that opens `<include` but no statement Blume can read. */
+ | {
+    kind: "malformed";
+}
+/** Not an include statement at all. */
+ | {
+    kind: "none";
+};
+/**
+ * Read the include statement opening at `lines[index]`, if any. A statement
+ * sits on a line of its own, or — as a formatter wraps a long one — runs from a
+ * line opening `<include` to the next line closing `</include>`, with no blank
+ * line between (the path on its own line, attributes on one line or several):
+ *
+ * ```mdx
+ * <include lang="ts" meta='title="config.ts"'>
+ *   ./examples/config.ts
+ * </include>
+ * ```
+ *
+ * The lines' trimmed text joins into the one-line form, so both parse by the
+ * same rules. In `.md` a first line indented like code is a code block, never
+ * a statement. A line that opens `<include` but doesn't close into a
+ * statement is `malformed`, so the author hears about it instead of the page
+ * rendering the raw tag. Shared by the string-level scanner and the render
+ * plugin so they splice exactly the same statements.
+ */
+export declare const matchIncludeStatement: (lines: readonly string[], index: number, format: "md" | "mdx") => IncludeMatch;
+/**
+ * The warning for a line that opens `<include` but isn't a statement Blume can
+ * read — it renders as written, so a silent miss would ship a raw tag.
+ */
+export declare const malformedIncludeDiagnostic: (file: string, line: number) => Diagnostic;
+/**
+ * Advance the HTML comment state across one `.md` line — the render plugin's
+ * half of the comment rule (a statement inside `<!-- -->` never splices),
+ * sharing the same tracking the string-level scanner uses.
+ */
+export declare const advanceHtmlCommentState: (line: string, inComment: boolean) => boolean;
+/** Provenance of one line of expanded output. */
+export interface LineOrigin {
+    /** Absolute path of the file the line came from. */
+    file: string;
+    /** 1-based line number within that file's raw source. */
+    line: number;
+}
+/** The result of expanding a document's include statements. */
+export interface IncludeExpansion {
+    /** The document with every include statement replaced by its content. */
+    text: string;
+    /** Per output line: the source file and raw-file line it came from. */
+    origins: LineOrigin[];
+    /** Absolute paths of every file included, transitively. */
+    includes: string[];
+    /** Structured errors (missing target, cycle, escape); statements with an
+     * error stay verbatim in the output. */
+    errors: Diagnostic[];
+}
+/**
+ * Expand a document's include statements at the string level. `lineOffset`
+ * shifts the includer's own recorded origin lines — pass the stripped front
+ * matter block's height when `body` is the stripped text, so origins point at
+ * real file lines. Never throws: unresolvable statements stay verbatim and
+ * surface through `errors`.
+ */
+export declare const expandIncludes: (body: string, options: {
+    /** Absolute path of the file being expanded. */
+    sourcePath: string;
+    /** The owning source's content root; bounds include resolution. */
+    contentRoot?: string;
+    /** Raw-file line of `body`'s first line, minus one (default `0`). */
+    lineOffset?: number;
+}) => Promise<IncludeExpansion>;
+/**
+ * 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
+ * needs each target spliced). Shares every semantic with
+ * {@link expandIncludes}.
+ */
+export declare const expandIncludeTarget: (statement: IncludeStatement, options: {
+    sourcePath: string;
+    contentRoot?: string;
+}) => Promise<{
+    text: string;
+    errors: Diagnostic[];
+} | {
+    error: Diagnostic;
+}>;
+/**
+ * Invert the scan's page → included-partials edges into the partial →
+ * including-pages map `includeHmrPlugin` reads (`generated/includes.json`),
+ * so editing a partial invalidates every page that splices it. Localized
+ * pages share a source path, hence the dedupe. Shared by `generateRuntime`
+ * and `eject`, whose configs both wire the plugin at the same path.
+ */
+export declare const buildIncludeGraph: (pages: {
+    sourcePath?: string;
+    includes?: string[];
+}[]) => Record<string, string[]>;

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

@@ -0,0 +1,47 @@
+import type { Diagnostic } from "./types.ts";
+/** Normalized form of the `lastModified` config. */
+export interface ResolvedLastModified {
+    enabled: boolean;
+    source: "git" | "frontmatter";
+}
+/** 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.
+ */
+export declare const parseGitLog: (output: string) => Map<string, string>;
+/**
+ * The toplevel of the repository containing `root`, or null when git is
+ * unavailable or the project isn't a repo. Callers use it to decide which
+ * content roots a `git log` pathspec can cover at all — a root outside the
+ * repository would fail the log outright and can never yield dates.
+ */
+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
+ * (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.
+ */
+export declare const gitLastModifiedTimes: (root: string, contentRoots: string[], sourcePaths: string[], repositoryRoot?: string | null) => Map<string, string>;
+/**
+ * Whether the repository containing `root` is a shallow clone. Returns false
+ * when git is unavailable or the project isn't a repo — those cases already
+ * yield no dates at all, and the shallow warning would only mislead.
+ */
+export declare const isShallowGitRepository: (root: string) => boolean;
+/**
+ * A warning for git-derived dates silently missing because the build ran in a
+ * shallow clone — the default on Vercel and `actions/checkout`, where `git log`
+ * only sees the last few commits, so most pages get no date and the sitemap's
+ * `<lastmod>` / "Last updated" stamps quietly disappear in production while
+ * working locally. Empty when every page got a date or the clone isn't
+ * shallow.
+ */
+export declare const lastModifiedShallowWarning: (root: string, undatedCount: number) => Diagnostic[];

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

@@ -0,0 +1,95 @@
+import type { LocaleRouting } from "./i18n.ts";
+import type { ContentGraph, Diagnostic, PageRecord } from "./types.ts";
+/** The page a relative link is written on, as the resolver sees it. */
+export interface RelativeLinkBase {
+    /** Whether the page is its folder's index (its route is its directory). */
+    isIndex: boolean;
+    /** The page's own route, base path included. */
+    route: string;
+}
+/**
+ * Where a relative page link written on `from` lands: a root-relative route
+ * with the authored `?query#hash` kept — or `undefined` when `href` isn't a
+ * relative page link (a root-relative path, a bare `#fragment` or `?query`,
+ * an external URL or other scheme, or a relative asset like `./diagram.png`).
+ *
+ * The one reading `blume validate` checks links against and the Markdown
+ * pipeline rewrites them to, so the built `href`, the link check, and the
+ * browser agree. Relative paths resolve file-style: a leaf page's links
+ * resolve against its parent directory, while an index page's route already is
+ * its directory — `./install` on `guides/index.mdx` (`/guides`) lands on
+ * `/guides/install`, where a browser reading the slashless URL would go to
+ * `/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
+ * `resolveFile`, or for a file it doesn't know, the target resolves
+ * route-relative with the extension dropped.
+ *
+ * Any other extension (`./diagram.png`) marks an asset, except where a page
+ * publishes at the resolved path: `hasRoute` answers that, so a dotted page
+ * 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;
+/**
+ * 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
+ * `localeTokens` before the extension (`index.fr.mdx` under the `dot` locale
+ * parser, `index.$.mdx` for a file shared by every locale).
+ */
+export declare const isIndexFileName: (name: string, localeTokens?: readonly string[]) => boolean;
+/** Where content files publish, for resolving file links (`./setup.mdx`). */
+export interface FileRouteIndex {
+    /**
+     * Absolute source path → the route that file publishes at. A file shared by
+     * every locale publishes once per locale; the default locale's route stands
+     * for it (a link from a localized page moves into that locale afterwards,
+     * exactly as the rendered link does). Fallback copies render another
+     * locale's file, so they never stand for it.
+     */
+    bySource: Map<string, string>;
+    /**
+     * A default-locale page's locale-stripped path (`navPath`) → its route. A
+     * page in a locale folder that links a sibling not translated yet
+     * (`fr/guides/setup.mdx` missing) means the default tree's file
+     * (`guides/setup.mdx`), whose route — its own `slug` included — then moves
+     * into the reader's locale onto the fallback copy.
+     */
+    byDefaultNavPath: Map<string, string>;
+}
+/** The linking side of a file link: where the page's source lives. */
+export interface FileLinkBase {
+    navPath: string;
+    sourcePath: string;
+}
+export declare const buildFileRouteIndex: (pages: readonly PageRecord[], i18n: LocaleRouting | null) => FileRouteIndex;
+/**
+ * The route a file link written on `from` lands on: the linked file's own
+ * route, or — when a locale folder doesn't have that file yet — the default
+ * tree's file at the same place.
+ */
+export declare const routeOfLinkedFile: (index: FileRouteIndex, from: FileLinkBase, path: string) => string | undefined;
+/**
+ * Validate every link discovered in the content graph: internal page links and
+ * anchors against the route map, asset links against the public dir, and
+ * (opt-in) external links over the network.
+ */
+export declare const validateLinks: (graph: ContentGraph, options: {
+    /** Site-wide route mount point (`""` or `/seg`); routes and redirects carry it. */
+    basePath?: string;
+    /**
+     * Servable routes the graph can't know: custom `.astro` pages and generated
+     * routes (e.g. the `/changelog` index). Mounted outside `basePath` (they're
+     * injected at their pattern), so they are *not* based here — mirroring the
+     * full-route-set resolution in `nav-diagnostics.ts`/`generateRuntime`.
+     */
+    extraRoutes?: string[];
+    /** Locale routing when i18n is on; links then resolve into the page's locale. */
+    i18n?: LocaleRouting | null;
+    publicDir: string | null;
+    checkExternal?: boolean;
+    /** Configured redirects; their `from` paths count as valid link targets. */
+    redirects?: {
+        from: string;
+    }[];
+}) => Promise<Diagnostic[]>;

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

@@ -0,0 +1,60 @@
+import type { LocaleRouting } from "./i18n.ts";
+/**
+ * Locale-aware resolution of content links.
+ *
+ * Authors write internal links as if mounted at the default locale's root
+ * (`[x](/guide)`, `<Card href="/guide">`), and translated pages are usually
+ * copies of the source with the same links — so read on `/fr/…`, a link would
+ * otherwise drop the reader back into the default language. These helpers move
+ * such a link to the reader's locale (`/fr/guide`) when that route is served
+ * (a real translation or a materialized fallback page), and leave it alone
+ * otherwise: an explicit cross-locale link (`/de/guide`), a custom `.astro`
+ * page or generated route that has no per-locale variant, or a missing
+ * translation on a site with fallbacks disabled all keep their authored
+ * target rather than pointing at a 404.
+ *
+ * The rewrite runs at render time (`components/layout/LocaleLinks.astro`)
+ * because content is compiled once per file but served per route: a fallback
+ * route renders the fallback locale's file under the missing locale's URL, and
+ * a shared `page.$.mdx` renders under every locale. The link checker applies
+ * the same resolution so anchors are validated against the page a reader lands
+ * on.
+ */
+/** A route set, as the runtime (`Set`) or the checker (a predicate) sees it. */
+export interface RouteSet {
+    has: (route: string) => boolean;
+}
+export interface LocalizeLinkOptions {
+    /** Site-wide route mount point (`""` or `/seg`); routes carry it. */
+    basePath: string;
+    i18n: LocaleRouting;
+    /** Locale of the page the link is rendered on. */
+    locale: string;
+    /** Every served route, base-prefixed like `path` (no `deployment.base`). */
+    routes: RouteSet;
+}
+/**
+ * Move a base-prefixed, fragment-less internal path into `locale` when that
+ * route is served, else return it unchanged. Idempotent: a path already under
+ * any configured locale prefix is never re-prefixed.
+ */
+export declare const localizeLinkPath: (path: string, options: LocalizeLinkOptions) => string;
+export interface LocalizeHrefOptions extends LocalizeLinkOptions {
+    /** `deployment.base` (Astro's `BASE_URL`), layered over `basePath` in hrefs. */
+    deployBase: string;
+}
+/**
+ * Localize a rendered `href`: external URLs, relative paths, bare fragments, and
+ * asset links pass through; a root-relative page link keeps its `?query` and
+ * `#fragment` and its `deployment.base` layer around the localized path.
+ */
+export declare const localizeHref: (href: string, options: LocalizeHrefOptions) => string;
+/**
+ * Rewrite every `<a href>` in rendered content HTML through `rewrite`. Code
+ * blocks are HTML-escaped (`&lt;a`), and island props live on
+ * `<astro-island>`, so neither is touched.
+ */
+export declare const localizeContentLinks: (html: string, rewrite: (href: string) => string) => string;
+export declare const routeSetFor: (routes: readonly {
+    path: string;
+}[]) => Set<string>;

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

@@ -0,0 +1,17 @@
+import type { ResolvedConfig } from "./schema.ts";
+import type { BlumeManifest, ContentGraph, PageRecord, ProjectContext } from "./types.ts";
+/** The current manifest schema version. */
+export declare const MANIFEST_VERSION = 1;
+/**
+ * Whether a page may be indexed on its own merits — not author-excluded and not
+ * hidden (unless hidden pages are opted in). This is independent of whether the
+ * 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;
+/** Build the runtime manifest that bridges core and the generated Astro app. */
+export declare const buildManifest: (options: {
+    context: ProjectContext;
+    config: ResolvedConfig;
+    graph: ContentGraph;
+}) => BlumeManifest;

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

@@ -0,0 +1,38 @@
+import type { FolderMeta } from "./schema.ts";
+import type { Diagnostic } from "./types.ts";
+/** A filesystem content source to scan for folder meta: its on-disk root and
+ * optional route prefix. The prefix is folded into every key so meta lines up
+ * with the sidebar group path, which carries the same prefix. */
+export interface FolderMetaSource {
+    root: string;
+    prefix?: string;
+}
+/**
+ * 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
+ * root (`""`/the prefix itself for a source's root directory), so meta matches
+ * the prefixed sidebar group path. A bare string is shorthand for a single,
+ * unprefixed source (the default project layout). `meta.$.*` files are returned
+ * in `shared` — folder meta that applies to that directory in every locale (a
+ * locale-specific `meta.*` overrides it). Each file default-exports an object or
+ * a (sync/async) function returning one.
+ *
+ * `localeDirs` names the top-level locale directories of a `dir`-parser i18n
+ * project. Navigation looks locale meta up as `locale/<group path>` where the
+ * group path starts with the source prefix, so a locale directory found at a
+ * source root is hoisted in front of the prefix (`docs/fr/guides/meta.ts` keys
+ * to `fr/docs/guides`, not `docs/fr/guides`).
+ *
+ * `versionDirs` names the archived-version snapshot directories, which sit
+ * outermost on disk — a locale directory inside a snapshot is one level deeper.
+ * Both are hoisted, version first (`v1.0/fr/guides/meta.ts` keys to
+ * `v1.0/fr/<prefix>/guides`), matching navigation's version-aware meta prefix.
+ */
+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[];
+}>;

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

@@ -0,0 +1,26 @@
+import type { Diagnostic, Navigation, PageRecord } from "./types.ts";
+/** Warn about icon names that aren't in Blume's set (skipping image/SVG icons). */
+export declare const validateNavIcons: (navigation: Navigation) => Diagnostic[];
+/**
+ * Warn about unknown icons on curated `search.popular` links. Same accepted
+ * input shapes as nav icons — resolved to markup on the server for the island.
+ */
+export declare const validateSearchPopularIcons: (popular: {
+    icon?: string;
+    label: string;
+}[]) => Diagnostic[];
+/**
+ * Warn when a config-linked tab/selector target has no matching page. `routes`
+ * must be the full set of servable routes — content, custom `.astro` pages, and
+ * generated routes — so this runs where all three are known (`generateRuntime`),
+ * not in the content-only graph build.
+ */
+export declare const validateNavTargets: (navigation: Navigation, routes: Set<string>) => Diagnostic[];
+/**
+ * Structural navigation diagnostics that need only the built navigation +
+ * content pages: duplicate sidebar labels at a level, and hidden pages that
+ * still surface in the sidebar (so pagination lands on them). Target existence
+ * is checked separately by {@link validateNavTargets}, which needs the full
+ * route set.
+ */
+export declare const validateNavStructure: (navigation: Navigation, pages: PageRecord[]) => Diagnostic[];

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

@@ -66,4 +66,10 @@ export declare const buildNavigation: (pages: PageRecord[], options: {
      * into in place; omit to discard.
      */
     diagnostics?: Diagnostic[];
+    /**
+     * Routes served outside the content tree that a tab `path` may name
+     * directly (the generated changelog index), so the tab links there instead
+     * of falling back to its section's first page.
+     */
+    extraRoutes?: ReadonlySet<string>;
 }) => Navigation;

package/dist/types/core/node-require.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Node's own `require`, for the SDKs and heavy modules Blume loads only when a
+ * feature needs them. Resolution starts from this file, inside the installed
+ * package, exactly like the `import()` it stands in for, and Node 22.12+ loads
+ * ES modules through it too.
+ *
+ * Never `import()` in their place. When Node can't import the generated Astro
+ * config itself — it refuses to strip types from TypeScript under
+ * `node_modules`, which is where an installed Blume's runtime source lives —
+ * Astro evaluates the config, and every Blume module it reaches, in a Vite
+ * module runner that it closes as soon as the config has loaded. A dynamic
+ * `import()` in one of those modules resolves through that runner, so a call
+ * made any later (an `astro:build:done` hook, a Markdown plugin) throws "Vite
+ * module runner has been closed". `require` is Node's, so it works however the
+ * calling module was evaluated. The repo itself never sees the failure: its
+ * workspace link puts Blume outside `node_modules`, so Node imports the config
+ * natively.
+ */
+export declare const nodeRequire: NodeJS.Require;

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

@@ -0,0 +1,13 @@
+/**
+ * Derive a valid npm package name from a directory name, falling back to
+ * `docs` when nothing usable remains.
+ */
+export declare const toPackageName: (raw: string) => string;
+/**
+ * A minimal, runnable `package.json` body for a Blume project: the `blume`
+ * dependency pinned to the installed version plus `dev`/`build`/`doctor`
+ * scripts, so `npm install && npm run dev` works immediately. Shared by
+ * `blume init` and the migrators, which scaffold one when a project has none.
+ * `extraDeps` adds source SDKs (e.g. `@notionhq/client`) beside `blume`.
+ */
+export declare const blumePackageJson: (name: string, extraDeps?: Record<string, string>) => string;

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

@@ -0,0 +1,42 @@
+import type { DiagnosticSeverity } from "./types.ts";
+export declare const PROBE_CONCURRENCY = 8;
+export declare const PROBE_TIMEOUT_MS = 10000;
+/** The outcome of a single HTTP probe, with failures normalized rather than thrown. */
+export interface ProbeResult {
+    ok: boolean;
+    status?: number;
+    timedOut?: boolean;
+    error?: string;
+    /** Whether the request was redirected before landing on `status`. */
+    redirected?: boolean;
+    /** The URL finally landed on, after following redirects. */
+    finalUrl?: string;
+    /** `Content-Encoding` of the response, when the server set one. */
+    encoding?: string | null;
+    /** Wall-clock milliseconds for the request. */
+    ms?: number;
+    /** `X-Robots-Tag` of the response, when the server set one. */
+    robotsTag?: string | null;
+}
+/**
+ * Probe a single URL: HEAD first, falling back to GET.
+ *
+ * Plenty of servers reject HEAD outright (405/501) or drop the connection, so a
+ * HEAD-only probe would report healthy pages as dead.
+ */
+export declare const probe: (url: string, options?: {
+    timeoutMs?: number;
+}) => Promise<ProbeResult>;
+/** Grade a probe result into a severity + detail, or null when the URL is fine. */
+export declare const gradeExternal: (result: ProbeResult) => {
+    severity: DiagnosticSeverity;
+    detail: string;
+} | null;
+/**
+ * Probe many URLs with bounded concurrency, deduplicating first. Returns a map
+ * from URL to its result — the caller decides what each one means.
+ */
+export declare const probeAll: (urls: readonly string[], options?: {
+    concurrency?: number;
+    timeoutMs?: number;
+}) => Promise<Map<string, ProbeResult>>;

package/dist/types/core/project-graph.d.ts

@@ -0,0 +1,51 @@
+import type { ResolvedConfig } from "./schema.ts";
+import type { ContentSource } from "./sources/types.ts";
+import type { BlumeManifest, ContentGraph, Diagnostic, ExampleLookup, ProjectContext } from "./types.ts";
+/** Build mode: drafts are kept in `dev` and dropped in `build`. */
+export type BuildMode = "dev" | "build";
+/** CLI-supplied overrides applied over the loaded config (see `scanProject`). */
+export interface ConfigOverrides {
+    /** Override `content.root` (`blume dev --content-dir`). */
+    contentRoot?: string;
+}
+/**
+ * Whether `path` sits at or under `dir`. A relative result that is itself
+ * absolute means a different drive root on Windows, which is outside too.
+ */
+export declare const isWithin: (dir: string, path: string) => boolean;
+/** Everything Blume knows about a project after a full scan. */
+export interface BlumeProject {
+    mode: BuildMode;
+    context: ProjectContext;
+    config: ResolvedConfig;
+    graph: ContentGraph;
+    manifest: BlumeManifest;
+    diagnostics: Diagnostic[];
+    /** Entries excluded from the graph because their frontmatter failed validation. */
+    droppedPages: number;
+    /** The instantiated content sources, for lazy entry reads (search/AI/raw). */
+    sources: ContentSource[];
+    /**
+     * Whether the config file set `theme.fonts` itself (see
+     * {@link ConfigLoadResult.themeFontsConfigured}); gates OG font derivation.
+     */
+    themeFontsConfigured: boolean;
+    /**
+     * Discovered `examples/` sources keyed by `<Component path>`, attached by the
+     * runtime/eject layer after {@link scanProject} (example discovery is an Astro
+     * concern, so core doesn't run it). Undefined until then; the agent-facing
+     * Markdown downleveler reads it to turn `<Component path="…" />` into the
+     * example's source. Empty when the project has no examples.
+     */
+    examples?: ExampleLookup;
+}
+export declare const scanProject: (root: string, options?: {
+    devServerUrl?: string;
+    mode?: BuildMode;
+    preview?: boolean;
+    refresh?: boolean;
+    /** CLI overrides applied over the loaded config (e.g. `--output`). */
+    overrides?: ConfigOverrides;
+    /** Relocate the generated runtime (e.g. `.blume-verify` for isolation). */
+    runtimeDir?: string;
+}) => Promise<BlumeProject>;

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

@@ -2,6 +2,8 @@ import type { ResolvedConfig } from "./schema.ts";
 import type { ProjectContext } from "./types.ts";
 /** Locate the Blume config file for a project root, if any. */
 export declare const findConfigFile: (root: string) => string | null;
+/** Locate the project's `components.ts`/`.tsx` override file, if any. */
+export declare const findComponentsFile: (root: string) => string | null;
 /**
  * Resolve the generated runtime directory for a project. Defaults to
  * `<root>/.blume`; an override (e.g. `.blume-verify` for an isolated build that

package/dist/types/core/safe-href.d.ts

@@ -0,0 +1,2 @@
+/** Whether a link destination from imported content is safe to keep. */
+export declare const isSafeHref: (href: string) => boolean;

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

@@ -0,0 +1,26 @@
+import type { Root } from "mdast";
+/** A link (or link definition) whose destination isn't safe. */
+export interface UnsafeLinkSpan {
+    /** End offset in the source, exclusive. */
+    end: number;
+    /** Start offset in the source. */
+    start: number;
+    /**
+     * What replaces it: the link's label, escaped so it can't form a link
+     * again; empty for a definition.
+     */
+    text: string;
+}
+/**
+ * The unsafe links in a parsed Markdown tree, in source order: inline and
+ * reference links (autolinks included) and link definitions whose parsed
+ * destination fails {@link isSafeHref}. The parsed `url` is what a browser
+ * would get, character references and all, so `javascript:` is caught.
+ */
+export declare const unsafeLinkSpans: (tree: Root) => UnsafeLinkSpan[];
+/**
+ * Markdown with every unsafe link reduced to its label text and every unsafe
+ * link definition removed. Everything else — safe links, raw HTML, code —
+ * passes through as written.
+ */
+export declare const neutralizeUnsafeLinks: (markdown: string) => string;