blume 1.6.5 → 1.6.6

package/dist/types/ai/ask-context.d.ts

@@ -55,6 +55,31 @@ export interface AskRetrievalOptions {
  * Exported for testing; {@link createAskContext} is the runtime entry point.
  */
 export declare const relevantExcerpt: (content: string, query: string, max: number) => string;
+interface PageSection {
+    /** Word tokens of the section's heading line, or none when it has no heading. */
+    headingWords: string[];
+    /** Position in the page, for source-order output and omission markers. */
+    index: number;
+    text: string;
+    /** The section's word tokens, cut once so scoring is a prefix test. */
+    words: string[];
+}
+/** A page split into sections once, so per-request scoring never re-tokenizes. */
+export interface ParsedPage {
+    sections: PageSection[];
+    /** NFC-normalized, LF-only, trimmed page text; excerpts slice from it. */
+    text: string;
+}
+/**
+ * Split a page at its `##`+ headings (outside code fences). The text above the
+ * first heading is the page's own lead-in and is a section like any other.
+ * Line endings are folded to LF first so a CRLF checkout splits and matches the
+ * same way as an LF one. Exported for testing; {@link createAskContext}
+ * parses each page once and caches it across requests.
+ */
+export declare const parsePage: (content: string) => ParsedPage;
+/** {@link excerptPage} over a page parsed on the spot. Exported for testing. */
+export declare const sectionExcerpt: (content: string, query: string, max: number) => string;
 /**
  * Build the request-time grounding function for the Ask AI endpoint.
  *
@@ -76,3 +101,4 @@ export declare const createAskContext: (data: AskData, options?: {
     instructions?: string;
     retrieval?: AskRetrievalOptions;
 }) => ((messages: AskMessage[], page?: AskPage) => Promise<string | undefined>);
+export {};

package/dist/types/core/code-fences.d.ts

@@ -0,0 +1,11 @@
+/** The open fence's delimiter char and run length, or null outside one. */
+export type FenceState = {
+    delimiter: "`" | "~";
+    length: number;
+} | null;
+/**
+ * Advance the fenced-code state for one line: an opening fence records its
+ * delimiter and run length, only a bare run of the same character at least as
+ * long closes it (CommonMark), and any other line leaves the state untouched.
+ */
+export declare const nextFenceState: (line: string, fence: FenceState) => FenceState;

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

@@ -11,7 +11,7 @@ export declare const findPackageRoot: (start: string) => string;
  * Anchoring here — rather than at a fixed offset from `import.meta` — keeps the
  * package's own `src/`, assets, and `node_modules` locatable whether the code
  * runs from source under Bun (`src/...`) or from the published, bundled CLI
- * (`dist/cli/index.js`). The two layouts sit at different depths, so a relative
+ * (`dist/cli/*.js`). The two layouts sit at different depths, so a relative
  * `../..` resolves to different places; locating `package.json` does not.
  */
 export declare const packageRoot: () => string;

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

@@ -146,6 +146,76 @@ export declare const pageMetaSchema: z.ZodObject<{
 }, z.core.$strict>;
 export type PageMeta = z.infer<typeof pageMetaBaseSchema>;
 export type PageMetaInput = z.input<typeof pageMetaBaseSchema>;
+/**
+ * The page schema as the generated content collections declare it, so
+ * `entry.data` is typed and normalized (dates as ISO strings, X handles with
+ * their `@`) the same way the scan's `PageMeta` is. Two deliberate loosenings
+ * over {@link pageMetaSchema}: custom keys (`frontmatter.extend`, per-type
+ * maps) pass through instead of failing the strict parse, and a page the
+ * strict parse rejects resolves to the empty defaults instead of throwing.
+ * The scan has already dropped such a page with a `BLUME_FRONTMATTER_INVALID`
+ * 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<{
+    ai: z.ZodPrefault<z.ZodObject<{
+        exclude: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strict>>;
+    authors: z.ZodOptional<z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+        avatar: z.ZodOptional<z.ZodString>;
+        image: z.ZodOptional<z.ZodString>;
+        name: z.ZodString;
+        url: z.ZodOptional<z.ZodString>;
+    }, z.core.$catchall<z.ZodUnknown>>]>, z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+        avatar: z.ZodOptional<z.ZodString>;
+        image: z.ZodOptional<z.ZodString>;
+        name: z.ZodString;
+        url: z.ZodOptional<z.ZodString>;
+    }, z.core.$catchall<z.ZodUnknown>>]>>]>>;
+    changelog: z.ZodOptional<z.ZodObject<{
+        category: z.ZodOptional<z.ZodString>;
+        date: z.ZodOptional<z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodDate]>, z.ZodTransform<string, string | Date>>>;
+        version: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    date: z.ZodOptional<z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodDate]>, z.ZodTransform<string, string | Date>>>;
+    deprecated: z.ZodDefault<z.ZodBoolean>;
+    description: z.ZodOptional<z.ZodString>;
+    draft: z.ZodDefault<z.ZodBoolean>;
+    hidden: z.ZodDefault<z.ZodBoolean>;
+    icon: z.ZodOptional<z.ZodString>;
+    lastModified: z.ZodOptional<z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodDate]>, z.ZodTransform<string, string | Date>>>;
+    noindex: z.ZodDefault<z.ZodBoolean>;
+    search: z.ZodPrefault<z.ZodObject<{
+        boost: z.ZodOptional<z.ZodNumber>;
+        exclude: z.ZodDefault<z.ZodBoolean>;
+        tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
+    seo: z.ZodPrefault<z.ZodObject<{
+        canonical: z.ZodOptional<z.ZodURL>;
+        description: z.ZodOptional<z.ZodString>;
+        image: z.ZodOptional<z.ZodString>;
+        noindex: z.ZodDefault<z.ZodBoolean>;
+        title: z.ZodOptional<z.ZodString>;
+        x: z.ZodOptional<z.ZodObject<{
+            creator: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<string | undefined, string>>>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    sidebar: z.ZodPrefault<z.ZodObject<{
+        badge: z.ZodOptional<z.ZodString>;
+        display: z.ZodOptional<z.ZodEnum<{
+            flat: "flat";
+            group: "group";
+            page: "page";
+        }>>;
+        hidden: z.ZodDefault<z.ZodBoolean>;
+        icon: z.ZodOptional<z.ZodString>;
+        label: z.ZodOptional<z.ZodString>;
+        order: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+    slug: z.ZodOptional<z.ZodString>;
+    title: z.ZodOptional<z.ZodString>;
+    type: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>>;
 export declare const folderMetaSchema: z.ZodObject<{
     collapsed: z.ZodOptional<z.ZodBoolean>;
     display: z.ZodOptional<z.ZodEnum<{

package/docs/02-deployment.mdx

@@ -101,7 +101,7 @@ On **Vercel**, **Netlify**, and **Cloudflare Pages**, Blume picks the matching a
 
 A server build includes everything a static build does, plus any Astro endpoints or middleware you add. The `node` adapter produces a standalone server you can run directly.
 
-On Vercel and Cloudflare, a server build also turns on [`Accept: text/markdown` content negotiation](/docs/discoverability/markdown#content-negotiation), so an agent requesting any content page with that header receives its raw-Markdown mirror at the same URL. On Vercel, Blume splices header-conditional rewrites into the deploy's routing config; on Cloudflare, it generates a small Worker in front of the Astro one and scopes `assets.run_worker_first` to the content routes, since the platform would otherwise serve the prerendered pages before any server code runs — other assets keep their zero-Worker fast path.
+On Vercel and Cloudflare, a server build also turns on [`Accept: text/markdown` content negotiation](/docs/discoverability/markdown#content-negotiation), so an agent requesting any content page with that header receives its raw-Markdown mirror at the same URL. On Vercel, Blume splices header-conditional rewrites into the deploy's routing config; on Cloudflare, it generates a small Worker in front of the Astro one and scopes `assets.run_worker_first` to the content routes, since the platform would otherwise serve the prerendered pages before any server code runs — other assets keep their zero-Worker fast path. That Worker also answers the prerendered per-page JSON documents (`/api/docs/pages/{route}.json`) from the asset binding when a request for one reaches it, because Astro would otherwise route it to the `/api/` catch-all.
 
 :::note
 Server features have their own configuration — for example, Ask AI needs a model API key. See the [Ask AI guide](/docs/configuration/ask-ai) for setup.

package/docs/configuration/ask-ai.mdx

@@ -170,7 +170,7 @@ Set `apiKeyEnv` (and, for the named providers, `baseUrl`) on any backend to poin
 **Inkeep** answers from the content you've indexed in the Inkeep dashboard — it runs its own retrieval — so Blume leaves it ungrounded. Every other backend is [grounded](#grounding) in this site's pages.
 :::
 
-Keys are read with `process.env`, which covers the Node, Vercel, and Netlify adapters. On Cloudflare, expose the key through the platform's [runtime binding](https://docs.astro.build/en/guides/integrations-guide/cloudflare/#environment-variables-and-secrets). Enabling Ask AI also turns on React for the in-page island — see [Customization](/docs/configuration/customization#interactive-islands).
+Keys are read through Astro's [`getSecret()`](https://docs.astro.build/en/guides/environment-variables/#retrieving-secrets-programmatically), so each adapter supplies them its own way: environment variables on Node, Vercel, and Netlify, and the Worker's [bindings](https://docs.astro.build/en/guides/integrations-guide/cloudflare/#environment-variables-and-secrets) on Cloudflare. Enabling Ask AI also turns on React for the in-page island — see [Customization](/docs/configuration/customization#interactive-islands).
 
 ## Rate limiting
 

package/docs/configuration/customization.mdx

@@ -182,13 +182,6 @@ blume eject --yes
 
 Eject is a one-way step: the hidden `.blume/` runtime becomes a normal Astro app you own and can modify directly. The `blume` package stays importable, so you keep its components, theme, and Markdown processors.
 
-### What eject leaves behind
+### What eject keeps
 
-After ejecting, your `build` script runs plain `astro build` — the site itself builds the same, but the artifacts `blume build` layered on top are no longer produced. The eject command warns about the ones your config actually uses. To keep them:
-
-- **Pagefind search index** — with `search.provider: "pagefind"`, the search UI loads the index from the built site, so search breaks in production until you index it yourself. Install `pagefind` as a devDependency and index after each build: `"build": "astro build && pagefind --site dist"`.
-- **Hosted search sync** — a hosted provider's index is no longer pushed on build; re-upload your search records after each build with the provider's API or CLI.
-- **sitemap.xml** — recreate it with the standard [@astrojs/sitemap](https://docs.astro.build/en/guides/integrations-guide/sitemap/) integration.
-- **robots.txt** — ship your own as `public/robots.txt`.
-- **llms.txt / llms-full.txt and agent-readability.json** — write them by hand (or generate them in a build step of your own) and serve them from `public/`.
-- **Platform redirect files** — `_redirects` and `vercel.json` are no longer emitted for static builds. Your redirects still work as Astro-generated meta-refresh pages, or you can move them into your host's own config.
+The ejected app's `build` script runs plain `astro build`, and the artifacts `blume build` layers on top — the search index (and a hosted provider's index sync), `llms.txt` and `llms-full.txt`, `sitemap.xml`, `robots.txt`, `agent-readability.json`, the `.well-known` discovery files, Agent Skills, and the platform `_redirects`/`_headers` files — are still produced: the Blume integration in the ejected `astro.config.mjs` writes them from Astro's `astro:build:done` hook, scanning the project (your `blume.config.ts` and content) the way the CLI did. What the ejected build does not do is the CLI's adapter post-processing: the Vercel and Cloudflare `Accept: text/markdown` routing splices, the Vercel function-bundle audit, and the `--analyze`/`--budget-*` gate.

package/docs/reference/cli.mdx

@@ -111,7 +111,7 @@ Add a `tsconfig.json` extending Astro's config to your project root so authored
 ```json title="tsconfig.json"
 {
   "extends": "astro/tsconfigs/strict",
-  "include": [".blume/.astro/types.d.ts", ".blume/src/env.d.ts", "**/*"]
+  "include": [".blume/.astro/types.d.ts", "**/*"]
 }
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "blume",
-  "version": "1.6.5",
+  "version": "1.6.6",
   "description": "Documentation that's fast, AI-ready, and zero-config.",
   "keywords": [
     "astro",
@@ -59,6 +59,7 @@
   },
   "scripts": {
     "build": "bun run scripts/build.ts",
+    "bench": "bun bench/run.ts",
     "bundle-docs": "node scripts/bundle-docs.mjs",
     "prepack": "bun run scripts/build.ts && node scripts/bundle-docs.mjs",
     "test": "bun test",
@@ -99,12 +100,12 @@
     "dompurify": "^3.4.15",
     "dotenv": "^17.4.2",
     "epub-gen-memory": "^1.1.2",
+    "es-module-lexer": "^3.0.2",
     "fast-xml-parser": "^5.11.1",
     "github-slugger": "^2.0.0",
     "graphql": "^17.0.2",
     "gray-matter": "^4.0.3",
     "html-escaper": "^3.0.3",
-    "image-size": "^2.0.2",
     "jiti": "^2.7.0",
     "js-yaml": "^5.4.1",
     "katex": "^0.18.7",
@@ -166,6 +167,7 @@
     "algoliasearch": "^5.59.0",
     "bun-types": "^1.4.2",
     "flexsearch": "^0.8.212",
+    "mitata": "1.0.34",
     "typesense": "^3.0.6"
   },
   "peerDependencies": {

package/src/ai/api/handlers.ts

@@ -11,10 +11,11 @@ import {
 } from "../mcp/query.ts";
 import type { SearchHitPayload } from "../mcp/query.ts";
 import {
-  API_BASE,
   API_PAGES_PATH,
   API_SEARCH_PATH,
   OPENAPI_PATH,
+  pageJsonPath,
+  pageParam,
 } from "./paths.ts";
 import { problemResponse } from "./problem.ts";
 
@@ -85,10 +86,6 @@ export const jsonResponse = (payload: ApiPayload, status = 200): Response =>
     status,
   });
 
-/** The `pages/{route}.json` path segment for a route (`index` for home). */
-export const pageParam = (route: string): string =>
-  route === "/" ? "index" : route.slice(1);
-
 /** The absolute (or root-relative) URL for a base-less path. */
 const siteUrl = (path: string, context: ApiSiteContext): string => {
   const based = withBasePath(context.base, path);
@@ -98,7 +95,7 @@ const siteUrl = (path: string, context: ApiSiteContext): string => {
 const summarize = (route: McpRoute, data: McpData): ApiPageSummary => {
   const summary: ApiPageSummary = {
     contentType: route.contentType,
-    json: siteUrl(`${API_BASE}/pages/${pageParam(route.route)}.json`, data),
+    json: siteUrl(pageJsonPath(route.route), data),
     lastModified: route.lastModified,
     locale: route.locale,
     markdownUrl: siteUrl(`/${pageParam(route.route)}.md`, data),
@@ -163,7 +160,7 @@ export const pageResponse = (data: McpData, route: string): Response => {
     return problemResponse({
       code: "PAGE_NOT_FOUND",
       detail: `No documentation page has the route "${route}".`,
-      instance: siteUrl(`${API_BASE}/pages/${pageParam(route)}.json`, data),
+      instance: siteUrl(pageJsonPath(route), data),
       resolution: `List every page at ${siteUrl(API_PAGES_PATH, data)}, or discover the API through ${siteUrl(OPENAPI_PATH, data)}.`,
       status: 404,
       title: "Page not found",

package/src/ai/api/paths.ts

@@ -12,3 +12,11 @@ export const API_PAGES_PATH = `${API_BASE}/pages.json`;
 export const API_PAGE_PATH = `${API_BASE}/pages/{route}.json`;
 export const API_NAVIGATION_PATH = `${API_BASE}/navigation.json`;
 export const API_SEARCH_PATH = `${API_BASE}/search`;
+
+/** The `pages/{route}.json` path segment for a route (`index` for home). */
+export const pageParam = (route: string): string =>
+  route === "/" ? "index" : route.slice(1);
+
+/** The base-less served path of a route's per-page JSON document. */
+export const pageJsonPath = (route: string): string =>
+  `${API_BASE}/pages/${pageParam(route)}.json`;

package/src/ai/api/spec.ts

@@ -1,3 +1,4 @@
+import { apiNamePhrase } from "../../core/api-name.ts";
 import { withBasePath } from "../../core/base-path.ts";
 import { absoluteUrl, siteRoot } from "../../core/site-url.ts";
 import {
@@ -658,7 +659,7 @@ export const buildApiSpec = (input: ApiSpecInput): ApiSpecDocument => {
       `Read-only JSON API over the ${input.name} documentation${input.description ? `: ${input.description}` : "."}`,
       "Every operation is public and needs no authentication. Errors are RFC 9457 problem details (`application/problem+json`) with a stable `code`, a `detail`, and a `resolution` hint.",
     ].join("\n\n"),
-    title: `${input.name} API`,
+    title: apiNamePhrase(input.name),
     version: input.version,
     "x-generator": `blume@${input.version}`,
   };