blume 2.0.1 → 2.0.2

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

@@ -74,6 +74,13 @@ export declare const strippedLineOffset: (raw: string | undefined, body: string)
 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"> & {
+    /**
+     * Whether the entry's ref is a path of file and folder names whose ordering
+     * prefixes (`01-intro`) sort the sidebar and drop from the route: true for
+     * filesystem sources. A staged source's ref is a slug, a release tag, or a
+     * note name, and keeps its leading numbers.
+     */
+    orderingPrefixes?: boolean;
     /** The source's route prefix (`NormalizeContext["source"]["prefix"]`). */
     prefix?: string;
 };
@@ -123,7 +130,9 @@ export interface EntryRoute extends Pick<EntryPlacement, "locales" | "version">
  * 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
+ * slug segment (`v1.2`). A slug that trims to nothing falls back. Only a
+ * filesystem ref (`ctx.orderingPrefixes`) loses its ordering prefixes; a slug
+ * is a route spelled out, so `2024-year-in-review` stays whole. 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

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

@@ -2,12 +2,21 @@ import type { JsonObject, JsonValue } from "./json.ts";
 import type { ContentSource, SourceContext, SourceEntry } from "./types.ts";
 /** What every REST-backed CMS source needs to be a staged, cached source. */
 export interface RemoteSourceOptions {
+    /**
+     * Throw a `BlumeError` when the source cannot load as configured. Runs
+     * before the cache is consulted: thrown from `fetchEntries` instead, a
+     * misconfiguration would be served over by a stale snapshot with only an
+     * offline warning.
+     */
+    assertConfigured?: () => void;
     /** Pull every entry from the API; called on refresh and on each poll. */
     fetchEntries: () => Promise<SourceEntry[]>;
     name: string;
     /** Opt-in dev polling interval (seconds); omit to freeze for the session. */
     pollInterval?: number;
     prefix?: string;
+    /** The adapter rebuilt on another context (`ContentSource.withContext`). */
+    withContext?: (ctx: SourceContext) => ContentSource;
 }
 /**
  * The staged-source scaffolding a CMS adapter shares: a snapshot cache under
@@ -68,7 +77,8 @@ export interface RemoteFieldMap {
  * when the slug field is missing or slugifies to nothing (pure punctuation),
  * so distinct documents never collapse onto one `untitled.md`; a slashed
  * slug keeps its segments. A string body is Markdown and passes through as
- * `.md`; any other shape goes to the CMS's lowerer, and is written as `.mdx`
+ * `.md`, its unsafe links reduced to their labels; any other shape goes to
+ * the CMS's lowerer, and is written as `.mdx`
  * when `lowersToMdx` (the source has serializers, see `writesMdx`).
  */
 export declare const documentEntry: (doc: JsonObject, fields: Required<RemoteFieldMap>, id: string, lower: (body: JsonValue) => string, draft?: boolean, lowersToMdx?: boolean) => SourceEntry;

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

@@ -1,3 +1,4 @@
+import type { ContentSourceAdapter } from "../../sources/registry.ts";
 import type { ResolvedConfig } from "../schema.ts";
 import type { ProjectContext } from "../types.ts";
 import type { ContentSource } from "./types.ts";
@@ -9,6 +10,17 @@ export interface SourceRuntime {
     preview?: boolean;
     refresh?: boolean;
 }
+/**
+ * The directory under `.blume/cache/<source>/` a source keeps its snapshot in:
+ * one per preview mode and set of adapter options. A preview snapshot holds
+ * drafts, so a published load must never read it, neither as dev's cache-first
+ * snapshot nor as a build's offline fallback; and a snapshot fetched with
+ * another `query` or `fields` is another result, not a cached copy of this
+ * one. `pollInterval` only paces dev re-fetches, so it is left out. A
+ * `custom()` source is a live instance rather than options, so its snapshot
+ * is keyed by preview mode alone.
+ */
+export declare const snapshotKey: (adapter: ContentSourceAdapter, runtime: SourceRuntime) => string;
 /**
  * Build the ordered list of content sources for a project. The config schema
  * already desugared the zero-config shorthand into a single `filesystem()`

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

@@ -35,6 +35,13 @@ export interface SourceEntry {
      * the owning source to expose a `contentRoot` to bound the log's pathspec.
      */
     sourcePath?: string;
+    /**
+     * How many lines of the file at `sourcePath` sit above `body.text`, when
+     * `raw` is not that file's text: a source that rewrites a local file's
+     * front matter (an Obsidian note) sets it, so a diagnostic points at the
+     * line the author wrote. Otherwise the height of `raw`'s front matter.
+     */
+    bodyLineOffset?: number;
     /** Optional provenance for "edit this page". */
     editUrl?: string;
     /** Optional last-modified ISO date supplied by the adapter (non-filesystem). */
@@ -119,6 +126,14 @@ export interface ContentSource {
      * switcher, since every other locale would only repeat the same text.
      */
     readonly monolingual?: boolean;
+    /**
+     * True for a staged source whose entry refs are file and folder names (an
+     * Obsidian vault), so their ordering prefixes (`01 Intro`) sort the sidebar
+     * and drop from the route the way a filesystem source's do. Filesystem
+     * sources always do; other staged refs are slugs and release tags, kept
+     * whole.
+     */
+    readonly orderedNames?: boolean;
     /**
      * Resolved on-disk root, set by sources whose entries live on disk. For
      * filesystem sources it drives folder-meta discovery (scan under this root)
@@ -128,6 +143,13 @@ export interface ContentSource {
      * no local tree.
      */
     readonly contentRoot?: string;
+    /**
+     * The globs a filesystem source reads under `contentRoot`, and the ones it
+     * skips. Folder-meta discovery honors them, so a `meta.ts` outside the
+     * content the source reads is never imported.
+     */
+    readonly include?: readonly string[];
+    readonly exclude?: readonly string[];
     /** Pull every entry. Called once per scan. */
     load: () => Promise<SourceLoadResult>;
     /** Validate the source is usable; throws a BlumeError when not. */
@@ -139,12 +161,21 @@ export interface ContentSource {
      * remote/static sources omit it (content is frozen for the session).
      */
     watch?: (onChange: () => void) => () => void;
+    /**
+     * This source rebuilt on another runtime context. A source passed to
+     * `custom()` is constructed before Blume knows the scan's preview flag,
+     * refresh policy, or runtime directory; Blume rebuilds it on them through
+     * this, so it previews and caches the way the built-in adapter does. The
+     * engine factories (`sanitySource`, `contentfulSource`, …) all set it.
+     */
+    withContext?: (ctx: SourceContext) => ContentSource;
 }
 /** Context passed to `normalizeEntry`, describing the owning source. */
 export interface NormalizeContext {
     source: {
         monolingual?: boolean;
         name: string;
+        orderedNames?: boolean;
         prefix?: string;
         staged: boolean;
     };

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

@@ -306,6 +306,13 @@ export interface Navigation {
      * locale trees.
      */
     brandHref?: string;
+    /**
+     * Where the banner's link points in this locale: `banner.link.href`
+     * localized like a featured link, then mounted under `basePath` (a route
+     * served outside the content tree keeps its own path). Set when the banner
+     * has a link.
+     */
+    bannerHref?: string;
 }
 /** The full content graph: the source of truth for generated modules. */
 export interface ContentGraph {
@@ -392,6 +399,8 @@ export interface RouteManifestEntry {
     fallback?: boolean;
     /** True when the page's source publishes one language only (no switcher). */
     monolingual?: boolean;
+    /** True when front matter `ai.exclude` keeps the page out of llms.txt. */
+    aiExclude?: boolean;
     /** Resolved "last updated" ISO date, when the feature is enabled. */
     lastModified?: string;
 }

package/dist/types/deploy/adapters/node.d.ts

@@ -3,8 +3,11 @@ import type { DeployAdapter, DeployOptions } from "./types.ts";
 export declare const NODE_ADAPTER_PACKAGE = "@astrojs/node";
 /**
  * Options for {@link node}: `output`, `site`, and `base`, plus any option of
- * `@astrojs/node` forwarded verbatim (`mode`, `host`, `port`, …). Blume
- * defaults `mode` to `"standalone"`; an option you pass wins.
+ * `@astrojs/node` forwarded verbatim (`mode`, `staticHeaders`, …). Blume
+ * defaults `mode` to `"standalone"`; an option you pass wins. `host` and
+ * `port` are forwarded too, but `@astrojs/node` replaces both with Astro's
+ * own server settings, so the standalone server listens on `localhost:4321`
+ * unless the `HOST` and `PORT` environment variables are set when it starts.
  */
 export type NodeOptions = DeployOptions;
 export type NodeAdapter = DeployAdapter<"node">;

package/dist/types/deploy/adapters/types.d.ts

@@ -49,6 +49,13 @@ export interface StaticDeployment {
      */
     site?: string;
 }
+/**
+ * `deployment.site`: an absolute http(s) URL, which always has a host. A bare
+ * `z.url()` takes any scheme, so `localhost:4321` (scheme `localhost:`),
+ * `mailto:`, and `javascript:` all passed and became the prefix of every
+ * sitemap entry and canonical link.
+ */
+export declare const siteUrlSchema: z.ZodURL;
 /** The named options' schema; every host adapter extends it with `z.json()` passthrough. */
 export declare const deployOptionsSchema: z.ZodObject<{
     base: z.ZodOptional<z.ZodString>;

package/dist/types/deploy/cloudflare-negotiation.d.ts

@@ -39,8 +39,9 @@
  *
  * Cloudflare does not apply `_headers` to worker-first routes, so the wrapper
  * also re-stamps what the static layer would otherwise add on the routes it
- * takes over: the homepage agent-discovery `Link` header and the Markdown
- * `charset=utf-8` (see `deploy/headers.ts`). The raw `.md`/`.mdx` URLs are
+ * takes over: the homepage agent-discovery `Link` header, the Markdown
+ * `charset=utf-8`, and the sandbox on the SVGs a content source downloaded
+ * (see `deploy/headers.ts`). The raw `.md`/`.mdx` URLs are
  * exempted from worker-first routing with negative rules, keeping their
  * `_headers` treatment and their zero-Worker serving path.
  *

package/dist/types/deploy/headers.d.ts

@@ -1,11 +1,24 @@
 import type { ResolvedConfig } from "../core/schema.ts";
+/** Where the generated endpoint serves content-source images from. */
+export declare const CONTENT_ASSETS_ROOT = "/blume-assets";
 /**
  * The policy a content-source SVG is served with: an opaque origin with
  * scripts off, so an uploaded SVG that carries a `<script>` stays inert when
- * opened directly. The endpoint sends it from the server and dev runtimes;
- * {@link headerRules} carries it to static hosts.
+ * opened directly.
  */
 export declare const SVG_ASSET_POLICY = "sandbox";
+/**
+ * The headers a content-source SVG is served with: the sandbox policy, and no
+ * MIME sniffing. The endpoint sends them from the dev runtime; every host
+ * gets them for the built files — static hosts through {@link headerRules},
+ * server builds through each platform's own mechanism (`deploy/platforms`).
+ */
+export declare const SVG_ASSET_HEADERS: {
+    "Content-Security-Policy": string;
+    "X-Content-Type-Options": string;
+};
+/** The served glob of content-source SVGs, under the deployment base. */
+export declare const svgAssetPath: (config: ResolvedConfig) => string;
 /**
  * One static-host header rule: a served path (a `*` glob spanning path
  * segments, or an exact path) and the header it sets there.
@@ -17,11 +30,9 @@ export interface HeaderRule {
 }
 /**
  * The header rules every static host should apply, in `_headers` glob syntax.
- * The glob carries the served prefix (`{deployment.base}{basePath}` for the
- * Markdown mirrors, `{deployment.base}` for the root `.txt` files) so the rules
- * still match once the site is mounted under a subpath (`/docs/*.md`); the
- * wildcard spans path segments, so a nested route like `/docs/ja/intro.md`
- * matches too.
+ * The glob carries the deployment base so the rules still match once the site
+ * is mounted under a subpath (`/docs/*.md`); the wildcard spans path
+ * segments, so a nested route like `/docs/ja/intro.md` matches too.
  *
  * When a homepage `Link` header is provided (see `ai/link-headers.ts`), an
  * exact-path rule for the root page advertises the agent-discovery resources —
@@ -33,6 +44,19 @@ export declare const headerRules: (config: ResolvedConfig, homeLinkHeader?: stri
  * indented header line, in the two-space format Netlify and Cloudflare read.
  */
 export declare const buildNetlifyHeaders: (config: ResolvedConfig, homeLinkHeader?: string | null) => string;
+/** One entry of Netlify's Frameworks API config `headers` array. */
+export interface NetlifyConfigHeaders {
+    for: string;
+    values: Record<string, string>;
+}
+/**
+ * The {@link headerRules} as Netlify Frameworks API `headers` entries
+ * (`.netlify/v1/config.json`), one per path with every header it sets. A
+ * `netlify()` server build reads no `_headers` file, so it carries the same
+ * rules here, in the `for`/`values` form that follows `netlify.toml`'s
+ * `[[headers]]` and the same path syntax as `_headers`.
+ */
+export declare const buildNetlifyConfigHeaders: (config: ResolvedConfig, homeLinkHeader?: string | null) => NetlifyConfigHeaders[];
 /** One entry of `vercel.json`'s `headers` array. */
 export interface VercelHeader {
     headers: {

package/dist/types/deploy/node-headers.d.ts

@@ -10,6 +10,12 @@ import type { BuildLog } from "./platforms/types.ts";
  * (`deploy/headers.ts`) that a Node server has no file to read from. The Markdown
  * and text charsets need no rule here: `send` already adds `charset=UTF-8` to
  * `text/*` types.
+ *
+ * The same wrapper answers the configured redirects. Astro's own handler
+ * honors a redirect's configured status only when its destination resolves
+ * to a discrete route, and Blume serves every page from `[...slug]`, so a
+ * `302` or `307` would go out as a `301` or `308` — permanent redirects that
+ * browsers cache.
  */
 /** The headers one exact served path (deployment base included) gets. */
 export interface NodeHeaderRule {
@@ -23,20 +29,49 @@ export declare const NODE_ASTRO_ENTRY_FILE = "astro-entry.mjs";
 /** The header rules for this config, merged per path. */
 export declare const nodeHeaderRules: (config: ResolvedConfig) => NodeHeaderRule[];
 /**
- * The entry that replaces Astro's: it stamps the rules' headers on the
- * response, then hands the request to Astro's handler. `send` leaves a
- * Content-Type that is already set alone, so the registered media type wins.
+ * The configured redirects the wrapper answers, keyed by served path (the
+ * trailing slash trimmed), each to its `Location` and exact status.
+ */
+export type NodeRedirects = Record<string, [string, number]>;
+/**
+ * The configured redirects, based the way the host matches them (see
+ * `platformRedirects`) and keyed for the wrapper's lookup, the `Location`
+ * percent-encoded as Astro sends it. A redirect at a content route's own path
+ * is left out: the prerendered page owns that URL, and the static handler
+ * serves it before Astro's redirect ever could.
+ */
+export declare const nodeRedirects: (project: BlumeProject) => NodeRedirects;
+/** What the wrapper needs beyond the header rules. */
+export interface NodeEntryOptions {
+    /** `deployment.base`, normalized (`""` at the root). */
+    base?: string;
+    /** The configured redirects, from {@link nodeRedirects}. */
+    redirects?: NodeRedirects;
+}
+/**
+ * The entry that replaces Astro's: it answers a configured redirect with its
+ * exact status, and otherwise stamps the rules' headers on the response and
+ * hands the request to Astro's handler. `send` leaves a Content-Type that is
+ * already set alone, so the registered media type wins.
+ *
+ * A rule matches the file the static handler will serve, not the raw URL:
+ * Astro strips the base when it leads the path and serves the rest from the
+ * client directory either way, and `send` decodes and normalizes the path —
+ * so `/docs/blume-assets/a.sv%67`, `/blume-assets/a.svg`, and
+ * `/docs//x/../blume-assets/a.svg` are all the same SVG. The comparison
+ * ignores case, as a case-insensitive disk and `send`'s MIME lookup do.
  *
  * It keeps Astro's contract — the `handler`, `options`, and `startServer`
  * exports `astro preview` and a middleware-mode host import — and its
  * autostart: Astro's entry is imported with autostart off (the env var is read
  * when that module evaluates, so the import has to be dynamic), and the
- * wrapper starts the server itself with its listener in front of Astro's.
+ * wrapper starts the server itself, taking over its request listener so a
+ * redirect is answered before Astro sees the request.
  */
-export declare const nodeEntryWrapper: (rules: readonly NodeHeaderRule[]) => string;
+export declare const nodeEntryWrapper: (rules: readonly NodeHeaderRule[], options?: NodeEntryOptions) => string;
 /**
- * Put the header wrapper in front of a Node server build's entry. A build
- * with no rule (no API catalog, AI catalog, MCP server, signatures directory,
- * or downloaded content assets) leaves Astro's entry alone.
+ * Put the wrapper in front of a Node server build's entry. A build with no
+ * rule (no API catalog, AI catalog, MCP server, signatures directory, or
+ * downloaded content assets) and no redirect leaves Astro's entry alone.
  */
 export declare const wrapNodeEntry: (project: BlumeProject, log: BuildLog) => Promise<void>;

package/dist/types/deploy/platforms/netlify.d.ts

@@ -1,6 +1,31 @@
-import type { DeployPlatform, RedirectFile } from "./types.ts";
-/** `_redirects`, the format Netlify and Cloudflare Pages/Workers read. */
+import type { BlumeProject } from "../../core/project-graph.ts";
+import type { BuildLog, DeployPlatform, RedirectFile } from "./types.ts";
+/**
+ * `_redirects`, the format Netlify and Cloudflare Pages/Workers read, in the
+ * form both accept: a static build for Cloudflare, or for no named host.
+ */
 export declare const REDIRECTS_FILE: RedirectFile;
+/**
+ * `_redirects` for a `netlify()` static build, every rule forced (`301!`).
+ * Astro writes a redirect page at each `from` (`dist/old/index.html`), and
+ * Netlify serves a file that exists ahead of an unforced rule, so without the
+ * flag that page would answer with a 200 instead of the redirect.
+ */
+export declare const NETLIFY_REDIRECTS_FILE: RedirectFile;
+/** The Frameworks API config, once the build surfaced it to the project root. */
+export declare const NETLIFY_CONFIG_FILE: string;
+/**
+ * Carry the static header rules into a server build. A static `netlify()`
+ * build gets them from `_headers` (see `deploy/artifacts.ts`), but a server
+ * build's header rules go in the Frameworks API config the adapter writes
+ * (`.netlify/v1/config.json`, beside its own `Cache-Control` rule for
+ * `/_astro/*`), which follows the same rules as `netlify.toml`'s
+ * `[[headers]]`: the charset on the raw Markdown and text files, the homepage
+ * `Link` header, the discovery files' media types and CORS header, and the
+ * sandbox on downloaded SVGs, which Netlify serves from the publish directory
+ * as static files, so the prerendered endpoint's own headers never ship.
+ */
+export declare const emitNetlifyHeaders: (project: BlumeProject, log: BuildLog) => Promise<void>;
 /**
  * Netlify. A server build runs on Netlify Functions from the Frameworks API
  * tree the adapter writes to `.netlify/v1`, relative to the Astro root —

package/dist/types/deploy/platforms/node.d.ts

@@ -2,10 +2,11 @@ import type { DeployPlatform } from "./types.ts";
 /**
  * A self-hosted Node server. The standalone server in `dist/server` serves
  * `dist/client` through its own static handler, which has no `_headers` or
- * `_redirects` support — redirects are answered at request time from the
- * Astro config, and a header file written there would be inert. The headers
- * the discovery files need come from a wrapper around the server entry
- * instead (`deploy/node-headers.ts`). No platform env to detect: the site URL
- * has to be configured.
+ * `_redirects` support, so a file written there would be inert. A wrapper
+ * around the server entry (`deploy/node-headers.ts`) sets the headers the
+ * discovery files and downloaded SVGs need instead, and answers the
+ * configured redirects with their exact status, which Astro's own handler
+ * would default to 301 or 308. No platform env to detect: the site URL has to
+ * be configured.
  */
 export declare const nodePlatform: DeployPlatform;

package/dist/types/deploy/platforms/types.d.ts

@@ -89,6 +89,13 @@ export interface DeployPlatform {
     kind: DeployAdapterKind;
     /** Whether a server build honors `Accept: text/markdown` at the content URLs. */
     negotiatesMarkdown: boolean;
+    /**
+     * The host CLI command that deploys a preview, for a platform whose
+     * `@astrojs/*` adapter has no local preview server: Astro's `preview`
+     * throws for its server build, so `blume preview` points here instead. Null
+     * when the adapter can preview a server build locally, or there is none.
+     */
+    previewDeploy: string | null;
     /**
      * Whether the platform applies a `_headers` file to the static assets it
      * serves, per output mode.

package/dist/types/deploy/platforms/vercel.d.ts

@@ -26,7 +26,8 @@ export declare const emitVercelNegotiation: (project: BlumeProject, log: BuildLo
  * `@vercel/nft` dependency trace is rooted there too, and tracing from the
  * hidden runtime silently drops the function's chunks and `node_modules`.
  * Static assets are served from the tree's `static/` half, so the deploy
- * artifacts are written there; headers arrive through the routing config
- * rather than a `_headers` file, which Vercel never reads.
+ * artifacts are written there; headers (the discovery files', the sandbox on
+ * downloaded SVGs) arrive through the routing config rather than a
+ * `_headers` file, which Vercel never reads.
  */
 export declare const vercelPlatform: DeployPlatform;

package/dist/types/deploy/redirects.d.ts

@@ -38,8 +38,13 @@ export declare const applyBaseToPlatformRedirects: (redirects: Redirect[], baseP
  * exemptions both compare these paths against real served URLs.
  */
 export declare const platformRedirects: (config: ResolvedConfig) => Redirect[];
-/** `_redirects` text (Netlify + Cloudflare Pages): `from to status` per line. */
-export declare const buildNetlifyRedirects: (redirects: Redirect[]) => string;
+/**
+ * `_redirects` text (Netlify + Cloudflare Pages): `from to status` per line.
+ * `force` appends Netlify's `!` to each status (`301!`), so the rule wins over
+ * the redirect page Astro writes at `from`; Cloudflare, which always applies
+ * its rules first, rejects a line carrying it.
+ */
+export declare const buildNetlifyRedirects: (redirects: Redirect[], force?: boolean) => string;
 /**
  * `vercel.json` contents with a `redirects` array, and a `headers` array when
  * header rules are given (see `buildVercelHeaders`). Uses `statusCode` (Vercel's

package/dist/types/deploy/vercel-negotiation.d.ts

@@ -101,9 +101,10 @@ export declare const buildNegotiationRoutes: (routePaths: readonly string[], hom
  * `404.md`, `notFound.json` for `404.json`), its routes go into the miss
  * phase right before the adapter's `/404.html` fallback — and nowhere when
  * that fallback is absent, since a `dest` with no file behind it would serve
- * nothing. Returns the updated JSON
+ * nothing. With `svgAssets`, a main-phase route also sandboxes the SVGs a
+ * content source downloaded (see {@link svgAssetRoute}). Returns the updated JSON
  * text (tab-indented, like the adapter's own output), or `null` when there is
  * nowhere safe to splice: an unparsable config, no `routes` array, or no
  * `handle: "filesystem"` marker to anchor the splice.
  */
-export declare const injectNegotiationRoutes: (configText: string, routePaths: readonly string[], homeLinkHeader?: string | null, contentTypeOverrides?: Record<string, string>, homeTokens?: number, notFound?: NotFoundVariants, corsPaths?: readonly string[]) => string | null;
+export declare const injectNegotiationRoutes: (configText: string, routePaths: readonly string[], homeLinkHeader?: string | null, contentTypeOverrides?: Record<string, string>, homeTokens?: number, notFound?: NotFoundVariants, corsPaths?: readonly string[], svgAssets?: boolean) => string | null;

package/dist/types/openapi/model.d.ts

@@ -1,5 +1,5 @@
 import type { Document, OperationObject } from "@scalar/openapi-types/3.1";
-import type { AsyncApiAction, AsyncApiDocument } from "./asyncapi.ts";
+import type { AsyncApiAction, AsyncApiDocument, AsyncApiSpecValue } from "./asyncapi.ts";
 import type { GraphqlDocument, GraphqlMember } from "./graphql.ts";
 import type { ReferenceKind } from "./references.ts";
 export { slugify } from "./references.ts";
@@ -46,7 +46,10 @@ export interface ApiOperationRef {
     /** The channel the operation acts on (AsyncAPI only). */
     channelId?: string;
 }
-/** A tag/section, in first-seen order. */
+/**
+ * A tag/section: the spec's declared tags in their declared order, then any
+ * undeclared tag an operation uses, in first-seen order.
+ */
 export interface ApiTagRef {
     slug: string;
     name: string;
@@ -114,6 +117,15 @@ export interface SpecAddresses {
  * live endpoint stands in.
  */
 export declare const specAddresses: (spec: ApiSpecData) => SpecAddresses;
+/**
+ * A server URL template — an OpenAPI `servers[].url`, an AsyncAPI server's
+ * `host` or `pathname` — with each `{variable}` replaced by the `default` its
+ * `variables` map declares. Code samples, the playground's Send, and the
+ * proxy allowlist all need a real address, and
+ * `https://{region}.api.example.com` is not one. A variable the map doesn't
+ * define with a default (invalid per both specs) stays templated.
+ */
+export declare const withServerDefaults: (template: string, variables: AsyncApiSpecValue) => string;
 /**
  * Assign each distinct tag name a unique slug. `slugify` can collapse
  * different names onto one value — any two punctuation-only tags (`!!!`,
@@ -142,16 +154,18 @@ export interface ExtractedOperations extends CollectedOperations {
 }
 /**
  * The collector behind both extractors (OpenAPI here, AsyncAPI in
- * `asyncapi.ts`): first-seen tag ordering, key de-duplication (a repeated key
- * gains its method/action as a suffix), and the shared route template — so
- * URL shape and slug rules can never drift between the two spec kinds.
+ * `asyncapi.ts`): declared-then-first-seen tag ordering, key de-duplication
+ * (a repeated key gains its method/action as a suffix), and the shared route
+ * template — so URL shape and slug rules can never drift between the two spec
+ * kinds.
  */
 export declare const operationCollector: (baseRoute: string, tagMeta: ReadonlyMap<string, string>) => OperationCollector;
 /**
  * Flatten a 3.1 document into a route-mapped operation list and its ordered
  * tags. Operations inherit the first tag they declare; keys are de-duplicated so
  * a repeated `operationId` still yields distinct routes. `warnings` reports
- * anything skipped (a `$ref` path item), so missing operations aren't silent.
+ * anything skipped (a `$ref` path item, webhooks), so missing operations
+ * aren't silent.
  */
 export declare const extractOperations: (document: ApiDocument, baseRoute: string) => ExtractedOperations;
 /** Resolve the operation object for a ref out of its (OpenAPI) document. */

package/dist/types/search/sync/algolia.d.ts

@@ -9,6 +9,8 @@ export type AlgoliaSyncConfig = Pick<AlgoliaOptions, "appId" | "indexName">;
  *
  * Uses `replaceAllObjects`, which atomically replaces the index contents, so
  * pages deleted or renamed since the last sync don't linger as stale search
- * hits that 404 when clicked.
+ * hits that 404 when clicked. Then adds `filterOnly(locale)` and
+ * `filterOnly(version)` to the index's `attributesForFaceting`, keeping any
+ * the site declared itself, so the dialog's locale and version filters match.
  */
 export declare const syncAlgolia: (records: SearchRecord[], config: AlgoliaSyncConfig) => Promise<void>;

package/docs/01-quickstart.mdx

@@ -23,11 +23,12 @@ Go from an empty folder to a running docs site in a few commands. Blume needs **
     npx blume init
     ```
 
-    On pnpm 12, add `--allow-build=esbuild` after `pnpm dlx` (`pnpm dlx --allow-build=esbuild blume init`): pnpm 12 refuses to run the install script of esbuild, which Astro depends on, unless you approve it. Inside an existing pnpm workspace, add `allowBuilds: { esbuild: true }` to the workspace's `pnpm-workspace.yaml`; `init` reminds you. With Yarn 2 or later, `init` writes a `.yarnrc.yml` that switches Yarn to a `node_modules` install, which Blume needs; on Yarn 1, run `npx blume init`.
+    On pnpm 12, add `--allow-build=esbuild` after `pnpm dlx` (`pnpm dlx --allow-build=esbuild blume init`): pnpm 12 refuses to run the install script of esbuild, which Astro depends on, unless you approve it. Inside an existing pnpm workspace, the new folder must be listed under the workspace's `packages` (pnpm installs nothing else, so `init` skips the install until it is), and esbuild needs `allowBuilds: { esbuild: true }` in the workspace's `pnpm-workspace.yaml`; `init` reminds you of both. With Yarn 2 or later, `init` writes a `.yarnrc.yml` that switches Yarn to a `node_modules` install, which Blume needs; on Yarn 1, run `npx blume init`.
 
     ```txt
     docs/
       index.mdx
+    .gitignore
     blume.config.ts
     package.json
     ```
@@ -52,7 +53,7 @@ Go from an empty folder to a running docs site in a few commands. Blume needs **
   </Step>
 </Steps>
 
-Adding Blume to a project that already has a `package.json`? `blume init` leaves existing files alone, so add `"dev": "blume dev"` and `"build": "blume build"` to its scripts, or run `npx blume dev` directly.
+Adding Blume to a project that already has a `package.json`? `blume init` leaves existing files alone and skips the install, so install Blume yourself (`npm install blume`), then add `"dev": "blume dev"` and `"build": "blume build"` to its scripts, or run `npx blume dev` directly. The next steps `init` prints include both commands for your package manager.
 
 :::tip
 Blume works with any package manager and never requires you to set up Astro or Tailwind yourself.