blume 1.0.3 → 1.1.0

package/CHANGELOG.md

@@ -1,5 +1,99 @@
 # blume
 
+## 1.1.0
+
+### Minor Changes
+
+- 9fec53f: Add `blume audit`, an offline site audit that replaces a hosted SEO crawler.
+
+  `blume audit` reads the built `dist/` HTML, joins each page back to the `.mdx` it came from, and reports SEO and site-health issues that name **both** the URL that is wrong and the front matter line that fixes it:
+
+  ```
+  ⚠ Meta description too long or too short   5 pages
+      /docs/configuration/export    content/docs/configuration/export.mdx:3
+      fix: Rewrite `description` in the frontmatter to fit the length range.
+  ```
+
+  It runs 87 checks across content, duplicates, indexability, links, redirects, social tags, localization, assets, sitemap, robots.txt, structured data, and AI discovery. Findings are rolled up by check rather than dumped per page, and any tier that didn't run says so. The check set deliberately skips things that can't happen to an Astro-built site (missing hashed bundles, `rel=nofollow`) in favor of checks a crawler can't do — broken `#fragment` anchors, `draft: true` pages that shipped, `llms.txt` held to the sitemap's standard, and Open Graph images verified as bytes.
+
+  Flags:
+
+  - `--url <origin>` also probes a live deployment for what `dist/` can't show (bad rewrites, missing compression, `X-Robots-Tag` deindexing).
+  - `--external` probes outbound links.
+  - `--claude` / `--codex` write the JSON report and open the agent interactively to fix each finding at its source.
+  - `--fail-on <severity>` (default `error`) as the CI gate, plus `--only`/`--skip`, `--json`, `--verbose`, and `--list-checks`.
+
+  `blume validate` is unchanged — it remains the fast source-level link check that needs no build.
+
+### Patch Changes
+
+- 3aee378: Strip trailing slashes from the deploy adapter root with a linear scan instead of a `/\/+$/` regex. The old pattern could backtrack polynomially on a root path containing long runs of `/` (CodeQL `js/polynomial-redos`); the new trim is O(n) and yields the same single-trailing-slash directory URL.
+- f779fd5: Make `blume audit --claude`/`--codex` work on Windows: npm installs the agent CLIs as `.cmd` shims that Node only runs through a shell, and cmd.exe can't carry the multi-line prompt as an argument — the handoff now writes the prompt to a file and launches the shim with a one-line pointer, and a missing executable still gets the install hint instead of a raw ENOENT
+- d99726a: Account for `deployment.base` throughout the audit: link, sitemap, hreflang, llms.txt, asset, and og:image checks now strip the deployment base from emitted URLs before comparing them to the built file tree, instead of reporting every internal link and sitemap entry as broken on subpath deploys
+- d99726a: Make the audit's double-slash check able to fire on the case it was written for: an href like `//docs/x` from a trailing-slash base is now flagged (once per target) instead of being silently skipped as a protocol-relative external link
+- d99726a: Replace a raw NUL byte in the audit's duplicate-content grouping key with the `\u0000` escape, so the shipped source is valid text (git diffed it as binary and grep skipped it)
+- d99726a: Exempt the home page from the audit's orphan-page check when it lives under a `basePath` — `/docs` was reported as an orphan even though `/` never is
+- d99726a: Stop reporting a redirect to a served static file (`/old-whitepaper` → `/files/whitepaper.pdf`) as broken — the audit now resolves redirects against files as well as pages
+- d99726a: Keep a gap between the URL and source-file columns in the audit report when a URL reaches the column width, instead of fusing them into one string
+- d99726a: Fix two robots.txt matching gaps in the audit: `Disallow: /docs*$` now matches everything under `/docs` (the trailing wildcard absorbs the anchor), and trailing-slash rules like `Disallow: /page/` are matched against the sitemap `<loc>` as served instead of a slash-stripped copy
+- d99726a: Only report `ROBOTS_META_UNEXPECTED` when the robots meta actually blocks indexing — a page declaring `index, follow` is no longer claimed to "not be indexed"
+- 8d7e779: Format the changelog timeline's dates in the configured locale. The timeline hardcoded `en`, so an i18n site showed two languages at once: a page's "last updated" stamp honored the locale while `/changelog` stayed English. `/changelog` is an unlocalized route whose chrome already renders in the default locale, so its dates now follow that same locale. English sites are unaffected.
+- d518958: Add `inline` and `param` props to the `Tabs` component. `inline` renders borderless — a tab strip on a full-width rule with the content flowing beneath as prose — instead of the bordered box. `param` syncs the active tab to a URL query param instead of the hash; because each group owns its own `param`, several `Tabs` can share a page and every selection is deep-linkable (a link ending in `?install=windows` opens on that tab). Existing boxed, hash-synced `Tabs` and `CodeGroup` are unchanged.
+- d9dfdba: Stop shipping underscore-prefixed `.astro` files in `pages/` as routes. Blume injects user pages itself and globbed every `.astro` file, so private partials — shared layouts and home-page sections like `pages/_home/Hero.astro` or `pages/_FeatureBrowser.astro` — were each built into their own HTML page. Page discovery now honors Astro's convention: any file or folder whose name starts with `_` stays importable but is never routed.
+- 437ce03: Fix `blume dev` under pnpm's default isolated linker. The generated runtime now checks Astro through the same physical `node_modules` ancestor lookup used by its ESM config, instead of mistaking pnpm's CommonJS-only `NODE_PATH` exposure for a resolvable `astro/config` import.
+- 9aad3e6: Add `frontmatter.extend`: opt-in custom frontmatter keys, each validated by a user-supplied schema. Page frontmatter stays strictly validated by default; a project can now declare extra keys (e.g. `owner`, `reviewedAt`) in `blume.config.ts`, mapped to schemas consumed through the Standard Schema interface — so Zod (any version the project installs), Valibot, and ArkType all work. Declared keys are validated on every page (mark them `.optional()` to relax), validated values are preserved on each page record's `custom` field, and every other key keeps the strict typo-catching behavior.
+- 368b258: Emit a `_headers` file for static builds so hosts serve the raw AI-ready endpoints with an explicit `charset=utf-8`. Blume's `/<route>.md`, `/<route>.mdx`, and `.txt` outputs (`llms.txt`, `llms-full.txt`) are valid UTF-8, but common static hosts serve them as `text/markdown` / `text/plain` with no charset — so browsers fall back to Windows-1252 and non-ASCII docs (Japanese, accented Latin, …) render as mojibake when the raw URL is opened directly. The new `_headers` pins the same `charset=utf-8` Content-Type the dev/server runtime already sends; Netlify and Cloudflare (Pages/Workers static assets) honor it, and hosts that ignore `_headers` (Vercel, S3) are unaffected. The globs carry any `deployment.base`/`basePath` stack, and a `_headers` you ship in `public/` is left untouched — exactly like `_redirects`.
+- d99726a: Prefix the `_headers` `.txt` charset rule with only `deployment.base` — `llms.txt`/`llms-full.txt` are served at the deploy root, so a `basePath` deployment shipped a `/docs/*.txt` rule that matched nothing and left the mojibake fix inert
+- a4453e4: Upgrade Takumi to v2 via takumi-js. Emoji in titles now render as Twemoji glyphs, fetched once per glyph per build. The OG card palette accepts any CSS color, matching `theme.accent` — a color the renderer can't parse now fails the build instead of silently falling back. `renderOgImage` (exported from `blume/og`) now returns a `Uint8Array` rather than a `Buffer`.
+- 548bdd7: Link the RSS feeds from `llms.txt`. The generated index mirrored the docs navigation but never referenced the per-content-type feeds (e.g. `/blog/rss.xml`), so an agent reading `llms.txt` had no pointer to fresh blog posts or changelog entries. The index now closes with an `## RSS Feeds` section listing each configured feed that has pages, under the same condition the feeds themselves exist — RSS enabled and an absolute `deployment.site` — and carrying any `deployment.base` subpath. This mirrors the `artifacts.feeds` list already emitted in `agent-readability.json`.
+- d99726a: Fix a data-loss bug in the blume-migrate Mintlify codemod: renaming a key into a parent block that appears earlier in the frontmatter (e.g. `canonical` into an existing `seo:`) deleted the wrong line and left the source key behind; icon remaps also now preserve trailing comments, and the skill references no longer document the pre-1.0.3 top-level `mcp` config
+- 8769dd1: Add `seo.og.fonts` to load Google Font families into the Open Graph card renderer. Takumi's built-in font covers only Latin, so a non-Latin page or site title (CJK, and so on) rendered as tofu with no way to fix it. List the families by name — bare strings, or `{ name, weight, style }` for weight/style — and Blume fetches them from Google Fonts at build via Takumi's `googleFonts` helper, registering only the glyph subsets each title uses. Latin text renders unchanged.
+- d99726a: Add `seo.og.fonts` to the `OgConfig` authoring type — the schema accepted it but TypeScript rejected it in `blume.config.ts`, making the documented CJK/tofu fix untypeable — and correct the palette doc comment to say any CSS color works, not just hex
+- de6403c: Fix the OG image build failing with "Cannot find native binding" on Vercel (Linux). The `googleFonts` OG-font loader is imported from `takumi-js/helpers`, but only the bare `takumi-js` was externalized for the static-prerender Vite environment — which matches by exact specifier, so the subpath (and the native `@takumi-rs/core` backend it pulls in) got bundled into the prerender chunk, relocating the `.node` binding lookup. Externalize `takumi-js/helpers` and the `@takumi-rs/*` packages so the native backend always resolves from `node_modules` at runtime.
+- bb9737e: Render authentication requirements in the native OpenAPI reference. Operations that declare security requirements — their own `security`, or the document's root default — now show an **Authorization** section above their parameters: the credential's carrier (`Authorization` header, API-key header/query/cookie), a human label per scheme type (Bearer token, Basic auth, API key, OAuth2, OpenID Connect, Mutual TLS), the scheme's description, and OAuth scopes. Multiple requirement alternatives render as "or" groups (schemes within one requirement are required together), an empty `{}` requirement marks auth as optional, and `security: []` on an operation keeps it public with no section. The generated code samples now send a matching placeholder credential (e.g. `-H "Authorization: Bearer YOUR_TOKEN"`), with a spec-declared explicit header parameter still taking precedence, and a query-borne API key appended to the sample URL. Previously the renderer ignored `security` entirely, so authenticated endpoints were indistinguishable from public ones.
+- d99726a: Align the accessible heading level of the Authorization and Parameters sections with Request body and Responses on API reference operation pages
+- d99726a: Stop duplicating a query API key in request samples when the spec also declares the credential as an explicit query parameter — the parameter's own example now wins, matching the header behavior
+- e6be2f6: Match unordered-list bullets to ordered-list numbers in prose. `--tw-prose-bullets` now defaults to `--blume-muted-foreground` (like `--tw-prose-counters`) instead of `--blume-border`, which rendered bullets much lighter than the numbers beside them.
+- d99726a: Normalize `deployment.base` before composing it into redirect targets — a trailing-slash (`/base/`) or bare (`base`) value produced `/base//new` or relative destinations in Astro redirects and the platform redirect files
+- 93ea41b: Fix redirects escaping the site under `deployment.base`. A redirect's `to` was only ever rewritten with `basePath`, never with the deployment base, so with `base: "/docs"` a `to: "/new"` emitted a redirect to `/new` — outside the base, 404ing on a subpath deploy (GitHub Pages project sites, most commonly) with no build-time error. Astro applies `base` when it builds the match pattern for `from`, but resolves a destination either by regenerating it from a matching route's segments (which carry no base) or by passing it through verbatim — neither prepends `base`, so Blume now applies it to `to` itself. The two bases also compose correctly: `deployment.base` and `basePath` set together stack as `{base}/{basePath}`, which the old front-prepend could not produce in that order.
+
+  The static host redirect files (`_redirects`, `vercel.json`, `blume-redirects.json`) had the mirror-image bug on the other side: they are matched against the real served URL, but `from` was written without the deployment base, so it never matched. Both sides now carry the full stack. Redirects are authored root-relative in every case, and a base already written into `to` by hand is preserved rather than doubled.
+
+- d99726a: Warn when a `search.popular` link uses an image or inline-SVG icon — the client search island can only render built-in icon names, and the silent fallback to the file glyph was exactly what the validator was meant to catch
+- 1c18379: Add `search.popular` to curate the Cmd+K empty-state link list. When set, each `{ href, label, icon? }` entry replaces the default first-six sidebar pages — useful on multi-tab sites where sidebar order surfaces the wrong section. Each `href` is authored root-relative and picks up `basePath` automatically (external URLs pass through); `icon` takes a built-in icon name and defaults to a file glyph. Omit or leave empty to keep the sidebar fallback.
+- ea4c560: Stop headings inside a `<Prompt>` block from leaking into the page's table of contents. `Prompt.astro` renders its children into a permanently `hidden` node (used only to build the copy-to-clipboard and Cursor-deeplink text), but `extractHeadings` had no way to know that — any `##` inside a `<Prompt>` was extracted as a real page heading and appeared in the "On this page" sidebar, linking to content that never renders visibly. Heading extraction now tracks `<Prompt>`/`</Prompt>` nesting depth the same way fenced code blocks already are, and skips headings while inside one. Tag detection is anchored to line starts — block-level JSX in MDX starts its own line — so a prose or heading mention of `<Prompt>` never opens a hidden region, and a tag whose attributes span several lines only counts once its closing `>` shows it isn't self-closing.
+- c6ca54a: Add a themeable content-column width. A new `--blume-content-width` token (default `42rem`) is exposed as a `max-w-content` utility through Tailwind's `--container-content` theme key, and the article, breadcrumb, mobile table of contents, page feedback, pagination, and last-updated line now use it instead of hardcoding `42rem`. Override `--blume-content-width` to re-measure the whole column at once; the default is unchanged.
+- 31ee259: Bundle the Vercel serverless function with its chunks, virtual middleware, and dependencies. With `deployment.output: "server"` and `adapter: "vercel"`, the render function (`.vercel/output/functions/_render.func`) shipped as `entry.mjs` alone, so any server-rendered request — the Docs MCP endpoint, Ask AI — 500'd at runtime with `ERR_MODULE_NOT_FOUND`. The adapter resolves both its Build Output tree and its `@vercel/nft` dependency trace against Astro's `root`, which Blume points at the hidden `.blume` runtime; the trace's base then excluded the server bundle (which lives under `outDir`, outside `.blume`) and collapsed to a single file. The adapter is now shown the real project root, so the trace covers the function's chunks and `node_modules` and the output lands at the project root natively. Projects inside a workspace were unaffected — nft's base search climbed past `.blume` to the workspace root — so this only ever broke standalone projects.
+
+## 1.0.4
+
+### Patch Changes
+
+- cf8fa22: Fix the spacing inside directive callouts (`:::note`, `:::success`, …). The global prose paragraph rule leaks a 1rem margin onto the callout's paragraphs even though the callout is `not-prose`, and with a title the body paragraph isn't the first child — so that margin stacked under the title's own gap and left a too-large space between the title and the body. The Callout now overrides that margin locally for a uniform, compact gap between the title, paragraphs, and lists. Callouts without a title and normal prose spacing are unchanged.
+- bb5944d: Gate the language icon on `data-language` so it no longer overlaps the first code line on header-less standalone `<CodeBlock>`s. The icon transformer runs whenever icons are on, but a standalone block without a `title` never gets `data-language` (the header bar that reserves the icon's space), so the absolutely-positioned icon sat on top of the first line. Fenced code and titled blocks are unaffected.
+- d59be0a: API references (OpenAPI, AsyncAPI) no longer add a header tab automatically. Point a `navigation.tabs` entry at the reference route to surface it — this also lets you control the tab label and scopes the operations sidebar for the native renderer.
+- f02b94e: Introduce the `blume-migrate` agent skill. It teaches an AI agent to migrate an existing docs site — Mintlify, Docusaurus, Fumadocs, Nextra, Starlight, or any docs framework — into an idiomatic Blume project: translating the source config to `blume.config.ts`, restructuring content into filesystem-derived navigation (with `redirects` for every moved route), rewriting callouts to `:::` directives, converting icons to Lucide, inlining snippets, and pointing generated API references at `openapi.sources` instead of porting endpoint stubs. Ships with per-framework mapping references, a deterministic Mintlify codemod for the icon/frontmatter pass, and monorepo/Vercel integration recipes. The skill is bundled in the package under `skills/`.
+- a421a1e: Make the generated runtime type-check cleanly under `blume check --strict --isolated` (and any project whose `tsconfig` includes the generated files). Previously a valid site could fail with dozens of errors in the generated `.blume-verify` files:
+
+  - The raw-Markdown, RSS, and OG endpoints imported `data.json` directly, so TypeScript widened the JSON (navigation `kind` to `string`, empty arrays to `never[]`, theme mode to `string`) and rejected it against Blume's own types. They now import the typed `blume:data` virtual module.
+  - Endpoint handlers (`GET`, `getStaticPaths` callbacks) and the changelog/content-page helper functions had implicit-`any` parameters; they now carry explicit types.
+  - The OG endpoint's PNG `Buffer` is wrapped in a `Uint8Array` so it satisfies the `Response` body type, and the empty component-overrides module and the `blume:examples`/`blume:examples-theme` virtual modules now declare types.
+
+  Also stops `blume check --isolated` from reloading a running `blume dev` server: `.blume-verify` is now in Blume's ignored-directory set, so generating the isolated runtime no longer trips the content watcher.
+
+- 6a97cb2: Reserve space for local per-mode SVG logos before they load.
+- 5793ccf: Render Mermaid diagrams in `blume dev`. Mermaid statically imports dayjs as CommonJS (`dayjs/dayjs.min.js`), and in dev Vite served that dependency un-pre-bundled, so it exposed no `default` export and mermaid threw `does not provide an export named 'default'` — leaving diagrams blank (the production build already handled the interop). Mermaid now goes through Vite's dependency optimizer, which bundles dayjs with correct CommonJS interop. Because Blume's `import("mermaid")` lives inside `node_modules/blume` — a path Vite's optimizer scan doesn't crawl in a standalone install — the diagram library was never discovered on its own, so it's included explicitly via the nested `blume > mermaid` form (mermaid isn't a direct dependency of the generated project).
+- 5c0b0f0: Add custom logo and palette settings for generated Open Graph cards.
+- 1bdc849: Truncate long page titles in the previous/next pagination links so they no longer overflow their pill container, and allow inline code inside table cells to wrap instead of forcing the whole table to overflow horizontally.
+- f2ffcb5: Prerender Cloudflare adapter builds in Node so build-time `node:` imports resolve. Astro 6 changed the `@astrojs/cloudflare` default prerender runtime from Node to workerd, which broke Blume prerender on Cloudflare (`No such module "node:path"` and `node:fs` usage in Blume's build-time content tooling). The generated `astro.config.mjs` now passes `prerenderEnvironment: "node"` to the Cloudflare adapter. On-demand pages still run in workerd at request time.
+- d11a90c: Stop the `Prompt` component's copy button from shifting the layout. On copy, the button's label swapped "Copy prompt" → "Copied", and because the button was sized to its text, it shrank — giving the description beside it more room and reflowing it (a two-line description would collapse to one line, then jump back). Both labels now share a single grid cell, so the button is always sized to the wider "Copy prompt" and never resizes when the state changes.
+- fcdc3b3: Match native browser controls, including scrollbars, to the active color theme.
+- 3795fbb: Keep root navigation tabs active on descendant routes unless a more specific tab matches.
+- e5aa042: Use the `rounded-blume` radius token instead of a hardcoded `rounded-full` on the `PageFeedback` and `Pagination` buttons so they respect the configured `theme.radius`.
+- 32e29f0: Keep the text caret inside the search input on mobile. The search dialog was vertically centered, so when the on-screen keyboard opened and the viewport shrank, the dialog re-centered and the input moved up while the native caret stayed put — stranding the cursor below the input, over the results. The dialog is now top-anchored on small screens (like DocSearch/cmdk) so the input sits above where the keyboard appears and doesn't move, and its height is capped to the dynamic viewport so it fits above the keyboard. Desktop keeps its centered layout.
+- 7806565: Resolve a section tab's link to its first page when the section has no index page, so the tab no longer 404s. A tab's `path` still scopes its sidebar section and matches the active tab, but the clickable target now falls back to the first page in the section (sidebar order) when nothing lives at the path itself — e.g. `/examples` with only `/examples/hello-world` links to that page instead of a missing `/examples`.
+- fe21c54: Wrap markdown tables in a horizontal-scroll container so wide tables no longer overflow the prose column. The wrapper is framed with a rounded border and cell padding, and header labels stay on one line, so a clipped wide table reads as scrollable rather than cut off.
+
 ## 1.0.3
 
 ### Patch Changes